跳转至

来发信谷歌地图扩展 — 版本更新规则

本文件是本项目版本更新的总规范。每次更新前请先完整阅读本文件。 最后更新:2026-05-28(v0.10.108 从 repo 根迁移到 docs/rules/)

⚠️ 特别提示:第七章「改进前自查清单」是历次踩坑后总结的,改设置页 / 调度逻辑 / 文案前必读。

一、项目概况

项目 说明
名称 来发信 谷歌地图数据采集专业版(Chrome 扩展)
技术栈 WXT + React + MUI + TypeScript
包管理器 pnpm
当前版本 0.8.37(见 package.json 的 version 字段)
构建输出 dist/chrome-mv3/

二、目录结构

05_google-map/
├── 更新规则.md          ← 本文件,更新规范
├── development-log.md          ← 问题 / 解决方案 / 注意点记录
├── CLAUDE.md            ← 给 AI 的项目说明(自动遵守本规则)
├── backup/              ← 【规则1】更新前的源码备份
├── src/                 ← 源代码
├── test/                ← 已构建版本的归档
├── dist/chrome-mv3/     ← 【规则3】构建输出,加载到浏览器的就是它
├── package.json         ← 版本号在这里改
└── wxt.config.ts        ← 扩展配置

三、三条核心规则

规则 1 — 更新前必须备份

在动任何代码之前,先把当前版本完整备份到 backup/。

  • 备份目录命名:backup/v<当前版本号>_<日期>/,例如 backup/v0.8.37_20260521/
  • 备份内容:src/、package.json、wxt.config.ts、tsconfig.json
  • 一键备份命令(在项目根目录执行,先把 0.8.37 换成当前实际版本号):
V=0.8.37; D=$(date +%Y%m%d); mkdir -p "backup/v${V}_${D}" && cp -R src package.json wxt.config.ts tsconfig.json "backup/v${V}_${D}/" && echo "已备份到 backup/v${V}_${D}"
  • 备份目录只增不删,出问题随时可以回滚。

规则 2 — 全程记录开发日志

每次更新都要在 development-log.md 写一条记录,内容包括:

  • 本次改动:这次要做 / 做了什么
  • 遇到的问题:现象 + 原因 + 解决方案
  • 注意点:下次要避开的坑、约定、易错点

最新记录放最上面。日志模板见 development-log.md 顶部。

规则 3 — 新版本输出到专门文件夹,浏览器刷新即测

  • 构建输出统一在 dist/chrome-mv3/(由 wxt.config.ts 的 outDir 配置,是可见文件夹)。
  • 首次加载:Chrome 打开 chrome://extensions → 右上角开启「开发者模式」→ 点「加载已解压的扩展程序」→ 选择 dist/chrome-mv3/ 文件夹。
  • 改完代码后测试:
  • 方式 A(推荐):pnpm dev —— 改代码后自动重新构建并热重载,浏览器无需手动刷新。
  • 方式 B:pnpm build 重新构建 → 到 chrome://extensions 点该扩展的「刷新」图标 → 刷新网页测试。
  • 版本发布:pnpm zip 打包,把产物归档到 test/。

四、标准更新流程

把上面三条规则串成一套固定动作,每次更新照着走。

  1. 读本文件 + development-log.md,了解历史坑点。
  2. 【规则1】 执行备份命令,备份到 backup/。
  3. 【规则2】 在 development-log.md 顶部新建一条记录,写下本次改动目标。
  4. 修改 package.json 的 version(如 0.8.37 → 0.8.38)。
  5. 修改源代码。
  6. pnpm compile —— TypeScript 类型检查,无报错再继续。
  7. pnpm build —— 构建到 dist/chrome-mv3/。
  8. 【规则3】 浏览器加载 / 刷新,实测功能。
  9. 【规则2】 把过程中遇到的问题、解决方案、注意点补写进 development-log.md。
  10. (需要分发时)pnpm zip 打包,归档到 test/。

五、常用命令

命令 作用
pnpm install 安装依赖
pnpm dev 开发模式,自动热重载
pnpm build 构建生产版本 → dist/chrome-mv3/
pnpm zip 打包 zip → dist/laifaxin-chajian-ditu-<版本>-chrome.zip
pnpm compile TypeScript 类型检查(不输出文件)

六、注意事项

  • 版本号只在 package.json 改,WXT 会自动同步到扩展 manifest。
  • 备份目录 backup/ 和归档目录 test/ 只进不出,不要删。
  • 每次只做一类改动,方便出问题时定位和回滚。
  • 本项目有历史 TS 报错,pnpm compile 不作为通过标准;以 pnpm build 成功出包为准。
  • 依赖用 pnpm 安装;pnpm 11+ 需根目录 pnpm-workspace.yaml 的 allowBuilds 放行 esbuild 等构建脚本,否则 pnpm install/build 会报错退出。
  • 改了 wxt.config.ts(权限、host 等)后必须重新 build 并在扩展页重载。

七、改进前自查清单(必读 — 历次踩坑总结)

这些坑都是真实踩过的(v0.10.12 / v0.10.13 / v0.10.14 反复犯过),每次改进前花 2 分钟扫一遍能省 30 分钟返工。

🚨 A. 改「设置页 / UI 文案」前 — 反复踩坑最多

症状:望文生义命名设置项,导致与实际调度逻辑矛盾,用户读了反而误导。

铁律 1:读源码确认语义,不靠字段名猜

字段 字段名暗示 实际语义(已确认) 出处
maxConcurrentTasks "同时几个任务" activeTabs.size 全局上限,与任务数无关。1 个任务也能用满 N 个 Tab batch-controller.ts 顶部注释第 18-30 行
deepScrapeConcurrency "同时几个网站" worker 线程数全局上限。所有任务的 MapTaskData 共用一张表 engine-manager.ts getConcurrency + manageQueue
requestConcurrency "请求并发" v0.10.0 后废弃字段,调度器不读。仅保留兼容老 storage task-manager.ts 第 41 行注释
pagerConcurrency "翻页并发" 全局翻页 Fetch 并发上限,不是 per-task batch-controller.ts pumpPager
deepScrapeDomainConcurrency "单网站并发" 同一 hostname 最多同时几个 worker(防 DDoS 对方站) engine-manager.ts domainActive

铁律 2:v0.10.0 起一切都是「共享队列」架构

  • 任务(status='running' 的)→ 共享队列 ← worker 池(N 个槽位)
  • N 个槽位 = maxConcurrentTasks(地图)/ deepScrapeConcurrency(网站)
  • 任务数与槽位数完全解耦,调度器 round-robin 从所有 running 任务取 URL

改文案的 checklist: - [ ] label 是否暗示 per-task?(错)应改为「全局上限」「上限」 - [ ] helper 是否解释了「与任务数无关」? - [ ] 是否给了具体例子?(1 任务 vs 5 任务下的行为) - [ ] 改完后回看 batch-controller.ts / engine-manager.ts 顶部注释,文案与代码是否自洽?

📦 B. 加新功能 / 设置项前

铁律 3:写死的常量都是设置项的候选

任何 const FOO_BLACKLIST = [...] / const PATTERNS = [...] / 行内的 if/else 判断,问自己: - 用户可能想关掉吗?→ 加 Switch - 用户可能想加一些自定义项吗?→ 加 textarea,自动 merge 到内置 - 内置内容用户能看见吗?→ export const 出来,给「查看内置 N 项」按钮用

铁律 4:用户在某个粒度上设置 X,往往也想在更粗/更细的粒度上设置 X

  • 邮箱黑名单 → 也要支持域名级(v0.10.14 补的)
  • 单根域跟随 → 也要支持跨根域白名单(v0.10.14 补的)
  • 关键词白名单 → 顺手加黑名单(同价但不同语义)

铁律 5:默认值必须保持老版本行为(向后兼容)

新加的 boolean 字段默认 true 或 false 要保持上一版的实际行为;text 字段默认 '' 走内置;不要让老用户升级后突然丢功能。

新功能 checklist: - [ ] 是否有"打包成一个函数 / 一段逻辑"导致用户没法部分关闭? - [ ] 是否有"硬编码列表"用户想改改不了? - [ ] 默认值是否 = 上一版行为? - [ ] 是否需要在更粗 / 更细粒度也提供?

🔧 C. Edit 工具操作

铁律 6:含中文的旧 JSX,不要手写 old_string 猜全角半角

源码里这些字符常常是全角: - () U+FF08/FF09(不是 ASCII ()) - : U+FF1A(不是 ASCII :) - , U+FF0C(不是 ASCII ,) - 。 U+3002(不是 ASCII .) - ; U+FF1B(不是 ASCII ;)

症状:Edit 报 String to replace not found。

正确做法(按性价比排序): 1. 小改动:先 awk 'NR==<行号>' 把目标行打印出来直接复制粘贴 2. 大块替换:用 Python 切片,根据唯一锚点定位区间,整体替换:

cat > /tmp/new.txt << 'EOF'
... 新内容 ...
EOF

python3 << 'PYEOF'
from pathlib import Path
p = Path("src/path/to/file.tsx")
src = p.read_text(encoding='utf-8')
start = src.find("唯一锚点1")
end = src.find("唯一锚点2", start)
new_block = Path("/tmp/new.txt").read_text(encoding='utf-8')
p.write_text(src[:start] + new_block + src[end:], encoding='utf-8')
PYEOF
  1. 从不:连续猜 3 次 ASCII vs 全角 —— 浪费 token。

🗄️ D. storage / 数据兼容

铁律 7:storage 字段加只能加,不要删

  • 废弃字段 → 加 // v0.x.y deprecated, no longer read 注释,保留在 interface
  • 改语义 → 加新字段,老字段保留(写迁移代码可选)
  • 删了字段 → 老用户升级时 storage 里仍有,新代码读出来是 undefined,可能引发崩溃

🧪 E. 验证标准

  • pnpm build 必须过(生产构建出包 = 真验证)
  • pnpm compile 仅查"新增的 TS 错误",已有历史错误不算
  • 改了 settings UI 必须在浏览器实际打开看一眼(文字溢出 / 换行 / 折叠是否对)
  • 改了调度逻辑必须用 2+ 个任务跑一遍,验证共享队列行为(不是只跑 1 个任务)

🗒️ F. 历次大事件(避免重蹈)

版本 事件 教训
v0.10.0 多任务调度重写,从 per-task 改共享队列 这是基线架构,所有"并发"字段都是全局
v0.10.12 把 maxConcurrentTasks label 写成"= 任务数" 改文案前没读 batch-controller.ts 顶部注释
v0.10.13 scraper.ts 把 7 类规则打包写死 用户能想关的逻辑,全部独立开关 + 可编辑
v0.10.13 Edit 中文标点踩坑(3 次) Python 切片代替 old_string
v0.10.14 再次把 deepScrapeConcurrency 写成"网站数" 与 v0.10.12 同坑 → 必须查源码
v0.10.15 长跑后浏览器累积孤儿 Tab 卡死 引入 watchdog(5min 巡检 + 3 次累积自动重启)
v0.10.16 popup loading 状态死循环(无超时) 铁律 8:任何"等异步结果"的 loading 必须有超时 + 兜底入口,否则 = 用户卡死无法操作
v0.10.17 主面板登录按钮 force=false 跳过开窗 铁律 9:「主动点击」≠「静默尝试」,用户点击的入口必须 force=true 绕过缓存
v0.10.18 filter chip 视觉变了但 jsstore 查询是空 铁律 10:UI 视觉与业务查询必须同步。"TODO: 暂留空"是定时炸弹
v0.10.19 列宽 stale closure + columns prop 引用不稳定 铁律 11:setState 用 functional 避免 stale;prop 传数组/对象用 useMemo 保稳定
v0.10.20 useMemo deps 含 object/array 但调用方传不稳定引用 → memo 形同虚设 铁律 12:useMemo deps 含 array/object 时,用字符串签名 arr.map(...).join(',') 做稳定 key;不能假设调用方一定 useMemo
v0.10.20 hasEmailOnly 在 taskId 分支「先分页再过滤」分页错乱 铁律 13:分页 + 过滤必须「先过滤再分页」,反过来数学上不等价
v0.10.20 修 ISSUE-0010 写了 useMemo 但没回到浏览器实测 → 没修到根 铁律 14:写 fix 后必须实测复现。"修了"≠"修好了",必跑 happy path 验证
v0.10.21 设置页双滚动条 v0.10.18 修不彻底,二次撞 → 父级 main-layout 已 overflow:auto,settings 又加 overflow → 双条 铁律 15:修嵌套滚动 bug 必须查父级链。每一层父级的 overflow / height 都要看清楚
v0.10.21 同上 — 子组件不应假设自己是页面根 铁律 16:「让父级负责滚动」是更稳的模式。子组件高度自适应内容,比硬撑高度自滚动更不易与父级冲突
v0.10.136 给测试做变异自测,python replace 锚点打在同名的另一处调用上,主路径没被变异 → 全绿 → 误判「这条测试是假闸」 铁律 17:变异自测必须先证明变异真的改到了文件(改前后 md5 不同才继续),并用内容匹配而非行号定位。replace / sed 不匹配是静默 no-op,产出的「全绿」量的是「我没改动它」,不是「闸不生效」。同一符号先 grep -n 数清有几处调用
v0.10.136 第一版只 path-scoped 提了 package.json,pnpm-lock.yaml 留在工作区 → HEAD 装不起来(ISSUE-0112) 铁律 18:path-scoped 提交要按「逻辑单元」列全清单,不是按「我编辑过的那个文件」。并行会话纪律禁 git add -A 是对的,但它按路径过滤——挡住别人的在制品的同时也挡住了自己的配套文件。已知原子对:deps↔lock、version↔docs/_overview.md、frontmatter↔docs/_index.tsv、表定义↔version bump
v0.10.137 写 offscreen 并发测试,「connect 一次都没被调用」误判了三轮(mock 坏了 / TDZ / 预热顺序),真因是 fake timers 与动态 import 铁律 19:测试跑不起来时先做「同文件内对照实验」,别改代码试。把已知能跑通的最小形态原样塞进出问题的文件,一次就分开「文件/mock 的问题」和「代码形态的问题」。三条已坐实的事实:① vi.useFakeTimers() 之下 await import() 不 resolve;② 纯 microtask 循环推不动动态 import,flush 必须含宏任务 tick;③ 固定 tick 数在全量跑时 flaky,要改 waitFor(cond) 条件轮询。压缩超时靠参数默认值注入(同 withDbInitTimeout),不靠 fake timers
v0.10.138 PageMarkdown 建表 + DB version 5→6,此后不可回退 铁律 20:撤掉一张已上线的表只能「停止写入 + 保留表定义」。从 jsstore 的 tables 数组里删掉 = 该 store 被 deleteObjectStore 静默删掉(worker :642),不报错不提示。同理:version 单向,bump 前必须先把最后一个可回退版本备份好并标注边界(见 backup/README.md 与 version-rollback-boundary)。附属表的级联删除顺序不能反 —— 收集外键必须在删主表之前,挪到后面就是查已删的行、返回空数组、级联静默失效
v0.10.141 回归测试用例构造不到被测代码的触发条件 ⇒ 去掉被测代码照样全绿(假闸第二形态) 铁律 21:写完一条回归测试,先问「这个用例真的走到那段代码了吗」。铁律 17 治的是「变异打偏没改到文件」,这条治的是「文件改对了、但用例根本触发不了」—— 两者都表现为变异后全绿,读代码看不出来,只能靠变异自测。实证:⑧b 的宽 key 去重要「候选 >5」才触发,而用例里 maps 优先把三对写法合并成 4 个候选,怎么改被测代码都不红。判据:变异自测里若某条变异全绿,先假设是自己的用例没触发,而不是「这段代码没被测到的价值」
v0.10.142 电话来源分类的四方案对抗论证:四个方案全部被找出致命缺陷,且失效点高度重合 铁律 22:拿一个「被上下文参数化的函数」当联接键,等于把最易变的算法冻进数据。canonKeyForDedupe 看着像一把尺,实际写入口与展示口的 primaryCC 是两个不同公式(v0.10.142 起更是如此),而写时那个上下文被合并本身销毁了 —— 四个方案里三个栽在这上面(A 的读时匹配、B 的 join key、D 的「复用同一把尺」)。判据:落库的键必须能在读时无歧义重建;重建依赖任何运行期上下文(行内其它值、配置、当期算法版本)就不合格。相关:给已有表加列的真实机理见 jsstore-add-column-mechanics,其中订正了「本项目从未加过列」这个失实结论(v0.9.9 加过 taskId 并栽了)
v0.10.143 同一轮里连出两个假闸(第 7、8 个),形态相同 铁律 23:测一个判据,就得构造一个「只有它能救」的场景。顺手写的"典型场景"往往同时满足多个判据,于是变异掉其中任何一个都不红 —— 测的是"这组输入能跑通",不是"这个判据有贡献"。两次实证:① 两口同源测试拿写入口产物喂展示口,而产物已去重过、展示口不会再合并 ⇒ 换成行级公式照样绿;② 写入口用例里都有带 + 的号,第三级反哺就够用 ⇒ 变异掉 countryCode 照样绿。判法:写完一条断言先问「把我要测的那个判据删掉,这条会红吗」,答不上来就去跑变异。与铁律 17(变异打偏没改到文件)、铁律 21(用例触发不到代码)合为假闸三形态
v0.10.148 用被测常量构造测试输入 ⇒ 测试自适应,改被测值也不红(假闸第四形态) 铁律 24:测试输入里不许出现被测的那个值。写「窗口上限」这类边界断言时,若拿被测常量去构造输入('x'.repeat(LOOKBEHIND)),被测值一改输入也跟着改 —— 两边永远保持同样的相对关系,变异怎么改都绿。实证:回看窗口 64→500 的变异被整个放过去。改法:写死一个夹在「当前值」与「变异值」之间的字面量(PAD = 100),并补一条 expect(被测常量).toBeLessThan(PAD) 锁住这个前提 —— 否则哪天窗口调大过 PAD,上面那条又会失去意义。与铁律 17(变异打偏)、21(用例触发不到)、23(断言不全)合为假闸四形态
v0.10.158 变异自测跑了三路,全是假的 —— zsh 不做词分割,多文件 filter 变成一个不存在的路径,vitest 报 No test files found 退出 1(假闸第五形态) 铁律 25:变异自测必须先看「未变异时是不是绿的」,并核对测试条数。zsh 与 bash 的关键差异:T="a.ts b.ts"; vitest run $T 在 bash 里分成两个参数,在 zsh 里是一个参数 ⇒ 匹配不到任何文件 ⇒ 0 个测试跑过、退出码 1。而我只 grep 'Tests ' 看到空输出,就当成「测试红了 = 变异咬住」。三条判法:① 每轮变异前先跑一次未变异的对照,把「Tests N passed」的 N 记下来;② 变异后的输出必须出现 Tests X failed \| Y passed (N),且 N 与对照相同 —— N 变小或没有这行,就是根本没跑;③ 别用 grep 判成败,grep 匹配不到和测试没跑是同一个空输出。前四形态治的是「测试没守住」,这条治的是「测试压根没跑,而我以为它跑了」——比前四条更隐蔽,因为它连红的样子都装出来了
v0.10.163 把「terra-dsh 填 GO 但正文写 P0」当成事实报了出去 —— 实查两路字段与正文都一致,矛盾根本不存在;错在用 grep -ah 一次读两份交付、按参数顺序假设归属 铁律 26:用搜索工具取证时,「搜索域」是结论的一部分,必须交代清楚。三个同族实例:① 铁律 25 —— grep 匹配不到 与 命令根本没跑 是同一个空输出(域=「有没有输出」);② 本条 —— grep -ah "^X_VERDICT=" a.log b.log 不打印文件名 ⇒ 「哪份是谁的」只能靠参数顺序假设,而假设被当成了事实(域=「哪份」);③ 并行会话同日实证 —— 拿一个符号 grep 整个文件得 9 次、只看函数体内得 0 次,两个数都对,粒度选错结论就反过来(域=「哪一段」)。⇒ 共同形状:把「读数工具的形状」当成了「事实的形状」。三条判法:① 多文件读数不许用 -h,或拿到结论后回单文件复核;② 报「命中 N 次」必须同时报搜索域(整文件 / 某函数 / 某段落);③ 任何「哪个是哪个」的归属判断,来源必须是带标识的输出,不是相邻位置的推断。危害等级:本条的误报被写进文档、commit message,还发给了并行会话并被对方据此实现了一条工具判据 —— 假情报会跨会话传播,且比本地错误更难召回
v0.10.164 并行会话实证:zsh 里 path 是 $PATH 的数组别名,while read -r meta path 直接摧毁 PATH ⇒ 后续 git update-index 全部 rc=127 一条没跑,而循环里自己的 printf "恢复 xxx" 照常打印 ⇒ 看起来全成功,实际零执行 铁律 27:判成败只能用被测命令自己的 rc 或副作用,不能用自己拼的字符串。这是铁律 26「把读数工具的形状当成事实的形状」最狠的变体 —— 前两次是读错了(域没交代清楚),这次是输出根本不来自被测命令。同族三例:① 铁律 25 —— grep 匹配不到与命令没跑是同一个空输出;② v0.10.163 —— python3 … | tail -5; echo $? 取到的是 tail 的退出码,恒 0 ⇒ 永远"干净";③ 本条 —— 循环体自己的 printf 冒充了 git 的回显。判法:① 成败判据必须是被测命令的 rc(不走管道,或 bash ${PIPESTATUS[0]} / zsh $pipestatus[1])或磁盘副作用(文件真存在、内容逐字节比对);② 自己的 echo/printf 永远不算证据;③ 🔴 zsh 禁用变量名:path cdpath fpath manpath status argv options —— 它们与 shell 内部数组绑定,赋值即破坏环境(bash 无此绑定,只在 zsh,而本仓 shell 是 zsh)。实证救场手段:对方最后靠 git ls-files --stage 逐条比 blob hash 才发现,那正是"验副作用"
v0.10.165 同一个「读源码文本做断言」的测试,三轮各挖出一个缺陷,形状完全一样:固定 400 字符窗口被新注释挤爆(假红)→ 改成「锚点之后第一个调用」被 decoy 骗(假绿)→ 改成「锚点后恰好一个」仍被「真调用放在锚点之前」骗(假绿) 铁律 29:任何以「位置」为锚的断言,都要问另一侧有没有盲区。「第 N 个」「之后的」「窗口内的」——这类锚点天然只约束一侧。三问:① 它想拦的缺陷是什么?② 有没有等价改写让它假绿(该拦没拦)?③ 有没有排版改写让它假红?🔴 三问权重不等:假红会自己暴露(测试红了有人看),假绿永远不会自己暴露,所以第 ② 问的权重远高于另外两问。改法:锚到结构而不是位置 —— 本条最终改成「锚点所在整个函数体内 AST 全收集 + 调用数量 + 逐要素载荷断言」,五组变异(原 bug / 锚点后 decoy / 锚点前真调用 / 等价排版 / 恢复)全部咬住。⚠️ 残留自查不能用 git diff(该文件本来就带未提交改动,diff 非空是正常的),要用变异前后 sha256 逐字节相同
v0.10.166 给「建任务时入库失败」加了 error 级留痕,两家审查方同时报出:那个 catch 在生产中永远不触发 —— insertMany 把 DB 失败吞成 {success:false} 返回值、根本不抛,而调用方在用 try/catch 等异常 铁律 30:同一个模块的导出,失败表达方式必须统一;混用时每个调用点都是一次赌博。实证:jsstore/base.ts 有吞型 4 个(selectAll/insertOne/insertMany/clearData 返回 {success:false})与抛型 5 个(selectByQuery/removeByQuery/countByQuery/updateByQuery/initJsStore)混用,由此产生两类误用:「用 try/catch 等一个不抛的函数」3 处、「不检查返回值就往下走」5 处。🔴 死 catch 比没有 catch 危险 —— 它让读代码的人以为这条路径有保护,也让审查时「有没有错误处理」这一问得到假的肯定答案;而没有 catch 至少一眼看得出没处理。可机械检查:列出模块所有导出标注吞/抛 → grep 调用点 → 抛型必须有 try/catch 或明确传播、吞型必须检查返回值;吞型外面包着 try/catch 的,那个 catch 十有八九是死的。⚠️ 连带教训:为死 catch 写的测试会用 mockRejectedValue 构造生产中不可达的场景,给出虚假覆盖信心 —— 与铁律 29 的假绿同源,只是这次假在 mock 比被测物宽
v0.10.170 用切片替换改测试文件(s[:A起点] + 新内容 + s[B起点:])时,把夹在 A 与 B 之间的另一个完整用例整个删掉;而同一轮又新增了一个用例 ⇒ 28 passed 纹丝不动,删除被总数掩盖,直到对抗审报「某条契约零断言」才发现 铁律 31:核对测试条数要核【组成】,不是总数。总数对「等量替换」完全失明 —— 删一个加一个,数字不变。判法:改完测试文件后跑 grep -oE "it\('[^']+" <file> 列出用例名逐个比对,或用 git show <基线>:<file> 做集合差。🔴 切片替换尤其危险:s[:start] + new + s[end:] 会吞掉 start 与 end 之间的一切,而你只想改 start 那一段 —— 用精确的 str.replace(旧全文, 新全文, 1) 并断言 count==1,不要用索引切片。⚠️ 这条与铁律 25(变异自测必须核对测试条数)是同一族:25 防「测试压根没跑」,31 防「测试被换掉了而数字没变」
v0.10.181 变异还原的 cp 备份把真改动一起抹了 —— 声称改了两处 helper,实际没进提交,而 vitest/tsc/verify/build 全绿 铁律:变异还原的备份每轮重做,不许跨轮复用;还原后要验「只还原了变异」而不是「测试变绿了」;凡声称「改了 X」,收尾前 git show <sha> \| grep 逐条核。见 0156-mutation-restore-wiped-a-real-edit
v0.10.183 变异验证用 git diff --numstat 判「变异写进去了吗」,而它对比的是 HEAD 本轮有未提交改动时该判据恒为真、证明不了任何事 ⇒ 改用与备份文件 diff;判据要量的是「这一次改动写进去了吗」
v0.10.186 后台等待循环空转 3 小时 40 分 —— until grep X_VERDICT /tmp/fg-terra.log 等的是【派工日志】,而裁决落在 briefs/<label>.txt【产出文件】;重派时还用 > 覆盖了那个日志,条件永远不成立 铁律:任何 until/轮询必须①判据指向【真正会变的那个文件】②带超时上限。判据写错时,有上限的循环会响亮退出,没上限的就是无声空转 —— 而它看起来一直在工作。🔴 与同版修的 truncated 恒真(0158-truncated-flag-measured-the-wrong-thing)是同一枚硬币两面:恒真的告警和恒假的等待条件,都不会报错、都在假装自己有用。同日第三次「判据在量别的东西」。⚠️ 杀它时先撞到另一个坑:pgrep -fl "X_VERDICT" 命中的是别的项目正在跑的 dsh 进程(任务书正文含该词)—— 按模式杀就是跨项目误杀,必须 ps 列出候选、核对命令行、按 PID 精确 kill

📋 改进流程的扩展版

把第四章「标准更新流程」第 1 步细化为:

  1. 读源码语义(A 节)—— 任何要改的设置/调度,先打开对应源码看顶部注释和实际逻辑
  2. 扫本清单(A→E)—— 2 分钟
  3. 读 development-log.md 最近 3 条记录,避免和最近的改动冲突
  4. 然后才开始改代码

铁律 · 过滤条件要放在查询侧,不是消费侧(v0.16.10 · ISSUE-0193)

「卡」这个家族到 v0.16.10 已经复发四次,每次换个位置、形态一模一样: 把几万行搬进内存,再扔掉其中 99%。

次 位置 形态
ISSUE-0188 详情页 useMemo 展开 40 万条笛卡尔积 × 每 2 秒
四审 F2 统计路径 select 无 limit
ISSUE-0192 详情页轮询 每 2 秒查 5 次、29,594 行、主线程
ISSUE-0193 combos useMemo / combosOfTask 走表路径没早退;状态过滤放在消费端

判据一句话:这条查询拿回来的行,有多少会被立刻扔掉? 超过一半就是放错了侧。

🔴 已建机器闸 pnpm scan:unbounded-query(挂在 verify 的 --diff 模式): 扫 select/selectByQuery 参数里没有 limit 的调用。 豁免要写理由 // SAFE: unbounded-ok — <为什么这张表不会大>, 「它现在不大」不是理由 —— ISSUE-0192 那张表写的时候脑子里是三五百行, 用户手上是 29,594 行,而 jsstore 跑在主线程。

⚠️ 截断方向要挑安全的那侧:少认出几个「搜过的」= 多搜一次(看得见), 少跑几个组合 = 静默漏采(看不见)。宁可多搜,不可漏采 —— 所以 combosOfTask 明确不设上限,而 searchedComboKeysSince 设。

铁律 · 别在响应通道里 await 长任务(v0.16.10 · ISSUE-0193)

MV3 的 service worker 会在 await 期间被回收,通道一断 UI 就收到 message channel closed —— 于是一次成功的操作被报成失败。 删任务的主体(removeTask)早就成功了,报红的是后面那趟 82,437 行的级联删除。

⇒ 主操作一完成就让响应返回,附属清理一律 fire-and-forget(catchAndLog)。 判据:这个 await 的耗时上界取决于用户的数据量吗? 是 ⇒ 移出响应路径。

铁律 · 修「假失败」之前,先看 UI 文案承诺了什么(v0.16.11 · ISSUE-0194)

v0.16.10 把删任务的级联清理移出响应路径,治好了「删除失败:message channel closed」—— 然后 notice.success('已删除 N 个任务(含商家数据)') 原样留着,而数据是后台在删。

假失败让人虚惊一场;假成功让人以为删干净了。后者更糟。

⇒ fire-and-forget 能成立的前提是有人续跑(持久化队列 + SW 启动时 resume), 没有续跑它就只是「这趟没被打断就删、被打断就永远不删」,而用户已经被告知成功了。 判据:这个 await 移出响应路径后,它失败了谁会知道?没人知道 ⇒ 缺续跑机制。

铁律 · 变异验证要变异调用点,不只是被测函数(v0.16.11 · ISSUE-0194)

四路审查 B 路实测:把详情页的 fromTable 写死成 false, shouldBuildLegacyCombos 的 2³ 矩阵判据全绿,而用户实测的那个卡当场复发。

纯函数全绿 ≠ 生产路径没坏。本仓第二次踩「判据没测真正的承重点」。

⇒ 每抽一个纯函数出来做判据,同时问:谁调它?把调用点改坏,判据会红吗? 调用点常常只能上源码判据(依赖运行时的值造不出来)—— 源码判据弱, 但有总比那一格空着强:空着的代价是被修好的 bug 可以无声回来。