来发信谷歌地图扩展 — 版本更新规则¶
本文件是本项目版本更新的总规范。每次更新前请先完整阅读本文件。 最后更新: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/。
四、标准更新流程¶
把上面三条规则串成一套固定动作,每次更新照着走。
- 读本文件 +
development-log.md,了解历史坑点。 - 【规则1】 执行备份命令,备份到
backup/。 - 【规则2】 在
development-log.md顶部新建一条记录,写下本次改动目标。 - 修改
package.json的version(如 0.8.37 → 0.8.38)。 - 修改源代码。
pnpm compile—— TypeScript 类型检查,无报错再继续。pnpm build—— 构建到dist/chrome-mv3/。- 【规则3】 浏览器加载 / 刷新,实测功能。
- 【规则2】 把过程中遇到的问题、解决方案、注意点补写进
development-log.md。 - (需要分发时)
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
- 从不:连续猜 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 步细化为:
- 读源码语义(A 节)—— 任何要改的设置/调度,先打开对应源码看顶部注释和实际逻辑
- 扫本清单(A→E)—— 2 分钟
- 读
development-log.md最近 3 条记录,避免和最近的改动冲突 - 然后才开始改代码
铁律 · 过滤条件要放在查询侧,不是消费侧(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 可以无声回来。