Files

T

Simon fab75760e0 WIP-CHECKPOINT[auth-refactor]: 固化工程师崩溃前部分成果 + 同树其他未提交WIP（仅源码，不含密钥/二进制）-- 待重激活工程师续作

2026-07-07 21:52:11 +08:00

21 KiB

Raw Blame History

增量 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.5 桥接	`KnowledgeSuggestion` 预埋图结构字段（issue/action/relation_type/parent_issue 等）；Neo4j 落地后 `approve_suggestion` 一步双写。当前仅预埋，不连 Neo4j。
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 的硬范围）

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.5桥接·当前仅flat KB| KB[(KnowledgeBase<br/>Postgres)]
    APPROVE -.->|D1 未来动作·不实现| NEO[(Neo4j 图存储<br/>Issue/Action/关系)]

通道 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）

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.5 桥接后续动作）：本 PRD 仅定义字段契约（P0-4）与未来双写占位（graph_sync_status='pending'），不实现 Neo4j 客户端（当前 backend 无 Neo4j 模块，重构方案 v1.1 为其落点）。

7.2 明确不在范围

敏感词 BLOCK 升级：已决仅 WARN（看板验真⑤）。本 PRD 不升级为 BLOCK；截图隐私仅留接口（D6）。
Neo4j 客户端实现、DLP 实质整合、RAGFlow 服务部署（仅定义其与 Dify 的上下游契约，部署由基础设施侧另行安排）。
重构方案 v1.1 中的非线性跳转/多意图并行/任务中断恢复等复杂场景引擎：本 PRD 仅复用其信息项/关系类型命名（D1 图字段对齐），不实现该引擎。

8. 待确认问题（留给用户/主理人）

专家模式默认值：P1-1 专家模式开关默认开还是关？（影响普通员工首屏体验）
独立队列超时：P0-6 未处理提案多久判 expired？是否需超时提醒训练师？超时后是否自动驳回或保留？
RAGFlow 触发时机：P1-5 由训练师手动上传触发，还是定时扫描某文档目录/对象存储？文档来源与格式范围？
置信阈值分场景微调：P2-3 是否所有场景统一 0.7？高敏场景（安全/账号）是否需更高阈值？
分诊概率展示形式：P1-1 "含概率的推荐"用百分比还是星级？是否披露原始 confidence 给用户？
坐席代答边界：P1-2 坐席排除错误项后，若用户迟迟不确认，坐席能否发提醒 / 是否允许超时自动采用"推荐标记"项（仍须用户最终确认）？
Qwen-VL 部署资源：D5 本地部署的显存/算力是否就绪？视觉理解的延迟 SLA 与降级策略？
audience 枚举：D8 目前 employee_quick_reply / engineer_workguide 两类，是否需第三类（如"管理运营 KB"）？
2.5 桥接双写触发时机：Neo4j 落地后 approve_suggestion 双写的具体发布窗口（本 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/图字段，需扩展

21 KiB Raw Blame History Unescape Escape

增量 PRD：知识库自动迭代修复 + 生产痛点缓解

1. 产品目标

2. 决策约束速查（D1–D9，硬约束）

3. 三条输入通道（写进 PRD 的硬范围）

4. 用户故事（员工 / 坐席 / AI训练师 三类角色）

5. 需求池（P0 / P1 / P2）

P0（Must have — 修复假完成 + 门控 + 桥接预埋 + 审批闭环）

P1（Should have — 交互缓解痛点）

P2（Nice to have — 二期/增强）

6. UI 设计稿

6.1 分诊置顶卡片（H5 · 员工端 · 对应 P1-1 / D4 / 补充B）

6.2 坐席代答 / 排除控件（坐席控制台 · 对应 P1-2 / D9 / 补充B）

6.3 训练师内联审批 + 拓扑预览（坐席控制台 · 对应 P0-6 / D7 / D1）

6.4 独立队列页（坐席控制台 / 管理后台 · 对应 P0-6 / D7）

7. 依赖项与不在范围

7.1 依赖项（前置，本 PRD 不实现）

7.2 明确不在范围

8. 待确认问题（留给用户/主理人）

9. 关键事实索引（供架构师回溯）

21 KiB

Raw Blame History

4. 用户故事（员工 / 坐席 / AI训练师三类角色）