Files

T

Simon facc04aa65 chore: docs 结构整改 + compose 双目录对齐（合并重建提交）

本提交为 .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-*/

2026-08-07 22:31:32 +08:00

6.8 KiB

Raw Blame History

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 来源标识配置

# 来源标识配置
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 数据结构

# 消息表新增字段
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

6.8 KiB Raw Blame History Unescape Escape