221 lines
8.0 KiB
Markdown
221 lines
8.0 KiB
Markdown
---
|
||
name: spec-docs
|
||
phases: ["all"]
|
||
description: >-
|
||
规范文档全生命周期管理系统。在 Agent 执行架构/规范类任务前自动提醒是否需要创建文档，
|
||
周期性审查文档与 changelog/代码的一致性（遗漏、陈旧、互斥检测），写入/更新规范文档。
|
||
触发关键词："架构"、"重构"、"设计方案"、"交互规范"、"编码规范"、"审查文档"、"review docs"等。
|
||
---
|
||
|
||
# Skill: spec-docs
|
||
|
||
# Spec Docs
|
||
|
||
规范文档管理系统。负责架构方案、技术规范、项目约定等文档的全生命周期管理——从创建前的提醒、到创建后的周期审查、再到一致性校验。
|
||
|
||
## 存储结构
|
||
|
||
| 文件/目录 | 位置 | 用途 |
|
||
|-----------|------|------|
|
||
| `docs/` | 项目根 | 所有规范文档（architecture/conventions/specs/reference） |
|
||
| `docs/README.md` | 项目根 docs/ | 目录标准与使用规范 |
|
||
| `state.json` | `.opencode/data/spec-docs/` | 周期审查状态追踪 |
|
||
|
||
## 锚点 ID 机制
|
||
|
||
规范文档使用 `DOC-NNN` 格式的 ID（如 `DOC-001`），与文件名中的三位编号一致。
|
||
每次创建新文档时自动分配（读取目录下最大编号 +1）。
|
||
|
||
在 frontmatter 的 `related_changelogs` 字段中记录关联的 `CL-xxx` 锚点 ID，实现 docs ↔ changelog 双向追溯。
|
||
|
||
## 操作 A：执行前检查（Pre-execution Check）
|
||
|
||
### 触发条件
|
||
|
||
当 Agent 判断当前任务涉及以下维度时，**在执行代码改动前**触发本操作：
|
||
|
||
- **架构级改动**：跨 3+ 模块、调整分层边界、引入/替换核心依赖、修改目录结构
|
||
- **系统方案设计**：设计系统、交互规范、数据流、API 设计、部署方案
|
||
- **项目规范制定**：编码规范、命名约定、工作流程、Git 规范
|
||
|
||
### 触发关键词
|
||
|
||
任一命中即触发（仅扫描用户消息，不扫描 Agent 输出）：
|
||
|
||
| 类别 | 关键词 |
|
||
|------|--------|
|
||
| `架构`、`重构`、`分层`、`模块划分`、`技术选型`、`目录结构`、`核心依赖`、`参考分析`、`竞品拆解`、`行业研究`、`反拆`、`GDD`、`设计参考` |
|
||
| 方案 | `设计方案`、`设计系统`、`交互规范`、`UI规范`、`界面风格`、`数据流`、`API设计`、`部署方案` |
|
||
| 方案 | `设计方案`、`设计系统`、`交互规范`、`UI规范`、`界面风格`、`数据流`、`API设计`、`部署方案` |
|
||
| 规范 | `项目规范`、`编码规范`、`命名规范`、`约定`、`标准`、`编码风格`、`工作流` |
|
||
|
||
### 执行流程
|
||
|
||
```
|
||
1. 暂停执行计划
|
||
2. 扫描 docs/ 目录，查找是否有与当前任务相关的已有文档
|
||
a. 按文件名关键词匹配
|
||
b. 按文档 frontmatter 的 type 分类匹配
|
||
3. 分支处理：
|
||
├─ 无相关文档 → 向用户建议创建新文档，提示：
|
||
│ "本次涉及 [架构/规范/方案]，建议在 docs/ 下创建对应文档固化下来。
|
||
│ 是否创建？可以现在创建，也可以执行完再创建。"
|
||
│
|
||
└─ 有相关文档 → 提示用户：
|
||
"本次任务可能影响 [DOC-xxx]：[文档标题]。
|
||
是否需要在本任务完成后更新该文档？"
|
||
4. 用户决策后继续执行
|
||
5. 执行完成后 → 若用户同意创建/更新文档，则执行操作 C（写入/更新文档）
|
||
```
|
||
|
||
### 不触发的情况
|
||
|
||
- 纯 bug 修复（不改架构/规范）
|
||
- 单文件小改动
|
||
- 临时实验性代码（用户明确标记为实验）
|
||
- 纯数据文件变更
|
||
|
||
---
|
||
|
||
## 操作 B：周期审查（Periodic Review）
|
||
|
||
### 触发条件（满足任一）
|
||
|
||
1. 距离上次审查超过 7 天
|
||
2. 上次审查后新增 30+ 条 changelog 条目
|
||
3. 用户主动触发：`审查文档`、`review docs`、`检查规范一致性`
|
||
|
||
### 状态追踪
|
||
|
||
`.opencode/data/spec-docs/state.json` 格式：
|
||
|
||
```json
|
||
{
|
||
"last_review_date": "2026-05-01",
|
||
"last_processed_changelog_id": "CL-20260501-2303",
|
||
"review_count": 1
|
||
}
|
||
```
|
||
|
||
### 执行流程
|
||
|
||
```
|
||
1. 加载 state.json
|
||
├─ 存在 → 读取 last_processed_changelog_id
|
||
└─ 不存在 → last_processed_changelog_id = null（全量审查）
|
||
|
||
2. 收集 changelog 增量
|
||
a. 读取 changelog-headlines.md（L3）
|
||
b. 筛选 last_processed_changelog_id 之后的新条目
|
||
c. 对于每条新条目，在 changelog-recent.md（L2）中定位并读取完整摘要
|
||
|
||
3. 分类 changelog 条目
|
||
将每条新条目标记为以下三类之一：
|
||
├─ `arch`：涉及架构决策、模块结构、依赖变更
|
||
├─ `conv`：涉及编码规范、命名约定、工作流程
|
||
└─ `none`：不涉及规范文档（纯 bug 修复、单文件改动）
|
||
|
||
4. 加载现有文档
|
||
读取 docs/ 下所有非 README、非模板的 .md 文件，解析 frontmatter
|
||
|
||
5. 一致性校验（对每个文档逐个检查）
|
||
|
||
=== 5a. 遗漏检查：changelog 中有，文档中无 ===
|
||
对于标记为 arch/conv 的 changelog 条目：
|
||
- 检查是否有对应的 docs/ 文档覆盖了此改动
|
||
- 无覆盖 → 列入"遗漏项"：建议创建新文档或追加到已有文档
|
||
|
||
=== 5b. 陈旧检查：文档引用的 changelog 已不反映现状 ===
|
||
对于每个文档的 related_changelogs：
|
||
- 检查引用的 CL-xxx 是否存在于 L1 changelog-full.md
|
||
- 检查被引用的条目在 L1 中的 affected_files 是否仍与文档描述一致
|
||
- 不一致 → 列入"陈旧项"
|
||
|
||
=== 5c. 互斥检查：文档与代码/changelog 描述冲突 ===
|
||
当 5b 发现不一致时，执行深度校验：
|
||
a. 从 changelog 条目的 affected_files 提取文件路径
|
||
b. 搜索实际代码中对应文件（Grep/Glob）
|
||
c. 比对：代码现状 vs 文档描述 vs changelog 记录
|
||
d. 三向对比结果分类：
|
||
|
||
| 代码状态 | 文档描述 | changelog 记录 | 诊断 |
|
||
|---------|---------|---------------|------|
|
||
| 与文档一致 | ✓ | 与文档不一致 | changelog 误记 |
|
||
| 与 changelog 一致 | ✗ | ✓ | 文档需更新 |
|
||
| 与两者都不一致 | ✗/✓ | ✗/✓ | 需人工调查 |
|
||
| 与两者都一致 | ✓ | ✓ | 无冲突 |
|
||
|
||
e. 对于"changelog 误记"：提醒用户修正 changelog
|
||
f. 对于"文档需更新"：列出需更新的具体章节，建议用户更新
|
||
g. 对于"需人工调查"：标记为严重冲突，高亮提醒
|
||
|
||
=== 5d. 引用死亡检查 ===
|
||
- 文档中引用的 CL-xxx 在 L1 中不存在 → 标记为"死亡引用"
|
||
|
||
6. 生成审查报告
|
||
按严重程度排序：
|
||
|
||
[严重] 互斥冲突（需人工调查）
|
||
[警告] 文件缺失（docs/ 缺少本应存在的文档）
|
||
[警告] 文档过时（与代码现状不一致）
|
||
[资讯] 遗漏项（changelog 中有架构级改动但未写入文档）
|
||
[资讯] changelog 误记（changelog 与代码/文档不符）
|
||
|
||
7. 汇报用户
|
||
格式如下：
|
||
|
||
"周期审查报告 — [日期]
|
||
自上次审查以来共 [N] 条改动，其中 [X] 条涉及架构/规范。
|
||
|
||
[严重] ...[条数] 项
|
||
[警告] ...[条数] 项
|
||
[资讯] ...[条数] 项
|
||
|
||
是否需要逐条查看和处理？"
|
||
|
||
8. 更新 state.json（无论用户是否处理了所有问题）
|
||
```
|
||
|
||
### 审查原则
|
||
|
||
- **不自动修改任何文件**——审查仅提供发现和诊断，不自动修改 docs/ 或 changelog
|
||
- **changelog 不可信假设**——始终通过检索实际代码来验证 changelog 的准确性
|
||
- **幂等**——重复执行同一次审查不会产生重复报告
|
||
|
||
---
|
||
|
||
## 操作 C：文档写入/更新
|
||
|
||
### 创建新文档
|
||
|
||
```
|
||
1. 读取 docs/ 下对应子目录，确定编号（如 architecture 下最大为 002）
|
||
2. 分配 DOC-NNN 编号，创建文件
|
||
3. 写入 frontmatter（status: draft）
|
||
4. 写入文档正文
|
||
5. 在 related_changelogs 中记录当前触发的 CL-xxx
|
||
```
|
||
|
||
### 更新已有文档
|
||
|
||
```
|
||
1. 修改文档内容
|
||
2. 更新 frontmatter 中的 updated 日期
|
||
3. 在 related_changelogs 中追加新的 CL-xxx（去重）
|
||
4. 如改动较大，将 status 从 stable 改为 review，提请用户确认后改回 stable
|
||
```
|
||
|
||
### 废弃文档
|
||
|
||
```
|
||
1. 将 frontmatter status 改为 deprecated
|
||
2. 在文档顶部添加废弃提示（替代文档编号）
|
||
3. 保留文档内容不删除（供历史追溯）
|
||
```
|
||
|
||
## 自迭代日志
|
||
|
||
### 已知必要检查
|
||
|
||
（暂无）
|