diff --git a/README.md b/README.md index 383d08c..7676dd8 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # Token Optimization Guide for GitHub Copilot +[English](README.md) | [繁體中文（台灣）](README.zh-TW.md) + > [!IMPORTANT] > **This is not official GitHub or Microsoft guidance.** This guide is a community resource born from real-world field experience — patterns observed, techniques tested, and lessons learned by practitioners adopting AI for development purposes. It reflects industry backspark: practical knowledge gathered from the ground up, not top-down product documentation. Use it to inform about optimization strategies, and adapt what works for the context of your customer. Official guidance lives at [docs.github.com/copilot](https://docs.github.com/copilot). diff --git a/README.zh-TW.md b/README.zh-TW.md new file mode 100644 index 0000000..2014f07 --- /dev/null +++ b/README.zh-TW.md @@ -0,0 +1,137 @@ +# GitHub Copilot 的 Token 最佳化指南 + +[English](README.md) | [繁體中文（台灣）](README.zh-TW.md) + +> [!IMPORTANT] +> **這不是 GitHub 或 Microsoft 的官方指引。** 這份指南是來自實務現場經驗的社群資源，整理了導入 AI 進行開發時，從實際觀察到的模式、驗證過的方法，以及第一線累積的教訓。它代表的是產業現場自下而上的實務知識，而不是自上而下的產品文件。你可以用它來思考最佳化策略，並依照客戶的情境調整適用做法。官方指引請見 [docs.github.com/copilot](https://docs.github.com/copilot)。 + +> 這是一份以資料為基礎、重視實務的指南，協助你在維持程式碼品質的同時降低 token 消耗。 +> 涵蓋 Chat、Inline 與 Coding Agent 工作流程。 + +--- + +## 快速開始：現在就該做的 12 件事 + +> **2026 年 6 月 1 日，按使用量計費（UBB）已正式上線。** GitHub Copilot 現在不再以請求次數計費，而是改為針對實際 token 用量（input + output + cached）計費，並從共用的 AI 點數池中扣抵（Business 每席次 30 美元、Enterprise 每席次 70 美元）。本指南中的每一項技巧，都可以直接轉換成點數節省，而且在新的計費模式下，對快取友善的使用習慣會比以前更重要。客戶治理與限制建議請參考 [Enterprise Governance](docs/12-enterprise-governance.zh-TW.md)，模型成本建議請參考 [Model Selection & Pricing](docs/11-models-and-pricing.zh-TW.md)。 + +> **輸出 token 的成本遠高於輸入 token。** 這是本指南最重要的定價事實。Anthropic 公開的定價可以很清楚地說明這種不對稱性（每百萬 token 的輸入／輸出價格分別為：Haiku 1 美元／5 美元、Sonnet 3 美元／15 美元、Opus 5 美元／25 美元）。Copilot 目前尚未公開各模型的 UBB 精確定價表，但在 UBB 模式下，冗長輸出仍然會顯得特別昂貴。大多數輸入 token 其實來自檔案內容、歷史對話與工具 schema，而不是你手動輸入的提示詞。你打的 prompt 只占整體輸入的一小部分。先從控制輸出開始，再處理結構性的輸入最佳化。 + +如果你沒時間讀完整份指南，今天先做這些事，就能開始降低 token 用量： + +| # | 行動 | 主要效果 | 設定時間 | +|---|------|----------|----------| +| 1 | **要求只輸出程式碼**：在 `copilot-instructions.md` 加上 `Code only, no explanation.`。這是每個 token 最值得投資的做法：輸出成本是輸入的 5 倍，這一條能在所有程式任務中永久減少 40-70% 的輸出 | 縮短回應長度 | 0 分鐘 | +| 2 | **預設限制輸出格式**：在 `copilot-instructions.md` 加上 `Bullets over paragraphs. No explanations unless asked.` | 讓回答保持精簡 | 0 分鐘 | +| 3 | **縮小常駐上下文**：壓縮 `copilot-instructions.md`，並把 `AGENTS.md` 修剪到只留下地雷項。這兩個檔案中的每一個 token，都會在每次互動（以及每一步 agent 執行）中被計費。刪掉填充內容、刪掉 agent 看程式碼就能自己發現的資訊、刪掉由 LLM 產生的 `/init` 樣板 | 降低常駐輸入／上下文 | 15 分鐘 | +| 4 | **預設使用 Auto 模型選擇**：把 Auto 當作基準，因為它會從支援的 Auto 模型池中自動挑選，並提供付費方案折扣。只有在任務明確值得時，再手動鎖定較高成本的模型。詳見 [Model Selection & Pricing](docs/11-models-and-pricing.zh-TW.md) | 降低符合條件用量的計費單價 | 0 分鐘 | +| 5 | **簡單問題用 Ask 模式**：多步驟工作再交給 Agent Mode | 避免 agent 額外開銷 | 0 分鐘（只要選對模式） | +| 6 | **用 `applyTo:` 路徑限制上下文**：把一份很大的 instructions 檔拆成數個小檔，只在相關情境載入 | 降低常駐輸入／上下文 | 15 分鐘 | +| 7 | **提示詞要精準**：像是「幫 `getUser()` 加上 null 檢查」，而不是「你可以幫我看看這裡，順便加一些錯誤處理嗎？」注意：你自己輸入的 prompt 只占總輸入的一小部分；精準對品質的幫助，大於它對原始 token 節省的幫助 | 提升任務聚焦程度 | 0 分鐘 | +| 8 | **依目標模型重調提示詞**：不同 provider 的 prompting 指南會隨模型與版本變動。把官方指南網址貼進 Copilot，請它依你實際使用的模型，調整 `.github/copilot-instructions.md`、agent profiles 或 app prompts | 減少返工 | 每次模型變更約 10 分鐘 | +| 9 | **稽核你的 MCP servers**：停用沒在用的 server；每個 server 都可能讓每一步 agent 額外增加約 100-500 個 token | 移除工具／schema 額外負擔 | 5 分鐘 | +| 10 | **先把富格式檔案轉成 Markdown 再交給 AI**：`.docx`、`.pdf`、`.pptx`、`.xlsx`、HTML、圖片、音訊、影片與 ZIP 都帶有格式稅。[Marc Bara 的文章](https://medium.com/@marc.bara.iniesta/your-docx-is-wasting-33-of-your-ai-budget-86a3d229d042) 已示範這類成本；在 chat、agent 或 RAG 匯入前，先用 [Microsoft MarkItDown](https://github.com/microsoft/markitdown) 轉成乾淨的 Markdown | 降低雜訊輸入／上下文 | 5 分鐘 | +| 11 | **每週執行 `/chronicle improve`**（**僅限 Copilot CLI**，實驗性功能）：這個 slash command 只能在互動式 Copilot CLI 工作階段中使用，並不是一般 Copilot Chat 功能。它會找出你 CLI 工作階段歷史中反覆出現的誤解，並產生自訂指令，讓同樣的誤判不再持續浪費 token | 降低重複返工 | 每次 2 分鐘 | +| 12 | **長工具鏈任務可考慮 CodeAct**（**僅限 Copilot CLI**，可選的外部外掛）：[`copilot-codeact-plugin`](https://github.com/jsturtevant/copilot-codeact-plugin) 可以把多步驟工具鏈收斂成一次沙箱執行，減少重複重播 system prompt、先前訊息與工具定義的次數 | 降低工具迴圈重播成本 | 10-15 分鐘 | + +**如果你是從企業治理或客戶治理的角度來看，而不是個人設定最佳化？** 請直接從 [Enterprise Governance](docs/12-enterprise-governance.zh-TW.md) 開始。那一章涵蓋 AI 點數預算、針對個別使用者收緊權限、模型存取政策、組織層級指示，以及何時值得為了治理需求拆分成不同組織。 + +*上表數字僅針對各列所述機制，不可直接相加，也不代表總體帳單降幅。* + +輸出控制（#1、#2）會立刻生效，而且會持續累積回報：設定一次，每次呼叫都省。結構性的輸入控制（#3、#6）會在每一次互動中持續累積效益。模型路由（#4、#5）會從計費層級直接降低成本。針對模型調整提示詞（#8）則透過提升首次回應品質來減少浪費。MCP 稽核（#9）可以直接砍掉每次 agent 任務中那些隱藏的 token 成本。Markdown 轉換（#10）則能在模型看到內容前，先移除 DOCX／PDF／HTML 的版面與標記雜訊。 + +--- + +## 指南內容 + +### Part 1：為什麼 Token 很重要 + +了解 BPE tokenization、token 為何會影響成本／速度／限制，以及 GitHub Copilot 在底層如何使用 token。 + +→ **[閱讀 Part 1](docs/01-why-tokens-matter.zh-TW.md)** + +--- + +### Part 2：各種技巧 + +#### [2.1 Prompt Compression](docs/02-prompt-compression.zh-TW.md) + +原始人式簡寫、強度分級（lite／full／ultra）、結構化格式、縮寫，以及以程式碼為中心的 prompting。可節省 30-50% 的輸入 token；搭配輸出控制（2.4）時，也能一起減少輸出。 + +#### [2.2 Language Comparison](docs/03-language-comparison.zh-TW.md) + +以資料為基礎的比較：在這些範例裡，英文是最省 token 的語言。CJK 成本高出 1.7-2.4 倍。內含 8 種語言的 tokenization 表格。 + +#### [2.3 Context Management](docs/04-context-management.zh-TW.md) + +壓縮 system instructions、壓縮記憶檔、用 `applyTo` 限定上下文、關閉未使用的編輯器分頁、在 AI 工作前先把非純文字檔轉成 Markdown、設定 Content Exclusion（Business／Enterprise 管理員可用），以及在需要時開新對話。重點是控制實際送進模型的內容。 + +#### [2.4 Output Control](docs/05-output-control.zh-TW.md) + +「`Code only, no explanation.`」限制回應格式，並把精簡輸出設成專案預設。 + +#### [2.5 Workflow Optimization](docs/06-workflow-optimization.zh-TW.md) + +精簡 commit 訊息、單行 PR review、Ask 與 Agent mode 的選擇、針對模型調整提示詞，以及什麼情況下**不該**壓縮。 + +#### [2.6 The Always-On Context Problem](docs/07-agents-md-problem.zh-TW.md) + +關於 LLM 產生的上下文檔案的研究顯示，這些檔案常常在增加 token 成本的同時，還會降低 agent 的正確性。這個教訓同樣適用於 `AGENTS.md` 與 `.github/copilot-instructions.md`：兩者雖然是不同慣例（檔名不同、歷史來源也不同），但在今天的 Copilot 裡，它們都會成為常駐上下文。無論你的 repo 用的是哪一種檔案，都應該採用「只留地雷項」的原則。把上下文檔當成 bug tracker，不要當成 wiki。 + +#### [2.7 MCP & Tool Costs](docs/08-mcp-tool-costs.zh-TW.md) + +隱性的 token 稅：每個 MCP tool 都會讓每一步 agent 額外增加 100-500 個 token。15 個 servers × 15 個步驟 = 26.5 萬個額外 token。內含稽核指南。 + +--- + +### Part 3：比較與資料 + +提示詞的正面對決比較、各語言 tokenization 表格、完整的技巧矩陣（40+ 種技巧），以及搭配效益遞減曲線的品質影響評估。 + +→ **[閱讀 Part 3](docs/09-comparisons-data.zh-TW.md)** + +--- + +### Part 4：實際設定 + +逐步說明：如何設定 Copilot、最佳化 Coding Agent、設定 agent mode，以及建立使用習慣。包含 VS Code 設定、決策框架與 4 週導入計畫。 + +→ **[閱讀 Part 4](docs/10-practical-setup.zh-TW.md)** + +--- + +### Part 4.2：Model Selection & Pricing + +專門說明模型、PRU 時代的倍率歷史、目前的 Auto 使用建議、不同方案可用性，以及在 Copilot 尚未公開各模型精確 UBB 費率表的情況下，供應商輸入／輸出 token 定價應如何納入考量。內含 GitHub Docs 官方頁面的連結，涵蓋 Auto 模型選擇、計費，以及方案／模型可用性。 + +→ **[閱讀 Part 4.2](docs/11-models-and-pricing.zh-TW.md)** + +--- + +### Part 4.3：Enterprise Governance + +專為面向客戶的管理情境而寫的章節：涵蓋按使用量計費的防護措施、AI 點數預算、針對個別使用者收緊權限、模型存取政策、組織層級指示，以及何時值得承擔額外負擔、拆分成不同組織。 + +→ **[閱讀 Part 4.3](docs/12-enterprise-governance.zh-TW.md)** + +--- + +如果你需要 glossary、quick terms、tools，或核心外部連結，請前往 [Guide Home](docs/index.zh-TW.md)。 + +--- + +## 影響最大的技巧 + +依成本影響排序。先看輸出，因為它每個 token 的成本是輸入的 5 倍。 + +1. **控制輸出**：`Code only, no explanation`，再加上 `copilot-instructions.md` 裡的精簡預設。程式任務可省 40-70% 的輸出，整體互動可省 30-60%。一條指令，永久生效。 +2. **縮小常駐上下文**（`copilot-instructions.md` + `AGENTS.md`）：壓縮填充內容、只留地雷項、刪掉 LLM 產生的樣板。這會在每次互動與每一步 agent 執行中持續累積效果；agent 任務可降低 20-23%，而且正確性更好。 +3. **簡單問題使用 Ask Mode**：避免 Agent 額外開銷，可節省 60-90%。 +4. **稽核 MCP servers**：停用沒在用的 servers，每次 agent 任務可省下 5 千到 19 萬個 token。 +5. **使用 Auto 模型選擇**：以更低成本的預設路由加上付費方案折扣達成節省，幾乎零成本導入。 +6. **先把富格式檔案轉成 Markdown**：避免在 chat、agent 與 RAG 工作流中為 Word／PDF／HTML 的版面雜訊付費。 +7. **依目標模型重調提示詞**：提升第一次輸出的品質，減少來回澄清。 +8. **精準提示詞**：可影響使用者提示詞輸入 token 的 20-40%；對品質的幫助通常比對原始節省更重要。 + +--- + +*這是一份會持續更新的文件。隨著 tokenizer 技術演進、模型能力改變，以及新技巧出現，這份指南也會持續更新。請查看此 repository 以取得最新版本。* diff --git a/docs/01-why-tokens-matter.zh-TW.md b/docs/01-why-tokens-matter.zh-TW.md new file mode 100644 index 0000000..f77f8d5 --- /dev/null +++ b/docs/01-why-tokens-matter.zh-TW.md @@ -0,0 +1,91 @@ +# Part 1：為什麼 Token 很重要 + +[English](01-why-tokens-matter.md) | [繁體中文（台灣）](01-why-tokens-matter.zh-TW.md) + +[← 返回指南](index.zh-TW.md) + +--- + +## 1.1 什麼是 Token？ + +Token 是大型語言模型讀寫時使用的基本單位。它不是單字，也不是字元，而是由 Byte-Pair Encoding（BPE）切分出來的**子詞**。 + +### BPE 如何運作 + +1. 從原始位元組開始（共 256 種可能值） +2. 找出訓練資料中最常出現的位元組配對 +3. 把這些配對合併成新的 token +4. 持續重複，直到詞彙表規模達到約 10 萬個 token + +結果就是：常見英文單字通常會變成單一 token，而較少見或較長的詞則會被拆成多段。 + +### 範例 + +| 文字 | Token | 數量 | +|------|--------|------| +| `hello` | `hello` | 1 | +| `unhappiness` | `un` + `happiness` | 2-3 | +| `authentication` | `authentication` | 2-3 | +| `I met a huge dog` | `I` `met` `a` `huge` `dog` | 5 | +| `Sure, I'd be happy to help you with that!` | （每個詞與標點） | 約 10 | + +最後這個例子很關鍵：10 個 token，幾乎沒有資訊量。這就是 token 最佳化的核心洞察。 + +**關鍵事實：** 在 Claude 3 tokenizer 中，最常見的 10,000 個英文詞裡，有 8,311 個會被切成單一 token。常見字詞很便宜；填充詞雖然也常只要 1 個 token，但幾乎沒有價值。 + +## 1.2 為什麼你該在意 + +你送出或收到的每一個 token 都有成本： + +| 面向 | 影響 | +|------|------| +| **成本** | Token 就是錢。API 定價以 token 為基礎，GitHub Copilot 的使用限制也和 token 有關。**最重要的不對稱點是：輸出 token 每個 token 的成本約是輸入的 5 倍**（Anthropic：每百萬 token 的輸入／輸出價格為 Haiku 1／5 美元、Sonnet 3／15 美元、Opus 5／25 美元）。Copilot 的 UBB 也採用相同桶位概念，因此每一句你其實不需要的回覆，都可能比你 prompt 裡同一句話貴上 5 倍。輸出控制是本指南中每個 token ROI 最高的技巧。 | +| **速率限制** | 每次請求用越少 token，在觸發上限前能發出的請求就越多。 | +| **Context window** | 輸入（prompt + context）與輸出（回應）共享有限空間。輸入浪費越多，輸出可用空間就越少。 | +| **速度** | 輸入 token 越少，第一個 token 出現得越快，回覆真的會更快。 | +| **計費** | 自 2026 年 6 月 1 日起，GitHub Copilot 針對用量採用 **usage-based billing（UBB）**。每次互動會落在三種計費桶：輸入 token（prompt + context + history）、輸出 token（回應內容）、以及快取 token（重複利用的 context，通常以輸入費率約 10% 計費）。成本 =（輸入 × 輸入費率）+（快取 × 快取費率）+（輸出 × 輸出費率）。Business 與 Enterprise 席次則含有組織共用的 AI credits（CB 每席次 30 美元、CE 每席次 70 美元）。程式碼補全（code completion）維持不計入用量。 | + +**複利效應：** 你的輸入 token 大多不是來自你打的字，而是來自檔案內容、對話歷史、system prompt 與 MCP 工具 schema。你自己輸入的 prompt 常常只有 5–100 個 token，但 agent mode 的總輸入可能到 5,000–50,000+。最大的輸入槓桿通常是結構性調整，例如 instruction 檔大小、分頁管理與 context 範圍控制。每 token 成本影響最大的則是輸出：因為價格高 5 倍，而且可以靠 `copilot-instructions.md` 裡一行設定直接控制。 + +## 1.3 GitHub Copilot 如何使用 Token + +了解 Copilot 背後實際做了什麼，才能知道該怎麼最佳化： + +```text +┌─────────────────────────────────────────────────┐ +│ Context Window │ +│ │ +│ ┌──────────────────┐ ┌─────────────────────┐ │ +│ │ INPUT TOKENS │ │ OUTPUT TOKENS │ │ +│ │ │ │ │ │ +│ │ System prompt │ │ 你收到的回應 │ │ +│ │ + copilot- │ │ │ │ +│ │ instructions │ │ │ │ +│ │ + file context │ │ │ │ +│ │ + conversation │ │ │ │ +│ │ history │ │ │ │ +│ │ + 你的 prompt │ │ │ │ +│ └──────────────────┘ └─────────────────────┘ │ +└─────────────────────────────────────────────────┘ +``` + +- **System prompt：** Copilot 自身的內建指示（你無法控制） +- **`copilot-instructions.md`：** 專案層級指示，**每次互動都會載入** +- **File context：** 你用 `#file` 指到的檔案，以及 Copilot 自動帶入的內容（開啟分頁、imports、附近檔案） +- **Conversation history：** 目前對話中的所有先前訊息 +- **你的 prompt：** 你實際輸入的內容 + +**隱性負擔：** Copilot 還會加入你看不到的 context，例如 repo 結構、檔案內容與 import graph。這就是為什麼你打了 20 個字，實際輸入卻可能消耗 2,000+ token。 + +**Coding Agent 的乘數效應：** GitHub Coding Agent 會執行多步驟工作階段。每一步都要讀檔、判斷、寫程式，因此從 issue 到 PR 的一次工作流程，常常就會吃掉數萬個 token。任何節省都會在這些步驟中持續放大。 + +## 1.4 這份指南適合誰 + +- **GitHub Copilot Chat 使用者**：主要讀者，大多數技巧都適用 +- **GitHub Copilot Inline／Edits 使用者**：部分技巧適用（prompt 控制較有限） +- **GitHub Coding Agent 使用者**：高價值族群，因為長工作階段會把節省放大 +- **任何重視效率的人**：即使你沒有碰到限制，更快回應與更乾淨的互動仍然值得 + +--- + +**下一章：** [Prompt Compression →](02-prompt-compression.zh-TW.md) diff --git a/docs/02-prompt-compression.zh-TW.md b/docs/02-prompt-compression.zh-TW.md new file mode 100644 index 0000000..21d888f --- /dev/null +++ b/docs/02-prompt-compression.zh-TW.md @@ -0,0 +1,218 @@ +# 2.1 Prompt Compression：用更少的 Token 表達同一件事 + +[English](02-prompt-compression.md) | [繁體中文（台灣）](02-prompt-compression.zh-TW.md) + +[← 返回指南](index.zh-TW.md) + +--- + +## 2.1.1 原始人式簡寫 + +最有效的 token 最佳化技巧，就是把不增加資訊的語言骨架拿掉。 + +**該刪掉的：** + +- 冠詞：a、an、the +- 填充詞：just、really、basically、actually、simply +- 客套話："Sure, I'd be happy to help!"、"Of course!"、"Certainly!" +- 模糊保留："I think maybe"、"it's probably"、"you might want to consider" + +**該保留的：** + +- 所有技術名詞，要精確 +- 程式碼，不要改動 +- 明確性，要更精準，不是更模糊 + +**前後對照：** + +| 風格 | Prompt | 約略輸入 Token | +|------|--------|----------------| +| 冗長 | "Hey, could you please help me refactor this function? I think it might have some issues with how it handles the authentication, and I'd really like it to be more efficient. Thanks!" | 約 40 | +| 原始人式 | "Refactor function. Fix auth handling. Make efficient." | 約 10 | + +在這個刻意塞滿填充詞的例子裡可節省 **75%**，而且模型對兩種寫法的理解一樣好。對本來就寫得相對精簡的開發者 prompt，常見節省幅度通常是 **30–50%**。 + +**常見模式：** `[物件] [動作] [原因]。[下一步]` + +更多例子： + +| 冗長版 | 原始人版 | 節省 | +|---|---|---| +| "Can you explain what this error message means and how I should fix it?" | "Explain error. How fix." | 約 69% | +| "I'd like you to add comprehensive error handling to this API endpoint, including validation of the request body." | "Add error handling to endpoint. Validate request body." | 約 55% | +| "Could you please review this pull request and let me know if there are any issues?" | "Review PR. Flag issues." | 約 71% | + +## 2.1.2 壓縮強度分級 + +不是每個情境都適合同一種壓縮程度。這份指南採用三種英文強度： + +### Lite：專業但精簡 + +刪掉填充詞與模糊保留，但保留冠詞與完整句子。 + +```text +"Your component re-renders because you create a new object reference +each render. Wrap it in useMemo." +``` + +約 20 tokens。適合：對外文件、新人上手文件、需要完整清晰表達的情境。 + +### Full：經典原始人模式（預設） + +拿掉冠詞，允許片語化，用更短的同義詞。 + +```text +"New object ref each render. Inline object prop = new ref = re-render. +Wrap in useMemo." +``` + +約 18 tokens。適合：日常開發、多數 Copilot 互動。 + +### Ultra：最大壓縮 + +常見術語直接縮寫，刪掉連接詞，用箭頭表示因果。 + +```text +"Inline obj prop → new ref → re-render. useMemo." +``` + +約 10 tokens。適合：高頻互動、你對領域非常熟時。 + +**估計各等級的節省幅度：** + +> **輸入 vs 輸出：** 輸入節省來自把 prompt 寫精簡；輸出節省則來自在 system instructions（例如 `copilot-instructions.md`）設定精簡輸出。把 prompt 寫精簡，並不會自動讓模型用精簡方式回答，兩者都要設。 + +| 等級 | 輸入節省 | 輸出節省† | 品質影響 | +|------|----------|-----------|----------| +| Lite | 15-25% | 15-25% | 幾乎無 | +| Full | 30-50% | 40-55% | 可忽略 | +| Ultra | 55-70% | 55-70% | 複雜指令可能變模糊 | + +†輸出節省要搭配 system-level 的精簡輸出設定，見 [Output Control](05-output-control.zh-TW.md)。 + +## 2.1.3 用結構取代散文 + +條列與 key-value 幾乎總是比段落省 token。 + +**散文版：** + +```text +I need you to create a REST API endpoint that accepts POST requests at /api/users. +It should validate that the request body contains a name field (string, required) +and an email field (string, required, must be valid email format). If validation +fails, return a 400 status with error details. On success, save to the database +and return 201 with the created user object. +``` + +**結構化版：** + +```text +POST /api/users +Validate: +- name: string, required +- email: string, required, valid format +400 on validation fail (include errors) +201 on success (return created user) +Save to DB +``` + +**可節省約 36%**，而且結構化版本可以說更清楚，因為它逼你把各項需求分開列。 + +## 2.1.4 縮寫與簡寫 + +模型通常能很好理解這些常見縮寫： + +| 縮寫 | 意義 | +|------|------| +| DB | Database | +| auth | Authentication/authorization | +| config | Configuration | +| req/res | Request/response | +| fn | Function | +| impl | Implementation | +| env | Environment | +| deps | Dependencies | +| repo | Repository | +| PR | Pull request | +| e2e | End-to-end | + +**有幫助的情境：** 長指令裡反覆出現的術語。 +**會出問題的情境：** 模型沒看過的專案內部縮寫。 + +## 2.1.5 以程式碼為中心的 Prompt + +有時候，程式碼比自然語言更省 token。 + +**自然語言：** + +```text +Create a function that takes a list of numbers, filters out the negative ones, +doubles each remaining number, and returns the sum. +``` + +**偽碼：** + +```text +fn(nums) → filter(>0) → map(*2) → sum +``` + +**型別簽章：** + +```python +def process(nums: list[int]) -> int: + # filter positive, double, sum +``` + +**「像 X，但改成 Y」：** + +```text +Like getUserById but for emails. Return 404 if missing. +``` + +這幾種方式通常都能讓模型理解，但後三種更省。 + +## 2.1.6 重質不重量：縮小範圍，不要一直加規則 + +模型做錯時，常見直覺是再加更多規則。這幾乎都會更貴，通常也更差。 + +應該做的是：**提高 context 品質，而不是增加數量。** + +| 症狀 | 錯誤作法 | 正確作法 | +|------|----------|----------| +| 模型漏掉 edge case | 把這個 edge case 永久加進 always-on instructions | 只在這次 prompt 提到 | +| 模型回覆太冗長 | 用五種不同說法一直要求簡潔 | 直接限制格式，例如「一行回答」 | +| Agent 走偏 | 再加更多全域規範 | 收緊這次 prompt：指定檔案、函式、完成條件 | +| 模型忘了慣例 | 每次都把慣例貼進 prompt | 放進 `applyTo` 範圍化 instruction 檔 | + +小而明確的 prompt，通常也比較不會把 agent 帶進長時間的失焦探索。 + +## 2.1.7 宣告式護欄 + +比起逐步命令模型怎麼做，直接說明輸出必須滿足哪些條件，通常更短、更穩。 + +| 命令式 | 宣告式 | +|---|---| +| "First read the file, then identify all the public functions..." | "All exported functions: JSDoc required." | +| "Make sure that whenever you write a SQL query..." | "SQL: parameterized queries only. No concatenation." | +| "Please write tests for any new code..." | "New code → tests. Cover happy + error paths." | + +宣告式規則也比較容易疊加，不會互相打架。 + +## 2.1.8 把 Instructions 當成程式碼整理 + +兩個原則： + +**1. Minify。** 把所有 filler 拿掉，像壓縮 production JS 一樣壓縮 instructions。 +**2. 結構化重用。** 不要把同一段規則複製到三個 instruction 檔。 + +建議做法： + +- 共用慣例 → 一份 `applyTo: "**/*"` 的共用檔 +- 各層規則 → 用 `applyTo` 做範圍化 +- 工作流特定規則 → 做成按需載入的 note 或 prompt file + +這樣每次互動載入的 context 更小，也更容易維護。 + +--- + +**下一章：** [Language Comparison →](03-language-comparison.zh-TW.md) diff --git a/docs/03-language-comparison.zh-TW.md b/docs/03-language-comparison.zh-TW.md new file mode 100644 index 0000000..259bfd5 --- /dev/null +++ b/docs/03-language-comparison.zh-TW.md @@ -0,0 +1,94 @@ +# 2.2 自然語言選擇：重新檢查 CJK 假設 + +[English](03-language-comparison.md) | [繁體中文（台灣）](03-language-comparison.zh-TW.md) + +[← 返回指南](index.zh-TW.md) + +--- + +## 2.2.1 人類語言的 Token 經濟學 + +有一種常見假設：**「中文或日文字數比較少，所以 prompt 應該比較省 token。」** + +**實際的 token 計數並不支持這個說法。** + +測試句子："I met a huge dog" 及其各語言版本： + +| 語言 | 句子 | 字元數 | Tokens | 相對英文 | +|------|------|--------|--------|----------| +| **英文** | I met a huge dog | 16 | **5** | 1.0x | +| **西班牙文** | Conocí a un perro enorme | 24 | **8** | 1.6x | +| **波蘭文** | Spotkałem ogromnego psa | 23 | **8** | 1.6x | +| **冰島文** | Ég hitti risastóran hund | 24 | **10** | 2.0x | +| **中文** | 我遇見了一隻大狗 | 8 | **11** | 2.2x | +| **日文** | 大きな犬に出会った | 9 | **11** | 2.2x | +| **俄文** | Я встретил огромную собаку | 26 | **14** | 2.8x | +| **希伯來文** | פגשתי כלב ענק | 13 | **16** | 3.2x | + +中文只有 8 個字，但要 11 個 token；英文 16 個字卻只要 5 個 token。 + +## 2.2.2 為什麼會這樣 + +BPE tokenizer 的訓練資料多數以英文為主，因此英文通常有最好的壓縮率： + +1. **常見英文詞通常就是 1 個 token** +2. **CJK 字元大約是每字 1–1.4 個 token**，不像常見誤解那樣是 2–3 個，但依然比英文每字元成本高很多 +3. **非拉丁字母系統**（如西里爾文、希伯來文、阿拉伯文）通常更吃虧 + +## 2.2.3 大樣本資料 + +根據 Capodieci／Castillo 的較大規模研究： + +| 語言 | 相對英文平均 Token 成本 | 每個 Token 對應字元數 | +|------|------------------------|-----------------------| +| English | 1.0x | 4.75 | +| Spanish | 約 1.3-1.6x | 約 3.5 | +| German | 約 1.4-1.6x | 約 3.2 | +| Mandarin Chinese | 約 1.76x | 1.33 | +| Japanese | 約 2.12x | 1.41 | +| Korean | 約 2.36x | 約 1.2 | +| Russian | 約 2.5-2.8x | 約 2.0 | + +## 2.2.4 文言文呢？ + +文言文本身資訊密度很高。現代中文可能要 8 個字，文言文可能只要 4 個字，但 tokenizer 不看資訊密度，只看位元組序列。 + +**例子："Explain database connection pooling"** + +| 模式 | 文字 | 約 Tokens | +|------|------|-----------| +| 英文（full caveman） | "Pool reuse open DB conn. Skip handshake → fast." | 約 12 | +| 文言文 full | "池reuse conn。skip handshake → fast。" | 約 15 | +| 文言文 ultra | "池reuse conn。skip→fast。" | 約 12 | + +最好的情況是和精簡英文打平，最差則更貴。再加上模型對英文的理解通常更穩，因此： + +**結論：** 文言文很有創意，也可能適合教學或示範，但**不建議拿來做真正的 token 最佳化**。 + +## 2.2.5 實務結論 + +1. **Prompt 與 instructions 盡量使用英文** +2. **不要把 prompt 翻成 CJK 語言以為會省 token** +3. **如果你用母語能寫得更短，品質可能更好，但 token 成本通常仍較高** +4. **程式輸出通常仍會維持英文** +5. **對非拉丁腳本，轉寫成拉丁字母有時能省 token** + +### 轉寫效果 + +| 腳本 | 句子 | Tokens | 相對原文 | +|------|------|--------|----------| +| 俄文（西里爾） | Я встретил огромную собаку | 14 | baseline | +| 俄文（轉寫） | Ya vstretil ogromnuyu sobaku | 11 | 便宜約 21% | +| 希伯來文 | פגשתי כלב ענק | 16 | baseline | +| 希伯來文（轉寫） | pgSti klv 3nq | 9 | 便宜約 44% | + +### 核心發現 + +> **英文是 LLM prompt 最省 token 的自然語言。** +> +> CJK 雖然字數少，但每個字通常要約 1–1.4 個 token。 +> 綜合下來，同樣意思的內容常常會比英文多出 1.7–2.4 倍的 token。 + +--- + +**下一章：** [Context Management →](04-context-management.zh-TW.md) diff --git a/docs/04-context-management.zh-TW.md b/docs/04-context-management.zh-TW.md new file mode 100644 index 0000000..54f2780 --- /dev/null +++ b/docs/04-context-management.zh-TW.md @@ -0,0 +1,156 @@ +# 2.3 Context Management：控制真正送進去的內容 + +[English](04-context-management.md) | [繁體中文（台灣）](04-context-management.zh-TW.md) + +[← 返回指南](index.zh-TW.md) + +--- + +## 2.3.1 System Instruction 壓縮 + +`.github/copilot-instructions.md` 會被注入到**每一次 Copilot 互動**。裡面的每個字都會在每次 prompt 中付出 token 成本。 + +> **補充：相關但不同的慣例。** `.github/copilot-instructions.md` 是 GitHub Copilot 原生的 repo 級 instruction 檔；`AGENTS.md` 則是跨工具慣例，Copilot 也會讀。它們不是同一個檔案，但共同點是：都屬於 **always-on context**。如果內容重複，就等於每次互動重複付費。 + +這也是最值得最佳化的檔案之一。假設 instruction 檔有 500 字、約 700 tokens，你每次問問題前就先燒掉 700 tokens。 + +**壓縮前：** + +```text +You should write terse responses like a caveman. Make sure all technical substance +remains exact. Only remove unnecessary filler words. Drop articles and hedging. +Use fragments when appropriate. Keep code unchanged. Use short synonyms where possible. +``` + +**壓縮後：** + +```text +Terse like caveman. Technical substance exact. Only fluff die. +Drop: articles, filler (just/really/basically), pleasantries, hedging. +Fragments OK. Short synonyms. Code unchanged. +``` + +這類調整常能節省超過一半，而且每次互動都會複利生效。 + +## 2.3.2 記憶檔壓縮 + +除了 `copilot-instructions.md`／`AGENTS.md`，很多專案還會累積 `CLAUDE.md`、project notes、coding guidelines、`.cursorrules` 等記憶檔。如果它們會進 context，就要一併計入成本。 + +**原則：** + +- 先合併重複內容，再做壓縮 +- 刪掉冠詞、填充詞、模糊保留與客套話 +- 保留程式碼區塊、inline code、URL、路徑與技術詞 +- 保持 Markdown 結構不被破壞 + +## 2.3.3 策略性檔案組織 + +Copilot 會自動納入工作區中的內容，例如開啟中的檔案、匯入模組與附近檔案。你可以主動控制。 + +**真正有效的做法：** + +- **關掉目前沒在處理的檔案。** 開啟中的 editor tabs 是最常見的 auto-context 來源。 +- **讓檔案保持小而聚焦。** 1,000 行的大檔若開著，Copilot 可能會送很多內容進去。 +- **對 build output、vendor、generated files 使用 `.gitignore`。** +- **使用 `applyTo:` 範圍化 instruction 檔**，讓特定規則只在相關檔案出現時才載入。 +- **在 AI 工作前，先把非純文字檔轉成 Markdown。** 這是處理富格式輸入時，最直接的 token 節省。 +- **Business／Enterprise 環境下**，可請管理員設定 Content Exclusion 做政策與敏感路徑控管，詳見 [GitHub Docs — 從 Copilot 排除內容](https://docs.github.com/en/copilot/how-tos/configure-content-exclusion/exclude-content-from-copilot)。它只在 Copilot Business 與 Enterprise 提供，且不適用於 Copilot CLI、cloud agent 或 IDE Chat 的 Agent Mode；請把它當成隱私／政策控制，而非每位開發者的省 token 旋鈕。 + +要小心的高風險檔案包括： + +- 大型 README +- 產生檔與打包輸出 +- vendor 目錄 +- CSV／JSON fixture 等資料檔 +- 歷史存檔文件 +- 富格式文件（`.docx`、`.pdf`、`.pptx`、`.xlsx`、HTML 匯出、掃描圖片、音訊／影片逐字稿） + +### 先把非純文字輸入轉成 Markdown + +當來源是 Word、PDF、PowerPoint、試算表、圖片、音訊檔，或匯出的 HTML 時，只要流程允許，就不要直接把富格式內容丟進 AI。先轉成乾淨的 Markdown，再把 Markdown 送進去。 + +[Marc Bara 的文章](https://medium.com/@marc.bara.iniesta/your-docx-is-wasting-33-of-your-ai-budget-86a3d229d042) 把這件事稱為**格式稅**：Word、PDF 與 HTML 會夾帶字型資料、XML、頁面定位中繼資料、版面殘渣、內嵌物件與 tag soup。模型得處理這些內容，卻通常不需要它們。文中舉的例子是：同一份 10 頁報告，從 PDF 抽取後大約用了 12,400 tokens；轉成乾淨 Markdown 後約 8,350 tokens，資訊相同，輸入卻少了約 33%。HTML 匯出往往更糟，因為語意內容外面還包著一長串 tags、classes、IDs 與版面骨架。 + +實務規則很簡單：Markdown 才是 AI 互動時的**工作格式**；Word／PDF／PowerPoint 則是最後交付給人看的格式。草稿、審閱、摘要、切 chunk、RAG 擷取，都先用 Markdown。只有在客戶、法規或內部流程真的需要時，最後才輸出 `.docx` 或 `.pdf`。 + +[Microsoft MarkItDown](https://github.com/microsoft/markitdown) 是最實用的橋接工具。它是把各種檔案與 Office 文件轉成 Markdown 的 Python 工具，專門給 LLM 與文字分析流程使用。它會保留標題、清單、表格、連結與實用中繼資料，同時避開高保真的視覺版面雜訊。目前支援 PDF、Word、PowerPoint、Excel、具 EXIF／OCR 的圖片、可轉錄的音訊、HTML、CSV／JSON／XML、ZIP 內容、YouTube URL、EPUB 等。 + +快速路徑： + +```bash +pip install 'markitdown[all]' +markitdown report.docx -o report.md +markitdown deck.pptx -o deck.md +markitdown source.pdf > source.md +``` + +如果是正式流程，且你知道自己只會碰哪些格式，盡量安裝較小的 extras： + +```bash +pip install 'markitdown[pdf,docx,pptx,xlsx]' +``` + +安全提醒：MarkItDown 會以目前程序的權限讀取檔案、串流與 URL。面對不受信任的輸入時，先驗證路徑與 URL，再使用最小化的轉換能力。 + +## 2.3.4 有意識地縮小 Context：條件式優於常駐式 + +多數 context 檔都會在**每次互動**載入，即使和目前問題無關也是如此。 + +解法是：**優先使用條件式 context，而不是 always-on context。** + +### 用 `applyTo:` 路徑範圍化 custom instructions + +`.github/instructions/*.instructions.md` 支援 `applyTo` frontmatter。Copilot 只會在對話涉及符合 glob 的檔案時載入它。 + +```markdown +--- +applyTo: "src/api/**/*.ts" +--- +API conventions: +- Routes in src/api/routes/. Handlers thin, logic in services/. +- Validate with zod. Errors via Result, never throw. +- All endpoints return { data, error } envelope. +``` + +不加 `applyTo`，這段內容會在每次 Copilot 呼叫都出現。加上之後，只有真的在處理 API 檔案時才會付費。 + +### 工作流指引也要按需載入 + +像 PR review checklist、release template、debugging playbook 這種不是每次都用的內容，不應該永遠放在 `copilot-instructions.md`。 + +規則可以分三類： + +- **Always-on：** 每次都真的適用的少數規則 +- **Conditional（`applyTo`）：** 依路徑範圍出現的規則 +- **On-demand：** 工作流特定內容，只在需要時載入 + +## 2.3.5 善用快取 + +最便宜的 token，是平台不用重新處理的 token。穩定的 context 前綴，通常能獲得較好的快取效果。 + +兩個實用模式： + +1. **穩定內容放前面，變動內容放後面。** +2. **重複使用已命名的共用 context。** + +快取同時帶來兩個好處： + +- **更快** +- **更便宜** + +## 2.3.6 適時開新對話 + +對話歷史會持續累積。20+ 則訊息後，每次新訊息可能都帶著 50K+ tokens 的歷史一起送出。 + +**適合開新對話的時機：** + +- 題目切換 +- 已經拿到你需要的答案 +- 回應開始變慢 +- 模型明顯被舊 context 干擾 + +**怎麼保留延續性：** 在新對話用一小段摘要承接即可。 + +--- + +**下一章：** [Output Control →](05-output-control.zh-TW.md) diff --git a/docs/05-output-control.zh-TW.md b/docs/05-output-control.zh-TW.md new file mode 100644 index 0000000..ad6d374 --- /dev/null +++ b/docs/05-output-control.zh-TW.md @@ -0,0 +1,61 @@ +# 2.4 Output Control：告訴模型哪些話不要說 + +[English](05-output-control.md) | [繁體中文（台灣）](05-output-control.zh-TW.md) + +[← 返回指南](index.zh-TW.md) + +> **為什麼這章對成本最重要：** 在 Anthropic／Copilot UBB 的定價邏輯下，輸出 token 的單價約是輸入的 **5 倍**。即使回應長度通常小於總輸入，這個價差仍讓輸出控制成為全指南中 ROI 最高的手段之一。只要在 `copilot-instructions.md` 放上一句 `Code only, no explanation.`，許多程式任務的輸出成本就能永久減少 40–70%。 + +--- + +## 2.4.1 要求只輸出程式碼 + +LLM 很愛解釋。你只是要它產生 50 行程式碼，它卻可能多送你 200 tokens 的說明。 + +**加在 prompt 或 `copilot-instructions.md`：** + +```text +Code only, no explanation. +``` + +也可以直接寫： + +```text +Add input validation to processOrder(). Code only. +``` + +**節省幅度：** 程式產生類任務常可減少 40-70% 的輸出 token。 + +**取捨：** 如果你正在學習或除錯，就還是需要解釋。當你已經知道自己要什麼，只想拿到實作時，再開 `code only` 最合適。 + +## 2.4.2 限制回應格式 + +直接指定格式： + +| 指令 | 效果 | 輸出節省 | +|------|------|----------| +| "Answer in one sentence" | 限制冗長程度 | 約 60-80% | +| "3 bullet points max" | 硬性限制項目數 | 約 50-70% | +| "Reply as JSON" | 結構化、無散文 | 約 30-60% | +| "Table format" | 適合比較、較緊湊 | 約 40-60% | +| "Yes or no, then one line why" | 回覆極短 | 約 70-90% | + +## 2.4.3 在 System Level 設定精簡輸出 + +把精簡輸出設成專案預設，例如放進 `copilot-instructions.md`： + +```text +Be concise. No explanations unless asked. +Code only for generation tasks. +Bullets over paragraphs. +``` + +這樣每次互動都自動套用，不用你每次再重打一次。 + +**節省幅度：** 幾乎每次互動都能省下約 30-60% 的輸出 token。 + +**何時覆蓋：** 你真的需要解釋時，直接明講即可，例如：`Explain why this approach is better than X.` + +--- + +**下一章：** [Workflow Optimization →](06-workflow-optimization.zh-TW.md) diff --git a/docs/06-workflow-optimization.zh-TW.md b/docs/06-workflow-optimization.zh-TW.md new file mode 100644 index 0000000..392b857 --- /dev/null +++ b/docs/06-workflow-optimization.zh-TW.md @@ -0,0 +1,157 @@ +# 2.5 工作流程最佳化 + +[English](06-workflow-optimization.md) | [繁體中文（台灣）](06-workflow-optimization.zh-TW.md) + +[← 返回指南](index.zh-TW.md) + +--- + +## 2.5.1 Commit 訊息 + +建議用 Conventional Commits。標題 ≤ 50 字；只有在「為什麼」不明顯時才寫 body。 + +**冗長版：** + +```text +feat: Added a new feature to allow users to reset their passwords through +the settings page, which also sends a confirmation email +``` + +**精簡版：** + +```text +feat: add password reset via settings page + +Sends confirmation email on reset. +``` + +每則 commit 省的不多，但 Coding Agent 會讀 git history，整個 repo 累積起來就有差。 + +## 2.5.2 PR Review + +比起長段評論，單行格式通常更省又同樣可執行： + +```text +L42: bug: user can be null here. Add null guard before .email access. +``` + +常見嚴重度前綴： + +- `🔴` Bug / security，必修 +- `🟡` Suggestion，建議修 +- `🔵` Nit，可選最佳化 +- `❓` Question，需要釐清 + +## 2.5.3 Ask Mode vs. Agent Mode + +這是整份指南裡省 token 效果很大的決策之一。 + +**Agent Mode** 可能為每個可見動作觸發 3-10 次以上內部模型呼叫。 +**Ask Mode** 通常就是一次呼叫、一個回答。 + +| 任務 | 建議模式 | 原因 | +|------|----------|------| +| "What does this function do?" | Ask | 單次回答，不需要工具 | +| "What's the TypeScript syntax for generics?" | Ask | 單純知識問題 | +| "Refactor this module to use dependency injection" | Agent | 多檔案變更 | +| "Create a REST API with tests and docs" | Agent | 多步驟建立 | +| "Why is this test failing?" | Ask（通常） | 多半只需要你提供錯誤與上下文 | + +**簡單問題選 Ask**，通常能省下 60-90%。 + +### Copilot CLI 的例外：CodeAct + +如果你主要是在 **Copilot CLI** 裡跑很多工具鏈，外部外掛 [`copilot-codeact-plugin`](https://github.com/jsturtevant/copilot-codeact-plugin) 值得評估。它把原本多輪的 model → tool → model 循環收斂成一次沙箱執行。 + +它可能節省 token 的原因： + +- 減少 system prompt、歷史訊息與工具定義的重播次數 +- MCP 工具 catalog 載入次數也會跟著下降 +- 整合後的結果通常比逐步敘述每一步更短 + +### 互補：用 RTK 壓縮工具輸出 + +CodeAct 減少的是工具呼叫的**次數**；[**RTK (Rust Token Killer)**](https://github.com/rtk-ai/rtk) 減少的則是每次工具結果的**大小**，兩者可搭配使用。RTK 是 CLI proxy，會攔截 `git`、`cargo test`、`grep`、`ls` 等 100+ 種開發指令，在輸出回灌給 agent 前先壓縮，每個指令可省 60–90%。設定方式與完整指令清單見 [MCP & Tool Costs §2.7.7](08-mcp-tool-costs.zh-TW.md#277-rtk)。 + +## 2.5.4 預設使用 Auto 模型選擇 + +模型選擇器本身就是重要的成本控制介面。把高成本模型長時間釘住，代表連最簡單的互動都會用高費率計價。 + +**正確預設是 Auto。** + +- Auto 會從支援的 Auto pool 中選擇 +- 在付費方案上，符合條件時會套用折扣 +- 它不是「自動幫你升到最貴模型」，高成本 premium 模型通常仍要手動 pin + +只有在你清楚知道任務很簡單或很重，才手動指定模型。 + +## 2.5.5 依目標模型重調 Prompt + +這不是每次都能直接減少單次 token，而是透過提升第一次回答品質，減少補問、修正與 agent 返工。 + +建議流程： + +```text +打開目標模型的官方 prompting guide。 +把網址貼進 Copilot。 +請 Copilot 依這份指南調整你的 instruction / prompt files。 +保留行為不變，但減少錯誤回合與澄清成本。 +``` + +各家官方 prompting guide 起點： + +| 供應商 | 模型家族 | Prompting guide | +|---|---|---| +| Anthropic | Claude Sonnet / Opus / Haiku | [Prompt engineering 總覽](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview)、[Claude 最新模型最佳實務](https://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/claude-4-best-practices) | +| OpenAI | GPT-5.5 / GPT-5 | [GPT-5.5 prompting guide](https://developers.openai.com/api/docs/guides/prompt-guidance)、[GPT-5 prompting guide](https://cookbook.openai.com/examples/gpt-5/gpt-5_prompting_guide) | +| Google | Gemini | [Gemini prompt design strategies](https://ai.google.dev/gemini-api/docs/prompting-strategies) | + +適用時機： + +- 換了預設模型 +- 原本在某模型表現不錯的 prompt，在新模型變得太囉唆、太死板或太積極 +- agent 換模型後開始反覆做同一種錯誤假設 + +## 2.5.6 什麼時候不該壓縮 + +以下情境不要過度壓縮： + +- 安全警告 +- 不可逆操作 +- 新人 onboarding +- 容易因順序或歧義導致誤解的多步驟指令 +- 法規／合規文字 + +## 2.5.7 用 `/chronicle` 關閉回饋迴路 + +Token 浪費不只發生在單一 prompt，也會發生在你沒察覺的重複模式上。 +[`/chronicle`](https://docs.github.com/en/copilot/concepts/agents/copilot-cli/chronicle) 能分析你的本機 session 歷史，找出 Copilot 常誤解你的地方。 + +最有價值的是： + +- **`/chronicle improve`**：找出反覆誤判，產生 custom-instruction 建議 +- **`/chronicle tips`**：依你的使用模式給個人化改善建議 +- **`/chronicle standup`**：整理工作狀態，偏流程幫助，非直接省 token + +`improve` 的價值最大，因為它能把一再重複的浪費，轉成一次性的 instruction 修正。 + +## 2.5.8 VS Code 用量分析：AI Engineering Coach + +`/chronicle` 偏向 Copilot CLI。 +對 VS Code，對應工具是 [AI Engineering Coach](https://github.com/microsoft/AI-Engineering-Coach)。 + +它會從本機的 VS Code AI session logs 中分析： + +- 常見反模式 +- token 使用型態 +- context 健康度 +- 技能與工作流缺口 + +它與 `/chronicle` 的關係是互補： + +- `/chronicle` 修 prompt／instruction 的反覆失誤 +- AI Engineering Coach 稽核整體 VS Code 使用結構 + +--- + +**下一章：** [The AGENTS.md Problem →](07-agents-md-problem.zh-TW.md) diff --git a/docs/07-agents-md-problem.zh-TW.md b/docs/07-agents-md-problem.zh-TW.md new file mode 100644 index 0000000..3716a14 --- /dev/null +++ b/docs/07-agents-md-problem.zh-TW.md @@ -0,0 +1,101 @@ +# 2.6 Always-On Context 問題：為什麼更少通常更好 + +[English](07-agents-md-problem.md) | [繁體中文（台灣）](07-agents-md-problem.zh-TW.md) + +[← 返回指南](index.zh-TW.md) + +--- + +> **不同慣例，相同成本型態。** `AGENTS.md`、`.github/copilot-instructions.md`、`CLAUDE.md` 各自有不同來源與用途，但共同點是：只要工具會在每次互動載入它，它們就屬於 **always-on context**。本章雖然以 `AGENTS.md` 研究為主，但原理也適用於任何常駐 instruction 檔。 + +## 2.6.1 研究發現：Context Files 常常有害 + +很多人預設認為：**更多 context = 更好結果。** + +ETH Zurich 的研究（Gloaguen 等，AGENTBENCH，2026 年 2 月）在 12 個 repositories、138 個任務與 4 種 coding agents 上測試後，得到的結果是： + +| 發現 | 資料 | +|------|------| +| LLM 產生的 context files 會降低表現 | 8 種設定中有 5 種表現下滑 | +| 平均正確率變化 | **−2%** | +| 使用 LLM 產生 context file 的成本增加 | **多 20-23% tokens** | +| GPT-5.2 reasoning overhead | **多 22% reasoning tokens** | + +結論不是中性，而是：**常見的 LLM 產生 context files 會讓 agent 更差，還更貴。** + +## 2.6.2 人寫的檔案也只是小幅幫助 + +人工撰寫的 context files 表現稍好，但不穩定： + +| 模型 | 人工 context file 的效果 | +|------|--------------------------| +| 跨模型平均 | 約提升 4%，但不一致 | +| Claude Code | 反而更差 | +| 檔案發現率 | 有無 context file 幾乎一樣 | + +最後一點很重要：agent 本來就會 `ls`、`grep`，它不需要 context file 才知道怎麼找檔案。 + +## 2.6.3 為什麼更多 Context 反而會傷害效果 + +四個常見機制： + +1. **Redundancy tax：** 檔案裡的資訊，agent 本來就能從程式碼自己找到 +2. **Attention tax：** 太長的檔案會讓重要規則埋在中間被忽略 +3. **Anchoring trap：** Agent 會過度服從過時或次佳的指示 +4. **Signal-to-noise ratio 下降：** 低價值 context 會稀釋真正重要的專案地雷 + +## 2.6.4 效率與正確率不是同一件事 + +有研究指出人工撰寫的 `AGENTS.md` 可以降低執行時間與輸出 token，但那測的是**效率**，不是**正確率**。 + +重點不是 agent 能不能更快到答案，而是能不能到**對的答案**。 +而且更快的導航節省，常常會被處理 context file 本身增加的成本抵銷。 + +## 2.6.5 那到底該放什麼 + +Addy Osmani 的篩選法很實用： + +> **「Agent 能不能光靠讀程式碼自己發現？如果可以，就刪掉。」** + +| 保留 | 刪掉 | +|------|------| +| "Use `uv` instead of `pip`" | "This is a Python project" | +| "Run tests with `--no-cache`" | "Tests are in the `tests/` directory" | +| "Don't refactor the auth module" | "We use JWT for authentication" | +| "Deploy requires VPN connection" | "Main branch is protected" | +| "DB migrations must run in order" | "We use PostgreSQL" | + +**模式很簡單：只留地雷，不留可發現資訊。** + +## 2.6.6 把它當成 Bug Tracker + +理想的維護方式： + +```text +一開始幾乎空白。 +Agent 踩到一次坑 → 補一行。 +根因被修掉 → 刪掉那一行。 +``` + +Context file 應該像 bug tracker 一樣增減，而不是像 wiki 一樣只增不減。 + +## 2.6.7 這個 Repo 的做法：6 行、約 50 Tokens + +本專案的 `.github/copilot-instructions.md` 大約只有 6 行、約 50 tokens。 + +拿來對比典型 `/init` 產物： + +- `/init`：200+ 行、約 1,500 tokens +- 本 repo：6 行、約 50 tokens + +在 50 次互動或長 agent session 中，這種差距會非常驚人。 + +| 類型 | 每次載入 Tokens | 50 次互動 | Agent（20 steps） | +|------|----------------|-----------|-------------------| +| `/init` 產生 | 約 1,500 | 75,000 | 30,000 | +| 一般人工撰寫 | 約 400 | 20,000 | 8,000 | +| 極簡壓縮版 | 約 50 | 2,500 | 1,000 | + +--- + +**下一章：** [MCP & Tool Costs →](08-mcp-tool-costs.zh-TW.md) diff --git a/docs/08-mcp-tool-costs.zh-TW.md b/docs/08-mcp-tool-costs.zh-TW.md new file mode 100644 index 0000000..a1afdc4 --- /dev/null +++ b/docs/08-mcp-tool-costs.zh-TW.md @@ -0,0 +1,151 @@ +# 2.7 工具與 MCP Server 成本：隱性的 Token 稅 + +[English](08-mcp-tool-costs.md) | [繁體中文（台灣）](08-mcp-tool-costs.zh-TW.md) + +[← 返回指南](index.zh-TW.md) + +--- + +## 在最佳化前，先量測真正載入了什麼 + +很多 context 浪費都藏在你平常不看的地方。先確認你真正的 context window 裡有什麼，再調整 MCP 或 instructions。 + +**Copilot CLI：** 可以在 session 中執行 `/context` 看拆解。 + +```text +Context Usage claude-opus-4.6 · 104k/200k tokens (52%) +System/Tools: 62.5k (31%) +Messages: 41.8k (21%) +Free Space: 55.3k (28%) +Buffer: 40.4k (20%) +``` + +**關鍵差別：always-loaded vs on-demand** + +| 元件 | 載入時機 | 會進 context window？ | +|------|----------|-----------------------| +| MCP tool definitions | 每則訊息 | ✅ | +| Agent instructions / `copilot-instructions.md` | 每則訊息 | ✅ | +| System prompt | 每則訊息 | ✅ | +| Copilot CLI skills | 被要求時才載入 | ❌ | +| Conversation history | 每輪累積 | ✅ | + +這也是為什麼 skills 放很多內容在磁碟上，不代表會增加 `System/Tools` 基線；真正推高基線的是 MCP schema 與 always-on instructions。 + +## 2.7.1 每個 Tool 都要 Token + +啟用 MCP server 或 tool 後，其**完整定義**都會被載入 agent 的 context：名稱、描述、參數 JSON schema，全都算。 + +| 元件 | 約略 Tokens | +|------|-------------| +| Tool 名稱 + 描述 | 20-50 | +| 簡單參數 schema | 30-80 | +| 複雜參數 schema | 100-300 | +| **每個 Tool 合計** | **100-500** | + +## 2.7.2 乘法問題 + +真正貴的是它會被重複載入： + +```text +Tools loaded = servers × tools_per_server × tokens_per_tool + +Example: +10 MCP servers × 5 tools × 200 tokens = 10,000 tokens + +Agent mode 走 15 steps： +10,000 × 15 = 150,000 tokens +``` + +也就是說，還沒做任何真正工作，就先花了 15 萬個 token 讓 agent 知道有哪些工具可用。 + +## 2.7.3 Tool Call 本身也有成本 + +除了 schema，工具呼叫本身也會產生成本： + +| 階段 | 成本 | +|------|------| +| Function name + params | 每次 20-200 output tokens | +| Result parsing | 每次 50-2,000+ input tokens | +| Agent 判斷要用哪個工具 | 每步 50-200 tokens | + +## 2.7.4 MCP Server 稽核的前後差異 + +**啟用一切的重度設定** 與 **只保留必要工具的設定**，差異可能是每次 agent 任務數十萬 token。 + +核心結論： + +- 不用的 MCP server 真的要關 +- schema 成本是每步都重付，不是只付一次 + +## 2.7.5 每個 Workspace 各自設定 MCP + +不要把所有 MCP server 都全域開著。 +做法是： + +- **全域設定** 只放真正到處都要用的 +- **workspace 設定** 才放專案特定的 + +規則很簡單：**這次任務用不到，就先關掉。** + +## 2.7.6 實用建議 + +1. **稽核你的 MCP servers**，停掉不用的 +2. **依任務啟用**，例如做 DB migration 才打開 Postgres MCP +3. **優先用內建工具**，避免和外掛 MCP 重複 +4. **注意總 tool 數量** +5. **在 custom instructions 補一句**，例如：`Minimize tool calls. Read files only when necessary.` +6. **偶爾才用的能力，優先做成 skill，不是 MCP** +7. **Copilot CLI 長工具鏈可考慮 CodeAct**（外部外掛 [`copilot-codeact-plugin`](https://github.com/jsturtevant/copilot-codeact-plugin)） +8. **用 RTK 壓縮工具輸出** + +## 2.7.7 從源頭壓縮工具輸出：RTK + +MCP schema 是「工作開始前」的成本。另一個大頭是 shell 命令的輸出：它們會在下一步原封不動回灌成 agent 的輸入 token。 + +[RTK (Rust Token Killer)](https://github.com/rtk-ai/rtk) 是 CLI proxy，會攔截指令、過濾噪音，再把壓縮後的結果傳回 agent。 + +**它做了什麼：** + +1. Agent 發出 Bash tool call +2. RTK 攔截並改寫為 `rtk ` +3. RTK 執行真正命令 +4. 依命令類型過濾雜訊 +5. Agent 拿到語意相同但更短的結果 + +**常見減幅：** + +| 指令 | 原始輸出 | RTK 後 | 減幅 | +|------|----------|--------|------| +| `ls` / `tree` | 約 2,000 | 約 400 | -80% | +| `git status` | 約 3,000 | 約 600 | -80% | +| `git diff` | 約 10,000 | 約 2,500 | -75% | +| `cargo test` / `npm test` | 約 25,000 | 約 2,500 | -90% | +| `grep` / `rg` | 約 16,000 | 約 3,200 | -80% | + +**對 VS Code Copilot 的重點：** + +- 需以 repo 為單位啟用：`rtk init --copilot` +- 這不是全域一次裝好就全部生效 +- 只影響 agent 的 Bash tool calls，不影響內建 `Read`、`Grep`、`Glob` + +## 2.7.8 案例：把大型 Plugin 範圍化 + +大型 plugin 常常是一整個 `System/Tools` 成本大戶。 +以 Azure MCP 為例，若預設載入 200+ tools，單一 plugin 就可能吃掉數萬 tokens。Microsoft／GitHub 內容貢獻者 Dina Berry 實測一套真實的 Copilot CLI 設定，發現單一 Azure plugin 每則訊息就載入約 27K tokens，跑 `/context` 之前完全看不出來。 + +做法通常有兩種： + +- **完全停用**：這個 session 根本不用 Azure +- **namespace 範圍化**：只保留真的有在用的 Azure services + +一般原則很清楚： + +- 當 `System/Tools` 偏高時，先檢查大型 plugins +- 一個大 plugin 的成本，常常比其他所有工具加總還高 + +完整實測記錄：[dfberry.github.io — Tuning up Copilot context](https://dfberry.github.io/2026-05-06-tuning-up-copilot-context)。 + +--- + +**下一章：** [Comparisons & Data →](09-comparisons-data.zh-TW.md) diff --git a/docs/09-comparisons-data.zh-TW.md b/docs/09-comparisons-data.zh-TW.md new file mode 100644 index 0000000..f75cda4 --- /dev/null +++ b/docs/09-comparisons-data.zh-TW.md @@ -0,0 +1,106 @@ +# Part 3：比較與資料 + +[English](09-comparisons-data.md) | [繁體中文（台灣）](09-comparisons-data.zh-TW.md) + +[← 返回指南](index.zh-TW.md) + +--- + +## 3.1 正面對決：同一個 Prompt，不同技巧 + +**任務：** "Add error handling to this function" + +| 技巧 | Prompt | 約略輸入 Tokens | 輸出品質 | +|------|--------|-----------------|----------| +| 冗長英文 | "Hey, could you please add comprehensive error handling..." | 約 40 | 好，但偏冗長 | +| Caveman lite | "Add error handling to this function. Cover null inputs..." | 約 16 | 好 | +| Caveman full | "Add error handling. Cover: null input, bad type..." | 約 12 | 好 | +| Caveman ultra | "Error handling: null/bad-type/net-err." | 約 7 | 好，但更依賴上下文 | +| 結構化 | `fn: add error handling\n- null input\n- invalid type\n- network error` | 約 12 | 好 | +| Code-centric | `# TODO: handle None, TypeError, ConnectionError` | 約 8 | 好 | + +這六種寫法都能得到正確方向的程式碼，但成本從 7 到 40 tokens，差了 **5.7 倍**。 + +## 3.2 語言比較表 + +### 單句比較 + +| 語言 | 句子 | 字元數 | UTF-8 Bytes | Tokens | 相對英文成本 | +|------|------|--------|-------------|--------|--------------| +| 英文 | I met a huge dog | 16 | 16 | **5** | 1.0x | +| 西班牙文 | Conocí a un perro enorme | 24 | 25 | **8** | 1.6x | +| 波蘭文 | Spotkałem ogromnego psa | 23 | 24 | **8** | 1.6x | +| 冰島文 | Ég hitti risastóran hund | 24 | 26 | **10** | 2.0x | +| 中文 | 我遇見了一隻大狗 | 8 | 24 | **11** | 2.2x | +| 日文 | 大きな犬に出会った | 9 | 27 | **11** | 2.2x | +| 俄文 | Я встретил огромную собаку | 26 | 49 | **14** | 2.8x | +| 希伯來文 | פגשתי כלב ענק | 13 | 24 | **16** | 3.2x | + +### 大樣本平均 + +| 語言 | 相對英文平均 Token 成本 | 每個 Token 對應字元數 | 判斷 | +|------|------------------------|-----------------------|------| +| English | 1.0x | 4.75 | ✅ 最適合 prompt | +| Spanish | 約 1.3-1.6x | 約 3.5 | ⚠️ 30-60% 更貴 | +| German | 約 1.4-1.6x | 約 3.2 | ⚠️ 40-60% 更貴 | +| Mandarin Chinese | 約 1.76x | 1.33 | ❌ 約 76% 更貴 | +| Japanese | 約 2.12x | 1.41 | ❌ 約 112% 更貴 | +| Korean | 約 2.36x | 約 1.2 | ❌ 約 136% 更貴 | +| Russian | 約 2.5-2.8x | 約 2.0 | ❌ 約 150-180% 更貴 | + +## 3.3 技巧總表 + +以下是本指南涵蓋技巧的高層比較： + +| 類別 | 技巧 | 輸入節省 | 輸出節省 | 品質影響 | 最適用情境 | +|------|------|----------|----------|----------|------------| +| Communication | Caveman-speak | 30-50% | 40-55%* | 極低 | 所有 Copilot 互動 | +| Communication | Structured prompts | 20-40% | 30-50% | 多半更好 | 技術性 prompt | +| Prompting | Precise prompts | 30-60% | 30-60% | 多半更好 | 所有互動 | +| Prompting | Constrain output | — | 40-80% | 視格式而定 | 資料抽取、快速回答 | +| Context | Limit context | 50-90% | — | 視情況 | 大型 codebase | +| Context | Compressed instructions | 40-60% of file | — | 幾乎無 | 每個 repo | +| Context | 先把非純文字檔轉成 Markdown | 引用 PDF 範例約 33%；雜訊 HTML 通常更高 | — | 結構更清楚 | DOCX、PDF、PPTX、XLSX、圖片、音訊、RAG 匯入 | +| Output | Code-only responses | — | 40-70% | 好 | 程式產生 | +| Agent | Ask vs Agent mode | 60-90% | — | 好 | 簡單問題 | +| Always-on files | 只留 landmines | 視檔案大小 | — | 多半更好 | 所有 agent 工作流 | +| MCP | Audit servers | 5K-190K/task | — | 無 | Agent mode | + +\*輸出節省要搭配 system-level 的精簡輸出設定。 + +### 影響最大的一批 + +1. **Caveman-speak** +2. **Precise prompts** +3. **Code-only / constrain output** +4. **縮小 always-on context** +5. **簡單問題用 Ask Mode** +6. **先把非純文字檔轉成 Markdown** +7. **稽核 MCP servers** +8. **依模型調整 prompts** + +> C5 來源：Marc Bara 的 [Your .docx Is Wasting 33% of Your AI Budget](https://medium.com/@marc.bara.iniesta/your-docx-is-wasting-33-of-your-ai-budget-86a3d229d042)。當非純文字檔需要進入 AI 工作流時，優先使用 [Microsoft MarkItDown](https://github.com/microsoft/markitdown)。 + +## 3.4 品質影響評估 + +壓縮會不會傷害品質？答案通常是：**很少，除非你壓過頭。** + +| 壓縮程度 | 品質影響 | 判斷 | +|----------|----------|------| +| Lite | 幾乎無 | 安全 | +| Full | 可忽略 | 最甜蜜點 | +| Ultra | 有小風險 | 複雜指令時要小心 | +| 文言文 | 中度風險 | 不建議用於實務 | +| 極端壓縮 | 高風險 | 易產生歧義 | + +### 效益遞減 + +最前面那 30% 的壓縮幾乎是白撿的：刪掉 filler 就好。 +再往後 20% 也通常很划算。 +超過那個點後，每多壓一點，都更可能帶來誤解。 + +**建議甜蜜點：** Full caveman。 + +--- + +**下一章：** [Practical Setup →](10-practical-setup.zh-TW.md) diff --git a/docs/10-practical-setup.zh-TW.md b/docs/10-practical-setup.zh-TW.md new file mode 100644 index 0000000..cf89398 --- /dev/null +++ b/docs/10-practical-setup.zh-TW.md @@ -0,0 +1,283 @@ +# Part 4：實際設定 + +[English](10-practical-setup.md) | [繁體中文（台灣）](10-practical-setup.zh-TW.md) + +[← 返回指南](index.zh-TW.md) + +--- + +## 4.1 如何把 GitHub Copilot 設定得更省 Token + +### Step 1：建立 `copilot-instructions.md` + +在 repo 根目錄建立 `.github/copilot-instructions.md`。這個檔案會在每次 Copilot 互動都被載入。 + +```bash +mkdir -p .github +touch .github/copilot-instructions.md +``` + +**建議起手式：** + +```markdown +Terse like caveman. Technical substance exact. Only fluff die. +Drop: articles, filler (just/really/basically), pleasantries, hedging. +Fragments OK. Short synonyms. Code unchanged. +Pattern: [thing] [action] [reason]. [next step]. +ACTIVE EVERY RESPONSE. No revert after many turns. No filler drift. +Code/commits/PRs: normal. Off: "stop caveman" / "normal mode". +``` + +這種版本大約 50 tokens，遠小於自然英文版的 120+ tokens。 + +### Step 2：用壓縮風格加入專案規則 + +```markdown +Stack: Node.js 20, TypeScript 5.4, PostgreSQL 16, Redis. +Test: Vitest. Lint: ESLint flat config. +Style: functional core, imperative shell. No classes. +Naming: camelCase vars/fns, PascalCase types, UPPER_SNAKE constants. +Errors: Result pattern, no thrown exceptions in business logic. +``` + +重點是：**保留規則，不保留廢話。** + +### Step 3：選擇預設模式 + +| 任務類型 | 建議模式 | 原因 | +|----------|----------|------| +| 快問快答 | Ask | 單次 LLM 呼叫，無工具負擔 | +| 程式說明 | Ask | 通常不需要改檔 | +| Bug 診斷 | Ask（多數） | 你可直接提供上下文 | +| 單檔修改 | Edit | 目標明確，負擔較低 | +| 多檔案重構 | Agent | 需要跨檔案讀寫 | +| 新功能實作 | Agent | 多步驟建立 | +| Issue-to-PR 自動化 | Coding Agent | 完整自主流程 | + +### Step 4：有策略地選模型 + +模型選擇應該反映任務真正需要的**努力等級**，不是習慣性地把最強模型整天釘住。 + +| 模型層級 | 相對成本 | 適用情境 | +|----------|----------|----------| +| 輕量模型 | 最低 | autocomplete、語法查詢、簡單問答 | +| 標準模型 | 中等 | 大多數日常開發 | +| 高努力模型 | 最高 | 架構、深度推理、安全審查 | +| **Auto** | 預設較低 | 當作日常基準最合理 | + +**預設用 Auto。** +只有在你知道任務特別簡單，或真的需要更深推理時，再手動切模型。 + +### Step 5：依任務混用模型 + +一個有效的成本策略是：**同一個工作流程，不同子任務用不同模型。** + +| 任務 | 建議模型 | 為什麼 | +|------|----------|--------| +| "What does this function do?" | 便宜／內含模型 | 只要知識擷取 | +| Quick explanations | 輕量模型 | 夠用就好 | +| 實作功能、修 bug | 標準模型 | 品質／成本比最好 | +| 架構決策、安全審查 | 高努力模型 | 真的值得多花 | + +核心原則：**不要把 premium 模型拿去做便宜模型也能正確完成的工作。** + +來源：[Anthropic Effort 參數文件](https://platform.claude.com/docs/en/build-with-claude/effort)、[VS Code Language Models 文件](https://code.visualstudio.com/docs/copilot/concepts/language-models)、[GitHub Copilot CLI 程式化參考](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-programmatic-reference)。 + +### Step 6：依實際使用模型重調 Instructions + +換模型時，不要假設舊 prompt stack 還是最佳做法。 +最佳流程： + +```text +把官方 guide 網址貼進 Copilot。 +指定目標模型與要調整的檔案。 +請它在不改變行為的前提下，降低錯誤與返工。 +``` + +各家官方 guide 起點：[Anthropic Claude 最佳實務](https://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/claude-4-best-practices)、[OpenAI GPT-5 prompting guide](https://cookbook.openai.com/examples/gpt-5/gpt-5_prompting_guide)、[Google Gemini prompt strategies](https://ai.google.dev/gemini-api/docs/prompting-strategies)。 + +### Step 7：把治理控制放在 Prompt 外 + +Prompt 檔只能影響行為，真正的計費控制在別處。 +若你在做組織或企業推動，請直接看 [Enterprise Governance](12-enterprise-governance.zh-TW.md)。 + +### Step 8：先把非純文字輸入轉成 Markdown 再交給 AI + +如果工作流一開始就會碰到 `.docx`、`.pdf`、`.pptx`、`.xlsx`、HTML 匯出、圖片、音訊、影片或 ZIP 壓縮檔，請在內容進入 Copilot 或 RAG pipeline 之前先加一道轉換步驟。富格式檔案會夾帶版面與中繼資料，增加輸入 token，卻不會提升模型理解。 + +[Marc Bara 的格式稅文章](https://medium.com/@marc.bara.iniesta/your-docx-is-wasting-33-of-your-ai-budget-86a3d229d042) 已把原則講得很清楚：Markdown 才是 AI 的工作格式，Word／PDF 則是人類流程需要時的交付格式。文中引用的 10 頁 PDF 範例，轉成乾淨 Markdown 後，token 量大約從 12,400 降到 8,350，資訊不變，輸入卻少了約 33%。 + +[Microsoft MarkItDown](https://github.com/microsoft/markitdown) 是預設最值得先試的工具。它可以把 PDF、Word、PowerPoint、Excel、圖片、音訊、HTML、CSV／JSON／XML、ZIP 內容、YouTube URL、EPUB 等轉成適合 LLM 與文字分析工作流的 Markdown。 + +```bash +pip install 'markitdown[all]' + +markitdown report.docx -o report.md +markitdown slides.pptx -o slides.md +markitdown spreadsheet.xlsx -o spreadsheet.md +markitdown source.pdf > source.md +``` + +如果是正式流程，且可控格式有限，盡量只安裝需要的 extras： + +```bash +pip install 'markitdown[pdf,docx,pptx,xlsx]' +``` + +之後把 `.md` 檔送進模型，或拿 `.md` 做 chunk／index；等到最後交付階段，再重新產出 `.docx` 或 `.pdf`。若來源不受信任，先驗證路徑與 URL；MarkItDown 會以執行程序的權限進行 I/O。 + +## 4.2 把可重用指引留在 Always-On Context 之外 + +這個 repo 不再內建可安裝 workflow packs，但原則一樣： + +- PR review checklist +- release／rollback templates +- debugging playbooks +- subsystem migration notes + +只要不是大多數互動都需要的內容，就不要一直放在 always-on prompt 裡。 + +### MCP vs Skills：Eager vs Lazy + +| 機制 | 每輪載入什麼 | 完整內容何時載入 | +|------|--------------|------------------| +| MCP | 完整 tool schema | 一直都在 | +| Skill | 標題 + 描述 | 只有被使用時 | + +**規則：** 常用能力用 MCP；偶爾才用的能力更適合 skill。 + +## 4.3 GitHub Coding Agent 的注意事項 + +### 4.3.1 壓縮 `copilot-instructions.md` + +Agent 也會讀這個檔案；它每一步都可能再次為這些 token 付費。 + +### 4.3.2 使用 `copilot-setup-steps.yml` + +預先把依賴安裝與建置步驟寫死，避免 agent 反覆試錯。 + +```yaml +steps: + - name: Install dependencies + run: npm ci + - name: Build + run: npm run build +``` + +### 4.3.3 Issue 描述要精準 + +精準 issue 能明顯減少 agent 的探索與返工。 + +**不好：** + +```text +Fix the login bug +``` + +**較好：** + +```text +Bug: login fails when email contains '+' character. +File: src/auth/login.ts, validateEmail() on L42. +Fix: URL-encode the email before passing to the OAuth provider. +Test: add case for "user+tag@example.com" in login.test.ts. +``` + +### 4.3.4 保持 PR 留言與 Commit 訊息精簡 + +Agent 會讀它們，把它們也當成 context。 + +### 4.3.5 客製化 Agent Profiles + +與其一份超大總 instruction，不如按任務類型做聚焦版 profile。 + +### 4.3.6 用 RTK 壓縮 Shell 輸出 + +Coding Agent 會跑很多 shell 指令，輸出都會回灌成下一步的輸入 token。[RTK (Rust Token Killer)](https://github.com/rtk-ai/rtk) 能把這些結果先壓縮再交給 agent，行為不變但輸出更精簡。安裝： + +```bash +brew install rtk # 或：curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh +``` + +設定方式與各指令減幅見 [MCP & Tool Costs §2.7.7](08-mcp-tool-costs.zh-TW.md#277-rtk)。 + +## 4.4 建立習慣 + +### 從小做起 + +1. 第 1 週：加入壓縮版 `copilot-instructions.md` +2. 第 2 週：練習 caveman-lite +3. 第 3 週：升級到 caveman-full +4. 第 4 週：在 code generation 任務加上 `code only` + +### 每月維護 + +- 檢查 `copilot-instructions.md` 是否膨脹 +- 檢查其他記憶檔是否變冗長 +- 關掉不必要的開啟分頁 +- 檢查是否常把高成本模型釘住 +- 預設模型變更時，重調 prompts + +## 4.5 為效率設定 Agent Mode + +### 4.5.1 Ask / Edit / Agent 的成本型態不同 + +| 模式 | 每次動作的 LLM 呼叫數 | 工具使用 | 最適合 | +|------|-----------------------|----------|--------| +| Ask | 1 | 無 | 問題、解釋 | +| Edit | 1-2 | 讀寫檔案 | 單檔修改 | +| Agent | 5-25 | 完整工具集 | 多步驟、多檔案任務 | + +Agent Mode 常比 Ask Mode 貴上很多倍。 + +### 4.5.2 Agent Mode 的內部迴圈 + +每多一步，完整 context 都可能再重送一次，而且還會帶上前一步的結果，因此後期步驟會越來越貴。 + +### 4.5.3 如何減少 Agent 步數 + +- **Prompt 要精準，並加上 acceptance criteria** +- **複雜任務先寫 plan file** +- **確定性的操作盡量交給 shell 一次完成，不要讓 agent 一步一步探索** + +### 4.5.4 VS Code 設定 + +```json +{ + "chat.agent.maxRequests": 10, + "github.copilot.chat.agent.model": "auto" +} +``` + +### 4.5.5 給 Agent 的效率型 Instructions + +```text +Minimize tool calls. Read files only when necessary. +Batch related changes. Don't read-modify-read-modify when read-modify-modify works. +Prefer grep_search over sequential read_file for discovery. +``` + +### 4.5.6 模式選擇框架 + +```text +問語法／概念／程式用途？ + → Ask + +單檔修改？ + → Edit + +多檔案且範圍清楚？ + → Agent + 精準 prompt + +模糊的 "幫我修一下"？ + → 先用 Ask 釐清，再切 Agent +``` + +## 4.6 管理員層級防護欄在別處 + +這一頁是給實作者的。 +如果你在做組織或客戶治理，請看 [Enterprise Governance](12-enterprise-governance.zh-TW.md)。 + +--- + +**下一章：** [Enterprise Governance →](12-enterprise-governance.zh-TW.md) diff --git a/docs/11-models-and-pricing.zh-TW.md b/docs/11-models-and-pricing.zh-TW.md new file mode 100644 index 0000000..352c794 --- /dev/null +++ b/docs/11-models-and-pricing.zh-TW.md @@ -0,0 +1,134 @@ +# 模型選擇與定價 + +[English](11-models-and-pricing.md) | [繁體中文（台灣）](11-models-and-pricing.zh-TW.md) + +[← 返回指南](index.zh-TW.md) + +--- + +這一頁存在的原因，是因為「模型怎麼選」與「費用怎麼看」很容易被混在一起。這裡其實有三種不同的定價視角： + +1. **GitHub Copilot 官方文件** +2. **本 repo 對 UBB 的理解框架** +3. **模型供應商 API 的每 token 定價** + +不要把這三者當成同一種單位。 + +## 你真正想看的官方 GitHub 文件 + +- [About Copilot auto model selection](https://docs.github.com/en/copilot/concepts/auto-model-selection) +- [Requests in GitHub Copilot](https://docs.github.com/en/copilot/concepts/billing/copilot-requests) +- [Plans for GitHub Copilot](https://docs.github.com/en/copilot/get-started/plans) + +這三頁大致上涵蓋實作者最需要知道的： + +- 有哪些模型 +- 哪些方案可以用 +- 哪些是 included、哪些是 premium +- Auto 真正怎麼運作 + +## 關於 Auto 最重要的澄清 + +repo 中一直建議把 **Auto** 當預設，這個方向仍然正確，但要更精準理解： + +- Auto 會從**支援的 Auto pool** 中選 +- 選擇依據是即時系統狀態與模型表現 +- 在付費方案中，Copilot Chat 的 Auto 可能有 **10% 折扣** +- Auto 不等於「自動幫你升到每一種 premium 模型」 + +> **實務後果：** Auto 是低摩擦的預設通道；如果你真的要更高成本 premium 模型，通常要自己手動 pin。 + +## 三種定價視角各自回答什麼問題 + +| 視角 | 單位 | 適合回答的問題 | +|------|------|----------------| +| GitHub 公開 Copilot 計費 | 模型倍率、AI credits | Copilot 裡官方怎麼描述這模型的成本？ | +| Repo 的 UBB 框架 | AI credits、預算 | Business / Enterprise 在 2026/06/01 後該怎麼看用量？ | +| Vendor API pricing | 每百萬 token 單價 | 原始 token 成本如何分別體現在輸入與輸出？ | + +各視角官方來源：[GitHub Copilot 計費 — Requests](https://docs.github.com/en/copilot/concepts/billing/copilot-requests)、[計量產品預算設定](https://docs.github.com/en/billing/how-tos/budgets/setting-up-budgets-to-control-spending-on-metered-products)、[Anthropic Pricing](https://platform.claude.com/docs/en/about-claude/pricing)。 + +## 輸入與輸出定價的關係 + +GitHub 目前沒有公開各 Copilot 模型的「輸入 token 單價 vs 輸出 token 單價」表。 +但 Anthropic API 定價仍然非常適合拿來理解「輸出遠比輸入貴」這件事。 + +| 模型 | 每百萬輸入 | 每百萬輸出 | +|------|------------|------------| +| Claude Haiku 4.5 | $1 | $5 | +| Claude Sonnet 4.6 | $3 | $15 | +| Claude Opus 4.6 | $5 | $25 | + +來源：[Anthropic Pricing](https://platform.claude.com/docs/en/about-claude/pricing)。 + +這能幫你建立正確直覺： + +- 輸出 token 的成本明顯更高 +- 冗長回覆比多打一點 prompt 更容易把成本拉高 +- 所以輸出控制依然是最有價值的習慣之一 + +## Reasoning Effort 是另一個成本旋鈕 + +模型不是唯一選項。對支援推理的模型，**thinking effort / reasoning effort** 也是成本控制項。 + +| 情境 | 建議 effort | 原因 | +|------|-------------|------| +| 高頻、簡單聊天或分類 | `low` | 最省 | +| 一般 coding、refactor、工具密集工作 | `medium` | 品質與成本平衡最好 | +| 架構、安全審查、全新分解問題 | `high` 或 `max` | 只有真的值得時才拉高 | + +> **重點：** 只有支援 reasoning 的模型才有這個旋鈕。 + +因此完整決策鏈應是： + +1. 先選對模型層級 +2. 如果該模型支援，再選最低但足夠的 reasoning effort + +## 實際上該怎麼做 + +### 預設立場 + +1. **日常工作預設用 Auto** +2. **瑣碎任務用 included 或較便宜模型** +3. **只有明顯值得時才手動 pin premium 模型** +4. **組織層面要先看 model policy，再擴大 premium 存取** + +### 好用的預設 heuristics + +| 任務 | 建議選擇 | 原因 | +|------|----------|------| +| 語法查詢、簡單說明、小修改 | Included model 或 Auto | 最便宜的路就夠用 | +| 一般實作、修 bug、重構 | Auto 或標準模型 | 品質／成本比最好 | +| 架構、threat modeling、全新拆解 | 手動 pin premium | Auto 不會自動跳進 premium lane | + +### 反模式 + +- 整個 session 都釘著昂貴 premium 模型 +- 以為 Auto 會在任務變難時自動幫你升到 Opus +- 把 vendor API 價格與 Copilot 價格信號當成同一件事 +- 沒確認方案支援就推薦模型 +- 還沒確認實際需求就對整個組織開啟所有 premium 模型 + +## 組織推行原則：啟用前先審查 + +團隊層面的模型選擇同時是治理問題，不只是 prompt 問題。 + +實務建議： + +1. 先開較便宜模型 +2. 依 workflow、團隊與 ROI 審 premium 需求 +3. 小範圍啟用 premium +4. 看 usage reports 與 AI credits 消耗，再決定是否擴大 + +組織擁有者與企業擁有者可用 [Configuring access to AI models in Copilot](https://docs.github.com/en/copilot/using-github-copilot/ai-models/configuring-access-to-ai-models-in-copilot) 控制成員能存取哪些 AI 模型。 + +## Repo 內交叉參照 + +- [Practical Setup](10-practical-setup.zh-TW.md) +- [Workflow Optimization](06-workflow-optimization.zh-TW.md) +- [Enterprise Governance](12-enterprise-governance.zh-TW.md) +- [Guide Home](index.zh-TW.md) + +--- + +**下一章：** [Enterprise Governance →](12-enterprise-governance.zh-TW.md) diff --git a/docs/12-enterprise-governance.zh-TW.md b/docs/12-enterprise-governance.zh-TW.md new file mode 100644 index 0000000..1e27fed --- /dev/null +++ b/docs/12-enterprise-governance.zh-TW.md @@ -0,0 +1,132 @@ +# Copilot 成本控制的企業治理 + +[English](12-enterprise-governance.md) | [繁體中文（台灣）](12-enterprise-governance.zh-TW.md) + +[← 返回指南](index.zh-TW.md) + +--- + +這一頁是寫給組織與企業管理員的。目標是：**在 GitHub 有文件支援的前提下控制成本，不自己發明不存在的控制機制。** + +## 真正控制成本的是什麼 + +最重要的三個槓桿： + +1. 預算上限 +2. 使用者層級預算控制 +3. 模型可用性 + +Prompt 壓縮依然重要，但那是**用量效率**槓桿，不是管理員計費控制。 + +## 1. 先設定預算 + +在 2026 年 6 月 1 日之後，Business 與 Enterprise 的治理主軸改成 AI credits 與 usage-based billing。可參考 GitHub 的[組織與企業 usage-based billing 指南](https://docs.github.com/en/copilot/concepts/billing/usage-based-billing-for-organizations-and-enterprises)與[計量產品的預算設定文件](https://docs.github.com/en/billing/how-tos/budgets/setting-up-budgets-to-control-spending-on-metered-products)。 + +GitHub 文件中的重點： + +- 可以在 organization、enterprise 或 cost center 層級設預算 +- 可以設定達到預算時停止使用 +- 也有 user-level budgets +- **使用者預算設為 `$0`** 代表該使用者無法使用 usage-based 功能 + +要注意一個重點：預算**不會**讓 prompt 變小，也**不會**減少每個 prompt 的 token，它只是替 AI credit 支出設上限。 + +實務預設： + +1. 先用非零測試預算啟動 rollout +2. 提早開 alerts +3. 觀察報表正常後，再開 stop usage +4. 每月固定檢查，不要等超支才看 + +## 2. 用 User-Level Budgets 做每人收緊 + +對 Business / Enterprise 來說，2026/06/01 之後最乾淨的每人上限，就是 GitHub [usage-based billing 指南](https://docs.github.com/en/copilot/concepts/billing/usage-based-billing-for-organizations-and-enterprises)所記載的 **user-level AI credit budget**。文件明確指出：使用者預算設為 **`$0`** 代表該使用者無法使用 usage-based 功能。 + +管理思維應轉成： + +- 先看 AI credit 用量 +- 再看模型選擇、聊天深度、agent 時長 + +實務模式： + +1. 一般使用者配低一些的 user-level 預算 +2. 重度使用者只有在工作需要明確時才提高 +3. 每月檢查，價值不明顯的使用者再降回來 + +> **舊制備註：** 若你還在為 6/1 之前的客戶做準備，[premium request management](https://docs.github.com/en/copilot/concepts/billing/premium-request-management) 說明的是即將淘汰的控制模型，只能當成過渡期指引。 + +## 3. 啟用模型前先審查 + +GitHub 支援由 organization 或 enterprise owner 控制成員可用的 AI 模型，做法見[在 Copilot 中設定 AI 模型存取](https://docs.github.com/en/copilot/using-github-copilot/ai-models/configuring-access-to-ai-models-in-copilot)。 +把這當成**官方支援的模型治理方式**。 + +建議的審查清單： + +1. 哪些 workflow 真的需要 premium 模型 +2. 哪些團隊會產生可量化價值 +3. 哪些使用者維持 Auto 或 included models 就足夠 +4. 啟用後要看哪份 usage report +5. 若成本跳升卻沒有品質收益，要用什麼 rollback 條件 + +## 4. 把 Custom Instructions 放在正確層級 + +GitHub 文件區分： + +- **repository instructions**（見[新增 repository custom instructions](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions)） +- **organization instructions**（見[新增 organization custom instructions](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-organization-instructions)） + +重要的是它們的套用範圍不同。 +尤其對成本控制來說，要注意： + +- 組織層級 instructions 不要假設在 IDE 一定生效 +- 如果你想讓 VS Code 或 JetBrains 也有精簡行為，應該把關鍵 always-on 規則放在 **repo instructions** + +建議分工： + +- **Org instructions：** 廣泛政策、review 提醒、GitHub.com surfaces 的跨 repo 規則 +- **Repo instructions：** coding、build、精簡輸出等 IDE 也需要的規則 +- **Path-specific instructions：** 只有局部需要的細規則 + +## 5. 分開組織可行，但只是有條件的做法 + +若你需要不同的 org-level model policies 或獨立 billing boundary，拆成不同 organizations 可能有用。 + +但這不是萬靈丹，代價包括： + +- 更多管理成本 +- license 分配更複雜 +- 使用者若跨多 org，流程更麻煩 + +只有當政策或計費邊界真的值得時，才考慮這條路。 + +## 6. 量測正確的東西 + +請看 GitHub usage reports 與 AI-credit reporting，重點問這四件事： + +1. 哪些團隊最常超過基線支出 +2. 哪些使用者消耗最多 AI credits +3. 哪些模型真的和更好結果有關，而不是只是習慣 +4. 哪些 agent workflows 花很多錢，卻沒有相稱交付價值 + +外部 benchmark 可以做補充，但不能取代你自己的 Copilot usage data。[llm-stats.com](https://llm-stats.com/) 可當成獨立的參考點，但請把它當成**補充性 benchmark**，既不是 GitHub 官方指引，也不能取代你自己的 Copilot usage reports。 + +## 7. 6 月 1 日切換清單 + +如果你在幫客戶準備 2026 年 6 月 1 日的切換： + +1. 把管理思維從 request counters 轉成 AI-credit budgets +2. 先決定哪些使用者需要緊 user-level budgets +3. 在 frontier models 變成直接成本前，先審模型可用性 +4. 提醒團隊：code completions 與 next edit suggestions 不計入 AI credits +5. 優先觀察長 chat 與 agent workflows，因為它們最容易放大支出 + +## 建議的企業預設 + +1. 預設模型路徑用 Auto +2. 廣泛 rollout 前先設預算 +3. 需要時用 user-level AI credit budgets 做更細控制 +4. premium 模型先審後開 +5. repo instructions 保持小而精 +6. 只有在 cost center／政策邊界真的合理時才拆 org + +這套做法刻意很無聊：**先用便宜預設，再用例外方式擴 premium，最後用量測結果決定是否擴張。** diff --git a/docs/index.zh-TW.md b/docs/index.zh-TW.md new file mode 100644 index 0000000..5b100af --- /dev/null +++ b/docs/index.zh-TW.md @@ -0,0 +1,77 @@ +# Token 最佳化指南 + +[English](index.md) | [繁體中文（台灣）](index.zh-TW.md) + +實務導向的 GitHub Copilot token 成本降低指南，同時維持回答與程式碼的實用性。 + +[從 Part 1 開始](01-why-tokens-matter.zh-TW.md){ .md-button .md-button--primary } +[直接看實際設定](10-practical-setup.zh-TW.md){ .md-button } + +## 這份指南涵蓋什麼 + +- 為什麼在 Usage-Based Billing 下，token 真的會影響成本 +- 為什麼輸出控制通常比 prompt 壓縮更有直接 ROI +- 如何縮小 always-on context、歷史訊息與工具負擔 +- 為什麼依模型調整 prompt guide 能提升第一次回答品質並減少返工 +- Ask、Edit、Agent Mode 分別何時最划算 +- 如何建立企業治理，而不是依賴未被官方支援的控制方式 +- 如何把這些做法變成可重複的團隊習慣 + +## 最快見效的做法 + +1. 預設限制輸出：`Code only, no explanation.` 與 `No explanations unless asked.` +2. 讓 `.github/copilot-instructions.md` 保持小而精準。 +3. 不需要工具的問題就用 Ask Mode。 +4. 依目標模型的官方指南重調 prompts 與 instructions。 +5. 停用沒在用的 MCP servers。 +6. 先把 DOCX／PDF／Office／媒體輸入轉成 Markdown 再做 AI 工作；優先試 [MarkItDown](https://github.com/microsoft/markitdown)。 +7. 稽核長時間 agent sessions 與重複來回澄清。 +8. 安裝 [RTK](https://github.com/rtk-ai/rtk)，壓縮 shell 指令輸出。 + +## 依主題閱讀 + +### Foundations + +- [Why Tokens Matter](01-why-tokens-matter.zh-TW.md) +- [Comparisons & Data](09-comparisons-data.zh-TW.md) + +### Techniques + +- [Context Management](04-context-management.zh-TW.md) +- [Output Control](05-output-control.zh-TW.md) +- [Workflow Optimization](06-workflow-optimization.zh-TW.md) +- [MCP & Tool Costs](08-mcp-tool-costs.zh-TW.md) + +### Implementation + +- [Practical Setup](10-practical-setup.zh-TW.md) +- [Model Selection & Pricing](11-models-and-pricing.zh-TW.md) +- [Enterprise Governance](12-enterprise-governance.zh-TW.md) + +## 快速詞彙 + +- **UBB**：usage-based billing。Copilot Business 與 Enterprise 的花費會透過 AI credit 用量計算。 +- **AI credits**：切換後的共用計費單位。 +- **Auto mode**：Copilot 預設模型選擇器。多數情境下是合理的預設通道。 +- **Ask Mode**：單次互動。最省成本。 +- **Agent Mode**：多步驟互動。槓桿高，但成本也高。 +- **Content Exclusion**：管理員用來讓特定 repo 內容不進 Copilot context 的控制項。 +- **格式稅**：DOCX、PDF、HTML、投影片、試算表、圖片、音訊／影片抽取內容中，多出來的版面、標記與中繼資料 token。先轉成 Markdown。 + +## 實用連結 + +- [Official GitHub Copilot docs](https://docs.github.com/copilot) +- [Usage-based billing for organizations and enterprises](https://docs.github.com/en/copilot/concepts/billing/usage-based-billing-for-organizations-and-enterprises) +- [OpenAI Tokenizer](https://platform.openai.com/tokenizer) +- [Awesome GitHub Copilot Customizations](https://github.com/github/awesome-copilot-customizations) +- [LLMLingua](https://github.com/microsoft/LLMLingua) +- [Caveman project](https://github.com/JuliusBrussee/caveman) +- [RTK — Rust Token Killer](https://github.com/rtk-ai/rtk) +- [Microsoft MarkItDown](https://github.com/microsoft/markitdown) — 把 PDF、Office 檔、圖片、音訊、HTML、ZIP 內容、YouTube URL、EPUB 等轉成適合 LLM 工作流的 Markdown +- [Marc Bara：Your .docx Is Wasting 33% of Your AI Budget](https://medium.com/@marc.bara.iniesta/your-docx-is-wasting-33-of-your-ai-budget-86a3d229d042) +- [Dina Berry：How I Cut Token Usage from 52% to 13%](https://dfberry.github.io/2026-05-06-tuning-up-copilot-context) + +## 備註 + +- 完整 `/chronicle` 是 **Copilot CLI** 功能；`/chronicle:tips` 也可在 **VS Code** 使用。 +- 本 repo 中的 Usage-Based Billing 縮寫為 **UBB**。 diff --git a/slides/index.zh-TW.html b/slides/index.zh-TW.html new file mode 100644 index 0000000..0dfa4a2 --- /dev/null +++ b/slides/index.zh-TW.html @@ -0,0 +1,1824 @@ + + + + + + GitHub Copilot Token 最佳化 - 8 小時工作坊 + + + + + + + +
+
+
+

8 小時客戶工作坊

+

GitHub Copilot Token 最佳化

+

花更少 token。維持品質。建立企業級護欄。

+

根據 repo 指南內容產生的 Reveal.js 投影片。

+ +
+ +
+

工作坊成果

+
+
+

說明成本

+

輸入、輸出、快取 token、agent 迴圈、MCP schema、模型分流。

+
+
+

改變行為

+

Prompt 壓縮、輸出控制、context 衛生、Ask/Edit/Agent 分流。

+
+
+

交付推行計畫

+

企業預算、模型政策、指令範圍、每月檢討循環。

+
+
+
+ +
+

重要前提

+
+ 這份簡報是根據此 repo 中的實務指引整理而成，不是 GitHub 或 Microsoft 的官方指引。 +
+

受支援的功能行為、計費控制與管理員政策，請參考 docs.github.com/copilot。

+
+ +
+

8 小時議程

+ + + + + + + + + + + + + + +
時間區塊產出
00:00-00:30為什麼 token 很重要 + 快速見效做法共同成本模型
00:30-02:00Prompt、語言、輸出實驗精簡 prompt 範本
02:00-03:15Context + 常駐檔案指令修剪 diff
03:15-04:15工作流程 + 模式模式分流速查表
04:15-05:15MCP／工具成本 + 資料MCP 稽核清單
05:15-06:15實務設定Repo 設定檢查清單
06:15-07:30模型／定價 + 治理客戶管理端推行方案
07:30-08:00收尾統整30 天 token 計畫
+
+ +
+

導覽方式

+

水平 = 章節。垂直 = 章節投影片 + 實驗。

+

按 Esc 可看總覽。按 S 可看講者備註。

+
+ +
+
+

快速開始

+

現在立刻要做的 12 件事

+

先從輸出下手，再縮小結構性輸入，最後再分流模型與工具。

+
+ +
+

最快見效的做法

+
    +
  1. 只回程式碼：每個 token 的 ROI 最高。
    2. +
  2. 限制格式：條列、單句、JSON、表格。
    3. +
  3. 縮小常駐 context：指令檔與 agent 檔案。
    4. +
  4. 預設使用 Auto：只有在有正當理由時才釘選 premium。
    5. +
  5. 簡單問題用 Ask Mode。
    6. +
+
+ +
+

更多快速見效做法

+
    +
  1. 用 applyTo 限定 context 範圍。
    2. +
  2. 寫精準的 prompt：目標檔案、函式、完成條件。
    3. +
  3. 依目標模型重新調整 prompt。
    4. +
  4. 稽核 MCP servers。
    5. +
  5. 把 DOCX／PDF／HTML 等富格式檔先轉成 Markdown。
    6. +
  6. 在 Copilot CLI 執行 /chronicle improve。
    7. +
  7. 長串 CLI 工具鏈可試試 CodeAct。
    8. +
+
+ +
+

優先順序堆疊

+
+
+

先管輸出

+

冗長回答很昂貴。一條預設指令就會影響每一次回應。

+
+
+

第二是常駐內容

+

指令檔與工具 schema 會重複載入。基線再小，累積起來也很可觀。

+
+
+

第三是模式

+

問題用 Ask。單檔修改用 Edit。多步驟工作用 Agent。

+
+
+

第四是治理

+

預算能封頂支出。模型政策能限制昂貴路徑。

+
+
+
+ +
+

Lab 0：建立你的習慣基準

+
+

目標

+

在學技巧之前，先找出你最主要的 3 個 token 漏點。

+

請做：把每項標成綠／黃／紅：輸出冗長度、指令大小、開啟的分頁、Agent 使用、MCP 數量、模型釘選、過長聊天歷史。

+

交付物：個人基準 + 一個「今天就修」的行動。

+

時間：10 分鐘。

+
+
+
+ +
+
+

第 1 部分

+

為什麼 token 很重要

+

Token 影響的是成本、速度、限制，還有 context 容量。

+
+ +
+

Token 是子詞

+
+
+

BPE 行為

+
    +
  • 常見字詞可能只占一個 token。
    • +
  • 罕見字詞會被拆成多個片段。
    • +
  • 標點與贅詞也都會計入。
    • +
+
+
+

核心觀念

+

Sure, I'd be happy to help! 這種話大約就會燒掉 10 個 token，卻沒有任何技術價值。

+
+
+
+ +
+

成本模型

+ + + + + + + +
類別包含內容控制桿
輸入Prompt、context、檔案、歷史、工具限縮範圍並壓縮
快取穩定且重複使用的前綴讓穩定 context 保持穩定
輸出模型回應只回程式碼、精簡格式
+

在供應商定價範例中，輸出 token 的成本通常明顯高於輸入 token。

+
+ +
+

輸入比你的 prompt 更大

+ 
Context window
+├─ System prompt
+├─ copilot-instructions.md / AGENTS.md
+├─ 檔案 context 與開啟的分頁
+├─ 對話歷史
+├─ MCP tool schemas
+└─ 你輸入的 prompt
+

你那個 20 個字的 prompt，可能只是包在數千個隱藏 token 裡面而已。

+
+ +
+

Coding Agent 放大效應

+

一次從 Issue 到 PR 的完整流程，不只是送出一個請求。

+
+
+

Agent 步驟

+

規劃、搜尋、讀檔、編輯、跑測試、檢查失敗、重試。

+
+
+

疊加效應

+

每一步都會重新載入基線 context，還會加上前一步的工具結果。

+
+
+
+ +
+

Lab 1：token 結構解析

+
+

目標

+

把看得到的 prompt 和隱藏的 context 分開來看。

+

請做：選一個最近的 Copilot 任務。列出可能的 context 來源：開啟的檔案、被參照的檔案、指令、歷史、工具、輸出。

+

討論：哪個來源最容易控制？

+

時間：15 分鐘。

+
+
+
+ +
+
+

第 2.1 部分

+

Prompt 壓縮

+

用更少 token 表達同一件事，同時保留技術精準度。

+
+ +
+

原始人寫法

+
+
+

刪掉

+

冠詞、贅詞、客套話、保留語氣、緩和詞。

+
+
+

保留

+

技術術語、程式碼、檔名、限制條件、精確完成條件。

+
+
+

[thing] [action] [reason]. [next step].

+
+ +
+

前後對照

+ + + + + + + + + + + + +
冗長版原始人版
Could you please review this pull request and let me know if there are any issues?Review PR. Flag issues.
Can you explain what this error message means and how I should fix it?Explain error. How fix.
+
+ +
+

壓縮等級

+ + + + + + + +
等級風格適用時機
Lite專業但精簡對外簡報、新人上手
Full片語式、零廢話日常開發者 prompt
Ultra縮寫、箭頭、極短高頻、熟悉領域
+
+ +
+

結構化勝過散文式描述

+ 
POST /api/users
+驗證：
+- name: string，必填
+- email: string，必填，格式有效
+驗證失敗回 400
+成功回 201，回傳建立後的 user
+存入 DB
+

條列與 key-value 會強迫內容更清楚，也能減少贅字。

+
+ +
+

以程式碼為中心的 prompting

+
+
+

自然語言

+

建立一個函式，接收數字、濾掉負值、把剩下的值乘二，最後回傳總和。

+
+
+

以程式碼為中心

+

fn(nums) -> filter(>0) -> map(*2) -> sum

+

Like getUserById but for emails. 404 if missing.

+
+
+
+ +
+

把護欄寫成不變條件

+ + + + + + +
冗長程序壓縮後的不變條件
Make sure every SQL query parameterizes values...SQL: parameterized queries only. No concatenation.
Please write tests for any new code...New code -> tests. Cover happy + error.
+
+ +
+

Lab 2：prompt 壓縮梯度

+
+

目標

+

把一個真實 prompt 改寫成三種版本：lite、full、ultra。

+

請做：保留檔名、行號、限制條件與完成條件，只刪掉廢話。

+

比較：哪個版本最短，同時又不會增加歧義？

+

時間：20 分鐘。

+
+
+ +
+

Lab 3：prompt A/B

+
+

試試這個 vs 那個

+ 
A: Could you take a look at auth and improve error handling?
+
+B: File: src/auth/login.ts.
+Bug: null user causes .email crash.
+Fix: null guard before .email.
+Test: add null-user case.
+Done: targeted test passes.
+

執行：先用 A，再用 B 問 Copilot。比較讀了哪些檔案、提出多少澄清、輸出長度如何。

+
+
+
+ +
+
+

第 2.2 部分

+

語言比較

+

在 prompt 上，英文通常是 token 效率最高的語言。

+
+ +
+

CJK 假設失靈

+ + + + + + + + + +
語言句子Tokens相對英文
EnglishI met a huge dog51.0x
SpanishConoci a un perro enorme81.6x
Chinese中文對應句112.2x
Japanese日文對應句112.2x
Russian俄文對應句142.8x
+
+ +
+

原因

+
    +
  • BPE tokenizer 主要是以英文資料大量訓練。
    • +
  • 常見英文單字常常只會對應一個 token。
    • +
  • CJK 文字雖然字數較少，但平均每個字的 token 可能更多。
    • +
  • 非拉丁文字通常成本更高；音譯有時會有幫助。
    • +
+
+ +
+

實務規則

+
+ Prompt 和指令請優先使用精簡英文。不要為了省 token 而翻成 CJK。 +
+

如果使用者用母語表達得更清楚，品質有時會比 token 成本更重要。但以最佳化來說，英文通常更有優勢。

+
+ +
+

Lab 4：tokenizer 現實檢查

+
+

目標

+

用實際 token 數，推翻或驗證語言直覺。

+

請做：選一個 prompt，翻成你最擅長的非英文語言，然後在 tokenizer 工具裡比較 token 數。

+

交付物：團隊語言指引：哪些情況必須用英文，哪些情況可接受使用母語。

+

時間：20 分鐘。

+
+
+
+ +
+
+

第 2.3 部分

+

Context 管理

+

控制真正送出去的內容。最大的輸入節省通常來自結構面。

+
+ +
+

常駐檔案每一輪都會產生成本

+

.github/copilot-instructions.md、AGENTS.md、CLAUDE.md 以及類似檔案，都可能成為持續存在的 context。

+

如果相同內容出現在多個檔案，而不同工具又都會載入它們，你可能會重複付費兩次。

+
+ +
+

指令壓縮範例

+ 
精簡像原始人。技術內容要精確。只讓廢話消失。
+刪掉：冠詞、贅詞（just/really/basically）、客套語、保留語氣。
+片語可接受。用短同義詞。程式碼不要改。
+模式：[thing] [action] [reason]. [next step].
+

大約 50 個 token，但會在每次互動都被載入。

+
+ +
+

Context 衛生

+
    +
  • 關閉與當前任務無關的檔案。
    • +
  • 讓檔案聚焦且小而精。
    • +
  • 忽略 build 輸出、vendor 目錄、產生檔。
    • +
  • 把富格式輸入先轉成 Markdown，避開格式稅。
    • +
  • 在 Business／Enterprise 使用 Content Exclusion 處理敏感路徑。
    • +
  • 換主題後開新對話。
    • +
+
+ +
+

富格式輸入先轉 Markdown

+
+
+

為什麼

+

DOCX、PDF、HTML、投影片、試算表、圖片與音訊，常夾帶版面與中繼資料雜訊。模型得多吃一堆沒用 token。

+
+
+

怎麼做

+

先用 Microsoft MarkItDown 轉成 Markdown，再拿 Markdown 給 Copilot、agent 或 RAG。

+
+
+

Marc Bara 的格式稅案例裡，同內容從 PDF 轉成乾淨 Markdown，輸入 token 約少 33%。

+
+ +
+

使用範圍化指令

+ 
---
+applyTo: "src/api/**/*.ts"
+---
+API 慣例：
+- Routes 放在 src/api/routes/。Handler 保持精簡，邏輯放在 services/。
+- 用 zod 驗證。
+- 錯誤透過 Result<T,E>，不要直接 throw。
+

只有當相關檔案真的進入範圍時，才支付這些路徑專屬指引的成本。

+
+ +
+

常駐 vs 條件式 vs 隨選

+ + + + + + + +
範圍用途Token 姿態
常駐通用規則保持極小
條件式路徑／分層規則applyTo
隨選審查清單、版本發佈說明只在呼叫時載入
+
+ +
+

快取友善行為

+
    +
  • 把穩定的 context 放在最上方。
    • +
  • 不要一直頻繁改動指令檔。
    • +
  • 用已儲存的片段，避免重貼大量 context。
    • +
  • 當歷史內容過期時，先摘要再重開對話。
    • +
+
+ +
+

企業版提醒：Content Exclusion

+
+

客戶端動作

+

為敏感檔案、產生的 bundle、大型資料檔，以及受規範的路徑設定 Content Exclusion。

+

重要：先把它視為隱私／政策控制，其次才是節省 token 的附帶效果。請以官方文件確認目前支援面。

+
+
+ +
+

Lab 5：context 稽核

+
+

目標

+

找出哪些常駐 context 應該改成範圍化或隨選。

+

請做：檢查 repo 指令、AGENTS／CLAUDE 檔案、開啟的分頁、產生檔、MCP 設定。

+

交付物：三欄清單：保留常駐、移到 applyTo、移成隨選／刪除。

+

時間：30 分鐘。

+
+
+
+ +
+
+

第 2.4 部分

+

輸出控制

+

告訴模型哪些話不用說。每個 token 的 ROI 在這裡最高。

+
+ +
+

預設一句話

+ 
Code only, no explanation.
+

最適合生成任務，而且團隊已知道想要什麼改動時使用。

+
+ +
+

格式限制

+ + + + + + + + + +
指令適用時機
用一句話回答快速決策或說明
最多 3 個 bullet方便掃讀的摘要
回覆為 JSON機器可讀的擷取結果
先回答 yes/no，再用一行說明原因審查關卡
只顯示 diffPatch 檢視
+
+ +
+

專案預設

+ 
保持精簡。除非被要求，否則不要解釋。
+生成任務只輸出程式碼。
+優先用條列，不要寫段落。
+

若是學習、除錯或教學情境，可覆寫：明確要求提供說明即可。

+
+ +
+

Lab 6：輸出 A/B

+
+

試試這個 vs 那個

+ 
A: Add input validation to processOrder().
+
+B: Add input validation to processOrder().
+Code only. No explanation. Minimal diff.
+

量測：回應長度、解釋所花的 token、diff 的實用性。

+

時間：15 分鐘。

+
+
+ +
+

Lab 7：強制格式

+
+

目標

+

練習要求有界限的輸出。

+

Prompts：「最多 3 個 bullet」、「只要表格」、「只要 JSON」、「單行結論 + 風險」。

+

交付物：團隊常用 Copilot 輸出片段庫。

+
+
+
+ +
+
+

第 2.5 部分

+

工作流程最佳化

+

先選對互動形態，再來優化措辭——形態選對，省的更多。

+
+ +
+

Commit 與 PR 文字很重要

+
+
+

Commit

+

feat: add password reset via settings page

+

只有在「為什麼」不明顯時才加 body。

+
+
+

Review

+

L42: bug: user can be null. Add guard before .email.

+

一行、可執行、帶嚴重度標記。

+
+
+
+ +
+

Ask vs Edit vs Agent

+ + + + + + + + + +
任務模式原因
這個 function 是做什麼的？Ask只需一次呼叫
語法問題Ask不需工具
單檔微調Edit目標明確
多檔重構Agent需要工具
Issue-to-PRCoding Agent自動化工作流程
+
+ +
+

Auto 模型預設

+

Auto 是不錯的基線：使用受支援的 Auto pool，會遵守 org policy，且依文件說明，符合資格的付費方案 Chat 使用可能有折扣。

+

Auto 不代表「會自動升級到所有 premium 模型」。釘選 premium 要有意識地進行。

+
+ +
+

模型變更時重新調整 prompt

+ 
目標模型：GPT-5.5。
+指南：<official prompting guide URL>
+檔案：.github/copilot-instructions.md、.github/instructions/*.md
+依指南調整 prompt。保留行為。降低重工。
+只顯示 diff。
+
+ +
+

什麼情況不該壓縮

+
    +
  • 安全警告。
    • +
  • 不可逆操作。
    • +
  • Onboarding 與教學。
    • +
  • 法規／合規文字。
    • +
  • 片語寫法會增加歧義的複雜指令。
    • +
+
+ +
+

用使用指導完成閉環

+
+
+

/chronicle

+

Copilot CLI 的 session 歷史。若持續出現同樣混亂，可用 /chronicle improve。

+
+
+

AI Engineering Coach

+

VS Code 本機 extension。可找出反模式、context 健康狀況與技能使用機會。

+
+
+
+ +
+

Lab 8：模式分流演練

+
+

目標

+

不要再把一次性工作都丟進 Agent Mode。

+

請做：把 20 個範例任務分類成 Ask／Edit／Agent／Coding Agent，並說明理由。

+

交付物：團隊模式分流速查表。

+

時間：20 分鐘。

+
+
+ +
+

Lab 9：模型分流演練

+
+

目標

+

避免把昂貴模型預設釘選在整天工作流中。

+

請做：把任務分配到 Auto、included／較低成本、standard、premium。如果支援，也請納入 reasoning-effort 的選擇。

+

交付物：模型升級規則。

+
+
+
+ +
+
+

第 2.6 部分

+

常駐 context 問題

+

更多 context 可能讓 agent 表現更差，也更昂貴。

+
+ +
+

研究訊號

+ + + + + + + + +
發現觀察到的影響
LLM 產生的 context 檔案在 8 種設定中的 5 種造成負面影響
平均正確率下降約 2%
Token 成本增加 20-23%
推理開銷在引用設定中增加約 22%
+
+ +
+

為什麼 context 會有害

+
+

冗餘稅

重複 agent 其實可以自己發現的事實。

+

注意力稅

重要規則埋在中間而被忽略。

+

錨定陷阱

過時的工具指引會過度影響 agent。

+

訊號／雜訊問題

例行資訊稀釋了真正的地雷。

+
+
+ +
+

只保留地雷

+ + + + + + + + +
保留刪除
用 uv 不要用 pip這是一個 Python 專案
DB migration 必須依序執行我們使用 PostgreSQL
不要重構 auth 模組；稽核尚未完成我們使用 JWT auth
部署需要 VPNMain branch 有保護
+
+ +
+

Bug 追蹤器模型

+ 
一開始幾乎留空。
+Agent 在某處跌倒 -> 補上一行。
+根因修好 -> 刪掉那一行。
+

指令檔應該會長、也會縮，不要像 wiki 一樣只會一直累積。

+
+ +
+

Lab 10：地雷修剪

+
+

目標

+

在不犧牲正確性的前提下縮減 context。

+

請做：把每條指令標記為可發現、風格、地雷、過時、重複。除了真正的常駐地雷外，其餘全部刪除或範圍化。

+

交付物：最多 10 行的指令檔草稿。

+

時間：35 分鐘。

+
+
+
+ +
+
+

第 2.7 部分

+

MCP 與工具成本

+

工具 schema 是隱藏的 token 稅。

+
+ +
+

先量測

+ 
/context
+
+System/Tools: MCPs + instructions + system prompt
+Messages: conversation history
+Free Space: 剩餘 context 空間
+

在 VS Code 中，可先粗估：啟用中的 MCP servers × 工具數 × 約 200 tokens／tool。

+
+ +
+

每個工具都會消耗 token

+ + + + + + + + +
元件約略成本
名稱 + 描述20-50 tokens
簡單參數 schema30-80 tokens
複雜參數 schema100-300 tokens
每個工具總計100-500 tokens
+
+ +
+

乘法問題

+ 
10 個 MCP servers
+x 每個 5 個工具
+x 每個工具 200 tokens
+= 每一步 10,000 tokens
+
+15 個 agent 步驟 = 150,000 個 schema tokens
+
+ +
+

稽核規則

+
    +
  • 停用目前不需要的 server。
    • +
  • 用 workspace 級設定，不要全域全開。
    • +
  • 優先使用內建工具，不要重複啟用檔案系統類 MCP。
    • +
  • 偶爾才需要的能力，優先用 skills。
    • +
  • 若支援，請按 namespace／mode 縮小大型外掛範圍。
    • +
+
+ +
+

工具輸出壓縮

+
+

RTK

+

CLI proxy 會在 agent 讀取前先過濾吵雜的 shell 輸出：測試、git diff、grep、logs、檔案清單。

+ 
rtk init --copilot
+
+
+ +
+

Azure MCP 案例模式

+

一個大型外掛就可能主導整個 System/Tools 預算。

+ 
--namespace appservice --namespace cosmos --namespace keyvault --namespace storage
+

依服務／角色縮小範圍。除非真的需要，否則避免「all tools」模式。

+
+ +
+

Lab 11：MCP 稽核

+
+

目標

+

移除隱藏的 schema 開銷。

+

請做：盤點已啟用的 MCP servers、工具數量、global vs workspace 範圍、負責人、使用頻率。

+

交付物：保留／停用／範圍化表格 + 重啟計畫。

+

時間：30 分鐘。

+
+
+ +
+

企業版實驗：工具政策

+
+

客戶端動作

+

依 persona 定義核准的 MCP servers：developer、data、platform、security、support。

+

交付物：各團隊預設 MCP profile + 大型外掛的例外流程。

+
+
+
+ +
+
+

第 3 部分

+

比較與資料

+

用數據找出投入產出比最高的習慣，再決定先做哪個。

+
+ +
+

同一任務，不同成本

+ + + + + + + + +
技巧PromptTokens
VerbosePlease add comprehensive error handling...~40
Caveman liteAdd error handling. Cover null, types, network.~16
Caveman fullError handling. Cover: null, bad type, net error.~12
UltraError handling: null/bad-type/net-err.~7
+
+ +
+

最大贏家

+
    +
  1. 原始人寫法 + 精準 prompt。
    2. +
  2. 只回程式碼／限制輸出格式。
    3. +
  3. 縮小常駐 context。
    4. +
  4. 簡單問題用 Ask Mode。
    5. +
  5. 先把富格式檔轉成 Markdown。
    6. +
  6. 稽核 MCP servers。
    7. +
  7. 模型變更後重新調整 prompt。
    8. +
+
+ +
+

品質曲線

+ 
節省：  lite ---- full ---- ultra ---- extreme
+風險：  低  ---- 低  ---- 中  --- 高
+

甜蜜點：full caveman。對技術使用者來說，回報最高，風險幾乎可忽略。

+
+ +
+

Lab 12：技術優先排序

+
+

目標

+

依影響、成本、風險挑選變更。

+

請做：為每項技巧在 impact、effort、adoption friction、governance need 上各打 1-5 分。

+

交付物：團隊前 5 名，以及「不要採用」清單。

+

時間：25 分鐘。

+
+
+
+ +
+
+

第 4 部分

+

實務設定

+

把技巧變成 repo 與團隊的預設。

+
+ +
+

Repo 設定步驟

+
    +
  1. 建立壓縮版 .github/copilot-instructions.md。
    2. +
  2. 加入壓縮後的專案專屬規則。
    3. +
  3. 用 applyTo 拆出路徑專屬指引。
    4. +
  4. 預設使用 Auto；只有在有理由時才釘選。
    5. +
  5. 為 Coding Agent 加上 copilot-setup-steps.yml。
    6. +
  6. 把 DOCX／PDF／HTML 等輸入先轉成 Markdown。
    7. +
+
+ +
+

起始指令範本

+ 
精簡像原始人。技術內容要精確。只讓廢話消失。
+刪掉：冠詞、贅詞、客套語、保留語氣。
+片語可接受。用短同義詞。程式碼不要改。
+生成任務只輸出程式碼。除非被要求，否則不要解釋。
+盡量減少工具呼叫。相關讀取／編輯要批次處理。
+
+ +
+

Coding Agent 設定

+ 
# .github/copilot-setup-steps.yml
+steps:
+  - name: 安裝相依套件
+    run: npm ci
+  - name: 建置
+    run: npm run build
+

避免靠 trial and error 來摸索，能節省 agent 步驟。

+
+ +
+

實務步驟：先轉成 Markdown

+ 
pip install 'markitdown[all]'
+
+markitdown report.docx -o report.md
+markitdown slides.pptx -o slides.md
+markitdown source.pdf > source.md
+

工作格式用 Markdown。最後交付再回產出 `.docx`／`.pdf`。

+
+ +
+

精準 issue 範本

+ 
錯誤：當 email 包含 "+" 時，登入失敗。
+檔案：src/auth/login.ts，validateEmail() L42。
+修正：呼叫 OAuth provider 前先對 email 做 URL encode。
+測試：新增 user+tag@example.com 案例。
+完成：目標測試通過。
+
+ +
+

用 4 週建立習慣

+ + + + + + + + +
週次習慣
1壓縮指令 + 問題改用 Ask Mode
2Caveman-lite prompts
3Caveman-full + 結構化格式
4只回程式碼的預設 + 把可重用片段放在常駐 context 之外
+
+ +
+

Agent 模式控制

+ 
{
+  "chat.agent.maxRequests": 10,
+  "github.copilot.chat.agent.model": "auto"
+}
+

要小心限制暴衝 session。只有任務真的需要時才往上調。

+
+ +
+

Lab 13：repo 實作

+
+

目標

+

建立可直接套用到 repo 的 token 最佳化 PR 草稿。

+

請做：起草 copilot-instructions.md、一個範圍化指令檔、一個 Coding Agent setup step、一個 issue template 片段。

+

交付物：branch 或 patch 提案。

+

時間：45 分鐘。

+
+
+
+ +
+
+

第 4.2 部分

+

模型選擇與定價

+

把 Copilot 文件、UBB 架構，以及供應商 token 定價分開看。

+
+ +
+

三種定價視角

+ + + + + + + +
視角回答什麼
GitHub Copilot 文件方案可用性、模型存取、Auto 行為、已公開訊號
UBB 架構切換後的 AI-credit 預算與治理
供應商 API 定價輸入 vs 輸出的成本直覺，不是 Copilot 計費表
+
+ +
+

Auto：實務上的意義

+
    +
  • 會從受支援的 Auto pool 中挑選。
    • +
  • 受方案與 org policy 限制。
    • +
  • 依健康度與效能決定。
    • +
  • 符合資格的付費方案 Chat 使用有折扣。
    • +
  • 不會自動升級到所有 premium 模型。
    • +
+
+ +
+

推理 effort

+ + + + + + + +
Effort適用情境
Low高流量的簡單 chat／分類
Medium一般程式撰寫與工具密集型工作（若支援）
High/max架構、安全、全新拆解問題
+

只在有提供此控制的模型上使用。

+
+ +
+

反模式

+
    +
  • 整天都把 premium model 釘住。
    • +
  • 以為任務變難時 Auto 會自動跳到 premium。
    • +
  • 把供應商 API 定價和 Copilot 計費混為一談。
    • +
  • 一開始就對整個 org 啟用所有 premium 模型。
    • +
  • 忽略方案／模型可用性。
    • +
+
+ +
+

Lab 14：模型升級政策

+
+

客戶端動作

+

定義使用者何時可以釘選 premium 模型，以及何時必須使用 Auto。

+

請做：把工作流程對應到預設模型路徑、升級觸發條件、預期價值、回滾訊號。

+

交付物：一頁式模型政策草稿。

+

時間：30 分鐘。

+
+
+
+ +
+
+

第 4.3 部分

+

企業治理

+

管理控制負責封頂支出；prompt 習慣負責降低上限內的浪費。

+
+ +
+

支出控制桿

+
    +
  1. 預算上限。
    2. +
  2. 使用者層級 AI-credit 預算。
    3. +
  3. 模型可用性政策。
    4. +
+

Prompt 壓縮不能封頂支出；它只是降低已允許使用範圍內的浪費。

+
+ +
+

先設定預算

+
+

客戶端動作

+

設定 enterprise／org／cost center 預算。提早開啟警示。待報表可信後，再啟用 stop-usage。每月檢討。

+
+
+ +
+

使用者層級收緊

+
    +
  • 基線使用者：較低 AI-credit 預算。
    • +
  • 重度使用者：因工作需要給較高預算。
    • +
  • $0 預算：無法使用計量型功能。
    • +
  • 每月檢查，將未使用的配額下調。
    • +
+
+ +
+

啟用前先檢視模型

+ + + + + + + + +
問題決策
哪些工作流程需要 premium？精準啟用
哪些團隊能創造可衡量價值？配置較高預算
哪些使用者可以留在 Auto？讓預設路徑維持低成本
回滾訊號是什麼？使用量上升、價值持平
+
+ +
+

指令範圍治理

+
    +
  • Org 指令：較廣泛的 GitHub.com 政策與 review 提醒。
    • +
  • Repo 指令：IDE 工作流程預設與程式規則。
    • +
  • 路徑專屬指令：只有在局部 context 值得時才放。
    • +
  • 不要假設 org 指令會套用到所有地方；請查官方文件。
    • +
+
+ +
+

分開的 org：只作為備案

+

當既有組織結構本來就對應不同模型政策或計費邊界時，才比較有用。

+

成本：管理負擔、授權複雜度、使用者分散、SCIM／cost-center 限制。

+
+ +
+

衡量正確的事情

+
    +
  1. 哪些團隊超出基線？
    2. +
  2. 哪些使用者驅動了 AI-credit 使用量？
    3. +
  3. 哪些模型真的改善成果？
    4. +
  4. 哪些 agent 工作流程花了錢卻沒有交付價值？
    5. +
+
+ +
+

6 月 1 日切換檢查清單

+
    +
  1. 從 request 計數轉成 AI-credit 預算。
    2. +
  2. 決定採用 pooled 還是 user-level 預算。
    3. +
  3. 在 premium 變成直接支出之前，先檢視模型可用性。
    4. +
  4. 提醒團隊：completions／next edits 仍不在 AI-credit 計費範圍內。
    5. +
  5. 先觀察長對話與 agent 工作流程。
    6. +
+
+ +
+

Lab 15：預算推行

+
+

客戶端動作

+

為一個 enterprise 帳戶設計預算推行方案。

+

請做：選定試點 org、cost center、基線預算、警示門檻、stop-usage 規則、使用者例外。

+

交付物：預算營運模型。

+

時間：35 分鐘。

+
+
+ +
+

Lab 16：治理桌上演練

+
+

情境

+

某團隊的 agent session 讓 AI-credit 使用量暴增 4 倍，但交付成果沒有變化。

+

請決定：預算動作、模型政策動作、指令／context 動作、MCP 稽核動作、溝通計畫。

+

時間：25 分鐘。

+
+
+
+ +
+
+

收尾統整

+

30 天 token 最佳化計畫

+

把工作坊所學轉化成可交付的客戶推行方案。

+
+ +
+

逐週推行

+ + + + + + + + +
週次團隊動作管理端動作
1輸出預設 + Ask Mode建立使用基線
2修剪指令 + 範圍化規則預算試點
3MCP 稽核 + 模型分流檢視模型存取政策
4Agent issue 範本 + setup steps建立每月報告節奏
+
+ +
+

收尾統整實作

+
+

目標

+

建立客戶專屬行動計畫。

+

章節：repo 變更、使用者習慣、MCP／工具政策、模型政策、預算、報告、負責人、到期日。

+

交付物：可直接交給客戶 sponsor 的 30 天計畫。

+

時間：30 分鐘。

+
+
+ +
+

最終檢查清單

+
+
+

開發者

+
    +
  • 預設只回程式碼
    • +
  • Ask/Edit/Agent 分流
    • +
  • 精簡 prompts
    • +
  • 適時開新 session
    • +
+
+
+

程式碼庫

+
    +
  • 極小的常駐指令
    • +
  • 範圍化的 applyTo 檔案
    • +
  • Coding Agent setup steps
    • +
  • 精準的 issue 範本
    • +
+
+
+

平台

+
    +
  • MCP profiles
    • +
  • Content Exclusion
    • +
  • 模型存取政策
    • +
  • RTK／CLI 工具輸出策略
    • +
+
+
+

企業

+
    +
  • 預算
    • +
  • 使用者層級上限
    • +
  • 使用量報表
    • +
  • 每月檢討
    • +
+
+
+
+ +
+

結語

+
+ 先從便宜的預設開始。Premium 存取採例外制。先量測，再擴張。 +
+
+
+
+
+ + + + + + + +