第 16 章
SDK 的边界：它替你做了什么，你还得做什么
用了 SDK，为什么还是不如 Claude Code？
第 2 章我们问过这个问题：
自己搭的 Agent，为什么还是不如 Claude Code？
当时的答案是“三层差距”：模型、Harness、产品/上下文。
现在我们已经用 SDK 走了一遍：第 10 章接上循环，第 11 章设计工具面，第 12 章接权限，第 13 章补上下文和 Skill，第 14 章处理长任务，第 15 章加控制。
这一章把那张“三层差距”的表填满：SDK 到底替你做了什么，你还得做什么，什么时候该回到 tiny/裸 API。
16.1 先回到那个问题
三层差距，现在的状态：
| 层 | 第 2 章的说法 | 现在 |
|---|---|---|
| 模型 | 同一个模型，能力一样 | 没变；SDK 不换模型 |
| Harness | 循环、工具、权限、上下文、压缩、会话 | SDK 补上了大部分 |
| 产品/上下文 | 项目知识、评测、审批 UX、数据、部署 | SDK 基本没补 |
所以“用了 SDK 还是不如 Claude Code”，通常不是 Harness 的问题，是第三层的问题。
但也不绝对。SDK 的 Harness 是“通用 Harness”，不是“你的 Harness”；它的默认值、工具面、权限、上下文，仍然要你配。配错了，第一层也会看起来像第三层。
16.2 完整 Harness 控制矩阵
把“Harness 六问”加上扩展、观测，做成一张矩阵：
| 行为 | 机制 | tiny 里怎么写 | SDK 里怎么配 | 你仍然控制不了的 |
|---|---|---|---|---|
| 看见什么 | 上下文组装 | Context | system_prompt / setting_sources / CLAUDE.md / skills | CLI 内部怎么拼、怎么截断 |
| 能做什么 | 工具面 | ToolRegistry | tools / allowed_tools / disallowed_tools / MCP | 内置工具的内部实现 |
| 允许做什么 | 权限 | Policy | 模式 / can_use_tool / Hook / 沙箱 | CLI 权限管线的细节（只能按文档/实测） |
| 什么时候停 | 循环刹车 | max_steps | max_turns / max_budget_usd / Stop Hook | 模型自己决定“做完了” |
| 失败怎么办 | 错误/恢复 | 重试、is_error | ResultError / resume / checkpoint / PreCompact | API 宕机、CLI 崩溃 |
| 做完留下什么 | 记忆/会话 | SessionLog / Notes | resume / session_store / progress.md | transcript 的原始格式 |
| 扩展 | 工具/流程 | 自己写 | MCP / Skill / 子 Agent / Hook | 第三方 MCP 的质量 |
| 观测 | 日志/用量 | 自己打 | ResultMessage / get_context_usage() / Hook | CLI 内部 trace |
这张表比“SDK 功能清单”有用：它告诉你每个行为对应哪个旋钮，以及旋钮之外还有什么。
16.3 SDK 替你做了什么
按章节数：
- 循环（第 10 章）：进程、消息流、工具调度、错误处理；
- 内置工具（第 11 章）：Read/Write/Edit/Bash/Glob/Grep/Agent 等；
- 权限管线（第 12 章）：模式、规则、
can_use_tool、Hook、沙箱； - 上下文（第 13 章）：
system_prompt、setting_sources、CLAUDE.md、Skill； - 长任务（第 14 章）：自动压缩、
PreCompact、子 Agent、resume/checkpoint； - 控制（第 15 章）：Hook、流式、中断、结构化输出；
- CLI 版本管理：SDK 和 CLI 的兼容、协议、进程生命周期。
这些你都不用从零写。第 9 章那 550 行 tiny，在 SDK 里大部分变成了配置。
16.4 SDK 没替你做什么
- 领域工具：你的业务 API、数据库、内部系统；SDK 不知道。
- 系统提示/工作流：默认是空的；你不写，它就自由发挥。
- 项目知识：
CLAUDE.md、Skill、README；你不配setting_sources，它看不见。 - 评测：没有一组任务、没有成功标准，你只能凭感觉。
- 审批 UX：
can_use_tool只给你一个回调；按钮、超时、审计界面要自己做。 - 租户/计费：多用户、配额、账单，SDK 不管。
- UI/部署：聊天窗口、任务队列、监控、灰度，都是产品层。
- 数据：训练/检索/知识库，SDK 不提供。
一句话：SDK 把“Agent 怎么跑”标准化了，没把“你的业务怎么跑”标准化。
产品层的差距，具体一点：
| 层 | Claude Code | 你的 SDK Agent |
|---|---|---|
| UI | 终端/IDE 集成 | 自己做 |
| 审批 | 交互式确认 | can_use_tool + 你的界面 |
| 更新 | 自动更新 | 自己管 SDK/CLI 版本 |
| 遥测 | 内置 | 自己打点 |
| 多租户 | 不涉及 | 自己做隔离/配额 |
| 计费 | 订阅/API 账单 | 自己算/收 |
| 评测 | 官方持续做 | 自己建任务集 |
这些不是 SDK“没做好”，是它本来就不在 SDK 的范围里。
16.5 五个典型配置错误
如果你觉得“用了 SDK 还是不如 Claude Code”，先查这五个：
tools=[]或工具面过窄。 Agent 看不见文件、跑不了命令，只能猜。第 11 章的工具面，先确认它“能做什么”。setting_sources=[]把CLAUDE.md/Skill 也关了。 你以为在隔离，其实是把项目知识也关了。第 13 章。system_prompt只有一句话。 没有工作流、没有完成标准、没有输出格式；模型只能按自己的习惯来。- 没有权限，或者
allowed_tools阴影掉审批。 前者是“什么都敢干”，后者是“以为有人管，其实没人管”。第 12 章。 - 没有评测。 只凭一次运行判断“好/不好”；换个 prompt 又不知道有没有变好。第 17 章会讲。
这五个里，前四个是“配置问题”，第五个是“方法问题”。配置可以照着清单改；方法要建一套评测。
把五个错误做成一次“消融”，症状会很直观：
| 去掉什么 | 预期症状 | 先看哪章 |
|---|---|---|
| 工具面 | 只能聊天，读不了文件 | 第 11 章 |
| 项目设置 | 不读 CLAUDE.md/Skill，开始猜 | 第 13 章 |
| 权限 | 改测试、跑危险命令 | 第 12 章 |
| Stop Hook | 说“完成”但没验证 | 第 15 章 |
| 评测 | 不知道改完有没有变好 | 第 17 章 |
这不是精确的实验数据，是排查顺序：先看“能不能做”，再看“知不知道”，再看“管不管得住”，最后看“有没有变好”。
16.6 十问诊断清单
下次你觉得“我的 Agent 不如 Claude Code”，按这十个问题走一遍：
上下文
- Agent 能看到项目规则吗？
CLAUDE.md加载了吗？ - 它知道“什么时候该用哪个 Skill/工具”吗？描述写清楚了吗？
工具 3. 工具面是太宽还是太窄？它选错过吗？ 4. 工具结果是太大、太脏，还是缺关键信息？
权限
5. 写/跑操作有没有审批？allowed_tools 有没有阴影回调？
6. 危险操作有没有 Hook/沙箱兜底？
停止/完成 7. 它说“完成”时，有没有验证（测试/diff/检查）？ 8. 有没有 Stop Hook 强制“没验证不许结束”？
记忆/评测
9. 长任务会不会忘约束？有没有 progress.md/压缩策略？
10. 你有没有一组固定任务，能对比“改之前/改之后”？
十个问题里，通常有三个以上能直接解释“为什么不如”。
还有三个常见误诊：
- “模型不行。” 同一模型在 Claude Code 里行，在你这里不行，先查工具面和上下文，不要先换模型。
- “SDK 不行。” 很多时候是默认值：
setting_sources没写、system_prompt空、tools太窄。先查配置，再下结论。 - “再写一版提示词。” 如果问题在工具/权限/评测，提示词改十版也没用；先定位是哪一层。
16.7 什么时候回到 tiny/裸 API
SDK 不是唯一答案。三种情况，回到更底层：
第一，你要改循环本身。 比如自定义“先计划、再执行、再反思”的多阶段循环，或者非标准的工具调度。SDK 的循环是闭源的，你只能配/扩，不能改。
第二，你要完全自定义上下文。 比如把检索、记忆、压缩做成自己的管线，不让 CLI 插手。tiny 的 Context/Compactor 更自由。
第三，你要用非 Claude 模型的原生能力。 SDK 走的是 Claude Code 的 Harness；换模型可以，但模型的 native tool use/长上下文/多模态，不一定都能透出来。裸 API 更直接。
反过来，如果你要的是“快速做一个能用的 Agent”，或者“和 Claude Code 同样的循环/工具/权限”，SDK 更划算。
一个简单的决策树：
你要改循环/上下文管线吗？
├─ 是 → tiny / 裸 API
└─ 否 → 你要 Claude Code 同款工具/权限/会话吗？
├─ 是 → SDK
└─ 否 → 看团队/生态：MCP/Skill 多不多？
├─ 多 → SDK
└─ 少 → 裸 API + 自建循环16.8 一个诊断例子
假设你的 SDK coding agent 还是不如 Claude Code。按矩阵走：
| 症状 | 可能原因 | 先改哪 |
|---|---|---|
| 它不读 README，直接改代码 | setting_sources=[]，或 system prompt 没要求 | 第 13 章：显式 ["project"]，加“先读” |
| 它改测试 | 没有权限，或 Stop 没验证 | 第 12 章：Edit(tests/**) deny；第 15 章：Stop Hook |
| 它选错工具 | 工具面太宽/描述太差 | 第 11 章：收窄 tools，改描述 |
| 它说“完成”但没跑测试 | 没有完成标准/Stop Hook | 第 15 章：Stop + 测试命令 |
| 长任务忘约束 | 没有 progress.md/压缩策略 | 第 14 章：笔记 + PreCompact |
| 换个 prompt 就变差，不知道哪个好 | 没有评测 | 第 17 章：任务集 + 指标 |
这张表不是“万能答案”，但它能让你从“感觉不对”走到“具体改哪”。
16.9 第三部分结语
到这儿，第三部分结束了。
你现在有一个用 SDK 写的 Agent：有工具面、权限、上下文、Skill、长任务、Hook。它比第 9 章的 tiny 更接近 Claude Code，但它仍然不是 Claude Code：
- 它没有 Claude Code 的产品层（UI、审批、遥测、更新）；
- 它没有你的领域数据/评测；
- 它的系统提示/工具面/权限，仍然是你配的。
SDK 把“Harness 的通用部分”给你了；剩下的“你的部分”，它替不了。
第四部分讲工程化：评测、成本、时延、可靠性、安全。这些是把“能跑”变成“敢上线”的东西。
第 17 章从评测开始：怎么用一组固定任务，判断“改之前/改之后”到底有没有变好。
本章说明 这一章没有新代码；它把第 10–15 章的机制汇总成一张“行为 × 机制 × tiny × SDK × 不能控制”的矩阵。 矩阵里的“不能控制”部分，以当前 SDK/CLI 基线为准；升级后要复验。
2026-10-21 的实测覆盖：第 10、11、12、13、15 章真跑过（SDK 0.2.168 + CLI 2.1.296 +
deepseek-flash）；第 14 章未跑（缺storage.pyfixture，且 1M 上下文下自动压缩不会在预算内触发）。矩阵里“配置存在”不等于“行为已验证”，别把这张表当成成功率数据。