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-*/
306 lines
17 KiB
Markdown
306 lines
17 KiB
Markdown
# 复杂场景重构第二阶段 — 增量 PRD
|
||
|
||
## 1. 文档信息
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 文档名称 | 复杂场景重构第二阶段 — 增量产品需求文档 |
|
||
| 版本 | v1.0 |
|
||
| 创建日期 | 2025-07-11 |
|
||
| 作者 | 许清楚（产品经理） |
|
||
| 状态 | 草案 |
|
||
| 关联文档 | 复杂场景重构第一阶段 PRD（Phase 1 已上线） |
|
||
|
||
### 1.1 背景
|
||
|
||
IT 智能服务台复杂场景重构第一阶段（P0 任务中断恢复 + P1 信息更正）已部署至生产环境，建立了以下核心能力：
|
||
|
||
- **InformationItem 数据模型**：PostgreSQL 表 `auto_information_items`（11 列，支持版本管理）
|
||
- **IntentRouter 全局意图识别**：PAUSE / RESUME_TASK / CORRECT / SUPPLEMENT 四类意图
|
||
- **SessionManager 会话管理**：pause / resume / correct / supplement 四类操作
|
||
- **9 个 API 端点**：`/itportal/automation/sessions/...`
|
||
- **前端**：H5 员工端 + 坐席端 复杂场景 UI 组件
|
||
|
||
第二阶段在此基础上新增 **P2 上下文压缩** 与 **P3 多轮纠错** 两个能力域。本文档仅描述第二阶段新增/变更内容，不重复 Phase 1 已定义内容。
|
||
|
||
### 1.2 术语
|
||
|
||
| 术语 | 说明 |
|
||
|------|------|
|
||
| Token 阈值 | 触发上下文压缩的 token 数量上限，可配置 |
|
||
| 压缩摘要 | 对历史对话进行摘要后生成的结构化文本，替代原始消息传入 LLM |
|
||
| 信息项依赖 | 信息项 A 的值由信息项 B 推导而来，当 B 更正时 A 需联动更新的关系 |
|
||
| 版本链 | 同一 session 中同一信息项的所有历史版本按时间排列的序列 |
|
||
| 快照 | 某次更正发生时，session 中所有信息项的完整状态记录 |
|
||
|
||
---
|
||
|
||
## 2. 产品目标
|
||
|
||
| # | 目标 | 衡量指标 |
|
||
|---|------|----------|
|
||
| G1 | 长对话场景下 AI 不因 token 超限而中断或丢失关键信息 | 超长会话（>8000 tokens）AI 正常响应率 ≥ 99%；关键信息项零丢失 |
|
||
| G2 | 员工可在同一会话中多次更正/补充信息，系统自动维护版本与依赖 | 单 session 支持无限次更正；依赖联动提示准确率 ≥ 95% |
|
||
| G3 | 压缩与多轮纠错对员工透明，不增加操作负担 | 员工无额外操作步骤；压缩过程用户无感知 |
|
||
|
||
---
|
||
|
||
## 3. 用户故事
|
||
|
||
### 3.1 P2 — 上下文压缩
|
||
|
||
| # | 用户故事 |
|
||
|---|----------|
|
||
| US-P2-1 | 作为 IT 服务台员工，我希望在超长对话中 AI 依然记得我之前提交的关键信息（如工号、申请事由），这样我不必反复重复。 |
|
||
| US-P2-2 | 作为 IT 服务台员工，我希望长对话被"智能记忆"后仍能继续正常审批与执行流程，不会因为对话太长而收到错误或中断。 |
|
||
| US-P2-3 | 作为运维人员，我希望能够查看每次上下文压缩的日志记录，这样在 AI 行为异常时可以定位是否与压缩有关。 |
|
||
|
||
### 3.2 P3 — 多轮纠错
|
||
|
||
| # | 用户故事 |
|
||
|---|----------|
|
||
| US-P3-1 | 作为 IT 服务台员工，我希望在对话过程中可以多次更正不同信息项（先更正工号、再更正设备型号），每次更正都被完整记录。 |
|
||
| US-P3-2 | 作为 IT 服务台员工，我希望更正某个信息项后，系统能提示我哪些关联信息需要一并更新，避免信息不一致。 |
|
||
| US-P3-3 | 作为 IT 服务台员工，如果我更正错了，我希望可以撤销最近一次更正，恢复到更正前的状态。 |
|
||
| US-P3-4 | 作为坐席人员，我希望能在坐席端查看完整的信息项版本链，并对比任意两个版本的差异，以便快速理清员工多次更正的脉络。 |
|
||
|
||
---
|
||
|
||
## 4. 需求池
|
||
|
||
> 优先级说明：P0 = Must have（本期必做）；P1 = Should have（本期应做）；P2 = Nice to have（资源允许时做）。本节 P0/P1/P2 为 Phase 2 内部优先级，与 Phase 1 的 P0/P1 无关。
|
||
|
||
### 4.1 P2 — 上下文压缩
|
||
|
||
| ID | 优先级 | 需求描述 | 验收要点 |
|
||
|----|--------|----------|----------|
|
||
| CC-P0-1 | P0 | **Token 实时计数**：SessionManager 在每次追加消息后计算当前会话消息历史的 token 总数（使用与目标 LLM 一致的 tokenizer） | 计数误差 ≤ 5%；H5/坐席端无额外请求开销 |
|
||
| CC-P0-2 | P0 | **压缩触发**：当 token 总数超过配置阈值（默认 8000，可通过环境变量 `CONTEXT_COMPRESSION_THRESHOLD` 配置）时，在下一次调用 LLM 前自动触发压缩 | 阈值可热更新无需重启；触发后不影响当前用户消息的响应 |
|
||
| CC-P0-3 | P0 | **压缩策略**：压缩时保留以下关键信息完整原文，其余历史消息生成摘要 —— ① 所有 InformationItem 的当前值与最新版本 ② 已执行动作（action）及状态 ③ 当前任务节点（task node）与决策点 ④ 最近 N 轮（默认 4 轮）原始对话 | 压缩后 LLM 可正确回答"我之前填的工号是多少"等回溯问题 |
|
||
| CC-P0-4 | P0 | **压缩后恢复**：压缩后的上下文以系统消息形式注入，格式为结构化 Markdown（含"已收集信息项""已执行动作""任务状态"分区），LLM 基于此继续对话 | 压缩前后任务流程节点不漂移；信息项不丢失 |
|
||
| CC-P1-5 | P1 | **压缩历史日志**：每次压缩记录写入 `auto_context_compressions` 表，字段含 session_id、压缩前 token 数、压缩后 token 数、压缩耗时、压缩时任务节点、触发时间 | 日志支持按 session_id 查询；保留 90 天 |
|
||
| CC-P1-6 | P1 | **压缩比例监控**：坐席端会话详情页展示该 session 的压缩次数、累计压缩比例；运维大盘展示全局压缩触发频率与平均压缩比 | 坐席端可见压缩标记 |
|
||
| CC-P2-7 | P2 | **渐进式压缩**：当单次压缩后仍超阈值，支持二次压缩（对摘要再摘要），最多 3 级，超出则告警并降级为截断最旧消息 | 二次压缩后关键信息项仍不丢失 |
|
||
|
||
### 4.2 P3 — 多轮纠错
|
||
|
||
| ID | 优先级 | 需求描述 | 验收要点 |
|
||
|----|--------|----------|----------|
|
||
| MC-P0-1 | P0 | **无限次更正**：移除 Phase 1 单次更正限制，同一 session 支持任意次数的 CORRECT / SUPPLEMENT 操作；每次更正生成新的 InformationItem 版本 | 连续更正 10 次功能正常；版本号单调递增 |
|
||
| MC-P0-2 | P0 | **版本快照**：每次更正发生时，记录该 session 全部信息项的快照（`auto_information_snapshots` 表），含 snapshot_id、session_id、trigger_item_key、各 item 的 key/value/version、创建时间 | 快照可回溯任意更正时刻的完整状态 |
|
||
| MC-P0-3 | P0 | **更正撤销**：新增 API `POST /itportal/automation/sessions/{session_id}/corrections/undo`，撤销最近一次更正，将受影响信息项回滚到上一版本，并恢复对应快照 | 撤销后 AI 上下文同步更新；连续撤销支持多步回退直至无更正可撤销 |
|
||
| MC-P1-4 | P1 | **信息项依赖关系**：在 InformationItem 模型新增 `derived_from` 字段（JSON 数组，记录推导来源 item_key）。更正某 item 时，系统自动检查是否存在 `derived_from` 指向该 item 的其他 item，向员工/坐席返回联动更新提示列表 | 依赖关系提示准确率 ≥ 95%；员工可选择是否联动更新 |
|
||
| MC-P1-5 | P1 | **批量更正**：CORRECT 意图支持一次提交多个信息项更正（payload 为数组），单次事务内完成多 item 版本递增与单条快照记录 | 批量更正原子性：全部成功或全部回滚 |
|
||
| MC-P1-6 | P1 | **坐席端版本链可视化**：坐席端会话详情页新增"信息项版本时间线"组件，展示每个 item 的所有版本；支持选择任意两个版本进行 diff 对比（高亮变更字段） | 坐席可在一屏内看清更正脉络 |
|
||
| MC-P2-7 | P2 | **更正备注**：员工/坐席发起更正时可附加备注（reason），记录更正原因，随版本一起存储 | 备注非必填，最长 200 字 |
|
||
|
||
---
|
||
|
||
## 5. 交互流程
|
||
|
||
### 5.1 上下文压缩流程
|
||
|
||
```
|
||
员工发送消息
|
||
↓
|
||
SessionManager.appendMessage()
|
||
↓
|
||
计算当前会话 token 总数
|
||
↓
|
||
token > 阈值?
|
||
├─ 否 → 正常调用 LLM → 返回响应
|
||
└─ 是 → 触发压缩
|
||
↓
|
||
提取关键信息：信息项当前值 + 已执行动作 + 任务节点 + 最近4轮对话
|
||
↓
|
||
调用 LLM 对其余历史消息生成摘要（summary）
|
||
↓
|
||
组装压缩后上下文（结构化 Markdown 系统消息 + 摘要 + 关键信息）
|
||
↓
|
||
写入压缩日志（auto_context_compressions）
|
||
↓
|
||
用压缩后上下文调用 LLM → 返回响应
|
||
↓
|
||
压缩后 token 仍超阈值? → 二次压缩（最多3级）/ 降级截断
|
||
```
|
||
|
||
**压缩后上下文结构示例**：
|
||
|
||
```markdown
|
||
## 会话上下文摘要（系统压缩）
|
||
|
||
### 已收集信息项
|
||
- 工号: EMP00234（v3，最近更正 14:32）
|
||
- 申请事由: 新员工办公电脑配置（v1）
|
||
- 设备型号: ThinkPad T14（v2，由"笔记本电脑"更正而来）
|
||
|
||
### 已执行动作
|
||
- ✅ 查询库存（14:20）— ThinkPad T14 有货
|
||
- ⏳ 提交审批（14:35）— 等待审批中
|
||
|
||
### 当前任务节点
|
||
资产配置审批流程 → 等待主管审批
|
||
|
||
### 最近对话
|
||
[最近4轮原始对话保留]
|
||
```
|
||
|
||
### 5.2 多轮纠错流程
|
||
|
||
```
|
||
员工: "不对，工号应该是 EMP00235"
|
||
↓
|
||
IntentRouter 识别 → CORRECT 意图
|
||
↓
|
||
解析更正目标: item_key=工号, new_value=EMP00235
|
||
↓
|
||
SessionManager.correct()
|
||
├─ 记录当前快照（全部信息项状态）→ auto_information_snapshots
|
||
├─ 工号 item 版本 v3 → v4，value 更新
|
||
└─ 检查依赖: 是否有其他 item.derived_from 含 "工号"?
|
||
├─ 有 → 返回联动提示列表（如"设备分配人"基于工号推导）
|
||
│ ↓
|
||
│ 员工选择是否联动更新
|
||
│ ├─ 是 → 批量更新关联 item，生成新版本
|
||
│ └─ 否 → 仅更新工号，标记关联 item 为"待确认"
|
||
└─ 无 → 完成
|
||
↓
|
||
返回更正结果（含新版本号、联动提示）→ AI 继续对话
|
||
```
|
||
|
||
### 5.3 更正撤销流程
|
||
|
||
```
|
||
员工/坐席: "撤销刚才的更正"
|
||
↓
|
||
POST /sessions/{session_id}/corrections/undo
|
||
↓
|
||
查询最近一次快照（auto_information_snapshots，按时间倒序第1条）
|
||
↓
|
||
将受影响信息项回滚到快照记录的上一版本值
|
||
↓
|
||
标记该快照为"已撤销"
|
||
↓
|
||
AI 上下文同步更新（注入更正撤销系统消息）
|
||
↓
|
||
返回撤销结果 → 继续对话
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 坐席端影响
|
||
|
||
### 6.1 新增功能
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| 压缩标记 | 会话消息流中，被压缩的区段显示"⚙️ 上下文已压缩（压缩前 8200 → 压缩后 2100 tokens）"标记，可展开查看压缩摘要 |
|
||
| 压缩统计 | 会话详情页顶部新增"压缩次数: N / 平均压缩比: X%"统计卡片 |
|
||
| 版本时间线 | 信息项面板新增"版本历史"Tab，以时间线展示选中 item 的所有版本（含值、版本号、更正时间、更正备注） |
|
||
| 版本 Diff | 版本时间线支持勾选任意两个版本，弹出 diff 对比面板，高亮变更字段 |
|
||
| 快照回溯 | 新增"快照查看"功能，可查看每次更正时刻全部信息项的完整快照 |
|
||
| 撤销按钮 | 更正操作记录旁新增"撤销"按钮，点击触发 undo API |
|
||
|
||
### 6.2 API 变更
|
||
|
||
| 方法 | 路径 | 说明 | Phase |
|
||
|------|------|------|-------|
|
||
| POST | `/itportal/automation/sessions/{session_id}/corrections/undo` | 撤销最近一次更正 | 新增 |
|
||
| GET | `/itportal/automation/sessions/{session_id}/corrections/history` | 获取更正历史（含快照） | 新增 |
|
||
| GET | `/itportal/automation/sessions/{session_id}/information-items/{key}/versions` | 获取单个信息项版本链 | 新增 |
|
||
| GET | `/itportal/automation/sessions/{session_id}/information-items/versions/diff` | 对比两个版本（参数: v1, v2） | 新增 |
|
||
| GET | `/itportal/automation/sessions/{session_id}/compressions` | 获取该会话的压缩日志列表 | 新增 |
|
||
| POST | `/itportal/automation/sessions/{session_id}/corrections` | 批量更正（扩展 Phase 1 单项更正为支持数组） | 变更 |
|
||
|
||
### 6.3 数据表变更
|
||
|
||
**新增表 `auto_context_compressions`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | SERIAL PK | 主键 |
|
||
| session_id | VARCHAR(64) | 关联会话 |
|
||
| tokens_before | INT | 压缩前 token 数 |
|
||
| tokens_after | INT | 压缩后 token 数 |
|
||
| compression_ratio | NUMERIC(5,2) | 压缩比 |
|
||
| task_node | VARCHAR(128) | 压缩时任务节点 |
|
||
| duration_ms | INT | 压缩耗时 |
|
||
| compression_level | SMALLINT | 压缩级别（1/2/3） |
|
||
| summary | TEXT | 压缩摘要内容 |
|
||
| created_at | TIMESTAMP | 创建时间 |
|
||
|
||
**新增表 `auto_information_snapshots`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | SERIAL PK | 主键 |
|
||
| session_id | VARCHAR(64) | 关联会话 |
|
||
| trigger_item_key | VARCHAR(64) | 触发更正的信息项 key |
|
||
| snapshot_data | JSONB | 全部信息项快照（key/value/version） |
|
||
| correction_ids | JSONB | 本次更正涉及的信息项版本 ID 列表 |
|
||
| is_undone | BOOLEAN DEFAULT FALSE | 是否已被撤销 |
|
||
| created_at | TIMESTAMP | 创建时间 |
|
||
|
||
**变更表 `auto_information_items`**：
|
||
|
||
| 字段 | 类型 | 说明 | 变更类型 |
|
||
|------|------|------|----------|
|
||
| derived_from | JSONB | 推导来源 item_key 数组 | 新增列 |
|
||
| correction_reason | VARCHAR(200) | 更正备注 | 新增列 |
|
||
|
||
---
|
||
|
||
## 7. 待确认问题
|
||
|
||
| # | 问题 | 影响范围 | 建议截止 |
|
||
|---|------|----------|----------|
|
||
| Q1 | 上下文压缩阈值 8000 tokens 是否合理？需根据实际使用的 LLM（如 GPT-4o 128k / 文心一言）上下文窗口调整。若用大窗口模型是否仍需压缩（节省成本 vs 复杂度）？ | P2 压缩策略 | 评审会确认 |
|
||
| Q2 | 压缩摘要调用 LLM 会增加单次响应延迟（预计 +1~3s），是否可接受？是否需要在员工端显示"正在整理对话记录…"的过渡提示？ | P2 用户体验 | 评审会确认 |
|
||
| Q3 | 信息项依赖关系（derived_from）由谁维护？是 AI 在收集信息时自动标注，还是由流程模板预定义？ | P3 依赖管理 | 需架构师确认 |
|
||
| Q4 | 更正撤销是否需要限制撤销次数（如仅允许撤销最近 3 次）？无限撤销可能导致版本回退混乱。 | P3 撤销策略 | 产品确认 |
|
||
| Q5 | 批量更正时，若其中某个信息项更正失败（如值校验不通过），是整体回滚还是部分成功？建议整体回滚（原子性），需确认。 | P3 批量更正 | 产品确认 |
|
||
| Q6 | 压缩后的摘要是否需要支持"解压缩"还原原始对话？还是原始消息永久保留在数据库、仅 LLM 传入时用摘要？建议后者：原始消息不删除，仅 LLM context 替换。 | P2 数据保留 | 需架构师确认 |
|
||
| Q7 | 多轮纠错的联动更新提示，由 AI 自然语言提示还是系统结构化卡片提示？建议系统卡片 + AI 补充说明。 | P3 交互形态 | 设计确认 |
|
||
|
||
---
|
||
|
||
## 8. 验收标准
|
||
|
||
### 8.1 P2 — 上下文压缩
|
||
|
||
| # | 验收标准 |
|
||
|---|----------|
|
||
| AC-P2-1 | 构造一个 token 数 > 8000 的超长会话，发送新消息后 AI 正常响应，响应中能正确引用早期提交的信息项值（零丢失） |
|
||
| AC-P2-2 | 压缩后 token 数下降至阈值的 30%~50% 区间；`auto_context_compressions` 表有对应日志记录 |
|
||
| AC-P2-3 | 坐席端会话详情中可见压缩标记，展开可查看压缩摘要内容与压缩前后 token 数 |
|
||
| AC-P2-4 | 连续构造超长对话触发 2 次以上压缩，任务流程节点不漂移，信息项不丢失 |
|
||
| AC-P2-5 | 压缩操作对员工无感知，员工端无额外加载/等待 UI 异常 |
|
||
|
||
### 8.2 P3 — 多轮纠错
|
||
|
||
| # | 验收标准 |
|
||
|---|----------|
|
||
| AC-P3-1 | 同一 session 连续更正 3 个不同信息项（如工号→设备型号→申请事由），每次更正生成新版本，版本号单调递增 |
|
||
| AC-P3-2 | 更正工号后，若设备分配人 derived_from 工号，系统返回联动提示；员工确认后设备分配人同步更新 |
|
||
| AC-P3-3 | 点击撤销按钮，最近一次更正被回滚，信息项恢复到更正前版本；AI 后续对话基于回滚后的值 |
|
||
| AC-P3-4 | 一次提交 2 个信息项更正（批量更正），事务原子性：2 项均成功或均回滚；生成单条快照 |
|
||
| AC-P3-5 | 坐席端版本时间线展示某信息项全部版本；选择 v1 与 v3 可查看 diff，变更字段高亮 |
|
||
| AC-P3-6 | 快照查看功能可回溯任意更正时刻全部信息项状态，数据与 `auto_information_snapshots` 一致 |
|
||
|
||
---
|
||
|
||
## 9. 里程碑建议
|
||
|
||
| 阶段 | 内容 | 预估周期 |
|
||
|------|------|----------|
|
||
| 评审 | PRD 评审 + 待确认问题闭环 | 2 天 |
|
||
| 设计 | 技术方案设计（压缩策略、依赖模型、API 设计） | 3 天 |
|
||
| 开发 | 后端（压缩引擎 + 快照/撤销 + 依赖检查）+ 前端（坐席端版本链/压缩标记） | 8 天 |
|
||
| 联调 | API 联调 + 端到端场景验证 | 3 天 |
|
||
| 测试 | 功能测试 + 超长对话压测 + 多轮纠错边界测试 | 3 天 |
|
||
| 上线 | 灰度发布 → 全量 | 2 天 |
|
||
|
||
---
|
||
|
||
*文档结束。如有疑问请联系产品经理 许清楚。*
|