ZCode

让 AI 智能体自主写代码、跑命令、改工程

开源 unknown 编程开发

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 7645

维护状态活跃

是否开源是

定价模式 unknown

项目预览

项目数据

分类编程开发

开发团队zai-org

所属国家

官网地址https://zcode.z.ai

GitHubhttps://github.com/zai-org/ZCode

定价模式unknown

价格说明定价信息待确认

访问状态

是否开源是

开源协议Apache-2.0

主要语言TypeScript

技术栈/模型

GitHub 星标★ 7645

30天Star增速

HF 下载量

上线时间2026-09-20 00:00:00

代码更新—

仓库体积—

本站数据更新—

维护状态活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-10-11

浏览次数0

项目介绍

ZCode 是 Z.ai 推出的编码智能体（coding agent）框架，用 TypeScript 编写。它要解决的问题是：让大模型不只是补全代码，而是能像真正的工程师一样自主完成开发任务。核心能力包括智能体编排（agent harness），即把模型、工具调用、文件读写、终端执行、上下文管理等环节串成一条可扩展的流水线，开发者可以接入不同模型、注册自定义工具、定义工作流。相比只做单点补全的插件，ZCode 更像一个可编程的自动化开发底座，适合把重复性的编码、调试、重构任务交给智能体执行，同时保留人工干预和扩展空间。项目星标约 7600，处于成长阶段，定位偏向开发者基础设施而非终端产品。

Star 增长趋势

本站每日记录该项目 GitHub 星标变化，观测越久曲线越完整

正在加载星标数据…

技术标签

使用教程

—

难度：进阶约 30 分钟部署方式：命令行工具 6 步

环境要求

Git（克隆仓库用）
Node.js 24.14.0（版本以仓库 mise.toml 为准）
pnpm 10.33.2
本地需保留空闲端口 3030（Web 模式使用）

安装与启动步骤

1准备环境并克隆仓库

先安装 Git、Node.js 24.14.0 与 pnpm 10.33.2，版本以仓库 mise.toml 为准，随后克隆仓库。下述所有开发与打包命令都在仓库根目录执行。
```
git clone https://github.com/zai-org/ZCode.git
cd ZCode
```
2初始化依赖

pnpm bootstrap 会安装 workspace 依赖、准备桌面本地运行资源，再执行 build:bootstrap。默认跳过远程资源准备，适合本地桌面开发。
```
pnpm bootstrap
```
3启动桌面开发环境

启动脚本会先准备本地运行资源、构建桌面 Agent，再启动 Electron 和源码监听。dev:desktop 默认等同 dev:desktop:prod（生产服务配置）。
```
pnpm dev:desktop:test
```
4构建并启动 Agent TUI

在已配置 ZCODE_DIST_BASE_URL 的前提下执行构建，然后直接运行产物启动终端 TUI 界面。
```
pnpm build:zcode
node dist/zcode/debug/zcode/bin/zcode.mjs
```
5以 Web 模式运行 Agent

用同一产物托管 Web 页面，指定工作区与端口并关闭自动打开浏览器。端口需空闲，若在跑 pnpm dev:web 请换端口。
```
node dist/zcode/debug/zcode/bin/zcode.mjs --web --workspace "$PWD" --port 3030 --no-open
```
6启动 Web 界面

已安装 zcode 命令时，可直接用 --web 参数启动 Web 界面，无需手动指定构建产物路径。
```
zcode --web
```

关键配置

配置项	必填	说明	示例
`ZCODE_DATA_BASE_DIR`	否	应用数据基目录，数据写入其下的 .zcode/	`$HOME/.zcode-dev-home`
`ZCODE_SERVER_WORKSPACE`	否	Web 后端的工作区路径	`/your/workspace`
`ZCODE_BUILTIN_PROVIDER_CONFIG_FILE`	否	本地 Provider 配置文件路径，未设置时使用内置配置	`/your/path/provider.json`
`ZCODE_DIST_BASE_URL`	否	命令行安装脚本使用的下载根地址	`https://your-cdn.example.com/zcode`

如何确认成功

浏览器打开 http://127.0.0.1:3030，能同时访问 Web 页面并驱动 Agent，即说明后端服务链路正常。

常见问题

Q：bootstrap 和 bootstrap:with-remote 有什么区别？

A：默认 pnpm bootstrap 跳过远程资源准备，适合本地桌面开发；使用远程工作区或验证远程发行资源时，改用 pnpm bootstrap:with-remote。

Q：端口 3030 被占用怎么办？

A：换用其他端口，例如在启动命令中写成 --port 3031。若正在运行 pnpm dev:web，也需要改用别的端口避免冲突。

Q：Agent CLI 需要单独拉取或初始化 submodule 吗？

A：不需要。Agent CLI 与运行时源码位于 apps/zcode-cli/，作为普通目录随仓库一起克隆。

Q：想用独立的开发数据目录怎么设置？

A：在启动命令前设置 ZCODE_DATA_BASE_DIR，例如 ZCODE_DATA_BASE_DIR="$HOME/.zcode-dev-home" pnpm dev:desktop:test。

Q：pnpm dev:desktop 用的是哪套服务配置？

A：pnpm dev:desktop 默认等同于 pnpm dev:desktop:prod，使用生产服务配置；需要测试配置时用 dev:desktop:test。

注意事项

所有开发和打包命令均在仓库根目录执行。
根目录 .env.example 提供服务地址与构建配置示例，可复制为 .env，本地覆盖写入 .env.local。
pnpm build 会递归执行各 workspace 包的构建脚本，包含包内资源准备步骤。
Desktop 的开发环境通过 dev:desktop:test / dev:desktop:prod 选择。

核心亮点

提供 agent harness 抽象层，模型、工具、上下文可插拔，便于二次开发
TypeScript 实现，与前端/Node 生态无缝集成，调试和扩展成本低
支持自主执行终端命令与文件操作，能完成端到端开发任务而非仅补全

不足之处

项目较新，文档与最佳实践积累有限
生态和第三方工具集成数量尚在成长中

适用场景

批量重构遗留代码库，让智能体自动改文件并跑测试
搭建企业内部编码助手，接入私有模型和自研工具链
自动化处理 issue：读需求、改代码、提 PR 的流水线

替代项目

OpenHands、Aider

上一篇：gentle-ai

下一篇：awesome-cli-coding-agents