# @fishaudio/agent-protocol 中文文档

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

版本：1\.0\.0
npm 元数据更新时间：2026-11-09T12:57:28.022Z
中文译文更新时间：2026-11-14T20:24:28.665Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40fishaudio/agent-protocol
原文对照：https://npmcn.com/package/%40fishaudio/agent-protocol/?lang=original
项目主页：https://docs.fish.audio/agents/deploy/protocol
源码仓库：https://github.com/fishaudio/fish-agent-sdk-web

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

- 包体积（解压后）：57.2 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-08-01T13:15:43.326Z
- 最新版本发布：2026-11-09T11:57:16.183Z
- 近 30 天下载量：22120（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

鱼音代理会话的电线合同:实时室道消息和会话创作外形.

## 安装

```sh
npm install @fishaudio/agent-protocol
```

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

## README

# @fishaudio/ agent-protocol (英语)

电线合同 [鱼声](https://fish.audio/) 代理会话:代理运行时间和终端用户客户端之间交换的实时室道消息,以及会话创建交换的形状. 它只包含TypeScript类型和主题常数. 零运行时间依赖,没有代码.

**这是一个半内部包.** 它住在空地上 所以在电线上行走的东西 完全可以审计 所以SDK和代理运行时间 符合一个公布的合同 它不是应用程序的API 。 不要直接依赖它. [`@fishaudio/agent-client`](https://www.npmjs.com/package/@fishaudio/agent-client) 已经再导出应用程序代码所需的类型 : `SessionToken`, (中文(简体) ), `SessionOverrides`,以及 `AgentSessionCreateRequest`。只有在建立实时通道的自定义消费者或审计协议本身时,才能获取此软件包.

## 里面的东西

### 实时频道( E)`realtime.ts`(中文(简体) )

每个信道有一个主题常数,加上载荷类型:

| 专题 | 方向 | 有效载荷 |
| --- | --- | --- |
| `AGENT_EVENT_TOPIC` | 代理人 客户 | `AgentSessionMessage`。会话控制,例如 `client_tool.call`,则 `tool.started` 编号 : `tool.completed` 编号 : `tool.failed` 生命周期, `session.ended` (带有 `SessionEndedReason`),以及 `error` (类别代码加 `stage` 财务报告和审定财务报表 `recovered`) (中文(简体) ). 每个消息一个完整的JSON对象. |
| `CLIENT_EVENT_TOPIC` | 客户 / 代理人 | `ClientSessionMessage`. 文字注入、工具结果、优雅挂起、音频准备状态报告(`client.audio_ready`) (中文(简体) ). |

两个参与者属性完成房间级合同. 它们作为常量发布 所以客户端和运行时共享一个定义:

| 常数 | 设定 | 含义 |
| --- | --- | --- |
| `AGENT_READY_ATTRIBUTE` (单位:千美元)`fish.agent.ready`(中文(简体) ) | 代理人 | 粘着 有价值的时代 输油管已直播,开通者已排队. 打开上面的"连接"UI `lk.agent.state` 作为旧时间的倒数. |
| `CLIENT_AUDIO_READY_ATTRIBUTE` (单位:千美元)`fish.client.audio_ready`(中文(简体) ) | 客户端 | `CLIENT_AUDIO_READY_PENDING` (单位:千美元)`"pending"`)在加入后宣布一个客户端将报告准备状态. epoch-ms值表示代理的音频音轨被附加并被浏览器允许回放. 跑步时间等待一个限定的时间 然后再说开场白 发布它需要一个加入符让参与者更新自己的属性. 现值也作为 `client.audio_ready` 信件内容 `CLIENT_EVENT_TOPIC`,因为 LiveKit 延迟了未发布音轨(麦克风关闭会话)的参与者的属性更新。 跑步时间需要先到者. |

译名(流程助理回复和用户ASR,临时和最终)不是本合同的一部分:他们在LiveKit的内置旅行 `lk.transcription` 文本流,按键 `lk.segment_id` 属性,与 `lk.transcription_final` 标记最终结果和流的发送者身份 区分用户和代理.

### 会话创建( O)`session.ts`(中文(简体) )

这个 `POST /v1/agent/sessions` 交换 :

-   `AgentSessionCreateRequest` 是请求体。 它携带的代理身份,每会 `SessionOverrides`,动态变量,归属字段,以及两个字段,意在后端的会话创建调用,而不是SDK的公共代理选项: `llm_extra_body` (转发到自定义 LLM 端点)和 `record_audio` (每期录制超过).
-   `SessionOverrides` 是允许列表的每会话配置替换。 它涵盖第一信息,系统即时,语音,语言,和语音识别模型.
-   `SessionToken` 是回应。 它是一个歧视工会 `transport` 并逐字交给客户.

## 公约

-   **克兴.** 会话创建形状是 `snake_case`,因为客户逐字地使用回应。 实时消息字段是 `camelCase`。 。 。 .
-   **相容性只有添加剂.** 已发布字段从不改变名称、含义或类型 。 新字段是可选的 。 语义变化的船作为新的 `type`消费者必须忽略未知 `type` 值和未知字段。 然后老客户端继续工作 随着协议的增长.
-   **运输业.** `SessionToken.transport` 是一个受歧视的工会。 不识别谈判臂的消费者必须以明显的升级出错而失败,永远不要沉默.

## 常见问题

### @fishaudio/agent-protocol 是什么？

鱼音代理会话的电线合同:实时室道消息和会话创作外形\.

### 如何安装 @fishaudio/agent-protocol？

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

### @fishaudio/agent-protocol 支持 TypeScript 吗？

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

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

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

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

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

### @fishaudio/agent-protocol 可以商用吗？

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

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

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

### @fishaudio/agent-protocol 还在维护吗？

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