SDK 与 CLI 能力对应
区分程序化 RPC、终端界面功能和实验性接口，并核对协议版本。
SDK 通过 JSON-RPC 使用 runtime 暴露的能力。CLI 中存在某个斜杠命令，不表示把同一命令文本发送给 SDK 会产生相同 UI 操作；有些能力有专门 RPC，有些仍只属于终端工作流。
常用能力对应
| CLI 或产品行为 | SDK 接口方向 |
|---|---|
| 新建、恢复会话 | createSession、resumeSession |
| 释放内存资源 | disconnect；destroy 已弃用 |
| 删除持久记录 | deleteSession |
| 查询历史 | getEvents |
| 中止当前请求 | abort |
| 模型选择 | 创建时 model；中途 setModel 或 rpc.model.switchTo |
| 查询当前模型 | rpc.model.getCurrent |
| 代理运行模式 | rpc.mode.get / set |
| 计划读写 | rpc.plan.read / update / delete |
| 工作区文件 | rpc.workspace.listFiles / readFile / createFile |
| 前台会话协调 | getForegroundSessionId / setForegroundSessionId |
| 登录状态、连通性 | getAuthStatus、ping、getStatus |
工具在会话配置中注册或通过支持的 registerTools 接口管理；模型列表包含能力、计费和政策信息。字段与调用签名以具体语言 SDK 类型为准，本表不是完整调用代码。
计划读写示例
const plan = await session.rpc.plan.read();
if (plan.exists) console.log(plan.content);
await session.rpc.plan.update({ content: "# Plan\n- Inspect the failing test\n" });删除使用 rpc.plan.delete。这里读写计划内容，不等于已经执行计划，也不自动打开 CLI /plan 界面。
终端独有功能
CLI 的模型/代理选择器、diff 对话框、主题、剪贴板、鼠标、屏幕阅读器和终端渲染不属于 SDK UI。SDK 应用应自己实现展示与输入，再调用对应能力。
/research、/chronicle、/review、/delegate 等完整 TUI 工作流也不能直接当作 SDK 协议方法。/plugin、/mcp、/skills 是交互管理入口；程序中加载能力使用插件、MCP与Skills配置。
会话导出 --share、--share-gist 不在 SDK 协议中。可由应用收集事件、调用 getEvents 并自行格式化，或单独使用 CLI 的导出功能；不要把获取历史等同于已经发布 gist。
实验性接口
官方把 agent 管理、Fleet、history.compact、history.clearContext、history.truncate 和 sessions.fork 列为实验性。它们分别涉及代理选择、并行工作、压缩、清空模型上下文、截断历史和分叉，不可混作“重置会话”。
例如 clearContext 还有 terminal tool 内调用等专门限制，见上下文清除。自动压缩的阈值是 0–1 的上下文使用比例，示例 0.80、0.95 不应被解释为绝对 token 数或所有版本默认值。
协议协商
当前兼容性参考写明 SDK 支持协议 v2–v3：连接 v3 使用完整支持，连接 v2 时自动把 tool.call 和 permission.request 适配到 v3 事件模型。SDK 启动时协商版本，可通过 client.getStatus() 的 protocolVersion 核对。
协议兼容不代表未来所有新特性都能在旧 runtime 使用。固定 SDK/runtime 组合、阅读具体功能的实验性说明，并在排障时同时记录包版本和协议版本。