{ "version": "https://jsonfeed.org/version/1.1", "title": "Bobo 的學思山丘", "home_page_url": "https://bobochen.dev/", "feed_url": "https://bobochen.dev/feed.json", "description": "學習、思考、紀錄。愛分享、愛開發的軟體工程師，二寶爸的技術與生活觀察。", "language": "zh-TW", "icon": "https://bobochen.dev/icon-512.png", "favicon": "https://bobochen.dev/favicon-32x32.png", "authors": [ { "name": "Bobo Chen", "url": "https://bobochen.dev/about", "avatar": "https://bobochen.dev/apple-touch-icon.png" } ], "items": [ { "id": "https://bobochen.dev/blog/citytasker-engineer-founder-real-costs/", "url": "https://bobochen.dev/blog/citytasker-engineer-founder-real-costs/", "title": "一個工程師創辦人的真實成本清單：CityTasker 教我的 4 件事", "content_text": "工程師創業，最容易低估的從來不是技術，而是看不見的成本——燒錢的速度、沒人教你的法規、聚焦的代價，還有那個致命錯覺：寫得出來的東西，最不值錢。這是 CityTasker 用兩年燒完的錢，幫我列出的成本清單。", "content_html": "2012 到 2014 年，我和朋友做了一個叫 CityTasker 的任務媒合平台——口號是「整個城市都有我的好幫手」，你有跑腿、代買、家事這類懶得做或做不來的事，就丟上平台，找附近的人接走。我那時候是共同創辦人兼全端工程師，前端、後端、雙平台 App 一個人扛。\n\n我以為最難的是把它做出來。\n\n後來才知道，把東西做出來，是這場創業裡最簡單、也最不值錢的一件事。\n\n\n\n![CityTasker 平台當年的實際畫面](./images/citytasker-product.webp)\n\n*這就是當年我們做出來的 CityTasker。把它寫出來，其實是整件事裡最簡單的一步。*\n\n下面這份清單，是 CityTasker 用兩年和我口袋裡的錢，幫我列出來的。寫給每一個正站在懸崖邊、猶豫要不要跳下去的工程師。\n\n## 你以為錢花在伺服器，其實是花在時間\n\n工程師看成本，習慣看帳單：AWS 多少、GCP 多少、簡訊一封幾毛。這些我算得很精。\n\n但真正燒掉資金的，不是機器，是時間。是你還沒搞清楚方向的每一個月，房租照付、人照養、自己也要吃飯。我們最後收攤，不是被某一筆大開銷壓垮，而是「還沒找到正確方向之前，就先坐吃山空了」。錢有跑道（runway），方向沒跑道——你以為自己在加速，其實只是在燒油空轉。\n\n**提醒**：算 runway 的時候，把「找到對的方向」當成最大的一筆隱形支出。問自己：如果接下來六個月方向都是錯的，我撐得住嗎？撐不住，就先別跳。\n\n## 你寫得出平台，但沒人教你法律\n\nCityTasker 上線後沒多久，我們收到一個完全沒料到的麻煩：勞動局以「非法人力仲介」要開罰。\n\n我當時的反應是——蛤？我們只是做了一個媒合資訊的網站啊。但在法規眼裡，你撮合了「人」去「做事」並從中產生關係，那條線就踩到了。這是一道工程師完全沒有雷達掃到的牆。你的 code review 不會幫你 review 法律，你的測試覆蓋率也涵蓋不到主管機關。\n\n更扎心的是，把我們捅到主管機關面前的，不是哪個官員自己上網發現——是同業。我們等於動了傳統人力仲介的乳酪，有人當面嗆聲，也有人直接拿著我們的網站去檢舉。那時我才懂：你以為自己在「做一個平台」，但在既有玩家眼裡，你是個闖進別人地盤、還不懂規矩的外人。法規那條看不見的線，常常是被「不希望你存在的人」幫你用力劃出來的。\n\n**提醒**：你的產品只要碰到「人、錢、健康、勞動」其中任何一個，先去問律師，別先寫 code。法規不是寫完上線後才補的功能，它是你能不能上線的前提——而且別忘了，最先去翻法條找你麻煩的，往往是被你動到的同業。\n\n## 想服務所有人，最後誰都沒服務好\n\n我們的定位很「大」。一邊想接小 B——行銷公司、公關公司、百貨賣場、活動展覽、研究調查；一邊又想做個人需求——代排、代買、跑腿、家事。聽起來市場很大，對吧？\n\n實際上，這代表我們的首頁要同時說服一個百貨採購和一個想找人代排隊的學生。代表每一個功能都得兼顧兩種完全不同的人。代表我們的行銷預算（本來就少得可憐）被切成好幾份，每一份都不夠用。用戶成長一直起不來，現在回頭看，不是行銷沒做好，是我們從沒讓任何一種人覺得「這就是為我做的」。\n\n更現實的是，我們媒合的那些事——搬家、代排、展場銷售人員——產值本來就低。B 端的公司要這些臨時人力，一單只肯付我們 50 元。50 元。就算用戶成長真的衝起來，把每一單的數字攤開，這個模式從一開始就撐不起一間公司。問題不只是「想服務所有人」，是我們挑的這幾個池子本身都太淺——選錯了池子，再努力划水也游不出去。\n\n聚焦，在當時的我眼裡是一個「策略選擇」——好像聚焦了就放棄了其他可能。但真相是：聚焦是生存問題，不是選擇題。它不只決定你能不能說服一種人，也決定你撈到的每一單，到底值不值得你做。\n\n**提醒**：開站第一天就回答得出「我先為哪一種人、解決哪一個具體場景」，而且要窄到讓你有點害怕。怕，通常代表你終於夠聚焦了。\n\n## 「能寫出來」不等於「有人要用」\n\n這是工程師最致命的錯覺，我也栽了。\n\n開站那天，我盯著後台一直按 F5——一天 106 個人註冊、最高 50 人同時在線。那一刻我和夥伴真的以為要成功了。但 106 個註冊，從來不等於 106 個「明天還會再回來」的人。我把「做得出來」和「有人持續要用」當成同一件事，這中間其實隔著一整個我沒搞懂的世界：需求是不是真的、頻率夠不夠、他願不願意付錢、付了之後會不會再來。\n\n我花了大把力氣把功能刻得又快又漂亮，卻很少停下來問：這個功能，到底有沒有人在等？寫得出來，是這整件事裡最廉價的能力。\n\n**提醒**：在你打開編輯器之前，先想辦法證明「有人要用」——哪怕只是用一張表單、一個 LINE 群、十通電話。能寫出來不是你的護城河，搞懂有沒有人要才是。\n\n## 所以呢，別創業嗎？\n\n不是。\n\nCityTasker 收攤後，我們各自先回去上班，有人轉去了旅遊產業，我則一路做到後來的技術負責人。我不後悔跳下去——那兩年讓我真正理解了 0 到 1 是什麼，這是再多薪水都買不到的學費。\n\n我想說的只是：跳，但張開眼睛再跳。技術從來不是創業最高的那道牆，這份清單上的每一項才是。看清楚它們，不會讓你變膽小，只會讓你跳得比當年的我聰明一點。\n\n至於那句一直在我心裡的「我們不是那 1%」——那是這個系列收尾時，我才想好好說清楚的事。", "summary": "工程師創業，最容易低估的從來不是技術，而是看不見的成本——燒錢的速度、沒人教你的法規、聚焦的代價，還有那個致命錯覺：寫得出來的東西，最不值錢。這是 CityTasker 用兩年燒完的錢，幫我列出的成本清單。", "image": "https://bobochen.dev/_astro/cover.CZXJ8wo9.webp", "date_published": "2026-06-13T00:00:00.000Z", "tags": [ "創業", "AppWorks", "CityTasker", "新創", "職涯反思", "工程師創業" ] }, { "id": "https://bobochen.dev/blog/citytasker-launch-day-story/", "url": "https://bobochen.dev/blog/citytasker-launch-day-story/", "title": "整個城市都有我的好幫手：CityTasker 開站那天，我們真的以為要成功了", "content_text": "2013 年 8 月 7 日，CityTasker 開站。我盯著後台一直按 F5，一天 106 個人註冊、最高 50 人同時在線、54 封簡訊發出去——那一刻，我跟夥伴真的以為要成功了。這是一個入選 AppWorks 第七屆、最後燒完錢收攤的創業故事的開場。", "content_html": "## 開站那天，我一直在重新整理後台\n\n2013 年 8 月 7 日，我幾乎沒離開過電腦。\n\n不是在寫程式——程式那天難得沒出包——而是一直按 F5。後台的數字每按一次就往上跳一格：註冊會員 87、94、101……到了傍晚，停在 106。同一時間最高有 50 個人在線上瀏覽，系統發出去 54 封簡訊通知，單日流量衝到 347MB。\n\n對今天動不動百萬日活的產品來說，這些數字小得可笑。但那天傍晚，我跟共同創辦人 JEJ 盯著螢幕，真的以為——我們要成功了。\n\n那個產品叫 CityTasker。\n\n![2013-08-07 CityTasker 單日流量後台，citytasker.tw 當天用掉 346.95 MB](./images/launch-day-bandwidth.webp)\n\n*開站當天的流量後台截圖。我一直留著它——`citytasker.tw` 那天跑了 346.95 MB，是這個小東西活著的證據。*\n\n## 一句話的傻勁\n\nCityTasker 的構想很簡單：**整個城市都有我的好幫手**。\n\n那時候國外的群眾外包（crowdsourcing）模式正紅，美國有 TaskRabbit、澳洲有 Airtasker——你有一件懶得做、或做不來的事：排隊買票、活動攝影、跑腿代買、家裡臨時需要人手，就把任務丟上平台，附近有空、想賺點外快的人接走。城市裡每個人的零碎時間，變成另一個人的解方。\n\n我們覺得這在台灣一定行。年輕、沒包袱、帳戶裡還有一點錢，再加上一股「這東西我做得出來」的傻勁，就開始了。\n\n我那時候是全端工程師，前端、後端、雙平台 App，一個人扛。技術選了 PHP、Laravel，後面接 AWS。團隊很小，所以沒有大公司那套流程，就是想到一個功能、刻出來、丟上線、看使用者怎麼反應，再改。JEJ 負責商務開發（BD），技術全是我扛，這樣就開幹了。\n\n## 我們還做了一支蝙蝠俠\n\n要讓人懂「找陌生人幫你做事」這件事，光用講的很無聊。所以我們拍了一支介紹影片。\n\n\n\n設定是這樣的：有一座叫「高潭市」的城市，永遠充滿混亂，高端局長每天頭痛得要命，好在他只要呼叫幫手，問題很快就解決了。然後鏡頭一轉——「但回歸現實，你住的不是高潭市，你也不是高端局長。當你有解決不了的問題時，該去哪裡找你的超級英雄呢？」\n\n對，就是蝙蝠俠那個高譚市。一群沒什麼預算的年輕人，硬是用這個梗，把產品講成一個「召喚城市英雄」的故事。現在回頭看有點中二，但我到今天還是覺得那個點子很可愛。\n\n## 入選 AppWorks 第七屆\n\n真正讓我們覺得「這好像是玩真的」的，是入選了 **AppWorks 第七屆（#7）** 創業育成計劃。\n\n對當時的我們來說，這是一張門票。突然之間，身邊都是一群跟你一樣、眼睛發亮、想用一個 app 改變世界的人。我還記得跑去跟 Jamie（林之晨）要簽名，空氣裡瀰漫著一種「hack everything」、什麼都能被重新發明的氣氛。第七屆的 Demo Day 結束後，連《數位時代》都報導了我們。\n\n那種「我們是被選中的」感覺，很迷人。迷人到讓你很容易忘記一件事：**入選育成計劃，跟做出一門生意，是兩回事。**\n\n## 那天之後呢？\n\n開站那天的 106 個註冊，是我創業生涯裡少數幾個純粹的快樂時刻。\n\n但你大概已經猜到了——這個故事的結局，不是我們成功了。\n\nCityTasker 最後沒能熬過去。資金燒完、市場定位卡住、路上還撞到幾道我完全沒想過的牆。那是接下來幾篇要慢慢講的事。\n\n我想先把這個開場留在這裡：留在那個還相信一切都會成的傍晚，留在那個一邊按 F5、一邊跟夥伴傻笑的我。\n\n因為接下來要復盤的每一件事——燒錢的速度、踩到的法規、那句「我們不是那 1%」——都是從這個傍晚出發的。", "summary": "2013 年 8 月 7 日，CityTasker 開站。我盯著後台一直按 F5，一天 106 個人註冊、最高 50 人同時在線、54 封簡訊發出去——那一刻，我跟夥伴真的以為要成功了。這是一個入選 AppWorks 第七屆、最後燒完錢收攤的創業故事的開場。", "image": "https://bobochen.dev/_astro/cover.6qJ646PR.webp", "date_published": "2026-06-13T00:00:00.000Z", "tags": [ "創業", "AppWorks", "CityTasker", "新創", "職涯反思", "群眾外包" ] }, { "id": "https://bobochen.dev/blog/citytasker-not-the-one-percent/", "url": "https://bobochen.dev/blog/citytasker-not-the-one-percent/", "title": "不是那 1% 的人：十年後，我怎麼看 CityTasker 這場沒成功的創業", "content_text": "創業圈總在歌頌那 1% 成功的人，剩下 99% 呢？十年後回看 CityTasker——一場燒完錢、親手收掉的創業，我想重新定義什麼叫「失敗」，以及這段沒成功的經歷，後來怎麼變成我做到 VP Engineering 的底氣。", "content_html": "CityTasker 是 2012 到 2014 年，我和朋友做的一個任務媒合平台——「整個城市都有我的好幫手」。入選了 AppWorks 第七屆育成計畫，開啟了不一樣的歷程，雖然公司後來被併購，故事最後結局還是燒完錢收攤了。\n\n![2014 年初，CityTasker 三人團隊在 AppWorks 的辦公室](./images/appworks-team-2014.webp)\n\n*2014 年初，AppWorks 的辦公室。我們團隊三人（中間是當年青澀的我）*\n\n## 收掉公司那天，我覺得自己是輸家\n\n口袋見底的感覺，是一點一點來的。\n\n不是某個戲劇性的早晨醒來發現帳戶歸零，而是你眼睜睜看著數字往下掉，知道再過幾個月就撐不住了，卻找不到任何能讓它停下來的方法。最後我們做了那個誰都不想做的決定：先散了吧，各自回去上班。隊友轉去了旅遊產業，我把履歷打開，重新變回一個「找工作的工程師」。\n\n那段時間我很難跟人說清楚自己在幹嘛。前一年還在 Demo Day 上意氣風發，被[《數位時代》報導](https://www.bnext.com.tw/article/30113/BN-ARTICLE-30113)，轉眼就要去面試別人的公司、當一個打工仔。我心裡有個聲音很清楚：你失敗了。你不是那種會成的人。\n\n![第七屆 AppWorks Demo Day，台上簡報的是 CityTasker](./demo-day.webp)\n\n*前一年的高光時刻：第七屆 AppWorks Demo Day，台上是 CityTasker，台下坐滿了人。*\n\n## 那 1% 的迷思\n\n創業圈是一個很會說故事的地方。\n\n我們聽到的，永遠是那些成的人——某某 App 被收購、某某團隊估值幾億、某某創辦人三十歲財富自由。這些故事很迷人，迷人到你會以為那是常態。但真相是，那只是 1%。剩下的 99%，安安靜靜地燒完錢、關掉網站、回去上班，沒有人替他們寫報導。\n\n而我，就是那 99%。\n\n我花了好幾年才願意承認這件事，又花了更久才想通：問題不在於我是 99%，而在於我一直用 1% 的標準，去審判一段根本不該那樣被衡量的經歷。\n\n## 重新定義「失敗」\n\n有句話我放在心裡很久——大意是：沒被開除過、沒開除過人、沒燒完錢結束過一間公司、沒領過失業救濟金，其實都不算什麼重大挫敗。\n\n當年我把它讀成自嘲。十年後再讀，我把它反過來想。\n\n我燒完了自己的錢。我親手把一間公司收掉。我一個人扛過前端、後端、雙平台 App，撞過從沒想過的法規牆，還活了下來。這些事，聽起來像一串失敗清單，但你仔細看——這是多數人一輩子都不會有機會經歷的事。大部分人從進職場到退休，從來沒有真正「擁有」過一個東西，沒有為它的生死負過全責。\n\n我有過。它沒成，但它確確實實是我的。失敗，原來不是經歷的相反，它本身就是一種少數人才有的經歷。\n\n## 創業沒給我財富，給了我視角\n\n那兩年最值錢的，不是任何一行我寫過的程式。\n\n是它逼著一個只會寫 code 的人，去做完整個 0 到 1：自己分析需求、自己選技術、自己帶人、自己跟外面的世界溝通。我第一次知道一個產品從無到有要繞過多少看不見的坑，第一次知道「做得出來」和「有人要用」中間隔著一整個世界。\n\n這些東西，後來全都回來找我。從 17 Media 的 Principal Engineer、Snapask 的後端技術總監，到現在 QT Medical 的 VP Engineering——每一個位子要我做的判斷，幾乎都能在 CityTasker 那兩年找到原型。我能比較沉得住氣地看一個產品、看一個團隊、看一個還沒被驗證的方向，是因為我年輕時用自己的錢，把這堂課完整上過一遍。\n\n創業沒讓我變有錢。它給了我一副別人花錢也買不到的眼睛。\n\n## 給那個按 F5 的傍晚\n\n所以如果能回到 2013 年那個傍晚——那個盯著後台數字一格一格往上跳、跟夥伴傻笑著以為要成功了的我——我不會劇透結局，也不會叫他別跳。\n\n我只想拍拍他的肩膀，告訴他：你不會成為那 1%，這件事到頭來沒那麼重要。你以為這是一場你會贏或會輸的賭局，但其實，你正在領的，是一筆要十年後才會到帳、而且永遠不會貶值的東西。\n\n好好享受這個傍晚吧。後面的路，比你想的長，也比你想的好。", "summary": "創業圈總在歌頌那 1% 成功的人，剩下 99% 呢？十年後回看 CityTasker——一場燒完錢、親手收掉的創業，我想重新定義什麼叫「失敗」，以及這段沒成功的經歷，後來怎麼變成我做到 VP Engineering 的底氣。", "image": "https://bobochen.dev/_astro/cover.DpyjKR2p.webp", "date_published": "2026-06-13T00:00:00.000Z", "tags": [ "創業", "AppWorks", "CityTasker", "新創", "職涯反思", "失敗復盤" ] }, { "id": "https://bobochen.dev/blog/citytasker-speed-over-perfection/", "url": "https://bobochen.dev/blog/citytasker-speed-over-perfection/", "title": "速度比完美更重要：創業教我的事，後來都變成我帶團隊的原則", "content_text": "CityTasker 是我 2012 年和朋友做的任務媒合平台。當年沒資源、沒時間，「速度比完美更重要」是被現實逼出來的生存本能；十年後當我帶團隊一路做到技術總監、VP，這套心態反而成了我刻意選擇的管理原則。", "content_html": "## 想到一個功能，當晚就上線\n\n2012 到 2014 年，我和朋友做了一個叫 CityTasker 的東西——一個任務媒合平台，slogan 是「整個城市都有我的好幫手」。你有件懶得做的事，丟上來，附近有空的人接走。\n\n那時候我是 Co-founder 兼全端工程師，前端、後端、雙平台 App，一個人扛。團隊小到不行，所以我們沒有什麼「規格先評審、設計先過稿」的流程。一個功能想到了，覺得使用者可能會要，當晚就刻，刻完隔天就丟上線，然後盯著後台看有沒有人用。\n\n沒人用，就拿掉。有人用，就接著改。\n\n現在回頭看，那根本不是什麼方法論，那是窮人的本能。\n\n## 完美是有錢人的奢侈品\n\n我得老實說：當年選擇「先上線再說」，不是因為我們讀過什麼敏捷開發的書，而是因為我們別無選擇。\n\n帳戶裡的錢每天都在變少。你沒有三個月去把一個功能磨到完美，因為三個月後公司可能就不在了。完美是一種需要時間和金錢餵養的東西，而那兩樣我們都沒有。我們唯一有的，是「先讓它活著、再看市場給不給臉」的急迫感。\n\n所以我們學會了一件事：**先把不完美的東西丟出去，讓真實的使用者告訴你哪裡錯，遠比關起門來自己猜要快得多。**一個你覺得很完美、但沒人要的功能，跟一個醜陋、卻有人天天用的功能比起來，後者的價值高出太多。\n\n那時候我以為這只是創業的求生技巧。我沒想到，它後來會變成我帶團隊的底層信念。\n\n## 從求生本能，變成刻意的選擇\n\nCityTasker 燒完錢收攤後，我回去上班，接著一路在軟體開發、技術管理、DevOps、雲端架構裡打滾，從 17 Media 的 Principal Engineer、Snapask 的後端技術總監，做到現在 QT Medical 的 VP Engineering。\n\n帶的人愈來愈多，我發現一件有趣的事：當年那個被現實逼出來的「速度比完美重要」，現在變成了我**刻意**選擇的管理原則。差別在於——以前是因為沒得選，現在是因為我知道它真的有用。\n\n具體來說，它長成幾個樣子：\n\n- **敏捷，但不是因為時髦。**小步快跑、快速迭代，是因為我親身體會過「猜錯方向但跑得快」可以及時掉頭，「猜對方向卻跑得慢」反而被市場拋下。\n- **公開透明的溝通。**創業時資訊就在我們幾個人腦袋裡，藏不住也不必藏。帶團隊後我刻意維持這件事：不藏決策的理由、不藏壞消息。資訊一旦變成少數人的特權，速度第一個死。\n- **鼓勵主動承擔、勇於實驗。**我希望團隊裡的人敢自己做決定、敢試錯，而不是每件事都等我點頭。能自己接住任務、自己往前推的人，才跑得起來。\n- **把失敗當養分，而不是拿來究責。**這大概是 CityTasker 給我最深的一課。一個沒成功的創業教會我，面對失敗可以更坦然，把它當成長的養分，而非絕對的挫敗。所以團隊裡有人實驗失敗了，我第一個問的不是「誰的錯」，而是「我們從中學到什麼」。\n\n## 但「速度比完美」也有它的代價\n\n不過十年下來，我也學到這句話不能無限上綱。\n\n「先上線再說」的另一面，是技術債、是品質的妥協、是你某天得回頭還的帳。創業時我可以說「反正公司能不能活到下個月都不知道，債以後再說」——但帶一個要長期經營的產品和團隊時，這句話會害死你。\n\n所以現在的我，拿捏的方式變了。我會問：這次的不完美，是「可以之後再補」的那種，還是「補不回來」的那種？使用者體驗的小瑕疵、之後可以重構的程式碼，先上；但牽涉到資料安全、病人安全、信任這種補不回來的東西，我寧可慢。\n\n速度依然重要，但成熟一點的版本是：**該快的地方快到底，該慢的地方有膽量慢下來。**而分辨這兩者，正是十年來我一直在練的功課。\n\n## CityTasker 真正留給我的\n\n那場創業沒有成功。錢燒完了，口袋見底，我們先回去上班，隊友轉去了旅遊產業。從世俗的標準看，它是個失敗的故事。\n\n但「速度比完美更重要」這句話，跟著我走了十年，從一個窮學生的求生本能，長成一個技術主管的管理哲學。它幫我帶過好幾個團隊、撐過好幾個產品。\n\n如果有人問我 CityTasker 留下了什麼——不是那些註冊數字，也不是 AppWorks 的光環。是這套被現實狠狠教過、之後我又選擇相信一輩子的做事方式。\n\n這大概就是一場沒成功的創業，最值錢的遺產。", "summary": "CityTasker 是我 2012 年和朋友做的任務媒合平台。當年沒資源、沒時間，「速度比完美更重要」是被現實逼出來的生存本能；十年後當我帶團隊一路做到技術總監、VP，這套心態反而成了我刻意選擇的管理原則。", "image": "https://bobochen.dev/_astro/cover.Dohn-98-.webp", "date_published": "2026-06-13T00:00:00.000Z", "tags": [ "創業", "AppWorks", "CityTasker", "職涯反思", "技術管理", "團隊管理" ] }, { "id": "https://bobochen.dev/blog/citytasker-sudo-acquisition/", "url": "https://bobochen.dev/blog/citytasker-sudo-acquisition/", "title": "賣掉之後呢：CityTasker 最意外的結局，是連買下我們的公司也不在了", "content_text": "我說 CityTasker 燒完錢收攤了——那是真的，但不是全部。它後來其實被一間 AppWorks 認識的獵頭顧問公司 sudo 買下，從合作、一頓頓早餐會、到一紙 2016 年的收購合約。而最意外的結局是：連買下我們的那間公司，後來也不在了。", "content_html": "我在前面說過，CityTasker 燒完錢、收攤了。\n\n那是真的。但不是全部。\n\n有一段我一直沒講——因為它太安靜了，安靜到連我自己都差點以為它不算數。CityTasker 並沒有真的死在 2014 年那個收攤的決定裡。它後來，被賣掉了。\n\n## 收攤，不等於結束\n\n公司收掉之後，團隊是散了，但 CityTasker 這個東西、還有我們在創業圈裡結下的關係，沒有跟著散。\n\n故事要從 AppWorks 說起。我們那屆育成裡，還有另一支團隊，叫 sudo——一間做獵頭、人力顧問的公司。創業圈很小，同一個屋簷下一起被孵化，低頭不見抬頭見，我們很自然就熟了。\n\n一開始只是合作。他們媒合的是「人才」，我們媒合的是「任務」，中間有不少搭得上的地方，就你幫我、我幫你地來往著。\n\n## 那些早餐會\n\n真正讓事情慢慢長出來的，是早餐。\n\nsudo 的創辦人會定期約我們吃早餐。沒有什麼正式議程，就是邊吃邊聊——聊產品、聊團隊、聊各自卡在哪裡。現在回頭看，那一頓一頓的早餐，其實是一段很慢、很有耐心的「互相了解」。\n\n創業的時候，我一直以為談事情要靠 pitch deck、靠估值表、靠會議室裡正襟危坐的那一套。後來才知道，很多真正重要的事，是在一張早餐桌上、配著一杯溫豆漿談成的。\n\n## 一紙合約\n\n2016 年，我們簽了一份合約。\n\nCityTasker，賣給了 sudo。\n\n那一刻的感覺，我到現在都說不太清楚。它不像 2014 年收攤那樣，有明確的失落；也不像被大公司高價收購那樣風光。它就是——一個我親手做出來、又親手收掉的東西，終於找到了一個願意接手的人。\n\n這算成功出場嗎？還是只是換一種方式收攤？我到今天都還沒有標準答案。\n\n![2016 年，把 CityTasker 賣給 sudo 的收購契約書](./images/citytasker-收購契約.jpg)\n\n*2016 年的那紙收購契約書。一個親手做出來的東西，最後用一份合約交了出去。*\n\n## 然後，買下我們的人也不在了\n\n但這個故事真正讓我意外的，不是「賣掉」這件事本身。\n\n是沒過多久，sudo 自己，也收了。\n\n那個曾經坐在我對面、一口一口早餐跟我談下 CityTasker 的人，他的公司，後來也走進了跟我們一樣的結局。\n\n我一直以為，我是把 CityTasker 交到了一個「比我們更穩、更會做生意」的人手上——一個更像那 1% 的人。但事實證明，沒有誰是穩的。在這個圈子裡，今天看起來活得好好的人，明天可能就不在了。我是這樣，他也是。\n\n## 真正活得比公司久的東西\n\n所以 CityTasker 到底死了幾次？\n\n收攤算一次，賣掉算一次，連買下它的人都消失，再算一次。照理說，這應該是一個徹底失敗、徹底歸零的故事。\n\n但奇怪的是，留下來的東西，比我以為的多。\n\n不是公司——公司早就沒了。是那張在 AppWorks 結下的關係網，是那些早餐桌上的對話，是「原來一件事可以這樣慢慢談成」的那種篤定。這些東西，比任何一間公司都活得久。\n\n我花了整整一個系列，想搞懂自己到底算不算那 1%。寫到這裡，我終於確定：這個問題，從一開始就問錯了。\n\n公司會收、會賣、會被接手的人再收掉一次。但你在過程裡認識的人、你學會看世界的方式，不會。那才是真正不會貶值的東西。\n\nCityTasker 死了三次。但它，從來沒有真的離開我。", "summary": "我說 CityTasker 燒完錢收攤了——那是真的，但不是全部。它後來其實被一間 AppWorks 認識的獵頭顧問公司 sudo 買下，從合作、一頓頓早餐會、到一紙 2016 年的收購合約。而最意外的結局是：連買下我們的那間公司，後來也不在了。", "image": "https://bobochen.dev/_astro/cover.dXyCgqnf.webp", "date_published": "2026-06-13T00:00:00.000Z", "tags": [ "創業", "AppWorks", "CityTasker", "併購", "新創", "職涯反思" ] }, { "id": "https://bobochen.dev/blog/agentic-engineering-future-and-you/", "url": "https://bobochen.dev/blog/agentic-engineering-future-and-you/", "title": "Agentic Engineering 的下一步：2026 之後，工程師還需要寫 code 嗎？", "content_text": "SWE-bench Pro 今天 23%，一年後會是多少？當 agent 的能力每季都在進步，工程師的不可取代性到底在哪裡？不做預測，而是從一年實戰中歸納出不會被 agent 取代的能力，以及一份你今天就能開始的「防衰退」訓練計畫。", "content_html": "> 這是「Agentic Engineering 實戰手冊」系列的最後一篇。上一篇：[團隊導入](/blog/agentic-engineering-team-adoption)\n\n## 一年前 49%，現在 72%，明年呢？\n\n一年前我開始 100% AI coding 的時候，SWE-bench Verified 的最高分是 49%。寫這篇文章的今天，最高分已經超過 72%。\n\n一年之內進步了 23 個百分點。如果保持這個速度，2027 年就會接近 95%。\n\n但別急著恐慌（或歡呼）。因為更嚴格的 SWE-bench Pro，最好的 model 也只拿到 ~23%。JetBrains 的 DPAI Arena 和 Stanford 的 Terminal-Bench 也顯示類似的模式——agent 在「乾淨的、有限範圍的」問題上進步飛速，在「混亂的、需要廣泛 context 的」真實世界問題上進步緩慢。\n\n72% 跟 23% 之間的落差（Gartner 預測 40% 的 agentic AI 部署會在 2027 年前被取消）告訴我們一個重要的事實：agent 的「demo 能力」和「真實世界能力」之間，仍有巨大鴻溝。\n\n這個鴻溝在縮小嗎？一定在。但以什麼速度，沒人知道。\n\n我不打算做預測，那是 pundit 的工作。作為一個 practitioner，我更感興趣的是：不管 agent 的能力怎麼變，什麼是不變的？\n\n## 2026 年，Agent 仍然不會做的事\n\n經過一年的實戰，我整理出五件 agent 到今天為止仍然做不好、且短期內不太可能做好的事：\n\n### 1. 釐清模糊的需求\n\n「用戶反映登入流程太複雜。」\n\n這句話背後可能意味著 20 種不同的改善方向。人類工程師會去找 PM 問、看 user research、在白板上畫 flow——然後形成一個具體的方案。\n\nAgent 拿到這句話之後，會直接開始寫 code。寫出來的東西可能很完整，但解決的可能不是真正的問題。\n\n[Spec-Driven Development](/blog/spec-driven-development-for-agents) 可以緩解這個問題，但 spec 本身得由人來寫。把模糊需求變成精確 spec 的能力，是目前 agent 無法取代的。\n\n### 2. 組織政治與跨團隊協調\n\n「這個 API 改動需要後端團隊同意」、「那個 PM 特別在意 performance」、「QA 組長不喜歡我們用太多 mock」。\n\n這些 organizational context 不在 codebase 裡，也不在任何文件裡，它們存在於人的關係和記憶中。Agent 沒辦法 navigate 這些。\n\n### 3. 品味與審美判斷\n\n「這個 UX 好嗎？」不是一個有標準答案的問題。\n\nAgent 可以完美實現你 spec 裡描述的每一個細節。但如果你的 spec 沒有描述「這個按鈕在這裡感覺太擠」，agent 不會自己發現。\n\nDesign sense、產品直覺、「這個感覺不對」的第六感，這些目前完全是人類的領域。\n\n### 4. 倫理和合規判斷\n\n「這個功能收集了 PII，需要通知用戶嗎？」\n「我們的 AI feature 在歐盟受 AI Act 規範嗎？」\n「這個 dark pattern 在法律上可以但在道德上該不該用？」\n\nAgent 可以幫你查法規、整理 compliance checklist，但最終的判斷——「我們做不做這件事」——必須是人做的。\n\n### 5. 真正創新的架構設計\n\nAgent 非常擅長 follow 既有的 patterns。你的 codebase 用了 MVC，它就會寫 MVC。你用了 event-driven，它就寫 event-driven。\n\n但當你需要 **break** 既有的 pattern——因為 scale 需要、因為 paradigm shift、因為你發現了一種更好的方式——agent 幫不了你。它的 training data 是過去的 best practices，不是未來的。\n\n## 不可取代的人類能力\n\n把以上歸納為四種核心能力：\n\n### 判斷力\n\n知道什麼該做、什麼不該做。\n\nAgent 可以做任何你叫它做的事。但「這件事值不值得做」、「做到什麼程度就夠了」、「這個 trade-off 怎麼取」，這些都是判斷力的範疇。\n\n在 agentic workflow 裡，你做的每一個決策的價值都被放大了。因為 agent 會忠實地執行你的決策：好的決策會被高效執行，壞的決策也會。\n\n### 品味\n\n不是「能不能做」，而是「該不該這樣做」。\n\n好的 API 設計、好的 UX、好的 code 結構，這些都需要 taste。Agent 可以在你給的 constraints 內找到最優解，但 constraints 的設計需要品味。\n\n### 組織 Context\n\n理解公司政治、團隊動態、stakeholder 的優先級。\n\nAgent 不知道你的 CTO 最近在推 microservices、你的 PM 下個月要 demo 給投資人看、你的 QA 上週才因為沒 test 被 production bug 搞到加班。這些 context 決定了你該怎麼排優先級、怎麼溝通、怎麼取捨。\n\n### 倫理決策\n\n合規、隱私、安全的最終判斷。\n\n這不是 agent 做不到，而是我們不應該讓 agent 做。涉及 ethics 的決策需要 accountability，而 accountability 只能由人來承擔。\n\n## 技能衰退？還是技能轉型？\n\n回到 [Post 2](/blog/agentic-engineering-mindset-shift) 討論過的身份認同議題：用了一年 agent，我的技能有什麼變化？\n\n### 衰退的能力\n\n- **語法記憶**：我已經忘記很多 API 的具體參數了。以前能憑記憶寫出完整的 `Array.reduce`，現在常常要想一下。\n- **手寫 boilerplate 的速度**：以前 30 分鐘能寫完一個 CRUD endpoint，現在手寫可能要 45 分鐘（因為不常練了）。\n- **某些 debug 直覺**：以前看到 error message 就大概知道是什麼問題。現在我傾向先丟給 agent，而不是自己分析。\n\n### 增長的能力\n\n- **系統設計能力**：因為 agent 處理了 implementation 細節，我花更多時間想架構、想 trade-off。設計能力反而變強了。\n- **需求分析能力**：寫 [spec](/blog/spec-driven-development-for-agents) 寫多了，分析和拆解需求的能力提升了。\n- **Review 眼光**：看了一年 agent 的 code，我對 [hallucination pattern](/blog/agent-output-verification-review) 的敏感度提高了很多。\n- **溝通表達能力**：寫好的 spec 就是清楚的溝通。這個技能也提升了。\n\n### 淨結果\n\n對有經驗的工程師來說，這是一個划算的交換：低價值的「打字型」技能衰退，高價值的「判斷型」技能增長。\n\n但我要誠實地說，這讓我偶爾感到不安。有時候同事問我一個 syntax 問題，我需要查一下才能回答，心裡會覺得「以前我是可以秒答的」。\n\n這種不安是正常的。技能轉型的過程中，舊能力的衰退總是比新能力的增長更容易被察覺。但退一步看，一個擅長系統設計和需求分析、只是需要查 syntax 的工程師，比一個能背 API 參數但不擅長設計的工程師，在 agent 時代更有價值。\n\n## 一份「防衰退」訓練計畫\n\n不管你對未來怎麼看，以下的練習都不會浪費。它們同時鍛練「跟 agent 協作」和「agent 做不到的事」。\n\n### 8 週循環計畫\n\n**Week 1-2：Context Engineering 練習**\n\n- 目標：讓你的 [CLAUDE.md](/blog/claude-md-rules-files-masterclass) 的品質提升一個等級\n- 練習：review 你的 CLAUDE.md，問自己「agent 重複犯的錯哪些可以靠加一條 rule 解決？」\n- 副作用：練習精確溝通的能力\n\n**Week 3-4：Spec Writing 練習**\n\n- 目標：每個 task 都先寫 [spec](/blog/spec-driven-development-for-agents) 再交給 agent\n- 練習：用 Goal / Constraints / Verification 格式寫 spec\n- 副作用：練習需求分析和拆解的能力\n\n**Week 5-6：Review 練習**\n\n- 目標：刻意練習找 agent code 裡的問題\n- 練習：review agent 的 PR 時，記錄你找到的每一個問題，分類是「邏輯錯誤」還是「事實錯誤」\n- 副作用：提升 [code review](/blog/agent-output-verification-review) 的效率和敏感度\n\n**Week 7-8：手寫練習**\n\n- 目標：保持基礎能力的手感\n- 練習：每兩週選一個小功能，不用 agent，完全手寫\n- 副作用：當 agent 出問題時你還有能力自己 debug\n\n### 持續練習\n\n- **每月一次架構設計**：不用 agent，自己做一個系統的架構決策。可以是你正在做的專案的某個子系統。\n- **每季一次 agent-free day**：完全不用 agent 工作一天。感受差異，保持自信。\n\n## 回到 Trust Paradox\n\n[Post 1](/blog/agentic-engineering-what-is-it) 開頭提到的數據：80% 的開發者在用 AI agent，但只有 29% 信任它。\n\n14 篇文章之後，我想我理解這個 paradox 了。\n\n信任不是靠「AI 變得更好」來建立的，而是靠方法論來建立的。\n\n你不信任 agent 是因為：\n\n- 它會 hallucinate（→ 你建了 [品質保證流程](/blog/agent-output-verification-review)）\n- 它不懂你的專案（→ 你設計了 [context engineering](/blog/context-engineering-deep-dive)）\n- 它會亂做（→ 你寫了 [spec](/blog/spec-driven-development-for-agents)）\n- 它可能搞壞東西（→ 你設了 [安全網](/blog/agentic-engineering-testing-safety)）\n- 它很貴（→ 你做了 [成本優化](/blog/agentic-engineering-cost-optimization)）\n\n每一個不信任的理由，都有一個工程解法。\n\nAgentic Engineering 不是盲目信任 AI，而是用工程方法建立有根據的信任。\n\n這整個系列教的，就是這件事。\n\n## 結語：工程師的黃金時代\n\n我不知道 5 年後工程師還需不需要寫 code。老實說，沒有人知道。\n\n但我知道一件事：2026 年的今天，是工程師有史以來能產出最多價值的時代。\n\n一個人 + 一個 agent，可以做到以前需要一個小團隊才能做的事。[一個需求 60 分鐘從 Prompt 到 Production](/blog/agentic-engineering-daily-workflow-advanced)。一個好的 [spec](/blog/spec-driven-development-for-agents) 可以驅動一整個 feature。一份好的 [CLAUDE.md](/blog/claude-md-rules-files-masterclass) 可以讓 agent 像一個了解你專案的 junior engineer 一樣工作。\n\nBuilder 的門檻比以前更低了。一個人可以建產品、發布、維護，不需要融資、不需要團隊。但這不代表工程師的價值降低了，恰恰相反，**有 judgment 的工程師**比以前更稀缺。\n\n因為 agent 放大了一切：好的判斷被放大成高效的成果，壞的判斷也被放大成高效的災難。能做出好判斷的人，從來沒有像現在這麼有價值。\n\n所以，如果你問我「工程師還需要寫 code 嗎？」\n\n我的答案是：你需要的不是「寫 code」的能力，而是「知道該寫什麼 code」的能力。前者 agent 在取代，後者 agent 在放大。\n\n14 篇下來，從 [Agentic Engineering 是什麼](/blog/agentic-engineering-what-is-it) 到 [怎麼帶進團隊](/blog/agentic-engineering-team-adoption)，我分享了一年 100% AI coding 的完整方法論。這不是一篇「AI 會改變世界」的泛泛之談。這是一個工程師的實戰紀錄——踩過的坑、找到的解法、建立的系統。\n\n如果這個系列對你有幫助，它之後會整理成書。\n\n不是因為我要賣書，而是因為我相信，工程師需要一份「agent 使用手冊」——不是工具教學，而是方法論。\n\n這份手冊，就是你現在手上的這 14 篇。\n\n## Takeaway\n\n1. **Agent 在進步，但「demo 分數」跟「真實世界能力」之間仍有巨大鴻溝**。SWE-bench Verified 72% vs SWE-bench Pro 23%，這個差距就是 Agentic Engineering 存在的意義——你是那個填補鴻溝的人。\n\n2. **不可取代的不是「會寫 code」，而是「知道該寫什麼 code」**。判斷力、品味、組織 context、倫理決策——這些能力在 agent 時代的價值不減反增。\n\n3. **最好的防衰退策略不是抗拒 AI，而是讓 AI 替你做低價值的事，你專注在高價值的判斷上**。8 週循環訓練計畫涵蓋了 context engineering、spec writing、code review、和手感維持——這些是不管 AI 怎麼發展都有用的能力。\n\n---\n\n_這是「Agentic Engineering 實戰手冊」系列的最後一篇。_\n_完整系列：[系列目錄](/blog/agentic-engineering-what-is-it)_\n_如果這個系列對你有幫助，它之後會整理成書。敬請期待。_", "summary": "SWE-bench Pro 今天 23%，一年後會是多少？當 agent 的能力每季都在進步，工程師的不可取代性到底在哪裡？不做預測，而是從一年實戰中歸納出不會被 agent 取代的能力，以及一份你今天就能開始的「防衰退」訓練計畫。", "image": "https://bobochen.dev/_astro/cover.BaTdqDSD.webp", "date_published": "2026-06-12T00:00:00.000Z", "tags": [ "Agentic Engineering", "AI", "未來趨勢", "職涯", "軟體工程" ] }, { "id": "https://bobochen.dev/blog/homebrew-6-0-0/", "url": "https://bobochen.dev/blog/homebrew-6-0-0/", "title": "Homebrew 6.0 來了：先搞懂這幾個會影響你日常的改動", "content_text": "Homebrew 6.0 不是炫技版號，而是把資安收緊、把你每天 brew install 的習慣改掉，還開始跟 Intel Mac 道別。挑幾個對 Mac 開發者最有感的改動，實測給你看。", "content_html": "如果你是 Mac 開發者，`brew` 大概是你每天最早敲下的幾個指令之一。所以當它跳上 **6.0** 這個大版號時，值得花十分鐘搞清楚發生了什麼事——因為大版號意味著 breaking change，而這次有幾個改動，是你「下一次 `brew install` 就會直接撞到」的那種。\n\n先給結論：6.0 的重點，是把你每天在用的 brew 變得**更安全、也更快**——不是塞一堆新功能，而是把基本功做扎實。而你會直接撞到的，是這三件事——\n\n1. **把供應鏈安全收緊**：第三方 tap 不再「裝了就跑」。\n2. **改掉你每天的操作習慣**：`brew install` 現在會先問你一句。\n3. **開始跟 Intel Mac 道別**：x86_64 進入退場時間表。\n\n剩下的都是錦上添花。下面一個一個看。\n\n## brew install 之後，它現在會先問你一句\n\n這是你最快會注意到的改動。以前 `brew install something` 按下 enter，它就一路裝到底。6.0 開始，**對開發者預設開啟「ask 模式」**：你敲下指令後，它不會立刻動手，而是先列出這次會連帶安裝或升級哪些相依套件，停下來等你回一個 `Y`。升級時如果沒有東西需要動，它也夠聰明、不會多問。\n\n官方說這是照使用者問卷做的決定——大家其實想在「它要對我的系統做什麼」之前，有個喊停的機會。\n\n實務上唯一要注意的是 **CI**。你的 pipeline 裡如果有 `brew install`，多了一個互動式確認就會直接卡住。兩個解法：\n\n```bash\n# 本機：這次不要問\nbrew install -y wget # 或寫成 --no-ask\n\n# CI：整個環境都別問\nexport HOMEBREW_NO_ASK=1\n```\n\n> [!NOTE]\n> `-y` / `--no-ask` 是「這次不要問」，`HOMEBREW_NO_ASK` 是「整個環境都別問」。本機留著 ask 模式其實很好用（避免手滑裝錯、被拖一大串相依套件下來），但 CI 記得設環境變數。\n\n## 第三方 tap 不再「裝了就跑」：Tap 信任機制\n\n這是 6.0 真正的頭條，也是最值得花時間理解的一個。\n\n先講清楚問題：一個第三方 tap（`brew tap user/repo` 那種）本質上是**一包會在你機器上、用你的權限、不經沙箱執行的 Ruby 程式碼**。你 `brew install` 它底下的某個 formula，等於同意跑它的安裝腳本。過去這件事是默默發生的——這也正是為什麼近期會出現「把惡意程式碼塞進 tap」這類攻擊。\n\n6.0 把這個洞補起來：**第三方 tap（以及它底下的 formula、cask、外部指令）現在必須先被你明確信任，Homebrew 才會去 evaluate 它的程式碼。** 官方的 Homebrew taps 和內建指令一律預設信任，所以你日常的 `brew install wget` 完全不受影響。\n\n要信任有兩種做法：\n\n```bash\n# 做法一（推薦）：只信任你真正要的那一個\n# 用「完整路徑名」安裝，就只信任這一項\nbrew install user/repo/formula\nbrew install --cask user/repo/cask\n\n# 做法二：信任整個 tap（連它之後新增的東西也一起放行）\nbrew trust user/repo\n```\n\n「做法一」的範圍最小，是官方建議的預設姿勢——你要哪個就信任哪個，而不是把整個 tap 未來會長出來的所有東西，現在就先簽下去。\n\n過渡期如果你被擋住、或 CI 整批爆掉，有一個**暫時**的逃生門：\n\n```bash\nexport HOMEBREW_NO_REQUIRE_TAP_TRUST=1\n```\n\n但官方講得很白：這只是過渡用的，最終會強制。所以正解是把你常用的幾個 tap 一次信任好，而不是長期靠這個環境變數繞過。\n\n> [!WARNING]\n> 如果你的 CI 在升上 6.0 之後突然變紅，第一個要懷疑的就是這裡——`brew doctor` 的 untrusted-tap 檢查、或第三方 tap 的 formula 載入被擋下。先盤點 pipeline 裡用到哪些非官方 tap，把它們補上 trust。\n\n## brew exec：Homebrew 版的 npx\n\n如果你寫過 Node，一定用過 `npx`——不想把工具裝進全域，臨時拉下來跑一次就好。6.0 給了 Homebrew 一個對應的東西：**`brew exec`**（縮寫 `brew x`）。\n\n它的用法是：指定這次需要哪些 formula，Homebrew 幫你（必要時）裝好、把它們和相依套件的執行檔目錄塞進 `PATH`，然後跑你的指令：\n\n```bash\n# 臨時用 jq + yq 跑一個腳本，不用先全域安裝\nbrew exec --formulae=jq,yq -- ./script.sh\n```\n\n對「我只是想跑個一次性腳本、不想污染環境」這種情境很實用，尤其是寫教學、寫 Makefile、或想在乾淨環境裡驗證相依關係的時候。\n\n## brew vulns：順手掃一下裝了什麼有洞的東西\n\n延續這版的資安主軸，6.0 還多了 **`brew vulns`**：拿你「已經安裝」的套件去比對已知漏洞，告訴你哪些東西該升級了。\n\n過去你大概得靠額外工具、或自己留意 CVE，現在 Homebrew 本身就能給你一張清單。詳細選項可以用 `brew vulns --help` 看，但概念很單純——把「你裝了什麼」和「哪些版本有已知問題」對起來，是個值得偶爾跑一次的習慣。\n\n## 這版整體變快了\n\n6.0 把幾個原本是選用的加速項目轉成預設：\n\n- **內建 JSON API 變預設**：把套件 metadata 合併成單次下載，少了一堆零碎的網路請求，啟動更快。（舊的 `HOMEBREW_USE_INTERNAL_API` 環境變數也因此功成身退、被標記棄用。）\n- **`brew leaves` 快了約 30%**：就是列出你「手動裝、且沒被其他套件依賴」的那個指令。\n- **平行化**：升級時平行抓 bottle 的 tab、`brew bundle` 預設平行安裝 formula。\n\n這些都不用你動手，升上去就有。\n\n## Intel Mac 的倒數計時開始了\n\n如果你還在用 Intel（x86_64）的 Mac，這段一定要看。官方公布了明確的退場時間表：\n\n| 時間 | x86_64 macOS 的狀態 |\n| --- | --- |\n| 2026 年 9 月 | 降到 **Tier 3**：不再跑 CI、不再產新的 bottle |\n| 2027 年 9 月 | **完全不支援**，相關程式碼整批移除 |\n\n白話講：今年九月之後，Intel Mac 上不少套件會開始沒有預編譯好的 bottle，得自己從原始碼編（慢，又容易踩雷）；明年九月之後就完全不在支援範圍內了。手上還有 Intel 機器在當生產力主力的人，這一年就是你規劃遷移的窗口。\n\n同一批 OS 相關更新還包括：\n\n- **macOS 27（Golden Gate）** 初步支援上線（同時這版也是放掉 Intel 的版本）。\n- 認得 **M5、M5 Pro/Max** 晶片。\n- WSL 體驗改善（`brew config` 會顯示 Windows build）。\n\n## 其他順手知道就好的改動\n\n不是每個人都會用到，但掃一眼留個印象：\n\n- **Cask 現在可以 pin**：把某個 GUI app 釘在特定版本，不讓它被升級。\n- **Install Steps 框架**：把常見的安裝步驟（建目錄、搬檔案、建 symlink）改成「純資料、不需要在安裝當下跑 Ruby」的描述——又是一個縮小安全暴露面的設計。\n- **下載冷卻（download cooldowns）**：對 Bundler、RubyGems、npm、pip、PyPI 加了節流，降低供應端被濫用的風險。\n- **`brew bundle` 變強**：新增 `npm`、`krew`、`winget`（Windows）支援，`cleanup` 也能一起管 npm／cargo／go／uv。\n- **Services**：可以啟動 systemd timer、自動建好 service 需要的目錄。\n\n## 要現在升級嗎？怎麼升\n\n要。這版的安全改動是實打實有意義的，加速也是免費送的。升級照舊：\n\n```bash\nbrew update\nbrew upgrade\n```\n\n升完之後，給自己三個提醒：\n\n1. **CI 會不會被卡**：ask 模式 → 設 `HOMEBREW_NO_ASK=1`；第三方 tap → 補 `brew trust`，別長期靠 `HOMEBREW_NO_REQUIRE_TAP_TRUST` 繞過。\n2. **盤點你的非官方 tap**：花五分鐘把常用的幾個一次信任好，之後就順了。\n3. **Intel 使用者排遷移**：把「九月前」放進行事曆。\n\n一句話總結：Homebrew 6.0 沒有給你新玩具，但它讓「你每天都在用的這個工具」更安全、更快，也更願意在動手前先問你一句。對天天 `brew` 的人來說，這種版本反而最值得認真升。\n\n---\n\n*資料來源：[Homebrew 6.0.0 官方公告](https://brew.sh/2026/06/11/homebrew-6.0.0/)、[Homebrew Tap-Trust 文件](https://docs.brew.sh/Tap-Trust)、[Homebrew Manpage](https://docs.brew.sh/Manpage)。*", "summary": "Homebrew 6.0 不是炫技版號，而是把資安收緊、把你每天 brew install 的習慣改掉，還開始跟 Intel Mac 道別。挑幾個對 Mac 開發者最有感的改動，實測給你看。", "image": "https://bobochen.dev/_astro/cover.DrXfWNUu.webp", "date_published": "2026-06-12T00:00:00.000Z", "tags": [ "Homebrew", "macOS", "套件管理", "開發環境", "資安" ] }, { "id": "https://bobochen.dev/blog/chezmoi-name-pronunciation-chez-moi/", "url": "https://bobochen.dev/blog/chezmoi-name-pronunciation-chez-moi/", "title": "chezmoi 到底怎麼念？它是法文「我家」，拿來管 $HOME 剛剛好", "content_text": "chezmoi 不念「切斯莫伊」——它是法文 chez moi [ʃɛ mwa]「我家」。一個管理你 $HOME 的工具，名字就叫「我家」，背後是個很巧妙的設計隱喻。", "content_html": "我寫了一整個系列在講 `chezmoi`——多機同步、template、加密、private repo bootstrap……每天 `chezmoi apply` 敲得飛快。\n\n但前陣子被同事問了一句話，我居然答不出來：\n\n> 「這個 `chezmoi`，到底怎麼念？」\n\n我下意識念了「切斯-莫伊」（chez-moy），唸完自己都心虛。回去查了一下才發現——**大部分人都念錯了，包括我**。\n\n## 正解：它是法文\n\n`chezmoi` 不是某個工程師亂拼的字母組合，它是一個**法文片語** `chez moi`：\n\n> [!NOTE] chezmoi 怎麼念\n> **`chez moi` → IPA `[ʃɛ mwa]`，注音近「雪・ㄇㄨㄚ」**\n> - `chez` ≈ 「雪」`[ʃɛ]`（不是「切斯」，z 不發音）\n> - `moi` ≈ 「ㄇㄨㄚ」`[mwa]`（不是「莫伊」，oi 在法文念 `[wa]`）\n>\n> （注音是為了好記的近似標註，真正的母音還是以 IPA 為準。）\n\n![Google AI 摘要：「chez moi」的法文發音為 ʃɛ mwa（雪 ㄇㄨㄚ），chez 唸 ʃɛ、moi 唸 mwa](./image.png)\n\n*連 Google 搜尋的 AI 摘要都這樣標——唸「雪・ㄇㄨㄚ」。*\n\n關鍵就在那兩個「以為會發音、其實不發」的字母：`chez` 的 `z` 是啞音，`moi` 的 `oi` 在法文一律念 `[wa]`（跟 `bonjour` 旁邊的 `moi`、`voilà` 的邏輯一樣）。所以整個字聽起來是輕快的「**雪・ㄇㄨㄚ**」，不是硬邦邦的「切斯莫伊」。\n\n## 意思更妙：它是「我家」\n\n把這個片語拆開：\n\n- `chez` 是法文的介系詞，意思是「**在……的地方 / 在某人家**」\n- `moi` 就是「**我**」\n\n合起來，`chez moi` = **「在我家 / 我家」**。這是法國人天天掛在嘴邊的日常用語——「Viens chez moi（來我家）」、「Je reste chez moi（我待在家）」。\n\n## 為什麼這名字是神來一筆\n\n現在回頭看這個工具在做什麼，你會會心一笑。\n\n[chezmoi 的設計哲學](/blog/chezmoi-dotfiles-multi-machine-setup/)是：**你的 dotfiles 是「原始碼」，你的 home 目錄是「編譯結果」**。它把 source state 編譯、渲染、解密之後，寫進你的 **destination state——也就是你的 `$HOME`**。\n\n換句話說，這個工具**從頭到尾就只做一件事：把東西安頓進你的家目錄**。\n\n而它的名字，字面意思就是「**我家**」。\n\n一個專門管理 `$HOME` 的工具，取名叫「我家」。連 Unix 裡代表 home 的那個 `~` 符號都跟著一起呼應了。命名跟功能扣得這麼緊，實在漂亮。\n\n> [!TIP] 順帶一提\n> chezmoi 的作者是 [Tom Payne（twpayne）](https://github.com/twpayne/chezmoi)。下次有人把它念成「切斯莫伊」，你就可以淡淡地補一句：「是『雪・ㄇㄨㄚ』喔，法文，意思是我家。」\n\n## 一句話記法\n\n> **念「雪・ㄇㄨㄚ」，意思是「我家」——管你 `$HOME` 的工具，名字就叫我家。**\n\n記住這句，發音、拼字、設計理念，一次全到位。\n\n---\n\n想真的把「我家」搬上每一台新電腦，看這幾篇實戰：\n\n- [chezmoi 實戰：一份 dotfiles 管理三台不同用途的 Mac](/blog/chezmoi-dotfiles-multi-machine-setup/)\n- Dotfiles 管理術：用 chezmoi 一鍵重建開發環境\n- [Mackup vs chezmoi vs 手寫 script：macOS 設定備份工具怎麼選？](/blog/mackup-vs-chezmoi-vs-defaults-sh-comparison/)", "summary": "chezmoi 不念「切斯莫伊」——它是法文 chez moi [ʃɛ mwa]「我家」。一個管理你 $HOME 的工具，名字就叫「我家」，背後是個很巧妙的設計隱喻。", "image": "https://bobochen.dev/_astro/cover.Buq0kwgH.webp", "date_published": "2026-06-08T00:00:00.000Z", "tags": [ "chezmoi", "dotfiles", "冷知識", "macOS", "開發環境" ] }, { "id": "https://bobochen.dev/blog/coursera-verify-id-chinese-name-passport/", "url": "https://bobochen.dev/blog/coursera-verify-id-chinese-name-passport/", "title": "拿到 Google Cybersecurity 證書，卻卡在最後一關 Verify ID：身分證一直失敗，改用護照英文姓名才過", "content_text": "我考完 Google Cybersecurity Professional Certificate，最後卻被 Coursera 的 Verify ID 擋了下來——用身分證驗證時名字一直出錯、一直失敗。原因是 Coursera 是國外系統，辨識中文姓名時偶有誤判。後來改用護照（英文姓名）就順利通過。這篇把踩雷過程與解法整理給同樣卡關的你。", "content_html": "## 最後卡住我的不是考試，是 Verify ID\n\n前陣子我把 [Google Cybersecurity Professional Certificate](https://www.coursera.org/professional-certificates/google-cybersecurity) 的課程與測驗全部跑完，正式拿到證書 🎉。![alt text](<2026-06-07 at 20.11.30.png>)\n\n照理說，最難的關卡應該是那些測驗才對。結果真正讓我卡住、差點放棄的，竟然是發證前的最後一道手續——**身分驗證（Verify ID）**。\n![alt text](image.png)\n\n如果你也在考 Coursera 上的證照，最後被這關擋下來，這篇就是寫給你的。我把當時的踩雷過程跟最後怎麼解掉，完整記錄下來。\n\n## 問題：用身分證驗證，名字一直出錯、一直失敗\n\nCoursera 在你完成證照前，會要你做一次身分驗證：上傳一份有照片的證件，系統會去比對證件上的姓名跟你帳號的姓名是否一致。\n\n我一開始很直覺地拿了**身分證**去驗證。結果就是——**一直失敗**。\n\n更怪的是，驗證流程辨識出來的名字是**錯的**：跟我身分證上的中文姓名對不起來。我重試了好幾次、重拍了好幾張照片，光線、角度都調整過了，結果還是一樣卡在那裡，怎麼弄都過不了。\n\n那種「課都上完了、測驗也通過了，只差最後一步卻一直被擋」的無力感，真的滿挫折的。\n\n## 為什麼會這樣：國外系統辨識中文姓名容易出錯\n\n後來我才搞懂癥結點：**Coursera 是國外的系統，在辨識中文姓名時偶爾會出錯。**\n\n它的證件辨識（OCR）與比對流程，本來就是以拉丁字母、英文姓名為主要設計情境。換成一張全是中文字的身分證，系統要嘛讀不準、要嘛跟帳號裡的姓名格式兜不起來，比對自然就一直失敗。\n\n換句話說，問題不在你、也不在你的證件，而是**「中文姓名」這個輸入，正好踩到了國外系統不擅長的地方**。\n\n## 解法：改用護照上的英文姓名\n\n知道原因之後，解法就很直覺了——**改用護照**。\n\n護照上有你的**英文姓名**，正好是這套國外系統最吃得準的格式。我把驗證證件從身分證換成護照之後，**一次就順利通過**，證書也就跟著發下來了。\n\n所以我的建議很簡單：\n\n> **在 Coursera 做 Verify ID 時，直接用護照、以護照上的英文姓名進行認證。** 別跟身分證上的中文姓名硬碰硬。\n\n如果你的 Coursera 帳號姓名原本是中文，驗證前可以先把姓名調整成與護照一致的英文拼法，能進一步降低比對失敗的機率。\n\n## 還是卡關？直接找 Coursera Help Center\n\n如果你換了護照還是過不了，或是遇到其他**系統設定相關**的問題——例如**姓名更改、Verify ID 異常**等等——我會建議不要一個人在那邊重試到崩潰，**直接洽詢 Coursera 官方的 Help Center 取得協助**：\n\n👉 [Coursera Learner Help Center — Contact Us](https://www.coursera.support/s/learner-help-center-contact-us?language=en_US)\n\n這類帳號／驗證層級的問題，官方客服能直接從後台處理，比自己反覆嘗試有效率得多。\n\n## 小結\n\n整理一下這次的重點：\n\n- 考完 Google Cybersecurity Professional Certificate，最後一關是 **Verify ID 身分驗證**。\n- **用身分證驗證會因為中文姓名辨識而一直失敗**——這是國外系統的常見限制，不是你的錯。\n- **改用護照、以英文姓名認證**通常就能順利通過。\n- 還有姓名更改、Verify ID 等系統問題，**直接找 [Coursera Help Center](https://www.coursera.support/s/learner-help-center-contact-us?language=en_US)**。\n\n別讓最後一道手續卡住你辛苦考來的證書。希望這篇能幫你少走一段冤枉路 🙌。", "summary": "我考完 Google Cybersecurity Professional Certificate，最後卻被 Coursera 的 Verify ID 擋了下來——用身分證驗證時名字一直出錯、一直失敗。原因是 Coursera 是國外系統，辨識中文姓名時偶有誤判。後來改用護照（英文姓名）就順利通過。這篇把踩雷過程與解法整理給同樣卡關的你。", "image": "https://bobochen.dev/_astro/cover.DLVehZWm.webp", "date_published": "2026-06-07T00:00:00.000Z", "tags": [ "資安", "Coursera", "證照", "Google Cybersecurity Certificate" ] }, { "id": "https://bobochen.dev/blog/agentic-engineering-team-adoption/", "url": "https://bobochen.dev/blog/agentic-engineering-team-adoption/", "title": "把 Agentic Engineering 帶進團隊：從一個人的實驗到整個 team 的文化轉變", "content_text": "你自己用 agent 很爽，但怎麼讓整個 team 跟上？從 solo practitioner 到 team evangelist 的過程——怎麼挑第一個 pilot project、怎麼處理「AI 會取代我嗎」的焦慮、怎麼建立共享的 agent 規範。", "content_html": "> 這是「Agentic Engineering 實戰手冊」系列的第十三篇。上一篇：[Agent 安全網設計](/blog/agentic-engineering-testing-safety)\n\n## 「你能不能幫全 Team 導入？」——我以為這是好事\n\n我在公司用了六個月 agent coding，效率翻倍，bug rate 沒有上升。主管注意到了，問我：「你能不能幫全 team 都導入這套工作流？」\n\n我以為這是好事。以為只要開個 workshop、分享我的 CLAUDE.md、讓大家裝好 Claude Code，就搞定了。\n\n結果第一週，10 個人裡有 3 個完全沒碰。2 個試了一次就放棄（「它改出來的 code 不是我想要的」）。3 個有在用但每次都來問我很基礎的問題。只有 2 個真的上手了。\n\n技術從來不是問題，人才是。\n\n讓一個人用 agent 很簡單，你只需要說服自己。讓十個人都開始用，你得同時處理恐懼、習慣、標準、流程，有時候還有辦公室政治。\n\n## 為什麼 Adoption 這麼難\n\n### 不同角色的阻力來源\n\n| 角色 | 最擔心什麼 | 表面行為 |\n| ------------- | -------------------------------------- | --------------------------------------------- |\n| **Junior** | 「我還沒學會基礎，agent 就要取代我了」 | 不敢用，怕被發現自己不懂 |\n| **Mid-level** | 「我的 coding 速度是我的價值」 | 用了但不信任，手動 rewrite agent 的 code |\n| **Senior** | 「我十年的經驗能被 AI 複製？」 | 聲稱不需要，或找到一個 agent 失敗的案例後拒絕 |\n| **Manager** | 「怎麼衡量？會不會引入新風險？」 | 口頭支持但不給時間和預算 |\n\n注意這些都不是「技術問題」，每一個都是心理層面和身份認同層面的挑戰。\n\n**Junior 的焦慮**：「如果我都讓 agent 寫，我什麼時候才能自己學會？」這是合理的擔心。你可以這樣回：agent 不是取代你的練習，而是你的 [pair programming partner](/blog/agentic-engineering-mindset-shift)。你寫 test、review code、做設計決策，這些才是真正建立能力的活動。Agent 幫你省掉的是 boilerplate，不是思考。\n\n**Mid-level 的焦慮**：「我的價值就是寫 code 寫得快寫得好，agent 做得比我快怎麼辦？」這時候可以說：你的價值正在從「寫 code 的速度」轉變為「判斷什麼 code 該寫」。[Post 2](/blog/agentic-engineering-mindset-shift) 聊過這個，在 new skill tree 裡，判斷力 > 打字速度。\n\n**Senior 的焦慮**：「我的 expertise 會過時嗎？」這反而是最不需要擔心的群體，senior 的 judgment、architecture sense、domain knowledge 恰恰是 agent 最缺乏的。但 senior 通常也最固執。\n\n## 挑選 Pilot Project 的標準\n\n第一印象決定一切。選錯 pilot project，可能讓導入倒退六個月。\n\n### 好的 Pilot 特徵\n\n1. **需求明確**：有清楚的 spec 或 ticket，不需要大量 clarification\n2. **有測試覆蓋**：agent 可以用 test 自我驗證，降低出錯風險\n3. **成果可量化**：能具體比較 before/after（時間、code 品質、bug count）\n4. **風險低**：不是 critical path，搞砸了不會影響 sprint delivery\n5. **有代表性**：是團隊日常會做的任務類型，不是 edge case\n\n### 推薦的 Pilot 類型\n\n| Pilot 類型 | 為什麼好 |\n| ------------------ | ------------------------------------------------ |\n| 新的 CRUD feature | 需求明確、pattern 成熟、容易比較 |\n| Test coverage 補全 | 低風險、結果可量化（coverage %）、agent 非常擅長 |\n| Documentation 更新 | 零風險、立竿見影、所有人都討厭手動寫文件 |\n| 小型 refactor | 有 test 保護、scope 有限、容易 demo before/after |\n\n### 千萬不要選的 Pilot\n\n- Legacy codebase 的大型 migration\n- 沒有 test 覆蓋的核心功能\n- 跨團隊依賴的複雜 feature\n- 需要大量 domain knowledge 的 business logic\n\n核心原則是這樣：pilot 的目標是讓團隊對 agent 建立信心，不是展示 agent 的極限能力。\n\n## 共享 CLAUDE.md 與團隊規範\n\n從個人的 CLAUDE.md 到團隊的 CLAUDE.md，需要一個規範化的過程。\n\n### 團隊 CLAUDE.md 該有什麼\n\n```markdown\n# Team CLAUDE.md\n\n## 技術棧（必填）\n\n- 框架、語言、主要 dependency\n\n## Build & Test（必填）\n\n- 指令列表\n\n## Coding Conventions（必填）\n\n- 命名規則、檔案結構、設計模式\n\n## Agent 使用規範（團隊新增）\n\n- 哪些操作需要人工確認\n- PR 上標注 AI-generated 的規則\n- Agent-generated code 的 review 標準\n```\n\n### PR 標注規範\n\n建議的做法是讓 agent 產生的 PR 在 description 裡加上標注：\n\n```markdown\n## AI Disclosure\n\n- 🤖 This PR was primarily generated by AI agent (Claude Code)\n- 👤 Human reviewed: architecture, security, business logic\n- ✅ Verification: all existing tests pass + 3 new tests added\n```\n\n這不是「揭發」，而是透明度。讓 reviewer 知道這個 PR 需要 [特別注意的 review 重點](/blog/agent-output-verification-review)（事實性檢查、hallucination patterns）。\n\n### CLAUDE.md 的版本控制\n\n團隊的 CLAUDE.md 應該跟 code 一樣被 version control：\n\n- 修改需要 PR review\n- 重大改動需要 team 討論\n- 每個月 review 一次是否需要更新\n\n## 處理「AI 會取代我嗎」的焦慮\n\n這不是理性問題。你不能用「根據統計，AI 導入後公司裁員率沒有上升」來說服一個害怕失業的人。\n\n### Acknowledge → Reframe → Demonstrate\n\n**Step 1: Acknowledge**（承認恐懼是合理的）\n\n「我理解你的擔心。AI 的確改變了工程師的工作內容。說不擔心是假的。」\n\n不要立刻反駁。讓對方知道你理解他們的感受。\n\n**Step 2: Reframe**（重新框架問題）\n\n「Agent 不是取代你，是把你從低價值的工作中解放出來。你以前花 60% 的時間在寫 boilerplate、copy-paste、做重複的工作。Agent 做了這些，你可以把時間花在需要判斷力的事，像是架構設計、需求分析、code review。」\n\n**Step 3: Demonstrate**（用事實示範）\n\n不要用數據說服，用體驗說服。讓同事親自體驗一次「10 分鐘寫 spec → agent 自動完成」的流程。\n\n第一次體驗的 wow moment 比任何論據都有效。但前提是你要選對 demo task，找一個那位同事正在做的、痛點明確的任務來 demo，不是你精心準備的表演。\n\n### 不同層級的對話策略\n\n**對 Junior**：「Agent 是你的學習加速器。你寫 test、review code、做設計——這些才是真正的學習。Agent 幫你省掉的是打字時間。」\n\n**對 Mid-level**：「你最大的價值不是手速，是你知道什麼 code 該寫、什麼不該寫。Agent 放大了這個價值。」\n\n**對 Senior**：不要硬推。找到他們真正的痛點（通常是 code review 太多、tech debt 清不完），用那個痛點做切入。\n\n## 衡量指標：導入期該量什麼\n\n### 不要量的指標\n\n- **Code 行數 / commit 數量**——agent 很容易產生大量 code，但量 ≠ 質\n- **工時節省**——前三個月可能不降反升（學習曲線）\n\n### 建議量的指標\n\n| 指標 | 為什麼重要 | 怎麼量 |\n| ----------------------- | ------------------------------ | ---------------------------- |\n| **PR review 品質** | Agent code 是否被 review 過 | PR 有沒有 AI disclosure 標注 |\n| **Bug rate** | 品質有沒有下降 | Bug tickets per sprint |\n| **Dev satisfaction** | 團隊對新工作流的感受 | 匿名問卷（每兩週一次） |\n| **Time-to-deploy** | 從 ticket 到 production 的時間 | Jira / GitHub metrics |\n| **Agent adoption rate** | 多少人在用 | 工具使用 analytics |\n\n前三個月不要期待效率提升，學習曲線是真的。期望值應該擺在「品質沒下降 + 大家開始養成習慣」，而不是「效率翻倍」。效率翻倍是六個月後的事。\n\n## 12 週導入計畫\n\n### Phase 1（Week 1-4）：個人探索\n\n- 每個人選一個 AI coding 工具（Claude Code / Cursor / Copilot）\n- 在自己的 task 上自由使用\n- 不設標準、不給壓力\n- 每週 15 分鐘 sharing session：分享 tips 和踩過的坑\n\n**Success criteria**：50% 的團隊成員每週至少用了一次 agent\n\n### Phase 2（Week 5-8）：Pair with Agent\n\n- 每個 sprint 至少一個 task 用 agent 完成\n- Agent-generated PR 需要額外的 reviewer tag\n- 開始建立共享的 CLAUDE.md\n- 兩週一次 retrospective：什麼有用、什麼沒用\n\n**Success criteria**：團隊共識「agent 在 X 類任務上有幫助」\n\n### Phase 3（Week 9-12）：Team Standard\n\n- 正式版 team CLAUDE.md commit 進 repo\n- Agent code review 標準定義好\n- Metrics dashboard 上線\n- 結案 retrospective：go / no-go / adjust\n\n**Success criteria**：80% 的成員在日常工作中使用 agent，bug rate 沒有上升\n\n### Go / No-Go Decision\n\nPhase 3 結束後，用數據做決策：\n\n- Bug rate 上升了？→ 調整 review 流程，回到 Phase 2\n- 大家不想用？→ 調查原因，可能是工具選擇問題或 pilot 選錯\n- 效率持平但大家有正面感受？→ Go，效率會在接下來幾個月自然提升\n\n## 向上管理：怎麼 Pitch 給主管\n\n主管在乎三件事：**ROI、Risk、Timeline。**\n\n### 不要說\n\n「AI 會讓我們快 10 倍。」\n\n這種承諾只會反噬。第一個月效率可能不升反降，主管就會質疑你的判斷。\n\n### 要說\n\n「我提議做一個 12 週的 pilot。目標是在 X 類任務上驗證 agent-assisted workflow 的效果。量化指標是 [PR 品質、bug rate、time-to-deploy]。如果 12 週後指標沒改善，我們 rollback，成本可控。」\n\n重點就是低風險 + 可量化 + 有退場機制。\n\n### Shopify 的參考案例\n\nShopify CEO Tobi Lutke 在 2025 年要求團隊的一個原則值得學習：\n\n> 在要求增加人力之前，先證明 AI 做不到這件事。\n\n這不是要「用 AI 取代人」，而是把 AI 視為團隊能力的一部分。就像你不會在提案新 feature 的時候忽略 CI/CD pipeline 的效率一樣，你也不該在規劃 capacity 的時候忽略 AI agent 的能力。\n\n## Takeaway\n\n1. **團隊導入的最大挑戰是人，不是技術**：不同角色有不同的恐懼和阻力。先 acknowledge 恐懼，再用體驗（不是數據）說服。一次好的 demo 勝過十頁 slide。\n\n2. **好的 pilot project 決定第一印象**：選需求明確、有 test 覆蓋、低風險的任務。千萬不要用 legacy migration 當 demo，那是讓整個團隊對 agent 失去信心的最快方式。\n\n3. **12 週 phased rollout 比「下週一所有人開始用」有效 100 倍**：Phase 1 個人探索、Phase 2 pair with agent、Phase 3 team standard。每個 phase 有明確的 success criteria 和 go/no-go 決策點。\n\n---\n\n_上一篇：[Agent 安全網設計](/blog/agentic-engineering-testing-safety)_\n_下一篇：[Agentic Engineering 的下一步](/blog/agentic-engineering-future-and-you)_", "summary": "你自己用 agent 很爽，但怎麼讓整個 team 跟上？從 solo practitioner 到 team evangelist 的過程——怎麼挑第一個 pilot project、怎麼處理「AI 會取代我嗎」的焦慮、怎麼建立共享的 agent 規範。", "image": "https://bobochen.dev/_astro/cover.sWYCrG_m.webp", "date_published": "2026-06-05T00:00:00.000Z", "tags": [ "Agentic Engineering", "團隊管理", "AI 導入", "文化轉變", "組織" ] }, { "id": "https://bobochen.dev/blog/claude-api-guide-complete-case-study/", "url": "https://bobochen.dev/blog/claude-api-guide-complete-case-study/", "title": "完整案例：從 0 到 1 打造 AI 客服系統", "content_text": "本書的綜合實戰章——一個完整的 AI 客服系統，涵蓋 Messages API、Tool Use、Prompt Caching、Streaming、Multi-Agent、成本優化的所有核心概念整合。從架構設計到 Cloud Run 部署，用真實程式碼走完全程。", "content_html": "在結束之前，讓我們把整本書學到的東西全部用上。\n\n這一章不是玩具範例——是一個你可以真正部署的 AI 客服系統。它會用到這本書介紹過的所有核心技術：Messages API、Tool Use、Prompt Caching、Streaming、Multi-Agent 架構，以及第十三章的成本優化策略。\n\n我把這個系統叫做 **Helios**（太陽神，意味著「照亮問題」）。\n\n## 系統需求\n\nHelios 需要做這幾件事：\n\n1. **接收用戶問題**：透過 REST API 接受問題，支援 Streaming 回覆\n2. **查詢知識庫（RAG）**：在公司的知識庫中搜尋相關文件，作為回覆的依據\n3. **判斷是否需要轉人工**：某些問題（退款、投訴、技術問題）應該轉給真人處理\n4. **生成高品質回覆**：基於知識庫內容，用自然語言回覆用戶\n\n非功能性需求：\n\n- P95 延遲 < 10 秒（包含 streaming 開始前的等待）\n- 每月 API 成本 < $500（假設 1000 名日活用戶）\n- 不記錄用戶的個人資訊\n\n## 技術架構\n\n```\n用戶\n │\n ▼\nFastAPI Server (Cloud Run)\n │\n ├── 分類 Agent (Haiku) ─── 判斷問題類型\n │\n ├── 知識庫查詢工具 ─────── pgvector (Cloud SQL)\n │\n ├── 回覆 Agent (Sonnet) ── 生成回覆 + Streaming\n │\n └── 升級工具 ───────────── Zendesk API (建立工單)\n\nRedis ─── 對話歷史快取（TTL: 1 小時）\n```\n\n**技術選擇說明：**\n\n- **FastAPI**：Python 非同步框架，原生支援 async/await，搭配 Anthropic SDK 的 streaming 最方便\n- **pgvector**：PostgreSQL 的向量搜尋擴充，不需要另外建立 Pinecone/Weaviate 等獨立服務，維護成本低\n- **Redis**：對話歷史的暫存，TTL 設 1 小時，超過就重置\n- **Cloud Run**：無伺服器容器部署，只有請求時才消耗資源，成本低\n\n## 資料流設計\n\n一個用戶問題的完整旅程：\n\n```\n1. 用戶 POST /chat {\"session_id\": \"xxx\", \"message\": \"我的訂單什麼時候到？\"}\n ↓\n2. 從 Redis 讀取對話歷史\n ↓\n3. 分類 Agent（Haiku）判斷：\n - 問題類型（訂單查詢 / 退款 / 技術問題 / 一般諮詢）\n - 是否需要轉人工（高風險問題）\n ↓\n4a. 如果需要轉人工 → 建立 Zendesk 工單 → 回覆「已為您轉接專員」\n4b. 如果不需要轉人工 → 繼續步驟 5\n ↓\n5. 回覆 Agent（Sonnet）：\n - 呼叫知識庫搜尋工具\n - 根據搜尋結果生成回覆\n - Streaming 回覆給用戶\n ↓\n6. 把這輪對話加入 Redis（對話歷史）\n```\n\n## 環境設定\n\n```bash\n# 建立 Poetry 專案\npoetry new helios-support\ncd helios-support\n\n# 安裝依賴\npoetry add anthropic fastapi uvicorn redis psycopg2-binary pgvector\npoetry add python-dotenv pydantic\n\n# .env\nANTHROPIC_API_KEY=sk-ant-api03-xxx\nREDIS_URL=redis://localhost:6379\nDATABASE_URL=postgresql://user:pass@localhost:5432/helios\nZENDESK_SUBDOMAIN=yourcompany\nZENDESK_EMAIL=support@yourcompany.com\nZENDESK_API_TOKEN=xxx\n```\n\n## 知識庫（RAG 層）\n\n首先建立知識庫的資料存取層：\n\n```python\n# helios/knowledge_base.py\nimport psycopg2\nfrom pgvector.psycopg2 import register_vector\nimport anthropic\nimport os\nfrom dataclasses import dataclass\n\nclient = anthropic.Anthropic()\n\n@dataclass\nclass Document:\n id: str\n title: str\n content: str\n similarity: float\n\ndef embed_text(text: str) -> list[float]:\n \"\"\"使用 Anthropic 的 embedding API 把文字轉成向量\"\"\"\n # 注意：Anthropic 目前沒有自己的 embedding model\n # 建議使用 OpenAI text-embedding-3-small 或 Google text-embedding-004\n # 這裡假設你已經設定好 embedding function\n # 使用你偏好的 embedding service\n raise NotImplementedError(\"請替換成你的 embedding service\")\n\ndef search_knowledge_base(\n query: str,\n limit: int = 3,\n similarity_threshold: float = 0.7\n) -> list[Document]:\n \"\"\"在知識庫中搜尋相關文件\"\"\"\n query_vector = embed_text(query)\n\n conn = psycopg2.connect(os.environ[\"DATABASE_URL\"])\n register_vector(conn)\n\n try:\n with conn.cursor() as cur:\n cur.execute(\"\"\"\n SELECT id, title, content,\n 1 - (embedding <=> %s::vector) AS similarity\n FROM knowledge_base\n WHERE 1 - (embedding <=> %s::vector) > %s\n ORDER BY similarity DESC\n LIMIT %s\n \"\"\", (query_vector, query_vector, similarity_threshold, limit))\n\n rows = cur.fetchall()\n return [\n Document(id=row[0], title=row[1], content=row[2], similarity=row[3])\n for row in rows\n ]\n finally:\n conn.close()\n```\n\n## 工具定義\n\n接下來定義 Agent 可以呼叫的工具：\n\n```python\n# helios/tools.py\nimport anthropic\nimport requests\nimport json\nimport os\nfrom .knowledge_base import search_knowledge_base\n\n# 工具定義（傳給 Anthropic API 的 tools 參數）\nSUPPORT_TOOLS = [\n {\n \"name\": \"search_knowledge_base\",\n \"description\": \"\"\"搜尋公司知識庫，找到跟用戶問題相關的文件。\n 在回覆任何問題之前，應該先用這個工具搜尋相關資訊。\n 如果找不到相關資訊，誠實告訴用戶你不知道，不要猜測。\"\"\",\n \"input_schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"query\": {\n \"type\": \"string\",\n \"description\": \"搜尋查詢詞，應該是描述問題的關鍵詞\"\n }\n },\n \"required\": [\"query\"]\n }\n },\n {\n \"name\": \"escalate_to_human\",\n \"description\": \"\"\"把用戶的問題升級給真人客服專員處理。\n 在以下情況應該使用這個工具：\n - 用戶要求退款\n - 用戶表達強烈不滿或憤怒\n - 涉及帳號安全問題\n - 問題超出你的知識範疇，用戶急需解決\"\"\",\n \"input_schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"reason\": {\n \"type\": \"string\",\n \"description\": \"升級原因的簡短說明（給客服專員看的，不是給用戶看的）\"\n },\n \"urgency\": {\n \"type\": \"string\",\n \"enum\": [\"low\", \"medium\", \"high\"],\n \"description\": \"緊急程度\"\n }\n },\n \"required\": [\"reason\", \"urgency\"]\n }\n }\n]\n\ndef execute_tool(tool_name: str, tool_input: dict) -> str:\n \"\"\"執行工具並回傳結果\"\"\"\n if tool_name == \"search_knowledge_base\":\n docs = search_knowledge_base(tool_input[\"query\"])\n if not docs:\n return \"知識庫中找不到相關資訊。\"\n\n results = []\n for doc in docs:\n results.append(f\"## {doc.title}\\n{doc.content[:500]}\")\n return \"\\n\\n\".join(results)\n\n elif tool_name == \"escalate_to_human\":\n ticket_id = create_zendesk_ticket(\n reason=tool_input[\"reason\"],\n urgency=tool_input[\"urgency\"]\n )\n return json.dumps({\n \"escalated\": True,\n \"ticket_id\": ticket_id,\n \"message\": f\"已建立工單 #{ticket_id}，專員將在 24 小時內與您聯繫\"\n })\n\n return f\"ERROR: 未知工具 {tool_name}\"\n\ndef create_zendesk_ticket(reason: str, urgency: str) -> str:\n \"\"\"建立 Zendesk 工單（簡化版）\"\"\"\n url = f\"https://{os.environ['ZENDESK_SUBDOMAIN']}.zendesk.com/api/v2/tickets.json\"\n auth = (\n f\"{os.environ['ZENDESK_EMAIL']}/token\",\n os.environ[\"ZENDESK_API_TOKEN\"]\n )\n\n priority_map = {\"low\": \"low\", \"medium\": \"normal\", \"high\": \"urgent\"}\n\n response = requests.post(url, auth=auth, json={\n \"ticket\": {\n \"subject\": \"AI 客服升級\",\n \"comment\": {\"body\": f\"升級原因：{reason}\"},\n \"priority\": priority_map.get(urgency, \"normal\"),\n \"tags\": [\"ai-escalated\"]\n }\n })\n\n if response.ok:\n return str(response.json()[\"ticket\"][\"id\"])\n return \"UNKNOWN\"\n```\n\n## 對話管理\n\n```python\n# helios/conversation.py\nimport redis\nimport json\nimport os\nfrom datetime import timedelta\n\nredis_client = redis.from_url(os.environ[\"REDIS_URL\"])\nSESSION_TTL = timedelta(hours=1)\n\ndef get_conversation_history(session_id: str) -> list[dict]:\n \"\"\"從 Redis 讀取對話歷史\"\"\"\n data = redis_client.get(f\"session:{session_id}\")\n if data:\n return json.loads(data)\n return []\n\ndef save_conversation_history(session_id: str, messages: list[dict]):\n \"\"\"把對話歷史存到 Redis\"\"\"\n redis_client.setex(\n f\"session:{session_id}\",\n SESSION_TTL,\n json.dumps(messages, ensure_ascii=False)\n )\n\ndef build_messages_with_cache(\n history: list[dict],\n new_message: str\n) -> list[dict]:\n \"\"\"建立帶有 Prompt Caching 標記的訊息列表\"\"\"\n messages = history.copy()\n\n # 如果歷史超過 6 輪，截斷最舊的\n if len(messages) > 12: # 6 輪 = 12 條訊息\n messages = messages[-12:]\n\n # 對倒數第二條訊息（最新的 assistant 訊息）加快取標記\n for i in range(len(messages) - 1, -1, -1):\n if messages[i][\"role\"] == \"assistant\":\n msg = messages[i].copy()\n content = msg[\"content\"]\n if isinstance(content, str):\n msg[\"content\"] = [\n {\n \"type\": \"text\",\n \"text\": content,\n \"cache_control\": {\"type\": \"ephemeral\"}\n }\n ]\n messages[i] = msg\n break\n\n messages.append({\"role\": \"user\", \"content\": new_message})\n return messages\n```\n\n## 核心 Agent 邏輯\n\n```python\n# helios/agent.py\nimport anthropic\nfrom typing import AsyncIterator\nfrom .tools import SUPPORT_TOOLS, execute_tool\nfrom .conversation import (\n get_conversation_history,\n save_conversation_history,\n build_messages_with_cache\n)\n\nclient = anthropic.Anthropic()\n\n# 大型知識庫摘要（幾千 tokens，固定內容，適合快取）\nCOMPANY_CONTEXT = \"\"\"\n你是 Helios 電商平台的 AI 客服助手。\n\n關於我們的服務：\n- 商品交貨時間：標準配送 3-5 個工作天，快速配送 1-2 個工作天\n- 退貨政策：收到商品 7 天內可申請退貨，商品需保持原狀\n- 退款時間：申請通過後 5-10 個工作天退款到原付款方式\n- 客服時間：週一到週五 9:00-18:00\n\n常見問題處理準則：\n[更多公司政策內容...]\n\"\"\"\n\nSYSTEM_PROMPT_BASE = \"\"\"你是 Helios 電商平台的 AI 客服助手，名字叫 Helios。\n\n你的職責：\n1. 用友善、專業的態度回應用戶問題\n2. 在回覆前，用 search_knowledge_base 工具查詢相關資訊\n3. 只根據知識庫中的資訊回覆，不要猜測或編造\n4. 遇到退款、投訴、帳號安全問題，主動使用 escalate_to_human 工具\n\n回覆風格：\n- 簡潔清晰，避免廢話\n- 中文回覆，但保留必要的技術術語\n- 如果不知道答案，誠實說明並提供升級選項\n\"\"\"\n\nasync def stream_support_response(\n session_id: str,\n user_message: str\n) -> AsyncIterator[str]:\n \"\"\"\n 處理用戶問題，Streaming 回覆。\n 這個 generator 會 yield 回覆的文字片段。\n \"\"\"\n # 讀取對話歷史\n history = get_conversation_history(session_id)\n messages = build_messages_with_cache(history, user_message)\n\n # Agent 的 agentic loop\n current_messages = messages.copy()\n final_response_parts = []\n assistant_message_content = []\n\n while True:\n # 呼叫 API（使用 streaming）\n with client.messages.stream(\n model=\"claude-3-5-sonnet-20241022\",\n max_tokens=1024,\n system=[\n {\n \"type\": \"text\",\n \"text\": SYSTEM_PROMPT_BASE,\n },\n {\n \"type\": \"text\",\n \"text\": COMPANY_CONTEXT,\n \"cache_control\": {\"type\": \"ephemeral\"} # 快取公司資訊\n }\n ],\n tools=SUPPORT_TOOLS,\n messages=current_messages,\n ) as stream:\n\n current_tool_calls = []\n current_text = \"\"\n\n for event in stream:\n if hasattr(event, 'type'):\n if event.type == 'content_block_start':\n if hasattr(event.content_block, 'type'):\n if event.content_block.type == 'text':\n pass # 準備收文字\n elif event.content_block.type == 'tool_use':\n current_tool_calls.append({\n \"id\": event.content_block.id,\n \"name\": event.content_block.name,\n \"input\": \"\"\n })\n\n elif event.type == 'content_block_delta':\n if hasattr(event.delta, 'text'):\n # 文字片段：直接 yield 給用戶\n text_chunk = event.delta.text\n current_text += text_chunk\n final_response_parts.append(text_chunk)\n yield text_chunk\n\n elif hasattr(event.delta, 'partial_json'):\n # 工具呼叫的參數（累積）\n if current_tool_calls:\n current_tool_calls[-1][\"input\"] += event.delta.partial_json\n\n # 取得完整的 response\n final_response = stream.get_final_message()\n\n # 檢查 stop_reason\n if final_response.stop_reason == \"end_turn\":\n # 完成！把這輪對話加入歷史\n assistant_content = []\n if current_text:\n assistant_content.append({\"type\": \"text\", \"text\": current_text})\n\n current_messages.append({\n \"role\": \"assistant\",\n \"content\": assistant_content if assistant_content else \"好的。\"\n })\n\n # 儲存更新後的對話歷史\n save_conversation_history(session_id, current_messages)\n return\n\n elif final_response.stop_reason == \"tool_use\":\n # 需要執行工具\n tool_results = []\n\n for content_block in final_response.content:\n if content_block.type == \"tool_use\":\n tool_name = content_block.name\n tool_input = content_block.input\n\n # 執行工具\n result = execute_tool(tool_name, tool_input)\n\n tool_results.append({\n \"type\": \"tool_result\",\n \"tool_use_id\": content_block.id,\n \"content\": result\n })\n\n # 如果是升級工具，向用戶發送通知\n if tool_name == \"escalate_to_human\":\n import json\n result_data = json.loads(result)\n yield f\"\\n\\n我已經為您建立工單（#{result_data['ticket_id']}），我們的專員將盡快與您聯繫。\"\n\n # 把工具呼叫和結果加入訊息\n current_messages.append({\n \"role\": \"assistant\",\n \"content\": final_response.content\n })\n current_messages.append({\n \"role\": \"user\",\n \"content\": tool_results\n })\n # 繼續 loop，讓 agent 根據工具結果繼續生成回覆\n\n else:\n # max_tokens 或其他停止原因\n yield \"\\n\\n（回覆已截斷，請繼續詢問）\"\n return\n```\n\n## FastAPI Server\n\n```python\n# helios/main.py\nfrom fastapi import FastAPI, HTTPException\nfrom fastapi.responses import StreamingResponse\nfrom pydantic import BaseModel\nimport uvicorn\nimport logging\n\nfrom .agent import stream_support_response\n\napp = FastAPI(title=\"Helios AI Support\")\nlogger = logging.getLogger(__name__)\n\nclass ChatRequest(BaseModel):\n session_id: str\n message: str\n\n class Config:\n # 限制輸入長度，防止超長輸入\n max_anystr_length = 2000\n\n@app.post(\"/chat\")\nasync def chat(request: ChatRequest):\n \"\"\"接受用戶問題，返回 Streaming 回覆\"\"\"\n\n # 基本輸入驗證\n if len(request.message.strip()) < 2:\n raise HTTPException(status_code=400, detail=\"問題太短，請重新輸入\")\n\n if len(request.session_id) > 100:\n raise HTTPException(status_code=400, detail=\"無效的 session ID\")\n\n async def generate():\n try:\n async for chunk in stream_support_response(\n session_id=request.session_id,\n user_message=request.message\n ):\n # SSE 格式\n yield f\"data: {chunk}\\n\\n\"\n yield \"data: [DONE]\\n\\n\"\n\n except Exception as e:\n logger.exception(f\"Error in chat stream: {e}\")\n yield f\"data: 抱歉，發生了技術問題，請稍後再試。\\n\\n\"\n yield \"data: [DONE]\\n\\n\"\n\n return StreamingResponse(\n generate(),\n media_type=\"text/event-stream\",\n headers={\n \"Cache-Control\": \"no-cache\",\n \"X-Accel-Buffering\": \"no\", # 禁用 Nginx 緩衝，確保 streaming 正常\n }\n )\n\n@app.get(\"/health\")\nasync def health_check():\n \"\"\"健康檢查 endpoint\"\"\"\n return {\"status\": \"ok\"}\n\nif __name__ == \"__main__\":\n uvicorn.run(app, host=\"0.0.0.0\", port=8080)\n```\n\n## 成本追蹤整合\n\n把第十三章的成本追蹤整合進來：\n\n```python\n# helios/metrics.py\nimport time\nimport logging\nfrom dataclasses import dataclass\n\nlogger = logging.getLogger(__name__)\n\n@dataclass\nclass RequestMetrics:\n session_id: str\n model: str\n input_tokens: int = 0\n output_tokens: int = 0\n cache_read_tokens: int = 0\n cache_creation_tokens: int = 0\n tool_calls: int = 0\n escalated: bool = False\n latency_ms: float = 0.0\n\n def log(self):\n # 計算成本\n input_cost = self.input_tokens * 3.0 / 1_000_000\n output_cost = self.output_tokens * 15.0 / 1_000_000\n cache_read_cost = self.cache_read_tokens * 0.30 / 1_000_000\n total_cost = input_cost + output_cost + cache_read_cost\n\n cache_hit_rate = (\n self.cache_read_tokens / max(self.input_tokens, 1) * 100\n )\n\n logger.info(\"request_completed\", extra={\n \"session_id\": self.session_id[:8] + \"...\", # 截斷，避免洩漏\n \"model\": self.model,\n \"input_tokens\": self.input_tokens,\n \"output_tokens\": self.output_tokens,\n \"cache_read_tokens\": self.cache_read_tokens,\n \"cache_hit_rate_pct\": round(cache_hit_rate, 1),\n \"tool_calls\": self.tool_calls,\n \"escalated\": self.escalated,\n \"latency_ms\": round(self.latency_ms),\n \"estimated_cost_usd\": round(total_cost, 6),\n })\n```\n\n## 部署到 Cloud Run\n\n**Dockerfile：**\n\n```dockerfile\nFROM python:3.12-slim\n\nWORKDIR /app\n\nCOPY pyproject.toml poetry.lock ./\nRUN pip install poetry && poetry install --no-dev\n\nCOPY helios/ ./helios/\n\nEXPOSE 8080\nCMD [\"poetry\", \"run\", \"uvicorn\", \"helios.main:app\", \"--host\", \"0.0.0.0\", \"--port\", \"8080\"]\n```\n\n**部署指令：**\n\n```bash\n# Build 和 Push 到 Google Container Registry\ngcloud builds submit --tag gcr.io/YOUR_PROJECT/helios-support\n\n# 部署到 Cloud Run\ngcloud run deploy helios-support \\\n --image gcr.io/YOUR_PROJECT/helios-support \\\n --platform managed \\\n --region asia-east1 \\\n --memory 512Mi \\\n --concurrency 80 \\\n --set-secrets \"ANTHROPIC_API_KEY=anthropic-api-key:latest\" \\\n --set-env-vars \"REDIS_URL=redis://10.x.x.x:6379\" \\\n --set-env-vars \"DATABASE_URL=postgresql://user:pass@10.x.x.x/helios\" \\\n --allow-unauthenticated\n```\n\n幾個 Cloud Run 的注意事項：\n\n`--concurrency 80` 代表每個 Cloud Run instance 同時處理 80 個請求。AI streaming 請求會長時間佔用連線，這個值可以根據你的實際情況調整。\n\nSecrets（API Key、資料庫密碼）用 Google Secret Manager 管理，透過 `--set-secrets` 注入，不要放在環境變數裡直接傳。\n\n## 成本估算\n\n這個系統在 1000 名日活用戶、每人平均 5 個問題的情況下：\n\n每天請求數：5,000\n每次請求的 token 估算：\n\n- Input（含 COMPANY_CONTEXT）：~3,000 tokens，其中 ~2,500 可以快取\n- Output：~300 tokens\n- 快取命中後，有效輸入成本：(500 × $3 + 2500 × $0.30) / 1,000,000 = $0.00225 / 請求\n\n每天成本：5,000 × ($0.00225 + 300 × $15/1,000,000) = $11.25 + $22.50 = **$33.75/天**\n\n每月成本：**~$1,000/月**\n\n這比第十三章的目標 $500/月 高一點。要進一步降低，可以：\n\n1. 把分類用的 Haiku 做 routing，簡單問題完全用 Haiku 回答（降至 ~$600）\n2. 提高快取命中率（確保 5 分鐘內有足夠的請求維持快取熱度）\n\n## 這本書的旅程\n\n你剛讀完了「Claude API & Agent SDK 完全指南」的最後一章。\n\n我想用幾段話回顧一下我們走過的路程。\n\n這本書是 Claude 三部曲的第三本。第一本（Claude 使用指南）告訴你怎麼跟 Claude 對話。第二本（Claude Code 完全指南）告訴你怎麼讓 AI 幫你寫程式碼。這本書——第三本——告訴你怎麼**用 Claude 建造東西**：真正的應用、真正的系統、真正可以服務用戶的產品。\n\n從第一章的第一個 `client.messages.create()` 呼叫，到這一章的多 agent、streaming、RAG 整合系統——中間走了很長的路。\n\n如果你真的把這本書的範例都跑過了，你現在應該能做這些事：\n\n- 用 Messages API 建立任何對話型應用\n- 用 Tool Use 讓 AI 操控外部系統\n- 用 Prompt Caching 把成本降到最低\n- 用 Streaming 讓用戶體驗更流暢\n- 用 Agent SDK 建立多 agent 協作系統\n- 開發自己的 MCP Server\n- 把這一切部署到生產環境，並且知道怎麼監控和維護\n\n**接下來呢？**\n\nAI 應用開發這個領域正在高速演進。Anthropic 每隔幾個月就會推出新功能——更好的模型、更低的成本、更強的 agent 能力。我的建議是：\n\n**建立一個真實的東西**。不要停在讀書和做練習。找一個你真正有需求的問題，用你在這本書學到的技術解決它。你在解決真實問題的過程中學到的東西，遠比讀任何書都多。\n\n**關注官方文件**。Anthropic 的 [docs.anthropic.com](https://docs.anthropic.com) 是最可靠的資訊來源，這本書的範例和定價資訊可能因版本更新而改變，但官方文件永遠是最新的。\n\n**加入社群**。Anthropic 的 Discord、各種 AI 開發者社群——這些地方有很多正在解決和你類似問題的開發者。\n\n最後，我想說：\n\n我花了很多時間在這三本書裡，試著把「如何真正用好 Claude」說清楚——不是表面的功能介紹，而是讓你能真正建造東西的深度知識。寫作的過程其實也是我重新整理自己理解的過程。\n\n如果這本書對你有幫助，最好的感謝方式，就是去建造一個真實的東西。\n\n祝你的 AI 應用上線順利。\n\n—— Bobo", "summary": "本書的綜合實戰章——一個完整的 AI 客服系統，涵蓋 Messages API、Tool Use、Prompt Caching、Streaming、Multi-Agent、成本優化的所有核心概念整合。從架構設計到 Cloud Run 部署，用真實程式碼走完全程。", "image": "https://bobochen.dev/_astro/cover.BBK6Nb2w.webp", "date_published": "2026-06-05T00:00:00.000Z", "tags": [ "Claude API", "完整案例", "AI 客服", "系統設計" ] }, { "id": "https://bobochen.dev/blog/enterprise-ai-agent-leading-small-ai-team/", "url": "https://bobochen.dev/blog/enterprise-ai-agent-leading-small-ai-team/", "title": "帶領一支 3–8 人的 AI 工程小隊：成功的關鍵不是追最新框架", "content_text": "一支小型 AI 工程團隊的成敗，不在於用了多潮的 framework，而在於有沒有建立一個可重複的 delivery loop。談 architecture/code/prompt/eval review 怎麼做、怎麼把 AI agent 的能力翻譯成 business stakeholder 聽得懂的 workflow impact 和 ROI、以及怎麼讓團隊在一個變化極快的領域裡持續交付。系列完結篇。", "content_html": "import DeckEmbed from '../../../components/blog/DeckEmbed.astro';\nexport const deckSlides = Object.entries(import.meta.glob('./slides/*.webp', { eager: true, import: 'default' })).sort(([a], [b]) => a.localeCompare(b)).map(([, m]) => m);\n\n> 這是「從 PoC 到 Production：企業 AI Agent 系統工程」系列第 12 篇，也是**完結篇**（共 12 篇）。上一篇：[Agent 治理框架](/blog/enterprise-ai-agent-governance-framework)。\n\n前面十一篇都在講系統。最後一篇回到人。因為「把上面那整套東西做出來、而且持續維護下去」，從來不是一個人的事，是一支團隊的事。如果你要帶一支 3–8 人的 AI 工程小隊，這篇是我認為最重要的幾件事。\n\n先講一個反直覺的結論：\n\n> 在一個變化快到每週都有新 framework 的領域裡，小團隊成功的關鍵，**恰恰不是**追最新的框架，而是建立一個**可重複的 delivery loop**。\n\n## 為什麼「追新」是小團隊的陷阱\n\nAI 這個領域，每週都有新模型、新 framework、新「這個會改變一切」的工具。對一個小團隊，這是甜蜜的毒藥：\n\n- 每換一次 framework，前面累積的 know-how 和工具就打掉一些。\n- 團隊的精力被「學新東西」吃掉，而不是「交付價值」。\n- 你永遠在起跑線上，永遠沒有把一個東西做到 production-grade。\n\n給個我自己用的粗略門檻：一個新 framework 要值得你打掉重練，它得能把你某個 delivery loop 環節的工作量砍掉一半以上、而且維護不用你自己扛——只是「換個寫法更優雅」不夠。LangChain 從 0.0.x 一路改到 1.0，多少團隊的 chain 寫法跟著翻修了好幾輪；同一段時間，「黃金題庫過了才能上」這條紀律一行都沒變。\n\n我這一年大量用 agentic 的方式工作，最深的體會是：**工具會一直換，但把一個 agent 從 demo 推到能信任的那套工程紀律（這整個系列講的東西）是不太變的**。一個好的 AI 工程 leader，要幫團隊**守住不變的那部分**——RAG 的品質、eval 的紀律、權限的嚴謹、可觀測性——而不是追著每個新玩具跑。框架是手段，能不能穩定交付可信任的系統才是目的。\n\n2026 回頭看更明顯：這一年真正沉澱下來、跨工具通用的，是**介面和紀律**，不是某個 framework。MCP 變成大家接 tool 的共同語言（也是為什麼我會去寫 MCP server，第 6 篇）、eval 從「加分項」變成 CI 裡的固定關卡、tracing 從各家自掃門前雪到 OpenTelemetry 的 GenAI conventions 開始有共通標準。這些你學一次、換不換 framework 都帶得走；某個「這個月最潮」的 agent SDK，你學了三個月可能就沒人維護了。\n\n## 建立可重複的 Delivery Loop\n\n「可重複」是關鍵字。一個健康的 AI 工程團隊，應該有一套**每個專案都照著走的循環**，而不是每次都重新發明：\n\n```\n需求 → 設計（架構/安全 review）→ 建黃金題庫 → 實作\n → eval 跑回歸 → 上線 → 觀測 → 用線上訊號回頭補題庫 → …\n```\n\n這個 loop 把前面各篇變成團隊的肌肉記憶：第 2 篇的架構、第 5/11 篇的權限與治理、第 9 篇的 eval 與觀測，都不是某個人臨時想起來才做，而是**流程裡的固定關卡**。新人加入，照著 loop 走就不會漏掉關鍵的工程紀律。這比任何 framework 都值錢。\n\n## 四種 Review，缺一不可\n\n傳統團隊有 code review。AI 工程團隊需要的 review 更多，因為「能出錯的地方」更多：\n\n- **Architecture review**：新功能上之前，先過一次架構——這個 agent 的權限邊界對不對？工具會不會給太多？走 RAG 還是 fine-tune？放哪個三角的角（第 10 篇）？在還沒寫 code 前就把方向定對，比寫完再改便宜太多。\n- **Code review**：照舊。AI 寫的 code 也是 code，一樣要審。\n- **Prompt review**：prompt 是這個系統的「邏輯」，改一句可能行為大變。它該像 code 一樣被版本控制、被 review——具體一點：prompt 進 git、改動走 PR，而且 PR 裡**附上這次的 eval diff**（不是「我覺得這版更好」，是「通過率從 87% 到 91%，但這三題退步了」）。沒有 eval 數字的 prompt PR，跟沒有測試的 code PR 一樣不該過。\n- **Eval review**：最容易被忽略、卻最重要的一種。黃金題庫（第 9 篇）夠不夠涵蓋？通過率掉了大家有沒有當一回事？**團隊要建立一個文化：eval 沒過，跟測試沒過一樣，不能上**。\n\n把這四種 review 變成習慣，團隊產出的就不是「跑得動的 demo」，是「敢上 production 的系統」。\n\n## 最被低估的能力：把 AI 翻譯成業務語言\n\n這是 technical lead 和純 IC 最大的差別，也是 JD 上「跟 business stakeholder 溝通」真正的意思。\n\n業務主管不在乎你用了 multi-agent 還是 RAG、reranking 調了什麼參數。他們在乎的是：\n\n- 這東西能幫我們**省多少時間 / 多少人力**？（workflow impact）\n- 它出錯的**風險**有多大、你怎麼控制？（risk control）\n- 投入這些工程，**回報**是什麼？（ROI）\n\n一個只會講技術的 AI 團隊，很難拿到資源和信任。你要能把第 11 篇的治理講成「我們怎麼確保它不會洩漏客戶資料」，把第 9 篇的 eval 講成「我們怎麼知道它的品質有沒有掉」，把第 10 篇的成本講成「每個月大概這個數，而它省下的人力是這個數」。\n\n**把工程語言翻譯成業務價值，是讓 AI 專案活下去的氧氣。** 做不到這件事的團隊，做得再好也常常拿不到下一輪資源。\n\n舉個翻譯的範例感受一下落差。技術版：「我們把 reranking 換成 cross-encoder，top-5 命中率上升、p95 latency 控制在兩秒內。」業務版：「客服 agent 第一次就答對的比例從六成拉到八成五，每天攔下大約三百通本來要轉真人的詢問，模型成本一個月小幾萬、省下的客服工時遠大於這個數。」——同一件事，後者才換得到下一輪預算。重點不是把數字講大，是把它放進主管的損益表裡。\n\n## 在不確定裡帶人\n\n最後，AI 工程有個特別的領導挑戰：**這個領域本身充滿不確定**。模型會被供應商偷偷改、某個做法下個月可能就過時、沒有人是「專家」因為大家都在同一條起跑線附近。\n\n其中「模型被供應商偷偷改」這件事，不只是領導氛圍問題，是 production 風險：同一個 model 名稱、同一段 prompt，供應商一次安靜的更新就可能讓行為飄掉——這正是第 1 篇講的，你有一個不能控制、也不會收到 changelog 的上游依賴。對小隊的紀律是兩條：版本能 pin 就 pin（別只寫 `latest`），以及讓黃金題庫**定期重跑**而不是只在改 code 時跑——這樣模型悄悄變了，是你的 eval 先尖叫，而不是客戶先尖叫。\n\n帶這樣的團隊，我覺得幾件事重要：\n\n- **建立心理安全感**：在一個沒有標準答案的領域，要讓團隊敢說「我不確定」、敢做實驗、敢承認某條路走不通。eval 和 observability（第 9 篇）在這裡有個額外好處——它們讓「對或錯」有**數據**可依，而不是靠誰嗓門大，這本身就降低了團隊的焦慮。\n- **知識共享是團隊資產**：一個人踩過的坑、調出來的好 prompt、學到的新工具，要有機制讓它變成團隊的，而不是鎖在某個人腦裡。寫下來、分享出來——這也是我自己一直在做的事（這整個系列就是）。\n- **postmortem 不咎責**：agent 出包了，重點是「系統哪裡讓這個錯誤溜過去了、怎麼補上防線（補進黃金題庫、加個 HITL 關卡）」，而不是「誰的 prompt 寫爛了」。判斷一場 postmortem 有沒有做對，看它的產出物：每一次線上出包，至少要長出**一條新的黃金題庫**或**一道新的關卡**——讓同一個錯誤下次過不了。沒長出防線的檢討，只是一場集體嘆氣。\n\n## 回到第 1 篇：六道鴻溝，其實是一支團隊的事\n\n這個系列從「為什麼企業 AI Agent 卡在 PoC」開始，講了六道鴻溝：正確性、eval、可觀測性、權限治理、成本延遲、fallback。\n\n走到最後一篇你會發現，**過這六道鴻溝，從來不是一個技術問題，是一個團隊能不能建立起對應紀律的問題**。\n\n- 正確性與權限 → 是不是有 architecture / eval review 把關？\n- Eval 與可觀測性 → 是不是有「沒過不能上」的文化？\n- 成本與治理 → 是不是有人能把它翻譯成業務聽得懂的價值，換到持續投入的資源？\n\n技術會給你過河的工具，但真正把一個企業 AI agent 從 demo 推到 production、而且**持續維護下去**的，是一支有紀律、能溝通、在不確定裡還能穩定交付的團隊——以及帶著他們的那個人。\n\n如果你正在或即將做這件事，希望這 12 篇，能幫你把「能 demo」和「能信任」之間那段最難的路，走得踏實一點。\n\n\n## 文章簡報\n\n\n\n---\n\n### 延伸閱讀\n\n- 上一篇：[Agent 治理框架](/blog/enterprise-ai-agent-governance-framework)\n- 系列起點：[為什麼企業 AI Agent 卡在 PoC？六道鴻溝](/blog/enterprise-ai-agent-poc-to-production-gap)\n- [Agentic Engineering 實戰手冊](/blog/agentic-engineering-what-is-it)——換個角度：用 agent 來做工程，而不是打造 agent 系統\n- [Agentic Engineering：團隊導入](/blog/agentic-engineering-team-adoption)——把 agent 工作流導入一支團隊的實戰", "summary": "一支小型 AI 工程團隊的成敗，不在於用了多潮的 framework，而在於有沒有建立一個可重複的 delivery loop。談 architecture/code/prompt/eval review 怎麼做、怎麼把 AI agent 的能力翻譯成 business stakeholder 聽得懂的 workflow impact 和 ROI、以及怎麼讓團隊在一個變化極快的領域裡持續交付。系列完結篇。", "image": "https://bobochen.dev/_astro/cover.DLS1_LLx.webp", "date_published": "2026-06-04T00:00:00.000Z", "date_modified": "2026-06-05T00:00:00.000Z", "tags": [ "技術領導", "團隊管理", "AI 工程", "職涯", "跨部門溝通" ] }, { "id": "https://bobochen.dev/blog/tailscale-spof-self-hosted-alternatives-headscale-netbird-nebula/", "url": "https://bobochen.dev/blog/tailscale-spof-self-hosted-alternatives-headscale-netbird-nebula/", "title": "Tailscale 好用到讓我焦慮：它會變成我的 SPOF 嗎？5 種備援方案全解", "content_text": "Tailscale 好用到不真實，但把整張網路綁在一個閉源控制面上，總讓人半夜睡不著。先講個反直覺的真相：你怕的那種 SPOF 其實不太會發生。從「其實不用搬」到 headscale、NetBird、Nebula、純 WireGuard，5 種備援方案一次說清楚怎麼選。", "content_html": "import DeckEmbed from '../../../components/blog/DeckEmbed.astro';\nexport const deckSlides = Object.entries(import.meta.glob('./slides/*.webp', { eager: true, import: 'default' })).sort(([a], [b]) => a.localeCompare(b)).map(([, m]) => m);\nimport figureA from './figure-a-control-vs-data-plane.svg?url';\nimport figureB from './figure-b-solution-map.svg?url';\nimport figDevices from './images/tailscale-admin-devices.webp?url';\nimport figStatus from './images/tailscale-status-cli.webp?url';\n\n事情是這樣開始的。\n\n我把家裡的 NAS、雲端的兩台 VPS、工作的 Mac、口袋裡的手機，全部接上了 Tailscale。一行 `tailscale up`，從此不管人在咖啡廳還是高鐵上，連回家裡的服務就像在同一個區網一樣順。NAT 穿透、金鑰交換、防火牆規則，全都不用管。它好用到一種……有點不真實的程度。\n\n{/* TODO 截圖：Tailscale 後台裝置列表（NAS / 2 台 VPS / Mac / 手機都 connected）。截好後直接覆蓋 images/tailscale-admin-devices.webp，不用改這裡。記得打碼 hostname 與帳號 email。 */}\n
\n \"Tailscale\n
我的 Tailnet 裝置列表：NAS、兩台 VPS、Mac、手機，全接在同一張網路上。
\n
\n\n{/* TODO 截圖：`tailscale status` 終端輸出，看得到 100.x.x.x 那串 IP 與 direct/relay 欄位。截好後直接覆蓋 images/tailscale-status-cli.webp，不用改這裡。記得打碼公網 IP。 */}\n
\n \"終端機執行\n
tailscale status 的輸出——就是這串 100.x.x.x，半夜讓我盯著發呆的元兇。
\n
\n\n然後某個半夜，我盯著那串 `100.x.x.x` 的 IP，腦中冒出一個念頭：\n\n**如果有一天 Tailscale 倒了呢？**\n\n被收購、改價、伺服器掛掉、甚至哪天判定我違反條款把帳號停掉——我這整張網路，是不是就跟著一起癱瘓？我是不是親手把所有東西，綁在一個自己完全控制不了的單點上？\n\n這就是工程師的職業病：**SPOF（Single Point of Failure，單點故障）焦慮**。\n\n這篇文章想做兩件事：第一，戳破一個誤解——你怕的那種 SPOF，其實沒你想的嚴重。第二，如果你還是想要主權（這才是真正該擔心的事），那 headscale、NetBird、Nebula、純 WireGuard 這幾條備援方案(或是你要稱作退路也可XD)，到底該怎麼選。\n\n---\n\n## 先講個反直覺的真相：Tailscale 掛掉，你不會斷線\n\n要談 SPOF，得先搞懂 Tailscale 到底是怎麼運作的。它其實是**兩個分開的平面**：\n\n- **控制面（control plane）**：那台 Tailscale 跑的「協調伺服器」（coordination server）。它負責記住誰是誰、交換公鑰、發 ACL 政策、管 MagicDNS。這部分是**閉源的**，跑在 Tailscale 的雲上。\n- **資料面（data plane）**：你的設備之間真正的流量。這是純 [WireGuard](https://www.wireguard.com/) 的點對點（P2P）加密通道，**完全不經過 Tailscale 的伺服器**。\n\n關鍵在這裡：協調伺服器只是個「電話簿 + 介紹人」。它幫你的設備互相認識、交換鑰匙，但一旦兩台機器牽上線，後面的封包就直接 P2P 飛來飛去，跟它沒關係了。\n\n所以 Tailscale 官方文件講得很直白——[如果協調伺服器掛掉會怎樣？](https://tailscale.com/kb/1091/what-happens-if-the-coordination-server-is-down/)答案是：**你的網路大致照常運作**。設備的金鑰都存在本地，現有連線會一直維持，直到金鑰過期為止。\n\n那 NAT 穿不過去、需要中繼的時候呢？Tailscale 有一套叫 [DERP](https://tailscale.com/kb/1232/derp-servers) 的中繼伺服器。但連 DERP 都很聰明：客戶端會把 DERP 清單**快取在本地**，就算協調伺服器掛了，只要 DERP 還活著就能用。而且 DERP 只是個「笨水管」——它轉送的是已經被 WireGuard 加密過的封包，它**看不到也解不開**你的內容。\n\n
\n \"Tailscale\n
圖 A：控制面負責交換金鑰與介紹節點，資料面是設備之間的 WireGuard P2P 加密隧道；協調伺服器掛掉時，既有資料連線仍可繼續運作。
\n
\n\n把「協調伺服器掛掉」這件事拆開來看，你會發現能用的東西比想像中多：\n\n| 協調伺服器掛掉時 | 狀態 |\n| --- | --- |\n| 現有設備之間的連線 | ✅ 照常運作（P2P / DERP 中繼） |\n| 已連上的服務（SSH、NAS、網站） | ✅ 繼續通 |\n| 加入**新設備** | ❌ 無法（需要協調伺服器發鑰匙） |\n| 金鑰到期後的續期 / 重新認證 | ❌ 會卡住 |\n| 改 ACL、改 MagicDNS、改路由 | ❌ 無法套用 |\n| Funnel / Serve 等設定變更 | ❌ 無法 |\n\n換句話說：**「Tailscale 掛掉 = 我全斷線」是個誤解。** 你不會在會議中突然連不回公司伺服器。真正會卡的，是「管理動作」——加機器、換鑰匙、改政策。短時間的故障，你甚至不會察覺。\n\n到這裡，焦慮應該先消一半了。但別急——還有另一半。\n\n---\n\n## 那真正該擔心的，到底是什麼？\n\n如果今天斷線不是問題，那我半夜那股不安到底是什麼？\n\n把它想清楚之後，我發現重點根本不是「**可用性**」，而是「**主權**」——**誰掌握我這張網路的控制權？**\n\n- **控制面是閉源的，而且不在你手上。** 你的整張網路拓樸、誰能連誰、設備清單、metadata，全都記在 Tailscale 的資料庫裡。你看不到原始碼，也搬不走那台大腦。\n- **DERP 中繼預設也是 Tailscale 跑的。** 雖然你可以自架 custom DERP，但多數人沒設，等於連備援路徑都依賴它的基礎設施。\n- **政策隨時會變，而且真的會變。** 就在 [2026 年 4 月 8 日，Tailscale 才大改過一次免費方案](https://tailscale.com/blog/pricing-v4)——免費 Personal 方案變成 6 個使用者、設備無限，但同時也調整了 tagged resources（50 個）跟 ephemeral 額度。這次是變好，但下次呢？商業公司的定價權，永遠握在它自己手上。\n- **帳號層級的風險。** 收購、倒閉、服務下架、甚至誤判把你停權——這些都不是技術故障，是**商業與信任層級**的單點。\n\n所以結論是：\n\n> **SPOF 不是「Tailscale 今天會不會掛」的技術問題，而是「我願不願意把網路的控制權，長期外包給一家公司」的主權問題。**\n\n想通這一點，後面的選型就清楚了。你要評估的不是「哪個比較不會故障」，而是「我想拿回多少控制權，又願意為此付出多少維運成本」。這是一個天秤，不是一個排行榜。\n\n面對這個焦慮，你其實有 **5 種方案**。第 1 種最簡單——**留在 Tailscale**：你已經知道那種 SPOF 是誤解了，把省下的時間拿去做別的事。剩下 4 條是自架退路，我刻意按照「**最像 Tailscale → 最原始**」的順序排，控制權一路往上加，維運成本也一路往上加。\n\n---\n\n## 方案一：headscale —「我愛 Tailscale 的體驗，只是想自己掌握大腦」\n\n[headscale](https://github.com/juanfont/headscale) 是社群用 Go 寫的、**Tailscale 協調伺服器的開源重新實作**。它做的事情就一件：把那台閉源的「大腦」換成你自己跑的版本。\n\n最妙的地方是——**你的設備繼續用官方 Tailscale 客戶端**。Tailscale 的客戶端本來就是開源的（BSD 授權），閉源的只有控制面。所以裝上 headscale 後，`tailscale up --login-server=https://你的網域` 一接，體驗跟原版幾乎一模一樣，流量照樣 P2P。\n\n**適合誰：** 你已經愛上 Tailscale 的客戶端體驗、MagicDNS、跨平台支援，純粹只是不想把控制面交給別人。小團隊、homelab、注重「設定即程式碼」的人。\n\n**會踩到的坑：**\n\n- **沒有官方 Web UI。** 核心專案只給你一支 CLI + 設定檔。想要圖形介面得自己裝社群方案，像 [Headplane](https://github.com/tale/headplane)（功能最完整，含 OIDC SSO、web SSH）或 headscale-admin。\n- **部分新功能缺席。** Funnel（對外公開服務）、Serve（HTTPS 反向代理）、network flow logs、某些動態 ACL 更新，都還沒實作或落後官方。\n- **ACL 走設定檔。** 用 JSON/HuJSON 寫權限規則。好處是能丟進 Git 版控、code review；壞處是沒有點點點的 GUI。\n- **你得自己維運那台伺服器。** 升級、備份、HA（高可用）都是你的事。諷刺的是——你為了消除「Tailscale 這個 SPOF」，結果自己架的那台 headscale，現在變成**你自己的 SPOF**。它掛了，一樣不能加新機器、不能續鑰匙（差別是現在掛不掛由你決定，而且你能立刻去修）。\n\n一句話：headscale 是「**最小遷移成本**」的解。客戶端不用換，焦慮卻能消掉一大半。\n\n---\n\n## 方案二：NetBird —「整套都換成我自己的，還要有漂亮 UI 和 SSO」\n\n如果說 headscale 是換掉大腦，[NetBird](https://github.com/netbirdio/netbird) 就是**連身體一起換掉**。它是一整套開源（BSD-3）的 mesh VPN stack：自己的客戶端、自己的管理伺服器、自己的 signal 伺服器、自己的中繼（TURN），全部你能自架。\n\n它一樣是建立在 WireGuard 之上，靠 ICE/STUN/TURN 做 NAT 穿透，但在 Tailscale 那些「管理層」的功能上做得相當完整：**內建 Web UI** 管 ACL 跟群組、**原生 SSO**（綁定 Zitadel 或你自己的 OIDC 供應商）、setup keys、路由管理。\n\n**適合誰：** 你想要的是一個「**完整、可完全自主、給團隊用**」的 Tailscale 替代品，而且不想犧牲圖形介面跟單一登入。要求資料主權的公司、想自己掌握全部基礎設施的團隊。它是這幾個選項裡，**最接近「完整替代 Tailscale」**的那個。\n\n**會踩到的坑與亮點：**\n\n- **以前自架很麻煩**——管理、signal、relay 是分開的元件，要喬一堆。但 [從 v0.65（2026 年 2 月）開始，NetBird 推出 unified server binary](https://netbird.io/)，把管理 + signal + relay 包進**單一容器**，自架難度大幅下降。\n- 它也有**官方雲端版（含免費額度）**，你可以先用雲端體驗，之後再搬成自架，遷移路徑清楚。\n- 因為是自己一整套客戶端，遷移成本比 headscale 高一點——你得把所有設備從 Tailscale 客戶端換成 NetBird 客戶端。\n\n一句話：NetBird 是「**我要一整套，而且我全都要自己的**」的解。\n\n---\n\n## 方案三：Nebula —「我要規模、要效能，執行期不想依賴任何中心」\n\n[Nebula](https://github.com/slackhq/nebula) 是 Slack 開源（MIT）的覆蓋網路工具，設計哲學跟前面幾個明顯不同。\n\n首先，**它不是 WireGuard**。Nebula 用的是自己基於 Noise 協議框架的實作。再來，它是**憑證制**的：你建立自己的 CA（憑證頒發機構），每個節點拿一張你簽的憑證，只有共用同一個 CA 的節點才會互信。憑證裡直接寫死了節點的 IP、群組、權限。\n\n那節點之間怎麼找到對方？靠 **lighthouse（燈塔）節點**。Lighthouse 是網路裡唯一需要固定 IP 的角色，負責幫其他節點互相發現、做 UDP 打洞。但重點來了——**一旦憑證發下去、節點認得 lighthouse 之後，執行期就沒有一個「控制面」需要常駐做決策了**。整個網路是去中心化的，Slack 自己就用它撐到數萬台主機的規模。\n\n**適合誰：** 規模大、把網路當成「基礎設施即程式碼」來管、對效能跟可擴展性有要求、而且**最在意「執行期不要有任何中心依賴」**的人。\n\n**會踩到的坑：**\n\n- **設定曲線最陡。** 沒有 Web UI、沒有 SSO、沒有 ACL 的圖形編輯器（開箱即用的話）。你得手動管 CA、簽憑證、發設定檔。對習慣 `tailscale up` 一行搞定的人，這是另一個世界。\n- **加一台機器 = 簽一張憑證、配一份設定。** 自動化做得好很爽，做不好很煩。\n- 如果你想要 Nebula 的核心 + Tailscale 般的託管體驗，可以看 [Defined Networking](https://www.defined.net/)（由 Nebula 原作者創立的公司）的託管控制面——但那又把你帶回「依賴一家公司」的起點了，只是換個對象。\n\n一句話：Nebula 是「**我要極致的去中心化與規模，願意用維運複雜度去換**」的解。\n\n---\n\n## 方案四：純 WireGuard —「我不要任何魔法，全部自己來」\n\n走到最底層，就是 [WireGuard](https://www.wireguard.com/) 本身。\n\n前面 Tailscale、headscale、NetBird，本質上都是在「**自動化 WireGuard 很難的那幾件事**」：金鑰分發、NAT 穿透、IP 分配、ACL。如果你把這層自動化全部拿掉，自己手動來，那就是純 WireGuard。\n\n**你要自己處理的：** 產生每台的金鑰對、手動把每個 peer 的公鑰跟 endpoint 互相設定、規劃 IP 網段、自己想辦法穿 NAT（需要至少一端有固定 IP 或 port forwarding，或自己架一台 bounce server 當中繼）。沒有 MagicDNS、沒有自動金鑰輪替、沒有 ACL GUI。\n\n**適合誰：** 只有少數幾台**固定 IP 的伺服器**要互連、追求極簡與零依賴、不想跑任何額外控制元件的純粹主義者。想降低手動痛苦的話，[wg-easy](https://github.com/wg-easy/wg-easy) 這類工具能給你一個 hub-and-spoke 的簡單 Web UI。\n\n**會踩到的坑：**\n\n- **不會 scale。** Peer 設定是 n² 的關係，三五台還好，二十台你會想哭。\n- **NAT 穿透要自己解。** 這正是 Tailscale 最值錢的地方，純 WireGuard 不幫你。\n- **你就是那個 SPOF。** 不是某台伺服器——是「**你的維運能力**」。金鑰沒輪替、設定漂移、某台 endpoint IP 變了沒人更新……這些都是你一個人扛。\n\n一句話：純 WireGuard 是「**沒有魔法的真相**」。它讓你徹底理解上面那三個工具到底幫你省了多少事。\n\n---\n\n## 5 種方案放一起比\n\n把 Tailscale 當基準，5 種一起攤開：\n\n| | Tailscale | headscale | NetBird | Nebula | 純 WireGuard |\n| --- | --- | --- | --- | --- | --- |\n| **底層協議** | WireGuard | WireGuard | WireGuard | 自有（Noise） | WireGuard |\n| **客戶端** | 官方 | **官方（共用）** | 自有 | 自有 | 內建/wg-quick |\n| **控制面** | 閉源・託管 | 開源・自架 | 開源・自架 | 憑證制・無常駐中心 | 無 |\n| **NAT 穿透** | ✅（含 DERP） | ✅（共用機制） | ✅（STUN/TURN） | ✅（lighthouse 打洞） | ❌ 自己解 |\n| **Web UI** | ✅ | ⚠️ 社群方案 | ✅ 內建 | ❌ | ⚠️ wg-easy |\n| **SSO** | ✅ | ⚠️ 靠 Headplane | ✅ 內建 | ❌ | ❌ |\n| **ACL** | GUI + 檔案 | 設定檔（Git） | Web UI | 憑證內嵌 | 手動 |\n| **執行期依賴中心** | 是（Tailscale） | 是（你的伺服器） | 是（你的伺服器） | **否** | 否 |\n| **維運成本** | 最低 | 中 | 中 | 高 | 最高 |\n| **授權** | 客戶端開源/控制面閉源 | BSD-3 | BSD-3 | MIT | GPLv2 |\n\n
\n \"Tailscale、headscale、NetBird、Nebula\n
圖 B：把 5 種方案放到「維運成本」與「控制權／主權」兩個軸上看；留在 Tailscale 是多數人的預設解，越往右上角越需要用維運成本換主權。
\n
\n\n---\n\n## 所以，我到底該選哪個？\n\n跟我寫 [Mackup vs chezmoi](/blog/mackup-vs-chezmoi-vs-defaults-sh-comparison) 那篇的結論一樣——**沒有最好的工具，只有最適合你的工具**。對號入座：\n\n- **你只是焦慮，但其實沒有真的非自架不可** → **留在 Tailscale**。讀懂上面「協調伺服器掛掉不會斷線」那段，焦慮就該消了。把省下來的時間拿去做別的事。\n- **你愛 Tailscale 的客戶端體驗，只想把大腦拿回來，團隊不大** → **headscale**。遷移成本最低，客戶端都不用換。\n- **你要一整套完全自主、要給團隊用、要 UI 跟 SSO** → **NetBird**。最接近完整替代品，v0.65 之後自架也不痛了。\n- **你規模大、走 infra-as-code、最在意「執行期不要有任何中心」** → **Nebula**。用維運複雜度換極致的去中心化與規模。\n- **你只有幾台固定 IP 的伺服器、想要極簡零依賴** → **純 WireGuard**。沒有魔法，但也沒有任何你不懂的東西。\n\n---\n\n## 結語：降低焦慮的方法，不是現在就搬家\n\n繞了一圈，我自己的結論其實有點反高潮：**我還在用 Tailscale。**\n\n因為我終於想清楚——我半夜那股不安，不是「它今天會掛」，而是「我怕我被綁住、想走的時候走不掉」。而這個焦慮，根本不需要靠「現在立刻搬家」來解決。\n\n真正的解法是：**知道自己隨時搬得走。**\n\n最務實的策略，可能是繼續用 Tailscale 享受它的順手，但**心裡備好一條退路**——而且 headscale 跟 NetBird 的存在，讓這條退路便宜到不可思議：headscale 共用官方客戶端，遷移幾乎零成本；NetBird 有雲端版可以先試，要自架隨時自架。\n\nSPOF 焦慮的相反，從來不是「擁有一個永不故障的系統」（那不存在），而是「**擁有選擇權**」。\n\n當你知道自己被綁住的那一刻可以一行指令走人，你就不再是被綁住了。然後你就能睡個好覺，繼續享受那串好用到不真實的 `100.x.x.x`。\n\n## 文章簡報\n\n\n\n---\n\n### 延伸閱讀\n\n- [What happens if the coordination server is down? — Tailscale Docs](https://tailscale.com/kb/1091/what-happens-if-the-coordination-server-is-down/)\n- [How Tailscale works — Tailscale Blog](https://tailscale.com/blog/how-tailscale-works)\n- [headscale — GitHub](https://github.com/juanfont/headscale) ／ [Headplane Web UI](https://github.com/tale/headplane)\n- [NetBird — GitHub](https://github.com/netbirdio/netbird)\n- [Nebula — GitHub](https://github.com/slackhq/nebula) ／ [Defined Networking](https://www.defined.net/)\n- [WireGuard 官方網站](https://www.wireguard.com/)", "summary": "Tailscale 好用到不真實，但把整張網路綁在一個閉源控制面上，總讓人半夜睡不著。先講個反直覺的真相：你怕的那種 SPOF 其實不太會發生。從「其實不用搬」到 headscale、NetBird、Nebula、純 WireGuard，5 種備援方案一次說清楚怎麼選。", "image": "https://bobochen.dev/_astro/cover.CgKVFd7Q.webp", "date_published": "2026-06-04T00:00:00.000Z", "tags": [ "Tailscale", "WireGuard", "NetBird", "Nebula", "headscale", "Self-hosted", "VPN", "網路" ] }, { "id": "https://bobochen.dev/blog/cloudflare-pages-20000-file-limit-taxmap-netlify/", "url": "https://bobochen.dev/blog/cloudflare-pages-20000-file-limit-taxmap-netlify/", "title": "Cloudflare Pages 的 20,000 檔案上限：當「一頁一檔」撞牆，我把 TaxMap 搬到 Netlify", "content_text": "TaxMap-TW build 出 23,331 個檔案，撞上 Cloudflare Pages Free 方案「單次部署最多 20,000 檔」的硬限制，最後改用 Netlify 5 分鐘解決。記錄為什麼會爆檔案數（一頁一檔 × 7,750 村里）、三個方案的取捨，以及換平台其實是「換天花板不是拆天花板」——選靜態部署平台別只看單檔大小，檔案數才是隱形天花板。", "content_html": "買了 `bobochen.dev`，興沖沖想把我做的「台灣所得地圖」TaxMap 掛上自己的網域。我用 Cloudflare 管 DNS，理所當然想直接丟 Cloudflare Pages。結果 `pnpm build` 完一看 `dist/`——**23,331 個檔案**。然後我才想起一件大家選部署平台時很容易忽略的事。\n\n## 背景：把 TaxMap 搬上自己的網域，理所當然選 Cloudflare Pages\n\n最近把主網域 `bobochen.dev` 買下來後，開始把各個 side project 掛到子網域底下。TaxMap-TW（台灣所得地圖，一個用 Astro 做的純靜態站）要放到 `taxmap.bobochen.dev`。\n\n因為我 DNS 本來就在 Cloudflare，最自然的選擇就是 Cloudflare Pages——同一個後台、免費、CDN 又快。我連 `astro.config.mjs` 的 `site` 都已經指好 `https://taxmap.bobochen.dev` 了，想說 build 完上傳就收工。\n\n## 撞牆：build 出來 23,331 個檔案\n\n部署前我習慣先看一下產物大小。一看傻眼：\n\n- `dist/` 共 **880MB**\n- **23,331 個檔案**\n\n我第一個反應是查單檔大小有沒有超標（Cloudflare Pages 單檔上限 25 MiB），結果最大的檔案才 5.7MB（`villages.pmtiles`），離 25 MiB 遠得很。容量、單檔都沒問題。\n\n但真正擋我的是另一條限制，引用官方文件：\n\n> Cloudflare Pages sites can contain up to 20,000 files（Free 方案）\n\n而我有 23,331 個。如果硬上傳，會吃到這個錯誤訊息：\n\n> `Error: Pages only supports up to 20,000 files in a deployment.`\n\n**擋我的不是 880MB，是「23,331」這個數字。** 檔案大小和檔案數量是兩個完全獨立的天花板。\n\n## 為什麼會爆檔案數？「一頁一檔」的代價\n\nTaxMap 是「每個村里一個頁面」的資料密集型靜態站。台灣大約有 **7,750 個村里**，而我為每個村里都預先生成了三樣東西：\n\n| 內容 | 檔案數 | 大小 |\n|------|-------|------|\n| 村里頁 HTML | 7,747 | 272MB |\n| 村里資料 JSON | 7,747 | 134MB |\n| 村里 OG 社群分享圖 (PNG) | 7,750 | 466MB |\n\n7,750 × 3 ≈ 23k 檔。光是給「分享你家村里所得」用的 OG 圖就 7,750 張。\n\n這就是 SSG（靜態網站生成）「一頁一檔」模式的代價：內容一多，**檔案數會線性爆炸**。地圖、字典、商品目錄這類有大量 detail 頁的網站特別容易破萬。\n\n## 我其實有三個選項\n\n查清楚後，我整理出三條路：\n\n1. **升級 Cloudflare Pages 付費方案** — Free 是 20,000 檔，但付費方案可到 **100,000 檔**（這是 2026 起的新上限，得設 `PAGES_WRANGLER_MAJOR_VERSION=4` 環境變數才會啟用），23,331 綽綽有餘。代價：要解鎖這個上限得開 Workers Paid，最低 **$5/mo**（注意不是網站那個 $20/mo 的 Pro 方案，當初我也一度被搞混）。\n2. **砍檔案數** — 不預生成那 7,750 張 OG 圖，[改用 Worker 即時產生](/blog/cloudflare-worker-on-demand-og-satori-taxmap)，檔案數降到 ~15,600 就能上 Free 版。代價：要改 OG pipeline。這個選項其實最漂亮——它不是「砍功能」，而是「換一種方式提供同樣的 OG 圖」，而且順便連未來的頻寬問題一起解了（圖只在被請求時才生成，不用整批塞進 CDN）。當下我嫌它要動工，但坦白說它是技術上最對的解。\n3. **換 Netlify** — Netlify 沒有 Cloudflare Pages 這種「單次部署檔案數」硬限制，免費版就吃得下。代價：DNS 在 Cloudflare、站台在 Netlify，變成跨平台管理。\n\n我選了 **3**。理由很務實：這是個人 hobby 專案，為了它每月多付錢、或為了遷就平台去重構 OG pipeline，當下都嫌麻煩；而那 7,750 張 OG 圖正是 TaxMap「分享你家村里」的病毒傳播核心，我不想動它。加上我另一個子網域（typelate）本來就在 Netlify，搬過去算順手。\n\n但我得先說清楚：**選 3 是「當下最快」的取捨，不是「客觀最優」。** 選項 2（改 Worker 即時生成）其實才是長期最乾淨的解，只是要動工；如果你很在意運維一致性，DNS、站台、Workers 全留在 Cloudflare 一個後台，那付那 $5/mo 留在單一平台，其實是完全合理的選擇——跨平台管理的隱性摩擦（兩套後台、兩套憑證、兩套帳單）不是零成本，只是不會出現在帳單上。\n\n## 解法：搬到 Netlify，5 分鐘搞定\n\n因為資料和 OG 圖都已經 commit 在 `public/`（`astro build` 會自動複製到 `dist/`），所以根本不用跑那些慢的資料抓取腳本，純 build 就好：\n\n```bash\npnpm build # 純 astro build → dist/\nnetlify deploy --prod --dir=dist # 直接上傳預先 build 好的 dist\n```\n\n中途遇到一次 `getaddrinfo ENOTFOUND api.netlify.com`——上傳到一半網路抖了一下。但 Netlify CLI 的部署是**增量**的，重跑一次它自動跳過已上傳的檔案、只續傳剩下的（23,330 → 22,455），第二次就成功了。\n\n最後 `https://taxmap.bobochen.dev` 上線，Let's Encrypt 憑證也自動簽好。\n\n### 但 Netlify 不是「沒有天花板」，只是換了一面牆\n\n我得誠實補一句，免得你照抄踩雷：搬到 Netlify 不等於「解除限制」，比較像是「把擋路的那道牆換成另一道」。Cloudflare Pages 卡我的是檔案數，但它的**頻寬是沒有上限的**；Netlify 反過來——沒有檔案數硬限制，但**免費版頻寬是 100GB/月，超量大約每 100GB 收 $55**。而 TaxMap 那 7,750 張 OG 圖正是設計來「被瘋狂分享」的，萬一哪天真的病毒傳播，最先撞牆的反而是 Netlify 的頻寬，不是 Cloudflare。換句話說，我換掉的是「檔案數天花板」，但同時換上了一個「頻寬天花板」——對一個指望靠分享擴散的站來說，這個取捨其實很微妙。\n\n還有一個更新的時效雷：Netlify 從 **2025-09** 起改成 credit-based 計費，免費版每月有 **300 credits 的硬上限**，連 deploy 本身都會扣點，而且一個專案超量會把**整個帳號**的服務一起暫停（連坐）。我另一個子網域 typelate 跟 TaxMap 同一個 Netlify 帳號，這種連坐風險其實被我放大了。所以「免費、5 分鐘、無痛」這句話是我 2025-09 之前的體感——**你的免費額度很可能跟我不一樣，動手前自己去對一遍當下的方案頁，別照抄我的數字。**\n\n## 反思\n\n選靜態網站部署平台，大家通常只盯著三個數字看：單檔大小、總容量、頻寬。這次提醒我還有第四個——檔案數上限——而它最容易被忽略。我要先界定清楚：檔案數對 TaxMap 這種「一頁一檔、上萬個 detail 頁」的[資料密集型站](/blog/pmtiles-http-range-request-single-file-tiles)才會這麼致命，一般部落格、產品官網根本碰不到兩萬檔，那種站更該盯的是頻寬跟 build 時間。各家的檔案數天花板也差很多：Cloudflare Pages Free 是 20,000、付費才到 100,000，Netlify 則沒有這種等級的硬卡點。重點是選平台前把這四個限制都對一遍，免得中途翻車。\n\n回頭看，我這次是 build 完、deploy 前才想到去查檔案數，算是運氣好，在浪費一次失敗部署之前就攔下來了。理想上這種限制應該在「選平台的當下」就查清楚，而不是撞牆才回頭——這也是我後來幫整個 [TaxMap 專案做覆盤](/blog/taxmap-tw-postmortem-6-decisions-4-pitfalls)時記下來的一條。至於最後選免費平台 5 分鐘搬完、沒去重構 OG pipeline 也沒付月費，這算不上什麼大道理，純粹是一個 side project 該有的鬆弛感：不是每個技術潔癖都值得當下還債，能用最小力氣讓站上線、功能一個沒少，往往就夠了。\n\n另外兩個踩坑時學到的東西：我一度以為「換成 Cloudflare Workers Static Assets 就能逃」，結果 Workers 靜態資源也有自己的檔案數上限，不是無腦解；還有就是這次最反直覺的地方——擋住你的可能不是「太大」，而是「太多」，880MB 完全沒事，是 23,331 這個「數量」把我卡死的。\n\n---\n\n*官方限制文件：[Cloudflare Pages Limits](https://developers.cloudflare.com/pages/platform/limits/)*", "summary": "TaxMap-TW build 出 23,331 個檔案，撞上 Cloudflare Pages Free 方案「單次部署最多 20,000 檔」的硬限制，最後改用 Netlify 5 分鐘解決。記錄為什麼會爆檔案數（一頁一檔 × 7,750 村里）、三個方案的取捨，以及換平台其實是「換天花板不是拆天花板」——選靜態部署平台別只看單檔大小，檔案數才是隱形天花板。", "image": "https://bobochen.dev/_astro/cover.KZinsJzY.webp", "date_published": "2026-05-31T00:00:00.000Z", "tags": [ "Cloudflare Pages", "Netlify", "部署", "Astro", "靜態網站" ] }, { "id": "https://bobochen.dev/blog/cloudflare-worker-on-demand-og-satori-taxmap/", "url": "https://bobochen.dev/blog/cloudflare-worker-on-demand-og-satori-taxmap/", "title": "把 7,750 張 OG 圖改成 Cloudflare Worker 即時生成：Satori at the edge", "content_text": "Cloudflare Worker 即時生成 OG 圖的設計稿：用 workers-og（Satori + resvg-wasm）取代 TaxMap-TW 預先生成的 7,750 張村里圖，預生檔案數從 7,750 降到 0、騰出空間搬回 Cloudflare Pages Free。含中文字型、Cache API 與 Workers Free CPU 上限踩雷。", "content_html": "> ⚠️ 開頭先誠實說：這篇是**設計與 How-to 指南**，不是已上線的復盤——它正是[上一篇](/blog/cloudflare-pages-20000-file-limit-taxmap-netlify)我「逃避」掉的那個重構。等真的做完，我會再寫一篇實戰版。\n\n## 起點：上一篇 7,750 張預先生成 OG 圖留下的尾巴\n\n[上一篇](/blog/cloudflare-pages-20000-file-limit-taxmap-netlify)講到 TaxMap 因為「每個村里預先生成 1 張 OG 圖 × 7,750 = 7,750 個檔案」，把 `dist/` 頂破 Cloudflare Pages 的 20,000 檔上限，最後搬去 Netlify。\n\n但其實有個更漂亮的解法：**根本不要預先產生那 7,750 張圖**。改成「有人要分享某個村里時，才即時生成那一張，然後快取在邊緣」。\n\n而且這招有個甜美的副作用——OG 圖從 7,750 個檔案變成 **0 個**，`dist/` 從 23,331 降到 ~15,584，**反而塞得回 Cloudflare Pages Free 版**。繞了一圈又回得去。\n\n## 核心概念：on-demand OG\n\n預先生成（build-time）vs 即時生成（runtime）的差別：\n\n| 比較項目 | Build-time（現在）| Runtime（這篇要做的）|\n|---|---|---|\n| 何時產圖 | build 時一次生 7,750 張 | 第一次有人請求才生那一張 |\n| 檔案數 | +7,750 | **0**（不進 `dist/`）|\n| 新增村里 | 要重 build | 自動就有 |\n| 首次延遲 | 無（已是檔案）| 有（首次渲染，之後吃快取）|\n| 冷啟動 | 無 | 有（Worker 冷啟 + WASM 初始化）|\n| 額外執行成本 | 無（純靜態檔） | 多一個 Worker（可能要 Workers Paid）|\n| 外部相依 | build 完就定版 | 線上要 fetch 字型、村里 JSON、Cache API |\n| 爬蟲可靠度 | 100%（檔案永遠在） | 看快取命中，首次被分享是冷渲染 |\n| 可驗證性 | CI build 階段就能驗、壞了不會上線 | 失敗移到線上請求路徑，要靠監控才看得到 |\n\n做法：一個 Worker 掛在 `/og/v/:code.png`，第一次被請求時 render 出 PNG、寫進 edge cache，之後都走快取。\n\n## 技術棧：workers-og（Satori + resvg-wasm）\n\n關鍵是 [`workers-og`](https://github.com/kvnang/workers-og) 這個套件——專為 Cloudflare Workers 設計的 OG 產生器，API 仿 `@vercel/og`，底層是：\n\n- [Satori](https://github.com/vercel/satori)：把 HTML/CSS → SVG（不需瀏覽器）\n- `@resvg/resvg-wasm`：把 SVG → PNG\n\n**為什麼不直接用 `@vercel/og`？** 因為它的 WASM 打包方式在 Cloudflare Worker 上會出錯。`workers-og` 就是為了解決這件事而生，還額外支援用 HTML 字串（透過 Worker 的 `HTMLRewriter` 解析），不用寫 JSX。\n\n底層的 Satori + resvg 其實就是我在 build-time 產 OG 圖時用的那套，差別只在這次搬到了 Worker 上跑。Satori 本身怎麼把 HTML/CSS 變成 OG 圖、為什麼是它而不是 puppeteer，我之前寫過一篇 build-time 的 Satori + resvg 教學；想先看「到底要不要自己生 OG 圖、有哪幾種做法」的，可以看 OG 圖自動生成的三種方案比較。這篇談的 runtime 生成，本質上是同一套引擎換個執行時機。\n\n### 3 分鐘快速上手\n\n```bash\nnpm create cloudflare@latest og-worker # 建一個 Worker 專案\ncd og-worker\nnpm install workers-og\n```\n\n最小可動範例（`src/index.ts`）：\n\n```ts\nimport { ImageResponse } from \"workers-og\";\n\nexport default {\n async fetch(request: Request) {\n const html = `\n
\n 哪里最有錢 · TaxMap\n
`;\n return new ImageResponse(html, { width: 1200, height: 630 });\n },\n};\n```\n\n```bash\nnpx wrangler dev # 本機跑起來\n# 開 http://localhost:8787 就看到一張 1200×630 的 PNG\n```\n\n`ImageResponse` 收 HTML 字串（或 JSX），回一個 body 是 PNG 的 `Response`。就這麼直接。\n\n## 套用到 TaxMap 的設計\n\n把村里資料、字型、快取串起來（設計草稿）：\n\n```ts\nimport { ImageResponse } from \"workers-og\";\n\nlet fontCache: ArrayBuffer | null = null;\nasync function getFont() {\n // ⚠️ 中文字型必須「手動」載入並塞給 Satori，它不會自己抓\n if (!fontCache) {\n const r = await fetch(\"https://taxmap.bobochen.dev/fonts/NotoSansTC-Bold.woff\");\n fontCache = await r.arrayBuffer();\n }\n return fontCache;\n}\n\nexport default {\n async fetch(request: Request, env: unknown, ctx: ExecutionContext) {\n const url = new URL(request.url);\n const code = url.pathname.split(\"/\").pop()?.replace(\".png\", \"\");\n\n // 1) 先查 edge cache，命中就直接回（每個村里只 render 一次）\n const cache = caches.default;\n const hit = await cache.match(request);\n if (hit) return hit;\n\n // 2) 手動 fetch 村里資料（Satori 在 Worker 內建抓取會「默默失敗」）\n const data = await fetch(\n `https://taxmap.bobochen.dev/data/villages/${code}.json`\n ).then((r) => r.json());\n\n // 3) render\n const img = new ImageResponse(\n `
\n
${data.county}${data.town}
\n
${data.name}
\n
中位數所得 ${data.median} 萬
\n
`,\n {\n width: 1200,\n height: 630,\n fonts: [{ name: \"Noto Sans TC\", data: await getFont(), weight: 700 }],\n }\n );\n\n // 4) 寫進 cache，回傳\n const res = new Response(img.body, img);\n res.headers.set(\"Cache-Control\", \"public, max-age=31536000, immutable\");\n ctx.waitUntil(cache.put(request, res.clone()));\n return res;\n },\n};\n```\n\n這段是設計骨架，刻意省了錯誤處理好讓主幹清楚——但正式版不能這樣留：`getFont()` 的 `fetch`、村里 JSON 的 `fetch`、`r.json()` 任何一步失敗，現在都會直接讓整個請求 500，而且這正是 build-time 沒有的失敗模式（build 階段抓不到字型，build 就紅燈了，根本上不了線；改成 runtime 之後，這些錯誤全被推到「使用者請求當下」才爆）。實作時這裡每一步都要包 try/catch，並準備一張 fallback OG 圖（純文字、不依賴外部資料的版本），抓不到資料時至少回得出一張像樣的圖，而不是讓爬蟲拿到 500。\n\n## 踩雷預告（先研究過、實作時會遇到的）\n\n1. **別用 `@vercel/og`**：WASM 打包不相容 Worker，改用 `workers-og`。\n2. **中文字型要手動塞**：非拉丁字型 Satori 不會自己載，要自己把 Noto Sans TC 的 WOFF buffer 餵給 `fonts`。WOFF ~1.4MB，但 Satori 只會 subset 實際用到的字，輸出 PNG 約 30KB。**注意字型格式只能餵 TTF / OTF / WOFF，Satori 不支援 WOFF2**——很多現成 CDN 字型預設給的是 .woff2，直接拿來會解析失敗，要找 .woff 版或自己轉一份。\n3. **Satori 內建抓圖會默默失敗**：在 Worker 裡，圖片要自己 `fetch` 轉成 base64 data URL，不要靠 Satori 內部抓。\n4. **Worker CPU 時間**：resvg-wasm render 吃 CPU，要靠 edge cache 讓每張只算一次。\n5. **Cache API 在 `*.workers.dev` 根本不會運作**：這是整套成本攤平的地雷。`caches.default` 只在 **custom domain**（或 Pages Functions）上才真的快取，掛在預設的 `xxx.workers.dev` 網域時 `cache.put` 是 **靜默 no-op**——`cache.match` 永遠 miss，每一次請求都重新 render 一張圖，「每個村里只算一次」的前提整個落空。所以這個 OG Worker **一定要掛在自己的 custom domain**（例如 `taxmap.bobochen.dev`），不能只用快速上手那個 `localhost:8787` / workers.dev 就上線。上面快速上手叫你開 `localhost:8787` 只是看渲染對不對，不代表 cache 有在運作。\n6. **Workers Free 每次 invocation 只有 10ms CPU**：Satori + resvg-wasm 第一次把 CJK PNG rasterize 出來，CPU 時間常常遠超過 10ms。如果跑在 Workers **Free**，這張首圖很可能直接被 runtime 中止——圖生不出來，也就寫不進快取，下一個請求又從頭再撞一次。所以要分清楚兩件事：**TaxMap 主站的靜態 `dist/` 回 Cloudflare Pages Free 沒問題**（純靜態託管），但**負責即時渲染的這個 OG Worker，很可能得開 Workers Paid（$5/mo）才扛得住第一次冷渲染**。下面「搬回 Free」講的是前者，別把它誤讀成「連渲染都免費」。\n\n## 反思\n\n### 技術面\n\n這是個經典的 **build-time vs runtime** 取捨，而且不是 runtime 完勝。Build-time 換來的是零冷啟動、不用多付 Worker 錢、build 完就定版沒有外部相依、爬蟲 100% 抓得到、壞了在 CI 階段就會被擋下來——這些 runtime 全部要重新賺。Runtime 換來的是零檔案、新村里自動就有，代價是多一個 Worker、首次渲染延遲，還有一整類 build-time 不存在的「線上才會炸」失敗模式：fetch 字型、fetch 村里 JSON、Cache API 命中率，任何一個出包都是使用者請求當下才發現。\n\n所以我不會說它「幾乎是必然」。我的門檻是這樣：如果頁面數會持續長大到撞檔案數上限、而且大多數頁面其實沒人會去分享（OG 圖很長尾），那 runtime 才划算——用「只渲染真的被分享到的那幾張」換掉「無差別預生幾千張」。反過來，如果頁面數可控、或熱門頁面就那幾個，build-time 的零延遲跟可驗證性還是比較省心。\n\n而且要對「首次延遲」很誠實。社群平台的爬蟲（Facebook、Threads、LINE）抓 OG 圖是同步的、有 timeout、而且基本上不重試。偏偏 cache miss 那一次——也就是這個村里第一次被分享出去的那一刻——正好是最慢的冷渲染。第一個願意幫你分享的人，很可能就是看不到預覽圖的那個人，這對想靠分享擴散的站來說格外諷刺。要救有幾條路：用 sitemap 或 build 後跑一輪預熱、把已知熱門的村里在 build 時先 warm 進快取、對爬蟲走 stale-while-revalidate（先回舊圖、背景重算）。但說到底，**如果一張圖幾乎都是「第一次被分享」時才被要求，那 build-time 預先準備好其實更安全**——這也是我還沒急著把它換掉的原因。\n\n還有快取本身也別想得太美。`caches.default` 是 **per-PoP** 的，每個邊緣節點各自一份、而且會被驅逐。所以「每個村里只 render 一次」嚴格說是「每個村里、在每個 PoP、在還沒被驅逐之前各 render 一次」；長尾村里散在各地、又久久才被看一次，命中率會很低，等於反覆 cache miss 反覆重算。真要做到全球只算一次，得把結果落到 R2 或 KV 這種持久層，而不是只靠 edge cache。\n\n### 心態面\n\n上一篇我為了快速上線，選了「換平台」這個 5 分鐘解法，把重構記成 TODO。這篇是把那張 TODO 攤開來「先想清楚怎麼做」——**先設計、再實作**，而不是一頭栽進去寫 code 才發現中文字型載不進來。光是先查清楚 Cache API 在 workers.dev 不運作、Free 版 10ms CPU 這兩個雷，預期就能省下實作時撞牆乾耗的半個下午——當然這還只是假設，真的動手做完才知道準不準。\n\n### 有趣發現\n\n最爽的是那個全循環：**把 OG 改成即時生成，預生檔案數掉到 20,000 以下，TaxMap 的靜態站就能搬回 Cloudflare Pages Free**。當初逼我搬家的限制，用對的架構就能繞回去。\n\n不過先別太得意。所謂「搬回 Free」是把帳算在靜態託管那一塊——真實的代價是架構從「一坨靜態檔」拆成「Pages 靜態站 + 一個獨立 OG Worker（很可能還得 Workers Paid）」兩塊東西。檔案數歸零的同時，我換來的是兩套部署、Worker 的字型/快取/錯誤處理要長期顧、出事時要分清楚是哪一邊。本質上是用「長期維運複雜度」去換「檔案數歸零」，不是無痛的勝利。值不值得，要看我願不願意長期養這個 Worker——這也是我到現在還只把它停在設計稿、沒真的動手的原因。\n\n---\n\n**這個系列其他文章**：前情是 [Cloudflare Pages 的 20,000 檔案上限：我把 TaxMap 搬到 Netlify](/blog/cloudflare-pages-20000-file-limit-taxmap-netlify)（就是它逼出這篇的重構）；整個專案怎麼蓋、踩了哪些坑的全紀錄在 [打造 TaxMap-TW 完整心得：6 個技術決策、踩了 4 個坑](/blog/taxmap-tw-postmortem-6-decisions-4-pitfalls)。\n\n*參考：[workers-og](https://github.com/kvnang/workers-og)、[Satori](https://github.com/vercel/satori)、[6 Pitfalls of Dynamic OG on Cloudflare Workers](https://dev.to/devoresyah/6-pitfalls-of-dynamic-og-image-generation-on-cloudflare-workers-satori-resvg-wasm-1kle)*", "summary": "Cloudflare Worker 即時生成 OG 圖的設計稿：用 workers-og（Satori + resvg-wasm）取代 TaxMap-TW 預先生成的 7,750 張村里圖，預生檔案數從 7,750 降到 0、騰出空間搬回 Cloudflare Pages Free。含中文字型、Cache API 與 Workers Free CPU 上限踩雷。", "image": "https://bobochen.dev/_astro/cover.D0Dg35Zl.webp", "date_published": "2026-05-31T00:00:00.000Z", "tags": [ "Cloudflare Workers", "Satori", "OG Image", "Astro", "邊緣運算" ] }, { "id": "https://bobochen.dev/blog/enterprise-ai-agent-governance-framework/", "url": "https://bobochen.dev/blog/enterprise-ai-agent-governance-framework/", "title": "Agent 治理框架：讓企業敢把 AI agent 接到真實業務上的那張安全網", "content_text": "把散落在各章的安全與信任機制，收斂成一張可以攤給資安和主管看的治理框架：資料分級、RBAC 權限邊界、tool registry、audit log、human-in-the-loop、eval harness、observability、成本監控。這一張圖，就是「能 demo」和「企業敢用」之間那道治理的牆。", "content_html": "import DeckEmbed from '../../../components/blog/DeckEmbed.astro';\nexport const deckSlides = Object.entries(import.meta.glob('./slides/*.webp', { eager: true, import: 'default' })).sort(([a], [b]) => a.localeCompare(b)).map(([, m]) => m);\n\n> 這是「從 PoC 到 Production：企業 AI Agent 系統工程」系列第 11 篇（共 12 篇）。上一篇：[延遲、可靠性、成本的系統權衡](/blog/enterprise-ai-agent-latency-reliability-cost-tradeoffs)。這篇整理的是**治理設計框架（一份 reference / 設計提案）**，不是某個已導入系統的稽核報告。\n\n前面十篇，安全和信任的機制是散落各處講的：第 5 篇的權限檢索、第 6 篇的工具邊界、第 9 篇的可觀測性。這一篇要做的，是把它們**收斂成一張完整的治理框架**——一張你可以攤在資安長、法遵、業務主管面前，回答那個關鍵問題的圖：\n\n> 「我們憑什麼敢相信這個 AI agent，把它接到真實的客戶資料、財務系統、製造流程上？」\n\nPoC 永遠回答不了這個問題，因為它根本沒想過。而這張圖，就是「能 demo」和「企業敢用」之間那道治理的牆。\n\n## 一頁治理框架\n\n![Agent 治理框架：上層控制「誰能碰什麼」、中層控制「能做什麼」、底層橫跨一切持續監督（audit、eval、observability、cost）](./images/governance-framework.webp)\n\n

治理框架的三層：上層管「誰能碰什麼」、中層管「能做什麼」、底層橫跨一切持續監督（audit / eval / observability / cost）。

\n\n八個元件，分三層：**控制誰能碰什麼（①②）、控制能做什麼（③④）、持續監督（⑤⑥⑦⑧）**。一個一個講它在治理上扮演什麼角色。\n\n在逐項講之前，先講一件對資安和法遵很重要的事：**這張圖不是我發明的。** 它只是把 NIST AI RMF、ISO/IEC 42001、EU AI Act 對 AI 系統的共同要求，落到 agent 工程上。八個元件幾乎一對一對得上既有框架：\n\n| 治理元件 | NIST AI RMF | ISO/IEC 42001 | EU AI Act（高風險） |\n|---|---|---|---|\n| ① 資料分級 | MAP | Annex A 控制 | Art.10 資料治理 |\n| ② RBAC/ABAC・最小權限 | GOVERN | Annex A 控制 | — |\n| ③ Tool Registry | MAP / GOVERN | Annex A 控制 | — |\n| ④ Human-in-the-loop | GOVERN / MANAGE | PDCA | Art.14 人類監督 |\n| ⑤ Audit Log | MEASURE | PDCA | Art.12 紀錄保存 |\n| ⑥ Eval Harness | MEASURE | Check（PDCA） | — |\n| ⑦ Observability | MEASURE | Check（PDCA） | Art.12 / Art.72 |\n| ⑧ Cost／持續監督 | MANAGE | Act（PDCA） | Art.72 上市後監督 |\n\n為什麼要花力氣對這層？因為當你把這張圖攤在法遵面前，他第一個問題不會是「你 RBAC 怎麼做的」，而是「**這對得上我們要遵的哪一條**」。對得上，框架的說服力就從「工程師畫的圖、聽起來有道理」，升級成「對得上稽核要求的圖」。\n\n## ① 資料分級：先知道你在保護什麼\n\n治理的起點不是技術，是**盤點**。哪些資料是公開的、內部的、機密的、個資 / 受法規保護的（個資法、營業秘密、客戶合約）？\n\n沒有分級，後面的權限控制就沒有依據——你不知道哪些資料「碰了會出事」。這一步常常要跟法遵、資安一起做，是治理裡最不技術、卻最不能跳過的一步。分級的結果，會變成第 5 篇那些 chunk 上的權限 metadata 的來源。\n\n## ② 身分與權限邊界：RBAC / ABAC\n\n把「誰、能透過 agent、碰到哪些資料和工具」明確定義出來。這是第 5 篇（資料檢索）和第 6 篇（工具動作）的權限，在治理層的統一視角。\n\n- **RBAC（角色為本）**：依角色給權限。工程師能查工單、不能查薪資；主管多一些；HR 又不同。\n- **ABAC（屬性為本）**：更細，依屬性動態判斷（部門 + 機密等級 + 地區）。複雜場景用得上。\n\n核心原則是**最小權限**：agent 代表某使用者行動時，只該有那個使用者該有的權限，**一分不多**。最該避免的反模式，就是第 2 篇警告過的——agent 用一個服務帳號的最大權限在跑，把自己變成權限放大器。\n\n## ③ Tool Registry：能做的事，要有一份清單\n\n第 6 篇講過，MCP / tool registry 把「agent 能做哪些動作」變成一份可盤點的清單。在治理層，這份清單要再標註：\n\n- 每個工具的 **action boundary**（唯讀 / 寫入 / 危險）\n- 需不需要 **approval**\n- 哪些角色能用哪些工具\n\n當資安問「你們的 agent 到底能對哪些系統做哪些事」，你掏得出這份清單——這就是治理的可稽核性。**沒有 registry，你連自己的 agent 能做什麼都說不清楚**，更別說讓資安放行。\n\n## ④ Human-in-the-loop：高風險動作的剎車\n\n第 6 篇講過 approval flow 的機制，治理層要決定的是**政策**：哪些動作非要人類確認不可？\n\n通常的分界：**會造成重大、不可逆副作用的**——大量資料異動、對外溝通、金流、改動生產設定——都該有 HITL 關卡。低風險唯讀的放行。這份「哪些要剎車」的清單，是治理的核心決策之一，要跟業務一起定，因為它直接影響效率和風險的平衡。\n\n但 HITL 最常見的失效，不是沒放關卡，是**放了卻變成橡皮圖章**——當待核可的動作又多、又通常是對的，人會很快養成「一律點同意」的習慣，關卡還在、監督已經沒了。這正是 EU AI Act Art.14 想堵的洞：它要的是**有意義的、能真正介入的人類監督**，不是流程上多一個 approval 按鈕。對 agent 還有個額外的坑：當待核可項是模型生成的一段自然語言，審核者很難在幾秒內判斷它的副作用範圍。所以 HITL 的設計品質，取決於「**呈現給人類的資訊，夠不夠讓他做出有意義的判斷**」——這動作會改到哪些資料、影響多大、為什麼 agent 這樣選——而不只是「有沒有放一個確認關卡」。\n\n## ⑤–⑧ 監督層：信任不是一次性的，是持續的\n\n前面四項是「事前控制」，但治理的另一半是**持續監督**——因為信任會隨時間、隨模型更新、隨資料變化而流失。這四項都在前面章節建好了，治理層把它們組織起來：\n\n- **⑤ Audit Log**：誰、何時、透過 agent、存取了什麼、做了什麼動作。合規與事故調查的底線，出事時這是你唯一能還原真相的東西。兩個常被漏掉的細節：(1) **要留多久？** EU AI Act Art.12 已把高風險系統的「自動事件記錄」從最佳實踐升級成法定義務，Art.19 對 deployer 給的下限是至少保存六個月——audit log 不只要有，還要回答得出保存期限。(2) **對 agent，光記「呼叫了哪個工具」遠遠不夠**，要連 prompt、檢索到的 chunk、工具的輸入輸出一起留，否則事故調查時最關鍵的中間決策過程是一片空白。這份資料跟第 9 篇 observability 的 trace 其實是同一份東西的兩種用途。\n- **⑥ Eval Harness（第 9 篇）**：品質有沒有偷偷掉？模型被供應商更新後行為有沒有漂移？這套持續監督的精神對應 NIST AI RMF 的 MEASURE / MANAGE；NIST 2024 年的 Generative AI Profile（NIST-AI-600-1）甚至把 **confabulation（也就是幻覺）獨立列為一個風險類別**，對 12 個 GenAI 風險領域給了 200+ 條建議行動，可以直接拿來當 eval 與監控清單的起點——它點名的第一個風險，正好就是這系列開頭的「鴻溝一：正確性沒有底線」。\n- **⑦ Observability（第 9 篇）**：每個決策可追、可重播，出包查得到根因。\n- **⑧ Cost Monitor（第 9、10 篇）**：花費透明、異常可告警。\n\n這四項合起來回答的是：**「我們有沒有在持續確認這套系統仍然值得信任？」** 一個只做事前控制、卻沒有持續監督的 agent，就像一個通過了上線審查、之後就再也沒人看的系統——遲早出事。\n\n## 怎麼落地：別想一次到位\n\n這張框架完整，但不代表你要一次全做完。務實的導入順序：\n\n1. **先做 ①②**（分級 + 權限邊界）：沒有這個，任何接觸真實資料的 agent 都不該上線。這是入場券。\n2. **再做 ③⑤**（registry + audit）：讓「能做什麼」和「做過什麼」可盤點、可追。\n3. **接著 ④**（HITL）：把最高風險的動作先用人類關卡保護起來。\n4. **持續強化 ⑥⑦⑧**：監督層隨系統成熟逐步加深。\n\n還有一個外部理由，讓「現在就做」比「等等再說」划算：**法規時鐘已經在跑。** 但這裡有個 2026 必須講對的眉角——EU AI Act 是分階段生效的：禁止性實務與 AI 素養義務已自 2025-02 適用、GPAI 義務自 2025-08 適用，這幾條都已生效。而大家最在意的**高風險義務，原訂 2026 年 8 月起，在 2025 年底的 Digital Omnibus 提案後被往後推**（討論中的新時程落在 2027–2028，截至本文撰稿仍待正式定案）。所以如果你還在網路上看到「2026 年 8 月高風險義務全面適用」，那是舊懶人包、已經過期了。給你的訊息很單純：**日期會動，但別賭它會無限延。** 分級、RBAC、audit、HITL 這套底層工程量大、牽涉法遵與業務，不是兩週能補完的——日期往後挪，剛好是讓你「提早做、做扎實」的窗口。\n\n依風險排序：**越是接觸機密資料、越是能造成不可逆動作的 agent，治理就要越完整**；一個只查公開 FAQ 的內部小工具，不需要這整套。治理的強度應該對應風險的高度，這本身也是一種工程判斷。\n\n## 小結\n\nAgent 治理不是上線後補的文件，是讓企業**敢**把 agent 接到真實業務上的前提。它把散落的機制收成一張圖：\n\n- **控制誰能碰什麼**：資料分級 + RBAC/ABAC 最小權限。\n- **控制能做什麼**：tool registry + 高風險動作的 HITL。\n- **持續監督**：audit log + eval + observability + cost。\n\n而它的精神，其實跟整個系列一致：**承認系統會錯、會被濫用、會隨時間退化，然後為這些事先設好防線**。能畫出這張圖、並依風險決定導入深淺的人，才是企業真正想要的「能把 AI agent 落地」的那個人。\n\n最後一篇，我們從系統回到人：當你要**帶一支 3–8 人的 AI 工程小隊**，把上面這整套東西做出來、維護下去，該怎麼帶。\n\n\n## 文章簡報\n\n\n\n---\n\n### 延伸閱讀\n\n- 上一篇：[延遲、可靠性、成本的系統權衡](/blog/enterprise-ai-agent-latency-reliability-cost-tradeoffs)\n- 回顧：[權限感知檢索](/blog/enterprise-ai-agent-permission-aware-retrieval)、[Tool use 與 MCP](/blog/enterprise-ai-agent-tool-use-mcp)、[可觀測性與評估](/blog/enterprise-ai-agent-llm-observability-eval)——治理框架的三個技術支柱\n- 下一篇（完結）：《帶領一支 3–8 人的 AI 工程小隊》", "summary": "把散落在各章的安全與信任機制，收斂成一張可以攤給資安和主管看的治理框架：資料分級、RBAC 權限邊界、tool registry、audit log、human-in-the-loop、eval harness、observability、成本監控。這一張圖，就是「能 demo」和「企業敢用」之間那道治理的牆。", "image": "https://bobochen.dev/_astro/cover.BKs-7b68.webp", "date_published": "2026-05-31T00:00:00.000Z", "date_modified": "2026-06-05T00:00:00.000Z", "tags": [ "AI 治理", "資安", "RBAC", "稽核", "企業導入" ] }, { "id": "https://bobochen.dev/blog/agentic-engineering-testing-safety/", "url": "https://bobochen.dev/blog/agentic-engineering-testing-safety/", "title": "Agent 安全網設計：當 AI 有 sudo 權限，你需要幾層保護", "content_text": "給 agent 越多權限它越有用，但也越危險。設計一套「agent 安全網」——從 sandbox 環境、permission boundaries、rollback 機制、到 human-in-the-loop 的斷路器設計。附 hooks 設定和曾經差點出事的真實故事。", "content_html": "> 這是「Agentic Engineering 實戰手冊」系列的第十二篇。上一篇：[Token 經濟學進階](/blog/agentic-engineering-cost-optimization)\n\n## Agent 自動 Push 了 47 次到 Staging\n\n有一次我設定了 agent 自動部署到 staging 的 workflow，然後去吃午餐。回來的時候，staging 環境已經被部署了 47 次。\n\n原因是 agent 卡在一個 deploy → test → fix → redeploy 的 loop 裡。每次 fix 都產生新的 issue，然後又觸發 redeploy。我去吃午餐的一個小時裡，它忠實地執行了 47 個 cycle。\n\nstaging 環境沒壞，但同事們的 test data 全被覆蓋了。那個下午我花了兩小時幫大家恢復環境，以及更久的時間恢復他們對我搞的 automation 的信任。\n\n這件事教了我一件事：agent 最危險的特質不是它會做錯事，而是它會不知疲倦地一直做錯事。人類犯錯會停下來思考，agent 犯錯只會繼續 loop。\n\n## Agent 的權限困境\n\nAgent 的有用程度跟它的權限成正比：\n\n- **只能讀 code** → 能幫你查東西，但不能幫你做事\n- **能讀寫 code** → 能幫你寫 code、修 bug\n- **能執行指令** → 能跑 test、build、lint\n- **能操作 Git** → 能 commit、create branch、push\n- **能操作外部系統** → 能 deploy、query database、send notification\n- **能操作瀏覽器** → 能做 visual testing、填表單、抓資料\n\n每一層權限的增加，都讓 agent 更有用，也更危險。\n\n目標不是「限制 agent」（那樣它就沒用了），而是**設計可控的自由度**，在每個權限等級上放對的護欄。\n\n## 安全網的三層架構\n\n我的 agent 安全設計有三層，從自動到人工：\n\n```\nLayer 1: Sandbox（自動隔離）\n ↓ 擋住大部分的「無意間搞破壞」\nLayer 2: Hooks & Guardrails（自動檢查）\n ↓ 擋住「不該做的操作」\nLayer 3: Human-in-the-Loop（人工審批）\n ↓ 擋住「需要判斷的決策」\n```\n\n### Layer 1: Sandbox 環境設計\n\n**Git Branch Isolation**\n\n最基本也最有效的 sandbox：agent 永遠在 feature branch 上工作，永遠不直接改 main。\n\n```bash\n# Agent 開始工作前\ngit checkout -b feat/agent-task-xxx\n\n# Agent 工作完成後\n# → 你 review → merge → 或 discard\n```\n\n萬一 agent 把事情搞砸了，`git checkout main && git branch -D feat/agent-task-xxx` 就好，一秒復原。\n\n**Git Worktree**\n\n進階做法：用 git worktree 讓 agent 在一個完全獨立的目錄裡工作。它的修改不會影響你正在看的 working directory。\n\nClaude Code 有內建的 worktree 支援——你可以讓 sub-agent 在 worktree 裡跑，確保主 context 的檔案狀態不被干擾。\n\n**Network Isolation**\n\n如果你用 Codex CLI，它有 kernel-level sandbox——agent 在一個隔離的 Linux 容器裡執行，只能存取你明確授權的路徑和 network。\n\nClaude Code 的隔離沒這麼嚴格（它在你的 terminal 裡直接執行），所以更需要依賴 Layer 2 和 Layer 3。\n\n### Layer 2: Hooks 作為 Guardrails\n\nClaude Code 的 hooks 系統讓你在 agent 的操作前後自動執行檢查：\n\n| Hook 類型 | 觸發時機 | 用途 |\n| ---------------- | -------------------- | --------------- |\n| **PreToolUse** | Agent 要使用工具之前 | 攔截危險操作 |\n| **PostToolUse** | Agent 使用工具之後 | 記錄 / 檢查結果 |\n| **Notification** | 需要通知時 | Alert / log |\n\n**我的 Hook 設定**：\n\n**1. 敏感檔案保護**\n\n```json\n{\n \"hooks\": {\n \"PreToolUse\": [\n {\n \"matcher\": \"Edit|Write\",\n \"command\": \"check-sensitive-files.sh \\\"$FILE_PATH\\\"\",\n \"description\": \"Block edits to .env, credentials, or config with secrets\"\n }\n ]\n }\n}\n```\n\nAgent 嘗試編輯 `.env`、`credentials.json`、或任何包含 secrets 的檔案時，自動擋住。\n\n**2. Git Push 確認**\n\nAgent 可以自由 commit（到 feature branch），但 push 需要人工確認。因為 push 是不可逆的，一旦 push 到 remote，其他人就能看到。\n\n**3. 破壞性操作攔截**\n\n`rm -rf`、`DROP TABLE`、`git reset --hard`——這些操作在被 agent 執行之前，一律需要你的明確批准。\n\n### Layer 3: Human-in-the-Loop 斷路器\n\n有些操作，不管有多少自動化檢查，最終都需要人來決定。\n\n**斷路器設計原則：Reversibility × Blast Radius**\n\n| | 低影響 | 高影響 |\n| ---------- | --------- | --------- |\n| **可逆** | 自動放行 | Hook 檢查 |\n| **不可逆** | Hook 檢查 | 人工審批 |\n\n對應到實際操作：\n\n**自動放行**（可逆 + 低影響）：\n\n- 讀取檔案\n- 跑 test / lint\n- 在 feature branch 上 commit\n- 格式化 code\n\n**Hook 檢查**（可逆 + 高影響 or 不可逆 + 低影響）：\n\n- 修改 config files\n- 安裝 npm packages\n- 執行 build\n- 修改 database migration files\n\n**人工審批**（不可逆 + 高影響）：\n\n- Git push to remote\n- Deploy to staging / production\n- 刪除檔案或 branch\n- 修改 CI/CD pipeline\n- 任何涉及 credentials 的操作\n\n## Near-Miss Stories：差點出事的那幾次\n\n### 案例 1：47 次 Staging Deploy\n\n（開場說的那個。）\n\n**根因**：agent 有自動 deploy 的權限，且沒有 rate limit。\n\n**加了什麼防護**：\n\n1. Deploy 操作加了 cooldown：每 10 分鐘最多 deploy 一次\n2. 連續失敗 3 次自動停止（回扣 [CLAUDE.md 的 \"max 3 attempts\" rule](/blog/claude-md-rules-files-masterclass)）\n3. Deploy 前需要人工 confirm\n\n### 案例 2：差點 Push Credentials\n\nAgent 在修一個環境設定問題時，為了「方便測試」，把一個 API key 硬寫在 code 裡。然後它準備 commit + push。\n\n幸好 pre-commit hook 攔住了——我的 hook 裡有 credential 掃描（用 gitleaks），偵測到 API key pattern 就 block 了 commit。\n\n**根因**：Agent 不理解 secrets management。它的 goal 是「讓 code 能跑」，hardcode API key 就是達到這個 goal 最快的方式。\n\n**加了什麼防護**：\n\n1. Pre-commit 的 credential scanning（原本就有，救了一命）\n2. 在 CLAUDE.md 裡加了明確規則：「永遠不要 hardcode secrets，使用環境變數」\n3. `.env` 檔案加入 hook 的保護清單\n\n### 案例 3：Production Migration 驚魂\n\nAgent 寫了一個 database migration script，在 staging 跑得很順利。然後它「貼心地」準備了 production 的 migration command——包含 production database 的連線字串。\n\n如果我沒注意到那個 command 裡的 hostname 是 production 而不是 staging，然後不小心讓 agent 執行了...\n\n**根因**：Agent 不區分環境。它看到 staging 成功了，就按照同樣的模式準備 production 的指令。它不知道 production migration 需要完全不同的審批流程。\n\n**加了什麼防護**：\n\n1. Production 連線字串不在任何 agent 可以讀取的檔案裡\n2. 任何包含 `production` 或 `prod` 關鍵字的指令需要人工 confirm\n3. Database migration 永遠是 human-only 的操作\n\n## 權限的漸進式開放\n\n不建議一次開放所有權限。建議的漸進路徑：\n\n### Week 1-2：Read Only + Write Code\n\n```\n✅ 讀檔案\n✅ 寫 code（在 feature branch）\n✅ 跑 test / lint\n❌ Git commit（你手動做）\n❌ 安裝 packages\n❌ 執行任意 shell 命令\n```\n\n熟悉 agent 的行為模式。看它會做什麼決策、會犯什麼錯。\n\n### Week 3-4：加 Git 操作\n\n```\n✅ 以上全部\n✅ Git commit（到 feature branch）\n✅ 安裝 npm packages（需確認）\n❌ Git push\n❌ 操作外部系統\n```\n\n### Month 2+：加外部操作\n\n```\n✅ 以上全部\n✅ Git push（需確認）\n✅ MCP 操作（指定的 server）\n✅ Deploy to staging（需確認）\n❌ Deploy to production\n❌ Database 操作\n```\n\n### 永遠不要自動化的事\n\n有些操作，無論你對 agent 多有信心，永遠需要人工審批：\n\n- **Production deploy**\n- **Database migration on production**\n- **刪除 production 資料**\n- **修改 IAM / permissions**\n- **Push to main/master**\n\n這不是因為 agent 一定會搞砸，而是這些操作的 blast radius 太大，萬一搞砸了，recovery 成本遠高於多花 30 秒人工確認的成本。\n\n## 建立你的安全網 Checklist\n\n```markdown\n## Agent Safety Checklist\n\n### Sandbox\n\n- [ ] Agent 在 feature branch 上工作（永遠不碰 main）\n- [ ] 有方便的 rollback 方式（git reset / git branch -D）\n- [ ] Production credentials 不在 agent 可讀的範圍\n\n### Automated Guardrails\n\n- [ ] Pre-commit hooks：credential scanning、lint、type check\n- [ ] Sensitive file protection（.env、config with secrets）\n- [ ] Rate limiting on destructive operations\n- [ ] Max retry limit（3 次失敗自動停止）\n\n### Human-in-the-Loop\n\n- [ ] Git push 需要確認\n- [ ] Deploy 需要確認\n- [ ] 刪除操作需要確認\n- [ ] Production-related 操作需要確認\n\n### Monitoring\n\n- [ ] Agent 的操作有 log（至少 git history）\n- [ ] 異常行為有通知（連續失敗、大量操作）\n- [ ] 定期 review agent 的操作歷史\n```\n\n## Takeaway\n\n1. **Agent 安全不是「限制 agent」，而是「設計可控的自由度」**：三層架構（Sandbox → Hooks → Human-in-the-Loop）讓 agent 在安全邊界內最大化有用性，每一層擋不同類型的風險。\n\n2. **Git 是你最好的安全網**：Branch isolation 加上 easy rollback，覆蓋了大部分「agent 搞壞了東西」的場景。確保 agent 永遠在 feature branch 上工作。\n\n3. **每次 near-miss 都是加強安全網的機會**：不要等到真的出事。47 次 staging deploy 教我加 rate limit，差點 push credentials 教我加 secret scanning。把每次驚險經歷都轉化成一條新的 guardrail。\n\n---\n\n_上一篇：[Token 經濟學進階](/blog/agentic-engineering-cost-optimization)_\n_下一篇：[把 Agentic Engineering 帶進團隊](/blog/agentic-engineering-team-adoption)_", "summary": "給 agent 越多權限它越有用，但也越危險。設計一套「agent 安全網」——從 sandbox 環境、permission boundaries、rollback 機制、到 human-in-the-loop 的斷路器設計。附 hooks 設定和曾經差點出事的真實故事。", "image": "https://bobochen.dev/_astro/cover.JHWBRbC7.webp", "date_published": "2026-05-29T00:00:00.000Z", "tags": [ "Agentic Engineering", "資安", "Sandbox", "AI Safety", "Hooks" ] }, { "id": "https://bobochen.dev/blog/claude-api-guide-production-deployment/", "url": "https://bobochen.dev/blog/claude-api-guide-production-deployment/", "title": "生產環境部署：錯誤處理、限流與可觀測性", "content_text": "開發環境跑得好，不代表生產環境沒問題。本章全面解析 Rate Limits、指數退避、錯誤分類、API Key 安全管理、Logging 策略，以及 OpenTelemetry 整合——附 10 項生產環境部署 checklist。", "content_html": "你的應用在開發環境完美運作，每次 demo 都沒出問題。\n\n然後你把它部署到生產環境，十個用戶同時使用，五分鐘後你收到第一個錯誤報告。\n\n這個場景幾乎每個做 AI 應用的工程師都經歷過。開發環境和生產環境之間有個巨大的鴻溝，而這個鴻溝在 AI API 應用中特別明顯。\n\n## 開發環境 vs 生產環境的本質差異\n\n**並發性**：開發環境通常是你一個人在用，偶爾跑幾個測試。生產環境可能有幾十甚至幾百個請求同時進來——這意味著 Rate Limit 問題、資源競爭問題會突然全部冒出來。\n\n**錯誤頻率**：在開發環境，你的請求大部分都成功。生產環境中，網路問題、Anthropic API 的偶發故障、用戶輸入的邊緣 case——這些都會讓你看到你從來沒見過的錯誤。\n\n**可觀測性需求**：開發環境你可以直接 print() 來 debug。生產環境你需要結構化的 log、metrics、追蹤系統，因為當出問題的時候，你不在場。\n\n**成本壓力**：開發環境的錯誤和重試只花你一點時間。生產環境的錯誤和不必要的重試會直接換算成錢。\n\n這一章我要告訴你，一個 AI API 應用要進生產環境，需要做哪些事。\n\n## Rate Limits 完整解析\n\nAnthropic 的 Rate Limit 有四個維度，分別計算：\n\n**RPM（Requests Per Minute）**：每分鐘的請求次數限制。對多數用戶，這個限制在 50-2000 RPM 之間，視你的帳戶 tier 而定。\n\n**TPM（Tokens Per Minute）**：每分鐘的 token 使用量限制。這是最常觸發的限制——一個複雜的請求可能用掉 10K tokens，如果很多請求同時進來，很快就會碰到 TPM 上限。\n\n**ITPM（Input Tokens Per Minute）**：輸入 token 的專屬限制，有些 tier 對輸入 token 有獨立的限制。\n\n**OTPM（Output Tokens Per Minute）**：輸出 token 的專屬限制。如果你的應用需要生成大量長文，OTPM 可能是你最先碰到的瓶頸。\n\n查看你的帳戶限制：\n\n```bash\n# 透過 Anthropic Console API 查看\ncurl https://api.anthropic.com/v1/organizations/limits \\\n -H \"x-api-key: $ANTHROPIC_API_KEY\" \\\n -H \"anthropic-version: 2023-06-01\"\n```\n\n或是在 [console.anthropic.com](https://console.anthropic.com) 的 Settings → Limits 頁面查看。\n\n如果你需要更高的限制，可以在 Console 申請提高——通常需要幾個工作天審核，並且需要說明你的使用場景。\n\n當你碰到 Rate Limit，API 會回傳 HTTP 429 狀態碼，response 中會包含 `Retry-After` header，告訴你需要等待幾秒。\n\n## 指數退避的正確實作\n\n碰到 429 的時候，很多初學者的直覺是「等一秒再試」。但這是錯的。\n\n如果你有 100 個並發請求都在等一秒，一秒後它們同時再試，又同時碰到 429，然後又同時等一秒……這個「驚群效應（Thundering Herd）」會讓情況越來越糟。\n\n正確的做法是**指數退避（Exponential Backoff）加上隨機 Jitter**：\n\n```python\nimport anthropic\nimport time\nimport random\nimport logging\nfrom typing import Optional\n\nlogger = logging.getLogger(__name__)\n\nclass AnthropicClientWithRetry:\n def __init__(\n self,\n api_key: str,\n max_retries: int = 5,\n initial_delay: float = 1.0,\n max_delay: float = 60.0,\n exponential_base: float = 2.0,\n ):\n self.client = anthropic.Anthropic(api_key=api_key)\n self.max_retries = max_retries\n self.initial_delay = initial_delay\n self.max_delay = max_delay\n self.exponential_base = exponential_base\n\n def create_message(self, **kwargs) -> anthropic.Message:\n \"\"\"帶有指數退避重試的 message 建立\"\"\"\n last_exception = None\n\n for attempt in range(self.max_retries + 1):\n try:\n response = self.client.messages.create(**kwargs)\n if attempt > 0:\n logger.info(f\"請求在第 {attempt + 1} 次嘗試成功\")\n return response\n\n except anthropic.RateLimitError as e:\n last_exception = e\n if attempt == self.max_retries:\n logger.error(f\"達到最大重試次數 ({self.max_retries})，放棄\")\n raise\n\n # 從 Retry-After header 取得等待時間（如果有的話）\n retry_after = e.response.headers.get(\"Retry-After\")\n if retry_after:\n wait_time = float(retry_after)\n else:\n # 指數退避 + jitter\n wait_time = min(\n self.initial_delay * (self.exponential_base ** attempt),\n self.max_delay\n )\n # 加入 ±25% 的隨機 jitter，防止驚群效應\n wait_time *= (0.75 + random.random() * 0.5)\n\n logger.warning(\n f\"Rate limit 觸發 (429)，等待 {wait_time:.1f} 秒後重試 \"\n f\"(第 {attempt + 1}/{self.max_retries} 次)\"\n )\n time.sleep(wait_time)\n\n except anthropic.APIStatusError as e:\n # 5xx 錯誤：Anthropic server 問題，可以重試\n if e.status_code >= 500:\n last_exception = e\n if attempt == self.max_retries:\n raise\n\n wait_time = min(\n self.initial_delay * (self.exponential_base ** attempt),\n self.max_delay\n ) * (0.75 + random.random() * 0.5)\n\n logger.warning(\n f\"Server error ({e.status_code})，等待 {wait_time:.1f} 秒後重試\"\n )\n time.sleep(wait_time)\n else:\n # 4xx 錯誤（除了 429）：客戶端錯誤，不要重試\n raise\n\n except anthropic.APIConnectionError as e:\n # 網路連線問題，可以重試\n last_exception = e\n if attempt == self.max_retries:\n raise\n\n wait_time = min(\n self.initial_delay * (self.exponential_base ** attempt),\n self.max_delay\n )\n logger.warning(f\"連線錯誤，等待 {wait_time:.1f} 秒後重試\")\n time.sleep(wait_time)\n\n raise last_exception\n```\n\n這個實作處理了三種可重試的情況：Rate Limit（429）、Server Error（5xx）、連線錯誤。每次重試的等待時間是上一次的 2 倍，再加上隨機 jitter，避免驚群效應。\n\n實際上，Anthropic 的官方 Python SDK 已經內建了類似的重試邏輯：\n\n```python\n# SDK 內建重試，最多重試 2 次\nclient = anthropic.Anthropic(\n api_key=\"...\",\n max_retries=2, # 預設就是 2\n timeout=30.0, # 請求 timeout（秒）\n)\n```\n\n但我推薦自己控制重試邏輯，因為你可以加入更細緻的 logging 和 metrics，知道重試發生的頻率——頻繁的重試是一個需要關注的信號。\n\n## 錯誤分類與對應策略\n\n不同類型的錯誤需要不同的處理策略。\n\n**可重試的錯誤：**\n\n| 錯誤類型 | HTTP 狀態碼 | 說明 | 策略 |\n| ------------------------- | ----------- | --------------------- | ------------------------ |\n| `RateLimitError` | 429 | 超過 Rate Limit | 指數退避重試 |\n| `InternalServerError` | 500 | Anthropic server 問題 | 短暫等待後重試 |\n| `ServiceUnavailableError` | 503 | 服務維護或過載 | 長時間等待後重試 |\n| `APIConnectionError` | N/A | 網路問題 | 重試 |\n| `APITimeoutError` | N/A | 請求逾時 | 重試（考慮增加 timeout） |\n\n**不可重試的錯誤（客戶端錯誤）：**\n\n| 錯誤類型 | HTTP 狀態碼 | 常見原因 | 策略 |\n| ----------------------- | ----------- | -------------------------- | ------------------------------ |\n| `AuthenticationError` | 401 | API Key 無效或已撤銷 | 檢查 API Key，告警 |\n| `PermissionDeniedError` | 403 | 沒有使用某個功能的權限 | 檢查帳戶設定 |\n| `NotFoundError` | 404 | 請求了不存在的資源 | 修復 bug |\n| `BadRequestError` | 400 | 請求格式錯誤 | 修復 bug，可能需要記錄 request |\n| `RequestTooLargeError` | 413 | 輸入超過 context window | 截斷輸入，記錄 |\n\n```python\nfrom anthropic import (\n Anthropic,\n AuthenticationError,\n PermissionDeniedError,\n RateLimitError,\n BadRequestError,\n APIConnectionError,\n InternalServerError,\n)\n\ndef handle_anthropic_error(e: Exception, context: dict) -> str:\n \"\"\"統一的錯誤處理，回傳用戶友好的訊息\"\"\"\n\n if isinstance(e, AuthenticationError):\n # 這是嚴重問題——API Key 有問題，要告警給工程師\n logger.critical(\"API Key 認證失敗，需要立即檢查\", extra=context)\n # 觸發 PagerDuty/Slack 告警\n alert_on_call_engineer(\"API Key 認證失敗\")\n return \"服務暫時無法使用，我們已收到通知並正在處理\"\n\n elif isinstance(e, RateLimitError):\n # 已在重試邏輯中處理，到這裡代表重試用盡了\n logger.error(\"Rate limit 重試用盡\", extra=context)\n return \"目前服務繁忙，請稍後再試\"\n\n elif isinstance(e, BadRequestError):\n # 可能是用戶輸入有問題，也可能是 bug\n error_msg = str(e)\n if \"too many tokens\" in error_msg.lower():\n logger.warning(\"輸入過長\", extra={**context, \"error\": error_msg})\n return \"您的輸入太長，請縮短後再試\"\n else:\n logger.error(\"Bad request\", extra={**context, \"error\": error_msg})\n return \"請求格式有誤，請重試\"\n\n elif isinstance(e, InternalServerError):\n logger.error(\"Anthropic server error\", extra=context)\n return \"AI 服務暫時不穩定，請稍後再試\"\n\n else:\n logger.exception(\"未預期的錯誤\", extra=context)\n return \"發生未知錯誤，請重試\"\n```\n\n## API Key 安全管理\n\nAPI Key 洩漏是 AI 應用最常見的安全事故之一。我見過有人把 API Key 直接 hardcode 在程式碼裡，commit 到 GitHub，然後一週內被人濫用了幾萬塊錢。\n\n**永遠不要做的事：**\n\n```python\n# ❌ 錯誤：hardcode 在程式碼中\nclient = anthropic.Anthropic(api_key=\"sk-ant-api03-xxxxx\")\n\n# ❌ 錯誤：commit 到 git\n# 就算你之後刪掉，git history 還是看得到\n```\n\n**正確做法：**\n\n```python\n# ✅ 從環境變數讀取\nimport os\nimport anthropic\n\n# SDK 預設就會讀 ANTHROPIC_API_KEY 環境變數\nclient = anthropic.Anthropic() # 自動讀取 os.environ[\"ANTHROPIC_API_KEY\"]\n\n# 或明確指定\nclient = anthropic.Anthropic(api_key=os.environ[\"ANTHROPIC_API_KEY\"])\n```\n\n**在生產環境使用 Secret Manager：**\n\n```python\n# Google Cloud Secret Manager 範例\nfrom google.cloud import secretmanager\n\ndef get_api_key() -> str:\n client = secretmanager.SecretManagerServiceClient()\n name = f\"projects/{PROJECT_ID}/secrets/anthropic-api-key/versions/latest\"\n response = client.access_secret_version(request={\"name\": name})\n return response.payload.data.decode(\"UTF-8\")\n\n# 在應用啟動時（不是每次請求時）取得 key\nANTHROPIC_API_KEY = get_api_key()\nanthropic_client = anthropic.Anthropic(api_key=ANTHROPIC_API_KEY)\n```\n\n另一個重要建議：**為不同環境使用不同的 API Key**。開發環境、staging 環境、生產環境各自一個 Key。這樣當某個環境的 Key 洩漏，其他環境不受影響，而且你可以透過 Anthropic Console 查看不同 Key 的使用量，更容易追蹤問題。\n\n## Logging 策略\n\nLog 要記什麼？不記什麼？這個問題比大多數人想的複雜。\n\n**要記錄的：**\n\n- 請求 ID（`x-request-id` header）——這是 debug 的生命線\n- 使用的 model、max_tokens\n- 回應的 token 使用量（input/output/cache）\n- 請求延遲（從送出到收到回應的時間）\n- 錯誤類型和錯誤訊息\n- 用戶 ID 或 session ID（匿名的，用於追蹤使用模式）\n\n**不要記錄的：**\n\n- 用戶的完整 prompt（可能包含個人資訊）\n- API Key\n- 任何 PII（個人識別資訊）\n\n```python\nimport anthropic\nimport time\nimport logging\nimport uuid\n\nlogger = logging.getLogger(__name__)\nclient = anthropic.Anthropic()\n\ndef call_api_with_logging(\n messages: list,\n system: str,\n model: str = \"claude-3-5-sonnet-20241022\",\n user_id: str = None,\n feature: str = \"unknown\"\n) -> anthropic.Message:\n \"\"\"帶有完整 logging 的 API 呼叫\"\"\"\n request_id = str(uuid.uuid4())\n start_time = time.time()\n\n # 記錄請求（注意：不記錄 prompt 內容）\n logger.info(\"api_request_started\", extra={\n \"request_id\": request_id,\n \"feature\": feature,\n \"model\": model,\n \"user_id\": user_id, # 應該是匿名 ID，不是真實用戶資料\n \"message_count\": len(messages),\n # 記錄 prompt 的 token 估算，但不記錄內容\n \"estimated_input_chars\": sum(len(str(m.get(\"content\", \"\"))) for m in messages),\n })\n\n try:\n response = client.messages.create(\n model=model,\n max_tokens=1024,\n system=system,\n messages=messages,\n )\n\n latency_ms = (time.time() - start_time) * 1000\n usage = response.usage\n\n # 從回應 headers 取得 Anthropic 的 request ID（用於聯繫 support）\n anthropic_request_id = response._request_id # SDK 中的 request ID\n\n logger.info(\"api_request_succeeded\", extra={\n \"request_id\": request_id,\n \"anthropic_request_id\": anthropic_request_id,\n \"feature\": feature,\n \"model\": model,\n \"latency_ms\": round(latency_ms),\n \"input_tokens\": usage.input_tokens,\n \"output_tokens\": usage.output_tokens,\n \"cache_read_tokens\": getattr(usage, 'cache_read_input_tokens', 0),\n \"cache_creation_tokens\": getattr(usage, 'cache_creation_input_tokens', 0),\n \"stop_reason\": response.stop_reason,\n })\n\n return response\n\n except Exception as e:\n latency_ms = (time.time() - start_time) * 1000\n logger.error(\"api_request_failed\", extra={\n \"request_id\": request_id,\n \"feature\": feature,\n \"model\": model,\n \"latency_ms\": round(latency_ms),\n \"error_type\": type(e).__name__,\n \"error_message\": str(e)[:200], # 截斷，避免 log 過大\n })\n raise\n```\n\n## OpenTelemetry 整合\n\n結構化 logging 只是開始。在生產環境，你還需要**分散式追蹤（Distributed Tracing）**——尤其是當你的 AI 功能只是更大系統的一部分時。\n\n```python\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import BatchSpanProcessor\nfrom opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter\nimport anthropic\n\n# 設定 OpenTelemetry\nprovider = TracerProvider()\notlp_exporter = OTLPSpanExporter(endpoint=\"http://otel-collector:4317\")\nprovider.add_span_processor(BatchSpanProcessor(otlp_exporter))\ntrace.set_tracer_provider(provider)\n\ntracer = trace.get_tracer(\"ai-service\")\nclient = anthropic.Anthropic()\n\ndef answer_question(user_question: str, context: str, user_id: str) -> str:\n \"\"\"帶有 OpenTelemetry 追蹤的 API 呼叫\"\"\"\n with tracer.start_as_current_span(\"claude_api_call\") as span:\n # 設定 span 屬性（不包含個人資訊）\n span.set_attribute(\"ai.model\", \"claude-3-5-sonnet-20241022\")\n span.set_attribute(\"ai.feature\", \"question_answering\")\n span.set_attribute(\"user.id\", user_id)\n\n try:\n response = client.messages.create(\n model=\"claude-3-5-sonnet-20241022\",\n max_tokens=1024,\n system=\"你是一個有幫助的助手。\",\n messages=[{\"role\": \"user\", \"content\": user_question}]\n )\n\n # 記錄結果 metrics\n usage = response.usage\n span.set_attribute(\"ai.input_tokens\", usage.input_tokens)\n span.set_attribute(\"ai.output_tokens\", usage.output_tokens)\n span.set_attribute(\"ai.stop_reason\", response.stop_reason)\n\n return response.content[0].text\n\n except Exception as e:\n span.record_exception(e)\n span.set_status(trace.StatusCode.ERROR, str(e))\n raise\n```\n\n## Latency 監控\n\nAPI 延遲是用戶體驗的核心指標。claude-3-5-sonnet 的典型延遲在 1-10 秒之間，視 prompt 長度和輸出長度而定。\n\n你應該監控 P50（中位數）、P95（第 95 百分位）、P99——不只是平均值。平均值會隱藏問題，P99 才能反映最差的用戶體驗。\n\n```python\nimport time\nfrom collections import deque\nimport threading\nimport statistics\n\nclass LatencyTracker:\n def __init__(self, window_size: int = 1000):\n self.latencies = deque(maxlen=window_size)\n self.lock = threading.Lock()\n\n def record(self, latency_ms: float):\n with self.lock:\n self.latencies.append(latency_ms)\n\n def get_percentiles(self) -> dict:\n with self.lock:\n if not self.latencies:\n return {}\n sorted_latencies = sorted(self.latencies)\n n = len(sorted_latencies)\n return {\n \"p50\": sorted_latencies[int(n * 0.50)],\n \"p95\": sorted_latencies[int(n * 0.95)],\n \"p99\": sorted_latencies[int(n * 0.99)],\n \"max\": sorted_latencies[-1],\n \"count\": n,\n }\n\nlatency_tracker = LatencyTracker()\n```\n\n如果你的 P99 延遲突然從 5 秒跳到 30 秒，這是一個嚴重的信號——可能是 Anthropic 服務有問題，或是你的 prompt 突然變長了。\n\n## Fallback 策略：降級到更便宜的模型\n\n當 Sonnet 不可用或響應過慢，降級到 Haiku 是一個有效的 fallback：\n\n```python\nimport anthropic\nfrom typing import Optional\n\nclient = anthropic.Anthropic()\n\nMODELS = {\n \"primary\": \"claude-3-5-sonnet-20241022\",\n \"fallback\": \"claude-3-5-haiku-20241022\",\n}\n\ndef create_message_with_fallback(\n messages: list,\n system: str,\n max_tokens: int = 1024,\n timeout: float = 30.0\n) -> tuple[anthropic.Message, str]:\n \"\"\"先嘗試主要模型，失敗則降級\"\"\"\n\n for model_tier, model in MODELS.items():\n try:\n response = client.messages.create(\n model=model,\n max_tokens=max_tokens,\n system=system,\n messages=messages,\n timeout=timeout,\n )\n if model_tier == \"fallback\":\n logger.warning(f\"使用了 fallback 模型: {model}\")\n return response, model_tier\n\n except anthropic.InternalServerError as e:\n if model_tier == \"primary\":\n logger.warning(f\"主要模型 {model} 不可用，嘗試 fallback\")\n continue\n else:\n raise # fallback 也失敗了，真的出問題了\n\n except anthropic.APITimeoutError:\n if model_tier == \"primary\":\n logger.warning(f\"主要模型 {model} 超時，嘗試 fallback\")\n continue\n else:\n raise\n```\n\n## 生產環境 10 項 Checklist\n\n在部署你的 AI 應用到生產環境之前，確認這 10 項：\n\n**[1] API Key 安全**\n\n- [ ] API Key 存放在環境變數或 Secret Manager，不在程式碼中\n- [ ] 不同環境使用不同的 API Key\n- [ ] `.gitignore` 有排除 `.env` 檔案\n\n**[2] 錯誤處理**\n\n- [ ] 所有 API 呼叫都有 try/except\n- [ ] 429 錯誤有指數退避重試\n- [ ] 4xx 客戶端錯誤不重試\n- [ ] 錯誤訊息對用戶友好（不暴露技術細節）\n\n**[3] Rate Limit 管理**\n\n- [ ] 了解你帳戶的 RPM 和 TPM 限制\n- [ ] 有機制監控目前的使用量\n- [ ] 有 queue 或 semaphore 控制最大並發請求數\n\n**[4] Timeout 設定**\n\n- [ ] 所有請求都有設定合理的 timeout\n- [ ] Streaming 請求有設定 connection timeout\n\n**[5] Logging**\n\n- [ ] 每次 API 呼叫都記錄延遲和 token 使用量\n- [ ] 錯誤有完整的 context 資訊\n- [ ] Log 中不包含 PII 或 API Key\n\n**[6] 監控和告警**\n\n- [ ] P95/P99 延遲有告警\n- [ ] 錯誤率有告警\n- [ ] API 費用有告警（設定每日/每月上限）\n\n**[7] 輸入驗證**\n\n- [ ] 用戶輸入有長度限制（防止 context window 爆炸）\n- [ ] 有基本的輸入清理\n\n**[8] Fallback 機制**\n\n- [ ] 主要模型不可用時有降級方案\n- [ ] 完全降級時有友好的錯誤提示\n\n**[9] 成本控制**\n\n- [ ] 啟用 Prompt Caching（如果適合）\n- [ ] max_tokens 設定合理的上限\n- [ ] 有成本監控 dashboard\n\n**[10] 運作驗證**\n\n- [ ] 有 health check endpoint（確認 Anthropic API 可達）\n- [ ] 有 staging 環境，部署前先驗證\n- [ ] 有 rollback 計劃\n\n完成這十項，你的 AI 應用才算真正準備好面對生產環境的挑戰。\n\n---\n\n這本書的前十四章，我們從最基礎的 Messages API 一路走到 multi-agent 系統、MCP Server、成本優化、生產部署。現在是最後一章——把所有這些拼在一起，建立一個真實的、可以部署的 AI 客服系統。", "summary": "開發環境跑得好，不代表生產環境沒問題。本章全面解析 Rate Limits、指數退避、錯誤分類、API Key 安全管理、Logging 策略，以及 OpenTelemetry 整合——附 10 項生產環境部署 checklist。", "image": "https://bobochen.dev/_astro/cover.Bn4ECRom.webp", "date_published": "2026-05-29T00:00:00.000Z", "tags": [ "Claude API", "生產環境", "錯誤處理", "可觀測性", "Rate Limit" ] }, { "id": "https://bobochen.dev/blog/competition-vs-dense-ranking-map-labels/", "url": "https://bobochen.dev/blog/competition-vs-dense-ranking-map-labels/", "title": "競爭排名 vs 密集排名 vs 百分位：地圖標籤的 ranking 設計", "content_text": "7,748 個村里，最大排名居然不是 7,748？做 TaxMap-TW 排名功能才發現「排名」有 5 種演算法，差別都在同分怎麼處理。比較 Competition、Dense、Standard 等的適用情境，說明地圖標籤為什麼選 Competition Ranking。", "content_html": "[TaxMap-TW](https://github.com/bobo52310/TaxMap-TW) 的每個村里詳細頁都顯示「全國第 #58 / 7,748」這種排名。\n\n我以為這是 5 分鐘的事：\n\n```typescript\nsorted.sort((a, b) => b.value - a.value);\nconst rank = sorted.findIndex(v => v.code === target.code) + 1;\n```\n\n寫完跑一下 verify 腳本，發現一個怪事：\n\n```text\nMax national rank == village count (7,748): expected 7748, got 7744 ✗\n```\n\n最大排名是 **7,744**，不是 7,748。為什麼？\n\n挖下去發現「排名」其實有 5 種演算法，差別都在「同分怎麼處理」。這篇整理 5 種 ranking 演算法、選擇邏輯、以及為什麼地圖視覺化選 Competition Ranking。\n\n## 排名為什麼會少 4 名？\n\n先確認問題：\n\n```typescript\nconst lowest = Object.entries(r.rankings)\n .map(([k, v]) => ({ key: k, rank: v.median.national.rank }))\n .sort((a, b) => b.rank - a.rank)\n .slice(0, 5);\n// [\n// { key: '新北市|石碇區|碧山里', rank: 7744 },\n// { key: '宜蘭縣|大同鄉|土場村', rank: 7744 },\n// { key: '澎湖縣|馬公市|新復里', rank: 7744 },\n// { key: '臺南市|南區|荔宅里', rank: 7743 },\n// { key: '新北市|瑞芳區|碩仁里', rank: 7742 },\n// ]\n```\n\n3 個村里**並列 7744 名**。他們的中位數所得都是 0（沒有任何納稅單位申報）。\n\n照「直觀」排名應該是 7746、7747、7748 — 但實際是 7744、7744、7744。\n\n這就是 **Competition Ranking** 在「並列最後一名」時的行為：**並列共享一個排名，剩下的名次被「跳過」**。\n\n## 5 種 ranking 演算法\n\n維基百科把排名演算法分成 5 種。用 `[100, 90, 90, 80, 70]` 當範例：\n\n### 1. Standard Ranking（也稱 Ordinal Ranking，1, 2, 3, 4, 5）\n\n> 維基百科把這個序列正名為 Ordinal ranking。我這裡沿用程式裡寫的 Standard 名稱，但它對應的就是維基的 Ordinal。\n\n```typescript\nsorted.indexOf(target) + 1; // 比物件參考而非值，同分也各自拿到唯一名次\n```\n\n簡單按 index 排，每個人都拿到唯一名次、永遠剛好 1 到 N。代價是同分時誰排前面取決於 sort 的細節 —— 如果你只用 `value` 排，同一個值可能拿到 2 或 3，結果不穩定。\n\n❌ 沒定義 tie-breaker 時不適合公開展示，因為名次會跟著排序實作飄。\n✅ 但只要補一個次要排序鍵（村里代碼、名稱字典序），它就變 deterministic，而且是「需要強制唯一名次」時的正解 —— 像分頁、產生穩定的 URL、做有序匯出，你就是不想看到並列。我自己的看法：Ordinal 不是壞演算法，只是它的「壞」全來自你沒把 tie-breaker 想清楚。\n\n### 2. Competition Ranking (1, 2, 2, 4, 5)\n\n同分共享名次，**下一個名次跳過**（\"olympic ranking\"）。\n\n```typescript\nfunction competitionRank(entries: { key: string; value: number }[]) {\n const sorted = [...entries].sort((a, b) => b.value - a.value);\n const ranks = new Map();\n let lastValue: number | null = null;\n let lastRank = 0;\n for (let i = 0; i < sorted.length; i++) {\n const { key, value } = sorted[i];\n const rank = value === lastValue ? lastRank : i + 1;\n ranks.set(key, rank);\n lastValue = value;\n lastRank = rank;\n }\n return ranks;\n}\n```\n\n✅ 公平、直覺、廣泛使用於體育（奧運、F1）。\n❌ 最大排名可能 < N（並列尾巴會壓縮）。\n\n### 3. Modified Competition Ranking (1, 3, 3, 4, 5)\n\n同分共享，**但跳過的是「前面」**（同分組共享後面的名次）。\n\n```text\n[100, 90, 90, 80, 70]\n 1 3 3 4 5\n```\n\n✅ 跟 Competition 一樣公平，但對「並列第二」的視覺感更強（不是 2、2，而是 3、3）。\n❌ 直覺上有點怪，少用。\n\n### 4. Dense Ranking (1, 2, 2, 3, 4)\n\n同分共享，**下一個名次不跳過**。\n\n```typescript\nfunction denseRank(entries: { key: string; value: number }[]) {\n const sorted = [...entries].sort((a, b) => b.value - a.value);\n const ranks = new Map();\n let lastValue: number | null = null;\n let currentRank = 0;\n for (const { key, value } of sorted) {\n if (value !== lastValue) currentRank++;\n ranks.set(key, currentRank);\n lastValue = value;\n }\n return ranks;\n}\n```\n\n✅ 最大排名 = 唯一值的數量。「全國第 X 級」這種概念上更貼。\n❌ 不直覺：你拿第 5 名可能其實是第 10 個人（前面有人並列）。\n\nDense 不是 Competition 的次等品，它有自己最對味的場景：**當重複值很多、或你想傳達的是「分到第幾級」而不是「絕對名次」時，Dense 更合適**。比方價格分 A/B/C/D 級、遊戲段位、或像我這個案例如果中位數所得只切成 5 段級距，Dense 給的「第幾級」反而比 Competition 的稀疏名次更好讀。我自己的取捨很簡單：使用者腦中想的是「我在第幾名」就用 Competition，是「我在哪一級」就用 Dense。\n\n### 5. Fractional Ranking (1, 2.5, 2.5, 4, 5)\n\n同分組分享「平均排名」。\n\n```text\n[100, 90, 90, 80, 70]\n 1 2.5 2.5 4 5\n```\n\n✅ 統計學正統（用於 Mann-Whitney U test 等非參數檢定）。\n❌ 出現小數，user-facing 不好看（「你是第 2.5 名」🤔）。\n\n## SQL 對照\n\nSQL 有對應的 window function，方便理解：\n\n| 演算法 | SQL Window Function |\n|--------|---------------------|\n| Standard | `ROW_NUMBER()` |\n| Competition | `RANK()` |\n| Modified Competition | （無原生支援）|\n| Dense | `DENSE_RANK()` |\n| Fractional | （無原生支援）|\n\n如果你用 PostgreSQL / MySQL，`RANK()` 就是 Competition Ranking。\n\n## TaxMap-TW 為什麼選 Competition Ranking\n\n對「展示給使用者看」這個場景，候選是 Competition vs Dense。我選了 Competition：\n\n**1. 跟體育、考試成績一致**\n\n讀者看到「第 58 名 / 7,748」會自動套用「奧運排名」的直覺。這是 Competition Ranking 的語意。\n\n**2. 同分共享給予正確的「相對位置」**\n\n如果 3 個村里中位數都是 0，他們的「位置」就是相同的，應該共享同一個排名。Dense Ranking 反而會說他們是「第 N 級」，但這層抽象對地圖讀者意義不大。\n\n**3. 「跳過名次」這件事其實 OK**\n\nverify 腳本第一次失敗讓我以為這是 bug，但仔細想：**沒有「第 7745 名、7746 名、7747 名」這 3 個位置是合理的** — 因為有 3 個人並列 7744。\n\n我把 verify 腳本的斷言從 `===` 改成 `<=`：\n\n```typescript\ncheck(\n `${y} max national rank ≤ village count (${count})`,\n maxRank <= count,\n);\n```\n\n**Competition 的代價我也認**：最大排名 < N 這件事，第一眼確實會讓人懷疑「是不是漏算了」（我自己就被 verify 腳本嚇到一次）；而且如果底部並列的村里很多 —— 像有一大票里中位數都是 0 —— Competition 會把它們全壓到同一個名次，名次的尾段等於被「壓扁」，看不出彼此差異。我覺得在這個案例可以接受，是因為那批所得 0 的村里本來就「沒有差異可言」，給它們同一名次反而誠實；要是換成一份重複值很密、又需要在尾段分出高下的資料，我就會回頭選 Dense。\n\n## 跨年「比去年變動」的計算\n\n排名穩定後，下一個需求是「比去年上升 / 下降幾名」（YoY delta）：\n\n```typescript\nconst deltaYoY = previousYearRank - currentYearRank;\n// 正值 = 名次上升（rank 數字變小）\n// 負值 = 名次下降\n// 0 = 持平\n// null = 去年無資料\n```\n\n注意正負號：rank 是「越小越好」，所以 delta = 去年 - 今年。\n\n實際範例（中華里 2022 vs 2021）：\n\n```text\n2021 全國中位數第 85 名\n2022 全國中位數第 58 名\nDelta = 85 - 58 = +27（上升 27 名）\n```\n\nUI 顯示：↑ 27（綠色 chip）。\n\n**邊界情況**：\n\n- 去年該村里無資料 → delta = null（顯示 \"—\"）\n- 今年該村里無資料 → 不顯示卡片\n- delta = 0 → 顯示「持平」（不是 ↑0 也不是 ↓0）\n\n## 排名 vs 百分位 — 兩個都要\n\n地圖視覺化常會搞混「排名」和「百分位」這兩個概念：\n\n**排名**（rank）：絕對位置，用於展示\n\n> 你的村里中位數所得 95 萬，全國第 58 名 / 7,748\n\n**百分位**（percentile）：分布位置，用於色階分級\n\n> 你的村里中位數所得 95 萬，落在全國第 80 百分位（前 20% 的村里）\n\n我一開始想偷懶，打算用排名直接驅動色階 —— 結果地圖糊成一片才想起這兩個根本不能混用：\n\n- 詳細頁的大數字 → 用排名\n- 地圖上的色塊 → 用百分位（quintile 分 5 級對應 5 種顏色）\n\n百分位適合視覺化的理由是 **單調性**：第 50 百分位以下的村里色塊都比第 50 以上淺。但如果用排名，第 100 名和第 7000 名的色塊差異會被視覺壓縮（因為 1-7748 是線性的，但人眼的「淺到深」感受不是線性）。\n\n不過用 quantile（等樣本數分桶）分級也不是沒代價：它保證每一級村里數量相等，但會把「值很接近、卻剛好跨桶邊界」的兩個村里塗成不同顏色，也會把「值差很多、卻擠在同一桶」的村里塗成同色 —— 所得這種長尾分布尤其明顯，最高那一桶可能從 200 萬一路涵蓋到 500 萬。所以分桶到底用 quantile 還是改用絕對門檻，本身就是另一個決策，我在色階那篇有完整討論。\n\n色階分級的詳細討論在 [這篇色階文章](/blog/data-map-color-scale-viridis-ylgnbu)；至於最後我為什麼把色階從 viridis 換成 OrRd、怎麼把分桶和選色拆成兩個獨立決策，寫在 [為什麼我把所得地圖色階從 viridis 換成 OrRd](/blog/orrd-warm-palette-two-decisions-framework)。\n\n## 反思\n\n本來估 5 分鐘搞定的功能，最後花了一個晚上讀維基百科的 ranking 條目、再回頭把 verify 腳本改一遍。讓我意外的不是排名很難，而是它根本不是一件事 —— `sort` 完寫個 index 的時候，我以為「排名」就是排名，完全沒意識到自己已經默默選了 Ordinal、還沒處理同分。\n\n這種「以為是常識、其實是默認選擇」的感覺很熟悉，做色階分級那次也一模一樣：當時把資料丟進 quantile 分 5 級就覺得理所當然，後來才發現「要不要等樣本數分桶」本身就是個有後果的決定。兩次都是同一個教訓 —— 看起來最沒爭議的步驟，往往藏著你沒注意到自己做了的選擇。也因為這樣，我現在會刻意把「展示給使用者的數字」和「拿去算的數字」分開：詳細頁的大數字用 rank 求直覺，地圖色塊用 percentile 求單調，硬要共用一個 metric 只會兩邊都將就。\n\n最有趣的觀察是 SQL window function 命名：`RANK()` 是 Competition，`DENSE_RANK()` 才是 Dense。也就是 SQL 標準把沒前綴的 `RANK()` 對應到 Competition。當然這不代表所有領域都這樣 —— 統計檢定預設用 Fractional、有些排行榜要的是 Dense —— 但至少在資料庫的世界，「排名」沒特別說明時通常指 Competition。\n\n## 系列其他文章\n\n- → [Web 地圖底圖是什麼？vector vs raster、tile pyramid、style spec 一次搞懂](/blog/web-map-tile-basics-vector-raster-style)\n- → [OpenFreeMap vs MapTiler vs Mapbox：6 個 Web 地圖底圖服務怎麼選？](/blog/openfreemap-maptiler-base-map-comparison)\n- → [從 PDF / CSV 到 JSON：政府開放資料的 ETL 實戰](/blog/tw-gov-open-data-csv-etl-fia-tax)\n- → [資料地圖該用哪種色階？viridis、YlGnBu 與 ColorBrewer 實戰指南](/blog/data-map-color-scale-viridis-ylgnbu)\n- → [為什麼我把所得地圖色階從 viridis 換成 OrRd：把「一個決策」拆成「兩個獨立軸」](/blog/orrd-warm-palette-two-decisions-framework)\n- → [打造 TaxMap-TW 完整心得：6 個技術決策、踩了 4 個坑](/blog/taxmap-tw-postmortem-6-decisions-4-pitfalls)", "summary": "7,748 個村里，最大排名居然不是 7,748？做 TaxMap-TW 排名功能才發現「排名」有 5 種演算法，差別都在同分怎麼處理。比較 Competition、Dense、Standard 等的適用情境，說明地圖標籤為什麼選 Competition Ranking。", "image": "https://bobochen.dev/_astro/cover.DhzV_Pt2.webp", "date_published": "2026-05-27T00:00:00.000Z", "tags": [ "資料視覺化", "演算法", "Ranking", "SQL", "TypeScript" ] }, { "id": "https://bobochen.dev/blog/data-map-color-scale-viridis-ylgnbu/", "url": "https://bobochen.dev/blog/data-map-color-scale-viridis-ylgnbu/", "title": "資料地圖該用哪種色階？viridis、YlGnBu 與 ColorBrewer 實戰指南", "content_text": "資料地圖（Choropleth）該用哪種色階？做台灣所得稅 TaxMap 時原本想用 viridis，最後換成 ColorBrewer 的 YlGnBu + Jenks 自然斷點。整理 7 種主流連續色階比較、為什麼紅綠對比是地雷、長尾分布怎麼分級、以及 opacity × 基底圖的隱藏陷阱。", "content_html": "最近在做 [TaxMap-TW](https://github.com/bobo52310/TaxMap-TW)：一張顯示全台灣 7,747 個村里所得稅統計的互動地圖。要為每個 polygon 上色時，第一個問題就讓我卡了一小時：\n\n**「Choropleth 地圖該用哪種色階？」**\n\n我以為這是 30 秒就能決定的設計問題。結果發現裡面有色盲議題、ColorBrewer 業界標準、長尾分布陷阱、以及跟基底圖的 opacity 互動，每一個都是踩過才知道的坑。\n\n這篇整理那一小時學到的東西。\n\n## 資料地圖的色階到底在解什麼問題\n\nChoropleth（音「克羅羅普列斯」，沒人念得對）就是「**用顏色表達數值**」的地圖：每個區域填一個顏色，深淺對應到該區的某個統計量。\n\n聽起來很簡單，但你的每一個選擇都在影響讀者：\n\n- **色相**（hue）：用紅、藍、綠表達不同的情緒\n- **明度漸層**：表達數值大小\n- **分級方式**：把連續數值切成幾個顏色區間\n- **透明度**：跟下層地圖怎麼疊\n- **色階方向**：低→高還是高→低\n\n每個選擇都可能讓讀者看到「不存在的趨勢」或「忽略真實的差異」。這不是美感問題，是**會不會誤導讀者**的問題。\n\n## 七種主流色階快速比較\n\n直接拿我整理出的比較表：\n\n| 色階 | 視覺風格 | 適合場景 | 陷阱 |\n|------|---------|---------|------|\n| **Viridis** | 紫→藍→綠→黃 | 學術、中性嚴肅 | 不夠吸睛 |\n| **YlGnBu** | 淺黃→綠→深藍 | 公部門報告、所得 / 教育 | 深色端容易跟水體混 |\n| **YlOrRd** | 黃→橘→紅 | 媒體、社群、視覺衝擊 | 紅色易被解讀為「壞」 |\n| **Plasma / Magma** | 黑→紫→紅→黃 | 深色模式、有質感 | 需要深底搭配 |\n| **Greys** | 淺灰→深灰 | 極簡、副地圖 | 訊息密度低 |\n| **Red-Green** | 紅→黃→綠 | ❌ 不推薦 | 8% 男性紅綠色盲無法區分 |\n| **Diverging (RdBu)** | 紅←白→藍 | 雙向偏離（如「相對於平均」） | 不適合單向資料 |\n\n前五個是 **sequential（單向）色階**，適合「越多越深」這種單方向遞增的資料；最後一個是 **diverging（雙向）色階**，適合表達相對於某個中心點的偏離（例如選舉得票率相對於 50%）。\n\n選錯類型會給錯誤的暗示——例如用 diverging 的紅藍色階畫所得，會讓讀者以為「藍色那邊比紅色那邊好或壞」，但其實只有「多」跟「少」。\n\n## Viridis：學術派的最愛\n\nViridis 是 Python `matplotlib` 在 2015 年導入的色階，後來變成科學論文的視覺標配。它的三個特性：\n\n1. **感知均勻（perceptually uniform）**：你眼睛看到的「色差」跟資料本身的「數值差」是線性對應的\n2. **色盲友善**：deuteranopia（綠色盲）跟 protanopia（紅色盲）讀者也能正確分辨\n3. **黑白列印也能用**：因為亮度本身就是漸層\n\n姊妹色階 plasma、inferno、magma 也都有這三個特性，只是色相不同。如果你不知道該選什麼，預設用 viridis 不會錯。\n\n但 viridis 不是沒有代價。對一般民眾來說它看起來有點「太學術」，而且整條色帶偏暗——低值端是深紫，疊到淺色底圖上反而比高值端的黃還搶眼，跟「越多越深」的直覺剛好相反，第一次看的人容易把低值區誤判成重點。如果你的網站受眾是公務員、媒體、社群讀者，YlGnBu 或 YlOrRd 這種低值夠淺、明度從淺到深單調遞增的色階，會更符合他們的視覺習慣。\n\n## YlGnBu：ColorBrewer 的經典\n\n[ColorBrewer](https://colorbrewer2.org/) 是 Penn State 的 Cynthia Brewer 教授在 2002 年釋出的色階庫，原本是給地圖設計師用的，現在幾乎所有 GIS / 視覺化工具（D3.js、Leaflet、Tableau、QGIS）都內建了它。\n\nColorBrewer 提供三類色階：\n\n- **Sequential**：YlGn、YlOrRd、Blues、Reds、Greens 等，適合單向遞增\n- **Diverging**：RdBu、PiYG、BrBG 等，適合雙向偏離\n- **Qualitative**：Set1、Pastel1 等，適合類別資料（無序）\n\nYlGnBu（黃→綠→藍）是 sequential 類別裡最常被選用的之一，理由是：\n\n- 黃色端夠亮、藍色端夠深，**對比範圍大**\n- 沒有用紅色，**避免「紅 = 壞」的情緒誤導**\n- 公部門報告書的視覺習慣，給人「冷靜、客觀、財經」的感覺\n\n我最後選 YlGnBu 的原因，就是「所得稅地圖」這個題材本身就需要冷靜感。如果是傳染病熱點圖，我會改用 YlOrRd 來強調「警示」。\n\n## 為什麼紅綠色階是地雷\n\n`#ff0000` 紅 → `#00ff00` 綠，這是直覺裡「**壞→好**」的對比。很多人做地圖第一個會想到的就是這個配色。\n\n但根據統計，**全球約 8% 的男性是紅綠色盲**（女性約 0.5%）。他們看到的紅色跟綠色都會變成偏黃褐色，幾乎無法區分。\n\n這代表如果你的地圖讀者裡每 12 個男生就有 1 個看不出來，你做的所有視覺化都失效了。\n\n更糟的是：紅綠色階的「紅 = 壞」是西方文化習慣。在台灣，紅色常代表喜慶；中國股市則「紅漲綠跌」。**同樣顏色在不同文化代表相反意義**，這也是要避開的坑。\n\n說到底，紅綠最大的問題不是「紅綠」這兩個顏色本身，而是它**只靠色相去編碼數值、明度卻幾乎沒變**——色盲讀者一旦分不出色相，就什麼資訊都拿不到。真正該守的原則是：不要只靠色相編碼，要保證**明度單調遞增**，這樣就算把地圖印成黑白、或讀者是色盲，深淺順序還是讀得出來。如果你真的需要雙向表達（高於平均 / 低於平均），也不必硬用紅綠——ColorBrewer 的 RdYlBu、BrBG 這類 diverging 色階就是設計成色盲安全的，兩端明度也夠分。\n\n**簡單原則：除非你有非常強的理由（例如就是要表達 +/− 雙向），否則 sequential 色階不要用紅綠對比；要雙向就挑色盲安全的 diverging。**\n\n## 分級方法：等距分級會殺死你的資料\n\n選好色階後還有第二個決定：怎麼把連續數值切成 5 個顏色區間？常見方法：\n\n| 方法 | 切法 | 適用 |\n|------|------|------|\n| **等距（Equal Interval）** | 從 min 到 max 平均切 | 均勻分布的資料 |\n| **分位數（Quantile）** | 每級剛好佔 20% | 想讓地圖顏色均勻 |\n| **自然斷點（Jenks）** | 演算法找資料的群聚邊界 | 學術正統、保留分布 |\n| **標準差** | ±1σ、±2σ 切 | 突顯異常值 |\n| **手動斷點** | 自訂門檻 | 有編輯觀點 |\n\n我原本想用等距分級，「最公平、最直覺」嘛。但攤開台灣所得稅資料一看：\n\n- 台北市松山區中華里中位數：**98.4 萬元**（全國前段）\n- 偏鄉村里中位數：**30-40 萬元**\n\n2025 年公布的 112 年度統計裡，台北松山中華里以**平均所得 526.6 萬元**登頂全台最富里，擠下蟬聯 5 年榜首的新竹關新里。但要注意 526.6 萬是「平均數」，會被里內極少數高所得家戶整個拉上去——同一個中華里的「中位數」其實只有 98.4 萬。一個里內 mean 比 median 高出五倍，本身就是長尾的訊號。\n\n這就是經典的**長尾分布**。如果你用等距分級，把上限拉到那種平均破 500 萬的村里，那 90% 的村里就會全部擠在最低色階——整張地圖看起來就是「一片米黃 + 一個刺眼藍點」，幾乎沒有區分度。\n\n**這是台灣公開資料視覺化的經典踩坑。**\n\n解法是 **Jenks 自然斷點**：演算法會找出資料的「天然群聚邊界」，讓組內變異最小、組間變異最大。視覺上既不會被尾部極端值搞爛、也不會被分位數的均勻切法掩蓋分布本身的特徵。\n\n但 Jenks 不是無代價的勝利。它的斷點是「跟著這份資料算出來的」，所以換一份資料就會跳——我做單一年度的靜態地圖沒事，但如果你要做跨年比較、或資料會定期更新，每次重算斷點會讓同一個值的顏色一直變，讀者沒辦法把兩張地圖疊著看；斷點也常落在像 47.3 萬這種難讀的非整數上，圖例不好寫；資料量大時演算法本身也吃計算資源。需要跨年比較或動態更新時，我反而會改用一組固定的手動斷點，犧牲一點貼合度換「同一個值永遠同一個顏色」。\n\n順帶一提，被我跳過的**分位數**也不是只有缺點。它保證每一級剛好塞進 1/5 的村里，每個顏色都有足夠樣本、不會出現某一級全空，而且因為切法跟絕對數值脫鉤，反而最適合講「相對排名」（你家這個里贏過全台幾成）。它的代價是會把分布的形狀抹平——明明差很多的兩個里可能同色、差一點點的卻被切到不同級。所以這比較像「想突顯分布形狀就 Jenks、想講相對位置就分位數」的取捨，不是誰絕對贏。\n\nColorBrewer + Jenks 是我這次的選擇，QGIS 內建分級和 Axis Maps 的 cheatsheet 也都把這組當預設起點。\n\n## 真實踩到的坑：opacity × 基底圖\n\n色階跟分級都選定了，本以為大功告成。結果 MapLibre 跑起來——polygons 看不見。\n\n我用的是 [OpenFreeMap](https://openfreemap.org) 的 positron 主題：一張極淺的灰底地圖。fill-opacity 設 0.7（直覺值），結果 YlGnBu 的淺色端（`#ffffcc` 黃白）幾乎跟灰底融成一體，深色端（`#253494` 海軍藍）又跟海面顏色撞色——這正是前面比較表裡標的「YlGnBu 深色端容易跟水體混」那個陷阱，被我親身撞上了。\n\n我沒有因為這個陷阱就放棄 YlGnBu，因為「冷靜客觀」對所得題材還是太合適。比較划算的是直接緩解撞色：把 positron 底圖的水體圖層換成更淺或偏灰的顏色、跟深藍拉開明度差，再幫每個 polygon 加一條極細的白色邊框，深色里之間就不會糊在一起、也不會跟海連成一片。fill-opacity 最後拉到 **0.85** 才整體看得清楚——但又會壓掉一些路名標籤。這就是真實場景才會踩到的互動：色階 × 基底圖 × opacity 是綁在一起的，不能分開選。\n\n**經驗法則**：\n\n- 淺底圖（positron / light）：fill-opacity 0.8–0.9\n- 深底圖（dark matter）：用 plasma / magma + opacity 0.7\n- 衛星圖底：避免低明度色階，用 viridis 反而清楚\n\n## 反思\n\n弄了一小時下來，最大的轉變是我終於不再把色階當「挑哪個比較好看」的事。實際做一張會被別人看的地圖才懂，每個選擇都在無聲地對讀者說「這裡多、那裡少、這裡異常、那裡正常」，選錯就是在誤導——它是「不要誤導」的問題，不是美感問題。\n\n至於怎麼選，我的順序是先抄 ColorBrewer 再依場景判斷例外。Cynthia Brewer 花了二十年讓那些色階通過色盲、印刷、感知測試，沒道理自己重調一遍；但「直接抄」也有抄不動的時候——要做連續漸層而不是分級、要配深色模式、或品牌色有指定，這幾種情況就得自己再調，ColorBrewer 只是個夠好的起點，不是終點。\n\n另一個只有真的跑過才知道的事，是「色階 × 基底圖 × opacity」綁在一起。設計稿上看好好的色階，疊到真實地圖才發現淺色端融進底圖、深色端撞水面，一定要在實際的 MapLibre / Leaflet 環境跑一次，光看 ColorBrewer 預覽不準。長尾資料則別用等距分級——台灣的所得、房價、人口、營收幾乎都是長尾，等距會把它們壓成「一片米色 + 幾個亮點」，用 Jenks 看分布形狀、用分位數看相對排名都比等距好。\n\n> 後記：這篇最後選的 YlGnBu，後來我又換掉了。做到比較後期、開始認真面對「一般民眾看得懂嗎」這件事，我把色階整個改成 OrRd（暖色、7 級、用對數絕對門檻分桶），原因和我怎麼把「選色階」這一個決策拆成兩個獨立的軸，寫在 [為什麼我把所得地圖色階從 viridis 換成 OrRd](/blog/orrd-warm-palette-two-decisions-framework)。所以這篇的結論請當成「當時的我」的選擇，不是定案。\n\n---\n\n完整的 TaxMap-TW 程式碼會放在 [GitHub repo](https://github.com/bobo52310/TaxMap-TW)。\n\n接下來其實還沒輪到 PMTiles。底圖本身要選哪家服務，是上色之前就得先決定的事——[下一篇](/blog/openfreemap-maptiler-base-map-comparison)會先比 OpenFreeMap、MapTiler、Mapbox 這幾個 Web 地圖底圖服務怎麼選。至於怎麼把這 7,747 個村里 polygon（簡化後 5.6 MB 的 GeoJSON）封裝成單檔 PMTiles、再用 HTTP Range 按需讀取，留到 [PMTiles 那篇](/blog/pmtiles-http-range-request-single-file-tiles)再細講。", "summary": "資料地圖（Choropleth）該用哪種色階？做台灣所得稅 TaxMap 時原本想用 viridis，最後換成 ColorBrewer 的 YlGnBu + Jenks 自然斷點。整理 7 種主流連續色階比較、為什麼紅綠對比是地雷、長尾分布怎麼分級、以及 opacity × 基底圖的隱藏陷阱。", "image": "https://bobochen.dev/_astro/cover.B1NMUiEQ.webp", "date_published": "2026-05-27T00:00:00.000Z", "tags": [ "資料視覺化", "地圖", "MapLibre", "ColorBrewer", "色彩" ] }, { "id": "https://bobochen.dev/blog/enterprise-ai-agent-latency-reliability-cost-tradeoffs/", "url": "https://bobochen.dev/blog/enterprise-ai-agent-latency-reliability-cost-tradeoffs/", "title": "延遲、可靠性、成本：AI agent 系統設計的鐵三角", "content_text": "LLM app 還是個 distributed system，延遲、可靠性、成本這三件事會互相打架，你不可能三個都要到極致。談 streaming 降感知延遲、retry/timeout/circuit breaker、prompt 與結果快取、model routing（小模型優先）、token 成本治理，以及怎麼用工程手段在這個三角上做出有意識的取捨。", "content_html": "import DeckEmbed from '../../../components/blog/DeckEmbed.astro';\nexport const deckSlides = Object.entries(import.meta.glob('./slides/*.webp', { eager: true, import: 'default' })).sort(([a], [b]) => a.localeCompare(b)).map(([, m]) => m);\n\n> 這是「從 PoC 到 Production：企業 AI Agent 系統工程」系列第 10 篇（共 12 篇）。上一篇：[生產級 LLM 可觀測性與評估](/blog/enterprise-ai-agent-llm-observability-eval)。\n\n到這篇，前面講的所有東西要付帳了。RAG 多檢索幾份文件、reranking 多一次模型呼叫、multi-agent 多幾顆 agent、retry 多跑幾次——每一個讓系統「更好」的決定，都在延遲、可靠性、成本這三件事上劃下一刀。\n\n而這三件事，是一個**互相打架的鐵三角**：\n\n![延遲、可靠性、成本的鐵三角：三股力量互相拉扯，把中心同時往三個方向拉開——你不可能三個都拉到極致](./images/iron-triangle.webp)\n\n

可靠性、延遲、成本互相拉扯的鐵三角：靠近任一角，另外兩角就被犧牲——三者無法同時拉到極致。

\n\n- 想**可靠** → 加 retry、加 fallback、用更強的模型 → 變慢、變貴。\n- 想**便宜** → 用小模型、少檢索、少 reasoning → 品質和可靠性下降。\n- 想**快** → 砍 reasoning、激進 cache、少檢索 → 可能犧牲正確性。\n\n你不可能三個都要到極致。Production 工程的價值，就是在這個三角上做出**有意識的取捨**，而不是預設「全都要最好」然後被帳單和延遲教訓。\n\n這也是我一直強調 LLM app 還是 distributed system 的原因——下面這些手段，做過後端的人會覺得無比熟悉。\n\n## 延遲：先區分「真延遲」和「感知延遲」\n\nLLM 天生慢，一個複雜回答跑好幾秒是常態。但使用者體感的「慢」，跟實際耗時是兩回事。\n\n**1. Streaming（串流）幾乎免費降感知延遲。**\n別等整個答案生成完才一次吐出來，邊生成邊吐字。實際總耗時沒變，但使用者「立刻看到東西在動」，體感快非常多。這是 CP 值最高的一招，幾乎沒有不做的理由。用工程語言講，streaming 壓的是 **TTFT（Time To First Token，首 token 延遲）**——聊天場景只要 TTFT 低於 1 秒，使用者就覺得「即時」；串流開始後順不順，則看 **TBT（token 之間的間隔）**。人對「按下送出到看到第一個字」的等待，遠比「字與字之間的間隔」敏感，所以該進你第 9 篇 dashboard、該設 SLO 的，是 TTFT，不是籠統的「總回應時間」。\n\n**2. 把能平行的就別串行。**\n如果一個任務要檢索三個不同來源，讓它們**同時跑**，而不是一個等一個。Agent runtime（第 2 篇）要支援這種平行。這是基本的並行思維，跟你優化任何後端流程一樣。\n\n**3. 用小模型處理快路徑。**\n不是每一步都要動用最強最慢的模型（下面 model routing 細談）。意圖分類、簡單抽取用快的小模型，把慢的大模型留給真正需要的那一步。\n\n## 可靠性：為「外部依賴一定會出包」設計\n\n你的 agent 依賴外部 LLM API，而那是一個**會逾時、會限流、會偶爾回垃圾、偶爾掛掉**的依賴。把它當成「一定會出包的外部服務」來設計，這又是後端的老功課：\n\n- **Timeout**：每次模型呼叫設合理逾時，別讓使用者無限等。\n- **Retry with backoff**：暫時性錯誤（限流、逾時）重試，但要退避、要設上限，別把對方打更慘、也別自己燒爆 token。\n- **Circuit breaker**：某個模型 / 供應商持續出錯，先「跳閘」停止打它，走 fallback，給它時間恢復。\n- **Fallback model**：主模型掛了或回垃圾，自動切備援（另一家供應商、或本地模型）。這也降低單一供應商的依賴風險。\n- **降級（graceful degradation）**：真的都不行時，老實回「現在無法處理，請稍後或轉人工」，而不是給一個爛答案。呼應第 1 篇的鴻溝六。\n\n注意這裡的張力：每加一層可靠性（retry、fallback），通常就**多一點延遲、多一點成本**。所以要分場景——關鍵動作值得多付，邊緣功能不必。\n\n關於 fallback 還有個坑要先講：跨供應商 fallback 沒有「一鍵切換、行為一致」那麼無痛。同一段 prompt 在 GPT、Claude、Gemini 上的輸出風格、JSON 遵循度、refusal 行為都不一樣；tool calling 的 schema 各家也不同；更別說等下要講的 prompt caching 是供應商綁定的——切到備援那一刻，前面省的快取全部失效，延遲跟成本反而往上跳。實務上只有兩條路：為主 / 備各自維護一套 prompt 與 parser，或把備援路徑當成「可接受的降級」來設計。別假設換家供應商，行為會一樣。\n\n## 成本：LLM 系統獨有的「浮動帳單」\n\n傳統服務成本相對固定（機器開著就那樣）。LLM 系統的成本是**按 token 浮動**的，而且會悄悄長大。第 9 篇我們已經把成本監控起來了，這篇講怎麼壓。\n\n**1. Model routing：小模型優先，必要才升級。**\n這是最大的省錢槓桿。把「要用哪個模型」抽成一層（第 2 篇的 Model Router），依任務難度路由：\n\n- 分類、抽取、格式轉換、簡單問答 → **便宜小模型**\n- 複雜推理、需要高品質的最終生成 → **大模型**\n\n光是把「不需要大模型的步驟」改用小模型，常常就能砍掉一大塊成本，而品質幾乎無感。\n\n有多大？拿 RouteLLM（UC Berkeley / Anyscale / Canva，ICLR 2025）的公開 benchmark 當參考：在偏對話的 MT-Bench 上，它能維持約 95% GPT-4 品質、成本卻砍掉約 85%。但別把這 85% 當保證值——同一個 router 換到偏推理的 benchmark，省幅就掉很多（MMLU 只省約 45%）。所以 routing 的省幅，本質上等於你流量裡「不需要大模型的那一塊」有多大：先量你自己的流量分布，再決定能省多少，別套別人的數字。\n\n**2. Cache：能不重算就不重算。**\n- **結果快取**：這裡其實藏了兩種完全不同難度的東西。**Exact cache**（把 query 正規化後當 key，同樣的問題回同樣的答案）幾乎零風險、該最先做；**semantic cache**（用 embedding 相似度命中「相似」問題）能多抓改寫過的重複，但有 false-positive 風險——兩個在向量空間很近的問題可能需要完全不同的答案，而且對的命中跟錯的命中相似度高度重疊，沒有通用安全閾值，閾值要訂多嚴取決於「答錯的代價」。生產數據也顯示 semantic cache 相對 exact 往往只多 5~8 個百分點命中率，未必抵得過它的複雜度與答錯風險。高風險場景就乖乖用 exact。（兩種都要注意時效和權限，別把 A 使用者的答案快取給 B。）\n- **Embedding 快取**：同一段文字別重複 embedding。\n- **Prompt 快取**：把穩定的內容（system prompt、few-shot 範例、長 context）放最前面、把每次都變的部分放最後，讓固定前綴可以被快取重用。但 2026 三家機制不一樣，這差異直接決定你有沒有真的省到：OpenAI、Gemini 是**自動命中**（前綴 ≥ 1,024 token 重複就生效，讀取省 50~90%、寫入不收費）；Anthropic 是**顯式 opt-in**，你得在 request 裡標 `cache_control` 斷點，cache read 只要基礎 input 價的約 0.1 倍（省 ~90%），但 cache write 要付約 1.25 倍溢價、預設 5 分鐘 TTL——換句話說 Claude 的快取要**至少命中一次才回本**。用 Claude 卻忘了標 `cache_control`＝你以為在省錢、其實一毛沒省，這是這招最常見的踩雷。\n\n**3. 管好 context 長度。**\nToken 成本跟 context 長度直接相關。第 7 篇講的記憶截斷 / 摘要、第 3 篇講的別塞太多 chunk，到這裡全都變成「省錢」的具體手段。**把不必要的東西塞進 context，是最常見的浪費。**\n\n**4. 設預算護欄。**\n單一請求、單一使用者、單一 multi-agent 任務（第 8 篇的成本爆炸風險）都要有 token / 花費上限。撞到上限就停下來或降級，別讓一個失控迴圈燒出一張嚇人的帳單。\n\n我做過 K8s 叢集那類的雲端成本優化，心法在這裡完全通用：**先讓成本可見（第 9 篇），找出最大的那塊，用最小的品質代價把它砍掉**。差別只是這次砍的不是 CPU/記憶體，是 token。\n\n## 把三角畫出來：依場景做取捨\n\n最後給一個務實的框架。不同功能在三角上的位置不該一樣：\n\n| 場景 | 優先 | 取捨 |\n|---|---|---|\n| 即時對話助理 | 延遲 | streaming、小模型快路徑、適度 cache，容忍偶爾要重問 |\n| 高風險決策 / 報告 | 可靠 + 正確 | 大模型、多檢索、critic 審查、HITL，接受慢和貴 |\n| 大量批次處理 | 成本 | 小模型、激進 cache、可離線慢慢跑，犧牲即時性 |\n| 內部低頻工具 | 成本 + 簡單 | 別過度工程，能跑就好 |\n\n關鍵不是背這張表，是養成一個習慣：**每設計一個 agent 功能，先問它在這三角的哪個角，然後刻意往那邊取捨**——而不是無意識地全都要最好，最後三個都普普、帳單還很貴。\n\n## 小結\n\n- 延遲、可靠性、成本是會互相打架的鐵三角，**不可能三個都極致**。\n- **延遲**：streaming 降感知延遲、平行化、小模型走快路徑。\n- **可靠性**：把 LLM API 當「一定會出包的外部依賴」——timeout、retry、circuit breaker、fallback、降級。\n- **成本**：model routing 是最大槓桿，加上 cache、管好 context、設預算護欄。\n- 每個功能依它在三角的位置**刻意取捨**，這份判斷力就是 production 系統工程師的核心價值。\n\n這些手段你會發現沒一個是 AI 玄學，全是分散式系統的硬功夫換了對象。下一篇，我們把第 5、6、9 篇散落的安全與信任機制，收斂成一套完整的**Agent 治理框架**——讓企業敢把這套系統接到真實業務上。\n\n\n## 文章簡報\n\n\n\n---\n\n### 延伸閱讀\n\n- 上一篇：[生產級 LLM 可觀測性與評估](/blog/enterprise-ai-agent-llm-observability-eval)\n- [Agentic Engineering：成本優化](/blog/agentic-engineering-cost-optimization)——agent 工作流的 token 成本怎麼省\n- 下一篇：《Agent 治理框架：RBAC、audit log、HITL、tool registry》", "summary": "LLM app 還是個 distributed system，延遲、可靠性、成本這三件事會互相打架，你不可能三個都要到極致。談 streaming 降感知延遲、retry/timeout/circuit breaker、prompt 與結果快取、model routing（小模型優先）、token 成本治理，以及怎麼用工程手段在這個三角上做出有意識的取捨。", "image": "https://bobochen.dev/_astro/cover.VPcuaszI.webp", "date_published": "2026-05-27T00:00:00.000Z", "date_modified": "2026-06-05T00:00:00.000Z", "tags": [ "系統設計", "成本優化", "延遲", "可靠性", "LLM" ] }, { "id": "https://bobochen.dev/blog/openfreemap-maptiler-base-map-comparison/", "url": "https://bobochen.dev/blog/openfreemap-maptiler-base-map-comparison/", "title": "OpenFreeMap vs MapTiler vs Mapbox：6 個 Web 地圖底圖服務怎麼選？", "content_text": "做台灣所得稅地圖選底圖時，發現業界標準 Mapbox 免費額度只有 5 萬次/月。整理 OpenFreeMap、MapTiler、Mapbox、NLSC 等 6 種主流服務的免費額度、token、style 比較，以及為什麼公民科技專案選了 2024 年才上線的 OpenFreeMap。", "content_html": "> **沒有 vector tile、style spec 的基本概念？**\n> 建議先看 [Web 地圖底圖是什麼？vector vs raster、tile pyramid、style spec 一次搞懂](/blog/web-map-tile-basics-vector-raster-style)。\n\n最近在做 [TaxMap-TW](https://github.com/bobo52310/TaxMap-TW)（台灣 7,747 個村里所得稅地圖），村里界、色階都選好之後，我以為「底圖」會是 5 分鐘就解決的小問題。\n\n結果光是底圖服務的選擇就讓我研究了一個下午。\n\n主要的卡點是：**業界標準的服務每月有額度上限，但我做的是公民科技專案，未來流量我控制不了**。如果某天上熱搜流量爆掉、剛好那個月超額被收錢，那真的會傻眼。\n\n這篇整理我評估的 6 種主流 Web 地圖底圖服務，最後選了 [OpenFreeMap](https://openfreemap.org/)（2024 才出現的新興服務）的理由。\n\n## 選底圖服務（Mapbox、MapTiler…）為什麼是個問題\n\n那天下午一開始我其實很輕鬆，想說底圖不就挑個好看的接上去就好。真正讓我卡住的是這件事：地圖網站上看到的「地圖本身」（道路、地名、地形）跟我疊在上面的所得資料（村里 polygon、色階）是兩層東西。\n\n- **底圖**：道路網、地名、邊界 — 由地圖服務商提供\n- **資料層**：我自己的村里標記、polygon、色塊 — 我自己畫\n\n底圖服務商要把全球 OSM 資料切成幾百 GB 的 tiles、放到 CDN、提供 API，成本不低，所以業界普遍採「免費額度 + 超量收費」模式。我打開 Mapbox 定價頁那一刻才意識到：原來「免費」是有條件的，而我這個專案的條件偏偏最差——流量我完全控制不了。\n\n對個人 / 公民科技專案來說，常見的選擇困境是：\n\n- **業界標準（Mapbox）**：品質最高，免費額度 5 萬次 map loads/月\n- **MapTiler**：免費額度是 10 萬次 API requests + 5,000 次 map sessions/月，中文支援好（注意計費單位跟 Mapbox 不一樣，下面會解釋）\n- **自架**：完全免費、流量完全自主，但要 100GB+ 儲存 + 維運\n- **政府服務（NLSC）**：免費、台灣地名/門牌/行政界線的在地化是所有選項裡最準的，但官方 style 偏舊、不好直接拿來做資料視覺化\n- **新興服務**：聽過但不敢用，怕停服\n\n## OpenFreeMap vs MapTiler vs Mapbox：6 種底圖服務比較\n\n我把每家的定價頁、文件、官方 demo 都點過一輪，整理成這張對照表：\n\n| 服務 | 費用 | Token | 中文標籤 | 部署 |\n|------|------|-------|----------|------|\n| **[OpenFreeMap](https://openfreemap.org/)** | 完全免費無限 | 不需要 | 一般 | 0 |\n| **[MapTiler](https://www.maptiler.com/)** | 10 萬 requests + 5,000 sessions/月免費 | 需要 | 中文好 | 0 |\n| **[Stadia Maps](https://stadiamaps.com/)** | 20 萬次/月免費 | 需要 | 一般 | 0 |\n| **[Mapbox](https://www.mapbox.com/)** | 5 萬次/月免費 | 需要 | 中文好 | 0 |\n| **[CARTO](https://carto.com/)** | 免費試用（額度請以官網為準）| 需要 | 一般 | 0 |\n| **[NLSC 國土測繪](https://maps.nlsc.gov.tw/)** | 政府免費 | 不需要 | 在地化最好 | 0 |\n| **自架** | $0 | 不需要 | 看你怎麼接 | 100GB+ |\n\n「部署」這欄是我比較關心的：除了自架，所有方案都是「用他們的 hosted endpoint」，本質上零部署。差別只在註冊、token、流量上限。\n\n要特別提醒一件事：**這些「免費額度」的計費單位其實不一樣，不能直接比大小**。Mapbox 算的是 map loads（地圖載入次數），MapTiler 同時有 API requests（每次抓 tile / style 都算）和 map sessions（一次地圖瀏覽算一個 session）兩種計量——它的 sessions 只有 5,000/月，反而比 Mapbox 的 5 萬 map loads 還低。所以「MapTiler 額度比 Mapbox 高」這句話其實站不住，得看你的使用情境是被哪個單位卡住。CARTO 的免費條件這幾年也改過幾次（從早期的固定額度變成試用 + PAYG），要用之前最好自己去官網確認一次當下的數字。\n\n## 為什麼選 OpenFreeMap\n\n最後我選了 [OpenFreeMap](https://openfreemap.org/)。它是 2024 年才上線的服務，由作者（GitHub 帳號 hyperknot）一個人營運，tile 跑在他自己租的 Hetzner dedicated server 上（用 Round-Robin DNS 撐負載），Cloudflare 則贊助頻寬、R2 拿來存 tile。經費來自 [GitHub Sponsors](https://github.com/sponsors/hyperknot) 的社群捐款。\n\n選擇理由：\n\n**1. 完全免費無流量上限**\n\n對公民科技 / 個人專案最重要的條件。MapTiler、Mapbox 都會在熱門時刻變成「等等我要付錢嗎」的焦慮源。OpenFreeMap 把那種「上熱搜當天會不會收到帳單」的焦慮直接拿掉了。\n\n不過得誠實講：**免費不等於沒風險，只是把風險換了一種**。付費服務你超額會被收錢，但你跟它有付費關係、它有義務給你 SLA；免費的公共 endpoint 你跟它沒有任何契約，它哪天要對特定 referer 限流、改政策、甚至收手不做，你都只能接受（OpenFreeMap 官方其實就有針對 referer 做過流量限制）。所以這裡換到的不是「零風險」，是「把超額帳單的風險，換成可用性與政策的風險」。如果你真的怕爆量、又不想被別人的政策綁住，**唯一的根治解是 self-host**——流量完全自主，代價是你得自己扛 100GB+ 的儲存跟維運。我這次沒走那條路，是因為這是個下班做的專案，我寧可賭供應商風險，也不想多養一台機器。\n\n**2. 零註冊、零 token**\n\n幾秒鐘就能接上。我做的是開源專案，要求每個 fork 的人都去申請 MapTiler token 太麻煩。\n\n**3. 基礎設施靠得住，但要清楚它是誰在撐**\n\n它的 tile 靠 Cloudflare 贊助頻寬、R2 存放，所以下載速度跟全球可達性其實滿穩。但要老實說：它不是「Cloudflare 託管」，背後是一個人租 Hetzner 機器在跑。我選它不是因為「Cloudflare 罩著就不會掛」，而是因為對一個公民科技專案，這個穩定度已經夠用——真要怕它哪天掛掉，後面我會講解法。\n\n**4. 風格夠用**\n\n官方現在提供 positron、bright、liberty、dark、fiord（含 3D）等幾種 style，我最常用的是 positron——經典的灰白底色，給彩色 polygon 留空間，很適合資料視覺化。\n\n當然它也有缺點：相對新（2024 年起）、中文標籤沒 MapTiler 細緻、單人營運加上靠 GitHub Sponsors 撐經費，哪天作者沒力或贊助斷掉就有停服風險。但對 MVP / 個人專案，這些都不是阻擋條件——前提是你想清楚萬一它掛了，你能多快換掉它。\n\n中文標籤這點我要多講一句，因為對台灣專案它可能是 deal-breaker。OpenFreeMap 的 OSM 標籤是有中文沒錯，但偏鄉的小地名、巷弄、行政界線的完整度，跟 MapTiler 或 NLSC 比是有差的——大概就是「縣市、主要道路、知名地標看得到，但越往細節越空」。我的地圖是看村里所得色塊、底圖只是襯底，所以這個差距我吃得下；但如果你做的是要讓使用者照著底圖找路、認在地地名的應用，這個落差就足以讓你改選 MapTiler，甚至認真考慮把 NLSC 疊進來。\n\n## 3 分鐘接上 OpenFreeMap\n\n從零到 [MapLibre GL JS](https://github.com/maplibre/maplibre-gl-js) + OpenFreeMap 跑起來，三步驟：\n\n**1. 裝套件**\n\n```bash\npnpm add maplibre-gl\n```\n\n**2. 初始化地圖**\n\n只要一行 style URL，剩下都跟一般 MapLibre 用法一樣：\n\n```ts\nimport maplibregl from 'maplibre-gl';\nimport 'maplibre-gl/dist/maplibre-gl.css';\n\nconst map = new maplibregl.Map({\n container: 'map',\n style: 'https://tiles.openfreemap.org/styles/positron',\n center: [121.0, 23.7], // Taiwan center\n zoom: 7,\n});\n```\n\n最常用的幾個 style URL（另外還有 `dark`、`fiord` 等）：\n\n- `positron` — 灰白底色（推薦做資料視覺化）\n- `bright` — 完整彩色（看起來像 Google Maps）\n- `liberty` — 經典 OSM 風格\n\n**3. attribution**\n\nOpenFreeMap 要求標示來源（也是 OSM 授權的要求）。MapLibre 預設會自動讀 style 的 attribution，所以不用額外做事。\n\n如果要客製 attribution：\n\n```ts\nconst map = new maplibregl.Map({\n // ...\n attributionControl: { compact: true },\n});\n```\n\n這樣地圖右下角會出現一個小 `(i)`，點開才會展開完整來源。\n\n## 反思\n\n研究這個的過程踩到一個我自己的迷思：**「業界標準 = 最佳選擇」**。Mapbox 是地圖領域的業界標準，所以一開始我幾乎想都沒想就要選它。但 5 萬次/月的免費額度，對一個未來不知道會多少流量的開源專案，是個沉重的決策。\n\n這讓我反思：技術選型其實有兩個維度\n\n1. **技術成熟度** — Mapbox > MapTiler > OpenFreeMap\n2. **商業模式 fit** — 對公民科技/個人專案，OpenFreeMap > MapTiler > Mapbox\n\n如果是企業專案、有預算、流量可預期，Mapbox 還是最佳選擇。但如果是「想做就做、不確定會不會紅、寧可服務醜一點也不想付錢」這種專案，業界標準反而是錯的選擇。\n\n其實這兩端中間還有路可走，不是只能二選一。比較務實的策略是**先用免費服務起步、流量真的起來再升級**：OpenFreeMap 接得快，等哪天爆量或想要更穩，再換成付費的 MapTiler / Mapbox，或乾脆自架——因為 style URL 只是一行設定，遷移成本很低。而 self-host 也別只當成「太麻煩」一句帶過：它是唯一能讓你**流量完全自主、不被任何供應商政策綁住**的選項，正好對應我開頭最焦慮的那件事。我這次沒選它，是清楚地拿「自己維運一台機器」去換「不用煩流量」，不是因為它不好。\n\n另一個收穫是：**新興的開源/免費服務（OpenFreeMap、Stadia 接手 Stamen）值得試**。老實說我自己一開始也是看到「2024 才上線、沒聽過」就想直接跳過，後來逼自己把官方 demo 點開、把 style 接到地圖上跑一遍，才發現它對我的需求剛剛好。這些服務通常是社群驅動、目標是補上業界標準的缺口，對小型專案、prototype、學生作業就是寶藏。但「值得試」不等於「閉著眼睛賭」——我會試一個新服務的前提是：我承受得起它哪天突然掛掉，而且我有一條半天內能換掉它的退路。如果是公司要長期維運、不能斷的系統，我就不會拿它當底圖。\n\n最有趣的發現是 **OpenFreeMap 的營運模式**：一個人租機器、Cloudflare 贊助頻寬、靠 GitHub Sponsors 收社群捐款，本質上是「我幫全世界省流量費，部分人回饋一點就夠我跑下去」。我喜歡這種商業模式之外的可能性，但也沒天真地把全部身家押上去——我留的後路是：TaxMap 的 style URL 是一行設定，真要換成 MapTiler 或自架，半天就能搬完。賭一個新服務，前提是你算得出「它掛掉的那天」要付出多少。\n\n## 系列其他文章\n\n- **想完全繞過底圖選型？** → [PMTiles 取代傳統 tile server：HTTP Range Request 的單檔魔術](/blog/pmtiles-http-range-request-single-file-tiles)\n- **底圖術語完全不懂？** → [Web 地圖底圖是什麼？vector vs raster、tile pyramid、style spec 一次搞懂](/blog/web-map-tile-basics-vector-raster-style)\n- **底圖之後是色階** → [資料地圖該用哪種色階？viridis、YlGnBu 與 ColorBrewer 實戰指南](/blog/data-map-color-scale-viridis-ylgnbu)\n- **整個專案的決策全貌** → [打造 TaxMap-TW 完整心得：6 個技術決策、踩了 4 個坑](/blog/taxmap-tw-postmortem-6-decisions-4-pitfalls)", "summary": "做台灣所得稅地圖選底圖時，發現業界標準 Mapbox 免費額度只有 5 萬次/月。整理 OpenFreeMap、MapTiler、Mapbox、NLSC 等 6 種主流服務的免費額度、token、style 比較，以及為什麼公民科技專案選了 2024 年才上線的 OpenFreeMap。", "image": "https://bobochen.dev/_astro/cover.C-xVGqG8.webp", "date_published": "2026-05-27T00:00:00.000Z", "tags": [ "WebGIS", "地圖", "MapLibre", "OpenFreeMap", "MapTiler" ] }, { "id": "https://bobochen.dev/blog/orrd-warm-palette-two-decisions-framework/", "url": "https://bobochen.dev/blog/orrd-warm-palette-two-decisions-framework/", "title": "為什麼我把所得地圖色階從 viridis 換成 OrRd：把「一個決策」拆成「兩個獨立軸」", "content_text": "做 TaxMap-TW 色階換三次，最後選 OrRd 不是因為好看，而是把「色階」拆成用色 (hue) + 分桶 (binning) 兩個獨立決策重新組裝。對數絕對門檻（30/50/80/130/200/350 萬）+ OrRd 7 級 = 跨年顏色穩定、中產區段視覺最寬、outlier 自然分出。", "content_html": "做 [TaxMap-TW](https://github.com/bobo52310/TaxMap-TW) 兩週，色階換了三次：**YlGnBu → viridis → OrRd**。最後選 OrRd 不是因為「比較好看」，而是因為我把「一個決策」拆成了「兩個獨立軸」。\n\n之前寫過一篇選 YlGnBu 的理由（系列第 1 篇 [《資料地圖該用哪種色階？》](/blog/data-map-color-scale-viridis-ylgnbu)），結論在實際做下來被自己推翻了。這篇是那篇的下一章。\n\n## 背景：7,747 個村里的所得色階怎麼選\n\nTaxMap-TW 是全台 7,747 個村里、11 年 × 4 指標可切換的所得熱度地圖。每個 polygon 要根據選定的年度與指標上色，選色階時我一開始把它當成「挑色卡」的問題：\n\n- 第 1 次選 **YlGnBu**（淺黃 → 深藍）：理由是「ColorBrewer 業界標準、色盲友善、公部門感」\n- 第 2 次換 **viridis**（紫 → 藍 → 綠 → 黃）：聽說 matplotlib 標準、感知均勻最科學\n- 第 3 次定案 **OrRd**（淺米 → 深紅）：使用者一句「viridis 不好看」之後重新思考\n\n問題不在於哪一個「比較對」，而是我一直把「色階」當成單一決策。\n\n## 發現過程\n\n### viridis 被打臉的那一刻\n\n從 YlGnBu 換到 viridis 的理由很學術：\n\n- Perceptually uniform（明度線性變化）\n- 色盲友善（Daltonization safe）\n- matplotlib 預設、學界共識\n\n換完跑 `pnpm dev`，使用者打開首頁，第一句話：「**顏色不好看。**」\n\n我愣了一下，因為這在我認知裡是「最對」的選擇。viridis 的 perceptual uniformity 是真本事——要精讀數值、要在連續漸層上分辨細微差距，它確實比 OrRd 強。但回頭看截圖 — 紫色 → 黃色的漸層在一般民眾眼裡確實很疏遠，沒有「熱度地圖」的直覺。問題不是 viridis 不好，而是它的優化目標（精讀、跨媒介穩定）跟我這張地圖的目標（讓一般人一眼看懂熱度）不一致。那一秒我才真正聽進去。\n\n### 找原型：kiang/salary 怎麼做？\n\n我問使用者：「要不要參考一下其他人怎麼選的？」最快的途徑是看 [kiang/salary](https://github.com/kiang/salary)（江明宗的村里所得地圖，TaxMap-TW 的精神祖父）的程式碼。\n\n翻到 `docs/map/main.js` 找到一個 `ColorBar(value)` function：\n\n```javascript\nfunction ColorBar(value) {\n if (value == 0) return \"rgba(255,255,255,0.6)\" // 白\n else if (value <= 300) return \"rgba(254,232,200,0.6)\"\n else if (value <= 400) return \"rgba(253,212,158,0.6)\"\n else if (value <= 500) return \"rgba(253,187,132,0.6)\"\n else if (value <= 700) return \"rgba(252,141,89,0.6)\"\n else if (value <= 900) return \"rgba(239,101,72,0.6)\"\n else if (value <= 1100) return \"rgba(215,48,31,0.6)\"\n else if (value <= 1300) return \"rgba(179,0,0,0.6)\"\n else if (value <= 1500) return \"rgba(127,0,0,0.6)\"\n else return \"rgba(64,0,0,0.6)\" // 最深\n}\n```\n\n短短 11 行，但裡面有**兩個獨立決策被疊在一起**：\n\n1. **用色**：ColorBrewer **OrRd 9 級**（橙紅熱度）\n2. **分桶**：**絕對門檻**（300/400/500/700/900/1100/1300/1500 千元，hard-coded）\n\n我之前的選擇是：\n\n1. 用色：YlGnBu / viridis（隨意換）\n2. 分桶：**quintile**（程式自動算每年的 20/40/60/80 分位數）\n\n**Ah ha。我一直把兩個獨立決策當成一個決策。**\n\n### 拆開看兩個軸\n\n把它們攤開：\n\n| 軸 | 選項 | 影響 |\n|---|---|---|\n| **用色** | YlGnBu / viridis / OrRd / RdYlBu / Cividis... | 視覺氣質、色盲友善度、情緒聯想 |\n| **分桶** | quintile / equal-interval / Jenks / 手動 / **log 絕對** | 跨年穩定度、outlier 處理、視覺均勻度 |\n\nquintile 看起來很合理（每年自動切 20%），但對「跨年看趨勢」是災難 — 因為門檻每年變，**同樣的 100 萬，在 2012 是綠色、在 2022 可能是黃色**。使用者拖年度滑桿時整張地圖會閃色，卻看不出真正的改變。\n\n絕對門檻沒這個問題，但要面對「outlier 怎麼處理」：kiang 的 9 級在 >1500 千元（150 萬）就封頂，但松山中華里 2022 中位數 526 萬，跟 200 萬的里會被染成同一個深紅，看不出差別。\n\n## 解法：OrRd 7 級 + 對數絕對門檻\n\n把兩個決策獨立優化：\n\n**用色：OrRd 7 級**\n\n- 暖紅本來就是「熱度地圖」的視覺直覺\n- 單色 sequential 不會像 RdYlBu 雙向被讀成「好 / 壞」\n- kiang 已驗證好看\n- 從 OrRd 9 級手挑 7 色子集（不是 ColorBrewer 官方 OrRd[7]），比 9 級少 2 級，視覺不擁擠\n\n這裡要誠實補一句：OrRd 是單色順序色階，色盲友善度其實不如 viridis（viridis 整條對各類色覺缺陷都安全，這是它最硬的優點，前面拿這點打它其實是我選邊站後的雙標）。我把色盲友善降為次要考量，是因為這張地圖的受眾是一般民眾、且色階靠「明度由淺到深」也能讀出高低——而且 ColorBrewer 仍把 OrRd 標為 colorblind-safe，不是裸奔。如果受眾換成需要精準辨色的專業使用者，這個取捨我會重做。\n\n**分桶：對數絕對門檻**\n\n- 倍率 ~1.5×：30 / 50 / 80 / 130 / 200 / 350 萬（單位千元為 300 / 500 / 800 / 1300 / 2000 / 3500）\n- 所得本來就 log-normal 分布，log 倍率切桶最自然\n- 中產區段（50–130 萬）佔最寬視覺空間\n- Outlier（>350 萬）自己一個頂色，中華里 526 萬獨立深紅，跟 200 萬區分得開\n\n實作很短：\n\n```typescript\n// src/components/MapClient.ts\n// 注意：這不是 ColorBrewer 官方 OrRd[7]（官方首色 #fef0d9、末色 #990000）。\n// 我是從 OrRd 9 級手挑出 7 色子集，跳掉中間兩階讓對比更開。\nconst ORRD_7 = [\n '#fee8c8', // <30 萬\n '#fdd49e', // 30–50\n '#fdbb84', // 50–80\n '#fc8d59', // 80–130\n '#ef6548', // 130–200\n '#d7301f', // 200–350\n '#7f0000', // >350\n] as const;\n\nconst ORRD_BREAKS = [300, 500, 800, 1300, 2000, 3500]; // 千元\n```\n\npaint expression 把每個 VILLCODE 對應到 stats、查 bucket 後上色：\n\n```typescript\nprivate classifyValue(value: number): number {\n for (let i = 0; i < ORRD_BREAKS.length; i++) {\n if (value < ORRD_BREAKS[i]) return i;\n }\n return ORRD_BREAKS.length; // 6 = >350 萬最深紅\n}\n```\n\n整段比 quintile 版簡單 — 因為門檻是常數，不再需要每次切換指標都重算 Jenks。\n\n## 具體數據 / 結果\n\n跟 kiang 比的改進：\n\n| | kiang | TaxMap-TW |\n|---|---|---|\n| 用色 | OrRd 9 級 | OrRd 7 級 |\n| 分桶數 | 9 級 + 0 | 7 級 + 無資料灰 |\n| 最高門檻 | >150 萬一個色 | >350 萬一個色 |\n| 中產解析度 | 50–130 萬擠在 2 級 | 50–130 萬攤開到 3 級 |\n| 中華里 526 萬 | 跟 200 萬同色 | 獨立深紅 |\n| 跨年穩定 | ✓（絕對門檻） | ✓（絕對門檻） |\n| 透明度 | 0.6 半透明 | 0.85 較飽和 |\n\n跟原本自己 quintile 版的差距更大 — 之前拖滑桿整張地圖在閃色，現在拖滑桿**只有「真正有變化的里」會升降顏色**，視覺訊號終於跟資料變化對齊。\n\n**這個方案的代價我也得說清楚：**一組固定門檻（30/50/80/130/200/350 萬）是照「綜所稅中位數」的量級調的，但我有 4 個指標可切（中位數、平均、各分位）。平均數那檔的數值分布跟中位數不一樣，套同一組門檻時，低收入村里會偏擠在前一兩桶，解析度沒有中位數那檔漂亮——嚴格講每個指標該有自己的一組門檻，我為了「跨指標也用同一把尺」偷懶用一組，這是已知的妥協。另外那個「>350 萬獨立深紅」聽起來解決了 kiang 的封頂問題，其實只是把 cap 從 150 萬往後推到 350 萬而已；中華里 526 萬跟假設某天冒出個 900 萬的里，還是會被染成同一個 `#7f0000`。outlier 永遠有，我只是把封頂線移到「現階段資料碰不到」的地方，不是真的解決了它。\n\n## 反思\n\n### 技術面\n\n**Choropleth 色階是兩個獨立決策，不要疊在一起想：**\n\n- **用色（hue / palette）**：解決「視覺氣質」與「色盲友善」\n- **分桶（binning）**：解決「跨年穩定度」與「outlier 處理」\n\n下次再看到任何 dataviz 設計問題卡住，先問自己：「**這真的是一個決策嗎？還是兩個被綁在一起？**」\n\n**log 倍率 binning 在「對的前提下」是被低估的選擇——但它有前提：**\n\n它對我這個場景好用，是因為剛好滿足三個條件：資料是 log-normal 分布、全正值、而且有公認的 anchor（所得級距、loan tier 那種大家認得的數字）。對應地：\n\n- 適合 log-normal 且全正的資料：所得、檔案大小、網站流量、收入級距、地震規模\n- 比 quintile 多了「絕對意義」（100 萬永遠是同色），所以能跨年比\n- 比 equal-interval 不會被 outlier 拉爆\n- 比手動 thresholds 容易解釋（「倍率 1.5x 切」一句話講完）\n\n但只要前提不成立就別硬套：資料含 0 或負值（log 直接爆）、近常態分布（log 反而把中間擠扁）、你要看的是相對排名而非絕對值、或資料偏態到大量村里全擠進同一桶——這些情況絕對門檻都會輸。而 quintile 也不是只有缺點：它保證每個色階都分到差不多的樣本數，做「單年、單指標的分布快照」時，這個「每色都有料」的特性其實比絕對門檻好看也好讀。我換掉它純粹是因為 TaxMap 的核心是「跨年拉滑桿看趨勢」，不是因為 quintile 本身爛。\n\n**抄前人的程式碼遠比從零推快：**\n\n- kiang 11 行 `ColorBar()` 包含了他幾年累積的設計判斷\n- 我看一眼就拿到「絕對門檻」的關鍵 insight\n- 但我沒照抄，看完後問「他這樣做的痛點在哪？我能不能改進？」 — 結果改成 7 級 + log 倍率 + 更高的 cap\n\n### 心態面\n\n**「好看」是合法的產品需求。** 我一開始把使用者「顏色不好看」當成主觀偏好，差點要去說服他 viridis 才是正確答案。回頭看那是傲慢 — 一張公開的地圖是給一般民眾看的，不是給 matplotlib 用戶。學術上對 ≠ 產品上對。前提是「好看」不能踩到底線：可及性（色盲能讀）跟正確性（顏色沒有誤導數值）是不能用美感換的，這次只是色盲友善降為次要、沒被犧牲掉。\n\n**「matplotlib 預設」不是中立選擇，是別人的優化目標。** viridis 是 2015 年 matplotlib 為「科學論文 print 出來在黑白紙上、影印後、色盲眼裡都讀得到」設計的——這目標很值得尊敬，只是它跟 web choropleth 的痛點不重疊。所以不是「viridis 不該用」，是「它的優化目標不該無條件套到我的場景」。盲目套用業界標準，等於把別人的優化目標當成自己的。\n\n**少嘴砲、先打開別人的程式碼。** 我花了一小時跟使用者來回討論色階理論，最後實際解決問題的關鍵 insight，是花 30 秒讀 kiang 11 行 javascript 拿到的。但讀前人 code 要帶批判——它包的是「他的痛點」的答案，不一定是你的，所以我看完是問「他為什麼這樣切？我的場景哪裡不一樣？」，而不是整段抄走。\n\n### 有趣發現\n\n**ColorBrewer 名字超難記但網站超實用。** [colorbrewer2.org](https://colorbrewer2.org/) 是 Cynthia Brewer 教授 2002 年做的 choropleth 配色工具，內建 35+ 個色階分 3 類（sequential / diverging / qualitative）。每個都有色盲模擬、列印友善、影印友善的標記。地圖配色 99% 用得到，但因為網站做得很學術老派，常被忽略。\n\n**換成暖紅之後，沒人再問「這顏色代表什麼」。** viridis 版我得跟使用者解釋「紫是低、黃是高」；OrRd 版打開來，他直接就說「喔右邊那塊比較紅就是有錢的」。紅＝熱＝高這個聯想在我這個使用者身上是零成本的——我不敢說它跨文化都成立，但對這張給台灣民眾看的地圖夠用了。\n\n**對數倍率 1.5× 不是亂猜的，是公部門統計手冊的「level set」傳統。** Loan / income tiers 常切 30/50/80/130/200/300/500 萬 — 看起來只是「順手挑的數字」，其實是平均所得倍率累積的結果。我 TaxMap-TW 用 30/50/80/130/200/350，差不多一脈相承。\n\n## 寫在最後\n\n如果這兩週只留一句給未來的自己，那會是：色階卡住的時候，我反覆換的多半是「色卡」，但真正卡住我的是「分桶」。先把這兩件事拆開，再決定「我這張圖到底要跨年比、還是看單年分布」，色階就不再是玄學了。至於要不要抄前人的 OrRd——抄判斷，不抄結論。\n\n## 參考連結\n\n- [TaxMap-TW GitHub](https://github.com/bobo52310/TaxMap-TW)\n- [kiang/salary 原型](https://github.com/kiang/salary)\n- [ColorBrewer 2.0](https://colorbrewer2.org/)\n- 這篇承接的決策起點：[資料地圖該用哪種色階？viridis、YlGnBu 與 ColorBrewer 實戰指南](/blog/data-map-color-scale-viridis-ylgnbu)（當初選 YlGnBu 的理由，這篇把它推翻了）\n- 同樣是「視覺優先 vs 教科書正解」的權衡：[地圖標籤密集時，competition ranking 還是 dense ranking？](/blog/competition-vs-dense-ranking-map-labels)\n- 系列總結：[打造 TaxMap-TW 完整心得：6 個技術決策、踩了 4 個坑](/blog/taxmap-tw-postmortem-6-decisions-4-pitfalls)", "summary": "做 TaxMap-TW 色階換三次，最後選 OrRd 不是因為好看，而是把「色階」拆成用色 (hue) + 分桶 (binning) 兩個獨立決策重新組裝。對數絕對門檻（30/50/80/130/200/350 萬）+ OrRd 7 級 = 跨年顏色穩定、中產區段視覺最寬、outlier 自然分出。", "image": "https://bobochen.dev/_astro/cover.Ckn3tKnv.webp", "date_published": "2026-05-27T00:00:00.000Z", "tags": [ "資料視覺化", "地圖", "MapLibre", "ColorBrewer", "Choropleth" ] }, { "id": "https://bobochen.dev/blog/pmtiles-http-range-request-single-file-tiles/", "url": "https://bobochen.dev/blog/pmtiles-http-range-request-single-file-tiles/", "title": "PMTiles 取代傳統 tile server：HTTP Range Request 的單檔魔術", "content_text": "PMTiles 把上千萬個 tile 打包成單一檔案，靠 HTTP Range Request 讓瀏覽器只讀需要的部分，沒有 tile server、丟到 S3 就能用。整理它的設計、跟 MBTiles 的差異、何時不該用，以及在 TaxMap-TW 怎麼用 tippecanoe 產一個。", "content_html": "> **沒有底圖、tile、vector tile 的基本概念？**\n> 建議先看 [Web 地圖底圖是什麼？vector vs raster、tile pyramid、style spec 一次搞懂](/blog/web-map-tile-basics-vector-raster-style)。\n\n在 [上一篇底圖比較](/blog/openfreemap-maptiler-base-map-comparison) 提到「自架需要 100GB+ 儲存」，我把自架直接排除了。但其實有第三條路：**PMTiles**。\n\nPMTiles 是 [Protomaps](https://protomaps.com/) 出品的新型 tile 格式。它的核心想法很瘋狂：\n\n**把上千萬個 tile 打包成 1 個檔案，丟到 S3 / R2 / Cloudflare Pages，瀏覽器靠 HTTP Range Request 只讀需要的位元組。**\n\n沒有 tile server、沒有 Docker、沒有資料庫。你可以把它想成「靜態檔案上的 tile 服務」。\n\n[TaxMap-TW](https://github.com/bobo52310/TaxMap-TW) 的 7,747 個村里 polygon 就是這樣上線的：一個 5.7 MB 的 `.pmtiles` 檔放在 Cloudflare Pages，瀏覽器只讀當前視窗需要的 chunks。整個地圖服務沒有任何 server。\n\n這篇拆解 PMTiles 的設計，以及實戰怎麼產一個。\n\n## 為什麼 PMTiles 想取代傳統 tile server\n\n傳統做法是這樣的：\n\n1. 用 [tippecanoe](https://github.com/felt/tippecanoe) 把 GeoJSON 切成 vector tiles，輸出成 MBTiles（一個 SQLite 檔，內含上萬條 tile blob）\n2. 跑一個 tile server（[tileserver-gl](https://github.com/maptiler/tileserver-gl)、[martin](https://github.com/maplibre/martin)）讀 MBTiles\n3. tile server 暴露 `/{z}/{x}/{y}.pbf` HTTP endpoint\n4. 瀏覽器透過 MapLibre 請求 tile\n\n這個架構的痛點：\n\n- **需要 server**：得有一台機器跑 24/7\n- **需要 SQLite 隨機讀**：tile server 要把 MBTiles 開著、不停讀\n- **冷啟動慢**：Cloud Run / Lambda 第一次請求 tile 要載入整個 SQLite\n- **延展性與成本**：流量大時 server 變瓶頸\n\n對小型 / 靜態網站來說，光是「為了底圖而養一台 server」就讓很多人卻步。\n\n不過先把話說公道：tile server 的這些「麻煩」反過來也是它的能力。它能即時更新——資料一改、下一次請求就拿到新 tile，不用重切；能在伺服器端依參數過濾，回傳不同子集；能依登入身分或權限產出不同的 tile。這些都是把資料封進一個靜態檔的 PMTiles 做不到的。所以它不是「過時」，而是換了一組取捨。下面講的痛點，是針對「資料不常變、不需要動態查詢」的場景。\n\n## PMTiles 的核心想法\n\nPMTiles 直接把問題拆掉：先把所有 tile（z/x/y 索引到 pbf binary）排成一個檔案、前面附上一份目錄（directory），然後把這個檔案丟到任何支援 HTTP Range Request 的地方（S3、R2、Cloudflare Pages、GitHub Pages 都行）。之後瀏覽器需要某個 `(z, x, y)` 的 tile 時，會先讀目錄查到那塊 tile 的 byte offset 和 length，再發一個像 `Range: bytes=12345-67890` 的請求，CDN 就只回那段 binary，MapLibre 直接吃。\n\n整個流程沒有任何 server。`.pmtiles` 就是個靜態檔，CDN 加速、邊緣節點、cache 全都能用——前提是 host 真的支援 Range Request。它得在回應帶 `Accept-Ranges: bytes`、對 `Range` 請求回 `206 Partial Content`，跨網域用時還要設好 CORS。S3、R2、Cloudflare Pages、GitHub Pages 都 OK，但自架 nginx 或某些 CDN 設定不見得預設開。上線前用 `curl -I -H \"Range: bytes=0-99\"` 看一眼回的是不是 206，最省事。\n\n### HTTP Range Request 是什麼？\n\nHTTP/1.1 早就有的功能（規格出自 1997 年的 RFC 2068，後來併入 1999 年的 RFC 2616），但很多人沒用過。\n\n瀏覽器送出：\n\n```http\nGET /villages.pmtiles HTTP/1.1\nHost: tiles.example.com\nRange: bytes=12345-67890\n```\n\n伺服器回應：\n\n```http\nHTTP/1.1 206 Partial Content\nContent-Range: bytes 12345-67890/5998619\nContent-Length: 55546\n\n<那段 binary>\n```\n\n關鍵點：**伺服器只回那個範圍**，不會把整個 6 MB 檔案傳給你。\n\n這個能力一直存在，PMTiles 只是聰明地用它來實作「單檔 tile 服務」。\n\n## PMTiles vs MBTiles 比較\n\n| 項目 | MBTiles | PMTiles |\n|------|---------|---------|\n| 格式 | SQLite（gzip 壓縮的 tile blob） | 自訂二進位 (header + directory + tile blobs) |\n| 需要 server | 是（tile-server-gl / martin） | 否 |\n| 部署 | server + SQLite 檔 | 一個 .pmtiles 檔 + 靜態 host |\n| 客戶端讀取 | 透過 server HTTP API | 瀏覽器直接 HTTP Range |\n| Cloud-native | 不友善（要 server 跑 SQLite） | 完美（純靜態檔） |\n| 工具支援 | 老牌、生態廣 | 較新但 tippecanoe 直接支援 |\n| 適合場景 | 自架 tile 服務、企業內部 | 靜態網站、無 server、低成本 |\n\n對 Cloudflare Pages、Vercel、GitHub Pages 這類只能放靜態檔、不能跑 server 的託管，PMTiles 幾乎是唯一不用另外架服務就能上 vector tile 的選項。\n\n## PMTiles 的限制：什麼時候不該用\n\n寫到這裡好像 PMTiles 全面碾壓，但它換來的好處是有代價的。Protomaps 官方自己就有一篇〈[You Might Not Want PMTiles](https://docs.protomaps.com/pmtiles/cloud-storage#you-might-not-want-pmtiles)〉，我自己用下來，下面幾個情況我不會選它：\n\n- **資料常變動**：PMTiles 是不可變的單一檔。改一個村里的幾何，就得整包重切、重傳、讓 CDN 重新快取。TaxMap 的村里界一年才更新一次，這成本可以接受；如果是每天甚至每小時更新的資料，傳統 tile server 的「改了就生效」反而省事。\n- **需要動態查詢或權限控管**：PMTiles 出去的是固定的一份檔，沒辦法依使用者身分、登入狀態回不同內容。要「付費才看高解析、依角色給不同圖層」這種需求，還是得有一層 server 把關。\n- **巨型資料集**：檔案越大、目錄越深，一次 tile 請求可能要先讀好幾跳目錄才找到 byte offset，Range Request 的來回次數跟頻寬都會上去。幾 MB 到幾百 MB 很舒服，但到了幾十 GB 的全球底圖等級，就要認真評估 CDN 命中率與請求數，不是無腦丟上去就好。\n\n簡單說：**資料靜態、規模中小、不需要伺服器端邏輯時，PMTiles 很香；反過來就回去用 tile server。**\n\n## 3 步驟產一個 PMTiles\n\n完整實戰：把一份 GeoJSON 變成可以丟 CDN 的 `.pmtiles`。\n\n### 1. 裝 tippecanoe\n\n[tippecanoe](https://github.com/felt/tippecanoe) 是把 GeoJSON 切成 vector tile 的 CLI。原來是 Mapbox 出的，但他們從 2020 停更，現在用社群維護的 felt fork：\n\n```bash\nbrew install tippecanoe\n# 或從 source build\ngit clone https://github.com/felt/tippecanoe.git\ncd tippecanoe && make -j && sudo make install\n```\n\n> 注意 Mapbox 原版 `tippecanoe` 已 2020 年停更，felt fork 是現役版本。它的 `--output` 看副檔名自動決定格式，`.mbtiles` 和 `.pmtiles` 兩種都能直接吐——所以同一份 GeoJSON 想換格式，只要改輸出檔名就好。\n\n### 2. 從 GeoJSON 產 PMTiles\n\n最簡單的命令：\n\n```bash\ntippecanoe \\\n --output=villages.pmtiles \\\n --layer=villages \\\n --minimum-zoom=6 \\\n --maximum-zoom=13 \\\n --detect-shared-borders \\\n --coalesce-densest-as-needed \\\n --extend-zooms-if-still-dropping \\\n --force \\\n villages.geojson\n```\n\n幾個關鍵 flag：\n\n- `--minimum-zoom / --maximum-zoom`：要切哪些 zoom level。z=6 看全國，z=13 看里街道\n- `--detect-shared-borders`：相鄰 polygon 共用邊界，省 50% 大小\n- `--coalesce-densest-as-needed`：低 zoom 自動合併小 polygon 避免破圖\n- `--extend-zooms-if-still-dropping`：高 zoom 還有特徵會自動延伸\n\n跑 30 秒，吐出 5.7 MB 的 `villages.pmtiles`。\n\n### 3. 放到 CDN + 在 MapLibre 接\n\n把 `villages.pmtiles` 丟到 `public/data/geometry/villages.pmtiles`，部署到 Cloudflare Pages。\n\n前端裝 [pmtiles npm](https://github.com/protomaps/PMTiles)：\n\n```bash\npnpm add pmtiles\n```\n\n接到 MapLibre：\n\n```ts\nimport maplibregl from 'maplibre-gl';\nimport { Protocol } from 'pmtiles';\n\n// 註冊 pmtiles:// protocol handler\nconst protocol = new Protocol();\nmaplibregl.addProtocol('pmtiles', protocol.tile);\n\nconst map = new maplibregl.Map({\n container: 'map',\n style: 'https://tiles.openfreemap.org/styles/positron',\n center: [121.0, 23.7],\n zoom: 7,\n});\n\nmap.on('load', () => {\n map.addSource('villages', {\n type: 'vector',\n url: 'pmtiles:///data/geometry/villages.pmtiles',\n promoteId: 'VILLCODE', // 把 properties.VILLCODE 提升為 feature.id\n });\n\n map.addLayer({\n id: 'villages-fill',\n type: 'fill',\n source: 'villages',\n 'source-layer': 'villages',\n paint: {\n 'fill-color': '#41b6c4',\n 'fill-opacity': 0.7,\n },\n });\n});\n```\n\n關鍵在 `pmtiles://` 這個自訂 protocol。MapLibre 看到 `pmtiles://...` 開頭的 URL 會交給 `Protocol.tile` handler，handler 用 HTTP Range Request 讀取 PMTiles。\n\n> 上面 `fill-color` 我先寫死成 YlGnBu 的青色 `#41b6c4` 只是為了把幾何畫出來。所得地圖真正的色階後來改成了 OrRd，原因見 [為什麼我把所得地圖色階從 viridis 換成 OrRd](/blog/orrd-warm-palette-two-decisions-framework)。\n\n對 MapLibre 來說，這就像是個正常的 vector tile source。但實際上瀏覽器只下載當前視窗需要的幾個 chunks（首屏約 200 KB），不是整個 6 MB。\n\n## PMTiles 在 TaxMap-TW 的實戰\n\n[TaxMap-TW](https://github.com/bobo52310/TaxMap-TW) 是個剛上線的台灣所得稅地圖，全台 7,747 個村里 polygon 都用 PMTiles 上線。\n\n實際整合的踩雷：\n\n**1. 從 MOI 下載的 Shapefile 是 Big5 編碼**\n\n[內政部國土測繪中心](https://maps.nlsc.gov.tw/) 的村里界 shapefile zip 內含中文檔名，macOS 預設 `unzip` 會崩潰。改用 macOS native `ditto`：\n\n```bash\nditto -x -k villages-1130928.zip villages-shp/\n```\n\n**2. tippecanoe 的 `--read-parallel` 會把 5.6 MB 的 GeoJSON 切碎解析錯誤**\n\n我的 GeoJSON 一行一個 feature（mapshaper 輸出格式）。`--read-parallel` 想平行讀但會在某些行切錯。**單線程讀更穩**，30 秒也不算慢。\n\n**3. `promoteId` 是必須的**\n\n預設情況下 tippecanoe 產出的 tile 不會把 properties 的 ID 欄位提升到 feature.id。這會導致 MapLibre 的 `setFeatureState`（用來做 hover 反白）失效。在 source 設定加 `promoteId: 'VILLCODE'` 即可。\n\n**4. Mapshaper 簡化要用 `keep-shapes`**\n\n把 NLSC 50 MB 的 shapefile 簡化到 5.6 MB GeoJSON，預設會「丟掉太小的 polygon」。但每個村里都要保留，所以要加 `-simplify 5% keep-shapes`，太小的村里也會被保留。\n\n## 反思\n\n讓我印象最深的是 Range Request 這個東西本身。它出自 1997 年的 RFC 2068、躺在 HTTP 規格裡快三十年，PMTiles 在 2021 年初發表、那年 FOSS4G 上正式亮相後，GIS 圈才比較多人這樣用它來做單檔 tile 服務。倒不是「沒人想到」，而是要等 R2 這類便宜物件儲存、CDN 對 Range 的普遍支援、瀏覽器端讀 PMTiles 的函式庫這幾個條件同時成熟，這套玩法才划算。我那天接完 `pmtiles://` 看到地圖跑起來、整個專案連一台 server 都沒有，確實愣了一下——原來繞了一圈，答案是 HTTP 本來就會的事。\n\n架構上 PMTiles 是「移除中間層」：傳統 tile 架構有 4 層（origin DB → tile server → CDN → browser），它直接拿掉 tile server 那層（origin file → CDN → browser）。少一層確實少一個故障點，但代價是原本集中在 server 那層的快取策略、可觀測性、錯誤處理也一起沒了，這些複雜度其實是轉嫁到了客戶端和 CDN 設定上，只是不再是「我要顧的一台機器」而已。\n\n成本面，PMTiles + Cloudflare 的零成本全端組合對個人專案、低中流量、用量落在免費額度內的情況，幾乎可以做到月付 $0：TaxMap-TW 的 OpenFreeMap 底圖、PMTiles polygon、SSG 靜態頁、CDN 流量加起來就是 $0。但 $0 不是物理定律——Range Request 一樣算請求數和頻寬，真的爆紅、流量衝破免費額度，帳單照樣會來。\n\n> 後記：這篇講的「TaxMap 放在 Cloudflare Pages」其實是當時的狀態。後來「一頁一檔」的 SSG 頁面撞到 Cloudflare Pages 的 2 萬檔上限，我把站搬到了 Netlify，過程寫在 [Cloudflare Pages 的 20,000 檔案上限](/blog/cloudflare-pages-20000-file-limit-taxmap-netlify)。PMTiles 這套單檔做法本身沒變，變的是放它的平台。\n\n如果你有「想做地圖但被 server 嚇退」的點子，週末花一兩個小時，從 GeoJSON 到丟上 CDN 是真的跑得完的——只是記得先確認你的資料是不是適合走靜態這條路。\n\n## 系列其他文章\n\n- → [Web 地圖底圖是什麼？vector vs raster、tile pyramid、style spec 一次搞懂](/blog/web-map-tile-basics-vector-raster-style)\n- → [OpenFreeMap vs MapTiler vs Mapbox：6 個 Web 地圖底圖服務怎麼選？](/blog/openfreemap-maptiler-base-map-comparison)\n- → [資料地圖該用哪種色階？viridis、YlGnBu 與 ColorBrewer 實戰指南](/blog/data-map-color-scale-viridis-ylgnbu)\n- → [打造 TaxMap-TW 完整心得：6 個技術決策、踩了 4 個坑](/blog/taxmap-tw-postmortem-6-decisions-4-pitfalls)", "summary": "PMTiles 把上千萬個 tile 打包成單一檔案，靠 HTTP Range Request 讓瀏覽器只讀需要的部分，沒有 tile server、丟到 S3 就能用。整理它的設計、跟 MBTiles 的差異、何時不該用，以及在 TaxMap-TW 怎麼用 tippecanoe 產一個。", "image": "https://bobochen.dev/_astro/cover.DCTaMbj6.webp", "date_published": "2026-05-27T00:00:00.000Z", "tags": [ "WebGIS", "地圖", "PMTiles", "MapLibre", "protomaps" ] }, { "id": "https://bobochen.dev/blog/taxmap-tw-postmortem-6-decisions-4-pitfalls/", "url": "https://bobochen.dev/blog/taxmap-tw-postmortem-6-decisions-4-pitfalls/", "title": "打造 TaxMap-TW 完整心得：6 個技術決策、踩了 4 個坑", "content_text": "TaxMap-TW（台灣所得稅地圖）月成本 $0、4-5 天從零上線的完整復盤：底圖、色階、PMTiles、Astro 6 SSG、FIA 直拓、Competition Ranking 共 6 個技術決策，與 macOS unzip Big5、MapLibre 容器尺寸卡 0×0 等 4 個踩過的坑。", "content_html": "起點其實只是一個很自私的問題：我想知道我家那個里，所得在全台排第幾。查不到現成的，就乾脆自己做一個。\n\n[TaxMap-TW](https://github.com/bobo52310/TaxMap-TW) 後來做成了全台 7,747 個村里的所得稅地圖（11 年資料、4 個指標、雙維度排名、YoY 變動、歷年折線圖、搜尋），月成本 $0，從零到上線大概花了 4-5 天。\n\n這篇是整個系列的收尾，回顧 6 個關鍵技術決策、踩過的 4 個坑，還有事後回頭看才想通的幾件事。\n\n## TaxMap-TW 的 6 個技術決策\n\n每個決定都有對應的詳細文章。這篇是 index。\n\n### 1. 底圖：OpenFreeMap\n\n> 詳細：[OpenFreeMap vs MapTiler vs Mapbox：6 個 Web 地圖底圖服務怎麼選？](/blog/openfreemap-maptiler-base-map-comparison)\n\n候選：Mapbox（業界標準、5 萬次/月免費）vs MapTiler（10 萬 requests 或 5,000 sessions/月）vs OpenFreeMap（無限免費）vs NLSC（政府服務）。\n\n選 OpenFreeMap。理由：**對公民科技/個人專案，「免費無上限」比「業界標準」更重要**。\n\n不過要誠實講 OpenFreeMap 的代價：它沒有 SLA、目前是單人維運、沒有商業等級的 backup、可選 style 也少。所以這個選擇只在「掛掉幾小時也沒人會死」的低營運風險場景成立——像這種個人 / 公民科技專案。如果是公司產品、有營收綁在地圖可用性上，我會老實付錢給 MapTiler 或 Mapbox 換 SLA。\n\n### 2. 色階：YlGnBu + Jenks 自然斷點\n\n> 詳細：[資料地圖該用哪種色階？viridis、YlGnBu 與 ColorBrewer 實戰指南](/blog/data-map-color-scale-viridis-ylgnbu)\n\n候選：viridis（學術主流）vs YlGnBu（公部門報告風）vs YlOrRd（媒體吸睛）。\n\n選 YlGnBu + Jenks。理由：**色階要配合資料的長尾分布**，台灣所得高度集中於少數里，等距分級會變「90% 同色 + 幾顆紅點」。\n\n（後記：這是當時的決策，但上線後我又把色階整個換掉了，從 YlGnBu 改成 OrRd、Jenks 改成對數絕對門檻，原因見 [為什麼我把所得地圖色階從 viridis 換成 OrRd](/blog/orrd-warm-palette-two-decisions-framework)。）\n\n### 3. 切片：PMTiles\n\n> 詳細：[PMTiles 取代傳統 tile server：HTTP Range Request 的單檔魔術](/blog/pmtiles-http-range-request-single-file-tiles)\n\n候選：傳統 tile server（要 24/7 機器）vs PMTiles（單檔 + HTTP Range Request）。\n\n選 PMTiles。理由：**用 HTTP 標準繞過「需要 server」的傳統假設**，丟靜態託管就能用，$0 月支出。\n\n要補一個適用邊界：PMTiles 的甜蜜點是**不常變動的資料**。村里界一年才更新一次，封裝成單檔最划算。如果你的資料頻繁更新、或需要動態查詢 / 即時篩選 tile，傳統 tile server 還是有它的位置——PMTiles 是在「靜態場景」取代 tile server，不是全面取代。\n\n（後記：當時我以為「丟 Cloudflare Pages」就完美收工了，結果上線後撞到 CF Pages 單站 2 萬檔上限——光是 OG 圖就爆量——最後整站搬到 Netlify，過程見 [Cloudflare Pages 的 20,000 檔案上限](/blog/cloudflare-pages-20000-file-limit-taxmap-netlify)。）\n\n### 4. 框架：Astro 6 SSG\n\n候選：Next.js（SSR + ISR）vs Astro（SSG）vs Vue/Nuxt vs SvelteKit。\n\n選 Astro 6 SSG。理由：**這個專案 100% static**（5 個固定路由 + 22 個縣市頁 + 7,747 個里詳細頁 + 1 個排行榜，全部 build time 預產）。Astro 對 SSG 場景比 Next.js 更輕、更快。最重要的是它有 **island architecture**：地圖元件 `client:only`、其他全部純 SSG，bundle 超小。\n\n但 SSG 不是沒代價：資料一更新就得整站重 build，這個專案因為村里資料一年才動一次，重 build 的成本可以忽略，所以 fit。如果是天天變的資料，Next.js 的 ISR（增量靜態再生）就是為這種場景存在的，那時候我會選 Next.js 而不是硬撐 SSG。說到底還是場景 fit，不是 Astro 一定贏 Next.js。\n\n7,774 個頁面 build 時間 7.5 秒。\n\n### 5. 資料：直接從 FIA 拓\n\n> 詳細：[從 PDF / CSV 到 JSON：政府開放資料的 ETL 實戰](/blog/tw-gov-open-data-csv-etl-fia-tax)\n\n候選：fork 既有專案的整理過 CSV vs 自己從 FIA 抓原始檔。\n\n選自己抓。理由：**乾淨的資料故事**，加上 schema 跨年漂移、合計過濾、罕用字 mojibake 都得自己處理，這個過程也是學習。\n\n但要把這個 trade-off 講清楚，別讓人誤會「自己拓一定比較好」：如果你的目標是**快速產出**、把東西做出來給人用，fork 別人整理好的 CSV 才是務實選擇，可以省掉好幾小時的 ETL 苦工。我選自己拓，是因為這是個人專案、沒有交付壓力，付得起這個「多花 3 小時換乾淨資料」的奢侈。換成接案或有 deadline，我大概會直接 fork。\n\n### 6. 排名：Competition Ranking\n\n> 詳細：[競爭排名 vs 密集排名 vs 百分位：地圖標籤的 ranking 設計](/blog/competition-vs-dense-ranking-map-labels)\n\n候選：Standard / Competition / Modified Competition / Dense / Fractional 共 5 種。\n\n選 Competition Ranking。理由：跟奧運排名一致，使用者直覺；同分共享是公平的處理；「跳過名次」雖然會讓最大排名 < 總數，但這是正確行為。\n\n## 4 個踩過的坑\n\n### 坑 1：NLSC zip 內含 Big5 編碼檔名\n\n[內政部國土測繪中心](https://maps.nlsc.gov.tw/) 提供的村里界 shapefile 是 zip 內含中文檔名。**macOS 預設 `unzip` 會崩潰**，因為它把檔名當 UTF-8 解析但裡面是 Big5。\n\n```text\ncheckdir error: cannot create villages-shp/߯®Ω¨…æ˙•vπœ∏Í_113\nIllegal byte sequence\n```\n\n解法：用 macOS 內建的 `ditto`，它會處理 legacy filename charsets：\n\n```bash\nditto -x -k villages-1130928.zip villages-shp/\n```\n\nLinux 上 `unzip -O cp950` 也可以指定編碼——但要注意 `-O` 不是上游 Info-ZIP 的預設選項，是 Debian / Ubuntu 打的 patch 才有，其他發行版（或自己編譯的版本）不一定吃這個 flag。\n\n政府服務的 zip 到 2026 年還是常用 Big5 檔名，這件事我已經學會不要再期待它會改了，手邊備好 `ditto` 跟支援 `-O` 的 `unzip` 就是。\n\n### 坑 2：MapLibre 強制把容器設為 position:relative\n\n我的 HTML 結構是：\n\n```html\n
\n
\n
\n```\n\n預期：`absolute inset-0` 讓 `#map` 填滿父 section。\n\n實際：**MapLibre 把 `#map` 強制設為 `position: relative`**（為了 attribution / control 的內部定位），讓 `absolute inset-0` 整組失效。\n\n```text\nmapW: 902, mapH: 0 ← 0 高度！\n```\n\n地圖渲染進一個 0 高度的容器。沒任何錯誤訊息。\n\n解法：別用 `absolute inset-0`，直接用 `h-full w-full`：\n\n```html\n
\n
\n
\n```\n\n這個坑教我一件事：第三方 widget 常常會偷改容器 style，而且不報錯。後來只要遇到「東西不顯示但 console 一片乾淨」，我都先打開 `getComputedStyle()` 看實際算出來的樣式，比盯著 console error 有用太多。\n\n### 坑 3：Astro hydration 後容器尺寸變動，MapLibre 卡 0×0\n\n跟坑 2 相關但更陰險。\n\n修好容器高度後，地圖底圖偶爾還是渲染失敗。canvas 大小正確、`isStyleLoaded()` 為 true、attribution 顯示出來，但 **0 個 tile request**。\n\n挖下去發現：MapLibre 在 `new Map()` 時記錄容器尺寸，**後續容器尺寸變動不會自動觸發 tile fetch**。Astro 的 island hydration 會在 map 建立後重新算 layout，導致 map 內部的 viewport 仍是 0×0。\n\n解法：在 constructor 後排幾個 resize：\n\n```typescript\nconst forceResize = () => this.map.resize();\nrequestAnimationFrame(forceResize);\nsetTimeout(forceResize, 100);\nsetTimeout(forceResize, 500);\n```\n\n醜，但 work。\n\n**Lesson**：第三方 widget + SSG/island 框架的整合常有「初始化時機」問題。一個 hack-y 但穩定的解法（多次 resize）比追求乾淨更實用。\n\n### 坑 4：tippecanoe `--read-parallel` 切碎 GeoJSON 解析錯誤\n\n跑 tippecanoe 把 GeoJSON 變 PMTiles 時遇到：\n\n```text\nvillages.simplified.geojson:1247: Found ] at top level\nvillages.simplified.geojson:1040: Reached EOF without all containers being closed\n```\n\n奇怪，我的 GeoJSON 結構明明是正確的，第 1247 行也不會有問題。\n\n挖下去發現是 `--read-parallel` 把 5.6 MB 的 GeoJSON 切成多個 chunk 平行解析。我的 GeoJSON 是「一行一個 feature」的格式（mapshaper 預設輸出），平行讀會在某些行切錯。\n\n解法：拿掉 `--read-parallel`。單線程讀 30 秒，不算慢。\n\n這裡的教訓是：CLI 工具的「快速 mode」flag 通常偷偷假設了某種輸入格式。`--read-parallel`、`--parallel`、`--fast` 這類 flag 一出問題，我現在的反射動作是先回到單線程版本確認，是工具的鍋還是我資料的鍋，一試就知道。\n\n## 整個專案的總結\n\n**規模**：\n\n- 5 個 routes + 7,774 個 SSG 頁面（5 + 22 + 7,747）\n- 11 年 × 4 指標 × 2 維度 = 88 組排名 pre-compute\n- 5.7 MB PMTiles + 17 MB stats JSON + 39 MB rankings JSON\n- 月成本 $0（OpenFreeMap + PMTiles + 靜態託管全免費）\n\n**時間**：\n\n- 規劃 + 研究：1 天（含底圖、色階、PMTiles 三個技術選型）\n- 資料管線：1 天（FIA fetcher + stats + rankings + verify）\n- 地圖 + UI：1.5 天（5 個頁面 + 地圖互動 + 搜尋 + 圖表）\n- 部署 + 收尾：0.5 天\n- 總計 4-5 天\n\n**事後回頭看才想通的幾件事**：\n\n做完這個專案，我最有感的一個轉變是：我以前會問「哪個技術比較好」，現在會先問「在我這個場景哪個比較 fit」。Mapbox 是業界標準，但 5 萬次/月對開源專案太緊；自架 tile server 技術上完全可行，但對一個要 $0 月支出的專案來說，PMTiles 的單檔方案就是更對；FIA CSV 自己拓比 fork 別人多花 3 小時，可是換來乾淨的資料故事。沒有一個決定是純技術考量。不過要補一句：這套「看 fit 不看絕對好壞」的邏輯有個前提，就是這些維度都還能妥協。有一個維度我完全不讓步，就是稅務數字本身的正確性，這個錯了整個地圖就沒有存在意義，所以資料管線那關我做了最多 verify。\n\n第二件事是新興工具真的值得試。OpenFreeMap（2024）、PMTiles（2022）、felt/tippecanoe（接手 Mapbox 棄子），這些都是 2-3 年前還不存在或不成熟的東西。技術圈的習慣是等成熟再用，但小型個人專案剛好是試新東西最划算的場域，賭錯了也只是我自己多花幾天。我會這樣賭，正是因為它低風險；同樣這幾個工具如果要進公司的生產系統，我會先盯著它們的維運狀態和 backup 方案再說，不會這麼隨性。\n\n第三件事比較像心態：「不完美但可用」是公民科技的常態。99.66% 的村里 JOIN 率、80% 的功能、$0 月成本，這個組合對開源 / 公民科技其實已經夠用了。追求 100% 完美常常會把預算和熱情都耗光，做不到上線那一步。但「夠用」也要分維度，前面講的稅務正確性就不在「夠用就好」的範圍內。\n\n## 系列全集\n\n整個系列總共 10 篇，按推薦閱讀順序：\n\n1. **入門基礎** → [Web 地圖底圖是什麼？vector vs raster、tile pyramid、style spec 一次搞懂](/blog/web-map-tile-basics-vector-raster-style)\n2. **底圖選型** → [OpenFreeMap vs MapTiler vs Mapbox：6 個 Web 地圖底圖服務怎麼選？](/blog/openfreemap-maptiler-base-map-comparison)\n3. **資料管線** → [從 PDF / CSV 到 JSON：政府開放資料的 ETL 實戰](/blog/tw-gov-open-data-csv-etl-fia-tax)\n4. **色階設計** → [資料地圖該用哪種色階？viridis、YlGnBu 與 ColorBrewer 實戰指南](/blog/data-map-color-scale-viridis-ylgnbu)\n5. **排名演算法** → [競爭排名 vs 密集排名 vs 百分位：地圖標籤的 ranking 設計](/blog/competition-vs-dense-ranking-map-labels)\n6. **進階技術** → [PMTiles 取代傳統 tile server：HTTP Range Request 的單檔魔術](/blog/pmtiles-http-range-request-single-file-tiles)\n7. **整體復盤** → 本文\n8. **色階再進化** → [為什麼我把所得地圖色階從 viridis 換成 OrRd：把「一個決策」拆成「兩個獨立軸」](/blog/orrd-warm-palette-two-decisions-framework)\n9. **搬站踩坑** → [Cloudflare Pages 的 20,000 檔案上限：TaxMap-TW 為什麼搬到 Netlify](/blog/cloudflare-pages-20000-file-limit-taxmap-netlify)\n10. **OG 圖生成** → [用 Cloudflare Worker 按需生成 OG 圖：Satori + resvg 為 TaxMap-TW 產 7,750 張預覽圖](/blog/cloudflare-worker-on-demand-og-satori-taxmap)\n\n> 本文（第 7 篇）寫的是「當時上線那一刻的決策」。第 8、9 篇記錄的是上線之後我又改掉的兩件事——色階換成 OrRd、託管從 Cloudflare Pages 搬到 Netlify——所以前面決策段落裡你會看到對應的後記註記。\n\nGitHub repo：[TaxMap-TW](https://github.com/bobo52310/TaxMap-TW)", "summary": "TaxMap-TW（台灣所得稅地圖）月成本 $0、4-5 天從零上線的完整復盤：底圖、色階、PMTiles、Astro 6 SSG、FIA 直拓、Competition Ranking 共 6 個技術決策，與 macOS unzip Big5、MapLibre 容器尺寸卡 0×0 等 4 個踩過的坑。", "image": "https://bobochen.dev/_astro/cover.QyDoHDUQ.webp", "date_published": "2026-05-27T00:00:00.000Z", "tags": [ "Postmortem", "專案總結", "Astro", "MapLibre", "公民科技" ] }, { "id": "https://bobochen.dev/blog/tw-gov-open-data-csv-etl-fia-tax/", "url": "https://bobochen.dev/blog/tw-gov-open-data-csv-etl-fia-tax/", "title": "從 PDF / CSV 到 JSON：政府開放資料的 ETL 實戰", "content_text": "做 TaxMap-TW 時清理財政部所得稅 CSV 踩到 6 個坑：民國年 vs 西元年命名陷阱、schema 跨年漂移、BOM / 引號變化、「合計」與「其他」過濾、村里名罕用字 mojibake、早期年度只有 PDF 沒 CSV。記錄這些政府開放資料的真實樣貌與 ETL 處理 pattern。", "content_html": "做 [TaxMap-TW](https://github.com/bobo52310/TaxMap-TW) 最讓我意外的不是地圖、不是色階、是資料清理。\n\n我以為「政府開放資料」就是去 [data.gov.tw](https://data.gov.tw/) 抓 CSV → 解析 → 完成。實際做才發現：\n\n- 民國年 vs 西元年命名混淆\n- 同一個 dataset 不同年度 schema 不一樣\n- BOM、引號規則跨年漂移\n- 表格裡藏著「合計」「其他」要過濾\n- 村里名有罕用字 mojibake 跨資料集對不起來\n- 早期年度只有 PDF，沒 CSV\n\n每一條單看都不是技術難題，但全部疊起來，地圖本身兩個晚上就會動了，光把這份資料弄乾淨我花了快一週。\n\n這篇整理我在處理財政部所得稅 CSV 時踩到的 pattern，這些 pattern 在不少政府開放資料上都能類推（至少 CSV / 下載式 dataset 這一類）。\n\n## 陷阱 1：民國年 vs 西元年\n\n財政部的所得稅 CSV 檔名長這樣：\n\n```text\n111_165-9.csv\n112_165-9.csv\n113_165-9.csv\n```\n\n`111`、`112` 是民國年。**但這個民國年指的是「所得發生年」，不是「發布年」或「申報年」。**\n\n舉例：\n\n| 檔名 | 民國年 | 所得發生 | 申報 | 初步核定 | 正式核定 |\n|------|--------|----------|------|---------|---------|\n| `111_165-9.csv` | 111 | 2022 | 2023/5 | 2024/6 | 2025/4 |\n| `112_165-9.csv` | 112 | 2023 | 2024/5 | 2025/6 | **2026/4/30** |\n| `113_165-9.csv` | 113 | 2024 | 2025/5 | **預估 2026/6-7** | 預估 2027/4 |\n\n所以「2024 年的資料」是模糊的：\n\n- 「2024 年發布的」= 民國 111（income year 2022）的核定版？還是民國 112 的初步核定版？\n- 「income year 2024」= 民國 113 = 還沒發布\n\n寫程式時要明確：**所有公開介面都用西元年（income year），內部存民國年只用在組 URL**。\n\n```typescript\nconst ROC_OFFSET = 1911;\nconst rocToCe = (rocYear: number) => rocYear + ROC_OFFSET;\nconst fiaCsvUrl = (rocYear: number) =>\n `https://www.fia.gov.tw/WEB/fia/ias/ias${rocYear}/${rocYear}_165-9.csv`;\n```\n\n這樣 user-facing 永遠是「2022 年所得」，build script 才用 `111` 組 URL。\n\n## 陷阱 2：Schema 跨年漂移\n\n抓下 11 年的 CSV（民國 101–111）後做了第一個 sanity check：每個檔頭幾個 bytes：\n\n```text\n101: e9 84 89 (鄉鎮市區)\n105: ef bb bf e9 84 89 (BOM + 鄉鎮市區)\n106: 22 e9 84 89 (引號 + 鄉鎮市區)\n110: 22 ef bb bf e7 b8 a3 (引號 + BOM + 縣市別)\n111: 22 ef bb bf e7 b8 a3 (引號 + BOM + 縣市別)\n```\n\n三件事跨年變了：\n\n1. **BOM**：民國 101–104 沒 BOM，民國 105 起有 BOM\n2. **引號**：民國 101–105 欄位無引號，民國 106 起加上雙引號\n3. **欄位名**：民國 101–110 的第一欄叫「鄉鎮市區」，民國 111 改叫「縣市別」（但實際資料一樣，都是「臺北市松山區」這種拼接字串）\n\n實際資料一致只是 header label 換名，所以解析時不能用「欄位名匹配」這種精準方法。**用欄位順序、忽略 BOM、忽略引號變化**：\n\n```typescript\nimport Papa from 'papaparse';\n\nconst csv = await readFile(csvPath, 'utf-8');\n// 跨年安全：strip BOM 若存在\nconst trimmed = csv.charCodeAt(0) === 0xfeff ? csv.slice(1) : csv;\n\nconst parsed = Papa.parse(trimmed, {\n header: false, // ← 不要用 header: true，跨年欄位名不一樣\n skipEmptyLines: true,\n transform: v => v.trim(),\n});\n\n// 直接用 row[0], row[1] 索引取值\nfor (const row of parsed.data) {\n const cityTownship = row[0]; // 「臺北市松山區」\n const village = row[1]; // 「中華里」\n const mean = Number(row[4]); // 平均所得\n}\n```\n\n關鍵點：在這個 dataset 裡，欄位順序比欄位名穩定。政府資料的 schema 命名隨時可能改，但欄位順序通常不太動（因為改順序會破壞既有使用者）。\n\n不過「信任欄位順序」不是免費的午餐，它有自己的失效情境。欄位名匹配遇到改名會直接報錯、逼你正視；位置索引遇到中間插一欄、刪一欄、或某年悄悄把兩欄對調，`row[4]` 還是讀得出一個數字，只是默默讀錯——這種**靜默取錯**比 header 對不上更危險，因為它不會炸，會一路把錯的值算進統計。我自己跨年漂移那段就是最好的反例：欄位名才剛被證明會跨年改，憑什麼相信順序就一定不改？\n\n所以我的折衷是「位置索引 + 輕量驗證」：解析時照樣用 `row[0]`、`row[1]` 取值，但每個檔開頭加一道 sanity check，確認欄位數和關鍵欄的型別跟我預期的一致，對不上就讓 build 直接 fail，而不是默默產出錯誤資料。\n\n```typescript\nconst EXPECTED_COLS = 10; // 這個 dataset 固定 10 欄\nfor (const row of parsed.data) {\n // 欄位數變了 → 大概率插欄/刪欄/重排，立刻停下來重新核對 schema\n if (row.length !== EXPECTED_COLS) {\n throw new Error(`欄位數異常：預期 ${EXPECTED_COLS}，實際 ${row.length}`);\n }\n // 該是數字的欄位卻不是數字 → 順序可能跑掉了\n if (Number.isNaN(Number(row[4]))) {\n throw new Error(`row[4] 應為平均所得數字，實際拿到「${row[4]}」`);\n }\n}\n```\n\n位置索引的賭注是「順序穩定」，驗證就是替這個賭注買的保險：賭對了幾乎零成本，賭錯了它會在第一個檔就尖叫，而不是讓你三個月後才發現某年的平均所得整欄錯位。\n\n## 陷阱 3：「合計」「其他」要過濾\n\n逐列檢視資料後發現：\n\n```csv\n\"臺北市松山區\",\"中崙里\",\"1439\",\"2452035\",\"1704\",\"817\",\"356\",\"1902\",\"5899.26\",\"346.20\"\n\"臺北市松山區\",\"自強里\",\"3029\",\"4355839\",\"1438\",\"666\",\"285\",\"1629\",\"3517.94\",\"244.63\"\n...\n\"臺北市松山區\",\"其他\",\"451\",\"340002\",\"754\",\"498\",\"268\",\"1016\",\"818.87\",\"108.62\"\n\"臺北市松山區\",\"合計\",\"69082\",\"98796332\",\"1430\",\"729\",\"310\",\"1639\",\"4770.51\",\"333.57\"\n\"臺北市大安區\",\"和平里\",\"...\",\"...\",\"...\",\"...\",\"...\",\"...\",\"...\",\"...\"\n```\n\n每個鄉鎮市區的最後兩列是 `其他` 和 `合計`。**這兩列不是村里**：\n\n- 「其他」：該鄉鎮中歸不到任何里的納稅單位\n- 「合計」：該鄉鎮的小計（所有里 + 其他的加總）\n\n如果不過濾，會被當成「2 個額外的村里」算進統計，總數就會錯。每個檔 ~387 個合計 + ~406 個其他要過濾掉。\n\n```typescript\nconst SKIP_VILLAGES = new Set(['合計', '其他']);\n\nfor (const row of parsed.data.slice(1)) { // skip header row\n const village = row[1];\n if (SKIP_VILLAGES.has(village)) continue;\n // 真正的村里\n}\n```\n\n過濾掉後民國 111 剩 7,748 個村里。這是 FIA 這份資料過濾後可對應到的村里數，與內政部公布的全台村里口徑量級一致（官方數字本身會逐年微調，不是固定值），不是什麼「官方公布的全台村里總數」——別把這份稅務資料的計數直接當成戶政權威數字。\n\n## 陷阱 4：拼接字串 split\n\n第一欄是「臺北市松山區」這種拼接字串。要拆成「縣市」+ 「鄉鎮市區」兩欄。\n\n我本來以為要寫個正則或字典 lookup。實際看資料：\n\n```text\n南投縣、嘉義市、嘉義縣、基隆市、宜蘭縣、屏東縣、\n彰化縣、新北市、新竹市、新竹縣、桃園市、澎湖縣、\n臺中市、臺北市、臺南市、臺東縣、花蓮縣、苗栗縣、\n連江縣、金門縣、雲林縣、高雄市\n```\n\n**全部 22 個縣市都是 3 個中文字**（最後一字為「市」或「縣」）。\n\n```typescript\nfunction splitCityTownship(combined: string) {\n return {\n city: combined.slice(0, 3),\n township: combined.slice(3),\n };\n}\n```\n\n3 行解決。但要老實說：`slice(0, 3)` 能成立，純粹是「現在這 22 個縣市剛好都是 3 個字」這個巧合。它不是定律——萬一哪天行政區改名、或這份資料混進別的縣市格式，這刀就會切歪，而且一樣是默默切歪。所以我把這個巧合當「可利用但要驗證」的規律，配一張白名單 assert 當安全網：\n\n```typescript\nconst KNOWN_CITIES = new Set([\n '臺北市', '新北市', '桃園市', '臺中市', '臺南市', '高雄市',\n '基隆市', '新竹市', '嘉義市', '新竹縣', '苗栗縣', '彰化縣',\n '南投縣', '雲林縣', '嘉義縣', '屏東縣', '宜蘭縣', '花蓮縣',\n '臺東縣', '澎湖縣', '金門縣', '連江縣',\n]); // 22 個\n\nfunction splitCityTownship(combined: string) {\n const city = combined.slice(0, 3);\n if (!KNOWN_CITIES.has(city)) {\n throw new Error(`切出非預期縣市「${city}」，原字串：${combined}`);\n }\n return { city, township: combined.slice(3) };\n}\n```\n\n規律性是政府資料的隱藏資產，多看幾個 row 比寫 fancy 解析器有用；但「規律」和「保證」是兩件事，能利用就順手加一個 assert 把假設釘死，免得哪天規律破了你還蒙在鼓裡。\n\n## 陷阱 5：跨資料集 JOIN 的罕用字 mojibake\n\n最痛苦的是這個。\n\n我要把 FIA 的「縣市|鄉鎮|村里」資料，跟 NLSC 國土測繪中心的村里界 GeoJSON（用 `VILLCODE` 索引）對起來。\n\n理論上「臺北市松山區中華里」在兩邊都該存在。實際做 JOIN：\n\n```typescript\n// 7,747 個 NLSC codified villages\n// 7,721 matched FIA\n// 26 不 match\n```\n\n99.66% 命中率。剩下 26 個是這種：\n\n```text\n嘉義市|西區|磚𥕢里 ← FIA 用「𥕢」\n嘉義市|西區|磚磘里 ← NLSC 用「磘」\n\n臺南市|安南區|塩埕里 ← FIA 用「塩」\n臺南市|安南區|鹽埕里 ← NLSC 用「鹽」（標準字）\n```\n\n兩個資料集對同一個村里用了不同的「異體字」或「PUA private use area」字。\n\n實際上 [kiang/salary](https://github.com/kiang/salary) 維護一份手動對照表來處理這些，但對我這個「在地圖上塗色」的 MVP 來說 99.66% 已經很夠。\n\n不過這個「夠」是看用途的，不是通則。我這裡每個村里只是地圖上一塊獨立色塊，缺 26 個就是 26 塊顯示「無資料」，不影響其他村里——這種場景 0.34% 缺漏可以接受。但如果今天是要把全台所得**加總**、算各縣市佔比、判斷「某村里有沒有達到某門檻」這類資格判定、或要拿去做學術統計，那 0.34% 就不能放著：缺的不是隨機 26 個，而是**系統性地漏掉用罕用字/異體字的偏鄉里**，等於你的缺漏剛好集中在某一類地區，會讓加總和分佈悄悄偏掉。用途越接近「精確數字」，這 0.34% 越不可妥協。\n\n處理方式：\n\n```typescript\nconst villages: Record = {};\nfor (const feature of geojson.features) {\n const compositeKey = `${COUNTYNAME}|${TOWNNAME}|${VILLNAME}`;\n const hasFiaMatch = fiaStats.has(compositeKey);\n villages[VILLCODE] = {\n code: VILLCODE,\n // ...\n hasStats: hasFiaMatch,\n };\n}\n```\n\n把「有沒有對應 FIA 資料」存進 master JSON，前端遇到沒對應的村里就顯示「目前無資料」。\n\n在「顯示用」的場景下，我寧可承認資料的不完美、誠實標記缺漏，也不硬塞模糊匹配演算法去猜——猜錯一個村里的所得，比老實說「無資料」傷害更大。但這句話別當成「永遠別追 100%」的鐵則：當缺的那 0.34% 會被拿去加總、判定資格或做統計時，該補的對照表還是得補（或至少把缺漏清單攤開讓人知道），而不是用「承認不完美」當不處理的藉口。\n\n## 陷阱 6：早期年度只有 PDF\n\n研究 agent 一開始給我的 URL pattern 是：\n\n```text\nhttps://www.fia.gov.tw/WEB/fia/ias/ias{民國年}/{民國年}_165-9.csv\n```\n\n說「民國 88 (1999) 到民國 112 (2023) 都有」。實測卻發現：\n\n```text\nROC 101-111 (2012-2022): HTTP 200 ✓\nROC 88-100 (1999-2011): HTTP 404 ✗\nROC 112 (2023): HTTP 404 ✗\n```\n\n實際上 CSV 只覆蓋 11 年。早期年度官方只有 PDF；2023 年（民國 112）核定版剛在 2026/4/30 公布但 CSV 還沒上架。\n\n這直接砍掉了「1999-2023 共 25 年」這個 scope。我把專案調整為 MVP 只做 2012-2022。\n\n後來我學乖了：政府資料的「公開」常常分好幾種介面（CSV、XLSX、HTML、PDF、API），而且不同年度開放的介面還不一樣。研究 agent 給的 description 寫得再篤定，規劃前我都先 curl 一輪把每年實際拿不拿得到檔案掃過，再決定 scope，省得做到一半才發現有四年根本沒 CSV。\n\n## 政府開放資料 ETL 的 6 條通用 pattern\n\n整理我這次學到的政府開放資料 ETL 通則：\n\n1. **公開介面用西元年** — 民國年只在組 URL 時用\n2. **不信任 header** — 用欄位順序、處理 BOM 與引號變化\n3. **掃描異常列** — 「合計」「其他」「小計」要過濾\n4. **規律性是寶藏** — 多看幾個 row 通常有 dirty 但穩定的 pattern\n5. **承認資料不完美（看用途）** — 顯示用場景，99% 命中 + 標記 1% missing 比強塞演算法可靠；但要拿去加總、判定資格或做統計時，那 1%（且常系統性漏掉偏鄉罕用字）就得補齊\n6. **規劃前先 curl** — 不同年度公開不同介面，description 不可信\n\n如果這六條只能記一條，我會記第 2 條的延伸版：別相信任何人（包括研究 agent、包括 description、包括上一年的自己）對這份資料長相的描述，自己 curl 下來、自己印出前幾個 byte、自己用 assert 把假設釘住。這次大半的坑，本質都是「我以為它長這樣，它其實長那樣」。\n\n也得老實承認：不是所有鍋都甩給上游。回頭看，這些坑有一半是我自己一開始沒先替整條管線立一份「資料契約」——把「應該幾欄、哪欄是數字、村里數量級、哪些值要過濾」這些預期先寫成 schema validation 擺在最前面，後面任何一年違約就立刻 fail。我是踩了三四個坑之後才補上這層驗證的，要是一開始就建，至少能少跑幾趟「產出怪數字 → 回頭 debug」的冤枉路。我也沒法保證這套打法在每一份台灣政府開放資料上都成立——我的樣本就 FIA 這一份（API、XML、奇怪編碼的資料各有各的故事）——但至少 CSV / 下載式 dataset 這一類，照這六條走能少踩很多坑。\n\n## 系列其他文章\n\n資料清乾淨之後，接下來就是「怎麼把這些村里排名、怎麼畫成地圖」，沿著「清理 → 排名 → 視覺化 → 復盤」的脈絡：\n\n- → [競爭排名 vs 密集排名 vs 百分位：地圖標籤的 ranking 設計](/blog/competition-vs-dense-ranking-map-labels)\n- → [PMTiles 取代傳統 tile server：HTTP Range Request 的單檔魔術](/blog/pmtiles-http-range-request-single-file-tiles)\n- → [打造 TaxMap-TW 完整心得：6 個技術決策、踩了 4 個坑](/blog/taxmap-tw-postmortem-6-decisions-4-pitfalls)\n- → [Web 地圖底圖是什麼？vector vs raster、tile pyramid、style spec 一次搞懂](/blog/web-map-tile-basics-vector-raster-style)\n- → [OpenFreeMap vs MapTiler vs Mapbox：6 個 Web 地圖底圖服務怎麼選？](/blog/openfreemap-maptiler-base-map-comparison)", "summary": "做 TaxMap-TW 時清理財政部所得稅 CSV 踩到 6 個坑：民國年 vs 西元年命名陷阱、schema 跨年漂移、BOM / 引號變化、「合計」與「其他」過濾、村里名罕用字 mojibake、早期年度只有 PDF 沒 CSV。記錄這些政府開放資料的真實樣貌與 ETL 處理 pattern。", "image": "https://bobochen.dev/_astro/cover.CZr_Hb3I.webp", "date_published": "2026-05-27T00:00:00.000Z", "tags": [ "資料工程", "ETL", "開放資料", "TypeScript", "Papa Parse" ] }, { "id": "https://bobochen.dev/blog/web-map-tile-basics-vector-raster-style/", "url": "https://bobochen.dev/blog/web-map-tile-basics-vector-raster-style/", "title": "Web 地圖底圖是什麼？vector vs raster、tile pyramid、style spec 一次搞懂", "content_text": "Web 地圖底圖到底是什麼？這篇用最白話的方式把 vector tile vs raster tile、tile pyramid（z/x/y 金字塔）怎麼設計、style spec 為什麼存在一次講清楚，順便聊 raster 和 vector 各自適合的場景。讀完再回去看其他地圖技術文章會順非常多。", "content_html": "剛開始碰 Web 地圖時，我看技術文章常常卡在一些術語：vector tile、raster tile、tile pyramid、style spec、z/x/y、PMTiles、MBTiles... 每一個拆開都不難，但混在一起就會頭很大。\n\n寫完 [TaxMap-TW](https://github.com/bobo52310/TaxMap-TW) 後回頭整理，發現 Web 地圖底圖其實就是三個核心概念：**tile**、**format**、**style**。把這三個搞懂，其他術語都是周邊。\n\n這篇給沒碰過 GIS 的讀者鋪底，把這三件事說清楚。\n\n## 第一個觀念：Web 地圖底圖為什麼要切成 tile？\n\n打開 Google Maps，你拖、你縮、它都很順。但全球地圖資料動輒幾百 GB，瀏覽器不可能一次下載完。\n\n解法：**把地圖切成方格**，需要哪一塊才下載哪一塊。這個方格就叫 **tile**。\n\n每個 tile 通常是 256×256 或 512×512 像素的小圖。瀏覽器看你縮放到哪個 zoom level、視窗範圍涵蓋哪些 tile，就只下載那幾張。\n\n縮小看全世界 → 1 張 tile 就夠\n放大到台北街道 → 視窗內有 4-8 張 tile\n\n這個機制讓 Web 地圖能用「漸進式載入」處理 PB 等級的資料。\n\n## Tile pyramid（瓦片金字塔）：z/x/y 是什麼？\n\n你常常會看到地圖圖磚的 URL 長這樣：\n\n```text\nhttps://tiles.example.com/{z}/{x}/{y}.pbf\n```\n\n`z` 是 zoom level（縮放等級），`x`、`y` 是該 zoom 下的座標。\n\n整個地圖被組織成「金字塔」結構：\n\n- **z = 0**：整個地球切成 1 張 tile（1×1 = 1 張）\n- **z = 1**：切成 4 張（2×2）\n- **z = 2**：切成 16 張（4×4）\n- ...\n- **z = 18**：切成 687 億張（262144×262144）\n\n每多一個 zoom level，tile 數量乘 4。z=18 大概是看清楚門牌號碼的等級。\n\n對地圖服務商來說，這個金字塔是固定的世界座標，所有人共享同一套切法。你開發地圖時，瀏覽器自動算出「現在這個視窗在 z=10 需要 (532, 411) 這張 tile」，然後請求那個 URL。\n\n## 第二個觀念：vector tile vs raster tile\n\nTile 有兩種主要格式，差別決定了你的地圖能做什麼。\n\n### Raster tile（點陣圖磚）\n\n每張 tile 是一張預先渲染好的 **PNG / JPG 圖片**。瀏覽器拿到就直接貼上去，沒有運算成本，連最老的瀏覽器都吃得下。代價是樣式被烤進圖裡了：顏色改不了、標籤關不掉，文字放大會糊（因為早就被點陣化），而且每換一種風格就得整套重切，存儲很快就爆。\n\n不過我要先澄清一件事，因為我自己一開始也搞錯：raster 不是「過時」，它是「不同需求」。有些東西本來就只能用 raster——衛星影像、空拍圖、地形暈渲這類本身就是像素的資料，沒有 geometry 可以拿來向量化；要列印或匯出成圖檔時，也是點陣圖最直接。基礎建設上 raster 也最簡單，一個資料夾擺一堆 PNG、丟到任何靜態 host 就能跑，不需要 WebGL、不需要 style JSON。Leaflet 這種老牌、輕量的函式庫原生就吃 raster。\n\n所以老牌地圖服務（Google Maps 早期版本、傳統 OSM tile server）用 raster，不代表它們「劣等」，只是當年那個需求 raster 就夠了。\n\n### Vector tile（向量圖磚）\n\n每張 tile 是 **geometry + properties 的二進位資料**（通常 `.pbf` Protocol Buffer 格式），不是圖片。瀏覽器拿到資料後即時渲染，所以可以動態改顏色、隱藏特定圖層，文字永遠清晰（在客戶端用向量字型正確繪製），而且同一套 tile 可以套用無限多種風格。這幾個優點是我選 vector 的主因。\n\n但 vector 不是免費午餐，這點當初的我也低估了。它要用 WebGL，老瀏覽器不支援，渲染還要吃客戶端的 CPU/GPU——這兩點是課本都會講的。實務上真正咬人的是另外幾件：你得載一包 MapLibre GL JS（壓縮後也有兩三百 KB），外加 glyphs（字型切片）和 sprites（圖示集），這些都算進首屏成本，比直接貼 PNG 重得多；行動裝置上持續的 GPU 渲染也比較耗電。如果你想自己切 vector tile（不是用現成服務），tippecanoe 那套工具鏈和 schema 設計的門檻也比烤一堆 PNG 高一截。最後是中文專案逃不掉的坑：CJK 字型切成 glyphs 後檔案動輒幾十 MB，字型 fallback 沒設好就會看到一堆豆腐方塊。\n\n所以我的結論是：如果你只是要在頁面上放一張不會動的底圖，用 vector 其實是殺雞用牛刀，raster 反而省事；vector 的價值要在「需要動態換樣式、疊資料層」時才真的兌現。\n\n近 5 年的主流地圖服務（Mapbox、MapTiler、OpenFreeMap）多半預設 vector tile，但這是「主流方向」不是「raster 被淘汰」——兩者是分工，各自守著不同的場景。\n\n**簡單記憶法**：raster 是「拍照」，vector 是「設計稿」。設計稿可以改顏色，照片不行；但要的就是一張照片時，硬套設計稿流程反而麻煩。\n\n## 第三個觀念：style spec — 同一份 tile，無限種風格\n\n既然 vector tile 是 geometry + properties，那要怎麼決定「這條路畫多粗」、「這個 polygon 上什麼色」？\n\n答案是 **style spec** — 一份 JSON 規格，描述每個圖層怎麼畫。\n\n[MapLibre Style Spec](https://maplibre.org/maplibre-style-spec/)（從 Mapbox GL JS 衍生）是業界標準。一個典型的 style 長這樣：\n\n```json\n{\n \"version\": 8,\n \"sources\": {\n \"openmaptiles\": {\n \"type\": \"vector\",\n \"url\": \"https://tiles.openfreemap.org/planet\"\n }\n },\n \"layers\": [\n {\n \"id\": \"water\",\n \"type\": \"fill\",\n \"source\": \"openmaptiles\",\n \"source-layer\": \"water\",\n \"paint\": {\n \"fill-color\": \"#a1d6f2\"\n }\n },\n {\n \"id\": \"road\",\n \"type\": \"line\",\n \"source\": \"openmaptiles\",\n \"source-layer\": \"transportation\",\n \"paint\": {\n \"line-color\": \"#ffffff\",\n \"line-width\": 1\n }\n }\n ]\n}\n```\n\n每個 `layer` 對應 vector tile 裡的一種圖層（water、road、building...），定義怎麼畫。\n\n換 style URL = 換樣式。底圖資料完全一樣，但灰白底色、深色模式、夜景樣式都是換 style 達成的。\n\n不過「無限種風格」有個前提常被忽略：你只能畫 tile 裡有的東西。style 是在既有的 geometry + properties 上塗色，tile 沒切進去的圖層（例如某個 POI 類別、某條行政界線），style 再怎麼寫也變不出來——那種時候只能回頭重切一份 tile。所以 style 給你的是「呈現自由」，不是「資料自由」。\n\nOpenFreeMap 最常用的是 positron（灰白）、bright（彩色）、liberty（OSM 經典）三種預設 style，另外還有 dark、fiord 等選擇；當然你也完全可以自己寫一份 style JSON 丟給 MapLibre 用。\n\n## 一個典型的 Web 地圖管線\n\n理解了 tile、format、style 之後，現代 Web 地圖的完整管線就清楚了：\n\n```text\nOSM 原始資料 (PB 等級)\n ↓ 切 tile\nVector tiles ({z}/{x}/{y}.pbf)\n ↓ 由 tile server / CDN serve\n你的瀏覽器\n ↓ MapLibre 讀取 tile + 套用 style\n畫在 canvas 上的地圖\n ↓ 你加上自己的資料層（標記、polygon...）\n完整的應用\n```\n\n對開發者來說，要做決定的點是：\n\n1. **Tile 從哪來**：用第三方服務（OpenFreeMap / MapTiler / Mapbox）？自架？\n2. **Style 用什麼**：服務商預設？自己寫？\n3. **怎麼顯示**：MapLibre / Leaflet（原生只支援 raster，要吃 vector 需外掛）/ deck.gl？\n\n大致上，「Web 地圖底圖」這個題目的自由度就落在這三件事上——當然細節還有很多，但抓住這三條主軸就不太會迷路。\n\n## 三個延伸場景\n\n**場景 A：你只是要在網站上放一張可拖拉的地圖**\n\n最簡單：用 [Leaflet](https://leafletjs.com/) + OSM raster tiles。10 行 code 搞定。\n\n**場景 B：你要做資料視覺化（choropleth、heatmap）**\n\n進階：MapLibre + vector tile 服務（OpenFreeMap 或 MapTiler）+ 自己加資料層。\n\n**場景 C：你要做完全離線、或客製化到底的地圖**\n\n最進階：自架 tile server，或者用 [PMTiles](/blog/pmtiles-http-range-request-single-file-tiles) 把 tile 打包成單檔。\n\nTaxMap-TW 我走的是場景 B：要在底圖上疊 7,747 個村里的所得 choropleth，又想要灰白底圖不搶戲、之後還能換深色模式，所以選了 MapLibre + OpenFreeMap 的 vector tile，自己加一層 GeoJSON 資料層。每個場景對 tile、style、顯示函式庫的選擇都不一樣，先想清楚自己在哪一格，後面的決定才不會亂套。\n\n## 收尾\n\n寫到這裡，前面的術語應該都能 mapping 回三個核心概念：\n\n- **z/x/y URL** = tile 在金字塔的座標\n- **PBF / MBTiles / PMTiles** = vector tile 不同的封裝格式\n- **Style URL** = 怎麼把 vector tile 變成你看到的地圖\n- **WebGL** = vector tile 需要的渲染技術\n\n老實說這三個概念我當初前後摸了快兩個晚上才串起來，但串起來之後再看任何一篇地圖技術文章，那些術語就各自歸位、不再嚇人了。如果要我給個偏好：大多數人其實不需要急著鑽 vector 的細節，先用場景 A 的 raster 把地圖跑起來、確定真的需要動態樣式了，再升級到 vector 也不遲。\n\n## 系列其他文章\n\n- → [PMTiles 取代傳統 tile server：HTTP Range Request 的單檔魔術](/blog/pmtiles-http-range-request-single-file-tiles)\n- → [OpenFreeMap vs MapTiler vs Mapbox：6 個 Web 地圖底圖服務怎麼選？](/blog/openfreemap-maptiler-base-map-comparison)\n- → [資料地圖該用哪種色階？viridis、YlGnBu 與 ColorBrewer 實戰指南](/blog/data-map-color-scale-viridis-ylgnbu)\n- → [打造 TaxMap-TW 完整心得：6 個技術決策、踩了 4 個坑](/blog/taxmap-tw-postmortem-6-decisions-4-pitfalls)", "summary": "Web 地圖底圖到底是什麼？這篇用最白話的方式把 vector tile vs raster tile、tile pyramid（z/x/y 金字塔）怎麼設計、style spec 為什麼存在一次講清楚，順便聊 raster 和 vector 各自適合的場景。讀完再回去看其他地圖技術文章會順非常多。", "image": "https://bobochen.dev/_astro/cover.ixw25Swj.webp", "date_published": "2026-05-27T00:00:00.000Z", "tags": [ "WebGIS", "地圖", "入門", "MapLibre", "OpenStreetMap" ] }, { "id": "https://bobochen.dev/blog/mosh-mobile-shell-intro/", "url": "https://bobochen.dev/blog/mosh-mobile-shell-intro/", "title": "Mosh 入門 — 把 SSH 帶到不穩網路上的 mobile shell", "content_text": "高鐵上、咖啡店、跨洲 SSH 一斷線就崩潰？Mosh 用 UDP + 本地回顯，讓 session 撐過 sleep、IP 切換、丟包，是行動辦公的標配工具。", "content_html": "## 背景\n\n你有沒有遇過這種情況：在高鐵上 `ssh` 到公司機器跑東西，過個山洞訊號掉一下，整個 session 就死了。回到位子上得重新連、重新進 tmux、重新 `cd` 回剛剛的目錄。\n\n或者更日常的：在咖啡店 Wi-Fi 連美西的 server，每按一個鍵都要等個半秒才看到字。寫個 `vim` 都覺得自己是在打電報。\n\n這兩件事的根源是同一個 — SSH 是建在 TCP 上的：\n\n1. **TCP 一斷就死** — IP 變了、封包丟太久、筆電 sleep，連線就不可挽回\n2. **每個按鍵都要等 RTT** — 終端機要等 server 回顯，你才看得到自己打了什麼\n\nMosh 就是為了解決這兩個問題而生的。\n\n## 什麼是 Mosh\n\n**Mosh = Mobile Shell**，2012 年從 MIT CSAIL 出來的研究專案。它的設計哲學很乾脆：\n\n> **SSH 負責登入認證，Mosh 接手互動 shell。**\n\n實際流程是：\n\n```\n1. mosh client 用 SSH 連到 server，照常做 key 認證\n2. server 啟動 mosh-server，回傳一個 UDP port + 共享金鑰\n3. SSH 結束，client 改用 UDP 跟 mosh-server 講話\n4. 後續所有按鍵、畫面更新都走加密 UDP\n```\n\n重點：**Mosh 不取代 SSH，是互動 shell 場景的延伸**。`scp`、`rsync`、port forwarding 那些事還是給 SSH 做。\n\n## 三個殺手級功能\n\n### 1. Local echo（本地回顯預測）\n\nMosh client 會「猜」你按的鍵會在螢幕上長什麼樣，有把握的就立刻顯示，沒把握的會加個底線等 server 確認。\n\nUSENIX 2012 論文的實測數字夠誇張：3G 環境下，**SSH 的按鍵中位延遲 503ms，Mosh < 5ms**。寫 vim、用 REPL、改 config 檔的體感差距是天和地。\n\n### 2. Roaming（IP 切換不斷線）\n\nMosh server 把「最新一個有效封包的來源 IP」當成你的位址。所以你從咖啡店 Wi-Fi 走出去切到 LTE、回辦公室再換成有線網路 — session 完全不會斷，連 reconnect 動作都不用做。\n\n對筆電帶著到處跑的人來說，這個功能等於再也不用煩惱「我等下要移動，先 disconnect 一下」。\n\n### 3. 持久連線（sleep / 斷網都撐得住）\n\n筆電闔上、進地下道、Wi-Fi 抖一下、咖啡店把你踢出網路 — Mosh 都不會把 session 砍掉。Client 端會在最上面顯示「多久沒收到 server 訊息」，網路一回來就自動接上。\n\n## 基本操作\n\n安裝（**client 和 server 兩邊都要裝**）：\n\n```bash\n# macOS\nbrew install mosh\n\n# Debian / Ubuntu\nsudo apt install mosh\n```\n\n第一次連線，用法跟 SSH 一模一樣：\n\n```bash\nmosh user@host\n# 也支援指定 ssh port、identity\nmosh --ssh=\"ssh -p 2222 -i ~/.ssh/work\" user@host\n```\n\n經典組合：搭配遠端 tmux，補上 Mosh 沒有 scrollback 的缺點：\n\n```bash\n# 連上去自動 attach 到 tmux session\nmosh user@host -- tmux a -t main\n```\n\n這套組合是行動辦公的黃金搭檔 — Mosh 撐連線、tmux 撐 session 與歷史。\n\n## 什麼時候該用 / 不該用\n\n| 情境 | 用 SSH | 用 Mosh |\n| --------------------------------- | --------------------- | ---------------------- |\n| 跨洲遠端 vim / tmux / REPL | 延遲爆炸 | 本地回顯瞬間反應 |\n| 筆電帶著到處跑、頻繁換網路 | 切網路就斷 | session 不死 |\n| 不穩 Wi-Fi、LTE hotspot 上開 shell | 一斷就重連 | 自動接回去 |\n| `scp` / `rsync` / port forwarding | ✓ | ✗（這些事還是用 SSH） |\n| 跳板機 / 沒裝 mosh-server 的雲端機 | ✓ | ✗（兩邊都要裝） |\n| 跑 `tail -f` 看完整 log | ✓ | △（會跳過中間畫面） |\n\n## 已知限制（坑）\n\n實際用之前要知道的事：\n\n1. **兩邊都要裝** `mosh-server` — 雲端機常缺、跳板機也常沒裝\n2. **UDP 60000–61000** — 預設用的 UDP port range，企業 firewall / cloud security group 常常擋掉，要記得開\n3. **沒有 scrollback** — Mosh 同步的是「目前可見的螢幕」，不是完整歷史。往上捲不回去 → 解法：遠端跑 tmux 或 screen\n4. **沒有 port forwarding / agent forwarding** — 這個是 issue #120 的長期未解。要 SSH 隧道、要 agent 轉發，乖乖回去用 SSH\n5. **不負責檔案傳輸** — `scp`、`sftp`、`rsync`、Git over SSH 都跟 Mosh 無關\n\n簡單記：**互動 shell 用 Mosh，其他通通用 SSH。**\n\n## 替代品與競品（2026 現況）\n\n過去幾年陸續有人想做「Mosh 的後繼者」，但截至 2026 年 5 月，沒有任何一個真正取代它。簡單盤點：\n\n| 工具 | 路線 | 2026 狀態 | 能取代 Mosh 嗎？ |\n| ----------------------------------- | ------------------------------------------ | ----------------------------------------------- | --------------------------------------------------------------------------- |\n| **trzsz/tssh + tsshd** | Go 寫的 OpenSSH 相容工具，UDP over QUIC / KCP | 最新 release 2026-05，**最活躍** | ◯ 補上 scrollback / port forwarding / agent forwarding，但**刻意不做 local echo** |\n| **Eternal Terminal (et)** | TCP-based session 持久化 + scrollback | v6.2.11（2024-07），bugfix commit 還在進 | △ 有 scrollback、有 reconnect，但 TCP-only，沒有 UDP roaming 體感 |\n| **Blink Shell** | iOS / iPadOS 終端機 app | 持續更新 | ✗ 它**內建 Mosh 協定**，是 Mosh 的最佳行動載體，不是替代品 |\n| **SSH3** | 學術派 QUIC-based SSH 重寫 | v0.1.7（2024-01），作者明說別上 production | ✗ 還在實驗階段 |\n| **Tailscale SSH / Cloudflare SSH** | 給 SSH 補上 zero-config 連線 | 都在活躍開發 | ✗ 解的是「怎麼連到 server」，不是「連上後體驗」 |\n| **QUICSSH、zmx 等 2026 新工具** | QUIC native 或 tmux 替代品 | 剛冒出來、community 還沒驗證 | △ 觀察名單 |\n\n**結論**：2026 年的局面是分工，不是取代。\n\n- 要 **local echo + 不穩網路上順手打字** → 還是 Mosh\n- 要 **scrollback + port forwarding + 現代 OpenSSH config 相容** → 看 **tssh + tsshd**\n- 要解決「**server 怎麼連得到**」這層 → 看 Tailscale / Cloudflare Access\n\n換句話說，Mosh 沒被取代不是因為它技術多神，是因為**沒人願意實作 local echo prediction**。這功能技術上不難，但對按鍵體感的影響太大，沒有它的工具就是「另一種 SSH 變種」。\n\n## 那實際上大家在用什麼？\n\n講完技術競品，回到現實 — **2026 年最主流的做法不是 Mosh，是無聊的 `ssh + tmux`**。\n\n| 層次 | 用法 | 為什麼主流 |\n| ---------------- | ------------------------------------- | -------------------------------------------------------------------------------- |\n| **真・最大宗** | `ssh user@host` + 遠端 `tmux a` | server 不用裝東西、所有雲端機都能用、防火牆不擋。會用 tmux 已經能撐 80% 場景。 |\n| **進階個人開發者** | Mosh + 遠端 tmux | 願意為「按鍵不延遲」+「IP 切換不斷線」付兩邊都要裝、UDP 要開洞的代價。 |\n| **現代團隊（爆發中）** | **Tailscale SSH** / Cloudflare Access | 不解 latency，解的是「怎麼連得到 + ACL 怎麼管」。近兩年新創幾乎全面換掉 VPN。 |\n\n所以實際的選擇大概是：\n\n- **問「個人怎麼連 server」** → 大部分人還是 `ssh + tmux`，少部分死忠用 Mosh\n- **問「團隊怎麼管遠端 access」** → Tailscale SSH 或 Cloudflare Access 已經是 2026 主流\n- **問「最強的技術方案」** → `tssh + tsshd`，但安裝成本和 SSH 一樣高、認知成本更高，主流採用還沒起來\n\nMosh 在這個光譜上是一個明確的「**進階個人選擇**」 — 它不會是團隊的標配，但會是某些開發者的隨身工具。\n\n## 反思\n\n### 技術面\n\nMosh 1.4.0 停在 2022 年 10 月，到現在三年多沒出新 stable release。但 GitHub master 還是有人在 commit，最近一筆是 2026 年 3 月。\n\n這不是 dead project，比較精準的描述是 **active but slow-moving** — 還活著，只是動得很慢。理由也很合理：Mosh 把「不穩網路上的互動 shell」這個窄題已經做完了，不太需要新功能。\n\n### 心態面\n\n我們常用 release 頻率來判斷一個開源專案的健康度，但 Mosh 提醒我們：**有些工具就是「做完了」**。把一個窄而清楚的問題解決到極致，就值得一直被用，不用每年硬擠新版本。\n\n但「做完了」也意味著風險 — 上面競品盤點裡可以看到，tssh + tsshd 已經把 Mosh 沒做到的事（scrollback、port forwarding）補齊。哪一天有人補上 local echo prediction，Mosh 就會被換掉。在那之前，它的地位來自一個有點諷刺的事實：**沒人想再寫一次按鍵預測**。\n\n### 有趣發現\n\niOS 上最知名的 mobile terminal — **Blink Shell** — 整個就是建在 Mosh 上的。一個 2012 年的 MIT 研究專案，撐起了 2026 年 iPad 上的開發者體驗。\n\n下次在高鐵上用 iPad 連回家裡 server 改 code，你用的其實還是這個十多年前的協定。", "summary": "高鐵上、咖啡店、跨洲 SSH 一斷線就崩潰？Mosh 用 UDP + 本地回顯，讓 session 撐過 sleep、IP 切換、丟包，是行動辦公的標配工具。", "image": "https://bobochen.dev/_astro/cover.OctpdivR.webp", "date_published": "2026-05-26T00:00:00.000Z", "tags": [ "Mosh", "SSH", "CLI", "開發工具", "遠端工作", "終端機" ] }, { "id": "https://bobochen.dev/blog/enterprise-ai-agent-llm-observability-eval/", "url": "https://bobochen.dev/blog/enterprise-ai-agent-llm-observability-eval/", "title": "生產級 LLM 可觀測性與評估：沒有 eval 的 agent，等於沒有測試的軟體", "content_text": "你改了一句 prompt、換了個模型，怎麼知道系統變好還是變壞？拆解 eval harness（黃金題庫、LLM-as-judge、回歸測試）、agent 的 tracing（每一步檢索/工具/模型的 span）、token 與成本監控，以及上線後怎麼偵測品質漂移。把後端的可觀測性硬功夫，搬到會講人話的元件上。", "content_html": "import DeckEmbed from '../../../components/blog/DeckEmbed.astro';\nexport const deckSlides = Object.entries(import.meta.glob('./slides/*.webp', { eager: true, import: 'default' })).sort(([a], [b]) => a.localeCompare(b)).map(([, m]) => m);\n\n> 這是「從 PoC 到 Production：企業 AI Agent 系統工程」系列第 9 篇（共 12 篇）。上一篇：[多代理協作](/blog/enterprise-ai-agent-multi-agent-orchestration)。\n\n這一篇是整個系列裡，我覺得最能分辨「玩過 agent」和「把 agent 當系統做過」的人的一篇。因為它要講的兩件事——eval 和 observability——在 demo 階段完全不存在，但它們正是讓系統可以被信任、被維運的東西。\n\n先把最重的一句話放這：\n\n> 一個沒有 eval 的 agent 專案，本質上就是**一套沒有測試的軟體**。只是因為它是 AI，大家就默許了這件事。\n\n## 為什麼 agent 的「測試」這麼難，但更不能省\n\n傳統軟體：輸入固定 → 輸出固定 → assert 相等 → 綠燈。\n\nAgent：輸入「請幫我總結這份報告」→ 輸出每次**用字都不一樣**，但可能都對；也可能字面很像、實際上錯了。你沒辦法用 `assertEqual` 測它。\n\n正因為輸出不確定，很多人就放棄測試，改用「我自己試幾題覺得還行」。但這正是災難的開始，因為：\n\n- 你換個模型版本（連 vendor 都可能 silent update），行為就漂移。\n- 你改一句 prompt 修好 A 問題，常常默默弄壞 B 問題。\n- 你調個檢索參數（第 3、4 篇），不知道整體變好還變壞。\n\n**越是不確定的系統，越需要有系統的方法去量它**，而不是越不確定就越靠感覺。\n\n## Eval Harness：給 agent 蓋一套測試\n\n### 1. 黃金題庫（golden set）\n準備一組「問題 + 期望答案 / 期望性質」的題目，涵蓋常見情境、邊界情境、和已知會出包的情境。每次你改任何東西（prompt、模型、檢索），**自動把整組題庫跑一遍**，看通過率。\n\n這就是 agent 版的回歸測試。它不需要很大才有用——**30 題涵蓋你最在乎的場景，就遠勝於零**。重點是它存在、而且每次改動都跑。出包過的 case 一定要補進題庫，確保同樣的錯不會再犯第二次。\n\n### 2. 怎麼判斷「答對」：三種尺\n輸出不固定，怎麼自動判分？由寬到嚴：\n\n- **規則 / 字串**：答案裡有沒有包含某關鍵事實、有沒有附來源、格式對不對。便宜、確定，但只能驗「硬性質」。\n- **語意比對**：用 embedding 比對答案和標準答案的語意相近度。能容忍用字不同。\n- **LLM-as-judge**：用另一個（通常更強的）模型，照你給的標準（正確性、完整性、有沒有幻覺）來評分。最有彈性，但「要小心偏誤」不是句口號——judge 有三個有名字、可被緩解的已知偏誤要主動防：**position bias**（偏好排前面的答案，緩解法是交換順序評兩次取一致）、**verbosity bias**（偏好較長的答案，即使長度沒帶來品質）、**self-preference bias**（偏袒自己或同家族模型的輸出——所以別拿同一個模型既當 judge 又當被評對象）。把這三個釘死，「要小心」才從感覺變成可勾的檢查清單，也才需要搭配規則與語意比對交叉驗證。\n\n實務上常常**三種混用**：硬性質用規則、整體品質用 LLM-as-judge。\n\n### 3. 別只測最終答案，要測中間步驟\n對會做事的 agent，光看最終輸出不夠。一個答案剛好對，不代表過程沒問題（可能檢索撈錯，但模型瞎猜對了）。所以 eval 也要看：**它檢索到的東西對不對、它選的工具對不對**。這需要下面的 tracing 撐著。\n\n這幾件事在業界都有正式名字，方便你搜：整條決策路徑對不對叫 **trajectory evaluation**（軌跡 / step-level evaluation）；檢索層有現成指標——**context precision / recall**（該撈的有沒有撈到、撈到的對不對）和 **faithfulness**（答案有沒有忠於檢索內容，也就是抓幻覺），RAGAS、Arize Phoenix 都內建；工具選對沒對則看 **tool-selection accuracy**。白話講對是第一步，知道學名你才搜得到工具去自動量它。\n\n## Tracing：把 agent 的黑盒打開\n\n第 1 篇的鴻溝三講過：agent 答錯，你常常什麼線索都沒有。Tracing 就是要把那條從問題到答案的完整路徑，變成一條可以攤開來看的紀錄。\n\n對 agent，一條 trace 應該記錄這些 span：\n\n![一條 agent trace：把一個請求拆成檢索、工具呼叫、模型推理、生成等可量測的 span，每一步的耗時、token、花費都看得到](./images/agent-trace.webp)\n\n

把一個 agent 請求拆成檢索、工具、模型、生成幾個可量測的 span——打開黑盒，每一步的耗時與花費都看得見。

\n\n有了這個，你 debug 的方式就從「再問一次看看」變成「攤開 trace，看是哪一個 span 出錯」。是檢索撈錯？工具回傳怪資料？還是模型拿到對的東西卻推理歪了？**根因一眼可見**。\n\n這套東西，做後端的人應該很熟——它就是 distributed tracing 套到 agent 上。我寫過用 tracing 去抓 PHP-FPM 記憶體洩漏、談過 fire-and-forget 服務的可觀測性陷阱，那套「每一步都要留下可追的足跡」的肌肉記憶，搬到 agent 上完全適用。差別只在 span 的內容從「DB query、HTTP call」變成「retrieval、tool call、model call」。**這正是後端工程師做 AI agent 的優勢**：可觀測性對你不是新觀念，只是新對象。\n\n而且這件事在 2024 後已經不只是「概念上像」了——它有了正式的開放標準。OpenTelemetry 的 GenAI SIG 從 2024 年起在制定 **GenAI Semantic Conventions**（CNCF 旗下），直接把「LLM / agent 的 span 該長什麼樣」標準化：模型呼叫叫 `chat` / `inference`、工具呼叫叫 `execute_tool`、agent 層級叫 `invoke_agent`，屬性有 `gen_ai.request.model`、`gen_ai.usage.input_tokens`、`gen_ai.tool.name` 這些。意思是上面那張 trace 圖不是各家自己亂畫的，而是一套有共識的 schema。一個誠實的提醒：截至 2026 它仍是 **experimental 狀態**，屬性名還可能變，採用時要留意版本相容。\n\n## 成本與 Token 監控：因為它會悄悄燒錢\n\nLLM 系統有個傳統服務沒有的特性：**每一次呼叫的成本是浮動的**，取決於 token 量。一個沒人注意的功能，可能因為 context 越塞越大、或一個 multi-agent 迴圈（第 8 篇）失控，悄悄把帳單翻倍。\n\n所以要把「成本」當成一級 metric 來監控：\n\n- 每個**功能 / endpoint** 平均花多少 token、多少錢？\n- 每個**使用者 / 租戶**燒多少？（抓異常、做計費）\n- 有沒有哪個 trace **異常昂貴**（爆 token）？要能告警。\n\n這直接餵給第 10 篇的成本權衡——你不先把成本看見，就無從優化。\n\n## 上線後：偵測「品質漂移」\n\n最後一層，是上線後的持續監控。你的黃金題庫是固定的，但真實世界的問題會變、資料會變、模型會被 vendor 偷偷更新。所以要盯著**線上的健康訊號**：\n\n- **代理指標**：使用者重問率、轉人工率、負評率、「這個答案沒幫助」的比例——這些不需要標準答案，就能反映品質掉了。\n- **定期回歸**：固定排程重跑黃金題庫，模型供應商一更新就可能漂移，你要第一個知道，而不是等客訴。\n- **抽樣人工複查**：定期抽真實對話人工看，補進黃金題庫。\n\n## 工具地景（會變，但方向很清楚）\n\n你可能會問：實際上用什麼做？我刻意不把這篇綁死在某個工具上（它們明天就可能改名），但給你一個 2026 的版圖方便開始搜：開源自架有 Langfuse、Arize Phoenix、Opik；商業 SaaS 有 LangSmith、Braintrust；既有 APM 則有 Datadog、New Relic 的 LLM Observability。但比「選哪個」更重要的是一個正在發生的收斂——這些工具都在往 **OpenTelemetry GenAI conventions** 靠。所以選型第一個該問的不是「dashboard 漂不漂亮」，而是「它能不能吐標準的 OTel span」——能，你換工具時 trace 還搬得走，不會被單一廠商鎖死。\n\n## 小結\n\n把 agent 從 demo 變成可信任的 production 系統，這篇是關鍵的一道工序：\n\n1. **Eval harness**：黃金題庫 + 混合評分（規則 / 語意 / LLM-as-judge），每次改動都跑回歸，出包的 case 一定補進去。\n2. **Tracing**：把每一步（檢索 / 工具 / 模型）變成可攤開的 span，debug 從許願變成看圖。\n3. **成本監控**：把 token 與花費當一級 metric，別讓它悄悄燒。\n4. **漂移偵測**：用線上代理指標 + 定期回歸，在客訴之前發現品質掉了。\n\n這四件事沒有一件是 AI 獨有的玄學——它們就是把後端的測試與可觀測性硬功夫，搬到一個會講人話的元件上。下一篇我們把這些 metric 派上用場，正面處理那個一直在背景的三角習題：**延遲、可靠性、成本，怎麼權衡**。\n\n\n## 文章簡報\n\n\n\n---\n\n### 延伸閱讀\n\n- 上一篇：[多代理協作](/blog/enterprise-ai-agent-multi-agent-orchestration)\n- [Agentic Engineering：測試與安全](/blog/agentic-engineering-testing-safety)——把測試與安全紀律套用在 agent 上的另一個視角\n- 下一篇：《延遲、可靠性、成本的系統權衡》", "summary": "你改了一句 prompt、換了個模型，怎麼知道系統變好還是變壞？拆解 eval harness（黃金題庫、LLM-as-judge、回歸測試）、agent 的 tracing（每一步檢索/工具/模型的 span）、token 與成本監控，以及上線後怎麼偵測品質漂移。把後端的可觀測性硬功夫，搬到會講人話的元件上。", "image": "https://bobochen.dev/_astro/cover.BkqzDgEv.webp", "date_published": "2026-05-23T00:00:00.000Z", "date_modified": "2026-06-05T00:00:00.000Z", "tags": [ "LLMOps", "可觀測性", "Eval", "監控", "生產環境" ] }, { "id": "https://bobochen.dev/blog/agentic-engineering-cost-optimization/", "url": "https://bobochen.dev/blog/agentic-engineering-cost-optimization/", "title": "Token 經濟學進階：當 Agent 一天燒掉 $50，你怎麼控制成本", "content_text": "Agent 越強大，token 燒越快。深入 token 成本的結構分析——哪些任務是 token 黑洞、怎麼設計 context 降低消耗、caching 策略、model routing，以及月成本從 $287 降到 $148 的實際做法。", "content_html": "> 這是「Agentic Engineering 實戰手冊」系列的第十一篇。上一篇：[Multi-Agent 編排實戰](/blog/multi-agent-orchestration-real-world)\n\n## 上個月帳單 $287，這個月 $148\n\n上個月我的 AI coding 總帳單是 $287。嚇了一跳。\n\n不是用太多，工作量其實差不多，問題出在使用方式：超長的 session 導致 context window 持續膨脹、探索性的 codebase 搜尋吃掉大量 token、該用便宜 model 的地方用了貴的。\n\n花了一個週末分析之後，這個月在相同工作量下壓到了 $148。差距來自三個改變：context pruning、model routing，還有更有紀律的 session management。\n\n重點不是「少用」，是「聰明用」。如果你也有 token 燒光的焦慮，這篇從工程面給你具體的解法。\n\n## Token 成本解剖學\n\n要省錢，先搞懂錢花在哪。\n\n### 三種 Token，三種價格\n\n| Token 類型 | 什麼時候產生 | 你能控制嗎 |\n| ------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |\n| **Input tokens** | 你給 model 的一切：system prompt、CLAUDE.md、conversation history、code context | 是——[context engineering](/blog/context-engineering-deep-dive) 直接影響 |\n| **Output tokens** | Model 回給你的一切：code、解釋、tool calls | 部分——精準的 spec 讓 agent 少寫廢話 |\n| **Thinking tokens** | 模型推理時的內部 token（extended thinking） | 部分——簡單任務關閉 extended thinking |\n\n真正隱藏的成本殺手是 **input tokens**。\n\n大部分人以為成本主要來自 output（agent 寫的 code），其實不是。在一個典型的 agentic session 裡，input tokens 通常是 output 的 **3-5 倍**。因為每一輪對話，整個 conversation history + system prompt + context 都會被重新送一次。\n\n一個 session 跑了 50 輪對話，最後幾輪每次都要送入幾十萬 token 的 history——光是這些重複的 input 就占了帳單的大頭。\n\n### 一次「幫我修這個 bug」的 Token 分解\n\n一個看似簡單的 bug fix request：\n\n```\nSystem prompt + CLAUDE.md: ~5,000 tokens\nConversation history (20 輪): ~40,000 tokens\nAgent 讀的 code files: ~15,000 tokens\nAgent 的 tool calls: ~8,000 tokens\nAgent 的 output (code + 說明): ~3,000 tokens\nExtended thinking: ~5,000 tokens\n─────────────────────────────────────────────\nTotal: ~76,000 tokens\n```\n\nAgent 最後寫出來的 code（3,000 tokens）只佔總消耗的 4%，而 conversation history（40,000 tokens）佔了 53%。最大的省錢機會不在「少寫 code」，在「管理 conversation history」。\n\n## 每種任務的成本對照\n\n根據我三個月的追蹤數據（approximation based on usage patterns）：\n\n| 任務類型 | 平均 Token 消耗 | 大約成本 | 備註 |\n| -------------------- | --------------- | ---------- | ------------------ |\n| Simple bug fix | 50K-100K | $0.20-0.50 | 通常 1-3 輪對話 |\n| New feature (small) | 150K-300K | $0.50-1.50 | 5-10 輪，含 review |\n| New feature (medium) | 500K-1M | $2-5 | 多輪 iteration |\n| Refactor | 800K-2M | $3-10 | 大量 codebase 探索 |\n| Code review | 100K-200K | $0.30-1.00 | 讀多寫少 |\n| Codebase exploration | 300K-800K | $1-4 | Token 黑洞 |\n| Documentation | 200K-400K | $0.50-2.00 | Output-heavy |\n\n**Token 黑洞排行**：\n\n1. **Refactor**——agent 需要讀很多檔案，理解整體架構，然後做大量修改\n2. **Codebase exploration**——「幫我搞懂這個系統怎麼運作」類型的任務，agent 會讀幾十個檔案\n3. **Long debugging sessions**——一來一回的 debug loop，conversation history 指數增長\n\n## 優化策略一：Context Pruning\n\n回到 [Context Engineering](/blog/context-engineering-deep-dive) 的核心觀念：context 不是越多越好，剛好夠就行。\n\n### 精簡 CLAUDE.md\n\n每多一行 CLAUDE.md，就多花幾個 token 在每一輪對話裡。乘以 session 裡的對話輪數，成本累積驚人。\n\n**Before**：400 行的 CLAUDE.md，每輪 ~4000 tokens × 30 輪 = 120,000 tokens 浪費在重複載入上\n\n**After**：100 行的 CLAUDE.md，每輪 ~1000 tokens × 30 輪 = 30,000 tokens\n\n光這一項就省了 90K tokens（約 $0.30/session）。看起來不多，但每天做 10 個 session，一個月就是 $90。\n\n### Session 管理紀律\n\n黃金法則就一句：一個 session 做一件事。\n\n一個 session 跑太久，conversation history 會指數膨脹。第 50 輪的對話要送入前面 49 輪的 history，那可能是 200K+ 的 input tokens。\n\n**改善做法**：\n\n- 一個 task 一個 session。task 做完就關，開新 session 做下一個。\n- 如果 task 需要多輪 iteration，中途做 checkpoint（更新 plan/TODO），然後開新 session 繼續。\n- 利用 Claude Code 的 context compaction，當 context 太大時它會自動壓縮舊的對話。但與其依賴自動壓縮，不如主動控制 session 長度。\n\n### Sub-Agent 模式\n\n探索性的任務（「幫我搞懂這個模組的架構」）特別燒 token。解法是用 sub-agent：\n\n```\n主 agent: 「研究 auth 模組的架構」\n → 派出 sub-agent（cheap model、獨立 context）\n → sub-agent 讀 20 個檔案，消耗 200K tokens\n → 回報 2000 token 的摘要給主 agent\n```\n\n主 agent 的 context 只增加了 2000 tokens，而不是 200K。\n\n## 優化策略二：Model Routing\n\n不是所有任務都需要最貴的模型。\n\n### 我的 Model 選擇框架\n\n| 任務類型 | 推薦 Model | 原因 |\n| -------------------- | ------------------- | ------------------------- |\n| 簡單問答、分類 | Haiku | 快、便宜、準確度足夠 |\n| 日常 coding、bug fix | Sonnet | 性價比最高 |\n| 複雜架構決策 | Opus | 需要深度推理 |\n| Code review | Sonnet | 理解力夠、比 Opus 快 |\n| Commit message | Sonnet/Haiku | 不需要 Opus 的推理能力 |\n| 長篇寫作 | Opus | 需要一致性和深度 |\n| Codebase exploration | Sonnet + sub-agents | 用便宜的 model 做大量探索 |\n\n### 實際省下多少？\n\n以一天的典型工作量為例：\n\n**Before（全部用 Opus）**：\n\n- 10 個 tasks × 平均 300K tokens × Opus 價格 ≈ $15/天\n\n**After（model routing）**：\n\n- 2 個 complex tasks → Opus：600K tokens ≈ $4\n- 6 個 standard tasks → Sonnet：1.2M tokens ≈ $4\n- 2 個 simple tasks → Haiku：200K tokens ≈ $0.10\n- **Total ≈ $8/天**\n\n同樣的工作量，成本掉了 47%，品質幾乎沒差。Sonnet 在日常 coding 任務上的表現跟 Opus 非常接近。\n\n### 怎麼切換\n\n在 Claude Code 裡，隨時可以用 `/model sonnet` 或 `/model opus` 切換。我的 [`commit` skill](/blog/claude-md-rules-files-masterclass) 裡就有提醒：做 git commit 用 Sonnet 就好，不需要 Opus。\n\n## 優化策略三：Prompt Caching & Batching\n\n### Prompt Caching\n\nAnthropic 的 prompt caching 機制讓相同的 system prompt 只需要在第一次完整傳送，後續的 request 可以使用 cache，大幅降低 input token 成本。\n\n**怎麼提高 cache hit rate**：\n\n- CLAUDE.md 保持穩定——頻繁修改 CLAUDE.md 會導致 cache miss\n- System prompt 放在 context 的最前面（cache 是 prefix-based 的）\n- 避免在 system-level context 裡放動態內容（timestamp、random ID 等）\n\n### Batching 策略\n\n把相似的小任務合成一個 request：\n\n**Before**（5 個獨立 request）：\n\n```\n1. \"修正 Button component 的 hover color\"\n2. \"修正 Card component 的 border radius\"\n3. \"修正 Input component 的 focus style\"\n4. \"修正 Modal component 的 backdrop color\"\n5. \"修正 Toast component 的 animation\"\n```\n\n5 次 system prompt 載入 + 5 次 CLAUDE.md 載入 = 大量重複的 input tokens。\n\n**After**（1 個 batch request）：\n\n```\n修正以下 5 個 component 的 CSS 問題：\n1. Button: hover color\n2. Card: border radius\n3. Input: focus style\n4. Modal: backdrop color\n5. Toast: animation\n```\n\n1 次 system prompt 載入 + 1 次 CLAUDE.md 載入。Token 節省 ~60%。\n\n## 月度預算框架\n\nAgentic engineering 合理的月成本是多少？取決於你的使用強度：\n\n| 使用級別 | 月成本 | 誰適合 |\n| ---------------------- | ---------------------- | ------------------------ |\n| **Light** ($20-50) | Pro 訂閱 + 少量 API | 兼職使用、學習階段 |\n| **Medium** ($50-150) | Pro + 日常 API 使用 | 全職 agent-first 開發 |\n| **Heavy** ($150-300) | 大量 API + multi-agent | 多專案、multi-agent 架構 |\n| **Enterprise** ($300+) | Team 帳號 + 自建工具 | 團隊級別使用 |\n\n### ROI 計算\n\n$150/月的 agent 成本值不值得？算一下：\n\n假設 agentic workflow 讓你每天省 2 小時（保守估計，根據 [Post 7](/blog/agentic-engineering-daily-workflow-advanced) 的 4x 效率提升）。\n\n- 一個月工作 22 天 × 2 小時 = 44 小時\n- 以台灣軟體工程師平均時薪 $25 USD 計算：44 × $25 = $1,100\n- ROI：$1,100 / $150 = **7.3x**\n\n即使你用最貴的 Opus model 跑所有事情，只要它讓你省下的時間值超過 $300/月，就是值得的。\n\n大部分 agent-first 工程師的 sweet spot 在 **$100-200/月**。這個範圍可以覆蓋每天 8-10 小時的 agent-first 工作方式，如果你做好 model routing 和 context management。\n\n## 我具體做了什麼把帳單從 $287 降到 $148\n\n1. **Session 拆分**：從平均 45 分鐘/session 降到 20 分鐘/session。對話輪數從 30 降到 12。\n2. **Model routing**：70% 任務改用 Sonnet（之前 90% 用 Opus）。\n3. **Sub-agent 探索**：codebase exploration 任務全部丟給 sub-agent，主 context 不膨脹。\n4. **CLAUDE.md 瘦身**：從 400 行精簡到 100 行。任務特定的指令移到 rules files 和 skills。\n5. **Batch 處理**：小任務合併。一天 15 個 request 降到 8 個。\n\n每一項單獨看都不是巨大的改變。但加在一起，就是 48% 的成本降低。\n\n## Takeaway\n\n1. Token 成本的最大殺手是不必要的 context 膨脹，不是使用量。Conversation history 佔了帳單的一半以上。控制 session 長度、精簡 CLAUDE.md、善用 sub-agent，這三招就能省 30-40%。\n\n2. Model routing 可以在不犧牲品質的前提下省 40-50% 成本。日常 coding 用 Sonnet，只有複雜架構決策才需要 Opus。Commit、simple Q&A 用 Haiku 就夠了。\n\n3. $100-200/月是大部分 agent-first 工程師的 sweet spot。這個成本對應的 ROI 通常在 5-10x。不要為了省 $50 犧牲工作流的效率，但也不要因為「反正有用」就不管成本地亂燒。\n\n---\n\n_上一篇：[Multi-Agent 編排實戰](/blog/multi-agent-orchestration-real-world)_\n_下一篇：[Agent 安全網設計](/blog/agentic-engineering-testing-safety)_", "summary": "Agent 越強大，token 燒越快。深入 token 成本的結構分析——哪些任務是 token 黑洞、怎麼設計 context 降低消耗、caching 策略、model routing，以及月成本從 $287 降到 $148 的實際做法。", "image": "https://bobochen.dev/_astro/cover.DILkHkDU.webp", "date_published": "2026-05-22T00:00:00.000Z", "tags": [ "Agentic Engineering", "Token", "成本優化", "AI", "Model Routing" ] }, { "id": "https://bobochen.dev/blog/claude-api-guide-cost-optimization/", "url": "https://bobochen.dev/blog/claude-api-guide-cost-optimization/", "title": "成本控制：省錢是一門工程藝術", "content_text": "從 Token 成本全貌、模型選擇策略、Prompt Caching 到 Batch API，系統性地把 AI 應用的成本降下來。一個真實 RAG 系統從每月 $2000 降到 $300 的完整過程。", "content_html": "我曾經有一個月收到 $2,341 的 Anthropic 帳單。\n\n那個時候，我在做一個內部知識庫的 RAG 系統，大概有三十幾個人在用。$2,341 除以 35 人，每個人每個月大概 $67——這個成本在企業環境裡看起來還好，但我的老闆覺得太貴了。\n\n他說：「這個系統有沒有辦法變成 $500 以內？」\n\n我花了兩週，把費用降到了 $287。這一章我要告訴你我是怎麼做到的。\n\n## 為什麼成本優化是 AI 應用的核心工程問題\n\n很多開發者把成本優化當成「後期才需要考慮的事」。這是個錯誤。\n\nAI 應用的成本結構跟傳統軟體完全不同。傳統 SaaS 的邊際成本接近零——多一個用戶，你的 AWS 帳單大概增加幾塊錢。但 AI 應用的邊際成本是**線性的甚至是超線性的**：用戶量增加一倍，API 費用大概也增加一倍；如果你的系統設計讓每次查詢消耗更多 token（例如累積越來越長的對話歷史），費用增長甚至會超過用戶量增長。\n\n成本不只影響利潤，還影響**產品設計決策**。當你知道每次 API 呼叫的成本，你會更謹慎地設計什麼時候要呼叫 API、呼叫什麼等級的模型、要不要快取。不理解成本的工程師，容易設計出用起來爽但賣不起錢的系統。\n\n## Token 成本的全貌\n\n很多人只知道「輸入 token 比輸出 token 便宜」，但 Anthropic 的計費實際上有四個維度：\n\n**Input Tokens（輸入 token）**：你傳給模型的所有文字——system prompt、用戶訊息、工具結果、對話歷史。這是最大宗的費用來源。\n\n以 claude-3-5-sonnet-20241022 為例，定價是 $3 / 1M tokens（2026 年初的定價，請以 Anthropic 官方定價頁面為準）。\n\n**Output Tokens（輸出 token）**：模型生成的文字——回覆內容、思考鏈（如果啟用）、工具呼叫參數。輸出 token 比輸入貴，Sonnet 是 $15 / 1M tokens——整整貴了五倍。這意味著讓模型少說一點話，比讓你少說一點話更有效益。\n\n**Cache Read Tokens（快取讀取 token）**：Prompt Caching 命中時，快取部分的 token 計費為 $0.30 / 1M——只有標準輸入的十分之一。快取是成本優化最強力的武器。\n\n**Cache Write Tokens（快取寫入 token）**：建立快取時，需要支付 $3.75 / 1M（比標準輸入稍貴）。但只要快取被讀取 1 次，就已大幅回本（寫入多付的 $0.75，對比讀取省下的 $2.70）。\n\n另外還有 **Tool Use** 的 token——工具的描述（`tools` 參數中的 JSON）也算 input tokens。如果你有很多工具，工具描述本身就可能佔用 1000-3000 tokens，每次呼叫都在計費。\n\n用這個表格來做成本估算：\n\n| 類型 | claude-3-5-haiku | claude-3-5-sonnet | claude-opus-4 |\n| ----------- | ---------------- | ----------------- | ------------- |\n| Input | $0.80/1M | $3/1M | $15/1M |\n| Output | $4/1M | $15/1M | $75/1M |\n| Cache Read | $0.08/1M | $0.30/1M | $1.50/1M |\n| Cache Write | $1/1M | $3.75/1M | $18.75/1M |\n\n（以上為撰寫時的定價，請參考官方 [pricing 頁面](https://www.anthropic.com/pricing)）\n\n## 模型選擇策略：用最便宜能完成任務的模型\n\n這是最直接的成本優化策略，也最容易被忽視。\n\n我見過很多系統，不管什麼任務都用 Sonnet——分類一個客服問題？Sonnet。判斷情感是正面還是負面？Sonnet。把一段文字翻譯成英文？Sonnet。\n\nHaiku 的定價是 Sonnet 的 1/4 左右。如果你用 Haiku 能做的事，就不要用 Sonnet。\n\n我的模型選擇框架：\n\n**用 Haiku（最便宜）的場景：**\n\n- 分類任務（這封信是垃圾郵件嗎？這個問題屬於哪個類別？）\n- 簡單的資料提取（從文字中提取名字、日期、金額）\n- 格式轉換（把 JSON 轉成 CSV）\n- 快速的是/否判斷\n\n**用 Sonnet（中等）的場景：**\n\n- 一般的對話和問答\n- 中等複雜的程式碼生成\n- 文件摘要\n- 大多數的 RAG 應用\n\n**用 Opus（最貴）的場景：**\n\n- 複雜的多步驟推理\n- 需要深度分析的長文件\n- 高風險的決策（法律文件分析、財務建議）\n- 你需要最高品質且預算不是問題\n\n在實際應用中，我推薦**分層模型策略（Model Routing）**：\n\n```python\nimport anthropic\n\nclient = anthropic.Anthropic()\n\ndef classify_query(user_message: str) -> str:\n \"\"\"用 Haiku 分類查詢的複雜度，決定用什麼模型回答\"\"\"\n response = client.messages.create(\n model=\"claude-3-5-haiku-20241022\", # 用 Haiku 做分類\n max_tokens=10,\n messages=[{\"role\": \"user\", \"content\": f\"\"\"\n判斷以下查詢的複雜度：\n\"{user_message}\"\n\n只回答 \"simple\"、\"medium\" 或 \"complex\"：\n- simple：直接的事實查詢、簡單的是/否問題\n- medium：需要一些推理、綜合多個資訊\n- complex：需要深度分析、多步驟推理、高風險決策\n\"\"\"}]\n )\n return response.content[0].text.strip().lower()\n\ndef route_and_answer(user_message: str, context: str) -> str:\n \"\"\"根據查詢複雜度選擇適當的模型\"\"\"\n complexity = classify_query(user_message)\n\n model_map = {\n \"simple\": \"claude-3-5-haiku-20241022\",\n \"medium\": \"claude-3-5-sonnet-20241022\",\n \"complex\": \"claude-opus-4-5\",\n }\n\n model = model_map.get(complexity, \"claude-3-5-sonnet-20241022\")\n print(f\"使用模型: {model} (複雜度: {complexity})\")\n\n response = client.messages.create(\n model=model,\n max_tokens=1024,\n messages=[\n {\"role\": \"user\", \"content\": f\"Context: {context}\\n\\nQuestion: {user_message}\"}\n ]\n )\n\n return response.content[0].text\n```\n\n這個策略讓你的系統自動把簡單問題路由到便宜的模型，複雜問題才用昂貴的模型。根據我的經驗，80% 的查詢屬於 simple 或 medium，只有 20% 需要 Sonnet 等級。光是這個策略就能把成本降低 40-60%。\n\n## Prompt Caching：最強力的成本武器\n\nPrompt Caching 是 Anthropic 在 2024 年推出的功能，我認為它是迄今為止最重要的成本優化工具。\n\n核心概念：如果你的 prompt 有一部分是固定的（system prompt、背景文件、工具描述），Anthropic 可以把這部分快取起來。下次請求如果包含相同的前綴，直接讀快取，費用只有標準輸入的十分之一。\n\n**快取的觸發條件：**\n\n- 前綴必須超過 1024 tokens（小於這個值不值得快取）\n- 使用 `cache_control: {\"type\": \"ephemeral\"}` 標記快取斷點\n- 快取有效時間：5 分鐘（5 分鐘沒有相同前綴的請求就過期）\n\n```python\nimport anthropic\n\nclient = anthropic.Anthropic()\n\n# 假設這是你的知識庫文件（幾千 tokens）\nknowledge_base = \"\"\"\n[你的公司知識庫內容，可能有 10,000+ tokens...]\n這裡是關於產品的說明...\n這裡是常見問題解答...\n這裡是退款政策...\n[更多內容...]\n\"\"\"\n\ndef answer_with_caching(user_question: str) -> anthropic.Message:\n \"\"\"使用 Prompt Caching 的 RAG 系統\"\"\"\n return client.messages.create(\n model=\"claude-3-5-sonnet-20241022\",\n max_tokens=1024,\n system=[\n {\n \"type\": \"text\",\n \"text\": \"你是公司的客服 AI 助手。請根據以下知識庫內容回答用戶問題。\"\n },\n {\n \"type\": \"text\",\n \"text\": knowledge_base,\n \"cache_control\": {\"type\": \"ephemeral\"} # 標記這裡是快取斷點\n }\n ],\n messages=[\n {\"role\": \"user\", \"content\": user_question}\n ]\n )\n\n# 第一次請求：需要寫入快取（稍貴）\nresponse1 = answer_with_caching(\"退款政策是什麼？\")\nusage1 = response1.usage\nprint(f\"Cache creation: {usage1.cache_creation_input_tokens} tokens\")\nprint(f\"Cache read: {usage1.cache_read_input_tokens} tokens\") # 第一次：0\n\n# 第二次請求（5 分鐘內）：命中快取\nresponse2 = answer_with_caching(\"如何申請退貨？\")\nusage2 = response2.usage\nprint(f\"Cache read: {usage2.cache_read_input_tokens} tokens\") # 第二次：命中快取！\n# 知識庫的 tokens 現在按 $0.30/1M 計費，而不是 $3/1M\n```\n\n**如何最大化快取命中率：**\n\n1. **把穩定的內容放在前面，動態的內容放在後面。** 快取是前綴匹配——只要前面相同，後面不同也算命中。\n\n2. **快取斷點要謹慎放置。** 如果你有多個可快取的段落，每個段落都加 `cache_control`，但注意每個斷點都需要前面的整個前綴完全匹配。\n\n3. **對話歷史的快取策略。** 在長對話中，把累積的對話歷史也標記為快取：\n\n```python\ndef chat_with_caching(\n messages: list[dict],\n new_user_message: str,\n system_prompt: str,\n knowledge_base: str\n) -> str:\n \"\"\"長對話中的快取策略\"\"\"\n\n # 建立新的訊息列表\n all_messages = messages.copy()\n\n # 對最後一條 assistant 訊息加快取標記（代表到目前為止的對話歷史）\n if all_messages and all_messages[-1][\"role\"] == \"assistant\":\n last_msg = all_messages[-1].copy()\n if isinstance(last_msg[\"content\"], str):\n last_msg[\"content\"] = [\n {\n \"type\": \"text\",\n \"text\": last_msg[\"content\"],\n \"cache_control\": {\"type\": \"ephemeral\"}\n }\n ]\n all_messages[-1] = last_msg\n\n # 加入新的用戶訊息\n all_messages.append({\"role\": \"user\", \"content\": new_user_message})\n\n response = client.messages.create(\n model=\"claude-3-5-sonnet-20241022\",\n max_tokens=1024,\n system=[\n {\"type\": \"text\", \"text\": system_prompt},\n {\n \"type\": \"text\",\n \"text\": knowledge_base,\n \"cache_control\": {\"type\": \"ephemeral\"}\n }\n ],\n messages=all_messages\n )\n\n return response.content[0].text\n```\n\n我的目標是讓 cache hit rate 超過 80%——也就是說，80% 以上的請求中，大部分 input tokens 都來自快取。這個數字對一個活躍的服務（每分鐘有多個請求）是可達到的。\n\n## Output Length 控制\n\n輸出 token 比輸入貴 5 倍，控制輸出長度是重要的成本槓桿。\n\n**設定合理的 max_tokens。** 很多開發者直接設 4096 或更高，但如果你的用例只需要幾百 token 的回覆，這樣做不只浪費（模型可能輸出比需要多的內容），也讓用戶等待更長時間。\n\n根據用例設定 max_tokens：\n\n- 客服問答：512-1024\n- 文件摘要：1024-2048\n- 長文章生成：2048-4096\n- 程式碼生成：視複雜度而定\n\n**在 prompt 中明確要求簡潔：**\n\n```python\nsystem_prompt = \"\"\"\n你是客服助手。回答用戶問題時：\n- 直接給出答案，不要有前言和後記\n- 使用條列式格式\n- 回答控制在 200 字以內\n- 如果問題複雜，告訴用戶可以進一步詢問，而不是一次說完所有內容\n\"\"\"\n```\n\n一個設計良好的 prompt，讓模型知道「夠了就停」，不要追求詳細。對多數用戶來說，精簡的回覆其實比詳細的回覆更好——AI 的「詳細」往往包含大量廢話。\n\n## Batch API：節省 50% 的懶人救星\n\n如果你的任務不需要即時回應（例如批次處理文件、離線分析），用 Batch API 可以省下 50% 的費用。\n\nBatch API 的工作方式：你一次送出多個請求，Anthropic 在 24 小時內處理完，費用是標準 API 的一半。\n\n```python\nimport anthropic\nimport json\n\nclient = anthropic.Anthropic()\n\n# 準備批次請求\nrequests = []\ndocuments = [\"文件 1 的內容...\", \"文件 2 的內容...\", \"文件 3 的內容...\"]\n\nfor i, doc in enumerate(documents):\n requests.append({\n \"custom_id\": f\"doc-{i}\",\n \"params\": {\n \"model\": \"claude-3-5-sonnet-20241022\",\n \"max_tokens\": 512,\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": f\"請摘要以下文件（100 字以內）：\\n\\n{doc}\"\n }\n ]\n }\n })\n\n# 送出批次請求\nbatch = client.messages.batches.create(requests=requests)\nprint(f\"Batch ID: {batch.id}\")\nprint(f\"狀態: {batch.processing_status}\")\n\n# 等待完成（可以隔幾個小時再查）\nimport time\nwhile True:\n batch_status = client.messages.batches.retrieve(batch.id)\n if batch_status.processing_status == \"ended\":\n break\n print(f\"還在處理中... ({batch_status.request_counts.processing} 個請求)\")\n time.sleep(60)\n\n# 取得結果\nfor result in client.messages.batches.results(batch.id):\n if result.result.type == \"succeeded\":\n print(f\"{result.custom_id}: {result.result.message.content[0].text}\")\n else:\n print(f\"{result.custom_id}: 失敗 - {result.result.error}\")\n```\n\n適合 Batch API 的場景：\n\n- 每晚批次生成隔天的報告\n- 離線的文件分類和標記\n- 測試時跑大量的 evaluation\n- 定期更新快取的知識庫摘要\n\n## Context Window 管理：不要無限累積對話歷史\n\n這是很多對話 AI 應用的常見問題：每輪對話都把完整的歷史塞進去，越說越長，費用越來越高。\n\n正確的做法是**有策略地管理對話歷史**：\n\n```python\nfrom anthropic import Anthropic\n\nclient = Anthropic()\n\nclass ConversationManager:\n def __init__(self, max_history_tokens: int = 4000):\n self.messages = []\n self.max_history_tokens = max_history_tokens\n\n def estimate_tokens(self, messages: list) -> int:\n \"\"\"粗略估算 token 數（1 token ≈ 4 個英文字元 / 2 個中文字元）\"\"\"\n total_chars = sum(\n len(m[\"content\"]) if isinstance(m[\"content\"], str)\n else sum(len(c.get(\"text\", \"\")) for c in m[\"content\"])\n for m in messages\n )\n return total_chars // 3 # 保守估算\n\n def trim_history(self):\n \"\"\"保留最近的對話，確保不超過 token 限制\"\"\"\n while len(self.messages) > 2 and self.estimate_tokens(self.messages) > self.max_history_tokens:\n # 移除最早的一組對話（user + assistant）\n self.messages = self.messages[2:]\n\n def chat(self, user_message: str, system_prompt: str) -> str:\n self.messages.append({\"role\": \"user\", \"content\": user_message})\n self.trim_history()\n\n response = client.messages.create(\n model=\"claude-3-5-sonnet-20241022\",\n max_tokens=1024,\n system=system_prompt,\n messages=self.messages\n )\n\n assistant_message = response.content[0].text\n self.messages.append({\"role\": \"assistant\", \"content\": assistant_message})\n\n return assistant_message\n\n def summarize_and_reset(self, system_prompt: str):\n \"\"\"當對話太長，先讓 AI 做摘要，然後重置歷史\"\"\"\n if len(self.messages) < 4:\n return\n\n # 用 Haiku 做對話摘要（便宜）\n summary_response = client.messages.create(\n model=\"claude-3-5-haiku-20241022\",\n max_tokens=512,\n messages=[\n {\n \"role\": \"user\",\n \"content\": f\"請用 200 字摘要以下對話的重點：\\n\\n{json.dumps(self.messages, ensure_ascii=False)}\"\n }\n ]\n )\n\n summary = summary_response.content[0].text\n\n # 重置歷史，只保留摘要\n self.messages = [\n {\n \"role\": \"user\",\n \"content\": f\"[對話摘要：{summary}]\\n\\n繼續我們的對話。\"\n },\n {\n \"role\": \"assistant\",\n \"content\": \"好的，我了解之前的對話內容。請繼續。\"\n }\n ]\n```\n\n## 監控成本：每個功能都應該知道它花了多少錢\n\n你不能優化你不監控的東西。我的做法是在每次 API 呼叫後記錄 token 使用量：\n\n```python\nimport anthropic\nfrom dataclasses import dataclass\nfrom datetime import datetime\nimport logging\n\nlogger = logging.getLogger(__name__)\n\n@dataclass\nclass APICallMetrics:\n feature: str\n model: str\n input_tokens: int\n output_tokens: int\n cache_read_tokens: int\n cache_creation_tokens: int\n timestamp: datetime\n\n def estimated_cost_usd(self) -> float:\n \"\"\"估算這次呼叫的美金成本\"\"\"\n pricing = {\n \"claude-3-5-haiku-20241022\": {\n \"input\": 0.80/1_000_000,\n \"output\": 4.00/1_000_000,\n \"cache_read\": 0.08/1_000_000,\n \"cache_write\": 1.00/1_000_000,\n },\n \"claude-3-5-sonnet-20241022\": {\n \"input\": 3.00/1_000_000,\n \"output\": 15.00/1_000_000,\n \"cache_read\": 0.30/1_000_000,\n \"cache_write\": 3.75/1_000_000,\n },\n }\n\n p = pricing.get(self.model, pricing[\"claude-3-5-sonnet-20241022\"])\n return (\n self.input_tokens * p[\"input\"] +\n self.output_tokens * p[\"output\"] +\n self.cache_read_tokens * p[\"cache_read\"] +\n self.cache_creation_tokens * p[\"cache_write\"]\n )\n\ndef track_api_call(feature: str, response: anthropic.Message) -> APICallMetrics:\n \"\"\"從 API 回應中提取並記錄 metrics\"\"\"\n usage = response.usage\n metrics = APICallMetrics(\n feature=feature,\n model=response.model,\n input_tokens=usage.input_tokens,\n output_tokens=usage.output_tokens,\n cache_read_tokens=getattr(usage, 'cache_read_input_tokens', 0),\n cache_creation_tokens=getattr(usage, 'cache_creation_input_tokens', 0),\n timestamp=datetime.now()\n )\n\n logger.info(\n \"api_call\",\n extra={\n \"feature\": feature,\n \"model\": response.model,\n \"cost_usd\": metrics.estimated_cost_usd(),\n \"cache_hit_rate\": metrics.cache_read_tokens / (metrics.input_tokens or 1),\n }\n )\n\n return metrics\n```\n\n把這些 metrics 送到你的監控系統（Datadog、Grafana、或簡單的 Google Sheets），你就能看到：哪個功能最貴、快取命中率如何、模型選擇是否合適。\n\n## 真實案例：從 $2000 降到 $287\n\n回到這章開頭的那個 RAG 系統。這是我具體做了什麼：\n\n**問題診斷（第一週）**\n\n首先我加入了 token tracking，看清楚費用來自哪裡：\n\n- 70% 的費用來自 input tokens（主要是知識庫文件每次都重新傳）\n- 20% 來自 output tokens（模型的回覆比必要的長）\n- 10% 來自 Sonnet 用於所有查詢（包括只需要 Haiku 的簡單問題）\n\n**修正 1：實施 Prompt Caching（最大效益）**\n\n知識庫文件大約 15,000 tokens，每次查詢都要傳一次。加入 cache 之後，命中率達到 85%——這 15,000 tokens 中的 85% 從 $3/1M 降到 $0.30/1M。\n\n光這一項，input tokens 費用降了 75%。\n\n**修正 2：模型路由（次大效益）**\n\n分析後發現，60% 的查詢是簡單的事實查詢（「退款期限是幾天？」「服務時間是？」），完全不需要 Sonnet。改用 Haiku 後，這 60% 的查詢費用降到原來的 20%。\n\n**修正 3：Output length 控制**\n\n修改 system prompt，明確要求簡潔回覆，平均 output tokens 從 420 降到 180。\n\n**修正 4：對話歷史截斷**\n\n原本每輪對話都傳完整歷史，改為最多保留 6 輪（避免 context 無限增長）。\n\n**最終結果：**\n\n| 項目 | 修改前 | 修改後 | 降幅 |\n| ------------------- | ---------- | ---------- | -------- |\n| 知識庫 input tokens | $1,200 | $220 | -82% |\n| Output tokens | $650 | $280 | -57% |\n| 模型費用 | $491 | 包含在上面 | - |\n| **總計** | **$2,341** | **$287** | **-88%** |\n\n兩個最重要的 takeaway：\n\n1. **Prompt Caching 是 ROI 最高的優化**，如果你有重複的大型 prompt，先把這個做好。\n2. **測量再優化**，不要猜——先加入 monitoring，搞清楚費用來自哪裡，再針對性地優化。\n\n---\n\n省了錢之後，下一個問題是：怎麼讓這個省錢的系統在生產環境穩定跑？錯誤處理、Rate Limit、可觀測性——這些是我們下一章要解決的問題。", "summary": "從 Token 成本全貌、模型選擇策略、Prompt Caching 到 Batch API，系統性地把 AI 應用的成本降下來。一個真實 RAG 系統從每月 $2000 降到 $300 的完整過程。", "image": "https://bobochen.dev/_astro/cover.hVdJm2qF.webp", "date_published": "2026-05-22T00:00:00.000Z", "tags": [ "Claude API", "成本優化", "Token", "省錢" ] }, { "id": "https://bobochen.dev/blog/enterprise-ai-agent-multi-agent-orchestration/", "url": "https://bobochen.dev/blog/enterprise-ai-agent-multi-agent-orchestration/", "title": "多代理協作：什麼時候真的需要 multi-agent，什麼時候那只是讓系統更貴", "content_text": "Multi-agent 聽起來很厲害，但大多數時候一個 agent 加好工具就夠了，而且更好 debug。談 supervisor/worker、pipeline、debate 等協作模式，handoff 怎麼傳 context，錯誤怎麼隔離不互相傳染，以及最重要的——什麼時候你「不」該用多代理。", "content_html": "import DeckEmbed from '../../../components/blog/DeckEmbed.astro';\nexport const deckSlides = Object.entries(import.meta.glob('./slides/*.webp', { eager: true, import: 'default' })).sort(([a], [b]) => a.localeCompare(b)).map(([, m]) => m);\n\n> 這是「從 PoC 到 Production：企業 AI Agent 系統工程」系列第 8 篇（共 12 篇）。上一篇：[Agent memory 與狀態管理](/blog/enterprise-ai-agent-memory-state-management)。\n\n「多代理」（multi-agent）是這兩年最性感的詞之一。一堆 agent 各司其職、互相協作、像個團隊——聽起來就很厲害。但我要先潑一盆冷水，因為這是我看過最多人**為了用而用**、結果把系統搞得又貴又難 debug 的地方。\n\n所以這篇反過來寫：先講**什麼時候不要用**，再講真的要用時怎麼用。\n\n## 先記住這句話：預設用單一 agent\n\n> 大多數你以為需要 multi-agent 的場景，其實一個 agent 加上一組好工具（第 6 篇）就解決了，而且更便宜、更好 debug。\n\n為什麼？因為每多一個 agent，你就多了：\n\n- **一次（或多次）額外的模型呼叫** → 更貴、更慢（第 10 篇）。\n- **一個 context 傳遞的接縫** → agent A 的理解要傳給 agent B，這中間一定會流失資訊、產生誤解。\n- **一個更難追的失敗點** → 出錯時，是哪個 agent 錯的？是它本身錯，還是它接收到的 context 已經被前一個 agent 弄歪了？\n- **錯誤會傳染** → A 給了 B 一個錯誤前提，B 在錯誤前提上認真工作，整條鏈一起歪。\n\n別小看這幾條的代價。Anthropic 自己揭露過一組值得背起來的數字：agent 大約用掉 chat 的 4 倍 token，multi-agent 系統更高達約 15 倍。換句話說，你還沒讓系統變聰明，光是把它拆成多個 agent，帳單就先乘了 15 倍上去。\n\n這些成本是實打實的。所以決定用 multi-agent 之前，先誠實問自己：**單一 agent 配好工具，真的解不了嗎？** 很多時候答案是「能，我只是覺得多 agent 比較酷」。\n\n## 什麼時候 multi-agent 真的有價值\n\n有三種情況，多代理確實划算：\n\n**1. 任務天然可以平行拆分。**\n比如「分析這 20 份競品報告」，拆成 20 個 agent 各讀一份、最後彙整，比一個 agent 慢慢讀快很多。這裡的價值是**平行**，不是「聰明」。\n\n**2. 需要的能力 / 權限差異很大。**\n一個負責「讀取分析」、另一個負責「執行高權限寫入動作」。把它們分開，是為了**權限隔離**（第 5、6 篇）——讓會動手的那個 agent 只有最小必要權限，唯讀分析的那個碰不到危險工具。這是安全考量驅動的拆分，很合理。\n\n**3. 需要對抗 / 審查的結構。**\n一個 agent 產出、另一個 agent 專門挑錯（critic）。這種「生成 vs 審查」的張力，確實能提升品質——本質上是把「自我檢查」外部化成一個獨立角色。\n\n注意這三個的共通點：**拆分有明確的工程理由（平行、隔離、對抗），不是為了模擬一個公司組織圖**。\n\n這個判斷不是我一個人的偏執。2025 年 6 月有一場被社群並列為「同一週對打」的公開辯論：Anthropic 發表《How we built our multi-agent research system》，主張在可平行的廣度研究任務上拆 agent 很划算——他們的多 agent 系統在這類任務上比單一 agent 高出 90.2%；幾乎同一週，做 Devin 的 Cognition（Walden Yan）發表《Don't Build Multi-Agents》，主張預設就用單執行緒的線性 agent、別輕易拆。\n\n表面上兩篇在打架，細看卻不矛盾——差別只在「這個任務是不是真的能平行解耦」。有趣的是 Anthropic 自己也點名：**大多數 coding 任務「真正可平行的部分比研究少很多」**，因為各部分彼此相依、要共享同一份 context，硬拆反而會撞車。所以判斷能不能平行，看的不是表面能不能分工，是分出去的子任務彼此依賴有多深——讀競品報告可以各讀各的，寫一個 feature 通常不行。\n\n## 幾種協作模式\n\n真的要做了，常見的結構有這幾種：\n\n### Supervisor / Worker（主管—工人）\n一個 supervisor agent 負責拆任務、分派、彙整；底下幾個 worker agent 各做一塊。最常見、最好管，因為**控制流集中在 supervisor**，責任清楚。大部分企業場景用這個就夠。\n\n### Pipeline（流水線）\nagent 串成一條線，A 的輸出是 B 的輸入（研究 → 草稿 → 審稿 → 定稿）。適合**階段分明、單向流動**的任務。要小心的是**錯誤會沿著管線累積放大**——第一棒歪一點，最後一棒可能歪很多。\n\n### Debate / Critic（辯論—審查）\n多個 agent 對同一問題提不同觀點，或一個產出、一個反駁，最後收斂。品質好但**最貴**（同一問題算好幾遍），留給高價值、容錯低的決策用。\n\n## Handoff：接縫是最容易漏水的地方\n\n多代理最脆弱的地方，是 agent 之間**交棒（handoff）**那一刻。A 要把它的理解傳給 B，這裡有兩個常見坑：\n\n- **傳太多**：把 A 的整段思考、所有中間產物全倒給 B，B 的 context 被灌爆、抓不到重點、又貴。\n- **傳太少**：只給 B 一個結論，B 缺了關鍵脈絡，只好自己腦補，腦補就錯。\n\n好的 handoff 是**設計過的介面**：明確定義「A 交給 B 的，是哪幾個欄位、什麼格式」，像在設計兩個 service 之間的 API contract 一樣。這又回到系統工程——agent 之間的協作，本質是**介面設計**問題，跟微服務之間怎麼定 contract 是同一種思考。\n\n這套「把 handoff 當 API contract」的想法，框架也已經幫你制度化了。OpenAI 的 Agents SDK 就把 handoff 做成一級原語：agent A 用一個類似 `transfer_to_agent_b` 的工具呼叫，把控制權加上一份結構化 payload 交給 B，整個轉移還會被記錄、可以重播；後續更新甚至把巢狀 handoff 的完整歷史改成預設 opt-in，正是為了減少跨 agent 的 context bleed——框架的演進方向，剛好就是這篇講的那套介面紀律。\n\n## 錯誤隔離：別讓一個 agent 拖垮全部\n\nCognition 講過一個很有畫面感的翻車案例：他們把「做一個 Flappy Bird clone」拆成平行子任務，結果一個 subagent 把背景做成了 Super Mario 的風格，另一個 subagent 做的鳥又跟整體美術不搭。每個 subagent 單獨看都很合理，合起來卻是個四不像——因為它們看不到彼此在做什麼。這就是「接縫漏水」最具體的長相：不是哪個 agent 出 bug，而是它們各自正確、彼此不一致。\n\n既然錯誤會傳染，就要主動隔離：\n\n- **驗證交棒內容**：B 接到 A 的東西，先做基本檢查（格式對不對、有沒有明顯矛盾），別照單全收。\n- **限制爆炸半徑**：一個 worker 失敗，supervisor 要能處理（重試、換人、降級），而不是整個任務崩掉。\n- **設總預算上限**：整個多代理任務要有 token / 時間 / 步數的天花板，否則一群 agent 互相觸發，可以把成本燒到失控（第 10 篇會細談這個「成本爆炸」風險）。\n\n## 一個務實的決策流程\n\n下次有人說「我們來做 multi-agent 吧」，照這個順序問：\n\n1. **單一 agent 配好工具能不能解？** 能 → 就用單一，收工。\n2. 不能的話，**是因為平行、權限隔離、還是需要對抗審查？** 三個都不是 → 你大概其實不需要 multi-agent。\n3. 是的話，**選最簡單能滿足的結構**（通常是 supervisor/worker），把 handoff 當 API contract 設計，設好預算上限和錯誤隔離。\n\n## 小結\n\nMulti-agent 不是更高級的 agent，是一個**有明確成本、要有明確理由才值得付**的架構選擇。預設用單一 agent；只在平行、權限隔離、對抗審查這三種情況下拆分；拆分時把 agent 間的 handoff 當成介面設計，並嚴防錯誤傳染和成本爆炸。\n\n這不只是我的經驗法則。做過最大規模多 agent 系統的 Anthropic，給的判準幾乎一模一樣：multi-agent 只在「任務價值高到足以支付那多燒的 token」時才划算。換句話說——能不能用，先算這題值不值得你多燒那 15 倍。\n\n能忍住「不為酷而拆」，是這個主題上最值錢的判斷力——也是面試時很容易聽得出來「這個人到底有沒有真的做過」的地方。\n\n前面八篇我們把系統的「能力面」蓋得差不多了：知道事情（RAG）、記得事情（memory）、做事情（tools）、協作（multi-agent）。接下來三篇轉向「**能不能信任**」這件事。下一篇先處理最基礎的：**你怎麼知道這整套東西到底有沒有在好好運作**——生產級的可觀測性與評估。\n\n## 文章簡報\n\n\n\n---\n\n### 延伸閱讀\n\n- 上一篇：[Agent memory 與狀態管理](/blog/enterprise-ai-agent-memory-state-management)\n- [多代理協作的真實世界案例](/blog/multi-agent-orchestration-real-world)\n- [用 Claude API 打造多代理系統](/blog/claude-api-guide-multi-agent)\n- 下一篇：《生產級 LLM 可觀測性與評估》", "summary": "Multi-agent 聽起來很厲害，但大多數時候一個 agent 加好工具就夠了，而且更好 debug。談 supervisor/worker、pipeline、debate 等協作模式，handoff 怎麼傳 context，錯誤怎麼隔離不互相傳染，以及最重要的——什麼時候你「不」該用多代理。", "image": "https://bobochen.dev/_astro/cover.BpHWtpH-.webp", "date_published": "2026-05-19T00:00:00.000Z", "date_modified": "2026-06-05T00:00:00.000Z", "tags": [ "Multi-Agent", "Orchestration", "AI Agent", "系統設計", "LLM" ] }, { "id": "https://bobochen.dev/blog/github-readme-dynamic-demo-strategies/", "url": "https://bobochen.dev/blog/github-readme-dynamic-demo-strategies/", "title": "GitHub README 動態 demo 的 5 種策略：從 GIF 到自架 CDN", "content_text": "把產品 demo 塞進 GitHub README 不只