Repository Wiki
zai-org/ZCode

项目概览与运行形态

ZCode 是一个以 AI 编程为核心的多端工作台：同一仓库同时承载桌面应用、浏览器 Web 界面、后端服务，以及终端 Agent/CLI 运行时。本文从仓库根目录的启动脚本和使用说明出发，说明这些运行形态如何组合、开发者如何选择入口，以及环境变量和构建脚本如何影响运行行为。

Purpose and Scope

本文覆盖 ZCode 的整体运行形态、主要开发入口、桌面/Web/CLI 三种运行模式、根目录 workspace 编排、关键环境变量和发行构建边界。重点是“如何启动以及各入口如何协作”，而不是某个具体业务服务或 UI 页面。

插件商店、插件生命周期等领域术语属于独立能力；仓库中的 CONTEXT.md 仅作为术语背景，本文不展开插件安装与运行时实现。具体 Agent 协议、Provider 行为和桌面内部模块也应分别阅读对应 workspace 的文档与源码。

Overview

仓库根目录是一个 pnpm workspace 项目，根 package.json 将开发、构建、类型检查和架构检查统一编排到各个 workspace 包。运行时可以概括为三类：

  • 桌面形态：通过 dev:desktop 或 dev:desktop:test 进入 Electron 开发流程；启动前会准备本地运行资源，并构建桌面 Agent。
  • Web 形态：通过 dev:web 并行启动 @zcode/server 与 @zcode/web。README 明确给出默认 Web 端口 5173、后端端口 3030，并将 /ws 与普通 /api 请求代理到本地后端。
  • 命令行形态：发行包统一使用 zcode 命令；无参数进入 TUI，首参数为 --web 时启动 Web，其他参数交给既有 Agent CLI。源码开发则直接使用 @zcode/cli 的 workspace 入口。

这种组织方式的设计意图是将共享的 Agent、服务和 UI 能力放在 workspace 中复用，同时给桌面开发、浏览器开发和发行版验证提供不同的薄入口。根脚本负责组合顺序，具体行为仍由各 package 的脚本实现。

Architecture

Loading diagram...

Source: package.json；README.md

图中的关系直接来自根脚本和 README：dev:web 使用 concurrently 并行执行 server 与 web；桌面命令通过 scripts/dev-desktop-env.mjs 选择环境；CLI 目录位于 apps/zcode-cli/，并与仓库一起发布。这里没有把未在已读取材料中确认的内部类或 HTTP handler 绘入图中。

运行形态与入口

桌面开发

根脚本把 dev:desktop 定义为生产配置桌面开发的别名，而测试配置使用独立入口。README 说明，桌面启动脚本会准备本地运行资源、构建桌面 Agent，然后启动 Electron 和源码监听；因此桌面开发不是单纯启动一个前端 dev server，而是包含运行时资源准备的组合流程。

bash
1pnpm dev:desktop 2 3# 使用测试环境 4pnpm dev:desktop:test

Source: README.md

独立数据目录通过 ZCODE_DATA_BASE_DIR 注入。这样可以把开发数据与默认用户数据隔离，适合测试不同环境或并行运行多个开发实例。

Web 开发

dev:web 使用 concurrently -k 启动两个进程：后端 workspace 的 dev 脚本和 Web workspace 的 dev 脚本。-k 表示其中一个进程结束时终止并行任务，避免前后端只剩一个进程继续运行而造成误判。

bash
1pnpm dev:web 2 3# 指定后端工作区（macOS / Linux） 4ZCODE_SERVER_WORKSPACE=/path/to/project pnpm dev:web

Source: README.md

README 给出的本地拓扑是：浏览器访问 http://localhost:5173，一般 API 与 WebSocket 通过代理到 http://localhost:3030；OAuth token 路由则单独代理到当前配置的产品服务。这里的代理划分意味着 Web 开发可以保持浏览器端同源访问，同时把本地开发请求交给本地 server。

CLI 与统一发行命令

发行包的统一命令根据参数选择 TUI、Web 或 Agent CLI。源码开发时，@zcode/cli 的入口更直接，不经过发行包的 --web 分流。

bash
1# 默认进入终端交互界面 2zcode 3 4# 启动 Web 界面 5zcode --web 6 7# 指定项目和端口，不自动打开浏览器 8zcode --web --workspace /path/to/project --port 3030 --no-open

Source: README.md

统一发行命令的价值在于把 TUI、Web 和 Agent 放入同一个本地发行物；但源码开发仍保留 workspace 级入口，以便只重建发生变化的 CLI 及其依赖。

Core Flow

下面的流程展示一次典型的 Web 开发启动路径：根脚本并行拉起两个 workspace，浏览器请求到达 Web dev server 后，/ws 与 /api 再被代理到本地后端。

Loading diagram...

Source: package.json；README.md

桌面流程则不同：先准备资源并构建桌面 Agent，再启动 Electron；CLI 发行流程也不等价于 Web 开发流程，因为发行构建会依次构建 CLI/TUI、后端和 Web，并收集运行时依赖后组装发行包。

配置与数据目录

根 README 列出的运行时变量如下。它们的共同特点是通过启动命令注入，不由根脚本硬编码；因此同一套入口可以在不同工作区、数据目录和服务配置下复用。

配置项用途证据与边界
ZCODE_DATA_BASE_DIR应用数据基目录，数据写入其下的 .zcode/README 明确用于桌面开发数据隔离
ZCODE_SERVER_WORKSPACEWeb 后端的工作区路径README 示例为 macOS/Linux 环境变量
ZCODE_BUILTIN_PROVIDER_CONFIG_FILE本地 Provider 配置文件路径；未设置时使用内置配置根 README 只确认配置语义，Provider 内部解析不在本文范围
ZCODE_DIST_BASE_URL命令行安装脚本使用的下载根地址build:zcode 打包时也要求提供或通过 --base-url 传入
ZCODE_SERVER_AUTH_TOKEN直接启动通用 Web 服务时的 API/WebSocket 认证令牌通过程序接口创建服务时对应选项名为 authToken

例如，桌面测试环境可以使用独立数据目录：

bash
ZCODE_DATA_BASE_DIR="$HOME/.zcode-dev-home" pnpm dev:desktop:test

Source: README.md

Web 发行模式还涉及认证与监听地址：README 说明 CLI Web 模式默认监听 127.0.0.1、默认不启用访问令牌；使用非本机监听地址时默认生成令牌，也可用 --token 或 --no-token 覆盖。直接启动通用 Web 服务时，则使用 ZCODE_SERVER_AUTH_TOKEN。

构建、检查与发行

根脚本把构建和质量门禁分为几个层次：

  1. pnpm build 递归执行各 workspace 的构建脚本。
  2. pnpm build:bootstrap 构建 packages/*，排除 desktop，再单独执行桌面无运行时资源构建。
  3. pnpm typecheck 对 RPC、Provider、shared、services、client、server、CLI、UI、Web 和 desktop host 配置执行 TypeScript 项目检查。
  4. pnpm verify:pre-push 串联 lint 与变更范围架构检查。
  5. pnpm architecture:check、architecture:report 和 architecture:baseline:update 提供架构约束检查与基线维护。
json
1"build": "pnpm -r build", 2"build:bootstrap": "pnpm -r --filter \"./packages/*\" --filter \"!@zcode/desktop\" build && pnpm --filter @zcode/desktop build:no-runtime-assets", 3"typecheck": "tsc -b packages/rpc packages/provider packages/provider-node packages/shared packages/services packages/client packages/server packages/zcode-server-cli packages/ui packages/web packages/desktop/tsconfig.host.json", 4"verify:pre-push": "pnpm run lint && pnpm run architecture:check -- --changed"

Source: package.json

桌面 bundle 使用 bundle:desktop，支持 --os 与 --arch；README 记录的默认目标是 macOS arm64，默认输出目录为 packages/desktop/dist/。命令行发行构建则使用 build:zcode，输出目录为 dist/zcode/，并可用 --skip-build 只重新组包。

bash
1pnpm bundle:desktop 2 3# 指定目标平台与 CPU 架构 4pnpm bundle:desktop -- --os win --arch x64 5 6pnpm build:zcode --base-url https://downloads.example.com/zcode/ 7pnpm build:zcode --skip-build

Source: README.md；README.md

失败模式、边界与运维注意事项

端口、监听地址与认证

Web 开发依赖默认的 5173/3030 拓扑；如果后端端口、代理或工作区配置被改变，应以实际启动输出和当前 workspace 配置为准。CLI Web 模式的 --port、--host、--token 和 --no-token 会影响可访问性与安全边界：本机监听适合开发，局域网监听时应保留令牌保护，除非有明确理由关闭。

数据隔离

ZCODE_DATA_BASE_DIR 只改变应用数据基目录，并不等价于改变项目工作区。前者用于隔离 .zcode/ 数据，后者通过 ZCODE_SERVER_WORKSPACE 或 CLI --workspace 指定服务/会话处理的项目路径。把两者混淆可能导致“代码项目已切换但本地应用状态仍共享”的开发体验。

远程工作区

README 说明 SSH/WSL 开发需要先执行 bootstrap:with-remote 准备远程资源；开发态资源来自本地 packages/desktop/mock-cdn 和本地构建产物，再经 SFTP 上传到远程，不访问 CDN。该流程属于桌面远程能力的运维前置条件，不能用普通 bootstrap 的本地默认行为替代。

版本前置条件

README 要求 Git、Node.js 24.14.0 和 pnpm 10.33.2，版本以 mise.toml 为准；根 package.json 同时声明 Node >=24.0.0 与 pnpm 10.33.2。依赖版本不满足时，优先检查工具链而不是修改业务源码。

扩展点与边界

根级扩展点主要是脚本编排：新增 workspace 能力时，应在对应 package 提供自己的 dev/build 脚本，再由根 package.json 通过 pnpm filter 或递归命令接入。需要改变桌面环境选择时，入口集中在 dev:desktop:test、dev:desktop:prod 及其 scripts/dev-desktop-env.mjs 实现；需要改变 Web 联调拓扑时，应同时检查 @zcode/web 的代理配置与 @zcode/server 的监听配置，而不是只修改根命令。

现有根脚本还为依赖图、依赖引用、架构报告、lint、格式化和 release 提供独立命令。它们构成工程化扩展面，但具体检查规则、服务 API 和插件机制不在当前“项目概览与运行形态”页面中展开。

Usage Examples

源码 CLI 开发

bash
1pnpm --filter @zcode/cli dev --help 2pnpm --filter @zcode/cli dev 3 4# 构建 CLI 及其 workspace 依赖 5pnpm --filter @zcode/cli... build 6node apps/zcode-cli/packages/cli/dist/zcode.cjs --help

Source: README.md

基础初始化

bash
pnpm bootstrap

Source: README.md

bootstrap 适合第一次初始化：README 说明它会安装 workspace 依赖、准备桌面本地运行资源，再执行 build:bootstrap。如果需要远程资源，应改用 bootstrap:with-remote；如果只需要浏览器开发，则可直接安装依赖后使用 dev:web。

命令参考

根目录可确认的公共入口如下；这些是脚本签名而非 TypeScript API，因此参数语义以 README 的命令示例和 package script 定义为准。

命令作用适用场景
pnpm bootstrap安装 workspace 依赖、准备桌面本地资源并执行 bootstrap 构建首次初始化
pnpm dev:desktop使用生产配置启动桌面开发流程Electron 桌面开发
pnpm dev:desktop:test使用测试环境启动桌面开发流程测试配置或隔离数据
pnpm dev:web并行启动 Web 与 server dev 进程浏览器端开发
pnpm build递归执行 workspace 构建全仓库构建
pnpm typecheck对指定项目引用执行 TypeScript 检查类型质量门禁
pnpm bundle:desktop打包桌面发行物本地桌面发行验证
pnpm build:zcode组装 CLI/Web/Agent 命令行发行包命令行发行构建

根脚本中没有为运行时服务声明 HTTP endpoint 级别的 API 签名；本文因此不对 server 内部路由、返回结构或异常类型作推断。要记录这些细节，需要继续阅读 packages/server 和相关共享协议源码。

性能与操作建议

  • Web 开发采用并行进程，减少手动分别启动前后端的成本；concurrently -k 也避免一端退出后另一端孤立运行。
  • CLI 和桌面构建均支持复用已有产物或准备本地资源，build:zcode --skip-build 适合只验证重新组包的场景。
  • 远程开发先准备 mock-CDN/远程资源，再启动桌面应用，避免开发过程中依赖外部 CDN。
  • pnpm typecheck 和架构检查覆盖多个 workspace，适合在提交前捕获跨包接口和层次违规；根脚本明确把它们纳入 verify:pre-push。
  • 本页没有发现连接池、缓存、重试、并发锁或持久化事务实现；这些实现细节不应从运行入口文档推导。

测试与验证边界

从已读取的根配置和 README 可以确认的验证方式包括：dev:desktop:test 测试环境启动、typecheck 类型检查、lint/格式化，以及 architecture:check -- --changed 的变更架构检查。具体单元测试数量、覆盖率和各服务的集成测试未在本页已读取材料中出现，因此实现细节不足以作进一步结论。

Sources

(3 files)
CONTEXT.mdpackage.jsonREADME.md