resources/ 索引¶
本 repo 的「reference 區」——非主路線、需要時來查的補充材料。每份檔案有明確角色，不重複。
7 份 reference + 各自的「什麼時候看」¶
| 檔案 | 角色 | 什麼時候看 | 行數 |
|---|---|---|---|
glossary.md |
30 秒查詞典 | 看 stage 內文時遇到 LLM / RAG / token / agent / vector DB / streaming / batch API 不知道什麼意思 | ~210 |
cli-agents-guide.md |
7 個 CLI agent 比較 | 第一次選 CLI agent（Claude Code / Codex / OpenCode / Gemini CLI / goose / Aider / Hermes Agent）不知道挑哪個 | ~134 |
mcp-skills-catalog.md |
62 個整合 catalog | 想把 Claude Code 接 Notion / Obsidian / Excel / Postgres / Slack / 等等實際工具 | ~775 |
schema-design-cheatsheet.md |
function schema 設計 5 規則 + 5 anti-pattern | 寫 tool schema / MCP server schema / function calling，發現 LLM 選錯 tool / 傳錯參數 | ~159 |
cookbook.md |
6 個 step-by-step recipe | 想 30-50 分鐘做出第一個 Skill / MCP server / 接 Office / 接 NotebookLM / 接 Zotero / 接本機 LLM | ~620 |
setup-guide.md |
從零開始的 setup 指南 | 完全沒 dev 背景、第一次申請 API key / 裝 Python / 用 Claude Code | ~400 |
style-guide.md |
送 PR 前的格式 / 用詞規範 | 要對 repo 貢獻、寫 entry / 翻譯 | ~338 |
合計 ~2500 行 reference。看起來不少，但每份檔案讀的時機不同——你不會一次全讀，只在對應情境查 30 秒到 45 分鐘。
怎麼進來：以「我現在要做什麼」分類¶
🆕 我完全沒寫過 code / 第一次接觸 AI agent¶
→ setup-guide.md（30-45 分鐘從零裝好）
🆕 我剛開始學 AI agent¶
不需要先讀任何 reference。直接從主路線 README → Stage 0 開始。遇到不懂的詞回來查 glossary.md 就好。
🛠 我要選 CLI agent¶
→ cli-agents-guide.md（6 個 CLI 比較 + 依 use case 推薦）
🔌 我要把 Claude Code 接 X 工具（Notion / Excel / Postgres 等）¶
→ mcp-skills-catalog.md（62 個整合分 14 類）
🍳 我想動手寫第一個 Skill / MCP server / 接 Word 等¶
→ cookbook.md（6 個 step-by-step recipe）
📐 我寫 tool schema 但 LLM 不照我意思做¶
→ schema-design-cheatsheet.md（5 規則 + 5 anti-pattern）
📚 我看 stage 內文遇到不懂的詞¶
→ glossary.md（每詞 30-80 字解釋 + 哪 stage 講細）
🤝 我想送 PR / 翻譯 / 加新 entry¶
→ style-guide.md + ../CONTRIBUTING.md
重複 / 重疊？¶
刻意避免重複。每份 reference 跟主路線 / 其他 reference 的關係：
- glossary 是「30 秒查」、stage 內文是「3-5 分鐘讀」、cookbook 是「30-50 分鐘做」——三層深度，不重疊
- schema-design-cheatsheet 跟 cookbook 2（寫 MCP server）有交集——cheatsheet 講「寫 schema 的規則」、cookbook 講「怎麼把 server 跑起來」。看哪個取決於你卡在哪
- cli-agents-guide 是 reference table；catalog 是 plug-in tools——兩個層級不同
- 跟 Hello-Agents 的關係：Hello-Agents 是中文圈最完整的 agent 教材，深度高。我們是「roadmap + curated catalog + 動手 recipe」的角度，不取代它。Stage 5.3 / cookbook 1 都明確 cross-ref Hello-Agents Extra08「如何寫出好的 Skill」當深度補充
三語覆蓋¶
| 檔案 | zh-TW（canonical） | zh-Hans | English |
|---|---|---|---|
| glossary | ✅ | ✅ | ✅ |
| cli-agents-guide | ✅ | ✅ | ✅ |
| mcp-skills-catalog | ✅ | ✅ | ✅ |
| schema-design-cheatsheet | ✅ | ✅ | ✅ |
| cookbook | ✅ | ✅ | ✅ |
| setup-guide | ✅ | ✅ | ✅ |
| style-guide | ✅ | ✅ | ✅ |
加新 reference 檔的標準¶
不是隨便加。新檔案必須：
- 不重複既有任何檔的角色（看上面的「角色」欄）
- 解決 main path 解決不了的問題——如果 Stage X 的內文加 50 行就能 cover，就放 stage 裡別開新檔
- 預期會被 ≥ 3 個 stage 或 branch cross-ref——只服務一個 stage 的內容，放那個 stage 就好
近期考慮過、但沒加的（可選 future work）：
- cost-calculator-guide.md（cross-provider 計價）—— 現在 Stage 1 有提到，等需求明顯再開
- troubleshooting-guide.md（常見錯誤 runbook）—— 現有資料夠應付，等社群回報多了再開
- prompt-patterns-guide.md（CoT / few-shot 範本庫）—— 現在 Stage 2 有，深度版等社群 PR
社群想加可以開 issue 討論。