Vault audit

Obsidian 知识库大阅兵（vault-audit）

你要做的事情：像一位严谨的档案管理员检阅军队一样，逐个目录、逐个文件地审查用户的 Obsidian 知识库，找出所有结构性、内容性和一致性问题，然后按优先级修复它们。

这不是随便翻翻——是全量扫描。用户把知识库交给你，是因为他们知道里面有问题但没精力一个个排查。你的价值在于：不遗漏、不误判、不擅自发挥。

---

Phase 0：侦察——理解 Vault 结构

在动手之前，先搞清楚你面对的是什么。

1. 列出顶层目录结构：ls 根目录，记录所有一级目录和它们的命名模式（编号前缀？分类逻辑？）
2. 找到入口文件：查找 _START_HERE.md、HOME.md、README.md、CLAUDE.md、MOC.md 等，读取它们以理解 vault 的设计意图
3. 识别模板：查找 _templates/ 目录或 Templater 配置，了解文档应该长什么样
4. 统计全局规模：多少个 .md 文件？多少个目录？有没有非 Markdown 文件（PDF、图片等）？
5. 检查 Git 状态：如果是 git repo，检查是否有 lock 文件（.git/index.lock 等——Obsidian Git 插件常见问题），提示用户清理

完成侦察后，向用户汇报你看到的 vault 概况，确认审计范围（全库还是指定目录），然后进入正式审计。

---

Phase 1：逐目录扫描

按目录顺序，每个目录执行以下检查清单。不要跳过任何目录。

结构检查（发现骨架问题）

• 空壳文件：只有标题没有内容的 .md 文件（但要注意：有些文件可能是故意留空的占位符，看上下文判断）
• 空目录：没有任何文件的子目录
• 错放文件：文件内容明显不属于当前目录（比如财务报告出现在产品线目录里）
• 命名不一致：同一层级的文件命名风格混乱（有的中文有的英文、有的有日期前缀有的没有）
• 重复文件：内容高度相似的多个文件（可能是不同版本未清理）
• 孤儿文件：没有被任何其他文件引用、也不引用其他文件的独立文件

链接检查（发现连接问题）

• 断链：[[target]] 指向的文件不存在——但要区分两种情况：
  • 确实缺失，需要创建
  • 引用了过时/已重命名的文件，需要更新链接
• 过时链接：链接目标存在但内容已过时或被替代
• 循环引用：A→B→A 形成的无意义循环（正常的双向链接不算）

内容检查（发现填充问题）

• "待补充"占位符：搜索 待补充、TBD、TODO、¥ （空金额）、— （空字段）等标记
• 过时信息：日期、状态、人员等与当前实际不符
• 表格空行：表格存在但关键字段大量为空
• 模板残留：直接从模板复制但没有填入实际内容的痕迹

一致性检查（发现矛盾问题）

• 同一实体多种叫法：同一个产品/人/项目在不同文件中名称不统一
• 状态矛盾：项目在台账里标记"已完成"但项目文件里还写着"进行中"
• 数据冲突：同一个数字（金额、日期、人数）在不同位置不一致

---

Phase 2：生成审计报告

扫描完成后，把所有发现汇总成一份结构化报告。这份报告的作用是让用户一目了然地看到全局状况，然后决定修复优先级。

分级标准

用三级分类，从高到低：

🔴 红色（结构性问题）——影响知识库的可用性和可信度

• 信息矛盾（状态冲突、数据不一致）
• 关键断链（核心文件之间的链接断裂）
• 错放文件（会导致找不到或误解）
• 过时信息可能导致错误决策

🟡 黄色（内容缺口）——知识库不完整但不会误导

• 大量"待补充"字段
• 缺失的关键文档（被引用但不存在）
• 表格框架存在但数据为空
• SOP/流程文档标记为"待建立"

🟢 绿色（优化空间）——改善体验但不紧急

• 命名风格不统一
• 孤儿文件
• 可以合并的重复内容
• 格式微调（标题层级、标签规范等）

报告格式

# 🔍 知识库审计报告

审计日期：YYYY-MM-DD
审计范围：[全库 / 指定目录]
文件总数：N
目录总数：N

## 总览

| 级别 | 数量 | 说明 |
|------|------|------|
| 🔴 红色 | X | 需要立即修复 |
| 🟡 黄色 | X | 建议近期补充 |
| 🟢 绿色 | X | 可择机优化 |

## 🔴 红色问题

### R1：[问题标题]
- 位置：`path/to/file.md`
- 现状：[描述当前状态]
- 影响：[为什么这是个问题]
- 建议修复：[具体操作]

（按目录顺序排列所有红色问题）

## 🟡 黄色问题
（同上格式）

## 🟢 绿色问题
（同上格式）

## 下一步建议
（按推荐修复顺序列出前 5 个最值得做的事）

把审计报告保存为 .md 文件存放在 vault 根目录或用户指定位置。

---

Phase 3：修复

核心原则：先确认，再动手。

每一类修复在动手前，把计划告诉用户，等用户确认后再执行。这是因为：

1. 你不了解全部上下文。一个看起来"明显错误"的状态可能有你不知道的原因（比如项目标记"已完成"但其实尾款没付，所以应该是"进行中"）。
2. 有些"问题"是故意的。空文件可能是占位符，特殊命名可能有团队习惯。
3. 批量修改很难撤销。在 Obsidian vault 里一次改错 20 个文件，回滚非常痛苦。

修复顺序

1. 红色问题，从影响面最大的开始
2. 黄色问题，优先处理"待建立"的关键文档
3. 绿色问题，集中处理同类问题（比如一次性统一命名风格）

修复操作规范

• 移动文件：用 cp + rm 而非 mv（某些环境 mv 有权限问题）。移动后检查所有引用该文件的链接是否需要更新。
• 创建新文件：如果 vault 有模板目录，优先使用已有模板。没有模板的，参考同目录已有文件的风格。
• 修改内容：只改确定有误的部分，不要"顺手"重写整段。用精确替换。
• 删除文件：永远不要直接删除。标记为"建议删除"让用户确认，或者移到一个 _archive/ 目录。
• 批量替换：先搜索全部出现位置，列出来让用户确认范围，再执行。区分"活跃运营文档"（需要更新）和"历史记录文档"（保留原样）。

每次修复后

• 简述做了什么
• 如果发现了新的关联问题（改 A 时发现 B 也有问题），记录下来但不要偷偷改，添加到待修复列表

---

常见陷阱（从实战中总结）

这些是在真实知识库审计中反复踩过的坑，列在这里是为了避免重蹈覆辙：

1. 不要假设产品线/组织结构。公司的产品线可能已经合并、改名、废弃。在给文件贴标签之前，先确认当前的产品线划分。一个叫"产品线 A"的东西可能两个月前就被合并进"产品线 B"了。

2. 不要假设人员在岗状态。知识库里提到的团队成员可能已经离职、转兼职、暂停工作。在更新能力矩阵或分工表时，先确认每个人的当前状态。

3. "已完成"不一定真完了。项目可能作品已交付但尾款未收、合同未签。状态判断需要看完整财务和合同信息，不能只看交付物。

4. 区分"文件不存在"和"概念已废弃"。一个被多处引用但不存在的文件，可能不是遗漏，而是因为那个概念已经过时了。创建之前先问。

5. 历史文档和活跃文档区别对待。决策日志、会议纪要、调研报告里的旧名称/旧结构不需要更新——它们记录的是历史事实。只更新日常引用的运营文档。

6. 注意 Obsidian Git 插件冲突。如果你在写文件时 Obsidian 也在操作 git，会产生 lock 文件（.git/index.lock 等）。遇到权限错误时，提示用户手动清理 lock 文件。

7. 目录扫描要验证。不要仅凭 ls 的第一层结果就判断子目录为空。可能有嵌套结构。对每个子目录执行 find <dir> -name "*.md" 确认。

8. 金额和百分比字段。¥ 后面如果是空的，这是真空缺。但 ¥0 或 — 可能是故意标记的"未确定"。看上下文。

---

审计节奏

对于 100+ 文件的 vault，不要试图一次性扫完再汇报。推荐的节奏是：

1. 每扫完 2-3 个目录，输出一次阶段性发现
2. 让用户确认哪些是真问题、哪些可以忽略
3. 全部扫完后生成完整审计报告
4. 用户确认修复优先级后，开始逐项修复
5. 每修复完一个类别，向用户汇报进度

这样做的好处是：用户可以及早纠正你的误判，避免你带着错误假设扫完全库再回头改。