agent-aide/.aide/project-docs/blocks/aide-program-decide.md

aide-program-decide

路径：aide-program/aide/decide/ 最后更新：2025-12-17

概述

待定项确认模块，提供 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	源码	模块入口，导出 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	前端交互逻辑

核心组件

DecideStorage 类

• 职责：管理 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 类

• 职责：HTTP 服务器生命周期管理
• 位置：aide/decide/server.py:26
• 关键方法：
  • start() - 前台启动服务
  • start_daemon(pid) - 后台启动服务
  • stop(reason) - 停止服务
  • _find_available_port() - 自动探测可用端口
  • _serve_forever() - 服务循环

DecideHandlers 类

• 职责：HTTP 请求路由和处理
• 位置：aide/decide/handlers.py:17
• 关键方法：
  • handle(method, path, body) - 请求分发
  • handle_get_items() - GET /api/items
  • handle_submit(body) - POST /api/submit
  • _validate_decisions() - 验证决策数据完整性

DecideInput 数据类

• 职责：待定项输入数据封装
• 位置：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 命令）：

{
  "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 命令）：

{
  "decisions": [
    {"id": 1, "chosen": "a", "note": "用户备注"}
  ]
}

接口说明

CLI 使用

# 提交待定项，启动 Web 服务
aide decide submit ./pending-items.json

# 获取决策结果
aide decide result

配置项

在 [decide] 节：

• port - 起始端口（默认 3721）
• bind - 监听地址（默认 127.0.0.1）
• url - 自定义访问地址
• timeout - 超时时间（秒，0 表示不超时）

依赖关系

• 依赖：aide/core（ConfigManager、output）、aide/flow/utils（now_task_id）
• 被依赖：aide/main.py

注意事项

• 服务以后台进程运行，用户提交后自动关闭
• 决策记录保存在 .aide/decisions/{session_id}.json
• Web 界面支持响应式设计，移动端友好
• 支持推荐选项默认选中
• 选项的 value 在同一待定项中必须唯一