波仔
🐎 第7章 无为而治：Headless 模式与 CI／CD 集成
📄 一句话概括

CLI 是「一次任务一条命令」，每条命令起一个进程；SDK 是「在你的程序里调函数」，进程只起一次。 实测十次任务：起十次进程五点二六秒，一次进程跑十次零点五三秒。 差的全是启动开销，业务逻辑本身是零。

📝 本章和前面几章的关系

上一节讲安全，这一节讲接口形态：同一件事，用命令调还是用代码调。 这一节有真计时，但结论的重点不在快慢——SDK 的价值在另外三处。

一、两种形状

CLI：起进程、传参数、读输出。能进任何脚本，没有依赖。 SDK：进程内调函数、拿事件。能嵌进已有程序，多一层依赖。 形状的差别决定了一件事：中间过程能不能被你的程序拿到。

CLI 只能给你最后的输出；SDK 能给你每一次工具调用、每一个中间事件。

二、真跑：十次任务，两种调法

演示里跑十次：起十次进程花五点二六秒，一次进程跑十次花零点五三秒。 差的全是进程启动——十次就多付十次，每次约半秒。 而那十次任务本身，程序自己报的耗时是零：业务逻辑在这里几乎不花时间。

所以这个十倍差距是「启动开销」被反复支付的极端例子，真实场景里模型调用占大头，差距没这么夸张。

三、SDK 真正的价值不是快

第一，能拿中间事件。CLI 只有最后的输出，SDK 能拿到每一次工具调用和它的结果。 第二，能自定义工具。你程序里的函数可以直接挂成它的工具，不用先包一个 MCP 服务器。 第三，能嵌进已有程序。不用拼命令行字符串，也就没有引号和转义那一堆事。

第三点在 Windows 上尤其明显：命令行参数的引号规则，能把人折磨一整天。

四、什么时候还用 CLI

一次性任务、要进别人的脚本、要给人手动跑——CLI 更好。它没有依赖，复制就能用。 判据：这段逻辑是被别的程序反复调用，还是被人偶尔跑一次？前者 SDK，后者 CLI。 还有一条现实考虑：CLI 出问题好排查（同一条命令能在终端里重放），SDK 出问题要加日志。

五、一个中间态

先用 CLI 把流程跑通，确认有用，再换成 SDK 嵌进去。 反过来做，容易在还没验证价值的时候先付依赖成本——而很多流程验证完发现根本不该自动化。 这个顺序和 7.12 节那四个阶段是同一个思路：每步只加一点复杂度，每步都能停。

六、动手 Demo：十次调用：起十次进程和一次进程内调十次

CLI 的用法是「一次任务一条命令」，每条命令都要起一个进程。 SDK 的用法是「在你的程序里调函数」，进程只起一次。

if "--batch" in sys.argv:
    for i in range(n):
        one(u"任务 %d" % i)        # 进程内，不重启
else:
    one(sys.argv[-1])              # 一次任务，一个进程

实跑输出：

--------------------------------------------------------------------
十次调用：起十次进程和一次进程内调十次
--------------------------------------------------------------------

  CLI 的用法是「一次任务一条命令」，每条命令都要起一个进程。
  SDK 的用法是「在你的程序里调函数」，进程只起一次。

  ① 两种形状
  --------------------------------------------------------------------
| 形状 | 怎么调 | 优点 | 代价 |
|---|---|---|---|
| CLI | 起进程、传参数、读输出 | 能进任何脚本 | 每次都要付启动开销 |
| SDK | 进程内调函数、拿事件 | 能嵌进已有程序 | 多一层依赖 |


  ② 真跑：十次任务，两种调法
  --------------------------------------------------------------------
  进程内那一次自己报的耗时：{"mode": "进程内", "n": 10, "sec": 0.0}
| 调法 | 总耗时 | 相对值 |
|---|:---:|:---:|
| 起十次进程 | 5.270 秒 | 1.00 |
| 一次进程跑十次 | 0.531 秒 | 0.10 |

  差的全是进程启动：十次就多付十次。它自己报的 0.0 秒说明业务逻辑本身几乎不耗时。
  真实场景里模型调用占大头，所以这个差距没这么夸张；但任务轻、次数多的时候，能差出一个数量级。

  ③ SDK 真正的价值不是快
  --------------------------------------------------------------------
  第一，能拿中间事件。CLI 只能拿到最后的输出，SDK 能拿到每一次工具调用。
  第二，能自定义工具。你的程序里的函数可以直接挂成它的工具，不用包成 MCP 服务器。
  第三，能嵌进已有程序。不用拼命令行字符串，也就没有引号和转义那一堆事。
  第三点在 Windows 上尤其明显：命令行参数的引号规则，能把人折磨一整天。

  ④ 什么时候还用 CLI
  --------------------------------------------------------------------
  一次性任务、要进别人的脚本、要给人手动跑——CLI 更好。它没有依赖，复制就能用。
  判据：这段逻辑是被别的程序反复调用，还是被人偶尔跑一次？前者 SDK，后者 CLI。

  ⑤ 一个中间态
  --------------------------------------------------------------------
  先用 CLI 把流程跑通，确认有用，再换成 SDK 嵌进去。反过来做，容易在还没验证价值时先付依赖成本。
  ! 这里的 sdk.py 是替身，演示的是「进程启动开销」这件事，不是真实 SDK 的接口。

①形状的差别决定一件事：中间过程能不能被你的程序拿到。CLI 只给最后的输出，SDK 能给每一次工具调用。 ②十次任务：起十次进程五点二六秒，一次进程跑十次零点五三秒。差的全是进程启动，每次约半秒。 而那十次任务本身，程序自己报的耗时是零——业务逻辑在这里几乎不花时间。 所以这个十倍是极端例子，真实场景里模型调用占大头。 ③SDK 真正的价值不是快：能拿中间事件、能自定义工具（不用先包 MCP 服务器）、 能嵌进已有程序（不用拼命令行字符串）。 第三点在 Windows 上尤其明显：命令行参数的引号规则能把人折磨一整天。

30 秒实验

  1. 把十次改成五十次，重跑一遍。两边的差距是线性拉大还是保持不变？这说明什么？
  2. 在 SDK 那条路径里加一步「每次调用前重新读一遍配置」，重跑一遍。它的优势会消失吗？
  3. 把十次任务换成每次耗时零点一秒的活，重跑一遍。这时候启动开销还重要吗？ 这说明什么场景下该换 SDK？

常见误区

  1. 为了省启动开销换 SDK。真实场景里启动开销往往不是主要成本。
  2. 用 SDK 却还拼命令行字符串。那样既不安全也没拿到事件。
  3. 直接上 SDK，不先用 CLI 验证流程有没有价值。
  4. 以为 CLI 拿不到中间结果就没办法。它可以用 stream-json，只是要多写一层解析。
  5. 忽略 Windows 的引号问题。拼命令行字符串在那边是长期的坑。
自测三问（点开对答案） 1. CLI 和 SDK 的形状差别是什么？ —— CLI 一次任务起一个进程，SDK 在你的程序里调函数。差别决定了中间过程能不能拿到。 2. SDK 真正的价值有哪三条？ —— 能拿中间事件、能自定义工具、能嵌进已有程序（不用拼命令行字符串）。 3. 什么时候该继续用 CLI？ —— 一次性任务、要进别人的脚本、要给人手动跑。判据是「被程序反复调用」还是「被人偶尔跑」。

接口形态讲完了，最后一节收口：这套东西怎么一步一步落进团队。

相关笔记