跳转至

文档治理自动化

1. 背景 / 动机

来源：../../raw/conversations/2026-05-26-docs-system-audit|2026-05-26-文档体系体检诊断

核心症结：v0.10.22 建立的 5 层文档体系本身设计 OK，但靠人/AI 自觉遵守约定，没有 enforcement → 错误持续累积： - raw INDEX 漏 50% 条目 - 21 个 issue 头部状态信息双重维护 - 9 个 wikilink 断链 - 25 个文件缺 description - watchdog 散在 10 个文件没有主题入口

为什么要做： - 不解决 → 几个月后文档烂掉，AI/人都信不过 - 自动化校验 → 错误一发生立即可见 - 自动化重建 → 维护成本降到接近 0

2. 目标 / 非目标

目标

  • 写 3 个 Python 脚本：check-docs.py / rebuild-docs.py / build-overview.py
  • 加 pnpm docs:check 和 pnpm docs:rebuild 命令
  • 修存量问题：清重复信息、补 description、修断链、加 type 字段
  • 元规则加「每次提交前必跑 docs:check」

非目标

  • 不引入复杂工具链（CI / pre-commit hook） — 用 npm script + 人工触发就够
  • 不把 INDEX 整个自动生成 — 保留头部说明的手写部分，只自动维护表格
  • 不解决 obsidian dataview 等高级查询 — 那是 obsidian 自己的能力，frontmatter 写好就好

3. 用户故事

作为知识库维护者，
我希望 commit 前一条命令就能扫出 INDEX 漏 / 断链 / frontmatter 不全，
以便我立即修，而不是几周后才发现。

作为加 issue 的 AI/人，
我希望写完 issue 后跑 rebuild，INDEX 自动同步，
以便不忘加索引行（这是上次脱节的根因）。

作为新进的 AI 实例，
我希望读 docs/_overview.md 一页纸就建立 80% 项目上下文，
以便不需要消耗 context 读全部 docs。

4. 数据模型

无 storage / DB 改动。所有数据来自 md 文件 frontmatter。

docs/_overview.md 的内容结构

---
title: 项目鸟瞰
description: AI / 新协作者的一页纸入口
type: overview
updated: <auto>
---

# 来发信谷歌地图扩展 — 项目鸟瞰

## 当前状态
- 版本: v0.10.x
- 最新改动: <最近 5 条开发日志摘要>

## 核心架构（必读）
- [共享队列架构](./wiki/shared-queue-architecture.md) — N 个 task 共用调度器
- [Tab 生命周期](./wiki/tab-lifecycle-and-watchdog.md) — 看门狗 + 自动恢复
- ...

## 知识库分布（按主题）
| 主题 | wiki | specs | issues |
|---|---|---|---|
| 调度 | 共享队列 | SPEC-002 | 0003,0015 |
| 登录 | popup认证 |  | 0001,0002 |

INDEX 自动维护标记

INDEX.md 文件用 HTML 注释标记自动区：

# Issues 索引

> 手写说明...

<!-- AUTO-START: index-table -->
| ID | 标题 | 状态 | ... |  ← 此区由脚本自动重建
|---|---|---|---|
| 0001 | ... |
<!-- AUTO-END: index-table -->

## 新增 issue 的 checklist
... 手写部分继续 ...

脚本只动 START/END 之间的内容。

5. API 接口

新增 3 个脚本：

scripts/check-docs.py

$ python3 scripts/check-docs.py
# 或
$ pnpm docs:check

输出： 

检查 docs/ ...

✅ 47 个文件 frontmatter 完整
⚠️  9 个 wikilink 断链:
   docs/specs/done/SPEC-001-knowledge-base-refactor.md → [[wikilink]] 不存在
   docs/rules/github-push.md → [[wikilink]] 不存在
❌ INDEX 与实际不一致:
   docs/raw/INDEX.md 漏了 2 个: feedback/...

退出码: 1（有问题）/ 0（干净）

scripts/rebuild-docs.py

$ pnpm docs:rebuild

动作： - 扫所有 frontmatter - 重建 INDEX.md 的 <!-- AUTO-* --> 区 - 重建 docs/_overview.md - 不动手写区 - 改完打印 diff 摘要

校验规则细则

规则 检查内容 严重度
FM-1 所有 md（非 _template）必有 frontmatter 🔴 error
FM-2 frontmatter 必含 title / type / tags 🔴 error
FM-3 frontmatter 建议含 description 🟡 warn
IDX-1 所有非 INDEX 的 md 必出现在所属 INDEX 中 🔴 error
LNK-1 [[wikilink]] 指向必须存在（跳过明显占位 [[wikilink]] [[wikilink]]） 🟡 warn
DUP-1 issue 头部不应再写 > **状态**：xxx（信息已在 frontmatter） 🟡 warn

6. UI 设计

无 UI（CLI 工具）。

7. 任务拆分

后端 / 工具

  • T1：建 scripts/ 目录
  • T2：写 scripts/check-docs.py
  • T3：写 scripts/rebuild-docs.py（含 INDEX 重建 + overview 生成）
  • T4：加 pnpm docs:check + pnpm docs:rebuild 到 package.json scripts

数据迁移 / 修存量

  • T5：3 个 spec 文件补 type: spec frontmatter
  • T6：修 9 个 wikilink 断链（SPEC-001 / github-推送 / _template 的占位）
  • T7：21 个 issue 头部清重复状态/严重度引用（保留相关源码 / 相关 wiki）
  • T8：25 个文件补 description frontmatter（从正文或引用块提取）
  • T9：跑 rebuild → 各 INDEX 同步完整

文档

  • T10：docs/rules/00-meta-rule.md 加「提交前跑 docs:check」铁律
  • T11：docs/README.md 加自动化校验一节
  • T12：本 spec 移到 done/

测试

  • T13：故意制造问题（删一行 INDEX / 改 wikilink 错） → check 应报错
  • T14：跑 rebuild → 应自动修

8. 风险 / 注意点

  • ⚠️ rebuild 会改 INDEX：第一次跑可能改很多。先 git commit 当前状态作 baseline
  • ⚠️ HTML 注释 <!-- AUTO-* --> 必须正确插入：插错了 rebuild 会找不到边界
  • ⚠️ 「占位 wikilink」识别：_template 文件里的 [[wikilink]] [[wikilink]] 是教学占位，不应报错。check 脚本要识别 _template 文件名
  • ⚠️ issue 头部清重复：脚本只删 status / 首次出现 / 修复版本 / 严重度 / 类别 5 个引用块行，保留「相关源码」「相关 wiki」「相关 rules」

9. 验证标准

  • pnpm docs:check 退出码 0（无 error，可以有 warn）
  • pnpm docs:rebuild 重建所有 INDEX，diff 不变（已是稳态）
  • docs/_overview.md 存在且包含当前版本 / 5 个最近改动
  • 元规则 + README 文档更新
  • pnpm build 通过

10. 决策记录

  • 2026-05-26：用 Python 而不是 TypeScript — docs 处理 grep + frontmatter parse + 表格生成，Python 标准库够用，没必要 TS（不需要 build）
  • 2026-05-26：用 HTML 注释 <!-- AUTO-START --> 区分手写 / 自动区 — 比整个 INDEX.md 全自动更稳，保留手写说明
  • 2026-05-26：不引入 pre-commit hook — 项目目前单人为主，手工 pnpm docs:check 够用；CI/hook 是 SPEC-004 候选
  • 2026-05-26：issue 头部清重复 — frontmatter 是 source of truth，引用块只保留与 frontmatter 互补的「相关源码」等
  • 2026-05-26 (v0.10.26 阶段二)：用户体检反馈「快速检索 8.5/10」原因 = 主题散在多文件无 hub。补 2 件事：
  • 主题 hub 自动生成：rebuild-docs.py 加 build_topics()，7 个预定义主题（watchdog / scheduling / auth / settings / ui / documentation / tooling），按 tags + 关键词聚合，生成 docs/_topics/<slug>.md
  • pre-commit hook：scripts/hooks/pre-commit + pnpm setup:hooks 一次装好。只在 docs/ 有改动时跑 check，加速 commit
  • 验收：watchdog hub 一个文件聚合 1 wiki + 2 specs + 2 issues + 3 raw = 8 个文档