✨ feat: 创建proj docs

.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"
     }
   ]
 }

.aide/flow-status.lock

@@ -1 +0,0 @@
-24287

.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** - 收尾：清理临时文件、汇报完成
+
+## 输出格式约定
+
+| 前缀 | 含义 |
+|------|------|
+| `✓` | 成功 |
+| `⚠` | 警告（可继续） |
+| `✗` | 错误（需处理） |
+| `→` | 进行中/信息 |

.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：初始化区块计划

.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` 是最常用的核心命令

.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 执行任务所需的知识
+- 避免冗余，保持简洁

.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()` 使用正则表达式保守更新配置，保留注释
+- 配置键不存在时会回退到完全重写（丢失注释）

.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 <file>  # 提交待定项，启动后台服务
+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 字段存在，对应选项默认选中

.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模块必须配置路径才能检测
+- 启用模块失败时会停止检测

.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 <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>                # 查看任务详情
+```
+
+## Git 集成
+
+每次 flow 操作自动执行：
+1. `git add .`
+2. `git commit -m "[aide] <phase>: <summary>"`
+
+提交信息格式：
+- 正常操作：`[aide] impl: 完成数据库模型设计`
+- 问题记录：`[aide] impl issue: 测试覆盖率低`
+- 错误记录：`[aide] impl error: 数据库连接失败`
+
+## 依赖关系
+
+- 依赖：core（output, config）
+- 被依赖：main.py
+
+## 注意事项
+
+- 状态文件使用文件锁防止并发写入
+- 归档文件保存在 `.aide/logs/` 目录
+- Hooks 支持 PlantUML 自动校验和构建