learn-claude-code：用 20 課拆解智慧體外殼
動手實作的教學，圍繞 Bash 從零打造一個極簡的 Claude Code 式代理外殼，講解模型與外殼如何組合成可用的代理產品。
秒懂
- 它是什麼？
- shareAI Lab 的教學從 agent_loop 出發，逐步加入工具、權限、記憶、鉤子、MCP、排程與工作區隔離。
- 適合誰用？
- 適合想逐章理解模型如何透過工具在環境中行動的開發者，不適合把教學程式當成完整的生產執行時期。先設定 ANTHROPIC_API_KEY，依序執行 python s01_agent_loop/code.py、python s08_context_compact/code.py 與 python s20_comprehensive/code.py，觀察 agent_loop、tool_result、上下文壓縮與錯誤處理的差異，再決定哪些機制值得移植。
- 可以商用嗎？
- 可以。MIT 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 20 天前。
- 用什麼語言寫的？
- 主要是 Python（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。
開源專案深度解析
能动性来自模型，而不是来自胶水代码 · shareai-lab-learn-claude-code-deep-analysis
README 的开篇提出一个核心区分：智慧體的能动性，也就是感知、推理和行动的能力，来自模型训练，而不是来自外部编排程式碼。它举了 DeepMind DQN、OpenAI Five、AlphaStar、腾讯绝悟和当前的大语言模型编程智慧體作为例子，说明训练好的模型需要被放进一个环境里。这个仓库的任务不是训练模型，而是建構外壳，也就是给模型提供工具、知识、观察、行动接口和权限的程式碼。README 还明确说，拖拽式工作流建構器和提示链库只是把 LLM 塞进过程化规则管道的产物，不是智慧體。这个观点是整个教程的前提。
這個區分會影響閱讀方法：不要先把 TOOL_HANDLERS 或提示字串當成智慧來源，而要看模型收到哪些觀察、能呼叫哪些 action，以及外殼如何限制權限。README 把檔案 I/O、shell、網路、資料庫與瀏覽器列為工具例子，這些工具讓同一個模型面對不同環境；它們本身不會把固定規則管道變成自主推理系統。
20 課的價值在於逐次改動可以對照。s01_agent_loop 先展示最小循環，後續資料夾把工具、上下文、權限和其他控制面逐項放回來。每次閱讀都應記下新增的檔案、訊息區塊與 stop_reason，因為 README 的主張是循環保持不變，而能力來自循環周邊的介面。
本課的專屬觀察點是第1節：把 README 指出的檔案、函式或命令與模型回應分開記錄，才能看出外殼改動造成的實際差異。
两条教程轨道：20 课的新版和 12 课的旧版 · shareai-lab-learn-claude-code-deep-analysis
项目包含两条教程轨道。当前规范轨道是根目录下的 s01_agent_loop 到 s20_comprehensive 文件夹，每一章添加一个外壳机制，并配有一句口号。旧轨道是保留在 docs/、agents/ 和当前 web 应用中的 12 课版本，供已有读者和旧链接使用。README 提醒，旧版和当前版本的章节编号并不总是对应，不要混用。没有旧版对应的新章节包括权限、钩子、记忆、系统提示、错误恢复、定时任务、MCP 和综合智慧體。每个当前章节文件夹都包含中文 README.md、英文和日文翻译、可執行的 code.py，以及需要的 SVG 图。
README 的外殼公式也提供一個實用檢查表：Tools 決定可做的動作，Knowledge 決定可引用的領域資料，Observation 決定模型看見的狀態，Action Interfaces 決定請求如何落地，Permissions 則決定哪些動作需要隔離或批准。這五項若有一項沒有明確邊界，教學示例與實際產品之間就會出現落差。
本課的專屬觀察點是第2節：把 README 指出的檔案、函式或命令與模型回應分開記錄，才能看出外殼改動造成的實際差異。
那个永远不变的循环 · shareai-lab-learn-claude-code-deep-analysis
核心程式碼示例是一个名为 agent_loop 的函数。它把消息列表发送给模型 API，把助手响应追加进去，然后检查 stop_reason 是否等于 tool_use。如果是，循环通过 TOOL_HANDLERS 映射执行每个请求的工具，并追加 tool_result 块；否则返回。README 说每一课都在这个循环上叠加一个机制，循环本身从不改变。循环属于智慧體，工具、知识和权限属于外壳。快速开始一节要求配置 ANTHROPIC_API_KEY，因此示例假设使用与 Anthropic 兼容的 API，但 README 没有说明支持哪些具体模型。
快速開始的命令沒有承諾固定輸出，因此測試重點應放在流程是否走到下一個 tool_use、工具結果是否回到訊息列表，以及 s20_comprehensive 是否能完成其示例路徑。README 明確說 JSONL mailbox 是教學實作，也沒有聲稱涵蓋完整事件匯流排、OAuth 或 MCP 資源訂閱。這些缺口不能由課程名稱推導。
本課的專屬觀察點是第3節：把 README 指出的檔案、函式或命令與模型回應分開記錄，才能看出外殼改動造成的實際差異。
明确省略的生产机制 · shareai-lab-learn-claude-code-deep-analysis
scope 一节明确列出了被简化或省略的内容。完整的事件和钩子总线行为，例如 PreToolUse、SessionStart、SessionEnd 和 ConfigChange，没有完整覆盖。基于规则的权限治理、完整的信任工作流、resume/fork 等会话生命周期控制、更完整的工作树生命周期处理，以及 MCP 的传输、OAuth、资源订阅和轮询等完整執行时细节，也被简化或省略。仓库里的 JSONL 邮箱协议被描述为教学实现，不是对任何生产内部实现的声明。换句话说，这些程式碼是为了演示机制，不是作为生产级智慧體執行时。
MIT 條款允許在本專案中使用、複製、修改、合併、發布、散佈、再授權與銷售，但分發時仍須保留著作權與許可聲明，且條款以現況提供、不作擔保。它解決的是程式碼分發權，不是 API 金鑰管理、shell 沙盒或代理權限的安全責任。
本課的專屬觀察點是第4節：把 README 指出的檔案、函式或命令與模型回應分開記錄，才能看出外殼改動造成的實際差異。
快速开始里写了什么 · shareai-lab-learn-claude-code-deep-analysis
快速开始一节给出了具体命令。克隆仓库并用 pip install -r requirements.txt 安装依赖后，需要把 .env.example 复制为 .env 并设置 ANTHROPIC_API_KEY。示例从 python s01_agent_loop/code.py 开始，经过 python s08_context_compact/code.py，最后是 python s20_comprehensive/code.py。旧轨道有自己的命令，例如 python agents/s01_agent_loop.py。web/ 目录下的网页平台当前渲染的是旧版 docs 轨道，可以用 npm install 和 npm run dev 启动。README 没有详细描述这些命令的预期输出。
本課的專屬觀察點是第5節：把 README 指出的檔案、函式或命令與模型回應分開記錄，才能看出外殼改動造成的實際差異。
课程之外：Kode、claw0 和许可证 · shareai-lab-learn-claude-code-deep-analysis
20 课之后，README 指向两个兄弟项目：Kode Agent CLI，通过 npm 全局安装；Kode Agent SDK，一个可嵌入应用的库。它还链接了一个姊妹教程 claw0，讲解带心跳、定时任务、IM 频道、记忆和 Soul 人格的常驻助手。除了安装命令和 GitHub 链接，README 没有提供这些项目的更多用法。仓库使用 MIT 授權，版权归 shareAI Lab 所有。授權允许使用、复制、修改、合并、发布、分发、再许可和销售，并声明不提供担保。授權文本没有提及安全保证、支持或生产就绪性。
本課的專屬觀察點是第6節：把 README 指出的檔案、函式或命令與模型回應分開記錄，才能看出外殼改動造成的實際差異。
編輯結論
適合想逐章理解模型如何透過工具在環境中行動的開發者，不適合把教學程式當成完整的生產執行時期。先設定 ANTHROPIC_API_KEY，依序執行 python s01_agent_loop/code.py、python s08_context_compact/code.py 與 python s20_comprehensive/code.py，觀察 agent_loop、tool_result、上下文壓縮與錯誤處理的差異，再決定哪些機制值得移植。
社群筆記