用户反馈系统设计文档

文档维护规范

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

策略总览

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

反馈动作语义（`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 中
缺少人类验证和反馈的闭环

目标

Trace 前端反馈：用户可以对知识使用情况、Goal、执行步骤进行反馈
知识库前端验证：用户可以验证自己 owner 的知识，将 approved 状态提升为 checked
反馈闭环：记录反馈来源（trace/人）、支持部分反馈（只对有信心的知识评价）
溯源能力：记录反馈人、来源 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 条)]                   │
└────────────────────────────────────────────────────────────────────────┘

交互细节：

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

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

数据结构

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

{
  "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 信息）

{
  "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 中每条记录增加溯源字段：

{
  "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 中添加：

{
  "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（核心功能）

Knowledge Log 反馈弹窗（Trace 前端）
知识验证界面（知识库前端）
API 接口实现
数据模型扩展

P1（增强功能）

Goal 反馈创建知识
Message 反馈创建知识
批量验证功能

P2（优化功能）

反馈统计和可视化
知识质量趋势分析
反馈提醒和通知

六、技术实现要点

6.1 前端技术栈

React + TypeScript
UI 组件库：Ant Design 或 Tailwind CSS
状态管理：React Query（API 调用）+ Zustand（本地状态）

6.2 关键交互

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

6.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 用户测试

反馈流程是否流畅
界面是否清晰易懂
批量操作是否高效

九、后续优化方向

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

user-feedback-plan.md 45 KB Histórico Raw

用户反馈系统设计文档

文档维护规范

策略总览

反馈动作语义（action）

反馈来源语义（source）

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

UX 原则

实现优先级

背景与目标

现状

目标

前端架构说明

一、Trace 前端反馈系统

1.1 知识使用反馈（Knowledge Log）

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

弹窗设计

数据结构

1.2 Goal 反馈（创建新知识）

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

弹窗设计

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

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

弹窗设计

二、知识库前端验证系统

2.1 知识验证界面

整体布局

「查看详情」展开

「标记问题」弹窗

验证操作

三、数据模型扩展

3.1 Knowledge Schema 扩展

3.2 Trace Metadata 扩展

四、重新评估机制

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

4.2 重新评估说明

4.3 完整后端处理流程

五、API 接口设计

5.1 Trace 相关接口

获取知识使用日志

提交知识反馈（含重新评估）

创建基于 Goal 的知识

创建基于 Message 的知识

5.2 知识库相关接口

获取待验证知识列表

验证知识

批量验证

五、实现优先级

P0（核心功能）

P1（增强功能）

P2（优化功能）

六、技术实现要点

6.1 前端技术栈

6.2 关键交互

6.3 性能优化

七、用户体验设计

7.1 反馈流程简化

7.2 信息透明

7.3 错误处理

八、测试计划

8.1 单元测试

8.2 集成测试

8.3 用户测试

九、后续优化方向

user-feedback-plan.md 45 KB

Histórico Raw

反馈动作语义（`action`）

反馈来源语义（`source`）

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