07 RPC 方法清单

手机要实现的 RPC 方法清单（必需 / 可选），含用来声明自身能力的 device.capabilities。

这是手机要实现的功能清单：桌面通过 06 的信封调用这些方法。每个方法一个小节，写明请求字段、响应字段、错误码、行为要点，并标注 必需 / 可选。

1. 必需与可选；不支持时怎么办

1.1 方法总表

1.2 不支持的方法必须返回什么

对任何自己不支持的方法，手机必须返回（而不是不回复或随便编一个结果）：

{ "status": "error", "payload": "{}", "error": "remote.method_unknown" }

这是统一的「不支持」错误码。不要用空结果假装成功——桌面会据此认为操作已完成。

1.3 桌面看到不支持时怎么展示

建议实现 device.capabilities（§6）：手机用它主动声明自己实现了哪些方法，桌面就不会在界面上摆出点了只会失败的入口。没有实现它的手机，桌面按「全部支持」处理，行为与上表一致。

2. 通用约定

1. 载荷是 JSON 对象的文本（见 06 §3）：请求的 payload 是字符串，先 JSON.parse 再使用；响应的 payload 同理是 JSON 对象序列化成的字符串。
2. 除 chat.* 外，字段值几乎全是字符串：数字、布尔值也用字符串表示（如 "size": "1048576"、"enabled": "true"、"offset": "0"）。chat.* 和 document.list/read 的响应里保留了真实的 JSON 数字 / 布尔。下面每个字段都写明了类型，请按表实现，不要自行统一。
3. 响应里的「JSON 文本」字段（如 items）表示：该字段的值是一个字符串，字符串内容是一段 JSON（数组 / 对象）。桌面会对它再 JSON.parse 一次。
4. 请求里的未知字段忽略；响应只放本页定义的字段，不要夹带额外信息（尤其是敏感内容）。
5. 每个方法必须在 15 秒内返回（05 §4）。耗时任务（聊天推理、定时任务运行）先返回「已接受」，由桌面用 chat.read 等方法轮询。
6. 回复明文 ≤ 350,000 字节，需要分页或缩图时自行处理。
7. 所有修改类方法只有真正完成才返回 ok（桌面据此更新界面）；做不到就返回明确的错误码，不允许「假成功」。
8. 范围隔离：模型配置、文件传输、幂等回执等状态按发送方桌面的公钥隔离（同一手机配对了多台桌面时互不可见）。
9. 错误码格式 ^[a-z_]+\.[a-z_]+$（见 06 §7）。下面每个方法列出它应当使用的错误码；表里没有的情况自行选用同命名风格的码，或用 remote.operation_failed。

幂等与结果未知

桌面在「请求发出但回复没到（超时 / 断连）」时不知道手机有没有执行，所以会把原操作的幂等键保留下来，用同一个键重发或查询。手机必须配合：

手机进程重启后，已接受但未完成的 chat.send 任务应标记为 interrupted，不得自动重新执行（任务可能有外部副作用）。

通用错误码

3. 模型

model.sync（必需）

桌面把当前选中的模型提供商配置发给手机，手机据此调用模型。桌面在以下时机调用：新配对成功后、发送消息前（配置变化时）、收到 chat.model_missing 后。

请求：

响应：{ "status": "saved", "model": "<model>", "revision": "<revision>" }。

行为：

• 配置按发送方桌面公钥保存为该桌面对应的模型提供商，并设为这台桌面发来任务时的默认模型；
• revision 小于已保存值 → model.stale_revision（拒绝倒退），等于或大于则接受；
• api_key 只能存进加密凭据库，不得写入日志、会话缓存、错误信息或云端；
• 错误码：model.invalid_url、model.invalid_config、model.unsupported_protocol、model.stale_revision。

4. 对话

chat.send（必需）

向手机的原生 Agent 发一条消息并启动任务；立即返回，任务在后台执行。

请求：

响应：{ "session_id": "<会话ID>", "client_id": "<同请求>", "status": "accepted" }。桌面只使用 session_id。

行为：

• 校验 → 持久化收据 → 启动任务 → 返回，顺序不可颠倒（见上节「幂等」）；
• 同一会话已有任务在运行 → chat.busy；
• 这台桌面还没有通过 model.sync 下发模型 → chat.model_missing（桌面会自动重新 model.sync 并用同一个 client_id 重试一次）；
• 新建会话时，标题取消息前若干字；
• 错误码：chat.invalid_id、chat.invalid_text、chat.id_reused、chat.model_missing、chat.session_missing、chat.busy、chat.receipt_failed，以及附件相关的 file.invalid_id、file.too_many、file.missing、file.incomplete。

chat.read（必需）

读取会话的消息与运行状态。任务运行期间桌面约每 0.5–1.5 秒调用一次（界面不可见时约 8 秒一次），每次从上次已知位置往前 2 条开始读。

请求：

响应：

items[] 的每条消息：

blocks[]：

要点：

• 分页必须有进展：offset < total 时 next 必须大于 offset，否则桌面报「手机历史记录分页异常」；
• 消息顺序与 ID 要稳定，桌面靠 ID 判断重读的尾部是否与已有内容对齐；
• 错误码：chat.session_missing。

chat.list（必需）

请求：{ "offset": 0 }（JSON 数字，≥ 0）。

响应：

items[]：id（string）、title（string，缺省「新的会话」）、updated（number，毫秒）、pinned（boolean）、running（boolean，是否有任务在运行）、model（string，可选）。

桌面据此同步会话索引；手机上已删除的会话，桌面会在下一轮同步里把它去掉。

chat.cancel（必需）

请求：{ "session_id": "…" }。响应：{ "status": "cancelled", "session_id": "…" }。

停止要真的完成才能回复：调用手机原生取消，等执行协程退出，再返回。桌面收到回复才会显示「已停止」；如果超时（结果未知），桌面显示「手机尚未确认停止」，不会假装已停。会话不存在 → chat.session_missing；会话本来就没在运行也返回成功。

chat.rename / chat.pin / chat.delete（可选）

请求都带 session_id（string），另有：

错误码：chat.session_missing、chat.invalid_title、chat.busy。桌面得到成功回执后才修改界面，随后重新拉取会话列表。

chat.file（可选）

把某条消息的附件登记为可读取的文件。请求：{ "session_id", "message_id", "index" }（index 是十进制字符串，对应该消息 attachments 的下标）。响应：一个 FileState（见 file.*，status 为 complete），桌面随后用 file.read 分片读取。

只允许导出该消息里真实存在的附件，不接受调用方给出的任意路径。错误码：file.message_missing、file.attachment_missing、file.invalid_source、file.quota_exceeded。

chat.image（可选）

把 Agent 回复里提到的一张图片登记为可读取的文件。请求：{ "session_id", "source" }，source 是回复文字里出现的图片引用（格式由手机端自己的 Agent 决定，例如沙箱内的路径或自定义地址）。响应同 chat.file（FileState，status: "complete"）。

安全要求：只能读取该会话沙箱内的图片，不得读取手机上的任意路径；文件类型限图片（PNG / JPEG / GIF / WebP），≤ 15 MiB（桌面端的内嵌显示上限）。错误码：chat.session_missing、image.changed_during_read、file.quota_exceeded。

5. 文档（人格与记忆）

文档名只有三类：SOUL.md（人格）、GLOBAL.md（全局记忆）、YYYY-MM-DD.md（按日记忆）。其他名字 → sync.invalid_name。单文档 ≤ 150,000 字节（UTF-8）。

revision 对桌面是不透明字符串，规则只有一条：内容变了它就必须变，内容没变就不变。官方实现用「文档 UTF-8 内容的 SHA-256 十六进制小写」，文件不存在按空文本处理。

document.list（必需，可返回空）

请求 {}。响应：

{ "items": [ { "name": "SOUL.md", "revision": "…", "modified": 1767222000000 } ] }

modified 是毫秒时间戳（JSON 数字）。顺序：SOUL.md、GLOBAL.md，然后按日期从新到旧的日记忆。不支持文档时返回 { "items": [] }。

document.read（必需）

请求 { "name": "SOUL.md" }。响应 { "name", "text", "revision", "modified" }（text 是全文）。文档不存在时 text 为 ""。

document.write（可选）

请求 { "name", "text", "revision" }，revision 是桌面上次读到的版本。响应同 document.read（写入后的最新快照）。

行为：写入前比较当前版本，不一致 → sync.conflict，不写入；一致则先备份旧内容，写入临时文件，再原子替换，最后返回新快照。错误码：sync.invalid_name、sync.document_too_large、sync.conflict、sync.write_failed。

6. 设备信息

device.capabilities（可选，建议实现）

手机用它声明自己真正实现了哪些方法，以及少量数值上限。桌面在配对成功后和每次连上手机时调用一次，并按设备缓存结果；据此决定手机页面里哪些入口显示、隐藏或置灰。这是 v=1 范围内新增的可选方法（见 08），不改变任何已有方法。

请求 {}。响应：

{
  "version": 1,
  "methods": ["device.capabilities", "device.status", "model.sync", "chat.send", "chat.read", "chat.list", "chat.cancel", "document.list", "document.read", "schedule.list"],
  "limits": { "chat.send.max_text_chars": 4000, "file.max_bytes": 104857600 }
}

limits 目前定义的键（不认识的键桌面一律忽略，后续可能新增）：

行为要求：

• methods 必须与手机的实际分派表一致（最好由分派表自动生成，而不是另写一份清单），否则桌面会显示手机其实做不了的入口，或藏起做得了的入口。
• 清单里列出的方法，不得再对同样的请求回 remote.method_unknown；清单里没有的方法，仍必须按 §1.2 回 remote.method_unknown。
• 手机上某项能力需要用户额外授权（例如 screen.* 需要用户在手机上打开开关），只要方法已实现就应列入 methods，授权状态由对应方法回 screen.permission_required 表达（见 §8），不要因为开关暂时没开就把方法从清单里拿掉。
• 只读、无副作用，每次返回当前的清单；清单在 App 升级后可能变化，桌面按「设备 ID + 手机 App 版本」缓存，版本变化后重新获取。
• 老手机兼容：没有实现本方法的手机按 §1.2 回 remote.method_unknown。桌面据此把该手机当作「全部支持」，保持现有行为（入口全部显示，调用不支持的方法时按 §1.3 降级）。这不是错误，手机不需要特别处理。
• 错误码：除 remote.method_unknown 外，没有本方法专属的错误码。若手机暂时无法回答（例如 remote.not_ready），桌面不会把它当作「全部不支持」，而是同样按老手机处理，稍后再试。

桌面据 methods 的显示规则（供实现参考，文案可能调整）：

此外，桌面运行中如果某个方法回了 remote.method_unknown，会把它记入该手机的「不支持」缓存（同样按设备 ID + App 版本），之后按上表处理；这样即使 device.capabilities 清单不准确，也不会反复点到失败的功能。

device.status（可选）

请求 {}。响应：

只读、无副作用，不要编造数值。

device.rename（可选）

请求 { "name": "…" }；响应 { "name": "<实际保存的名称>" }。桌面要求回执的 name 与请求逐字相同，否则判为「手机尚未确认新名称」。所以请原样保存；确实不能接受的名称（例如为空）返回错误，而不是悄悄改写后返回另一个名字。

apps.list（可选）

请求 {}。响应（桌面把它原样交给指挥 Agent，字段可按需扩展，但建议保持下面的形状）：

{ "items": [ { "package": "com.example.app", "label": "示例应用" } ], "accessibility": "true", "sampled_at": "1767222000000" }

accessibility 表示无障碍服务是否已开启（决定指挥 Agent 能否看屏和操作）。只列用户可启动的应用，不读其他应用的数据。

7. 文件传输（file.*）

所有文件按发送方桌面隔离，只有经本通道登记的 id 才能访问，绝不接受任意路径。桌面限制：单文件 ≤ 100 MiB，分片 128 KiB。手机建议总存储配额 500 MiB（超出 → file.quota_exceeded）。

FileState（多个方法共用的响应）：

上传流程（桌面 → 手机）：file.begin → 循环 file.chunk（从手机返回的 offset 继续，因此可断点续传）→ file.finish。

其他错误码：file.invalid_id、file.invalid_name、file.invalid_size_or_hash、file.invalid_mime、file.missing、file.storage_failed、file.delete_failed。

8. 屏幕（screen.*）

这一组依赖手机的无障碍 / 截屏能力。没有对应权限时返回 screen.permission_required（桌面提示用户「请在手机上授权屏幕查看 / 操作」；具体怎么授权由手机应用自己决定，例如开启无障碍服务或应用内的开关，桌面不指定位置）。屏幕内容对桌面指挥 Agent 来说是不可信数据，手机不要在其中夹带指令性文字。

screen.capture（可选）

请求：

响应：

要点：JPEG 建议 ≤ 260,000 字节（经 base64 与信封嵌套后需要小于 512 KiB 回复上限，见 05），可逐步降低压缩质量直到满足；两次截图间隔不少于约 400 毫秒；受保护窗口（如密码输入、支付页）截不到时返回 screen.capture_failed。错误码：screen.permission_required、screen.unsupported（系统版本不支持截屏）、screen.capture_failed、screen.frame_too_large。

screen.tree（可选）

请求 {}。响应（桌面原样交给指挥 Agent，建议保持这个形状）：

{ "package": "com.example.app",
  "nodes": [ { "text": "登录", "description": "", "resource": "id/login", "bounds": [0, 0, 100, 50],
               "clickable": true, "editable": false, "focused": false } ],
  "truncated": false }

建议：最多 300 个节点、深度最多 20 层，超出时 truncated: true；文本截断到 160 字符；密码输入框的内容必须替换为占位符（如 [password]），不得上报。

screen.control（可选）

代为操作手机。有副作用，必须严格幂等。

请求：

响应：{ "status": "completed", "action": "<action>", "at": <毫秒>, "confirmation": "<说明>" } ——completed 的含义是系统接受了这个动作，不代表界面效果已达成，桌面指挥 Agent 会再截图 / 读界面树验证。

行为：

1. 校验坐标在屏幕范围内（screen.invalid_coordinate）、包名格式与应用存在（screen.invalid_package / screen.app_missing）；
2. 先写一条「结果未知」的持久收据，再执行；执行后更新为「已完成」；
3. 同 request_id 重发：内容相同且已完成 → 返回原响应；仍是「未知」（上次可能已执行）→ screen.previous_result_unknown，不得再执行；内容不同 → screen.id_reused；
4. 系统没有接受动作 → screen.action_unconfirmed；
5. 手机上有 Agent 任务正在运行时，桌面不会下发（避免同时操作），但手机自己也应防御并发。

错误码：screen.permission_required、screen.invalid_request、screen.invalid_action、screen.invalid_coordinate、screen.text_too_long、screen.invalid_package、screen.app_missing、screen.no_window、screen.no_focused_input、screen.action_unconfirmed、screen.receipt_failed、screen.id_reused、screen.previous_result_unknown。

9. 技能（skills.*）

技能是带 SKILL.md 的包。桌面安装技能到手机的流程：先用 file.* 把 ZIP 包传到手机（拿到传输 id），再调 skills.install，最后 file.delete 清理暂存包。

PhoneSkill：id、name、description、version、enabled（"true"/"false"）、body（技能正文，列表中为 ""），均为 string。

skills.install 必须在写入前严格校验 ZIP：整包 ≤ 10 MiB，且传输已 complete 并通过 SHA-256；条目 ≤ 600、实际文件 ≤ 300、展开后总大小 ≤ 30 MiB；根目录（或唯一的公共顶层目录，去掉后）必须有 SKILL.md；拒绝绝对路径、.. / . 路径段、反斜杠、冒号、NUL 字符、符号链接、重复路径；忽略 __MACOSX/ 与 .DS_Store；写入目录必须落在技能存储根目录之内（规范化路径后比较）。SKILL.md 中需能解析出名称、描述、版本、正文，具体格式由手机端的技能体系决定。失败时清理已写入的部分。

错误码：skill.not_found、skill.invalid_toggle、skill.invalid_zip、skill.unsafe_path、skill.duplicate_path、skill.package_too_large、skill.expanded_too_large、skill.too_many_files、skill.missing_manifest、skill.invalid_manifest、skill.invalid_transfer、skill.already_exists_or_invalid_name、skill.storage_failed、skill.delete_failed。

10. 定时任务（schedule.*）

手机是定时任务的权威，桌面只是它的遥控器；列表同步以手机为准。

PhoneSchedule（所有字段为 string）：

schedule.save 需要手机已有这台桌面的模型配置（chat.model_missing 时桌面会先 model.sync 再重试）。time 为 once 时不得早于现在（除非任务本来就是停用的）：schedule.time_in_past。

schedule.run 的语义很严格，因为一次运行会产生外部副作用：

• 手机先把「dispatching」收据持久化，再启动任务，再把收据更新为 accepted（带上新会话 ID）或 failed；
• 同一个 request_id 重发 → 直接返回已保存的收据（桌面会在 10 分钟内为未确认的运行复用同一个 request_id）；
• 桌面把 accepted 视为「已启动」，failed / rejected 视为「确定没启动」，其余任何状态（含 dispatching、网络超时）都视为结果未知并保留请求，所以一定要用准确的状态；
• 回复 status:"error" 时，只有这些码被桌面视为「确定没执行」：schedule.invalid_id、schedule.invalid_request、schedule.missing、schedule.id_reused、schedule.dispatch_failed、sync.conflict；其他任何错误码都会被当成结果未知——如果任务可能已经启动，不要返回上面这几个码。

其他错误码：schedule.receipt_failed、schedule.invalid_content、schedule.unsupported_frequency、schedule.edit_on_phone、schedule.time_in_past、schedule.invalid_time、schedule.invalid_days、schedule.invalid_interval、chat.session_missing、chat.model_missing。

11. 子代理（subagent.*）

子代理是手机 Agent 可以委派的专门角色。手机是权威，桌面草稿不代表写入成功。

PhoneSubAgent（所有字段为 string）：id（[A-Za-z0-9._-]{1,100}）、name、description、instructions（工作指令）、model_group（空串 = 手机自动选模型；否则必须是 groups 里的某个 id）、enabled（"true"/"false"）、builtin（"true"/"false"，内置子代理不能删除 / 改名）、revision（不透明版本，覆盖所有语义字段但不含更新时间，非空）。

四个方法的响应都是同一个快照 PhoneSubAgents（写操作返回写入后的最新快照）：

{ "items": "<PhoneSubAgent 数组的 JSON 文本>",
  "groups": "<[{\"id\":\"…\",\"name\":\"…\"}] 的 JSON 文本，手机的模型分组>",
  "delegation_enabled": "true" }

桌面会严格校验响应：items 与 groups 必须是合法 JSON 数组，每个子代理的八个字段都是字符串且 id、revision 非空、id 不重复，enabled/builtin/delegation_enabled 只能是 "true" 或 "false"，否则提示「手机子代理回复格式无效，请更新手机端后重试」。

错误码：subagent.invalid_id、subagent.missing、subagent.limit、subagent.builtin、subagent.invalid_enabled、subagent.invalid_definition、subagent.model_missing、subagent.duplicate_name、subagent.not_ready、subagent.persist_failed、sync.conflict。

12. 协议里存在但手机无需实现的结构

线上协议的 JSON 契约（公开仓库 protocol/schema/remote-v1.json）里还定义了 TaskRequest / TaskReply、CommanderConfig / CommanderCall、ImageCacheKey / ImageCacheWrite、ChatSendFiles、FileRead / FileData / FileList 等结构。其中 TaskRequest / TaskReply、CommanderConfig / CommanderCall、ImageCacheKey / ImageCacheWrite 是早期或桌面本机内部使用的结构，桌面当前不会通过 RPC 把它们发给手机，可以忽略；FileRead / FileData / FileList / ChatSendFiles 对应本页 file.read / file.list / chat.send 的字段，以本页为准（契约文件里这些结构的字段都是字符串，而 chat.* 的真实载荷里有 JSON 数字 / 布尔，这是契约文件没有覆盖的部分，以本页为准）。