# Claude Code Agent SDK 能力矩阵

> Claude Code: Agent SDK 的权限评估、Hooks、MCP、SessionStore、成本追踪、OpenTelemetry、安全部署和 5m/1h 缓存策略。

URL: https://docs.passion8.cc/docs/claude-code/sdk-capabilities
Language: zh-CN
Publisher: Passion8

Agent SDK 不是“把 prompt 发给模型”的薄 wrapper。它启动 Claude Code agent loop,让模型、工具、权限、Hooks、MCP、会话和 telemetry 一起工作。这个页面把官方 SDK 细分文档整理成生产选型矩阵。

运行时 API 设计,包括 custom tools、system prompt、streaming、structured output、用户审批和 SDK slash commands,见 [Agent SDK 运行时模式](https://docs.passion8.cc/docs/claude-code/sdk-runtime-patterns)。




如果你只需要一个人在终端里改项目,用 CLI。只有当你要把 agent 嵌进产品、CI、后台任务或多租户服务时,才需要 SDK 的权限、会话、观测和隔离设计。




## 能力全景

| 能力 | 解决什么问题 | 生产注意 |
| --- | --- | --- |
| Permission modes | 控制工具能否自动执行 | `allowedTools` 是预批准,不是限制工具全集 |
| `canUseTool` | 在运行时向用户或业务系统要审批 | 可能被 allow、mode 或 deny 规则绕过,要理解评估顺序 |
| Hooks | 在工具调用、session 生命周期、停止点拦截 | 强制审计或阻断敏感动作时优先用 `PreToolUse` |
| MCP | 给 agent 接内部 API、数据库、浏览器、SaaS | 大型 MCP 要用 tool search,并控制认证和工具输出大小 |
| SessionStore | 跨主机恢复 transcript | 只同步 transcript,不替代工作目录、CLAUDE.md 或 checkpoint blobs |
| Cost tracking | 记录 token、model usage、估算成本 | SDK 成本是客户端估算,不能直接作为最终账单 |
| OpenTelemetry | 导出 metrics、logs、traces | SDK stdout 是消息通道,不要用 console exporter |
| Secure deployment | 隔离文件、网络、凭据和租户 | 多租户必须单独 cwd、config dir、env 和 egress |

## 权限评估顺序

SDK 工具请求按这个顺序处理:

| 顺序 | 层 | 结果 |
| --- | --- | --- |
| 1 | Hooks | 可以直接 deny,也可以记录或改写输入 |
| 2 | Deny rules | 命中即阻断,`Bash(rm *)` 这类 scoped deny 在 bypass 下也生效 |
| 3 | Ask rules | 命中后交给 `canUseTool`,需要用户或业务审批 |
| 4 | Permission mode | `bypassPermissions`、`acceptEdits`、`plan`、`dontAsk` 等全局策略 |
| 5 | Allow rules | 命中则自动批准 |
| 6 | `canUseTool` | 前面都没解决才调用 |

常见误区:

| 配置 | 实际行为 |
| --- | --- |
| `allowedTools: ["Read"]` + `bypassPermissions` | `Read` 被 allow,其他工具落到 bypass,仍可能全部通过 |
| `disallowedTools: ["Bash"]` | Bash 工具定义被移除,Claude 看不到 Bash |
| `disallowedTools: ["Bash(rm *)"]` | Bash 仍可见,但匹配命令会被阻断 |
| `dontAsk` + 少量 allowed tools | 最适合锁定只读或窄任务,未列出的动作直接拒绝 |
| 只靠 `canUseTool` | 如果前面 allow 或 mode 已批准,callback 可能不会被调用 |

## Hooks 用法

Hooks 适合把安全、审计和业务规则放到模型动作之前或之后。

| Hook 场景 | 建议 |
| --- | --- |
| 阻断危险命令 | `PreToolUse` 检查 Bash 输入,命中后 deny |
| 审计所有工具 | `PreToolUse` 和 `PostToolUse` 记录 tool name、session、agent、结果摘要 |
| 格式化或验证文件 | `PostToolUse` 在 Edit/Write 后运行 formatter 或 test |
| 注入短期凭据 | 在工具调用前由外部代理注入,不要把长期 secret 放进 prompt |
| 任务结束通知 | `Stop` 或运行结束事件发消息、webhook、ticket update |

Hook 返回 allow 不会跳过后续 deny/ask/permission rules。需要“每次都必须检查”的规则,放 `PreToolUse`,不要只放 `canUseTool`。

## MCP 接入

MCP 让 SDK agent 使用外部工具。生产环境要按工具数量、认证方式和输出大小规划。

| 设计点 | 建议 |
| --- | --- |
| Transport | 本地工具用 stdio,远程服务用 HTTP/SSE/WebSocket |
| Auth | OAuth 或短期 token,避免在 prompt 或仓库里暴露 secret |
| Tool search | 工具很多时开启,不要把所有 schema upfront 塞进 prompt |
| Output size | 限制大结果,给分页或摘要接口 |
| Human approval | 对高风险 MCP tool 设置 requires-user-interaction 或 ask rule |
| Gateway 场景 | 确认网关支持 tool search/deferred tools,否则缓存容易 miss |

MCP 工具输出进入 conversation 后会成为后续上下文的一部分。长日志、全表查询、完整网页 HTML 都会抬高下一轮成本。

## SessionStore

默认 transcript 在本机 `~/.claude/projects/`。`SessionStore` 可以把 transcript mirror 到 S3、Redis、数据库或自研后端,让任意 worker 恢复同一个 session。

| 方法 | 是否必需 | 用途 |
| --- | --- | --- |
| `append` | 必需 | 本地写入 transcript 后,把 entries 追加到外部 store |
| `load` | 必需 | resume 前加载历史 |
| `listSessions` | 可选 | 支持列出或 continue 最近 session |
| `delete` | 可选 | 删除 session,append-only 后端可实现 no-op |
| `listSubkeys` | 可选 | 恢复 subagent transcript |

边界:

| 不由 SessionStore 接管 | 需要你自己处理 |
| --- | --- |
| 工作目录文件 | 用持久卷、对象存储或每任务目录 |
| `CLAUDE.md` 和 auto memory | 独立隔离或禁用 |
| checkpoint blob | 如果要跨主机 rewind,需要单独持久化 |
| MCP server 状态 | 由 MCP server 或外部服务管理 |

监控 `mirror_error`。如果外部 store append 失败,agent 可能继续运行,但恢复能力已经不完整。

## 成本追踪

SDK 会在 message stream 中暴露 per-step usage、per-model usage 和 query 结束时的总估算。

| 字段/概念 | 用途 |
| --- | --- |
| assistant message usage | 观察每一步 input/output token |
| result `total_cost_usd` | 单次 `query()` 的客户端估算成本 |
| result `model_usage` | 多模型或 fallback 时分模型统计 |
| `cache_creation_input_tokens` | 本轮写入缓存的输入 |
| `cache_read_input_tokens` | 本轮读取缓存的输入 |

注意:并行工具调用可能生成多个 assistant message,但它们共享同一个 message ID 和 usage。做 per-step 统计时要按 ID 去重。




SDK 的成本字段是本地估算,会受 SDK 版本、模型 ID 识别和价格表更新影响。用于开发观测和预算预警可以,不要直接作为对客户扣费或财务结算的唯一来源。




## OpenTelemetry

生产环境建议开启 OTLP,把 agent 运行过程接入现有 observability。

```bash
CLAUDE_CODE_ENABLE_TELEMETRY=1
CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector.example.com:4318
```

| Signal | 适合看什么 |
| --- | --- |
| Metrics | session 数、token、cost、tool decision、lines changed |
| Log events | prompt/API/tool/error 事件摘要 |
| Traces | model request、tool call、hook、agent step 延迟链路 |

SDK 通过 stdout/stderr 和子进程通信。不要把 OTEL exporter 设置成 `console`,否则 telemetry 输出会污染 SDK 消息通道。

## 安全部署

Agent 可以读文件、跑命令、访问网络和调用外部服务。安全设计按“最小权限 + 隔离 + 多层防御”处理。

| 资源 | 控制方式 |
| --- | --- |
| Filesystem | 每租户/每任务单独 `cwd`,必要时只读挂载 |
| Network | 出站 allowlist、代理、无网 sandbox |
| Credentials | 由外部代理注入短期凭据,不要直接给长期 key |
| Settings | 多租户服务设置 `settingSources: []` 并显式给 options |
| Config dir | 每租户 `CLAUDE_CONFIG_DIR` |
| Auto memory | 共享环境禁用 `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` |
| Process | Docker、sandbox-runtime、gVisor、Firecracker 或 CI 隔离 |

如果 agent 处理用户上传文件、网页内容、issue 评论或仓库 README,要把 prompt injection 当作正常威胁模型处理:网络和凭据边界比“相信模型不会照做”更可靠。

## 5m / 1h 缓存策略

| SDK 场景 | 缓存建议 |
| --- | --- |
| 单次 `query()` | 一次任务内部多 step 会自然复用前缀,不要中途切模型/effort |
| 多次 `query()` + resume | 同一 session ID、同模型、同 effort 更容易命中 |
| 多 worker + SessionStore | transcript 可恢复,但 provider-side cache 不会跨 TTL 或跨 cache key 保证存在 |
| API key / Passion8 / Bedrock / Vertex | 默认按 5 分钟 TTL 设计交互节奏 |
| Claude subscription | 计划内通常可按 1 小时 TTL 设计长间隔 |
| MCP 工具多 | tool search 稳定前缀,避免每轮重发完整 schema |
| Permission/settings 变更 | 工具集合或 system 前缀变化后,下一轮可能重建缓存 |
| 子代理 | 每个子代理独立上下文和缓存,成本按 agent 数扩张 |

在 SDK 服务里,把 `/usage` 思路变成 telemetry 和业务指标:按 tenant、session、agent、model、tool、cache read/write 维度记录。

## 官方参考

- [Track cost and usage](https://code.claude.com/docs/en/agent-sdk/cost-tracking.md)
- [Configure permissions](https://code.claude.com/docs/en/agent-sdk/permissions.md)
- [Intercept and control agent behavior with hooks](https://code.claude.com/docs/en/agent-sdk/hooks.md)
- [Connect to external tools with MCP](https://code.claude.com/docs/en/agent-sdk/mcp.md)
- [Observability with OpenTelemetry](https://code.claude.com/docs/en/agent-sdk/observability.md)
- [Persist sessions to external storage](https://code.claude.com/docs/en/agent-sdk/session-storage.md)
- [Securely deploying AI agents](https://code.claude.com/docs/en/agent-sdk/secure-deployment.md)