# Why

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

- Skill: `orangeviolin/why` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add orangeviolin/why`
- Raw SKILL.md: https://api.skillmd.com/api/skills/orangeviolin/why/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: OrangeViolin (https://skillmd.com/u/orangeviolin)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/orangeviolin/why

---


# /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 |

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

```bash
# 找到 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 完全不运行、模块加载失败。

```bash
# 通用：找所有 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 修改同一文件）：

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

**修复后验证**：

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

---

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

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

### 2a — 标注位置错误

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

```bash
# 检查 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）` 等特殊前缀显示为纯文本，不是可点击链接。

```bash
# 检查正则是否覆盖特殊前缀
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 — 标注标签完全不出现

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

```bash
# 检查 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 + 静态缓存）。

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

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

### 3b — 结构位置错误

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

```bash
# 检查页面结构（以 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 原文引用。

```bash
# 检查页面是否有引文
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 引用。

```bash
# 检查页面是否有 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 字段缺失

```bash
# 检查 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 遮挡

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

### 5b — 文本不可选中

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

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

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

### 5c — 布局错位

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

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

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

```bash
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. 确认上游完成后，再处理下游

```bash
# 检查项目关键文件是否存在（管线完整性）
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 |

### 修复确认

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