# @cherrystudio/remote-protocol 中文文档

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

版本：0\.7\.0
npm 元数据更新时间：2026-10-22T03:46:17.505Z
中文译文更新时间：2026-11-09T12:36:58.462Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40cherrystudio/remote-protocol
原文对照：https://npmcn.com/package/%40cherrystudio/remote-protocol/?lang=original
源码仓库：https://github.com/CherryHQ/cherry-studio

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

- 包体积（解压后）：326 kB，14 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：zod ^4\.3\.4
- 首次发布：2026-09-24T10:03:36.678Z
- 最新版本发布：2026-10-22T03:46:17.243Z
- 近 30 天下载量：13840（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

樱桃工作室远程访问协议计划 和代理回收合同.

## 安装

```sh
npm install @cherrystudio/remote-protocol
```

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

## README

# 远程协议

由桌面和移动公司共同拥有的可移植化学和纯剂回收功能. 根拥有JSON-RPC和连接合同. 代理和配置传输 具有单独的导出;既不拥有套接字、密钥、持久性,也不重新连接. 根还拥有共享的发现服务类型, TXT 格式和固定 WebSocket 路径。 这些是樱桃同行互操作性合同,而不是听众或路由政策.

发表于 `@cherrystudio/remote-protocol` 通过寄存器的更改器发布 工作流程。 软件包版本独立于谈判的电线协议跟踪 版本。 仅凭建构或通过包件测试,并不能对桌面,博览会或中继互操作性进行限定.

运行 `pnpm --filter @cherrystudio/remote-protocol test`, (中文(简体) ), `typecheck` 财务报告和审定财务报表 `build`。 。 。 . 外部消费者通过包出口进入,从未 `src/` 深度进口.

事件会减少缓存, 将文本字节长度逐一缩短, 无需添加线条 字段。 仅在初始长度计算后追加新文本编码; 恢复或替换 部件计算自己的长度。 制片人读取 `part.append` 通过出口抵消 `textByteLength`,因此发送并验证一个附件共享一个缓存条目。 完成后仍检查全部内容摘要并确实 不继承流快照的缓存 。 旧的快照仍然可以独立使用 用于原子恢复; 其被弱控的缓存项随这些物体而消失.

## 连接地址

`connection.hello.connectionEndpointsVersion: 1` 广告 `connection.endpoints`。 。 。 . 请求中指定一个已经核准的域名; 桌面重新检查其当前授权 准备答复前后。 结果包含桌面身份和 最多32个直接终点,没有邀请或VPN证书. 客户端给 身份,保持建议短暂性,并且只坚持经过明确核实的选择. 没有这种可选能力的同行保留了现有的对接和人工地址流动.

## 失败的结果

`./failure` 拥有由活执行和消息共享的已绑定的执行失败快照 历史 信件带有明确的待处理/成功/错误/被搁置状态。 执行失败需要 失败和终端消息身份。 终端持续性或随消息持久 和历史修改,或 不可持久,单独持续失败。 RPC 授权错误 并且指令性收款仍然独立于执行结果.

`connection.hello.agentFailureVersion: 1` 广告本合同。 新客户需要它给特工 只访问; 配置和配对保留其现有的协议。 旧处决 `error` 字段 仍然是相容性投影。 缺少所需字段的旧缓存预测重建自 a 检查站。 上游未知原因分类为: `unknown`; 电线快照验证 版本理性词汇,不重写检查站文摘使用的字节.

## 互动和工作空间增加

-   互动摘要可声明 `kind: question`; 完整的问题保留在版本输入中 资源与使用 `questionInputSchema`反应是明确批准、否定和不选择的理由, 或用问题键值回答。 对照当前相互作用验证完整性 主机; 方案验证形状和界限。 问题文本密钥必须是独一无二的.
-   工作空间目录广告 `systemWorkspace`; 创建接受明确的系统或注册 选择。 主机拥有目录分辨率并返回真实的工作空间ID和类型.
-   遗产平原 `decision` 财务报告和审定财务报表 `workspaceId` 变异仍被接受,包括日记回收. 申请必须选择一种形式。 新客户对已有客户使用遗留表格 操作和添加的明确表格; 旧目录并不意味着系统支持.
-   命令身份包括完整答案或工作空间选择. 使用相同的ID重试 而不同的输入则是一种自相矛盾,从不是一种替换操作.

代理目录可选择包含 `emoji` (非空Unicode文本,最多64个UTF-16单位). 它显示的是元数据,而不是文件路径或 URL 。 与旧主机兼容; 客户保持正常回落。 图像传输在本字段合同之外.

### 信件使用情况

`AgentMessage.usage` 是一个可选的可实现摘要。 它带有非负数的符号数, 缓存/理由分类账、按货币计价和要求计价以及完成运行时间 期限。 缺席意味着未知,而不是零。 它故意排除了按要求进行的会计科目 和运行时间跨数组。 信息拥有快照,所以历史反应,消息更新, 检查点/重放时使用一个方案。 年长的同龄人可能忽略它;配对能力门不变.

可选的公开模型摘要(`modelId`, (中文(简体) ), `providerId`, (中文(简体) ), `name`) 由信件快照共享 和代理目录条目。 一个消息记录其生成模式; 目录记录当前 配置 (`null` 对未配置,对旧主机省略。 也不带供应商的秘密 或要求接收设备安装模型.

### 对齐地址

`pairingQrSchema` 接受遗留 v2 IP/ port 邀请和 v3 邀请并完成 `endpoints` (单位:千美元)`host`, (中文(简体) ), `port`, (中文(简体) ), `security`) (中文(简体) ). `fixtures/pairing-qr.json` 也由 Mobile的轻量级启动计划. 更改电线合同时保持固定副本对齐. `parseDirectEndpoint` 接受HTTP(S)输入作为WS(S)的同名词,保留TLS和显式端口. 固定路线还在 `/v1/remote/connect`; 广告终点使用 `advertisedEndpointSchema` 拒绝回转和通配符目的地.

## 页面信件摘要

`connection.hello.agentMessageSummariesVersion: 1` 广告可选 `agent.messages.list` 参数 `partsMode: 'paged'`只发送此参数 在观察能力后 没有答复,答复仍然完整 `partIds`。 。 。 .

页面答复中包含 `AgentMessageSummary` 项:信息身份、修订、, 角色、地位和可选用途/模型/失败元数据 `partsMode: 'paged'` 没有 `partIds`。通过 `agent.parts.list` 使用信件 身份证和审校: `nextCursor` 直到无效。 省略的索引不是 空消息来. 历史和部分修订检查保持不变.

`AgentMessageListItem` 是完整的信息/摘要结合。 摘要只列出; 事件、检查站和减少人员仍需要全部 `AgentMessage` 示意图. 没有能力的同伴保持现有的请求和响应形状.

响应预算返回中不可分割的列表项目 `RESOURCE_EXHAUSTED` 与 `details: { kind: 'ITEM_TOO_LARGE', itemBytes, budgetBytes, retryable: false }`。 。 。 . 同样的请求和数据无法通过等待恢复. 其他资源已用尽 错误保留其语义;遗留客户端可能忽略其他细节.

## 备用代理附件

`connection.hello.agentUploadsVersion: 1` 制作/获得/恢复/完成/取消和二进制DATA/ACK记录. 上传身份被限定为设备和代理授权,独立于套接字和会话. 一个持久 `committedOffset` 这是唯一的恢复位置. `resume` 使用同位素还原ID 和预期的作家时代; 老作家不能推进替换上传。 DATA携带由噪声AEAD认证的生字节,每个块后有一个可耐用的ACK. 桌面在发布现成的管理下的参考文献前计算完整文件SHA-256. 可选 `agentUploadChecksum: 'sha256'` hello 能力支持独立的源验证 : 准备修正 `checksumAlgorithm`,完整的用品 `expectedSha256`返回实际 `sha256`。不匹配会变成持久的失败状态 `CHECKSUM_MISMATCH`; 磁盘/出版物出错 使用情况 `VERIFICATION_FAILED`。修改记录的文摘或模式是一种偶应冲突. 缺席-模式上传保留了遗产行为. 新的移动散列 其保留不可改变的来源 本土 与正常 DATA 传输并行; 恢复在恢复写入前比较保存的文摘.

限制:1个GiB/file,2个GiB/message,8个文件,1个MiB区块和2个未决区块. 24小时闲置后失效或共计7天,4个GiB/device和8个GiB/Global 保留。 上传权限和到期后会独立于电文收据进行再检查. 发送接受文本,文件,或两者兼有. 客户端冻结持久发送中的上传引用 命令,然后在提交和查询该命令在不确定结果之后的接收. 它们绝不能在已经提交的命令中替换过期的上传引用 .

上传的文件历史使用一个有修订约束的内容引用,从不使用桌面文件系统路径. 内容页在目前的代理赠款下阅读,并与完整的摘要核对.

## 常见问题

### @cherrystudio/remote-protocol 是什么？

樱桃工作室远程访问协议计划 和代理回收合同\.

### 如何安装 @cherrystudio/remote-protocol？

在项目目录运行 npm install @cherrystudio/remote-protocol，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（^4\.3\.4）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cherrystudio/remote-protocol 支持 TypeScript 吗？

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

### @cherrystudio/remote-protocol 支持 ESM 还是 CommonJS？

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

### @cherrystudio/remote-protocol 可以商用吗？

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

### @cherrystudio/remote-protocol 的下载量有多少？

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

### @cherrystudio/remote-protocol 还在维护吗？

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