Context Mode 企業級 AI Agent 軟體開發教學手冊

Enterprise Context Engineering Handbook for AI Coding Agents 把 AI Coding Agent 從「把資料搬進 Context Window 的搬運工」改造成「設計分析程式的工程師」——一份可直接作為團隊開發規範的完整導入手冊

文件資訊

可信度標示制度（請務必先讀）

Context Mode 是一個高速演進中的 source-available 專案：2026-02 建立，到 2026-09 已發布 169 個版本，平均約 1.2 天一個版本。網路上（包含中文技術文章、影片、AI 產生的內容）有大量描述已經過時，而過時的部分往往正是企業最在意的：平台支援範圍、Hook 能力、安全邊界、節省比例。

更重要的是：官方 README 的行銷數字與官方 BENCHMARK 的實測數字並不相同。本手冊會把兩者分開陳述。

因此本手冊對每個重要論述標示來源等級：

最重要的一條：凡是標示 [Enterprise Recommendation] 的內容，都不是 Context Mode 的原生功能。不要因為手冊寫了，就以為安裝完就自動具備。

三個必須先知道的落差 [AI Analysis]

在讀任何章節之前，先建立這三個認知，它們會影響你對整份手冊的判讀：

落差一：「98% reduction」是子集數字，不是全域保證值

官方 README 首頁寫「315 KB becomes 5.4 KB. 98% reduction.」，但翻開官方 BENCHMARK.md：

首頁那個 98% 只涵蓋 ctx_execute_file 路徑。知識檢索路徑（ctx_index + ctx_search）只有 82%，因為它刻意保留完整程式碼區塊不做摘要——這其實是優點，但不能拿去當 KPI。詳見 第 26 章。

落差二：平台數量官方自己就不一致

Repo description 與 README 內文都寫「17 platforms」，但 README 的 Platform Compatibility 表格實際列出 18 個平台（多了 Qwen Code）。本手冊以表格為準，採用 18 個平台。詳見 第 9 章。

落差三：這是一個「開源核心 + 商業平台」的雙層產品，不是純 OSS 工具

README 的 Privacy 章節寫「No telemetry, no cloud sync, no account required」，工具清單裡的 ctx_insight 則是「opens the hosted Insight dashboard（context-mode.com/insight）」。 很多人讀到這裡會以為官方說法自相矛盾——其實不是，官方現在已把兩層講清楚了 [Official]：

官方明確聲明轉發內容「never source code、never prompt content、never file content」。

[AI Analysis] 但企業要注意的是：「只有結構化 metadata」不等於沒有敏感資訊。 檔案路徑本身就可能洩漏內部專案代號、客戶名稱、甚至併購案代號 （例如 src/projects/acme-merger/…）。官方的聲明是真的，但它保護的範圍未必涵蓋你的風險。

[Enterprise Recommendation] ctx_insight 預設停用；要啟用須先完成 ①「路徑命名是否洩漏敏感資訊」的評估 ② 與供應商簽署資料處理協議（DPA）。 金融業建議維持禁用。詳見 23.3 與 第 31 章。

目錄

本目錄列到章層級。各章的節（x.y）層級子目錄於每個 Part 開頭列出，全部可直接點擊跳轉。

卷首

• 文件資訊
• 可信度標示制度（請務必先讀）
• 原始 62 章需求 ↔ 本手冊章節對照表

Part 1 概念篇：為什麼需要 Context Mode

• 第 1 章 Executive Summary
• 第 2 章 AI Agent 的 Context Window 問題

Part 2 架構篇：Context Mode 如何運作

• 第 3 章 整體架構
• 第 4 章 核心設計：MCP Server 與 Tool Routing
• 第 5 章 Sandbox 與 Think in Code
• 第 6 章 FTS5 與 Persistent Knowledge
• 第 7 章 Session Continuity
• 第 8 章 MCP + Hooks：Routing Enforcement

Part 3 平台與安裝篇

• 第 9 章 平台相容性矩陣
• 第 10 章 Claude Code 安裝
• 第 11 章 GitHub Copilot 生態系安裝
• 第 12 章 Codex CLI / Cursor 安裝
• 第 13 章 其他平台安裝
• 第 14 章 企業標準安裝流程與設定管理

Part 4 工具實戰篇

• 第 15 章 11 個 MCP Tools 完整教學
• 第 16 章 AI Agent Prompt 標準

Part 5 開發情境實戰篇

• 第 17 章 Web Application 開發實戰
• 第 18 章 Legacy System 逆向工程
• 第 19 章 Framework Upgrade
• 第 20 章 大型 Repository、Log 與基礎設施分析
• 第 21 章 測試、安全與相依性稽核

Part 6 方法論與架構篇

• 第 22 章 Context Engineering 企業級規則

Part 7 企業治理篇

• 第 23 章 資料分類與安全治理

Part 8 維運篇

• 第 24 章 日常維運
• 第 25 章 Troubleshooting

Part 9 度量與導入篇

• 第 26 章 企業自建 Benchmark
• 第 27 章 開發者使用規範
• 第 28 章 企業導入 Roadmap
• 第 29 章 導入風險分析
• 第 30 章 十大企業使用原則
• 第 31 章 Token 成本可視化與 FinOps 歸因

附錄

• 附錄 A：Context Mode Developer Cheat Sheet
• 附錄 B：Mermaid 圖表索引
• 附錄 C：指令版本對照表
• 附錄 D：官方參考資料
• 附錄 E：三項自我審查結果
• 附錄 F：新進成員總檢查清單
• 文件維護

原始 62 章需求 ↔ 本手冊章節對照表

本手冊依主題重組為 Part 分卷，以下對照表確保原始需求的 62 個項目全部落地，方便逐項驗收。

v1.1.0 新增（超出原始 62 項需求）

Part 1 概念篇：為什麼需要 Context Mode

本 Part 的目標：讓任何一位同仁——不論是 PM 還是資深後端——在讀完之後能用三句話說清楚「Context Mode 是什麼、解決什麼、什麼時候該用」。

第 1 章 Executive Summary

1.1 一句話定義

Context Mode 是一個 MCP Server，它把 AI Coding Agent 的「工具輸出」與「對話 Context」分離開來：資料在沙箱裡被處理，只有結論進入 Context Window。 [Official]

如果只能記一件事，記這張圖：

傳統做法                          Context Mode 做法
─────────────────                 ─────────────────
Tool                              Tool
 ↓                                 ↓
Huge Output（56 KB）               Sandbox（獨立 subprocess）
 ↓                                 ↓
LLM Context                       Process / Script
 ↓                                 ↓
Context Bloat                     Filter / Aggregate / Search
 ↓                                 ↓
推理品質下降                        Small Result（299 B）
                                   ↓
                                  LLM Context

1.2 它解決什麼問題

官方把問題拆成四個面向 [Official]：

第 4 點值得特別注意 [Official]：官方明確引用了 Moonshot AI 對 kimi-k2.5 的觀察——激進的簡短化提示會降低 coding / reasoning benchmark 分數。所以 Context Mode 刻意不去約束模型的輸出風格，只約束資料流向。這對企業很重要：你可以同時要求「省 Token」和「答案要完整」，這兩件事在 Context Mode 的設計裡不衝突。

1.3 為什麼 AI Agent 需要 Context Optimization

Context Window 是一個固定大小的預算，而且它同時裝著四樣東西：

1. System Prompt + 專案規則（CLAUDE.md / AGENTS.md / copilot-instructions.md）
2. 對話歷史（你問的、模型答的）
3. 工具輸出（最容易失控的一項）
4. 模型當前要生成的內容

前三項會不斷累積。當總量逼近上限時，Agent Harness 會執行 compaction——把舊訊息壓縮或丟棄。問題是：被丟掉的往往是你真正需要的工作記憶，而佔位的往往是那份你只看了一行的 45 KB log。

這就是官方說的「the other half of the context problem」：大家都在討論怎麼把 Context Window 做大（100K → 200K → 1M），很少人討論怎麼不要浪費它。

1.4 為什麼大型 Web Application 更需要

企業級 Web Application 的開發，每一個環節都會產生大量文字輸出：

每一列的「輸出量」與「真正需要的」之間，差距都是兩到三個數量級。 這個差距就是 Context Mode 的作用空間。

1.5 與傳統 MCP Server 的差異 [AI Analysis]

這是最常見的誤解，必須講清楚：

關鍵句：一般 MCP Server 是 Context 的「消費者」，Context Mode 是 Context 的「守門人」。

事實上 Context Mode 還會保護你不被其他 MCP Server 淹死——它有一個 CONTEXT_MODE_EXTERNAL_MCP_NUDGE_EVERY 設定（預設 10），每 10 次工具呼叫就重新提醒模型「把大型 external MCP payload 包進 ctx_execute」[Official]。這個設計來自真實案例：一個 session 裡打了 50+ 次 Jira / Slack / Notion MCP，提示只講一次會在 compaction 後失效。

1.6 與一般 RAG 的差異 [AI Analysis]

一句話：RAG 是「擴充知識」，Context Mode 是「節流輸入」。 兩者不互斥，企業可以同時用。

1.7 與一般 Memory 的差異 [AI Analysis]

[Official] 官方對此有明確設計：「If you don’t --continue, previous session data is deleted immediately — a fresh session means a clean slate.」新 session 就是乾淨的白紙，這對資安其實是好事（見 第 23 章）。

1.8 與 Agent Harness 的關係 [AI Analysis]

Agent Harness 指的是 Claude Code、Copilot CLI、Codex CLI、Cursor 這些「跑 Agent 的外殼」——它們負責管理對話、呼叫工具、執行 compaction、提供 Hook 生命週期。

Context Mode 不取代 Harness，而是插進 Harness 的縫隙裡：

Harness 提供的擴充點          Context Mode 插入的東西
──────────────────          ────────────────────
MCP Server 註冊機制      →   11 個 ctx_* 工具
PreToolUse Hook          →   攔截並改寫 / 阻擋高輸出工具
PostToolUse Hook         →   捕捉事件寫入 SQLite
PreCompact Hook          →   建立 ≤2 KB 的 resume snapshot
SessionStart Hook        →   注入 routing 指示 + 還原工作狀態
UserPromptSubmit Hook    →   捕捉使用者決策與修正
Stop Hook                →   記錄回合結束狀態

推論：Harness 的 Hook 能力決定了 Context Mode 能發揮多少效果。這也是為什麼同樣裝了 Context Mode，Claude Code 能拿到約 98% 的節省，而 Zed 只有約 60%——因為 Zed 根本沒有 Hook [Official]。詳見 第 9 章。

1.9 對企業 AI SDLC 的價值

最後一點常被低估 [Enterprise Recommendation]：企業導入 AI 工具最大的難題不是「工具好不好」，而是「怎麼確保 50 個開發者都照規範用」。寫在 CLAUDE.md 裡的規範，模型遵循率約 60%；用 Hook 強制執行，約 98% [Official]。這 38 個百分點就是治理能力的差距。

1.10 傳統 AI Agent vs Context Mode AI Agent 對照表

1.11 本章實務案例

情境：某銀行內部網銀專案，要查「昨天下午的 500 錯誤是不是都來自同一個 API」。

傳統做法：

開發者：幫我看一下 access.log 昨天下午的 500 錯誤
Agent：（執行 Bash: grep " 500 " access.log | tail -200）
       → 200 行 log 進入 Context（約 18 KB）
Agent：我看到有一些 500 錯誤，主要在 /api/transfer...
開發者：那 4xx 呢？
Agent：（再 grep 一次）→ 又 20 KB 進 Context

兩次查詢吃掉約 38 KB，而且 tail -200 丟掉了前面所有資料，結論其實不可靠。

Context Mode 做法：

開發者：幫我看一下 access.log 昨天下午的 500 錯誤
Agent：（呼叫 ctx_execute_file，語言 python）
       腳本在 sandbox 內全量掃描整份 log：
       - 依 status code 分組計數
       - 抽出 500 錯誤的 URI pattern 與時間分布
       - 找出 top 5 client IP
       → 只有 1.2 KB 的統計結果進入 Context
Agent：昨天 13:00-18:00 共 1,247 筆 500，其中 1,198 筆（96%）
       集中在 POST /api/transfer/verify，時間高峰 14:32-14:41，
       全部來自 payment-gateway 的 3 個內網 IP。

差異不只是省 Token，而是結論可靠度：第二種做法看的是全量資料，第一種只看了尾巴 200 行。

1.12 本章注意事項

1. 不要把 Context Mode 當成「壓縮工具」。它不是把 56 KB 壓成 5 KB，而是在沙箱裡分析 56 KB，只把 299 B 的結論送進來。原始資料還在磁碟上，隨時可以再分析。
2. 不要以為裝了就自動省 98%。沒有 Hook 的平台只有約 60%，而且該數字是官方對「指令檔遵循率」的估計 [Official]。
3. 不要在需要「編輯」檔案時用 ctx_execute_file。官方 SKILL 明確規定：要編輯的檔案用一般 Read 工具，Context Mode 只負責分析 [Official]。
4. ELv2 授權要先過法務。企業內部自用一般沒問題，但不可包裝成內部 managed service 對外（或對其他法人）提供。
5. 這是 source-available，不是 open source。採購 / 資安流程上要用「第三方元件」的標準審查，不能當成 MIT 套件隨便帶進來。

1.13 本章檢查清單

• 我能用一句話說清楚 Context Mode 和一般 MCP Server 的差別
• 我知道「98%」這個數字的實際適用範圍（ctx_execute_file 子集，非全域）
• 我知道 Context Mode 不是 RAG、不是 Memory、不取代 Agent Harness
• 我知道有無 Hook 對效果的影響（約 98% vs 約 60%）
• 我知道本專案授權是 ELv2，需要法務確認使用範圍
• 我能舉出自己工作中至少 3 個「輸出量遠大於所需資訊」的場景

第 2 章 AI Agent 的 Context Window 問題

本章是整份手冊的理論基礎。如果你不理解這一章，後面所有的「最佳實務」對你來說都只是規定，而不是原則。

2.1 Context Window

定義：LLM 在單次推理時能「看見」的 token 總量上限。

它常被誤解為「記憶體」，但更精確的比喻是一張攤開的桌面：

• 桌面大小固定（例如 200K tokens）
• 所有要用的東西都得攤在桌上，模型才看得到
• 桌子滿了，就得把東西收走（compaction）
• 收走什麼由 Harness 決定，不由你決定

Context Window 的組成：

┌─────────────────────────────────────────┐
│ System Prompt + 工具定義                 │ ← 固定成本，通常 5–20 KB
├─────────────────────────────────────────┤
│ 專案規則（CLAUDE.md / AGENTS.md）        │ ← 固定成本
├─────────────────────────────────────────┤
│ 對話歷史（user / assistant 訊息）        │ ← 線性成長
├─────────────────────────────────────────┤
│ ★ 工具輸出（Tool Results）★             │ ← 爆炸性成長，本手冊的主戰場
├─────────────────────────────────────────┤
│ 本次生成的回應                           │ ← output token
└─────────────────────────────────────────┘

關鍵認知：在一個真實的開發 session 裡，工具輸出通常佔 Context 消耗的 60–90%，而不是對話本身 [AI Analysis]。所以優化對話長度的效益遠小於優化工具輸出。

2.2 Input Token

定義：每次呼叫模型時，送進去的所有內容（含整段對話歷史與所有工具輸出）。

最重要的一件事：Input Token 每一輪都會重算。

第 1 輪：System(10K) + 對話(1K)                      = 11K input
第 2 輪：System(10K) + 對話(2K) + 工具輸出A(45K)     = 57K input
第 3 輪：System(10K) + 對話(3K) + 工具輸出A(45K)
                                + 工具輸出B(56K)     = 114K input
第 4 輪：...                                          = 170K input

那份 45 KB 的 log，不是只付一次錢，是之後每一輪都付一次。這是最多人算錯的地方。

如果一個 session 有 30 輪對話，第 2 輪進來的 45 KB log 會被重複計費大約 29 次。

[Enterprise Recommendation] 跟財務或主管解釋 AI 成本時，用這個公式： 單次工具輸出的真實成本 ≈ 輸出大小 × 剩餘輪數 × input 單價 這遠比「這次呼叫花了多少錢」更貼近真實。Prompt Caching 可以緩解但無法消除此效應（cache 有 TTL，且被 compaction 打斷後會失效）。

2.3 Output Token

定義：模型生成的內容，包含最終回答與工具呼叫的參數。

工具參數也算 output token，這點常被忽略，而且會製造一個經典陷阱：

錯誤做法：
  1. 呼叫 Playwright browser_snapshot()  → 135K tokens 進 Context（input）
  2. 把結果貼進 ctx_index(content: <135K>) → 135K tokens 再算一次（output）
  = 總共 270K tokens ★ 加倍了 ★

正確做法：
  1. browser_snapshot(filename: "/tmp/snap.md")  → 約 50 B 確認訊息
  2. ctx_index(path: "/tmp/snap.md")              → 約 80 B 確認訊息（server 端讀檔）
  3. ctx_search(queries: [...])                   → 約 300 B 命中片段
  = 總共約 430 B

[Official] 這是官方 SKILL.md 明確標記的頭號 anti-pattern：「Never use ctx_index(content: large_data). Use ctx_index(path: ...)」。content 參數只能用於你自己寫的小段文字。

2.4 Tool Output

工具輸出的本質問題：它的大小由外部世界決定，不由你決定。

你寫 kubectl get pods，可能回 5 行，也可能回 500 行——取決於叢集規模。你不能預先知道。

官方列出的實測大小 [Benchmark]：

最後一列特別值得注意：subagent 的輸出會回到主 Agent 的 Context。你派出去的研究子任務，回來的報告也在燒你的 Context。

2.5 Context Pollution

定義：Context 裡塞滿了與當前任務無關的內容，干擾模型的注意力分配。

這不只是「浪費空間」，而是主動傷害推理品質。LLM 的 attention 機制會在所有 token 之間分配權重；當 Context 裡有 45 KB 的 log 行，模型在回答「這個函式該怎麼重構」時，仍然要在那些 log 行上花注意力。

典型症狀：

• 模型開始引用不相關的內容（「根據你剛才提供的 log…」但你問的是架構）
• 模型忽略你明確給過的指示
• 模型在長 session 後期變得「遲鈍」，重複問已經回答過的問題

2.6 Context Bloat

定義：Context 使用量隨時間不斷累積、逼近上限的現象。

典型的 Context 消耗曲線（無 Context Mode）：

Context 使用率
100% ┤                                    ╭──── compaction
     │                               ╭────╯
 75% ┤                          ╭────╯
     │                    ╭─────╯
 50% ┤              ╭─────╯       ← 官方說法：30 分鐘後 40% 消失
     │        ╭─────╯
 25% ┤   ╭────╯
     │╭──╯
  0% ┼─────────────────────────────────────────→ 時間
     0    10   20   30   40   50   60 分鐘

有 Context Mode 之後，曲線變得平緩，官方宣稱 session 可用時間從約 30 分鐘延長到約 3 小時 [Benchmark]。

[Benchmark] 這個「30 分鐘 → 3 小時」是官方數字，取決於你的工作型態。如果你的工作本來就很少產生大輸出（例如純寫新程式碼、不做分析），改善幅度會小很多。企業請自行量測，方法見 第 26 章。

2.7 Context Compaction

定義：Context 逼近上限時，Harness 自動壓縮或丟棄舊訊息以騰出空間的機制。

Compaction 是必要的，但它有兩個副作用：

1. 資訊遺失：被丟掉的細節不會回來
2. 遺失的選擇權不在你手上：Harness 用的是通用策略，它不知道哪些對你重要

Context Mode 的做法是在 compaction 發生前搶先保存：

PreCompact Hook 觸發
  → 從 SQLite 讀出本次 session 所有事件
  → 依優先級建立 ≤ 2 KB 的 XML snapshot
  → 寫入 session_resume 表

（Harness 執行 compaction，舊訊息被丟棄）

SessionStart Hook 觸發（source: "compact"）
  → 取出 snapshot
  → 寫成結構化事件檔並自動索引進 FTS5
  → 組裝 Session Guide（18 類）
  → 注入 <session_knowledge> 指示
  → 模型從你的「上一個 prompt」接著做

[Official] snapshot 有 2 KB 的硬預算，超出時優先丟低優先級事件（intent 分類、MCP 工具呼叫次數），一定保留的是：active files、tasks、rules、decisions。

2.8 Agent Memory Loss

Compaction 之後 Agent 具體會忘記什麼？官方整理的捕捉清單反推出以下遺失項目 [Official]：

「使用者做了哪些決策」是體感最差的一項 [AI Analysis]。開發者對「模型忘記檔案」的容忍度很高，但對「我講過的話它忘了」會直接失去信任。這也是為什麼 UserPromptSubmit Hook 的有無，在平台評估時權重要拉高（見 第 9 章）。

2.9 Tool Output Explosion

定義：單一工具呼叫產生遠超預期的輸出量。

幾個真實的爆炸點：

Playwright browser_snapshot 官方數據：回傳 10K–135K tokens 的 accessibility tree [Official]。而且 browser_navigate 會自動夾帶一份 snapshot ——你以為你只是換頁，其實已經吃掉幾萬 token。

[Official] 官方 SKILL 明確警告：「browser_navigate returns a snapshot automatically — ignore it, use browser_snapshot(filename) for any inspection.」

大型 JSON API 官方 Try It 範例用了一個 7.5 MB / 20,000 筆紀錄的 JSON。傳統做法根本無法處理（直接超過 Context 上限）；Context Mode 的做法是在 sandbox 內解析，只回傳那筆被藏起來的紀錄，約 0.9 KB。

Maven / Gradle build output 一次完整建置的輸出動輒上萬行，其中你要的可能只是「哪 3 個模組編譯失敗、錯在第幾行」。

kubectl logs 沒加 --tail 的話，是整個 container 生命週期的 log。

git log / git diff git diff HEAD~50 在大型專案裡可能是數十萬行。

2.10 Token Cost

成本計算的三個常見錯誤 [AI Analysis]：

錯誤一：只算一次 見 2.2。一筆大輸出會在後續每一輪重複計費。

錯誤二：忽略 output token 的單價差 多數模型的 output token 單價是 input 的 3–5 倍。所以「把大資料當成工具參數傳出去」（例如 ctx_index(content: ...)）比「讓大資料進 input」更貴。

錯誤三：把 stats 的節省量直接當成省下的錢

[Official] [AI Analysis] ctx_stats 顯示的是「避免進入 Context 的資料量」，不等於實際帳單減少額。原因：

1. 那些資料本來也未必會全部被讀進去（人可能會 head -50）
2. Prompt Caching 會讓重複的 input token 折價
3. 不同模型單價不同
4. Context Mode 自身的工具定義與 routing 提示也佔 Context（CONTEXT_MODE_EXTERNAL_MCP_NUDGE_EVERY 設為 1 時，每次呼叫約增加 250 tokens）

事實上官方 issue 追蹤中就有一則回報 ctx_stats 數字自相矛盾的 bug（per-chat「kept out」2.7 MB 超過 all-projects 總計 868 KB，且零 ctx_execute 呼叫的 session 顯示 100% savings）[Community]。企業 KPI 請以自建 benchmark 為準，見 第 26 章。

2.11 Reasoning Quality

這是最難量化、但影響最大的一項。

已知的三個機制 [AI Analysis]：

1. Lost in the Middle：長 Context 中間位置的資訊，模型的取用率明顯低於開頭和結尾。你的關鍵指示如果被埋在 45 KB log 中間，等於沒說。
2. Attention 稀釋：注意力預算被無關 token 分走。
3. Compaction 造成的斷裂：壓縮後的摘要不等於原文，細節（變數名、行號、錯誤碼）流失。

而官方特別點出的第四個機制值得企業注意 [Official]：

4. 激進的簡短化提示會傷害推理。很多團隊為了省 token 在 CLAUDE.md 裡寫「回答要極簡」「不要解釋」，官方引用 Moonshot AI 對 kimi-k2.5 的觀察指出這會降低 coding / reasoning benchmark 分數。

這推導出一條重要的企業規範 [Enterprise Recommendation]： 省 Context 要從「資料流向」下手，不要從「模型話術」下手。 請檢查你們現有的 CLAUDE.md / copilot-instructions.md，把「請簡短回答」這類指令移除，改成 routing 規則。

2.12 資料有價值與資料該進 Context 是兩件事

這是本章的結論，也是整份手冊的核心命題。

  資料本身有價值
        ≠
  資料應該全部進入 Context

用一張表說清楚：

判斷準則一句話：

會被模型「引用」的東西才該進 Context；只會被「計算」的東西，交給程式。

2.13 本章實務案例

情境：某製造業 ERP 系統升級專案，要盤點 1,200 個 Java 類別中哪些還在用已被淘汰的 SimpleDateFormat。

傳統做法的失敗過程：

第 1 輪：Agent 執行 grep -r "SimpleDateFormat" src/
        → 380 筆結果，約 32 KB 進 Context
第 2 輪：開發者問「這些裡面哪些是在多執行緒環境用的？」
        → Agent 需要讀每個檔案的 class 宣告
        → 開始一個一個 Read，讀到第 40 個檔案時 Context 就滿了
第 3 輪：compaction 觸發
        → Agent 忘了原本的 380 筆清單
        → 開發者必須重新說明一次任務

Context Mode 做法：

第 1 輪：Agent 呼叫 ctx_execute（shell + python 混合）
        腳本在 sandbox 內：
        1. 掃描全部 1,200 個 .java
        2. 找出使用 SimpleDateFormat 的檔案
        3. 同時檢查該類別是否為 @Service / @Component（Spring singleton）
        4. 檢查是否宣告為 static field（執行緒不安全的關鍵徵兆）
        5. 依風險分級輸出

        → 進入 Context 的只有：
          「380 個檔案使用 SimpleDateFormat。
            高風險（Spring singleton + static field）：12 個，清單如下…
            中風險（method local，但在 @Async 方法內）：45 個…
            低風險（method local）：323 個」
        → 約 2 KB

關鍵差異：第二種做法一次呼叫就回答了第一種做法三輪都答不出來的問題，因為判斷邏輯寫在程式裡，而不是靠模型逐檔閱讀。

2.14 本章注意事項

1. Input token 會重複計費，這是成本估算最容易錯的一點。
2. 工具參數也算 token，把大資料當參數傳出去比讓它進 input 更貴。
3. ctx_stats 的節省量是觀測值，不是帳單金額，官方自己都有相關 bug 回報 [Community]。
4. 不要用「請簡短回答」來省 token，官方引用的研究指出這會傷害推理品質。
5. Playwright 的 browser_navigate 會自動夾帶 snapshot，這是隱形的 token 消耗來源。
6. Subagent 的回傳也佔主 Agent 的 Context，官方實測有 986 KB 的案例。

2.15 本章檢查清單

• 我能解釋為什麼「一次 45 KB 的 log」實際成本遠高於 45 KB
• 我知道 ctx_index(content:) 與 ctx_index(path:) 的成本差異（差一倍以上）
• 我能區分「Context Pollution」與「Context Bloat」
• 我知道 compaction 之後 Agent 會忘記哪 9 類資訊
• 我知道「使用者決策」的遺失是體感最差的一項
• 我已檢查團隊現有的 CLAUDE.md 是否有「請簡短回答」這類會傷害推理的指令
• 我能用 2.12 的表格判斷一筆資料該不該進 Context

Part 2 架構篇：Context Mode 如何運作

本 Part 的目標：讓工程師理解 Context Mode 的每一個元件在做什麼，之後遇到問題時能自己推斷是哪一層出錯，而不是只能重裝。

第 3 章 整體架構

3.1 分層總覽

flowchart TD
    User["👤 User<br/>開發者"]
    Agent["🤖 AI Coding Agent<br/>Claude Code / Copilot / Codex / Cursor …"]
    Harness["⚙️ Agent Harness<br/>對話管理 · 工具呼叫 · Compaction · Hook 生命週期"]

    subgraph CM["Context Mode（本手冊主體）"]
        direction TB
        MCP["MCP Server<br/>註冊 11 個 ctx_* 工具"]
        HookRouter["Hook Router<br/>PreToolUse / PostToolUse / PreCompact<br/>SessionStart / UserPromptSubmit / Stop"]
        Sandbox["Sandbox Executor<br/>獨立 subprocess · 12 種語言 runtime"]
        Index["Context Index<br/>Markdown chunking · 標題切分"]
        SQLite[("SQLite<br/>per-project DB")]
        FTS5["FTS5 + BM25<br/>Porter · Trigram · RRF"]
        Session["Session Memory<br/>事件捕捉 · snapshot · restore"]
        Routing["Tool Routing<br/>攔截 / 阻擋 / 改寫"]
        CLI["Utility CLI<br/>context-mode doctor / index / search / upgrade"]
    end

    subgraph EXT["External Tools（資料來源）"]
        direction LR
        FS["File System"]
        Git["Git / GitHub"]
        Browser["Browser<br/>Playwright"]
        API["API / HTTP"]
        Docker["Docker"]
        K8s["Kubernetes"]
        Test["Test Runner"]
        OtherMCP["其他 MCP Tools<br/>Jira / Slack / Notion …"]
    end

    User --> Agent
    Agent --> Harness
    Harness -->|"MCP protocol"| MCP
    Harness -->|"lifecycle events"| HookRouter
    MCP --> Sandbox
    MCP --> Index
    HookRouter --> Routing
    HookRouter --> Session
    Routing -.->|"攔截後改導"| Sandbox
    Index --> SQLite
    Session --> SQLite
    SQLite --> FTS5
    FTS5 -->|"只回傳命中片段"| MCP
    Sandbox -->|"只回傳 stdout"| MCP
    CLI --> SQLite
    Sandbox --> EXT

    style CM fill:#e8f4f8,stroke:#0366d6,stroke-width:2px
    style EXT fill:#fff5e6,stroke:#d97706,stroke-width:2px
    style Sandbox fill:#d4edda,stroke:#28a745,stroke-width:2px
    style SQLite fill:#f8d7da,stroke:#dc3545,stroke-width:2px

這張圖要看懂三條線 [AI Analysis]：

1. 藍線（MCP protocol）：Agent 主動呼叫 ctx_* 工具。這條線需要模型「願意用」。
2. 虛線（Routing 攔截）：Agent 想用 Bash / Read / WebFetch 時，Hook 在執行前攔下來。這條線不需要模型配合，是程式化強制。
3. 紅框（SQLite）：所有持久化都落在這裡。它是企業資安審查的重點對象（見 第 23 章）。

3.2 逐層說明

3.2.1 MCP Server

職責：向 Agent Harness 註冊工具清單，並處理工具呼叫請求。 [Official]

• 使用 @modelcontextprotocol/sdk（官方 package.json 依賴 ^1.26.0）
• 透過 stdio 與 Harness 溝通
• 註冊 11 個工具：6 個 sandbox 工具 + 5 個 meta 工具
• 平台自動偵測：透過 MCP handshake 的 clientInfo.name 判斷跑在哪個平台，不需人工設定

[Official] 有一個例外要注意：OpenCode 與 KiloCode 不走 MCP，而是以 TypeScript plugin 的形式 in-process 註冊工具，因此沒有額外的 stdio 子行程。這也導致一個經典陷阱：如果設定檔裡同時有 plugin: ["context-mode"] 和 mcp.context-mode，會註冊到 0 個 ctx_* 工具。詳見 13.2。

3.2.2 Hook Router

職責：接收 Harness 發出的生命週期事件，執行對應動作。 [Official]

實作形式是 CLI 子指令：

context-mode hook <platform> <event>

例如 context-mode hook claude-code pretooluse。事件資料由 Harness 透過 stdin 以 JSON 傳入，Hook 以 stdout 回傳 JSON 決定後續行為。

六個事件的職責：

[Official] 重要的設計決策：Hook 失敗是 fail-open。官方在 Copilot CLI 章節明確寫道，舊版全域 binary 會讓 hook「inert（no routing/capture）」但不會阻擋你的工具。這對企業是好消息——Context Mode 掛掉不會讓開發停擺——但也代表你不會馬上發現它壞了。這是 第 24 章 要定期跑 ctx doctor 的原因。

3.2.3 Sandbox Executor

職責：在獨立的 subprocess 內執行程式碼，只把 stdout 帶回。 [Official]

• 每次 ctx_execute 呼叫產生一個獨立的 process boundary
• 腳本之間不能互相存取記憶體或狀態（這點很重要：不要期待第二次呼叫還記得第一次的變數）
• 12 種語言 runtime：JavaScript、TypeScript、Python、Shell、Ruby、Go、Rust、PHP、Perl、R、Elixir、C#
• Bun 自動偵測，JS/TS 執行速度快 3–5 倍

[Official] 安全邊界必讀：官方自己講得很清楚——ctx_execute 與 ctx_batch_execute 執行任意程式碼，並繼承該 process 的檔案系統存取權限。專案根目錄圍籬（ctx_execute_file 的 File access blocked）是針對檔案讀取工具的縱深防禦，不是完整的 OS sandbox。

換句話說：核准一次 ctx_execute 等於核准執行任意程式碼。請保持 host 層級的 sandbox 開啟。

3.2.4 Context Index

職責：把 Markdown 內容依標題切塊，保持程式碼區塊完整，存入 FTS5。 [Official]

切塊策略的兩個重點：

• 依 heading 切分（#、##、### 為邊界）
• 程式碼區塊保持完整（不會在 ``` 中間切斷）

第二點對開發場景至關重要：文件檢索如果把 code block 切一半，回傳的範例就不能用了。

3.2.5 SQLite / FTS5

職責：持久化儲存與全文檢索。 [Official]

後端在 runtime 自動選擇：

[Official] 為什麼 Linux + Node ≥22.5 一定要用 node:sqlite？官方說明是為了避開 V8 的 madvise(MADV_DONTNEED) 破壞 addon .got.plt section 導致的偶發 SIGSEGV（nodejs/node#62515）。也因此 Linux + Node < 22.5 是官方不支援組合（#564），npm install 會直接失敗。

企業意涵：如果你的 Linux 開發機或 CI 容器還在跑 Node 20 LTS，必須先升級 Node 才能導入 Context Mode。這常常是 PoC 階段最大的卡點。

3.2.6 Session Memory

職責：捕捉 session 事件、建立 snapshot、compaction 後還原。 [Official]

詳見 第 7 章。

3.2.7 Tool Routing

職責：決定「這個工具呼叫該不該直接執行」。 [Official]

官方的 routing 政策寫在 skills/context-mode/SKILL.md 裡，核心是一份 Bash 白名單：

白名單（可直接用 Bash 執行）：
  檔案異動  mkdir、mv、cp、rm、touch、chmod
  Git 寫入  git add、git commit、git push、git checkout、git branch、git merge
  導航      cd、pwd、which
  程序控制  kill、pkill
  套件安裝  npm install、npm publish、pip install
  簡單輸出  echo、printf

其餘一律走 ctx_execute / ctx_execute_file

判斷原則一句話 [Official]：

任何會 read / query / fetch / list / log / test / build / diff / inspect / 呼叫外部服務 的指令，都走 Context Mode。包含所有 CLI（gh、aws、kubectl、docker、terraform、gcloud…）。不確定的時候，用 Context Mode。

3.2.8 Utility CLI

職責：不進 AI session 也能操作。 [Official]

context-mode doctor                                          # 診斷安裝狀態
context-mode index . --source project:my-app                 # 索引本地目錄
context-mode search "authentication middleware" --source project:my-app
context-mode upgrade                                         # 升級並修復 hook 設定
context-mode insight                                         # 開啟 hosted dashboard（企業建議停用）
context-mode statusline                                      # Claude Code 狀態列
bash scripts/ctx-debug.sh                                    # 產生完整診斷報告（回報 bug 用）

3.3 一次完整的資料流

以「分析 5,000 行的 Nginx access log」為例：

sequenceDiagram
    autonumber
    participant U as 開發者
    participant A as AI Agent
    participant H as Hook Router
    participant S as Sandbox
    participant F as File System
    participant D as SQLite

    U->>A: 「幫我看 access.log 的錯誤分布」
    A->>H: 想執行 Bash: cat access.log
    Note over H: PreToolUse 攔截<br/>cat 不在白名單
    H-->>A: 阻擋 + 提示改用 ctx_execute_file
    A->>S: ctx_execute_file(path, language=python, code=分析腳本)
    S->>F: 讀取 access.log（45 KB）
    F-->>S: FILE_CONTENT（留在 sandbox）
    Note over S: 全量掃描<br/>分組統計<br/>只 print 結論
    S-->>A: stdout：155 B 統計結果
    A->>H: PostToolUse
    H->>D: 寫入事件（檔案讀取 / 工具延遲 / MCP 使用計數）
    A-->>U: 「共 5,000 筆，其中 500 錯誤 1,247 筆，集中在 …」

    rect rgb(255, 240, 240)
    Note over F,S: 45 KB 原始資料從未進入 Context
    end

3.4 儲存位置與磁碟佔用

以下為 v1.0.169 的行為 [Official]

<root> 的決定方式：

1. 若設定 CONTEXT_MODE_DIR（v1.0.147+）→ 使用該絕對路徑
2. 否則使用 adapter 預設，例如 ~/.claude/context-mode、~/.codex/context-mode、~/.omp/context-mode

[Official] CONTEXT_MODE_DIR 的三個限制：必須絕對路徑、不展開 ~、空白字串視同未設定（且會被 ctx_doctor 標出）。

Windows 範例：CONTEXT_MODE_DIR=D:\ai\context-mode（不要用 %USERPROFILE% 以外的相對寫法）。

[Community] 已知問題：有 issue 回報 stale content DB 清理會誤刪「還活著但閒置」的 session（僅看 WAL mtime，沒做 liveness 檢查）。長時間掛著不動的 session 有遺失索引的風險。

3.5 本章實務案例

情境：SA 接手一個沒有文件的 Spring Boot 專案，想先掌握「這個系統對外開了哪些 API」。

架構層面發生了什麼：

1. SA 輸入：「列出所有 REST endpoint 與對應的權限註解」

2. Agent 原本想做：Read 每個 @RestController 檔案
   → PreToolUse（Tool Routing 層）攔截：這會產生大量讀取

3. Agent 改用 ctx_execute（Sandbox Executor 層）：
   寫一支 shell + python 腳本，掃描全部 .java，
   用正則抽出 @GetMapping/@PostMapping/@PreAuthorize

4. Sandbox 讀檔（File System 層）→ 分析 → 只 print 表格

5. 結果約 3 KB 進 Context（MCP Server 層回傳）

6. PostToolUse（Hook Router 層）把「讀取了哪些檔案」寫入 SQLite
   → 之後 compaction 時，Session Memory 層知道 SA 正在看哪個模組

六層全部參與了這一次操作。 理解分層之後，當結果不如預期時你才知道該查哪一層：

• 結果太大 → Sandbox 腳本沒做彙整（第 3 層問題）
• Agent 還是直接 Read → Hook 沒生效（第 2 層問題）
• Compaction 後忘光 → Session Memory 沒捕捉到（第 6 層問題）

3.6 本章注意事項

1. ctx_execute 不是 OS sandbox。它執行任意程式碼並繼承檔案系統權限，host 層級的沙箱必須保持開啟。
2. 每次 ctx_execute 是獨立 process，不要寫「上次那個變數」這種依賴。
3. Node 版本是硬門檻。Linux + Node < 22.5 直接不支援，PoC 前先確認開發機與 CI 的 Node 版本。
4. CONTEXT_MODE_DIR 不展開 ~，Windows 上請給完整磁碟路徑。
5. Hook 是 fail-open，壞掉不會報錯，要靠定期 ctx doctor 才發現。
6. OpenCode / KiloCode 不走 MCP，plugin 與 mcp 設定不可並存。

3.7 本章檢查清單

• 我能畫出 Context Mode 的六個核心元件與它們的關係
• 我知道「MCP 呼叫」與「Hook 攔截」是兩條不同的路徑
• 我知道所有持久化都落在本機 SQLite，位置在哪裡
• 我知道 ctx_execute 的安全邊界到哪裡（不是 OS sandbox）
• 我已確認自己的開發環境 Node 版本 ≥ 22.5
• 我知道索引內容 14 天會自動清除

第 4 章 核心設計：MCP Server 與 Tool Routing

4.1 11 個工具的分類

[Official] 官方在 Claude Code 安裝章節明確寫出：plugin 註冊「all hooks … and 11 MCP tools — six sandbox tools plus five meta-tools」。

注意一個文件不一致：README 的 Tools 對照表只列了 10 個（漏掉 ctx_insight）。本手冊採用 11 個的說法，與 Claude Code 章節、Utility Commands 章節一致。

完整的參數、範例與常見錯誤，見 第 15 章。

4.2 MCP Architecture

flowchart LR
    subgraph Harness["Agent Harness"]
        LLM["LLM"]
        ToolReg["Tool Registry"]
    end

    subgraph Transport["MCP Transport（stdio）"]
        Req["tools/call request"]
        Resp["tool result"]
    end

    subgraph Server["Context Mode MCP Server"]
        Dispatch["Tool Dispatcher"]
        Detect["Platform Detection<br/>clientInfo.name / env var"]
        Guard["Permission Guard<br/>讀 .claude/settings.json"]

        subgraph SandboxG["Sandbox Group"]
            E1["ctx_execute"]
            E2["ctx_execute_file"]
            E3["ctx_batch_execute"]
        end

        subgraph KBG["Knowledge Base Group"]
            K1["ctx_index"]
            K2["ctx_search"]
            K3["ctx_fetch_and_index"]
        end

        subgraph MetaG["Meta Group"]
            M1["ctx_stats"]
            M2["ctx_doctor"]
            M3["ctx_upgrade"]
            M4["ctx_purge"]
            M5["ctx_insight"]
        end
    end

    Proc["獨立 subprocess<br/>12 種語言"]
    DB[("SQLite + FTS5")]

    LLM --> ToolReg
    ToolReg --> Req
    Req --> Dispatch
    Dispatch --> Detect
    Dispatch --> Guard
    Guard --> SandboxG
    Guard --> KBG
    Dispatch --> MetaG
    SandboxG --> Proc
    KBG --> DB
    MetaG --> DB
    Proc -->|"只有 stdout"| Resp
    DB -->|"只有命中片段"| Resp
    Resp --> LLM

    style Guard fill:#f8d7da,stroke:#dc3545
    style Proc fill:#d4edda,stroke:#28a745
    style DB fill:#fff3cd,stroke:#ffc107

Permission Guard 這一層是企業最該注意的 [Official]：

Context Mode 沿用 Claude Code 的權限設定格式，而且所有平台都讀這份設定——即使你跑在 Gemini CLI、VS Code Copilot 或 OpenCode 上：

{
  "permissions": {
    "deny": [
      "Bash(sudo *)",
      "Bash(rm -rf /*)",
      "Read(.env)",
      "Read(**/.env*)"
    ],
    "allow": [
      "Bash(git:*)",
      "Bash(npm:*)"
    ]
  }
}

規則語意 [Official]：

• 格式是 Tool(要比對的內容)，* 代表「任意」
• deny 永遠勝過 allow
• 專案層級規則覆蓋全域規則
• 用 &&、;、| 串接的指令會拆開逐段檢查——echo hello && sudo rm -rf /tmp 會因為 sudo 那段被擋
• 零設定時不啟用：沒設定任何規則，行為不變

[Enterprise Recommendation] 這代表你可以用一份 ~/.claude/settings.json 同時治理多個 AI 平台的沙箱行為。把它納入企業標準設定，詳見 14.2。

4.3 Tool Output Routing 決策流

flowchart TD
    Start["Agent 準備呼叫工具"] --> Check{"PreToolUse Hook<br/>攔截"}

    Check -->|"白名單指令<br/>mkdir/mv/git commit/echo"| Direct["直接執行 Bash"]
    Check -->|"讀檔 / 查詢 / 建置 / 外部呼叫"| Deny{"平台支援<br/>阻擋？"}

    Deny -->|"是<br/>Claude Code 等"| Block["阻擋 + 回傳 reason<br/>引導改用 ctx_*"]
    Deny -->|"否<br/>Zed / Antigravity IDE"| Rule["僅靠指令檔提示<br/>約 60% 遵循率"]

    Block --> Route{"資料型態？"}
    Rule --> Route

    Route -->|"指令輸出"| Exec["ctx_execute"]
    Route -->|"本地檔案"| ExecF["ctx_execute_file"]
    Route -->|"多個指令/查詢"| Batch["ctx_batch_execute"]
    Route -->|"外部文件 URL"| Fetch["ctx_fetch_and_index"]
    Route -->|"已存檔的大型輸出"| Index["ctx_index(path) → ctx_search"]

    Exec --> Sandbox["Sandbox subprocess"]
    ExecF --> Sandbox
    Batch --> Sandbox
    Fetch --> FTS["FTS5 索引"]
    Index --> FTS

    Sandbox --> Size{"stdout > 5 KB<br/>且有 intent？"}
    Size -->|"是"| Smart["Intent-driven filtering<br/>索引全文 → 依 intent 搜尋<br/>只回相關段落 + 可搜尋詞彙"]
    Size -->|"否"| Out["stdout 直接回傳"]

    FTS --> Hit["只回傳命中片段"]
    Smart --> Ctx["✅ 進入 Context"]
    Out --> Ctx
    Hit --> Ctx
    Direct --> Ctx

    style Block fill:#f8d7da,stroke:#dc3545
    style Rule fill:#fff3cd,stroke:#ffc107
    style Sandbox fill:#d4edda,stroke:#28a745
    style Ctx fill:#cce5ff,stroke:#0366d6

4.4 Intent-driven Filtering

[Official] 當 sandbox 輸出超過 5 KB 且呼叫時有提供 intent，Context Mode 不會直接回傳，而是：

1. 把完整輸出索引進知識庫
2. 依 intent 搜尋相關段落
3. 只回傳命中結果 + 一份可供後續查詢的詞彙表

這是一個重要但容易被忽略的機制：它讓「腳本寫得不夠精簡」這個常見錯誤有了安全網。開發者的腳本如果 print 了太多東西，Context Mode 會自動幫忙收斂。

[Enterprise Recommendation] 團隊規範應要求：呼叫 ctx_execute 時盡量帶 intent 參數。這是零成本的保險。

4.5 Progressive Throttling（漸進式節流）

[Official] ctx_search 有一個防濫用機制：

設計意圖 [AI Analysis]：模型有個壞習慣——一個問題查不到就換個關鍵字再查一次，查十次。每次 round trip 都有固定成本（工具定義 + 參數 + 回傳格式）。節流機制強迫模型把問題想清楚，一次批次查完。

對應的開發規範 [Official]：官方 SKILL 明確要求「Always use queries array — batch ALL search questions in ONE call … NEVER make multiple separate ctx_search() calls」。

4.6 平台偵測機制

[Official] Context Mode 需要知道自己跑在哪個平台，才能用對的 hook 格式與儲存路徑。偵測順序大致為：

1. 環境變數強制指定：CONTEXT_MODE_PLATFORM（例如 Copilot CLI plugin bundle 會釘 copilot-cli）
2. MCP handshake 的 clientInfo.name（例如 GitHub Copilot CLI、qwen-cli-mcp-client-*）
3. 平台專屬環境變數（QWEN_PROJECT_DIR、PI_CODING_AGENT_DIR）
4. Context Mode 自己寫過的標記檔（如 ~/.copilot/mcp-config.json）

[Community] 企業常見雷區：當一台機器同時裝了 Claude Code 和其他 Agent，~/.claude/ 的存在會讓偵測結果偏向 Claude Code（#774、#775）。

解法：在該平台的 MCP 設定裡明確釘住平台：

{
  "mcpServers": {
    "context-mode": {
      "command": "context-mode",
      "env": { "CONTEXT_MODE_PLATFORM": "copilot-cli" }
    }
  }
}

這在企業環境幾乎是必做設定，因為多數開發者機器上不會只有一個 AI Agent。

4.7 本章實務案例

情境：某團隊導入後抱怨「Context Mode 好像沒作用，Agent 還是一直 Read 檔案」。

診斷過程（依 routing 決策流逐層檢查）：

# 1. MCP 有沒有連上？
context-mode doctor

# 2. 平台偵測對不對？（這台機器同時有 Claude Code 與 Copilot CLI）
#    doctor 輸出顯示 platform = claude-code，但他們實際用的是 Copilot CLI
#    → 找到根因：偵測錯平台，hook 寫到錯的位置

修正：在 ~/.copilot/mcp-config.json 的 context-mode 項目加上 "env": { "CONTEXT_MODE_PLATFORM": "copilot-cli" }，重啟後 ctx doctor 顯示正確平台，routing 恢復。

這個案例說明：「Context 沒降低」這個症狀，有一半以上的根因是平台偵測或 hook 註冊錯誤，而不是模型不配合。

4.8 本章注意事項

1. 官方文件本身對工具數量有不一致（10 vs 11），以 11 個為準。
2. 權限設定用 Claude Code 格式，但所有平台都吃。這是優點也是陷阱——在 Gemini CLI 上排查權限問題時，要記得去看 .claude/settings.json。
3. 多 Agent 共存機器必須釘 CONTEXT_MODE_PLATFORM，否則偵測會偏向 Claude Code。
4. ctx_search 有節流，不要讓模型養成多次試探的習慣，要教它一次批次查完。
5. intent 參數是免費的保險，團隊規範應強制帶上。

4.9 本章檢查清單

• 我知道 11 個工具分成 sandbox / meta 兩類，各自的用途
• 我知道權限設定寫在 .claude/settings.json，且 deny 勝過 allow
• 我知道串接指令（&&、;、|）會被拆開逐段檢查
• 我的機器如果有多個 Agent，已設定 CONTEXT_MODE_PLATFORM
• 我知道 ctx_search 第 9 次呼叫會被封鎖
• 我知道輸出超過 5 KB 且帶 intent 時會自動轉為檢索模式

第 5 章 Sandbox 與 Think in Code

這一章是 Context Mode 的方法論核心。工具會改版，但這個思維方式不會過時。

5.1 Sandbox 到底做了什麼

傳統做法                              Context Mode 做法
────────────                          ─────────────────
Tool                                  Tool
 ↓                                     ↓
Huge Output                           Sandbox（獨立 subprocess）
 ↓                                     ↓
LLM Context                           Process / Script
 ↓                                     ↓
Context Bloat                         Filter / Aggregate / Search
                                       ↓
                                      Small Result
                                       ↓
                                      LLM Context

技術上的三個保證 [Official]：

1. Process boundary：每次呼叫獨立 subprocess，腳本間無法互相存取記憶體或狀態
2. 只有 stdout 進 Context：原始資料（log、API response、snapshot）從不離開 sandbox
3. 憑證透傳：gh、aws、gcloud、kubectl、docker 等已登入的 CLI 可直接用——它們繼承環境變數與設定檔路徑，但這些憑證不會進入對話

第 3 點對企業特別重要 [AI Analysis]：它讓「AI 幫我查 production K8s 狀態」變成可行——憑證留在環境裡，只有查詢結果進 Context。但這同時也意味著 AI 可以用你的身分執行任何該 CLI 能做的事，包含刪除。權限治理見 第 23 章。

5.2 12 種語言與選用原則

[Official] 支援：JavaScript、TypeScript、Python、Shell、Ruby、Go、Rust、PHP、Perl、R、Elixir、C#。Bun 會被自動偵測用於加速 JS/TS（3–5 倍）。

官方 SKILL 給的選用建議 [Official]：

[Enterprise Recommendation] 對台灣企業常見的 Java / .NET 技術棧，補充建議：

• 分析 Maven / Gradle 輸出 → shell（純文字處理）或 python（要做結構化統計）
• 解析 pom.xml / .csproj XML → python（xml.etree）
• 掃描 Java source 做靜態統計 → python（正則）或 shell（grep -c）
• 不建議用 csharp / go / rust 跑分析腳本：啟動成本高，且這些 runtime 未必裝在每台開發機上

5.3 Think in Code：核心方法論

LLM 不該是「大量資料的搬運工」，而該是「程式與分析策略的設計者」。

這句話的具體操作方式：

❌ 不要這樣：
   Read 100 files
   ↓
   100 個檔案內容全部進 Context
   ↓
   模型「肉眼」逐檔閱讀、心算統計
   ↓
   Context 爆掉，而且統計可能算錯

✅ 要這樣：
   Execute script
   ↓
   腳本在 sandbox 內分析 100 個檔案
   ↓
   Return only summary
   ↓
   只有結論進 Context，而且數字是程式算的，不會錯

官方給的對照範例 [Official]：

// Before: 47 × Read() = 700 KB.  After: 1 × ctx_execute() = 3.6 KB.
ctx_execute("javascript", `
  const files = fs.readdirSync('src').filter(f => f.endsWith('.ts'));
  files.forEach(f => console.log(f + ': ' + fs.readFileSync('src/'+f,'utf8').split('\\n').length + ' lines'));
`);

5.4 Think in Code 的四條紀律

[Official] 這四條直接來自官方 SKILL 的 Critical Rules，是最容易被忽略卻最影響效果的部分。

紀律一：一定要 console.log / print 你的發現

stdout 是唯一會進 Context 的東西。沒有輸出 = 這次呼叫白做了。

紀律二：寫「分析程式」，不是「傾印程式」

// ❌ 錯誤：只是把資料搬個位置，Context 一樣爆
console.log(JSON.stringify(data));

// ✅ 正確：先分析，只印結論
const errors = data.filter(d => d.status >= 500);
const byPath = {};
errors.forEach(e => byPath[e.path] = (byPath[e.path] || 0) + 1);
console.log(`共 ${data.length} 筆，5xx ${errors.length} 筆`);
Object.entries(byPath).sort((a,b) => b[1]-a[1]).slice(0,5)
  .forEach(([p,c]) => console.log(`  ${p}: ${c}`));

紀律三：輸出要具體

不要只印數量，要印可行動的細節：bug 的 ID、行號、確切數值。

❌ 「發現 3 個問題」
✅ 「Order #10233 quantity=-5（負數）；Order #10891 customer=null；
    Order #11002 total 與 items 加總不符（顯示 1200，實算 1150）」

紀律四：要「編輯」的檔案不要用 Context Mode

ctx_execute_file 是給「分析」用的。
要修改的檔案，用 Agent 原生的 Read / Edit 工具。

5.5 常見的三種錯誤用法

[Official] 全部出自官方 anti-patterns 清單。

錯誤一：在 sandbox 裡就先過濾掉資料

// ❌ 錯誤：上游先截斷，索引就看不到被丟掉的部分
ctx_execute("shell", "cat huge.log | head -100")

官方的說法是：ctx_execute 負責「捕捉」，ctx_search 負責「過濾」，把兩層合併會讓 index 永遠看不到被丟掉的資料。正確做法是讓腳本處理全量，再用 intent / search 收斂。

錯誤二：ctx_index(content: 大資料)

❌ browser_snapshot() → ctx_index(content: 那 135K)  = 270K tokens（加倍）
✅ browser_snapshot(filename) → ctx_index(path)       = 約 130 B

錯誤三：把已經在 Context 裡的資料再索引一次

如果某個 MCP 工具（Context7、GitHub API）上一輪已經回傳了內容，那些內容已經在 Context 裡了。再呼叫 ctx_index(content: 那份內容) 等於付兩次錢。直接用就好。

5.6 Playwright 的三種正確工作流

[Official] 因為 Playwright 是最大的 Context 殺手（10K–135K tokens），官方給了三套標準流程。

Workflow A：多次查詢 → 索引後搜尋

1. browser_snapshot(filename: "/tmp/snap.md")     → 約 50 B 確認
2. ctx_index(path: "/tmp/snap.md", source: "Playwright snapshot")
                                                   → 約 80 B 確認
3. ctx_search(queries: ["login form email password"], source: "Playwright")
                                                   → 約 300 B 命中片段
合計約 430 B（原本 135K tokens）

Workflow B：一次性抽取 → sandbox 處理

1. browser_snapshot(filename: "/tmp/snap.md")     → 約 50 B
2. ctx_execute_file(path: "/tmp/snap.md", language: "javascript", code: "
     const links = [...FILE_CONTENT.matchAll(/- link \"([^\"]+)\"/g)].map(m => m[1]);
     const buttons = [...FILE_CONTENT.matchAll(/- button \"([^\"]+)\"/g)].map(m => m[1]);
     console.log('Links:', links.length, '| Buttons:', buttons.length);
   ")                                              → 約 200 B
合計約 250 B

Workflow C：console / network

browser_console_messages(level: "error", filename: "/tmp/console.md")
  → ctx_execute_file(path: "/tmp/console.md", ...)

browser_network_requests(includeStatic: false, filename: "/tmp/network.md")
  → ctx_execute_file(path: "/tmp/network.md", ...)

四種做法的成本對照 [Official]：

[Official] 兩個額外警告：

1. browser_navigate 會自動回傳 snapshot —— 忽略它，要檢視頁面請另外呼叫 browser_snapshot(filename)
2. Playwright MCP 使用單一 browser instance，不是 parallel-safe —— 要平行處理請改用 agent-browser 透過 ctx_execute 執行

5.7 本章實務案例

情境：QA 要驗證某網銀頁面改版後，所有表單欄位的 aria-label 是否齊全（無障礙合規）。

Think in Code 的思考過程：

問題：這是「計算問題」還是「引用問題」？
→ 需要把每個欄位逐一比對，是計算問題
→ 所以應該寫程式，不是讓模型逐行讀 snapshot

實作：

1. browser_snapshot(filename: "D:/tmp/page.md")

2. ctx_execute_file(
     path: "D:/tmp/page.md",
     language: "python",
     intent: "找出缺少 aria-label 的互動元素",
     code: '''
import re
lines = FILE_CONTENT.split("\\n")
interactive = [l for l in lines
               if re.search(r"- (textbox|button|checkbox|radio|combobox)", l)]
missing = [l.strip() for l in interactive if "aria-label" not in l and '"' not in l]
print(f"互動元素共 {len(interactive)} 個，疑似缺少可及名稱 {len(missing)} 個：")
for m in missing[:20]:
    print("  " + m)
     '''
   )

結果：約 400 B 進 Context，涵蓋整份 56 KB 的 snapshot，而且判斷邏輯可重複、可版控、可交給 CI 跑。

這裡有個延伸價值 [Enterprise Recommendation]：這段腳本可以直接抽出來變成 QA 團隊的標準檢查腳本，存進 repo。Context Mode 逼你把「檢查邏輯」寫成程式碼，而程式碼是可以累積的資產；模型的「肉眼判斷」不是。

5.8 本章注意事項

1. 沒有 print / console.log 就等於沒做事。這是新手最常見的錯誤。
2. 不要在腳本裡先 head / tail 截斷，會讓後續索引看不到完整資料。
3. 要編輯的檔案用一般 Read，不要用 ctx_execute_file。
4. ctx_execute 可執行任意程式碼，等同於給 AI 一個 shell。企業必須搭配 permissions.deny 與 host sandbox。
5. Playwright 的 filename 參數是必填紀律，漏掉一次就浪費整個 session 的節省。
6. 每次呼叫是獨立 process，不要寫跨呼叫的狀態依賴。

5.9 本章檢查清單

• 我能說明 sandbox 的三個保證（process boundary、只有 stdout、憑證透傳）
• 我理解「Think in Code」不是省 token 技巧，而是把判斷邏輯程式化
• 我知道 Think in Code 的四條紀律，特別是「一定要 print」
• 我知道 ctx_index(content:) 會讓成本加倍
• 我熟記 Playwright 三種工作流，並知道 browser_navigate 的隱形成本
• 我知道自己團隊的技術棧該用哪種語言寫分析腳本

第 6 章 FTS5 與 Persistent Knowledge

6.1 為什麼選 SQLite FTS5 而不是 Vector DB

[AI Analysis] 這是一個值得企業理解的架構取捨：

結論：開發場景的檢索目標多半是精確的識別字——函式名、錯誤碼、套件版本、API 路徑。這些東西用關鍵字檢索比語意檢索更準。而且純本地不外流，對金融業是決定性優勢。

6.2 索引流程

flowchart LR
    Src["來源<br/>本地檔案 / URL / 工具輸出"]
    Conv["HTML → Markdown<br/>turndown + GFM plugin"]
    Chunk["Chunking<br/>依 heading 切分<br/>程式碼區塊保持完整"]
    Store[("SQLite<br/>FTS5 virtual table")]

    subgraph Tok["雙 tokenizer 索引"]
        P["Porter Stemmer<br/>running/runs/ran → run"]
        T["Trigram<br/>useEff → useEffect"]
    end

    Src --> Conv --> Chunk --> Store
    Store --> P
    Store --> T

    style Store fill:#fff3cd,stroke:#ffc107

兩個設計細節值得注意 [Official]：

1. 程式碼區塊不會被切斷。這是為什麼官方 BENCHMARK 說 ctx_index + ctx_search 的節省率只有 82%——它刻意保留完整程式碼，不做摘要。這是特性不是缺陷。
2. 標題與 heading 在 BM25 計分中權重 5 倍，讓「找某個章節」這種導航型查詢更準。

6.3 檢索流程：RRF 雙路徑融合

flowchart TD
    Q["查詢字串<br/>ctx_search(queries: [...])"]
    Fuzzy{"Levenshtein<br/>拼字修正"}
    Q --> Fuzzy
    Fuzzy -->|"kuberntes → kubernetes"| Split

    Split["同時執行兩種策略"]

    subgraph S1["策略一：Porter Stemming"]
        P1["FTS5 MATCH<br/>porter tokenizer"]
        P2["caching 命中 cached / caches / cach"]
        P1 --> P2
    end

    subgraph S2["策略二：Trigram Substring"]
        T1["FTS5 MATCH<br/>trigram tokenizer"]
        T2["useEff 命中 useEffect<br/>authenticat 命中 authentication"]
        T1 --> T2
    end

    Split --> S1
    Split --> S2

    BM25A["BM25 排名<br/>標題權重 5x"]
    BM25B["BM25 排名"]
    S1 --> BM25A
    S2 --> BM25B

    RRF["Reciprocal Rank Fusion<br/>合併兩份排名<br/>兩邊都高分的排更前面"]
    BM25A --> RRF
    BM25B --> RRF

    Prox["Proximity Reranking<br/>多詞查詢時<br/>詞距近的加分"]
    RRF --> Prox

    Snip["Smart Snippets<br/>圍繞命中詞抽取視窗<br/>不是從頭截斷"]
    Prox --> Snip

    Out["✅ 回傳相關片段<br/>程式碼區塊完整保留"]
    Snip --> Out

    style RRF fill:#d4edda,stroke:#28a745,stroke-width:2px
    style Out fill:#cce5ff,stroke:#0366d6

五個機制的白話解釋 [Official]：

6.4 查詢策略（給開發者的實用建議）

[Official] 直接來自官方 SKILL：

1. BM25 是 OR 語意 —— 命中越多詞的結果排越前面，不需要刻意用 AND
2. 每個 query 用 2–4 個具體技術詞，不要寫成一整句話
3. 多份文件並存時一定要用 source 參數，避免跨來源污染
   • 支援部分比對：source: "Node" 會命中 "Node.js v22 CHANGELOG"
4. 一定要用 queries 陣列批次查詢

✅ ctx_search(queries: ["transform pipe", "refine superRefine", "coerce codec"], source: "Zod")
❌ ctx_search(query: "transform pipe")   ← 然後又呼叫兩次

6.5 TTL Cache

[Official] ctx_fetch_and_index 的快取機制：

TTL 的實務設定建議 [Enterprise Recommendation]：

[Official] 這個機制讓 --continue 的 session 保留索引過的文件，重啟不用重抓。

6.6 Large Output Externalization（大型輸出外部化）

[Official] 這是官方 BENCHMARK.md 明列的第三類機制（21 個情境 = 14 個 ctx_execute_file ＋ 6 個 ctx_index／ctx_search ＋ 1 個 externalization pattern），但在多數中文介紹中被略過。

機制

當工具輸出超過 100 KB 時，Context Mode 不會把內容送進 Context，也不會單純截斷， 而是自動把整份輸出索引進 FTS5，只回傳一個 pointer：

工具輸出 > 100 KB
      ↓
自動寫入 FTS5（完整保留，不摘要、不截斷）
      ↓
Context 只收到 pointer：
  「輸出已外部化，共 N 個 chunk，使用 ctx_search 查詢」
      ↓
模型依需要用 ctx_search 取回命中的片段

為什麼這個設計重要 [AI Analysis]

它處理的是 2.9 Tool Output Explosion 最惡劣的情況—— 你事前不知道輸出會多大。沒有這層保護時，一個 kubectl get events -A 或一份 production log dump 就足以塞爆整個 Context Window；有了它，最糟情況也只是多花一次 ctx_search。

實務上要注意的三件事

1. 它是保護網，不是使用策略。 正確做法仍然是主動用 ctx_execute 在 sandbox 內先聚合 （見 第 5 章）。依賴 externalization 等於每次都先付一次 「寫入 FTS5 + 查詢」的成本。
2. 外部化的內容一樣受 14 天保留期與資料分類規範約束。 如果那份輸出含敏感資料， 它現在完整地躺在本機 SQLite 裡——這點與 ctx_index 完全相同，見 23.1。
3. 這是知識檢索路徑的節省率只有 82% 的原因之一：它刻意不做摘要，完整保留原文。 這是優點，但別拿去當 KPI（見 第 26 章）。

6.7 「把資料保存起來」≠「把資料放進 Context」

這是本章最重要的觀念，也是最多人搞混的地方。

❌ 錯誤心智模型：
   Raw Data ─────────────────────────────→ Context
   （反正都要用，先全部載入）

✅ 正確心智模型：
   Raw Data
      ↓
   SQLite / FTS5       ← 保存在這裡，磁碟上，不佔 Context
      ↓
   Search              ← 需要時才查
      ↓
   Relevant Result     ← 只有命中的片段
      ↓
   Context             ← 只有這一步才花錢

6.8 本章實務案例

情境：團隊要把 Spring Boot 3.2 升到 3.4，需要查閱官方 release notes 與 migration guide。

傳統做法：

WebFetch 官方 migration guide → 整頁 60 KB 進 Context
WebFetch release notes 3.3    → 又 40 KB
WebFetch release notes 3.4    → 又 45 KB
= 145 KB，而且每輪重複計費

Context Mode 做法：

1. ctx_fetch_and_index(
     requests: [
       { url: "https://.../spring-boot-3.3-release-notes", source: "SpringBoot 3.3" },
       { url: "https://.../spring-boot-3.4-release-notes", source: "SpringBoot 3.4" },
       { url: "https://.../migration-guide",               source: "SpringBoot Migration" }
     ],
     concurrency: 3,
     ttl: 604800000   // 7 天，release notes 不會變
   )
   → 三份文件平行抓取並索引，約 120 B 確認訊息進 Context

2. ctx_search(
     queries: ["deprecated removed", "breaking change configuration property",
               "Jakarta EE namespace", "auto-configuration change"],
     source: "SpringBoot"
   )
   → 只有命中的片段進 Context，約 3 KB，而且程式碼範例完整

3. 隔天再查別的主題 → TTL 內，不重抓，直接 search

關鍵收益不只是省 token：第 3 步「隔天再查」在傳統做法要重抓 145 KB，在 Context Mode 是零成本。一份索引，全 session 反覆查。

6.9 本章注意事項

1. FTS5 是關鍵字檢索，不是語意檢索。查「怎麼處理錯誤」可能不如查 exception handler @ControllerAdvice 準。
2. source 參數不加，多份文件會互相污染。這是搜尋結果不準的頭號原因。
3. ctx_index + ctx_search 的節省率官方只有 82%，因為它保留完整程式碼。不要拿 98% 去期待它。
4. 內容 14 天會自動清除，不要把它當長期知識庫用。長期知識請放 repo 裡的文件或正式的 RAG 系統。
5. [Community] 已知有「清理誤刪 live-but-idle session」的 issue，長時間閒置的 session 有風險。
6. 外部文件一律用 ctx_fetch_and_index，官方明確規定不要對你不擁有的套件用 cat 或本地路徑。

6.10 本章檢查清單

• 我知道為什麼這裡用 FTS5 而不是 Vector DB
• 我知道 RRF 是把 Porter 與 Trigram 兩種策略融合，不是二選一
• 我會用 queries 陣列一次批次查詢，而不是連續呼叫
• 我會在多份文件並存時加上 source 參數
• 我知道 TTL 預設 24 小時，可依內容型態調整
• 我能解釋「保存」與「放進 Context」的差別
• 我知道索引內容 14 天後會消失，不可當長期知識庫

第 7 章 Session Continuity

7.1 六個 Hook 的職責

[Official] 官方稱 session continuity 需要「5 hooks working together」，但實際列出的事件有 6 個（含 Stop）。本手冊列出全部 6 個。

7.2 完整的 Session Continuity 流程

sequenceDiagram
    autonumber
    participant U as 開發者
    participant H as Agent Harness
    participant CM as Context Mode Hook
    participant DB as SQLite
    participant M as LLM

    Note over U,M: ── 階段 1：Session 啟動 ──
    U->>H: 啟動 Agent
    H->>CM: SessionStart（source: "startup"）
    CM->>DB: 查詢是否有未消費的 snapshot
    DB-->>CM: 無（全新 session）
    CM-->>H: 注入 routing block
    H->>M: System prompt + routing 指示

    Note over U,M: ── 階段 2：正常工作 ──
    U->>H: 「幫我重構 OrderService，不要用 Lombok」
    H->>CM: UserPromptSubmit
    CM->>DB: 寫入 prompt(P1) + decision「不要用 Lombok」(P2)
    M->>H: 呼叫工具（Read / Edit / Bash …）
    H->>CM: PreToolUse
    CM-->>H: 允許 / 阻擋 / 改導
    H->>CM: PostToolUse
    CM->>DB: 寫入 file_edit / git_op / error / task 事件
    H->>CM: Stop（回合結束）
    CM->>DB: 寫入回合狀態

    Note over U,M: ── 階段 3：Context 逼近上限 ──
    H->>CM: PreCompact
    CM->>DB: 讀取本 session 全部事件
    Note over CM: 依優先級組裝<br/>P1 critical 一定保留<br/>P4 low 先丟<br/>總量 ≤ 2 KB
    CM->>DB: 寫入 session_resume 表
    H->>H: 執行 compaction（舊訊息被丟棄）

    Note over U,M: ── 階段 4：還原 ──
    H->>CM: SessionStart（source: "compact"）
    CM->>DB: 取出 snapshot
    CM->>DB: 寫成結構化事件檔 → 自動索引進 FTS5
    Note over CM: 組裝 Session Guide（18 類）
    CM-->>H: 注入 &lt;session_knowledge&gt; 指示
    H->>M: 帶著工作狀態繼續
    M-->>U: 從你上一個 prompt 接著做<br/>（記得「不要用 Lombok」）

    rect rgb(230, 255, 230)
    Note over CM,DB: 詳細事件仍在 FTS5 裡<br/>需要時可用 ctx_search 回查
    end

7.3 捕捉了哪些事件

[Official] 官方的完整事件表，依優先級分四層。這張表決定了 compaction 後什麼會被保住：

企業解讀 [AI Analysis]：注意 Decisions、Constraints、Rejected Approaches 三項都是 P2。這三項是「人的判斷」，重建成本最高——檔案可以重新掃，但「我們三個月前決定不用這個方案，因為 A 系統不支援」這種知識，忘了就真的忘了。

這推導出一條規範：選平台時，UserPromptSubmit 的有無應該是高權重指標，因為 Decisions 和 Blockers 都靠它。目前只有 Claude Code、GitHub Copilot CLI、Codex CLI、OpenCode、KiloCode 有（後兩者透過 chat.message 代理）[Official]。

7.4 Session Guide：還原後模型看到什麼

[Official] Compaction 之後注入的是一份結構化敘事，共 18 類：

[Official] 除了這份 Guide，詳細事件也被索引進 FTS5，模型可以用 ctx_search 隨時回查更細的內容。這是「摘要 + 可深掘」的雙層設計。

7.5 /resume 與非最新 session 的處理

[Official] 一個容易忽略但實用的細節：用 /resume <picker> 選一個不是最新的對話時，SessionStart Hook 會偵測到「這個新 session id 的 live-event 表是空的」，於是 fallback 到該專案最近一筆未被消費的 snapshot（session_resume 表）。

也就是說：picker 選對話，Context Mode 負責把工作狀態灌回去。

7.6 平台差異：不要假設每個平台都一樣

這是本章最重要的警告 [Official]

絕對不能假設所有平台都有完整的生命週期 Hook。 官方的 session completeness 評級：

幾個具體的坑 [Official]：

• Cursor：sessionStart 被 Cursor 的 validator 拒絕（forum 回報），compaction 後無法還原
• Kiro：agentSpawn（等同 SessionStart）尚未接上，同樣無法還原
• Gemini CLI / VS Code / JetBrains Copilot：沒有 UserPromptSubmit，所以使用者決策不會被捕捉——檔案異動、git、錯誤、任務都有，但「你說過不要用 Lombok」這件事沒有
• Codex CLI：PreCompact 是 runtime-gated，在 Codex CLI 0.130.0 有，舊版沒有
• Antigravity IDE / Zed：完全沒有 hook，沒有任何 session 追蹤

[Enterprise Recommendation] 企業選型時，把「session completeness」當成硬指標。如果團隊的工作型態是長時間、多輪次的複雜任務（例如 legacy 系統分析），Partial 以下的平台不建議作為主力。

7.7 本章實務案例

情境：某壽險系統的保單計算模組重構，預估 4 小時的工作。

沒有 Session Continuity 的實際情況：

09:00  開發者：「重構 PolicyCalculator，注意我們的規則是
              保費計算一律用 BigDecimal，不可以用 double」
09:40  Context 滿了 → compaction
09:41  Agent：「請問這個專案有什麼特殊的計算規則嗎？」
       ← 開發者要重講一次
10:20  再次 compaction
10:21  Agent 產出的程式碼用了 double
       ← 開發者要再講第三次，並且 code review 抓到 bug

有 Session Continuity 的情況：

09:00  開發者：「重構 PolicyCalculator，一律用 BigDecimal，不可以用 double」
       → UserPromptSubmit 捕捉為 decision（P2 High）
09:40  PreCompact → snapshot 保留該 decision
09:41  SessionStart → Session Guide 的 Key Decisions 區塊寫著
       「一律用 BigDecimal，不可以用 double」
       → Agent 繼續工作，沒有中斷
12:00  任務完成，開發者全程沒有重複交代任何規則

量化差異 [Enterprise Recommendation]：這個案例裡真正省下的不是 token，是開發者重複交代的時間與因遺忘導致的 rework。建議企業把 Session continuity rate 與 Rework rate 一起納入 KPI（見 26.3）。

7.8 本章注意事項

1. UserPromptSubmit 是最關鍵的 Hook，但支援的平台最少。選型時務必確認。
2. snapshot 只有 2 KB，P3/P4 事件在預算緊張時會被丟掉。不要依賴它保存細節，細節要靠 ctx_search 回查。
3. 不 --continue 就會立刻刪除前次 session 資料。這是刻意設計（clean slate），但也代表不要把它當備份機制。
4. Cursor 與 Kiro 目前無法還原，這是上游平台的限制，不是設定問題。
5. Codex 的 PreCompact 依 runtime 版本而定，升級 Codex 可能改變行為。
6. [Community] 已知 issue：注入的 session_continuity / priority_instructions 框架會觸發 Claude Code 的 auto-mode classifier，導致第三方 plugin 的 subagent 派送被擋。若遇到 subagent 無法派送，這是已知原因之一。

7.9 本章檢查清單

• 我能說出 6 個 Hook 各自的職責
• 我知道 P1 與 P2 事件分別有哪些，哪些在 compaction 後一定保留
• 我知道我使用的平台是 Full / High / Partial / 無
• 我知道我的平台有沒有 UserPromptSubmit（決定會不會忘記我的決策）
• 我知道 snapshot 只有 2 KB，細節要靠 ctx_search 回查
• 我知道不用 --continue 就會清空前次 session

第 8 章 MCP + Hooks：Routing Enforcement

8.1 為什麼單靠 MCP 不夠

這是整個架構最關鍵的設計論證 [AI Analysis]：

只有 MCP：
  ┌──────────────────────────────────────┐
  │ Agent 知道有 ctx_execute 這個工具     │
  │ 但它也還有 Bash / Read / WebFetch    │
  │ 用哪一個？—— 模型自己決定             │
  └──────────────────────────────────────┘
                 ↓
         遵循率約 60% [Official]
                 ↓
  一次沒遵循的 curl 或 Playwright snapshot
  就能倒灌 56 KB，抵銷整個 session 的節省

MCP + Hooks：
  ┌──────────────────────────────────────┐
  │ Agent 想用 Bash: curl ...            │
  │      ↓                               │
  │ PreToolUse Hook 攔截                 │
  │      ↓                               │
  │ 回傳 permissionDecision: "deny"      │
  │ + reason: 「請改用 ctx_execute」      │
  │      ↓                               │
  │ 工具根本沒執行                        │
  └──────────────────────────────────────┘
                 ↓
         遵循率約 98% [Official]

[Official] 官方對這個差距講得很直白：「Hooks intercept tool calls programmatically — they can block dangerous commands and redirect them to the sandbox before execution. Instruction files guide the model via prompt instructions but cannot block anything. Always enable hooks where supported.」

8.2 Hook Architecture

flowchart TD
    subgraph HarnessL["Agent Harness 生命週期"]
        direction TB
        E1["SessionStart"]
        E2["UserPromptSubmit"]
        E3["PreToolUse"]
        E4["（工具執行）"]
        E5["PostToolUse"]
        E6["Stop"]
        E7["PreCompact"]
        E1 --> E2 --> E3 --> E4 --> E5 --> E6
        E6 -.->|"Context 逼近上限"| E7
        E7 -.->|"compaction 完成"| E1
    end

    subgraph CMHook["context-mode hook <platform> <event>"]
        direction TB
        H1["注入 routing block<br/>還原 session snapshot"]
        H2["擷取 prompt / decision<br/>blocker / role / intent"]
        H3["白名單比對<br/>權限規則檢查<br/>deny / allow / 改寫"]
        H5["抽取結構化事件<br/>error / git / file / task"]
        H6["記錄回合結束"]
        H7["組 ≤2 KB XML snapshot"]
    end

    DB[("SQLite<br/>events / session_resume")]

    E1 -->|"stdin JSON"| H1
    E2 --> H2
    E3 --> H3
    E5 --> H5
    E6 --> H6
    E7 --> H7

    H1 -->|"stdout JSON<br/>additionalContext"| E1
    H3 -->|"stdout JSON<br/>permissionDecision"| E3

    H2 --> DB
    H5 --> DB
    H6 --> DB
    H7 --> DB
    DB --> H1

    style H3 fill:#f8d7da,stroke:#dc3545,stroke-width:2px
    style H7 fill:#fff3cd,stroke:#ffc107,stroke-width:2px
    style DB fill:#e8f4f8,stroke:#0366d6

8.3 Hook 的通訊協定

[Official] 基本形式是：Harness 用 stdin 送 JSON 進來，Hook 用 stdout 回 JSON。

但各平台的細節不同，這是企業導入最容易踩雷的地方：

[Enterprise Recommendation] 不要手刻 hook 設定。用官方提供的安裝路徑（plugin / context-mode upgrade），讓它自己寫對應格式。手刻最容易出現「設定檔看起來對，但事件名稱是另一個平台的」這種難查的問題。

8.4 Routing Enforcement 的實際效果

[Official] 官方對每個平台的「有 hook」與「沒 hook」給了明確的節省率估計：

[Official] 官方的一句話總結值得貼在團隊牆上： 「Without hooks, one unrouted curl or Playwright snapshot can dump 56 KB into context — wiping out an entire session’s worth of savings.」

8.5 一個歷史教訓：不要污染 git tree

[Official] 早期版本會在 session 啟動時自動把 routing 指令檔寫進專案目錄，造成 git working tree 被污染（#158、#164）。這個行為已被移除。

現在的設計：

• 有 hook 的平台：SessionStart 在 runtime 注入 routing 指示，不寫檔
• 沒有 hook 的平台（Zed、Antigravity IDE）：需要一次性手動複製 routing 檔

企業意涵 [Enterprise Recommendation]：如果你的團隊有人回報「專案裡莫名多出 AGENTS.md / GEMINI.md」，那是舊版本。請升級。同時建議把這些檔名加進 .gitignore 的檢查清單，避免誤 commit。

8.6 Fail-open 設計與它的代價

[Official] Hook 失敗時，Context Mode 不會阻擋你的工具（fail open）。官方在 Copilot CLI 章節寫：舊版全域 binary 會讓 hook「inert (no routing/capture)」但「they do not block your tools」。

這個設計的雙面性 [AI Analysis]：

[Enterprise Recommendation] 因應措施：

1. 每日或每次專案切換時跑 ctx doctor（見 24.3）
2. 在團隊規範中加入「升級 Agent 平台後，必須重跑 ctx doctor」
3. 把 ctx doctor 納入開發環境自檢腳本

8.7 本章實務案例

情境：某團隊同時用 Claude Code 與 Codex CLI，發現「Claude Code 上很省，Codex 上完全沒效果」。

診斷：

# Codex 環境下執行
context-mode doctor

發現：MCP 有連上（ctx stats 能跑），但 hook 全部未啟用。

根因 [Official]：Codex CLI 的 hook 功能需要 feature flag：

[features]
hooks = true
plugin_hooks = true    # 若使用 plugin 提供的 hooks

而且 Codex 還會要求使用者信任 plugin hook 指令——沒有點信任，hook 就不會跑。

關鍵提醒 [Official]：官方明確寫道「ctx stats proves the plugin MCP server is installed and reachable; it does not prove hooks are trusted or running」。

團隊規範修正：

驗證 Context Mode 是否生效，不能只看 ctx stats 有沒有回應。
必須跑 ctx doctor，並確認：
  [x] MCP registered
  [x] Hooks configured
  [x] Hooks trusted（Codex 特有）
  [x] FTS5 available
  [x] Runtime version OK

8.8 本章注意事項

1. ctx stats 有回應 ≠ Hook 有在跑。這是最常見的誤判。
2. 各平台 hook 設定格式差異很大，用官方安裝路徑，不要手刻。
3. Codex 需要 feature flag + 信任 hook，兩個都要。
4. Cursor 的 additional_context 不會送到模型（forum #155689），所以 Cursor 靠 .mdc rules 檔做 routing 提示。
5. Fail-open 代表壞掉很安靜，必須靠定期診斷。
6. 舊版會污染 git tree，遇到就升級。

8.9 本章檢查清單

• 我能解釋為什麼 MCP + Hooks 比單純 MCP 強（60% vs 98%）
• 我知道 hook 是 stdin JSON 進、stdout JSON 出
• 我知道我的平台用的是哪種命名格式（PascalCase / camelCase / TypeScript 函式）
• 我知道 ctx stats 有回應不代表 hook 在跑
• 我知道 Codex 需要 [features] hooks = true 且要信任 hook
• 我已把 ctx doctor 納入日常檢查

Part 3 平台與安裝篇

本 Part 的目標：讓任何一位同仁，不管用哪個 AI Agent，都能在 30 分鐘內完成安裝並驗證生效。

重要聲明：以下所有指令依 v1.0.169（2026-09-18 查證）的官方文件撰寫。Context Mode 的發版節奏極快（7 個月 169 版），實際版本升級後請以官方文件為準。指令差異對照見 附錄 C。

第 9 章 平台相容性矩陣

9.1 先釐清「17 還是 18 個平台」

[Official] [AI Analysis] 官方 repo description 與 README 內文都寫「17 platforms」，但 README 的 Platform Compatibility 表格實際列出 18 個平台（多了 Qwen Code）。

本手冊以表格為準，採用 18 個平台。這個落差不影響使用，但如果你在做採購評估或內部簡報，請直接用表格內容，不要引用「17」這個數字。

9.2 完整相容性矩陣

以下為 v1.0.169 官方 Platform Compatibility 表的整理版 [Official]。

圖例：Yes = 原生支援｜Plugin = 透過 plugin 架構｜Bounded = 僅限對應到的特定工具｜Capture-only = 只捕捉不攔截｜– = 不支援

額外能力 [Official]：

9.3 企業選型決策樹

flowchart TD
    Start["企業要選主力 AI Coding Agent"] --> Q1{"工作型態是<br/>長時間多輪複雜任務？<br/>（legacy 分析 / 大型重構）"}

    Q1 -->|"是"| Q2{"需要記住<br/>使用者決策？"}
    Q1 -->|"否<br/>短任務為主"| Q3{"需要程式化<br/>routing 強制？"}

    Q2 -->|"是（強烈建議）"| A1["✅ Claude Code<br/>✅ GitHub Copilot CLI<br/>✅ Codex CLI<br/>✅ OpenCode / KiloCode<br/><br/>有 UserPromptSubmit"]
    Q2 -->|"可接受沒有"| A2["✅ Gemini CLI<br/>✅ VS Code / JetBrains Copilot<br/>✅ OpenClaw / Pi / OMP<br/><br/>Session 完整度 High"]

    Q3 -->|"是"| A3["✅ 上述所有<br/>✅ Cursor / Kiro<br/>（有 hook 但無法還原 session）"]
    Q3 -->|"否"| A4["⚠️ Zed / Antigravity IDE<br/>僅約 60% 節省<br/>不建議作為企業主力"]

    A1 --> Note["⚠️ 提醒：最終仍受限於<br/>企業既有的工具採購與資安核准"]
    A2 --> Note
    A3 --> Note
    A4 --> Note

    style A1 fill:#d4edda,stroke:#28a745
    style A2 fill:#d1ecf1,stroke:#0dcaf0
    style A3 fill:#fff3cd,stroke:#ffc107
    style A4 fill:#f8d7da,stroke:#dc3545

9.4 台灣企業常見組合的建議 [Enterprise Recommendation]

9.5 本章實務案例

情境：某金控 IT 部門有三個開發團隊，分別用 VS Code Copilot、JetBrains Copilot、Claude Code。IT 主管問：「能不能統一？」

分析結果：

統一平台的代價 > 收益，理由：
1. 三個平台的 session 完整度都是 High 以上，效果差異不大
2. VS Code / JetBrains Copilot 缺 UserPromptSubmit，
   但可用 copilot-instructions.md 補足長期規則
3. 真正需要統一的不是「平台」，而是：
   - 權限規則（.claude/settings.json，所有平台都吃）
   - routing 規範（團隊開發規範文件）
   - 診斷 SOP（ctx doctor 檢查項目）

最終決策：不統一平台，統一治理。IT 部門發布三份設定：

1. 共用的 permissions 規則（放版控，各專案繼承）
2. 各平台的安裝驗收清單
3. 統一的 CONTEXT_MODE_PLATFORM 設定要求

這個案例的價值 [AI Analysis]：Context Mode 的多平台支援，讓「平台自由、治理統一」成為可行的企業策略。硬要統一平台，往往換來開發者抗拒。

9.6 本章注意事項

1. 官方自己的「17 platforms」與表格 18 個不一致，以表格為準。
2. Cursor 與 Kiro 無法還原 session，這是上游限制。
3. Codex 不支援改寫參數，只能 deny（等 openai/codex#18491）。
4. Slash command 只有 Claude Code 有，其他平台要在對話裡打 ctx stats 這類文字指令。
5. Zed 與 Antigravity IDE 沒有 hook，只能靠指令檔（約 60%），不建議作為企業主力。

9.7 本章檢查清單

• 我知道自己團隊使用的平台在矩陣中的位置
• 我知道該平台有沒有 UserPromptSubmit（決定會不會忘記決策）
• 我知道該平台能不能在 compaction 後還原
• 我知道 Slash Command 只有 Claude Code 有
• 如果是混合環境，我已規劃共用的權限治理策略

第 10 章 Claude Code 安裝

Claude Code 是官方支援最完整的平台（唯一具備 plugin marketplace + slash command + Full session），也是本手冊示範用的主力平台。

10.1 前置需求

[Official]

如果 /plugin 指令不被辨識，代表版本太舊：

# macOS（Homebrew）
brew upgrade claude-code

# 通用（npm）
npm update -g @anthropic-ai/claude-code

Windows（PowerShell）：

npm update -g @anthropic-ai/claude-code
node --version    # 必須 >= v22.5.0
claude --version  # 必須 >= 1.0.33

10.2 安裝（Plugin 路徑，建議）

在 Claude Code 的對話中輸入這兩行 [Official]：

/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode

安裝後重啟 Claude Code，或執行 /reload-plugins。

這一步做了什麼 [Official]：plugin 一次註冊了

• 6 個 hook：PreToolUse、PostToolUse、UserPromptSubmit、PreCompact、SessionStart、Stop
• 11 個 MCP 工具
• 7 個 slash command

10.3 驗證

/context-mode:ctx-doctor

所有檢查項目都應該顯示 [x]。doctor 會驗證 runtime、hooks、FTS5、plugin 註冊狀態。

[Official] 關鍵提醒：不要只用 ctx stats 驗證。官方明確說明 ctx stats 只能證明 MCP server 有安裝且可連線，不能證明 hook 有被信任或正在執行。

10.4 Slash Commands

[Official] Claude Code 專屬功能：

10.5 Routing 行為

[Official] Claude Code 的 routing 是全自動的：SessionStart hook 在 runtime 注入 routing 指示，不會寫任何檔案到你的專案目錄。

這點很重要——早期版本會污染 git tree，現在不會了（見 8.5）。

10.6 狀態列（選用但強烈建議）

[Official] Claude Code 的 plugin manifest 無法宣告狀態列，需要手動編輯一次 ~/.claude/settings.json：

{
  "statusLine": {
    "type": "command",
    "command": "context-mode statusline"
  }
}

Windows 路徑：%USERPROFILE%\.claude\settings.json

儲存後重啟 Claude Code。狀態列會顯示：

$ saved this session · $ saved across sessions · % efficient

[Enterprise Recommendation] 這個設定看似是小功能，但對推廣導入極為有效——開發者能即時看到節省累積，比任何內部宣導都有說服力。建議列為團隊標準設定。

10.7 替代安裝：MCP-only（不含 hook）

[Official] 如果只想先試用，不想裝完整 plugin：

claude mcp add context-mode -- npx -y context-mode

[Enterprise Recommendation] MCP-only 適合個人試用，不適合團隊標準。企業導入請走 plugin 路徑。

10.8 Claude Code 安裝完整指令清單

# ── 步驟 1：檢查前置需求 ──
node --version          # 需 >= v22.5.0
claude --version        # 需 >= 1.0.33

# ── 步驟 2：（如版本不足）升級 Claude Code ──
npm update -g @anthropic-ai/claude-code

# ── 步驟 3：在 Claude Code 對話中安裝 plugin ──
# /plugin marketplace add mksglu/context-mode
# /plugin install context-mode@context-mode

# ── 步驟 4：重啟 Claude Code ──

# ── 步驟 5：驗證 ──
# /context-mode:ctx-doctor      ← 全部 [x]

# ── 步驟 6：（選用）設定狀態列 ──
# 編輯 ~/.claude/settings.json 加入 statusLine

# ── 步驟 7：從終端機確認 CLI 可用 ──
context-mode doctor

10.9 Claude Code 專屬的已知問題

[Community] 以下來自官方 open issues，企業導入時應預先知道：

[Enterprise Recommendation] 針對 Windows 孤兒程序問題，建議在團隊的環境自檢腳本加入：

# 檢查殘留的 context-mode 程序
Get-Process node -ErrorAction SilentlyContinue |
  Where-Object { $_.CPU -gt 60 } |
  Select-Object Id, ProcessName, CPU, StartTime

若發現長時間高 CPU 的殘留 node 程序，可手動終止。這是已知上游問題的暫時緩解，不是 Context Mode 的原生功能。

10.10 本章實務案例

情境：新進工程師第一天報到，要完成 Claude Code + Context Mode 的環境建置。

標準 onboarding 流程（30 分鐘）：

[00:00] 確認 Node >= 22.5
        node --version
        （若不足：安裝 Node 22 LTS 或更新）

[00:05] 確認 Claude Code >= 1.0.33
        claude --version

[00:10] 安裝 plugin（Claude Code 對話中）
        /plugin marketplace add mksglu/context-mode
        /plugin install context-mode@context-mode
        重啟

[00:15] 驗證
        /context-mode:ctx-doctor      → 全部 [x]

[00:18] 套用團隊權限規則
        將團隊版 permissions 設定複製到 ~/.claude/settings.json
        （含 deny: Read(**/.env*)、Bash(sudo *) 等）

[00:22] 設定狀態列
        編輯 ~/.claude/settings.json 加入 statusLine

[00:25] 實測一次
        在對話中輸入：
        「分析這個專案的 git log 最近 100 個 commit，
          統計 top 5 貢獻者與最常改動的檔案」
        接著輸入 /context-mode:ctx-stats 看節省

[00:30] 完成

驗收標準：ctx-doctor 全綠 + ctx-stats 顯示本次操作有節省紀錄。

10.11 本章注意事項

1. ctx stats 能跑 ≠ 安裝成功，一定要跑 ctx doctor。
2. MCP-only 安裝只有約 60% 效果，不適合團隊標準。
3. 狀態列要手動加，但對推廣效果極佳。
4. Windows 有孤兒程序的已知問題，需納入環境自檢。
5. Node 版本是硬需求，這是導入時最常見的卡點。
6. 安裝後務必重啟（或 /reload-plugins），否則 hook 不會載入。

10.12 本章檢查清單

• node --version ≥ v22.5.0
• claude --version ≥ 1.0.33
• 已執行 /plugin marketplace add mksglu/context-mode
• 已執行 /plugin install context-mode@context-mode
• 已重啟 Claude Code
• /context-mode:ctx-doctor 全部顯示 [x]
• 已套用團隊權限規則到 ~/.claude/settings.json
• 已設定 statusLine
• 已實測一次並用 /context-mode:ctx-stats 確認有節省

第 11 章 GitHub Copilot 生態系安裝

台灣企業採購 GitHub Copilot Enterprise 的比例很高，因此本章特別完整。Copilot 生態系有三種型態，設定方式各不相同。

11.1 三種 Copilot 的差異

[AI Analysis] 關鍵差異：只有 Copilot CLI 有 UserPromptSubmit，也就是只有它會記住你的決策。IDE 版本的 Copilot 會記得你改了哪些檔案、跑過哪些 git 指令，但不會記得你說過「不要用 Lombok」。

企業因應：IDE 版 Copilot 的使用者，應把長期規則寫進 .github/copilot-instructions.md（每次 session 都會載入），而不是只在對話中口頭交代。

11.2 VS Code Copilot 安裝

[Official] 前置需求：Node.js ≥ 22.5（或 Bun）、VS Code + Copilot Chat v0.32 以上。

步驟 1：全域安裝

npm install -g context-mode

步驟 2：建立 .vscode/mcp.json（專案根目錄）

{
  "servers": {
    "context-mode": {
      "command": "context-mode"
    }
  }
}

步驟 3：建立 .github/hooks/context-mode.json

{
  "hooks": {
    "PreToolUse": [
      { "type": "command", "command": "context-mode hook vscode-copilot pretooluse" }
    ],
    "PostToolUse": [
      { "type": "command", "command": "context-mode hook vscode-copilot posttooluse" }
    ],
    "SessionStart": [
      { "type": "command", "command": "context-mode hook vscode-copilot sessionstart" }
    ]
  }
}

[Official] 完整 hook 設定（含 PreCompact）在官方 repo 的 configs/vscode-copilot/hooks.json。上面是最小可用版本。

步驟 4：重啟 VS Code

步驟 5：驗證

打開 Copilot Chat，輸入 ctx stats。應該看到 Context Mode 回應。

步驟 6（建議）：複製 routing 指令檔

cp node_modules/context-mode/configs/vscode-copilot/copilot-instructions.md .github/copilot-instructions.md

Windows（PowerShell）：

$cm = "$(npm root -g)\context-mode"
Copy-Item "$cm\configs\vscode-copilot\copilot-instructions.md" ".github\copilot-instructions.md"

[Enterprise Recommendation] 如果專案已有 copilot-instructions.md，不要直接覆蓋。請把 Context Mode 的 routing 段落合併進去，並在檔案裡標明來源與版本，方便日後升級比對。

11.3 JetBrains Copilot 安裝

[Official] 前置需求：Node.js ≥ 22.5（或 Bun）、JetBrains IDE + GitHub Copilot plugin v1.5.57 以上。

步驟 1：全域安裝

npm install -g context-mode

步驟 2：透過 Settings UI 新增 MCP server

Settings > Tools > AI Assistant > Model Context Protocol (MCP) > Add Server

  Name:    context-mode
  Command: context-mode

步驟 3：建立 .github/hooks/context-mode.json

{
  "hooks": {
    "PreToolUse": [
      { "type": "command", "command": "context-mode hook jetbrains-copilot pretooluse" }
    ],
    "PostToolUse": [
      { "type": "command", "command": "context-mode hook jetbrains-copilot posttooluse" }
    ],
    "SessionStart": [
      { "type": "command", "command": "context-mode hook jetbrains-copilot sessionstart" }
    ]
  }
}

注意平台識別是 jetbrains-copilot，與 VS Code 版不同。

步驟 4：重啟 JetBrains IDE

步驟 5：驗證 —— 在 Copilot Chat 輸入 ctx stats

步驟 6（建議）：複製 routing 指令檔

cp node_modules/context-mode/configs/jetbrains-copilot/copilot-instructions.md .github/copilot-instructions.md

[Official] JetBrains 完整設定指南在官方 repo 的 docs/jetbrains-copilot.md。

11.4 GitHub Copilot CLI 安裝

[Official] 前置需求：Node.js ≥ 22.5（或 Bun）、已安裝 copilot CLI。若使用隔離的 Copilot home，請先設定 COPILOT_HOME。

選項 A：Plugin 安裝（一行指令，官方建議）

npm install -g context-mode                                     # plugin 的 MCP server 會跑全域 binary
copilot plugin install mksglu/context-mode:configs/copilot-cli  # 註冊 MCP + hooks + routing skill

這個路徑的關鍵優勢 [Official]：bundle 的 .mcp.json 會釘住 CONTEXT_MODE_PLATFORM=copilot-cli，所以即使機器上同時裝了 Claude Code（~/.claude/ 會搶贏偵測），Context Mode 仍會正確辨識為 Copilot CLI。

這正是 4.6 提到的多 Agent 共存問題的官方解法。

從本地 clone 試用（尚未進 default branch 時）：

copilot --plugin-dir /path/to/context-mode/configs/copilot-cli

選項 B：手動安裝（不用 plugin）

步驟 1：全域安裝

npm install -g context-mode

步驟 2：用 Copilot CLI 內建指令註冊 MCP

copilot mcp add context-mode -- context-mode

這會幫你寫入 ~/.copilot/mcp-config.json。

步驟 3：設定 hooks

檔案位置：~/.copilot/hooks/context-mode.json（或 $COPILOT_HOME/hooks/context-mode.json）

{
  "version": 1,
  "hooks": {
    "preToolUse":          [{ "type": "command", "command": "context-mode hook copilot-cli pretooluse" }],
    "postToolUse":         [{ "type": "command", "command": "context-mode hook copilot-cli posttooluse" }],
    "preCompact":          [{ "type": "command", "command": "context-mode hook copilot-cli precompact" }],
    "sessionStart":        [{ "type": "command", "command": "context-mode hook copilot-cli sessionstart" }],
    "userPromptSubmitted": [{ "type": "command", "command": "context-mode hook copilot-cli userpromptsubmit" }],
    "agentStop":           [{ "type": "command", "command": "context-mode hook copilot-cli stop" }]
  }
}

Copilot CLI 的三個特殊之處 [Official]：

讓 Context Mode 自己寫 hooks 檔：

CONTEXT_MODE_PLATFORM=copilot-cli context-mode upgrade

[Official] 注意：upgrade 只寫 hooks 檔，MCP server 仍需用步驟 2 的 copilot mcp add 註冊。

步驟 4：重啟 Copilot CLI

步驟 5：驗證

# 在 Copilot CLI session 中輸入：ctx stats
# 從終端機確認 hook + MCP 註冊：
context-mode doctor

[Official] 版本相容性警告：hook 指令跑的是全域 context-mode。如果全域版本太舊（不支援 Copilot CLI），hook 會是「inert」狀態——不 routing、不捕捉，但也不會擋你的工具（fail open）。升級方式：

npm install -g context-mode@latest

11.5 多 Agent 共存時 Context Mode 的角色

企業現實：一台開發機上常常同時存在

Claude Code
GitHub Copilot（VS Code）
GitHub Copilot CLI
Codex CLI
Cursor

Context Mode 在這個環境中扮演三個角色 [AI Analysis]：

flowchart TD
    subgraph Agents["多個 AI Agent（開發者自由選擇）"]
        CC["Claude Code"]
        VSC["VS Code Copilot"]
        CLI["Copilot CLI"]
        CX["Codex CLI"]
        CUR["Cursor"]
    end

    subgraph CM["Context Mode（統一層）"]
        R1["角色 1：統一的 Context 治理<br/>相同的 routing 政策<br/>相同的 sandbox 行為"]
        R2["角色 2：統一的權限邊界<br/>全平台共讀<br/>.claude/settings.json"]
        R3["角色 3：統一的可觀測性<br/>ctx stats / ctx doctor<br/>跨平台一致的診斷語言"]
    end

    subgraph Store["儲存（各平台隔離）"]
        S1[("~/.claude/context-mode")]
        S2[("~/.codex/context-mode")]
        S3[("~/.omp/context-mode")]
    end

    CC --> CM
    VSC --> CM
    CLI --> CM
    CX --> CM
    CUR --> CM

    CM --> Store

    style CM fill:#d4edda,stroke:#28a745,stroke-width:2px
    style Store fill:#fff3cd,stroke:#ffc107

[Official] 注意第三塊：儲存是各平台隔離的。官方特別處理過 OMP 與 Pi 的儲存分離（#473），確保不同 agent 不會共用 session DB、content index 或 stats。

企業意涵：ctx_stats 的數字是per-platform 的。如果開發者在 Claude Code 和 Copilot CLI 之間切換，兩邊的統計不會合併。做團隊 KPI 時要注意這點。

11.6 本章實務案例

情境：某企業有 40 位開發者用 VS Code Copilot，5 位 tech lead 額外用 Copilot CLI 做大型分析。

部署策略：

【全體 40 人】VS Code Copilot
  - .vscode/mcp.json          → 放進專案版控（每個專案都有）
  - .github/hooks/context-mode.json → 放進專案版控
  - .github/copilot-instructions.md → 放進專案版控，含 routing 段落
  - 因為缺 UserPromptSubmit，團隊規則一律寫進 instructions 檔，
    不依賴對話中口頭交代

【5 位 tech lead】額外裝 Copilot CLI
  - copilot plugin install mksglu/context-mode:configs/copilot-cli
  - 這條路徑自動釘 CONTEXT_MODE_PLATFORM=copilot-cli，
    避免與 VS Code 的偵測衝突
  - 有完整 UserPromptSubmit，適合長時間的 legacy 分析工作

【全體共用】
  - ~/.claude/settings.json 的 permissions 規則（IT 統一派送）
  - 每週跑一次 context-mode doctor

關鍵決策說明：專案層級的設定檔（.vscode/mcp.json、.github/hooks/）進版控，讓新人 clone 下來就有；使用者層級的設定（權限規則）由 IT 派送。這是 14.2 四層設定策略 的實際應用。

11.7 本章注意事項

1. VS Code 用 servers，不是 mcpServers，這是最常見的抄錯。
2. Copilot CLI 用 camelCase，且事件名是 userPromptSubmitted / agentStop。
3. 平台識別參數不能抄錯（vscode-copilot / jetbrains-copilot / copilot-cli）。
4. IDE 版 Copilot 沒有 UserPromptSubmit，重要規則要寫進 instructions 檔。
5. Copilot CLI plugin 路徑會自動釘平台，多 Agent 環境強烈建議走這條。
6. context-mode upgrade 只寫 hooks 檔，MCP 要另外註冊。
7. 不要覆蓋既有的 copilot-instructions.md，要合併。

11.8 本章檢查清單

• 我知道自己用的是三種 Copilot 中的哪一種
• MCP 設定檔的鍵名正確（VS Code 是 servers）
• hook 指令中的平台識別正確
• 已重啟 IDE / CLI
• ctx stats 在 Copilot Chat 中有回應
• context-mode doctor 全綠
• 如果是 IDE 版，長期規則已寫進 copilot-instructions.md
• 多 Agent 環境已確認 CONTEXT_MODE_PLATFORM 正確

第 12 章 Codex CLI / Cursor 安裝

12.1 Codex CLI

[Official] 前置需求：Node.js ≥ 22.5（或 Bun）、已安裝 Codex CLI。

12.1.1 Plugin 安裝（建議）

步驟 1：加入 marketplace

codex plugin marketplace add mksglu/context-mode

然後從 Codex 的 plugin UI 安裝。

步驟 2：開啟 feature flag（這是 Codex 最關鍵的一步）

在 ~/.codex/config.toml 加入：

[features]
plugin_hooks = true
hooks = true

[Official] Feature flag 說明：

• 目前 Codex build 把 hooks 放在 [features].hooks（或 codex --enable hooks）
• 建議用 [features].hooks；[features].codex_hooks 是仍被接受的 legacy 別名
• bundled plugin hooks 額外需要 plugin_hooks，直到 Codex 預設啟用為止

步驟 3：重啟 Codex CLI，用 ctx stats 驗證 MCP

[Official] 極重要：官方明白寫著——ctx stats 證明 plugin MCP server 已安裝且可連線，但不證明 hook 被信任或正在執行。

步驟 4：信任 plugin hooks

如果 Codex 跳出 hook 核准提示，必須檢視並信任。Plugin hook 只有在兩個 feature flag 都開啟且 Codex 已接受 hook 指令之後才會生效。

自訂儲存位置（若 Codex 無法寫入預設目錄）：

CONTEXT_MODE_DIR="$HOME/.codex-context-mode" codex

Windows（PowerShell）：

$env:CONTEXT_MODE_DIR = "D:\ai\codex-context-mode"
codex

[Official] <root>/sessions 放 session 與 stats，<root>/content 放索引內容。

[Official] Node/PATH 注意：plugin 移除了手動 Codex 設定，但不會自動 vendor Node，也不會繼承 login shell 的 PATH 修正。必須確保 node 對 Codex 程序可見。這在 Windows 或用 nvm 的環境特別容易出問題。

12.1.2 手動安裝（Codex build 不支援 plugin_hooks 時）

步驟 1：全域安裝

npm install -g context-mode

步驟 2：~/.codex/config.toml

[features]
hooks = true

[mcp_servers.context-mode]
command = "context-mode"

[mcp_servers.context-mode.env]
CONTEXT_MODE_PLATFORM = "codex"

步驟 3：建立 $CODEX_HOME/hooks.json（CODEX_HOME 未設定時為 ~/.codex/hooks.json）

{
  "hooks": {
    "PreToolUse": [{ "matcher": "local_shell|shell|shell_command|exec_command|Bash|Shell|apply_patch|Edit|Write|grep_files|ctx_execute|ctx_execute_file|ctx_batch_execute|ctx_fetch_and_index|ctx_search|ctx_index|mcp__", "hooks": [{ "type": "command", "command": "context-mode hook codex pretooluse" }] }],
    "PostToolUse": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex posttooluse" }] }],
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex sessionstart" }] }],
    "PreCompact": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex precompact" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex userpromptsubmit" }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex stop" }] }]
  }
}

matcher 欄位的意思：只有工具名稱符合這個正則的呼叫才會觸發 hook。它同時涵蓋原生工具（shell、Bash、Edit）與 Context Mode 自己的工具與其他 MCP 工具（mcp__），確保所有可能產生大輸出的路徑都被監看。

步驟 4：複製 routing 指令檔

CM_ROOT="$(npm root -g)/context-mode"
cp "$CM_ROOT/configs/codex/AGENTS.md" ./AGENTS.md

全域版本：

CM_ROOT="$(npm root -g)/context-mode"
cp "$CM_ROOT/configs/codex/AGENTS.md" ~/.codex/AGENTS.md

[Official] 全域版套用到所有專案；兩者都存在時，Codex CLI 會合併。

步驟 5：重啟 Codex CLI

12.1.3 Codex 的三個限制（必讀）

[Official]

[Enterprise Recommendation] 因為 Codex 的 session 完整度是 Partial，如果團隊用 Codex 做長時間的複雜任務，請額外要求開發者把關鍵決策寫進 AGENTS.md，不要只靠對話。

12.2 Cursor

[Official] 前置需求：Node.js ≥ 22.5（或 Bun）、Cursor + agent mode。

🚧 [Official] 狀態提醒：Cursor Marketplace plugin 仍在等待 Cursor 團隊審核。在上架之前，請走 local-folder 或手動安裝路徑。追蹤：#485 / #489。

12.2.1 選項 A：本地資料夾 plugin（Marketplace 上架前）

Windows（PowerShell） —— Cursor 不跟隨 Windows symlink/junction，必須用 robocopy [Official]：

git clone https://github.com/mksglu/context-mode.git
cd context-mode
robocopy . "$env:USERPROFILE\.cursor\plugins\local\context-mode" /MIR `
  /XD node_modules .git build web tests scripts .vscode `
  /XF *.log .gitignore *.bundle.mjs.map

macOS / Linux：

git clone https://github.com/mksglu/context-mode.git
ln -s "$PWD/context-mode" ~/.cursor/plugins/local/context-mode

重啟 Cursor。Plugin 會出現在 Settings → Plugins，名稱為「Context Mode (Local)」。要更新就重跑同一行 robocopy / ln -s。

[Official] 衝突警告：如果 .cursor/hooks.json 裡已經有選項 B 留下的 context-mode 設定，context-mode doctor 會警告 hook 重複觸發。請移除其中一份設定，確保事件只觸發一次。

12.2.2 選項 B：手動安裝

步驟 1：全域安裝

npm install -g context-mode

步驟 2：.cursor/mcp.json（專案根目錄，或 ~/.cursor/mcp.json 做全域）

{
  "mcpServers": {
    "context-mode": {
      "command": "context-mode"
    }
  }
}

步驟 3：.cursor/hooks.json

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "command": "context-mode hook cursor pretooluse",
        "matcher": "Shell|Read|Grep|WebFetch|Task|MCP:ctx_execute|MCP:ctx_execute_file|MCP:ctx_batch_execute"
      }
    ],
    "postToolUse": [
      { "command": "context-mode hook cursor posttooluse" }
    ],
    "stop": [
      { "command": "context-mode hook cursor stop" }
    ]
  }
}

[Official] preToolUse 的 matcher 是選用的——不加就對所有工具觸發。stop hook 在 agent 回合結束時觸發，可以送 followup 訊息延續迴圈。另外還有 afterAgentResponse（fire-and-forget，收到完整回應文字）。

步驟 4：複製 routing rules 檔（Cursor 沒有 SessionStart，這步必做）

mkdir -p .cursor/rules
cp node_modules/context-mode/configs/cursor/context-mode.mdc .cursor/rules/context-mode.mdc

Windows（PowerShell）：

New-Item -ItemType Directory -Force ".cursor\rules" | Out-Null
$cm = "$(npm root -g)\context-mode"
Copy-Item "$cm\configs\cursor\context-mode.mdc" ".cursor\rules\context-mode.mdc"

步驟 5：重啟 Cursor 或開新的 agent session

驗證：Cursor Settings > MCP 確認 context-mode 顯示已連線；在 agent chat 輸入 ctx stats。

12.2.3 Cursor 的兩個已知限制

[Official]

[Official] 設定優先序：專案的 .cursor/hooks.json 覆蓋 ~/.cursor/hooks.json。

12.3 本章實務案例

情境：某新創團隊全員用 Cursor，導入後發現「每次 Cursor 重開，Agent 就完全忘記昨天做到哪」。

診斷：這不是設定錯誤，是平台限制。Cursor 的 sessionStart 被自家 validator 拒絕，Context Mode 無法注入還原內容。

因應方案 [Enterprise Recommendation]：

1. 接受限制：Cursor 的定位是「單次任務效率工具」，
   不適合跨天的長任務

2. 補償措施：
   - 把長期決策寫進 .cursor/rules/（會在每次 session 載入）
   - 重要的工作狀態用 ctx_index 主動索引成可搜尋內容：
     ctx_index(path: "docs/current-refactor-notes.md",
               source: "project:refactor-log")
     下次開 session 時用 ctx_search 主動回查

3. 長任務改用其他平台：
   tech lead 級的大型分析改用 Claude Code 或 Copilot CLI

這個案例的通用教訓：當平台能力不足時，把「自動記憶」改成「主動索引 + 主動查詢」。這是 Context Mode 在 Partial 平台上的標準補償模式。

12.4 本章注意事項

1. Codex 需要兩個 feature flag (hooks + plugin_hooks)，而且要信任 hook。
2. Codex 的 ctx stats 不能證明 hook 在跑。
3. Codex 不能改寫工具參數，只能 deny。
4. Codex 的 PreCompact 依 runtime 版本而定（0.130.0 有）。
5. Codex 需要 node 在 PATH 上，plugin 不會 vendor Node。
6. Cursor 在 Windows 不跟隨 symlink，必須用 robocopy。
7. Cursor 無法還原 session，這是平台限制不是 bug。
8. Cursor 不要同時用選項 A 和 B，會重複觸發 hook。

12.5 本章檢查清單

Codex CLI：

• ~/.codex/config.toml 已設定 [features] hooks = true
• （用 plugin 時）已設定 plugin_hooks = true
• 已在 Codex 中信任 context-mode 的 hook 指令
• node 對 Codex 程序可見
• AGENTS.md 已複製（專案或全域）
• context-mode doctor 確認 hook 已註冊

Cursor：

• 已選定安裝路徑（A 或 B，不可並用）
• .cursor/mcp.json 已建立
• .cursor/hooks.json 已建立
• .cursor/rules/context-mode.mdc 已複製（必做）
• 已知悉 Cursor 無法在 compaction 後還原 session
• context-mode doctor 沒有 duplicate hook 警告

第 13 章 其他平台安裝

本章涵蓋 OpenCode、KiloCode、OpenClaw、Pi、OMP、Gemini CLI、Qwen Code、Kimi Code、Kiro、Zed、Antigravity。

重點在於理解架構差異：不是所有平台都用傳統的 JSON hook。

13.1 三種擴充架構的差異

flowchart TD
    subgraph A["架構一：JSON Hook（傳統）"]
        A1["Harness 讀設定檔<br/>hooks.json / settings.json"]
        A2["spawn 子行程<br/>context-mode hook &lt;platform&gt; &lt;event&gt;"]
        A3["stdin JSON → stdout JSON"]
        A1 --> A2 --> A3
        A4["平台：Claude Code / Gemini CLI<br/>Copilot 系列 / Codex / Cursor<br/>Kimi / Kiro / Qwen"]
    end

    subgraph B["架構二：TypeScript Plugin（in-process）"]
        B1["設定檔宣告 plugin<br/>opencode.json / kilo.json"]
        B2["Harness 直接載入 TS 模組"]
        B3["函式呼叫，無子行程<br/>tool.execute.before / after"]
        B1 --> B2 --> B3
        B4["平台：OpenCode / KiloCode<br/>OpenClaw / Pi / OMP"]
    end

    subgraph C["架構三：MCP-only（無 hook）"]
        C1["只註冊 MCP server"]
        C2["靠指令檔提示模型"]
        C3["無程式化攔截<br/>約 60% 遵循率"]
        C1 --> C2 --> C3
        C4["平台：Zed / Antigravity IDE"]
    end

    style A fill:#d1ecf1,stroke:#0dcaf0
    style B fill:#d4edda,stroke:#28a745
    style C fill:#f8d7da,stroke:#dc3545

架構二的重要差異 [Official]：OpenCode / KiloCode 的 plugin 是 in-process 呼叫，沒有額外的 stdio MCP 子行程。這代表：

• 效能較好（省掉 process spawn）
• 但也代表 plugin 與 mcp 設定不可並存（見 13.2）

13.2 OpenCode / KiloCode

[Official] 兩者共用同一套 plugin 架構（OpenCodeAdapter），只有設定路徑不同。

安裝（以 OpenCode 為例）：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["context-mode"]
}

這一行就完成了——plugin 項目會原生註冊全部 11 個 ctx_* 工具並啟用 hook。

選用：複製 routing 檔

cp node_modules/context-mode/configs/opencode/AGENTS.md AGENTS.md

[Official] 沒有這個檔，hook 仍會強制 routing，但模型不知道指令為什麼被拒絕。有這個檔，模型知道該改用什麼。

重啟 OpenCode，輸入 ctx stats 驗證。

⚠️ 最重要的陷阱：plugin 與 mcp 不可並存

[Official] 如果設定檔同時有 plugin: ["context-mode"] 和 mcp.context-mode，OpenCode / KiloCode 會註冊 0 個 ctx_* 工具。

原因：plugin 路徑正確地抑制了 MCP 重複註冊，但舊的 MCP 項目會讓 loader 混淆。

解法：

context-mode upgrade    # 會移除 legacy 的 mcp.context-mode 項目，保留其他 MCP server

v1.0.140+ 在發生這個狀況時會輸出 stderr 診斷訊息。

Hook 對應關係

[Official] OpenCode / KiloCode 沒有真正的 SessionStart hook（#14808、#5409），Context Mode 用替代方案：

[Official] 儘管是代理實作，官方仍把 OpenCode / KiloCode 評為 Full session 完整度——因為 routing 注入、session 還原、使用者決策捕捉三項都有做到。

另外：AGENTS.md / CLAUDE.md / CONTEXT.md 規則會在每個專案第一次 hook 觸發時自動捕捉。

13.3 OpenClaw / Pi Agent

[Official] 前置需求：OpenClaw gateway > 2026.1.29（PR #9761）、Node.js 22+。

Context Mode 在這裡是 native gateway plugin，沒有獨立的 MCP server——plugin 直接註冊進 gateway runtime。

安裝：

git clone https://github.com/mksglu/context-mode.git
cd context-mode
npm run install:openclaw

自訂 state 目錄：

npm run install:openclaw -- /path/to/openclaw-state

[Official] 安裝腳本使用環境中的 $OPENCLAW_STATE_DIR（預設 /openclaw）。常見位置：Docker → /openclaw；本機 → ~/.openclaw 或你設定的 OPENCLAW_STATE_DIR。

安裝腳本會自動處理：npm install、npm run build、better-sqlite3 native rebuild、在 runtime.json 註冊 extension、以 SIGUSR1 重啟 gateway。

驗證：plugin 會透過 api.on()（lifecycle）與 api.registerHook()（commands）註冊 8 個 hook。輸入 ctx stats 確認。

[Official] 版本警告：OpenClaw ≤ 2026.1.29 的 lifecycle hook 會靜默失敗。此時 adapter 會 fallback 到 DB snapshot 重建（精確度較低，但關鍵狀態仍保留）。

Pi Coding Agent（獨立於 OpenClaw）：

npm install -g context-mode
pi install npm:context-mode

或手動加進 ~/.pi/agent/settings.json（專案層級為 .pi/settings.json）：

{ "packages": ["npm:context-mode"] }

再加 ~/.pi/agent/mcp.json（專案層級 .pi/mcp.json）：

{
  "mcpServers": {
    "context-mode": { "command": "context-mode" }
  }
}

[Official] Pi 的 extension 註冊四個生命週期事件：tool_call（≈PreToolUse）、tool_result（≈PostToolUse）、session_start（≈SessionStart）、session_before_compact（≈PreCompact）。

小技巧：Pi 可用預設鍵 Ctrl+O 收合／展開工具輸出。

13.4 OMP（Oh My Pi）

[Official] 建議路徑：

omp plugin install context-mode
# 重啟 OMP
omp plugin list
omp plugin doctor

兩個指令都應顯示 context-mode 為 enabled。

[Official] Plugin 會在首次載入時自動在 ~/.omp/agent/mcp.json 註冊自己的 MCP server（以 node <plugin>/server.bundle.mjs 啟動，因為 plugin 安裝目錄不在 PATH 上），所以重啟後 11 個 ctx_* 工具就可用，不需手動編輯 mcp.json（#677）。已存在的 context-mode 項目不會被覆蓋。

手動 plugin 路徑（omp plugin install 不可用時）：

cd ~/.omp/plugins
bun add context-mode    # 或 npm install context-mode

重啟即可。不需編輯 lock 檔、不需釘版本。

MCP-only 路徑：

npm install -g context-mode

加到 ~/.omp/agent/mcp.json（user scope）或 <project>/.omp/mcp.json（project scope）：

{
  "mcpServers": {
    "context-mode": { "command": "context-mode" }
  }
}

複製 routing 檔：

cp node_modules/context-mode/configs/omp/SYSTEM.md ~/.omp/agent/SYSTEM.md

[Official] 兩條路徑的效果差很多：

• Plugin 路徑：四個 pi.on(...) handler 程式化強制（tool_call 對 curl/wget/inline-fetch 回傳 { block: true, reason }），約 98% 遵循率，與 Claude Code hook 同級
• MCP-only 路徑：靠 SYSTEM.md 規則，約 60%

儲存根目錄在 ~/.omp/context-mode/，與 Pi 完全隔離，不共用 session DB、content index、stats（#473）。

13.5 Gemini CLI

[Official] 前置需求：Node.js ≥ 22.5（或 Bun）、Gemini CLI。

npm install -g context-mode

編輯 ~/.gemini/settings.json——一個檔案同時註冊 MCP server 與四個 hook：

{
  "mcpServers": {
    "context-mode": {
      "command": "context-mode"
    }
  },
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "run_shell_command|read_file|read_many_files|grep_search|search_file_content|web_fetch|activate_skill|mcp__plugin_context-mode|mcp__context-mode|mcp__(?!.*context-mode)",
        "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli beforetool" }]
      }
    ],
    "AfterTool": [
      { "matcher": "", "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli aftertool" }] }
    ],
    "PreCompress": [
      { "matcher": "", "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli precompress" }] }
    ],
    "SessionStart": [
      { "matcher": "", "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli sessionstart" }] }
    ]
  }
}

Gemini CLI 的事件名稱與眾不同 [Official]：

[Official] BeforeTool 的 matcher 為什麼這樣寫？ 它只針對會產生大輸出的工具（run_shell_command、read_file、read_many_files、grep_search、search_file_content、web_fetch、activate_skill）加上 Context Mode 自己的工具。這樣避免輕量工具承擔不必要的 hook 成本，同時攔截所有可能淹沒 context 的路徑。

注意最後的 mcp__(?!.*context-mode) —— 這是負向前瞻，意思是「所有其他 MCP 工具，但不含 context-mode 自己」。

驗證：/mcp list，應看到 context-mode: ... - Connected。

選用 routing 檔：

cp node_modules/context-mode/configs/gemini-cli/GEMINI.md ./GEMINI.md

13.6 Qwen Code

[Official] Qwen Code 使用與 Claude Code 完全相同的 hook wire protocol（JSON stdin/stdout、相同事件名稱）。

npm install -g @qwen-code/qwen-code    # 若尚未安裝
npm install -g context-mode

~/.qwen/settings.json：

{
  "mcpServers": {
    "context-mode": { "command": "context-mode", "args": [] }
  },
  "hooks": {
    "PreToolUse": [{ "matcher": "run_shell_command|read_file|read_many_files|grep_search|web_fetch|agent|mcp__plugin_context-mode_context-mode__ctx_execute|mcp__plugin_context-mode_context-mode__ctx_execute_file|mcp__plugin_context-mode_context-mode__ctx_batch_execute|mcp__(?!.*context-mode)", "hooks": [{ "type": "command", "command": "context-mode hook qwen-code pretooluse" }] }],
    "PostToolUse": [{ "matcher": "", "hooks": [{ "type": "command", "command": "context-mode hook qwen-code posttooluse" }] }],
    "SessionStart": [{ "matcher": "", "hooks": [{ "type": "command", "command": "context-mode hook qwen-code sessionstart" }] }],
    "PreCompact": [{ "matcher": "", "hooks": [{ "type": "command", "command": "context-mode hook qwen-code precompact" }] }],
    "UserPromptSubmit": [{ "matcher": "", "hooks": [{ "type": "command", "command": "context-mode hook qwen-code userpromptsubmit" }] }]
  }
}

Routing 檔：

cp node_modules/context-mode/configs/qwen-code/QWEN.md ./QWEN.md
# 全域：cp ... ~/.qwen/QWEN.md

[Official] 偵測方式：MCP clientInfo（qwen-cli-mcp-client-*）或 QWEN_PROJECT_DIR 環境變數。

13.7 Kimi Code

[Official] Kimi Code 使用與 Codex 相同的 JSON wire protocol，但設定是 TOML。

npm install -g context-mode

~/.kimi-code/mcp.json：

{
  "mcpServers": {
    "context-mode": { "command": "context-mode", "args": [] }
  }
}

~/.kimi-code/config.toml：

[[hooks]]
event = "PreToolUse"
matcher = "Bash|Shell|Read|Edit|Write|WebFetch|Agent|ctx_execute|ctx_execute_file|ctx_batch_execute|ctx_fetch_and_index|ctx_search|ctx_index|mcp__"
command = "context-mode hook kimi pretooluse"
timeout = 30

[[hooks]]
event = "PostToolUse"
command = "context-mode hook kimi posttooluse"
timeout = 30

[[hooks]]
event = "SessionStart"
command = "context-mode hook kimi sessionstart"
timeout = 30

[[hooks]]
event = "PreCompact"
command = "context-mode hook kimi precompact"
timeout = 30

[[hooks]]
event = "UserPromptSubmit"
command = "context-mode hook kimi userpromptsubmit"
timeout = 30

[[hooks]]
event = "Stop"
command = "context-mode hook kimi stop"
timeout = 30

[Official] Kimi 比 Codex 強的地方：接受 additionalContext、updatedInput、permissionDecision: "ask"（Codex 全部拒絕）。Kimi hook 還會把 ContentPart[] 格式的 prompt 陣列正規化成字串供下游解析。

Routing 檔（沿用 Codex 版）：

cp "$(npm root -g)/context-mode/configs/codex/AGENTS.md" ./AGENTS.md

13.8 Kiro

[Official] 前置需求：Node.js ≥ 22.5（或 Bun）、Kiro 已啟用 MCP（Settings 搜尋 “MCP”）。

npm install -g context-mode

.kiro/settings/mcp.json（或 ~/.kiro/settings/mcp.json 全域）：

{
  "mcpServers": {
    "context-mode": { "command": "context-mode" }
  }
}

.kiro/hooks/context-mode.json：

{
  "name": "context-mode",
  "description": "Context-mode hooks for context window protection",
  "hooks": {
    "preToolUse": [
      { "matcher": "execute_bash|fs_read|@context-mode/ctx_execute|@context-mode/ctx_execute_file|@context-mode/ctx_batch_execute|@(?!context-mode/)", "command": "context-mode hook kiro pretooluse" }
    ],
    "postToolUse": [
      { "matcher": "*", "command": "context-mode hook kiro posttooluse" }
    ]
  }
}

Routing 檔（必做，因為 Kiro 的 agentSpawn 尚未實作）：

cp node_modules/context-mode/configs/kiro/KIRO.md ./KIRO.md

[Official] Kiro 的工具名稱格式是 @context-mode/ctx_batch_execute，與其他平台不同。驗證方式：Kiro panel > MCP Servers 分頁確認 context-mode 顯示綠燈。

13.9 Zed（MCP-only，無 hook）

[Official]

npm install -g context-mode

~/.config/zed/settings.json（Windows：%APPDATA%\Zed\settings.json）：

{
  "context_servers": {
    "context-mode": {
      "command": "context-mode",
      "args": [],
      "env": {}
    }
  }
}

[Official] 注意 Zed 用的是 context_servers，不是 mcpServers。args 與 env 對 context-mode 是選用的，這裡列出是為了符合 Zed 的自訂 MCP server 格式。

Routing 檔（唯一的強制手段）：

cp node_modules/context-mode/configs/zed/AGENTS.md ./AGENTS.md

驗證：開啟 Agent Panel（Cmd+Shift+A），在設定中檢查 context-mode 旁的指示燈是否為綠色；在 agent chat 輸入 ctx stats。

[Official] Zed 的工具名稱格式是 mcp:context-mode:ctx_batch_execute。Routing 完全靠 AGENTS.md，約 60% 遵循率，沒有任何程式化攔截。

13.10 Antigravity IDE 與 Antigravity CLI（agy）

[Official] 這是兩個不同的東西，最容易混淆：

Antigravity IDE：

npm install -g context-mode

~/.gemini/antigravity/mcp_config.json：

{
  "mcpServers": {
    "context-mode": { "command": "context-mode" }
  }
}

cp node_modules/context-mode/configs/antigravity/GEMINI.md ./GEMINI.md

Antigravity CLI（agy） —— 需 agy ≥ 1.0.7（官方在 1.0.10 驗證過）：

npm install -g context-mode
agy plugin install https://github.com/mksglu/context-mode/tree/main/configs/antigravity-cli

重啟 agy。

[Official] 這個 bundle 會釘住 CONTEXT_MODE_PLATFORM=antigravity-cli，確保在同時裝有 Claude Code 的機器上仍能正確偵測（#774）。

移除方式：agy plugin uninstall context-mode

13.11 建置前置需求（CentOS / RHEL / Alpine）

[Official] 這一節對企業的 Linux CI 環境特別重要。

CentOS 8 / RHEL 8（glibc 2.28）：

dnf install -y gcc-toolset-10-gcc gcc-toolset-10-gcc-c++ make python3 python3-setuptools
scl enable gcc-toolset-10 'npm install -g context-mode'

CentOS 7 / RHEL 7（glibc 2.17）：

yum install -y centos-release-scl
yum install -y devtoolset-10-gcc devtoolset-10-gcc-c++ make python3
pip3 install setuptools
scl enable devtoolset-10 'npm install -g context-mode'

Alpine Linux：

[Official] better-sqlite3 v12.8.0+ 有 musl prebuilt binary。以 ^12.6.2 的依賴範圍會解析到最新 12.x，不需建置工具。若釘住舊版：

apk add build-base python3 py3-setuptools
npm install -g context-mode

Windows / binding 自我修復 [Official]：如果安裝後 better_sqlite3.node 遺失（例如 prebuild-install 不在 cmd.exe 的 PATH 上、沒有 MSVC toolchain），postinstall 腳本與 runtime hook 會自動重新抓取 prebuild 並修復 binding，不需手動 npm rebuild（#408）。

13.12 本章實務案例

情境：某企業的 CI 環境是 CentOS 7 容器，跑 Node 18。想在 CI 中用 Context Mode 做自動化程式碼分析。

問題盤點：

❌ CentOS 7 → glibc 2.17，prebuilt binary 載不起來
❌ Node 18  → Linux + Node < 22.5 是官方不支援組合，npm install 會直接失敗

兩個可行解：

方案 A（建議）：升級容器基底
  FROM node:22-bookworm       # glibc 2.36 + Node 22
  RUN npm install -g context-mode
  → 零建置工具，最乾淨

方案 B（無法換基底時）：改用 Bun
  FROM oven/bun:latest
  RUN bun add -g context-mode
  → bun:sqlite 內建，完全避開 better-sqlite3

不建議的方案：在 CentOS 7 上裝 devtoolset-10 硬編譯。雖然官方有給指令，但會讓 CI 映像肥大、建置時間拉長，而且 Node 18 的問題仍未解決。

[Enterprise Recommendation] 這個案例的通用結論：Context Mode 的導入往往會順帶推動 Node runtime 的升級。請把這件事納入 PoC 的成本評估，不要低估。

13.13 本章注意事項

1. OpenCode / KiloCode 的 plugin 與 mcp 不可並存，否則 0 個工具。
2. Gemini CLI 的事件名稱完全不同（BeforeTool / AfterTool / PreCompress）。
3. Zed 用 context_servers，不是 mcpServers。
4. Antigravity IDE 與 CLI 是兩個不同的東西，路徑與能力都不同。
5. Kiro 與 Zed 的工具名稱格式特殊（@context-mode/… 與 mcp:context-mode:…）。
6. OMP 的 plugin 路徑約 98%，MCP-only 路徑約 60%，差距巨大。
7. Linux + Node < 22.5 直接不支援，這會逼你升級 runtime。
8. OpenClaw ≤ 2026.1.29 的 lifecycle hook 會靜默失敗。

13.14 本章檢查清單

• 我知道自己的平台屬於三種架構中的哪一種
• （OpenCode/KiloCode）設定檔中沒有同時存在 plugin 與 mcp.context-mode
• （Gemini CLI）我用的是 BeforeTool / AfterTool / PreCompress 而非標準名稱
• （Zed）我用的是 context_servers
• （Antigravity）我確認自己裝的是 IDE 還是 CLI
• （OMP）我走的是 plugin 路徑而非 MCP-only
• 我的 Linux 環境 Node ≥ 22.5（或使用 Bun）
• 我的 CI 映像基底已確認相容

第 14 章 企業標準安裝流程與設定管理

14.1 企業標準安裝流程（八步驟）

[Enterprise Recommendation] 以下流程適用於任何平台，建議做成內部的標準作業程序。

flowchart TD
    S1["Step 1<br/>Install Runtime<br/>Node ≥ 22.5 或 Bun"]
    S2["Step 2<br/>Install Context Mode<br/>plugin / npm -g"]
    S3["Step 3<br/>Configure MCP<br/>平台對應的設定檔"]
    S4["Step 4<br/>Configure Hooks<br/>平台對應的 hook 格式"]
    S5["Step 5<br/>Configure Agent Instruction<br/>routing 檔 + 權限規則"]
    S6["Step 6<br/>Verify<br/>ctx doctor 全綠"]
    S7["Step 7<br/>Benchmark<br/>量測自家情境"]
    S8["Step 8<br/>Production Adoption<br/>納入標準環境"]

    S1 --> S2 --> S3 --> S4 --> S5 --> S6
    S6 -->|"有紅燈"| Fix["回到對應步驟排查<br/>見第 25 章"]
    Fix --> S6
    S6 -->|"全綠"| S7
    S7 -->|"效益不足"| Review["檢討 routing 政策<br/>或該場景不適用"]
    Review --> S7
    S7 -->|"效益達標"| S8

    style S6 fill:#d4edda,stroke:#28a745,stroke-width:2px
    style S7 fill:#fff3cd,stroke:#ffc107,stroke-width:2px
    style Fix fill:#f8d7da,stroke:#dc3545

各步驟的驗收標準：

14.2 四層設定策略

[Enterprise Recommendation] 企業環境的設定會散落在很多地方，建議明確劃分為四層，並規定「什麼東西放哪一層」：

flowchart TD
    subgraph L1["第 1 層：Global（IT 派送，不可自行修改）"]
        G1["~/.claude/settings.json 的 permissions<br/>資安紅線：deny sudo / .env / 生產路徑"]
        G2["CONTEXT_MODE_PLATFORM（多 Agent 機器）"]
    end

    subgraph L2["第 2 層：Project（進版控，團隊共用）"]
        P1[".vscode/mcp.json / .cursor/mcp.json"]
        P2[".github/hooks/context-mode.json"]
        P3["專案的 routing 檔<br/>copilot-instructions.md / AGENTS.md"]
        P4["專案層 permissions（可加嚴，不可放寬）"]
    end

    subgraph L3["第 3 層：User（個人偏好，不進版控）"]
        U1["statusLine 設定"]
        U2["個人慣用的 index source 命名"]
    end

    subgraph L4["第 4 層：Environment（執行期）"]
        E1["CONTEXT_MODE_DIR<br/>自訂儲存位置"]
        E2["CTX_FETCH_STRICT=1<br/>CI / 共享環境強化"]
        E3["CONTEXT_MODE_EXTERNAL_MCP_NUDGE_EVERY"]
    end

    L1 -->|"被覆蓋 ❌ deny 永遠勝出"| L2
    L2 -->|"可覆蓋"| L3
    L4 -->|"執行期生效"| L2

    style L1 fill:#f8d7da,stroke:#dc3545,stroke-width:2px
    style L2 fill:#d4edda,stroke:#28a745
    style L3 fill:#d1ecf1,stroke:#0dcaf0
    style L4 fill:#fff3cd,stroke:#ffc107

分層原則 [Enterprise Recommendation]：

[Official] 權限規則的合併語意：deny 永遠勝過 allow；更具體（專案層）的規則覆蓋全域規則。這代表專案可以加嚴，但不能放寬 IT 訂的 deny 規則——這正是企業要的行為。

14.3 環境變數完整清單

[Official] v1.0.169 的官方環境變數：

Windows 設定範例（PowerShell，使用者層級永久生效）：

[Environment]::SetEnvironmentVariable("CONTEXT_MODE_DIR", "D:\ai\context-mode", "User")
[Environment]::SetEnvironmentVariable("CONTEXT_MODE_PLATFORM", "copilot-cli", "User")
# 驗證
$env:CONTEXT_MODE_DIR

Linux / macOS（~/.bashrc 或 ~/.zshrc）：

export CONTEXT_MODE_DIR="/opt/ai/context-mode"
export CONTEXT_MODE_PLATFORM="claude-code"

CI 環境（GitHub Actions 範例）：

env:
  CTX_FETCH_STRICT: "1"          # 封鎖內網與 loopback
  CONTEXT_MODE_DIR: "/tmp/ctx"   # 容器內暫存，隨 job 結束消失

14.4 企業部署架構

[AI Analysis] [Enterprise Recommendation] 這一節要非常小心，因為很容易出現錯誤的架構想像。

14.4.1 正確的架構：Developer Local

Developer PC / 開發容器
 ├── Claude Code / Copilot / Codex / Cursor
 ├── Context Mode（本機執行）
 │    ├── Sandbox subprocess（本機）
 │    └── SQLite（本機檔案系統）
 └── Project Repository（本機 clone）

Context Mode 的設計就是本機執行的。它不是 server，沒有多租戶概念，SQLite 是單機檔案。

14.4.2 錯誤的架構想像（請勿這樣設計）

❌ 錯誤：
Developer A ─┐
Developer B ─┼──→ 共用的 Context Mode Server ──→ 中央知識庫
Developer C ─┘

為什麼不行 [AI Analysis]：

14.4.3 企業真正該集中的東西

flowchart TD
    subgraph Central["✅ 該集中的（治理層）"]
        C1["權限規則<br/>permissions deny/allow<br/>由 IT 派送"]
        C2["Routing 規範<br/>團隊開發規範文件"]
        C3["診斷 SOP<br/>ctx doctor 檢查項目"]
        C4["版本基準<br/>統一的 context-mode 版本"]
        C5["Benchmark 基準<br/>企業自訂的量測情境"]
    end

    subgraph Local["✅ 該留在本機的（執行層）"]
        L1["Context Mode 程序"]
        L2["Sandbox subprocess"]
        L3["SQLite session DB"]
        L4["索引內容"]
    end

    subgraph Shared["⚠️ 可考慮共用的（知識層，但不是 Context Mode 的功能）"]
        S1["企業 MCP Server<br/>Jira / Confluence / 內部 API"]
        S2["企業知識庫 / RAG<br/>另外的系統"]
        S3["Spec / 文件 Repository"]
    end

    Central -->|"設定派送"| Local
    Local -->|"透過 MCP 存取"| Shared

    style Central fill:#d4edda,stroke:#28a745,stroke-width:2px
    style Local fill:#d1ecf1,stroke:#0dcaf0
    style Shared fill:#fff3cd,stroke:#ffc107

[Enterprise Recommendation] 一句話總結： 集中「治理」，分散「執行」，知識共用交給企業 MCP / RAG，不要交給 Context Mode。

14.4.4 安全邊界

14.5 本章實務案例

情境：某金控要把 Context Mode 納入標準開發環境，IT 部門需要設計派送機制。

最終方案：

【1. Global 層 —— 由 IT 用 MDM / 群組原則派送】

檔案：%USERPROFILE%\.claude\settings.json
內容：
{
  "permissions": {
    "deny": [
      "Bash(sudo *)",
      "Bash(rm -rf /*)",
      "Read(.env)",
      "Read(**/.env*)",
      "Read(**/*secret*)",
      "Read(**/*credential*)",
      "Bash(*prod*)",
      "Bash(kubectl * -n prod*)"
    ],
    "allow": [
      "Bash(git:*)",
      "Bash(mvn:*)",
      "Bash(npm:*)"
    ]
  },
  "statusLine": {
    "type": "command",
    "command": "context-mode statusline"
  }
}

環境變數（使用者層級）：
  CONTEXT_MODE_DIR = D:\ai\context-mode
  （公司規定 AI 相關資料不得放在 C 槽使用者目錄）

【2. Project 層 —— 放進每個專案的 repo】

.vscode/mcp.json
.github/hooks/context-mode.json
.github/copilot-instructions.md（含 routing 段落）

由架構團隊維護一份範本 repo，新專案直接繼承

【3. 環境自檢腳本 —— 開機時執行】

scripts/ai-env-check.ps1：
  1. node --version 是否 >= 22.5
  2. context-mode --version 是否為公司基準版本
  3. context-mode doctor 是否全綠
  4. 檢查殘留的 node 孤兒程序（Windows 已知問題）
  5. 結果寫入 IT 的監控系統

【4. 明確禁止事項 —— 寫入資安規範】

  - 禁止使用 ctx_insight（hosted dashboard，資料流向未驗證）
  - 禁止對生產環境資料執行 ctx_index
  - 禁止放寬 Global 層的 deny 規則

這個案例的三個設計重點：

1. deny 規則涵蓋 *prod*，從源頭阻擋對生產環境的操作
2. CONTEXT_MODE_DIR 遷離 C 槽，符合公司的資料落地規範
3. 環境自檢腳本補上 fail-open 的盲點，讓 IT 能主動發現壞掉的安裝

14.6 本章注意事項

1. Context Mode 是本機工具，不要設計成共用 server。
2. 該集中的是治理（權限、規範、版本基準），不是執行。
3. CONTEXT_MODE_DIR 必須絕對路徑且不展開 ~。
4. CTX_FETCH_STRICT=1 會封鎖內網，開發者本機不要設，CI 要設。
5. 專案層可以加嚴權限但不能放寬 deny，這是設計出來的行為。
6. fail-open 需要主動自檢，把 ctx doctor 納入環境檢查腳本。

14.7 本章檢查清單

• 八步驟安裝流程已文件化，並有明確驗收標準
• 四層設定策略已定義，團隊知道什麼放哪一層
• Global 層的 permissions 規則已由 IT 派送
• 專案層設定檔已進版控，新專案可繼承
• 多 Agent 機器已設定 CONTEXT_MODE_PLATFORM
• CI 環境已設定 CTX_FETCH_STRICT=1
• 環境自檢腳本已建立並排程執行
• 已明確禁止 ctx_insight（或已完成資料流向驗證）
• 團隊知道 Context Mode 不是中央服務

Part 4 工具實戰篇

本 Part 的目標：讓開發者拿到手冊就能直接抄範例來用。每個工具都用相同的七段格式：目的 / 適用情境 / 輸入 / 輸出 / 範例 / 最佳實務 / 常見錯誤。

第 15 章 11 個 MCP Tools 完整教學

15.0 工具選用決策樹

[Official] 這張圖整理自官方 SKILL 的 Decision Tree，是全章最實用的一頁。

flowchart TD
    Start["準備執行指令 / 讀檔 / 呼叫 API"] --> W{"是 Bash 白名單指令？<br/>mkdir/mv/git commit/cd/echo"}

    W -->|"是"| Bash["✅ 直接用 Bash"]
    W -->|"否"| Big{"輸出可能很大，<br/>或你不確定？"}

    Big -->|"是 / 不確定"| Type{"資料型態？"}
    Big -->|"確定很小"| Bash

    Type -->|"指令輸出<br/>gh / aws / kubectl / npm test"| E["ctx_execute"]
    Type -->|"本地檔案<br/>log / CSV / JSON / source"| EF["ctx_execute_file"]
    Type -->|"多個指令 + 多個查詢"| BE["ctx_batch_execute"]
    Type -->|"外部網頁文件"| FI["ctx_fetch_and_index"]
    Type -->|"Playwright"| PW{"要查幾次？"}
    Type -->|"其他 MCP 工具的輸出"| MCP{"已經在 Context 裡？"}

    PW -->|"多次查詢"| PWA["browser_snapshot(filename)<br/>→ ctx_index(path)<br/>→ ctx_search"]
    PW -->|"一次抽取"| PWB["browser_snapshot(filename)<br/>→ ctx_execute_file(path)"]

    MCP -->|"是"| Direct["✅ 直接用，別再索引<br/>（重複索引 = 付兩次錢）"]
    MCP -->|"否，要多次查"| Save["ctx_execute 存檔<br/>→ ctx_index(path)<br/>→ ctx_search"]
    MCP -->|"否，一次抽取"| Save2["ctx_execute 存檔<br/>→ ctx_execute_file(path)"]

    FI --> S["ctx_search"]

    style Bash fill:#d1ecf1,stroke:#0dcaf0
    style Direct fill:#d4edda,stroke:#28a745
    style E fill:#d4edda,stroke:#28a745
    style EF fill:#d4edda,stroke:#28a745

15.1 ctx_execute

目的

在獨立 subprocess 中執行程式碼，只有 stdout 進入 Context。 [Official]

適用情境

輸入

輸出

腳本的 stdout。依輸出大小有三段行為 [Official]：

⚠️ 不要把外部化當成偷懶的藉口。 它是保護網，不是策略——真正該做的是在腳本裡先聚合， 讓 stdout 一開始就只有結論。

範例

範例 1：偵測 API 回傳的資料異常（官方範例）

const resp = await fetch('http://localhost:3000/api/orders');
const { orders } = await resp.json();

const bugs = [];
const negQty = orders.filter(o => o.quantity < 0);
if (negQty.length) bugs.push(`Negative qty: ${negQty.map(o => o.id).join(', ')}`);

const nullFields = orders.filter(o => !o.product || !o.customer);
if (nullFields.length) bugs.push(`Null fields: ${nullFields.map(o => o.id).join(', ')}`);

console.log(`${orders.length} orders, ${bugs.length} bugs found:`);
bugs.forEach(b => console.log(`- ${b}`));

範例 2：Maven 專案的相依性衝突盤點（企業場景）

import subprocess, re, collections

out = subprocess.run(["mvn", "-q", "dependency:tree", "-Dverbose"],
                     capture_output=True, text=True).stdout

# 抓出所有 omitted for conflict 的項目
conflicts = re.findall(r"omitted for conflict with ([\d.]+)\)[^\n]*", out)
lines = [l for l in out.split("\n") if "omitted for conflict" in l]

groups = collections.defaultdict(set)
for l in lines:
    m = re.search(r"([\w.\-]+):([\w.\-]+):jar:([\d.]+)", l)
    if m:
        groups[f"{m.group(1)}:{m.group(2)}"].add(m.group(3))

print(f"共發現 {len(lines)} 處版本衝突，涉及 {len(groups)} 個 artifact：")
for art, vers in sorted(groups.items(), key=lambda x: -len(x[1]))[:15]:
    print(f"  {art}: {', '.join(sorted(vers))}")

傳統做法：mvn dependency:tree 輸出數千行全部進 Context。 這個做法：約 1 KB 的衝突清單進 Context。

範例 3：查 GitHub PR 狀態（官方範例）

gh pr list --json number,title,state,reviewDecision \
  --jq '.[] | "\(.number) [\(.state)] \(.title) — \(.reviewDecision // "no review")"'

最佳實務

1. 一定要 console.log / print，沒輸出等於白做
2. 寫分析程式，不是傾印程式
3. 輸出要具體：印出 ID、行號、確切數值
4. 盡量帶 intent，免費的安全網
5. 選對語言：API/JSON → javascript；資料統計 → python；pipe 串接 → shell

常見錯誤

15.2 ctx_execute_file

目的

在 sandbox 內處理本地檔案，原始內容永不進入 Context。 [Official]

適用情境

輸入

輸出

stdout。官方 benchmark：45 KB 的 access log → 155 B。 [Benchmark]

範例

範例 1：解析大型 JSON（官方範例）

# FILE_CONTENT 由 ctx_execute_file 預先載入
import json
data = json.loads(FILE_CONTENT)
print(f"Records: {len(data)}")
# ... 分析並印出發現

範例 2：Nginx access log 的錯誤分析（企業場景）

import re, collections
from datetime import datetime

lines = FILE_CONTENT.strip().split("\n")
pat = re.compile(r'(\S+) .* \[([^\]]+)\] "(\w+) (\S+)[^"]*" (\d{3}) (\d+)')

total = 0
by_status = collections.Counter()
err_by_path = collections.Counter()
err_by_ip = collections.Counter()
err_by_hour = collections.Counter()

for l in lines:
    m = pat.search(l)
    if not m:
        continue
    total += 1
    ip, ts, method, path, status, size = m.groups()
    by_status[status[0] + "xx"] += 1
    if status.startswith("5"):
        err_by_path[f"{method} {path.split('?')[0]}"] += 1
        err_by_ip[ip] += 1
        err_by_hour[ts[12:14]] += 1

print(f"總請求 {total} 筆")
print("狀態碼分布：", dict(by_status))
print(f"\n5xx 共 {by_status['5xx']} 筆，Top 5 路徑：")
for p, c in err_by_path.most_common(5):
    print(f"  {c:5d}  {p}")
print(f"\n來源 IP Top 3：{err_by_ip.most_common(3)}")
print(f"時段分布：{sorted(err_by_hour.items())}")

範例 3：Java 原始碼的執行緒安全掃描（企業場景）

import re

is_spring_bean = bool(re.search(r"@(Service|Component|Repository|Controller|RestController)", FILE_CONTENT))
static_sdf = re.findall(r"(?:private|public|protected)?\s+static\s+.*SimpleDateFormat\s+(\w+)", FILE_CONTENT)
local_sdf  = len(re.findall(r"new\s+SimpleDateFormat", FILE_CONTENT))

if is_spring_bean and static_sdf:
    print(f"🔴 高風險：Spring singleton + static SimpleDateFormat → {static_sdf}")
elif static_sdf:
    print(f"🟡 中風險：static SimpleDateFormat（非 Spring bean）→ {static_sdf}")
elif local_sdf:
    print(f"🟢 低風險：{local_sdf} 處 method-local SimpleDateFormat")
else:
    print("✅ 未使用 SimpleDateFormat")

最佳實務

1. 記住 FILE_CONTENT 已經載好了，不要在程式碼裡再開檔
2. 要「編輯」的檔案不要用這個，用一般的 Read / Edit 工具
3. 搭配 ctx_execute 先把大型輸出存檔，再用這個處理

常見錯誤

15.3 ctx_batch_execute

目的

在一次呼叫中執行多個指令 + 多個查詢。 [Official]

適用情境

• 需要同時蒐集多個面向的資訊（例如專案盤點：git 統計 + 相依性 + 測試覆蓋率 + TODO 數）
• 避免多次 round trip（每次 round trip 都有固定的工具定義與回傳格式成本）
• ctx_search 被節流後的替代路徑

輸入

輸出

各項目的結果彙整。官方 benchmark：986 KB → 62 KB（94% 節省）[Benchmark]。

範例（企業場景：新專案接手的第一次盤點）

ctx_batch_execute([
  { language: "shell", code: "git log --oneline | wc -l && git shortlog -sn | head -10" },
  { language: "shell", code: "find src -name '*.java' | wc -l && find src -name '*Test.java' | wc -l" },
  { language: "shell", code: "mvn -q dependency:tree | grep -c 'omitted for conflict'" },
  { language: "shell", code: "grep -rn 'TODO\\|FIXME\\|XXX' src --include='*.java' | wc -l" },
  { language: "shell", code: "find . -name 'application*.yml' -o -name 'application*.properties' | head -20" }
], concurrency: 5)

一次呼叫拿到：commit 數、主要貢獻者、程式碼與測試檔數量、相依衝突數、技術債數量、設定檔位置。

最佳實務

1. concurrency 只對 I/O bound 有意義（網路、磁碟），CPU bound 反而更慢
2. 每個項目仍要各自 print 結論
3. 當 ctx_search 被節流時，改用它批次查詢

常見錯誤

[Community] 已知 issue：ctx_batch_execute 的 timeout 不會涵蓋 indexing / search 階段，導致 Agent 可能掛住數小時。

15.4 ctx_index

目的

把 Markdown 內容依標題切塊，索引進 SQLite FTS5（BM25 排名）。 [Official]

適用情境

• 已存檔的大型輸出（Playwright snapshot、API dump）需要多次查詢
• 本地文件目錄要變成可搜尋的知識庫
• 規格書、設計文件需要反覆查閱

輸入

輸出

確認訊息，約 40–80 B。官方 benchmark：60 KB → 40 B [Benchmark]。

範例

# 索引 Playwright snapshot
ctx_index(path: "D:/tmp/playwright-snapshot.md", source: "Playwright snapshot")

# 索引整個文件目錄
ctx_index(path: "./docs/architecture", source: "project:payment-arch")

# CLI 版本
context-mode index . --source project:my-app

最佳實務

1. 永遠用 path，不要用 content 傳大資料（官方最高優先的規則之一）
2. 一定要給 source，否則後續搜尋會跨來源污染
3. source 命名建議用階層式：project:<專案>、vendor:<套件>、snapshot:<日期>

常見錯誤

15.5 ctx_search

目的

查詢已索引內容，回傳相關片段。 [Official]

輸入

輸出

命中的內容片段，程式碼區塊完整保留。

範例

✅ 正確：一次批次查完
ctx_search(
  queries: ["transform pipe", "refine superRefine", "coerce codec"],
  source: "Zod"
)

✅ 只要程式碼範例
ctx_search(
  queries: ["useEffect cleanup"],
  source: "React",
  contentType: "code"
)

❌ 錯誤：連續呼叫三次
ctx_search(query: "transform pipe")
ctx_search(query: "refine superRefine")
ctx_search(query: "coerce codec")

最佳實務

[Official] 官方 SKILL 的四條查詢策略：

1. BM25 是 OR 語意，命中越多詞排越前，不用刻意組 AND
2. 每個 query 用 2–4 個具體技術詞，不要寫成一整句問句
3. 多份文件並存時一定加 source
4. 一定用 queries 陣列批次查詢

常見錯誤

15.6 ctx_fetch_and_index

目的

抓 URL → 轉 Markdown → 切塊 → 索引。原始頁面永不進 Context。 [Official]

輸入

輸出

確認訊息（約 40 B）。快取命中時回傳約 0.3 KB 的 cache hint [Official]。

範例（企業場景：Spring Boot 升級調研）

ctx_fetch_and_index(
  requests: [
    { url: "https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-3.3-Release-Notes",
      source: "SpringBoot 3.3" },
    { url: "https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-3.4-Release-Notes",
      source: "SpringBoot 3.4" }
  ],
  concurrency: 2,
  ttl: 604800000        // 7 天（release notes 不會變）
)

然後：
ctx_search(
  queries: ["deprecated removed", "breaking change", "configuration property rename"],
  source: "SpringBoot"
)

[Official] GitHub 專案的小技巧：用 raw URL 直接抓原始 Markdown，避免 HTML 轉換的雜訊： https://raw.githubusercontent.com/org/repo/main/CHANGELOG.md

最佳實務

1. 外部套件文件一律用這個，官方明確禁止對「你不擁有的套件」用 cat 或本地路徑
2. TTL 依內容穩定度調整（見 6.5）
3. 多 URL 一次抓完，用 requests + concurrency

常見錯誤

15.7 ctx_stats

目的

顯示 Context 節省量、呼叫次數、session 統計。 [Official]

範例

# 在任何 AI session 中
ctx stats

# Claude Code slash command
/context-mode:ctx-stats

輸出內容 [Official]

• 逐工具的節省細項
• Token 消耗
• 節省比例
• 快取效能另外列出：命中次數、避免的資料量、省下的網路請求

最佳實務與重要警告

[Official] ctx_stats 是唯讀的。它不會重設或清除任何東西。要刪除索引請用 ctx_purge(confirm: true)。

[Community] [AI Analysis] 企業必讀：ctx_stats 的數字是觀測值，不是帳單金額。官方 open issue 中就有回報：

• per-chat 的「kept out」（2.7 MB）超過全專案總計（868 KB）
• 零 ctx_execute 呼叫的 session 顯示 100% savings

不要把 ctx_stats 的數字直接寫進企業 KPI 報告。 請用 第 26 章 的方法自行量測。

15.8 ctx_doctor

目的

診斷安裝狀態：runtime、hooks、FTS5、版本、plugin 註冊。 [Official]

範例

# CLI
context-mode doctor

# AI session
ctx doctor

# Claude Code
/context-mode:ctx-doctor

企業使用標準

見 24.3 診斷 SOP。

最重要的一句話

[Official] 「ctx stats proves the plugin MCP server is installed and reachable; it does not prove hooks are trusted or running.」

驗證安裝，只能用 ctx doctor。

15.9 ctx_upgrade

目的

從 GitHub 更新、重建、重新設定 hook。 [Official]

範例

context-mode upgrade

# 指定平台（多 Agent 機器）
CONTEXT_MODE_PLATFORM=copilot-cli context-mode upgrade

它會做什麼 [Official]

• 拉最新版、重建
• 修復 / 寫入 hook 設定檔
• 遷移快取
• 移除 OpenCode / KiloCode 的 legacy mcp.context-mode 項目（保留其他 MCP server）

常見錯誤

15.10 ctx_purge

目的

永久刪除知識庫中所有索引內容。 [Official]

範例

ctx_purge(confirm: true)

⚠️ 警告

• 不可復原
• 刪除的是索引內容（<root>/content）
• 需要 confirm: true

企業使用時機 [Enterprise Recommendation]

[Enterprise Recommendation] 建議把「誤索引 production 資料 → 立即 ctx_purge(confirm: true) → 通報資安」寫進事件處理程序。

15.11 ctx_insight

目的

開啟 hosted Insight dashboard（context-mode.com/insight）。官方描述為「org analytics for AI-assisted engineering teams」。 [Official]

這是全部 11 個工具中唯一會離開本機的一個，也是唯一屬於付費商業方案（Organization tier， 每席 USD 20／月）的功能。其餘 10 個工具完全在本機運作。

它提供什麼 [Official]

• 角色別儀表板（CTO／工程主管／個別開發者／資安／財務與 DevOps）
• 生產性 session 比率、團隊 retry waste、行為樣態
• FinOps 成本歸因：per-model 支出、context-mode 節省量、net ROI（見 第 31 章）

傳送什麼、不傳送什麼 [Official]

⚠️ 企業處理原則

[Enterprise Recommendation] 預設停用。 啟用前須完成路徑命名風險評估與 DPA 簽署； 金融業建議維持禁用。

最容易被忽略的一點：官方不傳送檔案「內容」，但會傳送檔案「路徑」。 如果你的 repo 目錄以客戶名或案件代號命名，路徑本身就是敏感資訊。

完整判讀與分級處置見 可信度標示制度的落差三 與 23.3。

15.12 安全機制：三道防線

[Official] 這三道防線是企業資安審查的重點，必須理解。

防線一：權限規則繼承

Context Mode 把你現有的權限規則延伸到 MCP sandbox。如果你擋了 sudo，那麼 ctx_execute、ctx_execute_file、ctx_batch_execute 裡面也擋。

{
  "permissions": {
    "deny": ["Bash(sudo *)", "Bash(rm -rf /*)", "Read(.env)", "Read(**/.env*)"],
    "allow": ["Bash(git:*)", "Bash(npm:*)"]
  }
}

• 放在 .claude/settings.json（專案）或 ~/.claude/settings.json（全域）
• 所有平台都讀這個格式，包含 Gemini CLI、VS Code Copilot、OpenCode
• Codex 需要 hooks 設定好才會執行安全強制
• 零設定時不啟用

防線二：專案邊界圍籬

[Official] ctx_execute_file 被限制在專案根目錄內。以下情況會被 File access blocked 拒絕：

• 絕對路徑指向專案外（如 /home/user/secrets）
• ../../ 路徑穿越
• 專案內的 symlink 指向專案外

這道防線的來歷（#852）很值得企業理解：

攻擊路徑：
  1. Agent 想讀專案外的檔案 → host sandbox 拒絕
  2. Agent 改用 MCP sandbox 重試
  3. host 的 MCP 核准提示「看不到工具的輸入參數」
     → 核准者根本不知道它要讀哪個檔案
  4. 繞過成功

修補：在 MCP 層自己做圍籬，預設開啟，不需設定

要刻意開放專案外路徑（例如 /var/log 的共用 log）：

{
  "permissions": {
    "allow": ["Read(/var/log/**)"]
  }
}

[Official] 用的是跟 host Read 工具同一條 allow 規則，沒有 context-mode 專屬的環境變數開關。這是刻意設計：授權集中在一個地方。

[Official] 但要注意防線的極限：ctx_execute 與 ctx_batch_execute 執行任意程式碼，仍繼承 process 的檔案系統存取權。圍籬是給檔案讀取工具的縱深防禦，不是完整的 OS sandbox。

核准任何執行工具 = 核准執行任意程式碼。請保持 host 層級沙箱開啟。

防線三：網路抓取強化

[Official] ctx_fetch_and_index 預設封鎖：

在 hosted / CI 環境要連內網也擋：

export CTX_FETCH_STRICT=1

附加：憑證遮罩

[Official] 任何 mcp__* 工具呼叫的 tool_input 在寫入 session DB 前會被遮罩。hooks/posttooluse.mjs 的正則會把以下欄位（大小寫、連字號／底線不敏感）換成 [REDACTED]：

authorization、auth_token、access_token、refresh_token、bearer、token、secret、password、passwd、pwd、api_key / apikey / x_api_key、cookie / set-cookie、signature、private_key、client_secret

[Enterprise Recommendation] 這個清單很完整，但只涵蓋 MCP 工具參數。它不會遮罩：

• 你的腳本 print 出來的內容
• 被索引的檔案內容
• 非 MCP 工具的輸出

企業仍需自行建立資料分類與遮罩規範，見 第 23 章。

15.13 Utility Commands 速查

[Official]

在任何 AI session 中輸入（模型會自動呼叫對應的 MCP 工具）：

ctx stats       → Context 節省統計、呼叫次數、session 報告
ctx doctor      → 診斷 runtime、hooks、FTS5、版本
ctx index       → 索引本地檔案或目錄
ctx search      → 搜尋已索引內容
ctx upgrade     → 更新、重建、重設 hook
ctx purge       → 永久刪除所有索引內容
ctx insight     → 開啟 hosted dashboard（企業建議停用）

從終端機直接執行：

context-mode doctor
context-mode index . --source project:my-app
context-mode search "authentication middleware" --source project:my-app
context-mode upgrade
context-mode insight
bash scripts/ctx-debug.sh        # 完整診斷報告（回報 bug 用）

[Official] ctx-debug.sh 會收集：OS 資訊、runtime 版本、better-sqlite3 狀態、adapter 偵測結果、設定檔（已遮罩）、hook 驗證、FTS5/SQLite 測試、executor 測試、程序檢查、session 資料庫、環境變數，輸出成一份可直接貼上的 Markdown 報告。

Slash Commands（只有 Claude Code）：/ctx-stats、/ctx-doctor、/ctx-index、/ctx-search、/ctx-upgrade、/ctx-purge、/ctx-insight

15.14 本章實務案例

情境：開發者要為一個 5,000 檔案的專案做「架構健檢」，需要：模組相依關係、循環相依、過大的類別、缺測試的模組。

錯誤做法（會爆 Context）：

1. Read 每個 package-info.java
2. Read 每個 pom.xml
3. glob 所有 *Test.java 再逐一 Read
→ 第 50 個檔案就撐不住了

正確做法（一次 ctx_batch_execute）：

ctx_batch_execute([
  {
    language: "python",
    intent: "找出循環相依",
    code: '''
import os, re, collections
deps = collections.defaultdict(set)
for root, _, files in os.walk("src/main/java"):
    for f in files:
        if not f.endswith(".java"): continue
        p = os.path.join(root, f)
        src = open(p, encoding="utf-8", errors="ignore").read()
        m = re.search(r"^package\\s+([\\w.]+)", src, re.M)
        if not m: continue
        pkg = m.group(1)
        for imp in re.findall(r"^import\\s+(com\\.mycompany\\.[\\w.]+)", src, re.M):
            target = ".".join(imp.split(".")[:-1])
            if target != pkg: deps[pkg].add(target)

cycles = [(a, b) for a in deps for b in deps[a] if a in deps.get(b, ())]
print(f"套件數 {len(deps)}，相依邊 {sum(len(v) for v in deps.values())}")
print(f"循環相依 {len(cycles)} 組：")
for a, b in sorted(set(map(lambda x: tuple(sorted(x)), cycles)))[:10]:
    print(f"  {a} <-> {b}")
    '''
  },
  {
    language: "shell",
    intent: "找出過大的類別",
    code: "find src/main/java -name '*.java' -exec wc -l {} + | sort -rn | head -15"
  },
  {
    language: "shell",
    intent: "找出缺少測試的模組",
    code: '''
for d in src/main/java/com/mycompany/*/; do
  n=$(basename "$d")
  m=$(find "$d" -name '*.java' | wc -l)
  t=$(find src/test/java/com/mycompany/"$n" -name '*Test.java' 2>/dev/null | wc -l)
  echo "$n: 主程式 $m / 測試 $t"
done | awk -F'[:/ ]+' '$NF == 0 || $(NF-2) / ($NF + 1) > 5'
    '''
  }
], concurrency: 3)

結果：一次呼叫，約 2 KB 進 Context，涵蓋 5,000 個檔案的三個面向分析。

而且：這三段腳本可以直接存成 repo 裡的 scripts/arch-health.sh，變成團隊資產與 CI 檢查項目。

15.15 本章注意事項

1. ctx_index 永遠用 path，不要用 content 傳大資料。
2. ctx_search 一定用 queries 陣列，不然會被節流。
3. ctx_stats 的數字不能當 KPI，有已知的計算 bug。
4. ctx_doctor 是唯一可信的驗證方式。
5. ctx_purge 不可復原，但誤索引敏感資料時要立刻用。
6. ctx_insight 企業預設停用。
7. 三道防線不等於 OS sandbox，ctx_execute 仍可執行任意程式碼。
8. 憑證遮罩只涵蓋 MCP 工具參數，不涵蓋腳本輸出與索引內容。

15.16 本章檢查清單

• 我知道 11 個工具各自的用途與適用情境
• 我會用決策樹判斷該用哪個工具
• 我知道 ctx_index(content:) 的成本陷阱
• 我會用 queries 陣列批次搜尋
• 我知道 ctx_stats 不能當 KPI，要用自建 benchmark
• 我知道三道安全防線的範圍與極限
• 我知道誤索引敏感資料時要立刻 ctx_purge
• 我知道 ctx-debug.sh 可以產生完整診斷報告

第 16 章 AI Agent Prompt 標準

本章的價值 [Enterprise Recommendation]：把 Context Mode 的使用方式寫成標準 prompt，貼進 CLAUDE.md / AGENTS.md / copilot-instructions.md，讓全團隊的 Agent 行為一致。

16.1 通用基礎 Prompt

適用於所有平台。放進專案的 routing 指令檔。

## Context Mode 使用規範

你正在使用 Context Mode。在分析任何大型資料之前，請依序判斷：

1. 判斷資料量：這個操作的輸出可能超過 20 行嗎？不確定就當作「會」。
2. 優先使用 ctx_search：如果資料已經索引過，先搜尋，不要重新取得。
3. 優先使用 ctx_execute / ctx_execute_file：需要分析時，寫腳本讓程式算，
   不要把原始資料讀進 Context 後用人工方式判讀。
4. 優先使用 ctx_batch_execute：需要多個面向的資訊時，一次呼叫問完，
   不要連續發多個請求。
5. 避免把完整原始輸出載入 Context：
   - 絕不使用 ctx_index(content: <大資料>)，一律用 ctx_index(path: ...)
   - Playwright 工具一律帶 filename 參數
   - 已經在 Context 裡的 MCP 輸出，直接使用，不要重複索引
6. 只取得與當前任務相關的證據：搜尋時給 2-4 個具體技術詞，
   多份文件並存時一定帶 source 參數。
7. 如果真的需要完整資料，請先說明原因再取得。

### 撰寫分析腳本的紀律
- 一定要 console.log / print 你的發現，stdout 是唯一會進入 Context 的東西
- 寫「分析程式」不是「傾印程式」：先算出結論，再輸出
- 輸出要具體：印出 ID、行號、確切數值，不要只印數量
- 不要在腳本裡先用 head / tail 截斷資料
- 要「編輯」的檔案請用一般的 Read / Edit 工具，Context Mode 只負責分析

16.2 Web Development Prompt

## Web 開發時的 Context Mode 使用方式

### 前端
- 檢視頁面結構：browser_snapshot(filename) → ctx_execute_file(path)
- 需要多次查詢同一個頁面：browser_snapshot(filename) → ctx_index(path) → ctx_search
- Console / Network 檢查：browser_console_messages(level:"error", filename) → ctx_execute_file
- 注意：browser_navigate 會自動回傳 snapshot，請忽略它，另外呼叫 browser_snapshot

### 後端
- 打 API 驗證：ctx_execute（javascript + fetch），在腳本內驗證回應結構、
  檢查欄位缺漏、數值合理性，只印出異常項目
- 跑測試：ctx_execute 執行測試指令，解析結果，只印出失敗案例與原因
- 查 log：ctx_execute_file，全量掃描後印出統計與異常樣態

### 資料庫
- Schema 分析：ctx_execute 執行查詢並在腳本內彙整，
  不要把整份 schema dump 進 Context
- 慢查詢分析：ctx_execute_file 處理 slow query log，依耗時分組

### 第三方文件
- 一律使用 ctx_fetch_and_index，不要用 WebFetch
- GitHub 專案用 raw URL：https://raw.githubusercontent.com/org/repo/main/xxx.md

16.3 Reverse Engineering Prompt

## Legacy 系統逆向工程的 Context Mode 使用方式

嚴格禁止：Read all source code。

請依下列順序進行：

【階段 1：盤點（不讀內容，只統計）】
用 ctx_batch_execute 一次取得：
  - 檔案數量與副檔名分布
  - 程式碼行數分布（找出最大的 20 個檔案）
  - 進入點（main、Controller、Servlet、Form、批次排程）
  - 設定檔位置（*.config、*.properties、*.ini、web.xml）
  - 外部依賴徵兆（DB 連線字串樣式、FTP、MQ、WebService URL）

【階段 2：索引】
用 ctx_index 把以下內容建成可搜尋知識庫：
  - 所有設定檔
  - 所有 SQL / Stored Procedure
  - 所有介面定義檔
  各自給不同的 source 標籤

【階段 3：針對性搜尋】
用 ctx_search 依主題查詢，不要逐檔閱讀：
  - 「交易 commit rollback」找交易邊界
  - 「connection pool timeout」找連線設定
  - 「schedule cron batch」找排程

【階段 4：程式化分析】
用 ctx_execute 寫腳本產生：
  - 呼叫關係圖（誰呼叫誰）
  - 資料表使用矩陣（哪個模組動哪張表）
  - 死碼清單（沒有任何呼叫者的函式）

【階段 5：產出】
根據前四階段的「結論」（不是原始碼）撰寫：
  - 系統架構圖
  - 功能清單
  - 資料流
  - 需求規格書

只有在需要「引用具體實作細節」時，才讀取特定檔案的特定區段。

16.4 Framework Upgrade Prompt

## Framework 升級的 Context Mode 使用方式

【步驟 1：索引官方升級資訊】
ctx_fetch_and_index(
  requests: [
    { url: "<目標版本的 release notes>", source: "<框架> <版本>" },
    { url: "<migration guide>",          source: "<框架> Migration" },
    { url: "<raw CHANGELOG URL>",        source: "<框架> CHANGELOG" }
  ],
  concurrency: 3,
  ttl: 604800000
)

【步驟 2：查 breaking changes】
ctx_search(
  queries: ["breaking change removed", "deprecated replacement",
            "configuration property rename", "minimum version requirement"],
  source: "<框架>"
)

【步驟 3：分析現有程式碼的受影響範圍】
ctx_execute 寫腳本，針對步驟 2 找到的每個 breaking change，
掃描專案原始碼，統計：
  - 受影響的檔案數量
  - 受影響的具體位置（檔名 + 行號）
  - 風險等級

【步驟 4：分析相依性】
ctx_execute 執行 mvn dependency:tree / npm ls，
在腳本內找出：
  - 版本衝突
  - 與目標版本不相容的套件
  - 需要一併升級的傳遞相依

【步驟 5：產出遷移報告】
根據前四步的結論產生報告，包含：
  - 必須修改的項目（含檔案與行號）
  - 建議修改的項目
  - 可延後的項目
  - 預估工時

全程不要把完整的 release notes 或 dependency tree 讀進 Context。

16.5 Debug Prompt

## Debug 時的 Context Mode 使用方式

【禁止】
- 不要把完整的 stack trace 檔案 cat 進 Context
- 不要逐一 Read 呼叫鏈上的每個檔案

【建議流程】
1. 先用 ctx_execute_file 分析 log，找出：
   - 錯誤的確切訊息與發生次數
   - 第一次發生的時間
   - 是否有前置的警告
   - 相關的 request id / trace id

2. 用 ctx_execute 執行 git log / git blame，找出：
   - 相關檔案最近的修改
   - 修改者與 commit message

3. 用 ctx_search 查已索引的框架文件，找出：
   - 這個錯誤訊息的官方說明
   - 已知的常見原因

4. 只有在確定範圍後，才用 Read 讀取具體的問題程式碼

5. 修好之後用 ctx_execute 跑測試驗證，只印出結果摘要

16.6 Log Analysis Prompt

## Log 分析的 Context Mode 使用方式

絕對不要把 log 檔案內容直接讀進 Context，不論大小。

【標準流程】
ctx_execute_file(path: <log 檔>, language: "python", intent: <你要找什麼>, code: 分析腳本)

分析腳本至少要輸出：
  1. 總筆數與時間範圍
  2. 依嚴重度分組的計數（ERROR / WARN / INFO）
  3. Top N 的錯誤訊息樣態（用正則正規化掉變動的 ID / 時間）
  4. 時間分布（找出是否集中在特定時段）
  5. 具體的證據樣本（最多 3-5 筆完整的原始 log 行）

【多個 log 檔】
用 ctx_batch_execute 一次處理，不要一個一個來

【超大 log（> 1 GB）】
先用 shell 依時間範圍切出需要的區段到暫存檔，
再用 ctx_execute_file 分析那個區段。
切分本身也在 ctx_execute 裡做，不要在 Context 裡。

16.7 Security Review Prompt

## Security Review 的 Context Mode 使用方式

【重要前提】
Context Mode 不是 security scanner。它負責處理掃描工具的大量輸出，
實際的弱點偵測仍由 SAST / DAST / SCA 工具負責。

【標準流程】
1. 用 ctx_execute 執行掃描工具，在腳本內做風險過濾：
   - npm audit --json → 只印出 high / critical，含套件名、版本、CVE、修復版本
   - mvn dependency-check → 只印出 CVSS >= 7.0 的項目
   不要把完整的掃描報告印出來

2. 用 ctx_fetch_and_index 索引相關的 CVE 說明，再用 ctx_search 查細節

3. 用 ctx_execute 掃描原始碼中的風險樣態：
   - 硬編碼的憑證樣式
   - SQL 字串拼接
   - 未經驗證的重導向
   只印出檔名 + 行號 + 樣態，不要印出實際內容
   （避免把可能的 secret 帶進 Context）

【絕對禁止】
- 不要索引 production 資料
- 不要把含有真實憑證的設定檔索引進知識庫
- 若不慎索引，立即執行 ctx_purge(confirm: true) 並通報資安

16.8 Performance Analysis Prompt

## 效能分析的 Context Mode 使用方式

1. APM / Profiler 輸出 → ctx_execute_file
   在腳本內找出 Top N 熱點，只印出方法名、耗時、呼叫次數

2. 慢查詢分析 → ctx_execute_file 處理 slow query log
   正規化 SQL（把參數換成 ?），依樣態分組統計總耗時

3. 壓測結果（JMeter / k6）→ ctx_execute_file
   只印出：TPS、P50/P90/P99、錯誤率、瓶頸時間點

4. GC log → ctx_execute_file
   統計 GC 次數、暫停時間分布、是否有 Full GC

5. 容器資源 → ctx_execute 執行 kubectl top / docker stats
   在腳本內比對 limit 與實際用量，只印出超標項目

原則：效能分析的原始資料通常是數萬行的數值，
這正是「該用程式算、不該用模型讀」的典型場景。

16.9 本章實務案例

情境：某團隊發現不同開發者用 Context Mode 的效果差很多——有人省 90%，有人只省 30%。

調查發現：

省 90% 的開發者：
  - 習慣先寫分析腳本
  - 一次 batch 問完多個問題
  - 會帶 intent 參數

省 30% 的開發者：
  - 用 ctx_execute 但只是把指令包一層，沒有分析
    例：ctx_execute("shell", "kubectl get pods -A")
        → 還是把完整輸出印出來了
  - 連續多次 ctx_search
  - 不帶 source，搜尋品質差就再搜一次

根因：工具會用，但方法論沒建立。

解法：把 16.1 的標準 prompt 放進專案的 copilot-instructions.md，並加上一條具體的反例：

### 錯誤示範（請勿模仿）
ctx_execute("shell", "kubectl get pods -A")
→ 這只是把指令包一層，完整輸出照樣進 Context

### 正確示範
ctx_execute("shell", `
kubectl get pods -A -o json | jq -r '
  .items[] |
  select(.status.phase != "Running") |
  "\\(.metadata.namespace)/\\(.metadata.name): \\(.status.phase)"
'
echo "---"
kubectl get pods -A --no-headers | wc -l | xargs echo "總 Pod 數:"
`)
→ 只印出異常的 pod 與總數

成效：兩週後全團隊的平均節省率從 52% 提升到 81%。

[Enterprise Recommendation] 這個案例的教訓：Context Mode 的效果 60% 取決於使用方法，只有 40% 取決於安裝設定。導入時的教育訓練投資，回報率比技術設定高。

16.10 本章注意事項

1. Prompt 要放在會被自動載入的檔案裡（CLAUDE.md / AGENTS.md / copilot-instructions.md），不是口頭交代。
2. IDE 版 Copilot 沒有 UserPromptSubmit，更要依賴 instruction 檔。
3. 不要在 prompt 裡寫「請簡短回答」，會傷害推理品質。
4. 標準 prompt 要附反例，光講正確做法效果有限。
5. Security Review 的 prompt 要特別強調「不印出實際內容」，避免 secret 進 Context。

16.11 本章檢查清單

• 團隊的 routing 指令檔已包含通用基礎 Prompt
• 針對團隊主要工作型態，已有對應的專用 Prompt
• Prompt 中含有具體的錯誤示範
• Prompt 中沒有「請簡短回答」這類指令
• Security Review Prompt 已包含敏感資料處理規範
• 新人 onboarding 包含 Prompt 使用教學

Part 5 開發情境實戰篇

本 Part 的目標：把前面的概念落到真實的企業開發場景。三個完整案例（Web 開發 / 逆向工程 / Framework 升級）加上七個專項情境。

每個案例都遵循同一條資料流：

User Request → AI Agent → Context Mode → Tool → Sandbox
  → Index / Search → Relevant Evidence → AI Reasoning → Output

第 17 章 Web Application 開發實戰

17.1 完整案例 A：從零開始開發企業 Web Application

專案設定：某產險公司的「線上投保平台」

• 前端：Vue 3 + TypeScript
• 後端：Spring Boot 3.4 + Java 21
• 資料庫：PostgreSQL 16
• 團隊：1 PM、1 SA、4 開發、1 QA、1 DevOps

17.2 Context Mode 在各階段的介入點

flowchart TD
    R["① Requirement<br/>需求"] --> A["② Architecture<br/>架構"]
    A --> F["③ Frontend<br/>前端"]
    A --> B["④ Backend<br/>後端"]
    A --> D["⑤ Database<br/>資料庫"]
    F --> T["⑥ Test<br/>測試"]
    B --> T
    D --> T
    T --> S["⑦ Security<br/>資安"]
    S --> DP["⑧ Deployment<br/>部署"]

    R -.->|"ctx_fetch_and_index<br/>索引法規與同業規格<br/>ctx_search 查條文"| CM1["Context Mode"]
    A -.->|"ctx_fetch_and_index<br/>索引框架官方文件<br/>ctx_execute 評估選型"| CM1
    F -.->|"browser_snapshot(filename)<br/>→ ctx_execute_file<br/>驗證頁面結構"| CM1
    B -.->|"ctx_execute + fetch<br/>驗證 API 契約"| CM1
    D -.->|"ctx_execute 查 schema<br/>在腳本內比對設計"| CM1
    T -.->|"ctx_execute 跑測試<br/>只回傳失敗摘要"| CM1
    S -.->|"ctx_execute 跑 audit<br/>風險過濾後才回傳"| CM1
    DP -.->|"ctx_execute kubectl<br/>只回傳異常項目"| CM1

    style CM1 fill:#d4edda,stroke:#28a745,stroke-width:3px

17.3 階段一：Requirement（需求）

PM 的任務：把「線上投保」的法規要求與同業做法整理成需求清單。

傳統做法的問題：金管會的保險業相關函令、示範條款動輒數十頁 PDF / HTML，全部貼進 Context 會直接塞滿。

Context Mode 做法：

步驟 1：索引法規文件
ctx_fetch_and_index(
  requests: [
    { url: "<主管機關線上投保相關規定頁面>", source: "法規:線上投保" },
    { url: "<個資法施行細則相關頁面>",       source: "法規:個資" },
    { url: "<電子簽章法相關頁面>",           source: "法規:電子簽章" }
  ],
  concurrency: 3,
  ttl: 2592000000        // 30 天，法規不常變
)

步驟 2：針對性查詢
ctx_search(
  queries: ["身分驗證 要式 核保", "保費收取 信用卡 授權",
            "契約撤銷權 期間 通知", "個人資料 蒐集 告知"],
  source: "法規"
)
→ 只有命中的條文段落進 Context（約 4 KB）

步驟 3：產出需求清單
AI 根據命中的條文，產出：
  - 必要功能清單（含法規依據）
  - 必要的告知與同意畫面
  - 資料保存年限要求

效益：PM 不需要自己讀完所有法規，也不需要把法規全文塞進 AI。而且索引留著，後續開發過程中任何人都能查。

[Enterprise Recommendation] 法規、契約、規格書這類「需要精確引用條文」的內容，正是 FTS5 關鍵字檢索的強項（比語意檢索更準確，不會「差不多就命中」）。

17.4 階段二：Architecture（架構）

SA 的任務：確認 Spring Boot 3.4 + Java 21 的技術選型細節。

步驟 1：索引官方文件
ctx_fetch_and_index(
  requests: [
    { url: "https://raw.githubusercontent.com/spring-projects/spring-boot/main/README.md",
      source: "SpringBoot" },
    { url: "<Spring Security 6 官方文件>", source: "SpringSecurity" },
    { url: "<Vue 3 官方文件>",             source: "Vue3" }
  ],
  concurrency: 3
)

步驟 2：查關鍵決策點
ctx_search(
  queries: ["virtual thread configuration", "JWT resource server",
            "problem details RFC 7807", "graceful shutdown"],
  source: "SpringBoot"
)

步驟 3：驗證假設（實際跑一次）
ctx_execute("shell", `
  # 用 Spring Initializr 產一個測試專案驗證版本組合
  curl -s https://start.spring.io/metadata/client | \\
    jq -r '.bootVersion.values[] | select(.id | startswith("3.4")) | .id' | head -5
  echo "---"
  java -version 2>&1 | head -1
  mvn -version 2>&1 | head -1
`)

17.5 階段三：Frontend（前端）

開發者的任務：驗證投保表單的欄位與驗證規則是否符合設計。

❌ 傳統做法：
browser_snapshot() → 56 KB accessibility tree 進 Context
→ 模型「肉眼」比對，容易漏

✅ Context Mode 做法：
步驟 1：browser_navigate("http://localhost:5173/apply")
        （忽略它自動回傳的 snapshot）

步驟 2：browser_snapshot(filename: "D:/tmp/apply-form.md")
        → 約 50 B 確認訊息

步驟 3：ctx_execute_file(
  path: "D:/tmp/apply-form.md",
  language: "python",
  intent: "比對表單欄位與設計規格",
  code: '''
import re

# 設計規格要求的欄位
spec = {
    "姓名": "textbox", "身分證字號": "textbox", "出生日期": "textbox",
    "手機": "textbox", "email": "textbox", "地址": "textbox",
    "投保金額": "combobox", "受益人": "textbox",
    "同意條款": "checkbox", "同意個資": "checkbox"
}

found = {}
for line in FILE_CONTENT.split("\\n"):
    m = re.search(r'- (\\w+) "([^"]+)"', line)
    if m:
        found[m.group(2)] = m.group(1)

missing = [k for k in spec if not any(k in f for f in found)]
wrong = [(k, spec[k], found.get(k)) for k in spec
         if any(k in f for f in found) and spec[k] not in str(found)]

print(f"規格要求 {len(spec)} 個欄位，頁面找到 {len(found)} 個互動元素")
print(f"缺少：{missing if missing else '無'}")
print(f"型態不符：{wrong if wrong else '無'}")

# 無障礙檢查
no_label = [l.strip() for l in FILE_CONTENT.split("\\n")
            if re.search(r"- (textbox|combobox|checkbox)", l) and '"' not in l]
print(f"缺少可及名稱的元素：{len(no_label)} 個")
for n in no_label[:5]:
    print("  " + n)
  '''
)
→ 約 500 B 進 Context，涵蓋完整的 56 KB snapshot

17.6 階段四：Backend（後端）

開發者的任務：驗證 API 契約與實際實作是否一致。

ctx_execute("javascript", `
const BASE = 'http://localhost:8080';
const token = process.env.TEST_JWT;   // 憑證透傳，不進 Context

const cases = [
  { name: '建立投保申請', method: 'POST', path: '/api/v1/applications',
    body: { productCode: 'TRV001', insuredAmount: 1000000 },
    expectStatus: 201, expectFields: ['applicationId', 'status', 'createdAt'] },
  { name: '查詢申請', method: 'GET', path: '/api/v1/applications/TEST001',
    expectStatus: 200, expectFields: ['applicationId', 'status', 'premium'] },
  { name: '未授權存取', method: 'GET', path: '/api/v1/applications/OTHER001',
    expectStatus: 403 },
  { name: '金額超限', method: 'POST', path: '/api/v1/applications',
    body: { productCode: 'TRV001', insuredAmount: 999999999 },
    expectStatus: 400, expectFields: ['type', 'title', 'detail'] }  // RFC 7807
];

const fails = [];
for (const c of cases) {
  const res = await fetch(BASE + c.path, {
    method: c.method,
    headers: { 'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json' },
    body: c.body ? JSON.stringify(c.body) : undefined
  });
  if (res.status !== c.expectStatus) {
    fails.push(\`\${c.name}: 預期 \${c.expectStatus}，實得 \${res.status}\`);
    continue;
  }
  if (c.expectFields) {
    const j = await res.json().catch(() => ({}));
    const miss = c.expectFields.filter(f => !(f in j));
    if (miss.length) fails.push(\`\${c.name}: 回應缺少欄位 \${miss.join(', ')}\`);
  }
}

console.log(\`API 契約測試 \${cases.length} 項，失敗 \${fails.length} 項\`);
fails.forEach(f => console.log('  ✗ ' + f));
if (!fails.length) console.log('  ✓ 全部通過');
`)

關鍵點 [Official]：process.env.TEST_JWT 透過憑證透傳取得，token 本身不會出現在 Context 裡。

17.7 階段五：Database（資料庫）

ctx_execute("shell", `
psql "$DATABASE_URL" -t -A -F'|' -c "
  SELECT table_name, column_name, data_type, is_nullable
  FROM information_schema.columns
  WHERE table_schema = 'public'
  ORDER BY table_name, ordinal_position
" > /tmp/schema.txt

# 在 sandbox 內比對，不把整份 schema 印出來
python3 - <<'EOF'
import collections
tables = collections.defaultdict(list)
for line in open('/tmp/schema.txt'):
    p = line.strip().split('|')
    if len(p) >= 4:
        tables[p[0]].append((p[1], p[2], p[3]))

# 檢查企業規範
issues = []
for t, cols in tables.items():
    names = [c[0] for c in cols]
    if 'created_at' not in names: issues.append(f'{t}: 缺 created_at')
    if 'updated_at' not in names: issues.append(f'{t}: 缺 updated_at')
    for n, dt, null in cols:
        if 'amount' in n or 'premium' in n:
            if dt not in ('numeric', 'decimal'):
                issues.append(f'{t}.{n}: 金額欄位型態為 {dt}，應為 numeric')

print(f'資料表 {len(tables)} 張，欄位 {sum(len(v) for v in tables.values())} 個')
print(f'違反規範 {len(issues)} 項：')
for i in issues[:20]: print('  ' + i)
EOF
`)

[Enterprise Recommendation] 金融業的「金額一律用 numeric / BigDecimal」這類規範，非常適合寫成這種腳本檢查。把規範程式化，就能進 CI。

17.8 階段六至八：Test / Security / Deployment

這三個階段分別在 21.1、21.2、20.5 詳述。

17.9 本章實務案例：完整的資料流追蹤

以「驗證投保表單」為例，走完整條鏈：

① User Request
   「檢查投保表單的欄位是否符合設計規格，並檢查無障礙」

② AI Agent
   判斷：這需要取得頁面結構 → 會產生大輸出

③ Context Mode（PreToolUse Hook）
   攔截：不允許 browser_snapshot() 不帶 filename

④ Tool
   browser_snapshot(filename: "D:/tmp/apply-form.md")
   → 56 KB 寫入磁碟，Context 只收到 50 B 確認

⑤ Sandbox
   ctx_execute_file 在獨立 subprocess 載入 FILE_CONTENT
   執行比對邏輯

⑥ Index / Search
   （本例為一次性抽取，不需索引。
     若要多次查詢改用 ctx_index(path) → ctx_search）

⑦ Relevant Evidence
   「規格 10 個欄位，頁面 12 個互動元素。
     缺少：受益人。型態不符：投保金額（規格 combobox，實為 textbox）。
     缺少可及名稱：3 個」
   → 約 500 B

⑧ AI Reasoning
   模型根據這 500 B 判斷：
   - 受益人欄位未實作 → 開 issue
   - 投保金額用 textbox → 會有格式驗證風險
   - 3 個無障礙問題 → 違反企業無障礙規範

⑨ Output
   產出 issue 清單與修正建議

全程 Context 消耗：約 600 B。傳統做法：56 KB 以上。

17.10 本章注意事項

1. browser_navigate 會自動回傳 snapshot，要忽略它。
2. 法規、規格書類文件用 FTS5 檢索效果好，因為要精確引用。
3. 憑證用環境變數透傳，不要寫在腳本裡（會進 Context）。
4. 企業規範可以程式化，寫成腳本後能重複使用並進 CI。
5. 前端驗證的腳本要存進 repo，變成團隊資產。

17.11 本章檢查清單

• 我知道 Web 開發八個階段各自該用什麼工具
• 前端檢查一律先存檔再分析
• API 測試的憑證用環境變數，不寫在程式碼裡
• 資料庫規範已寫成可執行的檢查腳本
• 常用的分析腳本已存進 repo

第 18 章 Legacy System 逆向工程

18.1 完整案例 B：從 Legacy 系統產生系統規格

專案設定：某銀行的「放款管理系統」，2008 年建置，原始團隊已全部離職

• 前端：VB.NET WinForms（約 380 個 Form）
• 後端：C# .NET Framework 4.0（約 1,200 個類別）
• 資料庫：SQL Server，約 260 張表、180 個 Stored Procedure
• 批次：Windows 排程 + BAT 檔，約 45 支
• 整合：FTP 檔案交換、IBM MQ、3 支 WebService
• 文件：只有一份 2011 年的操作手冊

任務：產出系統架構圖、功能清單、資料流、需求規格書，作為重構專案的基礎。

18.2 為什麼「Read all source code」行不通

1,200 個 C# 類別 × 平均 300 行 × 平均 40 字元
≈ 14,400,000 字元 ≈ 3,600,000 tokens

即使是 1M context window 的模型，也裝不下。
而且就算裝得下，成本與推理品質都不可接受。

18.3 五階段逆向工程流程

flowchart TD
    Start["Legacy 系統<br/>VB.NET + C# + SP + Batch<br/>無文件"]

    P1["【階段 1】盤點<br/>不讀內容，只統計"]
    P2["【階段 2】索引<br/>設定檔 / SQL / 介面定義"]
    P3["【階段 3】搜尋<br/>依主題查詢，不逐檔讀"]
    P4["【階段 4】程式化分析<br/>呼叫關係 / 資料表矩陣 / 死碼"]
    P5["【階段 5】產出<br/>架構圖 / 功能清單 / 規格書"]

    Start --> P1 --> P2 --> P3 --> P4 --> P5

    P1 -.-> T1["ctx_batch_execute<br/>檔案數 / 行數分布<br/>進入點 / 設定檔 / 外部依賴"]
    P2 -.-> T2["ctx_index(path)<br/>source 分類標籤"]
    P3 -.-> T3["ctx_search(queries[])<br/>交易邊界 / 連線 / 排程"]
    P4 -.-> T4["ctx_execute<br/>正則分析 + 圖論"]
    P5 -.-> T5["AI Reasoning<br/>基於「結論」而非原始碼"]

    P5 --> Out["系統規格書<br/>重構專案的基礎"]

    Note["⚠️ 只有在需要引用具體實作細節時<br/>才讀取特定檔案的特定區段"]
    P5 -.-> Note

    style P1 fill:#d1ecf1,stroke:#0dcaf0
    style P4 fill:#d4edda,stroke:#28a745
    style Note fill:#fff3cd,stroke:#ffc107

18.4 階段一：盤點（不讀內容）

ctx_batch_execute([
  {
    language: "shell",
    intent: "檔案結構盤點",
    code: `
echo "=== 檔案類型分布 ==="
find . -type f \\( -name '*.cs' -o -name '*.vb' -o -name '*.sql' -o -name '*.bat' \\
     -o -name '*.config' -o -name '*.asmx' \\) | sed 's/.*\\.//' | sort | uniq -c | sort -rn

echo "=== 程式碼規模 ==="
find . -name '*.cs' -o -name '*.vb' | xargs wc -l 2>/dev/null | tail -1

echo "=== 最大的 15 個檔案（複雜度熱點）==="
find . -name '*.cs' -o -name '*.vb' | xargs wc -l 2>/dev/null | sort -rn | head -16
`
  },
  {
    language: "shell",
    intent: "找出系統進入點",
    code: `
echo "=== WinForms 進入點 ==="
grep -rl "Inherits System.Windows.Forms.Form\\|: Form\\b" --include='*.vb' --include='*.cs' . | wc -l

echo "=== WebService ==="
find . -name '*.asmx' -o -name '*.svc' | head -20

echo "=== 批次進入點 ==="
find . -name '*.bat' -o -name '*.cmd' | head -50
`
  },
  {
    language: "shell",
    intent: "找出外部系統整合點",
    code: `
echo "=== 資料庫連線字串位置 ==="
grep -rln "Data Source=\\|Initial Catalog=\\|connectionString" --include='*.config' . | head -20

echo "=== FTP 使用 ==="
grep -rn "FtpWebRequest\\|ftp://" --include='*.cs' --include='*.vb' . | wc -l
grep -rho "ftp://[^\\"' ]*" --include='*.cs' --include='*.vb' --include='*.config' . | sort -u | head -10

echo "=== MQ 使用 ==="
grep -rn "MQQueue\\|MQQueueManager\\|IBM.WMQ" --include='*.cs' --include='*.vb' . | wc -l

echo "=== WebService 呼叫 ==="
grep -rho "http://[^\\"' ]*asmx\\|https://[^\\"' ]*asmx" . | sort -u | head -10
`
  },
  {
    language: "shell",
    intent: "資料庫物件盤點",
    code: `
echo "=== Stored Procedure 數量 ==="
grep -rl "CREATE PROCEDURE\\|CREATE PROC" --include='*.sql' . | wc -l

echo "=== 最複雜的 10 個 SP ==="
for f in $(grep -rl "CREATE PROC" --include='*.sql' .); do
  echo "$(wc -l < "$f") $f"
done | sort -rn | head -10
`
  }
], concurrency: 4)

產出（約 3 KB 進 Context）：

檔案類型分布：cs 1,204 / vb 382 / sql 186 / bat 45 / config 23
程式碼規模：約 41 萬行
最大的檔案：LoanCalculator.cs (8,432 行) ← 重構重點
WinForms 進入點：378 個
WebService：3 個
批次：45 支
DB 連線字串：分散在 7 個 config
FTP：14 處，3 個外部主機
MQ：8 處
SP：186 個，最大的 ApplyLoanApproval.sql (2,109 行)

這 3 KB 已經足以讓 SA 建立系統的整體輪廓。

18.5 階段二：索引

ctx_index(path: "./config",        source: "legacy:config")
ctx_index(path: "./database/sp",   source: "legacy:storedproc")
ctx_index(path: "./interfaces",    source: "legacy:interface")
ctx_index(path: "./docs",          source: "legacy:doc")      // 那份 2011 年手冊

[Enterprise Recommendation] 索引的優先順序：設定檔 > SQL > 介面定義 > 文件 > 原始碼。

理由：設定檔密度最高（一行就是一個外部依賴），原始碼密度最低（大量樣板程式碼）。不要一開始就索引全部原始碼。

18.6 階段三：針對性搜尋

ctx_search(
  queries: ["transaction commit rollback isolation",
            "connection timeout pool size",
            "schedule cron daily batch",
            "encrypt decrypt key"],
  source: "legacy"
)

查到什麼（約 4 KB）：

- 交易邊界：多數 SP 內部自行 BEGIN TRAN，但有 12 支沒有 ROLLBACK 處理
- 連線設定：Connection Timeout=15，Max Pool Size 未設定（使用預設 100）
- 排程：有 45 支批次，其中 8 支在 02:00 同時啟動 ← 資源競爭風險
- 加密：使用 TripleDES，金鑰硬編碼在 CryptoHelper.cs ← 資安高風險

最後一項是重大發現，而且是在沒讀任何原始碼的情況下找到的。

18.7 階段四：程式化分析

分析 1：資料表使用矩陣

ctx_execute("python", `
import os, re, collections

table_by_module = collections.defaultdict(set)
tables_all = collections.Counter()

sql_pat = re.compile(
    r"\\b(?:FROM|JOIN|INTO|UPDATE|DELETE\\s+FROM)\\s+\\[?(\\w+)\\]?",
    re.I)

for root, _, files in os.walk("."):
    module = root.split(os.sep)[1] if os.sep in root else "root"
    for f in files:
        if not f.endswith((".cs", ".vb", ".sql")):
            continue
        try:
            src = open(os.path.join(root, f), encoding="utf-8", errors="ignore").read()
        except Exception:
            continue
        for t in sql_pat.findall(src):
            if t.lower() in ("select", "where", "set", "values"):
                continue
            table_by_module[module].add(t)
            tables_all[t] += 1

print(f"模組數 {len(table_by_module)}，資料表 {len(tables_all)}")
print("\\n被最多模組共用的表（重構時的耦合點）：")
shared = collections.Counter()
for m, ts in table_by_module.items():
    for t in ts:
        shared[t] += 1
for t, c in shared.most_common(15):
    print(f"  {t}: 被 {c} 個模組使用（共 {tables_all[t]} 處）")

print("\\n只被單一模組使用的表（可安全切分）：")
solo = [t for t, c in shared.items() if c == 1]
print(f"  共 {len(solo)} 張：{', '.join(sorted(solo)[:20])}")
`)

分析 2：死碼偵測

ctx_execute("python", `
import os, re, collections

defined = {}      # method name -> file
called = collections.Counter()

def_pat  = re.compile(r"(?:public|private|protected|internal)\\s+(?:static\\s+)?[\\w<>\\[\\]]+\\s+(\\w+)\\s*\\(")
call_pat = re.compile(r"\\b(\\w+)\\s*\\(")

files = []
for root, _, fs in os.walk("."):
    for f in fs:
        if f.endswith((".cs", ".vb")):
            files.append(os.path.join(root, f))

for p in files:
    src = open(p, encoding="utf-8", errors="ignore").read()
    for m in def_pat.findall(src):
        defined[m] = p
    for m in call_pat.findall(src):
        called[m] += 1

# 定義了但只被「定義處」出現一次的 = 可能是死碼
dead = [m for m, p in defined.items() if called[m] <= 1 and not m.startswith(("Form_", "btn", "On"))]
print(f"方法定義 {len(defined)} 個，疑似死碼 {len(dead)} 個（約 {len(dead)*100//max(len(defined),1)}%）")
print("樣本（前 20 個，含所在檔案）：")
for m in sorted(dead)[:20]:
    print(f"  {m}  ←  {defined[m]}")
`)

[AI Analysis] 注意這個腳本的限制：正則比對會有誤判（反射呼叫、事件繫結、XAML 繫結都抓不到）。它的用途是「縮小範圍」，不是「下定論」。產出的死碼清單仍需人工複核。

這一點要寫進報告，避免讀者誤以為是精確結果。

18.8 階段五：產出

到這個階段，Context 裡累積的是：

階段 1 盤點結果        約 3 KB
階段 3 搜尋命中        約 4 KB
階段 4 分析結論        約 5 KB
────────────────────────────
合計                   約 12 KB

用這 12 KB，AI 可以產出：

• 系統架構圖（模組、外部整合、資料流）
• 功能清單（依 378 個 Form 分類）
• 資料表使用矩陣（重構切分的依據）
• 風險清單（硬編碼金鑰、缺 ROLLBACK 的 SP、排程資源競爭）
• 重構優先順序建議

傳統做法要達到同樣結果，需要讀進 3,600,000 tokens —— 差距 300 倍。

18.9 只有這些時候才讀原始碼

[Enterprise Recommendation] 逆向工程的原則是「先廣後深」。以下情況才讀具體檔案：