why

name	why
description	系统性诊断和纠正错误。当用户报告任何 bug、视觉异常、内容错误时执行此 skill。基于 wiki/doc/why.md 记录的根因模式进行排查。

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

此 skill 编码了 wiki/doc/why.md 中的所有根因模式，提供一套快速诊断-分析-修复的工作流。

使用方式

/why <问题描述>

例如：

• /why 页面加载卡在"载入中"
• /why 诗歌检测错了，第001回把非诗段标成了诗歌
• /why 对话底色看起来不明显

诊断流程

按优先级逐层执行，stop-on-first-hit：一旦找到根因即停止深入。

---

Step 1 — 语法健康检查（针对 JS/CSS 崩溃问题）

触发条件：页面卡在"载入中"、JS 完全不运行、SPA 白屏。

检查清单：

# 1. JS 语法检查（核心渲染文件 + 插件）
node --check docs/wiki/js/renderer.js
node --check docs/wiki/js/main.js

# 2. 常见语法错误模式（手工追加的 `}`、未闭合 `*/`）
#    从行号倒推出出错区域

已知高发故障模式：

症状	根因	修复方法
整个 app 不加载	JS 语法错误（多余/缺少 } )）	node --check 定位行号，检查附近括号平衡
部分功能不工作	注释块未闭合 /** → */	搜索 /** 确认每个都有对应 */
样式完全错乱	CSS 语法错误或选择器泄漏	检查是否有未闭合 {

修复步骤：

1. node --check 找到错误行号和描述
2. 读取附近 20 行
3. 修复后重新 node --check 确认通过
4. 若涉及注释未闭合，逐对扫描所有 /** 和 */

---

Step 2 — 视觉/布局检查（针对 CSS 问题）

触发条件：用户反馈"不好看"、"看不清"、"位置不对"、"间距不对"。

检查清单：

1. PN 标签：

   • 桌面端：是否浮动到 article 左侧（.pn-label { float: left; margin-left: -6.8em }）
   • 移动端：是否回到段首（@media max-width 覆盖）
   • 是否可选中/复制（不要用 ::before CSS content，用真实元素 + user-select: all）
   • 点击是否复制到剪贴板（navigator.clipboard.writeText）

2. 对话底色：

   • 选择器是否只包住「」内容而不是括号本身
   • 颜色是否足够明显（建议 rgba(210,155,40,0.22) 或更深）
   • 多段对话换行时的背景连续性

3. 诗歌样式：

   • poetry 段之间是否有多余间距（.chapter-poem { margin: 0 }）
   • 判定规则是否误判非诗歌段（检查端词是否为 ： 。」 ！」 ？」）
   • 浮动的 PN 在 poetry 段是否也左对齐

4. 标题：

   • H1~H6 内的 wikilink 是否视觉上去链接化（pointer-events: none; color: inherit; text-decoration: none）
   • TOC 中 heading 的链接是否指向独立页面（不要双 hash 格式）

5. 移动端适配：

   • PN 是否回到段内
   • 对话底色在窄屏是否正常
   • 诗歌格式是否溢出

---

Step 3 — 语义/wikilink 检查（针对内容错误）

触发条件：用户反馈"标注不对"、"链接错了"、"内容语义有问题"。

检查清单：

1. 运行 wikilink lint：

   python3 wiki/scripts/build_registry.py wiki/public/pages --out /dev/null 2>&1 | grep '\[lint\]'
   

   关注 单汉字 wikilink 警告——[[记]]、[[花]] 等通常是拆分书名的错误。

2. 诗歌检测检查：

   • 被标记为 .chapter-poem 的段落是否真的是诗
   • 过滤条件：text.endsWith('：') 排除过渡句
   • 端词检测：行末是「，」「。」等标点的短行 → 确认非诗歌

3. 标题 wikilink 检查：

   • 标题中的链接是否指向已有页面
   • 若标题本身有独立页面，TOC 中应链接到独立页面而非本页 anchor

4. 书籍/作品名完整性检查：

   • 《西厢记》应整体链接 [[西厢记]]，不拆分为 [[西厢]] + [[记]]
   • 《牡丹亭》应整体链接 [[牡丹亭]]

---

Step 4 — 内容完整性检查

触发条件：用户反馈"少了内容"、"引文不足"。

检查清单：

1. event 页面是否有 ## 原文描写 节
2. person 页面是否有原文引文或性格描写
3. 引文 blockquote 末尾是否有 PN 编号 （NNN-PPP）
4. 引文内容是否与 corpus/ 原文一致

---

Step 5 — 根因匹配与报告

检查完以上步骤后，将当前问题匹配到 wiki/doc/why.md 中的根因模式：

模式	匹配特征	输出
A 视觉设计迭代	连续的视觉调整反馈	建议：一次问清三个参数再改
B 语义判断错误	启发式误判、wikilink 错误	建议：查注册表、加排除条件
C 编辑操作失误	JS 崩溃、语法错误	建议：改后必须 node --check
D 并发修改冲突	另一 session 也在改同一文件	建议：git diff 检查冲突
E 内容完整性	缺少引文或字段	建议：对照类型检查表确认

修复确认

修复完成后，执行一次快速验证：

1. 如果是 JS/CSS 问题：确认 node --check 通过
2. 如果是 wikilink 问题：确认 lint 无新增警告
3. 如果是视觉问题：确认 CSS 改动已应用，报出具体修改了什么
4. 用 git diff --stat 列出受影响文件

不适用情况

• 需要新增功能的请求（用 /wiki skill 或正常对话）
• 深层架构重构（需要先讨论方案）