Simon
e4e2de47bb
提交 OTP/RBAC/Tier0/Tier1/P0+P2 测试报告、方案A E2E 验证、知识库迭代设计(PRD/mermaid/html 原型)、项目状态看板更新; 根配置 docker-compose.yml/mkdocs.yml。
227 lines
21 KiB
Markdown
227 lines
21 KiB
Markdown
# 增量 PRD：知识库自动迭代修复 + 生产痛点缓解
|
||
|
||
> 文档类型：增量 PRD（简单 PRD 格式，无竞品分析）
|
||
> 版本：v0.1（草案，待主理人/用户评审）
|
||
> 日期：2026-07-07
|
||
> 作者：产品经理 许清楚（software-product-manager）
|
||
> 关联项目：IT 智能服务台（企业微信内嵌 IT 支持系统）
|
||
> 技术栈：后端 FastAPI + SQLAlchemy 2.0(async) + PostgreSQL(生产)/SQLite(测试)；
|
||
> 前端 H5（Vue3+Vant4，员工端）、坐席控制台（Vue3+Element Plus）、管理后台（Vue3+Element+Tailwind）
|
||
|
||
---
|
||
|
||
## 1. 产品目标
|
||
|
||
**一句话目标**：把"知识库自动迭代"从看板验真认定的**假完成**修复为**真可用**，并通过分诊式置信门控、坐席代答、多模态视觉理解与训练师内联审批，系统性缓解员工不信任 AI、信息过载、坐席输入质量差、流程不可审计、坐席与训练师工作重叠五大生产痛点。
|
||
|
||
**背景（事实基础，均来自代码/看板验真）**：
|
||
- 看板 QA 严过验真（2026-07-07）结论②：知识库自动迭代标"✅已完成"实为**桩实现 + API 未挂载**（严重偏差）。
|
||
- `backend/app/services/knowledge_iteration_service.py` 中 `_generate_update_suggestion` / `_generate_new_faq_suggestion` 全是 `TODO` 占位，返回 `[待AI生成]`。
|
||
- `backend/app/api/router.py` 第 284 行 `knowledge_iteration_router` 被注释，**API 根本不存在**（模块 `backend/app/api/knowledge_iteration.py` 已存在但未挂载）。
|
||
- 税友集团 IT 支持组长提出 **5 条生产痛点 + 2 条补充交互**，构成本 PRD 范围。
|
||
- 已与用户拍板 **D1–D9** 九项硬约束（见第 4 节），作为需求边界。
|
||
|
||
---
|
||
|
||
## 2. 决策约束速查（D1–D9，硬约束）
|
||
|
||
| 编号 | 决策 | 本 PRD 落地要点 |
|
||
|------|------|----------------|
|
||
| D1 | 存储边界：解读2 合一（直接写 Neo4j 图） | 知识迭代产出**直接写 Neo4j 图**（图即真相源）；`KnowledgeSuggestion` 携带图结构字段（issue/action/relation_type/parent_issue 等）；flat `KnowledgeBase` 降为图的派生视图，非独立存储。 |
|
||
| D2 | AI 后端 | **Dify 生成**（复用 `WingmanService` 的 `generate_summary`/`suggest_tags` 范式）+ **RAGFlow** 作非标准文档格式输入的上游 ingestion/ETL 第一道筛选/整理。二者互补。 |
|
||
| D3 | 置信门控 | AI 回复统一输出 `confidence`；低于**全局阈值 0.7** 时前端渲染"转人工"入口并附已收集上下文；上线后按**转人工率**回调。 |
|
||
| D4 | 一次一问 | 分诊卡片**自适应**（AI 判断复杂度决定一次给几步）+ **专家模式开关**（老手可一把梭）。 |
|
||
| D5 | vision | 截图理解用**本地化千问视觉模型 Qwen-VL**（Dify 后端接本地部署）。 |
|
||
| D6 | 截图隐私 | 仅**保留隐私检测接口**，不立即生效；后续与数据防泄漏(DLP)整合。关联敏感词当前仅 WARN 不拦截（待决安全缺口），本 PRD 不升级 BLOCK。 |
|
||
| D7 | 训练师审批 | **聊天内联审批**，未处理的转**独立队列**；提案**默认待审**（非默认采纳）。 |
|
||
| D8 | audience | `KnowledgeSuggestion.audience` 按**来源会话类型自动标**（员工快捷回复 KB / 工程师作业指导 KB）+ 坐席可改。 |
|
||
| D9 | 坐席代答 | 坐席**仅能排除错误项 + 用户最终确认** + 可加**手动推荐标记**；不能完全代用户回答（防越权/误代答）。 |
|
||
|
||
---
|
||
|
||
## 3. 三条输入通道（写进 PRD 的硬范围）
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[通道A: 会话<br/>员工⇄AI⇄坐席] -->|Dify 生成| KS((KnowledgeSuggestion))
|
||
B[通道B: 训练师<br/>直接录入] -->|手动| KS
|
||
C[通道C: 文档<br/>非标准格式] -->|RAGFlow 整理/ETL| KS
|
||
KS -->|D7 内联审批/独立队列| APPROVE[approve_suggestion]
|
||
APPROVE -->|D1 解读2·直接写图| NEO[(Neo4j 图存储<br/>Issue/Action/关系)]
|
||
NEO -.->|派生视图| KB[(KnowledgeBase<br/>Postgres 派生)]
|
||
```
|
||
|
||
- **通道 A（P0/P1，痛点⑤核心）**：会话 → Dify → `KnowledgeSuggestion`（自动）。覆盖分诊门控、坐席代答、vision、置信门控。
|
||
- **通道 B（P0/P2）**：训练师 → 直接录入（手动）。本 PRD 提供结构化录入表单（P2），内联审批控件复用通道 A 提案。
|
||
- **通道 C（P1/P2，二期优先于 A 之后）**：文档 → RAGFlow 整理 → 结构化 → KB（训练师驱动）。优先级低于 A。
|
||
|
||
---
|
||
|
||
## 4. 用户故事（员工 / 坐席 / AI训练师 三类角色）
|
||
|
||
| 角色 | 对应用户视角 | 用户故事 |
|
||
|------|--------------|----------|
|
||
| 员工（痛点①、②；补充A、B） | 不信任/被信息淹没 | 作为员工，当 AI 不确定时我希望**直接看到"转人工"入口**（并附已收集上下文），这样我不必被迫相信不准的 AI 回复。（痛点① / D3） |
|
||
| 员工 | 信息过载 | 作为员工，我希望复杂问题被**拆成分步选择题（是/否 或含概率的推荐）**，而不是一次性收到一大段需筛选/可能错误的复杂信息。（痛点② / D4 / 补充B） |
|
||
| 员工（补充A） | 多模态输入 | 作为员工，我希望**直接发截图**（含中途补图）也能被理解，而不必用文字费力描述故障。（补充A / D5） |
|
||
| 坐席（痛点③、④；补充B / D9） | 输入质量差 | 作为坐席，我希望能**排除 AI 澄清题里的错误选项、加手动推荐标记**，从坐席侧反向消解用户描述重复/模糊/跳跃的问题。（痛点③ / D9 / 补充B） |
|
||
| 坐席（痛点④） | 流程不可审计 | 作为坐席，我希望每一步决策都**留痕可审计**，避免复杂/人肉/无确定性效果、事后还需再回顾的流程。（痛点④） |
|
||
| 坐席（痛点⑤） | 工作重叠 | 作为坐席，我希望**在与用户+AI 互动中同步完成问题定位、决策与知识库训练优化**，不必把活儿甩给训练师再等回流。（痛点⑤ / D7） |
|
||
| AI训练师（痛点⑤ / D7 / D8 / 通道C） | 审批低效 | 作为训练师，我希望会话中自动生成的提案能**内联审批**、未处理的**进独立队列**，消除与坐席的工作重叠低效。（痛点⑤ / D7） |
|
||
| AI训练师（D8） | 分类负担 | 作为训练师，我希望提案**按来源会话类型自动打 audience 标签**，减少我手工分类。（D8） |
|
||
| AI训练师（通道C / D2） | 文档整理 | 作为训练师，我希望 **RAGFlow 帮我把非标准格式文档整理成结构化 KB 片段**，而不是人肉抄写。（通道C / D2） |
|
||
|
||
---
|
||
|
||
## 5. 需求池（P0 / P1 / P2）
|
||
|
||
> 字段说明：**决策**=引用的 D1–D9；**通道**=A/B/C；**验收**=可测标准；**落点**=H5(员工端)/坐席控制台/管理后台。
|
||
|
||
### P0（Must have — 修复假完成 + 门控 + 桥接预埋 + 审批闭环）
|
||
|
||
| ID | 需求 | 决策/通道 | 验收标准 | 前端落点 |
|
||
|----|------|-----------|----------|----------|
|
||
| P0-1 | **真 AI 生成替代占位**：用 Dify 真实生成替换 `_generate_update_suggestion` / `_generate_new_faq_suggestion` 的 `[待AI生成]` 占位，复用 `WingmanService` 范式（`_build_context_messages` + `_call_wingman_api` + `_parse_json_response`，结构化 JSON 输出 title/content/category/tags）。 | D2 / A | ①生成的建议 `title`/`content` 不再含 `[待AI生成]`；②Dify 不可用时降级（空内容标记 `source_failed=True`，不写伪数据）；③pytest 断言真实生成（原 4/4 桩断言需更新）。 | 管理后台（触发 analyze）、坐席控制台（提案出现） |
|
||
| P0-2 | **挂载 knowledge_iteration_router**：取消 `router.py` 第 284 行注释并修正 `prefix="/admin/knowledge-iteration"`、`tags=["知识库自动迭代"]`，使 API 对外可用。 | 修复验真② | ① `GET /api/admin/knowledge-iteration/suggestions` 返回 200；②`curl .../analyze` 触发真实生成；③OpenAPI 文档可见该路由。 | 无（后端挂载） |
|
||
| P0-3 | **置信门控（全局 0.7）**：AI 回复（员工端 Dify Agent1 及坐席 Wingman）统一输出 `confidence` 字段，复用 `WingmanService` 的 confidence 契约；低于 `settings.confidence_gate_threshold`（默认 0.7，可配置）时，前端（H5）主动渲染"转人工"入口并附**已收集上下文**（已填信息项摘要）。 | D3 / A | ①返回体含 `confidence`；②`confidence<0.7` 的 AI 消息旁出现"转人工"卡片；③阈值可经配置调整并即时生效；④转人工动作携带上下文快照。 | H5（员工端） |
|
||
| P0-4 | **图结构字段预埋（2.5 桥接）**：`KnowledgeSuggestion` 新增 `issue` / `action` / `relation_type` / `parent_issue` / `graph_meta`(JSON) 等字段（均 nullable，不连 Neo4j）；`approve_suggestion` 落库 `KnowledgeBase` 时一并保留图字段并置 `graph_sync_status='pending'`（双写占位）。 | D1 / A/B | ①Alembic migration 新增字段；②提案可填图字段；③approve 时 `KnowledgeBase` 记录携带图字段且 `graph_sync_status='pending'`；④**不创建任何 Neo4j 客户端/连接**。 | 管理后台（录入/审阅可见图字段） |
|
||
| P0-5 | **audience 自动标注**：`KnowledgeSuggestion` 新增 `audience` 字段；通道 A 提案按 `source_session_type`（员工会话 / 工程师会话）自动标 `employee_quick_reply` / `engineer_workguide`；坐席可改。 | D8 / A | ①不同来源会话生成的提案 `audience` 正确；②坐席在审批时可修改 `audience` 并落库；③统计可按 audience 分组。 | 坐席控制台（内联审批可改）、管理后台（统计） |
|
||
| P0-6 | **训练师内联审批 + 独立队列**：会话内 AI 提案以**内联卡片**呈现"采纳/驳回/改写"；未处理提案进入**独立队列**页；提案**默认 `status=pending` 不自动 applied**（D7）。 | D7 / A | ①坐席在会话中可对提案做内联审批；②超时/未处理提案出现在独立队列；③默认不自动采纳（与现有 `approve` 显式调用分离）；④审批动作写入审计日志。 | 坐席控制台（内联审批控件 + 独立队列页） |
|
||
| P0-7 | **依赖项：RBAC 修复（独立 BugFix 轨道，本 PRD 不实现）**：训练师审批写入、独立队列读取需正常角色鉴权。当前 `app/api/admin_users.py` 鉴权 422 失效（P0 安全漏洞，看板验真④），列为**前置依赖**。 | 范围边界 | ①训练师审批/队列接口在 RBAC 修复后可正常鉴权；②本 PRD 不改动 RBAC 代码。 | 管理后台 / 坐席控制台（受 RBAC 保护） |
|
||
|
||
### P1（Should have — 交互缓解痛点）
|
||
|
||
| ID | 需求 | 决策/通道 | 验收标准 | 前端落点 |
|
||
|----|------|-----------|----------|----------|
|
||
| P1-1 | **分诊式回复 + 专家模式**：AI 对复杂问题输出**分步选择题**（是/否 或含概率的推荐项）；卡片**置顶/悬浮**；一次给几步由 AI 判复杂度**自适应**；提供**专家模式开关**（关：分步；开：一把梭多步）。 | D4 / 补充B / A | ①复杂问题拆成选择题而非大段文本；②卡片置顶展示；③专家模式开关可见且生效（开→一次多步）；④概率以百分比/星级可视。 | H5（员工端） |
|
||
| P1-2 | **坐席代答/排除控件**：坐席可对 AI 澄清题**勾选排除错误选项**、加**手动推荐标记**；**不能替用户选正解**；最终确认权在用户。 | D9 / 补充B / A | ①坐席可排除错误项（选项置灰/划除）；②坐席可加"推荐"标记；③坐席无法代用户点最终确认；④用户侧收到"坐席已排除 X 项/推荐 Y"提示。 | 坐席控制台 |
|
||
| P1-3 | **多模态视觉理解**：员工发截图/中途补图 → 调用**本地 Qwen-VL**（Dify 后端接本地部署）产出结构化描述，进入对话上下文参与推理。 | D5 / 补充A / A | ①用户发图后系统调用视觉模型产出描述；②描述进入 AI 上下文并影响回复；③vision 调用可统计/可降级（无图模型时提示）。 | H5（员工端，图片上传+理解结果） |
|
||
| P1-4 | **截图隐私接口（仅留接口）**：复用 `ContentModerationService.check_privacy_leak` 提供隐私检测接口；**生产默认不拦截**（仅 WARN/记录），后续与 DLP 整合。 | D6 / 补充A / A | ①接口存在且可被调用，返回隐私命中类型；②默认不阻断消息；③与 DLP 整合点为预留扩展位（不实现）。 | H5（可选隐私提示） |
|
||
| P1-5 | **RAGFlow 上游 ETL（通道 C）**：训练师上传非标准格式文档 → RAGFlow 整理/筛选/结构化 → 生成 `KnowledgeSuggestion`（`source_type='document_ragflow'`）→ 进队列待审。 | D2 / C | ①训练师上传文档触发 RAGFlow；②产出结构化片段生成 pending 提案；③提案走 D7 审批流；④与 Dify 生成互补不冲突。 | 管理后台（文档上传/整理结果审阅） |
|
||
|
||
### P2（Nice to have — 二期/增强）
|
||
|
||
| ID | 需求 | 决策/通道 | 验收标准 | 前端落点 |
|
||
|----|------|-----------|----------|----------|
|
||
| P2-1 | **训练师直接录入（通道 B）**：在管理后台/坐席控制台提供结构化录入表单（含图结构字段、audience），直接生成 `KnowledgeSuggestion`（手动，`source_type='manual'`）。 | B / D1 / D8 | ①训练师可手填 title/content/分类/标签/图字段/audience 生成 pending 提案；②复用 D7 审批。 | 管理后台 |
|
||
| P2-2 | **转人工率回调看板**：统计"因 `confidence<0.7` 触发的转人工率"，支撑 D3 阈值回调。 | D3 / A | ①管理后台有转人工率指标；②可按会话类型/分类下钻。 | 管理后台（统计） |
|
||
| P2-3 | **置信阈值分场景微调（占位）**：部分高敏场景（安全/账号）是否需高于 0.7 的阈值，待确认后落地。 | D3 | ①若确认，支持按 category 配置阈值；②默认仍 0.7。 | 管理后台（配置，待定） |
|
||
|
||
---
|
||
|
||
## 6. UI 设计稿
|
||
|
||
> 所有 UI 标注**前端落点**（H5 / 坐席控制台 / 管理后台）。
|
||
|
||
### 6.1 分诊置顶卡片（H5 · 员工端 · 对应 P1-1 / D4 / 补充B）
|
||
|
||
```
|
||
┌─────────────────────────────────────────┐ ← 置顶/悬浮卡片
|
||
│ 🤖 AI 分诊（第 1/3 步） │
|
||
│ Q: 请问您的问题是"无法联网"还是"网速慢"? │
|
||
│ ( ) 无法联网 │
|
||
│ (○) 网速慢 ← 含概率推荐: 72% │
|
||
│ ( ) 都不是 │
|
||
│ [专家模式: 关] ← 开关(老手可开一把梭) │
|
||
└─────────────────────────────────────────┘
|
||
↓ 用户选择后
|
||
┌─────────────────────────────────────────┐
|
||
│ ✅ 已收集上下文: 网速慢 / Win11 / 财务部 │ ← P0-3 转人工时附带的上下文
|
||
│ [转人工] （仅当 confidence<0.7 时出现） │
|
||
└─────────────────────────────────────────┘
|
||
```
|
||
|
||
### 6.2 坐席代答 / 排除控件（坐席控制台 · 对应 P1-2 / D9 / 补充B）
|
||
|
||
```
|
||
┌─ AI 澄清题（坐席侧镜像）──────────────────┐
|
||
│ AI 问用户: "您的系统版本是?" │
|
||
│ □ Win10 □ Win11 │
|
||
│ ☑ macOS ← 坐席排除(错误项,置灰划除) │
|
||
│ [+ 推荐标记] ← 坐席可加手动推荐 │
|
||
│ 注: 坐席【不能】替用户点最终确认 │
|
||
└──────────────────────────────────────────┘
|
||
↓ 同步到用户 H5
|
||
[坐席已排除"macOS"，推荐您选 Win10/Win11]
|
||
```
|
||
|
||
### 6.3 训练师内联审批 + 拓扑预览（坐席控制台 · 对应 P0-6 / D7 / D1）
|
||
|
||
```
|
||
┌─ 会话内联提案卡片（默认待审）──────────────┐
|
||
│ 💡 新 FAQ 提案 (conf=0.86, audience=员工快捷回复)│
|
||
│ 标题: VPN 连不上怎么办 │
|
||
│ 内容: 1.检查网络 2.重置VPN客户端 ... │
|
||
│ 拓扑预览: │
|
||
│ [VPN问题]──LEADS_TO──>[个人VPN] │ ← D1 图字段预览
|
||
│ └──LEADS_TO──>[团队VPN] │
|
||
│ [采纳] [驳回] [改写] │ ← D7 内联审批
|
||
│ audience: [员工快捷回复 ▼]（可改,D8） │
|
||
└──────────────────────────────────────────┘
|
||
```
|
||
|
||
### 6.4 独立队列页（坐席控制台 / 管理后台 · 对应 P0-6 / D7）
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> pending: 通道A/B/C 生成提案
|
||
pending --> approved: 训练师内联/队列审批通过
|
||
pending --> rejected: 驳回
|
||
pending --> queued: 未处理(进独立队列)
|
||
queued --> approved: 队列中审批
|
||
queued --> expired: 超时(待确认,见第8节)
|
||
approved --> applied: approve_suggestion 落库KB
|
||
applied --> graph_pending: graph_sync_status='pending'(D1占位)
|
||
```
|
||
|
||
| 独立队列列 | 说明 |
|
||
|-----------|------|
|
||
| 提案来源 | 通道 A/B/C（会话 / 手动 / RAGFlow） |
|
||
| audience | 自动标 + 可改 |
|
||
| confidence | 门控参考 |
|
||
| 状态 | pending / queued / approved / rejected |
|
||
| 操作 | 采纳 / 驳回 / 改写 / 查看拓扑 |
|
||
|
||
---
|
||
|
||
## 7. 依赖项与不在范围
|
||
|
||
### 7.1 依赖项（前置，本 PRD 不实现）
|
||
- **RBAC 修复（P0 安全漏洞，看板验真④）**：`app/api/admin_users.py` 鉴权 422 失效。训练师审批写入、独立队列读取依赖正常角色鉴权，须作为**独立 BugFix 轨道**先解（P0-7 已列为依赖）。
|
||
- **Neo4j 直接写图（解读2 合一）**：本 PRD 定义**字段契约**（P0-4）并要求**实现 Neo4j 客户端 + 图 schema 作为前置阶段**（当前 backend 无 Neo4j 模块，须新建；技术方向见主 PRD `../02-产品需求/02-产品需求文档PRD-v1.2-20260704.md` §11.1）
|
||
|
||
### 7.2 明确不在范围
|
||
- **敏感词 BLOCK 升级**：已决仅 WARN（看板验真⑤）。本 PRD 不升级为 BLOCK；截图隐私仅留接口（D6）。
|
||
- **Neo4j 客户端实现**、**DLP 实质整合**、**RAGFlow 服务部署**（仅定义其与 Dify 的上下游契约，部署由基础设施侧另行安排）。
|
||
- **重构方案 v1.1 中的非线性跳转/多意图并行/任务中断恢复**等复杂场景引擎：本 PRD 仅复用其信息项/关系类型命名（D1 图字段对齐），不实现该引擎。
|
||
|
||
---
|
||
|
||
## 8. 待确认问题（留给用户/主理人）
|
||
|
||
1. **专家模式默认值**：P1-1 专家模式开关默认**开**还是**关**？（影响普通员工首屏体验）
|
||
2. **独立队列超时**：P0-6 未处理提案多久判 `expired`？是否需超时提醒训练师？超时后是否自动驳回或保留？
|
||
3. **RAGFlow 触发时机**：P1-5 由训练师**手动上传触发**，还是定时扫描某文档目录/对象存储？文档来源与格式范围？
|
||
4. **置信阈值分场景微调**：P2-3 是否所有场景统一 0.7？高敏场景（安全/账号）是否需更高阈值？
|
||
5. **分诊概率展示形式**：P1-1 "含概率的推荐"用**百分比**还是**星级**？是否披露原始 confidence 给用户？
|
||
6. **坐席代答边界**：P1-2 坐席排除错误项后，若用户迟迟不确认，坐席能否发提醒 / 是否允许超时自动采用"推荐标记"项（仍须用户最终确认）？
|
||
7. **Qwen-VL 部署资源**：D5 本地部署的显存/算力是否就绪？视觉理解的延迟 SLA 与降级策略？
|
||
8. **audience 枚举**：D8 目前 `employee_quick_reply` / `engineer_workguide` 两类，是否需第三类（如"管理运营 KB"）？
|
||
9. **Neo4j 图客户端与图 schema 的分期**：前置实现落在 Tier0 还是随 Tier1（本 PRD 要求实现，分期见架构设计）。
|
||
|
||
---
|
||
|
||
## 9. 关键事实索引（供架构师回溯）
|
||
|
||
| 项 | 文件/位置 | 现状 |
|
||
|----|-----------|------|
|
||
| 假完成占位 | `services/knowledge_iteration_service.py` L240-253, L273-286 | `_generate_*_suggestion` 返回 `[待AI生成]` |
|
||
| API 未挂载 | `api/router.py` L284 | `knowledge_iteration_router` 注释 |
|
||
| 已有 API 模块 | `api/knowledge_iteration.py` | 6 端点齐全，用 `require_admin`，未挂载 |
|
||
| Wingman 范式 | `services/wingman_service.py` | `generate_summary`/`suggest_tags`/`_call_wingman_api`/`_parse_json_response`/`_estimate_confidence` |
|
||
| 隐私接口 | `services/content_moderation_service.py` L139 | `check_privacy_leak` 仅 WARN，正则 `\b` 对中文失效（已知 Bug，不在本范围） |
|
||
| 图存储落点 | `docs/03-技术架构/02-技术方案/技术方案-复杂场景重构.md` | Neo4j Issue/Action/关系/信息项修饰（v1.1） |
|
||
| 验真结论 | `docs/10-项目管理/05-项目状态看板/01-项目状态看板.md` | #2 假完成 / #4 RBAC 422 / #5 隐私仅 WARN |
|
||
| 现有模型 | `models/knowledge_suggestion.py` | 无图字段 / 无 audience / 无 confidence |
|
||
| 现有 Schema | `schemas/knowledge_suggestion.py` | 无 audience/confidence/图字段，需扩展 |
|