用户反馈前置查询¶

触发场景：每次用户报 bug / 提反馈 / 提需求。起因：本会话很多次"用户报 X → 我直接读源码 → 错过同款历史 ISSUE / agent code review 后才发现关联（如 ISSUE-0008 vs SPEC-006）"。目标：把 CLAUDE.md 的"先查 INDEX"从口号变成肌肉记忆。

总原则¶

用户反馈
  ↓
**第一动作**：grep 关键词查 issues/ + wiki/ + rules/
  ↓
**第二动作**：看 docs/_todo.md 是否已记录类似项
  ↓
**第三动作**：才开始读源码

关键：先看历史 = 节省后续重新发现 + 避免回归。

按反馈类型的具体命令¶

1. UI / 显示问题¶

# 看是否有同款历史 UI bug
grep -rn "<关键词>" docs/issues/ | head
grep -rinE "UI|显示|布局|样式" docs/rules/ | head -n 40

# 关键 rules（每次必看）
cat docs/rules/ui-change-pre-check.md       # 4 步清单
cat docs/rules/no-mutilation-fix.md       # 反例

例：用户报"chip 显示错位" → 先 grep -rn "chip" docs/issues/ → 找到 0021-状态chip参差不齐 → 看现有解决方案。

2. 抓取相关（HEAD / GET / tab / 多阶段）¶

cat docs/rules/scrape-pipeline-decision-table.md           # mstage 标签完整速查
grep -rn "mstage\|pipeline\|scrape" docs/issues/
ls docs/wiki/multi-stage-scrape-pipeline.md docs/wiki/domain-state-machine.md

例：用户报"matsudental.com 显示失败" → 应该 grep mstage docs/issues/ 找 0069 → 知道是 UI 漏改，不是真失败。

3. SW kill / 持久化 / 窗口 / Tab¶

grep -n -A 130 "^## 七、" docs/rules/version-release-iron-rules.md  # 改进前自查清单
grep -rn "SW kill\|持久化\|windows\|tab" docs/issues/ docs/wiki/
ls docs/wiki/tab-lifecycle-and-watchdog.md docs/wiki/ext-reload-lifecycle.md

例：用户报"几十个新标签页累积" → 应该 grep windows docs/issues/ + 看 wiki/Tab生命周期与看门狗 → 找到 0070 + 0072。

4. jsstore / IndexedDB / 数据库¶

grep -rn "jsstore\|where:\s*{\s*taskId\|enableSearch" docs/issues/ \
  src/utils/jsstore/search-data.ts  # ⚠️ 顶部注释是高频踩坑
cat docs/wiki/shared-queue-architecture.md

例：用户报"已删任务的数据还在" → 应该看 search-data.ts:67-91 注释（where:taskId 坑）+ ISSUE-0071。

5. 设置 / Settings 字段¶

# 改 settings 前必看（CLAUDE.md 明确）
cat docs/rules/settings-change-pre-check.md
cat docs/wiki/settings-field-semantics.md
grep -rn "settings\|enableXxx" docs/issues/ docs/wiki/

6. 调度 / 并发 / 队列¶

cat docs/wiki/shared-queue-architecture.md       # 字段语义与名字暗示常不一致
grep -rn "manageQueue\|pumpTasks\|controlTask" docs/issues/

7. 用户隐私 / 安全 / 导出¶

grep -rn "导出\|export\|脱敏\|sensitive\|redact" docs/issues/ docs/rules/

例：用户报"导出文件含我的私域名" → 找 0073 → 知道 v0.10.103 后已脱敏。

8. MV3 / 持久化 / alarms / 定时¶

cat docs/rules/version-release-iron-rules.md  # 第七章 + 历次大事件
pnpm scan:mv3                         # MV3 陷阱扫描
ls docs/rules/mv3-persistence-pitfall-checklist.md

9. 任意关键词（兜底）¶

# 总入口（按相关度）
KW="<用户提到的关键词>"
grep -rn "$KW" docs/issues/INDEX.md   # ISSUE 索引
grep -rn "$KW" docs/wiki/INDEX.md     # wiki 索引
grep -rn "$KW" docs/rules/            # 所有 rule
grep -rn "$KW" docs/_todo.md          # 已知待办

已修同款问题的标志¶

看到 ISSUE 含 audit_grep 字段说明已有自动检测：

audit_grep:
  - pattern: "旧模式"
    description: "旧模式不得恢复"
    expect: absent       # 默认；命中即违规
    paths: "src/foo.ts" # 可选；限定扫描范围
  - pattern: "关键 guard"
    description: "关键实现必须保留"
    expect: present      # 至少命中一次
    allow_paths: "src/entry.ts" # 仅 present；允许路径外命中也违规

修类似问题时应该： 1. 跑 pnpm scan:issue-coverage -- --strict — 同时确认 absent 零命中、present 至少命中，且没有越过 allow_paths 2. 加新 audit_grep 防退化（修类似但不同的 case）

反例（本会话漏查的）¶

用户反馈	我做了	应做	后果
matsudental.com "失败"	直接读源码	`grep mstage docs/issues/` → 找 0069	多花 5 分钟才理解是 UI bug
几十个新标签页	直接读 scrape-window.ts	`grep windows docs/issues/` + wiki	错过 v0.9.x SW kill 经验
清空不刷新	直接看 local-toolbar.tsx	`grep clearSearchData docs/issues/`	错过同 pattern 历史
SPEC-006 cascade 删	直接写 removeByQuery	应看 search-data.ts:67-91 + grep ISSUE-0008	命中老坑，agent 找到才修

工具支持¶

pnpm scan:issue-coverage          # 跑所有 ISSUE 的 audit_grep
pnpm scan:mv3                     # MV3 持久化陷阱
pnpm scan:error-handling          # 静默吞错检测
pnpm docs:check                   # frontmatter + INDEX 收录 + wikilink

这些检查由 scripts/hooks/pre-commit 按 staged 路径选择性触发，不是每次 commit 全量执行：

docs/ 或文档检查/重建脚本变更 → docs:check
docs/issues/ 或 src/ 变更 → scan:issue-coverage
background、scrape watchdog/window/executor、engine-manager、auto-login 变更 → scan:mv3 --diff
src/**/*.ts(x) 变更 → scan:error-handling --diff

hook 还会按路径触发其他专项扫描，并可被 git commit --no-verify 跳过。通过只表示本次实际触发的静态检查未发现阻断项，不等于功能没有回归；完整触发条件以 scripts/hooks/pre-commit 为准。

给 AI 的强提示¶

如果用户报问题但 AI 直接读源码没 grep INDEX： - ❌ 几乎一定会错过历史 - 90% 概率重复历史踩坑 - 修法可能跟过去不一致

正确流程：

用户报问题
  ↓
**MUST**：先 grep 关键词在 docs/issues/INDEX.md
  ↓
**MUST**：找到 ≥ 1 个候选 → 读那个 ISSUE 看是否同款
  ↓
**MUST**：看 audit_grep 字段判断是否已有防退化
  ↓
然后才看源码