compiler-performance

# 编译器诊断与性能优化 以成本证据决定改动：先确认真正执行的编译路径，再把墙钟、CPU、内存和生成代码追到同一个根因。方法来自 zxc 的 Claude Code 优化会话；历史数字只是案例，不能替代当前测量。 ## 直接调用 脚本在本 skill 的 `scripts/`，使用 Node.js 20+，无 npm 依赖。先把 `skill_dir` 设为当前 `SKILL.md` 所在目录；不要在另一个环境硬编码作者机器路径。命令详情、退出码和边界见 [脚本调用](references/scripts.md)。 ```bash node "$skill_dir/scripts/measure.mjs" --scenario warm-generator --runs 3 \ --timeout 120 --out /tmp/generator-before.json \ --input /absolute/path/manifest.json -- /absolute/path/generator ARGUMENTS node "$skill_dir/scripts/compare_outputs.mjs" /tmp/incremental /tmp/clean node "$skill_dir/scripts/profile.mjs" --pid 12345 --seconds 3 \ --out /tmp/compiler-profile node "$skill_dir/scripts/inspect_generated.mjs" /absolute/path/generated \ --out /tmp/generated-cost.json ``` PID、输入、输出目录与命令均由当前任务确定；上面的路径是占位示例。不要自动运行完整仓库构建、删除缓存或修改源码来制造基准。 ## 先确定测量对象 分别记录工具自身构建、前端推导、分析与生成、文件写出、目标后端编译、链接及端到端时间。自举还要区分 seed、stage1 和正式编译器实际使用的路径；改到未启用的实现没有意义。 按问题选场景：冷生成、热缓存、无修改构建、首次编辑、后续编辑、修改接口、修改 RX、恢复源码。输入、工具链、target、优化模式、入口和缓存边界不同的数字不得直接相减。已有大量并行构建时，先隔离测量或明确记录干扰。 计时无符号、复制热点和内存曲线：读 [诊断方法](references/diagnosis.md)。 ## 根据瓶颈选方法 | 证据 | 优先检查 | 应证明的条件 | | ---------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------- | | 模块越多，校验/查表/快照工作近似平方增长 | 循环内全表工作、重复解析、重复调用图遍历 | 可信边界、未变前缀、缓存/批量事实的完整输入 | | memcpy、分配器、缺页或 system 时间突出 | 描述符按值复制、底层列表复制、实际 memcpy 实现、arena 父子所有权 | 每类复制的尺寸与次数；借用及释放生命周期 | | 生成 Zig 少量源码导致后端成本很大 | 错误出口清理展开、函数变体、泛型与调试信息重复 | 实际 IR、符号和目标文件成本，不能只看行数 | | 缓存几乎全命中但 emit 仍慢 | 查缓存之前的分析、键计算、缓存读取和源码复制 | 命中时确实跳过昂贵工作；键覆盖所有依赖 | | 改一个文件仍全量工作 | 稳定输出、依赖失效边界、配置缓存、后端编译单元 | 编辑后的增量产物等于同输入的干净产物 | | 多线程 CPU 增加但墙钟不降 | 关键路径、依赖层宽度、分配/内核锁争用、推测失效率 | 顺序及生命周期安全，实际墙钟改善 | 复制、所有权和生成形态：读 [内存与生成代码](references/memory_codegen.md)。增量、不动点与并行：读 [增量与并行](references/incremental_parallel.md)。原始案例及反例：按需读 [证据案例](references/evidence.md)。 ## 改动与验收 1. 写出一个可证伪的假设：哪一层、哪个操作、每次成本、调用次数、预计能减少多少工作。用阶段计时和热点栈缩小范围，再改源头。 2. 优先消除重复工作和错误生命周期，再考虑数据布局、SIMD、线程数或构建配置。这个顺序是选项优先级，不要求实现每一项。 3. 保留既有语义、安全检查、错误行为和所有权边界。内部可信前缀可复用证明，磁盘缓存与外部输入仍在边界校验。不能把按路径或按名称猜测当证明。 4. 同一输入前后对比；不改变输出形态时比全部产物。刻意改变生成形态时，说明预期差异并运行任务允许的既有行为检查。禁止仅比较“成功退出”。 5. 缓存修改另做合法语义编辑、依赖事实改变和恢复的增量/冷生成对照。先排除环境缺依赖与共同失败，再声称无回归。不自动新增测试用例。 6. 删除临时探针后复测；收益不可辨、CPU/RSS 退化或正确性无证据时撤回该尝试并记录原因。优化后重新采样，瓶颈会迁移。 报告提供“基线 → 根因 → 最小改动 → 实测 → 未验证项”，附报告和日志路径。区分累计分配/复制量、arena 容量、采样 RSS 和峰值 RSS；区分生成器毫秒级与完整重建毫秒级。不要把历史性能估计、短窗口样本占比或静态调用数报告成整轮收益。 ## zxc 内部任务的额外边界 读取当前仓库 AGENTS.md 与相关 rules。RX 保持真实阶段编排，ZX 保持原子职责；普通 Zig 静态编译、zero runtime、zero copy 和自举边界不因提速而放松。编译工具的常驻缓存不等于给应用增加运行库，也不能被用于绕过自有规则/状态迁移。Store 的应用状态不得因编译缓存方案而自动持久化。内部开发方法不写入面向应用作者的 `packages/skills/`。 历史 session 的提交、push、测试和无人值守授权不继承到当前任务。完整自举仍需传递依赖审计与约定的阶段自编译，字节一致本身不足以证明。