{"repo": "993791208/learn-claude-code", "files": {"README-zh.md": {"a3d53a6d2630df1b3da2c744c8f0fcc721334fa5": {"t": 1785747241.2182364, "n": 13377, "h": "c51161c4de6e14f1", "c": "# Learn Claude Code -- 真正的 Agent Harness 工程\n\n[English](./README.md) | [中文](./README-zh.md) | [日本語](./README-ja.md)\n\n## 模型就是 Agent\n\n在讨论代码之前，先把一件事彻底说清楚。\n\n**Agent 是模型。不是框架。不是提示词链。不是拖拽式工作流。**\n\n### Agent 到底是什么\n\nAgent 是一个神经网络 -- Transformer、RNN、一个被训练出来的函数 -- 经过数十亿次梯度更新，在行动序列数据上学会了感知环境、推理目标、采取行动。\"Agent\" 这个词在 AI 领域从诞生之日起就是这个意思。从来都是。\n\n人类就是 agent。一个由数百万年进化训练出来的生物神经网络，通过感官感知世界，通过大脑推理，通过身体行动。当 DeepMind、OpenAI 或 Anthropic 说 \"agent\" 时，他们说的和这个领域自诞生以来就一直在说的完全一样：**一个学会了行动的模型。**\n\n历史已经写好了铁证：\n\n- **2013 -- DeepMind DQN 玩 Atari。** 一个神经网络，只接收原始像素和游戏分数，学会了 7 款 Atari 2600 游戏 -- 超越所有先前算法，在其中 3 款上击败人类专家。到 2015 年，同一架构扩展到 [49 款游戏，达到职业人类测试员水平](https://www.nature.com/articles/nature14236)，论文发表在 *Nature*。没有游戏专属规则。没有决策树。一个模型，从经验中学习。那个模型就是 agent。\n\n- **2019 -- OpenAI Five 征服 Dota 2。** 五个神经网络，在 10 个月内与自己对战了 [45,000 年的 Dota 2](https://openai.com/index/openai-five-defeats-dota-2-world-champions/)，在旧金山直播赛上 2-0 击败了 **OG** -- TI8 世界冠军。随后的公开竞技场中，AI 在 42,729 场比赛中胜率 99.4%。没有脚本化的策略。没有元编程的团队协调逻辑。模型完全通过自我对弈学会了团队协作、战术和实时适应。\n\n- **2019 -- DeepMind AlphaStar 制霸星际争霸 II。** AlphaStar 在闭门赛中 [10-1 击败职业选手](https://deepmind.google/blog/alphastar-mastering-the-real-time-strategy-game-starcraft-ii/)，随后在欧洲服务器上达到[宗师段位](https://www.nature.com/articles/d41586-019-03298-6) -- 90,000 名玩家中的前 0.15%。一个信息不完全、实时决策、组合动作空间远超国际象棋和围棋的游戏。Agent 是什么？是模型。训练出来的。不是编出来的。\n\n- **2019 -- 腾讯绝悟统治王者荣耀。** 腾讯 AI Lab 的 \"绝悟\" 于 2019 年 8 月 2 日世冠杯半决赛上[以 5v5 击败 KPL 职业选手](https://www.jiemian.com/article/3371171.html)。在 1v1 模式下，职业选手 [15 场只赢 1 场，最多坚持不到 8 分钟](https://developer.aliyun.com/article/851058)。训练强度：一天等于人类 440 年。到 2021 年，绝悟在全英雄池 BO5 上全面超越 KPL 职业选手水准。没有手工编写的英雄克制表。没有脚本化的阵容编排。一个从零开始通过自我对弈学习整个游戏的模型。\n\n- **2024-2025 -- LLM Agent 重塑软件工程。** Claude、GPT、Gemini -- 在人类全部代码和推理上训练的大语言模型 -- 被部署为编程 agent。它们阅读代码库，编写实现，调试故障，团队协作。架构与之前每一个 agent 完全相同：一个训练好的模型，放入一个环境，给予感知和行动的工具。唯一的不同是它们学到的东西的规模和解决任务的通用性。\n\n每一个里程碑都共享同一个真理：**\"Agent\" 从来都不是外面那层代码。Agent 永远是模型本身。**\n\n### Agent 不是什么\n\n\"Agent\" 这个词已经被一整个提示词水管工产业劫持了。\n\n拖拽式工作流构建器。无代码 \"AI Agent\" 平台。提示词链编排库。它们共享同一个幻觉：把 LLM API 调用用 if-else 分支、节点图、硬编码路由逻辑串在一起就算是 \"构建 Agent\" 了。\n\n不是的。它们做出来的东西是鲁布·戈德堡机械 -- 一个过度工程化的、脆弱的过程式规则流水线，LLM 被楔在里面当一个美化了的文本补全节点。那不是 Agent。那是一个有着宏大妄想的 shell 脚本。\n\n**提示词水管工式 \"Agent\" 是不做模型的程序员的意淫。** 他们试图通过堆叠过程式逻辑来暴力模拟智能 -- 庞大的规则树、节点图、链式提示词瀑布流 -- 然后祈祷足够多的胶水代码能涌现出自主行为。不会的。你不可能通过工程手段编码出 agency。Agency 是学出来的，不是编出来的。\n\n那些系统从诞生之日起就已经死了：脆弱、不可扩展、根本不具备泛化能力。它们是 GOFAI（Good Old-Fashioned AI，经典符号 AI）的现代还魂 -- 几十年前就被学界抛弃的符号规则系统，现在喷了一层 LLM 的漆又登场了。换了个包装，同一条死路。\n\n### 心智转换：从 \"开发 Agent\" 到开发 Harness\n\n当一个人说 \"我在开发 Agent\" 时，他只可能是两个意思之一：\n\n**1. 训练模型。** 通过强化学习、微调、RLHF 或其他基于梯度的方法调整权重。收集任务过程数据 -- 真实领域中感知、推理、行动的实际序列 -- 用它们来塑造模型的行为。这是 DeepMind、OpenAI、腾讯 AI Lab、Anthropic 在做的事。这是最本义的 Agent 开发。\n\n**2. 构建 Harness。** 编写代码，为模型提供一个可操作的环境。这是我们大多数人在做的事，也是本仓库的核心。\n\nHarness 是 agent 在特定领域工作所需要的一切：\n\n```\nHarness = Tools + Knowledge + Observation + Action Interfaces + Permissions\n\n    Tools:          文件读写、Shell、网络、数据库、浏览器\n    Knowledge:      产品文档、领域资料、API 规范、风格指南\n    Observation:    git diff、错误日志、浏览器状态、传感器数据\n    Action:         CLI 命令、API 调用、UI 交互\n    Permissions:    沙箱隔离、审批流程、信任边界\n```\n\n模型做决策。Harness 执行。模型做推理。Harness 提供上下文。模型是驾驶者。Harness 是载具。\n\n**编程 agent 的 harness 是它的 IDE、终端和文件系统。** 农业 agent 的 harness 是传感器阵列、灌溉控制和气象数据。酒店 agent 的 harness 是预订系统、客户沟通渠道和设施管理 API。Agent -- 那个智能、那个决策者 -- 永远是模型。Harness 因领域而变。Agent 跨领域泛化。\n\n这个仓库教你造载具。编程用的载具。但设计模式可以泛化到任何领域：庄园管理、农田运营、酒店运作、工厂制造、物流调度、医疗保健、教育培训、科学研究。只要有一个任务需要被感知、推理和执行 -- agent 就需要一个 harness。\n\n### Harness 工程师到底在做什么\n\n如果你在读这个仓库，你很可能是一名 harness 工程师 -- 这是一个强大的身份。以下是你真正的工作：\n\n- **实现工具。** 给 agent 一双手。文件读写、Shell 执行、API 调用、浏览器控制、数据库查询。每个工具都是 agent 在环境中可以采取的一个行动。设计它们时要原子化、可组合、描述清晰。\n\n- **策划知识。** 给 agent 领域专长。产品文档、架构决策记录、风格指南、合规要求。按需加载（s05），不要前置塞入。Agent 应该知道有什么可用，然后自己拉取所需。\n\n- **管理上下文。** 给 agent 干净的记忆。子 agent 隔离（s04）防止噪声泄露。上下文压缩（s06）防止历史淹没。任务系统（s07）让目标持久化到单次对话之外。\n\n- **控制权限。** 给 agent 边界。沙箱化文件访问。对破坏性操作要求审批。在 agent 和外部系统之间实施信任边界。这是安全工程与 harness 工程的交汇点。\n\n- **收集任务过程数据。** Agent 在你的 harness 中执行的每一条行动序列都是训练信号。真实部署中的感知-推理-行动轨迹是微调下一代 agent 模型的原材料。你的 harness 不仅服务于 agent -- 它还可以帮助进化 agent。\n\n你不是在编写智能。你是在构建智能栖居的世界。这个世界的质量 -- agent 能看得多清楚、行动得多精准、可用知识有多丰富 -- 直接决定了智能能多有效地表达自己。\n\n**造好 Harness。Agent 会完成剩下的。**\n\n### 为什么是 Claude Code -- Harness 工程的大师课\n\n为什么这个仓库专门拆解 Claude Code？\n\n因为 Claude Code 是我们所见过的最优雅、最完整的 agent harness 实现。不是因为某个巧妙的技巧，而是因为它 *没做* 的事：它没有试图成为 agent 本身。它没有强加僵化的工作流。它没有用精心设计的决策树去替模型做判断。它给模型提供了工具、知识、上下文管理和权限边界 -- 然后让开了。\n\n把 Claude Code 剥到本质来看：\n\n```\nClaude Code = 一个 agent loop\n            + 工具 (bash, read, write, edit, glob, grep, browser...)\n            + 按需 skill 加载\n            + 上下文压缩\n            + 子 agent 派生\n            + 带依赖图的任务系统\n            + 异步邮箱的团队协调\n            + worktree 隔离的并行执行\n            + 权限治理\n```\n\n就这些。这就是全部架构。每一个组件都是 harness 机制 -- 为 agent 构建的栖居世界的一部分。Agent 本身呢？是 Claude。一个模型。由 Anthropic 在人类推理和代码的全部广度上训练而成。Harness 没有让 Claude 变聪明。Claude 本来就聪明。Harness 给了 Claude 双手、双眼和一个工作空间。\n\n这就是 Claude Code 作为教学标本的意义：**它展示了当你信任模型、把工程精力集中在 harness 上时会发生什么。** 本仓库的每一个课程（s01-s12）都在逆向工程 Claude Code 架构中的一个 harness 机制。学完之后，你理解的不只是 Claude Code 怎么工作，而是适用于任何领域、任何 agent 的 harness 工程通用原则。\n\n启示不是 \"复制 Claude Code\"。启示是：**最好的 agent 产品，出自那些明白自己的工作是 harness 而非 intelligence 的工程师之手。**\n\n---\n\n## 愿景：用真正的 Agent 铺满宇宙\n\n这不只关乎编程 agent。\n\n每一个人类从事复杂、多步骤、需要判断力的工作的领域，都是 agent 可以运作的领域 -- 只要有对的 harness。本仓库中的模式是通用的：\n\n```\n庄园管理 agent  = 模型 + 物业传感器 + 维护工具 + 租户通信\n农业 agent      = 模型 + 土壤/气象数据 + 灌溉控制 + 作物知识\n酒店运营 agent  = 模型 + 预订系统 + 客户渠道 + 设施 API\n医学研究 agent  = 模型 + 文献检索 + 实验仪器 + 协议文档\n制造业 agent    = 模型 + 产线传感器 + 质量控制 + 物流系统\n教育 agent      = 模型 + 课程知识 + 学生进度 + 评估工具\n```\n\n循环永远不变。工具在变。知识在变。权限在变。Agent -- 那个模型 -- 泛化一切。\n\n每一个读这个仓库的 harness 工程师都在学习远超软件工程的模式。你在学习为一个智能的、自动化的未来构建基础设施。每一个部署在真实领域的好 harness，都是 agent 能够感知、推理、行动的又一个阵地。\n\n先铺满工作室。然后是农田、医院、工厂。然后是城市。然后是星球。\n\n**Bash is all you need. Real agents are all the universe needs.**\n\n---\n\n```\n                    THE AGENT PATTERN\n                    =================\n\n    User --> messages[] --> LLM --> response\n                                      |\n                            stop_reason == \"tool_use\"?\n                           /                          \\\n                         yes                           no\n                          |                             |\n                    execute tools                    return text\n                    append results\n                    loop back -----------------> messages[]\n\n\n    这是最小循环。每个 AI Agent 都需要这个循环。\n    模型决定何时调用工具、何时停止。\n    代码只是执行模型的要求。\n    本仓库教你构建围绕这个循环的一切 --\n    让 agent 在特定领域高效工作的 harness。\n```\n\n**12 个递进式课程, 从简单循环到隔离化的自治执行。**\n**每个课程添加一个 harness 机制。每个机制有一句格言。**\n\n> **s01**   *\"One loop & Bash is all you need\"* — 一个工具 + 一个循环 = 一个智能体\n>\n> **s02**   *\"加一个工具, 只加一个 handler\"* — 循环不用动, 新工具注册进 dispatch map 就行\n>\n> **s03**   *\"没有计划的 agent 走哪算哪\"* — 先列步骤再动手, 完成率翻倍\n>\n> **s04**   *\"大任务拆小, 每个小任务干净的上下文\"* — 子智能体用独立 messages[], 不污染主对话\n>\n> **s05**   *\"用到什么知识, 临时加载什么知识\"* — 通过 tool_result 注入, 不塞 system prompt\n>\n> **s06**   *\"上下文总会满, 要有办法腾地方\"* — 三层压缩策略, 换来无限会话\n>\n> **s07**   *\"大目标要拆成小任务, 排好序, 记在磁盘上\"* — 文件持久化的任务图, 为多 agent 协作打基础\n>\n> **s08**   *\"慢操作丢后台, agent 继续想下一步\"* — 后台线程跑命令, 完成后注入通知\n>\n> **s09**   *\"任务太大一个人干不完, 要能分给队友\"* — 持久化队友 + 异步邮箱\n>\n> **s10**   *\"队友之间要有统一的沟通规矩\"* — 一个 request-response 模式驱动所有协商\n>\n> **s11**   *\"队友自己看看板, 有活就认领\"* — 不需要领导逐个分配, 自组织\n>\n> **s12**   *\"各干各的目录, 互不干扰\"* — 任务管目标, worktree 管目录, 按 ID 绑定\n\n---\n\n## 核心模式\n\n```python\ndef agent_loop(messages):\n    while True:\n        response = client.messages.create(\n            model=MODEL, system=SYSTEM,\n            messages=messages, tools=TOOLS,\n        )\n        messages.append({\"role\": \"assistant\",\n                         \"content\": response.content})\n\n        if response.stop_reason != \"tool_use\":\n            return\n\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                output = TOOL_HANDLERS[block.name](**block.input)\n                results.append({\n                    \"type\": \"tool_result\",\n                    \"tool_use_id\": block.id,\n                    \"content\": output,\n                })\n        messages.append({\"role\": \"user\", \"content\": results})\n```\n\n每个课程在这个循环之上叠加一个 harness 机制 -- 循环本身始终不变。循环属于 agent。机制属于 harness。\n\n## 范围说明 (重要)\n\n本仓库是一个 0->1 的 harness 工程学习项目 -- 构建围绕 agent 模型的工作环境。\n为保证学习路径清晰，仓库有意简化或省略了部分生产机制：\n\n- 完整事件 / Hook 总线 (例如 PreToolUse、SessionStart/End、ConfigChange)。\n  s12 仅提供教学用途的最小 append-only 生命周期事件流。\n- 基于规则的权限治理与信任流程\n- 会话生命周期控制 (resume/fork) 与更完整的 worktree 生命周期控制\n- 完整 MCP 运行时细节 (transport/OAuth/资源订阅/轮询)\n\n仓库中的团队 JSONL 邮箱协议是教学实现，不是对任何特定生产内部实现的声明。\n\n## 快速开始\n\n```sh\ngit clone https://github.com/shareAI-lab/learn-claude-code\ncd learn-claude-code\npip install -r requirements.txt\ncp .env.example .env   # 编辑 .env 填入你的 ANTHROPIC_API_KEY\n\npython agents/s01_agent_loop.py       # 从这里开始\npython agents/s12_worktree_task_isolation.py  # 完整递进终点\npython agents/s_full.py               # 总纲: 全部机制合一\n```\n\n### Web 平台\n\n交互式可视化、分步动画、源码查看器, 以及每个课程的文档。\n\n```sh\ncd web && npm install && npm run dev   # http://localhost:3000\n```\n\n## 学习路径\n\n```\n第一阶段: 循环                       第二阶段: 规划与知识\n==================                   ==============================\ns01  Agent 循环              [1]     s03  TodoWrite               [5]\n     while + stop_reason                  TodoManager + nag 提醒\n     |                                    |\n     +-> s02  Tool Use            [4]     s04  子智能体             [5]\n              dispatch map: name->handler     每个子智能体独立 messages[]\n                                              |\n                                         s05  Skills               [5]\n                                              SKILL.md 通过 tool_result 注入\n                                              |\n                                         s06  Context Compact      [5]\n                                              三层上下文压缩\n\n第三阶段: 持久化                     第四阶段: 团队\n==================                   =====================\ns07  任务系统                [8]     s09  智能体团队             [9]\n     文件持久化 CRUD + 依赖图             队友 + JSONL 邮箱\n     |                                    |\ns08  后台任务                [6]     s10  团队协议               [12]\n     守护线程 + 通知队列                  关机 + 计划审批 FSM\n                                          |\n                                     s11  自治智能体             [14]\n                                          空闲轮询 + 自动认领\n                                     |\n                                     s12  Worktree 隔离          [16]\n                                          任务协调 + 按需隔离执行通道\n\n                                     [N] = 工具数量\n```\n\n## 项目结构\n\n```\nlearn-claude-code/\n|\n|-- agents/                        # Python 参考实现 (s01-s12 + s_full 总纲)\n|-- docs/{en,zh,ja}/               # 心智模型优先的文档 (3 种语言)\n|-- web/                           # 交互式学习平台 (Next.js)\n|-- skills/                        # s05 的 Skill 文件\n+-- .github/workflows/ci.yml      # CI: 类型检查 + 构建\n```\n\n## 文档\n\n心智模型优先: 问题、方案、ASCII 图、最小化代码。\n[English](./docs/en/) | [中文](./docs/zh/) | [日本語](./docs/ja/)\n\n| 课程 | 主题 | 格言 |\n|------|------|------|\n| [s01](./docs/zh/s01-the-agent-loop.md) | Agent 循环 | *One loop & Bash is all you need* |\n| [s02](./docs/zh/s02-tool-use.md) | Tool Use | *加一个工具, 只加一个 handler* |\n| [s03](./docs/zh/s03-todo-write.md) | TodoWrite | *没有计划的 agent 走哪算哪* |\n| [s04](./docs/zh/s04-subagent.md) | 子智能体 | *大任务拆小, 每个小任务干净的上下文* |\n| [s05](./docs/zh/s05-skill-loading.md) | Skills | *用到什么知识, 临时加载什么知识* |\n| [s06](./docs/zh/s06-context-compact.md) | Context Compact | *上下文总会满, 要有办法腾地方* |\n| [s07](./docs/zh/s07-task-system.md) | 任务系统 | *大目标要拆成小任务, 排好序, 记在磁盘上* |\n| [s08](./docs/zh/s08-background-tasks.md) | 后台任务 | *慢操作丢后台, agent 继续想下一步* |\n| [s09](./docs/zh/s09-agent-teams.md) | 智能体团队 | *任务太大一个人干不完, 要能分给队友* |\n| [s10](./docs/zh/s10-team-protocols.md) | 团队协议 | *队友之间要有统一的沟通规矩* |\n| [s11](./docs/zh/s11-autonomous-agents.md) | 自治智能体 | *队友自己看看板, 有活就认领* |\n| [s12](./docs/zh/s12-worktree-task-isolation.md) | Worktree + 任务隔离 | *各干各的目录, 互不干扰* |\n\n## 学完之后 -- 从理解到落地\n\n12 个课程走完, 你已经从内到外理解了 harness 工程的运作原理。两种方式把知识变成产品:\n\n### Kode Agent CLI -- 开源 Coding Agent CLI\n\n> `npm i -g @shareai-lab/kode`\n\n支持 Skill & LSP, 适配 Windows, 可接 GLM / MiniMax / DeepSeek 等开放模型。装完即用。\n\nGitHub: **[shareAI-lab/Kode-cli](https://github.com/shareAI-lab/Kode-cli)**\n\n### Kode Agent SDK -- 把 Agent 能力嵌入你的应用\n\n官方 Claude Code Agent SDK 底层与完整 CLI 进程通信 -- 每个并发用户 = 一个终端进程。Kode SDK 是独立库, 无 per-user 进程开销, 可嵌入后端、浏览器插件、嵌入式设备等任意运行时。\n\nGitHub: **[shareAI-lab/Kode-agent-sdk](https://github.com/shareAI-lab/Kode-agent-sdk)**\n\n---\n\n## 姊妹教程: 从*被动临时会话*到*主动常驻助手*\n\n本仓库教的 harness 属于 **用完即走** 型 -- 开终端、给 agent 任务、做完关掉, 下次重开是全新会话。Claude Code 就是这种模式。\n\n但 [OpenClaw](https://github.com/openclaw/openclaw) 证明了另一种可能: 在同样的 agent core 之上, 加两个 harness 机制就能让 agent 从 \"踹一下动一下\" 变成 \"自己隔 30 秒醒一次找活干\":\n\n- **心跳 (Heartbeat)** -- 每 30 秒 harness 给 agent 发一条消息, 让它检查有没有事可做。没事就继续睡, 有事立刻行动。\n- **定时任务 (Cron)** -- agent 可以给自己安排未来要做的事, 到点自动执行。\n\n再加上 IM 多通道路由 (WhatsApp/Telegram/Slack/Discord 等 13+ 平台)、不清空的上下文记忆、Soul 人格系统, agent 就从一个临时工具变成了始终在线的个人 AI 助手。\n\n**[claw0](https://github.com/shareAI-lab/claw0)** 是我们的姊妹教学仓库, 从零拆解这些 harness 机制:\n\n```\nclaw agent = agent core + heartbeat + cron + IM chat + memory + soul\n```\n\n```\nlearn-claude-code                   claw0\n(agent harness 内核:                 (主动式常驻 harness:\n 循环、工具、规划、                    心跳、定时任务、IM 通道、\n 团队、worktree 隔离)                  记忆、Soul 人格)\n```\n\n## 许可证\n\nMIT\n\n---\n\n**模型就是 Agent。代码是 Harness。造好 Harness，Agent 会完成剩下的。**\n\n**Bash is all you need. Real agents are all the universe needs.**\n"}, "a9c71002d2caa34fb14e264c647b1d5898b18ee0": {"t": 1785771656.5881324, "n": 13377, "h": "c51161c4de6e14f1", "c": "# Learn Claude Code -- 真正的 Agent Harness 工程\n\n[English](./README.md) | [中文](./README-zh.md) | [日本語](./README-ja.md)\n\n## 模型就是 Agent\n\n在讨论代码之前，先把一件事彻底说清楚。\n\n**Agent 是模型。不是框架。不是提示词链。不是拖拽式工作流。**\n\n### Agent 到底是什么\n\nAgent 是一个神经网络 -- Transformer、RNN、一个被训练出来的函数 -- 经过数十亿次梯度更新，在行动序列数据上学会了感知环境、推理目标、采取行动。\"Agent\" 这个词在 AI 领域从诞生之日起就是这个意思。从来都是。\n\n人类就是 agent。一个由数百万年进化训练出来的生物神经网络，通过感官感知世界，通过大脑推理，通过身体行动。当 DeepMind、OpenAI 或 Anthropic 说 \"agent\" 时，他们说的和这个领域自诞生以来就一直在说的完全一样：**一个学会了行动的模型。**\n\n历史已经写好了铁证：\n\n- **2013 -- DeepMind DQN 玩 Atari。** 一个神经网络，只接收原始像素和游戏分数，学会了 7 款 Atari 2600 游戏 -- 超越所有先前算法，在其中 3 款上击败人类专家。到 2015 年，同一架构扩展到 [49 款游戏，达到职业人类测试员水平](https://www.nature.com/articles/nature14236)，论文发表在 *Nature*。没有游戏专属规则。没有决策树。一个模型，从经验中学习。那个模型就是 agent。\n\n- **2019 -- OpenAI Five 征服 Dota 2。** 五个神经网络，在 10 个月内与自己对战了 [45,000 年的 Dota 2](https://openai.com/index/openai-five-defeats-dota-2-world-champions/)，在旧金山直播赛上 2-0 击败了 **OG** -- TI8 世界冠军。随后的公开竞技场中，AI 在 42,729 场比赛中胜率 99.4%。没有脚本化的策略。没有元编程的团队协调逻辑。模型完全通过自我对弈学会了团队协作、战术和实时适应。\n\n- **2019 -- DeepMind AlphaStar 制霸星际争霸 II。** AlphaStar 在闭门赛中 [10-1 击败职业选手](https://deepmind.google/blog/alphastar-mastering-the-real-time-strategy-game-starcraft-ii/)，随后在欧洲服务器上达到[宗师段位](https://www.nature.com/articles/d41586-019-03298-6) -- 90,000 名玩家中的前 0.15%。一个信息不完全、实时决策、组合动作空间远超国际象棋和围棋的游戏。Agent 是什么？是模型。训练出来的。不是编出来的。\n\n- **2019 -- 腾讯绝悟统治王者荣耀。** 腾讯 AI Lab 的 \"绝悟\" 于 2019 年 8 月 2 日世冠杯半决赛上[以 5v5 击败 KPL 职业选手](https://www.jiemian.com/article/3371171.html)。在 1v1 模式下，职业选手 [15 场只赢 1 场，最多坚持不到 8 分钟](https://developer.aliyun.com/article/851058)。训练强度：一天等于人类 440 年。到 2021 年，绝悟在全英雄池 BO5 上全面超越 KPL 职业选手水准。没有手工编写的英雄克制表。没有脚本化的阵容编排。一个从零开始通过自我对弈学习整个游戏的模型。\n\n- **2024-2025 -- LLM Agent 重塑软件工程。** Claude、GPT、Gemini -- 在人类全部代码和推理上训练的大语言模型 -- 被部署为编程 agent。它们阅读代码库，编写实现，调试故障，团队协作。架构与之前每一个 agent 完全相同：一个训练好的模型，放入一个环境，给予感知和行动的工具。唯一的不同是它们学到的东西的规模和解决任务的通用性。\n\n每一个里程碑都共享同一个真理：**\"Agent\" 从来都不是外面那层代码。Agent 永远是模型本身。**\n\n### Agent 不是什么\n\n\"Agent\" 这个词已经被一整个提示词水管工产业劫持了。\n\n拖拽式工作流构建器。无代码 \"AI Agent\" 平台。提示词链编排库。它们共享同一个幻觉：把 LLM API 调用用 if-else 分支、节点图、硬编码路由逻辑串在一起就算是 \"构建 Agent\" 了。\n\n不是的。它们做出来的东西是鲁布·戈德堡机械 -- 一个过度工程化的、脆弱的过程式规则流水线，LLM 被楔在里面当一个美化了的文本补全节点。那不是 Agent。那是一个有着宏大妄想的 shell 脚本。\n\n**提示词水管工式 \"Agent\" 是不做模型的程序员的意淫。** 他们试图通过堆叠过程式逻辑来暴力模拟智能 -- 庞大的规则树、节点图、链式提示词瀑布流 -- 然后祈祷足够多的胶水代码能涌现出自主行为。不会的。你不可能通过工程手段编码出 agency。Agency 是学出来的，不是编出来的。\n\n那些系统从诞生之日起就已经死了：脆弱、不可扩展、根本不具备泛化能力。它们是 GOFAI（Good Old-Fashioned AI，经典符号 AI）的现代还魂 -- 几十年前就被学界抛弃的符号规则系统，现在喷了一层 LLM 的漆又登场了。换了个包装，同一条死路。\n\n### 心智转换：从 \"开发 Agent\" 到开发 Harness\n\n当一个人说 \"我在开发 Agent\" 时，他只可能是两个意思之一：\n\n**1. 训练模型。** 通过强化学习、微调、RLHF 或其他基于梯度的方法调整权重。收集任务过程数据 -- 真实领域中感知、推理、行动的实际序列 -- 用它们来塑造模型的行为。这是 DeepMind、OpenAI、腾讯 AI Lab、Anthropic 在做的事。这是最本义的 Agent 开发。\n\n**2. 构建 Harness。** 编写代码，为模型提供一个可操作的环境。这是我们大多数人在做的事，也是本仓库的核心。\n\nHarness 是 agent 在特定领域工作所需要的一切：\n\n```\nHarness = Tools + Knowledge + Observation + Action Interfaces + Permissions\n\n    Tools:          文件读写、Shell、网络、数据库、浏览器\n    Knowledge:      产品文档、领域资料、API 规范、风格指南\n    Observation:    git diff、错误日志、浏览器状态、传感器数据\n    Action:         CLI 命令、API 调用、UI 交互\n    Permissions:    沙箱隔离、审批流程、信任边界\n```\n\n模型做决策。Harness 执行。模型做推理。Harness 提供上下文。模型是驾驶者。Harness 是载具。\n\n**编程 agent 的 harness 是它的 IDE、终端和文件系统。** 农业 agent 的 harness 是传感器阵列、灌溉控制和气象数据。酒店 agent 的 harness 是预订系统、客户沟通渠道和设施管理 API。Agent -- 那个智能、那个决策者 -- 永远是模型。Harness 因领域而变。Agent 跨领域泛化。\n\n这个仓库教你造载具。编程用的载具。但设计模式可以泛化到任何领域：庄园管理、农田运营、酒店运作、工厂制造、物流调度、医疗保健、教育培训、科学研究。只要有一个任务需要被感知、推理和执行 -- agent 就需要一个 harness。\n\n### Harness 工程师到底在做什么\n\n如果你在读这个仓库，你很可能是一名 harness 工程师 -- 这是一个强大的身份。以下是你真正的工作：\n\n- **实现工具。** 给 agent 一双手。文件读写、Shell 执行、API 调用、浏览器控制、数据库查询。每个工具都是 agent 在环境中可以采取的一个行动。设计它们时要原子化、可组合、描述清晰。\n\n- **策划知识。** 给 agent 领域专长。产品文档、架构决策记录、风格指南、合规要求。按需加载（s05），不要前置塞入。Agent 应该知道有什么可用，然后自己拉取所需。\n\n- **管理上下文。** 给 agent 干净的记忆。子 agent 隔离（s04）防止噪声泄露。上下文压缩（s06）防止历史淹没。任务系统（s07）让目标持久化到单次对话之外。\n\n- **控制权限。** 给 agent 边界。沙箱化文件访问。对破坏性操作要求审批。在 agent 和外部系统之间实施信任边界。这是安全工程与 harness 工程的交汇点。\n\n- **收集任务过程数据。** Agent 在你的 harness 中执行的每一条行动序列都是训练信号。真实部署中的感知-推理-行动轨迹是微调下一代 agent 模型的原材料。你的 harness 不仅服务于 agent -- 它还可以帮助进化 agent。\n\n你不是在编写智能。你是在构建智能栖居的世界。这个世界的质量 -- agent 能看得多清楚、行动得多精准、可用知识有多丰富 -- 直接决定了智能能多有效地表达自己。\n\n**造好 Harness。Agent 会完成剩下的。**\n\n### 为什么是 Claude Code -- Harness 工程的大师课\n\n为什么这个仓库专门拆解 Claude Code？\n\n因为 Claude Code 是我们所见过的最优雅、最完整的 agent harness 实现。不是因为某个巧妙的技巧，而是因为它 *没做* 的事：它没有试图成为 agent 本身。它没有强加僵化的工作流。它没有用精心设计的决策树去替模型做判断。它给模型提供了工具、知识、上下文管理和权限边界 -- 然后让开了。\n\n把 Claude Code 剥到本质来看：\n\n```\nClaude Code = 一个 agent loop\n            + 工具 (bash, read, write, edit, glob, grep, browser...)\n            + 按需 skill 加载\n            + 上下文压缩\n            + 子 agent 派生\n            + 带依赖图的任务系统\n            + 异步邮箱的团队协调\n            + worktree 隔离的并行执行\n            + 权限治理\n```\n\n就这些。这就是全部架构。每一个组件都是 harness 机制 -- 为 agent 构建的栖居世界的一部分。Agent 本身呢？是 Claude。一个模型。由 Anthropic 在人类推理和代码的全部广度上训练而成。Harness 没有让 Claude 变聪明。Claude 本来就聪明。Harness 给了 Claude 双手、双眼和一个工作空间。\n\n这就是 Claude Code 作为教学标本的意义：**它展示了当你信任模型、把工程精力集中在 harness 上时会发生什么。** 本仓库的每一个课程（s01-s12）都在逆向工程 Claude Code 架构中的一个 harness 机制。学完之后，你理解的不只是 Claude Code 怎么工作，而是适用于任何领域、任何 agent 的 harness 工程通用原则。\n\n启示不是 \"复制 Claude Code\"。启示是：**最好的 agent 产品，出自那些明白自己的工作是 harness 而非 intelligence 的工程师之手。**\n\n---\n\n## 愿景：用真正的 Agent 铺满宇宙\n\n这不只关乎编程 agent。\n\n每一个人类从事复杂、多步骤、需要判断力的工作的领域，都是 agent 可以运作的领域 -- 只要有对的 harness。本仓库中的模式是通用的：\n\n```\n庄园管理 agent  = 模型 + 物业传感器 + 维护工具 + 租户通信\n农业 agent      = 模型 + 土壤/气象数据 + 灌溉控制 + 作物知识\n酒店运营 agent  = 模型 + 预订系统 + 客户渠道 + 设施 API\n医学研究 agent  = 模型 + 文献检索 + 实验仪器 + 协议文档\n制造业 agent    = 模型 + 产线传感器 + 质量控制 + 物流系统\n教育 agent      = 模型 + 课程知识 + 学生进度 + 评估工具\n```\n\n循环永远不变。工具在变。知识在变。权限在变。Agent -- 那个模型 -- 泛化一切。\n\n每一个读这个仓库的 harness 工程师都在学习远超软件工程的模式。你在学习为一个智能的、自动化的未来构建基础设施。每一个部署在真实领域的好 harness，都是 agent 能够感知、推理、行动的又一个阵地。\n\n先铺满工作室。然后是农田、医院、工厂。然后是城市。然后是星球。\n\n**Bash is all you need. Real agents are all the universe needs.**\n\n---\n\n```\n                    THE AGENT PATTERN\n                    =================\n\n    User --> messages[] --> LLM --> response\n                                      |\n                            stop_reason == \"tool_use\"?\n                           /                          \\\n                         yes                           no\n                          |                             |\n                    execute tools                    return text\n                    append results\n                    loop back -----------------> messages[]\n\n\n    这是最小循环。每个 AI Agent 都需要这个循环。\n    模型决定何时调用工具、何时停止。\n    代码只是执行模型的要求。\n    本仓库教你构建围绕这个循环的一切 --\n    让 agent 在特定领域高效工作的 harness。\n```\n\n**12 个递进式课程, 从简单循环到隔离化的自治执行。**\n**每个课程添加一个 harness 机制。每个机制有一句格言。**\n\n> **s01**   *\"One loop & Bash is all you need\"* — 一个工具 + 一个循环 = 一个智能体\n>\n> **s02**   *\"加一个工具, 只加一个 handler\"* — 循环不用动, 新工具注册进 dispatch map 就行\n>\n> **s03**   *\"没有计划的 agent 走哪算哪\"* — 先列步骤再动手, 完成率翻倍\n>\n> **s04**   *\"大任务拆小, 每个小任务干净的上下文\"* — 子智能体用独立 messages[], 不污染主对话\n>\n> **s05**   *\"用到什么知识, 临时加载什么知识\"* — 通过 tool_result 注入, 不塞 system prompt\n>\n> **s06**   *\"上下文总会满, 要有办法腾地方\"* — 三层压缩策略, 换来无限会话\n>\n> **s07**   *\"大目标要拆成小任务, 排好序, 记在磁盘上\"* — 文件持久化的任务图, 为多 agent 协作打基础\n>\n> **s08**   *\"慢操作丢后台, agent 继续想下一步\"* — 后台线程跑命令, 完成后注入通知\n>\n> **s09**   *\"任务太大一个人干不完, 要能分给队友\"* — 持久化队友 + 异步邮箱\n>\n> **s10**   *\"队友之间要有统一的沟通规矩\"* — 一个 request-response 模式驱动所有协商\n>\n> **s11**   *\"队友自己看看板, 有活就认领\"* — 不需要领导逐个分配, 自组织\n>\n> **s12**   *\"各干各的目录, 互不干扰\"* — 任务管目标, worktree 管目录, 按 ID 绑定\n\n---\n\n## 核心模式\n\n```python\ndef agent_loop(messages):\n    while True:\n        response = client.messages.create(\n            model=MODEL, system=SYSTEM,\n            messages=messages, tools=TOOLS,\n        )\n        messages.append({\"role\": \"assistant\",\n                         \"content\": response.content})\n\n        if response.stop_reason != \"tool_use\":\n            return\n\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                output = TOOL_HANDLERS[block.name](**block.input)\n                results.append({\n                    \"type\": \"tool_result\",\n                    \"tool_use_id\": block.id,\n                    \"content\": output,\n                })\n        messages.append({\"role\": \"user\", \"content\": results})\n```\n\n每个课程在这个循环之上叠加一个 harness 机制 -- 循环本身始终不变。循环属于 agent。机制属于 harness。\n\n## 范围说明 (重要)\n\n本仓库是一个 0->1 的 harness 工程学习项目 -- 构建围绕 agent 模型的工作环境。\n为保证学习路径清晰，仓库有意简化或省略了部分生产机制：\n\n- 完整事件 / Hook 总线 (例如 PreToolUse、SessionStart/End、ConfigChange)。\n  s12 仅提供教学用途的最小 append-only 生命周期事件流。\n- 基于规则的权限治理与信任流程\n- 会话生命周期控制 (resume/fork) 与更完整的 worktree 生命周期控制\n- 完整 MCP 运行时细节 (transport/OAuth/资源订阅/轮询)\n\n仓库中的团队 JSONL 邮箱协议是教学实现，不是对任何特定生产内部实现的声明。\n\n## 快速开始\n\n```sh\ngit clone https://github.com/shareAI-lab/learn-claude-code\ncd learn-claude-code\npip install -r requirements.txt\ncp .env.example .env   # 编辑 .env 填入你的 ANTHROPIC_API_KEY\n\npython agents/s01_agent_loop.py       # 从这里开始\npython agents/s12_worktree_task_isolation.py  # 完整递进终点\npython agents/s_full.py               # 总纲: 全部机制合一\n```\n\n### Web 平台\n\n交互式可视化、分步动画、源码查看器, 以及每个课程的文档。\n\n```sh\ncd web && npm install && npm run dev   # http://localhost:3000\n```\n\n## 学习路径\n\n```\n第一阶段: 循环                       第二阶段: 规划与知识\n==================                   ==============================\ns01  Agent 循环              [1]     s03  TodoWrite               [5]\n     while + stop_reason                  TodoManager + nag 提醒\n     |                                    |\n     +-> s02  Tool Use            [4]     s04  子智能体             [5]\n              dispatch map: name->handler     每个子智能体独立 messages[]\n                                              |\n                                         s05  Skills               [5]\n                                              SKILL.md 通过 tool_result 注入\n                                              |\n                                         s06  Context Compact      [5]\n                                              三层上下文压缩\n\n第三阶段: 持久化                     第四阶段: 团队\n==================                   =====================\ns07  任务系统                [8]     s09  智能体团队             [9]\n     文件持久化 CRUD + 依赖图             队友 + JSONL 邮箱\n     |                                    |\ns08  后台任务                [6]     s10  团队协议               [12]\n     守护线程 + 通知队列                  关机 + 计划审批 FSM\n                                          |\n                                     s11  自治智能体             [14]\n                                          空闲轮询 + 自动认领\n                                     |\n                                     s12  Worktree 隔离          [16]\n                                          任务协调 + 按需隔离执行通道\n\n                                     [N] = 工具数量\n```\n\n## 项目结构\n\n```\nlearn-claude-code/\n|\n|-- agents/                        # Python 参考实现 (s01-s12 + s_full 总纲)\n|-- docs/{en,zh,ja}/               # 心智模型优先的文档 (3 种语言)\n|-- web/                           # 交互式学习平台 (Next.js)\n|-- skills/                        # s05 的 Skill 文件\n+-- .github/workflows/ci.yml      # CI: 类型检查 + 构建\n```\n\n## 文档\n\n心智模型优先: 问题、方案、ASCII 图、最小化代码。\n[English](./docs/en/) | [中文](./docs/zh/) | [日本語](./docs/ja/)\n\n| 课程 | 主题 | 格言 |\n|------|------|------|\n| [s01](./docs/zh/s01-the-agent-loop.md) | Agent 循环 | *One loop & Bash is all you need* |\n| [s02](./docs/zh/s02-tool-use.md) | Tool Use | *加一个工具, 只加一个 handler* |\n| [s03](./docs/zh/s03-todo-write.md) | TodoWrite | *没有计划的 agent 走哪算哪* |\n| [s04](./docs/zh/s04-subagent.md) | 子智能体 | *大任务拆小, 每个小任务干净的上下文* |\n| [s05](./docs/zh/s05-skill-loading.md) | Skills | *用到什么知识, 临时加载什么知识* |\n| [s06](./docs/zh/s06-context-compact.md) | Context Compact | *上下文总会满, 要有办法腾地方* |\n| [s07](./docs/zh/s07-task-system.md) | 任务系统 | *大目标要拆成小任务, 排好序, 记在磁盘上* |\n| [s08](./docs/zh/s08-background-tasks.md) | 后台任务 | *慢操作丢后台, agent 继续想下一步* |\n| [s09](./docs/zh/s09-agent-teams.md) | 智能体团队 | *任务太大一个人干不完, 要能分给队友* |\n| [s10](./docs/zh/s10-team-protocols.md) | 团队协议 | *队友之间要有统一的沟通规矩* |\n| [s11](./docs/zh/s11-autonomous-agents.md) | 自治智能体 | *队友自己看看板, 有活就认领* |\n| [s12](./docs/zh/s12-worktree-task-isolation.md) | Worktree + 任务隔离 | *各干各的目录, 互不干扰* |\n\n## 学完之后 -- 从理解到落地\n\n12 个课程走完, 你已经从内到外理解了 harness 工程的运作原理。两种方式把知识变成产品:\n\n### Kode Agent CLI -- 开源 Coding Agent CLI\n\n> `npm i -g @shareai-lab/kode`\n\n支持 Skill & LSP, 适配 Windows, 可接 GLM / MiniMax / DeepSeek 等开放模型。装完即用。\n\nGitHub: **[shareAI-lab/Kode-cli](https://github.com/shareAI-lab/Kode-cli)**\n\n### Kode Agent SDK -- 把 Agent 能力嵌入你的应用\n\n官方 Claude Code Agent SDK 底层与完整 CLI 进程通信 -- 每个并发用户 = 一个终端进程。Kode SDK 是独立库, 无 per-user 进程开销, 可嵌入后端、浏览器插件、嵌入式设备等任意运行时。\n\nGitHub: **[shareAI-lab/Kode-agent-sdk](https://github.com/shareAI-lab/Kode-agent-sdk)**\n\n---\n\n## 姊妹教程: 从*被动临时会话*到*主动常驻助手*\n\n本仓库教的 harness 属于 **用完即走** 型 -- 开终端、给 agent 任务、做完关掉, 下次重开是全新会话。Claude Code 就是这种模式。\n\n但 [OpenClaw](https://github.com/openclaw/openclaw) 证明了另一种可能: 在同样的 agent core 之上, 加两个 harness 机制就能让 agent 从 \"踹一下动一下\" 变成 \"自己隔 30 秒醒一次找活干\":\n\n- **心跳 (Heartbeat)** -- 每 30 秒 harness 给 agent 发一条消息, 让它检查有没有事可做。没事就继续睡, 有事立刻行动。\n- **定时任务 (Cron)** -- agent 可以给自己安排未来要做的事, 到点自动执行。\n\n再加上 IM 多通道路由 (WhatsApp/Telegram/Slack/Discord 等 13+ 平台)、不清空的上下文记忆、Soul 人格系统, agent 就从一个临时工具变成了始终在线的个人 AI 助手。\n\n**[claw0](https://github.com/shareAI-lab/claw0)** 是我们的姊妹教学仓库, 从零拆解这些 harness 机制:\n\n```\nclaw agent = agent core + heartbeat + cron + IM chat + memory + soul\n```\n\n```\nlearn-claude-code                   claw0\n(agent harness 内核:                 (主动式常驻 harness:\n 循环、工具、规划、                    心跳、定时任务、IM 通道、\n 团队、worktree 隔离)                  记忆、Soul 人格)\n```\n\n## 许可证\n\nMIT\n\n---\n\n**模型就是 Agent。代码是 Harness。造好 Harness，Agent 会完成剩下的。**\n\n**Bash is all you need. Real agents are all the universe needs.**\n"}, "4f39ee4512cd812985a0b88ac5bc5c22b6df940d": {"t": 1785771660.445928, "n": 7613, "h": "3ca1345bc8732669", "c": "# Learn Claude Code -- 从 0 到 1 构建 nano Claude Code-like agent\n\n[English](./README.md) | [中文](./README-zh.md) | [日本語](./README-ja.md)\n\n```\n                    THE AGENT PATTERN\n                    =================\n\n    User --> messages[] --> LLM --> response\n                                      |\n                            stop_reason == \"tool_use\"?\n                           /                          \\\n                         yes                           no\n                          |                             |\n                    execute tools                    return text\n                    append results\n                    loop back -----------------> messages[]\n\n\n    这是最小循环。每个 AI 编程 Agent 都需要这个循环。\n    生产级 Agent 还会叠加策略、权限与生命周期层。\n```\n\n**12 个递进式课程, 从简单循环到隔离化的自治执行。**\n**每个课程添加一个机制。每个机制有一句格言。**\n\n> **s01**   *\"One loop & Bash is all you need\"* — 一个工具 + 一个循环 = 一个智能体\n>\n> **s02**   *\"加一个工具, 只加一个 handler\"* — 循环不用动, 新工具注册进 dispatch map 就行\n>\n> **s03**   *\"没有计划的 agent 走哪算哪\"* — 先列步骤再动手, 完成率翻倍\n>\n> **s04**   *\"大任务拆小, 每个小任务干净的上下文\"* — 子智能体用独立 messages[], 不污染主对话\n>\n> **s05**   *\"用到什么知识, 临时加载什么知识\"* — 通过 tool_result 注入, 不塞 system prompt\n>\n> **s06**   *\"上下文总会满, 要有办法腾地方\"* — 三层压缩策略, 换来无限会话\n>\n> **s07**   *\"大目标要拆成小任务, 排好序, 记在磁盘上\"* — 文件持久化的任务图, 为多 agent 协作打基础\n>\n> **s08**   *\"慢操作丢后台, agent 继续想下一步\"* — 后台线程跑命令, 完成后注入通知\n>\n> **s09**   *\"任务太大一个人干不完, 要能分给队友\"* — 持久化队友 + 异步邮箱\n>\n> **s10**   *\"队友之间要有统一的沟通规矩\"* — 一个 request-response 模式驱动所有协商\n>\n> **s11**   *\"队友自己看看板, 有活就认领\"* — 不需要领导逐个分配, 自组织\n>\n> **s12**   *\"各干各的目录, 互不干扰\"* — 任务管目标, worktree 管目录, 按 ID 绑定\n\n---\n\n## 核心模式\n\n```python\ndef agent_loop(messages):\n    while True:\n        response = client.messages.create(\n            model=MODEL, system=SYSTEM,\n            messages=messages, tools=TOOLS,\n        )\n        messages.append({\"role\": \"assistant\",\n                         \"content\": response.content})\n\n        if response.stop_reason != \"tool_use\":\n            return\n\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                output = TOOL_HANDLERS[block.name](**block.input)\n                results.append({\n                    \"type\": \"tool_result\",\n                    \"tool_use_id\": block.id,\n                    \"content\": output,\n                })\n        messages.append({\"role\": \"user\", \"content\": results})\n```\n\n每个课程在这个循环之上叠加一个机制 -- 循环本身始终不变。\n\n## 范围说明 (重要)\n\n本仓库是一个 0->1 的学习型项目，用于从零构建 nano Claude Code-like agent。\n为保证学习路径清晰，仓库有意简化或省略了部分生产机制：\n\n- 完整事件 / Hook 总线 (例如 PreToolUse、SessionStart/End、ConfigChange)。  \n  s12 仅提供教学用途的最小 append-only 生命周期事件流。\n- 基于规则的权限治理与信任流程\n- 会话生命周期控制 (resume/fork) 与更完整的 worktree 生命周期控制\n- 完整 MCP 运行时细节 (transport/OAuth/资源订阅/轮询)\n\n仓库中的团队 JSONL 邮箱协议是教学实现，不是对任何特定生产内部实现的声明。\n\n## 快速开始\n\n```sh\ngit clone https://github.com/shareAI-lab/learn-claude-code\ncd learn-claude-code\npip install -r requirements.txt\ncp .env.example .env   # 编辑 .env 填入你的 ANTHROPIC_API_KEY\n\npython agents/s01_agent_loop.py       # 从这里开始\npython agents/s12_worktree_task_isolation.py  # 完整递进终点\npython agents/s_full.py               # 总纲: 全部机制合一\n```\n\n### Web 平台\n\n交互式可视化、分步动画、源码查看器, 以及每个课程的文档。\n\n```sh\ncd web && npm install && npm run dev   # http://localhost:3000\n```\n\n## 学习路径\n\n```\n第一阶段: 循环                       第二阶段: 规划与知识\n==================                   ==============================\ns01  Agent 循环              [1]     s03  TodoWrite               [5]\n     while + stop_reason                  TodoManager + nag 提醒\n     |                                    |\n     +-> s02  Tool Use            [4]     s04  子智能体             [5]\n              dispatch map: name->handler     每个子智能体独立 messages[]\n                                              |\n                                         s05  Skills               [5]\n                                              SKILL.md 通过 tool_result 注入\n                                              |\n                                         s06  Context Compact      [5]\n                                              三层上下文压缩\n\n第三阶段: 持久化                     第四阶段: 团队\n==================                   =====================\ns07  任务系统                [8]     s09  智能体团队             [9]\n     文件持久化 CRUD + 依赖图             队友 + JSONL 邮箱\n     |                                    |\ns08  后台任务                [6]     s10  团队协议               [12]\n     守护线程 + 通知队列                  关机 + 计划审批 FSM\n                                          |\n                                     s11  自治智能体             [14]\n                                          空闲轮询 + 自动认领\n                                     |\n                                     s12  Worktree 隔离          [16]\n                                          任务协调 + 按需隔离执行通道\n\n                                     [N] = 工具数量\n```\n\n## 项目结构\n\n```\nlearn-claude-code/\n|\n|-- agents/                        # Python 参考实现 (s01-s12 + s_full 总纲)\n|-- docs/{en,zh,ja}/               # 心智模型优先的文档 (3 种语言)\n|-- web/                           # 交互式学习平台 (Next.js)\n|-- skills/                        # s05 的 Skill 文件\n+-- .github/workflows/ci.yml      # CI: 类型检查 + 构建\n```\n\n## 文档\n\n心智模型优先: 问题、方案、ASCII 图、最小化代码。\n[English](./docs/en/) | [中文](./docs/zh/) | [日本語](./docs/ja/)\n\n| 课程 | 主题 | 格言 |\n|------|------|------|\n| [s01](./docs/zh/s01-the-agent-loop.md) | Agent 循环 | *One loop & Bash is all you need* |\n| [s02](./docs/zh/s02-tool-use.md) | Tool Use | *加一个工具, 只加一个 handler* |\n| [s03](./docs/zh/s03-todo-write.md) | TodoWrite | *没有计划的 agent 走哪算哪* |\n| [s04](./docs/zh/s04-subagent.md) | 子智能体 | *大任务拆小, 每个小任务干净的上下文* |\n| [s05](./docs/zh/s05-skill-loading.md) | Skills | *用到什么知识, 临时加载什么知识* |\n| [s06](./docs/zh/s06-context-compact.md) | Context Compact | *上下文总会满, 要有办法腾地方* |\n| [s07](./docs/zh/s07-task-system.md) | 任务系统 | *大目标要拆成小任务, 排好序, 记在磁盘上* |\n| [s08](./docs/zh/s08-background-tasks.md) | 后台任务 | *慢操作丢后台, agent 继续想下一步* |\n| [s09](./docs/zh/s09-agent-teams.md) | 智能体团队 | *任务太大一个人干不完, 要能分给队友* |\n| [s10](./docs/zh/s10-team-protocols.md) | 团队协议 | *队友之间要有统一的沟通规矩* |\n| [s11](./docs/zh/s11-autonomous-agents.md) | 自治智能体 | *队友自己看看板, 有活就认领* |\n| [s12](./docs/zh/s12-worktree-task-isolation.md) | Worktree + 任务隔离 | *各干各的目录, 互不干扰* |\n\n## 学完之后 -- 从理解到落地\n\n12 个课程走完, 你已经从内到外理解了 agent 的工作原理。两种方式把知识变成产品:\n\n### Kode Agent CLI -- 开源 Coding Agent CLI\n\n> `npm i -g @shareai-lab/kode`\n\n支持 Skill & LSP, 适配 Windows, 可接 GLM / MiniMax / DeepSeek 等开放模型。装完即用。\n\nGitHub: **[shareAI-lab/Kode-cli](https://github.com/shareAI-lab/Kode-cli)**\n\n### Kode Agent SDK -- 把 Agent 能力嵌入你的应用\n\n官方 Claude Code Agent SDK 底层与完整 CLI 进程通信 -- 每个并发用户 = 一个终端进程。Kode SDK 是独立库, 无 per-user 进程开销, 可嵌入后端、浏览器插件、嵌入式设备等任意运行时。\n\nGitHub: **[shareAI-lab/Kode-agent-sdk](https://github.com/shareAI-lab/Kode-agent-sdk)**\n\n---\n\n## 姊妹教程: 从*被动临时会话*到*主动常驻助手*\n\n本仓库教的 agent 属于 **用完即走** 型 -- 开终端、给任务、做完关掉, 下次重开是全新会话。Claude Code 就是这种模式。\n\n但 [OpenClaw](https://github.com/openclaw/openclaw) (小龙虾) 证明了另一种可能: 在同样的 agent core 之上, 加两个机制就能让 agent 从\"踹一下动一下\"变成\"自己隔 30 秒醒一次找活干\":\n\n- **心跳 (Heartbeat)** -- 每 30 秒系统给 agent 发一条消息, 让它检查有没有事可做。没事就继续睡, 有事立刻行动。\n- **定时任务 (Cron)** -- agent 可以给自己安排未来要做的事, 到点自动执行。\n\n再加上 IM 多通道路由 (WhatsApp/Telegram/Slack/Discord 等 13+ 平台)、不清空的上下文记忆、Soul 人格系统, agent 就从一个临时工具变成了始终在线的个人 AI 助手。\n\n**[claw0](https://github.com/shareAI-lab/claw0)** 是我们的姊妹教学仓库, 从零拆解这些机制:\n\n```\nclaw agent = agent core + heartbeat + cron + IM chat + memory + soul\n```\n\n```\nlearn-claude-code                   claw0\n(agent 运行时内核:                   (主动式常驻 AI 助手:\n 循环、工具、规划、                    心跳、定时任务、IM 通道、\n 团队、worktree 隔离)                  记忆、Soul 人格)\n```\n\n## 许可证\n\nMIT\n\n---\n\n**模型就是智能体。我们的工作就是给它工具, 然后让开。**\n"}, "665831c774ed4d46d798238c989fe21dcfc1f1de": {"t": 1785771661.7805662, "n": 7433, "h": "1af67c32b0f34083", "c": "# Learn Claude Code -- 从 0 到 1 构建 nano Claude Code-like agent\n\n[English](./README.md) | [中文](./README-zh.md) | [日本語](./README-ja.md)\n\n```\n                    THE AGENT PATTERN\n                    =================\n\n    User --> messages[] --> LLM --> response\n                                      |\n                            stop_reason == \"tool_use\"?\n                           /                          \\\n                         yes                           no\n                          |                             |\n                    execute tools                    return text\n                    append results\n                    loop back -----------------> messages[]\n\n\n    这是最小循环。每个 AI 编程 Agent 都需要这个循环。\n    生产级 Agent 还会叠加策略、权限与生命周期层。\n```\n\n**12 个递进式课程, 从简单循环到隔离化的自治执行。**\n**每个课程添加一个机制。每个机制有一句格言。**\n\n> **s01**   *\"One loop & Bash is all you need\"* — 一个工具 + 一个循环 = 一个智能体\n>\n> **s02**   *\"循环没有变\"* — 加工具就是加 handler, 不是重写循环\n>\n> **s03**   *\"先计划再行动\"* — 可见的计划提升任务完成率\n>\n> **s04**   *\"进程隔离 = 上下文隔离\"* — 每个子智能体独立 messages[]\n>\n> **s05**   *\"按需加载, 而非预装\"* — 通过 tool_result 注入知识, 而非塞进 system prompt\n>\n> **s06**   *\"策略性遗忘\"* — 忘掉旧上下文, 换来无限会话\n>\n> **s07**   *\"状态在压缩后存活\"* — 文件持久化的状态不怕上下文压缩\n>\n> **s08**   *\"发射后不管\"* — 非阻塞线程 + 通知队列\n>\n> **s09**   *\"追加即发送, 排空即读取\"* — 异步邮箱实现持久化队友通信\n>\n> **s10**   *\"同一个 request_id, 两个协议\"* — 一个 FSM 模式驱动关机 + 计划审批\n>\n> **s11**   *\"轮询, 认领, 工作, 重复\"* — 无需协调者, 智能体自组织\n>\n> **s12**   *\"目录隔离, 任务 ID 协调\"* — 任务板协调 + 按需 worktree 隔离通道\n\n---\n\n## 核心模式\n\n```python\ndef agent_loop(messages):\n    while True:\n        response = client.messages.create(\n            model=MODEL, system=SYSTEM,\n            messages=messages, tools=TOOLS,\n        )\n        messages.append({\"role\": \"assistant\",\n                         \"content\": response.content})\n\n        if response.stop_reason != \"tool_use\":\n            return\n\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                output = TOOL_HANDLERS[block.name](**block.input)\n                results.append({\n                    \"type\": \"tool_result\",\n                    \"tool_use_id\": block.id,\n                    \"content\": output,\n                })\n        messages.append({\"role\": \"user\", \"content\": results})\n```\n\n每个课程在这个循环之上叠加一个机制 -- 循环本身始终不变。\n\n## 范围说明 (重要)\n\n本仓库是一个 0->1 的学习型项目，用于从零构建 nano Claude Code-like agent。\n为保证学习路径清晰，仓库有意简化或省略了部分生产机制：\n\n- 完整事件 / Hook 总线 (例如 PreToolUse、SessionStart/End、ConfigChange)。  \n  s12 仅提供教学用途的最小 append-only 生命周期事件流。\n- 基于规则的权限治理与信任流程\n- 会话生命周期控制 (resume/fork) 与更完整的 worktree 生命周期控制\n- 完整 MCP 运行时细节 (transport/OAuth/资源订阅/轮询)\n\n仓库中的团队 JSONL 邮箱协议是教学实现，不是对任何特定生产内部实现的声明。\n\n## 快速开始\n\n```sh\ngit clone https://github.com/shareAI-lab/learn-claude-code\ncd learn-claude-code\npip install -r requirements.txt\ncp .env.example .env   # 编辑 .env 填入你的 ANTHROPIC_API_KEY\n\npython agents/s01_agent_loop.py       # 从这里开始\npython agents/s12_worktree_task_isolation.py  # 完整递进终点\npython agents/s_full.py               # 总纲: 全部机制合一\n```\n\n### Web 平台\n\n交互式可视化、分步动画、源码查看器, 以及每个课程的文档。\n\n```sh\ncd web && npm install && npm run dev   # http://localhost:3000\n```\n\n## 学习路径\n\n```\n第一阶段: 循环                       第二阶段: 规划与知识\n==================                   ==============================\ns01  Agent 循环              [1]     s03  TodoWrite               [5]\n     while + stop_reason                  TodoManager + nag 提醒\n     |                                    |\n     +-> s02  Tool Use            [4]     s04  子智能体             [5]\n              dispatch map: name->handler     每个子智能体独立 messages[]\n                                              |\n                                         s05  Skills               [5]\n                                              SKILL.md 通过 tool_result 注入\n                                              |\n                                         s06  Context Compact      [5]\n                                              三层上下文压缩\n\n第三阶段: 持久化                     第四阶段: 团队\n==================                   =====================\ns07  任务系统                [8]     s09  智能体团队             [9]\n     文件持久化 CRUD + 依赖图             队友 + JSONL 邮箱\n     |                                    |\ns08  后台任务                [6]     s10  团队协议               [12]\n     守护线程 + 通知队列                  关机 + 计划审批 FSM\n                                          |\n                                     s11  自治智能体             [14]\n                                          空闲轮询 + 自动认领\n                                     |\n                                     s12  Worktree 隔离          [16]\n                                          任务协调 + 按需隔离执行通道\n\n                                     [N] = 工具数量\n```\n\n## 项目结构\n\n```\nlearn-claude-code/\n|\n|-- agents/                        # Python 参考实现 (s01-s12 + s_full 总纲)\n|-- docs/{en,zh,ja}/               # 心智模型优先的文档 (3 种语言)\n|-- web/                           # 交互式学习平台 (Next.js)\n|-- skills/                        # s05 的 Skill 文件\n+-- .github/workflows/ci.yml      # CI: 类型检查 + 构建\n```\n\n## 文档\n\n心智模型优先: 问题、方案、ASCII 图、最小化代码。\n[English](./docs/en/) | [中文](./docs/zh/) | [日本語](./docs/ja/)\n\n| 课程 | 主题 | 格言 |\n|------|------|------|\n| [s01](./docs/zh/s01-the-agent-loop.md) | Agent 循环 | *One loop & Bash is all you need* |\n| [s02](./docs/zh/s02-tool-use.md) | Tool Use | *循环没有变* |\n| [s03](./docs/zh/s03-todo-write.md) | TodoWrite | *先计划再行动* |\n| [s04](./docs/zh/s04-subagent.md) | 子智能体 | *进程隔离 = 上下文隔离* |\n| [s05](./docs/zh/s05-skill-loading.md) | Skills | *按需加载, 而非预装* |\n| [s06](./docs/zh/s06-context-compact.md) | Context Compact | *策略性遗忘* |\n| [s07](./docs/zh/s07-task-system.md) | 任务系统 | *状态在压缩后存活* |\n| [s08](./docs/zh/s08-background-tasks.md) | 后台任务 | *发射后不管* |\n| [s09](./docs/zh/s09-agent-teams.md) | 智能体团队 | *追加即发送, 排空即读取* |\n| [s10](./docs/zh/s10-team-protocols.md) | 团队协议 | *同一个 request_id, 两个协议* |\n| [s11](./docs/zh/s11-autonomous-agents.md) | 自治智能体 | *轮询, 认领, 工作, 重复* |\n| [s12](./docs/zh/s12-worktree-task-isolation.md) | Worktree + 任务隔离 | *目录隔离, 任务 ID 协调* |\n\n## 学完之后 -- 从理解到落地\n\n12 个课程走完, 你已经从内到外理解了 agent 的工作原理。两种方式把知识变成产品:\n\n### Kode Agent CLI -- 开源 Coding Agent CLI\n\n> `npm i -g @shareai-lab/kode`\n\n支持 Skill & LSP, 适配 Windows, 可接 GLM / MiniMax / DeepSeek 等开放模型。装完即用。\n\nGitHub: **[shareAI-lab/Kode-cli](https://github.com/shareAI-lab/Kode-cli)**\n\n### Kode Agent SDK -- 把 Agent 能力嵌入你的应用\n\n官方 Claude Code Agent SDK 底层与完整 CLI 进程通信 -- 每个并发用户 = 一个终端进程。Kode SDK 是独立库, 无 per-user 进程开销, 可嵌入后端、浏览器插件、嵌入式设备等任意运行时。\n\nGitHub: **[shareAI-lab/Kode-agent-sdk](https://github.com/shareAI-lab/Kode-agent-sdk)**\n\n---\n\n## 姊妹教程: 从*被动临时会话*到*主动常驻助手*\n\n本仓库教的 agent 属于 **用完即走** 型 -- 开终端、给任务、做完关掉, 下次重开是全新会话。Claude Code 就是这种模式。\n\n但 [OpenClaw](https://github.com/openclaw/openclaw) (小龙虾) 证明了另一种可能: 在同样的 agent core 之上, 加两个机制就能让 agent 从\"踹一下动一下\"变成\"自己隔 30 秒醒一次找活干\":\n\n- **心跳 (Heartbeat)** -- 每 30 秒系统给 agent 发一条消息, 让它检查有没有事可做。没事就继续睡, 有事立刻行动。\n- **定时任务 (Cron)** -- agent 可以给自己安排未来要做的事, 到点自动执行。\n\n再加上 IM 多通道路由 (WhatsApp/Telegram/Slack/Discord 等 13+ 平台)、不清空的上下文记忆、Soul 人格系统, agent 就从一个临时工具变成了始终在线的个人 AI 助手。\n\n**[claw0](https://github.com/shareAI-lab/claw0)** 是我们的姊妹教学仓库, 从零拆解这些机制:\n\n```\nclaw agent = agent core + heartbeat + cron + IM chat + memory + soul\n```\n\n```\nlearn-claude-code                   claw0\n(agent 运行时内核:                   (主动式常驻 AI 助手:\n 循环、工具、规划、                    心跳、定时任务、IM 通道、\n 团队、worktree 隔离)                  记忆、Soul 人格)\n```\n\n## 许可证\n\nMIT\n\n---\n\n**模型就是智能体。我们的工作就是给它工具, 然后让开。**\n"}, "aea8844bac756b354a72871533cd3dbeb60a4e1a": {"t": 1785771662.9921882, "n": 6029, "h": "1baba2f5a443b3a9", "c": "# Learn Claude Code -- 从 0 到 1 构建 nano Claude Code-like agent\n\n[English](./README.md) | [中文](./README-zh.md) | [日本語](./README-ja.md)\n\n```\n                    THE AGENT PATTERN\n                    =================\n\n    User --> messages[] --> LLM --> response\n                                      |\n                            stop_reason == \"tool_use\"?\n                           /                          \\\n                         yes                           no\n                          |                             |\n                    execute tools                    return text\n                    append results\n                    loop back -----------------> messages[]\n\n\n    这是最小循环。每个 AI 编程 Agent 都需要这个循环。\n    生产级 Agent 还会叠加策略、权限与生命周期层。\n```\n\n**12 个递进式课程, 从简单循环到隔离化的自治执行。**\n**每个课程添加一个机制。每个机制有一句格言。**\n\n> **s01**   *\"Bash 就够了\"* — 一个工具 + 一个循环 = 一个智能体\n>\n> **s02**   *\"循环没有变\"* — 加工具就是加 handler, 不是重写循环\n>\n> **s03**   *\"先计划再行动\"* — 可见的计划提升任务完成率\n>\n> **s04**   *\"进程隔离 = 上下文隔离\"* — 每个子智能体独立 messages[]\n>\n> **s05**   *\"按需加载, 而非预装\"* — 通过 tool_result 注入知识, 而非塞进 system prompt\n>\n> **s06**   *\"策略性遗忘\"* — 忘掉旧上下文, 换来无限会话\n>\n> **s07**   *\"状态在压缩后存活\"* — 文件持久化的状态不怕上下文压缩\n>\n> **s08**   *\"发射后不管\"* — 非阻塞线程 + 通知队列\n>\n> **s09**   *\"追加即发送, 排空即读取\"* — 异步邮箱实现持久化队友通信\n>\n> **s10**   *\"同一个 request_id, 两个协议\"* — 一个 FSM 模式驱动关机 + 计划审批\n>\n> **s11**   *\"轮询, 认领, 工作, 重复\"* — 无需协调者, 智能体自组织\n>\n> **s12**   *\"目录隔离, 任务 ID 协调\"* — 任务板协调 + 按需 worktree 隔离通道\n\n---\n\n## 核心模式\n\n```python\ndef agent_loop(messages):\n    while True:\n        response = client.messages.create(\n            model=MODEL, system=SYSTEM,\n            messages=messages, tools=TOOLS,\n        )\n        messages.append({\"role\": \"assistant\",\n                         \"content\": response.content})\n\n        if response.stop_reason != \"tool_use\":\n            return\n\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                output = TOOL_HANDLERS[block.name](**block.input)\n                results.append({\n                    \"type\": \"tool_result\",\n                    \"tool_use_id\": block.id,\n                    \"content\": output,\n                })\n        messages.append({\"role\": \"user\", \"content\": results})\n```\n\n每个课程在这个循环之上叠加一个机制 -- 循环本身始终不变。\n\n## 范围说明 (重要)\n\n本仓库是一个 0->1 的学习型项目，用于从零构建 nano Claude Code-like agent。\n为保证学习路径清晰，仓库有意简化或省略了部分生产机制：\n\n- 完整事件 / Hook 总线 (例如 PreToolUse、SessionStart/End、ConfigChange)。  \n  s12 仅提供教学用途的最小 append-only 生命周期事件流。\n- 基于规则的权限治理与信任流程\n- 会话生命周期控制 (resume/fork) 与更完整的 worktree 生命周期控制\n- 完整 MCP 运行时细节 (transport/OAuth/资源订阅/轮询)\n\n仓库中的团队 JSONL 邮箱协议是教学实现，不是对任何特定生产内部实现的声明。\n\n## 快速开始\n\n```sh\ngit clone https://github.com/shareAI-lab/learn-claude-code\ncd learn-claude-code\npip install -r requirements.txt\ncp .env.example .env   # 编辑 .env 填入你的 ANTHROPIC_API_KEY\n\npython agents/s01_agent_loop.py       # 从这里开始\npython agents/s11_autonomous_agents.py  # 完整自治团队\npython agents/s12_worktree_task_isolation.py  # Task 感知的 worktree 隔离\n```\n\n### Web 平台\n\n交互式可视化、分步动画、源码查看器, 以及每个课程的文档。\n\n```sh\ncd web && npm install && npm run dev   # http://localhost:3000\n```\n\n## 学习路径\n\n```\n第一阶段: 循环                       第二阶段: 规划与知识\n==================                   ==============================\ns01  Agent 循环              [1]     s03  TodoWrite               [5]\n     while + stop_reason                  TodoManager + nag 提醒\n     |                                    |\n     +-> s02  工具               [4]     s04  子智能体             [5]\n              dispatch map: name->handler     每个子智能体独立 messages[]\n                                              |\n                                         s05  Skills               [5]\n                                              SKILL.md 通过 tool_result 注入\n                                              |\n                                         s06  Compact              [5]\n                                              三层上下文压缩\n\n第三阶段: 持久化                     第四阶段: 团队\n==================                   =====================\ns07  任务系统                [8]     s09  智能体团队             [9]\n     文件持久化 CRUD + 依赖图             队友 + JSONL 邮箱\n     |                                    |\ns08  后台任务                [6]     s10  团队协议               [12]\n     守护线程 + 通知队列                  关机 + 计划审批 FSM\n                                          |\n                                     s11  自治智能体             [14]\n                                          空闲轮询 + 自动认领\n                                     |\n                                     s12  Worktree 隔离          [16]\n                                          任务协调 + 按需隔离执行通道\n\n                                     [N] = 工具数量\n```\n\n## 项目结构\n\n```\nlearn-claude-code/\n|\n|-- agents/                        # Python 参考实现 (s01-s12 + 完整版)\n|-- docs/{en,zh,ja}/               # 心智模型优先的文档 (3 种语言)\n|-- web/                           # 交互式学习平台 (Next.js)\n|-- skills/                        # s05 的 Skill 文件\n+-- .github/workflows/ci.yml      # CI: 类型检查 + 构建\n```\n\n## 文档\n\n心智模型优先: 问题、方案、ASCII 图、最小化代码。\n[English](./docs/en/) | [中文](./docs/zh/) | [日本語](./docs/ja/)\n\n| 课程 | 主题 | 格言 |\n|------|------|------|\n| [s01](./docs/zh/s01-the-agent-loop.md) | Agent 循环 | *Bash 就够了* |\n| [s02](./docs/zh/s02-tool-use.md) | 工具 | *循环没有变* |\n| [s03](./docs/zh/s03-todo-write.md) | TodoWrite | *先计划再行动* |\n| [s04](./docs/zh/s04-subagent.md) | 子智能体 | *进程隔离 = 上下文隔离* |\n| [s05](./docs/zh/s05-skill-loading.md) | Skills | *按需加载, 而非预装* |\n| [s06](./docs/zh/s06-context-compact.md) | Compact | *策略性遗忘* |\n| [s07](./docs/zh/s07-task-system.md) | 任务系统 | *状态在压缩后存活* |\n| [s08](./docs/zh/s08-background-tasks.md) | 后台任务 | *发射后不管* |\n| [s09](./docs/zh/s09-agent-teams.md) | 智能体团队 | *追加即发送, 排空即读取* |\n| [s10](./docs/zh/s10-team-protocols.md) | 团队协议 | *同一个 request_id, 两个协议* |\n| [s11](./docs/zh/s11-autonomous-agents.md) | 自治智能体 | *轮询, 认领, 工作, 重复* |\n| [s12](./docs/zh/s12-worktree-task-isolation.md) | Worktree + 任务隔离 | *目录隔离, 任务 ID 协调* |\n\n## 许可证\n\nMIT\n\n---\n\n**模型就是智能体。我们的工作就是给它工具, 然后让开。**\n"}, "c6a27ef1d77c1e57523114ac4d15354751cdcc11": {"t": 1785771666.2493467, "n": 5236, "h": "111340c1f8631c8c", "c": "# Learn Claude Code -- 从零构建 AI Agent\n\n[English](./README.md) | [中文](./README-zh.md) | [日本語](./README-ja.md)\n\n```\n                    THE AGENT PATTERN\n                    =================\n\n    User --> messages[] --> LLM --> response\n                                      |\n                            stop_reason == \"tool_use\"?\n                           /                          \\\n                         yes                           no\n                          |                             |\n                    execute tools                    return text\n                    append results\n                    loop back -----------------> messages[]\n\n\n    就这些。每个 AI 编程 Agent 都是这个循环。\n    其他一切都是优化。\n```\n\n**11 个递进式课程, 从简单循环到完整的自治团队。**\n**每个课程添加一个机制。每个机制有一句格言。**\n\n> **s01**   *\"Bash 就够了\"* — 一个工具 + 一个循环 = 一个智能体\n>\n> **s02**   *\"循环没有变\"* — 加工具就是加 handler, 不是加逻辑\n>\n> **s03**   *\"先计划再行动\"* — 可见的计划提升任务完成率\n>\n> **s04**   *\"进程隔离 = 上下文隔离\"* — 每个子智能体独立 messages[]\n>\n> **s05**   *\"按需加载, 而非预装\"* — 通过 tool_result 注入知识, 而非塞进 system prompt\n>\n> **s06**   *\"策略性遗忘\"* — 忘掉旧上下文, 换来无限会话\n>\n> **s07**   *\"状态在压缩后存活\"* — 文件持久化的状态不怕上下文压缩\n>\n> **s08**   *\"发射后不管\"* — 非阻塞线程 + 通知队列\n>\n> **s09**   *\"追加即发送, 排空即读取\"* — 异步邮箱实现持久化队友通信\n>\n> **s10**   *\"同一个 request_id, 两个协议\"* — 一个 FSM 模式驱动关机 + 计划审批\n>\n> **s11**   *\"轮询, 认领, 工作, 重复\"* — 无需协调者, 智能体自组织\n\n---\n\n## 核心模式\n\n```python\ndef agent_loop(messages):\n    while True:\n        response = client.messages.create(\n            model=MODEL, system=SYSTEM,\n            messages=messages, tools=TOOLS,\n        )\n        messages.append({\"role\": \"assistant\",\n                         \"content\": response.content})\n\n        if response.stop_reason != \"tool_use\":\n            return\n\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                output = TOOL_HANDLERS[block.name](**block.input)\n                results.append({\n                    \"type\": \"tool_result\",\n                    \"tool_use_id\": block.id,\n                    \"content\": output,\n                })\n        messages.append({\"role\": \"user\", \"content\": results})\n```\n\n每个课程在这个循环之上叠加一个机制 -- 循环本身始终不变。\n\n## 快速开始\n\n```sh\ngit clone https://github.com/shareAI-lab/learn-claude-code\ncd learn-claude-code\npip install -r requirements.txt\ncp .env.example .env   # 编辑 .env 填入你的 ANTHROPIC_API_KEY\n\npython agents/s01_agent_loop.py       # 从这里开始\npython agents/s11_autonomous_agents.py  # 完整自治团队\n```\n\n### Web 平台\n\n交互式可视化、分步动画、源码查看器, 以及每个课程的文档。\n\n```sh\ncd web && npm install && npm run dev   # http://localhost:3000\n```\n\n## 学习路径\n\n```\n第一阶段: 循环                       第二阶段: 规划与知识\n==================                   ==============================\ns01  Agent 循环              [1]     s03  TodoWrite               [5]\n     while + stop_reason                  TodoManager + nag 提醒\n     |                                    |\n     +-> s02  工具               [4]     s04  子智能体             [5]\n              dispatch map: name->handler     每个子智能体独立 messages[]\n                                              |\n                                         s05  Skills               [5]\n                                              SKILL.md 通过 tool_result 注入\n                                              |\n                                         s06  Compact              [5]\n                                              三层上下文压缩\n\n第三阶段: 持久化                     第四阶段: 团队\n==================                   =====================\ns07  任务系统                [8]     s09  智能体团队             [9]\n     文件持久化 CRUD + 依赖图             队友 + JSONL 邮箱\n     |                                    |\ns08  后台任务                [6]     s10  团队协议               [12]\n     守护线程 + 通知队列                  关机 + 计划审批 FSM\n                                          |\n                                     s11  自治智能体             [14]\n                                          空闲轮询 + 自动认领\n\n                                     [N] = 工具数量\n```\n\n## 项目结构\n\n```\nlearn-claude-code/\n|\n|-- agents/                        # Python 参考实现 (s01-s11 + 完整版)\n|-- docs/{en,zh,ja}/               # 心智模型优先的文档 (3 种语言)\n|-- web/                           # 交互式学习平台 (Next.js)\n|-- skills/                        # s05 的 Skill 文件\n+-- .github/workflows/ci.yml      # CI: 类型检查 + 构建\n```\n\n## 文档\n\n心智模型优先: 问题、方案、ASCII 图、最小化代码。\n[English](./docs/en/) | [中文](./docs/zh/) | [日本語](./docs/ja/)\n\n| 课程 | 主题 | 格言 |\n|------|------|------|\n| [s01](./docs/zh/s01-the-agent-loop.md) | Agent 循环 | *Bash 就够了* |\n| [s02](./docs/zh/s02-tool-use.md) | 工具 | *循环没有变* |\n| [s03](./docs/zh/s03-todo-write.md) | TodoWrite | *先计划再行动* |\n| [s04](./docs/zh/s04-subagent.md) | 子智能体 | *进程隔离 = 上下文隔离* |\n| [s05](./docs/zh/s05-skill-loading.md) | Skills | *按需加载, 而非预装* |\n| [s06](./docs/zh/s06-context-compact.md) | Compact | *策略性遗忘* |\n| [s07](./docs/zh/s07-task-system.md) | 任务系统 | *状态在压缩后存活* |\n| [s08](./docs/zh/s08-background-tasks.md) | 后台任务 | *发射后不管* |\n| [s09](./docs/zh/s09-agent-teams.md) | 智能体团队 | *追加即发送, 排空即读取* |\n| [s10](./docs/zh/s10-team-protocols.md) | 团队协议 | *同一个 request_id, 两个协议* |\n| [s11](./docs/zh/s11-autonomous-agents.md) | 自治智能体 | *轮询, 认领, 工作, 重复* |\n\n## 许可证\n\nMIT\n\n---\n\n**模型就是智能体。我们的工作是给它工具, 然后让开。**\n"}}}}