|
|
@@ -0,0 +1,837 @@
|
|
|
+# 用户反馈系统设计文档
|
|
|
+
|
|
|
+## 文档维护规范
|
|
|
+
|
|
|
+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 评估算法
|
elksmmx