datai/docs/skill/phase10-code-commit.md

# 阶段 10：代码提交技能书

## A. 元数据 (Metadata)

**name**: `phase10-code-commit`

**description**: 在 Datai 项目中，基于已完成的复盘和 API 文档，提交代码到本地仓库，询问用户是否提交到远程仓库，并更新索引和会话记录。此技能确保代码的可管理性和版本控制。

---

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

### 触发关键词
当用户输入包含以下关键词时，必须觉醒此技能：
- "代码提交"、"提交代码"、"git commit"
- "进入阶段 10"、"下一阶段"
- "git"、"commit"、"push"

### 触发场景
- 用户确认阶段 9 完成，要求进入阶段 10
- 用户要求提交代码
- 用户询问如何提交代码
- 用户提到"按照项目规则"或"SSOT 流程"进行代码提交

### 操作路径
此技能涉及以下文件和目录的操作：
- **检查**: 所有生成的代码文件
- **检查**: 所有生成的文档文件
- **执行**: git 命令（add, commit, push）
- **更新**: `docs/index.md`（记录代码提交信息）
- **更新**: `docs/sessions/YYYY-MM-DD-00X-session.md`
- **读取**: `.trae/rules/project_rules.md` (项目规则)
- **读取**: `docs/Prompt/0004-单一真源文档驱动架构师.md` (SSOT 架构师提示词)

### SSOT 依赖
必须参考以下"唯一真源"：
- [会话记录](file:///d:\idea_demo\datai\docs\sessions\YYYY-MM-DD-00X-session.md) - 阶段 9 更新的会话记录
- [项目规则](file:///d:\idea_demo\datai\.trae\rules\project_rules.md) - 项目规则和阶段定义
- [0004-单一真源文档驱动架构师.md](file:///d:\idea_demo\datai\docs\Prompt\0004-单一真源文档驱动架构师.md) - SSOT 架构师提示词

---

## C. 核心指令集 (Instructions)

### 架构约束

#### 1. 代码检查约束（强制）
- 必须检查所有生成的代码文件
- 必须检查所有生成的文档文件
- 确保代码文件符合项目规范
- 确保文档文件符合项目规范

#### 2. 提交信息约束（强制）
- 提交信息格式：`feat: [需求编号] 需求描述`
- 示例：`feat: [001] 实现用户登录功能`
- 提交信息必须清晰、准确，描述本次提交的主要内容

#### 3. 本地提交约束（强制）
- 必须使用 `git add` 添加所有变更
- 必须使用 `git commit` 提交到本地仓库
- 确保所有文件都已添加到提交中

#### 4. 远程提交约束（强制）
- 必须询问用户是否提交到远程仓库
- 如果用户确认，使用 `git push` 推送到远程
- 如果用户不确认，跳过推送

#### 5. 索引更新约束（强制）
- 必须在提交代码后更新 `docs/index.md`
- 必须记录代码提交信息
- 采用增量更新策略，**严禁**删除现有内容

#### 6. 会话记录约束（强制）
- 必须更新 `docs/sessions/YYYY-MM-DD-00X-session.md`
- 必须更新当前阶段为"阶段 10：代码提交"
- 必须记录代码提交信息
- 必须标记需求为已完成

### 业务逻辑 SOP（标准操作流程）

#### 步骤 1：代码和文档检查（Let's think step by step）
在提交代码前，必须执行以下检查：

1. **检查所有生成的代码文件**
   - 确认代码文件的路径和命名是否符合项目规范
   - 确认代码文件的内容是否符合项目规范
   - 确认代码文件是否包含单元测试
   - 确认代码文件是否通过编译和测试

2. **检查所有生成的文档文件**
   - 确认文档文件的路径和命名是否符合项目规范
   - 确认文档文件的内容是否符合项目规范
   - 确认文档文件之间的引用是否正确
   - 确认文档文件是否完整、准确

3. **确认提交信息**
   - 确定提交信息的格式：`feat: [需求编号] 需求描述`
   - 确保提交信息清晰、准确
   - 确保提交信息描述了本次提交的主要内容

#### 步骤 2：提交代码到本地
1. **添加所有变更**
   - 使用 `git add .` 添加所有变更到暂存区
   - 或使用 `git add <file>` 添加特定文件到暂存区
   - 确保所有生成的代码文件和文档文件都已添加

2. **提交到本地仓库**
   - 使用 `git commit -m "feat: [需求编号] 需求描述"` 提交到本地仓库
   - 确保提交信息符合项目规范
   - 确保提交成功

#### 步骤 3：询问用户是否提交到远程
1. **向用户询问**
   - 显示本地提交的信息
   - 询问："是否需要提交到远程仓库？"

2. **根据用户反馈执行**
   - 如果用户确认，使用 `git push` 推送到远程仓库
   - 如果用户不确认，跳过推送
   - 确保推送成功（如果执行）

#### 步骤 4：更新索引
1. **读取现有索引**
   - 使用 Read 工具读取 `docs/index.md`
   - 找到"代码提交记录"部分
   - 如果不存在，则创建该部分

2. **添加代码提交信息**
   - 在"代码提交记录"部分追加新的提交信息
   - 格式：`- YYYY-MM-DD: [提交信息] - [本地/远程]`
   - 示例：`- 2026-01-21: feat: [001] 实现用户登录功能 - 本地+远程`

3. **保存索引**
   - 使用 Write 工具更新 `docs/index.md`
   - **严禁**删除现有内容，只追加新内容

#### 步骤 5：更新会话记录
1. **读取现有会话记录**
   - 使用 Read 工具读取 `docs/sessions/YYYY-MM-DD-00X-session.md`

2. **更新阶段 10 信息**
   - 更新"当前阶段"为"阶段 10：代码提交"
   - 更新"阶段 10：代码提交"的状态为"已完成"
   - 添加代码提交信息
   - 标记需求为已完成

3. **保存会话记录**
   - 使用 Write 工具更新会话记录

#### 步骤 6：确认与总结
1. **向用户确认**
   - 显示代码提交的结果
   - 显示更新后的索引链接
   - 显示更新后的会话记录链接
   - 询问："代码是否已提交到本地？"
   - 询问："是否需要提交到远程仓库？"（如果尚未询问）

2. **总结本次执行**
   - 总结本次执行的主要内容
   - 总结生成的文档和代码
   - 总结遇到的问题和解决方案
   - 总结学到的经验和教训

### 工具调用

#### 必须使用的工具
1. **RunCommand 工具**：执行 git 命令
   - 使用场景：添加变更、提交到本地、推送到远程
   - 命令：`RunCommand(command="git add .", blocking=true, requires_approval=false, target_terminal="new")`
   - 命令：`RunCommand(command="git commit -m \"feat: [001] 实现用户登录功能\"")`, blocking=true, requires_approval=false, target_terminal="new")`
   - 命令：`RunCommand(command="git push", blocking=true, requires_approval=false, target_terminal="new")`

2. **Read 工具**：读取现有文件
   - 使用场景：读取索引、会话记录
   - 命令：`Read(file_path="d:\\idea_demo\\datai\\docs\\index.md")`

3. **Write 工具**：创建或更新文件
   - 使用场景：更新索引、更新会话记录
   - 命令：`Write(file_path="d:\\idea_demo\\datai\\docs\\index.md", content="...")`

#### 可选使用的工具
1. **TodoWrite 工具**：管理任务
   - 使用场景：跟踪阶段执行进度
   - 命令：`TodoWrite(todos=[...])`

2. **GetDiagnostics 工具**：获取代码诊断
   - 使用场景：检查代码的语法错误和类型错误
   - 命令：`GetDiagnostics()`

---

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

### 常见错误（Anti-Patterns）

#### 错误 1：不检查代码和文档就提交
**错误示例**：
```
AI：直接执行 git add .
AI：直接执行 git commit
AI：完成
```

**问题**：
- 没有检查代码和文档的正确性
- 可能提交错误的代码或文档
- 违反了项目规则

**正确示例**：
```
AI：检查所有生成的代码文件
AI：检查所有生成的文档文件
AI：确认代码和文档符合项目规范
AI：执行 git add .
AI：执行 git commit
AI：完成
```

#### 错误 2：提交信息不符合规范
**错误示例**：
```
AI：git commit -m "完成功能"
```

**问题**：
- 提交信息过于简单
- 没有遵循项目规范的提交信息格式
- 其他开发人员无法快速了解提交的内容

**正确示例**：
```
AI：git commit -m "feat: [001] 实现用户登录功能"
```

#### 错误 3：不询问用户就推送到远程
**错误示例**：
```
AI：执行 git add .
AI：执行 git commit
AI：直接执行 git push
AI：完成
```

**问题**：
- 违反了项目规则
- 没有尊重用户的决策权
- 可能导致不必要的远程分支污染

**正确示例**：
```
AI：执行 git add .
AI：执行 git commit
AI：询问用户是否提交到远程仓库
AI：如果用户确认，执行 git push
AI：完成
```

#### 错误 4：不更新索引和会话记录
**错误示例**：
```
AI：执行 git add .
AI：执行 git commit
AI：询问用户是否提交到远程仓库
AI：完成（忘记更新索引和会话记录）
```

**问题**：
- 违反了项目规则
- 索引中没有记录代码提交信息
- 会话记录中没有记录代码提交信息
- 其他开发人员无法快速了解代码提交情况

**正确示例**：
```
AI：执行 git add .
AI：执行 git commit
AI：询问用户是否提交到远程仓库
AI：更新索引，记录代码提交信息
AI：更新会话记录，记录代码提交信息
AI：完成
```

### 验收清单（Checklist）

在完成阶段 10 前，必须检查以下项目：

#### 代码和文档检查
- [ ] 已检查所有生成的代码文件
- [ ] 已检查所有生成的文档文件
- [ ] 代码文件的路径和命名符合项目规范
- [ ] 代码文件的内容符合项目规范
- [ ] 代码文件包含单元测试
- [ ] 代码文件通过编译和测试
- [ ] 文档文件的路径和命名符合项目规范
- [ ] 文档文件的内容符合项目规范
- [ ] 文档文件之间的引用正确
- [ ] 文档文件完整、准确

#### 本地提交检查
- [ ] 已使用 `git add` 添加所有变更
- [ ] 已使用 `git commit` 提交到本地仓库
- [ ] 提交信息格式符合要求：`feat: [需求编号] 需求描述`
- [ ] 提交信息清晰、准确
- [ ] 所有文件都已添加到提交中

#### 远程提交检查
- [ ] 已询问用户是否提交到远程仓库
- [ ] 如果用户确认，已使用 `git push` 推送到远程
- [ ] 如果执行了推送，推送成功

#### 索引更新检查
- [ ] `docs/index.md` 已更新
- [ ] 已记录代码提交信息
- [ ] 索引更新采用增量更新策略，未删除现有内容

#### 会话记录更新检查
- [ ] 会话记录已更新
- [ ] 会话记录的"当前阶段"已更新为"阶段 10：代码提交"
- [ ] 会话记录的"阶段 10：代码提交"状态已更新为"已完成"
- [ ] 会话记录包含代码提交信息
- [ ] 会话记录标记需求为已完成

#### 用户确认检查
- [ ] 已向用户显示代码提交的结果
- [ ] 已向用户显示更新后的索引链接
- [ ] 已向用户显示更新后的会话记录链接
- [ ] 已询问用户"代码是否已提交到本地？"
- [ ] 已询问用户"是否需要提交到远程仓库？"（如果尚未询问）

### Correct vs Incorrect 代码对比

#### Incorrect（错误示例）
```
AI：直接执行 git add .
AI：git commit -m "完成登录功能"
AI：直接执行 git push
AI：完成
```

#### Correct（正确示例）
```
AI：检查所有生成的代码文件和文档文件
AI：确认代码和文档符合项目规范
AI：git add .
AI：git commit -m "feat: [001] 实现用户登录功能"
AI：询问用户是否提交到远程仓库
AI：如果用户确认，git push
AI：更新 docs/index.md，记录代码提交信息
AI：更新会话记录，记录代码提交信息并标记需求为已完成
AI：向用户确认代码提交结果
AI：完成
```

---

## 附录：快速参考

### 文件路径速查
- 主索引：`docs/index.md`
- 会话记录：`docs/sessions/YYYY-MM-DD-00X-session.md`
- 项目规则：`.trae/rules/project_rules.md`
- SSOT 架构师提示词：`docs/Prompt/0004-单一真源文档驱动架构师.md`

### 工具命令速查
```powershell
# 添加所有变更
RunCommand(command="git add .", blocking=true, requires_approval=false, target_terminal="new")

# 提交到本地仓库
RunCommand(command="git commit -m \"feat: [001] 实现用户登录功能\"")`, blocking=true, requires_approval=false, target_terminal="new")`

# 推送到远程仓库
RunCommand(command="git push", blocking=true, requires_approval=false, target_terminal="new")

# 读取索引
Read(file_path="d:\\idea_demo\\datai\\docs\\index.md")

# 更新索引
Write(file_path="d:\\idea_demo\\datai\\docs\\index.md", content="...")
```

### 阶段 10 输出清单
- [ ] 代码提交到本地仓库
- [ ] 代码推送到远程仓库（如果用户确认）
- [ ] 更新的索引：`docs/index.md`
- [ ] 更新的会话记录：`docs/sessions/YYYY-MM-DD-00X-session.md`

### 项目完成总结
当完成阶段 10 后，整个 SSOT 流程即告完成。此时，你已经：
1. **需求定义与入库**：创建了需求文档，建立了需求追踪
2. **方案设计**：创建设计文档，明确了技术方案
3. **方案决策**：创建决策记录，记录了架构决策
4. **数据库结构生成**：生成 SQL 脚本，记录了数据库变更
5. **提示词生成**：生成针对当前需求的提示词
6. **执行代码生成**：根据需求和设计生成了代码
7. **记录当前会话**：完整记录了当前会话的所有信息
8. **变更记录与归档**：创建了变更日志，记录了所有变更
9. **闭环复盘和接口文档**：创建了复盘文档和 API 文档
10. **代码提交**：提交代码到本地仓库，并询问是否提交到远程

通过严格执行 SSOT 流程，确保了所有开发活动都有文档依据，提高了代码的可追溯性、可维护性和质量。同时，通过复盘和 API 文档，确保了项目的持续改进和 API 的可文档化。

---

## 最终确认
当完成所有 10 个阶段后，你可以向用户提供最终确认，包括：
1. 总结本次执行的主要内容
2. 列出所有生成的文档和代码
3. 询问用户是否对整个执行过程满意
4. 询问用户是否需要进行其他操作

通过这种方式，确保用户对整个执行过程有清晰的了解和控制，提高用户的满意度和参与度。