why

name	why
description	系统性诊断和纠正错误。当用户报告任何 bug、视觉异常、内容错误时执行此 skill。

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

通用根因分析框架

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

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

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

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

2. 找到其他类似的错误

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

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

3. 反思为什么会发生

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

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

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

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

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

---

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

---

Step 0 — 快速分诊

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

关键词 / 症状	跳转
白屏、不加载、JS 报错、语法错误	Step 1
插件不工作、PN 不渲染、wikilink 异常	Step 2
内容重复、位置错误、结构不符	Step 3
缺引文、缺链接、缺字段	Step 4
样式异常、布局错位、不可点击、不可选中	Step 5
问题反复出现、局部修复无效、操作顺序错	Step 6

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

# 找到 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)"

症状	根因	修复
整个 app 不加载	JS 语法错误（多余/缺少 } )）	node --check 定位行号，检查括号平衡
部分功能不工作	注释块未闭合 /** 缺 */	grep -n "/\*\*" FILE 确认每个都有对应 */
插件加载失败	import 路径错误	检查插件目录路径；确认相对路径从文件位置起算
re-export 失败	插件移位后 re-export 路径未同步更新	检查 export { } from '...' 的路径是否对应新位置
插件不被识别	plugins.json 字段名错误（src vs entry）	查看 plugins.json 规范，统一字段名

并发修改检查（若近期有多人/多 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 — 工序/流程问题（步骤顺序、管线不完整）

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

识别特征：

特征	可能的工序问题
修复一处，另一处又出错	根因在上游，局部修复治标不治本
某功能自项目创建以来从未工作	管线迁移不完整，缺少关键组件
内容质量整体偏低，无法逐页修补	语料/模板问题，应回到上游处理
自动化逻辑在边界条件下崩溃	缺少 fallback 和边界检查

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

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 — 根因匹配表 + 修复确认

根因匹配速查

模式	关键特征	对应 Step
JS 语法错误	node --check 报错	Step 1
注释块未闭合	/** 无对应 */	Step 1
插件字段名错误	src vs entry	Step 1 / Step 2
标注在标题内	### 标题（NNN-PPP）	Step 2a
特殊前缀不渲染	P0x / 非标准格式	Step 2b
标注前缺空行	与上一行合并为一段	Step 2c
书名错误分词	wikilink 切割语义单元	Step 2d
内容三层冗余	手工+query+cache 并存	Step 3a
结构顺序错误	与模板不符	Step 3b
缺引文	无 blockquote 原文	Step 4a
缺 wikilink+PN	凭通识写成，未查索引	Step 4b
不可点击	pointer-events 误用	Step 5a
不可选中	CSS 伪元素生成文本	Step 5b
布局错位	float 未清除 / CSS 路径错	Step 5c
问题反复出现	工序顺序错误	Step 6

修复确认

# 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 "^$"