wehub/wenyuchiou--awesome-agentic-ai-zh
1
0
Fork 0
Code Issues Pull Requests Actions 1 Deployments Models Agent Notes Packages Projects Releases Wiki Activity

chore: import upstream snapshot with attribution
Site (mkdocs + mdBook) → GitHub Pages / Build mkdocs (root) + mdBook (/book/) (push) Waiting to run
Details
Site (mkdocs + mdBook) → GitHub Pages / Deploy to GitHub Pages (push) Blocked by required conditions
Details

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 13:13:20 +08:00
commit 3a46cbf880
445 changed files with 61199 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/FUNDING.yml
+4
View File
@@ -0,0 +1,4 @@
# Shows a "Sponsor" button at the top of this repository.
# Docs: https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository
buy_me_a_coffee: wenyuchiou
# github: WenyuChiou # uncomment once the GitHub Sponsors application is approved
.github/ISSUE_TEMPLATE/bug-report.md
+24
View File
@@ -0,0 +1,24 @@
---
name: 🐛 Bug Report / 內容問題
about: 連結失效、資訊過時、星等錯誤、license 寫錯等
title: "[bug] "
labels: bug
---
<!-- 中文 / 英文皆可 -->
## 問題描述 / Issue
<!-- 例如：Stage 5 中 anthropics/claude-code 的連結失效 -->
## 受影響的檔案 / Affected file
<!-- 例如：stages/05-claude-code-ecosystem.md:65 -->
## 看到的內容 / What you saw
<!-- 把錯誤的原文貼上來 -->
## 應該是什麼 / What it should be
<!-- 你建議的修正 -->
## 其他資訊 / Other info
- [ ] 我已經確認連結真的失效（用 `curl -I` 或瀏覽器試過）
- [ ] 我看過 [`resources/style-guide.md`](../resources/style-guide.md)
.github/ISSUE_TEMPLATE/config.yml
+13
View File
@@ -0,0 +1,13 @@
# Issue 入口設定 — 把「不是 bug / 不是新增 entry」的提問導去 Discussions,
# 避免 issue tracker 被「我該怎麼開始」「stage X 卡住」這類問題灌爆。
blank_issues_enabled: false
contact_links:
- name: 💬 提問 / 學習討論（Discussions Q&A）
url: https://github.com/WenyuChiou/awesome-agentic-ai-zh/discussions
about: 學習路線怎麼走、某個 stage / branch 卡住、想討論 agent 工具選型——這類「不是 bug、不是新增 project」的問題請開 Discussion，不要開 issue。
- name: 📐 新增 project 前先讀策展標準（style-guide）
url: https://github.com/WenyuChiou/awesome-agentic-ai-zh/blob/main/resources/style-guide.md
about: 新增 project entry 的 schema、license 標註慣例、品質門檻都在這裡。讀完再用「Project Suggestion」範本開 issue。
- name: 🔒 回報安全問題（Security）
url: https://github.com/WenyuChiou/awesome-agentic-ai-zh/blob/main/SECURITY.md
about: 惡意連結、範例程式碼供應鏈風險、外洩密鑰——請依 SECURITY.md 用私人管道回報，不要開公開 issue。
.github/ISSUE_TEMPLATE/project-suggestion.md
+45
View File
@@ -0,0 +1,45 @@
---
name: 💡 Project Suggestion / 推薦新 project
about: 建議在某個 stage 加入新 project
title: "[suggest] <repo-name> for Stage <N>"
labels: suggestion
---
<!-- 中文 / 英文皆可 -->
## Project 連結 / Project URL
<!-- 例如：https://github.com/example/repo -->
## 建議放在哪個 stage / branch
<!-- 例如：Stage 4 — Agent Frameworks 或 for-researcher branch -->
## 為什麼這個 project 教這個 stage？/ Why does it teach this stage?
<!-- 1-2 段。具體說明它教什麼、跟現有 entries 的差異 -->
## 通過 [策展標準](../../CONTRIBUTING.md#策展標準) 嗎？
- [ ] 最近 6 個月內有 commit（或明確標示 stable）
- [ ] 有 hello-world 文件，30 分鐘內能跑起來
- [ ] License 明確（MIT / Apache-2 / BSD / 等）
- [ ] 維護者可信（知名組織 / 個人 / 公司）
## 提議的 entry 草稿（選填）/ Draft entry (optional)
<!-- 如果你願意直接附 entry 文字，貼在這裡。格式見 resources/style-guide.md -->
```markdown
### [Project Name](url) ⭐⭐⭐⭐
| 欄位 | 內容 |
|---|---|
| 語言 | Python |
| Stars | ★ Xk+ |
| License | MIT |
| 推薦度 | ⭐⭐⭐⭐ |
**教什麼**：...
**適合誰**：...
```
## 其他資訊
- [ ] 我已經讀過 [`resources/style-guide.md`](../resources/style-guide.md)
- [ ] 我確認這個 project 不是 self-promotion（如果是，請標註利益關係）
.github/PULL_REQUEST_TEMPLATE.md
+37
View File
@@ -0,0 +1,37 @@
<!-- 中文 / 英文皆可。先讀過 [`resources/style-guide.md`](../resources/style-guide.md) -->
## PR 類型 / Type
<!-- 勾選 -->
- [ ] 🆕 新增 project（Add new project entry）
- [ ] 🔧 修正錯誤（Fix error: stale link / wrong info）
- [ ] 🌏 翻譯（Translation: zh + en companion）
- [ ] 📝 內容改善（Content improvement）
- [ ] 🎨 風格 / 結構（Style / structure）
- [ ] 其他 / Other
## 影響範圍 / Affected files
<!-- 例如：stages/05-claude-code-ecosystem.md + stages/05-claude-code-ecosystem.en.md -->
## 摘要 / Summary
<!-- 1-3 句說明做了什麼 + 為什麼 -->
## 如果是新增 project：策展標準
<!-- 沒新增 project 可以跳過 -->
- [ ] 最近 6 個月內有 commit（或明確標示 stable）
- [ ] 有 hello-world 文件
- [ ] License 明確
- [ ] 維護者可信
- [ ] 我可以一句話說明它**教這個 stage 的什麼**
## 如果是翻譯 / 文字修正：style-guide check
- [ ] 沒有 zh-Hans 用詞（教程 / 視頻 / 軟件 / 用戶 / 網絡 / 接口 / 默認 / 函数 / 算法）
- [ ] 沒有 overclaim（the best / production-grade / 首選 / 全世界最好）
- [ ] License 標註符合 [慣例](../resources/style-guide.md#5-license-標註慣例)
- [ ] zh + en companion 兩邊都有更新（如果只動到一邊請說明為什麼）
## 額外說明 / Additional notes
<!-- 任何 reviewer 應該知道的 context -->
---
**Reviewer 會檢查**：策展理由是否成立、entry schema 是否符合 style guide、license 標註是否正確、zh/en 結構是否同步。
.github/TESTING-STATUS.md
+74
View File
@@ -0,0 +1,74 @@
# Testing Status — 誠實揭露
> 這份是給 maintainer / 第一個跑各個 build 的人看的。**誠實地說明哪些 code 真的跑過、哪些只是 syntax check、哪些完全沒測**。
最後更新：2026-05-06
---
## ✅ 真的跑過、有觀察輸出
| 項目 | 狀態 | 證據 |
|---|---|---|
| `scripts/refresh-stars.py` | ✅ Verified | 在 main 上跑過 N 次，0 drift / 0 not-found 都有實際輸出 |
| `scripts/check-links.py --fast` | ✅ Verified | 跑過 120 GitHub URLs 全 OK |
| `gh api` repo 元資料抓取 | ✅ Verified | 152 個 entry 的 stars / license / pushed 都對證過至少一次 |
| Mermaid syntax | ✅ Verified | GitHub 上 render 看過正確（README hero） |
| CI banned-words / overclaim grep | ✅ Verified | 用相同 grep 邏輯本地跑過，0 violations |
---
## ⚠️ 只做了 syntax check / 配置 validation，沒實際 end-to-end 跑
| 項目 | 狀態 | 缺什麼 |
|---|---|---|
| `scripts/build-pdf.sh` | ⚠️ Bash syntax OK | **沒實際跑過** pandoc + xelatex；沒驗證輸出的 PDF 真的能開、CJK 字型真的可用 |
| `scripts/build-mdbook.sh` | ⚠️ Bash syntax OK | 跑過一次但 mdbook-mermaid 失敗（已 fix 但沒重跑驗證） |
| `.github/workflows/lint.yml` | ⚠️ YAML valid | **沒在真 PR 上觸發過**——不知道 Linux runner 上 grep 行為跟本地 git-bash 是否一致 |
| `.github/workflows/docs.yml` | ⚠️ YAML valid · 本機 mkdocs build 綠 | 統一 Pages workflow（mkdocs `/` + mdBook `/book/`，取代已刪除的 deploy-book.yml）。mdBook 子路徑 base-url 尚未在 CI 端到端驗證（首次 deploy 後需實測 `/book/` 資產） |
| `walkthroughs/build-first-agent-in-7-steps.md` 的 Python 範例（~350 行）| ⚠️ 結構合理 | **完全沒實際跑過**——根據對 Anthropic SDK / LangGraph / Chroma / promptfoo 的理解寫出來，但沒從頭到尾 execute 一次。可能有：API 介面變動、套件版本相依、import path 微差 |
| `book.toml` mdBook 設定 | ⚠️ TOML valid | 沒實際 build 過完整 site |
---
## ❌ 完全沒測（design / template，等實際使用才會發現問題）
| 項目 | 為什麼沒測 |
|---|---|
| `scripts/build-pdf.sh` 跑出來的 PDF 視覺品質 | 需要 pandoc + xelatex + Noto Sans CJK 全套，本地環境沒裝 |
| GitHub Pages 上的 mdBook hosted 版 | repo Settings 還沒切到 GitHub Actions source（user 手動步驟） |
| 第一個 PDF release | 需要先跑 build-pdf.sh，沒做 |
| `.github/launch-checklist.md` 內所有「啟用 Discussions / 提交到 awesome lists / 寫 launch posts」項目 | 全部還沒做 |
---
## 對社群貢獻者的建議
如果你是第一個真的要跑某個 build / workflow 的人：
1. **跑 `bash scripts/build-pdf.sh` 之前**：先按 `scripts/README.md` 把字型裝好；輸出 PDF 之後實際開來看 CJK / mermaid block 有沒有正常
2. **跑 `bash scripts/build-mdbook.sh` 之前**：先 `cargo install mdbook mdbook-mermaid` 並在 repo root 跑 `mdbook-mermaid install .`；推上去前先本地 `--serve` 看一下
3. **試 walkthrough 的 Python**：建議用一個全新環境（venv），照 Stage 0 的一次性 install 跑完，遇到任何 import / API 不符的，**請開 issue + PR**——因為這就是「第一手實測」價值最高的時刻
4. **觸發 CI lint workflow**：開個 throwaway PR 改 `stages/01-llm-basics.md`，故意加 `教程` 這個禁用詞，看 banned-words job 有沒有正常 fail。如果沒抓到，調整 grep 邏輯
5. **Deploy book 第一次**：repo Settings → Pages → Source: GitHub Actions，然後 push 一次 commit 讓 workflow 跑。看 Actions tab 看結果
---
## 為什麼 maintainer 沒全部 test
老實說：
- **Build 工具鏈成本**：pandoc + xelatex + Noto Sans CJK 一套裝下來要 1-2 GB + 1-2 小時。不在 launch-blocking 路徑上時不值得本地裝
- **AI walkthrough 的 LangGraph / Chroma 等套件**：版本日新月異；今天測完明天可能就過期。所以選擇用「**對著官方 API 文件寫，註明可能要對現在版本調整**」的策略
- **CI workflow**：在真 PR 上才會觸發；沒第一個外部 PR 之前是 false-positive 還是 fully working 都看不出來
這份 repo 是 **「ship-able skeleton」**——所有結構都對、所有 metadata 都驗證過、所有 prose 都過 review，但**第一次實際跑 build / deploy / walkthrough 還是會發現坑**。
第一個踩到坑的人請開 issue + PR——這正是社群協作的價值所在。
---
## 修這份 testing status
每次跑過某個項目後，把上面表格的 ⚠️ 改成 ✅ 並補「證據」欄。
真實「跑過 + 有 observable output」才算 ✅，「我覺得 OK」不算。
.github/channel-partners.md
+135
View File
@@ -0,0 +1,135 @@
# Channel Partners — Outreach Tracking
> Single source of truth for **awesome-agentic-ai-zh** channel-partner outreach.
> Per-target pitch templates live in `.github/outreach/<slug>.md`.
> Maintainer: @WenyuChiou (个人 maintainer; rule: 1-2 sends/day max).
---
## Status enum
| Status | Meaning |
|---|---|
| `not contacted` | Pitch drafted in `outreach/<slug>.md`, nothing sent yet |
| `contacted` | Outbound sent (issue/PR/email) — awaiting response |
| `replied-positive` | Partner replied; discussion in progress; no commit yet |
| `replied-negative` | Partner declined or asked to redirect |
| `merged-or-listed` | Cross-link landed (PR merged / featured / listed) |
| `ghosted` | No reply in ≥ 2 weeks; one ping sent then dropped |
| `cooldown` | Don't contact for ≥ 30 days (over-asked, restructuring, etc.) |
## Outreach matrix
| # | Target | Channel | Status | Date contacted | Outcome | Date confirmed | Notes |
|---|---|---|---|---|---|---|---|
| 1 | [Datawhale](outreach/datawhale.md) | GitHub issue | not contacted | — | — | — | Already cite Hello-Agents Extra05/08 in our cookbook |
| 2 | [liyupi/ai-guide](outreach/liyupi.md) | GitHub PR | not contacted | — | — | — | ★13k mainland resource hub |
| 3 | [HuggingFace 中文社群](outreach/huggingface-zh.md) | HF community/discuss | not contacted | — | — | — | English ecosystem hub w/ growing zh segment |
| 4 | [LangChain (kyrolabs/awesome-langchain)](outreach/langchain-ai.md) | GitHub PR | not contacted | — | — | — | Stage 4 covers LangChain; §11 lists Langchain-Chatchat |
| 5 | [hesreallyhim/awesome-claude-code](outreach/awesome-claude-code.md) | GitHub **issue** | not contacted | — | — | — | ⚠️ Reorg STILL incomplete (verified 2026-05-21: README TOC is a placeholder; resources now live in `THE_RESOURCES_TABLE.csv` + a submission template). Keep parked — do not spend a send here yet |
| 6 | [punkpeye/awesome-mcp-servers](outreach/awesome-mcp-servers.md) | GitHub PR | contacted | 2026-05-09 | — | — | [PR #6135](https://github.com/punkpeye/awesome-mcp-servers/pull/6135). 2026-05-10: addressed bot name-check ([6f711ec](https://github.com/WenyuChiou/awesome-mcp-servers/commit/6f711ec3)) + replied to glama/emoji bot warnings ([comment](https://github.com/punkpeye/awesome-mcp-servers/pull/6135#issuecomment-4416517075)). Awaiting punkpeye human review. |
| 7 | [Zhipu BigModel community](outreach/zhipu.md) | dev community / 知乎 | not contacted | — | — | — | Inviting them to PR a Zhipu agent entry to §11 |
| 8 | [Moonshot Kimi](outreach/moonshot.md) | dev community / 知乎 | not contacted | — | — | — | Inviting them to PR a Kimi agent entry to §11 |
| 9 | [travisvn/awesome-claude-skills](https://github.com/travisvn/awesome-claude-skills) | GitHub PR | contacted | 2026-05-21 | — | — | [PR #754](https://github.com/travisvn/awesome-claude-skills/pull/754) opened 2026-05-21 — entry in `### Written Tutorials`, framed around Stage 5 (Claude Code ecosystem). Fit is moderate (Claude-Skills-specific list); awaiting maintainer review |
| 10 | [WangRongsheng/awesome-LLM-resources](https://github.com/WangRongsheng/awesome-LLM-resources) | GitHub PR | contacted | 2026-05-21 | — | — | [PR #121](https://github.com/WangRongsheng/awesome-LLM-resources/pull/121) opened 2026-05-21 — entry added to `## 课程 Course` (beside mlabonne/llm-course). Maintainer active; awaiting review |
| 11 | [AiHubCN/Awesome-Chinese-LLM](https://github.com/AiHubCN/Awesome-Chinese-LLM) | GitHub PR | not contacted | — | — | — | ★22k, pushed today, no license (yellow flag). Long TOC — need to browse README before deciding section. Lower priority due to license uncertainty |
## Sequencing rule
**Pace: 1-2 outbound sends per day.** Reasoning:
- Replies need to be handled. If we batch-send all 8 in one day, we can't respond
to early-positive replies before they cool.
- Multiple open conversations dilute attention; one-at-a-time keeps quality.
- If 5 replies land in week 1, that's a good problem; if 0 land, we don't burn
all our cards before learning what's not working.
Suggested first-week order (low-risk → high-risk, **revised 2026-05-09**
after upstream-target audit caught the awesome-claude-code reorg):
1. **Day 1**: [#6 punkpeye/awesome-mcp-servers PR](outreach/awesome-mcp-servers.md)
— has `## Tutorials` section, ★86k repo, reciprocal cite already exists.
Lowest-risk concrete-action target.
2. **Day 2**: [#5 awesome-claude-code **issue**](outreach/awesome-claude-code.md)
— repo mid-reorg, no PR-able sections; open an issue parking the proposal
for when their new TOC lands.
3. **Day 3**: [#1 Datawhale](outreach/datawhale.md) — most strategic for zh-Hans
reach (we cite Hello-Agents Extra05/08).
4. **Day 4**: [#2 liyupi](outreach/liyupi.md) — high reach if accepted (★13k
resource hub).
5. **Day 5**: [#4 LangChain (kyrolabs/awesome-langchain)](outreach/langchain-ai.md).
6. **Day 6**: pause — review responses to date.
7. **Day 7+**: [#3 HuggingFace](outreach/huggingface-zh.md), then
[#7 Zhipu](outreach/zhipu.md), [#8 Moonshot](outreach/moonshot.md) only
after digesting earlier feedback.
8. **Day 8+ (added 2026-05-10 retroactively)**: targets 9-11 (`travisvn/awesome-claude-skills`,
`WangRongsheng/awesome-LLM-resources`, `AiHubCN/Awesome-Chinese-LLM`) — discovered they were
on `.github/launch-checklist.md` from day 1 but missing from this outreach matrix. Pitch
files not yet drafted; use awesome-mcp-servers template as base when ready. Prioritize
travisvn (cleanest fit, explicit Tutorials section).
## Update protocol
- Always update this matrix when contacted / received reply / closed.
- Use `git commit -m "outreach: status update for <target> (<status>)"` so the
log is greppable.
- Dates: ISO format `YYYY-MM-DD`.
- Notes: 1-2 lines max — full context lives in the per-target `outreach/<slug>.md`.
## What NOT to do
- ❌ Bulk-send same template to all 8 in one day — looks like spam
- ❌ Lead with star count (★525) — small to ★1k+ partners; lead with scope
- ❌ Promise things we won't ship (e.g., "we'll add X if you cross-link")
- ❌ Ping after one reply — give 5+ business days
- ❌ Pitch via Discord DM unless explicitly invited (follow each project's
preferred contact channel; Discord DM cold = annoying)
- ❌ Edit pitch templates without recording the change in the file's git history
## Success indicators
Order by signal strength (top = stronger):
1. **Cross-link landed** in their canonical README / docs / awesome-list
2. **Public mention** (their tweet / post / blog cites us)
3. **Reciprocal listing** in their tutorials/learning section
4. **Soft acknowledgment** — they replied positively but no concrete action
If by **2026-06-01** no signal #1-3 has landed across all 8: pause outreach,
audit the pitch tone (likely too founder-y, not enough technical specifics).
---
## English-audience launch (added 2026-05-17)
Rationale: 14-day traffic is ~100% Chinese-social (Threads #1 external
referrer); zero English dev-channel inbound (no HN / Reddit / lobste.rs
/ newsletter). English content is 99.6% native (0.4% CJK measured) but
was under-promoted. Pre-req DONE this round: README positioning reframed
(trilingual / English fully maintained) + GitHub description/topics
de-zh-gated (commit b4bb862). Drafts ready — maintainer posts manually.
| # | Target | Channel | Status | Draft | Notes |
|---|---|---|---|---|---|
| E1 | Hacker News | Show HN (one shot) | not contacted | [hacker-news.md](outreach/hacker-news.md) | Highest single-spike; weekday AM US-Eastern; author first-comment pre-empts "why a list"/"MT slop" |
| E2 | r/AI_Agents | Reddit self-post | not contacted | [reddit.md](outreach/reddit.md) | Primary sub; exact audience |
| E3 | r/LocalLLaMA | Reddit self-post | not contacted | [reddit.md](outreach/reddit.md) | Local-LLM-angle variant |
| E4 | r/ClaudeAI | Reddit self-post | not contacted | [reddit.md](outreach/reddit.md) | Ecosystem-depth variant |
| E5 | r/learnmachinelearning | Reddit self-post | not contacted | [reddit.md](outreach/reddit.md) | Resource-framing variant |
| E6 | TLDR AI / Ben's Bites / Latent Space / LWiAI | Newsletter tip | not contacted | [newsletters-en.md](outreach/newsletters-en.md) | Submit AFTER a HN/Reddit signal to reference |
| E7 | kyrolabs/awesome-agents · Shubhamsaboo/awesome-llm-apps | GitHub PR | not contacted | [awesome-lists-en.md](outreach/awesome-lists-en.md) | Passive; PR desc MUST state "trilingual/EN-maintained" or `-zh` gets mis-filed. (e2b-dev/awesome-ai-agents dropped 2026-05-21 — ~15-month-stale, see awesome-lists-en.md Don'ts) |
### English sequencing rule
1. **First**: README positioning + GitHub metadata (✅ done b4bb862) —
without it every English referral bounces on "this is Chinese-only".
2. Then **one** of E1/E2 (HN or r/AI_Agents) — not both same day; gauge response.
3. E3–E5 spaced 1 sub/day, each tailored (identical body = spam-flag).
4. E6 newsletters only AFTER an E1–E5 signal exists ("already trending").
5. E7 awesome-list PRs anytime (passive, low-risk), excluding the two
already tracked above (punkpeye #6, travisvn #9).
Same "What NOT to do" rules as the zh matrix apply: no star-count lead,
no overclaim, no upvote/star asks, reply to comments for ~24h, never
mass-paste identical text.
.github/launch-checklist.md
+84
View File
@@ -0,0 +1,84 @@
# Launch checklist
> 這份是 maintainer 內部用的——repo 從 Phase 5 ship 到開始**主動推廣**前要走完的一次性步驟。
---
## ✅ Pre-launch（已完成）
- [x] Phase 1-5 內容 ship（134 entries、style guide、walkthrough、Mermaid 圖）
- [x] `.github/` issue + PR template
- [x] `resources/style-guide.md` zh + en
- [x] `scripts/check-links.py` + `refresh-stars.py` 可跑
- [x] CI lint workflow（zh-Hans slip + overclaim 自動檢查；每月跑 link-rot + star-drift）
## 🟡 Pre-launch（一次性手動 setup）
- [ ] **GitHub Pages**：repo Settings → Pages → Source: **GitHub Actions**
- 啟用後，`.github/workflows/docs.yml` 推 main 會自動 build mkdocs（`/` 首頁）+ mdBook（`/book/`）並 deploy 到 `https://wenyuchiou.github.io/awesome-agentic-ai-zh/`（單一 workflow 擁有 Pages）
- [ ] **GitHub Discussions**：repo Settings → Features → enable Discussions
- Categories 建議：
- 🙋 Q&A — 學習問題
- 💡 Project nominations — 推薦新 project（先討論再 PR）
- 📚 Stage discussion — 每個 stage 一個 thread
- 🎯 Show & tell — 走完 stage 的人 share 自己的成果
- [ ] **第一次 PDF release**：本地跑 `bash scripts/build-pdf.sh`，把 `dist/awesome-agentic-ai-zh.pdf` 上傳到 GitHub Release v1.0
- [ ] **GitHub Releases**：以 `phase-5` tag 為起點建第一個 release，附 PDF
## 🟢 Soft launch（小範圍宣傳）
- [ ] 跟 `WenyuChiou` 朋友圈分享（內測）
- [ ] 修 1-2 輪內測回饋（issue 處理）
## 🚀 Public launch（推廣）
### 提交到中文社群 awesome list
- [ ] [`AiHubCN/Awesome-Chinese-LLM`](https://github.com/AiHubCN/Awesome-Chinese-LLM) — 開 PR 加進 catalog（教學資源 / 學習路線 section）
- [ ] [`WangRongsheng/awesome-LLM-resources`](https://github.com/WangRongsheng/awesome-LLM-resources) — 開 PR
- [ ] [`hesreallyhim/awesome-claude-code`](https://github.com/hesreallyhim/awesome-claude-code) — 開 PR（learning resources）
- [ ] [`travisvn/awesome-claude-skills`](https://github.com/travisvn/awesome-claude-skills) — 開 PR（learning resources）
> 📡 **Channel partner outreach**：完整 outreach 計畫（8 個目標 × 3 種 pitch 變體 + 1-2 sends/day pacing）跟追蹤 matrix 在 [`.github/channel-partners.md`](channel-partners.md)。各 target 的 pitch 草稿在 [`.github/outreach/<slug>.md`](outreach/)。
### 寫 launch 文章
- [ ] **Threads 短版**（2-3 則）— 重點：134 個 project、跨 stage walkthrough、誠實時程
- [ ] **dev.to 長版**（一篇 1000-1500 字）— 寫「為什麼平鋪 awesome 不夠用、結構化路線怎麼做」
- [ ] （選）**個人部落格** — 同樣內容深度版
### 中文 LLM 社群
- [ ] Datawhale 微信社群（如果有 zh-TW 受眾）
- [ ] Hacker News（zh-TW 故事性夠強的話）
- [ ] r/LocalLLaMA、r/MachineLearning（看 reddit 接受度）
## 🔁 Post-launch（持續）
這份是**參考節奏，不是 SLA**——能做就做、忙起來放著也沒關係。社群開放型 repo 不需要強制定期維護。
- 有空時：review issue / 合併 PR
- 偶爾跑：CI 已設定每月自動跑 link rot + star drift（被動的、不用人工）
- 想做的時候：加幾個新 entry、清掉幾個 archived repo
- 不必排定期程：phase milestone、新增 branch 等大改——有 traction 訊號再做
---
## 📊 成功指標（不是目標、是訊號）
排序大致按 fingerprint 強度——前面比後面更可靠。
1. **每月新 issue / PR 數量**（活躍社群訊號）
2. **stage maintainer 自薦數**（深度 engagement）
3. **被引用 / 被收錄到其他 awesome list 數**
4. **Star 數**（弱訊號，容易被刷；只看趨勢、不看絕對值）
---
## 不該做的（deliberate "no"s）
- ❌ 為了上熱門就刷 SEO 關鍵字
- ❌ 為了 star 數加 low-quality entry
- ❌ 把 PR 合進 main 而不 review（即使是 typo 也要 review）
- ❌ 自家 repo 重新加回 catalog（先前刻意移除）
- ❌ 接 sponsor / affiliate link（會影響推薦獨立性）
.github/outreach/_send-day-packages.md
+237
View File
@@ -0,0 +1,237 @@
# Send-Day Packages (ready to paste)
> **What this file is**: the copy-paste operational source for outreach submissions. Open it on a send-day, pick ONE target, refresh the stats line, paste, submit. The per-target `.md` files in this folder hold the *positioning rationale* (why each target, pitch angle); **this** file holds the *exact content to send*.
>
> **Canonical numbers as of 2026-06-08** (baked into every package below):
> - Trilingual: **繁中 (canonical) / English / 简中** — all three hand-maintained, not machine-translated
> - **8 stages** (Stage 0 → Stage 8; Stage 5 + Stage 8 are shared hubs) · 2 tracks · 5 extension paths
> - **240+ curated resources** · MIT · CI lints links + anchors + banned-words on every PR
> - Repo: https://github.com/WenyuChiou/awesome-agentic-ai-zh · Docs: https://wenyuchiou.github.io/awesome-agentic-ai-zh/
> - ★ ≈ **1.9k** — **refresh on the day you send** (`gh repo view WenyuChiou/awesome-agentic-ai-zh --json stargazerCount`). Stale stars in a PR read as careless.
>
> **Cadence (do NOT blast)**: one target per send-day, 1–2 sends/day max. Wait for a reply or ~1 week before the next. All submissions are done by you (maintainer identity); I prepare content only.
---
## Status board
| # | Target | ★ | Channel | Section | Lang | Fit | Status |
|---|---|---|---|---|---|---|---|
| A | Hannibal046/Awesome-LLM | 18k+ | PR | LLM Tutorials and Courses | en | good | ready (last batch) |
| B | HqWu-HITCS/Awesome-Chinese-LLM | 20k+ | PR | ### 7. LLM教程 | zh-Hans | good | ready (last batch) |
| C | kyrolabs/awesome-langchain | 9k+ | PR | Learn → Notebooks | en | good | ready |
| D | liyupi/ai-guide | 14k+ | PR | AI 学习路线 / 相关资源 | zh-Hans | good | ready |
| E | datawhalechina/hello-agents | 55k+ | **Issue** | (cross-link, not catalog) | zh-Hans | good | ready |
| F | Jenqyang/Awesome-AI-Agents | — | PR | Related | en | medium | ready (looser fit — see note) |
| — | AiHubCN/Awesome-Chinese-LLM | — | — | — | — | — | **SKIP** (fork of B) |
**Nudges pending** (your existing open PRs — you run these): #121 WangRongsheng, #754 travisvn — see bottom.
---
## A — Hannibal046/Awesome-LLM (PR)
**Section**: `## LLM Tutorials and Courses` (or the closest "Other Awesome Lists" subsection if the maintainer prefers).
**Entry line**:
```markdown
* [awesome-agentic-ai-zh](https://github.com/WenyuChiou/awesome-agentic-ai-zh) - Trilingual (zh-TW / English / zh-Hans) learning roadmap for agentic AI, from LLM basics to multi-agent systems, with 240+ curated resources and runnable examples.
```
**PR title**: `Add awesome-agentic-ai-zh (trilingual agentic-AI learning roadmap)`
**PR body**:
```markdown
Hi Hannibal046,
Adding awesome-agentic-ai-zh to LLM Tutorials and Courses (move it if another spot fits better).
It's a trilingual learning roadmap for agentic AI — Traditional Chinese (canonical), English, and Simplified Chinese, all three hand-maintained. The path runs from Stage 0 (what an LLM is, how tokens work) to Stage 8 (multi-agent orchestration, Computer Use / Browser Use / sandboxes), with 240+ curated resources and small runnable examples. MIT licensed; CI checks links and anchors on every PR.
Thanks for maintaining Awesome-LLM.
— Wenyu Chiou (individual maintainer)
```
---
## B — HqWu-HITCS/Awesome-Chinese-LLM (PR)
**Section**: `### 7. LLM教程` (nested format — match exactly, this repo uses 项目名称 / 地址 / 简介).
**Entry block**:
```markdown
* awesome-agentic-ai-zh:
* 地址:[https://github.com/WenyuChiou/awesome-agentic-ai-zh](https://github.com/WenyuChiou/awesome-agentic-ai-zh)
* 简介:三语(繁中 / English / 简中)agentic AI 学习地图,从 LLM 基础到多代理系统,8 个阶段 + 2 条学习路线 + 240+ curated 资源,附可跑的范例。MIT。
```
**PR title**: `添加 awesome-agentic-ai-zh(三语 agentic AI 学习地图)到 7. LLM教程`
**PR body**:
```markdown
你好,
想把 awesome-agentic-ai-zh 加到「7. LLM教程」。这是一份 agentic AI 的三语学习地图(繁中 canonical / 简中 / English,三语手工维护),8 个阶段从 LLM 基础排到多代理编排,每阶段标了预估时程、入门条件、该读什么,目前 240+ curated 资源,MIT 协议。
已按本项目格式提供链接与简介。觉得不合适直接关掉就好,谢谢维护这份清单。
— Wenyu(个人 maintainer)
```
---
## C — kyrolabs/awesome-langchain (PR)
**Section**: `## Learn → ### Notebooks` — place **right after** the existing `liaokongVFX/LangChain-Chinese-Getting-Started-Guide` line (keeps the two zh learning resources adjacent). There is **no** "Tutorials" section; do not create one.
**Diff**:
```diff
- [LangChain Chinese Getting Started Guide](https://github.com/liaokongVFX/LangChain-Chinese-Getting-Started-Guide): Chinese LangChain Tutorial for Beginners ![GitHub Repo stars](https://img.shields.io/github/stars/liaokongVFX/LangChain-Chinese-Getting-Started-Guide?style=social)
+ - [WenyuChiou/awesome-agentic-ai-zh](https://github.com/WenyuChiou/awesome-agentic-ai-zh): Trilingual (zh-TW / zh-Hans / en) 8-stage learning roadmap for agentic AI. Stage 4 walks through LangChain, LangGraph, AutoGen, CrewAI, and Smolagents with prerequisites, time estimates, and hands-on exercises ![GitHub Repo stars](https://img.shields.io/github/stars/WenyuChiou/awesome-agentic-ai-zh?style=social)
```
**PR title**: `Add awesome-agentic-ai-zh (trilingual learning roadmap) to Learn → Notebooks`
**PR body**:
```markdown
Hi kyrolabs maintainers,
Proposing [WenyuChiou/awesome-agentic-ai-zh](https://github.com/WenyuChiou/awesome-agentic-ai-zh) for **Learn → Notebooks**, next to the existing `liaokongVFX/LangChain-Chinese-Getting-Started-Guide` entry (same zh-learning surface).
Why it fits:
- Trilingual (zh-TW canonical · zh-Hans · en — all three hand-maintained, not MT), which fills a gap for non-English learners.
- Stage 4 (Agent Frameworks) walks new developers through LangChain / LangGraph / AutoGen / CrewAI / Smolagents with prerequisites, time estimates, and hands-on exercises.
- The §11 catalog has 7 Chinese-ecosystem entries including `chatchat-space/Langchain-Chatchat` and the LangChain Chinese Getting Started Guide already in your list.
Stats (refresh on send-day): ★1.9k, MIT licensed, rendered docs at https://wenyuchiou.github.io/awesome-agentic-ai-zh/. CI runs banned-word, link-rot, and anchor-integrity lints on every PR.
If a different section works better, happy to redirect. Thanks for maintaining awesome-langchain.
— Wenyu Chiou (individual maintainer)
```
> **Send-day stat refresh**: `gh repo view WenyuChiou/awesome-agentic-ai-zh --json stargazerCount,forkCount` + `gh api repos/WenyuChiou/awesome-agentic-ai-zh/traffic/views` if you want fresh visitor numbers.
---
## D — liyupi/ai-guide (PR)
**Section**: 「AI 学习路线」或「相关资源」(放哪边由 liyupi 决定). liyupi 偏好简体 + 大陆友善措辞,PR 用 zh-Hans。
**Entry line**:
```markdown
- [WenyuChiou/awesome-agentic-ai-zh](https://github.com/WenyuChiou/awesome-agentic-ai-zh) — agentic AI 的三语(繁中 / English / 简中)8 阶段学习地图,从 Stage 0 的 LLM 基础走到 Stage 8 的多代理编排,240+ curated 资源 + 可跑的范例,MIT。和 ai-guide 互补:ai-guide 找 project、这份找学习顺序。
```
**PR title**: `添加 awesome-agentic-ai-zh(三语 agentic AI 学习地图)到「AI 学习路线」`
**PR body**:
```markdown
你好 liyupi,
想把 [awesome-agentic-ai-zh](https://github.com/WenyuChiou/awesome-agentic-ai-zh) 加到「AI 学习路线」或「相关资源」section(放哪边你决定)。
这份是 agentic AI 的三语学习地图(繁中 canonical / 简中 / English,三语手工维护,不是机翻),8 个阶段从 Stage 0 的 LLM 基础排到 Stage 8 的多代理编排,每阶段标了预估时程、入门条件、该读什么,目前 240+ curated 资源,MIT 协议。
定位上和 ai-guide 互补,不是取代:ai-guide 是资源大全,这份补的是「该按什么顺序学」。常见读者是想学但不知道先学哪个的工程师,走完阶段后回 ai-guide 找具体 project 用。
觉得不合适直接关掉就好,谢谢你做的 ai-guide。
— Wenyu(个人 maintainer)
```
---
## E — datawhalechina/hello-agents (GitHub **Issue**, not a PR)
> This one is a **cross-link suggestion Issue** on the hello-agents repo, not a catalog entry. We already link Hello-Agents on our side (no strings); the issue just opens a reciprocal-link conversation.
**Repo**: https://github.com/datawhalechina/hello-agents → Issues → New issue
**Issue title**: `Cross-link 建议:一份会把读者导向 Hello-Agents 的结构化学习路线`
**Issue body**:
```markdown
你好 Datawhale 团队,
我在维护 [awesome-agentic-ai-zh](https://github.com/WenyuChiou/awesome-agentic-ai-zh) —— 一份 agentic AI 的三语(繁中 canonical / 简中 / English)8 阶段学习地图,240+ curated 资源,MIT。
我们这边已经把 Hello-Agents 放进了「走完前面阶段后的延伸阅读」(无条件,已经 ship)。读者主要是走完 Stage 4 之后想进 framework 跟 multi-agent 的人,Hello-Agents 正好是下一阶段最强的中文教材。
想问有没有可能做个双向 cross-link:
1. 我们已经 link 你们了。
2. 如果你们觉得合适,能不能在 Hello-Agents 的 README 或 docs 里提一句「想看更完整的学习路线可以参考 awesome-agentic-ai-zh」?
3. 或是 reverse PR:我们在中文圈那一节加 Hello-Agents 的正式 entry,你们 review。
不合适也完全 OK。谢谢你们把 Hello-Agents 做出来,这几年中文 agentic AI 学习的公共财都是你们扛的。
— Wenyu(PhD candidate · Lehigh,个人 maintainer)
```
> Note: WeChat 是 Datawhale 主要互动 channel,但 GitHub issue 比较可追踪。一周没回就放着,他们团队很忙、不要 ping。
---
## F — Jenqyang/Awesome-AI-Agents (PR)
> **Fit note (read before sending)**: this list has no Tutorials / Learning section. The closest home is `## Related`, but its visible subsection is "Paper-List Repo", which isn't a clean match for a learning roadmap. Send only if you're OK with the looser fit; the entry below leads with "happy to move it" so the maintainer can reslot. Check `CONTRIBUTING.md` in the repo first.
**Section**: `## Related` (maintainer to confirm exact subsection).
**Entry line** (matches their `* [Name](URL) - desc ![stars]` format):
```markdown
* [awesome-agentic-ai-zh](https://github.com/WenyuChiou/awesome-agentic-ai-zh) - Trilingual (Traditional Chinese / English / Simplified Chinese) 8-stage learning roadmap for agentic AI, from LLM basics to multi-agent systems, with 240+ curated resources and runnable examples. [![GitHub Repo stars](https://img.shields.io/github/stars/WenyuChiou/awesome-agentic-ai-zh?style=social)](https://github.com/WenyuChiou/awesome-agentic-ai-zh)
```
**PR title**: `Add awesome-agentic-ai-zh (trilingual agentic-AI learning roadmap) to Related`
**PR body**:
```markdown
Hi Jenqyang,
Proposing awesome-agentic-ai-zh for the Related section — happy to move it wherever fits best, I wasn't sure which subsection is right.
It's a trilingual learning roadmap for agentic AI: Traditional Chinese (canonical), English, and Simplified Chinese, all three hand-maintained rather than machine-translated. The structure runs from Stage 0 (what an LLM is, how tokens work) up to Stage 8 (multi-agent orchestration, Computer Use / Browser Use / sandboxes), with 240+ curated resources and small runnable examples.
The gap it fills: most agent lists, including yours, are catalogs you reach for once you know what you want. This is the "where do I start, and in what order" layer for people who don't yet. MIT licensed; CI checks links and anchors on every PR.
If it's not a fit, no problem at all. Thanks for maintaining the list.
— Wenyu Chiou (individual maintainer)
```
---
## SKIP — AiHubCN/Awesome-Chinese-LLM
**Do not submit.** It shares the repo name, the section structure (`7. LLM教程`), and the exact nested entry format with **HqWu-HITCS/Awesome-Chinese-LLM** (target B above). That's a fork/mirror signature. Submitting the same entry to both reads as duplicate/spam and dilutes the one that matters. Send B (the canonical HqWu-HITCS) only. If you ever confirm AiHubCN is genuinely independent **and** actively merges external PRs, reuse the B package verbatim — the format is identical.
---
## Nudges (your existing open PRs — run on a send-day, ~1 week apart)
Both are your own PRs, so these are yours to run. Polite single ping; if still no reply after another week, leave them.
```bash
# PR #121 — WangRongsheng/awesome-LLM-resources (zh-Hans)
gh pr comment 121 --repo WangRongsheng/awesome-LLM-resources \
--body "Hi,这个 PR 开了一段时间了,不知道有没有机会 review 一下?如果格式或 section 需要调整我随时改。谢谢!"
# PR #754 — travisvn/awesome-claude-skills (en)
gh pr comment 754 --repo travisvn/awesome-claude-skills \
--body "Gentle ping on this one — happy to adjust the entry or move it if a different section fits better. Thanks for maintaining the list!"
```
---
## After you submit
Tell me which target + the PR/issue URL, and I'll update the matrix in `channel-partners.md` (status: submitted → date + link). Keep the one-at-a-time cadence so none of these read as a coordinated blast.
.github/outreach/awesome-claude-code.md
+100
View File
@@ -0,0 +1,100 @@
# Outreach: hesreallyhim/awesome-claude-code
> **Status**: not contacted · **Channel**: GitHub **issue** (NOT PR — see note below)
> **Primary lang**: en
> **Last updated**: 2026-05-09
> **Repo**: https://github.com/hesreallyhim/awesome-claude-code (★ 47k+)
> ⚠️ **REPO IS MID-REORG (verified 2026-05-09)** — their current README says
> "The previous Table of Contents was no longer fit for purpose, so a new
> organizational system is being prepared." There are no live sections to
> PR an entry into. **Don't open a PR.** Open an **issue** instead, parking
> the proposal for when the new TOC lands.
**Why this target**: We already cite their list in our README's "Related projects" section (and in zh-Hans / zh-TW counterparts). Reciprocal listing is natural. They're the canonical Claude Code awesome-list with ★43k.
**Pitch angle**: We're a **structured learning roadmap** complement to their flat catalog. Stage 5 of our roadmap is dedicated to the Claude Code ecosystem (MCP, Skills, Plugins).
**Their counter-value**: Reciprocal cross-link; their readers get a learning order; we get exposure to Claude Code power users.
---
## Variant 1 — Social post (X, ~280 chars)
```
For folks browsing @hesreallyhim's awesome-claude-code list — just published
an 8-stage trilingual learning roadmap that walks Stage 0 (foundations) → Stage 5
(Claude Code: MCP / Skills / Plugins) → Stage 8 (production).
★525 week 1 · 240+ curated projects · zh-TW / zh-Hans / en
🔗 github.com/WenyuChiou/awesome-agentic-ai-zh
```
## Variant 2 — GitHub **issue** (200-300 words) [USE THIS, NOT A PR]
**Issue title**: Proposal: add a "Learning Resources" / "Tutorials" section in the new TOC — would awesome-agentic-ai-zh fit?
**Issue body**:
```markdown
Hi @hesreallyhim,
Saw the reorg notice on the README — congrats on the cleanup, the previous
TOC had drifted hard. Holding off on opening a PR until the new TOC lands.
Wanted to surface a proposal for when you're ready:
I maintain [awesome-agentic-ai-zh](https://github.com/WenyuChiou/awesome-agentic-ai-zh)
— a trilingual (zh-TW canonical · zh-Hans · English) 8-stage learning roadmap
for agentic AI. **Stage 5 is dedicated entirely to the Claude Code ecosystem**
(MCP, Skills, Plugins, Hello-World walkthroughs, 65+ entry integration catalog
by use case).
awesome-claude-code is already in our `Related projects` section
([our README](https://github.com/WenyuChiou/awesome-agentic-ai-zh/blob/main/README.md))
— we cite you as the go-to flat catalog. We'd be the structured learning
complement.
Two questions for the new TOC design:
1. Will the new TOC have a "Learning Resources" / "Tutorials" / "Curricula"
section? If yes, a one-line entry there would close the reciprocal loop.
2. If the new TOC keeps the list strictly tooling-only, totally understand
— happy to drop this. No follow-up needed in that case.
No urgency. Reply when the new TOC is done. Thanks for maintaining this list
— it's a public good for the Claude Code community.
Stats for credibility (week 1): 6,869 views / 3,185 unique visitors / 1,099
clones / 408 unique cloners / 50 forks / 3 community contributors. MIT,
trilingual translation discipline, CI lint on every PR.
— Wenyu (PhD candidate, individual maintainer)
```
## Variant 3 — DM / Twitter reply (150 words)
```
Hey @hesreallyhim — your awesome-claude-code list is already in our README's
"Related projects". Built a complement: a trilingual (zh-TW / zh-Hans / en)
8-stage learning roadmap, with Stage 5 dedicated to Claude Code (MCP, Skills,
Plugins, walkthroughs, 65+ integrations grouped by use case).
★525 in week 1, MIT licensed. If a reciprocal link in awesome-claude-code's
Learning Resources section makes sense, just opened a PR
(github.com/hesreallyhim/awesome-claude-code/pull/<NN>). No worries if not.
— Wenyu
```
---
## Notes
- **Repo status as of 2026-05-09**: README is a placeholder ("Update in
progress"; TOC marked "I. TODO"). Maintainer @hesreallyhim is rebuilding
the organizational system. **OPEN AN ISSUE, NOT A PR.**
- The issue is a parking proposal — re-engage when the new TOC ships
- @hesreallyhim historically responsive (~3 days); during reorg, expect slower
- If they reply "the new TOC won't have a learning resources section" — thank
them, drop it, move on. Don't push.
- After they reply (positive or negative), update `.github/channel-partners.md`
.github/outreach/awesome-lists-en.md
+60
View File
@@ -0,0 +1,60 @@
# Outreach draft — English awesome-lists (get listed)
> **Status**: draft, not submitted. Passive reach (be listed in lists
> English builders already browse). Each is a PR to their list's
> learning/tutorials section. The `-zh` repo name reads as "Chinese-only"
> on these lists — the PR description must say "trilingual, English fully
> maintained" up front or it gets filed under a zh-only section.
## Targets
| Target | Section to PR into | Notes |
|---|---|---|
| [kyrolabs/awesome-agents](https://github.com/kyrolabs/awesome-agents) | learning / guides | Agent-specific. Verified live 2026-05-21 (★ 2.6k+, pushed 3d prior) — good fit |
| [Shubhamsaboo/awesome-llm-apps](https://github.com/Shubhamsaboo/awesome-llm-apps) | tutorials / learning | ★111k reach, but it is an *apps* list — confirm it has a learning/tutorials section before PR, else it gets rejected as out-of-scope |
| [punkpeye/awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers) | Tutorials | ALREADY in progress (PR #6135, see channel-partners.md #6) — don't double-submit |
| [travisvn/awesome-claude-skills](https://github.com/travisvn/awesome-claude-skills) | 📖 Tutorials & Guides | ALREADY tracked (channel-partners.md #9) — don't double-submit |
## PR title
```
Add awesome-agentic-ai-zh — trilingual staged roadmap (LLM basics → multi-agent)
```
## PR description (entry + rationale)
```
Adding **awesome-agentic-ai-zh** to the [learning/tutorials] section.
What it is: a staged learning roadmap for agentic AI (not a flat list) —
8 stages LLM-basics → multi-agent + Computer/Browser Use, 2 tracks
(use CLI agents vs build your own), 5 audience branches, 240+ curated
projects, runnable exercises. MIT.
Why it fits this list: it's the "where do I start / in what order"
companion to the reference lists already here.
Note on the name: the repo is `-zh` (Chinese-origin) but it is
**trilingual and the English edition is fully maintained** (~0.4% of
English lines carry any CJK; English-native required reading per stage;
CI-checked). Please file it under the general
learning/tutorials section, not a zh-only sub-section.
Repo: https://github.com/WenyuChiou/awesome-agentic-ai-zh
Rendered site: https://wenyuchiou.github.io/awesome-agentic-ai-zh/
```
## Suggested one-line list entry (match each list's existing format)
```
- [awesome-agentic-ai-zh](https://github.com/WenyuChiou/awesome-agentic-ai-zh) — Trilingual staged roadmap: LLM basics → multi-agent, 8 stages + 2 tracks + 240+ curated projects. MIT.
```
## Don'ts
- ❌ Don't PR to a list whose CONTRIBUTING forbids "roadmap/aggregate" entries — read it first.
- ❌ Don't double-submit to punkpeye / travisvn (already tracked).
- ❌ Don't PR to `e2b-dev/awesome-ai-agents` — verified 2026-05-21, last
push 2025-02-26 (~15 months stale / effectively abandoned); a PR there
will not be merged. Removed from the target table for this reason.
- ❌ Don't omit the "trilingual / English-maintained" note — the `-zh`
name otherwise gets it mis-filed or rejected as out-of-scope.
.github/outreach/awesome-mcp-servers.md
+100
View File
@@ -0,0 +1,100 @@
# Outreach: punkpeye/awesome-mcp-servers (PRIMARY)
> **Status**: not contacted · **Channel**: GitHub PR
> **Primary lang**: en
> **Last updated**: 2026-05-09
> **Primary repo**: https://github.com/punkpeye/awesome-mcp-servers (★86k+, MIT, has "Tutorials" section)
> **Secondary (skip for now)**: wong2/awesome-mcp-servers (★4k, MIT, **server-only policy** — no Tutorials section, off-policy for us)
**Why this target**: We already cite both in our README's "Related projects" section (mutual benefit baked in). punkpeye is the canonical large MCP catalog and **has an explicit `## Tutorials` section** that fits us. wong2 is a stricter server-only fork — we'll skip that one to respect their list shape.
**Pitch angle**: Their readers want to use MCP servers; we teach them how MCP works first (Stage 5.2 of our roadmap). Our §5.2 walkthrough → their flat catalog is a natural funnel.
**Their counter-value**: Reciprocal cross-link; better onboarding for their ★86k readers.
---
## Variant 1 — Social post (X, ~280 chars)
```
Browsing the awesome-mcp-servers catalog and unsure where to start? Stage 5.2
of awesome-agentic-ai-zh walks through MCP from concept to first install in
~2 hours, then hands you off to wong2/awesome-mcp-servers for the actual
catalog browsing.
★525 week 1 · MIT
🔗 github.com/WenyuChiou/awesome-agentic-ai-zh
```
## Variant 2 — GitHub PR (200-300 words)
**Target file**: `README.md` — `## Tutorials` section
**PR title**: Add awesome-agentic-ai-zh to Tutorials — trilingual 8-stage learning roadmap
**Diff** (insert in alphabetical or chronological position within `## Tutorials`):
```diff
+ - [awesome-agentic-ai-zh](https://github.com/WenyuChiou/awesome-agentic-ai-zh)
+ — Trilingual (zh-TW · zh-Hans · en) 8-stage learning roadmap. Stage 5.2 is
+ a dedicated walkthrough of MCP (concept → first install → writing your
+ own server), with prerequisites and time estimates. Catalog includes 65+
+ integrations grouped by use case.
```
**PR description**:
```markdown
Hi @punkpeye,
awesome-mcp-servers is already in our `Related projects` section
([README.md](https://github.com/WenyuChiou/awesome-agentic-ai-zh/blob/main/README.md))
— we cite you as the primary catalog for MCP server discovery.
Our repo is the **structured learning complement**:
- Stage 5.2 of our roadmap is a **dedicated MCP walkthrough**: concept →
first install → writing your own server, with hands-on exercises and time
estimates
- After Stage 5.2, readers are sent to your catalog to find specific servers
for their stack
- Trilingual (zh-TW / zh-Hans / en), MIT, ★525 week 1
Targeting your `## Tutorials` section (line ~XX in README) since this is a
"how to learn MCP" resource, not a server. If a different section fits
better, just redirect — happy to update.
Stats (week 1): 6,869 views / 3,185 unique / 1,099 clones / 408 unique cloners
/ 50 forks. CI runs banned-word audit + link-rot check on every PR.
— Wenyu (PhD candidate, individual maintainer)
```
## Variant 3 — DM / Twitter (150 words)
```
@punkpeye — your awesome-mcp-servers list is already in our README's
"Related projects". I run awesome-agentic-ai-zh: a trilingual 8-stage
learning roadmap with Stage 5.2 dedicated to MCP (walkthrough → install →
writing your own server, with cost/time estimates).
After Stage 5.2 our readers are sent to your catalog. Reciprocal link in
your Tutorials section would be natural — opened a PR (<link>). Close it
if it doesn't fit.
— Wenyu
```
---
## Notes
- **Targeting punkpeye, not wong2** — punkpeye has a `## Tutorials` section
(★86k repo, very large reach); wong2 is server-only-policy by design (★4k,
no tutorials section, off-policy for our pitch)
- Confirm the line number / position of `## Tutorials` in punkpeye's README
before opening PR — alphabetical sort within the section is the convention
- punkpeye is responsive — PRs typically reviewed within ~7 days
- If they accept, mirror cross-cite by ensuring our README still references
them (already done as of 2026-05-09)
- If they redirect to a different section, follow their guidance — don't
push back
.github/outreach/datawhale.md
+82
View File
@@ -0,0 +1,82 @@
# Outreach: Datawhale (datawhalechina)
> ⚠️ **Send content is now canonical in [`_send-day-packages.md`](_send-day-packages.md)** (package E — current numbers: 8 stages / 240+ resources). This file is kept for positioning rationale; do not paste its older issue/stats blocks directly.
> **Status**: not contacted · **Channel**: GitHub issue + (later) WeChat group
> **Primary lang**: zh-Hans
> **Last updated**: 2026-05-09
> **Decision-maker**: Datawhale 開源教學團隊 (open-source curriculum team)
**Why this target**: Datawhale 是中國大陸最有影響力的 AI 教學社群之一；他們的 [`hello-agents`](https://github.com/datawhalechina/hello-agents) (★ 60k+) 在中文 agentic AI 圈子幾乎人人在用。我們的 Stage 5 cookbook 已經 cite 他們的 Extra05 / Extra08——cross-link 對雙方都加分。
**Pitch angle (我們對他們)**: 我們的 7 階段三語學習地圖把 Hello-Agents 放在 Stage 5 / 6 的位置——讀完我們前 4 階段的 LLM 基礎、prompt、context engineering 之後再進 Hello-Agents 會吸收得更好。我們等於是他們的「pre-flight」入口。
**Their counter-value (他們對我們)**: ★45k 的影響力；如果他們在 Hello-Agents README / docs 提我們一句「想看更完整的學習路線可以參考...」，能帶可觀流量。
---
## Variant 1 — Social post (Weibo / Threads / X，~280 字)
> 「想用 Hello-Agents 但不確定該從哪裡入手？」
>
> awesome-agentic-ai-zh 把 agentic AI 切成 7 階段（Stage 0 基礎 → Stage 7 production），每階段都標註預估時程跟入門條件。Stage 5/6 直接接到 @datawhalechina 的 Hello-Agents Extra05/08。
>
> 三語（zh-TW / zh-Hans / en）· 145+ curated projects · MIT
> 👉 https://github.com/WenyuChiou/awesome-agentic-ai-zh
## Variant 2 — GitHub issue (200-300 字)
**Title**: Cross-link suggestion: structured learning path that points readers to Hello-Agents
```
Hi Datawhale 團隊！
我在維護 [awesome-agentic-ai-zh](https://github.com/WenyuChiou/awesome-agentic-ai-zh)
——一份中文 agentic AI 的 7 階段三語學習地圖（zh-TW canonical / zh-Hans / en，145+
curated projects，MIT），第一週累積 ★525、3,185 unique visitors、1,099 clones。
我們的 Stage 5 cookbook 已經把 Hello-Agents 的 Extra05（記憶 + RAG 概覽）跟 Extra08
（多代理）放進 reading list（[cookbook.md](https://github.com/WenyuChiou/awesome-agentic-ai-zh/blob/main/resources/cookbook.md)），
作為走完前 4 階段 LLM 基礎之後的延伸閱讀。
**想 propose 一個雙向 cross-link**：
1. 我們這邊已經 link 你們了（無條件，已經 ship）
2. 如果你們覺得合適——能不能在 Hello-Agents 的 README 或 docs 裡加一句「想看更
完整的 agentic AI 學習路線，可以參考 awesome-agentic-ai-zh」？
3. 或是 reverse PR：我們在 §11 中文圈專用 加 Hello-Agents 的正式 entry（你們
review）？
我們這邊的讀者主要從 Stage 4 之後想進 framework 跟 multi-agent，Hello-Agents
正好是下一階段最強的中文教材。如果不合適也完全 OK，謝謝你們把 Hello-Agents
做出來——它本身就是中文社群的公共財。
— Wenyu (PhD candidate · Lehigh CEE，個人 maintainer)
```
## Variant 3 — Email / WeChat DM (150 字)
```
Hi Datawhale 團隊好，
我是 awesome-agentic-ai-zh 的維護者 Wenyu。這份 repo 是中文 agentic AI 的 7 階段
三語學習地圖（145+ projects，三語齊全），上線一週 ★525。
我們 Stage 5 cookbook 已經把 Hello-Agents 的 Extra05/08 放進延伸閱讀清單。想跟你們
聊聊有沒有可能 reciprocal cross-link 的可能——細節在我剛開的 [GitHub issue]
（連結）。
謝謝你們把 Hello-Agents 做出來，這幾年中文 agentic AI 學習的公共財都是你們扛的，
真的很感激。
— Wenyu
```
---
## Notes
- **不要 promise**「我們會幫你們宣傳」之類的——只 offer 已經 ship 的 cross-link
- 如果他們同意 reverse PR 加 Hello-Agents 到 §11，記得用 `gh api` 確認 ★ 後加
- WeChat 是 Datawhale 主要互動 channel，但 GitHub issue 比較 maintainable + 可追蹤
- 如果一週沒回——OK，他們團隊很忙、不要 ping
.github/outreach/hacker-news.md
+74
View File
@@ -0,0 +1,74 @@
# Outreach draft — Hacker News (Show HN)
> **Status**: draft, not submitted. Maintainer reviews + posts manually.
> One shot — don't repost if it doesn't catch. Pick a weekday, ~08:00–10:00
> US Eastern (HN morning), not Fri/weekend.
## Why HN
Largest single English dev-audience spike potential. Audience overlaps
exactly: people building with LLMs / agents who like structured depth.
Risk: HN is allergic to hype and to "another awesome-list". The draft
below leads with the concrete artifact and pre-empts the two predictable
top comments ("why another list" / "is the English LLM-translated").
## Title (pick one — no emoji, no hype, ≤ 80 chars)
1. `Show HN: A trilingual, staged roadmap from LLM basics to multi-agent systems`
2. `Show HN: Agentic-AI learning roadmap – 8 stages, 240+ curated projects`
3. `Show HN: An opinionated path to learn agentic AI (not an awesome-list dump)`
Recommended: **#1** (says what it is + the trilingual angle, no adjectives).
## Body (paste into the text field, keep it short)
```
I built a structured learning roadmap for agentic AI because every
"awesome-list" I found was a flat link dump with no order — great as a
reference, useless as a path if you don't already know what you don't
know.
This is sequenced: 8 stages from "what's a token" to multi-agent
orchestration + Computer/Browser Use, with explicit entry conditions and
a self-check at the end of each stage, plus two tracks (use existing CLI
agents vs. build your own) and 5 audience branches (researcher /
developer / teacher / knowledge worker / everyday user).
It started as a Chinese-language project, but the English edition is
fully maintained, not a machine-translated afterthought (~0.4% of
English lines contain any CJK, almost all intentional term-mapping; CI
checks localization + anchor integrity). Rendered site (trilingual,
mkdocs): https://wenyuchiou.github.io/awesome-agentic-ai-zh/
Repo: https://github.com/WenyuChiou/awesome-agentic-ai-zh
It's MIT, ~240 curated projects each with star/audience/"what it
teaches/how to run", and small runnable exercises (1–5 per stage). Honest limitation:
it's opinionated (Claude-ecosystem-heavy in the later stages — MCP /
Skills / SDK), and the deep exercises point out to first-party cookbooks
rather than re-teaching them. Feedback on the sequencing + what's
missing is what I'm after.
```
## First-comment (post yourself, immediately, as the author)
```
Author here. Two things I expect to come up:
1. "Why not just a list?" — the curation IS in there (240+ entries with
the usual metadata), but the value I was missing was ORDER + exit
criteria, so the spine is the stage sequence, not the list.
2. "Is the English LLM-slop?" — fair worry for a zh-origin repo. It's
not a thin mirror: measured ~0.4% CJK across 64 English files, the
required-reading per stage is English-native primary sources
(Anthropic/OpenAI/HF docs), and structure is CI-gated. Tell me where
it reads translated and I'll fix it.
Happy to take "this stage is wrong / out of date" specifics.
```
## Don'ts
- ❌ Don't say "the best / definitive / production-grade" (HN will pile on).
- ❌ Don't lead with the star count.
- ❌ Don't repost a flopped submission within weeks.
- ❌ Don't ask for upvotes/stars anywhere.
.github/outreach/huggingface-zh.md
+97
View File
@@ -0,0 +1,97 @@
# Outreach: HuggingFace 中文社群
> **Status**: not contacted · **Channel**: HF community post / Spaces card / discuss page
> **Primary lang**: en + zh-Hans (HF 國際化)
> **Last updated**: 2026-05-09
**Why this target**: HuggingFace 是英語 ML / agent 生態的中心，但中文社群也越來越大（中國團隊頻繁在 HF 發 model）。HF 沒有「learning roadmap for agentic AI」這個 slot——我們 trilingual + structured 的定位剛好填補。
**Pitch angle**: 我們不是模型 / dataset / Space，我們是「先把 agentic AI 學完再來用 HF」的入口。
**Their counter-value**: HF 流量 + 國際曝光；對英語讀者來說我們的 zh-TW / zh-Hans 段落是 bonus。
---
## Variant 1 — Social post (Twitter / X，~280 chars)
```
For folks asking "where do I start with agentic AI?" — built a trilingual
8-stage learning roadmap (zh-TW · zh-Hans · en) covering Stage 0 (foundations)
through Stage 8 (multi-agent production). 240+ curated projects with cost,
audience, and time estimates per stage.
⭐ 525 in week 1 · MIT
🔗 github.com/WenyuChiou/awesome-agentic-ai-zh
```
## Variant 2 — HF Community Post / Discuss (200-300 words)
**Title**: Trilingual 8-stage learning roadmap for agentic AI (Stage 0 → multi-agent production)
**Body**:
```markdown
Hi HF community,
I've been building [awesome-agentic-ai-zh](https://github.com/WenyuChiou/awesome-agentic-ai-zh)
— a trilingual (zh-TW canonical · zh-Hans · English) 8-stage learning roadmap
for agentic AI:
- **Stage 0**: Foundations (Python, git, CLI, REST APIs)
- **Stage 1-3**: LLM basics, prompt engineering, RAG, frameworks
- **Stage 4**: Agentic frameworks (LangChain, LangGraph, AutoGen, etc.)
- **Stage 5**: Claude Code ecosystem (MCP, Skills, Plugins)
- **Stage 6**: Multi-agent + memory + production hardening
- **Stage 7**: Production deployment + observability
- **Stage 8**: Agent Interfaces (Computer Use, Browser Use, Code Sandbox)
Each stage has time estimates, prerequisites, hands-on exercises, and 240+
curated projects across the catalog. The catalog includes MCP servers, Skills,
and integrations grouped by 16 use-case categories — including a section
specifically for the Chinese-language ecosystem (Coze, Qwen-Agent, LangChain
zh learning, etc.).
Some HF community members may find it useful as a "**before you train your
first model**" structured path, especially folks asking where to start with
agents. Trilingual support is genuinely tested (not machine-translated).
Stats (week 1): ★525 / 50 forks / 3,185 unique visitors / 408 unique cloners.
MIT, contributors welcome.
Happy to take feedback if any HF maintainer thinks specific stages should
reference HF resources more directly (Stage 1 already cites HF transformers
and HF model cards).
— Wenyu
```
## Variant 3 — Email / DM to specific HF maintainer (150 words)
```
Hi <name>,
I built awesome-agentic-ai-zh, a trilingual (zh-TW / zh-Hans / en) 8-stage
learning roadmap for agentic AI — covers foundations through multi-agent
production with 240+ curated projects, cost/time estimates per stage. ★525
+ 3,185 unique visitors in week 1.
Stage 1 (LLM basics) and Stage 4 (frameworks) reference HF transformers
and HF Hub fairly heavily. Wondering if there's a HF-side touchpoint that
makes sense — community blog post, discussion thread, or HF Learn linkage.
No urgency, no expectation. If interested, happy to chat. If not, no offense
taken.
— Wenyu
```
---
## Notes
- HF community page: huggingface.co/posts (treat like a discussion forum)
- **Do not** tag random HF people; if pitching to maintainer, identify by past
ML/agent work specifically
- HF Learn: huggingface.co/learn — if our content ever gets featured, the
HF Learn audience is exactly our target
- For zh-Hans segment: HF has a 中文社群 page; can post there separately
.github/outreach/langchain-ai.md
+105
View File
@@ -0,0 +1,105 @@
# Outreach: LangChain ecosystem (langchain-ai / kyrolabs/awesome-langchain)
> ⚠️ **Send content is now canonical in [`_send-day-packages.md`](_send-day-packages.md)** (package C — current numbers: 8 stages / 240+ resources). This file is kept for positioning rationale; do not paste its older entry/stats blocks directly.
> **Status**: not contacted · **Channel**: GitHub PR
> **Primary lang**: en (with zh as bonus)
> **Last updated**: 2026-05-26 (refreshed — stats, 8-stage structure, correct section target)
> **Repos**:
> - https://github.com/langchain-ai/langchain (main repo)
> - https://github.com/kyrolabs/awesome-langchain (community awesome list ★9k+)
**Why this target**: LangChain is the gateway agent framework for ~80% of zh-language developers. Our Stage 4 covers it; our §11 catalog now includes Langchain-Chatchat (★37k) and the Chinese LangChain getting-started guide (which **already lives in the same section** we're targeting — see below). Cross-link is natural.
**Pitch angle**:
- For `langchain-ai/langchain` itself: too big a target; aim instead at the **community awesome list** (`kyrolabs/awesome-langchain`).
- For `kyrolabs/awesome-langchain`: we're a multilingual learning-order complement to their flat catalog.
- **Target section confirmed (2026-05-26)**: `## Learn → ### Notebooks`. Precedent: `liaokongVFX/LangChain-Chinese-Getting-Started-Guide` already sits there. There is **no** "Tutorials & Learning Resources" section in the current README; do not propose one.
**Their counter-value**: ★9k exposure to LangChain-curious developers worldwide.
---
## Variant 1 — Social post (X / LinkedIn, ~280 chars)
```
LangChain learners often ask: "I have the docs, but where do I actually start?"
Built an 8-stage trilingual learning roadmap (zh-TW · zh-Hans · en). Stage 4
walks through LangChain / LangGraph / AutoGen / CrewAI / Smolagents with
prerequisites and time estimates. 145+ projects · MIT · ★1.7k.
🔗 github.com/WenyuChiou/awesome-agentic-ai-zh
```
## Variant 2 — GitHub PR to kyrolabs/awesome-langchain (200-300 words)
**PR title**: Add awesome-agentic-ai-zh (trilingual learning roadmap) to Learn → Notebooks
**Diff** (against `## Learn → ### Notebooks`, after the `liaokongVFX/LangChain-Chinese-Getting-Started-Guide` line — keeps the two zh-ecosystem learning resources adjacent):
```diff
- [LangChain Chinese Getting Started Guide](https://github.com/liaokongVFX/LangChain-Chinese-Getting-Started-Guide): Chinese LangChain Tutorial for Beginners ![GitHub Repo stars](https://img.shields.io/github/stars/liaokongVFX/LangChain-Chinese-Getting-Started-Guide?style=social)
+ - [WenyuChiou/awesome-agentic-ai-zh](https://github.com/WenyuChiou/awesome-agentic-ai-zh): Trilingual (zh-TW / zh-Hans / en) 8-stage learning roadmap for agentic AI — Stage 4 walks through LangChain, LangGraph, AutoGen, CrewAI, Smolagents with prerequisites, time estimates, and hands-on exercises ![GitHub Repo stars](https://img.shields.io/github/stars/WenyuChiou/awesome-agentic-ai-zh?style=social)
```
**PR description**:
```markdown
Hi kyrolabs maintainers,
Proposing addition of [WenyuChiou/awesome-agentic-ai-zh](https://github.com/WenyuChiou/awesome-agentic-ai-zh) to **Learn → Notebooks**, next to the existing `liaokongVFX/LangChain-Chinese-Getting-Started-Guide` entry (same zh-learning surface).
**Why this is a good fit**:
- Trilingual (zh-TW canonical · zh-Hans · en — all three fully maintained, not MT) — fills a gap for non-English learners
- **Stage 4 (Agent Frameworks)** walks new developers through **LangChain / LangGraph / AutoGen / CrewAI / Smolagents** with prerequisites, time estimates, and hands-on exercises
- §11 of the catalog has 7 Chinese-ecosystem entries including `chatchat-space/Langchain-Chatchat` (★37k) and the LangChain Chinese Getting Started Guide that's already in your list
- Stage 5 covers the Claude Code / MCP / Skills layer; Stage 8 covers Agent Interfaces (Computer Use / Browser / Sandbox). Together with the catalog this is the complement-to-LangChain-docs that doesn't currently exist in zh
**Stats (2026-05-26)**: ★1.7k · 191 forks · 5,090 unique visitors (14d) · 1,316 unique cloners (14d) · 3 community contributors. MIT licensed. Rendered docs at https://wenyuchiou.github.io/awesome-agentic-ai-zh/. CI runs banned-word + link-rot + anchor-integrity lints on every PR.
If a different section or shape works better, happy to redirect. Thanks for maintaining awesome-langchain.
— Wenyu Chiou (individual maintainer)
```
## Variant 3 — Email to LangChain DevRel (150 words)
```
Hi LangChain team,
I built awesome-agentic-ai-zh — a trilingual (zh-TW / zh-Hans / en) 8-stage
learning roadmap for agentic AI. ★1.7k, 5k unique visitors / 14 days, heavy
zh-language community traction (top external referrer is Threads).
Stage 4 walks new developers through LangChain → LangGraph → AutoGen →
CrewAI → Smolagents with prerequisites and time estimates per step.
Designed to bridge "I know Python" to "I can build a working agent."
Two questions:
1. Is there a LangChain-side surface where this would fit (Learn, blog,
docs sidebar)?
2. Any specific LangChain features I should cover better in Stage 4? Open
to feedback.
No expectation, just opening dialogue.
— Wenyu
```
---
## Notes
- **First target**: kyrolabs/awesome-langchain (community awesome list, lower
barrier to merge). **Section: `Learn → Notebooks`**, not "Tutorials" (no such
section exists in the current README — verified 2026-05-26).
- **Second target**: LangChain blog/docs (higher signal but harder to land)
- Avoid pitching `langchain-ai/langchain` itself directly — too big, signal is
drowned out
- LangSmith / LangGraph teams are separate — different DevRel; don't pitch all
three at once
- **Stat snapshot is per-PR-day** — refresh `★`, `forks`, `unique visitors`,
`clones` with `gh repo view --json stargazerCount,forkCount` + `gh api
repos/.../traffic/views,clones` on the day you submit. Stale stats in a PR
body read as careless.
.github/outreach/liyupi.md
+82
View File
@@ -0,0 +1,82 @@
# Outreach: liyupi/ai-guide
> ⚠️ **Send content is now canonical in [`_send-day-packages.md`](_send-day-packages.md)** (package D — current numbers: 8 stages / 240+ resources). This file is kept for positioning rationale; do not paste its older entry/stats blocks directly.
> **Status**: not contacted · **Channel**: GitHub PR
> **Primary lang**: zh-Hans
> **Last updated**: 2026-05-09
> **Repo**: https://github.com/liyupi/ai-guide (★ 16k+)
**Why this target**: liyupi 的 ai-guide 是中國大陸最大的 AI 資源 hub 之一（★13k+），定位是 aggregator——「整理所有相關資源」。我們是結構化 7 階段學習地圖，剛好是他們資源海中缺的「**怎麼依序學**」這一塊。
**Pitch angle**: 我們不取代他們的 aggregator 功能，我們是他們資源使用者的「pre-reading 路線」。
**Their counter-value**: ★13k 的曝光；mainland zh 流量入口。
---
## Variant 1 — Social post (Weibo / X，~280 字)
> 在 ai-guide 找到一堆好資源，但不知道該從哪一個開始？
>
> awesome-agentic-ai-zh 把 agentic AI 切成 Stage 0 → Stage 7，每階段告訴你預估時程
> + 入門條件 + 該讀什麼。三語齊全（zh-TW / zh-Hans / en），145+ curated projects。
>
> 配著 ai-guide 一起看：用 ai-guide 找 project、用我們找順序。
> 👉 https://github.com/WenyuChiou/awesome-agentic-ai-zh
## Variant 2 — GitHub PR (200-300 字)
**PR title**: Add awesome-agentic-ai-zh to "AI 学习路线" / "相关资源" section
**File modified**: README.md（或者對應的 resource list 檔）
```diff
+ - [`WenyuChiou/awesome-agentic-ai-zh`](https://github.com/WenyuChiou/awesome-agentic-ai-zh)
+ — 7 阶段三语学习地图（zh-TW canonical / zh-Hans / en）；从 Stage 0 基础到
+ Stage 7 multi-agent production，每阶段附预估时程 + 入门条件 + 145+ curated
+ projects。MIT，跟 ai-guide 互补：ai-guide 找 project、awesome-agentic-ai-zh
+ 找学习顺序。
```
**PR description**:
```
你好 liyupi 大佬！
我维护的 [awesome-agentic-ai-zh](https://github.com/WenyuChiou/awesome-agentic-ai-zh)
是一份中文 agentic AI 的 7 阶段三语学习地图（zh-TW canonical / zh-Hans / en，145+
projects，MIT 协议），第一周 ★525、3,185 unique visitors、1,099 clones，主要流量来自 Threads /
X / 部分微信社群。
定位上跟 ai-guide 互补——ai-guide 是「大全」，我们是「学习顺序」。我们的读者经常
是「想学但不知道该先学什么」的工程师，看完我们的 Stage 0–7 后，回到 ai-guide 找
具体 project 用。
想 propose 加进 ai-guide 的「AI 学习路线」或「相关资源」section。如果觉得不合适
请直接关掉，谢谢您！
— Wenyu (PhD candidate · Lehigh，个人 maintainer)
```
## Variant 3 — Email / Weibo DM (150 字)
```
你好 liyupi 大佬，
我是 awesome-agentic-ai-zh 的维护者 Wenyu。这份是中文 agentic AI 的 7 阶段三语
学习地图（145+ projects，三语齐全），上线一周 ★525。
定位跟 ai-guide 互补——ai-guide 找 project、我们找顺序。想加进你们的「相关资源」
section，刚开了 PR（链接）。如果不合适请直接关掉，谢谢！
— Wenyu
```
---
## Notes
- liyupi 的 PR 速度看心情——如果一週沒動就 ping 一下、沒回就放著
- **不要**自吹「比 ai-guide 更好」之類的——我們是 complement、不是 replace
- 注意：liyupi 偏好簡體 + 中國大陸友善的措辭，PR 描述用 zh-Hans
.github/outreach/moonshot.md
+87
View File
@@ -0,0 +1,87 @@
# Outreach: Moonshot Kimi 開發者頻道
> **Status**: not contacted · **Channel**: 開發者社群（Discord / 知乎 / GitHub）
> **Primary lang**: zh-Hans
> **Last updated**: 2026-05-09
> **Their main surface**: https://kimi.moonshot.cn · https://github.com/MoonshotAI
**Why this target**: 月之暗面 (Moonshot) 是大陸 frontier AI lab 之一（Kimi K2 / Kimi-Chat）。我們 §11 中文圈專用 沒有 Moonshot entry——他們的開源主要是 model paper / weights，沒有 agent SDK 形態的 canonical repo。
**Pitch angle (邀請式)**: 跟 Zhipu 同邏輯——§11 缺 Moonshot 的 agent / Skills 入口；邀請他們社群推薦合適的 PR。
**Their counter-value**: Kimi 開發者透過我們學整個 agentic 生態；他們在 zh community 的 visibility 提升。
---
## Variant 1 — Social post (Weibo / X，~280 字)
```
中文 agentic AI 學習地圖 awesome-agentic-ai-zh，§11 中文圈專用 收了 Qwen-Agent +
Coze——缺 Moonshot 的 entry。
如果月之暗面的同學 / 熱心開發者覺得有 Kimi 系列的 agent skill / SDK / cookbook
該收進來，歡迎 PR：github.com/WenyuChiou/awesome-agentic-ai-zh
240+ projects · 三語齊全 · MIT · ★525 第一週
```
## Variant 2 — Discussion / 知乎文章 (200-300 字)
**Title**: 邀請：月之暗面 Kimi agent 生態，有合適的開源項目可以收進 awesome-agentic-ai-zh §11 嗎？
**Body**:
```markdown
你好 Moonshot 社群，
我维护 [awesome-agentic-ai-zh](https://github.com/WenyuChiou/awesome-agentic-ai-zh)
——一份中文 agentic AI 的 8 阶段三语学习地图（zh-TW canonical / zh-Hans / en，240+
projects，MIT，★525 第一周）。
**§11 中文圈专用** 已经收了 Qwen-Agent / Coze / Langchain-Chatchat 等，但缺
Moonshot Kimi 的 entry。我评估过的几个候选：
- `MoonshotAI/Kimi-K2`：模型 paper / weights repo，不是 agent SDK 形态
- 没看到官方的 `kimi-agent-sdk` / `kimi-skills` / `kimi-cookbook` canonical 仓库
想问问 Moonshot 社群：
1. 有没有官方或半官方的 Kimi agent / Skills / cookbook 仓库可以推荐？
2. 如果有，欢迎 PR 到 §11。收录原则：
- agent / Skill / SDK / MCP-shaped（不只是模型 API）
- license 清楚
- 最近 90 天有 commit
- 品质优于流行度（star 数不是门槛）
社群的 chat-bot / agent 二次开发也算——只要是 Kimi 周边的合适学习资源都可以。
如果一时没合适项目，也 OK，先留个 thread 追踪 agent 生态成熟度。
— Wenyu (Lehigh CEE PhD candidate，个人 maintainer)
```
## Variant 3 — DM / 邮件 (150 字)
```
你好 Moonshot 社群，
我是 awesome-agentic-ai-zh 的维护者 Wenyu。这份是中文 agentic AI 的 8 阶段三语
学习地图（240+ projects，三语齐全，MIT，★525 第一周）。
§11 中文圈专用 收了 Qwen-Agent + Coze，缺 Kimi 的 entry。如果有官方推荐的 Kimi
agent / Skills / cookbook 仓库我应该收进来，请告诉我；或者直接 PR 到 §11。收录
原则：agent-shaped + license 清楚 + 90 天内活跃。
谢谢！
— Wenyu
```
---
## Notes
- **同 Zhipu 邏輯**：邀請式而非推銷式
- Moonshot 的開源相對少（主要是 paper + weights），如果真的沒合適 repo，**不
要硬 fit**——可以先放著，等他們釋出 agent SDK 再收
- Moonshot 開發者社群入口：Discord / 知乎 / 飛書群（Kimi 開發者群）
- 不要與 Zhipu outreach 同日發送——避免「同一個人到處撒網」感
- 監測：如果 Moonshot 後續釋出 `MoonshotAI/Kimi-Agent` 或類似——優先收進 §11
.github/outreach/newsletters-en.md
+59
View File
@@ -0,0 +1,59 @@
# Outreach draft — English AI newsletters
> **Status**: draft, not submitted. These are "tip / submission" blurbs,
> not articles. Submit via each newsletter's tip form/email. A learning
> roadmap is newsletter-friendly (evergreen, linkable, low-risk to
> feature). Best AFTER a HN/Reddit signal exists (newsletters like
> "already getting traction").
## Targets + submission route
| Newsletter | Route | Notes |
|---|---|---|
| TLDR AI | tldr.tech "submit a link" / reply to an issue | Largest; wants a one-liner + link |
| Ben's Bites | bensbites submit form | Likes tools/resources builders can use today |
| Last Week in AI | skynettoday/LWiAI tip | Leans research+practitioner |
| Latent Space | latent.space (Discord/issue) | Practitioner, agent-heavy audience |
| C%2BAI / Rundown AI | their submit forms | Broad; keep it one sentence |
## Blurb A — generic one-liner (TLDR AI / Rundown style)
```
A free, trilingual, staged roadmap for learning agentic AI — 8 stages
from LLM basics to multi-agent + Computer/Browser Use, 240+ curated
projects, runnable exercises, with entry conditions and a self-check per
stage. MIT. Rendered site: https://wenyuchiou.github.io/awesome-agentic-ai-zh/
```
## Blurb B — 2–3 sentences (Ben's Bites / Latent Space style)
```
Most "awesome-AI-agents" lists are flat link dumps — useful to look
things up, useless as a path. This is a sequenced roadmap instead: 8
stages (LLM basics → tool use → frameworks → Claude Code ecosystem →
memory/RAG → multi-agent → Computer/Browser Use), two tracks (use
existing CLI agents vs build your own), 5 audience branches, 240+
curated projects with "what it teaches / how to run", and small runnable
exercises that work locally (Ollama) before any paid API. Trilingual and
MIT; the English edition is fully maintained, not machine-translated.
https://wenyuchiou.github.io/awesome-agentic-ai-zh/
```
## Blurb C — "why your readers care" framing (editor pitch email)
```
Subject: Resource submission — staged agentic-AI learning roadmap (MIT, trilingual)
Hi [name], your readers regularly ask "how do I actually start building
agents". This is a structured answer: a staged roadmap (not another flat
list) that goes LLM-basics → multi-agent with explicit prerequisites and
an end-of-stage self-check, plus a CLI-power-user track for people who
just want to USE agents rather than build them. Free/MIT, trilingual,
rendered docs site. Repo: https://github.com/WenyuChiou/awesome-agentic-ai-zh
Happy to give any extra context. — [you]
```
## Don'ts
- ❌ Mass-BCC the same email to all (personalise the [name]/[why]).
- ❌ Overclaim ("the definitive guide"). Editors cut hype.
- ❌ Submit the same week as a flop — wait for a signal to reference.
.github/outreach/reddit.md
+80
View File
@@ -0,0 +1,80 @@
# Outreach draft — Reddit
> **Status**: draft, not submitted. Maintainer posts manually, ONE
> subreddit per day max, tailored each time (cross-posting identical
> text reads as spam and gets auto-removed). Always disclose you're the
> author. Read each sub's rules + "self-promotion" policy first.
## Targets (priority order)
| Sub | Why | Rule note |
|---|---|---|
| r/AI_Agents | Exact audience (agent builders) | Self-promo tolerated if it's substantive + you engage |
| r/LocalLLaMA | Huge, builder-heavy, likes curation | No pure self-promo on weekends; lead with value |
| r/ClaudeAI | Later stages are Claude-ecosystem (MCP/Skills) | Fits; flair appropriately |
| r/learnmachinelearning | "How do I learn agents" asked daily | Post as a resource, not a launch |
| r/MachineLearning | Strict; only if framed as a resource, low priority | Needs heavy substance, mod-gated — optional |
## r/AI_Agents (primary)
**Title**: `A staged roadmap to learn agentic AI (not a flat awesome-list) — feedback wanted`
**Body**:
```
I kept seeing "awesome-X" lists for agents — useful as references, but
none gave an ORDER to actually learn in. So I built a sequenced roadmap
and I'd like this sub to poke holes in the sequencing.
- 8 stages: LLM basics → prompt design → tool use → frameworks →
Claude Code ecosystem (MCP/Skills) → memory/RAG → multi-agent →
Computer/Browser Use. Each stage has entry conditions + an end self-check.
- 2 tracks: "use existing CLI agents" vs "build your own".
- 5 audience branches (researcher / dev / teacher / knowledge worker /
everyday user).
- 240+ curated projects (star / audience / what it teaches / how to run)
+ small runnable exercises (1–5 per stage). MIT.
Trilingual (the project is Chinese-origin but the English edition is
fully maintained, not MT slop). Rendered site:
https://wenyuchiou.github.io/awesome-agentic-ai-zh/
Honest bias: Claude-ecosystem-heavy in the later stages. What I want:
where is the stage order wrong, and what's a glaring omission?
```
## r/LocalLLaMA (variant — lead with the local-LLM angle)
**Title**: `Trilingual agentic-AI roadmap — every stage's exercises run on Ollama/local first, Claude as the prod reference`
**Body**: (same skeleton, swap first paragraph)
```
Built a staged learn-path for agentic AI. Relevant to this sub
specifically: the hands-on exercises are dual-path — Ollama / local
runner first (llama.cpp, LocalAI, MLX listed), with Claude/Anthropic as
the production reference, so you can do the whole roadmap locally before
spending an API cent.
```
(then the same 8-stages / 2-tracks / link / "honest bias" / "feedback
wanted" tail as r/AI_Agents)
## r/ClaudeAI (variant — lead with the ecosystem depth)
**Title**: `A learning path that actually covers the Claude Code ecosystem (MCP / Skills / Plugins / SDK), staged`
**Body**: lead paragraph emphasising Stage 5/8 (Claude Code ecosystem +
Agent Interfaces) as the differentiator vs framework-only tutorials;
same tail.
## r/learnmachinelearning (variant — resource framing, not launch)
**Title**: `Resource: a free, staged roadmap from LLM basics to multi-agent (with exit self-checks)`
**Body**: frame as "for the recurring 'how do I start with agents'
question" — emphasise Stage 0–2 foundation + the self-check gating;
same link; lighter on the build-track detail.
## Don'ts
- ❌ Identical body across subs (auto-spam-flag).
- ❌ "Please star/upvote".
- ❌ Drive-by post then disappear — must reply to comments for ~24h.
- ❌ Posting to r/MachineLearning without resource framing (removal).
.github/outreach/x-twitter.md
+130
View File
@@ -0,0 +1,130 @@
# Outreach draft — X (Twitter)
> **Status**: draft, not submitted. Maintainer reviews + posts manually.
> Identity-bound channel — do not delegate posting to an agent.
## Why X
Fastest broadcast for the EN agentic-AI community (the same crowd that
amplifies on HN / Reddit also lives here in shorter form). What X does
well: identity-signal-driven discovery (a PhD researcher posting a
curated learning artifact is read very differently from an anonymous
account), image-driven engagement (link cards + banner = ~2× CTR), and
quote-retweet amplification by mid-tier AI accounts. What X does poorly:
depth (280-char ceiling), context (no threading culture for awesome-list
type artifacts), and persistence (24-48h half-life).
Risk: X is also where overclaim and self-promotion are punished hardest.
Lead with the artifact, not adjectives.
## Pre-flight (verify before posting)
These are already shipped (`44b1cbe`), but re-check the live preview
before you tweet — X's card scraper caches aggressively:
- [ ] X card preview for `github.com/WenyuChiou/awesome-agentic-ai-zh`
shows EN-lead description (paste URL into a draft tweet first, eyeball
the card; if zh-TW-lead, the cache hasn't refreshed — wait ~1h or
re-share via the Pages URL)
- [ ] Your X bio matches the LinkedIn reframe (PhD, Civil & Environmental,
Lehigh · agent-based modeling · LLM / AI agent). Identity coherence
across platforms is the discovery multiplier on X
- [ ] `banner.en.png` is uploaded as the tweet image (drag-attach, not URL
auto-card — image attachment outperforms link card for first impression)
## Tweet options (pick one; no emoji-spam, no hype, ≤ 280 chars)
### A — EN-lead, broad AI audience (recommended)
```
An AI agent learning map — curates 240+ repos across the agentic-AI
ecosystem (MCP / skills / frameworks / agents), from LLM basics to
multi-agent. Trilingual (EN / 繁中 / 简中); branches for researcher /
dev / teacher / knowledge worker.
github.com/WenyuChiou/awesome-agentic-ai-zh
```
### B — research-first (matches your LinkedIn reframe)
```
PhD student doing agent-based flood-adaptation modeling. Open-sourced
the AI agent learning map I built for my own learning — 240+ curated
repos across the agentic-AI ecosystem, LLM basics → multi-agent.
Trilingual (EN / 繁中 / 简中).
github.com/WenyuChiou/awesome-agentic-ai-zh
```
### C — bilingual lead (CJK AI-Twitter circle: 寶玉 / AK / 向阳乔木)
```
做了個 AI Agent 學習地圖 —— 蒐集 240+ 個 repo(MCP / skills / frameworks / agents),從 LLM 基本概念一路走到 multi-agent 系統,三語維護(繁中 / 简中 / EN)。對 researcher / 開發者 / 老師 / 知識工作者各有分支。
An AI agent learning map — github.com/WenyuChiou/awesome-agentic-ai-zh
```
Recommended: **A** for the first push (EN-lead is where the audience is
and the meta tags are now aligned). Consider **C** as a separate post
~1 week later targeting CJK AI Twitter — different audience, different
time window, doesn't compete with the EN push.
## Timing
- **A (EN)**: weekday 08:00–10:00 US Eastern (US AI Twitter morning;
overlaps EU evening). Avoid Fri PM / weekends.
- **C (CJK)**: weekday 20:00–22:00 Beijing time (CN evening; overlaps TW
prime time).
- Don't post both same day — collisions hurt both.
## First-reply (optional, post yourself ~5 min after main tweet)
Use this only if engagement is picking up and a clarifier would unlock
more clicks. Don't pre-load it if the main tweet flops.
```
A few things that aren't obvious from the README:
- Stage 0 is for non-coders (web/desktop on-ramps before any CLI).
- Examples default to local Ollama, not paid APIs — the cloud path is
the alt, not the default.
- The English edition is fully maintained alongside the Chinese
canonical, gated by CI (anchor + locale checks).
```
## Image / link strategy
- **Attach**: `resources/diagrams/banner.en.png` (the 2026-05-13 ChatGPT-
rendered EN banner, already in repo).
- **Link in tweet body**: `github.com/WenyuChiou/awesome-agentic-ai-zh`
— GitHub URL beats Pages URL because the ★ count is the trust signal
EN readers scan for. (Pages URL `wenyuchiou.github.io/awesome-agentic-ai-zh/en/`
is a fallback if you want to land EN readers on an English doc page
directly.)
- **No hashtags** in the main tweet — the audience is already targeted
by who follows you and who you quote-mention. Hashtags dilute the
reach signal more than they add discovery on X today.
## Engagement tactics (light)
- Quote-RT one of your own older posts about agent stuff with the new
URL, ~6h after main tweet, if first push got <20 likes (re-broadcast,
don't ask for boost)
- If a mid-tier AI account QTs you, reply with a *specific* follow-up
(a stage they'd find useful for their audience), not a generic
"thanks"
- If someone says "is the English just machine-translated?" — point them
to the CI lint config + the audit comment in the HN draft. Don't
defensively re-explain in the main thread.
## Don'ts
- ❌ Don't say "the best / definitive / world-class / production-grade"
- ❌ Don't lead with the ★ count (let the GitHub card show it)
- ❌ Don't @-mention famous AI accounts asking for amplification
- ❌ Don't post the same content to LinkedIn the same day (cross-platform
redundancy on the same hour smells like a launch campaign, not an
individual sharing). Stagger 24-48h
- ❌ Don't reuse the same tweet text after a flop — rewrite if going
for a second push
- ❌ Don't post C and A on the same day (different audiences, but
appearing twice in the same feed reads as spam)
.github/outreach/zhipu.md
+86
View File
@@ -0,0 +1,86 @@
# Outreach: Zhipu BigModel community (智譜)
> **Status**: not contacted · **Channel**: 開發者社群（Discord / 知乎 / GitHub Discussions）
> **Primary lang**: zh-Hans
> **Last updated**: 2026-05-09
> **Their main surface**: https://bigmodel.cn / https://github.com/MetaGLM
**Why this target**: 智譜 (Zhipu) 是大陸頭部 AI lab 之一（GLM 系列模型）。我們的 §11 中文圈專用目前**沒有 Zhipu 的條目**——主要是因為他們官方的 agent SDK 沒有一個 active + Apache-licensed 的 canonical repo。
**Pitch angle (邀請式，不是推銷式)**: 我們是中文 agentic AI 的 8 階段學習地圖；§11 已經收了 Qwen-Agent + Coze，缺 Zhipu。**邀請他們 PR 一個官方推薦的 Zhipu agent 教材 / SDK / cookbook**——他們在我們 catalog 站 §11 的位置，他們的開發者透過我們學 Zhipu 之外的整個 agentic 生態。
**Their counter-value**: 中文圈的 entrant developers 有結構化路線可學；GLM/AutoGLM 的曝光。
---
## Variant 1 — Social post (Weibo / 知乎 / X，~280 字)
```
中文 agentic AI 學習地圖 awesome-agentic-ai-zh，§11 中文圈專用 已經收 @QwenLM 跟
@coze-dev——缺 @zhipuai 的 entry。
如果智譜的同學 / 熱心開發者覺得有官方推薦的 GLM agent cookbook / SDK 該收進來，
歡迎 PR：github.com/WenyuChiou/awesome-agentic-ai-zh
240+ projects · 三語齊全 · MIT · ★525
```
## Variant 2 — Discussion / 知乎文章 (200-300 字)
**Title**: 邀請：智譜 GLM agent 生態的官方 / 社群推薦項目，可以收進 awesome-agentic-ai-zh §11 嗎？
**Body**:
```markdown
你好智譜社群，
我维护 [awesome-agentic-ai-zh](https://github.com/WenyuChiou/awesome-agentic-ai-zh)
——一份中文 agentic AI 的 8 阶段三语学习地图（zh-TW canonical / zh-Hans / en，240+
projects，MIT，★525 第一周）。
**§11 中文圈专用** 已经收了：
- QwenLM/Qwen-Agent（阿里巴巴）
- coze-dev/coze-studio + coze-loop（字节跳动）
- chatchat-space/Langchain-Chatchat
- liaokongVFX/LangChain-Chinese-Getting-Started-Guide
**目前缺智谱 GLM 生态的 entry**——之前评估过 MetaGLM/glm-cookbook 但 246 天没更新，
不太符合 catalog 的「活跃维护」收录原则。
想问问智谱社群：
1. 有没有官方维护的 GLM agent SDK / cookbook / Skills 仓库可以推荐？
2. 如果有合适的项目，欢迎大家直接 PR 到 §11。我们的收录原则在
[resources/style-guide.md](https://github.com/WenyuChiou/awesome-agentic-ai-zh/blob/main/resources/style-guide.md)
3. 评估标准：MCP / Skills / agent-shaped、license 清楚（避免无 license）、最近 90
天有 commit、品质优于流行度（star 数不是门槛）
如果一时没合适项目也 OK——agent 生态发展很快，先开个 thread 留言追踪。
— Wenyu (Lehigh CEE PhD candidate，个人 maintainer)
```
## Variant 3 — DM / 邮件 (150 字)
```
你好智谱社群，
我是 awesome-agentic-ai-zh 的维护者 Wenyu。这份是中文 agentic AI 的 8 阶段三语
学习地图（240+ projects，三语齐全，MIT，★525 第一周）。
§11 中文圈专用 已经收阿里 Qwen-Agent + 字节 Coze，缺智谱的 entry。如果有官方推荐
的 GLM agent SDK / cookbook 我应该收进来，请告诉我；或者直接 PR 到 §11。收录原则
在 resources/style-guide.md（agent-shaped + license 清楚 + 最近活跃）。
谢谢！
— Wenyu
```
---
## Notes
- **Tone**: 邀請式（"Want to be listed? Send PR"），不是 sales（"買我們服務"）
- 避免提 "★ 525" 太多次——對 ★1k+ partners 是小數字
- 如果 Zhipu 沒有合適 repo，**不要硬 fit**——保留 §11 的品質
- 如果有合適 PR 進來，注意 license 跟維護節奏（避免 archived / 246d-stale 的 MetaGLM/glm-cookbook 重蹈覆轍）
- Zhipu 中國大陸主要使用 知乎 + 微信 + 釘釘，GitHub Issues 是次要 channel
.github/workflows/anchor-validator.yml
+36
View File
@@ -0,0 +1,36 @@
name: Anchor Validator
# 內部 markdown anchor 連結驗證——避免 stage 之間 cross-ref 在 rename / cleanup 後破掉。
# 本 session 已遇過 3 次破 anchor（Stage 7 cleanup / Stage 5.6 rename / tracks/cli/A3）、
# 因此把 anchor validate 升為 CI-level check。
on:
pull_request:
paths:
- '**.md'
schedule:
# 每月 1 號 UTC 04:00 跑（避開 lint.yml UTC 03:00）
- cron: '0 4 1 * *'
workflow_dispatch:
permissions:
contents: read # explicit minimal permission (read-only repo content)
jobs:
anchors:
name: Validate internal cross-file anchors
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Setup Python
uses: actions/setup-python@v6
with:
python-version: '3.11'
- name: Validate anchors (strict mode)
# 2026-05 升級到 strict mode（commit 含 anchor cleanup batch、把 legacy 37 個
# broken anchor 全修完）。剩下 1 個 .github/ISSUE_TEMPLATE/project-suggestion.md
# 找不到 CONTRIBUTING.md 是 separate issue（missing file、非 anchor 問題）、
# script 已不算 broken anchor。
run: python scripts/check-anchors.py --strict
.github/workflows/docs.yml
+109
View File
@@ -0,0 +1,109 @@
name: Site (mkdocs + mdBook) → GitHub Pages
# SINGLE owner of the GitHub Pages deployment. GitHub Pages has exactly
# one root per repo, so the mkdocs site (root /) and the mdBook (/book/)
# MUST be built and published by ONE workflow — two workflows both
# calling actions/deploy-pages race and clobber each other (that is
# exactly what happened when the old deploy-book.yml coexisted with
# this one; deploy-book.yml has been removed).
#
# Layout published:
# / → mkdocs-material trilingual site (canonical homepage)
# /en/ /zh-Hans/ → mkdocs locale builds (mkdocs-static-i18n)
# /book/ → mdBook (zh-TW long-form "book" packaging)
#
# Pages source must be "GitHub Actions" (Settings → Pages → Source).
on:
push:
branches: [main]
paths:
- 'stages/**'
- 'tracks/**'
- 'branches/**'
- 'resources/**'
- 'walkthroughs/**'
- 'docs/**'
- 'examples/**'
- '*.md'
- 'mkdocs.yml'
- 'requirements-docs.txt'
- 'scripts/build-docs-tree.py'
- 'scripts/build-mdbook.sh'
- 'scripts/mkdocs_hooks.py'
- 'book.toml'
- '.github/workflows/docs.yml'
workflow_dispatch:
concurrency:
group: pages
cancel-in-progress: false
jobs:
build:
name: Build mkdocs (root) + mdBook (/book/)
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- uses: actions/checkout@v6
- name: Setup Python
uses: actions/setup-python@v6
with:
python-version: '3.12'
- name: Install docs dependencies
run: pip install -r requirements-docs.txt
- name: Stage content tree
run: python scripts/build-docs-tree.py
- name: Build mkdocs site (→ _build/site, the Pages root)
run: python -m mkdocs build
- name: Install mdBook
run: |
MDBOOK_VERSION="0.4.52"
curl -sSL "https://github.com/rust-lang/mdBook/releases/download/v${MDBOOK_VERSION}/mdbook-v${MDBOOK_VERSION}-x86_64-unknown-linux-gnu.tar.gz" | tar -xz
chmod +x mdbook
echo "$PWD" >> "$GITHUB_PATH"
- name: Build mdBook (subpath base-url → /book/)
# MDBOOK_OUTPUT__HTML__SITE_URL overrides book.toml's site-url
# (which is "/awesome-agentic-ai-zh/" for a root deploy) so every
# mdBook asset/link resolves under the /book/ subpath. No
# book.toml edit needed — env override is non-invasive.
env:
MDBOOK_OUTPUT__HTML__SITE_URL: /awesome-agentic-ai-zh/book/
run: bash scripts/build-mdbook.sh
- name: Merge mdBook into the mkdocs site under /book/
run: |
set -euo pipefail
test -f _build/site/index.html # mkdocs root must exist
test -f book/dist/index.html # mdBook must have built
mkdir -p _build/site/book
cp -r book/dist/. _build/site/book/
test -f _build/site/book/index.html
echo "merged: $(find _build/site/book -type f | wc -l) mdBook files under /book/"
- name: Upload Pages artifact
uses: actions/upload-pages-artifact@v3
with:
path: _build/site
deploy:
name: Deploy to GitHub Pages
needs: build
runs-on: ubuntu-latest
permissions:
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy
id: deployment
uses: actions/deploy-pages@v4
.github/workflows/freshness-2026.yml
+46
View File
@@ -0,0 +1,46 @@
name: 2026 Freshness Check
# 每月掃 .md 找 stale model references (Claude 3.5 / GPT-4o / Gemini 2.0 / etc.)
# without proper '前身 / 歷史 / lineage' qualifier. 不在 PR 跑（會 noise 太多、可能誤判）。
#
# Whitelist + stale patterns 維護在 scripts/freshness-models.yml（quarterly review）。
on:
schedule:
# 每月 1 號 UTC 05:00（避開 lint.yml 03:00 + anchor-validator 04:00）
- cron: '0 5 1 * *'
workflow_dispatch:
inputs:
strict:
description: 'Run in strict mode (fail CI on stale)'
required: false
default: 'false'
type: choice
options: ['false', 'true']
permissions:
contents: read # explicit minimal permission
jobs:
freshness:
name: Detect stale model references
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Setup Python
uses: actions/setup-python@v6
with:
python-version: '3.11'
- name: Install dependencies
run: pip install pyyaml
- name: Scan for stale model refs
run: |
# Default: warn-only on schedule; manual dispatch can choose strict
if [ "${{ github.event.inputs.strict }}" = "true" ]; then
python scripts/check-2026-freshness.py
else
python scripts/check-2026-freshness.py --warn-only
fi
.github/workflows/lint.yml
+194
View File
@@ -0,0 +1,194 @@
name: Lint (link rot + banned words + schema)
on:
pull_request:
paths:
- '**.md'
- 'scripts/**'
- 'resources/**'
schedule:
# 每月 1 號 UTC 03:00 跑完整檢查（catch link rot + star drift）
- cron: '0 3 1 * *'
workflow_dispatch:
jobs:
banned-words:
name: Banned-word audit (zh-Hans slips + overclaim phrases)
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Check zh-Hans slips in zh-TW canonical files
run: |
# 只掃 zh-TW canonical 檔。
# - --exclude="*.en.md" skip 英文 companion
# - --exclude="*.zh-Hans.md" skip 簡中 companion（裡面合法包含這些詞）
# resources/style-guide.md 跟 .github/ 是 policy doc，必然包含禁用詞做為
# 「不要這樣寫」的範例，所以這個 step 也不掃 resources/。
BANNED=("教程" "視頻" "軟件" "代碼" "用戶" "網絡" "默認" "函数" "演算法" "算法" "程序")
FOUND=0
for word in "${BANNED[@]}"; do
if grep -rn --include="*.md" --exclude="*.en.md" --exclude="*.zh-Hans.md" \
-F "$word" stages branches walkthroughs README.md CONTRIBUTING.md CONTRIBUTORS.md 2>/dev/null \
| grep -v "(zh-Hans)" \
| grep -v "zh-Hans repo" \
| grep -v "中文（zh-Hans）"; then
echo "❌ Banned word found: $word"
FOUND=$((FOUND+1))
fi
done
if [ $FOUND -gt 0 ]; then
echo ""
echo "Found $FOUND banned-word violations. See resources/style-guide.md §3."
exit 1
fi
echo "✓ No banned words detected."
- name: Check zh-TW residue in zh-Hans files (warning only)
run: |
# 反向檢查：zh-Hans 檔混入 zh-TW 用詞代表翻譯沒翻完。
# **僅 warning 模式**——不擋 PR、不要求完美。zh-Hans 翻譯是漸進的，
# 殘留是常態；這個 check 只是提示哪幾個詞還可以順手修。
# 不掃：style-guide / glossary（會引用對照詞當例子）、.ai/、book/。
BANNED_TW=("使用者" "軟體" "硬體" "資訊" "品質" "資料" "專案" "腳本" "預設" "影片" "演算法" "應用程式" "網路" "連結" "服務" "範例" "範本" "設定" "註解" "終端機" "命令列" "編輯器" "瀏覽器" "客戶端" "伺服器" "倉儲" "必修閱讀" "飛書")
FOUND=0
for word in "${BANNED_TW[@]}"; do
if grep -rn --include="*.zh-Hans.md" \
-F "$word" . 2>/dev/null \
| grep -v "^./resources/style-guide.zh-Hans.md" \
| grep -v "^./resources/glossary.zh-Hans.md" \
| grep -v "^./.ai/" \
| grep -v "^./book/"; then
echo "::warning::zh-TW word found in zh-Hans file: $word"
FOUND=$((FOUND+1))
fi
done
if [ $FOUND -gt 0 ]; then
echo "Note: $FOUND zh-TW residue word(s) detected in .zh-Hans.md. See .ai/zh-Hans_glossary.md. Not blocking the PR — fix when convenient."
else
echo "✓ No zh-TW residue."
fi
- name: Check overclaim phrases (strict — blocking)
run: |
# 掃公開展示的內容檔（zh + en + zh-Hans）找 style-guide §3 列為禁用的 overclaim 用語。
# 範圍涵蓋 stages/ branches/ walkthroughs/ tracks/ examples/ resources/（含
# mcp-skills-catalog / cookbook / cli-agents-guide 等實際被讀者讀到的文件）+ 各
# top-level 文件。
#
# 路徑 hygiene：
# - `.github/` 整個資料夾不在掃描 paths（內含 outreach drafts 跟「Don't say...」
# 明示禁用清單，本來就會引用禁用詞、不該被掃）。
# - `resources/style-guide.md` + `resources/glossary.md` 透過 grep -v 後過濾
# （它們在 resources/ 下、必然被 recurse 到，且為了當 policy 例子會列禁用詞）。
#
# 用 `grep -Fi`（fixed string + case-insensitive）—— 2026-05-26 incident：上一輪
# sweep 用 -F 是 case-sensitive、漏掉 examples/ 內 H2 標題的 `Production-grade`
# 大寫變體 5 處。這次升級為 -Fi。
#
# Warn-only step history：原本有第二個 step 掃 `最完整的` 之類的灰色地帶用語、
# 用 ::warning:: 不擋 PR。實測 corpus 有 30+ hit（多半是稱讚 Datawhale Hello-Agents
# 之類他人專案的 citation framing、非 self-promo overclaim），噪音大於價值、移除。
# 如未來要為其他灰色詞加 warn 機制，pattern 可參考 git log 找 2026-05-26 此 step
# 的初版實作（drafted but removed pre-merge）。
OVERCLAIMS=(
# === existing canonical bans ===
"the most canonical"
"全世界最好的"
"業界最強"
"最緊迫"
# === style-guide §3 expansions (2026-05-26, P3-G from audit) ===
"首選" # zh-TW "top choice"
"首选" # zh-Hans variant
"唯一選擇" # zh-TW "only choice"
"唯一选择" # zh-Hans
"業界最佳" # zh-TW "industry best" (sibling of 業界最強)
"业界最佳" # zh-Hans
# === audit P3-G English overclaim (case-insensitive matches all variants) ===
"production-grade" # supersedes the older exact "Production-grade Chinese tutorial"
"world-class"
"best-in-class"
"cutting-edge"
"state-of-the-art"
"industry-leading"
)
FOUND=0
for phrase in "${OVERCLAIMS[@]}"; do
hits=$(grep -rIn --include="*.md" -Fi "$phrase" \
stages branches walkthroughs tracks examples resources \
README.md README.en.md README.zh-Hans.md \
CONTRIBUTING.md CONTRIBUTING.en.md CONTRIBUTING.zh-Hans.md \
CONTRIBUTORS.md \
ROADMAP.md ROADMAP.en.md ROADMAP.zh-Hans.md \
CAPSTONE.md CAPSTONE.en.md CAPSTONE.zh-Hans.md \
PROGRESS.md PROGRESS.en.md PROGRESS.zh-Hans.md \
RESOURCES.md RESOURCES.en.md RESOURCES.zh-Hans.md \
2>/dev/null \
| grep -v "^resources/style-guide" \
| grep -v "^resources/glossary" \
|| true)
if [ -n "$hits" ]; then
echo "❌ Overclaim phrase found: $phrase"
echo "$hits"
FOUND=$((FOUND+1))
fi
done
if [ $FOUND -gt 0 ]; then
echo ""
echo "Found $FOUND overclaim category/categories. See resources/style-guide.md §3 'Overclaim 用語禁用'."
exit 1
fi
echo "✓ No overclaim phrases detected."
- name: Check zh-Hans mainland localization (blocking)
run: |
# Blocking gate: zh-Hans mirrors must stay mainland-localized.
# Catches future tw2s-only mirror syncs / hand edits that
# reintroduce Taiwan vocab (呼叫/程式/品质…) or 「」 quotes.
# stdlib-only script; ubuntu-latest ships python3 (no pip deps).
python3 scripts/zh-hans-localize.py --check
link-rot:
name: Link rot check (GitHub URLs)
runs-on: ubuntu-latest
# 只在 schedule 跟 workflow_dispatch 跑——PR 跑會太慢
if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
steps:
- uses: actions/checkout@v6
- name: Setup Python
uses: actions/setup-python@v6
with:
python-version: '3.11'
- name: Install requests
run: pip install requests
- name: Run link-check (--fast = GitHub URLs only)
run: python scripts/check-links.py --fast --quiet
star-drift:
name: Star drift detection
runs-on: ubuntu-latest
if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
steps:
- uses: actions/checkout@v6
- name: Setup Python
uses: actions/setup-python@v6
with:
python-version: '3.11'
- name: Install requests
run: pip install requests
- name: Run refresh-stars (warn only, don't fail CI)
# gh CLI 已內建在 ubuntu-latest runner，GH_TOKEN 自動 set
# 高門檻 (50%) 才警告，避免每月誤報
run: |
# 用 --check 才會在 drift 時退 1；用 || 接 ::warning:: 退 0
if ! python scripts/refresh-stars.py --threshold 50 --check; then
echo "::warning::Star drift detected (>=50%). 跑 'python scripts/refresh-stars.py' 看哪些 entry 要更新。"
fi
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
.github/workflows/mirror-sync-reminder.yml
+57
View File
@@ -0,0 +1,57 @@
name: Mirror Sync Reminder
# 當 PR 改了 zh-TW canonical 但沒同步 .en.md / .zh-Hans.md mirror 時、
# 自動在 PR 留一個 soft comment 提醒。不擋 PR——zh-TW 是 canonical、mirror sync 是 Path B。
on:
pull_request:
paths:
- 'stages/**.md'
- 'branches/**.md'
- 'tracks/**.md'
- 'resources/**.md'
- 'walkthroughs/**.md'
- 'README.md'
- 'CONTRIBUTING.md'
jobs:
mirror-check:
name: Detect mirror sync gap
runs-on: ubuntu-latest
permissions:
pull-requests: write
steps:
- uses: actions/checkout@v6
with:
# Need full history for accurate diff against base ref
fetch-depth: 0
- name: Setup Python
uses: actions/setup-python@v6
with:
python-version: '3.11'
- name: Detect mirror sync gap
id: detect
run: |
python scripts/check-mirror-sync.py \
--pr-base origin/${{ github.base_ref }}
- name: Comment on PR if gap detected
if: steps.detect.outputs.gap_detected == 'true'
# Pinned to v3.0.4 (specific release tag) — supply chain risk mitigation
# vs floating @v3. Upgrade by reviewing release notes + bumping tag.
# For tighter security (SHA pin), see: https://github.com/marocchino/sticky-pull-request-comment/releases
uses: marocchino/sticky-pull-request-comment@v3.0.4
with:
# `header` makes the comment sticky — re-running the workflow
# updates the same comment instead of creating duplicates.
header: mirror-sync
path: .mirror-sync-comment.md
- name: Delete comment if gap resolved
if: steps.detect.outputs.gap_detected == 'false'
uses: marocchino/sticky-pull-request-comment@v3.0.4
with:
header: mirror-sync
delete: true
.github/workflows/stage-template-check.yml
+28
View File
@@ -0,0 +1,28 @@
name: Stage Template Check
# 驗 stages/*.md 有所有必要 H2 section（template 對齊）。
# REQUIRED 缺則 fail PR、EXPECTED 缺則 warning（不擋）。
on:
pull_request:
paths:
- 'stages/**.md'
workflow_dispatch:
permissions:
contents: read # explicit minimal permission
jobs:
template:
name: Validate stage template structure
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Setup Python
uses: actions/setup-python@v6
with:
python-version: '3.11'
- name: Validate stage template
run: python scripts/check-stage-template.py
.github/workflows/weekly-catalog-refresh.yml
+298
View File
@@ -0,0 +1,298 @@
name: Weekly Catalog Refresh
# 每週一 04:00 UTC（12:00 台北）刷新 GitHub star 數 + 檢查連結失效。
# - star 數有變化 → 開 PR；若通過 sanity guard 則「自動 squash-merge」，
# maintainer 不需每週手動合。guard 不過 → PR 留開、上 needs-manual-review
# label + 貼原因,只有「異常週」才需要人看。
# - broken link → 開 issue 讓 maintainer 處理（不自動修）。
#
# 為何要 guard 而非裸 auto-merge：peter-evans 用 GITHUB_TOKEN 開的 PR
# GitHub 設計上不觸發 CI,所以 bot PR 沒有自動安全網。歷史上 PR-gate
# 攔過實際 bug（#17 漏 star-refresh.log、★ 空格被改壞）。此 inline guard
# 在 workflow 自己的 runner 跑,補上那個洞。
#
# Guard 會擋下(→ 改人工 review,不自動合):
# - 刪檔 / 改名 / 非 .md 路徑變動 / log 檔混入
# - 任何「★ 星數 token 以外」的內容被改(star-stripped diff 不一致)
# - 寫出 ★ 0(repo 多半被 archive/設私有,或 API 異常)
# - 變更行數 > 150 或變更檔數 > 40(疑似 mass API 異常 / runaway)
# - check-anchors --strict 壞掉
# 註:auto-merge 需 main 上「沒有強制 required-review 的 branch protection」
# (本 repo 單人維護、bot PR 無 CI,符合此前提)。若日後加了強制 review,
# auto-merge 會優雅地降級成「留 PR 等人工」,不會誤合。
#
# 跟其他 cron 錯開：lint 03:00 daily / freshness 05:00 monthly /
# weekly-refresh 04:00 Mon（本檔）。
# 手動觸發：Actions → Weekly Catalog Refresh → Run workflow。
# 環境需求：GITHUB_TOKEN（auto-provided）。
on:
schedule:
- cron: '0 4 * * 1'
workflow_dispatch:
inputs:
threshold:
description: 'Star drift threshold (%) — only PR if any entry drifted more than this'
required: false
default: '10'
permissions:
contents: write # create-pull-request 寫 branch + 自動 merge commit
pull-requests: write # 開 PR / gh pr merge / edit / comment
issues: write # broken link → open issue
jobs:
star-refresh:
name: Refresh GitHub star counts
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Setup Python
uses: actions/setup-python@v6
with:
python-version: '3.11'
- name: Install dependencies
run: pip install requests
- name: Refresh star counts (apply mode)
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
# star-refresh.log 已在 .gitignore（PR #17 leak fix, ae76b7d）
python scripts/refresh-stars.py \
--threshold "${{ github.event.inputs.threshold || '10' }}" \
--apply 2>&1 | tee star-refresh.log
if git diff --quiet; then
echo "drift=false" >> "$GITHUB_OUTPUT"
echo "No star drift detected this week."
else
echo "drift=true" >> "$GITHUB_OUTPUT"
echo "Star drift detected."
git diff --stat
fi
id: refresh
- name: Sanity guard (decides auto-merge vs manual review)
# 只在有 drift 時跑。本步驟永遠 exit 0(guard 不過 = 走人工
# review 分支,不是 workflow 失敗)。結果寫 steps.guard.outputs.guard。
if: steps.refresh.outputs.drift == 'true'
id: guard
run: |
set -uo pipefail
TMP="$(mktemp -d)"
fail() {
echo "guard=fail" >> "$GITHUB_OUTPUT"
{
echo "reason<<GUARD_REASON_HEREDOC_END"
echo "$1"
echo "GUARD_REASON_HEREDOC_END"
} >> "$GITHUB_OUTPUT"
echo "::warning::GUARD FAIL — $1 (PR stays open for manual review)"
exit 0
}
porc="$(git status --porcelain)"
echo "--- git status --porcelain ---"; echo "$porc"
# (a) no deletions / renames
if echo "$porc" | grep -qE '^[ ]?D|^D[ ]'; then fail "a tracked file was deleted"; fi
if echo "$porc" | grep -qE '^R'; then fail "a tracked file was renamed"; fi
# (b) every changed path must be a .md content file; no leak files
while IFS= read -r line; do
[ -z "$line" ] && continue
path="${line:3}"
case "$path" in
*.md) : ;;
*) fail "unexpected non-.md path changed: $path" ;;
esac
done <<< "$porc"
if echo "$porc" | grep -qE 'star-refresh\.log|link-report\.txt'; then
fail "diagnostic log file is staged"
fi
# (c) ONLY the ★ star-count token may differ. Strip ★N tokens from
# removed + added line bodies; the sorted multisets must be
# identical. Any prose/structural change makes them differ.
# (Kills the "line merely contains ★ somewhere" bypass.)
STAR_RE='★ ?[0-9]+(\.[0-9]+)?[kKmM]?[+]?'
# `|| true`: under pipefail, grep exiting 1 on no-match must not
# red the step (degenerate drift=true / no ±lines) — keep going,
# an empty file just makes diff -q identical (→ guard=pass, which
# is correct: nothing substantive changed).
git diff -- '*.md' | grep -E '^-' | grep -vE '^---' | sed 's/^-//' | sed -E "s/${STAR_RE}//g" | sort > "$TMP/old" || true
git diff -- '*.md' | grep -E '^\+' | grep -vE '^\+\+\+' | sed 's/^+//' | sed -E "s/${STAR_RE}//g" | sort > "$TMP/new" || true
if ! diff -q "$TMP/old" "$TMP/new" >/dev/null; then
echo "--- non-★ content changed (star-stripped diff) ---"
diff "$TMP/old" "$TMP/new" | head -20
fail "diff changed non-★ content (star-stripped line bodies differ)"
fi
# (d) no zero/garbage star written (archived/private/API-error → ★ 0)
if git diff -- '*.md' | grep -E '^\+' | grep -vE '^\+\+\+' | grep -qE '★ 0([^0-9]|$)'; then
fail "a new ★ value is 0 (repo likely archived / private / API error)"
fi
# (e) magnitude + file-count bounds (mass-zeroing / runaway rewrite)
changed="$(git diff --numstat | awk '{a+=$1; d+=$2} END{print a+d+0}')"
if [ "${changed:-0}" -gt 150 ]; then
fail "change magnitude ${changed} lines > 150 (suspicious for a star refresh)"
fi
repos="$(git diff --name-only -- '*.md' | wc -l | tr -d ' ')"
if [ "${repos:-0}" -gt 40 ]; then
fail "${repos} files changed > 40 (possible mass API anomaly)"
fi
# (f) anchors still valid after the rewrite
if ! python scripts/check-anchors.py --strict; then
fail "check-anchors --strict failed after refresh"
fi
echo "guard=pass" >> "$GITHUB_OUTPUT"
echo "GUARD PASS — only ★ annotations changed (${changed} lines, ${repos} files); anchors OK"
- name: Create PR (drift detected)
# guard.outcome=='success' = guard step exited 0 (i.e. guard=pass OR
# guard=fail — both intended). If the guard step itself ERRORED
# (non-zero), outcome=='failure' → no PR is opened, the red job is
# the single clear signal (no orphan unlabeled PR).
if: steps.refresh.outputs.drift == 'true' && steps.guard.outcome == 'success'
id: cpr
uses: peter-evans/create-pull-request@v8
with:
token: ${{ secrets.GITHUB_TOKEN }}
branch: auto/weekly-star-refresh
delete-branch: true
commit-message: |
chore(catalog): weekly auto-refresh of GitHub star counts
Generated by .github/workflows/weekly-catalog-refresh.yml
title: "chore(catalog): weekly auto-refresh of GitHub star counts"
body: |
## Weekly star count refresh
Auto-generated by `weekly-catalog-refresh.yml` (`refresh-stars.py
--apply`). An in-workflow sanity guard decides what happens next:
- **guard PASS** → auto-squash-merged (only `★` star annotations
changed; no log/non-`.md`/deleted/renamed files; no `★ 0`;
≤150 lines / ≤40 files; anchors still valid). No human action.
- **guard FAIL** → this PR stays **open**, labelled
`needs-manual-review`, with a comment naming the failed check.
### Skip a week
Just close the PR — next Monday a fresh PR opens with current numbers.
🤖 Generated weekly by GitHub Actions
labels: |
automation
catalog-refresh
- name: Auto-merge (guard passed)
if: >-
steps.refresh.outputs.drift == 'true' &&
steps.guard.outputs.guard == 'pass' &&
steps.cpr.outputs.pull-request-number
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
PR: ${{ steps.cpr.outputs.pull-request-number }}
run: |
set -uo pipefail
ensure_label() {
gh label create "needs-manual-review" --color "d93f0b" \
--description "Auto-merge withheld by a guard; needs a human" 2>/dev/null || true
}
echo "Guard passed — waiting for PR #$PR mergeability, then squash-merge"
for i in $(seq 1 12); do
state="$(gh pr view "$PR" --json mergeable --jq .mergeable 2>/dev/null || echo UNKNOWN)"
echo "attempt $i: mergeable=$state"
if [ "$state" = "MERGEABLE" ]; then
gh pr merge "$PR" --squash --delete-branch
gh pr comment "$PR" --body "✅ Auto-merged by sanity guard (guard=pass — only ★ star annotations changed). 🤖 weekly-catalog-refresh"
exit 0
fi
if [ "$state" = "CONFLICTING" ]; then
ensure_label
gh pr edit "$PR" --add-label "needs-manual-review" || true
gh pr comment "$PR" --body "⚠️ Guard passed but PR is CONFLICTING — manual resolution needed. 🤖 weekly-catalog-refresh"
exit 0
fi
sleep 5
done
ensure_label
gh pr edit "$PR" --add-label "needs-manual-review" || true
gh pr comment "$PR" --body "⚠️ Guard passed but GitHub did not confirm mergeability within ~60s — please merge manually. 🤖 weekly-catalog-refresh"
exit 0
- name: Flag for manual review (guard failed)
if: >-
steps.refresh.outputs.drift == 'true' &&
steps.guard.outputs.guard == 'fail' &&
steps.cpr.outputs.pull-request-number
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
PR: ${{ steps.cpr.outputs.pull-request-number }}
REASON: ${{ steps.guard.outputs.reason }}
run: |
set -uo pipefail
gh label create "needs-manual-review" --color "d93f0b" \
--description "Auto-merge withheld by a guard; needs a human" 2>/dev/null || true
gh pr edit "$PR" --add-label "needs-manual-review" || true
# REASON passed via env (NOT inlined into shell) → no script injection
{
echo '⚠️ **Auto-merge withheld — sanity guard failed.**'
echo
echo 'Reason:'
echo '```'
printf '%s\n' "$REASON"
echo '```'
echo
echo 'Review the `Files changed` tab: if it is genuinely just star-count'
echo 'updates, merge manually; otherwise close it and investigate'
echo '`scripts/refresh-stars.py`.'
echo
echo '🤖 weekly-catalog-refresh guard'
} > "$RUNNER_TEMP/guard-comment.md"
gh pr comment "$PR" --body-file "$RUNNER_TEMP/guard-comment.md"
link-check:
name: Scan for broken links
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Setup Python
uses: actions/setup-python@v6
with:
python-version: '3.11'
- name: Install dependencies
run: pip install requests
- name: Scan links (fast mode — GitHub repos only, weekly cadence)
run: |
python scripts/check-links.py --fast --quiet > link-report.txt 2>&1 || true
echo "--- broken links ---"
cat link-report.txt | head -50
if grep -qE "FAIL|404|timeout|error" link-report.txt; then
echo "broken=true" >> "$GITHUB_OUTPUT"
else
echo "broken=false" >> "$GITHUB_OUTPUT"
fi
id: linkcheck
- name: Open issue if broken links found
if: steps.linkcheck.outputs.broken == 'true'
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
existing=$(gh issue list --label "broken-links" --state open --json number --jq 'length')
if [ "$existing" -gt 0 ]; then
echo "An open broken-links issue already exists. Skipping new issue creation."
exit 0
fi
gh issue create \
--title "weekly link check: broken links detected ($(date -u +%Y-%m-%d))" \
--label "broken-links,automation" \
--body "$(printf '## Broken link report\n\n`check-links.py --fast` flagged the following URLs. Verify, then either fix the link, replace with a working alternative, or remove if the resource is genuinely gone.\n\n```\n%s\n```\n\n🤖 Generated weekly by GitHub Actions. To suppress next week, fix the listed links — next Monday the scan reruns.' "$(cat link-report.txt | head -100)")"
.gitignore
+34
View File
@@ -0,0 +1,34 @@
# OS
.DS_Store
Thumbs.db
# Editor
.vscode/
.idea/
*.swp
# Local
.env
.cache/
# Generated
_build/
node_modules/
.ai/
__pycache__/
# Phase 5 build artifacts (mdBook + PDF)
book/dist/
book/src/
dist/
mermaid.min.js
mermaid-init.js
# SVG artifacts from earlier cairosvg attempts (PIL is the canonical generator now)
resources/diagrams/stage5-stack*.svg
# CI workflow scratch files (mirror sync reminder generates this temporarily)
.mirror-sync-comment.md
# weekly-catalog-refresh.yml diagnostic logs — must NOT leak into the auto-PR
star-refresh.log
link-report.txt
CAPSTONE.en.md
+97
View File
@@ -0,0 +1,97 @@
# Capstone
> [繁體中文](./CAPSTONE.md) | [简体中文](./CAPSTONE.zh-Hans.md) | **English**
After finishing a track, **build something yourself** — this file is not a tutorial, not a walkthrough, and there is no model answer. Its purpose is to turn "I read the roadmap" into "I have something I can show + a grade I gave myself."
**How to use this file**:
1. Pick **a problem you actually have** (work, research, daily life). Don't pick a toy problem — a capstone's value comes from being real.
2. Check your track's "Prerequisites" and confirm the required stages have each passed their "Self-check".
3. When done, **self-assess with the matching rubric** (4 levels: Not yet / Basic / Good / Excellent). Scoring honestly is more useful than scoring high.
4. Want feedback? Post the artifact + your self-assessment to [Discussion](https://github.com/WenyuChiou/awesome-agentic-ai-zh/discussions) for peer review (optional, not required).
> What each stage teaches / what you need before it / how you know you've learned it — all of that stays with the stage file's "Learning objectives / Prerequisites / Self-check". This file only defines the **capstone** itself.
---
## Track A Capstone — CLI Power User
**Prerequisites**: Stage 0–2 + A1 + A2 + Stage 5 + A3 have each passed their self-check (Stage 8 is a shared hub across both tracks — recommended, but it does not gate capstone entry; the Track A capstone focuses on the CLI workflow).
**Brief**: Assemble a CLI-agent workflow **you will reuse**, automating something you currently do by hand.
**Requirements** (all mandatory):
- A CLI agent (Claude Code or equivalent) at the core
- At least **1** MCP server **or** a skill / command you wrote yourself
- A clear input → a usable artifact out (not "chatting with it")
- **Reproducible by someone else**: include `how to run` (install, configure, run, expected output)
- Handles at least **1 failure case** (missing input, API failure, what happens when the result is wrong)
**Deliverables**: a folder / repo with the artifact + `README` + evidence of at least one real run (log / screenshot / output file) + a reflection under 150 words (where you got stuck, what you'd change next time).
**Time**: 3–8 hours (not counting time spent learning the stages).
### Track A scoring rubric (self-assessed, 4 levels)
| Dimension | Not yet | Basic | Good | Excellent |
|---|---|---|---|---|
| Problem realism | Toy problem | Somewhat useful | Real, will reuse | Real, with a quantifiable metric (time saved / fewer errors etc.) |
| Tool use | Plain chat only | Used a CLI agent | + MCP or self-written skill/command | Multi-component, with justified choices |
| Reproducibility | Only runs for you | Steps incomplete | Others can run it from the README | One-click / fully automated with pre-checks |
| Robustness | Crashes on any error | Risks mentioned | Handles 1 failure | Multiple failures have fallbacks |
| Docs & reflection | None | Has a README | Clear README + reflection | Reflection points to a concrete next improvement |
---
## Track B Capstone — Agent Builder
**Prerequisites**: Stage 0–8 (including Stage 3, 4, 5, 6, 7, 7.5, 8) have each passed their self-check.
**Brief**: Design, build, and **evaluate** a small system that solves a concrete problem. Pick one:
- **A. Multi-agent**: ≥ 2 cooperating agents with orchestration logic; or
- **B. RAG system**: a complete retrieval + generation pipeline.
**Requirements** (all mandatory):
- Has tool use
- Has one outward interface (CLI / API / chat — any one, mapping to Stage 8)
- **Has explicit evaluation**: define ≥ 5 test cases yourself + measure a pass rate / qualitative assessment (this one is non-negotiable — the thing this curriculum most often skips is "verification")
- **Failure-mode analysis**: write down under what conditions it breaks and how you'd know
- An architecture sketch (a diagram or a paragraph describing components and data flow)
**Deliverables**: a code repo + an architecture description + evaluation results (even just an N-cases / pass-rate table) + `README` + a reflection under 200 words (where the architecture call was wrong, what you'd do differently).
**Time**: 8–20 hours (not counting time spent learning the stages).
### Track B scoring rubric (self-assessed, 4 levels)
| Dimension | Not yet | Basic | Good | Excellent |
|---|---|---|---|---|
| Problem definition | Vague | Has a goal | Clear scope, acceptance-checkable | Clear, and states why it's worth doing |
| Architecture | No design | Just runs | Justified multi-agent / RAG choice | Can articulate the trade-offs |
| Implementation correctness | Doesn't run | Main path runs | Handles edge cases | Stable and the code is readable |
| **Evaluation rigor** | Not tested | Tried it a few times by hand | ≥5 cases + pass rate | Has a baseline comparison / a rerunnable regression |
| Robustness & failure analysis | None | Risks mentioned | Concrete failure modes | Failures are detected + mitigated |
| Interface & docs | None | Runs | Interface + clear README | Others can use it directly |
| Reflection | None | One sentence | Concrete (names a specific problem in the architecture or component choice) | Points to an architecture-level next step |
---
## Pick a brief by role (audience flavor)
Same capstone — just swap in your scenario; no need to do a separate one:
- 🔬 **researcher**: literature Q&A / experiment-log organization / data-preprocessing agent
- 💻 **developer**: a review/triage agent inside CI / repo Q&A / automated release notes
- 🎓 **teacher**: question generation + grading support / material rewriting / course Q&A (mind the academic-integrity boundary)
- 📊 **knowledge-worker**: meeting notes → action items / cross-document synthesis / first-draft weekly report
- 👥 **everyday-user**: personal-data consolidation / scheduling and reminders / repetitive-chore automation
---
## How to show your work
- Post to the matching [Discussion](https://github.com/WenyuChiou/awesome-agentic-ai-zh/discussions) category with a link to the artifact + your rubric self-assessment.
- Put it in your own portfolio / GitHub; describe it with concrete facts (what you did, what you measured), and **avoid** hype like "the strongest / the best in the world".
- Want to review someone else's: give feedback against that person's track rubric — about the work, not the person.
> This file only defines the capstone and its scoring. Each stage's learning content and pass conditions stay with that stage's file.
CAPSTONE.md
+97
View File
@@ -0,0 +1,97 @@
# 結業專題 / Capstone
> **繁體中文** | [简体中文](./CAPSTONE.zh-Hans.md) | [English](./CAPSTONE.en.md)
走完一條軌道後,**自己做一個東西出來**——這份檔案不是教學、不是 walkthrough,沒有標準答案。它的用途是把「我讀完 roadmap」變成「我有一個能展示的作品 + 一份自己給自己的評分」。
**怎麼用這份檔案**:
1. 選你**真的有的一個問題**(工作上、研究上、生活上),別挑玩具題目——capstone 的價值來自真實。
2. 對照你那條軌道的「進入條件」,確認該完成的 stage 都過了它的「自我檢查」。
3. 做完後,用對應的 **rubric 自評**(四級:未達 / 基本 / 良好 / 優秀)。誠實打分比分數高更有用。
4. 想要回饋?把成品 + 自評貼到 [Discussion](https://github.com/WenyuChiou/awesome-agentic-ai-zh/discussions) 找人 peer review(可選,不強制)。
> 每一站「學什麼 / 進入前要會什麼 / 怎麼算學會」一律以該 stage 檔案內的「學習目標 / 進入條件 / 自我檢查」為準;這份檔案只定義**結業專題**本身。
---
## Track A Capstone — CLI Power User
**進入條件**:Stage 0–2 + A1 + A2 + Stage 5 + A3 都過了各自的自我檢查(Stage 8 是兩軌共用 hub,建議完成、但不擋 capstone 入場——Track A capstone 聚焦 CLI 工作流)。
**題目**:組一條**你會重複用**的 CLI-agent 工作流,把一件你現在手動做的事自動化。
**必要條件**(缺一不可):
- 用一個 CLI agent(Claude Code 或同類)當核心
- 至少接 **1 個** MCP server **或** 自寫的 skill / command
- 有明確輸入 → 產出可用的成品(不是「跟它聊天」)
- **能被別人重跑**:附 `怎麼跑`(安裝、設定、執行、預期輸出)
- 處理至少 **1 種失敗情況**(輸入缺、API 失敗、結果不對時會怎樣)
**交付物**:一個資料夾 / repo,含成品 + `README` + 至少一次真實執行的證據(log / 截圖 / 產出檔)+ 150 字內的反思(哪裡卡、下次怎麼改)。
**時間**:3–8 小時(不含學 stage 的時間)。
### Track A 評分 rubric(自評,四級)
| 面向 | 未達 | 基本 | 良好 | 優秀 |
|---|---|---|---|---|
| 問題真實度 | 玩具題 | 有點用 | 真實、會重複用 | 真實且有可量化指標(省時 / 減錯次數等) |
| 工具運用 | 只用基本對話 | 用了 CLI agent | + MCP 或自寫 skill/command | 多元件協作且選型有理由 |
| 可重現 | 只有自己跑得動 | 步驟不全 | 別人照 README 跑得起來 | 一鍵 / 全自動且有前置檢查 |
| 韌性 | 一出錯就崩 | 有提到風險 | 處理 1 種失敗 | 多種失敗有 fallback |
| 文件與反思 | 無 | 有 README | README 清楚 + 反思 | 反思具體可指出下一步改進 |
---
## Track B Capstone — Agent Builder
**進入條件**:Stage 0–8(含 Stage 3、4、5、6、7、7.5、8)都過了各自的自我檢查。
**題目**:設計、實作、並**評測**一個解決具體問題的小型系統,二選一:
- **A. Multi-agent**:≥ 2 個分工協作的 agent,有編排邏輯;或
- **B. RAG 系統**:檢索 + 生成的完整管線。
**必要條件**(缺一不可):
- 有 tool use
- 有一個對外 interface(CLI / API / chat 任一,對應 Stage 8)
- **有明確 evaluation**:自己定 ≥ 5 個測試案例 + 量出通過率 / 質性評估(這條不可省——這套課最容易跳過的就是「驗證」)
- **失敗模式分析**:寫清楚它在什麼情況會壞、你怎麼知道
- 架構草圖(一張圖或一段文字說明元件與資料流)
**交付物**:程式 repo + 架構說明 + evaluation 結果(哪怕只是 N 案例 / 通過率表)+ `README` + 200 字內反思(架構哪裡判斷錯、重來會怎麼改)。
**時間**:8–20 小時(不含學 stage 的時間)。
### Track B 評分 rubric(自評,四級)
| 面向 | 未達 | 基本 | 良好 | 優秀 |
|---|---|---|---|---|
| 問題定義 | 模糊 | 有目標 | 範圍清楚、可驗收 | 清楚且說明為何值得做 |
| 架構 | 無設計 | 能跑就好 | multi-agent / RAG 選型有理由 | 設計權衡寫得出來 |
| 實作正確性 | 跑不動 | 主流程能跑 | 邊界情況也處理 | 穩定且程式可讀 |
| **評測嚴謹度** | 沒測 | 手動試幾次 | ≥5 案例 + 通過率 | 有 baseline 對照 / 回歸可重跑 |
| 韌性與失敗分析 | 無 | 提到風險 | 具體失敗模式 | 失敗有偵測 + 緩解 |
| 介面與文件 | 無 | 能跑 | interface + README 清楚 | 別人能直接用 |
| 反思 | 無 | 一句話 | 具體(指得出架構或元件選擇的具體問題) | 指得出架構級的下一步 |
---
## 依身分選題(audience flavor)
同一個 capstone,換你的場景就好——不用另外做:
- 🔬 **researcher**:文獻問答 / 實驗 log 整理 / 資料前處理 agent
- 💻 **developer**:CI 內的 review/triage agent / repo 問答 / 自動化 release note
- 🎓 **teacher**:出題 + 評分輔助 / 教材改寫 / 課程問答(注意學術誠信邊界)
- 📊 **knowledge-worker**:會議記錄 → 行動項 / 跨文件彙整 / 週報初稿
- 👥 **everyday-user**:個人資料彙整 / 行程與提醒 / 重複雜務自動化
---
## 怎麼展示
- 貼到 [Discussion](https://github.com/WenyuChiou/awesome-agentic-ai-zh/discussions) 的對應分類,附成品連結 + 你的 rubric 自評。
- 放進你自己的 portfolio / GitHub;描述用具體事實(做了什麼、量到什麼),**避免**「最強 / 全世界最好」這類話術。
- 想替別人 review:照對方那條軌道的 rubric 給回饋,對事不對人。
> 這份檔案只定義結業專題與評分標準。各 stage 的學習內容與通過條件,仍以該 stage 檔案為準。
CAPSTONE.zh-Hans.md
+97
View File
@@ -0,0 +1,97 @@
# 结业专题 / Capstone
> [繁體中文](./CAPSTONE.md) | **简体中文** | [English](./CAPSTONE.en.md)
走完一条轨道后,**自己做一个东西出来**——这份文件不是教学、不是 walkthrough,没有标准答案。它的用途是把“我读完 roadmap”变成“我有一个能展示的作品 + 一份自己给自己的评分”。
**怎么用这份文件**:
1. 选你**真的有的一个问题**(工作上、研究上、生活上),别挑玩具题目——capstone 的价值来自真实。
2. 对照你那条轨道的“进入条件”,确认该完成的 stage 都过了它的“自我检查”。
3. 做完后,用对应的 **rubric 自评**(四级:未达 / 基本 / 良好 / 优秀)。诚实打分比分数高更有用。
4. 想要反馈?把成品 + 自评贴到 [Discussion](https://github.com/WenyuChiou/awesome-agentic-ai-zh/discussions) 找人 peer review(可选,不强制)。
> 每一站“学什么 / 进入前要会什么 / 怎么算学会”一律以该 stage 文件内的“学习目标 / 进入条件 / 自我检查”为准;这份文件只定义**结业专题**本身。
---
## Track A Capstone — CLI Power User
**进入条件**:Stage 0–2 + A1 + A2 + Stage 5 + A3 都过了各自的自我检查(Stage 8 是两轨共用 hub,建议完成、但不挡 capstone 入场——Track A capstone 聚焦 CLI 工作流)。
**题目**:组一条**你会重复用**的 CLI-agent 工作流,把一件你现在手动做的事自动化。
**必要条件**(缺一不可):
- 用一个 CLI agent(Claude Code 或同类)当核心
- 至少接 **1 个** MCP server **或** 自写的 skill / command
- 有明确输入 → 产出可用的成品(不是“跟它聊天”)
- **能被别人重跑**:附 `怎么跑`(安装、设置、执行、预期输出)
- 处理至少 **1 种失败情况**(输入缺、API 失败、结果不对时会怎样)
**交付物**:一个文件夹 / repo,含成品 + `README` + 至少一次真实执行的证据(log / 截图 / 产出文件)+ 150 字内的反思(哪里卡、下次怎么改)。
**时间**:3–8 小时(不含学 stage 的时间)。
### Track A 评分 rubric(自评,四级)
| 维度 | 未达 | 基本 | 良好 | 优秀 |
|---|---|---|---|---|
| 问题真实度 | 玩具题 | 有点用 | 真实、会重复用 | 真实且有可量化指标(省时 / 减错次数等) |
| 工具运用 | 只用基本对话 | 用了 CLI agent | + MCP 或自写 skill/command | 多组件协作且选型有理由 |
| 可重现 | 只有自己跑得动 | 步骤不全 | 别人照 README 跑得起来 | 一键 / 全自动且有前置检查 |
| 韧性 | 一出错就崩 | 有提到风险 | 处理 1 种失败 | 多种失败有 fallback |
| 文件与反思 | 无 | 有 README | README 清楚 + 反思 | 反思具体可指出下一步改进 |
---
## Track B Capstone — Agent Builder
**进入条件**:Stage 0–8(含 Stage 3、4、5、6、7、7.5、8)都过了各自的自我检查。
**题目**:设计、实作、并**评测**一个解决具体问题的小型系统,二选一:
- **A. Multi-agent**:≥ 2 个分工协作的 agent,有编排逻辑;或
- **B. RAG 系统**:检索 + 生成的完整管线。
**必要条件**(缺一不可):
- 有 tool use
- 有一个对外 interface(CLI / API / chat 任一,对应 Stage 8)
- **有明确 evaluation**:自己定 ≥ 5 个测试案例 + 量出通过率 / 质性评估(这条不可省——这套课最容易跳过的就是“验证”)
- **失败模式分析**:写清楚它在什么情况会坏、你怎么知道
- 架构草图(一张图或一段文字说明组件与数据流)
**交付物**:程序 repo + 架构说明 + evaluation 结果(哪怕只是 N 案例 / 通过率表)+ `README` + 200 字内反思(架构哪里判断错、重来会怎么改)。
**时间**:8–20 小时(不含学 stage 的时间)。
### Track B 评分 rubric(自评,四级)
| 维度 | 未达 | 基本 | 良好 | 优秀 |
|---|---|---|---|---|
| 问题定义 | 模糊 | 有目标 | 范围清楚、可验收 | 清楚且说明为何值得做 |
| 架构 | 无设计 | 能跑就好 | multi-agent / RAG 选型有理由 | 设计权衡写得出来 |
| 实作正确性 | 跑不动 | 主流程能跑 | 边界情况也处理 | 稳定且程序可读 |
| **评测严谨度** | 没测 | 手动试几次 | ≥5 案例 + 通过率 | 有 baseline 对照 / 回归可重跑 |
| 韧性与失败分析 | 无 | 提到风险 | 具体失败模式 | 失败有侦测 + 缓解 |
| 接口与文件 | 无 | 能跑 | interface + README 清楚 | 别人能直接用 |
| 反思 | 无 | 一句话 | 具体(指得出架构或组件选择的具体问题) | 指得出架构级的下一步 |
---
## 依身份选题(audience flavor)
同一个 capstone,换你的场景就好——不用另外做:
- 🔬 **researcher**:文献问答 / 实验 log 整理 / 数据预处理 agent
- 💻 **developer**:CI 内的 review/triage agent / repo 问答 / 自动化 release note
- 🎓 **teacher**:出题 + 评分辅助 / 教材改写 / 课程问答(注意学术诚信边界)
- 📊 **knowledge-worker**:会议记录 → 行动项 / 跨文件汇整 / 周报初稿
- 👥 **everyday-user**:个人数据汇整 / 行程与提醒 / 重复杂务自动化
---
## 怎么展示
- 贴到 [Discussion](https://github.com/WenyuChiou/awesome-agentic-ai-zh/discussions) 的对应分类,附成品链接 + 你的 rubric 自评。
- 放进你自己的 portfolio / GitHub;描述用具体事实(做了什么、量到什么),**避免**“最强 / 全世界最好”这类话术。
- 想替别人 review:照对方那条轨道的 rubric 给反馈,对事不对人。
> 这份文件只定义结业专题与评分标准。各 stage 的学习内容与通过条件,仍以该 stage 文件为准。
CHANGELOG.md
+198
View File
@@ -0,0 +1,198 @@
# Changelog
Last 14 days of substantive changes. Older history lives in `git log`.
Format: `YYYY-MM-DD · category · 1-line summary (commit-sha)`.
---
## 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/<owner>/<repo>` 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/<sha>`
- 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.
CITATION.cff
+31
View File
@@ -0,0 +1,31 @@
cff-version: 1.2.0
title: "awesome-agentic-ai-zh: A trilingual (English / 繁中 / 简中) learning roadmap for agentic AI"
message: "If you use this learning roadmap, please cite it using the metadata below."
type: software
authors:
- family-names: Chiou
given-names: Wenyu
alias: WenyuChiou
- name: "awesome-agentic-ai-zh contributors"
repository-code: "https://github.com/WenyuChiou/awesome-agentic-ai-zh"
url: "https://github.com/WenyuChiou/awesome-agentic-ai-zh"
abstract: >-
A community-curated, trilingual (Traditional Chinese / Simplified
Chinese / English) learning roadmap for agentic AI — covering LLM
basics, prompt design, tool use, agent frameworks, the Claude Code
ecosystem, memory/RAG, and multi-agent production, organized as
staged tracks and audience-specific branches.
license: MIT
version: "2026.06.13"
date-released: "2026-06-13"
keywords:
- agentic-ai
- ai-agents
- llm-agents
- claude-code
- claude-skills
- mcp
- model-context-protocol
- learning-roadmap
- trilingual
- tutorial
CLAUDE.md
+125
View File
@@ -0,0 +1,125 @@
# Project Memory — awesome-agentic-ai-zh
> Standing instructions for any AI agent (Claude, Codex, Gemini) working on this repo. Read this **first** before touching exercises or model recommendations.
## 📍 Repo positioning — read before adding anything
**This repo's role**: **learning roadmap + 240+ curated resources + simple illustrative cases.**
**Benchmark for "what we are NOT"**: [`datawhalechina/hello-agents`](https://github.com/datawhalechina/hello-agents) is the canonical chapter-length zh-TW depth tutorial (16 production capabilities, chapter format). **We don't compete with it; we route to it.**
**Implications when contributing**:
| Decision | Rule |
|---|---|
| New stage-level exercise folder | OK if it adds **a roadmap node + dual-path SDK demo + 1-line punchline**. 70-150 lines starter is the right size. |
| Expanding a starter beyond ~150 lines | **Push back**. If it's growing into chapter-length, add a 📚 callout pointing to hello-agents instead. |
| Adding a 5th `extension` to README | Diminishing return. Keep README tight (under ~200 lines); extra depth goes to the 📚 callout. |
| New resource (lib / paper / tool / framework) | Almost always YES — add to the relevant `精選 Projects` section or `resources/` catalog. Curation is the primary value. |
| New chapter-length tutorial inside this repo | **Push back**. If the topic deserves chapter-length, the right move is: write a 1-page summary + simple illustrative case + 📚 callout to a canonical source (hello-agents / Anthropic Cookbook / framework's own docs). |
| Trilingual mirror priority | zh-TW canonical first; en + zh-Hans mirror when capacity allows. Don't block shipping waiting for 3-lang. |
**One-line summary**: **route → depth, not reinvent**. Every exercise folder ends with 📚 "want chapter-length? go to hello-agents X + [extra ref]".
**Existing examples of this pattern** (as of 2026-05-13):
- All Stage 3 / 4 / 6 / 7 example READMEs have the 📚 callout (20 folders × 1 callout)
- Main README + 3-lang mirror have the positioning statement near 🎯 Why this exists section
- `tracks/cli/` is outline-only on purpose (CLI exercises are bash/markdown/config, not Python SDK; doesn't fit the dual-path frame — that's correct)
## Canonical Ollama models (verified against user's `ollama list`)
| Model tag | When to use | Notes |
|---|---|---|
| **`gemma4:e4b`** | Stage 1 + 2 (plain chat, prompt engineering) | Effective 4B params, ~7.5 GB download, CPU-friendly. **The `:e4b` tag matters** — NOT `gemma3n:e4b`, NOT `gemma3:4b`, NOT `gemma4:latest`. |
| **`gemma4:e2b`** | Low-RAM-machine alternative for Stage 1+2 | ~4 GB, runs on 4 GB RAM machines |
| **`qwen2.5:3b`** | Stage 3+ (tool use / agent / ReAct) | 1.9 GB, **reliable tool-use support** (OpenAI function-calling format), default for any agent / function-calling exercise |
| **`llama3.2:3b`** | `qwen2.5:3b` alternative for tool use | 2.0 GB, similar capability |
| **`mistral-nemo:12b`** | Higher-quality local fallback | 7.1 GB, closer-to-cloud quality |
**Wrong tags I've used in error before** (now fixed across 13 files via `.ai/.../rename_gemma.py`):
- ❌ `gemma3:4b` — older naming, replaced 2026-05-12
- ❌ `gemma3n:e4b` — wrong family, replaced 2026-05-12
- ✅ `gemma4:e4b` — correct (per user's Ollama installation screenshot)
If unsure, ask the user to run `ollama list` and verify.
## Canonical Anthropic models
| Model | Use case | Pricing (per 1M tokens) |
|---|---|---|
| **`claude-fable-5`** | Mythos-class (above Opus); suspended 2026-06-12, **restored 2026-07-01** (controls lifted 2026-06-30); the highest Claude tier | $10 input / $50 output |
| **`claude-haiku-4-5`** | Cheapest cloud option, OK for all exercises | $1 input / $5 output |
| **`claude-sonnet-5`** | Production default, agent development | $3 input / $15 output |
| **`claude-opus-4-8`** | Opus-class flagship; high quality, complex reasoning (Fable 5, restored 2026-07-01, is the tier above) | $5 input / $25 output |
## Framing rules (do not violate)
1. **Claude is the canonical / production reference** in documentation positioning.
2. **Ollama is the practice default** because of cost — students should not be blocked by API fees during learning.
3. **Every exercise must ship BOTH paths**:
- Path A (Ollama, `<details open>`, primary practice runnable)
- Path B (Anthropic, `<details>`, optional cloud-quality comparison)
4. **Every exercise must mention budget explicitly** — single-run cost + total stage cost.
5. **Local LLMs must appear in any model recommendation list** — never list cloud-only options.
## Exercise file conventions
- `starter.py` = Ollama / OpenAI-compatible default (Path A)
- `starter_anthropic.py` = Anthropic SDK version (Path B)
- `test.py` = mock-based tests for the Ollama starter (OpenAI-compat response shape)
- `test_anthropic.py` = mock-based tests for the Anthropic starter (content-block shape)
- `requirements.txt` = both `openai` and `anthropic` pinned
- `README.md` = trilingual switcher + 怎麼跑（兩條 path）+ budget per path + walkthrough + common pitfalls
- Each starter ends with `# === 自我驗證 ===` block containing 2+ `assert` statements
- Each Python file headers Windows-cp950 UTF-8 reconfigure:
```python
import sys
if hasattr(sys.stdout, "reconfigure"):
sys.stdout.reconfigure(encoding="utf-8", errors="replace")
```
## Translation rules
- **zh-TW canonical** (`.md` without language suffix). zh-Hans + en mirror.
- **Claude does translations** — do NOT delegate to Codex/Gemini.
- For zh-Hans bulk char conversion, use a per-char map (script in `.ai/2026/05/12/t2-trad-to-simp/`) then manual fix-up for remaining stragglers.
## Codex delegation rules
- Codex executes bulk batches (multiple exercises following an established pattern).
- Claude writes the pilot template + reviews codex output.
- Codex briefs must include the file structure (starter.py + starter_anthropic.py + test.py + test_anthropic.py + README.md + requirements.txt) and the framing rules above.
- Codex cannot commit (sandbox `.git` permission); Claude commits on its behalf per CLAUDE.md `~/.claude/CLAUDE.md` "agent boundary = commit boundary" rule.
## Existing curriculum state (as of 2026-05-12)
| Component | Status |
|---|---|
| Stage 0-3 inline exercises (3 langs) | ✅ Done — Path A Ollama / Path B Anthropic + budget callouts |
| Stage 3 folder `03-react-from-scratch` | ✅ Pilot rename done — `starter.py` (Ollama) + `starter_anthropic.py` (Anthropic) + dual test files |
| Stage 3 folders `02/04/05/06` | ✅ Phase 3 done (2026-05-12) — Ollama `starter.py` + rename existing → `starter_anthropic.py` + trilingual READMEs in dual-path style |
| Stage 1 folder `04-cross-provider` | ✅ Multi-provider (already includes Ollama via `call_ollama` in README) |
| Stage 1 folder `05-error-handling` | ✅ Phase 3 done (2026-05-12) — openai SDK exceptions + same retry wrapper, trilingual READMEs |
| Stage 3 doc inline simplified examples (練習 2-6) | ✅ Done (2026-05-12) — 5 new `<details>` blocks added inline (Path A 8-15 line cores), trilingual mirror, zh-Hans Trad-char drift fixed at lines 44/47/77/110/152 |
| `examples/stage-5/tool-calling-tutor/` skill | ✅ Done (2026-05-12) — installable Claude Code skill (frontmatter + 5-step body), 3 references (debug-flowchart / schema-evolution / sdk-diff), evals.json with 5 cases, trilingual READMEs + translations. Dual purpose: learner-aid + Stage 5 5.3 meta-example. Cross-referenced from stages/03 + stages/05 |
| Stage 4 (5 exercises) | ✅ Verified 2026-05-13 — ex1 LangGraph+CrewAI comparison, ex2 CrewAI multi-agent roles (CrewAI install fails on Python 3.14, code unmodified), ex3 LangGraph branching+HITL, ex4 Smolagents CodeAct, ex5 Pydantic AI typed output. 14 of 15 test suites verified green; ex2 CrewAI untestable on 3.14 due to tiktoken/regex wheel build failures |
| Stage 6 (5 exercises) | ✅ Verified 2026-05-13 — all 10 test suites green. Fixed 2 bugs: ChromaDB 'kb' collection name (needs 3-512 chars; renamed knowledge_base) + EphemeralClient state leak across test fixtures (added uuid suffix per test) |
| Stage 7 (5 exercises) | ✅ Verified 2026-05-13 — all 10 test suites green. Fixed 1 bug: eval test fake_agent operator precedence (and binds tighter than or) caused test_run_eval_aggregates to fail. FastAPI deploy includes Dockerfile |
| Track A1-A3 (12 CLI exercises) | 🟡 Outline complete (`tracks/cli/A{1,2,3}-*.md` × 3 langs, ~367 lines zh-TW; 12 numbered exercises documented end-to-end with goal / required-reading / hands-on / curated-projects / self-check). `examples/track-a/` folder intentionally NOT built — these exercises are bash + CLAUDE.md + slash command + MCP integration + GitHub Actions yml, **NOT** Python SDK code; the dual-path Ollama/Anthropic framing doesn't apply. Reference doc: [`resources/cli-agents-guide.md`](resources/cli-agents-guide.md) (148 lines). |
| Stage 5 (11 sub-exercises) | ⚪ Pending — different shape (bash / MCP / markdown / CLAUDE.md / SKILL.md / plugin.json authoring, not OpenAI SDK Python). 5.3 has 1 meta-example shipped: [`examples/stage-5/tool-calling-tutor/`](examples/stage-5/tool-calling-tutor/). Other sub- framing TBD — see [`docs/TESTING_PLAN.md`](docs/TESTING_PLAN.md). |
| `examples/README` LLM list + budget table | ✅ Done (3 langs) |
| Per-stage budget callouts | ✅ Done for Stage 1+2+3 (3 langs each) |
## Known follow-up: pilot `03-react-from-scratch` README.en.md + README.zh-Hans.md drift
The zh-TW `README.md` of `examples/stage-3/03-react-from-scratch/` already uses the dual-path layout (Path A primary / Path B optional + budget callouts + mock test mention for both backends). The `README.en.md` and `README.zh-Hans.md` siblings were NOT updated when the pilot's dual-path zh-TW README was written — they still describe the pre-dual-path layout (Anthropic-only `starter.py`, single `test.py`). After Phase 3 the other 5 folders all have aligned trilingual dual-path READMEs, so the pilot is now the lone outlier. Fix when revisiting Stage 3 docs polish — straight translation pass of the zh-TW README is enough.
## Reference scripts (in `.ai/2026/05/12/`)
- `t2-trad-to-simp/convert.py` — zh-TW → zh-Hans bulk char map (Stage 2)
- `t2-trad-to-simp/stage3_convert.py` — Stage 3 練習 1 inline section conversion
- `t2-trad-to-simp/en_swap.py` — Anthropic SDK → OpenAI SDK bulk substitution
- `t2-trad-to-simp/en_pathb_expand.py` — Compact 🦙 hint → full Path B `<details>` block
- `t2-trad-to-simp/rename_gemma.py` — `gemma3n:e4b` → `gemma4:e4b` (this commit's fix)
Keep these scripts — they're reusable for T3+ work.
CODE_OF_CONDUCT.en.md
+75
View File
@@ -0,0 +1,75 @@
# Code of Conduct
> [繁體中文](./CODE_OF_CONDUCT.md) | [简体中文](./CODE_OF_CONDUCT.zh-Hans.md) | **English**
This project adopts [Contributor Covenant 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) as its community code of conduct.
## Our Pledge
We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
## Our Standards
Examples of behavior that contributes to a positive environment for our community include:
- Demonstrating empathy and kindness toward other people
- Being respectful of differing opinions, viewpoints, and experiences
- Giving and gracefully accepting constructive feedback
- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
- Focusing on what is best not just for us as individuals, but for the overall community
Examples of unacceptable behavior include:
- The use of sexualized language or imagery, and sexual attention or advances of any kind
- Trolling, insulting or derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others’ private information, such as a physical or email address, without their explicit permission
- Other conduct which could reasonably be considered inappropriate in a professional setting
## Enforcement Responsibilities
Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
## Scope
This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the maintainer through the following channels:
- Open an issue in this repo with a title prefixed by `[conduct]`, and **@WenyuChiou**; if the content is sensitive and should not be public, prefer GitHub DM to **@WenyuChiou** (this goes directly to the maintainer), or use GitHub's **"Report content"** mechanism to report it to the platform (this goes to GitHub Trust & Safety, not the maintainer)
- All complaints will be reviewed and investigated promptly and fairly
All community leaders are obligated to respect the privacy and security of the reporter of any incident.
## Enforcement Guidelines
Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
1. **Correction** - Community Impact: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
Consequence: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
2. **Warning** - Community Impact: A violation through a single incident or series of actions.
Consequence: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
3. **Temporary Ban** - Community Impact: A serious violation of community standards, including sustained inappropriate behavior.
Consequence: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
4. **Permanent Ban** - Community Impact: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
Consequence: A permanent ban from any sort of public interaction within the community.
## Attribution
This Code of Conduct is adapted from the Contributor Covenant, version 2.1, available at:
<https://www.contributor-covenant.org/version/2/1/code_of_conduct/>
Community Impact Guidelines were inspired by [Mozilla’s code of conduct enforcement ladder](https://github.com/mozilla/diversity).
CODE_OF_CONDUCT.md
+64
View File
@@ -0,0 +1,64 @@
# 貢獻者公約 / Code of Conduct
> **繁體中文** | [简体中文](./CODE_OF_CONDUCT.zh-Hans.md) | [English](./CODE_OF_CONDUCT.en.md)
本專案採用 [Contributor Covenant 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) 作為社群行為準則。
## 我們的承諾
為了營造開放且友善的環境,我們以貢獻者與維護者的身分承諾:讓參與本專案及社群的每一個人,都不會因為年齡、體型、可見或不可見的身心障礙、族裔、性徵、性別認同與表達、經驗水準、教育程度、社經地位、國籍、外貌、種族、宗教,或性取向而受到騷擾。
我們承諾以有助於建立開放、友善、多元、包容且健康社群的方式行動與互動。
## 我們的準則
有助於營造正面環境的行為包括:
- 對他人展現同理與善意
- 尊重不同的意見、觀點與經驗
- 給予並優雅地接受建設性回饋
- 為自己的錯誤負責、向受影響的人致歉,並從經驗中學習
- 以整個社群的最大利益為重,而非只看個人
不可接受的行為包括:
- 使用情色化的語言或影像,以及任何形式的性騷擾或性挑逗
- 出言挑釁、侮辱或貶低性的言論,以及人身或政治攻擊
- 公開或私下的騷擾
- 未經明確許可,公開他人的私人資訊(例如真實姓名、地址、電子郵件)
- 其他在專業場合中可合理認定為不當的行為
## 執行責任
社群維護者有責任闡明並執行可接受行為的準則,對任何他們認為不當、具威脅性、冒犯或有害的行為,採取適當且公平的糾正措施。
維護者有權移除、編輯或拒絕不符合本準則的留言、commit、程式碼、wiki 編輯、issue 及其他貢獻,並在適當時說明理由。
## 適用範圍
本準則適用於所有專案空間,以及個人在公開場合代表專案或其社群的情況(例如使用官方信箱、透過官方社群帳號發文、或在線上/線下活動中擔任指定代表)。
## 執行
若遇到辱罵、騷擾或其他不可接受的行為,可透過以下管道向維護者檢舉:
- 在本 repo 開一個標題以 `[conduct]` 開頭的 issue,並 **@WenyuChiou**;若內容敏感不宜公開,請優先透過 GitHub 私訊 **@WenyuChiou**(這會直接送到維護者),或使用 GitHub 的 **「Report content / 檢舉內容」** 機制向平台舉報(這是送到 GitHub 信任與安全團隊,非維護者)
- 所有檢舉都會被即時且公平地審視與處理
維護者有義務尊重檢舉者的隱私與安全。
## 執行準則
維護者會依以下「社群影響準則」判斷違規後果:
1. **更正** — 私下書面提醒,說明違規之處,可能要求公開道歉。
2. **警告** — 對單一事件或一連串行為提出警告,並在一段時間內限制互動。
3. **暫時停權** — 一段時間內禁止與社群任何形式的互動。
4. **永久停權** — 永久禁止參與社群。
## 歸屬
本準則改編自 [Contributor Covenant](https://www.contributor-covenant.org) 2.1 版,原文:
<https://www.contributor-covenant.org/version/2/1/code_of_conduct/>
社群影響準則受 [Mozilla 的行為準則執行階梯](https://github.com/mozilla/diversity) 啟發。
CODE_OF_CONDUCT.zh-Hans.md
+64
View File
@@ -0,0 +1,64 @@
# 贡献者公约 / Code of Conduct
> [繁體中文](./CODE_OF_CONDUCT.md) | **简体中文** | [English](./CODE_OF_CONDUCT.en.md)
本项目采用 [Contributor Covenant 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) 作为社区行为准则。
## 我们的承诺
为了营造开放且友善的环境，我们以贡献者与维护者的身份承诺：让参与本项目及社区的每一个人，都不会因为年龄、体型、可见或不可见的身心障碍、族裔、性征、性别认同与表达、经验水平、教育程度、社会经济地位、国籍、外貌、种族、宗教，或性取向而受到骚扰。
我们承诺以有助于建立开放、友善、多元、包容且健康社区的方式行动与互动。
## 我们的准则
有助于营造正面环境的行为包括：
- 对他人展现同理与善意
- 尊重不同的意见、观点与经验
- 给予并优雅地接受建设性反馈
- 为自己的错误负责、向受影响的人道歉，并从经验中学习
- 以整个社区的最大利益为重，而非只看个人
不可接受的行为包括：
- 使用情色化的语言或图像，以及任何形式的性骚扰或性挑逗
- 出言挑衅、侮辱或贬低性的言论，以及人身或政治攻击
- 公开或私下的骚扰
- 未经明确许可，公开他人的私人信息（例如真实姓名、地址、电子邮件）
- 其他在专业场合中可合理认定为不当的行为
## 执行责任
社区维护者有责任阐明并执行可接受行为的准则，对任何他们认为不当、具威胁性、冒犯或有害的行为，采取适当且公平的纠正措施。
维护者有权移除、编辑或拒绝不符合本准则的留言、commit、代码、wiki 编辑、issue 及其他贡献，并在适当时说明理由。
## 适用范围
本准则适用于所有项目空间，以及个人在公开场合代表项目或其社区的情况（例如使用官方邮箱、通过官方社交账号发文、或在线上/线下活动中担任指定代表）。
## 执行
若遇到辱骂、骚扰或其他不可接受的行为，可通过以下渠道向维护者举报：
- 在本 repo 开一个标题以 `[conduct]` 开头的 issue，并 **@WenyuChiou**；若内容敏感不宜公开，请优先通过 GitHub 私信 **@WenyuChiou**（这会直接送到维护者），或使用 GitHub 的 **“Report content / 举报内容”** 机制向平台举报（这是送到 GitHub Trust & Safety 团队，不是维护者）
- 所有举报都会被及时且公平地审视与处理
维护者有义务尊重举报者的隐私与安全。
## 执行准则
维护者会依以下“社区影响准则”判断违规后果：
1. **更正** — 私下书面提醒，说明违规之处，可能要求公开道歉。
2. **警告** — 对单一事件或一连串行为提出警告，并在一段时间内限制互动。
3. **暂时封禁** — 一段时间内禁止与社区任何形式的互动。
4. **永久封禁** — 永久禁止参与社区。
## 归属
本准则改编自 [Contributor Covenant](https://www.contributor-covenant.org) 2.1 版，原文：
<https://www.contributor-covenant.org/version/2/1/code_of_conduct/>
社区影响准则受 [Mozilla 的行为准则执行阶梯](https://github.com/mozilla/diversity) 启发。
CONTRIBUTING.en.md
+117
View File
@@ -0,0 +1,117 @@
# Contributing
> [繁體中文](./CONTRIBUTING.md) | [简体中文](./CONTRIBUTING.zh-Hans.md) | **English**
Thanks for considering a contribution. **This is a curated learning roadmap, not an exhaustive catalog. Quality > quantity.**
This repo is **designed for community-driven improvement** — one person can't keep pace with the AI agent ecosystem alone. The maintainer's quarterly review isn't enough; more eyes are needed.
The catalog is split into **two tracks**: **Track A** (CLI Power User, `tracks/cli/A1-A3`) and **Track B** (Agent Builder, `stages/03-07`). When contributing, please indicate which track you're modifying — the two have different audiences.
## 🚪 First-time contribution: 5 easy starting points
Not sure where to start? Pick one you can finish in 30 minutes:
1. **🐛 Report a stale entry**: run `python scripts/refresh-stars.py`, find repos with significant star drift, open an issue saying "this should be removed / updated"
2. **🔗 Fix one broken link**: hit a 404 reading stage X? Just PR the fix
3. **✍️ Fill in an entry's "Run it" section**: many entries lack install commands; if you've run it, add them
4. **🌏 Improve one English companion sentence**: pick any `.en.md`, compare to the zh version, fix one awkward translation
5. **💬 Add a personal note to an entry**: stuck on `Exercise 3`? Add a "Note: xxx" line
None of these require reading the full style-guide first; they merge fast — perfect for a first PR.
> 🧪 **Running the walkthrough / build script / CI workflow for the first time?** See [`.github/TESTING-STATUS.md`](.github/TESTING-STATUS.md) — an **honest disclosure** of what the maintainer has actually executed vs only syntax-checked vs not tested at all. Being the first to hit a bug and open an issue + PR is the highest-value contribution.
## What We Accept
### High-value PRs
- **Adding a project** to a stage with reasoning for why it teaches that stage
- **Translating** a stage page to 繁中 (Traditional Chinese only — we are NOT zh-Hans)
- **Flagging stale / unmaintained projects** (open an issue first)
- **Improving curation notes** on existing projects (clearer "what it teaches" explanations)
- **Reorganizing** within a stage if the current ordering doesn't match learning progression
### Lower priority (still welcome)
- Typo fixes
- Link fixes (verify with `curl -I` first)
- Stage description polish
### Not accepted
- Bulk additions of repos without curation reasoning
- Self-promotion without educational value
- Projects with no documentation
- Projects without clear license
## How to Add a Project
Each project in a stage page should follow this format:
```markdown
### [Project Name](url)
| Field | Value |
|---|---|
| Language | Python / TS / etc. |
| Stars | ★ k |
| License | MIT / Apache 2 / ... |
| Recommendation | ⭐⭐⭐⭐ |
**What it teaches**: 1-sentence summary of the core learning.
**Best for**: who should study this and why.
**Notes**: 1-3 sentence personal evaluation. What's strong, what's weak, what to skip.
**Run it**:
\`\`\`bash
# minimal install / first-run command
\`\`\`
```
## Curation Criteria
A project worth listing must have:
1. **Active maintenance**: commits within last 6 months OR explicit "stable, no longer maintained" notice
2. **Documented hello-world**: a reader should be able to run something within 30 minutes
3. **Clear license**: MIT, Apache 2, BSD, or comparable. Avoid no-license repos.
4. **Trustworthy maintainer**: well-known org, company, or individual with track record
## Bilingual Style
- **Traditional Chinese (zh-TW) is canonical**; English (`*.en.md`) is the companion.
- **No zh-Hans PRs accepted**. If you submit zh-Hans we'll ask you to convert.
- **Natural translation**, not word-for-word. Technical terms can stay in English where natural ("使用 LangGraph 建 multi-agent 系統").
- **Full style rules: see [`resources/style-guide.md`](resources/style-guide.md)** (zh) or [`resources/style-guide.en.md`](resources/style-guide.en.md) (en) — banned words, entry schema, license conventions, writing style, recommendation star definitions all live there. Read before PR.
## Process
1. Open an issue first for new projects or bigger restructuring
2. PR with focused scope (one stage at a time)
3. Wait for review (typically 7 days)
4. Reviewer may ask for clarification on "why this teaches that stage"
## Anti-patterns to Avoid
- ❌ "leverage", "delve", "comprehensive", "robust" (LLM-tells)
- ❌ Hype framing ("revolutionary", "game-changing")
- ❌ Listing a project just because it's popular
- ❌ Long quotes from the project's own marketing copy
## Becoming a Stage / Branch Maintainer
Beyond one-shot PRs, we welcome **long-term maintainers** for specific stages
or branches — responsible for periodic review, triaging issues in that area,
and gating PRs.
Self-nomination process:
1. Open an issue titled `[maintainer] Stage N — your-handle` or `[maintainer] for-X branch — your-handle`
2. State your time commitment (suggested: at least one quarter = 3 months)
3. Briefly describe your background in this area
See [`CONTRIBUTORS.md`](CONTRIBUTORS.md) for the current maintainer roster.
## License
By contributing, you agree your work is licensed under MIT.
CONTRIBUTING.md
+114
View File
@@ -0,0 +1,114 @@
# 貢獻指南
> **繁體中文** | [简体中文](./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 授權。
CONTRIBUTING.zh-Hans.md
+114
View File
@@ -0,0 +1,114 @@
# 贡献指南
> [繁體中文](./CONTRIBUTING.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.zh-Hans.md`](resources/style-guide.zh-Hans.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 授权。
CONTRIBUTORS.md
+92
View File
@@ -0,0 +1,92 @@
# 貢獻者 / Contributors
謝謝每一個讓這份 repo 變更好的人。
---
## 🛠 Maintainer
- [@WenyuChiou](https://github.com/WenyuChiou) — 創立、整體 curation、phase 1-5 主要作者
## 🌱 Stage 維護者 / Stage maintainers
> 每個 stage 都歡迎社群志願者掛名**長期維護者**——有空時 review 一輪、處理該 stage 的 issue、把關 PR。沒有強制節奏。
>
> 想擔任 maintainer？開個 issue 自薦就好，不用承諾固定 review 期程——能做幾次就幾次。
### 共用基礎（Stage 0-2）
| Stage | Maintainer | 加入日期 |
|---|---|---|
| Stage 0 — 基礎準備 | （社群 PR 機會） | — |
| Stage 1 — LLM 入門 | （社群 PR 機會） | — |
| Stage 2 — Prompt 設計 | （社群 PR 機會） | — |
### Track A — CLI Power User
| Stage | Maintainer | 加入日期 |
|---|---|---|
| A1 — CLI Agent 入門 + 選擇 | （社群 PR 機會） | — |
| A2 — CLI Workflow Patterns | （社群 PR 機會） | — |
| A3 — Integration & Production | （社群 PR 機會） | — |
### Track B — Agent Builder
| Stage | Maintainer | 加入日期 |
|---|---|---|
| Stage 3 — Tool Use & Agent 入門 ⭐ | （社群 PR 機會） | — |
| Stage 4 — Agent 框架 | （社群 PR 機會） | — |
| Stage 5 — Claude Code 生態 ⭐⭐（兩條軌共用） | （社群 PR 機會） | — |
| Stage 6 — Memory · RAG · 進階 | （社群 PR 機會） | — |
| Stage 7 — 進階 Multi-Agent | （社群 PR 機會） | — |
## 🌳 Branch 維護者 / Branch maintainers
| Branch | Maintainer | 加入日期 |
|---|---|---|
| 🔬 for-researcher | （社群 PR 機會） | — |
| 💻 for-developer | （社群 PR 機會） | — |
| 🎓 for-teacher | **特別歡迎自薦**（學術引用待深化） | — |
| 📊 for-knowledge-worker | **特別歡迎自薦**（目前最薄） | — |
| 👥 for-everyday-users | （社群 PR 機會） | — |
## 💬 內容貢獻者 / Content contributors
> 每次 merged PR 或實質 issue 修正都會在這裡留名。第一次 contribution 不分大小都會列入。
| Contributor | 貢獻 / Contribution | First contribution |
|---|---|---|
| [@scott0127](https://github.com/scott0127) | **Stage 6 RAG 教材** — chunking strategies guide ([#2](https://github.com/WenyuChiou/awesome-agentic-ai-zh/pull/2))、unit guide overview ([#5](https://github.com/WenyuChiou/awesome-agentic-ai-zh/pull/5)) · **for-teacher 框架** — 3-tier 教師 AI 應用情境 + 學術引用 (Chen 2020 / Mittal 2024) ([#6](https://github.com/WenyuChiou/awesome-agentic-ai-zh/pull/6)) | 2026-05-08 |
| [@xfq](https://github.com/xfq) | **i18n correctness audit** — flagged BCP 47 / W3C compliance issue (`zh-CN` → `zh-Hans`) and provided the script subtag rationale ([#9](https://github.com/WenyuChiou/awesome-agentic-ai-zh/issues/9)). [W3C i18n lead](https://www.w3.org/International/). | 2026-05-10 |
| [@demo112](https://github.com/demo112) | **中國生態 catalog** — 新增 whale (DeepSeek terminal assistant) + a-stock-data (A 股工具包) 到 Chinese ecosystem ([#14](https://github.com/WenyuChiou/awesome-agentic-ai-zh/pull/14)) | 2026-05-14 |
| [@Rain120](https://github.com/Rain120) | **zh-Hans 大陸在地化** — 系統盤點 zh-Hans 鏡像的台灣用詞,促成 `scripts/zh-hans-localize.py`(curated 台→陸詞表 + 大陸引號,已套全 54 檔並進 lint CI gate;貢獻者掛 commit `7f73b8a` Co-Author)([#18](https://github.com/WenyuChiou/awesome-agentic-ai-zh/pull/18)) | 2026-05-16 |
| [@JunLin-Bobby](https://github.com/JunLin-Bobby) | **Stage 3 ReAct 練習 bug fix** — `trace.append` 移進 `for tc in tool_calls:` 迴圈內(原本在外層、一步多 tool 只記錄 `tool_calls[0]`)+ 為 question 內的 lookup key 加引號避免 LLM 跨語轉譯失敗(qwen2.5:3b + gemini-3-flash-preview 雙模型交叉驗證)([#26](https://github.com/WenyuChiou/awesome-agentic-ai-zh/pull/26)) | 2026-05-24 |
| [@thebrierfox](https://github.com/thebrierfox) | **§12 Finance hosted-MCP example** — 新增 YIELD INTELLIGENCE MCP (hosted remote server) 到 §12 其他常用、tri-locale。catalog 第一個用 style-guide §1 非 repo entry exemption 的 hosted-service entry (`形式 = hosted MCP server` 取代 Stars/License)、為 Stage 5 學習者示範 hosted vs self-hosted MCP 架構差異 ([#28](https://github.com/WenyuChiou/awesome-agentic-ai-zh/pull/28)) | 2026-05-26 |
---
## 🤖 AI 工具貢獻
這個 repo 有相當部分的繁體中文翻譯、結構審查、license 驗證、跨檔一致性檢查由 AI 工具協助完成：
- **Claude (Anthropic)** — 主要 curation、結構設計、zh-TW 翻譯、跨 phase planning
- **Codex (OpenAI)** — 多輪審查（Phase 2-5 各一次 + cross-phase audit），抓出實質的 license 錯標、overclaim 用語、文件 drift 問題
- **gh API** — 所有 entry 的 stars / license / pushed-at 都用 `gh api` 驗證過，避免幻覺
人工 review 仍是 ground truth——AI 找出**疑似問題**，最終決定（接受、拒絕、改寫）由 maintainer 拍板。
---
## 怎麼上這份名單
1. **Bug report / 連結修正 / 內容更新**：開 issue 或直接 PR
2. **新增 project entry**：照 [`resources/style-guide.md`](resources/style-guide.md) 的 schema 加，[PR template](.github/PULL_REQUEST_TEMPLATE.md) 會引導 checklist
3. **擔任 stage / branch maintainer**：開 issue 自薦，講清楚你願意 commit 多久（建議至少一季）
4. **改善 walkthroughs / scripts / 文件**：直接 PR
每次合併 PR 後，maintainer 會在這份檔案加你的 GitHub handle + 貢獻摘要。
---
## License
本檔案內容遵循 repo 的 MIT license。貢獻即視為同意以 MIT 授權你的內容。
LICENSE
+21
View File
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 Wenyu Chiou
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
PROGRESS.en.md
+82
View File
@@ -0,0 +1,82 @@
# Progress Tracker
> [繁體中文](./PROGRESS.md) | [简体中文](./PROGRESS.zh-Hans.md) | **English**
This is a checklist **for your own use**. You do not need to submit it, open a PR, or have anyone inspect it. Copy it (or fork the repo), tick your own progress, and see where you are and what comes next.
**How to use it**:
1. Each stage's "Learning goals", "Entry requirements", and "Self-check" live in that stage file. This checklist is only an **overview + entry point** and does not repeat the content.
2. A stage's ✅ condition = you can pass the "**Self-check**" section at the end of that stage. Tick it only after passing, then move to the next stop.
3. You do not need to finish everything. Pick one track (Track A or B) + one audience branch to get started.
> Not sure which track to choose? See the dual-track explanation in [`README.en.md`](README.en.md), or [`branches/DESIGN.md`](branches/DESIGN.md). If you get stuck, open a [Discussion](https://github.com/WenyuChiou/awesome-agentic-ai-zh/discussions).
---
## Shared Foundations (required for both tracks)
- [ ] **Stage 0 — Foundations** · [`stages/00-foundations.en.md`](stages/00-foundations.en.md)
✅ Pass this stage's completion criteria (Stage 0 is a prerequisite gateway; see the stage file for the criteria)
- [ ] **Stage 1 — LLM Basics** · [`stages/01-llm-basics.en.md`](stages/01-llm-basics.en.md)
✅ Pass this stage's "Self-check"
- [ ] **Stage 2 — Prompt Design** · [`stages/02-prompt-engineering.en.md`](stages/02-prompt-engineering.en.md)
✅ Pass this stage's "Self-check"
---
## Track A — CLI Power User
> You want to **use** agent tools to get work done, and you do not necessarily want to build them yourself.
- [ ] **A1 — CLI Agent Introduction + Selection** · [`tracks/cli/A1-cli-intro.en.md`](tracks/cli/A1-cli-intro.en.md)
- [ ] **A2 — CLI Workflow Patterns** · [`tracks/cli/A2-cli-workflow.en.md`](tracks/cli/A2-cli-workflow.en.md)
- [ ] **Stage 5 — Claude Code Ecosystem (shared by both tracks)** · [`stages/05-claude-code-ecosystem.en.md`](stages/05-claude-code-ecosystem.en.md)
- [ ] **A3 — Integration & Production** · [`tracks/cli/A3-cli-production.en.md`](tracks/cli/A3-cli-production.en.md)
- [ ] **Stage 8 — Agent Interfaces (shared by both tracks)** · [`stages/08-agent-interfaces.en.md`](stages/08-agent-interfaces.en.md)
---
## Track B — Agent Builder
> You want to **build** agents, frameworks, or multi-agent systems yourself.
- [ ] **Stage 3 — Tool Use and Your First Agent** ⭐ · [`stages/03-tool-use-and-hello-agent.en.md`](stages/03-tool-use-and-hello-agent.en.md)
- [ ] **Stage 4 — Agent Frameworks** · [`stages/04-agent-frameworks.en.md`](stages/04-agent-frameworks.en.md)
- [ ] **Stage 5 — Claude Code Ecosystem** ⭐⭐(shared by both tracks)· [`stages/05-claude-code-ecosystem.en.md`](stages/05-claude-code-ecosystem.en.md)
- [ ] **Stage 6 — Context Management: RAG and Memory** · [`stages/06-memory-rag.en.md`](stages/06-memory-rag.en.md)
- [ ] **Stage 7 — Multi-Agent · Advanced Applications** · [`stages/07-multi-agent-production.en.md`](stages/07-multi-agent-production.en.md)
- [ ] **Stage 7.5 — Advanced Agentic Concepts** · [`stages/07.5-advanced-agentic-concepts.en.md`](stages/07.5-advanced-agentic-concepts.en.md)
- [ ] **Stage 8 — Agent Interfaces (shared by both tracks)** · [`stages/08-agent-interfaces.en.md`](stages/08-agent-interfaces.en.md)
---
## Choose one audience branch (matching your role)
> A branch is not "another course layer". It maps what you learned in the stages above to your real scenario. Pick just one.
- [ ] 🔬 **for-researcher** · [`branches/for-researcher.en.md`](branches/for-researcher.en.md)
- [ ] 💻 **for-developer** · [`branches/for-developer.en.md`](branches/for-developer.en.md)
- [ ] 🎓 **for-teacher** · [`branches/for-teacher.en.md`](branches/for-teacher.en.md)
- [ ] 📊 **for-knowledge-worker** · [`branches/for-knowledge-worker.en.md`](branches/for-knowledge-worker.en.md)
- [ ] 👥 **for-everyday-users** · [`branches/for-everyday-users.en.md`](branches/for-everyday-users.en.md)
---
## Capstone
After finishing a track, build something you can show + self-assess. The brief, requirements, and 4-level rubric all live in [`CAPSTONE.en.md`](CAPSTONE.en.md) — this list is just the checkbox entry point; the standard is not duplicated.
- [ ] **Track A Capstone** — assemble a reusable CLI-agent workflow · [`CAPSTONE.en.md`](CAPSTONE.en.md)
- [ ] **Track B Capstone** — build + **evaluate** a multi-agent / RAG system · [`CAPSTONE.en.md`](CAPSTONE.en.md)
---
## Shortest viable path (if you only want one recommendation)
Do not want to plan it yourself? Follow this path to reach "able to do hands-on work" with roughly the fewest detours:
`Stage 0 → Stage 1 → Stage 2 →` choose a track `→`(Track A: `A1 → A2 → Stage 5 → A3`;Track B: `Stage 3 → Stage 4 → Stage 5 → Stage 6`)`→` your branch `→`(advanced, applies to Track B: `Stage 7 → 7.5 → 8`;Track A's Stage 8 is already in the main path above)`→` your track's **Capstone** (see [`CAPSTONE.en.md`](CAPSTONE.en.md))
---
> This checklist only tracks "where you are". For each stop, "what to learn / what you need before entering / how to know you learned it" is always defined by that stage file's "Learning goals / Entry requirements / Self-check" sections, to avoid splitting the same standard across two places.
PROGRESS.md
+82
View File
@@ -0,0 +1,82 @@
# 學習進度追蹤 / Progress Tracker
> **繁體中文** | [简体中文](./PROGRESS.zh-Hans.md) | [English](./PROGRESS.en.md)
這是一份**給你自己用**的打勾清單——不用提交、不用 PR、沒有人會檢查。複製一份(或 fork repo)勾你自己的進度,知道走到哪、下一站是哪。
**怎麼用**:
1. 每個 stage 的「學習目標」「進入條件」「自我檢查」都在該 stage 檔案裡——這份清單只是**總覽 + 入口**,不重複內容。
2. 一個 stage 的 ✅ 條件 = 你能通過該 stage 結尾的「**自我檢查**」那一節。通過了才勾,勾完往下一站。
3. 不用全部做完。先選一條軌道(Track A 或 B)+ 一條你的 audience branch 就夠開始。
> 不確定選哪條?看 [`README.md`](README.md) 的雙軌說明,或 [`branches/DESIGN.md`](branches/DESIGN.md)。卡住開 [Discussion](https://github.com/WenyuChiou/awesome-agentic-ai-zh/discussions)。
---
## 共用基礎(兩條軌道都要)
- [ ] **Stage 0 — 基礎準備** · [`stages/00-foundations.md`](stages/00-foundations.md)
✅ 過該 stage 的通過條件(Stage 0 是 prerequisite gateway,通過條件見 stage 內說明)
- [ ] **Stage 1 — LLM 基礎** · [`stages/01-llm-basics.md`](stages/01-llm-basics.md)
✅ 過該 stage 的「自我檢查」
- [ ] **Stage 2 — Prompt 設計** · [`stages/02-prompt-engineering.md`](stages/02-prompt-engineering.md)
✅ 過該 stage 的「自我檢查」
---
## Track A — CLI Power User
> 你想「**用** agent 工具把工作做完」,不一定要自己 build。
- [ ] **A1 — CLI Agent 入門 + 選擇** · [`tracks/cli/A1-cli-intro.md`](tracks/cli/A1-cli-intro.md)
- [ ] **A2 — CLI Workflow Patterns** · [`tracks/cli/A2-cli-workflow.md`](tracks/cli/A2-cli-workflow.md)
- [ ] **Stage 5 — Claude Code 生態(兩軌共用)** · [`stages/05-claude-code-ecosystem.md`](stages/05-claude-code-ecosystem.md)
- [ ] **A3 — Integration & Production** · [`tracks/cli/A3-cli-production.md`](tracks/cli/A3-cli-production.md)
- [ ] **Stage 8 — Agent 操作介面(兩軌共用)** · [`stages/08-agent-interfaces.md`](stages/08-agent-interfaces.md)
---
## Track B — Agent Builder
> 你想「**自己 build** agent / 框架 / 多 agent 系統」。
- [ ] **Stage 3 — 工具使用與第一個 Agent** ⭐ · [`stages/03-tool-use-and-hello-agent.md`](stages/03-tool-use-and-hello-agent.md)
- [ ] **Stage 4 — Agent 框架** · [`stages/04-agent-frameworks.md`](stages/04-agent-frameworks.md)
- [ ] **Stage 5 — Claude Code 生態** ⭐⭐(兩軌共用)· [`stages/05-claude-code-ecosystem.md`](stages/05-claude-code-ecosystem.md)
- [ ] **Stage 6 — 上下文管理:RAG 與 Memory** · [`stages/06-memory-rag.md`](stages/06-memory-rag.md)
- [ ] **Stage 7 — Multi-Agent · 進階應用** · [`stages/07-multi-agent-production.md`](stages/07-multi-agent-production.md)
- [ ] **Stage 7.5 — 進階 Agentic 概念** · [`stages/07.5-advanced-agentic-concepts.md`](stages/07.5-advanced-agentic-concepts.md)
- [ ] **Stage 8 — Agent 操作介面(兩軌共用)** · [`stages/08-agent-interfaces.md`](stages/08-agent-interfaces.md)
---
## 選一條 audience branch(對應你的身分)
> Branch 不是「再上一層課」,是把上面 stage 學到的東西**對應到你的實際場景**。挑 1 條就好。
- [ ] 🔬 **for-researcher** · [`branches/for-researcher.md`](branches/for-researcher.md)
- [ ] 💻 **for-developer** · [`branches/for-developer.md`](branches/for-developer.md)
- [ ] 🎓 **for-teacher** · [`branches/for-teacher.md`](branches/for-teacher.md)
- [ ] 📊 **for-knowledge-worker** · [`branches/for-knowledge-worker.md`](branches/for-knowledge-worker.md)
- [ ] 👥 **for-everyday-users** · [`branches/for-everyday-users.md`](branches/for-everyday-users.md)
---
## 結業專題 / Capstone
走完一條軌道後,做一個能展示的作品 + 自評。題目、必要條件、四級評分 rubric 全在 [`CAPSTONE.md`](CAPSTONE.md)——這份清單只放打勾入口,標準不重複。
- [ ] **Track A Capstone** — 組一條會重複用的 CLI-agent 工作流 · [`CAPSTONE.md`](CAPSTONE.md)
- [ ] **Track B Capstone** — build + **評測** 一個 multi-agent / RAG 系統 · [`CAPSTONE.md`](CAPSTONE.md)
---
## 一條最短可行路線(如果你只想要一個建議)
不想自己排?照這個走,大約能在最少繞路下到「能動手做事」:
`Stage 0 → Stage 1 → Stage 2 →` 選軌道 `→`(Track A: `A1 → A2 → Stage 5 → A3`;Track B: `Stage 3 → Stage 4 → Stage 5 → Stage 6`)`→` 你的 branch `→`(進階,Track B 適用:`Stage 7 → 7.5 → 8`;Track A 的 Stage 8 已在上方主線)`→` 你那軌的 **Capstone**(見 [`CAPSTONE.md`](CAPSTONE.md))
---
> 這份清單只追蹤「你走到哪」。每一站「學什麼 / 進入前要會什麼 / 怎麼算學會」一律以該 stage 檔案內的「學習目標 / 進入條件 / 自我檢查」為準——避免同一份標準散兩處。
PROGRESS.zh-Hans.md
+82
View File
@@ -0,0 +1,82 @@
# 学习进度追踪 / Progress Tracker
> [繁體中文](./PROGRESS.md) | **简体中文** | [English](./PROGRESS.en.md)
这是一份**给你自己用**的打勾清单——不用提交、不用 PR、没人会检查。复制一份（或 fork repo）勾你自己的进度，知道走到哪、下一站是哪。
**怎么用**：
1. 每个 stage 的“学习目标”“进入条件”“自我检查”都在该 stage 文件里——这份清单只是**总览 + 入口**，不重复内容。
2. 一个 stage 的 ✅ 条件 = 你能通过该 stage 结尾的“**自我检查**”那一节。通过了才勾，勾完往下一站。
3. 不用全部做完。先选一条轨道（Track A 或 B）+ 一条你的 audience branch 就够开始。
> 不确定选哪条？看 [`README.zh-Hans.md`](README.zh-Hans.md) 的双轨说明，或 [`branches/DESIGN.md`](branches/DESIGN.md)。卡住开 [Discussion](https://github.com/WenyuChiou/awesome-agentic-ai-zh/discussions)。
---
## 共用基础（两条轨道都要）
- [ ] **Stage 0 — 基础准备** · [`stages/00-foundations.zh-Hans.md`](stages/00-foundations.zh-Hans.md)
✅ 通过该 stage 的通过条件（Stage 0 是 prerequisite gateway，通过条件见 stage 内说明）
- [ ] **Stage 1 — LLM 基础** · [`stages/01-llm-basics.zh-Hans.md`](stages/01-llm-basics.zh-Hans.md)
✅ 通过该 stage 的“自我检查”
- [ ] **Stage 2 — Prompt 设计** · [`stages/02-prompt-engineering.zh-Hans.md`](stages/02-prompt-engineering.zh-Hans.md)
✅ 通过该 stage 的“自我检查”
---
## Track A — CLI Power User
> 你想“**用** agent 工具把工作做完”，不一定要自己 build。
- [ ] **A1 — CLI Agent 入门 + 选择** · [`tracks/cli/A1-cli-intro.zh-Hans.md`](tracks/cli/A1-cli-intro.zh-Hans.md)
- [ ] **A2 — CLI Workflow Patterns** · [`tracks/cli/A2-cli-workflow.zh-Hans.md`](tracks/cli/A2-cli-workflow.zh-Hans.md)
- [ ] **Stage 5 — Claude Code 生态(两轨共用)** · [`stages/05-claude-code-ecosystem.zh-Hans.md`](stages/05-claude-code-ecosystem.zh-Hans.md)
- [ ] **A3 — Integration & Production** · [`tracks/cli/A3-cli-production.zh-Hans.md`](tracks/cli/A3-cli-production.zh-Hans.md)
- [ ] **Stage 8 — Agent 操作界面(两轨共用)** · [`stages/08-agent-interfaces.zh-Hans.md`](stages/08-agent-interfaces.zh-Hans.md)
---
## Track B — Agent Builder
> 你想“**自己 build** agent / 框架 / 多 agent 系统”。
- [ ] **Stage 3 — 工具使用与第一个 Agent** ⭐ · [`stages/03-tool-use-and-hello-agent.zh-Hans.md`](stages/03-tool-use-and-hello-agent.zh-Hans.md)
- [ ] **Stage 4 — Agent 框架** · [`stages/04-agent-frameworks.zh-Hans.md`](stages/04-agent-frameworks.zh-Hans.md)
- [ ] **Stage 5 — Claude Code 生态** ⭐⭐(两轨共用)· [`stages/05-claude-code-ecosystem.zh-Hans.md`](stages/05-claude-code-ecosystem.zh-Hans.md)
- [ ] **Stage 6 — 上下文管理：RAG 与 Memory** · [`stages/06-memory-rag.zh-Hans.md`](stages/06-memory-rag.zh-Hans.md)
- [ ] **Stage 7 — Multi-Agent · 进阶应用** · [`stages/07-multi-agent-production.zh-Hans.md`](stages/07-multi-agent-production.zh-Hans.md)
- [ ] **Stage 7.5 — 进阶 Agentic 概念** · [`stages/07.5-advanced-agentic-concepts.zh-Hans.md`](stages/07.5-advanced-agentic-concepts.zh-Hans.md)
- [ ] **Stage 8 — Agent 操作界面(两轨共用)** · [`stages/08-agent-interfaces.zh-Hans.md`](stages/08-agent-interfaces.zh-Hans.md)
---
## 选一条 audience branch（对应你的身份）
> Branch 不是“再上一层课”，是把上面 stage 学到的东西**对应到你的实际场景**。挑 1 条就好。
- [ ] 🔬 **for-researcher** · [`branches/for-researcher.zh-Hans.md`](branches/for-researcher.zh-Hans.md)
- [ ] 💻 **for-developer** · [`branches/for-developer.zh-Hans.md`](branches/for-developer.zh-Hans.md)
- [ ] 🎓 **for-teacher** · [`branches/for-teacher.zh-Hans.md`](branches/for-teacher.zh-Hans.md)
- [ ] 📊 **for-knowledge-worker** · [`branches/for-knowledge-worker.zh-Hans.md`](branches/for-knowledge-worker.zh-Hans.md)
- [ ] 👥 **for-everyday-users** · [`branches/for-everyday-users.zh-Hans.md`](branches/for-everyday-users.zh-Hans.md)
---
## 结业专题 / Capstone
走完一条轨道后,做一个能展示的作品 + 自评。题目、必要条件、四级评分 rubric 全在 [`CAPSTONE.zh-Hans.md`](CAPSTONE.zh-Hans.md)——这份清单只放打勾入口,标准不重复。
- [ ] **Track A Capstone** — 组一条会重复用的 CLI-agent 工作流 · [`CAPSTONE.zh-Hans.md`](CAPSTONE.zh-Hans.md)
- [ ] **Track B Capstone** — build + **评测** 一个 multi-agent / RAG 系统 · [`CAPSTONE.zh-Hans.md`](CAPSTONE.zh-Hans.md)
---
## 一条最短可行路线（如果你只想要一个建议）
不想自己排？照这个走，大约能在最少绕路下到“能动手做事”：
`Stage 0 → Stage 1 → Stage 2 →` 选轨道 `→`（Track A: `A1 → A2 → Stage 5 → A3`;Track B: `Stage 3 → Stage 4 → Stage 5 → Stage 6`）`→` 你的 branch `→`（进阶，Track B 适用：`Stage 7 → 7.5 → 8`;Track A 的 Stage 8 已在上方主线）`→` 你那轨的 **Capstone**（见 [`CAPSTONE.zh-Hans.md`](CAPSTONE.zh-Hans.md)）
---
> 这份清单只追踪“你走到哪”。每一站“学什么 / 进入前要会什么 / 怎么算学会”一律以该 stage 文件内的“学习目标 / 进入条件 / 自我检查”为准——避免同一份标准散两处。
README.en.md
+324
View File
@@ -0,0 +1,324 @@
<div align="right">
<a href="./README.md">繁體中文</a> | <a href="./README.zh-Hans.md">简体中文</a> | <strong>English</strong>
</div>
<div align="center" markdown="1">
![AI Agent Learning Roadmap](resources/diagrams/banner.en.png)
# awesome-agentic-ai-zh
</div>
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![繁中](https://img.shields.io/badge/語言-繁體中文-red)](README.md)
[![简中](https://img.shields.io/badge/語言-简体中文-orange)](README.zh-Hans.md)
[![EN](https://img.shields.io/badge/lang-English-blue)](README.en.md)
![GitHub stars](https://img.shields.io/github/stars/WenyuChiou/awesome-agentic-ai-zh?logo=github)
![GitHub forks](https://img.shields.io/github/forks/WenyuChiou/awesome-agentic-ai-zh?logo=github)
[![Docs site](https://img.shields.io/badge/docs-Pages-2ea44f)](https://wenyuchiou.github.io/awesome-agentic-ai-zh/)
> **Trilingual — the English edition is fully maintained, not a thin machine translation** (only ~0.4% of English lines carry any CJK, almost all intentional bilingual term-mapping). zh-TW is the curation source of truth (new content lands there first); the English and 简中 editions track the same structure, with CI checking localization correctness and anchor integrity across all three.
**Learning roadmap + 240+ curated resources + simple illustrative cases** — three pillars helping you go from "I don't know where to start" to "I can design multi-agent systems". Structured **8-stage** path from LLM fundamentals to multi-agent orchestration, Computer Use / Browser Use / Code Sandbox.
---
## 🎯 Why this exists
**What this repo is**: **a learning roadmap + 240+ curated resources + simple illustrative cases** — three pillars helping AI / AI-agent learners go from "I don't know where to start" to "I can design multi-agent systems."
Concretely:
| Pillar | What it does | Scale |
|---|---|---|
| **Learning roadmap** | Organizes scattered high-quality projects, tutorials, and required reading into **8 stages** (including Stage 5 + Stage 8 as two shared hubs) + 2 tracks + 5 specialized branches, from zero to advanced | 8 stages, 2 tracks |
| **Resource curation** | Each stage curates **240+** projects (star rating, audience, what they teach, how to run) plus an MCP/Skill catalog covering the Chinese AI ecosystem (DeepSeek, Zhipu, Kimi, …) | 240+ projects, 65 MCP/Skill |
| **Simple illustrative cases** | Each stage ships 1-5 **foundational exercises** (70-150 line starter + dual-path Ollama/Anthropic SDK comparison + mock-based tests) | 23 exercise folders |
After the main path, you go from "**LLM user**" to "**agent system builder**" — capable of designing multi-agent collaboration, writing your own MCP server, and shipping real agent systems.
---
## 📋 Table of Contents
- [🎯 Why this exists](#-why-this-exists)
- [📚 Quick Start](#-quick-start)
- [🗺️ Learning Map (Two Tracks)](#️-learning-map-two-tracks)
- [💡 How to Learn](#-how-to-learn)
- [📚 Related Resources](#-related-resources)
- [🤝 Contributing](#-contributing)
- [🙏 Acknowledgments](#-acknowledgments)
- [🎓 Citation](#-citation)
- [☕ Support this project](#-support-this-project)
- [License](#license)
---
## 📚 Quick Start
### 🚀 First time with AI agents / never written code before?
Start here: **[`resources/setup-guide.en.md`](resources/setup-guide.en.md)** — 30-45 minutes from zero, walks you through getting an API key, installing Python, and running your first LLM hello-world.
### Read online
- **[Learning Map (Two Tracks)](#️-learning-map-two-tracks)** — read this section to decide Track A or Track B
- **[Stage 0 Foundations](stages/00-foundations.en.md)** — already know Python / git / API? Skip straight to Stage 1
### Local clone
```bash
git clone https://github.com/WenyuChiou/awesome-agentic-ai-zh.git
cd awesome-agentic-ai-zh
# Start with stages/00-foundations.en.md
```
### ✨ What you get
- 📖 **Fully free** — MIT-licensed, all content open
- 🗺️ **Two learning tracks** — Track A (CLI Power User) for "use existing CLIs"; Track B (Agent Builder) for "build your own". Shared Stages 0-2 foundation.
- 🛠️ **Foundational hands-on exercises** — 1-5 illustrative exercises per stage (specs + dual-path SDK comparison + success criteria). Positioned as **foundational + roadmap verification** — for chapter-length depth exercises see the hello-agents / Anthropic Cookbook callout in each stage
- 🎯 **240+ curated projects** — each with star rating, audience, what it teaches, how to run (incl. local LLM runners: Ollama, llama.cpp, LocalAI, MLX)
- 🌏 **Trilingual, fully maintained** — zh-TW (canonical) / 简中 / English; the English edition is complete, not a thin mirror
- 🎓 **Beyond frameworks: Claude Code ecosystem** — MCP / Skills / Plugins / SDK full stack
- 🔬 **5 specialized branches** — researcher / developer / teacher / knowledge worker / **everyday user**
- ⏱️ **Time commitment, stated upfront** — Track A 8-10 weeks / Track B 16-22 weeks minimum, 5-7 months realistic (5-8 hr/week part-time)
---
## 🗺️ Learning Map (Two Tracks)
![AI Agent Learning Map](resources/diagrams/learning-map.en.png)
After **Stages 0-2 (shared foundations)**, pick a track based on your goal:
- **Track A — CLI Power User**: you want to **USE** existing CLI agents (Claude Code, Codex, OpenCode, Gemini CLI, etc.) to get work done — not build agents from scratch. 3 sub-stages (A1-A3).
- **Track B — Agent Builder**: you want to **BUILD** your own agents — learn frameworks, write ReAct, design multi-agent systems. Stages 3-8 main path.
The two tracks are **not mutually exclusive** — most people start with A to get hands-on, then come back to B for internals (or vice versa). Stage 5 (Claude Code Ecosystem) is used by both tracks.
### Shared Foundations (Stages 0-2)
| Stage | Topic | Key Content | Time |
|---|---|---|---|
| **0** | [Foundations](stages/00-foundations.en.md) | Python · CLI · git · API · JSON | 1-2 wks |
| **1** | [LLM Fundamentals](stages/01-llm-basics.en.md) | tokens · API · model comparison · local LLM | 1 wk |
| **2** | [Prompt Engineering](stages/02-prompt-engineering.en.md) | system prompts · few-shot · CoT | 1-2 wks |
### Track A — CLI Power User (use CLIs to get work done)
| Stage | Topic | Key Content | Time |
|---|---|---|---|
| **A1** | [CLI Agent Intro & Selection](tracks/cli/A1-cli-intro.en.md) | 7-CLI comparison · install · first run | 1 wk |
| **A2** | [CLI Workflow Patterns](tracks/cli/A2-cli-workflow.en.md) | CLAUDE.md · slash commands · multi-step decomposition | 1-2 wks |
| **A3** | [Integration & Production](tracks/cli/A3-cli-production.en.md) | MCP-into-CLI · CI automation · cost / observability | 1-2 wks |
| **+5** | [Stage 5 — Claude Code Ecosystem](stages/05-claude-code-ecosystem.en.md) (**Shared Hub**) | MCP · Skills · Plugins · Subagents; Track A reads 5.1-5.4 (5.5-5.7 optional) | 1-2 wks (Track A view) |
| **+8** | [Stage 8 — Agent Interfaces](stages/08-agent-interfaces.en.md) (**Shared Hub**) | Computer Use · Browser Use · Code Sandbox; Track A reads Track A usage | 1-2 wks (Track A view) |
> **Track A total time**: includes Stages 0-2 (shared foundations) + A1-A3 + **Stage 5 + Stage 8 (two shared hubs) ≈ 8-10 weeks**. Core reference: [`resources/cli-agents-guide.en.md`](resources/cli-agents-guide.en.md).
### Track B — Agent Builder (build agents from scratch)
| Stage | Topic | Key Content | Time |
|---|---|---|---|
| **3** ⭐ | [Tool Use & Hello Agent](stages/03-tool-use-and-hello-agent.en.md) | function calling · ReAct · 5 hands-on exercises | 2-3 wks |
| **4** | [Agent Frameworks](stages/04-agent-frameworks.en.md) | LangGraph · AutoGen · CrewAI · Smolagents | 2-3 wks |
| **5** ⭐⭐ | [Claude Code Ecosystem](stages/05-claude-code-ecosystem.en.md) (**Shared Hub**, Track A also studies) | MCP · Skills · Plugins · Subagents | 3-4 wks (Track B view) |
| **6** | [Context Engineering: RAG and Memory](stages/06-memory-rag.en.md) | vector DB · long-term memory · contextual retrieval | 2 wks |
| **7** | [Multi-Agent · Productionization](stages/07-multi-agent-production.en.md) | multi-agent orchestration · eval · observability · advanced SDK | 2-4 wks |
| **7.5** | [Advanced Agentic Workflow Concepts](stages/07.5-advanced-agentic-concepts.en.md) (reading map) | work boundary · PAR loop · agent-as-judge · 12 advanced concepts + reading list | 1 wk (no code) |
| **8** ⭐⭐ | [Agent Interfaces](stages/08-agent-interfaces.en.md) (**Shared Hub**, Track A also studies) | Computer Use · Browser Use · Code Sandbox; 2024-2026 frontier | 2-3 wks (Track B view) |
> **Track B total time**: minimum **16-22 weeks**, realistic **5-7 months** (5-8 hr/week part-time)
> **Two shared hubs (used by both Track A + Track B)**:
> - **Stage 5** = Claude Code Ecosystem (MCP / Skills / Plugins / Subagents) — Track A learns MCP-into-CLI, Track B learns agent runtime structure
> - **Stage 8** = Agent Interfaces (Computer Use / Browser / Sandbox, 2024-2026 frontier) — Track A learns "how to use" for task delegation, Track B learns "how to build" with embedded interfaces
> 💡 **Want a concrete cross-stage example?** [Build Your First AI Agent in 7 Steps](walkthroughs/build-first-agent-in-7-steps.en.md) — same Paper Summary Bot traced from Stage 1 through Stage 7, ~350 lines of executable code (**Track B**)
After the main path, pick one of 5 specialized branches. **Not sure which?**
![Branch decision tree](resources/diagrams/branch-decision-tree.en.png)
> 💡 **The Everyday User branch can be read directly without walking the main path** — it's for people who want to use AI without writing code.
| Branch | Best for | Topics |
|---|---|---|
| 🔬 [Researcher](branches/for-researcher.en.md) | Grad students, postdocs, PIs | Lit triage · paper writing · multi-agent review |
| 💻 [Developer](branches/for-developer.en.md) | Software engineers | Cursor · Aider · CLI delegation · code review |
| 🎓 [Teacher](branches/for-teacher.en.md) | Teachers, instructors | Lesson planning · slides · student feedback · privacy / ethics · prompt templates |
| 📊 [Knowledge Worker](branches/for-knowledge-worker.en.md) | Consultants, PMs, analysts | Email · meeting notes · report automation |
| 👥 [Everyday User](branches/for-everyday-users.en.md) | ChatGPT / Claude.ai users | Daily writing · learning · privacy · CLI agent intro |
---
## 💡 How to Learn
Welcome — future agent system builder. Some guidance before you start.
This roadmap balances concepts with hands-on work, helping you **transform from an LLM user into an agent system builder**. It assumes **basic Python**. Before starting:
- **Basic Python** — written functions, used APIs, can read JSON
- **Basic git** — clone, commit, push
- **Motivation to learn** — agents are the fastest-changing area in AI 2025+, and require sustained effort
If anything's missing, do Stage 0; if not, **start at Stage 1**.
The main path has 5 parts:
- **Part 1 (Stages 0-2): Foundations & LLM Basics** — Python / git / API, what's an LLM, prompt design
- **Part 2 (Stages 3-4): Build Your Agent** — from tool use to agents, learn the major frameworks
- **Part 3 (Stage 5) Shared Hub** — Claude Code Ecosystem (MCP / Skills / Plugins / Subagents; used by both Track A + B)
- **Part 4 (Stages 6-7): Advanced Integration** — memory / RAG / multi-agent collaboration / harness engineering
- **Part 5 (Stage 8) Shared Hub** — Agent Interfaces (Computer Use / Browser Use / Code Sandbox, 2024-2026 frontier; used by both tracks)
> 🔭 **Three layers of concept evolution**: **prompt engineering** (Stage 2 — how to write a single prompt) → **context engineering** (Stage 3 onward — how to dynamically assemble system prompt + memory + retrieved chunks + tool schema) → **harness engineering** (Stage 7 — agent loop / eval / observability / deploy as a complete production system). Three terms, three phases; you don't need to look elsewhere. See [`stages/02-prompt-engineering.en.md`](stages/02-prompt-engineering.en.md) "Beyond prompts: context engineering" and [`stages/07-multi-agent-production.en.md`](stages/07-multi-agent-production.en.md) Required Reading 5+6.
After the main path (16-22 weeks for Track B, 8-10 weeks for Track A), pick a branch.
The most important advice: **don't skip the hands-on exercises**. Each stage's exercises are "you can't learn this without doing it" — skim past them and you'll get stuck later.
> 🎓 **How to actually use the exercises**: the `starter.py` in each exercise folder is a **complete solution**, not a TODO skeleton. If you clone, `cat starter.py`, and run `python test.py` to all-green, you'll think "I learned it" — but you haven't written a single line. **Correct learning loop**: `mv starter.py starter_reference.py`, look at signatures (not bodies), write your own, peek at the reference only after 20 min stuck. Full method + per-stage time budgets + escalation order in [`docs/HOW_TO_USE.md`](docs/HOW_TO_USE.md).
Ready? [Start at Stage 0](stages/00-foundations.en.md).
---
## 📚 Related Resources
The full related-resources block (term definitions + daily-tool MCP/Skill highlights + awesome lists + Chinese-community resources) lives in **[RESOURCES.en.md](RESOURCES.en.md)** so this README stays focused.
Common quick links, grouped by **scenario**:
### 🚀 Onboarding / Environment
| Your situation | Where | What's there |
|---|---|---|
| Never written code, first time with AI agents | [`resources/setup-guide.en.md`](resources/setup-guide.en.md) | 30-45 min from zero (API key, Python, first hello-world) |
| Not sure which LLM provider to pick | [`resources/setup-guide.en.md` A](resources/setup-guide.en.md#a--get-your-first-api-key-about-10-minutes) | Anthropic / OpenAI / DeepSeek / Kimi / NVIDIA NIM comparison |
| Topic-based awesome lists / Chinese community | [`RESOURCES.en.md` topic-based](RESOURCES.en.md#topic-based-awesome-lists) | 5-10 min skim |
### 📖 Concepts / Terminology
| Your situation | Where | What's there |
|---|---|---|
| Don't know a term (LLM / agent / RAG / token / MCP / Skill / vector DB…) | [`resources/glossary.en.md`](resources/glossary.en.md) | 30+ terms, 30-80 words each + which stage covers it |
| Why some agents live in terminal vs Telegram vs Jetson | [`resources/agent-paradigms.en.md`](resources/agent-paradigms.en.md) | 5 paradigms mental model + Hermes Agent / OpenClaw examples |
| MCP / Skills / Plugins glossary mapping | [`RESOURCES.en.md` three core terms](RESOURCES.en.md#three-core-terms-mcp--skills--plugins) | 1-page lookup |
| Certificate-granting online AI agent courses (EN + ZH) | [`resources/courses.en.md`](resources/courses.en.md) | 10 credible cert-granting courses, tiered; with an honest "completion cert ≠ a degree" caveat |
### 🛠 Hands-on
| Your situation | Where | What's there |
|---|---|---|
| Want to build Skill / MCP server / Word / Zotero / local LLM integration | [`resources/cookbook.en.md`](resources/cookbook.en.md) | 6 step-by-step recipes, 30-50 min each |
| Want to use subagents but do not know who to dispatch, how to dispatch, or what work to dispatch | [`resources/subagent-cookbook.en.md`](resources/subagent-cookbook.en.md) | 15 copy-paste dispatch recipes |
| Stuck on tool calling (LLM won't call / schema broken / ReAct won't stop) | [`examples/stage-5/tool-calling-tutor/`](examples/stage-5/tool-calling-tutor/) | Claude Code installable skill, 4-symptom diagnostic |
| How to use the hands-on exercises correctly (active vs passive mode) | [`docs/HOW_TO_USE.md`](docs/HOW_TO_USE.md) | 5-10 min read, applies to every stage |
### 🔌 Daily tool integrations / Finding MCP servers
| Your situation | Where | Scope |
|---|---|---|
| Connect to Notion / Obsidian / Excel / GitHub / etc. | [`RESOURCES.en.md` daily-tool integrations](RESOURCES.en.md#daily-tool-integrations-mcp-servers--skills) | 7-8 highlights |
| Full MCP server / Skill catalog (stars, categories) | [`resources/mcp-skills-catalog.en.md`](resources/mcp-skills-catalog.en.md) | 65+ entries, 16 categories |
### 🔬 Research / Production
| Your situation | Where | What's there |
|---|---|---|
| Research workflow + multi-LLM delegation skill pair | [`RESOURCES.en.md` research workflow](RESOURCES.en.md#research-workflow-by-the-repo-maintainer) | Maintainer's own Claude Code research skill set |
| CLI agent 7-way comparison + production combos | [`resources/cli-agents-guide.en.md`](resources/cli-agents-guide.en.md) | Track A's core reference, ~148 lines |
| Schema design rules (must-read for tool calling) | [`resources/schema-design-cheatsheet.en.md`](resources/schema-design-cheatsheet.en.md) | 5 golden rules + 5 anti-patterns |
---
## 🤝 Contributing
This repo is an AI learning document — if you've also curated great resources, contributions are very welcome:
- 🐛 **Bug reports** — wrong content, broken links, stale info → open Issue
- 💡 **Suggestions** — missing stage / new project to add → open Issue to discuss
- 📝 **Improvements** — refine existing stage content, fix typos → direct PR
- ✍️ **Add a project** — 1-3 new projects per stage with "why this teaches that stage" rationale
- 🌏 **Translations** — improve the English edition or translate to other languages
- 🌱 **Become a Stage / Branch maintainer** — long-term review of a specific area, see [CONTRIBUTORS.md](CONTRIBUTORS.md)
PR process and style rules: [CONTRIBUTING.md](CONTRIBUTING.md) + [resources/style-guide.en.md](resources/style-guide.en.md).
> 📅 **Want to see what shipped recently?** → [`CHANGELOG.md`](CHANGELOG.md) (last 14 days).
> Internal phase rollout progress and launch checklist: [`.github/launch-checklist.md`](.github/launch-checklist.md) (maintainer-facing internal doc).
---
## 💬 Advisory / Contact
A free, open (MIT) learning edition — use it freely.
Currently focused on advisory work: teams or companies needing **prompt review / audit** or **AI agent workflow consulting** are welcome to reach out (PhD student, limited availability): 📧 [wenyuchiou12@gmail.com](mailto:wenyuchiou12@gmail.com)
---
## 🙏 Acknowledgments
### Inspiration
- [**Datawhale Hello-Agents**](https://github.com/datawhalechina/hello-agents) — the most thorough chapter-length agent tutorial in the Chinese-language ecosystem; inspired our chapter + progress structure. Every stage / exercise folder has a 📚 callout pointing to the relevant depth chapter. Special thanks.
- [**Datawhale community**](https://github.com/datawhalechina) — landmark Chinese ML learning community; multiple anchor projects come from them
- [**liyupi/ai-guide**](https://github.com/liyupi/ai-guide) — largest Chinese-language "AI mega-guide" + Vibe Coding tutorial (covers Agent Skills / RAG / MCP / A2A / Harness Engineering). This repo is a "structured roadmap"; ai-guide is a "breadth resource hub" — complementary
### Related projects
Other lists in the same space — useful to browse alongside this repo when hunting for specific tools:
- [`wong2/awesome-mcp-servers`](https://github.com/wong2/awesome-mcp-servers) — categorized MCP server catalog
- [`punkpeye/awesome-mcp-servers`](https://github.com/punkpeye/awesome-mcp-servers) — another MCP server catalog
- [`hesreallyhim/awesome-claude-code`](https://github.com/hesreallyhim/awesome-claude-code) — Claude Code tools & plugins list
These are pure catalogs (browse and pick). This repo is different in that it has a **learning order from Stage 0 all the way to production**.
### Contributors
[![Contributors](https://contrib.rocks/image?repo=WenyuChiou/awesome-agentic-ai-zh)](https://github.com/WenyuChiou/awesome-agentic-ai-zh/graphs/contributors)
New contributors appear above automatically. Full list → [GitHub Contributors](https://github.com/WenyuChiou/awesome-agentic-ai-zh/graphs/contributors).
### Personal
- [@WenyuChiou](https://github.com/WenyuChiou) — Maintainer
---
## 🎓 Citation
If this learning roadmap helps your study or work, please cite:
```bibtex
@misc{awesome_agentic_ai_zh_2026,
title = {awesome-agentic-ai-zh: A Structured Learning Roadmap for Agentic AI},
author = {Chiou, Wenyu},
year = {2026},
url = {https://github.com/WenyuChiou/awesome-agentic-ai-zh},
note = {8-stage learning path from prerequisites to Agent Interfaces (Computer Use / Browser Use / Code Sandbox), with curated projects + hello-X demos. Bilingual (zh-TW / English).}
}
```
---
## ☕ Support this project
This learning map is free and open-source (MIT). If it helps you, a ⭐ Star means a lot — and if you'd like to support ongoing updates, you can buy the author a coffee:
<a href="https://www.buymeacoffee.com/wenyuchiou" target="_blank" rel="noopener noreferrer"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="44"></a>
Or use the **❤ Sponsor** button at the top of the repo. (GitHub Sponsors is under review and will be added once approved.)
---
## License
MIT. Maintained by [@WenyuChiou](https://github.com/WenyuChiou).
<div align="center">
<p>⭐ If this repo helps you, please give it a Star — it matters for ongoing iteration</p>
</div>
README.md
+330
View File
@@ -0,0 +1,330 @@
<div align="right">
<strong>繁體中文</strong> | <a href="./README.zh-Hans.md">简体中文</a> | <a href="./README.en.md">English</a>
</div>
<div align="center" markdown="1">
![AI Agent 學習路徑](resources/diagrams/banner.png)
# awesome-agentic-ai-zh
### 🤖 AI Agent 學習地圖 — 從基本 LLM 概念到自己打造多 agent 系統
<p><em><b>學習路線圖 + 240+ 資源 curation + 簡單 illustrative 案例</b><br/>結構化 8 階段、從「LLM 是什麼、token 怎麼算」走到 multi-agent 編排、Computer Use / Browser Use / Sandbox</em></p>
[![License](https://img.shields.io/badge/license-MIT-blue?style=flat)](LICENSE)
[![繁中](https://img.shields.io/badge/語言-繁體中文-red?style=flat)](README.md)
[![简中](https://img.shields.io/badge/語言-简体中文-orange?style=flat)](README.zh-Hans.md)
[![EN](https://img.shields.io/badge/lang-English-blue?style=flat)](README.en.md)
![GitHub stars](https://img.shields.io/github/stars/WenyuChiou/awesome-agentic-ai-zh?style=flat&logo=github)
![GitHub forks](https://img.shields.io/github/forks/WenyuChiou/awesome-agentic-ai-zh?style=flat&logo=github)
[![線上文件站](https://img.shields.io/badge/線上文件站-Pages-2ea44f?style=flat)](https://wenyuchiou.github.io/awesome-agentic-ai-zh/)
</div>
---
## 🎯 專案介紹
**本 repo 角色定位**：**學習路線圖 + 240+ 資源 curation + 簡單 illustrative 案例**——三件事為核心、幫想學 AI / AI agent 的人從「不知道從哪開始」走到「能設計多 agent 系統」。
具體做法：
| 核心 | 做什麼 | 規模 |
|---|---|---|
| **學習路線圖** | 把網路散落的高品質專案、教材、必修閱讀，按**從零開始、循序漸進**整理成 **8 個階段**（含 Stage 5 + Stage 8 兩個共用 hub）+ 2 條學習路線 + 5 條延伸路徑 | 8 stages、2 tracks |
| **資源 curation** | 每階段精選 **240+** 個 project（含星等、適合誰、教什麼、怎麼跑），加上中文 AI 生態(DeepSeek / Zhipu / Kimi 等)MCP / Skill 完整 catalog | 240+ projects、65 MCP/Skill |
| **簡單 illustrative 案例** | 每階段附 1-5 個**基礎練習**（70-150 行 starter + dual-path Ollama/Anthropic SDK 對照 + mock-based test） | 23 個練習 folder |
走完整條路線，你會從「**LLM 使用者**」進階到「**agent 系統建構者**」——能看懂 framework 在做什麼、能設計多 agent 協作、能寫自己的 MCP server。
> 📖 **關於中英文混用**：本專案保留 AI Agent 領域常見英文術語（Prompt Engineering / Context Engineering / Harness / MCP / Skills / RAG 等），因為官方文件、paper、GitHub repo 與 API 文件多以英文為主。每個重要概念會提供 **中文理解名 + 英文正式術語 + 一句白話定位**，讓讀者能先理解概念，再對接英文生態。完整對照見 [`resources/glossary.md`](resources/glossary.md)。
---
## 📋 目錄
- [🎯 專案介紹](#-專案介紹)
- [📚 快速開始](#-快速開始)
- [線上閱讀](#線上閱讀)
- [本地下載](#本地下載)
- [✨ 你會收穫什麼？](#-你會收穫什麼)
- [🗺️ 學習地圖（兩條學習路徑）](#️-學習地圖兩條學習路徑)
- [💡 如何學習](#-如何學習)
- [📚 相關資源](#-相關資源)
- [🤝 如何貢獻](#-如何貢獻)
- [🙏 致謝](#-致謝)
- [🎓 引用](#-引用)
- [☕ 支持這個專案](#-支持這個專案)
- [License](#license)
---
## 📚 快速開始
### 🚀 第一次接觸 AI agent / 沒寫過 code？
先看 **[`resources/setup-guide.md`](resources/setup-guide.md)** — 30-45 分鐘從零帶你申請 API key、裝好 Python、跑出第一個 LLM hello-world。
### 線上閱讀
- **[學習地圖（兩條學習路徑）](#️-學習地圖兩條學習路徑)** — 看完這節決定走 Track A 還 Track B
- **[Stage 0 基礎準備](stages/00-foundations.md)** — 已經會 Python / git / API 的人可以直接跳 Stage 1
### 本地下載
```bash
git clone https://github.com/WenyuChiou/awesome-agentic-ai-zh.git
cd awesome-agentic-ai-zh
# 從 stages/00-foundations.md 開始
```
### ✨ 你會收穫什麼？
- 📖 **完全免費** — MIT 授權，所有內容開放共學
- 🗺️ **兩條學習路徑** — Track A（CLI Power User）給「想 USE 現成 CLI agent」的人；Track B（Agent Builder）給「想 BUILD 自己 agent」的人。共用 Stage 0-2 基礎
- 🛠️ **基礎動手練習** — 每階段附 1-5 個 illustrative 練習（題目 + dual-path SDK 對照 + success criteria）。定位是**基礎入門 + 路線確認**——chapter-length 深度練習見對應 stage 的 hello-agents / Anthropic Cookbook callout
- 🎯 **精選 240+ 個 projects** — 每個都附星等推薦、適合誰、教什麼、怎麼跑（含本地 LLM 執行：Ollama、llama.cpp、LocalAI、MLX）
- 🌏 **三語完整維護** — 繁中(canonical)/ 簡中 / English,三版皆完整維護、英文非薄翻譯
- 🎓 **不只「框架」、還有「Claude Code 生態」** — MCP / Skills / Plugins / SDK 完整堆疊
- 🔬 **5 條依使用者分流的延伸路線** — 研究員 / 開發者 / 老師 / 知識工作者 / **日常使用者**
- ⏱️ **預估時程寫清楚** — Track A 8-10 週 / Track B 主幹最少 16-22 週、現實 5-7 個月（每週 5-8 hr）
---
## 🗺️ 學習地圖（兩條學習路徑）
![AI Agent 學習地圖](resources/diagrams/learning-map.png)
走完 **Stage 0-2（共用基礎）** 之後，依你的目的選一條學習路徑：
- **Track A — CLI Power User**：你想**用**現成的 CLI agent（Claude Code、Codex、OpenCode、Gemini CLI 等）把工作做順、效率拉高，不打算自己從零寫 agent。3 個 sub-stage（A1-A3）。
- **Track B — Agent Builder**：你想**從零打造**自己的 agent——學 framework、寫 ReAct、設計 multi-agent。Stage 3-8 是主路線。
兩條學習路徑**不互斥**——多數人是先走 A 把 CLI 用起來，再回到 B 學內部運作；或反過來也行。Stage 5（Claude Code 生態）兩條路徑都會用到。
### 共用基礎（Stage 0-2）
| Stage | 主題 | 關鍵內容 | 預估時程 |
|---|---|---|---|
| **0** | [基礎準備（Foundations）](stages/00-foundations.md) | Python · CLI · git · API · JSON | 1-2 週 |
| **1** | [LLM 基礎（LLM Basics）](stages/01-llm-basics.md) | token · API · 各家 LLM 比較 · 本地 LLM | 1 週 |
| **2** | [Prompt 設計（Prompt Engineering）](stages/02-prompt-engineering.md) | 系統 prompt · few-shot · CoT | 1-2 週 |
### Track A — CLI Power User（想用 CLI 把事情做完）
| Stage | 主題 | 關鍵內容 | 預估時程 |
|---|---|---|---|
| **A1** | [選一個 CLI Agent，開始用它做事（CLI Agent Intro & Selection）](tracks/cli/A1-cli-intro.md) | 7 主流 CLI 比較 · 安裝 · 第一次跑 | 1 週 |
| **A2** | [建立可重複使用的 CLI 工作流程（CLI Workflow Patterns）](tracks/cli/A2-cli-workflow.md) | CLAUDE.md · slash command · 多步驟拆解 | 1-2 週 |
| **A3** | [把 CLI Agent 接進真實工作流程（Integration & Production）](tracks/cli/A3-cli-production.md) | MCP 接 CLI · CI 自動化 · cost / observability | 1-2 週 |
| **+5** | [Stage 5 — Claude Code 生態](stages/05-claude-code-ecosystem.md)（**共用 hub**） | MCP · Skills · Plugins · Subagents、Track A 必看 5.1-5.4 / 選讀 5.5-5.7 | 1-2 週（Track A 視角）|
| **+8** | [Stage 8 — Agent Interfaces](stages/08-agent-interfaces.md)（**共用 hub**）| Computer Use · Browser Use · Code Sandbox、Track A 視角看 Track A 怎麼用 | 1-2 週（Track A 視角）|
> **Track A 預估總時程**：含 Stage 0-2（共用基礎）+ A1-A3 + **Stage 5 + Stage 8（兩個共用 hub）= 約 8-10 週**。核心參考：[`resources/cli-agents-guide.md`](resources/cli-agents-guide.md)。
### Track B — Agent Builder（從零打造 agent）
| Stage | 主題 | 關鍵內容 | 預估時程 |
|---|---|---|---|
| **3** ⭐ | [工具使用與第一個 Agent（Tool Use & Hello Agent）](stages/03-tool-use-and-hello-agent.md) | function calling · ReAct · 5 個動手練習 | 2-3 週 |
| **4** | [Agent 框架（Agent Frameworks）](stages/04-agent-frameworks.md) | LangGraph · AutoGen · CrewAI · Smolagents | 2-3 週 |
| **5** ⭐⭐ | [Claude Code 生態系（Claude Code Ecosystem）](stages/05-claude-code-ecosystem.md)（**共用 hub**、Track A 也學）| MCP · Skills · Plugins · Subagents | 3-4 週（Track B 視角）|
| **6** | [上下文管理（Context Engineering）：RAG 與 Memory](stages/06-memory-rag.md) | vector DB · long-term memory · contextual retrieval | 2 週 |
| **7** | [多 Agent 系統與穩定運作（Multi-Agent & Production）](stages/07-multi-agent-production.md) | multi-agent orchestration · eval · observability · SDK 進階 | 2-4 週 |
| **7.5** | [進階 Agentic Workflow 概念（Advanced Agentic Concepts）](stages/07.5-advanced-agentic-concepts.md)（reading map）| 工作邊界 · PAR loop · agent-as-judge · 12 個進階概念 + reading list | 1 週（不寫 code）|
| **8** ⭐⭐ | [Agent 操作介面（Agent Interfaces）](stages/08-agent-interfaces.md)（**共用 hub**、Track A 也學）| Computer Use · Browser Use · Code Sandbox、2024-2026 frontier | 2-3 週（Track B 視角）|
> **Track B 預估總時程**：主幹最少 **16-22 週**、現實 **5-7 個月**（每週 5-8 hr 兼職）
> **兩個共用 hub（Track A + Track B 都會用到）**：
> - **Stage 5** = Claude Code 生態（MCP / Skills / Plugins / Subagents）—— Track A 學 MCP 接 CLI、Track B 學 agent runtime 結構
> - **Stage 8** = Agent Interfaces（Computer Use / Browser / Sandbox、2024-2026 frontier）—— Track A 學「**怎麼用**」委派任務、Track B 學「**怎麼 build**」embed 進 agent
>
> 兩個 hub 出現在兩條 track 內、視角不同、學的深度也不同（內文有 Track A / Track B 分視角段）。
> 💡 **想看跨 stage 的完整範例？** [7 步打造你的第一個 AI Agent](walkthroughs/build-first-agent-in-7-steps.md) — 同一個 Paper Summary Bot 從 Stage 1 一路寫到 Stage 7，~350 行真實程式碼（**Track B 適用**）
走完主幹後，依你的身分挑一條延伸路線繼續走。**不確定挑哪條？**
![Branch 決策樹](resources/diagrams/branch-decision-tree.png)
> 💡 **「日常使用者」這條路線不必走完主幹就能直接讀**——是給「想用 AI、但不一定要寫 code」的人。
| 路線 | 適合誰 | 主題 |
|---|---|---|
| 🔬 [研究人員](branches/for-researcher.md) | 研究生、博後、PI | 文獻整理 · paper 寫作 · multi-agent review |
| 💻 [開發者](branches/for-developer.md) | 軟體工程師 | Cursor · Aider · CLI delegation · code review |
| 🎓 [教師](branches/for-teacher.md) | 老師、講師 | 備課 · 投影片 · 學生 feedback · 隱私 / 倫理 · prompt 範本 |
| 📊 [知識工作者](branches/for-knowledge-worker.md) | 顧問、PM、分析師 | Email · 會議紀錄 · report 自動化 |
| 👥 [日常使用者](branches/for-everyday-users.md) | ChatGPT / Claude.ai 使用者 | 寫信 · 學習 · 隱私場景 · CLI agent 入門 |
---
## 💡 如何學習
這份路線圖兼顧概念與實作，目標是帶你**從 LLM 使用者一路走到 agent 系統建構者**。適合**有基本 Python 能力**的開發者、研究生、自學者。動手之前，先確認你有：
- **基本 Python** — 寫過 function、用過 API、看得懂 JSON
- **基本 git** — clone、commit、push
- **想學的動機** — agent 是 2024-2026 變化最快的領域，需要持續投入（2026 仍每月推新 model / 新 framework）
上面有缺的就從 Stage 0 補齊；都會了就**直接跳 Stage 1**。
主幹分 5 部分：
- **Part 1（Stage 0-2）：基礎與 LLM 入門** — Python / git / API、什麼是 LLM、怎麼設計 prompt
- **Part 2（Stage 3-4）：建構你的 Agent** — 從 tool use 進化到 agent，學主流 framework
- **Part 3（Stage 5） 共用 hub** — Claude Code 生態系（MCP / Skills / Plugins / Subagents、Track A + B 都會用到）
- **Part 4（Stage 6-7）：進階整合** — memory / RAG / multi-agent 協作 / harness engineering
- **Part 5（Stage 8） 共用 hub** — Agent Interfaces（Computer Use / Browser Use / Code Sandbox、2024-2026 frontier、Track A + B 都會用到）
> 🔭 **三層概念進化**：**prompt engineering**（Stage 2、單一 prompt 怎麼寫）→ **context engineering**（Stage 3 之後、怎麼動態組 system prompt + memory + retrieved chunks + tool schema）→ **harness engineering**（Stage 7、agent loop / eval / observability / deploy 整套包成 production system）。3 個術語對應 3 個 phase、不必另外找資源。詳見 [`stages/02-prompt-engineering.md#-進階context-engineering不是-prompt-engineering-了`](stages/02-prompt-engineering.md) 跟 [`stages/07-multi-agent-production.md`](stages/07-multi-agent-production.md) 必修閱讀 5+6。
走完主幹（14-19 週）後，依你的身分（研究員 / 開發者 / 老師 / 知識工作者 / 日常使用者）挑一條延伸路線繼續走。
最重要的一句話：**不要跳過 動手練習**。每個 stage 的 動手練習都是「不動手就學不會」的東西，光讀過去後面會卡住。
> 🎓 **動手練習怎麼用才對**：每個練習 folder 裡的 `starter.py` 是**完整解答**、不是 TODO skeleton。如果你 clone 下來直接 `cat starter.py` + `python test.py` pass、會誤以為「我學會了」、其實沒寫一行 code。**正確學習法**：`mv starter.py starter_reference.py`、看 signature 不看 body、自己重寫、卡住才回去對照。完整方法論 + 每個 stage 的時間預算 + 卡住處理流程看 [`docs/HOW_TO_USE.md`](docs/HOW_TO_USE.md)。
準備好了嗎？[從 Stage 0 開始](stages/00-foundations.md)。
---
## 📚 相關資源
完整的相關資源（用語說明 + 常用 MCP / Skill highlight + awesome lists + 中文社群）抽到 **[RESOURCES.md](RESOURCES.md)** 避免主頁過長。
直接看常用入口、依**情境**分組：
### 🚀 入門 / 環境設定
| 你的狀況 | 去哪 | 內容 |
|---|---|---|
| 完全沒寫過 code、第一次接觸 AI agent | [`resources/setup-guide.md`](resources/setup-guide.md) | 30-45 分鐘從零裝好（API key、Python、第一個 hello-world） |
| 不知道挑哪個 LLM provider | [`resources/setup-guide.md` A](resources/setup-guide.md#a--申請第一個-api-key約-10-分鐘) | Anthropic / OpenAI / DeepSeek / Kimi / NVIDIA NIM 對照 |
| 同主題 awesome list / 中文社群 | [`RESOURCES.md` 同主題清單](RESOURCES.md#同主題的清單型-awesome-lists) | 5-10 分鐘逛一輪 |
### 📖 概念 / 用語
| 你的狀況 | 去哪 | 內容 |
|---|---|---|
| 不懂某個詞（LLM / agent / RAG / token / MCP / Skill / 向量資料庫…） | [`resources/glossary.md`](resources/glossary.md) | 30+ 詞、每個 30-80 字 + 哪 stage 講細的 |
| 想搞懂 agent 為什麼有的在 terminal、有的在 Telegram、有的在 Jetson | [`resources/agent-paradigms.md`](resources/agent-paradigms.md) | 5 種 agent 型態 mental model + Hermes / OpenClaw 例子 |
| MCP / Skills / Plugins 用語對照 | [`RESOURCES.md` 三個核心用語](RESOURCES.md#三個核心用語mcp--skills--plugins) | 1 頁速查表 |
| 想找帶證書的線上 AI agent 課（英文 + 中文） | [`resources/courses.md`](resources/courses.md) | 10 門 credible、會發證書的課，分 tier；含「完成證書 ≠ 學歷」誠實 caveat |
### 🛠 動手實作
| 你的狀況 | 去哪 | 內容 |
|---|---|---|
| 想動手寫 Skill / MCP server / 接 Word / Zotero / 本機 LLM | [`resources/cookbook.md`](resources/cookbook.md) | 6 個 step-by-step recipe、每個 30-50 分鐘 |
| 想用 subagent 但不知該派誰、怎麼派、派什麼工作 | [`resources/subagent-cookbook.md`](resources/subagent-cookbook.md) | 15 個複製貼上即用的 dispatch recipe |
| 自己寫 subagent / 組合多個 / debug 跑壞的（進階）| [`resources/subagent-advanced.md`](resources/subagent-advanced.md) | description 寫法 4 個 bug + composition 3 pattern + debug 5 切點 |
| 卡在 tool calling（LLM 不呼叫 / schema 寫不好 / ReAct loop 跑不停） | [`examples/stage-5/tool-calling-tutor/`](examples/stage-5/tool-calling-tutor/) | 可裝進 Claude Code 的 skill、4-symptom diagnostic |
| 動手練習怎麼正確使用（主動 vs 被動模式） | [`docs/HOW_TO_USE.md`](docs/HOW_TO_USE.md) | 5-10 分鐘讀完、配合每個 stage 用 |
### 🔌 接日常工具 / 找 MCP server
| 你的狀況 | 去哪 | 規模 |
|---|---|---|
| 接 Notion / Obsidian / Excel / GitHub 等工具 | [`RESOURCES.md` 接日常工具](RESOURCES.md#接日常工具常用-mcp-server--skill) | 7-8 個 highlight |
| 完整 MCP server / Skill 目錄（含星等、分類） | [`resources/mcp-skills-catalog.md`](resources/mcp-skills-catalog.md) | 65+ 條、16 大分類 |
### 🔬 研究 / production 級
| 你的狀況 | 去哪 | 內容 |
|---|---|---|
| 研究 workflow + multi-LLM delegation skill | [`RESOURCES.md` 研究工作流](RESOURCES.md#研究工作流本-repo-維護者出品) | 本 repo 維護者出品的 Claude Code 研究 skill 對 |
| CLI agent 7 家對照 + production 搭配 | [`resources/cli-agents-guide.md`](resources/cli-agents-guide.md) | Track A 的核心參考、148 行 |
| Schema 設計規則（tool calling 必看） | [`resources/schema-design-cheatsheet.md`](resources/schema-design-cheatsheet.md) | 5 條黃金規則 + 5 個 anti-pattern |
---
## 🤝 如何貢獻
這個 repo 是一個 AI 學習文件，如果你也有蒐集很好的資源，也歡迎貢獻：
- 🐛 **回報 Bug** — 內容錯誤、連結失效、過時資訊 → 開 Issue
- 💡 **提建議** — 缺什麼 stage、該加哪個 project → 開 Issue 討論
- 📝 **完善內容** — 改進現有 stage 內容、修 typo → 直接 PR
- ✍️ **新增 project** — 在某個 stage 加 1-3 個 project，並附上「為什麼這個 project 適合放這個 stage」的說明
- 🌏 **翻譯** — 補英文 companion 沒翻到的段落，或翻成其他語言
- 🌱 **擔任 Stage / Branch maintainer** — 長期 review 特定領域，詳見 [CONTRIBUTORS.md](CONTRIBUTORS.md)
PR 流程跟 style 規範請看 [CONTRIBUTING.md](CONTRIBUTING.md) 跟 [resources/style-guide.md](resources/style-guide.md)。
> 📅 **想看最近 ship 了什麼** → [`CHANGELOG.md`](CHANGELOG.md)（最近 14 天）。
> Maintainer 內部進度與 launch checklist 放在 [`.github/launch-checklist.md`](.github/launch-checklist.md)（內部文件）。
---
## 💬 顧問 / 聯絡
公開學習版（MIT），歡迎自由取用。
目前以顧問為主：團隊或公司若需 **prompt review / audit** 或 **AI agent workflow 諮詢**，歡迎來信（博士生、時間有限）：📧 [wenyuchiou12@gmail.com](mailto:wenyuchiou12@gmail.com)
---
## 🙏 致謝
### Inspiration
- [**Datawhale Hello-Agents**](https://github.com/datawhalechina/hello-agents) — 中文圈最完整的 chapter-length agent 教材，本 repo 的「章節 + 進度」結構受這份啟發；每個 stage / 練習 folder 都有 📚 callout 點過去深度章節。特別感謝。
- [**Datawhale 社群**](https://github.com/datawhalechina) — 中文 ML 共學社群的標竿，本 repo 多個 anchor project 來自這裡
- [**liyupi/ai-guide**](https://github.com/liyupi/ai-guide) — 中文圈最大「AI 資源大全」，跟 Vibe Coding 教學齊全（涵蓋 Agent Skills / RAG / MCP / A2A / Harness Engineering）。本 repo 是「結構化路線」、ai-guide 是「廣度資源庫」，互為補充
### 其他相關專案
同主題、不同切入角度的清單，搜資源時可以一起用：
- [`wong2/awesome-mcp-servers`](https://github.com/wong2/awesome-mcp-servers) — MCP server 清單，按分類整理
- [`punkpeye/awesome-mcp-servers`](https://github.com/punkpeye/awesome-mcp-servers) — 另一份 MCP server 清單
- [`hesreallyhim/awesome-claude-code`](https://github.com/hesreallyhim/awesome-claude-code) — Claude Code 相關工具與 plugin 清單
這些是純清單形式（看到再挑），本 repo 的不同點是有「**從 Stage 0 一路走到 production 的學習順序**」。
### 貢獻者
[![Contributors](https://contrib.rocks/image?repo=WenyuChiou/awesome-agentic-ai-zh)](https://github.com/WenyuChiou/awesome-agentic-ai-zh/graphs/contributors)
新貢獻者會自動出現在上方。完整列表 → [GitHub Contributors](https://github.com/WenyuChiou/awesome-agentic-ai-zh/graphs/contributors)。
### 個人
- [@WenyuChiou](https://github.com/WenyuChiou) — Maintainer
---
## 🎓 引用
如果這個學習地圖對你的學習或工作有幫助，歡迎引用：
```bibtex
@misc{awesome_agentic_ai_zh_2026,
title = {awesome-agentic-ai-zh: A Structured Learning Roadmap for Agentic AI},
author = {Chiou, Wenyu},
year = {2026},
url = {https://github.com/WenyuChiou/awesome-agentic-ai-zh},
note = {8-stage learning path from prerequisites to Agent Interfaces (Computer Use / Browser Use / Sandbox), with curated projects + hello-X demos. Bilingual (zh-TW / English).}
}
```
---
## ☕ 支持這個專案
這份學習地圖是免費、開源（MIT）。如果它對你有幫助，除了給個 ⭐ Star，也歡迎請作者喝杯咖啡、支持它持續更新：
<a href="https://www.buymeacoffee.com/wenyuchiou" target="_blank" rel="noopener noreferrer"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="44"></a>
或直接點 repo 右上角的 **❤ Sponsor** 按鈕。（GitHub Sponsors 審核中，通過後會一併加上。）
---
## License
MIT。Maintained by [@WenyuChiou](https://github.com/WenyuChiou)。
<div align="center">
<p>⭐ 如果這個 repo 對你有幫助，歡迎給個 Star — 這對作者繼續更新是很大的鼓勵</p>
</div>
README.wehub.md
+7
View File
@@ -0,0 +1,7 @@
# WeHub 来源说明
- 原始项目：`WenyuChiou/awesome-agentic-ai-zh`
- 原始仓库：https://github.com/WenyuChiou/awesome-agentic-ai-zh
- 导入方式：上游默认分支的最新快照
- 原作者、版权和许可证信息以原始仓库及本仓库 LICENSE 为准
- 本文件仅用于记录来源，不代表 WeHub 是原项目作者
README.zh-Hans.md
+358
View File
@@ -0,0 +1,358 @@
<div align="right">
<a href="./README.md">繁體中文</a> | <strong>简体中文</strong> | <a href="./README.en.md">English</a>
</div>
<div align="center" markdown="1">
![AI Agent 学习路径](resources/diagrams/banner.zh-Hans.png)
# awesome-agentic-ai-zh
### 🤖 AI Agent 学习地图 — 从基础 LLM 概念到自己构建多 agent 系统
<p><em><b>学习路线图 + 240+ 资源 curation + 简单 illustrative 案例</b><br/>结构化 8 阶段、从“LLM 是什么、token 怎么算”走到 multi-agent 编排、Computer Use / Browser Use / Sandbox</em></p>
[![License](https://img.shields.io/badge/license-MIT-blue?style=flat)](LICENSE)
[![繁中](https://img.shields.io/badge/語言-繁體中文-red?style=flat)](README.md)
[![简中](https://img.shields.io/badge/語言-简体中文-orange?style=flat)](README.zh-Hans.md)
[![EN](https://img.shields.io/badge/lang-English-blue?style=flat)](README.en.md)
![GitHub stars](https://img.shields.io/github/stars/WenyuChiou/awesome-agentic-ai-zh?style=flat&logo=github)
![GitHub forks](https://img.shields.io/github/forks/WenyuChiou/awesome-agentic-ai-zh?style=flat&logo=github)
[![在线文档站](https://img.shields.io/badge/在线文档站-Pages-2ea44f?style=flat)](https://wenyuchiou.github.io/awesome-agentic-ai-zh/)
</div>
---
## 🎯 项目介绍
**本 repo 角色定位**：**学习路线图 + 240+ 资源 curation + 简单 illustrative 案例**——三件事为核心、帮想学 AI / AI agent 的人从“不知道从哪开始”走到“能设计多 agent 系统”。
具体做法：
| 核心 | 做什么 | 规模 |
|---|---|---|
| **学习路线图** | 把网上散落的高质量项目、教材、必修阅读，按**从零开始、循序渐进**整理成 **8 个阶段**（含 Stage 5 + Stage 8 两个共用 hub）+ 2 条学习路线 + 5 条延伸路径 | 8 stages、2 tracks |
| **资源 curation** | 每阶段精选 **240+** 个 project（含星等、适合谁、教什么、怎么跑），加上中文 AI 生态(DeepSeek / Zhipu / Kimi 等)MCP / Skill 完整 catalog | 240+ projects、65 MCP/Skill |
| **简单 illustrative 案例** | 每阶段附 1-5 个**基础练习**（70-150 行 starter + dual-path Ollama/Anthropic SDK 对照 + mock-based test） | 23 个练习 folder |
走完这条路线，你会从“**LLM 用户**”进阶到“**agent 系统构建者**”——能看懂 framework 在做什么、能设计多 agent 协作、能写自己的 MCP server。
---
## 📚 快速开始
### 🚀 第一次接触 AI agent / 没写过 code？
先看 **[`resources/setup-guide.zh-Hans.md`](resources/setup-guide.zh-Hans.md)** — 30-45 分钟从零带你申请 API key、装好 Python、跑出第一个 LLM hello-world。
### 在线阅读
- **[学习地图（两条学习路径）](#️-学习地图两条学习路径)** — 看完这节决定走 Track A 还 Track B
- **[Stage 0 基础准备](stages/00-foundations.zh-Hans.md)** — 已经会 Python / git / API 的人可以直接跳 Stage 1
### 本地下载
```bash
git clone https://github.com/WenyuChiou/awesome-agentic-ai-zh.git
cd awesome-agentic-ai-zh
# 从 stages/00-foundations.zh-Hans.md 开始
```
### ✨ 你会收获什么？
- 📖 **完全免费** — MIT 授权，所有内容开放共学
- 🗺️ **两条学习路径** — Track A（CLI Power User）给“想 USE 现成 CLI agent”的人；Track B（Agent Builder）给“想 BUILD 自己 agent”的人。共用 Stage 0-2 基础
- 🛠️ **基础动手练习** — 每阶段附 1-5 个 illustrative 练习（题目 + dual-path SDK 对照 + success criteria）。定位是**基础入门 + 路线确认**——chapter-length 深度练习见对应 stage 的 hello-agents / Anthropic Cookbook callout
- 🎯 **精选 240+ 个 projects** — 每个都附星等推荐、适合谁、教什么、怎么跑（含本地 LLM 执行：Ollama、llama.cpp、LocalAI、MLX）
- 🌏 **三语完整维护** — 繁中(canonical)/ 简中 / English,三版皆完整维护、英文非薄翻译
- 🎓 **不只“框架”、还有“Claude Code 生态”** — MCP / Skills / Plugins 完整堆叠
- 🔬 **5 条依用户分流的延伸路线** — 研究员 / 开发者 / 老师 / 知识工作者 / 日常用户
- ⏱️ **预估时程写清楚** — Track A 8-10 周 / Track B 主干最少 16-22 周、现实 5-7 个月（每周 5-8 hr）
---
## 🗺️ 学习地图（两条学习路径）
![AI Agent 学习地图](resources/diagrams/learning-map.zh-Hans.png)
走完 **Stage 0-2（共用基础）** 之后，依你的目的选一条学习路径：
- **Track A — CLI Power User**：你想**用**现成的 CLI agent（Claude Code、Codex、OpenCode、Gemini CLI 等）把工作做顺、效率拉高，不打算自己从零写 agent。3 个 sub-stage（A1-A3）。
- **Track B — Agent Builder**: 你想**从零构建**自己的 agent——学 framework、写 ReAct、设计 multi-agent。Stage 3-8 是主路线。
两条学习路径**不互斥**——多数人是先走 A 把 CLI 用起来，再回到 B 学内部运作；或反过来也行。Stage 5（Claude Code 生态）两条路径都会用到。
### 共用基础（Stage 0-2）
| Stage | 主题 | 关键内容 | 预估时程 |
|---|---|---|---|
| **0** | [基础准备（Foundations）](stages/00-foundations.zh-Hans.md) | Python · CLI · git · API · JSON | 1-2 周 |
| **1** | [LLM 基础（LLM Basics）](stages/01-llm-basics.zh-Hans.md) | token · API · 各家 LLM 比较 · 本地 LLM | 1 周 |
| **2** | [Prompt 设计（Prompt Engineering）](stages/02-prompt-engineering.zh-Hans.md) | 系统 prompt · few-shot · CoT | 1-2 周 |
### Track A — CLI Power User（想用 CLI 把事情做完）
| Stage | 主题 | 关键内容 | 预估时程 |
|---|---|---|---|
| **A1** | [选一个 CLI Agent，开始用它做事（CLI Agent Intro & Selection）](tracks/cli/A1-cli-intro.zh-Hans.md) | 7 个主流 CLI 比较 · 安装 · 第一次跑 | 1 周 |
| **A2** | [建立可重复使用的 CLI 工作流程（CLI Workflow Patterns）](tracks/cli/A2-cli-workflow.zh-Hans.md) | CLAUDE.md · slash command · 多步骤拆解 | 1-2 周 |
| **A3** | [把 CLI Agent 接进真实工作流程（Integration & Production）](tracks/cli/A3-cli-production.zh-Hans.md) | MCP 接 CLI · CI 自动化 · cost / observability | 1-2 周 |
| **+5** | [Stage 5 — Claude Code 生态系（Claude Code Ecosystem）](stages/05-claude-code-ecosystem.zh-Hans.md)（**共用 hub**）| MCP · Skills · Plugins · Subagents、Track A 必看 5.1-5.4 / 选读 5.5-5.7 | 1-2 周（Track A 视角）|
| **+8** | [Stage 8 — Agent 操作介面（Agent Interfaces）](stages/08-agent-interfaces.zh-Hans.md)（**共用 hub**）| Computer Use · Browser Use · Code Sandbox、Track A 视角看 Track A 怎么用 | 1-2 周（Track A 视角）|
> **Track A 预估总时程**：含 Stage 0-2（共用基础）+ A1-A3 + **Stage 5 + Stage 8（两个共用 hub）= 约 8-10 周**。核心参考：[`resources/cli-agents-guide.zh-Hans.md`](resources/cli-agents-guide.zh-Hans.md)。
### Track B — Agent Builder（想从零构建 agent）
| Stage | 主题 | 关键内容 | 预估时程 |
|---|---|---|---|
| **3** ⭐ | [工具使用与第一个 Agent（Tool Use & Hello Agent）](stages/03-tool-use-and-hello-agent.zh-Hans.md) | function calling · ReAct · 5 个动手练习 | 2-3 周 |
| **4** | [Agent 框架（Agent Frameworks）](stages/04-agent-frameworks.zh-Hans.md) | LangGraph · AutoGen · CrewAI · Smolagents | 2-3 周 |
| **5** ⭐⭐ | [Claude Code 生态系（Claude Code Ecosystem）](stages/05-claude-code-ecosystem.zh-Hans.md)（**共用 hub**、Track A 也学）| MCP · Skills · Plugins · Subagents | 3-4 周（Track B 视角）|
| **6** | [上下文管理（Context Engineering）：RAG 与 Memory](stages/06-memory-rag.zh-Hans.md) | vector DB · long-term memory · contextual retrieval | 2 周 |
| **7** | [多 Agent 系统与稳定运作（Multi-Agent & Production）](stages/07-multi-agent-production.zh-Hans.md) | multi-agent orchestration · eval · observability · SDK 进阶 | 2-4 周 |
| **7.5** | [进阶 Agentic Workflow 概念（Advanced Agentic Concepts）](stages/07.5-advanced-agentic-concepts.zh-Hans.md)（reading map）| 工作边界 · PAR loop · agent-as-judge · 12 个进阶概念 + reading list | 1 周（不写 code）|
| **8** ⭐⭐ | [Agent 操作介面（Agent Interfaces）](stages/08-agent-interfaces.zh-Hans.md)（**共用 hub**、Track A 也学）| Computer Use · Browser Use · Code Sandbox、2024-2026 frontier | 2-3 周（Track B 视角）|
> **Track B 预估总时程**：主干最少 **16-22 周**、现实 **5-7 个月**（每周 5-8 hr 兼职）
> **两个共用 hub（Track A + Track B 都会用到）**：
> - **Stage 5** = Claude Code 生态（MCP / Skills / Plugins / Subagents）—— Track A 学 MCP 接 CLI、Track B 学 agent runtime 结构
> - **Stage 8** = Agent Interfaces（Computer Use / Browser / Sandbox、2024-2026 frontier）—— Track A 学“**怎么用**”委派任务、Track B 学“**怎么 build**”embed 进 agent
> 💡 **想看跨 stage 的完整示例？** [7 步构建你的第一个 AI Agent](walkthroughs/build-first-agent-in-7-steps.zh-Hans.md) — 同一个 Paper Summary Bot 从 Stage 1 一路写到 Stage 7，~350 行真实代码（**Track B 适用**）
走完主干（Track B 16-22 周 / Track A 8-10 周）后，依你的身份挑一条延伸路线继续走。**不确定挑哪条？**
![Branch 决策树](resources/diagrams/branch-decision-tree.zh-Hans.png)
> 💡 **“日常用户”这条路线不必走完主干就能直接读**——是给“想用 AI、但不一定要写 code”的人。
| 路线 | 适合谁 | 主题 |
|---|---|---|
| 🔬 [研究员](branches/for-researcher.zh-Hans.md) | 研究生、博后、PI | 文献整理 · paper 写作 · multi-agent review |
| 💻 [开发者](branches/for-developer.zh-Hans.md) | 软件工程师 | Cursor · Aider · CLI delegation · code review |
| 🎓 [老师](branches/for-teacher.zh-Hans.md) | 老师、讲师 | 备课 · 幻灯片 · 学生 feedback · 隐私 / 伦理 · prompt 范本 |
| 📊 [知识工作者](branches/for-knowledge-worker.zh-Hans.md) | 顾问、PM、分析师 | Email · 会议记录 · report 自动化 |
| 👥 [日常用户](branches/for-everyday-users.zh-Hans.md) | ChatGPT / Claude.ai 用户 | 写信 · 学习 · 隐私场景 · CLI agent 入门 |
---
## 💡 如何学习
这份路线图兼顾概念与实作，目标是带你“从 LLM 用户一路走到 agent 系统构建者”。适合“有基本 Python 能力”的开发者、研究生、自学者。动手之前，先确认你有：
- 基本 Python — 写过 function、用过 API、看得懂 JSON
- 基本 git — clone、commit、push
- 想学的动机 — agent 是 2025 年之后变化最快的领域，需要持续投入
上面有缺的就从 Stage 0 补齐；都会了就直接跳 Stage 1。
主干分 5 部分：
- **Part 1（Stage 0-2）：基础与 LLM 入门** — Python / git / API、什么是 LLM、怎么设计 prompt
- **Part 2（Stage 3-4）：构建你的 Agent** — 从 tool use 进化到 agent，学主流 framework
- **Part 3（Stage 5） 共用 hub** — Claude Code 生态系（MCP / Skills / Plugins / Subagents、Track A + B 都会用到）
- **Part 4（Stage 6-7）：进阶集成** — memory / RAG / multi-agent 协作 / harness engineering
- **Part 5（Stage 8） 共用 hub** — Agent Interfaces（Computer Use / Browser Use / Code Sandbox、2024-2026 frontier、两条 track 都会用到）
> 🔭 **三层概念进化**：**prompt engineering**（Stage 2、单一 prompt 怎么写）→ **context engineering**（Stage 3 之后、怎么动态组 system prompt + memory + retrieved chunks + tool schema）→ **harness engineering**（Stage 7、agent loop / eval / observability / deploy 整套包成 production system）。3 个术语对应 3 个 phase、不必另外找资源。详见 [`stages/02-prompt-engineering.zh-Hans.md`](stages/02-prompt-engineering.zh-Hans.md) 进阶：context engineering 跟 [`stages/07-multi-agent-production.zh-Hans.md`](stages/07-multi-agent-production.zh-Hans.md) 必修阅读 5+6。
走完主干（Track B 16-22 周 / Track A 8-10 周）后，依你的身份挑一条延伸路线继续走。
最重要的说一句话：**不要跳过 動手練習**。每个 stage 的 動手練習都是“不动手就学不会”的东西，光读过去后面会卡住。
> 🎓 **动手练习怎么用才对**：每个练习 folder 里的 `starter.py` 是**完整解答**、不是 TODO skeleton。如果你 clone 下来直接 `cat starter.py` + `python test.py` pass、会误以为“我学会了”、其实没写一行 code。**正确学习法**：`mv starter.py starter_reference.py`、看 signature 不看 body、自己重写、卡住才回去对照。完整方法论 + 每个 stage 的时间预算 + 卡住处理流程看 [`docs/HOW_TO_USE.md`](docs/HOW_TO_USE.md)。
准备好了吗？[从 Stage 0 开始](stages/00-foundations.zh-Hans.md)。
---
## 📚 相关资源
常用入口、依**情境**分组：
### 🚀 入门 / 环境设定
| 你的状况 | 去哪 | 内容 |
|---|---|---|
| 完全没写过 code、第一次接触 AI agent | [`resources/setup-guide.zh-Hans.md`](resources/setup-guide.zh-Hans.md) | 30-45 分钟从零装好（API key、Python、第一个 hello-world） |
| 不知道挑哪个 LLM provider | [`resources/setup-guide.zh-Hans.md` A](resources/setup-guide.zh-Hans.md#a--申请第一个-api-key约-10-分钟) | Anthropic / OpenAI / DeepSeek / Kimi / NVIDIA NIM 对照 |
### 📖 概念 / 用语
| 你的状况 | 去哪 | 内容 |
|---|---|---|
| 不懂某个词（LLM / agent / RAG / token / MCP / Skill / 向量数据库…） | [`resources/glossary.zh-Hans.md`](resources/glossary.zh-Hans.md) | 30+ 词、每个 30-80 字 + 哪 stage 讲细的 |
| 想搞懂 agent 为什么有的在 terminal、有的在 Telegram、有的在 Jetson | [`resources/agent-paradigms.zh-Hans.md`](resources/agent-paradigms.zh-Hans.md) | 5 种 agent 型态 mental model + Hermes / OpenClaw 例子 |
| MCP / Skills / Plugins 用语对照 | [`RESOURCES.zh-Hans.md` 三个核心用语](RESOURCES.zh-Hans.md#三个核心用语mcp--skills--plugins) | 1 页速查表 |
| 想找带证书的线上 AI agent 课（英文 + 中文） | [`resources/courses.zh-Hans.md`](resources/courses.zh-Hans.md) | 10 门 credible、会发证书的课，分 tier；并诚实标注完成证书不是学历 |
### 🛠 动手实作
| 你的状况 | 去哪 | 内容 |
|---|---|---|
| 想动手写 Skill / MCP server / 接 Word / Zotero / 本机 LLM | [`resources/cookbook.zh-Hans.md`](resources/cookbook.zh-Hans.md) | 6 个 step-by-step recipe、每个 30-50 分钟 |
| 想用 subagent 但不知道该派谁、怎么派、派什么工作 | [`resources/subagent-cookbook.zh-Hans.md`](resources/subagent-cookbook.zh-Hans.md) | 15 个复制粘贴即用的 dispatch recipe |
| 卡在 tool calling（LLM 不调用 / schema 写不好 / ReAct loop 跑不停） | [`examples/stage-5/tool-calling-tutor/`](examples/stage-5/tool-calling-tutor/) | 可装进 Claude Code 的 skill、4-symptom diagnostic |
| 动手练习怎么正确使用（主动 vs 被动模式） | [`docs/HOW_TO_USE.md`](docs/HOW_TO_USE.md) | 5-10 分钟读完、配合每个 stage 用 |
### 三个核心用语：MCP / Skills / Plugins
README 跟各 stage 会频繁提到这三个 Claude Code 生态的关键词，先快速说明：
- **MCP（Model Context Protocol）** — Anthropic 推的开放协议，让任何 LLM host（Claude Code、其他 IDE、自写 agent）都能用同一套接口去调用外部 tool server（文件、DB、API、自家服务）。把它想成“LLM 的 USB 接口”。详见 [Stage 5.2](stages/05-claude-code-ecosystem.zh-Hans.md#52--mcpmodel-context-protocol-基础)。
- **Skills** — Claude Code 的“行为包”。一个 Skill 就是一份 `SKILL.md`，描述“在什么情境要做什么、可以调用哪些 MCP tool”。写好之后 Claude Code 会自动 discover。详见 [Stage 5.3](stages/05-claude-code-ecosystem.zh-Hans.md#53--skillsclaude-code-的行为层-claude-code-生态最关键的一层)。
- **Plugins / Marketplaces** — 把 Skills、slash commands、hooks、MCP 设置打包成一个发布单位给 team 或社群安装。Marketplace 就是 plugin 的 catalog。详见 [Stage 5.4](stages/05-claude-code-ecosystem.zh-Hans.md#54--plugins-与-marketplaces)。
对, 应的 動手練習 练习都在 [Stage 5](stages/05-claude-code-ecosystem.zh-Hans.md)，Track A 的 [A3](tracks/cli/A3-cli-production.zh-Hans.md) 也会用到。
### 接日常工具：常用 MCP server / Skill
把 Claude Code（或其他 CLI agent）接到你已经在用的 app，省掉手动切换的成本。下面几个是社群 / 官方比较成熟的：
**笔记 / 知识库**
- [**MarkusPfundstein/mcp-obsidian**](https://github.com/MarkusPfundstein/mcp-obsidian) ★ 3.9k+ — 通过 Obsidian REST API plugin 让 LLM 读写你的 Obsidian vault
- [**makenotion/notion-mcp-server**](https://github.com/makenotion/notion-mcp-server) ★ 4.4k+ — Notion **官方** MCP server，可查询／创建 page、database
- [**PleasePrompto/notebooklm-skill**](https://github.com/PleasePrompto/notebooklm-skill) ★ 7.3k+ — NotebookLM Skill（浏览器自动化），用 Claude Code 直接查你 NotebookLM 里的文件，回答带 citation
- [**teng-lin/notebooklm-py**](https://github.com/teng-lin/notebooklm-py) ★ 16k+ — 非官方 NotebookLM Python API + CLI，支持 Claude Code / Codex 等 agent 集成
**办公文件（Word / Excel / PowerPoint / PDF）**
- [**anthropics/skills**](https://github.com/anthropics/skills) ★ 158k+ — Anthropic **官方** Skills 集合，docx / xlsx / pptx / pdf 处理直接内置
- [**tfriedel/claude-office-skills**](https://github.com/tfriedel/claude-office-skills) ★ 725 — 增强版 Office skills（PPTX/DOCX/XLSX/PDF），含自动化 workflow
**Google Workspace（Gmail / Docs / Drive / Calendar）**
- [**taylorwilsdon/google_workspace_mcp**](https://github.com/taylorwilsdon/google_workspace_mcp) ★ 2.6k+ — 一个 server 包整套 Google Workspace（Gmail、Calendar、Docs、Sheets、Slides、Drive）
**开发协作**
- [**github/github-mcp-server**](https://github.com/github/github-mcp-server) ★ 29k+ — GitHub **官方** MCP，issue / PR / repo 操作
- [**atlassian/atlassian-mcp-server**](https://github.com/atlassian/atlassian-mcp-server) ★ 810 — Atlassian **官方** Remote MCP（Jira、Confluence）
- [**jerhadf/linear-mcp-server**](https://github.com/jerhadf/linear-mcp-server) ★ 340+ — Linear MCP server
- [**korotovsky/slack-mcp-server**](https://github.com/korotovsky/slack-mcp-server) ★ 1.7k+ — Slack MCP，无 admin 权限也能用
**中文圈常用**
- [**leemysw/feishu-docx**](https://github.com/leemysw/feishu-docx) ★ 235 — 飞书（Lark）docs / sheet / bitable ↔ Markdown，含 Claude Skills 支持
> 上面只是 highlight。**完整 65+ 个集成**（含数据库、浏览器自动化、Figma、Excalidraw、Cloudflare、Stripe…）：[`resources/mcp-skills-catalog.zh-Hans.md`](resources/mcp-skills-catalog.zh-Hans.md)。
> 想找更多 MCP server catalog？看 [`wong2/awesome-mcp-servers`](https://github.com/wong2/awesome-mcp-servers) / [`punkpeye/awesome-mcp-servers`](https://github.com/punkpeye/awesome-mcp-servers)（按分类整理）。**Canva** 的官方 MCP 还在 early access，社群版本不稳定，等成熟后再补上。
### 同主题的清单型 awesome lists
这个 repo **不取代**清单型 awesome list — 你已经知道在找什么工具时，下面这些查起来更直接：
**MCP 相关**
- [**modelcontextprotocol/servers**](https://github.com/modelcontextprotocol/servers) — 官方 MCP reference servers（filesystem、github、sqlite、git、fetch、memory 等）
- [**wong2/awesome-mcp-servers**](https://github.com/wong2/awesome-mcp-servers) — 社群 MCP server 清单，按分类整理（150+ 个）
- [**punkpeye/awesome-mcp-servers**](https://github.com/punkpeye/awesome-mcp-servers) — 另一份 MCP server 清单
**Claude Code / Skills / Plugins 相关**
- [**hesreallyhim/awesome-claude-code**](https://github.com/hesreallyhim/awesome-claude-code) — Claude Code 相关工具与 plugin 清单（整理中）
- [**travisvn/awesome-claude-skills**](https://github.com/travisvn/awesome-claude-skills) — Claude Skills 清单
- [**anthropics/claude-plugins-official**](https://github.com/anthropics/claude-plugins-official) — Anthropic 官方 plugin 模板，要打包自己的 plugin 从这份开始
**中文圈常用**
- [**datawhalechina/hello-agents**](https://github.com/datawhalechina/hello-agents) — Datawhale 系统性 agent 教学（zh-Hans）
- [**WangRongsheng/awesome-LLM-resources**](https://github.com/WangRongsheng/awesome-LLM-resources) — 完整的中文 LLM 资源整理（8k+ stars）
- [**AiHubCN/Awesome-Chinese-LLM**](https://github.com/AiHubCN/Awesome-Chinese-LLM) — 中文开源大模型整理
---
## 🤝 如何贡献
这个 repo 是一个 AI 学习文档，如果你也有收集很好的资源，也欢迎贡献：
- 🐛 **汇报 Bug** — 内容错误、链接失效、过时信息 → 开 Issue
- 💡 **提建议** — 缺什么 stage、该加哪个 project → 开 Issue 讨论
- 📝 **完善内容** — 改进现有 stage 内容、修 typo → 直接 PR
- ✍️ **新增 project** — 在某个 stage 加 1-3 个 project，并附上“为什么这个 project 适合放这个 stage”的说明
- 🌏 **翻译** — 补英文 companion 没翻到的段落，或翻成其他语言
- 🌱 **担任 Stage / Branch maintainer** — 长期 review 特定领域，详见 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [resources/style-guide.zh-Hans.md](resources/style-guide.zh-Hans.md)。
PR 流程跟 style 规范请看 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [resources/style-guide.zh-Hans.md](resources/style-guide.zh-Hans.md)。
> 📅 **想看最近 ship 了什么** → [`CHANGELOG.md`](CHANGELOG.md)（最近 14 天）。
> Maintainer 内部进度与 launch checklist 放在 [.github/launch-checklist.md](.github/launch-checklist.md)（内部文件）。
---
## 💬 顾问 / 联系
公开学习版（MIT），欢迎自由取用。
目前以顾问为主：团队或公司若需 **prompt review / audit** 或 **AI agent workflow 咨询**，欢迎来信（博士生、时间有限）：📧 [wenyuchiou12@gmail.com](mailto:wenyuchiou12@gmail.com)
---
## 🙏 致谢
### Inspiration
- [**Datawhale Hello-Agents**](https://github.com/datawhalechina/hello-agents) — 中文圈最完整的 chapter-length agent 教材，本 repo 的“章节 + 进度”结构受这份启发；每个 stage / 练习 folder 都有 📚 callout 点过去深度章节。特别感谢。
- [**Datawhale 社群**](https://github.com/datawhalechina) — 中文 ML 共学社群的标杆，本 repo 多个 anchor project 来自这里
- [**liyupi/ai-guide**](https://github.com/liyupi/ai-guide) — 中文圈最大"AI 资源大全" + Vibe Coding 教学（涵盖 Agent Skills / RAG / MCP / A2A / Harness Engineering）。本 repo 是"结构化路线"、ai-guide 是"广度资源库"，互为补充
### 其他相关项目
同主题、不同切入角度的清单，搜资源时可以一起用：
- [`wong2/awesome-mcp-servers`](https://github.com/wong2/awesome-mcp-servers) — MCP server 清单，按分类整理
- [`punkpeye/awesome-mcp-servers`](https://github.com/punkpeye/awesome-mcp-servers) — 另一份 MCP server 清单
- [`hesreallyhim/awesome-claude-code`](https://github.com/hesreallyhim/awesome-claude-code) — Claude Code 相关工具与 plugin 清单（整理中）
- [`travisvn/awesome-claude-skills`](https://github.com/travisvn/awesome-claude-skills) — Claude Skills 清单
- [`anthropics/claude-plugins-official`](https://github.com/anthropics/claude-plugins-official) — Anthropic 官方 plugin 模板，要打包自己的 plugin 从这份开始
这些是纯清单形式（看到再挑），本 repo 的不同点是有“从 Stage 0 一路走到 production 的学习顺序”。
### 贡献者
[![Contributors](https://contrib.rocks/image?repo=WenyuChiou/awesome-agentic-ai-zh)](https://github.com/WenyuChiou/awesome-agentic-ai-zh/graphs/contributors)
新贡献者会自动出现在上方。完整列表 → [GitHub Contributors](https://github.com/WenyuChiou/awesome-agentic-ai-zh/graphs/contributors)。
### 个人
- [@WenyuChiou](https://github.com/WenyuChiou) — Maintainer
---
## 🎓 引用
如果这个学习地图对你的学习或工作有帮助，欢迎引用：
```bibtex
@misc{awesome_agentic_ai_zh_2026,
title = {awesome-agentic-ai-zh: A Structured Learning Roadmap for Agentic AI},
author = {Chiou, Wenyu},
year = {2026},
url = {https://github.com/WenyuChiou/awesome-agentic-ai-zh},
note = {8-stage learning path from prerequisites to Agent Interfaces (Computer Use / Browser Use / Code Sandbox), with curated projects + hello-X demos. Bilingual (zh-TW / English).}
}
```
---
## ☕ 支持这个项目
这份学习地图是免费、开源（MIT）。如果它对你有帮助，除了给个 ⭐ Star，也欢迎请作者喝杯咖啡、支持它持续更新：
<a href="https://www.buymeacoffee.com/wenyuchiou" target="_blank" rel="noopener noreferrer"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="44"></a>
或直接点 repo 右上角的 **❤ Sponsor** 按钮。（GitHub Sponsors 审核中，通过后会一并加上。）
---
## License
MIT。Maintained by [@WenyuChiou](https://github.com/WenyuChiou)。
<div align="center">
<p>⭐ 如果这个 repo 对你有帮助，欢迎给个 Star — 这对作者继续更新是很大的鼓励</p>
</div>
RESOURCES.en.md
+102
View File
@@ -0,0 +1,102 @@
# Related Resources
> [繁體中文](./RESOURCES.md) | [简体中文](./RESOURCES.zh-Hans.md) | **English**
> [← Back to main README](README.en.md)
This file collects: term definitions, daily-tool MCP/Skill highlights, topic-based awesome lists, Chinese-community resources. Pulled out of the main README to keep that page focused.
> 💡 **Don't know a term?** (LLM, agent, RAG, token, vector DB, …) → [`resources/glossary.en.md`](resources/glossary.en.md) — 30+ common terms with 30–80-word definitions
---
## Three core terms: MCP / Skills / Plugins
The README and stages reference these three Claude Code ecosystem terms a lot. Quick definitions:
- **MCP (Model Context Protocol)** — Anthropic's open protocol that lets any LLM host (Claude Code, other IDEs, your own agent) talk to any external tool server (filesystem, DB, API, your service) through one interface. Think "USB for LLMs". See [Stage 5.2](stages/05-claude-code-ecosystem.en.md#52--mcp-model-context-protocol--foundation).
- **Skills** — Claude Code's "behavior bundles". A Skill is a `SKILL.md` describing "in what context, do what, can call which MCP tools". Claude Code auto-discovers them. See [Stage 5.3](stages/05-claude-code-ecosystem.en.md#53--skills-claude-codes-behavior-layer--the-most-critical-layer-of-the-claude-code-ecosystem).
- **Plugins / Marketplaces** — package Skills, slash commands, hooks, and MCP configs into a distribution unit installable by your team or community. A marketplace is a catalog of plugins. See [Stage 5.4](stages/05-claude-code-ecosystem.en.md#54--plugins--marketplaces).
Hands-on exercises live in [Stage 5](stages/05-claude-code-ecosystem.en.md), with Track A's [A3](tracks/cli/A3-cli-production.en.md) covering production integration.
---
## Daily-tool integrations: MCP servers + Skills
Connect Claude Code (or any other CLI agent) to the apps you already use, without window-hopping. Mature picks below:
### Notes / Knowledge Base
- [**MarkusPfundstein/mcp-obsidian**](https://github.com/MarkusPfundstein/mcp-obsidian) ★ 3.9k+ — Obsidian REST API plugin lets the LLM read/write your vault
- [**makenotion/notion-mcp-server**](https://github.com/makenotion/notion-mcp-server) ★ 4.4k+ — Notion **official** MCP, query/create pages, manipulate databases
- [**PleasePrompto/notebooklm-skill**](https://github.com/PleasePrompto/notebooklm-skill) ★ 7.3k+ — NotebookLM Skill, citation-backed answers from your uploaded docs
- [**teng-lin/notebooklm-py**](https://github.com/teng-lin/notebooklm-py) ★ 16k+ — unofficial NotebookLM Python API + CLI, plays well with Claude Code / Codex
### Office Documents (Word / Excel / PowerPoint / PDF)
- [**anthropics/skills**](https://github.com/anthropics/skills) ★ 158k+ — Anthropic **official** Skills with built-in docx / xlsx / pptx / pdf processing
- [**tfriedel/claude-office-skills**](https://github.com/tfriedel/claude-office-skills) ★ 725 — Office skills with automation workflows on top of the official ones
### Google Workspace (Gmail / Docs / Drive / Calendar)
- [**taylorwilsdon/google_workspace_mcp**](https://github.com/taylorwilsdon/google_workspace_mcp) ★ 2.6k+ — full Workspace stack (Gmail, Calendar, Docs, Sheets, Slides, Drive) in one server
### Dev Collaboration
- [**github/github-mcp-server**](https://github.com/github/github-mcp-server) ★ 29k+ — GitHub **official** MCP for issues / PRs / repos
- [**atlassian/atlassian-mcp-server**](https://github.com/atlassian/atlassian-mcp-server) ★ 810 — Atlassian **official** Remote MCP (Jira, Confluence)
- [**jerhadf/linear-mcp-server**](https://github.com/jerhadf/linear-mcp-server) ★ 340+ — Linear MCP
- [**korotovsky/slack-mcp-server**](https://github.com/korotovsky/slack-mcp-server) ★ 1.7k+ — Slack MCP, works without admin permissions
### Research Workflow (by the repo maintainer)
- [**WenyuChiou/ai-research-skills**](https://github.com/WenyuChiou/ai-research-skills) ★ 123 — 14 research-workflow skills as a 5-plugin marketplace
- [**WenyuChiou/research-hub**](https://github.com/WenyuChiou/research-hub) ★ 33 — Zotero + Obsidian + NotebookLM integration workspace
- [**WenyuChiou/zotero-skills**](https://github.com/WenyuChiou/zotero-skills) ★ 28 — Zotero CLI skill
- [**WenyuChiou/codex-delegate**](https://github.com/WenyuChiou/codex-delegate) ★ 57 + [**gemini-delegate-skill**](https://github.com/WenyuChiou/gemini-delegate-skill) ★ 34 — multi-LLM delegation pair
### Chinese-language Ecosystem
- [**leemysw/feishu-docx**](https://github.com/leemysw/feishu-docx) ★ 235 — Feishu (Lark) docs / sheet / bitable ↔ Markdown with Claude Skills support
> The above is just the highlights. **Full 65+ entry catalog by category** (incl. databases, browser automation, Figma, Excalidraw, Cloudflare, Stripe, academic-writing / multi-LLM delegation, etc.) lives in [`resources/mcp-skills-catalog.en.md`](resources/mcp-skills-catalog.en.md).
> Looking for more MCP server catalogs? See [`wong2/awesome-mcp-servers`](https://github.com/wong2/awesome-mcp-servers) / [`punkpeye/awesome-mcp-servers`](https://github.com/punkpeye/awesome-mcp-servers) (categorized). **Canva**'s official MCP is still early access — community versions are unstable; will add when stable.
---
## Topic-based awesome lists
This repo **doesn't replace** flat awesome lists. When you already know which tool you want, these are more direct:
### MCP-related
- [**modelcontextprotocol/servers**](https://github.com/modelcontextprotocol/servers) — official reference servers (filesystem, github, sqlite, git, fetch, memory, …)
- [**wong2/awesome-mcp-servers**](https://github.com/wong2/awesome-mcp-servers) — community MCP server catalog, by category (150+)
- [**punkpeye/awesome-mcp-servers**](https://github.com/punkpeye/awesome-mcp-servers) — another MCP server catalog
### Claude Code / Skills / Plugins-related
- [**hesreallyhim/awesome-claude-code**](https://github.com/hesreallyhim/awesome-claude-code) — Claude Code resources (currently restructuring)
- [**travisvn/awesome-claude-skills**](https://github.com/travisvn/awesome-claude-skills) — Claude Skills catalog
- [**anthropics/claude-plugins-official**](https://github.com/anthropics/claude-plugins-official) — Anthropic's official plugin marketplace template; start here when packaging your own plugin
### Chinese-speaking community
- [**datawhalechina/hello-agents**](https://github.com/datawhalechina/hello-agents) — Datawhale systematic agent tutorial (zh-Hans)
- [**WangRongsheng/awesome-LLM-resources**](https://github.com/WangRongsheng/awesome-LLM-resources) — comprehensive zh-Hans LLM resources (8k+ stars)
- [**AiHubCN/Awesome-Chinese-LLM**](https://github.com/AiHubCN/Awesome-Chinese-LLM) — open-source Chinese LLM catalog
### Online courses / MOOCs (certificate comparison)
- [**resources/courses.en.md**](resources/courses.en.md) — 10 credible, certificate-granting online AI agent courses (EN + ZH), tiered; with an honest "completion certificate ≠ a degree" caveat
---
## What else?
- Main README: [README.en.md](README.en.md)
- Full MCP / Skill catalog: [resources/mcp-skills-catalog.en.md](resources/mcp-skills-catalog.en.md)
- CLI agent comparison guide: [resources/cli-agents-guide.en.md](resources/cli-agents-guide.en.md)
- Style guide / contributing: [resources/style-guide.en.md](resources/style-guide.en.md), [CONTRIBUTING.en.md](CONTRIBUTING.en.md)
RESOURCES.md
+104
View File
@@ -0,0 +1,104 @@
# 相關資源
> **繁體中文** | [简体中文](./RESOURCES.zh-Hans.md) | [English](./RESOURCES.en.md)
> [← 回主路線 README](README.md)
這份檔案集中放：用語說明、常用 MCP / Skill 整合 highlight、同主題 awesome list、中文社群資源。從主 README 抽出來避免主頁過長。
> 💡 **不懂某個詞**（LLM、agent、RAG、token、向量資料庫⋯）→ [`resources/glossary.md`](resources/glossary.md)（用語小辭典，30 多個詞每個 30-80 字解釋）
>
> 🍳 **想動手做但不知怎麼開始**（寫 Skill / 寫 MCP server / 接 Word / 接 NotebookLM / 接 Zotero / 接本機 LLM）→ [`resources/cookbook.md`](resources/cookbook.md)（6 個 step-by-step recipe，每個 30-50 分鐘做完）
---
## 三個核心用語：MCP / Skills / Plugins
主 README 跟各 stage 會頻繁提到這三個 Claude Code 生態的關鍵詞，先快速說明：
- **MCP（Model Context Protocol）** — Anthropic 推的開放協定，讓任何 LLM host（Claude Code、其他 IDE、自寫 agent）都能用同一套介面去呼叫外部 tool server（檔案、DB、API、自家服務）。把它想成「LLM 的 USB 接口」。詳見 [Stage 5.2](stages/05-claude-code-ecosystem.md#52--mcpmodel-context-protocol-基礎)。
- **Skills** — Claude Code 的「行為包」。一個 Skill 就是一份 `SKILL.md`，描述「在什麼情境要做什麼、可以呼叫哪些 MCP tool」。寫好之後 Claude Code 會自動 discover。詳見 [Stage 5.3](stages/05-claude-code-ecosystem.md#53--skillsclaude-code-的行為層-claude-code-生態最關鍵的一層)。
- **Plugins / Marketplaces** — 把 Skills、slash commands、hooks、MCP 設定打包成一個發佈單位給 team 或社群安裝。Marketplace 就是 plugin 的 catalog。詳見 [Stage 5.4](stages/05-claude-code-ecosystem.md#54--plugins-與-marketplaces)。
對應的 動手練習都在 [Stage 5](stages/05-claude-code-ecosystem.md)，Track A 的 [A3](tracks/cli/A3-cli-production.md) 也會用到。
---
## 接日常工具：常用 MCP server / Skill
把 Claude Code（或其他 CLI agent）接到你已經在用的 app，省掉手動切換的成本。下面幾個是社群 / 官方比較成熟的：
### 筆記 / 知識庫
- [**MarkusPfundstein/mcp-obsidian**](https://github.com/MarkusPfundstein/mcp-obsidian) ★ 3.9k+ — 透過 Obsidian REST API plugin 讓 LLM 讀寫你的 Obsidian vault
- [**makenotion/notion-mcp-server**](https://github.com/makenotion/notion-mcp-server) ★ 4.4k+ — Notion **官方** MCP server，可查詢／建立 page、database
- [**PleasePrompto/notebooklm-skill**](https://github.com/PleasePrompto/notebooklm-skill) ★ 7.3k+ — NotebookLM Skill（瀏覽器自動化），用 Claude Code 直接查你 NotebookLM 裡的文件，回答帶 citation
- [**teng-lin/notebooklm-py**](https://github.com/teng-lin/notebooklm-py) ★ 16k+ — 非官方 NotebookLM Python API + CLI，支援 Claude Code / Codex 等 agent 整合
### 辦公文件（Word / Excel / PowerPoint / PDF）
- [**anthropics/skills**](https://github.com/anthropics/skills) ★ 158k+ — Anthropic **官方** Skills 集合，docx / xlsx / pptx / pdf 處理直接內建
- [**tfriedel/claude-office-skills**](https://github.com/tfriedel/claude-office-skills) ★ 725 — 補強版 Office skills（PPTX/DOCX/XLSX/PDF），含自動化 workflow
### Google Workspace（Gmail / Docs / Drive / Calendar）
- [**taylorwilsdon/google_workspace_mcp**](https://github.com/taylorwilsdon/google_workspace_mcp) ★ 2.6k+ — 一個 server 包整套 Google Workspace（Gmail、Calendar、Docs、Sheets、Slides、Drive）
### 開發協作
- [**github/github-mcp-server**](https://github.com/github/github-mcp-server) ★ 29k+ — GitHub **官方** MCP，issue / PR / repo 操作
- [**atlassian/atlassian-mcp-server**](https://github.com/atlassian/atlassian-mcp-server) ★ 810 — Atlassian **官方** Remote MCP（Jira、Confluence）
- [**jerhadf/linear-mcp-server**](https://github.com/jerhadf/linear-mcp-server) ★ 340+ — Linear MCP server
- [**korotovsky/slack-mcp-server**](https://github.com/korotovsky/slack-mcp-server) ★ 1.7k+ — Slack MCP，無 admin 權限也能用
### 研究工作流（本 repo 維護者出品）
- [**WenyuChiou/ai-research-skills**](https://github.com/WenyuChiou/ai-research-skills) ★ 123 — 14 個研究流程 skill，5-plugin marketplace
- [**WenyuChiou/research-hub**](https://github.com/WenyuChiou/research-hub) ★ 33 — Zotero + Obsidian + NotebookLM 整合 workspace
- [**WenyuChiou/zotero-skills**](https://github.com/WenyuChiou/zotero-skills) ★ 28 — Zotero CLI skill
- [**WenyuChiou/codex-delegate**](https://github.com/WenyuChiou/codex-delegate) ★ 57 + [**gemini-delegate-skill**](https://github.com/WenyuChiou/gemini-delegate-skill) ★ 34 — Multi-LLM delegation 對
### 中文圈常用
- [**leemysw/feishu-docx**](https://github.com/leemysw/feishu-docx) ★ 235 — 飛書（Lark）docs / sheet / bitable ↔ Markdown，含 Claude Skills 支援
> 上面只是 highlight。**完整 65+ 個整合的分類目錄**（含資料庫、瀏覽器自動化、Figma、Excalidraw、Cloudflare、Stripe、學術寫作 / Multi-LLM delegation 等）在 [`resources/mcp-skills-catalog.md`](resources/mcp-skills-catalog.md)。
> 想找更多 MCP server catalog？看 [`wong2/awesome-mcp-servers`](https://github.com/wong2/awesome-mcp-servers) / [`punkpeye/awesome-mcp-servers`](https://github.com/punkpeye/awesome-mcp-servers)（依分類整理）。**Canva** 的官方 MCP 還在 early access，社群版本不穩定，等成熟後再補上。
---
## 同主題的清單型 awesome lists
本 repo **不取代**清單型 awesome list——你已經知道在找什麼工具時，下面這些查起來更直接：
### MCP 相關
- [**modelcontextprotocol/servers**](https://github.com/modelcontextprotocol/servers) — 官方 MCP reference servers（filesystem、github、sqlite、git、fetch、memory 等）
- [**wong2/awesome-mcp-servers**](https://github.com/wong2/awesome-mcp-servers) — 社群 MCP server 清單，按分類整理（150+ 個）
- [**punkpeye/awesome-mcp-servers**](https://github.com/punkpeye/awesome-mcp-servers) — 另一份 MCP server 清單
### Claude Code / Skills / Plugins 相關
- [**hesreallyhim/awesome-claude-code**](https://github.com/hesreallyhim/awesome-claude-code) — Claude Code 相關資源清單（整理中）
- [**travisvn/awesome-claude-skills**](https://github.com/travisvn/awesome-claude-skills) — Claude Skills 清單
- [**anthropics/claude-plugins-official**](https://github.com/anthropics/claude-plugins-official) — Anthropic 官方 plugin 範本，要打包自己的 plugin 從這份開始
### 中文社群必看
- [**datawhalechina/hello-agents**](https://github.com/datawhalechina/hello-agents) — Datawhale 系統性 agent 教學（zh-Hans）
- [**WangRongsheng/awesome-LLM-resources**](https://github.com/WangRongsheng/awesome-LLM-resources) — 完整的中文 LLM 資源整理（8k+ stars）
- [**AiHubCN/Awesome-Chinese-LLM**](https://github.com/AiHubCN/Awesome-Chinese-LLM) — 中文開源大模型整理
### 線上課程 / MOOC（帶證書對照）
- [**resources/courses.md**](resources/courses.md) — 10 門 credible、會發證書的線上 AI agent 課（英文 + 中文），分 tier；含「完成證書 ≠ 學歷」的誠實 caveat
---
## 還有什麼？
- 主 README：[README.md](README.md)
- 完整 MCP/Skill 目錄：[resources/mcp-skills-catalog.md](resources/mcp-skills-catalog.md)
- CLI agent 比較指南：[resources/cli-agents-guide.md](resources/cli-agents-guide.md)
- Style guide / 貢獻規範：[resources/style-guide.md](resources/style-guide.md)、[CONTRIBUTING.md](CONTRIBUTING.md)
RESOURCES.zh-Hans.md
+102
View File
@@ -0,0 +1,102 @@
# 相关资源
> [繁體中文](./RESOURCES.md) | **简体中文** | [English](./RESOURCES.en.md)
> [← 返回主路线 README](README.zh-Hans.md)
这份文件集中放：用語说明、常用 MCP / Skill 集成 highlight、同主题 awesome list、中文社群资源。从主 README 抽出避免主页过长。
> 💡 **不懂某个词**（LLM、agent、RAG、token、向量数据库⋯）→ [`resources/glossary.zh-Hans.md`](resources/glossary.zh-Hans.md)（用語小词典，30 多个词每个 30-80 字解释）
---
## 三个核心用语：MCP / Skills / Plugins
主 README 跟各 stage 会频繁提到这三个 Claude Code 生态的关键词，先快速说明：
- **MCP（Model Context Protocol）** — Anthropic 推的开放协定，让任何 LLM host（Claude Code、其他 IDE、自写 agent）都能用同一套接口去调用外部 tool server（文件、DB、API、自家系统）。把它想成“LLM 的 USB 接口”。详见 [Stage 5.2](stages/05-claude-code-ecosystem.zh-Hans.md#52--mcpmodel-context-protocol-基础)。
- **Skills** — Claude Code 的“行为包”。一个 Skill 就是一份 `SKILL.zh-Hans.md`，描述“在什么场景要做什么、可以调用哪些 MCP tool”。写好之后 Claude Code 会自动 discover。详见 [Stage 5.3](stages/05-claude-code-ecosystem.zh-Hans.md#53--skillsclaude-code-的行为层-claude-code-生态最关键的一层)。
- **Plugins / Marketplaces** — 把 Skills、slash commands、hooks、MCP 设置打包成一个发布单位给 team 或社群安装。Marketplace 就是 plugin 的 catalog。详见 [Stage 5.4](stages/05-claude-code-ecosystem.zh-Hans.md#54--plugins-与-marketplaces)。
对应的 **动手练习都在 [Stage 5](stages/05-claude-code-ecosystem.zh-Hans.md)，Track A 的 [A3](tracks/cli/A3-cli-production.zh-Hans.md) 也会用到。
---
## 接日常工具：常用 MCP server / Skill
把 Claude Code（或其他 CLI agent）接到你已经在用的 app，省掉手动切换的成本。下面几个是社群 / 官方比较成熟的：
### 笔记 / 知识库
- [**MarkusPfundstein/mcp-obsidian**](https://github.com/MarkusPfundstein/mcp-obsidian) ★ 3.9k+ — 透过 Obsidian REST API plugin 让 LLM 读写你的 Obsidian vault
- [**makenotion/notion-mcp-server**](https://github.com/makenotion/notion-mcp-server) ★ 4.4k+ — Notion **官方** MCP server，可查询／建立 page、database
- [**PleasePrompto/notebooklm-skill**](https://github.com/PleasePrompto/notebooklm-skill) ★ 7.3k+ — NotebookLM Skill（浏览器自动化），用 Claude Code 直接查你 NotebookLM 里的文件，回答带 citation
- [**teng-lin/notebooklm-py**](https://github.com/teng-lin/notebooklm-py) ★ 16k+ — 非官方 NotebookLM Python API + CLI，支持 Claude Code / Codex 等 agent 集成
### 办公文件（Word / Excel / PowerPoint / PDF）
- [**anthropics/skills**](https://github.com/anthropics/skills) ★ 158k+ — Anthropic **官方** Skills 集合，docx / xlsx / pptx / pdf 处理直接内建
- [**tfriedel/claude-office-skills**](https://github.com/tfriedel/claude-office-skills) ★ 725 — 补强版 Office skills（PPTX/DOCX/XLSX/PDF），含自动化 workflow
### Google Workspace（Gmail / Docs / Drive / Calendar）
- [**taylorwilsdon/google_workspace_mcp**](https://github.com/taylorwilsdon/google_workspace_mcp) ★ 2.6k+ — 一个 server 包整套 Google Workspace（Gmail、Calendar、Docs、Sheets、Slides、Drive）
### 开发协作
- [**github/github-mcp-server**](https://github.com/github/github-mcp-server) ★ 29k+ — GitHub **官方** MCP，issue / PR / repo 操作
- [**atlassian/atlassian-mcp-server**](https://github.com/atlassian/atlassian-mcp-server) ★ 810 — Atlassian **官方** Remote MCP（Jira、Confluence）
- [**jerhadf/linear-mcp-server**](https://github.com/jerhadf/linear-mcp-server) ★ 340+ — Linear MCP server
- [**korotovsky/slack-mcp-server**](https://github.com/korotovsky/slack-mcp-server) ★ 1.7k+ — Slack MCP，无 admin 权限也能用
### 研究工作流（本 repo 维护者出品）
- [**WenyuChiou/ai-research-skills**](https://github.com/WenyuChiou/ai-research-skills) ★ 123 — 14 个研究流程 skill，5-plugin marketplace
- [**WenyuChiou/research-hub**](https://github.com/WenyuChiou/research-hub) ★ 33 — Zotero + Obsidian + NotebookLM 集成 workspace
- [**WenyuChiou/zotero-skills**](https://github.com/WenyuChiou/zotero-skills) ★ 28 — Zotero CLI skill
- [**WenyuChiou/codex-delegate**](https://github.com/WenyuChiou/codex-delegate) ★ 57 + [**gemini-delegate-skill**](https://github.com/WenyuChiou/gemini-delegate-skill) ★ 34 — Multi-LLM delegation 对
### 中文圈常用
- [**leemysw/feishu-docx**](https://github.com/leemysw/feishu-docx) ★ 235 — 飞书（Lark）docs / sheet / bitable ↔ Markdown，含 Claude Skills 支持
> 上面只是 highlight。**完整 65+ 个集成的分类目录**（含数据库、浏览器自动化、Figma、Excalidraw、Cloudflare、Stripe、学术写作 / Multi-LLM delegation 等）在 [`resources/mcp-skills-catalog.zh-Hans.md`](resources/mcp-skills-catalog.zh-Hans.md)。
> 想找更多 MCP server catalog？看 [`wong2/awesome-mcp-servers`](https://github.com/wong2/awesome-mcp-servers) / [`punkpeye/awesome-mcp-servers`](https://github.com/punkpeye/awesome-mcp-servers)（按分类整理）。**Canva** 的官方 MCP 还在 early access，社群版本不稳定，等成熟后再补上。
---
## 同主题的清单型 awesome lists
本 repo **不取代清单型 awesome list——你已经知道在找什么工具时，下面这些查起来更直接：
### MCP 相关
- [**modelcontextprotocol/servers**](https://github.com/modelcontextprotocol/servers) — 官方 MCP reference servers（filesystem、github、sqlite、git、fetch、memory 等）
- [**wong2/awesome-mcp-servers**](https://github.com/wong2/awesome-mcp-servers) — 社群 MCP server 清单，按分类整理（150+ 个）
- [**punkpeye/awesome-mcp-servers**](https://github.com/punkpeye/awesome-mcp-servers) — 另一份 MCP server 清单
### Claude Code / Skills / Plugins 相关
- [**hesreallyhim/awesome-claude-code**](https://github.com/hesreallyhim/awesome-claude-code) — Claude Code 相关资源清单（整理中）
- [**travisvn/awesome-claude-skills**](https://github.com/travisvn/awesome-claude-skills) — Claude Skills 清单
- [**anthropics/claude-plugins-official**](https://github.com/anthropics/claude-plugins-official) — Anthropic 官方 plugin 范本，要打包自己的 plugin 从这份开始
### 中文圈必看
- [**datawhalechina/hello-agents**](https://github.com/datawhalechina/hello-agents) — Datawhale 系统性 agent 教学（zh-Hans）
- [**WangRongsheng/awesome-LLM-resources**](https://github.com/WangRongsheng/awesome-LLM-resources) — 完整的中文 LLM 资源整理（8k+ stars）
- [**AiHubCN/Awesome-Chinese-LLM**](https://github.com/AiHubCN/Awesome-Chinese-LLM) — 中文开源大模型整理
### 线上课程 / MOOC（带证书对照）
- [**resources/courses.zh-Hans.md**](resources/courses.zh-Hans.md) — 10 门 credible、会发证书的线上 AI agent 课（英文 + 中文），分 tier；并诚实标注完成证书不是学历
---
## 还有什么？
- 主 README：[README.zh-Hans.md](README.zh-Hans.md)
- 完整 MCP/Skill 目录：[resources/mcp-skills-catalog.zh-Hans.md](resources/mcp-skills-catalog.zh-Hans.md)
- CLI agent 比较指南：[resources/cli-agents-guide.zh-Hans.md](resources/cli-agents-guide.zh-Hans.md)
- Style guide / 贡献规范：[resources/style-guide.zh-Hans.md](resources/style-guide.zh-Hans.md)、[CONTRIBUTING.zh-Hans.md](CONTRIBUTING.zh-Hans.md)
ROADMAP.en.md
+56
View File
@@ -0,0 +1,56 @@
# Roadmap
> [繁體中文](./ROADMAP.md) | [简体中文](./ROADMAP.zh-Hans.md) | **English**
This repo is a **community-maintained learning roadmap**: no release date, no promised schedule. This document makes public “where we know things are not good enough and where we want to go next”, so people who want to contribute can pick one piece to start with, without reading the whole repo first just to know what is missing.
> Want to work on one item? Open a [Discussion](https://github.com/WenyuChiou/awesome-agentic-ai-zh/discussions) first, or send a PR directly. For long-term stage / branch maintainers, see [`CONTRIBUTORS.md`](CONTRIBUTORS.md). For beginner entry points, see the “5 easy entry points” section in [`CONTRIBUTING.md`](CONTRIBUTING.md).
**Status legend**: 🟢 In progress / always open to contributions · 🟡 Known gap, wanted · 🔵 Idea, pending discussion · ✅ Recently completed
---
## Near-Term Gaps We Want to Fill
### 🟡 Fill Out Hands-On Exercise Coverage
`examples/` currently covers Stage 1, 3, 4, 5, 6, and 7. **Missing**: Stage 2 (Prompt Design), Stage 8 (Agent Interfaces), plus Stage 0 (Foundation Concepts) and Stage 7.5 (Advanced Agentic Concepts), two existing stages that also have no corresponding hands-on examples. Each example should run in under 30 minutes and include `how to run` commands.
### 🟡 Deepen the audience branch Files
5 audience branch files by length (zh-TW canonical, 2026-05 snapshot): for-knowledge-worker (143 lines, shortest) < for-developer (166) < for-everyday-users (179) < for-researcher (208) < for-teacher (224). **The shortest files, `for-knowledge-worker.md` / `for-developer.md`, need scenario coverage the most**. `for-teacher.md` is actually the longest, but `CONTRIBUTORS.md` still marks it as “especially open to self-nominations”: what is truly thin is the **academic citation depth for teacher scenarios** (currently only Chen 2020 / Mittal 2024), and more 3-tier teacher AI application scenarios + matching citations are welcome.
### 🟡 Stage 2 / Stage 3 2026 freshness Touch-Up
A few small 2026 wording / model-reference updates have not been synced to mirrors yet (about 5 lines of diff × 2 locales).
---
## In Progress / Always Open to Contributions
- 🟢 **Outdated entry reports** — Run `python scripts/refresh-stars.py` to find repos with large star-count gaps, then open an issue or PR to annotate / remove them.
- 🟢 **Broken link fixes** — Monthly CI scans for link-rot, but direct PRs for anything found in real time are fastest.
- 🟢 **Complete `how to run` sections** — Many entries are missing installation / execution commands. If you have run one, add them.
- 🟢 **Mirror translation smoothing** — Compare `.en.md` / `.zh-Hans.md` against zh-TW, and fix one sentence that reads awkwardly.
- 🟢 **Long-term stage / branch maintainers** — Claim one stage or branch and review it when you have time. The slot table is in `CONTRIBUTORS.md`.
---
## Infrastructure (maintainer in progress)
- ✅ **Community health files** — `CODE_OF_CONDUCT.md` / `SECURITY.md` / `CITATION.cff` / issue-template routing (same batch as this roadmap).
- 🟢 **Learner progress layer** — `PROGRESS.md` self-check template + “Self check / Exit check” at the end of each stage (planned).
- 🔵 **Browsable docs site** — Render stages/tracks/branches into a website with navigation + search + language switching (GitHub Pages, under evaluation).
- 🟢 **Trilingual mirror parity** — `mirror-sync-reminder` + `check-mirror-sync.py` already guard PRs, and legacy drift is being cleaned continuously.
- 🟢 **Quality gates** — link-rot / star-drift / banned-word / anchor / zh-Hans localization CI is online and maintained.
---
## Idea Box (pending discussion, not committed yet)
- 🔵 **More audience branch files**: There are currently 5 (researcher / developer / teacher / knowledge-worker / everyday-users). Whether to split further (for example PM / designer / legal) depends on community needs.
- 🔵 **A third track?**: Today, Track A = CLI Power User (A1–A3 under `tracks/cli/`), and Track B = stages learning path (`stages/` directory Stage 0–8, **not** a standalone directory under `tracks/`). Whether to add a third track (for example “no-code agent only”) is pending discussion.
- 🔵 **Video / interactive supplements**: Whether a text-only learning roadmap should include minimal video walkthroughs depends on cost and maintenance load.
To suggest an idea, open a [Discussion](https://github.com/WenyuChiou/awesome-agentic-ai-zh/discussions), not an issue (issues are for bugs / outdated entries / new projects).
---
> This roadmap is not a contract. It reflects the direction “now”, and will change as the community contributes. The most reliable source for “what should happen next” is always open issues + Discussions.
ROADMAP.md
+56
View File
@@ -0,0 +1,56 @@
# 路線圖 / Roadmap
> **繁體中文** | [简体中文](./ROADMAP.zh-Hans.md) | [English](./ROADMAP.en.md)
這份 repo 是**社群維護的學習路線圖**——沒有發行日期、沒有承諾的時程。這份文件公開「我們知道哪裡還不夠好、接下來想往哪走」,讓想貢獻的人能挑一塊上手,而不用先讀完整個 repo 才知道缺什麼。
> 想動其中一項?開個 [Discussion](https://github.com/WenyuChiou/awesome-agentic-ai-zh/discussions) 講一聲,或直接 PR。擔任 stage / branch 長期維護者請看 [`CONTRIBUTORS.md`](CONTRIBUTORS.md)。新手切入點看 [`CONTRIBUTING.md`](CONTRIBUTING.md) 的「好上手的 5 個切入點」。
**狀態圖例**:🟢 進行中 / 隨時可貢獻 · 🟡 已知缺口、想做 · 🔵 想法、待討論 · ✅ 近期完成
---
## 近期想補的缺口
### 🟡 動手練習覆蓋補齊
`examples/` 目前涵蓋 Stage 1、3、4、5、6、7。**缺**:Stage 2(Prompt 設計)、Stage 8(Agent Interfaces),以及 Stage 0(基礎概念)、Stage 7.5(進階 Agentic 概念)這兩個現有 stage 也都沒有對應的 hands-on 範例。每個範例要能在 30 分鐘內跑完、附 `怎麼跑` 指令。
### 🟡 audience branch 深化
5 條 audience branch 篇幅(zh-TW canonical,2026-05 snapshot):for-knowledge-worker(143 行,最短)< for-developer(166)< for-everyday-users(179)< for-researcher(208)< for-teacher(224)。**篇幅最短的 `for-knowledge-worker.md` / `for-developer.md` 最需要補情境**。`for-teacher.md` 篇幅其實最長,但 `CONTRIBUTORS.md` 仍把它標「特別歡迎自薦」——它真正薄的是**教師情境的學術引用深度**(目前只有 Chen 2020 / Mittal 2024 兩筆),歡迎補更多 3-tier 教師 AI 應用情境 + 對應引用。
### 🟡 Stage 2 / Stage 3 2026 freshness 小修
幾處 2026 用語 / 模型引用的小幅更新還沒同步到鏡像(約 5 行 diff × 2 locale)。
---
## 進行中 / 隨時可貢獻
- 🟢 **過時 entry 回報** — 跑 `python scripts/refresh-stars.py` 找星數差距大的 repo,開 issue 或 PR 標註 / 移除。
- 🟢 **失效連結修正** — link-rot 每月 CI 會掃,但即時發現的直接 PR 最快。
- 🟢 **`怎麼跑` section 補完** — 很多 entry 缺安裝 / 執行指令,你跑過就補。
- 🟢 **鏡像翻譯順稿** — 對照 `.en.md` / `.zh-Hans.md` 與 zh-TW,改一句翻得不順的。
- 🟢 **stage / branch 長期維護者** — 認領一個 stage 或 branch,有空時 review 一輪。名額表在 `CONTRIBUTORS.md`。
---
## 基礎建設(maintainer 進行中)
- ✅ **社群健康檔** — `CODE_OF_CONDUCT.md` / `SECURITY.md` / `CITATION.cff` / issue-template 導流(本路線圖同批)。
- 🟢 **學習者進度層** — `PROGRESS.md` 自我打勾範本 + 每個 stage 結尾「自我檢核 / Exit check」(規劃中)。
- 🔵 **可瀏覽文件站** — 把 stages/tracks/branches 渲染成有導覽 + 搜尋 + 語言切換的網站(GitHub Pages,評估中)。
- 🟢 **三語鏡像 parity** — `mirror-sync-reminder` + `check-mirror-sync.py` 已在 PR 時把關,持續清 legacy drift。
- 🟢 **品質 gate** — link-rot / star-drift / banned-word / anchor / zh-Hans 在地化 CI 已上線並維護中。
---
## 想法箱(待討論,還沒承諾)
- 🔵 **更多 audience branch**:目前 5 條(researcher / developer / teacher / knowledge-worker / everyday-users),是否要再分(例如 PM / 設計師 / 法務)看社群需求。
- 🔵 **第三條軌道?**:目前 Track A = CLI Power User(`tracks/cli/` 的 A1–A3)、Track B = stages 學習路線(`stages/` 目錄 Stage 0–8,**不是** `tracks/` 下的獨立目錄)。是否要有第三條軌道(例如「只用 no-code agent」)待討論。
- 🔵 **影音 / 互動補充**:純文字學習路線是否要配最小影音 walkthrough,成本與維護負擔待評估。
要提想法請開 [Discussion](https://github.com/WenyuChiou/awesome-agentic-ai-zh/discussions),不要開 issue(issue 留給 bug / 過時 entry / 新增 project)。
---
> 這份路線圖不是契約。它反映「現在」的方向,會隨社群投入而變。最可靠的「接下來要做什麼」永遠是 open issues + Discussions。
ROADMAP.zh-Hans.md
+56
View File
@@ -0,0 +1,56 @@
# 路线图 / Roadmap
> [繁體中文](./ROADMAP.md) | **简体中文** | [English](./ROADMAP.en.md)
这份 repo 是**社区维护的学习路线图**——没有发布日期、没有承诺的时间表。这份文件公开“我们知道哪里还不够好、接下来想往哪里走”，让想贡献的人能挑一块上手，而不用先读完整个 repo 才知道缺什么。
> 想动其中一项？开个 [Discussion](https://github.com/WenyuChiou/awesome-agentic-ai-zh/discussions) 说一声，或直接 PR。担任 stage / branch 长期维护者请看 [`CONTRIBUTORS.md`](CONTRIBUTORS.md)。新手切入点看 [`CONTRIBUTING.md`](CONTRIBUTING.md) 的“好上手的 5 个切入点”。
**状态图例**：🟢 进行中 / 随时可贡献 · 🟡 已知缺口、想做 · 🔵 想法、待讨论 · ✅ 近期完成
---
## 近期想补的缺口
### 🟡 动手练习覆盖补齐
`examples/` 目前覆盖 Stage 1、3、4、5、6、7。**缺**：Stage 2（Prompt 设计）、Stage 8（Agent Interfaces），以及 Stage 0（基础概念）、Stage 7.5（进阶 Agentic 概念）这两个现有 stage 也都没有对应的 hands-on 示例。每个示例要能在 30 分钟内跑完，并附 `怎么跑` 命令。
### 🟡 audience branch 深化
5 条 audience branch 篇幅（zh-TW canonical, 2026-05 snapshot）：for-knowledge-worker（143 行，最短）< for-developer（166）< for-everyday-users（179）< for-researcher（208）< for-teacher（224）。**篇幅最短的 `for-knowledge-worker.md` / `for-developer.md` 最需要补情境**。`for-teacher.md` 篇幅其实最长，但 `CONTRIBUTORS.md` 仍把它标为“特别欢迎自荐”——它真正薄的是**教师情境的学术引用深度**（目前只有 Chen 2020 / Mittal 2024 两笔），欢迎补更多 3-tier 教师 AI 应用情境 + 对应引用。
### 🟡 Stage 2 / Stage 3 2026 freshness 小修
几处 2026 用语 / 模型引用的小幅更新还没同步到镜像（约 5 行 diff × 2 locale）。
---
## 进行中 / 随时可贡献
- 🟢 **过时 entry 反馈** — 跑 `python scripts/refresh-stars.py` 找星数差距大的 repo，开 issue 或 PR 标注 / 移除。
- 🟢 **失效链接修正** — link-rot 每月 CI 会扫，但即时发现的直接 PR 最快。
- 🟢 **`怎么跑` section 补完** — 很多 entry 缺安装 / 执行命令，你跑过就补。
- 🟢 **镜像翻译顺稿** — 对照 `.en.md` / `.zh-Hans.md` 与 zh-TW，改一句翻得不顺的。
- 🟢 **stage / branch 长期维护者** — 认领一个 stage 或 branch，有空时 review 一轮。名额表在 `CONTRIBUTORS.md`。
---
## 基础建设（maintainer 进行中）
- ✅ **社区健康文件** — `CODE_OF_CONDUCT.md` / `SECURITY.md` / `CITATION.cff` / issue-template 导流（本路线图同批）。
- 🟢 **学习者进度层** — `PROGRESS.md` 自我打勾模板 + 每个 stage 结尾“自我检查 / Exit check”（规划中）。
- 🔵 **可浏览文件站** — 把 stages/tracks/branches 渲染成有导航 + 搜索 + 语言切换的网站（GitHub Pages，评估中）。
- 🟢 **三语镜像 parity** — `mirror-sync-reminder` + `check-mirror-sync.py` 已在 PR 时把关，持续清 legacy drift。
- 🟢 **质量 gate** — link-rot / star-drift / banned-word / anchor / zh-Hans 本地化 CI 已上线并维护中。
---
## 想法箱（待讨论，还没承诺）
- 🔵 **更多 audience branch**：目前 5 条（researcher / developer / teacher / knowledge-worker / everyday-users），是否要再分（例如 PM / 设计师 / 法务）看社区需求。
- 🔵 **第三条轨道？**：目前 Track A = CLI Power User（`tracks/cli/` 的 A1–A3）、Track B = stages 学习路线（`stages/` 目录 Stage 0–8，**不是** `tracks/` 下的独立目录）。是否要有第三条轨道（例如“只用 no-code agent”）待讨论。
- 🔵 **视频 / 互动补充**：纯文字学习路线是否要配最小视频 walkthrough，成本与维护负担待评估。
要提想法请开 [Discussion](https://github.com/WenyuChiou/awesome-agentic-ai-zh/discussions)，不要开 issue（issue 留给 bug / 过时 entry / 新增项目）。
---
> 这份路线图不是契约。它反映“现在”的方向，会随社区投入而变。最可靠的“接下来要做什么”永远是 open issues + Discussions。
SECURITY.en.md
+39
View File
@@ -0,0 +1,39 @@
# Security Policy
> [繁體中文](./SECURITY.md) | [简体中文](./SECURITY.zh-Hans.md) | **English**
This repo is a **curated learning roadmap** (mainly Markdown learning materials plus a small amount of example code), not a software product that gets deployed. Even so, several categories of security issues are still worth reporting, especially because this material teaches readers to **actually run agents / MCP / tool-use**.
## Supported Scope
This project uses **rolling maintenance** and has no versioned releases. Only the latest state of the `main` branch will be fixed.
## What Counts as a Security Issue
Please report the following:
- **Hijacked / malicious third-party links** — a repo link in the catalog points to a phishing site or malicious package, or the project has been taken over maliciously
- **Supply-chain risks in example code** — code in `examples/`, `walkthroughs/`, or `scripts/` leads readers toward unsafe dependencies, patterns that leak keys, or injectable commands
- **Leaked secrets in learning materials** — real API keys / tokens / credentials were accidentally pasted into the docs
- **Command-injection-style instructional content** — a piece of instruction leads readers to run something dangerous on their own machines (for example, executing an agent on untrusted input without sandboxing)
**Not in scope** for this repo's security policy: vulnerabilities in third-party projects **themselves**. Please report those directly to the upstream project maintainers, and you may also open an issue to remind us to label or remove that entry.
## How to Report
**Please do not post exploitable details in a public issue.**
1. **Preferred**: Use GitHub's **private vulnerability reporting** (the repo's **Security** tab → **Report a vulnerability**). Only maintainers can see it.
2. If that feature is unavailable: please DM **@WenyuChiou** on GitHub with the impact and the affected files / links, and we will continue privately. **Do not open a public issue** — even without exploit details, a public title and labels would expose that there is an unpatched issue.
When reporting, please include as much as possible: affected files / links, a description of the issue, the possible impact, and (if any) suggested fixes.
## Response Timeline
This is a community-maintained educational project with no SLA, but we will handle reports as quickly as possible. In general:
- **Acknowledgement**: within 7 days
- **Initial assessment**: within 14 days
- **Fix or annotation**: depends on severity; malicious links will be prioritized
Thank you for helping make this material safer for all learners.
SECURITY.md
+39
View File
@@ -0,0 +1,39 @@
# 安全政策 / Security Policy
> **繁體中文** | [简体中文](./SECURITY.zh-Hans.md) | [English](./SECURITY.en.md)
這個 repo 是一份**精選學習路線圖**(主要是 Markdown 教材 + 少量範例程式碼),不是一個會部署的軟體產品。即便如此,有幾類安全問題仍然值得回報——尤其因為本教材教讀者**實際執行 agent / MCP / tool-use**。
## 支援範圍
本專案採**滾動式維護**,沒有版本化 release。只有 `main` 分支的最新狀態會被修正。
## 哪些算安全問題
請回報以下情況:
- **被劫持 / 惡意的第三方連結** —— 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 天內
- **修正或標註**:視嚴重程度而定;惡意連結會優先處理
謝謝你幫忙讓這份教材對所有學習者都更安全。
SECURITY.zh-Hans.md
+39
View File
@@ -0,0 +1,39 @@
# 安全政策 / Security Policy
> [繁體中文](./SECURITY.md) | **简体中文** | [English](./SECURITY.en.md)
这个 repo 是一份**精选学习路线图**（主要是 Markdown 教材 + 少量示例代码），不是一个会部署的软件产品。即便如此，有几类安全问题仍然值得报告，尤其因为本教材教读者**实际运行 agent / MCP / tool-use**。
## 支持范围
本项目采用**滚动式维护**，没有版本化 release。只有 `main` 分支的最新状态会被修正。
## 哪些算安全问题
请报告以下情况：
- **被劫持 / 恶意的第三方链接** —— 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 天内
- **修正或标注**：视严重程度而定；恶意链接会优先处理
谢谢你帮忙让这份教材对所有学习者都更安全。
book.toml
+39
View File
@@ -0,0 +1,39 @@
[book]
title = "awesome-agentic-ai-zh"
description = "AI Agent 學習地圖 — 從第一行 LLM API 到自己打造多 agent 系統"
authors = ["Wenyu Chiou"]
language = "zh-TW"
multilingual = false
src = "book/src"
[output.html]
default-theme = "light"
preferred-dark-theme = "navy"
git-repository-url = "https://github.com/WenyuChiou/awesome-agentic-ai-zh"
edit-url-template = "https://github.com/WenyuChiou/awesome-agentic-ai-zh/edit/main/{path}"
site-url = "/awesome-agentic-ai-zh/"
[output.html.search]
enable = true
limit-results = 30
use-boolean-and = true
boost-title = 2
boost-hierarchy = 2
boost-paragraph = 1
expand = true
[output.html.fold]
enable = true
level = 1
# Note: mdbook-mermaid preprocessor was removed. The repo no longer
# uses ```mermaid``` code blocks (replaced with PNG images + ASCII
# diagrams) and the v0.17.0 preprocessor was failing with "Unable to
# parse the input" on stale runs. To re-enable: install mdbook-mermaid,
# run `mdbook-mermaid install .`, and add back:
# additional-js = ["mermaid.min.js", "mermaid-init.js"]
# [preprocessor.mermaid]
# command = "mdbook-mermaid"
[build]
build-dir = "book/dist"
branches/DESIGN.md
+157
View File
@@ -0,0 +1,157 @@
# Branch 設計筆記
> 這份是給 maintainer 看的內部文件，**不是讀者面向的內容**。
>
> 5 個 branch 怎麼分、entry 怎麼判斷該放哪、什麼時候要不要新開 branch——這些設計決定的記錄。新 maintainer 接手時看這份就懂為什麼是這樣分。
---
## 為什麼是 5 個 branch（不是 3 個或 10 個）
### Branch 跟 Track 的關係
5 條 branch 設計成 **兩條軌道走完都接得上**：
- Track A 完成 A3 → 從 branches 選一條繼續
- Track B 完成 Stage 7 → 從 branches 選一條繼續
- Branch entry 的 curation 標準**不依軌道區分**——同一個工具不論是 Track A 用法（用現成 CLI）還是 Track B 用法（自己接 SDK），都放在對應 audience 的 branch 內
**例外：for-everyday-users branch 可以直接進入**——不一定要走完軌道。這條 branch 的目標讀者是「Claude.ai / ChatGPT 重度使用者，想用 AI 但不一定想 build」，他們可能根本不需要碰 Track A 或 B；branch 內也明確標示「不一定要走完整條主幹」。其他 4 條 branch（researcher / developer / teacher / knowledge-worker）預設讀者已走完一條軌道。
Branch maintainer 應該意識到：**進來看 branch 的讀者背景可能差很多**——剛走完 Track A 的人對 framework 內部不熟、剛走完 Track B 的人對 CLI 操作可能不熟、直接進 everyday-users 的人對 Stage 0-2 都可能跳過。Branch entry 的 prose 要盡量讓這幾種讀者都看得懂。
### 太少（≤3）的問題
3 個會強行把多個 audience 塞同一條，譬如「professional」涵蓋 dev + researcher + knowledge worker——但他們的 pain point 完全不同。研究者要 grounded citation，開發者要 git-native，知識工作者要 email triage——硬擠成一條 branch 會讓 entry 互相 dilute。
### 太多（≥7）的問題
audience 切太細會：
- 每個 branch 都很薄（沒幾個 entry），讀者覺得不被照顧
- 邊界開始模糊（資料科學家 vs 機器學習工程師？產品經理 vs 顧問？）
- maintain 成本變高（要看的 branch 變多）
### 5 是 sweet spot
4 個職業（research / dev / teach / knowledge work）覆蓋大部分專業場景；第 5 個 everyday users 收尾「不寫 code 的純使用者」這條沒被任何職業 branch 照顧到的 audience。
**判準**：每個 branch 都應該對應到一個**讀者一秒就能自我認領**的身份標籤。如果 maintainer 自己都要想 30 秒才能決定一個 entry 該放哪，就是 branch 切得不夠清楚。
---
## 5 個 audience 的核心 pain point
每個 branch 都是回應一個具體 pain，不是涵蓋一整個職業生涯：
| Branch | 核心 pain | branch 主要回應 |
|---|---|---|
| 🔬 研究人員 | 「我要 review 100 篇 paper、寫 lit review，但時間不夠」 | 文獻 RAG、Outline-driven 寫作、Zotero 整合 |
| 💻 開發者 | 「我有 10 個 PR 要 review、每個 codebase 都不同 convention」 | git-native CLI、IDE coding agent、code review skill |
| 🎓 教師 | 「備課要花 4 小時、我手上的 prompt 都太通用」 | 學科特化 prompt、課程素材、評量自動化 |
| 📊 知識工作者 | 「每天信箱 100 封、會議紀錄要轉成 action items、隔天還要寫 weekly report」 | Email triage、會議紀錄、自動化 workflow |
| 👥 日常使用者 | 「我不寫 code，但想用 AI 改善生活，不知道從哪開始」 | Tier 0 入門到 Tier 2 進階 CLI 的階梯式路線 |
每個 branch 的 entry 選入都應該回到「能不能解決核心 pain」這個問題。如果不能，就是 entry 該放別的地方。
---
## Branch 之間的邊界
判斷一個 entry 該放哪個 branch，按這 3 條判準依序考慮：
### 1. 主要 user persona
看上面 pain table——這個 entry 解決的是哪一個 audience 的 pain？通常很清楚。
### 2. 預期動手程度
不寫 code 的工具 → 偏 everyday-users / knowledge-worker。CLI / SDK 工具 → 偏 developer。介於中間（譬如 ChatPaper 是命令列但對研究者友善）→ 看 #1 主要 persona。
### 3. 應用場景
同一個工具在不同場景下歸類不同。例如：
- **Ollama**：給 everyday-users 是「隱私場景跑本地 LLM」（Tier 3），給 developer 是「開發 agent 的本地測試 backend」——但這份 catalog 把它放在 **Stage 1**（基礎設施層級），各 branch 從那裡引用。
- **f/awesome-chatgpt-prompts**：放 for-teacher（給教師當教材參考）、也放 for-everyday-users（不寫 code 也能用的 prompt 庫）。
### 灰色地帶處理（同一 repo 出現在多 branch）
**規則**：同一 repo 可以在多 branch 出現，但每處要有不同的 **framing**（適合誰、教什麼）。**推薦星等預設一致**——同一個工具的客觀價值不會因 audience 改變；除非有明確的 audience-specific 理由（譬如「進階度差太多」），且寫進 Notes 解釋。詳見 [`resources/style-guide.md`](../resources/style-guide.md) 2。
**範例**：
- `obra/superpowers` 出現在 Stage 5、for-developer、for-knowledge-worker、for-teacher
- Stage 5：作為 SKILL.md collection 範例
- for-developer：作為 TDD / debug skill 來源
- for-knowledge-worker：作為腦力激盪 / 規劃 skill
- for-teacher：作為通用寫作 skill
- **4 處都是 ⭐⭐⭐⭐**（這是規則的正例：framing 不同、評等一致）
**反例（不該這樣做）**：
- `kaixindelele/ChatPaper` 只放 for-researcher，不放 for-everyday-users。原因：它是研究者專用流程（總結 / 翻譯 / 審稿回覆），everyday user 用不到也不該被推。
---
## 兩種 entry 結構：tier vs flat
### Tier 結構（目前只用在 for-everyday-users）
![Branch tier 漸進結構](../resources/diagrams/branch-tier-progression.png)
**用 tier 的條件**：audience 內部「動手程度差很多」。Everyday users 從「打開 Claude.ai」到「跑 Ollama 本地 LLM」差距太大，不分 tier 會混亂。
### Flat 結構（其他 4 個 branch 都用這個）
單一個 list，照子主題分類（Coding Agents / Code Review / Workflow Tools 等）。
**用 flat 的條件**：audience 內部相對同質——研究者多半願意動手用 CLI、開發者一定會寫 code，沒必要分 tier。
### 什麼時候從 flat 升級成 tier
觀察 issue / PR 是否反覆出現「**這個 entry 太進階 / 太簡單**」抱怨。若 ≥3 個讀者反映該 branch 內 entry 落差太大，考慮分 tier。
---
## 自我引用排除原則
`WenyuChiou/*` repo 一律不收（已從 catalog 移除 32 instances）。
### 例外（什麼條件下作者自己的 repo 才能加回去）
1. 該 repo 在某個 stage / branch 是**唯一夠用的選項**（沒其他社群替代）
2. 至少 2 個 stage maintainer 簽字同意
3. 在 entry notes 明確標註「作者維護的 repo，含利益關係」
4. 加一個「替代品」連結，方便讀者比較
**目前 0 個 entry 滿足這 4 條**——保持 0 個是健康狀態。
---
## 加新 branch 的決策樹
![加新 branch 決策樹](../resources/diagrams/add-branch-decision-flow.png)
### 範例：要不要加 `for-data-scientists`？
- pain 已被 for-researcher 涵蓋（文獻 RAG、實驗設計）
- audience scale 大，但跟 researcher 重疊高
- 結論：不加 branch，但可以在 for-researcher 加「資料科學工具」 sub-section
### 範例：要不要加 `for-product-managers`？
- pain 已被 for-knowledge-worker 涵蓋（會議紀錄、report、跨 team 溝通）
- audience scale 大但邊界跟 knowledge-worker 模糊
- 結論：不加 branch，在 for-knowledge-worker 加「產品經理」use case
---
## 5 條 branch 的 maintenance 想法（不是 SLA）
社群 repo 的維護是「能做就做」、不是排程義務。下面是大致方向：
### Review 頻率
- 沒有強制節奏。CI 已設定每月自動跑 link rot + star drift（被動的）。
- 有空想動的人 → 跑 `python scripts/refresh-stars.py` 看哪些 entry 過時、`python scripts/check-links.py --fast` 看哪些連結壞掉。
### Entry 加入 / 移除節奏
- 加入：看到值得收的就 PR。不必為了「衝量」主動找。
- 移除：archived / 長期沒 commit / license 變奇怪 → 看到再標 ⚠️ 或 PR 拿掉。
### 跟 main path stages 的同步
- Stage 改了某個 entry，branch 引用該 entry 的地方順手更新就好——沒做也不會壞。
### Maintainer 自薦 / 退場機制
- 想擔任 maintainer 開 issue 自薦就好，不用承諾什麼具體期間。「我 review 一次」也算貢獻。
- 退場：不需要 ceremony——維持沉默 2 個月，自動視為退場，新人接手
- 詳見 [`CONTRIBUTORS.md`](../CONTRIBUTORS.md)
---
## 不在這份的內容
- **個別 branch 的 entry 詳細**：見 `for-X.md` 本身
- **stage 設計理由**：見 [`../stages/DESIGN.md`](../stages/DESIGN.md)
- **entry schema / 用詞規範**：見 [`../resources/style-guide.md`](../resources/style-guide.md)
branches/for-developer.en.md
+166
View File
@@ -0,0 +1,166 @@
# Extension Path: For Developers
> [繁體中文](./for-developer.md) | [简体中文](./for-developer.zh-Hans.md) | **English**
> 🚀 **First time installing Claude Code or writing `CLAUDE.md` / `SKILL.md`?** The quick setup guide is [`resources/setup-guide.en.md` D-E](../resources/setup-guide.en.md). Skip it if you already know this.
> [← Back to main path README](../README.en.md) · Continue here after **Track A's A3** or **Track B's Stage 7**. Apply agentic AI to coding workflows.
## Use Cases (Developer Scenarios × How AI Helps)
The table below splits a developer's day into 7 common scenarios. Each has a different pain point, and each calls for a different level of AI tooling:
| Scenario | Pain point | How AI helps | Recommended tools (light → heavy) |
|---|---|---|---|
| **AI pair programming** | You forget syntax mid-flow or cannot recall a method name | Autocomplete + rewrite + explanation | Cursor / Copilot → Claude Code |
| **Multi-file refactoring** | Changing one class risks missed references; cross-file rename is error-prone | Batch refactors while keeping style consistent across many files | Cursor → Claude Code → codex-delegate |
| **Code review (your own PR)** | Reviewing your own diff makes it easy to miss problems | Find bugs / smells and check edge cases | Claude Code / Cline → Continue (CI) |
| **Writing tests** | TDD cases are easy to miss; coverage falls short | Generate pytest cases from signatures / specs | Claude Code + Aider |
| **Debugging** | Logs are thin; stack traces are hard to interpret | Explain traces, generate hypotheses, run minimal repros | Claude Code |
| **Docs** | Docstrings / READMEs lag behind refactors | Generate docs from code and update docs alongside PRs | Claude Code |
| **CI / team automation** | Manual review is repetitive; style varies across people | Run automated review / lint in GitHub Actions | Claude Code Action + Continue |
> 💡 **Individual vs team**: the first 6 rows are personal daily workflows. The final row (CI) is team governance. For teams under 5 people, AI automation in CI often has low ROI; you can defer it.
## Curated Projects
> **CLI agent comparison**: 7 major CLI agents (Claude Code / Codex / OpenCode / Gemini CLI / goose / Aider / Hermes Agent) compared side-by-side in [`resources/cli-agents-guide.en.md`](../resources/cli-agents-guide.en.md). New to CLI agents and want step-by-step onboarding → [`tracks/cli/A1-cli-intro.en.md`](../tracks/cli/A1-cli-intro.en.md) (Track A first stop).
>
> **MCP catalog**: Looking for integrations to wire CLI into daily tools (GitHub, Linear, Atlassian, Postgres, Playwright, Figma…) → [`resources/mcp-skills-catalog.en.md`](../resources/mcp-skills-catalog.en.md) (65+ entries by category).
>
> This page only lists tool entry points directly relevant to developer workflows.
### Coding Agents
#### [Cursor](https://www.cursor.com/) ⭐⭐⭐⭐⭐
Editor-integrated AI pair-programming tool. Widely adopted in AI editor tools and a useful baseline for comparing other IDE agents.
#### [Aider-AI/aider](https://github.com/Aider-AI/aider) ⭐⭐⭐⭐⭐
★ 44k+ · Apache-2.0 — git-aware CLI pair-programmer. Edits files in your repo directly and writes commits for you. **The open-source reference for "git-native AI editing."** Model-agnostic.
#### [anthropics/claude-code](https://github.com/anthropics/claude-code) ⭐⭐⭐⭐⭐
★ 120k+ — Anthropic's official agentic coding assistant. Skills + plugins ecosystem.
#### [cline/cline](https://github.com/cline/cline) ⭐⭐⭐⭐⭐
★ 61k+ · Apache-2.0 — VS Code extension, autonomous in-IDE agent: tool use, browser, step-by-step approval. **The first pick for VS Code users wanting IDE-native agentic dev.**
#### [continuedev/continue](https://github.com/continuedev/continue) ⭐⭐⭐⭐
★ 33k+ · Apache-2.0 — source-controlled AI checks, enforceable in CI. Represents the **team / governance** angle on coding agents.
#### [OpenHands (formerly OpenDevin)](https://github.com/All-Hands-AI/OpenHands) ⭐⭐⭐⭐
★ 72k+ · MIT — open-source autonomous software development agent. More aggressive design than Aider / Claude Code — agent runs in its own sandbox and commits autonomously. Best for "throw a whole issue at it" scenarios.
#### [block/goose](https://github.com/block/goose) ⭐⭐⭐⭐
★ 43k+ · Apache-2.0 — Open-source, extensible AI agent that goes beyond code suggestions — install / execute / edit / test, with any LLM. Supports multiple LLM providers and MCP, ships as desktop app, CLI, and API. (Repo now resolves to `aaif-goose/goose`.)
#### [RooCodeInc/Roo-Code](https://github.com/RooCodeInc/Roo-Code) ⭐⭐⭐⭐
★ 23k+ · Apache-2.0 — VS Code coding agent with a "**team of specialized modes**" model. Different from Cline's single-agent flow.
### Code Review
#### [obra/superpowers](https://github.com/obra/superpowers) ⭐⭐⭐⭐
20+ battle-tested skills including TDD patterns, debugging, collaboration patterns. Good source for code-review skill design.
### Recommended Tools
- [**yamadashy/repomix**](https://github.com/yamadashy/repomix) ⭐⭐⭐⭐⭐ ★ 26k+ — **Typical developer use case: package the whole codebase for a reviewer / refactor agent**. Outputs a single AI-friendly file (XML / Markdown / JSON) for Claude Code / Codex code review / refactoring. See the official README for technical details such as MCP server mode, tree-sitter compression, and secretlint filtering. **A must-have, daily-driver-grade tool for Track A.**
## Workflows to Master (by frequency)
| Frequency | Workflow | Steps (≤3) | Recommended tools | Best for |
|---|---|---|---|---|
| **Daily** | AI pair programming | (1) Open a branch<br>(2) Give the task to Claude Code and **ask for a plan first** (no code yet)<br>(3) Review plan → approve → code → review your own diff | Claude Code / Cursor / Cline | All developers |
| **Daily** | Git-native AI editing | (1) `aider`<br>(2) Ask in natural language<br>(3) review + commit / `/undo` | Aider | People who want a clean git flow |
| **Per PR** | Automated code review | (1) `.github/workflows/claude-review.yml`<br>(2) Capture git diff → run prompt → post back to PR<br>(3) human + AI review | Claude Code Action + Continue | Teams |
| **Per feature** | Test generation | (1) Provide function signature + docstring<br>(2) Ask AI for pytest cases, including edge cases<br>(3) Run coverage + intentionally break a bug to verify tests catch it | Claude Code / Aider | Test-writing phase |
| **Occasional** | Multi-file batch edits | (1) Claude writes a plan<br>(2) codex-delegate handles mechanical refactors<br>(3) Claude reviews the diff | Claude + codex-delegate | Refactors across 30+ files |
> 💡 **Starter habit**: run "daily AI pairing" and "test generation" for a month first, then add automated PR review.
### 3 Concrete Workflow Recipes
**1. AI Pair Programming (daily cadence)**
1. Start a feature → `git checkout -b feature/xxx`
2. Hand the task to Claude Code / Cursor — **make it write a plan first** (don't dive into code)
3. Review the plan, course-correct → only then approve coding
4. After it's done: run tests + lint → review the diff yourself (**don't blind-accept**)
5. Write the commit message yourself, or have AI draft and edit before committing
**2. Aider Git-Native Flow (closest "pair with AI" experience)**
```bash
# Inside the repo
aider --model anthropic/claude-sonnet-5
# Natural-language ask
> Add a timezone parameter to parse_date in utils.py, default UTC
# Aider edits + commits automatically. To roll back:
> /undo # undoes the last AI commit
```
**3. PR-time Claude code review (GitHub Action)**
`.github/workflows/claude-review.yml`:
```yaml
on:
pull_request:
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Run Claude review
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
# Use anthropics/claude-code-action or your own script
# Get git diff, run prompt, post results back to PR
```
Reference: official [`anthropics/claude-code-action`](https://github.com/anthropics/claude-code-action) GitHub Action.
## Common Pitfalls (Anti-patterns)
| ❌ Don't | ✅ Do instead |
|---|---|
| Let AI push directly to main | Always go through PR → review → merge |
| Blind-accept large refactor diffs | Break into < 50 LOC chunks, review each |
| Hand `.env` / API keys to the AI | Use your tool's exclusion mechanism — Cursor `.cursorignore` / Aider `.aiderignore` / Claude Code `permissions.deny` in `.claude/settings.json` |
| Let AI run shell freely against production code | Sandbox + permission whitelist |
| Take AI-generated tests at face value | Run coverage + intentionally break a unit to see if tests catch it |
| Discover wrong direction after many commits | **Plan-first** mode: review the plan before any coding |
## Tier Progression
Recommended progression:
| Tier | Tools | Best for | Learning cost |
|---|---|---|---|
| **Tier 0** | Cursor / Copilot / Claude.ai | IDE chat, autocomplete, no custom agents | 0 (if you can use an editor) |
| **Tier 1** | Claude Code / Cline / OpenCode + `CLAUDE.md` | CLI with file-system access, human-in-the-loop | 1-2 days |
| **Tier 2** | Custom Skills + MCP server | Packaging dev workflows as shared team skills | 1 week of setup |
| **Tier 3** | Auto-running agents in CI + production observability | [Stage 7](../stages/07-multi-agent-production.en.md) territory | Several weeks, governance required |
> **Most individual developers can stay at Tier 0-1**. **Validate ROI before going Tier 2+**: it is only worth the investment if the team is large, the workflows repeat often, and failures are hard to reverse.
## Other Branches Also Apply
Branches that overlap heavily with developers:
- **Doing ML research / writing papers** → [Researcher branch](./for-researcher.en.md)
- **Wire Notion / Linear / Atlassian / Postgres / Figma into your CLI** → [`resources/mcp-skills-catalog.en.md`](../resources/mcp-skills-catalog.en.md)
- **Author your own Skill / MCP server** → [Stage 5](../stages/05-claude-code-ecosystem.en.md) + [`resources/cookbook.en.md`](../resources/cookbook.en.md)
- **Schema design details** → [`resources/schema-design-cheatsheet.en.md`](../resources/schema-design-cheatsheet.en.md)
- **CLI from zero** → [Track A](../tracks/cli/A1-cli-intro.en.md) (A1 → A2 → A3)
## Community Note
Contributions especially welcome:
- IDE-specific config templates (Cursor `.cursorrules`, Claude Code `CLAUDE.md` for Python / Go / Rust, etc.)
- Language-specific Skills (Python / TypeScript / Rust / Go best-practice patterns)
- CI / pre-commit hook integration case studies
- **Multi-developer team governance** — sharing Skills across devs, permission design, cost tracking
See [CONTRIBUTING.md](../CONTRIBUTING.md).
branches/for-developer.md
+166
View File
@@ -0,0 +1,166 @@
# 開發者延伸路線（For Developers）
> **繁體中文** | [简体中文](./for-developer.zh-Hans.md) | [English](./for-developer.en.md)
> 🚀 **第一次裝 Claude Code / 寫 `CLAUDE.md` / `SKILL.md`？** 快速 setup 指南在 [`resources/setup-guide.md` D-E](../resources/setup-guide.md)。已經熟可以跳過。
> [← 回主路線 README](../README.md) · 走完 **Track A 的 A3** 或 **Track B 的 Stage 7** 後從這裡接續。把 agentic AI 應用到開發流程上。
## 使用情境（開發場景 × AI 怎麼幫）
下表把開發者一天會遇到的 7 個情境拆開——每個情境有不同的痛點，AI 工具也不同：
| 場景 | 你常遇到的痛點 | AI 能幫的部分 | 推薦工具（從輕到重） |
|---|---|---|---|
| **AI 結對程式設計** | 寫到一半忘 syntax / 想到 method 名 | 自動補完 + 改寫 + 解釋 | Cursor / Copilot → Claude Code |
| **多檔重構** | 改一個 class 怕漏改、跨檔 rename 易錯 | batch refactor、改 50 個檔保持風格一致 | Cursor → Claude Code → codex-delegate |
| **Code review（自己 PR）** | review 自己的 diff 看不出問題 | 找 bug / smell、檢查 edge case | Claude Code / cline → Continue（CI） |
| **寫 test** | TDD 一直忘加 case、coverage 不足 | 從 signature / spec 生 pytest | Claude Code + Aider |
| **Debug** | log 不夠、stack trace 看不懂 | 解 trace、生 hypothesis、跑 minimal repro | Claude Code |
| **Doc** | docstring / README 沒人寫、refactor 後過期 | 從 code 生 doc、PR 對應改 doc | Claude Code |
| **CI / 團隊自動化** | 重複手動跑 review、跨人風格不一 | GitHub Action 自動跑 review / lint | Claude Code Action + Continue |
> 💡 **個人 vs 團隊**：表中前 6 個是個人 daily workflow；最後 1 個（CI）是團隊規範。團隊規模 < 5 人時 CI 自動化的 ROI 不高、可先不上。
## 精選 Projects
> **CLI agent 比較**：7 個主流 CLI agent（Claude Code / Codex / OpenCode / Gemini CLI / goose / Aider / Hermes Agent）的並列比較見 [`resources/cli-agents-guide.md`](../resources/cli-agents-guide.md)。第一次接觸 CLI agent 想要 step-by-step 入門 → [`tracks/cli/A1-cli-intro.md`](../tracks/cli/A1-cli-intro.md)（Track A 第一站）。
>
> **MCP catalog**：要把 CLI 接到日常工具（GitHub、Linear、Atlassian、Postgres、Playwright、Figma 等）→ [`resources/mcp-skills-catalog.md`](../resources/mcp-skills-catalog.md)（65+ 個分類整理）。
>
> 本頁只列**跟開發者 workflow 直接相關**的工具入口。
### Coding Agents
#### [Cursor](https://www.cursor.com/) ⭐⭐⭐⭐⭐
編輯器整合的 AI 結對程式設計工具。在 AI 編輯器類工具中採用度高、可作為比較其他 IDE agent 的基準。
#### [Aider-AI/aider](https://github.com/Aider-AI/aider) ⭐⭐⭐⭐⭐
★ 44k+ · Apache-2.0 — git-aware 的 CLI pair-programmer。直接編輯你 repo 中的檔案，commit 都自動寫好。**「git-native AI 編輯流程」的開源範本**。模型不限。
#### [anthropics/claude-code](https://github.com/anthropics/claude-code) ⭐⭐⭐⭐⭐
★ 120k+ — Anthropic 官方的 agentic coding 助理。有 Skills + plugin 生態系。
#### [cline/cline](https://github.com/cline/cline) ⭐⭐⭐⭐⭐
★ 61k+ · Apache-2.0 — VS Code extension，autonomous in-IDE agent：tool use、browser、step-by-step approval。**VS Code 使用者要 IDE-native agentic dev 的好選項**。
#### [continuedev/continue](https://github.com/continuedev/continue) ⭐⭐⭐⭐
★ 33k+ · Apache-2.0 — source-controlled AI checks，可以在 CI 強制執行。代表「**團隊 / governance**」這條角度的 coding agent。
#### [OpenHands (前身為 OpenDevin)](https://github.com/All-Hands-AI/OpenHands) ⭐⭐⭐⭐
★ 72k+ · MIT — open source 的自主軟體開發 agent。設計上比 Aider / Claude Code 更激進——agent 自己跑 sandbox、自己 commit，適合「整個 issue 丟給它解」場景。
#### [block/goose](https://github.com/block/goose) ⭐⭐⭐⭐
★ 43k+ · Apache-2.0 — 開源、可擴充的 AI agent，超出純 code suggestion——能 install / execute / edit / test，搭配任何 LLM。同時支援多家 LLM provider 跟 MCP，提供 desktop app、CLI、API 三種介面。（repo 現指向 `aaif-goose/goose`。）
#### [RooCodeInc/Roo-Code](https://github.com/RooCodeInc/Roo-Code) ⭐⭐⭐⭐
★ 23k+ · Apache-2.0 — VS Code 的 coding agent，採用「**多種專業 mode**」的設計，跟 Cline 的單一 agent flow 不同。VS Code 使用者要 multi-mode 替代方案的選擇。
### Code Review
#### [obra/superpowers](https://github.com/obra/superpowers) ⭐⭐⭐⭐
20+ 個經過實戰驗證的 skill，包括 TDD 模式、debug、協作模式。設計 code-review skill 時的好參考。
### 推薦工具
- [**yamadashy/repomix**](https://github.com/yamadashy/repomix) ⭐⭐⭐⭐⭐ ★ 26k+ — **典型開發者用途：打包整個 codebase 給 reviewer / refactor agent**。輸出單一 AI-friendly 檔案（XML / Markdown / JSON），方便 Claude Code / Codex 做 code review / refactoring。技術細節（MCP server mode、tree-sitter 壓縮、secretlint 過濾）見官方 README。**Track A 很值得當 daily driver 的工具。**
## 必練流程（按使用頻率）
| 頻率 | 流程 | 怎麼做（≤ 3 步） | 推薦工具 | 適合誰 |
|---|---|---|---|---|
| **每天** | AI 結對寫 code | (1) 開 branch<br>(2) 任務丟給 Claude Code、**先 plan**（不寫 code）<br>(3) Review plan → approve → 寫 code → 自己 review diff | Claude Code / Cursor / Cline | 全開發者 |
| **每天** | Git-native AI 編輯 | (1) `aider`<br>(2) 自然語言請求<br>(3) review + commit / `/undo` | Aider | 想要乾淨 git 流程的人 |
| **Per PR** | 自動 code review | (1) `.github/workflows/claude-review.yml`<br>(2) 抓 git diff → 跑 prompt → post 回 PR<br>(3) human + AI 雙審 | Claude Code Action + Continue | 團隊 |
| **Per feature** | 測試生成 | (1) 給 function signature + docstring<br>(2) 請 AI 生 pytest case（含 edge case）<br>(3) 跑覆蓋率 + 故意改 bug 看 test 抓不抓得到 | Claude Code / Aider | 寫 test 階段 |
| **不定期** | 多檔批次修改 | (1) Claude 寫 plan<br>(2) codex-delegate 跑機械式 refactor<br>(3) Claude review diff | Claude + codex-delegate | refactor 30+ 檔的時候 |
> 💡 **新手起手式**：先做「每天 AI 結對」+「測試生成」兩條一個月、習慣後再上 PR 自動 review。
### 3 個具體 workflow recipe
**1. AI 結對程式設計（每日節奏）**
1. 開新 feature → `git checkout -b feature/xxx`
2. 把任務丟給 Claude Code / Cursor，**先讓它寫 plan**（不直接寫 code）
3. Review plan、修正方向 → 才 approve 寫 code
4. 寫完跑 tests + lint → 自己 review diff（**不要 blind accept**）
5. Commit message 自己寫或 prompt 生草稿後改
**2. Aider git-native 流程（最像「跟 AI pair」）**
```bash
# 進入 repo 後
aider --model anthropic/claude-sonnet-5
# 自然語言請求
> 幫我把 utils.py 的 parse_date 加上時區參數，預設 UTC
# Aider 會自動編輯 + commit。若不滿意：
> /undo # 退掉最後一次 AI commit
```
**3. PR 上的 Claude code review（GitHub Action）**
`.github/workflows/claude-review.yml`：
```yaml
on:
pull_request:
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Run Claude review
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
# 用 anthropics/claude-code-action 或自寫 script
# 抓 git diff、跑 prompt、結果 post 回 PR
```
參考 [`anthropics/claude-code-action`](https://github.com/anthropics/claude-code-action) 官方 GitHub Action。
## 常見踩坑（Anti-patterns）
| ❌ 不要 | ✅ 改成 |
|---|---|
| 讓 AI 直接 push 到 main | 永遠 PR → review → merge |
| Blind accept 大規模 refactor diff | 拆成 < 50 LOC 改動，逐個 review |
| 把 .env / API key 丟給 AI 看 | 用工具對應的排除機制：Cursor `.cursorignore` / Aider `.aiderignore` / Claude Code 用 `.claude/settings.json` 的 `permissions.deny` |
| 讓 AI 在 production code 自由跑 shell | sandbox 限制、permission whitelist |
| 用 AI 生 test 後不檢查 assertion | 跑覆蓋率 + 故意改一個 bug 看 test 抓不抓得到 |
| 跨多個 commit 才發現方向錯 | **plan-first** 模式：先 review plan 再寫 code |
## Tier 升級路徑
下表是建議的進階路徑：
| Tier | 工具 | 適合誰 | 學習成本 |
|---|---|---|---|
| **Tier 0** | Cursor / Copilot / Claude.ai | IDE 內 chat、autocomplete、不自己寫 agent | 0（會用編輯器就行） |
| **Tier 1** | Claude Code / Cline / OpenCode + `CLAUDE.md` | CLI 接 file system、human-in-the-loop | 1-2 天上手 |
| **Tier 2** | 自寫 Skills + MCP server | 把 dev workflow 包成 skill 給團隊共用 | 1 週 setup |
| **Tier 3** | CI 自動跑 agent + production observability | 進到 [Stage 7](../stages/07-multi-agent-production.md) 領域 | 數週、需 governance |
> **多數個人開發者可先停在 Tier 0-1**。**升級到 Tier 2+ 要先確認 ROI**——團隊夠大、流程夠重複、事故不可逆、才值得 invest。
## 也適用其他分支
開發者重疊度高的分支：
- **要做 ML 研究 / 寫 paper** → [研究員分支](./for-researcher.md)
- **接 Notion / Linear / Atlassian / Postgres / Figma** 等 dev tool → [`resources/mcp-skills-catalog.md`](../resources/mcp-skills-catalog.md)
- **要寫自己的 Skill / MCP server** → [Stage 5](../stages/05-claude-code-ecosystem.md) + [`resources/cookbook.md`](../resources/cookbook.md)
- **想看 schema 設計細節** → [`resources/schema-design-cheatsheet.md`](../resources/schema-design-cheatsheet.md)
- **CLI 從零開始** → [Track A](../tracks/cli/A1-cli-intro.md)（A1 → A2 → A3）
## 社群備註
特別歡迎以下貢獻：
- IDE-specific 設定範本（Cursor `.cursorrules`、Claude Code `CLAUDE.md` for Python / Go / Rust 等）
- 程式語言特化 skill（Python / TypeScript / Rust / Go 各自的 best practice）
- CI / pre-commit hook 整合 case study
- **跨多人團隊用 AI dev 的 governance pattern**——多 dev 共用 Skills、permission 設計、cost tracking
請見 [CONTRIBUTING.md](../CONTRIBUTING.md)。
branches/for-developer.zh-Hans.md
+166
View File
@@ -0,0 +1,166 @@
# 开发者延伸路线（For Developers）
> [繁體中文](./for-developer.md) | **简体中文** | [English](./for-developer.en.md)
> 🚀 **第一次装 Claude Code / 写 `CLAUDE.md` / `SKILL.md`？** 快速 setup 指南在 [`resources/setup-guide.zh-Hans.md` D-E](../resources/setup-guide.zh-Hans.md)。已经熟可以跳过。
> [← 回主路线 README](../README.zh-Hans.md) · 走完 **Track A 的 A3** 或 **Track B 的 Stage 7** 后从这里接续。把 agentic AI 应用到开发流程上。
## 使用场景（开发场景 × AI 怎么帮）
下表把开发者一天会遇到的 7 个场景拆开——每个场景有不同的痛点，AI 工具也不同：
| 场景 | 你常遇到的痛点 | AI 能帮的部分 | 推荐工具（从轻到重） |
|---|---|---|---|
| **AI 结对编程** | 写到一半忘 syntax / 想不到 method 名 | 自动补全 + 改写 + 解释 | Cursor / Copilot → Claude Code |
| **多文件重构** | 改一个 class 怕漏改、跨文件 rename 容易错 | batch refactor、改 50 个文件仍保持风格一致 | Cursor → Claude Code → codex-delegate |
| **Code review（自己 PR）** | review 自己的 diff 看不出问题 | 找 bug / smell、检查 edge case | Claude Code / Cline → Continue（CI） |
| **写 test** | TDD 常忘加 case、coverage 不足 | 从 signature / spec 生成 pytest | Claude Code + Aider |
| **Debug** | log 不够、stack trace 看不懂 | 解释 trace、生成 hypothesis、跑 minimal repro | Claude Code |
| **Doc** | docstring / README 没人写、refactor 后过期 | 从 code 生成 doc、PR 对应改 doc | Claude Code |
| **CI / 团队自动化** | 重复手动跑 review、跨人风格不一 | GitHub Action 自动跑 review / lint | Claude Code Action + Continue |
> 💡 **个人 vs 团队**：表中前 6 个是个人 daily workflow；最后 1 个（CI）是团队规范。团队规模 < 5 人时 CI 自动化的 ROI 不高，可以先不上。
## 精选 Projects
> **CLI agent 比较**：7 个主流 CLI agent（Claude Code / Codex / OpenCode / Gemini CLI / goose / Aider / Hermes Agent）的并列比较见 [`resources/cli-agents-guide.zh-Hans.md`](../resources/cli-agents-guide.zh-Hans.md)。第一次接触 CLI agent 想要 step-by-step 入门 → [`tracks/cli/A1-cli-intro.zh-Hans.md`](../tracks/cli/A1-cli-intro.zh-Hans.md)（Track A 第一站）。
>
> **MCP catalog**：要把 CLI 接到日常工具（GitHub、Linear、Atlassian、Postgres、Playwright、Figma 等）→ [`resources/mcp-skills-catalog.zh-Hans.md`](../resources/mcp-skills-catalog.zh-Hans.md)（65+ 个分类整理）。
>
> 本页只列**跟开发者 workflow 直接相关**的工具入口。
### Coding Agents
#### [Cursor](https://www.cursor.com/) ⭐⭐⭐⭐⭐
编辑器集成的 AI 结对编程工具。在 AI 编辑器类工具中采用度高，可作为比较其他 IDE agent 的基准。
#### [Aider-AI/aider](https://github.com/Aider-AI/aider) ⭐⭐⭐⭐⭐
★ 44k+ · Apache-2.0 — git-aware 的 CLI pair-programmer。直接编辑你 repo 中的文件，commit 都自动写好。**“git-native AI 编辑流程”的开源模板**。模型不限。
#### [anthropics/claude-code](https://github.com/anthropics/claude-code) ⭐⭐⭐⭐⭐
★ 120k+ — Anthropic 官方的 agentic coding 助理。有 Skills + plugin 生态系。
#### [cline/cline](https://github.com/cline/cline) ⭐⭐⭐⭐⭐
★ 61k+ · Apache-2.0 — VS Code extension，autonomous in-IDE agent：tool use、browser、step-by-step approval。**VS Code 用户想 IDE-native agentic dev 的好选项**。
#### [continuedev/continue](https://github.com/continuedev/continue) ⭐⭐⭐⭐
★ 33k+ · Apache-2.0 — source-controlled AI checks，可以在 CI 强制执行。代表“**团队 / governance**”这条角度的 coding agent。
#### [OpenHands (前身为 OpenDevin)](https://github.com/All-Hands-AI/OpenHands) ⭐⭐⭐⭐
★ 72k+ · MIT — open source 的自主软件开发 agent。设计上比 Aider / Claude Code 更激进——agent 自己跑 sandbox、自己 commit，适合“整个 issue 丢给它解”场景。
#### [block/goose](https://github.com/block/goose) ⭐⭐⭐⭐
★ 43k+ · Apache-2.0 — 开源、可扩展的 AI agent，超出纯 code suggestion——能 install / execute / edit / test，搭配任何 LLM。同时支持多家 LLM provider 跟 MCP，提供 desktop app、CLI、API 三种接口。（repo 现指向 `aaif-goose/goose`。）
#### [RooCodeInc/Roo-Code](https://github.com/RooCodeInc/Roo-Code) ⭐⭐⭐⭐
★ 23k+ · Apache-2.0 — VS Code 的 coding agent，采用“**多种专业模式**”的设计，跟 Cline 的单一 agent flow 不同。VS Code 用户想 multi-mode 替代方案的选择。
### Code Review
#### [obra/superpowers](https://github.com/obra/superpowers) ⭐⭐⭐⭐
20+ 个经过实战验证的 skill，包括 TDD 模式、debug、协作模式。设计 code-review skill 时的好参考。
### 推荐工具
- [**yamadashy/repomix**](https://github.com/yamadashy/repomix) ⭐⭐⭐⭐⭐ ★ 26k+ — **典型开发者用途：打包整个 codebase 给 reviewer / refactor agent**。输出单个 AI-friendly 文件（XML / Markdown / JSON），方便 Claude Code / Codex 做 code review / refactoring。技术细节（MCP server mode、tree-sitter 压缩、secretlint 过滤）见官方 README。**Track A 的必备 daily-driver 工具。**
## 必练流程（按使用频率）
| 频率 | 流程 | 怎么做（≤ 3 步） | 推荐工具 | 适合谁 |
|---|---|---|---|---|
| **每天** | AI 结对写 code | (1) 开 branch<br>(2) 任务丢给 Claude Code、**先 plan**（不写 code）<br>(3) Review plan → approve → 写 code → 自己 review diff | Claude Code / Cursor / Cline | 全开发者 |
| **每天** | Git-native AI 编辑 | (1) `aider`<br>(2) 自然语言请求<br>(3) review + commit / `/undo` | Aider | 想要干净 git 流程的人 |
| **Per PR** | 自动 code review | (1) `.github/workflows/claude-review.yml`<br>(2) 抓 git diff → 跑 prompt → post 回 PR<br>(3) human + AI 双审 | Claude Code Action + Continue | 团队 |
| **Per feature** | 测试生成 | (1) 给 function signature + docstring<br>(2) 请 AI 生成 pytest case（含 edge case）<br>(3) 跑覆盖率 + 故意改 bug 看 test 抓不抓得到 | Claude Code / Aider | 写 test 阶段 |
| **不定期** | 多文件批量修改 | (1) Claude 写 plan<br>(2) codex-delegate 跑机械式 refactor<br>(3) Claude review diff | Claude + codex-delegate | refactor 30+ 文件的时候 |
> 💡 **新手起手式**：先做“每天 AI 结对”+“测试生成”两条一个月，习惯后再上 PR 自动 review。
### 3 个具体 workflow recipe
**1. AI 结对编程（每日节奏）**
1. 开新 feature → `git checkout -b feature/xxx`
2. 把任务丢给 Claude Code / Cursor，**先让它写 plan**（不直接写 code）
3. Review plan、修正方向 → 才 approve 写 code
4. 写完跑 tests + lint → 自己 review diff（**不要 blind accept**）
5. Commit message 自己写或 prompt 生草稿后改
**2. Aider git-native 流程（最像“跟 AI pair”）**
```bash
# 进入 repo 后
aider --model anthropic/claude-sonnet-5
# 自然语言请求
> 帮我把 utils.py 的 parse_date 加上时区参数，默认 UTC
# Aider 会自动编辑 + commit。若不满意：
> /undo # 退掉最后一次 AI commit
```
**3. PR 上的 Claude code review（GitHub Action）**
`.github/workflows/claude-review.yml`：
```yaml
on:
pull_request:
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Run Claude review
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
# 用 anthropics/claude-code-action 或自写 script
# 抓 git diff、跑 prompt、结果 post 回 PR
```
参考 [`anthropics/claude-code-action`](https://github.com/anthropics/claude-code-action) 官方 GitHub Action。
## 常见踩坑（Anti-patterns）
| ❌ 不要 | ✅ 改成 |
|---|---|
| 让 AI 直接 push 到 main | 永远 PR → review → merge |
| Blind accept 大规模 refactor diff | 拆成 < 50 LOC 改动，逐个 review |
| 把 .env / API key 丢给 AI 看 | 用工具对应的排除机制：Cursor `.cursorignore` / Aider `.aiderignore` / Claude Code 用 `.claude/settings.json` 的 `permissions.deny` |
| 让 AI 在 production code 自由跑 shell | sandbox 限制、permission whitelist |
| 用 AI 生 test 后不检查 assertion | 跑覆盖率 + 故意改一个 bug 看 test 抓不抓得到 |
| 跨多个 commit 才发现方向错 | **plan-first** 模式：先 review plan 再写 code |
## Tier 升级路径
下表是建议的进阶路径：
| Tier | 工具 | 适合谁 | 学习成本 |
|---|---|---|---|
| **Tier 0** | Cursor / Copilot / Claude.ai | IDE 内 chat、autocomplete、不自己写 agent | 0（会用编辑器就行） |
| **Tier 1** | Claude Code / Cline / OpenCode + `CLAUDE.md` | CLI 接 file system、human-in-the-loop | 1-2 天上手 |
| **Tier 2** | 自写 Skills + MCP server | 把 dev workflow 包成 skill 给团队共用 | 1 周 setup |
| **Tier 3** | CI 自动跑 agent + production observability | 进到 [Stage 7](../stages/07-multi-agent-production.zh-Hans.md) 领域 | 数周、需 governance |
> **多数个人开发者可先停在 Tier 0-1**。**升级到 Tier 2+ 要先确认 ROI**——团队够大、流程够重复、事故不可逆，才值得 invest。
## 也适用其他分支
开发者重叠度高的分支：
- **要做 ML 研究 / 写 paper** → [研究员分支](./for-researcher.zh-Hans.md)
- **接 Notion / Linear / Atlassian / Postgres / Figma** 等 dev tool → [`resources/mcp-skills-catalog.zh-Hans.md`](../resources/mcp-skills-catalog.zh-Hans.md)
- **要写自己的 Skill / MCP server** → [Stage 5](../stages/05-claude-code-ecosystem.zh-Hans.md) + [`resources/cookbook.zh-Hans.md`](../resources/cookbook.zh-Hans.md)
- **想看 schema 设计细节** → [`resources/schema-design-cheatsheet.zh-Hans.md`](../resources/schema-design-cheatsheet.zh-Hans.md)
- **CLI 从零开始** → [Track A](../tracks/cli/A1-cli-intro.zh-Hans.md)（A1 → A2 → A3）
## 社群备注
特别欢迎以下贡献：
- IDE-specific 设置范本（Cursor `.cursorrules`、Claude Code `CLAUDE.md` for Python / Go / Rust 等）
- 编程语言特化 skill（Python / TypeScript / Rust / Go 各自的 best practice）
- CI / pre-commit hook 集成 case study
- **跨多人团队用 AI dev 的 governance pattern**——多 dev 共用 Skills、permission 设计、cost tracking
请见 [CONTRIBUTING.md](../CONTRIBUTING.md)。
branches/for-everyday-users.en.md
+176
View File
@@ -0,0 +1,176 @@
# Extension Path: For Everyday Users
> [繁體中文](./for-everyday-users.md) | [简体中文](./for-everyday-users.zh-Hans.md) | **English**
> 🚀 **Everyday users can start directly at Tier 0** (web / mobile apps), **without any setup**. Only read [`resources/setup-guide.en.md` A-C](../resources/setup-guide.en.md) (about 30 minutes from zero) when you want to run a local LLM (Tier 3) or use CLI automation (Tier 2).
> [← Back to main path README](../README.en.md) · You **don't have to walk the full main path** to start here — this branch is for people who **just want to USE AI, not build agents**.
## Use Cases (Life Scenarios × How AI Helps)
The table below splits everyday AI use into 7 common scenarios. Most of them are fully covered by web apps at Tier 0:
| Scenario | Pain point | How AI helps | Recommended tools |
|---|---|---|---|
| **Writing email / cover letters** | Getting stuck on how to start | Drafting + tone edits + version comparison | Claude.ai / ChatGPT |
| **Learning new skills** | Materials feel formal; nobody is there to ask | Personalized tutoring, interruptible at any time | Claude.ai / ChatGPT |
| **Language practice** | No conversation partner; unclear grammar mistakes | Voice conversation and instant correction | ChatGPT Voice / Gemini |
| **Research / comparison** | Hard to know which source to trust | Multi-source search with citations | Perplexity |
| **Organizing life workflows** | Recipes / trips / todo lists are scattered | Consolidation + structure | Claude.ai / ChatGPT |
| **Batch file cleanup** | 100 PDFs / images with no clear grouping | Rename + classify + summarize | Claude Desktop / Claude Code |
| **Privacy-sensitive chat** | Medical / legal / financial notes should not go to the cloud | Run a local LLM | Ollama + qwen2.5 |
> 💡 **Do not rush upgrades**: the first 5 scenarios can stay at Tier 0 (web). You only need Tier 1-3 when you repeat the same flow often or data absolutely cannot leave your machine.
## Where to Start: 4 Tiers by "How Hands-On Are You?"
```
Tier 0: Web / Mobile App (recommended starting point)
↓
Tier 1: Desktop App (upgrade when you need to handle local files)
↓
Tier 2: CLI Agent (willing to learn a bit of command line; automate daily flows)
↓
Tier 3: Local LLM (privacy-sensitive, cost-sensitive, want offline)
```
**Most people stay at Tier 0 / Tier 1** — Tiers 2-3 are for special needs or learners.
---
## 🎯 Curated Projects
### Tier 0 — Web / Mobile App ⭐ Entry-level
#### [Claude.ai](https://claude.ai) ⭐⭐⭐⭐⭐
Anthropic's official interface. Best for long-form writing, in-depth discussion, complex questions — answer style is more restrained, less hallucination-prone.
#### [ChatGPT](https://chatgpt.com) ⭐⭐⭐⭐⭐
OpenAI's official interface. Largest ecosystem (GPTs, Custom Instructions, Voice mode). The standard general-purpose pick.
#### [Gemini](https://gemini.google.com) ⭐⭐⭐⭐
Google's offering. Long context — enough to read very long documents, roughly a thick book — is particularly useful for dropping in a whole PDF and asking questions; still check whether citations and summaries are correct. Integrated with Google services (Gmail, Docs).
#### [Perplexity](https://perplexity.ai) ⭐⭐⭐⭐
Search engine × LLM — every answer cites sources. Better than ChatGPT for "needs current info" scenarios.
---
### Tier 1 — Desktop App
#### [Claude Desktop](https://claude.ai/download) ⭐⭐⭐⭐⭐
Beyond the web version: drag files in, read local files, retain long conversation context. **Also the gateway to AI-tool integration (MCP)** — you can connect Slack / Gmail / Calendar and operate them directly inside Claude.
#### [ChatGPT Desktop](https://openai.com/chatgpt/desktop) ⭐⭐⭐⭐
Desktop version of ChatGPT. Ask questions about screenshots, voice conversation, integrate with other apps.
---
### Tier 2 — CLI Agents (advanced users willing to learn the command line)
> These tools are positioned for developers but **everyday users can use them too** — e.g. batch-rename files, organize the Downloads folder, auto-write weekly reviews, summarize PDFs into Markdown.
>
> Want a detailed comparison? See [`resources/cli-agents-guide.en.md`](../resources/cli-agents-guide.en.md) — six major CLI agents side by side, recommendations by use case, common pitfalls, real-world setups.
>
> Want step-by-step onboarding? See [`tracks/cli/A1-cli-intro.en.md`](../tracks/cli/A1-cli-intro.en.md) — Track A first stop, from install to your first task.
>
> Want to wire your CLI agent to Notion / Obsidian / Excel / Google docs / etc.? See [`resources/mcp-skills-catalog.en.md`](../resources/mcp-skills-catalog.en.md) — 65+ MCP servers / Skills grouped by use case.
#### [anthropics/claude-code](https://github.com/anthropics/claude-code) ⭐⭐⭐⭐⭐
★ 120k+ — Anthropic's official CLI agent. Reads/writes files, runs commands, handles multi-step tasks. **The most beginner-friendly CLI tool for everyday users.**
#### [openai/codex](https://github.com/openai/codex) ⭐⭐⭐⭐⭐
| Field | Value |
|---|---|
| Stars | ★ 80k+ |
| License | Apache-2.0 |
**What it teaches**: OpenAI's terminal agent — it can help organize files, batch-process text, and run multi-step tasks from the command line; coding is only one use case. Same category as Claude Code, but uses OpenAI models.
**Best for**: People who already subscribe to ChatGPT Plus / Pro and want to use the same account in the terminal.
#### [sst/opencode](https://github.com/sst/opencode) ⭐⭐⭐⭐⭐
| Field | Value |
|---|---|
| Stars | ★ 155k+ |
| License | MIT |
**What it teaches**: Open-source coding agent **not tied to any specific LLM provider** — use Claude, GPT, Gemini, or local Ollama, your choice. Community-maintained, fast iteration.
**Best for**: Self-hosters; people who don't want vendor lock-in; anyone switching between multiple LLMs.
#### [google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli) ⭐⭐⭐⭐
| Field | Value |
|---|---|
| Stars | ★ 103k+ |
| License | Apache-2.0 |
**What it teaches**: Google's official Gemini CLI agent. Brings Gemini's long context and Google ecosystem integration to the terminal.
**Best for**: Heavy users of the Google ecosystem (Gmail, Drive, Docs).
---
### Tier 3 — Local LLM (privacy / offline / cost)
#### [Ollama](https://github.com/ollama/ollama) ⭐⭐⭐⭐⭐
★ 170k+ — One command to run a local LLM. Use this when privacy-sensitive data (medical records, contracts, family conversations) shouldn't leave your machine. See [Stage 1 — Local LLM](../stages/01-llm-basics.en.md).
#### [LM Studio](https://lmstudio.ai/)
Closed-source but the most beginner-friendly option — drag-and-drop UI, no command line. Mac / Windows / Linux.
---
### Prompt Library
#### [f/awesome-chatgpt-prompts](https://github.com/f/awesome-chatgpt-prompts) ⭐⭐⭐⭐
★ 161k+ — Community-maintained prompt megacatalog. "Act as a translator / résumé consultant / chef..." in hundreds of roles. **When stuck on how to start, browse here.**
---
## Required Reading
1. [**Anthropic — How to write effective prompts**](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview) — readable without code
2. [**OpenAI — Prompting Guide**](https://platform.openai.com/docs/guides/prompt-engineering) — the parallel official doc
If you want to go deeper, see [Stage 2 — Prompt Engineering](../stages/02-prompt-engineering.en.md), which has a more systematic treatment.
## Workflows You Can Build (by frequency)
Use these 5 templates as starting points and adapt them to your own context:
| Frequency | Workflow | Steps (≤3) | Recommended tools |
|---|---|---|---|
| **Daily** | Email triage | (1) Paste pending emails into Claude in the morning<br>(2) Ask it to classify "reply now / today / this week / skip"<br>(3) Draft replies for your review | Claude.ai / ChatGPT |
| **Daily** | Speaking practice | (1) Open ChatGPT Voice<br>(2) Practice English / Japanese conversation<br>(3) Ask it to flag grammar mistakes | ChatGPT Voice / Gemini |
| **Weekly** | Weekly journal | (1) Tell Claude what you did this week<br>(2) Ask for a journal + next week's priorities<br>(3) Save it to Obsidian / Notion | Claude.ai |
| **Occasional** | Batch file cleanup | (1) Run Claude Code in your Downloads folder<br>(2) Rename by date + topic<br>(3) Sort into subfolders | Claude Code |
| **Privacy scenario** | Local medical / legal / financial notes | (1) Run qwen2.5:7b in Ollama<br>(2) Organize personal notes without sending data to the cloud<br>(3) ⚠️ It protects **privacy**, not **correctness**: specific diagnoses / legal judgments / investment decisions still require professionals | Ollama + qwen2.5 |
> 💡 **Starter habit**: run "daily email triage" and "speaking practice" for a month first, then add other workflows.
## Tier Recommendations for Everyday Users
Recommended progression:
| Tier | Tools | Best for | Learning cost |
|---|---|---|---|
| **Tier 0** | Claude.ai / ChatGPT / Gemini / Perplexity (web) | 90% of scenarios: no install, no payment required | 0 (if you can use a browser) |
| **Tier 1** | Claude Desktop / ChatGPT Desktop + MCP | Local files, retained conversation history, Gmail / Notion integrations | 30 minutes |
| **Tier 2** | Claude Code / opencode (CLI) | Repeated automation needs, such as doing the same task 100 times daily | 1-2 days |
| **Tier 3** | Ollama local LLM | Privacy-sensitive data that cannot go to the cloud, API-cost sensitivity, offline use | Half a day |
> **Do not let anyone push you to upgrade prematurely**. Tier 0 is enough for most people. Tiers 2-3 are tools, not status symbols.
## Community Notes
Contributions especially welcome:
- Domain-specific prompt templates (cooking, fitness, language learning)
- Chinese-friendly chat tools (Chinese LLMs, localized wrappers)
- Privacy / safety best practices (what data is OK to send / what isn't)
See [CONTRIBUTING.md](../CONTRIBUTING.md).
branches/for-everyday-users.md
+179
View File
@@ -0,0 +1,179 @@
# 日常使用者延伸路線（For Everyday Users）
> **繁體中文** | [简体中文](./for-everyday-users.zh-Hans.md) | [English](./for-everyday-users.en.md)
> 🚀 **日常使用者可直接從 Tier 0 開始**（網頁 / 手機 App）、**不需要任何 setup**。只有當你想跑本地 LLM（Tier 3）或用 CLI 自動化（Tier 2）時、才需要看 [`resources/setup-guide.md` A-C](../resources/setup-guide.md)（30 分鐘從零裝好）。
> [← 回主路線 README](../README.md) · 你**不一定要走完整條主幹**才能從這裡開始——這條分支是給「**只想 USE AI、不一定要 BUILD agent**」的人。
## 使用情境（生活場景 × AI 怎麼幫）
下表把日常使用者一天會遇到的 7 個情境拆開——多數場景在網頁版（Tier 0）就能搞定：
| 場景 | 你常遇到的痛點 | AI 能幫的部分 | 推薦工具 |
|---|---|---|---|
| **寫 email / cover letter** | 卡在「該怎麼開頭」 | 起草 + 改語氣 + 多版本對比 | Claude.ai / ChatGPT |
| **學新技能** | 教材太正式、沒人問問題 | 個人化 tutor、可隨時打斷問 | Claude.ai / ChatGPT |
| **練語言** | 沒對話對象、不知文法錯哪 | 語音對話、即時糾錯 | ChatGPT Voice / Gemini |
| **查資料 / 比較** | 不知該信哪個來源 | 多源搜尋 + 附引用 | Perplexity |
| **整理生活流程** | 食譜 / 行程 / 待辦清單散落 | 整合 + 結構化 | Claude.ai / ChatGPT |
| **批次整理檔案** | 100 個 PDF / 圖片不知怎麼分 | 重命名 + 分類 + 摘要 | Claude Desktop / Claude Code |
| **隱私敏感 chat** | 醫療 / 法律 / 財務筆記不想送雲 | 本地跑 LLM | Ollama + qwen2.5 |
> 💡 **不要被催著升級**：前 5 個場景都可以停在 Tier 0（網頁版）。只有要「重複跑同一個流程」或「資料絕對不能送雲」才需要 Tier 1-3。
## 起步：你應該從哪一層進來？
按「**動手願意度**」分 4 層，從低到高：
```
Tier 0：網頁 / 手機 App（推薦從這裡開始）
↓
Tier 1：Desktop App（要處理本機檔案再升級）
↓
Tier 2：CLI Agent（願意學一點命令列，能自動化日常流程）
↓
Tier 3：本地 LLM（隱私敏感、API 費用敏感、想 offline）
```
**多數人停在 Tier 0 / Tier 1 就夠用了**——Tier 2-3 是給有特殊需求或想學的人。
---
## 🎯 精選 Projects
### Tier 0 — 網頁 / 手機 App ⭐ 入門
#### [Claude.ai](https://claude.ai) ⭐⭐⭐⭐⭐
Anthropic 官方介面。長文章、深度討論、複雜問題很適合用——回答風格較收斂、不太瞎掰。
#### [ChatGPT](https://chatgpt.com) ⭐⭐⭐⭐⭐
OpenAI 官方介面。生態最廣（GPTs、Custom Instructions、Voice mode）。一般用途的標準選擇。
#### [Gemini](https://gemini.google.com) ⭐⭐⭐⭐
Google 出品。長 context（一次能讀很長文件、約一本厚書的量）特別適合丟整本 PDF 進去問問題；仍要自己檢查引用與摘要是否正確。整合 Google 服務（Gmail、Docs）。
#### [Perplexity](https://perplexity.ai) ⭐⭐⭐⭐
搜尋引擎 × LLM——每個答案都附引用來源。比 ChatGPT 適合「需要查最新資訊」的場景。
---
### Tier 1 — Desktop App
#### [Claude Desktop](https://claude.ai/download) ⭐⭐⭐⭐⭐
比網頁版多了：拖檔案進去、本機檔案讀取、保留長期對話脈絡。**也是進入 AI 工具整合生態（MCP）的入口**——可以接 Slack / Gmail / 行事曆，讓你在 Claude 裡直接操作這些服務。
#### [ChatGPT Desktop](https://openai.com/chatgpt/desktop) ⭐⭐⭐⭐
ChatGPT 桌面版。可以對螢幕截圖問問題、語音對話、跟其他 App 整合。
---
### Tier 2 — CLI Agent（願意學命令列的進階使用者）
> 這些工具雖然定位給開發者，但**日常使用者也能用**——例如批次重新命名檔案、整理下載資料夾、自動寫每週回顧、把 PDF 摘要存成 Markdown。
>
> 想看詳細比較？見 [`resources/cli-agents-guide.md`](../resources/cli-agents-guide.md)（7 個主流 CLI agent 並列、依 use case 推薦、常見坑、實用搭配）。
>
> 想要 step-by-step 上手？見 [`tracks/cli/A1-cli-intro.md`](../tracks/cli/A1-cli-intro.md)（Track A 第一站，從安裝到第一個任務）。
>
> 想把 CLI agent 接到你的 Notion / Obsidian / Excel / Google 文件等日常工具？見 [`resources/mcp-skills-catalog.md`](../resources/mcp-skills-catalog.md)（按分類整理 65+ 個 MCP server / Skill）。
#### [anthropics/claude-code](https://github.com/anthropics/claude-code) ⭐⭐⭐⭐⭐
★ 120k+ — Anthropic 官方的 CLI agent。能讀寫檔案、執行指令、做多步驟任務。**日常使用者最容易上手的 CLI 工具**。
#### [openai/codex](https://github.com/openai/codex) ⭐⭐⭐⭐⭐
| 欄位 | 內容 |
|---|---|
| Stars | ★ 80k+ |
| License | Apache-2.0 |
**教什麼**：OpenAI 出品的終端機 agent——可以在命令列幫你整理檔案、批次處理文字、執行多步驟任務；寫程式只是其中一種用途。跟 Claude Code 同類、但用的是 OpenAI 的模型。
**適合誰**：已經訂 ChatGPT Plus / Pro，想在終端機用同一個帳號做事的人。
#### [sst/opencode](https://github.com/sst/opencode) ⭐⭐⭐⭐⭐
| 欄位 | 內容 |
|---|---|
| Stars | ★ 155k+ |
| License | MIT |
**教什麼**：開源版的 coding agent，**不綁特定 LLM provider**——可以用 Claude、GPT、Gemini、本地 Ollama 任何一個。社群維護、迭代速度快。
**適合誰**：想 self-host、不想被 API provider 綁住，或要在多個 LLM 之間切換的人。
#### [google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli) ⭐⭐⭐⭐
| 欄位 | 內容 |
|---|---|
| Stars | ★ 103k+ |
| License | Apache-2.0 |
**教什麼**：Google 官方的 Gemini CLI agent。把 Gemini 的長 context 跟 Google 生態整合到終端機。
**適合誰**：Google 生態的重度使用者（Gmail、Drive、Docs）。
---
### Tier 3 — 本地 LLM（隱私 / 離線 / 省錢）
#### [Ollama](https://github.com/ollama/ollama) ⭐⭐⭐⭐⭐
★ 170k+ — 一行指令跑本地 LLM。隱私敏感資料（病歷、合約、家人對話）不適合送去雲端時用這個。詳見 [Stage 1 — Local LLM 執行](../stages/01-llm-basics.md)。
#### [LM Studio](https://lmstudio.ai/)
非開源但對非開發者最友善——拖拉介面、不用 command line。Mac / Windows / Linux 都有。
---
### Prompt 素材庫
#### [f/awesome-chatgpt-prompts](https://github.com/f/awesome-chatgpt-prompts) ⭐⭐⭐⭐
★ 161k+ — 社群維護的 prompt 大全。「act as 翻譯家 / 履歷顧問 / 廚師...」幾百種角色。**不知道怎麼開頭時從這裡找靈感**。
---
## 必修閱讀
1. [**Anthropic — How to write effective prompts**](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview) — 不用程式碼也能讀的 prompt 寫法
2. [**OpenAI — Prompting Guide**](https://platform.openai.com/docs/guides/prompt-engineering) — 對位的官方文件
3. [**ChatGPT 怎麼用得最好（中文）**](https://www.runoob.com/) — 各家中文部落格的整理（runoob 等等）
如果有興趣再深入，看 [Stage 2 — Prompt 設計](../stages/02-prompt-engineering.md)，那邊有正式系統性教學。
## 可以建的流程（按使用頻率）
下表 5 條是模板、配合你自己的場景調整：
| 頻率 | 流程 | 怎麼做（≤ 3 步） | 推薦工具 |
|---|---|---|---|
| **每天** | Email 分流 | (1) 早上把待回信件貼進 Claude<br>(2) 請它分類「立即回 / 今天回 / 這週回 / 不用回」<br>(3) 草擬回信讓你 review | Claude.ai / ChatGPT |
| **每天** | 練語言（口說） | (1) 打開 ChatGPT Voice 模式<br>(2) 對話練英 / 日<br>(3) 請它指出文法錯誤 | ChatGPT Voice / Gemini |
| **每週** | 週記整理 | (1) 跟 Claude 講這週做什麼<br>(2) 請它整理成週記 + 下週重點<br>(3) 存到 Obsidian / Notion | Claude.ai |
| **不定期** | 批次整理檔案 | (1) Claude Code 進 Downloads 資料夾<br>(2) 按日期 + 主題重命名<br>(3) 自動分到子資料夾 | Claude Code |
| **隱私場景** | 本地醫療 / 法律 / 財務筆記 | (1) Ollama 跑 qwen2.5:7b<br>(2) 整理個人筆記、資料不送雲<br>(3) ⚠️ 保護的是**隱私**、不是**正確性**——具體診斷 / 法律判斷 / 投資決策仍需專業人士 | Ollama + qwen2.5 |
> 💡 **新手起手式**：先把「每天 Email 分流」+「練語言」做一個月、習慣 AI 在日常的位置、再加其他流程。
## 給日常使用者的層級建議
下表是建議的進階路徑：
| Tier | 工具 | 適合誰 | 學習成本 |
|---|---|---|---|
| **Tier 0** | Claude.ai / ChatGPT / Gemini / Perplexity（網頁版） | 90% 的場景都在這裡——免安裝、免付費 | 0（會用瀏覽器就行） |
| **Tier 1** | Claude Desktop / ChatGPT Desktop + MCP | 要處理本機檔案、保留對話歷史、接 Gmail / Notion | 半小時裝好 |
| **Tier 2** | Claude Code / opencode（CLI） | 有重複自動化需求（每天做同樣的事 100 次） | 1-2 天上手 |
| **Tier 3** | Ollama 本地 LLM | 隱私敏感資料不能送雲、API 費用敏感、想 offline | 半天設定 |
> **不要被人催著升級**——多數人 Tier 0 就夠用了。Tier 2-3 是工具、不是身份地位。
## 社群備註
這條分支也歡迎社群貢獻：
- 推薦特定領域的 prompt template（料理、運動、學語言）
- 中文友善的 chat tools（國產 LLM、本地化 wrapper）
- 隱私 / 安全相關的最佳實踐（什麼資料能送 / 不能送）
詳見 [CONTRIBUTING.md](../CONTRIBUTING.md)。
branches/for-everyday-users.zh-Hans.md
+179
View File
@@ -0,0 +1,179 @@
# 日常用户延伸路线（For Everyday Users）
> [繁體中文](./for-everyday-users.md) | **简体中文** | [English](./for-everyday-users.en.md)
> 🚀 **日常用户可直接从 Tier 0 开始**（网页 / 手机 App）、**不需要任何 setup**。只有当你想跑本地 LLM（Tier 3）或用 CLI 自动化（Tier 2）时，才需要看 [`resources/setup-guide.zh-Hans.md` A-C](../resources/setup-guide.zh-Hans.md)（30 分钟从零装好）。
> [← 回主路线 README](../README.zh-Hans.md) · 你**不一定要走完主干**才能从这里开始——这条分支是给“**只想 USE AI、不一定要 BUILD agent**”的人。
## 使用场景（生活场景 × AI 怎么帮）
下表把日常用户一天会遇到的 7 个场景拆开——多数场景在网页版（Tier 0）就能搞定：
| 场景 | 你常遇到的痛点 | AI 能帮的部分 | 推荐工具 |
|---|---|---|---|
| **写 email / cover letter** | 卡在“该怎么开头” | 起草 + 改语气 + 多版本对比 | Claude.ai / ChatGPT |
| **学新技能** | 教材太正式、没人问问题 | 个性化 tutor、可随时打断问 | Claude.ai / ChatGPT |
| **练语言** | 没对话对象、不知道语法错哪 | 语音对话、即时纠错 | ChatGPT Voice / Gemini |
| **查资料 / 比较** | 不知道该信哪个来源 | 多源搜索 + 附引用 | Perplexity |
| **整理生活流程** | 食谱 / 行程 / 待办清单散落 | 整合 + 结构化 | Claude.ai / ChatGPT |
| **批量整理文件** | 100 个 PDF / 图片不知道怎么分 | 重命名 + 分类 + 摘要 | Claude Desktop / Claude Code |
| **隐私敏感 chat** | 医疗 / 法律 / 财务笔记不想送云 | 本地跑 LLM | Ollama + qwen2.5 |
> 💡 **不要被催着升级**：前 5 个场景都可以停在 Tier 0（网页版）。只有要“重复跑同一个流程”或“数据绝对不能送云”才需要 Tier 1-3。
## 起步：你应该从哪一层进入？
按“**动手意愿**”分 4 层，从低到高：
```
Tier 0：网页 / 手机 App（推荐从这里开始）
↓
Tier 1：Desktop App（要处理本地文件再升级）
↓
Tier 2：CLI Agent（愿意学一点命令行，能自动化日常流程）
↓
Tier 3：本地 LLM（隐私敏感、API 费用敏感、想 offline）
```
**多数人停在 Tier 0 / Tier 1 就够用了**——Tier 2-3 是给有特殊需求或想学的人。
---
## 🎯 精选 Projects
### Tier 0 — 网页 / 手机 App ⭐ 入门
#### [Claude.ai](https://claude.ai) ⭐⭐⭐⭐⭐
Anthropic 官方界面。长文章、深度讨论、复杂问题很适合用——回答风格较收敛、不太瞎掰。
#### [ChatGPT](https://chatgpt.com) ⭐⭐⭐⭐⭐
OpenAI 官方界面。生态最广（GPTs、Custom Instructions、Voice mode）。一般用途的标准选择。
#### [Gemini](https://gemini.google.com) ⭐⭐⭐⭐
Google 出品。长 context（一次能读很长文件、约一本厚书的量）特别适合丢整本 PDF 进去问问题；仍要自己检查引用与摘要是否正确。集成 Google 服务（Gmail、Docs）。
#### [Perplexity](https://perplexity.ai) ⭐⭐⭐⭐
搜索引擎 × LLM——每个答案都附引用来源。比 ChatGPT 适合“需要查最新信息”的场景。
---
### Tier 1 — Desktop App
#### [Claude Desktop](https://claude.ai/download) ⭐⭐⭐⭐⭐
比网页版多了：拖文件进去、本地文件读取、保留长期对话脉络。**也是进入 AI 工具整合生态（MCP）的入口**——可以接 Slack / Gmail / 日历，让你在 Claude 里直接操作这些服务。
#### [ChatGPT Desktop](https://openai.com/chatgpt/desktop) ⭐⭐⭐⭐
ChatGPT 桌面版。可以对屏幕截图问问题、语音对话、跟其他 App 集成。
---
### Tier 2 — CLI Agent（愿意学命令行的进阶用户）
> 这些工具虽然定位给开发者，但**日常用户也能用**——例如批量重命名文件、整理下载文件夹、自动写每周回顾、把 PDF 摘要存成 Markdown。
>
> 想看详细比较？见 [`resources/cli-agents-guide.zh-Hans.md`](../resources/cli-agents-guide.zh-Hans.md)（7 个主流 CLI agent 并列、依 use case 推荐、常见坑、实用搭配）。
>
> 想要 step-by-step 上手？见 [`tracks/cli/A1-cli-intro.zh-Hans.md`](../tracks/cli/A1-cli-intro.zh-Hans.md)（Track A 第一站，从安装到第一个任务）。
>
> 想把 CLI agent 接到你的 Notion / Obsidian / Excel / Google 文件等日常工具？见 [`resources/mcp-skills-catalog.zh-Hans.md`](../resources/mcp-skills-catalog.zh-Hans.md)（按分类整理 65+ 个 MCP server / Skill）。
#### [anthropics/claude-code](https://github.com/anthropics/claude-code) ⭐⭐⭐⭐⭐
★ 120k+ — Anthropic 官方的 CLI agent。能读写文件、执行指令、做多步骤任务。**日常用户最容易上手的 CLI 工具**。
#### [openai/codex](https://github.com/openai/codex) ⭐⭐⭐⭐⭐
| 栏位 | 内容 |
|---|---|
| Stars | ★ 80k+ |
| License | Apache-2.0 |
**教什么**：OpenAI 出品的终端机 agent——可以在命令行帮你整理文件、批量处理文字、执行多步骤任务；写程序只是其中一种用途。跟 Claude Code 同类，但用的是 OpenAI 的模型。
**适合谁**：已经订 ChatGPT Plus / Pro，想在终端机用同一个账号做事的人。
#### [sst/opencode](https://github.com/sst/opencode) ⭐⭐⭐⭐⭐
| 栏位 | 内容 |
|---|---|
| Stars | ★ 155k+ |
| License | MIT |
**教什么**：开源版的 coding agent，**不绑定特定 LLM provider**——可以用 Claude、GPT、Gemini、本地 Ollama 任何一个。社群维护、迭代速度快。
**适合谁**：想 self-host、不想被 API provider 绑定，或要在多个 LLM 之间切换的人。
#### [google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli) ⭐⭐⭐⭐
| 栏位 | 内容 |
|---|---|
| Stars | ★ 103k+ |
| License | Apache-2.0 |
**教什么**：Google 官方的 Gemini CLI agent。把 Gemini 的长 context 跟 Google 生态集成到终端机。
**适合谁**：Google 生态的重度用户（Gmail、Drive、Docs）。
---
### Tier 3 — 本地 LLM（隐私 / 离线 / 省钱）
#### [Ollama](https://github.com/ollama/ollama) ⭐⭐⭐⭐⭐
★ 170k+ — 一行指令跑本地 LLM。隐私敏感数据（病历、合约、家人对话）不适合送去云端时用这个。详见 [Stage 1 — Local LLM 执行](../stages/01-llm-basics.zh-Hans.md)。
#### [LM Studio](https://lmstudio.ai/)
非开源但对非开发者最友好——拖拉界面、不用 command line。Mac / Windows / Linux 都有。
---
### Prompt 素材库
#### [f/awesome-chatgpt-prompts](https://github.com/f/awesome-chatgpt-prompts) ⭐⭐⭐⭐
★ 161k+ — 社群维护的 prompt 大全。“act as 翻译家 / 履历顾问 / 厨师...”几百种角色。**不知道怎么开头时从这里找灵感**。
---
## 必修阅读
1. [**Anthropic — How to write effective prompts**](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview) — 不用代码也能读的 prompt 写法
2. [**OpenAI — Prompting Guide**](https://platform.openai.com/docs/guides/prompt-engineering) — 对称的官方文件
3. [**ChatGPT 怎么用得最好（中文）**](https://www.runoob.com/) — 各家中文博客的整理（runoob 等等）
如果有兴趣再深入，看 [Stage 2 — Prompt 设计](../stages/02-prompt-engineering.zh-Hans.md)，那边有正式系统性教学。
## 可以建的流程（按使用频率）
下表 5 条是模板，配合你自己的场景调整：
| 频率 | 流程 | 怎么做（≤ 3 步） | 推荐工具 |
|---|---|---|---|
| **每天** | Email 分流 | (1) 早上把待回信件贴进 Claude<br>(2) 请它分类“立即回 / 今天回 / 这周回 / 不用回”<br>(3) 草拟回信让你 review | Claude.ai / ChatGPT |
| **每天** | 练语言（口说） | (1) 打开 ChatGPT Voice 模式<br>(2) 对话练英 / 日<br>(3) 请它指出语法错误 | ChatGPT Voice / Gemini |
| **每周** | 周记整理 | (1) 跟 Claude 讲这周做什么<br>(2) 请它整理成周记 + 下周重点<br>(3) 存到 Obsidian / Notion | Claude.ai |
| **不定期** | 批量整理文件 | (1) Claude Code 进 Downloads 文件夹<br>(2) 按日期 + 主题重命名<br>(3) 自动分到子文件夹 | Claude Code |
| **隐私场景** | 本地医疗 / 法律 / 财务笔记 | (1) Ollama 跑 qwen2.5:7b<br>(2) 整理个人笔记，数据不送云<br>(3) ⚠️ 保护的是**隐私**，不是**正确性**——具体诊断 / 法律判断 / 投资决策仍需专业人士 | Ollama + qwen2.5 |
> 💡 **新手起手式**：先把“每天 Email 分流”+“练语言”做一个月，习惯 AI 在日常的位置，再加其他流程。
## 给日常用户的层级建议
下表是建议的进阶路径：
| Tier | 工具 | 适合谁 | 学习成本 |
|---|---|---|---|
| **Tier 0** | Claude.ai / ChatGPT / Gemini / Perplexity（网页版） | 90% 的场景都在这里——免安装、免付费 | 0（会用浏览器就行） |
| **Tier 1** | Claude Desktop / ChatGPT Desktop + MCP | 要处理本地文件、保留对话历史、接 Gmail / Notion | 半小时装好 |
| **Tier 2** | Claude Code / opencode（CLI） | 有重复自动化需求（每天做同样的事 100 次） | 1-2 天上手 |
| **Tier 3** | Ollama 本地 LLM | 隐私敏感数据不能送云、API 费用敏感、想 offline | 半天设置 |
> **不要被人催着升级**——多数人 Tier 0 就够用了。Tier 2-3 是工具，不是身份地位。
## 社群备注
这条分支也欢迎社群贡献：
- 推荐特定领域的 prompt template（料理、运动、学语言）
- 中文友善的 chat tools（国产 LLM、本地化 wrapper）
- 隐私 / 安全相关的最佳实践（什么数据能送 / 不能送）
详见 [CONTRIBUTING.md](../CONTRIBUTING.md)。
branches/for-knowledge-worker.en.md
+144
View File
@@ -0,0 +1,144 @@
# Extension Path: For Knowledge Workers
> [繁體中文](./for-knowledge-worker.md) | [简体中文](./for-knowledge-worker.zh-Hans.md) | **English**
> 🚀 **No development background at all?** Most knowledge workers can start directly with Claude.ai / Claude Desktop, **without any setup**. Only read [`resources/setup-guide.en.md` A-D](../resources/setup-guide.en.md) (30-45 minutes from zero) when you need to connect an MCP server (such as Gmail / Notion) or use CLI automation.
> [← Back to main path README](../README.en.md) · Continue here after **Track A's A3** or **Track B's Stage 7**. Apply agentic AI to office / knowledge work.
## Use Cases (Office Scenarios × How AI Helps)
The table below splits a knowledge worker's day into 7 common scenarios. Most of them are covered by Claude Desktop + MCP at Tier 1:
| Scenario | Pain point | How AI helps | Recommended tools |
|---|---|---|---|
| **Email triage** | 100 messages a day; priority is hard to judge | Categorize + draft replies for your review | Claude Desktop + Gmail MCP |
| **Meetings → action items** | You forget half of a 30-minute meeting; action items are not captured | Transcript → key decisions + action items | Otter / Zoom transcript + Claude |
| **Cross-tool report aggregation** | Slack / Gmail / Notion each hold part of the picture | Pull metrics + synthesize + email summary | n8n / Make / Langflow |
| **Research / market intelligence** | Hard to know what to ask or who to trust | Multi-source search + cross-validation + memo | Perplexity + Claude |
| **Slack / messaging** | Tone is hard to calibrate in sensitive situations | Rewrite + adjust tone + produce alternatives | Claude.ai |
| **Notion / knowledge-base cleanup** | Notes are messy, unstructured, and hard to find | Retag + classify + auto-summarize | Claude Desktop + Notion MCP |
| **Documents / proposal drafts** | Specs and proposals get stuck | Outline → sections → polish | Claude.ai |
> 💡 **MCP is central for knowledge workers**: new to MCP? Read [Stage 5.2 — MCP Foundation](../stages/05-claude-code-ecosystem.en.md#52--mcp-model-context-protocol--foundation). Looking for available MCP servers? See [`resources/mcp-skills-catalog.en.md`](../resources/mcp-skills-catalog.en.md).
## Curated Projects
> 💡 **Want to wire your AI agent to Notion / Gmail / Outlook / Slack / Excel / Lark?** Example: automatically turn Gmail messages into Notion todos. 65+ commonly-used office integration tools are listed in [`resources/mcp-skills-catalog.en.md`](../resources/mcp-skills-catalog.en.md) (grouped by use case). The section below stays focused on workflow / integration-platform-level tools.
### Workflow Tools
#### [n8n](https://github.com/n8n-io/n8n) ⭐⭐⭐⭐
Self-hostable workflow automation platform with built-in AI integration; visual node-based editor.
**Best for**: When you need glue between many SaaS tools (Slack + Gmail + Notion + AI).
---
#### [Make.com](https://www.make.com/) (formerly Integromat)
Hosted workflow automation. Strong AI integration nodes.
---
### Knowledge Worker Skills
#### [obra/superpowers](https://github.com/obra/superpowers) ⭐⭐⭐⭐
Brainstorming, planning, and decision-making skills.
---
### Knowledge Management / Personal AI
#### [khoj-ai/khoj](https://github.com/khoj-ai/khoj) ⭐⭐⭐⭐
| Field | Value |
|---|---|
| Stars | ★ 34k+ |
| License | AGPL-3.0 |
**What it teaches**: Self-hosted "second brain" — chat with web + local docs, schedule automations, build custom agents.
**Best for**: People wanting a self-hosted personal knowledge base + AI assistant.
**Notes**: AGPL-3.0 license (copyleft).
---
#### [lobehub/lobe-chat](https://github.com/lobehub/lobe-chat) ⭐⭐⭐⭐⭐
| Field | Value |
|---|---|
| Stars | ★ 76k+ |
| License | LobeHub Community License (Apache-2.0 base + commercial conditions) |
**What it teaches**: Deployable multi-agent chat platform — plugin marketplace, knowledge bases, team collaboration. One representative option for self-hosted AI workspaces.
**Best for**: Self-hosting a collaborative chat workspace.
**Notes**: Commercial use needs to verify the LobeHub Community License's added conditions.
---
#### [langflow-ai/langflow](https://github.com/langflow-ai/langflow) ⭐⭐⭐⭐
| Field | Value |
|---|---|
| Stars | ★ 147k+ |
| License | MIT |
**What it teaches**: Visual AI-agent design platform — useful for mapping customer support, report assembly, and data-query workflows into nodes. More agent-focused than n8n (n8n is generic workflow). API / MCP server deployment is an advanced note, not something you need to learn first.
**Best for**: Knowledge workers who'd rather wire nodes than write Python; or anyone designing agent flows for team handoff.
---
#### [Mintplex-Labs/anything-llm](https://github.com/Mintplex-Labs/anything-llm) ⭐⭐⭐⭐⭐
| Field | Value |
|---|---|
| Stars | ★ 60k+ |
| License | MIT |
**What it teaches**: All-in-one private RAG workspace — upload documents, build agents, MCP-compatible, on-device by default. **A self-hosted alternative to NotebookLM**.
**Best for**: Knowledge workers wanting a NotebookLM-style tool, self-hosted, without sending data to the cloud.
---
### MCP Servers Useful for Knowledge Workers
#### Communication MCP servers ⭐⭐⭐⭐
Slack / Gmail / Discord etc. The original Anthropic-hosted reference servers were reorganized in 2025; community-maintained servers now live in [**punkpeye/awesome-mcp-servers**](https://github.com/punkpeye/awesome-mcp-servers#communication) and [**wong2/awesome-mcp-servers**](https://github.com/wong2/awesome-mcp-servers). Browse those lists for current Slack / Gmail / Drive / Calendar MCP servers.
---
## Workflows You Can Build (by frequency)
| Frequency | Workflow | Steps (≤3) | Recommended tools | Best for |
|---|---|---|---|---|
| **Daily** | Email triage | (1) Scan inbox<br>(2) Categorize into "now / today / this week / no reply"<br>(3) Draft replies for your review | Claude Desktop + Gmail MCP | All knowledge workers |
| **Per meeting** | Meetings → action items | (1) Capture transcript (Otter / Zoom)<br>(2) Have Claude extract "key decisions + action items"<br>(3) Assign + announce in Slack / email | Claude.ai + transcript tool | Managers / PMs |
| **Weekly** | Cross-tool report | (1) Pull metrics from N tools<br>(2) Synthesize with Claude / n8n<br>(3) Send email summary | n8n / Make / Langflow | People who send regular updates |
| **Occasional** | Research / market intelligence | (1) Clarify the question<br>(2) Search multiple sources + cross-validate<br>(3) Write a 1-2 page memo | Perplexity + Claude | Analysts / strategy roles |
| **Occasional** | Notion / knowledge-base cleanup | (1) Paste scattered notes into Claude<br>(2) Ask it to retag + classify<br>(3) Output structured Notion format | Claude Desktop + Notion MCP | Notion / Obsidian users |
> 💡 **Starter habit**: run "daily email triage" for a month first so "open inbox, open Claude" becomes natural. Adding too many automations at once is hard to sustain.
## Tier Recommendations
Recommended progression:
| Tier | Tools | Best for | Learning cost |
|---|---|---|---|
| **Tier 0** | Claude.ai / ChatGPT / Gemini / Perplexity (web) | Most knowledge workers start here | 0 (if you can use a browser) |
| **Tier 1** | Claude Desktop + MCP (Gmail / Notion / calendar) | Repeat workflows over local / cloud files | Half a day |
| **Tier 2** | n8n / Make / Langflow (automation platforms) | Connecting several SaaS tools without writing code | 1 week of setup |
| **Tier 3** | Claude Code / Codex / your own Python | Dev background or dev support, workflows ready for production deployment | Several weeks, overlaps with Track A |
**Tier 3+ (CLI / SDK) is too heavy for most knowledge worker tasks**. Most people can stop at Tier 1-2.
## Reading
- [How I Turned Claude Code Into My Personal AI Agent OS](https://aimaker.substack.com/p/how-i-turned-claude-code-into-personal-ai-agent-operating-system-for-writing-research-complete-guide) — knowledge worker case study
- [**Anthropic — The Founder's Playbook**](https://claude.com/blog/the-founders-playbook) — Anthropic's 35-page startup playbook (2026-05-14); maps Idea / MVP / Launch / Scale onto 2026 AI capability
branches/for-knowledge-worker.md
+144
View File
@@ -0,0 +1,144 @@
# 知識工作者延伸路線（For Knowledge Workers）
> **繁體中文** | [简体中文](./for-knowledge-worker.zh-Hans.md) | [English](./for-knowledge-worker.en.md)
> 🚀 **完全沒開發背景？** 多數知識工作者可以直接從 Claude.ai / Claude Desktop 開始、**不需要任何 setup**。只有當你要接 MCP server（如 Gmail / Notion）或用 CLI 自動化時、才需要看 [`resources/setup-guide.md` A-D](../resources/setup-guide.md)（30-45 分鐘從零）。
> [← 回主路線 README](../README.md) · 走完 **Track A 的 A3** 或 **Track B 的 Stage 7** 後從這裡接續。把 agentic AI 應用到辦公室 / 知識工作上。
## 使用情境（辦公場景 × AI 怎麼幫）
下表把知識工作者一天會遇到的 7 個情境拆開——多數場景在 Claude Desktop + MCP（Tier 1）就能搞定：
| 場景 | 你常遇到的痛點 | AI 能幫的部分 | 推薦工具 |
|---|---|---|---|
| **Email 分流** | 每天 100 封看不完、優先順序錯 | 分類 + 草擬回信讓你 review | Claude Desktop + Gmail MCP |
| **會議 → 行動項目** | 聽完 30 分鐘忘一半、action item 沒記 | 逐字稿 → 主要決策 + 行動項目 | Otter / Zoom 逐字稿 + Claude |
| **跨工具報告整合** | Slack / Gmail / Notion 各一塊、要手動拉 | 自動拉指標 + 整合 + email summary | n8n / Make / Langflow |
| **研究 / 市場情報** | 不知問什麼問題、不知該信誰 | 多源搜尋 + 交叉驗證 + 備忘錄 | Perplexity + Claude |
| **Slack / 訊息** | 拿捏不準口氣、敏感場景 | 改寫 + 調語氣 + 多版本 | Claude.ai |
| **Notion / 知識庫整理** | 雜亂、沒架構、找不到舊筆記 | 重 tag + 分類 + 自動摘要 | Claude Desktop + Notion MCP |
| **文件 / 提案草稿** | spec / proposal 卡關 | 大綱 → 段落 → 潤色 | Claude.ai |
> 💡 **MCP 是知識工作者的關鍵**：第一次接觸 MCP？看 [Stage 5.2 — MCP 基礎](../stages/05-claude-code-ecosystem.md#52--mcpmodel-context-protocol-基礎)；想知道有哪些 MCP server → [`resources/mcp-skills-catalog.md`](../resources/mcp-skills-catalog.md)。
## 精選 Projects
> 💡 **想把 AI agent 接到 Notion / Gmail / Outlook / Slack / Excel / 飛書？**（例：把 Gmail 來信自動整理成 Notion 待辦）65+ 個常用辦公整合工具表見 [`resources/mcp-skills-catalog.md`](../resources/mcp-skills-catalog.md)（按使用情境分類）。下面這節保留 workflow / 整合平台級的工具。
### 工作流工具
#### [n8n](https://github.com/n8n-io/n8n) ⭐⭐⭐⭐
可自架的工作流自動化平台，內建 AI 整合，採用視覺化節點式編輯器。
**適合誰**：要把多個 SaaS 工具串起來時（Slack + Gmail + Notion + AI）。
---
#### [Make.com](https://www.make.com/)（前身為 Integromat）
雲端代管的工作流自動化平台，AI 整合節點功能完整。
---
### 知識工作者 Skills
#### [obra/superpowers](https://github.com/obra/superpowers) ⭐⭐⭐⭐
腦力激盪、規劃、決策類的 skill。
---
### 知識管理 / 個人 AI
#### [khoj-ai/khoj](https://github.com/khoj-ai/khoj) ⭐⭐⭐⭐
| 欄位 | 內容 |
|---|---|
| Stars | ★ 34k+ |
| License | AGPL-3.0 |
**教什麼**：自架的「第二大腦」——可以跟 web + 本地文件對話、排程自動化、自訂 agent。
**適合誰**：想自架個人知識庫 + AI assistant 的人。
**備註**：AGPL-3.0 license（傳染性開源）。
---
#### [lobehub/lobe-chat](https://github.com/lobehub/lobe-chat) ⭐⭐⭐⭐⭐
| 欄位 | 內容 |
|---|---|
| Stars | ★ 76k+ |
| License | LobeHub Community License（基於 Apache-2.0 + 商用附加條款） |
**教什麼**：可部署的多 agent 聊天平台——含 plugin marketplace、知識庫、團隊協作。可自架的 AI workspace 代表選項之一。
**適合誰**：要找可自架的協作 chat workspace。
**備註**：商用使用需確認 LobeHub Community License 的附加條款。
---
#### [langflow-ai/langflow](https://github.com/langflow-ai/langflow) ⭐⭐⭐⭐
| 欄位 | 內容 |
|---|---|
| Stars | ★ 147k+ |
| License | MIT |
**教什麼**：視覺化 AI agent 設計平台——適合把客服、報告整理、資料查詢這類流程畫成節點。比 n8n 更專注在 agent 設計（n8n 是泛用工作流）。API / MCP server 部署是進階備註、不必一開始就學。
**適合誰**：寧可拉節點不寫 Python 的知識工作者，或要設計 agent 跟團隊溝通流程的人。
---
#### [Mintplex-Labs/anything-llm](https://github.com/Mintplex-Labs/anything-llm) ⭐⭐⭐⭐⭐
| 欄位 | 內容 |
|---|---|
| Stars | ★ 60k+ |
| License | MIT |
**教什麼**：all-in-one 的私有 RAG 工作平台——上傳文件、建 agent、相容 MCP、預設 on-device。**NotebookLM 的私有 self-hosted 替代方案**。
**適合誰**：知識工作者要私有部署、類 NotebookLM 的工具，避免把資料送到雲端。
---
### 對知識工作者有用的 MCP Server
#### 通訊類 MCP server ⭐⭐⭐⭐
Slack / Gmail / Discord 等。Anthropic 原本維護的 reference server 已於 2025 年重整；目前由社群維護的 server 集中在 [**punkpeye/awesome-mcp-servers**](https://github.com/punkpeye/awesome-mcp-servers#communication) 跟 [**wong2/awesome-mcp-servers**](https://github.com/wong2/awesome-mcp-servers)，要找最新的 Slack / Gmail / Drive / Calendar MCP server 可以從這兩個清單翻找。
---
## 可以建的流程（按使用頻率）
| 頻率 | 流程 | 怎麼做（≤ 3 步） | 推薦工具 | 適合誰 |
|---|---|---|---|---|
| **每天** | Email 分流 | (1) 掃 inbox<br>(2) 分類成「立即 / 今天 / 這週 / 不用回」<br>(3) 草擬回信讓你 review | Claude Desktop + Gmail MCP | 全知識工作者 |
| **每次會議** | 會議 → 行動項目 | (1) 逐字稿（Otter / Zoom）<br>(2) Claude 抓「主要決策 + 行動項目」<br>(3) 指派 + Slack / email 公告 | Claude.ai + 逐字稿工具 | 主管 / PM |
| **每週** | 跨工具報告 | (1) 從 N 個工具拉指標<br>(2) Claude / n8n 整理<br>(3) email summary 寄出 | n8n / Make / Langflow | 要定期 update 老闆的人 |
| **不定期** | 研究 / 市場情報 | (1) 想清楚問題<br>(2) 多來源搜尋 + 交叉驗證<br>(3) 寫成 1-2 頁備忘錄 | Perplexity + Claude | 分析 / 策略職 |
| **不定期** | Notion / 知識庫重整 | (1) 把散落筆記貼進 Claude<br>(2) 請它重新 tag + 分類<br>(3) 輸出 Notion 結構化格式 | Claude Desktop + Notion MCP | 有 Notion / Obsidian 習慣的人 |
> 💡 **新手起手式**：先把「每天 Email 分流」做一個月、養成「inbox 開 Claude」的習慣、再加其他流程。一次裝太多會養不起來。
## 層級建議
下表是建議的進階路徑：
| Tier | 工具 | 適合誰 | 學習成本 |
|---|---|---|---|
| **Tier 0** | Claude.ai / ChatGPT / Gemini / Perplexity（網頁版） | 大多數知識工作者從這裡開始 | 0（會用瀏覽器就行） |
| **Tier 1** | Claude Desktop + MCP（Gmail / Notion / 行事曆） | 要對本機 / 雲端檔案重複跑流程 | 半天裝好 |
| **Tier 2** | n8n / Make / Langflow（自動化平台） | 要把多個 SaaS 工具串起來、不寫 code | 1 週 setup |
| **Tier 3** | Claude Code / Codex / 自己寫 Python | 有 dev 背景或團隊有 dev 支援、要做能上線部署的成果 | 數週、跟 Track A 重疊 |
**Tier 3+（CLI / SDK）對多數知識工作者任務來說太重**——不要被別人慫恿過去。多數人停在 Tier 1-2 就夠。
## 閱讀
- [How I Turned Claude Code Into My Personal AI Agent OS](https://aimaker.substack.com/p/how-i-turned-claude-code-into-personal-ai-agent-operating-system-for-writing-research-complete-guide) — 知識工作者個案研究
- [**Anthropic — The Founder's Playbook**](https://claude.com/blog/the-founders-playbook) — Anthropic 2026-05-14 發布的 35 頁 startup 指南;Idea / MVP / Launch / Scale 四階段對應到 2026 AI capability
branches/for-knowledge-worker.zh-Hans.md
+144
View File
@@ -0,0 +1,144 @@
# 知识工作者延伸路线（For Knowledge Workers）
> [繁體中文](./for-knowledge-worker.md) | **简体中文** | [English](./for-knowledge-worker.en.md)
> 🚀 **完全没有开发背景？** 多数知识工作者可以直接从 Claude.ai / Claude Desktop 开始、**不需要任何 setup**。只有当你要接 MCP server（如 Gmail / Notion）或用 CLI 自动化时，才需要看 [`resources/setup-guide.zh-Hans.md` A-D](../resources/setup-guide.zh-Hans.md)（30-45 分钟从零）。
> [← 回主路线 README](../README.zh-Hans.md) · 走完 **Track A 的 A3** 或 **Track B 的 Stage 7** 后从这里接续。把 agentic AI 应用到办公室 / 知识工作上。
## 使用场景（办公场景 × AI 怎么帮）
下表把知识工作者一天会遇到的 7 个场景拆开——多数场景在 Claude Desktop + MCP（Tier 1）就能搞定：
| 场景 | 你常遇到的痛点 | AI 能帮的部分 | 推荐工具 |
|---|---|---|---|
| **Email 分流** | 每天 100 封看不完、优先顺序错 | 分类 + 草拟回信让你 review | Claude Desktop + Gmail MCP |
| **会议 → 行动项目** | 听完 30 分钟忘一半、action item 没记 | 逐字稿 → 主要决策 + 行动项目 | Otter / Zoom 逐字稿 + Claude |
| **跨工具报告集成** | Slack / Gmail / Notion 各一块、要手动拉 | 自动拉指标 + 整合 + email summary | n8n / Make / Langflow |
| **研究 / 市场情报** | 不知道问什么问题、不知道该信谁 | 多源搜索 + 交叉验证 + 备忘录 | Perplexity + Claude |
| **Slack / 消息** | 拿捏不准语气、敏感场景 | 改写 + 调语气 + 多版本 | Claude.ai |
| **Notion / 知识库整理** | 杂乱、没架构、找不到旧笔记 | 重 tag + 分类 + 自动摘要 | Claude Desktop + Notion MCP |
| **文件 / 提案草稿** | spec / proposal 卡关 | 大纲 → 段落 → 润色 | Claude.ai |
> 💡 **MCP 是知识工作者的关键**：第一次接触 MCP？看 [Stage 5.2 — MCP 基础](../stages/05-claude-code-ecosystem.zh-Hans.md#52--mcpmodel-context-protocol-基础)；想知道有哪些 MCP server → [`resources/mcp-skills-catalog.zh-Hans.md`](../resources/mcp-skills-catalog.zh-Hans.md)。
## 精选 Projects
> 💡 **想把 AI agent 接到 Notion / Gmail / Outlook / Slack / Excel / 飞书？**（例：把 Gmail 来信自动整理成 Notion 待办）65+ 个常用办公集成工具表见 [`resources/mcp-skills-catalog.zh-Hans.md`](../resources/mcp-skills-catalog.zh-Hans.md)（按使用场景分类）。下面这节保留 workflow / 集成平台级的工具。
### 工作流工具
#### [n8n](https://github.com/n8n-io/n8n) ⭐⭐⭐⭐
可自架的工作流自动化平台，内置 AI 集成，采用可视化节点式编辑器。
**适合谁**：要把多个 SaaS 工具串起来时（Slack + Gmail + Notion + AI）。
---
#### [Make.com](https://www.make.com/)（前身为 Integromat）
云端代管的工作流自动化平台，AI 集成节点功能完整。
---
### 知识工作者 Skills
#### [obra/superpowers](https://github.com/obra/superpowers) ⭐⭐⭐⭐
头脑风暴、规划、决策类的 skill。
---
### 知识管理 / 个人 AI
#### [khoj-ai/khoj](https://github.com/khoj-ai/khoj) ⭐⭐⭐⭐
| 栏位 | 内容 |
|---|---|
| Stars | ★ 34k+ |
| License | AGPL-3.0 |
**教什么**：自架的“第二大脑”——可以跟 web + 本地文件对话、排程自动化、自定义 agent。
**适合谁**：想自架个人知识库 + AI assistant 的人。
**备注**：AGPL-3.0 license（传染性开源）。
---
#### [lobehub/lobe-chat](https://github.com/lobehub/lobe-chat) ⭐⭐⭐⭐⭐
| 栏位 | 内容 |
|---|---|
| Stars | ★ 76k+ |
| License | LobeHub Community License（基于 Apache-2.0 + 商用附加条款） |
**教什么**：可部署的多 agent 聊天平台——含 plugin marketplace、知识库、团队协作。可自架的 AI workspace 代表选项之一。
**适合谁**：想找可自架的协作 chat workspace。
**备注**：商用使用需确认 LobeHub Community License 的附加条款。
---
#### [langflow-ai/langflow](https://github.com/langflow-ai/langflow) ⭐⭐⭐⭐
| 栏位 | 内容 |
|---|---|
| Stars | ★ 147k+ |
| License | MIT |
**教什么**：可视化 AI agent 设计平台——适合把客服、报告整理、资料查询这类流程画成节点。比 n8n 更专注于 agent 设计（n8n 是泛用工作流）。API / MCP server 部署是进阶备注，不必一开始就学。
**适合谁**：宁可拉节点不写 Python 的知识工作者，或要设计 agent 跟团队沟通流程的人。
---
#### [Mintplex-Labs/anything-llm](https://github.com/Mintplex-Labs/anything-llm) ⭐⭐⭐⭐⭐
| 栏位 | 内容 |
|---|---|
| Stars | ★ 60k+ |
| License | MIT |
**教什么**：all-in-one 的私有 RAG 工作平台——上传文件、建 agent、相容 MCP、预设 on-device。**NotebookLM 的私有 self-hosted 替代方案**。
**适合谁**：知识工作者要私有部署、类 NotebookLM 的工具，避免把数据送到云端。
---
### 对知识工作者有用的 MCP Server
#### 通讯类 MCP server ⭐⭐⭐⭐
Slack / Gmail / Discord 等。Anthropic 原本维护的 reference server 已于 2025 年重整；目前由社群维护的 server 集中在 [**punkpeye/awesome-mcp-servers**](https://github.com/punkpeye/awesome-mcp-servers#communication) 跟 [**wong2/awesome-mcp-servers**](https://github.com/wong2/awesome-mcp-servers)，要找最新的 Slack / Gmail / Drive / Calendar MCP server 可以从这两个清单翻找。
---
## 可以建的流程（按使用频率）
| 频率 | 流程 | 怎么做（≤ 3 步） | 推荐工具 | 适合谁 |
|---|---|---|---|---|
| **每天** | Email 分流 | (1) 扫 inbox<br>(2) 分类成“立即 / 今天 / 这周 / 不用回”<br>(3) 草拟回信让你 review | Claude Desktop + Gmail MCP | 全知识工作者 |
| **每次会议** | 会议 → 行动项目 | (1) 逐字稿（Otter / Zoom）<br>(2) Claude 抓“主要决策 + 行动项目”<br>(3) 指派 + Slack / email 公告 | Claude.ai + 逐字稿工具 | 主管 / PM |
| **每周** | 跨工具报告 | (1) 从 N 个工具拉指标<br>(2) Claude / n8n 整理<br>(3) email summary 寄出 | n8n / Make / Langflow | 要定期 update 老板的人 |
| **不定期** | 研究 / 市场情报 | (1) 想清楚问题<br>(2) 多来源搜索 + 交叉验证<br>(3) 写成 1-2 页备忘录 | Perplexity + Claude | 分析 / 策略职 |
| **不定期** | Notion / 知识库重整 | (1) 把散落笔记贴进 Claude<br>(2) 请它重新 tag + 分类<br>(3) 输出 Notion 结构化格式 | Claude Desktop + Notion MCP | 有 Notion / Obsidian 习惯的人 |
> 💡 **新手起手式**：先把“每天 Email 分流”做一个月，养成“inbox 开 Claude”的习惯，再加其他流程。一次装太多会养不起来。
## 层级建议
下表是建议的进阶路径：
| Tier | 工具 | 适合谁 | 学习成本 |
|---|---|---|---|
| **Tier 0** | Claude.ai / ChatGPT / Gemini / Perplexity（网页版） | 大多数知识工作者从这里开始 | 0（会用浏览器就行） |
| **Tier 1** | Claude Desktop + MCP（Gmail / Notion / 日历） | 要对本机 / 云端文件重复跑流程 | 半天装好 |
| **Tier 2** | n8n / Make / Langflow（自动化平台） | 要把多个 SaaS 工具串起来、不写 code | 1 周 setup |
| **Tier 3** | Claude Code / Codex / 自己写 Python | 有 dev 背景或团队有 dev 支援、要做能上线部署的成果 | 数周、跟 Track A 重叠 |
**Tier 3+（CLI / SDK）对多数知识工作者任务来说太重**——不要被别人怂恿过去。多数人停在 Tier 1-2 就够。
## 阅读
- [How I Turned Claude Code Into My Personal AI Agent OS](https://aimaker.substack.com/p/how-i-turned-claude-code-into-personal-ai-agent-operating-system-for-writing-research-complete-guide) — 知识工作者个案研究
- [**Anthropic — The Founder's Playbook**](https://claude.com/blog/the-founders-playbook) — Anthropic 2026-05-14 发布的 35 页 startup 指南;Idea / MVP / Launch / Scale 四阶段对应到 2026 AI capability
branches/for-researcher.en.md
+208
View File
@@ -0,0 +1,208 @@
# Extension Path: For Researchers
> [繁體中文](./for-researcher.md) | [简体中文](./for-researcher.zh-Hans.md) | **English**
> 🚀 **Computational researchers** (can run Python scripts, have an API key, and can use git) can jump into the advanced path directly. **Non-programming researchers** (humanities/social sciences, clinical research, literature-first work) can start with literature Q&A (NotebookLM) and Zotero AI tools, then read [`resources/setup-guide.en.md` A-C](../resources/setup-guide.en.md) when needed.
> [← Back to main path README](../README.en.md) · Continue here after **Track A's A3** or **Track B's Stage 7**. Apply agentic AI to research workflows.
## Use Cases
Research days break into stages, and AI plays a different role at each stage. Use this table to orient yourself:
| Stage | Common pain point | How AI helps | Recommended tools (light to heavy) |
|---|---|---|---|
| **Literature exploration** | You do not know the classic papers in a field | Recommendations + summaries + comparison | NotebookLM → paper-qa → gpt-researcher |
| **Close reading** | You lose the thread halfway through a PDF / miss the claim | Extract claims, figures, citations, and notes | Zotero + zotero-gpt → zotero-skills |
| **Research design** | The RQ is fuzzy, or the method choice is unclear | Clarifying dialogue and trade-off mapping | Claude.ai chat → ai-research-skills |
| **Experiments / coding** | Boilerplate repeats and plotting eats time | Write / edit code and batch refactor | Claude Code → codex-delegate |
| **Manuscript writing** | Drafts stall or sentences do not land | Outline → paragraphs → polishing | Claude.ai → gemini-delegate (long drafts) |
| **Revision / submission** | Journal requirements are easy to miss | banned-word / figure-text / submission checklist | academic-writing-skills |
| **Cross-paper synthesis** | Five papers need to talk to each other and context explodes | Read 1M tokens at once and organize the synthesis | gemini-delegate |
> 💡 **Computational vs non-programming researchers**: the recommended tools run from light to heavy. Non-programming researchers can usually stop at the **first** tool in each row; computational researchers should move right only when they need automation.
## Curated Projects
> 💡 **Want to wire Claude Code into NotebookLM, Obsidian, Notion, Excel, PDF, Excalidraw, and other research tools?** 65+ integrations in [`resources/mcp-skills-catalog.en.md`](../resources/mcp-skills-catalog.en.md) (grouped by use case). The section below keeps research-specific tools and marketplaces.
### Research Workflow Marketplaces
#### [flonat/claude-research](https://github.com/flonat/claude-research) ⭐⭐⭐
Claude Code infrastructure for PhD researchers — skills, agents, hooks, rules for academic workflows. Strong LaTeX/bibliography focus.
---
### Literature RAG / Q&A
#### [Future-House/paper-qa](https://github.com/Future-House/paper-qa) ⭐⭐⭐⭐⭐
| Field | Value |
|---|---|
| Stars | ★ 8k+ |
| License | Apache-2.0 |
**What it teaches**: PDF Q&A designed for **citation-grounded Q&A** — every answer includes sentence-level citations to reduce hallucination risk. Actual accuracy depends on document type; use the official benchmarks / papers as the reference.
**Best for**: Researchers writing literature reviews who need "every answer must be traceable to its source." More rigorous than generic RAG.
---
#### [assafelovic/gpt-researcher](https://github.com/assafelovic/gpt-researcher) ⭐⭐⭐⭐
| Field | Value |
|---|---|
| Stars | ★ 27k+ |
| License | Apache-2.0 |
**What it teaches**: Autonomous deep-research agent — planner + multi-source crawl + report synthesis. Give it a research topic, get a markdown / PDF brief out.
**Best for**: Researchers who need to quickly scope new topics and produce research briefs.
---
### Outline & Writing
#### [stanford-oval/storm](https://github.com/stanford-oval/storm) ⭐⭐⭐⭐
| Field | Value |
|---|---|
| Stars | ★ 28k+ |
| License | MIT |
**What it teaches**: Multi-perspective outline-then-write pipeline — plain-language version: (1) simulate different perspectives asking questions, (2) organize those questions into an outline, then (3) generate a Wikipedia-style draft. From Stanford OVAL.
**Best for**: Learning **outline-driven writing**. Great for producing topic briefs from scratch; the closest open-source analog to NotebookLM's structured report flow.
**Notes**: Last push was over 6 months ago — verify the latest commit date before relying on it.
---
#### [kaixindelele/ChatPaper](https://github.com/kaixindelele/ChatPaper) ⭐⭐⭐⭐⭐ (Chinese readers)
| Field | Value |
|---|---|
| Language | Chinese + Python |
| Stars | ★ 19k+ |
| License | NOASSERTION (custom non-commercial) |
**What it teaches**: Full arXiv workflow for Chinese researchers — paper summary + translation + polishing + review-response generation. Maintained by a Chinese team; defaults are friendly to Chinese-language workflows.
**Best for**: Chinese graduate students looking for a Chinese-friendly entry-level paper workflow tool.
**Notes**: License is custom non-commercial — read the original terms before any use; common practice is research / personal use, but you should verify the terms yourself.
---
### Citation Manager Integrations
#### [MuiseDestiny/zotero-gpt](https://github.com/MuiseDestiny/zotero-gpt) ⭐⭐⭐⭐
| Field | Value |
|---|---|
| Stars | ★ 7k+ |
| License | AGPL-3.0 |
**What it teaches**: A Zotero LLM plugin — chat with your library, summarize selections, generate inline notes.
**Best for**: Heavy Zotero users who want AI inside their reading workflow without switching tools.
**Notes**: AGPL-3.0 license (copyleft) — derivative products that ship modifications must follow the terms.
---
### Multi-LLM Research Stack (Maintainer Setup)
Some research tasks only need Claude (dialogue, design, review). Others waste Claude tokens (large code refactors, long-form drafts). The maintainer's actual setup is **Claude as planner / reviewer, Codex for code, and Gemini for long drafts**. Use this table to decide which model to use when:
| Task type | Example | LLM to use | Why |
|---|---|---|---|
| Research design / hypothesis discussion | "Should this RQ use logistic vs survival?" | Claude.ai chat | Collaborative dialogue and context memory |
| Writing / editing code | "Add logging to 50 simulation scripts" | codex-delegate | Fast mechanical edits without burning Claude tokens |
| Long-form drafting (Chinese / English) | "Draft an 8-page paper section" | gemini-delegate | 1M context and strong long-form prose |
| Second opinion | "Ask Gemini to review my discussion section" | gemini-delegate | LLM-vs-LLM comparison makes Claude's own biases easier to spot |
| Pre-submission audit | "Run banned-word + figure-text checklist" | academic-writing-skills | Structured audit instead of ad hoc LLM judgment |
#### Maintainer's 6 self-used research skills
> ⚠️ **Disclosure**: The following 6 tools are research skills used day to day by the maintainer [@WenyuChiou](https://github.com/WenyuChiou) (Lehigh CEE PhD candidate) and published for people with similar needs. **They have not been independently evaluated by third parties**. Best fit: PhD dissertation writing and cross-paper literature organization. They may not fit your field. Full entries are in [`resources/mcp-skills-catalog.en.md` 13 + 14](../resources/mcp-skills-catalog.en.md#13-research-workflow-skills-academic--paper--lit).
| Tool | Best for stage | One-liner |
|---|---|---|
| **[ai-research-skills](https://github.com/WenyuChiou/ai-research-skills)** ⭐⭐⭐⭐⭐ | Full pipeline | 14 research skills packaged as a 5-plugin marketplace; one command installs the set |
| **[research-hub](https://github.com/WenyuChiou/research-hub)** ⭐⭐⭐⭐ | Literature organization | Zotero + Obsidian + NotebookLM workspace with CLI / MCP / REST / dashboard interfaces |
| **[zotero-skills](https://github.com/WenyuChiou/zotero-skills)** ⭐⭐⭐⭐ | Reference management | Zotero CLI skill for search / add / classify / tag; complements zotero-gpt, which chats inside Zotero while this operates from outside |
| **[academic-writing-skills](https://github.com/WenyuChiou/academic-writing-skills)** ⭐⭐⭐ | Pre-submission | banned-word audit, figure-text coupling, and submission checklist; per-paper journal_format / style_overrides customization |
| **[codex-delegate](https://github.com/WenyuChiou/codex-delegate)** ⭐⭐⭐⭐⭐ | Coding | Standard Claude planner + Codex executor skill for batch refactor / boilerplate / migration work |
| **[gemini-delegate-skill](https://github.com/WenyuChiou/gemini-delegate-skill)** ⭐⭐⭐⭐ | Long drafts / synthesis | Claude planner + Gemini for 1M-context long-form writing / CJK / second opinions |
---
### Multi-Agent for Research
#### [langchain-ai/open_deep_research](https://github.com/langchain-ai/open_deep_research) ⭐⭐⭐⭐⭐
| Field | Value |
|---|---|
| Stars | ★ 11k+ |
| License | MIT |
**What it teaches**: Open-source Deep Research — supports both single-agent and supervisor + multi-researcher architectures (the multi-agent path currently lives in `src/legacy/`), parallel search, citation-grounded report synthesis. A solid reference for "LLM agent that auto-produces a cited brief."
**Best for**: Researchers building "agent auto-generates a cited brief" workflows. A solid open-source pick when you want a maintained reference implementation.
**Notes**: Depends on LangGraph + search tools (API key required).
---
#### [SakanaAI/AI-Scientist-v2](https://github.com/SakanaAI/AI-Scientist-v2) ⭐⭐⭐⭐
| Field | Value |
|---|---|
| Stars | ★ 6k+ |
| License | The AI Scientist Source Code License (source-available, non-commercial + manuscript-disclosure clause) |
**What it teaches**: End-to-end multi-agent science loop: ideate → code → experiment → write → peer-review. Sakana AI's research implementation of "AI writes a full ML paper."
**Best for**: Researchers who want to see "what does a swarm of agents running a full research lifecycle look like." Architecture reference, not a production tool.
**Notes**: Outputs are demo-level (not field-ready), ML/CS-domain bias. License is a custom source-available term (with a manuscript-disclosure clause) — read the LICENSE file before use.
---
> Still missing: actively-maintained peer-review automation, conference-review pipelines. If you've built or know of one, please open a PR.
## Required Reading
1. [The Effortless Academic — Claude Code beginner guides](https://effortlessacademic.com/claude-code-and-cowork-for-academics-beginner-guide-part-1/)
2. [Pedro Sant'Anna — Researcher setup guide](https://paulgp.substack.com/p/getting-started-with-claude-code)
## Workflows to Master
The biggest mistake researchers make with AI is opening ChatGPT only when they get stuck. The key is making AI a daily tool by setting a cadence. The 7 workflows below are ordered by usage frequency and are routines the maintainer actually runs, not hypotheticals.
| Frequency | Workflow | How to run it (≤ 3 steps) | Recommended tools | Best for |
|---|---|---|---|---|
| **Daily** | Literature inbox triage | (1) Put yesterday's papers into paper-qa<br>(2) Extract claims + a 4-5 line summary<br>(3) Move notes into Zotero / Obsidian | paper-qa + zotero-gpt | All researchers |
| **Daily** | Writing sprint (25 min) | (1) Give one paragraph to Claude.ai<br>(2) Run banned-word + figure-text audit<br>(3) Merge the revision into the main draft | Claude.ai + academic-writing-skills | Paper-writing stage |
| **Weekly** | Cross-paper synthesis | (1) Feed 5-10 PDFs to Gemini<br>(2) Ask where the papers disagree<br>(3) Turn the answer into a 1-page brief | gemini-delegate (1M context) | Computational researchers |
| **Weekly** | Zotero cleanup | (1) Mark unread / read<br>(2) Retag items<br>(3) Pull out PDFs that should be archived | zotero-skills or zotero-gpt | All researchers |
| **Monthly** | Research progress brief | (1) Pull recent notes from Obsidian + Zotero + NotebookLM<br>(2) Summarize 5 progress points<br>(3) Send to your advisor | research-hub | People using all 3 tools |
| **Per paper** | Final pre-submission audit | (1) banned-word audit<br>(2) figure-text coupling check<br>(3) submission checklist | academic-writing-skills | Final week before submission |
| **Per paper** | Multi-agent peer review | (1) Claude reviews logic / argument<br>(2) Codex checks code / table numbers<br>(3) Gemini reviews prose / clarity | codex-delegate + gemini-delegate | Pre-submission second opinion |
> 💡 **Starter playbook**: run the daily inbox triage and writing sprint for one month first. Add advanced workflows only after the habit sticks.
## Tier Recommendations
Researchers do not need to install Claude Code on day one. This is the recommended progression:
| Tier | Tools | Best for | Learning cost |
|---|---|---|---|
| **Tier 0** | Claude.ai web + NotebookLM | Non-programming researchers, humanities / social sciences, clinical research | 0 (browser skills are enough) |
| **Tier 1** | Claude Desktop + Zotero MCP / Obsidian MCP | Researchers already using Zotero / Obsidian | Half-day setup |
| **Tier 2** | Claude Code + ai-research-skills | Computational researchers who mostly write / edit code | 1-2 days to get started |
| **Tier 3** | Claude Code + codex-delegate + gemini-delegate + research-hub | People building a multi-LLM research pipeline across multiple tools | 1 week setup + ongoing tuning |
**Most researchers can stop at Tier 1-2**. Tier 3 is worth it only when you have a lot of repeated workflows, such as running the same paper synthesis every week.
branches/for-researcher.md
+208
View File
@@ -0,0 +1,208 @@
# 研究者延伸路線（For Researchers）
> **繁體中文** | [简体中文](./for-researcher.zh-Hans.md) | [English](./for-researcher.en.md)
> 🚀 **計算型研究者**（會跑 Python script、有 API key、會用 git）可直接進階；**非程式背景研究者**（人文社科、臨床研究、文獻為主）可先從文獻 Q&A（NotebookLM）、Zotero AI 工具開始、需要時再看 [`resources/setup-guide.md` A-C](../resources/setup-guide.md)。
> [← 回主路線 README](../README.md) · 走完 **Track A 的 A3** 或 **Track B 的 Stage 7** 後從這裡接續。把 agentic AI 應用到研究流程上。
## 使用情境（研究階段 × AI 怎麼幫）
研究者一天分成幾個階段、AI 在每個階段的角色不同。下表幫你定位：
| 階段 | 你常遇到的痛點 | AI 能幫的部分 | 推薦工具（從輕到重） |
|---|---|---|---|
| **文獻探索** | 不知道某個領域有哪些經典 paper | 推薦 + 摘要 + 比較 | NotebookLM → paper-qa → gpt-researcher |
| **文獻精讀** | PDF 翻一半就忘 / 抓不到 claim | 抓 claim、figure、citation、做筆記 | Zotero + zotero-gpt → zotero-skills |
| **研究設計** | RQ 模糊、不知選哪個 method | 對話釐清、列出 trade-off | Claude.ai 對話 → ai-research-skills |
| **實驗 / 寫程式** | 重複 boilerplate、寫 plot 浪費時間 | 寫 / 改 code、batch refactor | Claude Code → codex-delegate |
| **論文撰寫** | 草稿卡關、句子不通 | 大綱 → 段落 → 潤色 | Claude.ai → gemini-delegate（長稿） |
| **改稿 / 投稿** | 期刊規範一堆、容易漏 | banned-word / figure-text / submission checklist | academic-writing-skills |
| **跨 paper synthesis** | 5 篇 paper 互相對話、context 爆 | 1M token 一次讀完 + 整理 | gemini-delegate |
> 💡 **計算型 vs 非程式背景**：表中「推薦工具」由輕到重——非程式背景研究者先停在每行**第一個**就夠了；計算型研究者要自動化才往後挑。
## 精選 Projects
> 💡 **想把 Claude Code 接到 NotebookLM、Obsidian、Notion、Excel、PDF、Excalidraw 等研究常用工具？** 65+ 個整合在 [`resources/mcp-skills-catalog.md`](../resources/mcp-skills-catalog.md)（按使用情境分類）。下面這節保留「研究專屬」的工具與 marketplace。
### 研究流程 Marketplace
#### [flonat/claude-research](https://github.com/flonat/claude-research) ⭐⭐⭐
給博士研究者的 Claude Code 基礎建設——學術流程用的 skill、agent、hook、規則。LaTeX / 文獻管理為主。
---
### 文獻 RAG / Q&A
#### [Future-House/paper-qa](https://github.com/Future-House/paper-qa) ⭐⭐⭐⭐⭐
| 欄位 | 內容 |
|---|---|
| Stars | ★ 8k+ |
| License | Apache-2.0 |
**教什麼**：對 PDF 文件以 **citation-grounded Q&A** 為設計目標——每個答案附句子層級的引用、減少幻覺風險。實際準確率依文件類型而異、評測結果以官方 benchmark / paper 為準。
**適合誰**：寫文獻回顧、需要「查文獻時答案要可追溯」的研究者。比一般 RAG 更嚴謹。
---
#### [assafelovic/gpt-researcher](https://github.com/assafelovic/gpt-researcher) ⭐⭐⭐⭐
| 欄位 | 內容 |
|---|---|
| Stars | ★ 27k+ |
| License | Apache-2.0 |
**教什麼**：自主 deep-research agent——planner + multi-source crawl + report 合成。給定一個研究主題，自動產出 markdown / PDF brief。
**適合誰**：要快速 scope 新題目、產 research brief 的研究者。
---
### 大綱與寫作
#### [stanford-oval/storm](https://github.com/stanford-oval/storm) ⭐⭐⭐⭐
| 欄位 | 內容 |
|---|---|
| Stars | ★ 28k+ |
| License | MIT |
**教什麼**：multi-perspective outline-then-write pipeline——**白話三步**：(1) 先模擬不同觀點提出問題、(2) 把問題整理成大綱、(3) 最後生成 Wikipedia-style 草稿。Stanford OVAL 出品。
**適合誰**：想學「**outline-driven 寫作**」的人。從零產主題 brief 時的好工具，類似 NotebookLM structured report 流程的開源版。
**備註**：最後一次推送已超過 6 個月，使用前確認最新 commit 日期。
---
#### [kaixindelele/ChatPaper](https://github.com/kaixindelele/ChatPaper) ⭐⭐⭐⭐⭐（中文讀者）
| 欄位 | 內容 |
|---|---|
| 語言 | 中文 + Python |
| Stars | ★ 19k+ |
| License | NOASSERTION（自訂條款，非商用） |
**教什麼**：中文研究者向的 arXiv 全流程工具——論文總結 + 翻譯 + 潤色 + 審稿回覆生成。中國研究團隊維護，預設值對中文場景友善。
**適合誰**：中文研究生想找對中文友善的 paper 全流程入門工具。
**備註**：License 是自訂的非商用條款，使用前請先讀原始條款；研究或個人用途常見，但條款還是要自己看過確認。
---
### 文獻管理整合
#### [MuiseDestiny/zotero-gpt](https://github.com/MuiseDestiny/zotero-gpt) ⭐⭐⭐⭐
| 欄位 | 內容 |
|---|---|
| Stars | ★ 7k+ |
| License | AGPL-3.0 |
**教什麼**：Zotero 的 LLM plugin——可以跟你的文獻庫對話、總結 selection、生成 inline notes。
**適合誰**：Zotero 重度使用者，想在閱讀流程裡直接接 AI 而不用切到別的工具。
**備註**：AGPL-3.0 license（傳染性開源）— 修改後要散布的衍生產品需遵守條款。
---
### Multi-LLM 研究組合（本 repo 維護者的研究 setup）
研究流程裡有些任務 Claude 一個就夠（對話、設計、review），有些 Claude 做會浪費 token（大批 code refactor、長稿 draft）。維護者實際用的搭配是 **Claude 當 planner / reviewer、Codex 跑程式、Gemini 跑長稿**——下表列何時用哪個：
| 任務類型 | 例子 | 用哪個 LLM | 為什麼 |
|---|---|---|---|
| 研究設計 / 假設討論 | 「這個 RQ 該用 logistic vs survival？」 | Claude.ai 對話 | 對話協作、context memory |
| 寫 / 改 code | 「50 個 simulation script 都加 logging」 | codex-delegate | 機械式編輯快、不燒 Claude token |
| 寫長稿（中英文） | 「draft 一個 8 頁 paper section」 | gemini-delegate | 1M context、長 prose 強項 |
| Second opinion | 「請 Gemini 看我的 discussion 段落」 | gemini-delegate | LLM-vs-LLM 對照、容易看出 Claude 自身偏誤 |
| 投稿前 audit | 「跑 banned-word + figure-text checklist」 | academic-writing-skills | structured audit、不靠 LLM 即興判斷 |
#### 維護者自用的 6 個研究 skill
> ⚠️ **揭露**：以下 6 個工具是維護者 [@WenyuChiou](https://github.com/WenyuChiou)（Lehigh CEE PhD candidate）日常在用的研究 skills、公開讓有相似需求的人用。**未經第三方獨立評測**——適合 PhD 學位寫作 / 跨 paper 文獻整理這類流程；不一定適合你的領域。詳細 entry 看 [`resources/mcp-skills-catalog.md` 13 + 14](../resources/mcp-skills-catalog.md#13-研究工作流-skills學術--paper--文獻)。
| 工具 | 適合階段 | 一句話 |
|---|---|---|
| **[ai-research-skills](https://github.com/WenyuChiou/ai-research-skills)** ⭐⭐⭐⭐⭐ | 全流程 | 14 個研究 skill 打包成 5-plugin marketplace、一個指令裝整套 |
| **[research-hub](https://github.com/WenyuChiou/research-hub)** ⭐⭐⭐⭐ | 文獻整理 | Zotero + Obsidian + NotebookLM 三工具整合 workspace、CLI / MCP / REST / dashboard 四介面 |
| **[zotero-skills](https://github.com/WenyuChiou/zotero-skills)** ⭐⭐⭐⭐ | 文獻管理 | Zotero CLI skill（搜 / 加 / 分類 / 標記）——跟 zotero-gpt 互補（後者在 Zotero 裡 chat、這份從外部操作） |
| **[academic-writing-skills](https://github.com/WenyuChiou/academic-writing-skills)** ⭐⭐⭐ | 投稿前 | banned-word audit、figure-text coupling、submission checklist；per-paper 可自訂 journal_format / style_overrides |
| **[codex-delegate](https://github.com/WenyuChiou/codex-delegate)** ⭐⭐⭐⭐⭐ | 寫程式 | Claude planner + Codex executor 的標準 skill——batch refactor / boilerplate / migration |
| **[gemini-delegate-skill](https://github.com/WenyuChiou/gemini-delegate-skill)** ⭐⭐⭐⭐ | 長稿 / synthesis | Claude planner + Gemini 寫 1M context 長文 / CJK / second-opinion |
---
### Multi-Agent for Research
#### [langchain-ai/open_deep_research](https://github.com/langchain-ai/open_deep_research) ⭐⭐⭐⭐⭐
| 欄位 | 內容 |
|---|---|
| Stars | ★ 11k+ |
| License | MIT |
**教什麼**：開源版的 Deep Research——支援單 agent 跟 supervisor + multi-researcher 兩種架構（multi-agent 那條目前在 `src/legacy/`）、平行搜尋、再合成成有引用的 report。是學「LLM agent 怎麼自動產出有引用 brief」的好參考。
**適合誰**：要打造「agent 自動產出有引用 brief」工作流程的研究者。是這個分類最 canonical 的開源選擇。
**備註**：依賴 LangGraph + 搜尋 tool（要 API key）。
---
#### [SakanaAI/AI-Scientist-v2](https://github.com/SakanaAI/AI-Scientist-v2) ⭐⭐⭐⭐
| 欄位 | 內容 |
|---|---|
| Stars | ★ 6k+ |
| License | The AI Scientist Source Code License（source-available，非商用 + 有 manuscript-disclosure 條款） |
**教什麼**：端到端的 multi-agent 科學研究 loop：構想 → 寫程式 → 跑實驗 → 寫 paper → 互審。Sakana AI 的「AI 寫整篇 ML paper」研究實作。
**適合誰**：想看「多個 agent 跑完整研究 lifecycle 會長什麼樣」的研究者。研究架構參考、不是 production 工具。
**備註**：產出是 demo 等級（不是直接投稿用），ML / CS 領域偏多。License 是自訂的 source-available 條款（含 manuscript-disclosure 規定），使用前請先讀 LICENSE 檔。
---
> 還缺：peer-review 自動化、conference review pipeline 的活躍開源案例。如果你做過或知道有，歡迎開 PR。
## 必修閱讀
1. [The Effortless Academic — Claude Code beginner guides](https://effortlessacademic.com/claude-code-and-cowork-for-academics-beginner-guide-part-1/)
2. [Pedro Sant'Anna — Researcher setup guide](https://paulgp.substack.com/p/getting-started-with-claude-code)
## 必練流程（按使用頻率）
研究者用 AI 的最大誤區是「只在卡關才打開 ChatGPT」。把 AI 變成日常工具的關鍵是**設好頻率**——下表 7 條都是維護者自己每週都在跑的、不是空想。
| 頻率 | 流程 | 怎麼做（≤ 3 步） | 推薦工具 | 適合誰 |
|---|---|---|---|---|
| **每天** | 文獻 inbox 分流 | (1) 把昨天看到的 paper 丟 paper-qa<br>(2) 抓 claim + 4-5 行 summary<br>(3) 進 Zotero / Obsidian | paper-qa + zotero-gpt | 全研究者 |
| **每天** | 寫作 sprint（25 min） | (1) 寫一段給 Claude.ai<br>(2) 跑 banned-word + figure-text audit<br>(3) 改完進 main draft | Claude.ai + academic-writing-skills | 寫 paper 階段 |
| **每週** | 跨 paper synthesis | (1) 把 5-10 篇 PDF 餵 Gemini<br>(2) 問「這幾篇 disagree 在哪」<br>(3) 寫成 1 頁 brief | gemini-delegate（1M context） | 計算型 |
| **每週** | Zotero 整理 | (1) 標未讀 / 已讀<br>(2) 重 tag<br>(3) 抓出該歸檔的 PDF | zotero-skills 或 zotero-gpt | 全研究者 |
| **每月** | 研究進度 brief | (1) 從 Obsidian + Zotero + NotebookLM 抓近期筆記<br>(2) 整理出 5 個進度點<br>(3) 送指導教授 | research-hub | 同時用 3 工具的人 |
| **Per paper** | 投稿前 final audit | (1) banned-word audit<br>(2) figure-text coupling check<br>(3) submission checklist | academic-writing-skills | 投稿前 1 週 |
| **Per paper** | Multi-agent peer review | (1) Claude 看 logic / argument<br>(2) Codex 看 code / table 數字<br>(3) Gemini 看 prose / clarity | codex-delegate + gemini-delegate | 投稿前 second-opinion |
> 💡 **新手起手式**：先做「每天 inbox 分流」+「寫作 sprint」兩條一個月、習慣後再加進階流程。一次裝太多會養不起來。
## 層級建議
研究者不需要一開始就裝 Claude Code。下表是建議的進階路徑：
| Tier | 工具 | 適合誰 | 學習成本 |
|---|---|---|---|
| **Tier 0** | Claude.ai 網頁版 + NotebookLM | 非程式背景、人文社科、臨床研究 | 0（會用瀏覽器就行） |
| **Tier 1** | Claude Desktop + Zotero MCP / Obsidian MCP | 已有 Zotero / Obsidian 習慣的研究者 | 半天裝好 |
| **Tier 2** | Claude Code + ai-research-skills | 計算型研究者、寫 / 改程式為主 | 1-2 天上手 |
| **Tier 3** | Claude Code + codex-delegate + gemini-delegate + research-hub | 想跑 multi-LLM 研究 pipeline、跨多工具整合 | 1 週 setup + 持續調 |
**多數研究者停在 Tier 1-2 就夠了**——Tier 3 是有大量重複流程（譬如每週跑同樣的 paper synthesis）才值得。
branches/for-researcher.zh-Hans.md
+208
View File
@@ -0,0 +1,208 @@
# 研究者延伸路线（For Researchers）
> [繁體中文](./for-researcher.md) | **简体中文** | [English](./for-researcher.en.md)
> 🚀 **计算型研究者**（会跑 Python script、有 API key、会用 git）可直接进阶；**非程序背景研究者**（人文社科、临床研究、文献为主）可先从文献 Q&A（NotebookLM）、Zotero AI 工具开始，需要时再看 [`resources/setup-guide.zh-Hans.md` A-C](../resources/setup-guide.zh-Hans.md)。
> [← 回主路线 README](../README.zh-Hans.md) · 走完 **Track A 的 A3** 或 **Track B 的 Stage 7** 后从这里接续。把 agentic AI 应用到研究流程上。
## 使用场景（研究阶段 × AI 怎么帮）
研究者一天分成几个阶段，AI 在每个阶段的角色不同。下表帮你定位：
| 阶段 | 你常遇到的痛点 | AI 能帮的部分 | 推荐工具（从轻到重） |
|---|---|---|---|
| **文献探索** | 不知道某个领域有哪些经典 paper | 推荐 + 摘要 + 比较 | NotebookLM → paper-qa → gpt-researcher |
| **文献精读** | PDF 翻一半就忘 / 抓不到 claim | 抓 claim、figure、citation、做笔记 | Zotero + zotero-gpt → zotero-skills |
| **研究设计** | RQ 模糊、不知选哪个 method | 对话厘清、列出 trade-off | Claude.ai 对话 → ai-research-skills |
| **实验 / 写代码** | 重复 boilerplate、写 plot 浪费时间 | 写 / 改 code、batch refactor | Claude Code → codex-delegate |
| **论文撰写** | 草稿卡关、句子不通 | 大纲 → 段落 → 润色 | Claude.ai → gemini-delegate（长稿） |
| **改稿 / 投稿** | 期刊规范一堆、容易漏 | banned-word / figure-text / submission checklist | academic-writing-skills |
| **跨 paper synthesis** | 5 篇 paper 互相对话、context 爆 | 1M token 一次读完 + 整理 | gemini-delegate |
> 💡 **计算型 vs 非程序背景**：表中“推荐工具”由轻到重——非程序背景研究者先停在每行**第一个**就够了；计算型研究者要自动化才往后挑。
## 精选 Projects
> 💡 **想把 Claude Code 接到 NotebookLM、Obsidian、Notion、Excel、PDF、Excalidraw 等研究常用工具？** 65+ 个集成在 [`resources/mcp-skills-catalog.zh-Hans.md`](../resources/mcp-skills-catalog.zh-Hans.md)（按使用场景分类）。下面这节保留“研究专属”的工具与 marketplace。
### 研究流程 Marketplace
#### [flonat/claude-research](https://github.com/flonat/claude-research) ⭐⭐⭐
给博士研究者的 Claude Code 基础建设——学术流程用的 skill、agent、hook、规则。LaTeX / 文献管理为主。
---
### 文献 RAG / Q&A
#### [Future-House/paper-qa](https://github.com/Future-House/paper-qa) ⭐⭐⭐⭐⭐
| 栏位 | 内容 |
|---|---|
| Stars | ★ 8k+ |
| License | Apache-2.0 |
**教什么**：对 PDF 文件以 **citation-grounded Q&A** 为设计目标——每个答案附句子层级的引用、减少幻觉风险。实际准确率依文件类型而异，评测结果以官方 benchmark / paper 为准。
**适合谁**：写文献回顾、需要“查文献时答案要可追溯”的研究者。比一般 RAG 更严谨。
---
#### [assafelovic/gpt-researcher](https://github.com/assafelovic/gpt-researcher) ⭐⭐⭐⭐
| 栏位 | 内容 |
|---|---|
| Stars | ★ 27k+ |
| License | Apache-2.0 |
**教什么**：自主 deep-research agent——planner + multi-source crawl + report 合成。给定一个研究主题，自动产出 markdown / PDF brief。
**适合谁**：要快速 scope 新题目、产 research brief 的研究者。
---
### 大纲与写作
#### [stanford-oval/storm](https://github.com/stanford-oval/storm) ⭐⭐⭐⭐
| 栏位 | 内容 |
|---|---|
| Stars | ★ 28k+ |
| License | MIT |
**教什么**：multi-perspective outline-then-write pipeline——**白话三步**：(1) 先模拟不同观点提出问题、(2) 把问题整理成大纲、(3) 最后生成 Wikipedia-style 草稿。Stanford OVAL 出品。
**适合谁**：想学“**outline-driven 写作**”的人。从零产主题 brief 时的好工具，类似 NotebookLM structured report 流程的开源版。
**备注**：最后一次推送已超过 6 个月，使用前确认最新 commit 日期。
---
#### [kaixindelele/ChatPaper](https://github.com/kaixindelele/ChatPaper) ⭐⭐⭐⭐⭐（中文读者）
| 栏位 | 内容 |
|---|---|
| 语言 | 中文 + Python |
| Stars | ★ 19k+ |
| License | NOASSERTION（自定义条款，非商用） |
**教什么**：中文研究者向的 arXiv 全流程工具——论文总结 + 翻译 + 润色 + 审稿回复生成。中国研究团队维护，默认值对中文场景友好。
**适合谁**：中文研究生想找对中文友好的 paper 全流程入门工具。
**备注**：License 是自定义的非商用条款，使用前请先读原始条款；研究或个人用途常见，但条款还是要自己看过确认。
---
### 文献管理集成
#### [MuiseDestiny/zotero-gpt](https://github.com/MuiseDestiny/zotero-gpt) ⭐⭐⭐⭐
| 栏位 | 内容 |
|---|---|
| Stars | ★ 7k+ |
| License | AGPL-3.0 |
**教什么**：Zotero 的 LLM plugin——可以跟你的文献库对话、总结 selection、生成 inline notes。
**适合谁**：Zotero 重度用户，想在阅读流程里直接接 AI 而不用切到别的工具。
**备注**：AGPL-3.0 license（传染性开源）— 修改后要散布的衍生产品需遵守条款。
---
### Multi-LLM 研究组合（本 repo 维护者的研究 setup）
研究流程里有些任务 Claude 一个就够（对话、设计、review），有些 Claude 做会浪费 token（大批 code refactor、长稿 draft）。维护者实际用的搭配是 **Claude 当 planner / reviewer、Codex 跑程序、Gemini 跑长稿**——下表列什么时候用哪个：
| 任务类型 | 例子 | 用哪个 LLM | 为什么 |
|---|---|---|---|
| 研究设计 / 假设讨论 | “这个 RQ 该用 logistic vs survival？” | Claude.ai 对话 | 对话协作、context memory |
| 写 / 改 code | “50 个 simulation script 都加 logging” | codex-delegate | 机械式编辑快、不烧 Claude token |
| 写长稿（中英文） | “draft 一个 8 页 paper section” | gemini-delegate | 1M context、长 prose 强项 |
| Second opinion | “请 Gemini 看我的 discussion 段落” | gemini-delegate | LLM-vs-LLM 对照，容易看出 Claude 自身偏误 |
| 投稿前 audit | “跑 banned-word + figure-text checklist” | academic-writing-skills | structured audit，不靠 LLM 即兴判断 |
#### 维护者自用的 6 个研究 skill
> ⚠️ **披露**：以下 6 个工具是维护者 [@WenyuChiou](https://github.com/WenyuChiou)（Lehigh CEE PhD candidate）日常在用的研究 skills，公开让有相似需求的人用。**未经第三方独立评测**——适合 PhD 学位写作 / 跨 paper 文献整理这类流程；不一定适合你的领域。详细 entry 看 [`resources/mcp-skills-catalog.zh-Hans.md` 13 + 14](../resources/mcp-skills-catalog.zh-Hans.md#13-研究工作流-skills学术--paper--文献)。
| 工具 | 适合阶段 | 一句话 |
|---|---|---|
| **[ai-research-skills](https://github.com/WenyuChiou/ai-research-skills)** ⭐⭐⭐⭐⭐ | 全流程 | 14 个研究 skill 打包成 5-plugin marketplace，一个指令装整套 |
| **[research-hub](https://github.com/WenyuChiou/research-hub)** ⭐⭐⭐⭐ | 文献整理 | Zotero + Obsidian + NotebookLM 三工具集成 workspace，CLI / MCP / REST / dashboard 四种接口 |
| **[zotero-skills](https://github.com/WenyuChiou/zotero-skills)** ⭐⭐⭐⭐ | 文献管理 | Zotero CLI skill（搜 / 加 / 分类 / 标记）——跟 zotero-gpt 互补（后者在 Zotero 里 chat，这份从外部操作） |
| **[academic-writing-skills](https://github.com/WenyuChiou/academic-writing-skills)** ⭐⭐⭐ | 投稿前 | banned-word audit、figure-text coupling、submission checklist；per-paper 可定制 journal_format / style_overrides |
| **[codex-delegate](https://github.com/WenyuChiou/codex-delegate)** ⭐⭐⭐⭐⭐ | 写代码 | Claude planner + Codex executor 的标准 skill——batch refactor / boilerplate / migration |
| **[gemini-delegate-skill](https://github.com/WenyuChiou/gemini-delegate-skill)** ⭐⭐⭐⭐ | 长稿 / synthesis | Claude planner + Gemini 写 1M context 长文 / CJK / second-opinion |
---
### Multi-Agent for Research
#### [langchain-ai/open_deep_research](https://github.com/langchain-ai/open_deep_research) ⭐⭐⭐⭐⭐
| 栏位 | 内容 |
|---|---|
| Stars | ★ 11k+ |
| License | MIT |
**教什么**：开源版的 Deep Research——支持单 agent 跟 supervisor + multi-researcher 两种架构（multi-agent 那条目前在 `src/legacy/`）、平行搜索、再合成为有引用的 report。是学“LLM agent 怎么自动产出有引用 brief”的好参考。
**适合谁**：要打造“agent 自动产出有引用 brief”工作流程的研究者。是这个分类最 canonical 的开源选择。
**备注**：依赖 LangGraph + 搜索 tool（要 API key）。
---
#### [SakanaAI/AI-Scientist-v2](https://github.com/SakanaAI/AI-Scientist-v2) ⭐⭐⭐⭐
| 栏位 | 内容 |
|---|---|
| Stars | ★ 6k+ |
| License | The AI Scientist Source Code License（source-available，非商用 + 有 manuscript-disclosure 条款） |
**教什么**：端到端的 multi-agent 科学研究 loop：构想 → 写代码 → 跑实验 → 写 paper → 互审。Sakana AI 的“AI 写整篇 ML paper”研究实践。
**适合谁**：想看“多个 agent 跑完整研究生命周期会长什么样”的研究者。研究架构参考、不是 production 工具。
**备注**：产出是 demo 级别（不是直接投稿用），ML / CS 领域偏多。License 是自定义的 source-available 条款（含 manuscript-disclosure 规定），使用前请先读 LICENSE 文件。
---
> 还缺：peer-review 自动化、conference review pipeline 的活跃开源案例。如果你做过或知道有，欢迎开 PR。
## 必修阅读
1. [The Effortless Academic — Claude Code beginner guides](https://effortlessacademic.com/claude-code-and-cowork-for-academics-beginner-guide-part-1/)
2. [Pedro Sant'Anna — Researcher setup guide](https://paulgp.substack.com/p/getting-started-with-claude-code)
## 必练流程（按使用频率）
研究者用 AI 的最大误区是“只在卡关才打开 ChatGPT”。把 AI 变成日常工具的关键是**设好频率**——下表 7 条都是维护者自己每周都在跑的，不是空想。
| 频率 | 流程 | 怎么做（≤ 3 步） | 推荐工具 | 适合谁 |
|---|---|---|---|---|
| **每天** | 文献 inbox 分流 | (1) 把昨天看到的 paper 丢 paper-qa<br>(2) 抓 claim + 4-5 行 summary<br>(3) 进 Zotero / Obsidian | paper-qa + zotero-gpt | 全研究者 |
| **每天** | 写作 sprint（25 min） | (1) 写一段给 Claude.ai<br>(2) 跑 banned-word + figure-text audit<br>(3) 改完进 main draft | Claude.ai + academic-writing-skills | 写 paper 阶段 |
| **每周** | 跨 paper synthesis | (1) 把 5-10 篇 PDF 喂 Gemini<br>(2) 问“这几篇 disagree 在哪”<br>(3) 写成 1 页 brief | gemini-delegate（1M context） | 计算型 |
| **每周** | Zotero 整理 | (1) 标未读 / 已读<br>(2) 重 tag<br>(3) 抓出该归档的 PDF | zotero-skills 或 zotero-gpt | 全研究者 |
| **每月** | 研究进度 brief | (1) 从 Obsidian + Zotero + NotebookLM 抓近期笔记<br>(2) 整理出 5 个进度点<br>(3) 送指导教授 | research-hub | 同时用 3 工具的人 |
| **Per paper** | 投稿前 final audit | (1) banned-word audit<br>(2) figure-text coupling check<br>(3) submission checklist | academic-writing-skills | 投稿前 1 周 |
| **Per paper** | Multi-agent peer review | (1) Claude 看 logic / argument<br>(2) Codex 看 code / table 数字<br>(3) Gemini 看 prose / clarity | codex-delegate + gemini-delegate | 投稿前 second-opinion |
> 💡 **新手起手式**：先做“每天 inbox 分流”+“写作 sprint”两条一个月，习惯后再加进阶流程。一次装太多会养不起来。
## 层级建议
研究者不需要一开始就装 Claude Code。下表是建议的进阶路径：
| Tier | 工具 | 适合谁 | 学习成本 |
|---|---|---|---|
| **Tier 0** | Claude.ai 网页版 + NotebookLM | 非程序背景、人文社科、临床研究 | 0（会用浏览器就行） |
| **Tier 1** | Claude Desktop + Zotero MCP / Obsidian MCP | 已有 Zotero / Obsidian 习惯的研究者 | 半天装好 |
| **Tier 2** | Claude Code + ai-research-skills | 计算型研究者、写 / 改程序为主 | 1-2 天上手 |
| **Tier 3** | Claude Code + codex-delegate + gemini-delegate + research-hub | 想跑 multi-LLM 研究 pipeline、跨多工具集成 | 1 周 setup + 持续调 |
**多数研究者停在 Tier 1-2 就够了**——Tier 3 是有大量重复流程（比如每周跑同样的 paper synthesis）才值得。
branches/for-teacher.en.md
+226
View File
@@ -0,0 +1,226 @@
# Extension Path: For Teachers / Educators
> [繁體中文](./for-teacher.md) | [简体中文](./for-teacher.zh-Hans.md) | **English**
> 🚀 **Most teachers can start directly with Claude.ai (web) + NotebookLM, without any setup**. Only read [`resources/setup-guide.en.md` A-C](../resources/setup-guide.en.md) (about 30 minutes to install what you need) when you need to automate repeated workflows (Tier 2+, such as generating 50 parent letters every week).
> [← Back to main path README](../README.en.md) · Continue here after **Track A's A3** or **Track B's Stage 7**. Apply agentic AI to teaching workflows.
## Use Cases
Teacher-facing AI use cases can first be read as three branches: **lesson prep and class material creation**, **classroom and learning support**, and **other use cases**.
This grouping follows common AI in Education discussions around administration, instruction, and learning, while also reflecting recent work on generative AI for material creation, feedback, and interactive support (Chen et al., 2020; Mittal et al., 2024). Start with teacher oversight principles and boundaries, then choose the branch that best matches your teaching need.
![Teacher and AI agent use-case overview](../resources/diagrams/teacher-ai-use-cases-overview.jpg)
### What Teachers Should Watch For When Using AI
AI can prepare and assist, but it should not replace teacher judgment. Recent AI in Education and generative AI for education research also emphasizes clear learning goals, safety boundaries, and human review when teachers design AI agents (Chen et al., 2020; Mittal et al., 2024).
- **Keep teacher judgment in the loop**: when student data, grades, or teaching decisions are involved, teachers remain responsible for final review.
- **Avoid giving answers too quickly**: if students interact with an AI agent, design the flow as Socratic dialogue so students explain their reasoning across multiple turns.
- **Align with learning goals**: use fixed prompts, checklists, or school-approved tools to constrain the AI's role and task, so student interaction stays tied to the lesson.
- **Rewrite student questions when needed**: for younger students, such as elementary or middle-school learners, rewrite unclear questions before sending them to the agent.
### Lesson Prep and Class Material Creation
These workflows help teachers prepare materials. The output should still be revised, selected, and checked by the teacher.
- **Lesson plan generation**: turn curriculum standards, unit goals, and student levels into lesson outlines, time allocation, activity design, discussion prompts, and supplementary guides.
- **Quiz / rubric creation**: generate multiple-choice, short-answer, essay questions, answer keys, and scoring criteria from texts, textbook sections, or academic articles.
- **Slide deck preparation, curriculum mapping, and multimedia visualization**: turn textbook chapters or teacher notes into slide outlines, handout structures, weekly sequences, prerequisite knowledge, assessment checkpoints, images, 3D objects, video scripts, GIFs, or classroom presentation assets.
- **Student feedback synthesis and analysis**: summarize student answers, assignments, or class responses to identify common misconceptions, remediation needs, and next-step practice.
- **Multilingual material translation and adaptation**: rewrite or translate material for different languages, and generate text-to-speech assets when useful.
- **Materials for interactive games, activities, and virtual simulation scenarios**: prepare educational games, rhymes, task cards, role cards, scenario text, or simulation backgrounds; for actual interaction or activity design, see the next section on classroom and learning support.
### Classroom and Learning Support
![Classroom and learning support use cases](../resources/diagrams/teacher-ai-classroom-use-cases.jpg)
These workflows help students understand, practice, and interact. AI acts more like a teaching assistant or activity support tool. Note that a single lesson does not need to include every element; choose the moments where an AI agent design actually fits the learning activity.
- **Immersive learning and realistic scenario practice**: use realistic simulation, role-play, or speaking practice so students can rehearse in near-authentic contexts while lowering cognitive load and hesitation.
- **Curiosity and questioning support**: use Socratic follow-up questions and multi-turn interaction to help students ask clearer questions, explain their reasoning, and develop critical thinking and metacognition.
- **Instant grading and deeper feedback**: help students learn from mistakes by pointing out errors, explaining why they happen, and suggesting revisions instead of only giving a score or answer.
- **Intelligent tutoring and virtual teaching assistants**: answer questions, explain terminology, and provide hints so students receive appropriate support in and beyond class.
- **Adaptive teaching and dynamic paths**: provide difficulty-matched content based on student level, infer the zone of proximal development from learning performance, and offer suitable scaffolding or remediation materials.
### Other Use Cases
These use cases may not happen directly inside a lesson, but they shape teacher work, student support, and education-system operations.
- **Special education support**: use speech-to-text, text-to-speech, and related tools to help students with different needs participate in class.
- **Parent-teacher communication and family learning**: summarize student progress and suggest home-based follow-up activities.
- **Administration and academic integrity**: summarize learning traces, generate reports, or support plagiarism and cheating-risk checks.
- **Career and skill-development guidance**: support career exploration, training-plan design, and weak-spot practice recommendations.
- **Teacher professional development**: summarize teaching methods, education-technology trends, and research insights.
- **Advanced research and business analysis**: support literature review, market-trend analysis, or business-plan drafting.
- **Privacy-preserving synthetic data**: generate anonymized synthetic data for research or system testing without directly exposing personal data.
### References
- Chen, L., Chen, P., & Lin, Z. (2020). [Artificial Intelligence in Education: A Review](https://doi.org/10.1109/ACCESS.2020.2988510). *IEEE Access*, 8, 75264-75278.
- Mittal, U., Sai, S., Chamola, V., & Sangwan, D. (2024). [A Comprehensive Review on Generative AI for Education](https://doi.org/10.1109/ACCESS.2024.3468368). *IEEE Access*, 12, 142733-142759.
## Curated Projects
### Teaching Workflow Skills
(Most are not yet skill-marketplace packaged. This branch has the most room for community contribution — see CONTRIBUTING.md.)
### Useful Building Blocks
#### [obra/superpowers](https://github.com/obra/superpowers) ⭐⭐⭐⭐
General writing / brainstorming skills. Adaptable for lesson prep.
#### Advanced automation: [Claude Code](https://github.com/anthropics/claude-code) (with custom CLAUDE.md) ⭐⭐⭐⭐⭐
★ 120k+ — **The basic teacher stack is Claude.ai (web) + NotebookLM + Google Classroom / LMS integrations**; start there. **Upgrade to Claude Code only when you already have repeatable batch workflows** (such as generating 50 parent letters every week or analyzing student feedback every semester), and expect to learn some CLI.
### Teaching Course Materials (for teachers preparing classes)
#### [huggingface/agents-course](https://github.com/huggingface/agents-course) ⭐⭐⭐⭐
| Field | Value |
|---|---|
| Stars | ★ 28k+ |
| License | Apache-2.0 |
**What it teaches**: Hugging Face's official agents curriculum — notebooks, exercises, certifications. A ready-made **AI agent teaching artifact**.
**Best for**: Teachers running an "AI agents intro" workshop or class who want existing materials to teach from or adapt.
**Notes**: This teaches *how to build agents* — it's not an "AI tutor for students" tool.
---
#### [datawhalechina/llm-universe](https://github.com/datawhalechina/llm-universe) ⭐⭐⭐⭐ (Chinese)
| Field | Value |
|---|---|
| Language | Chinese (zh-Hans) |
| Stars | ★ 13k+ |
| License | NOASSERTION |
**What it teaches**: Datawhale's Chinese-language LLM application development course — RAG, agents, chapter exercises. A ready-made template for Chinese-speaking teachers preparing class material.
**Best for**: Chinese-language teachers wanting a ready LLM curriculum to adapt to their students' level.
**Notes**: Same caveat as `huggingface/agents-course` — it's "teach students to build LLM apps," not "AI assistant for the teacher."
---
### Prompt Libraries
#### [f/awesome-chatgpt-prompts](https://github.com/f/awesome-chatgpt-prompts) ⭐⭐⭐⭐
| Field | Value |
|---|---|
| Stars | ★ 161k+ |
| License | NOASSERTION (CC0 / public-domain-style, but no SPDX) |
**What it teaches**: Community-maintained prompt megacatalog — "act as X" templates covering hundreds of roles (teacher, interviewer, stand-up comedian, debater, ...). Teachers can use it as "prompt writing examples" to show students, or borrow specific prompts for in-class demos.
**Best for**: Teachers introducing "prompt engineering" who want concrete examples of different writing styles to compare.
**Notes**: Quality varies — treat as a sourcebook to pick from, not "use everything as-is."
---
### Reading Material
#### [The Effortless Academic — Beginner Guides](https://effortlessacademic.com/claude-code-and-cowork-for-academics-beginner-guide-part-1/)
Multi-part guide for academics adopting Claude Code, applicable to teachers.
## Workflows You Can Build (by teaching stage)
Use these 5 templates as starting points and adapt them to your subject:
| Stage | Workflow | Steps (≤3) | Recommended tools | Caveat |
|---|---|---|---|---|
| **Before prep** | Lesson plan generator | (1) Curriculum + topic prompt → outline<br>(2) Outline → slides<br>(3) Slides → assessment items | Claude.ai / NotebookLM | Teacher final review |
| **During prep** | Rubric creation | (1) Provide student work samples + learning goals<br>(2) Ask AI for a 4-level rubric draft<br>(3) Teacher adjusts level boundaries | Claude.ai | Avoid vague terms like "high quality" |
| **Grading work** | Personalized feedback | (1) Student work + rubric → AI feedback draft<br>(2) Teacher reviews and edits each one<br>(3) Send back | Claude.ai | **AI assistance ≠ AI grading**; final grades must be human |
| **Class activity** | Scenario simulation | (1) Learning goal + role setup → dialogue script<br>(2) Run class practice<br>(3) Ask reflection questions | Claude.ai | Socratic follow-up, no direct answers; student input must contain **no PII** |
| **After class** | Personalized remediation material | (1) Summarize common student errors<br>(2) Generate short practice + hints by student level<br>(3) Add extension challenges | Claude.ai | Anonymize student data |
> 💡 **Starter habit**: run the "before-prep lesson plan generator" for one semester first, then add rubric / feedback workflows. ⚠️ Any step involving student data or grading should be checked against the §Privacy + Ethics (Important) section below.
### 3 Copy-Paste Prompt Templates
**1. Lesson outline generator** (paste into Claude.ai):
```
You are a [SUBJECT] teacher. I'm preparing a [DURATION]-minute class for
[GRADE] students on the topic "[TOPIC]". Prior knowledge: [SUMMARY].
Produce:
1. Learning goals (3-4 bullets, use Bloom's taxonomy verbs)
2. Class outline with time allocation
3. 1 in-class activity / discussion prompt
4. 1 follow-up assessment item
Don't introduce content outside the topic I gave.
```
**2. Rubric draft**:
```
I have a [ASSIGNMENT TYPE] for [GRADE] students on [TOPIC].
Learning objectives: [2-3 bullets].
Produce a 4-level rubric (Excellent / Proficient / Developing / Needs work)
with one paragraph per level across 4 dimensions:
content depth / organization / argumentation or calculation / clarity.
Make descriptions concrete and observable, not vague terms like "high quality".
```
**3. Student feedback synthesis**:
```
Below are [N] student submission excerpts:
[PASTE TEXT]
Please:
1. Summarize 3 common strengths across this batch
2. Summarize 3 common weaknesses
3. For the most common weakness, suggest 1-2 things to reinforce next class
Don't write per-student feedback — I'll do that myself.
```
## Privacy + Ethics (Important)
Teachers using LLMs are different from regular users — **student data is involved**. Hard rules:
- **Don't put student PII into public LLMs** (names, IDs, contact info, grades). Anonymize first ("Student A / B / C")
- **AI assistance ≠ AI grading**: drafting feedback / rubrics with LLM is fine, but **final grades require human judgment** — LLMs aren't reliable on complex evaluation yet
- **Disclose to students**: if class material is AI-assisted, disclose it (similar to declaring AI tool use in papers). Teaching integrity matters
- **Fact-check**: LLMs hallucinate citations, scholar names, research data. Domain content **must be verified** before class
- **Student work copyright**: don't bulk-upload student writing to third-party services for analysis — it may involve local privacy law, school policy, and third-party service terms. In the **United States**, also consider FERPA (student record protection); in the **European Union**, GDPR; and in **Taiwan**, the Personal Data Protection Act and school notices. Actual applicability depends on local law and school IT policy
If your school / institution has an AI policy, **that takes priority** over this guide.
## Tier Recommendations for Teachers
Recommended progression. Most teachers should stay at Tier 0-1:
| Tier | Tools | Best for | Learning cost |
|---|---|---|---|
| **Tier 0** | Claude.ai web chat | Occasional lesson prep, one-off tasks, item generation, writing emails. Copy the prompt template above and fill in the topic. | 0 (if you can use a browser) |
| **Tier 1** | Claude Desktop / [NotebookLM](https://notebooklm.google.com/) | Grading / organizing a semester's data, course mapping, bulk-importing reading list PDFs and querying them | 30 minutes |
| **Tier 2+** | Claude Code / CLI / SDK | Repeated automation, such as 30 student submissions every week → auto-generated draft feedback | 1 week; non-coders can ask school IT / a student RA to set it up |
> **Most teachers can stop at Tier 0-1**. Once you're at Tier 2+, follow [Track A — CLI Power User](../tracks/cli/A1-cli-intro.en.md).
## Other Branches Also Apply
Many teachers are also researchers / knowledge workers. These branches overlap:
- **Also doing research** (lit review, paper writing, references) → [Researcher branch](./for-researcher.en.md)
- **Reports / meeting notes / cross-tool integration** (Notion, Excel, email) → [Knowledge Worker branch](./for-knowledge-worker.en.md)
- **Connect AI to Notion / Obsidian / Lark / etc.** → [`resources/mcp-skills-catalog.en.md`](../resources/mcp-skills-catalog.en.md)
## Community Note
This branch is the smallest curated section currently. Contributions especially welcome:
- Lesson plan generation skills
- Subject-specific prompt libraries (literature teacher's prompts, math teacher's prompts, language teacher's prompts...)
- Teacher-specific MCP servers (gradebook integrations, LMS connections like Canvas / Moodle / Google Classroom)
- **Subject + grade-level case studies** (e.g., "I used AI to teach middle-school math for a semester — here's my workflow")
See [CONTRIBUTING.md](../CONTRIBUTING.md).
branches/for-teacher.md
+224
View File
@@ -0,0 +1,224 @@
# 教師延伸路線（For Teachers / Educators）
> **繁體中文** | [简体中文](./for-teacher.zh-Hans.md) | [English](./for-teacher.en.md)
> 🚀 **大多數教師可直接從 Claude.ai（網頁版）+ NotebookLM 開始、不需要任何 setup**。只有當你要自動化重複流程（Tier 2+、例如每週生成 50 份家長信）時、才需要看 [`resources/setup-guide.md` A-C](../resources/setup-guide.md)（30 分鐘從零裝好需要的東西）。
> [← 回主路線 README](../README.md) · 走完 **Track A 的 A3** 或 **Track B 的 Stage 7** 後從這裡接續。把 agentic AI 應用到教學流程上。
## 使用情境
教師使用 AI 的情境可以先看成三個分支：**備課與上課素材製作**、**教學現場與學習輔助**、以及**其他應用場景**。
這樣的分類參考 AI in Education 文獻中常見的行政、教學與學習應用脈絡、也加入生成式 AI 在教材生成、回饋與互動支援上的近期討論（Chen et al., 2020；Mittal et al., 2024）。閱讀時建議先理解教師把關原則與使用邊界、再依自己的教學需求挑一個分支深入。
![教師與 AI agent 使用情境總覽](../resources/diagrams/teacher-ai-use-cases-overview.jpg)
### 教師使用 AI 輔助時要注意什麼
AI 可以幫忙準備和輔助，但不應該直接取代教師判斷。近期 AI in Education 與生成式 AI 教育研究也提醒，教師設計 AI agent 時要保留清楚的教學目標、安全邊界與人工把關（Chen et al., 2020；Mittal et al., 2024）。
- **保留教師最後判斷**：牽涉學生資料、成績、教學決策等重大判斷時，教師仍要負責最後確認。
- **避免直接給答案**：如果要讓學生與 AI agent 互動，可以設計成蘇格拉底式對話，在多輪互動中引導學生說出理由。
- **貼合教學目標**：用固定提示詞、檢查清單、或學校核准的工具設定、限制 AI 的角色與任務、避免學生互動脫離課程目標。
- **調整學生提問**：如果學生年齡較低，例如國小或國中，可以把學生問題先改寫成更清楚的提問，再交給 agent 回答。
### 備課與上課素材製作
這類情境偏向「幫老師準備材料」，輸出通常會被老師再改寫、挑選、檢查。
- **教案生成**：依課綱、單元目標與學生程度，整理課程大綱、時間分配、活動設計、討論提示與補充學習指南。
- **Quiz / 評分量表（rubric）建立**：依文本、課文或學術文章，產生選擇題、簡答題、申論題、參考答案與評分規準。
- **投影片準備、課程地圖、多媒體與視覺化素材**：把課本章節或教師筆記轉成投影片大綱、講義架構、週次安排、先備知識、評量節點、圖像、3D 物件、影片腳本、GIF 或課堂展示素材。
- **學生回饋整理分析**：彙整學生作答、作業或課堂反應，找出常見迷思、需要補救的概念與下一步練習。
- **多語系教材翻譯與轉化**：把教材改寫或翻譯成不同語言版本，也可以產生語音合成素材。
- **互動式遊戲與活動、虛擬模擬場景的素材**：準備教學遊戲、押韻兒歌、任務卡、角色卡、情境文本或模擬場景背景；若要設計實際互動流程或課堂活動，請參考下一節「教學現場與學習輔助」。
### 教學現場與學習輔助
![教學現場與學習輔助應用場景](../resources/diagrams/teacher-ai-classroom-use-cases.jpg)
這類情境偏向「幫學生理解、練習、互動」，AI 比較像教學助教或活動輔助工具。特別注意：不需要在單一教學活動中加入所有要素，而是挑選適合的環節加入 AI agent 設計。
- **沉浸式學習體驗與真實情境演練**：用真實情境模擬、角色扮演或外語口說模擬，讓學生在接近實作的情境中練習，降低認知負荷與退縮感。
- **激發好奇心與提問能力**：透過蘇格拉底式追問與多輪互動，引導學生提出更清楚的問題、說明理由，進一步訓練批判性思考與後設認知。
- **即時批改與深度回饋**：讓學生從錯誤中學習，AI 可以指出錯誤、說明原因、建議修正方向，而不是只給分數或答案。
- **智慧家教與虛擬助教**：協助回答提問、解釋術語、給提示，讓學生在課堂內外都能獲得適度支援。
- **適性教學與動態路徑**：依學生程度提供對應難度內容，並透過學習表現推測近側發展區，提供合適的鷹架與補救素材。
### 其他應用場景
這類情境不一定直接發生在課堂中，但會影響教師工作、學生支援與教育系統運作。
- **特殊教育支援**：透過語音轉文字、文字轉語音等方式，協助不同需求的學生參與課程。
- **親師溝通與家庭教育**：整理學生進度報告，並提供家庭可延伸的輔助學習活動建議。
- **行政管理與學術誠信**：整理學習軌跡、產生報告，或協助進行抄襲與作弊風險檢查。
- **職涯與技能發展輔導**：協助職涯探索、培訓清單規劃，並依弱點推薦練習題。
- **教師專業發展**：摘要教學方法、教育科技趨勢與研究重點，協助教師持續更新。
- **高階研究分析**：輔助文獻分析、快速理解論文研究中提出的教學法或教育心理學。
- **隱私保護與合成資料**：在不直接使用真實個資的前提下，產生匿名合成資料。
### 參考文獻
- Chen, L., Chen, P., & Lin, Z. (2020). [Artificial Intelligence in Education: A Review](https://doi.org/10.1109/ACCESS.2020.2988510). *IEEE Access*, 8, 75264-75278.
- Mittal, U., Sai, S., Chamola, V., & Sangwan, D. (2024). [A Comprehensive Review on Generative AI for Education](https://doi.org/10.1109/ACCESS.2024.3468368). *IEEE Access*, 12, 142733-142759.
## 精選 Projects
### 教學流程 Skills
（大多數還沒有做成 skill marketplace。這個分支最有社群貢獻空間——見 CONTRIBUTING.md。）
### 可用的基礎元件
#### [obra/superpowers](https://github.com/obra/superpowers) ⭐⭐⭐⭐
通用的寫作 / 腦力激盪 skill。可改用在備課上。
#### 進階自動化：[Claude Code](https://github.com/anthropics/claude-code)（搭配自訂 CLAUDE.md）⭐⭐⭐⭐⭐
★ 120k+ — **教師的基礎工具是 Claude.ai（網頁版）+ NotebookLM + Google Classroom / LMS 整合**、先從這裡開始。**只有當你已有會重複跑的批次流程**（如每週生成 50 份家長信、每學期跑學生反饋分析）才升級到 Claude Code、需要學一點 CLI。
### 教學課程素材（給教師備課用）
#### [huggingface/agents-course](https://github.com/huggingface/agents-course) ⭐⭐⭐⭐
| 欄位 | 內容 |
|---|---|
| Stars | ★ 28k+ |
| License | Apache-2.0 |
**教什麼**：Hugging Face 官方的 agent 課程——notebook、練習、結業認證。是一份**現成的「AI agent 教學」素材**。
**適合誰**：要在學校 / 工作坊開「AI agent 入門」課程的老師，可以直接拿來當教材或改編。
**備註**：注意這是「教 AI agent 怎麼建」的教材，不是「老師用 AI 教書」的工具。
---
#### [datawhalechina/llm-universe](https://github.com/datawhalechina/llm-universe) ⭐⭐⭐⭐（中文）
| 欄位 | 內容 |
|---|---|
| 語言 | 中文（zh-Hans） |
| Stars | ★ 13k+ |
| License | NOASSERTION |
**教什麼**：Datawhale 出品的中文 LLM 應用開發課程——含 RAG、agent、章節練習。中文教師備課的現成模板。
**適合誰**：中文教師要找現成可改的 LLM 教材底稿、再針對自己學生程度調整。
**備註**：跟 hf agents-course 一樣，是「教學生建 LLM 應用」的教材，不是「教師端的 AI 助教」。
---
### Prompt 素材庫
#### [f/awesome-chatgpt-prompts](https://github.com/f/awesome-chatgpt-prompts) ⭐⭐⭐⭐
| 欄位 | 內容 |
|---|---|
| Stars | ★ 161k+ |
| License | NOASSERTION（CC0 / public domain 風格，但未提供 SPDX） |
**教什麼**：社群維護的 prompt 大全——「act as X」型樣板涵蓋幾百種角色（老師、面試官、stand-up comedian、辯論者⋯）。教師可以拿來當「prompt 寫法範例」教給學生，或直接借用其中合適的當作課堂示範。
**適合誰**：要教學生「prompt engineering」的老師，找現成例子比較不同寫法的差異。
**備註**：品質不一致——當作素材庫挑選用，不是「全部直接拿去教」。
---
### 閱讀材料
#### [The Effortless Academic — Beginner Guides](https://effortlessacademic.com/claude-code-and-cowork-for-academics-beginner-guide-part-1/)
寫給學術工作者導入 Claude Code 的多篇指南，教師也適用。
## 可以建的流程（按教學階段）
下表 5 條是模板——配合你的學科自行調整：
| 階段 | 流程 | 怎麼做（≤ 3 步） | 推薦工具 | 注意 |
|---|---|---|---|---|
| **備課前** | 教案生成器 | (1) 課綱 + 主題提示 → 大綱<br>(2) 大綱 → 投影片<br>(3) 投影片 → 評量題目 | Claude.ai / NotebookLM | 教師最後審 |
| **備課中** | Rubric 建立 | (1) 給學生作業樣本 + 學習目標<br>(2) 請 AI 草擬 4 級 rubric<br>(3) 教師調整級距 | Claude.ai | 避免「品質好」這種模糊詞 |
| **改作業** | 個別化回饋 | (1) 學生作業 + rubric → AI 寫回饋初稿<br>(2) 教師逐份審 + 改<br>(3) 寄回 | Claude.ai | **AI 輔助 ≠ AI 評分**，最終分數一定人工 |
| **課堂活動** | 情境模擬 | (1) 教學目標 + 角色設定 → 對話腳本<br>(2) 課堂演練<br>(3) 反思問題 | Claude.ai | 蘇格拉底式追問、不直接給答案；學生輸入**不含個資** |
| **課後補救** | 個別化補救教材 | (1) 整理學生常見錯誤<br>(2) 依學生程度 → 小練習 + 提示<br>(3) 延伸挑戰題 | Claude.ai | 注意學生個資匿名化 |
> 💡 **新手起手式**：先做「備課前的教案生成器」一個學期、習慣後再加 rubric / 回饋流程。⚠️ 所有跟學生個資 / 評分相關的步驟都要回頭看下面的 §隱私 + 倫理（重要）章節。
### 3 個可直接複製的 prompt 範本
**1. 教案大綱生成**（複製到 Claude.ai 即可用）：
```
你是一位 [學科] 老師。我要給 [年級] 學生上一堂 [時長] 分鐘的課，主題是「[主題]」。
學生先備知識：[簡述]。請產出：
1. 學習目標（3-4 條，用 Bloom's taxonomy 動詞）
2. 課程大綱（含時間分配）
3. 1 個課堂活動 / 討論題
4. 1 個課後評量題
不要產生超出我給的主題範圍的內容。
```
**2. Rubric 草稿生成**：
```
我有一份 [作業類型] 作業，學生年級 [年級]，主題 [主題]。
學習目標：[列 2-3 條]。
請產出一份 4 級 rubric（卓越 / 熟練 / 發展中 / 待改進），
每級在「內容深度」「組織結構」「論證 / 計算」「表達清晰度」4 個面向各給一段描述。
描述要具體可觀察，不用「品質好」這種模糊詞。
```
**3. 學生回饋整理**：
```
以下是 [N] 份學生作業片段：
[貼上文本]
請：
1. 摘要這批作業共同的 3 個強項
2. 摘要 3 個共同弱點
3. 針對最常見弱點，建議 1-2 個下次上課該加強的環節
不要做個別化評語——我會自己針對個人寫。
```
## 隱私 + 倫理（重要）
教師端用 LLM 跟一般 user 不同，**牽涉學生資料**——以下是 hard rule：
- **不要把學生個資丟進公開 LLM**（姓名、學號、聯絡方式、成績）。需要的話先匿名化（用「學生 A / B / C」）
- **AI 輔助 ≠ AI 評分**：用 LLM 草擬回饋 / rubric 沒問題，但**最終評分一定要人工把關**——LLM 對複雜思考的評估還不可靠
- **告知學生**：如果課堂材料是 AI 輔助生成，建議向學生揭露（比照論文揭露 AI 工具使用）。教學誠信很重要
- **檢查事實**：LLM 會編造引用、學者名字、研究資料。專業領域內容**必須核對**才能上課
- **學生作品的著作權**：不要把學生作品用 LLM 大量分析後上傳到第三方 service、**可能涉及所在地個資法、學校政策、第三方服務條款**——在**美國**另需留意 FERPA（學生紀錄保護法）、在**歐盟**需留意 GDPR、在**台灣**則需注意《個資法》與校方公告。實際適用範圍請以該地法規與學校 IT 政策為準
如果你的學校 / 機構有 AI 使用政策，**那份比這份優先**。
## 給教師的層級建議
下表是建議的進階路徑——大多數教師應該停在 Tier 0-1：
| Tier | 工具 | 適合誰 | 學習成本 |
|---|---|---|---|
| **Tier 0** | Claude.ai 網頁版聊天 | 偶爾備課、單次任務、出題、寫信。複製上面的 prompt 範本填入主題即可 | 0（會用瀏覽器就行） |
| **Tier 1** | Claude Desktop / [NotebookLM](https://notebooklm.google.com/) | 批改 / 整理一整學期資料、做課程地圖、整批匯入課本 PDF 後問問題 | 半小時裝好 |
| **Tier 2+** | Claude Code / CLI / SDK | 有重複自動化需求（例：每週收 30 份作業 → 自動生成回饋初稿） | 1 週上手；不熟程式可找學校 IT / 學生 RA 幫忙設定 |
> **多數教師停在 Tier 0-1 就夠了**。升級到 Tier 2+ 就建議走 [Track A — CLI Power User](../tracks/cli/A1-cli-intro.md)。
## 也適用其他分支
很多老師同時是研究員 / 知識工作者，這幾個分支重疊：
- **也做研究**（找文獻、寫 paper、整理 references）→ [研究員分支](./for-researcher.md)
- **要寫報告 / 整理會議記錄 / 跨工具整合**（Notion、Excel、Email）→ [知識工作者分支](./for-knowledge-worker.md)
- **要把 AI 接到 Notion / Obsidian / 飛書** 等日常工具 → [`resources/mcp-skills-catalog.md`](../resources/mcp-skills-catalog.md)
## 社群備註
這個分支目前是精選內容最少的一塊。特別歡迎以下貢獻：
- 教案生成 skill
- 學科專屬的 prompt library（國文老師的 prompts、數學老師的 prompts、英文老師的 prompts ⋯）
- 教師專屬的 MCP server（成績冊整合、LMS 串接如 Canvas / Moodle / Google Classroom）
- **某學科 + 某年級的完整 case study**（例如「我用 AI 帶國中數學一個學期，這是我的 workflow」）
請見 [CONTRIBUTING.md](../CONTRIBUTING.md)。
branches/for-teacher.zh-Hans.md
+224
View File
@@ -0,0 +1,224 @@
# 教师延伸路线（For Teachers / Educators）
> [繁體中文](./for-teacher.md) | **简体中文** | [English](./for-teacher.en.md)
> 🚀 **大多数教师可直接从 Claude.ai（网页版）+ NotebookLM 开始，不需要任何 setup**。只有当你要自动化重复流程（Tier 2+，例如每周生成 50 份家长信）时，才需要看 [`resources/setup-guide.zh-Hans.md` A-C](../resources/setup-guide.zh-Hans.md)（30 分钟从零装好需要的东西）。
> [← 回主路线 README](../README.zh-Hans.md) · 走完 **Track A 的 A3** 或 **Track B 的 Stage 7** 后从这里接续。把 agentic AI 应用到教学流程上。
## 使用场景
教师使用 AI 的场景可以先看成三个分支：**备课与上课素材制作**、**教学现场与学习辅助**、以及**其他应用场景**。
这样的分类参考 AI in Education 文献中常见的行政、教学与学习应用脉络，也加入生成式 AI 在教材生成、反馈与互动支援上的近期讨论（Chen et al., 2020；Mittal et al., 2024）。阅读时建议先理解教师把关原则与使用边界，再依自己的教学需求挑一个分支深入。
![教师与 AI agent 使用场景总览](../resources/diagrams/teacher-ai-use-cases-overview.jpg)
### 教师使用 AI 辅助时要注意什么
AI 可以帮忙准备和辅助，但不应该直接取代教师判断。近期 AI in Education 与生成式 AI 教育研究也提醒，教师设计 AI agent 时要保留清楚的教学目标、安全边界与人工把关（Chen et al., 2020；Mittal et al., 2024）。
- **保留教师最后判断**：牵涉学生数据、成绩、教学决策等重大判断时，教师仍要负责最后确认。
- **避免直接给答案**：如果要让学生与 AI agent 互动，可以设计成苏格拉底式对话，在多轮互动中引导学生说出理由。
- **贴合教学目标**：用固定提示词、检查清单、或学校核准的工具设置，限制 AI 的角色与任务，避免学生互动脱离课程目标。
- **调整学生提问**：如果学生年龄较低，例如小学或初中，可以把学生问题先改写成更清楚的提问，再交给 agent 回答。
### 备课与上课素材制作
这类场景偏向“帮老师准备材料”，输出通常会被老师再改写、挑选、检查。
- **教案生成**：依课纲、单元目标与学生程度，整理课程大纲、时间分配、活动设计、讨论提示与补充学习指南。
- **Quiz / 评分量表（rubric）建立**：依文本、课文或学术文章，产生选择题、简答题、申论题、参考答案与评分规准。
- **幻灯片准备、课程地图、多媒体与可视化素材**：把课本章节或教师笔记转成幻灯片大纲、讲义架构、周次安排、先备知识、评估节点、图像、3D 对象、视频脚本、GIF 或课堂展示素材。
- **学生反馈整理分析**：汇整学生作答、作业或课堂反应，找出常见迷思、需要补救的概念与下一步练习。
- **多语系教材翻译与转化**：把教材改写或翻译成不同语言版本，也可以产生语音合成素材。
- **互动式游戏与活动、虚拟模拟场景的素材**：准备教学游戏、押韵儿歌、任务卡、角色卡、情境文本或模拟场景背景；若要设计实际互动流程或课堂活动，请参考下一节“教学现场与学习辅助”。
### 教学现场与学习辅助
![教学现场与学习辅助应用场景](../resources/diagrams/teacher-ai-classroom-use-cases.jpg)
这类场景偏向“帮学生理解、练习、互动”，AI 比较像教学助教或活动辅助工具。特别注意：不需要在单一教学活动中加入所有要素，而是挑选适合的环节加入 AI agent 设计。
- **沉浸式学习体验与真实情境演练**：用真实情境模拟、角色扮演或外语口说模拟，让学生在接近实作的情境中练习，降低认知负荷与退缩感。
- **激发好奇心与提问能力**：透过苏格拉底式追问与多轮互动，引导学生提出更清楚的问题、说明理由，进一步训练批判性思考与后设认知。
- **即时批改与深度反馈**：让学生从错误中学习，AI 可以指出错误、说明原因、建议修正方向，而不是只给分数或答案。
- **智慧家教与虚拟助教**：协助回答提问、解释术语、给提示，让学生在课堂内外都能获得适度支援。
- **适性教学与动态路径**：依学生程度提供对应难度内容，并透过学习表现推测近侧发展区，提供合适的鹰架与补救素材。
### 其他应用场景
这类场景不一定直接发生在课堂中，但会影响教师工作、学生支援与教育系统运作。
- **特殊教育支援**：透过语音转文字、文字转语音等方式，协助不同需求的学生参与课程。
- **亲师沟通与家庭教育**：整理学生进度报告，并提供家庭可延伸的辅助学习活动建议。
- **行政管理与学术诚信**：整理学习轨迹、产生报告，或协助进行抄袭与作弊风险检查。
- **职涯与技能发展辅导**：协助职涯探索、培训清单规划，并依弱点推荐练习题。
- **教师专业发展**：摘要教学方法、教育科技趋势与研究重点，协助教师持续更新。
- **高阶研究分析**：辅助文献分析、快速理解论文研究中提出的教学法或教育心理学。
- **隐私保护与合成数据**：在不直接使用真实个资的前提下，产生匿名合成数据。
### 参考文献
- Chen, L., Chen, P., & Lin, Z. (2020). [Artificial Intelligence in Education: A Review](https://doi.org/10.1109/ACCESS.2020.2988510). *IEEE Access*, 8, 75264-75278.
- Mittal, U., Sai, S., Chamola, V., & Sangwan, D. (2024). [A Comprehensive Review on Generative AI for Education](https://doi.org/10.1109/ACCESS.2024.3468368). *IEEE Access*, 12, 142733-142759.
## 精选 Projects
### 教学流程 Skills
（大多数还没有做成 skill marketplace。这个分支最有社群贡献空间——见 CONTRIBUTING.md。）
### 可用的基础组件
#### [obra/superpowers](https://github.com/obra/superpowers) ⭐⭐⭐⭐
通用的写作 / 头脑风暴 skill。可改用在备课上。
#### 进阶自动化：[Claude Code](https://github.com/anthropics/claude-code)（搭配自定义 CLAUDE.md）⭐⭐⭐⭐⭐
★ 120k+ — **教师的基础工具是 Claude.ai（网页版）+ NotebookLM + Google Classroom / LMS 集成**，先从这里开始。**只有当你已有会重复跑的批量流程**（如每周生成 50 份家长信、每学期跑学生反馈分析）才升级到 Claude Code，需要学一点 CLI。
### 教学课程素材（给教师备课用）
#### [huggingface/agents-course](https://github.com/huggingface/agents-course) ⭐⭐⭐⭐
| 栏位 | 内容 |
|---|---|
| Stars | ★ 28k+ |
| License | Apache-2.0 |
**教什么**：Hugging Face 官方的 agent 课程——notebook、练习、结业认证。是一份**现成的“AI agent 教学”素材**。
**适合谁**：要在学校 / 工作坊开“AI agent 入门”课程的老师，可以直接拿来当教材或改编。
**备注**：注意这是“教 AI agent 怎么建”的教材，不是“老师用 AI 教书”的工具。
---
#### [datawhalechina/llm-universe](https://github.com/datawhalechina/llm-universe) ⭐⭐⭐⭐（中文）
| 栏位 | 内容 |
|---|---|
| 语言 | 中文（zh-Hans） |
| Stars | ★ 13k+ |
| License | NOASSERTION |
**教什么**：Datawhale 出品的中文 LLM 应用开发课程——含 RAG、agent、章节练习。中文教师备课的现成模板。
**适合谁**：中文教师想找现成可改的 LLM 教材底稿、再针对自己学生程度调整。
**备注**：跟 hf agents-course 一样，是“教学生建 LLM 应用”的教材，不是“教师端的 AI 助教”。
---
### Prompt 素材库
#### [f/awesome-chatgpt-prompts](https://github.com/f/awesome-chatgpt-prompts) ⭐⭐⭐⭐
| 栏位 | 内容 |
|---|---|
| Stars | ★ 161k+ |
| License | NOASSERTION（CC0 / public domain 风格，但未提供 SPDX） |
**教什么**：社群维护的 prompt 大全——“act as X”型模板涵盖几百种角色（老师、面试官、stand-up comedian、辩论者⋯）。教师可以拿来当“prompt engineering 写法示例”教给学生，或直接借用其中合适的当作课堂示范。
**适合谁**：要教学生“prompt engineering”的老师，找现成例子比较不同写法的差异。
**备注**：质量不一致——当作素材库挑选用，不是“全部直接拿去教”。
---
### 阅读材料
#### [The Effortless Academic — Beginner Guides](https://effortlessacademic.com/claude-code-and-cowork-for-academics-beginner-guide-part-1/)
写给学术工作者导入 Claude Code 的多篇指南，教师也适用。
## 可以建的流程（按教学阶段）
下表 5 条是模板——配合你的学科自行调整：
| 阶段 | 流程 | 怎么做（≤ 3 步） | 推荐工具 | 注意 |
|---|---|---|---|---|
| **备课前** | 教案生成器 | (1) 课纲 + 主题提示 → 大纲<br>(2) 大纲 → 幻灯片<br>(3) 幻灯片 → 评估题目 | Claude.ai / NotebookLM | 教师最后审 |
| **备课中** | Rubric 建立 | (1) 给学生作业样本 + 学习目标<br>(2) 请 AI 草拟 4 级 rubric<br>(3) 教师调整级距 | Claude.ai | 避免“质量好”这种模糊词 |
| **改作业** | 个性化反馈 | (1) 学生作业 + rubric → AI 写反馈初稿<br>(2) 教师逐份审 + 改<br>(3) 寄回 | Claude.ai | **AI 辅助 ≠ AI 评分**，最终分数一定人工 |
| **课堂活动** | 情境模拟 | (1) 教学目标 + 角色设定 → 对话脚本<br>(2) 课堂演练<br>(3) 反思问题 | Claude.ai | 苏格拉底式追问、不直接给答案；学生输入**不含个资** |
| **课后补救** | 个性化补救教材 | (1) 整理学生常见错误<br>(2) 依学生程度 → 小练习 + 提示<br>(3) 延伸挑战题 | Claude.ai | 注意学生个资匿名化 |
> 💡 **新手起手式**：先做“备课前的教案生成器”一个学期，习惯后再加 rubric / 反馈流程。⚠️ 所有跟学生个资 / 评分相关的步骤都要回头看下面的 §隐私 + 伦理（重要）章节。
### 3 个可直接复制的 prompt 范本
**1. 教案大纲生成**（复制到 Claude.ai 即可用）：
```
你是一位 [学科] 老师。我要给 [年级] 学生上一堂 [时长] 分钟的课，主题是「[主题]」。
学生先备知识：[简述]。请产出：
1. 学习目标（3-4 条，用 Bloom's taxonomy 动词）
2. 课程大纲（含时间分配）
3. 1 个课堂活动 / 讨论题
4. 1 个课后评估题
不要产生超出我给的主题范围的内容。
```
**2. Rubric 草稿生成**：
```
我有一份 [作业类型] 作业，学生年级 [年级]，主题 [主题]。
学习目标：[列 2-3 条]。
请产出一份 4 级 rubric（卓越 / 熟练 / 发展中 / 待改进），
每级在「内容深度」「组织结构」「论证 / 计算」「表达清晰度」4 个面向各给一段描述。
描述要具体可观察，不用「质量好」这种模糊词。
```
**3. 学生反馈整理**：
```
以下是 [N] 份学生作业片段：
[贴上文本]
请：
1. 摘要这批作业共同的 3 个强项
2. 摘要 3 个共同弱点
3. 针对最常见弱点，建议 1-2 个下次上课该加强的环节
不要做个人化评语——我会自己针对个人写。
```
## 隐私 + 伦理（重要）
教师端用 LLM 跟一般 user 不同，**牵涉学生数据**——以下是 hard rule：
- **不要把学生个资丢进公开 LLM**（姓名、学号、联系方式、成绩）。需要的话先匿名化（用“学生 A / B / C”）
- **AI 辅助 ≠ AI 评分**：用 LLM 草拟反馈 / rubric 没问题，但**最终评分一定要人工把关**——LLM 对复杂思考的评估还不可靠
- **告知学生**：如果课堂材料是 AI 辅助生成，建议向学生揭露（比照论文揭露 AI 工具使用）。教学诚信很重要
- **检查事实**：LLM 会编造引用、学者名字、研究数据。专业领域内容**必须核对**才能上课
- **学生作品的著作权**：不要把学生作品用 LLM 大量分析后上传到第三方 service，**可能涉及所在地个资法、学校政策、第三方服务条款**——在**美国**另需留意 FERPA（学生记录保护法）、在**欧盟**需留意 GDPR、在**台湾**则需注意《个资法》与校方公告。实际适用范围请以该地法规与学校 IT 政策为准
如果你的学校 / 机构有 AI 使用政策，**那份比这份优先**。
## 给教师的层级建议
下表是建议的进阶路径——大多数教师应该停在 Tier 0-1：
| Tier | 工具 | 适合谁 | 学习成本 |
|---|---|---|---|
| **Tier 0** | Claude.ai 网页版聊天 | 偶尔备课、单次任务、出题、写信。复制上面的 prompt 范本填入主题即可 | 0（会用浏览器就行） |
| **Tier 1** | Claude Desktop / [NotebookLM](https://notebooklm.google.com/) | 批改 / 整理一整学期数据、做课程地图、整批导入课本 PDF 后问问题 | 半小时装好 |
| **Tier 2+** | Claude Code / CLI / SDK | 有重复自动化需求（例：每周收 30 份作业 → 自动生成反馈初稿） | 1 周上手；不熟程序可找学校 IT / 学生 RA 帮忙设置 |
> **多数教师停在 Tier 0-1 就够了**。升级到 Tier 2+ 就建议走 [Track A — CLI Power User](../tracks/cli/A1-cli-intro.zh-Hans.md)。
## 也适用其他分支
很多老师同时是研究员 / 知识工作者，这几个分支重叠：
- **也做研究**（找文献、写 paper、整理 references）→ [研究员分支](./for-researcher.zh-Hans.md)
- **要写报告 / 整理会议记录 / 跨工具集成**（Notion、Excel、Email）→ [知识工作者分支](./for-knowledge-worker.zh-Hans.md)
- **要把 AI 接到 Notion / Obsidian / 飞书** 等日常工具 → [`resources/mcp-skills-catalog.zh-Hans.md`](../resources/mcp-skills-catalog.zh-Hans.md)
## 社群备注
这个分支目前是精选内容最少的一块。特别欢迎以下贡献：
- 教案生成 skill
- 学科专属的 prompt library（语文老师的 prompts、数学老师的 prompts、英文老师的 prompts ⋯）
- 教师专属的 MCP server（成绩册集成、LMS 串接如 Canvas / Moodle / Google Classroom）
- **某学科 + 某年级的完整 case study**（例如“我用 AI 带初中数学一个学期，这是我的 workflow”）
请见 [CONTRIBUTING.md](../CONTRIBUTING.md)。
docs/HOW_TO_USE.md
+155
View File
@@ -0,0 +1,155 @@
# 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 等決定後開出來。
docs/TESTING_PLAN.md
+114
View File
@@ -0,0 +1,114 @@
# 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 `<details>` (練習 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. **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.
4. **Trilingual mirror of 🎓 callout incomplete** — v1 only added the 學習模式 callout to zh-TW READMEs. en + zh-Hans exercise READMEs still need the same callout. Low priority since most learners use zh-TW.
5. **Pilot exercise drift** (pre-session, still open) — `examples/stage-3/03-react-from-scratch/README.en.md` + `.zh-Hans.md` are pre-dual-path; the zh-TW canonical is current. Stage 3 polish pass should fix.
## 🔵 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) — 7-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.
docs/stylesheets/extra.css
+98
View File
@@ -0,0 +1,98 @@
/* awesome-agentic-ai-zh — site branding + landing-page styles.
Loaded via mkdocs.yml `extra_css`. Material defaults stay intact;
this refines brand color, the home hero, grid cards, and tables. */
/* ---- Brand color (indigo) ---- */
:root {
--md-primary-fg-color: #4f46e5;
--md-primary-fg-color--light: #6366f1;
--md-primary-fg-color--dark: #4338ca;
--md-accent-fg-color: #6366f1;
}
/* ---- Landing hero (index.md) ---- */
.aaz-hero {
text-align: center;
padding: 2.5rem 1rem 1.5rem;
}
.aaz-hero .aaz-repo {
font-family: var(--md-code-font-family);
font-size: .72rem;
color: var(--md-default-fg-color--light);
}
.aaz-hero h1 { font-size: 2.1rem; font-weight: 700; margin: .35rem 0 .25rem; }
.aaz-hero .aaz-tagline {
font-size: 1.05rem;
color: var(--md-default-fg-color--light);
max-width: 34rem;
margin: .4rem auto 1.4rem;
line-height: 1.6;
}
.aaz-cta {
display: inline-flex;
gap: .6rem;
flex-wrap: wrap;
justify-content: center;
margin-bottom: 1rem;
}
.aaz-cta .md-button { border-radius: 24px; }
.aaz-langs { display: flex; gap: .4rem; justify-content: center; flex-wrap: wrap; }
.aaz-langs a {
font-size: .72rem;
color: var(--md-default-fg-color--light);
border: 1px solid var(--md-default-fg-color--lighter);
border-radius: 20px;
padding: .15rem .7rem;
text-decoration: none;
transition: color .15s ease, border-color .15s ease, background .15s ease;
}
.aaz-langs a:hover {
color: var(--md-accent-fg-color);
border-color: var(--md-accent-fg-color);
background: var(--md-default-fg-color--lightest);
}
/* ---- Stat strip ---- */
.aaz-stats {
display: grid;
grid-template-columns: repeat(4, 1fr);
gap: .75rem;
max-width: 40rem;
margin: 1.5rem auto;
}
.aaz-stat {
text-align: center;
padding: 1rem .4rem;
border-radius: 12px;
background: var(--md-default-fg-color--lightest);
}
.aaz-stat .aaz-num { font-size: 1.6rem; font-weight: 700; display: block; line-height: 1.2; }
.aaz-stat .aaz-lbl { font-size: .78rem; color: var(--md-default-fg-color--light); }
@media (max-width: 30rem) {
.aaz-stats { grid-template-columns: repeat(2, 1fr); }
}
/* ---- Grid-card polish (Material `.grid.cards`) ---- */
.md-typeset .grid.cards > ul > li {
border-radius: 12px;
transition: border-color .2s ease, box-shadow .2s ease, transform .2s ease;
}
.md-typeset .grid.cards > ul > li:hover {
border-color: var(--md-accent-fg-color);
box-shadow: 0 4px 18px rgba(0, 0, 0, .08);
transform: translateY(-2px);
}
/* ---- Tables: tighter, rounded, hover ---- */
.md-typeset table:not([class]) {
border-radius: 10px;
overflow: hidden;
font-size: .80rem;
}
.md-typeset table:not([class]) th {
background: var(--md-default-fg-color--lightest);
font-weight: 600;
}
.md-typeset table:not([class]) tr:hover td {
background: var(--md-default-fg-color--lightest);
}
examples/README.en.md
+219
View File
@@ -0,0 +1,219 @@
<div align="right">
<a href="./README.md">繁體中文</a> | <a href="./README.zh-Hans.md">简体中文</a> | <strong>English</strong>
</div>
# `examples/` — Runnable hands-on exercises
> [← Back to main path README](../README.en.md)
Every stage in the learning roadmap has a "Hands-on Exercises" section that tells you *what* to do. This folder adds the **actual runnable starter code** — copy → install deps → `python starter.py` → see expected output.
## Directory layout
```
examples/
├── stage-3/ # Tool Use & Agent intro
│ ├── 03-react-from-scratch/ # Exercise 3: ReAct from scratch
│ │ ├── starter.py # Main program (~70 LOC runnable)
│ │ ├── test.py # Self-check (pure assert, no pytest)
│ │ ├── README.md # 200-400-word walkthrough (+.zh-Hans.md +.en.md)
│ │ └── requirements.txt # Pinned deps
│ └── ...
├── stage-1/
└── ...
```
Short exercises (≤30 LOC) stay inline as `<details>` blocks in the stage doc — no folder. Longer ones (>30 LOC) get their own folder so stage docs don't get bloated by code blocks.
## How to run any example
```bash
cd examples/stage-3/03-react-from-scratch
pip install -r requirements.txt
export ANTHROPIC_API_KEY=sk-ant-... # Each example header lists the key it needs
python starter.py # Hits the real API to see output (~$0.001 in credits)
python test.py # Runs validation (mock-based, free)
```
## Design rules
| Dimension | Rule |
|---|---|
| Program length | starter ≤80 LOC, split if longer |
| Dependencies | stdlib + ≤2 pip packages, pinned versions |
| Tests | Plain `assert`, no pytest; reader runs `python test.py` to see ✅ |
| Comments | Chinese (zh-TW primary), English variable / function names |
| Self-check | Every starter.py ends with a `# === Self-check ===` block |
| Environment vars | Header comment must list required keys |
| Free-tier friendly | Use the cheapest model (claude-haiku / Ollama); note how to switch to Sonnet |
| **Windows encoding** | **Every .py must reconfigure stdout to UTF-8** (see below) |
### Windows cp950 encoding fix (mandatory in every starter.py / test.py)
Windows consoles default to cp950 (Big5) and can't print emoji or non-Big5 Chinese. Add this right after imports in every `.py`:
```python
import sys
if hasattr(sys.stdout, "reconfigure"):
sys.stdout.reconfigure(encoding="utf-8", errors="replace")
```
Without it, Windows readers running in PowerShell / cmd hit `UnicodeEncodeError: 'cp950' codec can't encode character '✅'`.
## Three paths — **default is Ollama (cost-driven)**
> 💰 **Why default to Ollama?** Running 1000 practice iterations on Sonnet costs ~$4; on haiku ~$0.25; on local Ollama $0. **API cost should not block learning.** Reserve cloud LLMs for "want to see high-quality answers / production deployment".
Every exercise ships with all three paths:
### Path A (**default, recommended**) — local Ollama
- Default `starter.py` / first inline `<details>` block uses a local model
- Requires [Ollama](https://ollama.com); pull a model based on the stage:
- **Stage 1 + 2** (plain chat / prompt eng): `ollama pull gemma4:e4b` (~7.5 GB; multimodal (text + image + audio); CPU-friendly)
- **Stage 3+** (tool use / agent): `ollama pull qwen2.5:3b` (1.9 GB; reliable tool-use support)
- $0, offline, fine for privacy-sensitive data
- SDK uses the `openai` package (OpenAI-compatible API) with `base_url="http://localhost:11434/v1"`
- Best for: all readers (this is the default recommendation)
### Path B (optional) — Anthropic API (when you want cloud quality)
- Companion `starter_anthropic.py` (folder) or the second inline `<details>` block
- Requires `ANTHROPIC_API_KEY`; ~$0.001 per run (haiku) / ~$0.004 (sonnet)
- Higher answer quality and lower latency than local 3-4B Ollama models
- Best for: production-quality demands, long-context work, the Stage 7 production tier
### Path C (verify logic, no API call)
- Every `test.py` uses `unittest.mock`; `python test.py` validates code logic without spending
- Complements A / B — mock first, then real call
### Trade-offs
| Dimension | A Ollama (default) | B Anthropic | C Mock |
|---|---|---|---|
| Cost per call | $0 | ~$0.001-0.004 | $0 |
| Requires | Ollama install | API key | nothing |
| Answer quality | medium (3-4B model) | high | canned, unrepresentative |
| Speed | 5-30 s/call (no GPU) | ~1-3 s/call | <0.1 s |
| Offline | ✅ | ❌ | ✅ |
| Privacy-sensitive data | ✅ | ❌ | ✅ |
| Stage 3+ tool use | ✅ (qwen2.5 / llama3.2) | ✅ | ✅ |
| Best for | **default, no budget pressure** | production upgrade | logic verification |
→ **Recommended flow**: C first (validate logic, no cost), then A (see real model behaviour locally), then B at the Stage 7 production stage if cloud quality is needed.
## Recommended LLM list
> Local + cloud, user-perspective.
> 💡 You don't need to install every model — this table shows "which to use for practice" and "which to upgrade to for production". **Claude is the canonical / production reference; Ollama is the practice default.**
### Local LLMs (practice default, via Ollama)
| Model | Download | Recommended RAM | Stage | Tool-use | Speed (CPU/GPU) | Primary use |
|---|---|---|---|---|---|---|
| **`gemma4:e4b`** ⭐ | 7.5 GB | 8 GB | 1+2 | basic | slow / med | Stage 1-2 plain chat / prompt eng (default) |
| **`qwen2.5:3b`** ⭐ | 1.9 GB | 4 GB | 3+ | **reliable** | med / fast | Stage 3+ tool use / agent (default) |
| `llama3.2:3b` | 2.0 GB | 4 GB | 3+ | reliable | med / fast | qwen2.5:3b alternative |
| `mistral-nemo:12b` | 7.1 GB | 16 GB | 3+ | strong | slow / med | When you want closer-to-cloud quality |
| `qwen2.5:14b` | 9.0 GB | 16 GB | advanced | strong | slow / med | Larger-model comparison (GPU preferred) |
| `gemma4:e2b` | 4.0 GB | 4 GB | 1+2 | basic | med / fast | 4 GB-RAM-machine alternative |
Install: `ollama pull <model>` + `ollama serve`. Hardware tuning details: [resources/cli-agents-guide.en.md](../resources/cli-agents-guide.en.md).
### Cloud LLMs (canonical / production stack, via Anthropic)
| Model | $/1M input | $/1M output | Context | Primary use |
|---|---|---|---|---|
| `claude-fable-5` | $10 | $50 | 1M | Mythos-class (above Opus); suspended 2026-06-12, **restored 2026-07-01** (export controls lifted); the highest Claude tier |
| **`claude-haiku-4-5`** ⭐ | $1 | $5 | 200k | Cheapest; fine for Stage 1-7 cloud-quality comparisons |
| **`claude-sonnet-5`** ⭐ | $3 | $15 | 1M | **Production default**; Stage 5+ agent development |
| `claude-opus-4-8` | $5 | $25 | 1M | Opus-class flagship; complex reasoning / long-context refactors |
Subscription alternative: Claude Pro $20/month (includes Sonnet usage); Claude Max $100/month (includes Opus). Details: [resources/cli-agents-guide.en.md](../resources/cli-agents-guide.en.md).
### Cloud LLM Chinese / open-source alternatives (region limits / budget / Chinese-language scenarios)
> Can't or don't want to use Anthropic? These APIs are **all OpenAI-compatible** — change `base_url` and model name to run the same exercises.
| Provider | Main model | $/1M input | $/1M output | OpenAI-compat? | Key selling point |
|---|---|---|---|---|---|
| **DeepSeek** ⭐ | `deepseek-chat` (V3) | $0.27 | $1.10 | ✅ | Cheapest cloud (4× cheaper than haiku $1/$5); strong CN & EN; free web at `chat.deepseek.com` |
| DeepSeek R1 | `deepseek-reasoner` | $0.55 | $2.19 | ✅ | Reasoning model (o1-class), still 1/30 the price of OpenAI o1 |
| **Moonshot Kimi** | `kimi-k2-turbo-preview` | $5-10 | $15-30 | ✅ | **1M-token context** (key selling point); good for large files / long conversations. Free web at `kimi.com` |
| **Qwen (Alibaba)** | `qwen-max` / `qwen-turbo` | $0.50-1.50 | $1.50-6 | ✅ (DashScope) | Native Chinese; **same models also run locally via Ollama** (cloud + local both work) |
| **GLM (ZhipuAI)** | `glm-4.5` / `glm-4-plus` | $0.30-2 | $1.50-9 | ✅ | China-native, has free tier. Free web `chatglm.cn` |
| **NVIDIA NIM** | Llama / Mistral / DeepSeek / Qwen etc. hosted | free tier 1000 credits | (same) | ✅ | **Hosts 10+ open models**; new accounts get credits; no local GPU needed. `build.nvidia.com` |
**API endpoints (OpenAI SDK usage)**:
```python
# DeepSeek
client = OpenAI(api_key=os.environ["DEEPSEEK_API_KEY"], base_url="https://api.deepseek.com/v1")
r = client.chat.completions.create(model="deepseek-chat", messages=[...])
# Moonshot Kimi (China endpoint; international uses .ai)
client = OpenAI(api_key=os.environ["MOONSHOT_API_KEY"], base_url="https://api.moonshot.cn/v1")
r = client.chat.completions.create(model="kimi-k2-turbo-preview", messages=[...])
# Qwen (Alibaba DashScope)
client = OpenAI(api_key=os.environ["DASHSCOPE_API_KEY"],
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1")
r = client.chat.completions.create(model="qwen-turbo", messages=[...])
# GLM (ZhipuAI)
client = OpenAI(api_key=os.environ["ZHIPUAI_API_KEY"], base_url="https://open.bigmodel.cn/api/paas/v4")
r = client.chat.completions.create(model="glm-4.5-flash", messages=[...])
# NVIDIA NIM (hosted open-source)
client = OpenAI(api_key=os.environ["NVIDIA_API_KEY"], base_url="https://integrate.api.nvidia.com/v1")
r = client.chat.completions.create(model="meta/llama-3.3-70b-instruct", messages=[...])
```
**How to pick**:
| Scenario | Pick | Why |
|---|---|---|
| Mainland China, no cloud access | Ollama local / DeepSeek API | Local is free; DeepSeek has an in-China endpoint |
| Tight budget (< $1/month) | DeepSeek API | 4× cheaper than haiku; quality close |
| Large files / long-doc RAG | Moonshot Kimi | 1M-token context |
| Chinese-native task (classical Chinese, CN search) | Qwen / GLM | Higher Chinese training corpus ratio |
| Want to try 10+ open models without GPU | NVIDIA NIM | One key, play with Llama / Mixtral / Qwen / DeepSeek |
| Production agent (tool use) | Anthropic Claude (canonical) | This repo's Path B default; tool calling most reliable |
### Budget estimate (completing all 54 exercises across Stage 1-7)
| Learning path | Total time | Total cost | Best for |
|---|---|---|---|
| **All local Ollama** | ~30 hr (CPU) / ~10 hr (GPU) | **$0** | Budget-conscious, privacy needs, China-mainland no-cloud-access |
| **Mixed: local practice + haiku final review** ⭐ | ~30 hr | **$2-5** | **Recommended default** — practice locally, run final 1-2 iterations on haiku to see cloud quality |
| **All haiku** | ~10 hr | $5-15 | Want speed, budget allows, want full cloud experience |
| **All sonnet** | ~8 hr | $20-50 | Deep practice with higher-quality answers, want high-quality answers |
| **Mixed: sonnet + opus on hard problems** | ~8 hr | $30-80 | Already a production agent developer |
> 🎯 **Beginner default**: run everything locally first; cap budget at $5. **Only consider upgrading to sonnet at the Stage 7 production tier.**
## Index by stage
| Stage | Exercises | Example location |
|---|---|---|
| 1 LLM basics | 6 | inline 4 + folder 2 (`examples/stage-1/`) |
| 2 Prompt engineering | 4 | all inline |
| **3 Tool use** | **6** | inline 1 + folder 5 (`examples/stage-3/`) |
| 4 Frameworks | 5 | all folder (`examples/stage-4/`) |
| 5 Claude Code ecosystem | 11 | inline 6 + folder 5 (`examples/stage-5/`) |
| 6 Memory/RAG | 5 | all folder (`examples/stage-6/`) |
| 7 Multi-agent | 5 | inline 1 + folder 4 (`examples/stage-7/`) |
| Track A1-A3 | 12 | all inline + 2 small folders (CLI-9 / CLI-10) |
→ T1 scope: **Stage 3 全 6 exercises only** (remaining stages roll out per plan tiers).
## Contributing / reporting issues
If something doesn't run, output doesn't match expectations, or you want to add a new example:
- File an issue tagged `examples`
- Or open a PR following the "Design rules" table above
## Why this split (instead of stuffing everything into stage docs)
1. **Stage docs stay readable** — roadmap readers don't always want code, they want concepts; long code blocks break that
2. **Examples evolve independently** — SDK bumps, model rename, example needs its own commit without polluting the roadmap's git log
3. **Readers can clone one example** — `svn export` or `git clone --filter=tree:0` grabs a single folder
4. **Future CI** — example failures shouldn't block mdbook deploy; this split lets CI run examples conditionally
examples/README.md
+237
View File
@@ -0,0 +1,237 @@
<div align="right">
<strong>繁體中文</strong> | <a href="./README.zh-Hans.md">简体中文</a> | <a href="./README.en.md">English</a>
</div>
# `examples/` — 動手練習可跑範例
> [← 回主路線 README](../README.md)
學習地圖每個 stage 都有「動手練習」section、講「該做什麼」。這個資料夾補上**真的可以跑的範例 code**——複製 → 裝依賴 → `python starter.py` 看到預期輸出。
## 目錄結構
```
examples/
├── stage-3/ # Tool Use & Agent 入門
│ ├── 03-react-from-scratch/ # 練習 3：從零實作 ReAct
│ │ ├── starter.py # 主程式（~70 行可跑）
│ │ ├── test.py # 自我驗證（pure assert、無 pytest）
│ │ ├── README.md # 200-400 字走查（+.zh-Hans.md +.en.md）
│ │ └── requirements.txt # 依賴釘版本
│ └── ...
├── stage-1/
└── ...
```
短的練習（≤30 LOC）直接以 `<details>` 收摺塞在 stage 檔內、不開資料夾。長的（>30 LOC）才開資料夾——避免 stage 檔被 code block 撐爆。
## 怎麼跑任一個範例
```bash
cd examples/stage-3/03-react-from-scratch
pip install -r requirements.txt
export ANTHROPIC_API_KEY=sk-ant-... # 各範例頂端會說它要哪個 key
python starter.py # 跑真的 API 看輸出（會花一點點錢、約 $0.001）
python test.py # 跑驗證（用 mock、不花錢）
```
## 設計原則
| 維度 | 規則 |
|---|---|
| 程式長度 | starter ≤80 LOC、超過拆檔 |
| 依賴 | stdlib + 最多 2 個 pip 套件、釘版本 |
| 測試 | 純 `assert`、不用 pytest、reader 跑 `python test.py` 看 ✅ |
| 註解 | 中文（zh-TW 為主）、變數 / 函式名英文 |
| 自我驗證 | 每個 starter.py 結尾必有 `# === 自我驗證 ===` 區塊 |
| 環境變數 | 頂端註解寫清楚需要哪些 key |
| Free-tier 友善 | 用最便宜 model（claude-haiku / Ollama）、註解寫怎麼換 Sonnet |
| **Windows 編碼** | **每個 .py 頂端必須有 UTF-8 reconfigure**（見下） |
### Windows cp950 編碼 fix（每個 starter.py / test.py 必加）
Windows 預設 console 是 cp950（Big5）、印不出 emoji 跟非 Big5 中文。每個 `.py` 檔頂端 import 區後立刻加：
```python
import sys
if hasattr(sys.stdout, "reconfigure"):
sys.stdout.reconfigure(encoding="utf-8", errors="replace")
```
否則 Windows reader 在 PowerShell / cmd 跑會炸 `UnicodeEncodeError: 'cp950' codec can't encode character '✅'`。
## 三條路徑 — **預設用 Ollama（成本考量）**
> 💰 **為什麼默認 Ollama？** 練習場景跑 1000 次跑滿 Sonnet ~$4、跑 haiku ~$0.25、跑本機 Ollama $0。**學習階段不該被 API 成本卡住**。Cloud LLM 留給「想看高品質答案 / production deployment」時用。
每個練習都同時提供 3 條路徑：
### Path A（**默認、推薦**）— Ollama 本機
- 預設 `starter.py` / 第一個 inline `<details>` 用本機 LLM
- 需 [Ollama](https://ollama.com)、按 stage pull 對應 model：
- **Stage 1 + 2**（純 chat / prompt eng）：`ollama pull gemma4:e4b`（~7.5 GB、多模態、CPU 跑得動）
- **Stage 3+**（tool use / agent）：`ollama pull qwen2.5:3b`（1.9 GB、tool-use 支援穩定）
- 全程 $0、offline、隱私敏感資料 OK
- SDK 用 `openai` package（OpenAI-compatible API）、`base_url="http://localhost:11434/v1"`
- 適合：所有讀者（默認推這條）
### Path B（選擇性）— Anthropic API（想看 cloud 高品質時）
- 對照 `starter_anthropic.py`（folder）或第二個 inline `<details>` 區塊
- 需 `ANTHROPIC_API_KEY`、跑一輪約 $0.001（haiku）/ $0.004（sonnet）
- 答案品質 / latency 都比本機 Ollama 強
- 適合：production 要求高品質、需要 long-context、Stage 7 production tier
### Path C（驗邏輯、不打 API）
- 所有 `test.py` 都用 `unittest.mock`、`python test.py` 看程式邏輯有沒有寫對
- 跟 Path A / B 互補：先 mock 驗邏輯、再 real call 確認
### 三條路的 Trade-off
| 維度 | A Ollama（默認）| B Anthropic | C Mock |
|---|---|---|---|
| Cost / call | $0 | ~$0.001-0.004 | $0 |
| 需要 | Ollama install | API key | 無 |
| 答案品質 | 中（3-4B model） | 高 | 預設、看不出真實品質 |
| 速度 | 5-30s/call（無 GPU） | ~1-3s/call | <0.1s |
| Offline | ✅ | ❌ | ✅ |
| 隱私敏感資料 | ✅ | ❌ | ✅ |
| Stage 3+ tool use | ✅（qwen2.5 / llama3.2） | ✅ | ✅ |
| 適合 | **默認、無預算壓力** | production 升級 | 程式邏輯驗證 |
→ **建議流程**：先 C 驗邏輯（不花錢）、再 A 本機跑看實際 model 行為、production 階段（Stage 7）再升 B 看 cloud 品質。
## 推薦 LLM 清單
> 本機 + cloud、user 視角。
> 💡 不是要你全裝、是讓你看到「練習用哪個」「production 升級到哪個」。**Claude 是 canonical / production 主軸；Ollama 是練習默認**。
### 本機 LLM（練習默認、用 Ollama）
| Model | 下載大小 | 建議 RAM | 對應 Stage | Tool-use | 速度（CPU/GPU） | 主用途 |
|---|---|---|---|---|---|---|
| **`gemma4:e4b`** ⭐ | 7.5 GB | 8 GB | 1+2 | 基本 | 慢 / 中 | Stage 1-2 純 chat / prompt eng（默認）|
| **`qwen2.5:3b`** ⭐ | 1.9 GB | 4 GB | 3+ | **穩定** | 中 / 快 | Stage 3+ tool use / agent（默認）|
| `llama3.2:3b` | 2.0 GB | 4 GB | 3+ | 穩定 | 中 / 快 | qwen2.5:3b 的替代 |
| `mistral-nemo:12b` | 7.1 GB | 16 GB | 3+ | 強 | 慢 / 中 | 想看更接近 cloud 品質 |
| `qwen2.5:14b` | 9.0 GB | 16 GB | 進階 | 強 | 慢 / 中 | 大 model 對照（需 GPU 偏好）|
| `gemma4:e2b` | 4.0 GB | 4 GB | 1+2 | 基本 | 中 / 快 | 4GB RAM 機器替代 |
安裝：`ollama pull <model>` + `ollama serve`。詳細硬體配置看 [resources/cli-agents-guide.md](../resources/cli-agents-guide.md)。
### Cloud LLM（canonical / production 主軸、用 Anthropic）
| Model | 每 1M input | 每 1M output | Context | 主用途 |
|---|---|---|---|---|
| `claude-fable-5` | $10 | $50 | 1M | Mythos 級（位階在 Opus 之上）；2026-06-12 暫停、**2026-07-01 恢復**（出口管制解除）——目前最高階的 Claude 層級 |
| **`claude-haiku-4-5`** ⭐ | $1 | $5 | 200k | 最便宜、Stage 1-7 練習 cloud 對照都 OK |
| **`claude-sonnet-5`** ⭐ | $3 | $15 | 1M | **production 默認**、Stage 5+ agent 開發 |
| `claude-opus-4-8` | $5 | $25 | 1M | Opus 級旗艦、複雜推理 / 長 context refactor |
訂閱替代：Claude Pro $20/月含 Sonnet 用量、Claude Max $100/月含 Opus。詳細看 [resources/cli-agents-guide.md](../resources/cli-agents-guide.md)。
### Cloud LLM 中國 / 開源 alternatives（地區限制 / 預算敏感 / 中文場景）
> 不能 / 不想用 Anthropic？這些 API **都 OpenAI-compatible**、改 `base_url` 跟 model name 就能跑本 repo 同一份練習。
| Provider | 主 model | 每 1M input | 每 1M output | OpenAI-compat? | 主賣點 |
|---|---|---|---|---|---|
| **DeepSeek** ⭐ | `deepseek-chat` (V3) | $0.27 | $1.10 | ✅ | 最便宜 cloud（比 haiku $1/$5 還便宜 4 倍）、中英文俱佳、含免費 web `chat.deepseek.com` |
| DeepSeek R1 | `deepseek-reasoner` | $0.55 | $2.19 | ✅ | 推理模型（o1 級）、價格仍只是 OpenAI o1 的 1/30 |
| **Moonshot Kimi** | `kimi-k2-turbo-preview` | $5-10 | $15-30 | ✅ | **1M token context**（賣點）、適合大檔案 / 長對話。web 版 `kimi.com` 免費 |
| **通義千問 Qwen** | `qwen-max` / `qwen-turbo` | $0.50-1.50 | $1.50-6 | ✅（DashScope）| 中文 native、**同 model 也能 Ollama 本機跑**（cloud + local 兩條路徑都通） |
| **智譜 GLM** | `glm-4.5` / `glm-4-plus` | $0.30-2 | $1.50-9 | ✅ | 中國 native、有 free tier。web `chatglm.cn` 免費 |
| **NVIDIA NIM** | Llama / Mistral / DeepSeek / Qwen 等 hosted | free tier 1000 credits | (同) | ✅ | **托管 10+ open model**、新帳號送 credits、不必本機 GPU。`build.nvidia.com` |
**API endpoints（OpenAI SDK 接法）**：
```python
# DeepSeek
client = OpenAI(api_key=os.environ["DEEPSEEK_API_KEY"], base_url="https://api.deepseek.com/v1")
r = client.chat.completions.create(model="deepseek-chat", messages=[...])
# Moonshot Kimi（中國 endpoint；海外用 .ai 結尾）
client = OpenAI(api_key=os.environ["MOONSHOT_API_KEY"], base_url="https://api.moonshot.cn/v1")
r = client.chat.completions.create(model="kimi-k2-turbo-preview", messages=[...])
# 通義千問 Qwen（Alibaba DashScope）
client = OpenAI(api_key=os.environ["DASHSCOPE_API_KEY"],
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1")
r = client.chat.completions.create(model="qwen-turbo", messages=[...])
# 智譜 GLM
client = OpenAI(api_key=os.environ["ZHIPUAI_API_KEY"], base_url="https://open.bigmodel.cn/api/paas/v4")
r = client.chat.completions.create(model="glm-4.5-flash", messages=[...])
# NVIDIA NIM（hosted open-source）
client = OpenAI(api_key=os.environ["NVIDIA_API_KEY"], base_url="https://integrate.api.nvidia.com/v1")
r = client.chat.completions.create(model="meta/llama-3.3-70b-instruct", messages=[...])
```
**怎麼挑**：
| 情境 | 選 | 理由 |
|---|---|---|
| 中國大陸、無 cloud 訪問 | Ollama 本機 / DeepSeek API | 本機免費；DeepSeek 在中國有 endpoint |
| 預算極敏感（< $1/月） | DeepSeek API | 比 haiku 便宜 4 倍、品質接近 |
| 大檔案 / 長文檔 RAG | Moonshot Kimi | 1M token context 賣點 |
| 中文 native task（古文、中文搜索）| Qwen / GLM | 訓練語料中文佔比高 |
| 想試 10+ open model 沒 GPU | NVIDIA NIM | 一個 key 玩 Llama / Mixtral / Qwen / DeepSeek |
| Production agent（agent / tool use）| Anthropic Claude（canonical）| 本 repo Path B 默認、tool calling 最穩 |
### 預算估算（跑完 Stage 1-7 全 54 練習）
| 學習路徑 | 總時間 | 總成本 | 適合誰 |
|---|---|---|---|
| **全本機 Ollama** | ~30 hr (CPU) / ~10 hr (GPU) | **$0** | 預算敏感、隱私需求、中國大陸無 cloud 訪問 |
| **混合：本機練 + haiku 終驗** ⭐ | ~30 hr | **$2-5** | **推薦默認**：練習 local 跑、最後 1-2 次用 haiku 看 cloud 品質 |
| **全 haiku** | ~10 hr | $5-15 | 想快、預算允許、想看完整 cloud 體驗 |
| **全 sonnet** | ~8 hr | $20-50 | 深度練習、追求高品質答案 |
| **混合：sonnet 為主 + opus 難題** | ~8 hr | $30-80 | 已是 production agent 開發者 |
> 🎯 **新手默認**：先全本機跑、預算上限 $5。**Stage 7 production tier 才考慮 sonnet 升級**。
### 怎麼從 Ollama 換到 Anthropic？
每個練習都有 `<details>` Path B 區塊或 `starter_anthropic.py`、改 3 行：
```python
# 從這個（Path A 默認）：
from openai import OpenAI
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
r = client.chat.completions.create(model="gemma4:e4b", ...)
# 換成這個（Path B、若有 ANTHROPIC_API_KEY）：
import anthropic
client = anthropic.Anthropic()
r = client.messages.create(model="claude-haiku-4-5", ...)
```
主要差異：messages create 方法名、response shape（`choices[0].message.content` vs `content[0].text`）、tool spec wrap（OpenAI 多一層 `{"type": "function", "function": {...}}`）。詳細對照表見 [`resources/cli-agents-guide.md`](../resources/cli-agents-guide.md)。
## 對應 stage 索引
| Stage | 練習 | 範例位置 |
|---|---|---|
| 1 LLM 基礎 | 6 個 | inline 4 + folder 2（`examples/stage-1/`） |
| 2 Prompt eng | 4 個 | 全 inline |
| **3 Tool use** | **6 個** | inline 1 + folder 5（`examples/stage-3/`） |
| 4 Frameworks | 5 個 | 全 folder（`examples/stage-4/`） |
| 5 Claude Code 生態 | 11 個 | inline 6 + folder 5（`examples/stage-5/`） |
| 6 Memory/RAG | 5 個 | 全 folder（`examples/stage-6/`） |
| 7 Multi-agent | 5 個 | inline 1 + folder 4（`examples/stage-7/`） |
| Track A1-A3 | 12 個 | 全 inline、外加 2 個小 folder（CLI-9 / CLI-10） |
→ T1 完成範圍：**只有 Stage 3 全部 6 個**（剩餘 stage 按 plan 分批推進）。
## 貢獻 / 報錯
跑不過、結果跟預期輸出對不上、或想補一個新練習：
- 開 issue 標 `examples` label
- 或直接 PR、follow 本資料夾「設計原則」表格的規則
## 為什麼這樣分（不直接全塞 stage 檔）
1. **Stage 檔保持 readable**：學習地圖讀者不一定要看 code、只想理解 concept；長 code block 干擾閱讀流
2. **範例可獨立演進**：API SDK 升版、model name 改、範例需要單獨 commit、不污染學習地圖 git log
3. **Reader 可以 clone 單一 example**：`svn export` 或 `git clone --filter=tree:0` 只抓一個資料夾
4. **未來 CI**：example 失敗不應 block mdbook deploy；分開可讓 CI 有條件性檢查
examples/README.zh-Hans.md
+219
View File
@@ -0,0 +1,219 @@
<div align="right">
<a href="./README.md">繁體中文</a> | <strong>简体中文</strong> | <a href="./README.en.md">English</a>
</div>
# `examples/` — 动手练习可跑范例
> [← 回主路线 README](../README.zh-Hans.md)
学习地图每个 stage 都有“动手练习”section、讲“该做什么”。这个资料夹补上**真的可以跑的范例 code**——复制 → 装依赖 → `python starter.py` 看到预期输出。
## 目录结构
```
examples/
├── stage-3/ # Tool Use & Agent 入门
│ ├── 03-react-from-scratch/ # 练习 3：从零实现 ReAct
│ │ ├── starter.py # 主程式（~70 行可跑）
│ │ ├── test.py # 自我验证（pure assert、无 pytest）
│ │ ├── README.md # 200-400 字走查（+.zh-Hans.md +.en.md）
│ │ └── requirements.txt # 依赖钉版本
│ └── ...
├── stage-1/
└── ...
```
短的练习（≤30 LOC）直接以 `<details>` 收摺塞在 stage 档内、不开资料夹。长的（>30 LOC）才开资料夹——避免 stage 档被 code block 撑爆。
## 怎么跑任一个范例
```bash
cd examples/stage-3/03-react-from-scratch
pip install -r requirements.txt
export ANTHROPIC_API_KEY=sk-ant-... # 各范例顶端会说它要哪个 key
python starter.py # 跑真的 API 看输出（会花一点点钱、约 $0.001）
python test.py # 跑验证（用 mock、不花钱）
```
## 设计原则
| 维度 | 规则 |
|---|---|
| 程序长度 | starter ≤80 LOC、超过拆档 |
| 依赖 | stdlib + 最多 2 个 pip 套件、钉版本 |
| 测试 | 纯 `assert`、不用 pytest、reader 跑 `python test.py` 看 ✅ |
| 注解 | 中文（zh-Hans 为主）、变数 / 函数名英文 |
| 自我验证 | 每个 starter.py 结尾必有 `# === 自我验证 ===` 区块 |
| 环境变数 | 顶端注解写清楚需要哪些 key |
| Free-tier 友善 | 用最便宜 model（claude-haiku / Ollama）、注解写怎么换 Sonnet |
| **Windows 编码** | **每个 .py 顶端必须有 UTF-8 reconfigure**（见下） |
### Windows cp950 编码 fix（每个 starter.py / test.py 必加）
Windows 预设 console 是 cp950（Big5）、印不出 emoji 跟非 Big5 中文。每个 `.py` 档顶端 import 区后立刻加：
```python
import sys
if hasattr(sys.stdout, "reconfigure"):
sys.stdout.reconfigure(encoding="utf-8", errors="replace")
```
否则 Windows reader 在 PowerShell / cmd 跑会炸 `UnicodeEncodeError: 'cp950' codec can't encode character '✅'`。
## 三条路径 — **默认用 Ollama（成本考量）**
> 💰 **为什么默认 Ollama？** 练习场景跑 1000 次跑满 Sonnet ~$4、跑 haiku ~$0.25、跑本机 Ollama $0。**学习阶段不该被 API 成本卡住**。Cloud LLM 留给“想看高质量答案 / production deployment”时用。
每个练习都同时提供 3 条路径：
### Path A（**默认、推荐**）— Ollama 本机
- 预设 `starter.py` / 第一个 inline `<details>` 用本机 LLM
- 需 [Ollama](https://ollama.com)、按 stage pull 对应 model：
- **Stage 1 + 2**（纯 chat / prompt eng）：`ollama pull gemma4:e4b`（~7.5 GB、多模態、CPU 跑得動）
- **Stage 3+**（tool use / agent）：`ollama pull qwen2.5:3b`（1.9 GB、tool-use 支持稳定）
- 全程 $0、offline、隐私敏感资料 OK
- SDK 用 `openai` package（OpenAI 兼容 API）、`base_url="http://localhost:11434/v1"`
- 适合：所有读者（默认推这条）
### Path B（选择性）— Anthropic API（想看 cloud 高质量时）
- 对照 `starter_anthropic.py`（folder）或第二个 inline `<details>` 区块
- 需 `ANTHROPIC_API_KEY`、跑一轮约 $0.001（haiku）/ $0.004（sonnet）
- 答案质量 / latency 都比本机 Ollama 强
- 适合：production 要求高质量、需要 long-context、Stage 7 production tier
### Path C（验逻辑、不打 API）
- 所有 `test.py` 都用 `unittest.mock`、`python test.py` 看程序逻辑有没有写对
- 跟 Path A / B 互补：先 mock 验逻辑、再 real call 确认
### 三条路的 Trade-off
| 维度 | A Ollama（默认）| B Anthropic | C Mock |
|---|---|---|---|
| Cost / call | $0 | ~$0.001-0.004 | $0 |
| 需要 | Ollama install | API key | 无 |
| 答案质量 | 中（3-4B model） | 高 | 预设、看不出真实质量 |
| 速度 | 5-30s/call（无 GPU） | ~1-3s/call | <0.1s |
| Offline | ✅ | ❌ | ✅ |
| 隐私敏感资料 | ✅ | ❌ | ✅ |
| Stage 3+ tool use | ✅（qwen2.5 / llama3.2） | ✅ | ✅ |
| 适合 | **默认、无预算压力** | production 升级 | 程序逻辑验证 |
→ **建议流程**：先 C 验逻辑（不花钱）、再 A 本机跑看实际 model 行为、production 阶段（Stage 7）再升 B 看 cloud 质量。
## 推荐 LLM 清单
> 本机 + cloud、user 视角。
> 💡 不是要你全装、是让你看到“练习用哪个”“production 升级到哪个”。**Claude 是 canonical / production 主轴；Ollama 是练习默认**。
### 本机 LLM（练习默认、用 Ollama）
| Model | 下载大小 | 建议 RAM | 对应 Stage | Tool-use | 速度（CPU/GPU） | 主用途 |
|---|---|---|---|---|---|---|
| **`gemma4:e4b`** ⭐ | 7.5 GB | 8 GB | 1+2 | 基本 | 慢 / 中 | Stage 1-2 纯 chat / prompt eng（默认）|
| **`qwen2.5:3b`** ⭐ | 1.9 GB | 4 GB | 3+ | **稳定** | 中 / 快 | Stage 3+ tool use / agent（默认）|
| `llama3.2:3b` | 2.0 GB | 4 GB | 3+ | 稳定 | 中 / 快 | qwen2.5:3b 的替代 |
| `mistral-nemo:12b` | 7.1 GB | 16 GB | 3+ | 强 | 慢 / 中 | 想看更接近 cloud 质量 |
| `qwen2.5:14b` | 9.0 GB | 16 GB | 进阶 | 强 | 慢 / 中 | 大 model 对照（需 GPU 偏好）|
| `gemma4:e2b` | 4.0 GB | 4 GB | 1+2 | 基本 | 中 / 快 | 4GB RAM 机器替代 |
安装：`ollama pull <model>` + `ollama serve`。详细硬件配置看 [resources/cli-agents-guide.zh-Hans.md](../resources/cli-agents-guide.zh-Hans.md)。
### Cloud LLM（canonical / production 主轴、用 Anthropic）
| Model | 每 1M input | 每 1M output | Context | 主用途 |
|---|---|---|---|---|
| `claude-fable-5` | $10 | $50 | 1M | Mythos 级（位阶在 Opus 之上）；2026-06-12 暂停、**2026-07-01 恢复**（出口管制解除）——目前最高阶的 Claude 层级 |
| **`claude-haiku-4-5`** ⭐ | $1 | $5 | 200k | 最便宜、Stage 1-7 练习 cloud 对照都 OK |
| **`claude-sonnet-5`** ⭐ | $3 | $15 | 1M | **production 默认**、Stage 5+ agent 开发 |
| `claude-opus-4-8` | $5 | $25 | 1M | Opus 级旗舰、复杂推理 / 长 context refactor |
订阅替代：Claude Pro $20/月含 Sonnet 用量、Claude Max $100/月含 Opus。详细看 [resources/cli-agents-guide.zh-Hans.md](../resources/cli-agents-guide.zh-Hans.md)。
### Cloud LLM 中国 / 开源 alternatives（地区限制 / 预算敏感 / 中文场景）
> 不能 / 不想用 Anthropic？这些 API **都 OpenAI-compatible**、改 `base_url` 跟 model name 就能跑本 repo 同一份练习。
| Provider | 主 model | 每 1M input | 每 1M output | OpenAI-compat? | 主卖点 |
|---|---|---|---|---|---|
| **DeepSeek** ⭐ | `deepseek-chat` (V3) | $0.27 | $1.10 | ✅ | 最便宜 cloud（比 haiku $1/$5 还便宜 4 倍）、中英文俱佳、含免费 web `chat.deepseek.com` |
| DeepSeek R1 | `deepseek-reasoner` | $0.55 | $2.19 | ✅ | 推理模型（o1 级）、价格仍只是 OpenAI o1 的 1/30 |
| **Moonshot Kimi** | `kimi-k2-turbo-preview` | $5-10 | $15-30 | ✅ | **1M token context**（卖点）、适合大文件 / 长对话。web 版 `kimi.com` 免费 |
| **通义千问 Qwen** | `qwen-max` / `qwen-turbo` | $0.50-1.50 | $1.50-6 | ✅（DashScope）| 中文 native、**同 model 也能 Ollama 本机跑**（cloud + local 两条路径都通） |
| **智谱 GLM** | `glm-4.5` / `glm-4-plus` | $0.30-2 | $1.50-9 | ✅ | 中国 native、有 free tier。web `chatglm.cn` 免费 |
| **NVIDIA NIM** | Llama / Mistral / DeepSeek / Qwen 等 hosted | free tier 1000 credits | (同) | ✅ | **托管 10+ open model**、新账号送 credits、不必本机 GPU。`build.nvidia.com` |
**API endpoints（OpenAI SDK 接法）**：
```python
# DeepSeek
client = OpenAI(api_key=os.environ["DEEPSEEK_API_KEY"], base_url="https://api.deepseek.com/v1")
r = client.chat.completions.create(model="deepseek-chat", messages=[...])
# Moonshot Kimi（中国 endpoint；海外用 .ai 结尾）
client = OpenAI(api_key=os.environ["MOONSHOT_API_KEY"], base_url="https://api.moonshot.cn/v1")
r = client.chat.completions.create(model="kimi-k2-turbo-preview", messages=[...])
# 通义千问 Qwen（Alibaba DashScope）
client = OpenAI(api_key=os.environ["DASHSCOPE_API_KEY"],
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1")
r = client.chat.completions.create(model="qwen-turbo", messages=[...])
# 智谱 GLM
client = OpenAI(api_key=os.environ["ZHIPUAI_API_KEY"], base_url="https://open.bigmodel.cn/api/paas/v4")
r = client.chat.completions.create(model="glm-4.5-flash", messages=[...])
# NVIDIA NIM（hosted open-source）
client = OpenAI(api_key=os.environ["NVIDIA_API_KEY"], base_url="https://integrate.api.nvidia.com/v1")
r = client.chat.completions.create(model="meta/llama-3.3-70b-instruct", messages=[...])
```
**怎么挑**：
| 情境 | 选 | 理由 |
|---|---|---|
| 中国大陆、无 cloud 访问 | Ollama 本机 / DeepSeek API | 本机免费；DeepSeek 在中国有 endpoint |
| 预算极敏感（< $1/月） | DeepSeek API | 比 haiku 便宜 4 倍、质量接近 |
| 大文件 / 长文档 RAG | Moonshot Kimi | 1M token context 卖点 |
| 中文 native task（古文、中文搜索）| Qwen / GLM | 训练语料中文占比高 |
| 想试 10+ open model 没 GPU | NVIDIA NIM | 一个 key 玩 Llama / Mixtral / Qwen / DeepSeek |
| Production agent（agent / tool use）| Anthropic Claude（canonical）| 本 repo Path B 默认、tool calling 最稳 |
### 预算估算（跑完 Stage 1-7 全 54 练习）
| 学习路径 | 总时间 | 总成本 | 适合谁 |
|---|---|---|---|
| **全本机 Ollama** | ~30 hr (CPU) / ~10 hr (GPU) | **$0** | 预算敏感、隐私需求、中国大陆无 cloud 访问 |
| **混合：本机练 + haiku 终验** ⭐ | ~30 hr | **$2-5** | **推荐默认**：练习 local 跑、最后 1-2 次用 haiku 看 cloud 质量 |
| **全 haiku** | ~10 hr | $5-15 | 想快、预算允许、想看完整 cloud 体验 |
| **全 sonnet** | ~8 hr | $20-50 | 深度练习、追求高质量答案 |
| **混合：sonnet 为主 + opus 难题** | ~8 hr | $30-80 | 已是 production agent 开发者 |
> 🎯 **新手默认**：先全本机跑、预算上限 $5。**Stage 7 production tier 才考虑 sonnet 升级**。
## 对应 stage 索引
| Stage | 练习 | 范例位置 |
|---|---|---|
| 1 LLM 基础 | 6 个 | inline 4 + folder 2（`examples/stage-1/`） |
| 2 Prompt eng | 4 个 | 全 inline |
| **3 Tool use** | **6 个** | inline 1 + folder 5（`examples/stage-3/`） |
| 4 Frameworks | 5 个 | 全 folder（`examples/stage-4/`） |
| 5 Claude Code 生态 | 11 个 | inline 6 + folder 5（`examples/stage-5/`） |
| 6 Memory/RAG | 5 个 | 全 folder（`examples/stage-6/`） |
| 7 Multi-agent | 5 个 | inline 1 + folder 4（`examples/stage-7/`） |
| Track A1-A3 | 12 个 | 全 inline、外加 2 个小 folder（CLI-9 / CLI-10） |
→ T1 完成范围：**只有 Stage 3 全部 6 个**（剩余 stage 按 plan 分批推进）。
## 贡献 / 报错
跑不过、结果跟预期输出对不上、或想补一个新练习：
- 开 issue 标 `examples` label
- 或直接 PR、follow 本资料夹“设计原则”表格的规则
## 为什么这样分（不直接全塞 stage 档）
1. **Stage 档保持 readable**：学习地图读者不一定要看 code、只想理解 concept；长 code block 干扰阅读流
2. **范例可独立演进**：API SDK 升版、model name 改、范例需要单独 commit、不污染学习地图 git log
3. **Reader 可以 clone 单一 example**：`svn export` 或 `git clone --filter=tree:0` 只抓一个资料夹
4. **未来 CI**：example 失败不应 block mdbook deploy；分开可让 CI 有条件性检查
examples/stage-1/04-cross-provider/README.md
+127
View File
@@ -0,0 +1,127 @@
> **繁體中文** | [简体中文](./README.zh-Hans.md) | [English](./README.en.md)
# 練習 4：Cross-Provider 比較（Claude / GPT / Gemini）
對應 [Stage 1 — LLM 基礎](../../../stages/01-llm-basics.md) 練習 4。
> 🎓 **學習模式**：這份 `starter.py` 是**完整解答**、不是 TODO skeleton。建議用**主動模式**——`mv starter.py starter_reference.py`、看 signature 不看 body、自己重寫一份 `starter.py`、跑 `python test.py` 驗證；卡 20 分鐘再回去對照 reference。完整方法論看 [`docs/HOW_TO_USE.md`](../../../docs/HOW_TO_USE.md)。
## 為什麼要比較
同樣是「解釋 AGI vs narrow AI」這個 prompt、三家 LLM 回得不一樣：
- **Claude**：通常傾向先給結構（定義 → 例子）、語氣中性
- **GPT**：傾向先給簡短答案、再展開（type-A 風格）
- **Gemini**：傾向 list / bullet 排列、example 多
跑一次自己看、比讀論文有感。順便量 token / 成本 / latency 三維。
## 怎麼跑
```bash
pip install -r requirements.txt
# 至少設一個。沒設的會 skip、不會 crash
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GOOGLE_API_KEY=...
python starter.py
```
預期看到（樣本）：
```
prompt: 用 1-2 句話解釋 AGI 跟 narrow AI 的差別。
============================================================
⚠ skip call_gemini（沒有對應 API key）
[Anthropic / claude-haiku-4-5] latency=823ms in=21 out=58
AGI（通用人工智慧）能跨領域學習與解題；narrow AI 只擅長單一任務...
[OpenAI / gpt-5-mini] latency=612ms in=24 out=49
Narrow AI 專精於特定任務（如下棋、辨識）、AGI 則具備...
✅ 練習 4 通過 — 收到 2 家 provider 回應、可比較風格 / 長度 / 成本
```
## 不花錢驗證程式邏輯
```bash
python test.py
```
4 個 test 都用 `unittest.mock.patch` 取代 SDK：
```
✅ test_skip_when_no_key
✅ test_compare_returns_only_valid_replies
✅ test_reply_dataclass_shape
✅ test_compare_one_provider_set
🎉 全部通過 — Cross-provider 邏輯正確（skip-on-missing-key 已驗）
```
## 程式結構走查
| 段 | 在做什麼 |
|---|---|
| `Reply` dataclass | 統一三家 SDK 各自 Response 物件、抽出 4 個共通欄位（text/in/out/latency） |
| `call_claude / call_openai / call_gemini` | 各家 SDK 包裝、沒 key 就 return `None` |
| `compare(prompt)` | 跑三個 caller、跳過 None、回 valid replies list |
| `__main__` | 印對照表、自我驗證 |
## 常見坑
1. **三家 SDK API shape 差很多**：Anthropic 用 `messages.create`、OpenAI 用 `chat.completions.create`、Google 用 `models.generate_content`。**用 dataclass 統一才能比較**
2. **Token 計算欄位名不一樣**：Anthropic 是 `input_tokens / output_tokens`、OpenAI 是 `prompt_tokens / completion_tokens`、Google 是 `prompt_token_count / candidates_token_count`
3. **沒設 key 應該 skip 而非 raise**：production code 一定要做這層 guard、production agent 不能因為一家 down 就全死
4. **沒抓 latency**：跑完才知道哪家慢、production routing 需要這 data
## 想加更多家？
OpenRouter / Mistral / Cohere / Groq 都是 OpenAI-compatible API、改 `base_url` 就接：
```python
client = OpenAI(
base_url="https://api.groq.com/openai/v1",
api_key=os.environ["GROQ_API_KEY"],
)
```
## 🦙 Path B — 加上本機 Ollama 當第 4 家對照
`call_openai` 已經是 OpenAI-compatible client、把 `base_url` 跟 `model` 換掉就接 Ollama：
```python
def call_ollama(prompt: str) -> Reply | None:
"""本機 Ollama (gemma4:e4b 或 qwen2.5:3b)。沒裝就 return None、不 crash。"""
import requests
try:
requests.get("http://localhost:11434/api/tags", timeout=2)
except Exception:
return None # Ollama 沒跑
from openai import OpenAI
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
t0 = time.time()
r = client.chat.completions.create(
model="gemma4:e4b",
max_tokens=200,
messages=[{"role": "user", "content": prompt}],
)
return Reply(
provider="Ollama-local",
model="gemma4:e4b",
text=r.choices[0].message.content or "",
in_tokens=r.usage.prompt_tokens,
out_tokens=r.usage.completion_tokens,
latency_ms=int((time.time() - t0) * 1000),
)
```
把 `call_ollama` 加進 `compare()` 的 caller list、就能看 4 家對照（包括本機 free $0 model）。實測你會發現 gemma4:e4b 在 CPU 上的 latency 通常比 cloud 慢 5-10 倍、但 cost = 0。
## 延伸
- **成本對照** → 接 [`examples/stage-1/03-pricing/`](../) 的 PRICING dict、印 dollar cost column
- **同 prompt 跑 N 次取平均** → 在 `compare()` 內加 for-loop、看 latency stdev
- **加 quality eval** → 加第四家 LLM 當 judge、給每家回應打分（這在 Stage 7 練習 2 會教）
examples/stage-1/04-cross-provider/requirements.txt
+3
View File
@@ -0,0 +1,3 @@
anthropic>=0.40,<1.0
openai>=1.50,<2.0
google-genai>=1.0,<2.0
examples/stage-1/04-cross-provider/starter.py
+132
View File
@@ -0,0 +1,132 @@
"""
Stage 1 練習 4：Cross-Provider 比較 — starter.py
同一個 prompt 同時送給 Claude / GPT / Gemini、印對照表。
缺哪家 key 就 skip 哪家、不 crash。
跑法：
pip install -r requirements.txt
export ANTHROPIC_API_KEY=... # 至少設一個
export OPENAI_API_KEY=... # （可選）
export GOOGLE_API_KEY=... # （可選）
python starter.py
驗證：
python test.py （用 mock、不打 API）
"""
from __future__ import annotations
import os
import sys
import time
from dataclasses import dataclass
if hasattr(sys.stdout, "reconfigure"):
sys.stdout.reconfigure(encoding="utf-8", errors="replace")
PROMPT = "用 1-2 句話解釋 AGI 跟 narrow AI 的差別。"
@dataclass
class Reply:
provider: str
model: str
text: str
in_tokens: int
out_tokens: int
latency_ms: int
def call_claude(prompt: str) -> Reply | None:
if not os.environ.get("ANTHROPIC_API_KEY"):
return None
import anthropic
client = anthropic.Anthropic()
t0 = time.time()
msg = client.messages.create(
model="claude-haiku-4-5",
max_tokens=200,
messages=[{"role": "user", "content": prompt}],
)
return Reply(
provider="Anthropic",
model="claude-haiku-4-5",
text=msg.content[0].text,
in_tokens=msg.usage.input_tokens,
out_tokens=msg.usage.output_tokens,
latency_ms=int((time.time() - t0) * 1000),
)
def call_openai(prompt: str) -> Reply | None:
if not os.environ.get("OPENAI_API_KEY"):
return None
from openai import OpenAI
client = OpenAI()
t0 = time.time()
r = client.chat.completions.create(
model="gpt-4o-mini",
max_tokens=200,
messages=[{"role": "user", "content": prompt}],
)
return Reply(
provider="OpenAI",
model="gpt-4o-mini",
text=r.choices[0].message.content or "",
in_tokens=r.usage.prompt_tokens,
out_tokens=r.usage.completion_tokens,
latency_ms=int((time.time() - t0) * 1000),
)
def call_gemini(prompt: str) -> Reply | None:
if not os.environ.get("GOOGLE_API_KEY"):
return None
from google import genai
client = genai.Client()
t0 = time.time()
r = client.models.generate_content(
model="gemini-2.0-flash",
contents=prompt,
)
usage = getattr(r, "usage_metadata", None)
return Reply(
provider="Google",
model="gemini-2.0-flash",
text=r.text,
in_tokens=getattr(usage, "prompt_token_count", 0) or 0,
out_tokens=getattr(usage, "candidates_token_count", 0) or 0,
latency_ms=int((time.time() - t0) * 1000),
)
def compare(prompt: str) -> list[Reply]:
replies = []
for fn in (call_claude, call_openai, call_gemini):
r = fn(prompt)
if r is None:
print(f"⚠ skip {fn.__name__}（沒有對應 API key）")
else:
replies.append(r)
return replies
if __name__ == "__main__":
print(f"prompt: {PROMPT}\n" + "=" * 60)
replies = compare(PROMPT)
for r in replies:
print(f"\n[{r.provider} / {r.model}] latency={r.latency_ms}ms in={r.in_tokens} out={r.out_tokens}")
print(r.text)
# === 自我驗證 ===
assert len(replies) >= 1, "至少要有一家 provider 回應（請設一個 API key）"
for r in replies:
assert len(r.text) > 5, f"{r.provider} 回應太短"
assert r.in_tokens > 0, f"{r.provider} 沒 input token"
print(f"\n✅ 練習 4 通過 — 收到 {len(replies)} 家 provider 回應、可比較風格 / 長度 / 成本")
examples/stage-1/04-cross-provider/test.py
+73
View File
@@ -0,0 +1,73 @@
"""
Stage 1 練習 4 自我驗證：用 mock 取代三家 SDK、不打 API。
驗證內容：
- 沒設 key 的 provider 自動 skip、不會 crash
- 設了 key 的 provider 正常 call、Reply dataclass 結構正確
- 至少一家 provider 才能 pass
"""
from __future__ import annotations
import os
import sys
from unittest.mock import patch
if hasattr(sys.stdout, "reconfigure"):
sys.stdout.reconfigure(encoding="utf-8", errors="replace")
from starter import Reply, call_claude, call_openai, call_gemini, compare
def test_skip_when_no_key():
"""沒設任何 key 時、三個 call_xxx 都該回 None。"""
with patch.dict(os.environ, {}, clear=True):
assert call_claude("hi") is None
assert call_openai("hi") is None
assert call_gemini("hi") is None
print("✅ test_skip_when_no_key")
def test_compare_returns_only_valid_replies():
"""compare() 跳過沒 key 的 provider、不會 raise。"""
with patch.dict(os.environ, {}, clear=True):
replies = compare("hi")
assert replies == [], "沒任何 key 時、replies 應為空 list"
print("✅ test_compare_returns_only_valid_replies")
def test_reply_dataclass_shape():
"""Reply 結構 ok。"""
r = Reply(
provider="X", model="x-1", text="hello",
in_tokens=10, out_tokens=20, latency_ms=500,
)
assert r.provider == "X"
assert r.in_tokens + r.out_tokens == 30
print("✅ test_reply_dataclass_shape")
def test_compare_one_provider_set():
"""模擬：只設 ANTHROPIC_API_KEY、call_claude 被 mock 成回固定 Reply。"""
fake_reply = Reply(
provider="Anthropic", model="claude-haiku-4-5",
text="AGI 跟 narrow AI 的差別…",
in_tokens=20, out_tokens=50, latency_ms=800,
)
with patch.dict(os.environ, {"ANTHROPIC_API_KEY": "sk-fake"}, clear=True), \
patch("starter.call_claude", return_value=fake_reply):
replies = compare("test prompt")
assert len(replies) == 1
assert replies[0].provider == "Anthropic"
assert replies[0].in_tokens == 20
print("✅ test_compare_one_provider_set")
if __name__ == "__main__":
test_skip_when_no_key()
test_compare_returns_only_valid_replies()
test_reply_dataclass_shape()
test_compare_one_provider_set()
print("\n🎉 全部通過 — Cross-provider 邏輯正確（skip-on-missing-key 已驗）")
examples/stage-1/05-error-handling/README.en.md
+116
View File
@@ -0,0 +1,116 @@
<div align="right">
<a href="./README.md">繁體中文</a> | <a href="./README.zh-Hans.md">简体中文</a> | <strong>English</strong>
</div>
# Exercise 5: Error Handling + Retry Wrapper
Corresponds to [Stage 1 — LLM Basics](../../../stages/01-llm-basics.en.md) Exercise 5.
## Why this matters
Production agents in Stages 3-8 will absolutely hit API errors:
- Rate limit (429) — different subscription tiers, you can hit it anytime
- Network jitter (connection reset) — cross-DC / VPN happens daily
- Expired API key (401) — rotation out of sync
- Context overflow (400) — you appended too much history
**Some errors should be retried (rate limit / network), others should not (key, context full).** Not distinguishing them is one of the most common production-agent mistakes.
## How to run — two paths
### Path A (default, free, local)
```bash
pip install -r requirements.txt
ollama pull gemma4:e4b
ollama serve
python starter.py
```
Budget: **$0**. The local demo shows connection / context-window behavior.
### Path B (Anthropic, real cloud errors)
```bash
pip install -r requirements.txt
export ANTHROPIC_API_KEY=sk-ant-...
python starter_anthropic.py
```
Budget: ~**$0.0005** per run (only "scenario 2 normal call" actually hits the API).
Expected output (Path A, local):
```
[Scenario 1] Pointing at a dead Ollama port
✅ Caught APIConnectionError
💡 Production handling: retry (network errors are typically transient)
[Scenario 2] Normal call wrapped in with_retry (needs Ollama running)
✅ Succeeded on first try: 👋
[Scenario 3] Prompt over context window (Ollama usually truncates or raises)
⚠ Ollama didn't raise (it likely truncated). Cloud APIs would 400.
✅ Exercise 5 passed — you understand which errors raise, when to retry, when to stop. $0/run
```
## Validate the logic without network failures (mock-based)
```bash
python test.py # validates Path A (Ollama) retry wrapper
python test_anthropic.py # validates Path B (Anthropic) retry wrapper
```
6 tests use `unittest.mock` to fabricate errors + fake sleep (0 real seconds), validating the retry logic:
```
✅ test_no_retry_when_success_first_time
✅ test_retry_on_connection_error_then_success
✅ test_retry_on_rate_limit
✅ test_raise_after_max_attempts
✅ test_no_retry_on_auth_error
✅ test_exponential_backoff_delays
🎉 All passed — retry wrapper logic correct
```
> **Local advantage**: Ollama can't hit a real `RateLimitError` (no quota), so the "rate limit demo" is invisible. But the mock-based tests cover the retry logic completely and reproduce in 0 seconds — which is precisely what makes the Ollama path ideal for **learning retry patterns: fast, free, deterministic**.
## Program structure walkthrough
| Section | What it does |
|---|---|
| `RETRIABLE = (APIConnectionError, RateLimitError)` | Whitelist: only these two retry; everything else raises |
| `with_retry(fn, ...)` | Exponential backoff wrapper: 1s, 2s, 4s, 8s + jitter |
| `demo_bad_key()` | Triggers a network / 401 error to inspect the raised exception |
| `demo_with_retry()` | Normal call wrapped in `with_retry`, expected to succeed on first try |
| `demo_too_long_prompt()` | Oversize prompt — see how the context-window limit surfaces |
## Exception-class mapping between SDKs
| Anthropic SDK | OpenAI SDK (Ollama) | Meaning | RETRIABLE? |
|---|---|---|---|
| `anthropic.APIConnectionError` | `openai.APIConnectionError` | Network down | ✅ |
| `anthropic.RateLimitError` | `openai.RateLimitError` | 429 throttle | ✅ |
| `anthropic.AuthenticationError` | `openai.AuthenticationError` | 401 bad key | ❌ |
| `anthropic.APIStatusError` | `openai.APIStatusError` | Generic HTTP error | Depends on status |
The two SDKs use nearly identical class names; the retry logic is **fully backend-agnostic**. Swap SDKs = change the import line.
## Common pitfalls
1. **Blindly retry every exception** — you'll retry `AuthenticationError` 4 times for nothing. The RETRIABLE whitelist is the heart of this pattern
2. **No jitter** — 1000 workers rate-limited together, all retry after 1s, hit the limit again → deadlock. Add `random.uniform(0, 0.3)` to spread them
3. **`max_attempts` too high** — 8 retries = 1+2+4+8+16+32+64+128 = 255s, user gave up long ago. `max_attempts=4` usually suffices
4. **No attempt-count metric** — production must emit retry-count metrics; alert above threshold
5. **Ignoring `Retry-After`** — rate-limit responses include this header; SDKs handle it automatically, but a custom wrapper shouldn't ignore the hint
## Extensions
- **Better jitter** — try [decorrelated jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/) for stability
- **Circuit breaker** — after N consecutive failures, stop calling for a while
- **Use [tenacity](https://github.com/jd/tenacity)** — production code shouldn't roll its own retry; this starter is just to show what's inside
- **Finer error classification** — different backoffs for 429 / 503 / 502 / 500
- **Stage 3 tool-level errors** — see [`../../stage-3/05-error-handling/`](../../stage-3/05-error-handling/) for structured tool errors that let the LLM decide within a ReAct loop
examples/stage-1/05-error-handling/README.md
+118
View File
@@ -0,0 +1,118 @@
<div align="right">
<strong>繁體中文</strong> | <a href="./README.zh-Hans.md">简体中文</a> | <a href="./README.en.md">English</a>
</div>
# 練習 5：Error Handling + Retry wrapper
對應 [Stage 1 — LLM 基礎](../../../stages/01-llm-basics.md) 練習 5。
> 🎓 **學習模式**：這份 `starter.py` 是**完整解答**、不是 TODO skeleton。建議用**主動模式**——`mv starter.py starter_reference.py`、看 signature 不看 body、自己重寫一份 `starter.py`、跑 `python test.py` 驗證；卡 20 分鐘再回去對照 reference。完整方法論看 [`docs/HOW_TO_USE.md`](../../../docs/HOW_TO_USE.md)。
## 為什麼這題重要
Stage 3-8 的 production agent 一定會碰到 API 錯誤：
- Rate limit（429）→ 雲端 API 訂閱階級不一樣、隨時可能撞到
- 網路抖（connection reset）→ 跨機房 / VPN 是日常
- API key 過期（401）→ rotate 沒同步
- Context 過長（400）→ 你給太多歷史對話
**有些錯誤該 retry（rate limit / 網路）、有些不該（key 錯、context 滿）**。沒分清楚 = 寫 production agent 的常見坑。
## 怎麼跑 — 兩條路徑
### Path A（默認、本機免費）
```bash
pip install -r requirements.txt
ollama pull gemma4:e4b
ollama serve
python starter.py
```
預算：**$0**。本機 demo 看 connection error / context window 的反應。
### Path B（Anthropic、想看真實 cloud 錯誤）
```bash
pip install -r requirements.txt
export ANTHROPIC_API_KEY=sk-ant-...
python starter_anthropic.py
```
預算：每次 ≈ **$0.0005**（只有「情境 2 正常 call」會打 API、claude-haiku-4-5）。
預期看到（Path A、本機）：
```
[情境 1] 故意連到不存在的 Ollama port
✅ 抓到 APIConnectionError: APIConnectionError
💡 production 處理: retry（網路錯通常是 transient）
[情境 2] 正常 call、with_retry 包裝（需要 Ollama 在跑）
✅ 成功、第一次就過: 👋
[情境 3] Prompt 超過 context window（Ollama 通常會截斷或 raise）
⚠ Ollama 沒 raise（可能直接截斷 prompt）。Cloud API 通常會 400
✅ 練習 5 通過 — 你已了解 3 種錯誤如何 raise、知道何時該 retry 何時該 stop、$0/run
```
## 不花錢驗證程式邏輯（不需真的斷網）
```bash
python test.py # 驗 Path A (Ollama) retry wrapper 邏輯
python test_anthropic.py # 驗 Path B (Anthropic) retry wrapper 邏輯
```
6 個 test 都用 `unittest.mock` 構造假錯誤 + 假 sleep（時間 0 秒）、驗證 retry 邏輯：
```
✅ test_no_retry_when_success_first_time
✅ test_retry_on_connection_error_then_success
✅ test_retry_on_rate_limit
✅ test_raise_after_max_attempts
✅ test_no_retry_on_auth_error
✅ test_exponential_backoff_delays
🎉 全部通過 — retry wrapper 邏輯正確
```
> **本機優勢**：Ollama 不會真的撞 RateLimitError（沒 quota），所以「rate limit demo」看不到。但 mock-based test 完整、retry 邏輯 0 秒可重現——這恰好是 Ollama path 適合理解 retry pattern 的地方：**快、免費、可重現**。
## 程式結構走查
| 段 | 在做什麼 |
|---|---|
| `RETRIABLE = (APIConnectionError, RateLimitError)` | 白名單：只 retry 這兩種、其他直接 raise |
| `with_retry(fn, ...)` | exponential backoff wrapper：1s, 2s, 4s, 8s + jitter |
| `demo_bad_key()` (Ollama) / `demo_bad_key()` (Anthropic) | 故意觸發網路 / 401 錯、看 exception 怎麼 raise |
| `demo_with_retry()` | 正常 call 包 with_retry、預期 1 次成功 |
| `demo_too_long_prompt()` | 超長 prompt、看 context window 反應 |
## 兩個 SDK 的 exception class 對應表
| Anthropic SDK | OpenAI SDK (Ollama) | 含義 | RETRIABLE? |
|---|---|---|---|
| `anthropic.APIConnectionError` | `openai.APIConnectionError` | 網路斷 | ✅ |
| `anthropic.RateLimitError` | `openai.RateLimitError` | 429 限流 | ✅ |
| `anthropic.AuthenticationError` | `openai.AuthenticationError` | 401 key 錯 | ❌ |
| `anthropic.APIStatusError` | `openai.APIStatusError` | 一般 HTTP 錯 | 視 status code |
兩個 SDK 的 exception class 名字幾乎一樣、retry 邏輯**完全跨 backend**。換 SDK 只要改 import 那一行。
## 常見坑
1. **無腦 retry 所有 exception**：會把 AuthenticationError 也 retry 一遍、浪費 4 倍時間最後 still 401。RETRIABLE 白名單是核心
2. **Backoff 不加 jitter**：1000 個 worker 同時被 rate limit、同時 1s 後重試、再次 rate limit → 死循。加 `random.uniform(0, 0.3)` 打散
3. **max_attempts 太高**：retry 8 次 = 1+2+4+8+16+32+64+128 = 255 秒、user 早就 give up。`max_attempts=4` 通常夠
4. **沒記錄 attempt count**：production 一定要把 retry 次數加進 metric、超過 threshold 該 alert
5. **rate limit response 帶 `Retry-After` header**：API 告訴你等多久、SDK 已自動處理，但自寫 wrapper 別忽略這個 hint
## 延伸
- **加 jitter strategy**：除了 uniform、可試 [decorrelated jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)（更穩）
- **加 circuit breaker**：連續 N 次 retry 失敗、暫時 stop call
- **改用 [tenacity](https://github.com/jd/tenacity)** library：production 不要自己寫 retry、用成熟 lib
- **錯誤分類更細**：依 status code（429 / 503 / 502 / 500）給不同 backoff strategy
- **Stage 3 tool-level 錯誤**：看 [`../../stage-3/05-error-handling/`](../../stage-3/05-error-handling/)、結構化 tool error 讓 LLM 在 ReAct loop 裡決策
examples/stage-1/05-error-handling/README.zh-Hans.md
+116
View File
@@ -0,0 +1,116 @@
<div align="right">
<a href="./README.md">繁體中文</a> | <strong>简体中文</strong> | <a href="./README.en.md">English</a>
</div>
# 练习 5：Error Handling + Retry wrapper
对应 [Stage 1 — LLM 基础](../../../stages/01-llm-basics.zh-Hans.md) 练习 5。
## 为什么这题重要
Stage 3-8 的 production agent 一定会碰到 API 错误：
- Rate limit（429）→ 云端 API 订阅级别不一样、随时可能撞到
- 网络抖（connection reset）→ 跨机房 / VPN 是日常
- API key 过期（401）→ rotate 没同步
- Context 过长（400）→ 你给太多历史对话
**有些错误该 retry（rate limit / 网络）、有些不该（key 错、context 满）**。没分清楚 = 写 production agent 的常见坑。
## 怎么跑 — 两条路径
### Path A（默认、本机免费）
```bash
pip install -r requirements.txt
ollama pull gemma4:e4b
ollama serve
python starter.py
```
预算：**$0**。本机 demo 看 connection error / context window 的反应。
### Path B（Anthropic、想看真实 cloud 错误）
```bash
pip install -r requirements.txt
export ANTHROPIC_API_KEY=sk-ant-...
python starter_anthropic.py
```
预算：每次 ≈ **$0.0005**（只有“情境 2 正常 call”会打 API、claude-haiku-4-5）。
预期看到（Path A、本机）：
```
[情境 1] 故意连到不存在的 Ollama port
✅ 抓到 APIConnectionError: APIConnectionError
💡 production 处理: retry（网路错通常是 transient）
[情境 2] 正常 call、with_retry 包装（需要 Ollama 在跑）
✅ 成功、第一次就过: 👋
[情境 3] Prompt 超过 context window（Ollama 通常会截断或 raise）
⚠ Ollama 没 raise（可能直接截断 prompt）。Cloud API 通常会 400
✅ 练习 5 通过 — 你已了解 3 种错误如何 raise、知道何时该 retry 何时该 stop、$0/run
```
## 不花钱验证程序逻辑（不需真的断网）
```bash
python test.py # 验 Path A (Ollama) retry wrapper 逻辑
python test_anthropic.py # 验 Path B (Anthropic) retry wrapper 逻辑
```
6 个 test 都用 `unittest.mock` 构造假错误 + 假 sleep（时间 0 秒）、验证 retry 逻辑：
```
✅ test_no_retry_when_success_first_time
✅ test_retry_on_connection_error_then_success
✅ test_retry_on_rate_limit
✅ test_raise_after_max_attempts
✅ test_no_retry_on_auth_error
✅ test_exponential_backoff_delays
🎉 全部通过 — retry wrapper 逻辑正确
```
> **本机优势**：Ollama 不会真的撞 RateLimitError（没 quota），所以“rate limit demo”看不到。但 mock-based test 完整、retry 逻辑 0 秒可重现——这恰好是 Ollama path 适合理解 retry pattern 的地方：**快、免费、可重现**。
## 程序结构走查
| 段 | 在做什么 |
|---|---|
| `RETRIABLE = (APIConnectionError, RateLimitError)` | 白名单：只 retry 这两种、其他直接 raise |
| `with_retry(fn, ...)` | exponential backoff wrapper：1s, 2s, 4s, 8s + jitter |
| `demo_bad_key()` (Ollama) / `demo_bad_key()` (Anthropic) | 故意触发网络 / 401 错、看 exception 怎么 raise |
| `demo_with_retry()` | 正常 call 包 with_retry、预期 1 次成功 |
| `demo_too_long_prompt()` | 超长 prompt、看 context window 反应 |
## 两个 SDK 的 exception class 对应表
| Anthropic SDK | OpenAI SDK (Ollama) | 含义 | RETRIABLE? |
|---|---|---|---|
| `anthropic.APIConnectionError` | `openai.APIConnectionError` | 网络断 | ✅ |
| `anthropic.RateLimitError` | `openai.RateLimitError` | 429 限流 | ✅ |
| `anthropic.AuthenticationError` | `openai.AuthenticationError` | 401 key 错 | ❌ |
| `anthropic.APIStatusError` | `openai.APIStatusError` | 一般 HTTP 错 | 视 status code |
两个 SDK 的 exception class 名字几乎一样、retry 逻辑**完全跨 backend**。换 SDK 只要改 import 那一行。
## 常见坑
1. **无脑 retry 所有 exception**：会把 AuthenticationError 也 retry 一遍、浪费 4 倍时间最后 still 401。RETRIABLE 白名单是核心
2. **Backoff 不加 jitter**：1000 个 worker 同时被 rate limit、同时 1s 后重试、再次 rate limit → 死循。加 `random.uniform(0, 0.3)` 打散
3. **max_attempts 太高**：retry 8 次 = 1+2+4+8+16+32+64+128 = 255 秒、user 早就 give up。`max_attempts=4` 通常够
4. **没记录 attempt count**：production 一定要把 retry 次数加进 metric、超过 threshold 该 alert
5. **rate limit response 带 `Retry-After` header**：API 告诉你等多久、SDK 已自动处理，但自写 wrapper 别忽略这个 hint
## 延伸
- **加 jitter strategy**：除了 uniform、可试 [decorrelated jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)（更稳）
- **加 circuit breaker**：连续 N 次 retry 失败、暂时 stop call
- **改用 [tenacity](https://github.com/jd/tenacity)** library：production 不要自己写 retry、用成熟 lib
- **错误分类更细**：依 status code（429 / 503 / 502 / 500）给不同 backoff strategy
- **Stage 3 tool-level 错误**：看 [`../../stage-3/05-error-handling/`](../../stage-3/05-error-handling/)、结构化 tool error 让 LLM 在 ReAct loop 里决策
examples/stage-1/05-error-handling/requirements.txt
+2
View File
@@ -0,0 +1,2 @@
openai>=1.50,<2.0
anthropic>=0.40,<1.0 # 只 starter_anthropic.py 需要、Ollama path 不用
examples/stage-1/05-error-handling/starter.py
+137
View File
@@ -0,0 +1,137 @@
"""
Stage 1 練習 5：Error Handling + Retry wrapper — Path A（Ollama 默認、本機免費）。
3 種錯誤情境 + 1 個 retry wrapper：
1. API key 錯（401 AuthenticationError）→ 不要 retry、直接 raise
2. Rate limit（429 RateLimitError）→ exponential backoff retry
3. 網路錯（APIConnectionError）→ exponential backoff retry
跑法：
pip install -r requirements.txt
ollama pull gemma4:e4b # Stage 1+2 預設、CPU-friendly
ollama serve # 預設 port 11434
python starter.py
驗證：
python test.py （mock 三種錯誤、不需真的斷網）
想看 Anthropic 版本：
python starter_anthropic.py （需 ANTHROPIC_API_KEY）
⚠️ 注意：本機 Ollama 不會真的撞 RateLimitError（沒 quota），所以「情境 2 rate limit」
demo 看不到。但 `python test.py` 全部用 mock、retry 邏輯一樣可以完整驗證。
這恰好是 Ollama path 反而更適合理解 retry pattern——快、免費、可重現。
"""
from __future__ import annotations
import os
import random
import sys
import time
from typing import Any, Callable
if hasattr(sys.stdout, "reconfigure"):
sys.stdout.reconfigure(encoding="utf-8", errors="replace")
from openai import (
APIConnectionError,
APIStatusError,
AuthenticationError,
OpenAI,
RateLimitError,
)
MODEL = os.environ.get("MODEL", "gemma4:e4b")
# === Retry wrapper ===
RETRIABLE = (APIConnectionError, RateLimitError)
MAX_ATTEMPTS = 4
BASE_DELAY = 1.0 # 秒
def with_retry(fn: Callable[[], Any], *, max_attempts: int = MAX_ATTEMPTS, base_delay: float = BASE_DELAY, sleep_fn=time.sleep) -> Any:
"""
Exponential backoff retry。
- RETRIABLE 例外 → 等 base * 2^attempt 秒再試（含 jitter）
- 不 retriable 例外（譬如 AuthenticationError）→ 直接 raise、不浪費時間
"""
last_exc = None
for attempt in range(max_attempts):
try:
return fn()
except RETRIABLE as e: # noqa: PERF203
last_exc = e
if attempt == max_attempts - 1:
break
delay = base_delay * (2 ** attempt) + random.uniform(0, 0.3)
print(f" ⚠ attempt {attempt+1}/{max_attempts} fail ({type(e).__name__}); retry in {delay:.1f}s")
sleep_fn(delay)
raise last_exc # type: ignore[misc]
# === 3 個錯誤情境 demo ===
def demo_bad_key() -> None:
"""情境 1: 故意用壞 base_url、看 APIConnectionError（Ollama 沒在跑時）。"""
print("\n[情境 1] 故意連到不存在的 Ollama port")
client = OpenAI(base_url="http://localhost:65535/v1", api_key="ollama")
try:
client.chat.completions.create(
model=MODEL,
max_tokens=10,
messages=[{"role": "user", "content": "hi"}],
)
except APIConnectionError as e:
print(f" ✅ 抓到 APIConnectionError: {type(e).__name__}")
print(f" 💡 production 處理: retry（網路錯通常是 transient）")
def demo_with_retry() -> None:
"""情境 2: 包 with_retry 跑一次正常 call、應該第 1 次就成功。"""
print("\n[情境 2] 正常 call、with_retry 包裝（需要 Ollama 在跑）")
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
def call():
return client.chat.completions.create(
model=MODEL,
max_tokens=30,
messages=[{"role": "user", "content": "用一個 emoji 回答。"}],
)
try:
msg = with_retry(call)
print(f" ✅ 成功、第一次就過: {msg.choices[0].message.content}")
except APIConnectionError:
print(" ⚠ Ollama 沒在跑（port 11434 不通）。請先 `ollama serve`")
def demo_too_long_prompt() -> None:
"""情境 3: 故意丟超大 prompt、看 context window 滿了怎樣。"""
print("\n[情境 3] Prompt 超過 context window（Ollama 通常會截斷或 raise）")
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
huge_prompt = "重複很多次的 token。" * 200_000 # ~1M tokens
try:
client.chat.completions.create(
model=MODEL,
max_tokens=10,
messages=[{"role": "user", "content": huge_prompt}],
)
print(" ⚠ Ollama 沒 raise（可能直接截斷 prompt）。Cloud API 通常會 400")
except APIStatusError as e:
print(f" ✅ 抓到 APIStatusError: {e.status_code}")
print(f" 💡 production 處理: 在 client 端先 count token、超過就拒、別浪費 API call")
except APIConnectionError:
print(" ⚠ Ollama 沒在跑")
if __name__ == "__main__":
demo_bad_key()
demo_with_retry()
demo_too_long_prompt()
# === 自我驗證 ===
print("\n✅ 練習 5 通過 — 你已了解 3 種錯誤如何 raise、知道何時該 retry 何時該 stop、$0/run")
examples/stage-1/05-error-handling/starter_anthropic.py
+121
View File
@@ -0,0 +1,121 @@
"""
Stage 1 練習 5：Error Handling + Retry wrapper — Path B（Anthropic Claude）。
3 種錯誤情境 + 1 個 retry wrapper：
1. API key 錯（401 AuthenticationError）→ 不要 retry、直接 raise
2. Rate limit（429 RateLimitError）→ exponential backoff retry
3. 網路錯（APIConnectionError）→ exponential backoff retry
跑法：
pip install -r requirements.txt
export ANTHROPIC_API_KEY=sk-ant-...
python starter_anthropic.py
預算：每次 ≈ $0.0005（只有「情境 2 正常 call」會真的打 API、claude-haiku-4-5）。
Ollama 版本見 starter.py（本機 $0、用 openai SDK exception class）。
"""
from __future__ import annotations
import os
import random
import sys
import time
from typing import Any, Callable
if hasattr(sys.stdout, "reconfigure"):
sys.stdout.reconfigure(encoding="utf-8", errors="replace")
import anthropic
from anthropic import (
APIConnectionError,
APIStatusError,
AuthenticationError,
RateLimitError,
)
# === Retry wrapper ===
RETRIABLE = (APIConnectionError, RateLimitError)
MAX_ATTEMPTS = 4
BASE_DELAY = 1.0 # 秒
def with_retry(fn: Callable[[], Any], *, max_attempts: int = MAX_ATTEMPTS, base_delay: float = BASE_DELAY, sleep_fn=time.sleep) -> Any:
"""
Exponential backoff retry。
- RETRIABLE 例外 → 等 base * 2^attempt 秒再試（含 jitter）
- 不 retriable 例外（譬如 AuthenticationError）→ 直接 raise、不浪費時間
"""
last_exc = None
for attempt in range(max_attempts):
try:
return fn()
except RETRIABLE as e: # noqa: PERF203
last_exc = e
if attempt == max_attempts - 1:
break # 最後一次失敗、break 出來 raise
delay = base_delay * (2 ** attempt) + random.uniform(0, 0.3)
print(f" ⚠ attempt {attempt+1}/{max_attempts} fail ({type(e).__name__}); retry in {delay:.1f}s")
sleep_fn(delay)
raise last_exc # type: ignore[misc]
# === 3 個錯誤情境 demo ===
def demo_bad_key() -> None:
"""情境 1: 故意用壞 key、看 AuthenticationError 怎麼 raise。"""
print("\n[情境 1] 故意用壞 API key")
client = anthropic.Anthropic(api_key="sk-ant-FAKE-KEY-DO-NOT-USE")
try:
client.messages.create(
model="claude-haiku-4-5",
max_tokens=10,
messages=[{"role": "user", "content": "hi"}],
)
except AuthenticationError as e:
print(f" ✅ 抓到 AuthenticationError: {e.status_code}")
print(f" 💡 production 處理: 立刻 alert、stop retry（key 不會自己變對）")
def demo_with_retry() -> None:
"""情境 2: 包 with_retry 跑一次正常 call、應該第 1 次就成功。"""
print("\n[情境 2] 正常 call、with_retry 包裝")
client = anthropic.Anthropic()
def call():
return client.messages.create(
model="claude-haiku-4-5",
max_tokens=30,
messages=[{"role": "user", "content": "用一個 emoji 回答。"}],
)
msg = with_retry(call)
print(f" ✅ 成功、第一次就過: {msg.content[0].text}")
def demo_too_long_prompt() -> None:
"""情境 3: 故意丟超大 prompt、看 context window 滿了怎樣。"""
print("\n[情境 3] Prompt 超過 context window")
client = anthropic.Anthropic()
huge_prompt = "重複很多次的 token。" * 300_000 # ~1.5M tokens、絕對超過任何 model
try:
client.messages.create(
model="claude-haiku-4-5",
max_tokens=10,
messages=[{"role": "user", "content": huge_prompt}],
)
except APIStatusError as e:
print(f" ✅ 抓到 APIStatusError: {e.status_code}")
print(f" 💡 production 處理: 在 client 端先 count token、超過就拒、別浪費 API call")
if __name__ == "__main__":
demo_bad_key()
demo_with_retry()
demo_too_long_prompt()
# === 自我驗證 ===
print("\n✅ 練習 5 通過 — 你已了解 3 種錯誤如何 raise、知道何時該 retry 何時該 stop")
examples/stage-1/05-error-handling/test.py
+126
View File
@@ -0,0 +1,126 @@
"""
Stage 1 練習 5 自我驗證 — Path A（Ollama starter.py）。
跑法：
python test.py
驗證內容：
- with_retry 對 RETRIABLE 錯誤會 retry
- with_retry 對 non-retriable（譬如 AuthenticationError）直接 raise、不浪費 retry
- 超過 max_attempts 後 raise 最後一個 exception
- sleep 確實被叫（透過 mock sleep_fn）
- exponential backoff 真的指數增長
Anthropic 版本見 test_anthropic.py。
"""
from __future__ import annotations
import sys
from unittest.mock import MagicMock
if hasattr(sys.stdout, "reconfigure"):
sys.stdout.reconfigure(encoding="utf-8", errors="replace")
from openai import APIConnectionError, AuthenticationError, RateLimitError
from starter import with_retry
def _make_connection_error():
"""openai.APIConnectionError 需要 request 參數、用 MagicMock 假裝。"""
return APIConnectionError(request=MagicMock())
def _make_rate_limit_error():
"""openai.RateLimitError 需要 message + response + body。"""
return RateLimitError(message="rate limited", response=MagicMock(status_code=429), body=None)
def _make_auth_error():
return AuthenticationError(message="bad key", response=MagicMock(status_code=401), body=None)
def test_no_retry_when_success_first_time():
fn = MagicMock(return_value="ok")
sleep = MagicMock()
result = with_retry(fn, sleep_fn=sleep)
assert result == "ok"
assert fn.call_count == 1
assert sleep.call_count == 0
print("✅ test_no_retry_when_success_first_time")
def test_retry_on_connection_error_then_success():
err = _make_connection_error()
fn = MagicMock(side_effect=[err, err, "ok"])
sleep = MagicMock()
result = with_retry(fn, max_attempts=4, sleep_fn=sleep)
assert result == "ok"
assert fn.call_count == 3
assert sleep.call_count == 2
print("✅ test_retry_on_connection_error_then_success")
def test_retry_on_rate_limit():
err = _make_rate_limit_error()
fn = MagicMock(side_effect=[err, "ok"])
sleep = MagicMock()
result = with_retry(fn, sleep_fn=sleep)
assert result == "ok"
assert fn.call_count == 2
print("✅ test_retry_on_rate_limit")
def test_raise_after_max_attempts():
err = _make_connection_error()
fn = MagicMock(side_effect=[err, err, err, err])
sleep = MagicMock()
try:
with_retry(fn, max_attempts=4, sleep_fn=sleep)
except APIConnectionError:
assert fn.call_count == 4
assert sleep.call_count == 3 # 4 次 attempt 之間 sleep 3 次
print("✅ test_raise_after_max_attempts")
return
raise AssertionError("應該 raise APIConnectionError")
def test_no_retry_on_auth_error():
"""AuthenticationError 不是 RETRIABLE、應該第一次就 raise、不 retry。"""
err = _make_auth_error()
fn = MagicMock(side_effect=err)
sleep = MagicMock()
try:
with_retry(fn, sleep_fn=sleep)
except AuthenticationError:
assert fn.call_count == 1, "AuthenticationError 不該被 retry"
assert sleep.call_count == 0
print("✅ test_no_retry_on_auth_error")
return
raise AssertionError("應該 raise AuthenticationError")
def test_exponential_backoff_delays():
"""驗 sleep 的延遲時間隨 attempt 指數增長（base * 2^attempt）。"""
err = _make_connection_error()
fn = MagicMock(side_effect=[err, err, err, "ok"])
delays = []
sleep = MagicMock(side_effect=lambda d: delays.append(d))
result = with_retry(fn, max_attempts=4, base_delay=1.0, sleep_fn=sleep)
assert result == "ok"
# 預期：attempt 0 後 sleep ~1s、attempt 1 後 ~2s、attempt 2 後 ~4s
assert 1.0 <= delays[0] < 1.5
assert 2.0 <= delays[1] < 2.5
assert 4.0 <= delays[2] < 4.5
print("✅ test_exponential_backoff_delays")
if __name__ == "__main__":
test_no_retry_when_success_first_time()
test_retry_on_connection_error_then_success()
test_retry_on_rate_limit()
test_raise_after_max_attempts()
test_no_retry_on_auth_error()
test_exponential_backoff_delays()
print("\n🎉 全部通過 — Ollama path retry wrapper 邏輯正確（RETRIABLE 才 retry、exponential backoff 有效）")
examples/stage-1/05-error-handling/test_anthropic.py
+125
View File
@@ -0,0 +1,125 @@
"""
Stage 1 練習 5 自我驗證 — Path B（Anthropic starter_anthropic.py）。
跑法：
python test_anthropic.py
驗證內容：
- with_retry 對 RETRIABLE 錯誤會 retry
- with_retry 對 non-retriable（譬如 AuthenticationError）直接 raise、不浪費 retry
- 超過 max_attempts 後 raise 最後一個 exception
- sleep 確實被叫（透過 mock sleep_fn）
Ollama 版本見 test.py（用 openai SDK 的 exception class）。
"""
from __future__ import annotations
import sys
from unittest.mock import MagicMock
if hasattr(sys.stdout, "reconfigure"):
sys.stdout.reconfigure(encoding="utf-8", errors="replace")
from anthropic import APIConnectionError, AuthenticationError, RateLimitError
from starter_anthropic import with_retry
def _make_connection_error():
"""anthropic.APIConnectionError 需要 request 參數、用 MagicMock 假裝。"""
return APIConnectionError(request=MagicMock())
def _make_rate_limit_error():
"""anthropic.RateLimitError 需要 response 參數。"""
return RateLimitError(message="rate limited", response=MagicMock(status_code=429), body=None)
def _make_auth_error():
return AuthenticationError(message="bad key", response=MagicMock(status_code=401), body=None)
def test_no_retry_when_success_first_time():
fn = MagicMock(return_value="ok")
sleep = MagicMock()
result = with_retry(fn, sleep_fn=sleep)
assert result == "ok"
assert fn.call_count == 1
assert sleep.call_count == 0
print("✅ test_no_retry_when_success_first_time")
def test_retry_on_connection_error_then_success():
err = _make_connection_error()
fn = MagicMock(side_effect=[err, err, "ok"])
sleep = MagicMock()
result = with_retry(fn, max_attempts=4, sleep_fn=sleep)
assert result == "ok"
assert fn.call_count == 3
assert sleep.call_count == 2
print("✅ test_retry_on_connection_error_then_success")
def test_retry_on_rate_limit():
err = _make_rate_limit_error()
fn = MagicMock(side_effect=[err, "ok"])
sleep = MagicMock()
result = with_retry(fn, sleep_fn=sleep)
assert result == "ok"
assert fn.call_count == 2
print("✅ test_retry_on_rate_limit")
def test_raise_after_max_attempts():
err = _make_connection_error()
fn = MagicMock(side_effect=[err, err, err, err])
sleep = MagicMock()
try:
with_retry(fn, max_attempts=4, sleep_fn=sleep)
except APIConnectionError:
assert fn.call_count == 4
assert sleep.call_count == 3 # 4 次 attempt 之間 sleep 3 次
print("✅ test_raise_after_max_attempts")
return
raise AssertionError("應該 raise APIConnectionError")
def test_no_retry_on_auth_error():
"""AuthenticationError 不是 RETRIABLE、應該第一次就 raise、不 retry。"""
err = _make_auth_error()
fn = MagicMock(side_effect=err)
sleep = MagicMock()
try:
with_retry(fn, sleep_fn=sleep)
except AuthenticationError:
assert fn.call_count == 1, "AuthenticationError 不該被 retry"
assert sleep.call_count == 0
print("✅ test_no_retry_on_auth_error")
return
raise AssertionError("應該 raise AuthenticationError")
def test_exponential_backoff_delays():
"""驗 sleep 的延遲時間隨 attempt 指數增長（base * 2^attempt）。"""
err = _make_connection_error()
fn = MagicMock(side_effect=[err, err, err, "ok"])
delays = []
sleep = MagicMock(side_effect=lambda d: delays.append(d))
result = with_retry(fn, max_attempts=4, base_delay=1.0, sleep_fn=sleep)
assert result == "ok"
# 預期：attempt 0 後 sleep ~1s、attempt 1 後 ~2s、attempt 2 後 ~4s
assert 1.0 <= delays[0] < 1.5
assert 2.0 <= delays[1] < 2.5
assert 4.0 <= delays[2] < 4.5
print("✅ test_exponential_backoff_delays")
if __name__ == "__main__":
test_no_retry_when_success_first_time()
test_retry_on_connection_error_then_success()
test_retry_on_rate_limit()
test_raise_after_max_attempts()
test_no_retry_on_auth_error()
test_exponential_backoff_delays()
print("\n🎉 全部通過 — retry wrapper 邏輯正確（RETRIABLE 才 retry、exponential backoff 有效）")
examples/stage-3/02-multi-tool-selection/README.en.md
+93
View File
@@ -0,0 +1,93 @@
<div align="right">
<a href="./README.md">繁體中文</a> | <a href="./README.zh-Hans.md">简体中文</a> | <strong>English</strong>
</div>
# Exercise 2: Multi-Tool Selection
Corresponds to [Stage 3 — Tool Use & Agent Intro](../../../stages/03-tool-use-and-hello-agent.en.md) Exercise 2.
## Why this matters
This exercise puts an LLM in front of three tools in a single turn: `web_search`, `calculator`, `calendar_lookup`. The point isn't tool quality — it's watching how schema `name` / `description` / `parameters` steer the model's choice. Writing schemas well is one of the highest-leverage things you do in Stage 3.
## How to run — two paths
### Path A (default, free, local)
```bash
pip install -r requirements.txt
ollama pull qwen2.5:3b
ollama serve
python starter.py
```
Budget: **$0**. A single qwen2.5:3b tool call takes ~1-5s (CPU slower, GPU faster).
### Path B (Anthropic, cloud-quality comparison)
```bash
pip install -r requirements.txt
export ANTHROPIC_API_KEY=sk-ant-...
python starter_anthropic.py
```
Budget: ~**$0.0005** per run (claude-haiku-4-5).
Expected output (Path A, local):
```
❓ Question: What is (19 * 42) - 8? Use the best available tool. (using Ollama qwen2.5:3b)
tool: calculator
tool_input: {'expression': '(19 * 42) - 8'}
observation: 790
✅ Exercise 2 passed — you ran multi-tool selection locally on qwen2.5:3b, $0/run
```
## Validate the logic without API credits (mock-based)
```bash
python test.py # validates Path A (Ollama) starter.py logic
python test_anthropic.py # validates Path B (Anthropic) starter_anthropic.py logic
```
Both test suites use `unittest.mock`, no real API call, $0/run. Path A uses the OpenAI-compat response shape; Path B uses Anthropic content blocks.
## SDK differences between the two paths
Three key differences (everything else is identical):
| Part | Anthropic (Path B) | OpenAI-compat / Ollama (Path A) |
|---|---|---|
| Schema wrap | `tools=[{name, description, input_schema}, ...]` | `tools=[{"type": "function", "function": {name, description, parameters}}, ...]` |
| Reading tool call | `resp.content[i].type == "tool_use"` | `resp.choices[0].message.tool_calls[i]` |
| input format | `call.input` is already a dict | `call.function.arguments` is a JSON string — needs `json.loads(...)` |
The selection **logic** is backend-agnostic — write a good schema and qwen2.5:3b picks the right tool too. This exercise is a great place to compare "on which questions does Claude pick the right tool but qwen2.5 doesn't?" — a clean way to feel the boundary of small models.
## Common pitfalls
The most common failure in multi-tool design is descriptions that read like documentation, not decision rules:
- `calendar_lookup` described as "calendar" is ambiguous with `web_search`; "look up events for a specific date" is clearer
- `web_search` is for "external / recent / uncertain info", `calculator` for arithmetic — the clearer the boundary, the fewer wrong picks
- Small models (qwen2.5:3b) are **more sensitive** to description quality than Claude — the same schema where Claude might guess correctly can lead qwen astray
## Want smarter answers?
Default is `claude-haiku-4-5` (cheapest). Try Sonnet:
```bash
MODEL=claude-sonnet-5 python starter_anthropic.py
```
Or on the Ollama path, swap to `qwen2.5:7b` (bigger, more stable, but slower):
```bash
MODEL=qwen2.5:7b python starter.py
```
## Extensions
- **Add more tools** — append one entry each to `TOOLS_SPEC` + `TOOL_IMPL`
- **Make it multi-turn ReAct** — wrap the single call in a `while` loop; see [`../03-react-from-scratch/`](../03-react-from-scratch/)
- **Dig into schema design** — see [`../06-schema-design/`](../06-schema-design/) for a bad vs good schema A/B
examples/stage-3/02-multi-tool-selection/README.md
+100
View File
@@ -0,0 +1,100 @@
<div align="right">
<strong>繁體中文</strong> | <a href="./README.zh-Hans.md">简体中文</a> | <a href="./README.en.md">English</a>
</div>
# 練習 2：多工具選擇
對應 [Stage 3 — Tool Use & Agent 入門](../../../stages/03-tool-use-and-hello-agent.md) 練習 2。
> 🎓 **學習模式**：這份 `starter.py` 是**完整解答**、不是 TODO skeleton。建議用**主動模式**——`mv starter.py starter_reference.py`、看 signature 不看 body、自己重寫一份 `starter.py`、跑 `python test.py` 驗證；卡 20 分鐘再回去對照 reference。完整方法論看 [`docs/HOW_TO_USE.md`](../../../docs/HOW_TO_USE.md)。
> 📚 **想要 chapter-length 深入版？** 本 folder 的 starter 是 70-150 行 illustrative 版、聚焦 `核心 pattern + 兩條 SDK path`，不是進階深度教材。深度教材推薦：
> - [`datawhalechina/hello-agents`](https://github.com/datawhalechina/hello-agents) ⭐ 中文圈最完整、章節式 + 16 種 production 能力。**本練習對應 hello-agents 的 tool-calling / multi-tool dispatch 章節**
> - [Anthropic Tool Use Cookbook](https://github.com/anthropics/claude-cookbooks/tree/main/tool_use)（單工具→多工具→parallel 完整 notebook）
> - 完整 references 見 [Stage 3 精選 Projects](../../../stages/03-tool-use-and-hello-agent.md#-精選-projects)
## 為什麼這題重要
這個練習讓 LLM 在同一輪面對三個工具：`web_search`、`calculator`、`calendar_lookup`。重點不是工具本身強不強，而是觀察 schema 的 `name` / `description` / `parameters` 如何決定模型挑哪一個。寫清楚 schema、是 Stage 3 最值得花時間的子題。
## 怎麼跑 — 兩條路徑
### Path A（默認、本機免費）
```bash
pip install -r requirements.txt
ollama pull qwen2.5:3b
ollama serve
python starter.py
```
預算：**$0**。qwen2.5:3b 單輪 tool call ≈ 1-5 秒（CPU 慢、GPU 快）。
### Path B（Anthropic、想看 cloud 高品質）
```bash
pip install -r requirements.txt
export ANTHROPIC_API_KEY=sk-ant-...
python starter_anthropic.py
```
預算：每次 ≈ **$0.0005**（claude-haiku-4-5）。
預期看到（Path A、本機）：
```
❓ 問題：What is (19 * 42) - 8? Use the best available tool.（using Ollama qwen2.5:3b）
tool: calculator
tool_input: {'expression': '(19 * 42) - 8'}
observation: 790
✅ 練習 2 通過 — 你已用本機 qwen2.5:3b 跑通 multi-tool selection、$0/run
```
## 不花錢驗證程式邏輯（mock-based）
```bash
python test.py # 驗 Path A (Ollama) starter.py 邏輯
python test_anthropic.py # 驗 Path B (Anthropic) starter_anthropic.py 邏輯
```
兩條 test 都用 `unittest.mock`、不打真 API、$0/run。Path A 用 OpenAI-compat response shape、Path B 用 Anthropic content blocks。
## 兩條 path 的 SDK 差異
三個關鍵差異（其他完全一樣）：
| 部分 | Anthropic（Path B） | OpenAI-compat / Ollama（Path A） |
|---|---|---|
| Schema 包法 | `tools=[{name, description, input_schema}, ...]` | `tools=[{"type": "function", "function": {name, description, parameters}}, ...]` |
| 抓 tool call | `resp.content[i].type == "tool_use"` | `resp.choices[0].message.tool_calls[i]` |
| input 格式 | `call.input` 是 dict（自動 parse） | `call.function.arguments` 是 JSON string、要 `json.loads(...)` |
Tool selection **邏輯本身**跨 backend——schema 寫好、qwen2.5:3b 也會挑對 tool。這題很適合拿來對照 Claude vs qwen2.5「在哪幾題會挑錯」，是觀察小 model 邊界的好實驗。
## 容易踩坑
多工具選擇最常見的錯誤是 description 寫得太像「一般說明文件」，而不是「給模型做決策的判斷規則」：
- `calendar_lookup` 描述只說「行事曆」就會跟 `web_search` 邊界模糊；明寫「查特定日期事件」才好
- `web_search` 適合「外部 / 近期 / 不確定資訊」、`calculator` 只處理算式；邊界寫越清楚、模型越少誤判
- 小 model（qwen2.5:3b）對 description 質量比 Claude **更敏感**——同一份 schema、Claude 可能還能猜對、qwen 直接挑錯
## 想看更聰明的答案？
預設用 `claude-haiku-4-5`（最便宜）。改成 sonnet：
```bash
MODEL=claude-sonnet-5 python starter_anthropic.py
```
或在 Ollama path 換 `qwen2.5:7b`（更大、更穩、但慢）：
```bash
MODEL=qwen2.5:7b python starter.py
```
## 延伸
- **加更多 tool**：在 `TOOLS_SPEC` + `TOOL_IMPL` 補一個 entry 即可
- **改成多輪 ReAct**：把單輪 call 包進 while loop，看 [`../03-react-from-scratch/`](../03-react-from-scratch/)
- **schema 細節**：看 [`../06-schema-design/`](../06-schema-design/) 比較 bad / good schema 對選擇正確率的影響
examples/stage-3/02-multi-tool-selection/README.zh-Hans.md
+93
View File
@@ -0,0 +1,93 @@
<div align="right">
<a href="./README.md">繁體中文</a> | <strong>简体中文</strong> | <a href="./README.en.md">English</a>
</div>
# 练习 2：多工具选择
对应 [Stage 3 — Tool Use & Agent 入门](../../../stages/03-tool-use-and-hello-agent.zh-Hans.md) 练习 2。
## 为什么这题重要
这个练习让 LLM 在同一轮面对三个工具：`web_search`、`calculator`、`calendar_lookup`。重点不是工具本身强不强，而是观察 schema 的 `name` / `description` / `parameters` 如何决定模型挑哪一个。把 schema 写清楚，是 Stage 3 最值得花时间的子题。
## 怎么跑 — 两条路径
### Path A（默认、本机免费）
```bash
pip install -r requirements.txt
ollama pull qwen2.5:3b
ollama serve
python starter.py
```
预算：**$0**。qwen2.5:3b 单轮 tool call ≈ 1-5 秒（CPU 慢、GPU 快）。
### Path B（Anthropic、想看 cloud 高质量）
```bash
pip install -r requirements.txt
export ANTHROPIC_API_KEY=sk-ant-...
python starter_anthropic.py
```
预算：每次 ≈ **$0.0005**（claude-haiku-4-5）。
预期看到（Path A、本机）：
```
❓ 问题：What is (19 * 42) - 8? Use the best available tool.（using Ollama qwen2.5:3b）
tool: calculator
tool_input: {'expression': '(19 * 42) - 8'}
observation: 790
✅ 练习 2 通过 — 你已用本机 qwen2.5:3b 跑通 multi-tool selection、$0/run
```
## 不花钱验证程序逻辑（mock-based）
```bash
python test.py # 验 Path A (Ollama) starter.py 逻辑
python test_anthropic.py # 验 Path B (Anthropic) starter_anthropic.py 逻辑
```
两条 test 都用 `unittest.mock`、不打真 API、$0/run。Path A 用 OpenAI-compat response shape、Path B 用 Anthropic content blocks。
## 两条 path 的 SDK 差异
三个关键差异（其他完全一样）：
| 部分 | Anthropic（Path B） | OpenAI-compat / Ollama（Path A） |
|---|---|---|
| Schema 包法 | `tools=[{name, description, input_schema}, ...]` | `tools=[{"type": "function", "function": {name, description, parameters}}, ...]` |
| 抓 tool call | `resp.content[i].type == "tool_use"` | `resp.choices[0].message.tool_calls[i]` |
| input 格式 | `call.input` 是 dict（自动 parse） | `call.function.arguments` 是 JSON string、要 `json.loads(...)` |
Tool selection **逻辑本身**跨 backend——schema 写好、qwen2.5:3b 也会挑对 tool。这题很适合拿来对照 Claude vs qwen2.5“在哪几题会挑错”，是观察小 model 边界的好实验。
## 容易踩坑
多工具选择最常见的错误是 description 写得太像“一般说明文档”，而不是“给模型做决策的判断规则”：
- `calendar_lookup` 描述只说“行事历”就会跟 `web_search` 边界模糊；明写“查特定日期事件”才好
- `web_search` 适合“外部 / 近期 / 不确定信息”、`calculator` 只处理算式；边界写越清楚、模型越少误判
- 小 model（qwen2.5:3b）对 description 质量比 Claude **更敏感**——同一份 schema、Claude 可能还能猜对、qwen 直接挑错
## 想看更聪明的答案？
预设用 `claude-haiku-4-5`（最便宜）。改成 sonnet：
```bash
MODEL=claude-sonnet-5 python starter_anthropic.py
```
或在 Ollama path 换 `qwen2.5:7b`（更大、更稳、但慢）：
```bash
MODEL=qwen2.5:7b python starter.py
```
## 延伸
- **加更多 tool**：在 `TOOLS_SPEC` + `TOOL_IMPL` 补一个 entry 即可
- **改成多轮 ReAct**：把单轮 call 包进 while loop，看 [`../03-react-from-scratch/`](../03-react-from-scratch/)
- **schema 细节**：看 [`../06-schema-design/`](../06-schema-design/) 比较 bad / good schema 对选择正确率的影响
examples/stage-3/02-multi-tool-selection/requirements.txt
+2
View File
@@ -0,0 +1,2 @@
openai>=1.50,<2.0
anthropic>=0.40,<1.0 # 只 starter_anthropic.py 需要、Ollama path 不用
examples/stage-3/02-multi-tool-selection/starter.py
+120
View File
@@ -0,0 +1,120 @@
"""練習 2：多工具選擇 — Path A（Ollama 默認、本機免費）。
讓本機 qwen2.5:3b 在 3 個 tool（web_search / calculator / calendar_lookup）裡選一個。
重點不是工具強不強，是觀察 schema 的 description / 參數 / required 如何引導模型選對。
跑法：
pip install -r requirements.txt
ollama pull qwen2.5:3b # Stage 3+ tool-use 默認 model
ollama serve # 預設 port 11434
python starter.py
驗證：
python test.py （用 mock、不打 API）
想看 Anthropic Claude 版本：
python starter_anthropic.py （需 ANTHROPIC_API_KEY、$0.0005/run）
"""
from __future__ import annotations
import json
import os
import sys
from typing import Any
if hasattr(sys.stdout, "reconfigure"):
sys.stdout.reconfigure(encoding="utf-8", errors="replace")
from openai import OpenAI
MODEL = os.environ.get("MODEL", "qwen2.5:3b") # tool-use 穩定的 Ollama model
# === 1. Tools 定義（含實作）===
def web_search(query: str) -> str:
return f"search result: {query} -> Anthropic tool use docs and examples"
def calculator(expression: str) -> str:
allowed = set("0123456789.+-*/() ")
if any(ch not in allowed for ch in expression):
return "error: calculator only accepts basic arithmetic"
try:
return str(eval(expression, {"__builtins__": {}}, {})) # noqa: S307
except Exception as exc: # noqa: BLE001
return f"error: {exc}"
def calendar_lookup(date: str) -> str:
events = {
"2026-05-13": "10:00 Stage 3 review, 15:00 agent study group",
"tomorrow": "10:00 Stage 3 review, 15:00 agent study group",
}
return events.get(date.strip(), f"no events found for {date}")
# OpenAI-compat 的 tools schema 要包一層 {"type": "function", "function": {...}}
def _wrap(name: str, description: str, field: str, field_description: str) -> dict:
return {
"type": "function",
"function": {
"name": name,
"description": description,
"parameters": {
"type": "object",
"properties": {field: {"type": "string", "description": field_description}},
"required": [field],
},
},
}
TOOLS_SPEC = [
_wrap("web_search", "Search current or external information not in the prompt.", "query", "Search query"),
_wrap("calculator", "Evaluate basic arithmetic with +, -, *, /, and parentheses.", "expression", "Math expression"),
_wrap("calendar_lookup", "Look up events for a specific date or relative day.", "date", "Date to inspect"),
]
TOOL_IMPL = {
"web_search": lambda args: web_search(args["query"]),
"calculator": lambda args: calculator(args["expression"]),
"calendar_lookup": lambda args: calendar_lookup(args["date"]),
}
# === 2. 單輪 tool selection ===
def run_tool_selection(question: str, client: Any = None) -> dict:
"""單輪 call：LLM 看完 question + tools 後選一個 tool 呼叫，本地執行 observation 接回去。"""
client = client or OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
resp = client.chat.completions.create(
model=MODEL,
tools=TOOLS_SPEC,
messages=[{"role": "user", "content": question}],
)
msg = resp.choices[0].message
text = msg.content or ""
tool_calls = msg.tool_calls or []
if not tool_calls:
return {"tool": None, "thought": text, "observation": None}
call = tool_calls[0]
args = json.loads(call.function.arguments)
fn = TOOL_IMPL.get(call.function.name, lambda _: f"error: unknown tool {call.function.name}")
return {"tool": call.function.name, "tool_input": args, "thought": text, "observation": fn(args)}
# === 3. 自我驗證 ===
if __name__ == "__main__":
question = "What is (19 * 42) - 8? Use the best available tool."
print(f"❓ 問題：{question}（using Ollama {MODEL}）")
result = run_tool_selection(question)
print(f" tool: {result['tool']}")
print(f" tool_input: {result.get('tool_input')}")
print(f" observation: {result['observation']}")
assert result["tool"] == "calculator", f"預期 calculator、得到 {result['tool']}"
assert result["observation"] and not result["observation"].startswith("error:")
print("✅ 練習 2 通過 — 你已用本機 qwen2.5:3b 跑通 multi-tool selection、$0/run")

Some files were not shown because too many files have changed in this diff Show More