跳转至

Issues 索引（已知问题与改进方案）

每个已经发生过的问题都在这里归档。

🎯 用途： - 🤖 AI 改代码前查这里，避免重蹈覆辙 - 👨‍💻 人排查类似症状时一眼对上号 - 📚 形成"踩坑知识库"，越用越值钱

状态图例

状态 含义
✅ 已修复 修复版本已发布
🔧 修复中 当前版本正在修
⚠️ 已知未修 已记录，未来再修（可能是低优先级或权衡决策）
🔄 反复出现 修过又犯 → 已写入 version-release-iron-rules.md 第七章铁律

严重度图例

图标 含义
🔴 严重 用户卡死 / 崩溃 / 无法使用
🟡 中等 功能不可用但有 workaround
🟢 轻微 体验问题 / 文案 / 工具

全部问题（按出现时间倒序）

ID 标题 状态 严重度 首现 修复 类别
0001 主面板「立即登录」点击无反应 ✅ 🔴 v0.10.2 v0.10.17 登录
0002 Popup 启动后 loading 骨架屏永久卡住 ✅ 🔴 v0.10.7 v0.10.16 登录/UI
0003 长时间运行后浏览器卡死/累积孤儿 Tab ✅ 🔴 v0.10.0 v0.10.15 调度/性能
0004 设置字段命名望文生义 🔄 🟡 v0.10.0 v0.10.12 / v0.10.14 UI/命名
0005 Edit 工具改含中文标点的旧代码反复失败 ✅ 🟢 v0.10.13 v0.10.13 工具
0006 「有邮箱」chip 选中但表格未过滤 ✅ 🔴 v0.10.1 v0.10.18 UI/数据
0007 设置页右侧出现两个滚动条 🔄 🟡 v0.10.0 v0.10.18（不彻底）→ v0.10.21 UI
0008 商家列表单行高度过大 ✅ 🟢 v0.10.0 v0.10.18 UI/设计
0009 国家标识用文字「US」而非国旗 ✅ 🟢 v0.10.0 v0.10.18 UI/优化（Unicode emoji）
0010 拖动表格列宽后被自动重置 ✅ 🟡 v0.10.0 v0.10.19 UI/持久化
0011 商家详情 Drawer 视觉平淡 ✅ 🟢 v0.10.0 v0.10.19 UI/设计
0012 taskId + 有邮箱 chip 分页错 ✅ 🔴 v0.10.18 v0.10.20 数据/分页
0013 v0.10.19 列宽 fix 没修到根 ✅ 🔴 v0.10.19 v0.10.20 UI/性能
0014 列宽/列序多账号污染 ✅ 🟡 v0.10.0 v0.10.20 数据/多账号
0015 watchdog 鲁棒性三连 ✅ 🟡 v0.10.15 v0.10.20 调度/资源
0016 RatingStars 异常输入崩 ✅ 🟢 v0.10.19 v0.10.20 UI/防御
0017 Popup timeout 与 uid race ⚠️ 🟢 v0.10.16 — UI/状态机
0018 hasEmailOnly 50k 上限截断 ⚠️ 🟢 v0.10.18 — 性能/容量
0019 FormProvider flex 潜在副作用 ⚠️ 🟢 v0.10.18 — 布局
0020 设置页双滚动条二次修复（v0.10.18 不彻底） ✅ 🟡 v0.10.0 v0.10.21 UI/布局
0021 状态 chip 参差不齐（建议靠右） ✅ 🟢 v0.10.0 v0.10.22 UI/设计

按类别

登录 / 认证

  • 0001 — background open-login 用 force=false 跳过开窗（v0.10.17 修）
  • 0002 — popup loading 无超时（v0.10.16 修）

同源教训：stale token 场景反复出现。任何"已登录就跳过"逻辑必须考虑 token 可能已过期。

调度 / 性能

  • 0003 — 缺 watchdog 巡检（v0.10.15 修）

UI / 命名

  • 0004 — 字段名 ≠ 实际语义（已成铁律）

工具 / 工作流

  • 0005 — Edit 全角/半角不归一化（已有兜底方案）

新增 issue 的 checklist

每次踩坑必须落档。流程：

  1. 用 _template.md 起手
  2. 文件名格式：<编号>-<简短标题>.md，编号 4 位数字（0001 / 0002 / ...）
  3. 头部元数据完整填（状态/首现/修复/严重度/类别）
  4. 「用户感知的现象」用用户原话引用块 — 让未来 AI 一眼对上号
  5. 「如何避免再犯」是最重要一节 — 提炼成可执行 checklist
  6. 回到本 INDEX 加一行
  7. 如果是「反复出现」 → 在 version-release-iron-rules.md 第七章铁律里也加一条

与其它文档的关系

文档 与 issues 的关系
../changelog/development-log.md 按版本记，含本次改动 → issues 按问题记，跨版本追踪同类
docs/wiki/ 描述「系统怎么工作」 → issues 描述「系统怎么坏过」
docs/rules/ 描述「该怎么做」 → issues 描述「曾经怎么错过」
version-release-iron-rules.md 第七章 铁律提炼 → issues 是铁律的「案例库」

简单类比： - wiki = 教科书 - rules = 操作手册 - issues = 真实案例 + 复盘报告

改进流程

每完成一个版本： 1. 把本次修的所有 bug 落档到 issues 2. 严重的 / 反复的 → 同步更新 version-release-iron-rules.md 第七章 3. 涉及新模块/架构变化 → 同步 wiki 4. 用了新工具 → 同步 rules 5. 在 ../changelog/development-log.md 加一行 "本次新增 issue：#xxxx, #yyyy"

全部 issues（按编号）

ID 标题 状态 严重度 tags 链接
0001 主面板「立即登录」按钮点击无反应 fixed critical issue, auth 打开
0002 Popup 启动后 loading 骨架屏永久卡住 fixed critical issue, auth 打开
0003 长时间运行后浏览器卡死 / 累积孤儿 Tab fixed critical issue 打开
0004 设置字段命名望文生义，与实际语义矛盾 fixed medium issue, settings 打开
0005 Edit 工具改含中文标点的旧代码反复失败 fixed minor issue, tooling 打开
0006 [ISSUE-0006]「有邮箱」chip 选中但表格未过滤 fixed critical issue, ui 打开
0007 设置页右侧出现两个滚动条 fixed medium issue, settings 打开
0008 商家列表单行高度过大 fixed minor issue 打开
0009 国家标识用文字「US」而非 SVG 国旗 fixed minor issue 打开
0010 拖动表格列宽后被自动重置 fixed medium issue 打开
0011 商家详情 Drawer 视觉平淡 fixed minor issue, ui 打开
0012 taskId + hasEmailOnly 同时启用时分页错乱 fixed critical issue 打开
0013 列宽 fix 的 useMemo 形同虚设（v0.10.19 修复不彻底） fixed critical issue 打开
0014 列宽 / 列序 storage key 未按账号隔离 fixed medium issue 打开
0015 Watchdog 鲁棒性三连：并发触发 / nuke 不真关 tab / 计数残留 fixed medium issue, scraping 打开
0016 RatingStars 对异常 rating 输入不稳健 fixed minor issue 打开
0017 Popup 2s timeout 与 uid 到达的竞态 fixed minor issue, auth 打开
0018 hasEmailOnly 全表 50k 上限静默截断 fixed minor issue 打开
0019 FormProvider 强制 flex column 对 Dialog 表单的潜在副作用 fixed minor issue 打开
0020 设置页双滚动条 — v0.10.18 修不彻底（二次修复） fixed medium issue, settings 打开
0021 商家列表「已完善」状态 chip 参差不齐 fixed minor issue, ui 打开
0022 Extension context invalidated 错误未处理 fixed medium issue, chrome-extension, error-handling, mv3 打开
0023 mailto 链接 URL 编码 body 污染邮箱字段 fixed high issue, scraping, email, regex 打开
0024 扩展 reload 后 main.html tab 变成 newtab fixed medium issue, extension-lifecycle, sw, mv3 打开
0025 Google 验证拦截后用户感知 + 恢复体验差 fixed high issue, scraping, captcha, ux, scheduling 打开
0026 拦截恢复机制在 SW 重启时丢失状态 + setTimeout 不可靠 fixed high issue, mv3, sw, scheduling, captcha, state-management 打开
0027 watchdog 自动恢复 cooldown 用 setTimeout（SW kill 时丢失） fixed high issue, mv3, sw, watchdog, scheduling 打开
0028 doResumeFromInterception 只调 manageQueue 漏地图调度 fixed high issue, mv3, scheduling, captcha 打开
0029 DataView 浪费 IndexedDB taskId 索引 + onMessage listener 无 cleanup fixed medium issue, performance, react-lifecycle, indexed-db 打开
0030 use-countdown 双 useEffect + module-let interval 反模式 fixed low issue, react, lifecycle, hooks 打开
0031 第三轮 agent 找到 3 真 bug — watchdog 镜像 / 死 listener / 正则漂移 fixed high issue, mv3, react, scheduling, anchor-bias, pattern-replication 打开
0032 scan:protocol 基础设施 + open-results lost message + 死 messager 删 fixed medium issue, infrastructure, dead-code, protocol 打开
0033 第四轮 agent 找到 ISSUE-0031 第 4 兄弟 + 2 个孤儿 listener fixed high issue, mv3, dead-code, anchor-bias, control-flow 打开
0034 TypeError: Failed to fetch 冒到 chrome://extensions 错误日志 fixed medium issue, ext-context-guard, network, ux 打开
0035 「去创建任务」按钮点击无反应 — storage API 混用 fixed high issue, storage, api-consistency, ux 打开
0036 创建任务 toast 显示成功，但任务列表没增加 fixed high issue, storage, error-handling, ux, quota 打开
0037 州/省 API 加载失败被误显示为「该国家无州/省数据」 fixed high issue, ux, error-handling, network 打开
0038 地区选择城市列表右侧文字被截 + 鼠标滚轮无效 fixed medium issue, ux, layout, dialog, scroll 打开
0039 任务暂停/继续/停止/删除 按钮失败时用户无反馈 fixed medium issue, ux, error-propagation, user-action 打开
0040 第 6 轮 agent 发现 6 个真 bug —「补丁不彻底」家族 fixed high issue, error-propagation, anchor-bias, pattern-replication 打开
0041 第 7 轮 agent 验证 v0.10.58 — 还有 4 处漏（补丁不彻底续集） fixed high issue, error-propagation, anchor-bias, pattern-replication, writechain, webext-bridge 打开
0042 第 8 轮 agent — scan 工具盲区暴露 4 个新 bug + 扩 3 类新规则 fixed high issue, error-propagation, anchor-bias, scan-tool-blind-spot, pattern-replication 打开
0043 用户截图：选「1 国」整国采集，提交报「请选具体州/城市」— API shape 防御不够 + 错误消息误导 fixed high issue, api-shape, error-message-misleading, defensive-parsing, pattern-replication 打开
0044 用户截图 v0.10.52 集中反馈：缩放 / 按钮色 / 排序 / 分页 / 顶部 CTA / 文案 fixed medium issue, ux, theme, accessibility, pagination, sorting, cta-visibility 打开
0045 质量分真排序 — 撤 v0.10.64 sortable:false + 加 client-sort 路径 fixed medium issue, sorting, computed-field, jsstore, ux 打开
0046 质量分可配置 — 3 预设 + 5 维度权重 + 阈值 + 等级门槛 fixed medium feature, settings, quality-score, personalization 打开
0047 第 9 轮 agent — 质量分 config 3 处漏（init race / 改不刷新 / setValue 漏 catch） fixed medium issue, race, cache, async, anchor-bias 打开
0048 用户反馈：去掉顶部重复创建任务 CTA + 任务列表加「全部暂停」 fixed low issue, ux, cta-duplication, batch-operation 打开
0049 数据空状态「去创建任务」直接弹 Dialog（不跳页） fixed low issue, ux, prop-drilling, dialog 打开
0050 商家列表 chip count 截断 50k + 加载慢（22w 数据时） fixed medium issue, performance, jsstore, count, truncation 打开
0051 商家列表打开卡顿 — rows polling 5s + create_time sort 双重 IndexedDB 压力 fixed medium issue, performance, jsstore, indexeddb, polling 打开
0052 ext-context-guard 应在 import-time 装 listener（早期 fetch reject 漏过） fixed low issue, error-handling, race, listener-timing 打开
0053 A2：商家列表 client/server hybrid 模式（默认 client 瞬开 + server fallback） fixed medium issue, performance, refactor, indexeddb, hybrid 打开
0054 第 10 轮 agent — v0.10.73 A2 hybrid 6 处真 bug（数据安全 / 刷新失效 / page race / CTA 失效） fixed high issue, regression, race, data-safety, hybrid-mode 打开
0055 saveParams 治本：search.ts 接受 taskId/hasEmailOnly，撤销 v0.10.74 短期拦截 fixed high issue, refactor, data-safety, search-api, helper-extraction 打开
0056 第 11 轮 agent — v0.10.75 撤拦截后仍 4 个 quickFilter 漏 + 3 个性能/安全洞 fixed high issue, regression, data-safety, defense-in-depth 打开
0057 watchdog 自动恢复触发浏览器'确认关闭 N 个标签页'弹窗 fixed medium issue, ux, chrome-api, watchdog, confirm-dialog 打开
0058 长期改进 3 连击：task scan limit + optimistic delete + keyword 一致性 fixed low issue, improvement, optimistic-ui, consistency, scan-limit 打开
0059 useDataSource hook 大重构 — agent 元洞察治本 fixed low issue, refactor, hook, architecture, separation-of-concerns 打开
0060 第 12 轮 agent — useDataSource viewId 双拉 + state.sort 死代码 fixed low issue, polish, refactor-followup, dead-code 打开
0061 第 13 轮 agent — server mode page reset regression（v0.10.79 大重构丢的语义） fixed medium issue, regression, refactor-aftermath, semantic-loss 打开
0062 background SW 缺 unhandledrejection guard — chrome 错误面板冒出 [object Object] fixed low issue, error-handling, sw-context, defense-in-depth 打开
0063 商家列表首次 mount 闪'无数据' — rowsSnapshot 异步拉时空 CTA 错显 fixed medium issue, ux, loading-state, async-race, flash-content 打开
0064 第 14 轮 agent — polling 闪 + pageSize reset + SW sync error fixed medium issue, polish, pagination, polling, sw-guard, last-batch 打开
0066 dynamic-scraper.ts tabStatus/tabError Map 加 onRemoved 兜底清理 fixed low issue, memory-leak, mv3, dynamic-scraper 打开
0067 dogfood v0.10.87 暴露 4 项 — email 占位符 / phone 从未写库 / probe 403 / 缺 UI toggle fixed high issue, scrape, dogfood, email-blacklist, phone, long-standing-bug, ui, spec-004 打开
0068 dogfood v0.10.89 暴露 4 项 — 清空不刷新 / mstage 误显失败 / phone 去重漏 / 创建无 loading fixed high issue, dogfood, ux, mstage, phone, scrape-pipeline, spec-004 打开
0069 data-view HTTP 列 mstage 漏改 + 嵌套滚动条（部分修） in-progress medium issue, ui, mstage, multi-renderer, scrape-pipeline, spec-004, dogfood 打开
0070 共享窗口孤儿累积 — storage 漏写 + SW kill 竞态 fixed high issue, mv3, storage, sw-kill, scrape-window, ux 打开
0071 SPEC-006 cascade 删命中 ISSUE-0008 历史回归 — where:taskId 老 DB 给 0 行 fixed high issue, regression, jsstore, where, taskId, spec-006, code-review 打开
0072 cleanupOrphanScrapeWindows 误杀用户新标签页 — 尺寸阈值 ±80 太宽 fixed critical issue, ui-disaster, scrape-window, code-review, regression-of-fix 打开
0073 导出日志 JSON 版本号写死 + settings 未脱敏（含用户私域名/自建服务地址） fixed medium issue, export, privacy, version-hardcode, code-review 打开

按状态分组

✅ 已修复 (71)

🔧 修复中 (1)