ZCode Protocol 与通信协议

ZCode Protocol 是 App、Host Process 与 zcode-cli 之间唯一的 Agent 协议。当前聊天主链路使用 V4 conversation topic、权威 projection 与 command inbox；packages/shared/src/zcode-protocol/index.ts 中仍保留的旧 session schema 只服务尚未删除的兼容调用，不是新增功能入口。

核心约束

协议实体统一叫 session；产品层历史 taskId 在聊天主链路中等同于 sessionId。
CLI 是 conversation 的事实源：消息行、运行阶段、队列、交互请求、模型配置、usage、goal 与控制能力都来自 ConversationSnapshot。
UI 只拥有草稿、滚动、焦点、面板展开等纯本地展示状态，不能在 renderer 中维护第二份权威消息或队列。
桌面使用 desktop-continuous，手机远控使用 web-remote-replayable。两种 profile 共享同一 CLI 投影，但恢复语义不能互相扩散。
手机 /remote 只 attach 已有 Host/CLI，不创建独立 Agent runtime。

传输拓扑

Renderer
  │ MessagePort RPC
  ▼
Host Process
  │ stdio NDJSON
  ▼
zcode-cli app-server
  ├─ command inbox
  ├─ ProductProjection reducer
  └─ conversation topic publisher

stdio NDJSON 只按 LF 字节 0x0a 分帧；写帧固定为 JSON.stringify(message) + "\n"。
reader 可兼容帧尾 CRLF，但不得 trim 或改写帧内字符串。
Host←CLI 是 ZCode Protocol JSON over stdio NDJSON，典型 method 如 v4/command。

V4 读路径

客户端订阅 conversation/<sessionId> topic。subscribe ACK 本身不内嵌 snapshot；服务端随后按该 subscription 的水位、logEpoch 和 delivery profile 投递 initial/recovery snapshot 或连续 delta：

subscribe(topic, baseSeq, baseLogEpoch)
  ├─ base 可续接 ──> delta(fromSeq, toSeq]
  └─ base 失效   ──> snapshot + 后续 delta

snapshot 是完整可恢复视图（session 元信息、rows.window、queue/inputRouting、pending interactions、model/mode/thought、usage/goal、control availability）。
客户端只允许按 seq 连续应用 delta；重复/迟到帧静默丢弃；gap 时重新订阅并以 snapshot 收敛。
桌面 continuous 不拼接手机 replayable 的运行态恢复消息。

V4 写路径

所有用户意图通过 v4/command 发送。信封包含稳定 commandId、clientId、sessionId、可选 baseRevision / baseLogEpoch、命令类型与 payload：

CAS 命令要求 baseRevision；row-targeting 命令还要求 baseLogEpoch；重试必须复用原 commandId。
CLI 用 session-runtime 中的 CommandInbox 做幂等、epoch、CAS 和 product guard 裁决。
sendText 支持 requestedDelivery: startNow | queue | guide。

命令全集以 packages/shared/src/zcode-protocol-v4/command.ts 为唯一类型事实源，主要分组：

会话：createSession、sendText、stop、compact、switchModelConfig、forkSessionAtMessage 等
查询 / 订阅：conversation / sessions-index / workspace-config 三类 topic
ACK：接受、拒绝、过期、重复

两代协议并存

	legacy v1	V4
路径	`shared/src/zcode-protocol/index.ts`（~257 导出单文件）	`shared/src/zcode-protocol-v4/`（61 文件）
常量	`ZCODE_PROTOCOL_VERSION=1`	`V4_WIRE_PROTOCOL_VERSION=3`（`core.ts`）
状态	承重旧栈，明确待删除	新功能唯一入口
内容	session/workspace snapshot 投影、工具 display 通道 schema	command / transport / wire / snapshot / delta / workflow-runs

V4 wire 子模块：wire.ts + wire-binary.ts + wire-codec.ts + wire-assembler.ts + wire-reassembly.ts（物理帧编解码与分片重组）、snapshot.ts/delta.ts/rows.ts/apply.ts/coalesce.ts（投影行与增量合并）。

交付 profile 与 attachment

helloMessageSchema.superRefine（transport.ts:44-58）强制 clientMode 与 deliveryProfile 匹配：

desktop-continuous：本地桌面窗口、SSH/WSL/Docker 桌面窗口、zcode-server 的 /ws/host trusted relay。
web-remote-replayable：手机 /remote shared-host attachment、Web remote/relay WebSocket、zcode-server 普通 /ws。

profile 在连接建立时由 host 注入，客户端不能自选。手机远控不另起 Agent/Host/远程会话，而是通过 shared-host attachment 接入桌面已有 Host，复用同一 task runtime owner。详见 server-remote、web-mobile。

owner / lease 与跨 Host 路由

owner/lease/stale-run 是 Host 路由层概念：保证单 owner、阻塞响应与跨 host 命令正确；remote workspace、bot/proxy、跨 host fallback 与阻塞请求仍依赖它，但它不再拥有第二份 conversation queue。

每个 RPC attachment 由 host 创建不可伪造的 TrustedConnectionContext {connectionId, clientMode, deliveryProfile}；UI 入参里的同名字段被 facade 清除后写回 host 真值（services/src/zcode-agent/zcodeAgentConnectionScope.ts:72-99）。
订阅路由按 connectionId → subscriptionId → owning attachment port。

协议分层心智模型

细节见 architecture：三层 = 通道（MessagePort / stdio / WebSocket / Electron IPC / postMessage）、信封（@zcode/rpc / ZCode Protocol JSON / typed postMessage）、内容（V4 对话协议 / Service API / Host 控制消息）。

Wiki AI

目录