codex 学习笔记

Appearance

SDK 与 IDE 集成 — 练习 ​

练习 1：使用 SDK 发起代理请求 ​

通过 SDK API 发起一个简单的代理请求，理解调用流程。

参考答案

TypeScript SDK 使用方式：

typescript
import { Codex } from 'codex-sdk';

const codex = new Codex({
    codexPathOverride: '/path/to/codex',  // 可选
    config: { model: 'o4-mini' }          // 可选配置
});

// 启动新线程
const thread = codex.startThread();

// 提交用户输入
const turn = thread.turn("创建一个 hello world 程序");

// 获取结果
const result = turn.result();
console.log(result);

// 恢复已有线程
const resumed = codex.resumeThread('thread-id-123');

Python SDK 使用方式：

python
from openai_codex import Codex, TextInput, Input

# 同步 API
codex = Codex()
thread = codex.start_thread()
handle = thread.turn(Input(items=[TextInput(content="创建一个 hello world 程序")]))

# 方式 1：等待最终结果
result = handle.result()
print(result)

# 方式 2：流式处理事件
for event in handle.events():
    print(event)

# 异步 API
import asyncio
from openai_codex import AsyncCodex

async def main():
    codex = AsyncCodex()
    thread = await codex.start_thread()
    handle = await thread.turn(Input(items=[TextInput(content="创建 hello world")]))
    result = await handle.result()

asyncio.run(main())

TypeScript SDK 内部通过 CodexExec 启动 codex exec --experimental-json 子进程，解析 JSON Lines 输出。Python SDK 直接使用 JSON-RPC 协议与 App Server 通信。

练习 2：分析 IDE 插件通信 ​

分析 IDE 插件与 Codex 后端之间的通信协议和消息格式。

参考答案

IDE 插件通过 SDK 与 Codex 后端通信，两种 SDK 使用不同的传输方式：

TypeScript SDK（VS Code 插件）：

  1. 启动 codex exec --experimental-json 子进程
  2. 通过 stdin 发送用户指令
  3. 通过 stdout 接收 JSON Lines 格式的事件流
  4. 解析每行 JSON 为 ThreadEvent（TurnStartedEvent、AgentMessageItem 等）
  5. 子进程退出表示 turn 完成

Python SDK（JetBrains 插件）：

  1. 连接到本地 App Server（守护进程或嵌入式）
  2. 通过 JSON-RPC 2.0 发送请求（ClientRequest 变体）
  3. 接收 JSON-RPC 响应和通知
  4. 支持持久连接，多个 turn 复用同一连接
  5. 使用 CodexRpcError 和 retry_on_overload() 处理错误

消息格式对比：

消息类型TypeScript SDKPython SDK
请求stdin 文本JSON-RPC 请求
响应JSON LinesJSON-RPC 响应
事件JSON LinesJSON-RPC 通知
错误JSON Lines errorCodexError 层级
连接每请求新进程持久连接

练习 3：评估 SDK API 设计 ​

从开发者体验角度评估 SDK API 的设计，识别改进点。

参考答案

从 API 设计角度的评估：

优点：

  1. 双模态 API（Python）：同步 Codex/Thread 和异步 AsyncCodex/AsyncThread 满足不同使用场景
  2. 类型安全：强类型的输入（TextInput、ImageInput、SkillInput）和输出（TurnResult、ThreadEvent）
  3. 错误层级：CodexError 的子类化设计让调用者可以精确捕获和处理特定错误
  4. 重试机制：retry_on_overload() 封装了常见的重试逻辑
  5. 简洁入口：Codex 构造器接受可选配置，startThread() 无需复杂参数

改进空间：

  1. TypeScript SDK 的进程模型：每次 turn 启动新子进程的开销较大，可考虑支持持久连接
  2. 流式 API：TypeScript SDK 缺少 Python SDK 的 events() 迭代器，无法流式处理中间事件
  3. 配置统一：TypeScript 的 CodexOptions 和 Python 的 CodexConfig 接口不完全一致
  4. 类型导出：Python SDK 的 __init__.py 导出了所有公共类型，但缺少模块化的子包

架构差异的影响：

  • Python SDK 直接使用 App Server Protocol，功能更完整（支持恢复、分叉、实时配置）
  • TypeScript SDK 通过子进程包装，功能受限于 codex exec 的能力
  • 两种架构的选择反映了各自生态的特点：Node.js 倾向于子进程隔离，Python 倾向于直接 RPC

拓展挑战 ​

  • 阅读 TypeScript SDK 的 CodexExec 实现，理解子进程管理
  • 分析 Python SDK 的 JSON-RPC 连接建立和认证流程
  • 比较 TurnHandle 和 AsyncTurnHandle 的实现差异
  • 设计一个统一的 SDK 接口规范，使两种 SDK API 更一致

出链