sayurinana/agent-aide
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[aide] finish: 清理遗留的任务计划文件

Browse Source
This commit is contained in:
sayurinana(vm)
2025-12-19 04:00:47 +08:00
parent 4cf9fc7a60
commit bd5719febb
7 changed files with 0 additions and 876 deletions
Download Patch File Download Diff File Expand all files Collapse all files

78
.aide/task-plans/guide.md
View File

@@ -1,78 +0,0 @@
# 任务计划总导览
## 任务简述
对 Aide 工作流体系进行多项调整：基础配置修改、面向用户的文档系统（3个命令）、返工流程优化。
## 用户决策记录
| # | 待定项 | 选择 | 备注 |
|---|--------|------|------|
| 1 | 命令拆分方案 | 3个命令 | `/aide:readme` + `/aide:user-docs` + `/aide:user-graph` |
| 2 | 返工确认机制 | 完整 key 确认 | `aide flow back-confirm --key xxx` |
| 3 | 配置项命名 | user_docs 命名空间 | `user_docs.*` |
| 4 | README 已存在处理 | 直接覆盖 | 不需备份，git 已提供版本控制 |
## 子计划列表
| # | 名称 | 状态 | 细则文档 | 说明 |
|---|------|------|----------|------|
| 1 | 基础配置修改 | **completed** | spec-01.md | gitignore_aide 默认值、aide init 任意目录 |
| 2 | README skill 模板集 | **completed** | spec-02.md | 创建 readme-templates skill |
| 3 | README 命令实现 | **completed** | spec-03.md | /aide:readme 命令 |
| 4 | 用户文档命令实现 | **completed** | spec-04.md | /aide:user-docs 命令 |
| 5 | 用户流程图命令实现 | **completed** | spec-05.md | /aide:user-graph 命令 |
| 6 | 返工流程优化 | **completed** | spec-06.md | rework skill + 程序修改 |
## 执行顺序
```
1 (基础配置) ─────────────────────────────────────┐
│
2 (README skill) ──→ 3 (readme 命令) ─────────────┼──→ 完成
│ │
↓ │
4 (user-docs 命令) │
│ │
↓ │
5 (user-graph 命令) ─────────┤
│
6 (返工优化) ─────────────────────────────────────┘
```
**依赖说明**：
- 子计划 1、2、6 可并行执行（无相互依赖）
- 子计划 3 依赖子计划 2（需要 skill 模板）
- 子计划 4 依赖子计划 3（基于 readme 命令扩展）
- 子计划 5 依赖子计划 4（流程图与用户文档关联）
## 涉及模块
| 模块 | 路径 | 涉及子计划 |
|------|------|-----------|
| aide-program | `aide-program/aide/` | 1, 3, 4, 5, 6 |
| commands | `aide-marketplace/aide-plugin/commands/` | 3, 4, 5, 6 |
| skills | `aide-marketplace/aide-plugin/skills/` | 2, 6 |
## 配置项规划
```toml
[user_docs]
# README 文件路径
readme_path = "README.md"
# 用户文档目录
docs_path = "docs"
# README 编写规范文件
rules_path = "make-readme-rules.md"
# 用户流程图目录
graph_path = "docs/graph-guide"
```
## 备注
- 这是一个超大型任务，预计需要多个对话周期完成
- 子计划 5（用户流程图）复杂度最高，可能需要进一步细分
- 建议每完成一个子计划后进行 confirm，确保方向正确

53
.aide/task-plans/spec-01.md
View File

@@ -1,53 +0,0 @@
# 子计划 1：基础配置修改
## 目标
完成两项基础配置修改：
1. 将 `gitignore_aide` 默认值改为 `false`
2. 使 `aide init` 支持在任意目录执行原地初始化
## 具体步骤
### 1.1 修改 gitignore_aide 默认值
**位置**：`aide-program/aide/` 中的配置相关模块
**操作**：
1. 找到 `gitignore_aide` 配置项的默认值定义
2. 将默认值从 `true` 改为 `false`
3. 更新相关文档说明
### 1.2 修改 aide init 行为
**当前行为**：可能限制只能在项目根目录执行
**目标行为**：
- 像 `git init` 一样可以在任意目录执行
- 即使当前目录是已有 `.aide` 管理的子目录，也能执行原地初始化
- 在当前目录创建新的 `.aide/` 目录和配置
**位置**：`aide-program/aide/` 中的 init 相关模块
**操作**：
1. 分析当前 `aide init` 的实现逻辑
2. 移除或修改目录检查限制
3. 确保在任意目录都能创建 `.aide/` 目录
4. 测试验证
## 验证标准
- [ ] `aide init` 后项目的 `.gitignore` 不自动添加 `.aide/` 条目
- [ ] 在任意目录执行 `aide init` 能成功创建 `.aide/` 目录
- [ ] 在已有 `.aide` 的项目子目录中执行 `aide init` 能成功创建新的 `.aide/`
- [ ] 不影响已有的 aide 功能
## 依赖
- 前置：无
- 后续：无（独立任务）
## 风险评估
- **风险等级**：低
- **潜在影响**：已有使用默认配置的项目可能需要手动调整
- **缓解措施**：在 CHANGELOG 中明确说明变更

102
.aide/task-plans/spec-02.md
View File

@@ -1,102 +0,0 @@
# 子计划 2：README skill 模板集
## 目标
创建 `readme-templates` skill，包含多种 README 模板和模块化内容规范板块，供 `/aide:readme` 命令使用。
## 具体步骤
### 2.1 设计模板体系
**模板类型**（按项目类型）：
| 模板 | 文件名 | 适用场景 |
|------|--------|----------|
| 微型项目 | `minimal.md` | < 500 行代码的小工具 |
| 库/工具 | `library.md` | npm/cargo/pip 等库项目 |
| 应用程序 | `application.md` | CLI/GUI/Web 应用 |
| 纯文档 | `documentation.md` | 文档、教程、材料类项目 |
| 多项目仓库 | `monorepo.md` | 包含多个子项目的仓库 |
**可选模块**（可自由组合）：
| 模块 | 文件名 | 说明 |
|------|--------|------|
| 快速开始 | `module-quickstart.md` | 5分钟上手指南 |
| 安装指南 | `module-installation.md` | 详细安装步骤 |
| 使用示例 | `module-examples.md` | 代码示例和用例 |
| API 文档 | `module-api.md` | 接口说明 |
| 配置说明 | `module-configuration.md` | 配置项详解 |
| 架构概述 | `module-architecture.md` | 系统架构说明 |
| 贡献指南 | `module-contributing.md` | 如何贡献代码 |
| 变更日志 | `module-changelog.md` | 版本历史 |
| 许可证 | `module-license.md` | 许可证说明 |
| FAQ | `module-faq.md` | 常见问题 |
### 2.2 创建 skill 目录结构
```
aide-marketplace/aide-plugin/skills/readme-templates/
├── SKILL.md # 技能说明和使用指南
├── templates/ # 完整模板
│ ├── minimal.md
│ ├── library.md
│ ├── application.md
│ ├── documentation.md
│ └── monorepo.md
└── modules/ # 可选模块
├── module-quickstart.md
├── module-installation.md
├── module-examples.md
├── module-api.md
├── module-configuration.md
├── module-architecture.md
├── module-contributing.md
├── module-changelog.md
├── module-license.md
└── module-faq.md
```
### 2.3 编写 SKILL.md
内容包括：
- skill 用途说明
- 模板选择指南（根据项目类型推荐）
- 模块组合建议（不同场景的推荐组合）
- 各模板和模块的简介
- 使用示例
### 2.4 编写各模板文件
每个模板文件应包含：
- 模板说明（作为注释）
- 完整的 README 结构
- 占位符标记（供 LLM 填充）
- 可选部分标注
### 2.5 编写各模块文件
每个模块文件应包含：
- 模块说明
- 标准结构
- 最佳实践提示
- 示例内容
## 验证标准
- [ ] SKILL.md 内容完整，指导清晰
- [ ] 5 个完整模板覆盖主要项目类型
- [ ] 10 个可选模块覆盖常见需求
- [ ] 模板和模块风格统一
- [ ] 占位符标记清晰，便于 LLM 填充
## 依赖
- 前置：无
- 后续：子计划 3（README 命令实现）依赖本计划
## 风险评估
- **风险等级**：低
- **潜在影响**：模板质量直接影响生成文档的质量
- **缓解措施**：参考优秀开源项目的 README 编写

108
.aide/task-plans/spec-03.md
View File

@@ -1,108 +0,0 @@
# 子计划 3：README 命令实现
## 目标
创建 `/aide:readme` 命令，实现 README 编写规范管理和 README 文件生成功能。
## 具体步骤
### 3.1 添加配置项
**位置**：`aide-program/aide/` 配置模块
**新增配置项**：
```toml
[user_docs]
# README 文件路径（相对于项目根目录）
readme_path = "README.md"
# README 编写规范文件路径
rules_path = "make-readme-rules.md"
```
**实现**：
1. 在 config.toml 模板中添加默认配置
2. 实现 `aide config get user_docs.readme_path` 等命令支持
3. 更新配置文档注释
### 3.2 创建命令文件
**位置**：`aide-marketplace/aide-plugin/commands/readme.md`
**命令流程**：
```
开始
│
├─ 检查 make-readme-rules.md 是否存在
│ │
│ ├─ 不存在 → 进入规范引导流程
│ │
│ └─ 存在 → 进入 README 生成流程
│
└─ 结束
```
### 3.3 规范引导流程
当 `make-readme-rules.md` 不存在时：
1. **提示用户**：
- 建议先完成 `docs + load`（面向 LLM 的项目文档）
- 询问是否已完成或确定不需要
2. **建议独立对话**：
- 提示用户规范制定是一个重要任务
- 建议将本次对话专注于规范制定
- 完成后使用 `/exit` 退出
3. **触发 readme-templates skill**：
- 加载模板和模块信息
- 向用户介绍可用模板
- 提供可选模块列表
4. **引导用户选择**：
- 根据项目类型推荐模板
- 根据项目文档分析提供建议
- 允许用户自由组合模块
5. **生成规范文件**：
- 将用户选择写入 `make-readme-rules.md`
- 包含：选择的模板、启用的模块、自定义要求
### 3.4 README 生成流程
当 `make-readme-rules.md` 存在时：
1. **读取规范文件**
2. **检查 README.md 是否存在**：
- 存在 → 直接覆盖（用户决策：无需备份，git 提供版本控制）
3. **触发 readme-templates skill**
4. **根据规范和项目文档生成 README**
5. **写入 README.md**
### 3.5 与项目文档的集成
- 读取 `.aide/project-docs/` 下的项目文档
- 分析项目类型、技术栈、模块结构
- 为用户提供基于项目实际情况的建议
## 验证标准
- [ ] `aide config get user_docs.readme_path` 正常工作
- [ ] 规范文件不存在时正确进入引导流程
- [ ] 规范文件存在时正确生成 README
- [ ] README 存在时直接覆盖
- [ ] 与项目文档的集成正常工作
## 依赖
- 前置：子计划 2（readme-templates skill）
- 后续：子计划 4（user-docs 命令）
## 风险评估
- **风险等级**：中
- **潜在影响**：规范引导流程的用户体验
- **缓解措施**：提供清晰的提示和合理的默认选项

124
.aide/task-plans/spec-04.md
View File

@@ -1,124 +0,0 @@
# 子计划 4：用户文档命令实现
## 目标
创建 `/aide:user-docs` 命令，实现 docs 目录下面向用户的详细文档生成功能。
## 具体步骤
### 4.1 添加配置项
**位置**：`aide-program/aide/` 配置模块
**新增配置项**：
```toml
[user_docs]
# 用户文档目录路径（相对于项目根目录）
docs_path = "docs"
```
### 4.2 创建命令文件
**位置**：`aide-marketplace/aide-plugin/commands/user-docs.md`
**命令流程**：
```
开始
│
├─ 检查 make-readme-rules.md 是否存在
│ │
│ ├─ 不存在 → 提示先执行 /aide:readme
│ │
│ └─ 存在 → 继续
│
├─ 检查项目文档是否存在（.aide/project-docs/）
│ │
│ ├─ 不存在 → 建议先执行 /aide:docs + /aide:load
│ │
│ └─ 存在 → 继续
│
├─ 分析项目类型和结构
│
├─ 确定文档结构
│
├─ 生成/更新 docs 目录下的文档
│
└─ 结束
```
### 4.3 文档结构设计
根据项目类型，docs 目录应包含不同的文档：
**纯文档/材料类项目**：
```
docs/
├── overview.md # 内容概述
├── navigation.md # 导航指南
└── topics/ # 主题分类
├── topic-1.md
└── topic-2.md
```
**单体程序项目**：
```
docs/
├── getting-started.md # 快速开始
├── installation.md # 安装指南
├── usage.md # 使用说明
├── configuration.md # 配置说明
├── api/ # API 文档
│ └── ...
└── guides/ # 使用指南
└── ...
```
**多项目仓库**：
```
docs/
├── overview.md # 仓库概述
├── projects/ # 各项目文档
│ ├── project-a/
│ │ ├── README.md
│ │ └── ...
│ └── project-b/
│ ├── README.md
│ └── ...
└── shared/ # 共享文档
└── ...
```
### 4.4 与 README 的关联
- 读取 `make-readme-rules.md` 了解用户偏好
- docs 目录下的文档与 README 中的链接保持一致
- 支持在 README 中自动插入 docs 文档的链接
### 4.5 增量更新机制
- 首次执行：生成完整文档结构
- 再次执行：
- 检测项目变更
- 更新受影响的文档
- 保留用户手动编辑的内容（通过标记区分）
## 验证标准
- [ ] `aide config get user_docs.docs_path` 正常工作
- [ ] 根据项目类型生成合适的文档结构
- [ ] 与 README 正确关联
- [ ] 增量更新机制正常工作
- [ ] 保留用户手动编辑的内容
## 依赖
- 前置：子计划 3（README 命令）
- 后续：子计划 5（用户流程图命令）
## 风险评估
- **风险等级**：中
- **潜在影响**：文档结构的合理性和可维护性
- **缓解措施**：参考主流开源项目的文档组织方式

194
.aide/task-plans/spec-05.md
View File

@@ -1,194 +0,0 @@
# 子计划 5：用户流程图命令实现
## 目标
创建 `/aide:user-graph` 命令，实现面向用户的长期维护流程图系统，支持分步执行和接续执行。
## 具体步骤
### 5.1 添加配置项
**位置**：`aide-program/aide/` 配置模块
**新增配置项**：
```toml
[user_docs]
# 用户流程图目录路径（相对于项目根目录）
graph_path = "docs/graph-guide"
# 流程图计划文件路径
graph_plan_path = "docs/graph-guide/plan.md"
```
### 5.2 创建命令文件
**位置**：`aide-marketplace/aide-plugin/commands/user-graph.md`
**命令流程**：
```
开始
│
├─ 检查计划文件是否存在
│ │
│ ├─ 不存在 → 进入分析和计划阶段
│ │
│ └─ 存在 → 进入接续执行阶段
│
└─ 结束
```
### 5.3 流程图目录结构设计
以用户示例为参考（api-lib + api + user-interface）：
```
docs/graph-guide/
├── plan.md # 计划和进度文档
├── guide.puml # 总导览流程图
├── api-lib/ # 子项目 1
│ ├── guide.puml # 子项目导览
│ ├── module-a.puml # 模块 A 流程图
│ └── module-b.puml # 模块 B 流程图
├── api/ # 子项目 2
│ ├── guide.puml
│ └── ...
└── user-interface/ # 子项目 3
├── guide.puml
└── ...
```
### 5.4 分析和计划阶段
当计划文件不存在时：
1. **加载项目文档**：
- 读取 `.aide/project-docs/` 下的项目文档
- 了解项目结构和模块
2. **区块划分**（按业务逻辑整体）：
- 不同于项目文档的深度全覆盖
- 目标是呈现整体形式
- 识别独立的开发项目/模块
3. **复杂度分析**：
- 评估每个区块的复杂度
- 估算每个区块需要的工作量
- 识别可能需要细分的大型区块
4. **生成计划文档**（plan.md）：
```markdown
# 用户流程图编写计划
## 项目概述
[基于项目文档的简要描述]
## 区块划分
| # | 区块名称 | 类型 | 复杂度 | 状态 |
|---|----------|------|--------|------|
| 1 | api-lib | 库项目 | 高 | pending |
| 2 | api | 应用 | 中 | pending |
| 3 | user-interface | 前端 | 中 | pending |
## 执行步骤
### 区块 1: api-lib
- [ ] 步骤 1.1: 分析模块结构
- [ ] 步骤 1.2: 编写 guide.puml
- [ ] 步骤 1.3: 编写 module-a.puml
- [ ] 步骤 1.4: 编写 module-b.puml
...
### 区块 2: api
...
## 当前进度
- 当前区块：1
- 当前步骤：1.1
- 最后更新：[时间戳]
## 备注
[执行过程中的记录]
```
5. **用户确认**：
- 展示计划摘要
- 询问是否开始执行
### 5.5 接续执行阶段
当计划文件存在时：
1. **读取计划文档**
2. **定位当前进度**
3. **继续执行未完成的步骤**
4. **每完成一个步骤，更新计划文档**
### 5.6 流程图类型
根据项目内容决定流程图类型：
**不含程序的项目**：
- 引导用户了解项目的流程图
- 内容导航图
- 学习路径图
**含程序的项目**：
- 引导流程图（如何了解项目）
- 程序逻辑流图（参考 /aide:run 中的规范）
- 入口点
- 控制结构
- 语义化抽象
- 模块化表示
- 层次化组织
### 5.7 一套流程图的标准
每个开发项目/区块应包含：
1. **guide.puml**：子项目导览
- 模块概览
- 调用关系
- 数据流向
2. **子模块 puml**：详细流程
- 核心逻辑
- 关键函数
- 状态转换
### 5.8 分步执行机制
为支持大型项目的分步执行：
1. **进度持久化**：通过 plan.md 记录进度
2. **接续点精确定位**：通过区块+步骤编号
3. **上下文恢复**：每次执行前读取项目文档和计划
4. **增量产出**：每步完成后保存产出的 puml 文件
## 验证标准
- [ ] 计划文档格式正确，信息完整
- [ ] 区块划分合理，符合业务逻辑
- [ ] 接续执行能正确定位进度
- [ ] 生成的流程图符合 PlantUML 语法
- [ ] 流程图能正确生成 PNG
## 依赖
- 前置：子计划 4（user-docs 命令）
- 后续：无
## 风险评估
- **风险等级**：高
- **潜在影响**：
- 大型项目可能需要多次对话完成
- 区块划分不当可能导致重复工作
- 流程图质量影响用户理解
- **缓解措施**：
- 完善的进度跟踪机制
- 用户确认关键决策
- 参考优秀的流程图设计

217
.aide/task-plans/spec-06.md
View File

@@ -1,217 +0,0 @@
# 子计划 6：返工流程优化
## 目标
优化 Aide 工作流的返工流程，包括：
1. 创建 `rework` skill 提供返工指导
2. 修改 `/aide:run` 命令引用该 skill
3. 修改 aide-program 实现 back-confirm 机制
## 具体步骤
### 6.1 创建 rework skill
**位置**：`aide-marketplace/aide-plugin/skills/rework/SKILL.md`
**内容结构**：
```markdown
# 返工流程指南
## 返工类型判断
| 返工目标 | 触发条件 | 处理方式 |
|----------|----------|----------|
| task-optimize | 新需求、需求理解偏差 | 更新 task.source |
| flow-design | 架构/流程设计问题 | 更新细则 + new-requirements.md |
| impl | 实现问题 | 更新细则 + new-requirements.md |
| verify | 验证未通过 | 更新细则 + new-requirements.md |
## 返工到 task-optimize 阶段
### 流程
1. `aide flow issue "准备返工: [原因简述]"`
2. 更新 task.source 文档：
- 插入用户新需求原文
- 记录提出时机
- 添加 LLM 建议（可选）
3. 提醒用户
4. 执行 `aide flow back-confirm --key [key]`
5. 执行 `aide flow back-part task-optimize "[原因]"`
### task.source 更新格式
在文档末尾添加：
```markdown
---
## 返工记录 [时间戳]
### 用户反馈
[用户原文]
### 提出时机
[在哪个阶段/步骤提出]
### LLM 建议
[如有]
```
## 返工到其他阶段
### 流程
1. `aide flow issue "准备返工前处理需求整合: [原因简述]"`
2. 创建/更新 new-requirements.md：
- 记录用户新需求原文
- 记录提出时机
3. 更新细则文档：
- 在导览部分添加返工声明
- 梳理：已完成项、未完成项、需重新处理项
- 处理需求冲突
- 融入新需求
- 删除返工声明
4. 提醒用户
5. 执行 `aide flow back-confirm --key [key]`
6. 执行 `aide flow back-part [阶段] "[原因]"`
### new-requirements.md 格式
```markdown
# 新需求记录
## 返工 [时间戳]
### 用户反馈
[原文]
### 提出时机
[阶段/步骤]
### 影响分析
- 已完成项：[列表]
- 未完成项：[列表]
- 需重新处理：[列表]
### 冲突处理
[如何处理与原细则的冲突]
```
## 提醒用户
### 返工到 task-optimize
> 我将会对 task-now.md 进行更新，加入您的新需求和我的建议，然后更新流程状态返工到 task-optimize 阶段。建议您在流程状态返工后使用 `/exit` 结束本次对话，重新启动一个新的对话执行 load+run，我将会自动接续任务的处理。
### 返工到其他阶段
> 我将会对 new-requirements.md 进行更新，加入您的新需求和我的建议，然后处理好您的新需求和原细则的需求冲突整合，然后更新流程状态返工到 [阶段] 阶段。建议您在流程状态返工后使用 `/exit` 结束本次对话，重新启动一个新的对话执行 load+run，我将会自动接续任务的处理。
## 确认机制
返工前必须完成确认流程，详见 aide flow back-confirm 命令说明。
```
### 6.2 修改 /aide:run 命令
**位置**：`aide-marketplace/aide-plugin/commands/run.md`
**修改内容**：
在 confirm 阶段的返工流程部分添加：
```markdown
#### 6.3 返工流程
当用户发现问题或有新需求时：
**触发 rework skill**：
加载 `rework` skill 学习返工流程指南，按照指南完成返工处理。
```
### 6.3 修改 aide-program：back-confirm 机制
**位置**：`aide-program/aide/flow/` 模块
**新增命令**：`aide flow back-confirm --key <key>`
**实现逻辑**：
1. **back-part 命令修改**：
- 执行前检查是否有待确认的 back 请求
- 如无确认，输出提示并生成随机 key
- 记录目标阶段和原因到状态文件
- 要求 LLM 确认已完成准备工作后执行 back-confirm
2. **back-confirm 命令实现**：
- 验证 key 是否匹配
- 匹配成功后：
- 读取状态文件中的目标阶段和原因
- 清理状态文件（删除 `.aide/back-confirm-state.json`）
- 执行 back-part 操作
- 暂存所有更改：`git add .`
- 创建清洁提交：`git commit -m "[aide] 返工前清洁提交"`
- 输出警告：建议用户 `/exit` 重新对话
**数据流**：
```
LLM 请求 back-part flow-design "设计遗漏"
│
↓
aide 检测未确认，记录目标和原因，生成 key "abc123"，输出提示
│
↓
LLM 完成准备工作后，执行 back-confirm --key abc123
│
↓
aide 验证 key 成功 → 清理状态文件 → 执行 back-part → 创建清洁提交 → 输出警告
│
↓
结束（LLM 无需第三次请求）
```
### 6.4 状态存储
**位置**：`.aide/back-confirm-state.json`
**格式**：
```json
{
"pending_key": "abc123",
"target_part": "flow-design",
"reason": "设计遗漏，需要补充",
"created_at": "2025-12-19T10:00:00+08:00"
}
```
> 注：验证成功后直接执行并清理状态文件，无需 confirmed 字段
## 验证标准
- [ ] rework skill 内容完整，指导清晰
- [ ] /aide:run 正确引用 rework skill
- [ ] `aide flow back-part` 在未确认时生成 key 并记录状态
- [ ] `aide flow back-confirm --key` 正确验证 key 并直接执行 back-part
- [ ] 执行后创建清洁提交
- [ ] 输出正确的警告信息
- [ ] 状态文件在完成后被清理
## 依赖
- 前置：无（独立任务）
- 后续：无
## 风险评估
- **风险等级**：中
- **潜在影响**：
- 确认机制增加操作复杂度
- 清洁提交可能与用户 git 工作流冲突
- **缓解措施**：
- 提供清晰的操作提示
- 清洁提交信息明确标注来源
- 文档说明机制目的