644 lines
24 KiB
Markdown
644 lines
24 KiB
Markdown
# Claude Agent SDK 深度剖析
|
||
|
||
对 `@anthropic-ai/claude-agent-sdk` v0.2.29–0.2.34 的反向工程发现，以理解 `query()` 如何工作、为什么 agent teams 子代理（subagents）被终止，以及如何修复。补充了官方 SDK 参考文档。
|
||
|
||
## 架构（Architecture）
|
||
|
||
```
|
||
Agent Runner (我们的代码)
|
||
└── query() → SDK (sdk.mjs)
|
||
└── 生成 CLI 子进程 (cli.js)
|
||
└── Claude API 调用、工具执行
|
||
└── Task 工具 → 生成子代理子进程
|
||
```
|
||
|
||
SDK 以子进程形式生成 `cli.js`，带有 `--output-format stream-json --input-format stream-json --print --verbose` 标志。通信通过 stdin/stdout 上的 JSON 行进行。
|
||
|
||
`query()` 返回一个扩展了 `AsyncGenerator<SDKMessage, void>` 的 `Query` 对象。内部机制：
|
||
|
||
- SDK 以子进程形式生成 CLI，通过 stdin/stdout JSON 行通信
|
||
- SDK 的 `readMessages()` 从 CLI stdout 读取，排入内部流
|
||
- `readSdkMessages()` 异步生成器从该流中产出
|
||
- `[Symbol.asyncIterator]` 返回 `readSdkMessages()`
|
||
- 迭代器仅在 CLI 关闭 stdout 时返回 `done: true`
|
||
|
||
V1 (`query()`) 和 V2 (`createSession`/`send`/`stream`) 都使用完全相同的三层架构：
|
||
|
||
```
|
||
SDK (sdk.mjs) CLI 进程 (cli.js)
|
||
-------------- --------------------
|
||
XX Transport ------> stdin 读取器 (bd1)
|
||
(生成 cli.js) |
|
||
$X Query <------ stdout 写入器
|
||
(JSON 行) |
|
||
EZ() 递归生成器
|
||
|
|
||
Anthropic Messages API
|
||
```
|
||
|
||
## 核心代理循环 (EZ)
|
||
|
||
在 CLI 内部，代理循环是一个名为 `EZ()` 的**递归异步生成器**，而非迭代 while 循环：
|
||
|
||
```
|
||
EZ({ messages, systemPrompt, canUseTool, maxTurns, turnCount=1, ... })
|
||
```
|
||
|
||
每次调用 = 一次对 Claude 的 API 调用（一个"轮次（turn）"）。
|
||
|
||
### 每轮流程：
|
||
|
||
1. **准备消息**——裁剪上下文，必要时运行压缩（compaction）
|
||
2. **调用 Anthropic API**（通过 `mW1` 流式函数）
|
||
3. **从响应中提取 tool_use 块**
|
||
4. **分支：**
|
||
- 如果**没有 tool_use 块**→ 停止（运行停止钩子，返回）
|
||
- 如果**存在 tool_use 块** → 执行工具，递增 turnCount，递归
|
||
|
||
所有复杂逻辑——代理循环、工具执行、后台任务（background tasks）、队友（teammate）编排——都在 CLI 子进程内运行。`query()` 只是一个薄传输包装器。
|
||
|
||
## query() 选项
|
||
|
||
官方文档中的完整 `Options` 类型：
|
||
|
||
| 属性 | 类型 | 默认值 | 描述 |
|
||
|----------|------|---------|-------------|
|
||
| `abortController` | `AbortController` | `new AbortController()` | 用于取消操作的控制器 |
|
||
| `additionalDirectories` | `string[]` | `[]` | Claude 可访问的附加目录 |
|
||
| `agents` | `Record<string, AgentDefinition>` | `undefined` | 以编程方式定义子代理（不是 agent teams——无编排功能） |
|
||
| `allowDangerouslySkipPermissions` | `boolean` | `false` | 使用 `permissionMode: 'bypassPermissions'` 时必需 |
|
||
| `allowedTools` | `string[]` | 所有工具 | 允许的工具名称列表 |
|
||
| `betas` | `SdkBeta[]` | `[]` | Beta 功能（例如 `['context-1m-2025-08-07']` 用于 1M 上下文） |
|
||
| `canUseTool` | `CanUseTool` | `undefined` | 自定义工具使用权限函数 |
|
||
| `continue` | `boolean` | `false` | 继续最近的对话 |
|
||
| `cwd` | `string` | `process.cwd()` | 当前工作目录 |
|
||
| `disallowedTools` | `string[]` | `[]` | 禁用的工具名称列表 |
|
||
| `enableFileCheckpointing` | `boolean` | `false` | 启用文件更改追踪以支持回退 |
|
||
| `env` | `Dict<string>` | `process.env` | 环境变量 |
|
||
| `executable` | `'bun' \| 'deno' \| 'node'` | 自动检测 | JavaScript 运行时 |
|
||
| `fallbackModel` | `string` | `undefined` | 主模型失败时使用的模型 |
|
||
| `forkSession` | `boolean` | `false` | 恢复时，分叉到新的 session ID 而非继续原始会话 |
|
||
| `hooks` | `Partial<Record<HookEvent, HookCallbackMatcher[]>>` | `{}` | 事件钩子回调 |
|
||
| `includePartialMessages` | `boolean` | `false` | 包含部分消息事件（流式） |
|
||
| `maxBudgetUsd` | `number` | `undefined` | 查询的最大美元预算 |
|
||
| `maxThinkingTokens` | `number` | `undefined` | 思考过程的最大 token 数 |
|
||
| `maxTurns` | `number` | `undefined` | 最大对话轮次 |
|
||
| `mcpServers` | `Record<string, McpServerConfig>` | `{}` | MCP 服务器配置 |
|
||
| `model` | `string` | CLI 默认值 | 使用的 Claude 模型 |
|
||
| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | 结构化输出格式 |
|
||
| `pathToClaudeCodeExecutable` | `string` | 使用内置版本 | Claude Code 可执行文件路径 |
|
||
| `permissionMode` | `PermissionMode` | `'default'` | 权限模式 |
|
||
| `plugins` | `SdkPluginConfig[]` | `[]` | 从本地路径加载自定义插件 |
|
||
| `resume` | `string` | `undefined` | 要恢复的 session ID |
|
||
| `resumeSessionAt` | `string` | `undefined` | 在特定消息 UUID 处恢复会话 |
|
||
| `sandbox` | `SandboxSettings` | `undefined` | 沙箱行为配置 |
|
||
| `settingSources` | `SettingSource[]` | `[]`（无） | 要加载的文件系统设置。必须包含 `'project'` 才能加载 CLAUDE.md |
|
||
| `stderr` | `(data: string) => void` | `undefined` | stderr 输出回调 |
|
||
| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string }` | `undefined` | 系统提示词。使用预设可获取 Claude Code 的提示词，可选 `append` |
|
||
| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | 工具配置 |
|
||
|
||
### PermissionMode
|
||
|
||
```typescript
|
||
type PermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan';
|
||
```
|
||
|
||
### SettingSource
|
||
|
||
```typescript
|
||
type SettingSource = 'user' | 'project' | 'local';
|
||
// 'user' → ~/.claude/settings.json
|
||
// 'project' → .claude/settings.json（版本控制的）
|
||
// 'local' → .claude/settings.local.json（gitignored）
|
||
```
|
||
|
||
省略时，SDK 不加载任何文件系统设置（默认隔离）。优先级：local > project > user。编程方式提供的选项始终覆盖文件系统设置。
|
||
|
||
### AgentDefinition
|
||
|
||
以编程方式定义的子代理（不是 agent teams——这些更简单，无代理间协调）：
|
||
|
||
```typescript
|
||
type AgentDefinition = {
|
||
description: string; // 何时使用此代理
|
||
tools?: string[]; // 允许的工具（省略则继承全部）
|
||
prompt: string; // 代理的系统提示词
|
||
model?: 'sonnet' | 'opus' | 'haiku' | 'inherit';
|
||
}
|
||
```
|
||
|
||
### McpServerConfig
|
||
|
||
```typescript
|
||
type McpServerConfig =
|
||
| { type?: 'stdio'; command: string; args?: string[]; env?: Record<string, string> }
|
||
| { type: 'sse'; url: string; headers?: Record<string, string> }
|
||
| { type: 'http'; url: string; headers?: Record<string, string> }
|
||
| { type: 'sdk'; name: string; instance: McpServer } // 进程内
|
||
```
|
||
|
||
### SdkBeta
|
||
|
||
```typescript
|
||
type SdkBeta = 'context-1m-2025-08-07';
|
||
// 为 Opus 4.6、Sonnet 4.5、Sonnet 4 启用 1M token 上下文窗口
|
||
```
|
||
|
||
### CanUseTool
|
||
|
||
```typescript
|
||
type CanUseTool = (
|
||
toolName: string,
|
||
input: ToolInput,
|
||
options: { signal: AbortSignal; suggestions?: PermissionUpdate[] }
|
||
) => Promise<PermissionResult>;
|
||
|
||
type PermissionResult =
|
||
| { behavior: 'allow'; updatedInput: ToolInput; updatedPermissions?: PermissionUpdate[] }
|
||
| { behavior: 'deny'; message: string; interrupt?: boolean };
|
||
```
|
||
|
||
## SDKMessage 类型
|
||
|
||
`query()` 可以产出 16 种消息类型。官方文档展示了一个简化的 7 种联合类型，但 `sdk.d.ts` 包含完整集合：
|
||
|
||
| 类型 | 子类型 | 用途 |
|
||
|------|---------|---------|
|
||
| `system` | `init` | 会话已初始化，包含 session_id、tools、model |
|
||
| `system` | `task_notification` | 后台代理已完成/失败/停止 |
|
||
| `system` | `compact_boundary` | 对话已压缩 |
|
||
| `system` | `status` | 状态变更（例如正在压缩） |
|
||
| `system` | `hook_started` | 钩子执行已开始 |
|
||
| `system` | `hook_progress` | 钩子进度输出 |
|
||
| `system` | `hook_response` | 钩子已完成 |
|
||
| `system` | `files_persisted` | 文件已保存 |
|
||
| `assistant` | — | Claude 的响应（文本 + 工具调用） |
|
||
| `user` | — | 用户消息（内部） |
|
||
| `user` (replay) | — | 恢复时重放的用户消息 |
|
||
| `result` | `success` / `error_*` | 提示词处理轮的最终结果 |
|
||
| `stream_event` | — | 部分流式内容（当 includePartialMessages 时） |
|
||
| `tool_progress` | — | 长时间运行工具进度 |
|
||
| `auth_status` | — | 认证状态变化 |
|
||
| `tool_use_summary` | — | 前置工具使用的摘要 |
|
||
|
||
### SDKTaskNotificationMessage (sdk.d.ts:1507)
|
||
|
||
```typescript
|
||
type SDKTaskNotificationMessage = {
|
||
type: 'system';
|
||
subtype: 'task_notification';
|
||
task_id: string;
|
||
status: 'completed' | 'failed' | 'stopped';
|
||
output_file: string;
|
||
summary: string;
|
||
uuid: UUID;
|
||
session_id: string;
|
||
};
|
||
```
|
||
|
||
### SDKResultMessage (sdk.d.ts:1375)
|
||
|
||
两种变体，共享字段：
|
||
|
||
```typescript
|
||
// 两种变体共享的字段：
|
||
// uuid, session_id, duration_ms, duration_api_ms, is_error, num_turns,
|
||
// total_cost_usd, usage: NonNullableUsage, modelUsage, permission_denials
|
||
|
||
// 成功：
|
||
type SDKResultSuccess = {
|
||
type: 'result';
|
||
subtype: 'success';
|
||
result: string;
|
||
structured_output?: unknown;
|
||
// ...共享字段
|
||
};
|
||
|
||
// 错误：
|
||
type SDKResultError = {
|
||
type: 'result';
|
||
subtype: 'error_during_execution' | 'error_max_turns' | 'error_max_budget_usd' | 'error_max_structured_output_retries';
|
||
errors: string[];
|
||
// ...共享字段
|
||
};
|
||
```
|
||
|
||
result 上有用的字段：`total_cost_usd`、`duration_ms`、`num_turns`、`modelUsage`（按模型细分的 `costUSD`、`inputTokens`、`outputTokens`、`contextWindow`）。
|
||
|
||
### SDKAssistantMessage
|
||
|
||
```typescript
|
||
type SDKAssistantMessage = {
|
||
type: 'assistant';
|
||
uuid: UUID;
|
||
session_id: string;
|
||
message: APIAssistantMessage; // 来自 Anthropic SDK
|
||
parent_tool_use_id: string | null; // 非空时来自子代理
|
||
};
|
||
```
|
||
|
||
### SDKSystemMessage (init)
|
||
|
||
```typescript
|
||
type SDKSystemMessage = {
|
||
type: 'system';
|
||
subtype: 'init';
|
||
uuid: UUID;
|
||
session_id: string;
|
||
apiKeySource: ApiKeySource;
|
||
cwd: string;
|
||
tools: string[];
|
||
mcp_servers: { name: string; status: string }[];
|
||
model: string;
|
||
permissionMode: PermissionMode;
|
||
slash_commands: string[];
|
||
output_style: string;
|
||
};
|
||
```
|
||
|
||
## 轮次行为：代理何时停止与继续
|
||
|
||
### 代理停止时（不再进行 API 调用）
|
||
|
||
**1. 响应中没有 tool_use 块（主要情况）**
|
||
|
||
Claude 仅以文本响应——它判定已完成任务。API 的 `stop_reason` 将为 `"end_turn"`。SDK 不做此决定——完全由 Claude 的模型输出驱动。
|
||
|
||
**2. 超过最大轮次**——导致 `SDKResultError`，`subtype: "error_max_turns"`。
|
||
|
||
**3. 中止信号**——通过 `abortController` 用户中断。
|
||
|
||
**4. 超出预算**——`totalCost >= maxBudgetUsd` → `"error_max_budget_usd"`。
|
||
|
||
**5. 停止钩子阻止继续**——钩子返回 `{preventContinuation: true}`。
|
||
|
||
### 代理继续时（进行另一次 API 调用）
|
||
|
||
**1. 响应包含 tool_use 块（主要情况）**——执行工具，递增 turnCount，递归进入 EZ。
|
||
|
||
**2. max_output_tokens 恢复**——最多 3 次重试，附带"将工作拆分为更小片段"的上下文消息。
|
||
|
||
**3. 停止钩子阻塞错误**——错误作为上下文消息反馈，循环继续。
|
||
|
||
**4. 模型回退**——使用回退模型重试（一次性）。
|
||
|
||
### 决策表
|
||
|
||
| 条件 | 动作 | 结果类型 |
|
||
|-----------|--------|-------------|
|
||
| 响应有 `tool_use` 块 | 执行工具，递归进入 `EZ` | 继续 |
|
||
| 响应没有 `tool_use` 块 | 运行停止钩子，返回 | `success` |
|
||
| `turnCount > maxTurns` | 产出 max_turns_reached | `error_max_turns` |
|
||
| `totalCost >= maxBudgetUsd` | 产出预算错误 | `error_max_budget_usd` |
|
||
| `abortController.signal.aborted` | 产出中断消息 | 取决于上下文 |
|
||
| `stop_reason === "max_tokens"`（输出） | 使用恢复提示词最多重试 3 次 | 继续 |
|
||
| 停止钩子 `preventContinuation` | 立即返回 | `success` |
|
||
| 停止钩子阻塞错误 | 反馈错误，递归 | 继续 |
|
||
| 模型回退错误 | 使用回退模型重试（一次性） | 继续 |
|
||
|
||
## 子代理执行模式
|
||
|
||
### 情况 1：同步子代理 (`run_in_background: false`)——阻塞
|
||
|
||
父代理调用 Task 工具 → `VR()` 为子代理运行 `EZ()` → 父代理等待完整结果 → 工具结果返回给父代理 → 父代理继续。
|
||
|
||
子代理运行完整的递归 EZ 循环。父代理的工具执行通过 `await` 挂起。存在一个执行中"提升"机制：同步子代理可以通过 `Promise.race()` 与 `backgroundSignal` promise 竞争被提升为后台。
|
||
|
||
### 情况 2：后台任务 (`run_in_background: true`)——不等待
|
||
|
||
- **Bash 工具：**命令启动，工具立即返回空结果 + `backgroundTaskId`
|
||
- **Task/Agent 工具：**子代理在即发即忘（fire-and-forget）包装器 (`g01()`) 中启动，工具立即返回 `status: "async_launched"` + `outputFile` 路径
|
||
|
||
在发出 `type: "result"` 消息之前，零"等待后台任务"逻辑。当后台任务完成时，单独发出 `SDKTaskNotificationMessage`。
|
||
|
||
### 情况 3：Agent Teams (TeammateTool / SendMessage)——先结果，后轮询
|
||
|
||
团队领导者运行其正常的 EZ 循环，其中包括生成队友。当领导者的 EZ 循环完成时，发出 `type: "result"`。然后领导者进入结果后轮询循环：
|
||
|
||
```javascript
|
||
while (true) {
|
||
// 检查是否没有活跃队友且没有正在运行的任务 → 跳出
|
||
// 检查来自队友的未读消息 → 作为新提示词重新注入，重启 EZ 循环
|
||
// 如果 stdin 关闭且有活跃队友 → 注入关闭提示词
|
||
// 每 500ms 轮询
|
||
}
|
||
```
|
||
|
||
从 SDK 消费者角度看：你收到初始的 `type: "result"`，但 AsyncGenerator 可能继续产出更多消息，因为团队领导者处理队友响应并重新进入代理循环。生成器只有在所有队友都已关闭时才真正完成。
|
||
|
||
## isSingleUserTurn 问题
|
||
|
||
来自 sdk.mjs：
|
||
|
||
```javascript
|
||
QK = typeof X === "string" // isSingleUserTurn = true，当 prompt 为字符串时
|
||
```
|
||
|
||
当 `isSingleUserTurn` 为 true 且第一个 `result` 消息到达时：
|
||
|
||
```javascript
|
||
if (this.isSingleUserTurn) {
|
||
this.transport.endInput(); // 向 CLI 关闭 stdin
|
||
}
|
||
```
|
||
|
||
这触发连锁反应：
|
||
|
||
1. SDK 关闭 CLI stdin
|
||
2. CLI 检测到 stdin 关闭
|
||
3. 轮询循环看到 `D = true`（stdin 关闭）且有活跃队友
|
||
4. 注入关闭提示词 → 领导者向所有队友发送 `shutdown_request`
|
||
5. **队友在搜索中途被杀死**
|
||
|
||
关闭提示词（通过在压缩的 cli.js 中的 `BGq` 变量找到）：
|
||
|
||
```
|
||
You are running in non-interactive mode and cannot return a response
|
||
to the user until your team is shut down.
|
||
|
||
You MUST shut down your team before preparing your final response:
|
||
1. Use requestShutdown to ask each team member to shut down gracefully
|
||
2. Wait for shutdown approvals
|
||
3. Use the cleanup operation to clean up the team
|
||
4. Only then provide your final response to the user
|
||
```
|
||
|
||
### 实际问题
|
||
|
||
使用 V1 `query()` + 字符串 prompt + agent teams：
|
||
|
||
1. 领导者生成队友，他们开始搜索
|
||
2. 领导者的 EZ 循环结束（"我已经派出了团队，他们正在处理此事"）
|
||
3. 发出 `type: "result"`
|
||
4. SDK 看到 `isSingleUserTurn = true` → 立即关闭 stdin
|
||
5. 轮询循环检测到 stdin 关闭 + 活跃队友 → 注入关闭提示词
|
||
6. 领导者向所有队友发送 `shutdown_request`
|
||
7. **队友可能刚开始了 10 秒的 5 分钟搜索任务，就被要求停止**
|
||
|
||
## 修复方案：流式输入模式
|
||
|
||
不传递字符串 prompt（这会设置 `isSingleUserTurn = true`），而是传递一个 `AsyncIterable<SDKUserMessage>`：
|
||
|
||
```typescript
|
||
// 之前（对 agent teams 有问题的写法）：
|
||
query({ prompt: "do something" })
|
||
|
||
// 之后（保持 CLI 存活）：
|
||
query({ prompt: asyncIterableOfMessages })
|
||
```
|
||
|
||
当 prompt 是 `AsyncIterable` 时：
|
||
- `isSingleUserTurn = false`
|
||
- SDK 在第一个 result 后**不会**关闭 stdin
|
||
- CLI 保持活跃，继续处理
|
||
- 后台代理保持运行
|
||
- `task_notification` 消息流经迭代器
|
||
- 我们控制何时结束可迭代对象
|
||
|
||
### 额外好处：流式传入新消息
|
||
|
||
使用异步可迭代对象方案，我们可以在代理仍在工作时将新的 WhatsApp 消息推入可迭代对象。不用将消息排队直到容器退出再生成新容器，我们直接将它们流入正在运行的会话。
|
||
|
||
### 使用 Agent Teams 的预期生命周期
|
||
|
||
使用异步可迭代对象修复 (`isSingleUserTurn = false`)，stdin 保持打开，因此 CLI 永远不会触发队友检查或关闭提示词注入：
|
||
|
||
```
|
||
1. system/init → 会话已初始化
|
||
2. assistant/user → Claude 推理、工具调用、工具结果
|
||
3. ... → 更多 assistant/user 轮次（生成子代理等）
|
||
4. result #1 → 领导代理的第一次响应（捕获）
|
||
5. task_notification(s) → 后台代理完成/失败/停止
|
||
6. assistant/user → 领导代理继续（处理子代理结果）
|
||
7. result #2 → 领导代理的后续响应（捕获）
|
||
8. [iterator done] → CLI 关闭 stdout，全部完成
|
||
```
|
||
|
||
所有 result 都有意义——捕获每一个，而不仅仅是第一个。
|
||
|
||
## V1 与 V2 API
|
||
|
||
### V1：`query()`——一次性异步生成器
|
||
|
||
```typescript
|
||
const q = query({ prompt: "...", options: {...} });
|
||
for await (const msg of q) { /* 处理事件 */ }
|
||
```
|
||
|
||
- 当 `prompt` 是字符串时：`isSingleUserTurn = true` → stdin 在第一个 result 后自动关闭
|
||
- 对于多轮次：必须传递 `AsyncIterable<SDKUserMessage>` 并自行管理协调
|
||
|
||
### V2：`createSession()` + `send()` / `stream()`——持久化会话
|
||
|
||
```typescript
|
||
await using session = unstable_v2_createSession({ model: "..." });
|
||
await session.send("first message");
|
||
for await (const msg of session.stream()) { /* 事件 */ }
|
||
await session.send("follow-up");
|
||
for await (const msg of session.stream()) { /* 事件 */ }
|
||
```
|
||
|
||
- `isSingleUserTurn = false` 始终 → stdin 保持打开
|
||
- `send()` 排入异步队列 (`QX`)
|
||
- `stream()` 从同一个消息生成器产出，遇到 `result` 类型时停止
|
||
- 多轮次很自然——只需交替 `send()` / `stream()`
|
||
- V2 在内部**不**调用 V1 `query()`——两者独立创建 Transport + Query
|
||
|
||
### 对比表
|
||
|
||
| 方面 | V1 | V2 |
|
||
|--------|----|----|
|
||
| `isSingleUserTurn` | 字符串 prompt 时为 `true` | 始终 `false` |
|
||
| 多轮次 | 需要管理 `AsyncIterable` | 只需调用 `send()`/`stream()` |
|
||
| stdin 生命周期 | 第一个 result 后自动关闭 | 保持打开直到 `close()` |
|
||
| 代理循环 | 相同的 `EZ()` | 相同的 `EZ()` |
|
||
| 停止条件 | 相同 | 相同 |
|
||
| 会话持久化 | 必须向新的 `query()` 传递 `resume` | 通过 session 对象内置 |
|
||
| API 稳定性 | 稳定 | 不稳定预览（`unstable_v2_*` 前缀） |
|
||
|
||
**关键发现：轮次行为零差异。**两者使用相同的 CLI 进程、相同的 `EZ()` 递归生成器和相同的决策逻辑。
|
||
|
||
## 钩子事件
|
||
|
||
```typescript
|
||
type HookEvent =
|
||
| 'PreToolUse' // 工具执行前
|
||
| 'PostToolUse' // 工具成功执行后
|
||
| 'PostToolUseFailure' // 工具执行失败后
|
||
| 'Notification' // 通知消息
|
||
| 'UserPromptSubmit' // 用户提示词已提交
|
||
| 'SessionStart' // 会话已启动（启动/恢复/清除/压缩）
|
||
| 'SessionEnd' // 会话已结束
|
||
| 'Stop' // 代理正在停止
|
||
| 'SubagentStart' // 子代理已生成
|
||
| 'SubagentStop' // 子代理已停止
|
||
| 'PreCompact' // 对话压缩前
|
||
| 'PermissionRequest'; // 正在请求权限
|
||
```
|
||
|
||
### 钩子配置
|
||
|
||
```typescript
|
||
interface HookCallbackMatcher {
|
||
matcher?: string; // 可选的工具名称匹配器
|
||
hooks: HookCallback[];
|
||
}
|
||
|
||
type HookCallback = (
|
||
input: HookInput,
|
||
toolUseID: string | undefined,
|
||
options: { signal: AbortSignal }
|
||
) => Promise<HookJSONOutput>;
|
||
```
|
||
|
||
### 钩子返回值
|
||
|
||
```typescript
|
||
type HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput;
|
||
|
||
type AsyncHookJSONOutput = { async: true; asyncTimeout?: number };
|
||
|
||
type SyncHookJSONOutput = {
|
||
continue?: boolean;
|
||
suppressOutput?: boolean;
|
||
stopReason?: string;
|
||
decision?: 'approve' | 'block';
|
||
systemMessage?: string;
|
||
reason?: string;
|
||
hookSpecificOutput?:
|
||
| { hookEventName: 'PreToolUse'; permissionDecision?: 'allow' | 'deny' | 'ask'; updatedInput?: Record<string, unknown> }
|
||
| { hookEventName: 'UserPromptSubmit'; additionalContext?: string }
|
||
| { hookEventName: 'SessionStart'; additionalContext?: string }
|
||
| { hookEventName: 'PostToolUse'; additionalContext?: string };
|
||
};
|
||
```
|
||
|
||
### 子代理钩子（来自 sdk.d.ts）
|
||
|
||
```typescript
|
||
type SubagentStartHookInput = BaseHookInput & {
|
||
hook_event_name: 'SubagentStart';
|
||
agent_id: string;
|
||
agent_type: string;
|
||
};
|
||
|
||
type SubagentStopHookInput = BaseHookInput & {
|
||
hook_event_name: 'SubagentStop';
|
||
stop_hook_active: boolean;
|
||
agent_id: string;
|
||
agent_transcript_path: string;
|
||
agent_type: string;
|
||
};
|
||
|
||
// BaseHookInput = { session_id, transcript_path, cwd, permission_mode? }
|
||
```
|
||
|
||
## Query 接口方法
|
||
|
||
`Query` 对象 (sdk.d.ts:931)。官方文档列出以下公开方法：
|
||
|
||
```typescript
|
||
interface Query extends AsyncGenerator<SDKMessage, void> {
|
||
interrupt(): Promise<void>; // 停止当前执行（仅流式输入模式）
|
||
rewindFiles(userMessageUuid: string): Promise<void>; // 将文件恢复到消息时的状态（需要 enableFileCheckpointing）
|
||
setPermissionMode(mode: PermissionMode): Promise<void>; // 更改权限（仅流式输入模式）
|
||
setModel(model?: string): Promise<void>; // 更改模型（仅流式输入模式）
|
||
setMaxThinkingTokens(max: number | null): Promise<void>; // 更改思考 token 数（仅流式输入模式）
|
||
supportedCommands(): Promise<SlashCommand[]>; // 可用的斜杠命令
|
||
supportedModels(): Promise<ModelInfo[]>; // 可用模型
|
||
mcpServerStatus(): Promise<McpServerStatus[]>; // MCP 服务器连接状态
|
||
accountInfo(): Promise<AccountInfo>; // 已认证用户信息
|
||
}
|
||
```
|
||
|
||
在 sdk.d.ts 中存在但官方文档中未出现（可能为内部方法）：
|
||
- `streamInput(stream)`——流式传入额外用户消息
|
||
- `close()`——强制结束查询
|
||
- `setMcpServers(servers)`——动态添加/移除 MCP 服务器
|
||
|
||
## 沙箱配置
|
||
|
||
```typescript
|
||
type SandboxSettings = {
|
||
enabled?: boolean;
|
||
autoAllowBashIfSandboxed?: boolean;
|
||
excludedCommands?: string[];
|
||
allowUnsandboxedCommands?: boolean;
|
||
network?: {
|
||
allowLocalBinding?: boolean;
|
||
allowUnixSockets?: string[];
|
||
allowAllUnixSockets?: boolean;
|
||
httpProxyPort?: number;
|
||
socksProxyPort?: number;
|
||
};
|
||
ignoreViolations?: {
|
||
file?: string[];
|
||
network?: string[];
|
||
};
|
||
};
|
||
```
|
||
|
||
当 `allowUnsandboxedCommands` 为 true 时，模型可以在 Bash 工具输入中设置 `dangerouslyDisableSandbox: true`，这会回退到 `canUseTool` 权限处理器。
|
||
|
||
## MCP 服务器辅助函数
|
||
|
||
### tool()
|
||
|
||
使用 Zod schema 创建类型安全的 MCP 工具定义：
|
||
|
||
```typescript
|
||
function tool<Schema extends ZodRawShape>(
|
||
name: string,
|
||
description: string,
|
||
inputSchema: Schema,
|
||
handler: (args: z.infer<ZodObject<Schema>>, extra: unknown) => Promise<CallToolResult>
|
||
): SdkMcpToolDefinition<Schema>
|
||
```
|
||
|
||
### createSdkMcpServer()
|
||
|
||
创建进程内 MCP 服务器（我们改用 stdio 以支持子代理继承）：
|
||
|
||
```typescript
|
||
function createSdkMcpServer(options: {
|
||
name: string;
|
||
version?: string;
|
||
tools?: Array<SdkMcpToolDefinition<any>>;
|
||
}): McpSdkServerConfigWithInstance
|
||
```
|
||
|
||
## 内部机制参考
|
||
|
||
### 关键的压缩标识符 (sdk.mjs)
|
||
|
||
| 压缩名 | 用途 |
|
||
|----------|---------|
|
||
| `s_` | V1 `query()` 导出 |
|
||
| `e_` | `unstable_v2_createSession` |
|
||
| `Xx` | `unstable_v2_resumeSession` |
|
||
| `Qx` | `unstable_v2_prompt` |
|
||
| `U9` | V2 Session 类 (`send`/`stream`/`close`) |
|
||
| `XX` | ProcessTransport（生成 cli.js） |
|
||
| `$X` | Query 类（JSON 行路由、异步可迭代） |
|
||
| `QX` | AsyncQueue（输入流缓冲区） |
|
||
|
||
### 关键的压缩标识符 (cli.js)
|
||
|
||
| 压缩名 | 用途 |
|
||
|----------|---------|
|
||
| `EZ` | 核心递归代理循环（异步生成器） |
|
||
| `_t4` | 停止钩子处理器（当没有 tool_use 块时运行） |
|
||
| `PU1` | 流式工具执行器（在 API 响应期间并行） |
|
||
| `TP6` | 标准工具执行器（API 响应之后） |
|
||
| `GU1` | 单个工具执行器 |
|
||
| `lTq` | SDK 会话运行器（直接调用 EZ） |
|
||
| `bd1` | stdin 读取器（来自传输层的 JSON 行） |
|
||
| `mW1` | Anthropic API 流式调用器 |
|
||
|
||
## 关键文件
|
||
|
||
- `sdk.d.ts` — 所有类型定义（1777 行）
|
||
- `sdk-tools.d.ts` — 工具输入 schema
|
||
- `sdk.mjs` — SDK 运行时（压缩的，376KB）
|
||
- `cli.js` — CLI 可执行文件（压缩的，作为子进程运行）
|