ZCode 总览

是什么

ZCode 是智谱 / Z.ai（GitHub 组织 zai-org）开源的 AI 编程工作台（AI Coding Workbench）。它不是单一的 CLI 工具，而是一套多形态客户端 + 独立 Agent 运行时的完整产品：桌面应用（Electron）、浏览器界面（Web）、手机远控、终端 Agent（CLI/TUI），以及可独立部署的 Server。整个仓库包含客户端、后端服务、共享 UI，以及 Agent CLI 与运行时源码。

GitHub: https://github.com/zai-org/ZCode
许可：Apache-2.0
语言：TypeScript（pnpm monorepo）+ 少量 Kotlin（Android 远控壳）
运行环境：Node ≥ 24（精确 24.14.0，以 mise.toml 为准），pnpm 10.33.2
分析基线：master @ aac4755（v3.15.1，2026-10-10）

三种交付形态

形态	入口	说明
桌面版（Desktop）	`pnpm dev:desktop`	Electron 应用，主形态：AI 工作台 + 多窗口 workspace
Web 版	`pnpm dev:web`	浏览器界面；同一后端同时托管 Web 页面与 Agent
命令行版（CLI/TUI/Web）	`zcode` / `zcode --web`	Node 发行包，含 TUI、Web 与 Agent，无需 Electron

发行包统一用 zcode 启动：无参数进入 TUI；第一个参数为 --web 时启动 Web；其余参数交给底层 Agent CLI。统一分发方案见 distribution。

一句话架构

ZCode 的核心模型是三层运行边界：

Renderer（Desktop / Web / Mobile）
   Composer / Settings / Timeline / Charts / Workbench UI
        │ intent、query、projection subscription
        ▼
Host（Local / SSH / WSL / Docker / Shared Host）
   platform services / process supervision / routing / attachment
        │ ZCode Protocol / service RPC
        ▼
ZCode CLI
   AgentRuntime / CommandInbox / ProductProjection /
   session event journal / usage SQLite

Renderer 只拥有草稿、选择态等纯本地展示状态，不持有会话正文或 Agent 运行态。
Host 拥有窗口级服务、凭证、远程连接、进程监督、附件路由、平台 IO。
ZCode CLI 是 conversation 的唯一权威事实源：Agent/turn、CommandInbox、ProductProjection、session event、模型/工具执行、会话恢复。

详见 architecture。

快速上手（源码方式）

# 以 mise.toml 为准：Node 24.14.0 / pnpm 10.33.2
pnpm bootstrap          # 安装依赖 + 准备桌面本地资源 + build:bootstrap
pnpm dev:desktop        # 桌面开发（默认生产服务配置）
pnpm dev:web            # Web 开发（前端 5173 / 后端 3030）
 
# CLI 源码开发
pnpm --filter @zcode/cli dev --help
node apps/zcode-cli/packages/cli/dist/zcode.cjs --help

主包：根 zcode（private workspace）、@zcode/cli（apps/zcode-cli）、@zcode/desktop、@zcode/web、@zcode/server、@zcode/server-cli。

一图看懂组成

层	内容	详见
仓库组织	根 workspace（`packages/*`）+ 嵌套 CLI workspace（`apps/zcode-cli`）	monorepo
运行架构	Renderer / Host / CLI 三层、Main↔Host↔CLI 进程模型	architecture
Agent 核心	AgentRuntime、turn 状态机、context/compact、stream recovery	agent-core
会话运行时	session event journal、SQLite、ProductProjection、resume/rewind	session-runtime
通信协议	ZCode Protocol（legacy v1 + V4）、command inbox、topic snapshot/delta	zcode-protocol
终端界面	CLI 命令分发、TUI（OpenTUI + React）、headless 输出	cli-tui
模型能力	Provider Registry、Model runtime、model-option-map	model-provider
工具与安全	内置工具、调度器、执行流水线、权限审批	tool-system
桌面应用	Electron main/host/renderer、plugin sandbox、附件注册表	desktop
服务与远控	HTTP/WS server、server-cli Supervisor/Core、SSH/WSL/Docker、手机远控	server-remote
Web / 手机	Web 客户端、远控 SPA、会话分享、Android 壳	web-mobile
扩展生态	插件市场、Skills、MCP、动态工作流、Office/CUA	plugin-system、skills-system、mcp-integration、dynamic-workflow、office-computer-use
工程面	构建、测试矩阵、GitLab CI、架构治理	engineering、distribution

值得注意的点

单窗口唯一 Host：每个 workspace window 有且只有一个 Window Host（唯一 PID），每个 workspaceKey 最多一个聊天 CLI；远程 workspace 的连接与 scoped services 也由同一 Host 管理。见 desktop。
CLI 是权威状态源：消息行、运行阶段、队列、交互请求、usage、goal 全部来自 CLI 的 ConversationSnapshot；Main、relay、Renderer 都不得持有第二份权威会话。见 zcode-protocol。
两代协议并存：packages/shared/src/zcode-protocol（legacy v1，~257 导出，明确待删）与 zcode-protocol-v4（V4，wire v3）共存；新功能走 V4。
两种投递语义：桌面 desktop-continuous（连续实时）与手机 web-remote-replayable（gap 时 snapshot 恢复）由 Host 在连接建立时注入，客户端不可自选。
插件生态三层：官方市场（Builtin + CDN 分片）、Personal Source（用户自加）、不入市场的系统内置（node-repl-host、bundled-skills）。见 plugin-system。
跨工具兼容：插件兼容 Claude Code / Codex 的 manifest（.claude-plugin / .codex-plugin），skill 目录 .zcode/skills 优先、.agents/skills 补充；支持从 16 个外部 Agent 目录导入技能。见 skills-system。
CUA 是 fail-closed 占位：packages/zcode-cua 在本检出中是接口形状保留、运行时全部 unavailable 的桩；computer-use 插件默认关闭且受 feature flag 门控。见 office-computer-use。
文档工程极重：docs/ 全量约 1866 篇 Markdown，含 docs/architecture/、docs/adr/、docs/plugins/、docs/specs/、docs/v4-refactor/ 等设计资产。

项目声明与风险

NOTICE.md 明确：AI 输出与执行的错误/权限/自动化风险；当前共享 Agent 执行适配器不提供默认 OS 沙箱；共享配置默认 build 权限模式，独立 CLI 的 --prompt 未指定 --mode 时采用 yolo；工作区指令、技能、Hook、插件、MCP 均可引入命令执行；CUA 本仓为不可用占位。判断运行位置不能只看当前设备（Web/远端工作区可能执行在服务端/SSH/WSL/容器）。

Wiki AI

目录