跳到主要内容
AI教程

ZCode 开发教程：搭建桌面、Web 与终端 AI 编程工作台

本教程介绍如何搭建 ZCode 开发环境，运行 Electron 桌面端、Web 工作台和 Agent CLI，并进一步配置远程资源、访问认证及发行包。

AI我搜编辑部阅读约 14 分钟
ZCode 开发教程：搭建桌面、Web 与终端 AI 编程工作台

认识 ZCode

ZCode 项目标志

ZCode 是一个 AI 编程工作台，同时提供 Electron 桌面应用、浏览器界面和终端 Agent。仓库采用 workspace 形式组织，集中维护客户端、后端服务、共享 UI、Agent CLI、TUI 和运行时源码。

项目提供三个主要开发入口：

  • Desktop：Electron 桌面应用，使用 pnpm dev:desktop 启动。
  • Web：同时启动浏览器工作台和本地后端，使用 pnpm dev:web。
  • Agent CLI：直接开发终端 Agent 或 TUI，使用 pnpm --filter @zcode/cli dev。

此外，ZCode 还可以构建为统一命令行发行包。安装后执行 zcode 进入 TUI，执行 zcode --web 则启动本地 Web 工作台。

主要特性

  • 提供桌面、浏览器和终端三种使用方式。
  • Web 前端、HTTP/WebSocket 后端与 Agent 可在本机组成完整工作链路。
  • Desktop 和 Web 共用 Agent CLI 运行时。
  • 支持 SSH、WSL 等远程工作区开发。
  • 共享 React 组件、hooks、Zustand 状态、协议类型、RPC 框架和 Agent 客户端 SDK。
  • 可分别构建桌面安装包和统一的 ZCode 命令行发行包。
  • Web 对外监听时支持自动生成访问令牌，也可显式配置认证令牌。

准备开发环境

安装必要工具

开始之前，请准备以下工具。具体版本以仓库根目录的 mise.toml 为准：

  • Git
  • Node.js 24.14.0
  • pnpm 10.33.2

克隆仓库并进入根目录后，执行推荐的初始化命令：

pnpm bootstrap

pnpm bootstrap 会安装 workspace 依赖、准备桌面端本地运行资源，并执行 build:bootstrap。Agent CLI 与运行时已经位于 apps/zcode-cli/，无需额外初始化 Git submodule。

默认的 bootstrap 会跳过远程资源准备，因此更适合本地桌面开发。只有需要 SSH、WSL 或远程发行资源时，才需要执行远程资源相关命令。

按需选择初始化命令

  • pnpm install：仅安装依赖。
  • pnpm prepare:desktop-runtime：准备桌面运行资源，默认包含远程资源准备。
  • pnpm prepare:remote-assets：单独准备远程运行资源。
  • pnpm bootstrap:with-remote：初始化依赖、本地与远程资源，并串行构建相关包，但跳过桌面应用 bundle。
  • pnpm build：递归执行各 workspace 包的构建脚本，包括包内资源准备步骤。

运行桌面版

完成初始化后，在仓库根目录启动 Electron 桌面应用：

pnpm dev:desktop

pnpm dev:desktop 默认等同于 pnpm dev:desktop:prod，使用生产服务配置。启动脚本会准备本地运行资源、构建桌面 Agent，然后启动 Electron 和源码监听。

如果希望使用测试环境，可运行：

pnpm dev:desktop:test

隔离开发数据

为了避免开发数据与日常使用的数据混在一起，可以通过 ZCODE_DATA_BASE_DIR 指定独立的数据基目录。应用数据会写入该目录下的 .zcode/：

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

该写法适用于 macOS 和 Linux。

运行 Web 工作台

修改 Web 前端或后端源码时，推荐使用联合开发模式：

pnpm dev:web

该命令会同时启动：

  • Web 开发服务器，默认地址为 http://localhost:5173。
  • 本地后端，默认地址为 http://localhost:3030。

浏览器应访问前端地址。开发服务器会将 /ws 和一般的 /api 请求代理到本地后端；/api/v1/oauth/token 会单独代理到当前配置的产品服务。

指定后端工作区

在 macOS 或 Linux 中，可以通过环境变量指定 Web 后端使用的项目目录：

ZCODE_SERVER_WORKSPACE=/path/to/project pnpm dev:web

如果修改了 Agent 源码，需要重新构建 CLI 及其 workspace 依赖，然后重启服务：

pnpm --filter @zcode/cli... build

开发 Agent CLI 与 TUI

如果主要开发终端界面或 Agent，可直接运行源码入口：

pnpm --filter @zcode/cli dev --help
pnpm --filter @zcode/cli dev

构建 CLI 及其依赖后，也可以直接运行生成的 CommonJS 文件：

pnpm --filter @zcode/cli... build
node apps/zcode-cli/packages/cli/dist/zcode.cjs --help

这个源码入口直接运行 Agent CLI，不会执行统一发行命令中的 --web 分流。开发 Web 应使用 pnpm dev:web；测试统一的 zcode 命令则应构建并解压命令行发行包。

使用 ZCode 命令行版

命令行发行包把 TUI、Web、后端和 Agent 组合在一起，并统一通过 zcode 启动。它不依赖 Electron，但运行时仍然需要符合 mise.toml 要求的 Node.js。

基本命令

# 进入终端交互界面
zcode

# 启动 Web 工作台
zcode --web

# 指定项目和端口，并禁止自动打开浏览器
zcode --web --workspace /path/to/project --port 3030 --no-open

# 查看帮助
zcode --help
zcode --web --help

Web 模式默认使用当前目录作为工作目录，监听 127.0.0.1，自动选择空闲端口并打开浏览器。默认不会启用访问令牌。完成使用后，可在终端按 Ctrl+C 停止服务。

在局域网中访问

如需让其他设备访问，可将监听地址改为 0.0.0.0：

zcode --web --host 0.0.0.0

监听非本机地址时，ZCode 默认会生成访问令牌。应使用终端输出的带令牌链接访问服务。也可以通过 --token 指定令牌，或使用 --no-token 关闭令牌认证。

直接启动通用 Web 服务的 HTTP 入口时，可通过 ZCODE_SERVER_AUTH_TOKEN 配置 API 和 WebSocket 认证；通过程序接口创建服务时，则使用 authToken 选项。

配置环境变量

仓库根目录的 .env.example 提供服务地址与构建配置示例。可以按需复制为 .env，并将仅供本地使用的覆盖项放入 .env.local。

  • ZCODE_DATA_BASE_DIR：应用数据基目录，数据写入其下的 .zcode/。
  • ZCODE_SERVER_WORKSPACE：指定 Web 后端工作区路径。
  • ZCODE_BUILTIN_PROVIDER_CONFIG_FILE：指定本地 Provider 配置文件；未设置时使用内置配置。
  • ZCODE_DIST_BASE_URL：命令行安装脚本使用的下载根地址。

这些运行时变量也可以直接放在启动命令的环境中。Desktop 的开发服务配置则通过 dev:desktop:test 和 dev:desktop:prod 选择。

开发 SSH 与 WSL 远程功能

开发远程工作区功能前，先准备远程资源：

pnpm bootstrap:with-remote
pnpm dev:desktop

连接远程项目时，将资源选择为“本地下载后上传”。开发环境会从本地 packages/desktop/mock-cdn 和本地构建产物获取资源，再通过 SFTP 上传到远程主机，不会访问 CDN。

构建桌面安装包

运行以下命令构建桌面版：

pnpm bundle:desktop

默认目标为 macOS arm64，输出目录为 packages/desktop/dist/。也可以指定操作系统和 CPU 架构：

pnpm bundle:desktop -- --os win --arch x64
pnpm bundle:desktop -- --help

--os 支持 mac、win 和 linux，--arch 支持 x64 和 arm64。实际打包与签名仍需要目标平台对应的工具和配置。

在 macOS 上可打开生成的 DMG，并将 ZCode 拖入“应用程序”。如果本地未签名构建首次启动时被系统拦截，可执行：

sudo xattr -rd com.apple.quarantine /Applications/ZCode.app

构建命令行发行包

命令行发行包的构建入口为 pnpm build:zcode。构建前必须设置下载根地址 ZCODE_DIST_BASE_URL，也可以通过 --base-url 直接传入：

pnpm build:zcode --base-url https://downloads.example.com/zcode/

# 已配置 ZCODE_DIST_BASE_URL 时
pnpm build:zcode

# 复用已有构建产物，仅重新组包
pnpm build:zcode --skip-build

# 查看可选参数
pnpm build:zcode --help

其中的下载地址只是占位示例，正式发布时需要替换为实际托管地址。构建脚本会依次处理 CLI/TUI、后端和 Web，收集原生库、worker 与运行时依赖，再组装发行包。

默认版本来自根目录的 package.json，输出目录为 dist/zcode/，其中包括：

  • releases/<version>/zcode-<version>.tar.gz：运行包。
  • releases/<version>/sha256.txt：校验摘要。
  • latest.json：版本索引。
  • install.sh：安装脚本。

安装脚本默认将运行时安装到 ~/.zcode/runtime，并在 ~/.local/bin 创建 zcode 命令。可分别通过 ZCODE_DIST_HOME 和 ZCODE_DIST_BIN_DIR 修改这两个位置。

本地验证发行包

无需上传文件或执行安装脚本，也可以直接解压并运行构建结果：

zcode_version=$(node -p "require('./dist/zcode/latest.json').version")
mkdir -p dist/zcode/debug
tar -xzf "dist/zcode/releases/$zcode_version/zcode-$zcode_version.tar.gz" \
  -C dist/zcode/debug

# 启动 TUI
node dist/zcode/debug/zcode/bin/zcode.mjs

# 启动 Web
node dist/zcode/debug/zcode/bin/zcode.mjs --web \
  --workspace "$PWD" --port 3030 --no-open

随后访问 http://127.0.0.1:3030，即可验证同一后端托管 Web 页面和 Agent 的完整链路。端口必须处于空闲状态；如果 pnpm dev:web 正在使用该端口，请通过 --port 改用其他端口。

进阶开发建议

  1. 优先使用对应入口：桌面功能使用 dev:desktop，前后端联调使用 dev:web，Agent 和 TUI 使用 CLI workspace 的 dev 命令。
  2. 修改 Agent 后重新构建：Web 服务不会自动获得所有 Agent 构建结果，修改后应执行 pnpm --filter @zcode/cli... build 并重启服务。
  3. 隔离测试数据：通过 ZCODE_DATA_BASE_DIR 为不同开发场景建立独立数据目录。
  4. 对外监听时保留认证：使用 --host 0.0.0.0 后，应优先保留自动生成的令牌或显式设置 --token。
  5. 检查命令来源：pnpm build:zcode 只生成发行包，不会替换系统 PATH 中已有的 zcode。macOS 和 Linux 可运行 command -v zcode，Windows 可运行 where.exe zcode。
  6. 区分开发与发行验证：pnpm dev:web 适合源码迭代；解压后的 bin/zcode.mjs 更适合验证最终统一命令及完整发行链路。

仓库结构速览

  • packages/desktop：Electron Main、Host、Renderer 与桌面打包。
  • packages/web：Web 客户端。
  • packages/server：HTTP、WebSocket 服务与远程连接。
  • packages/zcode-server-cli：独立 Server 启动与进程管理。
  • packages/ui：共享 React 组件、hooks 与 Zustand 状态。
  • packages/services：业务服务与持久化。
  • packages/shared、packages/rpc、packages/client：共享协议和类型、RPC 框架及 Agent 客户端 SDK。
  • packages/provider、packages/provider-node：Provider 公共能力与 Node.js 实现。
  • apps/zcode-cli：Agent CLI、TUI、运行时与工具。
  • scripts、config、third-party：构建维护脚本、内置配置与第三方声明材料。

总结

ZCode 将桌面端、Web、后端和 Agent CLI 集成在同一个 workspace 中。首次开发可从 pnpm bootstrap 开始，再根据目标选择 pnpm dev:desktop、pnpm dev:web 或 CLI 源码入口。需要测试远程工作区或正式发行时，再准备远程资源并构建对应的桌面或命令行安装包。