diff --git a/.aide/flow-status.json b/.aide/flow-status.json index 4fdf9b3..cfdd1cc 100644 --- a/.aide/flow-status.json +++ b/.aide/flow-status.json @@ -1,7 +1,7 @@ { "task_id": "2025-12-15T21-48-00", "current_phase": "finish", - "current_step": 12, + "current_step": 13, "started_at": "2025-12-15T21:48:00+08:00", "history": [ { @@ -99,6 +99,14 @@ "step": 12, "summary": "文档更新完成,进入收尾", "git_commit": "da8ac8bbc014bd4a57d21a2ac750fdb72a766b75" + }, + { + "timestamp": "2025-12-15T21:55:24+08:00", + "action": "next-step", + "phase": "finish", + "step": 13, + "summary": "任务完成", + "git_commit": "7353f2100d784daae5a2ee6a9388f7812ec8e72c" } ] } diff --git a/.aide/flow-status.lock b/.aide/flow-status.lock deleted file mode 100755 index cf9301a..0000000 --- a/.aide/flow-status.lock +++ /dev/null @@ -1 +0,0 @@ -24287 \ No newline at end of file diff --git a/.aide/project-docs/README.md b/.aide/project-docs/README.md new file mode 100644 index 0000000..816002e --- /dev/null +++ b/.aide/project-docs/README.md @@ -0,0 +1,83 @@ +# Aide 项目导览 + +> 本文档面向 LLM,用于快速了解项目结构和脉络。 +> 最后更新:2025-12-15 + +## 项目简介 + +Aide 是一套面向 Claude Code 的工作流辅助体系,旨在解决 AI 辅助开发中的信息过载、操作不确定性和流程耦合问题。通过模块化的 Commands、Skills 和命令行工具,帮助开发者更高效地进行 AI 辅助开发。 + +## 技术栈 + +- **语言**:Python 3.11+, Markdown +- **包管理**:uv +- **配置格式**:TOML +- **前端**:原生 HTML/CSS/JS(decide 模块) +- **流程图**:PlantUML + +## 架构概述 + +``` +用户 + │ + ▼ +aide-plugin (Claude Code 插件) + ├── Commands: /aide:setup, /aide:load, /aide:docs, /aide:run + └── Skills: aide, env-config + │ + ▼ 调用 +aide-program (命令行工具) + ├── aide init - 初始化配置 + ├── aide env - 环境检测(模块化) + ├── aide config - 配置读写 + ├── aide flow - 进度追踪 + git 集成 + └── aide decide - 待定项 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-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/` | 流程图目录 | + +## 标准工作流程 + +1. **task-optimize** - 任务优化:分析任务、识别待定项 +2. **flow-design** - 流程设计:创建 PlantUML 流程图 +3. **impl** - 迭代实现:按计划执行 +4. **verify** - 验证交付:对照任务细则验证 +5. **docs** - 文档更新:更新相关文档 +6. **finish** - 收尾:清理临时文件、汇报完成 + +## 输出格式约定 + +| 前缀 | 含义 | +|------|------| +| `✓` | 成功 | +| `⚠` | 警告(可继续) | +| `✗` | 错误(需处理) | +| `→` | 进行中/信息 | diff --git a/.aide/project-docs/block-plan.md b/.aide/project-docs/block-plan.md new file mode 100644 index 0000000..8b49a3f --- /dev/null +++ b/.aide/project-docs/block-plan.md @@ -0,0 +1,57 @@ +# 区块计划 + +## 项目概况 +- 项目名称:Aide +- 主要语言:Python, Markdown +- aide-program 代码行数:~4100 行 +- 项目阶段:设计完成,核心功能已实现 + +## 区块划分 + +### 区块 1:aide-program-core +- 路径:aide-program/aide/core/ +- 文件数:3 +- 说明:核心模块(配置管理、输出格式) +- 状态:待处理 + +### 区块 2:aide-program-env +- 路径:aide-program/aide/env/ +- 文件数:12 +- 说明:环境检测模块(python, uv, node, rust 等) +- 状态:待处理 + +### 区块 3:aide-program-flow +- 路径:aide-program/aide/flow/ +- 文件数:9 +- 说明:进度追踪模块(含 Git 集成) +- 状态:待处理 + +### 区块 4:aide-program-decide +- 路径:aide-program/aide/decide/ +- 文件数:11 +- 说明:待定项确认模块(Web 界面) +- 状态:待处理 + +### 区块 5:aide-plugin-commands +- 路径:aide-marketplace/aide-plugin/commands/ +- 文件数:4 +- 说明:插件斜杠命令(setup, load, docs, run) +- 状态:待处理 + +### 区块 6:aide-plugin-skills +- 路径:aide-marketplace/aide-plugin/skills/ +- 文件数:2 +- 说明:插件技能(aide, env-config) +- 状态:待处理 + +## 进度追踪 +- [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 + +## 更新记录 +- 2025-12-15:完成所有区块文档和总导览 +- 2025-12-15:初始化区块计划 diff --git a/.aide/project-docs/blocks/aide-plugin-commands.md b/.aide/project-docs/blocks/aide-plugin-commands.md new file mode 100644 index 0000000..4b51f6f --- /dev/null +++ b/.aide/project-docs/blocks/aide-plugin-commands.md @@ -0,0 +1,77 @@ +# aide-plugin-commands + +> 路径:aide-marketplace/aide-plugin/commands/ +> 最后更新:2025-12-15 + +## 概述 + +Aide 插件的斜杠命令定义,是面向 LLM 的执行指令文件。 + +## 文件清单 + +| 文件 | 说明 | +|------|------| +| `setup.md` | `/aide:setup` - 环境配置命令 | +| `load.md` | `/aide:load` - 项目认知载入 | +| `docs.md` | `/aide:docs` - 项目文档管理 | +| `run.md` | `/aide:run` - 任务执行(核心命令) | + +## 命令说明 + +### /aide:setup + +- **用途**:环境配置(独立运行) +- **触发 skill**:env-config +- **流程**: + 1. 检查 aide 运行时环境 + 2. 初始化 .aide 目录 + 3. 分析项目依赖 + 4. 配置环境模块 + 5. 执行环境检测 + +### /aide:load + +- **用途**:项目认知载入(由 run 调用) +- **触发 skill**:aide +- **流程**: + 1. 检查项目文档配置 + 2. 载入总导览 + 3. 建立脉络认知 + 4. 按需深入 + +### /aide:docs + +- **用途**:项目文档创建和维护(独立运行) +- **触发 skill**:aide +- **流程**: + - 创建流程:目录探索 → 区块划分 → 逐区块生成文档 → 生成总导览 + - 更新流程:读取区块计划 → 分区块验证 → 增量更新 + +### /aide:run + +- **用途**:任务执行(核心命令) +- **触发 skill**:aide +- **标准流程**: + 1. task-optimize - 任务准备 + 2. flow-design - 流程设计 + 3. impl - 迭代实现 + 4. verify - 验证交付 + 5. docs - 文档更新 + 6. finish - 收尾 + +## 设计原则 + +- 执行文件给 LLM 看,聚焦执行指令 +- 设计文档给人看,包含完整上下文 +- 每个命令开始时触发对应的 skill 学习必要知识 + +## 依赖关系 + +- 依赖:aide skill, env-config skill +- 调用:aide 命令行工具 + +## 注意事项 + +- `/aide:setup` 和 `/aide:docs` 是独立运行的命令 +- `/aide:load` 通常由 `/aide:run` 内部调用 +- `/aide:run` 是最常用的核心命令 diff --git a/.aide/project-docs/blocks/aide-plugin-skills.md b/.aide/project-docs/blocks/aide-plugin-skills.md new file mode 100644 index 0000000..a02b79f --- /dev/null +++ b/.aide/project-docs/blocks/aide-plugin-skills.md @@ -0,0 +1,57 @@ +# aide-plugin-skills + +> 路径:aide-marketplace/aide-plugin/skills/ +> 最后更新:2025-12-15 + +## 概述 + +Aide 插件的技能定义,提供专门知识供 LLM 按需学习。 + +## 文件清单 + +| 目录 | 说明 | +|------|------| +| `aide/SKILL.md` | aide 基础命令指南(始终加载) | +| `env-config/SKILL.md` | 环境配置详细指南(按需触发) | + +## 技能说明 + +### aide skill + +- **触发方式**:始终加载 +- **内容**: + - aide 命令行工具的完整使用指南 + - 所有子命令的参数说明和示例 + - 输出格式说明(✓/⚠/✗/→) + - 数据存储结构 + - 常见用法示例 + +### env-config skill + +- **触发方式**:当 `aide env ensure` 失败时按需触发 +- **内容**: + - 环境模块详细配置方法 + - 各模块的配置项说明 + - 多项目场景处理 + - 故障排除指南 + +## 设计理念 + +**Skill 拆分原则**: +- `aide` skill:基础知识,始终需要 +- `env-config` skill:专门知识,仅在配置环境时需要 + +这样设计的好处: +1. 减少 LLM 上下文占用 +2. 按需加载专门知识 +3. 职责分离,便于维护 + +## 依赖关系 + +- 被依赖:commands(setup, load, docs, run) + +## 注意事项 + +- Skill 文件是 Markdown 格式 +- 内容应聚焦于 LLM 执行任务所需的知识 +- 避免冗余,保持简洁 diff --git a/.aide/project-docs/blocks/aide-program-core.md b/.aide/project-docs/blocks/aide-program-core.md new file mode 100644 index 0000000..61ae1b9 --- /dev/null +++ b/.aide/project-docs/blocks/aide-program-core.md @@ -0,0 +1,67 @@ +# aide-program-core + +> 路径:aide-program/aide/core/ +> 最后更新:2025-12-15 + +## 概述 + +核心模块,提供配置管理和输出格式化功能,是所有其他模块的基础依赖。 + +## 文件清单 + +| 文件 | 说明 | +|------|------| +| `__init__.py` | 模块初始化,导出 output | +| `config.py` | 配置管理器(~390 行) | +| `output.py` | 统一输出格式(25 行) | + +## 核心组件 + +### ConfigManager + +- **职责**:管理 `.aide/config.toml` 配置文件 +- **位置**:`config.py:240` +- **关键方法**: + - `ensure_config()` - 确保配置文件存在,不存在则创建默认配置 + - `load_config()` - 加载配置(返回 dict) + - `get_value(key)` - 获取配置值(支持点号分隔的键) + - `set_value(key, value)` - 设置配置值(保留注释和格式) + - `ensure_gitignore()` - 根据配置决定是否忽略 .aide 目录 + +### DEFAULT_CONFIG + +- **职责**:默认配置模板(自文档化,含完整注释) +- **位置**:`config.py:13` +- **特点**: + - 包含所有配置节的详细说明 + - 用户可仅通过此文件了解所有支持的功能 + - 约 230 行注释文档 + +### output 模块 + +- **职责**:统一输出格式 +- **位置**:`output.py` +- **输出函数**: + - `ok(msg)` → `✓ {msg}` 成功 + - `warn(msg)` → `⚠ {msg}` 警告 + - `err(msg)` → `✗ {msg}` 错误 + - `info(msg)` → `→ {msg}` 信息 + - `step(msg, current, total)` → `[n/m] {msg}` 步骤 + +## 接口说明 + +被所有其他模块依赖: +```python +from aide.core import output +from aide.core.config import ConfigManager +``` + +## 依赖关系 + +- 依赖:标准库 + tomllib + tomli_w +- 被依赖:env, flow, decide, main + +## 注意事项 + +- `set_value()` 使用正则表达式保守更新配置,保留注释 +- 配置键不存在时会回退到完全重写(丢失注释) diff --git a/.aide/project-docs/blocks/aide-program-decide.md b/.aide/project-docs/blocks/aide-program-decide.md new file mode 100644 index 0000000..d91f3ea --- /dev/null +++ b/.aide/project-docs/blocks/aide-program-decide.md @@ -0,0 +1,100 @@ +# aide-program-decide + +> 路径:aide-program/aide/decide/ +> 最后更新:2025-12-15 + +## 概述 + +待定项确认模块,提供 Web 界面让用户对任务中的待定项进行决策。服务在后台运行,用户提交后自动关闭。 + +## 文件清单 + +| 文件 | 说明 | +|------|------| +| `__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 前端资源 | + +## 核心组件 + +### CLI 入口 + +- **职责**:解析参数并调度功能 +- **位置**:`cli.py` +- **关键函数**: + - `cmd_decide_submit(file_path)` - 提交待定项数据 + - `cmd_decide_result()` - 获取决策结果 + +### DecideServer + +- **职责**:HTTP 服务器生命周期管理 +- **位置**:`server.py:26` +- **关键方法**: + - `start()` - 前台启动服务 + - `start_daemon(pid)` - 后台启动服务 + - `stop(reason)` - 停止服务 + +### DecideStorage + +- **职责**:管理待定项和决策结果的存储 +- **位置**:`storage.py` +- **关键方法**: + - `save_pending(input)` - 保存待定项到 pending.json + - `load_pending()` - 加载待定项 + - `save_result(result)` - 保存决策结果 + - `load_result()` - 加载决策结果 + - `is_server_running()` - 检查服务是否运行 + +### 数据结构 + +- `DecideInput` - 待定项输入数据 +- `DecideItem` - 单个待定项(含多个选项) +- `DecideOption` - 选项(value, label, score, pros, cons) +- `DecideResult` - 决策结果 +- `DecidedItem` - 单个决策(chosen, note) + +## 接口说明 + +```python +# CLI 入口 +aide decide submit # 提交待定项,启动后台服务 +aide decide result # 获取决策结果 + +# Web 界面 +GET / # 主页面 +GET /api/data # 获取待定项数据 +POST /api/submit # 提交决策 +``` + +## 配置项 + +在 `.aide/config.toml` 的 `[decide]` 节: + +| 配置项 | 默认值 | 说明 | +|--------|--------|------| +| `port` | 3721 | 起始端口 | +| `bind` | 127.0.0.1 | 监听地址 | +| `url` | "" | 自定义访问地址 | +| `timeout` | 0 | 超时时间(秒) | + +## 数据文件 + +- `.aide/decisions/pending.json` - 当前待定项数据 +- `.aide/decisions/{timestamp}.json` - 决策记录归档 + +## 依赖关系 + +- 依赖:core(output, config) +- 被依赖:main.py + +## 注意事项 + +- 服务作为后台进程运行,与 CLI 脱离 +- 用户提交决策后服务自动关闭 +- 如果 recommend 字段存在,对应选项默认选中 diff --git a/.aide/project-docs/blocks/aide-program-env.md b/.aide/project-docs/blocks/aide-program-env.md new file mode 100644 index 0000000..fe05a85 --- /dev/null +++ b/.aide/project-docs/blocks/aide-program-env.md @@ -0,0 +1,93 @@ +# aide-program-env + +> 路径:aide-program/aide/env/ +> 最后更新:2025-12-15 + +## 概述 + +环境检测模块,提供模块化的开发环境检测和修复功能。支持多种语言和工具,以及模块实例化(多项目场景)。 + +## 文件清单 + +| 文件 | 说明 | +|------|------| +| `__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 项目依赖检测 | + +## 核心组件 + +### EnvManager + +- **职责**:环境检测和修复的入口 +- **位置**:`manager.py:53` +- **关键方法**: + - `list_modules()` - 列出所有可用模块 + - `ensure(runtime_only, modules, check_only, verbose)` - 检测并修复环境 + - `set_modules(module_names)` - 设置启用的模块列表 + - `set_module_config(module_name, key, value)` - 设置模块配置 + +### ModuleRegistry + +- **职责**:模块注册表,管理所有可用的环境检测模块 +- **位置**:`registry.py:8` +- **关键方法**: + - `register(module)` - 注册模块 + - `get(name)` - 获取模块 + - `names()` - 获取所有模块名称 + +### BaseModule(抽象基类) + +- **职责**:定义模块接口 +- **位置**:`modules/base.py:37` +- **关键方法**: + - `info` - 返回模块元信息 + - `check(config, root)` - 检测环境 + - `ensure(config, root)` - 修复环境(可选) + - `validate_config(config)` - 验证配置 + +### 数据类 + +- `CheckResult` - 检测/修复结果 +- `ModuleInfo` - 模块元信息(名称、描述、能力、配置需求) + +## 接口说明 + +```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 # 设置模块配置 +``` + +## 模块分类 + +| 类型 | 模块 | 需要配置 | 支持修复 | +|------|------|----------|----------| +| A | python, uv, rust, node, flutter, android | 否 | 否 | +| B | venv, requirements, node_deps | 是 | 是 | + +## 依赖关系 + +- 依赖:core(output, config) +- 被依赖:main.py + +## 注意事项 + +- 支持模块实例化命名:`模块类型:实例名`(如 `node_deps:frontend`) +- 类型B模块必须配置路径才能检测 +- 启用模块失败时会停止检测 diff --git a/.aide/project-docs/blocks/aide-program-flow.md b/.aide/project-docs/blocks/aide-program-flow.md new file mode 100644 index 0000000..70ee94f --- /dev/null +++ b/.aide/project-docs/blocks/aide-program-flow.md @@ -0,0 +1,101 @@ +# aide-program-flow + +> 路径:aide-program/aide/flow/ +> 最后更新:2025-12-15 + +## 概述 + +进度追踪模块,提供任务流程管理、Git 自动提交、环节校验和 Hooks 支持。 + +## 文件清单 + +| 文件 | 说明 | +|------|------| +| `__init__.py` | 模块初始化 | +| `tracker.py` | FlowTracker 主逻辑(~200 行) | +| `storage.py` | 状态文件读写(~147 行) | +| `types.py` | 数据结构定义(~103 行) | +| `validator.py` | 环节校验器(~50 行) | +| `git.py` | Git 集成(~75 行) | +| `hooks.py` | pre/post commit 钩子(~125 行) | +| `errors.py` | 自定义异常 | +| `utils.py` | 工具函数 | + +## 核心组件 + +### FlowTracker + +- **职责**:编排一次 flow 动作(校验 → hooks → git → 落盘 → 输出) +- **位置**:`tracker.py:20` +- **关键方法**: + - `start(phase, summary)` - 开始新任务 + - `next_step(summary)` - 记录步骤前进 + - `back_step(reason)` - 记录步骤回退 + - `next_part(phase, summary)` - 进入下一环节 + - `back_part(phase, reason)` - 回退到之前环节 + - `issue(description)` - 记录一般问题 + - `error(description)` - 记录严重错误 + +### FlowStorage + +- **职责**:状态文件的读写、锁定和归档 +- **位置**:`storage.py:16` +- **关键方法**: + - `lock()` - 上下文管理器,获取文件锁 + - `load_status()` - 加载当前任务状态 + - `save_status(status)` - 保存状态(原子写入) + - `archive_existing_status()` - 归档旧状态到 logs/ + - `list_all_tasks()` - 列出所有任务 + - `load_task_by_id(task_id)` - 按 ID 加载任务 + +### FlowValidator + +- **职责**:校验环节跳转合法性 +- **位置**:`validator.py` +- **校验规则**: + - `next_part`: 只能跳转到相邻的下一环节 + - `back_part`: 可以回退到任意之前的环节 + - `start`: 必须从有效环节开始 + +### 数据结构 + +- `FlowStatus` - 任务状态(task_id, current_phase, current_step, history) +- `HistoryEntry` - 历史条目(timestamp, action, phase, step, summary, git_commit) + +## 接口说明 + +```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 # 查看任务详情 +``` + +## Git 集成 + +每次 flow 操作自动执行: +1. `git add .` +2. `git commit -m "[aide] : "` + +提交信息格式: +- 正常操作:`[aide] impl: 完成数据库模型设计` +- 问题记录:`[aide] impl issue: 测试覆盖率低` +- 错误记录:`[aide] impl error: 数据库连接失败` + +## 依赖关系 + +- 依赖:core(output, config) +- 被依赖:main.py + +## 注意事项 + +- 状态文件使用文件锁防止并发写入 +- 归档文件保存在 `.aide/logs/` 目录 +- Hooks 支持 PlantUML 自动校验和构建