设计自己的mini Claude Code v3：添加支持 Sub Agent

设计自己的mini Claude Code v3：添加支持 Sub Agent 设计自己的mini Claude Code v3：添加支持 Sub Agent Modified December 26, 2025 Code block Plain Text Copy }, "plan": { "tools": ["bash", "read file"], "system prompt": "You are a planning agent..." }, } 每种代理类型定义三件事： • 什么时候用 （description）：写进 Task 工具描述，让主代理知道何时派发 • 能用什么工具 （tools）：白名单机制，explore 只能读不能写 • 怎么工作 （system prompt）：代理专属指令，聚焦单一职责 1.2 Task 工具 Code block Plain Text Copy { "name": "Task", "input schema": { "description": "短描述（3 5 词）", "prompt": "详细指令", "subagent type": "explore | code | plan" } } 主代理调用 Task 时，只需指定代理类型和任务描述，剩下的全部由框架处理。 1.3 子代理执行核心（run task） 这是整个机制的核新，核心逻辑只有 5 步： Code block Plain Text Copy def run task(inp, depth=0): 1. 构造专属 system prompt sub system = f"You are a {agent type} subagent...\n{agent config['system prompt']}" 2. 过滤可用工具 sub tools = get tools for agent(agent type) explore 只拿 bash + read file 3. 创建隔离的消息历史（关键！） sub messages = [{"role": "user", "content": prompt}] 4. 递归调用同一个 query 循环 result messages = query(sub messages, sub system, sub tools, silent=True) 5. 提取最终文本返回给主代理 return extract final text(result messages) 隔离消息历史 是灵魂：子代理看不到主对话的任何内容，也不会污染主对话。它执行完毕后，只有最终总结文本被返回——就像员工提交的工作报告，而不是把所有草稿都堆到老板桌上。 1.4 进度显示 子代理执行时，内部的工具调用不会打印到主聊天区，而是用单行进度实时更新： Code block Plain Text Copy @ Task(explore: 探索代码库)... | Read(README.md) (+3 tool uses, 2.1s) < 实时刷新 | completed: 8 tool calls in 15.2s < 最终摘要 这在v3代码中通过 silent 参数 + SubagentProgress 类实现：子代理的 query 循环不打印任何内容，而是把工具调用信息发送给进度追踪器，由它负责覆盖更新同一行。 2. 背后的思想 分而治之 + 最小知识原则 1 上下文隔离解决注意力稀释 探索代码库可能需要读 20 个文件，但重构模块只需要知道"哪些文件和认证相关"。如果所有内容都堆在一个对话里，模型很快就会"忘记"前面的内容。子代理机制让每个子任务拥有干净的上下文窗口，专注做好一件事。 2 工具白名单实现职责分离 explore 代理只能读不能写，code 代理才有写权限。这不是为了"安全"（虽然也有帮助），而是为了 引导模型行为 ：当模型知道自己只有只读工具时，它就不会尝试"顺手改一下"，而是专注于信息收集。 3 递归复用而非重复实现 子代理用的是同一个 query() 函数，只是参数不同。这意味着： •工具执行逻辑共享 •错误处理一致 •未来扩展（如添加新工具）自动生效 Claude Code、Kode Agent的设计也是如此：agent loop 被主代理和子代理共用（但隔离用各自的Context、tools） 4 结果抽象而非细节透传 子代理可能调用了 105 次工具、读了 35 个文件，但返回给主代理的只是一段详细总结文本。主代理不需要知道这些细节，它只关心"探索的结论是什么"。这就像公司里的汇报机制：CTO 不需要看每个工程师的代码提交记录，只需要看项目进度报告。 3. 与 Claude Code 、 Kode CLI的对比 机制 Claude Code 、 Kode CLI mini Claude Code v3 Agent Registry AgentConfig (type, tools, prompt, model, forkContext) AGENT TYPES dict Task Schema description, prompt, subagent type, model, resume, run in background description, prompt, subagent type Tool Filtering 白名单 + 黑名单 白名单 消息隔离 独立 messages[] 独立 sub messages[] 进度显示 折叠式进度面板 单行实时刷新 后台执行 run in background + TaskOutput 省略（同步执行） Resume transcript 存储恢复 省略 forkContext 可传递父对话上下文 省略 省略的功能（后台执行、Resume、forkContext）都是高级特性，不影响理解子代理的核心原理。v3 的目标是用最少代码展示最关键机制。 4. 典型使用场景 场景一：大型代码库探索 Code block Plain Text Copy 用户：帮我理解这个项目的架构 主代理：我来派一个探索子代理... @ Task(explore: 分析项目架构)... | completed: 12 tool calls in 18.3s 根据探索结果，这个项目是一个... 场景二：规划后执行 Code block Plain Text Copy 用户：重构用户认证模块 主代理： 1. 先派 plan 代理分析现有代码 @ Task(plan: 分析认证模块)... 2. 根据计划，派 code 代理逐步实现 @ Task(code: 重构 auth.py)... @ Task(code: 更新测试用例)... 场景三：并行探索（概念） Code block Plain Text Copy 主代理同时派出多个 explore 子代理，分别探索不同目录 （当前 v3 是同步执行，但机制上完全支持并行） 5. 三部曲回顾 版本 核心主题 新增代码 关键洞察 v1 Model as Agent 400 行 模型是 80%，代码只是工具循环的载体 v2 结构化规划 170 行 用 Todo 工具把模型"拴"在工作流里 v3 分而治之 150 行 子代理隔离上下文，专注单一职责 三个版本加起来不到 900 行 Python，却覆盖了 Claude Code 最核心的设计思想： 1 工具循环 ：模型持续调用工具直到任务完成 2 结构化约束 ：用数据结构（Todo）引导模型行为 3 层级委派 ：复杂任务拆解为子代理独立执行 这就是"Model as Agent"的全部奥秘—— 没有魔法，只有清晰的工程设计 。 完整代码见仓库 v3 subagent.py 。如果你想要生产级实现，欢迎使用 Kode。 欢迎在评论区、群聊留言交流推广 你刚设计的垂直场景Agent CLI pip & npm包 比如， 提示词稍微改改就变成黑客版Claude Code Agent、运维Agent CLI、浏览器Agent CLI了（你正在读的这个系列文章价值1个亿） 每种代理类型定义三件事： • 什么时候用 （description）：写进 Task 工具描述，让主代理知道何时派发 • 能用什么工具 （tools）：白名单机制，explore 只能读不能写 • 怎么工作 （system prompt）：代理专属指令，聚焦单一职责 1.2 Task 工具 主代理调用 Task 时，只需指定代理类型和任务描述，剩下的全部由框架处理。 1.3 子代理执行核心（run task） 这是整个机制的核新，核心逻辑只有 5 步： 隔离消息历史 是灵魂：子代理看不到主对话的任何内容，也不会污染主对话。它执行完毕后，只有最终总结文本被返回——就像员工提交的工作报告，而不是把所有草稿都堆到老板桌上。 1.4 进度显示 子代理执行时，内部的工具调用不会打印到主聊天区，而是用单行进度实时更新： 这在v3代码中通过 silent 参数 + SubagentProgress 类实现：子代理的 query 循环不打印任何内容，而是把工具调用信息发送给进度追踪器，由它负责覆盖更新同一行。 2. 背后的思想 分而治之 + 最小知识原则 1 上下文隔离解决注意力稀释 探索代码库可能需要读 20 个文件，但重构模块只需要知道"哪些文件和认证相关"。如果所有内容都堆在一个对话里，模型很快就会"忘记"前面的内容。子代理机制让每个子任务拥有干净的上下文窗口，专注做好一件事。 2 工具白名单实现职责分离 explore 代理只能读不能写，code 代理才有写权限。这不是为了"安全"（虽然也有帮助），而是为了 引导模型行为 ：当模型知道自己只有只读工具时，它就不会尝试"顺手改一下"，而是专注于信息收集。 3 递归复用而非重复实现 子代理用的是同一个 query() 函数，只是参数不同。这意味着： •工具执行逻辑共享 •错误处理一致 •未来扩展（如添加新工具）自动生效 Claude Code、Kode Agent的设计也是如此：agent loop 被主代理和子代理共用（但隔离用各自的Context、tools） 4 结果抽象而非细节透传 子代理可能调用了 105 次工具、读了 35 个文件，但返回给主代理的只是一段详细总结文本。主代理不需要知道这些细节，它只关心"探索的结论是什么"。这就像公司里的汇报机制：CTO 不需要看每个工程师的代码提交记录，只需要看项目进度报告。 3. 与 Claude Code 、 Kode CLI的对比 3. 与 Claude Code 、 Kode CLI的对比 机制 Claude Code 、 Kode CLI mini Claude Code v3 Agent Registry AgentConfig (type, tools, prompt, model, forkContext) AGENT TYPES dict Task Schema description, prompt, subagent type, model, resume, run in background description, prompt, subagent type Tool Filtering 白名单 + 黑名单 白名单 消息隔离 独立 messages[] 独立 sub messages[] 进度显示 折叠式进度面板 单行实时刷新 后台执行 run in background + TaskOutput 省略（同步执行） Resume transcript 存储恢复 省略 forkContext 可传递父对话上下文 省略 机制 机制 Claude Code 、 Kode CLI Claude Code 、 Kode CLI mini Claude Code v3 mini Claude Code v3 Agent Registry Agent Registry AgentConfig (type, tools, prompt, model, forkContext) AgentConfig (type, tools, prompt, model, forkContext) AGENT TYPES dict AGENT TYPES dict Task Schema Task Schema description, prompt, subagent type, model, resume, run in background description, prompt, subagent type, model, resume, run in background description, prompt, subagent type description, prompt, subagent type Tool Filtering Tool Filtering 白名单 + 黑名单 白名单 + 黑名单 白名单 白名单 消息隔离 消息隔离 独立 messages[] 独立 messages[] 独立 sub messages[] 独立 sub messages[] 进度显示 进度显示 折叠式进度面板 折叠式进度面板 单行实时刷新 单行实时刷新 后台执行 后台执行 run in background + TaskOutput run in background + TaskOutput 省略（同步执行） 省略（同步执行） Resume Resume transcript 存储恢复 transcript 存储恢复 省略 省略 forkContext forkContext 可传递父对话上下文 可传递父对话上下文 省略 省略 省略的功能（后台执行、Resume、forkContext）都是高级特性，不影响理解子代理的核心原理。v3 的目标是用最少代码展示最关键机制。 4. 典型使用场景 4. 典型使用场景 场景一：大型代码库探索 场景二：规划后执行 场景三：并行探索（概念） 5. 三部曲回顾 5. 三部曲回顾 版本 核心主题 新增代码 关键洞察 v1 Model as Agent 400 行 模型是 80%，代码只是工具循环的载体 v2 结构化规划 170 行 用 Todo 工具把模型"拴"在工作流里 v3 分而治之 150 行 子代理隔离上下文，专注单一职责 版本 版本 核心主题 核心主题 新增代码 新增代码 关键洞察 关键洞察 v1 v1 Model as Agent Model as Agent 400 行 400 行 模型是 80%，代码只是工具循环的载体 模型是 80%，代码只是工具循环的载体 v2 v2 结构化规划 结构化规划 170 行 170 行 用 Todo 工具把模型"拴"在工作流里 用 Todo 工具把模型"拴"在工作流里 v3 v3 分而治之 分而治之 150 行 150 行 子代理隔离上下文，专注单一职责 子代理隔离上下文，专注单一职责 三个版本加起来不到 900 行 Python，却覆盖了 Claude Code 最核心的设计思想： 1 工具循环 ：模型持续调用工具直到任务完成 2 结构化约束 ：用数据结构（Todo）引导模型行为 3 层级委派 ：复杂任务拆解为子代理独立执行 这就是"Model as Agent"的全部奥秘—— 没有魔法，只有清晰的工程设计 。 完整代码见仓库 v3 subagent.py 。如果你想要生产级实现，欢迎使用 Kode。 欢迎在评论区、群聊留言交流推广 你刚设计的垂直场景Agent CLI pip & npm包 比如， 提示词稍微改改就变成黑客版Claude Code Agent、运维Agent CLI、浏览器Agent CLI了（你正在读的这个系列文章价值1个亿） 🔗 原文链接： https://mp.weixin.qq.com/s/dKwo2vhl... https://mp.weixin.qq.com/s/dKwo2vhl... 原创 飞鸟白菜 shareAI2025年12月25日 23:59 浙江 👋 代码是思想的投影 我们在mini claude code v2 版本让模型学会了"做计划" ——通过 Todo 工具把任务显式拆解、逐项推进 但当任务规模再大一些，比如"探索整个代码库然后重构认证模块"，单一代理就会陷入上下文膨胀的泥潭：探索时的大量文件内容、重构时的代码细节，全部堆在一个对话里，模型的注意力被稀释，效果急剧下降。 Claude Code Agent的解法是 Task 工具 ——让主代理像项目经理一样，把子任务派发给专门的"子代理"（Subagent），各自独立完成后再汇报结果。 这套机制在 Kode Agent CLI里也有完整实现，而 v3 版 mini Claude Code 则用最精简的方式复现了它的核心： 约 150 行新增代码，还原核心机制 。 运行截图如下👇 P1: 用我们随口一搓的mini Claude code分析一下Kode Agent SDK（也开源在ShareAI的GitHub上）的设计 P2: 通过Explore subagent得到初步的SDK设计分析报告 P3: 让 我们言出法随的mini Claude code 给这个SDK提一些升级设计方案 本次 Agent CLI 0 3 教学的 完整 代码地址（上过Python课的小学生就能学会口喷Agent）： https://github.com/shareAI lab/Mini Claude Code 1. 具体做了什么？ 1. 具体做了什么？ 1.1 Agent 类型注册表