ZCode: Z.ai's coding agent harness. Powerful, intelligent, extensible Z.ai released ZCode, an AI coding agent harness distributed as an open repository containing an Electron desktop app, a browser workbench, and a terminal Agent CLI that runs via the `zcode` command. The project requires Git, Node.js 24.14.0, and pnpm 10.33.2, with setup handled by `pnpm bootstrap` and desktop builds defaulting to macOS arm64 output in `packages/desktop/dist/`. The CLI launches a TUI with no arguments or a local web interface on 127.0.0.1 with `zcode --web`, generating an access token by default when bound to a non-local address. 简体中文 | English https://github.com/zai-org/ZCode/blob/main/README.en.md ZCode 是 AI 编程工作台，提供桌面应用、浏览器界面和终端 Agent。本仓库包含客户端、后端服务、共享 UI，以及 Agent CLI 与运行时源码。 | 入口 | 用途 | 开发命令 | |---|---|---| | Desktop | Electron 桌面应用 | pnpm dev:desktop | | Web / ZCode 命令行版 | 终端与浏览器工作台；将 TUI、Web、后端和 Agent 组装为独立运行包 | pnpm dev:web | | Agent CLI | 在终端中使用 zcode ，也为 Desktop 和 Web 提供 Agent 运行时 | pnpm --filter @zcode/cli dev | 准备 Git、Node.js 24.14.0 和 pnpm 10.33.2 ，版本以 mise.toml https://github.com/zai-org/ZCode/blob/main/mise.toml 为准。以下开发和打包命令均在仓库根目录执行。 pnpm bootstrap pnpm bootstrap 安装 workspace 依赖、准备桌面本地运行资源，再执行 build:bootstrap 。 Agent CLI 与运行时源码位于 apps/zcode-cli/ https://github.com/zai-org/ZCode/blob/main/apps/zcode-cli ，作为普通目录随本仓库一起克隆，无需单独拉取或初始化 Git submodule。 根据需要选择其他初始化或构建入口： | 命令 | 用途 | |---|---| | pnpm install | 安装依赖 | | pnpm prepare:desktop-runtime | 准备桌面运行资源，默认包含远程资源准备 | | pnpm prepare:remote-assets | 单独准备远程运行资源 | | pnpm bootstrap:with-remote | 初始化依赖、本地与远程资源，并串行构建相关包；跳过桌面应用 bundle | | pnpm build | 递归执行各 workspace 包的构建脚本，包括包内的资源准备步骤 | 默认 bootstrap 跳过远程资源准备，适合本地桌面开发。使用远程工作区或验证远程发行资源时，再运行对应准备命令。 pnpm dev:desktop 使用测试环境 pnpm dev:desktop:test pnpm dev:desktop 默认等同于 pnpm dev:desktop:prod ，使用生产服务配置。启动脚本会准备本地运行资源、构建桌面 Agent，再启动 Electron 和源码监听。 需要独立开发数据目录时，可设置 ZCODE DATA BASE DIR 。例如在 macOS / Linux 中： ZCODE DATA BASE DIR="$HOME/.zcode-dev-home" pnpm dev:desktop:test 先执行 pnpm bootstrap:with-remote 准备远程资源（mock-cdn），再 pnpm dev:desktop ；连接远程项目时资源选择「本地下载后上传」。开发态资源取自本地 packages/desktop/mock-cdn 和本地构建产物，经 SFTP 上传到远程，不访问 CDN。 修改 Web 或后端源码时，使用开发模式： 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 命令行版”打包章节解压运行。 命令行发行包包含 TUI、Web 和 Agent，统一使用 zcode 启动：无参数进入 TUI；第一个参数为 --web 时启动 Web；其他参数交给现有 Agent CLI 处理。两种模式都在本机运行，无需 Electron。 默认进入终端交互界面 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 检查。 直接开发 TUI 或 Agent 时，运行源码入口： pnpm --filter @zcode/cli dev --help pnpm --filter @zcode/cli dev 构建 CLI 及其 workspace 依赖 pnpm --filter @zcode/cli... build node apps/zcode-cli/packages/cli/dist/zcode.cjs --help 这个入口直接运行 Agent CLI，不经过发行包的 --web 分流。开发 Web 用 pnpm dev:web ；验证统一的 zcode 命令，用下方解压后的 bin/zcode.mjs 。 根目录 .env.example https://github.com/zai-org/ZCode/blob/main/.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 DIST BASE URL | 命令行安装脚本使用的下载根地址 | 运行时变量可在启动命令的环境中显式设置。随客户端发布的默认配置见 config/README.md https://github.com/zai-org/ZCode/blob/main/config/README.md 。 第三方声明生成、发行校验流程及声明在发行物中的位置见 third-party/README.md https://github.com/zai-org/ZCode/blob/main/third-party/README.md 。 pnpm bundle:desktop 指定目标平台与 CPU 架构 pnpm bundle:desktop -- --os win --arch x64 pnpm bundle:desktop -- --help 默认目标为 macOS arm64，默认输出目录为 packages/desktop/dist/ 。 --os 支持 mac 、 win 、 linux ， --arch 支持 x64 、 arm64 ；实际打包与签名需要目标平台对应的工具和配置。 安装：双击打开产物 DMG，将 ZCode 拖入"应用程序"。本地构建未签名，首次打开若被 macOS 拦截，执行： sudo xattr -rd com.apple.quarantine /Applications/ZCode.app 构建入口为 pnpm build:zcode 。脚本会依次构建 CLI/TUI、后端和 Web，收集 TUI 的原生库、worker 与运行时依赖，再组装发行包；运行发行包仍需要 Node.js，版本以 mise.toml 为准。 打包前必须设置下载根地址 ZCODE DIST BASE URL （可放在 .env 、 .env.local 或环境变量中），也可以通过 --base-url 传入。以下地址是占位示例，发布时替换为实际托管地址： pnpm build:zcode --base-url https://downloads.example.com/zcode/ 已配置 ZCODE DIST BASE URL 时 pnpm build:zcode 仅重新组包，复用已有的 Agent、后端和 Web 构建产物 pnpm build:zcode --skip-build 查看版本、输出目录等可选参数 pnpm build:zcode --help 默认版本取根目录 package.json ，输出目录为 dist/zcode/ ： - releases/