# 完整性自检详细方法

> 本文件包含 18 个自检维度的详细定义、检查方法和报告模板。
> 在执行工作流 Phase 6（自检）时读取本文件。

---

## 📋 目录

1. [三层自检体系](#三层自检体系)
2. [第一层：结构完整（S1-S7）](#第一层结构完整s1-s7)
3. [第二层：内容有效（C1-C6）](#第二层内容有效c1-c6)
4. [第三层：体系健康（H1-H5）](#第三层体系健康h1-h5)
5. [维度间依赖关系](#维度间依赖关系)
6. [执行顺序](#执行顺序)
7. [自检报告固定模板](#自检报告固定模板)
8. [与 contract-doc-sync 的分工](#与contract-doc-sync的分工)

---

## 三层自检体系

| 层次 | 问题 | 确定性 | 执行时机 |
|------|------|--------|---------|
| **结构完整 (S)** | 文档是否包含应有的章节？关系是否正确？ | 🤖 全自动 | 生成后立即 |
| **内容有效 (C)** | 文档内容是否与代码一致？引用是否有效？ | 🤖👤 半自动 | 生成后 + 代码变更时 |
| **体系健康 (H)** | 文档系统是否覆盖所有需要的领域？ | 👤 人工判断 | 按需/定期 |

---

## 第一层：结构完整（S1-S7）

### S1 模板合规

- **检查内容**：每份文档是否包含模板定义的固定章节
- **方法**：`scripts/md-sections.sh <file>` → 获取章节树 → 比对模板定义
- **通过标准**：所有固定章节都存在
- **修复权限**：🤖 自动

### S2 目录完整

- **检查内容**：📋 目录章节是否与实际章节一致
- **方法**：提取目录章节名 vs 实际章节名 → 逐一比对
- **通过标准**：目录列出的章节全部存在，无遗漏无多余
- **修复权限**：🤖 自动

### S3 交叉引用

- **检查内容**：文档间 Markdown 链接是否指向存在的文件/章节
- **方法**：提取 `[text](path)` 链接 → 验证目标文件存在 → 验证锚点章节存在
- **通过标准**：所有链接有效
- **修复权限**：🤖 自动

### S4 入口索引覆盖

- **检查内容**：入口文件（AGENTS.md 或等效文件）是否覆盖所有文档
- **方法**：扫描 docs/ 目录下所有 .md 文件 → 比对入口文件中的引用
- **通过标准**：入口文件引用了所有文档
- **修复权限**：🤖 自动

### S5 轨道标签

- **检查内容**：每份文档是否标注了所属轨道
- **方法**：正则匹配 🔴 / 🟢 / 🔵 标记或 Intent / Contract / Constraint 关键词
- **通过标准**：所有文档已标注
- **修复权限**：🤖 自动

### S6 引用强度

- **检查内容**：入口文件中每个文档条目是否标注了引用强度
- **方法**：正则匹配 ⛔ / ⚠️ / 💡 或 MUST / SHOULD / MAY
- **通过标准**：所有条目已标注
- **修复权限**：🤖 自动

### S7 变更历史

- **检查内容**：Contract 轨文档是否有变更历史章节
- **方法**：`scripts/md-sections.sh <file>` → 检查"变更历史"章节存在
- **通过标准**：所有 Contract 轨文档包含变更历史
- **修复权限**：🤖 自动

---

## 第二层：内容有效（C1-C6）

### C1 代码引用存在

- **检查内容**：文档提到的类/函数/配置是否在代码中存在
- **方法**：提取文档中的代码引用（类名、函数名、配置项）→ Grep 代码库
- **通过标准**：所有引用存在
- **修复权限**：🤖👤（检测自动，是否修复需人类判断）

### C2 API 签名一致

- **检查内容**：文档中的 API 描述是否与代码签名一致
- **方法**：根据技术栈选择 API 提取方式（注解/装饰器/export/路由配置）
- **泛化策略**：不在技能中硬编码，根据识别到的技术栈现场推导检测方式
- **通过标准**：API 描述与代码一致
- **修复权限**：🤖👤

### C3 数据模型一致

- **检查内容**：文档中的数据模型/类图是否与代码一致
- **方法**：根据技术栈选择模型提取方式（Entity/Schema/Type/Struct）
- **泛化策略**：同 C2
- **通过标准**：模型描述与代码一致
- **修复权限**：🤖👤

### C4 配置项一致

- **检查内容**：文档中的配置项是否与代码定义一致
- **方法**：根据技术栈选择配置提取方式（Properties类/环境变量/config文件）
- **泛化策略**：同 C2
- **通过标准**：配置项与代码一致
- **修复权限**：🤖👤

### C5 版本号一致

- **检查内容**：文档中的版本号是否与构建文件一致
- **方法**：根据构建系统选择（pom.xml / package.json / Cargo.toml / go.mod / CMakeLists.txt）
- **通过标准**：版本号匹配
- **修复权限**：🤖👤

### C6 语义一致

- **检查内容**：文档描述的行为是否与代码实际行为一致
- **方法**：LLM 阅读 + 分析（深度模式）
- **通过标准**：行为描述与代码一致
- **修复权限**：🤖👤
- **适用**：仅在用户要求深度检查时执行

### 内容有效维度的泛化策略

C2/C3/C4/C5 的检测方式根据技术栈**现场推导**：

| 维度 | Java 示例 | JS/TS 示例 | Go 示例 | C++ 示例 |
|------|----------|-----------|---------|---------|
| C2 API | @PostMapping 注解 | export function | func (http.Handler) | 头文件声明 |
| C3 模型 | Java Entity | TypeScript interface | struct | struct/class |
| C4 配置 | @ConfigurationProperties | .env / config.json | struct tags | config.hpp |
| C5 版本 | pom.xml | package.json | go.mod | CMakeLists.txt |

推导结果记录在项目的文档系统元数据中，供 contract-doc-sync 复用。

---

## 第三层：体系健康（H1-H5）

### H1 模块覆盖

- **检查内容**：每个代码模块是否有对应的文档
- **方法**：Phase 2 的模块列表 vs 生成的文档列表
- **通过标准**：所有模块有文档
- **修复权限**：👤（需要人类判断是否需要为小模块创建文档）

### H2 关注点覆盖

- **检查内容**：识别到的关注点是否都有规范文档
- **方法**：Phase 2 的关注点列表 vs Constraint 轨文档列表
- **通过标准**：所有主要关注点有文档
- **修复权限**：👤

### H3 职责唯一

- **检查内容**：是否有两份文档回答了同一个问题
- **方法**：分析每份文档的一句话职责 → 查重
- **通过标准**：所有文档职责唯一
- **修复权限**：👤（需要判断是合并还是重新切分）

### H4 信息孤岛

- **检查内容**：是否有文档未被任何其他文档引用
- **方法**：构建交叉引用图 → 找入度为 0 的节点
- **通过标准**：所有文档被至少一个文档引用（入口文件除外）
- **修复权限**：👤

### H5 业界对标

- **检查内容**：文档体系是否覆盖了该领域常见关注点
- **方法**：**现场调研** → 对比项目文档 vs 业界常见关注点
- **通过标准**：覆盖主要关注点
- **修复权限**：👤

---

## 维度间依赖关系

```
S5 (轨道标签) → S1 (模板合规) → S3 (交叉引用)
                                    ↓
S4 (入口索引) ──────────────→ S3 (交叉引用)
                                    ↓
S1 (模板合规) → C1 (代码引用) → C2 (API 签名)
                            → C3 (数据模型)
                            → C4 (配置项)
                            → C5 (版本号)
                                    ↓
                              C6 (语义一致) ← 依赖 C1-C5 的结果
                                    ↓
S7 (变更历史) ──→ 独立维度
H1-H5 ────────→ 独立维度（体系级）
```

---

## 执行顺序

1. **S5** 轨道标签 → **S1** 模板合规（确认结构正确）
2. **S4** 入口索引 + **S3** 交叉引用（确认关系正确）
3. **C1-C5** 并行（代码级内容检查）
4. **C6** 语义一致（深度检查）
5. **S7** + **H1-H5**（体系和历史检查）

---

## 自检报告固定模板

```
📋 文档系统完整性报告

## 结构完整性 (🤖 全自动)
  ✅/⚠️/❌ S1 模板合规: {通过数}/{总数} 文档包含所有固定章节
  ✅/⚠️/❌ S2 目录完整: {通过数}/{总数} 文档的📋目录与实际章节一致
  ✅/⚠️/❌ S3 交叉引用: {有效数}/{总数} 链接有效
  ✅/⚠️/❌ S4 入口索引: 入口文件覆盖 {覆盖数}/{总文档数} 文档
  ✅/⚠️/❌ S5 轨道标签: {标注数}/{总数} 文档已标注轨道
  ✅/⚠️/❌ S6 引用强度: {标注数}/{总数} 文档已标注强度
  ✅/⚠️/❌ S7 变更历史: Contract 轨 {有变更历史数}/{Contract总数} 文档包含变更历史

## 内容有效性 (🤖👤 半自动)
  ✅/⚠️/❌ C1 代码引用: {有效数}/{总数} 引用存在于代码库
  ✅/⚠️/❌ C2 API 签名: {一致数}/{检查数} API 描述与代码一致
  ✅/⚠️/❌ C3 数据模型: {一致数}/{检查数} 模型描述与代码一致
  ✅/⚠️/❌ C4 配置项: {一致数}/{检查数} 配置项与代码一致
  ✅/⚠️/❌ C5 版本号: {一致数}/{检查数} 版本号与构建文件一致
  ✅/⚠️/❌ C6 语义一致: {通过数}/{检查数} 行为描述与代码一致

## 体系健康性 (👤 人工判断)
  ⚠️ H1 模块覆盖: {有文档数}/{总模块数} 模块有文档 [{缺失列表}]
  ⚠️ H2 关注点覆盖: {有文档数}/{总关注点数} 关注点有文档 [{缺失列表}]
  ⚠️ H3 职责唯一: {唯一数}/{总数} 文档职责唯一 [{重复列表}]
  ⚠️ H4 信息孤岛: {被引用数}/{总数} 文档被至少一个文档引用 [{孤立列表}]
  ⚠️ H5 业界对标: 调研发现 {N} 个常见关注点，项目覆盖 {M}/{N} [{缺失列表}]

## 发现详情
  {逐项列出所有 ⚠️ 和 ❌ 的具体内容}

## 建议操作
  {按优先级列出需要修复的项目}
```

**符号说明**：✅ 全部通过 / ⚠️ 部分通过或有风险 / ❌ 不通过或缺失

---

## 与 contract-doc-sync 的分工

```
新技能（doc-system-generator）     contract-doc-sync（持续维护）
───────────────────────     ─────────────────────
生成后：S1-S7 全量检查       日常：C1-C6 漂移检测
生成后：C1-C6 初始基线       日常：C1-C6 同步修复
按需：H1-H5 体系检查         日常：多级同步（L0-L3）

→ 新技能生成时产出的"检测方式配置"（技术栈适配的 C2/C3/C4/C5 检测逻辑）
  可直接被 contract-doc-sync 复用，解决其"绑定特定技术栈"的问题。
```