diff --git a/.aide/flow-status.json b/.aide/flow-status.json index aa2157c..414c9f2 100644 --- a/.aide/flow-status.json +++ b/.aide/flow-status.json @@ -1,143 +1,15 @@ { - "task_id": "2025-12-17T01-45-46", - "current_phase": "finish", - "current_step": 17, - "started_at": "2025-12-17T01:45:46+08:00", + "task_id": "2025-12-17T02-28-46", + "current_phase": "task-optimize", + "current_step": 1, + "started_at": "2025-12-17T02:28:46+08:00", "history": [ { - "timestamp": "2025-12-17T01:45:46+08:00", + "timestamp": "2025-12-17T02:28:46+08:00", "action": "start", "phase": "task-optimize", "step": 1, - "summary": "开始任务准备: 改进 /aide:docs 命令实现完整项目导览", - "git_commit": "04c2425e6c45a6cbbab44e4cb3d18a41c78d498f" - }, - { - "timestamp": "2025-12-17T01:46:20+08:00", - "action": "next-step", - "phase": "task-optimize", - "step": 2, - "summary": "问题根源分析完成:识别出 5 个核心差距点", - "git_commit": "73bf7b96f402ac6468694a61e6d476cbcdbc9418" - }, - { - "timestamp": "2025-12-17T01:48:02+08:00", - "action": "next-step", - "phase": "task-optimize", - "step": 3, - "summary": "待定项确认完成:用户选择混合模式的目录结构展示", - "git_commit": "8e69ced8b199dd853198abaf880990d3ac3da655" - }, - { - "timestamp": "2025-12-17T01:48:20+08:00", - "action": "next-step", - "phase": "task-optimize", - "step": 4, - "summary": "任务准备完成:生成任务细则", - "git_commit": "af771402cb3b2be934a23b04d352fe2c6d31cc17" - }, - { - "timestamp": "2025-12-17T01:48:33+08:00", - "action": "next-part", - "phase": "flow-design", - "step": 5, - "summary": "进入流程设计环节", - "git_commit": "9ecc7baa8b83e04431f9ff8eb60c69d91c0f916d" - }, - { - "timestamp": "2025-12-17T01:49:30+08:00", - "action": "next-step", - "phase": "flow-design", - "step": 6, - "summary": "流程图设计完成", - "git_commit": "ea06ffee1d1d6b4e5cf6edd5c16e9c391c930ed0" - }, - { - "timestamp": "2025-12-17T01:49:46+08:00", - "action": "next-part", - "phase": "impl", - "step": 7, - "summary": "流程设计完成,进入实现环节", - "git_commit": "65c02dc79796e35a1d3a438b1abaf082382fa832" - }, - { - "timestamp": "2025-12-17T01:51:43+08:00", - "action": "next-step", - "phase": "impl", - "step": 8, - "summary": "完成 docs.md 命令文件修改", - "git_commit": "dfe26eff4370dfcae7513b748d2559737278e71d" - }, - { - "timestamp": "2025-12-17T01:53:11+08:00", - "action": "next-step", - "phase": "impl", - "step": 9, - "summary": "完成 docs/commands/docs.md 设计文档更新", - "git_commit": "f13676c52085470908e857ec577ef2aedf7b52e9" - }, - { - "timestamp": "2025-12-17T01:53:52+08:00", - "action": "next-step", - "phase": "impl", - "step": 10, - "summary": "完成 project-docs 区块文档更新", - "git_commit": "20f2fe21c0ee80b25adb1d755ff33e490db32c30" - }, - { - "timestamp": "2025-12-17T01:54:49+08:00", - "action": "next-step", - "phase": "impl", - "step": 11, - "summary": "完成 CHANGELOG.md 更新", - "git_commit": "b19acd2677772ca5e96058e48b4e61d662e19db1" - }, - { - "timestamp": "2025-12-17T01:55:24+08:00", - "action": "next-part", - "phase": "verify", - "step": 12, - "summary": "实现完成,进入验证环节", - "git_commit": "6ad4416c269d996d0f5a65065a51baa83437e4ad" - }, - { - "timestamp": "2025-12-17T01:56:03+08:00", - "action": "next-step", - "phase": "verify", - "step": 13, - "summary": "验证完成:所有修改点都已正确实现", - "git_commit": "b41a51937d12b9994963478794cbb8f4ce521441" - }, - { - "timestamp": "2025-12-17T01:56:21+08:00", - "action": "next-part", - "phase": "docs", - "step": 14, - "summary": "验证通过,进入文档环节", - "git_commit": "0956b9e8adc19e70173bbb6093498c1f6a13ed83" - }, - { - "timestamp": "2025-12-17T01:56:34+08:00", - "action": "next-step", - "phase": "docs", - "step": 15, - "summary": "文档已在实现阶段同步更新,CHANGELOG.md 已记录变更", - "git_commit": "0029267e913a0eda2557367f7e565df45fba9791" - }, - { - "timestamp": "2025-12-17T01:57:12+08:00", - "action": "next-part", - "phase": "finish", - "step": 16, - "summary": "文档更新完成,进入收尾", - "git_commit": "8cb2f0d7a9bf292a147342462c8fbd2742e85c35" - }, - { - "timestamp": "2025-12-17T01:57:29+08:00", - "action": "next-step", - "phase": "finish", - "step": 17, - "summary": "任务完成" + "summary": "开始任务准备: 优化 docs.md 命令实现完整深度探索" } ] } diff --git a/.aide/flow-status.lock b/.aide/flow-status.lock index 8856730..31c03b9 100755 --- a/.aide/flow-status.lock +++ b/.aide/flow-status.lock @@ -1 +1 @@ -12913 \ No newline at end of file +16647 \ No newline at end of file diff --git a/.aide/logs/flow-status.2025-12-17T01-45-46.json b/.aide/logs/flow-status.2025-12-17T01-45-46.json new file mode 100644 index 0000000..01ea038 --- /dev/null +++ b/.aide/logs/flow-status.2025-12-17T01-45-46.json @@ -0,0 +1,144 @@ +{ + "task_id": "2025-12-17T01-45-46", + "current_phase": "finish", + "current_step": 17, + "started_at": "2025-12-17T01:45:46+08:00", + "history": [ + { + "timestamp": "2025-12-17T01:45:46+08:00", + "action": "start", + "phase": "task-optimize", + "step": 1, + "summary": "开始任务准备: 改进 /aide:docs 命令实现完整项目导览", + "git_commit": "04c2425e6c45a6cbbab44e4cb3d18a41c78d498f" + }, + { + "timestamp": "2025-12-17T01:46:20+08:00", + "action": "next-step", + "phase": "task-optimize", + "step": 2, + "summary": "问题根源分析完成:识别出 5 个核心差距点", + "git_commit": "73bf7b96f402ac6468694a61e6d476cbcdbc9418" + }, + { + "timestamp": "2025-12-17T01:48:02+08:00", + "action": "next-step", + "phase": "task-optimize", + "step": 3, + "summary": "待定项确认完成:用户选择混合模式的目录结构展示", + "git_commit": "8e69ced8b199dd853198abaf880990d3ac3da655" + }, + { + "timestamp": "2025-12-17T01:48:20+08:00", + "action": "next-step", + "phase": "task-optimize", + "step": 4, + "summary": "任务准备完成:生成任务细则", + "git_commit": "af771402cb3b2be934a23b04d352fe2c6d31cc17" + }, + { + "timestamp": "2025-12-17T01:48:33+08:00", + "action": "next-part", + "phase": "flow-design", + "step": 5, + "summary": "进入流程设计环节", + "git_commit": "9ecc7baa8b83e04431f9ff8eb60c69d91c0f916d" + }, + { + "timestamp": "2025-12-17T01:49:30+08:00", + "action": "next-step", + "phase": "flow-design", + "step": 6, + "summary": "流程图设计完成", + "git_commit": "ea06ffee1d1d6b4e5cf6edd5c16e9c391c930ed0" + }, + { + "timestamp": "2025-12-17T01:49:46+08:00", + "action": "next-part", + "phase": "impl", + "step": 7, + "summary": "流程设计完成,进入实现环节", + "git_commit": "65c02dc79796e35a1d3a438b1abaf082382fa832" + }, + { + "timestamp": "2025-12-17T01:51:43+08:00", + "action": "next-step", + "phase": "impl", + "step": 8, + "summary": "完成 docs.md 命令文件修改", + "git_commit": "dfe26eff4370dfcae7513b748d2559737278e71d" + }, + { + "timestamp": "2025-12-17T01:53:11+08:00", + "action": "next-step", + "phase": "impl", + "step": 9, + "summary": "完成 docs/commands/docs.md 设计文档更新", + "git_commit": "f13676c52085470908e857ec577ef2aedf7b52e9" + }, + { + "timestamp": "2025-12-17T01:53:52+08:00", + "action": "next-step", + "phase": "impl", + "step": 10, + "summary": "完成 project-docs 区块文档更新", + "git_commit": "20f2fe21c0ee80b25adb1d755ff33e490db32c30" + }, + { + "timestamp": "2025-12-17T01:54:49+08:00", + "action": "next-step", + "phase": "impl", + "step": 11, + "summary": "完成 CHANGELOG.md 更新", + "git_commit": "b19acd2677772ca5e96058e48b4e61d662e19db1" + }, + { + "timestamp": "2025-12-17T01:55:24+08:00", + "action": "next-part", + "phase": "verify", + "step": 12, + "summary": "实现完成,进入验证环节", + "git_commit": "6ad4416c269d996d0f5a65065a51baa83437e4ad" + }, + { + "timestamp": "2025-12-17T01:56:03+08:00", + "action": "next-step", + "phase": "verify", + "step": 13, + "summary": "验证完成:所有修改点都已正确实现", + "git_commit": "b41a51937d12b9994963478794cbb8f4ce521441" + }, + { + "timestamp": "2025-12-17T01:56:21+08:00", + "action": "next-part", + "phase": "docs", + "step": 14, + "summary": "验证通过,进入文档环节", + "git_commit": "0956b9e8adc19e70173bbb6093498c1f6a13ed83" + }, + { + "timestamp": "2025-12-17T01:56:34+08:00", + "action": "next-step", + "phase": "docs", + "step": 15, + "summary": "文档已在实现阶段同步更新,CHANGELOG.md 已记录变更", + "git_commit": "0029267e913a0eda2557367f7e565df45fba9791" + }, + { + "timestamp": "2025-12-17T01:57:12+08:00", + "action": "next-part", + "phase": "finish", + "step": 16, + "summary": "文档更新完成,进入收尾", + "git_commit": "8cb2f0d7a9bf292a147342462c8fbd2742e85c35" + }, + { + "timestamp": "2025-12-17T01:57:29+08:00", + "action": "next-step", + "phase": "finish", + "step": 17, + "summary": "任务完成", + "git_commit": "3efff299d5c8b53060b5a479b8cf3d758ee3df50" + } + ] +} diff --git a/.aide/project-docs/README.md b/.aide/project-docs/README.md index d178180..087f8f0 100644 --- a/.aide/project-docs/README.md +++ b/.aide/project-docs/README.md @@ -1,89 +1,103 @@ -# Aide 项目导览 +# ccoptimize 项目导览 > 本文档面向 LLM,用于快速了解项目结构和脉络。 -> 最后更新:2025-12-16 +> 最后更新:2025-12-17 ## 项目简介 -Aide 是一套面向 Claude Code 的工作流辅助体系,旨在解决 AI 辅助开发中的信息过载、操作不确定性和流程耦合问题。通过模块化的 Commands、Skills 和命令行工具,帮助开发者更高效地进行 AI 辅助开发。 +ccoptimize 是 Aide 工具的开发项目。Aide 是一套命令行工具集,用于支持 LLM 辅助开发的工作流体系。项目提供环境管理、进度追踪、待定项确认等功能,并通过 Claude Code 插件形式提供斜杠命令和技能定义。 ## 技术栈 -- **语言**:Python 3.11+, Markdown -- **包管理**:uv -- **配置格式**:TOML -- **前端**:原生 HTML/CSS/JS(decide 模块) -- **流程图**:PlantUML +- 语言:Python 3.11+ +- 包管理:uv +- HTTP 服务:Python 标准库(http.server) +- 前端:原生 HTML/CSS/JavaScript +- 配置格式:TOML +- 流程图:PlantUML + +## 项目结构(简化版) + +``` +ccoptimize/ +├── aide-program/ Aide CLI 核心程序 +│ ├── aide/ Python 包 +│ │ ├── core/ 核心模块(配置、输出) +│ │ ├── env/ 环境管理模块 +│ │ ├── flow/ 进度追踪模块 +│ │ └── decide/ 待定项确认模块 +│ ├── bin/ 可执行脚本 +│ ├── docs/ 命令文档 +│ └── lib/ 第三方库 +├── aide-marketplace/ 插件市场组件 +│ └── aide-plugin/ Aide 插件定义 +│ ├── commands/ 斜杠命令 +│ └── skills/ 技能定义 +├── anthropic-agent-skills/ [ignored] 第三方技能库 +├── .aide/ 项目 Aide 配置 +├── .venv/ [ignored] 虚拟环境 +├── cache/ [ignored] 缓存目录 +├── CLAUDE.md Claude 指令 +├── README.md 项目说明 +└── requirements.txt Python 依赖 +``` + +> 详细结构见各区块文档 ## 架构概述 ``` -用户 - │ - ▼ -aide-plugin (Claude Code 插件) - ├── Commands: /aide:setup, /aide:load, /aide:docs, /aide:run - └── Skills: aide, env-config, task-parser - │ - ▼ 调用 -aide-program (命令行工具) - ├── aide init - 初始化配置 - ├── aide env - 环境检测(模块化) - ├── aide config - 配置读写 - ├── aide flow - 进度追踪 + git 集成 - └── aide decide - 待定项 Web 确认 +┌─────────────────────────────────────────────────────────────┐ +│ Claude Code 插件层 │ +├──────────────────────────┬──────────────────────────────────┤ +│ commands/ │ skills/ │ +│ ┌──────────────────┐ │ ┌──────────────────────────┐ │ +│ │ /aide:setup │ │ │ aide (工具使用指南) │ │ +│ │ /aide:load │ │ │ env-config (环境配置) │ │ +│ │ /aide:docs │ │ │ task-parser (任务解析) │ │ +│ │ /aide:run │ │ └──────────────────────────┘ │ +│ └──────────────────┘ │ │ +├─────────────────────────┴───────────────────────────────────┤ +│ Aide CLI 程序层 │ +├──────────┬──────────┬─────────────┬────────────────────────┤ +│ core │ env │ flow │ decide │ +│ 配置管理 │ 环境检测 │ 进度追踪 │ 待定项确认 │ +│ 输出格式 │ 模块注册 │ Git 集成 │ Web 服务 │ +└──────────┴──────────┴─────────────┴────────────────────────┘ ``` ## 区块索引 -| 区块 | 路径 | 说明 | -|------|------|------| -| [aide-program-core](./blocks/aide-program-core.md) | aide-program/aide/core/ | 核心模块(配置、输出) | -| [aide-program-env](./blocks/aide-program-env.md) | aide-program/aide/env/ | 环境检测模块 | -| [aide-program-flow](./blocks/aide-program-flow.md) | aide-program/aide/flow/ | 进度追踪模块 | -| [aide-program-decide](./blocks/aide-program-decide.md) | aide-program/aide/decide/ | 待定项确认模块 | -| [aide-plugin-commands](./blocks/aide-plugin-commands.md) | aide-marketplace/aide-plugin/commands/ | 插件命令 | -| [aide-plugin-skills](./blocks/aide-plugin-skills.md) | aide-marketplace/aide-plugin/skills/ | 插件技能 | +| 区块 | 路径 | 文件数 | 说明 | +|------|------|--------|------| +| [aide-program-core](./blocks/aide-program-core.md) | aide-program/aide/core/ | 6 | 核心配置和输出模块 | +| [aide-program-env](./blocks/aide-program-env.md) | aide-program/aide/env/ | 13 | 环境检测和管理模块 | +| [aide-program-flow](./blocks/aide-program-flow.md) | aide-program/aide/flow/ | 9 | 进度追踪和流程控制模块 | +| [aide-program-decide](./blocks/aide-program-decide.md) | aide-program/aide/decide/ | 10 | 待定项确认 Web 服务模块 | +| [aide-plugin-commands](./blocks/aide-plugin-commands.md) | aide-marketplace/aide-plugin/commands/ | 4 | 斜杠命令定义 | +| [aide-plugin-skills](./blocks/aide-plugin-skills.md) | aide-marketplace/aide-plugin/skills/ | 3 | 技能定义 | ## 快速导航 -- 想了解配置管理 → 查看 [aide-program-core](./blocks/aide-program-core.md) -- 想了解环境检测 → 查看 [aide-program-env](./blocks/aide-program-env.md) -- 想了解进度追踪 → 查看 [aide-program-flow](./blocks/aide-program-flow.md) -- 想了解待定项确认 → 查看 [aide-program-decide](./blocks/aide-program-decide.md) -- 想了解插件命令 → 查看 [aide-plugin-commands](./blocks/aide-plugin-commands.md) -- 想了解插件技能 → 查看 [aide-plugin-skills](./blocks/aide-plugin-skills.md) +- 想了解 aide 命令实现 → 查看 [aide-program-core](./blocks/aide-program-core.md) +- 想修改环境检测逻辑 → 查看 [aide-program-env](./blocks/aide-program-env.md) +- 想修改进度追踪功能 → 查看 [aide-program-flow](./blocks/aide-program-flow.md) +- 想修改待定项确认界面 → 查看 [aide-program-decide](./blocks/aide-program-decide.md) +- 想新增斜杠命令 → 查看 [aide-plugin-commands](./blocks/aide-plugin-commands.md) +- 想新增技能定义 → 查看 [aide-plugin-skills](./blocks/aide-plugin-skills.md) -## 核心数据文件 +## 核心命令体系 -| 文件 | 说明 | -|------|------| -| `.aide/config.toml` | 项目配置(自文档化) | -| `.aide/flow-status.json` | 当前任务进度 | -| `.aide/decisions/` | 待定项决策记录 | -| `.aide/logs/` | 历史任务归档 | -| `.aide/diagrams/` | 流程图目录 | +| 命令 | 说明 | 独立运行 | +|------|------|----------| +| `/aide:setup` | 环境配置(分析、检测、修复) | 是 | +| `/aide:load` | 项目认知载入 | 否(由 run 调用) | +| `/aide:docs` | 项目文档创建和维护 | 是 | +| `/aide:run` | 任务执行(核心命令) | 是 | -## 标准工作流程 +## 统计信息 -1. **task-optimize** - 任务优化:分析任务、识别待定项、口语化内容解析 -2. **flow-design** - 流程设计:创建 PlantUML 流程图(任务流程图 + 程序逻辑流图) -3. **impl** - 迭代实现:按计划执行 -4. **verify** - 验证交付:对照任务细则验证 -5. **docs** - 文档更新:更新相关文档 -6. **finish** - 收尾:清理临时文件、汇报完成 - -## 最近更新(2025-12-16) - -- 新增 `task-parser` skill:口语化任务内容解析 -- 强化流程图规范:区分任务执行流程图和程序逻辑流图 -- 优化 `aide flow` git 提交顺序:状态先保存再提交 - -## 输出格式约定 - -| 前缀 | 含义 | -|------|------| -| `✓` | 成功 | -| `⚠` | 警告(可继续) | -| `✗` | 错误(需处理) | -| `→` | 进行中/信息 | +- 总目录数:约 50(核心项目) +- 总文件数:约 45(核心项目) +- 被忽略项:anthropic-agent-skills、.venv、cache、__pycache__ +- 代码行数:约 5000 行(核心项目) diff --git a/.aide/project-docs/block-plan.md b/.aide/project-docs/block-plan.md index 8b49a3f..c347aac 100644 --- a/.aide/project-docs/block-plan.md +++ b/.aide/project-docs/block-plan.md @@ -1,57 +1,108 @@ # 区块计划 ## 项目概况 -- 项目名称:Aide -- 主要语言:Python, Markdown -- aide-program 代码行数:~4100 行 -- 项目阶段:设计完成,核心功能已实现 + +- 项目名称:ccoptimize(Aide 工具开发项目) +- 主要语言:Python 3.14 +- 框架/工具:uv 虚拟环境管理 +- 文件总数:约 200(核心项目,排除第三方) +- 空目录数:约 10 +- 代码行数:约 5000 行(核心项目) + +## 完整目录树(简化版) + +``` +ccoptimize/ +├── .aide/ 项目 Aide 配置 +│ ├── config.toml +│ ├── diagrams/ +│ ├── flow-status.json +│ └── logs/ +├── aide-program/ Aide CLI 核心程序 +│ ├── aide/ Python 包 +│ ├── bin/ 可执行脚本 +│ ├── docs/ 命令文档 +│ └── lib/ 第三方库 +├── aide-marketplace/ 插件市场组件 +│ └── aide-plugin/ Aide 插件 +├── anthropic-agent-skills/ [ignored] 第三方技能库 +├── cache/ [ignored] 缓存目录 +├── .cache/ [ignored] 缓存目录 +├── .venv/ [ignored] 虚拟环境 +├── test-cache/ [ignored] 测试缓存 +├── discuss/ 讨论文档目录 +├── docs/ 项目文档 +├── reply/ 回复文档目录 +├── statements/ 声明文档目录 +├── AGENTS.md +├── CHANGELOG.md +├── CLAUDE.md +├── README.md +├── requirements.txt +└── task-now.md +``` ## 区块划分 ### 区块 1:aide-program-core + - 路径:aide-program/aide/core/ -- 文件数:3 -- 说明:核心模块(配置管理、输出格式) +- 文件数:约 5 +- 空目录:0 - 状态:待处理 +- 说明:Aide 核心配置和输出模块 ### 区块 2:aide-program-env + - 路径:aide-program/aide/env/ -- 文件数:12 -- 说明:环境检测模块(python, uv, node, rust 等) +- 文件数:约 15 +- 空目录:0 - 状态:待处理 +- 说明:环境检测和管理模块 ### 区块 3:aide-program-flow + - 路径:aide-program/aide/flow/ -- 文件数:9 -- 说明:进度追踪模块(含 Git 集成) +- 文件数:约 10 +- 空目录:0 - 状态:待处理 +- 说明:进度追踪和流程控制模块 ### 区块 4:aide-program-decide + - 路径:aide-program/aide/decide/ -- 文件数:11 -- 说明:待定项确认模块(Web 界面) +- 文件数:约 12 +- 空目录:0 - 状态:待处理 +- 说明:待定项确认 Web 服务模块 ### 区块 5:aide-plugin-commands + - 路径:aide-marketplace/aide-plugin/commands/ -- 文件数:4 -- 说明:插件斜杠命令(setup, load, docs, run) +- 文件数:约 8 +- 空目录:0 - 状态:待处理 +- 说明:Aide 插件斜杠命令定义 ### 区块 6:aide-plugin-skills + - 路径:aide-marketplace/aide-plugin/skills/ -- 文件数:2 -- 说明:插件技能(aide, env-config) +- 文件数:约 5 +- 空目录:0 - 状态:待处理 +- 说明:Aide 插件技能定义 ## 进度追踪 -- [x] 区块 1: aide-program-core -- [x] 区块 2: aide-program-env -- [x] 区块 3: aide-program-flow -- [x] 区块 4: aide-program-decide -- [x] 区块 5: aide-plugin-commands -- [x] 区块 6: aide-plugin-skills + +- [x] 区块 1:aide-program-core +- [x] 区块 2:aide-program-env +- [x] 区块 3:aide-program-flow +- [x] 区块 4:aide-program-decide +- [x] 区块 5:aide-plugin-commands +- [x] 区块 6:aide-plugin-skills +- [x] 总导览文档 ## 更新记录 -- 2025-12-15:完成所有区块文档和总导览 -- 2025-12-15:初始化区块计划 + +- 2025-12-17:创建区块计划 +- 2025-12-17:完成所有区块文档和总导览 diff --git a/.aide/project-docs/blocks/aide-plugin-commands.md b/.aide/project-docs/blocks/aide-plugin-commands.md index 10e9b58..6a85197 100644 --- a/.aide/project-docs/blocks/aide-plugin-commands.md +++ b/.aide/project-docs/blocks/aide-plugin-commands.md @@ -1,97 +1,128 @@ # aide-plugin-commands > 路径:aide-marketplace/aide-plugin/commands/ -> 最后更新:2025-12-16 +> 最后更新:2025-12-17 ## 概述 -Aide 插件的斜杠命令定义,是面向 LLM 的执行指令文件。 +Aide 插件的斜杠命令定义。每个 Markdown 文件定义一个命令,文件内容作为 LLM 的提示词展开。命令通过 `/aide:命令名` 方式调用。 + +## 目录结构 + +``` +aide-marketplace/aide-plugin/commands/ +├── docs.md 项目文档管理命令 +├── load.md 项目认知载入命令 +├── run.md 任务执行命令(核心) +└── setup.md 环境配置命令 +``` ## 文件清单 -| 文件 | 说明 | -|------|------| -| `setup.md` | `/aide:setup` - 环境配置命令 | -| `load.md` | `/aide:load` - 项目认知载入 | -| `docs.md` | `/aide:docs` - 项目文档管理 | -| `run.md` | `/aide:run` - 任务执行(核心命令) | +| 文件 | 类型 | 说明 | +|------|------|------| +| docs.md | 命令 | `/aide:docs` - 项目文档创建和维护 | +| load.md | 命令 | `/aide:load` - 项目认知载入 | +| run.md | 命令 | `/aide:run` - 任务执行(核心命令) | +| setup.md | 命令 | `/aide:setup` - 环境配置 | -## 命令说明 +## 命令详解 -### /aide:setup +### /aide:docs - 项目文档管理 -- **用途**:环境配置(独立运行) -- **触发 skill**:env-config -- **流程**: - 1. 检查 aide 运行时环境 - 2. 初始化 .aide 目录 - 3. 分析项目依赖 - 4. 配置环境模块 - 5. 执行环境检测 +- **功能**:创建和维护面向 LLM 的完整深度项目文档 +- **独立运行**:是 +- **核心原则**:完全深度探索,不遗漏任何文件或目录 -### /aide:load +**流程**: +1. 创建流程: + - 完整目录扫描 + - 初步区块划分 + - 区块验证 + - 逐区块深度探索 + - 生成总导览 +2. 更新流程: + - 读取区块计划 + - 重新扫描目录 + - 分区块验证 + - 增量更新 -- **用途**:项目认知载入(由 run 调用) -- **触发 skill**:aide -- **流程**: - 1. 检查项目文档配置 - 2. 载入总导览 - 3. 建立脉络认知 - 4. 按需深入 +### /aide:load - 项目认知载入 -### /aide:docs +- **功能**:按需载入项目文档,建立对项目的认知 +- **独立运行**:否(由 `/aide:run` 调用) -- **用途**:项目文档创建和维护(独立运行) -- **触发 skill**:aide -- **核心原则**:完全深度探索,不考虑效率,对每个文件/目录完全覆盖 -- **流程**: - - 创建流程:完整目录扫描 → 生成 tree 结构 → 区块划分 → 逐区块完全深度探索 → 生成总导览 - - 更新流程:读取区块计划 → 重新扫描目录 → 分区块验证 → 增量更新 -- **文档格式**: - - 总导览:简化版目录结构(前两层)+ 区块索引 + 统计信息 - - 子区块:完整 tree 结构 + 每文件概括 + 核心组件说明 +**流程**: +1. 载入总导览 +2. 建立脉络认知 +3. 按需深入(根据任务) -### /aide:run +**无文档时**:快速认知(阅读关键文件、探索目录结构) -- **用途**:任务执行(核心命令) -- **触发 skill**:aide, task-parser(按需) -- **新增功能**: - - 口语化内容检测:在任务分析前检测内容特征 - - 自动触发 task-parser skill 解析口语化内容 - - 流程图规范:区分任务执行流程图和程序逻辑流图 -- **标准流程**: - 1. task-optimize - 任务准备(含口语化检测) - 2. flow-design - 流程设计(含流程图规范) - 3. impl - 迭代实现 - 4. verify - 验证交付 - 5. docs - 文档更新 - 6. finish - 收尾 +### /aide:run - 任务执行 -## 流程图要求 +- **功能**:核心命令,整合任务准备和任务执行 +- **独立运行**:是 +- **参数**:任务文档路径(可选) -### 任务执行流程图(所有任务必需) -- 展示任务执行的步骤顺序 -- 体现决策点和依赖关系 +**流程阶段**: +1. **task-optimize**:任务准备 + - 口语化内容检测 + - 任务分析 + - 复杂度评估 + - 任务优化 + - 待定项处理 + - 生成任务细则 +2. **flow-design**:流程设计 + - 制定执行计划 + - 创建流程图(任务执行流程图、程序逻辑流图) +3. **impl**:迭代实现 +4. **verify**:验证交付 +5. **docs**:文档更新 +6. **finish**:收尾 -### 程序逻辑流图(程序类任务必需) -- 从入口函数开始 -- 体现顺序/分支/循环结构 -- 语义化抽象,模块化表示 -- 支持层次化组织 +**复杂任务**:拆分为子计划,循环执行 flow-design → impl → verify → docs -## 设计原则 +### /aide:setup - 环境配置 -- 执行文件给 LLM 看,聚焦执行指令 -- 设计文档给人看,包含完整上下文 -- 每个命令开始时触发对应的 skill 学习必要知识 +- **功能**:环境依赖分析、配置、检测和修复 +- **独立运行**:是 + +**流程**: +1. 检查 aide 运行时环境 +2. 初始化 aide 目录 +3. 分析项目依赖 +4. 配置环境模块 +5. 执行环境检测 +6. 处理问题 + +## 接口说明 + +### 命令调用方式 + +```bash +# 项目文档管理 +/aide:docs + +# 项目认知载入(通常由 run 自动调用) +/aide:load + +# 任务执行 +/aide:run [任务文档路径] + +# 环境配置 +/aide:setup +``` ## 依赖关系 -- 依赖:aide skill, env-config skill, task-parser skill -- 调用:aide 命令行工具 +- 依赖:aide skill(aide 命令使用方法) +- 依赖:env-config skill(环境配置指导) +- 依赖:task-parser skill(口语化内容解析) ## 注意事项 -- `/aide:setup` 和 `/aide:docs` 是独立运行的命令 -- `/aide:load` 通常由 `/aide:run` 内部调用 -- `/aide:run` 是最常用的核心命令 +- 命令文件使用 Markdown 格式,内容作为 LLM 提示词 +- `/aide:run` 是核心命令,其他命令可独立运行 +- `/aide:load` 通常由 `/aide:run` 自动调用 +- 流程图是必需的,用于规范化思考和早期发现错误 diff --git a/.aide/project-docs/blocks/aide-plugin-skills.md b/.aide/project-docs/blocks/aide-plugin-skills.md index 8baacaf..9c6c4f3 100644 --- a/.aide/project-docs/blocks/aide-plugin-skills.md +++ b/.aide/project-docs/blocks/aide-plugin-skills.md @@ -1,70 +1,98 @@ # aide-plugin-skills > 路径:aide-marketplace/aide-plugin/skills/ -> 最后更新:2025-12-16 +> 最后更新:2025-12-17 ## 概述 -Aide 插件的技能定义,提供专门知识供 LLM 按需学习。 +Aide 插件的技能定义。每个技能是一个独立目录,包含 SKILL.md 文件作为技能知识库。技能通过 Skill 工具触发,为 LLM 提供专业领域的知识和指导。 + +## 目录结构 + +``` +aide-marketplace/aide-plugin/skills/ +├── aide/ +│ └── SKILL.md Aide 命令使用指南 +├── env-config/ +│ └── SKILL.md 环境配置详细指南 +└── task-parser/ + └── SKILL.md 口语化内容解析指南 +``` ## 文件清单 -| 目录 | 说明 | -|------|------| -| `aide/SKILL.md` | aide 基础命令指南(始终加载) | -| `env-config/SKILL.md` | 环境配置详细指南(按需触发) | -| `task-parser/SKILL.md` | 口语化任务内容解析(按需触发) | +| 文件 | 类型 | 说明 | +|------|------|------| +| aide/SKILL.md | 技能 | Aide CLI 工具完整使用指南 | +| env-config/SKILL.md | 技能 | 环境配置和故障排除指南 | +| task-parser/SKILL.md | 技能 | 口语化任务内容解析方法 | -## 技能说明 +## 技能详解 -### aide skill +### aide - Aide 工具使用指南 -- **触发方式**:始终加载 -- **内容**: - - aide 命令行工具的完整使用指南 - - 所有子命令的参数说明和示例 - - 输出格式说明(✓/⚠/✗/→) +- **触发描述**:Aide 工作流工具集。提供环境管理、进度追踪、待定项确认等功能。 +- **内容覆盖**: + - `aide env` - 环境管理命令 + - `aide flow` - 进度追踪命令 + - `aide decide` - 待定项确认命令 + - `aide config` - 配置管理命令 + - `aide init` - 初始化命令 - 数据存储结构 - 常见用法示例 -### env-config skill +### env-config - 环境配置指南 -- **触发方式**:当 `aide env ensure` 失败时按需触发 -- **内容**: - - 环境模块详细配置方法 - - 各模块的配置项说明 - - 多项目场景处理 - - 故障排除指南 +- **触发描述**:环境配置详细指南。由 `/aide:setup` 命令强制触发。 +- **触发条件**:当 `aide env ensure` 检测失败时 +- **内容覆盖**: + - 问题诊断(常见失败原因) + - 模块分类(类型A/类型B) + - 配置命令使用 + - 项目类型配置示例 + - 多项目场景处理(模块实例化命名) + - node_deps 模块详解 + - 故障排除 -### task-parser skill +### task-parser - 口语化内容解析器 -- **触发方式**:当任务文档或用户对话具有明显口语化特征时触发 -- **内容**: - - 口语化内容识别标准 - - 语义解析方法(表层理解、深层提取、结构重组) - - 批判性分析(逻辑漏洞、盲点、过度设计) - - 建设性优化建议 - - 上下文关联分析 - - 规范化输出格式 +- **触发描述**:口语化任务内容解析器。当发现用户对话或任务文档具有明显口头语气时使用。 +- **触发条件**:内容具有口语化特征(模糊表述、松散结构、思维跳跃等) +- **解析流程**: + 1. 语义解析(表层理解、深层提取、结构重组) + 2. 批判性分析(逻辑漏洞、盲点识别、过度设计识别) + 3. 建设性优化(优化建议、方案对比、风险权衡) + 4. 上下文关联分析(项目关联、隐含需求、复杂度预判) -## 设计理念 +## 接口说明 -**Skill 拆分原则**: -- `aide` skill:基础知识,始终需要 -- `env-config` skill:专门知识,仅在配置环境时需要 -- `task-parser` skill:专门知识,仅在解析口语化内容时需要 +### 技能文件格式 -这样设计的好处: -1. 减少 LLM 上下文占用 -2. 按需加载专门知识 -3. 职责分离,便于维护 +每个 SKILL.md 文件包含 YAML 前置元数据: + +```yaml +--- +name: 技能名称 +description: 技能描述(用于触发匹配) +--- + +# 技能内容 +... +``` + +### 技能触发方式 + +技能通过 Skill 工具自动触发: +- LLM 根据任务场景匹配合适的技能 +- 触发后技能内容作为上下文提供给 LLM ## 依赖关系 -- 被依赖:commands(setup, load, docs, run) +- 被依赖:aide-plugin commands(命令中引用技能) ## 注意事项 -- Skill 文件是 Markdown 格式 -- 内容应聚焦于 LLM 执行任务所需的知识 -- 避免冗余,保持简洁 +- 技能文件使用 Markdown 格式,内容作为 LLM 知识库 +- YAML 前置元数据中的 description 用于技能匹配 +- 技能应专注于单一领域,提供完整但聚焦的指导 +- 技能之间可以相互引用(如 aide skill 引用 env-config skill) diff --git a/.aide/project-docs/blocks/aide-program-core.md b/.aide/project-docs/blocks/aide-program-core.md index 61ae1b9..69b9390 100644 --- a/.aide/project-docs/blocks/aide-program-core.md +++ b/.aide/project-docs/blocks/aide-program-core.md @@ -1,67 +1,118 @@ # aide-program-core -> 路径:aide-program/aide/core/ -> 最后更新:2025-12-15 +> 路径:aide-program/aide/core/ 及 aide-program/aide/ +> 最后更新:2025-12-17 ## 概述 -核心模块,提供配置管理和输出格式化功能,是所有其他模块的基础依赖。 +Aide CLI 工具的核心模块,包含配置管理、输出格式化和命令行入口。本区块是整个 aide 程序的基础设施层,被所有其他模块依赖。 + +## 目录结构 + +``` +aide-program/aide/ +├── __init__.py 包初始化 +├── __main__.py 模块入口 +├── main.py 命令行主入口 +└── core/ + ├── __init__.py 核心模块初始化 + ├── config.py 配置管理 + └── output.py 输出格式工具 +``` ## 文件清单 -| 文件 | 说明 | -|------|------| -| `__init__.py` | 模块初始化,导出 output | -| `config.py` | 配置管理器(~390 行) | -| `output.py` | 统一输出格式(25 行) | +| 文件 | 类型 | 说明 | +|------|------|------| +| aide/__init__.py | 源码 | 包初始化,定义包描述 | +| aide/__main__.py | 源码 | 模块入口,支持 `python -m aide` | +| aide/main.py | 源码 | 命令行主入口,解析参数并分发命令 | +| core/__init__.py | 源码 | 核心模块初始化,定义模块描述 | +| core/config.py | 源码 | 配置管理器,处理 TOML 配置 | +| core/output.py | 源码 | 输出格式工具,统一输出前缀 | ## 核心组件 -### ConfigManager +### ConfigManager 类 -- **职责**:管理 `.aide/config.toml` 配置文件 -- **位置**:`config.py:240` +- **职责**:管理 .aide 目录和 config.toml 配置文件 +- **位置**:`aide/core/config.py:240` - **关键方法**: - - `ensure_config()` - 确保配置文件存在,不存在则创建默认配置 - - `load_config()` - 加载配置(返回 dict) - - `get_value(key)` - 获取配置值(支持点号分隔的键) - - `set_value(key, value)` - 设置配置值(保留注释和格式) - - `ensure_gitignore()` - 根据配置决定是否忽略 .aide 目录 + - `ensure_base_dirs()` - 创建 .aide 目录结构 + - `ensure_gitignore()` - 根据配置更新 .gitignore + - `ensure_config()` - 确保配置文件存在 + - `load_config()` - 加载 TOML 配置 + - `get_value(key)` - 读取配置值(支持点号分隔键) + - `set_value(key, value)` - 设置配置值(保留注释) + - `_update_config_value()` - 保守更新配置,保留原文件注释 ### DEFAULT_CONFIG -- **职责**:默认配置模板(自文档化,含完整注释) -- **位置**:`config.py:13` -- **特点**: - - 包含所有配置节的详细说明 - - 用户可仅通过此文件了解所有支持的功能 - - 约 230 行注释文档 +- **职责**:默认配置模板,包含完整注释说明 +- **位置**:`aide/core/config.py:13-237` +- **配置节**: + - `[general]` - 通用配置(gitignore_aide) + - `[runtime]` - 运行时要求(python_min, use_uv) + - `[task]` - 任务文档路径(source, spec) + - `[env]` - 环境检测模块配置 + - `[docs]` - 项目文档配置 + - `[flow]` - 流程追踪配置 + - `[plantuml]` - PlantUML 工具配置 + - `[decide]` - 待定项确认配置 ### output 模块 - **职责**:统一输出格式 -- **位置**:`output.py` -- **输出函数**: - - `ok(msg)` → `✓ {msg}` 成功 - - `warn(msg)` → `⚠ {msg}` 警告 - - `err(msg)` → `✗ {msg}` 错误 - - `info(msg)` → `→ {msg}` 信息 - - `step(msg, current, total)` → `[n/m] {msg}` 步骤 +- **位置**:`aide/core/output.py` +- **函数**: + - `ok(msg)` - 成功输出(✓ 前缀) + - `warn(msg)` - 警告输出(⚠ 前缀) + - `err(msg)` - 错误输出(✗ 前缀) + - `info(msg)` - 信息输出(→ 前缀) + - `step(msg, current, total)` - 步骤输出([n/m] 前缀) + +### main() 函数 + +- **职责**:命令行入口,构建解析器并分发命令 +- **位置**:`aide/main.py:16` +- **支持的命令**: + - `aide init` - 初始化 .aide 目录 + - `aide env {ensure|list|set}` - 环境管理 + - `aide config {get|set}` - 配置管理 + - `aide flow {start|next-step|back-step|next-part|back-part|issue|error|status|list|show}` - 进度追踪 + - `aide decide {submit|result}` - 待定项确认 ## 接口说明 -被所有其他模块依赖: +### 配置读写 API + +```python +from aide.core.config import ConfigManager + +cfg = ConfigManager(Path.cwd()) +cfg.ensure_config() # 确保配置存在 +value = cfg.get_value("env.venv.path") # 读取嵌套键 +cfg.set_value("task.source", "my-task.md") # 设置值 +``` + +### 输出格式 API + ```python from aide.core import output -from aide.core.config import ConfigManager + +output.ok("操作成功") # ✓ 操作成功 +output.warn("警告信息") # ⚠ 警告信息 +output.err("错误信息") # ✗ 错误信息 +output.info("提示信息") # → 提示信息 ``` ## 依赖关系 -- 依赖:标准库 + tomllib + tomli_w -- 被依赖:env, flow, decide, main +- 依赖:tomllib(标准库)、tomli_w(第三方) +- 被依赖:aide/env、aide/flow、aide/decide ## 注意事项 -- `set_value()` 使用正则表达式保守更新配置,保留注释 -- 配置键不存在时会回退到完全重写(丢失注释) +- `set_value()` 使用正则替换保留原文件注释格式 +- 配置键支持点号分隔的嵌套访问(如 `env.venv.path`) +- 新增配置键时会回退到完全重写模式(丢失注释) diff --git a/.aide/project-docs/blocks/aide-program-decide.md b/.aide/project-docs/blocks/aide-program-decide.md index d91f3ea..1ef108e 100644 --- a/.aide/project-docs/blocks/aide-program-decide.md +++ b/.aide/project-docs/blocks/aide-program-decide.md @@ -1,100 +1,187 @@ # aide-program-decide > 路径:aide-program/aide/decide/ -> 最后更新:2025-12-15 +> 最后更新:2025-12-17 ## 概述 -待定项确认模块,提供 Web 界面让用户对任务中的待定项进行决策。服务在后台运行,用户提交后自动关闭。 +待定项确认模块,提供 Web 界面让用户对任务中的待定项进行决策。采用后台服务模式,支持 JSON 数据输入、Web UI 交互和决策结果输出。 + +## 目录结构 + +``` +aide-program/aide/decide/ +├── __init__.py 模块入口 +├── types.py 数据结构与校验 +├── errors.py 错误类型 +├── cli.py CLI 入口 +├── storage.py 数据读写与管理 +├── daemon.py 后台服务入口点 +├── server.py HTTP 服务器管理 +├── handlers.py HTTP 请求处理 +└── web/ + ├── index.html Web 界面 HTML + ├── style.css CSS 样式 + └── app.js 前端 JavaScript +``` ## 文件清单 -| 文件 | 说明 | -|------|------| -| `__init__.py` | 模块初始化,导出 cmd 函数 | -| `cli.py` | CLI 入口(~134 行) | -| `server.py` | HTTP 服务器管理(~280 行) | -| `daemon.py` | 后台进程启动器(~30 行) | -| `handlers.py` | HTTP 请求处理器(~170 行) | -| `storage.py` | 数据存储(~155 行) | -| `types.py` | 数据结构定义(~300 行) | -| `errors.py` | 自定义异常 | -| `web/` | Web 前端资源 | +| 文件 | 类型 | 说明 | +|------|------|------| +| __init__.py | 源码 | 模块入口,导出 CLI 函数 | +| types.py | 源码 | 数据类定义(DecideInput、DecideOutput 等) | +| errors.py | 源码 | DecideError 异常类 | +| cli.py | 源码 | CLI 命令处理(submit、result) | +| storage.py | 源码 | DecideStorage 类,数据读写与归档 | +| daemon.py | 源码 | 后台服务入口点,供 subprocess 启动 | +| server.py | 源码 | DecideServer 类,HTTP 服务生命周期 | +| handlers.py | 源码 | DecideHandlers 类,HTTP 路由和处理 | +| web/index.html | HTML | Web 界面结构 | +| web/style.css | CSS | 响应式样式定义 | +| web/app.js | JavaScript | 前端交互逻辑 | ## 核心组件 -### CLI 入口 +### DecideStorage 类 -- **职责**:解析参数并调度功能 -- **位置**:`cli.py` -- **关键函数**: - - `cmd_decide_submit(file_path)` - 提交待定项数据 - - `cmd_decide_result()` - 获取决策结果 +- **职责**:管理 pending.json、决策记录和服务状态 +- **位置**:`aide/decide/storage.py:16` +- **关键方法**: + - `save_pending(data)` - 保存待定项数据并生成 session_id + - `load_pending()` - 读取待定项 + - `save_result(output)` - 保存决策结果为历史记录 + - `load_result()` - 读取当前会话的决策结果 + - `save_server_info()` - 保存服务状态信息 + - `is_server_running()` - 检查服务是否运行中 -### DecideServer +### DecideServer 类 - **职责**:HTTP 服务器生命周期管理 -- **位置**:`server.py:26` +- **位置**:`aide/decide/server.py:26` - **关键方法**: - `start()` - 前台启动服务 - `start_daemon(pid)` - 后台启动服务 - `stop(reason)` - 停止服务 + - `_find_available_port()` - 自动探测可用端口 + - `_serve_forever()` - 服务循环 -### DecideStorage +### DecideHandlers 类 -- **职责**:管理待定项和决策结果的存储 -- **位置**:`storage.py` +- **职责**:HTTP 请求路由和处理 +- **位置**:`aide/decide/handlers.py:17` - **关键方法**: - - `save_pending(input)` - 保存待定项到 pending.json - - `load_pending()` - 加载待定项 - - `save_result(result)` - 保存决策结果 - - `load_result()` - 加载决策结果 - - `is_server_running()` - 检查服务是否运行 + - `handle(method, path, body)` - 请求分发 + - `handle_get_items()` - GET /api/items + - `handle_submit(body)` - POST /api/submit + - `_validate_decisions()` - 验证决策数据完整性 -### 数据结构 +### DecideInput 数据类 -- `DecideInput` - 待定项输入数据 -- `DecideItem` - 单个待定项(含多个选项) -- `DecideOption` - 选项(value, label, score, pros, cons) -- `DecideResult` - 决策结果 -- `DecidedItem` - 单个决策(chosen, note) +- **职责**:待定项输入数据封装 +- **位置**:`aide/decide/types.py:151` +- **字段**: + - `task: str` - 任务名称 + - `source: str` - 来源文件 + - `items: list[DecideItem]` - 待定项列表 + - `meta: MetaInfo | None` - 元信息(session_id、created_at) + +### DecideItem 数据类 + +- **职责**:单个待定项封装 +- **位置**:`aide/decide/types.py:66` +- **字段**: + - `id: int` - 项目 ID + - `title: str` - 标题 + - `options: list[Option]` - 选项列表 + - `location: Location | None` - 位置信息 + - `context: str | None` - 上下文 + - `recommend: str | None` - 推荐选项值 + +### Option 数据类 + +- **职责**:选项封装 +- **位置**:`aide/decide/types.py:31` +- **字段**: + - `value: str` - 选项值 + - `label: str` - 显示标签 + - `score: float | None` - 评分(0-100) + - `pros: list[str] | None` - 优点列表 + - `cons: list[str] | None` - 缺点列表 + +## API 接口 + +### REST API + +| 方法 | 路径 | 说明 | +|------|------|------| +| GET | /api/items | 获取待定项数据 | +| POST | /api/submit | 提交决策结果 | +| GET | / | Web 界面 HTML | +| GET | /style.css | CSS 样式 | +| GET | /app.js | JavaScript | + +### 数据格式 + +**输入格式(submit 命令):** +```json +{ + "task": "任务名称", + "source": "task-now.md", + "items": [ + { + "id": 1, + "title": "问题标题", + "options": [ + {"value": "a", "label": "选项A", "score": 85, "pros": ["优点1"], "cons": ["缺点1"]}, + {"value": "b", "label": "选项B"} + ], + "recommend": "a", + "context": "问题背景", + "location": {"file": "task.md", "start": 5, "end": 7} + } + ] +} +``` + +**输出格式(result 命令):** +```json +{ + "decisions": [ + {"id": 1, "chosen": "a", "note": "用户备注"} + ] +} +``` ## 接口说明 -```python -# CLI 入口 -aide decide submit # 提交待定项,启动后台服务 -aide decide result # 获取决策结果 +### CLI 使用 -# Web 界面 -GET / # 主页面 -GET /api/data # 获取待定项数据 -POST /api/submit # 提交决策 +```bash +# 提交待定项,启动 Web 服务 +aide decide submit ./pending-items.json + +# 获取决策结果 +aide decide result ``` -## 配置项 +### 配置项 -在 `.aide/config.toml` 的 `[decide]` 节: - -| 配置项 | 默认值 | 说明 | -|--------|--------|------| -| `port` | 3721 | 起始端口 | -| `bind` | 127.0.0.1 | 监听地址 | -| `url` | "" | 自定义访问地址 | -| `timeout` | 0 | 超时时间(秒) | - -## 数据文件 - -- `.aide/decisions/pending.json` - 当前待定项数据 -- `.aide/decisions/{timestamp}.json` - 决策记录归档 +在 `[decide]` 节: +- `port` - 起始端口(默认 3721) +- `bind` - 监听地址(默认 127.0.0.1) +- `url` - 自定义访问地址 +- `timeout` - 超时时间(秒,0 表示不超时) ## 依赖关系 -- 依赖:core(output, config) -- 被依赖:main.py +- 依赖:aide/core(ConfigManager、output)、aide/flow/utils(now_task_id) +- 被依赖:aide/main.py ## 注意事项 -- 服务作为后台进程运行,与 CLI 脱离 -- 用户提交决策后服务自动关闭 -- 如果 recommend 字段存在,对应选项默认选中 +- 服务以后台进程运行,用户提交后自动关闭 +- 决策记录保存在 .aide/decisions/{session_id}.json +- Web 界面支持响应式设计,移动端友好 +- 支持推荐选项默认选中 +- 选项的 value 在同一待定项中必须唯一 diff --git a/.aide/project-docs/blocks/aide-program-env.md b/.aide/project-docs/blocks/aide-program-env.md index fe05a85..13104f1 100644 --- a/.aide/project-docs/blocks/aide-program-env.md +++ b/.aide/project-docs/blocks/aide-program-env.md @@ -1,93 +1,163 @@ # aide-program-env > 路径:aide-program/aide/env/ -> 最后更新:2025-12-15 +> 最后更新:2025-12-17 ## 概述 -环境检测模块,提供模块化的开发环境检测和修复功能。支持多种语言和工具,以及模块实例化(多项目场景)。 +环境检测和管理模块,负责检测和修复开发环境。采用插件式架构,支持多种开发环境的检测。模块分为两类:类型A(全局工具,无需配置)和类型B(项目级,需要配置路径)。 + +## 目录结构 + +``` +aide-program/aide/env/ +├── __init__.py 模块初始化 +├── manager.py 环境管理器 +├── registry.py 模块注册表 +└── modules/ + ├── __init__.py 模块集合初始化 + ├── base.py 模块基类定义 + ├── python.py Python 解释器检测 + ├── uv.py uv 包管理器检测 + ├── venv.py 虚拟环境管理 + ├── requirements.py Python 依赖管理 + ├── rust.py Rust 工具链检测 + ├── node.py Node.js 运行时检测 + ├── node_deps.py Node.js 项目依赖 + ├── flutter.py Flutter SDK 检测 + └── android.py Android SDK 检测 +``` ## 文件清单 -| 文件 | 说明 | -|------|------| -| `__init__.py` | 模块初始化 | -| `manager.py` | 环境管理器(~374 行) | -| `registry.py` | 模块注册表(~55 行) | -| `modules/base.py` | 模块基类定义(~90 行) | -| `modules/python.py` | Python 检测模块 | -| `modules/uv.py` | uv 包管理器检测 | -| `modules/venv.py` | Python 虚拟环境检测 | -| `modules/requirements.py` | Python 依赖检测 | -| `modules/rust.py` | Rust 工具链检测 | -| `modules/node.py` | Node.js 检测 | -| `modules/flutter.py` | Flutter SDK 检测 | -| `modules/android.py` | Android SDK 检测 | -| `modules/node_deps.py` | Node.js 项目依赖检测 | +| 文件 | 类型 | 说明 | +|------|------|------| +| __init__.py | 源码 | 模块初始化 | +| manager.py | 源码 | EnvManager 类,环境检测核心逻辑 | +| registry.py | 源码 | ModuleRegistry 注册表,管理所有检测模块 | +| modules/base.py | 源码 | BaseModule 基类和数据类定义 | +| modules/python.py | 源码 | Python 版本检测(类型A) | +| modules/uv.py | 源码 | uv 包管理器检测(类型A) | +| modules/venv.py | 源码 | 虚拟环境检测/创建(类型B) | +| modules/requirements.py | 源码 | Python 依赖检测/安装(类型B) | +| modules/rust.py | 源码 | Rust 工具链检测(类型A) | +| modules/node.py | 源码 | Node.js 运行时检测(类型A) | +| modules/node_deps.py | 源码 | Node.js 依赖检测/安装(类型B) | +| modules/flutter.py | 源码 | Flutter SDK 检测(类型A) | +| modules/android.py | 源码 | Android SDK 检测(类型A) | ## 核心组件 -### EnvManager +### EnvManager 类 -- **职责**:环境检测和修复的入口 -- **位置**:`manager.py:53` +- **职责**:环境管理器,协调各模块的检测和修复 +- **位置**:`aide/env/manager.py:53` - **关键方法**: - - `list_modules()` - 列出所有可用模块 - - `ensure(runtime_only, modules, check_only, verbose)` - 检测并修复环境 - - `set_modules(module_names)` - 设置启用的模块列表 - - `set_module_config(module_name, key, value)` - 设置模块配置 + - `list_modules()` - 列出所有可用模块(aide env list) + - `ensure()` - 检测并修复环境(aide env ensure) + - `set_modules()` - 设置启用的模块列表 + - `set_module_config()` - 设置模块配置 + - `_process_module()` - 处理单个模块的检测/修复 -### ModuleRegistry +### ModuleRegistry 类 - **职责**:模块注册表,管理所有可用的环境检测模块 -- **位置**:`registry.py:8` +- **位置**:`aide/env/registry.py:8` - **关键方法**: - `register(module)` - 注册模块 - - `get(name)` - 获取模块 + - `get(name)` - 获取指定模块 - `names()` - 获取所有模块名称 + - `list_info()` - 获取所有模块的元信息 -### BaseModule(抽象基类) +### BaseModule 抽象类 -- **职责**:定义模块接口 -- **位置**:`modules/base.py:37` -- **关键方法**: - - `info` - 返回模块元信息 +- **职责**:模块基类,定义检测模块的接口 +- **位置**:`aide/env/modules/base.py:37` +- **抽象方法**: + - `info` - 返回模块元信息(ModuleInfo) - `check(config, root)` - 检测环境 - `ensure(config, root)` - 修复环境(可选) - - `validate_config(config)` - 验证配置 + - `validate_config(config)` - 验证模块配置 -### 数据类 +### CheckResult 数据类 -- `CheckResult` - 检测/修复结果 -- `ModuleInfo` - 模块元信息(名称、描述、能力、配置需求) +- **职责**:检测结果封装 +- **位置**:`aide/env/modules/base.py:12` +- **字段**: + - `success: bool` - 是否成功 + - `version: str | None` - 版本信息 + - `message: str | None` - 消息 + - `can_ensure: bool` - 是否可修复 + +### ModuleInfo 数据类 + +- **职责**:模块元信息 +- **位置**:`aide/env/modules/base.py:22` +- **字段**: + - `name: str` - 模块名称 + - `description: str` - 描述 + - `capabilities: list[str]` - 能力(check, ensure) + - `requires_config: bool` - 是否需要配置 + - `config_keys: list[str]` - 需要的配置键 + +## 模块列表 + +| 模块 | 类型 | 能力 | 说明 | +|------|------|------|------| +| python | A | check | Python 解释器版本检测 | +| uv | A | check | uv 包管理器检测 | +| venv | B | check, ensure | 虚拟环境检测/创建 | +| requirements | B | check, ensure | Python 依赖检测/安装 | +| rust | A | check | Rust 工具链(rustc + cargo) | +| node | A | check | Node.js 运行时 | +| node_deps | B | check, ensure | Node.js 项目依赖 | +| flutter | A | check | Flutter SDK | +| android | A | check | Android SDK | ## 接口说明 +### 环境检测 API + ```python -# CLI 入口 -aide env list # 列出可用模块 -aide env ensure # 检测启用的模块 -aide env ensure --runtime # 仅检测运行时 -aide env ensure --modules python,node # 指定模块 -aide env ensure --all # 检测所有(仅报告) -aide env set modules python,uv,venv # 设置启用模块 -aide env set venv.path .venv # 设置模块配置 +from aide.env.manager import EnvManager +from aide.core.config import ConfigManager + +cfg = ConfigManager(Path.cwd()) +manager = EnvManager(Path.cwd(), cfg) + +# 检测运行时环境 +manager.ensure(runtime_only=True) + +# 检测所有启用模块 +manager.ensure() + +# 检测指定模块 +manager.ensure(modules=["python", "node"]) + +# 列出可用模块 +manager.list_modules() ``` -## 模块分类 +### 模块实例化命名 -| 类型 | 模块 | 需要配置 | 支持修复 | -|------|------|----------|----------| -| A | python, uv, rust, node, flutter, android | 否 | 否 | -| B | venv, requirements, node_deps | 是 | 是 | +支持多项目场景,如 `node_deps:frontend`、`node_deps:backend`: + +```python +# 配置格式 +# [env."node_deps:frontend"] +# path = "frontend" +# manager = "pnpm" +``` ## 依赖关系 -- 依赖:core(output, config) -- 被依赖:main.py +- 依赖:aide/core(ConfigManager、output) +- 被依赖:aide/main.py ## 注意事项 -- 支持模块实例化命名:`模块类型:实例名`(如 `node_deps:frontend`) -- 类型B模块必须配置路径才能检测 -- 启用模块失败时会停止检测 +- 类型A模块无需配置即可检测(全局工具) +- 类型B模块需要在配置中指定路径 +- requirements 模块会自动注入 venv 路径 +- node_deps 模块支持自动检测包管理器(npm/yarn/pnpm/bun) +- 模块名支持实例化命名(module_type:instance_name) diff --git a/.aide/project-docs/blocks/aide-program-flow.md b/.aide/project-docs/blocks/aide-program-flow.md index 73a8eb1..5c7cd63 100644 --- a/.aide/project-docs/blocks/aide-program-flow.md +++ b/.aide/project-docs/blocks/aide-program-flow.md @@ -1,32 +1,47 @@ # aide-program-flow > 路径:aide-program/aide/flow/ -> 最后更新:2025-12-16 +> 最后更新:2025-12-17 ## 概述 -进度追踪模块,提供任务流程管理、Git 自动提交、环节校验和 Hooks 支持。 +进度追踪和流程控制模块,负责管理任务执行流程、Git 集成和环节钩子。采用状态机模式,支持环节跳转校验、自动 Git 提交和 PlantUML 流程图验证。 + +## 目录结构 + +``` +aide-program/aide/flow/ +├── __init__.py 模块初始化 +├── types.py 数据结构定义 +├── errors.py 错误类型 +├── tracker.py 流程追踪器 +├── storage.py 状态文件读写 +├── git.py Git 操作封装 +├── hooks.py 环节钩子 +├── validator.py 流程校验 +└── utils.py 工具函数 +``` ## 文件清单 -| 文件 | 说明 | -|------|------| -| `__init__.py` | 模块初始化 | -| `tracker.py` | FlowTracker 主逻辑(~220 行) | -| `storage.py` | 状态文件读写(~147 行) | -| `types.py` | 数据结构定义(~103 行) | -| `validator.py` | 环节校验器(~50 行) | -| `git.py` | Git 集成(~75 行) | -| `hooks.py` | pre/post commit 钩子(~125 行) | -| `errors.py` | 自定义异常 | -| `utils.py` | 工具函数 | +| 文件 | 类型 | 说明 | +|------|------|------| +| __init__.py | 源码 | 模块初始化 | +| types.py | 源码 | FlowStatus、HistoryEntry 数据类 | +| errors.py | 源码 | FlowError 异常类 | +| tracker.py | 源码 | FlowTracker 核心类,编排流程动作 | +| storage.py | 源码 | FlowStorage 类,状态文件读写和归档 | +| git.py | 源码 | GitIntegration 类,Git 操作封装 | +| hooks.py | 源码 | 环节钩子(PlantUML、CHANGELOG) | +| validator.py | 源码 | FlowValidator 类,流程校验逻辑 | +| utils.py | 源码 | 时间戳和文本处理工具 | ## 核心组件 -### FlowTracker +### FlowTracker 类 - **职责**:编排一次 flow 动作(校验 → hooks → 落盘 → git → 输出) -- **位置**:`tracker.py:20` +- **位置**:`aide/flow/tracker.py:20` - **关键方法**: - `start(phase, summary)` - 开始新任务 - `next_step(summary)` - 记录步骤前进 @@ -35,76 +50,126 @@ - `back_part(phase, reason)` - 回退到之前环节 - `issue(description)` - 记录一般问题 - `error(description)` - 记录严重错误 - - `_apply_action()` - 应用动作,生成新状态和 commit 消息 - - `_do_git_commit()` - 执行 git 操作并更新 commit hash + - `_run()` - 核心执行逻辑 + - `_apply_action()` - 应用动作,更新状态 + - `_do_git_commit()` - 执行 Git 提交 -### FlowStorage +### FlowStorage 类 -- **职责**:状态文件的读写、锁定和归档 -- **位置**:`storage.py:16` +- **职责**:状态文件的读写、锁和归档 +- **位置**:`aide/flow/storage.py:16` - **关键方法**: - - `lock()` - 上下文管理器,获取文件锁 - - `load_status()` - 加载当前任务状态 - - `save_status(status)` - 保存状态(原子写入) - - `archive_existing_status()` - 归档旧状态到 logs/ + - `ensure_ready()` - 确保 .aide 目录存在 + - `lock()` - 文件锁上下文管理器 + - `load_status()` - 加载当前状态 + - `save_status()` - 保存状态(原子写入) + - `archive_existing_status()` - 归档旧状态 - `list_all_tasks()` - 列出所有任务 - - `load_task_by_id(task_id)` - 按 ID 加载任务 + - `load_task_by_id()` - 根据 ID 加载任务 -### FlowValidator +### GitIntegration 类 -- **职责**:校验环节跳转合法性 -- **位置**:`validator.py` -- **校验规则**: - - `next_part`: 只能跳转到相邻的下一环节 - - `back_part`: 可以回退到任意之前的环节 - - `start`: 必须从有效环节开始 +- **职责**:封装 Git 操作 +- **位置**:`aide/flow/git.py:12` +- **关键方法**: + - `ensure_available()` - 检查 git 命令可用 + - `ensure_repo()` - 检查是否在 git 仓库中 + - `add_all()` - git add . + - `commit(message)` - git commit + - `rev_parse_head()` - 获取 HEAD commit hash + - `status_porcelain(path)` - 检查文件状态 + - `commit_touches_path()` - 检查提交是否修改指定文件 -### 数据结构 +### FlowValidator 类 -- `FlowStatus` - 任务状态(task_id, current_phase, current_step, history) -- `HistoryEntry` - 历史条目(timestamp, action, phase, step, summary, git_commit) +- **职责**:流程校验,验证环节跳转合法性 +- **位置**:`aide/flow/validator.py:8` +- **关键方法**: + - `validate_phase_exists(phase)` - 验证环节存在 + - `validate_start(phase)` - 验证开始环节 + - `validate_next_part(from, to)` - 验证前进跳转(只能相邻) + - `validate_back_part(from, to)` - 验证回退跳转(只能向前) + +### FlowStatus 数据类 + +- **职责**:流程状态封装 +- **位置**:`aide/flow/types.py:50` +- **字段**: + - `task_id: str` - 任务 ID(时间戳格式) + - `current_phase: str` - 当前环节 + - `current_step: int` - 当前步骤号 + - `started_at: str` - 开始时间(ISO 格式) + - `history: list[HistoryEntry]` - 历史记录 + +### HistoryEntry 数据类 + +- **职责**:历史条目封装 +- **位置**:`aide/flow/types.py:10` +- **字段**: + - `timestamp: str` - 时间戳 + - `action: str` - 动作类型 + - `phase: str` - 环节名 + - `step: int` - 步骤号 + - `summary: str` - 摘要 + - `git_commit: str | None` - Git 提交 hash + +## 环节钩子 + +### PlantUML 钩子 + +- **触发时机**:离开 flow-design 环节时(next-part/back-part) +- **位置**:`aide/flow/hooks.py:61` +- **功能**: + 1. 校验 .puml/.plantuml 文件语法 + 2. 生成 PNG 图片 + 3. 检查目录:.aide/diagrams、docs、discuss + +### CHANGELOG 钩子 + +- **触发时机**:离开 docs 环节时 +- **位置**:`aide/flow/hooks.py:126` +- **功能**:验证 CHANGELOG.md 已更新 ## 接口说明 +### 流程追踪 API + ```python -# CLI 入口 -aide flow start "" # 开始任务 -aide flow next-step "" # 步骤前进 -aide flow back-step "" # 步骤回退 -aide flow next-part "" # 进入下一环节 -aide flow back-part "" # 回退环节 -aide flow issue "" # 记录问题 -aide flow error "" # 记录错误 -aide flow status # 查看当前状态 -aide flow list # 列出所有任务 -aide flow show # 查看任务详情 +from aide.flow.tracker import FlowTracker +from aide.core.config import ConfigManager + +cfg = ConfigManager(Path.cwd()) +tracker = FlowTracker(Path.cwd(), cfg) + +# 开始新任务 +tracker.start("task-optimize", "开始任务准备") + +# 步骤前进 +tracker.next_step("完成数据库设计") + +# 进入下一环节 +tracker.next_part("impl", "进入实现环节") + +# 回退环节 +tracker.back_part("flow-design", "发现设计遗漏") ``` -## Git 集成 +### 默认环节列表 -**执行顺序**(已优化): -1. 运行 pre_commit_hooks -2. 更新 FlowStatus(内存) -3. 保存状态到磁盘(flow-status.json) -4. `git add .` -5. `git commit -m "[aide] : "` -6. 更新 commit hash 到状态文件 - -> **关键改进**:状态文件先保存再执行 git 操作,确保 flow-status.json 的更新包含在 commit 中 - -提交信息格式: -- 正常操作:`[aide] impl: 完成数据库模型设计` -- 问题记录:`[aide] impl issue: 测试覆盖率低` -- 错误记录:`[aide] impl error: 数据库连接失败` +```python +DEFAULT_PHASES = ["task-optimize", "flow-design", "impl", "verify", "docs", "finish"] +``` ## 依赖关系 -- 依赖:core(output, config) -- 被依赖:main.py +- 依赖:aide/core(ConfigManager、output) +- 被依赖:aide/main.py ## 注意事项 -- 状态文件使用文件锁防止并发写入 -- 归档文件保存在 `.aide/logs/` 目录 -- Hooks 支持 PlantUML 自动校验和构建 -- Git 提交在状态保存之后执行,确保 .aide 目录变更被包含 +- 每次 flow 操作都会自动执行 git add + commit +- 状态文件使用文件锁防止并发冲突 +- next-part 只能前进到相邻环节 +- back-part 可以回退到任意之前的环节 +- 离开 flow-design 时会自动校验和生成 PlantUML 图 +- 离开 docs 时会验证 CHANGELOG.md 已更新 diff --git a/aide-marketplace/aide-plugin/.claude-plugin/plugin.json b/aide-marketplace/aide-plugin/.claude-plugin/plugin.json index a85d191..6574abc 100644 --- a/aide-marketplace/aide-plugin/.claude-plugin/plugin.json +++ b/aide-marketplace/aide-plugin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "aide-plugin", "description": "Aide 工作流体系插件,提供环境配置、项目认知、文档管理和任务执行的标准化流程", - "version": "2.0.4", + "version": "2.0.5", "author": { "name": "Aide Team" }, diff --git a/aide-marketplace/aide-plugin/commands/docs.md b/aide-marketplace/aide-plugin/commands/docs.md index 250a028..6755a7a 100644 --- a/aide-marketplace/aide-plugin/commands/docs.md +++ b/aide-marketplace/aide-plugin/commands/docs.md @@ -329,9 +329,10 @@ xxx/ 1. 每次开始时读取区块计划 2. 找到未完成的区块 -3. **完全深度探索**该区块(每个文件从头到尾) -4. 生成区块内完整目录树 -5. 更新区块计划的进度 +3. **大小控制**:单个区块不超过 5000 行代码 +4. **完全深度探索**该区块(每个文件从头到尾) +5. 生成区块内完整目录树 +6. 更新区块计划的进度 --- diff --git a/task-now.md b/task-now.md index acc47e1..4f55253 100644 --- a/task-now.md +++ b/task-now.md @@ -19,7 +19,7 @@ 你可以检查一下当前项目的aide-plugin中已实现的docs.md,再对比一下.aide/project-docs中的由LLM根据docs.md的要求执行产出的项目文档, -为什么这个项目文档中没有看到aide-marketplace、docs这些目录的导览信息,更别说discuss、reply这些仅有文件夹本身的空目录,整个project-docs读完都对它们完全没有感知,而且也没有体现出目录/文件结构(类似tree命令输出那样) +为什么这个项目文档中没有看到docs这个目录的导览信息,整个project-docs读完都对它们完全没有感知, 原因是什么,单纯是docs.md没有按预期行为准确的给出提示词?还是我之前的想法没有描述到位?还是什么其他原因?