207 lines
6.8 KiB
Markdown
207 lines
6.8 KiB
Markdown
# re-03 意见调整完成报告
|
||
|
||
## 一、调整概述
|
||
|
||
根据 `reply/re-03.md` 中提出的意见，已完成对 commands 和 SKILL.md 的调整。
|
||
|
||
---
|
||
|
||
## 二、调整内容详情
|
||
|
||
### 2.1 init 命令执行顺序优化
|
||
|
||
**问题**：原设计中先执行 `aide env ensure` 再执行 `aide init`，但 env 检查需要配置文件，而配置文件在 init 时创建，存在逻辑矛盾。
|
||
|
||
**解决方案**：拆分 env 检查为两个阶段：
|
||
|
||
1. **aide env ensure --runtime**
|
||
- 仅检查 aide 程序自身运行环境
|
||
- 不依赖项目配置文件
|
||
- 确保 Python 等基础环境可用
|
||
|
||
2. **aide init**
|
||
- 创建 `.aide/` 目录
|
||
- 生成默认配置文件
|
||
- 更新 `.gitignore`
|
||
|
||
3. **aide env ensure**
|
||
- 读取项目配置文件
|
||
- 检查项目开发环境
|
||
- 输出项目配置信息
|
||
|
||
**调整文件**：
|
||
- `aide-marketplace/aide-plugin/commands/init.md`
|
||
- `aide-marketplace/aide-plugin/skills/aide/SKILL.md`
|
||
- `aide-requirements.md`
|
||
|
||
---
|
||
|
||
### 2.2 prep 和 exec 流程指导优化
|
||
|
||
**问题**：prep 和 exec 命令中主动向 LLM 提示 git 操作、状态记录等内容，但这些已经被 `aide flow` 封装，LLM 不应该关注这些自动化操作。
|
||
|
||
**解决方案**：
|
||
|
||
1. **移除主动提示**：不再在 commands 中提示 LLM 关注 git 操作和状态记录
|
||
2. **添加注意事项**：在 prep.md 和 exec.md 末尾添加注意事项，明确说明：
|
||
- 不要主动提及 git 操作
|
||
- 不要主动提及状态记录
|
||
- 专注于核心工作（prep 专注任务分析优化，exec 专注任务实现）
|
||
|
||
**调整文件**：
|
||
- `aide-marketplace/aide-plugin/commands/prep.md`
|
||
- `aide-marketplace/aide-plugin/commands/exec.md`
|
||
|
||
---
|
||
|
||
### 2.3 prep 流程追踪启动时机调整
|
||
|
||
**问题**：原设计中 prep 在确定任务文档后才启动流程追踪，但应该在最开始就执行 `aide flow`。
|
||
|
||
**解决方案**：
|
||
|
||
1. **调整执行顺序**：
|
||
- 先执行 `aide flow start task-optimize "开始任务准备: <任务简述>"`
|
||
- 再确定任务文档路径
|
||
- 然后读取任务文档内容
|
||
|
||
2. **更新环节名称**：
|
||
- prep 阶段使用 `task-optimize` 环节
|
||
- exec 阶段使用 `flow-design` / `impl` / `verify` / `docs` / `finish` 环节
|
||
|
||
**调整文件**：
|
||
- `aide-marketplace/aide-plugin/commands/prep.md`
|
||
- `aide-marketplace/aide-plugin/skills/aide/SKILL.md`
|
||
- `aide-requirements.md`
|
||
|
||
---
|
||
|
||
### 2.4 参数传递支持
|
||
|
||
**问题**：prep 和 exec 命令应该支持传入文档路径参数，未传入时使用配置文件中的默认路径。
|
||
|
||
**解决方案**：
|
||
|
||
1. **prep 命令参数**：
|
||
- 参数：`[任务原文档路径]`（可选）
|
||
- 未传入时：使用 `aide config get task.source` 获取默认路径（通常为 task-now.md）
|
||
|
||
2. **exec 命令参数**：
|
||
- 参数：`[任务细则文档路径]`（可选）
|
||
- 未传入时：使用 `aide config get task.spec` 获取默认路径（通常为 task-spec.md）
|
||
|
||
**调整文件**：
|
||
- `aide-marketplace/aide-plugin/commands/prep.md`
|
||
- `aide-marketplace/aide-plugin/commands/exec.md`
|
||
- `aide-requirements.md`
|
||
|
||
---
|
||
|
||
## 三、文件修改清单
|
||
|
||
### 3.1 Commands 文件
|
||
|
||
| 文件 | 主要修改 |
|
||
|------|---------|
|
||
| `init.md` | 1. 添加 `--runtime` 参数说明<br>2. 调整执行顺序为：runtime检查 → init → 项目认知 → 项目环境检查 |
|
||
| `prep.md` | 1. 调整流程追踪启动时机到最开始<br>2. 添加参数说明<br>3. 添加注意事项（不主动提及git和状态记录） |
|
||
| `exec.md` | 1. 添加参数说明<br>2. 添加注意事项（不主动提及git和状态记录） |
|
||
|
||
### 3.2 SKILL.md 文件
|
||
|
||
| 修改项 | 内容 |
|
||
|-------|------|
|
||
| aide env ensure | 添加 `--runtime` 参数说明 |
|
||
| aide flow start | 更新环节名称列表，添加 `task-optimize` |
|
||
| 环节名称列表 | 添加使用场景列，区分 prep 和 exec 阶段 |
|
||
| 常见用法示例 | 拆分为 prep 阶段示例和 exec 阶段示例 |
|
||
|
||
### 3.3 aide-requirements.md 文件
|
||
|
||
| 章节 | 修改内容 |
|
||
|------|---------|
|
||
| 4.1 /aide:init | 添加执行顺序说明，明确三步流程 |
|
||
| 4.2 /aide:prep | 添加参数说明，更新职责列表，添加流程管理说明 |
|
||
| 4.3 /aide:exec | 添加参数说明，明确各环节名称，添加运行特点说明 |
|
||
| 5.1 aide flow | 更新环节名称列表，添加使用场景列 |
|
||
| 5.3 aide env | 添加 `--runtime` 参数说明 |
|
||
|
||
---
|
||
|
||
## 四、设计改进总结
|
||
|
||
### 4.1 解决的核心问题
|
||
|
||
1. **环境检查依赖问题**：通过 `--runtime` 参数解决了配置文件依赖的循环问题
|
||
2. **信息污染问题**：明确 LLM 不需要关注自动化操作，专注核心业务
|
||
3. **流程完整性**：prep 阶段从一开始就启动流程追踪，保证完整性
|
||
4. **灵活性提升**：支持参数传递，同时保持默认配置的便利性
|
||
|
||
### 4.2 设计原则体现
|
||
|
||
1. **确定性封装**：git 操作和状态记录完全由程序处理
|
||
2. **渐进式披露**：LLM 只看到必要的信息，不被实现细节干扰
|
||
3. **关注点分离**：Commands 专注流程指导，Skills 专注工具说明
|
||
|
||
---
|
||
|
||
## 五、后续建议
|
||
|
||
### 5.1 需要在程序实现中注意的点
|
||
|
||
1. **aide env ensure --runtime**
|
||
- 必须不依赖任何配置文件
|
||
- 只检查 Python、pip/uv 等基础环境
|
||
- 失败时给出明确的修复建议
|
||
|
||
2. **aide flow 环节校验**
|
||
- 需要区分 prep 和 exec 阶段的环节
|
||
- task-optimize 只能在 prep 阶段使用
|
||
- flow-design/impl/verify/docs/finish 只能在 exec 阶段使用
|
||
|
||
3. **配置文件默认值**
|
||
- task.source 默认为 "task-now.md"
|
||
- task.spec 默认为 "task-spec.md"
|
||
- 这些默认值应该在 aide init 时写入配置文件
|
||
|
||
### 5.2 文档完整性检查
|
||
|
||
所有调整已完成，文档之间保持一致：
|
||
- ✅ Commands 与 SKILL.md 一致
|
||
- ✅ Commands 与 aide-requirements.md 一致
|
||
- ✅ SKILL.md 与 aide-requirements.md 一致
|
||
|
||
---
|
||
|
||
## 六、验证要点
|
||
|
||
在实际使用时，应验证以下场景：
|
||
|
||
1. **init 流程**：
|
||
- 在没有 Python 的环境下，`aide env ensure --runtime` 应该报错
|
||
- 在没有配置文件的情况下，`aide init` 应该成功创建
|
||
- 创建配置文件后，`aide env ensure` 应该能读取配置
|
||
|
||
2. **prep 流程**：
|
||
- 不传参数时，应该使用配置中的默认路径
|
||
- 传入参数时，应该使用指定路径
|
||
- 整个过程不应该有 git 操作的提示
|
||
|
||
3. **exec 流程**：
|
||
- 环节跳转应该符合预期流程
|
||
- flow-design 环节应该检查 PlantUML 语法
|
||
- docs 环节应该检查 CHANGELOG 更新
|
||
|
||
---
|
||
|
||
## 七、总结
|
||
|
||
本次调整完全响应了 re-03 中提出的所有意见：
|
||
|
||
1. ✅ 解决了 init 命令的执行顺序问题
|
||
2. ✅ 移除了 prep 和 exec 中对 git 操作的主动提示
|
||
3. ✅ 调整了 prep 的流程追踪启动时机
|
||
4. ✅ 添加了参数传递支持
|
||
|
||
所有修改都遵循了 aide 系统的核心设计原则，保持了文档的一致性和完整性。
|