ZCode：Z.ai 开源的 AI 编程工作台，桌面端、浏览器、终端三套壳共用一个 Agent

两天时间，GitHub 上冒出一个 5600 多星的项目。仓库地址是 github.com/zai-org/ZCode，简介只有一句话：「Z.ai’s coding agent harness. Powerful, intelligent, extensible.」——Z.ai 的编程智能体承载层。

它不是又一个 Claude Code 复刻，也不是单纯的终端 TUI。ZCode 想做的事更大一点：把「AI 写代码」这件事拆成一套完整的工作台，同时给出三个入口——桌面应用、浏览器界面、终端 Agent，底层共用同一套 Agent 运行时。

一句话定位

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`

关键在最后一行：Agent CLI 不只是个终端工具，它同时是桌面版和 Web 版的运行时底座。换句话说，三个界面共享同一个大脑，你在终端里攒下的会话和配置，桌面端能接着用。

为什么值得关注

它不是「壳」，是整套栈。 很多同类项目只做一层 UI，背后调用别家的 Agent。ZCode 把 Electron Main/Host/Renderer、Web 客户端、HTTP/WebSocket 服务、共享 React 组件、Provider 抽象、Agent CLI 全部放在同一个 monorepo 里。仓库结构可以直接当架构图看：

目录	职责
`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 实现
`apps/zcode-cli`	Agent CLI、TUI、运行时与工具

它真的在乎「远程开发」。 这个项目对 SSH / WSL 远程工作流做了一等公民支持。你可以先跑 pnpm bootstrap:with-remote 准备远程资源，再连接远程项目；开发态资源从本地构建产物经 SFTP 上传到远程，不依赖 CDN。对于习惯「笔记本写代码、服务器跑任务」的人来说，这个设计比很多把远程当附加功能的工具实在。

怎么跑起来

先明确环境要求，ZCode 对版本卡得比较死：Git、Node.js 24.14.0、pnpm 10.33.2，版本以仓库里的 mise.toml 为准。所有命令都在仓库根目录执行。

pnpm bootstrap

这一条做了三件事：安装 workspace 依赖、准备桌面本地运行资源、执行 build:bootstrap。

需要别的入口时：

pnpm install                    # 只装依赖
pnpm prepare:desktop-runtime    # 准备桌面运行资源（默认含远程资源）
pnpm prepare:remote-assets      # 单独准备远程运行资源
pnpm bootstrap:with-remote      # 依赖 + 本地 + 远程资源，串行构建（跳过桌面 bundle）
pnpm build                      # 递归执行各 workspace 包的构建脚本

默认的 bootstrap 会跳过远程资源准备，适合本地桌面开发；只有验证远程发行资源时才需要那几条 remote 命令。

桌面端

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

pnpm dev:desktop 默认等同 pnpm dev:desktop:prod。启动脚本会自动准备本地运行资源、构建桌面 Agent，再拉起 Electron 和源码监听。想隔离开发数据，可以指定数据目录：

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

Web 端

pnpm dev:web
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 再重启服务。

命令行版本

这是最有意思的部分。命令行发行包把 TUI、Web 和 Agent 打包在一起，统一用 zcode 启动：无参数进 TUI，第一个参数是 --web 就起 Web 界面，其他参数交给 Agent CLI。两种模式都在本机跑，不需要 Electron。

zcode                                                    # 进入终端交互界面
zcode --web                                              # 启动 Web 界面
zcode --web --workspace /path/to/project --port 3030 --no-open
zcode --help
zcode --web --help

Web 模式默认工作目录是当前目录，监听 127.0.0.1，默认不启用访问令牌，自动挑一个空闲端口并打开浏览器。局域网访问可以加 --host 0.0.0.0；监听非本机地址时会默认生成访问令牌，用终端输出的带令牌链接访问。也可以用 --token 指定，或 --no-token 关掉认证。

打包成自己的发行版

ZCode 支持把整套东西打成可分发产物。

桌面版：

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

默认目标是 macOS arm64，默认输出在 packages/desktop/dist/。--os 支持 mac、win、linux，--arch 支持 x64、arm64——注意实际打包和签名需要目标平台对应的工具链。本地构建未签名，macOS 首次打开若被拦截，官方给的办法是：

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

命令行版用 pnpm build:zcode，打包前必须设置下载根地址 ZCODE_DIST_BASE_URL：

pnpm build:zcode --base-url https://downloads.example.com/zcode/
pnpm build:zcode --skip-build     # 复用已有构建产物，只重新组包

产物落在 dist/zcode/ 下：releases//zcode-.tar.gz 是运行包，sha256.txt 是校验摘要，另外还有 latest.json 和 install.sh。安装脚本默认装到 ~/.zcode/runtime，并在 ~/.local/bin 创建 zcode 命令；目录可以用 ZCODE_DIST_HOME、ZCODE_DIST_BIN_DIR 改。

不想上传 CDN 也能本地验证：

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

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

浏览器打开 http://127.0.0.1:3030，就能验证「同一后端同时托管 Web 页面和 Agent」的完整链路。注意这个端口要空闲，如果 pnpm dev:web 正在跑就换个 --port。

配置项速查

根目录的 .env.example 给了服务地址与构建配置示例，复制成 .env 即可，本地覆盖放 .env.local。几个关键变量：

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

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

几点实话

它需要你有点工程耐心。 这不是 npm install -g 就能用的那种工具。Node 版本卡到 24.14.0、pnpm 卡到 10.33.2，要跑 bootstrap，要理解 desktop / web / cli 三条开发路径的区别。官方也提示：旧 Lite 用户需要改用新的构建命令、环境变量和安装脚本，而且新安装不会迁移或删除已有的会话数据——升级要自己心里有数。

但它给的东西很完整。 从 Electron 桌面端到浏览器工作台再到终端 Agent，从 Provider 抽象到远程 SSH/WSL 工作流，从开发调试到打包分发和安装脚本，这套 monorepo 几乎是「一个 AI 编程产品该有的全部零件」。Apache-2.0 许可，你可以直接拿它当自己产品的底座。

两天的 5600 星说明市场对「能自己掌控的 AI 编程工作台」有多饥渴。现在几乎所有编程 Agent 都绑在某朵云上，ZCode 把整套栈开源出来，等于给想做私域、想接自己模型、想在远程服务器上跑 Agent 的团队递了一把完整的扳手。

仓库和文档都在这里：