✨ feat: 完成文档拆分
This commit is contained in:
353
aide-program/docs/commands/decide.md
Normal file
353
aide-program/docs/commands/decide.md
Normal file
@@ -0,0 +1,353 @@
|
||||
# aide decide 子命令设计文档
|
||||
|
||||
## 一、背景
|
||||
|
||||
### 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)
|
||||
Reference in New Issue
Block a user