Why

/why — 错误根因诊断与纠正

通用根因分析框架

你是一个诊断 agent。用户报告了一个问题。在查任何具体清单之前，先完成以下四步思考：

1. 找到这个问题的根本原因

不要停在表面症状。追问：

• 这个错误是怎么产生的？（操作失误？逻辑假设错误？工具误用？）
• 在哪一步发生的？（编辑时？构建时？渲染时？设计时？）
• 如果不是第一次发生，上次是怎么修的？修完为什么又出现了？

2. 找到其他类似的错误

这个错误很可能不是孤立的。主动搜索：

• 同一文件或同类文件中是否有相同模式的错误？
• 同一机制（同一插件、同一脚本、同一约定）的其他地方是否也有问题？
• 修复这里时是否会引入新的同类错误？

3. 反思为什么会发生

• 是哪个环节的假设出了问题？（比如：以为行号稳定，其实不稳定；以为正则覆盖所有格式，其实只覆盖主格式）
• 是什么习惯或捷径导致了这个错误？（比如：改完没验证；凭记忆写路径；猜测语义而不查原文）
• 这个错误在什么条件下会被遮蔽、不容易发现？

4. 如果以后要不再出现，应该改变什么

• 是否需要在流程中加一个检查步骤？
• 是否需要更新某个 skill 或规范文档？
• 是否需要修改工具/脚本，让它自动拦截这类错误？
• 是否需要在 CLAUDE.md 或 CONSTITUTION.md 中加一条约定？

完成上述思考后，执行修复，并在回复中明确写出：

• 根本原因（一句话）
• 已修复的内容
• 同类问题的排查结果
• 如果以后要避免，需要做什么（若有具体行动，立即执行）

以下是常见错误类型的具体诊断清单，作为参考：

Step 0 — 快速分诊

读取用户的错误描述，匹配类别，直接跳到对应 Step：

项目结构自检（首次诊断时执行）：

# 找到 JS 主文件位置
find . -name "renderer.js" -not -path "*/node_modules/*" | head -5
find . -name "plugins.json" -not -path "*/node_modules/*" | head -5

# 确认 wiki 类型
ls docs/wiki/pages/ 2>/dev/null || ls site/wiki/pages/ 2>/dev/null || echo "未找到页面目录"

Step 1 — 系统崩溃诊断（JS/CSS 语法、插件加载）

触发：页面卡在"载入中"、SPA 白屏、JS 完全不运行、模块加载失败。

# 通用：找所有 JS 文件并检查语法
find . -name "*.js" -not -path "*/node_modules/*" -not -path "*/.git/*" | \
  xargs -I{} node --check {} 2>&1 | grep -v "^$"

# 重点检查：主渲染文件和插件
# honglou/ai-history: site/wiki/js/ 和 site/wiki/plugins/
# tongjian/three-body/shiji-kb: 路径相似，按项目调整
node --check "$(find . -name 'renderer.js' -not -path '*/node_modules/*' | head -1)"
node --check "$(find . -name 'main.js' -not -path '*/node_modules/*' | head -1)"

并发修改检查（若近期有多人/多 session 修改同一文件）：

git log --oneline -10
git diff HEAD~2 HEAD -- "$(find . -name 'renderer.js' -not -path '*/node_modules/*' | head -1)"

修复后验证：

node --check "$(find . -name 'renderer.js' -not -path '*/node_modules/*' | head -1)"

Step 2 — 渲染/标注异常诊断（引注、wikilink、插件渲染）

触发：PN 不显示、PN 出现在标题里、wikilink 渲染错误、特定前缀格式不识别。

2a — 标注位置错误

症状：PN / 引注出现在标题内，而非段落末尾。

# 检查 PN 是否写进了标题行（通用：检查各种 PN 格式）
grep -rn "^#.*（[0-9P][0-9][0-9]-[0-9]" docs/wiki/pages/ 2>/dev/null || \
grep -rn "^#.*（[0-9P][0-9][0-9]-[0-9]" site/wiki/pages/ 2>/dev/null

修复：PN 必须在段落末尾，不能在标题行。

2b — 特殊前缀格式不渲染

症状：（P03-002） 等特殊前缀显示为纯文本，不是可点击链接。

# 检查正则是否覆盖特殊前缀
find . -name "*.js" -not -path "*/node_modules/*" | xargs grep -l "pn-citation\|PN\|paragraph" 2>/dev/null
# 查看正则定义
grep -n "regex\|RegExp\|\\\d{3}" "$(find . -name 'pn-citation' -type d | head -1)/index.js" 2>/dev/null

修复：更新插件正则；在 chapter_map.json / 等价配置文件中补入缺失的映射条目。

2c — 标注标签完全不出现

根因：标注行前没有空行，与上一行合并为同一段落，插件正则匹配不到段落开头。

# 检查 PN 行前是否有空行（以 honglou 格式为例，按项目调整正则）
# find 兼容平铺和分桶
page_file=$(find docs/wiki/pages -name "PAGE.md" | head -1)
grep -n "^\[" "$page_file" | head -20

修复：在所有标注行前补空行。

2d — wikilink 语义错误

症状：书名/专名被错误拆分为多个 wikilink（如 [[记]][[西厢]]）。

根因：分词未考虑上下文，按字符拆分。

修复：书名/专名整体处理；有疑问时查原文再判断。

Step 3 — 内容结构问题（冗余、位置错误、格式不符）

触发：内容重复显示、段落顺序不符规范、结构位置错误。

3a — 内容冗余

症状：同一数据在页面出现 2-3 次（手工列表 + 动态 query + 静态缓存）。

# 检查页面是否同时存在多种数据来源
# find 兼容平铺和分桶
find docs/wiki/pages -name "year-*.md" -exec grep -l "query\|手工" {} \; 2>/dev/null | head -5

修复：只保留一种数据来源（优先动态 query 块）；删除冗余层。

3b — 结构位置错误

症状：标题、节、列表的顺序不符合项目规范。

# 检查页面结构（以 H2/H3 为骨架）
page_file=$(find docs/wiki/pages -name "PAGE.md" | head -1)
grep -n "^#" "$page_file"

修复：对照项目模板（local/template/）确认正确顺序。

Step 4 — 内容完整性（缺引文、缺字段、缺链接）

触发：页面缺少原文引用、frontmatter 字段缺失、人名/概念无 wikilink。

4a — 缺原文引文

症状：event/person 页面无 blockquote 原文引用。

# 检查页面是否有引文
page_file=$(find docs/wiki/pages -name "PAGE.md" | head -1)
grep -c "^>" "$page_file"
# 在 sentence_index 中搜索相关内容（路径按项目调整）
grep -r "关键词" wiki/data/sentence_index/ 2>/dev/null | head -5

修复：查 sentence_index；找到原文后以 blockquote 格式引用，加 PN 标注。

4b — 缺 wikilink 和标注

症状：concept/event 页面提到人名/概念但无 [[]]；页面无任何 PN 引用。

# 检查页面是否有 PN
page_file=$(find docs/wiki/pages -name "PAGE.md" | head -1)
grep -c "（[0-9P][0-9][0-9]-[0-9]" "$page_file" 2>/dev/null || echo "0"

修复：

1. 用关键词搜索 sentence_index，找书中实际段落
2. 若书中有提及：引用原文，加 PN
3. 若书中未提及：建 stub 页面，加 [[wikilink]]

4c — frontmatter 字段缺失

# 检查 frontmatter 完整性
page_file=$(find docs/wiki/pages -name "PAGE.md" | head -1)
head -20 "$page_file"

修复：对照项目 CLAUDE.md 中定义的 frontmatter 字段补全。

Step 5 — 视觉/交互问题（CSS 布局、可选中性、可点击性）

触发：样式异常、布局错位、元素不可点击、文本不可选中。

5a — 元素不可点击

常见根因：

• pointer-events: none 作用域过大，连带禁用子元素
• z-index 遮挡

# 查找 pointer-events 设置
find . -name "*.css" -not -path "*/node_modules/*" | xargs grep -n "pointer-events" 2>/dev/null

5b — 文本不可选中

常见根因：用 CSS ::before 伪元素生成文本，浏览器无法选中伪元素内容。

find . -name "*.css" -not -path "*/node_modules/*" | xargs grep -n "::before\|content:" 2>/dev/null | grep -v "//\|/\*"

修复：改为在 DOM 中注入真实文本节点。

5c — 布局错位

常见根因：float 未清除（clearfix 缺失）、CSS 路径错误导致样式未加载。

# 检查 CSS 文件是否实际存在
find . -name "*.css" -not -path "*/node_modules/*" | head -10
# 检查 HTML 中的 link 路径
grep -r '<link.*\.css' site/ 2>/dev/null | head -10

5d — 视觉参数问题（颜色、透明度）

find . -name "*.css" -not -path "*/node_modules/*" | xargs grep -n "opacity\|color\|background" 2>/dev/null | grep -v "//\|/\*" | head -20

Step 6 — 工序/流程问题（步骤顺序、管线不完整）

触发：局部修复无效、同类问题反复出现、某个功能从未正常工作过。

识别特征：

处理方式：不做局部修复，而是：

1. 识别哪个上游步骤被跳过或未完成
2. 回到该步骤重新执行
3. 确认上游完成后，再处理下游

# 检查项目关键文件是否存在（管线完整性）
ls local/config/why.config.md 2>/dev/null && echo "config: OK" || echo "config: 缺失"
ls BIRTH.md 2>/dev/null && echo "BIRTH: OK" || echo "BIRTH: 缺失"
ls wiki/scripts/add_page.py 2>/dev/null && echo "add_page: OK" || echo "add_page: 缺失"

Step 7 — 根因匹配表 + 修复确认

根因匹配速查

修复确认

# JS 修改后
node --check "$(find . -name 'renderer.js' -not -path '*/node_modules/*' | head -1)"

# 内容批量修改后（若项目有注册表脚本）
find . -name "build_registry.py" -not -path "*/node_modules/*" | head -1 | \
  xargs -I{} python3 {} 2>&1 | grep -i "warn\|error" | head -20

# 查看改动范围
git diff --stat

# 确认没有引入新的语法错误
find . -name "*.js" -not -path "*/node_modules/*" -not -path "*/.git/*" | \
  xargs -I{} node --check {} 2>&1 | grep -v "^$"