故障排查
双链失效 / 反链不显示
重命名 / 移动后索引偶尔落后；理解索引模型才能彻底解决。
症状
[[Some Note]] 在编辑器里显示成灰色或带红色波浪（"unresolved"）— 但你明明知道 Some Note.md 文件就在 vault 里。或者反过来：双链在文档里正常蓝色高亮，但右侧反链面板（Backlinks）一片空白。
这两种现象都是 链接索引 (link index) 落后于文件系统的表现。Kition 把所有 wikilink 的关系存在 .kition/index/ 下，文件改名 / 移动 / 大批量同步进来时偶尔会有几秒到几分钟的延迟。
常见原因
- 文件刚被外部工具改名 / 移动（Finder、git pull、rsync），fs watcher 还没追上
- 云盘同步把文件拉下来时绕过了 Kition 的文件系统监听
- 链接里的标题大小写或空格与文件名不一致（macOS HFS+ 大小写不敏感，但索引敏感）
.kition/index/损坏或被并发写入冲突过[[#section]]这种 anchor-only 链接，目标文件不存在
逐步诊断
- 右下角状态栏看是否还在 "Indexing..."，等它完成
- 把鼠标悬停在红色链接上，看 tooltip 里的"期望路径"
- Vault 里跑
ls "<期望路径>"确认文件真的在 - 检查大小写是否完全一致（
[[Some Note]]vsSome note.md） - 命令面板 → "Rebuild link index"，等 5-30 秒（看 vault 大小）
- 若仍失败，关闭 Kition，备份
.kition/index/，删掉它，重启 — Kition 会全量重建
手动检查 / 修复索引
关闭 Kition，命令面板找不到时也可以从命令行触发索引重建：
# Rebuild the link index from disk
kition index rebuild
# Or verify only — reports inconsistencies without rewriting
kition index check
# Last-resort: wipe and rebuild from scratch
kition index reset --rebuild修复
- 索引落后：命令面板 → "Rebuild link index"
- 大小写不一致：要么改文件名要么改链接，二选一（建议统一用 kebab-case）
- DB 损坏：用上面的 dump + reload 流程修，或干脆删掉让 Kition 全量重建
- 云盘绕过 watcher：每次大批量 pull 后手动重建一次索引
- Anchor-only 死链：把
[[#section]]改成[[file#section]]
应急方案
在索引修复期间，全文搜索（Cmd/Ctrl + Shift + F）依然可以找到任何文件，因为它走文件系统而不是索引。可以临时用搜索替代反链跳转。
什么时候该提 bug
- 重建索引后仍然有大量 "unresolved"，且文件确实存在
PRAGMA integrity_check反复报错，说明 DB 写入路径有问题- 正常单文件改名后反链没自动迁移（应该自动迁移）
- 索引体积异常（> vault Markdown 总体积的 30%）