# @ai-matrx/desktop-protocol 中文文档

规范地址：https://npmcn.com/package/%40ai-matrx/desktop-protocol/

版本：0\.21\.102
npm 元数据更新时间：2026-10-28T12:44:59.305Z
中文译文更新时间：2026-11-05T19:04:38.820Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ai-matrx/desktop-protocol
原文对照：https://npmcn.com/package/%40ai-matrx/desktop-protocol/?lang=original
项目主页：https://github.com/AI-Matrix-Engine/aidream/tree/main/apps/shared/desktop-protocol#readme
源码仓库：https://github.com/AI-Matrix-Engine/aidream

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

- 包体积（解压后）：8.9 MB，48 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：3 个
- peer 依赖：react \>=18\.0\.0
- 首次发布：2026-10-02T05:30:00.067Z
- 最新版本发布：2026-10-28T12:44:59.101Z
- 近 30 天下载量：47110（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：136（近 12 个月 136 个）

## 中文简介

Matrx 2 (桌面应用) 和每个驱动它的客户端之间的一份电线合同——电话,网络应用,扩展,服务器: zod schemas for the billet and every cap.op, 16字节二进制帧代码c, 一个重新连接的请求/流/信用/reattach clien

## 安装

```sh
npm install @ai-matrx/desktop-protocol
```

也可以使用：`pnpm add @ai-matrx/desktop-protocol`、`yarn add @ai-matrx/desktop-protocol`、`bun add @ai-matrx/desktop-protocol`

## README

# `@ai-matrx/desktop-protocol`

**Matrx 2(桌面应用)和一切驱动器之间的一份电线合同** - 那个 电话控制台、网络应用程序、扩展和服务器。 一个 Zod 源; 一个生成的 JSON Schema 和CI保持字节相同的平面双胞胎(SPEC P11:合同生成,从未写入) (两次).

```bash
pnpm add @ai-matrx/desktop-protocol
```

| 条目 | 这是什么 |
| --- | --- |
| `@ai-matrx/desktop-protocol` | 信封和每个 `cap.op`, (中文(简体) ), `OPS` 编号 : `EVENTS` 登记册, `ErrorCode`关闭密码, `DesktopProtocolError`。每个计划名称也是其推断类型. |
| `@ai-matrx/desktop-protocol/frame` | 16字节二进制框架编码器. Zod-free(接力工人的热路). |
| `@ai-matrx/desktop-protocol/client` | `createDesktopClient` ——重新连接客户端与打字请求,信用加码流,透明终端重接,心跳和中继重接. |
| `@ai-matrx/desktop-protocol/react` | `DesktopClientProvider`, (中文(简体) ), `useDesktopConnection`, (中文(简体) ), `useDesktopRequest`, (中文(简体) ), `useDesktopEvent`, (中文(简体) ), `useDesktopWake`。 。 。 . |

## 客户端

```ts
import { createDesktopClient } from "@ai-matrx/desktop-protocol/client";

const client = createDesktopClient({
  url: `wss://relay.matrxserver.com/v1/devices/${deviceId}/connect`,
  // Re-read on every reconnect; tokens ride the subprotocol, never the URL.
  protocols: async () => ["matrx.v1", `bearer.${await getAccessToken()}`],
  getToken: getAccessToken, // answers relay.auth_expiring without dropping the socket
  clientType: "web",
  clientVersion: "1.0.0",
});

const listing = await client.request("fs.list", { path: "/Users/me" }); // typed by op name

const term = client.stream("exec.pty.start", { cols: 80, rows: 24 }, {
  onData: (bytes) => new Promise((done) => xterm.write(bytes, done)), // credit follows consumption
  onSnapshot: (bytes) => {
    xterm.reset();
    xterm.write(bytes);
  },
});
term.write("ls\n");
```

-   **后压 :** 流的入计量只有在 `onData` 返回(或承诺) ),所以慢接手机从不会使中继器或Mac缓冲器不受约束.
-   **重排 :** 资源流(地表和表)在空出套接字后存活。 在重新连接时 客户端发送 `session.attach` 与 `since_seq` =最后一帧您 `onData` 消耗; 核心 重放空白或发送 `gap` + 屏幕快照。 一样 `DesktopStream` 继续工作.
-   **错误** 为: `DesktopProtocolError` 与 `code`, (中文(简体) ), `retryable` 财务报告和审定财务报表 `data.reason` - 分支在 那些,从来没有在消息。 丢弃的套接字拒绝无用的工作 `DEVICE_OFFLINE` (可重审).
-   **终端关闭** (单位:千美元)`4010` 已撤销, `4003` 禁止进入, `4004` 没有找到, `4009` 替换, `4426` 升级)永远结束客户端;其他一切与共享重新连接 `@ai-matrx/data/realtime` 后置(稳定重置 + 抖动)——包括 `1006` (中继部署投放) 每个套接字没有近相框)和 `1012` (接力"设备重接":你好和 与新的核心会议相对应.
-   **回来:** `client.wake()` (或 `bindDesktopWake(client)` 编号 : `useDesktopWake()`,这叫它 打开 `visibilitychange`, (中文(简体) ), `pageshow`, (中文(简体) ), `online` 财务报告和审定财务报表 `focus`在重新连接时立即拨号 探测一个开口的套接字,如果4 s 以内无任何答案,则用接线重排.
-   **重新装入重排 :** 保留 `stream.resourceId` 财务报告和审定财务报表 `stream.lastSeq` (例如在 URL 中); 重新装入后 `client.stream("session.attach", { resource_id, since_seq })` 重放空隙, 然后表现 和原始的溪流完全一样, 包括幸存下来的后遗症.
-   背景问题( 变形消息、 序列间隙、 心跳死亡、 重接提醒) 前往 `onDiagnostic` ——默认高声(`console.warn`) (中文(简体) ).

## 当地记录

```ts
import { createDesktopTranscriber } from "@ai-matrx/desktop-protocol/client";

const transcriber = createDesktopTranscriber(client, { model: "base", onProgress: (p) => show(p) });
const { text, segments } = await transcriber.transcribe(recordingBlob); // on the person's computer
// Or as a voice input's transport: new BrowserAudioKernel({ transport: transcriber })
```

## 反应

```tsx
<DesktopClientProvider client={client}>
  <Files />
</DesktopClientProvider>

function Files() {
  const { status } = useDesktopConnection();
  const { data, error, loading, refetch } = useDesktopRequest("fs.list", { path: "/Users/me" });
  useDesktopEvent("fs.changed", () => void refetch());
}
```

## Python (英语)

```python
from aidream._generated.desktop_protocol import OPS, FsListParams, validate_wire

params = validate_wire(FsListParams, raw_json)  # same verdict as zod, always
```

`validate_wire` 是一个 Python 切入点: 严格( 否) `"2"` —— 2) 和 JavaScript- 忠实 (单位:千美元)`2.0` 是整数 2. `OPS` 将每个操作都映射到它的参数/结果模型、种类和错误.

## Python 服务( 磁盘- 桌面)

桌面监督的 Python 服务从安装的软件包中生成他们的模型 同一发电机,所以核心和服务 永远不会漂移:

```bash
python3 node_modules/@ai-matrx/desktop-protocol/scripts/gen_pydantic.py \
  --schema node_modules/@ai-matrx/desktop-protocol/generated/desktop-protocol.schema.json --out <module>.py
```

模块携带 `SERVICES`,输入处理器 `Protocol` 每项服务`MlServiceHandlers`和 `CONTRACT_SHA256`,它必须等于核心的`import { CONTRACT_SHA256 }`在服务你好.

## 修改协议

编辑 `src/schema/*.ts`,则 `pnpm generate` 并输入所有三个文件。 规则 `pnpm lint` 由 `generate`: `z.strictObject` 仅;无 `.refine`编号 :`.transform`编号 :`z.coerce`编号 : `.meta`; 永远不能同时可选和无效; 一个新的命名计划进入 `NAMED_SCHEMAS`; 添加一个 对等大小写为 `corpus/parity-corpus.json` 对于任何新的电线形状.

MIT AI 矩阵引擎

## 常见问题

### @ai-matrx/desktop-protocol 是什么？

Matrx 2 \(桌面应用\) 和每个驱动它的客户端之间的一份电线合同——电话,网络应用,扩展,服务器: zod schemas for the billet and every cap\.op, 16字节二进制帧代码c, 一个重新连接的请求/流/信用/reattach clien

### 如何安装 @ai-matrx/desktop-protocol？

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

### @ai-matrx/desktop-protocol 支持 TypeScript 吗？

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

### @ai-matrx/desktop-protocol 支持 ESM 还是 CommonJS？

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

### @ai-matrx/desktop-protocol 需要什么版本的 Node\.js？

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

### @ai-matrx/desktop-protocol 可以商用吗？

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

### @ai-matrx/desktop-protocol 的下载量有多少？

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

### @ai-matrx/desktop-protocol 还在维护吗？

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