# Vault Audit

> Obsidian 知识库"大阅兵"——对整个 Vault 进行系统性审计和清理。扫描每个目录的结构健康度、文件内容质量、链接完整性、命名一致性，输出分级审计报告并逐项修复。 MANDATORY TRIGGERS: 知识库审计、大阅兵、vault audit、清理知识库、梳理知识库、检查知识库、知识库体检、vault cleanup、vault review、整理 Obsidian、Obsidian 大扫除。也适用于：用户说"帮我看看知识库有什么问题"、"知识库乱了"、"文档需要整理"、"检查一下文件结构"等任何涉及对 Obsidian vault 做系统性检查和修复的场景。即使用户只是说"帮我整理一下"但当前工作目录是一个 Obsidian vault，也应当触发本 skill。 English triggers - "audit my vault", "my knowledge base is a mess", "full vault checkup", "clean up my Obsidian".

- Skill: `yiweicreates/vault-audit` (Agent Skill)
- Install (CLI): `npx skillmds@latest add yiweicreates/vault-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yiweicreates/vault-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: YiweiCreates (https://skillmd.com/u/yiweicreates)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/yiweicreates/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/流程文档标记为"待建立"

**🟢 绿色（优化空间）**——改善体验但不紧急
- 命名风格不统一
- 孤儿文件
- 可以合并的重复内容
- 格式微调（标题层级、标签规范等）

### 报告格式

```markdown
# 🔍 知识库审计报告

审计日期：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. 每修复完一个类别，向用户汇报进度

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