同一个能力有三种用法：敲命令、写脚本调命令、在程序里调 SDK。 差别不在能不能干，在能看见多少、能控制多少。 六个控制点排下来，SDK 能五项，敲命令只有两项。它不是更强的 CLI，是把能力装进你的程序。
第 7 章讲的是「怎么让它跑起来」，这一章讲「怎么把它装进别的东西里」。 这一节先定坐标：SDK 到底在哪儿，它替代了什么、没替代什么。
一、三种用法的位置
直接敲命令：人在终端里，一次对话，结果看屏幕。 脚本调命令：脚本里拼一条命令，读标准输出。 程序调 SDK：在你的程序里调函数，拿一串事件。
三种不是「新旧」关系，它们各自都有最合适的场合。 判断的依据是「一次能拿到什么」：一次对话、一条输出、还是一串事件。
二、控制点逐个对照
一次跑一个任务：三种都能。这是基本能力。 拿中间事件：脚本能（读流式输出），SDK 能，敲命令不行。 自己定义工具：只有 SDK 能。命令行只能挂 MCP 服务器。
控制会话：脚本和 SDK 能，敲命令不行（每次都是从零开始）。 嵌进已有程序：只有 SDK 能。 不用装依赖：前两种能，SDK 不能。
六项里 SDK 能五项，唯一不能的是「不装依赖」——这一项恰好是前两种的全部优势。
三、从工具到构造
敲命令的时候，你用的是别人造好的东西：它怎么循环、怎么调工具，你改不了。 用 SDK 的时候，循环和工具调度有一部分交到你手里：你能决定给它哪些工具、什么时候停。 所以「从工具到构造」的意思是：你从使用者变成了装配者。
代价也在这儿：装配错了，是装配的人负责。这是这一章所有注意事项的源头。
四、什么时候不需要 SDK
一天跑两次、看看结果就完——CLI 更好。装依赖、写代码，全是为「反复调用」付的成本。 判据：这件事会不会被别的程序调用？会，才值得上 SDK。 这和 7.11 节那个判据是同一条，只是换了个角度说：一个从「谁调」看，一个从「拿到什么」看。
五、这一章的路
8.2 到 8.3 讲接口：query 怎么调、消息长什么样。 8.4 到 8.5 讲控制：选项怎么配、会话怎么续。 8.6 到 8.9 讲扩展与约束：自定义工具、钩子、四道防线、结构化输出。
8.10 到 8.11 收口：一个 Web 服务，以及 CLI 与 SDK 怎么选。 顺序是「先会用，再会控，最后会约束」——这也是自己动手时的顺序。
六、动手 Demo：三种用法，各自能拿到什么控制点
同一个能力，有三种用法：直接敲命令、写脚本调命令、在程序里调 SDK。 它们的差别不是「能不能干」，是「你能看见多少、能控制多少」。
CAPS = [(u"一次跑一个任务", 1, 0, 1),
(u"拿中间事件（每次工具调用）", 0, 1, 1),
(u"自己定义工具", 0, 0, 1),
(u"不用装依赖", 1, 1, 0)]
实跑输出：
--------------------------------------------------------------------
三种用法，各自能拿到什么控制点
--------------------------------------------------------------------
同一个能力，有三种用法：直接敲命令、写脚本调命令、在程序里调 SDK。
它们的差别不是「能不能干」，是「你能看见多少、能控制多少」。
① 三种用法的位置
--------------------------------------------------------------------
| 用法 | 谁在调 | 一次拿到什么 | 结果交给谁 |
|---|---|---|---|
| 直接敲命令 | 人在终端里 | 一次对话 | 看屏幕 |
| 脚本调命令 | 脚本里 | 一条命令一个结果 | 读标准输出 |
| 程序调 SDK | 你的程序里 | 一串事件 | 接回调 |
② 控制点逐个对照
--------------------------------------------------------------------
| 控制点 | 直接敲命令 | 脚本调命令 | 程序调 SDK |
|---|:---:|:---:|:---:|
| 一次跑一个任务 | 能 | 不能 | 能 |
| 拿中间事件（每次工具调用） | 不能 | 能 | 能 |
| 自己定义工具 | 不能 | 不能 | 能 |
| 控制会话（续、分支） | 不能 | 能 | 能 |
| 嵌进已有程序 | 不能 | 不能 | 能 |
| 不用装依赖 | 能 | 能 | 不能 |
程序调 SDK 这一列六项里能五项，唯一不能的是「不用装依赖」。
直接敲命令只有两项。这个表最能说明 SDK 的定位：
它不是「更强的 CLI」，是「把同一个能力装进你的程序」。
③ 从工具到构造
--------------------------------------------------------------------
敲命令的时候，你用的是别人造好的东西：它怎么循环、怎么调工具，你改不了。
用 SDK 的时候，循环和工具调度有一部分交到你手里：你可以决定给它哪些工具、什么时候停。
所以「从工具到构造」这句话的意思是：你从「使用者」变成了「装配者」。
代价也在这儿：装配错了，是装配的人负责。
④ 什么时候不需要 SDK
--------------------------------------------------------------------
一天跑两次、看看结果就完——CLI 更好。装依赖、写代码，全是为「反复调用」付的成本。
判据：这件事会不会被别的程序调用？会，才值得上 SDK。
这条和 7.11 节那个判据是同一条，只是换了个角度说。
⑤ 这一章的路
--------------------------------------------------------------------
8.2 到 8.3 讲接口：query 怎么调、消息长什么样。
8.4 到 8.5 讲控制：选项怎么配、会话怎么续。
8.6 到 8.9 讲扩展与约束：自定义工具、钩子、四道防线、结构化输出。
8.10 到 8.11 收口：一个 Web 服务，以及 CLI 与 SDK 怎么选。
! 本沙箱没有安装 SDK，这一章的代码是语义复刻；教材原码照贴并标注不执行。
①三种用法：人在终端里敲、脚本拼命令、程序里调 SDK。 判断依据是「一次能拿到什么」：一次对话、一条输出、还是一串事件。 ②六项控制点里 SDK 能五项，唯一不能的是「不用装依赖」——而这一项恰好是前两种的全部优势。 ③「从工具到构造」是说：你从使用者变成了装配者。代价是装配错了，由装配的人负责。 ④什么时候不需要 SDK：一天跑两次、看看结果就完。判据是「会不会被别的程序调用」。
30 秒实验
- 给「能看到它的每一次工具调用」加一行，三种用法的答案各是什么？ 如果只能用敲命令，有什么办法勉强做到？
- 把「不用装依赖」这一项的权重调高（比如目标机器不能联网装包），结论会怎么变？
- 拿你现在的一个脚本，逐项对一遍这张表。它其实属于哪一种用法？
常见误区
- 以为 SDK 是「更高级的 CLI」。它们是两种形状，各有最合适的场合。
- 只跑一次的任务也上 SDK。装依赖、写代码，全是为反复调用付的成本。
- 用 SDK 却仍然拼命令行字符串。那样既没拿到事件，也没省掉转义问题。
- 以为上了 SDK 就自动安全。它只是把控制权交给你，控制错了还是你负责。
- 忽略「不装依赖」这一项的价值。目标机器不能联网时，这一项就是决定性的。
自测三问（点开对答案）
1. 三种用法的分界在哪？ —— 在一次能拿到什么：一次对话、一条输出、还是一串事件。也决定了能看见多少中间过程。 2. SDK 唯一不能的一项是哪个？ —— 「不用装依赖」。这恰好是 CLI 和脚本的全部优势。 3. 「从工具到构造」是什么意思？ —— 从「用别人造好的东西」变成「把能力装进自己的程序」。代价是装配错了要自己负责。坐标定好了，下一节看第一个接口：query 函数。
- ☐ （本篇完，下一篇 8.2 核心 API：query 函数）
相关笔记
- 从 CLI 到 Agent SDK：CLI 与 SDK 的分工
- 核心 API：query 函数
- Claude Code 橙皮书 · 索引
- 🐎 Claude Code 实战 · 索引