# 用户反馈系统设计文档

## 文档维护规范

0. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现
1. **文档分层，链接代码** - 重要或复杂设计可以另有详细文档；关键实现需标注代码文件路径
2. **简洁快照，日志分离** - 只记录最重要的、与代码准确对应的或者明确的已完成的设计的信息

---

## 策略总览

> 本节汇总全文的核心设计决策，方便实现前快速对齐。详细说明见各章节。

### 反馈动作语义（`action`）

| 值 | 含义 | 后端处理 |
|---|---|---|
| `confirm` | 同意 Agent 评估 | 对应计数 +1，history 追加 `action="confirm"` |
| `override` | 重新评估，覆盖 Agent 结果 | 按新 `eval_status` 计数 +1，history 追加 `action="override"` |
| `skip` | 跳过，不确定 | 不做任何操作 |

### 反馈来源语义（`source`）

| 值 | 含义 |
|---|---|
| `agent` | 由 Agent 自动评估 |
| `user` | 由人工在 Trace 前端提交 |

### 知识验证状态语义（`verification.status`）

| 值 | 含义 |
|---|---|
| `approved` | 经去重审核自动通过，等待人工验证 |
| `checked` | 人工已验证通过 |

### UX 原则

- 默认所有知识选中「跳过」，只对有信心的知识反馈，降低参与门槛
- 「同意 Agent 评估」一键确认，无需额外输入
- 底部按钮实时显示已反馈数量（跳过不计入）
- 支持键盘快捷键：Enter 提交，Esc 取消

### 实现优先级

| 优先级 | 内容 |
|---|---|
| **P0** | Knowledge Log 反馈弹窗（Trace 前端）、知识验证界面（知识库前端）、API 接口、数据模型扩展 |
| **P1** | Goal 反馈创建知识、Message 反馈创建知识、批量验证 |
| **P2** | 反馈统计可视化、知识质量趋势分析、反馈提醒通知 |

---

## 背景与目标

### 现状
- Agent 自动评估知识的可用性（helpful/harmful/unused/irrelevant/neutral）
- 评估结果记录在 `knowledge_log.json` 中
- 缺少人类验证和反馈的闭环

### 目标
1. **Trace 前端反馈**：用户可以对知识使用情况、Goal、执行步骤进行反馈
2. **知识库前端验证**：用户可以验证自己 owner 的知识，将 `approved` 状态提升为 `checked`
3. **反馈闭环**：记录反馈来源（trace/人）、支持部分反馈（只对有信心的知识评价）
4. **溯源能力**：记录反馈人、来源 trace、时间戳等信息

---

## 前端架构说明

当前 Trace 前端采用 React + TypeScript，主要组件结构：

```
┌─────────────────────────────────────────────────────────────────────┐
│ TopBar (顶部工具栏)                                                  │
│ [Trace选择器▼] trace-20260324-abc  [📚知识反馈] [刷新] [其他]      │
├──────────────────────────────────────┬──────────────────────────────┤
│ MainContent (主内容区)                │ DetailPanel (详情面板)       │
│ ┌────────────────────────────────┐  │ ┌──────────────────────────┐ │
│ │ FlowChart (流程图可视化)        │  │ │ 节点详情            [×] │ │
│ │                                │  │ ├──────────────────────────┤ │
│ │  ┌──┐  Goal节点               │  │ │ Goal ID: 2.1             │ │
│ │  │G1│                          │  │ │ 状态: completed          │ │
│ │  └┬─┘                          │  │ │ 描述: 定位导出按钮        │ │
│ │   │                            │  │ │                          │ │
│ │  ┌▼──┐ Message节点             │  │ │ 💬 反馈 (新增按钮)       │ │
│ │  │M42│                         │  │ │                          │ │
│ │  └───┘                         │  │ │ 注入知识: 3条            │ │
│ │                                │  │ │ [知识列表显示...]        │ │
│ │                                │  │ │                          │ │
│ │                                │  │ │ 消息历史:                │ │
│ │                                │  │ │ [消息列表...]            │ │
│ └────────────────────────────────┘  │ └──────────────────────────┘ │
└──────────────────────────────────────┴──────────────────────────────┘
```

**组件说明**：
- **TopBar**：顶部工具栏，包含 trace 选择器和操作按钮
- **MainContent**：包含 FlowChart，显示 Goal 和 Message 节点的流程图
- **DetailPanel**：右侧详情面板，点击节点后显示详细信息
  - 点击 Goal 节点 → 显示 Goal 详情 + 该 Goal 下的所有 messages
  - 点击 Message 节点 → 显示该 Message 的详细内容

---

## 一、Trace 前端反馈系统

### 1.1 知识使用反馈（Knowledge Log）

#### 界面位置 A：TopBar 添加全局反馈按钮

在 TopBar 右侧按钮组添加「📚 知识反馈」按钮：

```
┌─────────────────────────────────────────────────────────────────────┐
│ [Trace选择器 ▼] trace-20260324-abc123                               │
│                                    [📚 知识反馈] [刷新] [其他按钮]   │
└─────────────────────────────────────────────────────────────────────┘
                                           ↑
                                      新增按钮
```

**实现文件**：`frontend/react-template/src/components/TopBar/TopBar.tsx`

**按钮状态**：
- 默认：灰色，显示「📚 知识反馈」
- 有待反馈：橙色，显示「📚 知识反馈 (5)」← 数字表示待反馈数量
- 已反馈：绿色，显示「✅ 已反馈」

#### 弹窗设计

**触发**：点击 TopBar 的「📚 知识反馈」按钮

**弹窗结构**（实际效果）：

```
┌────────────────────────────────────────────────────────────────────────┐
│  知识使用反馈 - trace-20260324-abc123                          [×]     │
├────────────────────────────────────────────────────────────────────────┤
│  💡 提示：只需对有信心的知识做反馈，不确定的可以跳过                    │
│  本次执行共注入 5 条知识，Agent 已评估 5 条，待您确认 5 条              │
│                                                                          │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │ 📚 知识 1/5                                                      │  │
│  │ ──────────────────────────────────────────────────────────────── │  │
│  │ ID: knowledge-20260320-a1b2                          ⭐ 评分: 4  │  │
│  │                                                                  │  │
│  │ 📍 注入位置: Goal 2.1 "定位导出按钮" (sequence 42)              │  │
│  │                                                                  │  │
│  │ 🎯 任务场景: 如何使用 selenium 处理登录验证                     │  │
│  │ 📖 知识内容: 使用 WebDriverWait 等待元素加载... [展开]          │  │
│  │                                                                  │  │
│  │ 🤖 Agent 评估: ✅ helpful                                        │  │
│  │    理由: "成功应用于登录流程，等待逻辑有效"                      │  │
│  │                                                                  │  │
│  │ ─────────────────────────────────────────────────────────────── │  │
│  │ 👤 您的反馈:                                                     │  │
│  │   ○ 同意 Agent 评估 (一键确认)                                  │  │
│  │   ○ 不同意，我要重新评估                                        │  │
│  │   ● 跳过此条 (不确定)  ← 默认选中                               │  │
│  └──────────────────────────────────────────────────────────────────┘  │
│                                                                          │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │ 📚 知识 2/5                                                      │  │
│  │ ──────────────────────────────────────────────────────────────── │  │
│  │ ID: knowledge-20260318-c3d4                          ⭐ 评分: 3  │  │
│  │ 📍 注入位置: Goal 2.1 (sequence 42)                             │  │
│  │ 🎯 任务场景: 如何处理 CAPTCHA 验证码                            │  │
│  │ 📖 知识内容: 使用第三方打码平台...                              │  │
│  │ 🤖 Agent 评估: ⚠️ unused - "未在执行中使用"                     │  │
│  │                                                                  │  │
│  │ 👤 您的反馈:                                                     │  │
│  │   ○ 同意    ● 不同意，重新评估  ○ 跳过  ← 用户选了重新评估     │  │
│  │                                                                  │  │
│  │   ┌────────────────────────────────────────────────────────────┐ │  │
│  │   │ 📝 重新评估 (展开)                                          │ │  │
│  │   │ 选择评估结果:                                               │ │  │
│  │   │  ○ helpful   ● harmful   ○ unused                          │ │  │
│  │   │  ○ irrelevant   ○ neutral                                  │ │  │
│  │   │                                                            │ │  │
│  │   │ 反馈说明 (可选):                                            │ │  │
│  │   │ ┌────────────────────────────────────────────────────────┐ │ │  │
│  │   │ │ 这条知识误导了我，该网站实际没有验证码              │ │ │  │
│  │   │ └────────────────────────────────────────────────────────┘ │ │  │
│  │   └────────────────────────────────────────────────────────────┘ │  │
│  └──────────────────────────────────────────────────────────────────┘  │
│                                                                          │
│  ... (其他 3 条知识，折叠显示)                                          │
│                                                                          │
├────────────────────────────────────────────────────────────────────────┤
│                    [取消]  [提交反馈 (已反馈 2/5 条)]                   │
└────────────────────────────────────────────────────────────────────────┘
```

**交互细节**：
1. 每条知识默认折叠，点击可展开/收起
2. 默认所有知识选中「跳过此条」
3. 选择「同意 Agent 评估」：直接确认，无需额外输入
4. 选择「不同意，重新评估」：下方展开评估表单
5. 底部按钮实时显示已反馈数量（跳过不计入）
6. 支持键盘快捷键：Enter 提交，Esc 取消

**实现文件**：新建 `frontend/react-template/src/components/KnowledgeFeedbackModal/`

#### 数据结构

**API 请求**：`POST /api/trace/{trace_id}/knowledge_feedback`

```json
{
  "feedback_list": [
    {
      "knowledge_id": "knowledge-20260320-a1b2",
      "action": "confirm",  // confirm | override | skip
      "eval_status": "helpful",  // 仅 action=override 时需要
      "feedback_text": "这条知识确实有用，但参数版本有点旧",  // 可选
      "source": {
        "trace_id": "trace-20260324-abc123",
        "goal_id": "2.1",
        "sequence": 42,
        "feedback_by": "user@example.com",
        "feedback_at": "2026-03-24T10:30:00Z"
      }
    }
  ]
}
```

**后端处理**：
- `action=confirm`：knowledge.eval.helpful += 1，记录到 helpful_history
- `action=override`：根据新的 eval_status 更新 helpful/harmful，记录到对应 history
- `action=skip`：不做任何操作
- 所有 history 记录包含 source 信息（trace_id, feedback_by 等）

---

### 1.2 Goal 反馈（创建新知识）

#### 界面位置 B：DetailPanel 中添加 Goal 反馈按钮

当用户在 FlowChart 中点击 Goal 节点后，DetailPanel 显示该 Goal 的详情。在详情面板顶部添加「💬 反馈」按钮：

```
┌──────────────────────────────────────┐
│ DetailPanel (右侧详情面板)            │
│ ┌────────────────────────────────┐   │
│ │ 节点详情                  [×]  │   │
│ ├────────────────────────────────┤   │
│ │ Goal ID: 2.1                   │   │
│ │ 状态: completed                │   │
│ │ 描述: 定位导出按钮              │   │
│ │                                │   │
│ │ [💬 为此 Goal 创建知识]  ← 新增 │   │
│ │                                │   │
│ │ 注入知识: 3 条                 │   │
│ │ [知识列表...]                  │   │
│ │                                │   │
│ │ 消息历史: 5 条                 │   │
│ │ [消息列表...]                  │   │
│ └────────────────────────────────┘   │
└──────────────────────────────────────┘
```

**实现文件**：`frontend/react-template/src/components/DetailPanel/DetailPanel.tsx`

**按钮位置**：在 Goal 描述下方、知识列表上方

#### 弹窗设计

**触发**：点击 Goal 右侧的 💬 按钮

**弹窗结构**：

```
┌──────────────────────────────────────────────────────────────────┐
│  为 Goal 创建知识反馈                                    [×]     │
├──────────────────────────────────────────────────────────────────┤
│                                                                    │
│  Goal 2.1 "定位导出按钮"  状态: completed                         │
│  执行摘要: 使用 XPath 定位到导出按钮并点击 (来自 goal.summary)    │
│                                                                    │
│  ─────────────────────────────────────────────────────────────   │
│  📝 创建知识                                                       │
│                                                                    │
│  知识类型 (至少选一个):                                            │
│  ☑ strategy   ☐ tool   ☐ usecase   ☐ definition   ☐ plan        │
│                                                                    │
│  任务场景 (Task):                                                  │
│  ┌──────────────────────────────────────────────────────────────┐ │
│  │ 在阿里巴巴后台定位导出按钮  ← 预填 goal.description         │ │
│  └──────────────────────────────────────────────────────────────┘ │
│                                                                    │
│  知识内容 (Content):                                               │
│  ┌──────────────────────────────────────────────────────────────┐ │
│  │ （请填写有价值的经验）                                        │ │
│  │                                                               │ │
│  └──────────────────────────────────────────────────────────────┘ │
│                                                                    │
│  初始评分: ○ 1  ○ 2  ● 3  ○ 4  ○ 5                              │
│                                                                    │
│  标签 (可选，如 platform:alibaba action:export):                  │
│  ┌──────────────────────────────────────────────────────────────┐ │
│  │                                                               │ │
│  └──────────────────────────────────────────────────────────────┘ │
│                                                                    │
├──────────────────────────────────────────────────────────────────┤
│                         [取消]  [创建知识]                         │
└──────────────────────────────────────────────────────────────────┘
```

**数据结构**：

**API 请求**：`POST /api/knowledge`（复用现有接口，增加 source 信息）

```json
{
  "task": "在阿里巴巴后台定位导出按钮",
  "content": "导出按钮的 XPath 为 //button[@data-action='export']...",
  "types": ["strategy"],
  "tags": {"platform": "alibaba", "action": "export"},
  "score": 3,
  "source": {
    "name": "user_feedback",
    "category": "exp",
    "trace_id": "trace-20260324-abc123",
    "goal_id": "2.1",
    "submitted_by": "user@example.com",
    "timestamp": "2026-03-24T10:30:00Z"
  }
}
```

**后端处理**：
- 知识状态设为 `pending`，进入去重队列
- source 中记录完整的溯源信息

---

### 1.3 执行步骤反馈（Message 级别）

#### 界面位置 C：DetailPanel 中的 Message 列表添加反馈按钮

当用户点击 Goal 节点后，DetailPanel 显示该 Goal 下的所有 messages。在每条 message 右上角添加「💬」按钮：

```
┌──────────────────────────────────────┐
│ DetailPanel                          │
│ ┌────────────────────────────────┐   │
│ │ 节点详情 - Goal 2.1       [×]  │   │
│ ├────────────────────────────────┤   │
│ │ ... Goal 信息 ...              │   │
│ │                                │   │
│ │ 消息历史: 5 条                 │   │
│ │ ┌──────────────────────────┐   │   │
│ │ │ [user] #41          💬   │   │   │
│ │ │ 请定位导出按钮            │   │   │
│ │ └──────────────────────────┘   │   │
│ │                                │   │
│ │ ┌──────────────────────────┐   │   │
│ │ │ [assistant] #42     💬   │   │   │
│ │ │ 我将使用 XPath 定位...    │   │   │
│ │ │ Tool: browser_find(...)   │   │   │
│ │ └──────────────────────────┘   │   │
│ │                                │   │
│ │ ┌──────────────────────────┐   │   │
│ │ │ [tool] #43          💬   │   │   │
│ │ │ 找到元素: button[@data...│   │   │
│ │ └──────────────────────────┘   │   │
│ └────────────────────────────────┘   │
└──────────────────────────────────────┘
```

**实现文件**：`frontend/react-template/src/components/DetailPanel/DetailPanel.tsx`

**按钮位置**：每条 message 卡片右上角

#### 弹窗设计

**触发**：点击消息右上角的 💬 按钮

**弹窗结构**：

```
┌──────────────────────────────────────────────────────────────────┐
│  为执行步骤创建知识反馈 - #42 (Goal 2.1)                 [×]     │
├──────────────────────────────────────────────────────────────────┤
│                                                                    │
│  [assistant] #42                                                  │
│  ┌──────────────────────────────────────────────────────────────┐ │
│  │ 我将使用 XPath 定位导出按钮...                               │ │
│  │ Tool: browser_find(xpath="//button[@data-action='export']")  │ │
│  └──────────────────────────────────────────────────────────────┘ │
│                                                                    │
│  ─────────────────────────────────────────────────────────────   │
│  反馈类型:                                                         │
│  ● 创建新知识（记录有价值的经验）                                  │
│  ○ 报告问题（此步骤有误或可改进，不创建知识）                      │
│                                                                    │
│  ── 创建新知识 ────────────────────────────────────────────────   │
│  知识类型: ☑ tool   ☐ strategy   ☐ usecase   ☐ definition        │
│                                                                    │
│  任务场景 (Task):                                                  │
│  ┌──────────────────────────────────────────────────────────────┐ │
│  │ 在后台页面定位导出按钮                                       │ │
│  └──────────────────────────────────────────────────────────────┘ │
│                                                                    │
│  知识内容 (Content):                                               │
│  ┌──────────────────────────────────────────────────────────────┐ │
│  │ 导出按钮 XPath: //button[@data-action='export']              │ │
│  │ 需在页面 DOMContentLoaded 后再查找                           │ │
│  └──────────────────────────────────────────────────────────────┘ │
│                                                                    │
│  初始评分: ○ 1  ○ 2  ● 3  ○ 4  ○ 5                              │
│                                                                    │
├──────────────────────────────────────────────────────────────────┤
│                         [取消]  [创建知识]                         │
└──────────────────────────────────────────────────────────────────┘
```

**数据结构**：
- 创建新知识：同 Goal 反馈，source 中额外记录 `message_id`、`sequence`、`role`
- 报告问题：仅记录到 trace metadata 的 feedback 列表中，不创建知识

---

## 二、知识库前端验证系统

### 2.1 知识验证界面

> 注：知识库前端为独立系统（KnowHub 管理页面），与 Trace 前端分开部署

#### 整体布局

```
┌──────────────────────────────────────────────────────────────────────┐
│ KnowHub 知识库管理                                                    │
├──────────────────────────────────────────────────────────────────────┤
│ [全部] [待验证 (12)] [已验证]  筛选: [Owner: 我的知识▼] [类型▼]      │
├──────────────────────────────────────────────────────────────────────┤
│                                                                        │
│  ☐ knowledge-20260320-a1b2                             ⭐ 3/5  💬 3  │
│  ────────────────────────────────────────────────────────────────── │
│  Task: 如何使用 selenium 处理登录验证                                 │
│  Content: 使用 WebDriverWait 等待元素加载完成...（截断显示）          │
│                                                                        │
│  Owner: user@example.com  │  来源: trace-20260320 > Goal 2.1         │
│  创建: 2026-03-20 10:00  │  使用: helpful 3 / harmful 0              │
│                                                                        │
│  [查看详情]  [✓ 验证通过]  [✗ 标记问题]                              │
│                                                                        │
│  ──────────────────────────────────────────────────────────────────  │
│                                                                        │
│  ☐ knowledge-20260318-c3d4                             ⭐ 4/5  💬 1  │
│  ────────────────────────────────────────────────────────────────── │
│  Task: 如何处理 CAPTCHA 验证码                                        │
│  Content: 使用第三方打码平台 API...（截断显示）                        │
│                                                                        │
│  Owner: user@example.com  │  来源: trace-20260318 > Goal 1.2         │
│  创建: 2026-03-18 14:30  │  使用: helpful 1 / harmful 0              │
│                                                                        │
│  [查看详情]  [✓ 验证通过]  [✗ 标记问题]                              │
│                                                                        │
│  ... (更多知识)                                                        │
│                                                                        │
├──────────────────────────────────────────────────────────────────────┤
│  ☐ 全选 (0/12)                            [批量验证通过 (0)]          │
└──────────────────────────────────────────────────────────────────────┘
```

#### 「查看详情」展开

点击「查看详情」，知识条目展开显示完整信息：

```
│  ☑ knowledge-20260320-a1b2                             ⭐ 3/5  💬 3  │
│  ────────────────────────────────────────────────────────────────── │
│  Task: 如何使用 selenium 处理登录验证                                 │
│  Content:                                                             │
│  ┌────────────────────────────────────────────────────────────────┐  │
│  │ 使用 WebDriverWait 等待元素加载完成：                           │  │
│  │ element = WebDriverWait(driver, 10).until(                      │  │
│  │   EC.presence_of_element_located((By.XPATH, "//input[@id='.."])) │  │
│  │ 避免直接 find_element 导致 NoSuchElement 异常                  │  │
│  └────────────────────────────────────────────────────────────────┘  │
│                                                                        │
│  类型: strategy | tool                                                │
│  标签: platform=selenium, action=login                                │
│                                                                        │
│  使用历史:                                                             │
│  ┌────────────────────────────────────────────────────────────────┐  │
│  │ ✅ helpful │ trace-20260322-xxx > Goal 2.1 │ agent@research    │  │
│  │ ✅ helpful │ trace-20260323-yyy > Goal 1.3 │ agent@research    │  │
│  │ 🚨 harmful │ trace-20260324-zzz > Goal 3.2 │ user@example.com  │  │
│  │            │ 理由: "该网站实际无需等待..."                     │  │
│  └────────────────────────────────────────────────────────────────┘  │
│                                                                        │
│  [✓ 验证通过]  [✗ 标记问题]                                           │
```

#### 「标记问题」弹窗

```
┌────────────────────────────────────────────────────────────┐
│  标记知识问题 - knowledge-20260320-a1b2            [×]     │
├────────────────────────────────────────────────────────────┤
│                                                              │
│  Task: 如何使用 selenium 处理登录验证                        │
│                                                              │
│  请选择问题类型:                                             │
│  ● 内容有误（知识本身不准确）                                │
│  ○ 过时（内容曾经正确，现在已不适用）                        │
│  ○ 描述模糊（task 或 content 表述不清）                     │
│  ○ 重复（与其他知识高度重叠）                                │
│                                                              │
│  处理方式:                                                   │
│  ● 降低评分（-1 分，保留此知识）                             │
│  ○ 标记为需要修改                                            │
│  ○ 删除此知识                                                │
│                                                              │
│  备注:                                                       │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ WebDriverWait 超时参数应该是可配置的，不应写死 10...    │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                              │
├────────────────────────────────────────────────────────────┤
│                   [取消]  [确认提交]                         │
└────────────────────────────────────────────────────────────┘
```

#### 验证操作
- **单个验证通过**：`status: approved → checked`，记录验证人和时间
- **标记问题**：根据处理方式降分/删除，记录原因
- **批量验证通过**：勾选多个知识，一键验证

---

## 三、数据模型扩展

### 3.1 Knowledge Schema 扩展

在 `helpful_history` / `harmful_history` 中每条记录增加溯源字段：

```json
{
  "eval": {
    "score": 3,
    "helpful": 3,
    "harmful": 0,
    "confidence": 0.8,
    "helpful_history": [
      {
        "source": "agent",
        "trace_id": "trace-20260320-xxx",
        "goal_id": "2.1",
        "sequence": 42,
        "feedback_by": "agent:research_agent",
        "feedback_at": "2026-03-20T10:05:00Z",
        "eval_status": "helpful",
        "feedback_text": "成功应用于登录流程",
        "action": "auto"
      },
      {
        "source": "user",
        "trace_id": "trace-20260322-yyy",
        "goal_id": "3.1",
        "sequence": 88,
        "feedback_by": "user@example.com",
        "feedback_at": "2026-03-22T15:30:00Z",
        "eval_status": "helpful",
        "feedback_text": "该知识有效，但超时参数建议可配置",
        "action": "confirm"
      }
    ],
    "harmful_history": []
  },

  "verification": {
    "status": "checked",
    "verified_by": "user@example.com",
    "verified_at": "2026-03-24T10:30:00Z",
    "note": "已确认此知识准确有效",
    "issue_type": null,
    "issue_action": null
  }
}
```

**`source` 字段说明**：
| 值 | 含义 |
|---|---|
| `"agent"` | 由 Agent 自动评估 |
| `"user"` | 由人工在 Trace 前端提交 |

**`action` 字段说明**：
| 值 | 含义 |
|---|---|
| `"auto"` | Agent 自动评估（未经人工确认） |
| `"confirm"` | 用户同意 Agent 评估 |
| `"override"` | 用户重新评估（覆盖 Agent 结果） |

**`verification.status` 字段说明**：
| 值 | 含义 |
|---|---|
| `"approved"` | 经过去重审核，知识自动通过，等待人工验证 |
| `"checked"` | 人工已验证通过 |

### 3.2 Trace Metadata 扩展

在 `.trace/{trace_id}/metadata.json` 中添加：

```json
{
  "trace_id": "trace-20260324-abc123",
  "task": "登录阿里巴巴后台并导出销售报表",

  "user_feedback": {
    "knowledge_feedback_submitted": true,
    "knowledge_feedback_at": "2026-03-24T10:30:00Z",
    "knowledge_feedback_by": "user@example.com",
    "knowledge_feedback_count": 3,

    "goal_feedback": [
      {
        "goal_id": "2.1",
        "knowledge_id": "knowledge-20260324-new1",
        "feedback_at": "2026-03-24T10:35:00Z"
      }
    ],

    "message_feedback": [
      {
        "sequence": 42,
        "type": "knowledge",
        "knowledge_id": "knowledge-20260324-new2",
        "feedback_at": "2026-03-24T10:40:00Z"
      }
    ]
  }
}
```

---

## 四、重新评估机制

### 4.1 核心前提：消息永远不会丢失

压缩（Compression）**只修改内存 history**，不修改存储。
原始消息永远保留在 `.trace/{trace_id}/messages/{message_id}.json`。

> 来源：`agent/trace/compaction.py` 顶部注释
> "压缩不修改存储：原始消息永远保留在 messages/，纯内存操作。"

因此，用户在 trace 执行结束后的任意时刻触发重新评估，都可以从文件系统重建出执行时的上下文。

---

### 4.2 重新评估说明

用户在弹窗中选择 `action=override` 时，将用户的 `eval_status` 写入 `helpful_history` / `harmful_history`，`source="user"`。这是纯数据记录操作，不调用 LLM。

---

### 4.3 完整后端处理流程

```
用户提交「不同意，重新评估」(action=override)
  ↓
1. 记录覆盖评估（立即写入）
   → 在 knowledge.eval.helpful_history / harmful_history 追加一条记录
   → source="user", action="override", feedback_by=user_email
   → 根据 eval_status 决定 helpful 或 harmful +1

2. 更新 trace 的 knowledge_log.json
   → 将对应 entry 的 eval_result 更新为用户的 eval_status
   → 额外字段: user_override=true, user_feedback_text=...

3. 返回前端
   → {status: "ok", updated: N}
```

---

## 五、API 接口设计

### 5.1 Trace 相关接口

#### 获取知识使用日志
```
GET /api/trace/{trace_id}/knowledge_log
Response: knowledge_log.json 内容
```

#### 提交知识反馈（含重新评估）
```
POST /api/trace/{trace_id}/knowledge_feedback
Body: {
  feedback_list: [
    {
      knowledge_id: "...",
      action: "confirm | override | skip",
      eval_status: "helpful | harmful | unused | irrelevant | neutral",
      feedback_text: "（可选说明）",
      source: {feedback_by, feedback_at}
    }
  ]
}
Response: {
  status: "ok",
  updated: 3
}
```

**后端逻辑**：
- `action=confirm`：helpful +1，history 追加 action="confirm"
- `action=override`：按 eval_status 对应计数 +1，history 追加 action="override"
- `action=skip`：不做任何操作

#### 创建基于 Goal 的知识
```
POST /api/knowledge
Body: {task, content, types, source: {trace_id, goal_id, ...}}
Response: {knowledge_id, status: "pending"}
```

#### 创建基于 Message 的知识
```
POST /api/knowledge
Body: {task, content, types, source: {trace_id, message_id, sequence, ...}}
Response: {knowledge_id, status: "pending"}
```

### 5.2 知识库相关接口

#### 获取待验证知识列表
```
GET /api/knowledge?status=approved&owner={user_email}
Response: {results: [...], count: 12}
```

#### 验证知识
```
POST /api/knowledge/{knowledge_id}/verify
Body: {action: "approve", verified_by, note}
Response: {status: "ok", new_status: "checked"}
```

#### 批量验证
```
POST /api/knowledge/batch_verify
Body: {knowledge_ids: [...], action: "approve", verified_by}
Response: {status: "ok", updated: 5}
```

---

## 五、实现优先级

### P0（核心功能）
1. Knowledge Log 反馈弹窗（Trace 前端）
2. 知识验证界面（知识库前端）
3. API 接口实现
4. 数据模型扩展

### P1（增强功能）
1. Goal 反馈创建知识
2. Message 反馈创建知识
3. 批量验证功能

### P2（优化功能）
1. 反馈统计和可视化
2. 知识质量趋势分析
3. 反馈提醒和通知

---

## 六、技术实现要点

### 6.1 前端技术栈
- React + TypeScript
- UI 组件库：Ant Design 或 Tailwind CSS
- 状态管理：React Query（API 调用）+ Zustand（本地状态）

### 6.2 关键交互
1. **弹窗管理**：使用 Modal 组件，支持嵌套和多层级
2. **表单验证**：必填字段检查、字符长度限制
3. **批量操作**：复选框选择 + 批量提交
4. **实时更新**：提交后自动刷新列表，显示最新状态

### 6.3 性能优化
1. 知识列表分页加载（已有）
2. 反馈提交防抖（避免重复提交）
3. 大量知识时虚拟滚动

---

## 七、用户体验设计

### 7.1 反馈流程简化
- 默认「跳过」，只对有信心的知识反馈
- 「同意 Agent 评估」一键确认，无需额外输入
- 批量操作减少重复点击

### 7.2 信息透明
- 显示知识来源（trace、goal、提交人）
- 显示使用历史（helpful/harmful 计数和详情）
- 显示验证状态和验证人

### 7.3 错误处理
- 网络错误时显示友好提示
- 部分提交失败时显示详细错误信息
- 支持重试机制

---

## 八、测试计划

### 8.1 单元测试
- API 接口测试（反馈提交、验证操作）
- 数据模型测试（history 记录、status 更新）

### 8.2 集成测试
- Trace 前端 → API → 知识库更新
- 知识库前端 → API → status 更新

### 8.3 用户测试
- 反馈流程是否流畅
- 界面是否清晰易懂
- 批量操作是否高效

---

## 九、后续优化方向

1. **智能推荐**：根据用户反馈历史，推荐可能需要验证的知识
2. **协作验证**：多人协作验证同一知识，达成共识后更新状态
3. **反馈分析**：分析用户反馈模式，优化 Agent 评估算法