zai-org / ZCode

# ZCode
 飞书社群 ·
 Discord 
 简体中文 | English 
ZCode 是 AI 编程工作台，提供桌面应用、浏览器界面和终端 Agent。本仓库包含客户端、后端服务、共享 UI，以及 Agent CLI 与运行时源码。
## 更新
- **2026-10-19**：更新至 ZCode v3.16.2 版本。
- **2026-10-16**：更新至 ZCode v3.16.1 版本。
- 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 为准。以下开发和打包命令均在仓库根目录执行。
 [code] 
`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` 跳过远程资源准备，适合本地桌面开发。使用远程工作区或验证远程发行资源时，再运行对应准备命令。
## 开发与运行
### 桌面版
 [code] 
`pnpm dev:desktop` 默认等同于 `pnpm dev:desktop:prod`，使用生产服务配置。启动脚本会准备本地运行资源、构建桌面 Agent，再启动 Electron 和源码监听。
需要独立开发数据目录时，可设置 `ZCODE_DATA_BASE_DIR`。例如在 macOS / Linux 中：
 [code] 
### 远程功能（SSH/WSL）
先执行 `pnpm bootstrap:with-remote` 准备远程资源（mock-cdn），再 `pnpm dev:desktop`；连接远程项目时资源选择「本地下载后上传」。开发态资源取自本地 `packages/desktop/mock-cdn` 和本地构建产物，经 SFTP 上传到远程，不访问 CDN。
### Web 开发
修改 Web 或后端源码时，使用开发模式：
 [code] 
该命令同时启动 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。
 [code] 
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 时，运行源码入口：
 [code] 
这个入口直接运行 Agent CLI，不经过发行包的 `--web` 分流。开发 Web 用 `pnpm dev:web`；验证统一的 `zcode` 命令，用下方解压后的 `bin/zcode.mjs`。
### UI Plugin 开发
参见 UI Plugin：能力、API 与调试，从 Excalidraw 的画布协作示例开始，了解插件安装更新、页面 API 和宿主联调入口。
**向 `zcode-plugins` 提交插件 PR 时，必须在 PR 模板中声明是否为 UI Plugin，并填写插件名称。** 判断标准见提交 PR 时声明插件类型。
## 配置
根目录 .env.example 提供服务地址与构建配置示例，可按需复制到 `.env`，本地覆盖放入 `.env.local`。Desktop 的开发环境通过 `dev:desktop:test` / `dev:desktop:prod` 选择。
| 配置 | 用途 |
| ------------------------------------ | ------------------------------------------------ |
| `ZCODE_DATA_BASE_DIR` | 应用数据基目录，数据写入其下的 `.zcode/` |
| `ZCODE_SERVER_WORKSPACE` | Web 后端的工作区路径 |
| `ZCODE_BUILTIN_PROVIDER_CONFIG_FILE` | 本地 Provider 配置文件路径；未设置时使用内置配置 |
| `ZCODE_DIS