Claude Code Mods：從設定與 Hooks，走向可改寫行為與 UI 的外掛層 | Allen 知識庫 | Allen 知識庫AI Developer Toolsthreads
Claude Code Mods：從設定與 Hooks，走向可改寫行為與 UI 的外掛層
Claude Code Mods 可觀察、改寫或拒絕事件，也能畫自訂 UI；新增 ctx-handoff 實例，拆解自動 /clear、長對話交接、離席 cache refresh 的證據、成本與安全邊界。
2026年10月2日6 分鐘閱讀👁 11
Claude Code / Plugins / Function Hooks
Mods 把 Claude Code 從「可設定」推進到「可程式化改造」
Mod 是隨 Claude Code session 常駐的 JavaScript／TypeScript 模組：它能監看事件、改寫輸入、阻擋工具呼叫、註冊命令，並在 Terminal 或 Desktop App 畫出 pane、按鈕與狀態區。它沿用 Plugin 的安裝與發佈機制，不是另一套互不相容的擴充系統。
結論先講：Mods 最有價值的不是「換皮」，而是把治理、審核與工作流放到模型與工具之間的可程式化攔截層；但 Mod 仍是高權限本機程式碼，安裝第三方 Mod 應比照 npm 套件或 IDE extension 做來源與程式碼審查。
官方定義與最低條件
- 官方教學要求
Claude Code 2.1.287+；Mods 預設啟用，不需另開功能開關。
- Mod 本質是 Plugin：
.claude-plugin/plugin.json 宣告套件，hooks/hooks.json 指向一個 module。
- 模組匯出
register(on, options)，以 on(event, matcher?, hook) 註冊事件。
- API 仍可能隨版本變動；每次載入時寫出的
.claude-plugin/types/ 型別宣告，才是該版本的權威介面。
核心心智模型：middleware chain
Observe
先 await next(e)，再讀結果或記錄事件。適合 telemetry、變更紀錄、context 使用率與稽核。
Rewrite
把修改後的事件交給 。適合 prompt policy、參數正規化、敏感資料代換或命令改寫。
next({...e})
Answer / Deny
不呼叫 next，直接回傳結果或拒絕。適合硬性 guard、客製命令與自訂工具。
可攔截的範圍包含工具呼叫、prompt submit、turn／session 起訖、slash command 與 ui.render。與舊式 settings hook 每次啟動 shell、以 stdin/stdout 傳 JSON 不同，Mod 在 session 內常駐，可保存狀態、熱重載、開 pane、執行受控 process、註冊 command 或 model-callable tool。
三個官方範例各自教什麼
| 範例 | 展示能力 | 真正可重用的模式 |
|---|
| Token Weather | 在 prompt 上方顯示 context 使用率、token 數、近 12 輪趨勢與天氣狀態。 | session.usage()＋$.state＋ui.render；狀態應放 host state，避免 hot reload 後遺失。 |
| Blast Radius | 在 rm -rf、git reset --hard、force push、migration 前暫停，預估影響並讓人 Proceed／Cancel。 | 工具呼叫前審核、side pane 與按鈕決策；窄終端可退化為 prompt 上方 band。 |
| Replay Theater | 記錄單輪中的 Edit／Write，使用 /replay 逐步播放每次變更。 | 以 turn.start／turn.complete 做事件配對，再用 command＋pane 建立審查介面。 |
重要修正：Blast Radius 是 safety net，不是 permission system。官方明說它只讀 command text；subshell、alias 或內部再呼叫危險指令的 script 可能繞過。真正的硬阻擋仍要用 permission rules、最小權限與隔離環境。
分享與部署
- 開發時可用
claude --plugin-dir ./your-mod 載入並熱重載。
- 用
claude plugin validate 檢查 manifest、hooks、API calls 與 state contract；用 claude plugin test 跑 runtime tests。
- 發佈沿用 Plugin Marketplace：加入 marketplace、安裝 plugin、再
/reload-plugins。
- 可保持私人使用、發給團隊，或提交 Claude Directory；官方 Claude Code repo 已公開
mods/，包含 AGENTS.md、diff、security-default 與 telemetry 等實作可供審閱。
安全邊界：Threads 留言有一半對、一半需要校正
| 說法 | 官方證據 | 準確解讀 |
|---|
| 「Mod 沒有 sandbox」 | 官方教學寫明 module 在自己的 sandbox 內執行，沒有 DOM、也沒有 Node；外部能力透過 $ API。 | 字面上不正確；它有執行介面限制，但不能因此把第三方 Mod 當低風險。 |
| 「Mod 權限跟 Claude Code 一樣大」 | 官方同時警告：Mod 是 publisher 寫、在本機 Claude Code 內執行的程式碼，應只安裝可信來源。 | 實務風險方向正確：透過 host 暴露的 fs／process／http／tool 等能力，惡意或有漏洞的 Mod 仍可造成高影響。 |
| 「能自動替你允許／拒絕權限」 | hook 可 answer／deny 或改寫事件，也可畫決策 UI。 | 技術上可做治理層，但第三方 Mod 也可能篡改流程；安全 Mod 本身需要測試、code review 與明確 fail-closed 設計。 |
導入檢查清單
- 鎖定 Claude Code 最低版本，並把該版本自動產生的 types 當相容性基準。
- 先從 read-only observability Mod 開始，再逐步進到 rewrite／deny。
- 所有 tool.call guard 都要測試 timeout、exception、hot reload、窄終端與 subagent 情境。
- 第三方 Mod 安裝前審 repo、publisher、更新機制、fs/process/http 呼叫與資料外送面。
- 高風險操作仍保留 OS 權限、sandbox、branch protection、CI 與人工 approval，不把 Mod 當唯一防線。
- 對治理型 Mod 建立稽核紀錄、明確 fail-open／fail-closed 策略，以及可一鍵停用與回滾的版本。
案例：ctx-handoff 把長對話接力變成事件驅動工作流
社群 Mod，不是 Claude Code 官方功能：cablate/ctx-handoff-mod 使用 Mods 的
turn.complete、
model.fork、
command.run 與
prompt.submit，在主對話達門檻時自動產生 handoff、執行
/clear，再把 handoff 送進新對話。這正是一般 Plugin 設定或只在被呼叫時執行的 Skill 難以單獨完成的「回合後主動行為」。
在場交接
主對話 context 達 min(600k, 視窗 × 80%) 時觸發；若仍有背景 shell、workflow 或 subagent，先延後，避免清掉仍在工作的 session。
離席保溫
閒置 55 分鐘後以極短 fork 嘗試刷新 prompt cache，預設最多 3 次；第 4 次只保存 away handoff，不會趁使用者不在時自動清空對話。
回來再選
下一則人類訊息會先被暫存；/handoff-resume 開新對話接續，/handoff-continue 則留在舊對話。最近 5 份 handoff 保存在 Mod store。
證據與仍未驗證的部分
| 項目 | 目前證據 | 判讀 |
|---|
| 自動 handoff 流程 | repo 有 9 個 mock runtime tests，涵蓋門檻、200k 視窗、離席刷新、背景工作延後與 resume。 | 邏輯覆蓋合理，但不是長時間真實 session 的端到端證明。 |
| 大 context fork 的 cache 命中 | 作者回報 102,523 input tokens 中 102,003 為 cache read，約 99.5%。 | 支持 fork 可重用快取；仍是作者單次 probe。 |
| 600k 真實自動交接 | README 明列尚未在完整真實 session 觀察。 | 實驗性功能，不應無人看管地直接用於關鍵工作。 |
| 「可整晚保溫」 | 作者在 Threads 回覆可移除刷新次數上限。 | 程式可以無限排程，不等於 cache 一定被延長；README 也明列 idle refresh 是否真的延長 1 小時 cache 尚未確認。 |
成本與安全邊界
- 先確認 cache TTL：作者警告 API key、Bedrock、Vertex，以及訂閱進入 usage credits 後可能只有 5 分鐘 cache；55 分鐘刷新會太晚，應用
/handoff-refresh off。這是專案文件的操作假設，採用前仍應以帳號 telemetry 驗證。
- 不要把無限保溫當免費：每次 fork 都可能產生 cache read、cache creation 或 output 成本；若 cache 已失效，反而可能重寫整段長 context。
- 清除是有狀態副作用：Mod 能自動執行
/clear 並送出新 prompt。安裝前必須審查原始碼、鎖 commit，並先用非關鍵 session 測試。
- 附件不完整：離席後暫存的第一則訊息只保留文字；圖片不會跟著 handoff。
- 背景偵測不是完整調度器：Workflow／Monitor task ID 依文字格式解析，作者已標示該格式仍未驗證；永不結束的 dev server 最長可能讓 handoff 延後 12 小時。
Skill 與 Mod 的分工：Skill 很適合定義 handoff 格式、摘要品質與接手規則；Mod 則負責「何時觸發、監看閒置、攔住訊息、執行 clear」。較穩健的設計不是二選一，而是由 Mod 做 lifecycle orchestration、Skill 做可重用的交接方法。
對產品與 Agent 平台的意義
Mods 把原本分散在 wrapper script、settings hook、MCP server 與外部 dashboard 的一部分能力，拉進同一個 session runtime：一邊能觀察模型與工具事件，一邊能畫出可操作 UI。這使「context 預算、變更審閱、敏感資訊遮蔽、production command guard、專案導覽、成本與 rate-limit 顯示」都能變成可安裝、可測試、可分享的 Plugin。真正的競爭力將不只在 prompt，而在具備事件模型、UI、測試、權限與更新治理的 workflow product。