第 01 章

SDK 是什么

SDK 是什么？为什么要用代码调 Codex

这章搞清楚一件事：Codex SDK 到底是什么，跟直接敲 codex 命令有什么区别。

先讲个故事

假设你雇了一个超级程序员助手（就是 Codex），有两种方式跟它合作：

方式一：当面指挥（CLI）

你坐在终端前，敲一个命令，它干一件事，你看结果，再敲下一个命令。就像开手动挡车——你踩离合、挂挡、给油，每一步都得自己来。

方式二：写个程序指挥（SDK）

你写一段 TypeScript 代码，告诉它："先分析这个项目的代码质量，然后检查有没有安全漏洞，最后生成一份报告。" 它自己跑完全程，中间不用你盯着。就像自动驾驶——你设好目的地，坐着就行。

SDK 就是"方式二"的工具包。

真实场景：你想让 Codex 每天凌晨 3 点自动扫描代码仓库、生成报告、发到飞书群里。用 CLI 怎么搞？写 shell 脚本 + parse 文本输出 + 各种 workaround？太累了。用 SDK 几十行 TypeScript 搞定。

SDK 的核心架构

一句话版本：你的代码 → SDK → 生成 CLI 子进程 → JSONL 事件流 → 你的代码处理结果

展开说：

┌──────────────┐    生成子进程     ┌─────────────┐
│  你的 TS 代码  │ ──────────────→ │  Codex CLI   │
│  (用 SDK)     │ ←────────────── │  (Rust 二进制) │
└──────────────┘    JSONL 事件流    └─────────────┘

SDK 在背后干了什么？

帮你生成一个 Codex CLI 子进程（就是 codex exec 命令）
把你的输入通过 stdin 传进去
从 stdout 一行一行读取 JSON 事件（这就是 JSONL——每行一个 JSON 对象）
把这些事件解析好，包装成 TypeScript 类型，交给你处理

你完全不需要知道底层的 JSONL 长什么样，SDK 全帮你封装好了。但知道这个架构，出了问题你知道去哪儿排查。

什么时候该用 SDK

场景	用 CLI	用 SDK
日常写代码、改 bug	✅ 直接用，体验最好	杀鸡用牛刀
一次性脚本任务	✅ 够用	可以但没必要
自动化流水线（CI/CD）	勉强，得 parse 文本	✅ 首选，结构化输出
集成到自己的应用/服务	❌ 没法用	✅ 唯一选择
批量处理多个项目	写 shell 循环，很痛苦	✅ 一个 for 循环搞定
需要结构化数据（JSON）	❌ CLI 输出是文本	✅ 原生支持 JSON Schema
构建 AI 工具/机器人	❌	✅ 就是干这个的

经验法则：如果你要写代码来调 Codex，就用 SDK；如果你是坐在终端前手动用，就用 CLI。

四个核心概念（先混个脸熟）

在 SDK 的世界里，只有 4 个东西需要记住：

概念	类比	干什么的
Codex	App 的入口	创建实例，配置 API Key、模型等全局参数
Thread	微信聊天窗口	一个对话线程，支持多轮对话，上下文连续
Event	直播弹幕	实时事件流，告诉你 AI 正在干什么
Item	订单里的商品	AI 产出的具体东西：回复文本、执行的命令、改的文件

用代码串起来就三行：

typescriptconst codex = new Codex();                    // 创建入口
const thread = codex.startThread();            // 开一个聊天窗口
const turn = await thread.run("帮我看看代码"); // 说一句话，等结果

后面的章节会逐个展开。现在知道有这 4 个东西就够了。

小结

SDK 是用代码调 Codex 的工具包，底层就是帮你管理 CLI 子进程
CLI 适合手动用，SDK 适合写程序调
记住 4 个核心概念：Codex、Thread、Event、Item
SDK 基于 JSONL 协议通信，但你不用关心细节

下一章：安装与 Hello World — 5 分钟跑通第一个 SDK 程序。