diff --git a/.aide/flow-status.json b/.aide/flow-status.json index 7338999..647e554 100644 --- a/.aide/flow-status.json +++ b/.aide/flow-status.json @@ -105,7 +105,8 @@ "action": "next-step", "phase": "finish", "step": 13, - "summary": "任务完成" + "summary": "任务完成", + "git_commit": "854791e25ce42cbfdb7226a8afb69b0c2ea3b718" } ] } diff --git a/.aide/flow-status.lock b/.aide/flow-status.lock deleted file mode 100755 index 65c1970..0000000 --- a/.aide/flow-status.lock +++ /dev/null @@ -1 +0,0 @@ -17545 \ No newline at end of file diff --git a/.aide/project-docs/README.md b/.aide/project-docs/README.md deleted file mode 100644 index 087f8f0..0000000 --- a/.aide/project-docs/README.md +++ /dev/null @@ -1,103 +0,0 @@ -# ccoptimize 项目导览 - -> 本文档面向 LLM，用于快速了解项目结构和脉络。 -> 最后更新：2025-12-17 - -## 项目简介 - -ccoptimize 是 Aide 工具的开发项目。Aide 是一套命令行工具集，用于支持 LLM 辅助开发的工作流体系。项目提供环境管理、进度追踪、待定项确认等功能，并通过 Claude Code 插件形式提供斜杠命令和技能定义。 - -## 技术栈 - -- 语言：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 依赖 -``` - -> 详细结构见各区块文档 - -## 架构概述 - -``` -┌─────────────────────────────────────────────────────────────┐ -│ 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/ | 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 命令实现 → 查看 [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:setup` | 环境配置（分析、检测、修复） | 是 | -| `/aide:load` | 项目认知载入 | 否（由 run 调用） | -| `/aide:docs` | 项目文档创建和维护 | 是 | -| `/aide:run` | 任务执行（核心命令） | 是 | - -## 统计信息 - -- 总目录数：约 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 deleted file mode 100644 index c347aac..0000000 --- a/.aide/project-docs/block-plan.md +++ /dev/null @@ -1,108 +0,0 @@ -# 区块计划 - -## 项目概况 - -- 项目名称：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/ -- 文件数：约 5 -- 空目录：0 -- 状态：待处理 -- 说明：Aide 核心配置和输出模块 - -### 区块 2：aide-program-env - -- 路径：aide-program/aide/env/ -- 文件数：约 15 -- 空目录：0 -- 状态：待处理 -- 说明：环境检测和管理模块 - -### 区块 3：aide-program-flow - -- 路径：aide-program/aide/flow/ -- 文件数：约 10 -- 空目录：0 -- 状态：待处理 -- 说明：进度追踪和流程控制模块 - -### 区块 4：aide-program-decide - -- 路径：aide-program/aide/decide/ -- 文件数：约 12 -- 空目录：0 -- 状态：待处理 -- 说明：待定项确认 Web 服务模块 - -### 区块 5：aide-plugin-commands - -- 路径：aide-marketplace/aide-plugin/commands/ -- 文件数：约 8 -- 空目录：0 -- 状态：待处理 -- 说明：Aide 插件斜杠命令定义 - -### 区块 6：aide-plugin-skills - -- 路径：aide-marketplace/aide-plugin/skills/ -- 文件数：约 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] 总导览文档 - -## 更新记录 - -- 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 deleted file mode 100644 index bff49b8..0000000 --- a/.aide/project-docs/blocks/aide-plugin-commands.md +++ /dev/null @@ -1,134 +0,0 @@ -# aide-plugin-commands - -> 路径：aide-marketplace/aide-plugin/commands/ -> 最后更新：2025-12-17 - -## 概述 - -Aide 插件的斜杠命令定义。每个 Markdown 文件定义一个命令，文件内容作为 LLM 的提示词展开。命令通过 `/aide:命令名` 方式调用。 - -## 目录结构 - -``` -aide-marketplace/aide-plugin/commands/ -├── docs.md 项目文档管理命令 -├── load.md 项目认知载入命令 -├── run.md 任务执行命令（核心） -└── setup.md 环境配置命令 -``` - -## 文件清单 - -| 文件 | 类型 | 说明 | -|------|------|------| -| docs.md | 命令 | `/aide:docs` - 项目文档创建和维护 | -| load.md | 命令 | `/aide:load` - 项目认知载入 | -| run.md | 命令 | `/aide:run` - 任务执行（核心命令） | -| setup.md | 命令 | `/aide:setup` - 环境配置 | - -## 命令详解 - -### /aide:docs - 项目文档管理 - -- **功能**：创建和维护面向 LLM 的完整深度项目文档 -- **独立运行**：是 -- **核心原则**：完全深度探索，不遗漏任何文件或目录 - -**流程**： -1. 创建流程： - - 完整目录扫描（递归遍历所有目录和文件） - - 初步区块划分（必须覆盖所有非忽略的顶层目录） - - 区块验证（强制完整性检查） - - 逐区块深度探索 - - 生成总导览 -2. 更新流程： - - 读取区块计划 - - 重新扫描目录 - - 分区块验证 - - 增量更新 - -**关键规则**： -- 根目录下每个非忽略的子目录都必须归入某个区块 -- 非代码目录（如 docs/、discuss/、assets/）同样必须作为区块覆盖 -- 区块划分后必须进行完整性验证 -- 完成后必须运行目录完整性最终检查 - -### /aide:load - 项目认知载入 - -- **功能**：按需载入项目文档，建立对项目的认知 -- **独立运行**：否（由 `/aide:run` 调用） - -**流程**： -1. 载入总导览 -2. 建立脉络认知 -3. 按需深入（根据任务） - -**无文档时**：快速认知（阅读关键文件、探索目录结构） - -### /aide:run - 任务执行 - -- **功能**：核心命令，整合任务准备和任务执行 -- **独立运行**：是 -- **参数**：任务文档路径（可选） - -**流程阶段**： -1. **task-optimize**：任务准备 - - 口语化内容检测 - - 任务分析 - - 复杂度评估 - - 任务优化 - - 待定项处理 - - 生成任务细则 -2. **flow-design**：流程设计 - - 制定执行计划 - - 创建流程图（任务执行流程图、程序逻辑流图） -3. **impl**：迭代实现 -4. **verify**：验证交付 -5. **docs**：文档更新 -6. **finish**：收尾 - -**复杂任务**：拆分为子计划，循环执行 flow-design → impl → verify → docs - -### /aide:setup - 环境配置 - -- **功能**：环境依赖分析、配置、检测和修复 -- **独立运行**：是 - -**流程**： -1. 检查 aide 运行时环境 -2. 初始化 aide 目录 -3. 分析项目依赖 -4. 配置环境模块 -5. 执行环境检测 -6. 处理问题 - -## 接口说明 - -### 命令调用方式 - -```bash -# 项目文档管理 -/aide:docs - -# 项目认知载入（通常由 run 自动调用） -/aide:load - -# 任务执行 -/aide:run [任务文档路径] - -# 环境配置 -/aide:setup -``` - -## 依赖关系 - -- 依赖：aide skill（aide 命令使用方法） -- 依赖：env-config skill（环境配置指导） -- 依赖：task-parser skill（口语化内容解析） - -## 注意事项 - -- 命令文件使用 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 deleted file mode 100644 index 9c6c4f3..0000000 --- a/.aide/project-docs/blocks/aide-plugin-skills.md +++ /dev/null @@ -1,98 +0,0 @@ -# aide-plugin-skills - -> 路径：aide-marketplace/aide-plugin/skills/ -> 最后更新：2025-12-17 - -## 概述 - -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 CLI 工具完整使用指南 | -| env-config/SKILL.md | 技能 | 环境配置和故障排除指南 | -| task-parser/SKILL.md | 技能 | 口语化任务内容解析方法 | - -## 技能详解 - -### aide - Aide 工具使用指南 - -- **触发描述**：Aide 工作流工具集。提供环境管理、进度追踪、待定项确认等功能。 -- **内容覆盖**： - - `aide env` - 环境管理命令 - - `aide flow` - 进度追踪命令 - - `aide decide` - 待定项确认命令 - - `aide config` - 配置管理命令 - - `aide init` - 初始化命令 - - 数据存储结构 - - 常见用法示例 - -### env-config - 环境配置指南 - -- **触发描述**：环境配置详细指南。由 `/aide:setup` 命令强制触发。 -- **触发条件**：当 `aide env ensure` 检测失败时 -- **内容覆盖**： - - 问题诊断（常见失败原因） - - 模块分类（类型A/类型B） - - 配置命令使用 - - 项目类型配置示例 - - 多项目场景处理（模块实例化命名） - - node_deps 模块详解 - - 故障排除 - -### task-parser - 口语化内容解析器 - -- **触发描述**：口语化任务内容解析器。当发现用户对话或任务文档具有明显口头语气时使用。 -- **触发条件**：内容具有口语化特征（模糊表述、松散结构、思维跳跃等） -- **解析流程**： - 1. 语义解析（表层理解、深层提取、结构重组） - 2. 批判性分析（逻辑漏洞、盲点识别、过度设计识别） - 3. 建设性优化（优化建议、方案对比、风险权衡） - 4. 上下文关联分析（项目关联、隐含需求、复杂度预判） - -## 接口说明 - -### 技能文件格式 - -每个 SKILL.md 文件包含 YAML 前置元数据： - -```yaml ---- -name: 技能名称 -description: 技能描述（用于触发匹配） ---- - -# 技能内容 -... -``` - -### 技能触发方式 - -技能通过 Skill 工具自动触发： -- LLM 根据任务场景匹配合适的技能 -- 触发后技能内容作为上下文提供给 LLM - -## 依赖关系 - -- 被依赖：aide-plugin commands（命令中引用技能） - -## 注意事项 - -- 技能文件使用 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 deleted file mode 100644 index 69b9390..0000000 --- a/.aide/project-docs/blocks/aide-program-core.md +++ /dev/null @@ -1,118 +0,0 @@ -# aide-program-core - -> 路径：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 输出格式工具 -``` - -## 文件清单 - -| 文件 | 类型 | 说明 | -|------|------|------| -| aide/__init__.py | 源码 | 包初始化，定义包描述 | -| aide/__main__.py | 源码 | 模块入口，支持 `python -m aide` | -| aide/main.py | 源码 | 命令行主入口，解析参数并分发命令 | -| core/__init__.py | 源码 | 核心模块初始化，定义模块描述 | -| core/config.py | 源码 | 配置管理器，处理 TOML 配置 | -| core/output.py | 源码 | 输出格式工具，统一输出前缀 | - -## 核心组件 - -### ConfigManager 类 - -- **职责**：管理 .aide 目录和 config.toml 配置文件 -- **位置**：`aide/core/config.py:240` -- **关键方法**： - - `ensure_base_dirs()` - 创建 .aide 目录结构 - - `ensure_gitignore()` - 根据配置更新 .gitignore - - `ensure_config()` - 确保配置文件存在 - - `load_config()` - 加载 TOML 配置 - - `get_value(key)` - 读取配置值（支持点号分隔键） - - `set_value(key, value)` - 设置配置值（保留注释） - - `_update_config_value()` - 保守更新配置，保留原文件注释 - -### DEFAULT_CONFIG - -- **职责**：默认配置模板，包含完整注释说明 -- **位置**：`aide/core/config.py:13-237` -- **配置节**： - - `[general]` - 通用配置（gitignore_aide） - - `[runtime]` - 运行时要求（python_min, use_uv） - - `[task]` - 任务文档路径（source, spec） - - `[env]` - 环境检测模块配置 - - `[docs]` - 项目文档配置 - - `[flow]` - 流程追踪配置 - - `[plantuml]` - PlantUML 工具配置 - - `[decide]` - 待定项确认配置 - -### output 模块 - -- **职责**：统一输出格式 -- **位置**：`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 - -output.ok("操作成功") # ✓ 操作成功 -output.warn("警告信息") # ⚠ 警告信息 -output.err("错误信息") # ✗ 错误信息 -output.info("提示信息") # → 提示信息 -``` - -## 依赖关系 - -- 依赖：tomllib（标准库）、tomli_w（第三方） -- 被依赖：aide/env、aide/flow、aide/decide - -## 注意事项 - -- `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 deleted file mode 100644 index 1ef108e..0000000 --- a/.aide/project-docs/blocks/aide-program-decide.md +++ /dev/null @@ -1,187 +0,0 @@ -# aide-program-decide - -> 路径：aide-program/aide/decide/ -> 最后更新：2025-12-17 - -## 概述 - -待定项确认模块，提供 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 | 源码 | 模块入口，导出 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 | 前端交互逻辑 | - -## 核心组件 - -### DecideStorage 类 - -- **职责**：管理 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 类 - -- **职责**：HTTP 服务器生命周期管理 -- **位置**：`aide/decide/server.py:26` -- **关键方法**： - - `start()` - 前台启动服务 - - `start_daemon(pid)` - 后台启动服务 - - `stop(reason)` - 停止服务 - - `_find_available_port()` - 自动探测可用端口 - - `_serve_forever()` - 服务循环 - -### DecideHandlers 类 - -- **职责**：HTTP 请求路由和处理 -- **位置**：`aide/decide/handlers.py:17` -- **关键方法**： - - `handle(method, path, body)` - 请求分发 - - `handle_get_items()` - GET /api/items - - `handle_submit(body)` - POST /api/submit - - `_validate_decisions()` - 验证决策数据完整性 - -### DecideInput 数据类 - -- **职责**：待定项输入数据封装 -- **位置**：`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": "用户备注"} - ] -} -``` - -## 接口说明 - -### CLI 使用 - -```bash -# 提交待定项，启动 Web 服务 -aide decide submit ./pending-items.json - -# 获取决策结果 -aide decide result -``` - -### 配置项 - -在 `[decide]` 节： -- `port` - 起始端口（默认 3721） -- `bind` - 监听地址（默认 127.0.0.1） -- `url` - 自定义访问地址 -- `timeout` - 超时时间（秒，0 表示不超时） - -## 依赖关系 - -- 依赖：aide/core（ConfigManager、output）、aide/flow/utils（now_task_id） -- 被依赖：aide/main.py - -## 注意事项 - -- 服务以后台进程运行，用户提交后自动关闭 -- 决策记录保存在 .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 deleted file mode 100644 index 13104f1..0000000 --- a/.aide/project-docs/blocks/aide-program-env.md +++ /dev/null @@ -1,163 +0,0 @@ -# aide-program-env - -> 路径：aide-program/aide/env/ -> 最后更新：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 | 源码 | 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 类 - -- **职责**：环境管理器，协调各模块的检测和修复 -- **位置**：`aide/env/manager.py:53` -- **关键方法**： - - `list_modules()` - 列出所有可用模块（aide env list） - - `ensure()` - 检测并修复环境（aide env ensure） - - `set_modules()` - 设置启用的模块列表 - - `set_module_config()` - 设置模块配置 - - `_process_module()` - 处理单个模块的检测/修复 - -### ModuleRegistry 类 - -- **职责**：模块注册表，管理所有可用的环境检测模块 -- **位置**：`aide/env/registry.py:8` -- **关键方法**： - - `register(module)` - 注册模块 - - `get(name)` - 获取指定模块 - - `names()` - 获取所有模块名称 - - `list_info()` - 获取所有模块的元信息 - -### BaseModule 抽象类 - -- **职责**：模块基类，定义检测模块的接口 -- **位置**：`aide/env/modules/base.py:37` -- **抽象方法**： - - `info` - 返回模块元信息（ModuleInfo） - - `check(config, root)` - 检测环境 - - `ensure(config, root)` - 修复环境（可选） - - `validate_config(config)` - 验证模块配置 - -### CheckResult 数据类 - -- **职责**：检测结果封装 -- **位置**：`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 -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() -``` - -### 模块实例化命名 - -支持多项目场景，如 `node_deps:frontend`、`node_deps:backend`： - -```python -# 配置格式 -# [env."node_deps:frontend"] -# path = "frontend" -# manager = "pnpm" -``` - -## 依赖关系 - -- 依赖：aide/core（ConfigManager、output） -- 被依赖：aide/main.py - -## 注意事项 - -- 类型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 deleted file mode 100644 index 5c7cd63..0000000 --- a/.aide/project-docs/blocks/aide-program-flow.md +++ /dev/null @@ -1,175 +0,0 @@ -# aide-program-flow - -> 路径：aide-program/aide/flow/ -> 最后更新：2025-12-17 - -## 概述 - -进度追踪和流程控制模块，负责管理任务执行流程、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 | 源码 | 模块初始化 | -| 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 类 - -- **职责**：编排一次 flow 动作（校验 → hooks → 落盘 → git → 输出） -- **位置**：`aide/flow/tracker.py:20` -- **关键方法**： - - `start(phase, summary)` - 开始新任务 - - `next_step(summary)` - 记录步骤前进 - - `back_step(reason)` - 记录步骤回退 - - `next_part(phase, summary)` - 进入下一环节 - - `back_part(phase, reason)` - 回退到之前环节 - - `issue(description)` - 记录一般问题 - - `error(description)` - 记录严重错误 - - `_run()` - 核心执行逻辑 - - `_apply_action()` - 应用动作，更新状态 - - `_do_git_commit()` - 执行 Git 提交 - -### FlowStorage 类 - -- **职责**：状态文件的读写、锁和归档 -- **位置**：`aide/flow/storage.py:16` -- **关键方法**： - - `ensure_ready()` - 确保 .aide 目录存在 - - `lock()` - 文件锁上下文管理器 - - `load_status()` - 加载当前状态 - - `save_status()` - 保存状态（原子写入） - - `archive_existing_status()` - 归档旧状态 - - `list_all_tasks()` - 列出所有任务 - - `load_task_by_id()` - 根据 ID 加载任务 - -### GitIntegration 类 - -- **职责**：封装 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 类 - -- **职责**：流程校验，验证环节跳转合法性 -- **位置**：`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 -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", "发现设计遗漏") -``` - -### 默认环节列表 - -```python -DEFAULT_PHASES = ["task-optimize", "flow-design", "impl", "verify", "docs", "finish"] -``` - -## 依赖关系 - -- 依赖：aide/core（ConfigManager、output） -- 被依赖：aide/main.py - -## 注意事项 - -- 每次 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 6574abc..381b0ff 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.5", + "version": "2.0.6", "author": { "name": "Aide Team" },