ZCode 架构与进程模型

上游把 docs/architecture/zcode-code-architecture-overview.md 与 docs/architecture/communication-protocol-layers.md 标为「当前事实」入口，历史方案与迁移计划不能覆盖它。本页提炼这两篇 + docs/product-capability-map.md。

一句话模型

ZCode 可以运行多个 workspace window；每个窗口有且只有一个 Window Host（唯一 PID），每个 workspaceKey 最多一个聊天 CLI。Renderer 只通过 service/protocol 边界访问能力；CLI 持有 conversation 的权威状态。远程 workspace 的连接和 scoped services 也由该窗口的同一个 Host 管理。

Electron App
├─ Main Process（调度/原生能力/attachment 中转）
└─ Workspace Window（每个窗口独立一组）
   ├─ Renderer
   └─ Window Host（唯一 PID）
      ├─ LocalSource
      │  ├─ workspaceKey A ── stdio ── zcode-cli A
      │  └─ workspaceKey B ── stdio ── zcode-cli B
      ├─ RemoteConnectionRegistry
      │  ├─ SSH / WSL pooled connection
      │  ├─ Docker / Server dedicated connection
      │  └─ remoteSessionId -> workspaceKey scoped services
      ├─ ControllerProjection（workspace/task 列表事实）
      └─ AttachmentRegistry
         ├─ desktop-continuous
         └─ web-remote-replayable

窗口、Host、connection 和 workspace 不是同一层级：窗口 Host 按 workspaceKey 隔离本地 CLI，并在进程内维护远端 connection 与 logical session。SSH 在同一窗口、同一标准化 target 下共享一条连接和一个远端 zcode-server；WSL 按 normalized distro/user 共享连接并保留 60 秒 idle TTL / running-task protection；Docker、Server 保持 dedicated connection。连接复用不等于 workspace 身份合并。

进程职责

Main Process

只做平台调度：窗口生命周期、native dialog、external URL、OAuth callback、唯一窗口 Host Process 的监督、远端连接控制请求与 MessagePort/broadcast/远控 attachment 薄转发、日志接收。Main 不拥有连接池、logical session lifecycle、task projection、row、stream、queue、snapshot、goal 或 interaction 状态；remoteSessionId 由 Window Host 分配。

Renderer

负责 React UI、路由、布局以及草稿/滚动/焦点等本地状态；通过 hooks/service proxy 和 V4 transport 发意图；订阅 snapshot/delta 渲染 projection。Renderer 不直接调用 Repo/Node/CLI，也不维护第二份权威 conversation。

Host Process

由 createLocalServices({ parentPort }) 初始化窗口本地服务，并在同一进程中维护 RemoteConnectionRegistry、ControllerProjection 与 AttachmentRegistry。Host 按 workspaceKey 选择或启动本地 CLI，或把 scoped facade 路由到远端权威 service。列表 membership、在线/运行/等待事实与列表写路由由 Controller 持有，但 Host 不替 CLI reducer 拼 conversation rows、stream、permission 或 runtime snapshot。

一个窗口只注册一个 realtime hostId；每个 attachment 独立持有可信 clientMode、订阅、seq、背压和 dispose。远端断连保留最后可信 task 投影并标记 offline，所有 IO/mutation fail-closed，禁止回落本地；重连后由新 source snapshot 原子替换。

zcode-cli

每个 workspaceKey 最多一个聊天 CLI 进程。CLI 承载 session/core runtime、V4 command inbox、幂等/CAS 裁决、ProductProjection reducer、conversation topic、queue、goal、interaction、tool 与模型运行态。

Workspace Identity

workspaceKey = workspaceIdentity?.trim() || workspacePath

身份/隔离使用 workspaceKey：CLI 映射、session 绑定、缓存、队列、持久化与跨进程关联。
文件执行使用 workspacePath：cwd、文件读写、Git 和路径展示。
SSH/WSL/Docker 必须传递 workspaceIdentity；远控同时贯穿 remoteSessionId。
不得用相同远端路径推导相同 workspace 身份，也不得在业务代码手写 remote identity 格式（统一构造/解析在 packages/shared/src/remote-workspace-identity.ts，形如 remote:ssh:<host>:<port>:<user>:<path>）。详见 server-remote。

通信协议三层心智模型

上游用「寄快递」类比：

第 3 层：内容 —— 要做什么（业务含义）
第 2 层：信封 —— 如何描述、编号和匹配消息（消息/Call 协议）
第 1 层：通道 —— 消息通过什么管道传输（Transport）

链路	第 3 层：内容	第 2 层：信封	第 1 层：通道
Renderer → Host	Service API、V4 命令/查询/订阅	`@zcode/rpc`	MessagePort
Renderer → Main	平台操作	Electron IPC channel	Electron IPC
Main → Host	Host 控制消息	typed `{ type, ... }`	postMessage
Host → 本地 CLI	V4、少量 legacy	ZCode Protocol JSON	stdio NDJSON
Host → `zcode-server`	远程 Service API（参数可携带 V4）	`@zcode/rpc`	SSH stdio 或 WebSocket
`zcode-server` → 远端 CLI	V4、少量 legacy	ZCode Protocol JSON	stdio NDJSON
手机 → Relay → Main	远控 Service/V4 调用	relay envelope + `rpc-frame`	WebSocket

关键区分：V4 命令 ≠ V4 调用。V4 命令是业务意图（如 sendText），V4 调用是把命令送到下一跳的 Service API 调用。详见 zcode-protocol。

Monorepo 分层

模块	职责
`packages/shared`	跨进程类型、V4 schema、workspace identity 与平台契约
`packages/rpc`	Channel RPC、MessagePort/WebSocket transport、日志中间件
`packages/services`	Host 业务服务接口和 Node 实现
`packages/client`	service proxy 与客户端 transport 装配
`packages/ui`	平台无关 React UI、hooks、V4 projection store
`packages/desktop`	Electron main/preload/renderer/host 壳
`apps/zcode-cli`	Agent core、command、projection 与 app-server

依赖方向：UI -> hooks/types -> service/protocol contracts；Host services -> adapters/interfaces -> runtime implementations；Desktop/Web shells -> dependency injection -> shared UI。禁止 UI 直接调用 Repo、Service 引用 Runtime 具体实现、跨域导入非 Types 模块或形成循环依赖。详见 monorepo。

Conversation 数据流

UI command
  -> Host transport
  -> workspace CLI command inbox
  -> core events
  -> ProductProjection
  -> snapshot/delta
  -> SessionDataLayer
  -> ConversationProjectionStore
  -> UI rows/status/composer

desktop 和 mobile 共享这条事实链，差别只在 delivery profile：桌面 desktop-continuous，手机 web-remote-replayable（gap 时 snapshot 恢复）。relay/Main 不能下沉业务状态。详见 session-runtime。

产品能力地图（三段）

docs/product-capability-map.md 把能力划为三层运行边界 + 一层工程基础设施，交互式图由 apps/dev-docs 承载（pnpm dev:docs）：

Renderer：对话与任务体验、模型与账户体验、扩展体验、浏览器与开发工作台、办公/Computer Use 孵化、自动化体验、UI 平台、数据洞察与反馈。
Host：账户与权益、扩展管理与同步、浏览器与计算机操作平台、工作区与交付、工作台服务、自动化与渠道运行时、客户端平台、数据与可观测性。
ZCode CLI：智能体核心、对话运行时、模型能力、工具运行时与安全、多智能体、扩展运行时、浏览器运行时、用量可观测存储。
工程基础设施（不参与线上请求链）：构建与发布工程、测试自动化平台、质量数据与工程治理。

当前事实入口（上游文档）

docs/architecture/communication-protocol-layers.md — 通信协议分层
docs/zcode-protocol.md — ZCode Protocol
docs/architecture/message-flow.md — 消息流
docs/web-remote-control/web-remote-control-architecture.md — 手机远控
docs/ui/chat-message-queue.md — 聊天消息队列

Wiki AI

目录