analysis_claude_code/s17_integrated_harness/README.zh.md

s17: Agent Harness 集成 — 多种机制，一个循环

English · 中文 · 日本語

s01 → ... → s15 → s16 → s17 → s18 → s19

"机制很多，循环一个" — 工具、权限、记忆、任务、团队、插件都挂在同一个 while True 上。

Harness 层: 集成 — 把 s01-s16 的机制放回同一个可运行系统。

---

问题

前 16 章每章只加一个机制，让每个边界都能单独观察。本章把它们接入同一个运行时。

一个能长期工作的 coding agent 需要同时拥有：

• 工具分发和权限边界
• hooks 扩展点
• todo 计划和任务图
• 技能、记忆、系统 prompt 组装
• 压缩和错误恢复
• 后台任务和 cron 调度
• 团队、协议、自治认领
• 任务绑定的 worktree
• MCP 外部工具接入

本章的难点在于看清楚每项功能挂在循环的哪个位置。S17 是集成检查点：先把此前组件归位，再由 s18-s19 在外层加入编排与目标闭环。

---

解决方案

S17 不再引入新机制，而是把前面各章的组件集成到同一个 harness：

用户输入
  → UserPromptSubmit hooks
  → cron/background 通知注入
  → context compact
  → memory + skills + MCP 状态组装 system prompt
  → LLM
  → has tool_use block?
      否 → Stop hooks → 返回
      是 → PreToolUse hooks + permission
          → TOOL_HANDLERS / MCP handlers / background dispatch
          → PostToolUse hooks
          → tool_result / task_notification 回 messages
          → 下一轮

循环仍是同一个结构：调用模型，检查响应里是否出现 tool_use block，执行工具，再把结果追加回 messages。是否继续工具轮，由响应中有没有实际的 tool_use block 决定。

---

组件在循环中的位置

位置	组件	作用
用户输入前后	UserPromptSubmit hooks	记录、注入、审计用户输入
LLM 前	cron queue	把定时触发的 prompt 注入 messages
LLM 前	background notifications	后台任务完成后以 <task_notification> 注入
LLM 前	compaction pipeline	先压大输出，再裁历史，再压旧 tool_result，必要时摘要
LLM 前	memory / skills / MCP state	组装 system prompt，让模型看到当前能力和长期上下文
LLM 调用	error recovery	429/529 重试，max_tokens 升级，prompt too long 触发 reactive compact
工具执行前	PreToolUse hooks + permission	拦截危险命令、写越界、破坏性 MCP 工具
工具分发	assemble_tool_pool	组装内置工具和 MCP 动态工具
工具执行时	background dispatch	慢 bash 操作放 daemon thread，主循环先返回占位结果
工具执行后	PostToolUse hooks	大输出告警、日志等后处理
返回循环	tool_result	每个 tool_use 对应一个 tool_result，再回到下一轮
本轮没有 tool_use / 停止时	Stop hooks	统计、清理、审计

---

code.py 包含什么

工具与分发

内置工具池包含 25 个工具：

bash, read_file, write_file, edit_file, glob
todo_write, task, load_skill, compact
create_task, list_tasks, get_task, claim_task, complete_task
schedule_cron, list_crons, cancel_cron
spawn_teammate, send_message
request_shutdown, request_plan, review_plan
create_worktree, remove_worktree
connect_mcp

assemble_tool_pool() 每轮组装：

BUILTIN_TOOLS + connected MCP tools
BUILTIN_HANDLERS + mcp__server__tool handlers

所以 connect_mcp("docs") 后，下一轮工具池里会出现 mcp__docs__search。

权限和 hooks

权限不写死在工具执行行里，而是作为 PreToolUse hook：

blocked = trigger_hooks("PreToolUse", block)
if blocked:
    results.append(tool_result(block.id, blocked))
    continue

这样 permission、log、审计都可以挂在同一个 hook 点上。Lead、一次性 subagent 和队友的工具都会先经过 PreToolUse；允许执行的调用会在 handler 返回后触发 PostToolUse。

对于 MCP 工具，hook 会读取发现阶段得到的元数据：标记为 (readOnly) 的工具可以直接运行，修改型或没有分类的工具则先询问用户。

计划与任务

S17 同时保留两层计划：

• todo_write：当前会话内的轻量计划，保存在内存中
• task graph：跨会话、可依赖、可认领的任务文件，写入 .tasks/task_*.json

前者帮助单个 Agent 不漂移；后者支撑团队协作。

两者目标相近，但实现不同：todo_write 整表替换当前会话清单，task record 则有稳定 ID 和单条生命周期更新。下面单独出现的 task 工具表示“一次性派发隔离 subagent”，不是 Task System。

子 agent 与团队

S17 有两种 delegation：

• task：一次性 subagent。独立 messages[]，中间过程丢弃，只返回最终摘要。
• spawn_teammate：持久队友线程。它按 WORK → result → IDLE 运行，不设固定的工具轮数上限；模型或分发失败会发出 error，线程清理会把未完成 assignment 释放回任务板。idle 时先等待 MessageBus 消息，只在超时后扫描就绪 task，并以原子操作最多认领一个。

一次性 subagent 解决“上下文隔离”；持久队友解决“长期并行协作”。

记忆、技能和 prompt

assemble_system_prompt(context) 每轮组装：

• 身份和工具说明
• workspace
• skills catalog
• .memory/MEMORY.md
• 已连接 MCP server

技能只在 system prompt 里放目录。完整内容通过 load_skill(name) 按需加载。

压缩和恢复

LLM 前先跑压缩管线：

tool_result_budget → snip_compact → micro_compact → compact_history

调用模型时再包一层恢复：

• 429：指数退避重试
• 529：指数退避，连续失败可切 fallback model
• max_tokens：先提高 max_tokens，再要求 continuation
• prompt too long：reactive compact 后重试

后台和 cron

慢 bash 操作不会阻塞主循环：

should_run_background → start_background_task → placeholder tool_result
后台完成 → task_notification → 下一轮注入 messages

cron 调度器独立 daemon thread 每秒检查一次。CLI 同时监听 cron_queue、Lead 收件箱和已完成的后台任务，任一事件都能自动唤醒一轮 Agent。

worktree 与 MCP

从 s15 继承的任务级 worktree 机制负责管理任务工作目录：

• pending 且未被认领的 task 可以留在主工作区，也可以通过 create_worktree(name, task_id) 绑定独立分支和目录
• 创建前会校验 task、名称、路径、分支和 Git registry；Git 命令失败后还会核对 registry 和分支状态，任何部分创建的 checkout 都保持未绑定并保留供人工恢复
• idle 队友以原子操作认领一个就绪 task，assignment 同时记录 task_id 和有效 cwd
• 队友所有文件工具都使用该 cwd；只有 task owner 能完成任务并清空 assignment
• 模型可调用的 remove_worktree(name) 工具会拒绝绑定未完成 task 的目录，并且只移除干净 checkout；已跟踪、未跟踪和已忽略文件都会阻止它。破坏性移除属于宿主操作，需要另行取得用户确认。成功移除后会清除绑定并保留分支；若 checkout 删除后的解绑持久化失败，则报告 partial success 供人工恢复

worktree 只改变工具的默认工作目录，用于分离 working copy，并不是安全沙箱。

MCP 负责外部能力：

• connect_mcp(name) 连接 mock server
• assemble_tool_pool() 把 MCP 工具组装进工具池，并拒绝规范化后的名称冲突
• 工具名统一为 mcp__server__tool

---

相对 s16 的变化

组件	s16 MCP	s17 Agent Harness 集成
工具池	内置 + MCP	内置 + MCP，补齐 s01-s15 的机制
权限	不在 s16 重点范围内	PreToolUse hook 中执行
hooks	不在 s16 重点范围内	UserPromptSubmit / PreToolUse / PostToolUse / Stop
todo	不在 s16 重点范围内	todo_write + reminder
skill	不在 s16 重点范围内	catalog in system prompt + load_skill
compact	不在 s16 重点范围内	LLM 前压缩 + compact 工具 + reactive compact
error recovery	简化 try/except	retry / max_tokens / prompt too long
background	不在 s16 重点范围内	慢操作后台线程 + task notification
cron	不在 s16 重点范围内	daemon scheduler + durable jobs
multi-agent	从 s15 继承	保留原子 task ownership 和任务级 cwd
worktree	task 可选绑定	保留安全的创建和移除语义
MCP	新增	保留，作为集成工具池的一部分

---

试一下

cd learn-claude-code
python s17_integrated_harness/code.py

可以试：

1. 检查这个仓库，告诉我哪些 Python 文件最重要。
2. 从已连接的文档中查一下 agent loop 的相关说明。
3. 请在独立的 worktree 中并行重构认证模块和登录页，修改前先把各自的计划给我看。
4. 3 分钟后提醒我开会。
5. 在后台安装依赖，同时继续阅读 README.md。

观察重点：

• 工具调用前是否经过 hooks/permission
• connect_mcp 后下一轮是否出现 MCP 工具
• 慢操作是否返回 background placeholder
• 到点是不是自动提醒开会
• 队友是否提交 plan，并在 approval 前暂停
• idle 队友是否只原子认领一个就绪 task
• 队友所有文件工具是否都切换到已认领 task 的 cwd
• 是否只有 task owner 能完成任务并清空 assignment

---

结束亦是开始

从 s01 到 s17，代码表面越来越复杂，但核心始终没变：

while True:
    response = LLM(messages, tools)
    if not has_tool_use(response.content):
        return
    results = execute_tools(response.content)
    messages.append(tool_results)

成熟 harness 的复杂性来自模型周围的协作机制。模型负责判断和行动选择，harness 负责组织环境、工具、权限、记忆、团队和外部能力。

这是课程的集成检查点：机制很多，循环一个。

下一章：s18 Workflow Runtime — 当编排形状固定时，把它从多轮对话移入确定性、可恢复的代码。