diff --git a/README-zh.md b/README-zh.md index 843cce1f3..7f1744a99 100644 --- a/README-zh.md +++ b/README-zh.md @@ -1,162 +1,185 @@ -# Learn Claude Code -- 真正的 Agent Harness 工程 - [English](./README.md) | [中文](./README-zh.md) | [日本語](./README-ja.md) -## 模型就是 Agent +# Learn Claude Code -- 真正的 Agent Harness 工程 + +## Agent 的本质：模型即智能体 在讨论代码之前，先把一件事彻底说清楚。 -**Agent 是模型。不是框架。不是提示词链。不是拖拽式工作流。** +**Agent 的本质就是模型。它不是框架，不是提示词链（Prompt Chain），更不是那种可视化拖拽的工作流。** ### Agent 到底是什么 -Agent 是一个神经网络 -- Transformer、RNN、一个被训练出来的函数 -- 经过数十亿次梯度更新，在行动序列数据上学会了感知环境、推理目标、采取行动。"Agent" 这个词在 AI 领域从诞生之日起就是这个意思。从来都是。 +Agent 是一个神经网络 —— 无论是 Transformer、RNN，还是一个高度复杂的泛函 —— 它经过了数十亿次基于“行动序列数据”的梯度更新。它在训练中学会了如何感知环境、推理目标，并采取行动以达成目的。在 AI 领域，“Agent” 自诞生之日起就代表这个含义，从未改变。 -人类就是 agent。一个由数百万年进化训练出来的生物神经网络，通过感官感知世界，通过大脑推理，通过身体行动。当 DeepMind、OpenAI 或 Anthropic 说 "agent" 时，他们说的和这个领域自诞生以来就一直在说的完全一样：**一个学会了行动的模型。** +人类本身就是 Agent。一个由数百万年进化“训练”出来的生物神经网络：通过感官感知世界，通过大脑进行推理，通过身体执行行动。当 DeepMind、OpenAI 或 Anthropic 谈论 “Agent” 时，其内涵与该领域初期并无二致：**一个学会了行动的模型。** -历史已经写好了铁证： +历史早已给出了铁证： -- **2013 -- DeepMind DQN 玩 Atari。** 一个神经网络，只接收原始像素和游戏分数，学会了 7 款 Atari 2600 游戏 -- 超越所有先前算法，在其中 3 款上击败人类专家。到 2015 年，同一架构扩展到 [49 款游戏，达到职业人类测试员水平](https://www.nature.com/articles/nature14236)，论文发表在 *Nature*。没有游戏专属规则。没有决策树。一个模型，从经验中学习。那个模型就是 agent。 +- **2013 -- DeepMind DQN 纵横 Atari 游戏。** +一个仅接收原始像素和游戏分数的神经网络，学会了 7 款 Atari 2600 游戏，表现超越了此前所有算法。到 2015 年，该架构扩展至 [49 款游戏，达到职业人类水平](https://www.nature.com/articles/nature14236)，论文发表于 *Nature*。**没有游戏规则硬编码，没有决策树。只有一个从经验中学习的模型。那个模型，就是 Agent**。 -- **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%。没有脚本化的策略。没有元编程的团队协调逻辑。模型完全通过自我对弈学会了团队协作、战术和实时适应。 +- **2019 -- OpenAI Five 征服 Dota 2。** +五个神经网络在 10 个月内通过自我对弈，积攒了 [45,000 年的 Dota 2游戏经验](https://openai.com/index/openai-five-defeats-dota-2-world-champions/)，它们在旧金山的直播赛中以 2-0 完胜 TI8 世界冠军 **OG**。随后在公开竞技场中，AI 以 99.4% 的胜率横扫全球玩家。**没有脚本化的策略，没有人工编写的协作逻辑。模型完全通过自我对弈学会了团队配合、战术部署与实时应变**。 -- **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 是什么？是模型。训练出来的。不是编出来的。 +- **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) （前 0.15%）。面对信息不完全、实时决策且操作空间远超围棋的复杂环境，**Agent 是什么？它是一个训练出来的模型，而不是编排出来的脚本**。 -- **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 职业选手水准。没有手工编写的英雄克制表。没有脚本化的阵容编排。一个从零开始通过自我对弈学习整个游戏的模型。 +- **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)。其训练强度达到“人间一日，模型百年”。**没有手写的英雄克制表，没有预设的阵容组合。这是一个从零开始，通过自我对弈理解了整个游戏规则的模型。** -- **2024-2025 -- LLM Agent 重塑软件工程。** Claude、GPT、Gemini -- 在人类全部代码和推理上训练的大语言模型 -- 被部署为编程 agent。它们阅读代码库，编写实现，调试故障，团队协作。架构与之前每一个 agent 完全相同：一个训练好的模型，放入一个环境，给予感知和行动的工具。唯一的不同是它们学到的东西的规模和解决任务的通用性。 +- **2024-2025 -- LLM Agent 深度重构软件工程。** +这一年，以 Claude、GPT 和 Gemini 为代表的大模型，在汲取了全人类的代码精髓与推理逻辑后，正式进化为 **Coding Agent**。它们深入代码库，独立完成实现、调试与团队协同。从架构上看，它们与此前的每一代 Agent 别无二致：同样是置于特定环境中、赋予感知与行动能力的预训练模型。真正的质变，在于其学习规模的跨越，以及处理通用任务的非凡上限。 -每一个里程碑都共享同一个真理：**"Agent" 从来都不是外面那层代码。Agent 永远是模型本身。** +以上每一个里程碑都昭示着同一个真理：**所谓的“智能体”，其灵魂从未存在于那些包裹它的外层代码中。Agent，永远指代模型本身。** -### Agent 不是什么 +### Agent “不是”什么 -"Agent" 这个词已经被一整个提示词水管工产业劫持了。 +如今，“Agent” 这个词正被一整个“提示词水管工（Prompt Plumbing）”产业所劫持。 -拖拽式工作流构建器。无代码 "AI Agent" 平台。提示词链编排库。它们共享同一个幻觉：把 LLM API 调用用 if-else 分支、节点图、硬编码路由逻辑串在一起就算是 "构建 Agent" 了。 +无论是拖拽式的工作流生成器、无代码 AI Agent 平台，还是各类提示词链（Prompt Chain）编排库，它们都沉溺于同一个幻觉：只要把一堆 LLM API 调用，用 if-else 分支、节点图和硬编码的路由逻辑串联起来，就是在“构建 Agent”了。 -不是的。它们做出来的东西是鲁布·戈德堡机械 -- 一个过度工程化的、脆弱的过程式规则流水线，LLM 被楔在里面当一个美化了的文本补全节点。那不是 Agent。那是一个有着宏大妄想的 shell 脚本。 +这完全是误导。 它们构建的不过是**“鲁布·戈德堡机械”（Rube Goldberg machine）—— 一堆过度工程化、极度脆弱的过程式规则流水线，而 LLM 只是被硬生生塞进去充当一个“高级文本补全插件”。那不是 Agent，那只是一个患有“宏大叙事妄想症”的 Shell 脚本**。 -**提示词水管工式 "Agent" 是不做模型的程序员的意淫。** 他们试图通过堆叠过程式逻辑来暴力模拟智能 -- 庞大的规则树、节点图、链式提示词瀑布流 -- 然后祈祷足够多的胶水代码能涌现出自主行为。不会的。你不可能通过工程手段编码出 agency。Agency 是学出来的，不是编出来的。 +这种“水管工式 Agent”，是不懂模型训练的程序员的集体意淫。 他们试图通过堆叠过程式逻辑来暴力模拟智能：拉出庞大的规则树、节点图和链式提示词瀑布流，然后祈祷只要胶水代码写得足够多，就能“涌现”出自主行为。 -那些系统从诞生之日起就已经死了：脆弱、不可扩展、根本不具备泛化能力。它们是 GOFAI（Good Old-Fashioned AI，经典符号 AI）的现代还魂 -- 几十年前就被学界抛弃的符号规则系统，现在喷了一层 LLM 的漆又登场了。换了个包装，同一条死路。 +现实是：不可能。 自主性（Agency）是“练”出来的，不是“编”出来的。你无法通过纯粹的工程手段强行编排（Engineer）出真正的智能。 -### 心智转换：从 "开发 Agent" 到开发 Harness +这些系统从诞生之日起就注定了失败：它们结构脆弱、无法扩展、且根本不具备泛化能力。它们本质上是 GOFAI（经典符号 AI）的现代还魂 —— 几十年前就被主流学界抛弃的符号规则系统，如今喷了一层 LLM 的油漆便试图重亮招牌。包装变了，但依然是一条死路。 -当一个人说 "我在开发 Agent" 时，他只可能是两个意思之一： +### 心智转向：从“开发 Agent”到“构建 Harness” -**1. 训练模型。** 通过强化学习、微调、RLHF 或其他基于梯度的方法调整权重。收集任务过程数据 -- 真实领域中感知、推理、行动的实际序列 -- 用它们来塑造模型的行为。这是 DeepMind、OpenAI、腾讯 AI Lab、Anthropic 在做的事。这是最本义的 Agent 开发。 +当有人说“我在开发 Agent”时，其真实含义只可能有两种： -**2. 构建 Harness。** 编写代码，为模型提供一个可操作的环境。这是我们大多数人在做的事，也是本仓库的核心。 +**1. 训练模型（Training）** 通过强化学习（RL）、微调（Fine-tuning）或 RLHF 等手段调整模型权重。核心在于收集任务过程数据（Task-Process Data）——即真实领域中感知、推理、行动的序列——并以此塑造模型的行为。这是 DeepMind、OpenAI 或 Anthropic 的战场。这是最原教旨意义上的 Agent 开发。 -Harness 是 agent 在特定领域工作所需要的一切： +**2. 构建 Harness（机架/载具）** 编写代码，为模型提供一个可交互、可感知的运行环境。** 这是绝大多数开发者的使命，也是本仓库的核心。** + +什么是 Harness？Harness 是 Agent 在特定领域开展工作所需的一切基础设施： ``` -Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions +Harness = 工具 (Tools) + 知识 (Knowledge) + 观测 (Observation) + 行动接口 (Action Interfaces) + 权限 (Permissions) + + 工具：文件 I/O、Shell、网络请求、数据库、浏览器。 + + 知识：产品文档、领域参考、API 规范、风格指南。 - Tools: 文件读写、Shell、网络、数据库、浏览器 - Knowledge: 产品文档、领域资料、API 规范、风格指南 - Observation: git diff、错误日志、浏览器状态、传感器数据 - Action: CLI 命令、API 调用、UI 交互 - Permissions: 沙箱隔离、审批流程、信任边界 + 观测：Git Diff、错误日志、浏览器状态、传感器回传。 + + 行动：CLI 命令、API 调用、UI 交互。 + + 权限：沙箱隔离、审批流、信任边界。 ``` -模型做决策。Harness 执行。模型做推理。Harness 提供上下文。模型是驾驶者。Harness 是载具。 +模型负责决策，Harness 负责执行。模型负责推理，Harness 提供上下文。模型是驾驶员，Harness 是载具。 + +- 编程 Agent 的 Harness 是它的 IDE、终端和文件系统。 + +- 农业 Agent 的 Harness 是传感器阵列、灌溉控制和气象数据源。 + +- 酒店 Agent 的 Harness 是预订系统、客情渠道和设施管理接口。 + +智能（决策者）永远是模型，它是通用的；而 Harness 随领域而变。 -**编程 agent 的 harness 是它的 IDE、终端和文件系统。** 农业 agent 的 harness 是传感器阵列、灌溉控制和气象数据。酒店 agent 的 harness 是预订系统、客户沟通渠道和设施管理 API。Agent -- 那个智能、那个决策者 -- 永远是模型。Harness 因领域而变。Agent 跨领域泛化。 +本仓库教你构建“载具”———虽然我们以编程为例，但其背后的设计模式适用于任何需要“感知-推理-执行”循环的领域：从工厂制造到物流调度，从医疗保健到科学研究。 -这个仓库教你造载具。编程用的载具。但设计模式可以泛化到任何领域：庄园管理、农田运营、酒店运作、工厂制造、物流调度、医疗保健、教育培训、科学研究。只要有一个任务需要被感知、推理和执行 -- agent 就需要一个 harness。 +### Harness 工程师的真实职责 -### Harness 工程师到底在做什么 +如果你正在阅读本仓库，你很可能就是一名 Harness 工程师。这是一个极具威力的角色，你的核心工作包括： -如果你在读这个仓库，你很可能是一名 harness 工程师 -- 这是一个强大的身份。以下是你真正的工作： +- **实现工具：赋予 Agent “双手”**。开发文件读写、API 调用、数据库查询等接口。每个工具都是 Agent 在环境中的一个动作。设计原则：原子化、可组合、描述清晰。 -- **实现工具。** 给 agent 一双手。文件读写、Shell 执行、API 调用、浏览器控制、数据库查询。每个工具都是 agent 在环境中可以采取的一个行动。设计它们时要原子化、可组合、描述清晰。 +- **策划知识：赋予 Agent “专长”。** 整合架构决策（ADR）、合规要求或项目文档。采用按需加载 (s05) 而非一股脑塞入。Agent 应当清楚“地图”上有哪些资源，并在需要时自行调取。 -- **策划知识。** 给 agent 领域专长。产品文档、架构决策记录、风格指南、合规要求。按需加载（s05），不要前置塞入。Agent 应该知道有什么可用，然后自己拉取所需。 +- **管理上下文：赋予 Agent “记忆”。** 通过子 Agent 隔离 (s04) 屏蔽噪声，利用上下文压缩 (s06) 防止历史冗余，依靠任务系统 (s07) 实现跨会话的目标持久化。 -- **管理上下文。** 给 agent 干净的记忆。子 agent 隔离（s04）防止噪声泄露。上下文压缩（s06）防止历史淹没。任务系统（s07）让目标持久化到单次对话之外。 +- **控制权限：赋予 Agent “边界”。** 沙箱化文件访问，为高危操作设置审批，在 Agent 与外部系统间筑起信任防火墙。这是安全工程与 Harness 工程的交汇点。 -- **控制权限。** 给 agent 边界。沙箱化文件访问。对破坏性操作要求审批。在 agent 和外部系统之间实施信任边界。这是安全工程与 harness 工程的交汇点。 +- **收集任务过程数据：反哺进化。** Agent 在你的 Harness 中执行的每一条路径都是珍贵的训练信号。真实环境下的“感知-推理-行动”轨迹，是微调下一代 Agent 模型的原材料。你的 Harness 不仅在消耗智能，更在生产智能。 -- **收集任务过程数据。** Agent 在你的 harness 中执行的每一条行动序列都是训练信号。真实部署中的感知-推理-行动轨迹是微调下一代 agent 模型的原材料。你的 harness 不仅服务于 agent -- 它还可以帮助进化 agent。 +你不是在编写智能，你是在构建智能栖居的世界。 -你不是在编写智能。你是在构建智能栖居的世界。这个世界的质量 -- agent 能看得多清楚、行动得多精准、可用知识有多丰富 -- 直接决定了智能能多有效地表达自己。 +这个世界的精度——Agent 看得多清、动作多准、知识多深——直接决定了那颗“智能大脑”的表达上限。 -**造好 Harness。Agent 会完成剩下的。** +**造好你的 Harness，剩下的交给 Agent。** -### 为什么是 Claude Code -- Harness 工程的大师课 +### 为什么选择 Claude Code：Harness 工程的大师课 -为什么这个仓库专门拆解 Claude Code？ +为什么本仓库选择深度拆解 Claude Code？ -因为 Claude Code 是我们所见过的最优雅、最完整的 agent harness 实现。不是因为某个巧妙的技巧，而是因为它 *没做* 的事：它没有试图成为 agent 本身。它没有强加僵化的工作流。它没有用精心设计的决策树去替模型做判断。它给模型提供了工具、知识、上下文管理和权限边界 -- 然后让开了。 +因为 Claude Code 是目前我们所见过的、最优雅且实现最完整的 **Agent Harness** 范本。它的卓越不在于某种奇巧淫技，而在于它**克制**了什么：它没有试图僭越成为 Agent 本身；它没有强加僵化的工作流；它更没有用复杂的决策树去预判模型的意图。 -把 Claude Code 剥到本质来看： +Claude Code 的逻辑非常纯粹：**为模型提供工具、知识、上下文管理和权限边界，然后——退后，让模型自己发挥。** + +剥离表象，Claude Code 的本质架构极其精炼： ``` -Claude Code = 一个 agent loop - + 工具 (bash, read, write, edit, glob, grep, browser...) - + 按需 skill 加载 - + 上下文压缩 - + 子 agent 派生 - + 带依赖图的任务系统 - + 异步邮箱的团队协调 - + worktree 隔离的并行执行 - + 权限治理 +Claude Code = 核心 Agent Loop + + 基础工具集 (bash, read, write, edit, glob, grep, browser...) + + 技能按需加载 (On-demand Skill Loading) + + 上下文压缩 (Context Compression) + + 子 Agent 派生 (Subagent Spawning) + + 带依赖图的任务系统 (Task System w/ Dependency Graph) + + 基于异步信箱的团队协作 (Team Coordination) + + 工作流隔离的并行执行 (Worktree Isolation) + + 权限治理与安全边界 (Permission Governance) ``` -就这些。这就是全部架构。每一个组件都是 harness 机制 -- 为 agent 构建的栖居世界的一部分。Agent 本身呢？是 Claude。一个模型。由 Anthropic 在人类推理和代码的全部广度上训练而成。Harness 没有让 Claude 变聪明。Claude 本来就聪明。Harness 给了 Claude 双手、双眼和一个工作空间。 +这就是全部。每一个组件都是一种 Harness 机制 —— 它们共同构成了 Agent 赖以生存的“栖居地”。 + +至于 Agent 本身，它是 Claude。一个由 Anthropic 在全人类推理逻辑与代码数据上训练而成的深度模型。Harness 并没有让 Claude 变聪明，Claude 本身就足够聪明。Harness 的意义在于给了 Claude 双手、双眼和一个高效的作业空间。 + +这也是 Claude Code 具备极高教学价值的原因：**它完美演示了当你选择信任模型，并将工程精力全部集中在 Harness 上时，能爆发多大的生产力。** -这就是 Claude Code 作为教学标本的意义：**它展示了当你信任模型、把工程精力集中在 harness 上时会发生什么。** 本仓库的每一个课程（s01-s12）都在逆向工程 Claude Code 架构中的一个 harness 机制。学完之后，你理解的不只是 Claude Code 怎么工作，而是适用于任何领域、任何 agent 的 harness 工程通用原则。 +本仓库的每一章（s01-s12）都在逆向工程 Claude Code 架构中的一个核心 Harness 机制。学完这些课程，你掌握的不只是 Claude Code 的运行逻辑，更是能够横跨任何领域、适配任何 Agent 的 Harness 工程通用原则。 -启示不是 "复制 Claude Code"。启示是：**最好的 agent 产品，出自那些明白自己的工作是 harness 而非 intelligence 的工程师之手。** +这门课给我们的启示并非“复制一个 Claude Code”，而是：**真正顶级的 Agent 产品，往往出自那些深刻理解“自己的工作是构建 Harness，而非代行 Intelligence”的工程师之手。** --- ## 愿景：用真正的 Agent 铺满宇宙 -这不只关乎编程 agent。 +这不只关乎编程 Agent。 -每一个人类从事复杂、多步骤、需要判断力的工作的领域，都是 agent 可以运作的领域 -- 只要有对的 harness。本仓库中的模式是通用的： +任何人类从事复杂、多步骤、高度依赖判断力的领域，都是 Agent 可以大显身手的疆场——前提是拥有匹配的 **Harness**。本仓库沉淀的设计模式具有普适性： -``` -庄园管理 agent = 模型 + 物业传感器 + 维护工具 + 租户通信 -农业 agent = 模型 + 土壤/气象数据 + 灌溉控制 + 作物知识 -酒店运营 agent = 模型 + 预订系统 + 客户渠道 + 设施 API -医学研究 agent = 模型 + 文献检索 + 实验仪器 + 协议文档 -制造业 agent = 模型 + 产线传感器 + 质量控制 + 物流系统 -教育 agent = 模型 + 课程知识 + 学生进度 + 评估工具 -``` +* **庄园管理 Agent** = 模型 + 物业传感器 + 维护工具 + 租户通信接口 +* **农业生产 Agent** = 模型 + 土壤/气象数据 + 灌溉控制系统 + 作物生长知识库 +* **酒店运营 Agent** = 模型 + 预订系统 + 客情渠道 + 设施管理 API +* **医学研究 Agent** = 模型 + 文献自动检索 + 实验仪器接口 + 实验协议文档 +* **智能制造 Agent** = 模型 + 产线传感器 + 质量控制算法 + 物流调度系统 +* **教育辅导 Agent** = 模型 + 课程知识图谱 + 学生进度追踪 + 自动化评估工具 -循环永远不变。工具在变。知识在变。权限在变。Agent -- 那个模型 -- 泛化一切。 +**循环逻辑永远不变，改变的只是工具、知识与权限。Agent（模型）负责泛化一切，而你负责武装它。** -每一个读这个仓库的 harness 工程师都在学习远超软件工程的模式。你在学习为一个智能的、自动化的未来构建基础设施。每一个部署在真实领域的好 harness，都是 agent 能够感知、推理、行动的又一个阵地。 +每一位阅读本仓库的 Harness 工程师，都在学习一套远超软件工程范畴的元模式。你正在为那个智能化、自动化的未来构建基础设施。在真实领域中每部署一个设计精良的 Harness，就是为 Agent 开辟了一块能够感知、推理与行动的阵地。 -先铺满工作室。然后是农田、医院、工厂。然后是城市。然后是星球。 +从工作室开始，延伸至农田、医院与工厂。最终，它们将遍布城市，铺满星球。 -**Bash is all you need. Real agents are all the universe needs.** +**有 Bash 就够了，宇宙只需要真正的 Agent。** --- -``` - THE AGENT PATTERN - ================= - - User --> messages[] --> LLM --> response - | - stop_reason == "tool_use"? - / \ - yes no - | | - execute tools return text - append results - loop back -----------------> messages[] - - - 这是最小循环。每个 AI Agent 都需要这个循环。 - 模型决定何时调用工具、何时停止。 - 代码只是执行模型的要求。 - 本仓库教你构建围绕这个循环的一切 -- - 让 agent 在特定领域高效工作的 harness。 +### Agent 模式图解 + +```text + 用户 --> 消息列表[] --> 大模型 (LLM) --> 响应内容 + | + 结束原因 == "调用工具"? + / \ + 是 否 + | | + 执行工具 返回文本 + 附加结果 + 回到循环 -----------------> 消息列表[] + + 这是 最小化循环。它是所有 AI Agent 的心脏。 + + 模型决定何时调用工具、何时终止。 + + 代码只负责忠实执行模型的需求。 + + 本仓库教你构建环绕这个心脏的整个躯干——即让 Agent 在特定领域高效工作的 Harness。 ``` **12 个递进式课程, 从简单循环到隔离化的自治执行。** @@ -164,27 +187,27 @@ Claude Code = 一个 agent loop > **s01**   *"One loop & Bash is all you need"* — 一个工具 + 一个循环 = 一个 Agent > -> **s02**   *"加一个工具, 只加一个 handler"* — 循环不用动, 新工具注册进 dispatch map 就行 +> **s02**   *"增加工具，只需增加一个 Handler"* — 循环架构无需改动，新工具直接注册进 Dispatch Map > -> **s03**   *"没有计划的 agent 走哪算哪"* — 先列步骤再动手, 完成率翻倍 +> **s03**   *"没有计划的 Agent 只能盲目漂流"* — 先列步骤再动手，任务完成率将获得质的提升。 > -> **s04**   *"大任务拆小, 每个小任务干净的上下文"* — Subagent 用独立 messages[], 不污染主对话 +> **s04**   *"拆解大任务；每个子任务拥有洁净的上下文"* — 子 Agent 使用独立对话流，拒绝污染主进程。 > -> **s05**   *"用到什么知识, 临时加载什么知识"* — 通过 tool_result 注入, 不塞 system prompt +> **s05**   *"按需加载知识，而非预置知识"* — 通过 tool_result 动态注入，不要加重 System Prompt 的负担。 > -> **s06**   *"上下文总会满, 要有办法腾地方"* — 三层压缩策略, 换来无限会话 +> **s06**   *"上下文终会填满，必须学会舍弃"* — 三层压缩策略，换取理论上的无限轮次对话。 > -> **s07**   *"大目标要拆成小任务, 排好序, 记在磁盘上"* — 文件持久化的任务图, 为多 agent 协作打基础 +> **s07**   *"拆解目标，排序任务，持久化至磁盘"* — 基于文件的任务依赖图，是多 Agent 协作的基石。 > -> **s08**   *"慢操作丢后台, agent 继续想下一步"* — 后台线程跑命令, 完成后注入通知 +> **s08**   *"耗时操作转后台，Agent 持续思考"* — 守护线程处理指令，完成后异步注入结果通知。 > -> **s09**   *"任务太大一个人干不完, 要能分给队友"* — 持久化队友 + 异步邮箱 +> **s09**   *"独木难支时，委派给队友"* — 构建持久化队友实体与异步信箱机制。 > -> **s10**   *"队友之间要有统一的沟通规矩"* — 一个 request-response 模式驱动所有协商 +> **s10**   *"团队协作需要统一的通讯规约"* —一套 Request-Response 模式，驱动所有复杂的协同谈判。 > -> **s11**   *"队友自己看看板, 有活就认领"* — 不需要领导逐个分配, 自组织 +> **s11**   *"能者揭榜：队友自主领受任务"* — 无需领袖逐一分配，实现任务看板的自组织演进。 > -> **s12**   *"各干各的目录, 互不干扰"* — 任务管目标, worktree 管目录, 按 ID 绑定 +> **s12**   *"目录隔离，并行不悖"* — 任务管理目标，Worktree 管理空间，通过唯一 ID 强绑定。 ---