changwei-code-check · 使用说明

提交前的产物检查闸：把要交出去的代码、文档、配置、交付件扫一遍，出一份问题报告。

拷贝这个目录到你的机器就能用，不需要安装任何三方包。本文只讲最常用的一条路—— 「我在本地写完 / 改完算子，提交前自己先查一遍」。他检别人 PR、扫转测交付件见 SKILL.md。

---

1. 装配（一次，约 2 分钟）

必需

依赖	说明
python3	无三方依赖。语法层面兼容 3.9+，实测环境是 3.12；低版本没实测过
git	被检仓要是 git 仓库（要算 diff）

可选，但强烈建议装

依赖	不装的后果
clang-format 18.1.8	组 10 的格式检查查不了；版本对不上会额外报一条版本不一致

验收：跑一次自检，确认这份拷贝在你机器上是好的

cd scripts
python3 selftest.py        # 期望：哑弹 0
python3 lint_checkers.py   # 期望：无「扫代码却不去注释」的 checker

selftest.py 会在系统临时目录里造一个带各种毛病的假仓 + 假 canndev，验证每条规则在 它必然该响的样本上真的响了。看到「哑弹 0」才算装好。 它不依赖任何外部仓库， 在任何机器上都应该是绿的；如果不是，别继续用，先来问。

---

2. 最短路径：查自己刚写的算子

一条命令，不用先 commit，不用管 git 版本：

cd <changwei-code-check>/scripts
python3 check.py --repo <你的算子仓> --ops <算子名> \
                 --report ~/check_report.md --stamp $(date +%F)

--ops 三种写法都认，多个用逗号隔开：

--ops multi_add_rms_norm_dynamic_quant          # 目录名
--ops MultiAddRmsNormDynamicQuant               # 驼峰名
--ops norm/multi_add_rms_norm_dynamic_quant     # 仓内相对路径
--ops op_a,op_b,domain/op_c                     # 多个

名字打错会退出码 2 并告诉你哪个没找着，不会静默当成"这个算子没问题"。

• --report 生成 Markdown 问题报告；不给就只打到终端
• --stamp 报告里的生成时间。脚本内部不取当前时间，由你传，同一输入重跑结果一致
• 只想看某几组：--groups 1,3,16
• 🟢 规范与卫生默认收起（只给每规则条数）；要逐条看加 --full
• 确认过的误报写进根目录 suppressions.json（必须写 why/who），报告末尾会留一行「已按白名单过滤 N 条」

口令唤起（在 Claude Code / agent 里）

直接说人话，不用记命令。 agent 认下面这些说法，会自动翻成 check.py --ops ...：

你说	agent 干什么
「检查一下 group_norm_silu_quant」	查这一个算子，出报告
「帮我看看 op_a 和 op_b」	逗号拼成 --ops op_a,op_b
「提交前过一遍 xxx 算子」	同上
「检查我刚写的算子」	先问你是哪个（或从 git status 推），再查
「转测前查一下 xxx」	带上交付件根，多跑组 15/20/22/23（交付件与性能与新鲜度）
「审一下这个 PR：<链接>」	走远程他检：克隆 PR → 只查不改 → 出行级评论清单

算子名三种写法都认：目录名 group_norm_silu_quant、驼峰 GroupNormSiluQuant、 相对路径 norm/group_norm_silu_quant。名字打错会明确告诉你哪个没找着，不会静默当没问题。

agent 会按四步汇报，不只报第一节

1. 结论 N 条 —— 先讲 🔴，🟢 默认收起
2. ⏳ 待判定 —— 脚本只定位、没下结论的。agent 应当直接派子 agent 答掉再汇报， 而不是把"没有结论"丢给你（题包在 <仓的父目录>/judgment_pack_<仓名>.md， 答完用 --answers ans.json 回填）
3. 跳过说明 —— 哪几组没跑、为什么。说"全查过了"之前必须先看这节
4. 要不要改由你定；🟢 规范类可以直接改，🔴 功能类先说清再动

让它更好用的两件事

export CHANGWEI_CANNDEV=~/repos/canndev                    # 组 5/7/18 要
export CHANGWEI_DELIVERABLES_ROOT=~/repos/<交付件仓>/...    # 组 15/20/22/23 要

设过之后 agent 不用每次问你路径。转测前还想查新鲜度，再补 --vendor <部署根>。

什么时候改用版本区间模式

要查「这次改动有没有污染 A2」「提交卫生（单 commit / 大量删除）」这类问题时， 判据是"改了什么"，算子模式给不出这个输入。这时先提交，再按区间跑：

git add -A && git commit -m "wip"
python3 check.py --repo <仓> --base origin/master --head HEAD --local --report ~/r.md

（--base 不确定就用 git merge-base origin/master HEAD 算。） 算子模式下组 4、13 会显式跳过并写进报告，不会假装查过。

---

3. 两个外部对照物（不给不会报错，但会少查）

有些问题必须跟别的东西比才查得出来——"该有而没有"这一类比"写错了"难查一个数量级。 这两个对照物不在你的算子仓里，得你自己指路：

对照物	怎么给	不给的后果
canndev（A2 权威基线，外部代码仓）	--canndev <路径> 或 export CHANGWEI_CANNDEV=<路径>	组 5 / 7 / 18 跳过；组 4 判不了「A2 实现在不在」
转测交付件根（内部件，不在算子仓里）	--deliverables <路径> 或 export CHANGWEI_DELIVERABLES_ROOT=<路径>	组 15 / 20 跳过

两者都不猜路径：猜出来的根会把"我没处可查"静默变成"它不存在"，而后者是强得多的结论。 路径给错直接退出码 2，不会降级成"没给"。

设成环境变量之后，日常就不用每次带参数了：

export CHANGWEI_CANNDEV=~/repos/canndev
export CHANGWEI_DELIVERABLES_ROOT=~/repos/<你们团队的交付件仓>/changwei_deliverables

---

4. 报告怎么读

报告有四节，缺一不可。只看第一节会读出错误结论。

节	意思
结论：N 条问题	脚本有把握下结论的。按危害排：🔴 功能正确性 / 🟡 一致性与覆盖 / 🟢 规范与卫生
⏳ 待判定	脚本只定位、没下结论。要跨函数追数据流或读懂意图才能判
执行记录	真跑过的检查，过与不过都列。用来确认"它到底查了什么"
基线与范围 / 跳过说明	哪组按什么权威源判、哪组根本没跑

三个要点：

1. 「0 条问题」不等于「全查过且没事」。 先翻到「跳过说明」看有几组没跑。 一个永远返回 0 的检查比没有检查更危险，因为它看起来像通过了。
2. ⏳ 待判定不是问题、也不是没问题——是没有结论。 没人去答就一直是没有结论， 不许当成通过。题目本体会写到被检仓的父目录下：judgment_pack_<仓名>.md， 整份丢给一个能读代码的人（或 agent）去答。
3. 标了 需人工复核 的，是静态扫描给的提示：如果上界确实有别处保证，忽略即可。

---

5. 常见问题

diff 列出 N 个文件，工作树里只有 M 个存在 多半是没 checkout 到 --head 那个版本。先 git checkout <head> 再跑—— 否则所有检查都会拿到空文件列表、静默返回 0 条。

某组显示「未实现」 这份版本没实现该组，报告里会明写「没查，不等于没问题」。这是故意的： 未实现的组必须每次现形，不能从报告里消失。

报告里 🔴 很多，但看着像同一个毛病刷屏 同文件同规则超过 5 条会自动折叠成一条 + 行号列表（--fold N 可调，--json 始终全量）。 挑一条改掉，同文件其余同类一般跟着一起改。

报出来的确认是误报怎么办 写进根目录 suppressions.json（rule + op/file + 必填 why/who）。 规则一律往严了报——误报开发确认一下就完了，漏报要等测试打回来才知道，那更贵。 被压掉的条目不会消失：报告末尾会留一行「🔇 已按白名单过滤 N 条」。

改了规则之后 必跑 python3 selftest.py（哑弹）+ python3 lint_checkers.py（元检查）。 新增规则要同时在夹具里加一个必然触发它的样本，否则它是个哑弹也没人知道。

---

6. 还能干什么

场景	入口
审别人的 PR，出行级评论	check.py --json + render_comments.py，见 SKILL.md 用法 ②
只扫转测交付件	scan_handover.py --op <OpName> --deliverables <根> --write
语义判定（脚本出题 → agent 判）	跑 check.py 就会出题；单独出题见 semantic_probe.py --emit

完整能力清单见 docs/checklist.md：三层 大类→子类→逐项， 每项标了用 📜 脚本还是 🤖 agent 执行、判据来源是什么，已知缺口也在表里。 该表由 scripts/gen_checklist.py 渲染 checkers/registry.py 生成—— 规则必须先在 registry 登记才能用，未登记的构造时直接抛异常。

设计取舍、六条纪律见 SKILL.md 与 docs/。