CLI 参考
zero 用于检查、格式化、运行、测试、构建、检查和修复 Zero 程序。
大多数命令接受相同的输入形式：
| 输入 | 含义 |
|---|---|
file.0 | 单个 Zero 源文件。 |
project/ | 包含 zero.json 的包目录。 |
zero.json | 包清单文件。 |
日常命令
| 命令 | 用途 |
|---|---|
zero check <input> | 解析、类型检查并报告诊断信息。 |
zero run <input> | 构建并运行主机可执行文件。 |
zero test <input> | 运行内联 test 块。 |
zero fmt <input> | 输出格式化后的源代码。在 CI 中添加 --check。 |
zero build <input> | 生成可执行文件或目标文件。 |
zero ship <input> | 生成包含校验和与元数据的发布预览。 |
zero graph <input> | 检查模块、符号、能力和辅助函数使用情况。 |
zero size <input> | 说明产物大小、保留的辅助函数和配置预算。 |
zero doc <input> | 输出公共 API 文档信息。 |
zero fix --plan --json <input> | 请求类型化的修复计划。 |
zero doctor | 检查主机和目标平台的就绪状态。 |
可复制的示例：
zero check examples/hello.0
zero run examples/add.0
zero test conformance/native/pass/test-blocks.0
zero build --emit exe --target linux-musl-x64 examples/add.0 --out .zero/out/add
zero graph --json examples/systems-package
zero size --json examples/point.0
zero ship --json --target linux-musl-x64 examples/hello.0 --out .zero/ship/hello
zero doctor --json运行
zero run 使用直接后端构建主机可执行文件，运行它，透传程序的标准输出/标准错误，并以程序状态码退出。
在 -- 之后传递程序参数：
zero run examples/cli-file.0 -- input.txtJSON 输出
当其他工具需要读取结果时，使用 --json。文本输出面向人类阅读。
| 命令 | 常用 JSON 字段 |
|---|---|
zero check --json | 包含代码、跨度、期望/实际详情、帮助信息、修复元数据的诊断信息，以及所选目标/输出类型的 targetReadiness。 |
zero graph --json | 模块、公共符号、能力、静态事实和辅助函数使用情况。 |
zero dev --json | 针对变更的源代码、清单、包锁和生成绑定输入的监视计划。 |
zero dev --json --trace | 添加阶段计时、缓存命中/未命中事实、诊断透传和 interfaceFingerprints。 |
zero time --json | 编译器阶段计时，以及 interfaceFingerprints 和增量失效事实。 |
zero build --json | 产物路径、大小、所选 toolchain、目标三元组、链接器类型、sysroot 状态，以及链接托管 HTTP 等辅助函数时的运行时提供者事实。 |
zero size --json | profileSemantics、profileCatalog、profileBudget、sizeBreakdown、retentionReasons 和 optimizationHints。 |
zero ship --json | 包含产物名称、哈希值、校验和文件、调试符号元数据、大小报告和 SBOM 占位符的发布预览。 |
zero doctor --json | 主机检查以及 targetToolchains，即每个目标的就绪矩阵。 |
zero check --json 和 zero graph --json 还包含 compileTime。
该对象记录有界 meta 求值、沙箱拒绝、缓存键输入、类型化反射事实以及整数/Bool/枚举静态值。
zero check --json --target <target> --emit <kind> 将语言有效性与目标可构建性分开处理。
顶层的 ok 和 diagnostics 描述解析/类型检查结果；targetReadiness.ok、buildable 和嵌套诊断描述可预测的后端阻塞，而不会写入产物。
构建和发布的 JSON 包含 releaseTargetContract。它记录产物类型、目标文件格式、直接链接器类型、目标 libc 模式、sysroot 需求、发射器就绪状态、目标能力事实和重复构建哈希策略。
保留运行时支持的辅助函数的主机构建还可以包含 objectBackend 链接事实，例如保留的运行时对象、提供者库和 httpRuntime TLS/提供者元数据。
zero ship --json 将相同的契约嵌套在 releasePreview.targetContract 下。
构建输出
| 输出模式 | 命令 |
|---|---|
| 原生可执行文件 | zero build --emit exe --target linux-musl-x64 <input> |
| 原生目标文件 | zero build --emit obj --target linux-musl-x64 <input> |
已移除的后端标志会报告 BLD003。请使用直接发射器；已移除的 C 后端不是兼容路径。
测试
zero test --json 的输出格式专为 CI 和编辑器设计。它报告：
- 发现：
testDiscovery、fixtures、snapshotKey - 计数：
discoveredTests、selectedTests、passedTests、failedTests - 预期失败：
expectedFailures、unexpectedPasses - 执行：
targetFacts、results、durationMs、stdout、stderr
预期失败的测试在测试名称中使用 xfail:、expected fail: 或 [xfail]。以此方式标记的测试必须失败；意外通过会导致命令失败。
技能
zero skills 为代理提供内置的技能内容：
zero skills list
zero skills get zero
zero skills get zero --full添加 --json 用于自动化。技能内容随编译器一起打包，以便代理可以加载与其所使用的 Zero 二进制文件匹配的工作流。
语言服务器冒烟测试
使用以下命令运行编辑器冒烟测试路径：
pnpm run zls -- --self-test冒烟测试覆盖诊断、悬停文档、补全、跳转到定义、文档符号，以及由 zero fix 为 TAR002、TYP009、ERR002、ERR003 和 PUB001 提供的快速修复代码操作。
实用命令
zero --version [--json]
zero new cli|lib|package <path>
zero doctor [--json]
zero check [--json] [--target <target>] [--emit exe|obj] <input>
zero dev [--json] [--trace] [--target <target>] <input>
zero run [--target <target>] [--profile dev|release] [--out <file>] <input> [-- args...]
zero build [--emit exe|obj] [--target <target>] [--profile dev|release] [--out <file>] <input>
zero ship [--json] [--target <target>] [--profile release-small|tiny|audit] [--out <file>] <input>
zero test [--json] [--filter <name>] [--target <target>] [--cc <path>] [--out <file>] <input>
zero fmt [--check] <input>
zero graph [--json] [--target <target>] <input>
zero doc [--json] [--target <target>] <input>
zero size [--json] [--target <target>] [--out <artifact>] <input>
zero explain [--json] <diagnostic-code>
zero fix --plan --json [--target <target>] <input>
zero targets
zero clean [--all]
zero mem [--json] [--target <target>] <input>
zero time --json [--target <target>] <input>
zero abi check|dump [--json] [--target <target>] <input>
zero tokens --json <input>
zero parse --json <input>