🎯 專案介紹

本 repo 角色定位：學習路線圖 + 145+ 資源 curation + 簡單 illustrative 案例——三件事為核心、幫想學 AI / AI agent 的人從「不知道從哪開始」走到「能設計多 agent 系統」。

具體做法：

走完整條路線，你會從「LLM 使用者」進階到「agent 系統建構者」——能看懂 framework 在做什麼、能設計多 agent 協作、能寫自己的 MCP server。

📖 關於中英文混用：本專案保留 AI Agent 領域常見英文術語（Prompt Engineering / Context Engineering / Harness / MCP / Skills / RAG 等），因為官方文件、paper、GitHub repo 與 API 文件多以英文為主。每個重要概念會提供 中文理解名 + 英文正式術語 + 一句白話定位，讓讀者能先理解概念，再對接英文生態。完整對照見 resources/glossary.md。

📋 目錄

• 🎯 專案介紹
• 📚 快速開始
  • 線上閱讀
  • 本地下載
  • ✨ 你會收穫什麼？
• 🗺️ 學習地圖（兩條學習路徑）
• 💡 如何學習
• 📚 相關資源
• 🤝 如何貢獻
• 🙏 致謝
• 🎓 引用
• License

📚 快速開始

🚀 第一次接觸 AI agent / 沒寫過 code？

先看 resources/setup-guide.md — 30-45 分鐘從零帶你申請 API key、裝好 Python、跑出第一個 LLM hello-world。

線上閱讀

• 學習地圖（兩條學習路徑） — 看完這節決定走 Track A 還 Track B
• Stage 0 基礎準備 — 已經會 Python / git / API 的人可以直接跳 Stage 1

本地下載

git clone https://github.com/WenyuChiou/awesome-agentic-ai-zh.git
cd awesome-agentic-ai-zh
# 從 stages/00-foundations.md 開始

✨ 你會收穫什麼？

• 📖 完全免費 — MIT 授權，所有內容開放共學
• 🗺️ 兩條學習路徑 — Track A（CLI Power User）給「想 USE 現成 CLI agent」的人；Track B（Agent Builder）給「想 BUILD 自己 agent」的人。共用 Stage 0-2 基礎
• 🛠️ 基礎動手練習 — 每階段附 1-5 個 illustrative 練習（題目 + dual-path SDK 對照 + success criteria）。定位是基礎入門 + 路線確認——chapter-length 深度練習見對應 stage 的 hello-agents / Anthropic Cookbook callout
• 🎯 精選 145+ 個 projects — 每個都附星等推薦、適合誰、教什麼、怎麼跑（含本地 LLM 執行：Ollama、llama.cpp、LocalAI、MLX）
• 🌏 三語完整維護 — 繁中(canonical)/ 簡中 / English,三版皆完整維護、英文非薄翻譯
• 🎓 不只「框架」、還有「Claude Code 生態」 — MCP / Skills / Plugins / SDK 完整堆疊
• 🔬 5 條依使用者分流的延伸路線 — 研究員 / 開發者 / 老師 / 知識工作者 / 日常使用者
• ⏱️ 預估時程寫清楚 — Track A 8-10 週 / Track B 主幹最少 16-22 週、現實 5-7 個月（每週 5-8 hr）

🗺️ 學習地圖（兩條學習路徑）

走完 Stage 0-2（共用基礎） 之後，依你的目的選一條學習路徑：

• Track A — CLI Power User：你想用現成的 CLI agent（Claude Code、Codex、OpenCode、Gemini CLI 等）把工作做順、效率拉高，不打算自己從零寫 agent。3 個 sub-stage（A1-A3）。
• Track B — Agent Builder：你想從零打造自己的 agent——學 framework、寫 ReAct、設計 multi-agent。Stage 3-7 是主路線。

兩條學習路徑不互斥——多數人是先走 A 把 CLI 用起來，再回到 B 學內部運作；或反過來也行。Stage 5（Claude Code 生態）兩條路徑都會用到。

共用基礎（Stage 0-2）

Track A — CLI Power User（想用 CLI 把事情做完）

Track A 預估總時程：含 Stage 0-2（共用基礎）+ A1-A3 + Stage 5 + Stage 8（兩個共用 hub）= 約 8-10 週。核心參考：resources/cli-agents-guide.md。

Track B — Agent Builder（從零打造 agent）

Track B 預估總時程：主幹最少 16-22 週、現實 5-7 個月（每週 5-8 hr 兼職）

兩個共用 hub（Track A + Track B 都會用到）：

• Stage 5 = Claude Code 生態（MCP / Skills / Plugins / Subagents）—— Track A 學 MCP 接 CLI、Track B 學 agent runtime 結構
• Stage 8 = Agent Interfaces（Computer Use / Browser / Sandbox、2024-2026 frontier）—— Track A 學「怎麼用」委派任務、Track B 學「怎麼 build」embed 進 agent

兩個 hub 出現在兩條 track 內、視角不同、學的深度也不同（內文有 Track A / Track B 分視角段）。

💡 想看跨 stage 的完整範例？ 7 步打造你的第一個 AI Agent — 同一個 Paper Summary Bot 從 Stage 1 一路寫到 Stage 7，~350 行真實程式碼（Track B 適用）

走完主幹後，依你的身分挑一條延伸路線繼續走。不確定挑哪條？

💡 「日常使用者」這條路線不必走完主幹就能直接讀——是給「想用 AI、但不一定要寫 code」的人。

💡 如何學習

這份路線圖兼顧概念與實作，目標是帶你從 LLM 使用者一路走到 agent 系統建構者。適合有基本 Python 能力的開發者、研究生、自學者。動手之前，先確認你有：

• 基本 Python — 寫過 function、用過 API、看得懂 JSON
• 基本 git — clone、commit、push
• 想學的動機 — agent 是 2024-2026 變化最快的領域，需要持續投入（2026 仍每月推新 model / 新 framework）

上面有缺的就從 Stage 0 補齊；都會了就直接跳 Stage 1。

主幹分 5 部分：

• Part 1（Stage 0-2）：基礎與 LLM 入門 — Python / git / API、什麼是 LLM、怎麼設計 prompt
• Part 2（Stage 3-4）：建構你的 Agent — 從 tool use 進化到 agent，學主流 framework
• Part 3（Stage 5） 共用 hub — Claude Code 生態系（MCP / Skills / Plugins / Subagents、Track A + B 都會用到）
• Part 4（Stage 6-7）：進階整合 — memory / RAG / multi-agent 協作 / harness engineering
• Part 5（Stage 8） 共用 hub — Agent Interfaces（Computer Use / Browser Use / Code Sandbox、2024-2026 frontier、Track A + B 都會用到）

🔭 三層概念進化：prompt engineering（Stage 2、單一 prompt 怎麼寫）→ context engineering（Stage 3 之後、怎麼動態組 system prompt + memory + retrieved chunks + tool schema）→ harness engineering（Stage 7、agent loop / eval / observability / deploy 整套包成 production system）。3 個術語對應 3 個 phase、不必另外找資源。詳見 stages/02-prompt-engineering.md#-進階context-engineering不是-prompt-engineering-了 跟 stages/07-multi-agent-production.md 必修閱讀 5+6。

走完主幹（14-19 週）後，依你的身分（研究員 / 開發者 / 老師 / 知識工作者 / 日常使用者）挑一條延伸路線繼續走。

最重要的一句話：不要跳過 動手練習。每個 stage 的 動手練習都是「不動手就學不會」的東西，光讀過去後面會卡住。

🎓 動手練習怎麼用才對：每個練習 folder 裡的 starter.py 是完整解答、不是 TODO skeleton。如果你 clone 下來直接 cat starter.py + python test.py pass、會誤以為「我學會了」、其實沒寫一行 code。正確學習法：mv starter.py starter_reference.py、看 signature 不看 body、自己重寫、卡住才回去對照。完整方法論 + 每個 stage 的時間預算 + 卡住處理流程看 docs/HOW_TO_USE.md。

準備好了嗎？從 Stage 0 開始。

📚 相關資源

完整的相關資源（用語說明 + 常用 MCP / Skill highlight + awesome lists + 中文社群）抽到 RESOURCES.md 避免主頁過長。

直接看常用入口、依情境分組：

🚀 入門 / 環境設定

📖 概念 / 用語

🛠 動手實作

🔌 接日常工具 / 找 MCP server

🔬 研究 / production 級

🤝 如何貢獻

這個 repo 是一個 AI 學習文件，如果你也有蒐集很好的資源，也歡迎貢獻：

• 🐛 回報 Bug — 內容錯誤、連結失效、過時資訊 → 開 Issue
• 💡 提建議 — 缺什麼 stage、該加哪個 project → 開 Issue 討論
• 📝 完善內容 — 改進現有 stage 內容、修 typo → 直接 PR
• ✍️ 新增 project — 在某個 stage 加 1-3 個 project，並附上「為什麼這個 project 適合放這個 stage」的說明
• 🌏 翻譯 — 補英文 companion 沒翻到的段落，或翻成其他語言
• 🌱 擔任 Stage / Branch maintainer — 長期 review 特定領域，詳見 CONTRIBUTORS.md

PR 流程跟 style 規範請看 CONTRIBUTING.md 跟 resources/style-guide.md。

📅 想看最近 ship 了什麼 → CHANGELOG.md（最近 14 天）。 Maintainer 內部進度與 launch checklist 放在 .github/launch-checklist.md（內部文件）。

🙏 致謝

Inspiration

• Datawhale Hello-Agents — 中文圈最完整的 chapter-length agent 教材，本 repo 的「章節 + 進度」結構受這份啟發；每個 stage / 練習 folder 都有 📚 callout 點過去深度章節。特別感謝。
• Datawhale 社群 — 中文 ML 共學社群的標竿，本 repo 多個 anchor project 來自這裡
• liyupi/ai-guide — 中文圈最大「AI 資源大全」，跟 Vibe Coding 教學齊全（涵蓋 Agent Skills / RAG / MCP / A2A / Harness Engineering）。本 repo 是「結構化路線」、ai-guide 是「廣度資源庫」，互為補充

其他相關專案

同主題、不同切入角度的清單，搜資源時可以一起用：

• wong2/awesome-mcp-servers — MCP server 清單，按分類整理
• punkpeye/awesome-mcp-servers — 另一份 MCP server 清單
• hesreallyhim/awesome-claude-code — Claude Code 相關工具與 plugin 清單

這些是純清單形式（看到再挑），本 repo 的不同點是有「從 Stage 0 一路走到 production 的學習順序」。

貢獻者

新貢獻者會自動出現在上方。完整列表 → GitHub Contributors。

個人

• @WenyuChiou — Maintainer

🎓 引用

如果這個學習地圖對你的學習或工作有幫助，歡迎引用：

@misc{awesome_agentic_ai_zh_2026,
  title = {awesome-agentic-ai-zh: A Structured Learning Roadmap for Agentic AI},
  author = {Chiou, Wenyu},
  year = {2026},
  url = {https://github.com/WenyuChiou/awesome-agentic-ai-zh},
  note = {8-stage learning path from prerequisites to Agent Interfaces (Computer Use / Browser Use / Sandbox), with curated projects + hello-X demos. Bilingual (zh-TW / English).}
}

📈 Star History

License

MIT。Maintained by @WenyuChiou。

Stage 0 — 基礎準備（Foundations）

繁體中文 | 简体中文 | English

⏱ 時間估算：1-2 週（約 5-15 小時，已具備可跳過）

💡 看不懂某個詞？翻 resources/glossary.md 查 30 秒再回來。Stage 0 還不會碰太多 jargon，但接下來幾 stage 會。 🗺️ 想先看 agent 的全景地圖（為什麼有的 agent 在 terminal、有的在 Telegram、有的在 Jetson 板子）？→ resources/agent-paradigms.md（5 種 agent 型態，10 min 讀完）

📋 本章組成：跳過條件檢查 → 環境設定步驟 → 進入 Stage 1（foundation stage，無「學習目標 / 進入條件」框架）
🔑 關鍵名詞：見 resources/glossary.md（每 stage 用到的術語都收在那裡）

何時可以跳過這個階段

如果你能：

• 寫一個會呼叫公開 API 並解析 JSON 回應的 Python 函式
• 用 git 做 clone、commit、push，並處理基本的 merge 衝突
• 在自己的作業系統上使用命令列（cd、ls、mkdir、執行 script）
• 看懂 YAML / JSON 檔案

→ 直接跳到 Stage 1。

如果做不到，就把這個階段走完。不要跳——後面每個階段都會預設你已經會這些。

📌 學習目標

• 寫 Python：函式、類別、async/await 基本用法
• 用 git：clone、branch、commit、push、基本衝突處理
• 用 REST API：發 GET/POST、解析 JSON、處理 auth header
• 讀寫 YAML 跟 JSON

🛠 動手練習

• 練習：Python — 寫一個 Python script 呼叫 https://api.github.com/users/torvalds 並印出 follower 數量
• 練習：git — clone 任何一個公開 repo，做一次 commit，push 到自己的 fork
• 練習：CLI — 用命令列建幾個資料夾跟檔案（macOS / Linux：mkdir project && cd project && mkdir src tests docs；Windows PowerShell：New-Item -ItemType Directory -Path project,project\src,project\tests,project\docs）、執行 Python script、把輸出存到檔案
• 練習：YAML — 用 Python 讀一個 .yaml 設定檔，改一個值，再寫回去
• 練習：API auth — 去 github.com/settings/tokens 產生一個 personal access token（給最少權限：read:user），呼叫 https://api.github.com/user 需 auth 的 endpoint，看 401（無 token）vs 200（帶 token）的差別。注意：production agent 一定會用到 API auth，所以這一題要做

🎯 精選資源（不是完整 Project，只是學習素材）

按 5 個 prereq 主題分類、18 個資源一張表搞定。挑入口看「適合誰」、想深入點連結看 repo / 網站。

為什麼有這個階段

大多數「AI agent」教學都預設你已經會這些。如果你還沒，就會在奇怪的地方卡關（tool 需要 async、設定檔是 YAML、SDK 安裝要用 git）。在這裡花一週的投資，可以省下後面 10 週以上的挫折。

✅ 走完 Stage 0 了？ 接下來 Stage 1 — LLM 基礎 會用 5-8 小時帶你做完第一次 LLM API 呼叫、認識 token / context window / temperature，以及用 per-token 計價估算實際任務成本。繼續往下走 →

Stage 1 — LLM 基礎（LLM Basics）

繁體中文 | 简体中文 | English

⏱ 時間估算：1 週（約 5-8 小時）

👋 從 Stage 0 來的：好，環境已經夠用——這 5-8 小時：第一次成功呼叫 Claude / GPT / Gemini API、搞懂 token / context window / temperature 怎麼影響輸出、用 per-token 計算實際成本。直接從這裡開始的：先確認你能跑 Python script、有任一家供應商的 API key——做不到請先回 Stage 0。

💡 看不懂某個詞（LLM / token / context window / temperature / RAG / agent⋯）→ 先翻 resources/glossary.md 查 30 秒再回來。

📋 本章組成：學習目標 → 進入條件 → 必修閱讀 →〔可選 · 概念地圖〕→ 動手練習 → 精選 Projects → 自我檢查
🔑 關鍵名詞：見 resources/glossary.md（每 stage 用到的術語都收在那裡）

三個核心詞（先記住、後面 stage 都會用到）

→ 這 3 個詞貫穿後續所有 stage。Stage 1 的目標就是讓你用 API 跑出來、親手摸到它們如何影響輸出。

📌 學習目標

走完這個階段後你會：

• 解釋 LLM 是什麼、token 是什麼、context window 是什麼意思
• 第一次成功呼叫 Claude / GPT / Gemini API 並解析回應
• 在強項上比較四大 LLM 家族（Claude / GPT / Gemini / Llama）
• 用 per-token 計價來估算單次任務的成本

🌐 主流 LLM 家族對比（2026-05 snapshot）

「Claude 跟 GPT 有什麼不同？」「中國模型能用嗎？」「我該裝 Ollama 跑哪個 OSS model？」——這節給你客觀對照。不下「最好」結論——用 強項 / 適合任務 / 弱項 3 維比較、附官方 docs URL讓你自己 verify。

💡 先解釋幾個名詞：

• Context window = LLM 一次能記住的對話量、有上限（譬如 200k token ≈ 15 萬中文字）
• Apache 2.0 / MIT = 可商用 / 可改 / 可閉源的開源條款；Llama Community License = 開源但有條款限制（譬如 ≥ 7 億 MAU 要授權）
• Frontier model = 各家最強旗艦；OSS = open-source、weights 可下載 self-host

🇺🇸 美系商業 frontier（3 家）

這 3 家是 SaaS API、付 token 用、不能 self-host：

🇨🇳 中國商業 + 開源 frontier（7 家）

中文場景的主力——有些純 API（DeepSeek / Kimi / Hunyuan）、有些同時釋出 OSS weights（Qwen / GLM-5.1 / Yi 可在 Ollama 跑）：

⚠️ 小米 MiMo 雖在 resources/cli-agents-guide.md 列入 Hermes Agent routing、但 2026-05 無權威官方 source 可驗證、暫不收進此表。要試 → 透過 Hermes Agent 200+ provider routing 接入。

🌍 西方開源（4 家、self-host 主力）

跑在自己機器、不付 API、隱私敏感場景的主力——可透過 Ollama 一行指令裝起來：

🎯 我該選哪家？（按場景反查）

📊 中立 benchmark 資源（自己 verify、不靠單一 source）

⚠️ 重要警語

• ⚠️ Benchmark ≠ production performance——LLM 在你 specific 任務的表現要自己跑 small eval（譬如貼 10 個你真實 prompt 看哪家答得最像你要的）、不能只看排名選
• ⚠️ Frontier 6 個月洗牌一次——上面所有數字是 2026-05 snapshot、之後請以官方 docs / Artificial Analysis 為準
• ⚠️ 「強項」是 relative、不是 absolute——所有 frontier model 都能完成基本任務、差別在邊際情境
• ⚠️ 中文場景看 SuperCLUE——一般國際 benchmark（如 MMLU）以英文為主、中文表現可能跟英文不一致

🚪 進入條件

你應該已經：

• 能跑 Python script
• 概念上知道 HTTP / REST 是什麼
• 至少有一家供應商的 API key（Anthropic / OpenAI / Google）

如果還沒——先回 Stage 0。

📚 必修閱讀

1. Anthropic — Claude 模型總覽 — 官方模型 family、含 2026 最新 Opus 4.7 / Sonnet 4.6 / Haiku 4.5
2. anthropics/courses — Anthropic API Fundamentals ⭐⭐⭐⭐⭐ ★ 21k+ — Anthropic 官方 5 course umbrella、module 1「Anthropic API Fundamentals」對應本 stage。Jupyter notebook、用 Claude 3 Haiku（最便宜）跑、跟著做就能拿到 API 基本功
3. OpenAI Quickstart — 第一次 API call 的步驟
4. A Visual Guide to LLM Tokenizers — Hugging Face 的入門
5. Anthropic API Pricing — 把計價表看完，算一下 1k input + 1k output 的成本

🎥 中文影片補充（強烈推薦）：

• 李宏毅 — 生成式 AI 導論（2024 春台大課程） ⭐⭐⭐ — 第 1-5 集講 LLM 是什麼、怎麼運作、token / context window / temperature 怎麼影響輸出。中文圈最高品質的 LLM 學術級導論、台大授課、官方頁含投影片 + YouTube。最新整合版見 GenAI-ML 2025 秋
• 3Blue1Brown — Transformer 視覺化（中文配音版：3Blue1Brown 中文）— LLM 內部運作 visual intro
• Andrej Karpathy — Intro to LLMs — 英文影片、1hr、英文圈最被推薦的 LLM 入門影片

🛠 動手練習（基礎 illustrative 練習）

🦙 本 stage 預設用 Ollama（成本考量、本機 gemma4:e4b 跑得動、$0/run）。每個練習都有 Path A（Ollama、預設）+ Path B（Anthropic、選擇性、想看 cloud 高品質時用）。完整 3 路 trade-off 見 examples/README.md。

💰 Stage 1 預算估算（全 6 練習各跑 3-5 次）：全本機 = $0、全 haiku ≈ $0.30、全 sonnet ≈ $0.90。完整 model 清單 + Stage 1-7 全程預算估算見 examples/README.md#推薦-llm-清單。

💡 不裝 Ollama 也能讀 — 每個練習的 Path B 區塊就是 Anthropic 版、選一個跑就行。先 pip install openai && ollama pull gemma4:e4b 就裝好 Path A 環境。

練習 1：LLM API（hello world）

五行 Python 呼叫 LLM 並印出回應。預設用 Ollama 本機跑（免費、offline）；想看 cloud 答案品質改 Path B Anthropic。詳見 examples/README.md。

# 需要：pip install openai      (用 OpenAI-compatible SDK 跟 Ollama 溝通)
# 前置：ollama pull gemma4:e4b && ollama serve
import sys
if hasattr(sys.stdout, "reconfigure"):
    sys.stdout.reconfigure(encoding="utf-8", errors="replace")

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",  # Ollama 不檢查、隨便填
)

r = client.chat.completions.create(
    model="gemma4:e4b",   # 換成 qwen2.5:3b / llama3.2:3b 也可
    max_tokens=100,
    messages=[{"role": "user", "content": "用一句話自我介紹。"}],
)

# === 自我驗證 ===
text = r.choices[0].message.content
print("回應：", text)
print("usage:", r.usage)

assert r.choices[0].finish_reason in ("stop", "length"), f"非預期 finish_reason: {r.choices[0].finish_reason}"
assert len(text) > 0, "回應不應為空"
assert r.usage.completion_tokens > 0, "output token 應 > 0"
print("✅ 練習 1 通過 — Ollama gemma4:e4b 已能本機回應、$0/次")

回應：嗨！我是 Gemma、一個由 Google 訓練的開源語言模型...
usage: CompletionUsage(completion_tokens=35, prompt_tokens=12, total_tokens=47)
✅ 練習 1 通過 — Ollama gemma4:e4b 已能本機回應、$0/次

# 需要：pip install anthropic
# 環境變數：export ANTHROPIC_API_KEY=sk-ant-...
import sys
if hasattr(sys.stdout, "reconfigure"):
    sys.stdout.reconfigure(encoding="utf-8", errors="replace")

import anthropic

client = anthropic.Anthropic()
msg = client.messages.create(
    model="claude-haiku-4-5",  # haiku 最便宜；換 sonnet 改這行
    max_tokens=100,
    messages=[{"role": "user", "content": "用一句話自我介紹。"}],
)

# === 自我驗證 ===
text = msg.content[0].text
print("回應：", text)
print("usage:", msg.usage)

assert msg.stop_reason in ("end_turn", "max_tokens"), f"非預期 stop_reason: {msg.stop_reason}"
assert len(text) > 0, "回應不應為空"
assert msg.usage.input_tokens > 0 and msg.usage.output_tokens > 0, "token 數應 > 0"
print("✅ 練習 1 通過 — 你已成功打通 Anthropic API")

回應：我是 Claude，一個由 Anthropic 訓練的 AI 助理...
usage: Usage(input_tokens=18, output_tokens=42, ...)
✅ 練習 1 通過 — 你已成功打通 Anthropic API

練習 2：Tokens

同一個 prompt 跑 100 次，觀察 token 數的變化。

• 注意：temperature ≠ 0 會產生變動
• 注意：同一句話的英文 vs 中文 token 數差異

# 需要：pip install openai     (OpenAI-compatible SDK 跟 Ollama 溝通)
# 前置：ollama pull gemma4:e4b && ollama serve
import sys, statistics
if hasattr(sys.stdout, "reconfigure"):
    sys.stdout.reconfigure(encoding="utf-8", errors="replace")

from openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

PROMPTS = {
    "中文": "用一句話描述一隻貓在做什麼。",
    "English": "Describe in one sentence what a cat is doing.",
}

N = 10  # 本機慢、N 小一點；確認 OK 後加大
for label, prompt in PROMPTS.items():
    output_tokens = []
    for _ in range(N):
        r = client.chat.completions.create(
            model="gemma4:e4b",
            max_tokens=80,
            temperature=1.0,  # 拉高 temperature 看 variance
            messages=[{"role": "user", "content": prompt}],
        )
        output_tokens.append(r.usage.completion_tokens)
    print(f"\n[{label}] prompt: {prompt}")
    print(f"  input tokens: {r.usage.prompt_tokens}")
    print(f"  output tokens — min={min(output_tokens)} max={max(output_tokens)} mean={statistics.mean(output_tokens):.1f} stdev={statistics.stdev(output_tokens):.1f}")

# === 自我驗證 ===
assert max(output_tokens) > min(output_tokens), "temperature=1.0 下、output 長度應該有 variance"
print("\n✅ 練習 2 通過 — 觀察到 temperature 對 output token 的 variance、本機跑 $0")
print("💡 中文 prompt 通常 input tokens 比 English 多（中文 token 化通常一字 ≈ 2 tokens）")

[中文] prompt: 用一句話描述一隻貓在做什麼。
  input tokens: 32
  output tokens — min=18 max=58 mean=35.2 stdev=11.4

✅ 練習 2 通過 — 觀察到 temperature 對 output token 的 variance、本機跑 $0

# 需要：pip install anthropic
import sys, statistics
if hasattr(sys.stdout, "reconfigure"):
    sys.stdout.reconfigure(encoding="utf-8", errors="replace")

import anthropic

client = anthropic.Anthropic()
PROMPTS = {"中文": "用一句話描述一隻貓在做什麼。", "English": "Describe in one sentence what a cat is doing."}

for label, prompt in PROMPTS.items():
    output_tokens = []
    for _ in range(20):
        msg = client.messages.create(model="claude-haiku-4-5", max_tokens=80, temperature=1.0,
                                     messages=[{"role": "user", "content": prompt}])
        output_tokens.append(msg.usage.output_tokens)
    print(f"[{label}] input={msg.usage.input_tokens} output min/max/mean={min(output_tokens)}/{max(output_tokens)}/{sum(output_tokens)/len(output_tokens):.1f}")

練習 3：Pricing / Latency

Cost-sensitive 工作必修：算出你的 hello-world prompt 跑 1000 次在不同 model 上的成本。Ollama 本機是 $0 但有 latency 成本；Cloud LLM 有 $ 成本但快。會算這兩個 trade-off 才能挑對 model。

# 需要：pip install openai
# 前置：ollama pull gemma4:e4b && ollama serve
import sys, time
if hasattr(sys.stdout, "reconfigure"):
    sys.stdout.reconfigure(encoding="utf-8", errors="replace")

from openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

# 量 5 次 latency
latencies = []
for _ in range(5):
    t0 = time.time()
    r = client.chat.completions.create(
        model="gemma4:e4b",
        max_tokens=200,
        messages=[{"role": "user", "content": "你好！自我介紹一下。"}],
    )
    latencies.append(time.time() - t0)

# 統計
avg_latency = sum(latencies) / len(latencies)
out_tok_avg = r.usage.completion_tokens  # 末次當代表
tps = out_tok_avg / avg_latency if avg_latency > 0 else 0

print(f"model: gemma4:e4b (本機)")
print(f"5 次 latency (sec): min={min(latencies):.2f} max={max(latencies):.2f} mean={avg_latency:.2f}")
print(f"avg output: {out_tok_avg} tokens、約 {tps:.1f} tokens/sec")
print(f"\n1000 次成本: $0 (本機)、預計時長: {avg_latency * 1000 / 60:.1f} 分鐘")

# === 自我驗證 ===
assert avg_latency > 0, "latency 應 > 0"
assert out_tok_avg > 0, "output token 應 > 0"
print(f"\n✅ 練習 3 通過 — 本機 model $0 但要花 {avg_latency * 1000 / 60:.0f} 分鐘跑 1000 次")
print("💡 對照 Path B Anthropic：1000 次只要 ~10-20 分鐘但要 $0.25（haiku）")

model: gemma4:e4b (本機)
5 次 latency (sec): min=4.21 max=8.93 mean=6.54
avg output: 48 tokens、約 7.3 tokens/sec

1000 次成本: $0 (本機)、預計時長: 109.0 分鐘

✅ 練習 3 通過 — 本機 model $0 但要花 109 分鐘跑 1000 次
💡 對照 Path B Anthropic：1000 次只要 ~10-20 分鐘但要 $0.25（haiku）

# 需要：pip install anthropic
import sys
if hasattr(sys.stdout, "reconfigure"):
    sys.stdout.reconfigure(encoding="utf-8", errors="replace")

import anthropic

# Anthropic 2026 Q2 公開計價（每 1M token、USD）— 跑前對照 https://www.anthropic.com/pricing
PRICING = {
    "claude-haiku-4-5":   {"input": 1.00, "output":  5.00},
    "claude-sonnet-4-6":  {"input": 3.00, "output": 15.00},
    "claude-opus-4-7":    {"input": 5.00, "output": 25.00},  # Opus 4.7 (April 2026) 價格下調至 5/25
}

client = anthropic.Anthropic()
MODEL = "claude-haiku-4-5"

msg = client.messages.create(model=MODEL, max_tokens=200,
                             messages=[{"role": "user", "content": "你好！自我介紹一下。"}])
in_tok, out_tok = msg.usage.input_tokens, msg.usage.output_tokens
rates = PRICING[MODEL]
cost_one = (in_tok * rates["input"] + out_tok * rates["output"]) / 1_000_000

print(f"model: {MODEL}")
print(f"single: input={in_tok} output={out_tok} → ${cost_one:.6f}")
print(f"1000 calls cost across model tiers:")
for name, r in PRICING.items():
    c = (in_tok * r["input"] + out_tok * r["output"]) / 1_000_000 * 1000
    print(f"  {name:<22} ${c:.4f}")

# === 自我驗證 ===
assert cost_one > 0, "Cloud LLM 一定有成本"
print(f"\n✅ 練習 3 通過（Anthropic）— 1000 次 haiku ≈ $0.25、sonnet 4.6 ≈ $0.76、opus 4.7 ≈ $1.27")

model: claude-haiku-4-5
single: input=14 output=48 → $0.000254
1000 calls cost across model tiers:
  claude-haiku-4-5       $0.2540
  claude-sonnet-4-6      $0.7620
  claude-opus-4-7        $1.2700

練習 4：Cross-Provider 比較

同一個 prompt 同時送給 Claude、GPT、Gemini，比較三家的回應差異。觀察「同一句話為什麼產生不同答案」——回答風格、長度、判斷取捨都不一樣。建議用 OpenAI、Anthropic、Google 三家 SDK 各一段程式呼叫。

→ 基礎 starter 範本 → examples/stage-1/04-cross-provider/（含三家 SDK 並行呼叫 + table 對照、缺哪家 key 就 skip 哪家；illustrative，不是 chapter-length 完整教學）

練習 5：Error Handling

故意觸發錯誤情境並寫 retry：

• API key 錯誤 → 看怎麼 raise
• prompt 超長 → context window 滿了會發生什麼
• 網路斷掉 → 寫一個有 exponential backoff 的 retry wrapper

這是後面 Stage 3-7 寫 production agent 一定會用到的基礎。

→ 基礎 starter 範本 → examples/stage-1/05-error-handling/（含 mock-based test、不用真的斷網就能驗證 retry 邏輯；illustrative，不是 chapter-length 完整教學）

練習 6：Local LLM

不付 API 費用、跑在自己電腦上：用 Ollama 下載一個小模型（建議 llama3.2:3b 或 qwen2.5:3b），用 OpenAI-相容 API 呼叫它。

# 1. 裝 Ollama: https://ollama.com
ollama pull qwen2.5:3b
ollama serve  # 預設 port 11434

# 需要：pip install openai
# 前置：Ollama 已 serve、qwen2.5:3b 已 pull
import sys
if hasattr(sys.stdout, "reconfigure"):
    sys.stdout.reconfigure(encoding="utf-8", errors="replace")

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",  # Ollama 不檢查、隨便填
)

r = client.chat.completions.create(
    model="qwen2.5:3b",
    messages=[{"role": "user", "content": "用 3 句話介紹什麼是 ReAct。"}],
)

text = r.choices[0].message.content
print("回應：", text)

# === 自我驗證 ===
assert len(text) > 10, "回應太短、Ollama 可能沒跑起來"
print(f"✅ 練習 6 通過 — 你的本機 Ollama 已能透過 OpenAI-compatible API 呼叫")
print(f"💡 跑這次完全沒花錢（除了你的電力）")

回應：ReAct 是一種讓 AI 結合「推理」和「行動」的方法...
✅ 練習 6 通過 — 你的本機 Ollama 已能透過 OpenAI-compatible API 呼叫
💡 跑這次完全沒花錢（除了你的電力）

🎯 精選 Projects

按用途分 5 類、17 個項目一張表搞定。挑入口看「適合誰」、想深入點連結看 repo / 課程網站。

💡 建議閱讀路徑：API 入手就 Anthropic / OpenAI Cookbook → 中文系統路線就 happy-llm + llm-universe → 想深入內部就 Karpathy 影片 + rasbt 書搭 code → 想跑本地就 Ollama 起步、進階再讀 llama.cpp。

✅ 進 Stage 2 前的自我檢查

你能不能：

• 用 5 行 Python 呼叫 Claude API
• 解釋為什麼「你好」可能用 2 個 token，但「Hello」只用 1 個
• 大致說出 Claude Sonnet vs Opus 的 per-token 價格
• 各說出 Claude / GPT / Gemini / Llama 的一個強項

如果可以 → 進 Stage 2 — Prompt Engineering。

如果不行 → 重看 Anthropic Quickstart + 把上面 3 個 hello-X 都跑一次。

✅ Stage 1 完成？ 接下來 Stage 2 — Prompt Engineering 會用 5-12 小時帶你寫出可重用的結構化 prompt、用 few-shot 跟 chain-of-thought 解推理題、並學會用 eval 量化 prompt 改善幅度。繼續往下走 →

Stage 2 — Prompt 設計（Prompt Engineering）

繁體中文 | 简体中文 | English

⏱ 時間估算：1-2 週（約 5-12 小時）

👋 從 Stage 1 來的：好，你會呼叫 API 了——這 5-12 小時：寫出可重用的結構化 prompt、用 few-shot 跟 chain-of-thought 解難題、用 eval 量化 prompt 改善幅度。直接從這裡開始的：先確認你會呼叫 LLM API、會用 token 算成本——做不到請先回 Stage 1。

💡 用語不熟（prompt / few-shot / CoT / system prompt⋯）→ 翻 resources/glossary.md。

📋 本章組成：學習目標 → 進入條件 → 必修閱讀 →〔可選 · 概念地圖〕→ 動手練習 → 精選 Projects → 自我檢查 🔑 關鍵名詞：見 resources/glossary.md（每 stage 用到的術語都收在那裡）

📌 學習目標

走完這個階段後你會：

• 寫出結構化 prompt（角色 + 任務 + 格式 + 範例）
• 應用 few-shot prompting，並知道什麼時候有用
• 在推理任務上使用 chain-of-thought（CoT）
• 反覆迭代修改一個 prompt 並衡量改善
• 看出什麼時候 prompt 已經到極限了（這時你需要 tool / agent）

🚪 進入條件

你應該已經：

• 會呼叫 LLM API（Stage 1）
• 會解析 / 走訪 API 回應

📚 必修閱讀

1. anthropics/prompt-eng-interactive-tutorial ⭐⭐⭐⭐⭐ ★ 35k+ — Anthropic 官方互動教學、9 章 Jupyter notebook（basic / intermediate / advanced + appendix），含 playground 跟 answer key。用 Claude 3 Haiku（最便宜）跑得起來、Stage 2 的 canonical 動手教材。也是 anthropics/courses 5 course umbrella 的 module 2，想看更廣（含 API Fundamentals / Real World Prompting / Eval / Tool Use）直接看 umbrella
2. anthropics/courses — Real World Prompting ⭐⭐⭐⭐ ★ 21k+ — 同 umbrella 的 module 3，「真實情境下怎麼用 prompting」：chatbot / legal / financial / coding 案例 walk-through。看完 #1 再來看 #2
3. Anthropic Prompt Engineering Guide — 官方 docs、配合上面 #1 一起讀
4. OpenAI Prompt Engineering — OpenAI 觀點
5. dair-ai Prompt Engineering Guide — 學術風，深入
6. Anthropic — Prompting Best Practices — 直接清楚

🎥 中文影片補充（強烈推薦）：

• 李宏毅 — 生成式 AI 導論（2024 春台大課程） ⭐⭐⭐ — 中後段集數講 prompt engineering（few-shot、CoT、in-context learning）+ 對應 lab。中文圈最完整的 prompting 學術級教學。最新整合版見 GenAI-ML 2025 秋
• 李宏毅 — 機器學習 2025 春（含 prompt + LLM 章節） — 適合想看 ML 完整背景的人

🛠 動手練習

🦙 本 stage 預設用 Ollama gemma4:e4b（成本考量、$0/run）。Prompt engineering 對小 model 更有教學價值——小 model 對 prompt 質量敏感、能讓你看清楚 system prompt / few-shot / CoT / refinement 各自帶來多少改善。每個練習都有 Path A（Ollama、預設）+ Path B（Anthropic、選擇性）。

💰 Stage 2 預算估算（全 4 練習各跑 3-5 次）：全本機 = $0、全 haiku ≈ $0.20、全 sonnet ≈ $0.60。Few-shot 分類任務的 12 calls × 5 reps ≈ $0.30 haiku / $0.90 sonnet。完整預算見 examples/README.md#推薦-llm-清單。

完整 3 路 trade-off 見 examples/README.md。

練習 1：System Prompt

同樣的 user message，三個不同的 system prompt。觀察人格 / 輸出格式怎麼變。

# 需要：pip install openai
# 前置：ollama pull gemma4:e4b && ollama serve
import sys, json
if hasattr(sys.stdout, "reconfigure"):
    sys.stdout.reconfigure(encoding="utf-8", errors="replace")

from openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

# 同一個 user message、3 個不同 system prompt
SYSTEM_PROMPTS = {
    "嚴肅律師": "你是嚴謹的合約律師。回答要精準、引用法條編號、避免任何主觀形容詞。",
    "幼兒園老師": "你是溫柔的幼兒園老師、要對 5 歲小孩說話。用比喻、口語、少於 80 字。",
    "JSON 機器": "你只回 JSON。schema: {\"answer\": string, \"confidence\": float}",
}

USER_MSG = "請幫我解釋什麼是租賃合約。"

outputs = {}
for label, system in SYSTEM_PROMPTS.items():
    # Note: Ollama 把 system 放 messages 第一筆（不像 Anthropic 用 system= 參數）
    r = client.chat.completions.create(
        model="gemma4:e4b",
        max_tokens=200,
        messages=[
            {"role": "system", "content": system},
            {"role": "user", "content": USER_MSG},
        ],
    )
    outputs[label] = r.choices[0].message.content
    print(f"\n--- [{label}] ---")
    print(outputs[label])

# === 自我驗證 ===
json_output = outputs["JSON 機器"]
assert "{" in json_output and "}" in json_output, "JSON 機器版輸出應該含 JSON braces"
try:
    parsed = json.loads(json_output.strip().split("\n")[-1] if "\n" in json_output else json_output)
    assert "answer" in parsed, "JSON schema 應包含 answer 欄位"
except json.JSONDecodeError:
    pass # 容許 model 回 JSON 含解釋文字、最後一筆才是 JSON
print(f"\n✅ 練習 1 通過 — 同一個問題、3 種人格 / 格式 / 語氣")
print("💡 觀察：律師長、老師短、JSON 機器一定是 {...}")

--- [嚴肅律師] ---
依民法第 421 條...

--- [幼兒園老師] ---
租賃合約就像借玩具給朋友、講好什麼時候還、要付多少糖果...

--- [JSON 機器] ---
{"answer": "租賃合約是當事人約定一方以物租與他方使用...", "confidence": 0.85}

# 需要：pip install anthropic
import sys, json
if hasattr(sys.stdout, "reconfigure"):
    sys.stdout.reconfigure(encoding="utf-8", errors="replace")

import anthropic
client = anthropic.Anthropic()
SYSTEM_PROMPTS = {
    "嚴肅律師": "你是嚴謹的合約律師。回答要精準、引用法條編號、避免任何主觀形容詞。",
    "幼兒園老師": "你是溫柔的幼兒園老師、要對 5 歲小孩說話。用比喻、口語、少於 80 字。",
    "JSON 機器": "你只回 JSON。schema: {\"answer\": string, \"confidence\": float}",
}
USER_MSG = "請幫我解釋什麼是租賃合約。"

outputs = {}
for label, system in SYSTEM_PROMPTS.items():
    # Anthropic 用 system= 參數（不放 messages 內）
    msg = client.messages.create(model="claude-haiku-4-5", max_tokens=200,
                                 system=system, messages=[{"role": "user", "content": USER_MSG}])
    outputs[label] = msg.content[0].text
    print(f"\n--- [{label}] ---")
    print(outputs[label])

# 同樣的 JSON assert（schema 跨 backend 通用）
json_output = outputs["JSON 機器"]
assert "{" in json_output and "}" in json_output
print(f"\n✅ 練習 1 通過（Anthropic）")

練習 2：Few-Shot

挑一個分類任務。先用 0-shot 跑，再用 3-shot 跑。量一下準確率差多少。

# 需要：pip install openai
# 前置：ollama pull gemma4:e4b && ollama serve
import sys
if hasattr(sys.stdout, "reconfigure"):
    sys.stdout.reconfigure(encoding="utf-8", errors="replace")

from openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

# 中文情緒分類（正面 / 負面 / 中立）
TEST_SET = [
    ("這部電影超讚、看完想再看一次！", "正面"),
    ("劇情無聊、演員演技尷尬。", "負面"),
    ("這是一部 2019 年的電影。", "中立"),
    ("我不確定喜不喜歡、可能再想想。", "中立"),
    ("第一集很不錯但第二集就崩了。", "負面"),
    ("看完心情很好、推薦！", "正面"),
]

FEW_SHOT_EXAMPLES = """範例：
input: 這家餐廳的牛排好吃到讓我哭出來。
output: 正面

input: 服務生態度很差、我再也不會來了。
output: 負面

input: 這家店位於新北市三重區。
output: 中立
"""


def classify(text: str, *, use_few_shot: bool) -> str:
    prefix = FEW_SHOT_EXAMPLES + "\n" if use_few_shot else ""
    prompt = f"{prefix}input: {text}\noutput:"
    r = client.chat.completions.create(
        model="gemma4:e4b",
        max_tokens=10,
        messages=[{"role": "user", "content": prompt}],
    )
    return r.choices[0].message.content.strip().splitlines()[0]


def evaluate(use_few_shot: bool) -> tuple[int, int]:
    correct = 0
    for text, label in TEST_SET:
        pred = classify(text, use_few_shot=use_few_shot)
        ok = label in pred
        print(f" {'✓' if ok else '✗'} [{label}] {text[:30]}... → '{pred}'")
        if ok:
            correct += 1
    return correct, len(TEST_SET)


print("=== 0-shot ===")
c0, n = evaluate(use_few_shot=False)
print(f"正確 {c0}/{n} = {c0/n:.0%}")

print("\n=== 3-shot ===")
c3, _ = evaluate(use_few_shot=True)
print(f"正確 {c3}/{n} = {c3/n:.0%}")

# === 自我驗證 ===
assert c3 >= c0, f"預期 3-shot 不比 0-shot 差、實際 {c3} < {c0}（小 model 樣本小、跑幾次比較）"
print(f"\n✅ 練習 2 通過 — 0-shot {c0}/{n}、3-shot {c3}/{n}（本機 $0）")
print("💡 觀察：'中立' 在 0-shot 容易被誤判成正面或負面、3-shot 後改善明顯")
print("💡 小 model（gemma4:e4b）通常 0-shot 表現比 Claude 差更多、所以 few-shot 改善幅度更大")

# 需要：pip install anthropic
# 把 starter Path A 的 client 跟 classify() 改成：
import anthropic
client = anthropic.Anthropic()

def classify(text: str, *, use_few_shot: bool) -> str:
    prefix = FEW_SHOT_EXAMPLES + "\n" if use_few_shot else ""
    msg = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=10,
        messages=[{"role": "user", "content": f"{prefix}input: {text}\noutput:"}],
    )
    return msg.content[0].text.strip().splitlines()[0]
# 其餘 TEST_SET / FEW_SHOT_EXAMPLES / evaluate() 跟 Path A 一樣

練習 3：CoT

挑一個數學文字題，比較：

• 純 prompt
• 純 prompt + 「Let's think step by step」
• 純 prompt + 一個展示 CoT 的範例

# 需要：pip install openai
# 前置：ollama pull gemma4:e4b && ollama serve
import sys, re
if hasattr(sys.stdout, "reconfigure"):
    sys.stdout.reconfigure(encoding="utf-8", errors="replace")

from openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

QUESTION = "小明有 3 顆蘋果。他給了小華 1 顆、又從媽媽那邊拿到 5 顆、然後吃了 2 顆。請問現在剩幾顆？"
ANSWER = 5 # 3 - 1 + 5 - 2 = 5

COT_EXAMPLE = """範例：
Q: 一隻雞有 2 隻腳。3 隻雞跟 1 個人共有幾隻腳？
A: 讓我一步一步算。3 隻雞 × 2 隻腳 = 6 隻腳。1 個人有 2 隻腳。總共 6 + 2 = 8 隻腳。答案是 8。
"""


def ask(prompt: str) -> str:
    r = client.chat.completions.create(
        model="gemma4:e4b",
        max_tokens=300,
        messages=[{"role": "user", "content": prompt}],
    )
    return r.choices[0].message.content


def extract_number(text: str) -> int | None:
    nums = re.findall(r"-?\d+", text)
    return int(nums[-1]) if nums else None


# A. 純 prompt
out_a = ask(QUESTION); ans_a = extract_number(out_a)

# B. + Let's think step by step
out_b = ask(QUESTION + "\nLet's think step by step."); ans_b = extract_number(out_b)

# C. + CoT example
out_c = ask(COT_EXAMPLE + "\n\nQ: " + QUESTION + "\nA:"); ans_c = extract_number(out_c)

for label, out, ans in [("A 純 prompt", out_a, ans_a), ("B +step-by-step", out_b, ans_b), ("C +CoT example", out_c, ans_c)]:
    print(f"\n--- [{label}] 答案={ans} {'✓' if ans == ANSWER else '✗'} ---")
    print(out[:200])

# === 自我驗證 ===
correct = sum(1 for a in (ans_a, ans_b, ans_c) if a == ANSWER)
assert correct >= 1, f"3 種 prompt 至少要 1 種答對、實際 {correct}/3"
# 小 model 對 CoT 依賴性更高、放寬條件：B 或 C 至少 1 對（vs Anthropic Path B 要求嚴格）
assert ans_b == ANSWER or ans_c == ANSWER, "B (step-by-step) 或 C (CoT example) 至少一種要答對 — CoT 對小 model 是基本功"
print(f"\n✅ 練習 3 通過 — {correct}/3 答對（本機 $0）")
print(f"💡 觀察小 model：A 純 prompt 通常答錯、B/C 加 CoT 後明顯改善——比 Claude 更能凸顯 CoT 重要性")

import anthropic
client = anthropic.Anthropic()

def ask(prompt: str) -> str:
    msg = client.messages.create(model="claude-haiku-4-5", max_tokens=300,
                                 messages=[{"role": "user", "content": prompt}])
    return msg.content[0].text

練習 4：Iterative Refinement

拿一個模糊的 prompt，refine 5 次。把每一輪記下來。觀察哪些改動會提升品質。

# 需要：pip install openai
# 前置：ollama pull gemma4:e4b && ollama serve
import sys
if hasattr(sys.stdout, "reconfigure"):
    sys.stdout.reconfigure(encoding="utf-8", errors="replace")

from openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

# 5 個 iteration、每一輪 prompt 都比前一輪更具體
PROMPTS = {
    "v1 模糊": "寫一段介紹 ReAct 的文字。",
    "v2 加目標讀者": "寫一段介紹 ReAct 的文字、給寫過 Python 的軟體工程師看。",
    "v3 加格式": "寫一段介紹 ReAct 的文字、給寫過 Python 的軟體工程師看。100 字以內、用一個段落。",
    "v4 加 example 要求": "寫一段介紹 ReAct 的文字、給寫過 Python 的軟體工程師看。100 字以內、用一個段落、結尾舉一個具體例子（譬如查天氣）。",
    "v5 加禁忌": "寫一段介紹 ReAct 的文字、給寫過 Python 的軟體工程師看。100 字以內、用一個段落、結尾舉一個具體例子（譬如查天氣）。不要用「賦能」「驅動」「智能」這類空泛詞彙。",
}

outputs = {}
for label, prompt in PROMPTS.items():
    r = client.chat.completions.create(
        model="gemma4:e4b",
        max_tokens=200,
        messages=[{"role": "user", "content": prompt}],
    )
    text = r.choices[0].message.content
    outputs[label] = text
    print(f"\n--- [{label}] ({len(text)} chars) ---")
    print(text)

# === 自我驗證 ===
v1_len, v5_len = len(outputs["v1 模糊"]), len(outputs["v5 加禁忌"])
banned_words = ("賦能", "驅動", "智能")
v5_has_banned = any(w in outputs["v5 加禁忌"] for w in banned_words)
assert v5_len > 0, "v5 必須有輸出"
assert not v5_has_banned, f"v5 應該避免禁忌詞、實際含: {[w for w in banned_words if w in outputs['v5 加禁忌']]}"
print(f"\n✅ 練習 4 通過 — v5 長度 {v5_len}、無禁忌詞（本機 $0）")
print(f"💡 觀察：v1 ({v1_len} chars) 通常比 v5 ({v5_len} chars) 「鬆」、加約束會逼 prompt 收斂")
print("💡 用 gemma4:e4b 跑這題特別有感——小 model 對 prompt 質量極敏感、5 輪 refine 的差距會比 Claude 更明顯")

import anthropic
client = anthropic.Anthropic()

# 迴圈內：
msg = client.messages.create(model="claude-haiku-4-5", max_tokens=200,
                             messages=[{"role": "user", "content": prompt}])
text = msg.content[0].text

進階做法：把這 5 輪輸出全存進 csv、Stage 7 練習 2 會教怎麼把這變成 eval harness（評估腳手架、即「跑評估用的外圍程式 / 控制層」、完整定義見下面 進階：prompt → context → harness 三層 engineering）量化「prompt 改善了多少」。

🎯 精選 Projects

按用途分 4 類、9 個項目一張表搞定。挑入口看「適合誰」、想深入點連結看 repo / 網站。

💡 建議閱讀路徑：dair-ai guide 入手（理論） → Anthropic Cookbook 看 Claude 實作 → NirDiamant 邊跑邊學 → 進 production 時讀 dspy。

🔭 進階：prompt → context → harness 三層 engineering

LLM-powered system 的工程實踐分成 3 層 stack（不是 1 次 call vs N 次 call）。每一層工程的對象不一樣：

• Prompt Engineering（本 stage）= 工程「送進模型的那段字串」
• Context Engineering（Stage 6）= 工程「每次 call 時、 context window 裡裝什麼資訊」——把 RAG retrieve 結果、memory、tool definitions、對話 history 動態組裝
• Harness Engineering（Stage 7）= 工程「模型外面的 runtime / scaffolding」——agent loop、retry、sandbox、observability、deployment 等所有非 LLM 程式碼

→ 三層正交：一次 call 的 RAG app 也在做 context engineering（重點是組 context、不是 call 幾次）；50 次 call 但沒做 retrieval 的 chatbot 仍只在做 prompt engineering。

完整三層 lineage（本路線的學習進度）：

💡 Karpathy 2025-06：「context engineering 是把對下一步有用的資訊剛好填進 context window 的精細藝術」（it's about what goes in the window）。

💡 Simon Willison / Addy Osmani：「coding agent = LLM + harness」、harness = 所有不是 model 本身的程式碼。OpenAI 2026-02 也使用 "Harness Engineering" 這個說法。

這個 stage 不用學完後兩層，只是給方向性提示——進入 Stage 6 / 7 時會接續這個 lineage。

延伸閱讀（不必修、未來想深挖時看）：

• Meirtz/Awesome-Context-Engineering（★ 3k+）——從 prompt engineering 一路推到 production agent 的 survey
• Windy3f3f3f3f/how-claude-code-works（★ 2.4k+）——Claude Code 內部解析，含 context engineering 章節

✅ 進 Stage 3 前的自我檢查

你能不能：

• 寫一個有 system message + user message + 3 個範例 message 的 prompt（few-shot）
• 示範 CoT 在某個推理任務上提升準確率
• 反覆 refine 一個 prompt 5 次，每一版都留下記錄
• 看出 prompt 不是對的工具的時候（這時要用 tool use）

如果可以 → 進 Stage 3 — Tool Use & Agent 入門。這是最重要的一個階段——prompt 不要急著跳過去，但也不要卡在這裡。

Stage 3 — 工具使用與第一個 Agent（Tool Use & Hello Agent）⭐

繁體中文 | 简体中文 | English

⏱ 時間估算：2-3 週（約 10-20 小時）

💡 用語密集（agent / tool use / function calling / ReAct / structured output⋯）→ 翻 resources/glossary.md 2。 🗺️ 進 Track A（CLI Power User）還是 Track B（Agent Builder）前，先看 resources/agent-paradigms.md — 5 種 agent 型態的全景圖，幫你選軌。

📋 本章組成：〔開場框景：AI/LLM/Agent 三者關係〕→ 學習目標 → 進入條件 → 必修閱讀 →〔可選 · 概念地圖〕→ 動手練習 → 反思（概念 + 路由）→ 精選 Projects → 自我檢查 🔑 關鍵名詞：見 resources/glossary.md 2

🤖 開始前：AI / LLM / Agent — 三者怎麼分？

本節是「開場框景」（由大到小 pedagogy）：先把學習者腦中的 mental hierarchy 建好，再進 學習目標、練習。這節只做簡短說明 + 對照，深度入門讀物已經是中英文圈各自的 canonical reference（見下方資源）。不是重寫 hello-agents Ch1。

一張階層圖先建立認知

→ 「Agent」不是「比 LLM 更厲害的模型」，也不是 LLM 樹狀分類底下的一個分支。Agent 是個跨層抽象的系統，把 LLM 當作其中一個元件來用。Cursor / Claude Code / Hermes Agent 內部都還是同一批 LLM（Claude / GPT / Gemini）—— 差別是怎麼把 LLM 包進工具呼叫迴圈裡。

三行對照（最快版）

一句話：LLM 像是會理解與產生文字的大腦；Agent 則是把這個大腦接上工具、流程與回饋迴圈，讓它能完成多步驟任務的系統。

Agent 的 3 個最小必要部件（這就是 agent vs LLM 的核心差別）

→ 這 3 個合在一起就是 agent 的最低定義。沒有 tools / loop，那只是「LLM + 你寫 retry」，不算 agent。

Agent 的經典範式（thinking patterns）

學完最小 3 部件後、下一層是「LLM 怎麼想」。hello-agents Ch4「智能體經典範式構建」整章在講這個。簡短對照：

→ 這些範式都是「LLM 自我引導」的不同變化、堆疊在 3 部件（LLM + Tools + Loop）之上。「Agent 是什麼」用 3 部件就講完了；「Agent 怎麼想」需要這 4 個範式才講得完整。

💡 延伸組件（agent 變強的 infrastructure、但不是「是不是 agent」的判準）：

• 記憶 / RAG（agent 能跨對話記住東西）→ Stage 6 完整教
• 反思 / self-critique（agent 看自己答案、發現問題、回頭改）→ 基本版見 本 stage 反思（concept + paper routing）；帶持久 memory 的進階版見 Stage 6 Reflexion with Memory
• Production harness（telemetry / safety / retry / orchestration）→ Stage 5 5.6

這些都是 advanced pattern——Stage 3 教最小可行 agent、後面 stage 教怎麼變強。

📚 深度入門資源（中英文 / 影片優先）

🀄 中文：

1. 李宏毅 — 生成式 AI 導論（2024 春台大課程） ⭐⭐⭐ — 中文圈最高品質的 AI / LLM / agent 學術級導論。每集 30-60 分鐘、台大授課、官方頁含投影片 + YouTube 連結。LLM / agent 概念都涵蓋。最新整合版見 GenAI-ML 2025 秋、YouTube 主頻道 @HungyiLeeNTU
2. datawhalechina/hello-agents Ch1「初識智能體」 ⭐ — 文字版最完整中文 agent 導論
3. datawhalechina/hello-agents Ch2「智能體發展史」 — BabyAGI → AutoGPT → Claude Code 演化脈絡
4. 3Blue1Brown 中文配音版 — LLM / Transformer 視覺化解說（中文配音）

🇺🇸 English：

1. Andrej Karpathy — "Intro to Large Language Models" ⭐⭐⭐（1hr）— LLM 從零開始 visual intro（ex-OpenAI / ex-Tesla AI Director、英文圈最重視的 LLM 入門影片）
2. Andrej Karpathy — "Let's build GPT from scratch" ⭐⭐（2hr）— 想看 LLM 內部到程式碼級的人
3. 3Blue1Brown — "But what is a Transformer?" ⭐⭐⭐ — visual 解釋 LLM，英文圈最被推薦的視覺化教材
4. Lilian Weng — "LLM Powered Autonomous Agents" ⭐⭐⭐ — canonical 1-page agent anatomy（Planning / Memory / Tool use / Action）、英文圈被引用最多的 agent 解剖文
5. Anthropic — "Building Effective Agents" ⭐ — Anthropic 觀點：何時該用 agent、何時 workflow 就夠
6. Chip Huyen — "Agents" — practitioner 視角，full chapter 級深度

選讀 / 進階補充：

• Simon Willison — "I think 'agent' may finally have a widely enough agreed upon definition" — working definition：「agent runs tools in a loop to achieve a goal」、含對照 OpenAI 等不同定義的爭議（給已有基礎的人）
• DeepLearning.AI Short Courses：「AI Agents in LangGraph」/「Multi AI Agent Systems with crewAI」/「Functions, Tools and Agents with LangChain」（API 多數是 2023-2024 舊版、看概念為主、寫 code 對照官方最新 docs）
• microsoft/ai-agents-for-beginners — 微軟官方 12 課 build-agent 入門（MIT、★ 64k+）。結構化、英文、含 code；適合想要一條平行入門課對照的人，不是本 stage 動手練習的替代
• liyupi/ai-guide — 中文圈最大 AI 資源聚合型 repo（不是原創教材、適合廣度延伸）

📌 資源清單上限規則：本 section 是 router 不是 tutorial。主清單合計上限 10 條（中 4 + 英 6），要加新資源前必須先移除一條。選讀區不計入主清單上限。

💡 推薦學習路徑：先看 1-2 個影片（中：李宏毅、英：Karpathy / 3Blue1Brown）建立 visual mental model → 再讀 1-2 個 blog（Lilian Weng / Anthropic）拿到 working definition → 再回本 stage 動手練習。不必全部看完，這是 reference library 不是 reading list。

這是整個學習路線最關鍵的一站。你建過一個 agent 才算真懂 agent——本 stage 的基礎練習建議至少實際手寫一次、再依需求往 hello-agents 或本 stage 精選 projects 找深度教材。

📌 學習目標

完成這個 stage 後你會：

• 講得出為什麼 LLM 需要 tools（它不是萬能的，而且文字以外的事它都做不了）
• 定義一個 tool schema，並讓 LLM 呼叫它
• 從零（不靠任何 framework）寫出一個單步 ReAct agent
• 寫出多步 ReAct agent，並讓它自己判斷何時該停
• 分得出哪種問題該用 tool use、哪種純 prompt 就夠

🚪 進入條件

你應該已經：

• 有可以跑的 Claude / OpenAI / Gemini API 權限（Stage 1）
• 對 prompt engineering 基礎已經上手（Stage 2）
• 能寫一個吃 JSON 進、吐 JSON 出的 Python 函式

📚 必修閱讀

1. Anthropic — Tool Use — 官方指南
2. anthropics/courses — Tool Use ⭐⭐⭐⭐⭐ ★ 21k+ — Anthropic 官方 5 course umbrella、module 5「Tool Use」對應本 stage。Jupyter notebook 互動式練習、含 multimodal prompts / streaming / tool 實作 walk-through
3. ReAct: Synergizing Reasoning and Acting in Language Models — Yao et al. 2022，奠基論文。至少讀 abstract 跟 Section 3。
4. OpenAI — Function Calling — function calling 格式參考
5. Build an agent from scratch — 從零打造 agent 的故事式導覽

🛠 動手練習（基礎 illustrative 練習）

🦙 本 stage 預設用 Ollama qwen2.5:3b（成本考量、tool-use 支援穩定）。Stage 3 進到 tool calling / ReAct loop、gemma4:e4b 不夠、改用 qwen2.5:3b（1.9 GB、ollama pull qwen2.5:3b 即裝）。每個練習都有 Path A（Ollama、預設）+ Path B（Anthropic、選擇性、想看 cloud 高品質 tool-use 時用）。

💰 Stage 3 預算估算（全 6 練習、tool use 較重）：全本機 = $0、全 haiku ≈ $0.50、全 sonnet ≈ $1.50。ReAct loop 練習單次 4-6 tool calls × 5 練習 × 5 reps ≈ $0.80 haiku。完整預算見 examples/README.md#推薦-llm-清單。

完整 3 路 trade-off 見 examples/README.md。

🆘 卡住了？ Tool calling 是整個 curriculum 最陡的學習曲線。裝 examples/stage-5/tool-calling-tutor/ skill——當你 prompt Claude Code「為什麼 LLM 不呼叫我的 tool」、「我這 schema 哪裡寫壞」會自動載入、走 4-symptom 診斷流程。

🪜 本 stage 是 single-agent 起點：一個 LLM + ReAct loop。Multi-agent 概念（多個 agent 協作）入門看 Stage 4 什麼是 multi-agent framework、Claude 原生 subagent 機制（.claude/agents/ + Task tool、不需 framework）看 Stage 5.5。

練習 1：Function Calling（一個工具、一次呼叫）

給 Claude 一個工具（假的天氣 API）跟一個問題（「台北現在有下雨嗎？」）。看 Claude 怎麼呼叫工具、拿到結果、再回答你。

# 需要：pip install openai
# 前置：ollama pull qwen2.5:3b && ollama serve
# Note: Stage 3+ 用 qwen2.5:3b（tool-use 穩定）、不是 gemma4:e4b
import sys, json
if hasattr(sys.stdout, "reconfigure"):
    sys.stdout.reconfigure(encoding="utf-8", errors="replace")

from openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

# Step 1: 定義 tool schema — OpenAI-compatible 格式包一層 {"type":"function", "function":{...}}
weather_tool = {
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "查詢城市目前天氣（晴/雨/陰），回傳一個短字串。",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "城市名稱（如「台北」）"},
            },
            "required": ["city"],
        },
    },
}

# Step 2: 問問題、讓 LLM 自己決定要不要呼叫 tool
resp = client.chat.completions.create(
    model="qwen2.5:3b",
    max_tokens=512,
    tools=[weather_tool],
    messages=[{"role": "user", "content": "台北現在有下雨嗎？"}],
)

# === 自我驗證 ===
msg = resp.choices[0].message
print("finish_reason:", resp.choices[0].finish_reason)
print("tool_calls:", msg.tool_calls)

assert msg.tool_calls, "預期 LLM 會選擇呼叫 tool（而非直接回答）"
tc = msg.tool_calls[0]
assert tc.function.name == "get_weather", f"預期呼叫 get_weather、實際 {tc.function.name}"
args = json.loads(tc.function.arguments)
assert args.get("city"), "預期 city 參數有值"
print(f"✅ 練習 1 通過 — qwen2.5:3b 正確選了 get_weather、帶 city='{args['city']}' 參數")

finish_reason: tool_calls
tool_calls: [ChatCompletionMessageToolCall(id='call_xxx', function=Function(name='get_weather', arguments='{"city": "台北"}'), type='function')]
✅ 練習 1 通過 — qwen2.5:3b 正確選了 get_weather、帶 city='台北' 參數

# 需要：pip install anthropic
# 環境變數：export ANTHROPIC_API_KEY=sk-ant-...
import anthropic

client = anthropic.Anthropic()

# Anthropic native tool schema — 不用包 wrapper
weather_tool = {
    "name": "get_weather",
    "description": "查詢城市目前天氣（晴/雨/陰），回傳一個短字串。",
    "input_schema": {
        "type": "object",
        "properties": {
            "city": {"type": "string", "description": "城市名稱（如「台北」）"},
        },
        "required": ["city"],
    },
}

resp = client.messages.create(
    model="claude-haiku-4-5",
    max_tokens=512,
    tools=[weather_tool],
    messages=[{"role": "user", "content": "台北現在有下雨嗎？"}],
)

# === 自我驗證 ===
assert resp.stop_reason == "tool_use", f"非預期 stop_reason: {resp.stop_reason}"
tool_calls = [b for b in resp.content if b.type == "tool_use"]
assert tool_calls[0].name == "get_weather"
assert tool_calls[0].input.get("city")
print(f"✅ 練習 1 通過（Anthropic）— Claude 選了 get_weather、city='{tool_calls[0].input['city']}'")

練習 2：多工具選擇

給 Claude 三個工具（搜尋、計算機、行事曆）跟一個任務。看 Claude 怎麼挑工具，順便注意它什麼時候會挑錯。

from openai import OpenAI
import json

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

TOOLS = [
    {"type": "function", "function": {"name": "web_search",
        "description": "Search current or external info not in the prompt.",
        "parameters": {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}}},
    {"type": "function", "function": {"name": "calculator",
        "description": "Evaluate basic arithmetic with +, -, *, /, parentheses.",
        "parameters": {"type": "object", "properties": {"expression": {"type": "string"}}, "required": ["expression"]}}},
    {"type": "function", "function": {"name": "calendar_lookup",
        "description": "Look up events for a specific date.",
        "parameters": {"type": "object", "properties": {"date": {"type": "string"}}, "required": ["date"]}}},
]

resp = client.chat.completions.create(model="qwen2.5:3b", tools=TOOLS,
    messages=[{"role": "user", "content": "What is (19 * 42) - 8?"}])

tc = resp.choices[0].message.tool_calls[0]
print(f"LLM 挑了: {tc.function.name}, args: {json.loads(tc.function.arguments)}")
# 預期：calculator, {"expression": "(19 * 42) - 8"}

→ 基礎 starter 範本 → examples/stage-3/02-multi-tool-selection/（starter.py 含 stub + 簡單 test，illustrative，不是 chapter-length 完整教學；深度章節見 stage 開頭 📚 hello-agents callout）

練習 3：從零實作 ReAct（不用 framework）

用 50-80 行 Python 把 Thought → Action → Observation 迴圈寫出來。不要 LangChain、不要 LangGraph，就是純 while not done: thought; action; observation; ...。

# 假設 TOOLS + TOOL_IMPL（dict: name → callable）已經像練習 2 一樣定義好
messages = [{"role": "user", "content": "台北人口除以紐約人口？"}]

for step in range(5): # max_iter safety net
    r = client.chat.completions.create(model="qwen2.5:3b", tools=TOOLS, messages=messages)
    msg = r.choices[0].message
    # 把 assistant response 接回 messages（重要！下輪 LLM 才看得到自己上輪講什麼）
    messages.append({"role": "assistant", "content": msg.content, "tool_calls": msg.tool_calls})
    if not msg.tool_calls:
        print(f"✅ 收尾：{msg.content}"); break
    for tc in msg.tool_calls:
        args = json.loads(tc.function.arguments)
        obs = TOOL_IMPL[tc.function.name](args) # 本地執行
        # observation 接回 messages（用 role="tool"、配 tool_call_id）
        messages.append({"role": "tool", "tool_call_id": tc.id, "content": obs})

→ 基礎 starter 範本 → examples/stage-3/03-react-from-scratch/（含 mock-based test.py、不花 API 錢也能驗；illustrative，不是 chapter-length 完整教學——深度章節見 stage 開頭 📚 hello-agents callout）

練習 4：多步驟推理任務

一個需要連續呼叫 3-5 次 tool 的任務。例如：「找出台北人口，除以紐約人口，再把比例換成百分比。」每一步用不同的工具。

# 沒有新 code、純粹是 TOOLS / TOOL_IMPL 換內容
TOOL_IMPL = {
    "lookup_population": lambda i: lookup_population(i["city"]),
    "divide": lambda i: divide(i["a"], i["b"]),
    "to_percentage": lambda i: to_percentage(i["ratio"]),
    "round_int": lambda i: round_int(i["x"]),
}
# loop 完全照 練習 3，只是 max_iter 拉大到 8

→ 基礎 starter 範本 → examples/stage-3/04-multi-step-reasoning/（starter.py 含 stub + 簡單 test，illustrative，不是 chapter-length 完整教學；深度章節見 stage 開頭 📚 hello-agents callout）

練習 5：錯誤處理

讓某個工具失敗（網路錯誤、輸入無效）。看看 agent 會怎麼處理錯誤、能不能恢復，再加上 retry 機制。

def fetch_weather(city: str) -> dict:
    if network_failed():
        return {"error": "network timeout", "retry_hint": "try again in 1s"}
    return {"city": city, "forecast": "rain", "temperature_c": 24}

# loop 裡：
obs = fetch_weather(args["city"])
messages.append({"role": "tool", "tool_call_id": tc.id,
                 "content": json.dumps(obs, ensure_ascii=False)}) # error dict 也是 string 化接回去
# 下一輪 LLM 看到 retry_hint、可能會 retry、可能會放棄、可能會改 query

→ 基礎 starter 範本 → examples/stage-3/05-error-handling/（starter.py 含 stub + 簡單 test，illustrative，不是 chapter-length 完整教學；深度章節見 stage 開頭 📚 hello-agents callout）

練習 6：Function schema 設計（壞 schema 修到好）

先給 LLM 一份故意寫爛的 schema——description 模糊（「處理資料」）、參數全用 type: string、沒分 required / optional、enum 該用沒用。觀察 LLM 怎麼選錯 tool、傳錯參數。然後逐項修：

• description 寫到 LLM 一眼就懂這個 tool 適用情境（不是寫給人讀的 docstring）
• parameters 用對 type（number / boolean / enum / array），required 列清楚
• 模糊邊界用 enum 強制收斂（例如 unit: "celsius" | "fahrenheit" 而不是 unit: string）
• error 回傳要包 {"error": "...", "retry_hint": "..."} 讓 LLM 能恢復

💡 詳細 cheatsheet 看 resources/schema-design-cheatsheet.md——5 條黃金規則 + 5 個常見 anti-pattern。

# ❌ BAD — qwen2.5:3b 幾乎必錯（Claude haiku 還能猜對、但機率明顯下降）
{"name": "convert", "description": "Convert a value.",
 "parameters": {"type": "object", "properties": {
     "value": {"type": "string"}, "unit": {"type": "string"}}}}

# ✅ GOOD — qwen 也能穩定挑對
{"name": "convert_temperature",
 "description": "Use when user asks to convert temperatures between Fahrenheit and Celsius.",
 "parameters": {"type": "object", "properties": {
     "value": {"type": "number", "description": "Temperature value"},
     "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}},
     "required": ["value", "unit"]}}

→ 基礎 starter 範本 → examples/stage-3/06-schema-design/（含 bad schema vs good schema 兩個版本對照；illustrative，不是 chapter-length 完整教學——深度章節見 stage 開頭 📚 hello-agents callout）

🪞 反思（Reflexion / Self-Refine）— 概念 + 路由

本節是 concept + routing、不是練習。沒有 verified working solution、不掛「練習 N」label、不給 success criteria——遵守本 repo「沒驗證答案不寫練習、頂多 routing」原則。想動手做？直接讀下方 paper / project。

反思是什麼：練習 5 的 error handling 是「LLM 出錯 → 你（外部）catch + retry」；反思是「LLM 觀察自己出錯 → 自己改」。差別是 agency 在哪一邊——這是 production agent（Cursor / Cline / Claude Code）每天都在跑的迴圈。

為什麼這節在 Stage 3 而不是 Stage 6：反思在學術（Reflexion paper Shinn 2023、Self-Refine Madaan 2023）跟 production（Cursor / Claude Code）上都被歸類在 planning / reasoning loop 機制——是 ReAct（練習 3）的 sibling pattern，不是 memory pattern。同樣是 LLM 自我引導的多輪迴圈，只是「下一輪要做什麼」從「呼叫 tool」換成「批改自己」。

進階版（帶 persistent memory 的 Reflexion 完整版）→ Stage 6 進階：Reflexion with Memory——當反思要跨 session、把過去失敗存起來當下一輪 context，這個版本才真的需要 memory 層。

一張對照圖

📚 想動手 / 想深入？直接讀這些

Paper：

• Reflexion (Shinn et al. 2023) ⭐ — 原 paper，定義「verbal reinforcement learning」
• Self-Refine (Madaan et al. 2023) — single-agent self-critique，是「基本反思」的學術定義

Reference 實作：

• arunpshankar/react-from-scratch — 已在本 stage 精選 Projects 列出，含 Reflection 實作可直接讀
• LangChain — Reflection Agents（blog） — framework 實作參考 + 完整 working notebook
• datawhalechina/hello-agents — 對應章節（自我反思 / Self-Refine 段落、中文完整教學）

💡 想看反思怎麼長進 production agent：Stage 5 5.6 Harness Internals 解剖 Claude Code source 時可以看到——agent 跑完 tool call 後自我評估 patch、有問題回頭改、修正後再 commit。這是現代 production agent 的核心 building block 之一。

🎯 精選 Projects

按用途分 4 類、12 個項目一張表搞定。挑入口看「適合誰」、想深入點連結看 repo README。

💡 建議閱讀路徑：練習 1-2 跑 Anthropic Cookbook → 練習 3 跑 pguso/ai-agents-from-scratch → 練習 3 後讀 Building Effective Agents → 中文章節式教材就 hello-agents + jjyaoao 配對 → 進 Stage 4 前看 LangChain ReAct template 對照 framework 抽象。

✅ 進 Stage 4 前的自我檢查

你能不能：

• 定義一個 tool schema（name + description + JSON schema 輸入/輸出）
• 用不到 100 行 Python、不靠任何 framework，把 ReAct 迴圈寫出來
• 解釋為什麼 agent 需要一個「我做完了」的退出條件
• 比較 CodeAct（程式碼即 action）跟 JSON-tool 兩種路線
• 看出哪些問題其實不需要 agent

如果可以 → 進 Stage 4 — Agent Frameworks。

如果不行 → 把 練習 3 再跑一次，不要跳過。如果你不懂 framework 在幫你抽象什麼，Stage 4 的那些東西看起來會像黑魔法。

Stage 4 — Agent 框架（Agent Frameworks）

繁體中文 | 简体中文 | English

⏱ 時間估算：2-3 週（約 10-15 小時）

💡 用語不熟（framework / supervisor / worker / handoff⋯）→ 翻 resources/glossary.md。

📋 本章組成：學習目標 → 進入條件 → 必修閱讀 →〔可選 · 概念地圖：multi-agent intro + 進階 tool patterns〕→ 動手練習 → 精選 Projects → 自我檢查 🔑 關鍵名詞：見 resources/glossary.md（framework / agent loop / handoff / supervisor 等收在 2、4）

你已經從零打造過一個 ReAct agent（Stage 3）。現在來看 framework 到底幫你做了什麼。挑一個深入學，其他的瀏覽過去就好，知道什麼時候該換。

📌 學習目標

完成這個 stage 後你會：

• 比較 5 個主流 agent framework（LangGraph、AutoGen、CrewAI、Smolagents、OpenAI Agents SDK）
• 替任務挑出對的 framework
• 用兩個 framework 各做一次同樣的 agent，親身感受差異
• 看出什麼時候該丟掉 framework、自己寫

🚪 進入條件

你應該已經：

• 跑完 Stage 3 的全部 5 個 hello-X projects
• 從零寫過 ReAct（練習 3）
• 對 async Python 上手（framework 大量依賴 async）

📚 必修閱讀

1. Anthropic — Building Effective Agents — 什麼時候用 framework、什麼時候直接用 raw API
2. LangChain — Conceptual Guide: Agents — agent 的抽象概念
3. Best Multi-Agent Frameworks 2026 comparison — 當前市場定位
4. 挑一個 framework 的 Quickstart — 選 LangGraph 或 CrewAI，把官方教學從頭跑到尾

🤔 什麼是 multi-agent framework？

兩個維度先分清楚（workflow vs agent / single vs multi）

要看懂 multi-agent framework 之前、有一個有用的釐清方式——把 workflow vs agent 跟 single vs multi LLM 當成兩個正交維度。Anthropic「Building Effective Agents」原文的核心區分是 workflow（固定 code path）vs agent（LLM 自主決定 next step）；我們把它跟 single/multi 疊起來看 4 個象限：

為什麼這個區分有用：production 場景大多落在「single agent workflow」+「single agent」象限——多數任務根本不需要 multi-agent。真正需要 multi-agent framework 的是右下角象限——LLM 自主性高 + 多角色協作。但實作上四個象限的邊界有時模糊（LangGraph 的 conditional edge 可以同時看成 workflow routing 跟 agent 動態決策）、不要把這個 matrix 當互斥分類。

→ 本 stage 後續討論都假設你已經知道：Multi-agent framework 主要幫你處理多個 agent 之間的協調、交接、狀態管理與重複性程式碼，讓你不用從零寫整套協作流程（右下角象限的 orchestration boilerplate）。

Single-agent vs multi-agent — 一張對照表先看清楚差異

什麼時候真的需要 multi-agent（不要硬上）

Multi-agent 不是 default、是 last resort。Anthropic 跟 Cognition 兩家 frontier lab 在 2024-2025 都明白寫過：90% 用例其實不該用 multi-agent——硬上會付 3-10× token、debug 痛苦、context fragmentation（context 被切散在多個 agent、彼此看不到全貌）嚴重。

需要 multi-agent 通常是這 4 個信號之一：

4 個信號都不在？ → single agent + 好 prompt + tool use 就夠。硬上 multi-agent 會付 3-10x token、debug 痛苦、其實不會比較準。

💡 後續閱讀：到 Stage 7 但你真的需要 multi-agent 嗎？ 會再帶 production 視角的決策——本節是設計階段的決策、那邊是 deploy 前的最後一次回頭檢查。

Multi-agent 經典 pattern（按複雜度排序）

📝 跟 Stage 3 經典範式怎麼分：Stage 3 的 4 個 paradigm（CoT / ReAct / Reflection / Planning）是單一 agent 內部怎麼想；本節這 5 個 pattern 是多個 agent 之間怎麼協作——正交的兩個層。

Claude Code subagent — 另一條 orchestration 路線

這節跟上面的 5 個 pattern 不同層：上面 5 個 pattern 是 framework / 自己 code 都能實作的設計選擇；本節介紹的 Claude Code subagent 是另一個 execution model（runtime 內建的 orchestration、不寫 framework code）。讀完 5 個 pattern 後、本節讓你知道「multi-agent 還有第二條路」。

Multi-agent 不只有 framework 這條路。Anthropic 自家的 Claude Code 提供另一個 abstraction 層：subagent — 寫一個 .claude/agents/<name>.md 檔就是一個 subagent，不需要 framework。

跟 framework 路線的根本差異（一句話）：framework 路線跨 LLM provider、寫 Python orchestration code、checkpointing / audit trail 完整；Claude Code subagent 只在 Claude Code runtime 內、寫 markdown 不寫 code、天生 context 隔離。

📌 完整逐維度對照表（啟動方式 / runtime / context 隔離 / provider lock-in / 學習曲線）的 canonical 在 Stage 5.5 開頭——本 stage 只需知道「multi-agent 還有 Claude Code 原生這第二條路」、逐項實作差異到 5.5 再看。

何時選 subagent 而非 framework：

• 你已經在用 Claude Code 跑日常工作
• 任務 context 大、會吃光主 session window（讀整個 codebase 之類）
• 多 subagent 平行（research / write / critic）省 wall-clock 時間
• 不需要跨 provider migration

詳細寫法 + 動手練習見 Stage 5.5（建議先完成 Stage 5.1 Claude Code 基礎再回來看 5.5——subagent 是 Claude Code 生態的進階功能、需要先熟悉基礎用法）。

Framework 的工作

Framework 把上面這 5 個 pattern 的 orchestration boilerplate（roles、handoff、state、retry、checkpoint、HITL pause）抽出來、讓你只寫角色定義跟任務描述。一句話：framework 是 multi-agent 的腳手架，不是必需品——簡單情境你自己寫個 dict 跟 for loop 也行（Stage 7 練習 1 就是這樣）。

📚 想系統化深入？

🇺🇸 學術 paper（影響後續所有 framework 設計）：

1. Anthropic — "Building Effective Agents" ⭐⭐⭐ — 何時用 workflow 何時用 agent、5 個經典 orchestration pattern。英文圈 multi-agent 設計入門必讀
2. AutoGen paper (Wu et al. 2023) — Microsoft 多 agent 對話框架原 paper
3. CAMEL paper (Li et al. 2023) — multi-agent role-play 開山之作
4. ChatDev paper (Qian et al. 2023) — multi-agent software dev、planner-executor canonical
5. Generative Agents paper (Park et al. 2023) — 25 個 agent 在 The Sims 互動、社會 simulation

🀄 中文系統教材：

1. hello-agents Ch6「框架開發實踐」+ Ch7「構建你的 Agent 框架」 ⭐ — 中文圈完整講 framework 開發 + 從零構建。注意：Ch4「智能體經典範式構建」是 single-agent paradigm（ReAct / Plan-and-Solve / Reflection），不是 multi-agent
2. 李宏毅 — 生成式 AI 導論 — 中後段有 AI agent / multi-agent 相關集數

Framework 官方 multi-agent docs：

• LangGraph — Multi-Agent Systems — supervisor / swarm / hierarchical 三種架構官方教學
• Anthropic Cookbook — customer_service_agent.ipynb — multi-agent orchestration canonical 範例（routing + handoff）
• Microsoft AutoGen — Examples — group-chat / debate / peer review pattern 完整範例

💡 建議框架學習流程（5 步）：

1. 建立 mental model（30 min）— 讀 Anthropic Building Effective Agents、把 workflow vs agent 跟 single vs multi 兩維度搞清楚
2. 跑 1 個 framework quickstart（2-3 hr）— LangGraph 或 CrewAI 二選一、跑官方多 agent 教學
3. 對照 Anthropic Cookbook customer_service_agent（1 hr）— production-style routing + handoff 範例
4. (可選) 深入學術側：挑 paper 1-2 篇看（AutoGen / CAMEL / ChatDev / Generative Agents）
5. (Claude 使用者可選) 寫一個 subagent 對照：見 Stage 5.5、跟 framework 路線比較

不必把 5 個 paper 全讀完、挑跟你場景最近的 1-2 個。

🛠 進階 tool patterns（framework 替你處理掉的東西）⭐ Track B 必看

Stage 3 教你寫 single tool / multi-tool selection（手寫 if/elif/else 路由）。Framework 把這層抽掉，並加了三種更進階的 tool pattern——這三個 pattern 都需要 framework 抽象層才寫得乾淨，Stage 3 自己手寫會炸開：

📚 深度資源：

• Anthropic — Tool Use best practices — 官方 tool design guide
• LlamaIndex — Tool Router pattern — Dynamic selection canonical reference
• LangGraph — Tool Node — composition graph 寫法

💡 Track B 學完本節：你應該講得出「同一個任務」在 (a) Stage 3 手寫 (b) 本 stage framework 寫 (c) Stage 5.5 Claude subagent 寫 三種路線的差別。這是 Track B 路線「會設計 agent」核心問題。

🛠 動手練習

練習 1：同一個 agent、兩個 framework

用以下兩個 framework 各做一次同樣的簡單 agent（搜尋 + 摘要）：

• LangGraph
• CrewAI 比較程式碼行數、debug 體驗、以及它們各自把哪些複雜度藏在哪裡。

練習 2：多 agent 角色分配

用 CrewAI 做一個 2-3 個 agent、各自有不同角色一起完成同一個任務的 demo。（這種情境 CrewAI 最拿手。）

練習 3：圖式 workflow

用 LangGraph 做一個有分支邏輯跟 human-in-the-loop checkpoint 的 workflow。（這種情境 LangGraph 最拿手。）

練習 4：CodeAct vs JSON tool

用 Smolagents 做一個會寫 Python 程式碼當作 action 的 agent（CodeAct pattern），跟 練習 1 用的 JSON tool call 路線比較。問同一個問題，看兩種路線怎麼解。

練習 5：型別安全 agent

用 Pydantic AI 做一個會回傳結構化輸出的 agent（例如：問問題回 { "answer": str, "confidence": float, "sources": [str] }）。看 Pydantic 的 schema validation 怎麼防止 agent 偷懶或 hallucinate 結構。

🎯 精選 Projects

按用途分 5 類、15 個項目一張表搞定。挑入口看「適合誰」、想深入點連結看 repo / quickstart。

💡 建議閱讀路徑：挑 1 個 production 等級（LangGraph）+ 1 個快速雛形（CrewAI）深入學 → 跑練習 1-3 → 其他 framework README 瀏覽過去、知道存在即可。特殊路線那 3 個（CodeAct / typed / memory-first）在特定場景才有對手、平常不必碰。

✅ 進 Stage 5 前的自我檢查

你能不能：

• 用 LangGraph 跟 CrewAI 各做一次同一個 agent
• 替任務挑出對的 framework（production vs 雛形）
• 解釋 LangGraph 的 checkpoint 跟 CrewAI 的 task delegation 差在哪
• 看出什麼時候 CodeAct（Smolagents）比 JSON-tool 更好
• 判斷什麼時候該丟掉 framework、直接用 raw API

如果可以 → 進 Stage 5 — Claude Code Ecosystem。

💡 策略提示 + 過程中可能踩到的坑

不要想把這些全部學完。挑**一個 production 等級的（LangGraph）跟一個快速雛形用的（CrewAI）**深入學。其他的 README 瀏覽過去就好，知道有這些選項存在即可。

Memory 預備（學的時候可能碰到、不用先讀）：有些 framework 功能會用到 memory 概念 — LangGraph 的 checkpointing（狀態持久化）、CrewAI agent 之間傳遞任務結果（輕量 memory）。這些在 Stage 6 — Memory & RAG 完整講；本 stage 看不懂某個 framework 功能時、再去那邊查就好，不用先讀完才能繼續本 stage。

Stage 5 — Claude Code 生態系（Claude Code Ecosystem）⭐⭐

繁體中文 | 简体中文 | English

⏱ 時間估算：3-4 週（約 15-25 小時）

🚪 進入條件（共用 hub、依 track 不同）：Track A（CLI Power User） 從 A1-A2 過來、會用 Python + 跑過基本 CLI 即可、從 5.1/5.2 起步；Track B（Agent Builder） 建議先完成 Stage 3（tool use）+ Stage 4（agent frameworks）再進、把整個 stage 當「Claude Code 內部怎麼運作」深讀。不確定走哪條 → 看下面 📌 的兩軌說明。

💡 整個 stage 圍繞 4 個關鍵詞（MCP / Skills / Plugins / Marketplace）展開 → 不熟先翻 resources/glossary.md 5。

👥 共用 hub：本 stage 是 Track A（CLI Power User）+ Track B（Agent Builder）兩條路徑的共用中心。Stage 5 跟 Stage 8 — Agent Interfaces 是 curriculum 的兩個 hub。

📌 這個 stage 兩條軌都用：

• Track A（CLI Power User）：A2 用 5.1（Claude Code 基礎）；A3 用 5.2（MCP） + 選擇性用到 5.3（Skills） 跟 5.4（Plugins）（A3 的 動手練習 CLI-12 會教把 CLAUDE.md 跟 commands 打包成 plugin）。讀的角度是「怎麼用 Claude Code 把工作做好」
• Track B（Agent Builder）：把整個 stage 當「Claude Code 內部怎麼運作」的深度學習，從 5.1 完整走到 5.4

🗺️ Claude Code 屬於哪種 agent 型態？→ resources/agent-paradigms.md Type 1（IDE-coupled）+ Type 2（Terminal pair-programmer）；想看完整 5 種 paradigm 對照也從這份開始。

⚠️ 想用本機 LLM？這個 stage 不是那條路線。 Claude Code 需要 Anthropic API / OAuth，不能直接改接 Ollama 或本機 endpoint。離線、隱私資料或不想用 API 額度時，請看 resources/cookbook.md Recipe 6，用 OpenCode / goose / Aider / Hermes 這類支援 BYO LLM 的 CLI agent。

📋 本章組成：6 個子章（5.1 基礎 / 5.2 MCP / 5.3 Skills / 5.4 Plugins / 5.5 Subagents / 5.6 Claude Code Source 解剖），每個子章都有「學習目標 → 必修閱讀 → 動手練習 → 精選 Projects」 → 章末 自我檢查。注意：Harness Engineering（Agent 執行系統設計）的學科級概念在 Stage 7 系統整理；本章 5.6 則把 Claude Code 當成案例，觀察一個成熟 agent 工具如何處理工具、記憶、設定、權限與執行流程 🔑 關鍵名詞：見 resources/glossary.md 5

Stack 一覽

由上往下，每一層都建立在底下那一層上：

每一層各自加上一種能力：

• API + SDK：用程式存取 LLM
• Tool Use：讓 LLM 呼叫你定義的 function
• MCP：標準化協定，讓任何 LLM host 都能使用任何 tool server
• Skills：Claude Code 的行為包，可以封裝 MCP tool
• Plugins：把 Skills、hooks、commands、MCP 設定打包成一個單位發佈

這個階段有 4 個子章節，請按順序做——每一節都建立在前一節之上。

5.1 Claude Code 基礎 3-5 天 （安裝、slash commands、CLAUDE.md）
5.2 MCP — 協定層 5-7 天 （寫你的第一個 MCP server）
5.3 Skills — 行為層 5-7 天 （寫你的第一個 SKILL.md）
5.4 Plugins 與 Marketplaces 5-7 天 （打包並發佈）

跑完這個階段，你會能擴充 Claude Code、寫自己的 MCP server、發佈一個 plugin marketplace。

🗺️ 7-Layer Architecture Map（先看這張圖、再讀 5.1-5.6）

📋 這節是什麼：把 Claude Code 的 7 個 primitive（MCP / Skills / Plugins / Subagents / Hooks / Slash commands / CLI）對應到 7 個架構層 + 3 個工程學 discipline——進 5.1-5.6 之前看一次知道接下來在學什麼層、學完回頭看是 synthesis。分層是教學選擇、不是 absolute 真理。

📊 上圖：Claude Code 7 個架構層 + 3 個工程學 discipline 整合視圖。

每層 1 句白話 + Claude 的版本

3 工程學 Discipline overlay（核心 insight）

「Prompt / Context / Harness」是不同層的 discipline——學會其中一個不會自動會另一個：

💡 MCP 的特殊位置：MCP 嚴格說是 Context Engineering（feed context source）+ Tool design（協議規範）跨層東西、不純歸任一 discipline——所以圖裡用 Layer 2.5 標明。

跨 CLI vendor mini-comparison（2026-05 snapshot）

只有 Claude Code 有完整 7-layer stack；其他 CLI 大多停在 single-agent + 簡化版：

→ 細看 resources/cli-agents-guide.md

5.1 — Claude Code 基礎

Claude Code 是什麼（先定位）

Claude Code = 跑在你 terminal 內的 Claude agent——有完整 file system / shell / git / subprocess access、可以自主完成多步驟工作（讀檔 → 改檔 → 跑 test → commit → 發 PR）。

跟其他 Claude 介面差別：

進 5.2-5.6 之前你會在這節學到 4 個 Claude Code 核心結構：CLAUDE.md（記憶層）/ slash commands（控制層）/ ~/.claude/ 目錄（設定層）/ settings.json（行為層）。

學習目標

完成本節後你會：

• 講得出 Claude Code 跟 claude.ai / API / SDK 各自的角色（「為什麼用 CLI 不用 web」）
• 安裝 Claude Code、配置認證、跑第一個有 file access 的 session
• 用 8-10 個常用 slash command 控制 Claude Code 行為
• 寫一份 project-level CLAUDE.md 設定 baseline 行為
• 認得 ~/.claude/ 目錄結構（skills / agents / plugins / settings.json 各放哪）

必修閱讀

1. Anthropic — Claude Code Quickstart — 官方安裝指南
2. Anthropic — CLAUDE.md best practices — 怎麼寫專案 memory
3. Anthropic — Slash Commands — 官方完整 slash command 列表
4. Anthropic — Settings — settings.json 完整 schema + env var
5. KimYx0207/Claude-Code-x-OpenClaw-Guide-Zh — 簡中入門指南

🛠️ 要寫好 CLAUDE.md？ 先看 Stage 7.5 核心 Harness Engineering 原則（多 source） 建概念、再用下面 2 個 prompt 動手。

📋 CLAUDE.md 設計 prompts（依 5 原則）

寫 / 改 CLAUDE.md 時直接複製貼上：

Prompt 1 — Audit 你現有的 CLAUDE.md

我有一個 CLAUDE.md（在 [貼路徑]），請依下面 5 個 harness engineering 原則 audit：

1. Legibility — 用 markdown header 分區嗎？conventions 寫具體（"2-space indent"）還是模糊（"format properly"）？
2. Progressive Disclosure — < 200 行嗎？有用 `@-import` 或 `.claude/rules/<topic>.md` 拆分嗎？
3. System of Record — CLAUDE.md 是否當 entry map、實際內容指向 `docs/` + `.coord/`？還是把所有規則塞同一檔？
4. Taste Invariants — 規則可驗證嗎（"run `make lint` before commit"）？還是「follow best practices」這種空話？
5. Transparency — 有要求 agent show planning step 嗎？還是預期它默默做完？

每條給 PASS / FAIL / PARTIAL + 原因 + 改進建議。總分 X/5、最該先修哪條。

Prompt 2 — 生成新的 CLAUDE.md（依 5 原則）

我要為一個 [描述專案，例如：Python data analysis monorepo / 學術論文 repo / Next.js app] 寫 CLAUDE.md。請依下面 5 個 harness engineering 原則生成：

- **< 200 行**
- 當 **entry map**，把實際 conventions 用 `@-import` 引外部 docs 或 `.claude/rules/<topic>.md`
- 每條規則**可驗證**（不要「follow best practices」這種空話）
- 加 **1-2 個 transparency rule**（例如「edit > 50 lines 前先 show plan」）
- 標明哪些內容該放 CLAUDE.md、哪些該分到 `.claude/rules/<topic>.md`

輸出：
1. 完整 CLAUDE.md 內容
2. 建議的 `.claude/rules/` 目錄切法（topic 列表）
3. 1 個示範 `.claude/rules/<topic>.md`（任選一個 topic）

→ 建議流程：寫 CLAUDE.md 前用 Prompt 2 生成、寫完用 Prompt 1 audit。

常用 slash commands（10 個必學）

完整列表見上方 Slash Commands 官方文件。

~/.claude/ 目錄結構（先有 mental map）

~/.claude/ ← 全域 user-level
├── settings.json ← 全域行為（env / hooks / permissions / model 預設）
├── settings.local.json ← 機器特定（不入 git）
├── CLAUDE.md ← 全域 baseline（每個 session 都載入）
├── skills/<name>/SKILL.md ← user-level skills（5.3）
├── agents/<name>.md ← user-level subagents（5.5）
├── plugins/ ← 已安裝的 plugin（5.4）
├── hooks/ ← user-level hook scripts
└── jobs/<id>/ ← background sessions 狀態（5.5 background agent）

<project-root>/.claude/ ← project-level（隨 repo）
├── settings.local.json ← project 行為（含 permissions）
├── skills/<name>/SKILL.md ← project-level skills（優先級高於 user-level）
├── agents/<name>.md ← project-level subagents
├── commands/<name>.md ← project-level slash command
└── hooks/ ← project-level hook

<project-root>/CLAUDE.md ← project baseline（每個 session 都載入）

優先順序（衝突時誰贏）：project > user > built-in default。

動手練習

• 練習 1：第一個 session — 安裝、認證、cd 到 repo、跑 claude → 問「summarize this codebase」→ 觀察怎麼讀檔
• 練習 2：CLAUDE.md — 寫 repo 根目錄 CLAUDE.md（role / context / 不能做的事 / 怎麼做事 / 常用指令），對照「沒 CLAUDE.md」跟「有 CLAUDE.md」的行為差別
• 練習 3：5 個 slash commands — 在一個 session 內依序用 /help /plan /compact /model /agents，觀察各自做什麼
• 練習 4：目錄探索 — ls ~/.claude/ + cat ~/.claude/settings.json、看自己 user-level 設定長什麼樣

精選 Projects

5.2 — MCP（Model Context Protocol）⭐ 基礎

MCP 是什麼（先定位）

MCP = 「讓 LLM 用任何外部工具 / 資料」的開放協定。在 MCP 之前每個 LLM 廠商都得自己定義 tool 規格、每個工具供應商都得為每個 LLM 寫一份接法。MCP 把這層標準化——寫一次 MCP server、Claude / Codex / Cursor / 任何支援 MCP 的 host 都能用。

MCP 三個抽象：

多數 MCP server 主要用 Tools 抽象——Resources 跟 Prompts 用得少。

MCP vs Tool Use vs Skill vs Plugin：

• Tool Use（Stage 3）：你 in-process 寫的 function 給 LLM 呼叫
• MCP（本節）：把 tool 標準化成 server / client 協定、跨 host / 跨 LLM 可用
• Skill（5.3）：行為層 — 教 Claude「遇到 X 用哪個 MCP tool」
• Plugin（5.4）：把 MCP + Skill + 其他打包散佈

→ 核心區分：MCP 是「能力」（讓 LLM 能做什麼）、Skill 是「行為」（什麼時候用什麼能力）。

學習目標

• 解釋 MCP 的三個抽象（Tools、Resources、Prompts）
• 把現成的 MCP server 接上 Claude Desktop 或 Claude Code
• 用 Python 寫一個最小的 MCP server，提供 1-2 個 tool
• 區分 MCP server vs Tool Use vs Skills vs Plugins

必修閱讀

1. Anthropic — Introducing MCP — 最初發表，概念總覽
2. MCP Specification — 實際的協定規格
3. Complete Guide to MCP in 2026 — 實作導讀

動手練習

• 練習：MCP client — 安裝 modelcontextprotocol/servers/filesystem，從 Claude Desktop 連上去。看著 Claude 讀你的檔案。
• 練習：MCP server — 寫一個 Python MCP server，提供一個 tool（例如「換算溫度」）。從 Claude Code 連過去。step-by-step 怎麼做 → resources/cookbook.md 2
• 練習：MCP in production — 在同一個 Claude session 裡同時連 2-3 個 MCP server，看它們互相搭配。

精選 Projects（spec / SDK / 範本參考）

💡 找日常工具的 MCP（Notion / Obsidian / Excel / Postgres / Playwright / Figma 等）？ 看 resources/mcp-skills-catalog.md——按 14 個分類整理 62 個常用 MCP server / Skill，每個都附 stars / license / 適合誰。下表保留的是「寫自己 MCP server 時的 reference」性質的官方 server / SDK。

5.3 — Skills（Claude Code 的行為層）⭐ Claude Code 生態最關鍵的一層

Skill 是什麼（先定位）

Skill = 一個 markdown 檔（.claude/skills/<name>/SKILL.md），告訴 Claude「遇到某情境 → 走某流程」。Claude 每次 inference 前掃所有可用 skill 的 description frontmatter（檔案開頭那段 YAML metadata）、看是否匹配當前情境、匹配就把 SKILL.md 自動載入 context。

🛠️ 要寫好 SKILL.md？ 兩條路：

• 路 A：用 Anthropic 官方 skill-creator skill 自動產生（5.3.x 之後安裝段落會教），它會自動產 frontmatter + 子目錄結構、是 Anthropic 維護的 canonical 工具。
• 路 B：用下面 SKILL.md 設計 prompts 自己寫——先看 Stage 7.5 核心 Harness Engineering 原則 建概念、再用 prompt 動手。

兩條不衝突：skill-creator 給結構、5 原則 prompt 給內容品質檢查。

📋 SKILL.md 設計 prompts（含 skill-creator 替代）

寫 / 改 SKILL.md 時直接複製貼上：

Prompt 1 — Audit 你現有的 SKILL.md

我有一個 SKILL.md（在 [貼路徑]），請依下面 5 個 harness engineering 原則做 audit。每條給「PASS / FAIL / PARTIAL」+ 1 行原因 + 1 行改進建議：

1. Legibility — description 寫清楚「何時觸發」嗎？tool param 命名一致嗎？
2. Progressive Disclosure — SKILL.md < 200 行嗎？細節是否放 `references/` 而不是塞主檔？
3. System of Record — `references/` 是 single source、主檔不重複嗎？
4. Taste Invariants — success criteria 是否寫死可驗證、不是「盡量好」這種主觀詞？
5. Throughput / Merge — 有附 acceptance check（lint / test / preset YAML）嗎？

最後給：總分 X/5、最該先修哪一條、為什麼。

Prompt 2 — 生成新的 SKILL.md（依 5 原則）

我要寫一個 skill 處理 [描述任務，例如：把 PDF 轉成 markdown / 跑學術論文 banned-word audit]。請依下面 5 個 harness engineering 原則生成 SKILL.md：

- **description** 寫清楚「何時觸發」（讓 Claude 能 match 對情境）
- **主檔 < 200 行**，所有 examples / edge cases / detailed rules 放 `references/<topic>.md`
- 列出建議的 `references/` 結構（1-3 個 topic 檔案）
- 加一個 **success criteria 表**（可驗證、不主觀）
- 加一段 **acceptance check**：要跑哪些 lint / unit test / preset YAML

輸出：
1. 完整 SKILL.md 內容
2. references/ 目錄結構建議
3. 用哪個 acceptance gate preset 驗證它（如 multi-locale-mirror-sync / catalog-entry-add 之一）

→ 建議流程：先 /skill skill-creator 拿乾淨骨架 → 用 Prompt 2 填內容 → 寫完用 Prompt 1 audit。

核心 mental model：你發現自己「每次都要打同樣的 prompt 教 Claude 怎麼做某件事」→ 把它寫成 skill、下次就不用了。Claude Code 生態裡 skill 是 power user 跟一般使用者的分水嶺——熟練 skill 寫作的人能把 1 個小時的工作壓到 5 分鐘。

Skill vs CLAUDE.md vs MCP vs Plugin vs Subagent — 一張表分清楚

各層常被搞混。一行對照：

怎麼選：

• 一句話設定 → 寫進 CLAUDE.md
• 多步驟流程、某情境才用 → 寫 Skill（本節主題）
• 需要存取外部資源（API / DB） → 寫 MCP server
• Skill 跑起來太大、會吃光主 session window → 改成 Subagent
• Skill / command / MCP / hook 想打包送人 → 包成 Plugin

→ 核心區分：MCP 是「能力」、Skill 是「行為」、Plugin 是「散佈」、Subagent 是「獨立 worker」。

學習目標

• SKILL.md 的結構（YAML frontmatter + 本文）
• skill 何時會自動載入（description 比對）
• 怎麼寫一份能解決你日常工作的 SKILL.md
• references/、scripts/、evals/ 子目錄的用途

必修閱讀

1. Anthropic — Claude Skills 文件
2. 幾份範例 SKILL.md——從 anthropics/claude-code 或社群 marketplace 拿
3. Hello-Agents — Extra08 如何寫出好的 Skill — 中文最完整的 Skill 最佳實踐
4. Hello-Agents — Extra05 Agent Skills 與 MCP 對比解讀 — Skills vs MCP 概念對比

動手練習

• 練習：SKILL.md — 寫一份 200 字的 skill，解決你日常工作中的某一件事。step-by-step 怎麼做 → resources/cookbook.md 1
• 練習：SKILL with references — 加一份 references/ markdown 讓 skill 可以引用
• 練習：SKILL eval — 加 evals/evals.json，放 3-5 個自我測試

📦 本 repo 自帶 meta-example：examples/stage-5/tool-calling-tutor/ 是這個 stage 的對應 skill 範本——完整 frontmatter（含 trigger phrases + Do NOT use for）、3 份 references/、evals/evals.json 5 個 test case，直接 fork 改成你自己的 skill。雙重用途：(a) 學習者自用、卡在 tool calling 時讓它 auto-load 幫你 debug；(b) Stage 5 5.3 SKILL.md 寫法的對照樣板。

常用 Skills 推薦（按用途分類）

不知道從哪裡開始？下面是 2025 後段官方 + 社群常用 skill。安裝方式：(a) 多數來自 plugin、安裝對應 plugin 即得；(b) 或從 anthropics/skills clone 後放進 ~/.claude/skills/ 或 .claude/skills/。

建議入手順序：

1. 第一個必裝：skill-vetter（裝其他 skill 前先用它檢查）
2. 第二批必裝：skill-creator + find-skills（寫 / 找 skill 用）
3. 依工作領域：Office workflow 加 pdf/docx/xlsx、開發加 code-reviewer/debugger、學術寫作加 academic-writing-skills
4. 想看更多：逛 obra/superpowers 或 wshobson/agents 看 production 範本

精選 Projects（spec / 範本參考）

💡 找日常用 Skill（NotebookLM、Excalidraw、Office docs 等）？ 看 resources/mcp-skills-catalog.md——按使用情境分類，含 Anthropic 官方 + 社群 Skill。下表保留的是「寫自己 Skill 時的 spec / showcase reference」性質。

5.4 — Plugins 與 Marketplaces

Plugin 是什麼（先定位）

Plugin = MCP + Skills + slash commands + hooks 的組合包——把前面 5.2 / 5.3 學到的零件 打包成一個單位、可以 /plugin install 一次裝進去。

Plugin
├── .mcp.json ← 5.2 學的 MCP server config（提供 tool / data）
├── skills/<name>/SKILL.md ← 5.3 學的 skill（行為包）
├── commands/<name>.md ← slash command（5.1 學的、自訂 prompt 入口）
├── hooks/ ← 觸發點 hook（譬如 PreToolUse、SessionStart）
├── agents/<name>.md ← 5.5 學的 subagent（如果有）
└── .claude-plugin/plugin.json ← 打包元資料

為什麼要 plugin：你寫了好用的 skill 想 share → 一行 git clone 太麻煩、設定也容易裝錯。包成 plugin、push 到 marketplace、team 其他人 /plugin install foo@your-marketplace 一次到位。

Plugin 跟 marketplace 差在哪：plugin 是單一打包單位、marketplace 是多個 plugin 的目錄（譬如 anthropics/claude-plugins-official 是 marketplace、裡面 35 個 plugin）。

學習目標

• plugin.json schema（name、version、skills array、configuration）
• marketplace.json schema（plugins array、source、metadata）
• claude plugin marketplace add 的流程
• 區分 single-plugin bundle vs multi-plugin marketplace
• 發佈自己的 marketplace

必修閱讀

1. Anthropic — Plugins 文件
2. 讀下面 2-3 個 marketplace 的 plugin.json 與 marketplace.json

動手練習

• 練習：plugin install — 安裝下面的某一個 marketplace，看它載入
• 練習：plugin.json — 把 5.3 寫的 SKILL.md 打包成一個 plugin
• 練習：marketplace publish — push 到 GitHub，用 claude plugin marketplace add 安裝

常用 plugin 推薦（按用途分類）

不知道從哪裡開始裝 plugin？下面是 2025 後段 Anthropic 官方 + 社群高評價選擇。安裝指令統一格式：/plugin install <plugin-name>@<marketplace-name>（譬如 /plugin install code-review@claude-plugins-official）。

建議入手順序：

1. 開發者必裝（5 個）：code-review + pr-review-toolkit + commit-commands + feature-dev + 一個你語言的 *-lsp
2. 按工作領域加 bundle：工程團隊裝 engineering、財務裝 finance、其他類似
3. 想寫自己的 skill / plugin → 裝 skill-creator + plugin-dev
4. 想看更多 → 逛 awesome-claude-code-toolkit 或 resources/mcp-skills-catalog.md

精選 Projects（marketplace 範本參考）

💡 上面列的是「裝哪些 plugin」；下表列的是「marketplace 怎麼寫」——想自建 marketplace 的人才需要看。

💡 「如何發佈自己的 marketplace」walkthrough：目前最可靠的是 Anthropic 官方 plugin 文件。社群有好的部落格 / repo？歡迎開 PR 補上。

5.5 — Subagents（Claude Code 原生 multi-agent 機制）⭐ 2025 新功能

到這裡為止你學了 MCP（工具層）/ Skills（行為層）/ Plugins（散佈層）。Subagents 是 orchestration 層——讓主 Claude session spawn 出有獨立 context 的子 agent、跑特定任務、回報結果。

📊 上圖：subagent 從定義 → 發現 → 派遣 → 執行 4 個階段、看完這張再讀下面細節最快。

跟 Stage 4 的 framework-based multi-agent（LangGraph / CrewAI / AutoGen）對照：

各家 CLI / SDK 的 multi-agent 機制現況（2025 後段）

很多人以為 multi-agent CLI 是 Anthropic / OpenAI / Google 三家標配——但實際上目前只有 Claude Code 有完整 native multi-agent stack。Codex CLI / Gemini CLI / Cursor 都還是 single-agent，要 multi-agent 得自己用 SDK 或 framework 寫。

現況解讀：

• 想用 CLI 玩 multi-agent → 目前只有 Claude Code 有 native 支援（本節主題）
• 想 跨 provider / 跨 LLM → 走 Stage 4 framework path
• 想 OpenAI 生態 + 多 agent → 用 OpenAI Agents SDK 寫 handoff pattern（programmatic、非 CLI）
• 想 完全自己控 → 走 Stage 5.6 Harness Internals（讀 SDK source、自己 wire 多 agent）

→ 本節剩下內容都聚焦在 Claude Code subagent。其他平台的進展請追蹤各家 changelog（Codex / Gemini / Cursor 都還在 single-agent + MCP 階段、可能 2026 後段才會跟進）。

怎麼派遣 Claude Code 的 3 種 multi-agent 機制（具體 syntax）

3 個機制怎麼選：

• 任務獨立、worker 不互動、結果回主 session 即可 → Subagent（最簡單、token 最省）
• Worker 需要互相溝通 / debate / 共享 task list → Agent team（已正式有 docs、但仍需 opt-in env var；token 3-5x、適合 research / debug 競爭假設）
• 多個獨立任務各自跑、想用 1 個介面監控全部 → Background agent（research preview、適合長時間任務並行）

可派遣的 subagent 有哪些？

💡 先解釋一下名詞：subagent = 主 Claude session spawn 出來的「子 Claude」——有自己的 context window（一次能記住的對話量、有上限）、跑完回報結果。**派遣（dispatch）**就是叫 subagent 去做事、像派任務給同事。

很多人以為要用 subagent 都得自己寫一個——其實 Claude Code 內建一批 subagent、開箱即用。下表列三種來源：

🔍 想知道你的 Claude Code 現在有哪些 subagent 可用？ 終端機跑 /agents 一指令列表（內建 + plugin + 自訂全部）。

怎麼選哪一個 subagent？（decision table）

對應上面 7 個 Claude Code 內建 subagent、下表是「遇到 X 任務、用 Y subagent」對照（這叫 decision table——「要 X 用 Y」的快速對照、不用想自己會選）：

5 個常見情境的 mini cookbook（完整 15 個 recipe 見下面）：

📋 完整 15 個 recipe（每個含情境 + subagent + 直接複製貼上的 prompt 範本 + 何時不用）→ resources/subagent-cookbook.md

易混淆觀念釐清（學完表格還是有點霧、看這節）

學生最常搞混的 3 組概念 + 5 條老手才知道的 gotcha——挑你需要的看：

Subagent vs Skill — 5 個關鍵差別

很多人把 Subagent 跟 Skill 當同一件事——其實完全不同層的東西：

判斷快速辦法：你要新 context window 嗎？要 → subagent；不要 → skill。

Subagent vs Slash Command — 一個是任務、一個是指令

⚠️ 常見誤會：/agents 不是用來呼叫 subagent——它是「查當前可用 subagent 清單」的指令。派遣是直接打對話 prompt 文字、Claude 自己挑 subagent。

Description = 路由 key（寫法決定能不能被選）

主 session 怎麼知道該派哪個 subagent？看 .claude/agents/<name>.md 的 description 欄位。寫法影響觸發行為：

💡 寫 description 像寫廣告詞——把「我能解決什麼問題」寫具體、Claude 越會在對的時機選你。PROACTIVELY 是個強訊號詞——出現時 Claude 推斷「適合主動派遣」的機率大幅提升；沒寫就更常只在使用者明白要求時才會派。（它影響 Claude 的判斷、不是程式碼層的 if-then 開關。）

5 條老手才知道的 Gotcha

Subagent 整體優缺點（讀完前面、回頭看這個 summary）

5 個優點（為什麼存在）：

5 個缺點（什麼時候不值得）：

📌 1 句話判斷：任務 ≥ 5 分鐘 + 可以用一個 brief 寫死（不需來回對話）+ 結果一次回來夠用（不需逐步 feedback）→ 用 subagent；否則自己跑。

📋 準備自己寫 subagent / 組合多個 / debug 跑壞的？ → resources/subagent-advanced.md（description 寫法 4 個 bug 對照、composition 3 種 pattern、debug 5 切點）

---
name: code-reviewer
description: Review staged git changes for security issues, style violations, and missing tests. Use when user asks "review my changes" or runs /review.
tools:
  - Read
  - Grep
  - Bash
model: claude-haiku-4-5 # 可選、想 route 到便宜 model 省成本
---

You are a senior code reviewer. When invoked:
1. Run `git diff --cached` to get staged changes
2. Check for: hard-coded secrets, SQL injection patterns, missing error handling, missing tests
3. Output: PASS / list of specific issues with file:line references

📚 官方完整文件：

• Subagent spec（frontmatter 欄位、project vs user scope、Task tool 介面）
• Agent team 完整指南（display modes、task list、subagent-as-teammate 進階）
• Agent view / background（v2.1.139+、quick start + dispatch 流程）

學習目標

• 講得出 subagent 跟 skill / MCP server 的差別（subagent ≠ skill：skill 是行為 prompt，subagent 是另一個 Claude instance with isolated context）
• 寫一個 .claude/agents/<name>.md 自訂 subagent（frontmatter + system prompt + tools: 白名單——明寫允許的工具清單）
• 從主 session 用 Task tool invoke subagent，觀察 context 隔離（parent 看不到 subagent 的中間 step、只看到最終 result）
• 知道何時用 subagent（parallel research / large-context isolated task / specialized review），何時不用（小 query 用 skill 即可）

必修閱讀

1. Anthropic — Claude Code Subagents 官方文件 ⭐ — .claude/agents/ 結構、Task tool 介面、最佳實踐
2. Anthropic — Building Effective Agents orchestrator-workers — Anthropic 自己對 orchestrator pattern 的看法（理論 + 實例）
3. Anthropic Cookbook — customer_service_agent — canonical multi-agent orchestration 範例（chapter-length 深度教材；notebook 在 tool_use/customer_service_agent.ipynb）

動手練習

• 練習：第一個 subagent — 寫 .claude/agents/code-reviewer.md（前置 frontmatter 含 description 寫清楚何時 trigger、tools 限定 Read+Grep）+ system prompt 跑 staged diff review。從主 Claude session 跑 /agents list 確認載入、然後用 prompt「review staged changes」觀察 Task tool 怎麼 spawn subagent
• 練習：parallel subagent crew — 寫 3 個 subagent（researcher.md / writer.md / critic.md）做「研究某主題 → 寫 blog 草稿 → 審稿」pipeline、主 session 用 Task tool 串起來。對照 examples/stage-4/02-multi-agent-roles/（CrewAI 框架版同一個任務）、看「framework 路線 vs Claude 原生路線」程式碼差別
• 練習：subagent 跟 skill 的決策練習 — 拿你自己日常工作流的 5 個常用任務、每個判斷該用 skill（行為層）還是 subagent（獨立 context 層）。寫成 1 頁 decision table

📚 想要 chapter-length 深入版：subagent 進階 pattern（agent-as-skill composition、parallel-spawn、handoff between subagents）→ 看 wshobson/agents repo 整個結構 + obra/superpowers 的 subagent 用法。

精選 Projects

4 個項目一張表搞定。挑入口看「適合誰」、想深入點連結看 repo。

💡 Subagent 雖然強、不要無腦用：每個 subagent invoke 都是一個新的 Claude inference call、有 token cost + latency。簡單 query 用 skill（行為 prompt）即可、不必 spawn subagent。Subagent 的甜蜜點是：(1) 任務 context 大、會吃光主 session 的 window（譬如 read 整個 codebase），(2) 任務跟主 session 邏輯獨立、隔離 context 有助 main flow，(3) 多 subagent 平行（research / write / critic）能省 wall-clock 時間。

🔗 相關進階機制（Claude Code 官方、本 stage 不深入講）：

• Agent teams — 多 sessions 之間互相溝通（reviewer agent ↔ implementer agent 來回交流）
• Background agents / agent view — 多 session 背景跑、單一介面監控（一次 spawn N 個 PR review 同時跑）

Subagent 是這兩個的進入點——本節學完之後想擴展再看官方文件。

5.6 — Claude Code Source 解剖（reference harness implementation）⭐ Track B 必看

本節定位：本節不是 harness engineering 的學科級概念教學——學科級的定義 / 8 個核心元件 / prompt→context→harness 三層工程分工 是 Stage 7 Harness Engineering 在講。本節是 case study——拿 Claude Code（一個 production-grade 參考實作）的 source code 來解剖、把 Stage 7 列的 8 個元件中前 6 個 runtime-internal 元件（Eval / Cost-Latency 兩個是跨層議題、不在 source 主 loop）在實作裡找到對應位置。

學習目標

完成本節後你會：

• 看得懂 claude-agent-sdk-python source 的 main loop（不是逐行、是抓得到主幹）
• 在 source 裡標出 Stage 7 列的 8 個 harness 元件中前 6 個 runtime-internal 元件（agent loop / tool registry（agent 可呼叫工具的清單 + 介面定義） / context manager / safety layer / retry / telemetry）各自的 file:line。Stage 7 列的第 7 個 Eval 是外掛、第 8 個 Cost / Latency 是 cross-cutting、不在 source 主 loop 內、不在本練習範圍
• 講得出 Claude Code 的 agent loop 跟 Stage 3 練習 3 from-scratch ReAct 差在哪——production-grade 多了哪些東西

學科級概念在哪：harness engineering 是什麼 / framework vs harness 差別 / prompt→context→harness 三層工程分工 → 全部見 Stage 7 Harness Engineering。本節只負責 Claude Code source 的 case study。

📚 必修閱讀

1. Anthropic — Building Effective Agents ⭐ — orchestrator / worker / handoff / reflection 等 pattern 的 canonical reference
2. anthropics/claude-agent-sdk-python — Claude Code 官方 Python SDK 的 source；重點 file：src/claude_agent_sdk/_internal/client.py（main loop 在這）+ query.py（單回合 API）
3. ai-boost/awesome-harness-engineering ⭐（★ 940） — community curation：harness pattern / eval / memory / observability 整合
4. ZhangHanDong/harness-engineering-from-cc-to-ai-coding — 中文圈最完整的 Claude Code 內部解讀

🛠 動手練習 — 解剖 agent loop（閱讀題，非寫 code）

這節不是寫 code 練習，是閱讀練習——production harness 不是抄 200 行範例能學的，是抄完還看不懂為什麼這樣寫，所以本練習要求你開 source、自己 trace。

步驟：

1. clone：git clone https://github.com/anthropics/claude-agent-sdk-python
2. 定位 agent loop：找出 _internal/client.py 裡實際發出 LLM call、收 tool_use response、dispatch 給 tool runner 的核心 loop。提示：找 async def 跟 tool_use_id 關鍵字
3. 標出前 6 個 runtime-internal harness 元件在 source 裡的位置（檔名 + 行號）——對應 Stage 7 列的 8 元件的前 6 個（第 7 個 Eval 外掛 / 第 8 個 Cost-Latency cross-cutting 不在 source 主 loop）：
   • (a) Agent loop：實際發出 LLM call + 收 response 的迴圈在哪
   • (b) Tool registry / dispatch：LLM 回 tool_use → 怎麼 route 到對應 tool 實作
   • (c) Context manager：tool result 怎麼寫回 message history、context window 控制 / auto-compact
   • (d) Safety layer：tool 執行前有沒有 permission gate / sandboxing
   • (e) Retry / recovery：tool fail 時怎麼處理（exception vs LLM 自己看 error 反思）
   • (f) Telemetry：metrics / logging / token counting 接在哪
4. 寫一段 80-150 字摘要：「Claude Code 的 agent loop 跟你 Stage 3 練習 3 from-scratch ReAct 差在哪」。重點不是「Claude Code 比較複雜」這種廢話，是講得出多了哪些東西、為什麼那些是 production-grade 必須

交付物：一段筆記（寫在自己的 obsidian / notion / .md 都行），不必交。但講不出來你就還沒懂——這是進 Stage 7 production deploy 之前的必要 mental model。

→ 基礎 starter 範本：本練習無 examples folder——是 source-reading exercise，非 code-writing exercise。illustrative，深度教學見上方 📚。

🎯 精選 Projects

4 個項目一張表搞定。挑入口看「適合誰」、想深入點連結看 repo。

💡 本節跟 Stage 7 的差別：本節學「Claude Code 這個 harness 怎麼跑」（具體 reference）；Stage 7 學「production harness 一般要有什麼」（抽象 pattern）。先具體後抽象、看完本節再進 Stage 7 會輕鬆很多。

✅ 進入 Stage 6 前的自我檢查

你能不能：

• 安裝 Claude Code 並使用 5 個不同的 slash command
• 在同一個 Claude session 裡接 2 個 MCP server
• 用 Python 寫自己的 MCP server，提供 1 個能用的 tool
• 寫一份能在特定觸發詞自動載入的 SKILL.md
• 把 skill 打包成 plugin，再用 marketplace.json 發佈
• 寫過 .claude/agents/ 自訂 subagent 並從 Task tool invoke 過
• 讀過 claude-agent-sdk-python 的 main loop、能在 source 裡標出 Stage 7 列的 8 個 harness 元件 的前 6 個 runtime-internal 元件位置（5.6 練習）
• 從角色分工說出 MCP / Skills / Plugins / Subagents / SDK 各自的位置

如果都可以 → 前往 Stage 6 — Memory & RAG。

💡 Stage 5 是兩 track 第一個 hub——Track A 跟 Track B 都會用到。第二個 hub 是 Stage 8 — Agent Interfaces（Computer Use / Browser Use / Sandbox），可以走完主幹後再進、或對 Computer Use / Browser MCP 有興趣可以提前 preview。

💡 Bonus：完成這個階段之後

• 對 anthropics/claude-cookbooks 發一個 PR（小修正、文件更新）
• 把自己的 plugin 投稿到社群 marketplace
• 寫一篇文章，比較自己的 hello-MCP server 跟官方 modelcontextprotocol/servers 收的某一個

Stage 6 — 上下文管理（Context Engineering）：RAG 與 Memory

繁體中文 | 简体中文 | English

⏱ 時間估算：2 週（約 10 小時）

💡 這 stage 用語密度高（RAG / 向量資料庫 / embedding / chunking / hybrid search / reranking⋯）→ 不熟先翻 resources/glossary.md 3。

📋 本章組成：定位 → 入口 → RAG 主軸（基礎 + 進階 + DSPy + Eval）→ Bridge → Memory 主軸（3 pattern + Trio + 進階）→ Chunking → Reflexion / Reasoning → 練習 → Projects

🔑 關鍵名詞：見 resources/glossary.md 3（memory / RAG / embedding / chunking / reranking）

本 stage 的核心不是「多背一點名詞」，而是理解 agent 如何管理 context。

• RAG 解決的是：現在要從外部知識庫查哪些資料？
• Memory 解決的是：agent 應該跨對話、跨 session、跨任務記住什麼？
• Context Engineering 是更上層的問題：每次 LLM call 前，該把哪些資訊組進 prompt，讓模型在有限 context window 內做出正確決策？

→ 接著 Stage 7 三層工程分工：Prompt = 單次怎麼問 / Context = 這次該給哪些資訊 / Harness = 整個 agent system 怎麼跑起來。本 stage 是中間那層。

Agent 需要的兩種 context 能力

1. Retrieval：從外部知識庫找出和當前任務相關的資料。
2. Memory：保留跨對話、跨 session、跨任務的狀態、偏好與經驗。

RAG（Retrieval-Augmented Generation） 是目前最常見的 retrieval 架構；Memory 則負責讓 agent 記得使用者、任務歷史與自己的過去經驗。這一章會把兩者分開講，避免把「查資料」和「記事情」混在一起。

先把名詞切開：Retrieval / RAG / Vector Store / Memory 不是同一件事

🎯 Context Engineering 是什麼（先定位）

一句話：Context Engineering = 決定每次呼叫 LLM 時、要把哪些資訊塞進它看得到的視窗（context window）。

重點不是「開了幾次對話」、是「每次對話裡塞了什麼」。Karpathy 2025-06 原 tweet 講得最精準：「把對下一步有用的資訊剛好填進視窗的精細藝術」。

📺 視覺學習：李宏毅 2025 第 2 講 — Context Engineering：AI Agent 背後的關鍵技術（NTU 生成式人工智慧與機器學習導論 2025）

三層 stack 中的位置

詳細對照表見 Stage 2 進階。

本 stage 處理 4 個 sub-problem 中的 2 個（Lance Martin 2025 framework）

4 個常被搞混的概念 — 一張表分清楚

→ 核心區分：Memory 是能力、Embedding 是資料轉換、Vector DB 是儲存、RAG 是架構 pattern——這 4 個常被混用、實際上是 4 個不同層的概念。

RAG vs Long Context vs Fine-tuning — 何時用什麼

LLM 知道你的私有 / 領域資料、有 3 種主要做法。本 stage 教 RAG，但你要知道何時不該用：

→ 怎麼選：先試 RAG（成本最低、變動最容易）→ RAG 撈不到才考慮 Long Context → 兩個都不行才考慮 Fine-tuning。進 Stage 7 學 fine-tune deploy。

📌 學習目標

• 建一條基本 RAG 流水線（chunk → embed → store → retrieve → generate）
• 看出 RAG 不該用在哪些地方（以及該用在哪些地方）
• 區分 short-term、long-term、episodic、semantic memory
• 理解 vector embedding 與相似度搜尋
• 知道進階 RAG（GraphRAG / Contextual Retrieval / Hybrid Search）何時加、何時不加

🚪 進入條件

你應該已經：

• 完成 Stage 3（會寫 tool use、會呼叫 LLM API、看得懂 ReAct loop）—— 硬性技術前置
• 走過 Stage 4（agent frameworks）+ Stage 5（Claude Code 生態）—— curriculum 主線是 3 → 4 → 5 → 6（見 README 學習地圖）；非硬性技術前置，但 RAG / memory 常跟 framework + Claude Code memory 機制搭配、照順序走過理解更完整，且 Stage 7 預期你已完成 4 + 5 + 6
• 能跑 Python pip install 安裝 SDK（後面練習會用到 chromadb、sentence-transformers 等）
• 對 list / dict / generator 等基礎 Python 結構上手

沒到的話 → 回 Stage 3 或 Stage 0 環境設定。

📚 必修閱讀

1. LlamaIndex — RAG concepts — 最清楚的入門
2. LangChain — RAG tutorial — 動手做
3. Pinecone — Learning Center — vector DB 基礎
4. Anthropic — Contextual Retrieval — Anthropic 搭配 prompt caching 的 RAG 寫法
5. LangChain — Text splitters — chunking 策略入門

🙏 Memory 章節特別推薦 datawhalechina/hello-agents：本 stage 探討 memory 的概念跟初級實作、要 chapter-length 深入版請看 hello-agents 對應章節——short-term / long-term memory 的差異、context engineering 怎麼動態組裝、session 持久化、forgetting strategy 都講得最完整。本 stage 是路線圖、那邊是深度教材。

🧭 單元指引（漸進式 flow）

本章按 RAG 先學、Memory 後學 的順序走——RAG 是 context engineering 最基礎、最常用的工具，Memory 是 agent 跨對話/跨 session 的能力；先把 RAG pipeline 跑通、再帶到 Memory 設計，最後回頭看 Chunking 細節。

閱讀順序建議：

1. 🌐 RAG 基礎流水線（下一節）— 建立 mental model
2. 🚀 進階 RAG 技巧 — GraphRAG / Contextual Retrieval / Hybrid Search 等 production 升級
3. 🌉 從 RAG 到 Memory — 為什麼 RAG 還不夠、需要 Memory 補哪段
4. 🧠 Memory 設計 — 短期 vs 長期、3 種 pattern、CoALA framework
5. 🧩 Chunking 細節 — RAG / Memory 都會用到的技術深入

讀這章時可以順便思考：RAG 不適合哪些應用場景？哪些場景適合 RAG，但基本 RAG 還不夠好？這會帶到後面的 GraphRAG / Self-RAG / RAPTOR 等進階技術。

🌐 RAG 基礎流水線

RAG（Retrieval-Augmented Generation）= 「retrieve 相關片段 → 塞進 prompt → 生成」這個 pattern。可以想成在幫 agent 蓋圖書館——你要先把書放好、分類好，後續要查資料時，才會又快又精準。

最基礎的 RAG 拆成兩條流水線：

• 資料預處理（ingest 一次）：ingest → chunk → embed → store（index）。這一步是在建立可檢索的知識庫。
• 檢索生成（每次 query）：retrieve → generate。這一步是在使用者提問時，找出相關內容，再交給 LLM 生成回答。

圖中的 RAG Fusion、query rewrite 等屬於進階檢索技巧。第一次學 RAG 時，先理解主線流程即可。

5 個 step 解讀：

上面只是最小骨架。最常踩的坑 3 個：

• chunk 太大 / 太小：太大、retrieve 撈到的 chunk 裡只有一句相關、其他都是雜訊；太小、失去前後文（見 Chunking 細節）
• embedding model 選錯：中文文件用英文 model、retrieval 精度直接掉一半
• top-k 設太大 / 太小：太小、漏 relevant chunk；太大、雜訊高 / token 燒

📚 想看更多 RAG 踩坑指南 + 解法：NirDiamant/RAG_Techniques ★ 大型 production RAG cookbook、含 30+ 技巧 + Jupyter notebook 範例。

跑完基本骨架後，跑 動手練習 1-4（embeddings / vector DB / chunking / 完整 pipeline）建立手感、再進下一節 進階 RAG 技巧。

🚀 進階 RAG 技巧（跑完基本 RAG 之後再看）

下面六個 subsection 是 2024-2026 production RAG 最常加上的槓桿，按「加進 pipeline 哪一層」分組：

• Retrieve 後 —— GraphRAG / Contextual Retrieval / Hybrid Search & Reranking
• Retrieve 前（query 改寫）—— Query Transformations
• Retrieve 期間（control flow）—— Adaptive / Agentic RAG
• Index 結構 —— RAPTOR
• 2024-2026 縱覽 —— 其他 17 個值得知道的技巧

先跑完上面 RAG 基礎拿到基準版本、再回來看這裡——不然你會在沒有基準的情況下調參數，永遠不知道是哪個改動帶來提升。

🔗 GraphRAG — 知識圖譜 + RAG

Mental model：vanilla RAG 把文件切成 chunk、靠 embedding 相似度撈片段——但它不知道哪些 entity 是同一個東西、entity 之間有什麼關係。GraphRAG 在 ingest 階段先用 LLM 把文件抽成 (entity, relation, entity) 三元組建知識圖譜，retrieve 時除了向量比對、還做 graph traversal 撈到「相關 entity 的相關 entity」。

何時用：

• 任務需要 multi-hop reasoning（A → B → C 才能回答）
• 跨多份文件、entity 互相引用（公司財報、論文引用、調查報告、法律案例）
• 問題形如「X 影響了什麼 Y、Y 又連到哪些 Z」——vanilla RAG 通常只撈到 X 那塊文件

何時不用：

• 文件之間沒有 entity-relation 連結（純 FAQ、產品手冊各自獨立）
• 知識庫小（< 1k chunk）——vanilla RAG 已經夠
• 預算緊——建 KG 的 token 成本可能是普通 RAG 的 10-50 倍

代表 framework：

• HKUDS/LightRAG ★ 35.1k MIT EMNLP 2025 — 目前社群最熱的選擇、輕量、KG + vector hybrid、cost 比 Microsoft 版低
• Microsoft GraphRAG — 原版 reference 實作、Apache-2.0、含 community detection
• gusye1234/nano-graphrag — < 1000 行的最小實作、適合先讀懂原理

Paper：From Local to Global: A Graph RAG Approach to Query-Focused Summarization (Edge et al. 2024) — Microsoft GraphRAG 的原始 paper、解釋 community summarization 為什麼能解 global query

🪶 Contextual Retrieval — Anthropic 的 prompt-caching 解法

Mental model：vanilla chunk 失去原文件 context——「Q3 revenue grew 15%」這個 chunk 抽出來、你不知道是哪家公司、哪一年的 Q3。Anthropic 2024 提出：ingest 時用 LLM 為每個 chunk 寫一段 50-100 token 的 contextual header（「This chunk is from ACME Corp 2024 Q3 earnings, discussing the cloud segment...」）拼到 chunk 前面再 embed。搭配 prompt caching 讓「整份文件 + 每個 chunk」這個 prompt 只計費一次、後面所有 chunk 共用 cache。

何時用：

• chunk 字面意思跟原文件主題距離遠（財報、研究報告、長 narrative 文件）
• 你願意一次性付 ingest 成本、換 retrieve 精度
• 已經在用 Claude / 想用 prompt caching（其他 model 也能跑、就是沒 cache 折扣）

何時不用：

• chunk 本身就是 self-contained（FAQ、產品介紹頁、定義條目）
• 知識庫經常變動（每改一次就要重 ingest）
• 預算極緊——即便 cache 折扣後、ingest 成本仍比 vanilla 高

為什麼省 90% cost：Anthropic 報告 prompt caching 把「整份文件當 cached prefix」、每個 chunk 只送差異——比起每 chunk 都餵整份文件、成本降到約 1/10。但這只省 ingest、不省 retrieve 階段。

代表實作：

• Anthropic — Contextual Retrieval blog ⭐ — 官方說明 + benchmark（failed retrieval rate 從 5.7% 降到 1.9%）
• Anthropic cookbook — 端到端 Jupyter notebook、含 prompt 模板

搭配技巧：Anthropic 同篇 blog 還建議疊上 Contextual BM25（contextual chunk 同時餵 vector + BM25）+ reranking——剛好接到下面 Hybrid Search & Reranking。

🎯 Hybrid Search & Reranking — production RAG 的兩個常見強化元件

Mental model：

• Hybrid Search = vector similarity（語意像）+ BM25 / keyword（字面像）並查、用 RRF (Reciprocal Rank Fusion) 之類融合分數。解決純 vector search「query 跟 chunk 同義但用詞不同沒撈到」+「人名 / 編號 / 罕用詞語意 embedding 太弱」的雙重盲點。
• Reranking = 第一階段 retrieve top-50（recall 優先、寬鬆撈）→ 用 cross-encoder reranker 重新打分排成 top-5（precision 優先、精準篩）。cross-encoder（query + chunk 一起進 model）比 bi-encoder（query / chunk 分開 embed）精準很多、但太慢、所以只用在第二階段。

為什麼是「必加的強化元件」：production RAG 評測幾乎一面倒——加 hybrid + reranker 後 recall@5 通常從 70% 上下提到 85-90%、邊際成本低、實作成熟。這是 cost / benefit 最好的兩個改動。

何時用：

• production RAG（不是 demo / 練習）
• query 包含人名、產品編號、技術術語、罕見字（純 vector 容易漏）
• 預算允許每 query 多 100-300ms latency

何時可以暫緩：

• 練習階段 / MVP（先把 vanilla RAG 跑通）
• 預算極緊 / latency 極敏感（reranker 是額外一次 model call）

代表工具：

• Hybrid search：Weaviate（內建 BM25 + vector + RRF）/ Qdrant（支援 sparse + dense vector）/ pgvector + Postgres FTS
• Reranker：Cohere Rerank API（商業、最常用）/ BGE Reranker(開源、HuggingFace、中文表現好) / Jina Reranker
• Framework 內建：LlamaIndex 的 SentenceTransformerRerank / LangChain 的 ContextualCompressionRetriever

Paper / 入門：

• Pinecone — Rerankers and Two-Stage Retrieval — reranker mental model 講最清楚
• Anthropic — Contextual Retrieval（上面已列）— 同時示範 hybrid + reranker、有 benchmark

Query Transformations — HyDE / Multi-Query / RAG Fusion

Mental model：vanilla RAG 把 user query 直接 embed 去查——但 query 跟文件用詞 / 風格 / 抽象層級經常差太多（user 問「我胃痛怎麼辦」、文件寫「上腹部疼痛之鑑別診斷」）。Query transformations 在 retrieve 前先改寫 query、讓改寫版本更接近文件形式。

3 個代表技巧：

何時不用：query 已經是長 + 結構化（RAG over code、user 直接 paste error stack trace）——改寫反而引入雜訊。

Paper / 實作：

• HyDE (Gao et al. 2022) — 原始 paper
• RAG Fusion (Raudaschl 2023) — Multi-Query + RRF 的 reference 實作
• LangChain 內建 MultiQueryRetriever / LlamaIndex HyDEQueryTransform

🔁 Adaptive / Agentic RAG — Self-RAG / CRAG / Adaptive RAG（讓 retrieval 變成可判斷的流程）

Mental model：上面所有 RAG 技巧都假設「query 來 → retrieve → generate」是固定 pipeline。Self-improving RAG 把這個 pipeline 變成有判斷能力的 agent loop——LLM 自己決定要不要 retrieve、判斷 retrieve 品質、不夠就再查或改 query。這是 2024 RAG 研究的主軸。

為什麼這是 2024 主軸：固定 pipeline 在簡單 query（「Tokyo 首都？」不用 retrieve）+ 複雜 query（multi-hop、cross-doc）兩個極端都吃虧。讓 LLM 自己 routing → 兩個極端都解。

何時用：production RAG、query 類型分布廣（從事實題到推理題都有）、願意付 1.5-3 倍 latency 換準確度。 何時不用：query 類型單一 / 預算 / latency 極緊。

實作：LangGraph 有官方 Self-RAG cookbook + CRAG cookbook + Adaptive RAG cookbook、可直接套。

🌳 RAPTOR — 階層式遞迴 retrieval（ICLR 2024）

Mental model：vanilla chunking 把文件切扁平 chunk——但整本書的主旨不在任何單一 chunk 裡。RAPTOR 把 chunk 遞迴聚類 + 摘要、建一棵多層樹：底層 = 原 chunk、中層 = 一群相關 chunk 的摘要、頂層 = 全文摘要。retrieve 時可選整棵樹搜尋、或選特定抽象層。

為什麼有用：

• 抽象 query 撈得到（「這篇 paper 主要結論？」原 chunk 都沒這句、但頂層摘要有）
• 細節 query 也撈得到（底層 chunk 保留）
• 跟 GraphRAG 不同——RAPTOR 是樹（hierarchical summarization）、GraphRAG 是圖（entity-relation）

何時用：長文件（書、論文、報告）需要不同抽象層 query、知識庫 narrative 連貫。 何時不用：chunk 之間獨立（FAQ）、知識庫經常變動（重建樹貴）。

Paper / 實作：

• RAPTOR (Sarthi et al. ICLR 2024) ⭐ — 原始 paper
• parthsarthi03/raptor — 官方 reference 實作
• LlamaIndex 內建 RAPTOR pack

🧬 DSPy — 不寫 prompt、用 program 自動 optimize（Path 3 paradigm）

Mental model：傳統 RAG / Agent = 手寫 prompt + 手刻 chain。DSPy = 不寫 prompt——你只定義「signature」（input → output 的型別）、再寫 program（chain 結構）；DSPy 自己用 LLM compile 出最佳 prompt + few-shot examples + retriever 設定。Stanford NLP group 2024 提出、Karpathy 推、目前 production 越用越多。

何時用：

• 你的 RAG 用了 6 個月、prompt 累積到難維護、想自動 optimize
• 同一 program 要切換不同 LLM provider（DSPy 自動 recompile）
• agent system 有多個 step、想跟蹤 trace / metrics

何時不用：

• 你只有一個 prompt、不需要 optimization
• 第一次學 LLM、還沒摸過 prompting

代表 repo：stanfordnlp/dspy ★ 34.4k MIT、Stanford NLP group 官方、active 維護中。

怎麼放進 RAG：DSPy 跟本 stage 講的 RAG 技巧不衝突——你可以把 GraphRAG / Hybrid Search / Reranking 都當成 DSPy 的 module 來組、然後 compile。是 RAG 構築方式的「上層」typing 系統。

→ 跟 Path 1 / Path 2 reasoning 並列：Path 1 是「人手寫 prompt」、Path 2 是「訓練進 model 權重」、DSPy 是 Path 3「program 自動 search 出 prompt」。Stage 7 multi-agent 進階場景特別好用。

📊 RAG 進階技巧縱覽 — 2025-2026 三條主軸

進階 RAG 的 2025-2026 演化集中在 3 條主軸：

1. 🧠 KG + Memory 融合 — 從 flat vector store 走向「結構化、可演化、可聯想」的知識表示。代表：HippoRAG 2（海馬迴啟發、KG + PageRank、跨文件 multi-hop）、A-MEM、KAG。
2. 🎬 Multimodal RAG — 從文字 retrieval 走向圖像 / 影片 / 表格 native。代表：ColPali（PDF 頁面圖像直接 embed、繞過 OCR）、TV-RAG、MegaRAG。
3. 🤖 Agentic RAG — retrieval 從固定 pipeline 變 agent loop 內的 tool（agent 自己決定查幾次 / 怎麼查）。代表：A-RAG、Self-RAG（已上面 Self-improving）、SoK: Agentic RAG survey 2026。

另外 2 個值得追的方向：

• 🛡 RAG 安全 — corpus poisoning / prompt injection 進入 production 考量。代表：RAGPart / RAGMask。
• 🔧 不再手寫 prompt — 系統自動 search 出最佳 prompt + retriever 組合。代表：DSPy（Stanford「programming not prompting」典範、見上方 DSPy 段落）。

5 個值得深挖的代表作（速查）：

🌉 從 RAG 到 Memory — 為什麼 RAG 還不夠

讀到這你已會跑基本 RAG + 知道幾個 production 槓桿。但回頭看 Context Engineering 列的 3 個 problem domain——你只解決了 Retrieval，Memory 管理還沒碰。為什麼這兩件事要分開？

RAG 解決「從外部知識庫 retrieve 相關片段」——但 agent 還需要「自己 跨對話 / 跨 session 記事情」。這兩件事不是同一個問題：

3 個 RAG 不夠用的場景（剛好對應到 Memory）：

1. 跨 session 記 user preference / persona——user 上禮拜跟 agent 說「我是純素」、這禮拜回來、agent 還記得不能推薦肉食。RAG 知識庫不會這樣自動更新。
2. agent 過去成敗教訓累積（Reflexion 主場）——agent 第一次跑 task 失敗、反思「為什麼失敗」存起來、下次遇類似 task retrieve 進 prompt 避免重蹈覆轍。RAG 知識庫不會「記住自己的失敗」。
3. Long-horizon task 中間狀態——agent 跑 100 step task、中間需要保留 working memory 不丟失。RAG 不適合做這種「短期 + 結構化 + 高頻寫入」的 state。

→ 結論：RAG 跟 Memory 是互補而非取代。Production agent 通常兩個都要：RAG 接外部知識、Memory 記自己跟 user 的互動。下節 Memory 設計 教你怎麼挑 memory pattern。

🧠 Memory 是什麼 + 怎麼設計

📺 視覺學習：李宏毅 2025 第二講 — 一堂課搞懂 AI Agent 的原理（含 read / write / reflection memory module）（NTU 生成式AI時代下的機器學習 2025）

Working memory vs Long-term memory — 兩種時間尺度

→ 在 agent 裡，「短期記憶」嚴格說更接近 working memory——它不是外部儲存、是目前 prompt / context window 裡看得到的內容。

Episodic / Semantic / Procedural memory — 三種內容類型

注意：上面 working / long-term 是時間軸，下面三種是內容軸——兩組分類正交、不互斥。Long-term memory 裡可以同時有 episodic + semantic + procedural 三種。

→ 這 3 種對應 CoALA framework、production agent 通常 3 種都用得到。Reflexion 是典型的 episodic memory 應用（累積 trial 的成敗經驗）。

這裡的工作階段（session）可以理解成一次連續互動，例如同一段聊天、同一次任務，或同一次 agent 執行。

3 種設計 pattern（什麼時候用什麼）⭐ Track B 必看

不是所有 agent 都需要外部 memory store。Memory 架構選錯會花十倍 token 達同樣效果。

這是進練習前要建立的 mental model——下面練習 1-5 跑的是「pattern 3 vector store」，但 production 你可能不需要這麼複雜。

怎麼選：

• 對話 chatbot 沒跨 session → pattern 1
• agent + 長對話、要記今天聊過什麼 → pattern 2
• agent + 跨 session + 知識庫（本 stage 練習場景）→ pattern 3
• production 大型 agent → 通常混用：近期 pattern 1/2、長期 pattern 3

💡 Track B 重點：你 Stage 7 寫 multi-agent 時，每個 agent 都會有「自己的 memory」+「shared memory」雙層——需要的 pattern 通常是 2 + 3 混用。先在本 stage 把 3 種 pattern 跑透，到 Stage 7 才不會被 multi-agent memory 設計卡住。

⭐ 5 個可上線使用的 Memory Layer（按 use case 挑）

Star 數與 benchmark 會變動；這裡重點不是排行，而是理解每個 memory layer 的設計取向。

學完 3 pattern 後、production 不必自己刻 memory store。下面 5 個都是 Apache-2.0 / MIT、active 維護、各擅其場：

怎麼挑：

• 寫 coding agent → agentmemory（MCP-native、跟 Stage 5 ecosystem 完美 align）
• 做 chatbot / 個人助理 → mem0（最成熟、最大社群）
• 做 long-running 跨月 agent → Letta（OS-paging 強項）
• 需要時間軸 + audit → Zep（temporal KG）
• 已在 LangChain stack → LangMem（不必跳 framework）

另加官方 docs：Anthropic Memory Tool（Claude 官方 tool-based memory、file-based、API 直接 call）、LangChain Memory concepts（framework 內各 memory class 對比）。

進階：CoALA framework — agent memory 的 4 層 taxonomy

Sumers et al. 2023 — Cognitive Architectures for Language Agents 把 agent memory 拆成 4 種、是現在最常用的 mental model：

→ 為什麼有用：上面 3 種 pattern（buffer / summary / vector）都只在處理 working + episodic。Production agent 4 層都要設計——CoALA 是檢查表，看看你的 agent 哪一層缺了。

進階：Generative Agents — 三分數打分（經典案例）

Park et al. 2023 — Generative Agents: Smallville 的小鎮模擬有 25 個 NPC agent、每個都有自己的 memory stream。retrieve 時用三個分數加權：

• Importance：LLM 自己幫每個 memory 打 1-10 重要性分（吃飯 = 2 分、分手 = 9 分）
• Recency：時間衰減（exponential decay）
• Relevance：跟當前 query 的 embedding 相似度

最終分 = α·importance + β·recency + γ·relevance、排前 k retrieve。這是 2024-2025 可上線使用的 memory layer（mem0 / Letta）的概念骨架。

💻 官方 code：joonspk-research/generative_agents ★ paper 配套的小鎮模擬 code repo、想跟著實作 memory stream + 三分數 retrieval 看這裡。

2024-2026 最新 Memory 作品 — 三條主軸

Memory research 2024-2026 集中在 3 條主軸：

1. 🧠 結構化、可演化、可聯想 — 從 flat vector store 走向人腦 / Zettelkasten 啟發的記憶結構。代表：A-MEM（memory 之間自動建 link）、HippoRAG 2（KG + PageRank、海馬迴啟發）。
2. 📚 2026 survey 大爆發 — 一年內 5 個重磅 survey + 跨領域整理。代表：Memory in the Age of AI Agents（3 維 taxonomy + benchmark）、Memory for Autonomous LLM Agents（write-manage-read loop 形式化）。
3. 🛡 Memory security 變獨立子領域 — agent 跑久了、memory 會被 cross-session poisoning / 未授權存取攻擊。代表：Memory Security survey（Stage 7 安全 會接到）。

4 個值得深挖的代表作：

→ 跑很久的 agent（週 / 月為單位）、上面 survey 必讀。

🧩 Chunking 細節（技術深入）

好的 chunking 可以讓 LLM 在有限 context 內，用更精確、完整的資訊生成回答。它不是把文字平均切開。

切法取決於應用場景與文件內容。它會決定 retriever 看見的最小語意單位。

一個好 chunk 要同時做到兩件事：夠完整，讓模型看得懂上下文；夠聚焦，讓檢索不帶太多雜訊。chunk 太小會失去前後文，chunk 太大會讓相似度搜尋變鈍。

常見策略：

• 固定長度（Fixed-Length）：照字元數或 token 數切。優點是簡單穩定；缺點是一板一眼，容易切斷段落、句子或表格。
• 滑動視窗（Sliding Window）：每個 chunk 之間保留重疊區塊（overlap）。優點是比較不會在邊界掉資訊；缺點是索引量會變大。
• 遞迴切割（Recursive）：先嘗試保留段落，如果長度還是不適合，再退到句子、字詞等更小單位。通常是入門 RAG 的好基準。
• 語意切割（Semantic Chunking）：依 embedding 或語意變化切，也就是當前區塊與前一個區塊的語意相似度出現差異。適合長文件，但成本與複雜度較高。
• 混合策略（Hybrid）：依照應用場景，思考不同文件結構該怎麼混搭切法。例如，一篇論文可能要保留章節、表格、公式與引用脈絡。

📚 經典教學：Greg Kamradt — 5 Levels of Text Splitting ★ chunking 入門必看、從 character-based 一路講到 agentic chunking 五個層次、含 Jupyter notebook。

第一次做 RAG 時，不要一開始就追求複雜切法。LangChain 文件建議多數情境先從 RecursiveCharacterTextSplitter 開始。

先跑出基準版本，再用後續 retrieval 結果決定要不要換策略。

from langchain_text_splitters import RecursiveCharacterTextSplitter

text = "這是一個很長的文件內容...（此處省略一千字）..."

splitter = RecursiveCharacterTextSplitter(
    chunk_size=100,
    chunk_overlap=20,
    length_function=len,
)

chunks = splitter.split_text(text)
print(f"共切成 {len(chunks)} 個 chunk")
print(chunks[0])

直覺判斷 chunking 好不好，可以先看兩件事：

• 回答缺漏資訊，或有頭無尾：通常是 chunk 太小，或 overlap 不夠。
• 回答包含正確資訊，但混入無關內容：通常是 chunk 太大，或 top-k 撈太多。

進階思考：

• chunking 不是一次設定好就結束，要配合真實 query 與失敗案例反覆調整。
• chunk size、overlap、top-k、reranker 會互相影響，不要只單看其中一個參數。
• 想想看，如果今天要 RAG 的資料有含圖片的 PDF、會議字幕檔，要如何切割比較好？
• chunking 的進階變形（Sentence-Window / Parent-Child / Multi-Vector）見 進階 RAG 技巧縱覽表。

🪞 進階：帶持久記憶的 Reflexion 完整版 ⭐ Track B 選讀

本節是 concept + routing、不是練習。延續 Stage 3 反思 的基本版（single-session Actor / Critic loop），講為什麼有些反思需要持久記憶——這版本才真正屬於 Stage 6 主題。

Reflexion 完整版跟 Self-Refine 差在哪：

為什麼這個版本要 memory：Reflexion paper 的 verbal reinforcement learning 是「agent 跨 trial 累積教訓」——agent 嘗試 task → 失敗 → 反思「為什麼失敗」存起來 → 下次遇到類似 task 時把過去反思 retrieve 進 prompt，避免重蹈覆轍。這就需要 persistent episodic memory，跟本 stage 上面講的 3 種 memory pattern 直接接上。

典型架構（持久記憶完整版）：

→ 跟 Stage 3 反思的差別：Stage 3 是 single-session in-context loop（沒外部 store）、本節是 persistent episodic memory store + retrieve（跨 trial 累積）。

📚 想動手 / 想深入

Paper：

• Reflexion (Shinn et al. 2023) ⭐ — 完整版 paper，Algorithm 1 寫出 memory buffer 怎麼用
• Self-Refine (Madaan et al. 2023) — 對照 baseline，沒 episodic memory 的版本

Reference 實作：

• noahshinn/reflexion — paper 第一作者的 reference 實作（含 episodic memory 完整流程）
• LangChain — Reflexion — LangGraph 版本，跟本 stage 練習 4 RAG pipeline 直接接得起來
• mem0（已在上面列）+ Letta（已在上面列）— 可上線使用的 memory layer，可以直接當 Reflexion 的 episodic store

💡 跟 Stage 3 反思的分工：

• 想理解「反思 loop 怎麼運作、單次怎麼跑」→ Stage 3 反思
• 想理解「反思怎麼跨 session 累積、agent 怎麼從過去學教訓」→ 本節
• 想看 production agent 內怎麼用反思（Cursor / Claude Code）→ Stage 5 5.6 Harness Internals

🤔 進階 Reasoning / Reflection — 2024-2026 思潮 ⭐ 兩個 track 都看

Reflexion 是 prompt-based reflection——LLM 在 inference 時自己改自己。2024-2025 出現了第二條路：訓練時就把 reflection 練進 model（OpenAI o1 / DeepSeek R1）。兩條路你都該知道。

Path 1：Prompt-based reflection / reasoning（傳統做法）

Path 2：Trained-in reasoning / reflection（2024-2026 大轉折）

📺 視覺學習：李宏毅 2025 第七講 — DeepSeek-R1 這類大型語言模型是如何進行「深度思考」(Reasoning) 的？（NTU 生成式AI時代下的機器學習 2025）

OpenAI o1（2024-09）開啟、DeepSeek R1（2025-01）開源化、DeepSeek-V4-Pro（2026-04 preview、agent-focused 開源 reasoning）+ Claude Opus 4.7（2026-04）+ GPT-5.5（2026-04）+ Gemini 3.1 Pro（2026-02）為當前 frontier——把「step-by-step thinking + 自我糾錯」訓練進 model 權重、inference 時自動展開長 reasoning chain（thinking tokens）。這是 2024-2026 LLM 最大典範轉移、目前所有 frontier model 都走這路。下表只列當前（2026-05）frontier——歷史前身（o1 / R1 / Sonnet 4.5 / Gemini 2.5）省略、想看 lineage 看每家發布日列。

兩條路怎麼選

💡 2025-2026 觀察：

• reasoning model 把 Reflexion 那套吞進權重——但 prompt-based reflection 沒被取代：agent loop（控制反思時機 / 內容）+ multi-agent debate 還是必須的
• 2026 開源逼近閉源——DeepSeek-V4-Pro（2026-04 preview、MIT license）把 R1 reasoning 併入主線、agent-focused 訓練、跟 GPT-5.5 / Gemini 3.1 Pro 差距持續縮小
• agent capability 變主訴求——V4 / Opus 4.7 都把 agent-as-product（SWE-bench / Terminal-bench / tool use）當 headline benchmark、單純 reasoning 已經不夠賣
• 兩條路會長期共存、production agent 兩個都用

📏 RAG / Memory Eval — 跑得起來 ≠ 跑得準

為什麼這節重要：RAG / Memory 系統最大的坑是「看起來能跑、實際 retrieval 精度爛」。沒 eval、你不會知道改 chunk size / 換 embedding / 加 reranker 是不是真的有幫助——只會看到「答案好像比較順」這種主觀印象。Production agent 沒 eval 等於沒測試。

3 個核心 metric：

代表 framework：

• explodinggradients/ragas ★ 13.9k Apache-2.0 ⭐ — RAG evaluation 標準工具、含 8+ metric（faithfulness / answer relevance / context precision / context recall 等）、支援 reference-free + reference-based eval
• TruLens — observability + eval 一起、LangChain / LlamaIndex 整合好
• LangSmith — LangChain 官方 eval + tracing、closed-source SaaS

怎麼開始：跑完 動手練習 4（完整 RAG pipeline）後、加上 ragas eval、measure 一次 baseline——再回頭調 chunk / embedding / top-k、看數字怎麼動。沒這一步、調參全是猜。

→ Stage 7 Eval 接續本節、把 eval 擴到 multi-agent / full harness。

🛠 動手練習（基礎 illustrative 練習）

練習 1：Embeddings

把 100 個句子做 embedding，找出某個 query 的最近鄰。理解 vector 之間的距離意義。

練習 2：Vector DB

把 embedding 存進 Chroma，做語意 query。比對「跟 keyword search 差在哪」。

練習 3：Chunking 對照

拿同一份文件做三種切法：固定長度、段落切法、heading-aware 切法。用 5 個真實問題比較 top-k 結果，記錄哪種切法比較容易撈到正確上下文。

練習 4：完整 RAG 流水線

把一份 PDF 切塊 → embed → 取 top-k → 生成回答。這是大多數 RAG 應用的基本骨架。

練習 5：Long-term Memory

讓 agent 在多輪對話之間記得事情。可以用 mem0 或自己用 vector store 接。

🎯 常用 Memory / RAG 工具推薦（按用途分類）

不知道從哪裡開始挑工具？下面是 2025 後段業界常用搭配——挑入口看「場景」、想深入點連結看 repo：

建議入手順序：

1. 第一個必裝：Chroma + LlamaIndex（跑 Stage 6 練習）
2. agent 要記事：加 mem0（最簡單的 memory layer）
3. 開始 production-scale：換成 Qdrant 或 pgvector
4. 想升級到進階 RAG：看上方 進階 RAG 技巧 三個 subsection

🎯 精選 Projects（範本 / spec / 範例 collection）

按用途分類、17 個項目一張表搞定。挑入口看「適合誰」、想深入點連結看 repo。

✅ 進入 Stage 7 前的自我檢查

你能不能：

• 寫一條 50 行的 RAG 流水線（load → chunk → embed → store → query → answer）
• 解釋為什麼天真的切塊在長文件上會失敗
• 針對 API 文件、PDF、表格設計不同的 chunking 策略
• 在某個規模下，能在 Chroma、Qdrant、pgvector 之間做出選擇
• 區分「給 agent memory」跟「用 RAG」這兩件事
• 解釋 RAG 跟 Memory 各補哪段（從上面 從 RAG 到 Memory 表）

如果都可以 → 前往 Stage 7 — Multi-Agent · 進階應用。

Stage 7 — 多 Agent 系統與穩定運作（Multi-Agent & Production）

繁體中文 | 简体中文 | English

⏱ 時間估算：2-4 週（約 15-30 小時）

💡 用語密度高（multi-agent / handoff / eval / observability / guardrails⋯）→ 翻 resources/glossary.md 4 + 6。

📋 本章組成：〔Multi-Agent · Production 化 是什麼（先定位）+ 三層工程分工 + 何時用 multi-agent〕→ 學習目標 → 進入條件 → 必修閱讀 → Harness Engineering（8 個核心元件含 Cost/Latency）→ 動手練習（含練習 6 Cost Optimization）→ Agent Benchmark Landscape：怎麼看，不要只看排行榜 → 常用工具推薦 → 精選 Projects → 自我檢查 🔑 關鍵名詞：見 resources/glossary.md 4 + 6（multi-agent / orchestration / handoff / eval / observability / harness（模型外圍的執行與控制層））

最後一個階段。你正從「我會做 agent」走向「我能讓 agent 真的給人穩定用——多個 agent 協作、有 eval、有 observability、能部署到可用環境」。「Production 化」 ≠ enterprise scale——只要 agent 能穩定產出 + 能讓別人使用、就算進入這 stage 範圍。

🎯 Multi-Agent · Production 化 是什麼（先定位）

本 stage = 多 agent 怎麼協作 + 把 agent 從 prototype 推到能穩定給人用的程度。三句話釐清範圍：

• 不是只學 framework——Stage 4 已教 framework 怎麼挑
• 不一定要 enterprise scale——只要 agent 能讓別人用、就算 production 化
• 核心是 harness engineering——8 個核心元件 + eval + observability + cost / latency 控制

跟前後 stage 的分工：

• Stage 4 = 單 agent framework 怎麼挑、ReAct / Plan-Execute 等 pattern
• 本 stage = 多 agent 協作 + harness engineering（執行系統工程）+ 部署到可用環境 / observability / eval

三層工程分工：Prompt → Context → Harness

工程分工可以分成三層、對應 stack 不同位置（不是 call 一次 vs 多次的差別）：

白話差異：

• Prompt = 設計一個好的問法，讓模型這次回答準
• Context = 動態決定要放入哪些背景、記憶、文件、工具結果，讓模型知道現在情境
• Harness = 把 prompt、context、工具、狀態、流程控制、錯誤處理串成一套可以運作的系統

本 stage 三個核心問題：

1. Multi-agent 協作 — debate / planner-executor / peer review / handoff / supervisor-worker pattern
2. Harness Engineering — agent loop / tool registry（agent 可呼叫工具的清單 + 介面定義）/ context manager / safety / retry / telemetry / eval / cost（8 個核心元件、下面詳述）
3. Production 化 — eval harness / observability / cost & latency 優化 / 部署到可用環境

跟 Stage 5 的分工（避免混淆）：

⚠ 但你真的需要 multi-agent 嗎？

Multi-agent 不是 default、是任務真的需要時才上的設計。多數場景應先嘗試 simple workflow 或 single agent；只有在任務天然可分解、需要平行探索、單一 context 不夠、或需要明確角色分工時，multi-agent 才值得引入。硬上會付 3-10× token、debug 困難、context fragmentation（context 被切散在多個 agent、彼此看不到全貌）嚴重。

📌 決策框架的 canonical 在 Stage 4：完整的 Anthropic / Cognition 立場對照 + 4 個「該上 multi-agent」訊號 + 每個訊號對應的 pattern，見 Stage 4 §什麼時候真的需要 multi-agent（設計階段決策）。本節只做 production 前的最後回頭檢查——4 個訊號一個都不在？ → single agent + 好 prompt + tool use 就夠、別硬上 multi-agent。本 stage 的 harness engineering 部分（8 個元件 / eval / observability）即使你最後用 single agent 也都會用到——所以即使你決定不走 multi-agent、本 stage 仍是必修。

📌 學習目標

• 設計 multi-agent orchestration 模式（debate、planner-executor、peer review）
• 為 agent 架一套 evaluation harness
• 加上 observability（tracing、logging、cost tracking）
• 用 Anthropic SDK / OpenAI SDK 部署到可用環境（進階功能：streaming、prompt caching、batching）
• 把 agent deploy 到 production（Docker、serverless、monitoring）

🚪 進入條件

你應該已經：

• 完成 Stage 4（用過至少一個 agent framework 跑 multi-agent demo）
• 完成 Stage 5（懂 MCP / Skills / Plugins / Subagents 各自角色，並用 5.6 解剖過 harness 內部）
• 完成 Stage 6（會基本 RAG，能講出 memory pattern 差異）
• 對 Docker / git / CI 基礎熟悉（部署成可用服務會用到）

沒到的話 → 補完前面幾個 stage。本 stage 是「組合所有前面學到的東西 → 跑 production」，缺一塊都會卡。

📚 必修閱讀

1. Anthropic — Building Effective Agents — 用 production 的角度再讀一次
2. Anthropic — Prompt Caching — 90% 成本下降的技巧
3. Anthropic — Message Batches API — 非同步 batch job
4. anthropics/courses — Prompt Evaluations ⭐⭐⭐⭐⭐ ★ 21k+ — Anthropic 官方 5 course umbrella、module 4「Prompt Evaluations」對應本 stage eval / observability 部分。Jupyter notebook、教怎麼系統化評估 prompt 跟 agent 行為
5. 任一 eval framework 的文件 — promptfoo 或 LangSmith 或 weave
6. ai-boost/awesome-harness-engineering（★ 940）— agent harness 的工具 / pattern / eval / memory / MCP / observability 全集合
7. ZhangHanDong/harness-engineering-from-cc-to-ai-coding（★ 1.3k+）— 從 Claude Code 原始碼學 harness 設計（中文）

🏗 Harness Engineering — production agent runtime 的工程設計 ⭐ 本 stage 核心概念

定位：模型外圍的執行與控制層

要把 LLM 變成可用的 agent，通常會碰到三層工程問題。這三層對應的是不同工程位置，不是單純用「一次 call」或「多次 call」來區分。

💡 Simon Willison 2025：「coding agent = LLM + harness」、harness = 所有不是 model 本身的程式碼。

💡 OpenAI 2026 也使用 "Harness Engineering" 這個說法（見 OpenAI Harness Engineering article、2026-02 發布）。

怎麼分辨自己在做哪一層？問：

1. 我改的是字串本身嗎？→ Prompt engineering
2. 我改的是塞進視窗的資訊嗎？→ Context engineering
3. 我改的是呼叫模型的外圍程式嗎？→ Harness engineering

→ 三層正交：1 次 call 的 RAG app 也在做 context engineering（重點是組視窗）；50 次 call 但沒做 retrieval 的 chatbot 仍只在做 prompt engineering。

Harness 的 8 個核心元件

Harness Engineering（Agent 執行系統設計）= 把 LLM、tools、memory、state、workflow control、retry、safety、eval、observability 與 deployment 串成一套可執行、可觀測、可維護的 agent 系統。

→ 所有不屬於 model weights、也不只是 prompt string 本身的工程元件都算 harness 範圍。一個 production-grade agent runtime 包含這 8 個核心元件（前 6 個是 runtime 內建、第 7 個 eval 是外掛工具、第 8 個 cost / latency 是跨層議題）：

Framework vs Harness 關鍵差別：

• Framework（Stage 4）規範 API — 你呼叫的介面長什麼樣
• Harness（本節）規範 runtime — 怎麼跑、怎麼 recovery、怎麼觀測

參考實作

想看 production-grade harness 長什麼樣？兩個 reference：

• Claude Code 整個 runtime — 是 reference harness 實作。讀 source 練習見 Stage 5.6（clone claude-agent-sdk-python 解剖 main loop + 上表前 6 個 runtime 元件位置；第 7 個 Eval harness 是外掛、第 8 個 Cost / Latency 是 cross-cutting、見下方深入段）
• anthropics/claude-agent-sdk-python source — 上面練習用的具體 repo

→ 本 stage 剩下的 6 個練習（multi-agent / eval / observability / SDK / deploy / cost）每個都是 harness 的一個面向。學完整 stage = 拼出完整的 harness engineering mental model。

第 8 個核心元件深入 — Cost / Latency Optimization（2024-2026 Production 化必修）

Production agent 跑久了、cost / latency 兩條線會吃掉你大半預算與使用者體驗。2024-2026 前沿模型都把這當 first-class API feature——會用 = 省 50-90% cost / latency。

Track A 怎麼用（用 CLI agent 的人）：

• 在 Claude Code / Cursor 設定 prompt caching、daily session 省 50-90% cost
• 用 RouteLLM / OpenRouter 動態切換 model（簡單問用 Haiku / Flash、難問用 Opus / Pro）
• Claude API 用 thinking_budget 參數控 reasoning model 的 token 上限

Track B 怎麼 build（自己寫 agent 的人）：

• 自架 cascade router、把 query embedding → classifier → model 對應
• 在 agent loop 內監控 token cost、超 budget 自動降級
• 部署到可用環境時整合 semantic cache 層
• Helicone / langfuse 等 observability 平台都已內建這幾招、不用自己寫

🛠 動手練習（基礎 illustrative 練習）

練習 1：Multi-Agent 辯論

兩個 agent 辯論一個題目（例如「該用 Python 還是 Rust 寫 backend」），第三個 agent 當裁判。觀察辯論收斂或分歧的 pattern。

練習 2：Eval

替你前面的 agent 寫一份 eval，跑 N 次量成功率。把「我用眼睛看一下」的習慣換掉。

練習 3：Observability

把 LangSmith、Helicone、或 weave 接上一個 agent，看完整 trace。理解「沒 observability 的 agent debug = 黑盒」。

練習 4：SDK 進階

在同一次呼叫裡用 streaming + prompt caching + tool use。看成本怎麼降下來。

練習 5：Deploy

把一個 agent 包進 Docker，deploy 到雲端（任何 provider 都行）。學會把 prototype 變成可以給別人跑的東西。

練習 6：Cost Optimization（新加）⭐

量你前面任一個練習 agent 的 token cost、加上 prompt caching、再量一次。觀察 cache hit rate 跟 cost 下降的對應關係。Bonus：接 RouteLLM 或 OpenRouter、做 cascade routing（簡單 query → Haiku / 難 query → Opus），量平均 cost。

📊 Agent Benchmark Landscape：怎麼看，不要只看排行榜 + ⚠ Reward-Hacking 警告

挑 model / 打造 agent 之前、你會想看 benchmark 數字——但 2026-04 UC Berkeley 發現 8 個主流 agent benchmark 全部可被 reward-hack 到 ~100%。下面是 2026 leaderboard 現況 + 怎麼看不被騙。

主流 Agent Benchmark 2026-05 SOTA

→ 詳細排行 + 即時更新：Agent Benchmark Leaderboard 2026、Rapid Claw AI Agent Framework Scorecard 2026

⚠ Berkeley 2026-04 Reward-Hacking 警告

UC Berkeley RDI 2026-04-12 報告：用 automated scanning agent 系統性 audit 8 個主流 benchmark（SWE-bench / WebArena / OSWorld / GAIA / Terminal-Bench / FieldWorkArena / CAR-bench 等）、每個都能 reward-hack 到接近 100%、agent 一個 task 都不用真正解。

意思：leaderboard 上「Claude 87.6% / GPT 85.0%」這種數字、可能其中 X% 是 hack 出來的、不是真的解 task。

怎麼看 benchmark 不被騙

哪些 benchmark 較難 hack（2026-05）：

• τ-bench — 多輪對話 + tool use、reward function 較密集
• RE-bench — research engineering 真實任務
• 你自己的 production eval set ⭐ 永遠是最可靠的

💡 production agent 的 eval 紀律：

• 不要把外部 benchmark 數字當 ground truth、它告訴你「上限」不是「真實表現」
• 你自己的 eval set（內部 hold-out test）才是上線決策的依據
• 每次 model upgrade → 跑內部 eval set 驗證、不只看廠商公布的 benchmark 提升
• 接 langfuse / promptfoo 把 eval 自動化、每次 deploy 都跑

🎯 常用 Multi-Agent / Production 工具推薦（按用途分類）

不知道從哪挑工具？下面是 2025-2026 業界常用搭配——挑入口看「場景」、想深入點連結看 repo：