AI 编程工具太多切来切去太累?| 开源工作台 ZCode:桌面、Web、终端三端一体的 Agent 开发环境(附初始化与打包全

一、痛点与破局

你是否也有这样的体验：写代码时想在终端里让 AI Agent 改代码，切到桌面应用看 Diff，又想偶尔在浏览器里远程操作服务器上的项目——于是装了三四个工具，配置散落各处，会话数据互不相通，别提多累了。

更难受的是，很多 AI 编程工具是黑盒：想定制 Provider、想自己部署后端、想把 Agent 嵌进自己的工作流？对不起，源码不开放。

ZCode 就是为解决这些问题而生的开源 AI 编程工作台。它一句话概括：桌面应用 + 浏览器界面 + 终端 Agent 三端一体，客户端、后端服务、共享 UI，以及 Agent CLI 与运行时源码全部开源。目前最新版本为 v3.14.3，社区覆盖飞书社群与 Discord。

二、核心功能深挖

1. 三端统一体验，一套代码全打通

ZCode 的命令行发行包包含 TUI、Web 和 Agent，统一用 zcode 命令启动：无参数进入 TUI，--web 启动浏览器界面，其他参数交给 Agent CLI 处理。两种模式都在本机运行，无需 Electron。这意味着：

• 本地开发：终端里直接 TUI 交互；
• 图形化操作：zcode --web 打开浏览器界面；
• 远程场景：Web 模式支持 --host 0.0.0.0 局域网访问，非本机监听时默认自动生成访问令牌，安全不裸奔。

2. 清晰的 Monorepo 架构

ZCode 采用 pnpm workspace 管理，仓库职责划分非常干净：

想给 Agent 加自定义工具链？改 apps/zcode-cli；想换模型 Provider？改 packages/provider。每一层都能定制，这才是开源工作台该有的样子。

3. 远程开发支持（SSH/WSL）

针对远程工作区场景，ZCode 提供了完整的开发链路：开发态资源取自本地 packages/desktop/mock-cdn 和本地构建产物，经 SFTP 上传到远程，不依赖外部 CDN。连接远程项目时资源选择「本地下载后上传」即可。

4. 灵活的配置体系

根目录 .env.example 提供服务地址与构建配置示例，本地覆盖放 .env.local。核心环境变量一览：

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

三、实战演示

环境准备

需要 Git、Node.js 24.14.0、pnpm 10.33.2（版本以仓库的 mise.toml 为准）。Agent CLI 源码在 apps/zcode-cli/，随仓库一起克隆，无需单独拉取 submodule。

初始化

pnpm bootstrap

这一条命令会安装 workspace 依赖、准备桌面本地运行资源，再执行 build:bootstrap。其他常用入口：

pnpm install                  # 仅安装依赖pnpm prepare:desktop-runtime  # 准备桌面运行资源pnpm prepare:remote-assets    # 单独准备远程资源pnpm bootstrap:with-remote    # 含远程资源的完整初始化pnpm build                    # 递归构建各 workspace 包

本地开发

桌面版：

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

需要独立数据目录时（macOS / Linux）：

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 请求自动代理到本地后端。

命令行版使用：

zcode                                  # 默认进入终端交互界面zcode --web                            # 启动 Web 界面zcode --web --workspace /path/to/project --port 3030 --no-openzcode --help                           # 查看参数

打包发行

桌面版打包：

pnpm bundle:desktop# 指定目标平台与架构，--os 支持 mac/win/linux，--arch 支持 x64/arm64pnpm bundle:desktop -- --os win --arch x64

默认输出到 packages/desktop/dist/。本地构建未签名，macOS 首次打开被拦截时执行：

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

命令行版打包：

# 打包前必须设置下载根地址（也可放在 .env 中）pnpm build:zcode --base-url https://downloads.example.com/zcode/# 仅重新组包，复用已有构建产物pnpm build:zcode --skip-build

产物输出到 dist/zcode/，包含 releases/<version>/zcode-<version>.tar.gz 运行包、sha256.txt 校验摘要、latest.json 版本索引和 install.sh 安装脚本。本地调试可直接解压运行：

zcode_version=$(node -p "require('./dist/zcode/latest.json').version")mkdir -p dist/zcode/debugtar -xzf "dist/zcode/releases/$zcode_version/zcode-$zcode_version.tar.gz" \  -C dist/zcode/debug# 启动 TUInode dist/zcode/debug/zcode/bin/zcode.mjs# 启动 Webnode dist/zcode/debug/zcode/bin/zcode.mjs --web \  --workspace "$PWD" --port 3030 --no-open

四、避坑指南与总结

几个容易踩的坑提前告诉你：

• 版本敏感
  ：Node.js 必须是 24.14.0、pnpm 必须是 10.33.2，以 mise.toml 为准，版本不对大概率初始化失败；
• 命令行版构建前置条件
  ：打包前必须设置 ZCODE_DIST_BASE_URL（或用 --base-url 传入）；pnpm build:zcode 只生成发行包，不会替换 PATH 中已有的 zcode，可用 command -v zcode（macOS/Linux）或 where.exe zcode（Windows）排查；
• 老用户注意
  ：旧 Lite 用户需改用新的构建命令与安装脚本，新安装不会删除旧目录，也不会迁移已有会话数据；
• 端口冲突
  ：Web 验证默认用 3030 端口，如果 pnpm dev:web 正在运行，记得换 --port。

适用人群：想私有化部署 AI 编程环境的团队、需要定制 Agent 工具链或自有模型 Provider 的开发者、以及在终端 / 桌面 / 浏览器多场景切换的重度 AI 编程用户。功能范围、维护规则与数据风险详见项目的 NOTICE.md，上手前建议先读一遍。

项目地址可在 GitHub 搜索 ZCode，社区支持飞书社群与 Discord，感兴趣的同学赶紧去 Star 一下吧！