# Claude Code Agent SDK Agent 能力

> Agent SDK 的 agent loop、settingSources、Claude Code features、sessions、skills、subagents、todo tracking、file checkpointing 和 hosting 限制。

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

Agent SDK 可以复用 Claude Code 的项目规则、skills、hooks、MCP、subagents、todo/task tracking 和 checkpointing。问题不在于“能不能用”,而在于哪些上下文会自动加载、哪些状态落在本地磁盘、哪些能力会增加缓存前缀和成本。

运行时 API 看 [Agent SDK 运行时模式](https://docs.passion8.cc/docs/claude-code/sdk-runtime-patterns)。部署拓扑和隔离看 [Agent SDK 生产部署](https://docs.passion8.cc/docs/claude-code/sdk-production)。

## 覆盖的官方页面

| 官方页面 | 本页覆盖重点 |
| --- | --- |
| Agent loop | 消息、工具、context、result 和 hooks 生命周期 |
| Claude Code features in SDK | `settingSources`、CLAUDE.md、skills、hooks 和 MCP 加载 |
| Sessions | continue、resume、fork、跨主机恢复 |
| Skills | SDK 中如何发现和加载 skills |
| Subagents | programmatic agents、继承边界、工具限制 |
| Todo tracking | Task tools 和实时进度 UI |
| File checkpointing | SDK 内文件回退能力和限制 |
| Hosting | subprocess、本地状态、资源和已知限制 |

## Agent loop

一次 SDK 任务大致是这个循环:

```text
user prompt
  -> system/init
  -> assistant thinks and emits tool calls
  -> SDK/CLI checks hooks and permissions
  -> tools execute
  -> tool results enter conversation
  -> repeat until success, max turns, max budget, or error
```

| 消息/阶段 | 你要处理什么 |
| --- | --- |
| `system/init` | session id、模型、可用 slash commands、工具和权限模式 |
| assistant text | UI 流式显示 |
| tool use | 展示正在读文件、编辑、跑命令或调用 MCP |
| tool result | 记录摘要,敏感内容默认折叠 |
| result success | 保存结果、usage、成本 |
| result error | 显示失败原因,保留可恢复信息 |

常见 result subtype:

| Subtype | 含义 |
| --- | --- |
| `success` | 正常完成 |
| `error_max_turns` | 到达 `maxTurns` |
| `error_max_budget_usd` | 到达预算上限 |
| `error_during_execution` | API、工具、取消或运行时错误 |
| `error_max_structured_output_retries` | 结构化输出多次校验失败 |

## Context 来源

| 来源 | 何时加载 | 缓存影响 |
| --- | --- | --- |
| System prompt | 每次请求 | 稳定时容易被 prompt cache 复用 |
| CLAUDE.md / rules | session 启动和按需读取 | 内容越大,首次写入越贵 |
| Tool definitions | 每次请求或 tool search 延迟加载 | MCP upfront schema 会显著增大前缀 |
| Conversation history | 每轮增长 | 长会话需要 compact 或分支 |
| Skill descriptions | session 启动 | 通常小,完整 skill 内容只在调用时加载 |
| Hooks | 加载配置后影响工具执行 | hook 结果可能追加上下文 |

## `settingSources`

| Source | 加载内容 |
| --- | --- |
| `project` | 项目 CLAUDE.md、`.claude/rules`、skills、hooks、settings |
| `user` | `~/.claude/CLAUDE.md`、用户 rules、skills、settings |
| `local` | `CLAUDE.local.md`、`.claude/settings.local.json` |

`settingSources` 不控制这些:

| 输入 | 行为 | 禁用方式 |
| --- | --- | --- |
| Endpoint-managed policy | 由主机策略加载 | 移除设备策略 |
| Server-managed settings | 符合条件时由组织管理 | 只能由管理员控制 |
| `~/.claude.json` | 仍可能读取 | 用 `CLAUDE_CONFIG_DIR` 隔离 |
| Auto memory | session 启动进入 system prompt | `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` |
| claude.ai MCP connectors | subscription 登录时可能加载 | `strictMcpConfig` 或禁用 connector |

多租户和 CI 默认不要加载用户环境:

```typescript
options: {
  settingSources: [],
  env: {
    ...process.env,
    CLAUDE_CONFIG_DIR: "/srv/claude-config/job-123",
    CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1"
  }
}
```

## Sessions

| 场景 | 用法 |
| --- | --- |
| 一次性任务 | 不传 session,让 `query()` 新建 |
| 同目录继续最近一次 | `continue: true` 或 `continue_conversation=True` |
| 恢复特定 session | 保存 ID,传 `resume` |
| 尝试替代方案 | fork session |
| 不落盘 | TypeScript 可用 `persistSession: false` |

跨主机恢复只靠 session ID 不够。transcript 之外的工作目录、CLAUDE.md、checkpoint blob、工具缓存和文件产物都要单独规划。

## Skills

SDK 可以加载项目或用户 skills,也可以通过 plugins 传入。

| 设计点 | 建议 |
| --- | --- |
| `description` | 写清什么时候用,否则 Claude 不会自动触发 |
| `allowed-tools` | 给 skill 限制工具范围 |
| 项目 skills | 跟 repo 一起版本化 |
| 用户 skills | 适合个人工作流 |
| 插件 skills | 适合团队分发 |
| SDK 隔离 | 不想自动加载时清空 `settingSources` |

Skill 内容通常不会全部进首轮上下文,但 description 会。大型 skill 多了仍会影响 cache 前缀。

## Subagents

Programmatic agent definition 比文件定义更适合 SDK 产品。

| 字段 | 作用 |
| --- | --- |
| `description` | Claude 判断何时使用这个 subagent |
| `prompt` | subagent 的系统角色和任务边界 |
| `tools` | 限制可用工具 |
| `disallowedTools` | 从继承工具集中移除工具 |
| `model` | 指定 subagent 模型 |
| `skills` | 预加载指定 skills |
| `mcpServers` | 给 subagent 单独配置 MCP |
| `maxTurns` | 限制子任务轮数 |
| `background` | 后台运行,不阻塞主线程 |

继承边界:

| Subagent 获得 | Subagent 不获得 |
| --- | --- |
| 自己的 system prompt | 父会话完整历史 |
| 项目 CLAUDE.md | 父工具结果 |
| 指定或继承的工具定义 | 父 system prompt |
| 指定 skills | 未预加载的 skill 内容 |

工具组合建议:

| 用例 | 工具 |
| --- | --- |
| 只读分析 | `Read`, `Grep`, `Glob` |
| 跑测试 | `Bash`, `Read`, `Grep` |
| 改代码 | `Read`, `Edit`, `Write`, `Grep`, `Glob` |
| 完整自治 | 谨慎继承全部工具,并放进 sandbox |

## Todo 和 Task tools

新版本更推荐 Task tools,而不是旧的 `TodoWrite`。

| 旧 `TodoWrite` | 新 Task tools |
| --- | --- |
| 一次重写整个 todos array | `TaskCreate` 新增一项 |
| 用 `status` 跟踪状态 | `TaskUpdate` 局部更新 |
| UI 直接渲染数组 | UI 需要累积 task 事件或读取 snapshot |
| 适合简单列表 | 适合 owner、blocked by、metadata 和并行任务 |

实时进度 UI 应监听 `TaskCreate`、`TaskUpdate` 和 `TaskList` 结果,不要只解析 assistant 文本。

## File checkpointing

SDK checkpointing 适合在 agent 写文件前后创建恢复点。

| 能跟踪 | 说明 |
| --- | --- |
| `Write` | 新文件或覆盖写入 |
| `Edit` | 现有文件的局部修改 |
| `NotebookEdit` | Jupyter notebook cell 修改 |
| 同一 session 内恢复 | 回到该 session 内的恢复点 |

限制:

| 限制 | 说明 |
| --- | --- |
| Bash 改动 | 通过 shell 生成或删除的文件不在 checkpoint 内 |
| 目录操作 | 创建、移动、删除目录不完整回退 |
| 远端文件 | 网络文件和远端资源不追踪 |
| 跨 session | checkpoint 绑定创建它的 session |

高风险批量编辑前,让 agent 先创建 checkpoint,再执行迁移。

## Hosting 限制

| 限制 | 对策 |
| --- | --- |
| 没有顶层 wall-clock timeout | 用 `maxTurns`、外部进程 watchdog 和队列超时 |
| 长会话内存增长 | 定期 compact、分段任务、回收子进程 |
| 大量并行 subagent 会限流 | 分批,控制 fanout |
| per-subagent 无总时限 | subagent 设置 `maxTurns`,后台任务设置 stall watchdog |
| 本地状态多 | `CLAUDE_CONFIG_DIR`、工作目录和 SessionStore 都要规划 |

## 缓存影响

| 能力 | 5m/1h cache 影响 |
| --- | --- |
| `settingSources` 加载 CLAUDE.md | 内容稳定时适合 1 小时 TTL |
| 大量 skills | description 增大前缀 |
| MCP upfront tools | 工具 schema 变化会频繁 miss |
| Subagents | 每个 subagent 有独立上下文和缓存前缀 |
| Task tools | 任务状态进入历史,长任务需要 compact |
| Checkpointing | 主要影响本地状态,但回退说明会进会话 |

## 官方参考

- [How the agent loop works](https://code.claude.com/docs/en/agent-sdk/agent-loop.md)
- [Claude Code features in SDK](https://code.claude.com/docs/en/agent-sdk/claude-code-features.md)
- [Work with sessions](https://code.claude.com/docs/en/agent-sdk/sessions.md)
- [Agent Skills in SDK](https://code.claude.com/docs/en/agent-sdk/skills.md)
- [Subagents in SDK](https://code.claude.com/docs/en/agent-sdk/subagents.md)
- [Todo Lists](https://code.claude.com/docs/en/agent-sdk/todo-tracking.md)
- [File checkpointing](https://code.claude.com/docs/en/agent-sdk/file-checkpointing.md)
- [Hosting the Agent SDK](https://code.claude.com/docs/en/agent-sdk/hosting.md)