← Discover MCPs and Agents
Z
MCPAI & MLGitHub

ZCode

Z.ai's coding agent harness. Powerful, intelligent, extensible.

Links

Repository

README

From the repo.

ZCode

ZCode

飞书社群 · Discord

简体中文 | English

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

更新

  • 2026-9-23：更新至 ZCode v3.14.3 版本。

初始化

准备 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。

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

命令用途
pnpm install安装依赖
pnpm prepare:desktop-runtime准备桌面运行资源，默认包含远程资源准备
pnpm prepare:remote-assets单独准备远程运行资源
pnpm bootstrap:with-remote初始化依赖、本地与远程资源，并串行构建相关包；跳过桌面应用 bundle
pnpm build递归执行各 workspace 包的构建脚本，包括包内的资源准备步骤

默认 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

远程功能（SSH/WSL）

先执行 pnpm bootstrap:with-remote 准备远程资源（mock-cdn），再 pnpm dev:desktop；连接远程项目时资源选择「本地下载后上传」。开发态资源取自本地 packages/desktop/mock-cdn 和本地构建产物，经 SFTP 上传到远程，不访问 CDN。

Web 开发

修改 Web 或后端源码时，使用开发模式：

pnpm dev:web

# 指定后端工作区（macOS / Linux）
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 并重启服务。需要验证完整发行包时，按下方“ZCode 命令行版”打包章节解压运行。

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 --help

Web 模式默认工作目录为当前目录，监听 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 检查。

CLI 源码开发

直接开发 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。

配置

根目录 .env.example 提供服务地址与构建配置示例，可按需复制到 .env，本地覆盖放入 .env.local。Desktop 的开发环境通过 dev:desktop:test / dev:desktop:prod 选择。

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

运行时变量可在启动命令的环境中显式设置。随客户端发布的默认配置见 config/README.md。

打包

第三方声明生成、发行校验流程及声明在发行物中的位置见 third-party/README.md。

桌面版

pnpm bundle:desktop

# 指定目标平台与 CPU 架构
pnpm bundle:desktop -- --os win --arch x64

pnpm bundle:desktop -- --help

默认目标为 macOS arm64，默认输出目录为 packages/desktop/dist/。--os 支持 mac、win、linux，--arch 支持 x64、arm64；实际打包与签名需要目标平台对应的工具和配置。

安装：双击打开产物 DMG，将 ZCode 拖入"应用程序"。本地构建未签名，首次打开若被 macOS 拦截，执行：

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

ZCode 命令行版

构建入口为 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：版本索引和安装脚本。

完整目录可上传到配置的下载根地址。安装脚本从该地址下载运行包，默认安装到 ~/.zcode/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/desktopElectron Main、Host、Renderer 与桌面打包
packages/webWeb 客户端
packages/serverHTTP / 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-nodeProvider 公共能力与 Node 实现
apps/zcode-cliAgent CLI、TUI、运行时与工具
scripts、config、third-party构建维护脚本、内置配置与第三方声明材料

项目声明

功能与优惠范围、维护规则、执行与数据风险，以及许可和第三方版权说明，详见 NOTICE.md。

Collected info

  • ★ 6,724 stars
  • ⎇ 2,007 forks
  • Language: TypeScript
  • Source updated: 9/25/2026

Config for your environment

Replace {MCP_ENDPOINT_URL} with this MCP’s endpoint URL (from its repo or docs above). No API key — you connect directly.

Tool

OS

Config file: ~/.cursor/mcp.json

{
  "mcpServers": {
    "mcp-server": {
      "url": "{MCP_ENDPOINT_URL}"
    }
  }
}

Paste into mcpServers in the config file. Restart Cursor after saving.

If this MCP is also published on mcpchannel.ai, you can subscribe from Browse and use the gateway config there instead.