diff --git a/.aide/flow-status.json b/.aide/flow-status.json index 6aa50ba..61d549e 100644 --- a/.aide/flow-status.json +++ b/.aide/flow-status.json @@ -1,7 +1,7 @@ { "task_id": "2025-12-15T17-28-53", "current_phase": "finish", - "current_step": 22, + "current_step": 23, "started_at": "2025-12-15T17:28:53+08:00", "history": [ { @@ -178,6 +178,14 @@ "step": 22, "summary": "同步更新 aide skill 文档: 新增命令体系、数据存储结构、完整流程示例", "git_commit": "cc959ee7cfb3ac4a70cb15b35ffec6574d35c05e" + }, + { + "timestamp": "2025-12-15T18:25:17+08:00", + "action": "next-step", + "phase": "finish", + "step": 23, + "summary": "同步更新 env-config skill: 添加与新命令体系的关系说明", + "git_commit": "67162d23370766258fffd10ec0e476c8bca86924" } ] } diff --git a/.aide/flow-status.lock b/.aide/flow-status.lock deleted file mode 100755 index 5194fb1..0000000 --- a/.aide/flow-status.lock +++ /dev/null @@ -1 +0,0 @@ -127361 \ No newline at end of file diff --git a/aide-marketplace/aide-plugin/docs/README.md b/aide-marketplace/aide-plugin/docs/README.md index f71b9d2..6603e5b 100644 --- a/aide-marketplace/aide-plugin/docs/README.md +++ b/aide-marketplace/aide-plugin/docs/README.md @@ -15,40 +15,43 @@ aide-plugin 是 Claude Code 插件，提供 Aide 工作流体系的 Commands 和 ### 1.2 组件关系 ``` -┌─────────────────────────────────────────────────┐ -│ Commands │ -│ 定义"做什么"和"按什么顺序做" │ -│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ -│ │ init │ │ prep │ │ exec │ │ -│ └────┬────┘ └────┬────┘ └────┬────┘ │ -└───────┼────────────┼────────────┼───────────────┘ - │ │ │ - ▼ ▼ ▼ -┌─────────────────────────────────────────────────┐ -│ Skill │ -│ 定义"怎么调用工具" │ -│ ┌─────────────────────────────────────────┐ │ -│ │ aide skill │ │ -│ │ env | flow | decide | config | init │ │ -│ └─────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────┘ +┌─────────────────────────────────────────────────────────────────┐ +│ Commands │ +│ 定义"做什么"和"按什么顺序做" │ +│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ +│ │ setup │ │ load │ │ docs │ │ run │ │ +│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ +└───────┼────────────┼────────────┼────────────┼──────────────────┘ + │ │ │ │ + ▼ ▼ ▼ ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ Skills │ +│ 定义"怎么调用工具" │ +│ ┌─────────────────────┐ ┌─────────────────────┐ │ +│ │ aide skill │ │ env-config skill │ │ +│ │ (基础命令指南) │ │ (环境配置详细指南) │ │ +│ └─────────────────────┘ └─────────────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ │ ▼ 调用 -┌─────────────────────────────────────────────────┐ -│ aide-program │ -│ 实际执行操作，返回精简结果 │ -└─────────────────────────────────────────────────┘ +┌─────────────────────────────────────────────────────────────────┐ +│ aide-program │ +│ 实际执行操作，返回精简结果 │ +└─────────────────────────────────────────────────────────────────┘ ``` --- ## 二、Commands 索引 -| Command | 设计文档 | 执行文件 | 职责 | -|---------|----------|----------|------| -| `/aide:init` | [commands/init.md](commands/init.md) | [../../commands/init.md](../commands/init.md) | 项目认知与环境初始化 | -| `/aide:prep` | [commands/prep.md](commands/prep.md) | [../../commands/prep.md](../commands/prep.md) | 任务准备流程 | -| `/aide:exec` | [commands/exec.md](commands/exec.md) | [../../commands/exec.md](../commands/exec.md) | 任务执行流程 | +| Command | 设计文档 | 执行文件 | 职责 | 独立运行 | +|---------|----------|----------|------|----------| +| `/aide:setup` | [commands/setup.md](commands/setup.md) | [../commands/setup.md](../commands/setup.md) | 环境配置 | 是 | +| `/aide:load` | [commands/load.md](commands/load.md) | [../commands/load.md](../commands/load.md) | 项目认知载入 | 否 | +| `/aide:docs` | [commands/docs.md](commands/docs.md) | [../commands/docs.md](../commands/docs.md) | 项目文档管理 | 是 | +| `/aide:run` | [commands/run.md](commands/run.md) | [../commands/run.md](../commands/run.md) | 任务执行（核心） | 否 | + +> 注：原 `/aide:init`、`/aide:prep`、`/aide:exec` 已重组为上述命令 ### 2.1 Commands 设计原则 @@ -64,35 +67,42 @@ Commands 只告诉 LLM： ### 2.2 工作流程 ``` -/aide:init /aide:prep /aide:exec - │ │ │ - ▼ ▼ ▼ -┌────────┐ ┌──────────┐ ┌──────────┐ -│环境检测│ │ 任务分析 │ │ 流程设计 │ -│项目认知│ │ 任务优化 │ │ 迭代实现 │ -│介绍能力│ │ 待定项 │ │ 验证交付 │ -└────────┘ │ 生成细则 │ │ 文档更新 │ - └──────────┘ │ 收尾 │ - │ └──────────┘ - ▼ - task-spec.md ──────────────▶ +/aide:setup /aide:docs /aide:run +(独立运行) (独立运行) (核心命令) + │ │ │ + ▼ ▼ ▼ +┌────────┐ ┌──────────┐ ┌──────────────────┐ +│环境配置│ │ 项目文档 │ │ task-optimize │ +│依赖分析│ │ 区块划分 │ │ ├─ 任务分析 │ +│模块检测│ │ 文档生成 │ │ ├─ 复杂度评估 │ +│问题修复│ │ 增量更新 │ │ ├─ 待定项处理 │ +└────────┘ └──────────┘ │ └─ 生成细则 │ + │ flow-design │ + │ └─ 创建流程图 │ + │ impl (迭代实现) │ + │ verify (验证) │ + │ docs (文档更新) │ + │ finish (收尾) │ + └──────────────────┘ ``` +> `/aide:load` 由 `/aide:run` 自动调用，用于按需载入项目文档。 + --- ## 三、Skill 索引 | Skill | 执行文件 | 职责 | 触发时机 | |-------|----------|------|----------| -| aide | [../skills/aide/SKILL.md](../skills/aide/SKILL.md) | aide 基础命令指南 | 始终加载 | -| env-config | [../skills/env-config/SKILL.md](../skills/env-config/SKILL.md) | 环境配置详细指南 | `aide env ensure` 失败时 | +| aide | [../skills/aide/SKILL.md](../skills/aide/SKILL.md) | aide 基础命令指南 | `/aide:run` 强制触发 | +| env-config | [../skills/env-config/SKILL.md](../skills/env-config/SKILL.md) | 环境配置详细指南 | `/aide:setup` 强制触发 | ### 3.1 Skill 设计原则 **按需触发，避免信息过载** -- `aide` skill：始终加载，提供基础命令用法 -- `env-config` skill：按需触发，仅在环境检测失败时使用 +- `aide` skill：由 `/aide:run` 强制触发，提供基础命令用法 +- `env-config` skill：由 `/aide:setup` 强制触发，提供详细环境配置指导 **纯工具说明，便于快速查阅** @@ -106,13 +116,18 @@ Skill 只包含： ### 3.2 Skill 触发逻辑 ``` -aide env ensure - │ - ├─ 全部 ✓ → 继续流程（无需额外 skill） - │ - └─ 有 ✗ → 触发 env-config skill +/aide:setup /aide:run + │ │ + ▼ ▼ +触发 env-config skill 触发 aide skill + │ │ + ▼ ▼ +aide env ensure aide flow status + │ │ + ├─ 全部 ✓ → 完成 ├─ 无活跃任务 → 新任务流程 + │ │ + └─ 有 ✗ → 分析项目类型 └─ 有活跃任务 → 续接流程 │ - ├─ 分析项目类型 ├─ aide env set 配置 └─ 重试 aide env ensure ``` @@ -129,6 +144,7 @@ aide env ensure | 待定项呈现与确认 | `aide decide` | | 状态记录与 git 提交 | `aide flow` | | 配置读写 | `aide config` | +| 流程图校验与构建 | `aide flow` + PlantUML | ### 4.2 不需要程序约束的场景 @@ -136,9 +152,11 @@ aide env ensure |------|------| | 任务分析思考 | LLM 自由发挥 | | 任务优化思考 | LLM 自由发挥 | +| 复杂度评估 | LLM 根据指导原则判断 | | 业务决策判断 | LLM 自由发挥 | | 任务细则编写 | LLM 自由发挥，产出 task-spec.md | | 业务代码编写 | LLM 自由发挥 | +| 流程图设计 | LLM 自由发挥，产出 .puml 文件 | --- @@ -146,9 +164,9 @@ aide env ensure ### 5.1 修改 Command -1. 阅读对应的设计文档（如 `commands/init.md`） +1. 阅读对应的设计文档（如 `commands/setup.md`） 2. 理解职责和流程 -3. 修改执行文件（如 `../commands/init.md`） +3. 修改执行文件（如 `../commands/setup.md`） 4. 更新设计文档（如有重大变更） 5. 更新本导览（如有新增/删除 Command） @@ -178,3 +196,11 @@ aide env ensure - [aide flow 子命令](../../../aide-program/docs/commands/flow.md) - [aide flow 详细设计](../../../aide-program/docs/commands/flow/README.md) - [Claude Code 插件指南](../../../docs/03-插件指南.md) + +--- + +## 七、版本信息 + +- 当前版本：2.0.0 +- 更新日期：2025-12-15 +- 主要变更：Commands 体系重组（setup/load/docs/run 替代 init/prep/exec） diff --git a/aide-marketplace/aide-plugin/docs/commands/exec.md b/aide-marketplace/aide-plugin/docs/commands/_deprecated_exec.md similarity index 100% rename from aide-marketplace/aide-plugin/docs/commands/exec.md rename to aide-marketplace/aide-plugin/docs/commands/_deprecated_exec.md diff --git a/aide-marketplace/aide-plugin/docs/commands/init.md b/aide-marketplace/aide-plugin/docs/commands/_deprecated_init.md similarity index 100% rename from aide-marketplace/aide-plugin/docs/commands/init.md rename to aide-marketplace/aide-plugin/docs/commands/_deprecated_init.md diff --git a/aide-marketplace/aide-plugin/docs/commands/prep.md b/aide-marketplace/aide-plugin/docs/commands/_deprecated_prep.md similarity index 100% rename from aide-marketplace/aide-plugin/docs/commands/prep.md rename to aide-marketplace/aide-plugin/docs/commands/_deprecated_prep.md diff --git a/aide-marketplace/aide-plugin/docs/commands/docs.md b/aide-marketplace/aide-plugin/docs/commands/docs.md new file mode 100644 index 0000000..673badb --- /dev/null +++ b/aide-marketplace/aide-plugin/docs/commands/docs.md @@ -0,0 +1,185 @@ +# /aide:docs 命令设计文档 + +## 一、概述 + +`/aide:docs` 是项目文档管理命令，用于创建和维护面向 LLM 的项目文档。 + +### 1.1 设计目标 + +| 目标 | 说明 | +|------|------| +| 独立运行 | 通常在需要时单独执行 | +| 区块化 | 文档按区块组织，支持增量更新 | +| 面向 LLM | 文档格式针对 LLM 理解优化 | +| 多对话续接 | 大项目支持多次对话完成 | + +### 1.2 新增命令 + +本命令是 v2.0.0 新增的独立命令。 + +--- + +## 二、执行流程 + +### 2.1 创建流程 + +``` +┌─────────────────────────────────────────┐ +│ /aide:docs │ +│ (文档不存在时) │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 目录探索 │ +│ (遍历结构、统计文件、识别忽略项) │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 初步区块划分 │ +│ (按目录结构和功能模块划分) │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 区块验证 │ +│ (浅层探索验证划分合理性) │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 逐区块深度了解 │ +│ (完整阅读、提取信息、生成文档) │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 生成总导览 │ +│ (整合所有区块信息) │ +└─────────────────────────────────────────┘ +``` + +### 2.2 更新流程 + +``` +┌─────────────────────────────────────────┐ +│ /aide:docs │ +│ (文档已存在时) │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 读取区块计划 │ +│ (了解当前文档结构) │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 分区块验证 │ +│ (对比文档与代码，识别差异) │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 增量更新 │ +│ (只更新有变化的区块) │ +└─────────────────────────────────────────┘ +``` + +--- + +## 三、文档结构 + +### 3.1 目录结构 + +``` +.aide/project-docs/ +├── README.md # 总导览 +├── block-plan.md # 区块计划（进度追踪） +└── blocks/ # 子区块文档 + ├── core.md + ├── api.md + └── ... +``` + +### 3.2 总导览格式 + +```markdown +# [项目名称] 项目导览 + +> 本文档面向 LLM，用于快速了解项目结构和脉络。 + +## 项目简介 +## 技术栈 +## 架构概述 +## 区块索引 +## 快速导航 +``` + +### 3.3 子区块格式 + +```markdown +# [区块名称] + +> 路径：xxx/ + +## 概述 +## 文件清单 +## 核心组件 +## 接口说明 +## 依赖关系 +## 注意事项 +``` + +--- + +## 四、职责边界 + +### 4.1 本命令负责 + +- 探索项目目录结构 +- 划分文档区块 +- 创建和更新项目文档 +- 维护区块计划（进度追踪） + +### 4.2 本命令不负责 + +- 环境配置（由 `/aide:setup` 负责） +- 项目文档载入（由 `/aide:load` 负责） +- 任务准备和执行（由 `/aide:run` 负责） + +--- + +## 五、区块划分规则 + +1. **按目录结构**：每个主要目录可作为一个区块 +2. **按功能模块**：相关功能的文件归为一个区块 +3. **大小控制**：单个区块不超过 5000 行代码 +4. **低耦合**：区块间依赖关系尽量简单 + +--- + +## 六、多对话续接 + +大项目可能需要多次对话完成： + +1. 每次开始时读取区块计划 +2. 找到未完成的区块 +3. 继续处理 +4. 更新区块计划的进度 + +--- + +## 七、相关文档 + +- [执行文件](../../commands/docs.md) +- [/aide:load 命令](load.md) +- [plugin 导览](../README.md) + +--- + +## 八、版本信息 + +- 创建日期：2025-12-15 +- v2.0.0 新增命令 diff --git a/aide-marketplace/aide-plugin/docs/commands/load.md b/aide-marketplace/aide-plugin/docs/commands/load.md new file mode 100644 index 0000000..09bbc82 --- /dev/null +++ b/aide-marketplace/aide-plugin/docs/commands/load.md @@ -0,0 +1,117 @@ +# /aide:load 命令设计文档 + +## 一、概述 + +`/aide:load` 是项目认知载入命令，用于按需载入项目文档，建立对项目的认知。 + +### 1.1 设计目标 + +| 目标 | 说明 | +|------|------| +| 按需载入 | 初次仅了解脉络，后续按需深入 | +| 节省 Token | 避免一次性加载过多信息 | +| 支持续接 | 为任务续接提供项目上下文 | + +### 1.2 与旧命令的关系 + +本命令从原 `/aide:init` 中拆分出项目认知功能。 + +--- + +## 二、执行流程 + +``` +┌─────────────────────────────────────────┐ +│ /aide:load │ +│ (通常由 /aide:run 自动调用) │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 检查项目文档配置 │ +│ aide config get docs.path │ +└─────────────────────────────────────────┘ + │ + ┌──────────┴──────────┐ + ▼ ▼ + [文档存在] [文档不存在] + │ │ + ▼ ▼ +┌───────────────┐ ┌───────────────────┐ +│ 载入总导览 │ │ 提示执行 /aide:docs│ +│ 建立脉络认知 │ │ 或快速项目认知 │ +└───────────────┘ └───────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 按需深入 │ +│ (根据任务需要载入相关区块) │ +└─────────────────────────────────────────┘ +``` + +--- + +## 三、职责边界 + +### 3.1 本命令负责 + +- 检查项目文档是否存在 +- 载入总导览文档 +- 建立项目脉络认知 +- 按需载入区块详细文档 + +### 3.2 本命令不负责 + +- 环境配置（由 `/aide:setup` 负责） +- 项目文档创建和维护（由 `/aide:docs` 负责） +- 任务准备和执行（由 `/aide:run` 负责） + +--- + +## 四、调用方式 + +本命令通常**不单独执行**，而是由 `/aide:run` 在以下场景自动调用： + +1. 续接未完成的任务时 +2. 需要了解项目上下文时 + +--- + +## 五、文档载入策略 + +### 5.1 初次载入（脉络认知） + +仅读取总导览文档，了解： +- 项目简介 +- 技术栈 +- 架构概述 +- 区块索引 + +### 5.2 按需深入 + +根据任务需要，载入相关区块的详细文档： +- 任务涉及哪些模块 → 载入对应区块 +- 需要了解某个功能 → 载入相关区块 + +### 5.3 快速认知（无文档时） + +如果项目文档不存在，进行快速认知： +1. 阅读 README.md、CLAUDE.md +2. 阅读配置文件（package.json、Cargo.toml 等） +3. 探索目录结构 + +--- + +## 六、相关文档 + +- [执行文件](../../commands/load.md) +- [/aide:docs 命令](docs.md) +- [/aide:run 命令](run.md) +- [plugin 导览](../README.md) + +--- + +## 七、版本信息 + +- 创建日期：2025-12-15 +- 从 `/aide:init` 拆分而来 diff --git a/aide-marketplace/aide-plugin/docs/commands/run.md b/aide-marketplace/aide-plugin/docs/commands/run.md new file mode 100644 index 0000000..3d0f4c1 --- /dev/null +++ b/aide-marketplace/aide-plugin/docs/commands/run.md @@ -0,0 +1,214 @@ +# /aide:run 命令设计文档 + +## 一、概述 + +`/aide:run` 是任务执行的核心命令，整合了任务准备和任务执行功能。 + +### 1.1 设计目标 + +| 目标 | 说明 | +|------|------| +| 统一入口 | 一个命令完成任务准备和执行 | +| 状态感知 | 自动检测 flow 状态，支持续接 | +| 复杂度适应 | 支持简单任务直接执行，复杂任务拆分子计划 | + +### 1.2 与旧命令的关系 + +本命令整合了原 `/aide:prep` 和 `/aide:exec` 的功能。 + +--- + +## 二、执行流程 + +### 2.1 总体流程 + +``` +┌─────────────────────────────────────────┐ +│ /aide:run │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 强制触发 aide skill │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ aide flow status │ +│ (检查当前 flow 状态) │ +└─────────────────────────────────────────┘ + │ + ┌──────────┴──────────┐ + ▼ ▼ + [无活跃任务] [有活跃任务] + [或已 finish] [未完成] + │ │ + ▼ ▼ + 新任务流程 续接流程 +``` + +### 2.2 新任务流程 + +``` +┌─────────────────────────────────────────┐ +│ task-optimize (任务准备) │ +├─────────────────────────────────────────┤ +│ 1. aide flow start task-optimize │ +│ 2. 读取任务文档 │ +│ 3. 任务分析 │ +│ 4. 复杂度评估 │ +│ 5. 任务优化 │ +│ 6. 待定项处理（如有） │ +│ 7. 生成任务细则 │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ flow-design (流程设计) │ +├─────────────────────────────────────────┤ +│ 1. aide flow next-part flow-design │ +│ 2. 制定执行计划 │ +│ 3. 创建流程图（PlantUML） │ +│ 4. aide flow next-part impl │ +│ (自动校验并生成 PNG) │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ impl (迭代实现) │ +├─────────────────────────────────────────┤ +│ 按计划执行，每步记录： │ +│ aide flow next-step "<完成内容>" │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ verify (验证交付) │ +├─────────────────────────────────────────┤ +│ 1. aide flow next-part verify │ +│ 2. 对照任务细则验证 │ +│ 3. 执行测试（如适用） │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ docs (文档更新) │ +├─────────────────────────────────────────┤ +│ 1. aide flow next-part docs │ +│ 2. 更新 README、CHANGELOG 等 │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ finish (收尾) │ +├─────────────────────────────────────────┤ +│ 1. aide flow next-part finish │ +│ 2. 清理临时文件 │ +│ 3. 向用户汇报 │ +└─────────────────────────────────────────┘ +``` + +### 2.3 续接流程 + +``` +┌─────────────────────────────────────────┐ +│ 分析当前进度 │ +├─────────────────────────────────────────┤ +│ aide flow status │ +│ aide flow show │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 载入项目认知 │ +├─────────────────────────────────────────┤ +│ 调用 /aide:load 逻辑 │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 读取任务细则 │ +├─────────────────────────────────────────┤ +│ aide config get task.spec │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 从中断处继续执行 │ +└─────────────────────────────────────────┘ +``` + +--- + +## 三、复杂任务处理 + +### 3.1 复杂度评估 + +根据**任务复杂度评估指导原则**判断： + +| 等级 | 特征 | 处理方式 | +|------|------|----------| +| 简单 | 单文件或少量文件 | 直接执行 | +| 中等 | 2-4 个模块 | 直接执行 | +| 复杂 | 5+ 模块 | **拆分子计划** | +| 超大 | 10+ 模块 | 拆分独立任务 | + +### 3.2 子计划执行模式 + +``` +task-optimize + │ + ▼ +[flow-design → impl → verify → docs] × N + │ + ▼ +finish +``` + +每个子计划完成 docs 后，回退到 flow-design 开始下一个子计划。 + +--- + +## 四、职责边界 + +### 4.1 本命令负责 + +- 检查 flow 状态 +- 任务分析和优化 +- 复杂度评估和子计划拆分 +- 待定项处理 +- 流程设计和流程图创建 +- 迭代实现 +- 验证交付 +- 文档更新 +- 收尾汇报 + +### 4.2 本命令不负责 + +- 环境配置（由 `/aide:setup` 负责） +- 项目文档创建和维护（由 `/aide:docs` 负责） + +--- + +## 五、触发的 Skill + +| Skill | 触发方式 | 用途 | +|-------|----------|------| +| aide | 强制触发 | 提供 aide 命令使用指南 | + +--- + +## 六、相关文档 + +- [执行文件](../../commands/run.md) +- [aide skill](../../skills/aide/SKILL.md) +- [aide flow 子命令](../../../../aide-program/docs/commands/flow.md) +- [aide decide 子命令](../../../../aide-program/docs/commands/decide.md) +- [plugin 导览](../README.md) + +--- + +## 七、版本信息 + +- 创建日期：2025-12-15 +- 整合原 `/aide:prep` 和 `/aide:exec` diff --git a/aide-marketplace/aide-plugin/docs/commands/setup.md b/aide-marketplace/aide-plugin/docs/commands/setup.md new file mode 100644 index 0000000..eb86232 --- /dev/null +++ b/aide-marketplace/aide-plugin/docs/commands/setup.md @@ -0,0 +1,140 @@ +# /aide:setup 命令设计文档 + +## 一、概述 + +`/aide:setup` 是环境配置命令，专注于环境依赖分析、配置、检测和修复。 + +### 1.1 设计目标 + +| 目标 | 说明 | +|------|------| +| 独立运行 | 通常在新项目开始时单独执行 | +| 环境专注 | 只处理环境问题，不涉及任务执行 | +| 自动化 | 尽可能自动检测和修复环境问题 | + +### 1.2 与旧命令的关系 + +本命令从原 `/aide:init` 中拆分出环境相关功能。 + +--- + +## 二、执行流程 + +``` +┌─────────────────────────────────────────┐ +│ /aide:setup │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 强制触发 env-config skill │ +│ (获取详细环境配置指导) │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ aide env ensure --runtime │ +│ (检查 aide 运行时环境) │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ aide init │ +│ (初始化 .aide 目录) │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 分析项目依赖 │ +│ (识别项目类型和所需模块) │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ aide env set modules ... │ +│ (配置环境模块) │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ aide env ensure │ +│ (执行环境检测) │ +└─────────────────────────────────────────┘ + │ + ┌──────────┴──────────┐ + ▼ ▼ + [成功] [失败] + │ │ + ▼ ▼ + 完成汇报 故障排除 + │ + ▼ + 重试(最多3次) +``` + +--- + +## 三、职责边界 + +### 3.1 本命令负责 + +- 检测 aide 运行时环境 +- 初始化 .aide 目录 +- 分析项目类型和依赖 +- 配置环境检测模块 +- 执行环境检测和修复 +- 处理环境问题 + +### 3.2 本命令不负责 + +- 项目认知和文档载入（由 `/aide:load` 负责） +- 任务准备和执行（由 `/aide:run` 负责） +- 项目文档管理（由 `/aide:docs` 负责） + +--- + +## 四、触发的 Skill + +| Skill | 触发方式 | 用途 | +|-------|----------|------| +| env-config | 强制触发 | 提供详细的环境配置和故障排除指导 | + +--- + +## 五、使用场景 + +### 5.1 新项目开始 + +```bash +# 用户执行 +/aide:setup + +# LLM 执行流程 +1. 触发 env-config skill +2. aide env ensure --runtime +3. aide init +4. 分析项目（检查 package.json、Cargo.toml 等） +5. aide env set modules <根据项目类型> +6. aide env ensure +7. 汇报结果 +``` + +### 5.2 环境问题排查 + +当任务执行中遇到环境错误时，用户可重新执行此命令进行诊断和修复。 + +--- + +## 六、相关文档 + +- [执行文件](../../commands/setup.md) +- [env-config skill](../../skills/env-config/SKILL.md) +- [aide env 子命令](../../../../aide-program/docs/commands/env.md) +- [plugin 导览](../README.md) + +--- + +## 七、版本信息 + +- 创建日期：2025-12-15 +- 从 `/aide:init` 拆分而来 diff --git a/aide-program/docs/README.md b/aide-program/docs/README.md index bf7ed55..025b5ec 100644 --- a/aide-program/docs/README.md +++ b/aide-program/docs/README.md @@ -47,7 +47,12 @@ aide-program 是 Aide 工作流体系的命令行工具，为 aide-plugin 提供 | `aide env list` | [commands/env.md](commands/env.md) | ✅ 已实现 | 列出可用模块 | | `aide env set` | [commands/env.md](commands/env.md) | ✅ 已实现 | 设置环境配置（带验证） | | `aide config` | [formats/config.md](formats/config.md) | ✅ 已实现 | 配置读写 | -| `aide flow` | [commands/flow.md](commands/flow.md) | ✅ 已实现 | 进度追踪与 git 集成 | +| `aide flow start` | [commands/flow.md](commands/flow.md) | ✅ 已实现 | 开始新任务 | +| `aide flow next-part` | [commands/flow.md](commands/flow.md) | ✅ 已实现 | 进入下一阶段 | +| `aide flow next-step` | [commands/flow.md](commands/flow.md) | ✅ 已实现 | 记录步骤完成 | +| `aide flow status` | [commands/flow.md](commands/flow.md) | ✅ 已实现 | 查看当前任务状态 | +| `aide flow list` | [commands/flow.md](commands/flow.md) | ✅ 已实现 | 列出所有任务 | +| `aide flow show` | [commands/flow.md](commands/flow.md) | ✅ 已实现 | 查看指定任务详情 | | `aide decide submit` | [commands/decide.md](commands/decide.md) | ✅ 已实现 | 提交待定项并启动 Web 服务 | | `aide decide result` | [commands/decide.md](commands/decide.md) | ✅ 已实现 | 获取用户决策结果 | @@ -175,10 +180,20 @@ aide-program/ ``` .aide/ -├── config.toml # 项目配置 +├── config.toml # 项目配置（自文档化） ├── flow-status.json # 当前任务进度状态 +├── archive/ # 已完成任务归档 +│ └── {task_id}.json ├── decisions/ # 待定项决策记录 │ └── {timestamp}.json +├── diagrams/ # 流程图文件 +│ └── {task_id}/ +│ ├── *.puml # PlantUML 源文件 +│ └── *.png # 生成的图片 +├── project-docs/ # 项目文档（由 /aide:docs 生成） +│ ├── README.md # 总导览 +│ ├── block-plan.md # 区块计划 +│ └── blocks/ # 子区块文档 └── logs/ # 操作日志 ``` @@ -186,6 +201,7 @@ aide-program/ - `aide init` 时自动检查 `.gitignore` - 默认添加 `.aide/` 为忽略项 +- 可通过配置 `general.gitignore_aide = false` 禁用此行为 --- diff --git a/aide-program/docs/commands/flow.md b/aide-program/docs/commands/flow.md index 66566b5..7ec355a 100644 --- a/aide-program/docs/commands/flow.md +++ b/aide-program/docs/commands/flow.md @@ -153,6 +153,68 @@ aide flow error "<描述>" ✗ 错误已记录: <描述> ``` +### 3.8 aide flow status + +**用途**：查看当前任务状态 + +**语法**： +``` +aide flow status +``` + +**输出**： +``` +→ 当前任务: +→ 环节: +→ 步骤: +→ 开始时间: +``` + +无活跃任务时： +``` +→ 无活跃任务 +``` + +### 3.9 aide flow list + +**用途**：列出所有任务（当前 + 已归档） + +**语法**： +``` +aide flow list +``` + +**输出**： +``` +→ 当前任务: + (, step ) + +→ 已归档任务: + (finish) + (finish) +``` + +### 3.10 aide flow show + +**用途**：查看指定任务的详细信息 + +**语法**： +``` +aide flow show +``` + +**输出**： +``` +→ 任务: +→ 环节: +→ 步骤: +→ 开始时间: + +→ 历史记录: + [1] step=: + [2] ... +``` + --- ## 四、业务流程 @@ -377,8 +439,8 @@ class FlowValidator: | 依赖方 | 说明 | |--------|------| -| /aide:prep | 调用 flow start、next-step | -| /aide:exec | 调用 flow next-part、next-step、issue、error | +| /aide:run | 调用 flow start、next-part、next-step、status、issue、error | +| /aide:load | 调用 flow status 检查任务状态 | --- @@ -410,6 +472,6 @@ class FlowValidator: - [program 导览](../README.md) - [flow 详细设计（交接包）](flow/README.md) - [数据格式文档](../formats/data.md) -- [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md) -- [/aide:prep 命令设计](../../../aide-marketplace/aide-plugin/docs/commands/prep.md) -- [/aide:exec 命令设计](../../../aide-marketplace/aide-plugin/docs/commands/exec.md) +- [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skills/aide/SKILL.md) +- [/aide:run 命令设计](../../../aide-marketplace/aide-plugin/docs/commands/run.md) +- [/aide:load 命令设计](../../../aide-marketplace/aide-plugin/docs/commands/load.md) diff --git a/aide-program/docs/formats/config.md b/aide-program/docs/formats/config.md index 6a30ad6..0c3c747 100644 --- a/aide-program/docs/formats/config.md +++ b/aide-program/docs/formats/config.md @@ -21,6 +21,11 @@ aide 使用 TOML 格式的配置文件，位于 `.aide/config.toml`。 ```toml # Aide 默认配置（由 aide init 生成） +# 本配置文件采用自文档化设计，所有字段均有注释说明 + +# general: 通用设置 +[general] +gitignore_aide = true # 是否自动将 .aide/ 添加到 .gitignore # runtime: aide 自身运行要求 [runtime] @@ -49,10 +54,19 @@ path = ".venv" [env.requirements] path = "requirements.txt" +# docs: 项目文档配置 +[docs] +path = ".aide/project-docs" # 项目文档存放路径 + # flow: 流程配置 [flow] phases = ["task-optimize", "flow-design", "impl", "verify", "docs", "finish"] +# plantuml: PlantUML 配置 +[plantuml] +jar_path = "" # plantuml.jar 路径，为空时使用内置 jar +diagram_path = ".aide/diagrams" # 流程图存放路径 + # decide: 待定项确认服务配置 [decide] port = 3721 @@ -63,7 +77,17 @@ timeout = 0 ## 四、字段详解 -### 4.1 [runtime] 运行时配置 +### 4.1 [general] 通用设置 + +| 字段 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `gitignore_aide` | bool | `true` | 是否自动将 .aide/ 添加到 .gitignore | + +**使用场景**： +- `aide init` 时检查此配置，决定是否修改 .gitignore +- 设为 `false` 可将 .aide/ 纳入版本控制 + +### 4.2 [runtime] 运行时配置 | 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| @@ -74,7 +98,7 @@ timeout = 0 - `aide env ensure --runtime` 使用硬编码的 `"3.11"` - `aide env ensure` 读取 `python_min` 进行检查 -### 4.2 [task] 任务文档配置 +### 4.3 [task] 任务文档配置 | 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| @@ -82,12 +106,12 @@ timeout = 0 | `spec` | string | `"task-spec.md"` | 任务细则文档默认路径 | **使用场景**： -- `/aide:prep` 未传参数时，使用 `source` 作为默认路径 -- `/aide:exec` 未传参数时，使用 `spec` 作为默认路径 +- `/aide:run` 未传参数时，使用 `source` 作为默认路径 +- `/aide:run` 续接任务时，使用 `spec` 读取任务细则 -### 4.3 [env] 环境配置 +### 4.4 [env] 环境配置 -#### 4.3.1 模块列表 +#### 4.4.1 模块列表 | 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| @@ -109,7 +133,7 @@ timeout = 0 **模块实例化命名**：支持 `模块类型:实例名` 格式，用于同类型多实例场景。 -#### 4.3.2 模块配置 +#### 4.4.2 模块配置 **类型A模块（可选配置）**： @@ -151,7 +175,17 @@ manager = "pnpm" - `aide env list` 显示所有可用模块及启用状态 - `aide env ensure --modules X,Y` 检测指定模块 -### 4.4 [flow] 流程配置 +### 4.5 [docs] 项目文档配置 + +| 字段 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `path` | string | `".aide/project-docs"` | 项目文档存放路径 | + +**使用场景**： +- `/aide:docs` 创建和更新项目文档时使用此路径 +- `/aide:load` 载入项目文档时读取此路径 + +### 4.6 [flow] 流程配置 | 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| @@ -161,7 +195,18 @@ manager = "pnpm" - `aide flow` 校验环节跳转合法性 - 定义有效的环节名称 -### 4.5 [decide] 待定项确认配置 +### 4.7 [plantuml] PlantUML 配置 + +| 字段 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `jar_path` | string | `""` | plantuml.jar 路径，为空时使用内置 jar | +| `diagram_path` | string | `".aide/diagrams"` | 流程图存放路径 | + +**使用场景**： +- `aide flow next-part` 离开 flow-design 时校验和生成流程图 +- 支持自定义 jar 路径以使用特定版本的 PlantUML + +### 4.8 [decide] 待定项确认配置 | 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| @@ -315,4 +360,5 @@ modules = ["python", "uv", "venv", "requirements"] - [program 导览](../README.md) - [aide init 设计](../commands/init.md) - [aide env 设计](../commands/env.md) -- [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md) +- [aide flow 设计](../commands/flow.md) +- [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skills/aide/SKILL.md) diff --git a/cache/update_docs.sh b/cache/update_docs.sh new file mode 100755 index 0000000..aaa12ad --- /dev/null +++ b/cache/update_docs.sh @@ -0,0 +1,10 @@ +#!/bin/bash +cd /home/user/temp/ccoptimize/aide-marketplace/aide-plugin/docs/commands + +# 重命名旧设计文档 +mv init.md _deprecated_init.md 2>/dev/null || echo "init.md 不存在" +mv prep.md _deprecated_prep.md 2>/dev/null || echo "prep.md 不存在" +mv exec.md _deprecated_exec.md 2>/dev/null || echo "exec.md 不存在" + +echo "旧设计文档已重命名" +ls -la diff --git a/cache/verify_links.sh b/cache/verify_links.sh new file mode 100755 index 0000000..acd51f1 --- /dev/null +++ b/cache/verify_links.sh @@ -0,0 +1,66 @@ +#!/bin/bash +# 验证文档导览链接有效性 + +cd /home/user/temp/ccoptimize + +echo "=== 验证导览链接 ===" +echo "" + +# 定义要检查的文档文件 +docs=( + "docs/aide-overview.md" + "aide-marketplace/aide-plugin/docs/README.md" + "aide-marketplace/aide-plugin/docs/commands/setup.md" + "aide-marketplace/aide-plugin/docs/commands/load.md" + "aide-marketplace/aide-plugin/docs/commands/docs.md" + "aide-marketplace/aide-plugin/docs/commands/run.md" + "aide-program/docs/README.md" + "aide-program/docs/commands/flow.md" + "aide-program/docs/formats/config.md" +) + +errors=0 + +for doc in "${docs[@]}"; do + if [ ! -f "$doc" ]; then + echo "✗ 文档不存在: $doc" + ((errors++)) + continue + fi + + dir=$(dirname "$doc") + + # 提取所有 markdown 链接 + links=$(grep -oE '\[([^]]+)\]\(([^)]+)\)' "$doc" | grep -oE '\(([^)]+)\)' | tr -d '()' | grep -v '^http' | grep -v '^#') + + if [ -z "$links" ]; then + echo "→ $doc: 无相对链接" + continue + fi + + doc_errors=0 + for link in $links; do + # 解析相对路径 + target="$dir/$link" + # 移除锚点 + target=$(echo "$target" | sed 's/#.*//') + + if [ ! -e "$target" ]; then + echo "✗ $doc: 链接无效 -> $link" + ((doc_errors++)) + ((errors++)) + fi + done + + if [ $doc_errors -eq 0 ]; then + echo "✓ $doc: 所有链接有效" + fi +done + +echo "" +echo "=== 验证完成 ===" +if [ $errors -eq 0 ]; then + echo "✓ 所有链接有效" +else + echo "✗ 发现 $errors 个无效链接" +fi diff --git a/docs/aide-overview.md b/docs/aide-overview.md index 56180c4..4cdeb3e 100644 --- a/docs/aide-overview.md +++ b/docs/aide-overview.md @@ -33,9 +33,9 @@ Aide 是一套面向 Claude Code 的工作流辅助体系，旨在解决 AI 辅 ▼ ┌─────────────────────────────────────────────────────────────┐ │ aide-plugin │ -│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ -│ │ /aide:init │ │ /aide:prep │ │ /aide:exec │ Commands │ -│ └─────────────┘ └─────────────┘ └─────────────┘ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ /aide:setup │ │ /aide:load │ │ /aide:docs │ │ /aide:run │ │ +│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ ┌─────────────────────────────────────────────┐ │ │ │ aide skill │ Skill │ @@ -71,10 +71,12 @@ Aide 是一套面向 Claude Code 的工作流辅助体系，旨在解决 AI 辅 | 文档 | 位置 | 说明 | |------|------|------| | **导览** | [aide-plugin/docs/README.md](../aide-marketplace/aide-plugin/docs/README.md) | plugin 整体介绍和索引 | -| init 命令 | [aide-plugin/docs/commands/init.md](../aide-marketplace/aide-plugin/docs/commands/init.md) | 项目认知与环境初始化 | -| prep 命令 | [aide-plugin/docs/commands/prep.md](../aide-marketplace/aide-plugin/docs/commands/prep.md) | 任务准备流程 | -| exec 命令 | [aide-plugin/docs/commands/exec.md](../aide-marketplace/aide-plugin/docs/commands/exec.md) | 任务执行流程 | +| setup 命令 | [aide-plugin/docs/commands/setup.md](../aide-marketplace/aide-plugin/docs/commands/setup.md) | 环境配置（独立运行） | +| load 命令 | [aide-plugin/docs/commands/load.md](../aide-marketplace/aide-plugin/docs/commands/load.md) | 项目认知载入 | +| docs 命令 | [aide-plugin/docs/commands/docs.md](../aide-marketplace/aide-plugin/docs/commands/docs.md) | 项目文档管理（独立运行） | +| run 命令 | [aide-plugin/docs/commands/run.md](../aide-marketplace/aide-plugin/docs/commands/run.md) | 任务执行（核心命令） | | aide skill | [aide-plugin/docs/skill/aide.md](../aide-marketplace/aide-plugin/docs/skill/aide.md) | aide 命令使用指南 | +| env-config skill | [aide-plugin/skills/env-config/SKILL.md](../aide-marketplace/aide-plugin/skills/env-config/SKILL.md) | 环境配置详细指南 | ### 4.2 aide-program 区块 @@ -104,19 +106,30 @@ Aide 是一套面向 Claude Code 的工作流辅助体系，旨在解决 AI 辅 ### 想了解完整工作流程 ``` -/aide:init → /aide:prep → /aide:exec - │ │ │ - ▼ ▼ ▼ -项目认知 任务准备 任务执行 -环境检测 任务分析 流程设计 - 任务优化 迭代实现 - 待定项处理 验证交付 - 生成细则 文档更新 +/aide:setup /aide:docs /aide:run +(独立运行) (独立运行) (核心命令) + │ │ │ + ▼ ▼ ▼ +环境配置 项目文档 任务执行 +依赖分析 区块划分 ├─ task-optimize (任务准备) +模块检测 文档生成 │ ├─ 任务分析 +问题修复 增量更新 │ ├─ 复杂度评估 + │ ├─ 待定项处理 + │ └─ 生成细则 + ├─ flow-design (流程设计) + │ └─ 创建流程图 + ├─ impl (迭代实现) + ├─ verify (验证交付) + ├─ docs (文档更新) + └─ finish (收尾) ``` +> `/aide:load` 由 `/aide:run` 自动调用，用于按需载入项目文档。 + --- ## 六、版本信息 -- 当前版本：1.0.0 -- 文档拆分自：aide-requirements.md +- 当前版本：2.0.0 +- 更新日期：2025-12-15 +- 主要变更：Commands 体系重组（setup/load/docs/run 替代 init/prep/exec）