abc/analysis_claude_code

Fork 0

mirror of https://github.com/shareAI-lab/analysis_claude_code.git synced 2026-09-21 21:03:38 +08:00

Files

Haoran ab35e59672 Refine course progression and runtime safety

2026-08-11 15:13:13 +08:00

11 KiB

Raw Blame History

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

English · 中文 · 日本語

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

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

Harness 层: 集成 — 把本章示例实际使用的机制放进同一个可运行系统。

问题

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

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

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

本章的难点在于看清楚每项功能挂在循环的哪个位置。S17 是集成检查点，把这个可运行示例保留的机制接入同一个 Harness。S18 在它之上加入 workflow 编排；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 包含什么

工具与分发

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

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
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 server 自己写的 description 当成授权依据。宿主维护一组精确的已知只读工具名单，其他 MCP 工具都要询问用户。文件工具越过 WORKDIR 会直接拒绝，每条 bash 命令执行前都会询问。只有前台用户轮次可以弹出交互确认；异步轮次直接拒绝需要确认的操作，不和主 CLI 争抢输入。

计划与任务

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 释放回任务板。每次调用模型前都会先读取收件箱，因此直接消息和关机请求不会被连续的 tool-use 轮次饿死。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

只有 bash 会进入后台路径。命令非零退出或 worker 抛出异常时会发出 failed 通知，不会伪装成成功完成。每条 Shell 命令都在独立进程组中运行；命令结束，或 Agent 经正常路径、SIGTERM 退出时，运行时会停止原进程组。另建 session 的进程可以离开该边界。

cron 调度器独立 daemon thread 每秒检查一次。durable 的一次性任务会先持久化为 pending_delivery，再进入队列，并保留到包含该 prompt 的模型调用成功；调用失败会放回队列，重启后也会再次入队，因此交付语义是至少一次。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() 函数中，模型不能调用。用户或宿主先检查任务所有权、assignment lease、后台工作和 Git 状态；破坏性移除需要另行取得用户确认

worktree 只改变工具的默认工作目录，用于分离 working copy，并不是安全沙箱。进程组清理也无法约束另建 session 的进程，因此删除保留为宿主操作。

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	后台 bash + 通知	同一生命周期，执行路径增加 permission hooks
cron	daemon scheduler + durable jobs	同一调度器接入集成事件循环
multi-agent	从 s15 继承	保留原子 task ownership 和任务级 `cwd`
worktree	task 可选绑定	模型创建，宿主检查并移除
MCP	新增	保留，作为集成工具池的一部分

试一下

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

可以试：

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

观察重点：

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

结束亦是开始

从 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 — 当编排形状固定时，把它从多轮对话移入确定性、可恢复的代码。

11 KiB Raw Blame History Unescape Escape