一、四条判据

会被别的程序调吗？会 → SDK。进程边界是天然的胶水，能省就省。 要中间事件吗？要 → SDK。CLI 只能给最终输出（流式要自己解析）。 要自定义工具吗？要 → SDK。CLI 只能挂 MCP 服务器，那是另一条路。

能不装依赖吗？不想装 → CLI。CLI 复制就能用，这是它唯一的、但很硬的优势。 四条里前三条指向 SDK，最后一条指向 CLI。所以选型往往是「三条对一条」的权衡。

二、真跑：六个需求逐个判

演示里六个需求：手工跑一次看报告、接工单系统、网页上点一下、记审计、调内部 API、批量巡检脚本。 结果是四个建议 SDK、两个建议 CLI。 两个 CLI 里，一个是「每天手工跑一次」（命中零条），一个是「批量巡检脚本」（命中一条）。

这个结果符合直觉：偶尔跑一次的东西，不值得为它维护一份代码。

三、一个反直觉的例子

「接到工单系统里」命中三条，但你完全可以用 CLI 加一个脚本完成。 判据说的是「倾向」，不是「规定」。分数只帮你排除明显的错误方向。 真正的决定因素往往是「谁来维护」：SDK 要人维护代码，CLI 要人维护脚本。

所以选型会上真正该问的一句是：这个东西以后谁改？他更愿意改代码还是改脚本？

四、一个中间路线

用 CLI 跑通流程，把命令固定在一个脚本里；需要更细控制时，只把那一部分换成 SDK。 这条路线的好处是「随时能停」：脚本已经能干活了，换 SDK 是优化，不是重写。 它和 7.12 节那四个阶段是同一个思路：每步只加一点复杂度，每步都能停。

反过来一步到位上 SDK，很可能在还没验证价值的时候先付了一堆工程成本。

五、本章小结

第 8 章讲 Agent SDK。十一节收在一句话上：它把同一个能力装进你的程序，让你当装配者。 8.1 定位：从「用工具」到「造东西」，代价是装配错了自己负责。 8.2 query：异步迭代器，一条一条读，不是一次给完。

8.3 消息：四种类型，result 那一条带轮数、用量、花费。 8.4 选项：分层合并，列表是替换还是追加必须先搞清楚。 8.5 会话：创建、延续、分叉；分叉是复制，不是共享。

8.6 自定义工具：装饰器生成 schema，校验信息要能指导重试。 8.7 钩子：前能拦能改，后只能记。 8.8 四道防线：模式、白名单、路径、成本，缺一道就有一类事没人管。

8.9 结构化输出：四样关键字够用，重试要有上限。 8.10 Web 服务：收、跑、回三步；逻辑留纯函数，壳可以换。 8.11 选型：四条判据是倾向不是规定，最后看的往往是「谁来维护」。

六、动手 Demo：六个需求，四条判据，看该用哪个

CLI 和 SDK 不是新旧关系，是两种形状：一个是命令，一个是库。 四个判据真跑六个需求，看分数把它们分成哪两组。

REQS = [(u"每天手工跑一次，看看报告", 0, 0, 0),
        (u"接到工单系统里，自动分析", 3, 0, 0),
        (u"要把每次工具调用记进审计", 2, 3, 0)]

score = called + events + tools
pick = u"SDK" if score >= 2 else u"CLI"

实跑输出：

--------------------------------------------------------------------
六个需求，四条判据，看该用哪个
--------------------------------------------------------------------

  CLI 和 SDK 不是新旧关系，是两种形状：一个是命令，一个是库。
  选错方向的代价不是「不好用」，是「多写一堆没人要的胶水」。

  ① 四条判据
  --------------------------------------------------------------------
| 判据 | 结论 | 理由 |
|---|---|---|
| 会被别的程序调吗 | 会 → SDK | 进程边界是天然的胶水 |
| 要中间事件吗 | 要 → SDK | CLI 只能给最终输出 |
| 要自定义工具吗 | 要 → SDK | CLI 只能挂 MCP 服务器 |
| 要装依赖吗（不想装） | 不想 → CLI | CLI 复制就能用 |


  ② 真跑：六个需求逐个判
  --------------------------------------------------------------------
| 需求 | 命中几条 | 建议 |
|---|:---:|:---:|
| 每天手工跑一次，看看报告 | 0 | CLI |
| 接到工单系统里，自动分析 | 3 | SDK |
| 要在网页上点一下出结果 | 3 | SDK |
| 要把每次工具调用记进审计 | 5 | SDK |
| 要调公司内部的 API | 5 | SDK |
| 要给团队做一个批量巡检脚本 | 1 | CLI |

  六个里 4 个建议用 SDK，2 个用 CLI。
  最后一条（批量巡检脚本）命中一条，走的还是 CLI：脚本调命令就够了，不必上库。

  ③ 一个反直觉的例子
  --------------------------------------------------------------------
  「接到工单系统里」命中三条，但你完全可以用 CLI 加一个脚本完成。
  判据说的是「倾向」，不是「规定」。分数只帮你排除明显的错误方向。
  真正的决定因素往往是「谁来维护」：SDK 要人维护代码，CLI 要人维护脚本。

  ④ 一个中间路线
  --------------------------------------------------------------------
  用 CLI 跑通流程，把命令固定在一个脚本里；需要更细控制时，只把那一部分换成 SDK。
  这条路线的好处是「随时能停」：脚本已经能干活了，换 SDK 是优化，不是重写。

  ⑤ 本章小结
  --------------------------------------------------------------------
  第 8 章讲 Agent SDK。十一节收在一句话上：它把同一个能力装进你的程序，让你当装配者。
  8.1 定位：从「用工具」到「造东西」，代价是装配错了自己负责。
  8.2 query：异步迭代器，一条一条读，不是一次给完。
  8.3 消息：四种类型，result 那一条带轮数、用量、花费。
  8.4 选项：分层合并，列表是替换还是追加必须先搞清楚。
  8.5 会话：创建、延续、分叉；分叉是复制，不是共享。
  8.6 自定义工具：装饰器生成 schema，校验信息要能指导重试。
  8.7 钩子：前能拦能改，后只能记。
  8.8 四道防线：模式、白名单、路径、成本，缺一道就有一类事没人管。
  8.9 结构化输出：四样关键字够用，重试要有上限。
  8.10 Web 服务：收、跑、回三步；逻辑留纯函数，壳可以换。
  8.11 选型：四条判据是倾向不是规定，最后看的往往是「谁来维护」。
  下一章讲把它放进真实项目：一套完整的工程化方案长什么样。
  ! 判据与分数阈值是这一课归纳的，用来排除明显错的方向，不做精确评级。

①四条判据：会被别的程序调吗、要中间事件吗、要自定义工具吗（三条指向 SDK）， 能不装依赖吗（这条指向 CLI）。 ②六个需求里四个建议 SDK、两个建议 CLI：手工跑一次那个命中零条，批量巡检脚本命中一条。 偶尔跑一次的东西，不值得为它维护一份代码。 ③分数只排除明显错的方向，不是精确评级。 「接到工单系统里」命中三条，但你完全可以用 CLI 加一个脚本完成。 ④真正的决定因素往往是「谁来维护」：SDK 要人维护代码，CLI 要人维护脚本。 中间路线是先脚本跑通，再局部换 SDK——随时能停。

30 秒实验

1. 把「会装依赖」这一项加进去（目标机器不能联网装包），重跑一遍。哪几个需求的结论会翻转？
2. 把阈值从 2 改成 3，重跑一遍。分组变了吗？这说明阈值本身有多重要？
3. 拿你手上一个真实需求，四条判据走一遍。结论和你现在的做法一样吗？不一样的话，差在哪一条？

常见误区

1. 把四条判据当成打分表。它只排除明显错的方向，不做精确评级。
2. 忽略「谁来维护」这一条。它往往比技术判据更决定最后的选择。
3. 一步到位上 SDK。很可能在还没验证价值时就先付了一堆工程成本。
4. 为了「统一技术栈」把脚本也改成 SDK。维护成本上去，收益可能为零。
5. 选完就不回头看。需求变了，判据的答案也会变，这时候该重新问一遍。

第 8 章到此收尾。下一章把这些零件装进一个真实项目，看一套完整的工程化方案长什么样。

• ☐ （本篇完，下一篇 9.1 Plugins 的定位：能力的封装与分发）

相关笔记

• 从 CLI 到 Agent SDK：CLI 那一边的形状
• 渐进式落地策略：四个落地阶段
• Claude Code 橙皮书 · 索引
• 🐎 Claude Code 实战 · 索引