技能｜Obsidian兼容性校验法

适用场景

检查知识库笔记是否能在 Obsidian 中正常打开/链接（双链、附件、命名、frontmatter）。触发词：Obsidian 打不开、兼容校验、双链失效、报告。对应：<项目源码目录>\scripts\obsidian_compat_check.py + 路由 /api/obsidian_check。

操作步骤

1. 确认脚本指向正确（历史坑）：旧版 base=resolve_root() 再 join(base,"<我的知识库>") 会误扫整个 <项目根目录>，且报告落到根目录。正确默认：直接指向 <项目根目录>\知识库根\<我的知识库>，报告输出到 <项目根目录>\<项目源码目录>\docs\obsidian_compat_report.md。改目录后必查此处。
2. 跑校验：
   bash python "<项目根目录>\<项目源码目录>\scripts\obsidian_compat_check.py"
   也可在页面点「Obsidian 兼容检查」（/api/obsidian_check）触发。
3. 看四类问题：
   - 文件名非法字符（Obsidian 限制 \ / : * ? " < > |）
   - 双链指向不存在的文件（死链）
   - 附件路径失效
   - frontmatter 格式异常（缺 title/type 等）
4. 按严重度处置：死链优先修（用《技能｜全库织网与死链修复法》），文件名问题批量改名并同步双链（见《技能｜笔记改名双链同步法》）。
5. 报告留档：报告只保留最新 + 上一版，定稿后按存储规则迁 PC服务器端\知识库系统开发目录。

注意边界

• 校验是只读的，不会改文件；修复动作要单独执行并留痕。
• 目录结构调整后，脚本默认路径与输出路径都要复核，否则静默扫错范围。
• 报告属源码级留档，不要与正式开发文档双重存放。

反例避雷