# 中台智能体运行时加固（MARH）设计文档

## 1. 设计目标

围绕 AC-MARH-01~12，构建中台运行时加固层，确保输出可控、打断可消费、检索可依赖、时延可治理、节奏可调优。

---

## 2. 架构改造点

## 2.1 对话主链路增强
在 `respond` 主流程增加以下阶段：
1. `interrupt_context_enricher`：消费 `interrupted_segments`
2. `kb_default_tool_stage`：Agent 默认检索工具尝试
3. `output_guardrail_stage`：输出前强制过滤
4. `segment_humanizer`：语义+长度分段与 delay 计算
5. `runtime_observer`：补齐 trace 与 metrics

## 2.2 超时统一治理
- ReAct 最大循环：3~5
- 单工具超时：<=2000ms
- 全链路超时：<=8000ms
- 超时均落 `fallback_reason_code`

---

## 3. 关键流程

## 3.1 正常响应流程
1. 收到请求并校验已送达历史
2. 若存在中断片段则做语义去重标记
3. policy_router 决策
4. Agent 模式默认调用 KB 工具（可降级）
5. 生成候选文本
6. 输出护栏强制过滤
7. 分段拟人策略生成 `segments[]`
8. 输出 trace（guardrail/interrupt/kb_hit/timeouts/segment_stats）

## 3.2 打断重入流程
1. 新请求带 `interrupted_segments`
2. 重规划时避开被打断语义
3. 若中断信息异常则兜底继续

---

## 4. 数据结构与字段补充

新增或强化 trace 字段：
- `guardrail_triggered`
- `guardrail_rule_id`
- `interrupt_consumed`
- `kb_tool_called`
- `kb_hit`
- `segment_stats`
- `timeout_profile`

---

## 5. 组件职责

- `OutputGuardrailExecutor`
  - 强制执行输出过滤
  - 返回 blocked/filtered_text/rule_id

- `InterruptContextEnricher`
  - 将中断片段转成重规划上下文
  - 提供异常兜底

- `DefaultKbToolRunner`
  - Agent 默认 KB 检索
  - 失败时返回降级信号

- `SegmentHumanizer`
  - 文本分段与 delay 生成
  - 支持租户覆盖配置

- `RuntimeObserver`
  - 汇总 trace 与 metrics

---

## 6. 与 AC 映射

- AC-MARH-01/02：`OutputGuardrailExecutor`
- AC-MARH-03/04：`InterruptContextEnricher`
- AC-MARH-05/06：`DefaultKbToolRunner`
- AC-MARH-07/08/09：`TimeoutGovernor + Orchestrator`
- AC-MARH-10/11：`SegmentHumanizer`
- AC-MARH-12：`RuntimeObserver`