Harness 控制手册 · Claude Agent SDK 实战

六问、八个旋钮、一张检查表。

这本书讲 Claude Agent SDK，但 SDK 只是“手”；真正决定 Agent 行为的是 Harness。

这个附录把散在各章的 Harness 控制点收成一张表，方便你设计/排查时回头查。

A.1 Agent = 模型 + Harness

模型负责“下一步做什么”；Harness 负责：

给它看什么；
让它能做什么；
允许它做什么；
什么时候停；
失败怎么办；
做完留下什么。

同一个模型，换一套 Harness，成功率和成本会完全不同。第 17 章的评测、第 22–24 章的项目，都是这个结论的实例。

A.2 六问与控制面

六问	控制什么	SDK 旋钮/机制	重点章节
看见什么	上下文	`system_prompt`、`setting_sources`、`CLAUDE.md`、Skill、工具结果裁剪	6、7、13
能做什么	工具面	`tools`、`allowed_tools`、MCP、`AgentDefinition`	4、8、11
允许做什么	权限	`permission_mode`、`can_use_tool`、`PreToolUse`、`sandbox`	5、12、21
什么时候停	循环/预算	`max_turns`、`max_budget_usd`、Stop Hook、Verifier	15、18
失败怎么办	恢复	重试、`resume`、`fork_session`、checkpoint、降级	7、20
做完留下什么	状态/产物	`session_store`、patch、audit、trace、报告	7、19、21

这张表是“设计检查表”，不是“API 列表”。先填六问，再找旋钮。

A.3 八个旋钮

1. 上下文装配

常驻：system、短 CLAUDE.md、Skill 目录；
按需：Glob/Grep/Read、检索、子 Agent 摘要；
禁止：密钥、其他租户数据、无关长文。

控制手段：setting_sources 显式、工具结果裁剪、压缩、子 Agent 隔离、缓存稳定前缀。

2. 工具面

只读优先；
写/执行最小化；
工具 schema 稳定、顺序固定；
子 Agent 工具面更窄。

控制手段：tools/allowed_tools、MCP 白名单、自定义工具、AgentDefinition.tools。

3. 权限/审批/沙箱

allowed_tools 放只读；写/执行走 can_use_tool；
路径 jail、命令 deny、写白名单；
审批持久化、超时默认拒绝、理由回填；
Bash 进沙箱，allowUnsandboxedCommands=False。

控制手段：permission_mode、can_use_tool、PreToolUse、sandbox、settings deny。

4. 循环/停止

max_turns 防跑飞；
max_budget_usd 防烧钱；
Stop Hook 防“没验证就说完成”；
Verifier 用代码判“完成”。

控制手段：options + hooks + 外部 Verifier。

5. 失败/恢复

读操作可重试；写操作要幂等；
resume 前验证世界；
tool_use/tool_result 成对；
会话/文件检查点；
降级/人工接管。

控制手段：resume、fork_session、session_store、enable_file_checkpointing、重试包装。

6. 状态/产物

会话 ID、run 状态机；
patch/diff、测试输出、报告；
审计、成本、trace。

控制手段：RunStore、session store、hooks、文件 checkpoint。

7. 扩展

Hooks：拦截/脱敏/审计/注入上下文；
Skills：流程知识按需加载；
子 Agent：隔离长过程；
MCP：接内部系统。

扩展不是“功能”，是“控制点”。每加一个扩展，问它扩大了什么权限。

8. 可观测/评测

每次 run 记 turns/cost/latency/tool_calls；
固定任务集 + 确定性评分；
失败分类：模型/工具/权限/预算/环境。

控制手段：ResultMessage、trace JSONL、run_eval.py、审计日志。

A.4 SDK 能控制什么，不能控制什么

能控制：

给 CLI 的 options：模型、工具、权限、system、setting_sources、hooks、agents、sandbox、预算/轮数；
会话：resume/fork/session_store/checkpoint；
输入输出：流式、结构化输出、中断；
外围：你自己写的队列/状态机/审批/审计/评测。

不能控制：

Agent Loop 的内部实现（闭源 CLI）；
模型“怎么想”；
工具调用的具体选择（只能通过工具面/提示影响）；
底层计费/缓存实现（只能观测/适配）。

所以“Harness 控制”不是“控制模型”，是“控制模型能看见/能做/能留下的东西”。

A.5 控制强度

从弱到强：

text

提示词 < 工具面 < 权限/审批 < 沙箱 < 持久化状态/审计

只在提示词写“不要读 .env”：最弱；
不给 Read 权限/路径 deny：更强；
沙箱 + 网络关闭：更强；
审批 + 审计 + 幂等 + 状态机：可恢复、可追责。

设计时先问“最坏能造成什么”，再决定控制强度。

A.6 一张配置骨架

python

options = ClaudeAgentOptions(
    cwd=str(WORKSPACE),
    setting_sources=["project"],
    system_prompt={"type": "preset", "preset": "claude_code", "append": RULES},
    tools=["Read", "Glob", "Grep", "Edit", "Bash", "TodoWrite", "Skill", "Agent"],
    allowed_tools=["Read", "Glob", "Grep", "TodoWrite", "Skill", "Agent"],
    permission_mode="default",
    can_use_tool=policy,
    hooks={
        "PreToolUse": [HookMatcher(hooks=[audit_pre])],
        "PostToolUse": [HookMatcher(hooks=[redact_post])],
        "Stop": [HookMatcher(hooks=[require_tests])],
    },
    sandbox={"enabled": True, "allowUnsandboxedCommands": False},
    agents={"researcher": RESEARCHER},
    max_turns=12,
    max_budget_usd=0.3,
)

这张骨架不是“最佳配置”；它展示的是“每个控制点都有落点”。

A.7 怎么证明控制生效

不要“看代码觉得对”，要跑用例：

权限：让 Agent 读 .env/改测试/跑 rm -rf，应该 deny；
审批：写操作没有批准，应该不执行；超时应该拒绝；
停止：没跑测试就停，Stop Hook 应该 block；
恢复：中途 kill，resume 后不重复副作用；
脱敏：工具结果里的手机号，模型上下文/日志里应该是 ****；
审计：每个工具调用/审批都能在日志里查到；
预算：超预算后停止，不是继续跑。

第 12、15、20、21 章的失败，很多都是“以为配了，其实没生效”。控制要验证。

A.8 三个项目的 Harness 对照

coding：workspace 隔离、写白名单、Stop + Verifier、patch/audit；
research：提纲/来源预算、网络白名单、引用验证、source/claim 表；
support：只读/写分离、持久化审批、幂等、PII 脱敏、租户隔离。

它们看起来是三个业务，底层是同一套六问。

附录说明 这张手册是“设计/排查索引”，不是 API 文档；具体字段以 SDK 版本为准。