ZCode 架构分析

本文件基于当前检出的源码（2026-10）分析 ZCode 的整体架构与各类流程。

核心事实来源：AGENTS.md、packages/*、apps/zcode-cli/packages/*。

目标：让读者理解"一个用户输入走完整条链路"以及各子系统（启动、记忆、工具、编排、权限、服务）如何协同。

0. 关键前提：一个仓库，两套"核心"

ZCode 是应用壳层 + 捆绑 Agent 运行时的组合，这对理解所有调用链至关重要：

壳层（多端外壳） ：packages/desktop（Electron）、packages/web + packages/server（Web）、packages/ui（React/Zustand）、packages/services（业务服务）、packages/rpc（RPC 框架）、packages/shared（协议）、packages/client（SDK）。
真正跑 LLM 的运行时 ：apps/zcode-cli/packages/core（上下文/记忆/压缩/工具/子代理/权限/模型循环），经 stdio 协议被壳层拉起和驱动。

真正的 LLM 执行引擎（自动压缩、工具鉴权、提示注入防御）都捆绑在运行时内；壳层只负责托管、协议、状态投影和权限策略面。

1. Overall Architecture 整体架构

#mermaid-svg-qB20rbBi5yfjMhZ7{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-qB20rbBi5yfjMhZ7 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-qB20rbBi5yfjMhZ7 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-qB20rbBi5yfjMhZ7 .error-icon{fill:#552222;}#mermaid-svg-qB20rbBi5yfjMhZ7 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-qB20rbBi5yfjMhZ7 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-qB20rbBi5yfjMhZ7 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-qB20rbBi5yfjMhZ7 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-qB20rbBi5yfjMhZ7 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-qB20rbBi5yfjMhZ7 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-qB20rbBi5yfjMhZ7 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-qB20rbBi5yfjMhZ7 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-qB20rbBi5yfjMhZ7 .marker.cross{stroke:#333333;}#mermaid-svg-qB20rbBi5yfjMhZ7 svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-qB20rbBi5yfjMhZ7 p{margin:0;}#mermaid-svg-qB20rbBi5yfjMhZ7 .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-qB20rbBi5yfjMhZ7 .cluster-label text{fill:#333;}#mermaid-svg-qB20rbBi5yfjMhZ7 .cluster-label span{color:#333;}#mermaid-svg-qB20rbBi5yfjMhZ7 .cluster-label span p{background-color:transparent;}#mermaid-svg-qB20rbBi5yfjMhZ7 .label text,#mermaid-svg-qB20rbBi5yfjMhZ7 span{fill:#333;color:#333;}#mermaid-svg-qB20rbBi5yfjMhZ7 .node rect,#mermaid-svg-qB20rbBi5yfjMhZ7 .node circle,#mermaid-svg-qB20rbBi5yfjMhZ7 .node ellipse,#mermaid-svg-qB20rbBi5yfjMhZ7 .node polygon,#mermaid-svg-qB20rbBi5yfjMhZ7 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-qB20rbBi5yfjMhZ7 .rough-node .label text,#mermaid-svg-qB20rbBi5yfjMhZ7 .node .label text,#mermaid-svg-qB20rbBi5yfjMhZ7 .image-shape .label,#mermaid-svg-qB20rbBi5yfjMhZ7 .icon-shape .label{text-anchor:middle;}#mermaid-svg-qB20rbBi5yfjMhZ7 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-qB20rbBi5yfjMhZ7 .rough-node .label,#mermaid-svg-qB20rbBi5yfjMhZ7 .node .label,#mermaid-svg-qB20rbBi5yfjMhZ7 .image-shape .label,#mermaid-svg-qB20rbBi5yfjMhZ7 .icon-shape .label{text-align:center;}#mermaid-svg-qB20rbBi5yfjMhZ7 .node.clickable{cursor:pointer;}#mermaid-svg-qB20rbBi5yfjMhZ7 .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-qB20rbBi5yfjMhZ7 .arrowheadPath{fill:#333333;}#mermaid-svg-qB20rbBi5yfjMhZ7 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-qB20rbBi5yfjMhZ7 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-qB20rbBi5yfjMhZ7 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-qB20rbBi5yfjMhZ7 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-qB20rbBi5yfjMhZ7 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-qB20rbBi5yfjMhZ7 .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-qB20rbBi5yfjMhZ7 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-qB20rbBi5yfjMhZ7 .cluster text{fill:#333;}#mermaid-svg-qB20rbBi5yfjMhZ7 .cluster span{color:#333;}#mermaid-svg-qB20rbBi5yfjMhZ7 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-qB20rbBi5yfjMhZ7 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-qB20rbBi5yfjMhZ7 rect.text{fill:none;stroke-width:0;}#mermaid-svg-qB20rbBi5yfjMhZ7 .icon-shape,#mermaid-svg-qB20rbBi5yfjMhZ7 .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-qB20rbBi5yfjMhZ7 .icon-shape p,#mermaid-svg-qB20rbBi5yfjMhZ7 .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-qB20rbBi5yfjMhZ7 .icon-shape .label rect,#mermaid-svg-qB20rbBi5yfjMhZ7 .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-qB20rbBi5yfjMhZ7 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-qB20rbBi5yfjMhZ7 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-qB20rbBi5yfjMhZ7 :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}#mermaid-svg-qB20rbBi5yfjMhZ7 .ext>*{fill:#f5f0ff!important;stroke:#7c6cf0!important;stroke-width:1px!important;}#mermaid-svg-qB20rbBi5yfjMhZ7 .ext span{fill:#f5f0ff!important;stroke:#7c6cf0!important;stroke-width:1px!important;} Web 端
桌面端 Desktop (Electron)
fork eUtilityProcess
WebSocket
RPC MessagePort
spawn --stdio (LF 分隔 JSON)
Remote Control (手机 attachment)
共享契约层
zcode-protocol (+ v4)
rpc 框架
shared/src/platform.ts

IPlatformService
Agent Runtime (捆绑, 独立 Node 进程)

apps/zcode-cli/packages/core
context 上下文装配

短期记忆
模型循环 / provider
tool 工具系统 + 权限流
memory 文件记忆 Agent

长期记忆
CommandInbox 串行 admission
compact 压缩归纳

中期记忆
subagent 子代理
Main 进程

packages/desktop/src/main

窗口 / 原生操作 / 进程调度 / 消息转发

不承载 task/session 业务状态
Host 进程 (Local)

desktopHostProcess.ts

每窗口一个 window-scoped Host
Renderer

packages/ui React + Zustand
CUA 授权面板

desktop/src/main/cuaPermission*
Web (packages/web)
Server (packages/server)

远程 Host / 部署远程 agent 运行时

要点：

Desktop 的 desktop-continuous 实时链路与手机的 web-remote-replayable 恢复链路必须区分。
手机远控连接桌面已有 Host attachment，复用会话运行时；不为手机另起 Agent、Local Host 或远程会话。
Main 只做窗口、原生操作、进程调度和消息转发，不承载 task/session 业务状态。

2. Request Lifecycle 请求生命周期（启动 + 一次用户输入）

2.1 启动流程

Renderer Agent Runtime (stdio) Host (utilityProcess) Electron Main Renderer Agent Runtime (stdio) Host (utilityProcess) Electron Main #mermaid-svg-DvV1bZvlf6oUI9FB{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-DvV1bZvlf6oUI9FB .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-DvV1bZvlf6oUI9FB .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-DvV1bZvlf6oUI9FB .error-icon{fill:#552222;}#mermaid-svg-DvV1bZvlf6oUI9FB .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-DvV1bZvlf6oUI9FB .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-DvV1bZvlf6oUI9FB .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-DvV1bZvlf6oUI9FB .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-DvV1bZvlf6oUI9FB .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-DvV1bZvlf6oUI9FB .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-DvV1bZvlf6oUI9FB .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-DvV1bZvlf6oUI9FB .marker{fill:#333333;stroke:#333333;}#mermaid-svg-DvV1bZvlf6oUI9FB .marker.cross{stroke:#333333;}#mermaid-svg-DvV1bZvlf6oUI9FB svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-DvV1bZvlf6oUI9FB p{margin:0;}#mermaid-svg-DvV1bZvlf6oUI9FB .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-DvV1bZvlf6oUI9FB text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-DvV1bZvlf6oUI9FB .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-DvV1bZvlf6oUI9FB .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-DvV1bZvlf6oUI9FB .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-DvV1bZvlf6oUI9FB .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-DvV1bZvlf6oUI9FB #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-DvV1bZvlf6oUI9FB .sequenceNumber{fill:white;}#mermaid-svg-DvV1bZvlf6oUI9FB #sequencenumber{fill:#333;}#mermaid-svg-DvV1bZvlf6oUI9FB #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-DvV1bZvlf6oUI9FB .messageText{fill:#333;stroke:none;}#mermaid-svg-DvV1bZvlf6oUI9FB .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-DvV1bZvlf6oUI9FB .labelText,#mermaid-svg-DvV1bZvlf6oUI9FB .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-DvV1bZvlf6oUI9FB .loopText,#mermaid-svg-DvV1bZvlf6oUI9FB .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-DvV1bZvlf6oUI9FB .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-DvV1bZvlf6oUI9FB .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-DvV1bZvlf6oUI9FB .noteText,#mermaid-svg-DvV1bZvlf6oUI9FB .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-DvV1bZvlf6oUI9FB .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-DvV1bZvlf6oUI9FB .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-DvV1bZvlf6oUI9FB .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-DvV1bZvlf6oUI9FB .actorPopupMenu{position:absolute;}#mermaid-svg-DvV1bZvlf6oUI9FB .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-DvV1bZvlf6oUI9FB .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-DvV1bZvlf6oUI9FB .actor-man circle,#mermaid-svg-DvV1bZvlf6oUI9FB line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-DvV1bZvlf6oUI9FB :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} packages/desktop/src/main/index.ts appLaunchCoordinator 构建 Host init 消息/envapp.whenReady() → settings bootstrap → DB 启动 → cron 调度ensurePrimaryWindow 创建窗口fork (electronUtilityProcess) → desktopHostProcess.spawnHostProcessIPC/broadcast 接线warmUpZCodeAgent 预预热 agentzcodeAgentProcessManager.startClient → spawn(zcode.cjs app-server --stdio)stdio stdout 成帧 (JSON\\n) zcodeStdioTransportHost 就绪Host 可用信号

Agent stdio 成帧 ：zcodeStdioTransport.ts 使用 LF 分隔的 JSON{...}\n；stdout 回读 → zcodeProtocolMessageSchema 校验。
Renderer ↔ Host ：RPC 走 MessagePort（packages/client/messageport.ts），Host 暴露 v4 facade，Renderer 侧调用形如 sendPrompt。
Web 启动 ：packages/server/src/entry-http.ts → Hono HTTP + WebSocket（默认端口 3030）；packages/web/src/main.tsx 用 connectViaWebSocket 连接。
CLI 运行时初始化 ：packages/cli/src/main.ts → run() → runZCodeProtocolAgent → ZCodeProtocolAgentServer → createConversationV4Gateway。

2.2 一次用户输入的完整调用链

Tool Executor Provider/模型 core Runtime (上下文/记忆/模型) CommandInbox (串行 gate) zcodeStdioTransport Host Renderer/UI (pending optimistic) Tool Executor Provider/模型 core Runtime (上下文/记忆/模型) CommandInbox (串行 gate) zcodeStdioTransport Host Renderer/UI (pending optimistic) #mermaid-svg-cRpKqz6oo0FLAHdL{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-cRpKqz6oo0FLAHdL .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-cRpKqz6oo0FLAHdL .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-cRpKqz6oo0FLAHdL .error-icon{fill:#552222;}#mermaid-svg-cRpKqz6oo0FLAHdL .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-cRpKqz6oo0FLAHdL .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-cRpKqz6oo0FLAHdL .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-cRpKqz6oo0FLAHdL .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-cRpKqz6oo0FLAHdL .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-cRpKqz6oo0FLAHdL .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-cRpKqz6oo0FLAHdL .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-cRpKqz6oo0FLAHdL .marker{fill:#333333;stroke:#333333;}#mermaid-svg-cRpKqz6oo0FLAHdL .marker.cross{stroke:#333333;}#mermaid-svg-cRpKqz6oo0FLAHdL svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-cRpKqz6oo0FLAHdL p{margin:0;}#mermaid-svg-cRpKqz6oo0FLAHdL .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-cRpKqz6oo0FLAHdL text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-cRpKqz6oo0FLAHdL .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-cRpKqz6oo0FLAHdL .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-cRpKqz6oo0FLAHdL .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-cRpKqz6oo0FLAHdL .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-cRpKqz6oo0FLAHdL #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-cRpKqz6oo0FLAHdL .sequenceNumber{fill:white;}#mermaid-svg-cRpKqz6oo0FLAHdL #sequencenumber{fill:#333;}#mermaid-svg-cRpKqz6oo0FLAHdL #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-cRpKqz6oo0FLAHdL .messageText{fill:#333;stroke:none;}#mermaid-svg-cRpKqz6oo0FLAHdL .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-cRpKqz6oo0FLAHdL .labelText,#mermaid-svg-cRpKqz6oo0FLAHdL .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-cRpKqz6oo0FLAHdL .loopText,#mermaid-svg-cRpKqz6oo0FLAHdL .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-cRpKqz6oo0FLAHdL .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-cRpKqz6oo0FLAHdL .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-cRpKqz6oo0FLAHdL .noteText,#mermaid-svg-cRpKqz6oo0FLAHdL .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-cRpKqz6oo0FLAHdL .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-cRpKqz6oo0FLAHdL .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-cRpKqz6oo0FLAHdL .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-cRpKqz6oo0FLAHdL .actorPopupMenu{position:absolute;}#mermaid-svg-cRpKqz6oo0FLAHdL .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-cRpKqz6oo0FLAHdL .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-cRpKqz6oo0FLAHdL .actor-man circle,#mermaid-svg-cRpKqz6oo0FLAHdL line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-cRpKqz6oo0FLAHdL :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} Renderer 只保留未提交草稿 + pending optimistic overlay v4-gateway.handleCommand → inbox.handle(rawParams) pinLiveInput / decide() 处理 busy/running 与 staleness UI 增量更新 (conversation topic) 提交 prompt (sendPrompt / zcodeTaskService.sendPrompt)包成 ZCode Protocol v4 命令信封写 JSON\\n 到 agent stdin取 key gate取每 session FIFO gate (sessionGates.acquire) --- 持有到 settle()admissionSeq 分配 CLI 权威顺序获准 → host.admitCommandInput → host.executeCommand重建会话上下文 (短期: SQLite hydrate)注入长期记忆 MEMORY.md + AGENTS.mdcompaction 检查 (超窗 → 中期归纳)模型请求 (流式)流式响应 / tool_call执行工具 (registry→权限→executor)结果回填 → 继续模型循环terminal ACK + 流事件settle() 释放 FIFO gateRPC 流事件 / 快照 / revision 投影

CommandInbox 串行语义（AGENTS.md 的核心约束） ：已接受的 busy/running 输入由 CLI/runtime CommandInbox 串行 admission；Renderer 只保留未提交草稿与 pending optimistic overlay；Host owner/lease 负责路由。关键文件：apps/zcode-cli/packages/bootstrap/src/zcode-protocol-v4/{v4-gateway,command-inbox}.ts、v4-bridge.ts。

3. Memory System 记忆系统（短期 / 中期 / 长期）调用流程

记忆没有逐字命名"短/中/长期"，但运行时明确分了三层，全落在 apps/zcode-cli/packages/（shell 层 packages/services/src/memory/memoryService.ts 是其应用侧读取）。
#mermaid-svg-L8S09T5sfoOdsU6a{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-L8S09T5sfoOdsU6a .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-L8S09T5sfoOdsU6a .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-L8S09T5sfoOdsU6a .error-icon{fill:#552222;}#mermaid-svg-L8S09T5sfoOdsU6a .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-L8S09T5sfoOdsU6a .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-L8S09T5sfoOdsU6a .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-L8S09T5sfoOdsU6a .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-L8S09T5sfoOdsU6a .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-L8S09T5sfoOdsU6a .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-L8S09T5sfoOdsU6a .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-L8S09T5sfoOdsU6a .marker{fill:#333333;stroke:#333333;}#mermaid-svg-L8S09T5sfoOdsU6a .marker.cross{stroke:#333333;}#mermaid-svg-L8S09T5sfoOdsU6a svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-L8S09T5sfoOdsU6a p{margin:0;}#mermaid-svg-L8S09T5sfoOdsU6a .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-L8S09T5sfoOdsU6a .cluster-label text{fill:#333;}#mermaid-svg-L8S09T5sfoOdsU6a .cluster-label span{color:#333;}#mermaid-svg-L8S09T5sfoOdsU6a .cluster-label span p{background-color:transparent;}#mermaid-svg-L8S09T5sfoOdsU6a .label text,#mermaid-svg-L8S09T5sfoOdsU6a span{fill:#333;color:#333;}#mermaid-svg-L8S09T5sfoOdsU6a .node rect,#mermaid-svg-L8S09T5sfoOdsU6a .node circle,#mermaid-svg-L8S09T5sfoOdsU6a .node ellipse,#mermaid-svg-L8S09T5sfoOdsU6a .node polygon,#mermaid-svg-L8S09T5sfoOdsU6a .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-L8S09T5sfoOdsU6a .rough-node .label text,#mermaid-svg-L8S09T5sfoOdsU6a .node .label text,#mermaid-svg-L8S09T5sfoOdsU6a .image-shape .label,#mermaid-svg-L8S09T5sfoOdsU6a .icon-shape .label{text-anchor:middle;}#mermaid-svg-L8S09T5sfoOdsU6a .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-L8S09T5sfoOdsU6a .rough-node .label,#mermaid-svg-L8S09T5sfoOdsU6a .node .label,#mermaid-svg-L8S09T5sfoOdsU6a .image-shape .label,#mermaid-svg-L8S09T5sfoOdsU6a .icon-shape .label{text-align:center;}#mermaid-svg-L8S09T5sfoOdsU6a .node.clickable{cursor:pointer;}#mermaid-svg-L8S09T5sfoOdsU6a .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-L8S09T5sfoOdsU6a .arrowheadPath{fill:#333333;}#mermaid-svg-L8S09T5sfoOdsU6a .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-L8S09T5sfoOdsU6a .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-L8S09T5sfoOdsU6a .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-L8S09T5sfoOdsU6a .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-L8S09T5sfoOdsU6a .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-L8S09T5sfoOdsU6a .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-L8S09T5sfoOdsU6a .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-L8S09T5sfoOdsU6a .cluster text{fill:#333;}#mermaid-svg-L8S09T5sfoOdsU6a .cluster span{color:#333;}#mermaid-svg-L8S09T5sfoOdsU6a div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-L8S09T5sfoOdsU6a .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-L8S09T5sfoOdsU6a rect.text{fill:none;stroke-width:0;}#mermaid-svg-L8S09T5sfoOdsU6a .icon-shape,#mermaid-svg-L8S09T5sfoOdsU6a .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-L8S09T5sfoOdsU6a .icon-shape p,#mermaid-svg-L8S09T5sfoOdsU6a .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-L8S09T5sfoOdsU6a .icon-shape .label rect,#mermaid-svg-L8S09T5sfoOdsU6a .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-L8S09T5sfoOdsU6a .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-L8S09T5sfoOdsU6a .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-L8S09T5sfoOdsU6a :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}#mermaid-svg-L8S09T5sfoOdsU6a .lv>*{fill:#eef6ff!important;stroke:#4a90d9!important;stroke-width:1px!important;}#mermaid-svg-L8S09T5sfoOdsU6a .lv span{fill:#eef6ff!important;stroke:#4a90d9!important;stroke-width:1px!important;} 长期 · 文件记忆 Agent
中期 · 压缩归纳
短期 · 工作上下文
超窗
会话 transcript (SQLite)

adapters/src/storage/session-store/
resume.ts → hydrateMessageHistoryFromSession

重建 provider-visible 上下文
compact/policy.ts shouldAutoCompact

窗口默认 200K, 阈值 −13K buffer
摘要写回 SQLite

compact-persistence.ts summaryMessageId
记忆提取子代理

memory/memory-agent-loop.ts (独立 LLM 循环)

工具白名单收窄: read-only + Write/Edit
每记忆一个 frontmatter .md + MEMORY.md 索引

/memories/projects/-/memory/
context/sections/memory.ts 注入

MEMORY.md 前 200 行/25KB + AGENTS.md

frontmatter 四型 ：type: user | feedback | project | reference（标准 auto-memory 模型）。
指令文件 ：根目录只有 AGENTS.md，以 # agentsMd 注入 meta_user（OVERRIDE 语义）；.agents/ 仅含技能。
子代理记忆 ：子代理有独立的 AgentMemoryScope 作用域记忆（subagent/persistent-memory.ts）。
应用侧读取防护 ：memoryService.ts 做符号链接/大小写/路径越界防护（UI 侧即 "Project Memory"）。

4. Tool System 工具系统架构

真正 LLM 层的工具系统捆绑在运行时 core/src/tool/。
#mermaid-svg-18E2n0h6yvIhCvcm{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-18E2n0h6yvIhCvcm .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-18E2n0h6yvIhCvcm .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-18E2n0h6yvIhCvcm .error-icon{fill:#552222;}#mermaid-svg-18E2n0h6yvIhCvcm .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-18E2n0h6yvIhCvcm .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-18E2n0h6yvIhCvcm .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-18E2n0h6yvIhCvcm .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-18E2n0h6yvIhCvcm .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-18E2n0h6yvIhCvcm .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-18E2n0h6yvIhCvcm .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-18E2n0h6yvIhCvcm .marker{fill:#333333;stroke:#333333;}#mermaid-svg-18E2n0h6yvIhCvcm .marker.cross{stroke:#333333;}#mermaid-svg-18E2n0h6yvIhCvcm svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-18E2n0h6yvIhCvcm p{margin:0;}#mermaid-svg-18E2n0h6yvIhCvcm .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-18E2n0h6yvIhCvcm .cluster-label text{fill:#333;}#mermaid-svg-18E2n0h6yvIhCvcm .cluster-label span{color:#333;}#mermaid-svg-18E2n0h6yvIhCvcm .cluster-label span p{background-color:transparent;}#mermaid-svg-18E2n0h6yvIhCvcm .label text,#mermaid-svg-18E2n0h6yvIhCvcm span{fill:#333;color:#333;}#mermaid-svg-18E2n0h6yvIhCvcm .node rect,#mermaid-svg-18E2n0h6yvIhCvcm .node circle,#mermaid-svg-18E2n0h6yvIhCvcm .node ellipse,#mermaid-svg-18E2n0h6yvIhCvcm .node polygon,#mermaid-svg-18E2n0h6yvIhCvcm .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-18E2n0h6yvIhCvcm .rough-node .label text,#mermaid-svg-18E2n0h6yvIhCvcm .node .label text,#mermaid-svg-18E2n0h6yvIhCvcm .image-shape .label,#mermaid-svg-18E2n0h6yvIhCvcm .icon-shape .label{text-anchor:middle;}#mermaid-svg-18E2n0h6yvIhCvcm .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-18E2n0h6yvIhCvcm .rough-node .label,#mermaid-svg-18E2n0h6yvIhCvcm .node .label,#mermaid-svg-18E2n0h6yvIhCvcm .image-shape .label,#mermaid-svg-18E2n0h6yvIhCvcm .icon-shape .label{text-align:center;}#mermaid-svg-18E2n0h6yvIhCvcm .node.clickable{cursor:pointer;}#mermaid-svg-18E2n0h6yvIhCvcm .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-18E2n0h6yvIhCvcm .arrowheadPath{fill:#333333;}#mermaid-svg-18E2n0h6yvIhCvcm .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-18E2n0h6yvIhCvcm .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-18E2n0h6yvIhCvcm .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-18E2n0h6yvIhCvcm .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-18E2n0h6yvIhCvcm .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-18E2n0h6yvIhCvcm .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-18E2n0h6yvIhCvcm .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-18E2n0h6yvIhCvcm .cluster text{fill:#333;}#mermaid-svg-18E2n0h6yvIhCvcm .cluster span{color:#333;}#mermaid-svg-18E2n0h6yvIhCvcm div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-18E2n0h6yvIhCvcm .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-18E2n0h6yvIhCvcm rect.text{fill:none;stroke-width:0;}#mermaid-svg-18E2n0h6yvIhCvcm .icon-shape,#mermaid-svg-18E2n0h6yvIhCvcm .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-18E2n0h6yvIhCvcm .icon-shape p,#mermaid-svg-18E2n0h6yvIhCvcm .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-18E2n0h6yvIhCvcm .icon-shape .label rect,#mermaid-svg-18E2n0h6yvIhCvcm .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-18E2n0h6yvIhCvcm .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-18E2n0h6yvIhCvcm .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-18E2n0h6yvIhCvcm :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}#mermaid-svg-18E2n0h6yvIhCvcm .tool>*{fill:#fff7e6!important;stroke:#e8a000!important;stroke-width:1px!important;}#mermaid-svg-18E2n0h6yvIhCvcm .tool span{fill:#fff7e6!important;stroke:#e8a000!important;stroke-width:1px!important;} 供权限流判断
LLM 请求 tool_call
registry.ts

register / get / toContracts
tool/executor/call-runner.ts
入参归一化 input-normalization.ts
schema 校验 validation.ts
权限流 permission-flow.ts
pre/post 钩子 hook-flow.ts
超时 timeout.ts
执行 impl.ts
结果回填 runtime/helpers/tool-result.ts

modelContentForToolResult / isErrorForToolResult
回灌模型上下文 → 继续循环
bash 只读分类器

tool/handlers/bash-semantics.ts

壳层只提供权限策略面 ：toolAllowlist/toolDenylist 全程透传（session create/resume 防冷恢复丢约束）；模式 plan/build/edit/yolo/auto；决策 allow/deny/escalate/modify；automationToolPolicy.ts 限制自动化变体；CUA 走独立 cua-permission-broker 通道。

5. Multi-Agent Orchestration 多智能体编排

Workflow DSL + 子会话（子进程） 两级模型。
#mermaid-svg-jT86uLDxgL77ZxVl{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-jT86uLDxgL77ZxVl .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-jT86uLDxgL77ZxVl .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-jT86uLDxgL77ZxVl .error-icon{fill:#552222;}#mermaid-svg-jT86uLDxgL77ZxVl .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-jT86uLDxgL77ZxVl .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-jT86uLDxgL77ZxVl .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-jT86uLDxgL77ZxVl .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-jT86uLDxgL77ZxVl .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-jT86uLDxgL77ZxVl .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-jT86uLDxgL77ZxVl .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-jT86uLDxgL77ZxVl .marker{fill:#333333;stroke:#333333;}#mermaid-svg-jT86uLDxgL77ZxVl .marker.cross{stroke:#333333;}#mermaid-svg-jT86uLDxgL77ZxVl svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-jT86uLDxgL77ZxVl p{margin:0;}#mermaid-svg-jT86uLDxgL77ZxVl .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-jT86uLDxgL77ZxVl .cluster-label text{fill:#333;}#mermaid-svg-jT86uLDxgL77ZxVl .cluster-label span{color:#333;}#mermaid-svg-jT86uLDxgL77ZxVl .cluster-label span p{background-color:transparent;}#mermaid-svg-jT86uLDxgL77ZxVl .label text,#mermaid-svg-jT86uLDxgL77ZxVl span{fill:#333;color:#333;}#mermaid-svg-jT86uLDxgL77ZxVl .node rect,#mermaid-svg-jT86uLDxgL77ZxVl .node circle,#mermaid-svg-jT86uLDxgL77ZxVl .node ellipse,#mermaid-svg-jT86uLDxgL77ZxVl .node polygon,#mermaid-svg-jT86uLDxgL77ZxVl .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-jT86uLDxgL77ZxVl .rough-node .label text,#mermaid-svg-jT86uLDxgL77ZxVl .node .label text,#mermaid-svg-jT86uLDxgL77ZxVl .image-shape .label,#mermaid-svg-jT86uLDxgL77ZxVl .icon-shape .label{text-anchor:middle;}#mermaid-svg-jT86uLDxgL77ZxVl .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-jT86uLDxgL77ZxVl .rough-node .label,#mermaid-svg-jT86uLDxgL77ZxVl .node .label,#mermaid-svg-jT86uLDxgL77ZxVl .image-shape .label,#mermaid-svg-jT86uLDxgL77ZxVl .icon-shape .label{text-align:center;}#mermaid-svg-jT86uLDxgL77ZxVl .node.clickable{cursor:pointer;}#mermaid-svg-jT86uLDxgL77ZxVl .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-jT86uLDxgL77ZxVl .arrowheadPath{fill:#333333;}#mermaid-svg-jT86uLDxgL77ZxVl .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-jT86uLDxgL77ZxVl .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-jT86uLDxgL77ZxVl .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-jT86uLDxgL77ZxVl .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-jT86uLDxgL77ZxVl .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-jT86uLDxgL77ZxVl .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-jT86uLDxgL77ZxVl .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-jT86uLDxgL77ZxVl .cluster text{fill:#333;}#mermaid-svg-jT86uLDxgL77ZxVl .cluster span{color:#333;}#mermaid-svg-jT86uLDxgL77ZxVl div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-jT86uLDxgL77ZxVl .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-jT86uLDxgL77ZxVl rect.text{fill:none;stroke-width:0;}#mermaid-svg-jT86uLDxgL77ZxVl .icon-shape,#mermaid-svg-jT86uLDxgL77ZxVl .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-jT86uLDxgL77ZxVl .icon-shape p,#mermaid-svg-jT86uLDxgL77ZxVl .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-jT86uLDxgL77ZxVl .icon-shape .label rect,#mermaid-svg-jT86uLDxgL77ZxVl .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-jT86uLDxgL77ZxVl .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-jT86uLDxgL77ZxVl .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-jT86uLDxgL77ZxVl :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}#mermaid-svg-jT86uLDxgL77ZxVl .org>*{fill:#ffeef0!important;stroke:#d94a5a!important;stroke-width:1px!important;}#mermaid-svg-jT86uLDxgL77ZxVl .org span{fill:#ffeef0!important;stroke:#d94a5a!important;stroke-width:1px!important;} 子会话 (独立进程经 stdio 拉起)
Workflow DSL:

agent() / phase() / lanes / handoffs(many 并行扇出)
分叉
编辑选区侧聊
事件经 v4 protocol 还原到父会话
workflow_parent 会话
Child
subagent_child / 研究员/工作角色
nested_workflow_child
fork
selection_side_chat

会话分型 zcodeSessionKindSchema（zcode-protocol-legacy-types.ts:83-91）：workflow_parent / workflow_child / subagent_child / nested_workflow_child / fork / selection_side_chat。
运行态投影：workflow-runs.ts / workflow-runs-phases.ts / workflow-runs-reducer.ts（可复现因果图 reduce）。
Subagent 管理服务：packages/services/src/subagents/。
子会话通常作为独立进程经 stdio 拉起 （zcodeAgentProcessManager），共享同一 v4 协议契约。

6. Permission and Security Model 权限与安全模型

#mermaid-svg-COQoBHukn3YxwW0O{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-COQoBHukn3YxwW0O .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-COQoBHukn3YxwW0O .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-COQoBHukn3YxwW0O .error-icon{fill:#552222;}#mermaid-svg-COQoBHukn3YxwW0O .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-COQoBHukn3YxwW0O .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-COQoBHukn3YxwW0O .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-COQoBHukn3YxwW0O .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-COQoBHukn3YxwW0O .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-COQoBHukn3YxwW0O .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-COQoBHukn3YxwW0O .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-COQoBHukn3YxwW0O .marker{fill:#333333;stroke:#333333;}#mermaid-svg-COQoBHukn3YxwW0O .marker.cross{stroke:#333333;}#mermaid-svg-COQoBHukn3YxwW0O svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-COQoBHukn3YxwW0O p{margin:0;}#mermaid-svg-COQoBHukn3YxwW0O .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-COQoBHukn3YxwW0O .cluster-label text{fill:#333;}#mermaid-svg-COQoBHukn3YxwW0O .cluster-label span{color:#333;}#mermaid-svg-COQoBHukn3YxwW0O .cluster-label span p{background-color:transparent;}#mermaid-svg-COQoBHukn3YxwW0O .label text,#mermaid-svg-COQoBHukn3YxwW0O span{fill:#333;color:#333;}#mermaid-svg-COQoBHukn3YxwW0O .node rect,#mermaid-svg-COQoBHukn3YxwW0O .node circle,#mermaid-svg-COQoBHukn3YxwW0O .node ellipse,#mermaid-svg-COQoBHukn3YxwW0O .node polygon,#mermaid-svg-COQoBHukn3YxwW0O .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-COQoBHukn3YxwW0O .rough-node .label text,#mermaid-svg-COQoBHukn3YxwW0O .node .label text,#mermaid-svg-COQoBHukn3YxwW0O .image-shape .label,#mermaid-svg-COQoBHukn3YxwW0O .icon-shape .label{text-anchor:middle;}#mermaid-svg-COQoBHukn3YxwW0O .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-COQoBHukn3YxwW0O .rough-node .label,#mermaid-svg-COQoBHukn3YxwW0O .node .label,#mermaid-svg-COQoBHukn3YxwW0O .image-shape .label,#mermaid-svg-COQoBHukn3YxwW0O .icon-shape .label{text-align:center;}#mermaid-svg-COQoBHukn3YxwW0O .node.clickable{cursor:pointer;}#mermaid-svg-COQoBHukn3YxwW0O .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-COQoBHukn3YxwW0O .arrowheadPath{fill:#333333;}#mermaid-svg-COQoBHukn3YxwW0O .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-COQoBHukn3YxwW0O .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-COQoBHukn3YxwW0O .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-COQoBHukn3YxwW0O .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-COQoBHukn3YxwW0O .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-COQoBHukn3YxwW0O .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-COQoBHukn3YxwW0O .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-COQoBHukn3YxwW0O .cluster text{fill:#333;}#mermaid-svg-COQoBHukn3YxwW0O .cluster span{color:#333;}#mermaid-svg-COQoBHukn3YxwW0O div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-COQoBHukn3YxwW0O .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-COQoBHukn3YxwW0O rect.text{fill:none;stroke-width:0;}#mermaid-svg-COQoBHukn3YxwW0O .icon-shape,#mermaid-svg-COQoBHukn3YxwW0O .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-COQoBHukn3YxwW0O .icon-shape p,#mermaid-svg-COQoBHukn3YxwW0O .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-COQoBHukn3YxwW0O .icon-shape .label rect,#mermaid-svg-COQoBHukn3YxwW0O .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-COQoBHukn3YxwW0O .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-COQoBHukn3YxwW0O .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-COQoBHukn3YxwW0O :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}#mermaid-svg-COQoBHukn3YxwW0O .sec>*{fill:#eafaf0!important;stroke:#2fa26a!important;stroke-width:1px!important;}#mermaid-svg-COQoBHukn3YxwW0O .sec span{fill:#eafaf0!important;stroke:#2fa26a!important;stroke-width:1px!important;} 约束
约束
旁路专用
工具/命令请求
模式枚举

plan/build/edit/yolo/auto

默认兜底 permissionMode ?? yolo
规则行为

allow / deny / ask
决策

allow / deny / escalate / modify
响应 zcodePermissionResponseSchema

decision / reason / modifiedInput / permissionUpdates
toolAllowlist / toolDenylist

session create/resume 全程透传
automationToolPolicy.ts

自动化/非高峰限流变异工具
CUA 独立权限通道

cua-permission-broker + 桌面授权面板

本壳层提供策略面；真正的工具鉴权与提示注入防御在捆绑 runtime 内。
无独立的"prompt injection"过滤字符串于本层------该防御在捆绑 runtime。
决策含 WORKFLOW_REFINE_PERMISSION_OPTION_ID（Workflow 确认窗 Refine）。

7. Services Layer 服务层架构

服务 = RPC channel。
#mermaid-svg-hsrraXpzMXmLHVlA{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-hsrraXpzMXmLHVlA .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-hsrraXpzMXmLHVlA .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-hsrraXpzMXmLHVlA .error-icon{fill:#552222;}#mermaid-svg-hsrraXpzMXmLHVlA .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-hsrraXpzMXmLHVlA .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-hsrraXpzMXmLHVlA .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-hsrraXpzMXmLHVlA .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-hsrraXpzMXmLHVlA .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-hsrraXpzMXmLHVlA .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-hsrraXpzMXmLHVlA .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-hsrraXpzMXmLHVlA .marker{fill:#333333;stroke:#333333;}#mermaid-svg-hsrraXpzMXmLHVlA .marker.cross{stroke:#333333;}#mermaid-svg-hsrraXpzMXmLHVlA svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-hsrraXpzMXmLHVlA p{margin:0;}#mermaid-svg-hsrraXpzMXmLHVlA .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-hsrraXpzMXmLHVlA .cluster-label text{fill:#333;}#mermaid-svg-hsrraXpzMXmLHVlA .cluster-label span{color:#333;}#mermaid-svg-hsrraXpzMXmLHVlA .cluster-label span p{background-color:transparent;}#mermaid-svg-hsrraXpzMXmLHVlA .label text,#mermaid-svg-hsrraXpzMXmLHVlA span{fill:#333;color:#333;}#mermaid-svg-hsrraXpzMXmLHVlA .node rect,#mermaid-svg-hsrraXpzMXmLHVlA .node circle,#mermaid-svg-hsrraXpzMXmLHVlA .node ellipse,#mermaid-svg-hsrraXpzMXmLHVlA .node polygon,#mermaid-svg-hsrraXpzMXmLHVlA .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-hsrraXpzMXmLHVlA .rough-node .label text,#mermaid-svg-hsrraXpzMXmLHVlA .node .label text,#mermaid-svg-hsrraXpzMXmLHVlA .image-shape .label,#mermaid-svg-hsrraXpzMXmLHVlA .icon-shape .label{text-anchor:middle;}#mermaid-svg-hsrraXpzMXmLHVlA .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-hsrraXpzMXmLHVlA .rough-node .label,#mermaid-svg-hsrraXpzMXmLHVlA .node .label,#mermaid-svg-hsrraXpzMXmLHVlA .image-shape .label,#mermaid-svg-hsrraXpzMXmLHVlA .icon-shape .label{text-align:center;}#mermaid-svg-hsrraXpzMXmLHVlA .node.clickable{cursor:pointer;}#mermaid-svg-hsrraXpzMXmLHVlA .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-hsrraXpzMXmLHVlA .arrowheadPath{fill:#333333;}#mermaid-svg-hsrraXpzMXmLHVlA .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-hsrraXpzMXmLHVlA .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-hsrraXpzMXmLHVlA .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-hsrraXpzMXmLHVlA .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-hsrraXpzMXmLHVlA .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-hsrraXpzMXmLHVlA .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-hsrraXpzMXmLHVlA .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-hsrraXpzMXmLHVlA .cluster text{fill:#333;}#mermaid-svg-hsrraXpzMXmLHVlA .cluster span{color:#333;}#mermaid-svg-hsrraXpzMXmLHVlA div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-hsrraXpzMXmLHVlA .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-hsrraXpzMXmLHVlA rect.text{fill:none;stroke-width:0;}#mermaid-svg-hsrraXpzMXmLHVlA .icon-shape,#mermaid-svg-hsrraXpzMXmLHVlA .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-hsrraXpzMXmLHVlA .icon-shape p,#mermaid-svg-hsrraXpzMXmLHVlA .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-hsrraXpzMXmLHVlA .icon-shape .label rect,#mermaid-svg-hsrraXpzMXmLHVlA .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-hsrraXpzMXmLHVlA .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-hsrraXpzMXmLHVlA .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-hsrraXpzMXmLHVlA :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}#mermaid-svg-hsrraXpzMXmLHVlA .svc>*{fill:#f5f0ff!important;stroke:#7c6cf0!important;stroke-width:1px!important;}#mermaid-svg-hsrraXpzMXmLHVlA .svc span{fill:#f5f0ff!important;stroke:#7c6cf0!important;stroke-width:1px!important;} @zcode/client

messageport / websocket
ProxyChannel.fromService

自动代理
ChannelServer

persistent-protocol / remote / ipc
ServiceCollection

descriptors.ts (channelName + phantom type)
node.ts register() 约 40 个领域服务

file / git / system / terminal / setting / credential

broadcast / zcode-agent / zcode-session / subagents / skills

mcp-sync / plugins / commands / memory / model-provider

oauth / cua-permission-broker / usage-stats / ...

ServiceDescriptor = channelName + phantom type；ServiceCollection.register/get/getOptional/exposeOnChannelServer。
浏览器安全边界 ：根入口保持 browser-safe，Node 专属实现仅经 @zcode/services/node 引入。

8. State and Data Flow 状态管理与数据流

#mermaid-svg-sOmEIrxgugQDFyWs{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-sOmEIrxgugQDFyWs .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-sOmEIrxgugQDFyWs .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-sOmEIrxgugQDFyWs .error-icon{fill:#552222;}#mermaid-svg-sOmEIrxgugQDFyWs .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-sOmEIrxgugQDFyWs .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-sOmEIrxgugQDFyWs .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-sOmEIrxgugQDFyWs .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-sOmEIrxgugQDFyWs .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-sOmEIrxgugQDFyWs .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-sOmEIrxgugQDFyWs .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-sOmEIrxgugQDFyWs .marker{fill:#333333;stroke:#333333;}#mermaid-svg-sOmEIrxgugQDFyWs .marker.cross{stroke:#333333;}#mermaid-svg-sOmEIrxgugQDFyWs svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-sOmEIrxgugQDFyWs p{margin:0;}#mermaid-svg-sOmEIrxgugQDFyWs .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-sOmEIrxgugQDFyWs .cluster-label text{fill:#333;}#mermaid-svg-sOmEIrxgugQDFyWs .cluster-label span{color:#333;}#mermaid-svg-sOmEIrxgugQDFyWs .cluster-label span p{background-color:transparent;}#mermaid-svg-sOmEIrxgugQDFyWs .label text,#mermaid-svg-sOmEIrxgugQDFyWs span{fill:#333;color:#333;}#mermaid-svg-sOmEIrxgugQDFyWs .node rect,#mermaid-svg-sOmEIrxgugQDFyWs .node circle,#mermaid-svg-sOmEIrxgugQDFyWs .node ellipse,#mermaid-svg-sOmEIrxgugQDFyWs .node polygon,#mermaid-svg-sOmEIrxgugQDFyWs .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-sOmEIrxgugQDFyWs .rough-node .label text,#mermaid-svg-sOmEIrxgugQDFyWs .node .label text,#mermaid-svg-sOmEIrxgugQDFyWs .image-shape .label,#mermaid-svg-sOmEIrxgugQDFyWs .icon-shape .label{text-anchor:middle;}#mermaid-svg-sOmEIrxgugQDFyWs .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-sOmEIrxgugQDFyWs .rough-node .label,#mermaid-svg-sOmEIrxgugQDFyWs .node .label,#mermaid-svg-sOmEIrxgugQDFyWs .image-shape .label,#mermaid-svg-sOmEIrxgugQDFyWs .icon-shape .label{text-align:center;}#mermaid-svg-sOmEIrxgugQDFyWs .node.clickable{cursor:pointer;}#mermaid-svg-sOmEIrxgugQDFyWs .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-sOmEIrxgugQDFyWs .arrowheadPath{fill:#333333;}#mermaid-svg-sOmEIrxgugQDFyWs .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-sOmEIrxgugQDFyWs .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-sOmEIrxgugQDFyWs .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-sOmEIrxgugQDFyWs .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-sOmEIrxgugQDFyWs .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-sOmEIrxgugQDFyWs .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-sOmEIrxgugQDFyWs .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-sOmEIrxgugQDFyWs .cluster text{fill:#333;}#mermaid-svg-sOmEIrxgugQDFyWs .cluster span{color:#333;}#mermaid-svg-sOmEIrxgugQDFyWs div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-sOmEIrxgugQDFyWs .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-sOmEIrxgugQDFyWs rect.text{fill:none;stroke-width:0;}#mermaid-svg-sOmEIrxgugQDFyWs .icon-shape,#mermaid-svg-sOmEIrxgugQDFyWs .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-sOmEIrxgugQDFyWs .icon-shape p,#mermaid-svg-sOmEIrxgugQDFyWs .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-sOmEIrxgugQDFyWs .icon-shape .label rect,#mermaid-svg-sOmEIrxgugQDFyWs .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-sOmEIrxgugQDFyWs .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-sOmEIrxgugQDFyWs .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-sOmEIrxgugQDFyWs :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}#mermaid-svg-sOmEIrxgugQDFyWs .st>*{fill:#eef7f0!important;stroke:#42a25a!important;stroke-width:1px!important;}#mermaid-svg-sOmEIrxgugQDFyWs .st span{fill:#eef7f0!important;stroke:#42a25a!important;stroke-width:1px!important;} 壳层状态
readonly 订阅
约束
流事件
运行时事实源
session 事件流

zcodeSessionEventCoalescer 合并
快照 / revision 投影

zcode-protocol-v4/snapshot.ts
Zustand store

packages/ui/src/store/

zcodeSessionStore (+task/workspace slice)

tabStore / mcpStore / subagentsStore ...
packages/ui/src/hooks/

访问服务 (需 .tsx if JSX)
UI 局部状态 ≠ 服务端事实

广播主题/语言防回环

Host owner/lease 负责路由

协议单文件契约 zcode-protocol/index.ts（ZCODE_PROTOCOL_VERSION=1，v4 wire=3，legacy 并存待弃），约 257 导出，分：请求/响应、事件通知、快照投影、Workflow 因果图、工具结果、权限规则/决策、model/usage。
UI 组件经 hooks/ 访问服务，不直接调用 Repo/Service 实现细节；平台操作经 IPlatformService，不直接调用 window.zcode。

9. 总览：一次用户输入的完整脉络

#mermaid-svg-Ix0hazLvql47oD1I{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-Ix0hazLvql47oD1I .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-Ix0hazLvql47oD1I .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-Ix0hazLvql47oD1I .error-icon{fill:#552222;}#mermaid-svg-Ix0hazLvql47oD1I .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-Ix0hazLvql47oD1I .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-Ix0hazLvql47oD1I .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-Ix0hazLvql47oD1I .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-Ix0hazLvql47oD1I .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-Ix0hazLvql47oD1I .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-Ix0hazLvql47oD1I .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-Ix0hazLvql47oD1I .marker{fill:#333333;stroke:#333333;}#mermaid-svg-Ix0hazLvql47oD1I .marker.cross{stroke:#333333;}#mermaid-svg-Ix0hazLvql47oD1I svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-Ix0hazLvql47oD1I p{margin:0;}#mermaid-svg-Ix0hazLvql47oD1I .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-Ix0hazLvql47oD1I .cluster-label text{fill:#333;}#mermaid-svg-Ix0hazLvql47oD1I .cluster-label span{color:#333;}#mermaid-svg-Ix0hazLvql47oD1I .cluster-label span p{background-color:transparent;}#mermaid-svg-Ix0hazLvql47oD1I .label text,#mermaid-svg-Ix0hazLvql47oD1I span{fill:#333;color:#333;}#mermaid-svg-Ix0hazLvql47oD1I .node rect,#mermaid-svg-Ix0hazLvql47oD1I .node circle,#mermaid-svg-Ix0hazLvql47oD1I .node ellipse,#mermaid-svg-Ix0hazLvql47oD1I .node polygon,#mermaid-svg-Ix0hazLvql47oD1I .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Ix0hazLvql47oD1I .rough-node .label text,#mermaid-svg-Ix0hazLvql47oD1I .node .label text,#mermaid-svg-Ix0hazLvql47oD1I .image-shape .label,#mermaid-svg-Ix0hazLvql47oD1I .icon-shape .label{text-anchor:middle;}#mermaid-svg-Ix0hazLvql47oD1I .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-Ix0hazLvql47oD1I .rough-node .label,#mermaid-svg-Ix0hazLvql47oD1I .node .label,#mermaid-svg-Ix0hazLvql47oD1I .image-shape .label,#mermaid-svg-Ix0hazLvql47oD1I .icon-shape .label{text-align:center;}#mermaid-svg-Ix0hazLvql47oD1I .node.clickable{cursor:pointer;}#mermaid-svg-Ix0hazLvql47oD1I .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-Ix0hazLvql47oD1I .arrowheadPath{fill:#333333;}#mermaid-svg-Ix0hazLvql47oD1I .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-Ix0hazLvql47oD1I .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-Ix0hazLvql47oD1I .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Ix0hazLvql47oD1I .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-Ix0hazLvql47oD1I .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Ix0hazLvql47oD1I .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-Ix0hazLvql47oD1I .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-Ix0hazLvql47oD1I .cluster text{fill:#333;}#mermaid-svg-Ix0hazLvql47oD1I .cluster span{color:#333;}#mermaid-svg-Ix0hazLvql47oD1I div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-Ix0hazLvql47oD1I .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-Ix0hazLvql47oD1I rect.text{fill:none;stroke-width:0;}#mermaid-svg-Ix0hazLvql47oD1I .icon-shape,#mermaid-svg-Ix0hazLvql47oD1I .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Ix0hazLvql47oD1I .icon-shape p,#mermaid-svg-Ix0hazLvql47oD1I .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-Ix0hazLvql47oD1I .icon-shape .label rect,#mermaid-svg-Ix0hazLvql47oD1I .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Ix0hazLvql47oD1I .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-Ix0hazLvql47oD1I .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-Ix0hazLvql47oD1I :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}#mermaid-svg-Ix0hazLvql47oD1I .k>*{fill:#eaf4ff!important;stroke:#4a90d9!important;stroke-width:1px!important;}#mermaid-svg-Ix0hazLvql47oD1I .k span{fill:#eaf4ff!important;stroke:#4a90d9!important;stroke-width:1px!important;} admit + execute
超窗
用户输入
Renderer/UI (pending optimistic)
Host sendPrompt
v4 命令信封 JSON\

CommandInbox 串行 gate
core 运行时
短期: 会话上下文 SQLite 重建
长期: MEMORY.md 索引 + AGENTS.md
中期: compaction 摘要
工具执行 (registry→权限→executor→回填)
模型循环 → 流式事件
stdout → Host 传输 → RPC → Renderer 增量更新
快照 / revision 投影到 UI

附：关键文件速查

关注点	文件
桌面入口	`packages/desktop/src/main/index.ts`、`desktopHostProcess.ts`
Agent stdio	`packages/services/src/zcode-agent/{zcodeAgentProcessManager,zcodeStdioTransport,zcodeProtocolClient}.ts`
协议契约	`packages/shared/src/zcode-protocol/index.ts`、`zcode-protocol-v4/`
串行 admission	`apps/zcode-cli/packages/bootstrap/src/zcode-protocol-v4/{v4-gateway,command-inbox}.ts`、`v4-bridge.ts`
记忆长期	`apps/zcode-cli/packages/core/src/memory/`、`packages/services/src/memory/memoryService.ts`
记忆短期/中期	`core/src/context/`、`core/src/session-context/`、`core/src/compact/`
工具系统	`core/src/tool/{registry,executor}.ts`、`runtime/helpers/tool-result.ts`
子代理/编排	`core/src/subagent/`、`packages/services/src/subagents/`、`zcode-protocol-v4/workflow-runs*.ts`
权限	`packages/shared/src/zcode-protocol-legacy-types.ts`、`zcode-agent/automationToolPolicy.ts`、`cua-permission-broker/`
服务层 DI	`packages/services/src/{descriptors,collection,node}.ts`、`packages/rpc/src/proxy-channel.ts`
UI 状态	`packages/ui/src/store/`、`packages/ui/src/hooks/`、`packages/ui/src/logger.ts`