{"slug": "zcode-z-ai-s-coding-agent-harness-powerful-intelligent-extensible", "title": "ZCode: Z.ai's coding agent harness. Powerful, intelligent, extensible", "summary": "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.", "body_md": "简体中文 | [English](https://github.com/zai-org/ZCode/blob/main/README.en.md)\n\nZCode 是 AI 编程工作台，提供桌面应用、浏览器界面和终端 Agent。本仓库包含客户端、后端服务、共享 UI，以及 Agent CLI 与运行时源码。\n\n| 入口 | 用途 | 开发命令 | \n|---|---|---|\n| Desktop | Electron 桌面应用 | `pnpm dev:desktop` | \n| Web / ZCode 命令行版 | 终端与浏览器工作台；将 TUI、Web、后端和 Agent 组装为独立运行包 | `pnpm dev:web` | \n| Agent CLI | 在终端中使用 `zcode` ，也为 Desktop 和 Web 提供 Agent 运行时 | `pnpm --filter @zcode/cli dev` | \n\n准备 Git、Node.js **24.14.0** 和 pnpm **10.33.2**，版本以 [mise.toml](https://github.com/zai-org/ZCode/blob/main/mise.toml) 为准。以下开发和打包命令均在仓库根目录执行。\n\n```\npnpm bootstrap\n```\n\n`pnpm bootstrap` 安装 workspace 依赖、准备桌面本地运行资源，再执行 `build:bootstrap`。\n\nAgent CLI 与运行时源码位于 [apps/zcode-cli/](https://github.com/zai-org/ZCode/blob/main/apps/zcode-cli)，作为普通目录随本仓库一起克隆，无需单独拉取或初始化 Git submodule。\n\n根据需要选择其他初始化或构建入口：\n\n| 命令 | 用途 | \n|---|---|\n| `pnpm install` | 安装依赖 | \n| `pnpm prepare:desktop-runtime` | 准备桌面运行资源，默认包含远程资源准备 | \n| `pnpm prepare:remote-assets` | 单独准备远程运行资源 | \n| `pnpm bootstrap:with-remote` | 初始化依赖、本地与远程资源，并串行构建相关包；跳过桌面应用 bundle | \n| `pnpm build` | 递归执行各 workspace 包的构建脚本，包括包内的资源准备步骤 | \n\n默认 `bootstrap` 跳过远程资源准备，适合本地桌面开发。使用远程工作区或验证远程发行资源时，再运行对应准备命令。\n\n```\npnpm dev:desktop\n\n# 使用测试环境\npnpm dev:desktop:test\n```\n\n`pnpm dev:desktop` 默认等同于 `pnpm dev:desktop:prod`，使用生产服务配置。启动脚本会准备本地运行资源、构建桌面 Agent，再启动 Electron 和源码监听。\n\n需要独立开发数据目录时，可设置 `ZCODE_DATA_BASE_DIR`。例如在 macOS / Linux 中：\n\n```\nZCODE_DATA_BASE_DIR=\"$HOME/.zcode-dev-home\" pnpm dev:desktop:test\n```\n\n先执行 `pnpm bootstrap:with-remote` 准备远程资源（mock-cdn），再 `pnpm dev:desktop`；连接远程项目时资源选择「本地下载后上传」。开发态资源取自本地 `packages/desktop/mock-cdn` 和本地构建产物，经 SFTP 上传到远程，不访问 CDN。\n\n修改 Web 或后端源码时，使用开发模式：\n\n```\npnpm dev:web\n\n# 指定后端工作区（macOS / Linux）\nZCODE_SERVER_WORKSPACE=/path/to/project pnpm dev:web\n```\n\n该命令同时启动 Web 开发服务器（默认 `http://localhost:5173`）和后端（默认 `http://localhost:3030`）；浏览器访问前者。`/ws` 和一般 `/api` 请求代理到本地后端，`/api/v1/oauth/token` 单独代理到当前配置的产品服务。\n\nAgent 源码修改后，执行 `pnpm --filter @zcode/cli... build` 并重启服务。需要验证完整发行包时，按下方“ZCode 命令行版”打包章节解压运行。\n\n命令行发行包包含 TUI、Web 和 Agent，统一使用 `zcode` 启动：无参数进入 TUI；第一个参数为 `--web` 时启动 Web；其他参数交给现有 Agent CLI 处理。两种模式都在本机运行，无需 Electron。\n\n```\n# 默认进入终端交互界面\nzcode\n\n# 启动 Web 界面\nzcode --web\n\n# 指定项目和端口，不自动打开浏览器\nzcode --web --workspace /path/to/project --port 3030 --no-open\n\n# 查看 CLI 或 Web 参数\nzcode --help\nzcode --web --help\n```\n\nWeb 模式默认工作目录为当前目录，监听 `127.0.0.1`，默认不启用访问令牌，自动选择空闲端口并打开浏览器。访问终端输出的地址，按 `Ctrl+C` 停止服务。局域网访问可使用 `--host 0.0.0.0`；监听非本机地址时默认生成访问令牌，使用终端输出的带令牌链接。可通过 `--token` 指定令牌或 `--no-token` 关闭令牌认证。\n\n直接启动通用 Web 服务的 HTTP 入口时，通过 `ZCODE_SERVER_AUTH_TOKEN` 配置 API／WebSocket 认证；通过程序接口创建服务时，使用 `authToken` 选项。\n\n构建方式见下方打包章节。`pnpm build:zcode` 只生成发行包，不会替换 `PATH` 中已有的 `zcode`。如果命令仍指向旧安装或其他源码目录，macOS / Linux 可用 `command -v zcode` 检查，Windows 可用 `where.exe zcode` 检查。\n\n直接开发 TUI 或 Agent 时，运行源码入口：\n\n```\npnpm --filter @zcode/cli dev --help\npnpm --filter @zcode/cli dev\n\n# 构建 CLI 及其 workspace 依赖\npnpm --filter @zcode/cli... build\nnode apps/zcode-cli/packages/cli/dist/zcode.cjs --help\n```\n\n这个入口直接运行 Agent CLI，不经过发行包的 `--web` 分流。开发 Web 用 `pnpm dev:web`；验证统一的 `zcode` 命令，用下方解压后的 `bin/zcode.mjs`。\n\n根目录 [.env.example](https://github.com/zai-org/ZCode/blob/main/.env.example) 提供服务地址与构建配置示例，可按需复制到 `.env`，本地覆盖放入 `.env.local`。Desktop 的开发环境通过 `dev:desktop:test` / `dev:desktop:prod` 选择。\n\n| 配置 | 用途 | \n|---|---|\n| `ZCODE_DATA_BASE_DIR` | 应用数据基目录，数据写入其下的 `.zcode/` | \n| `ZCODE_SERVER_WORKSPACE` | Web 后端的工作区路径 | \n| `ZCODE_BUILTIN_PROVIDER_CONFIG_FILE` | 本地 Provider 配置文件路径；未设置时使用内置配置 | \n| `ZCODE_DIST_BASE_URL` | 命令行安装脚本使用的下载根地址 | \n\n运行时变量可在启动命令的环境中显式设置。随客户端发布的默认配置见 [config/README.md](https://github.com/zai-org/ZCode/blob/main/config/README.md)。\n\n第三方声明生成、发行校验流程及声明在发行物中的位置见 [third-party/README.md](https://github.com/zai-org/ZCode/blob/main/third-party/README.md)。\n\n```\npnpm bundle:desktop\n\n# 指定目标平台与 CPU 架构\npnpm bundle:desktop -- --os win --arch x64\n\npnpm bundle:desktop -- --help\n```\n\n默认目标为 macOS arm64，默认输出目录为 `packages/desktop/dist/`。`--os` 支持 `mac`、` win`、` linux`，`--arch` 支持 `x64`、` arm64`；实际打包与签名需要目标平台对应的工具和配置。\n\n安装：双击打开产物 DMG，将 ZCode 拖入\"应用程序\"。本地构建未签名，首次打开若被 macOS 拦截，执行：\n\n```\nsudo xattr -rd com.apple.quarantine /Applications/ZCode.app\n```\n\n构建入口为 `pnpm build:zcode`。脚本会依次构建 CLI/TUI、后端和 Web，收集 TUI 的原生库、worker 与运行时依赖，再组装发行包；运行发行包仍需要 Node.js，版本以 `mise.toml` 为准。\n\n打包前必须设置下载根地址 `ZCODE_DIST_BASE_URL`（可放在 `.env`、`.env.local` 或环境变量中），也可以通过 `--base-url` 传入。以下地址是占位示例，发布时替换为实际托管地址：\n\n```\npnpm build:zcode --base-url https://downloads.example.com/zcode/\n\n# 已配置 ZCODE_DIST_BASE_URL 时\npnpm build:zcode\n\n# 仅重新组包，复用已有的 Agent、后端和 Web 构建产物\npnpm build:zcode --skip-build\n\n# 查看版本、输出目录等可选参数\npnpm build:zcode --help\n```\n\n默认版本取根目录 `package.json`，输出目录为 `dist/zcode/`：\n\n- `releases/<version>/zcode-<version>.tar.gz` ：运行包。\n- `releases/<version>/sha256.txt` ：校验摘要。\n- `latest.json` 、`install.sh` ：版本索引和安装脚本。\n\n完整目录可上传到配置的下载根地址。安装脚本从该地址下载运行包，默认安装到 `~/.zcode/runtime`，并在 `~/.local/bin` 创建 `zcode` 命令。安装目录可通过 `ZCODE_DIST_HOME` 修改，命令目录可通过 `ZCODE_DIST_BIN_DIR` 修改。\n\n旧 Lite 用户需要改用上述构建命令、环境变量和新的安装脚本。新安装不会删除旧 Lite 目录，也不会迁移或删除已有会话数据。\n\n本地调试打包产物时，可直接解压运行，无需上传或安装：\n\n``` js\nzcode_version=$(node -p \"require('./dist/zcode/latest.json').version\")\nmkdir -p dist/zcode/debug\ntar -xzf \"dist/zcode/releases/$zcode_version/zcode-$zcode_version.tar.gz\" \\\n  -C dist/zcode/debug\n# 默认启动 TUI\nnode dist/zcode/debug/zcode/bin/zcode.mjs\n\n# 启动 Web\nnode dist/zcode/debug/zcode/bin/zcode.mjs --web \\\n  --workspace \"$PWD\" --port 3030 --no-open\n```\n\n浏览器打开 `http://127.0.0.1:3030`，即可验证同一后端服务托管 Web 页面和 Agent 的完整链路。该端口需要空闲；如正在运行 `pnpm dev:web`，可改用其他 `--port`。\n\n| 目录 | 职责 | \n|---|---|\n| `packages/desktop` | Electron Main、Host、Renderer 与桌面打包 | \n| `packages/web` | Web 客户端 | \n| `packages/server` | HTTP / WebSocket 服务与远程连接 | \n| `packages/zcode-server-cli` | 独立 Server 启动与进程管理 | \n| `packages/ui` | 共享 React 组件、hooks 与 Zustand 状态 | \n| `packages/services` | 业务服务与持久化 | \n| `packages/shared` 、`packages/rpc` 、`packages/client` | 共享协议和类型、RPC 框架、Agent 客户端 SDK | \n| `packages/provider` 、`packages/provider-node` | Provider 公共能力与 Node 实现 | \n| `apps/zcode-cli` | Agent CLI、TUI、运行时与工具 | \n| `scripts` 、`config` 、`third-party` | 构建维护脚本、内置配置与第三方声明材料 | \n\n功能与优惠范围、维护规则、执行与数据风险，以及许可和第三方版权说明，详见 [NOTICE.md](https://github.com/zai-org/ZCode/blob/main/NOTICE.md)。", "url": "https://wpnews.pro/news/zcode-z-ai-s-coding-agent-harness-powerful-intelligent-extensible", "canonical_source": "https://github.com/zai-org/ZCode", "published_at": "2026-09-21 01:28:58+00:00", "updated_at": "2026-09-21 01:53:21.997590+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-products"], "entities": ["Z.ai", "ZCode", "Electron", "Node.js", "pnpm", "Agent CLI", "ZCODE_DATA_BASE_DIR", "ZCODE_SERVER_WORKSPACE"], "alternates": {"html": "https://wpnews.pro/news/zcode-z-ai-s-coding-agent-harness-powerful-intelligent-extensible", "markdown": "https://wpnews.pro/news/zcode-z-ai-s-coding-agent-harness-powerful-intelligent-extensible.md", "text": "https://wpnews.pro/news/zcode-z-ai-s-coding-agent-harness-powerful-intelligent-extensible.txt", "jsonld": "https://wpnews.pro/news/zcode-z-ai-s-coding-agent-harness-powerful-intelligent-extensible.jsonld"}}