文档同步

保持 DevDocs 文档与实际实现进度一致，检测偏差并更新状态。

语言规则

• 支持中英文提问
• 统一中文回复
• 使用中文生成文档

触发条件

• 用户完成一个或多个开发任务后
• 用户要求检查文档与代码一致性
• 用户需要更新文档进度
• 定期同步（如 Sprint 结束时）

运行模式

/devdocs-sync                    → 完整同步（检查 + 确认 + 更新）
/devdocs-sync --check            → 仅检查，不更新文档
/devdocs-sync --absorb           → 吸收模式（自动 + 智能补齐）
/devdocs-sync --archive          → 强制归档已完成任务
/devdocs-sync T-01 T-02          → 指定范围同步

模式对比

核心理念

文档与代码的关系

文档定义（计划）          代码实现（实际）
     │                        │
     ├── F-XXX 功能点    ←→   ├── 功能模块
     ├── AC-XXX 验收标准 ←→   ├── 业务逻辑
     ├── T-XX 开发任务   ←→   ├── 代码提交
     └── UT/IT/E2E 测试  ←→   └── 测试文件

核心原则：

• 文档是计划，代码是实现
• 偏差是正常的，关键是及时同步
• 同步应该双向：文档→代码（指导）、代码→文档（记录）

同步时机

工作流程

1. 读取 DevDocs 文档
   │
   ▼
2. 扫描代码库（工作区状态）
   ├── 检查文件是否存在（Glob）
   ├── 运行测试（获取实时结果）
   ├── 检查未提交变更（git status）
   └── 参考提交记录（git log，辅助）
   │
   ▼
3. 对比分析
   ├── 任务完成状态
   ├── 测试覆盖情况
   └── 功能实现状态
   │
   ▼
4. 生成偏差报告
   │
   ▼
5. 询问用户确认更新
   │
   ▼
6. 更新文档

重要：检查基于当前工作区状态，而非仅依赖 git 提交历史。未提交的代码变更也会被检测到。

吸收模式 (–absorb)

从”检查员”进化为”记录员”，支持”代码优先”开发路径。

吸收模式流程

1. 执行标准检查（同 sync）
   │
   ▼
2. 分类偏差
   │
   ├── 低风险偏差 → 自动吸收（无需确认）
   └── 高风险偏差 → 生成建议（需确认）
   │
   ▼
3. 执行自动吸收
   │
   ├── 更新任务状态
   ├── 更新测试结果
   └── 更新追溯矩阵
   │
   ▼
4. 展示高风险建议
   │
   ▼
5. 用户确认高风险变更
   │
   ▼
6. 执行确认的变更

吸收规则

低风险（自动吸收，无需确认）

自动吸收条件：

• 仅更新状态字段（✅/⏳/❌）
• 不新增内容，不删除内容
• 不修改描述性文字

高风险（需确认）

高风险处理：

## 需确认的变更

### 1. 新增接口（来源：src/services/cache.ts）

建议追加到 02-system-design.md：

```typescript
interface ICacheService {
  get(key: string): Promise<any>;
  set(key: string, value: any, ttl?: number): Promise<void>;
}

是否吸收？[是/否/修改]

2. 新增测试（来源：src/services/cache.test.ts）

建议追加到 03-test-cases.md：

请指定关联的 AC 编号：[AC-___]

### 吸收报告

```markdown
# 吸收报告

**执行时间**：2024-XX-XX
**模式**：--absorb

## 自动吸收（已完成）

| 文档 | 变更项 | 数量 |
|------|--------|------|
| 04-dev-tasks.md | 任务状态更新 | 3 |
| 03-test-cases.md | 追溯矩阵状态 | 5 |
| 04-dev-tasks.md | 执行检查清单 | 8 |

## 需确认变更

| 类型 | 来源 | 建议操作 | 状态 |
|------|------|----------|------|
| 新增接口 | cache.ts | 追加到 02 | ⏳ 待确认 |
| 新增测试 | cache.test.ts | 追加到 03 | ⏳ 待确认 |

## 无法自动处理

- `src/utils/helper.ts` - 无法确定关联的功能点
  - 建议：手动补充或使用 `/devdocs-feature --lite`

检查项目

1. 任务状态检查

检查 04-dev-tasks.md 中的任务状态：

| 检查项 | 方法 | 状态更新 |
|--------|------|----------|
| 文件是否存在 | Glob 检查 `涉及文件` | 存在 → 进行中/已完成 |
| 测试是否通过 | 运行测试命令 | 通过 → 已完成 |
| 文件是否有变更 | git status/diff | 有未提交变更 → 标注 |

检查优先级：

1. 工作区状态优先：检查当前文件系统和测试结果
2. 提交记录辅助：git log 仅作为参考，不作为主要依据
3. 未提交变更提示：如有未提交变更，在报告中标注

2. 测试覆盖检查

检查 03-test-cases.md 中的测试状态：

| 检查项 | 方法 | 状态更新 |
|--------|------|----------|
| 测试文件存在 | Glob 检查测试目录 | ✅ 已实现 |
| 测试通过 | 运行测试 | ✅ 通过 / ❌ 失败 |
| 覆盖率达标 | 覆盖率报告 | 达标 / 未达标 |

3. 功能实现检查

检查 01-requirements.md 中的功能状态：

| 功能点 | 检查方法 |
|--------|----------|
| F-XXX | 关联任务全部完成 → 已实现 |
| US-XXX | 关联 E2E 测试通过 → 已验收 |
| AC-XXX | 关联测试通过 → 已满足 |

偏差类型

类型一：文档有，代码无

文档中定义但未实现的内容：

**偏差报告**：
- T-03: 用户认证模块 - 文档定义，代码未实现
  - 涉及文件: `src/services/auth.ts` (不存在)
  - 建议: 继续开发 或 移除任务

类型二：代码有，文档无

代码中实现但未在文档记录的内容：

**偏差报告**：
- 发现未记录的实现:
  - `src/utils/cache.ts` - 缓存工具（无对应任务）
  - 建议: 补充到设计文档 或 确认是否需要

类型三：实现与设计不一致

代码实现与设计文档描述不符：

**偏差报告**：
- 设计文档: IUserService.createUser(CreateUserDTO) → User
- 实际实现: UserService.createUser(email, password) → Promise<User>
- 建议: 更新设计文档 或 修改实现

输出文件

进度报告

生成 docs/devdocs/progress-report.md：

# 进度报告

**生成时间**：2024-XX-XX
**检查范围**：全量

## 总体进度

| 类型 | 总数 | 已完成 | 进行中 | 未开始 | 完成率 |
|------|------|--------|--------|--------|--------|
| 功能点 | 5 | 3 | 1 | 1 | 60% |
| 开发任务 | 12 | 8 | 2 | 2 | 67% |
| 单元测试 | 20 | 15 | 3 | 2 | 75% |
| 集成测试 | 5 | 3 | 1 | 1 | 60% |
| E2E 测试 | 3 | 2 | 0 | 1 | 67% |

## 偏差汇总

### 待实现
- [ ] T-10: 日志模块
- [ ] T-11: 错误处理优化

### 进行中（有未提交变更）
- [ ] T-09: 缓存模块 ⚠️ `src/cache.ts` 已修改但未提交

### 待补充文档
- [ ] `src/utils/validator.ts` - 验证工具（未提交）

### 待修正
- [ ] IUserService 接口签名与实现不一致

## 下一步建议

1. 优先完成 T-10 日志模块（阻塞其他任务）
2. 补充 validator.ts 的文档记录
3. 统一 IUserService 接口定义

文档更新

更新以下文档中的状态：

同步命令

快速检查

# 检查任务状态（不更新文档）
/devdocs-sync --check

# 输出: 偏差报告（仅显示，不写入）

完整同步

# 完整同步（检查 + 更新文档）
/devdocs-sync

# 流程:
# 1. 检查所有偏差
# 2. 显示偏差报告
# 3. 询问确认
# 4. 更新文档

吸收模式

# 吸收模式（自动 + 智能补齐）
/devdocs-sync --absorb

# 流程:
# 1. 执行标准检查
# 2. 低风险偏差自动吸收（状态更新）
# 3. 高风险偏差生成建议
# 4. 用户确认高风险变更
# 5. 生成吸收报告

典型使用场景：

• 完成一批任务后，快速同步状态
• “代码优先”开发后，补齐文档记录
• Sprint 结束时，批量更新进度

指定范围

# 只同步特定任务
/devdocs-sync T-01 T-02

# 只同步测试状态
/devdocs-sync --tests

任务归档

# 检测并建议归档
/devdocs-sync
# → 如检测到已完成任务过多，自动建议归档

# 强制执行归档
/devdocs-sync --archive

任务归档功能

归档触发条件

同步时自动检测以下条件：

• 04-dev-tasks.md 超过 300 行
• 已完成任务超过 15 个

满足条件时，在偏差报告中提示：

⚠️ 建议归档：已完成任务 18 个，超过阈值 15 个
是否将已完成任务归档？[是/否]

归档规则

主文档保留：

• 所有”待开发”和”进行中”任务
• 最近完成的 5 个任务

归档文件：04-dev-tasks-archive.md

归档结构：按功能点 (F-XXX) 分组

# 已完成任务归档

## F-001: 用户注册

### T-01: 数据库表设计 ✅
- **完成时间**：2024-01-15
- **关联需求**：F-001, AC-001
- **涉及文件**：`src/db/schema.ts`
- **测试结果**：IT-001 通过

---

## F-002: 用户登录
...

归档流程

1. 检测归档条件
   │
   ├── 未满足 → 正常同步
   │
   └── 满足 → 询问用户
         │
         ├── 拒绝 → 正常同步
         │
         └── 确认
               │
               ▼
2. 识别待归档任务
   ├── 已完成且不在"最近5个"内
   └── 按关联功能点 (F-XXX) 分组
         │
         ▼
3. 更新归档文件
   ├── 追加到对应功能点分组
   └── 按完成时间排序
         │
         ▼
4. 更新主文档
   ├── 移除已归档任务详情
   ├── 保留执行检查清单
   └── 添加归档引用链接

归档后的主文档

## 任务列表

> 已完成任务已归档至 [04-dev-tasks-archive.md](04-dev-tasks-archive.md)

### 最近完成

#### T-15: 缓存优化 ✅ (2024-01-25)
...

#### T-14: 日志模块 ✅ (2024-01-24)
...

### 进行中

#### T-16: 监控集成
...

### 待开发

#### T-17: 性能优化
...

约束

检查约束

• 必须读取所有 DevDocs 文档后再进行检查
• 必须生成偏差报告
• 更新文档前必须询问用户确认（吸收模式低风险除外）
• 检查结果必须可追溯（显示检查方法）

更新约束

• 不自动删除文档内容，只标记状态
• 不自动修改代码，只更新文档
• 保留原有文档结构
• 更新时记录时间戳

吸收模式约束

• 低风险吸收仅限状态字段更新
• 高风险吸收必须用户确认
• 新增内容必须指定关联编号（AC/F/US）
• 无法确定关联的内容标记为”待手动处理”
• 吸收操作必须生成吸收报告

安全约束

• 不执行未知的 shell 命令
• 测试命令使用项目配置的命令
• 大规模更新前必须确认

Skill 协作

使用示例

示例一：Sprint 结束同步

用户: /devdocs-sync

Agent:
1. 读取 DevDocs 文档...
2. 扫描代码库...
3. 对比分析...

**偏差报告**:

已完成但未更新:
- T-05: 用户登录接口 (代码已实现，测试通过)
- T-06: 密码加密 (代码已实现，测试通过)

未完成:
- T-07: 邮箱验证 (文件不存在)

是否更新文档？[确认/取消]

用户: 确认

Agent:
✅ 已更新 04-dev-tasks.md
✅ 已更新 03-test-cases.md
✅ 已生成 progress-report.md

示例二：快速检查

用户: /devdocs-sync --check

Agent:
**快速检查结果**:

任务进度: 8/12 完成 (67%)
测试覆盖: 18/25 通过 (72%)

偏差:
- 2 个任务状态需更新
- 1 个新增文件未记录

使用 `/devdocs-sync` 或 `/devdocs-sync --absorb` 进行同步。

下一步

同步完成后，可根据进度报告：

• 继续开发未完成任务
• 补充缺失的文档记录
• 修正不一致的设计