ZCode-CE

问题反馈 · 讨论区 · 上游项目

简体中文 | English

ZCode-CE 是 AI 编程工作台 ZCode 的开源社区版，提供桌面应用、浏览器界面和终端 Agent。本仓库包含客户端、后端服务、共享 UI，以及 Agent CLI 与运行时源码。

ZCode-CE 基于 zai-org/ZCode（Apache-2.0）构建，面向希望完全掌控自己开发环境的用户。欢迎社区成员参与建设 —— 无论是功能开发、问题反馈还是文档改进。

当前发布 3.16.3-ce.1.fix.1（3.16.3-ce.1 的启动热修复）：代码基线是上游开源 3.16.2（3c5b2276）的逐特性移植；版本号对齐官方闭源 3.16.3（3.16.3 未开源）。逐条状态见上游同步，本版变更见 Releases。

我们与官方发行版的差异目前集中在七个方面：

• 不是官方发行版。ZCode-CE 由社区维护，不代表 Z.ai 或智谱的官方立场。
• 不提供账号服务。模型访问、套餐与计费仍由官方服务提供，本项目不代理、不转售。

以下限制长期存在，与具体版本无关；发版说明只记录「因本次变更而新出现」的限制，避免每版重复同样的内容。

• 桌面自动化（Computer Use）：Windows 为正式支持；Linux 为实验性（默认关闭，需在设置中开启）。官方发行版不支持 Linux 桌面自动化，本版通过开源实现提供，但受上游验证范围限制。详见桌面自动化文档。

• 桌面自动化在 Linux 上有环境限制：已在 X11 / Sway / KDE Wayland 验证，Wayland 下截图不可用（元素操作不受影响），GNOME 未完整验证。

• Windows 构建未签名：首次运行需在 SmartScreen 提示中选择「仍要运行」，原因与进展见下方安装一节。

• Windows / macOS 未在真机做完整功能回归：CI 会为两个平台打包，但本项目的日常验证以 Linux 为主。

• macOS 无自动更新：macOS 客户端不检查更新（electron-updater 在 darwin 保持关闭）。安装包随版由 CI 产出（.dmg / .zip，ad-hoc 签名、未公证，首次打开需允许 Gatekeeper）。见上方安装一节。

• 无头/Web 面板的安全默认值：服务默认只监听回环；非回环监听必须带令牌，否则拒绝启动。明文 http 只应出现在可信局域网内，公网/不可信网络请放在 TLS 终结的反向代理或隧道之后（否则令牌与流量可被窃听/替换）；令牌等价于 agent 级访问，拿到它就能执行工具调用。

• 手机窄屏仍有未完成的打磨项：主内容区裁切与头部控件重叠已修（窄屏默认收起侧栏、头部按窄屏简化、浮层命中区补到 44px），仍有三项未完成：发送/停止键命中区偏小、composer 存在结构错位、软键盘避让只做了单行 meta 修复（真机 IME 未验证）。桌面宽度不受影响。

• 手机与桌面同时连的行为未测：两个客户端可各自建立连接，但同一会话被两端同时操作的并发语义没有测（见网页远控 §8），不要在依赖它之前假定行为。

以下能力官方发行版包含但未随源码分发。本版的实际状态见各行（有的已补齐、有的只补齐部分），仍未提供的计划在后续版本补齐 —— 某一行若自带限制说明，以该行的说明为准。

其余未提供的能力及其原因见与官方发行版的差异。

CLI/Web 发行包目前支持 Linux-x64（glibc）：Alpine / musl 不在正式支持范围；实测在 Alpine 上装满足 engines 的 musl 版 Node ≥24 后，服务与面板可用，终端功能不可用（会给出明确提示，而不是崩溃）。Windows / macOS 需按目标平台构建并补齐原生载荷与终端后端（conpty），另需为 Windows 提供令牌轮换的替代通道（Windows 没有 SIGHUP）。支持边界见无头服务器文档。

从 Releases 下载对应平台的安装包。

数据目录：与官方 ZCode 共享 ~/.zcode/v2，两者可并存安装（安装身份独立），但不建议同时运行。

关于 Windows 签名：官方发行版使用 DigiCert 签发的组织验证（OV）证书签名。本项目作为社区项目无法申请同类证书，正在申请 SignPath Foundation 的免费开源代码签名（证书签发给 SignPath Foundation，非本项目），通过后将消除 SmartScreen 提示。详见 Code signing policy。

不装桌面应用、只在服务器上跑工作台并用浏览器（含手机窄屏）操作时走这两条。它们不接管桌面端，也不含桌面端的本地能力（Computer Use、内嵌浏览器等）。

Docker 形态要先产出构建上下文 dist/zcode/（需要仓库源码，命令见无头服务器发行包 §2），然后：

# 1) 准备令牌（compose 会读同目录 .env）
printf "ZCODE_SERVER_TOKEN=%s\n" "$(openssl rand -hex 16)" > .env
: > tokens.txt        # compose 会把它挂成令牌文件（追加即可轮换）

# 2) 构建 + 启动（首次会构建镜像，约几分钟）
docker compose up -d --build

# 3) 探活（本机）
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3030/   # 200

卷与备份、令牌与轮换、局域网访问、安全边界见无头服务器：Docker；参数、安全默认值与平台支持见无头服务器发行包。

想从源码构建或参与开发？见下方初始化与开发与运行。

准备 Git、Node.js 24.14.0 和 pnpm 10.33.2，版本以 mise.toml 为准。以下开发和打包命令均在仓库根目录执行。

pnpm bootstrap

pnpm bootstrap 安装 workspace 依赖、准备桌面本地运行资源，再执行 build:bootstrap。

Agent CLI 与运行时源码位于 apps/zcode-cli/，作为普通目录随本仓库一起克隆，无需单独拉取或初始化 Git submodule。

根据需要选择其他初始化或构建入口：

默认 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 dev:web

该命令同时启动 Web 开发服务器和后端；浏览器访问前者。

改动桌面端 main/renderer 时，额外运行 bash scripts/desktop-typecheck-baseline.sh diff —— pnpm typecheck 的工程列表不覆盖这两个子工程。

ZCode-CE 与官方 ZCode 使用独立的安装身份，可以并存。两者共享 ~/.zcode/v2/ 数据目录，因此不建议同时运行并写入同一工作区。

开发者文档见 docs/：

• 架构与模块边界
• 与上游的差异
• 与官方发行版的差异
• 本地开发
• 遥测与隐私
• 网页远控：无头服务器 + 浏览器面板
• 远程工作区（SSH / Docker / WSL）
• 工具与权限：按资源/工具精细启停
• 贡献指南
• 发布流程

ZCode-CE 站在许多开源项目的肩膀上。以下按用途分类列出我们复用或参考的项目。

这些项目的代码被直接引入本仓库，完整清单与许可快照见 third-party/copied-components.json。

完整的 npm 依赖许可清单见 THIRD-PARTY-NOTICES.md。

以下项目未复用代码，但其设计与接口约定对本项目的实现有重要参考价值。

模型访问、套餐与计费由 Z.ai / 智谱 提供，本项目不代理、不转售。

感谢上述项目的作者与维护者。如果你的项目出现在这里但归属或表述有误，欢迎提 issue 指正。

本项目基于 zai-org/ZCode 构建，遵循 Apache-2.0。

第三方组件声明见 THIRD-PARTY-NOTICES.md，功能说明与风险提示见 NOTICE.md。