✨ feat: 完成部分文档更新

2025-12-14 23:10:02 +08:00
parent 1cf99c7b5f
commit 52d1605a60
6 changed files with 53 additions and 32 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -0,0 +1,8 @@
+# CHANGELOG
+
+本文件记录 Aide 项目对使用者可见的重要变更。
+
+## 2025-12-14
+
+- 实现 `aide flow`（进度追踪 + Git 自动提交 + 流程校验 + Hooks）
+- 补充 `aide flow` 详细设计文档与导航链路
--- a/README.md
+++ b/README.md
@@ -32,7 +32,7 @@ aide-program (命令行工具)
  ├── aide init   - 初始化配置
  ├── aide env    - 环境检测（模块化）
  ├── aide config - 配置读写
-  ├── aide flow   - 进度追踪 + git 集成（待实现）
+  ├── aide flow   - 进度追踪 + git 集成（已实现）
  └── aide decide - 待定项 Web 确认（待实现）
 ```

@@ -91,7 +91,7 @@ ccoptimize/
    │   ├── core/
    │   │   ├── config.py     # 配置管理
    │   │   └── output.py     # 输出格式
-    │   └── env/
+    │   ├── env/
    │       ├── manager.py    # 环境管理器
    │       ├── registry.py   # 模块注册表
    │       └── modules/      # 环境检测模块
@@ -101,11 +101,14 @@ ccoptimize/
    │           ├── android.py, node_deps.py
    │           ├── venv.py, requirements.py
    │           └── ...
+    │   └── flow/             # 进度追踪（已实现）
+    │       └── ...
    └── docs/                 # 设计文档（给人）
        ├── README.md
        ├── commands/
        │   ├── env.md
        │   ├── flow.md
+        │   ├── flow/          # flow 详细设计（交接包）
        │   ├── decide.md
        │   └── init.md
        └── formats/
@@ -146,7 +149,7 @@ ccoptimize/
 | aide env ensure --all | ✅ 已实现 | 全量检测（仅检查） |
 | aide env ensure --verbose | ✅ 已实现 | 详细配置输出 |
 | aide config get/set | ✅ 已实现 | 配置读写 |
-| aide flow | ⏳ 待实现 | 进度追踪 + git 集成 |
+| aide flow | ✅ 已实现 | 进度追踪 + git 集成 |
 | aide decide | ⏳ 待实现 | 待定项 Web 确认 |

 代码位于 `aide-program/aide/`
@@ -188,13 +191,14 @@ ccoptimize/

 ### 4.2 了解/修改 Commands 或 Skill

-1. 阅读 `aide-marketplace/aide-plugin/docs/README.md` - plugin 导览
+1. 阅读 [aide-plugin 导览](aide-marketplace/aide-plugin/docs/README.md)
 2. 阅读对应 command 的设计文档

 ### 4.3 了解/修改 aide 程序

-1. 阅读 `aide-program/docs/README.md` - program 导览
-2. 阅读对应子命令的设计文档
+1. 阅读 [aide-program 导览](aide-program/docs/README.md)
+2. 阅读对应子命令的设计文档（如 [flow 子命令概览](aide-program/docs/commands/flow.md)）
+3. 深入 flow 实现细节：[`aide-program/docs/commands/flow/README.md`](aide-program/docs/commands/flow/README.md)

 ### 4.4 了解数据格式

@@ -205,19 +209,7 @@ ccoptimize/

 ## 五、待完成工作

-### 5.1 aide flow 实现
-
-**功能**：进度追踪 + git 自动提交 + 流程校验
-
-**设计文档**：`aide-program/docs/commands/flow.md`
-
-**主要工作**：
- 实现 `aide/flow/tracker.py` - 状态追踪
- 实现 `aide/flow/git.py` - git 集成
- 实现 `aide/flow/validator.py` - 流程校验
- 在 `main.py` 添加 CLI 路由
-
-### 5.2 aide decide 实现
+### 5.1 aide decide 实现

 **功能**：待定项 Web 确认界面

@@ -228,7 +220,7 @@ ccoptimize/
 - 实现 `aide/decide/web/` - React 前端
 - 在 `main.py` 添加 CLI 路由

-### 5.3 扩展环境模块（可选）
+### 5.2 扩展环境模块（可选）

 可按需添加更多环境检测模块：
 - java - Java JDK 检测
@@ -237,9 +229,9 @@ ccoptimize/
 - cargo_deps - Rust 项目依赖（类似 node_deps）
 - pub_deps - Flutter/Dart 项目依赖

-### 5.4 整体验证
+### 5.3 整体验证

-完成 flow 和 decide 后，需要进行完整工作流验证：
+完成 decide 后，需要进行完整工作流验证：
 1. `/aide:init` → `/aide:prep` → `/aide:exec` 完整流程测试
 2. 验证 git 自动提交功能
 3. 验证待定项 Web 界面
@@ -271,9 +263,11 @@ ccoptimize/

 - 文档版本：1.2.0
 - 更新日期：2025-12-14
- 项目阶段：设计完成，部分实现
+- 项目阶段：设计完成，部分实现（flow 已实现，decide 待实现）
 - 最近更新：
  - aide env set 命令实现
+  - aide flow 子命令实现
+  - 新增 CHANGELOG.md（用于 docs 阶段校验）
  - 新增环境模块：rust, node, flutter, android, node_deps
  - 支持模块实例化命名（多项目场景）
  - Skill 拆分：aide（基础）+ env-config（按需）
--- a/aide-marketplace/aide-plugin/docs/README.md
+++ b/aide-marketplace/aide-plugin/docs/README.md
@@ -175,4 +175,6 @@ aide env ensure

 - [总导览](../../../docs/aide-overview.md)
 - [aide-program 导览](../../../aide-program/docs/README.md)
+- [aide flow 子命令](../../../aide-program/docs/commands/flow.md)
+- [aide flow 详细设计](../../../aide-program/docs/commands/flow/README.md)
 - [Claude Code 插件指南](../../../docs/03-插件指南.md)
--- a/aide-program/docs/README.md
+++ b/aide-program/docs/README.md
@@ -47,9 +47,11 @@ aide-program 是 Aide 工作流体系的命令行工具，为 aide-plugin 提供
 | `aide env list` | [commands/env.md](commands/env.md) | ✅ 已实现 | 列出可用模块 |
 | `aide env set` | [commands/env.md](commands/env.md) | ✅ 已实现 | 设置环境配置（带验证） |
 | `aide config` | [formats/config.md](formats/config.md) | ✅ 已实现 | 配置读写 |
-| `aide flow` | [commands/flow.md](commands/flow.md) | ⏳ 待实现 | 进度追踪与 git 集成 |
+| `aide flow` | [commands/flow.md](commands/flow.md) | ✅ 已实现 | 进度追踪与 git 集成 |
 | `aide decide` | [commands/decide.md](commands/decide.md) | ⏳ 待实现 | 待定项 Web 确认 |

+补充：flow 的实现细节与验证清单见 `commands/flow/README.md`。
+
 ### 2.1 环境检测模块

 | 模块 | 类型 | 说明 |
@@ -72,13 +74,16 @@ aide-program 是 Aide 工作流体系的命令行工具，为 aide-plugin 提供

 ```
 aide-program/
-├── aide.sh                  # Linux/Mac 入口脚本
-├── aide.bat                 # Windows 入口脚本
+├── bin/                     # 入口脚本
+│   ├── aide.sh              # Linux/Mac
+│   ├── aide.bat             # Windows
+│   └── aide                 # 软链接（指向 aide.sh）
 ├── docs/                    # 设计文档（本目录）
 │   ├── README.md            # 导览（本文件）
 │   ├── commands/            # 子命令设计文档
 │   │   ├── env.md
 │   │   ├── flow.md
+│   │   ├── flow/            # flow 详细设计（交接包）
 │   │   ├── decide.md
 │   │   └── init.md
 │   └── formats/             # 数据格式文档
@@ -100,7 +105,13 @@ aide-program/
    │       ├── node.py, flutter.py, android.py
    │       ├── venv.py, requirements.py
    │       └── node_deps.py
-    ├── flow/                # 待实现
+    ├── flow/                # 进度追踪（已实现）
+    │   ├── tracker.py
+    │   ├── validator.py
+    │   ├── storage.py
+    │   ├── git.py
+    │   ├── hooks.py
+    │   ├── types.py
    │   └── ...
    └── decide/              # 待实现
        └── ...
@@ -173,17 +184,18 @@ aide-program/

 ```bash
 # Linux/Mac
-./aide-program/aide.sh <command> [args]
+./aide-program/bin/aide.sh <command> [args]

 # Windows
-aide-program\aide.bat <command> [args]
+aide-program\bin\aide.bat <command> [args]
 ```

 ### 6.2 通过 Python 模块

 ```bash
-# 需要先激活虚拟环境或设置 PYTHONPATH
-python -m aide <command> [args]
+# 需要先使用 uv 创建并安装依赖，或直接使用入口脚本 ./aide-program/bin/aide.sh
+# 这里展示“直接使用虚拟环境的 python”运行模块：
+aide-program/.venv/bin/python -m aide <command> [args]
 ```

 ### 6.3 依赖要求
--- a/aide-program/docs/commands/flow/README.md
+++ b/aide-program/docs/commands/flow/README.md
@@ -2,6 +2,10 @@

 本目录为 `aide flow` 子命令的**详细设计**。目标是让接手开发者在不阅读额外上下文的情况下，能够依据本文档集完成实现、联调与验证。

+实现位置：
+- 核心实现：`aide-program/aide/flow/`
+- CLI 入口：`aide-program/aide/main.py` 的 `aide flow ...` 子命令树
+
 上游/关联文档：
 - 概览设计：[`aide-program/docs/commands/flow.md`](../flow.md)
 - 数据格式规范（状态文件、提交信息）：[`aide-program/docs/formats/data.md`](../../formats/data.md)
@@ -42,7 +46,7 @@

 ## 四、推荐实现模块划分（仅文件/职责约定）

-建议在 `aide-program/aide/flow/` 下按职责拆分：
+实现位于 `aide-program/aide/flow/`，按职责拆分为：

 - `tracker`：编排一次 flow 操作（校验 → hooks → git → 落盘 → 输出）
 - `validator`：环节/动作校验（基于 phases 列表）
--- a/docs/aide-overview.md
+++ b/docs/aide-overview.md
@@ -83,6 +83,7 @@ Aide 是一套面向 Claude Code 的工作流辅助体系，旨在解决 AI 辅
 | **导览** | [aide-program/docs/README.md](../aide-program/docs/README.md) | program 整体介绍和索引 |
 | env 子命令 | [aide-program/docs/commands/env.md](../aide-program/docs/commands/env.md) | 环境检测与修复 |
 | flow 子命令 | [aide-program/docs/commands/flow.md](../aide-program/docs/commands/flow.md) | 进度追踪与 git 集成 |
+| flow 详细设计 | [aide-program/docs/commands/flow/README.md](../aide-program/docs/commands/flow/README.md) | flow 实现细节与验证清单 |
 | decide 子命令 | [aide-program/docs/commands/decide.md](../aide-program/docs/commands/decide.md) | 待定项 Web 确认 |
 | init 子命令 | [aide-program/docs/commands/init.md](../aide-program/docs/commands/init.md) | 初始化 .aide 目录 |
 | 配置格式 | [aide-program/docs/formats/config.md](../aide-program/docs/formats/config.md) | config.toml 规范 |