# ZCode 是什么

> 智谱的 AI 编程工作台：桌面应用、Web 与终端三种形态，Coding Plan 登录与自带模型，命令行子命令、权限模式、斜杠命令与快捷键，数据放在哪里，以及它和 Claude Code、Codex、OpenCode 的兼容之处。

- 作者：David（道雾轩）
- 专栏：ZCode 源码解读（https://daiw.org/manual/zcode.md）
- 最后更新：2026-09-21
- 原文：https://daiw.org/manual/zcode/what-is-zcode
- 转载与引用：请注明出处并附原文链接（https://daiw.org/about/copyright）

README 开篇只用一句话介绍 ZCode（`README.md:14`）：

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

“工作台”这个词很准确：它首先是一个带图形界面的桌面产品，终端里的 `zcode` 既是一种独立用法，也是桌面端和 Web 背后真正干活的 Agent。这一篇先把它当成产品来看——有哪几种形态、怎么登录、模型从哪来、有哪些命令和快捷键、数据放在哪。实现细节留给后面各篇。

## 仓库与版本

- 仓库是 `zai-org/ZCode`，2026-09-21 以一个“feat: open source”提交整体公开，之前只有一个空的初始提交。产品版本 `3.14.0`，Agent CLI 版本 `0.16.9`。
- 第一方代码是 Apache-2.0。根目录的 `NOTICE.md` 提醒，受第三方许可与再分发条件约束，开源版“不承诺提供官方产品的全部功能及活动政策”（`NOTICE.md:70`）——最明显的例子是 Computer Use：仓库里的 `@zcode/zcode-cua` 只是占位实现，调用一律返回不可用。
- 官方站点是 `zcode.z.ai`：Web 版会话分享页里的下载链接就指向它（`packages/web/src/share/ConversationShareLandingPage.tsx:91`），产品文档地址是 `https://zcode.z.ai/docs`（`packages/ui/src/lib/productDocs.ts:2`）。

## 三种形态

README 把入口分成三类（`README.md:16`）：

| 形态 | 是什么 | 从源码启动 |
| --- | --- | --- |
| Desktop | Electron 桌面应用，完整的图形工作台：会话列表、文件树、Git、内嵌浏览器、终端、定时任务 | `pnpm dev:desktop` |
| Web / ZCode 命令行版 | 一个发行包里装着 TUI、Web 前端、后端和 Agent；`zcode` 进 TUI，`zcode --web` 在本机起 Web 服务 | `pnpm dev:web` |
| Agent CLI | 终端里的 `zcode`，同时也是 Desktop 与 Web 背后的 Agent 运行时 | `pnpm --filter @zcode/cli dev` |

前两种是给最终用户的形态，第三种是开发者视角：发行包里的 `zcode` 命令其实是一个薄薄的分流脚本，第一个参数是 `--web` 就启动 Web 服务，否则把全部参数原样交给 Agent CLI（`scripts/zcode-distribution/runner.mjs:256`）。Web 模式默认只监听 `127.0.0.1`、自动挑空闲端口并打开浏览器；改成监听非本机地址时会默认生成访问令牌（`README.md:103`），细节见 [Web 与服务端](https://daiw.org/manual/zcode/server-web)。

安装方面，开源仓库没有提供现成的公共下载地址：`pnpm build:zcode` 打出的发行包带 `install.sh`，要求打包前用 `ZCODE_DIST_BASE_URL` 指定托管位置；安装脚本把运行包放进 `~/.zcode/runtime`，在 `~/.local/bin` 建 `zcode` 命令（`README.md:185`）。README 还顺带提到“旧 Lite 用户”要改用新的安装脚本，说明命令行版此前有过一个叫 Lite 的前身（`README.md:187`）。

## 登录与模型

ZCode 默认接智谱自家的 GLM Coding Plan，账号分两个区域：面向海外的 Z.ai 与面向国内的 BigModel（智谱开放平台）。命令行里：

```bash
zcode login            # 默认 zai
zcode login bigmodel
zcode login --no-browser   # 只打印授权地址，不自动打开浏览器
```

`login` 只接受 `zai` 与 `bigmodel` 两个参数（`apps/zcode-cli/packages/cli/src/login-command.ts:15`），走浏览器授权并轮询结果，成功后打印凭据文件与模型选择配置的路径。TUI 里的 `/login` 更灵活：不带参数弹出 Coding Plan 的配置选择，也可以直接传 API Key 走手动模式（`packages/shared/src/zcode-slash-command-help.ts:28`）。

模型目录来自随包分发、可远程更新的内置规则集 `config/provider/zcode-builtin.json`。按账号分，有个人 Coding Plan、团队 Coding Plan、Start Plan，以及隐藏的闲时计划（Idle plan），内置模型是 GLM-5.3、GLM-5.3-Flash、GLM-5.2、GLM-5-Turbo 这几档；按 API Key 接入，模板里还有 Kimi、MiniMax、DeepSeek、阿里云百炼、Xiaomi MiMo、OpenAI、Anthropic、xAI、OpenRouter 与 OpenCode Go/Zen 等十几家。协议形态只有三种：`anthropic-messages`、`openai-chat-completions` 与 `openai-responses`。会话里用 `/model` 换模型、`/effort` 调推理强度。规则集怎样组织、模型选项怎样翻译成各家参数，见 [Provider 规则](https://daiw.org/manual/zcode/provider-config)；账号与各档计划见[账号、Coding Plan 与闲时计划](https://daiw.org/manual/zcode/accounts-plans)。

## 命令行

不带子命令直接运行 `zcode`，就是打开全屏 TUI；想不开界面跑一句提示词要用 `-p`，写成 `zcode "修个 bug"` 会被当成未知子命令（`apps/zcode-cli/packages/cli/src/run.ts:570`）。子命令在 `run.ts:518` 的 `switch` 里分派：

| 子命令 | 作用 |
| --- | --- |
| `tui` | 打开终端界面（默认） |
| `login [zai\|bigmodel]`、`logout` | 浏览器授权登录；删除共享的登录凭据 |
| `plugins`（别名 `plugin`） | 插件与市场：`list`、`install`、`uninstall`、`enable`、`disable`、`update`、`validate`、`marketplace` |
| `skills`、`commands` | 列出（`list`，缺省）或查看（`inspect <name>`）本地技能与自定义斜杠命令 |
| `hooks trust …` | 审查、授予、撤销工作区钩子的信任 |
| `doctor` | 打印版本、Node、平台、是否 SEA 单文件等运行时信息 |
| `app-server`、`agent-server` | 以 ZCode Protocol stdio 服务端运行，给桌面端与 Web 服务端拉起用 |
| `version`、`help` | 版本与帮助 |

常用的全局选项：

| 选项 | 作用 |
| --- | --- |
| `-p, --prompt <text>` | 不开 TUI，单次执行一个提示词；未指定 `--mode` 时权限模式默认 `yolo` |
| `--output-format text\|json\|stream-json` | 无头运行的输出格式；`stream-json` 会把每个会话事件按行输出 |
| `--target <text>` | 无头运行一个目标，等价于 `-p "/goal <text>"`；`--target-replace` 替换已有目标 |
| `-c, --continue`、`--resume <sessionId>` | 继续当前目录最近的会话，或按 ID 恢复会话 |
| `--mode build\|edit\|plan\|yolo` | 本次运行的权限模式 |
| `--attach <path>` | 给 `-p` 附加本地文件，可重复 |
| `--disallowed-tools <tools...>` | 本次运行移除整个工具，例如 `"Bash Edit"` |
| `--browser-use headless` | 用无头浏览器提供 Browser Use |
| `--cwd <path>`、`--locale`、`--json`、`--verbose` | 工作目录、界面语言、机器可读输出、诊断信息 |

有两处与帮助文本对不上：`zcode --help` 的文案（`apps/zcode-cli/packages/i18n/src/locales/zh-CN.ts:10`）没有列出 `hooks`、`agent-server` 两个子命令和 `--output-format` 选项，但它们在 `run.ts` 里都实实在在地实现了（`run.ts:306`、`run.ts:525`、`run.ts:119`）。完整的路由与无头模式流程见[命令行入口、无头模式与打包](https://daiw.org/manual/zcode/cli-surface)。

## 权限模式

四种模式决定 Agent 调工具时要不要问你：

| 模式 | 大意 |
| --- | --- |
| `build` | 共享运行配置的默认模式：只读工具直接放行，高风险与有副作用的操作要确认 |
| `edit` | 在 `build` 的基础上，工作区内的文件编辑直接放行 |
| `plan` | 只读规划：只放行只读工具与不具破坏性的 MCP 工具，其余一律拒绝 |
| `yolo` | 跳过权限询问；`-p` 无头运行的默认值 |

`NOTICE.md` 专门提醒了默认值的差别：“共享运行配置默认采用 `build` 权限模式；独立 CLI 通过 `--prompt` 执行非交互任务时，未指定 `--mode` 会采用 `yolo`”（`NOTICE.md:11`，对应 `run.ts:42`）。即使在 `yolo` 下，需要用户交互的工具和声明了“总要确认”的工具仍然会问（`apps/zcode-cli/packages/core/src/permission/service.ts:112`）。TUI 里 `Shift+Tab` 轮换模式，`/mode` 查看或指定。四种模式的精确语义与规则语法，见[权限模式与规则](https://daiw.org/manual/zcode/permission)。

## 斜杠命令

内置斜杠命令登记在 `BUILTIN_ZCODE_SLASH_COMMAND_HELP_ENTRIES`（`packages/shared/src/zcode-slash-command-help.ts:9`），共 19 个：

| 用途 | 命令 |
| --- | --- |
| 会话 | `/new`（别名 `/clear`）、`/resume`（别名 `/continue`）、`/fork`、`/rewind`、`/compact [instructions]` |
| 模型与账号 | `/model`、`/effort`（别名 `/variant`）、`/login`、`/logout` |
| 工作方式 | `/mode`、`/goal`（别名 `/target`）、`/expert`、`/dwf` |
| 扩展 | `/skill`、`/plugins`（别名 `/plugin`）、`/mcp`、`/init` |
| 界面与帮助 | `/locale`（别名 `/language`）、`/help` |

几个值得一提：`/init` 让 Agent 检查工作区、创建或更新根目录的 `AGENTS.md`，并提醒已有文件要改而不是覆盖（`zcode-slash-command-help.ts:45`）；`/goal` 给会话设一个目标，Agent 会一直做到它判定完成为止（[目标模式](https://daiw.org/manual/zcode/goal-target)）；`/expert` 启动固定八阶段的专家工作流，`/dwf` 管理动态工作流的运行（[专家工作流](https://daiw.org/manual/zcode/expert-workflow)、[动态工作流](https://daiw.org/manual/zcode/dwf-tools)）。桌面端的输入框还多一个 `/plan`，只在 App 里出现（`apps/zcode-cli/packages/bootstrap/src/slash-command-surface.ts:10`）。`--help` 文案里的斜杠命令表只列了其中 15 个，漏了 `/init`、`/effort`、`/locale`、`/plugins`。

## 快捷键

TUI 的按键处理集中在 `apps/zcode-cli/packages/tui/src/app-keyboard.ts`，常用的几个：

| 按键 | 作用 |
| --- | --- |
| `Enter` | 发送；`Shift+Enter` 换行（`app-input-pane.tsx:35`） |
| `Shift+Tab` | 轮换权限模式（`app-keyboard-helpers.ts:73`） |
| `Tab` | 补全斜杠命令，以及 `/model`、`/effort`、`/mode` 的候选 |
| `Esc` | 关掉候选面板；都没有时中断正在进行的输出 |
| `Ctrl+C` | 有选中文本时复制，有草稿时清空草稿；2 秒内连按两次退出（`app-keyboard-helpers.ts:102`） |
| `Ctrl+U` | 清空草稿与附件 |
| `Ctrl+V` | 粘贴剪贴板里的图片 |
| `↑`、`↓` | 草稿为空时翻看输入历史 |
| `Ctrl+X` 后接 `B`、`M`、`A` | 两秒内按：显示或隐藏侧边栏、展开改动文件、展开 API 区（`app-sidebar-shortcut.ts:2`） |
| `+`、`-` | 草稿为空时展开或收起全部工作流卡片 |

完整的键位表与界面结构见[终端界面](https://daiw.org/manual/zcode/tui)。

## 数据放在哪

独立 CLI 的数据都在用户主目录下的 `~/.zcode`：

| 位置 | 内容 |
| --- | --- |
| `~/.zcode/cli/config.json` | 用户主配置：MCP、钩子、插件、功能开关等（`apps/zcode-cli/packages/adapters/src/config/config-factory.ts:37`） |
| `~/.zcode/cli/db/db.sqlite` | 会话库，用 Node 内置的 `node:sqlite`（[SQLite 会话库](https://daiw.org/manual/zcode/session-store)） |
| `~/.zcode/cli/log` | 日志（`apps/zcode-cli/packages/adapters/src/logging/index.ts:223`） |
| `~/.zcode/cli/rollout` | 模型输入输出记录，开发态写到 `debug`（`apps/zcode-cli/packages/adapters/src/model/runner-debug.ts:590`） |
| `~/.zcode/cli/plugins`、`~/.zcode/cli/workflows` | 插件缓存与数据、工作流 |
| `~/.zcode/v2/credentials.json` | 共享的登录凭据，`ZCODE_DATA_BASE_DIR` 可以换基目录（`apps/zcode-cli/packages/adapters/src/auth/shared-credentials.ts:289`） |
| `~/.zcode/AGENTS.md` | 用户级的默认指令（`apps/zcode-cli/packages/adapters/src/context/index.ts:237`） |

项目里则认 `.zcode/` 目录：`.zcode/config.json` 是工作区配置，`.zcode/agents` 放自定义子 Agent，`.zcode/workflows` 放工作流；技能目录除了 `.zcode/skills` 也认 `.agents/skills`（`apps/zcode-cli/packages/adapters/src/skills/roots.ts:102`）。`NOTICE.md` 第三节还提醒了两件容易忽略的事：模型输入输出日志在开发和生产运行中默认写到本地，可能含提示词与代码；CLI 的共享凭据文件虽然加密，默认密钥却可以从本机环境信息派生（`NOTICE.md:62`、`NOTICE.md:64`）。

## 和其他产品的关系

ZCode 的 Agent 循环、工具与终端界面都是自己写的，但在格式上主动向几家主流产品靠拢：

- **Claude Code**：生命周期钩子的七个事件名——`SessionStart`、`UserPromptSubmit`、`PreToolUse`、`PermissionRequest`、`PostToolUse`、`PostToolUseFailure`、`Stop`——与 Claude Code 一致（`apps/zcode-cli/README.md`，[生命周期钩子](https://daiw.org/manual/zcode/hooks)）；插件除了自己的 `.zcode-plugin/plugin.json`，也认 `.claude-plugin/plugin.json` 与 Claude 的插件市场文件（`apps/zcode-cli/packages/adapters/src/plugins/index.ts:101`）；桌面端能扫描 `~/.claude/projects`，把 Claude Code 的历史会话导入进来（`packages/services/src/session/claude-native/claudeNativeSessionImportRepo.ts:63`）。
- **Codex**：插件清单同样认 `.codex-plugin/plugin.json`（`adapters/src/plugins/index.ts:102`）。
- **OpenCode**：终端界面基于 OpenTUI 的 React 渲染，Provider 模板里也有 OpenCode Go 与 OpenCode Zen。
- **AGENTS.md**：指令文件默认只认 `AGENTS.md`（`apps/zcode-cli/packages/adapters/src/context/index.ts:24`），不读 `CLAUDE.md`。

下一篇：[仓库全景：两层 workspace 与依赖方向](https://daiw.org/manual/zcode/monorepo-map)——三十多个包各管什么、规模多大，产品一侧与 Agent 一侧为什么只靠一条进程边界相连。