walidboulanouar/vault-organizer

Vault Organizer（知识库整理器）

将混乱的 Markdown 知识库变成一个干净、交叉链接且可高效检索的知识体系，让 LLM（或队友）能够快速查找。基于 Karpathy 的原则： 将知识当作代码。 原始来源是源文件，编译后的 wiki 是构建输出，INDEX 是模式，而本技能则是编译器加代码检查器。

模型（三层）

层	内容	存放位置
RAW（原始）	未处理的内容：转录稿、片段、转储、截图	00_Inbox/raw/，或最近的专题文件夹
COMPILED（编译）	经过综合的页面，使用 [[wikilinks]] 进行交叉引用	PARA 文件夹（01_–04_）
SCHEMA（模式）	INDEX 文件、CLAUDE.md、规则	每个文件夹内的 INDEX.md 加一个主索引

每个文件都携带 type: 类型的前置元数据（raw | compiled | reference | framework | client | index）。 参见 references/standards.md 获取前置元数据和 INDEX 模板。

工作流程

按顺序执行这些步骤。先审计并提议，再修改。在未确认前绝不删除或移动。建议使用 git 仓库以便更改可逆。

1. 审计（只读）

# 整个知识库：
python3 scripts/audit.py <vault_root> --stale-days 120 --report /tmp/vault-audit.md
# 单个子文件夹，但针对整个知识库解析 [[wikilinks]]（避免误报“破损”标志）：
python3 scripts/audit.py <subfolder> --link-root <vault_root> --report /tmp/vault-audit.md

返回一份健康报告：缺失的前置元数据、破损或丢失的 wikilinks、孤立页面、缺失的“相关内容”段落、重复文件、过时文件、没有 INDEX 的文件夹。阅读报告后，向用户展示摘要表格和主要问题。（--json 选项用于机器输出。）

2. 分类

将发现的问题分组，询问哪些现在修复、哪些以后修复。默认优先级：

1. 没有 INDEX 的文件夹（破坏检索能力）
2. 缺失的前置元数据（破坏搜索和属性功能）
3. 破损的 wikilinks（破坏关系图）
4. 缺失的“相关内容”段落和孤立页面（破坏发现能力）
5. 过时/重复文件（清理）

3. 清理（针对每个文件）

对于每个被标记的文件：

• 添加 YAML 前置元数据（title, type, source, author, created, description, tags）——根据内容推断，如果不知道创建日期则使用今天的日期填写 created。
• 在知识库中任何概念、工具、人物或文件的首次出现处添加 [[wikilinks]]。
• 在文档末尾添加 ## Related（相关内容）段落，包含 3–8 个指向最相关页面的 [[wikilinks]]。同时，在其中的 2–3 个页面的“相关内容”中也添加指向本文件的链接（双向链接）。
• 修复破损的 wikilinks：重新指向正确的别名，或者如果目标页面值得以后撰写则保留为有意的存根。 使用 references/standards.md 中的模板。不要删除现有的前置元数据或链接。

4. 整理（先提议后执行）

• 将放错位置的文件移动到正确的层/文件夹（raw 文件 → 00_Inbox/raw/，已编译文件 → PARA）。
• 规范化文件名为短横线命名（kebab-case）；合并或重命名重复文件。
• 保持移动操作小而可逆。列出每次移动，获得同意后再执行。

5. 注册（交付物）

• 为每个内容文件夹生成或更新 INDEX.md：每个文件一行指针（- [[file-name]] — 短描述），按类型分组，最新或最重要的排前面。
• 创建/刷新主索引（例如根目录下的 INDEX.md，或 meta/ 模式文件夹），链接到每个文件夹的 INDEX。
• 这个注册表是快速检索的关键，也是你交给队友的资料。

6. 检查（确认）

重新运行 audit.py。显示修复前后的计数。当前置元数据、INDEX 覆盖率和破损链接数量都为零时，知识库就算“干净”了（孤立页面/过时文件可能保留，由用户自行决定）。

分享给队友

当目标是向队友分享整理后的知识库时：确保主 INDEX 是最新的，每个文件夹都有自己的 INDEX，并在根目录放置一个简短的 README.md 解释这个三层模型以及如何浏览。README 和主 INDEX 是入口点。

规则

• 始终先进行只读审计。公开信息，不要制造意外。
• 未经明确确认绝不删除或批量移动；建议先提交更改。
• 不要碰 .obsidian/、.git/ 或 Claude Code 配置（settings.json、hooks）。
• 匹配知识库现有的约定（本仓库采用 PARA 加 references/standards.md 中的标准）。
• 分批工作；每批之后报告更改内容。

文件

• scripts/audit.py — 只读扫描器，核心引擎。首先运行它，最后再运行一次。
• references/standards.md — 前置元数据规范、类型分类、INDEX 和 README 模板。