✨ feat: 文档同步

2025-12-15 18:53:39 +08:00
parent 67162d2337
commit 1329643932
16 changed files with 987 additions and 85 deletions
--- a/aide-program/docs/README.md
+++ b/aide-program/docs/README.md
@@ -47,7 +47,12 @@ 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 start` | [commands/flow.md](commands/flow.md) | ✅ 已实现 | 开始新任务 |
+| `aide flow next-part` | [commands/flow.md](commands/flow.md) | ✅ 已实现 | 进入下一阶段 |
+| `aide flow next-step` | [commands/flow.md](commands/flow.md) | ✅ 已实现 | 记录步骤完成 |
+| `aide flow status` | [commands/flow.md](commands/flow.md) | ✅ 已实现 | 查看当前任务状态 |
+| `aide flow list` | [commands/flow.md](commands/flow.md) | ✅ 已实现 | 列出所有任务 |
+| `aide flow show` | [commands/flow.md](commands/flow.md) | ✅ 已实现 | 查看指定任务详情 |
 | `aide decide submit` | [commands/decide.md](commands/decide.md) | ✅ 已实现 | 提交待定项并启动 Web 服务 |
 | `aide decide result` | [commands/decide.md](commands/decide.md) | ✅ 已实现 | 获取用户决策结果 |

@@ -175,10 +180,20 @@ aide-program/

 ```
 .aide/
-├── config.toml          # 项目配置
+├── config.toml          # 项目配置（自文档化）
 ├── flow-status.json     # 当前任务进度状态
+├── archive/             # 已完成任务归档
+│   └── {task_id}.json
 ├── decisions/           # 待定项决策记录
 │   └── {timestamp}.json
+├── diagrams/            # 流程图文件
+│   └── {task_id}/
+│       ├── *.puml       # PlantUML 源文件
+│       └── *.png        # 生成的图片
+├── project-docs/        # 项目文档（由 /aide:docs 生成）
+│   ├── README.md        # 总导览
+│   ├── block-plan.md    # 区块计划
+│   └── blocks/          # 子区块文档
 └── logs/                # 操作日志
 ```

@@ -186,6 +201,7 @@ aide-program/

 - `aide init` 时自动检查 `.gitignore`
 - 默认添加 `.aide/` 为忽略项
+- 可通过配置 `general.gitignore_aide = false` 禁用此行为

 ---

--- a/aide-program/docs/commands/flow.md
+++ b/aide-program/docs/commands/flow.md
@@ -153,6 +153,68 @@ aide flow error "<描述>"
 ✗ 错误已记录: <描述>
 ```

+### 3.8 aide flow status
+
+**用途**：查看当前任务状态
+
+**语法**：
+```
+aide flow status
+```
+
+**输出**：
+```
+→ 当前任务: <task_id>
+→ 环节: <current_phase>
+→ 步骤: <current_step>
+→ 开始时间: <started_at>
+```
+
+无活跃任务时：
+```
+→ 无活跃任务
+```
+
+### 3.9 aide flow list
+
+**用途**：列出所有任务（当前 + 已归档）
+
+**语法**：
+```
+aide flow list
+```
+
+**输出**：
+```
+→ 当前任务:
+  <task_id> (<current_phase>, step <n>)
+
+→ 已归档任务:
+  <task_id_1> (finish)
+  <task_id_2> (finish)
+```
+
+### 3.10 aide flow show
+
+**用途**：查看指定任务的详细信息
+
+**语法**：
+```
+aide flow show <task_id>
+```
+
+**输出**：
+```
+→ 任务: <task_id>
+→ 环节: <current_phase>
+→ 步骤: <current_step>
+→ 开始时间: <started_at>
+
+→ 历史记录:
+  [1] <timestamp> <action> <phase> step=<n>: <summary>
+  [2] ...
+```
+
 ---

 ## 四、业务流程
@@ -377,8 +439,8 @@ class FlowValidator:

 | 依赖方 | 说明 |
 |--------|------|
-| /aide:prep | 调用 flow start、next-step |
-| /aide:exec | 调用 flow next-part、next-step、issue、error |
+| /aide:run | 调用 flow start、next-part、next-step、status、issue、error |
+| /aide:load | 调用 flow status 检查任务状态 |

 ---

@@ -410,6 +472,6 @@ class FlowValidator:
 - [program 导览](../README.md)
 - [flow 详细设计（交接包）](flow/README.md)
 - [数据格式文档](../formats/data.md)
- [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md)
- [/aide:prep 命令设计](../../../aide-marketplace/aide-plugin/docs/commands/prep.md)
- [/aide:exec 命令设计](../../../aide-marketplace/aide-plugin/docs/commands/exec.md)
+- [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skills/aide/SKILL.md)
+- [/aide:run 命令设计](../../../aide-marketplace/aide-plugin/docs/commands/run.md)
+- [/aide:load 命令设计](../../../aide-marketplace/aide-plugin/docs/commands/load.md)
--- a/aide-program/docs/formats/config.md
+++ b/aide-program/docs/formats/config.md
@@ -21,6 +21,11 @@ aide 使用 TOML 格式的配置文件，位于 `.aide/config.toml`。

 ```toml
 # Aide 默认配置（由 aide init 生成）
+# 本配置文件采用自文档化设计，所有字段均有注释说明
+
+# general: 通用设置
+[general]
+gitignore_aide = true    # 是否自动将 .aide/ 添加到 .gitignore

 # runtime: aide 自身运行要求
 [runtime]
@@ -49,10 +54,19 @@ path = ".venv"
 [env.requirements]
 path = "requirements.txt"

+# docs: 项目文档配置
+[docs]
+path = ".aide/project-docs"  # 项目文档存放路径
+
 # flow: 流程配置
 [flow]
 phases = ["task-optimize", "flow-design", "impl", "verify", "docs", "finish"]

+# plantuml: PlantUML 配置
+[plantuml]
+jar_path = ""            # plantuml.jar 路径，为空时使用内置 jar
+diagram_path = ".aide/diagrams"  # 流程图存放路径
+
 # decide: 待定项确认服务配置
 [decide]
 port = 3721
@@ -63,7 +77,17 @@ timeout = 0

 ## 四、字段详解

-### 4.1 [runtime] 运行时配置
+### 4.1 [general] 通用设置
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `gitignore_aide` | bool | `true` | 是否自动将 .aide/ 添加到 .gitignore |
+
+**使用场景**：
+- `aide init` 时检查此配置，决定是否修改 .gitignore
+- 设为 `false` 可将 .aide/ 纳入版本控制
+
+### 4.2 [runtime] 运行时配置

 | 字段 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
@@ -74,7 +98,7 @@ timeout = 0
 - `aide env ensure --runtime` 使用硬编码的 `"3.11"`
 - `aide env ensure` 读取 `python_min` 进行检查

-### 4.2 [task] 任务文档配置
+### 4.3 [task] 任务文档配置

 | 字段 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
@@ -82,12 +106,12 @@ timeout = 0
 | `spec` | string | `"task-spec.md"` | 任务细则文档默认路径 |

 **使用场景**：
- `/aide:prep` 未传参数时，使用 `source` 作为默认路径
- `/aide:exec` 未传参数时，使用 `spec` 作为默认路径
+- `/aide:run` 未传参数时，使用 `source` 作为默认路径
+- `/aide:run` 续接任务时，使用 `spec` 读取任务细则

-### 4.3 [env] 环境配置
+### 4.4 [env] 环境配置

-#### 4.3.1 模块列表
+#### 4.4.1 模块列表

 | 字段 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
@@ -109,7 +133,7 @@ timeout = 0

 **模块实例化命名**：支持 `模块类型:实例名` 格式，用于同类型多实例场景。

-#### 4.3.2 模块配置
+#### 4.4.2 模块配置

 **类型A模块（可选配置）**：

@@ -151,7 +175,17 @@ manager = "pnpm"
 - `aide env list` 显示所有可用模块及启用状态
 - `aide env ensure --modules X,Y` 检测指定模块

-### 4.4 [flow] 流程配置
+### 4.5 [docs] 项目文档配置
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `path` | string | `".aide/project-docs"` | 项目文档存放路径 |
+
+**使用场景**：
+- `/aide:docs` 创建和更新项目文档时使用此路径
+- `/aide:load` 载入项目文档时读取此路径
+
+### 4.6 [flow] 流程配置

 | 字段 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
@@ -161,7 +195,18 @@ manager = "pnpm"
 - `aide flow` 校验环节跳转合法性
 - 定义有效的环节名称

-### 4.5 [decide] 待定项确认配置
+### 4.7 [plantuml] PlantUML 配置
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `jar_path` | string | `""` | plantuml.jar 路径，为空时使用内置 jar |
+| `diagram_path` | string | `".aide/diagrams"` | 流程图存放路径 |
+
+**使用场景**：
+- `aide flow next-part` 离开 flow-design 时校验和生成流程图
+- 支持自定义 jar 路径以使用特定版本的 PlantUML
+
+### 4.8 [decide] 待定项确认配置

 | 字段 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
@@ -315,4 +360,5 @@ modules = ["python", "uv", "venv", "requirements"]
 - [program 导览](../README.md)
 - [aide init 设计](../commands/init.md)
 - [aide env 设计](../commands/env.md)
- [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md)
+- [aide flow 设计](../commands/flow.md)
+- [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skills/aide/SKILL.md)