# SDK集成服务
**本文档引用的文件**
- [src/lib/sdk/client.ts](file://src/lib/sdk/client.ts)
- [src/lib/sdk/system-prompt.ts](file://src/lib/sdk/system-prompt.ts)
- [src/lib/sdk/agents-loader.ts](file://src/lib/sdk/agents-loader.ts)
- [src/lib/sdk/mcp-loader.ts](file://src/lib/sdk/mcp-loader.ts)
- [src/lib/sdk/permission-bridge.ts](file://src/lib/sdk/permission-bridge.ts)
- [src/lib/sdk/message-mapper.ts](file://src/lib/sdk/message-mapper.ts)
- [src/lib/sdk/frontmatter.ts](file://src/lib/sdk/frontmatter.ts)
- [src/lib/provider.ts](file://src/lib/provider.ts)
- [src/lib/workspace-fs.ts](file://src/lib/workspace-fs.ts)
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件面向Claude Agent SDK集成服务，系统性阐述SDK客户端封装器的设计与实现，覆盖以下主题：
- 环境变量构建：确保子进程具备正确的HOME、PATH与认证头注入
- CLI可执行文件发现机制：多路径扫描与版本管理器支持
- 多版本管理器支持：fnm/nvm/volta的bin目录扩展
- 系统提示词构建流程：五层提示词架构与动态环境注入
- 思维模式映射策略：统一Off/Auto/Max到各Provider参数的适配
- 权限控制系统：桥接SDK canUseTool与前端SSE交互
- 附件处理机制：多模态内容构建（图像/PDF/文本/二进制）
- 错误处理策略：子进程stderr日志清洗与异常上报
- API密钥管理与认证类型处理：Anthropic与第三方Provider
- 代理配置选项：会话管理、工具使用回调、MCP服务器加载
- SDK查询选项配置：附件、思维模式、IM紧凑提示等
## 项目结构
SDK集成服务位于src/lib/sdk目录，围绕“客户端封装器”为核心，辅以系统提示词、代理定义加载、MCP服务器加载、权限桥接与消息映射等模块协同工作。
```mermaid
graph TB
subgraph "SDK集成服务"
Client["client.ts
SDK客户端封装器"]
Sys["system-prompt.ts
系统提示词构建"]
Agents["agents-loader.ts
代理定义加载"]
MCP["mcp-loader.ts
MCP服务器加载"]
Perm["permission-bridge.ts
权限桥接"]
Msg["message-mapper.ts
消息映射"]
FM["frontmatter.ts
Frontmatter解析"]
Prov["provider.ts
Provider解析"]
WS["workspace-fs.ts
工作区文件系统"]
end
Client --> Sys
Client --> Agents
Client --> MCP
Client --> Perm
Client --> Prov
Client --> WS
Agents --> FM
MCP --> Client
Perm --> Msg
```
**图表来源**
- [src/lib/sdk/client.ts:1-598](file://src/lib/sdk/client.ts#L1-L598)
- [src/lib/sdk/system-prompt.ts:1-553](file://src/lib/sdk/system-prompt.ts#L1-L553)
- [src/lib/sdk/agents-loader.ts:1-53](file://src/lib/sdk/agents-loader.ts#L1-L53)
- [src/lib/sdk/mcp-loader.ts:1-80](file://src/lib/sdk/mcp-loader.ts#L1-L80)
- [src/lib/sdk/permission-bridge.ts:1-285](file://src/lib/sdk/permission-bridge.ts#L1-L285)
- [src/lib/sdk/message-mapper.ts:1-705](file://src/lib/sdk/message-mapper.ts#L1-L705)
- [src/lib/sdk/frontmatter.ts:1-99](file://src/lib/sdk/frontmatter.ts#L1-L99)
- [src/lib/provider.ts:1-201](file://src/lib/provider.ts#L1-L201)
- [src/lib/workspace-fs.ts:1-512](file://src/lib/workspace-fs.ts#L1-L512)
**章节来源**
- [src/lib/sdk/client.ts:1-598](file://src/lib/sdk/client.ts#L1-L598)
- [src/lib/sdk/system-prompt.ts:1-553](file://src/lib/sdk/system-prompt.ts#L1-L553)
- [src/lib/sdk/agents-loader.ts:1-53](file://src/lib/sdk/agents-loader.ts#L1-L53)
- [src/lib/sdk/mcp-loader.ts:1-80](file://src/lib/sdk/mcp-loader.ts#L1-L80)
- [src/lib/sdk/permission-bridge.ts:1-285](file://src/lib/sdk/permission-bridge.ts#L1-L285)
- [src/lib/sdk/message-mapper.ts:1-705](file://src/lib/sdk/message-mapper.ts#L1-L705)
- [src/lib/sdk/frontmatter.ts:1-99](file://src/lib/sdk/frontmatter.ts#L1-L99)
- [src/lib/provider.ts:1-201](file://src/lib/provider.ts#L1-L201)
- [src/lib/workspace-fs.ts:1-512](file://src/lib/workspace-fs.ts#L1-L512)
## 核心组件
- SDK客户端封装器：负责构建环境、查找CLI、组装系统提示词、映射思维模式、加载代理与MCP、注入canUseTool权限桥接、处理附件与多模态消息、设置超时与错误日志。
- 系统提示词构建器：提供基础提示词、动态环境注入、IM紧凑提示与完整提示的差异。
- 代理定义加载器：从.claude/agents目录读取Markdown文件，解析Frontmatter生成AgentDefinition。
- MCP服务器加载器：从数据库读取启用的MCP服务器，转换为SDK可识别的配置。
- 权限桥接器：将SDK canUseTool回调桥接到SSE事件，与前端决策端点协作。
- 消息映射器：将SDK消息流映射为SSE事件，支持主/子线程工具流与结果聚合。
- Provider解析器：解析模型到Provider映射，选择Anthropic或第三方Provider，处理API Key与CLI认证。
- 工作区文件系统：提供工作区路径、.claude/目录结构、上下文文件读取与迁移。
**章节来源**
- [src/lib/sdk/client.ts:217-537](file://src/lib/sdk/client.ts#L217-L537)
- [src/lib/sdk/system-prompt.ts:16-553](file://src/lib/sdk/system-prompt.ts#L16-L553)
- [src/lib/sdk/agents-loader.ts:15-52](file://src/lib/sdk/agents-loader.ts#L15-L52)
- [src/lib/sdk/mcp-loader.ts:31-79](file://src/lib/sdk/mcp-loader.ts#L31-L79)
- [src/lib/sdk/permission-bridge.ts:62-152](file://src/lib/sdk/permission-bridge.ts#L62-L152)
- [src/lib/sdk/message-mapper.ts:28-85](file://src/lib/sdk/message-mapper.ts#L28-L85)
- [src/lib/provider.ts:108-180](file://src/lib/provider.ts#L108-L180)
- [src/lib/workspace-fs.ts:32-347](file://src/lib/workspace-fs.ts#L32-L347)
## 架构总览
SDK客户端封装器通过“查询构建器”串联各子系统，形成完整的调用链路：Provider解析→环境构建→CLI发现→系统提示词→代理/MCP加载→权限桥接→多模态消息→SDK执行→消息映射→前端渲染。
```mermaid
sequenceDiagram
participant Caller as "调用方"
participant Client as "createForgeQuery(client.ts)"
participant Prov as "resolveProvider(provider.ts)"
participant Env as "buildSdkEnv(client.ts)"
participant CLI as "findClaudeExecutable(client.ts)"
participant Sys as "buildSystemPrompt(system-prompt.ts)"
participant Agents as "loadAgentsFromFiles(agents-loader.ts)"
participant MCP as "loadMcpServersFromDb(mcp-loader.ts)"
participant Perm as "createPermissionBridge(permission-bridge.ts)"
participant SDK as "query(@anthropic-ai/claude-agent-sdk)"
Caller->>Client : 传入ForgeQueryOptions
Client->>Prov : 解析Provider与认证
Prov-->>Client : 返回apiKey/baseUrl/authType
Client->>Env : 构建子进程环境变量
Client->>CLI : 查找claude可执行文件
Client->>Sys : 组装系统提示词
Client->>Agents : 加载代理定义
Client->>MCP : 加载MCP服务器配置
Client->>Perm : 创建权限桥接回调
Client->>SDK : 调用query(options)
SDK-->>Client : 流式消息/结果
Client->>Perm : 处理权限请求(SSE)
Client-->>Caller : 返回AsyncIterable/订阅
```
**图表来源**
- [src/lib/sdk/client.ts:378-537](file://src/lib/sdk/client.ts#L378-L537)
- [src/lib/provider.ts:108-180](file://src/lib/provider.ts#L108-L180)
- [src/lib/sdk/system-prompt.ts:257-300](file://src/lib/sdk/system-prompt.ts#L257-L300)
- [src/lib/sdk/agents-loader.ts:15-52](file://src/lib/sdk/agents-loader.ts#L15-L52)
- [src/lib/sdk/mcp-loader.ts:31-79](file://src/lib/sdk/mcp-loader.ts#L31-L79)
- [src/lib/sdk/permission-bridge.ts:62-152](file://src/lib/sdk/permission-bridge.ts#L62-L152)
**章节来源**
- [src/lib/sdk/client.ts:378-537](file://src/lib/sdk/client.ts#L378-L537)
## 详细组件分析
### 环境变量构建与CLI发现
- 环境变量构建要点：
- 复制当前进程环境，确保HOME存在，扩展PATH包含版本管理器bin目录，移除可能引发“嵌套会话”检测的变量，按认证类型注入API Key或Token。
- 支持Anthropic原生API Key与第三方Provider的Bearer Token两种认证头类型。
- CLI可执行文件发现机制：
- 预设候选路径（常见安装位置）+ 版本管理器扫描（fnm/nvm/volta）+ 登录Shell查询（兼容自定义PATH），带缓存与超时保护。
- 多版本管理器支持：
- 自动枚举版本bin目录加入PATH，提升跨Node版本场景下的CLI可用性。
```mermaid
flowchart TD
Start(["开始"]) --> CopyEnv["复制进程环境变量"]
CopyEnv --> EnsureHome["确保HOME存在"]
EnsureHome --> ExpandPath["扩展PATH至版本管理器bin目录"]
ExpandPath --> RemoveVar["移除可能的嵌套会话变量"]
RemoveVar --> InjectCreds{"是否提供API Key?"}
InjectCreds --> |是| SetAuth["按认证类型注入API Key/Token"]
InjectCreds --> |否| RemoveCreds["清理旧凭据CLI OAuth"]
SetAuth --> BuildEnv["返回SDK环境对象"]
RemoveCreds --> BuildEnv
BuildEnv --> FindCLI["查找claude可执行文件"]
FindCLI --> Done(["结束"])
```
**图表来源**
- [src/lib/sdk/client.ts:173-215](file://src/lib/sdk/client.ts#L173-L215)
- [src/lib/sdk/client.ts:34-116](file://src/lib/sdk/client.ts#L34-L116)
- [src/lib/sdk/client.ts:120-160](file://src/lib/sdk/client.ts#L120-L160)
**章节来源**
- [src/lib/sdk/client.ts:173-215](file://src/lib/sdk/client.ts#L173-L215)
- [src/lib/sdk/client.ts:34-116](file://src/lib/sdk/client.ts#L34-L116)
- [src/lib/sdk/client.ts:120-160](file://src/lib/sdk/client.ts#L120-L160)
### 系统提示词构建流程
- 五层系统提示词架构：
- 基础层：Forge基础提示词（工具使用、记忆、安全等）
- 动态环境层：平台、架构、Shell、Node版本、工作目录
- 工作区层：.claude/根目录下所有.md文件（除CLAUDE.md与MEMORY.md）
- 记忆层：MEMORY.md前200行 + 最近2天的每日记忆
- 规则层：.claude/rules/下的规则文件（无paths字段的无条件加载；有paths的仅列出）
- IM紧凑提示：在保持人格与用户信息一致的前提下，显著缩短提示词长度，用于即时通讯场景。
```mermaid
flowchart TD
A["输入: workspaceId"] --> B["读取工作区上下文(loadWorkspaceContext)"]
A --> C["读取记忆上下文(loadMemoryContext)"]
A --> D["读取规则上下文(loadRulesContext)"]
A --> E["获取项目路径(getProjectPath)"]
E --> F["构建动态环境(buildEnvironmentPrompt)"]
B --> G["拼接系统提示词片段"]
C --> G
D --> G
F --> G
G --> H["返回完整系统提示词"]
```
**图表来源**
- [src/lib/sdk/client.ts:257-300](file://src/lib/sdk/client.ts#L257-L300)
- [src/lib/sdk/system-prompt.ts:488-508](file://src/lib/sdk/system-prompt.ts#L488-L508)
- [src/lib/workspace-fs.ts:327-347](file://src/lib/workspace-fs.ts#L327-L347)
- [src/lib/workspace-fs.ts:355-397](file://src/lib/workspace-fs.ts#L355-L397)
- [src/lib/workspace-fs.ts:404-458](file://src/lib/workspace-fs.ts#L404-L458)
**章节来源**
- [src/lib/sdk/client.ts:257-300](file://src/lib/sdk/client.ts#L257-L300)
- [src/lib/sdk/system-prompt.ts:16-553](file://src/lib/sdk/system-prompt.ts#L16-L553)
- [src/lib/workspace-fs.ts:327-347](file://src/lib/workspace-fs.ts#L327-L347)
- [src/lib/workspace-fs.ts:355-397](file://src/lib/workspace-fs.ts#L355-L397)
- [src/lib/workspace-fs.ts:404-458](file://src/lib/workspace-fs.ts#L404-L458)
### 思维模式映射策略
- 统一思维模式：Off/Auto/Max
- Provider映射：
- Anthropic/Custom：使用原生thinking参数
- MiniMax：始终开启思维（Off被忽略）
- GLM：显式禁用需传递disabled
- Moonshot/Kimi：默认开启思维，禁用需尝试disabled
- Qwen：通过代理层接受thinking参数，禁用可能不生效
- 兼容性处理：未知Provider回退为Anthropic原生格式
```mermaid
flowchart TD
In["输入: thinkingMode, providerType"] --> Norm["归一化: adaptive→auto, enabled→max, disabled→off"]
Norm --> Switch{"匹配Provider"}
Switch --> |anthropic/custom| A["Off→disabled
Max→enabled
Auto→adaptive"]
Switch --> |minimax| B["Off→disabled
其他→enabled"]
Switch --> |zhipu| C["Off→disabled
其他→enabled"]
Switch --> |moonshot/kimi| D["Off→disabled
其他→默认(开启)"]
Switch --> |qwen| E["Off→disabled
其他→enabled"]
Switch --> |其他| F["Off→disabled
Max→enabled
Auto→adaptive"]
A --> Out["输出: thinking/effect配置"]
B --> Out
C --> Out
D --> Out
E --> Out
F --> Out
```
**图表来源**
- [src/lib/sdk/client.ts:315-373](file://src/lib/sdk/client.ts#L315-L373)
**章节来源**
- [src/lib/sdk/client.ts:315-373](file://src/lib/sdk/client.ts#L315-L373)
### 权限控制系统
- SDK安全检查：.claude/目录写操作在CLI中被硬编码拦截，即使bypassPermissions也无法绕过。
- 权限桥接策略：
- bypassPermissions模式：直接允许所有工具调用，并允许危险权限
- 正常模式：包装caller提供的canUseTool，自动批准.claudefile路径，同时限制settingSources仅加载项目级设置，防止预批准规则绕过权限桥
- SSE桥接：将SDK canUseTool请求通过SSE发送到前端，等待用户决策（允许/会话允许/拒绝/超时），并记录审计日志
```mermaid
sequenceDiagram
participant SDK as "SDK"
participant Bridge as "permission-bridge.ts"
participant SSE as "SSE事件"
participant FE as "前端"
SDK->>Bridge : canUseTool(toolName, input, options)
Bridge->>Bridge : 检查会话白名单
alt 已允许
Bridge-->>SDK : behavior=allow
else 未允许
Bridge->>SSE : permission_request
SSE-->>FE : 显示权限弹窗
FE->>Bridge : resolvePermission(decision)
Bridge-->>SDK : behavior=allow/deny
end
```
**图表来源**
- [src/lib/sdk/client.ts:451-498](file://src/lib/sdk/client.ts#L451-L498)
- [src/lib/sdk/permission-bridge.ts:62-152](file://src/lib/sdk/permission-bridge.ts#L62-L152)
- [src/lib/sdk/permission-bridge.ts:187-214](file://src/lib/sdk/permission-bridge.ts#L187-L214)
**章节来源**
- [src/lib/sdk/client.ts:451-498](file://src/lib/sdk/client.ts#L451-L498)
- [src/lib/sdk/permission-bridge.ts:62-152](file://src/lib/sdk/permission-bridge.ts#L62-L152)
- [src/lib/sdk/permission-bridge.ts:187-214](file://src/lib/sdk/permission-bridge.ts#L187-L214)
### 附件处理机制与多模态内容构建
- 附件类型分级：
- 一级：图像（base64 image块）、PDF（base64 document块）
- 二级：文本/代码/配置（读取内容并以标签形式注入）
- 三级：二进制（仅提示文件名）
- 多模态消息：当存在附件时，构建ContentBlockParam数组并以异步迭代器形式提交给SDK
```mermaid
flowchart TD
Att["输入: prompt + attachments"] --> Loop{"遍历每个附件"}
Loop --> |image| Img["读取二进制→base64→image块"]
Loop --> |pdf| Pdf["读取二进制→base64→document块"]
Loop --> |text| Txt["读取UTF-8→截断(约25k tokens)→text块"]
Loop --> |binary| Bin["记录文件名→text块"]
Img --> Acc["累积到blocks"]
Pdf --> Acc
Txt --> Acc
Bin --> Acc
Acc --> Prompt{"附加文本prompt?"}
Prompt --> |是| AddTxt["添加text块"]
Prompt --> |否| Done
AddTxt --> Done["返回blocks"]
```
**图表来源**
- [src/lib/sdk/client.ts:546-597](file://src/lib/sdk/client.ts#L546-L597)
**章节来源**
- [src/lib/sdk/client.ts:546-597](file://src/lib/sdk/client.ts#L546-L597)
### API密钥管理与认证类型处理
- Provider解析：
- 内置Provider映射（Anthropic、MiniMax、GLM、Kimi、Qwen），选择对应Base URL与认证类型
- 支持自定义Provider（model_name匹配），使用Bearer Token
- Anthropic支持API Key与CLI OAuth两种模式
- CLI OAuth检测：读取用户主目录下的OAuth账户信息，判断是否已登录
- 认证注入：
- Anthropic：x-api-key头（API Key）或同值auth token（CLI）
- 第三方：Bearer Token（auth token）
```mermaid
flowchart TD
Model["输入: model"] --> Lookup["查找内置Provider映射"]
Lookup --> |命中| Catalog["读取Provider目录: base_url, auth_type"]
Lookup --> |未命中| Custom["按model_name匹配自定义Provider"]
Catalog --> DB["读取DB: api_key/base_url/provider"]
Custom --> DB
DB --> |有API Key| UseKey["使用API Key"]
DB --> |无API Key| CLI["检查CLI OAuth"]
CLI --> |已登录| UseCLI["使用CLI OAuth"]
CLI --> |未登录| Error["抛出凭证缺失错误"]
UseKey --> Out["返回ResolvedProvider"]
UseCLI --> Out
```
**图表来源**
- [src/lib/provider.ts:108-180](file://src/lib/provider.ts#L108-L180)
- [src/lib/provider.ts:66-98](file://src/lib/provider.ts#L66-L98)
**章节来源**
- [src/lib/provider.ts:108-180](file://src/lib/provider.ts#L108-L180)
- [src/lib/provider.ts:66-98](file://src/lib/provider.ts#L66-L98)
### 代理配置选项与会话管理
- 查询选项：
- prompt/sessionId/model/workspaceId/abortController/canUseTool/bypassPermissions/customSystemPrompt/resumeSession
- extraMcpServers/skipMcpServers/skipAgents/useImPrompt/skipPersistSession
- attachments（多模态）
- 会话管理：
- 首条消息：sessionId + persistSession
- 后续消息：resume（不携带sessionId）
- 代理与MCP：
- 从.claude/agents加载代理定义
- 从DB与浏览器加载MCP服务器，合并extraMcpServers
**章节来源**
- [src/lib/sdk/client.ts:219-244](file://src/lib/sdk/client.ts#L219-L244)
- [src/lib/sdk/client.ts:378-450](file://src/lib/sdk/client.ts#L378-L450)
### 工具使用回调机制
- canUseTool包装策略：
- bypassPermissions：直接允许
- 正常模式：自动批准.claudefile路径，其余委托给调用方
- settingSources限制：仅加载项目级设置，避免预批准规则绕过
- 权限建议更新：将SDK建议的权限更新回传给SDK，保证内部状态同步
**章节来源**
- [src/lib/sdk/client.ts:451-498](file://src/lib/sdk/client.ts#L451-L498)
- [src/lib/sdk/permission-bridge.ts:84-94](file://src/lib/sdk/permission-bridge.ts#L84-L94)
### 消息映射与前端事件
- 主线程与子代理消息分流：根据parent_tool_use_id区分
- 内容块聚合：文本、思考、工具调用、工具结果、进度
- 审计与调试：剥离SDK元数据、提取WebSearch结果、记录工具错误
**章节来源**
- [src/lib/sdk/message-mapper.ts:28-85](file://src/lib/sdk/message-mapper.ts#L28-L85)
- [src/lib/sdk/message-mapper.ts:525-704](file://src/lib/sdk/message-mapper.ts#L525-L704)
## 依赖关系分析
- 组件耦合：
- client.ts高度内聚，依赖provider.ts、workspace-fs.ts、system-prompt.ts、agents-loader.ts、mcp-loader.ts、permission-bridge.ts
- permission-bridge.ts与message-mapper.ts通过SSE事件交互
- 外部依赖：
- @anthropic-ai/claude-agent-sdk（query、Options、SDKUserMessage、ContentBlockParam、CanUseTool）
- 子进程execSync/execFileSync用于CLI发现与版本管理器扫描
- 潜在循环依赖：
- workspace-fs.ts在初始化时延迟导入db.ts，避免循环
```mermaid
graph LR
client_ts["client.ts"] --> provider_ts["provider.ts"]
client_ts --> workspace_fs_ts["workspace-fs.ts"]
client_ts --> sys_prompt_ts["system-prompt.ts"]
client_ts --> agents_loader_ts["agents-loader.ts"]
client_ts --> mcp_loader_ts["mcp-loader.ts"]
client_ts --> perm_bridge_ts["permission-bridge.ts"]
perm_bridge_ts --> msg_mapper_ts["message-mapper.ts"]
```
**图表来源**
- [src/lib/sdk/client.ts:14-27](file://src/lib/sdk/client.ts#L14-L27)
- [src/lib/sdk/permission-bridge.ts:14-16](file://src/lib/sdk/permission-bridge.ts#L14-L16)
- [src/lib/sdk/message-mapper.ts](file://src/lib/sdk/message-mapper.ts#L8)
**章节来源**
- [src/lib/sdk/client.ts:14-27](file://src/lib/sdk/client.ts#L14-L27)
- [src/lib/sdk/permission-bridge.ts:14-16](file://src/lib/sdk/permission-bridge.ts#L14-L16)
- [src/lib/sdk/message-mapper.ts](file://src/lib/sdk/message-mapper.ts#L8)
## 性能考量
- CLI发现缓存：60秒内复用上次发现结果，减少IO与exec开销
- PATH扩展：仅在必要时枚举版本管理器bin目录，避免过度膨胀
- 附件读取：文本附件截断上限控制令牌量，二进制仅记录文件名
- 会话持久化：非必要时可跳过持久化，降低磁盘写入
- IM提示：紧凑提示词显著减少tokens，适合轻量查询
## 故障排查指南
- CLI不可用：
- 检查可执行文件是否存在与可执行权限
- 使用登录Shell查询which claude，确认自定义PATH
- 清理缓存后重试
- 认证失败：
- Anthropic：确认API Key或CLI OAuth状态
- 第三方Provider：确认Bearer Token与Base URL
- 权限被阻：
- .claude/写操作需经权限桥接，检查SSE连接与前端决策
- bypassPermissions仅在明确需求时使用
- 多模态附件失败：
- 图像/PDF读取异常会记录告警，检查文件路径与权限
- 文本附件过大可导致截断，注意令牌预算
- 子进程错误：
- stderr清洗后输出，关注清洗后的日志片段
**章节来源**
- [src/lib/sdk/client.ts:34-116](file://src/lib/sdk/client.ts#L34-L116)
- [src/lib/sdk/client.ts:505-515](file://src/lib/sdk/client.ts#L505-L515)
- [src/lib/sdk/client.ts:585-588](file://src/lib/sdk/client.ts#L585-L588)
- [src/lib/provider.ts:66-98](file://src/lib/provider.ts#L66-L98)
- [src/lib/sdk/permission-bridge.ts:109-120](file://src/lib/sdk/permission-bridge.ts#L109-L120)
## 结论
该SDK集成服务通过“查询构建器”将Provider解析、环境构建、CLI发现、系统提示词、代理/MCP加载、权限桥接与消息映射有机整合，既满足桌面Agent的复杂能力，又为IM等轻量场景提供紧凑提示与快速启动路径。其设计在安全性（.claude/写操作强制桥接）、可扩展性（多Provider、多MCP、多版本管理器）与可观测性（SSE审计、stderr清洗）方面均具备良好实践。
## 附录
### API密钥与认证类型对照
- Anthropic：x-api-key（API Key）或同值auth token（CLI OAuth）
- 第三方Provider（MiniMax/GLM/Kimi/Qwen）：Bearer Token（auth token）
**章节来源**
- [src/lib/provider.ts:33-57](file://src/lib/provider.ts#L33-L57)
- [src/lib/provider.ts:135-138](file://src/lib/provider.ts#L135-L138)
### 代理定义Frontmatter字段
- name/description/model/enabled/disallowedTools（支持行内数组或YAML列表）
**章节来源**
- [src/lib/sdk/frontmatter.ts:6-12](file://src/lib/sdk/frontmatter.ts#L6-L12)
- [src/lib/sdk/frontmatter.ts:23-98](file://src/lib/sdk/frontmatter.ts#L23-L98)