# @agent-relay/harnesses 中文文档

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

版本：17\.2\.1
npm 元数据更新时间：2026-11-07T03:55:48.051Z
中文译文更新时间：2026-11-05T18:43:45.842Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：281 kB，54 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：8 个
- 首次发布：2026-06-04T13:31:48.697Z
- 最新版本发布：2026-11-07T03:55:47.583Z
- 近 30 天下载量：58370（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：156（近 12 个月 156 个）

## 中文简介

为代理中继器预建了套接字定义.

## 安装

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

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

## README

# @ agent-relay/harneses (英语)

本地编码代理器的预置绳接定义. 要求节点.js 22或更新.

使用此软件包 `@agent-relay/harness-driver` 当代理中继器创建或监督管理的会话时.

## 运行时间选择

Claude Code, Codex, and OpenCode 既提供了官方AI SDK本土的取用运行时间,也提供了现有的PTY运行时间. 他们的适配器从实验开始,所以 `auto` 继续选择 PTY ,直到每个适配器通过升级门.

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

await claude.create({ relay }); // auto: PTY while the adapter is experimental
await claude.create({ relay, runtime: 'native' }); // explicit native harness runtime
await claude.create({ relay, runtime: 'pty' }); // explicit terminal runtime
```

运行时间选择在会话开始前是最终的 。 中继不会在PTY和AI SDK之间切换运行的会话.

| 节奏 | AI SDK 适配器 | PTY 主题 | 初始选择 |
| --- | --- | --- | --- |
| 克劳德代码 | `@ai-sdk/harness-claude-code@1.0.35` | 对 | PTY; 本地语是明确和实验的 |
| 代码 | `@ai-sdk/harness-codex@1.0.40` | 对 | PTY; 本地语是明确和实验的 |
| 打开代码 | `@ai-sdk/harness-opencode@1.0.35` | 对 | PTY; 本地语是明确和实验的 |
| Pi | `@ai-sdk/harness-pi@1.0.34` | 没有 | 明显的实验性本土 |
| 深层特工 | `@ai-sdk/harness-deepagents@1.0.33` | 没有 | 明显的实验性本土 |
| 进取 | 无 | 对 | 保留有批准提示的 PTY |
| 其他内置 | 无 | 对 | PTY 主题 |

见 [Devin CLI 设置和限制](https://npmcn.com/package/docs/harnesses/devin.md) 用于认证、工作空间信任和孤立的 MCP 配置.

皮和深层特工需要 `runtime: 'native'` 在实验期间 深层代理公司不发布人工收缩广告,停止其目前的适配器不会保留记忆中的对话.

机能执行是 `pty` 或者说 `native`。经纪人可在内部将本地的绑带和附带的应用程序服务器包装为 `headless` 进程,但 `headless` 不是一个可观察模式。 两种执行路径都发布相同的常态化 `AgentEvent` 合同.

本地会话在启动时收到认证的代理中继主机工具和协作指示. 他们可以发现代理商和频道,检查或搜索消息,发送DM,发送到频道,并回复线索,而无需依赖提供者-全球MCP配置或用户的额外提示.

## 原生带附着

AI SDK会话揭露代理事件历史和现场事件而不是终端字节:

```bash
agent-relay node agent attach my-agent --mode view
agent-relay node agent attach my-agent --mode drive
agent-relay node agent attach my-agent --mode view --json
agent-relay node agent attach my-agent --mode view --reasoning --diagnostics
```

`view` 只读. `drive` 在经纪人确认后发送每个输入行; `/interrupt`, (中文(简体) ), `/approve <id>`, (中文(简体) ), `/reject <id>`,以及 `/detach` 属于本地控制. `passthrough` 无法使用, 因为本地磁带会话没有终端字节流 . `--json` 写入已正常的 NDJSON 以退出 。 理由和诊断除非有要求,否则保密.

## 观察性

AI SDK流是Relay的参考可观察性剖面. 中继发布便携式代理事件和活动 `starting`, (中文(简体) ), `thinking`, (中文(简体) ), `typing`, (中文(简体) ), `using_tool`, (中文(简体) ), `waiting`, (中文(简体) ), `idle`,以及 `error`每个事件都有其来源,其中之一 `exact` 或者说 `inferred` 忠诚.

PTY会话使用相同的能力矩阵. 今天,经纪人提供确切的启动和运行时间失败,加上推断的繁忙和闲置边界. 终端字节无法证明的信号,包括推理,文本块,工具,批准,文件,和收缩,被报告为不可用,而不是被猜测.

另一个中继程序可以通过消息表层检查成功被接受到中继广播的持久代理日志中的事件:

```ts
const activity = await relay.messaging.sessionEvents?.list('my-agent', {
  type: 'activity.changed',
  limit: 100,
});
```

经纪人拥有每个产卵表面的PTY出版物. 管理 `create({ relay })` 给本地的听众打电话 `AgentRelay` 举个例子.

托管出版物在业务上是可观察的,而不是无损失的审计分类账。 经纪人通过限定的出版商队列和日志队列,超时,以及本地重播故障来维护秩序;在持续断电或经纪人崩溃期间,事件可以缺席.

## 当地东道国的安保和解决问题

AI SDK本地主机提供商是一个过程和文件系统生命周期边界,不是操作系统沙盒. 它拒绝Lexical traversal and statistic symlink 为适配器文件操作进行最优的逃生,在将桥端端口交给适配器进程之前,以回转方式将桥端端口搁置,并终止它所启动的唯一子进程. 由另一个过程所实现的并发文件系统突变在此边界外,所以路径守护不安全,不能用作对不可信代码的隔离.

本地主机AI SDK运行时间目前支持macOS和Linux. 在 Windows 上,使用 PTY 运行时间;在输入平台出错的情况下,一个明确的本地选择失败,而不是尝试 POSIX 适配器靴陷阱命令. 飞行前检查月台 22号节点, `pnpm`,工作空间访问,缓存访问,以及回路端口分配. 如果启动失败, 请先验证这些命令和权限 。 Bootstrap 工作通过运行时缓存下的稳定适配器身份来缓存;删除无关的工作空间文件从来不是清理的一部分.

适配器升级必须保留 `@ai-sdk/harness@1.0.34` 在改变适配器的推出状态之前,家庭统一并通过注册、生命周期、代理活动重放、可观察性、真实CLI和100循环浸泡合同.

## 常见问题

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

为代理中继器预建了套接字定义\.

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

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

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

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

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

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

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

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

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

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

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

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

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

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