311 lines
10 KiB
Markdown
311 lines
10 KiB
Markdown
# 任务细则：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*
|
||
*基于用户决策生成*
|