# 意图驱动智能体中台改造（仅中台侧）设计文档

## 1. 设计目标

围绕 `requirements.md` 中 AC-IDMP-01~10，给出可实施的中台设计：
- 对外协议统一
- 决策模式可治理
- 高风险场景可强接管
- 工具链路可观测、可降级

---

## 2. 总体架构

1. 请求入口层
- `DialogueController`：接收渠道请求、基础校验、注入 request_id

2. 策略路由层
- `PolicyRouter`：根据意图、风险、置信度、会话模式确定执行路径

3. 执行层
- `AgentOrchestrator`：ReAct 循环与工具编排
- `MicroFlowExecutor`：高风险 SOP 微流程执行
- `FixedResponder`：固定回复
- `TransferResponder`：转人工兜底

4. 依赖适配层
- `MetadataAdapter`：意图驱动检索链路
- `MemoryAdapter`：recall/update

5. 护栏与输出层
- `OutputGuardrail`：合规与承诺边界校验
- `SegmentFormatter`：统一封装 `segments[] + trace`

6. 可观测与审计
- `TraceLogger`：记录 mode、tool_calls、fallback_reason_code、generation_id

---

## 3. 关键流程

## 3.1 会话响应主流程
1. 入参校验：`session_id/user_message/history`
2. 读取会话模式（BOT_ACTIVE/HUMAN_ACTIVE）
3. 召回记忆（可失败降级）
4. `PolicyRouter` 决策模式
5. 执行模式链路
6. 输出护栏校验
7. 格式化并返回 `segments[] + trace`
8. 异步记录审计日志

## 3.2 打断重入流程
1. 同一 session 收到新请求，生成新 `generation_id`
2. 执行层只处理最新 generation
3. 旧 generation 结果写审计但不对外生效

## 3.3 人工模式流程
1. 模式接口将 session 置为 `HUMAN_ACTIVE`
2. 会话响应接口直接走 `transfer` 结果或返回人工处理提示
3. 仍接受消息上报，保持数据闭环

---

## 4. 数据结构设计

## 4.1 入参模型（核心）
- `session_id: string`
- `user_message: string`
- `history: Message[]`（仅已送达）
- `interrupted_segments?: Segment[]`

## 4.2 出参模型（核心）
- `segments: Segment[]`
  - `segment_id`
  - `text`
  - `delay_after`
- `trace`
  - `mode`
  - `intent`
  - `tools_used`
  - `fallback_reason_code`
  - `guardrail_triggered`
  - `request_id`
  - `generation_id`

---

## 5. 决策规则设计

## 5.1 PolicyRouter 决策矩阵
- 高风险命中（退款/投诉/隐私承诺/转人工）=> `micro_flow` 或 `transfer`
- 低风险且意图清晰 => `agent`
- 工具不可用或置信度低 => `fixed`
- 人工模式开启 => `transfer`

## 5.2 降级策略
- 工具超时（单工具 2s）=> 降级 `fixed`
- 连续关键工具失败 => 降级 `transfer`
- 护栏拦截 => 强制 `micro_flow` 或 `transfer`

---

## 6. 检索与记忆策略

## 6.1 Metadata 检索固定链路
`intent -> target_kbs -> metadata_filter -> vector_search -> rerank`

元数据最小过滤建议：
- `grade`
- `subject`
- `scene`
- `flow_step`
- `intent_type`
- `status=active`

## 6.2 Memory 接入
- 对话前 `recall(user_id, session_id)`
- 对话后异步 `update(messages)`
- recall 失败不阻断主链路

---

## 7. 可观测与治理

必须采集：
- 会话维度：`session_id/request_id/generation_id`
- 决策维度：`mode/intent/fallback_reason_code`
- 工具维度：`tool_name/duration/result/error_code`
- 护栏维度：`guardrail_triggered/policy_code`

建议告警：
- P95 时延超阈值
- tool timeout rate 超阈值
- fallback rate 激增
- transfer rate 异常上升

---

## 8. 与 AC 的映射

- AC-IDMP-01/02：`SegmentFormatter + TraceLogger`
- AC-IDMP-03/04：`HistoryValidator + GenerationGuard`
- AC-IDMP-05/06：`PolicyRouter + FallbackManager`
- AC-IDMP-07：`TraceLogger`
- AC-IDMP-08：`MessageReportController`
- AC-IDMP-09：`SessionModeController`
- AC-IDMP-10：`MetadataAdapter`