[aide] task-optimize: 整合用户决策，生成任务细则

2025-12-15 17:45:21 +08:00
parent 5cf5a5810c
commit 244e8c8f05
3 changed files with 320 additions and 2 deletions
--- a/.aide/flow-status.json
+++ b/.aide/flow-status.json
@@ -1,7 +1,7 @@
 {
  "task_id": "2025-12-15T17-28-53",
  "current_phase": "task-optimize",
-  "current_step": 3,
+  "current_step": 4,
  "started_at": "2025-12-15T17:28:53+08:00",
  "history": [
    {
@@ -26,6 +26,14 @@
      "step": 3,
      "summary": "任务优化完成，生成待定项",
      "git_commit": "2bc86b1d893d57e24083775cd51437de6adc46bf"
+    },
+    {
+      "timestamp": "2025-12-15T17:43:38+08:00",
+      "action": "next-step",
+      "phase": "task-optimize",
+      "step": 4,
+      "summary": "用户完成待定项确认",
+      "git_commit": "5cf5a5810c4bd45f4aa18758e1a1e4475e03c175"
    }
  ]
 }
--- a/.aide/flow-status.lock
+++ b/.aide/flow-status.lock
@@ -1 +1 @@
-105261
+106310
--- a/.aide/task-spec.md
+++ b/.aide/task-spec.md
@@ -0,0 +1,310 @@
+# 任务细则：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*
+*基于用户决策生成*