# ZCode CLI 使用指南

本指南面向从开源仓库构建 CLI 的使用者，重点介绍非交互调用、扩展配置和任务评测。无参数启动的 TUI 也可用于交互操作。本文随源码维护；不要仅凭 `0.16.x` 版本号判断两个构建的能力相同。

## 从哪里开始

1. [快速开始](01-quickstart.md)：源码构建、可执行文件、自检和第一次调用。
2. [命令行参考](02-cli-reference.md)：参数、输出格式和退出码。
3. [配置](03-config.md)：运行配置、个人模型配置、旧配置迁移和环境变量。
4. [工具与评测配置](04-tools.md)：工具可见性、非交互限制和评测边界。
5. [权限](05-permissions.md)：权限模式、拒绝行为和执行证据。
6. [会话](06-sessions.md)：新建、恢复、目标、用量和持久化。
7. [MCP](07-mcp.md)：连接外部工具服务。
8. [Skills](08-skills.md)：技能发现、调用和自定义命令。
9. [Hooks](09-hooks.md)：生命周期脚本与工作区信任。
10. [Plugins](10-plugins.md)：安装、市场、本地插件和数据目录。
11. [指令与记忆](11-memory.md)：`AGENTS.md`、记忆隔离与提取。
12. [排障](12-troubleshooting.md)：启动、配置、权限和输出问题。
13. [批量任务与运行记录](13-automation.md)：可复现运行、结果判定和轨迹导出。

## 版本与验证

每次运行至少保存 `zcode --version`、`zcode doctor --json`、构建提交号或二进制 SHA-256。记录插件版本、模型 ID、模型配置和任务工作区。模型目录或插件市场可能独立更新，因此相同 CLI 版本不等于相同运行条件。

本指南描述当前源码接口。旧构建可能缺少 `--workflow-mode`，或仍使用旧模型配置。先用对应章节的小型自检确定能力；`--help` 可能没有展示解析器支持的全部参数，不能只靠帮助文本判定。

本次核对日期为 2026-10-14。具体验证范围和未验证项见[运行记录](13-automation.md#验证范围)。

## 开源构建的范围

源码构建需要本仓库的 workspace 依赖和运行资源。不要只复制 `zcode.cjs` 就假设插件、模型配置和原生工具资源齐全。Computer Use 在开源导出中使用占位实现，不能据此宣称开源构建具备完整的原生桌面控制能力。Browser Use 是独立能力，仍需可用的 Chrome/Chromium 和对应插件。

示例中的服务地址、API Key、模型 ID 和绝对路径必须换成自己的值。示例不会提供可用凭据。通用模型接口配置与账号登录是不同入口，应按实际使用的 provider 选择。