ZCode 是什么

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

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 与服务端。

安装方面，开源仓库没有提供现成的公共下载地址：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（智谱开放平台）。命令行里：

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 规则；账号与各档计划见账号、Coding Plan 与闲时计划。

命令行

不带子命令直接运行 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）。完整的路由与无头模式流程见命令行入口、无头模式与打包。

权限模式

四种模式决定 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 查看或指定。四种模式的精确语义与规则语法，见权限模式与规则。

斜杠命令

内置斜杠命令登记在 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 会一直做到它判定完成为止（目标模式）；/expert 启动固定八阶段的专家工作流，/dwf 管理动态工作流的运行（专家工作流、动态工作流）。桌面端的输入框还多一个 /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`）
`+`、`-`	草稿为空时展开或收起全部工作流卡片

完整的键位表与界面结构见终端界面。

数据放在哪

独立 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 会话库）
`~/.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，生命周期钩子）；插件除了自己的 .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 与依赖方向——三十多个包各管什么、规模多大，产品一侧与 Agent 一侧为什么只靠一条进程边界相连。

本页目录