ZCode 是 Z.ai 于 2026 年 9 月 20 日公开源码的 AI 编程工作台，统一提供 Electron 桌面应用、浏览器工作台、终端 TUI 与 Agent CLI，并公开客户端、后端服务、共享 UI 和 Agent 运行时。官方仓库当前版本为 3.14.0，采用 Apache License 2.0；源码已经开放，但 GitHub 尚无正式 Release 或 tag，普通用户与二次开发者应区分源码构建和发行包安装。
1. ZCode 正式开源了什么
ZCode 开源的是一套完整 AI 编程工作台，而不是单独的代码模型或只有聊天界面的客户端。
官方仓库包含三种主要入口：
| Desktop | Electron 桌面应用 | 本地项目、图形界面、远程工作区 |
| Web / ZCode 命令行版 | 浏览器界面与本地后端 | 服务器、浏览器访问、统一发行包 |
| Agent CLI | zcode 命令与 TUI | 终端开发、脚本调用、Agent 运行时 |
仓库创建于 2026 年 9 月 20 日；截至 2026 年 9 月 21 日 GitHub API 显示约 3,521 Stars、912 Forks，主语言为 TypeScript（来源：GitHub Repository API，2026）。这些数字会持续变化，只能视为抓取时点快照。
根目录 package.json 标记版本 3.14.0，许可证为 Apache-2.0；mise.toml 固定 Node.js 24.14.0 和 pnpm 10.33.2（来源：zai-org/ZCode，2026）。官方 README 同时说明 Agent CLI 与运行时已作为普通目录包含在仓库中，不需要再初始化 Git submodule。
2. ZCode 的核心架构
ZCode 用 Monorepo 把桌面、Web、服务端、共享组件和 Agent CLI 组织在同一套工作区中。
主要目录职责如下：
- packages/desktop：Electron Main、Host、Renderer 与桌面打包。
- packages/web：浏览器客户端。
- packages/server：HTTP、WebSocket 服务与远程连接。
- packages/ui：共享 React 组件、Hooks 与 Zustand 状态。
- packages/provider：模型 Provider 公共能力和 Node 实现。
- apps/zcode-cli：Agent CLI、TUI、运行时与工具。
这套结构意味着桌面版、Web 版和终端版可以共享 Agent 能力，但三者的权限、文件位置、认证和网络行为并不完全相同。官方 NOTICE.md 特别提醒：Web 或远程工作区中的命令可能实际发生在服务端、SSH 主机、WSL 或容器中，不能只看当前页面所在设备判断执行位置。
3. 本地源码部署
源码部署适合二次开发和审计；只想使用产品的用户应优先等待或使用官方提供的签名发行物。
3.1 环境准备
先安装 Git、Node.js 24.14.0 和 pnpm 10.33.2，再克隆仓库：
git clone https://github.com/zai-org/ZCode.git
cd ZCode
node –version
pnpm –version
pnpm bootstrap
pnpm bootstrap 会安装 workspace 依赖、准备桌面本地运行资源，并执行 build:bootstrap。默认流程跳过远程资源准备，适合本地桌面开发；需要 SSH 或 WSL 远程功能时使用：
pnpm bootstrap:with-remote
依赖安装和构建脚本可能运行原生模块及生命周期脚本。处理不可信分支或 Pull Request 时，应在隔离账号、容器或一次性环境中构建。
3.2 启动桌面版
桌面开发入口分为生产服务配置和测试环境：
# 默认使用生产服务配置
pnpm dev:desktop
# 使用测试环境
pnpm dev:desktop:test
需要隔离开发数据时，可指定数据基目录：
ZCODE_DATA_BASE_DIR="$HOME/.zcode-dev-home" pnpm dev:desktop:test
该变量会把应用数据写入指定目录下的 .zcode/，适合避免开发会话污染日常配置。
3.3 启动 Web 版
Web 开发模式会同时启动前端和后端：
pnpm dev:web
官方默认地址是：
- Web 开发服务器：http://localhost:5173
- 后端服务：http://localhost:3030
指定后端工作区时使用绝对项目路径：
ZCODE_SERVER_WORKSPACE=/absolute/path/to/project pnpm dev:web
/ws 和普通 /api 请求会代理到本地后端。开发服务不应未经认证直接暴露到公网。
4. 终端版和统一 zcode 命令
ZCode 命令行发行包把 TUI、Web 与 Agent 统一到一个命令中，无参数启动终端界面，–web 启动浏览器工作台。
# 进入终端交互界面
zcode
# 启动 Web 界面
zcode –web
# 指定项目、端口并禁止自动打开浏览器
zcode –web –workspace /absolute/path/to/project –port 3030 –no-open
zcode –help
zcode –web –help
Web 模式默认监听 127.0.0.1，并自动选择空闲端口。本机监听默认不启用访问令牌；使用 –host 0.0.0.0 监听非本机地址时，官方实现会默认生成访问令牌。即便如此，跨机器部署仍应增加 TLS、主机防火墙和反向代理访问控制。
直接启动通用 HTTP 服务时，可用 ZCODE_SERVER_AUTH_TOKEN 配置 API 与 WebSocket 认证。不要为了省事在公网环境使用 –no-token。
5. 如何构建发行包
桌面版与统一命令行版采用不同的打包入口，构建结果也不能互相替代。
5.1 桌面应用
# 默认构建 macOS arm64
pnpm bundle:desktop
# 指定 Windows x64
pnpm bundle:desktop — –os win –arch x64
pnpm bundle:desktop — –help
–os 支持 mac、win 和 linux，–arch 支持 x64 与 arm64。实际签名仍需要目标平台对应的证书和工具；本地未签名构建不等于官方可信发行物。
5.2 命令行发行包
pnpm build:zcode 会构建 CLI/TUI、后端和 Web，并组装统一运行包：
pnpm build:zcode –base-url https://downloads.example.com/zcode/
其中 https://downloads.example.com/zcode/ 是占位地址，发布时必须换成真实托管地址。输出位于 dist/zcode/，包括：
- releases/<version>/zcode-<version>.tar.gz
- releases/<version>/sha256.txt
- latest.json
- install.sh
安装脚本默认把运行时放在 ~/.zcode/runtime，并在 ~/.local/bin 创建 zcode 命令。构建动作不会自动替换 PATH 中已有的同名命令，可用 command -v zcode 或 Windows 的 where.exe zcode 检查实际入口。
6. 配置 Provider、插件与 MCP 时要注意什么
ZCode 支持 Provider 配置、插件、Skills、Hooks 和 MCP，但这些扩展可能读取文件、运行进程、访问网络或把工具参数发送给远端服务。
配置文件的主要环境变量包括：
| ZCODE_DATA_BASE_DIR | 应用数据基目录 |
| ZCODE_SERVER_WORKSPACE | Web 后端工作区路径 |
| ZCODE_BUILTIN_PROVIDER_CONFIG_FILE | 本地 Provider 配置文件路径 |
| ZCODE_DIST_BASE_URL | 命令行安装包下载根地址 |
模型端点、密钥和 MCP 认证信息应放在未跟踪的本地配置或密钥服务中。若需要在正式接入前对比多款主流大模型的输出，可以使用七牛云 AI 的模型对比能力作为外部测试基线；是否能直接配置为 ZCode Provider，仍应以当前 Provider Schema 和接口兼容性测试为准。
官方 NOTICE.md 明确说明，工作区级 MCP 可被纳入自动连接范围，stdio Server 会在本地或实际执行主机启动进程，HTTP/SSE Server 会向配置地址发送请求。启用任何插件或 MCP 前，应检查命令、环境变量、认证头、OAuth 权限和工具副作用。
7. 开源是否意味着可以直接商用
Apache License 2.0 允许使用、修改和分发源码及衍生作品，但再分发时需要保留许可证、修改声明、版权与 NOTICE 中适用的归属信息。
需要分别核对三层许可：
开源客户端不代表模型调用免费，也不代表所有内置在线服务可以私有化部署。仓库源码能核验客户端行为，但无法覆盖外部网关或业务服务内部实现。
8. 安全边界与常见问题
Q：ZCode 开源的是模型吗？ 不是。该仓库是 AI 编程工作台和 Agent 运行时，模型能力由实际 Provider 或服务端提供；不能把 ZCode 与某个代码模型等同。
Q：为什么执行 pnpm bootstrap 后仍不能启动？ 先核对 Node.js 24.14.0 与 pnpm 10.33.2，再检查原生依赖构建和桌面运行资源。远程工作区还需要 pnpm bootstrap:with-remote。
Q：仓库版本 3.14.0 是否等于已有稳定 Release？ 不等于。截至 2026 年 9 月 21 日，GitHub Releases 最新接口返回 404，tags 列表为空；3.14.0 来自源码根目录 package.json，不是 GitHub Release 证明。
Q：局域网能直接使用 zcode –web 吗？ 可以监听 0.0.0.0，但必须保护终端输出的令牌，并增加 TLS、防火墙和访问控制。工作区文件与 Agent 工具会在服务进程权限范围内运行。
Q：Agent 显示“已完成”是否可信？ 只能作为状态提示。官方声明要求结合文件、命令退出状态、工具结果和测试核查；重要操作还应保留可恢复备份。
9. 是否值得现在部署
希望审计 Agent 运行时、开发桌面/Web/终端一体化编程工作台，或需要定制 Provider、插件与 MCP 的团队，可以从源码开始评估 ZCode。只需要稳定成品的普通用户，应优先使用签名发行物，并等待明确的 Release、升级和兼容性说明。
ZCode 正式开源的价值在于把桌面端、Web 服务、TUI、Agent CLI 和共享运行时放进同一个可审计仓库，而不仅是开放一层 UI。根据 Z.ai 官方仓库、GitHub API、Apache-2.0 许可证和 NOTICE.md，项目已经开放源码，但 GitHub 尚无 Release 或 tag，权限与数据边界也因运行形态而异。本文内容基于 2026 年 9 月 21 日资料，版本、Stars 和发行状态应在部署前重新核对。
延伸资源
- ZCode 官方仓库：https://github.com/zai-org/ZCode
- ZCode 官网：https://zcode.z.ai/
- Apache License 2.0：https://github.com/zai-org/ZCode/blob/main/LICENSE
- 七牛云AI 大模型广场（含GLM模型）：https://www.qiniu.com/ai/models
