[aide] task-optimize: 开始任务准备: 优化 docs.md 命令实现完整深度探索

2025-12-17 02:28:46 +08:00
parent 3efff299d5
commit c805da7a90
14 changed files with 973 additions and 559 deletions
--- 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 命令实现完整深度探索"
    }
  ]
 }
--- a/.aide/flow-status.lock
+++ b/.aide/flow-status.lock
@@ -1 +1 @@
-12913
+16647
--- a/.aide/logs/flow-status.2025-12-17T01-45-46.json
+++ 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"
+    }
+  ]
+}
--- 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 行（核心项目）
--- 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：完成所有区块文档和总导览
--- 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` 自动调用
+- 流程图是必需的，用于规范化思考和早期发现错误
--- 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）
--- 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`）
+- 新增配置键时会回退到完全重写模式（丢失注释）
--- 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 <file>  # 提交待定项，启动后台服务
-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 在同一待定项中必须唯一
--- 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）
--- 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 <phase> "<summary>"    # 开始任务
-aide flow next-step "<summary>"        # 步骤前进
-aide flow back-step "<reason>"         # 步骤回退
-aide flow next-part <phase> "<summary>" # 进入下一环节
-aide flow back-part <phase> "<reason>"  # 回退环节
-aide flow issue "<description>"         # 记录问题
-aide flow error "<description>"         # 记录错误
-aide flow status                        # 查看当前状态
-aide flow list                          # 列出所有任务
-aide flow show <task_id>                # 查看任务详情
+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] <phase>: <summary>"`
-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 已更新