solo-audit

/audit

审核知识库的质量问题：缺少 frontmatter、链接失效、标签不一致、孤立文件和内容覆盖缺口。适用于任何以 Markdown 为主的项目。

步骤

1. 解析关注区域：从 $ARGUMENTS 中解析关注区域（可选）。如果提供了关注区域，则聚焦该区域（例如，“标签”“frontmatter”“链接”）。如果为空，则执行完整审核。

2. 查找所有 Markdown 文件： 使用 Glob 查找所有 .md 文件，排除常见的非内容目录：.venv/、node_modules/、.git/、archive/、.archive_old/。

3. Frontmatter 审核： 首先扫描一部分现有文件（前 10–20 个），检测所用的 frontmatter 架构（有哪些字段，以及 type 和 status 常见的值）。然后检查每个 Markdown 文件：

   • 是否包含 YAML frontmatter（以 --- 开头，并以 --- 结束）
   • 是否包含核心字段：title、tags（以及知识库中其他一致使用的字段）
   • type 和 status 的值（如果使用）是否符合检测到的架构
   • tags 是否为非空列表 记录缺少 frontmatter 的文件，以及 frontmatter 不完整或无效的文件。

4. 链接检查： 查找失效的内部链接：

   • 使用 Grep 查找 Markdown 链接 \[.*\]\(.*\.md\)，并验证每个目标文件是否存在
   • 如果项目中有链接检查脚本（例如 scripts/check_links.py），也运行该脚本

5. 标签一致性审核： 使用 Grep 查找所有 .md 文件中的 tags: 区段。检查以下问题：

   • 近似重复的标签（例如，“ai”与“AI”与“artificial-intelligence”）
   • 只使用一次的标签（可能是拼写错误）
   • 过于宽泛的高频标签 列出所有唯一标签及其计数。

6. 孤立文件： 检查哪些文件未在任何其他文件的 related: 字段中被引用。存在但从未被交叉引用的文件可能是孤立文件。

7. 内容质量： 查找看起来像创意或机会的文档（依据检测到的 type 字段或目录位置），并检查：

   • draft 状态持续超过 30 天的文档
   • 缺少其他同类文档所包含的关键元数据字段的文档
   • 内容过少的文档（不含 frontmatter 时少于 100 个单词）

8. 覆盖缺口： 检查各目录的内容：

   • 标记空目录或内容极少的目录
   • 查找仅有 1–2 个文件的目录（可能需要补充内容）

9. 输出报告：

   ## KB Audit Report
   
   **Date:** [today]
   
   ### Summary
   - Total .md files: X
   - With frontmatter: X (X%)
   - Without frontmatter: X
   
   ### Frontmatter Issues
   | File | Issue |
   |------|-------|
   | path | Missing field: type |
   
   ### Broken Links
   [list of broken references]
   
   ### Tag Analysis
   - Total unique tags: X
   - Single-use tags: [list]
   - Potential duplicates: [list]
   
   ### Orphaned Files
   [files not referenced anywhere]
   
   ### Content Quality
   - Stale drafts (> 30 days): [list]
   - Missing metadata: [list]
   - Low-content files: [list]
   
   ### Coverage
   [directory analysis]
   
   ### Recommendations
   1. [specific action]
   2. [specific action]
   3. [specific action]
   

注意事项

1. 只出现一次的标签不一定是拼写错误 — 只使用一次的标签可能是有意为之（例如，特定活动使用的 event-2026）。应标记，但不要在未检查上下文前自动合并。
2. 孤立文件可能是有意归档的 — 3-inbox/ 或 4-opportunities/ 中的文件通常是有意独立存在的。只标记方法论或原则目录中的孤立文件。
3. 不同目录的 Frontmatter 架构可能有所不同 — 0-principles/ 使用 type: principle，3-inbox/ 使用 type: capture。应检测各目录的惯例，不要在全局强制统一架构。
4. related: 字段并非唯一依据 — 许多有效的交叉引用以行内 Markdown 链接 [text](path.md) 的形式存在，而不只在 YAML related: 数组中。两者都要检查。
5. 空目录可能是占位目录 — 5-active-projects/ 或 6-companies/ 可能有意保持为空（由自动化填充）。标记之前先检查 registry.yaml 或 Makefile。

常见问题

未找到 Markdown 文件

原因： 在错误的目录中运行，或所有文件都被排除了。
解决方法： 确保当前目录是知识库根目录。检查步骤 2 中的排除模式。

只出现一次的标签过多

原因： 文档之间的标签使用不一致。
解决方法： 从使用频率最高的标签中选定规范标签。清理后再次运行审核。

Frontmatter 验证错误

原因： YAML 语法问题（缺少引号、缩进错误）。
解决方法： 确保存在 --- 分隔符。type: 和 status: 的值应符合检测到的知识库架构。