[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/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 在同一待定项中必须唯一