README

ZCode


  


  飞书社群 ·
  Discord


  简体中文 | English


ZCode 是 AI 编程工作台，提供桌面应用、浏览器界面和终端 Agent。本仓库包含客户端、后端服务、共享 UI，以及 Agent CLI 与运行时源码。

 更新

- 2026-11-03：更新至 ZCode v3.17.2 版本。
- 2026-10-30：更新至 ZCode v3.17.1 版本。
- 2026-10-19：更新至 ZCode v3.16.2 版本。
- 2026-10-16：更新至 ZCode v3.16.1 版本。
- 2026-10-16：更新至 ZCode v3.15.4 版本。
- 2026-10-10：更新至 ZCode v3.15.1 版本。
- 2026-9-23：更新至 ZCode v3.14.3 版本。

 初始化

准备 Git、Node.js 24.14.0 和 pnpm 10.33.2，版本以 mise.toml 为准。以下开发和打包命令均在仓库根目录执行。

bash
pnpm bootstrap


pnpm bootstrap 安装 workspace 依赖、准备桌面本地运行资源，再执行 build:bootstrap。

Agent CLI 与运行时源码位于 apps/zcode-cli/，作为普通目录随本仓库一起克隆，无需单独拉取或初始化 Git submodule。

根据需要选择其他初始化或构建入口：

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

默认 bootstrap 跳过远程资源准备，适合本地桌面开发。使用远程工作区或验证远程发行资源时，再运行对应准备命令。

 开发与运行

 桌面版

bash
pnpm dev:desktop

 使用测试环境
pnpm dev:desktop:test


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

需要独立开发数据目录时，可设置 ZCODE_DATA_BASE_DIR。例如在 macOS / Linux 中：

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


 远程功能（SSH/WSL）

先执行 pnpm bootstrap:with-remote 准备远程资源（mock-cdn），再 pnpm dev:desktop；连接远程项目时资源选择「本地下载后上传」。开发态资源取自本地 packages/desktop/mock-cdn 和本地构建产物，经 SFTP 上传到远程，不访问 CDN。

 Web 开发

修改 Web 或后端源码时，使用开发模式：

bash
pnpm dev:web

 指定后端工作区（macOS / Linux）
ZCODE_SERVER_WORKSPACE=/path/to/project pnpm dev:web


该命令同时启动 Web 开发服务器（默认 http://localhost:5173）和后端（默认 http://localhost:3030）；浏览器访问前者。/ws 和一般 /api 请求代理到本地后端，/api/v1/oauth/token 单独代理到当前配置的产品服务。

Agent 源码修改后，执行 pnpm --filter @zcode/cli... build 并重启服务。需要验证完整发行包时，按下方“ZCode 命令行版”打包章节解压运行。

 ZCode 命令行版

命令行发行包包含 TUI、Web 和 Agent，统一使用 zcode 启动：无参数进入 TUI；第一个参数为 --web 时启动 Web；其他参数交给现有 Agent CLI 处理。两种模式都在本机运行，无需 Electron。

bash
 默认进入终端交互界面
zcode

 启动 Web 界面
zcode --web

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

 查看 CLI 或 Web 参数
zcode --help
zcode --web --help


Web 模式默认工作目录为当前目录，监听 127.0.0.1，默认不启用访问令牌，自动选择空闲端口并打开浏览器。访问终端输出的地址，按 Ctrl+C 停止服务。局域网访问可使用 --host 0.0.0.0；监听非本机地址时默认生成访问令牌，使用终端输出的带令牌链接。可通过 --token 指定令牌或 --no-token 关闭令牌认证。

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

构建方式见下方打包章节。pnpm build:zcode 只生成发行包，不会替换 PATH 中已有的 zcode。如果命令仍指向旧安装或其他源码目录，macOS / Linux 可用 command -v zcode 检查，Windows 可用 where.exe zcode 检查。

 CLI 源码开发

CLI 的模型配置、非交互调用、工具与扩展、批量评测和轨迹记录见 CLI 使用指南。

直接开发 TUI 或 Agent 时，运行源码入口：

bash
pnpm --filter @zco

Latest release

ZCode 3.17.2

macOS arm64 · macOS x64 · Windows arm64 · Windows x64

Build source: e6b675b40abb79e1d38d98d4e8750d0859cfedd9

Verify downloads with the attached SHA256SUMS.