From 0bf9f7169f59f09d0b80a9d69cd0dd5588631467 Mon Sep 17 00:00:00 2001 From: "sayurinana(vm)" Date: Sat, 13 Dec 2025 02:30:37 +0800 Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20feat:=20=E6=9B=B4=E6=96=B0=E4=BA=86?= =?UTF-8?q?command=EF=BC=8C=E4=B8=8A=E4=B8=8B=E6=96=87=E7=88=86=E4=BA=86?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- aide-marketplace/aide-plugin/commands/exec.md | 246 +++++++----------- aide-marketplace/aide-plugin/commands/init.md | 84 +++--- aide-marketplace/aide-plugin/commands/prep.md | 227 ++++++++-------- 3 files changed, 252 insertions(+), 305 deletions(-) diff --git a/aide-marketplace/aide-plugin/commands/exec.md b/aide-marketplace/aide-plugin/commands/exec.md index 3b88491..1bafd55 100644 --- a/aide-marketplace/aide-plugin/commands/exec.md +++ b/aide-marketplace/aide-plugin/commands/exec.md @@ -1,251 +1,203 @@ --- -description: 任务执行流程。基于 task-spec.md 执行任务，包含流程设计、迭代实现、验证交付、文档更新和收尾。 +description: 任务执行流程。基于任务细则执行任务，包含流程设计、迭代实现、验证交付、文档更新。 +argument-hint: [任务细则文档路径] --- # Aide 任务执行 -你正在执行 Aide 任务执行流程。本流程基于任务细则（task-spec.md）完成实际的任务实施。 +你正在执行 Aide 任务执行流程。基于任务细则完成实际的任务实施。 -## 流程概览 +## 参数 -``` -流程设计 → 迭代实现 → 验证交付 → 文档更新 → 收尾 -``` - -## 运行特点 - -- **完整闭环**：包含状态记录、git 提交、流程校验 -- **可追溯**：每个步骤都有记录，支持中断恢复 -- **自动化**：状态管理和版本控制通过 aide 程序处理 - -## 前置条件 - -确认存在 `task-spec.md`： -- 存在：读取并理解任务细则 -- 不存在：提示用户先执行 `/aide:prep` 或提供任务细则 +- `$ARGUMENTS`：任务细则文档路径（可选） +- 未传入时使用配置中的默认路径 --- -## 环节 1：流程设计 +## 开始 -### 1.1 启动任务 +### 确定任务细则 -执行命令开始新任务： ```bash -aide flow start flow-design "开始任务: <任务简述>" +# 如果传入了参数 +细则文档 = $ARGUMENTS + +# 如果未传入参数，使用配置默认值 +aide config get task.spec ``` -### 1.2 理解任务细则 +读取任务细则内容。如文档不存在，提示用户先执行 `/aide:prep` 或指定文档路径。 + +### 进入流程设计环节 + +```bash +aide flow next-part flow-design "进入流程设计环节" +``` + +--- + +## 环节 1：流程设计 (flow-design) + +### 理解任务细则 -仔细阅读 `task-spec.md`： - 明确任务目标和成功标准 - 理解执行步骤和依赖关系 - 识别技术决策和约束 -### 1.3 分析项目环境 +### 分析项目环境 -根据任务需要： -- 阅读相关代码文件 -- 了解项目结构和约定 -- 识别需要修改的模块 +根据需要阅读相关代码/文档。 -### 1.4 制定执行计划 +### 制定执行计划 -产出执行计划，包含： - 具体的实现步骤 - 每个步骤的预期产出 -- 步骤间的依赖关系 - 潜在风险和应对方案 > 复杂任务建议使用 sequential-thinking 进行结构化规划 -### 1.5 完成流程设计 +### 创建流程图（如需要） + +在配置指定的流程图目录创建 PlantUML 源文件。 -记录步骤推进： ```bash -aide flow next-step "流程设计完成，计划 N 个实现步骤" +aide flow next-step "流程图设计完成" ``` +> aide flow 会在此环节自动校验 PlantUML 语法 + +### 进入下一环节 + +```bash +aide flow next-part main "流程设计完成，进入实现环节" +``` + +> aide flow 会自动生成 PNG 流程图 + --- -## 环节 2：迭代实现 +## 环节 2：迭代实现 (main) -### 2.1 进入实现环节 +### 按计划执行 + +对于每个实现步骤，完成后记录： ```bash -aide flow next-part impl "开始迭代实现" +aide flow next-step "<完成内容简述>" ``` -### 2.2 按计划执行 +### 处理问题 -对于每个实现步骤： - -1. **执行前**：明确本步骤目标 -2. **执行中**：自由发挥，完成实际编码/修改 -3. **执行后**：记录完成 - ```bash - aide flow next-step "<本步骤完成的内容简述>" - ``` - -### 2.3 处理问题 - -遇到问题时： - -**一般问题（可继续）**： ```bash +# 一般问题（可继续） aide flow issue "<问题描述>" -``` -记录后继续执行，后续解决。 -**严重错误（阻塞）**： -```bash +# 严重错误（需解决） aide flow error "<错误描述>" ``` -必须先解决再继续。处理方式： + +严重错误处理： 1. 尝试自行解决（最多3次） -2. 成功：在 `discuss/` 创建分析文档记录解决过程 +2. 成功：在 `discuss/` 创建分析文档 3. 失败：停止并告知用户 -### 2.4 需要回退时 +### 需要回退时 -发现设计问题需要回退： ```bash -aide flow back-part flow-design "发现 xxx 问题，需要调整设计" +# 回退到上一步 +aide flow back-step "<原因>" + +# 回退到之前环节 +aide flow back-part <环节名> "<原因>" ``` -步骤内小回退： +### 进入下一环节 + ```bash -aide flow back-step "<回退原因>" +aide flow next-part verify "实现完成，进入验证环节" ``` --- -## 环节 3：验证交付 +## 环节 3：验证交付 (verify) -### 3.1 进入验证环节 +### 对照任务细则验证 -```bash -aide flow next-part verify "开始验证交付" -``` - -### 3.2 对照任务细则验证 - -逐项检查 `task-spec.md` 中的成功标准： -- 每个标准是否满足 +- 每个成功标准是否满足 - 每个交付物是否完成 - 功能是否正常工作 -### 3.3 执行测试 +### 执行测试 -根据项目情况： -- 运行已有测试套件 -- 手动测试关键功能 -- 验证边界情况 +根据项目情况运行测试或手动验证。 -### 3.4 记录验证结果 +### 记录结果 ```bash aide flow next-step "验证完成: <验证结论>" ``` -验证失败时： -- 记录失败原因 -- 回退到实现环节修复 -- 修复后重新验证 +验证失败时回退修复： + +```bash +aide flow back-part main "验证失败: <原因>" +``` + +### 进入下一环节 + +```bash +aide flow next-part docs "验证通过，进入文档环节" +``` --- -## 环节 4：文档更新 +## 环节 4：文档更新 (docs) -### 4.1 进入文档环节 +> aide flow 会在进入此环节时提示更新 CHANGELOG -```bash -aide flow next-part docs "开始文档更新" -``` +### 更新相关文档 -### 4.2 更新相关文档 - -根据任务影响更新： - `README.md`（如有用户可见变更） -- `CHANGELOG.md`（记录本次变更） +- `CHANGELOG.md` - 其他相关文档 -### 4.3 CHANGELOG 更新规范 - -在 `CHANGELOG.md` 中： -1. 在 `[Unreleased]` 区块添加本次变更 -2. 使用语义化分类（Added/Changed/Fixed/Removed） -3. 简明描述变更内容 - -### 4.4 记录完成 +### 记录完成 ```bash aide flow next-step "文档更新完成" ``` ---- - -## 环节 5：收尾 - -### 5.1 进入收尾环节 +### 进入下一环节 ```bash -aide flow next-part finish "开始收尾" +aide flow next-part finish "文档更新完成，进入收尾" ``` -### 5.2 清理工作 +> aide flow 会校验 CHANGELOG 是否已更新 + +--- + +## 环节 5：收尾 (finish) + +### 清理工作 - 删除临时文件和调试代码 - 确保代码格式规范 -- 检查是否有遗漏的 TODO +- 检查遗漏的 TODO -### 5.3 最终检查 +### 最终检查 -确认： -- 所有计划步骤已完成 -- 所有测试通过 -- 文档已更新 -- 仓库状态干净 +确认所有计划步骤已完成。 -### 5.4 完成任务 +### 记录完成 ```bash aide flow next-step "任务完成" ``` -### 5.5 向用户汇报 +### 向用户汇报 总结本次任务： - 完成了什么 - 主要变更点 - 遗留问题（如有） -- 后续建议（如有） - ---- - -## 错误恢复机制 - -### ⚠ 警告级别 - -- 记录问题：`aide flow issue "<描述>"` -- 分析是否影响继续 -- 可继续：记录"继续-xxx" -- 需解决：记录"待解决-xxx" - -### ✗ 错误级别 - -- 记录错误：`aide flow error "<描述>"` -- 必须解决后才能继续 -- 尝试自行解决（最多3次） -- 成功：在 `discuss/` 创建分析文档 -- 失败：停止并告知用户 - ---- - -## 注意事项 - -1. **状态同步**：每个步骤变化都要通过 `aide flow` 记录 -2. **原子提交**：aide flow 会自动处理 git add 和 commit -3. **业务自由**：编写业务代码时自由发挥，不受格式约束 -4. **简体中文**：所有输出和记录使用简体中文 -5. **可恢复**：任务中断后可通过状态记录恢复进度 diff --git a/aide-marketplace/aide-plugin/commands/init.md b/aide-marketplace/aide-plugin/commands/init.md index b4710a2..47baa85 100644 --- a/aide-marketplace/aide-plugin/commands/init.md +++ b/aide-marketplace/aide-plugin/commands/init.md @@ -1,5 +1,6 @@ --- description: 项目认知与环境初始化。进入新项目或开始工作前使用，触发对项目的主动认知和环境检测修复。 +argument-hint: [无参数] --- # Aide 初始化 @@ -8,63 +9,78 @@ description: 项目认知与环境初始化。进入新项目或开始工作前 ## 执行步骤 -### 1. 项目认知 +### 1. Aide 运行时环境检测 -**目标**：快速建立对项目的整体理解 +首先确保 aide 程序本身可以正常运行： + +```bash +aide env ensure --runtime +``` + +根据输出处理： +- `✓`：aide 运行时就绪，继续 +- `✗`：按提示修复后重试，无法修复则告知用户 + +### 2. Aide 数据目录初始化 + +```bash +aide init +``` + +此命令会： +- 创建 `.aide/` 目录（如不存在） +- 生成默认配置文件 `.aide/config.toml` +- 检查并更新 `.gitignore` + +### 3. 项目认知 + +快速建立对项目的整体理解： -执行以下操作： 1. 阅读项目根目录的 `README.md`（如存在） 2. 阅读 `CLAUDE.md`（如存在） 3. 浏览项目目录结构，理解核心模块划分 -4. 识别项目类型（前端/后端/全栈/工具库/文档等） -5. 识别主要技术栈和依赖 +4. 识别项目类型和主要技术栈 -**产出**：向用户简要汇报项目概况（3-5句话） +向用户简要汇报项目概况（3-5句话）。 -### 2. 环境检测与修复 +### 4. 项目环境检测 -**目标**：确保开发环境就绪，避免后续业务逻辑被环境问题打扰 - -执行命令： ```bash aide env ensure ``` +此命令会： +- 读取 `.aide/config.toml` 中的环境配置 +- 检测并修复项目开发环境 +- 输出环境状态和配置信息 + 根据输出处理： -- `✓` 开头：环境就绪，继续下一步 -- `⚠` 开头：有警告但可继续，记录并继续 -- `✗` 开头：环境有问题，尝试按提示修复，3次失败则停止并告知用户 +- `✓`：环境就绪，继续 +- `⚠`：有警告但可继续，记录并继续 +- `✗`：按提示修复，3次失败则告知用户 -### 3. Aide 数据目录初始化 +**注意**：aide env 会输出项目配置信息，包括默认的任务文档路径，记住这些信息供后续使用。 -检查 `.aide/` 目录是否存在： -- 不存在：执行 `aide init`（会自动创建目录和默认配置） -- 已存在：跳过 - -检查 `.gitignore` 是否包含 `.aide/`： -- 不包含：添加 `.aide/` 到 `.gitignore` -- 已包含：跳过 - -### 4. 汇报就绪状态 +### 5. 汇报就绪状态 向用户汇报： -1. 项目概况（来自步骤1） -2. 环境状态（来自步骤2） -3. 可用的 Aide 命令提示 -示例汇报： ``` -项目概况：这是一个基于 Rust 的 CLI 工具项目，使用 clap 处理命令行参数。 +项目概况：[来自步骤3的概要] -环境状态：✓ 环境就绪 (rust:1.75, cargo:1.75) +环境状态：✓ 环境就绪 (python:3.12, ...) + +项目配置： +- 任务原文档：task-now.md +- 任务细则：task-spec.md Aide 已就绪，可用命令： -- /aide:prep - 开始任务准备（分析优化任务描述） -- /aide:exec - 开始任务执行（需要先完成 prep） +- /aide:prep [文档路径] - 任务准备 +- /aide:exec [文档路径] - 任务执行 ``` ## 注意事项 -1. **沉没成本小**：如果在初始化过程中发现严重环境问题无法解决，建议用户修复后重开对话 -2. **不执行业务操作**：本命令只做认知和环境准备，不修改任何业务代码 -3. **简体中文**：所有输出使用简体中文 +1. 如果在初始化过程中发现严重环境问题无法解决，建议用户修复后重开对话 +2. 本命令只做认知和环境准备，不修改任何业务代码 +3. 所有输出使用简体中文 diff --git a/aide-marketplace/aide-plugin/commands/prep.md b/aide-marketplace/aide-plugin/commands/prep.md index 712c390..a981ee2 100644 --- a/aide-marketplace/aide-plugin/commands/prep.md +++ b/aide-marketplace/aide-plugin/commands/prep.md @@ -1,168 +1,131 @@ --- -description: 任务准备流程。分析用户任务描述，优化表述，处理待定项，产出可执行的任务细则（task-spec.md）。 +description: 任务准备流程。分析用户任务描述，优化表述，处理待定项，产出可执行的任务细则。 +argument-hint: [任务原文档路径] --- # Aide 任务准备 -你正在执行 Aide 任务准备流程。本流程帮助用户将模糊的任务描述转化为清晰、可执行的任务细则。 +你正在执行 Aide 任务准备流程。将任务描述转化为清晰、可执行的任务细则。 -## 流程概览 +## 参数 -``` -任务分析 → 任务优化 → 待定项处理 → 结果生成 → 用户确认 +- `$ARGUMENTS`：任务原文档路径（可选） +- 未传入时使用配置中的默认路径 + +--- + +## 开始 + +### 确定任务文档 + +```bash +# 如果传入了参数 +任务文档 = $ARGUMENTS + +# 如果未传入参数，使用配置默认值 +aide config get task.source ``` -## 运行特点 +读取任务文档内容。如文档不存在，询问用户提供任务内容或指定文档路径。 -- **轻量化**：不创建工作目录、不记录状态、不 git 提交 -- **用户确认制**：待定项和最终结果都需要用户确认 -- **可返工**：用户不满意可返回重新优化 +### 启动流程追踪 + +```bash +aide flow start task-optimize "开始任务准备: <任务简述>" +``` --- ## 阶段 1：任务分析 -### 1.1 获取任务描述 +### 深度理解任务 -确认任务描述来源： -- 用户已提供任务描述：直接使用 -- 用户指定文件（如 `now-task.md`）：读取文件内容 -- 用户未提供：询问用户任务内容 - -### 1.2 深度分析 - -对任务描述进行全面分析： - -**理解核心目标** - 任务要解决什么问题？ - 最终交付物是什么？ - 成功的标准是什么？ +- 涉及哪些模块/系统？ +- 是否有技术难点？ -**识别复杂度** -- 涉及哪些模块/文件/系统？ -- 是否有多个子目标？ -- 是否存在技术难点？ +### 分析项目环境 -**分析项目环境** -- 任务与项目现有结构的关系 -- 是否需要了解特定代码/文档？ -- 是否有相关历史实现可参考？ +根据需要阅读相关代码/文档，理解任务与项目现有结构的关系。 > 复杂任务（多子目标、多方案对比）建议使用 sequential-thinking 进行结构化分析 -### 1.3 产出分析结论 +### 记录进度 -在心中形成对任务的完整理解，为下一阶段做准备。 +```bash +aide flow next-step "任务分析完成" +``` --- ## 阶段 2：任务优化 -### 2.1 准确性优化 +### 准确性优化 -- 识别任务描述中的**歧义**和**不明确之处** +- 识别**歧义**和**不明确之处** - 识别**隐含假设**和**未说明的前提** -- 明确任务**边界**：哪些在范围内，哪些不在 +- 明确任务**边界** -### 2.2 简洁性优化 +### 简洁性优化 -- 识别**冗余表述**（同一意思重复多次） +- 识别**冗余表述** - 区分**真冗余**与**必要强调** -- 保持简洁但不丢失关键信息 -### 2.3 可执行性优化 +### 可执行性优化 - 将抽象要求转化为**具体步骤** - 确保每个步骤有明确的**输入、输出、验证标准** -- 考虑步骤间的**顺序和依赖关系** - 识别可能的**替代方案** -### 2.4 生成待定项 +### 生成待定项 -对于以下情况，生成待定项： -- 存在**多种可行方案**需要用户选择 -- 描述**有歧义**需要用户澄清 -- 存在**隐含假设**需要用户确认 -- 识别出**可以优化**但需要用户认可的内容 +对于存在多种方案、有歧义、需要用户确认的内容，准备待定项数据。 -待定项数据格式： -```json -{ - "task": "任务简述", - "source": "任务描述来源文件", - "items": [ - { - "id": 1, - "title": "问题标题", - "location": { - "file": "now-task.md", - "start": 5, - "end": 7 - }, - "context": "为什么这是一个需要确认的问题", - "options": [ - { - "value": "option_a", - "label": "选项A描述", - "score": 85, - "pros": ["优点1", "优点2"], - "cons": ["缺点1"] - } - ], - "recommend": "option_a" - } - ] -} +### 记录进度 + +```bash +aide flow next-step "任务优化完成，生成待定项" ``` --- ## 阶段 3：待定项处理 -### 3.1 提交待定项 +### 有待定项时 + +提交待定项数据： -如果有待定项，执行： ```bash aide decide '' ``` -程序会启动 Web 服务并输出访问链接。 +告知用户访问链接进行确认。 -### 3.2 等待用户决策 +用户完成后获取结果： -告知用户： -``` -待定项已生成，请访问以下链接进行确认： -http://localhost:xxxx - -完成后请告诉我，我会读取您的决策结果。 -``` - -### 3.3 获取决策结果 - -用户确认完成后，执行： ```bash aide decide result ``` -读取用户的决策结果，整合到后续的任务细则中。 +### 记录进度 -### 3.4 无待定项的情况 +```bash +aide flow next-step "用户完成待定项确认" +``` -如果分析后没有待定项（任务描述已经足够清晰），直接进入下一阶段。 +### 无待定项时 + +任务描述已足够清晰，直接进入下一阶段。 --- ## 阶段 4：结果生成 -### 4.1 生成任务细则 +### 生成任务细则 -基于： -- 原始任务描述 -- 分析优化结果 -- 用户决策结果（如有） - -产出 `task-spec.md`，包含： +整合原始描述、优化结果、用户决策，产出任务细则： ```markdown # 任务细则 @@ -175,45 +138,61 @@ aide decide result ## 执行步骤 1. [步骤1] - - 输入：xxx - - 输出：xxx - - 验证：xxx 2. [步骤2] - ... +... ## 技术决策 -[记录已确认的技术选型和方案] +[已确认的技术选型] ## 约束与边界 -[任务范围边界、不包含的内容] - -## 风险与假设 -[已识别的风险和前提假设] +[任务范围边界] ``` -### 4.2 用户最终确认 +### 记录进度 -向用户展示 `task-spec.md` 内容，询问确认： - -``` -任务细则已生成，请审阅上述内容。 - -- 如果满意，请回复"确认"，我将保存为 task-spec.md -- 如果需要修改，请说明具体问题，我会进行调整 +```bash +aide flow next-step "生成任务细则，等待用户确认" ``` -### 4.3 处理用户反馈 +### 用户确认 -- **用户确认**：保存 `task-spec.md`，prep 流程结束 -- **用户要求修改**：根据反馈返回相应阶段重新处理 -- **用户否决**：询问具体问题，必要时从分析阶段重来 +向用户展示任务细则，询问确认： +- **确认**：保存到任务细则文档 +- **需修改**：根据反馈调整 + +```bash +aide flow next-step "用户确认任务细则" +``` --- -## 注意事项 +## 完成 -1. **不做假设**：遇到模糊需求主动询问，不要自行假设 -2. **用户主导**：所有重要决策都需要用户确认 -3. **保持精简**：任务细则要清晰可执行，避免冗余 -4. **简体中文**：所有输出使用简体中文 -5. **核心优先**：聚焦任务分析和优化本身，形式问题交给程序处理 +任务准备完成，任务细则已保存。 + +提示用户： +``` +任务细则已保存到 task-spec.md + +可执行 /aide:exec 开始任务执行 +``` + +--- + +## 处理问题 + +遇到问题时： + +```bash +# 一般问题 +aide flow issue "<问题描述>" + +# 严重错误 +aide flow error "<错误描述>" +``` + +需要回退时： + +```bash +aide flow back-step "<原因>" +```