### HOW TO USE # How to use this curriculum — 主動 vs 被動學習 > 給每個動手練習 folder 的 meta-instruction。如果你跳過這一頁、會把這套教材當 reference book 讀完、學到大概 60%。讀完這一頁、用對方法、學到 100%。 ## 真實問題 每個練習 folder（譬如 `examples/stage-3/03-react-from-scratch/`）裡都有一個 **`starter.py`**——它**長得像 starter、其實是完整解答**。 如果你： ```bash git clone ... && cd examples/stage-3/03-react-from-scratch cat starter.py # 看完整解答 python starter.py # 跑通 python test.py # 全 pass ``` 你會以為「學會了」、其實**沒寫過一行 code**。 這是這份教材的最大設計缺陷。下面講怎麼繞過它。 ## 兩種學習模式 ### 🟢 主動模式（推薦、學到 100%） **步驟**： ```bash cd examples/stage-3/03-react-from-scratch/ # 1. 讀 README、了解這題在做什麼、預期 input / output cat README.md # 2. 把 starter.py 改名（藏起來、等下對照用） mv starter.py starter_reference.py # 3. 看 starter_reference.py 的「imports + function signatures」、不看 function body head -50 starter_reference.py # 4. 自己寫一個新的 starter.py、function body 自己想 $EDITOR starter.py # 5. 跑 test.py、看自己寫的能不能 pass python test.py # 6. 卡住超過 20 分鐘？才打開 starter_reference.py 對照 diff starter.py starter_reference.py # 7. 寫完一輪後、看 README 的 punchline + common pitfalls、跟你的 trial 對照 ``` **重點**： - **看 signature、不看 body**。imports / TOOLS_SPEC / function names + arg types 可以看；裡面怎麼實作要自己想。 - **卡 20 分鐘是健康的**。卡 1 小時也健康。卡 3 小時就回去看 reference、然後**默寫一遍**。 - **test 通過 ≠ 學會**。test 通過代表 logic 對；學會代表你**講得出**為什麼這 13 行 ReAct loop 必要、為什麼 `tool_call_id` 要配對、為什麼要 `max_iter`。 ### 🟡 被動模式（reference book、學到 60%） **步驟**： ```bash cd examples/stage-3/03-react-from-scratch/ cat README.md cat starter.py # 讀完整解答、理解每一行 python test.py # 確認跑得起來 ``` **何時用**： - 你**之前寫過 ReAct loop**、現在只是想看本 curriculum 是怎麼寫的、做 cross-reference - 你在**找 pitfall reference**（譬如 production 出 bug、想看 curriculum 提過沒） - 你是**講課老師**、要快速看完整套教材然後挑題目給學生 被動模式適合**已經會了**的人複習、不適合**沒寫過**的人入門。 ## 為什麼這份教材的 starter.py 是完整解答（不是 TODO skeleton） 短答：**v1 階段、為了快速 ship 完整可跑版本**。 長答：完整 starter.py 有 3 個好處（給維護者）： 1. **test 直接 pass**——確認 framework 整合沒漏東西 2. **不會 outdated**——隨 framework 升級可以馬上 fix（不必同步維護 template） 3. **新手 onboard 快**——把 repo clone 下來就能跑、降低裝環境 friction 但對學習者來講有 1 個大缺點：**容易被誤用成抄答案**。所以這份 HOW_TO_USE 文件存在、提醒你**自己改名、自己重寫**。 **v2 規劃**（未開始）：把 starter.py 分裂成 `starter_template.py`（TODO skeleton）+ `starter_reference.py`（完整解答）、test 預設打 template、學生 fill in、卡住才看 reference。這需要重做 ~20 個 folder、預計 v2 在 [`docs/TESTING_PLAN.md`](TESTING_PLAN.md) 之後排期。 ## 每個 stage 怎麼用這份教材 | Stage | 主動模式時間預算 | 被動模式時間預算 | |---|---|---| | Stage 3（tool use + ReAct） | 5-8 hr（每練習 1-1.5 hr） | 1-2 hr（讀過去） | | Stage 4（agent frameworks） | 8-12 hr（每練習 2 hr） | 2-3 hr | | Stage 6（RAG + memory） | 8-12 hr | 2-3 hr | | Stage 7（production） | 10-15 hr | 3-4 hr | **主動模式時間是被動的 4-5 倍**——這就是「卡住 + 修通」的時間成本、也是真學會的成本。如果你只有 1 週時間、選 1-2 個你覺得最重要的練習走**主動模式**、其他**被動模式**過。 ## 我自己（curriculum 作者）跑驗證踩到的 bug 跑 verification（2026-05-13）發現我寫的 starter / test **本身有 6 個 bug**： 1. **operator precedence** in test (`and` 比 `or` 緊) 2. **ChromaDB collection name length** (Chroma 1.0 break、'kb' 太短) 3. **EphemeralClient state leak** 跨 test fixture 4. **i18n key mismatch**（test 用中文 query、starter db 用英文 key） 5. **Smolagents `@tool` 要求 Google-style docstring `Args:`** 區塊 6. **Python 3.14 + tiktoken/regex 無 wheel**（CrewAI 在 3.14 裝不起來） **這對你的意義**：當你做主動模式、卡住時，**有可能不是你錯、是教材有 bug**。提 issue 上來、我會修。Bug 修在 commit [50c3bf8](https://github.com/WenyuChiou/awesome-agentic-ai-zh/commit/50c3bf8)。 ## 練習 checkpoint（每練習做完問自己這 3 題） 不要光看 starter.py 過去、問自己： 1. **「為什麼」**：這份 code 為什麼這樣寫、不那樣寫？（譬如 ReAct loop 為什麼必須把 assistant response 接回 messages？沒接會怎樣？） 2. **「拿掉 X 會怎樣」**：拿掉 `max_iter`、拿掉 `tool_call_id`、拿掉 `cache_control`，runtime 會出什麼問題？ 3. **「production 怎麼改」**：這份 demo code 上 production 還缺什麼？（提示：observability / eval / retry / auth 通常都缺） 回答得出來 = 真學會了。回答不出來 = 只是讀過。 ## 進入條件：每個 Stage 開始前自我檢查 不要直接從 Stage 4 開始——除非 Stage 3 的 6 個練習你**每個都用主動模式寫過 1 次**。 - **Stage 4** 前：必須能不查文件寫出 13 行 ReAct loop（Stage 3 練習 3） - **Stage 6** 前：必須能講出為什麼 schema 要寫 enum + required（Stage 3 練習 6） - **Stage 7** 前：必須會用 mock 寫 LLM unit test（Stage 3 練習 5 + 任何 Stage 4） 沒過 checkpoint 直接跳級、後面會卡住、回頭重做更慢。 ## 如果你卡住 順序： 1. **再讀一次 README 的 pitfall + punchline** — 80% 的卡住來自漏看某個關鍵設計 2. **打開 `examples/stage-5/tool-calling-tutor/` skill**（裝進 Claude Code）— tool calling 相關的卡住、4-symptom triage 帶你診斷 3. **看 `starter_reference.py`**（你改名藏起來的那個）— 對照你寫的差別、找出哪裡邏輯漏 4. **看 GitHub issue** 有沒有人問過 5. **開 issue** — 帶上你的 code + 你看到的錯誤、我會回 絕對不要：抄 `starter_reference.py` 就走。沒寫過 = 沒學會。 --- ## 給維護者：v2 path v2 把 starter.py 拆成 template + reference 的計畫： - 每個 folder 多 2 個檔案：`starter_template.py`（TODO skeleton）+ `starter_reference.py`（answer） - `test.py` 預設打 `starter_template.py`、有 env var 切到 reference 對照 - README 多 1 段 "Learning mode" 解釋 - 約 20 個 folder × 3 file changes = 60 個檔案 如果有人想接 v2、歡迎 PR。對應 issue / branch 等決定後開出來。 --- ### TESTING PLAN # Testing Plan — T3+ Verification Log > Updated 2026-05-13. Verification is **done**; this doc is now a historical log. > The branch `t3-stage-4-6-7-unverified` referenced in earlier versions has been > fully merged into `main` and deleted. ## ✅ Final state (everything on `main`) | Batch | What | How verified | Bugs fixed | |---|---|---|---| | Phase 3 — Stage 1 + 3 folder renames (6 folders) | `starter.py` (Ollama) / `starter_anthropic.py` / both test suites | `python test.py` + `python test_anthropic.py` per folder | 0 | | Phase A — `stages/03-tool-use-and-hello-agent.md` inline `
` (練習 2-6) | 5 simplified inline blocks + zh-Hans drift | `wc -l` parity, `grep` no residual Trad chars | 0 | | Phase B — `examples/stage-5/tool-calling-tutor/` skill | SKILL.md + 3 references + evals + trilingual READMEs | YAML frontmatter parses; evals.json valid JSON | 0 (live skill-install test still pending) | | Phase C — cross-references | stages/03 + stages/05 + CLAUDE.md links | `grep -c` confirms 10 references across 7 files | 0 | | **Stage 4 (5 ex)** | LangGraph + CrewAI + LangGraph workflow + Smolagents + Pydantic AI | 8/8 test suites verified green; ex2 CrewAI install-blocked on Python 3.14 (tiktoken/regex wheels) — code shipped unmodified | 3 (i18n key mismatch in ex3 + Smolagents docstring `Args:` requirement in ex4 + Pydantic AI version fallback in ex5 test) | | **Stage 6 (5 ex)** | embeddings + ChromaDB + chunking + full RAG + long-term memory | 10/10 test suites verified green | 2 (ChromaDB `kb` collection name too short for Chroma 1.0+; `EphemeralClient` state leak across test fixtures) | | **Stage 7 (5 ex)** | multi-agent debate + eval + observability + streaming/caching + FastAPI deploy | 10/10 test suites verified green | 1 (operator precedence: `and` binds tighter than `or` in fake_agent dispatcher) | **Total: 28/30 test files run green** + 1 install caveat (CrewAI on Python 3.14) + 1 pending live test (skill auto-load). **Total bugs fixed**: 6 — all in commit [`50c3bf8`](https://github.com/WenyuChiou/awesome-agentic-ai-zh/commit/50c3bf8). ## 🟢 Pedagogy v1 also shipped (2026-05-13) Recognized late in the session: every `starter.py` is a **complete solution**, not a TODO skeleton. A learner who clones and runs `python test.py` passes without writing any code. v1 fix (doc-only, no code rename): - `docs/HOW_TO_USE.md` — full active-vs-passive learning method (~200 lines, zh-TW) - 22 exercise READMEs — 🎓 callout pointing to `mv starter.py starter_reference.py` shortcut + link to HOW_TO_USE - Main README × 3 langs — surface the meta-instruction at the top-level Shipped in commits [`d598e37`](https://github.com/WenyuChiou/awesome-agentic-ai-zh/commit/d598e37) + [`2cf99fe`](https://github.com/WenyuChiou/awesome-agentic-ai-zh/commit/2cf99fe). ## ⚠ Known caveats still on `main` 1. **CrewAI exercise (Stage 4 ex2)** not tested on Python 3.14 — tiktoken + regex don't have wheels yet. Code shipped unchanged; users on Python 3.11/3.12/3.13 should be fine. Document at top of `examples/stage-4/02-multi-agent-roles/README.md` if needed for future learners. 2. **tool-calling-tutor skill** not live-tested in Claude Code — only structural validation (YAML frontmatter parse + JSON evals validate). Manual install test: `cp -r examples/stage-5/tool-calling-tutor/{SKILL.md,references,evals} ~/.claude/skills/tool-calling-tutor/`, restart Claude Code, prompt 「為什麼 LLM 不呼叫我的 tool」. 3. ~~**Walkthrough Python never executed**~~ — **RESOLVED 2026-08-10**. All 9 python blocks (304 lines) of `walkthroughs/build-first-agent-in-7-steps.md` were extracted to the filenames the doc names and executed in a clean venv on Python 3.14, with `Anthropic` and `requests` mocked (no API key, no spend): Stage 1-6 (6 blocks) plus all of Stage 7 (7.1 `eval_provider`, 7.2 `step7_observability`, 7.3 `main.py`). **Four** real defects were found and fixed in all three locales, plus two zh-Hans blocks that did not even parse (` ` expanded into real newlines, so Stage 1 and `reflect` raised `unterminated f-string literal` — a Simplified-Chinese reader's very first script crashed): Stage 6's vector memory stored nothing at all (empty-DB early return meant `store_paper` was never reached, compounded by a hardcoded `"..."` id that `collection.add()` silently ignores); `compare_with_memory`'s `comparison` was dropped because `State` never declared it; and `import step2_paper_summary` issued a billed API call at module level, which every later stage inherited. Post-fix, measured: memory count goes 1→2→3, `comparison` survives in state, and the four imported modules make 0 API calls; and Stage 6 now stores each paper's own summary rather than three byte-identical `[Reviewer verdict: PASS]` strings — the `compare` node read `messages[-1]`, which is `reflect`'s verdict, not the summary. Completed 2026-08-10: 7.2's import path was corrected (`observe` moved to the top-level package in langfuse **3.0**, not 4.x — verified by installing 2.60.10, 3.0.0 and 4.14.2; only 2.x has `langfuse.decorators`. `@observe(name=…)` itself is unchanged across all four, signature checked) and 7.3 was run with fastapi 0.141.1 — `TestClient` gets HTTP 200 and a `{'summary': …}` body from `POST /summarize`, and HTTP 422 on a missing field. **Still open**: end-to-end output quality against a live API key is untested — every run so far has mocked the model. 4. **starter.py = complete solution pedagogy gap** — flagged in `docs/HOW_TO_USE.md`. v2 would split into `starter_template.py` (TODO) + `starter_reference.py` (solution); v1 is doc-only meta-instruction. 5. ~~**Trilingual mirror of 🎓 callout incomplete**~~ — **RESOLVED 2026-08-02**. The 🎓 callout and the 📚 deeper-material block are now in the `.en.md` + `.zh-Hans.md` mirrors of **21 of the 22** exercise READMEs (202 blockquote lines). The 22nd, `examples/stage-1/04-cross-provider`, is **not a callout gap** — it is the only example folder with **no mirror files at all**, so it needs a full trilingual translation first, not a callout port. A blocking CI gate (`scripts/check-mirror-parity.py`) now stops this class of gap reappearing. 6. ~~**Pilot exercise drift**~~ — **RESOLVED 2026-08-02**. `examples/stage-3/03-react-from-scratch/README.en.md` + `.zh-Hans.md` were missing the entire free local Path A (Ollama) and ran the Ollama script under the Anthropic heading; both now match the dual-path canonical. ## 🔵 Stage 5 + Track A — current coverage ### Track A1-A3 CLI track — **outline complete, no `examples/` folder by design** 12 hands-on exercises documented across `tracks/cli/A{1,2,3}-*.md` × 3 langs (zh-TW canonical ~367 lines): | File | Lines (zh-TW) | Exercises | |---|---|---| | `tracks/cli/A1-cli-intro.md` | 107 | CLI-1 安裝 + 第一次跑 / CLI-2 CLAUDE.md / CLI-3 第二個 CLI 並用 / CLI-4 認證細節 | | `tracks/cli/A2-cli-workflow.md` | 126 | CLI-5 production CLAUDE.md / CLI-6 slash command / CLI-7 多步驟拆解 / CLI-8 portable prompt | | `tracks/cli/A3-cli-production.md` | 134 | CLI-9 MCP server 接 CLI / CLI-10 GitHub Actions / CLI-11 cost tracking / CLI-12 plugin 跨 team 分享 | **No `examples/track-a/` folder built — and this is intentional**. CLI exercises are: - Bash commands (`ollama pull`, `claude` install, MCP-server install) - Markdown authoring (CLAUDE.md, slash command `.md` files, SKILL.md) - YAML / JSON config (GitHub Actions `.yml`, `plugin.json`, `marketplace.json`) - **Not Python SDK code**, so the dual-path Ollama/Anthropic `starter.py` + `test.py` pattern doesn't apply. What learners do for Track A: follow each numbered exercise in the outline doc, on their own real repo (their work codebase, not a sample). The `tracks/cli/A*.md` files contain success criteria for self-check. **Core reference**: [`resources/cli-agents-guide.md`](../resources/cli-agents-guide.md) (148 lines) — 8-CLI comparison + decision rubric + common pitfalls. **Potential v2** (not committed): could ship `examples/track-a/` containing sample CLAUDE.md / `.claude/commands/review.md` / sample GHA workflow yml. Low priority — current outline is self-contained. ### Stage 5 — partial coverage Stage 5 (`stages/05-claude-code-ecosystem.md`) has 4 sub-stages with hands-on exercises: | Sub-stage | Status | |---|---| | 5.1 Claude Code 基礎 | Outline only (in `stages/05-...md` 動手練習) | | 5.2 MCP (Model Context Protocol) | Outline only; cookbook 2 covers building first MCP server | | 5.3 Skills | Outline + **1 shipped meta-example**: [`examples/stage-5/tool-calling-tutor/`](../examples/stage-5/tool-calling-tutor/) (full SKILL.md + 3 references + evals.json, used as the Stage 5.3 authoring exemplar) | | 5.4 Plugins & Marketplaces | Outline only | For v2, sub-stages 5.1 / 5.2 / 5.4 could ship sample artifacts (sample `CLAUDE.md`, MCP server skeleton, plugin.json). Similar to Track A v2 — low priority. ## v2 path (deferred) Per `docs/HOW_TO_USE.md` "給維護者：v2 path": - Split each `starter.py` → `starter_template.py` (TODO skeleton) + `starter_reference.py` (solution) - Make `test.py` behavioral (input → output contract) instead of implementation-bound - ~20 folders × 3 file changes = ~60 file changes - Probably needs its own session ## Historical: what was on the unverified branch Before verification, Stage 4 + 6 + 7 commits sat on branch `t3-stage-4-6-7-unverified` (rationale: framework deps not pip-installed at write time, API drift risk). After actual verification on 2026-05-13: ``` 50c3bf8 fix(examples): 6 bugs found while verifying Stage 4/6/7 tests 9f60759 Stage 7 練習 5 (FastAPI deploy) 1a8ba16 Stage 7 練習 4 (streaming + caching) 128ca7a Stage 7 練習 3 (observability) 8119de0 Stage 7 練習 2 (eval) 5ff3ce3 Stage 7 練習 1 (multi-agent debate) 8150881 Stage 6 練習 5 (long-term memory) 7633874 Stage 6 練習 4 (full RAG pipeline) 7a8af9b Stage 6 練習 3 (chunking comparison) b83a5e5 Stage 6 練習 2 (vector DB) 7d2c1b7 Stage 6 練習 1 (embeddings) ab6d358 Stage 4 練習 5 (Pydantic AI) 6316d83 Stage 4 練習 4 (Smolagents CodeAct) ea9c14a Stage 4 練習 3 (LangGraph branching) dbe7c91 Stage 4 練習 2 (CrewAI multi-agent) 8051861 Stage 4 練習 1 (LangGraph + CrewAI) ``` All merged into `main` via [`cdb0ae3`](https://github.com/WenyuChiou/awesome-agentic-ai-zh/commit/cdb0ae3). Branch deleted from origin after merge. --- ### Mkdocs.Yml site_name: awesome-agentic-ai-zh site_description: A trilingual learning roadmap for agentic AI (English / 繁中 / 简中) — 8 stages from LLM basics to multi-agent systems, with hands-on exercises and curated projects. site_url: https://wenyuchiou.github.io/awesome-agentic-ai-zh/ repo_url: https://github.com/WenyuChiou/awesome-agentic-ai-zh repo_name: WenyuChiou/awesome-agentic-ai-zh edit_uri: edit/main/ # Content lives at the REPO ROOT (stages/ tracks/ branches/ resources/ # + root *.md), not a docs/ subfolder. mkdocs forbids docs_dir being # the parent of mkdocs.yml, so `scripts/build-docs-tree.py` stages the # whitelisted content into _build/docs/ first (run it before `mkdocs # build` — the GitHub Actions workflow does this automatically). docs_dir: _build/docs site_dir: _build/site extra_css: - docs/stylesheets/extra.css exclude_docs: | *.py *.sh theme: name: material language: zh-TW features: - navigation.tabs - navigation.top - navigation.indexes - navigation.footer - navigation.instant - navigation.instant.progress - navigation.tracking - search.suggest - search.highlight - search.share - content.action.edit - content.code.copy - content.code.annotate - content.tabs.link - content.tooltips - toc.follow palette: - media: "(prefers-color-scheme: light)" scheme: default primary: indigo accent: indigo toggle: icon: material/weather-night name: 切換深色 / Dark mode - media: "(prefers-color-scheme: dark)" scheme: slate primary: indigo accent: indigo toggle: icon: material/weather-sunny name: 切換淺色 / Light mode plugins: - search - i18n: docs_structure: suffix fallback_to_default: true reconfigure_material: true reconfigure_search: true languages: - locale: zh-TW default: true name: 繁體中文 build: true - locale: en name: English build: true nav_translations: 首頁: Home 專案說明: Project overview 怎麼用: How to use 進度: Progress 結業專題: Capstone 路線圖: Roadmap 書本版: Book (mdBook) 共用基礎: Foundations Track A — CLI: Track A — CLI power user Track B — Agent: Track B — Agent builder 讀者分流: Audience branches 實作: Walkthroughs 資源: Resources 貢獻: Contributing - locale: zh-Hans name: 简体中文 build: true nav_translations: 首頁: 首页 專案說明: 项目说明 怎麼用: 怎么用 進度: 进度 結業專題: 结业专题 路線圖: 路线图 書本版: 书本版 共用基礎: 共用基础 Track A — CLI: Track A — CLI 高手 Track B — Agent: Track B — Agent 建构者 讀者分流: 读者分流 實作: 实作 資源: 资源 貢獻: 贡献 # Material ships no `zh-Hans.html` UI partial (it predates strict # BCP-47 — uses `zh` for Simplified). Map this locale's chrome to # Material's `zh`. Applied via apply_user_overrides (runs AFTER # the plugin's forced language=locale, so this wins). theme: language: zh markdown_extensions: - admonition - attr_list - md_in_html - tables # slugify: python-markdown's default strips non-ASCII, so every CJK heading # ("### Loop Engineering（迴圈工程）") rendered as id="loop-engineering" while # GitHub — and scripts/check-anchors.py, which validates against GitHub's # github-slugger rules — produce "loop-engineering迴圈工程". The two disagreed # on 151 distinct fragments: the gate stayed green while those jump-links were # dead on the published site. Emoji-prefixed ASCII headings diverged too, since # GitHub keeps the leading separator that python-markdown strips. # pymdownx's slugify(case="lower") reproduces check-anchors.py's output exactly # on every heading in this repo (4344 real headings), so the SITE and the GATE # now share one rule. GitHub is aligned too except for one documented case: # it preserves U+FE0F where both of these strip it, so a heading carrying a # variation selector has no fragment that works in both. That is guarded # separately — a linked-to heading may not contain one. # All of this is pinned by scripts/test_anchor_slug_parity.py; do not change # this block without running it. - toc: permalink: true slugify: !!python/object/apply:pymdownx.slugs.slugify kwds: case: lower - pymdownx.details - pymdownx.superfences - pymdownx.tasklist: custom_checkbox: true - pymdownx.emoji: emoji_index: !!python/name:material.extensions.emoji.twemoji emoji_generator: !!python/name:material.extensions.emoji.to_svg # Build-time hooks. mkdocs_hooks.on_page_markdown strips the README's # GitHub-only inline language switcher (its ./README.*.md links 404 # on the rendered site; Material's header selector is the in-site one). hooks: - scripts/mkdocs_hooks.py nav: - 首頁: index.md - 專案說明: about.md - 怎麼用: docs/HOW_TO_USE.md - 進度: PROGRESS.md - 結業專題: CAPSTONE.md - 路線圖: ROADMAP.md - 書本版: https://wenyuchiou.github.io/awesome-agentic-ai-zh/book/ - 共用基礎: - Stage 0 — Foundations: stages/00-foundations.md - Stage 1 — LLM Basics: stages/01-llm-basics.md - Stage 2 — Prompt Engineering: stages/02-prompt-engineering.md - Track A — CLI: - A1 — CLI Intro: tracks/cli/A1-cli-intro.md - A2 — CLI Workflow: tracks/cli/A2-cli-workflow.md - A3 — CLI Production: tracks/cli/A3-cli-production.md - Track B — Agent: - Stage 3 — Tool Use & Hello Agent: stages/03-tool-use-and-hello-agent.md - Stage 4 — Agent Frameworks: stages/04-agent-frameworks.md - Stage 5 — Claude Code Ecosystem: stages/05-claude-code-ecosystem.md - Stage 6 — Memory & RAG: stages/06-memory-rag.md - Stage 7 — Multi-Agent: stages/07-multi-agent-production.md - Stage 7.5 — Advanced Agentic: stages/07.5-advanced-agentic-concepts.md - Stage 8 — Agent Interfaces: stages/08-agent-interfaces.md - 讀者分流: - Branch design: branches/DESIGN.md - for-researcher: branches/for-researcher.md - for-developer: branches/for-developer.md - for-teacher: branches/for-teacher.md - for-knowledge-worker: branches/for-knowledge-worker.md - for-everyday-users: branches/for-everyday-users.md - 實作: - Build your first agent in 7 steps: walkthroughs/build-first-agent-in-7-steps.md - 資源: RESOURCES.md - 貢獻: - Contributing guide: CONTRIBUTING.md - Code of Conduct: CODE_OF_CONDUCT.md - Security policy: SECURITY.md - Contributors: CONTRIBUTORS.md - Changelog: CHANGELOG.md --- ### CONTRIBUTING # 貢獻指南 > **繁體中文** | [简体中文](./CONTRIBUTING.zh-Hans.md) | [English](./CONTRIBUTING.en.md) 謝謝你考慮貢獻。**這是一份精選的學習路線圖，不是百科目錄。品質 > 數量。** 這個 repo **本來就是設計給社群一起改良的**——一個人 curate 永遠跟不上 AI agent 生態的變化速度。Maintainer 一個季度跑 1 次 review 不夠，需要更多眼睛看。 這份 catalog 分**兩條軌道**：**Track A**（CLI Power User，`tracks/cli/A1-A3`）跟 **Track B**（Agent Builder，`stages/03-07`）。貢獻時請註明你動的是哪條軌道——兩條的 audience 不一樣。 ## 🚪 第一次貢獻：好上手的 5 個切入點 不確定從哪開始？挑一個你 30 分鐘內能做完的： 1. **🐛 回報過時 entry**：跑 `python scripts/refresh-stars.py` 找星數差距大的 repo，開 issue 說「這個應該移除 / 更新」 2. **🔗 修一個失效連結**：你看 stage X 時連結 404 了，直接 PR 改 3. **✍️ 補一個 entry 的 `怎麼跑` section**：很多 entry 沒寫安裝指令，你跑過就補上 4. **🌏 補英文 companion 沒翻好的句子**：找一個 `.en.md` 跟 zh 對照，你覺得翻得不順的地方改一行 5. **💬 對某個 entry 加個人筆記**：你跑過 `練習 3` 卡某個地方，補一句「注意：xxx」 這 5 種都不用先讀完整份 style-guide，merge 速度也快——適合第一次貢獻、累積信心。 > 🧪 **想跑 walkthrough / build script / CI workflow 第一次？** 看 [`.github/TESTING-STATUS.md`](.github/TESTING-STATUS.md)——這份**誠實揭露**哪些 code maintainer 真的跑過、哪些只 syntax check、哪些完全沒測。第一個踩到坑的人開 issue + PR 是 highest-value contribution。 ## 我們接受什麼 ### 高價值 PR - **新增 project** 到某個 stage，並說明為什麼這個 project 對應該階段的學習 - **翻譯** 某個 stage 頁面成繁中（只要繁中——我們不收 zh-Hans） - **標記停滯 / 失維護的 project**（請先開 issue） - **改善現有 project 的策展備註**（讓「教什麼」說明更清楚） - **重新整理** 某個 stage 內部順序，如果現在的順序不符合學習進程 ### 較低優先（仍然歡迎） - 錯字修正 - 連結修正（請先用 `curl -I` 驗證） - Stage 介紹文字優化 ### 不接受 - 沒有策展理由的批量加 repo - 沒有教學價值的自我推銷 - 沒文件的 project - 沒明確 license 的 project ## 怎麼新增一個 project 每一個 project 在 stage 頁面內應該照這個格式： ```markdown ### [Project Name](url) | 欄位 | 內容 | |---|---| | 語言 | Python / TS / etc. | | Stars | ★ k | | License | MIT / Apache 2 / ... | | 推薦度 | ⭐⭐⭐⭐ | **教什麼**：核心學習一句話總結。 **適合誰**：誰應該讀這個、為什麼。 **備註**：1-3 句的個人評價。哪裡好、哪裡弱、哪裡可以跳。 **怎麼跑**： \`\`\`bash # 最小安裝 / 第一次跑的指令 \`\`\` ``` ## 策展標準 值得列入的 project 必須： 1. **有維護**：最近 6 個月內有 commit，或明確標示「stable, no longer maintained」 2. **有 hello-world 文件**：讀者應該能在 30 分鐘內把東西跑起來 3. **明確 license**：MIT、Apache 2、BSD 或類似。避免沒 license 的 repo。 4. **可信賴的維護者**：知名組織、公司，或有口碑的個人 ## 雙語風格 - **繁中（Traditional Chinese, zh-TW）為正本**，英文版（`*.en.md`）是 companion。 - **不接受 zh-Hans PR**。如果你交 zh-Hans 的 PR，我們會請你轉成繁中。 - **自然翻譯**，不要逐字對譯。技術詞如果直接用英文比較自然，就保留英文（「使用 LangGraph 建 multi-agent 系統」）。 - **完整風格規範請看 [`resources/style-guide.md`](resources/style-guide.md)**——禁用詞、entry schema、license 標註慣例、寫作風格、推薦星等定義都在裡面。PR 之前請先讀。 ## 流程 1. 新 project 或大幅重組請先開 issue 2. 一次一個 stage，PR 範圍要聚焦 3. 等審查（通常 7 天） 4. Reviewer 可能會問你「為什麼這個 project 教這個 stage」 ## 要避免的反模式 - ❌ 「leverage」、「delve」、「comprehensive」、「robust」（LLM tell） - ❌ 過度行銷（「revolutionary」、「game-changing」） - ❌ 只因為熱門就列上來 - ❌ 大段引用 project 自己的行銷文案 ## 擔任 Stage / Branch 維護者 除了交一次性 PR，也歡迎擔任**特定 stage 或 branch 的長期維護者**——負責定期 review、處理該領域的 issue、把關該領域的 PR。 自薦流程： 1. 開一個 issue，標題 `[maintainer] Stage N — your-handle` 或 `[maintainer] for-X branch — your-handle` 2. 講清楚你願意 commit 多久（建議至少一季 = 3 個月） 3. 簡述你在這個領域的背景 詳見 [`CONTRIBUTORS.md`](CONTRIBUTORS.md)。每個 stage / branch 的 maintainer 名單都在那邊。 ## License 貢獻即代表你同意你的內容以 MIT 授權。 --- ### CHANGELOG # Changelog Last 14 days of substantive changes. Older history lives in `git log`. Format: `YYYY-MM-DD · category · 1-line summary (commit-sha)`. --- ## 2026-08-14(第七批) - **fix** · **zh-Hans 裡最後一個「投影片」改成「幻灯片」**。`stages/03-tool-use-and-hello-agent.zh-Hans.md` 第 67 行是整棵 zh-Hans 樹上僅剩的一個,其他 5 處早就寫「幻灯片」了——其中 `stages/01-llm-basics.zh-Hans.md` 第 152 行是**同一門李宏毅課程的同一句介紹**,只差一個 stage。同一份鏡像對同一個東西有兩種叫法,那是殘留,不是用字選擇。**沒有任何 gate 抓得到這種東西**:`check-hans-chars` 是字元級的,而投、影、片三個字在簡體裡都是合法字,所以它永遠會是綠的;要看見這個,只能靠詞彙層的規則或人眼。(下面那條講 `GUARDED_VOCAB` 的說「第 67 行原封不動」,問的是另一件事——守衛防的是把「投影片」改成「投视频」,那個保護仍然需要。) - **fix** · **有 5 處台灣用語躺在 zh-Hans 檔裡，而 blocking gate 是「故意」抓不到的**。`zh-hans-localize.py --check` 一直回報 clean,但 lint 裡那個 warn-only 的殘留檢查看得到。原因寫在 [`scripts/zh-hans-localize.py`](scripts/zh-hans-localize.py) 的註解裡:`影片→视频` 被整條排除,因為「影片」是「**投影片**」的子字串,而 `VOCAB` 是純 `str.replace`,一改就會把投影片變成「投视频」。**那個註解對碰撞的判斷是正確的,對解法的判斷是錯的**——排除掉整條規則,等於讓 5 處真的殘留永遠留在樹上,而且 blocking gate 還會說沒事。 - **fix** · **修法不是排除,是加守衛**。新增 `GUARDED_VOCAB`:該改的改、投影片不動。(第一版用 negative lookbehind `(? ```bash`),其他六份都不認——而 `check-anchors` 因此會去驗一個在網站上其實是純文字的連結。所以共用版補上了 blockquote 支援(記住開頭 fence 的引用層數,只在同層收尾)。拿全 repo **234 個版控內檔案**對**真正的 renderer** 比對標題數:零筆不一致。(刻意寫 234 不是 235——235 正是下面那條在修的 bug 產生的數字,把一個未追蹤的本地檔也算了進去。) - **fix** · **`collect_anchors()` 之前是在原始內容上跑的**——#95 只修了連結那一側,**目標那一側從來沒有排除程式碼**。所以一個只出現在程式碼範例裡的 `## 標題` 會被當成合法的錨點目標。全 repo **642 個**這種幽靈目標,現在不再被接受;沒有任何實際連結指到它們,所以修完 `--strict` 照樣全綠。 - **fix** · **`_md_files()` 會把未追蹤的本地檔算進 gate 的輸入**,所以同一個 gate 在本機跟 CI 看到的檔案集不一樣——一個放在 repo 根目錄的暫存檔就足以讓標題總數對不上,目錄過濾也擋不掉。改成走 `git ls-files`,拿不到 git 時退回原本的 rglob(退化成比較寬,不會靜靜變成空集合)。 - **test** · 新增 `test_no_script_reimplements_the_fence_rule`:**正面斷言七支 gate 都必須 `from md_fences import`**——黑名單擋得掉的形狀永遠有限(實測舊版黑名單只抓到七支裡的五支,漏掉 `check-mirror-parity` 的 `open_marker` 狀態機與 `check-anchors` 自己 #95 前那種寫法),而「沒有 import」是繞不過去的。黑名單保留當後備,掃原始碼裡的翻轉式判斷與 DOTALL ` ```…``` ` regex。這是照 `test_repo_scan_excludes.py` 擋「exclude-path」那個 bug 的同一種做法——那個 bug 復發了八次,**原始碼層級的守門才是讓一個修好的類別不再被下一個人重新引入的東西**。變異驗證過:把 toggler 塞回任一支就會紅。 - **chore** · **這次 refactor 真的有代價,而且是我原本說錯的那個代價**。上一批我說「不共用是因為每支 gate 都彼此不 import」——那是錯的。真正的代價在別的地方:`test_mirror_parity` 與 `test_image_locale` 會把待測腳本複製到暫存目錄跑,而腳本現在多了一個相依,所以那四個 harness 全部 ImportError、31 條測試裡有 19 條為了錯誤的理由失敗。修法是 harness 一起複製 `md_fences.py`。**gate 本身全綠、只有單元測試紅**——如果我當時只看 gate 就以為沒事,這個問題會一路帶進 CI。 - **fix** · **有一頁的四個標題在網站上是以「程式碼」的樣子呈現的,三個語系都一樣([#95](https://github.com/WenyuChiou/awesome-agentic-ai-zh/issues/95))**。`examples/stage-4/04-codeact-vs-json-tool` 想示範「LLM 回一段 Python」,所以在一個 code block 裡面又放了一個 ` ```python `。但 **CommonMark 規定收尾的 fence 不可以帶語言標籤**,所以那個 ` ```python ` 不會收尾、只是內容;真正收尾的是下一個裸 fence,而再下一個裸 fence 反而**又開了一個新的 block**——把後面〈CodeAct vs JSON tool 對照〉〈兩個 path 觀察重點〉〈常見坑〉〈想看更聰明的答案?〉整段吞進去。修法是把外層 fence 加長成四個反引號:**CommonMark 允許 block 內含較短的 fence**,這正是這種「示範用巢狀 fence」該有的寫法。三語都修,12 個標題全部回來。 - **fix** · **`check-anchors.py` 的 `strip_code_blocks` 以前是「看到 ``` 就翻轉狀態」**,那既不是 CommonMark、也就跟真正在發布網站的 renderer 不一致。**gate 跟 renderer 對「哪幾行是程式碼」的認知不同,gate 就是在驗一份沒人發布的文件**。已改成照 CommonMark 判斷:記住開頭 fence 的字元與長度,收尾必須同字元、不短於開頭、而且不能帶語言標籤;另外支援 `~~~`、允許最多三格縮排、拒絕把 ` ```foo`bar ` 當成 fence(兩個 renderer 都不當)、以及**未收尾的 fence 會發警告**——那種情況 gate 會靜靜跳過檔案剩下的部分,然後照樣印「All internal anchors valid」。改完 repo 全域找到的 anchor link **零筆差異(689 → 689)**,因為 fence 已經先修好了,所以這次純粹是防未來。 - **chore** · **但要講清楚:這只修了六個之中的一個,不是「根因修好了」**。`scripts/` 底下還有五支各自寫了同一套「看到 fence 就翻轉」的邏輯——`check-hans-chars`、`check-image-locale`、`check-links`、`check-locale-links`(兩處)、`zh-hans-localize`(它只處理 `.zh-Hans.md`,涵蓋範圍與其他幾支不同),`check-mirror-parity` 則是認得 marker 但仍然忽略長度與語言標籤規則。實測那幾支用 `^\s*` 形式的今天把**同樣 3 個檔案的 12 行**判成散文而非程式碼,那 12 行沒有任何 URL、anchor 或標題,所以現在沒壞。**但這一批同時在推薦巢狀 fence 這種寫法**,等於替它們埋了地雷——而且這不是假設:實測在 `.zh-Hans.md` 裡放一個含 `# 這是繁體註解` 的巢狀 ` ```python `,`check-hans-chars` 就會把那段程式碼當散文掃、回報繁體殘留、擋下合法內容。已開 [#97](https://github.com/WenyuChiou/awesome-agentic-ai-zh/issues/97) 追,沒有在這一批一起改,理由是**六支 CI gate 的重構值得自己一輪 review**——順帶更正我原本寫的理由:我以為「每支 gate 都彼此不 import」是這個 repo 的現有性質,那是錯的,`check-locale-links.py:62` 早就用 importlib 載入 `check-anchors.py` 來共用 slugify,而且它上面那段註解講的正是「第二份拷貝一定會飄」——跟 #97 要做的事情同一個論證。我當初的 grep 看得到 `import importlib.util` 那一行,但看不出它載入的是**同目錄的另一支 gate**——我只掃了 import 陳述句、沒有去看它載入什麼。 - **test** · 新增 `scripts/test_check_anchors.py`(14 條)。關鍵是**它必須抓得到退版**:把解析器換回舊的翻轉式寫法,14 條裡有 **8 條**失敗,包含直接編碼 #95 原始形狀的那條。**而同一時間 `check-anchors.py --strict` 還是回報綠燈**——這正是重點:gate 自己看不見這個缺陷,只有這些單元測試看得見。已掛進 lint job(純 stdlib)。 - **test** · **review 在這批測試裡挑出三個洞,每個都是「綠燈但沒在測」**:①有一條只斷言「後面的標題看得到」,而拿掉長度規則之後它照樣通過——因為 fence 只是重新配對、尾巴仍然落在外面;現在改成斷言**否定面**(區塊內的標題必須看不到)。②唯一擋得住那個變異的,竟然是那條「檔案不存在就 `return`」的端到端測試——**一次改名就會無聲刪掉那條規則的唯一覆蓋**;現在改成硬性斷言檔案存在、而且三個語系四個標題全查。③`rest.strip()` 改成 `rest == ''`(收尾 fence 後面多一個空格就不算收尾)整條測試套件毫無反應;現在補上了。後來又補了兩條:未收尾 fence 的警告本身沒被測(刪掉它,**當時那 12 條**照樣全過——現在補上之後刪掉就會紅),以及那條「反引號 info string」規則不可以外溢到 `~~~`。 - **chore** · 順手刪掉 `CODE_FENCE_RE`。它從來沒被任何地方引用過,而且它編碼的正是 #95 證明錯誤的那條規則(任何 ``` 都能開能關)。留著只會誤導下一個人。 - **chore** · **上一批說的「4344 個真實標題」在這個 commit 仍然是 4344,但「沒有變」是巧合,不是穩定**。舊解析器把那 12 個被吞掉的標題**算進去了**(它以為那些行不在 code block 裡),renderer 卻沒有渲染出來——一邊多算、一邊少渲。實測矩陣(只算版控內檔案):**HEAD 是 raw 5069 / naive 4343 / CommonMark 4331,這個 commit 是 5070 / 4344 / 4344**;修 fence 讓 CommonMark 那側 +12,而這則 CHANGELOG 自己的 `##` 標題讓兩側各 +1,加起來剛好回到同一個數字。單看那三個檔案:修 fence 前 naive=12 / CommonMark=8,修完兩邊都是 12。**另外上一批那個 4344 是在一份含未追蹤本地檔的掃描下量到的**——`scripts/test_anchor_slug_parity.py` 的 `_md_files()` 用 `rglob` 走工作區、只過濾目錄,所以未追蹤檔會混進 gate 的輸入,本機跟 CI 會不一樣。根因併入 [#97](https://github.com/WenyuChiou/awesome-agentic-ai-zh/issues/97)。 - **chore** · **順便記一個這一批沒有動、但同一類的問題**:`collect_anchors()` 是在**原始內容**上跑的,`strip_code_blocks` 在正式流程裡只被 `parse_anchor_links` 呼叫一次——也就是說 fence 規則只管**連結那一側**,**anchor 目標那一側從來沒有排除程式碼**。實測 gate 因此接受了 **642 個只存在於 code block 裡的 anchor slug** 當作合法目標。目前沒有任何實際連結指到那些,所以是潛在而非已壞,而且早在這批之前就存在。一併寫進 #97。 ## 2026-08-14 - **fix** · **網站上有 151 個錨點連結是死的,而 gate 一直是綠的([#93](https://github.com/WenyuChiou/awesome-agentic-ai-zh/issues/93))**。`scripts/check-anchors.py` 是照 GitHub 的 github-slugger 規則驗的——這對「在 github.com 上讀這個 repo」的人完全正確。但發布出去的 MkDocs 網站用的是 python-markdown 的預設 slugify,**它會把非 ASCII 整段丟掉**:`### Loop Engineering（迴圈工程）` 在 GitHub 上是 `#loop-engineering迴圈工程`,在網站上卻是 `#loop-engineering`。兩邊算法不同,誰都沒錯,但**沒有任何東西在檢查第二個**。 - **fix** · **修法是一行設定,不是改 151 個連結**。`mkdocs.yml` 的 `toc` 改用 `pymdownx.slugs.slugify(case="lower")`。先量過才敢改:拿 repo 裡**每一個標題**(4344 個;`HEADER_RE` 在原始文字上會匹配到 5070 筆,其中 726 筆是 ``` 區塊裡的 `#` 註解,不是標題)逐一比對,這個 slugify 與 `check-anchors.py` 的輸出**零筆不一致**。建置時的 anchor 診斷從 **349 筆降到 0**。 - **fix** · **改完剩下 16 個,那是第二個 gate 看不見的洞**。`check-anchors.py` 比對前會把**連結那一側也 slugify 一次**(`anchor_slug = slugify(anchor)`),所以 `#📋-playbook-4…` 這種夾帶 emoji 的連結,正規化之後對得上、gate 就放行——但瀏覽器不做正規化,它是拿 `id` 逐字比對的。16 個連結對 gate 有效、在瀏覽器裡是死的,已全部改成**字面正確**的形式(三個是大小寫不符)。 - **fix** · **還有第三個洞,而且是 review 逼出來的:`U+FE0F` 變異選擇子上,GitHub 跟另外兩邊不一樣**。`check-anchors.py` 與 pymdownx 都會把它丟掉,GitHub 不會——實際抓 github.com 渲染後的 HTML 確認過,`## 🗺️ 學習地圖(兩條學習路徑)` 的 id 是 `user-content-️-學習地圖兩條學習路徑`,**第一個 codepoint 就是 `0xFE0F`**;而沒有變異選擇子的 emoji(例如 `📋`)GitHub 確實會整個拿掉、只留前導連字號。**所以帶變異選擇子的標題根本沒有任何一種 fragment 能同時在兩邊成立**。我原本把那些連結改成無 `FE0F` 的形式,等於修好網站、卻讓 **12 條連結在 GitHub 上死掉**,方向修反了。正解是改**標題**不是改連結:六個被連結到的標題(三份 README 的〈學習地圖〉、`stages/05` 的〈7-Layer Architecture Map〉三語)拿掉變異選擇子,三邊就一致了。 - **fix** · **查這件事的時候才發現,那六個標題底下其實有 24 條連結,而且原本剛好一半一半壞掉**。12 條用帶 `FE0F` 的寫法(在 GitHub 好、在網站死),另外 **12 條早就是無 `FE0F` 的寫法、在 GitHub 上一直是死的**——而且分佈在鏡像檔裡。也就是說 **同一句話的三個語系用了相反的錨點慣例**:`stages/06-memory-rag.md:98` 是帶 `FE0F` 的,它自己的 `.en.md:98` 與 `.zh-Hans.md:98` 卻是無 `FE0F` 的;`stages/07`、`stages/07.5`、`stages/08`、`tracks/cli/A3-cli-production` 同樣有這種分裂,共**五處**。鏡像本來就該是等價的,這種分裂**沒有任何 gate 看得到**。(我第一次數成四處,是因為那支檢查腳本用「檔名 + 行號」分組——但鏡像的行號不會對齊:`stages/07.5` 的繁中版在第 637 行、兩個鏡像在第 635 行,於是被分到不同組、看起來沒有衝突。改成只用檔名分組才對。總數 24 / 12 / 12 不受影響,錯的只有列舉。)改標題一次把 24 條全部修好——這也是「改標題比改連結對」最強的理由。repo 裡另外 53 個帶組合字元的標題**不能一併處理**——`⚠` 的 `Emoji_Presentation` 是 No,拿掉選擇子預設就會變成單色文字字形,而且沒有任何連結指向它們。(同樣的性質也適用在 `🗺` 上,是個已知的取捨:錨點壞掉是實際量得到的,呈現差異則是看字型、屬於外觀問題。細節寫在測試的 docstring 裡。) - **test** · 新增 `scripts/test_anchor_slug_parity.py`,把三個洞都釘住:①網站設定的 slugify 必須與 `check-anchors.py` 對每一個標題輸出相同;②任何內部 fragment 都不准「正規化之後才成立」;③**被連結到的標題不准含組合字元(Unicode Mn/Me)**。第③條原本只擋 `U+FE0F`,review 指出那是**擋一個字、漏一整類**:`1️⃣` 是 `U+0031 U+FE0F U+20E3`,只拿掉變異選擇子會剩下 `1⃣`,`U+20E3` 還在、在 GitHub 上照樣是死的——而 gate 會變綠。也就是說那條規則會**指引人走到「綠燈但仍然壞掉」**,跟 #93 本身同一個形狀。已改成整個 Mn/Me 類,並實際抓 github.com 驗證過 `resources/setup-guide.md` 的 id 是 `user-content-1️⃣-網頁版最簡單免費可試零-setup`,`U+FE0F` 與 `U+20E3` **兩個都留著**。那份檔案有 5 個這種數字標題(三個語系合計 15 個),正好是最可能被人深連結的「步驟一、步驟二」。三條都做過變異測試,各自只被對應的那個缺陷觸發、不互相誤報。第③條寫完當場就抓到 `stages/05` 那三個我跟 review 都沒列進去的——它們在網站上是好的、gate 也是綠的,在 GitHub 上是死的。CI 以獨立 job 執行(需要真正的 mkdocs config loader);`docs.yml` 只在 push 到 main 才動,當 gate 太晚了。 - **fix** · 那個 CI job 第一版**在乾淨 checkout 上跑不起來**:`mkdocs.yml` 的 `docs_dir` 指向被 gitignore 的 `_build/docs`,而 `load_config` 會驗證這個目錄存在。我本機會過只是因為之前建置留下了那個資料夾。已補上 `build-docs-tree.py` 步驟;測試的 `main()` 也改成**非 assert 的例外一律計為失敗並印出來**——原本那種情況只會安靜印一行綠色 `ok`,看起來像通過。 - **content** · 上一批 glossary 的兩條交叉引用當時**刻意不用 `#fragment`**,因為那時沒有任何一種寫法能同時在 GitHub 與網站上成立。這個限制已經消失,兩條改回正常的錨點連結。 - **chore** · **「三邊同一套規則」這句話要加兩個但書,不然就是誇大**。①**重複標題**:同一頁出現兩個同名標題時,網站會編成 `_1`/`_2`,GitHub 編成 `-1`/`-2`,而 `check-anchors.py` 用 `set()` 收集、根本沒有重複的概念。全 repo 有 15 頁、122 個這種 id(`stages/05` 的〈學習目標〉、`resources/cookbook.*` 的〈為什麼〉等)。**目前沒有任何連結指到第二個以後的同名標題**,所以實際影響是零,但那句話在這個情況下不成立。②**mdBook**:`/book/` 是這個 repo 發布的第四個渲染面,用的是它自己的 `normalize_id`,既不是 github-slugger 也不是 pymdownx,而且 `check-anchors.py` 一直把 `book/` 排除在外。這一批沒有讓它變差,但它從來就沒對齊過。兩件都另外開 issue 追。 ## 2026-08-13 - **fix** · **維護者回報五層階梯「排序看起來有問題」,查下去發現是兩個不同的毛病**。第一個:表格的「對應 stage」欄由上往下是 `2 → 6 → 7 → 5.6 → 4`——**前三列遞增、後兩列突然倒退**,看起來像階梯排錯(圖上更明顯:堆疊最上層的 Graph 標的是 Stage 4)。實際上那欄是「這個主題在哪一章講」,不是閱讀順序。欄名改成 **「在哪一章講」**,並加一句「**不是閱讀順序**,照 Stage 0 → 8 讀就好」。 - **fix** · **第二個才是根因:`loop` 這個詞在同一章有兩個意思**。harness 自己的八個核心元件,第一個就叫 `Agent loop`(「LLM → tool → result → LLM」的機械迴圈);而第 4 層又叫 Loop Engineering。**同一個字,一個在 harness 裡面、一個在 harness 上面**,讀起來當然卡。stage 07 四處消歧義:第 4 層加副標 **(長時間執行)**、八元件那格加 **(單次執行內)** 並註明兩者層次不同、圖下補一句指路、白話差異那條點明「不是 harness 裡那個單次執行的機械迴圈」。 - **fix** · **同一個字在 glossary 也撞,而且讀者卡住時第一個去查的是 glossary,不是 stage 07**。`Agent Loop` 與 `Loop Engineering` 兩條各自獨立,誰都沒提對方。兩條互相加上一句交叉引用(三語共六處)。這是同一個缺陷的另一個表面,不補等於只修了一半。 - **content** · **沒有把 Loop 層拿掉**。維護者原本的直覺是收成四層(prompt → context → harness → graph),那也站得住。但這份階梯是**用「撞到什麼牆」串起來的**,而第 3 層 harness 撞的牆寫的是「一次跑不完一件大事」。收成四層之後,回答這道牆的就變成 Graph——可是 Graph 自己的目的欄寫的是「看得到、管得住、能重來」,那是**看得見**的問題,不是**跑得久**的問題。鏈子會斷在一個承重的接點上。所以判斷是**命名衝突而非層序排錯**,修命名不動層序。 - **diagram** · **五層圖同步改版:拿掉每層左邊那顆 `Stage N` 徽章**,只留名稱來源徽章。理由是表格有空間放「不是閱讀順序」這句但書,**圖沒有**——所以圖負責概念與名稱來源,「去哪裡讀」交給表格。第 4 層的層名也加上副標。 - **fix** · **這張圖改了三輪才對,而且第一輪的缺陷三語不一樣嚴重**。v3 把副標放成**第三行**,但卡片高度沒變:**英文版只是擠、還讀得出來,繁中與简中是真的重疊**——「（長時間執行）」壓到上面 `Loop Engineering` 的字母下緣、又跟下面「撞牆」黏在一起。**CJK 字高比拉丁字母高,同一套三行排版在英文只是擁擠、在中文就是撞在一起**;只看英文版會誤判成可以接受。v4 改成副標與層名**同一行**,每張卡維持兩行。(v3 的 PNG 沒留存,但生成腳本留在委派紀錄裡:副標確實是獨立一行畫的,delegate 自己當下也記了「the new Loop subtitle is colliding with the wall line」。**只有三語嚴重程度的差異**是純文字記錄,無法事後以像素稽核。) - **fix** · **v3 同時把兩個中文版的主標副標改壞了,而且沒人發現,一路抄到 v4**。已發布版本是「一層撞牆,才生出下一層」/「一层撞墙,才生出下一层」;v3 的生成腳本裡寫的卻是 `一層撞牆才生出下一層`(逗號沒了)與 `一层撞墙才出下一层`(**逗號沒了,「生」也沒了**)。v4 因為 brief 要求「照現行檔案逐字照抄」,把這兩個錯字原封不動又抄了一輪。**我每一輪都只放大檢查我要求改的那一列,主標那行從頭到尾沒被看過**——改動範圍是一列,重繪範圍是整張,這就是代價。v5 兩處調整才收斂:brief 裡**把三語副標原文逐字寫進去**(不再說「照現行檔案抄」),驗收條件改成**整張圖每一塊文字都裁切放大檢查**。抓到這個字的是 review,不是我。 - **fix** · **v5 沒有重新生成,而是在舊圖上「清掉一塊再重畫」,清除範圍比標題底色帶多了 7 px**,在三張圖上都留下一條 921×7 px、比背景亮一階的橫向色階(ΔRGB 只有 `(7,9,17)`,1:1 檢視完全看不出來)。**這是純文字的驗收清單結構上抓不到的缺陷**——我用肉眼看了三張全圖都沒發現,是 review 逐像素掃出來的。已把那 7 列補回背景色並驗證色帶底緣三張一致。 - **chore** · 我第一次描述 v3 缺陷時說「三語都重疊」,放大之後才發現**英文版其實沒有重疊**,只是擠。已在委派 brief 裡改成精確描述——拿不準的問題去要求重做,只會換回一個沒對準的修法。 - **chore** · **這一輪真正的教訓不是「驗收要更仔細」**。這張圖沒有進版控的生成腳本,所以每一輪 delegate 都得從頭重寫一份繪圖程式——「逐字照抄」會失敗兩次,根因在這裡。把腳本連同文字一起進版控,「文字有沒有飄」就從裁圖瞇眼變成看 diff。列為下一輪待辦。 ## 2026-08-12(第二批) - **diagram** · **新增第二張圖〈一張「圖」裡面有什麼〉(三語、1920×1080)**,接在 `stages/07`〈迴圈跟圖差在哪〉的核心引言正下方。五層那張回答「有哪五層」,這張回答**下一個問題**:圖到底長什麼樣。刻意畫成**由左到右的流程圖**、跟五層那張的堆疊構圖區隔開。圖上把**迴圈做不到的三件事**畫出來:兩格同時跑、不通過退回、以及**每個 agent 格右上角一個 ⟳ 標「格子裡面它自己繞圈」**——讓「迴圈活在格子裡」變成看得見的東西,而不是只有一句話。四種格子四色四 icon:**agent / 工具 / 驗證 / 人**。 - **fix** · **這張圖第一版有兩個版面缺陷,而且只有開圖才看得到**。① 「兩格可以同時跑」被放在退回箭頭旁邊,讀起來像在標那條箭頭——**英文版更嚴重,橘色退回線直接穿過那行字**(`these two run at the sa|me time`);② 「不通過就退回」壓在圖例膠囊的上框線上。尺寸、aspect、檔案時間戳全部正常,`.result.json` 也回報 success。修法照 `locale-variant-prompts.md` 的教訓——**指定重新生成、附完整規格,而不是叫它「只修這兩點」**(上批四次嘗試裡,叫它改圖有兩次擅自重新設計節點還引入新缺陷)。v2 三語都乾淨。 - **content** · **收錄 `AMAP-ML/LongHorizon-Harness`(issue #89),Multi-Agent Orchestration 第 5 列**,三語。收它的理由不是「又一個 framework」,而是**它剛好是上面那張圖的實作**:Manager / Executor / **Auditor** 三個角色,Executor 每輪用新 context、Auditor 獨立檢查後才寫進持久 state——就是圖上「檢查對不對」那一格。第一手查證:★ 587、MIT、未封存、當天有 push、5 個 release,`lh-harness` 在 PyPI 上是 v0.1.4,README 確實有 Manager / Executor / Auditor。 - **content** · **給 ⭐⭐⭐ 而不是投稿者建議的 ⭐⭐⭐⭐,而且把「很新」寫進條目**。同分類的 `open-multi-agent` 是 4.5 個月、52 位 contributor、20 個 release,而這個是 **2026-08-04 建立(8 天)、2 位 contributor**——兩個給同一級會讓這欄失去鑑別力。條目裡直接寫「**很新**:2026-08-04 建立、2 位 contributor,還沒有長期維護紀錄」,不藏。另外 repo description 宣稱有 OpenClaw 整合,但**README 裡找不到**,所以只寫 README 支持得了的部分。表格 28 → 29,三語同步(這個數字一樣沒有 gate 在管)。 - **chore** · **刪掉 `prompt-context-harness-stack.{png,en.png,zh-Hans.png}`**。它畫的是三層,已被五層那張取代;刪之前確認已發佈內容零引用(只剩 CHANGELOG 歷史紀錄提到),git history 留得住。 - **chore** · 順帶跑例行星數更新:**24 處 drift、12 個檔**,修完重跑 277 個 repo 全部收斂。 ## 2026-08-12 - **content** · **分層模型從三層改成五層,而且改的重點不是數字**。以前六個地方各自重述一次這個模型,結果講出**三種版本**:`stages/02` ×2 說「三層」、`stages/06` 掛一張三層的圖、`stages/07` 標題說三層但下面註解又補「Loop 是第四層」、glossary 的 Loop 條目自稱第四層、Graph 條目存在卻沒接進階梯、`stages/07.5` 還特別警告「這跟 Stage 7 的三層不一樣」。**只把 3 改成 5 半年後會再漂一次**,所以改成 **1 個 canonical + 5 個指標**:`stages/07` 是唯一出處,其他五處只指回去、不重述。 - **content** · **敘事改成目的先行**。原本是「層級 / 概念 / 關注單位」的名詞表,現在每一層寫「**目的(要解決什麼)**」加「**撞到什麼牆 → 所以有下一層**」——五層不是並列清單,是一層撞牆才生出下一層。白話用詞照 `stages/07:39` 既有的標準(「Prompt = 設計一個好的問法,讓模型這次回答準」),不用術語堆。 - **content** · **新增〈迴圈跟圖差在哪〉整節**,三語。這兩個最容易混,而且網路上多數講法停在「迴圈一條路、圖可以多條」,那個講法**沒抓到重點**:迴圈也有步驟,只是那些步驟沒名字、指不到、測不了。真正的差別是**流程有沒有事先畫出來**。用的比喻:迴圈像洗碗(拿起來、洗、不乾淨再洗),圖像餐廳出菜(切、炒、擺盤,順序先寫好,兩個爐可同時開)。核心那句取自 Prefect 的講法:**格子裡面是 agent 自己繞圈,格子跟格子之間才是你安排的順序**——所以圖是把好幾個迴圈裝進格子再排順序,不是拿來取代迴圈的。**代價也寫進去**:圖逼你事先想清楚拆成哪幾格,任務如果就是「一直試到成功」、也沒人回頭查,先畫圖只是多做工。 - **content** · **補上一件多數中文講法漏掉的事**:格子裡放的不一定是 agent,**也可以是一個工具、一段檢查、或「這裡要人按核准才能往下」**。人也是圖上的一格。 - **fix** · **名稱來源獨立成一欄,而且照實標**。前三層(Prompt / Context / Harness)廠商文件自己在用;**後兩層沒有**——Loop / Graph Engineering 是社群名字,Anthropic 官方叫 *dynamic workflows*、Google ADK 與 Microsoft Agent Framework 叫 *graph-based workflow(s)*。查過:七篇談 graph engineering 的全是二手部落格,**零第一方來源**用這個詞當學科名;連 Anthropic 最新那篇 harness 長文都沒用 "harness engineering" 這個說法。表格旁邊直接寫「你去查官方文件查不到這個詞,不是你漏看」。 - **diagram** · **新圖 `agent-engineering-5layer.{png,en.png,zh-Hans.png}`(1920×1080,三語)**,取代只有三層的 `prompt-context-harness-stack.*`。委派 Codex 生成、沿用 repo 既有的深底霓虹 house style;**前三層實線、後兩層虛線**,讓「官方採用 / 非官方名稱」不是只靠文字。文案是委派者逐字寫好放進 brief 的,Codex 只負責算圖。 - **fix** · **改標題就會斷連結,這次自己踩到**。`stages/02` 的 `##` 標題從「prompt → context → harness 三層 engineering」改掉之後,`stages/06:51` 指向那個 anchor 的連結就死了。改成指向 Stage 7 的新 anchor;`check-anchors --strict` 綠。 - **fix** · **「六個地方」這個清單本身是錯的,實際是十一個——而且是 review 用全 repo grep 抓出來的,不是我列的**。我那份清單是**憑印象回想「已知會出問題的地方」**列的,不是搜出來的,所以漏掉:**`README` 三語**(全 repo 最多人看的檔,寫著「3 個術語對應 3 個 phase、**不必另外找資源**」——明白宣稱完整)、**`stages/02` 的正文三語**、`stages/05` 兩處三語、`stages/06` 的小標題三語、glossary 的指標文字三語。 - **fix** · **`stages/02` 那個是我自己弄糟的,值得單獨記**。我只把 `##` 標題裡的「三層」拿掉,**底下整段三層說明加一張三列表格原封不動**,而且那張表上面寫著「**完整**三層 lineage」。後果有兩層:① Stage 2 排在 Stage 7 **之前**,讀者先讀到它,會建立「總共就三層」的心智模型;② 標題不再有「三層」兩個字,**等於讓下一次 grep 再也找不到它**——我把問題藏得更深了。修法不是硬塞五層表格(Stage 2 的讀者不需要),是**拿掉「完整」這個宣稱**、改成「這裡先看跟寫 prompt 相鄰的三層,完整五層見 Stage 7」。 - **fix** · **修的時候又犯了同一個錯的鏡像版**:README 我改好了正文那句、**忘了改標題**「🔭 三層概念進化」。自己重掃才抓到。標題與正文要一起看,這一批裡兩個方向的漏都發生過。 - **chore** · **這次收尾改成「全 repo grep + 逐一 triage」而不是「跑 gate」**。12 個 gate 全綠但**一個都抓不到這類殘留**——它們檢查結構,看不出「這段話的內容已經過時」。triage 後確認留下的都是 false positive,刻意不動:`stages/08` 的三層 interface(computer / browser / sandbox)、`07.5` 解釋 stack 用的 frontend→backend→database、`07.5` 的痛點→原則→實作、`stages/05` 的「階梯式三層」(CLI / 調車 / SDK)、`resources/README` 的「三層深度」。委派 brief 裡也明列這些**不准動**。 - **fix** · **委派回來之後抓到自己的漏改**。`stages/07` 第 9 行的「本章組成」還寫著「三層工程分工」,而且**三語都是**——因為 Codex 忠實鏡像了我沒改到的 canonical。同一支檔案第 123 行的 harness 定位段也還說「通常會碰到三層工程問題」;那一段講的是 harness 跟前後兩層的關係,**不是漏改而是範圍不同**,所以改成「五層裡的前三層(完整階梯見上面)」而不是硬改成五,保留它原本要講的正交性論證。 - **content** · **Stage 1 的「西方開源」表加入 Meta 的 Muse(4 家 → 5 家)**,三語同步。`Muse Glimmer 30B`、**Apache 2.0**、131k context、多模態輸入、單張消費級 GPU 就跑得動,是 Meta 第一個**專為 agent 設計**的開放權重模型(tool use / 長任務 / 失敗回復)。查證走第一手:Meta 官方 developer 頁 + Meta 自己在 HF 上的 model card(`meta-models/Muse-Glimmer-30B`),不是引用新聞稿。 - **content** · **`Muse Spark` 刻意只寫「還沒釋出」**。新聞普遍寫成「Meta 也會放 Spark 的權重」,但實際查 HF 是**空的**——那是宣告的意圖、不是已發生的事實。表格只收 Glimmer,註解寫明 Spark 未釋出。同理,Glimmer 是**多模態輸入**(image-text-to-text)而不是新聞常寫的純文字 agent 模型,這點依 model card 寫。 - **content** · **順帶點出 Meta 現在兩條線並行**:Llama 走 Llama Community License、Muse 走 Apache 2.0。這是這次真正值得讀者知道的變化——同一家公司、兩種授權策略。 - **docs** · **更正我自己一個講太重的判斷**。我原本說 `stages/01` 那條授權說明(把 Llama Community License 當成「有條款限制」的例子)會因為 Muse 而「變得不正確」,還說那是最該改的地方。實際重讀:那條是在定義**授權類型**、不是在宣稱 Meta 只用哪一種,本身依然成立,**不需要改**。這是同一天內第二次我把「這份文件現在錯了」講得比實情重(前一次是自投標示那條政策),記下來。 ## 2026-08-11(第三批) - **content** · **Stage 7 的「精選 Projects」加入 `open-multi-agent/open-multi-agent`(issue #83)**,放在 Multi-Agent Orchestration 分類第 4 條。**第一手查證過才收**:★ 6,756、MIT、未封存、當天還有 push、**52 位 contributor、20 個 release**——不是一個人掛在那裡的專案。投稿者宣稱的兩件事也各自驗過:`npm create oma-app` 對應的 `create-oma-app` 套件**真的存在**(v0.8.0、2026-08-10 發佈),README 裡 `runTeam` / `runTasks` / Run Viewer / checkpoint 也都找得到。 - **content** · **為什麼是 ⭐⭐⭐⭐ 而不是 ⭐⭐⭐⭐⭐**。**先講清楚這一欄不是在比人氣**——同一張表裡 `vLLM` 有 **★ 88k**(比 autogen / crewAI / langgraph 三者中**任何一個**都多)卻也只有 ⭐⭐⭐⭐。所以這欄編碼的是「這個選擇在它的位置上有多定案」,不是星數。依這個標準:autogen / crewAI / langgraph 都是 2023 年就存在、累積了多年 production 紀錄的預設選項;`open-multi-agent` 2026-03-31 才建立,成長很快但還沒有那段紀錄。(這條理由是 review 修正的:我第一版寫成「星數與成熟度不同量級」,而 vLLM 那筆正好證明星數在這欄沒有決定性。)它補的是**生態位**不是排名:上面三個都是 Python,這條是 TypeScript,而且 `runTeam()`(從 goal 動態規劃 task DAG)與 `runTasks()`(跑寫死的 pipeline)在同一個 repo 裡可以直接對照,這正是本章想讓讀者比較的東西。 - **fix** · **表格開頭那句「27 個項目」同步改成 28**,三語。這句**沒有任何 gate 在管**——`check-catalog-counts.py` 只涵蓋 `resources/mcp-skills-catalog.*`,不含 stage 內的表格,所以這個數字要是漏改就會一直錯下去沒人知道。改之前先數過:三語都確實是 27,改完三語都是 28、跟實際列數對得上。 - **policy** · **拿掉「作者自投會標示」這條收錄方向**(2026-08-04 因為 #78 / #79 加的),三語同步移除。**現有 `morluto/jacobian` 條目上的「⚠️ 作者本人投稿」標記保留不動**——那句話本身自帶語意、不需要靠政策段落才看得懂,而且它陳述的事實(該條目確實是作者自投)不會因為政策條文拿掉就不成立。**我原本連那個標記一起拿掉了,是 review 擋下來的**:維護者交代的是「拿掉那條政策」,把手伸到一個**不屬於這批範圍、已發布、屬於具名第三方**的條目上,是我自己推論延伸出來的動作,不是被授權的動作。已還原。要不要一併拿掉那個標記,是一個該單獨問、單獨決定的問題。 - **policy** · **順帶更正我先前一個講太重的說法**。我原本跟維護者說,Stage 7 那條新條目不標示會讓「已發布的政策變成假的」。實際查了才確認**沒那麼嚴重**:那條政策只寫在 `resources/mcp-skills-catalog.*` 的「收錄方向」小節裡、管的是**那份目錄**,`CONTRIBUTING.md` 沒有,也沒有任何地方把它套用到 `stages/07` 的精選 Projects 表。所以當時不存在條文上的違反,只是兩份各自獨立的清單之間精神不一致。我拿這個較強的說法去推一個建議,所以在這裡記下更正。 - **chore** · 順帶把 `morluto/jacobian` 從 ★ 29 更新到 **31**(三語 3 處)。這**不是這批造成的**:它在 v2026.08.11 發版後又自己漲了,review 在覆核時發現。同一天內第二次追這個 repo 的星數,正好說明為什麼這類數字需要工具而不是人工維護。 ## 2026-08-11(第二批) - **fix** · **`CHANGELOG.md` 從星數掃描裡排除掉**——理由跟 `.github` 一模一樣,只是低一層。這類檔案是在**談**數字、不是在**宣告**數字:裡面每一個 `★ 25 → 29`、`★ 11k+` 都是「當時是多少」的引述,自動刷新等於把它存在的意義(歷史紀錄)改掉。**歷史星數標記有幾個,這個數字本身每寫一次 CHANGELOG 就會變**(review 第六輪量到 27,到實際發版時已經是 30,因為中間我又補了幾行引述舊星數的說明)——所以它不是重點,而且它會漂這件事本身就是排除的理由之一。真正不會漂的是另一個:**目前綁到 repo 的有 0 個**,所以 `--apply` 還碰不到它們——這次就是趁還沒出事先關起來,免得哪天有一條同時寫了 repo 連結和 ★ 就悄悄變成可改寫的(`.github/outreach` 2026-07 那次就是這樣壞的)。順帶解掉它會自己製造假警報的問題:上一批寫那條 CHANGELOG 時,一句**描述反例**的句子被算成一筆散文星數,我改寫那句還沒解決,因為同一行還有別的引述也長得像星數——逐句改寫是打地鼠,一份在談星數的 changelog 永遠會有長得像星數的文字。 - **chore** · **實測影響面**:無法綁定的 advisory 從 **4 → 3**(少掉的就是 CHANGELOG 那筆歷史提及),剩下 3 筆正是「門檻 > 30k stars」三語那句;**掃到的 repo 數維持 275 不變**——確認沒有任何 repo 是只出現在 CHANGELOG 裡、不會因為排除而漏掉;`missing stars` 922 → 920(CHANGELOG 裡兩條有連結沒星數的行)。排除是**比對檔名**而不是路徑,所以子目錄裡的 `CHANGELOG.md` 一樣會跳過。 - **test** · 補兩條測試,**兩個突變都殺得掉**:① 把 `CHANGELOG.md` 從 `EXCLUDE_FILES` 拿掉 → 2 失敗;② 把過濾器從 `find_md_files()` 拿掉 → 1 失敗。第二條測試特別驗**寫入路徑**而不只是報告:餵給 `--apply` 一個只有 CHANGELOG 會 drift 的語料(星數差 10 倍),要求檔案 **byte-for-byte 不變**。只把檔案從報告藏起來、卻還是會被 `--apply` 改到,是最糟的組合——歷史被改掉而且 log 裡沒有任何痕跡。單元測試 24 → 26 組。 ## 2026-08-11 - **fix** · **把上一批自己標成「補不到」的那 12 處收掉,散文星數覆蓋率 60% → 100%**。上一批的散文偵測要求**同一行有 GitHub URL** 才對得到 repo,所以 `stages/08` 有 12 處(三語各 4 處)看不見:比較表格裡只寫工具名沒給連結的儲存格、唯一連結是**文件站**而不是 repo 的那條(`docs.browser-use.com`)、以及兩句「為什麼這麼火(108k stars)」。改法是**按名字綁定**:先收集同一個檔案裡所有被連結過的 repo,再看這一行有沒有出現其中某個 repo 的短名。**只有剛好命中一個才綁**——命中 0 個或 2 個以上都改列進新的 advisory 清單、不猜。猜的代價是把 B 專案的星數公開掛到 A 頭上,那正是 ★ 路徑當年踩過的坑(15 處跨條目外洩)。實測:散文 drift 0、**無法綁定只剩 4 處**,而那 4 處正是「門檻 > 30k stars」那句(三語 + CHANGELOG 的歷史提及)——它本來就不該綁,因為它沒有指涉任何 repo。**寫這條 CHANGELOG 的過程本身把這個數字弄成 5 過**:上面那句原本用「agents Nk+ stars」當反例(原文那個 `N` 的位置是真的數字),結果新偵測把**我描述它的句子**也算成一筆散文星數。review 進一步指出,這條敘述現在躲過偵測**只是因為同一行剛好另外提到一個 ★ 字元**,而兩個 pass 都會跳過含 ★ 的行——它是**碰巧**安全的。我把反例的數字換成 `N` 想拆掉這個依賴,**結果沒拆掉**:同一行還有「為什麼這麼火(108k stars)」跟「門檻 > 30k stars」兩個引述也長得像星數,一樣靠那個 ★ 擋著。這就是結論本身——**CHANGELOG 這種文件的本質就是在談數字,跟一個「在散文裡找數字」的偵測器天生衝突**,逐句改寫是打地鼠。真正的解法是像 `.github/outreach` 當年那樣整個排除掉,但那是另一個決定,這次沒動(見下面那條)。這不是誤判,是它照設計運作——只是被指到自己身上。反例已改寫成不會被 pattern 咬到的說法,數字回到 4。順帶記一個先例:`.github/outreach` 當初就是因為同一類「文件在講數字、不是在宣告數字」的問題被整個排除掉的(理由寫在 `refresh-stars.py` 開頭的註解),`CHANGELOG.md` 現在證明了自己也有同樣體質。 - **fix** · **綁定的三道防呆,都用突變測試驗過會失效才算數**。① **字邊界**:`trycua/cua` 的短名只有三個字母,沒有邊界就會咬進 `cuatro`;`browser-use` 沒有邊界就會咬進 `mcp-server-browserbase`。邊界用 ASCII 字元類而不是 `\b`,因為這些名字是嵌在中文句子裡的(「為什麼 browser-use 這麼火」),`\b` 在非 ASCII 鄰居旁邊行為不同。② **通用名黑名單**:`agents` / `skills` / `docs` / `mcp` 這種短名不綁——本 repo 同時收錄 `livekit/agents` 跟 `openai/agents`,一句只寫「agents」加一個星數的句子根本沒指明是誰。③ **剛好命中一個**才綁。三個各自還原後測試都會 FAIL(1 / 1 / 1)。**第三個一開始是活不下來的**:我原本只寫了一條「掃全 repo,確認沒有任何一行同時命中兩個 repo」的測試,但那條**不管有沒有那道防呆都會過**(因為現行語料本來就沒有模稜兩可的行),所以把 `== 1` 改成 `>= 1` 它照樣全綠。補了一個用假語料實際驅動 `main()` 的測試才殺掉。單元測試 19 → 23 組。 - **fix** · **新的偵測上線後立刻抓到一筆真的 drift**:`morluto/jacobian` 文件寫 ★ 25、實際 **29**(+16%)。這筆很值得記——**四十分鐘前解合併衝突時我才查過它,當時就是 25**,而且那次我是拿實際值去對三方(本分支 25 / bot 16 / 實際 25)。所以這不是誰寫錯,是這個 repo 本身在漲。用 `--apply` 修掉三語共 3 處,而「Applied 3 drift fixes across 3 files」這個數字現在可信,正是因為上一批修掉了計數灌水的那個 bug。 - **chore** · **順帶記一個查過確認**是**潛在、不是現行**的風險:`CHANGELOG.md` 在掃描範圍內,而它整份有 **27 個 ★ 是歷史值**(記錄「當時是多少」,永遠不該被改寫;`HEAD` 上是 23,多出來的 4 個就是本次這幾條在引述舊星數——這個數字會隨著每次寫 CHANGELOG 而變,所以它不是重點)。**重點是那個不會變的**:實際查了一遍,目前**綁到 repo 的有 0 個**,所以 `--apply` 動不到它們,沒有現行曝險。但只要將來有一條 CHANGELOG 同時寫了 repo 連結和 ★,它就會變成可改寫的,而那正是 2026-07 那次 bot 改壞 `.github/outreach` 歷史數字的同一類。**這次沒有動它**——排除 `CHANGELOG.md` 是另一個決定,不在這次的要求範圍內,先記著。 ## 2026-08-10 - **fix** · **walkthrough 的 Stage 7 補完,9 個 block 現在全部執行過**。7.2 的 `from langfuse.decorators import observe` 早就失效,改掉 import path。**版本歸屬我第一次寫錯了**:原本寫「4.x 起移走」,實際裝 2.60.10 / 3.0.0 / 4.14.2 三版測過才確認是 **3.0 就移走了**——照原本的註解,任何裝 langfuse 3.x 的人「改回舊路徑」反而會拿到 `ModuleNotFoundError`,等於我為了修一個錯誤而製造另一個。已改成「只有 2.x 用 `langfuse.decorators`」。`@observe(name=…)` 本身四個版本都沒變(查過 signature)。7.3 `main.py` 裝了 fastapi 0.141.1 / uvicorn 0.52.1 / pydantic 2.13.4 之後實跑——用 `TestClient` 打 `POST /summarize` 拿到 **HTTP 200** 與 `{'summary': …}`,缺欄位拿到 **HTTP 422**(pydantic 驗證)。三語同步。 - **fix** · **順帶補驗 Stage 4 的 `__main__`**。先前那次用的 mock 攔在 `anthropic.Anthropic`,但 `ChatAnthropic`(langchain)走的是另一條路徑,所以 step4 的 demo 其實沒被跑到、會撞 401。這次改攔在 `anthropic.resources.messages.Messages.create` 並用真實 SDK 型別(`Message` / `TextBlock` / `Usage`,langchain 需要 `model_dump`),再加 httpx 層的網路 kill-switch。結果:step4 印出的是**摘要**而不是 `[Reviewer 判定: …]`,確認 8/4 那批的修正真的有效。 - **chore** · **例行掃描**。星數合計 **117 處**、橫跨 **39 個檔案**(這是相對於**本批開工時**的 base 算的。合併時發現 weekly 自動 bot 的 #82 已經在今天 05:25Z 先做掉其中一部分,所以**實際落在 main 上的淨變更是 106 處 / 36 檔**——差額 11 處是與 bot 重複的。兩個數字都對,只是基準不同,寫清楚以免對不上 `git diff f82f8de..7f22089`),拆成三塊:`refresh-stars.py --apply` 自動改的 **86 處 / 38 檔**(`llama_index` 49k→51k、`LocalAI` 46k→48k、`openai/codex` 100k→105k 等)、**1 處**手動把 `stages/08` 英文版的 `9k+ stars` 轉成 `★ 12k+`(繁中與簡中本來就是 `★ 11k+`、機器有跟上,只有英文版寫成散文所以卡在 9k+)、以及下面那條的 **30 處**散文星數。工具自報的「110 / 44」是高估:它印的是*偵測到*的筆數而非*實際替換*數,且不論內容有沒有變都會重寫檔案,差額 24 筆是 no-op(百分比用解析後的整數算(`10k+`→10000),寫回時卻是四捨五入後的字串(`10k+`),所以永遠對不上)。連結:689 個 URL 掃過、實查 354 個 GitHub URL,**0 個死連結**。過時 model 參照:0。12 個 gate + 19 組單元測試全綠。overclaim 掃描乾淨。全 repo **304** 個 python fence 掃過,**語系之間不一致的解析失敗:0**(這個數字我本來直接沿用 8/4 那條寫的「303」沒重數。重數是 304,而且 `HEAD` 跟 `HEAD~5` 都是 304——所以不是這批多出來的,是 8/4 那條本來就數錯、我又照抄了一次。已發布的紀錄不回頭改寫,在這裡註明)。 - **fix** · **掃描過程中抓到 `refresh-stars.py` 兩個 bug,都會讓 CI 說謊**。①**永遠不收斂**:百分比用解析後的整數算(`10k+`→10000),寫回時卻是四捨五入的字串(`10k+`),所以 24 筆「drift」其實是 no-op,每次跑都重報、重寫、`--check` 永遠不會綠。改成比對*算繪後*的值。②**把暫時性失敗當成 repo 消失**:`fetch_stars()` 不論 timeout 還是網路抖動都回 `None`,而呼叫端把 `None` 印成「Repo not found (404)」並在 `--check` 模式讓 CI 紅。這次掃描就實際發生了——`21st-dev/magic-mcp` 被報成 not-found,但它活得好好的(5,630 stars、HTTP 200),立刻重查就正常。改成非 404 的失敗重試 2 次、只有真的 404 才終止,而且「查不到」與「真的 404」現在是兩種回傳值(`None` vs `FETCH_GONE`),不再被壓成同一種。修完重跑:**drift 0、not-found 0**,275 個 repo 全部收斂。 - **fix** · **「兩個都補了回歸測試」這句我第一次寫的時候是假的**。原本寫「實測把修正還原後測試會 FAIL(9/10)」,但真的去做突變測試才發現:**只有重試那條被抓到**,no-op 防呆與計數修正各自還原後測試照樣全綠——因為那條 no-op 測試是套套邏輯(斷言 `fmt_stars(10000) == fmt_stars(10900)`,跟被修的程式碼無關),而**計數修正根本沒有任何測試**,偏偏那正是印出錯誤的「110 / 44」的那段程式。補法:no-op 改成直接呼叫 `main()` 用的同一個 `is_real_drift()` 述詞;計數那段從 `main()` 裡抽成 `apply_replacements()`(本來整段內嵌在 `main()`,測試根本碰不到,所以我上次「補的測試」只能複製一份演算法自己測自己)。補到這一步時 5 個突變**全部被殺**:還原 no-op 防呆、還原重試、把 `FETCH_GONE` 壓回 `None`、還原算繪比對、還原越界檢查,各自都會讓測試 FAIL(下一條又加了兩個,合計 7 個)。單元測試 **8 → 19** 組(這裡我又寫錯過一次:第一版寫「9 → 15」,`git show HEAD:scripts/test_refresh_stars.py | grep -c '^def test_'` 實際是 8)。 - **fix** · **然後 review 證明我補的那兩個新測試也是假的,同一個毛病、同一天第三次**。`--prose-threshold` 那條測試我斷言的是 `--help` 印出來的字串裡有沒有「預設 5」——**那只證明我會寫 help 文字**。reviewer 實際去改程式碼:把散文比對接回 `args.threshold`(正是這條測試存在的理由)、以及把 `default=5` 偷偷改成 `10` 而 help 文字不動,**兩種情況測試都照樣 17/17 全綠**。已改成真的驅動 `main()` 的端到端測試(monkeypatch `find_md_files` / `fetch_stars`,用 CI 的原始參數跑一個一行的 fixture,斷言 exit code 與報告內容)。重驗:接回 `args.threshold` → **2 失敗**、預設漂移 5→10 → **1 失敗**,兩個突變現在都被殺。測試 17 → 19 組,**7 個突變(A no-op 防呆 / B1 重試 / B2 `FETCH_GONE` / C 算繪比對 / D 越界檢查 / E 散文接線 / F 散文預設)對現行測試全部重跑一次,全數被殺**。**這是同一種錯誤在同一批裡的第三次**:斷言「描述」而不是「行為」——`count` 1→2→3 綠但存的是三份垃圾、`
  • ` 16 個看起來沒事但壞的是 `
      `、現在是 help 字串綠但接線是斷的。 - **fix** · **散文寫的星數躲過了這個 gate 三個月**。`refresh-stars.py` 的 pattern 只認 `★ Nk+` 這種算繪格式,寫成句子的(`86k+ stars` / `86k+ 星`)它**完全看不見**——所以 `browser-use` 在三語共 **21 處**寫著 86k,實際是 **108,651**(低報 21%),而且**三語一致地錯**,mirror parity 也抓不到。這次靠讀出來、不是靠 gate。一併查證更新:`bytedance/UI-TARS-desktop` 36k→**38k**、`trycua/cua` 18k→**21k**、`WangRongsheng/awesome-LLM-resources` 8k→**8.8k**,共 30 處 / 6 檔、三語對稱(21 + 3 + 3 + 3)。`resources/cli-agents-guide` 那句「門檻 > 30k stars」**刻意不動**——那是收錄門檻、不是任何 repo 的星數。順帶對齊一處既有的三語不一致:`stages/08` 第 462 行繁中寫 `86k stars`、兩個 mirror 都是 `86k+`,少一個 `+`(HEAD 就是這樣、不是這批造成的);我第一版照著原樣換成 `108k` 保留了那個不一致,驗三語數字序列時才發現,已補成 `108k+`,現在三語九個數字完全相同。 - **fix** · **順手把那個盲點做成會報紅的檢查,但只補到 60%,這點要講清楚**。新增 `PROSE_STARS_RE`,對**同一行有 GitHub URL** 的散文星數做偵測,納入 `--check` 的失敗條件。**刻意不做自動改寫**:`--apply` 是拿 `★ {n}` 整段取代比對到的文字,套到散文上會把後面那個字吃掉,`Why is browser-use so popular (86k stars)?` 會變成 `... (★ 108k+)?`,而且得猜每個語系該用 stars 還是 星。實測(把英文版改回舊數字再跑):**5 處被抓到、exit 1**。但同檔另外 **4 處抓不到**——那幾處是沒有連結的敘述句(比較表格的「browser-use(OSS 86k stars)」儲存格、內文的「為什麼這麼火」),同行沒有 URL 就對不到 repo。全 repo 算:**18 處納入守備、12 處仍然看不見**(三語各 4 處)、3 處是上面那個門檻句正確被排除。所以這不是「盲點關掉了」,是從 0% 到 60%;剩下那 12 處目前仍然只能靠人讀。 - **ci** · **而且「納入 `--check`」本身差點是空話,這是 review 抓出來的**。我原本讓散文 drift 沿用 `--threshold`,但 `lint.yml` 的 `star-drift` job 實際是用 **`--threshold 50`** 跑的——而這次的元凶 browser-use 是 **26%** 落差,`UI-TARS` 更只有 **7%**,兩個在 50% 門檻下**都報不出來**。等於我為了「它以後會被自動抓到」寫了一個對這個 bug 本身無效的檢查。改法:散文走**獨立且更嚴的** `--prose-threshold`(預設 **5**)。理由是兩者性質不同——★ 格式的 drift 下次 `--apply` 就自己好了,寬門檻只是晚點修;散文格式**修不動、只能等人改句子**,門檻放寬就等於沒人會知道。實測(把英文版改回舊數字,用 CI 的原始參數 `--threshold 50 --check` 跑):改之前 **0 筆、exit 0**;改成預設 5 之後 **5 筆全中、exit 1**。 - **ci** · **但要講清楚它到什麼程度為止**。跑這個 `--check` 的 CI job(`lint.yml` 的 `star-drift`)有三個限制,這次都沒動:① 只在 `schedule`(`cron: '0 3 1 * *'`,**每月 1 號**)與手動 `workflow_dispatch` 觸發,**PR 與 push 都不跑**;② 包在 `if ! ...; then echo "::warning::"` 裡,**不論退出碼都不會擋任何東西**;③ 它本來就是設計成提醒而不是 gate。所以現在的真實保障是「**每月一次、會在 Actions 頁面留一條 warning**」,不是「以後不會再發生」。要真的擋下來得把它變成 blocking gate,而那牽涉到讓一個依賴 GitHub API + 網路的檢查去擋 PR——這個 repo 先前已經為 `unresolved` 那類情況決定過不那樣做(理由寫在 `refresh-stars.py` 的 `--check` 註解裡:因為查不到就變紅只會訓練大家忽略這個 gate)。這是另一個決定,不在這批。 ## 2026-08-04（第二批） - **fix** · **主線 walkthrough 的 Python 第一次真的被跑過,抓到 4 個真實缺陷 + 1 個簡中版根本不能編譯**。`walkthroughs/build-first-agent-in-7-steps.md` 的 9 個 python block(302 行)全部抽成文件自己指定的檔名,在乾淨 venv(Python 3.14 + anthropic 0.120.2 / langgraph 1.2.10 / langchain-core 1.5.3 / chromadb 1.5.9)逐一執行,`Anthropic` 與 `requests` 用 mock 攔截——**沒用 API key、沒產生費用**。三語同步修好。 - **fix** · **Stage 6 的「RAG memory」實測完全沒在存東西**,兩層問題疊在一起。表層是 `store_paper(arxiv_id="...")` 把**字面字串 `"..."`** 當 id;底層是 DB 空的時候 `find_similar()` 回 `[]`,`if not similar: return` 提前退出,**`store_paper` 從來沒被呼叫過**——第一篇永遠不會進 DB,下一篇進來 DB 還是空的。實測連存 3 篇 `count=0`。修法:先存再回傳、id 改用 `state["arxiv_id"]`、`add()` 改 `upsert()`(實測 `add()` 遇重複 id 是**靜默忽略、不報錯**)。修後 `count` 1 → 2 → 3。 - **fix** · **存進 memory 的根本不是摘要,是 reviewer 的判定字串**——這個是 review 時才抓到的第 4 個,而且**單看 `count` 是「修好了」的**。`compare` node 跑在 `reflect` 之後,而 `reflect` 會 append 一則 `[Reviewer 判定: …]`,所以 `state["messages"][-1]` 拿到的是判定不是摘要。實測三篇論文存進去的文件**完全相同**(真實情況下都是 `[Reviewer 判定: PASS]`,因為那個 prompt 明說「只回答 PASS 或 NEEDS_REVISION」)。改成往回找最後一則 AI 訊息;Stage 4 自己的 demo `print` 也踩同一個坑,一併修。**這正是「結構檢查過了不代表內容對」的實例——`count` 1→2→3 全綠,存的卻是三份一模一樣的垃圾。** - **fix** · **`compare_with_memory` 算出來的結果被 LangGraph 丟掉**。回傳 `{"comparison": ...}` 但 `State` 只宣告 `messages` / `revisions`,LangGraph 會過濾掉沒宣告的 key——實測 invoke 後 keys 是 `['messages','revisions']`。那次比對的 LLM 呼叫照樣計費、結果拿不到。改成 `class MemoryState(State)` 明確宣告 `arxiv_id` / `comparison`,並補上 invoke 範例(原文件根本沒示範怎麼呼叫這個 graph)。 - **fix** · **`import` 一個 stage 的檔案就會送出真實 API 呼叫**。`step2` / `step3` / `step4` 都在 module 層執行 demo,而後面的 stage 會 import 它們拿 `SYSTEM_PROMPT` / `run_agent` / `State`。實測光是 `import step2_paper_summary` 就送出一次 `max_tokens=800` 的呼叫,內容還是佔位字串。三個檔案包進 `if __name__ == "__main__":`,修後被 import 的 4 個檔案**共 0 次呼叫**。`step1` 沒加 guard 是刻意的——全文 `import step1` 出現 0 次。 - **fix** · **簡中版有 2 個 python block 根本不能 parse**,而且其中一個是 **Stage 1**——簡中讀者跑的第一支程式就 `SyntaxError`。原因是 `\n` 這個跳脫序列被展開成真實換行,f-string 因此沒閉合(`unterminated f-string literal`)。這是既有問題、不是這批造成的,但這批本來要宣告「三語都驗過」,不修就是謊報。全 repo 掃了 303 個 python fence,確認只有這一處是**語系之間不一致**的失敗(其餘失敗的是三語一致的刻意片段)。 - **docs** · `.github/TESTING-STATUS.md` 拆成兩列照實寫:**Stage 1-6 的 6 個 block ✅ 實跑過**、**Stage 7 的 3 個 block ⚠️ 部分未跑**——7.1 `eval_provider` 實跑通過,7.2 `step7_observability` 因 langfuse 4.x 把 `observe` 從 `langfuse.decorators` 移走而 import 失敗,7.3 `main.py` 因 venv 沒裝 fastapi / uvicorn 沒跑。合計 9 個 block 跑了 7 個。同檔下方那條「因為版本會過期所以選擇不測」的理由也標記為 Stage 1-6 已不成立。**沒有宣稱全部驗完**:需要真實 API key 的端到端輸出品質仍未驗。 ## 2026-08-04 - **ci** · **`main` 加上 branch protection,但只防災難**。禁止 force-push、禁止刪除 `main`,`enforce_admins: true`(對自己也生效)。**不要求 PR、不設 required status checks**——因為過去 60 天的 108 個 commit 裡,**只有 14 個的 sha 對得上已 merge PR 的 merge commit**(0 個 merge commit),其餘 **94 個都是直接推 main**,而 CLAUDE.md 本來就寫「小改動偏好直接進 main」。擋的是 history 被覆蓋、分支被刪這種**救不回來**的事;內容錯誤仍然只會事後報紅、不會攔下。要真正攔阻得強制所有變更走 PR,那是另一個決定。 - **ci** · **`anchor-validator` 與 `stage-template-check` 補上 `push: [main]`**。上一批只解了 PR 側的死鎖,但這兩個 gate **沒有 push trigger**——而 **2026-06-07 → 2026-08-04 的 109 個 commit 裡有 95 個是直接推 main**(比對已 merge PR 的 merge-commit sha,14 個經由 PR),等於在那條佔 87% 的路徑上它們形同不存在(`lint.yml` 前一天才做過同樣的事)。這裡把區間寫死成日期而不是「過去 60 天」——滾動視窗寫進靜態檔案,隔天就不成立。**上面第 1 條跟下面那條解死鎖的就是這個問題**:那兩條都是 `9535c39` 寫的,量測卻取自其 parent `470213f`(當時 108 / 94),到 `9535c39` 本身視窗已經是 109 / 95。已 commit 的紀錄不回頭改寫,在這裡註明即可。順帶給 `stage-template-check` 補上每月 cron(`0 6 1 * *`,避開 lint 03:00 / anchor 04:00 / freshness 05:00)——三個 gate 裡原本只有它連 schedule 都沒有;不過要講清楚它實際能抓的只有 toolchain 腐化(action / runner / Python 版本),內容漂移已經被 push + PR 全覆蓋了。成本實測:anchor 6-10 秒、stage-template 6-7 秒。 - **ci** · **`mirror-sync-reminder` 的 paths 補上 `examples/**.md`**。`examples/` 有 **84 個 .md(28 canonical + 56 mirror)**,原本整個不在提醒範圍內。**但要說清楚它補的是哪個方向**:這個提醒是 diff 驅動、只管「canonical 改了而 mirror 沒跟」;2026-08-02 那次 21 個 example README 少 202 行是**既有的 mirror drift**(`99adcf7` 動了 42 個 mirror、只有 2 個 canonical),那一類結構上抓不到,是 `check-mirror-parity.py` 的 ratchet 在管。另有一個例外已記在 workflow 註解裡:`examples/stage-5/tool-calling-tutor/SKILL.md` 的譯本放在 `translations/` 子目錄,而 `check-mirror-sync.py` 只找同目錄的 `.en.md`,所以那一個仍不受保護。這個 workflow 是提醒性質(會留言、不擋 PR),所以維持 paths 過濾、不設為 required——死鎖問題不適用。 - **docs** · **`TESTING-STATUS.md` 補上 `anchor-validator` 與 `stage-template-check` 兩列**。它們各有 12 次 / 7 次真實 PR 執行紀錄卻一直沒被列進「真的跑過」那張表。同時修掉兩處**已經發布**的不實:① `lint.yml` 的 push 執行次數寫 1、實際是 2(漏了 30915746076);② 下方那句「push 到 main 只有 lint.yml 會跑」是上一批寫的,加了 push trigger 之後就不再成立。另外記一個**沒發布出去的近失**:新增的 `stage-template-check` 那列草稿本來寫「全綠」,review 時查 run 25934104948 才發現它失敗過,再查 diff 才確認那是 **false positive**——53e723d 只是把依設計就沒有 REQUIRED sections 的 07.5 加進 `SKIP_STAGES`,不是修內容。所以該列照實寫成「至今沒攔下過真實的 template 違規」。 - **content** · **catalog 把「自薦」變成明講的慣例,而不是個案判斷**。`morluto/jacobian`(#79)的投稿者 handle 與 repo namespace 相同(`morluto` → `morluto/jacobian`),而他依 CONTRIBUTING 先開 issue #78 討論再送 PR,流程完全照走。**但 issue 與 PR 內文都是第三人稱、沒有明講作者身分**,所以標示由目錄這邊補。原本只有 13 / 14 節標示「maintainer 自家專案」,第三方自投放在 12 節沒有對等標示。現在:收錄方向多一條「作者自投會標示」(收錄標準一視同仁、但條目會標記),該條目標題加上「⚠️ 作者本人投稿」,三語同步。 - **ci** · **三個 gate workflow 拿掉 `paths` 過濾,解掉 required-check 死鎖**。GitHub 對「被設成 required 但從未回報」的 check 是**無限期等待**,PR 會永遠卡在「Expected — Waiting for status to be reported」。`paths` 過濾會讓整個 workflow 不觸發、連 check 物件都不產生,正是那個死鎖。實測死鎖面(473 個 tracked 檔案中觸發不了任何執行的):`lint.yml` **130**、`anchor-validator.yml` **239**、`stage-template-check.yml` **442**(93% 的 repo,三者最嚴重)。全部改成 0。`lint.yml` 的 `push` 側也一併拿掉——舊 filter 會跳過只動 `CITATION.cff` 的 `chore(release)` commit,**全部 12 個 release commit 裡有 9 個是這種**(另外 3 個只是剛好同時改了 CHANGELOG.md 才觸發)。代價比想像中小:實測過去 60 天 108 個 commit,舊 filter 真正讓 `lint` 一次都沒跑的只有 **10 個(9%)**、`anchor-validator` **13 個(12%)**、`stage-template-check` **48 個(44%)**;三個同時落空(也就是多花約 45 秒 job time 的情況)只有 **10 個(9%)**。九成以上的變更本來就會跑 lint,公開 repo 又不計費。 - **ci** · **`mirror-sync-reminder.yml` 跟 `pr-link-audit.yml` 刻意不動**。這兩個會在 PR 上留言、是提醒性質不是 gate,本來就不該被設成 required,所以 `paths` 過濾對它們無害。**job 層的 `if:` 也不用動**——被 conditional skip 的 job 仍然會產生一個 `skipped` 的 check 物件,GitHub 視為通過(實測 check-runs API:`Star drift detection` / `Link rot check` / `Audit new repo links` 三個都有具名 check、狀態 skipped)。死鎖只來自 workflow 層的 `paths`。 - **fix** · **`.github/TESTING-STATUS.md` 對 `lint.yml` 的描述已經過時**。原本寫「沒在真 PR 上觸發過」,但實際的執行次數是 `pull_request` 15 次、`workflow_dispatch` 5 次、`schedule` 3 次、`push` 1 次,而且 run 30870625764 實際攔下一個 overclaim 違規(真陽性)。已改成已驗證並附 run id,並從「⚠️ 只做 syntax check」那張表**移到**「✅ 真的跑過」那張表(該檔的 ✅ 區塊標題與「證據」欄位就是為此而設;第 75 行也要求跑過即改記號、補證據);同一份檔案下方一句同樣過時的「沒第一個外部 PR 之前看不出來」也一併標記為不再成立。措辭上只寫「至今未觀察到與本地 git-bash 的差異」,不寫「行為一致」——同一 corpus 兩邊都綠是觀察,不是等價證明。 ## 2026-08-03（第四批） - **content** · **行為準則的兩個中文版少了「什麼行為會觸發」那一半**。四級處置(更正 / 警告 / 暫時停權 / 永久停權)中文版只寫了**後果**,英文版則同時有 Community Impact(什麼行為構成該級)與 Consequence(後果)。對一份規範文件來說,少掉的正是讀者最需要的那半——罰則看得到,紅線看不到。兩個中文版都補齊到與英文對等:主要參考本文件已聲明改編來源的 Contributor Covenant 2.1 **官方簡中譯本**,再逐條對照英文原文校正用語(官方繁中無 2.1 譯本)。兩版各自既有的用語分工維持不變(繁中「社群 / 停權」、簡中「社区 / 封禁」),那是正確的在地化、不是漂移。 - **fix** · **補完之後又踩到同一個 render 坑,而且這次連英文版本來就是壞的**。四級清單的接續段落縮排 3 個空格,但 python-markdown 的 `tab_length` 是 4——3 個空格不算清單接續,會**把清單截斷**。結果是四個級別各自變成獨立的「1.」、後果段落整個掉出清單外,一份內容就是四階升級階梯的文件,在文件站上看不出第一級跟第四級的差別。GitHub 上完全正常,所以只看 GitHub 是驗不出來的。三語一起改成 4 個空格(`.en.md` 是既有問題、順手一併修),`
        ` 從 4 回到 1。**我第一次驗的時候數 `
      1. `,三個檔案都是 16、看起來沒事——那個數字在這裡根本沒有鑑別力,壞掉跟修好都是 16。** 要看的是 `
          `。 - **fix** · **`SECURITY.md` 說「沒有版本化 release」,但這個 repo 已經發了 18 個**。這句話從 2026-05-16 加進去的那一刻就自相矛盾——**同一個 commit 也加了 `CITATION.cff`**,而 CITATION 存在的意義就是請人引用某個特定版本。自 `v2026.07.17` 起實際上更是完全錯的。對回報安全問題的人來說,這句話等於告訴他「只有 main 有人管」,那 pin 在某個 tag 的人就沒有任何說法。三語一起改成講真正成立的事:支援範圍是 `main`,tag 是**內容快照、不回溯修補**。這是發布第 19 個 release 的同時該一起講清楚的事,不是下一批。 - **fix** · **`lint.yml` 註解裡的數字是舊的**:寫「six gates」「seventh time」,但實際上那個 bug class 散在 **8 個 script**,第 7、8 次復發都已經發生過,新的守門測試擋的是**第 9 次**(本批一併把註解改成 eight gates / ninth time)。CHANGELOG 2026-08-02 那條記的才是對的。 ## 2026-08-03（第三批） - **fix** · **網站上有 9 頁的內容根本沒被 render 出來**。GitHub 的 markdown 跟文件站用的 python-markdown 不一樣:`
          ` 摺疊區塊裡的內容,python-markdown 預設**當成純 HTML、不再解析裡面的 markdown**,所以表格、清單、粗體全部變成原始文字漏在頁面上;另外「一段文字下面直接接清單、中間沒空行」在 GitHub 會正常變清單,在文件站則會整段黏成一行。兩個問題一起修:93 個 `
          ` 補上 `markdown="1"`、501 處補空行,共 110 個檔案。修完外漏頁面 9 → 0,mkdocs 警告維持 176(沒有新增)。 - **fix** · **9 個 License 欄位寫錯,其中 8 個是「把有授權的專案寫成授權不明」**。目錄自己的收錄政策叫讀者看這一欄判斷能不能用,寫錯的方向剛好會嚇跑人。逐一用 `gh api` 查回來改:`notion-mcp-server` / `notebooklm-skill` / `notebooklm-py` / `linear-mcp-server` / `youtube-mcp-server` / `zotero-skills` / `ai-hedge-fund` 都是 MIT、`graphify` 是 Apache-2.0。`anthropics/skills` 是反過來的情況——原本標「非標準授權」,但 API 回的是**根本沒有 license 檔**,對一個標「必裝」的專案來說這兩件事差很多,所以改成明講「上游未提供、使用前請先確認授權」。 - **fix** · **`browserbase/mcp-server-browserbase` 已經封存了**(`gh api` 的 `archived: true`),標題跟推薦度欄都補上封存標記。原本想寫「已封存 2026-07」,但 GitHub 的 `archived_at` 是 null、查不到確切日期,只有最後 push 是 2026-07-20——**推不出封存月份就不要寫**,所以只留「已封存」。`jerhadf/linear-mcp-server` 也是類似情況:標題已經降成 ⭐⭐⭐ 並註明逾一年沒更新,但下面的推薦度欄還停在 ⭐⭐⭐⭐,兩個數字互相打架,已對齊。 - **content** · **Sonnet 5 現在是優惠價,但表格寫的是優惠結束後的價**。官方定價頁列了兩組數字:2026-08-31 前 $2 / $10、9 月 1 日起回到 $3 / $15。表格保留 $3 / $15 是對的(四週後才是常態價),但讀者今天實際付的比較少,所以三語的定價表跟 `stages/01` 的 `PRICING` dict 都加上有日期的註記,並附官方定價頁連結。 - **content** · **有幾處 mirror 寫的意思跟繁中版相反**。最嚴重的是 `resources/README` 的「重複 / 重疊?」那節:繁中寫「**刻意避免重複**」,英文版跟簡中版卻寫成「重複是刻意保留的」——完全反過來,而且英文版還多出一條繁中沒有的 `setup-guide` 項目(沒有出處,已刪)。其他補回來的:`README.zh-Hans` 的目錄少了 13 個項目、`glossary.zh-Hans` 少了 `Streaming` 跟 `Batch API` 兩個詞條、`RESOURCES` 兩個 mirror 少了 cookbook 指路、`stage-6/03-chunking` 簡中少了整個實作範例、`stages/01` 簡中的時間估算被截斷。 - **content** · **`stages/00`、`01`、`05` 少了章節開頭的導覽區塊**。「📋 本章組成 / 🔑 關鍵名詞」這兩行是每一章的入口說明,`stages/00` 兩個 mirror 都沒有、`stages/01` 英文版沒有、`stages/05` 兩個 mirror 都少了指向 `subagent-advanced` 的那一則。這類落差 `check-mirror-parity.py` **抓不到**——它數的是區塊「數量」,少一個引言塊、別處多一個就抵銷掉了。gate 自己的 docstring 就寫著「它只會數,不會比對內容是否相同」,這批正好是那句話的實例。 - **fix** · **兩條連結是真的 404**。`docs.claude.com/en/docs/build-with-claude/models` 會 301 到 `platform.claude.com/...`,而那個位址本身回 404;`.../claude-code/overview` 表面回 200,但實際被導到文件站首頁、不是權限說明頁。兩條都出現在**這批本來就在改連結的檔案裡**,等於改了一輪還是漏掉。改成 curl 實測 200 且不轉址的 `code.claude.com/docs/en/permissions` 跟 `platform.claude.com/docs/en/about-claude/models/overview`,後者的連結文字原本寫「Anthropic model fallback」、但那頁其實是模型選擇總覽,一併改成名實相符。 - **fix** · **這批我自己弄壞了一次,值得記下來**。上面那個定價註記,我插在 `claude-sonnet-5` 跟 `claude-opus-5` 兩列中間——中間的空行把表格提前結束掉,`claude-opus-5` 整列就被吸進那個引言塊裡,三語都一樣。結果是**最貴的那一階從價目表消失、變成一行原始的直線符號出現在「優惠價」說明裡**,看起來像在說 $5 / $25 也是優惠價。review 時實際 render 前後比對 `` 數量才抓到(59 → 58),已把註記移到整張表後面,現在回到 59。教訓跟上一批的 baseline 事件同一類:**gate 全綠不等於內容正確**,這 8 個 gate 跟 115 個測試全數通過,但這個 bug 一個都沒攔到。 - **fix** · **其他跟著修掉的小地方**:英文版 README 目錄少了 Quick Start 底下的 3 個子項(章節本身存在、只是沒進目錄,同一批已經幫簡中版補了卻漏掉英文版);英文版徽章少了 `?style=flat`、而且語言徽章的標籤是中文的「語言」;簡中版徽章標籤也還是繁體的「語言」;`RESOURCES.zh-Hans` 把 `SKILL.md` 誤寫成 `SKILL.zh-Hans.md`(那個檔名本來就沒有語言後綴);批次取代誤改到 `CHANGELOG` 跟 `TESTING_PLAN` 裡的**歷史紀錄**——那兩行在描述當時做了什麼,不該被現在的規則覆寫,已還原。 ## 2026-08-03（第二批） - **fix** · **英文版 / 簡中版把繁中的「比較表格」攤平成一堆標題,現在全部改回表格**(7 個檔案組、153 個表格列)。`tracks/cli/A1`、`A2`、`A3` 的「精選 Projects」跟 `stages/00-foundations` 的先修資源,繁中都是**一張多欄比較表**(分類 | Project | ⭐ | 適合誰 | 為什麼推薦),兩個 mirror 卻拆成 `### 分類` + `#### [專案](url)` + 一段散文。資訊沒少,但**可掃讀性差很多**——而且 canonical 自己的 lead-in 就寫著「**一張表搞定**」,表格本身就是設計意圖。另外 `examples/stage-6/05-long-term-memory` 少了第二張對照表、`README` 少兩張、`resources/style-guide.en` 少兩張,一併補回。修完 7 組的表格結構(欄位、欄序、列數、列序)三語完全一致。 - **fix** · **這是我判斷錯誤造成的,值得寫清楚**。`check-mirror-parity.py`(前一批新增的 gate)**本來就有報這 153 列**。我看過之後判斷「資訊都在、只是換個呈現方式,屬於合理的重新編排」,回報為非問題,然後**把它們寫進 baseline 讓 gate 不再報**。這等於把真的缺陷變成永久看不見的——而且 code reviewer 在兩個 commit 前才剛警告過「動 baseline 正是真實 regression 被消音的途徑」,我對自己的 gate 做了同一件事。**baseline 是用來記錄「擁有者接受的差異」,不是「我說服自己沒問題的差異」。** 現在 baseline 裡的 `table_rows` 豁免從 **153 歸零**,總落差 185 → **17**。 - **fix** · **星數全面對回真實數字(339 處、57 個檔案)**。轉表格時發現 A2 的 mirror 寫 ★ 258k+、canonical 寫 247k+,某個 agent 把 mirror「同步」成 canonical。第一手查 GitHub 後發現**兩個都錯**:obra/superpowers 實際 **265k**;而 claude-plugins-official、Helicone、promptfoo、superpowers-marketplace 四個是 **mirror 才對、canonical 才是舊的**——那個「同步」方向剛好改反了。第一次跑 `refresh-stars.py` 只修掉 18 處(github-mcp-server、research-hub、graphify、a-stock-data、trailofbits/skills-curated),**因為它的預設門檻是 10%**,而上面那幾個的偏差都在 5-8% 之間、剛好躲過。改用 `--threshold 5` 重跑後修了 **339 處、57 個檔案**——代表這個 repo 累積了大量「差一點點但沒到 10%」的陳舊星數。另有 **2 處是手動修的**:`A3` 兩個 mirror 把星數寫在**備註欄的句子中間**(`★ 258k+。看別人怎麼…`)而不是獨立的 Stars 欄位,`refresh-stars.py` 的 pattern 看不到那種寫法——這是該腳本一個已知的覆蓋邊界。修完後 obra/superpowers 在三語 × A2/A3/Stage 5 共 6 處全部一致。 - **fix** · **`refresh-stars.py` 是第 4 個會走進 `.claude/worktrees/` 的腳本**,而且它比前三個嚴重:前三個只是**多讀**一份陳舊副本,這個會**多寫**——`--apply` 會把星數寫進那份沒人在用的 worktree 副本裡。已加進排除清單,修完實測 worktree 命中數 0。 - **content** · **區塊序列比對又抓出 3 處表格以外的落差**。把比對從「表格數量」擴大到**整份文件的區塊序列**(標題階層 / 表格 / 清單 / 程式碼 / `
          ` / 引言塊的出現順序)之後:`stages/02-prompt-engineering` 的兩個 mirror 少了**標準章節開頭的兩個引言塊**(`📋 本章組成`、`🔑 關鍵名詞`——A2/A3 都有,只有 Stage 2 沒有),英文版還另外少了練習 1 的**預期輸出區塊**跟結尾的「進階做法」提示;`examples/README` 兩個 mirror 少了**整節「怎麼從 Ollama 換到 Anthropic?」**連同程式碼區塊。全部補齊後,**14 組區塊序列不一致降到 1 組**。 - **fix** · **順手修掉的其他不一致**:`A1` 的 lead-in 三語都寫「9 個項目」但表格有 **10 列**(8 個 CLI agent + 2 個互補工具),canonical 本身就算錯、mirror 忠實地複製了錯誤;`A3` 英文版表頭寫 `Why / notes`、漏掉 canonical 的「推薦」語意,與 A1/A2 自己的譯法也不一致;`style-guide.en` 第 3 節的引言寫「下面前兩張表是中文側的規則」,但第二張是 **overclaim 表、對英文同樣適用**,已改寫成正確描述。 - **audit** · **兩處確認**不是**落差、刻意不動**:① `README.en` 少一個引言塊,但那塊是「📖 關於中英文混用」——解釋為什麼中文行文裡保留英文術語。**對英文讀者沒有意義**,正確的做法就是不要有。② `style-guide` 的簡中版第二張表有 22 列、繁中只有 19 列,因為兩邊是**互為鏡像**的:繁中版列的是「簡中詞 → 繁中詞」(代碼→程式碼、視頻→影片),簡中版列的是「繁中詞 → 簡中詞」(使用者→用户、軟體→软件)。**各自禁用對方的用詞才是對的**,硬要列數一致反而錯。這兩個提醒了一件事:「所有語系都要跟繁中一樣」是**格式**的原則,不是把只對某語系有意義的內容硬塞進其他語系。 ## 2026-08-03 - **content** · **最後幾處內容落差補完,三語 URL 也對齊了**。上一批用「結構比對」找落差,這批改用**內容比對**(canonical 有哪些連結、mirror 是不是也有)重掃一次——這個換法很重要,因為結構數字**會有假陽性**:`stages/00-foundations` 的表格在兩個 mirror 都「不見」,但那 18 筆資源**全都在、只是改用條列呈現**,`A2` / `A3` 的 Projects 表也是同一回事(改用 `####` 標題)。真正缺的只有這些,已補:`stages/02-prompt-engineering` 的**李宏毅課程影片區塊**(en + 簡中,跟上一批補的 stage-01 影片區塊同一類、措辭刻意對齊)、`resources/README` 的「跟 Hello-Agents 的關係」說明、`resources/cookbook.en.md` 的 hello-agents Extra08(寫 Skill)。 - **fix** · **兩處其實不是「缺」,是 host 寫錯**——這是內容比對才看得出來的:`stages/06-memory-rag` 的 Pinecone reranker 連結,兩個 mirror 寫成 `www.pinecone.com`、canonical 是 `www.pinecone.io`(同一份檔案的另一處也是 `.io`);`tracks/cli/A2` 的 Anthropic CLAUDE.md 指南,mirror 是 `docs.anthropic.com`、canonical 的表格列是 `docs.claude.com`。**兩處內容都在、只是連到錯的地方**,所以任何「有沒有這段」的檢查都看不出來。已對齊 canonical。 - **content** · **`resources/schema-design-cheatsheet.zh-Hans.md` 缺的不只一條 bullet,是整個 H2 段落**。原本只打算補一條 promptfoo 參考,實作時發現簡中版比 canonical / 英文版**少一整節**(「延伸閱讀」四條:向後相容的參數改法、語意變了就開新 tool、改完 description 要重測、promptfoo eval),只補一條會放錯位置。四條一起補。 - **content** · **`examples/stage-1/04-cross-provider` 補上英文版與簡中版**——它是全 repo **最後一個沒有 mirror 檔的練習資料夾**。附帶發現一個因果鏈:正因為它沒有 mirror,`sync-language-switchers.py` 一直**跳過它**(該腳本要求至少有一個 mirror 才處理),所以它是唯一還在用舊的行內語言切換列格式的檔案。補上 mirror 之後跑 `--apply`,三個檔案一起正規化成跟其餘 21 份一致的 `
          ` 格式。**mkdocs 警告數因此從 182 降到 176**——少的 6 筆全是這個資料夾原本指向不存在 mirror 的切換列連結,確認過沒有任何新增的警告類型。 - **fix** · **6 個 DeepSeek R1 過時標記全部清掉,freshness 首次全綠**。兩處問題性質不同、修法也不同:`setup-guide`(三語)是 NVIDIA NIM 的**代管 model 清單**寫 `DeepSeek-R1`——在一份舉例用的清單上鎖版本號必然會過期,改成 `DeepSeek`;`01-llm-basics`(三語)的 Hunyuan 那列寫「**可比 DeepSeek R1 推理**」,這個對照對學習者其實有用,所以不是刪掉而是**標記成它本來的身分**:「**深度思考推理**(對標 DeepSeek R1 這條 **2025 推理基線**)」。`基線` / `基线` / `baseline` 正好是 freshness gate 自己列的合格限定詞,所以這是誠實地通過、不是繞過。 - **fix** · **Claude Code 官方文件已搬家,repo 內所有相關連結改指最終目的地**。第一手實測發現 `docs.anthropic.com` 的舊連結全部會被 301 轉址,而且**有兩條不同的對應規則**:Claude Code 文件 → **`code.claude.com/docs/en/`**(實測 `.../claude-code/memory` → `code.claude.com/docs/en/memory`、`.../claude-code/quickstart` → `.../en/quickstart`,最終頁面回 200 且確認是正確內容);API / 平台文件則是 → **`platform.claude.com/docs/en/docs/...`**。**Claude Code 那一類已全部改完**(`tracks/cli/A1`、`A2`、`resources/setup-guide` 各三語,共 12 處),改完後全 repo 這類舊連結歸零。**API / 平台那一類這批不動**——它的對應規則不同、我只實測了 2 個代表性 URL,拿 2 個樣本去改一整批正是這一輪反覆學到該避免的事,規則與證據先記在這裡,要改得逐一驗過。附帶一提:code review 抓到我原本的「修法」其實只修到一半——把 `docs.anthropic.com` 換成 `docs.claude.com` 之後**那個網址自己也還是 301**,真正的終點是 `code.claude.com`,而正確答案當時就寫在同一個 commit 的 CHANGELOG 裡。 - **fix** · **順手修掉一個指向不存在資料夾的連結**:`examples/stage-1/04-cross-provider`(三語)寫著「接 [`examples/stage-1/03-pricing/`](../) 的 PRICING dict」,但 `stage-1` 底下**只有 `04-cross-provider` 跟 `05-error-handling`**,`03-pricing/` 從來沒建過。連結本身指向 `../`(父目錄存在)所以任何連結檢查都不會報,但顯示文字點名了一個不存在的資料夾。實際的 `PRICING` dict 在 Stage 1 的計價練習裡,已改指那裡。 - **fix** · **新譯的兩個 mirror,預期輸出區塊改成各自語系**。`04-cross-provider` 的英文版 / 簡中版原本把繁中的 console 輸出**原封不動照抄**(`練習 4 通過`、`沒有對應 API key`、`風格 / 長度`),理由是「那確實是 `starter.py` 印出來的字」——但隔壁 `05-error-handling` 的既有慣例正好相反:它的 `test.py` 同樣硬寫繁中,英文版 README 仍然譯成 `🎉 All passed — retry wrapper logic correct`。`check-hans-chars` 依設計**豁免 fenced code block**(裡面本來就可能要展示 zh-TW 範例),所以沒有 gate 會抓到——這是純粹的可讀性回歸,已按既有慣例補譯。 - **process** · **這一輪也記錄一個 gate 的能力邊界**:`check-mirror-parity.py` 只數 h2 / h3 / blockquote / code fence / 圖片 / 表格列,**不數條列項、也不看連結**。所以上面那個「缺一整段條列」跟「表格儲存格連結指向錯 host」兩種情況,它**都是綠的**。這不是 bug、是它宣告過的範圍(docstring 已寫明「它只數數量、不比對內容」),但值得寫下來:**gate 綠 ≠ 內容對**,補完之後真正的驗證仍然來自跟 canonical 逐條比對。 ## 2026-08-02（第三批） - **content** · **21 個 example README 的英文版 / 簡中版補回 202 行說明區塊**。上一批量出來的那個系統性刪節,這批做完了:每份練習開頭的兩個 blockquote——「🎓 學習模式」(講 `starter.py` 是**完整解答**不是 TODO skeleton,建議先 `mv starter.py starter_reference.py`、只看 signature 自己重寫,卡 20 分鐘再對照)跟「📚 想要 chapter-length 深入版?」(指向 hello-agents 對應章節 + 該 stage 的深度教材)——繁中每份都有,兩個 mirror 一份都沒有。**42 個 mirror 檔、202 行**,現在補齊。**🎓 那行是純樣板**,所以由我統一寫好兩種語系再讓各 lane **逐字貼上**、不是各自翻譯:實測 21 個英文檔的該行 sha256 完全相同、21 個簡中檔也完全相同。📚 那塊的 3 個 bullet 則**逐檔不同**(每份練習對應 hello-agents 不同章節、外部參考也不同),按各自 canonical 翻譯。第 3 個 bullet 的 anchor 最容易錯,所以事前用 repo 自己的 `slugify` 算好每個 stage × 每個語系的正確字串再發下去。 - **tooling** · **新增 `scripts/check-mirror-parity.py` + 14 個測試——這是本輪最該做的一件事**。這個 repo 反覆出問題的**不是翻錯,是整段沒翻**:光是 2026-08 這一輪就抓到五次(catalog 的組合說明段、A2/A3 的進入條件、stages/01 的五個預期輸出區塊、stage-3 example 整條免費本地路線、以及這批的 202 行)。**現有 gate 一個都抓不到**——它們全都在驗「已經存在的東西對不對」,沒有人在驗「有沒有東西不見了」。新 gate 逐組比對三語的結構(h2 / h3 / blockquote / code fence / 圖片 / 表格列),**mirror 比 canonical 少就報**。它是**棘輪(ratchet)不是絕對檢查**:repo 本來就有合理的落差(例如英文版拿掉只有中文才有的影片清單),那些存進 baseline,gate 只在**落差變大或出現在新地方**時 fail——所以落差只能縮小、不會回頭。首次量測:**66 組、35 組有落差、總計 389**;補完這批之後是 **15 組、187**,`389 − 187 = 202`,跟補進去的行數完全對得上。 - **fix** · **順手修掉兩個 canonical 自己的連結損壞**(是 porting agent 在翻譯時發現的,不是我原本要找的):`examples/stage-3/05-error-handling/README.md:12` 的連結文字是 `[ 5 結構化錯誤回傳]`——開頭是個裸空格、掉了字(對照 cheatsheet 的「### 規則 5:error 回傳要讓 LLM 可以恢復」,掉的是「規則」);`examples/stage-3/06-schema-design/README.md:12` 更明顯,`[](...)` **連結文字整個是空的**、在頁面上渲染成一個看不見的連結。兩個都補上正確標籤,三語一致。 - **process** · **兩件值得記的事**。① `examples/stage-1/05-error-handling` 的 canonical **本來就只有 🎓、沒有 📚**,負責那個 lane 的 agent **拒絕**幫它生一個,理由是「bullet 的內容必須來自該檔 canonical,這裡沒有來源,硬寫等於在兩個 mirror 注入沒有出處的內容——而且會通過所有 gate,因為 gate 驗的是 anchor 跟語系、不是出處」。這個判斷是對的,予以採納:那個資料夾維持只有 🎓。② **這個環境裡 bash 的 `grep` 對 emoji 會靜默回報 0 筆**——本輪稍早我用 `grep -c "^## 🚪"` 掃 A2/A3,六個檔案全部回 0,當下差點據此下結論說「canonical 也沒有這一節」,實際上 canonical 有。改用文字關鍵字或 ripgrep 才正確。**任何用 emoji 當 key 的 bash grep 檢查在這裡都會假性通過**。 ## 2026-08-02（第二批） - **content** · **MCP 網址查證結果:一個都沒搬,但多了一整層該寫的東西**。把 repo 引用的每個 MCP 網址第一手查了一遍——`modelcontextprotocol.io/specification`、`py.sdk.modelcontextprotocol.io/migration`、Registry、三個 SDK repo——**全部仍然解析、沒有任何 redirect**,spec revision 也確認就是我們寫的 **2026-07-28**;Registry 的 README 仍自述「this is still a preview release and breaking changes or data resets may occur」,所以「仍在 preview」這句**維持正確、不用改**。**但查證過程發現一件本來擱置的事現在有答案了**:2026-07-28 那版把「核心協定」跟「**extension**」正式分家,而且官方 extension 現在有穩定網址與正式的官方 / 實驗分層(`ext-` 開頭 repo + `io.modelcontextprotocol/` 前綴 vs `experimental-ext-`)。**2026-07-31 那批當時刻意不寫 Apps / Tasks,理由正是「命名不一致、看不出是不是正式的」——這個理由現在失效了**,所以補一則三語**選讀**方塊到 Stage 5.2。仍然刻意**不教協定內部機制**,只留一條不會過期的規則:**extension 一律預設關閉、要雙方明確支援才生效**,看到教學叫你用某個 extension 先確認 client 支不支援,否則會靜默退回核心行為。 - **content** · **英文版 / 簡中版補回 7 處缺的內容(不只原本點名的 4 處)**。`tracks/cli/A2`、`A3` 的「🚪 進入條件」整節在兩個 mirror 都不存在,而兩份檔案自己第 9 行的「本章組成」**還寫著有這一節**;`stages/01-llm-basics` 少了 **5 個「預期輸出(樣本)」**區塊(繁中 6 個、mirror 各只有 1 個),學習者沒有「跑對了長什麼樣」的對照;`examples/stage-3/03-react-from-scratch` 的**整條免費本地 Path A(Ollama)**在兩個 mirror 都不見了、只剩付費路線,而 `examples/README.en.md` 還宣告「Three paths」。**補完之後對抗式複查又抓出 3 處**:`stages/01` 的「🎥 影片補充」三則(李宏毅 / 3Blue1Brown / Karpathy——這三則對中文讀者價值最高,卻正好是簡中版缺的)、Ex.6 的「沒裝 Ollama 也想跑」LM Studio / vLLM 退路、以及 A2 與 A3 的「💡 建議入手路徑」收尾方塊。A2 三語現在 h2 與 blockquote 數完全一致(7/7/7)。 - **tooling** · **新增 `scripts/check-hans-chars.py` + 15 個測試,補掉一個永久性盲區**。`zh-hans-localize.py` 只驗**用詞**與**引號**,字元層繁→簡是假設 opencc 在產 mirror 時就做完了——所以**當初沒轉到的字,永遠不會被任何 gate 看見**。新 gate 直接斷言真正的不變式:**用 opencc `t2s` 轉一次簡中檔必須是 no-op**。上線後立刻抓到 **10 行真殘留**(涵蓋 11 個相異繁體字),包括 `README.zh-Hans.md` 正文裡的「不要跳过 **動手練習**」、三個 stage 檔的 `邏輯` / `區別` / `選定`、`examples/README` 的 `多模態`,外加一個 `对, 应的` 的損壞字串。**同一類問題在上一批已用手工修掉 3 處**(catalog 的 `正規`、`RESOURCES` 的 `用語` ×2),所以這個類別今天總共出現 13 處——但那 3 處是靠人眼、不是靠 gate 找到的,這正是要把它自動化的理由。**兩件事值得記**:① 我先試著手寫一張「繁體字清單」,結果**又漏又錯**——漏掉 檔/個/體/專/點 這些最常見的,卻把兩邊同形的 `叫` 列進去,所以整個丟掉改用斷言;② 必須用 `t2s` 而**不是** `tw2s`——`tw2s` 會把台灣變體 么 映成 幺,拿去掃正確的簡中文字會把「什么」改成「什幺」、報出約 880 個假陽性。這兩個坑都寫成測試釘住。 - **tooling** · **新增 `scripts/check-image-locale.py` + 14 個測試**,把上一批記錄的「沒有 gate 在管圖片語系」補上。`check-locale-links.py` 的正則明確只吃 `.md` 結尾,圖片路徑完全在它視野外。新 gate 把兩類發現**刻意分開**:**該修的**(正確語系的圖檔已存在、頁面卻指向別的)一律 fail,那是一行的事;**已知缺口**(圖檔根本還沒做)列在 `KNOWN_MISSING`,因為補它要重新產生美術素材、不是一個 commit 能做完的。分開的用意是:既不會讓 CI 卡在沒人能當場修的事上,**新的錯配也不會靜悄悄混進那堆既有缺口裡**。目前 50 個圖片引用:41 正確、9 已知缺口、0 該修、0 死連結。 - **fix** · **三個 gate 會被殘留的 git worktree 汙染,其中一個因此靜默失效**。`.claude/worktrees//` 是一份完整的第二套檔案樹,而 `Path.rglob`(不像 `glob.glob`)**會走進點開頭的目錄**。實測:repo 真正的 `.zh-Hans.md` 是 **65 個**(扣掉 2 個 PROTECT),但 `rglob` 掃出來的數字是它的**兩倍多**——多出來的全是 `.claude/worktrees/` 底下的整份副本(數量會隨 worktree 當下的狀態浮動)。`zh-hans-localize.py`、`check-2026-freshness.py`、`check-anchors.py` 三個 gate 全部在掃雙份。後果不只是慢:`zh-hans-localize.py` 的 `PROTECT` 白名單是用 repo 相對路徑比對的,worktree 副本路徑不同**所以完全比不到**——也就是說**只要存在一個 worktree,被保護的檔案就自動失去保護**,這次正是它讓 gate 對著一個本該跳過的檔案報錯。freshness 的數字也從真實的 6 被灌水成 13。三個檔案都把 `.claude` 加進排除清單。(本 repo 新加的兩個 gate 用 `glob.glob`、天生不受影響——這點也實測確認過,而不是假設。) - **audit** · **這批查出、但刻意不在這批做的一件大事**:`examples/**/README.md` 的 mirror 是**系統性刪節版**。掃過全部三語檔案組之後,約 **25 個 example README** 呈現同一個形狀——繁中有 **5 個 blockquote、兩個 mirror 都是 0 個**。缺的是每份練習開頭的「🎓 學習模式」(講 `starter.py` 是完整解答、建議先改名再自己重寫的主動學習法)跟「📚 想要 chapter-length 深入版?」(指向 hello-agents 對應章節 + 該 stage 的深度教材)。換算約 **250 個 blockquote、50 個 mirror 檔案**,而且內容**逐檔不同**(每個 README 的深度教材推薦都對應不同章節),不是複製貼上能解決的。這是一個獨立批次的量,硬塞進這批只會讓 review 失去意義,所以先量出規模、寫在這裡。 ## 2026-08-02 - **fix** · **同一個「假全綠」bug 其實散在 8 個 script 裡,而且其中一個正在實際發作**。上面那條只修了 `check-locale-links.py`,複查時被反問「這個 bug class 掃過全 repo 了嗎」——沒有。`git grep` 後找到另外 5 個同樣拿**絕對路徑**比對排除目錄的 script:`check-anchors.py`、`check-2026-freshness.py`、`check-catalog-counts.py`、`check-links.py`、`refresh-stars.py`。其中 **`check-catalog-counts.py` 是正在發作的**:它的排除集合裡直接寫了 `.claude`,所以在 `.claude/worktrees/` 底下的 checkout,它掃到的 markdown 是 **0 / 248 個**,卻照樣印出 `✓ Catalog counts consistent` 退 0——一個 **blocking** gate 完全空轉。修完後它實際比對到 **39 條**數量宣稱。**CI 沒被影響過**(runner 路徑 `/home/runner/work/...` 不含任何被排除的路徑段),所以這純粹是**本機盲區**——而本機正是提交前唯一會跑它的地方,等於這些 gate 對 worktree 工作流從來沒真的把關過。順帶效果:`check-2026-freshness.py` 修好後在本機浮出 6 處既有的 `DeepSeek-R1` 過時引用(CI 的排程 job 本來就看得到、是 `--warn-only`),屬既有內容債,不在這批範圍。`check-catalog-counts.py` 那個內嵌的排除集合也改成具名常數 `SCAN_EXCLUDE_DIRS`,免得再默默飄走。**合併 main 之後又冒出第 7 個**:`check-mirror-parity.py` 同樣拿絕對路徑比對,在 worktree 下掃到的 trio 是 **0 / 67**——它沒有靜默通過,是因為 main 幫它加了「trio 數不得下降」的 ratchet,把盲區變成一個明確的失敗(`complete trios dropped 67 -> 0`),**這正是每個 walker 都該有的設計**。它之所以躲過我第一版的原始碼掃描,是因為它的集合叫 `SKIP_DIR_PARTS` 而不是 `EXCLUDE_DIRS`,而我當初的正則要求該行含 "EXCLUDE"——**用命名當偵測條件本身就是錯的**,現在改成:任何對絕對路徑做 `.parts` 成員檢查一律視為可疑,不管那個集合叫什麼。**然後第 8 個又用第三種寫法躲過去**:`zh-hans-localize.py` 寫的是集合交集 `SKIP_PARTS & set(p.parts)`,不是 for 迴圈,所以廣義後的正則還是看不到——而它**正在發作而且沒有 ratchet 保護**:掃到 **0 / 68** 個 zh-Hans 檔卻印出 `✓ zh-Hans localization clean — no drift`,一個守 zh-Hans 品質的 blocking gate 什麼都沒檢查。修完掃到 66 個(另 2 個在 PROTECT 清單)。**三種語法表達同一個 bug,證明「猜哪種寫法危險」這條路走不通**,所以偵測改成反向:**所有 `.parts` 使用一律標記為可疑**,安全的必須自己說明理由——同行呼叫 `.relative_to(...)`,或加上 `# abs-parts-ok: <原因>` 註記。目前兩處合法豁免都是 `glob.glob(root_dir=REPO_ROOT)` 走訪,本質上就回傳相對路徑。八個 gate 現在實際掃描量:catalog-counts 39 條、mirror-parity 67 組、image-locale 50 個引用、zh-hans-localize 66 檔——全部從 0 或盲區恢復。 - **fix** · **既有的 `check-locale-links.py` 會回報「假的全綠」,而且是我在寫新 gate 時撞出來的**。它的 `EXCLUDE_DIRS` 比對的是 `fp.parts`——也就是**絕對路徑**的每一段——所以只要 checkout 本身位在任何一個被排除的目錄名底下,整個 repo 的檔案都會被跳過,然後印出 `✓ All mirror links point at their own locale.` 退 0。實際觸發條件很日常:在 `.claude/worktrees//` 裡開 worktree 工作時,每個檔案的絕對路徑都含 `.claude`,於是 **67 個 `.en.md` + 簡中鏡像一個都沒掃到**。CI 之所以一直是對的,純粹因為 runner 的 checkout 路徑 (`/home/runner/work/...`) 剛好沒有任何被排除的路徑段——換句話說**這個 gate 在本機從來沒有真的跑過**,而本機正是大家提交前唯一會跑它的地方。兩個 gate 現在都改成比對「相對於 repo root」的路徑。修完後 link gate 的 0 是真的 0(既有 14 個測試全過),新的 image gate 則從 0 變成正確回報 9。**一個會靜默通過的 gate 比會失敗的 gate 更糟**,這條由 `scripts/test_repo_scan_excludes.py` 釘住——除了逐個 walker 的行為測試,還有一道**原始碼層掃描**,任何 script 只要再寫回「拿絕對路徑比對排除目錄」就直接讓 build 失敗,擋掉第七次復發。 - **content** · **9 個缺的語系變體圖全部補齊,圖片語系錯配歸零**。5 張圖缺的 9 個變體(`multi-llm-delegation-composition.zh-Hans` + `rag-pipeline-overview` / `chunking-strategies` / `teacher-ai-use-cases-overview` / `teacher-ai-classroom-use-cases` 各缺 `.en` + `.zh-Hans`)已全數產出,9 處引用同步改指自己語系,gate 從 9 降到 0。作法是**委派 Codex CLI 用它內建的 image-gen 工具生成**,每張都以繁中原圖當風格參考,brief 一律附「誠實失敗條款」(文字不對就不准存檔、如實回報哪張沒做成、禁止拿 PIL/SVG 硬畫充數)。順手修掉繁中原圖帶進來的 3 個既有錯字:`hybird`→`hybrid`、`Rewrite qustion`→`Rewrite question`、`Learning form error`→`Learning from error`。**接著把那 4 張流程圖整組升級成 repo 主力的插圖風格**——它們原本是 draw.io / Mermaid 匯出的素面方框圖,跟另外 20 張帶線條 icon、雙語標籤、分色卡片的 house style 明顯不同調,是 repo 裡的異類;因為三語必須一致,升級連繁中原圖一起重產,副檔名同時由 `.jpg` 改為 `.png`(house style 那批都是 png,線條插圖加密集文字用 jpeg 會有壓縮雜訊),`stages/06-memory-rag` 與 `branches/for-teacher` 共 12 處引用一併更新,舊 `.jpg` 移除。用長寬比當客觀對齊指標,五組圖三語差異現在全部 < 0.05。**未竟的部分照實記**:`teacher` 兩組(6 張)完整做到 house style,但 `rag-pipeline-overview` 與 `chunking-strategies` 兩組(6 張)四次嘗試都在「有 house style 但有瑕疵」與「乾淨但退回素面」之間擺盪,最後收在乾淨、文字正確、三語一致的淺色卡片版,**視覺等級不如 teacher 那兩組**;原始 `.jpg` 仍在 git 歷史可還原,細節與後續建議寫在 `resources/diagrams/locale-variant-prompts.md`。 - **process** · **「delegate 回報 success」不等於做對了——這批四次假成功**。每一張都是委派者自己開圖驗收(不是看 `.result.json` 的 status),抓到四件事:① `chunking-strategies.zh-Hans` 圓柱體殘留繁體 `種`/`純`,回報 `success`;② 重產修好 `純`→`纯` 但 **`種` 仍是繁體**,又回報 `success`;③ 要求「只修四角裝飾方塊與文字溢出」時,它擅自把 `RAG Fusion` 改名重設計,還引入新缺陷(`store` 標籤壓在方框上、`.en` 圓柱內文字被上下裁切);④ 最後一次**根本沒改寫任何檔案**(時間戳未變),卻在 summary 列出一串「已執行的驗證指令」,看起來像做完了。**兩個可操作的教訓**:一是 **CJK 繁簡差異在縮圖尺寸下看不出來**——`种`=`禾`+`中`、`種`=`禾`+`重`,可靠做法是裁切放大 3-4 倍再拿 repo 裡已知正確的同一個字當對照(這裡用 `rag-pipeline-overview.zh-Hans` 的 `各种资料`);二是**「改圖」比「重新生成」更容易失控**,叫它「只修這兩點」兩次都超出範圍,指定重新生成並附完整規格反而可靠。跟本檔上面那條「結構對齊不等於內容對齊」同一類:只回報「做完了」的複查等於沒複查。 - **tooling** · **圖片語系 gate:跟 main 上的同類 gate 收斂成一支**。這條分支原本自己寫了 `check-locale-images.py`(RETARGET / MISSING 兩類 + `--apply` 自動改引用),但合併時發現 `main` 已經先有功能等價的 `check-image-locale.py`(白名單式 `KNOWN_MISSING`,新缺口會擋 build),而且已接進 CI。**兩支併存等於每次 CI 跑兩次同樣的檢查**,所以撤掉本分支這支,保留 main 的。本分支真正不可替代的產出是那 13 張圖與 6 個 script 的 false-green 修復,gate 本身是重複投資。撤除時把唯一會流失的東西留下來:`check-locale-images.py` 的測試裡有 EXCLUDE_DIRS 相對路徑的 regression,而 main 的 `test_image_locale.py` **零覆蓋**這個 bug class——已改寫成獨立的 `scripts/test_repo_scan_excludes.py`,涵蓋範圍比原本更廣(7 個 walker + 原始碼層防再犯)。**這次收斂確實損失一項能力,照實記**:被撤掉那支有 `--apply` 可以把「指錯語系」的引用自動改好,main 這支只偵測不修正——下次遇到失敗要手改 markdown。目前 fixable 是 0,影響是未來式。順帶把 main 的 `KNOWN_MISSING` 白名單**清空**:那 9 筆全指向已經不存在的 `.jpg` 路徑(圖都補齊且改成 `.png` 了),是永遠不會命中的死資料;清空後任何新缺口會直接擋 build,比留著 9 筆過期豁免更嚴格。對應的測試從「必須是 9 筆」改成「必須是空的」。 - **docs** · **這批圖的生成流程與教訓寫成文件**:[`resources/diagrams/locale-variant-prompts.md`](resources/diagrams/locale-variant-prompts.md)。上一批記錄「圖是貼 prompt 到 ChatGPT image-gen 手動生成、repo 內沒有 source 檔」——這份把那個缺口補上,但**實際做法跟原本設想的不同**:不是貼到 ChatGPT 網頁,而是**委派 Codex CLI 的內建 image-gen 工具**,brief 裡指定 repo 內既有圖當風格參考(Codex 能直接讀圖檔)並附完整逐字文字表,`.ai/` 下留 brief 當稽核紀錄。文件內容包含:五張圖各自的處理結果、風格基準檔、四次假成功的完整清單、以及三個可操作的驗收方法(CJK 繁簡要裁切放大＋已知good對照、長寬比當客觀對齊指標、「重新生成」比「改圖」可靠)。**未竟事項也照實寫在裡面**——`rag-pipeline-overview` 與 `chunking-strategies` 兩組視覺等級不如 teacher 兩組,含後續再挑戰的三個建議與「原始 .jpg 仍在 git 歷史可還原」。順帶查出繁中原圖本身有 3 個既有拼字錯誤(`hybird` / `Rewrite qustion` / `Learning form error`),新圖已全部修正。**時效性另記一筆**:`multi-llm-delegation-composition` 把中間 lane 標成 `gemini-delegate`,那個 skill repo 已於 2026-07 封存,但圖說明的概念沒過時——緊接在圖後面那段仍在教三方分工,repo 的立場是「workflow 還能用、只是 skill repo 封存了」,所以是**概念現行、標籤過時**;這批的 `.zh-Hans` 忠實比照現有兩張(先解決簡中讀者看到繁體字的當下問題),「三張一起改標成 Gemini CLI」列為後續選項。該圖畫了廠商 logo,牴觸 `concept-prompts.md` 自己的禁令——既有不一致,不是這次造成的。 - **fix** · **簡中版對貢獻者講的收錄政策,跟繁中/英文是相反的**(本批最重要的一項)。`mcp-skills-catalog.zh-Hans.md` 的開頭「收錄原則」跟結尾「維護備註」兩段,是 rewrite 前的舊版被留下來,而且不是翻譯腔差異、是**語意相反的政策**:簡中寫「**★ 100+ 起跳**:除非是官方,社群 repo **至少 100 stars 才收录**」,繁中/英文寫的是「**stars 看一下就好**……但『小眾但好用』也歡迎送 PR 解釋為什麼要收」;簡中寫「過時的會在**每季 review** 時更新」「**stars < 1k 且 < 3 个 entry 的分类先别开**」,繁中/英文寫的是「**有空 review 一輪就好——不用排定期程**」「新分類**有 1-2 個值得收的就可以先開**」;簡中還缺了整句定調的「**不是 SLA,是「能做就做」的方向**」跟第 5 條「用詞、格式不一致 → 不要苛求,PR 進來能讀懂優先」,標題也從「給未來想幫忙的人」變成較生硬的「给未来的 maintainer」。**實際影響是會勸退人**:一個讀簡中的貢獻者會以為自己的 repo 沒有 100 stars 就不用送 PR,而專案的真實立場正好相反。三語現在一致。同段另修:`为什么 JIA`(拼音沒轉回中文的損壞字串)→ `为什么要加`;`style-guide` 連結的**顯示文字**還寫著繁中檔名(連結本身指向簡中);`tavily-mcp` 的推薦度少了註記「(新手第一選擇)」,補回後三語帶註記的推薦度儲存格都是 49 個。 - **fix** · **簡中版 style-guide 有大約 200 行在網站上根本沒顯示**。`resources/style-guide.zh-Hans.md` 的 entry 範本裡有一組**巢狀 code fence 沒有跳脫**——繁中/英文都寫成 `\`\`\`bash`(跳脫過),簡中是裸的 ```` ```bash ````,於是內層 fence 提早關掉外層,從第 49 行到第 246 行(「必填字段」一路到「6. Stage 页面模板」)整段被吞進同一個 code block。用 python-markdown 實測:修前簡中版只渲染出 **7 個 h2 / 8 個 h3 / 0 個表格**,修後是 **12 / 17 / 5**,與繁中完全一致。原始碼裡的標題數三語一直都是 23,所以任何只看原始碼的檢查都看不出問題——這也是它能存活這麼久的原因。 - **content** · **簡中版補回缺的內容,catalog 三語終於真的對齊**。上一批收尾時已知簡中版少了「三個 skill 的組合」這個說明段落,這次一併把整份 catalog 的三語結構比對做完,實際找到三處而不是一處:① **缺整個說明段落**——`## 14. Multi-LLM Delegation Skills` 開頭那段「這 3 個 skill 是設計成一起用的」連同分工圖,繁中/英文都有、簡中沒有;② **兩個條目的翻譯是舊的短版**——`codex-delegate` 跟 `gemini-delegate-skill` 在繁中/英文各有 `何時用` / `何時不用` 兩行(全 catalog 76 個條目裡只有這 2 個有這兩行),簡中版整個缺,而且 `適合誰` 那行是語意較弱的舊譯;③ **兩條多出來的分隔線**——簡中版在 `discord-mcp` 跟 `mcp_excalidraw` 後面各多一條 section 內的 `---`,繁中/英文都沒有,結果只有簡中讀者會看到兩條莫名其妙的水平線。修完後三語的 `---` 數量都是 19、條目 body 行數零落差。標籤沿用 corpus 既有的 `何时用` / `何时不用`(全 repo 已用 22 / 19 次),不自創新寫法。 - **content** · **這批的已知缺口:簡中版的分工圖沿用繁中圖檔**。`resources/diagrams/` 的慣例是有做語系變體的圖就做滿三個,但 `multi-llm-delegation-composition` **只有 `.png`(繁中)跟 `.en.png`,沒有 `.zh-Hans.png`**——清點後它是**唯一一張只做了三分之二的圖**(20 張三個語系齊全、6 張是本來就只有單一語系的素材如 `.jpg` 教學圖,只有這張卡在 2/3)。附帶確認:那 20 組的三個變體都是不同圖檔、不是複製同一張改檔名,所以缺的這張沒辦法用複製混過去。圖裡有三處繁中字串(「機械式批次」「長 context」「平行時用」),簡中讀者看得懂但不是正確在地化。這些圖是把 prompt 貼到 ChatGPT image-gen 手動生成的、repo 內沒有 source 檔(`resources/diagrams/concept-prompts.md` 也只涵蓋 Stage 7.5 那三張),所以**沒有辦法在這批裡忠實重製**——與其生一張風格不一致或 CJK 文字糊掉的圖冒充,先讓簡中段落指向繁中圖檔,缺口寫在這裡,補圖列為後續手動工作。 - **audit** · **順著上面那個缺口查下去,發現它不是單一個案而是一整類(9 處)**。目前**沒有任何 gate 在管「圖片素材的語系」**——`check-locale-links.py` 只驗 `.md` 連結、正則明確只吃 `.md` 結尾,圖片路徑完全在它的視野外。全 repo 掃過之後,除了這次的 composition 圖,另有 **8 處既有的錯配**:`stages/06-memory-rag` 的 `rag-pipeline-overview.jpg` 與 `chunking-strategies.jpg`、`branches/for-teacher` 的 `teacher-ai-use-cases-overview.jpg` 與 `teacher-ai-classroom-use-cases.jpg`,這 4 張**只有繁中一個版本**,卻同時被英文版與簡中版頁面引用——而且 **alt text 有在地化、圖檔沒有**,所以讀者看到的是「英文說明配一張整張都是繁體字的圖」。這 8 處是既有問題、不是這次改動造成的,補圖同樣需要手動重製素材,**這批不動**,先把清單記在這裡免得又被忘掉。 - **content** · **順手清掉 3 個殘留的繁體字,並發現 gate 的盲區**。簡中檔裡混著沒轉乾淨的繁體字:`mcp-skills-catalog.zh-Hans.md` 的「等**正規** MCP 出现」、`RESOURCES.zh-Hans.md` 的「**用語**说明」與「**用語**小词典」——都是繁體字卡在一個其餘已簡化的詞裡,轉檔時漏掉的。**`zh-hans-localize.py --check` 對這類完全無感**:它管的是**用詞**(台灣詞彙 → 大陸詞彙)跟**引號**,字元層的繁→簡是假設 opencc `tw2s` 在產生 mirror 時就做完了,所以「當初沒轉到的字」永遠不會被任何 gate 看見。全 repo 掃過確認只有這 3 處。**刻意不動**的兩處:`README.zh-Hans.md` 的 shields.io badge 標籤 `語言`——那整塊 badge 區在三個語系的 README 裡是**逐字相同**的共用頁首,只改簡中版反而會製造出這批正在消滅的那種跨語系落差;還有 `resources/style-guide.zh-Hans.md` 的繁體字,那是「不要這樣寫」對照表的左欄,本來就該是繁體。 - **process** · **值得記的一件事:錯誤的偵測方式撞出了真的 bug**。我一開始用「條目 body 行數差」當作翻譯落差的偵測訊號,它報了 4 個條目,其中 2 個(`discord-mcp` / `mcp_excalidraw`)其實是我的 parser 把結尾的 `---` 也算進 body 的假陽性 —— 但去查為什麼只有簡中版多那一行,才發現那兩條 `---` 是**真的多出來的、只存在於簡中版的分隔線**。假陽性本身是雜訊,追下去的原因不是。另:目前**沒有任何 gate 會抓這一類「某個語系少一整段」的落差** —— `check-anchors` 只驗 anchor 解析得到、`check-locale-links` 只驗連結指向自己語系、`zh-hans-localize` 只驗用詞、`check-catalog-counts` 只驗數字,三語的**結構**對不對齊沒有人管。mkdocs 建置警告數維持 **182**(與改動前相同),且無任何警告指向新加的圖片路徑。 - **process** · **更值得記的一件事:我自己的檢查方法對本批最嚴重的兩個問題完全無感**。我用的三個訊號——條目 body 行數差、條目順序、`---` 數量——都是**結構性**的,而政策相反的那兩段(收錄原則 / 維護備註)結構完全對得上(段落數、bullet 數看起來都合理),style-guide 的 fence 問題在**原始碼層**也看不出任何異常(三語標題數都是 23)。兩者都是靠**對抗式複查**抓到的:讓複查者的任務不是「確認這批做完了」,而是「**推翻『已經對齊』這個宣稱**、而且必須引用原文當證據」。兩個複查角度(逐條目 / 非條目區塊)都成功推翻。教訓很具體:**「結構對齊」不等於「內容對齊」**,而一個只會回報「看起來沒問題」的複查等於沒複查。 - **audit** · **另外 4 處同類缺口,這批不做但先記錄**(需要翻譯與內容重製,不是機械修正):`tracks/cli/A2-cli-workflow` 與 `A3-cli-production` 的英文版/簡中版**都缺整個「🚪 進入條件」章節**,而兩份檔案自己的「本章組成」那行**還寫著有這一節**——文件承諾了一個不存在的段落,A3 還是 Track A 的收尾章、等於最難那章的先修條件對非繁中讀者是隱形的;`stages/01-llm-basics` 的英文版/簡中版少了 **5 個「預期輸出(樣本)」範例區塊**,學習者沒有「跑對了長什麼樣」的對照;`examples/stage-3/03-react-from-scratch` 的英文版/簡中版**整條免費本地 Path A(Ollama)不見了**、只剩付費的 Anthropic 路線,而 `examples/README.en.md` 還宣告「Three paths」。 --- ## 2026-08-01 - **content** · **MCP catalog P2 收尾:計數同步 + 星數刷新**(tri-locale)。catalog 實際有 **76** 個條目但到處還寫「65+」——**36 處、橫跨 32 個檔案**(catalog 導言、README ×2 個位置、RESOURCES、resources/README、四條 branch、Stage 5.2、Track A3,以及兩份尚未寄出的 outreach 草稿),全部改成 76。TOC 分項數也有兩處錯(§8 設計 3→**4**、§11 中文圈 9→**11**),修正後**分項加總 76 = 實際條目數 76**(先前只有 73)。**這個數字我連錯三次**:① 第一輪用逐檔手改只清 8 處就當做完;② 改用全域 grep 後數字對了,但 `grep "^### \["` 漏掉唯一一筆**沒有方括號連結**的條目(`YIELD INTELLIGENCE MCP`),導致總數少算 1、還把 §12 從正確的 4 誤改成 3;③ 過濾說明段落的 regex 只認 `composition` 而漏掉英文版的 `compose`。三次都是 code-reviewer 抓到的。另:`intuitek-ace` 條目寫「已列入 **Anthropic 官方** MCP Registry」—— Registry 自 2025-12 起由 Linux Foundation 的 Agentic AI Foundation 管理,拿掉「Anthropic」;cookbook 的 `claude mcp add` 補上 `--` 分隔符與 `--scope project`(前者讓帶 flag 的 server 參數不被吃掉,後者產生可簽入的 `.mcp.json`、團隊共用)。並用修好的 star bot 跑了一次刷新:**40 筆星數更新、19 個檔案,star bot 沒有異動任何 `.github` 檔**。 - **tooling** · **新增 `scripts/check-catalog-counts.py` + blocking CI gate**,終結上面那個數字問題。它從檔案**算出**真實條目數,再據此檢查三件事:每個 Index 分項數 vs 該節實際條目、Index 加總 vs 總數、以及散落各處的「NN+ MCP servers」宣稱。「什麼算一個條目」用**顯式標記**而不是猜:純說明性的 `###` 段落要在上一行加 ``(已標在「三個 skill 的組合」上),因為看得見的 opt-out 勝過會漏掉邊界情況的啟發式規則。**這個 gate 自己也差點重演同樣的錯**:第一版的 headline regex 要求數字後面緊接固定關鍵字,但中文散文常插字(「76+ 個**常用**整合」、「76+ **integration** catalog」),結果 36 處宣稱只驗到 17 處 —— gate 會綠著讓文件漂移,正是它要防的那件事。改成「認 `NN+` 這個形狀」後,gate 每次跑會驗 **39 個宣稱點**(上面修掉的 36 處,加上 3 處本來就寫對的),並加了 11 個測試(含負向測試:故意寫錯數字必須被抓)。 - **tooling** · **freshness gate 新增兩條 MCP 規則**。原本規劃是把 MCP spec revision 加進 `current_frontier_models`,但查證後發現**那個區塊根本不被 `check-2026-freshness.py` 讀取**(只是給維護者看的參考),所以改成加在真正會生效的 `stale_patterns`:① MCP Python SDK v1 API(`from mcp.server import Server` / `@app.list_tools()` / `@app.call_tool()`)—— 這正是 2026-07-28 v2 破壞性改版後會讓教材失效的寫法;② 未鎖版本的 `pip install mcp`。兩條都設了 qualifier(`v1` / `legacy` / `遷移` / `裸寫` 等),所以在警告文字裡**引用**錯誤寫法不會誤報 —— 實測零誤報、flag 數維持 6(皆為既有的 DeepSeek R1)。 - **content** · **英文版 / 簡中版不再把讀者丟回繁中頁**(111 個連結、37 個檔案)。`.en.md` / `.zh-Hans.md` 裡有大量連結直接指向繁中 canonical(例如 `README.en.md` 的 `[CONTRIBUTING.md](CONTRIBUTING.md)`、`index.en.md` 首頁 13 條),即使同語系的檔案就在旁邊 —— 英文讀者點下去會落到讀不懂的頁面。改成指向自己語系的檔案。**刻意保守**:同語系檔案不存在時不動(繁中連結才是對的)、語言切換列不動(它本來就該跨語系)、fenced code 內不動。**mkdocs 建置警告數改動前後皆為 182、零新增警告類型**,確認網站不受影響。 - **tooling** · **新增 `scripts/check-locale-links.py` + CI blocking gate**,防止上面那類連結再累積。既有的 gate 都抓不到它:`check-anchors` 只驗目標解析得到、`sync-language-switchers` 只管切換列。附 12 個 stdlib 單元測試(含一個直接把 repo 現況當測項)。**第一次跑時我把它寫錯了**:它連帶重寫了帶 anchor 的連結,而標題是翻譯過的 —— 繁中 anchor 在 `.en.md` 裡不存在,於是產生 **5 個死連結**(被 `check-anchors` 當場擋下)。修法是加第 5 條規則:帶 anchor 的連結必須先確認該 anchor 在目標語系檔裡真的存在,否則維持 canonical;並補一個 regression test 把這個教訓釘住。 - **docs** · 順手把 12 個連結的**顯示文字**對齊讀者語系(`[foo.md](foo.en.md)` → `[foo.en.md](foo.en.md)`)。註:先前口頭估的「119 處」是誤算 —— 那個 grep 沒排除反引號寫法,把 107 個本來就正確的連結也算進去了。 ## 2026-07-31 - **content** · **Stage 5.2 補上 MCP 採用規模數據**(tri-locale,一句話)。Anthropic 在[官方公告](https://claude.com/blog/bringing-mcp-2026-07-28-to-claude)給出可引用的數字:MCP 的 SDK **月下載量超過 4 億**(今年約成長 4 倍)、Claude connectors 目錄收錄 **950+ 個 MCP server**。放在「MCP 是什麼」段落之後,用來回答讀者的「這值得學嗎」。**同一篇公告裡刻意沒採用的部分**:無狀態核心、Apps / Tasks extension 框架、企業託管 auth、observability dashboard、MCP tunnels —— 那些是協定層與 connector 平台的事,初學者無感;而且 Anthropic 對 Claude 產品端的支援時程只寫「soon」、沒有日期,也沒說既有 server 的相容性或遷移,寫進教材只會是一句空話。Apps / Tasks 是否算正式官方 extension 暫不寫入教材(此判斷來自另行查閱 spec repo 時觀察到的命名不一致,非本則公告內容,故未引用)。 ## 2026-07-30 - **content** · **MCP 教材修復:SDK v2 破壞性改版讓唯一的 MCP 練習跑不動了**(tri-locale,第一手查證 PyPI + 官方 migration guide)。官方 Python SDK 於 **2026-07-28 發布 v2.0.0**:`FastMCP` 改名 `MCPServer`、低階 `Server` 的 handler 從 decorator 改成建構子參數。cookbook 的 `pip install mcp` **沒鎖版本**,讀者現在會裝到 2.x,然後在 `from mcp.server import Server` / `@app.list_tools()` 那行直接 `AttributeError` —— 跟 2026-07-17 那次 Kimi K2 停用 model ID 是同一類失效。修法:程式碼改寫成官方 v2 形狀(`from mcp.server.mcpserver import MCPServer` + `@app.tool()` + `app.run(transport="stdio")`,從約 40 行縮到約 10 行)、安裝行鎖 `"mcp>=2,<3"` 並附 v1 逃生門 `"mcp>=1,<2"`(v1.x 仍在維護模式)、加一則說明 v2 為何變短(type hints 自動產 inputSchema、docstring 當 description、回傳值自動包裝)。Stage 5.2 內另一處未鎖版的 `pip install mcp` 一併補上。三語程式碼區塊 byte-identical 且 `ast.parse` 通過。 - **content** · **MCP 其他事實修正**(同批,tri-locale):**transport 從「三種」改為兩種** —— 只有 stdio 與 Streamable HTTP,舊的 HTTP+SSE 早在 **2025-03-26** 那版 spec 就 deprecated(glossary + cookbook pitfall 兩處都寫錯);**「20+ 官方 servers」→ 實際 7 個 reference server**(everything / fetch / filesystem / git / memory / sequentialthinking / time),**github 與 sqlite 已移到 `servers-archived`**,並註明官方 README 自述這些不是 production-ready;Stage 8 的 Browser MCP 連結從 `modelcontextprotocol/servers` 改指正確的 `microsoft/playwright-mcp`;FastMCP 連結更新為 `PrefectHQ/fastmcp`(★27k、Apache-2.0)並加一句消歧義 —— 它是**獨立第三方套件**,跟官方 SDK 內部改名為 `MCPServer` 的 class 不同;Registry 補上「仍在 preview」;glossary 補「MCP 已於 **2025-12-09** 捐給 Linux Foundation 的 Agentic AI Foundation」(第一手:blog.modelcontextprotocol.io + Anthropic 公告)。另指名目前 spec revision 為 **2026-07-28**,並教讀者「MCP 用 `YYYY-MM-DD` 標版本、要先確認自己在哪一版」這個不會過期的 meta-skill。 - **content** · **刻意不做的部分**(研究後的範圍決定,非遺漏):2026-07-28 那版 spec 的協定層內部機制(連線 / 握手模型、server 端 RPC、擴充提案等)**全部不寫** —— 那些是 SDK 實作者與 gateway 作者的義務,寫 `@app.tool()` 的讀者一輩子打不到,教了只會讓章節變長又快過期。**也不補 auth 章節**:MCP 的授權模型在 2025-2026 間多次改版,教一個可能半年後就過時的機制,對初學者是負資產 —— 本 repo 原本零覆蓋反而讓我們不必追。只在 cookbook pitfall 加一句 spec 明文:**stdio server 不需要 OAuth**,憑證從環境變數取。 ## 2026-07-27 - **content** · **Claude Opus 5 上線,全 repo 模型陣容更新**(tri-locale,第一手查證 anthropic.com/news/claude-opus-5 + platform.claude.com docs)。Opus 5 於 **2026-07-24** 推出:`claude-opus-5`、1M context、128k max output、**$5/$25(與 Opus 4.8 同價)**、adaptive thinking、knowledge cutoff May 2026;官方 docs 明示「複雜 agentic coding 與企業工作從 Opus 5 開始」,Anthropic 宣稱它「接近 Fable 5 的能力、一半的價格」。**Opus 4.8 未被 deprecated**(仍 Active、$5/$25,官方 docs 移入 Legacy models 摺疊區),所以這是「推薦起點轉移」而非可用性變更;階層維持 Fable 5(Mythos-class,最強)> Opus 5 > Sonnet 5 > Haiku 4.5。更新 Stage 1 旗艦表 + 必修閱讀、glossary(Context Window / Frontier Model / Computer Use)、CLAUDE.md、examples/README 定價表、Stage 2/6/7/7.5/8 的旗艦宣稱與 model pick-list、`scripts/freshness-models.yml`。**刻意不做的兩件事**:① 所有實測 benchmark 維持原歸屬(SWE-bench 88.6%、Terminal-Bench、OSWorld 2.0 20.6% 都是在 **Opus 4.8** 上量測,改掛 Opus 5 就是捏造),Stage 7 leaderboard 改為加註說明而非換數字;② **不寫入 Opus 5 的 benchmark 數字**(Frontier-Bench / CursorBench / ARC-AGI 3 全為 Anthropic 自published、無第三方複現)。Dynamic Workflows 的首發歸屬仍留在 Opus 4.8(歷史正確)。順手修好 Stage 1 可執行計價範例的既有 bug:`PRICING` dict 有 4 個 model 但預期輸出只列 3 行,補上 `claude-fable-5 $2.5400`。 - **content** · **glossary 新增 Graph Engineering(圖工程)詞條**(§7 用詞 / Buzzword,tri-locale)。2026-07 起這個詞在中文圈流傳,詞條給讀者一個誠實的答案:它指的是**執行流程圖(control graph),不是 GraphRAG 的知識圖譜檢索**;而且**是舊技術的新名字,不是新技術**——LangGraph 自 2023 就這樣運作,LangChain 官方也直言這不是新想法,Anthropic / Google ADK / Microsoft Agent Framework 三家官方文件都不使用這個說法(各自稱 *dynamic workflows* / *graph-based workflow(s)*)。詞條把讀者導向真正該學的 [Stage 4 multi-agent pattern](stages/04-agent-frameworks.md) 與可執行的 `examples/stage-4/03-graph-workflow/`。**刻意不開新章節**:它與本 repo 既有的「Prompt→Context→Harness 三層正交」主張衝突(graph 是第 3 層的實作形狀、不是新的關注單位),且與 Stage 7.5「人不畫 DAG、是 agent 寫 code」的既有分析相牴觸;新章節成本有實測(上次新增 Stage 7.5 花了 40 commits / 134 檔案 / 約 2 個月,並被迫在 `check-stage-template.py` 開例外)。重評觸發條件已寫在研究紀錄:需同時滿足「非 LangChain 的第一方正式文件採用該詞」+「Wikipedia 或 HF glossary 收錄」+「舉得出 Stage 4/7 畢業生做不出來的具體 artifact」。 ## 2026-07-20 - **tooling** · **`refresh-stars.py` now excludes `.github/`** + clean weekly star refresh applied. The weekly star bot was scanning `.github/` outreach drafts and corrupting them: it mis-associated this repo's own URL with nearby *prose* star counts and overwrote historical launch stats + other repos' numbers with this repo's current count (the week's auto-PR #71 had 7 such false edits, e.g. `Langchain-Chatchat ★37k` → `★4.6k+`). Added `.github` to the scan exclude list + a regression test; re-ran the fixed bot to apply **218 legitimate catalog ★-count updates** (tri-locale ★ parity verified, 0 `.github` touched). #71 closed as superseded (5e3887e). ## 2026-07-18 - **tooling** · **Freshness gate now scans mirror locales** (salvaged from a background chip): `check-2026-freshness.py` scans `.en.md`/`.zh-Hans.md` (not just the zh-TW canonical), the DeepSeek regex catches the space-form `DeepSeek R1`, CJK `基線/基线` qualifiers are recognized, plus 12 unit tests and a `freshness-tests` CI job. En route, corrected a fabricated model fact in two places (a rule note + a live `setup-guide.md` line): DeepSeek-R1 was described as "superseded by R2 in 2026-03" — **R2 never shipped** (verified first-party); the reasoning capability shipped in DeepSeek V4 (2026-04) (58cfb99). ## 2026-07-17 - **docs** · **Homepage note for the PR link-audit bot** (README `🤝 如何貢獻 / Contributing` section, tri-locale). A `🤖` callout tells contributors that a new `github.com/owner/repo` link on a PR gets an automated stars/license/archived/last-push comment checked against `§策展標準` — advisory, never blocks, maintainer decides. Honestly discloses the v1 fork-PR limitation (runs on maintainer-branch PRs only) rather than over-promising coverage; placed in Contributing, not the learner hero. Also fixed a pre-existing tri-locale parity slip the reviewer caught in the same section — `README.zh-Hans.md`'s maintainer bullet linked `CONTRIBUTING.md` + style-guide instead of `CONTRIBUTORS.md` like the TW/EN siblings (5f92d04). - **tooling** · **PR link-audit bot** (`scripts/pr-link-audit.py` + `.github/workflows/pr-link-audit.yml`, a stdlib unit-test suite wired into lint CI). When a PR *adds* a new `github.com/owner/repo` link, a GitHub Action posts a sticky comment with that repo's stars / license / archived / last-push, checked against CONTRIBUTING `§策展標準` (maintained ≤6 months, clear license, not archived) and flagging archived / stale / unlicensed rows. **Advisory only — never fails the build** (star counts have no hard bar; self-promo / teaching-value stays a human call). No LLM, no pip deps: `gh` CLI + stdlib Python. Diff-scoped to genuinely new repos (present on `+` lines, absent from `-`), so re-formatting an existing entry doesn't re-trigger it. **Verified end-to-end on a real throwaway PR** (#68, since closed): the Action triggered, posted its comment, sticky-PATCH-updated it on a 2nd push (same comment, no duplicate), flagged archived / stale(23mo) / no-license correctly, and both runs stayed green — plus offline `--diff-file` smoke + a stdlib unit-test suite (tracked in `.github/TESTING-STATUS.md`). **v1 audits same-repo (maintainer) branches only** — fork PRs get a read-only `GITHUB_TOKEN` and are skipped; closing that needs the two-workflow `pull_request` → `workflow_run` pattern, deferred until fork coverage is wanted. - **content** · **P2 benchmark refresh — OSWorld v1 → 2.0** (Stage 7 leaderboard row + Stage 8 milestone bullet, variance table, dataset row, mastery checklist; tri-locale). The stale "OSWorld 76.26% = superhuman = production reality" framing became misleading: v1 approached saturation, so [OSWorld 2.0](https://osworld-v2.xlang.ai/) (2026-06-26, arXiv 2606.29537) reset the bar with **108 long-horizon workflows** (~318 tool calls each vs ~30 in v1). On 2.0 the strongest model, **Claude Opus 4.8 (max thinking), reaches only 20.6%** binary completion at 500 steps, GPT-5.5 ~14%, and no model clears 10% on 137+ minute tasks. Reframed as a benchmark-discipline lesson (saturation + reward-hacking → read SOTA skeptically) rather than a raw number bump. First-party verified (osworld-v2.xlang.ai). - **content** · **P2 caveat sweep** (audit-driven): 4 archived tools flagged + rating-downgraded (all `gh api` archived:true) — **LangServe** (→ LangGraph Platform for new deploys), **microsoft/prompt-engine** (dead since 2023), **GongRzhe/Office-PowerPoint-MCP-Server** (→ anthropics/skills pptx; heading + metadata Rating both fixed), **crewAIInc/crewAI-examples**; **Canva** MCP note corrected from "still early access" to the official GA server (canva.dev/docs/mcp, ~32 tools, any plan); the cli-agents-guide maintenance note fixed to "8 CLI" and the ">30k stars" inclusion bar reconciled with the very-new/official-vendor Grok Build exception; and a schema-evolution mirror error fixed (zh "從 ~70% 提升" → "~30%", matching the correct English). Tri-locale. - **content** · **P2 model-version refresh** (audit-driven; Stage 1 model tables + glossary Context-Window/Frontier entries + Stage 6 pick-list, tri-locale): **Grok 4.3 → 4.5** (context 1M → 500K — coupled, since 4.5 dropped the window), **MiniMax M2.7 → M3** (1M), **GLM-5.1 → 5.2** (MIT, 1M), **Qwen3 → 3.7 / 3.6**, **Mistral** 7B/Mixtral/Codestral → **Small 4 / Ministral 3 / Large 3** (license hedged: only Large 3 confirmed Apache-2.0), **Yi** flagged frozen (01.AI exited foundation-model training in 2025), and a false "open weights" label dropped from Mistral Medium 3.5 (it's premier/proprietary). Cross-checked against multiple current sources. - **content** · **Kimi → K3** (Stage 1 model table + picker, examples/README, setup-guide; tri-locale). Moonshot's current flagship is **K3** (2.8T params, native multimodal, **1M context**). Two stale facts fixed: Stage 1 listed K2.6 as "1M+" (K2.6 is 256K — the 1M is K3's), and the examples/README pricing table + runnable snippet + setup-guide used the **discontinued** `kimi-k2-turbo-preview` (Moonshot retired the K2 series 2026-05-25, so the example threw) → `kimi-k3`, with its price marked context-tiered (K3 per-token pricing was not first-party confirmable, so no numbers invented). First-party verified (platform.kimi.ai/docs/models). - **docs** · CITATION.cff version 2026.06.13 → 2026.07.17 (stale vs this week's content batches). - **tooling** · **`scripts/refresh-stars.py` fixed** — the weekly star-refresh bot silently no-op'd every entry-block `★` since May (it recorded the URL line, not the star line, as the write-back target), freezing ~half the repo's star counts while same-line siblings updated. Fix targets the star's own line + adds a next-GitHub-URL boundary to the Step-2 lookahead (a coupled requirement: without it the write-back fix would corrupt neighbour cells — code-reviewer found 15 live cross-URL leaks). Regression test (7 cases) wired into CI (ccd733b). - **content** · **P1 staleness fixes** from the repo-health audit (first-party re-verified, tri-locale, each code-reviewed): (1) time-critical — DeepSeek legacy IDs `deepseek-chat` / `deepseek-reasoner` (sunset 2026-07-24 15:59 UTC) → `deepseek-v4-flash` / `v4-pro` (1M context, refreshed $0.14/$0.28 + $0.44/$0.87 pricing), and the retired `gemini-2.0-flash` → `gemini-3.5-flash` in the runnable Stage-1 cross-provider `starter.py` so it stops throwing (47748d1); (2) **ChatGPT Atlas** marked discontinued (announced 2026-07-09, shuts down 2026-08-09, macOS-only, folded into the ChatGPT desktop app), the false "Llama 4 unreleased as of 2026-05" note corrected (Scout / Maverick shipped 2025-04), and **Codex CLI + Gemini CLI** re-marked as shipping native subagents + hooks in 2026 (were labelled ❌ single-agent) (0c7b1da); (3) archived-tool caveats — RooCodeInc/Roo-Code ("active community" struck) and the author's own deprecated WenyuChiou/gemini-delegate-skill (980bfc5). ## 2026-07-16 - **content** · Track A (A2 CLI Workflow) gains **langchain-ai/openwiki** in Recommended Tools, next to repomix. First-party verified (github.com/langchain-ai/openwiki, MIT, 11.7k★, released 2026-07-01): an npm CLI (`openwiki --init`) that generates and auto-maintains a wiki of your codebase and wires a reference into `CLAUDE.md` / `AGENTS.md` so the coding agent reads it on demand; built on DeepAgents, traces to LangSmith. Added with a 💡 concept note naming the **agent-facing documentation** idea (structured codebase context the agent reads on demand, kept out of the prompt) and framing repomix (one-shot snapshot) vs OpenWiki (living wiki) as two angles on the same gap. Placed in Track A (not Track B): the learner value is operating a CLI agent better via context, not building an agent. Tri-locale; anchor / zh-Hans / switcher gates + code-reviewer pass. - **content** · Glossary "Term not here? / 找不到的詞？" footer now points to **baihuaai.com（白话AI）** as a plainer-language companion (resolves #65, suggested by @linsipeng) — a free, ad-free Simplified-Chinese beginner glossary (term index + zero-basics zone) that explains AI terms in everyday words with analogies. Described only from first-party verification of the site; no unconfirmed term-coverage claims. Tri-locale; gates + code-reviewer pass. - **content** · Four last-month breakout projects added after a first-party trending survey (GitHub Search API `created:>=2026-06-16` by stars; every fact re-verified from each repo's README + API before writing): **vercel/eve** → Stage 4 特殊路線 (filesystem-first TS agent framework — agent parts are conventional files: `instructions.md` / `tools/` / `skills/` / `channels/` / `schedules/`; `npx eve@latest init`, Apache-2.0, ★ 3.7k+, ⚠️ new 2026-06; category label extended to include filesystem-first, table now 17 projects); **cloudflare/security-audit-skill** → 5.3 recommended-skills table (official six-phase adversarial security-audit pipeline that seeded Cloudflare's vulnerability harness, MIT, ★ 2.5k+); **anthropics/launch-your-agent** → 5.3 recommended-skills table (official educational skill, idea → live Claude Managed Agent, honest ⚠️ it self-describes as an unmaintained reference implementation, Apache-2.0) — originally proposed for Stage 8, but the repo has no Managed-Agents context there, so it lives with the skills it actually is; **xai-org/grok-build** → cli-agents-guide comparison now 8 CLI agents (SpaceXAI's Rust TUI coding agent: codebase-aware edits, shell, web search, headless CI mode, ACP editor embedding; browser sign-in auth, Apache-2.0, ★ 10k+, ⚠️ flagged very-new — open-sourced 2026-07-14). Declined this round: the Tier-2 niche candidates (open-connector / openscience / shepherd / llm-space) and the offensive-security (AGPL red-teaming), no-license, and ToS-gray candidates. code-reviewer REQUEST CHANGES then caught stale "7 CLI agents" count/roster survivors, and a widened follow-up self-scan caught 8 more lines the review missed — **~28 survivor lines across 20 more files in total** (README ×3, resources/README ×3, for-developer ×3, for-everyday-users ×3 — incl. a pre-Hermes "six" in the en mirror, cookbook ×3 ×2 spots, A1-cli-intro's own duplicated roster ×3, agent-paradigms ×3, setup-guide ×3, docs/TESTING_PLAN) — all swept to 8, Grok Build added to every enumerated roster (the A1 entries carry the same very-new / not-your-first-CLI caveat; the cookbook "BYO-LLM CLIs" subset lists were deliberately NOT extended since Grok Build has no verified BYO support). Also per review: zh "hunting" mistranslation 攻擊/攻击 → 漏洞搜獵/漏洞搜猎, provider label pinned to "SpaceXAI（xAI，官方）", auth cell tightened to the README's literal claim, star-counts dropped from the 5.3 rows for table consistency ("educational" kept — it is the README's own verbatim self-description). Tri-locale; anchor / zh-Hans / switcher / stage-template gates + code-reviewer pass. ## 2026-07-13 - **content** · **Claude Fable 5 is back** — swept the repo's now-false "suspended / unavailable / use Opus 4.8" caveats. First-party verified (anthropic.com/news/redeploying-fable-5, 2026-06-30): the US export controls were lifted 2026-06-30 and Fable 5 was redeployed globally on 2026-07-01 (Claude Platform / Claude Code / Cowork; API rollout in progress; redeployed with a new safety classifier that blocks the flagged jailbreak and reroutes to Opus 4.8). Mythos 5 restored only for approved US organizations. Updated ~44 mentions across Stage 1 / 6 / 7 / 7.5 / 8, the glossary, examples/README, and the repo CLAUDE.md (tri-locale): suspension caveats → "restored 2026-07-01"; and since Fable 5 (Mythos-class, above Opus) is on top again, the now-false "Opus 4.8 is the current top usable Claude tier" claims were corrected to "Opus-class flagship" (kept only as a past-tense note where it records that Opus was the top usable tier *while Fable was suspended*). Also filled in Fable 5's now-known 1M context in the model pickers. Example pricing code AST-parses clean. Tri-locale; anchor / zh-Hans / switcher gates + code-reviewer pass. ## 2026-07-12 - **content** · Stage 2 Exercise 2 (Few-Shot) now makes a **fair** zero-shot vs few-shot comparison (resolves #62, reported by @WMichstaBe). The zero-shot baseline had no task instruction (just `input: {text}\noutput:`), which conflated "telling the model the task" with "showing examples" — small models often read it as text continuation and scored ~0, overstating the few-shot gain. Both conditions now share the same `TASK` instruction and few-shot only *adds* examples, so the experiment isolates the effect of the examples. The fragile `assert c3 >= c0` (few-shot isn't guaranteed to beat zero-shot) was replaced with a completeness check plus an honest "net gain may be 0 or even negative" printout; the observation prose was reframed to few-shot's real value (pinning output format + judgment on ambiguous cases). Path A + Path B, tri-locale; example code AST-parses clean; gates + code-reviewer pass. ## 2026-07-09 - **content** · Stage 7.5 gains a plain-language **"分工 / Division of labor"** subsection (tri-locale), sourced first-party from Anthropic's *Agentic coding and persistent returns to expertise* (2026-06-16) + the *2026 Agentic Coding Trends Report*: you decide **what** to build, the agent decides **how** (~70% of planning decisions are the human's; ~80% of execution is left to the agent). Ties into the stage's "work boundary" axis, the returns-to-expertise framing, and the human → agent-team extension (Stage 7). Written analogy-first (home-renovation) for non-engineers; every cited number is first-party-verified — the trends-report "delegation gap" figures were NOT first-party-confirmable, so deliberately omitted. Tri-locale; anchor / zh-Hans / switcher gates + code-reviewer pass. - **site** · Removed the README **Star History** section. The star-history.com embedded chart no longer renders (GitHub restricted star-timeline data access in 2026; the anonymous `api.star-history.com/svg` embed now 503s for every repo, verified incl. `facebook/react`). Since the README header already carries a live stars badge, the section was redundant once the trend chart was gone, so it was dropped rather than kept as a duplicate badge. Tri-locale; gates + code-reviewer pass. - **content** · **GPT-5.6 (Sol / Terra / Luna)** shipped and is no longer preview — rolled through Stage 1 (model table + legend), glossary (Context-Window + Frontier-Model), and Stage 6 (reasoning-table intro + GPT-5.5 row). All first-party verified against OpenAI's API model docs: **Sol** `gpt-5.6-sol` ($5/$30 per MTok), **Terra** `gpt-5.6-terra` ($2.50/$15), **Luna** `gpt-5.6-luna` ($1/$6); all three **1.05M context**, 128K max output, available in ChatGPT + Codex + API. **Fixes a real error**: the GPT row's Context read `~400k` (that was GPT-5.5's) — GPT-5.6 is 1.05M. The `(preview)` marker plus its now-unused legend clause were dropped per the table's maintenance convention (status resolved → delete the legend line); Stage 1 header month 2026-06 → 2026-07; the glossary frontier entry gains a 2026-07 cluster. Preview-vs-GA was checked carefully: the 2026-06-26 *preview* system card described the pre-launch limited-preview phase, whereas the API docs now list all three under "Frontier models" with pricing and **no** preview/limited badge (that page does badge "Deprecated" elsewhere, so the absence is meaningful). Tri-locale; anchor / zh-Hans / switcher / stage-template gates + code-reviewer pass. ## 2026-07-01 - **content** · Claude **Sonnet 5** (released 2026-06-30) rolled through the repo, all first-party verified (platform.claude.com model docs + anthropic.com/news/claude-sonnet-5): `claude-sonnet-4-6` → `claude-sonnet-5` and `Sonnet 4.6` → `Sonnet 5` everywhere they name the current default Sonnet — Stage 1 model table + reading list + pricing example, glossary Context-Window / Computer-Use / Frontier-Model entries, Stage 8 Computer-Use row, setup-guide + examples/README model-picker, all walkthrough + stage-3/4 example CLI commands, the `branches/for-developer` Aider example (its two-generations-old `claude-sonnet-4-20250514` snapshot also bumped to `claude-sonnet-5`), the repo CLAUDE.md picker, and the `freshness-models.yml` whitelist (47 content files, 43 model-ID swaps). Verified specs carried, none invented: **1M context** (same as Opus 4.8), **$3/$15** standard ($2/$10 intro through 2026-08-31), "best speed×intelligence" positioning; Sonnet 5 supersedes Sonnet 4.6 (now Legacy). Historical `Sonnet 4.5` references (Stage 6 predecessor list, Stage 7 GAIA leaderboard) deliberately left intact. Tri-locale; anchor / zh-Hans / switcher gates + code-reviewer pass. - **content** · Stage 2 (Prompt Engineering) + glossary now spell out **zero-shot / one-shot / few-shot** in plain language — terms Exercise 2 leaned on but never defined. The glossary entry `Few-shot / Zero-shot` → `Zero-shot / One-shot / Few-shot` gains the previously-missing **one-shot** (exactly 1 example) plus a one-line framing (the three differ only in how many examples you show the LLM); Stage 2 Exercise 2 gets a 3-bullet inline explainer tying the `3-shot` its code uses back to "few-shot". Also corrected a stray Traditional `分類` → `分类` in the zh-Hans exercise line. Tri-locale; anchor / zh-Hans / switcher gates + code-reviewer pass. ## 2026-06-30 - **content** · Staleness audit Batch 1 (from the 2026-06-29 multi-agent repo audit): removed the phantom "Claude Mythos Preview" attribution on the Stage 7 WebArena benchmark row (→ "領先 model 未公布" — Mythos/Fable benchmarks were never published and access is suspended, so the cell contradicted the table's own caption); glossary Context-Window entry gains Grok 4.3 1M + Mistral Medium 3.5 256k for parity with the Frontier Model entry; cookbook "Claude 4.5+" → "Claude 4.8+"; A2A glossary entry refreshed to v1.0 (Linux Foundation governance, 150+ orgs, signed Agent Cards). All first-party verified. Tri-locale; gates pass. - **content** · Staleness audit Batch 2 (model-ID / recommendation refresh, all first-party verified): Stage 6 Path-2 reasoning list + observation line, Stage 8 example comment, and setup-guide updated Gemini 3.1 Pro → 3.5 Flash and added xAI Grok 4.3 (GA) to the strongest-reasoning options; GPT-5.5 deliberately kept in runnable example code since GPT-5.6 is still limited preview (not GA); setup-guide free-tier corrected to "GPT-5.5 Instant (rate-limited)"; Stage 4 OpenAI Agents SDK "April 2026 update" reframed to past-tense (the built-in-sandbox / 7-provider claim verified accurate), AG2 v0.2-vs-v0.4 note softened. Tri-locale; gates pass. - **layout** · Stage 1 model tables de-crammed: time-sensitive status/caveat text (Fable 5 suspension, license clauses, release dates, Arena rank) moved out of the data cells into one plain-language legend line per table; genuinely-old entries retired (GPT-5 / o-series, Gemini 3.1 Pro). Added an HTML-comment maintenance convention so the tables self-clean as models churn (new flagship = swap not append; resolved status = delete the legend line). Worst flagship cell dropped ~75 → ~33 chars. Tri-locale; plain-language; gates + code-reviewer (APPROVE) pass. - **layout** · Stage 2 Curated-Projects table de-crammed (same pattern): the two worst cells (dspy / NirDiamant, ~150-182 → ~38-74 units) trimmed to a short reason + ★ / license; framework-not-tutorial + NOASSERTION caveats moved to one legend line. Tri-locale; gates pass. - **layout** · Stage 1 Chinese-frontier table (the 7-provider / 7-col one, widest in the stage) split along the API-vs-open-weights line into two 6-col tables (① API-only: DeepSeek / Kimi / Hunyuan / MiniMax · ② open weights: Qwen / GLM / Yi); the License column folded into one plain legend per group. All 7 providers + license nuance preserved. Tri-locale; gates + column-count scan pass. - **site** · MkDocs-Material UI upgrade (verified with a local `mkdocs build`, clean across all 3 locales): code-copy buttons, instant/SPA-style navigation + progress, navigation.sections, search.share, content tabs/tooltips/annotate; `:material-*:` icon support; new `docs/stylesheets/extra.css` (indigo brand color, grid-card hover, tighter rounded tables). A custom card landing page is a planned follow-up (blocked on the README-vs-index i18n conflict). - **site** · Nav cleanup: the top nav was bilingual + inconsistent ("首頁 / Home", "Audience branches"…); switched to single-language source labels + i18n `nav_translations` so each locale shows only its own language (繁中 首頁 / en Home / 简中 首页), and dropped `navigation.sections` (over-expanded the sidebar). Verified with a local build, all 3 locales. - **site** · Custom card landing page shipped (resolves the earlier README-vs-index blocker): `index.md` / `.en.md` / `.zh-Hans.md` is now the trilingual home — hero + stat cards + track/stage grid-cards. The README moved to an `/about/` page (staged as `about.md` so it no longer collides with `index` for the home slot), and `mkdocs_hooks.py` rewrites in-content `README.md` links to `about` at build time so they keep resolving (examples/README untouched). Verified locally: clean build, all 3 locale homes = landing, anchor / zh-Hans / switcher gates pass. - **content** · Staleness audit Batch 3 (new harness-engineering frames + adds, all first-party sourced): Stage 7 gains a "feedback loops, not a more perfect prompt" subsection — the 4 feedback timings (tool returns / mid-run steering / end-of-turn acceptance / outer loop), anchored on Anthropic's planner→generator→evaluator harness post; Stage 7.5 gains "Harnesses expire: Model-Harness-Fit + the Bitter Lesson" (Sutton 2019); `deepagents` (LangChain, LangGraph-based, MIT, v0.6.12) added to Stage 4 framework resources + a plain glossary "Deep Agent" entry. Written analogy-first for non-engineers, jargon glossed inline; Codex `/goal` folded into N1's outer-loop row (no separate section). Tri-locale; gates pass. ## 2026-06-29 - **content** · Stage 1 model table + glossary (frontier + Context-Window entries) + `scripts/freshness-models.yml` whitelist refreshed with late-June-2026 frontier models, all first-party verified: GPT row gains GPT-5.6 (Sol / Terra / Luna, **preview**); Gemini row → 3.5 Flash (3.5 Pro in dev); glossary frontier adds xAI Grok 4.3 (GA) + Mistral Medium 3.5 (open weights, preview), relabeled by half-month (Fable 5 suspension note retained). Preview-vs-GA marked; no fabricated benchmark / context numbers. Tri-locale; anchor / zh-Hans / switcher gates pass. - **content** · Stage 6 reasoning-model table consistency follow-up: the "current (Jun 2026) frontier" intro + the GPT-5.5 and Gemini 3.1 Pro rows now flag that newer tiers exist (GPT-5.6 Sol / Terra / Luna **preview**; Gemini 3.5 Flash available, 3.5 Pro in dev). Existing verified rows and benchmarks (e.g. Gemini 3.1 Pro GPQA Diamond 94.3%) kept and correctly attributed; no preview-model benchmarks fabricated. Tri-locale; gates pass. ## 2026-06-24 - **catalog** · Added DeusData/codebase-memory-mcp (★ 13.5k, MIT) to §5 Dev Collaboration — a code-intelligence MCP that indexes a codebase into a queryable knowledge graph (query structure / symbols / call paths instead of grep+read). Plain, non-marketing description (notes the re-index-after-edits + verify-load-bearing-claims caveats); tri-locale; §5 TOC count 7→9 (also corrects a pre-existing off-by-one); gates pass. ## 2026-06-13 - **catalog** · Added 12 high-confidence repos (all gh-verified stars/license, none previously listed): microsoft/agent-framework (Stage 4); getzep/graphiti + lancedb/lancedb (Stage 6); comet-ml/opik, pydantic/logfire, NVIDIA-NeMo/Guardrails, BoundaryML/baml (Stage 7, incl. new Safety/Guardrails + Structured-Output rows); bytedance/UI-TARS-desktop + trycua/cua (Stage 8, new Computer Use Agent Stack); awslabs/mcp + ComposioHQ/composio (MCP/Skills catalog §6 / §12); microsoft/mcp-for-beginners (Stage 5.2 reading list). Tri-locale; per-section counts updated; anchor / zh-Hans / switcher gates pass. - **content** · Stage 5 — plain-language orientation box in 5.1 (Claude Code = terminal agent for devs; Claude Cowork = desktop agent for non-coders; OpenAI parallels = Codex CLI / ChatGPT agent) so beginners see Claude Code is one *shape* among several; plus first-use plain glosses for heavy terms (harness / orchestration / scaffolding / control plane). Tri-locale; Cowork + ChatGPT agent verified first-party; anchor / zh-Hans / switcher gates pass. - **content** · Reframed Claude Fable 5 across the roadmap after Anthropic suspended all access to Fable 5 + Mythos 5 on 2026-06-12 (US government export-control directive; [status](https://status.claude.com/) · [statement](https://www.anthropic.com/news/fable-mythos-access); no restoration timeline). Documentation tables (`CLAUDE.md` / `examples/` / stages 01·06·07·07.5·08 / glossary) now mark Fable 5 as suspended and currently unavailable, with Opus 4.8 as the current top usable Claude tier; recommendation pick-lists (Path-2 reasoning chooser, Computer Use vendor table, OmniParser / browser-use swap-lists) drop Fable 5 so no reader is pointed at an inaccessible model. Tri-locale; anchor / zh-Hans-localize / language-switcher gates all pass. Suspension verified against two first-party sources, no fabricated facts. - **docs** · `CITATION.cff` version `2026.05.19` → `2026.06.13` (was stale vs the recent content batches). ## 2026-06-12 - **content** · Claude Fable 5 (Mythos-class, `claude-fable-5`, GA 2026-06-09) added as the new top Claude tier across the trilingual roadmap — model tables in `CLAUDE.md` / `examples/` / stages 01·06·07·07.5·08 + glossary frontier entry; Opus 4.8 reframed as Opus-class flagship + Fable 5 safeguard-fallback. No fabricated context-window or benchmark numbers (Anthropic published none — marked "not yet published"). Also fixed a pre-existing `claude-opus-4-7` → `claude-opus-4-8` inconsistency (`12980b3`). - **content** · Stage 5 — new **5.6 Dynamic Workflows** section after 5.5 Subagents (ecosystem-level intro + cross-link to the 7.5 deep-dive, no duplication); old 5.6 Source → 5.7, old 5.7 SDK → 5.8, all in-file refs + 7-Layer-map ranges + cross-file anchors (glossary / stages 03·06·07) relinked, tri-locale (`5044008`). - **catalog** · `1weiho/open-slide` (★4.9k, MIT) added to §2 as an agent-native slide framework — ships Claude Code Skills, distinct from Stage 4 orchestration frameworks; tri-locale (`7d3fd5d`). - **docs** · MCP/Skills catalog count made drift-proof — stale `62` → robust `65+`, category count reconciled to 15, across 33 files / all locales (`3782dd4`). Propagated the 7→8 stage reality into design notes / style-guide / reader docs (`39d397a`) and fixed outreach-draft count drift (`25785f0`). - **outreach** · send-day copy-paste packages playbook for awesome-list submissions (`afd7a76`). - **content** · per-chapter improvement audit (12-agent fan-out + skeptical filter) → 5 gap-fills, all tri-locale: Stage 3 lethal-trifecta security callout + MCP router note + glossary (`f3bde60`); Stage 1 next-token / sampling mental-model box (`1bd171f`); Stage 5 Hooks (L3 control layer) subsection (`9d2897f`); Stage 7 Loop Engineering note + glossary (`eb8e64c`). - **catalog** · new Web Search / Retrieval category (exa-mcp + tavily-mcp) + Context7 in Dev-Collaboration; category count 15→16 (`b1718d3`). - **content** · improvement-audit medium batch (6 more tri-locale gap-fills): Stage 3 structured outputs / JSON-mode (`93006a8`); Stage 2 reasoning-vs-CoT + Stage 5 MCP-in-2026 (Registry / FastMCP / security) + Stage 8 accessibility-tree & Playwright-MCP (`ea0633e`); Stage 6 RAG ingest-parsing + embedding-model selection + Stage 7 OTel GenAI conventions / pass^k·τ²-bench / MAST (`2fcfc6b`). --- ## 2026-05-31 - **tooling** · pruned the ops-metric scripts that don't touch stars or URL validity (strategic-review action #1, scoped down per maintainer): removed `scripts/snapshot-traffic.py` (GitHub traffic snapshots), `scripts/refresh-outreach-status.py` (outreach-matrix drift), `scripts/check-catalog-staleness.py` (dormant-entry pinger), and the `docs/traffic/` snapshot dir. **KEPT** the weekly stars + URL auto-update (`weekly-catalog-refresh.yml` + `lint.yml`'s `star-drift` job) — the maintainer values the weekly cadence for star-count refresh and link-rot checking. All correctness + trilingual-parity guards intact (anchor / link-rot / mirror-sync / stage-template / banned-words / overclaim / zh-Hans-localize). --- ## 2026-05-26 - **ci** · `lint.yml` overclaim check expanded (P3-G from audit) — promoted from case-sensitive exact-phrase to case-insensitive (`grep -Fi`), broadened scope to include `tracks/` `examples/` `resources/` (which the previous narrower scope missed — letting 5 uppercase `Production-grade` H2 headers in `examples/` slip through the earlier sweep). Strict-blocking list now includes all style-guide §3 phrases (`首選` / `首选` / `唯一選擇` / `唯一选择` / `業界最佳` / `业界最佳` / `業界最強` / `全世界最好的` / `最緊迫` / `the most canonical`) plus English equivalents (`production-grade` / `world-class` / `best-in-class` / `cutting-edge` / `state-of-the-art` / `industry-leading`). Corpus pre-cleaned across tri-locale before flipping to strict. - **content** · overclaim residue swept across tri-locale (18 file edits) before the lint flip — 3 × `## Production-grade …` H2 headers in `examples/stage-{6,7}/` normalized to `## Production-ready …`; 3 × inline `首選` in `stages/05` / `stages/06` / `tracks/cli/A1` softened per style-guide §3; `tracks/cli/A1` `最完整的中文社群資源` → `中文社群資源豐富` (marketing → factual). - **tooling** · `scripts/snapshot-traffic.py` shipped — captures weekly 14-day traffic window (views / clones / referrers / paths + point-in-time totals) to `docs/traffic/snapshots/YYYY-MM-DD.json` so historical trend survives the GitHub API's 14-day visibility limit. Each file ~5 KB. First snapshot included (`docs/traffic/snapshots/2026-05-26.json`). - **tooling** · `scripts/refresh-outreach-status.py` shipped — reads `.github/channel-partners.md`, extracts PR URLs, queries `gh pr view`, reports drift between recorded status and live PR state (merged / closed / ghosted / approved). Report-only (text / markdown / json), `--check` for CI. Closes P2-F from the 2026-05-25 audit; P2-E closed by snapshot-traffic. --- ## 2026-05-25 - **tooling** · `scripts/check-catalog-staleness.py` shipped — queries `gh api repos//` for `pushed_at` + `archived`, flags catalog entries dormant >= N months (default 12) or archived. Report-only (text / markdown / json). Initial run on the 247-repo catalog surfaced 17 stale entries: 5 archived (incl. `langchain-ai/langserve` archived 2026-05-05 still cited as live, `RooCodeInc/Roo-Code` archived 2026-05-15 in setup-guide) + 12 dormant (oldest: `microsoft/prompt-engine` 37 mo). - **i18n** · Stage 1 + Stage 2 mirror schema resync — `## 🎯 Curated Projects` regenerated from canonical (en hand-translated · zh-Hans via opencc tw2s + zh-hans-localize vocab); −358 lines of stale H3-card format replaced with compact-table parity to canonical. Also normalized 5 Stage 1 .zh-Hans H2 titles back to canonical wording + emoji. Eliminates the forward-schema drift across all 8 stages. --- ## 2026-05-19 - **catalog** · `microsoft/ai-agents-for-beginners` added to Stage 3 選讀/進階補充 as a parallel beginner course (explicitly *not* a substitute for the stage's hands-on practice), tri-locale (`2d83f72`, `94f2d73`). ## 2026-05-18 - **catalog** · Kimi-K2 + GLM-4.5 added to §11 中文圈專用 — neutral schema, gh-verified Stars/License, tri-locale (`fd81f31`, `ad80845`). - **ci** · weekly catalog-refresh PR now guarded auto-merge: sanity guard (star-token-only diff, ≤150 lines, anchors pass) → squash-merge, else label `needs-manual-review` (`3dc6ecd`). ## 2026-05-17 - **docs** · per-track Capstone + 4-level self-assess rubric (`CAPSTONE`), tri-locale (`dbf1ef3`, `a31dde5`). - **docs** · Pages unified — mkdocs at `/`, mdBook at `/book/`, one workflow; README's GitHub-only switcher stripped from rendered site (`5e59c7c`, `001d765`). - **docs** · README positioning reframed (trilingual, English fully maintained); stale exercise-folder count corrected 27 → 23 (`b4bb862`, `24a87fe`). - **outreach** · English-audience launch drafts — HN / Reddit / newsletters / awesome-lists (`b8f365b`). ## 2026-05-16 - **governance** · CoC + SECURITY + CITATION.cff + issue-template config added, tri-locale mirrors (`9aa2963`, `84bc58f`). - **docs** · public ROADMAP.md + learner PROGRESS.md tracker added, tri-locale (`e5cc310`, `3e628e9`). - **docs** · GitHub Pages site (mkdocs-material, trilingual) + live docs-site badge (`498932c`, `ea4530f`). - **i18n** · zh-Hans mainland-localization pass + Lint gate blocking Taiwan-vocab/「」 drift (`7f73b8a`, `805ae57`). - **visuals** · final ASCII concept blocks replaced with generated PNGs — 10/10 complete (tri-locale) (`21a2bbf`). - **ci** · actions bumped off deprecated Node20 ahead of June 2026 forced migration (`c6a8c19`). - **outreach** · CONTRIBUTORS — @demo112 (#14) + @Rain120 (#18) (`7040738`). ## 2026-05-15 - **content** · Stage 1 §主流 LLM 家族對比 (US 3 + China 7 + Western-OSS 4 + decision tree + benchmark + caveat) (`8f578bf`). - **content** · Stage 5 §7-Layer Architecture Map (Claude primitives × 3 engineering disciplines) + embedded figures (`5f99bbb`, `1e5a12b`). - **content** · subagent teaching deepened — dispatch who/how/what, vs Skill/Slash-Command disambiguation, advanced doc + figures (`009ddf9`, `21c555b`, `e8a919e`). - **content** · 5 audience branches tableized (使用情境 / 流程 / Tier ladder) + academic-style polish, tri-locale (`184015b`, `6b7e5f6`). - **i18n** · 97 broken outbound mirror anchors fixed + anchor-checker now enforces mirror files (`e1991a6`, `ab3a6d0`). ## 2026-05-14 - **content** · NEW Stage 7.5 — Advanced Agentic Concepts (OpenAI Harness Engineering 5 principles, Why→What→How map, work-boundary diagram) (`4a6bf18`, `e2c1d11`). - **content** · Track A3 §6 advanced-concept playbooks for daily CLI work (`876a457`). - **visuals** · § (513×) and 🔄 (24×) symbols stripped across all user-facing docs; concept diagrams embedded as PNG × 3 locales (`29eb774`, `d04c224`). - **catalog** · 4 Anthropic-related resources added across stages (`0af7fbc`). - **ci** · weekly catalog-refresh workflow + `--apply` flag (`dc91a8b`). ## 2026-05-13 - **content** · Stage 4/6/7 verified + merged to main (`cdb0ae3`); Stage 8 NEW — Agent Interfaces, §1-15 across 3 commits A/B/C (`b83c894`, `6c87a2f`, `069406f`). - **content** · curation positioning crystallized — exercises reframed foundational/illustrative; repo = curation hub + simple cases, depth → hello-agents (`00dc046`, `0206dbc`). - **content** · 精選 Projects consolidated to single 適合誰 tables across Stages 0-8 + Track A (`fd94d80`, `19a14a8`). - **content** · Stage 5 expanded (§5.1-5.6: Claude Code basics, MCP/Plugin/Skill 定位, §5.5 Subagents, Harness Internals) (`2c3f1dd`, `f7de4e7`). - **content** · Stage 6 RAG-first restructure + GraphRAG / Contextual Retrieval / Hybrid Search; 2026 frontier-model refresh (`f00e2c2`, `acbc9dc`). - **ci** · 4 checks added — anchor validator, mirror-sync reminder, 2026 freshness, stage-template enforce (`a14c809`, `4491e6e`). - **i18n** · 8-stage tri-locale mirror catch-up via Codex + Gemini delegation; 37 legacy anchors fixed, validator → strict (`8b39c75`, `706d257`). - **catalog** · whale (DeepSeek terminal) + a-stock-data added to Chinese ecosystem (#14) (`3d375bd`). ## 2026-05-12 - **content** · examples/ bootstrapped — Stage 1 (6) + 2 (4) + 3 (6) + 4 (5) + 6 (5) + 7 (5) inline starters + folder examples, tri-locale (`c1fcaa7`, `8051861`, `7d2c1b7`). - **content** · dual-path examples — Ollama (default, cost-driven) alongside Anthropic; per-stage budget + LLM recommendation list (`bc37ad8`, `3fa5410`). - **content** · tool-calling-tutor — installable Claude Code skill + Stage 5 §5.3 meta-example (`3584669`). - **i18n** · diagrams renamed `.zh-Hans.png` per BCP 47 / W3C convention (`78797a3`). ## 2026-05-11 - **accessibility** · `resources/setup-guide.md` (3 langs) — addresses the dev-fluency assumption gap that subagent audit flagged across 5 non-dev branches. 5 sections covering API key registration, Python install, hello-world, Claude Code first auth, SKILL.md primer (`3c88b2b`). Plus 15 branch-top callouts on all 5 audience branches. `resources/README.{en,zh-Hans}.md` created for trilingual parity. - **accessibility** · README — promoted setup-guide pointer to top of Quick Start across all 3 langs (`ad47706`). Was buried in Related Resources where non-dev visitors hit technical walls before discovering it. - **accessibility** · setup-guide opens with a 4-tier on-ramp (Web / Desktop / CLI / API) + official download URLs for Claude.ai, ChatGPT, Gemini, Le Chat, Claude Desktop, ChatGPT Desktop, LM Studio (`3c89952`). Replaces the abstract "decide two things" intro so non-dev readers see "just use claude.ai for free" as the first option, not "register API key → install Python". - **accessibility** · setup-guide adds a 3rd tier between Desktop and CLI: **IDE with built-in AI** (Cursor, Windsurf, Cline, Continue, Roo Code, Zed, GitHub Copilot) with download URLs (`7e14093`). Distinguishes "AI sidekick while you write code" from "agent runs autonomous task in terminal". ## 2026-05-10 - **funnel** · Stage 1 → Stage 2 callouts added across 3 langs to address visible drop in `traffic/popular/paths` (`0ee2a3a`) - **outreach** · 3 awesome-list targets backfilled into channel-partners matrix from launch-checklist: `travisvn/awesome-claude-skills`, `WangRongsheng/awesome-LLM-resources`, `AiHubCN/Awesome-Chinese-LLM` (`90a6ad1`) - **outreach** · PR #6135 to `punkpeye/awesome-mcp-servers` — addressed bot `name-check`, replied to non-applicable `glama-check` + `emoji-check` (`81a7313`) - **content** · Cookbook Recipe 6 — **Local-LLM × CLI Agent walkthrough** (`5855852`). Bridges Stage 1 (local LLM) + Stage 5 (CLI agent) end-to-end. Explicitly notes Claude Code does **not** support local LLM as backend; routes readers to OpenCode / goose / Aider / Hermes instead. Stage 5 + cli-agents-guide also gain matching pointers. - **catalog** · Hermes Agent (`NousResearch/hermes-agent` ★142k) added as 7th major CLI agent across `cli-agents-guide`, `tracks/cli/A1`, and 5 dependent files (`698f13a`). Differentiator: cloud-VM-native, model-neutral (200+ LLMs via OpenRouter / NIM / GLM / Kimi / etc.), self-improving skill loop. - **i18n** · `*.zh-CN.md` → `*.zh-Hans.md` migration per BCP 47 / W3C compliance (`21b653d`). 25 files renamed, ~270 markdown lines updated, tooling (`sync-language-switchers.py`, `lint.yml`, `generate-stage5-stack.py`) migrated. Thanks [@xfq](https://github.com/xfq) (W3C i18n lead) for flagging in [#9](https://github.com/WenyuChiou/awesome-agentic-ai-zh/issues/9). Added to CONTRIBUTORS (`868691d`). - **visuals** · English README hero (`banner.en.png`), Learning Map (`learning-map.en.png`), and Branch Decision Tree (`branch-decision-tree.en.png`) refreshed to ChatGPT-rendered versions (`c7edff8`, `4be6b88`, `6c03c58`). ## 2026-05-09 - **outreach** · Day 1 PR sent: `punkpeye/awesome-mcp-servers#6135`, adding awesome-agentic-ai-zh to `## Tutorials` (`a0dc4d5`). Plan revised after upstream audit caught `hesreallyhim/awesome-claude-code` mid-reorg (Day 2 = issue not PR) (`708259c`). - **outreach** · 8 channel-partner pitch templates created in `.github/outreach/` plus tracking matrix `.github/channel-partners.md` (`2f63745`). Targets: Datawhale, liyupi, HuggingFace, LangChain (kyrolabs), awesome-claude-code, awesome-mcp-servers, Zhipu, Moonshot. - **catalog** · 11 中文圈專用 expanded from 2 → 7 entries: `QwenLM/Qwen-Agent`, `coze-dev/coze-studio`, `coze-dev/coze-loop`, `liaokongVFX/LangChain-Chinese-Getting-Started-Guide`, `chatchat-space/Langchain-Chatchat` (`4809039`). - **funnel** · Stage 0 → Stage 1 callouts added (`3dfe761`). - **ci** · zh-Hans companion files excluded from zh-TW banned-word audit (closes #7) (`3acc3f2`). ## 2026-05-08 - **content** · `for-teacher` branch expanded with 3-tier teacher AI use-case framework (Chen 2020, Mittal 2024) via @scott0127 PR #6 (`cd1cad4`). - **content** · Stage 6 unit guide: memory + RAG overview via @scott0127 PR #5. - **content** · Branch decision tree (zh-Hans) added, English banner added, `for-developer` branch thickened 56 → 138 lines × 3 langs. ## 2026-05-07 - **catalog** · 3 user-flagged gaps filled: `safishamsi/graphify`, `pbakaus/impeccable`, `netease-youdao/LobsterAI` + context-engineering and harness-engineering coverage. - **content** · `resources/cookbook.md` added with 5 (now 6) step-by-step recipes covering Skill / MCP / Office / NotebookLM / Zotero / Local-LLM workflows. ## 2026-05-06 - **launch** · Repo announced to bilingual community. Star count: 0 → 519 in week one. - **content** · `learning-map.png` polished, README hero banner placement finalized. --- ## Conventions - Each commit SHA is clickable: `https://github.com/WenyuChiou/awesome-agentic-ai-zh/commit/` - Categories: `content` (stages/branches/tracks) · `docs` (project meta-docs: README/ROADMAP/PROGRESS/CAPSTONE/Pages site) · `governance` (CoC/SECURITY/CITATION/issue templates) · `accessibility` (on-ramp/setup friction) · `catalog` (mcp-skills-catalog entries) · `funnel` (cross-stage navigation) · `visuals` (diagrams/banners) · `i18n` (translation/locale) · `outreach` (channel partners) · `ci` (workflows/lint) · `launch` (one-time events) - Maintained manually; not auto-generated. Updated alongside substantive commits. --- ### SECURITY # 安全政策 / Security Policy > **繁體中文** | [简体中文](./SECURITY.zh-Hans.md) | [English](./SECURITY.en.md) 這個 repo 是一份**精選學習路線圖**(主要是 Markdown 教材 + 少量範例程式碼),不是一個會部署的軟體產品。即便如此,有幾類安全問題仍然值得回報——尤其因為本教材教讀者**實際執行 agent / MCP / tool-use**。 ## 支援範圍 本專案採**滾動式維護**:支援範圍是 `main` 分支的最新狀態。版本化 tag(`vYYYY.MM.DD[-N]`,供 [`CITATION.cff`](CITATION.cff) 引用)是**內容快照**,不回溯修補——回報的問題一律修在 `main`,不會為舊 tag 發布修正版。 ## 哪些算安全問題 請回報以下情況: - **被劫持 / 惡意的第三方連結** —— catalog 裡某個 repo 連結指向了釣魚站、惡意套件,或專案已被惡意接管 - **範例程式碼的供應鏈風險** —— `examples/`、`walkthroughs/`、`scripts/` 裡的程式碼會引導不安全的相依套件、洩漏金鑰的寫法,或可被注入的指令 - **教材中外洩的密鑰** —— 文件裡不小心貼出真實 API key / token / 憑證 - **指令注入式的教學內容** —— 某段教學會誘導讀者在自己機器上跑出危險後果(例如未沙箱化地對 untrusted input 執行 agent) **不屬於**本 repo 安全範疇的:第三方專案**本身**的漏洞——那些請直接回報給上游專案的維護者,並可同時開 issue 提醒我們把該 entry 標註或移除。 ## 如何回報 **請不要在公開 issue 裡貼出可被利用的細節。** 1. **首選**:用 GitHub 的 **私人漏洞回報**(repo 的 **Security** 分頁 → **Report a vulnerability**)。只有維護者看得到。 2. 若該功能不可用:請透過 GitHub 私訊 **@WenyuChiou**,說明問題影響與受影響的檔案 / 連結,我們會私下接續。**請勿開公開 issue**——即使不貼 exploit 細節,公開的標題與標籤也會對外暴露「有一個未修補的問題」。 回報時請盡量附上:受影響的檔案 / 連結、問題說明、可能的影響,以及(若有)修正建議。 ## 處理時程 這是一個社群維護的教育專案,沒有 SLA,但我們會儘速處理。一般而言: - **確認收到**:7 天內 - **初步評估**:14 天內 - **修正或標註**:視嚴重程度而定;惡意連結會優先處理 謝謝你幫忙讓這份教材對所有學習者都更安全。 ---