192 lines
5.9 KiB
Markdown
192 lines
5.9 KiB
Markdown
# 中台运行时加固：迭代与工具追溯台账
|
||
|
||
> 文档目的：记录“已完成迭代需求”“待完成工具”“工具使用说明”，作为后续对齐与更新的追溯入口。
|
||
>
|
||
> 约定：本文件是工作台账，不替代 `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`
|