datai/docs/archive/skill/0002-establish-ssot-hub.md

---
name: 0002-establish-ssot-hub
description: 建立项目唯一真源中心，创建 docs/index.md 作为项目文档的唯一入口
---

# 技能：建立真源中心 (Establish SSOT Hub)

## 元数据 (Metadata)

- **name**: establish-ssot-hub
- **description**: 建立项目唯一真源中心，创建 docs/index.md 作为项目文档的唯一入口
- **version**: 1.0.0
- **author**: SSOT Architect
- **lastUpdated**: 2026-01-15

## 触发与定位 (Triggers & Scope)

### 触发条件 (Triggers)
当以下情况发生时，AI 应当"觉醒"本技能：

1. **Bootstrap 完成**: 完成项目协作基线初始化后
2. **缺少文档入口**: 检测到 `docs/index.md` 不存在
3. **文档索引更新**: 创建新的需求、设计、决策或提示词文档后
4. **孤儿文件检测**: 发现未被索引的文档文件
5. **工作流阶段 2**: 用户进入工作流的"建立真源中心"阶段

### 定位范围 (Scope)
- **适用模块**: 所有 Datai 项目模块
- **影响文件**: `docs/index.md`
- **索引范围**: docs/ 下的所有子目录和文档
- **相关技能**: skill-bootstrap-workflow, skill-setup-information-architecture

## 核心指令集 (Instructions)

### 架构约束 (Architecture Constraints)

1. **docs/index.md 的核心规则**:
   - 这是项目的**唯一**文档入口
   - 它不仅是列表，更是导航图
   - 必须包含对 Requirements, Design, ADRs, Prompts, Sessions, Retros 的动态索引
   - **严禁出现"孤儿文件"**（即未被 index 索引的文件）

2. **必须索引的文档类型**:
   - `docs/requirements/` - 需求文档
   - `docs/design/` - 系统设计文档
   - `docs/decisions/adr/` - 架构决策记录
   - `docs/prompts/` - 提示词资产
   - `docs/sessions/` - AI 会话快照
   - `docs/retros/` - 迭代复盘
   - `docs/changelog/` - 变更记录
   - `docs/skills/` - 技能文档

3. **索引结构要求**:
   - 按文档类型分组
   - 每个文档必须包含状态标识（Draft/In Progress/Completed）
   - 必须包含文档的创建/更新日期
   - 必须包含文档的简要描述

### 业务逻辑 SOP (Business Logic SOP)

#### 步骤 1: 检查 docs/index.md 是否存在
```bash
# 检查文档入口是否存在
if [ ! -f "docs/index.md" ]; then
    echo "警告: docs/index.md 不存在，需要创建"
fi
```

#### 步骤 2: 扫描 docs/ 目录结构
```bash
# 使用 LS 工具扫描 docs/ 目录
# 列出所有子目录和文件
```

#### 步骤 3: 识别孤儿文件
```bash
# 读取 docs/index.md 内容
# 提取所有已索引的文档路径
# 对比 docs/ 目录中的实际文件
# 标记未被索引的文件为"孤儿文件"
```

#### 步骤 4: 创建或更新 docs/index.md
```markdown
# Datai 项目文档中心 (SSOT Hub)

> 本文档是项目的唯一真源入口，所有文档必须在此索引。

## 📋 文档导航

### 📝 需求文档 (Requirements)
| 文档 | 状态 | 描述 | 更新日期 |
|------|------|------|----------|
| [REQ-001](requirements/REQ-001.md) | ✅ Completed | 初始需求 | 2026-01-15 |
| [REQ-002](requirements/REQ-002.md) | 🔄 In Progress | 新功能需求 | 2026-01-15 |

### 🏗️ 系统设计 (Design)
| 文档 | 状态 | 描述 | 更新日期 |
|------|------|------|----------|
| [DES-001](design/DES-001.md) | ✅ Completed | 架构设计 | 2026-01-15 |
| [DES-002](design/DES-002.md) | 📝 Draft | 接口设计 | 2026-01-15 |

### 🎯 架构决策 (ADRs)
| 文档 | 状态 | 描述 | 更新日期 |
|------|------|------|----------|
| [ADR-001](decisions/adr/ADR-001.md) | ✅ Accepted | 技术栈选择 | 2026-01-15 |
| [ADR-002](decisions/adr/ADR-002.md) | 📝 Draft | 数据库设计 | 2026-01-15 |

### 💡 提示词资产 (Prompts)
| 文档 | 版本 | 描述 | 更新日期 |
|------|------|------|----------|
| [PROMPT-001](prompts/PROMPT-001.md) | v1.0.0 | 工作流提示词 | 2026-01-15 |
| [PROMPT-002](prompts/PROMPT-002.md) | v1.0.0 | 代码生成提示词 | 2026-01-15 |

### 🗣️ 会话记录 (Sessions)
| 文档 | 触发 | 结果 | 日期 |
|------|------|------|------|
| [20260115-TaskName](sessions/20260115-TaskName.md) | REQ-001 | Commit: abc123 | 2026-01-15 |

### 🔄 迭代复盘 (Retros)
| 文档 | 类型 | 日期 |
|------|------|------|
| [20260115-Review](retros/20260115-Review.md) | Sprint Review | 2026-01-15 |

### 📊 变更记录 (Changelog)
| 文档 | 版本 | 日期 |
|------|------|------|
| [CHANGELOG](changelog/CHANGELOG.md) | v1.0.0 | 2026-01-15 |

### 🛠️ 技能文档 (Skills)
| 文档 | 描述 | 版本 |
|------|------|------|
| [Bootstrap Workflow](skills/0001-bootstrap-workflow.md) | 项目协作基线初始化 | v1.0.0 |
| [SSOT Hub](skills/0002-establish-ssot-hub.md) | 建立真源中心 | v1.0.0 |

## ⚠️ 孤儿文件警告

以下文档未被索引，请及时处理：
- [文件路径](file/path) - 原因说明

## 📊 统计信息

- 需求文档: X 个
- 设计文档: X 个
- 架构决策: X 个
- 提示词资产: X 个
- 会话记录: X 个
- 迭代复盘: X 个
- 变更记录: X 个
- 技能文档: X 个

## 🔗 快速链接

- [项目 README](../README.md)
- [贡献指南](../CONTRIBUTING.md)
- [变更日志](../CHANGELOG.md)
```

#### 步骤 5: 验证索引完整性
```bash
# 验证所有文档都被索引
# 检查是否有孤儿文件
# 如果有，提示用户处理
```

### 工具调用 (Tool Usage)

1. **目录扫描工具**:
   - 使用 `LS` 工具递归扫描 `docs/` 目录
   - 列出所有文件和子目录

2. **文件读取工具**:
   - 使用 `Read` 工具读取 `docs/index.md` 现有内容
   - 使用 `Read` 工具读取各文档的元数据

3. **文件搜索工具**:
   - 使用 `Grep` 工具搜索文档中的元数据标记
   - 使用 `SearchCodebase` 工具查找特定类型的文档

4. **文件创建/更新工具**:
   - 使用 `Write` 工具创建或更新 `docs/index.md`
   - 确保索引格式一致

## 错误陷阱与验证 (Anti-Patterns & Checklist)

### 常见错误 (Anti-Patterns)

1. **错误**: 创建了新文档但未更新 docs/index.md
   - **后果**: 产生孤儿文件，违反 SSOT 原则
   - **修正**: 每次创建新文档后必须更新索引

2. **错误**: docs/index.md 只是简单的文件列表
   - **后果**: 无法作为有效的导航图
   - **修正**: 必须包含状态、描述、日期等元数据

3. **错误**: 索引格式不一致
   - **后果**: 难以维护和查找
   - **修正**: 使用统一的 Markdown 表格格式

4. **错误**: 忽略孤儿文件警告
   - **后果**: 文档结构混乱，违反 SSOT 原则
   - **修正**: 及时处理或删除孤儿文件

5. **错误**: 删除文档后未更新索引
   - **后果**: 索引包含无效链接
   - **修正**: 删除文档时同步更新索引

### 验收清单 (Acceptance Checklist)

- [ ] docs/index.md 已创建或更新
- [ ] 所有文档类型都已索引
- [ ] 每个文档都包含状态标识
- [ ] 每个文档都包含创建/更新日期
- [ ] 每个文档都包含简要描述
- [ ] 没有孤儿文件
- [ ] 索引格式统一
- [ ] 统计信息准确
- [ ] 快速链接有效

### Correct vs Incorrect 对比

#### Correct 示例
```markdown
### 📝 需求文档 (Requirements)
| 文档 | 状态 | 描述 | 更新日期 |
|------|------|------|----------|
| [REQ-001](requirements/REQ-001.md) | ✅ Completed | 初始需求 | 2026-01-15 |
| [REQ-002](requirements/REQ-002.md) | 🔄 In Progress | 新功能需求 | 2026-01-15 |
```

#### Incorrect 示例
```markdown
### 需求文档
- REQ-001.md
- REQ-002.md
```

**问题**: 缺少状态、描述、日期等元数据，无法作为有效的导航图。

## 相关文档 (Related Documents)

- [工作流提示词](../prompts/03-创建工作流提示词.md#phase-2-建立真源中心-ssot-hub)
- [Bootstrap 工作流技能](./0001-bootstrap-workflow.md)
- [信息架构设置技能](./0003-setup-information-architecture.md)
- [SSOT 原则](../prompts/03-创建工作流提示词.md#核心原则无文档不开发)