Wiki AI

ZCode Monorepo 结构与包清单

6分钟阅读

双 workspace 拓扑

ZCode 是一个大型 pnpm monorepo，内有两个嵌套 workspace：

# 根 pnpm-workspace.yaml
packages:
  - apps/dev-docs
  - packages/*              # 19 个包
  - apps/zcode-cli          # 嵌套 CLI workspace 宿主
  - apps/zcode-cli/packages/*
  - apps/zcode-cli/tools/*
  • 根 workspace：仓库根，负责 Desktop / Web / Server / 共享 UI。
  • CLI 子 workspace：apps/zcode-cli 自带 pnpm-workspace.yaml（packages/* + tools/*）、独立 pnpm-lock.yaml 与 turbo.json。根通过通配把它纳入根图，但 CLI 内部有自己的依赖解析与 Turbo 图。

版本锚点：Node >=24.0.0（精确 24.14.0，见 mise.toml）、pnpm 10.33.2、TypeScript 根 ^6.0.2（CLI 子库 ^5.9.0）。.npmrc 使用 node-linker=hoisted（SEA 打包脚本依赖向上逐级查找 node_modules/.bin）。

allowBuilds 显式放行 12 个需编译的原生包：cpu-features、edgedriver、electron、electron-winstaller、esbuild、geckodriver、koffi、msw、node-pty、protobufjs、ssh2、unsafe-pointer。

根 packages/（19 个）

目录npm name作用
shared@zcode/shared跨进程共享协议/类型：ZCode Protocol、V4 wire、平台契约、gen-ui、MCP Apps
rpc@zcode/rpcVS Code 风格 IPC 框架：序列化、传输协议、Channel RPC、连接管理、远程连接
provider@zcode/providerProvider/Model 抽象与 Registry：配置模型、解析、选择校验、Settings/Selection facade
provider-node@zcode/provider-nodeProvider 的 Node 实现：内置/个人配置持久化、下载、materialize、运行时装配
model-option-map@zcode/model-option-map模型选项 DSL：受限 CEL 编译/求值 + JSON merge-patch（reasoningLevel/maxOutputTokens）
services@zcode/services业务服务与持久化集合（session/storage/gen-ui/plugin-ui-bridge/zcode-agent 等）+ Node 实现
client@zcode/clientAgent/远端客户端 SDK：WebSocket/MessagePort 连接、RemoteServiceAccess 服务代理
server@zcode/serverHTTP/WebSocket 服务端：本地服务托管、静态资源、SSH/WSL/Docker/Server 远程连接与部署
zcode-server-cli@zcode/server-cli（bin zcode）独立 Server CLI/进程管理：serve/status/stop/restart/update/uninstall + Supervisor 守护
ui@zcode/ui平台无关 React 组件、hooks、Zustand store、i18n、V4 会话投影（体量最大）
web@zcode/webWeb 客户端：手机远控 SPA、OAuth 登录、分享落地页、Vite 远端页
web-share@zcode/web-share独立会话分享入口（不经完整 Web bootstrap），复用 web/src/share 与 share-ui
share-ui@zcode/share-ui会话分享只读 UI 外壳，复用 @zcode/ui 的 ConversationShareReadonlyTimeline
desktop@zcode/desktopElectron 桌面应用：main/host/preload/renderer/scheduler + 插件沙箱 + 打包
zcode-cua@zcode/zcode-cua v0.6.3Computer Use fail-closed 占位包（本 build 不提供 CUA）
stream-animate@zcode/stream-animate流式输出帧率分析工具（60/120 FPS 每帧字符数预测）
formal-proof@zcode/formal-proof产品行为状态空间枚举器（compact/fork/goal/queue 组合），D3 渲染
e2e-report@zcode/e2e-reportE2E 结果采集（node side）+ Chart.js 可视化 viewer
android（无 package.json）Android 远控壳：Compose + WebView 打开 zcode.z.ai/remote，扫码/保活 Service

apps/zcode-cli/packages/（30 个）

CLI 子 workspace 是 Agent 的真正实现，按功能分四大类。

核心链路

包作用
shared-types仅 CLI 边界类型（RunContext、GlobalOptions、输出格式）
contracts跨边界端口、事件、错误、tool schema、model 类型
coreagent、turn、session、tool、permission、memory、workflow 业务运行时
adapters全部 Node/I/O/provider/MCP/storage/config 适配器
bootstrapcomposition root：创建 App、Runtime、provider registry、session store、MCP、plugin、V4 server
clizcode 二进制入口、命令解析、headless/protocol/TUI 分派
tuiOpenTUI + React 终端界面

基础设施

包作用
i18nen-US / zh-CN CLI/TUI 文案
telemetryOTLP trace/metrics 与 Agent telemetry（OTel）
debug本地日志/SQLite/trace 浏览 + MITM 网络抓包开发工具
dynamic-workflow纯 TS 工作流 facade、编译、静态分析与纯执行引擎
dynamic-workflow-runtimechild-process + vm 沙箱 harness
bundled-skills不可卸载的内置技能包（当前仅 dynamic-workflows）
node-repl-hostBrowser Use / Computer Use 共用的 node_repl MCP 宿主
swift-bridge当前仅为 placeholder（src/index.ts）

扩展插件（*-plugin）

包作用
visualize-pluginGen UI / 交互视图（唯一提供 HTML 交互页的默认启用 UI Plugin）
browser-use-plugin浏览器自动化 skills + client runtime
zcode-cua-pluginComputer Use SDK/skill（默认关闭，受 feature flag 门控）
documents-pluginDOCX 文档技能
pdf-pluginPDF/LaTeX/HTML 排版技能
presentations-pluginPPTX 演示文稿技能
spreadsheets-pluginXLSX 表格技能
image-search-plugin官方 HTTP 搜图 MCP
android-emulator-pluginAndroid 开发/模拟器自动化（默认关闭）
ios-simulator-pluginiOS 开发/模拟器自动化（默认关闭）
restore-legacy-sessions-plugin旧 ACP 会话迁移（已退出市场展示）
superpowers-plugin开发方法论 skill/hook 集合（已从内置 SEA 资源下线，改按需安装）

创建器 / 指南

包作用
plugin-creator-plugin插件创作与本地市场脚手架
skill-creator-pluginSkill 创建/编辑/迭代
zcode-guide-pluginZCode 配置与自诊断技能

包级依赖图

# 根 packages
shared            -> model-option-map
provider          -> model-option-map, shared
provider-node     -> provider, model-option-map, shared
rpc               -> (leaf)
services          -> rpc, shared, provider, provider-node, zcode-cua
client            -> rpc, services, shared
server            -> client, rpc, services, shared
ui                -> rpc, services, shared, provider
web               -> client, shared, ui
web-share         -> shared, share-ui
share-ui          -> shared
zcode-server-cli  -> rpc, services, shared
desktop           -> client, rpc, server, services, shared, ui, provider, provider-node, zcode-cua, e2e-report
 
# apps/zcode-cli（独立分层）
shared-types      -> (leaf)
contracts         -> shared
core              -> contracts, shared, shared-types, dynamic-workflow, zcode-cua
adapters          -> contracts, shared, provider, model-option-map, dynamic-workflow, zcode-cua
bootstrap         -> core, adapters, contracts, shared, provider, provider-node,
                     dynamic-workflow, dynamic-workflow-runtime, formal-proof, i18n, telemetry
cli               -> core, bootstrap, adapters, contracts, shared-types, provider-node,
                     dynamic-workflow-runtime, i18n, tui
tui               -> contracts, i18n, shared

依赖严格分层：shared-types → contracts → core/adapters → bootstrap → cli。zcode-cua 被 services/core/adapters/node-repl-host 广泛消费（但当前是占位实现，见 office-computer-use）。

其他顶层目录

目录职责
apps/dev-docs交互式能力图 / 协议文档（pnpm dev:docs）
scripts/80+ 构建维护脚本（见 engineering）
config/内置配置
third-party/第三方声明材料（见 distribution）
docs/全量约 1866 篇 Markdown 设计资产
specs/zcode-unified-distribution.md（见 distribution）
harness/remote/远程 harness Dockerfile
.agents/skills/仓库自身开发用技能（同时被运行时发现）

相关页面

关系图谱

反向链接