用途:该技能面向 Zig 0.17.x(0.17.0、0.17.1)代码的编写、审查、重构与从 0.16 升级,重点是在失败、并发与后续变更下保持正确性。资料说明其事实依据为 0.17.0/0.17.1 标准库与编译器,以及一次真实的 0.16 到 0.17 移植。
主要能力:
- 版本核对:读取 build.zig.zon 中的 .minimum_zig_version 并运行 zig version;指出 0.16 与 0.17 均不强制该字段,编译器不匹配会延迟且误导性地报错。
- 正确性规则:每次分配有唯一所有者与成功/失败清理路径;指针或切片不得超出存储或跨可重分配变更存活;外部长度、偏移、计数、递归、重试、队列与捕获输出在算术、分配或切片前校验并设界;断言与 catch unreachable 仅用于程序自有不变式;整数转换与算术需说明范围与溢出推理;共享可变状态需有所有者与同步策略;公开契约需说明所有权,不意外暴露 anyerror、anytype 或内部可变存储。
- 静默行为变化清单:@hasDecl 仅见 pub 声明;std.mem.containsAtLeastScalar 末两参数顺序调换;@bitCast 重定义(数组与向量按逻辑位表示拼接,拒绝 extern struct/union,枚举转换检查标签);@tagName(builtin.optimize) 返回 debug/safe/fast/small;浮点 eql 与 findDiff 不再把切片视为与自身相等;std.array_list.Managed 需要 pointer_stability 字段。
- 移除与弃用对照:列出 0.16 到 0.17 不再编译的写法(如 ** 重复、errdefer |err|、void{}/i0、@cImport、旧优化标签、StackFallbackAllocator、@typeInfo 旧字段、b.build_root 等)及弃用项与替代(如 allocPrint→gpa.print、bufPrint→std.mem.print、indexOf*→find 系列、copyForwards→@memmove、std.fs→std.Io.Dir.path、builtin.mode→builtin.optimize 等),并提示 copyForwards、utf8Decode、DebugAllocator 三项替换可能改变行为。
- 入口、I/O 与分配器:给出 main(init: std.process.Init) 示例;说明 init.gpa 在 Debug/ReleaseSafe 下为 SafeAllocator 并报告泄漏且不改变退出码,其他构建在链接 libc 时为 c_allocator,否则为 smp_allocator;init.io 为 std.Io.Threaded,应向下传递;按生命周期选择分配器(测试用 std.testing.allocator、泄漏检查用 SafeAllocator 但不用于生产、请求/批处理用 ArenaAllocator、有界暂存用 FixedBufferAllocator、共享并发用 smp_allocator);std.Io.Evented 在 0.17.0/0.17.1 不编译。
- 工作流程:新代码只用替代列,并用 scripts/check_deprecated.py 扫描至退出码 0;迁移时先读 toolchain,执行 scripts/migrate.py --write 做精确转发重命名,再运行 zig fmt 重写 @intFromEnum/@enumFromInt,构建全部产物并跑完整测试,运行 check_deprecated.py --review 并逐项核对六项行为变化,为每个修复的静默变化补测试;合并升级主线到 0.16 分支时用 merge 而非 rebase。
- 审查与验证:对改动文件运行扫描器,将新增 @hasDecl 探测、containsAtLeastScalar 调用、数组/extern struct/枚举的 @bitCast 视为待确认问题;按内存安全、非法行为、竞态、泄漏优先排序。验证优先用仓库命令,否则运行 zig fmt --check、zig build、zig build test;按需增加 fuzz、Debug/ReleaseSafe、交叉编译、ReleaseFast/ReleaseSmall 与可执行文件运行,并说明未能运行的部分。
使用方式:资料给出脚本调用形式 python3 <this skill>/scripts/check_deprecated.py <files or directories> 与 python3 <this skill>/scripts/migrate.py --write <files or directories>,以及 zig fmt <files or directories>;参考文件按需加载(types-memory-errors、api-maintainability、io-concurrency-security、testing-build-size、language、std、build-system、toolchain、examples.zig)。
适用场景:Zig 0.17 项目的新代码编写、代码审查、0.16 到 0.17 迁移、构建与测试验证。
限制:仅覆盖 0.17.0/0.17.1;其他版本只能用与版本无关的参考并查标准库源码;仓库指令(AGENTS.md 等)、build.zig 与 build.zig.zon 优先于该技能;不得升级、重链接或替换共享的 zig 安装;资料未提供具体收费、平台支持范围或性能数据。