优化与大小配置

优化与体积配置文件

Zero 的配置文件是产品契约，而非编译器的隐式行为。构建和体积 JSON 会暴露所选配置文件的信息，以便 CI 和智能体能够解释为何保留了某些字节。

常见的配置文件选择：

配置文件	适用场景	契约
`debug`	需要诊断信息和本地符号时。	检查陷阱、诊断性 panic 路径、保留调试元数据。
`fast`	吞吐量比最小体积更重要时。	直接代码生成，优先优化速度，同时保留检查式安全边界。
`small`	这是默认的发布配置文件。	按需付费的辅助函数、剥离未请求的元数据、确定性产物。
`tiny`	产物体积是主要约束时。	陷阱时中止、最少的运行时元数据、严格的辅助函数预算。

可复制的命令：

bin/zero build --json --profile small --target linux-musl-x64 examples/hello.0 --out .zero/out/hello-small
bin/zero build --json --profile tiny --target linux-musl-x64 examples/hello.0 --out .zero/out/hello-tiny
bin/zero size --json --profile debug --target linux-musl-x64 examples/memory-primitives.0
bin/zero size --json --profile tiny --target linux-musl-x64 examples/fixed-vec.0
bin/zero mem --json examples/allocator-collections.0

zero build --json 包含：

profileSemantics：规范配置文件、profileKey、别名及优化目标。
profileCatalog：可用的配置文件和别名。
profileBudget：所选配置文件的体积限制和辅助函数预算策略。

zero size --json 额外包含 sizeBreakdown、retentionReasons 和 optimizationHints。当产物体积超出预期时，请从这里开始排查。

zero mem --json 是内存预算的配套工具。它包含：

memoryBudgets：栈、静态区、堆、arena 和固定缓冲区的总量。
allocatorFacts：使用了哪些分配器 API。
allocationInstrumentation：分配失败和清理的相关信息。
collectionFacts：固定容量集合的使用情况和无全局分配器检查。

体积分解

sizeBreakdown 的结构专为优化智能体设计：

functions：保留的函数、测试、导出、估算字节数及保留原因。
sections：代码、只读字面量、栈、调试元数据及可选的输出产物段。
literals：只读字符串和字节字面量的开销。
stdlibHelpers：按需付费的辅助函数开销及能力归属。
imports：所选程序保留的能力导入。
runtimeShims：由能力或边界检查保留的目标/运行时垫片。
debugMetadata：配置文件保留的元数据的字节数和策略。

使用 retentionReasons 来回答某个函数、辅助函数、字面量或调试元数据块为何保留在产物中。使用 optimizationHints 获取下一步操作建议，例如从 debug 切换到其他配置文件、从目标无关代码中移除托管文件系统辅助函数，或检查 topLargestEmittedHelpers。

基准测试趋势

基准测试门控会同时写入一份完整的单次运行报告和一个紧凑的趋势产物：

ZERO_BENCH_RUNS=1 pnpm run bench

基准测试的输出文件为：

文件	用途
`.zero/bench/latest.json`	完整的单次运行冒烟报告。
`.zero/bench/trends/latest.json`	紧凑的趋势摘要。
`.zero/bench/trends/summary.md`	人类可读的配套报告。

趋势摘要跟踪产物体积、压缩体积、构建时间、启动时间、操作计时以及在可用时的峰值 RSS。

在信任配置文件回归之前，请先使用基准测试趋势。debug、fast、small 和 tiny 配置文件的构建和体积报告在重复运行中应保持确定性。