Blog E

[Claude Code 實戰] 重新盤點終端機工作流：從 zsh 自動完成到搜尋比對工具鏈

Tue, 04 Aug 2026 00:00:00 +0000

痛點：每打一個指令，都要重新來一次

平常用 Claude Code 處理事情的時候，一直有兩個小摩擦一直在，只是還沒認真處理過。

第一個是 shell 本身太陽春：~/.zshrc 裡除了兩行 PATH 什麼都沒有，沒有自動完成、沒有指令記憶，翻歷史只能一路按上鍵慢慢找，找到類似指令還得手動改。第二個是跟 Claude Code 協作時，一些明明是唯讀、完全不會有副作用的指令（列檔案、查版本、curl 個 README），每次都要跳出來按一次允許，一來一回打斷節奏。

這篇記錄的就是一次把這兩件事一次盤點掉的過程：怎麼選工具、踩到什麼坑、以及最後怎麼跟 Claude Code 的權限系統對接起來。

解法一：先讓 zsh 自己記得你打過什麼

沒有裝 oh-my-zsh，也不想為了兩個功能扛一整套框架，所以直接挑最小夠用的兩個套件：

zsh-autosuggestions：打字時用灰色文字提示之前打過的類似指令，按 Ctrl+空白鍵 或 → 接受
zsh-completions：補強 tab 自動完成的涵蓋範圍

brew install zsh-autosuggestions zsh-completions

再搭配歷史紀錄設定，讓上下鍵可以依照目前已輸入的內容去篩選歷史，而不是整批往前翻：

# --- 指令歷史紀錄設定 ---
HISTFILE=~/.zsh_history
HISTSIZE=10000
SAVEHIST=10000
setopt SHARE_HISTORY       # 多個終端機視窗共用歷史紀錄
setopt HIST_IGNORE_DUPS
setopt HIST_IGNORE_ALL_DUPS
setopt HIST_FIND_NO_DUPS
setopt INC_APPEND_HISTORY  # 指令一輸入就馬上寫入歷史檔

autoload -Uz up-line-or-beginning-search down-line-or-beginning-search
zle -N up-line-or-beginning-search
zle -N down-line-or-beginning-search
bindkey "^[[A" up-line-or-beginning-search
bindkey "^[[B" down-line-or-beginning-search

裝完套件、加完設定，理論上重開終端機就能用了——實際上沒有這麼順利。

解法二：補顏色，讓終端機看得更快

自動完成裝好之後，順手把顏色也一起補了：

zsh-syntax-highlighting：打指令時即時上色，有效指令綠色、無效指令紅色
ls -G：資料夾、執行檔、連結各自不同顏色
grep --color=auto：比對到的關鍵字直接標紅

export CLICOLOR=1
export LSCOLORS=GxFxCxDxBxegedabagaced
alias grep='grep --color=auto'

source /opt/homebrew/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh

字體也一起處理：Ghostty 的設定檔（~/Library/Application Support/com.mitchellh.ghostty/config.ghostty）原本沒指定字體大小，吃系統預設的 13，直接加一行 font-size = 16 解決。

解法三：把 `ls`、`cat`、`cd` 也換成更聰明的版本

顏色跟自動完成算是基礎建設，接著補了三個常用指令的現代化替代品，選擇標準只有一個：單一執行檔、沒有背景常駐程序，不會拖慢啟動速度。

指令	替代品	換來什麼
`ls`	`eza --icons`	彩色、圖示、樹狀結構（`lt`）
`cat`	`bat --paging=never`	語法高亮、行號
`cd`（輔助）	`zoxide`	記住常去的資料夾，`z proj` 直接跳過去

fzf 這次評估後沒有裝——目前的使用習慣還沒有到需要模糊搜尋歷史/檔案的程度，等真的有感覺卡再補。

解法四：讓 Claude Code 搜尋、比對檔案更快

前面幾項是「人用得爽」，這一項是「Claude Code 用得快」。Claude Code 內建的搜尋工具本身就是用 ripgrep（rg）在跑，jq 也已經裝了，所以缺的是這三個：

fd：取代 find，語法簡單、速度快，列檔案清單特別有感
ast-grep：結構化程式碼搜尋，不是純文字比對，而是看語法樹（AST）。可以搜「所有呼叫某函式且第一個參數是字串的地方」，對大範圍重構或精準搜尋特定寫法比 regex 準確很多
difftastic（difft）：語法感知的 diff，函式搬位置也看得出來只是移動，不是整段被砍掉重寫

brew install fd ast-grep difftastic git-delta

git-delta 主要是給人看 git diff 用的，跟 Claude Code 本身無關，但反正裝了就順手一起弄。

解法五：把常用唯讀指令收進 Claude Code 的權限白名單

工具裝好之後浮出一個新問題：這些新指令第一次被 Claude Code 呼叫時，一樣得跳出來問一次要不要允許。用 fewer-permission-prompts 這個 skill 掃了最近幾個 session 的 transcript，統計出實際常跑、而且真的是唯讀的指令，整理出一份白名單：

{
  "permissions": {
    "allow": [
      "Bash(curl -s https://raw.githubusercontent.com/*)",
      "Bash(curl -s \"https://api.github.com/*)",
      "Bash(brew list*)",
      "Bash(xcodes list*)",
      "Bash(xcodebuild -version)",
      "Bash(curl -sI *)",
      "Bash(difft *)",
      "Bash(delta *)"
    ]
  }
}

fd、rg、jq 沒有出現在清單裡，不是漏掉，是因為 Claude Code 本身已經把這幾個列為內建自動允許的唯讀指令，不需要再加規則。

容易忽略的三個坑

坑一：`compinit` 抱怨「insecure directories」

裝完套件重開終端機，第一次啟動就跳出：

zsh compinit: insecure directories, run compaudit for list.

用 compaudit 查出問題出在 /opt/homebrew/share 這層目錄權限太開放（group 有寫入權限）。compinit 在載入補全腳本前會檢查權限，只要有一層目錄是「別人也能寫」，就直接拒絕載入，避免有心人把惡意腳本塞進補全路徑裡執行。修法是 Homebrew 官方就建議的做法：

chmod go-w /opt/homebrew/share
chmod -R go-w /opt/homebrew/share/zsh
rm -f ~/.zcompdump*

清掉快取讓它重建一次，問題就沒再出現過。

坑二：`zsh-syntax-highlighting` 一定要放在檔案最後一行

這個套件的官方文件寫得很明白：這一行必須是 .zshrc 裡最後被執行的東西，放在 zsh-autosuggestions 或其他 bindkey 設定前面的話，語法上色跟自動建議會互相干擾、按鍵綁定也可能失效。整理設定檔的時候特別把它挪到檔案最尾端，而不是照裝的順序隨手加在中間。

坑三：`ast-grep` 沒有被放進白名單，是刻意的

白名單清單裡少了 ast-grep，不是漏掉。它預設跑起來是唯讀搜尋沒錯，但只要加上 -U / --update-all 參數就會直接改寫檔案。權限規則是前綴比對（prefix match），沒辦法只允許「不帶 -U」的用法——只要開了 Bash(ast-grep *) 這種大範圍規則，理論上就等於連改寫檔案的用法也一起放行了。

這跟專案原本對 sed 的處理邏輯是一致的：sed 也只有「唯讀運算式」的用法會被自動允許，帶有 in-place 編輯的用法一律還是要跳出來問一次。與其自己重新評估一次風險，不如直接沿用同一套判斷標準。

總結與效益

這次的終端機環境重整，說到底是把「人打字」跟「Claude Code 執行」兩件事分開優化：

打字更少：zsh-autosuggestions + 歷史篩選，重複指令幾乎不用重打
看得更快：語法上色、eza、bat 讓輸出一眼就能分辨重點
找路更快：zoxide 取代死記路徑，fd 取代龜速的 find
Claude Code 搜得更準：ast-grep 補上純文字比對做不到的結構化搜尋，difftastic 讓 diff 結果更貼近實際改動
少按幾次允許：把真正唯讀、且風險可控的指令收進白名單，剩下真正該問的（像 ast-grep -U）還是照樣會問

工具選擇的主軸自始至終沒變過：單一執行檔、沒有背景常駐、能不裝框架就不裝框架。真正花時間的反而是判斷「這個要不要放進白名單」——速度是其次，會不會不小心把一個能改檔案的指令包成看似安全的萬用規則，才是要謹慎的地方。

[開發紀錄][Node.js] Feedly Classic 回不去了，我自己動手做了一個 FeedFlow（一）

Sat, 25 Jul 2026 00:00:00 +0000

前言:

Feedly 改版之後，介面我一直不習慣，尤其是懷念舊版 Feedly Classic 那種一欄式、資訊密度高、不拖泥帶水的閱讀節奏。訂閱的來源裡有不少英文、日文、韓文的技術部落格，每次要嘛開分頁丟去翻譯、要嘛乾脆跳過，久而久之這些來源就變成已讀不回。

與其繼續將就，我花了一個週末，自己刻了一個 RSS 閱讀器：FeedFlow。手機瀏覽器優先、深色主題、多欄位檢視模式，這部分是在向 Feedly Classic 致敬；資料存在 Google Firestore，帳號綁 LINE Login；訂閱到的非中文文章，背景會自動用 Gemini 2.5 Flash 翻成繁體中文。目前已經部署在 Cloud Run 上面，自己每天在用。

這個 repo 會持續開發下去，這篇是系列文章的第一篇，先把整個專案的骨架、幾個關鍵決策的來龍去脈記錄下來。

TL;DR

本篇文章會依序介紹：

為什麼要自己刻一個 RSS 閱讀器
LINE Login 在這個專案裡代表的意義
RSS 閱讀器的開發過程：從單機 MVP 到多使用者雲端同步
為什麼選 Gemini 當翻譯引擎，中間踩了哪些坑
前端介面：四種檢視模式與行動裝置優先設計
意外的插曲：把洩漏的密鑰從 git 歷史裡挖乾淨
目前進度與下一篇的方向
結論
參考連結

為什麼要自己刻一個 RSS 閱讀器

市面上不缺 RSS 閱讀器，但我要的東西很具體：手機上開起來要快、介面資訊密度要高（不要每篇文章都用一張大圖佔掉整個螢幕）、然後外文來源要能就地翻譯，不用切換到別的分頁。這三個條件湊在一起，現成的服務沒有一個完全符合，尤其是「非中文文章自動翻譯」這件事，幾乎沒有閱讀器把它當一等公民做。

專案取名 FeedFlow，核心就三塊：後端一支 Express（server.js），負責抓 RSS、解析內容、呼叫 Gemini、讀寫 Firestore；前端是純 Vanilla JS 的 ES Modules（app.js、store.js、api.js、i18n.js），沒有套框架；資料庫用 Firestore，帳號則是 LINE Login。整個 MVP 第一版就把訂閱管理、資料夾分類、四種檢視模式、深色主題全部生出來了，後面的每一版都是在這個骨架上加東西。

我之前寫過如何透過 Golang 開發 OAuth2 的 PKCE，講的是 LINE Login 導入 PKCE 的實作細節。那時候是把 LINE Login 當研究對象在拆解協定；這次在 FeedFlow 裡，LINE Login 換了一個角色——它是整個多使用者架構能不能成立的關鍵。

FeedFlow 最早其實沒有帳號系統，資料就存在瀏覽器的 localStorage，換一台裝置訂閱就不見了。要做雲端同步，第一件事是要有一個穩定的使用者身份，而且這個身份要能在 Firestore 裡當 document 路徑的 key（users/{userId}/...）。比起自己刻一套帳號密碼系統，直接用 LINE Login 換來的 LINE User ID（sub claim）當這把 key，省掉了整套密碼、驗證信、忘記密碼流程，對一個個人專案來說划算很多。

這個決定也不是一次到位的。最早的版本其實是偷懶版：讓使用者自己貼一段 LINE UID 字串進去，後端只是拿去當 Firestore key，沒有做任何身份驗證——這樣的「登入」等於任何人都能冒充任何一個 UID。下一版才換成正規的 LINE OpenID Connect：標準的 OAuth 2.1 授權碼流程，拿到 id_token 之後用 LINE 的 /oauth2/v2.1/verify 驗證簽章，session 存在 HTTP-only cookie，而不是塞在網址參數裡到處跑。再之後又補上 state 跟 nonce 檢查，擋掉 CSRF。這個「先求有、再求對」的順序，某種程度上也反映了個人專案常見的節奏：先把功能兜起來確認方向對不對，安全性的坑等看得到需求了再回頭補。

因為主要使用情境是在 LINE 裡分享連結、在 LINE 內建瀏覽器打開，所以除了標準的 OAuth 重導向，也整合了 LIFF SDK，讓使用者如果是在 LINE App 裡開啟，可以直接用 LIFF 的 SSO 登入，不用再跳出去瀏覽器繞一圈。

RSS 閱讀器的開發過程：從單機 MVP 到多使用者雲端同步

MVP 階段的功能其實跟一般 RSS 閱讀器沒什麼差異：貼網址進去，後端用 rss-parser 解析 feed，找不到 feed 就用 cheerio 去掃網頁 <link> 標籤做 auto-discovery；訂閱進來的來源可以分類到資料夾；文章可以標記已讀、全部標記已讀；提供重新整理拉取最新文章。這一版資料還全部存在 localStorage。

真正讓專案變得「像一個產品」的是接上 Firestore 之後的那幾版。每個使用者的訂閱清單、資料夾、閱讀進度、偏好設定，都寫進 users/{LINE_UID}/... 底下獨立的路徑，多租戶資料互不干擾。閱讀進度記到很細：不只是「這篇讀過了」的 ID 清單（readArticleIds），還記了每個 feed 目前讀到哪一篇（lastReadArticleId），換裝置或重新整理都接得回去。

比較有意思的是「auto-hydration」這個小機制：Cloud Run 重新部署、或是換一台裝置登入時，記憶體裡是沒有文章資料的，只有 Firestore 裡的訂閱清單。這時後端會在背景把訂閱清單裡每個 feed 重新抓一次、解析出文章，再把畫面填滿，使用者不會看到一個空的「請先訂閱」畫面，銜接得算自然。

後來又加了一版「豐富預覽」：貼 RSS 網址進去的當下，除了抓 feed 的標題跟簡介，還會順便抓最新三篇文章當樣本，非中文的內容一併丟給 Gemini 翻譯，訂閱前就能看懂這個來源在寫什麼，不用真的訂下去才發現是自己看不懂的語言。

為什麼選 Gemini 當翻譯引擎，中間踩了哪些坑

會需要翻譯，是因為訂閱清單裡有不少非中文來源。判斷邏輯很單純：後端偵測文章語言，不是繁體中文的，就丟給 Gemini 2.5 Flash 翻，回傳 JSON 結構的 translatedTitle / translatedContent，前端在文章卡片跟閱讀器都加一個「✨ 繁中」的翻譯徽章，閱讀器裡還有一顆按鈕可以在原文跟翻譯之間切換。選 Gemini 沒有太多懸念，2.5 Flash 的延遲跟成本都適合這種「每次進畫面就要順手翻好幾篇」的用量，用其他家 API 也做得到，但當時手上這個 GCP 專案本來就在用，順手接上去而已。

第一版是最直接的做法：拿 GEMINI_API_KEY 直接打 Generative Language API。能動，但部署到 Cloud Run 之後，這代表要多管理一組 API Key 環境變數，金鑰外洩的風險也跟著多一份。後來把翻譯這段改成走 Vertex AI，用 Cloud Run 服務本身的身份（ADC，Application Default Credentials）驗證，不用另外持有一把 API Key——Cloud Run 的 service account 本身就有權限呼叫 Vertex AI，設定 IAM 就好，不用在程式碼或環境變數裡塞任何密鑰。本地開發沒有 ADC 環境的時候，才退回用 GEMINI_API_KEY 當備援。

這一版上線後在 Cloud Run 的 log 裡整批翻譯請求都在失敗，訊息是「Neither Vertex AI ADC self-identity nor GEMINI_API_KEY is available」，明明兩條路都設定了。查下去才發現是 @google/genai SDK 的用法搞錯：它要的是 vertexai: true 這個布林值，加上 project、location 兩個平行參數；我一開始寫成巢狀的 vertexai: { project, location }，SDK 判斷「有沒有開 Vertex 模式」跟「有沒有讀到 project/location」是兩段分開的邏輯，結果變成 SDK 以為 Vertex 模式開著，卻讀不到專案跟區域，每次呼叫都在起手式就死掉。

與其去啃 SDK 的參數規則，最後乾脆把 @google/genai 整包拿掉，改用 google-auth-library 的 GoogleAuth 直接要一張 ADC token，自己組 HTTP request 打 Vertex AI 的 generateContent REST endpoint。少一層 SDK 包裝，行為反而更好預測——這種時候繞過 SDK、直接打 REST API，比在文件裡找 SDK 到底哪個參數該巢狀哪個該平行，省事很多。

前端介面：四種檢視模式與行動裝置優先設計

介面設計的參考座標就是 Feedly Classic：一個右上角的檢視模式切換鈕，四種模式都在同一份文章資料上套不同版型，不用重新抓資料。

模式	特色
Magazine（雜誌）	預設模式，圖文並陳的摘要卡片，適合快速掃過標題跟一小段內容
List（列表）	高密度純文字列表，一眼能看到的文章數量最多
Title Only（純標題）	只留標題，捲動速度最快
Cards（卡片）	大圖為主的視覺卡片，適合圖片內容豐富的來源

側邊欄是資料夾結構，每個資料夾跟未分類的訂閱各自列出，旁邊帶未讀數字徽章；文章清單跟閱讀器是兩塊面板，點文章從清單滑進閱讀器、上滑手勢滑回清單，操作邏輯照著手機原生 App 的習慣走，不是網頁常見的那種點連結整頁跳轉。整體是深色主題，topbar 放了選單、檢視模式、全部已讀、重新整理、設定幾顆圖示按鈕，登入後 LINE 顯示名稱直接顯示在原本「LINE 登入」按鈕的位置。

設定頁裡把「介面語言」跟「翻譯目標語言」拆成兩個獨立選項：介面語言目前有 zh-TW / en / ja 三種，翻譯目標語言則是決定 Gemini 要把外文翻成哪種語言，這兩件事沒有理由綁在一起，一個使用者的介面可能開英文，但還是想把日文文章翻成繁體中文看。

目前進度與下一篇的方向

寫這篇的當下，repo 裡剛好新增了兩份文件（docs/superpowers/specs/ 跟 docs/superpowers/plans/），在規劃文章列表的分頁瀏覽，每五篇一頁、支援滑動手勢、滾輪、按鈕三種方式翻頁。這部分還在開發中，等做完會是這個系列的下一篇。

結論

FeedFlow 目前解決的問題很單純：手機上快速掃過一堆外文技術文章，不用切分頁翻譯、不用忍受臃腫的介面。三個決策撐起了現在這個架構——LINE Login 提供免刻帳密系統的使用者身份、Firestore 撐多使用者雲端同步、Gemini 2.5 Flash（走 Vertex AI ADC，不落地存 API Key）處理翻譯。這幾塊都不是一次做對，LINE 登入從貼字串進化到正規 OAuth，翻譯從裸 API Key 換成服務身份驗證，都是先跑通、再補強。

參考連結：

[學習心得][Golang] AI Agent 時代的授權難題：ID-JAG 是什麼？為什麼我用 Go 重新實作了一次

Thu, 23 Jul 2026 00:00:00 +0000

前言:

這半年多讓 AI Agent 直接接上內部系統、幫忙做事，已經不是什麼新鮮事了。但只要仔細想一步：Agent 要用「誰的身份」去呼叫那些 API？如果它拿到的權限跟人一樣大，一旦被騙去執行了不該做的操作，後果可能比人自己手滑還嚴重。

這正是 ID-JAG（Identity Assertion JWT Authorization Grant）想解的問題。我最近把這套機制的原理整理了一遍，也照著 athenz-community/id-jag-the-hard-way 這個教學 repo，把裡面的 MCP Server 用 Go 重新實作了一遍：kkdai/id-jag-mcp。這篇文章想把 ID-JAG 的技術原理講清楚：它建立在哪些 RFC 標準上、跟我之前寫過的 OAuth2 / PKCE 有什麼不一樣、實際的 token 交換流程長什麼樣，最後也會示範怎麼把這個 Go 專案跑起來、怎麼測試。

TL;DR

本篇文章會依序介紹：

什麼是 ID-JAG？為什麼需要它？
從 OAuth2、PKCE，到 Agent 時代的新問題
兩塊 RFC 基石：Token Exchange 與 JWT Bearer
ID-JAG 的完整 token 交換流程
每一跳都窄化權限：最小權限原則怎麼落地
為什麼要用 Go 重新實作這個 MCP Server？
動手玩：安裝、執行與測試
結論
參考文章

什麼是 ID-JAG？為什麼需要它？

ID-JAG 是一種讓 AI Agent 代替使用者去存取受保護資源的授權機制，重點是「代替」這兩個字。目前它還是 IETF 的 Internet-Draft，還沒成為正式 RFC，但已經有 LY Corporation（在 Athenz 授權系統上）跟 Okta 等單位開始實作，MCP（Model Context Protocol）規範也已經引用了這份草案。

傳統的服務對服務授權，通常是兩種極端：要嘛整個服務共用一把萬用鑰匙（API Key、Service Account），要嘛乾脆把使用者的 session 或長效 token 直接借給程式用。前者權限太大，後者不僅沒有審計軌跡，一旦洩漏，攻擊者幾乎可以完全冒充使用者，而且很難被偵測出來。等到 AI Agent 開始自己決定要呼叫哪些工具、串接哪些內部 API 的時候，這兩種做法的風險都被放大了：Agent 可能因為 prompt injection 或幻覺，做出使用者根本沒打算做的操作，而如果 Agent 手上握的是一把萬用鑰匙，後果就是全公司資料任其存取。真實場景裡也常常是「Orchestrator Agent 呼叫 Sub-Agent」的多層架構，風險是一路往下傳遞的。

ID-JAG 想做到的是：Agent 每一次行動，都必須能證明「這是某個特定使用者，在某個特定當下，授權我做這一件特定的事」，而且這個授權範圍要盡可能窄、有效期要盡可能短。它建立在 OAuth2 的 token exchange（RFC 8693）之上，多蓋了一層「這個 token 是從人的身份主張衍生出來的」證明機制。這也是為什麼它同時被列在 OAuth.net 的 Cross-App Access（XAA）頁面上——這正是 Agent 時代才會冒出來的新問題。

順帶一提，ID-JAG 也解決了一個很實際的使用體驗問題：如果每次 Agent 要存取一個新服務，都得跳出瀏覽器視窗讓使用者手動按「同意」，這種體驗很快就會讓人疲乏、乾脆什麼都按同意。ID-JAG 把授權動作收斂到使用者透過 SSO 登入的那一刻，之後 Agent 需要新的存取權限時，是拿著已經核發的身份主張去跟授權伺服器換 token，不需要使用者再跳出來按一次。

從 OAuth2、PKCE，到 Agent 時代的新問題

我之前寫過如何透過 Golang 開發 OAuth2 的 PKCE，內容是 LINE Login 導入 PKCE 的實作經驗。那篇文章解的問題，跟 ID-JAG 解的問題其實完全是兩個層次，拿出來對比一下會更清楚 ID-JAG 到底新在哪裡。

PKCE 解的是「client 身份是否可信」的問題：手機 App 這種沒辦法安全保管 client secret 的公開客戶端，authorization code 有可能在傳遞過程中被同一支手機上的惡意 App 攔截。PKCE 用 code_verifier / code_challenge 這組一次性配對，確保就算 code 被偷了，沒有正確的 verifier 也換不到 token。整個問題發生在「使用者本人跟他手上那支 App」之間的單一跳（single hop）。

ID-JAG 解的則是「這個非人類的服務身份，有沒有資格代表這個人做這件事」的問題，而且往往橫跨好幾跳：使用者登入 IdP → AI Client Gateway → MCP Server → 最終的 Resource Server。每一跳的呼叫者都不是使用者本人，卻都得證明自己是「奉旨行事」。傳統 OAuth 2.0 一開始的設計，是為「人類使用者 ↔ 應用程式」這種場景設計的，並不直接支援這種多層 Agent 鏈的委派情境。PKCE 保護的是一次授權交換的完整性；ID-JAG 保護的是一整條授權鏈路上，每一個環節的最小必要權限。兩者不衝突，是同一個大架構下，解決不同階段問題的機制。

兩塊 RFC 基石：Token Exchange 與 JWT Bearer

ID-JAG 沒有憑空發明一套新協定，而是把兩個既有的 IETF 標準組合起來用。搞懂這兩塊基石，才看得懂後面完整的交換流程在做什麼。

第一塊是 RFC 8693 — OAuth 2.0 Token Exchange，定義了一個通用的「用一種 token 換另一種 token」協定，概念上有點像去外幣兌換所把日圓換成台幣，只是這裡換的是安全令牌。一個 token exchange 請求大致長這樣：

POST /token
grant_type=urn:ietf:params:oauth:grant-type:token-exchange
subject_token=<身份主張 JWT>
subject_token_type=urn:ietf:params:oauth:token-type:jwt
requested_token_type=urn:ietf:params:oauth:token-type:access_token
scope=read:orders

subject_token 放的是代表被委派身份的 token，requested_token_type 說明想換成什麼型別的 token，scope 則可以在交換的當下就把權限範圍縮小。

第二塊是 RFC 7523 — JWT Bearer Grant，讓一個 JWT 本身就可以直接拿來當 OAuth 2.0 的授權憑證，不用先繞去換一次 authorization code：

POST /token
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
assertion=<已簽名的身份主張 JWT>

授權伺服器收到之後，用簽發者（IdP）的公鑰驗證這個 JWT 的簽章，確認 audience、scope、exp 這些欄位都合理，就可以直接核發 Access Token，不需要使用者二次同意——因為 IdP 已經替這個身份主張背書過了。

這兩者要交換的「身份主張 JWT」，一般會包含以下欄位：

{
  "iss": "https://enterprise.idp.example.com/v1",
  "sub": "alice@company.com",
  "aud": "https://api.service.example.com",
  "exp": 1773839486,
  "iat": 1773825086,
  "jti": "abc123-7dc6-42ab-b326-uniqueid",
  "scope": "read:orders write:tickets"
}

sub 是被代理的使用者、aud 是這份主張要交給哪個服務用、scope 是允許的權限範圍、jti 則是唯一 ID，用來防止同一份主張被重放使用。ID-JAG 就是把這份短效的身份主張，透過上面兩個 RFC 定義的交換機制，逐步換成 Agent 真正能拿去呼叫 API 的 Access Token。

ID-JAG 的完整 token 交換流程

以 id-jag-the-hard-way 這個教學 repo 的架構為例（用 Athenz 當授權伺服器），完整的鏈路是把前面兩個 RFC 串接起來使用：

使用者登入 IdP（Keycloak）
   │  拿到 OIDC ID Token
   ▼
AI Client Gateway
   │  用 RFC 8693 Token Exchange，把 ID Token 換成 ID-JAG
   │  （grant_type=token-exchange, subject_token_type=id_token,
   │   requested_token_type=id-jag）
   ▼
再用 RFC 7523 JWT Bearer，拿 ID-JAG 去換一個真正能用的 Athenz Access Token
   │  （grant_type=jwt-bearer, assertion=<ID-JAG>）
   ▼
AI Client 帶著這個 Access Token 呼叫 MCP Server
   │
   ▼
MCP Server 收到請求後，「自己」再做一次 RFC 8693 Token Exchange
   │  把收到的 Access Token 換成「這個工具需要的最小 scope」的新 Access Token
   │  （這一步用的是 MCP Server 自己的 mTLS service identity，不是使用者的憑證）
   ▼
用換到的窄化 Access Token 呼叫最終的 Resource Server

整條鏈路裡，token 被交換了不只一次，而是每經過一個信任邊界就交換一次，範圍也越換越窄。這個設計刻意讓每一段路徑的「憑證」都不一樣——AI Client Gateway 手上的 token 沒辦法直接拿去騙過最終的 Resource Server，因為 MCP Server 這一關會強制重新驗證、重新換發。核發出來的 Access Token 裡，通常也會同時記錄 sub（被代理的使用者）跟 act（實際執行操作的 Agent 身份）兩個欄位，下游服務因此可以清楚看到「Alice 透過某個 Agent 執行了這個操作」，稽核記錄不會斷在半路。

每一跳都窄化權限：最小權限原則怎麼落地

這是我覺得整個架構設計得最漂亮的地方：最小權限不是寫在文件裡的原則，而是被 token exchange 這個機制物理性地強制執行。

以我重新實作的 id-jag-mcp 為例，它對外提供三個工具：

工具	對應的 Athenz Scope
`get_k8s_docs`	`api:role.docs-getter`
`delete_k8s_doc`	`api:role.docs-deleter`
`post_k8s_doc`	`api:role.docs-poster`

MCP Server 收到請求時，不會直接把 AI Client 傳來的 Access Token 轉發給上游 API——它一定會先用自己的 mTLS 憑證，向 Athenz ZTS 拿著「這個工具實際需要的 scope」重新交換一次 token，換到的新 token 才會拿去呼叫上游。就算 AI Client Gateway 那邊的 token 範圍比較寬（例如同時擁有讀跟刪的權限），MCP Server 在轉發之前，也只會替每一個工具要求它真正需要的那一小塊權限。

換句話說，整個系統裡沒有任何一個環節「順手」擁有比它當下任務更大的權限——這不是靠 code review 或是內規檢查出來的，而是架構上根本沒辦法繞過。

為什麼要用 Go 重新實作這個 MCP Server？

id-jag-the-hard-way 原本的 MCP Server（api_server/mcp/）是用 TypeScript + Express 寫的，而且是手刻 JSON-RPC 2.0 協定（沒有用官方 SDK）。我想確認兩件事：第一，這套 token 交換架構如果換一個語言、換一個 MCP SDK 實作，邏輯是不是真的完全可以複製；第二，官方的 modelcontextprotocol/go-sdk 用起來到底如何。

最後的實作維持了原本的核心邏輯（同樣的 scope 對應、同樣的 mTLS token exchange 流程），但把協定層整個換成官方 Go SDK，mTLS client 則是自己刻的（沒有依賴 Athenz 官方的 Go client library）。

動手玩：安裝、執行與測試

程式碼在 kkdai/id-jag-mcp（Apache 2.0 授權）。專案結構跟職責切分大致是：

cmd/id-jag-mcp/       進入點：讀取設定、組裝所有元件、啟動 HTTP server
internal/config/      環境變數設定讀取
internal/athenz/      mTLS client + Athenz ZTS RFC 8693 token exchange
internal/tools/       工具輸入型別 + 共用的上游轉發邏輯
internal/server/      MCP 工具註冊（官方 SDK）+ REST 快捷路由 + logging

先把專案抓下來、建置成 binary：

git clone https://github.com/kkdai/id-jag-mcp.git
cd id-jag-mcp
go build -o id-jag-mcp ./cmd/id-jag-mcp

要實際跑起來，需要準備 mTLS 憑證、以及一個可連線的 Athenz ZTS 和上游 API server，設定完全透過環境變數：

mkdir -p certs
cp /path/to/api-mcp.crt /path/to/api-mcp.key /path/to/ca.crt certs/

export UPSTREAM_BASE_URL=http://localhost:14443
export AUTHORIZATION_SERVER_URL=https://athenz-zts-server.athenz:4443/zts/v1

go run ./cmd/id-jag-mcp

啟動後除了 /mcp 這個給 MCP client 連線的 endpoint，也提供了跟三個工具對應的 REST 快捷路由，方便用 curl 直接測試，不需要透過 MCP client：

curl -H "Authorization: Bearer $AT" http://localhost:8101/api/docs

curl -X DELETE -H "Authorization: Bearer $AT" http://localhost:8101/api/docs/5

curl -X POST -H "Authorization: Bearer $AT" -H "Content-Type: application/json" \
  -d '{"name":"doc1","content":"hello"}' \
  http://localhost:8101/api/docs

如果只是想確認邏輯本身有沒有寫對，不需要真的架一套 Athenz/Keycloak 環境——測試全程用 httptest 模擬 ZTS 跟上游 API：

go build ./...
go vet ./...
go test ./...

例如 internal/athenz 的測試會起一個假的 ZTS server，驗證送出去的 grant_type、subject_token、scope、audience 這些參數是否正確；internal/tools 的測試則會驗證每個工具轉發給上游時，帶的是「交換後窄化的 token」而不是原始收到的那個。這樣不需要真的連上 Athenz，也能確認整條 token 交換邏輯是對的。

README 裡（中英文都有）有完整的環境變數清單跟更多細節。

結論

ID-JAG 解的不是「這個 client 是不是它自己說的那個 client」（這是 PKCE 的問題），而是「這個非人類的服務身份，有沒有資格代表某個特定的人，在當下做這一件特定的事」。撐起這套架構的不是文件上的約束，是把 RFC 8693 跟 RFC 7523 這兩個標準串成一條鏈，讓每一跳都被強制重新驗證、重新窄化權限。

如果你的 AI Agent 已經開始接觸內部系統，這是很值得花時間搞懂的一套架構——而且不一定要照抄 Athenz 這一套，重點是理解「每一跳都要重新換發、範圍要越換越窄」這個核心原則，套用到自己的授權伺服器上。

[GCP 實戰] LINE 名片 Bot 再進化：用 Gemini 一次搞定名片正反面辨識合併

Wed, 22 Jul 2026 00:00:00 +0000

痛點：一張中文名片，其實是兩張名片

台灣的名片有個很常見的設計：正面印中文，背面印英文（或反過來）。我們的 LINE 名片 Bot 原本的邏輯很單純：收到一張圖片，OCR 一次，存一筆資料。

問題就出在這裡。使用者傳正面，Bot 存了一筆只有中文姓名的資料；如果使用者接著把背面也傳過去，Bot 會把它當成「另一張新名片」，同一個人在資料庫裡就會出現兩筆各缺一半資訊的紀錄。使用者得自己手動比對、刪除重複資料，體驗非常糟。

這篇文章記錄我們如何讓 Bot 學會「這是同一張名片的兩面」，並且把正反面資訊合併成一筆完整資料。

解法：先問一句「還有背面嗎？」

比起自己寫規則去猜兩張圖片是不是同一張名片，我們選了一個更直接的做法：問使用者。

流程設計如下：

使用者傳送名片正面，Bot 照常 OCR。
OCR 完成後，Bot 不馬上存檔，而是回覆一句「📇 已辨識正面資料，這張名片還有背面嗎？」，並附上兩顆 Quick Reply 按鈕。
使用者按「沒有，直接儲存」→ 照原本流程存檔，結束。
使用者按「有背面」→ Bot 記住剛剛那張正面圖片，等待下一張圖片進來。
背面圖片一到，兩張圖片一起送進 Gemini，合併成一筆資料再存檔。

這個等待狀態我們用專案原本就有的 user_states 記憶體字典來管理，並且加上 5 分鐘的逾時：使用者按了「有背面」卻不理它、跑去做別的事，5 分鐘一過就當作放棄，不會卡住整個流程。

user_states[user_id] = {
    'action': 'pending_backside_confirm',
    'card_obj': card_obj,
    'front_image_bytes': image_content,
    'expires_at': time.time() + PENDING_BACKSIDE_TIMEOUT_SECONDS
}

核心：讓 Gemini 一次看兩張圖，自己做合併

最關鍵的技術決定是：要不要分兩次辨識正面、背面，再自己寫程式合併？我們選擇了另一條路，把正反面圖片包在同一次 generate_content 請求裡，直接交給 Gemini 判斷。

原因很簡單：中英文姓名要合併成「王大明 David Wang」這種格式，靠字串規則去兜很容易兜得又醜又不準；但這種語意層級的整合，靠規則去湊反而更容易出錯，交給 Gemini 直接判斷比較省事。

在 app/gemini_utils.py 中新增了 generate_json_from_two_images，沿用既有的 NAMECARD_SCHEMA 結構化輸出，只是這次 contents 塞了兩個圖片 Part：

def generate_json_from_two_images(
        front_img: PIL.Image.Image,
        back_img: PIL.Image.Image,
        prompt: str) -> object:
    model = GenerativeModel(
        "gemini-3-flash-preview",
        generation_config={
            "response_mime_type": "application/json",
            "response_schema": NAMECARD_SCHEMA
        },
    )
    front_part = Part.from_data(
        data=pil_to_bytes(front_img), mime_type="image/jpeg")
    back_part = Part.from_data(
        data=pil_to_bytes(back_img), mime_type="image/jpeg")
    response = model.generate_content(
        [prompt, front_part, back_part],
        stream=False,
        labels={"client_id": "namecard"}
    )
    return response

Prompt 也只是在原本的 IMGAGE_PROMPT 後面多加一段合併指示：

DOUBLE_SIDED_IMAGE_PROMPT = IMGAGE_PROMPT + """
這兩張圖片是同一張名片的正面與背面，請整合成一筆完整資料。
若同一欄位中英文都有出現（如姓名、公司），請合併呈現
（例如「王大明 David Wang」）；
若某欄位只有一面出現，直接採用該面的值；忽略明顯重複的資訊。
"""

一次 API 呼叫，換來的是完全不用自己寫合併規則、也不用維護那套規則。

容易忽略的兩個小坑

功能上線前的整體 code review，抓到兩個很容易被忽略、但真的會咬人的細節。

坑一：重複檢查的時機點

原本的重複檢查（比對 email 是否已存在）是 OCR 完馬上做。但雙面辨識上線後，如果正面剛好跟舊資料的 email 重複，這時候就提早判定「已存在」並結束流程，那背面圖片裡如果帶有新的 email，就再也沒有機會被看到了。

修法是把重複檢查往後挪，統一放到「單面選擇不合併」或「雙面合併完成」之後才做，確保永遠是拿最終版本的資料去比對：

async def _finalize_and_save_card(card_obj, event, user_id) -> None:
    existing_card_id = firebase_utils.check_if_card_exists(card_obj, user_id)
    if existing_card_id:
        # ... 回覆已存在
        return
    card_id = firebase_utils.add_namecard(card_obj, user_id)
    # ... 回覆儲存成功

單面流程、雙面合併流程最後都收斂呼叫這個共用函式，重複檢查只會在資料底定的那一刻執行一次。

坑二：清狀態不能一路清到底

user_states 這個字典其實同時被好幾個功能共用：編輯備忘錄、修改欄位、這次的背面辨識都會往裡面寫東西。一開始的實作圖方便，只要偵測到殘留狀態就整個刪掉再處理新事件。

問題是：如果使用者正在「編輯電話欄位」等你輸入新號碼，這時候手滑傳了一張圖片，這段邏輯會把 editing_field 的狀態也一起清掉，使用者原本的編輯操作就這樣被默默取消了。

修法是只清跟背面辨識流程相關的兩個狀態，其他狀態一律不碰：

if state.get('action') in (
    'pending_backside_confirm', 'awaiting_backside_image'
):
    del user_states[user_id]

同樣的邏輯後來也發現漏掉了一個分支，處理「操作已過期」回覆的地方一開始也是整個清掉，統一改成一樣的選擇性判斷後才算真正補齊。

順手做的資源清理：別讓背面圖片一直留在記憶體裡

awaiting_backside_image 狀態裡存的不只是文字，還有正面圖片的原始位元組資料。如果使用者問完「還有背面嗎」就人間蒸發，這包資料理論上會一直留在 process 記憶體裡，因為原本的設計只有「使用者下次互動」才會順便檢查並清掉逾時狀態。

我們加了一個 sweep_expired_states()，掛在 Webhook 進來的第一時間執行一次，把所有使用者裡已經過期的暫存狀態清掉，不用等到當事人自己回來才被動清理：

def sweep_expired_states() -> None:
    now = time.time()
    expired_user_ids = [
        user_id for user_id, state in user_states.items()
        if 'expires_at' in state and state['expires_at'] <= now
    ]
    for user_id in expired_user_ids:
        del user_states[user_id]

只要任何一個使用者傳訊息進來，就會順便幫全體使用者做一次垃圾清理，讓放棄流程的人不會留下永久佔用記憶體的殘骸。

總結與效益

這次的雙面辨識合併功能，讓 LINE 名片 Bot 更貼近台灣使用者真實的名片使用習慣：

一次辨識，資料完整：正反兩面一次送進 Gemini，中英文欄位自動合併，不用再手動比對重複資料。
不打斷使用者：忽略提示、逾時、臨時去做別的事，都能自然退回單面儲存，不會卡住流程。
重複檢查對準最終資料：確保比對的永遠是合併後的完整版本，不會漏接背面才出現的新資訊。
狀態機互不干擾：背面辨識的暫存狀態只影響自己，不會誤傷使用者正在進行的其他操作。
記憶體用得乾淨：主動清掃逾時狀態，放棄流程的使用者不會留下看不見的記憶體負擔。

完整程式碼已同步推播至 GitHub，歡迎參考！

[好書分享]台灣AI大未來解析最新的AI趨勢、台灣情勢、企業布局與個人發展

Sat, 18 Jul 2026 00:00:00 +0000

台灣AI大未來
解析最新的AI趨勢、台灣情勢、企業布局與個人發展
作者： 簡立峰（Chien Lee-feng）  蕭玉品  
出版社：商業周刊 

買書推薦網址：

Readmoo: 由此去購買。

前言:

這是 2026 年第 2 本讀完的書。這大概也是蠻新的一本書，就是 2025 年底才出的一本書，那時候會買這本書因為就是公司在 2024 年有邀請簡立峰來公司演講，後來偶然在電子書櫃上看到他出的書，就想說來看一下。

大綱

當AI改寫世界，台灣下一步怎麼走？
Google台灣區前董事總經理、電腦科學暨人工智慧學者──簡立峰
為台灣撰寫第一本AI時代的使用說明書，
讓台灣人看懂AI時代的機會與挑戰！

世界每十年就歷經一次數位革命：
●1990年，個人電腦開啟電腦世代；
●2000年，網際網路造就網路世代；
●2010年，行動裝置與社群媒體引領行動世代；
●2020年，生成式AI如ChatGPT震撼登場……
如今正是AI世代，遊戲規則全面改寫，差距正在1：99間急遽擴大。
你會落後被淘汰，還是把握機遇、成為1%的贏家？
本書帶你洞悉AI格局，掌握關鍵轉型之鑰！

【地緣政治下的AI發展】
當全球正經歷一場由AI驅動的典範轉移，美國將AI視為其重返霸權的關鍵，這不僅預示著AI產品化將徹底顛覆世界的運行規則，更開啟了未來AI演變的無限可能。從「曼哈頓計畫」到「星際之門」的深遠布局，本書將深入剖析美中關稅戰下的全球局勢，洞察AI如何重塑國際秩序。
●1：99的挑戰，抓住機會的國家、企業、個人，都有可能會成為獨一無二、遠超他人的「1」，其他人則成了遠遠落後的「99」。
●DeepSeek的出現，顛覆了美國壟斷的現象，帶來AI世界的「再平衡」，等於發明了窮人的原子彈。
●如果不加快晶片國產化的腳步，不具生產力的美國就沒有明天，直接在AI戰役中喪失競爭力，台積電因而成了美中對抗的X因子。

【放眼世界的台灣】
AI浪潮席捲全球，這不只是技術革新，更是國家發展的關鍵轉捩點。身處這股巨浪中，台灣不僅擁有得天獨厚的「護國神山」台積電，更在AI挑戰與機會並存之際，看到成為「世界的台灣」的黃金十年。本書帶你一窺台灣製造業的未來潛能，以及新舊企業如何重新定調「台灣製造」。
●面對地緣政治變局，以製造業為主的台灣企業要順勢而為，透過海外生產，在台研發打造「台灣＋N（外國）」模式，協助台灣去除紅色供應鏈、加入美系供應鏈的一環。
●海島的市場永遠在外面，你飛去日本、飛去美國旅遊、出差幾天不等於國際化，國際化是每天的生活受不同文化衝擊。

【百工百業的AI實踐】
AI時代是企業轉型、人才再造的關鍵時刻，敢於轉向的企業才有競爭機會。本書例舉許多不同業種企業如何因應AI的案例，並提供實用的對策方向，引導台灣企業轉型搶占AI市場，邁向成長與創新。
●AI的影響可比喻成「大風吹」，從科技巨擘到中小企業，不論是騰籠換鳥，還是為員工賦能，風往哪裡吹，新的機會就在那裡。
●「老創＋新創」從軟體整合轉向軟硬整合，結合二者優勢，AI應用才有可能。
●發展主權AI並非外包出去就結束了，不論是自建模型、請科技巨頭幫忙，要把策略規畫得清清楚楚，否則恐怕只是白花錢。

【掌握個人學習、職涯的黃金鑰匙】
身為AI世代的一分子，如何利用AI提升學習效率，同時清晰辨識AI的極限，是AI時代的重要課題。本書建議如何善用AI工具的同時，也點出人類的差異化經驗將成為無可取代的稀世珍寶，因此聰明地累積個人獨特價值，才能讓自己在AI時代立於不敗之地。
●AI喜歡用某些特定句型，究其原因在於AI是機率概念，自然有些規律在裡頭，但反過來說，正因為它資料量夠大，才能試出各種人類沒見過的組合。
●AI將許多工作的「及格線」從60分一舉提高到80分，迫使各行各業必須重新定義人力的核心職能和價值。
● AI時代，具備專業基礎的資深人才學AI最快，因為他們長期累積的知識能判斷AI生成內容的正確性，這次AI的典範轉移，反過來將老一世代的優勢給放大了。

這是一本專為台灣量身打造的AI生存指南，幫助你全面掌握AI變革的脈絡，找到國家、企業與個人在變局中的成長之道。

這本書可以說是 Google 台灣前董事總經理簡立峰博士與資深媒體人蕭玉品，聯手為台灣人與企業量身打造的「AI時代生存說明書」。簡博士用非常務實、精準的在地視角，剖析了在這波瘋狂的 AI 浪潮下，台灣該如何重新定位、企業如何打出軟硬整合的國際盃，以及每個人該如何避免陷入「大腦外包」的危機。

我為你將全書的四大核心架構整理出來，先透過這個概覽掌握整體脈絡：

全書四大核心架構概覽

面向分類	核心痛點與趨勢	台灣與個人的突圍戰略
1. 最新AI趨勢	AI 帶來高度的集權與統一，可能演變成 1:99 的能力與資源懸殊；不過 DeepSeek 等新興勢力的崛起，也正為全球帶來「再平衡」的機會。	理解 AI 的「機率與語言架構」本質，從中尋找非美系壟斷的突破點，拉高基本能力下限。
2. 台灣情勢定位	台灣雖是地緣政治與 AI 晶片的關鍵 X 因子，但也面臨島嶼內捲、少子化與五缺的結構性限制。	將「農民心態」徹底轉向「航海家心態」，以出海為唯一生存王道，跨出台灣邊界擴大數位國土。
3. 企業轉型布局	台灣「硬體極強、軟體極弱」，缺乏算力與商業情境的軟體新創很難獨立在國際存活。	推動「老創（硬體大廠）＋新創（軟體應用）」攜手，利用 Edge AI（邊緣AI）為強大的硬體裝置裝上大腦。
4. 個人發展鑰匙	面臨「大腦外包」的無形危機，只會照書教、缺乏實戰經驗的平庸專業新鮮人將首當其衝。	從「解題式」慣性轉為「出題式」思維，透過與 AI 進行高頻次的「反覆互動與修正」來創造獨特價值。

一、最新AI趨勢：1:99 的「超級人類」大挑戰

極端的權力集中：AI 時代帶來了高度的中央集權，全球科技巨頭佔據極大優勢。全球數千種語言中，僅有約百種能在主流 AI 中使用，且英文與簡體中文被深度優化，這代表語言與文化架構是掌握 AI 的第一關鍵。
1:99 的分水嶺：這波海嘯最殘酷的不是消滅底層普通人（AI 反而能拉高普通人的下限），而是消滅「平庸的專業人士」。抓住機會的 1% 人會因為 AI 變身超級人類，拿走 99% 人的能力與機會，其他人則成了落後的 99%。
AI 世界的再平衡：近年非美系低成本高效模型的出現，打破了美國科技巨頭的絕對壟斷，這被形容為發明了「窮人的原子彈」，為資源較少的國家與企業帶來重新洗牌的契機。

二、台灣情勢：從「海島內捲」轉向「大航海時代」

地緣政治的 X 因子：台積電與台灣硬體供應鏈在美中科技對抗中高居關鍵地位，因為台灣具備「最早知道需求」的特性（例如能率先掌握伺服器電壓變化等系統需求），在全球基礎設施的調整中擁有重要身分。
打破農民心態：多數台灣企業習慣了「海島思維」，日常生活中「看不見海」，容易在舒適的同溫層中陷入內捲。面對未來 20 年少子化、新生兒暴跌的結構性危機，簡博士疾呼必須轉向「航海家心態」，因為「出海」已是台灣各行各業唯一的生存之道。
數位國土的延伸：以台積電為例，AI 能讓台灣在海外複製工廠後，由台灣工程師進行遠距操作；台灣也應將高齡化、勞動力短缺的危機轉為機會，積極發展機器人與屬於自己的主權 AI，避免國家級的數位落差。

三、企業布局：軟硬整合，讓「老創＋新創」攜手共舞

用 Edge AI 幫硬體裝上大腦：Edge AI（邊緣AI，指讓終端裝置具備在地運算能力，不全依賴雲端）是台灣的天下。台灣純做軟體新創很難拼過國際巨頭，但我們可以把 AI 服務直接內建、綑綁在全世界都在用的強大硬體裝置中（如捷安特的自行車或各種終端設備），大幅提升附加價值。
老創加新創打國際盃：現在的 AI 新創如果沒有富爸爸提供的數據、算力和真實的「商業情境」，幾乎不可能成功。因此，硬體大廠（老創）應該攜手軟體新創，結合老創的國際通路與新創的靈活應用，一起組隊出海打國際盃。
主權 AI 的務實規劃：發展主權 AI 不能只是盲目把業務外包給科技巨頭。企業不論是自建模型還是與大廠合作，都必須把自身的策略、場域應用規劃得清清楚楚，否則只是平白燒錢。

四、個人發展：拒絕「大腦外包」，做高段位的「出題者」

思維從「解題」變「出題」：AI 的能耐都是被「問」出來的，問題越專業，得到的回應就越準確。未來職場不再看重死記硬背，核心能力將轉向問題定義、思辨與方向掌控，能展現主動影響力的「出題者」才能勝出。
利用「反覆迭代」深化學習：如果只是把問題丟給 AI、一次取得答案就直接複製使用，這種行為等同於抄襲；但如果能跟 AI 來回修改 10 次，那是「學習」的過程；若是持續反覆修正與調整到 100 次，才是真正接近「創造」的層次。
累積不可取代的「差異化經驗」：記憶與計算這些功能都可以外包給 AI，但你個人的獨特經驗、跨領域協作能力（π型人才）以及人類的思辨力，才是 AI 時代無可取代的稀世珍寶。聰明地利用 AI 工具放大自己的產出，才能避免成為被時代淘汰的「失落一代」。

本書最核心的靈魂金句：

「改變是人類永遠的不安，但若從宏觀角度看，AI 帶來的，是讓人類更有能力的契機。」當計算與記憶被大腦外包時，請務必保留住自己思考與創造的力量。

這支簡立峰博士專訪：誰是AI時代失落的一代影片深入探討了書中提及的「1:99 超級人類挑戰」與職場思維轉型，能幫你更直觀地理解如何在這個大腦外包的時代保留個人競爭力。

心得

就我自己的心得來說，這一本書整理得蠻多近期國內外的 AI 發展過程。並且以簡立峰自己曾經身為 Google 前任總經理的相關經歷給予許多未來的看法。並且許多時候分享了 AI 時代下，各行各業應該要如何面對給予的一個建議。這個部分之前在他的演講中也經常會提到，並且也有相當清楚的分享與說明。

就自己的感受來說，這部分的書籍可能翻一下就好。比較起來還是比較喜歡簡立峰博士帶來的演講部分，會讓人有更多的震撼與觸發。

[好書分享]蔡桑說怪 - 日本神話與靈界怪談，有時還有臺灣

Fri, 17 Jul 2026 00:00:00 +0000

蔡桑說怪
日本神話與靈界怪談，有時還有臺灣
 共 73 人評分
作者： 蔡亦竹  出版社：圓神出版 

買書推薦網址：

Readmoo: 由此去購買。

前言:

這是 2026 年第 1 本讀完的書。今年上半年都沒有寫讀書心得，因為許多書籍都只有看一點點。這一本書也讀了蠻久的，是在找書的時候偶爾看到這一本書，結果整本書到了後半段卻是相當的好看，我一口氣最後就看完。

大綱

沒有最ㄎㄧㄤ，只有更ㄎㄧㄤ！蔡亦竹a.k.a.民俗學中二教授的鬼話連篇大解放！

◆日本初代神明家庭是如何天天上演八點檔狗血劇？
◆日本神話是怎麼把各種「性隱喻」藏在故事裡？
◆妖怪不是統統都是害人精，哪些妖怪可以讓你發大財、上天堂？
◆妖怪界裡也有霸凌現象？只是變老變醜就可以是一種妖怪？
◆玉皇大帝其實不是CEO？觀世音菩薩其實是外籍人士？
◆臺灣也可以有「師公手錶」「妖怪寶可夢」？

臺灣人怕鬼，日本人怕鬼，全世界的人都怕鬼……
沒有看過《鬼話連篇》沒關係，來這裡聽蔡桑練肖話、說鬼神，讓你心裡不再「毛毛der」！

大多數人對日本的印象是──參拜不完的寺廟、超萌超宅的coser、AV女優……威！一定還有靈異故事、貞子、妖怪，以及各種都市傳說！

聽蔡桑如何把毛骨悚然的撞鬼經驗結合流傳千古的歷史故事，看蔡桑如何用超接地氣語法，揭露日本神話背後的文化意涵！

日本民俗學博士蔡亦竹集結多年對民俗學的研究，以神話鬼話做媒介，用輕鬆易懂的鄉民語言，帶讀者進入日本的「神鬼傳奇」。其中包括日本神明的家譜、妖怪與文化的關聯以及其中所蘊藏的寓意等，同時也讓臺灣的眾神明可以臺日友好大串聯地活躍於文字中，讓你懂鬼話、迷鬼神！看完保證媽媽還會問你，為什麼要跪著看這本書？

因為《蔡桑說怪》會讓你跪地大喊：「日本神話到底是嗑了什麼？我也想要來一點！」

這本書可不是那種硬梆梆的學術論文，而是筑波大學民俗學博士蔡亦竹（蔡桑），用超接地氣的「鄉民用語」與爆笑風格，把日本神話和靈界怪談扒開給你看的文化解析書！最精妙的是，他不僅講日本，還會時不時拉回臺灣的民俗視角做對比。

以下為你精煉出這本書的三大核心板塊與重點整理：

核心三大板塊重點整理

板塊分類	核心研究焦點	蔡桑的「台味白話解讀」與亮點
1. 日本的神話原型	日本初代神明家庭（伊邪那岐、伊邪那美、天照、須佐之男）的誕生，以及歷史上的怨靈信仰。	用「色情與暴力、獵奇與SOD大集合」來吐槽日本神話極度放飛自我的荒謬劇情。介紹日本古代史的「怨靈同好會」及天狗等特有種。
2. 妖怪與都市怪談	鄉野鬼怪如何隨著時代演變成現代的都市傳說（如裂口女、超高速阿婆）。	妖怪是「都市化的新寵物」，背後折射出的是現代人的集體焦慮、孤單，以及媒體對靈異風潮的推波助瀾。
3. 有時還有臺灣	臺灣與日本之間信仰的跨海交涉與文化對照（如長崎媽祖與台南飛虎將軍）。	展現「臺日友好大串聯」。透過觀看日本的怪談，反思臺灣人自己的文化根源與主體性。

一、日本神話：比本土劇還超展開的第一家庭

初代家庭的愛恨情仇：日本的創世神明（伊邪那岐與伊邪那美）決裂過程荒謬又驚悚（老婆在黃泉變腐屍、老公嚇到逃跑離婚），後代的太陽神天照大神和弟弟須佐之男也是相愛相殺。蔡桑笑稱這些情節放到現代來看，簡直是種種驚悚與獵奇情節的大集合。
怨靈同好會：日本歷史上許多被膜拜的高階神明（如學問之神菅原道真、崇德天皇），其實生前都是「死得很慘的政治鬥爭受害者」。因為後人害怕他們變成怨靈報復，才趕緊蓋神社把他們當神拜，形成了日本獨特的怨靈信仰文化。

二、妖怪與都市傳說：現代人的集體焦慮

妖怪是都市的新寵物：以前的妖怪（如河童、山姥）住在深山樹林，代表人類對大自然的敬畏；都市化之後，妖怪也「搬進城裡」，演變成裂口女、超高速阿婆等都市怪談。
反映現實社會的孤獨：這些現代怪談的誕生，表面上是恐怖故事，骨子裡其實折射出都市人的疏離感與集體焦慮。同時書中也回顧了八〇、九〇年代日本大眾媒體（電視靈異節目）為了收視率推波助瀾的「靈異熱潮興衰史」。

三、有時還有臺灣：臺日神鬼的奇妙連結

講日文的媽祖與日本神明：書中特別提及臺日信仰的交織。例如日本長崎有多間媽祖廟，那裡的媽祖因為在地化而會「說日文」；而臺灣台南則有「飛虎將軍廟」，供奉的是二戰時為了保護臺灣村民而犧牲的日本飛行員杉浦茂峰。
民俗學的本質是「人的研究」：蔡桑強調，無論是研究日本神話還是臺灣的靈異現象，恐怖或荒謬的終究不是鬼怪，而是背後的人類社會。信仰能撫慰人心，是因為它反映了當代人的思考邏輯。

本書核心精神金句：

「了解人就會理解鬼，妖怪、幽靈都是依據現實的想像。」

我們必須去發現每一個現象背後為何形成的主因。當我們透過日本怪談這面鏡子，深刻理解了民俗傳說的運作，才能帶著更清晰的眼光，回頭發現並認同屬於「臺灣自己」的文化形貌。

心得

這一本書是充滿了相當多的鄉間傳奇，並且最後跟著一篇他的研究報告與實際發生過的事情會讓你覺得驚訝萬分。首先整本書會開始分享著日本鬼怪的一些故事，並且去思考著許多日本神話背後鬼怪故事由來。並且也會根據著日本色情與暴力跟他們許多鬼怪故事的牽連。

第二話就一些台灣相關故事的分享，並且也會講到「膽大黨」裡面的超高速婆婆的由來，裂嘴女的相關故事。這些都會讓你很想要一口氣閱讀完。隨著最近好像鬼月又要到了，似乎這一系列的書又會變得開始熱門。大家也也可以看看。

[數位憑證皮夾] 進階版 - 打造「訪客背書發證」：一個同時當驗證方與發行方的 DID 全鏈應用（附開發踩坑紀錄）

Wed, 08 Jul 2026 00:00:00 +0000

(圖片來源：數位憑證皮夾官方網站)

前提：

上一篇入門版做了一個 HR 員工卡系統：同仁自己申請一張員工卡，然後拿它去申請「運動補助」跟「育兒補助」。那一篇的重點是「發卡（Issuer）」跟「驗證（Verifier）」兩個角色分開來看。

這一篇想再往前走一步：如果一個場景要同時扮演驗證方跟發行方，串成一條完整的 DID 生態鏈，會長什麼樣子？我挑的場景是「訪客背書發證」——這也是我在腦力激盪五個檢驗方應用時，覺得最能展示「全鏈」的一個。

順便，這篇會很誠實地把開發過程中踩到的三個坑寫下來，因為那些才是 TIL 真正有價值的部分。

程式碼在這裡：https://github.com/kkdai/did-usecase-visitor 線上體驗：https://did-usecase-visitor-660825558664.asia-east1.run.app

場景：員工門禁 + 訪客背書發證

這個大廳證件台有兩個模式：

員工門禁 / 活動報名：員工用數位皮夾出示員工卡，系統只驗證「是不是有效員工」，驗過就開門 / 報名成功。姓名、生日、子女數這些欄位一律不揭露，留在皮夾裡——這就是選擇性揭露。
訪客背書發證（這篇的主角）：由一位在職員工出示員工卡「背書」，驗證通過之後，系統當場核發一張帶到期時間的臨時訪客通行證到訪客的皮夾。

第二個模式的價值在於，它把兩個角色接起來了：

先當 Verifier（驗員工卡）→ 驗過才當 Issuer（發訪客卡）

比起傳統的紙本訪客簿（抄身分證、押證件影本、一堆個資堆在櫃台還要人工回收），數位背書只留下「哪位員工背書」這一筆可追責的資訊，訪客資料留在訪客自己的皮夾，通行證還可以設到期時間。

架構決策：為什麼不直接改上一個專案

這次我開了一個全新的專案、部署到獨立的 Cloud Run 服務，而不是在原本的 HR 專案上加頁面。幾個考量：

靜態前端 + JSON API：原專案用 jade 樣板 server-side render，這次改成 public/ 靜態頁 + 幾支 JSON API（/api/access/qrcode、/api/access/status），前後端分得比較乾淨。
把皮夾 API 呼叫抽成 lib/wallet.js：原專案的 issuer / verifier 呼叫是內嵌在路由裡、而且重複。這次抽成三個函式：requestPresentationQRCode()、getPresentationResult()、issueCredential()，好維護也好測。
狀態改用記憶體：原專案把資料寫進單一 record.js 檔案，在 Cloud Run 這種無狀態環境上寫檔會有問題。這次用簡單的記憶體物件（重啟歸零，展示用途足夠）。
權杖沿用同一個沙盒帳號：issuer / verifier 的 access token 跟上一篇是同一組，直接重用。

驗證「持有員工卡」的部分，我先沿用既有的運動補助 verifier ref 當 fallback（VERIFIER_ACCESS_REF 沒設就用 VERIFIER_SPORT_REF），這樣不用等後台設定就能先跑起來。

踩坑紀錄一：出示成功了，畫面卻一直卡住

這是最經典的一個。手機掃碼、皮夾也完成出示了，但桌面的頁面就是不往下走，一直在輪詢。

第一步先看 Cloud Run 的日誌，發現 /api/access/status 每 3 秒回一次、每次都回「未驗證」。我在後端加了一行把驗證方原始回應印出來的 log，重新部署後再測一次，就抓到真相了：

{
  "data": [
    {
      "credentialType": "0028680530_line_school",
      "claims": [
        { "ename": "english_name", "cname": "英文名字", "value": "Lub" },
        { "ename": "join_company", "cname": "入職時間", "value": "2018-10-05" }
      ]
    }
  ],
  "verifyResult": true,
  "resultDescription": "success",
  "transactionId": "8cd7f37b-..."
}

看到問題了嗎？回應裡的欄位是 verifyResult（camelCase），而且根本沒有 code 這個欄位。但我沿用上一篇的舊寫法，判斷式是：

// 舊的（對不上現在的回應）
const verified = data.code === 0 && data.verify_result === true;

data.code 是 undefined、data.verify_result 也是 undefined（人家叫 verifyResult），所以永遠 false，永遠 pending。其實驗證早就成功了（verifyResult: true、resultDescription: "success"），只是我判斷的欄位名對不上——看起來沙盒 API 的回應格式已經從 snake_case 換成 camelCase 了。

修法就是把判斷式改成相容兩種格式：

const verified =
  data.verifyResult === true ||        // 新格式 camelCase
  data.verify_result === true ||       // 舊格式相容
  (data.code === 0 && data.verify_result === true);

TIL：接第三方 API，不要相信「上一版能動的判斷式這一版也能動」。沙盒會改。加一行印出原始回應的 log，比對著改，比盯著程式碼猜半天快多了。

踩坑紀錄二：訪客卡一直「待發」

門禁那關通了之後，換訪客背書那關卡住——畫面顯示「訪客卡待發（issuer 樣板未設定）」，沒有真的發出一張卡。

我直接拿 curl 打發卡 API /api/vc-item-data 來看它到底回什麼。分兩種情況測：

情況 A：用員工樣板 + 正確的員工欄位 → HTTP 200，而且完整回應裡有這些 key：

KEYS: [ 'id', 'content', 'pureContent', ..., 'qrCode', 'deepLink', 'expired', ... ]
qrCode   = data:image/png;base64,iVBOR...      ← 真的能掃進皮夾的領卡 QR
deepLink = https://frontend-uat.wallet.gov.tw/api/moda/vcqrcode?...
expired  = 2027-01-09T...

情況 B：用員工樣板 + 訪客欄位（visitor_type、endorsed_by…） → HTTP 500 / 400 BAD_REQUEST。

原因很清楚了：員工樣板的欄位是 isRequired: true（姓名、英文名字…），我卻送了一堆它沒有的訪客欄位，就被打槍。而發卡成功時的回應其實就帶了 qrCode 跟 deepLink，可以直接讓訪客掃碼領卡——我原本的解析是對的，卡關的純粹是「欄位對不上樣板」。

於是我設計了兩種發卡模式，用環境變數自動切換（程式裡的 HAS_VISITOR_TEMPLATE）：

模式	條件	行為	卡面
Option 1（fallback）	沒設 `VISITOR_VC_*`	借用員工樣板，把訪客資訊塞進它的必填欄位（姓名=「臨時訪客」等）發卡	顯示為員工卡卡面
Option 2（正規）	有設 `VISITOR_VC_*`	送 `visitor_type / endorsed_by / valid_until` 到專屬訪客樣板	正規訪客通行證卡面

Option 1 的好處是不用等後台設定就能發出一張真的能領的卡（雖然卡面是借來的），先把整條鏈跑通；要正規卡面再走 Option 2 建專屬樣板即可，程式碼一行都不用改。

踩坑紀錄三：領卡 QR 太小 + 手機版面

第一版我把訪客通行證做成一張漂亮的小識別證，領卡 QR 只有 48px——結果就是根本掃不到。這個 QR 是要給「另一支手機」掃來領卡的，太小就失去意義。

後來把訪客證改成直式卡片，領卡 QR 放大成卡片主體（最大 240px、白底留白），下面才放「背書員工 / 有效至」的資訊。兩個 QR（出示用、領卡用）也都改成 clamp() 響應式尺寸，手機上不爆版、桌機上夠清楚。

TIL：只要是「給別人掃」的 QR，就要當成主角來排版，不能當裝飾。

關於「限時自動失效」的真相

我原本以為可以逐張指定「這張訪客證 4 小時後過期」，但實測發現：透過 /api/vc-item-data 發卡，卡片的實際有效期是跟著樣板設定走的（例如員工樣板是發卡日 +約半年），沒辦法一張一張指定短效期。

所以現在卡面上的「有效至 HH:MM」是應用層自己算的顯示值，不是皮夾強制的到期。如果要真正的短效訪客證，有兩條路：

建立訪客樣板時，把樣板的有效期直接設短。
或改用平台的排程撤銷（revoke）——發卡回應裡有 clearScheduleId、scheduleRevokeMessage 這些欄位，暗示平台支援排程撤銷，但要另外串接對應 API。

部署：從原始碼直接上 Cloud Run

這次用 buildpacks 從原始碼直接部署，不用自己寫 Dockerfile：

gcloud run deploy did-usecase-visitor \
  --source=. --region=asia-east1 --platform=managed --allow-unauthenticated \
  --set-env-vars="VC_SERNUM=607861,VC_UID=0028680530_line_school,\
ISSUER_ACCESS_TOKEN=...,VERIFIER_SPORT_REF=...,VERIFIER_ACCESS_TOKEN=...,\
VISITOR_TTL_HOURS=4"

之後要切換到 Option 2 的正規訪客卡，只要在這串 --set-env-vars 補上 VISITOR_VC_SERNUM=<新樣板 vcId>,VISITOR_VC_UID=<新樣板 vcCid> 重新部署即可， HAS_VISITOR_TEMPLATE 會自動變 true。

總結與未來展望

這次的重點不是「又做了一個 demo」，而是三件事：

DID 全鏈是可行的：同一個場景同時當 Verifier 跟 Issuer，驗過一張卡再發一張卡，把生態鏈接起來，體驗上很順。
踩坑都在細節：欄位命名（verifyResult vs verify_result）、樣板必填欄位、QR 尺寸——這些不看原始回應、不實際用手機掃，是不會發現的。
fallback 設計讓 demo 先能動：不用等後台把每個樣板 / ref 都建好，先用既有資源跑通，再逐步換成正規設定，開發節奏會好很多。

數位憑證皮夾能做的應用場景真的很多，「訪客背書」只是其中一個。上一篇的員工卡，其實還可以延伸出福利社優惠核銷、年資里程碑禮、親子設施門禁、健身房積點……每一個都是一個「檢驗方」的新應用。很期待看到更多有創意的場景被做出來。

[GCP 帳單與 Vertex AI] 破解單一專案 Gemini 費用拆分難題：Vertex AI 動態計費標籤 (Labels) 實戰記

Tue, 07 Jul 2026 00:00:00 +0000

痛點：同一個專案內的 Gemini API 費用如何精準分攤？

在開發企業級 LLM 服務或是經營多租戶 (Multi-tenant) 平台時，最常被財務與維運團隊問到的問題就是：

「我們同一個 GCP 專案內接了許多不同的業務與 LINE Bot，每天的 Gemini Key 費用都會統統出現在 Gemini API 的範圍，我們有辦法根據不同的 Gemini Key 或不同的使用者來拆分費用嗎？」

直接回答你的問題： 在 Google Cloud 帳單（Cloud Billing）報告中，無法直接「根據不同的 API Key 金鑰名稱」來分開顯示費用。 Google Cloud 的帳單報表最小的歸屬維度是到「專案 (Project)」、「服務 (Service)」和「SKU (產品細項)」，系統並不會把個別的 API Key 字串當作獨立的計費項目。對帳單系統來說，同一個專案內不論你建了 10 把還是 100 把 API Key，通通都會被揉在一起算成一筆 Gemini API 的總帳。

山不轉路轉：Vertex AI 的「請求標籤 (Labels)」救星

如果因為架構限制非得塞在同一個專案，最推薦的做法就是：切換至 Vertex AI 呼叫，並使用「請求標籤 (Labels)」。

如果你目前使用的是 Google AI Studio 的 API Key，它在單一專案內是無法傳遞計費標籤的。但如果你將程式碼改為呼叫 Vertex AI 的 Gemini API（一樣在同一個專案內），Vertex AI 支援在每次發送請求時，動態帶入自訂的 labels（標籤）。

原理與流程

在每次發送請求（例如呼叫 generateContent）時，於 API Request 中帶入特定的 Metadata：

{
  "contents": { ... },
  "labels": {
    "client_id": "info_helper",
    "api_key_group": "marketing_team"
  }
}

這些自訂標籤會直接被傳遞到 GCP 的帳單系統。之後當你到 GCP 帳單報告中，在「分組依據 (Group by)」選擇你設定的標籤鍵（例如 client_id），就能在同一個專案內，把不同標籤（代表不同服務、客戶或使用者）的費用算得一清二楚！

專案實戰改造：全面導入 Labels 機制

為了完成這個需求，我們盤點了目前 LINE Bot 專案的 API 呼叫架構，並進行了以下重構。

1. 專案 API 呼叫盤點

經由掃描，我們發現專案中絕大部分都是使用 Vertex AI 進行呼叫（17 個 Client 中有 14 個使用 vertexai=True），只有少數例外：

Vertex AI 呼叫：包括 GitHub 摘要、多個 Google Maps Grounding 工具、文字摘要、圖片分析、語音轉文字等（共 11 個檔案、19 處呼叫點）。
Gemini API Key 呼叫：main.py 的 Live API、batch_service.py 的 Batch 服務，以及 tts_tool.py 的 TTS 語音合成。

[!IMPORTANT] labels 參數僅 Vertex AI 支援，若在 API Key (vertexai=False) 下帶入此參數會導致 SDK 拋出 Error，因此我們只針對 11 個使用 Vertex AI 的檔案進行修改。

2. 實作修改方式

對於 google-genai Python SDK，我們有兩種主要的修改場景：

場景 A：已包含 `GenerateContentConfig`

若原本的呼叫就帶有 Config，我們只需在 config 中額外傳入 labels={"client_id": "info_helper"}：

# 修改前 (例如 loader/gh_tools.py)
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=prompt,
    config=types.GenerateContentConfig(
        temperature=0,
        max_output_tokens=2048,
    )
)

# 修改後
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=prompt,
    config=types.GenerateContentConfig(
        temperature=0,
        max_output_tokens=2048,
        labels={"client_id": "info_helper"},  # 帶入計費標籤
    )
)

場景 B：無 Config 參數

若原本的呼叫非常簡單（例如 searchtool.py 或 youtube_gcp.py），我們需要主動帶入一個包含 labels 的 GenerateContentConfig：

# 修改前 (例如 loader/searchtool.py)
response = client.models.generate_content(
    model="gemini-3.1-flash-lite-preview",
    contents=prompt,
)

# 修改後
response = client.models.generate_content(
    model="gemini-3.1-flash-lite-preview",
    contents=prompt,
    config=types.GenerateContentConfig(
        labels={"client_id": "info_helper"},  # 新增 config 帶入標籤
    ),
)

3. 被修改的檔案清單

我們總共對以下 11 個檔案中的 19 個呼叫點進行了精準修改，並在提交前使用 Python 的 AST 模組（ast.parse）以及 Flake8 進行語法與排版檢驗：

agents/chat_agent.py：修改 _create_chat_config()，為一般問答及 Grounding 對話都加上 labels。
loader/chat_session.py：為 Chat session config 帶入 labels。
loader/gh_tools.py：GitHub 摘要 API。
loader/langtools.py：文字摘要、圖片 JSON 生成、社群貼文生成。
loader/maps_grounding.py：地圖搜尋 API。
loader/searchtool.py：關鍵字提取工具。
loader/youtube_gcp.py：YouTube 影片理解 API。
tools/audio_tool.py：異步語音轉文字。
tools/maps_tool.py：地圖附近搜尋、餐廳名稱擷取、批次與評價搜尋等 5 處呼叫。
tools/summarizer.py：文字摘要與 Agentic Vision 圖像理解。
tools/youtube_tool.py：YouTube 摘要工具。

避坑指南：小心 SDK 模組導入問題

在為 youtube_gcp.py 與 youtube_tool.py 重構無 Config 的呼叫時，由於這兩個檔案原本只使用了 named import 導入特定的型別：

from google.genai.types import HttpOptions, Part

當我們在程式碼中寫下 types.GenerateContentConfig(...) 時，系統會拋出 NameError: name 'types' is not defined 的錯誤。

解決辦法： 我們需要修正該 import 敘述，直接引入 GenerateContentConfig：

# 修改前
from google.genai.types import HttpOptions, Part

# 修改後
from google.genai.types import HttpOptions, Part, GenerateContentConfig

並在呼叫時直接使用，而不加上 types. 前綴：

config=GenerateContentConfig(labels={"client_id": "info_helper"})

總結與後續步驟

本次修改成功將 client_id=info_helper 標籤注入至 LINE Bot 專案內所有 Vertex AI API 的呼叫中。

帳單生效延遲：請注意，當我們開始帶入 labels 之後，GCP 的帳單數據通常會有 24 到 48 小時的生效延遲。
在 GCP Billing 設定：過兩天後，可以前往 GCP Console -> Billing (計費) -> Reports (報表)。在右側的 Group by (分組依據) 中選擇 Labels 並輸入我們的 key client_id。
大功告成：此時報表就會將 info_helper 當作獨立的計費列獨立繪出，完美解決了專案費用分開核銷與統計的難題！

[AI 實戰][Gemini Live Translate] 打磨 macOS 會議翻譯 App：自動重連、懸浮字幕、會議記錄匯出全面進化

Wed, 01 Jul 2026 00:00:00 +0000

寫在前面：第二回合，換一把利器

在上一篇文章中，我們用 AGY CLI (Antigravity) 從零打造了一個 macOS 即時會議翻譯 App：透過 ScreenCaptureKit 擷取 Zoom / Google Meet 的音訊，送入 Gemini Live API 進行即時翻譯，並在 App 視窗中顯示繁體中文雙語字幕。

App 上線後，開發者在實際開會中發現了幾個讓人皺眉的問題，同時也有了更多功能想法。這一次，我們換上了 Anthropic 的 Claude Code，在終端機中展開了第二回合的深度打磨。

以下記錄這場協作的完整對話流程，還原每一個關鍵決策點。

階段一：揭露隱藏危機 — 10 分鐘後自動停住的 WebSocket 謎團

App 看似完美運作，但開發者在一場真實的長會議後帶著疑問回來了：

User: 查一下這個程式碼，為什麼大概即時翻譯大概十多分鐘就會停住，幫我查看可能會有的原因。

閱讀了全部五個 Swift 原始檔，並結合內建的 Gemini Live API 技能文件，精準指出問題根源：

Gemini Live API 的 WebSocket 連線有約 10 分鐘的 Session 上限。時間一到，伺服器會主動關閉連線並送出 GoAway 信號。然而原始程式碼對這個情境毫無防備，造成三層失效：

斷線後不重連：didCloseWith 回呼只更新了 UI 上的狀態文字，沒有任何重連邏輯。
音訊靜默丟棄：isConnected = false 之後，每一個來自麥克風的音訊 chunk 都被 guard isConnected else { return } 無聲地吃掉，使用者毫無察覺。
isRunning 狀態錯誤：主視窗的「翻譯中」圖示仍在閃爍，但實際上什麼都沒有發生。

隨即重構了 GeminiLiveConnection.swift，在不改變任何外部介面的前提下，引入三道防線：

GoAway 信號提前偵測：在 parseServerResponse() 中解析伺服器發出的 goAway JSON 訊息，不等連線真正斷掉，就提前主動重連，實現無縫接續翻譯。
指數退避自動重連：斷線後以 2s → 4s → 6s 的間隔遞增重試，最多 10 次；重連成功後計數歸零，確保下一次斷線同樣有完整的重試機會。全程靜默，使用者無感。
30 秒 Ping 保活：連線成功後啟動 Timer，每 30 秒向伺服器發送 sendPing，防止中間網路設備因閒置而切斷連線。

修改完成後，開發者執行了 bash build_app.sh 並推送至 GitHub：

Build 成功，commit 完成，push 上去了。之後即時翻譯應該可以長時間持續運作，Session 到期時自動靜默重連，使用者不會察覺中斷。

階段二：功能訪談 — 五個問題鎖定兩大優先開發方向

穩定性解決之後，開發者開始思考 App 能走得更遠：

User: 幫我仔細研究後給我三個新功能推薦

仔細閱讀程式碼後，先提出一個定向問題，而非直接給出清單：

這三個新功能的方向你比較傾向哪一類？

A. 實用性 / UX — 讓日常使用更方便（字幕匯出、快捷鍵、會議記錄）

B. 翻譯品質 — 更準確、更自然（多語言偵測、說話人辨識）

C. 系統整合 — 與其他工具串接（Notion、Zoom overlay）

User: A

三個 UX 功能隨即出爐：懸浮字幕視窗、會議記錄自動匯出、全域快捷鍵。開發者的回應很直接：

User: 1 跟 2 都要

接下來是一場簡短的需求訪談，一次只問一個最關鍵的問題：

懸浮視窗要顯示幾行？→ 雙行（原文小字 + 翻譯大字）
背景風格？→ 毛玻璃效果（vibrancy）
匯出方式？→ 自動存到桌面，不跳對話框

五個問題之後，設計方向完全清晰。提出完整的設計方案並撰寫了規格文件，存入版本庫後，開發者確認「沒問題」，進入實作階段。

階段三：計畫驅動開發 — Subagent 閉環交付，Review 抓出關鍵 Bug

有了明確規格，進入了它最擅長的工作模式：先寫計畫，再用多個獨立 Subagent 分工執行，每個 Task 完成後立即由 Reviewer Subagent 審查。

整個流程分為三個 Task，以下記錄最關鍵的兩個：

Task 1：會議記錄自動匯出

Implementer Subagent 快速完成了三件事：移除原本 25 行的歷史記錄上限、新增 exportTranscript() 方法、在停止翻譯時自動將完整的雙語對照記錄以 Markdown 格式存入 Desktop。

然而 Reviewer Subagent（審查子代理人） 立刻舉旗：

發現 Critical Issue：stop() 裡的 status = "已停止" 緊接在 exportTranscript() 後面執行，立即覆蓋了存檔路徑訊息。使用者永遠只會看到「已停止」，永遠不知道檔案存到哪裡。

這是一個一行之差的邏輯 Bug，在沒有 Reviewer 的情況下非常容易被忽略。Fix Subagent 隨即介入，將 exportTranscript() 改為回傳 Bool：有匯出成功時 stop() 不再覆蓋 status；沒有記錄可匯出時才顯示「已停止」。修改後 Reviewer 再次確認，全數通過。

Task 2：懸浮字幕視窗

新增 FloatingSubtitleWindow.swift，核心結構為三層疊加：

NSPanel（level = .floating）：永遠置頂，不搶奪焦點（.nonactivatingPanel），能跨全螢幕 App 顯示
NSVisualEffectView（material = .hudWindow）：macOS 原生毛玻璃效果
NSHostingView 內嵌 SwiftUI 的 FloatingSubtitleView：直接綁定 TranslatorViewModel.currentLine，實時更新

同時，TranslatorViewModel 的所有權從 ContentView 上移至 TranslatorApp，讓主視窗與懸浮視窗共用同一份資料來源，避免資料複製或同步問題。視窗位置在拖拉後存入 UserDefaults，重啟後自動恢復。

Task Reviewer 逐一核查 11 項規格，全數通過，無任何修正需求。

整個「實作 → 審查 → 修正 → 再審查」的閉環全程由子代理人自動完成，開發者只需確認最終 bash build_app.sh 乾淨通過即可：

Build 成功、commit 完成、push 上去了。

階段四：App 品牌升級 — 用 Python 即時生成專業 Icon

功能齊備之後，開發者把注意力放到了外觀：

User: app icon 不好看，幫我產生一個專業的

先確認環境中有 Pillow（Python 圖像函式庫），接著直接動手寫了一個完整的 Icon 生成腳本，設計說明如下：

背景：深海藍漸層（#0D1B4E → #1565C0），macOS 標準 22% 圓角，呼應 macOS Design Language。
核心圖案：兩個相互疊加的對話泡泡，上方泡泡（半透明白）內含「A」代表英文原音，下方泡泡（純白）內含「中」代表翻譯輸出，中央以雙向箭頭連接，一眼即懂「即時翻譯」的產品定位。
字型：英文採 Avenir Next，中文採 Apple SD Gothic Neo，均為 macOS 內建字型，無需任何外部資源。

腳本一次輸出 10 種尺寸（16px → 1024px），透過系統的 iconutil 命令轉成 .icns 檔，並自動更新 build_app.sh 將 icon 複製進 App Bundle，Info.plist 加上 CFBundleIconFile 宣告。全程不需要打開 Xcode，也不需要任何圖像設計工具。

階段五：程式碼品質精修 — 清零所有編譯 Warning

在開發者執行 bash build_app.sh 驗收時，注意到輸出中夾帶了幾行黃色警告：

User: 執行 build_app.sh 有一些 warning 幫我確認一下

仔細執行 Build 並分類了三種警告，依序對症下藥：

Warning 類型	根本原因	修法
`onChange(of:perform:)` deprecated × 2	`swiftc` 未指定部署目標，預設以最新 SDK 規則檢查	在 `build_app.sh` 加入 `-target arm64-apple-macos13.0`，讓編譯器知道我們針對 macOS 13，舊 API 是正確選擇
`SCRunningApplication` non-Sendable × 2	ScreenCaptureKit 框架的類型未標記 `Sendable`	`import ScreenCaptureKit` 改為 `@preconcurrency import ScreenCaptureKit`
`TranslatorViewModel` 非 Sendable 被捕獲	ViewModel 在 `@Sendable` 閉包中被捕獲	為 `TranslatorViewModel` 加上 `@MainActor`（SwiftUI ViewModel 的現代標準做法），delegate conformance 加上 `@preconcurrency` 壓制衍生警告

最終 Build 輸出乾淨如新，沒有任何 Warning：

🛠 開始編譯 Swift 檔案 (target: arm64-apple-macos13.0)...
🎨 複製 App Icon...
📝 產生 Info.plist...
✅ 打包完成！

全部修改一併 commit 並 push 至 GitHub。

階段六：真實場景踩坑 — ScreenCaptureKit 權限迷宮

App 功能看似完整，直到開發者實際開機要開始使用時：

User: 是因為權限問題嗎？我打開 app 一直無法掃描到「目標 App」列表，幫我檢查一下相關程式碼

App 清單永遠是空的。系統設定裡的「螢幕錄製」也確實有打勾。這是一個典型的「明明有給權限，但就是不動」的鬼打牆問題。

第一刀：靜默失敗的 error 處理

閱讀 AudioCaptureManager.swift 後，第一眼就發現問題：fetchShareableApps() 呼叫 SCShareableContent.current 失敗時，只會 print 到 console，UI 顯示空列表但毫無任何提示。開發者完全不知道發生了什麼事。

第一波修改做了三件事：

Info.plist 補上 NSScreenCaptureUsageDescription：沒有這個 key，macOS 的授權對話框永遠不會跳出來。
加入 ad-hoc 簽名步驟：codesign --sign - --force --deep — ScreenCaptureKit 需要 App 具備 code identity，才能出現在「系統設定 > 螢幕錄製」清單中。
錯誤往 UI 浮出：fetchShareableApps() 改為回傳 (apps, errorMessage?)，任何失敗都會顯示在 App 的狀態列，讓開發者能立刻看到發生了什麼。

Build 完成，再次測試——還是同樣的錯誤訊息。

第二刀：錯誤分類邏輯太激進

仔細看 error 判斷的程式碼：

let isPermissionDenied = nsError.domain == "..." && nsError.code == 1
    || error.localizedDescription.lowercased().contains("permission")
    || error.localizedDescription.lowercased().contains("denied")

contains("permission") 這一行太過激進，只要 error 描述裡有任何含有 “permission” 的字，就會被錯誤地判定為「權限被拒」，顯示「請至系統設定開啟授權」。實際上可能是完全不同的錯誤。

修正了判斷邏輯——只有 ScreenCaptureKit 確切的 userDeclined 錯誤碼（-3801）才視為權限問題，其他錯誤一律顯示真實的 domain、code 與描述，方便診斷：

let isPermissionDenied = nsError.code == -3801
let message = isPermissionDenied
    ? "需要螢幕錄製權限：請至系統設定開啟授權"
    : "無法取得 App 清單（code \(nsError.code)）：\(error.localizedDescription)"

第三刀：找到根本原因 — TCC 身分不匹配

修正 error 分類後，執行 App 並擷取 log，發現狀態列顯示的是帶有 code 編號的新訊息，不是 -3801。這確認了：問題根本不是用戶沒給權限，而是 macOS 根本認不出這個 App。

根本原因：

每次執行 build_app.sh 重新 ad-hoc 簽名後，binary 的 hash 改變，macOS TCC 資料庫把它視為一個全新的 App。 舊的螢幕錄製授權是給上一個 binary 的，新 binary 沒有繼承。系統設定裡顯示勾選，但那是對舊身分的授權，對新 binary 無效。

解法是重置 TCC 讓 macOS 重新觸發授權對話框：

tccutil reset ScreenCapture com.poc.MeetingTranslator

執行後，重新開啟 App、點「↻」，macOS 立刻跳出「MeetingTranslator 想要錄製這個螢幕的內容」對話框。點「允許」，App 清單瞬間列出所有正在執行的應用程式。

永久對策：把重置寫進 build 流程

Ad-hoc 簽名的問題在開發期間會持續存在——每次 rebuild 都需要重新授權。把 tccutil reset 直接加進 build_app.sh 的最後一步：

tccutil reset ScreenCapture com.poc.MeetingTranslator 2>/dev/null && \
  echo "✅ 已重置，開啟 App 後系統會重新詢問授權" || true

從此每次 bash build_app.sh 之後，直接 open MeetingTranslator.app，系統就會重新詢問一次授權，整個開發循環再也不會卡在「明明有給權限卻不動」的怪圈裡。

結語：「計畫 → Subagent 實作 → AI Review」閉環的真正價值

這次的協作，讓我感受到與第一次 AGY CLI 開發截然不同的工作方式：

主動問問題，而非直接動手：面對「給我三個新功能推薦」，Claude Code 的第一步是問方向；面對「懸浮視窗」，它逐一確認風格與細節。這種「先對齊再實作」的節奏，比直接猜測需求要可靠得多。
計畫是品質的護城河：在實作前先撰寫規格文件與實作計畫，讓每個 Subagent 都有清晰的邊界與驗收條件。這個看似「多餘」的步驟，在 Task 1 的審查中直接發現了人類開發者很容易忽略的狀態覆蓋 Bug。
AI Review AI 是不同的保障層：Reviewer Subagent 和 Implementer Subagent 是完全獨立啟動的，它們沒有共享上下文。正因如此，Reviewer 能以全新視角發現 Implementer 的盲點——這是「AI 雙檢」帶來的額外保障，不是人力 Code Review 的替代品，而是一個全新的品質層次。
工具邊界即是功能邊界：App Icon 生成、Warning 修復、Git commit/push，Claude Code 在整個開發環境中自由穿梭，開發者不需要切換任何工具，所有動作都在對話中完成。
真實使用才是最好的測試：階段六的 ScreenCaptureKit 問題在所有 build 測試中從未出現，直到開發者真正開機要用才踩到。這種「靜默失敗 + 系統層面的身分不匹配」問題，只有在真實場景下才會浮現。Claude Code 的診斷方式——從修正 error 分類、到讓 UI 顯示真實錯誤碼、再到找到 TCC 根本原因——是一個典型的「縮小假設範圍，讓問題說話」的除錯思路。

如果說第一篇是「從零到有」，這篇記錄的是「從可用到好用，再到在真實場景下站得住腳」。兩種 AI Agent、兩種協作風格，共同完成了一個涵蓋底層音訊、WebSocket 連線、SwiftUI UI、Python 圖像生成、系統權限診斷的完整 Native macOS App。我們下期見！

[Gemini API 實戰] 打造 MemeFinder：用 Gemini 視覺與語意嵌入，做一個「打字就找到梗圖」的原生 Mac 選單列小工具

Sat, 20 Jun 2026 00:00:00 +0000

緣起：聊天打到一半，那張梗圖到底在哪？

每個重度聊天的人手機與電腦裡都存了一堆迷因圖，但真正要用的時候——對話進行到一半、想丟一張「謝謝再聯絡」或「我就爛」——卻怎麼也翻不到。檔名是 IMG_4821.jpg，相簿沒有分類，搜尋更是無從下手。

我先看到一個很棒的開源專案 ShiQu1218/MemeTalk，它用 Python + Streamlit + SQLite 打造了一套本地迷因語意搜尋系統，會掃描你本機的迷因資料夾、用 OCR 與向量嵌入建立索引，再做多路召回。功能完整，但偏研究取向、要開瀏覽器跑 Streamlit。

我想要的是更貼近「日常順手工具」的東西：

一個原生 Mac App，一個搜尋框，打我想找的內容，就跳出相關的梗圖，點一下直接複製到剪貼簿。

於是有了 MemeFinder。這篇文章紀錄它從零到「選單列常駐 + 全域快捷鍵」的開發過程，以及途中幾個很有代表性的坑。

系統設計與架構

核心概念很單純：指定一個本機迷因資料夾 → 用 Gemini 幫每張圖建立索引 → 打字做語意搜尋 → 點圖複製。

技術選型上我做了三個關鍵決定：

原生 SwiftUI App，而不是 Electron。剪貼簿複製圖片、全域快捷鍵、選單列常駐，這些用 AppKit 都是一級公民。
Gemini 負責兩件事：用視覺模型 gemini-3-flash-preview 讀出圖中文字、生成繁中描述與情緒標籤；用 gemini-embedding-2 把這些語意轉成 768 維向量。
語意向量 + 關鍵字混合搜尋。純關鍵字對中文召回太差；語意向量才能做到「打相關敘述就找到圖」。

系統架構流向

graph TD
    A[使用者指定迷因資料夾] -->|掃描 jpg/png/webp| B[Indexer 索引器]
    B -->|每張圖| C[Gemini 視覺模型 gemini-3-flash-preview]
    C -->|OCR文字 + 描述 + 標籤 + 情緒| D[Gemini 嵌入 gemini-embedding-2]
    D -->|768 維向量| E[本機索引檔 index.json]
    F[使用者打字查詢] -->|⌃⌘M 選單列浮窗| G[Gemini 嵌入查詢字串]
    G -->|cosine 相似度 + 關鍵字加權| E
    E -->|排序結果| H[縮圖牆]
    H -->|點圖| I[NSPasteboard 複製到剪貼簿]

整個專案刻意拆成兩個 Swift Package target：

Target	類型	內容
`MemeFinder`	library	邏輯、模型、服務、ViewModel（全部有單元測試）
`MemeFinderApp`	executable	SwiftUI 畫面 + 選單列殼（薄殼，依賴上面的函式庫）

這個拆分不是裝飾——它直接決定了測試能不能順利跑，後面「踩坑二」會講到為什麼。

核心實作

1. 用 Gemini 視覺模型自動標註迷因圖

索引時，每張圖會送進視覺模型，要求它只輸出 JSON：圖中文字、繁中描述、標籤、情緒。responseMimeType 設成 application/json 來穩定輸出格式：

public static func annotateRequest(apiKey: String, imageData: Data, mimeType: String) -> URLRequest {
    let prompt = """
    你是迷因圖標註助手。請閱讀這張圖，輸出 JSON，欄位：
    ocr_text(圖中所有文字), description(用繁體中文描述畫面與梗),
    tags(3-8 個繁體中文關鍵字陣列), emotion(單一情緒詞)。只輸出 JSON。
    """
    let body: [String: Any] = [
        "contents": [[
            "parts": [
                ["text": prompt],
                ["inline_data": ["mime_type": mimeType, "data": imageData.base64EncodedString()]]
            ]
        ]],
        "generationConfig": ["responseMimeType": "application/json"]
    ]
    // ... 設定 URL、x-goog-api-key header、POST body
}

2. 語意 + 關鍵字混合排序

查詢字串嵌入成向量後，對每張圖算 cosine 相似度，再對 OCR 文字與標籤命中的關鍵字加權，合併排序：

public func search(queryEmbedding: [Float], queryText: String,
                   in images: [IndexedImage], limit: Int) -> [SearchResult] {
    let tokens = queryText.lowercased().split(whereSeparator: { $0.isWhitespace }).map(String.init)
    let results: [SearchResult] = images.compactMap { image in
        let cos = cosineSimilarity(queryEmbedding, image.embedding)
        let haystack = (image.ocrText + " " + image.tags.joined(separator: " ")).lowercased()
        let matches = tokens.filter { !$0.isEmpty && haystack.contains($0) }.count
        let boost = 0.1 * Float(min(matches, 3))   // 關鍵字加權上限 0.3
        let score = cos + boost
        return score > 0 ? SearchResult(image: image, score: score) : nil
    }
    return Array(results.sorted { $0.score > $1.score }.prefix(limit))
}

整個搜尋引擎是純函式，把 Gemini 藏在 protocol 後面，所以這段邏輯完全能離線單元測試，不用打真實 API。

重大踩坑與解決方案

這個專案真正花時間的地方，從來不是「快樂路徑」，而是下面這幾個坑。

踩坑一：神秘的 `GeminiError error 0`——索引與搜尋全部失敗

App 打包完、設定好金鑰、選好資料夾，一搜尋——下面什麼圖都沒有，只跳出 GeminiError error 0。

我沒有亂猜，而是直接用真實金鑰打了一次 embedding 端點，把回應印出來：

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
  -H "x-goog-api-key: $KEY" \
  -d '{"content":{"parts":[{"text":"貓"}]},"output_dimensionality":768}'

證據一翻兩瞪眼：

{ "embedding": { "values": [ -0.0063, -0.0200, ... ] } }

問題在於，我的解析器讀的是複數 embeddings[0].values（那是 batchEmbedContents 批次端點的格式），但單筆 embedContent 回的是單數 embedding.values。於是每一次 embed 都失敗——索引每張圖失敗、把查詢字串轉向量也失敗，全都丟出 badResponse（在 UI 上顯示成 GeminiError error 0）。

【解決方案】 修正解析器讀單數 embedding.values，並保留複數格式作為後備；順手也加固了標註解析器（思考型模型有時會多回一個沒有文字的 “thought” part，要跳過取第一個有文字的 part）：

public static func embedding(fromEmbedContent data: Data) throws -> [Float] {
    guard let root = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else {
        throw GeminiError.badResponse("cannot parse embedContent payload")
    }
    // 單筆 embedContent 回傳 {"embedding":{"values":[...]}}
    if let embedding = root["embedding"] as? [String: Any],
       let values = embedding["values"] as? [Double] {
        return values.map(Float.init)
    }
    // batchEmbedContents 才是 {"embeddings":[{"values":[...]}]} — 一併容忍
    if let embeddings = root["embeddings"] as? [[String: Any]],
       let values = embeddings.first?["values"] as? [Double] {
        return values.map(Float.init)
    }
    throw GeminiError.badResponse("cannot parse embedContent payload")
}

教訓：API 回應格式請以真實回應為準，不要相信記憶或二手文件。一行 curl 省下無數猜測。

踩坑二：SwiftPM 的 `main` 入口衝突與 SwiftUICore 連結錯誤

我一開始把整個專案做成單一 executableTarget，讓測試直接依賴它。結果測試怎麼跑都連結失敗：executable target 需要一個 main 進入點，但這個進入點要到 UI 那一步的 @main App 才會存在；而隨手補一個 main.swift 佔位檔，又會和 @main 衝突（Swift 不允許一個 target 同時有兩個進入點）。更別說 SwiftUI 在 executable target 還會冒出 SwiftUICore.tbd ... not an allowed client 的連結警告。

【原因分析與解決方案】 這其實是個架構問題，不是編譯問題。正確做法是把專案拆成兩層：

MemeFinder（library target）：所有邏輯、模型、服務、ViewModel——測試只依賴這層，沒有進入點，乾乾淨淨地當函式庫連結。ViewModel 要 import Combine（而不是 SwiftUI）就能拿到 ObservableObject。
MemeFinderApp（executable target）：只放 SwiftUI 畫面與 @main，import MemeFinder 取用上面的公開型別。

拆完之後，library 與測試完全不碰 SwiftUI，連結警告消失，@main 衝突也不復存在。「測試要依賴什麼」往往會反過來逼出乾淨的模組邊界。

踩坑三：平行索引的速率限制與「索引到一半想喊停」

第一版索引是一張一張序列呼叫 Gemini（先 annotate 再 embed），上百張圖慢到讓人懷疑人生。於是改成用 withTaskGroup 做有界平行（同時最多 4 條），但這帶出三個新問題：

Gemini 免費額有速率限制，併發太多會吃 429。
大資料夾索引到一半，使用者想取消。
平行完成的順序是亂的，但結果要穩定排序。

【解決方案】 三個問題分別處理，全部收斂在同一個 buildIndex 裡：

429 退避重試：只對 GeminiError.rateLimited 做指數退避重試（最多 3 次），其他錯誤直接記錄不重試。
協作式取消：尊重 Task.isCancelled，取消時停止派新工作、保留已完成的部分。連退避時的 Task.sleep 都讓 CancellationError 正常傳遞，而不是吞掉它再多打一次 API。
穩定排序：結果收進 [路徑: 圖] 字典，最後依「事先排好序的檔案清單」重組輸出，跟完成順序脫鉤。

// 先塞滿 maxConcurrent 個任務，之後每完成一個就補一個——嚴格維持併發上限
for _ in 0..<maxConcurrent { if !scheduleNext() { break } }
while let res = await group.next() {
    if let img = res.image { resultsByPath[res.path] = img }
    if let err = res.error { errors.append(err) }
    done += 1
    progress(done, total)
    _ = scheduleNext()
}

順帶一提，HTTP 狀態碼也被抽成一個純函式 mapResponse(data:statusCode:)：429 → rateLimited、其他非 2xx → httpError(碼)、2xx → 回傳資料。重試邏輯才有依據，這段也好測。

踩坑四：從「有視窗的 App」進化成「選單列常駐 + 全域快捷鍵」

工具好不好用，差別在於「叫出它要幾步」。我希望聊天到一半按 ⌃⌘M 就能呼叫搜尋浮窗，App 平常縮在選單列、不佔 Dock。這一步踩了兩個 macOS 老坑：

(a) 全域快捷鍵要不要輔助使用權限？ 不用。用 Carbon 的 RegisterEventHotKey 註冊固定快捷鍵，不需要 Accessibility 權限（不像監聽全鍵盤）。但在 Swift 6 嚴格並行下，C 事件回呼要透過一個 id → 實例 的靜態註冊表來分派，得用 nonisolated(unsafe) 並靠「Carbon 事件只在主執行緒派發」這個不變量來保證安全。若 ⌃⌘M 已被佔用，RegisterEventHotKey 會回傳失敗——這時靜默降級、記一筆 log，點選單列 icon 仍可用。

(b) 選單列右鍵選單的時序競態。 最初的寫法是「設定 statusItem.menu → performClick → 馬上清空 menu」，但同步清空會和 AppKit 的選單追蹤迴圈打架，選單會閃一下就消失。

【解決方案】 改用直接彈出選單，完全繞過 statusItem.menu 的賦值與清空：

@objc private func statusButtonClicked() {
    guard let event = NSApp.currentEvent else { togglePopover(); return }
    if event.type == .rightMouseUp {
        // 直接彈出，不要賦值再同步清空 statusItem.menu（會和 AppKit 選單追蹤迴圈競態）
        if let button = statusItem?.button {
            NSMenu.popUpContextMenu(makeMenu(), with: event, for: button)
        }
    } else {
        togglePopover()
    }
}

最後在 build-app.sh 打包的 Info.plist 加上 LSUIElement = true，Dock 圖示消失，MemeFinder 正式成為純選單列工具。

踩坑五：設定表單一片空白——一個症狀，三層原因

改成選單列版後，使用者回報「設定視窗整個是空白的」。這個看似單純的 bug，剝開來其實有三層，每一層都很有代表性。

第一層：Form 在手刻 NSWindow 裡塌成零高度。 原本設定畫面住在 SwiftUI 原生的 Settings { } scene 裡，SwiftUI 會自動給它合理尺寸。改版後改用手刻的 NSWindow(contentViewController: NSHostingController(rootView: SettingsView())) 承載，而 SettingsView 的結尾只寫了 .frame(width: 460)——只有寬度、沒有高度。NSWindow(contentViewController:) 會用內容的自然尺寸決定視窗大小，但 SwiftUI Form 在垂直方向是貪婪的、沒有約束時自然高度會被算成接近 0，於是視窗開成一條 460 寬、高度幾乎為零的空白條。修正只要補上高度：

.padding(20)
// 在手刻 NSWindow（非 SwiftUI Settings scene）裡承載時，沒有高度約束的
// Form 會塌成 ~0，視窗就變成一條空白。
.frame(width: 460, height: 320)

第二層：⌘, 和選單列「設定…」走的是兩條不同的路。 補了高度後，使用者說「還是空白」。追問之下才發現——他是按 ⌘, 叫出設定的，而選單列右鍵的「設定…」走的卻是另一條路。原因是：⌘, 在 SwiftUI App 會觸發 Settings { } scene，而我當初為了迴避狀態共享問題，把那裡放成了 Settings { EmptyView() }：

// 改版時為了避開狀態共享，Settings scene 被放空——於是 ⌘, 開出來就是一片空白
var body: some Scene {
    Settings { EmptyView() }
}

換句話說，設定有兩個入口，而它們指向不同的東西：⌘, 指向空 scene，選單列「設定…」指向真正的視窗。修正是把兩條路統一——讓 Settings scene 裝真正的 SettingsView（⌘, 直接可用），選單列「設定…」也改成開同一個原生設定視窗：

Settings {
    SettingsView(vm: appDelegate.settings, indexing: appDelegate.indexing,
                 onReindex: { appDelegate.reindexNow() },
                 onCancel: { appDelegate.cancelReindex() })
}

// 選單列「設定…」改成開同一個 Settings scene
@objc private func openSettings() {
    NSApp.activate(ignoringOtherApps: true)
    NSApp.sendAction(Selector(("showSettingsWindow:")), to: nil, from: nil)
}

這裡也順帶把 SwiftUI App body 是 @MainActor 隔離這件事用上了——所以從 body 直接讀取 @MainActor 的 appDelegate.settings 是合法的，不需要額外的橋接。

第三層（最陰險的）：選單列 App 用 open 根本不會載入新版。 過程中最浪費時間的，是我重新編譯後請使用者 open MemeFinder.app，他卻一直看到舊行為。因為 MemeFinder 是 LSUIElement 選單列常駐 App——當已經有一個實例在跑時，open 只會喚醒既有的舊行程，而不會用新的二進位重啟。於是我們其實一直在測同一個舊版。正確的開發循環是先確實關掉，再從原始碼跑：

killall MemeFinderApp 2>/dev/null; swift run MemeFinderApp

這層提醒我：debug 時要先確認「你測的真的是你改的那一版」，否則所有推理都建立在錯誤的觀察上。

關於「開發過程」本身

這個專案幾乎全程是用規格 → 計畫 → 子代理逐項實作 → 兩段式審查的 AI agent 工作流推進的：每個功能先寫設計規格、再拆成可獨立測試的小任務、每個任務都先寫失敗測試（TDD）再實作，完成後由獨立的審查代理檢查規格符合度與程式品質，最後再做一次整支分支的總審。

幾個踩坑——GeminiError error 0、library/executable 拆分、退避時吞掉 CancellationError、選單時序競態——其實有一半是審查階段揪出來的，而不是第一版就寫對。這也呼應了那條老原則：有測試護體、有人（或代理）認真讀 diff，比寫得快重要得多。 最終整支專案維持 47 個單元測試、release build 零警告。

成果與效益

打字即得、點圖即貼：在選單列浮窗打中文敘述，語意搜尋立刻列出相關梗圖，點一下複製到剪貼簿，直接貼進 LINE / Slack / 訊息。
隱私友善、離線可搜：圖片與索引都在本機（~/Library/Application Support/MemeFinder/index.json），只有「建立索引」那一步會呼叫 Gemini。
真正的順手工具：⌃⌘M 隨叫隨到、選單列常駐、不佔 Dock；增量索引只處理新增/變動的圖，索引可顯示進度、可取消。
乾淨可維護的架構：library/executable 雙層、Gemini 藏在 protocol 後、純邏輯全有測試覆蓋。

本專案所有開發程式碼均已開源於 GitHub：kkdai/meme-finder-app。歡迎大家 clone 下來、放進自己的迷因收藏資料夾，親自體驗一下「打字就找到梗圖」的快感！

Blog E

[Claude Code 實戰] 重新盤點終端機工作流：從 zsh 自動完成到搜尋比對工具鏈

痛點：每打一個指令，都要重新來一次

解法一：先讓 zsh 自己記得你打過什麼

解法二：補顏色，讓終端機看得更快

解法三：把 ls、cat、cd 也換成更聰明的版本

解法四：讓 Claude Code 搜尋、比對檔案更快

解法五：把常用唯讀指令收進 Claude Code 的權限白名單

容易忽略的三個坑

坑一：compinit 抱怨「insecure directories」

坑二：zsh-syntax-highlighting 一定要放在檔案最後一行

坑三：ast-grep 沒有被放進白名單，是刻意的

總結與效益

[開發紀錄][Node.js] Feedly Classic 回不去了，我自己動手做了一個 FeedFlow（一）

前言:

TL;DR

為什麼要自己刻一個 RSS 閱讀器

LINE Login 在這個專案裡代表的意義

RSS 閱讀器的開發過程：從單機 MVP 到多使用者雲端同步

為什麼選 Gemini 當翻譯引擎，中間踩了哪些坑

前端介面：四種檢視模式與行動裝置優先設計

目前進度與下一篇的方向

結論

參考連結：

[學習心得][Golang] AI Agent 時代的授權難題：ID-JAG 是什麼？為什麼我用 Go 重新實作了一次

前言:

TL;DR

什麼是 ID-JAG？為什麼需要它？

從 OAuth2、PKCE，到 Agent 時代的新問題

兩塊 RFC 基石：Token Exchange 與 JWT Bearer

ID-JAG 的完整 token 交換流程

每一跳都窄化權限：最小權限原則怎麼落地

為什麼要用 Go 重新實作這個 MCP Server？

動手玩：安裝、執行與測試

結論

相關文章：

[GCP 實戰] LINE 名片 Bot 再進化：用 Gemini 一次搞定名片正反面辨識合併

痛點：一張中文名片，其實是兩張名片

解法：先問一句「還有背面嗎？」

核心：讓 Gemini 一次看兩張圖，自己做合併

容易忽略的兩個小坑

坑一：重複檢查的時機點

坑二：清狀態不能一路清到底

順手做的資源清理：別讓背面圖片一直留在記憶體裡

總結與效益

[好書分享]台灣AI大未來 解析最新的AI趨勢、台灣情勢、企業布局與個人發展

買書推薦網址：

前言:

大綱

全書四大核心架構概覽

一、 最新AI趨勢：1:99 的「超級人類」大挑戰

二、 台灣情勢：從「海島內捲」轉向「大航海時代」

三、 企業布局：軟硬整合，讓「老創＋新創」攜手共舞

四、 個人發展：拒絕「大腦外包」，做高段位的「出題者」

心得

[好書分享]蔡桑說怪 - 日本神話與靈界怪談，有時還有臺灣

買書推薦網址：

前言:

大綱

核心三大板塊重點整理

一、 日本神話：比本土劇還超展開的第一家庭

二、 妖怪與都市傳說：現代人的集體焦慮

三、 有時還有臺灣：臺日神鬼的奇妙連結

心得

[數位憑證皮夾] 進階版 - 打造「訪客背書發證」：一個同時當驗證方與發行方的 DID 全鏈應用（附開發踩坑紀錄）

前提：

場景：員工門禁 + 訪客背書發證

架構決策：為什麼不直接改上一個專案

踩坑紀錄一：出示成功了，畫面卻一直卡住

踩坑紀錄二：訪客卡一直「待發」

踩坑紀錄三：領卡 QR 太小 + 手機版面

關於「限時自動失效」的真相

部署：從原始碼直接上 Cloud Run

總結與未來展望

[GCP 帳單與 Vertex AI] 破解單一專案 Gemini 費用拆分難題：Vertex AI 動態計費標籤 (Labels) 實戰記

痛點：同一個專案內的 Gemini API 費用如何精準分攤？

山不轉路轉：Vertex AI 的「請求標籤 (Labels)」救星

原理與流程

專案實戰改造：全面導入 Labels 機制

1. 專案 API 呼叫盤點

解法三：把 `ls`、`cat`、`cd` 也換成更聰明的版本

坑一：`compinit` 抱怨「insecure directories」

坑二：`zsh-syntax-highlighting` 一定要放在檔案最後一行

坑三：`ast-grep` 沒有被放進白名單，是刻意的

[好書分享]台灣AI大未來解析最新的AI趨勢、台灣情勢、企業布局與個人發展

一、最新AI趨勢：1:99 的「超級人類」大挑戰

二、台灣情勢：從「海島內捲」轉向「大航海時代」

三、企業布局：軟硬整合，讓「老創＋新創」攜手共舞

四、個人發展：拒絕「大腦外包」，做高段位的「出題者」

一、日本神話：比本土劇還超展開的第一家庭

二、妖怪與都市傳說：現代人的集體焦慮

三、有時還有臺灣：臺日神鬼的奇妙連結

場景 A：已包含 `GenerateContentConfig`

踩坑一：神秘的 `GeminiError error 0`——索引與搜尋全部失敗

踩坑二：SwiftPM 的 `main` 入口衝突與 SwiftUICore 連結錯誤