Agent Lab 机制导图

解决什么问题

模型只会输出文字，它说"我要执行命令"并不会真的执行。需要一个程序接住模型的工具调用请求，真正去执行，再把结果交回模型，让它决定下一步，直到它给出最终答复。

关键数据结构

• messages 列表：每条是 {role, content}。assistant 的 content 直接存 SDK 返回的内容块对象；工具结果是字典 {type: "tool_result", tool_use_id, content}。messages.py 负责兼容这两种写法。
• stop_reason：tool_use 表示要执行工具；max_tokens 表示输出被截断（交给错误恢复）；其他值表示答复结束。
• LEAD_MESSAGE_HISTORY：Lead 唯一的一份历史，用户输入回合和后台事件回合共用；agent_lock 保证同一时间只有一个回合在跑。

执行步骤

1. 用户输入：触发 UserPromptSubmit 回调，追加为一条 user 消息。
2. 调用模型：带上 system、messages、工具菜单 TOOLS 和 max_tokens。
3. 把模型返回的整个 content 追加为一条 assistant 消息。
4. stop_reason 不是 tool_use：触发 Stop 回调，结束本轮，打印最后一条的文字。
5. 是 tool_use：逐个执行这次返回的所有工具调用，每个结果按 tool_use_id 写成一个 tool_result。
6. 本批全部 tool_result 合成一条 user 消息追加到历史，回到第 2 步。主循环本身没有轮数上限。

解决什么问题

只给模型一个 bash，读写文件都要拼命令，容易出错，也很难做检查。把常用操作做成专门的工具，每个工具有明确的参数说明，程序按名字找到对应函数执行。

关键数据结构

• TOOLS：给模型看的工具菜单，每项有 name、description、input_schema（JSON Schema）。
• TOOL_HANDLERS：工具名到 Python 函数的字典，启动时由 configure_tools() 填充。
• 三份菜单：Lead 25 个工具，队员 10 个，子代理 5 个（SUB_TOOLS / SUB_HANDLERS）。

执行步骤

1. 模型按 schema 给出工具名和参数。
2. 在 TOOL_HANDLERS 里查函数；查不到就返回 Unknown: 工具名。
3. 用 handler(**参数) 调用；参数名对不上会抛 TypeError，转成 Error: bad argument。
4. 函数内部的文件或命令错误，也以 Error: 开头的文字返回，让模型自己修正。

五个基础工具的具体做法

• read_file：按 UTF-8 读取；可按行数截断，并注明还剩多少行没读。
• write_file：自动创建缺少的父目录，整个文件覆盖。
• edit_file：原文必须精确出现，否则报错；只替换第一处。
• glob：在工作目录内匹配，经过符号链接后仍不在目录内的结果会去掉。
• bash：用 bash -lc 执行，默认超时 120 秒；stdout 和 stderr 合并后最多保留 50000 字符；退出码非 0 时加错误标题。

解决什么问题

模型可能提出危险操作，例如删文件、提权、写到工作目录外面。执行前要判断三种结果之一：直接拒绝、直接放行、问用户。

关键数据结构

• DENY_LIST：rm -rf /、sudo、shutdown、reboot、mkfs、dd if=、> /dev/sda，按子串匹配。
• PERMISSION_RULES：每条是 {tools, check, message}。当前两条：spawn_teammate 一律需要确认；bash 命令含 rm 、> /etc/、chmod 777 需要确认。
• _unattended_turn：当前回合是否无人值守（由定时任务或团队事件触发）。

执行步骤（check_permission）

1. bash 命令命中禁止清单：直接拒绝，用户同意也不能放行。
2. write_file / edit_file 的路径解析后不在当前工作目录内：需要确认。
3. 命中 PERMISSION_RULES：需要确认。
4. 需要确认时：无人值守回合和队员线程没人可问，直接拒绝；前台回合在终端显示工具和参数，输入 y 或 yes 才放行，其他输入、Ctrl+C、输入结束都算拒绝。
5. 拒绝时把原因写成 tool_result：Permission denied due to '…'。

解决什么问题

日志、权限、提醒这类附加逻辑如果都写进主循环，循环会越来越难读。改成在几个固定时机调用登记好的函数，主循环只负责在这些时机触发。

关键数据结构

HOOKS 字典：四个事件各对应一个回调列表。当前登记（bootstrap.initialize）：

执行步骤（trigger_hooks）

1. 按登记顺序逐个调用该事件的回调。
2. 某个回调返回非 None 就停止，后面的不再调用。
3. PreToolUse 返回非 None：这次工具调用被拦下，返回值作为拒绝原因。
4. Stop 返回非 None：主循环把返回值作为新的 user 消息，继续下一轮，而不是结束。当前 Stop 回调都返回 None。
5. 队员调用时传 skip_permission=True，跳过权限回调（队员另做权限检查），日志回调照常执行；prompt_user 参数只传给权限回调。

解决什么问题

多步骤任务中，模型容易漏步骤或忘了做到哪一步。让它先列计划、边做边更新，用户也能在终端看到进度。

关键数据结构

• LEAD_TODOS：[{content, status}]，status 只能是 pending / in_progress / completed。
• rounds_since_todo：连续多少轮工具调用没有更新清单。

执行步骤

1. system prompt 要求多步骤任务先调用 todo_write 列计划。
2. 每次传完整清单，整表替换，不是增量更新。参数是字符串时先按 JSON、再按 Python 字面量解析；检查每项都有 content 和合法的 status。
3. 成功后在终端打印清单，计数清零。
4. 每完成一批工具调用，计数加 1；达到 3 时往历史里追加 <reminder>Update your todos.</reminder>，计数清零。

解决什么问题

调查一个报错可能要读十几个文件，过程全留在主历史里会占满上下文。把这类工作交给一个独立的子代理，只把结论带回来。

关键数据结构

• 子代理自己的 messages：只从一条任务描述开始。
• SUB_TOOLS / SUB_HANDLERS：bash、read_file、write_file、edit_file、glob。
• SUBAGENT_SYSTEM_PROMPT：说明在哪个目录、完成后给简短总结、不要再委派。

执行步骤

1. Lead 调用 task(description)。
2. 新建只含这条描述的历史，循环调用模型，最多 30 轮。
3. 每个工具调用同样经过 PreToolUse（含权限）和 PostToolUse 回调。
4. 模型不再调用工具就结束；取最后一条消息的文字，没有就往前找最近一条有文字的 assistant 消息。
5. 只把这段文字作为 tool_result 返回 Lead，子代理的历史全部丢弃。

解决什么问题

操作指南（例如怎么写测试、怎么部署）如果全放进 system prompt，每轮都占上下文。先只告诉模型有哪些技能，需要时再取全文。

关键数据结构

• 技能文件：workspace/skills/<目录>/SKILL.md，开头 YAML 写 name、description。
• SKILL_REGISTRY：技能名到 {name, description, content} 的字典，content 是含 YAML 头的原文。

执行步骤

1. 启动时扫描每个子目录的 SKILL.md，用 yaml.safe_load 解析文件头；缺 name 用目录名，缺 description 用第一行。
2. 全文读进内存注册表。
3. 每轮 system prompt 只放"名字：简介"目录，并说明需要时用 load_skill。
4. 模型调用 load_skill(name)，全文作为 tool_result 进入上下文；名字不对返回 Skill not found，让模型改正。

解决什么问题

对话和工具输出越积越多，请求会超出模型的上下文上限，成本也会上升。每轮调模型前先减少要发送的内容，优先使用不调用模型的办法。

关键数据结构（阈值和存放位置）

解决什么问题

新会话里 Agent 不记得用户偏好和项目背景，每次都要重说。把值得长期保留的信息存成文件，下次按需取用。

关键数据结构

• 记忆文件：.memory/<name>.md，一条记忆一个文件，文件头写 name、description、type。type 分四类：user / feedback / project / reference。
• 索引：.memory/MEMORY.md，每行"名字 + 文件名 + 简介"，每次写入记忆后自动重建。
• 合并阈值 CONSOLIDATE_THRESHOLD = 10。

解决什么问题

写死的 system prompt 不知道当前有哪些工具、记忆和技能。每轮按真实状态重新组装，同时避免内容没变也重复拼接。

关键数据结构

• context 字典：{enabled_tools, workspace, memories}，memories 是 MEMORY.md 索引。
• 缓存：_cached_lead_context_key 和 _cached_lead_system_prompt。
• 三种角色提示词：Lead（每轮组装）、队员（按名字和职责填模板）、子代理（启动时生成一次）。

执行步骤

1. collect_lead_prompt_context：读取工具名列表、工作目录、MEMORY.md 索引。
2. 用 json.dumps(sort_keys=True) 把这三样序列化成缓存键。
3. 键和上次相同就返回缓存字符串；不同才调用 build_lead_system_prompt 重新拼接。
4. Lead 提示词包含：角色和目录、可用工具、多步任务先用 todo_write、task 工具与任务系统的区别、组队前先征得用户同意、组队后结束本轮不要轮询信箱、后台和定时的用法、技能目录、记忆索引、团队和 worktree 规则。

解决什么问题

调用模型会遇到限流、服务过载、输出被截断、上下文超限。不处理的话程序直接中断，这一轮的工作也就丢了。

关键数据结构

• RecoveryState（每次进入主循环新建）：current_model、max_tokens、has_escalated、continuations、reactive_retries、consecutive_529。

执行步骤（按错误类型）

1. 429 限流：响应带 Retry-After 就按它等；否则等 min(500ms × 2ⁿ, 32s)，再加 0–25% 随机延迟，然后重试同一请求。
2. 503 / 529 过载：同样退避；连续 3 次、且配置了 FALLBACK_MODEL_ID，就切换到备用模型。成功一次计数清零。总共最多 10 次，用完抛错。
3. 输出截断（stop_reason = max_tokens）：第一次把上限从 8000 提到 64000，丢弃截断的回复重发；还被截断，就把已有文字存为 assistant、追加续写提示（照 Claude Code 原文：不道歉、不复述、从断处接着写），最多 3 次；截断处只有工具调用、没有文字时放弃。
4. 上下文超限：按错误文字识别（prompt_too_long、too many tokens、context_length_exceeded 等），执行应急压缩后重试。每次调用成功后计数清零，所以连续超限只应急一次。
5. 其他错误，或以上都失败：错误写进对话作为一条 assistant 消息，本轮结束，命令行不退出。

解决什么问题

Todo 只在内存里，也没有依赖和负责人。需要一份落盘的工作账本：程序会检查"前置任务没完成就不能开工"，进程重启后任务还在。

关键数据结构

• Task：id、subject、description、status、owner、blockedBy、worktree（S13d 加入，旧文件缺这个字段时按 None 处理）。
• 文件：.tasks/task_xxxxxxxx.json，编号必须匹配 ^task_[0-9a-f]{8}$，防止路径穿越。
• 状态流转：pending → in_progress → completed。Lead 认领时 owner 固定为 agent，模型不能自己填负责人。

执行步骤

1. create_task：在锁内用随机数生成编号（最多试 100 次防重复），只建节点，依赖为空。
2. update_task(task_id, addBlockedBy)：只允许改 pending 且无人负责的任务；整批检查不能依赖自己、依赖必须存在、从新依赖往前追溯不能回到自己（成环）；全部通过才写入。
3. claim_task：在锁内重新读文件，检查 pending、无人负责、自己手上没有别的任务、前置都已完成、worktree 绑定有效，才写入 owner 和 in_progress。
4. complete_task：检查是本人的 in_progress 任务、不在 plan 模式、目录没变，写入 completed，并报告这次新解锁了哪些任务。
5. list_tasks 每个任务只显示一行摘要；get_task 才返回完整 JSON。
6. 每次保存先写同目录的临时文件并 fsync，再用 os.replace 替换正式文件；读取时校验文件名与 id 一致、status 合法。

解决什么问题

跑测试或构建可能要几分钟，前台等待时模型什么也做不了。把明确不急着要结果的命令放到后台，先继续别的工作。

关键数据结构

• BackgroundManager：jobs（bg_0001 → tool_use_id、command、cwd、status）、results、_ready 待领取列表，一把锁保护。
• 全部只在内存中。

执行步骤

1. 模型调用 bash 并设 run_in_background=true，必须是布尔值 True，字符串 "true" 不算。
2. 先照常经过 PreToolUse 权限检查。
3. 登记作业（编号递增，固定当前任务目录），启动后台线程；立刻回一条 tool_result："[Background task bg_0001 started] The result will be collected on a later turn."
4. 线程里执行命令，超时 600 秒；退出码为 0 记 completed，否则 failed；结果放进待领取列表。
5. Lead 下一轮开头取出所有已完成作业，每个生成一段 <task_notification>（编号、状态、命令、输出前 500 字符），追加到最后一条 user 消息；取走后作业记录删除。

解决什么问题

有些工作要到某个时间再做，例如每天早上检查一次构建。不能靠用户到点手动输入，需要程序按时间把指令交给 Agent。

关键数据结构

• CronJob：id（cron_xxxxxxxx）、cron、prompt、recurring、durable。
• CronScheduler：jobs、queue（已触发、还没交给 Lead）、_last_fired（去重记录）、一把锁。
• .scheduled_tasks.json：只保存 durable 的任务定义。

执行步骤

1. schedule_cron 注册：校验 5 段（分 0–59、时 0–23、日 1–31、月 1–12、星期 0–6，0 是周日），支持 *、*/n、逗号列表、a-b 区间；prompt 不能为空；recurring、durable 必须是布尔值；最多 50 个；durable 的立即写文件。
2. 启动时加载 durable 定义，每条重新校验，坏的跳过。
3. 调度线程每秒检查一次：分、时、月必须都匹配；日和星期都有限制时，任一匹配即可（标准 cron 规则）。
4. 同一任务同一分钟只入队一次（用"年-月-日 时:分"作去重标记）；一次性任务触发后立即删除定义。
5. Lead 事件线程每 0.2 秒检查；有到期任务且 Lead 空闲（非阻塞地拿到锁），就标记为无人值守回合，把每个任务以 [Scheduled] <prompt> 追加进历史，跑一轮 Lead。