doc-gardener

name	doc-gardener
description	文档园丁，负责知识库建立后的一切维护工作：自动巡检（过期文档、代码不一致、失效引用）、整理散乱文档、审计模块旧文档、梳理归类。当用户提到"文档巡检""文档园丁""检查文档""扫描文档""整理文档""审计文档""梳理文档"时使用。

文档园丁

知识库建立后的唯一维护入口。包含三大能力：巡检、整理、审计。

子 agent 使用规范

所有涉及多文件、多模块的操作，必须使用 Task 工具启动子 agent 并行处理。

• 不指定 model 参数（继承父级模型）
• 每批最多 4 个并行子 agent
• 每个子 agent 负责一个独立范围（如一个模块、一类文档）

能力A：巡检

触发："文档巡检" / "跑一下文档园丁" / "检查文档" / "扫描文档"

第一步：运行扫描脚本

bash ~/.cursor/skills/doc-gardener/scripts/scan.sh <项目根目录>

脚本执行 13项检查：

范围	检查项
文档结构	关键文件存在、AGENTS.md行数、设计文档验证状态、索引同步、过期（>30天）、空目录
代码一致性	容器一致（docker ps vs 架构.md）、端口一致、凭据一致（.env vs 凭据文档）、模块目录一致、部署模式一致
Git分析	代码变更但文档未更新的模块、文档统计

第二步：子 agent 并行修复

根据扫描结果，启动并行子 agent 分头处理：

问题类型	子 agent 任务
容器/端口/模块不一致	更新 架构.md 和 AGENTS.md 对应部分
凭据不一致	读取 .env 最新值，更新凭据文档
部署模式不一致	读取 docker-compose，更新 架构.md 标记
代码变更未同步	逐模块分析 git diff，判断是否需要更新文档

Agent 额外主动检查：

• 质量评分是否覆盖所有模块
• 文档/ 内的 TODO/FIXME 标记
• 执行计划/进行中/ 是否有已完成但未归档的计划
• AGENTS.md 知识库索引是否与 文档/ 子目录同步

第三步：生成巡检报告

存入 文档/变更日志/文档巡检报告-YYYYMMDD.md。

---

能力B：整理散乱文档

触发："整理文档" / "整理XX模块的文档"

当项目下有散落在各处的旧文档时使用。

流程

第一步：扫描盘点（子 agent）

启动 1 个子 agent 递归扫描目标范围内所有 .md 文件，生成审计清单：

| 序号 | 当前路径 | 文件名 | 大小 | 最后修改 | 初步分类 | 处置建议 |

处置建议类型：迁移 / 合并 / 归档 / 废弃 / 更新后迁移

第二步：并行分类迁移（多个子 agent）

按审计清单结果，启动并行子 agent：

子 agent	负责范围
agent-A	迁移设计文档类（补验证状态头部）
agent-B	迁移参考资料类（API文档、数据库Schema等）
agent-C	迁移凭据/配置类 + 产品规格类
agent-D	处理需合并/归档/废弃的文档

每个子 agent 的执行动作：

• 迁移：复制到 文档/ 对应子目录，补验证状态头部
• 合并：整合多份文档为一份，保留各自独特信息
• 归档：移至 文档/执行计划/已完成/
• 废弃：删除文件，在变更日志中记录

第三步：清理与更新索引

1. 清理原目录下已迁移的文档
2. 清除空目录
3. 更新 AGENTS.md 知识库索引
4. 更新 架构.md（如发现架构信息需修正）

第四步：输出审计报告

# 文档审计报告 — [范围] — [日期]

## 统计
## 发现的问题
## 新增的隐性知识

---

能力C：审计模块旧文档

触发："审计XX模块的文档" / "梳理XX模块"

对特定模块下的旧文档进行深度审计，验证其与代码的一致性。

流程

第一步：定位模块文档

读取目标模块目录，找出所有 .md 文件和文档类子目录（规划文档/、文档/ 等）。

第二步：逐份验证（子 agent 并行，每个 agent 处理 3-5 份文档）

对每份文档：

1. 读取全文
2. 对照当前代码验证：接口/逻辑/配置是否与代码一致
3. 判定验证状态（✅/⚠️/❌/🚧）
4. 识别隐性知识（决策原因、踩坑记录等，这些需保留）

第三步：分类处置

根据验证结果：

• 有效文档 → 迁移到中央 文档/ 对应子目录
• 过时文档 → 归档或废弃
• 重复文档 → 合并
• 模块特定的开发文档（需求/接口/数据库/页面设计/开发进度）→ 保留在模块内

第四步：输出模块审计报告

---

自动修复权限

操作	权限
架构.md 补充容器/端口	直接修复
AGENTS.md 更新知识库索引	直接修复
设计文档补验证状态头部	直接修复
删除空目录	直接修复
凭据文档更新	修复后展示 diff
部署模式标记修正	修复后展示 diff
质量评分调整	修复后展示 diff
过期文档处置	需人工确认
大范围代码-文档不一致	需人工确认