去掉没价值的注释

注释只留不看它就会写错或改错的东西，规矩和例子在 docs/style/code.md，本文不复述。分隔线和给一段代码起的标题 vp check 已经挡了（vibevalley/no-comment-divider）；剩下的要读懂才判断得了，模型先审一遍，你对着代码定每一条。偏向删：留一条废话的代价是每个读的人都读一遍，删错一条的代价是下一个改它的人可能写错；拿不准的那一条就去问「删掉它，改这段的人会写错什么」，说不出具体会错什么的，删。

1. 定范围

• 提 PR 前（默认）：这个分支比 origin/main 新加的注释，包括没提交的。
• 主人点了一块：那个模块或目录里已有的全部注释，一次一块，不扫整个仓库。
• 主人没点、分支也没有新注释：问主人清哪块。

先 --dry-run 数一数，不调模型：

vpx scripts/comment-review.ts --dry-run                          # 这个分支新加的
vpx scripts/comment-review.ts --all apps/server/src/issue --dry-run   # 一块已有的

花钱的量级：一个模块一两百条注释、十次以内的请求，一分钱上下。新加的直接跑；--all 超过 500 条，先把条数告诉主人再跑。

2. 跑

vpx scripts/comment-review.ts                                    # 要 DEEPSEEK_API_KEY
vpx scripts/comment-review.ts --all apps/server/src/issue

每条不该留的打三行：文件:行 delete|rewrite <对上的规矩那一行>: <理由>、注释原文、rewrite 的话 → 改好的写法。判 keep 的不打。有不该留的退出码 1；模型漏答或答得不成格式，脚本报错退出，重跑一次，还错就看报错。

3. 逐条核实

模型只读了注释附近的十几行，会判错。每一条打开文件、读它说的那段代码，按顺序问：

1. 删掉它，改这段的人会写错什么？ 说不出来就删。复述名字和签名、讲这段代码在做什么、测试里讲每一步、写这段从哪来的、文件开头概述这个文件有什么的，都在这里删掉。
2. 说得出，能不能让代码自己说？ 局部变量、参数、私有函数的名字说不清的，改名字；「"" 表示没有」这类取值，能用类型（联合、undefined）说的改类型；然后删注释。导出的名字、接口、表的字段改名牵连大，不在这里改，记下来告诉主人。
3. 代码说不了，注释里还夹着别的？ 只留那一句（为什么、顺序和锁、安全边界、单位和取值、要和哪里一起改），别的删掉。模型给的 rewrite 是参考，常常还能更短；留下的照周围的口吻，英文，从这件事本身说起。
4. 模型判错了（它就是 建议写 那几类，删了真会写错）：留着，记下文件、行和理由，汇报时列出来。

删的时候连带收拾：注释删掉后留下的连着两个空行合成一个；整段 JSDoc 一起删；行尾的 // … 连前面的空格一起删。工具的指令（@ts-expect-error、oxlint-disable、@internal）脚本不审，也别删。

只动模型报出来的和你核实时顺带看到的同一类；模型判 keep 的不逐条重审，模块里别的问题（死代码、能简化的）记下来，交给 vv-simplify。

4. 改完

• vp check --fix，再 vp check。只删、改了注释，不用跑测试；改了名字或类型，跑和那块有关的最窄的检查（vp run server:check、vp run web:check）。
• 再跑一次第 2 节的命令：改写的注释是新加的，会再审一遍；模型每次判的不一样，--all 的第二轮还会在第一轮留下的里报出新的，照第 3 节核实。第二轮还报的、你已经判过要留的，不再改，不来回拉锯。
• 清一块已有的注释是机械改动，单独一个 PR（vv-pr 第 1 节），一块一个；标题说改完以后的样子（Issue module comments say only what the code cannot）。

5. 汇报

• 审了多少条，删了几条、改短了几条、改名或改类型替掉了几条。
• 模型判了不该留、你留下的：每条 文件:行 和一句理由。
• 看到了没改的：导出的名字说不清的、别的该简化的地方。