Simon
facc04aa65
本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交 （5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。 一、docs 结构整改（整改 #14） 根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入， 随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录 树并存于 docs/，共 791 文件、双分类体系冲突。 修复动作： - b2 同名异主题文件改名迁移保全 9 个 - C 类 39 个孤立文件按主题正确归类 - A/B1 类 222 个重复文件删除（新结构已有内容副本） - 9 个旧独有空目录删除 - 270 处内部引用按 verified 映射改写 - 整改记录 #14 登记于 04-运维文档/部署运维 结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。 残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。 二、compose 双目录对齐（消除踩坑 A） - docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist 改为 src/frontend-*/dist（h5 / agent / admin / terminal） - docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/ - 效果：本地 docker compose up 不再把根目录 stale dist 挂回， 与线上一致，分叉隐患消除（已 docker compose config 校验通过） 防复发铁律： - 重构须提交；仓库修复须 git stash -u 或先 commit - 新结构须 git add 并提交，避免再次 untracked 复活 - H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/
213 lines
6.8 KiB
Markdown
213 lines
6.8 KiB
Markdown
# IT智能服务台 - AI回复来源标识 PRD
|
||
|
||
**版本**：v1.0
|
||
**日期**：2026-07-20
|
||
**状态**：已评审
|
||
**评审日期**：2026-07-20
|
||
**作者**：许清楚
|
||
**子系统**：03-AI服务
|
||
**模块**：来源标识
|
||
|
||
---
|
||
|
||
## 一、文档变更记录
|
||
|
||
| 版本 | 日期 | 变更说明 |
|
||
|------|------|----------|
|
||
| v1.0 | 2026-07-20 | 初始版本 |
|
||
|
||
---
|
||
|
||
## 二、背景与目标
|
||
|
||
### 2.1 背景
|
||
|
||
当前系统 AI 回复来源不透明，用户和坐席无法感知回复来自哪个路由（本地快判/图谱/Dify/业务路由等），影响信任度和问题追溯。
|
||
|
||
### 2.2 目标
|
||
|
||
| # | 目标 | 衡量指标 |
|
||
|---|------|----------|
|
||
| G1 | **来源透明** - 用户能感知回复来自哪个路由 | 来源标识显示覆盖率 = 100% |
|
||
| G2 | **可追溯** - 坐席能追溯每条回复的来源 | 来源记录可追溯率 = 100% |
|
||
| G3 | **统一管理** - 来源标识统一配置，易维护 | 标识变更无需代码修改 |
|
||
|
||
---
|
||
|
||
## 三、用户故事
|
||
|
||
| # | 角色 | 用户故事 |
|
||
|---|------|----------|
|
||
| US-1 | 员工 | **As a** 员工, **I want** 能看到 AI 回复的来源标识, **so that** 我知道回复的可靠性来源 |
|
||
| US-2 | 坐席 | **As a** 坐席, **I want** 能在会话记录中追溯每条 AI 回复的来源, **so that** 在需要人工介入时快速定位问题来源 |
|
||
| US-3 | 运维 | **As a** 运维人员, **I want** 统一配置来源标识的图标和映射关系, **so that** 调整标识时无需修改代码 |
|
||
|
||
---
|
||
|
||
## 四、来源类型定义
|
||
|
||
### 4.1 来源类型
|
||
|
||
| 来源Key | 来源名称 | 图标 | 说明 |
|
||
|--------|----------|------|------|
|
||
| `byod` | BYOD拦截 | 🔒 | 员工自带设备策略拦截 |
|
||
| `rule` | 本地快判 | ⚡️ | 打招呼/呼叫人工等规则匹配 |
|
||
| `vision` | 图片增强 | 🖼️ | Vision多模态理解 |
|
||
| `graph` | Neo4j图谱 | 🕸️ | 知识图谱匹配命中 |
|
||
| `dify` | Dify推理 | 🤖 | Dify主推理链路 |
|
||
| `routing` | 业务路由 | 📋 | 非IT问题路由到业务负责人 |
|
||
| `assets` | 资产推荐 | 💻 | IT资产管理推荐 |
|
||
| `fallback` | 降级回复 | ⚠️ | 所有路由均未命中时的兜底回复 |
|
||
|
||
### 4.2 来源标识配置
|
||
|
||
```python
|
||
# 来源标识配置
|
||
REPLY_SOURCE_MARKERS = {
|
||
"byod": "🔒", # BYOD拦截
|
||
"rule": "⚡️", # 本地快判（打招呼/呼叫人工）
|
||
"vision": "🖼️", # 图片增强
|
||
"graph": "🕸️", # Neo4j图谱
|
||
"dify": "🤖", # Dify主推理
|
||
"routing": "📋", # 业务路由
|
||
"assets": "💻", # 资产推荐
|
||
"fallback": "⚠️", # 降级回复
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 五、实现方案
|
||
|
||
### 5.1 方案对比
|
||
|
||
| 方案 | 实现方式 | 优点 | 缺点 |
|
||
|------|----------|------|------|
|
||
| 方案A | 回复内容末尾嵌入标识 | 简单直接，实现成本低 | 可能被用户复制，影响体验 |
|
||
| 方案B | persist函数统一追加 | 统一管理，原始内容纯净，便于数据分析 | WS推送和DB存储都会追加，需注意区分 |
|
||
|
||
**推荐：方案B** - 统一在 persist 函数追加标识，便于集中管理和配置调整。
|
||
|
||
### 5.2 方案B详细设计
|
||
|
||
#### 5.2.1 数据结构
|
||
|
||
```python
|
||
# 消息表新增字段
|
||
class Message:
|
||
id: str
|
||
conversation_id: str
|
||
content: str # 原始内容（不含标识）
|
||
reply_source: List[str] # 来源列表，可叠加
|
||
created_at: datetime
|
||
```
|
||
|
||
#### 5.2.2 处理流程
|
||
|
||
```
|
||
AI回复生成
|
||
↓
|
||
确定来源（rule/graph/dify/routing/...）
|
||
↓
|
||
persist函数统一追加标识
|
||
↓
|
||
├── WS推送：content + 标识
|
||
└── DB存储：content + reply_source字段
|
||
```
|
||
|
||
#### 5.2.3 标识追加规则
|
||
|
||
- **单来源**：直接追加对应图标，如 `⚡️`
|
||
- **多来源**：按优先级顺序叠加，如 `📋💻`（业务路由 + 资产推荐）
|
||
- **来源优先级**：`rule` > `byod` > `vision` > `graph` > `dify` > `routing` > `assets` > `fallback`
|
||
|
||
### 5.3 前端展示
|
||
|
||
#### 5.3.1 H5员工端
|
||
|
||
```
|
||
┌─────────────────────────────────┐
|
||
│ 用户消息 │
|
||
└─────────────────────────────────┘
|
||
|
||
┌─────────────────────────────────┐
|
||
│ AI回复内容... │
|
||
│ 🕸️ │ ← 来源标识
|
||
└─────────────────────────────────┘
|
||
```
|
||
|
||
#### 5.3.2 坐席工作台
|
||
|
||
```
|
||
┌─────────────────────────────────┐
|
||
│ 来源：🕸️ Neo4j图谱 │ ← 详细信息
|
||
└─────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 六、非目标
|
||
|
||
| # | 明确不做 |
|
||
|---|----------|
|
||
| N1 | 不修改各路由模块的返回逻辑，仅在 persist 层统一处理 |
|
||
| N2 | 不在消息气泡内显示详细来源文字（坐席端可查看详情） |
|
||
| N3 | 不支持前端自定义图标（统一配置管理） |
|
||
|
||
---
|
||
|
||
## 七、指标与验收
|
||
|
||
| # | 指标 | 目标值 | 验收方式 |
|
||
|---|------|--------|----------|
|
||
| AC1 | 来源标识显示覆盖率 | 100% | 每条AI回复均有标识 |
|
||
| AC2 | 来源记录可追溯率 | 100% | DB中reply_source字段完整 |
|
||
| AC3 | 标识配置可维护性 | 调整无需代码修改 | 配置文件变更即可 |
|
||
|
||
---
|
||
|
||
## 八、关联文档
|
||
|
||
| 文档 | 说明 |
|
||
|------|------|
|
||
| `PRD-REQ-AI-001-复杂场景与统一路由-v1.1.md` | 路由层设计 |
|
||
| `PRD-REQ-AI-002-置信度门控-v1.0.md` | 置信度门控 |
|
||
| `PRD-REQ-AI-003-多模态视觉理解-v1.0.md` | Vision设计 |
|
||
| `技术方案-REQ-AI-004-AI回复来源标识-v1.0.md` | 技术实现方案 |
|
||
|
||
---
|
||
|
||
## 九、风险与依赖
|
||
|
||
| 风险 | 影响 | 缓解措施 |
|
||
|------|------|----------|
|
||
| R1：现有路由未返回来源标识 | 功能不完整 | 审查所有路由模块，确保返回reply_source |
|
||
| R2：多来源叠加显示混乱 | 用户体验差 | 严格按优先级排序，限制最多3个 |
|
||
| R3：WS推送和DB存储不一致 | 数据分析困难 | 统一在persist层处理 |
|
||
|
||
**依赖**：
|
||
- D01：各路由模块需返回reply_source字段
|
||
- D02：前端消息组件需支持显示标识
|
||
|
||
---
|
||
|
||
## 十、里程碑
|
||
|
||
| 阶段 | 任务 | 预计时间 |
|
||
|------|------|----------|
|
||
| M1 | 技术方案评审 | 1天 |
|
||
| M2 | 后端实现（persist层改造） | 2天 |
|
||
| M3 | 前端展示（H5+坐席端） | 2天 |
|
||
| M4 | 联调测试 | 1天 |
|
||
| M5 | 上线 | 1天 |
|
||
|
||
---
|
||
|
||
## 十一、待确认问题
|
||
|
||
| # | 问题 | 建议 | 优先级 |
|
||
|---|------|------|--------|
|
||
| Q1 | 多来源叠加时排序规则 | 按优先级排列 | P1 |
|
||
| Q2 | 降级回复是否固定显示fallback标识 | 是 | P2 |
|
||
| Q3 | 历史消息是否需要补充标识 | 否，仅新消息 | P2 |
|