简体中文 | English
"为什么我们这么坚持开源?因为这个愿景本身就要求开源。你没有这个愿景,你没法把人组织起来。比如说,智谱也开源,但是智谱的开源跟我们的开源不一样。智谱的开源有一种被迫的感觉,他们觉得这不是本意,但是对我们来讲,这就是我们的本意。"
—— 梁文锋,深度求索 CEO
ZCodium 是 ZCode 的独立审计分支。上游 ZCode 是 AI 编程工作台,提供桌面应用、浏览器界面和终端 Agent;本仓库包含客户端、后端服务、共享 UI,以及 Agent CLI 与运行时源码。代码更新只从官方开源仓库 zai-org/ZCode 吸收,并保留“去遥测、不依赖官方云服务”的审计边界;维护规则见 docs/specs/maintenance-model.md。
上游在 2026-09 被迫将 ZCode 客户端开源,但开源出来的源码与他们实际发布的安装包并不等价:发布包里带有一批开源代码中没有的功能。ZCodium 的做法是跟进上游官方仓库,在不恢复官方遥测、账号、购买和云服务的前提下,把仅存在于发布包中的本地功能补全,让自建的源码能够构建出与官方包本地能力对等的产物。
补全手段包括:补齐缺失的内置插件与技能、比对 i18n 键定位功能缺口、按协议与设置 schema 对齐交互链路。所有补全都记录在 .agents/specs/ 下的 spec 中,包含范围、状态所有者、接口契约与验收场景。
以下是基于官方 3.14.3 安装包的历史核对底稿(ZCode-3.14.3-win-x64.exe,appVersion: 3.14.3,构建于 2026-09-22)。核对方法:从安装包取出 resources/app.asar 内 out/renderer/assets/IntlProvider-*.js 的语言表,与 packages/ui/src/i18n/locales/ 做键差集。下表保留当时的分类,部分说明已按后续实现更新;不是当前 3.15.1 的完整能力验收,也不把语言键数量等同于功能数量。
已补全:
- 内置插件与技能:documents、pdf、presentations、spreadsheets、skill-creator、plugin-creator、image-search、restore-legacy-sessions、zcode-guide、zcode-cua。安装包只分发源码资源完整且明确注册的插件;范围见 .agents/specs/builtin-plugin-parity.md、.agents/specs/pdf-plugin-backfill.md 与 .agents/specs/spreadsheets-plugin-backfill.md。
- Computer Use 的模型可见面:
apps/zcode-cli/packages/zcode-cua-plugin/scripts/computer-use-client.mjs、技能与文档。原生 runtime(koffi/sharp,约 20 MiB)未随包发布,与上游runtimeTopLevelPaths: []的声明一致。
历史语言表分类(当时统计 258 键;下表含后续已实现项及有意不补的官方账号/权益/营销项,不作为当前缺口总数):
| 领域 | 缺口 | 说明 |
|---|---|---|
webRemoteControl |
0 键 | 手机远控桌面已补齐(LAN 直连 + 用户自托管 relay) |
manualClaimPlan |
53 键 | 官方权益领取与验证码流程;按审计边界不补全 |
mode |
38 键 | 会话模式扩展 |
settings |
26 键 | 含 Claude 模型槽位映射、Anthropic/OpenAI/Gemini 端点模板 |
server |
12 键 | Server 入口 |
appHeader |
8 键 | Provider 配置入口 |
marketingTouch |
7 键 | 官方权益触达;按审计边界不补全 |
taskList |
6 键 | Codex / Claude 新建任务 |
chat |
5 键 | agent 切换 |
rewards |
5 键 | 官方权益菜单;按审计边界不补全 |
onboarding |
4 键 | agent 设置步骤 |
| 其他 | 5 键 | remote、zcode、titleBar |
bots 的 259 个键已由上游 3.14.3 全部开源并随合并进入本仓库,缺口为 0。webRemoteControl 的 89 键已由本仓库补齐(2026-09-29,spec 见 .agents/specs/web-remote-control.md):默认同网扫码直连,桥接桌面已有 Host;用户自托管 relay(跨网)为可选后续。manualClaimPlan 按审计边界不实现,不列为待补债务。历史反向差集中的 33 个本仓特有键主要来自 AstrBot 桥接与 .zcodium 命名空间;当前键数未在本段重新统计。
有意不补全:
- 仓库快照上传。官方 3.14.0 之前的版本会在每次提问前打包整个 workspace(含
.git)并加密上传至对象存储,服务端持有私钥。该行为已从上游移除,本仓库同样不实现,仅在 apps/zcode-cli/tools/repo-snapshot-parody/ 保留一份 localhost 本地复现用于审计对照——密钥本地生成、默认拒绝非回环目标。 - 官方遥测采集与上报。ZCodium 保留安全的本地诊断,默认无上报;用户可显式配置自己的 OTLP 接收端。详见诊断说明。
- 官方账号、登录、OAuth、购买、套餐、权益领取、营销触达、官方分享/上传、官方 client config/rollout、官方 relay 与官方更新源。源码中保留历史 Provider ID 和数据库迁移用于读取旧数据,运行时不恢复账号执行能力。
已落地:
bots:Bots 服务 + AstrBot 桥接并存。 上游 3.14.3 已开源bots(四套平台 adapter 与“接哪个平台”的设置 GUI),本仓库已并入。自研的 AstrBot 桥接不再是与 Bots 服务 并行的独立服务,而是收敛为BotsService的一个传输 provider (BotProviderAdapter,channel 固定为astrbot),已在 Bots 设置界面与手机远控入口接入; 平台适配由 AstrBot 承担,本仓库只维护桥接契约(wire 协议 v2);AstrBot 侧需安装支持该协议的插件。 见 .agents/specs/bots-astrbot-bridge.md。- Computer Use 运行时:原生执行层不自研,复用开源项目
trycua/cua的@trycua/cua-driver(MIT,Rust,macOS / Windows / Linux),适配器见 packages/zcode-cua/; client 由上层注入,没有 client 时保持 fail-closed。老 GNOME / Wayland 另有一层 物理输入兼容层。能力对接与缺口、适配器契约与各平台机制分别见 .agents/specs/computer-use-capabilities.md、 .agents/specs/computer-use-runtime.md 与 .agents/specs/computer-use-platform-architecture.md。
用户自配置能力:
- image-search 无默认服务:用户显式配置完整
imageSearchMcpUrl(本地或自建远程 MCP)及可选认证头,插件默认不启用,未配置时不连接。本仓不提供搜图后端,也不注入官方凭据。见 .agents/specs/image-search-local-backend.md。
本仓库只跟踪官方 zai-org/ZCode,不跟踪任何第三方 fork。ZCodium-project/ZCodium 只作为审计原则和实现方式的只读参考,不作为合并来源。
每次同步的固定顺序是:拉取官方 tag → 建同步分支 → merge(不 rebase)→ 按审计边界解决冲突 → 执行检查清单 → 记录官方基线、吸收项、剥离项、未同步项和验证范围。完整流程与欠账清单见 docs/specs/maintenance-model.md。
审计边界:不引入官方遥测/监控/崩溃采集/资源或网络采样上报/UI 埋点;不依赖官方账号、购买、套餐、分享、上传、官方插件市场自动拉取、官方 client config/rollout、官方 relay 或官方更新源。用户使用自己的 API Key 或自定义 Provider;安全本地日志可用;后台采样与对外诊断导出分别默认关闭,导出仅在用户显式开启并配置自建接收端时启用。官方重新引入已删除的遥测/云服务时,保留本仓删除并做最小适配,不通过恢复模块来让测试变绿。
补全规则:只评估符合本仓产品与审计边界的本地能力;安装包、源码和运行时证据用于定位差异,不因安装包包含某功能就恢复官方遥测、账号、权益或云服务。等价实现先明确 spec、许可和验收,不承诺全产品无差异。补全内容按功能单独提交,并在 .agents/specs/ 下记录实现范围、决策依据与未验证部分。许可证与第三方版权归属见 LICENSE、NOTICE.md。
| 入口 | 用途 | 开发命令 |
|---|---|---|
| Desktop | Electron 桌面应用 | pnpm dev:desktop |
| Web / ZCode 命令行版 | 终端与浏览器工作台;将 TUI、Web、后端和 Agent 组装为独立运行包 | pnpm dev:web |
| Agent CLI | 在终端中使用 zcode,也为 Desktop 和 Web 提供 Agent 运行时 |
pnpm --filter @zcode/cli dev |
- 2026-09-29:补齐手机远控(
webRemoteControl)本体:桌面 LAN 直连配对/QR + 桥接已有 Host +packages/webmobile entry,89 键全量落地;跨网提供用户自托管 relay 包(packages/relay,Docker 一键),本项目不运营任何中转(spec)。 - 2026-09-24:AstrBot 桥接整合为官方
BotsService的传输 provider,并在官方 Bots GUI 与手机远控入口接入(#11–#14)。 - 2026-09-24:按官方 3.14.3 安装包重新核对 i18n 键缺口,
bots259 键已归零,剩余 258 键;核对方法记入「与官方包的能力差异」。 - 2026-09-24:Computer Use 运行时改为复用
@trycua/cua-driver作为唯一原生引擎,移除自研 desk-pilot;client 由上层注入,缺失时保持 fail-closed,老 GNOME / Wayland 另走物理输入兼容层。 - 2026-09-24:合并上游 3.14.3(
328c1a0),纳入官方 bots 与手机远控等新开源内容;继续保留.zcodium数据命名空间。
发行版本以根目录 package.json 为准。发布标签必须严格匹配 v<version>,由 node scripts/ci/desktop-release.mjs check-version 校验。安装包通过独立的 ZCodium 产品身份区分,文件名为 ZCodium-<version>-<platform>-<arch>.<ext>,不要求添加 -modified 后缀。
Desktop CI 仅在用户明确要求的手动 workflow_dispatch 时构建;每次运行产出 Windows x64/arm64 exe 和 macOS arm64/x64 DMG,push 分支、push 标签和 PR 均不触发。本 fork 不分发 Linux 安装包或 Linux 远端运行资源,手机远控继续提供。
准备 Git、Node.js 24.14.0 和 pnpm 10.33.2,版本以 mise.toml 为准。以下开发和打包命令均在仓库根目录执行。
pnpm bootstrappnpm bootstrap 安装 workspace 依赖、准备桌面本地运行资源,再执行 build:bootstrap。
Agent CLI 与运行时源码位于 apps/zcode-cli/,作为普通目录随本仓库一起克隆,无需单独拉取或初始化 Git submodule。
根据需要选择其他初始化或构建入口:
| 命令 | 用途 |
|---|---|
pnpm install |
安装依赖 |
pnpm prepare:desktop-runtime |
准备目标 Windows/macOS 的本机运行资源 |
pnpm build |
递归执行各 workspace 包的构建脚本,包括包内的资源准备步骤 |
本 fork 的桌面构建仅支持 Windows/macOS,不准备或嵌入 Linux 远端运行资源。
pnpm dev:desktop
# 使用测试环境
pnpm dev:desktop:testpnpm dev:desktop 默认等同于 pnpm dev:desktop:prod,使用生产服务配置。启动脚本会准备本地运行资源、构建桌面 Agent,再启动 Electron 和源码监听。
需要独立开发数据目录时,可设置 ZCODE_DATA_BASE_DIR。例如在 macOS 中:
ZCODE_DATA_BASE_DIR="$HOME/.zcodium-dev-home" pnpm dev:desktop:test内置模型与供应商目录随应用和 CLI 发布,运行时不会从官方服务下载更新,也不会使用历史下载缓存。个人模型、API 密钥与自定义端点仍通过现有设置管理。
本 fork 的桌面包不提供 Linux 远端运行资源,因此不支持部署 SSH、WSL 或 Linux 容器远程工作区。连接时会明确报缺少运行资源,不联网补下载或复用历史制品。
手机远控连接本机桌面的已有 Host,不需要 Linux 远端资源,继续随 Windows/macOS 桌面包提供。
只检查桌面启动动效时,可运行 node scripts/ci/startup-animation-preview.mjs,打开终端输出的
本地地址。页面支持重复播放、深浅色、慢启动与失败场景,复用实际启动代码,不连接真实项目。
实现边界和验证命令见 启动动画说明。
修改 Web 或后端源码时,使用开发模式:
pnpm dev:web
# 指定后端工作区(macOS / Linux)
ZCODE_SERVER_WORKSPACE=/path/to/project pnpm dev:web该命令同时启动 Web 开发服务器(默认 http://localhost:5173)和后端(默认 http://localhost:3030);浏览器访问前者。/ws 和 /api 请求均代理到本地后端,不存在官方账号 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 --helpWeb 模式默认工作目录为当前目录,监听 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。
参见 UI Plugin:能力、API 与调试,从 Excalidraw 的画布协作示例开始,了解插件安装更新、页面 API 和宿主联调入口。
向 zcode-plugins 提交插件 PR 时,必须在 PR 模板中声明是否为 UI Plugin,并填写插件名称。 判断标准见提交 PR 时声明插件类型。
根目录 .env.example 提供服务地址与构建配置示例,可按需复制到 .env,本地覆盖放入 .env.local。Desktop 的开发环境通过 dev:desktop:test / dev:desktop:prod 选择。
| 配置 | 用途 |
|---|---|
ZCODE_DATA_BASE_DIR |
应用数据基目录,数据写入其下的 .zcodium/ |
ZCODE_SERVER_WORKSPACE |
Web 后端的工作区路径 |
ZCODE_BUILTIN_PROVIDER_CONFIG_FILE |
本地 Provider 配置文件路径;未设置时使用内置配置 |
ZCODE_DIST_BASE_URL |
命令行安装脚本使用的下载根地址 |
运行时变量可在启动命令的环境中显式设置。随客户端发布的默认配置见 config/README.md。
Desktop CI 是唯一工作流,只响应手动 workflow_dispatch;push 分支、push 标签和 PR 均不触发。检查与 Windows x64/arm64、macOS arm64/x64 打包从同一 ref 并行运行。Windows 产 exe,macOS 只产 dmg;Actions 产物分别为 desktop-win-x64、desktop-win-arm64、desktop-mac-arm64、desktop-mac-x64,保留 14 天。不构建 Linux 安装包或 Linux 远端运行资源。
工作流只生成 Actions 产物,不创建或更新 GitHub Release。构建只在用户明确要求时执行,先确认目标分支已推送;未获推送授权时不得借构建推送。手动从 tag 运行仍须满足 v<package.json.version> 校验。release-it 默认不 push;版本、commit、tag、push 与发布分别需要授权,显式 push 只发往 origin。
流程使用仓库自带的 GITHUB_TOKEN,无需额外服务凭据或签名证书。安装包未签名;应用内更新和独立远程运行资源不由此流程发布。规则见 CI/CD spec。
第三方声明由 node scripts/licenses.mjs notices 依据工作区生产依赖图与 third-party/ 下的来源、原生组件及许可证文本生成,产物为随发行物分发的 THIRD-PARTY-NOTICES.md;命令行发行包的组装与校验见 scripts/zcode-distribution/。
默认使用 GitHub 构建;以下本机打包命令只在用户明确要求时执行,从准备阶段起设置 ZCODE_ENV=production。
pnpm bundle:desktop
# 指定目标平台与 CPU 架构
pnpm bundle:desktop -- --os win --arch x64
pnpm bundle:desktop -- --help默认目标为 macOS arm64,默认输出目录为 packages/desktop/dist/。--os 仅支持 mac、win,--arch 支持 x64、arm64;实际打包与签名需要目标平台对应的工具和配置。
安装:双击打开产物 DMG,将 ZCodium 拖入"应用程序"。本地构建未签名,首次打开若被 macOS 拦截,执行:
sudo xattr -rd com.apple.quarantine /Applications/ZCodium.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/<version>/zcode-<version>.tar.gz:运行包。releases/<version>/sha256.txt:校验摘要。latest.json、install.sh:版本索引和安装脚本。
完整目录可上传到配置的下载根地址。安装脚本从该地址下载运行包,默认安装到 ~/.zcodium/runtime,并在 ~/.local/bin 创建 zcode 命令。安装目录可通过 ZCODE_DIST_HOME 修改,命令目录可通过 ZCODE_DIST_BIN_DIR 修改。
旧 Lite 用户需要改用上述构建命令、环境变量和新的安装脚本。新安装不会删除旧 Lite 目录,也不会迁移或删除已有会话数据。
本地调试打包产物时,可直接解压运行,无需上传或安装:
zcode_version=$(node -p "require('./dist/zcode/latest.json').version")
mkdir -p dist/zcode/debug
tar -xzf "dist/zcode/releases/$zcode_version/zcode-$zcode_version.tar.gz" \
-C dist/zcode/debug
# 默认启动 TUI
node dist/zcode/debug/zcode/bin/zcode.mjs
# 启动 Web
node dist/zcode/debug/zcode/bin/zcode.mjs --web \
--workspace "$PWD" --port 3030 --no-open浏览器打开 http://127.0.0.1:3030,即可验证同一后端服务托管 Web 页面和 Agent 的完整链路。该端口需要空闲;如正在运行 pnpm dev:web,可改用其他 --port。
| 目录 | 职责 |
|---|---|
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 实现 |
packages/model-option-map |
模型选项映射编译 |
packages/formal-proof |
产品行为状态空间枚举器 |
packages/zcode-cua |
Computer Use 运行时适配器 |
apps/zcode-cli |
Agent CLI、TUI、运行时与工具 |
scripts、config、third-party |
构建维护脚本、内置配置与第三方声明材料 |
harness/remote |
远程工作区联调用的 SSH Docker 镜像 |
ZCodium 新增的内容:
| 路径 | 职责 |
|---|---|
.agents/specs/ |
能力补全的 spec:范围、状态所有者、接口契约与验收场景 |
.agents/skills/ |
编码代理技能:架构治理、Electron、React 等 |
apps/zcode-cli/packages/*-plugin |
内置插件与技能源码 |
apps/zcode-cli/tools/repo-snapshot-parody/ |
仓库快照上传的 localhost 复现,仅用于审计对照 |
docs/ |
GitHub Pages 落地页 |
编码约定、开工前基线检查与各领域规范见 AGENTS.md;插件商店领域词汇见 CONTEXT.md,UI 设计规范见 DESIGN.md。
磁盘上的 astrbot-zcodium-plugin/ 是配套 AstrBot 插件的独立仓库工作副本,不在本仓库版本控制内,克隆本仓库不会得到它。
功能与优惠范围、维护规则、执行与数据风险,以及许可和第三方版权说明,详见 NOTICE.md。