From 8d217421866d7309725075bc15652976c75b9be2 Mon Sep 17 00:00:00 2001 From: Jamestsai Date: Sun, 7 Jun 2026 18:42:39 +0800 Subject: [PATCH 1/7] Add zh-TW README and linked documentation --- README.md | 2 + README.zh-TW.md | 135 ++++++++++++++ docs/01-why-tokens-matter.zh-TW.md | 91 +++++++++ docs/02-prompt-compression.zh-TW.md | 214 +++++++++++++++++++++ docs/03-language-comparison.zh-TW.md | 94 ++++++++++ docs/04-context-management.zh-TW.md | 127 +++++++++++++ docs/05-output-control.zh-TW.md | 61 ++++++ docs/06-workflow-optimization.zh-TW.md | 145 +++++++++++++++ docs/07-agents-md-problem.zh-TW.md | 101 ++++++++++ docs/08-mcp-tool-costs.zh-TW.md | 149 +++++++++++++++ docs/09-comparisons-data.zh-TW.md | 102 ++++++++++ docs/10-practical-setup.zh-TW.md | 248 +++++++++++++++++++++++++ docs/11-models-and-pricing.zh-TW.md | 128 +++++++++++++ docs/12-enterprise-governance.zh-TW.md | 128 +++++++++++++ docs/index.zh-TW.md | 73 ++++++++ 15 files changed, 1798 insertions(+) create mode 100644 README.zh-TW.md create mode 100644 docs/01-why-tokens-matter.zh-TW.md create mode 100644 docs/02-prompt-compression.zh-TW.md create mode 100644 docs/03-language-comparison.zh-TW.md create mode 100644 docs/04-context-management.zh-TW.md create mode 100644 docs/05-output-control.zh-TW.md create mode 100644 docs/06-workflow-optimization.zh-TW.md create mode 100644 docs/07-agents-md-problem.zh-TW.md create mode 100644 docs/08-mcp-tool-costs.zh-TW.md create mode 100644 docs/09-comparisons-data.zh-TW.md create mode 100644 docs/10-practical-setup.zh-TW.md create mode 100644 docs/11-models-and-pricing.zh-TW.md create mode 100644 docs/12-enterprise-governance.zh-TW.md create mode 100644 docs/index.zh-TW.md diff --git a/README.md b/README.md index bdfee06..e476c1d 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..b7926af --- /dev/null +++ b/README.zh-TW.md @@ -0,0 +1,135 @@ +# 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 工作流程。 + +--- + +## 快速開始：現在就該做的 11 件事 + +> **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 | **每週執行 `/chronicle improve`**（**僅限 Copilot CLI**，實驗性功能）：這個 slash command 只能在互動式 Copilot CLI 工作階段中使用，並不是一般 Copilot Chat 功能。它會找出你 CLI 工作階段歷史中反覆出現的誤解，並產生自訂指令，讓同樣的誤判不再持續浪費 token | 降低重複返工 | 每次 2 分鐘 | +| 11 | **長工具鏈任務可考慮 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 成本。 + +--- + +## 指南內容 + +### 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` 限定上下文、關閉未使用的編輯器分頁、設定 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. **依目標模型重調提示詞**：提升第一次輸出的品質，減少來回澄清。 +7. **精準提示詞**：可影響使用者提示詞輸入 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..ce0a27f --- /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，在觸發上限前能發出的請求就越多。 | +| **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。 | + +**複利效應：** 你的輸入 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..b68a28c --- /dev/null +++ b/docs/02-prompt-compression.zh-TW.md @@ -0,0 +1,214 @@ +# 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." +``` + +適合：對外文件、需要完整清晰表達的情境。 + +### Full：經典原始人模式（預設） + +拿掉冠詞，允許片語化，用更短的同義詞。 + +```text +"New object ref each render. Inline object prop = new ref = re-render. +Wrap in useMemo." +``` + +適合：日常開發、多數 Copilot 互動。 + +### Ultra：最大壓縮 + +常見術語直接縮寫，刪掉連接詞，用箭頭表示因果。 + +```text +"Inline obj prop → new ref → re-render. useMemo." +``` + +適合：高頻互動、你對領域非常熟時。 + +| 等級 | 輸入節省 | 輸出節省† | 品質影響 | +|------|----------|-----------|----------| +| 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 +``` + +結構化寫法通常更省，也更清楚。 + +## 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..43e8cea --- /dev/null +++ b/docs/04-context-management.zh-TW.md @@ -0,0 +1,127 @@ +# 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 檔**，讓特定規則只在相關檔案出現時才載入。 +- **Business／Enterprise 環境下**，可請管理員設定 Content Exclusion 做政策與敏感路徑控管。 + +要小心的高風險檔案包括： + +- 大型 README +- 產生檔與打包輸出 +- vendor 目錄 +- CSV／JSON fixture 等資料檔 +- 歷史存檔文件 + +## 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..345572f --- /dev/null +++ b/docs/06-workflow-optimization.zh-TW.md @@ -0,0 +1,145 @@ +# 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 載入次數也會跟著下降 +- 整合後的結果通常比逐步敘述每一步更短 + +## 2.5.4 預設使用 Auto 模型選擇 + +模型選擇器本身就是重要的成本控制介面。把高成本模型長時間釘住，代表連最簡單的互動都會用高費率計價。 + +**正確預設是 Auto。** + +- Auto 會從支援的 Auto pool 中選擇 +- 在付費方案上，符合條件時會套用折扣 +- 它不是「自動幫你升到最貴模型」，高成本 premium 模型通常仍要手動 pin + +只有在你清楚知道任務很簡單或很重，才手動指定模型。 + +## 2.5.5 依目標模型重調 Prompt + +這不是每次都能直接減少單次 token，而是透過提升第一次回答品質，減少補問、修正與 agent 返工。 + +建議流程： + +```text +打開目標模型的官方 prompting guide。 +把網址貼進 Copilot。 +請 Copilot 依這份指南調整你的 instruction / prompt files。 +保留行為不變，但減少錯誤回合與澄清成本。 +``` + +適用時機： + +- 換了預設模型 +- 原本在某模型表現不錯的 prompt，在新模型變得太囉唆、太死板或太積極 +- agent 換模型後開始反覆做同一種錯誤假設 + +## 2.5.6 什麼時候不該壓縮 + +以下情境不要過度壓縮： + +- 安全警告 +- 不可逆操作 +- 新人 onboarding +- 容易因順序或歧義導致誤解的多步驟指令 +- 法規／合規文字 + +## 2.5.7 用 `/chronicle` 關閉回饋迴路 + +Token 浪費不只發生在單一 prompt，也會發生在你沒察覺的重複模式上。 +`/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..c9fa857 --- /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..309c455 --- /dev/null +++ b/docs/08-mcp-tool-costs.zh-TW.md @@ -0,0 +1,149 @@ +# 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** +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。 + +做法通常有兩種： + +- **完全停用**：這個 session 根本不用 Azure +- **namespace 範圍化**：只保留真的有在用的 Azure services + +一般原則很清楚： + +- 當 `System/Tools` 偏高時，先檢查大型 plugins +- 一個大 plugin 的成本，常常比其他所有工具加總還高 + +--- + +**下一章：** [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..80b9be1 --- /dev/null +++ b/docs/09-comparisons-data.zh-TW.md @@ -0,0 +1,102 @@ +# 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 | +| 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. **稽核 MCP servers** +7. **依模型調整 prompts** + +## 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..ccf1378 --- /dev/null +++ b/docs/10-practical-setup.zh-TW.md @@ -0,0 +1,248 @@ +# 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 模型拿去做便宜模型也能正確完成的工作。** + +### Step 6：依實際使用模型重調 Instructions + +換模型時，不要假設舊 prompt stack 還是最佳做法。 +最佳流程： + +```text +把官方 guide 網址貼進 Copilot。 +指定目標模型與要調整的檔案。 +請它在不改變行為的前提下，降低錯誤與返工。 +``` + +### Step 7：把治理控制放在 Prompt 外 + +Prompt 檔只能影響行為，真正的計費控制在別處。 +若你在做組織或企業推動，請直接看 [Enterprise Governance](12-enterprise-governance.zh-TW.md)。 + +## 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 能把這些結果先壓縮再交給 agent。 + +## 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..dc796f1 --- /dev/null +++ b/docs/11-models-and-pricing.zh-TW.md @@ -0,0 +1,128 @@ +# 模型選擇與定價 + +[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 模型的「輸入 token 單價 vs 輸出 token 單價」表。 +但 Anthropic API 定價仍然非常適合拿來理解「輸出遠比輸入貴」這件事。 + +| 模型 | 每百萬輸入 | 每百萬輸出 | +|------|------------|------------| +| Claude Haiku 4.5 | $1 | $5 | +| Claude Sonnet 4.6 | $3 | $15 | +| Claude Opus 4.6 | $5 | $25 | + +這能幫你建立正確直覺： + +- 輸出 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 消耗，再決定是否擴大 + +## 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..306012f --- /dev/null +++ b/docs/12-enterprise-governance.zh-TW.md @@ -0,0 +1,128 @@ +# 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 文件中的重點： + +- 可以在 organization、enterprise 或 cost center 層級設預算 +- 可以設定達到預算時停止使用 +- 也有 user-level budgets +- **使用者預算設為 `$0`** 代表該使用者無法使用 usage-based 功能 + +實務預設： + +1. 先用非零測試預算啟動 rollout +2. 提早開 alerts +3. 觀察報表正常後，再開 stop usage +4. 每月固定檢查，不要等超支才看 + +## 2. 用 User-Level Budgets 做每人收緊 + +對 Business / Enterprise 來說，2026/06/01 之後最乾淨的每人上限，就是 **user-level AI credit budget**。 + +管理思維應轉成： + +- 先看 AI credit 用量 +- 再看模型選擇、聊天深度、agent 時長 + +實務模式： + +1. 一般使用者配低一些的 user-level 預算 +2. 重度使用者只有在工作需要明確時才提高 +3. 每月檢查，價值不明顯的使用者再降回來 + +## 3. 啟用模型前先審查 + +GitHub 支援由 organization 或 enterprise owner 控制成員可用的 AI 模型。 +把這當成**官方支援的模型治理方式**。 + +建議的審查清單： + +1. 哪些 workflow 真的需要 premium 模型 +2. 哪些團隊會產生可量化價值 +3. 哪些使用者維持 Auto 或 included models 就足夠 +4. 啟用後要看哪份 usage report +5. 若成本跳升卻沒有品質收益，要用什麼 rollback 條件 + +## 4. 把 Custom Instructions 放在正確層級 + +GitHub 文件區分： + +- **repository instructions** +- **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。 + +## 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..99bc5c7 --- /dev/null +++ b/docs/index.zh-TW.md @@ -0,0 +1,73 @@ +# 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. 稽核長時間 agent sessions 與重複來回澄清。 +7. 安裝 [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 的控制項。 + +## 實用連結 + +- [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) +- [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**。 From 338da2eef1ee2d610adc43de6782a2219fa3a2aa Mon Sep 17 00:00:00 2001 From: Jamestsai Date: Sun, 7 Jun 2026 21:32:15 +0800 Subject: [PATCH 2/7] Add Traditional Chinese (Taiwan) slide deck MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Translate slides/index.html into Taiwanese Mandarin using the taiwanese-mandarin-translate skill. Terminology follows Taiwan conventions (台灣華語), presenter notes are fully localized, and all presenterNotes JS keys are kept in sync with slide headings. Co-Authored-By: Claude Sonnet 4.6 (1M context) --- slides/index.zh-TW.html | 1795 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 1795 insertions(+) create mode 100644 slides/index.zh-TW.html diff --git a/slides/index.zh-TW.html b/slides/index.zh-TW.html new file mode 100644 index 0000000..557ec7f --- /dev/null +++ b/slides/index.zh-TW.html @@ -0,0 +1,1795 @@ + + + + + + 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 可看講者備註。

+
+ +
+
+

快速開始

+

現在立刻要做的 11 件事

+

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

+
+ +
+

最快見效的做法

+
    +
  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. 在 Copilot CLI 執行 /chronicle improve。
    6. +
  6. 長串 CLI 工具鏈可試試 CodeAct。
    7. +
+
+ +
+

優先順序堆疊

+
+
+

先管輸出

+

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

+
+
+

第二是常駐內容

+

指令檔與工具 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 目錄、產生檔。
    • +
  • 在 Business／Enterprise 使用 Content Exclusion 處理敏感路徑。
    • +
  • 換主題後開新對話。
    • +
+
+ +
+

使用範圍化指令

+ 
---
+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. 稽核 MCP servers。
    6. +
  6. 模型變更後重新調整 prompt。
    7. +
+
+ +
+

品質曲線

+ 
節省：  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. +
+
+ +
+

起始指令範本

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

Coding Agent 設定

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

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

+
+ +
+

精準 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 存取採例外制。先量測，再擴張。 +
+
+
+
+
+ + + + + + + + From 9ae4eecd64973d465a496bacef87e573cf06ec30 Mon Sep 17 00:00:00 2001 From: Marco Olivo <8478776+olivomarco@users.noreply.github.com> Date: Mon, 8 Jun 2026 13:02:52 +0200 Subject: [PATCH 3/7] Enhance README and documentation with guidance on converting non-text files to Markdown for token efficiency --- README.md | 16 +++++++++------- docs/04-context-management.md | 28 ++++++++++++++++++++++++++++ docs/09-comparisons-data.md | 8 ++++++-- docs/10-practical-setup.md | 25 +++++++++++++++++++++++++ docs/index.md | 8 ++++++-- 5 files changed, 74 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index e476c1d..7676dd8 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ --- -## Quick Start — 11 Things to Do Right Now +## Quick Start — 12 Things to Do Right Now > **June 1, 2026 — Usage-Based Billing (UBB) is live.** GitHub Copilot now bills real tokens (input + output + cached) drawn from pooled AI credits ($30/seat Business, $70/seat Enterprise) instead of request counters. Every technique in this guide translates directly into credit savings — and cache-friendly habits matter more than ever. See [Enterprise Governance](docs/12-enterprise-governance.md) for customer guardrails and [Model Selection & Pricing](docs/11-models-and-pricing.md) for model-cost guidance. @@ -29,14 +29,15 @@ Don't have time to read the full guide? Do these today and cut your token usage: | 7 | **Be precise in your prompts** — "Add null check to `getUser()`" not "Can you please look at this and maybe add some error handling?" Note: your typed prompt is a small fraction of total input; precision matters more for quality than for raw token savings | Improves task targeting | 0 minutes | | 8 | **Retune prompts to the target model** — provider prompting guides change by model/version. Paste the official guide URL into Copilot and ask it to adapt `.github/copilot-instructions.md`, agent profiles, or app prompts for the model you actually use | Reduces rework | 10 minutes per model change | | 9 | **Audit your MCP servers** — disable servers you're not using; each costs ~100-500 tokens per agent step | Removes tool/schema overhead | 5 minutes | -| 10 | **Run `/chronicle improve` weekly** (**Copilot CLI only**, experimental) — this slash command works in interactive Copilot CLI sessions, not as a general Copilot Chat feature. It finds recurring confusion in your CLI session history and generates custom-instruction fixes so the same misread intent stops costing tokens forever | Cuts recurring rework | 2 minutes per run | -| 11 | **Try CodeAct for long tool chains** (**Copilot CLI only**, optional external plugin) — [`copilot-codeact-plugin`](https://github.com/jsturtevant/copilot-codeact-plugin) collapses multi-step tool chains into one sandboxed execution, which can reduce repeated replay of system prompt, prior messages, and tool definitions | Reduces tool-loop replay | 10-15 minutes | +| 10 | **Convert rich files to Markdown before AI work** — `.docx`, `.pdf`, `.pptx`, `.xlsx`, HTML, images, audio, video, and ZIPs carry format tax. [Marc Bara's writeup](https://medium.com/@marc.bara.iniesta/your-docx-is-wasting-33-of-your-ai-budget-86a3d229d042) shows the cost; use [Microsoft MarkItDown](https://github.com/microsoft/markitdown) before chat, agent, or RAG ingestion | Reduces noisy input context | 5 minutes | +| 11 | **Run `/chronicle improve` weekly** (**Copilot CLI only**, experimental) — this slash command works in interactive Copilot CLI sessions, not as a general Copilot Chat feature. It finds recurring confusion in your CLI session history and generates custom-instruction fixes so the same misread intent stops costing tokens forever | Cuts recurring rework | 2 minutes per run | +| 12 | **Try CodeAct for long tool chains** (**Copilot CLI only**, optional external plugin) — [`copilot-codeact-plugin`](https://github.com/jsturtevant/copilot-codeact-plugin) collapses multi-step tool chains into one sandboxed execution, which can reduce repeated replay of system prompt, prior messages, and tool definitions | Reduces tool-loop replay | 10-15 minutes | **Looking at this from an enterprise or customer-governance angle instead of an individual setup angle?** Start with [Enterprise Governance](docs/12-enterprise-governance.md). That chapter covers AI-credit budgets, per-user tightening, model-access policy, org instructions, and separate-organization tradeoffs. *Figures above are scoped to the mechanism named in each row, are not additive, and do not equal total bill reduction.* -Output control (#1, #2) pays off immediately and compounds — set it once, save on every call. Structural input control (#3, #6) compounds across every interaction. Model routing (#4, #5) reduces cost at the billing tier. Model-specific prompt tuning (#8) cuts waste by improving first-pass quality. MCP audit (#9) eliminates thousands of hidden tokens per agent task. +Output control (#1, #2) pays off immediately and compounds — set it once, save on every call. Structural input control (#3, #6) compounds across every interaction. Model routing (#4, #5) reduces cost at the billing tier. Model-specific prompt tuning (#8) cuts waste by improving first-pass quality. MCP audit (#9) eliminates thousands of hidden tokens per agent task. Markdown conversion (#10) removes DOCX/PDF/HTML layout noise before the model ever sees it. --- @@ -62,7 +63,7 @@ Data-backed comparison: English is the most token-efficient language in these ex #### [2.3 Context Management](docs/04-context-management.md) -Compress system instructions, compress memory files, scope context with `applyTo`, close unused editor tabs, configure Content Exclusion (Business/Enterprise admins), start fresh conversations. Control what gets sent to the model. +Compress system instructions, compress memory files, scope context with `applyTo`, close unused editor tabs, convert non-text files to Markdown before AI work, configure Content Exclusion (Business/Enterprise admins), start fresh conversations. Control what gets sent to the model. #### [2.4 Output Control](docs/05-output-control.md) @@ -127,8 +128,9 @@ Ranked by cost impact. Output first — it costs 5× more per token than input. 3. **Ask Mode for simple questions** — 60-90% savings by avoiding Agent overhead 4. **Audit MCP servers** — disable unused servers, save 5K-190K tokens per agent task 5. **Auto model selection** — lower-cost default routing plus paid-plan discount on eligible usage, zero effort -6. **Retune prompts to the target model** — better first-pass output reduces repeated clarification turns -7. **Precise prompts** — 20-40% of user-prompt input tokens; more important for quality than raw savings +6. **Convert rich files to Markdown first** — avoid paying for Word/PDF/HTML layout noise in chat, agent, and RAG workflows +7. **Retune prompts to the target model** — better first-pass output reduces repeated clarification turns +8. **Precise prompts** — 20-40% of user-prompt input tokens; more important for quality than raw savings --- diff --git a/docs/04-context-management.md b/docs/04-context-management.md index d3d915e..97c9d7d 100644 --- a/docs/04-context-management.md +++ b/docs/04-context-management.md @@ -93,9 +93,37 @@ What actually reduces auto-included context (per-developer levers that work ever - Vendor directories - Data files (CSVs, JSON fixtures) - Archived documentation +- Rich document formats (`.docx`, `.pdf`, `.pptx`, `.xlsx`, HTML exports, scanned images, audio/video transcripts) Every file that enters context costs tokens. Be intentional about what's open and what's referenced with `#file`. +### Normalize non-text inputs to Markdown first + +When the source is a Word file, PDF, PowerPoint, spreadsheet, image, audio file, or exported HTML, do not paste the rich format directly into an AI workflow if you can avoid it. Convert it to clean Markdown first, then send the Markdown. + +Marc Bara calls this the **format tax** in [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): Word, PDF, and HTML carry font data, XML, page-positioning metadata, layout artifacts, embedded objects, and tag soup that models must process but rarely need. The article cites a concrete example where a 10-page report extracted from PDF used roughly 12,400 tokens, while the same content as clean Markdown used about 8,350 tokens — a 33% reduction with the same information. HTML exports can be even worse because semantic content gets wrapped in long tags, classes, IDs, and layout scaffolding. + +The rule: use Markdown as the **working format** for AI interaction, and treat Word/PDF/PowerPoint as delivery formats. Draft, review, summarize, chunk, and retrieve from Markdown. Generate `.docx` or `.pdf` at the end only when a client, regulator, or internal process needs that artifact. + +[Microsoft MarkItDown](https://github.com/microsoft/markitdown) is the practical bridge. It is a Python tool for converting files and office documents to Markdown for LLM and text-analysis pipelines. It preserves useful structure such as headings, lists, tables, links, and extracted metadata, while avoiding high-fidelity visual layout noise. Current converters include PDF, Word, PowerPoint, Excel, images with EXIF/OCR support, audio with transcription support, HTML, CSV/JSON/XML, ZIP contents, YouTube URLs, EPUBs, and more. + +Fast path: + +```bash +pip install 'markitdown[all]' +markitdown report.docx -o report.md +markitdown deck.pptx -o deck.md +markitdown source.pdf > source.md +``` + +Use narrower extras when you control the workflow and want fewer dependencies: + +```bash +pip install 'markitdown[pdf,docx,pptx,xlsx]' +``` + +Security note: MarkItDown reads files, streams, and URLs with the privileges of the current process. For untrusted inputs, validate paths and URLs first, and prefer the narrowest conversion API that fits the workflow. + ## 2.3.4 Scope Context Intentionally — Conditional Over Always-On Most context files are loaded on **every** interaction. That's a tax you pay even when the file isn't relevant — your React component questions don't need your database migration guidelines. diff --git a/docs/09-comparisons-data.md b/docs/09-comparisons-data.md index 206a950..d4cb876 100644 --- a/docs/09-comparisons-data.md +++ b/docs/09-comparisons-data.md @@ -74,6 +74,7 @@ The complete comparison of every technique covered in this guide: | C2 | Compressed instructions file | 40-60% of file | — | None | Low | Every repo | | C3 | Progressive on-demand guidance | 60-90% of optional guidance | — | Positive | High | Teams with reusable prompt files | | C4 | Start new conversations | 80%+ | — | Lose context | Low | Long sessions | +| C5 | Convert non-text files to Markdown first | ~33% on cited PDF example; higher for noisy HTML | — | Improves structure | Low | DOCX, PDF, PPTX, XLSX, images, audio, RAG ingestion | | **Output Control** | | D1 | Code-only responses | — | 40-70% | Good | Low | Code generation | | D2 | Structured output (JSON/tables) | — | 30-60% | Depends | Low | Data tasks | @@ -113,9 +114,11 @@ The complete comparison of every technique covered in this guide: > †A1/A2 output savings require system-level terse output instructions (see B5). Writing terse prompts alone saves input tokens; output tokens are only reduced if the model is instructed to respond tersely. +> C5 source: Marc Bara's [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). Use [Microsoft MarkItDown](https://github.com/microsoft/markitdown) when non-text files need to enter an AI workflow. + ### The Big Winners -If you do nothing else, do these six. Ranked by impact-to-effort ratio: +If you do nothing else, do these eight. Ranked by impact-to-effort ratio: 1. **Caveman-speak** — 30-50% input token savings; combine with B5 for 40-55% output savings 2. **Precise prompts** — 30-60% savings, just a habit change @@ -123,7 +126,8 @@ If you do nothing else, do these six. Ranked by impact-to-effort ratio: 4. **Shrink always-on context** (`copilot-instructions.md` + `AGENTS.md`) — compress filler, prune to landmines only, delete LLM-generated boilerplate. Compounds on every interaction and agent step; 20-23% agent-task reduction plus better correctness 5. **Ask Mode for simple questions** — 60-90% savings by avoiding Agent overhead 6. **Audit MCP servers** — disable unused servers, save 5K-190K tokens per agent task -7. **Retune prompts to target model guide** — not a per-request shrink; improves first-pass quality and avoids rework after model changes +7. **Convert non-text files to Markdown first** — avoid the DOCX/PDF/HTML format tax before content enters chat, agents, or RAG +8. **Retune prompts to target model guide** — not a per-request shrink; improves first-pass quality and avoids rework after model changes ## 3.4 Quality Impact Assessment diff --git a/docs/10-practical-setup.md b/docs/10-practical-setup.md index 20be55c..db5dcda 100644 --- a/docs/10-practical-setup.md +++ b/docs/10-practical-setup.md @@ -183,6 +183,31 @@ If you are guiding an organization or enterprise rollout, stop here and read [En Use this page for practitioner setup. Use the enterprise chapter for customer governance decisions. +### Step 8: Convert Non-Text Inputs Before AI Work + +When a workflow starts from `.docx`, `.pdf`, `.pptx`, `.xlsx`, HTML exports, images, audio, video, or ZIP archives, add a conversion step before the content reaches Copilot or a RAG pipeline. Rich formats carry layout and metadata that inflate input tokens without improving the model's understanding. + +[Marc Bara's format-tax writeup](https://medium.com/@marc.bara.iniesta/your-docx-is-wasting-33-of-your-ai-budget-86a3d229d042) gives the operating principle: Markdown should be the working format for AI, while Word/PDF remain output formats when a human process requires them. The article cites a 10-page PDF example dropping from roughly 12,400 tokens to 8,350 after clean Markdown conversion — about 33% less input for the same content. + +[Microsoft MarkItDown](https://github.com/microsoft/markitdown) is the default tool to try first. It converts PDF, Word, PowerPoint, Excel, images, audio, HTML, CSV/JSON/XML, ZIP contents, YouTube URLs, EPUBs, and more into Markdown for LLM and text-analysis workflows. + +```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 +``` + +For production pipelines, install only the needed extras when possible: + +```bash +pip install 'markitdown[pdf,docx,pptx,xlsx]' +``` + +Then send the `.md` file to the model, chunk/index the `.md` file for retrieval, and regenerate `.docx` or `.pdf` only at the final delivery step. For untrusted uploads, validate paths and URLs first; MarkItDown performs I/O with the privileges of the running process. + ## 4.2 Keep Reusable Guidance Outside Always-On Context This repo no longer ships installable workflow packs. Keep the same habit, though: put occasional workflow guidance outside the always-on prompt and pull it in only when the task needs it. diff --git a/docs/index.md b/docs/index.md index d367f9f..ad8c4d9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -22,8 +22,9 @@ Practical guide to reducing GitHub Copilot token spend while keeping answers and 3. Use Ask Mode for questions that do not need tools. 4. Retune prompts and instructions against the official guide for your target model. 5. Disable MCP servers you are not using. -6. Audit long-running agent sessions and repeated back-and-forth. -7. Install [RTK](https://github.com/rtk-ai/rtk) — CLI proxy that filters `git`, test runners, `grep`, and 100+ other shell commands before output reaches the agent. One install, 60-90% savings on tool-call results in agent and coding-agent sessions. +6. Convert DOCX/PDF/Office/media inputs to Markdown before AI work; start with [MarkItDown](https://github.com/microsoft/markitdown). +7. Audit long-running agent sessions and repeated back-and-forth. +8. Install [RTK](https://github.com/rtk-ai/rtk) — CLI proxy that filters `git`, test runners, `grep`, and 100+ other shell commands before output reaches the agent. One install, 60-90% savings on tool-call results in agent and coding-agent sessions. ## Read by Topic @@ -53,6 +54,7 @@ Practical guide to reducing GitHub Copilot token spend while keeping answers and - **Ask Mode**: single-shot interaction. Lowest-overhead choice for simple questions. - **Agent Mode**: multi-step interaction. Higher leverage, higher cost. - **Content Exclusion**: admin control for keeping selected repo content out of Copilot context. +- **Format tax**: extra tokens from rich file metadata and layout noise in DOCX, PDF, HTML, slides, spreadsheets, images, and audio/video extraction. Convert to Markdown first. ## Useful Links @@ -63,6 +65,8 @@ Practical guide to reducing GitHub Copilot token spend while keeping answers and - [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) — convert PDF, Office files, images, audio, HTML, ZIP contents, YouTube URLs, EPUBs, and more to Markdown for LLM workflows +- [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) — real measured numbers from a Copilot CLI production setup (Microsoft/GitHub content contributor) ## Notes From 8403c43e14417b4830f6ac641cd117395ee36720 Mon Sep 17 00:00:00 2001 From: Jamestsai Date: Mon, 8 Jun 2026 23:55:07 +0800 Subject: [PATCH 4/7] Update zh-TW docs for markdown conversion changes Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.zh-TW.md | 16 +++++++------ docs/04-context-management.zh-TW.md | 29 ++++++++++++++++++++++++ docs/09-comparisons-data.zh-TW.md | 8 +++++-- docs/10-practical-setup.zh-TW.md | 25 +++++++++++++++++++++ docs/index.zh-TW.md | 8 +++++-- slides/index.zh-TW.html | 35 ++++++++++++++++++++++++++--- 6 files changed, 107 insertions(+), 14 deletions(-) diff --git a/README.zh-TW.md b/README.zh-TW.md index b7926af..2014f07 100644 --- a/README.zh-TW.md +++ b/README.zh-TW.md @@ -10,7 +10,7 @@ --- -## 快速開始：現在就該做的 11 件事 +## 快速開始：現在就該做的 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)。 @@ -29,14 +29,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 | **每週執行 `/chronicle improve`**（**僅限 Copilot CLI**，實驗性功能）：這個 slash command 只能在互動式 Copilot CLI 工作階段中使用，並不是一般 Copilot Chat 功能。它會找出你 CLI 工作階段歷史中反覆出現的誤解，並產生自訂指令，讓同樣的誤判不再持續浪費 token | 降低重複返工 | 每次 2 分鐘 | -| 11 | **長工具鏈任務可考慮 CodeAct**（**僅限 Copilot CLI**，可選的外部外掛）：[`copilot-codeact-plugin`](https://github.com/jsturtevant/copilot-codeact-plugin) 可以把多步驟工具鏈收斂成一次沙箱執行，減少重複重播 system prompt、先前訊息與工具定義的次數 | 降低工具迴圈重播成本 | 10-15 分鐘 | +| 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 成本。 +輸出控制（#1、#2）會立刻生效，而且會持續累積回報：設定一次，每次呼叫都省。結構性的輸入控制（#3、#6）會在每一次互動中持續累積效益。模型路由（#4、#5）會從計費層級直接降低成本。針對模型調整提示詞（#8）則透過提升首次回應品質來減少浪費。MCP 稽核（#9）可以直接砍掉每次 agent 任務中那些隱藏的 token 成本。Markdown 轉換（#10）則能在模型看到內容前，先移除 DOCX／PDF／HTML 的版面與標記雜訊。 --- @@ -62,7 +63,7 @@ #### [2.3 Context Management](docs/04-context-management.zh-TW.md) -壓縮 system instructions、壓縮記憶檔、用 `applyTo` 限定上下文、關閉未使用的編輯器分頁、設定 Content Exclusion（Business／Enterprise 管理員可用），以及在需要時開新對話。重點是控制實際送進模型的內容。 +壓縮 system instructions、壓縮記憶檔、用 `applyTo` 限定上下文、關閉未使用的編輯器分頁、在 AI 工作前先把非純文字檔轉成 Markdown、設定 Content Exclusion（Business／Enterprise 管理員可用），以及在需要時開新對話。重點是控制實際送進模型的內容。 #### [2.4 Output Control](docs/05-output-control.zh-TW.md) @@ -127,8 +128,9 @@ 3. **簡單問題使用 Ask Mode**：避免 Agent 額外開銷，可節省 60-90%。 4. **稽核 MCP servers**：停用沒在用的 servers，每次 agent 任務可省下 5 千到 19 萬個 token。 5. **使用 Auto 模型選擇**：以更低成本的預設路由加上付費方案折扣達成節省，幾乎零成本導入。 -6. **依目標模型重調提示詞**：提升第一次輸出的品質，減少來回澄清。 -7. **精準提示詞**：可影響使用者提示詞輸入 token 的 20-40%；對品質的幫助通常比對原始節省更重要。 +6. **先把富格式檔案轉成 Markdown**：避免在 chat、agent 與 RAG 工作流中為 Word／PDF／HTML 的版面雜訊付費。 +7. **依目標模型重調提示詞**：提升第一次輸出的品質，減少來回澄清。 +8. **精準提示詞**：可影響使用者提示詞輸入 token 的 20-40%；對品質的幫助通常比對原始節省更重要。 --- diff --git a/docs/04-context-management.zh-TW.md b/docs/04-context-management.zh-TW.md index 43e8cea..25367b2 100644 --- a/docs/04-context-management.zh-TW.md +++ b/docs/04-context-management.zh-TW.md @@ -53,6 +53,7 @@ Copilot 會自動納入工作區中的內容，例如開啟中的檔案、匯入 - **讓檔案保持小而聚焦。** 1,000 行的大檔若開著，Copilot 可能會送很多內容進去。 - **對 build output、vendor、generated files 使用 `.gitignore`。** - **使用 `applyTo:` 範圍化 instruction 檔**，讓特定規則只在相關檔案出現時才載入。 +- **在 AI 工作前，先把非純文字檔轉成 Markdown。** 這是處理富格式輸入時，最直接的 token 節省。 - **Business／Enterprise 環境下**，可請管理員設定 Content Exclusion 做政策與敏感路徑控管。 要小心的高風險檔案包括： @@ -62,6 +63,34 @@ Copilot 會自動納入工作區中的內容，例如開啟中的檔案、匯入 - 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：條件式優於常駐式 diff --git a/docs/09-comparisons-data.zh-TW.md b/docs/09-comparisons-data.zh-TW.md index 80b9be1..f75cda4 100644 --- a/docs/09-comparisons-data.zh-TW.md +++ b/docs/09-comparisons-data.zh-TW.md @@ -60,6 +60,7 @@ | 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 工作流 | @@ -74,8 +75,11 @@ 3. **Code-only / constrain output** 4. **縮小 always-on context** 5. **簡單問題用 Ask Mode** -6. **稽核 MCP servers** -7. **依模型調整 prompts** +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 品質影響評估 diff --git a/docs/10-practical-setup.zh-TW.md b/docs/10-practical-setup.zh-TW.md index ccf1378..8694857 100644 --- a/docs/10-practical-setup.zh-TW.md +++ b/docs/10-practical-setup.zh-TW.md @@ -97,6 +97,31 @@ Errors: Result pattern, no thrown exceptions in business logic. 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，但原則一樣： diff --git a/docs/index.zh-TW.md b/docs/index.zh-TW.md index 99bc5c7..5b100af 100644 --- a/docs/index.zh-TW.md +++ b/docs/index.zh-TW.md @@ -24,8 +24,9 @@ 3. 不需要工具的問題就用 Ask Mode。 4. 依目標模型的官方指南重調 prompts 與 instructions。 5. 停用沒在用的 MCP servers。 -6. 稽核長時間 agent sessions 與重複來回澄清。 -7. 安裝 [RTK](https://github.com/rtk-ai/rtk)，壓縮 shell 指令輸出。 +6. 先把 DOCX／PDF／Office／媒體輸入轉成 Markdown 再做 AI 工作；優先試 [MarkItDown](https://github.com/microsoft/markitdown)。 +7. 稽核長時間 agent sessions 與重複來回澄清。 +8. 安裝 [RTK](https://github.com/rtk-ai/rtk)，壓縮 shell 指令輸出。 ## 依主題閱讀 @@ -55,6 +56,7 @@ - **Ask Mode**：單次互動。最省成本。 - **Agent Mode**：多步驟互動。槓桿高，但成本也高。 - **Content Exclusion**：管理員用來讓特定 repo 內容不進 Copilot context 的控制項。 +- **格式稅**：DOCX、PDF、HTML、投影片、試算表、圖片、音訊／影片抽取內容中，多出來的版面、標記與中繼資料 token。先轉成 Markdown。 ## 實用連結 @@ -65,6 +67,8 @@ - [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) ## 備註 diff --git a/slides/index.zh-TW.html b/slides/index.zh-TW.html index 557ec7f..0dfa4a2 100644 --- a/slides/index.zh-TW.html +++ b/slides/index.zh-TW.html @@ -241,7 +241,7 @@

導覽方式

快速開始

-

現在立刻要做的 11 件事

+

現在立刻要做的 12 件事

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

@@ -263,6 +263,7 @@

更多快速見效做法

  • 寫精準的 prompt：目標檔案、函式、完成條件。
  • 依目標模型重新調整 prompt。
  • 稽核 MCP servers。
    • +
  • 把 DOCX／PDF／HTML 等富格式檔先轉成 Markdown。
  • 在 Copilot CLI 執行 /chronicle improve。
  • 長串 CLI 工具鏈可試試 CodeAct。
    • @@ -574,11 +575,27 @@

    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%。

    +
    +

    使用範圍化指令

    ---
@@ -970,6 +987,7 @@ 
    最大贏家
    
               
  • 只回程式碼／限制輸出格式。
    • 
               
  • 縮小常駐 context。
    • 
               
  • 簡單問題用 Ask Mode。
    • 
+              
  • 先把富格式檔轉成 Markdown。
    • 
               
  • 稽核 MCP servers。
    • 
               
  • 模型變更後重新調整 prompt。
    • 
             
@@ -1009,6 +1027,7 @@ 
    Repo 設定步驟
    
               
  • 用 applyTo 拆出路徑專屬指引。
    • 
               
  • 預設使用 Auto；只有在有理由時才釘選。
    • 
               
  • 為 Coding Agent 加上 copilot-setup-steps.yml。
    • 
+              
  • 把 DOCX／PDF／HTML 等輸入先轉成 Markdown。
    •
    @@ -1032,6 +1051,16 @@

    Coding Agent 設定

    避免靠 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 包含 "+" 時，登入失敗。
@@ -1356,10 +1385,10 @@ 
    結語
    
           
    時間：1 分鐘。
    
           
    只有在瀏覽器 live demo 時才示範控制方式。講者畫面可看備註；如果觀眾想跳章節，可用總覽模式。
    
         `,
-        "現在立刻要做的 11 件事": `
+        "現在立刻要做的 12 件事": `
           
    時間：2 分鐘。
    
           
    把這頁當成 executive summary。若客戶只能實作一頁，就實作這一頁。
    
-          
    強調順序：輸出、常駐 context、模式／模型／工具分流。
    
+          
    強調順序：輸出、常駐 context、模式／模型／工具分流，再補上富格式檔案轉 Markdown 的前處理。
    
         `,
         "最快見效的做法": `
           
    時間：3 分鐘。
    

From bc34c9b2c159fbb518c9e918633e4474a00f9c54 Mon Sep 17 00:00:00 2001
From: Jamestsai 
Date: Tue, 9 Jun 2026 00:28:33 +0800
Subject: [PATCH 5/7] Add zh-TW translation automation

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .github/workflows/translate-zh-tw.yml | 133 +++++++++++
 scripts/translate_zh_tw.py            | 306 ++++++++++++++++++++++++++
 2 files changed, 439 insertions(+)
 create mode 100644 .github/workflows/translate-zh-tw.yml
 create mode 100644 scripts/translate_zh_tw.py

diff --git a/.github/workflows/translate-zh-tw.yml b/.github/workflows/translate-zh-tw.yml
new file mode 100644
index 0000000..7e8aeaa
--- /dev/null
+++ b/.github/workflows/translate-zh-tw.yml
@@ -0,0 +1,133 @@
+name: Translate zh-TW Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'README.md'
+      - 'docs/**/*.md'
+      - '!README.zh-TW.md'
+      - '!docs/**/*.zh-TW.md'
+      - '.github/workflows/translate-zh-tw.yml'
+      - 'scripts/translate_zh_tw.py'
+  workflow_dispatch:
+    inputs:
+      translate_all:
+        description: Translate all supported English markdown files
+        required: false
+        default: false
+        type: boolean
+      model:
+        description: GitHub Models model id
+        required: false
+        default: openai/gpt-4.1-mini
+        type: string
+
+permissions:
+  contents: write
+  models: read
+
+concurrency:
+  group: translate-zh-tw
+  cancel-in-progress: true
+
+env:
+  DEFAULT_TRANSLATE_MODEL: openai/gpt-4.1-mini
+
+jobs:
+  translate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install Taiwanese Mandarin translation skill
+        run: npx --yes taiwanese-mandarin-translate-skill init --target copilot
+
+      - name: Generate zh-TW translations
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_EVENT_BEFORE: ${{ github.event.before }}
+          GITHUB_SHA: ${{ github.sha }}
+          TRANSLATE_ALL: ${{ github.event_name == 'workflow_dispatch' && inputs.translate_all || false }}
+          TRANSLATE_MODEL: ${{ github.event_name == 'workflow_dispatch' && inputs.model || env.DEFAULT_TRANSLATE_MODEL }}
+          TRANSLATION_OUTPUT_DIR: ${{ runner.temp }}/zh-tw-output
+        run: python scripts/translate_zh_tw.py
+
+      - name: Prepare zh-TW worktree
+        id: worktree
+        shell: bash
+        run: |
+          worktree_dir="$RUNNER_TEMP/zh-TW-worktree"
+          rm -rf "$worktree_dir"
+
+          if git ls-remote --exit-code --heads origin zh-TW >/dev/null 2>&1; then
+            git fetch origin zh-TW
+            git worktree add -B zh-TW "$worktree_dir" origin/zh-TW
+          else
+            git worktree add -b zh-TW "$worktree_dir" HEAD
+          fi
+
+          echo "worktree_dir=$worktree_dir" >> "$GITHUB_OUTPUT"
+
+      - name: Apply translated files
+        env:
+          TRANSLATION_OUTPUT_DIR: ${{ runner.temp }}/zh-tw-output
+          ZH_TW_WORKTREE: ${{ steps.worktree.outputs.worktree_dir }}
+        run: |
+          python - <<'PY'
+          import json
+          import os
+          import shutil
+          from pathlib import Path
+
+          output_dir = Path(os.environ["TRANSLATION_OUTPUT_DIR"])
+          worktree = Path(os.environ["ZH_TW_WORKTREE"])
+          manifest_path = output_dir / "manifest.json"
+          manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+
+          for rel_path in manifest.get("written", []):
+            source = output_dir / rel_path
+            destination = worktree / rel_path
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(source, destination)
+
+          for rel_path in manifest.get("deleted", []):
+            destination = worktree / rel_path
+            if destination.exists():
+              destination.unlink()
+          PY
+
+      - name: Commit and push zh-TW updates
+        working-directory: ${{ steps.worktree.outputs.worktree_dir }}
+        shell: bash
+        run: |
+          if [ -z "$(git status --porcelain)" ]; then
+            echo "No zh-TW updates to commit."
+            exit 0
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add -A README.zh-TW.md docs
+
+          if git diff --cached --quiet; then
+            echo "No staged zh-TW changes."
+            exit 0
+          fi
+
+          git commit -m "Update zh-TW translations from main"
+          git push origin HEAD:zh-TW
diff --git a/scripts/translate_zh_tw.py b/scripts/translate_zh_tw.py
new file mode 100644
index 0000000..c56b0cc
--- /dev/null
+++ b/scripts/translate_zh_tw.py
@@ -0,0 +1,306 @@
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import textwrap
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+
+MODELS_ENDPOINT = "https://models.github.ai/inference/chat/completions"
+ZERO_SHA = "0" * 40
+
+
+def run_git(*args: str, cwd: Path | None = None) -> str:
+    result = subprocess.run(
+        ["git", *args],
+        cwd=cwd,
+        check=True,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+    )
+    return result.stdout.strip()
+
+
+def supported_source_files(repo_root: Path) -> list[Path]:
+    files = [repo_root / "README.md"]
+    docs_dir = repo_root / "docs"
+    if docs_dir.exists():
+        files.extend(
+            path
+            for path in sorted(docs_dir.rglob("*.md"))
+            if not path.name.endswith(".zh-TW.md")
+        )
+    return [path for path in files if path.exists()]
+
+
+def is_supported_source(rel_path: Path) -> bool:
+    posix = rel_path.as_posix()
+    if posix == "README.md":
+        return True
+    return posix.startswith("docs/") and posix.endswith(".md") and not posix.endswith(".zh-TW.md")
+
+
+def target_for_source(rel_path: Path) -> Path:
+    if rel_path.suffix != ".md" or rel_path.name.endswith(".zh-TW.md"):
+        raise ValueError(f"Unsupported source path: {rel_path}")
+    return rel_path.with_name(f"{rel_path.stem}.zh-TW.md")
+
+
+def parse_changed_files(repo_root: Path, before_sha: str, after_sha: str) -> tuple[set[Path], set[Path]]:
+    changed_sources: set[Path] = set()
+    deleted_targets: set[Path] = set()
+
+    if not before_sha or before_sha == ZERO_SHA:
+        for file_path in supported_source_files(repo_root):
+            changed_sources.add(file_path.relative_to(repo_root))
+        return changed_sources, deleted_targets
+
+    diff_output = run_git(
+        "diff",
+        "--name-status",
+        "-M",
+        "--find-renames",
+        before_sha,
+        after_sha,
+        "--",
+        "README.md",
+        "docs",
+        cwd=repo_root,
+    )
+
+    for line in diff_output.splitlines():
+        if not line.strip():
+            continue
+
+        parts = line.split("\t")
+        status = parts[0]
+
+        if status.startswith("R") and len(parts) == 3:
+            old_path = Path(parts[1])
+            new_path = Path(parts[2])
+            if is_supported_source(new_path):
+                changed_sources.add(new_path)
+            if is_supported_source(old_path):
+                deleted_targets.add(target_for_source(old_path))
+            continue
+
+        if len(parts) < 2:
+            continue
+
+        rel_path = Path(parts[1])
+        if not is_supported_source(rel_path):
+            continue
+
+        if status == "D":
+            deleted_targets.add(target_for_source(rel_path))
+        else:
+            changed_sources.add(rel_path)
+
+    return changed_sources, deleted_targets
+
+
+def load_skill_context() -> str:
+    skill_dir = Path(
+        os.environ.get(
+            "TRANSLATE_SKILL_DIR",
+            Path.home() / ".copilot" / "skills" / "taiwanese-mandarin-translate",
+        )
+    )
+    required_files = [
+        skill_dir / "SKILL.md",
+        skill_dir / "EXAMPLES.md",
+        skill_dir / "references" / "vocabulary.md",
+    ]
+    missing = [str(path) for path in required_files if not path.exists()]
+    if missing:
+        raise FileNotFoundError(f"Missing translation skill files: {', '.join(missing)}")
+
+    parts: list[str] = []
+    for path in required_files:
+        header = path.relative_to(skill_dir).as_posix()
+        parts.append(f"## {header}\n{path.read_text(encoding='utf-8')}")
+    return "\n\n".join(parts)
+
+
+def build_system_prompt(skill_context: str) -> str:
+    return textwrap.dedent(
+        f"""
+        You are a translation engine for repository documentation.
+
+        Follow the translation skill below as the highest-priority style guide.
+        Output only the final translated Markdown for the target file. Do not add explanations.
+        Preserve headings, tables, links, code fences, inline code, placeholders, HTML, and file paths.
+        Keep brands, APIs, commands, and technical identifiers in the source language unless translation is clearly required.
+        Prefer Taiwanese Mandarin written in Traditional Chinese used in Taiwan.
+        Reuse accurate wording from the existing zh-TW file where possible so unchanged sections stay stable.
+
+        {skill_context}
+        """
+    ).strip()
+
+
+def build_user_prompt(
+    source_path: Path,
+    source_markdown: str,
+    existing_translation: str | None,
+    source_diff: str | None,
+) -> str:
+    existing_block = existing_translation if existing_translation else "[No existing translation file]"
+    diff_block = source_diff if source_diff else "[No prior diff available. Produce a full up-to-date translation.]"
+    return textwrap.dedent(
+        f"""
+        Update the Traditional Chinese (Taiwan) translation for this repository file.
+
+        Source file: {source_path.as_posix()}
+        Target file: {target_for_source(source_path).as_posix()}
+
+        English source diff against previous main:
+        ```diff
+        {diff_block}
+        ```
+
+        Current English source Markdown:
+        ```markdown
+        {source_markdown}
+        ```
+
+        Existing zh-TW Markdown:
+        ```markdown
+        {existing_block}
+        ```
+
+        Requirements:
+        - Return the full final contents for the target file only.
+        - Match the English source completely.
+        - Preserve Markdown structure and link targets.
+        - Keep terminology natural for Taiwan readers.
+        - Keep unchanged sections stable when the existing translation is already correct.
+        """
+    ).strip()
+
+
+def request_translation(model: str, system_prompt: str, user_prompt: str, github_token: str) -> str:
+    payload = {
+        "model": model,
+        "temperature": 0.2,
+        "messages": [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt},
+        ],
+    }
+    request = urllib.request.Request(
+        MODELS_ENDPOINT,
+        data=json.dumps(payload).encode("utf-8"),
+        headers={
+            "Accept": "application/vnd.github+json",
+            "Authorization": f"Bearer {github_token}",
+            "Content-Type": "application/json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+        method="POST",
+    )
+
+    try:
+        with urllib.request.urlopen(request) as response:
+            body = response.read().decode("utf-8")
+    except urllib.error.HTTPError as exc:
+        error_body = exc.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"GitHub Models request failed: HTTP {exc.code} {error_body}") from exc
+
+    parsed = json.loads(body)
+    choices = parsed.get("choices", [])
+    if not choices:
+        raise RuntimeError(f"GitHub Models returned no choices: {body}")
+
+    content = choices[0].get("message", {}).get("content", "")
+    if not content:
+        raise RuntimeError(f"GitHub Models returned empty content: {body}")
+    return content.rstrip() + "\n"
+
+
+def source_diff(repo_root: Path, before_sha: str, after_sha: str, rel_path: Path) -> str | None:
+    if not before_sha or before_sha == ZERO_SHA:
+        return None
+
+    try:
+        diff_text = run_git(
+            "diff",
+            "--unified=3",
+            before_sha,
+            after_sha,
+            "--",
+            rel_path.as_posix(),
+            cwd=repo_root,
+        )
+    except subprocess.CalledProcessError:
+        return None
+
+    return diff_text or None
+
+
+def translate_files() -> None:
+    repo_root = Path(os.environ.get("GITHUB_WORKSPACE", Path.cwd())).resolve()
+    output_dir = Path(os.environ["TRANSLATION_OUTPUT_DIR"]).resolve()
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    github_token = os.environ["GITHUB_TOKEN"]
+    before_sha = os.environ.get("GITHUB_EVENT_BEFORE", "")
+    after_sha = os.environ.get("GITHUB_SHA", "HEAD")
+    translate_all = os.environ.get("TRANSLATE_ALL", "").lower() == "true"
+    model = os.environ.get("TRANSLATE_MODEL", "openai/gpt-4.1-mini")
+
+    if translate_all:
+        changed_sources = {path.relative_to(repo_root) for path in supported_source_files(repo_root)}
+        deleted_targets: set[Path] = set()
+    else:
+        changed_sources, deleted_targets = parse_changed_files(repo_root, before_sha, after_sha)
+
+    skill_context = load_skill_context()
+    system_prompt = build_system_prompt(skill_context)
+
+    written_files: list[str] = []
+    for rel_source in sorted(changed_sources):
+        source_path = repo_root / rel_source
+        target_rel = target_for_source(rel_source)
+        existing_target = repo_root / target_rel
+
+        source_markdown = source_path.read_text(encoding="utf-8")
+        existing_translation = None
+        if existing_target.exists():
+            existing_translation = existing_target.read_text(encoding="utf-8")
+
+        translation = request_translation(
+            model=model,
+            system_prompt=system_prompt,
+            user_prompt=build_user_prompt(
+                source_path=rel_source,
+                source_markdown=source_markdown,
+                existing_translation=existing_translation,
+                source_diff=source_diff(repo_root, before_sha, after_sha, rel_source),
+            ),
+            github_token=github_token,
+        )
+
+        output_path = output_dir / target_rel
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(translation, encoding="utf-8")
+        written_files.append(target_rel.as_posix())
+        print(f"Translated {rel_source.as_posix()} -> {target_rel.as_posix()}")
+
+    manifest = {
+        "written": written_files,
+        "deleted": sorted(path.as_posix() for path in deleted_targets),
+    }
+    (output_dir / "manifest.json").write_text(
+        json.dumps(manifest, indent=2, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+    )
+    print(json.dumps(manifest, indent=2, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    translate_files()

From 1354cfc791a1407528f74a17ef447f6125c5b950 Mon Sep 17 00:00:00 2001
From: Jamestsai 
Date: Tue, 9 Jun 2026 00:39:50 +0800
Subject: [PATCH 6/7] Revert "Add zh-TW translation automation"

This reverts commit bc34c9b2c159fbb518c9e918633e4474a00f9c54.
---
 .github/workflows/translate-zh-tw.yml | 133 -----------
 scripts/translate_zh_tw.py            | 306 --------------------------
 2 files changed, 439 deletions(-)
 delete mode 100644 .github/workflows/translate-zh-tw.yml
 delete mode 100644 scripts/translate_zh_tw.py

diff --git a/.github/workflows/translate-zh-tw.yml b/.github/workflows/translate-zh-tw.yml
deleted file mode 100644
index 7e8aeaa..0000000
--- a/.github/workflows/translate-zh-tw.yml
+++ /dev/null
@@ -1,133 +0,0 @@
-name: Translate zh-TW Docs
-
-on:
-  push:
-    branches:
-      - main
-    paths:
-      - 'README.md'
-      - 'docs/**/*.md'
-      - '!README.zh-TW.md'
-      - '!docs/**/*.zh-TW.md'
-      - '.github/workflows/translate-zh-tw.yml'
-      - 'scripts/translate_zh_tw.py'
-  workflow_dispatch:
-    inputs:
-      translate_all:
-        description: Translate all supported English markdown files
-        required: false
-        default: false
-        type: boolean
-      model:
-        description: GitHub Models model id
-        required: false
-        default: openai/gpt-4.1-mini
-        type: string
-
-permissions:
-  contents: write
-  models: read
-
-concurrency:
-  group: translate-zh-tw
-  cancel-in-progress: true
-
-env:
-  DEFAULT_TRANSLATE_MODEL: openai/gpt-4.1-mini
-
-jobs:
-  translate:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout main
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.12'
-
-      - name: Install Taiwanese Mandarin translation skill
-        run: npx --yes taiwanese-mandarin-translate-skill init --target copilot
-
-      - name: Generate zh-TW translations
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          GITHUB_EVENT_BEFORE: ${{ github.event.before }}
-          GITHUB_SHA: ${{ github.sha }}
-          TRANSLATE_ALL: ${{ github.event_name == 'workflow_dispatch' && inputs.translate_all || false }}
-          TRANSLATE_MODEL: ${{ github.event_name == 'workflow_dispatch' && inputs.model || env.DEFAULT_TRANSLATE_MODEL }}
-          TRANSLATION_OUTPUT_DIR: ${{ runner.temp }}/zh-tw-output
-        run: python scripts/translate_zh_tw.py
-
-      - name: Prepare zh-TW worktree
-        id: worktree
-        shell: bash
-        run: |
-          worktree_dir="$RUNNER_TEMP/zh-TW-worktree"
-          rm -rf "$worktree_dir"
-
-          if git ls-remote --exit-code --heads origin zh-TW >/dev/null 2>&1; then
-            git fetch origin zh-TW
-            git worktree add -B zh-TW "$worktree_dir" origin/zh-TW
-          else
-            git worktree add -b zh-TW "$worktree_dir" HEAD
-          fi
-
-          echo "worktree_dir=$worktree_dir" >> "$GITHUB_OUTPUT"
-
-      - name: Apply translated files
-        env:
-          TRANSLATION_OUTPUT_DIR: ${{ runner.temp }}/zh-tw-output
-          ZH_TW_WORKTREE: ${{ steps.worktree.outputs.worktree_dir }}
-        run: |
-          python - <<'PY'
-          import json
-          import os
-          import shutil
-          from pathlib import Path
-
-          output_dir = Path(os.environ["TRANSLATION_OUTPUT_DIR"])
-          worktree = Path(os.environ["ZH_TW_WORKTREE"])
-          manifest_path = output_dir / "manifest.json"
-          manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
-
-          for rel_path in manifest.get("written", []):
-            source = output_dir / rel_path
-            destination = worktree / rel_path
-            destination.parent.mkdir(parents=True, exist_ok=True)
-            shutil.copy2(source, destination)
-
-          for rel_path in manifest.get("deleted", []):
-            destination = worktree / rel_path
-            if destination.exists():
-              destination.unlink()
-          PY
-
-      - name: Commit and push zh-TW updates
-        working-directory: ${{ steps.worktree.outputs.worktree_dir }}
-        shell: bash
-        run: |
-          if [ -z "$(git status --porcelain)" ]; then
-            echo "No zh-TW updates to commit."
-            exit 0
-          fi
-
-          git config user.name "github-actions[bot]"
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git add -A README.zh-TW.md docs
-
-          if git diff --cached --quiet; then
-            echo "No staged zh-TW changes."
-            exit 0
-          fi
-
-          git commit -m "Update zh-TW translations from main"
-          git push origin HEAD:zh-TW
diff --git a/scripts/translate_zh_tw.py b/scripts/translate_zh_tw.py
deleted file mode 100644
index c56b0cc..0000000
--- a/scripts/translate_zh_tw.py
+++ /dev/null
@@ -1,306 +0,0 @@
-from __future__ import annotations
-
-import json
-import os
-import subprocess
-import textwrap
-import urllib.error
-import urllib.request
-from pathlib import Path
-
-
-MODELS_ENDPOINT = "https://models.github.ai/inference/chat/completions"
-ZERO_SHA = "0" * 40
-
-
-def run_git(*args: str, cwd: Path | None = None) -> str:
-    result = subprocess.run(
-        ["git", *args],
-        cwd=cwd,
-        check=True,
-        capture_output=True,
-        text=True,
-        encoding="utf-8",
-    )
-    return result.stdout.strip()
-
-
-def supported_source_files(repo_root: Path) -> list[Path]:
-    files = [repo_root / "README.md"]
-    docs_dir = repo_root / "docs"
-    if docs_dir.exists():
-        files.extend(
-            path
-            for path in sorted(docs_dir.rglob("*.md"))
-            if not path.name.endswith(".zh-TW.md")
-        )
-    return [path for path in files if path.exists()]
-
-
-def is_supported_source(rel_path: Path) -> bool:
-    posix = rel_path.as_posix()
-    if posix == "README.md":
-        return True
-    return posix.startswith("docs/") and posix.endswith(".md") and not posix.endswith(".zh-TW.md")
-
-
-def target_for_source(rel_path: Path) -> Path:
-    if rel_path.suffix != ".md" or rel_path.name.endswith(".zh-TW.md"):
-        raise ValueError(f"Unsupported source path: {rel_path}")
-    return rel_path.with_name(f"{rel_path.stem}.zh-TW.md")
-
-
-def parse_changed_files(repo_root: Path, before_sha: str, after_sha: str) -> tuple[set[Path], set[Path]]:
-    changed_sources: set[Path] = set()
-    deleted_targets: set[Path] = set()
-
-    if not before_sha or before_sha == ZERO_SHA:
-        for file_path in supported_source_files(repo_root):
-            changed_sources.add(file_path.relative_to(repo_root))
-        return changed_sources, deleted_targets
-
-    diff_output = run_git(
-        "diff",
-        "--name-status",
-        "-M",
-        "--find-renames",
-        before_sha,
-        after_sha,
-        "--",
-        "README.md",
-        "docs",
-        cwd=repo_root,
-    )
-
-    for line in diff_output.splitlines():
-        if not line.strip():
-            continue
-
-        parts = line.split("\t")
-        status = parts[0]
-
-        if status.startswith("R") and len(parts) == 3:
-            old_path = Path(parts[1])
-            new_path = Path(parts[2])
-            if is_supported_source(new_path):
-                changed_sources.add(new_path)
-            if is_supported_source(old_path):
-                deleted_targets.add(target_for_source(old_path))
-            continue
-
-        if len(parts) < 2:
-            continue
-
-        rel_path = Path(parts[1])
-        if not is_supported_source(rel_path):
-            continue
-
-        if status == "D":
-            deleted_targets.add(target_for_source(rel_path))
-        else:
-            changed_sources.add(rel_path)
-
-    return changed_sources, deleted_targets
-
-
-def load_skill_context() -> str:
-    skill_dir = Path(
-        os.environ.get(
-            "TRANSLATE_SKILL_DIR",
-            Path.home() / ".copilot" / "skills" / "taiwanese-mandarin-translate",
-        )
-    )
-    required_files = [
-        skill_dir / "SKILL.md",
-        skill_dir / "EXAMPLES.md",
-        skill_dir / "references" / "vocabulary.md",
-    ]
-    missing = [str(path) for path in required_files if not path.exists()]
-    if missing:
-        raise FileNotFoundError(f"Missing translation skill files: {', '.join(missing)}")
-
-    parts: list[str] = []
-    for path in required_files:
-        header = path.relative_to(skill_dir).as_posix()
-        parts.append(f"## {header}\n{path.read_text(encoding='utf-8')}")
-    return "\n\n".join(parts)
-
-
-def build_system_prompt(skill_context: str) -> str:
-    return textwrap.dedent(
-        f"""
-        You are a translation engine for repository documentation.
-
-        Follow the translation skill below as the highest-priority style guide.
-        Output only the final translated Markdown for the target file. Do not add explanations.
-        Preserve headings, tables, links, code fences, inline code, placeholders, HTML, and file paths.
-        Keep brands, APIs, commands, and technical identifiers in the source language unless translation is clearly required.
-        Prefer Taiwanese Mandarin written in Traditional Chinese used in Taiwan.
-        Reuse accurate wording from the existing zh-TW file where possible so unchanged sections stay stable.
-
-        {skill_context}
-        """
-    ).strip()
-
-
-def build_user_prompt(
-    source_path: Path,
-    source_markdown: str,
-    existing_translation: str | None,
-    source_diff: str | None,
-) -> str:
-    existing_block = existing_translation if existing_translation else "[No existing translation file]"
-    diff_block = source_diff if source_diff else "[No prior diff available. Produce a full up-to-date translation.]"
-    return textwrap.dedent(
-        f"""
-        Update the Traditional Chinese (Taiwan) translation for this repository file.
-
-        Source file: {source_path.as_posix()}
-        Target file: {target_for_source(source_path).as_posix()}
-
-        English source diff against previous main:
-        ```diff
-        {diff_block}
-        ```
-
-        Current English source Markdown:
-        ```markdown
-        {source_markdown}
-        ```
-
-        Existing zh-TW Markdown:
-        ```markdown
-        {existing_block}
-        ```
-
-        Requirements:
-        - Return the full final contents for the target file only.
-        - Match the English source completely.
-        - Preserve Markdown structure and link targets.
-        - Keep terminology natural for Taiwan readers.
-        - Keep unchanged sections stable when the existing translation is already correct.
-        """
-    ).strip()
-
-
-def request_translation(model: str, system_prompt: str, user_prompt: str, github_token: str) -> str:
-    payload = {
-        "model": model,
-        "temperature": 0.2,
-        "messages": [
-            {"role": "system", "content": system_prompt},
-            {"role": "user", "content": user_prompt},
-        ],
-    }
-    request = urllib.request.Request(
-        MODELS_ENDPOINT,
-        data=json.dumps(payload).encode("utf-8"),
-        headers={
-            "Accept": "application/vnd.github+json",
-            "Authorization": f"Bearer {github_token}",
-            "Content-Type": "application/json",
-            "X-GitHub-Api-Version": "2022-11-28",
-        },
-        method="POST",
-    )
-
-    try:
-        with urllib.request.urlopen(request) as response:
-            body = response.read().decode("utf-8")
-    except urllib.error.HTTPError as exc:
-        error_body = exc.read().decode("utf-8", errors="replace")
-        raise RuntimeError(f"GitHub Models request failed: HTTP {exc.code} {error_body}") from exc
-
-    parsed = json.loads(body)
-    choices = parsed.get("choices", [])
-    if not choices:
-        raise RuntimeError(f"GitHub Models returned no choices: {body}")
-
-    content = choices[0].get("message", {}).get("content", "")
-    if not content:
-        raise RuntimeError(f"GitHub Models returned empty content: {body}")
-    return content.rstrip() + "\n"
-
-
-def source_diff(repo_root: Path, before_sha: str, after_sha: str, rel_path: Path) -> str | None:
-    if not before_sha or before_sha == ZERO_SHA:
-        return None
-
-    try:
-        diff_text = run_git(
-            "diff",
-            "--unified=3",
-            before_sha,
-            after_sha,
-            "--",
-            rel_path.as_posix(),
-            cwd=repo_root,
-        )
-    except subprocess.CalledProcessError:
-        return None
-
-    return diff_text or None
-
-
-def translate_files() -> None:
-    repo_root = Path(os.environ.get("GITHUB_WORKSPACE", Path.cwd())).resolve()
-    output_dir = Path(os.environ["TRANSLATION_OUTPUT_DIR"]).resolve()
-    output_dir.mkdir(parents=True, exist_ok=True)
-
-    github_token = os.environ["GITHUB_TOKEN"]
-    before_sha = os.environ.get("GITHUB_EVENT_BEFORE", "")
-    after_sha = os.environ.get("GITHUB_SHA", "HEAD")
-    translate_all = os.environ.get("TRANSLATE_ALL", "").lower() == "true"
-    model = os.environ.get("TRANSLATE_MODEL", "openai/gpt-4.1-mini")
-
-    if translate_all:
-        changed_sources = {path.relative_to(repo_root) for path in supported_source_files(repo_root)}
-        deleted_targets: set[Path] = set()
-    else:
-        changed_sources, deleted_targets = parse_changed_files(repo_root, before_sha, after_sha)
-
-    skill_context = load_skill_context()
-    system_prompt = build_system_prompt(skill_context)
-
-    written_files: list[str] = []
-    for rel_source in sorted(changed_sources):
-        source_path = repo_root / rel_source
-        target_rel = target_for_source(rel_source)
-        existing_target = repo_root / target_rel
-
-        source_markdown = source_path.read_text(encoding="utf-8")
-        existing_translation = None
-        if existing_target.exists():
-            existing_translation = existing_target.read_text(encoding="utf-8")
-
-        translation = request_translation(
-            model=model,
-            system_prompt=system_prompt,
-            user_prompt=build_user_prompt(
-                source_path=rel_source,
-                source_markdown=source_markdown,
-                existing_translation=existing_translation,
-                source_diff=source_diff(repo_root, before_sha, after_sha, rel_source),
-            ),
-            github_token=github_token,
-        )
-
-        output_path = output_dir / target_rel
-        output_path.parent.mkdir(parents=True, exist_ok=True)
-        output_path.write_text(translation, encoding="utf-8")
-        written_files.append(target_rel.as_posix())
-        print(f"Translated {rel_source.as_posix()} -> {target_rel.as_posix()}")
-
-    manifest = {
-        "written": written_files,
-        "deleted": sorted(path.as_posix() for path in deleted_targets),
-    }
-    (output_dir / "manifest.json").write_text(
-        json.dumps(manifest, indent=2, ensure_ascii=False) + "\n",
-        encoding="utf-8",
-    )
-    print(json.dumps(manifest, indent=2, ensure_ascii=False))
-
-
-if __name__ == "__main__":
-    translate_files()

From eb63d6a053d0520189fef6ab634aa7390db84a22 Mon Sep 17 00:00:00 2001
From: Jamestsai 
Date: Sat, 13 Jun 2026 16:31:20 +0800
Subject: [PATCH 7/7] Refine zh-TW docs with skill v0.1.2 and restore source
 links
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Re-polish the Traditional Chinese (Taiwan) docs using taiwanese-mandarin-translate-skill v0.1.2, then restore external links and key facts the earlier condensed pass had dropped.

Phase 1 (terminology and fixes):
- Fix repeated 'hedging' mistranslation in 02 and 04
- Unify terms: optimize->最佳化, configure->設定, data->資料
- Add missing key numbers (token counts, 36%, input vs output callout)

Phase 2 (restore source links and facts):
- 01: seat AI-credit amounts, code completion unlimited, output-control ROI line
- 04: Content Exclusion doc link plus RTK complement note
- 06: RTK section, three vendor prompting-guide links, /chronicle link
- 08: CodeAct plugin and dfberry writeup links
- 10: source links, vendor guides, RTK install
- 11: pricing-perspective sources, Anthropic pricing, configuring AI models
- 12: external links

Fix cross-doc anchor 06->08 to #277-rtk (rendered slug). mkdocs build --strict passes; Chinese-mainland term scan returns zero hits.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 docs/01-why-tokens-matter.zh-TW.md     |  4 ++--
 docs/02-prompt-compression.zh-TW.md    | 16 ++++++++++------
 docs/04-context-management.zh-TW.md    |  6 +++---
 docs/06-workflow-optimization.zh-TW.md | 16 ++++++++++++++--
 docs/07-agents-md-problem.zh-TW.md     |  2 +-
 docs/08-mcp-tool-costs.zh-TW.md        |  8 +++++---
 docs/10-practical-setup.zh-TW.md       | 12 +++++++++++-
 docs/11-models-and-pricing.zh-TW.md    |  6 ++++++
 docs/12-enterprise-governance.zh-TW.md | 18 +++++++++++-------
 9 files changed, 63 insertions(+), 25 deletions(-)

diff --git a/docs/01-why-tokens-matter.zh-TW.md b/docs/01-why-tokens-matter.zh-TW.md
index ce0a27f..f77f8d5 100644
--- a/docs/01-why-tokens-matter.zh-TW.md
+++ b/docs/01-why-tokens-matter.zh-TW.md
@@ -39,11 +39,11 @@ 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 就是錢。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。 |
+| **計費** | 自 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` 裡一行設定直接控制。
 
diff --git a/docs/02-prompt-compression.zh-TW.md b/docs/02-prompt-compression.zh-TW.md
index b68a28c..21d888f 100644
--- a/docs/02-prompt-compression.zh-TW.md
+++ b/docs/02-prompt-compression.zh-TW.md
@@ -30,7 +30,7 @@
 | 冗長 | "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%**。
+在這個刻意塞滿填充詞的例子裡可節省 **75%**，而且模型對兩種寫法的理解一樣好。對本來就寫得相對精簡的開發者 prompt，常見節省幅度通常是 **30–50%**。
 
 **常見模式：** `[物件] [動作] [原因]。[下一步]`
 
@@ -48,14 +48,14 @@
 
 ### Lite：專業但精簡
 
-刪掉填充詞與保留語氣，但保留冠詞與完整句子。
+刪掉填充詞與模糊保留，但保留冠詞與完整句子。
 
 ```text
 "Your component re-renders because you create a new object reference
 each render. Wrap it in useMemo."
 ```
 
-適合：對外文件、需要完整清晰表達的情境。
+約 20 tokens。適合：對外文件、新人上手文件、需要完整清晰表達的情境。
 
 ### Full：經典原始人模式（預設）
 
@@ -66,7 +66,7 @@ each render. Wrap it in useMemo."
 Wrap in useMemo."
 ```
 
-適合：日常開發、多數 Copilot 互動。
+約 18 tokens。適合：日常開發、多數 Copilot 互動。
 
 ### Ultra：最大壓縮
 
@@ -76,7 +76,11 @@ Wrap in useMemo."
 "Inline obj prop → new ref → re-render. useMemo."
 ```
 
-適合：高頻互動、你對領域非常熟時。
+約 10 tokens。適合：高頻互動、你對領域非常熟時。
+
+**估計各等級的節省幅度：**
+
+> **輸入 vs 輸出：** 輸入節省來自把 prompt 寫精簡；輸出節省則來自在 system instructions（例如 `copilot-instructions.md`）設定精簡輸出。把 prompt 寫精簡，並不會自動讓模型用精簡方式回答，兩者都要設。
 
 | 等級 | 輸入節省 | 輸出節省† | 品質影響 |
 |------|----------|-----------|----------|
@@ -112,7 +116,7 @@ Validate:
 Save to DB
 ```
 
-結構化寫法通常更省，也更清楚。
+**可節省約 36%**，而且結構化版本可以說更清楚，因為它逼你把各項需求分開列。
 
 ## 2.1.4 縮寫與簡寫
 
diff --git a/docs/04-context-management.zh-TW.md b/docs/04-context-management.zh-TW.md
index 25367b2..54f2780 100644
--- a/docs/04-context-management.zh-TW.md
+++ b/docs/04-context-management.zh-TW.md
@@ -12,7 +12,7 @@
 
 > **補充：相關但不同的慣例。** `.github/copilot-instructions.md` 是 GitHub Copilot 原生的 repo 級 instruction 檔；`AGENTS.md` 則是跨工具慣例，Copilot 也會讀。它們不是同一個檔案，但共同點是：都屬於 **always-on context**。如果內容重複，就等於每次互動重複付費。
 
-這也是最值得優化的檔案之一。假設 instruction 檔有 500 字、約 700 tokens，你每次問問題前就先燒掉 700 tokens。
+這也是最值得最佳化的檔案之一。假設 instruction 檔有 500 字、約 700 tokens，你每次問問題前就先燒掉 700 tokens。
 
 **壓縮前：**
 
@@ -39,7 +39,7 @@ Fragments OK. Short synonyms. Code unchanged.
 **原則：**
 
 - 先合併重複內容，再做壓縮
-- 刪掉冠詞、填充詞、客套話與保留語氣
+- 刪掉冠詞、填充詞、模糊保留與客套話
 - 保留程式碼區塊、inline code、URL、路徑與技術詞
 - 保持 Markdown 結構不被破壞
 
@@ -54,7 +54,7 @@ Copilot 會自動納入工作區中的內容，例如開啟中的檔案、匯入
 - **對 build output、vendor、generated files 使用 `.gitignore`。**
 - **使用 `applyTo:` 範圍化 instruction 檔**，讓特定規則只在相關檔案出現時才載入。
 - **在 AI 工作前，先把非純文字檔轉成 Markdown。** 這是處理富格式輸入時，最直接的 token 節省。
-- **Business／Enterprise 環境下**，可請管理員設定 Content Exclusion 做政策與敏感路徑控管。
+- **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 旋鈕。
 
 要小心的高風險檔案包括：
 
diff --git a/docs/06-workflow-optimization.zh-TW.md b/docs/06-workflow-optimization.zh-TW.md
index 345572f..392b857 100644
--- a/docs/06-workflow-optimization.zh-TW.md
+++ b/docs/06-workflow-optimization.zh-TW.md
@@ -39,7 +39,7 @@ L42: bug: user can be null here. Add null guard before .email access.
 
 - `🔴` Bug / security，必修
 - `🟡` Suggestion，建議修
-- `🔵` Nit，可選優化
+- `🔵` Nit，可選最佳化
 - `❓` Question，需要釐清
 
 ## 2.5.3 Ask Mode vs. Agent Mode
@@ -69,6 +69,10 @@ L42: bug: user can be null here. Add null guard before .email access.
 - 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 模型選擇
 
 模型選擇器本身就是重要的成本控制介面。把高成本模型長時間釘住，代表連最簡單的互動都會用高費率計價。
@@ -94,6 +98,14 @@ L42: bug: user can be null here. Add null guard before .email access.
 保留行為不變，但減少錯誤回合與澄清成本。
 ```
 
+各家官方 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) |
+
 適用時機：
 
 - 換了預設模型
@@ -113,7 +125,7 @@ L42: bug: user can be null here. Add null guard before .email access.
 ## 2.5.7 用 `/chronicle` 關閉回饋迴路
 
 Token 浪費不只發生在單一 prompt，也會發生在你沒察覺的重複模式上。  
-`/chronicle` 能分析你的本機 session 歷史，找出 Copilot 常誤解你的地方。
+[`/chronicle`](https://docs.github.com/en/copilot/concepts/agents/copilot-cli/chronicle) 能分析你的本機 session 歷史，找出 Copilot 常誤解你的地方。
 
 最有價值的是：
 
diff --git a/docs/07-agents-md-problem.zh-TW.md b/docs/07-agents-md-problem.zh-TW.md
index c9fa857..3716a14 100644
--- a/docs/07-agents-md-problem.zh-TW.md
+++ b/docs/07-agents-md-problem.zh-TW.md
@@ -14,7 +14,7 @@
 
 ETH Zurich 的研究（Gloaguen 等，AGENTBENCH，2026 年 2 月）在 12 個 repositories、138 個任務與 4 種 coding agents 上測試後，得到的結果是：
 
-| 發現 | 數據 |
+| 發現 | 資料 |
 |------|------|
 | LLM 產生的 context files 會降低表現 | 8 種設定中有 5 種表現下滑 |
 | 平均正確率變化 | **−2%** |
diff --git a/docs/08-mcp-tool-costs.zh-TW.md b/docs/08-mcp-tool-costs.zh-TW.md
index 309c455..a1afdc4 100644
--- a/docs/08-mcp-tool-costs.zh-TW.md
+++ b/docs/08-mcp-tool-costs.zh-TW.md
@@ -78,7 +78,7 @@ Agent mode 走 15 steps：
 - 不用的 MCP server 真的要關
 - schema 成本是每步都重付，不是只付一次
 
-## 2.7.5 每個 Workspace 各自配置 MCP
+## 2.7.5 每個 Workspace 各自設定 MCP
 
 不要把所有 MCP server 都全域開著。  
 做法是：
@@ -96,7 +96,7 @@ Agent mode 走 15 steps：
 4. **注意總 tool 數量**
 5. **在 custom instructions 補一句**，例如：`Minimize tool calls. Read files only when necessary.`
 6. **偶爾才用的能力，優先做成 skill，不是 MCP**
-7. **Copilot CLI 長工具鏈可考慮 CodeAct**
+7. **Copilot CLI 長工具鏈可考慮 CodeAct**（外部外掛 [`copilot-codeact-plugin`](https://github.com/jsturtevant/copilot-codeact-plugin)）
 8. **用 RTK 壓縮工具輸出**
 
 ## 2.7.7 從源頭壓縮工具輸出：RTK
@@ -132,7 +132,7 @@ MCP schema 是「工作開始前」的成本。另一個大頭是 shell 命令
 ## 2.7.8 案例：把大型 Plugin 範圍化
 
 大型 plugin 常常是一整個 `System/Tools` 成本大戶。  
-以 Azure MCP 為例，若預設載入 200+ tools，單一 plugin 就可能吃掉數萬 tokens。
+以 Azure MCP 為例，若預設載入 200+ tools，單一 plugin 就可能吃掉數萬 tokens。Microsoft／GitHub 內容貢獻者 Dina Berry 實測一套真實的 Copilot CLI 設定，發現單一 Azure plugin 每則訊息就載入約 27K tokens，跑 `/context` 之前完全看不出來。
 
 做法通常有兩種：
 
@@ -144,6 +144,8 @@ MCP schema 是「工作開始前」的成本。另一個大頭是 shell 命令
 - 當 `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/10-practical-setup.zh-TW.md b/docs/10-practical-setup.zh-TW.md
index 8694857..cf89398 100644
--- a/docs/10-practical-setup.zh-TW.md
+++ b/docs/10-practical-setup.zh-TW.md
@@ -81,6 +81,8 @@ Errors: Result pattern, no thrown exceptions in business logic.
 
 核心原則：**不要把 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 還是最佳做法。  
@@ -92,6 +94,8 @@ Errors: Result pattern, no thrown exceptions in business logic.
 請它在不改變行為的前提下，降低錯誤與返工。
 ```
 
+各家官方 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 檔只能影響行為，真正的計費控制在別處。  
@@ -189,7 +193,13 @@ Agent 會讀它們，把它們也當成 context。
 
 ### 4.3.6 用 RTK 壓縮 Shell 輸出
 
-Coding Agent 會跑很多 shell 指令，輸出都會回灌成下一步的輸入 token。RTK 能把這些結果先壓縮再交給 agent。
+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 建立習慣
 
diff --git a/docs/11-models-and-pricing.zh-TW.md b/docs/11-models-and-pricing.zh-TW.md
index dc796f1..352c794 100644
--- a/docs/11-models-and-pricing.zh-TW.md
+++ b/docs/11-models-and-pricing.zh-TW.md
@@ -46,6 +46,8 @@ repo 中一直建議把 **Auto** 當預設，這個方向仍然正確，但要
 | 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 單價」表。  
@@ -57,6 +59,8 @@ GitHub 目前沒有公開各 Copilot 模型的「輸入 token 單價 vs 輸出 t
 | Claude Sonnet 4.6 | $3 | $15 |
 | Claude Opus 4.6 | $5 | $25 |
 
+來源：[Anthropic Pricing](https://platform.claude.com/docs/en/about-claude/pricing)。
+
 這能幫你建立正確直覺：
 
 - 輸出 token 的成本明顯更高
@@ -116,6 +120,8 @@ GitHub 目前沒有公開各 Copilot 模型的「輸入 token 單價 vs 輸出 t
 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)
diff --git a/docs/12-enterprise-governance.zh-TW.md b/docs/12-enterprise-governance.zh-TW.md
index 306012f..1e27fed 100644
--- a/docs/12-enterprise-governance.zh-TW.md
+++ b/docs/12-enterprise-governance.zh-TW.md
@@ -20,7 +20,7 @@ Prompt 壓縮依然重要，但那是**用量效率**槓桿，不是管理員計
 
 ## 1. 先設定預算
 
-在 2026 年 6 月 1 日之後，Business 與 Enterprise 的治理主軸改成 AI credits 與 usage-based billing。
+在 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 文件中的重點：
 
@@ -29,6 +29,8 @@ GitHub 文件中的重點：
 - 也有 user-level budgets
 - **使用者預算設為 `$0`** 代表該使用者無法使用 usage-based 功能
 
+要注意一個重點：預算**不會**讓 prompt 變小，也**不會**減少每個 prompt 的 token，它只是替 AI credit 支出設上限。
+
 實務預設：
 
 1. 先用非零測試預算啟動 rollout
@@ -38,7 +40,7 @@ GitHub 文件中的重點：
 
 ## 2. 用 User-Level Budgets 做每人收緊
 
-對 Business / Enterprise 來說，2026/06/01 之後最乾淨的每人上限，就是 **user-level AI credit budget**。
+對 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 功能。
 
 管理思維應轉成：
 
@@ -51,9 +53,11 @@ GitHub 文件中的重點：
 2. 重度使用者只有在工作需要明確時才提高
 3. 每月檢查，價值不明顯的使用者再降回來
 
+> **舊制備註：** 若你還在為 6/1 之前的客戶做準備，[premium request management](https://docs.github.com/en/copilot/concepts/billing/premium-request-management) 說明的是即將淘汰的控制模型，只能當成過渡期指引。
+
 ## 3. 啟用模型前先審查
 
-GitHub 支援由 organization 或 enterprise owner 控制成員可用的 AI 模型。  
+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)。
 把這當成**官方支援的模型治理方式**。
 
 建議的審查清單：
@@ -68,8 +72,8 @@ GitHub 支援由 organization 或 enterprise owner 控制成員可用的 AI 模
 
 GitHub 文件區分：
 
-- **repository instructions**
-- **organization instructions**
+- **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)）
 
 重要的是它們的套用範圍不同。  
 尤其對成本控制來說，要注意：
@@ -104,7 +108,7 @@ GitHub 文件區分：
 3. 哪些模型真的和更好結果有關，而不是只是習慣
 4. 哪些 agent workflows 花很多錢，卻沒有相稱交付價值
 
-外部 benchmark 可以做補充，但不能取代你自己的 Copilot usage data。
+外部 benchmark 可以做補充，但不能取代你自己的 Copilot usage data。[llm-stats.com](https://llm-stats.com/) 可當成獨立的參考點，但請把它當成**補充性 benchmark**，既不是 GitHub 官方指引，也不能取代你自己的 Copilot usage reports。
 
 ## 7. 6 月 1 日切換清單
 
@@ -125,4 +129,4 @@ GitHub 文件區分：
 5. repo instructions 保持小而精
 6. 只有在 cost center／政策邊界真的合理時才拆 org
 
-這套做法刻意很無聊：**先用便宜預設，再用例外方式擴 premium，最後用數據決定是否擴張。**
+這套做法刻意很無聊：**先用便宜預設，再用例外方式擴 premium，最後用量測結果決定是否擴張。**