# 中台运行时加固：迭代与工具追溯台账

> 文档目的：记录“已完成迭代需求”“待完成工具”“工具使用说明”，作为后续对齐与更新的追溯入口。
> 
> 约定：本文件是工作台账，不替代 `requirements.md / design.md / tasks.md` 的正式规范地位。

---

## 1. 当前模块与范围

- 模块目录：`spec/mid-agent-runtime-hardening/`
- 当前需求版本：`v0.1.0`
- AC 范围：`AC-MARH-01 ~ AC-MARH-12`
- 当前目标：中台运行时加固（护栏、打断、KB默认工具链、超时统一、拟人分段、观测闭环）

---

## 2. 本轮已完成（截至当前）

> 说明：以下状态来自当前会话确认与实现验收检查；若后续代码有回滚/重构，请同步更新。

### 2.1 需求与规范产物（已完成）

- [x] `spec/mid-agent-runtime-hardening/requirements.md`
- [x] `spec/mid-agent-runtime-hardening/scope.md`
- [x] `spec/mid-agent-runtime-hardening/openapi.provider.yaml`
- [x] `spec/mid-agent-runtime-hardening/openapi.deps.yaml`
- [x] `spec/mid-agent-runtime-hardening/design.md`
- [x] `spec/mid-agent-runtime-hardening/tasks.md`

### 2.2 运行时能力（已完成）

- [x] 输出护栏强制执行链路（AC-MARH-01/02）
- [x] interrupted_segments 中断语义处理与兜底（AC-MARH-03/04）
- [x] Agent 默认 KB 工具链 + 失败降级（AC-MARH-05/06）
- [x] ReAct 循环上限与超时口径统一（AC-MARH-07/08/09）
- [x] 分段拟人策略（语义/长度 + delay）与统计（AC-MARH-10/11）
- [x] 运行时观测闭环（AC-MARH-12）

### 2.3 结构化提示

- 当前已观测到：代码注释中存在超出 `AC-MARH-01~12` 范围的 AC 编号引用，后续建议对齐清理，避免追踪口径不一致。

---

## 3. 工具建设现状与计划

## 3.1 已完成工具

### 工具 A：`kb_search_dynamic`

- 状态：✅ 已实现（在另一个并行窗口完成）
- 目标：通过元数据配置动态构建检索过滤参数，而非固定入参写死。
- 核心价值：
  - 适配不同场景差异化过滤需求
  - 运营配置变化可直接生效
  - 避免 Agent 无工具可用导致空转

---

## 3.2 待完成工具（下一阶段）

### 工具 B：`intent_hint`

- 状态：⏳ 待实施
- 定位：轻量意图识别 + 路由建议（软信号）
- 注意：不是最终裁决器，最终由 `policy_router` 决策。

### 工具 C：`high_risk_check`

- 状态：✅ 已实现
- 定位：高风险快速判定（退款/投诉升级/隐私敏感承诺/转人工）
- 目标：减少高风险场景误路由与慢路由
- 核心特性：
  - 基于租户元数据配置进行风险判定（从 HighRiskPolicy 表读取）
  - 支持关键词 + 正则 + 优先级匹配
  - 租户隔离（tenant_id 必须参与查询）
  - 超时 <= 500ms（可配置）
  - 返回结构化结果，不抛硬异常
  - 高风险优先于普通意图路由

### 工具 D：`memory_recall`

- 状态：✅ 已实现
- 定位：对话前读取用户记忆（profile/facts/preferences/summary/slots）
- 目标：减少重复追问、增强上下文连续性
- 核心特性：
  - 读取 profile/facts/preferences/last_summary/slots
  - 槽位冲突优先级：user_confirmed > rule_extracted > llm_inferred > default
  - 超时 <= 1000ms（可配置）
  - 失败不抛硬异常，返回空记忆包 + fallback_reason_code
  - 多租户隔离正确（tenant_id 必须参与查询）
  - 输出 missing_slots，供上层决定是否追问

### 工具 E：`memory_update_async`

- 状态：⏳ 待实施
- 定位：对话后异步记忆更新
- 目标：不阻塞主链路响应。

### 工具 F：`session_mode_control`（可选）

- 状态：⏳ 规划中
- 定位：智能体触发会话模式切换（BOT_ACTIVE/HUMAN_ACTIVE）
- 目标：转人工与回切更自动化。

---

## 4. 工具使用说明（当前约定）

## 4.1 `kb_search_dynamic` 使用说明（初版）

### 输入（概念）
- `query`：用户问题/检索问题
- `scene`：场景标识（决定元数据过滤策略）
- `tenant_id`：租户隔离
- `top_k`：召回数量
- `context`：会话已知槽位

### 核心行为
1. 基于元数据配置读取“生效 + 可过滤 + 适用知识库文档”的字段
2. 按字段类型（单选/多选/文本）动态生成过滤条件
3. 处理必填缺失与默认值回填
4. 执行检索并返回结构化结果

### 输出（概念）
- `hits`
- `applied_filter`
- `missing_required_slots`
- `filter_debug`
- `fallback_reason_code`

### 调用建议
- 优先用于开放咨询场景
- 低置信度或缺关键槽位时，不硬失败，可回退追问或降级模式

---

## 4.2 `intent_hint` 预期使用说明（待落地）

### 作用
- 提供低成本方向提示，减少 Agent 盲思考

### 非作用
- 不直接替代意图规则
- 不直接决定最终路由

### 协同原则
- 规则主导（硬约束） + hint 辅助（软信号） + router 裁决（最终）

---

## 5. 回归测试建议（页面联调优先）

1. 普通咨询：验证 KB 工具调用与分段输出
2. 高风险输入：验证接管/降级与 trace 字段
3. 打断重入：验证 interrupt_consumed 与语义连续性
4. 超时场景：验证 2s/8s 口径与 fallback_reason_code

---

## 6. 后续更新机制

每次确认细节或功能实现后，至少更新以下字段：

- 版本与日期
- 工具状态（⏳/🔄/✅）
- 输入输出变化
- 使用说明变化
- 风险与限制

建议在每次迭代结束时追加一段“变更记录”：

```markdown
### 变更记录（YYYY-MM-DD）
- 本次新增：...
- 本次调整：...
- 本次风险：...
- 下一步：...
```

---

## 7. 快速索引（相关文档）

- 需求：`spec/mid-agent-runtime-hardening/requirements.md`
- 设计：`spec/mid-agent-runtime-hardening/design.md`
- 任务：`spec/mid-agent-runtime-hardening/tasks.md`
- Provider 契约：`spec/mid-agent-runtime-hardening/openapi.provider.yaml`
- Deps 契约：`spec/mid-agent-runtime-hardening/openapi.deps.yaml`
- 协议：`docs/session-handoff-protocol.md`