# @agent-relay/fleet 中文文档

规范地址：https://npmcn.com/package/%40agent-relay/fleet/

版本：17\.2\.0
npm 元数据更新时间：2026-11-06T17:00:06.266Z
中文译文更新时间：2026-11-06T06:54:47.669Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：91.2 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：5 个
- 首次发布：2026-06-16T06:12:35.708Z
- 最新版本发布：2026-11-06T17:00:05.452Z
- 近 30 天下载量：24288（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：140（近 12 个月 140 个）

## 中文简介

舰队节点SDK代表中继特工.

## 安装

```sh
npm install @agent-relay/fleet
```

也可以使用：`pnpm add @agent-relay/fleet`、`yarn add @agent-relay/fleet`、`bun add @agent-relay/fleet`

## README

# @ agent-relay/ fleet (英语)

舰队节点SDK代表中继特工 定义 a **节点** ——一个命名为主机,发布打字广告 **能力** (动作和产物)和反应 通过 **触发** 那么... 说吧.. 给它服务 `agent-relay fleet` CLI(英语:CLI).

使用 `@agent-relay/fleet` 当您想要曝光本地能力时( 运行一个命令, 生成一个 hand, 答复请求)到接力工作空间作为长生节点. 使用 `@agent-relay/sdk` 用于纯代理信件和 `@agent-relay/harness-driver` 启动和监督本地 直接控制进程.

完整文档 : [extrelay.com/docs (英语)](https://agentrelay.com/docs)。 。 。 .

## 安装

```bash
npm install @agent-relay/fleet zod
```

## 快开始

```ts
import { defineNode, action, spawn, onMessage } from '@agent-relay/fleet';
import { z } from 'zod';

export default defineNode({
  name: 'builder',
  capabilities: {
    'run:test': action({ input: z.object({ suite: z.string() }) }, async ({ input }) => {
      // ...run the suite...
      return { ok: true, suite: input.suite };
    }),
    'spawn:claude': spawn({ harness: 'claude' }),
  },
  triggers: [
    // When a message matching the pattern lands in #deploys, invoke run:test.
    onMessage({ channel: '#deploys', match: /[Ss]hip/ }, 'run:test'),
  ],
});
```

交给CLI:

```bash
agent-relay node up --config ./builder.node.ts
# or drop the file at the project root as agent-relay.ts and run `agent-relay node up` (auto-discovered)
agent-relay fleet nodes      # list registered nodes
agent-relay fleet status     # show node + capability health
```

### 仓库放置

一个节点可以宣布它可以用一个 `owner/repo` 密钥映射 :

```ts
export default defineNode({
  name: 'builder',
  repoPaths: {
    'AgentWorkforce/factory': '/srv/repos/factory',
    'AgentWorkforce/relay': '/srv/repos/relay',
  },
  capabilities: {/* … */},
});
```

每个值必须是该节点上的绝对路径. 登记来源于 安置安全 `AgentWorkforce/factory` 财务报告和审定财务报表 `AgentWorkforce/relay` 键; 键 绝对值从不发送到中继广播、在名册中曝光或登录.

### 在方案方面担任节点

`@agent-relay/fleet` 也传送节点运行时间, 这样您就可以在其中启动一个节点 没有 CLI 的进程 :

```ts
import { defineNode, serveNode, startServeNode } from '@agent-relay/fleet';

const definition = defineNode({
  name: 'builder',
  capabilities: {/* … */},
});
const connection = { url: 'http://127.0.0.1:8787' }; // broker HTTP API base URL (apiKey optional)

// startServeNode returns a RunningNode { stop(), done } for supervised use…
const running = startServeNode({ definition, connection });
// …await running.done to block until the node stops, or call running.stop().
await running.stop();

// serveNode runs the node to completion (resolves when it stops / aborts).
await serveNode({ definition, connection });
```

### 特工人员

服务 `spawn(...)` 处理者要求核实准备状态,并在完成后完成 委托经纪人报告一名随时待命的工人。 发射失败向呼叫者传播. 引擎必须支持节点所属的产卵援引状态 限为130秒。 如果确认被中断,则核对所报告的 重试前引用孩子, 因为经纪人可能仍在完成设置 . 在发布/更新机队软件包之前释放兼容引擎 服务。 仅供遗留的安置操作员使用,操作员可以明确 设定 `spawn(harness, { verifyReady: false })` 或者说 `ctx.spawnAgent({ agent, verifyReady: false })`。 。 。 . 这样会跳过投票准备和返回 `{ placement, ready: false, readiness: 'unverified' }`· ; 它不能用作确认的启动或授权订阅创建。 已验证 准备状态仍然是默认的,必须保留给订阅者.

内置 `spawn:<harness>` 能力发射原始的带子。 一个 Agent Workforce persona) 也带有其常备指示,已安装的技能, MCP服务器、机床、模型和机床设置,必须加以解决 准备作为目标节点上的单位.

使用 `defineWorkforcePersonaSpawnNode` 从 `@agentworkforce/local-surface` 改为 广告 `spawn:persona` 能力:

```ts
import { serveNode } from '@agent-relay/fleet';
import { defineWorkforcePersonaSpawnNode } from '@agentworkforce/local-surface';

const definition = defineWorkforcePersonaSpawnNode({
  nodeName: 'workforce-personas',
  cwd: process.cwd(),
});

await serveNode({ definition, connection });
```

呼叫者可以通过 `persona` (id或JSON路径)代替 `cli` 页:1 代理中继 `spawn` MCP工具. 人产卵由SDK支撑并报告为 只有在节点登记和拉带准备握手后才能成功.

### 日志

节点运行时间发布结构化事件——每个节点注册的能力和每个节点运行时间 击出动作(引出/完成/失败,持续时间)——通过 `logger` 注射药 形状匹配 `@agent-relay/utils`' `createLogger`,以及 每个事件都有结构化 `extra` 袋( 装入`{ capability, action, invocationId, ms, … }`)所以文件和JSON汇可以在字段上按键:

```ts
import { createLogger } from '@agent-relay/utils';

await serveNode({ definition, connection, logger: createLogger('fleet') });
```

通过CLI, `agent-relay node up` 显示此代码 :

```bash
agent-relay node up --config ./builder.node.ts --log-file ./node.log
agent-relay node up --config ./builder.node.ts --log-level debug   # include per-capability lines
agent-relay node up --config ./builder.node.ts --log-json          # one JSON object per line
```

能力登记记录 `debug`; 行动引用于 `info`; 失败 `warn`没有 `logger` 节点是沉默的——通过 `logger` (或老年人) `log`编号 :`warn` 调用)以接收事件. CLI线a `warn`\- 只在没有时沉入 `--log-*` 旗帜是 给,所以 `agent-relay node up` 保持安静,除了警告,直到你选择加入.

## 概念

-   **节点** ——在工作空间注册的有名主机. `defineNode` 验证清单 在前面返回 a `FleetNodeDefinition`。 。 。 .
-   **能力** ——按名键进行打字操作. 以 `action(...)` (处理者) 带有可选 Zod 输入方案)或 `spawn(...)` (一种发射绳索的能力).
-   **触发** ——一条规则,对频道消息援引能力. 创建一个 与 `onMessage({ channel?, match?, mention? }, actionName)`。 。 。 .

## 触发和 `match`

`match` 接受字符串( substring/ 准确匹配) 或 a `RegExp`模式序列化为 中继和匹配的经纪人侧.

> **尚未支持 Regex 旗帜 .** `defineNode` **拒绝** 触发器 `match` 是一个 标记 `RegExp` (例如:. `/ship/i`, (中文(简体) ), `/ship/m`而不是默默地降下国旗——a 默不作声地剥去旗帜会改变匹配的语义而不发出警告. 直到旗帜支持 土地,编码为字符类的不敏感案例:
> 
> ```ts
> onMessage({ match: /[Ss]hip/ }, 'run:test'); // ✅ case-insensitive via character class
> onMessage({ match: /ship/i }, 'run:test'); // ❌ throws at defineNode validation
> ```

## 许可证

阿帕奇 - 2.0

## 常见问题

### @agent-relay/fleet 是什么？

舰队节点SDK代表中继特工\.

### 如何安装 @agent-relay/fleet？

在项目目录运行 npm install @agent-relay/fleet，或使用 pnpm add / yarn add / bun add。

### @agent-relay/fleet 支持 TypeScript 吗？

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

### @agent-relay/fleet 支持 ESM 还是 CommonJS？

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

### @agent-relay/fleet 需要什么版本的 Node\.js？

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

### @agent-relay/fleet 可以商用吗？

@agent-relay/fleet 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @agent-relay/fleet 的下载量有多少？

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

### @agent-relay/fleet 还在维护吗？

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