Zero CLI：check、run、build、test、fix 与 explain

CLI 能为你做什么

zero 这个二进制文件就是全部的开发工具链。没有单独的包管理器、格式化工具、lint 工具或测试运行器，它们都是 zero 的子命令。这样能让工具的接口保持小巧、可预测，而这正是设计的初衷。

下面是最常用的几个命令：

每个命令都支持 --json，输出机器可读的结果，而不是给人看的格式化文本。

zero check

这是最常用的主力命令。zero check 运行编译器的静态检查：语法解析、类型检查、能力与副作用推断、缺失导入检测，并在生成代码之前停下。它速度很快，这一点很重要，因为智能体和编辑器会频繁调用它。

zero check hello.0

输出干净（什么都不打印，退出码为 0）说明文件是合法的。默认情况下，错误以人类可读的文本输出。加上 --json，你会得到供智能体使用的结构化形式：

zero check hello.0 --json

{
    "ok": false,
    "diagnostics": [
        {
            "code": "NAM003",
            "message": "unknown identifier",
            "line": 3,
            "repair": { "id": "declare-missing-symbol" }
        }
    ]
}

诊断信息的结构在 JSON 诊断 中有完整说明。注意稳定的 code 字段：无论编译器是哪个版本，NAM003 始终表示“unknown identifier”（未知标识符）。

你也可以让 check 检查整个包目录，而不只是单个文件：

zero check ./my-package

它会读取 zero.json，遍历源代码树，并报告所有目标中的每一个问题。

zero run

run 一步完成编译和运行。当你在反复修改一个小程序、不在乎是否在磁盘上生成二进制文件时，用它最合适。

zero run hello.0

它相当于先运行 zero build，再执行生成的二进制文件，只是构建结果会被丢弃。程序的标准输出会转发到终端的标准输出，也就是说，程序里调用的 world.out.write 会直接显示在你的屏幕上。

如果程序需要参数，把它们放在 -- 后面：

zero run greet.0 -- Alice

运行时会通过同一个暴露 I/O 的 World 能力，让程序访问这些参数。

zero build

需要构建结果时，用 build：

zero build hello.0

编译器会在源文件旁边（如果你在包里工作，则在包的构建目录下）生成一个原生可执行文件。你可以像运行其他程序一样运行它，不需要额外的运行时，因为 Zero 的二进制文件是自包含的。

Zero 的二进制文件很小。项目的设计目标是让简单程序的可执行文件小于 10KB，做法是绕开 LLVM 工具链，直接生成紧凑的代码路径。

zero test

运行包的测试目标：

zero test

测试和源代码一起放在 src/ 下，并在包的 zero.json 中声明为测试目标。测试运行器会找到它们，逐个执行，并输出通过或失败。加上 --json 后，每个测试的输出都是结构化的（名称、状态、耗时、捕获的诊断信息），方便智能体和 CI 工具使用。

Zero 包 介绍了如何在 zero.json 中声明测试目标。

zero fix

fix 使用 check --json 产生的修复元数据。它有两种模式：

zero fix --plan --json   # show the structured plan, don't apply
zero fix                 # apply the plan in place

修复计划大致是这样的（结构仅作示意）：

{
    "diagnostic": { "code": "NAM003", "line": 3 },
    "plan": {
        "id": "declare-missing-symbol",
        "edits": [
            { "kind": "insert", "line": 1, "text": "fun answer() -> i32 { return 42 }\n" }
        ]
    }
}

它的思路是：智能体获取计划，判断是否可信，然后直接应用，或者交给更高层的推理步骤处理。计划就是数据，智能体不需要理解文字说明就能采取行动。

zero explain

explain 是诊断系统中负责文字说明的部分：

zero explain NAM003

它会打印错误代码的人类可读解释：代码的含义、编译器为什么报出它，以及常见的修复方式。以下情况会用到它：

• 人在调试时，想看比行内提示更详细的说明。
• 智能体遇到训练数据中没有的诊断代码，需要更多上下文。

诊断代码本身在各个编译器版本之间保持稳定，所以缓存下来的解释依然有效。

zero new

生成一个新包的脚手架：

zero new cli hello

这会创建一个 hello/ 目录，里面有 zero.json 清单文件和一个起步用的 src/main.0。第一个参数（这里是 cli）用来选择模板，在这个例子里是一个可执行的命令行应用。Zero 包 详细介绍了目录结构。

养成用 --json 的习惯

几乎每个命令都支持 --json。如果你要围绕 Zero 构建工具、智能体运行框架或 CI 流水线，默认就用 JSON 格式。它有这些优点：

• 稳定。 输出格式有版本号，团队把它当作契约来维护。
• 完整。 你能拿到人类可读输出里没有的字段（精确的代码范围、修复计划 ID、依赖图数据）。
• 易于解析。 不用写正则表达式从英文句子里提取行号。

如果是人在终端里使用，就别加 --json，格式化的文本才是你想看的。

其他实用命令

还有几个用得没那么频繁、但值得了解的命令：

• zero graph --json：以结构化数据输出包的依赖图。可以帮你理解谁依赖谁，也方便智能体分析调用位置。
• zero size --json：按目标报告编译产物在磁盘上的大小。如果你在意二进制文件的体积（这也是 Zero 的设计目标之一），它很有帮助。
• zero --version：打印工具链版本。团队协作时，最好把版本固定下来记在某处，因为 Zero 还没到 1.0，确实会有破坏性变更。

下一篇：Zero 包

写 hello world 用一个 .0 文件就够了。真实项目会使用包，包里有 zero.json 清单文件和 src/ 目录。Zero 包 会演示如何生成包的脚手架，并解释每个字段。