# @agent-relay/agent 中文文档

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

版本：7\.1\.1
npm 元数据更新时间：2026-05-25T06:54:04.033Z
中文译文更新时间：2026-11-06T13:29:52.663Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：140 kB，30 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-05-12T18:54:20.267Z
- 最新版本发布：2026-05-25T06:54:03.741Z
- 近 30 天下载量：3125（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 27 个）

## 中文简介

![Agent Relay](https://npmcn.com/package/readme-banner.png)

## 安装

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

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

## README

![Agent Relay](https://npmcn.com/package/readme-banner.png)

# @ agent-relay/ agent( 代理服务器)

主动的代理跑步时间——一个接线员,三个触发器,一个工作空间.

[![npm](https://img.shields.io/npm/v/@agent-relay/agent)](https://www.npmjs.com/package/@agent-relay/agent) [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://npmcn.com/package/LICENSE)

**网站:** [agentrelay.com (英语)](https://agentrelay.com/) • 妇女 **文档 :** [extrelay.com/docs (英语)](https://agentrelay.com/docs)

## 它会做什么

`@agent-relay/agent` 让开发商在不到10分钟和~30行的代码内运送主动代理. 一个 `agent({ ... })` 一号电话 `onEvent` 处理器和运行时间将克龙调度表、文件表和收件箱信息接入单一的常态流——共享工作空间+ `ctx`政策定位、重试、破解和追踪.

这是建立在 [`@agent-relay/events`](https://npmcn.com/package/%40agent-relay/events) (Layer 2——迁移-不可知事件流)并曝光了工作空间-意识 第3层表面开发者实际上想要调用.

## 安装

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

## 快开始

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

const handle = agent({
  workspace: 'support',
  schedule: { every: '5m' },
  watch: ['/linear/issues/**'],
  onEvent: async (event, ctx) => {
    switch (event.type) {
      case 'cron.tick':
        await ctx.messages.post({ channel: '#triage', text: 'tick' });
        return;

      case 'relayfile.changed':
        const issue = await event.expand('full');
        await ctx.once(`triage:${event.id}`, async () => {
          // dedup-safe work
        });
        return;
    }
  },
});

// ... later
await handle.stop();
```

## 处理者合同

每个处理器都收到 `(event, ctx)`数字 :

-   `event` - 正常化 [`AgentEvent`](https://npmcn.com/package/%40agent-relay/events) 信封(轻;呼叫) `event.expand('full')` 页:1
-   `ctx` 工作空间认识背景: `ctx.workspace`, (中文(简体) ), `ctx.agentId`, (中文(简体) ), `ctx.logger`, (中文(简体) ), `ctx.signal` (AbortSignal), (美国英语), `ctx.schedule.{at,every,cancel}`, (中文(简体) ), `ctx.once(key, fn)`, (中文(简体) ), `ctx.files`, (中文(简体) ), `ctx.messages`

## 政策执行

```ts
agent({
  workspace: 'support',
  policy: { mode: 'approval-required', approvals: ['#triage-leads'] },
  onEvent: async (event, ctx) => {
    // each side-effect is gated through policy
    await ctx.messages.post({ channel: '#triage', text: 'ack' });
  },
});
```

| 模式 | 行为 |
| --- | --- |
| `suggest` | Ctx 的表面意图; 不执行 |
| `auto` | 立即执行( 默认) |
| `approval-required` | 阻止人类通过 `approvals` 频道 |

## 托管代理部署

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

await deployAgent({
  name: 'support-triage',
  workspace: 'support',
  source: './agent.ts',
  provider: { mode: 'byok' },
});
```

(见 [主动代理 运行时光谱 §7](https://github.com/AgentWorkforce/cloud/blob/main/docs/proactive-runtime/spec.md) 为主机代理语义学. )

## 燃烧( LLM 调用标记)

LLM 呼叫内部 `ctx.*` 自动标记为 `(workspace, agentId, event.type, event.id)` 可通过 `burn`。将任意代码路径与 `withBurnTags({...}, fn)` 如果您需要添加自定义尺寸.

## 相关

-   [`@agent-relay/events`](https://npmcn.com/package/%40agent-relay/events) —— 第2层规范事件流,其基础是
-   [`@agent-relay/sdk`](https://npmcn.com/package/%40agent-relay/sdk) ——经纪人控制+工作流程协调
-   [主动代理运行时光谱](https://github.com/AgentWorkforce/cloud/blob/main/docs/proactive-runtime/spec.md) - 这个装置的设计

## 许可证

阿帕奇-2.0 — 见 [自由主义](https://npmcn.com/package/LICENSE)。 。 。 .

## 常见问题

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

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

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

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

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

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

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

@agent-relay/agent 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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