# @blade-ai/agent-sdk 中文文档

规范地址：https://npmcn.com/package/%40blade-ai/agent-sdk/

版本：7\.4\.16
npm 元数据更新时间：2026-10-17T19:03:21.296Z
中文译文更新时间：2026-11-08T06:03:48.029Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40blade-ai/agent-sdk
原文对照：https://npmcn.com/package/%40blade-ai/agent-sdk/?lang=original
项目主页：https://github.com/echoVic/blade-agent-sdk#readme
源码仓库：https://github.com/echoVic/blade-agent-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2 MB，772 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.14\.0
- 运行依赖：17 个
- peer 依赖：pg 8\.23\.0，@ai-sdk/azure ^3\.0\.54，@ai-sdk/google ^3\.0\.64，@vscode/ripgrep ^1\.17\.0，@ai-sdk/deepseek ^2\.0\.29，@ai-sdk/anthropic ^3\.0\.71，fs-native-extensions 1\.5\.0
- 首次发布：2026-02-08T04:19:53.203Z
- 最新版本发布：2026-10-17T19:03:20.940Z
- 近 30 天下载量：2171（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：123（近 12 个月 123 个）

## 中文简介

刀锋AI特工SDK

## 安装

```sh
npm install @blade-ai/agent-sdk
```

也可以使用：`pnpm add @blade-ai/agent-sdk`、`yarn add @blade-ai/agent-sdk`、`bun add @blade-ai/agent-sdk`

## README

# Blade Agent SDK

[English](https://npmcn.com/package/%40blade-ai/agent-sdk/README.md)

同时面向本地 Node.js 进程与 Node.js 服务端的 Session-first TypeScript Agent SDK。它用一套 API 统一多轮会话、流式工具执行、MCP、子 Agent、Skills、权限、Hooks、沙箱策略、结构化输出和可观测性。

## 环境要求

-   Node.js 22.14.0 或更高版本
-   ESM 项目或支持 ESM 的构建工具

本包仅提供 ESM，不支持 CommonJS `require()`。

## 5 分钟快速开始

```bash
npm install @blade-ai/agent-sdk
```

创建 `agent.mjs`：

```js
import { createAgent } from '@blade-ai/agent-sdk';

const apiKey = process.env.OPENAI_API_KEY;
if (!apiKey) throw new Error('缺少 OPENAI_API_KEY');

const agent = await createAgent({
  model: 'gpt-4o-mini',
  apiKey,
  filesystem: {
    roots: [process.cwd()],
    cwd: process.cwd(),
  },
});

const response = await agent.send('读取 package.json，用三个要点总结这个项目');

for await (const chunk of response.textStream()) {
  process.stdout.write(chunk);
}

await agent.close();
```

运行：

```bash
OPENAI_API_KEY=your-key node agent.mjs
```

`createAgent()` 默认使用 OpenAI。其他 Provider 可通过 `provider` 和 `baseUrl` 配置。传入 `filesystem` 时会自动选择 local profile；未传入时使用 server profile。也可以通过 `profile: 'local' | 'server'` 显式选择。

常用选项保留在顶层，基础设施和策略配置统一放入 `advanced`：

```ts
const agent = await createAgent({
  model: 'gpt-4o-mini',
  apiKey,
  temperature: 0.2,
  systemPrompt: '回答务必简洁。',
  advanced: {
    permission: 'accept-edits',
    tokenBudget: { maxTotalTokens: 100_000 },
    skills: [
      {
        name: 'review',
        description: '审查代码正确性和风险',
        content: '按严重程度输出问题，并提供文件和行号。',
        allowedTools: ['Read', 'Glob', 'Grep'],
      },
    ],
  },
});
```

每次 `send()` 返回一个 `AgentResponse`。使用 `text()` 获取完整文本， `textStream()` 消费文本增量，`on(type, listener)` 监听指定事件， `stream()` 消费全部类型化事件。所有视图共享同一次底层执行，并可重放其他视图 已经消费的事件。

## 项目脚手架

生成不依赖 PostgreSQL 或 Docker 的本地 Agent：

```bash
npm exec --yes --package=@blade-ai/agent-sdk@latest -- \
  create-blade-agent my-agent --preset local --verify
```

生成 Browser + AgentServer 应用（真实工具、运行中插入指令、重启后会话仍在 `.blade/`）：

```bash
npm exec --yes --package=@blade-ai/agent-sdk@latest -- \
  create-blade-agent my-agent --preset web
```

在终端里，安装完成后服务会直接启动并打开浏览器；加 `--no-start` 跳过， 或加 `--verify` 改为运行 9 步 smoke。

生成完整的 PostgreSQL、Worker、Docker、审批和恢复拓扑：

```bash
npm exec --yes --package=@blade-ai/agent-sdk@latest -- \
  create-blade-agent my-agent --preset production --verify
```

最长的安装后 smoke 预算为五分钟。省略 `--verify` 可跳过 smoke， `--skip-install` 只生成文件。

## 底层 Session API

框架和运行时集成可以直接使用 `createSession()`：

```ts
import {
  createSession as createNodeSession,
  createServerSession,
} from '@blade-ai/agent-sdk/advanced';
```

两个 profile 共用同一套 Session API 与协议，区别在于进程的运行位置和可触达范围：

|  | `local` | `server` |
| --- | --- | --- |
| 本地文件与 Shell 工具 | 配置 `filesystem` capability 后可用 | 不隐式注册；显式数据 Skill 只引入 `Skill` loader |
| `storagePath` | 由本地 JSONL 持久化支撑 | 直接抛 `ConfigError`：服务端 Session 需要 `sessionRepository` 与 `sessionEventStore` |
| 默认持久化 | 设置 `storagePath` 时写本地 JSONL | 未注入 repository 时仅内存 |
| 上下文与 Skill 发现 | 开启 | 关闭（`localDiscovery` 为 false） |

本地 Agent 或 CLI 使用 local profile；构建共享的多租户服务并显式注入存储时使用 server profile。

## 核心能力

-   Agent facade：使用必需、常用和 `advanced` 三层选项的 `createAgent()`
-   底层 Session 生命周期：`createSession()`、`resumeSession()`、`forkSession()`、`prompt()`
-   可转向请求：持久化的 `now`、`next`、`later` 输入，支持取消和待处理输入查询
-   Durable 恢复：带 fencing 的执行租约、受控 worker handoff、Request/Turn rollover、显式模型/工具对账与 cursor 断线续读
-   执行平面：`AgentWorker`、可注入的 `SessionRunner` 契约、`SdkSessionRunner` 与 `ExecutionHostSessionRunner`
-   流式事件：17 种类型化事件，覆盖轮次、内容、思维、工具、usage、转向、结果和错误
-   Provider：OpenAI、Anthropic、Azure OpenAI、Gemini、DeepSeek 和 OpenAI-compatible API
-   工具：支持 async function 与 AsyncGenerator、TypeBox schema、按能力分组的内置工具、MCP 工具、类型化进度/副作用与 `blade-tool-*` 包约定
-   扩展：洋葱式模型/工具 middleware，以及可打包 middleware、hooks 与工具的声明式插件
-   协作：前台/后台子 Agent、任务工具，以及项目级 Skills
-   安全：有界模型、工具与 inline hook 执行、权限模式、策略回调、路径检查和可选 OS 沙箱集成
-   运行时：可选 workspace、结构化输出、崩溃安全的本地会话记录、上下文压缩、token 预算和 trace

## 转向活动请求

`send()` 返回 `InputSubmission`。请求运行期间，可以选择新输入的应用时机：

```ts
const current = await session.send('分析这个仓库');

for await (const event of session.stream()) {
  if (event.type === 'tool_use' && event.name === 'Bash') {
    await session.send('停止修改，只报告发现', {
      priority: 'now',
      expectedRequestId: current.requestId,
    });
  }
}
```

-   `now`：中断当前可取消步骤并立即转向
-   `next`：在下一个模型或工具安全点应用
-   `later`：排队到下一个请求

使用 `getPendingInputs()` 和 `cancelInput()` 管理已接受的输入。

## 自定义工具

常用路径使用 TypeBox schema 和普通 async function。返回值会自动转换成内部成功结果：

```ts
import { defineTool } from '@blade-ai/agent-sdk';
import Type from 'typebox';

const weather = defineTool({
  name: 'GetWeather',
  description: '查询城市天气',
  parameters: Type.Object({ city: Type.String() }),
  async execute({ city }) {
    return { weather: `${city}：晴，25 C` };
  },
});
```

`defineTool.execute` 始终返回 JSON 数据；失败时抛出异常。SDK 不会根据返回对象 中的字段猜测结果语义。

## 权限与 Hooks

新的 Agent 集成只使用一个权限字段：

```ts
const agent = await createAgent({
  model: 'gpt-4o-mini',
  apiKey,
  advanced: {
    permission: async (request) =>
      request.kind === 'readonly' ? 'allow' : 'ask',
    hooks: {
      PreToolUse: [
        async (event) => {
          console.log(event.toolName, event.toolInput);
          return { action: 'continue' };
        },
      ],
    },
  },
});
```

`advanced.hooks` 只包含进程内 TypeScript callback，对应 8 种 Session hook 事件。底层集成仍可使用 `SessionOptions.permissionMode` 和 `permissionHandler`。

## 包入口

```ts
import { createAgent, defineTool } from '@blade-ai/agent-sdk';
import { AgentClient } from '@blade-ai/agent-sdk/browser';
import {
  createSession,
  createServerSession,
  DockerExecutionHost,
  type SessionRunner,
} from '@blade-ai/agent-sdk/advanced';
import {
  AgentServer,
  AgentWorker,
} from '@blade-ai/agent-sdk/server/infra';
import { PostgresRuntimeStore } from '@blade-ai/agent-sdk/server/postgres';
```

-   根入口：`createAgent`、`defineTool`、middleware、模型契约、常量和公共类型
-   `/browser`：browser-safe `AgentClient`、协议契约和事件解析器
-   `/protocol`：wire protocol schema 与解析器
-   `/server/infra`：`AgentServer`、`AgentWorker` 和 Runtime Store 契约
-   `/advanced`：底层 local/server Session、`SessionRunner`、ExecutionHost 和 Node adapter

原 `/node`、`/server`、`/core`、`/model`、`/session`、`/middleware`、 `/tools` compatibility alias 已删除。可选 PostgreSQL adapter 位于 `/server/postgres`，导入 `/server/infra` 不会强制安装 `pg`。Server 与 Worker telemetry 是显式接口，应用可以接入任意可观测性后端。

浏览器误导入仅服务端入口时，会解析到带清晰错误信息的 stub。

使用一条命令在本地运行完整的浏览器到 Worker 生产拓扑：

```bash
pnpm example:production
```

该命令会启动 PostgreSQL、`AgentServer`、运行真实 SDK Session 的 `AgentWorker`， 以及带浏览器审批步骤的隔离 Docker 仓库环境。详见[可运行 Golden Paths](https://npmcn.com/package/%40blade-ai/agent-sdk/examples/README.md)。

PostgreSQL、非内置 Provider adapter 和本机原生增强是按需 peer：

```bash
pnpm add pg                         # /server/postgres 的 PostgresRuntimeStore
pnpm add @ai-sdk/anthropic          # provider: anthropic
pnpm add fs-native-extensions        # Node JSONL 跨进程锁
```

## 持久化与 Workspace

未同时配置只读 `SessionRepository` 与只写 `SessionEventStore` 时，Session 只保存在内存中。local Agent 会把 `advanced.storagePath` 转换为同时实现两者的 本地 JSONL 存储适配器：

```ts
import { createAgent } from '@blade-ai/agent-sdk';

const agent = await createAgent({
  model,
  apiKey,
  profile: 'local',
  filesystem: {
    roots: [process.cwd()],
    cwd: process.cwd(),
  },
  advanced: {
    storagePath: '/var/lib/my-agent',
  },
});
```

底层 `createServerSession()` 不会把 `storagePath` 解释为本地持久化； 服务端应用必须显式注入 `sessionRepository` 和 `sessionEventStore`， 或配置共享 `runtimeStore`。 HTTP/SSE 服务端、浏览器客户端、多租户存储、幂等、 审批和遥测见 [Server Runtime](https://npmcn.com/package/%40blade-ai/agent-sdk/docs/server-runtime.md)。 多实例持久化见 [Runtime Store](https://npmcn.com/package/%40blade-ai/agent-sdk/docs/runtime-store.md)。 worker 协调与崩溃恢复见 [Worker Runtime](https://npmcn.com/package/%40blade-ai/agent-sdk/docs/worker-runtime.md)。 容器隔离、资源限制、checkpoint 与短期凭据见 [Execution Host](https://npmcn.com/package/%40blade-ai/agent-sdk/docs/execution-host.md)。 公开类型的所有权与边界规则见[类型架构](https://npmcn.com/package/%40blade-ai/agent-sdk/docs/type-architecture.md)。

workspace 是可选的。没有 workspace 时，Session 和显式配置的 Agent 仍可工作，但本地文件工具和项目级发现需要具备文件系统能力的 workspace。

## 文档

-   [中文文档](https://npmcn.com/package/%40blade-ai/agent-sdk/docs/index.md)
-   [Middleware 与插件](https://npmcn.com/package/%40blade-ai/agent-sdk/docs/middleware.md)
-   [Server Runtime](https://npmcn.com/package/%40blade-ai/agent-sdk/docs/server-runtime.md)
-   [Runtime Store](https://npmcn.com/package/%40blade-ai/agent-sdk/docs/runtime-store.md)
-   [Worker Runtime](https://npmcn.com/package/%40blade-ai/agent-sdk/docs/worker-runtime.md)
-   [Execution Host](https://npmcn.com/package/%40blade-ai/agent-sdk/docs/execution-host.md)
-   [Durable Event Store](https://npmcn.com/package/%40blade-ai/agent-sdk/docs/durable-events.md)
-   [English documentation](https://npmcn.com/package/%40blade-ai/agent-sdk/docs/en/index.md)
-   [迁移到真实仓库](https://npmcn.com/package/%40blade-ai/agent-sdk/docs/migrating-to-your-repository.md)
-   [可运行 Golden Paths](https://npmcn.com/package/%40blade-ai/agent-sdk/examples/README.md)
-   [Runtime 基准](https://npmcn.com/package/%40blade-ai/agent-sdk/docs/runtime-benchmarks.md)
-   [中文更新日志](https://npmcn.com/package/%40blade-ai/agent-sdk/CHANGELOG.zh-CN.md)
-   [English changelog](https://npmcn.com/package/%40blade-ai/agent-sdk/CHANGELOG.md)

## 仓库开发

```bash
pnpm install
pnpm run lint
pnpm run type-check
pnpm run test
pnpm run build
pnpm run docs:build
```

## 发布流程

发布版本号来自 Git tag，与 commit 类型无关。每个可发布的改动仍然要在 `.changes/` 下增加一个双语 JSON fragment：

```json
{
  "type": "feature",
  "en": "Add a user-facing capability.",
  "zh-CN": "新增一项用户可见能力。"
}
```

文件名必须唯一且使用 kebab-case。`type` 只允许 `breaking`、`feature`、 `fix`、`performance`、`refactor` 和 `docs`，它决定变更日志的分节，不决定版本号。

要发布，就给 `main` 上的提交打 tag 并推送该 tag：

```bash
git tag v7.4.2
git push origin v7.4.2
```

发布工作流随后以该 tag 的代码树为准：

1.  先 checkout 它声明的 tag，并在**构建之前**把该版本号写进 `package.json`，避免 bundle 与 tarball manifest 携带上一个版本；
2.  校验 fragment、lint、类型检查、构建并测试 package 和文档；
3.  校验构建产物确实带有该版本号后，把 `v7.4.2` 原样发布到 npm 并带上 provenance——不会产生别的版本号；
4.  在 `main` 上用一次 `chore(release): 7.4.2` 提交记录版本号、两份变更日志和已消费的 fragment；
5.  用双语说明创建 GitHub Release。

推送到 `main` 不再触发发布。用 `pnpm run changelog:check` 校验 fragment； 先在本地打 tag，再用 `pnpm run release:dry --tag v7.4.2` 预演发布。

更多贡献约定见 [CONTRIBUTING.md](https://npmcn.com/package/%40blade-ai/agent-sdk/CONTRIBUTING.md)。

## 许可证

[MIT](https://npmcn.com/package/%40blade-ai/agent-sdk/LICENSE)

## 常见问题

### @blade-ai/agent-sdk 是什么？

刀锋AI特工SDK

### 如何安装 @blade-ai/agent-sdk？

在项目目录运行 npm install @blade-ai/agent-sdk，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 create-blade-agent，可以用 npx create-blade-agent 直接运行。

### @blade-ai/agent-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @blade-ai/agent-sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @blade-ai/agent-sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.14\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @blade-ai/agent-sdk 可以商用吗？

@blade-ai/agent-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @blade-ai/agent-sdk 的下载量有多少？

根据 npm 官方下载统计，@blade-ai/agent-sdk 在 2026/10/09 – 2026/11/07 这 30 天内被下载 2,171 次，日均约 72 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @blade-ai/agent-sdk 还在维护吗？

最新版本 7\.4\.16 发布于 2026/10/18（21 天前）；至今共发布 123 个版本，其中过去 12 个月发布了 123 个；首次发布于 2026/02/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。