hwj123hwj docs-maintainer
项目路径
绝对路径：/Users/weijian/Desktop/develop/custom-skills
所有路径基于此根目录，下文简称 {root}。
文档结构规范
本 skill 维护以下目录结构：
docs/
├── README.md # 文档总索引（必须覆盖所有文件）
├── architecture.md # 项目架构（核心，长期维护）
├── skill-spec.md # Skill 规范（核心，长期维护）
├── agent-spec.md # Agent 规范（核心，长期维护）
├── registry-workflow.md # Registry 生成与校验流程
├── upstream-sync.md # 第三方 Skill 同步规范
│
├── agent-infra/ # Agent 基础设施设计文档
│ ├── overview.md # 总览
│ ├── mvp.md # MVP 定义
│ └── ... # 各子系统设计文档
│
├── agent-stories/ # Agent 演进 Story
│ ├── README.md # Story 规范
│ └── {agent-id}.md # 各 Agent 的 Story
│
├── showcase/ # 产出物展示与审核
│ ├── README.md # 展示索引
│ ├── recipes/ # Deck 配方
│ └── reviews/ # 审核快照
│
├── wiki/ # Wiki 类内容
│ └── reviews/ # Wiki 审核记录
│
├── spec/ # 历史规格与演进设计
│ ├── v1-baseline/ # v1 基线快照（不再更新）
│ └── v2-agent-platform/ # v2 设计规格
│
├── plans/ # 阶段性计划与问题分析
│
└── prototypes/ # 原型设计文档
文档归属判断
| 性质 | 归属 | 示例 |
|---|---|---|
| 项目级核心规范 | docs/ 根目录 |
architecture、skill-spec、agent-spec |
| Agent 基础设施设计 | docs/agent-infra/ |
MVP、知识编译层、eval case 规范 |
| Agent 演进 Story | docs/agent-stories/ |
intel-agent story |
| 产出物展示 | docs/showcase/ |
Deck brief、配方、审核快照 |
| 历史规格快照 | docs/spec/ |
v1 基线、v2 设计稿 |
| 阶段性计划 | docs/plans/ |
优化路线图、问题分析 |
| 代码审查快照 | docs/ 根目录 |
codebase-review-{date}.md |
索引规范
docs/README.md 必须覆盖 所有存在的 .md 文件，按上述分类分组列出。每条索引包含：
- 文件链接
- 一句话描述
快速检查模式
当用户说"文档有没有过时"、"快速检查一下文档"时，跳过完整流程，只做：
- 索引一致性：
find docs/ -name "*.md" | sortvsdocs/README.md中列出的文件 - 散落文件：docs/ 根目录下不在 README 索引中的 .md 文件
- plans/ 归档候选：超过 30 天且描述的改动已合并到 main 的计划文件
- spec/ 状态审查：v2 文档中标记"待审核"但实际已完成的功能
输出一个简洁的清单即可，不做修改。
维护流程
阶段一：扫描现状
1. 扫描源码结构
# skills 目录
ls {root}/skills/ | head -60
# agents 目录
ls {root}/agents/ | head -20
# web 关键文件
ls {root}/web/src/lib/skill-categories.ts
ls {root}/web/scripts/validate-registry.ts
# registry
cat {root}/registry/skills.json | python3 -c "import sys,json; print(len(json.load(sys.stdin)))"
cat {root}/registry/agents.json | python3 -c "import sys,json; print(len(json.load(sys.stdin)))"
# 根 CLAUDE.md
head -80 {root}/.claude/CLAUDE.md
# 根 README.md
head -80 {root}/README.md
2. 动态扫描所有文档
find {root}/docs -name "*.md" -type f | sort
对每个文件：
- 读取内容（至少前 30 行 + 关键章节）
- 判断文档类型和当前状态
docs/README.md：检查索引是否覆盖所有文件docs/architecture.md：检查与实际代码一致性docs/skill-spec.md：检查 tag 白名单是否与 validate-registry.ts 一致docs/agent-spec.md：检查与 agents/ 目录一致性docs/upstream-sync.md：检查与 CI 工作流一致性
阶段二：差异分析
对每份文档做以下检查：
| 检查项 | 判断标准 |
|---|---|
| 索引缺失 | docs/README.md 没有列出存在的文件 |
| 索引多余 | docs/README.md 列出了但文件已不存在 |
| 内容过时 | 文档描述与当前源码/配置不一致 |
| plans/ 归档判断 | 计划文件描述的改动已合并或超过 30 天 |
| spec/ 状态不明 | v2 规格中标记的待定功能实际已完成 |
| 归属错误 | 文档放在错误的目录 |
| architecture 过时 | 技术栈、模块描述与实际不符 |
| skill-spec tag 过时 | tag 白名单与 ALLOWED_TAGS 不一致 |
| CLAUDE.md 过时 | 技能数量、命令、规则与实际不符 |
| README 过时 | 自动生成的技能表与 registry 不一致（应重新 generate） |
归档判断规则（plans/ 下的文件）
满足以下任一条件，即可建议归档：
- 描述的改动已合并：计划中列出的任务已出现在 main 分支代码中
- 用户明确指示：用户说"归档 X"或"X 已完成"
- 陈旧度检测：文件创建日期距今超过 30 天，且描述的功能已明显上线
阶段三：执行修正
docs/README.md 更新
- 补全缺失的索引条目（按分类分组）
- 移除已不存在文件的条目
- 确保每个文件都有对应链接和描述
核心文档更新
- architecture.md：技术栈版本、模块描述、数据流与实际代码同步
- skill-spec.md：tag 白名单与
validate-registry.ts的ALLOWED_TAGS对齐 - agent-spec.md：与
agents/目录中的实际 agent 对齐 - registry-workflow.md：生成文件列表与实际
sync-skills.ts产出对齐 - upstream-sync.md：CI 工作流路径、触发条件与实际
.github/workflows/对齐
CLAUDE.md 更新
- 技能数量等硬编码数字（应避免硬编码或改为动态描述）
- 命令列表与
package.jsonscripts 对齐 - 关键规则与实际校验逻辑对齐
归档操作
满足归档条件的 plans/ 文件，在文件顶部添加归档标记：
> **归档说明**：本计划已于 {date} 执行完毕，保留供历史参考。
不删除文件、不移动目录。
阶段四：输出维护报告
## 文档维护报告 {YYYY-MM-DD}
### 已修正
- [更新] docs/README.md：补充了 X 的索引
- [更新] docs/skill-spec.md：tag 白名单新增 Architecture, Coding 等
- [归档] docs/plans/xxx.md：标记为已归档
### 无需修正
- docs/agent-spec.md：内容准确
- docs/registry-workflow.md：内容准确
### 需人工确认
- docs/plans/xxx.md：描述了尚未确定的设计方向，建议确认后更新
- docs/spec/v2-agent-platform/xxx.md：标记"待审核"，请确认是否已完成
写作标准
- 只改该改的：不要重写内容准确的文档
- 保持风格一致：沿用现有格式，不引入新模板
- 谨慎归档：宁可多保留也不误归档，有疑问的放进"需人工确认"
- 不要删文件：只做标记归档和内容更新
- 不改代码：只维护文档，发现代码问题列到"需人工确认"
- 不手动编辑生成文件：
registry/、skills-data.json、README.md技能表属于自动生成，应通过npm run generate:registry更新