故障排查
编辑器卡顿
通常是单文档过大、附件目录爆炸、扩展冲突，或文件索引落后。
症状
打字与屏幕上出现字符之间有可感知的延迟（200ms 以上）；滚动一长段笔记时画面撕裂或掉帧；CPU 风扇明显起飞；甚至偶尔出现"双字符" — 按一次 a 蹦出 aa。
卡顿是症状不是病。Kition 编辑器底层是基于 ProseMirror 的渲染管线，正常情况下 60fps 处理几万字毫无压力。一旦卡顿，几乎一定有某一项的体量超过设计预期。
常见原因
- 单个文档超过 50K 字（特别是有大量 wikilink / 嵌入图片的）
- 附件目录（默认
.attachments/）单层超过 1000 个文件 - 装了多个扩展，且其中某个监听了
onDocChange— 每键都跑 - 文件索引在重建（首次打开大 vault、或刚改名移动大量文件后）
- 系统级 IME 候选窗与编辑器抢焦点（中文输入法常见）
- 后台某个 Agent 还在跑工具调用、占着 sidecar 主线程
逐步诊断
- 看右下角状态栏：是否显示 "Indexing..."？等它消失再试
Cmd/Ctrl + Shift + P→ "Show editor stats"，查文档字数 / wikilink 数 / 渲染时间- 查附件目录大小：
ls -l .attachments | wc -l - Settings → Extensions → 全部 disable 再试一次（隔离扩展嫌疑）
- 关 Agent 面板，再试 — 隔离 Agent / sidecar 嫌疑
- macOS 用 Activity Monitor 看 Kition Helper (Renderer) 的 CPU 占用
修复
- 拆大文档：超过 50K 字用 H1 切成多个文件并用 wikilink 串起来
- 把扁平的
.attachments/按月分子目录：.attachments/2026-06/ - 禁用可疑扩展，逐个开回，定位罪魁
- 强刷渲染：
Cmd/Ctrl + Shift + R（不会丢未保存内容，仅重建 DOM） - IME 抢焦点：在系统输入法设置里把候选窗位置改成 "Below cursor"
Cmd/Ctrl + Shift + P→ "Rebuild file index"，强制重建索引
排查命令
# Find the heaviest docs in your vault
find . -name "*.md" -type f -exec wc -c {} + | sort -rn | head -10
# Count attachments per folder
find .attachments -type d -exec sh -c 'echo "$(ls -1 "$1" | wc -l)\t$1"' _ {} \; | sort -rn | head -10
# macOS: profile renderer CPU for 10 seconds
sample "Kition Helper (Renderer)" 10 -file /tmp/kition-renderer.txt应急方案
在巨型文档上工作时可以临时切到 "Source mode"（Cmd/Ctrl + .）— 它绕过了富文本渲染，直接编辑原始 Markdown，几十万字也丝滑。代价是没有实时预览。
另外可以临时关掉 wikilink 实时解析：Settings → Editor → Live wikilink resolution → off。打开文档变快、但 hover 预览就没了。
什么时候该提 bug
- 空文档、无扩展、关闭 Agent 后仍卡
- CPU 占用 < 10% 但仍有打字延迟（说明不是计算瓶颈，是事件流问题）
- "双字符" bug 在禁用所有 IME 后仍然出现
- 渲染统计里
paint > 200ms且字数 < 10K