ZCode CLI 与终端界面（TUI）

CLI 位于 apps/zcode-cli/packages/cli，TUI 位于 apps/zcode-cli/packages/tui。zcode 二进制入口按参数分为 TUI、headless 与协议服务三种形态。

进程入口

cli/src/main.ts:16 是进程级入口：在加载 bootstrap/provider 之前完成 env 清洗、SEA runtime tools、plugin-host 短路、TUI/protocol stderr 隔离、console 重定向、错误和退出生命周期。
cli/src/index.ts 只导出 run。

命令分发

cli/src/run.ts 是分发核心：

zcode 无位置参数时 commandName() 默认为 tui（run.ts:70）；zcode tui 是显式别名。
分派顺序（run.ts:519 附近）：
1. --prompt / -p → headless runPrompt
2. --target → /goal headless
3. tui → runTuiCommand
4. app-server / agent-server → runZCodeProtocolCommand
5. 其余为 doctor / login / logout / commands / plugins / skills 等

注意：在当前 v3.15.1 检出中，CLI 本身没有 --web 选项，--surface 只支持 terminal 和 desktop（映射 zcode_desktop）。--web 是顶层 distribution 统一发行包 bin/zcode.mjs 的 launcher 分流概念，不是 Agent CLI 自身参数。

Headless 输出

cli/src/prompt-command.ts:51 支持三种输出：

text
json
stream-json：每行一个映射后的 SessionEvent，最后一行是 type:"result" 终态

TUI

TUI 是 OpenTUI renderer + React app：

入口 tui/src/tui.tsx:13；App 状态边界 tui/src/app.tsx:48。
TUI 只维护展示态：草稿、焦点、滚动、选择、弹窗。
真实 runtime/session/model/tool/permission 状态通过 subscribeSessionEvents 和显式 prompt callbacks 进入 TUI（见 session-runtime）。
cli/src/tui-stderr.ts:11 负责 TUI 判断与 stderr 隔离。

内置 slash command

cli/src/command-center/slash-commands.ts:40：

/compact  /expert  /effort  /dwf     /fork   /help   /init
/workflow /login   /logout  /locale  /resume /new    /rewind
/mode     /mcp     /plugins /model   /goal   /skill

CLI 配置（MCP / Hooks）

CLI 从主 JSON 配置读取 MCP 与 Hooks，默认用户配置路径 ~/.zcode/cli/config.json：

MCP：mcp.servers，类型 stdio / http / sse，工具暴露为 mcp__<server>__<tool>；会话内用 /mcp list|status|connect|disconnect 管理。详见 mcp-integration。
Hooks：hooks.enabled（默认 false）+ hooks.events，支持 SessionStart、UserPromptSubmit、PreToolUse、PermissionRequest、PostToolUse、PostToolUseFailure、Stop。Hook 为进程型（argv 执行，非 shell 字符串），可与 Claude Code hooks 兼容。

插件与技能命令

zcode plugins list
zcode plugins enable ios-simulator
zcode plugins disable browser-use

插件状态在 ~/.zcode/cli/plugins：cache/（安装代码）、data/<plugin-id>/（持久数据）、marketplaces/zcode-plugins-official/。详见 plugin-system。

打包

默认产物是普通 Node CLI bundle dist/zcode.cjs（运行时零生产依赖，用 Node 内建做参数解析与终端控制）。
SEA 是可选打包路径：pnpm --dir apps/zcode-cli build:sea（6 target，postject 注入 SEA blob）。SEA 失败时普通 CLI 仍是 fallback。详见 distribution。

源码开发

pnpm --filter @zcode/cli dev --help
pnpm --filter @zcode/cli dev
pnpm --filter @zcode/cli... build
node apps/zcode-cli/packages/cli/dist/zcode.cjs --help

CLI 子库有独立的 typecheck / lint / test；上游 AGENTS.md 明确 CLI 变更不能用根 test:unit:affected 代替。

Wiki AI

目录