# @agent-relay/session 中文文档

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

版本：17\.0\.0
npm 元数据更新时间：2026-11-05T07:53:33.401Z
中文译文更新时间：2026-11-05T22:41:27.913Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：94.6 kB，22 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：1 个
- 首次发布：2026-08-13T19:22:53.297Z
- 最新版本发布：2026-11-05T07:53:32.978Z
- 近 30 天下载量：11031（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：78（近 12 个月 78 个）

## 中文简介

代理中继器的横断面连续性和归属性

## 安装

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

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

## README

# @ agent-relay/会话

代理中继的可移植会话连续性 。 SDK保持一个稳定的中继 跨越机器和人工智能的会话ID,同时保留不可改变性 拥有者、当前方向盘和完整的控制转移审计线索.

## 安装

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

设定 `RELAYHISTORY_URL` 到中继历史部署。 客户端接受 URL 有无 `/v1` 后缀.

```sh
export RELAYHISTORY_URL=https://history.agentrelay.com
export RELAYHISTORY_TOKEN=...
```

`RELAYHISTORY_ACCESS_TOKEN` 财务报告和审定财务报表 `RELAY_AGENT_TOKEN` 作为符号支持 堕倒.

已完成的会话重放也加入了全工作空间的中继广播对话. 设定 `RELAY_WORKSPACE_KEY` (或 `AGENT_RELAY_WORKSPACE_KEY`和,对于不违约 部署, `RELAY_BASE_URL`编辑 `relay session replay` CLI 使用工作空间 当两个工作空间键变量都不是时, 已经为当前工程选中 设置.

## 开始并日志会话

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

const sessions = new SessionClient({ cli: 'claude', node: 'danny-mac' });
const owner = {
  userId: 'usr_danny',
  email: 'danny@example.com',
  displayName: 'Danny',
};

const session = await sessions.createSession({
  cli: 'claude',
  node: 'danny-mac',
  owner,
});

// Best effort: failures do not interrupt the harness. Pass onWriteError to
// SessionClient when the host wants logging or telemetry for failed writes.
void sessions.writeTurn({
  sessionId: session.sessionId,
  role: 'user',
  content: 'Continue the migration.',
  actor: owner,
});
```

## 再来一次

```ts
const sessions = new SessionClient({ cli: 'codex', node: 'dev-mac' });
const { session, turns, resume } = await sessions.resumeSession(relaySessionId);

if (resume.mode === 'native') {
  // Only selected for a Claude-origin session resumed by Claude.
  launchClaude(['--resume', resume.nativeResumeId]);
} else {
  // Codex, OpenCode, Grok, Cursor, and every cross-CLI handoff use this path.
  launchHarness({ prompt: resume.contextPrompt });
}
```

注入的提示包含命令、 归结的 Relay History 日记和 标记为引用的上下文。 编码会话是仅限日记的,包括 代码对Codex的交接.

## 重放已完成的多代理会话

```ts
const replay = await sessions.replaySession(relaySessionId);

console.log(replay.contextPrompt);
console.log(replay.conversation.availability);
console.log(replay.conversation.retention);
```

`replaySession` 加入中继历史翻转, 并加盖中继广播信件 同会话引用,获取每个中继广播页面,并命令添加 时间戳。 重播是整个工作空间的 所以谈话片段 尽管Relay History 日记是每个节点的,但继续横跨节点。 一个不见了 节点日记仍然可以省略节点的自带回转;回放标签 并且不推断中继历史的完整性.

每一次重放都会打印出有效的再播保留边界. `partial`, (中文(简体) ), `aged_out`,并标出未知/未成功结果 `INCOMPLETE` 而不是将空谈作为代理人的证据 没有沟通。 因此,可以达到的谈话只能延伸到 作为工作空间计划的有效保留政策.

## 记录方向和属性

```ts
await sessions.recordSteering({
  sessionId: relaySessionId,
  actor: {
    userId: 'usr_dev',
    email: 'dev@example.com',
    displayName: 'Dev',
  },
  relayMessageId: '213570121302978560',
});

const trailers = await sessions.getGitTrailers(relaySessionId);
// Append trailers.join('\n') to the commit message.
```

拖车包括去重复 `Co-authored-by` 身份加稳定 `Relay-Session-*`,活性演员,起源-CLI,和起源-节点归属.

## 中继历史电线合同

SDK 使用现有的 RelayHistory 日记端点 :

-   `POST /v1/sessions/:sessionId/turns`
-   `GET /v1/sessions/:sessionId/turns`

创建和引导是持久的系统,其元数据充满 `RelaySession` 示意图. 普通用户、助手和系统转换使用 同样的日记。 这使得后端日记成为真理的唯一来源 关于对话的背景和身份审计线索.

## 常见问题

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

代理中继器的横断面连续性和归属性

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

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

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

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

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

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

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

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

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

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

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

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

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

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