ai-robot-core/spec/mid-agent-runtime-hardening/runtime-iteration-and-tools-tracking.md

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

文档目的：记录“已完成迭代需求”“待完成工具”“工具使用说明”，作为后续对齐与更新的追溯入口。

约定：本文件是工作台账，不替代 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 需求与规范产物（已完成）

• spec/mid-agent-runtime-hardening/requirements.md
• spec/mid-agent-runtime-hardening/scope.md
• spec/mid-agent-runtime-hardening/openapi.provider.yaml
• spec/mid-agent-runtime-hardening/openapi.deps.yaml
• spec/mid-agent-runtime-hardening/design.md
• spec/mid-agent-runtime-hardening/tasks.md

2.2 运行时能力（已完成）

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

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

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

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

### 变更记录（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