# 任务细则：Aide 工具 Git 分支管理和任务细则确认功能

> 生成时间：2025-12-17
> 任务来源：task-now.md
> 复杂度评估：**复杂任务**（涉及多模块修改，建议拆分为子计划）

---

## 任务目标

为 Aide 工作流工具添加两项核心功能：

1. **Git 分支管理**：在任务执行期间自动管理 Git 分支，保持主分支干净，同时保留任务执行细节
2. **任务细则确认机制**：强化任务准备阶段的确认流程，确保关键节点经用户确认

---

## 用户决策结果

| 决策项 | 选择 | 关键修改点 |
|--------|------|------------|
| 分支命名规则 | `aide/NNN` | 三位数递增编号，非 task_id |
| 分支概况文档 | 双格式 | JSON（程序用）+ MD（人阅读） |
| 合并冲突处理 | 安全合并 | 检测原分支变更，必要时用临时分支 |
| 任务中断恢复 | 智能判断 | LLM 判断细则符合度，aide flow 自动清理 |
| 细则确认机制 | 分场景 | 待定项用 aide decide，细则用 AskUserQuestion |
| 细则存储位置 | 现有配置 | `task.spec = "task-spec.md"` |

---

## 子计划拆分

本任务拆分为 **3 个子计划**：

### 子计划 1：Git 分支管理核心功能

**目标**：实现 aide flow 的 Git 分支自动管理

**涉及文件**：
- `aide-program/aide/flow/git.py` - 扩展 Git 操作方法
- `aide-program/aide/flow/branch.py` - 新增分支管理模块
- `aide-program/aide/flow/tracker.py` - 集成分支管理逻辑
- `aide-program/aide/flow/types.py` - 可能需要扩展数据结构

**具体功能**：

#### 1.1 GitIntegration 扩展

新增方法：
- `get_current_branch()` - 获取当前分支名
- `is_clean()` - 检查工作目录是否干净
- `has_commits()` - 检查是否有提交历史
- `create_branch(name)` - 创建分支
- `checkout(branch)` - 切换分支
- `has_commits_since(commit, branch)` - 检查分支自某提交后是否有新提交
- `reset_soft(commit)` - 软重置到指定提交
- `merge_squash(branch)` - squash 合并

#### 1.2 分支管理模块 (branch.py)

**BranchManager 类**：
- `get_next_branch_number()` - 获取下一个分支编号
- `create_task_branch()` - 创建任务分支
- `load_branches()` - 加载分支概况
- `save_branches()` - 保存分支概况（同时生成 JSON 和 MD）
- `record_branch_start()` - 记录分支开始信息
- `record_branch_finish()` - 记录分支结束信息

**分支概况文档格式**：

`.aide/branches.json`:
```json
{
  "next_number": 2,
  "branches": [
    {
      "number": 1,
      "branch_name": "aide/001",
      "source_branch": "master",
      "start_commit": "abc1234",
      "end_commit": "def5678",
      "task_id": "2025-12-17T10-30-00",
      "task_summary": "实现用户登录功能",
      "started_at": "2025-12-17T10:30:00+08:00",
      "finished_at": "2025-12-17T12:00:00+08:00",
      "status": "finished"
    }
  ]
}
```

`.aide/branches.md`:
```markdown
# Git 分支概况

## aide/001
- **任务**: 实现用户登录功能
- **源分支**: master
- **起始提交**: abc1234
- **结束提交**: def5678
- **状态**: finished
- **时间**: 2025-12-17 10:30 ~ 12:00
```

#### 1.3 FlowTracker 集成

**start() 修改**：
1. 检查 git 状态，不干净则创建保存提交
2. 如果无提交历史，创建初始提交
3. 记录起始提交和源分支
4. 调用 BranchManager 创建任务分支
5. 切换到任务分支

**next_part() 修改**（进入 finish 时）：
1. 调用 BranchManager 处理分支合并
2. 检查源分支是否有新提交
3. 执行安全合并策略
4. 更新分支概况文档

#### 1.4 安全合并策略

```
源分支自起始提交后无新提交:
  → 切回源分支
  → git reset --soft <起始提交>
  → git add .
  → git commit -m "<任务压缩提交>"

源分支自起始提交后有新提交:
  → 从起始提交检出临时分支 aide/NNN-merge
  → 在临时分支完成合并
  → 警告用户: "源分支有新提交，已在临时分支完成合并，请手动处理"
  → 保留任务分支和临时分支供用户决策
```

**验证标准**：
- [ ] aide flow start 能正确创建任务分支
- [ ] aide flow 操作在任务分支上执行
- [ ] 进入 finish 时能正确执行安全合并
- [ ] 分支概况文档正确生成（JSON + MD）
- [ ] 源分支有新提交时正确警告用户

---

### 子计划 2：任务中断恢复和细则确认机制

**目标**：更新 command/run 流程，实现智能续接和确认机制

**涉及文件**：
- `aide-marketplace/aide-plugin/commands/run.md` - 更新流程定义

**具体修改**：

#### 2.1 续接流程更新

在"续接流程"部分，增加智能判断逻辑：

```markdown
## 续接流程

当检测到未完成的任务时：

### 1. 智能续接判断

1. 检查任务细则文档是否存在
   - 路径: `aide config get task.spec`

2. 如果细则文档不存在:
   - 旧状态已无效，需要 start 新任务
   - 提示用户确认是否继续

3. 如果细则文档存在:
   - 阅读细则文档内容
   - 判断上次未完成任务的名称和步骤是否符合细则含义
   - 符合 → 接续之前的状态继续执行
   - 不符合 → 旧状态已无效，需要 start 新任务

4. 如果判断为应继续，但 git 状态不干净:
   - aide flow 会自动执行 git add . 并创建清理提交
   - 这是预期行为，无需手动处理
```

#### 2.2 确认机制更新

在"任务准备"阶段，明确确认要求：

```markdown
#### 1.7 待定项处理

**必须执行**，无论是否有待定项：

1. 如果有待定项:
   ```bash
   aide decide submit .aide/pending-items.json
   ```
   - 等待用户完成决策
   ```bash
   aide decide result
   ```

2. 如果无待定项:
   - 向用户报告"无需确认的待定项"
   - 继续下一步

#### 1.8 生成任务细则

**必须执行**：

1. 根据分析结果生成任务细则文档
2. 保存到配置的路径:
   ```bash
   aide config get task.spec
   ```
3. **强制确认点**:
   - 向用户展示细则摘要
   - 使用 AskUserQuestion 询问用户是否确认
   - 等待用户明确答复后才能继续
   - 如用户有修改意见，更新细则后重新确认

```bash
aide flow next-step "任务细则已确认"
```
```

**验证标准**：
- [ ] command/run 包含智能续接判断逻辑
- [ ] 待定项处理有明确的强制要求
- [ ] 细则保存后有强制确认点
- [ ] 确认机制区分 aide decide 和 AskUserQuestion

---

### 子计划 3：文档和 Skill 更新

**目标**：更新相关文档和 skill，说明新功能和副作用

**涉及文件**：
- `aide-marketplace/aide-plugin/skills/aide.md` - 更新 aide 命令说明
- `aide-program/docs/commands/flow.md` - 更新 flow 命令文档
- `CHANGELOG.md` - 记录变更

**具体修改**：

#### 3.1 aide skill 更新

在 `aide flow` 部分增加说明：

```markdown
### Git 分支管理（自动）

aide flow 命令会自动管理 Git 分支：

**任务开始时**:
- 检查 git 状态，必要时自动提交保存
- 创建任务分支 `aide/NNN`（递增编号）
- 自动切换到任务分支

**任务结束时**:
- 将任务分支合并回源分支
- 使用软重置生成压缩提交
- 如果源分支有新提交，会创建临时分支并警告

**分支概况文档**:
- `.aide/branches.json` - 程序读取
- `.aide/branches.md` - 人工查阅
```

#### 3.2 flow 命令文档更新

更新 `aide-program/docs/commands/flow.md`，添加分支管理章节。

#### 3.3 CHANGELOG 更新

```markdown
## [Unreleased]

### Added
- aide flow 自动 Git 分支管理
  - 任务开始时自动创建 aide/NNN 分支
  - 任务结束时自动合并并压缩提交
  - 分支概况文档（JSON + MD 双格式）
  - 安全合并策略（检测源分支变更）

### Changed
- command/run 流程更新
  - 智能续接判断逻辑
  - 待定项强制确认
  - 细则文档强制确认
```

**验证标准**：
- [ ] aide skill 包含分支管理说明
- [ ] flow 命令文档更新
- [ ] CHANGELOG 记录变更

---

## 执行顺序

```
子计划 1 (Git 分支管理) → 子计划 2 (流程更新) → 子计划 3 (文档更新)
```

**依赖关系**：
- 子计划 2 依赖子计划 1 完成（需要知道 aide flow 的新行为）
- 子计划 3 依赖子计划 1、2 完成（需要文档化所有变更）

---

## 风险识别

| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| Git 操作失败 | 可能导致工作丢失 | 所有 git 操作前检查状态，失败时中止并警告 |
| 分支编号冲突 | 编号不唯一 | 使用文件锁保护编号分配 |
| 合并冲突 | 无法自动完成 | 使用安全合并策略，创建临时分支让用户处理 |
| 兼容性问题 | 旧状态文件无法识别 | 增加版本字段，向后兼容 |

---

## 约束条件

- 尽可能少改动 commands & skills
- 核心逻辑封装在 aide flow 中
- 遵循现有代码风格和架构
- 保持向后兼容

---

## 成功标准

1. ✅ aide flow start 自动创建任务分支
2. ✅ aide flow 操作记录在任务分支
3. ✅ finish 时安全合并到源分支
4. ✅ 分支概况文档正确维护
5. ✅ command/run 包含智能续接逻辑
6. ✅ 待定项和细则有强制确认点
7. ✅ 相关文档和 skill 更新完成