agent-aide/.aide/task-spec.md

# 任务细则：Aide 工作流体系重构

## 任务目标

对 Aide 工作流体系进行全面重构，包括：
1. Commands 体系重组（拆分 init、合并 prep+exec、新增文档管理）
2. aide flow 功能增强（状态查看、流程图集成）
3. 配置系统完善（自文档化、新增配置项）
4. 项目文档体系建立（面向 LLM 的区块化文档系统）
5. 任务分析阶段增强（复杂度评估、子计划拆分）

## 成功标准

1. **Commands 重组完成**
   - `/aide:setup` 命令实现环境依赖分析、配置、检测、修复功能
   - `/aide:load` 命令实现项目文档按需载入功能
   - `/aide:docs` 命令实现项目文档创建和维护功能
   - `/aide:run` 命令整合原 prep 和 exec 功能，支持流程状态检测和续接

2. **aide flow 增强完成**
   - 支持 `aide flow status` 查看当前任务状态
   - 支持 `aide flow list` 查看所有任务列表
   - 支持 `aide flow show <task_id>` 查看详细状态
   - flow-design 阶段强制 PlantUML 流程图，集成校验和构建

3. **配置系统完善**
   - 配置文件完全自文档化（所有配置项含注释说明）
   - 新增 `.gitignore` 忽略 `.aide` 目录的可配置选项
   - 新增项目文档路径配置项
   - 新增流程图目录路径配置项
   - PlantUML jar 路径配置

4. **项目文档体系建立**
   - 文档结构规范设计完成
   - 区块划分规则制定完成
   - 支持总导览 + 多子区块的文档结构
   - 支持增量更新（无需了解全局即可修改局部）

5. **任务分析增强完成**
   - 复杂度评估指导原则制定
   - 复杂任务自动拆分为子计划
   - 子计划循环执行机制实现

---

## 技术决策

### 1. Commands 命名方案
| 命令 | 功能 | 独立运行 |
|------|------|----------|
| `/aide:setup` | 环境依赖分析、配置、检测、修复 | 是 |
| `/aide:load` | 项目文档按需载入，了解项目脉络 | 否（由 run 调用） |
| `/aide:docs` | 项目文档创建和维护 | 是 |
| `/aide:run` | 任务准备 + 任务执行（合并 prep+exec） | 否 |

### 2. 流程图要求
- **强制要求**：所有任务必须有流程图，无例外
- **目的**：规范化思考，方便用户审阅，早期发现逻辑错误

### 3. PlantUML 依赖处理
- **方式**：本地 java + 本地 jar
- **来源**：复制 `/home/user/env-hub/jar/plantuml.jar` 到 `aide-program/` 目录
- **配置**：jar 路径写入 aide 程序配置

### 4. 任务复杂度判断
- **方式**：LLM 综合判断
- **依据**：详细的指导原则（见附录）

### 5. prep+exec 合并命令
- **命名**：`/aide:run`
- **行为**：启动时检查 flow 状态，根据状态决定新建或续接

---

## 执行步骤

本任务拆分为 **6 个子计划**，按依赖顺序执行：

### 子计划 1：配置系统增强

**目标**：完善 aide 配置系统，为后续功能提供基础支持

**步骤**：
1. 修改 `aide-program/aide/core/config.py`，增加新配置项支持
2. 更新配置文件模板，添加完整注释（自文档化）
3. 新增配置项：
   - `[general]` 节：`gitignore_aide = true/false`
   - `[docs]` 节：`path = "..."`, `block_plan_path = "..."`
   - `[flow]` 节：`diagram_path = "..."`
   - `[plantuml]` 节：`jar_path = "..."`
4. 修改 `aide init` 逻辑，根据 `gitignore_aide` 配置决定是否添加忽略项
5. 复制 plantuml.jar 到 aide-program 目录
6. 更新相关设计文档

**交付物**：
- 更新后的 `config.py`
- 自文档化的配置文件模板
- `aide-program/lib/plantuml.jar`

---

### 子计划 2：aide flow 状态查看功能

**目标**：支持查看流程信息，为 `/aide:run` 续接功能提供依赖

**步骤**：
1. 设计 flow 状态数据存储格式（`.aide/flow-status.json` 增强）
2. 实现 `aide flow status` 子命令：
   - 显示当前任务进度（环节、简述、时间戳、git 提交标识）
3. 实现 `aide flow list` 子命令：
   - 列出所有任务的名称和 task_id
4. 实现 `aide flow show <task_id>` 子命令：
   - 显示指定任务的详细状态历史
5. 更新 skill 文档（aide skill）
6. 更新设计文档

**交付物**：
- flow 子命令增强实现
- 更新后的 skill 文档

---

### 子计划 3：aide flow 流程图集成

**目标**：在 flow-design 阶段集成 PlantUML 校验和构建

**步骤**：
1. 创建 PlantUML 环境检测模块 `aide-program/aide/env/modules/plantuml.py`
2. 实现 PlantUML 语法校验功能
3. 实现 PlantUML 构建功能（生成 PNG）
4. 修改 flow 相关逻辑：
   - `next-step` 在 flow-design 阶段校验流程图目录下的 .puml 文件
   - `next-part impl` 时先校验，通过后批量构建 PNG
   - 校验失败时记录状态并提交 git，返回错误提示
5. 更新设计文档

**交付物**：
- `plantuml.py` 环境模块
- flow 流程图集成逻辑
- 相关设计文档

---

### 子计划 4：项目文档体系设计与实现

**目标**：建立面向 LLM 的区块化项目文档体系

**步骤**：
1. 设计文档结构规范：
   - 总导览文档格式
   - 子区块文档格式
   - 区块划分规则
2. 设计文档创建流程：
   - 目录探索 → 区块划分 → 逐区块深度了解 → 文档生成
3. 设计文档更新流程：
   - 分区块验证 → 差异检测 → 增量更新
4. 创建 `/aide:docs` command 执行文件
5. 更新相关 skill 文档
6. 更新设计文档

**交付物**：
- 文档结构规范文档
- `/aide:docs` command
- 相关 skill 和设计文档

---

### 子计划 5：Commands 重组

**目标**：重新组织 aide-plugin 的 commands

**步骤**：
1. 创建 `/aide:setup` command：
   - 强制触发 env-config skill
   - 专注环境依赖分析、配置、检测、修复
   - 独立运行设计
2. 创建 `/aide:load` command：
   - 项目文档按需载入
   - 初次仅了解项目脉络
   - 支持后续按需深入
3. 重构 `/aide:run` command（合并 prep + exec）：
   - 启动时检查 flow 状态
   - flow 为空或已 finish：启动新 flow（从 task-optimize 开始）
   - flow 未完成：分析进度，按需载入文档，续接任务
   - 强制触发 aide skill
4. 删除或重命名原 init/prep/exec commands
5. 更新 plugin.json
6. 更新设计文档

**交付物**：
- `/aide:setup` command
- `/aide:load` command
- `/aide:docs` command（子计划 4 产出）
- `/aide:run` command
- 更新后的 plugin.json

---

### 子计划 6：任务分析阶段增强

**目标**：支持复杂任务识别和拆分

**步骤**：
1. 制定任务复杂度评估指导原则（见附录）
2. 设计子计划结构：
   - 任务计划总导览格式
   - 子计划细则格式
3. 实现复杂任务拆分逻辑（在 `/aide:run` 的 task-optimize 阶段）
4. 实现子计划循环执行机制：
   - task-optimize → [flow-design → impl → verify → docs] × N → finish
5. 更新 `/aide:run` command
6. 更新设计文档

**交付物**：
- 复杂度评估指导原则文档
- 子计划相关格式规范
- 更新后的 `/aide:run` command

---

## 约束与边界

### 范围内
- aide-plugin 的 commands 和 skills 修改
- aide-program 的功能增强
- 相关设计文档更新

### 范围外
- 现有环境检测模块（python, uv, rust, node 等）的修改
- aide decide 功能的修改
- docs/ 下的教程文档（如自定义斜杠命令指南等）

### 技术约束
- Python >= 3.11
- 使用 uv 管理虚拟环境
- 输出使用 `core/output.py` 格式
- PlantUML 使用本地 java + jar 方式

---

## 附录：任务复杂度评估指导原则

### 一、评估维度

#### 1. 结构维度
- **模块数量**：涉及多少个独立的功能模块或代码区块？
- **文件数量**：预计需要创建或修改多少个文件？
- **依赖关系**：模块之间的依赖关系是否复杂？是否存在循环依赖？

#### 2. 逻辑维度
- **业务逻辑**：是否涉及复杂的业务规则或算法？
- **状态管理**：是否需要管理复杂的状态转换？
- **边界条件**：是否存在大量需要处理的边界情况？

#### 3. 集成维度
- **外部依赖**：是否需要集成外部服务或 API？
- **数据格式**：是否涉及复杂的数据转换或格式处理？
- **兼容性**：是否需要考虑向后兼容或多版本支持？

#### 4. 风险维度
- **技术风险**：是否涉及不熟悉的技术栈或新框架？
- **影响范围**：修改是否会影响现有功能的稳定性？
- **回滚难度**：如果出错，是否容易回滚？

### 二、复杂度等级

| 等级 | 描述 | 特征 | 处理方式 |
|------|------|------|----------|
| **简单** | 单一明确的小任务 | 单文件或少量文件修改，逻辑清晰，无复杂依赖 | 直接执行 |
| **中等** | 涉及多个相关组件 | 2-4 个模块，有一定依赖关系，需要协调修改 | 直接执行，注意顺序 |
| **复杂** | 跨多个子系统的任务 | 5+ 模块，复杂依赖，涉及架构调整 | **必须拆分为子计划** |
| **超大** | 系统性重构或新系统 | 10+ 模块，全面重构，涉及多个子系统 | 拆分为多个独立任务 |

### 三、拆分判断标准

当满足以下任一条件时，**应当拆分为子计划**：

1. **模块标准**：涉及 3 个以上相对独立的功能模块
2. **阶段标准**：任务自然分为多个可独立交付的阶段
3. **风险标准**：存在高风险环节，需要阶段性验证
4. **依赖标准**：存在明确的前后依赖关系，前置任务完成后才能进行后续任务
5. **上下文标准**：单次对话可能无法完成，需要多次对话续接

### 四、拆分原则

1. **独立性**：每个子计划应该有独立的目标和交付物
2. **完整性**：每个子计划完成后应该是可验证的完整状态
3. **顺序性**：子计划之间的依赖关系要明确，执行顺序要清晰
4. **粒度适中**：子计划不宜过大（难以完成）或过小（增加管理开销）

### 五、评估流程

```
1. 阅读任务描述，识别所有涉及的功能点
2. 分析功能点之间的依赖关系
3. 按四个维度评估复杂度
4. 确定复杂度等级
5. 如果是复杂或超大任务：
   a. 识别可独立交付的阶段
   b. 按依赖关系排序
   c. 为每个阶段制定子计划
6. 如果是简单或中等任务：
   a. 直接制定执行计划
```

---

*文档版本：1.0.0*
*生成日期：2025-12-15*
*基于用户决策生成*