一个Agent上下文不够用claude-code-from-scratch多Agent架构Sub-Agent fork-return深度解析【免费下载链接】claude-code-from-scratchBuild your own Claude Code from scratch. Claude Code 开源了 50 万行代码读不动用 ~5000 行 TypeScript / Python 从零复现核心架构11 章分步教程带你理解 coding agent 精髓项目地址: https://gitcode.com/gh_mirrors/cl/claude-code-from-scratch用claude-code-from-scratch这个项目只需约 5000 行 TypeScript / Python 代码就能看懂多 Agent 架构的核心玩法——Sub-Agent fork-return 模式。当主 Agent 的上下文快被大任务撑爆时它会把子任务「fork」出去让一个拥有全新上下文窗口的Sub-Agent独立执行干完只把一份精简结论「return」回来。本文带你看懂这套机制的设计思想、三种内置子 Agent 类型和关键实现代码。为什么「上下文不够用」是单 Agent 的死穴先搞清楚问题出在哪。一个 Coding Agent 的本质是一个循环调用模型 → 执行工具 → 把结果塞回消息数组 → 重复。每读一个文件、每跑一次命令上下文都在膨胀。跑几十轮后会发生三件事窗口爆满API 直接报错对话中断这也是第 7 章 docs/07-context.md 做四层压缩的原因信噪比下降大量中间搜索过程淹没关键信息模型「看花了眼」成本失控每轮请求都要把全部历史重发一遍。压缩compact能治标但治不了根大任务的中间过程本就不该灌回主对话。解法只有一个字——分。这就是多 Agent 架构登场的原因。核心理解fork-return 模式的「分而治之」fork-return分叉-返回是最朴素也最实用的多 Agent 模式整个流程只有四步阶段发生了什么上下文视角Fork主 Agent 调用agent工具传入一个 task 描述主对话里只多了一条工具调用记录Execute子 Agent 用自己的干净上下文跑完整工具循环可多轮几十次搜索、读取都发生在「沙箱」里Return子 Agent 把最终文本结论作为tool_result交回主对话只增加一段摘要Forget子 Agent 实例销毁中间过程全部丢弃主上下文保持干净关键洞察主 Agent 的上下文里没有子 Agent 的搜索过程只有一份结论。子 Agent 读 50 个文件产生的噪音被天然隔离了——这不是压缩是「物理隔离」。三种内置子 Agent 类型explore / plan / general项目用一套配置文件就定义了三种职责不同的子 Agent源码见 src/subagent.ts类型工具权限职责典型场景explore只读三件套read_file、list_files、grep_search快速代码搜索尽快返回「这个函数在哪被调用」plan同 explore只读输出结构化实现方案「先别动手给我一份改造计划」️general除agent外的全部工具独立完成一个完整任务「把这段代码的测试补全」两个细节很值得品味1. 连 shell 都不给 explore。探索只需要读和搜索性不放run_shell——从工具层面直接断掉跑破坏性命令的可能比在 prompt 里叮嘱「请只跑只读命令」可靠得多。2. 子 Agent 不能再创建子 Agent。general类型的工具列表里过滤掉了agent工具防止 A 建 B、B 建 C 的递归嵌套指数级消耗 token——每层都有自己的系统提示词和消息历史实践中 1 层委派已覆盖绝大多数场景。实现关键代码走读简单到令人惊讶教学版实现里fork-return 的全部核心就两处改动。① 主循环里把agent工具单独拦下来steps/canonical/ts/agent.ts// The agent tool forks a read-only sub-agent with its own context. if (tu.name agent) { const summary await runSubAgent(task, this.client, MODEL); results.push({ type: tool_result, tool_use_id: tu.id, content: summary }); continue; }对主 Agent 来说agent就是一个返回字符串的普通工具——它甚至不知道也不需要知道背后跑了多长的循环。② 子 Agent 本体一个带新消息数组的迷你循环steps/canonical/ts/subagent.tsexport async function runSubAgent(task: string, client: Anthropic, model: string): Promisestring { const messages: Anthropic.MessageParam[] [{ role: user, content: task }]; // 全新上下文 const tools toolDefinitions.filter((t) EXPLORE_TOOLS.includes(t.name)); // 只读工具 while (true) { const reply await client.messages.create({ model, system: You are an explore sub-agent..., tools, messages }); // ...执行工具、回填结果直到没有 tool_use 为止 if (toolUses.length 0) return /* 拼接最终文本 */; } }注意这个while循环和主 Agent 的 agent loop结构完全一样——这正是整个项目的精髓Sub-Agent 本质上就是一个配置不同的 Agent 实例不同 system prompt、不同工具集、不同消息数组而不是另一套代码。生产版还加了一个优雅的outputBuffer设计子 Agent 的文本输出不直接打印而是收集到缓冲区runOnce执行完统一取走返回token 消耗也用「运行后 - 运行前」的增量汇总到父 Agent 的账本上避免重复计费。详见 docs/11-multi-agent.md。fork-return 为什么是学习多 Agent 的最佳起点生产环境的多 Agent 体系如 Claude Code 的 Coordinator 协调者、Swarm 蜂群模式允许 Agent 间对等通信、并行探索但复杂度是指数级上升的。fork-return 的优势恰好相反它把一切都简化到最坏情况也简单✅无共享状态子 Agent 上下文独立物理上不可能污染主对话✅控制流确定发任务 → 等结果没有消息队列、没有并发协调✅容错免费子 Agent 出错时返回一段错误字符串父 Agent 的 LLM 看到后自行决定重试或换策略不会崩溃。这也是为什么该项目选它作为「第 11 章」——在上下文管理、权限、Plan Mode 之后它是第一个让你感受到「架构 算法」的章节。动手跑起来一条命令看委派全过程无需 API key项目自带本地 mock 模型直接运行第 11 章 demosteps/run.mjsnode steps/run.mjs 11你会看到这样的输出you: Use a sub-agent to find out what greeting.txt says. → agent({task:Read greeting.txt and report its contents.}) The sub-agent reports greeting.txt says: hello from the subagent demo.主 Agent 没有自己读文件——它派了个子 Agent 去查拿回结论后作答。整个委派过程对应场景文件 steps/scenarios/delegate-to-subagent.json想改场景做实验可以直接对照它。进阶玩法在项目的.claude/agents/目录下放一个.md文件frontmatter 写name、description、allowed-tools正文写 prompt就能定义自定义子 Agent 类型项目级优先于用户级~/.claude/agents/——和 Claude Code 的扩展方式完全一致。写在最后回到标题的问题一个 Agent 上下文不够用怎么办claude-code-from-scratch 给出的答案是——不要试图塞进去fork 出去、拿回结论、忘掉过程。这个不足 200 行实现的模式浓缩了多 Agent 架构最本质的三件事上下文隔离、职责划分工具权限即职责、以及「子 Agent 只是一个配置不同的 Agent」的复用思想。想动手复现整个教程把仓库拉下来跟着 13 章走一遍即可git clone https://gitcode.com/gh_mirrors/cl/claude-code-from-scratch想深入理解上下文压缩如何与 fork-return 配合、或者 Coordinator 模式的 4 阶段工作流可以从 docs/11-multi-agent.md 和 docs/07-context.md 继续读起。【免费下载链接】claude-code-from-scratchBuild your own Claude Code from scratch. Claude Code 开源了 50 万行代码读不动用 ~5000 行 TypeScript / Python 从零复现核心架构11 章分步教程带你理解 coding agent 精髓项目地址: https://gitcode.com/gh_mirrors/cl/claude-code-from-scratch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考