sayurinana/agent-aide
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
46435c031cb933b04ddb4a01ee761b97f6016abf
agent-aide/.aide/task-spec.md

10 KiB
Raw Blame History

任务细则：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 基于用户决策生成