# aide decide 子命令设计文档

## 零、详细设计文档包

本文档为概览设计；更细的实现交接规格见：

- [aide-program/docs/commands/decide/README.md](decide/README.md)
- [aide-program/docs/commands/decide/cli.md](decide/cli.md)
- [aide-program/docs/commands/decide/server.md](decide/server.md)
- [aide-program/docs/commands/decide/web.md](decide/web.md)
- [aide-program/docs/commands/decide/storage.md](decide/storage.md)
- [aide-program/docs/commands/decide/verification.md](decide/verification.md)

## 一、背景

### 1.1 解决的问题

| 问题 | 影响 |
|------|------|
| 待定项呈现繁琐 | LLM 输出大量文本描述选项 |
| 用户确认不便 | 在终端中逐项确认效率低 |
| 决策记录分散 | 难以追溯历史决策 |

### 1.2 设计目标

提供**程序化的待定项确认机制**：
- LLM 传入精简 JSON 数据
- 程序启动 Web 服务，提供可视化界面
- 用户在 Web 界面操作
- LLM 读取精简决策结果

---

## 二、职责

### 2.1 做什么

1. 接收待定项 JSON 数据
2. 启动 HTTP 服务
3. 提供 Web 界面供用户操作
4. 存储用户决策
5. 返回决策结果

### 2.2 不做什么

- 不分析待定项内容
- 不做决策建议
- 不修改业务代码

---

## 三、接口规格

### 3.1 aide decide（提交数据）

**用途**：提交待定项数据并启动 Web 服务

**语法**：
```
aide decide '<json数据>'
```

**输入**：待定项 JSON 数据（见数据格式章节）

**输出**：
```
→ Web 服务已启动
→ 请访问: http://localhost:3721
→ 等待用户完成决策...
```

### 3.2 aide decide result

**用途**：获取用户决策结果

**语法**：
```
aide decide result
```

**输出**：
```json
{
  "decisions": [
    {"id": 1, "chosen": "option_a"},
    {"id": 2, "chosen": "option_b", "note": "用户的补充说明"}
  ]
}
```

**错误情况**：
```
✗ 尚无决策结果，请等待用户完成操作
```

```
✗ 未找到待定项数据，请先执行 aide decide '<json>'
```

---

## 四、业务流程

### 4.1 整体流程

```
@startuml
skinparam defaultFontName "PingFang SC"

participant LLM
participant "aide decide" as Decide
participant "Web Server" as Web
participant User

LLM -> Decide : aide decide '<json>'
Decide -> Decide : 解析 JSON
Decide -> Decide : 保存待定项数据
Decide -> Web : 启动 HTTP 服务
Decide --> LLM : 输出访问链接

LLM -> User : 告知访问链接

User -> Web : 访问页面
Web -> User : 渲染待定项界面
User -> Web : 选择选项、添加备注
User -> Web : 提交决策
Web -> Web : 保存决策结果

LLM -> Decide : aide decide result
Decide -> Decide : 读取决策结果
Decide --> LLM : 返回 JSON 结果

@enduml
```

### 4.2 Web 服务流程

```
@startuml
skinparam defaultFontName "PingFang SC"

start

:接收 JSON 数据;

:解析并验证格式;
if (格式有效?) then (是)
else (否)
  :输出错误信息;
  stop
endif

:保存到 .aide/decisions/pending.json;

:启动 HTTP 服务;
note right: 默认端口 3721

:输出访问链接;

:等待用户操作;

:用户提交决策;

:保存决策结果;
note right: .aide/decisions/{timestamp}.json

:关闭 HTTP 服务;

stop
@enduml
```

---

## 五、数据结构

### 5.1 输入格式（LLM → 程序）

```
DecideInput:
    task: str                    # 任务简述
    source: str                  # 来源文档
    items: list[DecideItem]      # 待定项列表

DecideItem:
    id: int                      # 待定项 ID
    title: str                   # 问题标题
    location: Location | None    # 原文位置（可选）
    context: str | None          # 详细说明（可选）
    options: list[Option]        # 选项列表
    recommend: str | None        # 推荐选项的 value（可选）

Location:
    file: str                    # 文件路径
    start: int                   # 起始行
    end: int                     # 结束行

Option:
    value: str                   # 选项标识
    label: str                   # 选项描述
    score: int | None            # 评分（可选）
    pros: list[str] | None       # 优点列表（可选）
    cons: list[str] | None       # 缺点列表（可选）
```

### 5.2 输出格式（程序 → LLM）

```
DecideOutput:
    decisions: list[Decision]    # 决策列表

Decision:
    id: int                      # 待定项 ID
    chosen: str                  # 选中的选项 value
    note: str | None             # 用户备注（可选）
```

### 5.3 方法签名原型

```
class DecideServer:
    root: Path
    port: int                    # 默认 3721
    pending_path: Path           # .aide/decisions/pending.json
    decisions_dir: Path          # .aide/decisions/

    submit(json_data: str) -> bool
        # 提交待定项数据，启动服务

    get_result() -> DecideOutput | None
        # 获取决策结果

    _parse_input(json_data: str) -> DecideInput
        # 解析输入 JSON

    _validate_input(data: DecideInput) -> bool
        # 验证输入格式

    _start_server() -> None
        # 启动 HTTP 服务

    _stop_server() -> None
        # 停止 HTTP 服务

    _save_pending(data: DecideInput) -> None
        # 保存待定项数据

    _save_result(result: DecideOutput) -> None
        # 保存决策结果

    _load_result() -> DecideOutput | None
        # 加载决策结果
```

### 5.4 Web 界面组件

```
DecideApp:
    # React 前端应用

    state:
        items: list[DecideItem]      # 待定项列表
        decisions: dict[int, str]    # 当前选择
        notes: dict[int, str]        # 用户备注

    methods:
        loadItems() -> None          # 加载待定项
        selectOption(id, value) -> None  # 选择选项
        addNote(id, note) -> None    # 添加备注
        submit() -> None             # 提交决策
```

---

## 六、Web 界面设计

### 6.1 页面结构

```
┌─────────────────────────────────────────────────┐
│  Aide 待定项确认                                 │
│  任务: <task>                                   │
├─────────────────────────────────────────────────┤
│                                                  │
│  ┌─────────────────────────────────────────┐    │
│  │ 1. <title>                               │    │
│  │    <context>                             │    │
│  │                                          │    │
│  │    ○ <option_a.label>  [推荐]            │    │
│  │      优点: ...  缺点: ...                │    │
│  │                                          │    │
│  │    ○ <option_b.label>                    │    │
│  │      优点: ...  缺点: ...                │    │
│  │                                          │    │
│  │    备注: [________________]              │    │
│  └─────────────────────────────────────────┘    │
│                                                  │
│  ┌─────────────────────────────────────────┐    │
│  │ 2. <title>                               │    │
│  │    ...                                   │    │
│  └─────────────────────────────────────────┘    │
│                                                  │
│                              [提交决策]          │
└─────────────────────────────────────────────────┘
```

### 6.2 交互流程

1. 页面加载时从后端获取待定项数据
2. 用户点击选项进行选择
3. 用户可选择性添加备注
4. 点击"提交决策"按钮
5. 前端发送决策到后端
6. 后端保存结果并关闭服务
7. 页面显示"决策已提交"

---

## 七、依赖

| 依赖项 | 类型 | 说明 |
|--------|------|------|
| output | 内部模块 | 输出格式化 |
| http.server | 标准库 | HTTP 服务 |
| json | 标准库 | JSON 解析 |

---

## 八、被依赖

| 依赖方 | 说明 |
|--------|------|
| /aide:prep | 调用 decide 处理待定项 |

---

## 九、修改指南

### 9.1 修改输入/输出格式

1. 更新本文档的数据结构章节
2. 修改代码实现
3. 同步更新 [数据格式文档](../formats/data.md)
4. 同步更新 [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md)

### 9.2 修改 Web 界面

1. 更新本文档的界面设计章节
2. 修改 `aide/decide/web/` 下的前端代码

### 9.3 修改端口配置

1. 在配置文件中添加端口配置项
2. 修改 `DecideServer` 读取配置
3. 更新 [配置格式文档](../formats/config.md)

---

## 十、相关文档

- [program 导览](../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)