144 lines
6.8 KiB
Markdown
144 lines
6.8 KiB
Markdown
---
|
||
feature_id: "MARH"
|
||
title: "中台智能体运行时加固（Mid Agent Runtime Hardening）"
|
||
status: "draft"
|
||
version: "0.1.0"
|
||
active_version: "0.1.0"
|
||
version_history:
|
||
- version: "0.1.0"
|
||
ac_range: "AC-MARH-01~12"
|
||
description: "护栏强制执行、中断语义利用、KB工具闭环、超时口径统一、拟人分段增强"
|
||
owners:
|
||
- "product"
|
||
- "backend"
|
||
- "architecture"
|
||
last_updated: "2026-03-05"
|
||
source:
|
||
type: "conversation"
|
||
ref: "基于中台现状缺口清单新增模块特性需求"
|
||
---
|
||
|
||
# 中台智能体运行时加固（MARH）
|
||
|
||
## 1. 背景与目标
|
||
|
||
### 1.1 背景
|
||
当前中台已具备 Agent 编排、Tool Registry、会话追踪与分段响应能力，但运行时层面仍存在关键缺口：
|
||
- 输出护栏执行点未强制化，存在绕过风险
|
||
- `interrupted_segments` 已入参但语义价值未充分利用
|
||
- KB 检索能力存在，但未形成 Agent 默认事实闭环
|
||
- 超时口径与既有规范存在偏差
|
||
- 分段回复策略偏静态，拟人节奏不足
|
||
|
||
### 1.2 目标
|
||
本特性模块聚焦“中台运行时可靠性与可控性”，实现：
|
||
- 输出护栏强制执行与可观测
|
||
- 打断语义可消费、可重规划
|
||
- Agent 默认 KB 事实链路
|
||
- 超时治理与需求口径一致
|
||
- 分段策略具备可配置拟人化能力
|
||
|
||
### 1.3 非目标（Out of Scope）
|
||
- 不覆盖 Java 渠道侧发送队列、取消令牌、终端 UI 细节
|
||
- 不引入新模型供应商或大规模模型替换
|
||
- 不重写现有业务意图体系，仅做运行时增强
|
||
|
||
---
|
||
|
||
## 2. 模块边界（Scope）
|
||
|
||
### 2.1 覆盖
|
||
- 中台 `respond` 输出前护栏拦截与替换
|
||
- 打断片段语义建模与重规划输入
|
||
- KB 检索工具在 Agent 模式下的默认接入策略
|
||
- ReAct/工具/全链路超时统一治理
|
||
- 分段切分与 delay 策略增强
|
||
- 运行时观测字段与指标补齐
|
||
|
||
### 2.2 不覆盖
|
||
- 渠道端真实发送速度控制实现
|
||
- 管理端复杂可视化重构（仅保留必要观测展示）
|
||
|
||
---
|
||
|
||
## 3. 依赖盘点（Dependencies）
|
||
|
||
- `intent-driven-mid-platform` 现有中台主链路与契约
|
||
- 现有护栏模块（输出过滤/流式过滤）
|
||
- 现有检索与知识库模块（metadata + vector）
|
||
- 渠道侧 `segments` 消费协议与打断回传协议
|
||
|
||
---
|
||
|
||
## 4. 用户故事（User Stories）
|
||
|
||
- [US-MARH-01] 作为平台安全负责人，我希望任何中台输出都经过护栏，以便避免违规内容下发。
|
||
- [US-MARH-02] 作为会话体验负责人，我希望打断后中台能理解已中断语义并重新决策，以便对话自然衔接。
|
||
- [US-MARH-03] 作为智能体工程师，我希望 Agent 默认基于 KB 事实回答，以便降低幻觉。
|
||
- [US-MARH-04] 作为系统治理方，我希望超时口径统一并可追踪，以便避免体验抖动。
|
||
- [US-MARH-05] 作为产品方，我希望分段回复更像真人节奏，以便提升用户感知。
|
||
|
||
---
|
||
|
||
## 5. 验收标准（Acceptance Criteria, EARS）
|
||
|
||
- [AC-MARH-01] WHEN 中台生成候选输出 THEN 系统 SHALL 在返回 `segments[]` 前强制执行输出护栏过滤。
|
||
- [AC-MARH-02] WHEN 输出护栏触发拦截/替换 THEN 系统 SHALL 在 `trace.guardrail_triggered` 与审计日志中记录触发结果与规则来源。
|
||
- [AC-MARH-03] WHEN 请求携带 `interrupted_segments` THEN 系统 SHALL 将其纳入上下文重规划输入，并避免重复发送已被打断语义。
|
||
- [AC-MARH-04] WHEN 打断信息为空或异常 THEN 系统 SHALL 使用兜底策略继续响应且不影响主链路可用性。
|
||
- [AC-MARH-05] WHEN Agent 模式处理开放咨询 THEN 系统 SHALL 默认尝试调用 KB 检索工具获取事实依据再组织回复。
|
||
- [AC-MARH-06] WHEN KB 检索无结果或失败 THEN 系统 SHALL 触发可观测降级（fixed/micro_flow）并记录 `fallback_reason_code`。
|
||
- [AC-MARH-07] WHEN 执行 ReAct 循环 THEN 系统 SHALL 将最大循环次数限制为 3~5 次。
|
||
- [AC-MARH-08] WHEN 执行工具调用 THEN 系统 SHALL 将单工具超时限制为 ≤2000ms。
|
||
- [AC-MARH-09] WHEN 执行整轮中台响应 THEN 系统 SHALL 将全链路超时限制为 ≤8000ms 并在超时时可预测降级。
|
||
- [AC-MARH-10] WHEN 输出文本生成后 THEN 系统 SHALL 按可配置策略进行分段（按语义/长度）并输出 `delay_after`。
|
||
- [AC-MARH-11] WHEN 分段策略启用拟人参数 THEN 系统 SHALL 支持按字数区间生成不同 delay，且可按租户配置覆盖。
|
||
- [AC-MARH-12] WHEN 一轮响应完成 THEN 系统 SHALL 输出完整运行时观测（guardrail、interrupt、kb_hit、timeouts、segment_stats）。
|
||
|
||
---
|
||
|
||
## 6. 追踪映射（Traceability）
|
||
|
||
| AC ID | Endpoint | 方法 | operationId（建议） | 备注 |
|
||
|------|----------|------|---------------------|------|
|
||
| AC-MARH-01 | /mid/dialogue/respond | POST | respondDialogue | 输出前护栏强制执行 |
|
||
| AC-MARH-02 | /mid/dialogue/respond | POST | respondDialogue | 护栏触发可观测 |
|
||
| AC-MARH-03 | /mid/dialogue/respond | POST | respondDialogue | 打断语义重规划 |
|
||
| AC-MARH-04 | /mid/dialogue/respond | POST | respondDialogue | 打断异常兜底 |
|
||
| AC-MARH-05 | /mid/dialogue/respond | POST | respondDialogue | Agent 默认 KB 工具链 |
|
||
| AC-MARH-06 | /mid/dialogue/respond | POST | respondDialogue | KB 失败降级 |
|
||
| AC-MARH-07 | /mid/dialogue/respond | POST | respondDialogue | ReAct 循环上限 |
|
||
| AC-MARH-08 | /mid/dialogue/respond | POST | respondDialogue | 单工具超时 |
|
||
| AC-MARH-09 | /mid/dialogue/respond | POST | respondDialogue | 全链路超时 |
|
||
| AC-MARH-10 | /mid/dialogue/respond | POST | respondDialogue | 分段策略输出 |
|
||
| AC-MARH-11 | /mid/dialogue/respond | POST | respondDialogue | 拟人 delay 配置化 |
|
||
| AC-MARH-12 | /mid/dialogue/respond | POST | respondDialogue | 运行时观测闭环 |
|
||
|
||
---
|
||
|
||
## 7. 非功能性需求（NFR）
|
||
|
||
- [NFR-MARH-01] 护栏执行不应导致 P95 时延增加超过 15%。
|
||
- [NFR-MARH-02] 中断重规划逻辑错误率（重复回复/上下文错位）低于 1%。
|
||
- [NFR-MARH-03] KB 默认链路在有可用数据时命中率达到设定阈值（由租户配置）。
|
||
- [NFR-MARH-04] 超时与降级路径可重复验证，且错误码口径统一。
|
||
|
||
---
|
||
|
||
## 8. 风险与缓解
|
||
|
||
| 风险 | 影响 | 概率 | 缓解措施 |
|
||
|------|------|------|---------|
|
||
| 护栏误杀正常回复 | 体验受损 | 中 | 提供分级策略与白名单回放审核 |
|
||
| 打断语义利用过度导致信息丢失 | 对话不连贯 | 中 | 引入“仅移除未送达语义”与可观测对比 |
|
||
| KB 默认调用引入时延 | 首字延迟上升 | 中 | top_k 限制 + 超时降级 + 结果摘要缓存 |
|
||
| 分段策略过度复杂 | 行为难以预测 | 低 | 参数模板化 + 租户灰度开关 |
|
||
|
||
---
|
||
|
||
## 9. 发布建议（分阶段）
|
||
|
||
- Phase 1：护栏强制执行 + 超时口径对齐（AC-MARH-01/02/07/08/09）
|
||
- Phase 2：打断语义重规划 + KB 默认工具链（AC-MARH-03/04/05/06）
|
||
- Phase 3：分段拟人策略 + 观测闭环（AC-MARH-10/11/12）
|