架构与进程
- Renderer — React UI 层（Desktop/Web/Mobile），只拥有草稿、选择态、筛选范围等本地状态；不持有权威会话。
- Host / Window Host — 每个窗口唯一的进程（唯一 PID），拥有窗口级服务、凭证、远程连接、进程监督、附件路由、平台 IO。
- Main Process — Electron 主进程，只做窗口生命周期、原生能力、Host 监督与 attachment 薄转发。
- zcode-cli — Agent CLI 进程，每个
workspaceKey 最多一个；conversation 的权威事实源。
- workspaceKey —
workspaceIdentity?.trim() || workspacePath；用于身份/隔离（CLI 映射、session 绑定、缓存、队列、持久化）。
- workspacePath — 用于文件执行（cwd、读写、Git、路径展示）。
- remoteSessionId — 远端逻辑会话标识，由 Window Host 分配；与 workspaceKey 一起贯穿远控链路。
协议与会话
- ZCode Protocol — App/Host/CLI 之间唯一的 Agent 协议；当前聊天主链路走 V4。
- V4 / zcode-protocol-v4 — 新一代协议（wire v3）：commands、transport、snapshot/delta、workflow-runs。
- legacy v1 —
packages/shared/src/zcode-protocol/index.ts 的旧 session schema（~257 导出，承重旧栈，待删除）。
- CommandInbox — CLI/runtime 的串行输入 admission 权威：幂等、epoch、CAS、product guard、per-key/per-session FIFO gate。
- ProductProjection — 面向客户端的可重建视图；
SessionEvent → ProductProjection → Snapshot/Delta。
- ConversationSnapshot — 完整可恢复视图（session 元信息、rows、queue、interactions、model/mode、usage/goal 等）。
- delta / seq / revision / logEpoch — 增量、序号、CAS 版本、日志纪元；客户端只按 seq 连续应用 delta，gap 时重新订阅收敛。
- clientMode / deliveryProfile —
desktop-continuous（连续实时）或 web-remote-replayable（gap 时 snapshot 恢复），由 host 在连接建立时注入。
- Command ≠ Call — V4 命令是业务意图（如
sendText）；V4 调用是把命令送到下一跳的 Service API 调用。
Agent 运行时
- AgentRuntime — CLI Agent 核心（
core/src/runtime/agent-runtime.ts），承载 turn、model、tool、memory、subagent。
- Turn — 一轮工作；入口
executeTurn。
- Turn 状态机 —
processing_input → awaiting_model_response → streaming → scheduling_tools → executing_tools/awaiting_permission → aggregating_results → completing。
- Session Event Store — append-only 事件 + reducer，live/replay 顺序事实源。
- Part — 消息组成部分（text/reasoning/file/agent/compaction/timeline/subtask/retry/step/snapshot/patch/tool）。
- compact — 上下文压缩；阈值 = context window 扣 output reserve 再留 13K buffer。
- resume / rewind / branch / fork — 会话恢复、回退、分支、分叉。
- subagent — 子代理；内置
general-purpose、Explore，插件可贡献（如 visual-judge）。
工具与安全
- Tool Contract — 工具元数据（readOnly/destructive/concurrentSafe/sideEffectScope/risk/timeout/output budget/approval/turn-control）。
- Scheduler — 按工具元数据拓扑排序、分组并发。
- 权限模式 — 默认
build；独立 CLI --prompt 未指定 --mode 时为 yolo。
- Hook — 进程型生命周期挂点（SessionStart/UserPromptSubmit/PreToolUse/PermissionRequest/PostToolUse/PostToolUseFailure/Stop）。
- fail-closed — 失败或未授权时拒绝执行；CUA、账号 provider overlay、远端断连 mutation 等都采用。
扩展生态
- Official Marketplace — 官方唯一分发渠道，id
zcode-plugins-official，= Builtin + CDN。
- Builtin / CDN Plugin — 随包 seed 的内置插件 / 经官方 CDN zip 按需下载的插件。
- Personal Source — 用户自加的一切插件来源（
claude-plugins-official、git/GitHub/URL/本地目录、inline）。
- Restorable Builtin — 被卸载入抑制态、可从 Public Segment 恢复的内置插件。
- Orphaned Installed Plugin — 来源被删、安装目录/数据保留、仍可用但不能更新的插件。
- Plugin Manifest — 包内
plugin.json 的功能定义（commands/agents/skills/hooks/mcpServers/userConfig）。
- Store Listing — 目录条目的展示元数据，不影响插件功能。
- UI Plugin — 提供
ui.surfaces 面板或 tool _meta.ui.resourceUri 页面的插件（区别于仅 MCP/skill 的能力插件）。
- MCP Apps — 插件 HTML 页面的官方线协议（
@modelcontextprotocol/ext-apps）+ ZCode 扩展。
- Skill — 含
SKILL.md 的目录；发现优先级 .zcode/skills > .agents/skills，逐级向上合并。
- 限定技能名 — 插件技能为
<plugin>:<skill>。
- bundled-skills — 不可卸载、不进市场的系统技能根（当前仅
dynamic-workflows）。
- Dynamic Workflow — 模型写 TypeScript 脚本指挥多 subagent（工具
CreateWorkflow）；与旧 Workflow//expert 不同。
- Site / Instance — facade 调用的稳定 id / 每次执行；journal 支撑重跑恢复。
工程
- architecture-policy.yaml — 可执行的组织级模块契约（module/layer/requires/publicEntrypoints + 全局限额）。
- managed module — 已完成迁移、受架构检查严格约束的模块（storage、gen-ui、plugin-ui 等）。
- Ratchet baseline — 违规指纹基线；命中为存量不阻断，新指纹才 FAIL。
- fork-isolated test — 需串行 forks 的 Vitest 测试白名单（每条对应真实故障）。
- SEA — Node Single Executable Application，用
postject 注入 blob。
- 统一分发 —
zcode 发行包（TUI + Web + Agent），--web 由 launcher 分流。
相关页面