> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zerone.run/llms.txt
> Use this file to discover all available pages before exploring further.

# 示例

> 按任务选择 Agent SDK 示例并在本地运行。

# 从示例开始

SDK 仓库的 `examples/` 目录包含 30 余个可运行示例，按基础查询、多轮会话、Tool、Skill、MCP、subagent、权限和 UI 集成组织。本页是策划索引；`examples/` 目录本身是权威来源。

克隆仓库并安装依赖后，可直接运行一个示例：

```bash theme={null}
git clone https://github.com/zerone-agents/agent-sdk.git
cd agent-sdk
npm install
npx tsx examples/basic/01-simple-query.ts
```

运行前设置所选 Provider 的 API key。涉及文件或 Bash 的示例应在临时工作目录运行，并先检查权限配置。

## 类别总览

| 类别           | 内容                                    |
| ------------ | ------------------------------------- |
| `basic/`     | 简单查询、多 Tool、多轮、prompt API、系统提示词       |
| `tools/`     | 自定义 Tool、权限、二进制读取、TodoWrite、Edit Tool |
| `agents/`    | Subagent、Task Tool 模式、MultiTask 编排    |
| `skills/`    | 上下文内 Skill、文件系统 Skill Agent           |
| `sessions/`  | Session 回退、分叉、查询上限                    |
| `streaming/` | 流式响应、带 Tool 的流式、子任务事件                 |
| `mcp/`       | MCP server 集成、自定义 MCP Tool            |
| `advanced/`  | Hook、OpenAI/官方 API 兼容、Web 搜索、压缩、推理强度  |
| `testing/`   | 并行 Tool、max tokens、连接错误的测试工具          |

## 基础

| 示例                                          | 说明                     |
| ------------------------------------------- | ---------------------- |
| `examples/basic/01-simple-query.ts`         | 带事件处理的流式查询             |
| `examples/basic/02-multi-tool.ts`           | 多 Tool 编排（Glob + Bash） |
| `examples/basic/03-multi-turn.ts`           | 多查询 Session 持久化        |
| `examples/basic/04-prompt-api.ts`           | 阻塞式 `prompt()` API     |
| `examples/basic/05-custom-system-prompt.ts` | 自定义系统提示词               |

## Tool 与权限

| 示例                                        | 说明                                 |
| ----------------------------------------- | ---------------------------------- |
| `examples/tools/07-custom-tools.ts`       | 用 `defineTool()` 自定义 Tool          |
| `examples/tools/10-permissions.ts`        | 带 Tool 限制的只读 Agent                 |
| `examples/tools/21-test-read-binary.ts`   | Read Tool 二进制文件处理（图片、tar.gz）       |
| `examples/tools/22-todowrite.ts`          | 用 TodoWrite Tool 做结构化任务跟踪          |
| `examples/tools/28-edit-tool-features.ts` | Edit Tool 高级特性（old\_string 校验、多文件） |
| `examples/tools/37-read-directory.ts`     | 用 Read Tool 列出目录                   |
| `examples/tools/38-tool-env-isolation.ts` | 控制 Bash/Grep 子进程可见的环境变量（宿主嵌入隔离）    |

## Agent 与 Subagent

| 示例                                      | 说明                                                |
| --------------------------------------- | ------------------------------------------------- |
| `examples/agents/09-subagents.ts`       | Subagent 委派                                       |
| `examples/agents/29-task-tool-modes.ts` | Task Tool 的 `subagent_type` 模式（explore 与 general） |
| `examples/agents/30-multitask.ts`       | 用 MultiTask Tool 并行编排 subagent                    |

## Skill

| 示例                                              | 说明                                  |
| ----------------------------------------------- | ----------------------------------- |
| `examples/skills/12-skills.ts`                  | Skill 系统用法                          |
| `examples/skills/14-filesystem-skills-agent.ts` | 文件系统 Skill 加载                       |
| `examples/skills/15-nested-skills.ts`           | 嵌套 Skill 目录 + frontmatter 覆盖 + 变量替换 |

## Session 与历史

| 示例                                            | 说明                                   |
| --------------------------------------------- | ------------------------------------ |
| `examples/sessions/23-session-revert.ts`      | 将 Session 回退到之前的消息状态                 |
| `examples/sessions/24-fork-from-message.ts`   | 从任意消息分叉 Session                      |
| `examples/sessions/25-revert-fork-guide.ts`   | 完整指南：回退与分叉模式                         |
| `examples/sessions/26-agent-revert-api.ts`    | Agent 回退 API（程序化 Session 回退）         |
| `examples/sessions/27-caller-revert-flow.ts`  | 调用方控制的回退流程                           |
| `examples/sessions/31-session-query-limit.ts` | 用 `maxSessionQueries` 限制 Session 上下文 |

## 流式

| 示例                                                 | 说明                |
| -------------------------------------------------- | ----------------- |
| `examples/streaming/16-streaming.ts`               | 流式响应（行分隔 JSON 事件） |
| `examples/streaming/17-streaming-with-tools.ts`    | 带 Tool 调用与结果的流式   |
| `examples/streaming/33-subtask-completed-event.ts` | 流式模式下的子任务完成事件     |
| `examples/streaming/34-streaming-tool-results.ts`  | 流式 Tool 结果（中间输出）  |

## MCP 集成

| 示例                                    | 说明                                |
| ------------------------------------- | --------------------------------- |
| `examples/mcp/06-mcp-server.ts`       | MCP server 集成                     |
| `examples/mcp/11-custom-mcp-tools.ts` | `tool()` + `createSdkMcpServer()` |

## 高级特性

| 示例                                                | 说明                   |
| ------------------------------------------------- | -------------------- |
| `examples/advanced/08-official-api-compat.ts`     | `query()` API 模式     |
| `examples/advanced/13-hooks.ts`                   | 生命周期 hook            |
| `examples/advanced/15-openai-compat.ts`           | OpenAI / DeepSeek 模型 |
| `examples/advanced/18-system-preset-alignment.ts` | 系统预设对齐，保持行为一致        |
| `examples/advanced/19-web-search.ts`              | Web 搜索 Tool 集成       |
| `examples/advanced/20-compact-features.ts`        | 压缩特性（上下文窗口管理）        |
| `examples/advanced/32-reasoning-effort.ts`        | 推理强度控制               |

## Web UI

| 示例                       | 说明             |
| ------------------------ | -------------- |
| `examples/web/server.ts` | 用于测试的 Web 聊天界面 |

运行任意示例：

```bash theme={null}
npx tsx examples/basic/01-simple-query.ts
npx tsx examples/agents/09-subagents.ts
npx tsx examples/streaming/34-streaming-tool-results.ts
```

启动 Web UI：

```bash theme={null}
npx tsx examples/web/server.ts
```

## 推荐路径

1. 简单 blocking query。
2. Streaming 事件消费。
3. 自定义 Tool。
4. Session 恢复。
5. Skill 与 subagent 能力隔离。