Claude Agent SDK Bridge — Development skill for Claude Code

用 Claude Agent SDK 将订阅额度与完整 harness 接入自建聊天前端

本文记录一条自 2026-07-28 起持续运行的链路：手机上的聊天页 → 自建网关 → 家用 Mac 上的 Agent SDK → Claude Code 的 CLI 子进程。 计费走 Claude 订阅额度；运行环境是 Claude Code 的完整 harness（CLAUDE.md、MCP 工具、记忆库、session 续接、自动 compact）。 文中数字来自该链路的日志、转写与测量脚本，均标注日期；未测量的部分标注「未验证」。 基准版本：`@anthropic-ai/claude-agent-sdk` 0.3.258（内置 Claude Code 2.1.258），macOS，Node 22。

---

1. 概述

本实现的目标是在自建前端里得到与终端 Claude Code 相同的模型行为：同一份系统提示、同一份 CLAUDE.md、同一套 MCP 工具、同一种 session 与压缩机制，并且由订阅额度计费。实现方式是在本机以 Agent SDK 的 `query()` 逐轮启动 CLI 子进程，把事件流转发到前端。

全文分三部分：第 2、3 节说明 Agent SDK 与 `claude -p` 的关系、认证与计费的前提；第 4 至 9 节是实现本身（架构、`query()` 参数、事件流、权限、固定前缀、提示缓存）；第 10 至 14 节是运行期的事项（登录态、部署位置、上下文窗口、故障对照、版本）。

2. Agent SDK 与 `claude -p` 的关系与差别

以下内容核对自 SDK 包内的 `sdk.mjs`（0.3.258）与一次实测。

**同一个二进制。** SDK 包依赖一个平台包（macOS arm64 为 `@anthropic-ai/claude-agent-sdk-darwin-arm64`），其中是一份 Claude Code 二进制，版本与 SDK 对应（0.3.258 对应 2.1.258）。`query()` 启动的就是这份二进制；`pathToClaudeCodeExecutable` 可以指向另一份。它与终端里安装的 CLI 是两份文件，版本可能不同（本机终端为 2.1.266）。

**固定参数，不含 `-p`。** `query()` 对每个子进程固定传入：

--output-format stream-json --verbose --input-format stream-json

参数列表里没有 `-p` / `--print`。实测（2.1.258，stdin 为管道，仅上述三项加 `--model haiku --max-turns 1 --no-session-persistence --tools ""`）：进程以非交互方式完成一轮后退出，`system/init` 事件报 `apiKeySource: none`，即使用本机登录态。非交互模式由双向 stream-json 与非 TTY 的标准输入输出决定。

**事件格式相同。** `claude -p --output-format stream-json --verbose` 输出的每一行 JSON，与 SDK `for await` 得到的每一条消息是同一份数据；SDK 只做了按行解析与 TypeScript 类型。转写文件、session 目录、自动 compact、后台任务的退出等待、hook 超时等运行期行为也相同，因为它们都在 CLI 内。

**选项到命令行参数的映射。** 大多数选项是一对一的命令行参数：

SDK 选项	命令行参数
model / effort	--model / --effort
tools: [] / tools: [...] / tools: { type: "preset" }	--tools "" / --tools A,B / --tools default
allowedTools / disallowedTools	--allowedTools / --disallowedTools
settingSources	--setting-sources=user,project；省略时不传，CLI 取默认（全部来源）
mcpServers	--mcp-config ；进程内 server 在其中记为 `{ "typ