mirror of
https://github.com/shareAI-lab/analysis_claude_code.git
synced 2026-09-22 05:13:48 +08:00
Consolidate agent harness course into 19 lessons
This commit is contained in:
Haoran
263
s17_integrated_harness/README.zh.md
Normal file
263
s17_integrated_harness/README.zh.md
Normal file
@@ -0,0 +1,263 @@
|
||||
# s17: Agent Harness 集成 — 多种机制，一个循环
|
||||
|
||||
[English](README.md) · [中文](README.zh.md) · [日本語](README.ja.md)
|
||||
|
||||
s01 → ... → s15 → [s16](../s16_mcp_plugin/) → `s17` → [s18](../s18_workflow_runtime/) → s19
|
||||
|
||||
> *"机制很多，循环一个"* — 工具、权限、记忆、任务、团队、插件都挂在同一个 while True 上。
|
||||
>
|
||||
> **Harness 层**: 集成 — 把 s01-s16 的机制放回同一个可运行系统。
|
||||
|
||||
---
|
||||
|
||||
## 问题
|
||||
|
||||
前 16 章每章只加一个机制，让每个边界都能单独观察。本章把它们接入同一个运行时。
|
||||
|
||||
一个能长期工作的 coding agent 需要同时拥有：
|
||||
|
||||
- 工具分发和权限边界
|
||||
- hooks 扩展点
|
||||
- todo 计划和任务图
|
||||
- 技能、记忆、系统 prompt 组装
|
||||
- 压缩和错误恢复
|
||||
- 后台任务和 cron 调度
|
||||
- 团队、协议、自治认领
|
||||
- 任务绑定的 worktree
|
||||
- MCP 外部工具接入
|
||||
|
||||
本章的难点在于看清楚每项功能挂在循环的哪个位置。S17 是集成检查点：先把此前组件归位，再由 s18-s19 在外层加入编排与目标闭环。
|
||||
|
||||
---
|
||||
|
||||
## 解决方案
|
||||
|
||||
|
||||
|
||||
S17 不再引入新机制，而是把前面各章的组件集成到同一个 harness：
|
||||
|
||||
```text
|
||||
用户输入
|
||||
→ 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 个工具：
|
||||
|
||||
```text
|
||||
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()` 每轮组装：
|
||||
|
||||
```text
|
||||
BUILTIN_TOOLS + connected MCP tools
|
||||
BUILTIN_HANDLERS + mcp__server__tool handlers
|
||||
```
|
||||
|
||||
所以 `connect_mcp("docs")` 后，下一轮工具池里会出现 `mcp__docs__search`。
|
||||
|
||||
### 权限和 hooks
|
||||
|
||||
权限不写死在工具执行行里，而是作为 `PreToolUse` hook：
|
||||
|
||||
```python
|
||||
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 前先跑压缩管线：
|
||||
|
||||
```text
|
||||
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 操作不会阻塞主循环：
|
||||
|
||||
```text
|
||||
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 | 新增 | 保留，作为集成工具池的一部分 |
|
||||
|
||||
---
|
||||
|
||||
## 试一下
|
||||
|
||||
```sh
|
||||
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，代码表面越来越复杂，但核心始终没变：
|
||||
|
||||
```python
|
||||
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](../s18_workflow_runtime/) — 当编排形状固定时，把它从多轮对话移入确定性、可恢复的代码。
|
||||
|
||||
<!-- translation-sync: zh@v3, en@v3, ja@v3 -->
|
||||
Reference in New Issue
Block a user