spec: add intent-driven-mid-platform and mid-agent-runtime-hardening specifications [AC-IDMP-01~20, AC-MARH-01~12]
This commit is contained in:
MerCry
parent
1b325f5aeb
commit
3d9f718f5f
|
|
@ -0,0 +1,147 @@
|
||||||
|
# 意图驱动智能体中台改造（仅中台侧）设计文档
|
||||||
|
|
||||||
|
## 1. 设计目标
|
||||||
|
|
||||||
|
围绕 `requirements.md` 中 AC-IDMP-01~10，给出可实施的中台设计：
|
||||||
|
- 对外协议统一
|
||||||
|
- 决策模式可治理
|
||||||
|
- 高风险场景可强接管
|
||||||
|
- 工具链路可观测、可降级
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 总体架构
|
||||||
|
|
||||||
|
1. 请求入口层
|
||||||
|
- `DialogueController`：接收渠道请求、基础校验、注入 request_id
|
||||||
|
|
||||||
|
2. 策略路由层
|
||||||
|
- `PolicyRouter`：根据意图、风险、置信度、会话模式确定执行路径
|
||||||
|
|
||||||
|
3. 执行层
|
||||||
|
- `AgentOrchestrator`：ReAct 循环与工具编排
|
||||||
|
- `MicroFlowExecutor`：高风险 SOP 微流程执行
|
||||||
|
- `FixedResponder`：固定回复
|
||||||
|
- `TransferResponder`：转人工兜底
|
||||||
|
|
||||||
|
4. 依赖适配层
|
||||||
|
- `MetadataAdapter`：意图驱动检索链路
|
||||||
|
- `MemoryAdapter`：recall/update
|
||||||
|
|
||||||
|
5. 护栏与输出层
|
||||||
|
- `OutputGuardrail`：合规与承诺边界校验
|
||||||
|
- `SegmentFormatter`：统一封装 `segments[] + trace`
|
||||||
|
|
||||||
|
6. 可观测与审计
|
||||||
|
- `TraceLogger`：记录 mode、tool_calls、fallback_reason_code、generation_id
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 关键流程
|
||||||
|
|
||||||
|
## 3.1 会话响应主流程
|
||||||
|
1. 入参校验：`session_id/user_message/history`
|
||||||
|
2. 读取会话模式（BOT_ACTIVE/HUMAN_ACTIVE）
|
||||||
|
3. 召回记忆（可失败降级）
|
||||||
|
4. `PolicyRouter` 决策模式
|
||||||
|
5. 执行模式链路
|
||||||
|
6. 输出护栏校验
|
||||||
|
7. 格式化并返回 `segments[] + trace`
|
||||||
|
8. 异步记录审计日志
|
||||||
|
|
||||||
|
## 3.2 打断重入流程
|
||||||
|
1. 同一 session 收到新请求，生成新 `generation_id`
|
||||||
|
2. 执行层只处理最新 generation
|
||||||
|
3. 旧 generation 结果写审计但不对外生效
|
||||||
|
|
||||||
|
## 3.3 人工模式流程
|
||||||
|
1. 模式接口将 session 置为 `HUMAN_ACTIVE`
|
||||||
|
2. 会话响应接口直接走 `transfer` 结果或返回人工处理提示
|
||||||
|
3. 仍接受消息上报，保持数据闭环
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 数据结构设计
|
||||||
|
|
||||||
|
## 4.1 入参模型（核心）
|
||||||
|
- `session_id: string`
|
||||||
|
- `user_message: string`
|
||||||
|
- `history: Message[]`（仅已送达）
|
||||||
|
- `interrupted_segments?: Segment[]`
|
||||||
|
|
||||||
|
## 4.2 出参模型（核心）
|
||||||
|
- `segments: Segment[]`
|
||||||
|
- `segment_id`
|
||||||
|
- `text`
|
||||||
|
- `delay_after`
|
||||||
|
- `trace`
|
||||||
|
- `mode`
|
||||||
|
- `intent`
|
||||||
|
- `tools_used`
|
||||||
|
- `fallback_reason_code`
|
||||||
|
- `guardrail_triggered`
|
||||||
|
- `request_id`
|
||||||
|
- `generation_id`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 决策规则设计
|
||||||
|
|
||||||
|
## 5.1 PolicyRouter 决策矩阵
|
||||||
|
- 高风险命中（退款/投诉/隐私承诺/转人工）=> `micro_flow` 或 `transfer`
|
||||||
|
- 低风险且意图清晰 => `agent`
|
||||||
|
- 工具不可用或置信度低 => `fixed`
|
||||||
|
- 人工模式开启 => `transfer`
|
||||||
|
|
||||||
|
## 5.2 降级策略
|
||||||
|
- 工具超时（单工具 2s）=> 降级 `fixed`
|
||||||
|
- 连续关键工具失败 => 降级 `transfer`
|
||||||
|
- 护栏拦截 => 强制 `micro_flow` 或 `transfer`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. 检索与记忆策略
|
||||||
|
|
||||||
|
## 6.1 Metadata 检索固定链路
|
||||||
|
`intent -> target_kbs -> metadata_filter -> vector_search -> rerank`
|
||||||
|
|
||||||
|
元数据最小过滤建议：
|
||||||
|
- `grade`
|
||||||
|
- `subject`
|
||||||
|
- `scene`
|
||||||
|
- `flow_step`
|
||||||
|
- `intent_type`
|
||||||
|
- `status=active`
|
||||||
|
|
||||||
|
## 6.2 Memory 接入
|
||||||
|
- 对话前 `recall(user_id, session_id)`
|
||||||
|
- 对话后异步 `update(messages)`
|
||||||
|
- recall 失败不阻断主链路
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. 可观测与治理
|
||||||
|
|
||||||
|
必须采集：
|
||||||
|
- 会话维度：`session_id/request_id/generation_id`
|
||||||
|
- 决策维度：`mode/intent/fallback_reason_code`
|
||||||
|
- 工具维度：`tool_name/duration/result/error_code`
|
||||||
|
- 护栏维度：`guardrail_triggered/policy_code`
|
||||||
|
|
||||||
|
建议告警：
|
||||||
|
- P95 时延超阈值
|
||||||
|
- tool timeout rate 超阈值
|
||||||
|
- fallback rate 激增
|
||||||
|
- transfer rate 异常上升
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. 与 AC 的映射
|
||||||
|
|
||||||
|
- AC-IDMP-01/02：`SegmentFormatter + TraceLogger`
|
||||||
|
- AC-IDMP-03/04：`HistoryValidator + GenerationGuard`
|
||||||
|
- AC-IDMP-05/06：`PolicyRouter + FallbackManager`
|
||||||
|
- AC-IDMP-07：`TraceLogger`
|
||||||
|
- AC-IDMP-08：`MessageReportController`
|
||||||
|
- AC-IDMP-09：`SessionModeController`
|
||||||
|
- AC-IDMP-10：`MetadataAdapter`
|
||||||
|
|
@ -0,0 +1,161 @@
|
||||||
|
openapi: 3.0.3
|
||||||
|
info:
|
||||||
|
title: Intent-Driven Mid Platform Dependency API
|
||||||
|
version: 0.3.0
|
||||||
|
x-contract-level: L1
|
||||||
|
paths:
|
||||||
|
/deps/metadata/query:
|
||||||
|
post:
|
||||||
|
operationId: queryMetadata
|
||||||
|
summary: 查询元数据与知识内容
|
||||||
|
x-requirements:
|
||||||
|
- AC-IDMP-10
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/MetadataQueryRequest'
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: 查询成功
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/MetadataQueryResponse'
|
||||||
|
|
||||||
|
/deps/memory/recall:
|
||||||
|
post:
|
||||||
|
operationId: recallMemory
|
||||||
|
summary: 召回用户记忆
|
||||||
|
x-requirements:
|
||||||
|
- AC-IDMP-13
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/RecallRequest'
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: 召回成功
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/RecallResponse'
|
||||||
|
|
||||||
|
/deps/memory/update:
|
||||||
|
post:
|
||||||
|
operationId: updateMemory
|
||||||
|
summary: 更新用户记忆
|
||||||
|
x-requirements:
|
||||||
|
- AC-IDMP-14
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/UpdateRequest'
|
||||||
|
responses:
|
||||||
|
'202':
|
||||||
|
description: 已接受异步更新
|
||||||
|
|
||||||
|
components:
|
||||||
|
schemas:
|
||||||
|
MetadataQueryRequest:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- intent
|
||||||
|
- target_kbs
|
||||||
|
- metadata_filter
|
||||||
|
- query
|
||||||
|
properties:
|
||||||
|
intent:
|
||||||
|
type: string
|
||||||
|
target_kbs:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
metadata_filter:
|
||||||
|
type: object
|
||||||
|
additionalProperties: true
|
||||||
|
query:
|
||||||
|
type: string
|
||||||
|
|
||||||
|
MetadataQueryResponse:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- items
|
||||||
|
properties:
|
||||||
|
items:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/MetadataItem'
|
||||||
|
|
||||||
|
MetadataItem:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- id
|
||||||
|
- score
|
||||||
|
- content
|
||||||
|
properties:
|
||||||
|
id:
|
||||||
|
type: string
|
||||||
|
score:
|
||||||
|
type: number
|
||||||
|
content:
|
||||||
|
type: string
|
||||||
|
metadata:
|
||||||
|
type: object
|
||||||
|
additionalProperties: true
|
||||||
|
|
||||||
|
RecallRequest:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- user_id
|
||||||
|
- session_id
|
||||||
|
properties:
|
||||||
|
user_id:
|
||||||
|
type: string
|
||||||
|
session_id:
|
||||||
|
type: string
|
||||||
|
|
||||||
|
RecallResponse:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
profile:
|
||||||
|
type: object
|
||||||
|
description: 基础属性记忆（年级、地区、渠道等）
|
||||||
|
additionalProperties: true
|
||||||
|
facts:
|
||||||
|
type: array
|
||||||
|
description: 事实型记忆（已购课程、学习结论等）
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
preferences:
|
||||||
|
type: object
|
||||||
|
description: 偏好记忆（语气偏好、关注科目等）
|
||||||
|
additionalProperties: true
|
||||||
|
last_summary:
|
||||||
|
type: string
|
||||||
|
description: 最近一次会话摘要
|
||||||
|
|
||||||
|
UpdateRequest:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- user_id
|
||||||
|
- session_id
|
||||||
|
- messages
|
||||||
|
properties:
|
||||||
|
user_id:
|
||||||
|
type: string
|
||||||
|
session_id:
|
||||||
|
type: string
|
||||||
|
messages:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: object
|
||||||
|
additionalProperties: true
|
||||||
|
summary:
|
||||||
|
type: string
|
||||||
|
description: 本轮会话摘要（可选，由中台异步生成后回写）
|
||||||
|
|
@ -0,0 +1,338 @@
|
||||||
|
openapi: 3.0.3
|
||||||
|
info:
|
||||||
|
title: Intent-Driven Mid Platform Provider API
|
||||||
|
version: 0.3.0
|
||||||
|
x-contract-level: L2
|
||||||
|
paths:
|
||||||
|
/mid/dialogue/respond:
|
||||||
|
post:
|
||||||
|
operationId: respondDialogue
|
||||||
|
summary: 生成中台分段响应
|
||||||
|
x-requirements:
|
||||||
|
- AC-IDMP-01
|
||||||
|
- AC-IDMP-02
|
||||||
|
- AC-IDMP-03
|
||||||
|
- AC-IDMP-04
|
||||||
|
- AC-IDMP-05
|
||||||
|
- AC-IDMP-06
|
||||||
|
- AC-IDMP-07
|
||||||
|
- AC-IDMP-11
|
||||||
|
- AC-IDMP-12
|
||||||
|
- AC-IDMP-15
|
||||||
|
- AC-IDMP-16
|
||||||
|
- AC-IDMP-17
|
||||||
|
- AC-IDMP-18
|
||||||
|
- AC-IDMP-19
|
||||||
|
- AC-IDMP-20
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/DialogueRequest'
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: 成功生成分段响应
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/DialogueResponse'
|
||||||
|
'400':
|
||||||
|
description: 请求参数错误
|
||||||
|
'500':
|
||||||
|
description: 服务内部错误
|
||||||
|
|
||||||
|
/mid/messages/report:
|
||||||
|
post:
|
||||||
|
operationId: reportMessages
|
||||||
|
summary: 上报会话消息与事件
|
||||||
|
x-requirements:
|
||||||
|
- AC-IDMP-08
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/MessageReportRequest'
|
||||||
|
responses:
|
||||||
|
'202':
|
||||||
|
description: 已接受异步处理
|
||||||
|
'400':
|
||||||
|
description: 请求参数错误
|
||||||
|
|
||||||
|
/mid/sessions/{sessionId}/mode:
|
||||||
|
post:
|
||||||
|
operationId: switchSessionMode
|
||||||
|
summary: 切换会话模式
|
||||||
|
x-requirements:
|
||||||
|
- AC-IDMP-09
|
||||||
|
parameters:
|
||||||
|
- name: sessionId
|
||||||
|
in: path
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/SwitchModeRequest'
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: 模式切换成功
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/SwitchModeResponse'
|
||||||
|
'400':
|
||||||
|
description: 请求参数错误
|
||||||
|
|
||||||
|
components:
|
||||||
|
schemas:
|
||||||
|
DialogueRequest:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- session_id
|
||||||
|
- user_message
|
||||||
|
- history
|
||||||
|
properties:
|
||||||
|
session_id:
|
||||||
|
type: string
|
||||||
|
user_id:
|
||||||
|
type: string
|
||||||
|
description: 用于记忆召回与更新的用户标识
|
||||||
|
user_message:
|
||||||
|
type: string
|
||||||
|
minLength: 1
|
||||||
|
maxLength: 2000
|
||||||
|
history:
|
||||||
|
type: array
|
||||||
|
description: 仅允许已送达历史
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/HistoryMessage'
|
||||||
|
interrupted_segments:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/InterruptedSegment'
|
||||||
|
feature_flags:
|
||||||
|
$ref: '#/components/schemas/FeatureFlags'
|
||||||
|
|
||||||
|
FeatureFlags:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
agent_enabled:
|
||||||
|
type: boolean
|
||||||
|
description: 会话级 Agent 灰度开关
|
||||||
|
rollback_to_legacy:
|
||||||
|
type: boolean
|
||||||
|
description: 强制回滚传统链路
|
||||||
|
|
||||||
|
HistoryMessage:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- role
|
||||||
|
- content
|
||||||
|
properties:
|
||||||
|
role:
|
||||||
|
type: string
|
||||||
|
enum: [user, assistant, human]
|
||||||
|
content:
|
||||||
|
type: string
|
||||||
|
|
||||||
|
InterruptedSegment:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- segment_id
|
||||||
|
- content
|
||||||
|
properties:
|
||||||
|
segment_id:
|
||||||
|
type: string
|
||||||
|
content:
|
||||||
|
type: string
|
||||||
|
|
||||||
|
DialogueResponse:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- segments
|
||||||
|
- trace
|
||||||
|
properties:
|
||||||
|
segments:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/Segment'
|
||||||
|
trace:
|
||||||
|
$ref: '#/components/schemas/TraceInfo'
|
||||||
|
|
||||||
|
Segment:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- segment_id
|
||||||
|
- text
|
||||||
|
- delay_after
|
||||||
|
properties:
|
||||||
|
segment_id:
|
||||||
|
type: string
|
||||||
|
text:
|
||||||
|
type: string
|
||||||
|
delay_after:
|
||||||
|
type: integer
|
||||||
|
minimum: 0
|
||||||
|
|
||||||
|
TraceInfo:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- mode
|
||||||
|
properties:
|
||||||
|
mode:
|
||||||
|
type: string
|
||||||
|
enum: [agent, micro_flow, fixed, transfer]
|
||||||
|
intent:
|
||||||
|
type: string
|
||||||
|
request_id:
|
||||||
|
type: string
|
||||||
|
generation_id:
|
||||||
|
type: string
|
||||||
|
guardrail_triggered:
|
||||||
|
type: boolean
|
||||||
|
fallback_reason_code:
|
||||||
|
type: string
|
||||||
|
react_iterations:
|
||||||
|
type: integer
|
||||||
|
minimum: 0
|
||||||
|
maximum: 5
|
||||||
|
description: ReAct 实际循环次数
|
||||||
|
timeout_profile:
|
||||||
|
$ref: '#/components/schemas/TimeoutProfile'
|
||||||
|
metrics_snapshot:
|
||||||
|
$ref: '#/components/schemas/MetricsSnapshot'
|
||||||
|
high_risk_policy_set:
|
||||||
|
type: array
|
||||||
|
description: 当前启用的高风险最小场景集
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
enum: [refund, complaint_escalation, privacy_sensitive_promise, transfer]
|
||||||
|
tools_used:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
tool_calls:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/ToolCallTrace'
|
||||||
|
|
||||||
|
TimeoutProfile:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
per_tool_timeout_ms:
|
||||||
|
type: integer
|
||||||
|
maximum: 2000
|
||||||
|
end_to_end_timeout_ms:
|
||||||
|
type: integer
|
||||||
|
maximum: 8000
|
||||||
|
|
||||||
|
MetricsSnapshot:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
task_completion_rate:
|
||||||
|
type: number
|
||||||
|
format: float
|
||||||
|
slot_completion_rate:
|
||||||
|
type: number
|
||||||
|
format: float
|
||||||
|
wrong_transfer_rate:
|
||||||
|
type: number
|
||||||
|
format: float
|
||||||
|
no_recall_rate:
|
||||||
|
type: number
|
||||||
|
format: float
|
||||||
|
avg_latency_ms:
|
||||||
|
type: number
|
||||||
|
format: float
|
||||||
|
|
||||||
|
ToolCallTrace:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- tool_name
|
||||||
|
- duration_ms
|
||||||
|
- status
|
||||||
|
properties:
|
||||||
|
tool_name:
|
||||||
|
type: string
|
||||||
|
tool_type:
|
||||||
|
type: string
|
||||||
|
enum: [internal, mcp]
|
||||||
|
registry_version:
|
||||||
|
type: string
|
||||||
|
auth_applied:
|
||||||
|
type: boolean
|
||||||
|
duration_ms:
|
||||||
|
type: integer
|
||||||
|
minimum: 0
|
||||||
|
status:
|
||||||
|
type: string
|
||||||
|
enum: [ok, timeout, error, rejected]
|
||||||
|
error_code:
|
||||||
|
type: string
|
||||||
|
args_digest:
|
||||||
|
type: string
|
||||||
|
result_digest:
|
||||||
|
type: string
|
||||||
|
|
||||||
|
MessageReportRequest:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- session_id
|
||||||
|
- messages
|
||||||
|
properties:
|
||||||
|
session_id:
|
||||||
|
type: string
|
||||||
|
messages:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/ReportedMessage'
|
||||||
|
|
||||||
|
ReportedMessage:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- role
|
||||||
|
- content
|
||||||
|
- source
|
||||||
|
- timestamp
|
||||||
|
properties:
|
||||||
|
role:
|
||||||
|
type: string
|
||||||
|
enum: [user, assistant, human, system]
|
||||||
|
content:
|
||||||
|
type: string
|
||||||
|
source:
|
||||||
|
type: string
|
||||||
|
enum: [bot, human, channel]
|
||||||
|
timestamp:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
segment_id:
|
||||||
|
type: string
|
||||||
|
|
||||||
|
SwitchModeRequest:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- mode
|
||||||
|
properties:
|
||||||
|
mode:
|
||||||
|
type: string
|
||||||
|
enum: [BOT_ACTIVE, HUMAN_ACTIVE]
|
||||||
|
reason:
|
||||||
|
type: string
|
||||||
|
|
||||||
|
SwitchModeResponse:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- session_id
|
||||||
|
- mode
|
||||||
|
properties:
|
||||||
|
session_id:
|
||||||
|
type: string
|
||||||
|
mode:
|
||||||
|
type: string
|
||||||
|
enum: [BOT_ACTIVE, HUMAN_ACTIVE]
|
||||||
|
|
@ -0,0 +1,107 @@
|
||||||
|
---
|
||||||
|
feature_id: "IDMP"
|
||||||
|
title: "意图驱动智能体中台改造（仅中台侧）需求规范"
|
||||||
|
status: "draft"
|
||||||
|
version: "0.3.0"
|
||||||
|
active_version: "0.2.0-0.3.0"
|
||||||
|
version_history:
|
||||||
|
- version: "0.3.0"
|
||||||
|
ac_range: "AC-IDMP-19~20"
|
||||||
|
description: "MCP/Tool Registry治理与高风险场景最小集显式化"
|
||||||
|
- version: "0.2.0"
|
||||||
|
ac_range: "AC-IDMP-11~18"
|
||||||
|
description: "ReAct约束、记忆分层、工具治理与灰度回滚补充"
|
||||||
|
- version: "0.1.0"
|
||||||
|
ac_range: "AC-IDMP-01~10"
|
||||||
|
description: "中台协议统一与智能编排首版"
|
||||||
|
owners:
|
||||||
|
- "product"
|
||||||
|
- "backend"
|
||||||
|
last_updated: "2026-03-03"
|
||||||
|
source:
|
||||||
|
type: "conversation"
|
||||||
|
ref: "仅中台侧改造文档生成"
|
||||||
|
---
|
||||||
|
|
||||||
|
# 意图驱动智能体中台改造（仅中台侧）（IDMP）
|
||||||
|
|
||||||
|
## 1. 背景与目标
|
||||||
|
|
||||||
|
- 背景：当前中台能力与渠道协同语义不统一，打断重入、模式归因、护栏接管等关键路径缺少标准化契约。
|
||||||
|
- 目标：建立中台统一响应协议、决策编排与治理框架，在不改动渠道实现细节的前提下提升稳定性与可观测性。
|
||||||
|
- 非目标：不覆盖渠道发送实现、不覆盖管理端页面改造、不覆盖模型替换。
|
||||||
|
|
||||||
|
## 2. 模块边界（Scope）
|
||||||
|
|
||||||
|
- 覆盖：中台会话响应、模式切换、消息上报、元数据检索、工具编排与记忆服务调用。
|
||||||
|
- 不覆盖：渠道端 SegmentDispatcher/InterruptManager/DeliveredHistoryStore 具体实现。
|
||||||
|
|
||||||
|
## 3. 依赖盘点（Dependencies）
|
||||||
|
|
||||||
|
- 渠道侧服务（请求入口与响应消费）
|
||||||
|
- 元数据服务（KB/Intent/Flow/Prompt）
|
||||||
|
- 记忆服务（recall/update）
|
||||||
|
|
||||||
|
## 4. 用户故事（User Stories）
|
||||||
|
|
||||||
|
- [US-IDMP-01] 作为渠道调用方，我希望中台返回统一 `segments[] + trace`，以便稳定消费并做打断重入。
|
||||||
|
- [US-IDMP-02] 作为平台治理方，我希望中台能基于策略选择 agent/micro_flow/fixed/transfer，以便平衡效果与合规。
|
||||||
|
- [US-IDMP-03] 作为运维方，我希望关键链路有完整可观测字段和指标，以便快速归因与回滚。
|
||||||
|
- [US-IDMP-04] 作为产品方，我希望高风险场景被微流程强接管，以避免不受控回复。
|
||||||
|
- [US-IDMP-05] 作为架构方，我希望 Agent 运行有明确循环与超时上限，以避免时延失控。
|
||||||
|
- [US-IDMP-06] 作为平台方，我希望记忆能力分层可管控，以提升连续会话质量。
|
||||||
|
- [US-IDMP-07] 作为平台治理方，我希望 MCP/Tool Registry 被纳入统一注册与策略治理，以便工具扩展可控。
|
||||||
|
- [US-IDMP-08] 作为业务方，我希望高风险场景最小集有明确口径，以便实施和验收一致。
|
||||||
|
|
||||||
|
## 5. 验收标准（Acceptance Criteria, EARS）
|
||||||
|
|
||||||
|
### v0.1.0
|
||||||
|
- [AC-IDMP-01] WHEN 渠道调用会话响应接口 THEN 中台 SHALL 返回 `segments[]`，每个分段包含 `segment_id/text/delay_after`。
|
||||||
|
- [AC-IDMP-02] WHEN 中台返回会话响应 THEN 中台 SHALL 同时返回 `trace.mode`，且其值属于 `agent|micro_flow|fixed|transfer`。
|
||||||
|
- [AC-IDMP-03] WHEN 请求包含已送达历史 THEN 中台 SHALL 仅基于已送达历史进行上下文推理，不依赖未送达内容。
|
||||||
|
- [AC-IDMP-04] WHEN 会话处于发送中发生用户新输入 THEN 中台 SHALL 支持打断重入并以最新请求代际结果为准。
|
||||||
|
- [AC-IDMP-05] WHEN 进入退款/投诉/隐私承诺/转人工等高风险场景 THEN 中台 SHALL 强制切换到 `micro_flow` 或 `transfer`。
|
||||||
|
- [AC-IDMP-06] WHEN Agent 工具调用超时或失败 THEN 中台 SHALL 按策略降级到 `fixed` 或 `transfer` 并给出 `fallback_reason_code`。
|
||||||
|
- [AC-IDMP-07] WHEN 中台执行一次响应 THEN 中台 SHALL 记录 `session_id/request_id/generation_id/mode/intent/tool_calls/guardrail_triggered` 等审计字段。
|
||||||
|
- [AC-IDMP-08] WHEN 渠道上报人工或机器人消息 THEN 中台 SHALL 接收并落库，保证会话闭环数据完整。
|
||||||
|
- [AC-IDMP-09] WHEN 渠道发起会话模式切换 THEN 中台 SHALL 更新会话模式状态并影响后续编排路径。
|
||||||
|
- [AC-IDMP-10] WHEN 执行元数据检索 THEN 中台 SHALL 执行 `intent -> target_kbs -> metadata_filter -> vector_search -> rerank` 固定链路。
|
||||||
|
|
||||||
|
### v0.2.0
|
||||||
|
- [AC-IDMP-11] WHEN Agent 进入 ReAct 推理 THEN 中台 SHALL 限制循环次数在 3~5 次内，超限必须触发降级。
|
||||||
|
- [AC-IDMP-12] WHEN 发生工具调用 THEN 中台 SHALL 约束单工具超时 ≤2s 且全链路超时 ≤8s。
|
||||||
|
- [AC-IDMP-13] WHEN 进行记忆读取 THEN 中台 SHALL 在响应前执行 recall 并注入基础属性、事实记忆与偏好记忆。
|
||||||
|
- [AC-IDMP-14] WHEN 一轮会话完成 THEN 中台 SHALL 异步执行记忆更新（含会话摘要），且不阻塞主响应。
|
||||||
|
- [AC-IDMP-15] WHEN 中台调用工具 THEN 中台 SHALL 以结构化 `tool_call/tool_result` 记录参数摘要、耗时、结果与错误码。
|
||||||
|
- [AC-IDMP-16] WHEN 意图置信度低或关键信息缺失 THEN 中台 SHALL 回退到 `micro_flow` 或 `fixed`，不得继续自由 Agent 输出。
|
||||||
|
- [AC-IDMP-17] WHEN 系统进入灰度发布 THEN 中台 SHALL 支持按会话级开关启停 Agent 链路并支持回滚到传统链路。
|
||||||
|
- [AC-IDMP-18] WHEN 采集运行指标 THEN 中台 SHALL 提供任务达成率、槽位完整率、误转人工率、无召回率、平均时延等指标。
|
||||||
|
|
||||||
|
### v0.3.0
|
||||||
|
- [AC-IDMP-19] WHEN 新增或调用工具能力（含 MCP 工具） THEN 中台 SHALL 通过统一 Tool Registry 完成注册、鉴权、超时策略、版本与启停治理，并将治理结果写入 trace/tool 日志。
|
||||||
|
- [AC-IDMP-20] WHEN 判定高风险场景接管范围 THEN 中台 SHALL 以“退款/投诉升级/隐私与敏感承诺/转人工”作为最小强接管场景集，且该集合可配置但不得缺省为空。
|
||||||
|
|
||||||
|
## 6. 追踪映射（Traceability）
|
||||||
|
|
||||||
|
| AC ID | Endpoint | 方法 | operationId | 备注 |
|
||||||
|
|------|----------|------|-------------|------|
|
||||||
|
| AC-IDMP-01 | /mid/dialogue/respond | POST | respondDialogue | 分段协议 |
|
||||||
|
| AC-IDMP-02 | /mid/dialogue/respond | POST | respondDialogue | trace 模式 |
|
||||||
|
| AC-IDMP-03 | /mid/dialogue/respond | POST | respondDialogue | 已送达历史 |
|
||||||
|
| AC-IDMP-04 | /mid/dialogue/respond | POST | respondDialogue | 打断重入/代际 |
|
||||||
|
| AC-IDMP-05 | /mid/dialogue/respond | POST | respondDialogue | 高风险接管 |
|
||||||
|
| AC-IDMP-06 | /mid/dialogue/respond | POST | respondDialogue | 降级策略 |
|
||||||
|
| AC-IDMP-07 | /mid/dialogue/respond | POST | respondDialogue | 审计观测 |
|
||||||
|
| AC-IDMP-08 | /mid/messages/report | POST | reportMessages | 全量上报 |
|
||||||
|
| AC-IDMP-09 | /mid/sessions/{sessionId}/mode | POST | switchSessionMode | 模式切换 |
|
||||||
|
| AC-IDMP-10 | /deps/metadata/query | POST | queryMetadata | 元数据链路 |
|
||||||
|
| AC-IDMP-11 | /mid/dialogue/respond | POST | respondDialogue | ReAct 循环上限 |
|
||||||
|
| AC-IDMP-12 | /mid/dialogue/respond | POST | respondDialogue | 超时治理 |
|
||||||
|
| AC-IDMP-13 | /deps/memory/recall | POST | recallMemory | 记忆读取 |
|
||||||
|
| AC-IDMP-14 | /deps/memory/update | POST | updateMemory | 异步记忆更新 |
|
||||||
|
| AC-IDMP-15 | /mid/dialogue/respond | POST | respondDialogue | 工具调用结构化记录 |
|
||||||
|
| AC-IDMP-16 | /mid/dialogue/respond | POST | respondDialogue | 低置信度回退 |
|
||||||
|
| AC-IDMP-17 | /mid/dialogue/respond | POST | respondDialogue | 灰度与回滚 |
|
||||||
|
| AC-IDMP-18 | /mid/dialogue/respond | POST | respondDialogue | 运行指标输出 |
|
||||||
|
| AC-IDMP-19 | /mid/dialogue/respond | POST | respondDialogue | MCP/Tool Registry 治理 |
|
||||||
|
| AC-IDMP-20 | /mid/dialogue/respond | POST | respondDialogue | 高风险最小场景集 |
|
||||||
|
|
@ -0,0 +1,47 @@
|
||||||
|
# 意图驱动智能体中台改造 - 功能定界（仅中台侧）
|
||||||
|
|
||||||
|
## 1. 模块边界（Module Scope）
|
||||||
|
|
||||||
|
### 1.1 覆盖范围（In Scope）
|
||||||
|
- 中台会话编排：`policy_router` 决策 `agent | micro_flow | fixed | transfer`
|
||||||
|
- 中台输出协议：统一返回 `segments[] + trace`
|
||||||
|
- 中台工具编排：KB/Intent/Flow/Prompt/Memory 工具调用治理
|
||||||
|
- 中台记忆融合：会话前 recall、会话后异步更新
|
||||||
|
- 中台高风险微流程：退款/投诉/隐私承诺/转人工
|
||||||
|
- 中台可观测性：模式、工具调用、降级原因、护栏触发、请求代际
|
||||||
|
|
||||||
|
### 1.2 不覆盖范围（Out of Scope）
|
||||||
|
- 渠道侧消息分段发送实现（队列、延迟、重试）
|
||||||
|
- 渠道侧中断管理实现（取消令牌、本地缓存）
|
||||||
|
- 前端/管理端页面改造
|
||||||
|
- 模型供应商切换与底层推理框架替换
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 依赖盘点（Dependencies）
|
||||||
|
|
||||||
|
- 渠道侧（Java）
|
||||||
|
- 提供：用户消息、已送达历史、可选中断片段
|
||||||
|
- 消费：中台返回 `segments[] + trace`
|
||||||
|
- 元数据与知识库服务
|
||||||
|
- 提供：KB 文档、intent 规则、flow 模板、prompt 模板
|
||||||
|
- 记忆服务
|
||||||
|
- 提供：用户长期记忆 recall / update 能力
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 依赖接口清单（Dependency Contracts）
|
||||||
|
|
||||||
|
1. `POST /mid/dialogue/respond`（中台对渠道）
|
||||||
|
2. `POST /mid/sessions/{sessionId}/mode`（会话模式切换）
|
||||||
|
3. `POST /mid/messages/report`（全量消息上报）
|
||||||
|
4. `POST /deps/metadata/query`（中台调用元数据服务）
|
||||||
|
5. `POST /deps/memory/recall`、`POST /deps/memory/update`（中台调用记忆服务）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 阶段目标
|
||||||
|
|
||||||
|
- Phase 1：协议统一与主链路可用
|
||||||
|
- Phase 2：高风险护栏与记忆增强
|
||||||
|
- Phase 3：稳定性治理与灰度回滚
|
||||||
|
|
@ -0,0 +1,117 @@
|
||||||
|
# 意图驱动智能体中台改造（IDMP）- 任务清单
|
||||||
|
|
||||||
|
## 活跃版本：v0.2.0-0.3.0
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 1: 记忆服务增强（AC-IDMP-13/14）
|
||||||
|
|
||||||
|
### Task-1.1: 记忆召回服务（AC-IDMP-13）⏳
|
||||||
|
**验收标准**: WHEN 进行记忆读取 THEN 中台 SHALL 在响应前执行 recall 并注入基础属性、事实记忆与偏好记忆
|
||||||
|
|
||||||
|
**子任务**:
|
||||||
|
- [ ] 1.1.1 创建 `services/mid/memory_adapter.py` - 记忆适配器
|
||||||
|
- [ ] 1.1.2 实现 `RecallRequest` / `RecallResponse` 数据模型
|
||||||
|
- [ ] 1.1.3 实现 `recall(user_id, session_id)` 方法，返回 profile/facts/preferences
|
||||||
|
- [ ] 1.1.4 集成到对话响应流程（响应前调用）
|
||||||
|
- [ ] 1.1.5 实现 recall 失败降级（不阻断主链路）
|
||||||
|
|
||||||
|
**参考**:
|
||||||
|
- `openapi.deps.yaml` - `/deps/memory/recall`
|
||||||
|
- `services/memory.py` - 现有 MemoryService
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Task-1.2: 记忆更新服务（AC-IDMP-14）⏳
|
||||||
|
**验收标准**: WHEN 一轮会话完成 THEN 中台 SHALL 异步执行记忆更新（含会话摘要），且不阻塞主响应
|
||||||
|
|
||||||
|
**子任务**:
|
||||||
|
- [ ] 1.2.1 实现 `update(user_id, session_id, messages, summary)` 方法
|
||||||
|
- [ ] 1.2.2 创建异步任务队列（使用 asyncio.create_task）
|
||||||
|
- [ ] 1.2.3 实现会话摘要生成（可选，由中台异步生成后回写）
|
||||||
|
- [ ] 1.2.4 集成到对话响应流程（响应后异步调用）
|
||||||
|
- [ ] 1.2.5 添加错误处理与重试机制
|
||||||
|
|
||||||
|
**参考**:
|
||||||
|
- `openapi.deps.yaml` - `/deps/memory/update`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 2: 工具调用治理（AC-IDMP-15/19）
|
||||||
|
|
||||||
|
### Task-2.1: 工具调用结构化记录（AC-IDMP-15）⏳
|
||||||
|
**验收标准**: WHEN 中台调用工具 THEN 中台 SHALL 以结构化 `tool_call/tool_result` 记录参数摘要、耗时、结果与错误码
|
||||||
|
|
||||||
|
**子任务**:
|
||||||
|
- [ ] 2.1.1 创建 `models/mid/tool_trace.py` - ToolCallTrace 数据模型
|
||||||
|
- [ ] 2.1.2 实现 `ToolCallRecorder` 服务
|
||||||
|
- [ ] 2.1.3 记录字段：tool_name, tool_type, registry_version, auth_applied, duration_ms, status, error_code, args_digest, result_digest
|
||||||
|
- [ ] 2.1.4 集成到 TraceInfo 输出
|
||||||
|
- [ ] 2.1.5 实现敏感参数脱敏（args_digest）
|
||||||
|
|
||||||
|
**参考**:
|
||||||
|
- `openapi.provider.yaml` - `ToolCallTrace` schema
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Task-2.2: Tool Registry 治理（AC-IDMP-19）⏳
|
||||||
|
**验收标准**: WHEN 新增或调用工具能力（含 MCP 工具） THEN 中台 SHALL 通过统一 Tool Registry 完成注册、鉴权、超时策略、版本与启停治理，并将治理结果写入 trace/tool 日志
|
||||||
|
|
||||||
|
**子任务**:
|
||||||
|
- [ ] 2.2.1 创建 `services/mid/tool_registry.py` - 工具注册表
|
||||||
|
- [ ] 2.2.2 实现 `ToolDefinition` 数据模型（name, type, version, timeout_ms, auth_required, is_enabled）
|
||||||
|
- [ ] 2.2.3 实现 `register_tool()` - 工具注册
|
||||||
|
- [ ] 2.2.4 实现 `authorize_tool()` - 工具鉴权
|
||||||
|
- [ ] 2.2.5 实现 `get_timeout_policy()` - 超时策略获取
|
||||||
|
- [ ] 2.2.6 实现 `is_tool_enabled()` - 启停状态检查
|
||||||
|
- [ ] 2.2.7 创建数据库表 `tool_registry`（可选，支持动态配置）
|
||||||
|
- [ ] 2.2.8 集成 MCP 工具支持
|
||||||
|
|
||||||
|
**参考**:
|
||||||
|
- `openapi.provider.yaml` - `TraceInfo.tools_used`, `ToolCallTrace`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 3: 测试与验证
|
||||||
|
|
||||||
|
### Task-3.1: 单元测试 ⏳
|
||||||
|
**覆盖路径**:
|
||||||
|
- [ ] 成功路径：正常 recall/update，工具调用成功
|
||||||
|
- [ ] 超时路径：recall 超时降级，工具调用超时
|
||||||
|
- [ ] 错误路径：recall 失败降级，工具调用错误
|
||||||
|
- [ ] 降级路径：记忆服务不可用时继续主链路
|
||||||
|
|
||||||
|
**测试文件**:
|
||||||
|
- `tests/test_memory_adapter.py`
|
||||||
|
- `tests/test_tool_registry.py`
|
||||||
|
- `tests/test_tool_call_recorder.py`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 依赖关系
|
||||||
|
|
||||||
|
```
|
||||||
|
Task-1.1 (recall) ──┐
|
||||||
|
├──> Task-1.2 (update) ──> Task-3.1 (tests)
|
||||||
|
Task-2.1 (trace) ───┘
|
||||||
|
│
|
||||||
|
└──> Task-2.2 (registry) ──> Task-3.1 (tests)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 变更文件清单
|
||||||
|
|
||||||
|
| 文件路径 | 状态 | 关联 AC |
|
||||||
|
|---------|------|---------|
|
||||||
|
| `services/mid/__init__.py` | 待创建 | - |
|
||||||
|
| `services/mid/memory_adapter.py` | 待创建 | AC-IDMP-13/14 |
|
||||||
|
| `services/mid/tool_registry.py` | 待创建 | AC-IDMP-19 |
|
||||||
|
| `services/mid/tool_call_recorder.py` | 待创建 | AC-IDMP-15 |
|
||||||
|
| `models/mid/__init__.py` | 待创建 | - |
|
||||||
|
| `models/mid/memory.py` | 待创建 | AC-IDMP-13/14 |
|
||||||
|
| `models/mid/tool_trace.py` | 待创建 | AC-IDMP-15 |
|
||||||
|
| `models/mid/tool_registry.py` | 待创建 | AC-IDMP-19 |
|
||||||
|
| `tests/test_memory_adapter.py` | 待创建 | AC-IDMP-13/14 |
|
||||||
|
| `tests/test_tool_registry.py` | 待创建 | AC-IDMP-19 |
|
||||||
|
| `tests/test_tool_call_recorder.py` | 待创建 | AC-IDMP-15 |
|
||||||
|
|
@ -0,0 +1,202 @@
|
||||||
|
# 元数据 + 意图识别 + 话术流程关联操作文档
|
||||||
|
|
||||||
|
## 1. 目标
|
||||||
|
|
||||||
|
本文用于指导运营/配置人员在管理界面完成以下闭环：
|
||||||
|
1. 配置元数据字段
|
||||||
|
2. 录入知识库文档并标注元数据
|
||||||
|
3. 配置意图规则（触发路由）
|
||||||
|
4. 配置话术流程（多轮推进）
|
||||||
|
5. 打通“意图 -> 检索/流程 -> 话术生成”
|
||||||
|
|
||||||
|
适用对象：产品、运营、实施、测试。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 概念关系（先理解）
|
||||||
|
|
||||||
|
- **元数据（Metadata）**：用于“筛选与路由”的标签，如 `grade`、`subject`、`scene`。
|
||||||
|
- **意图规则（Intent Rule）**：用于判断“用户在说什么、系统该做什么”。
|
||||||
|
- **话术流程（Script Flow）**：用于处理“多轮引导”，例如收集年级 -> 收集薄弱点 -> 推荐课程。
|
||||||
|
|
||||||
|
**执行链路**：
|
||||||
|
|
||||||
|
用户消息 -> 意图匹配 ->
|
||||||
|
- 命中 `response_type=rag`：进入知识库检索（带 metadata filter）
|
||||||
|
- 命中 `response_type=flow`：进入话术流程
|
||||||
|
- 命中 `fixed/transfer`：直接固定回复或转人工
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 第一步：配置元数据字段
|
||||||
|
|
||||||
|
进入：`元数据配置` 页面 -> 新建字段。
|
||||||
|
|
||||||
|
建议首批字段（教育场景）：
|
||||||
|
- `grade`（枚举）：初一/初二/初三/all
|
||||||
|
- `subject`（枚举）：语文/数学/英语/物理/化学/综合/all
|
||||||
|
- `scene`（枚举）：pain_point/transition/module_intro/faq/policy/closing
|
||||||
|
- `flow_step`（枚举）：step1/step2/step3/step4/step5/none
|
||||||
|
- `intent_type`（枚举）：ask_grade/ask_weak_point/module_recommend/next_action/faq_answer/compliance
|
||||||
|
- `audience`（枚举）：parent/student/all
|
||||||
|
- `priority`（数字）：1-10
|
||||||
|
- `status`（枚举）：draft/active/deprecated
|
||||||
|
|
||||||
|
字段配置建议：
|
||||||
|
- `是否必填`：`grade/subject/scene/status` 建议必填
|
||||||
|
- `可过滤`：上述字段建议全部开启
|
||||||
|
- `排序特征`：仅 `priority` 建议开启
|
||||||
|
- `状态`：配置完成后由 `草稿 -> 激活`
|
||||||
|
|
||||||
|
注意：字段标识只用小写字母/数字/下划线，避免后续过滤失败。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 第二步：录入知识库文档并打元数据
|
||||||
|
|
||||||
|
进入：`知识库文档` 页面 -> 新增文档。
|
||||||
|
|
||||||
|
### 4.1 文档内容规范（你当前按行分块）
|
||||||
|
- 一行一个知识点
|
||||||
|
- 每行尽量只表达一个事实或一个建议
|
||||||
|
- 避免一行过长（建议 20~80 字）
|
||||||
|
|
||||||
|
### 4.2 元数据填写规范
|
||||||
|
示例（初一痛点文档）：
|
||||||
|
- `grade=初一`
|
||||||
|
- `subject=综合`
|
||||||
|
- `scene=pain_point`
|
||||||
|
- `flow_step=step2`
|
||||||
|
- `intent_type=ask_weak_point`
|
||||||
|
- `audience=parent`
|
||||||
|
- `status=active`
|
||||||
|
- `priority=8`
|
||||||
|
|
||||||
|
### 4.3 无年级、仅学科的数据怎么填
|
||||||
|
- `grade=all`
|
||||||
|
- `subject=语文/数学/...`
|
||||||
|
- 其余按场景填写
|
||||||
|
|
||||||
|
不建议因为“无年级”单独新建知识库，优先通过文档+metadata区分。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 第三步：配置意图规则（路由入口）
|
||||||
|
|
||||||
|
进入：`意图规则` 页面 -> 新建规则。
|
||||||
|
|
||||||
|
### 5.1 必填项
|
||||||
|
- 名称
|
||||||
|
- `keywords`（关键词）和/或 `patterns`（正则）
|
||||||
|
- `response_type`：fixed / rag / flow / transfer
|
||||||
|
- 优先级
|
||||||
|
|
||||||
|
### 5.2 推荐路由策略
|
||||||
|
- 课程咨询、薄弱点分析 -> `response_type=flow`
|
||||||
|
- 短问短答（价格、班型） -> `response_type=rag` 或 `fixed`
|
||||||
|
- 明确转人工 -> `response_type=transfer`
|
||||||
|
|
||||||
|
### 5.3 metadata 关联
|
||||||
|
在意图规则 metadata 中建议填写：
|
||||||
|
- `scene`
|
||||||
|
- `grade`（可选）
|
||||||
|
- `subject`（可选）
|
||||||
|
|
||||||
|
用于后续检索过滤增强。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. 第四步：配置话术流程（与意图绑定）
|
||||||
|
|
||||||
|
进入：`话术流程` 页面 -> 新建或编辑流程。
|
||||||
|
|
||||||
|
### 6.1 你当前推荐流程（示例）
|
||||||
|
- Step1：确认年级
|
||||||
|
- Step2：年级特点 + 过渡到薄弱点
|
||||||
|
- Step3：确认薄弱科目/能力点
|
||||||
|
- Step4：针对薄弱点介绍课程模块
|
||||||
|
- Step5：给出下一步建议
|
||||||
|
|
||||||
|
### 6.2 每步建议配置
|
||||||
|
- `script_mode = flexible`
|
||||||
|
- 配置 `intent` / `intent_description`
|
||||||
|
- 配置 `script_constraints`
|
||||||
|
- 配置 `fallback content`
|
||||||
|
- 配置 `expected_variables`（如 `grade`, `weak_points`）
|
||||||
|
|
||||||
|
### 6.3 与知识库关联方式
|
||||||
|
- 在流程步骤中通过 `rag_config.tag_filter` 或上下文变量注入过滤（如 `grade`, `subject`, `scene`）
|
||||||
|
- Step2 常用 `scene=pain_point`
|
||||||
|
- Step4 常用 `scene=module_intro`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. 第五步：关联关系配置清单（上线前检查）
|
||||||
|
|
||||||
|
### 7.1 意图 -> 流程
|
||||||
|
- 已有意图规则 `response_type=flow`
|
||||||
|
- `flow_id` 指向正确流程
|
||||||
|
|
||||||
|
### 7.2 意图/上下文 -> 检索
|
||||||
|
- 命中 `response_type=rag` 或流程步骤需要RAG时
|
||||||
|
- metadata filter 至少包含 `grade/subject/scene` 之一
|
||||||
|
|
||||||
|
### 7.3 文档 -> 检索命中
|
||||||
|
- 文档已 `status=active`
|
||||||
|
- 文档 metadata 与过滤字段一致（值完全一致）
|
||||||
|
- 文档内容按行分块且可检索
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. 验收用例（建议）
|
||||||
|
|
||||||
|
### 用例1：初一家长咨询
|
||||||
|
输入：`孩子刚上初一，成绩上不去怎么办？`
|
||||||
|
期望：
|
||||||
|
1. 命中课程咨询意图
|
||||||
|
2. 进入 flow（或rag+flow）
|
||||||
|
3. 检索优先命中 `grade=初一` 且 `scene=pain_point` 文档
|
||||||
|
|
||||||
|
### 用例2：仅学科问题
|
||||||
|
输入：`语文阅读理解总是丢分`
|
||||||
|
期望：
|
||||||
|
1. 命中学科提升相关意图
|
||||||
|
2. 检索命中 `subject=语文`、`grade=all` 或当前年级内容
|
||||||
|
|
||||||
|
### 用例3：无召回兜底
|
||||||
|
输入：冷门问题且无相关文档
|
||||||
|
期望：
|
||||||
|
1. 返回 fallback 话术
|
||||||
|
2. 记录无召回原因（便于补文档）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. 常见问题与处理
|
||||||
|
|
||||||
|
1. **有文档但检索不到**
|
||||||
|
- 检查 metadata 值是否一致（如“初一” vs “七年级”）
|
||||||
|
- 检查字段是否可过滤、状态是否 active
|
||||||
|
|
||||||
|
2. **命中不准，答非所问**
|
||||||
|
- 缩小意图规则关键词
|
||||||
|
- 增加 metadata 过滤条件
|
||||||
|
- 拆分长行文本为更原子知识点
|
||||||
|
|
||||||
|
3. **是否要新增知识库**
|
||||||
|
- 先不拆库，优先文档+metadata
|
||||||
|
- 仅当串库严重/权限隔离/规模过大再拆
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. 运营维护建议
|
||||||
|
|
||||||
|
- 每周复盘：
|
||||||
|
- 高频命中问题
|
||||||
|
- 无召回问题
|
||||||
|
- 错召回问题
|
||||||
|
- 按复盘结果更新：
|
||||||
|
- 意图规则关键词与优先级
|
||||||
|
- 文档内容与metadata
|
||||||
|
- 流程约束与fallback
|
||||||
|
|
||||||
|
目标：持续提高“命中率、相关性、可用率”。
|
||||||
|
|
@ -0,0 +1,200 @@
|
||||||
|
# AI客服智能体增强改造方案（渠道侧 / Java）
|
||||||
|
|
||||||
|
## 1. 改造定位
|
||||||
|
|
||||||
|
Java 渠道侧承担“用户体验与会话控制中枢”角色，核心职责：
|
||||||
|
- 分段消息发送（拟人化节奏）
|
||||||
|
- 打断处理（实时中断、无重复发送）
|
||||||
|
- 本地会话历史缓存（已送达真相）
|
||||||
|
- 全量消息异步上报（含人工阶段）
|
||||||
|
|
||||||
|
目标：让智能体能力在前端体验上可感知且可控。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 渠道侧总体设计
|
||||||
|
|
||||||
|
## 2.1 新增组件
|
||||||
|
1. `SegmentDispatcher`（消息调度器）
|
||||||
|
2. `InterruptManager`（打断管理器）
|
||||||
|
3. `DeliveredHistoryStore`（已送达历史存储）
|
||||||
|
4. `MessageReporter`（全量消息上报器）
|
||||||
|
5. `SessionModeManager`（机器人/人工状态管理）
|
||||||
|
|
||||||
|
## 2.2 会话状态机
|
||||||
|
- `BOT_ACTIVE`：机器人对话中
|
||||||
|
- `BOT_SENDING`：机器人分段发送中
|
||||||
|
- `INTERRUPTED`：发送被打断，等待新请求
|
||||||
|
- `HUMAN_ACTIVE`：人工接管
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 核心流程设计
|
||||||
|
|
||||||
|
## 3.1 正常流程（无打断）
|
||||||
|
1. 用户消息进入渠道侧
|
||||||
|
2. 组装请求（`session_id + user_message + delivered_history`）调用中台
|
||||||
|
3. 收到 `segments[]`
|
||||||
|
4. `SegmentDispatcher` 按 `delay_after` 顺序发送
|
||||||
|
5. 每发送成功一段，写入 `DeliveredHistoryStore`
|
||||||
|
6. 异步上报每条消息（用户/机器人）
|
||||||
|
|
||||||
|
## 3.2 打断流程
|
||||||
|
1. 发送中收到新用户消息
|
||||||
|
2. `InterruptManager` 立即取消未发送段
|
||||||
|
3. 仅保留“已送达段”作为历史
|
||||||
|
4. 发起新请求，附带 `interrupted_segments`（可选）
|
||||||
|
5. 中台重新决策后返回新 `segments[]`
|
||||||
|
|
||||||
|
## 3.3 转人工流程
|
||||||
|
1. 渠道侧调用中台状态接口标记 `HUMAN_ACTIVE`
|
||||||
|
2. 后续消息不再调用智能体
|
||||||
|
3. 用户与人工消息继续异步上报中台（保证闭环数据）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 关键模块说明
|
||||||
|
|
||||||
|
## 4.1 SegmentDispatcher
|
||||||
|
|
||||||
|
职责：
|
||||||
|
- 顺序发送片段
|
||||||
|
- 尊重 `delay_after`
|
||||||
|
- 支持取消令牌（中断）
|
||||||
|
|
||||||
|
建议实现点：
|
||||||
|
- 每个 session 单独队列
|
||||||
|
- 每段发送前检查会话是否仍为 `BOT_SENDING`
|
||||||
|
- 失败重试最多 1 次（避免重复刷屏）
|
||||||
|
|
||||||
|
## 4.2 InterruptManager
|
||||||
|
|
||||||
|
职责：
|
||||||
|
- 监听用户新消息事件
|
||||||
|
- 取消当前发送任务
|
||||||
|
- 记录中断点（最后已送达 segment_id）
|
||||||
|
|
||||||
|
建议规则：
|
||||||
|
- 中断优先级高于发送
|
||||||
|
- 丢弃未送达段，不做补发
|
||||||
|
|
||||||
|
## 4.3 DeliveredHistoryStore（Redis）
|
||||||
|
|
||||||
|
建议键：`chat:{sessionId}:delivered`
|
||||||
|
|
||||||
|
建议字段：
|
||||||
|
- role（user/assistant/human）
|
||||||
|
- content
|
||||||
|
- timestamp
|
||||||
|
- segment_id（assistant可选）
|
||||||
|
- source（bot/human）
|
||||||
|
|
||||||
|
只存“已送达”消息，避免上下文污染。
|
||||||
|
|
||||||
|
## 4.4 MessageReporter
|
||||||
|
|
||||||
|
职责：
|
||||||
|
- 异步上报全量消息到中台历史服务
|
||||||
|
- 支持重试与死信队列
|
||||||
|
|
||||||
|
必须上报：
|
||||||
|
- 用户消息
|
||||||
|
- 机器人每个已送达段
|
||||||
|
- 人工客服消息
|
||||||
|
- 模式切换事件（bot->human/human->bot）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 请求与响应协议建议
|
||||||
|
|
||||||
|
## 5.1 渠道 -> 中台请求
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"session_id": "sess_123",
|
||||||
|
"user_message": "孩子五年级，数学不好",
|
||||||
|
"history": [
|
||||||
|
{"role": "user", "content": "你好"},
|
||||||
|
{"role": "assistant", "content": "您好"}
|
||||||
|
],
|
||||||
|
"interrupted_segments": [
|
||||||
|
{"segment_id": "seg_2", "content": "稍等，我查一下"}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 5.2 中台 -> 渠道响应
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"segments": [
|
||||||
|
{"segment_id": "seg_3", "text": "好的，请问孩子具体是哪个知识点薄弱？", "delay_after": 800},
|
||||||
|
{"segment_id": "seg_4", "text": "比如分数应用题还是几何？", "delay_after": 0}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. 与中台协同的关键约束
|
||||||
|
|
||||||
|
1. 渠道侧只认 `segments[]`，不关心中台内部是 agent 还是 flow。
|
||||||
|
2. 必须使用“已送达历史”回传，不能用“计划发送历史”。
|
||||||
|
3. 打断后立即重发，不等待旧请求自然结束。
|
||||||
|
4. 人工模式下继续上报，保证中台记忆与分析完整。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. 可观测性指标（渠道侧）
|
||||||
|
|
||||||
|
建议上报指标：
|
||||||
|
- `segment_send_latency_ms`
|
||||||
|
- `segment_drop_count`（中断丢弃）
|
||||||
|
- `interrupt_count`
|
||||||
|
- `resend_request_count`
|
||||||
|
- `bot_to_human_switch_count`
|
||||||
|
- `history_report_success_rate`
|
||||||
|
|
||||||
|
日志关键字段：
|
||||||
|
- session_id
|
||||||
|
- request_id
|
||||||
|
- segment_id
|
||||||
|
- mode
|
||||||
|
- interrupted_at
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. 分阶段实施建议（渠道侧）
|
||||||
|
|
||||||
|
## Phase 1
|
||||||
|
- 实现分段发送 + 本地已送达历史
|
||||||
|
- 接入中台 `segments` 协议
|
||||||
|
|
||||||
|
## Phase 2
|
||||||
|
- 打断管理上线（实时取消 + 重新请求）
|
||||||
|
- 全量消息上报链路上线
|
||||||
|
|
||||||
|
## Phase 3
|
||||||
|
- 人工接管状态机完善
|
||||||
|
- 失败重试、幂等、死信治理完善
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. 风险与应对
|
||||||
|
|
||||||
|
1. 重复发送风险
|
||||||
|
- 通过 `segment_id + session_id` 做幂等去重
|
||||||
|
|
||||||
|
2. 中断竞态（旧包晚到）
|
||||||
|
- 用 `request_id` / `generation_id` 校验，只消费最新响应
|
||||||
|
|
||||||
|
3. 历史错乱
|
||||||
|
- 仅以“已送达消息”入历史，不以“待发送消息”入历史
|
||||||
|
|
||||||
|
4. 上报积压
|
||||||
|
- 异步队列 + 批量上报 + 失败重试
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. 最终建议（渠道侧）
|
||||||
|
|
||||||
|
- 渠道侧的首要目标不是“更聪明”，而是“更稳定 + 更像人 + 可打断”。
|
||||||
|
- 只要分段、打断、历史上报三件事做稳，中台 Agent 的价值会显著放大。
|
||||||
|
|
@ -0,0 +1,201 @@
|
||||||
|
# AI客服智能体增强改造方案（仅中台侧）
|
||||||
|
|
||||||
|
## 1. 改造定位
|
||||||
|
|
||||||
|
中台侧承担“智能决策与会话编排核心”角色，负责在不改变渠道发送机制的前提下，输出可被渠道稳定消费的分段回复与可观测信息。
|
||||||
|
|
||||||
|
本次文档范围**仅覆盖中台侧**，并以渠道侧协同接口为边界。
|
||||||
|
|
||||||
|
### 核心目标
|
||||||
|
- 统一中台对外响应为 `segments[]` 协议，支撑渠道侧分段发送与打断重入。
|
||||||
|
- 构建“Agent 主链路 + Micro-flow 护栏兜底”的双轨决策。
|
||||||
|
- 仅基于“已送达历史”做上下文推理，避免上下文污染。
|
||||||
|
- 完整沉淀可观测字段，支持回放、归因与灰度治理。
|
||||||
|
|
||||||
|
### 非目标（Out of Scope）
|
||||||
|
- 不定义渠道侧发送节奏实现细节（队列、重试、UI 展现）。
|
||||||
|
- 不新增渠道侧状态机实现要求（仅声明协同接口语义）。
|
||||||
|
- 不扩展 Python 代码级任务与语言实现细节。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 中台侧能力边界
|
||||||
|
|
||||||
|
## 2.1 中台负责
|
||||||
|
1. 接收会话请求并执行策略路由（agent / micro_flow / fixed / transfer）。
|
||||||
|
2. 组织工具调用（KB/Intent/Flow/Prompt/Memory）并生成结果。
|
||||||
|
3. 返回分段回复 `segments[]` 与追踪信息 `trace`。
|
||||||
|
4. 接收并落库全量消息上报（含人工阶段消息与模式切换事件）。
|
||||||
|
5. 提供会话模式状态接口（机器人/人工）。
|
||||||
|
|
||||||
|
## 2.2 中台不负责
|
||||||
|
1. 渠道消息发送调度与本地打断取消逻辑。
|
||||||
|
2. 渠道本地“已送达历史”缓存实现。
|
||||||
|
3. 渠道端展示层节奏控制。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 协同契约（与渠道侧）
|
||||||
|
|
||||||
|
## 3.1 请求协议（渠道 -> 中台）
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"session_id": "sess_123",
|
||||||
|
"user_message": "孩子五年级，数学不好",
|
||||||
|
"history": [
|
||||||
|
{"role": "user", "content": "你好"},
|
||||||
|
{"role": "assistant", "content": "您好"}
|
||||||
|
],
|
||||||
|
"interrupted_segments": [
|
||||||
|
{"segment_id": "seg_2", "content": "稍等，我查一下"}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
约束：
|
||||||
|
- `history` 必须是**已送达历史**，不得包含未送达片段。
|
||||||
|
- `interrupted_segments` 为可选协同信息，中台可用于上下文修正与日志归因。
|
||||||
|
|
||||||
|
## 3.2 响应协议（中台 -> 渠道）
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"segments": [
|
||||||
|
{"segment_id": "seg_3", "text": "好的，请问孩子具体是哪个知识点薄弱？", "delay_after": 800},
|
||||||
|
{"segment_id": "seg_4", "text": "比如分数应用题还是几何？", "delay_after": 0}
|
||||||
|
],
|
||||||
|
"trace": {
|
||||||
|
"mode": "agent",
|
||||||
|
"intent": "course_consult",
|
||||||
|
"tools_used": ["get_knowledge_bases", "recall_memory"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
约束：
|
||||||
|
- 中台必须保证 `segments[]` 可直接消费，不依赖渠道二次改写。
|
||||||
|
- `trace.mode` 必须返回，便于渠道侧与观测平台统一归因。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 中台核心架构
|
||||||
|
|
||||||
|
## 4.1 决策总线
|
||||||
|
- `policy_router`：根据意图、风险级别、置信度决定执行模式：
|
||||||
|
- `agent`（默认）
|
||||||
|
- `micro_flow`（高风险/强SOP）
|
||||||
|
- `fixed`（固定答复）
|
||||||
|
- `transfer`（转人工）
|
||||||
|
|
||||||
|
## 4.2 Agent 执行层
|
||||||
|
- `Agent Orchestrator` 执行 ReAct 循环（思考-行动-观察）。
|
||||||
|
- 通过 `Tool Registry` 调用工具（含 MCP 扩展能力）。
|
||||||
|
- 输出统一分段结构，受输出护栏二次校验。
|
||||||
|
|
||||||
|
## 4.3 微流程护栏层
|
||||||
|
仅保留高风险场景的最小流程集：
|
||||||
|
- 退款/退费
|
||||||
|
- 投诉升级
|
||||||
|
- 隐私与敏感承诺
|
||||||
|
- 转人工
|
||||||
|
|
||||||
|
## 4.4 记忆与元数据层
|
||||||
|
- 记忆读取：按 `user_id/session_id` 注入长期与短期上下文。
|
||||||
|
- 元数据检索：严格执行 `intent -> target_kbs -> metadata_filter -> vector_search -> rerank`。
|
||||||
|
- 标签规范遵循既有方法论（grade/subject/scene/flow_step/intent_type 等）。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 中台执行时序
|
||||||
|
|
||||||
|
## 5.1 正常对话
|
||||||
|
1. 接收渠道请求（含已送达历史）。
|
||||||
|
2. `policy_router` 决策模式。
|
||||||
|
3. 进入 `agent` 或 `micro_flow`。
|
||||||
|
4. 工具调用 + 护栏校验。
|
||||||
|
5. 返回 `segments[] + trace`。
|
||||||
|
6. 异步写入会话日志与观测事件。
|
||||||
|
|
||||||
|
## 5.2 打断重入
|
||||||
|
1. 渠道发送中断后发起新请求。
|
||||||
|
2. 中台接收新的 `history` 与可选 `interrupted_segments`。
|
||||||
|
3. 丢弃旧 generation 的输出影响，仅以最新请求生成结果。
|
||||||
|
4. 返回新的 `segments[]`，保证语义连续。
|
||||||
|
|
||||||
|
## 5.3 人工接管
|
||||||
|
1. 渠道触发模式切换接口，标记 `HUMAN_ACTIVE`。
|
||||||
|
2. 中台停用机器人主链路输出。
|
||||||
|
3. 持续接收并记录人工消息上报。
|
||||||
|
4. 必要时支持 `HUMAN_ACTIVE -> BOT_ACTIVE` 回切。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. 关键治理与门禁
|
||||||
|
|
||||||
|
## 6.1 质量门禁
|
||||||
|
- 输出必须可分段消费（结构合法、字段完整）。
|
||||||
|
- 高风险场景必须命中 micro-flow，不允许 agent 直出。
|
||||||
|
- 低置信度或工具异常必须降级（fixed 或 transfer）。
|
||||||
|
|
||||||
|
## 6.2 可观测性字段（必须）
|
||||||
|
- `mode`
|
||||||
|
- `intent_id/intent`
|
||||||
|
- `target_kbs`
|
||||||
|
- `applied_metadata_filters`
|
||||||
|
- `tool_calls`（参数摘要、耗时、状态）
|
||||||
|
- `fallback_reason_code`
|
||||||
|
- `guardrail_triggered`
|
||||||
|
- `session_id/request_id/generation_id`
|
||||||
|
|
||||||
|
## 6.3 关键指标（建议）
|
||||||
|
- 响应时延 P50/P95
|
||||||
|
- 工具超时率
|
||||||
|
- fallback 触发率
|
||||||
|
- micro-flow 接管率
|
||||||
|
- 误转人工率
|
||||||
|
- 无召回率
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. 分阶段落地（仅中台）
|
||||||
|
|
||||||
|
## Phase 1：协议与主链路打通
|
||||||
|
- 固化 `segments[]` 对外响应协议。
|
||||||
|
- 打通 `policy_router + Agent Orchestrator` 最小闭环。
|
||||||
|
- 上线基础观测字段。
|
||||||
|
|
||||||
|
## Phase 2：护栏与记忆增强
|
||||||
|
- 上线高风险 micro-flow 最小集。
|
||||||
|
- 接入记忆读写与 metadata 过滤检索全链路。
|
||||||
|
- 完善降级与回退策略。
|
||||||
|
|
||||||
|
## Phase 3：稳定性与治理
|
||||||
|
- 完善 generation 级并发与乱序治理。
|
||||||
|
- 强化工具治理（超时、重试、熔断、错误映射）。
|
||||||
|
- 建立灰度策略与回滚开关。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. 主要风险与应对
|
||||||
|
|
||||||
|
1. 打断竞态导致旧响应污染
|
||||||
|
- 应对：按 `generation_id/request_id` 只认最新请求结果。
|
||||||
|
|
||||||
|
2. 工具调用抖动影响时延
|
||||||
|
- 应对：工具超时上限 + 快速降级 + 结果摘要缓存（可选）。
|
||||||
|
|
||||||
|
3. 元数据质量不一致导致召回偏差
|
||||||
|
- 应对：统一 metadata 枚举、入库校验、周期巡检。
|
||||||
|
|
||||||
|
4. 智能体自由度过高引发合规风险
|
||||||
|
- 应对：policy_router 前置约束 + 输出护栏 + micro-flow 强接管。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. 最终结论
|
||||||
|
|
||||||
|
本方案坚持“仅中台侧改造”：
|
||||||
|
- 以统一分段协议承接渠道可打断发送能力。
|
||||||
|
- 以 Agent 主链路提升效果，以 Micro-flow 护栏保证可控。
|
||||||
|
- 以观测与治理机制保障可回放、可归因、可灰度演进。
|
||||||
|
|
||||||
|
在不扩展渠道实现细节与不引入语言实现绑定的前提下，可支撑中台能力平滑升级。
|
||||||
|
|
@ -0,0 +1,137 @@
|
||||||
|
# 客户资料分类 TODO
|
||||||
|
|
||||||
|
> 目的：沉淀“客户提供的文字资料”并拆解为可录入中台的结构化项。
|
||||||
|
> 状态：进行中
|
||||||
|
|
||||||
|
## 分类维度（固定）
|
||||||
|
|
||||||
|
1. 数据库录入项（结构化事实）
|
||||||
|
- 企业/品牌信息
|
||||||
|
- 产品与服务目录
|
||||||
|
- 业务规则（价格、时效、区域、限制）
|
||||||
|
- 售后/退款/改期政策
|
||||||
|
- 联系方式与升级路径
|
||||||
|
|
||||||
|
2. 流程编排项（Flow / Script）
|
||||||
|
- 意图入口
|
||||||
|
- 主流程节点
|
||||||
|
- 异常分支
|
||||||
|
- 打断恢复策略
|
||||||
|
- 降级与转人工
|
||||||
|
|
||||||
|
3. 元数据配置项（Metadata）
|
||||||
|
- 租户配置
|
||||||
|
- 检索配置
|
||||||
|
- 超时配置
|
||||||
|
- 分段与 delay 配置
|
||||||
|
- 观测与审计字段
|
||||||
|
|
||||||
|
4. 提示词约束项（Prompt Guardrails）
|
||||||
|
- 角色与边界
|
||||||
|
- 合规/禁答策略
|
||||||
|
- 回复风格
|
||||||
|
- 事实优先级
|
||||||
|
- 工具调用策略
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 待处理清单
|
||||||
|
|
||||||
|
- [x] TODO-001：首批销售转化话术资料（已完成分类）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 处理记录
|
||||||
|
|
||||||
|
### TODO-001
|
||||||
|
- 原始资料：
|
||||||
|
- 主题包含：用户分层、下危机铺垫、课程效果外化、上直播、加微与辅导老师价值说明。
|
||||||
|
- 输入特征：左侧为“问题/场景”，右侧为“思路及参考话术”。
|
||||||
|
|
||||||
|
- 分类结果：
|
||||||
|
- 数据库录入项：
|
||||||
|
- 产品信息：
|
||||||
|
- 课程名称（暂命名）：方法技巧提升课
|
||||||
|
- 课程节数：10节
|
||||||
|
- 授课形式：线上直播
|
||||||
|
- 上课时间：周末
|
||||||
|
- 回放机制：有回放，可反复观看
|
||||||
|
- 教学配置：辅导老师 1对1 学情分析与答疑
|
||||||
|
- 主讲卖点：清北老师主讲（需合规校验后再对外展示）
|
||||||
|
- 覆盖题型：阅读、计算、证明题、完形填空等
|
||||||
|
- 价格与营销规则：
|
||||||
|
- 原价：299元
|
||||||
|
- 活动价：19元
|
||||||
|
- 活动标签：限时优惠
|
||||||
|
- 收费口径：无二次收费
|
||||||
|
- 用户分层维度（建议入库为标签/槽位）：
|
||||||
|
- 年级（必填）
|
||||||
|
- 薄弱科目/薄弱能力（如基础不扎实、举一反三弱）
|
||||||
|
- 最近考试表现（可选）
|
||||||
|
- 转化动作记录字段：
|
||||||
|
- 是否建议上直播
|
||||||
|
- 是否引导加微
|
||||||
|
- 是否已添加班主任/辅导老师
|
||||||
|
- 用户对价格接受度（accept_price: yes/no/hesitate）
|
||||||
|
|
||||||
|
- 流程编排项：
|
||||||
|
- 主流程（建议）：
|
||||||
|
1) 用户分层：先确认年级
|
||||||
|
2) 画像共情：结合最近考试与薄弱点做问题诊断
|
||||||
|
3) 方案匹配：给出“10节提升方案 + 1对1答疑”
|
||||||
|
4) 价值外化：讲课程内容、题型覆盖、预期效果与试错成本低
|
||||||
|
5) 价格锚定：原价299→活动19，并确认接受度
|
||||||
|
6) 行动推进：建议上直播（强调互动答疑）
|
||||||
|
7) 私域沉淀：引导加班主任/辅导老师并要求截图确认
|
||||||
|
- 关键分支：
|
||||||
|
- 若用户提出薄弱项在课程覆盖内：强化“针对性内容”介绍
|
||||||
|
- 若用户只关注单科：补充“学科能力关联性，不止提升一科”
|
||||||
|
- 若用户价格犹豫：强化“单节成本低、无二次收费、可回放”
|
||||||
|
- 若用户时间顾虑：强调“周末上课+回放复习”
|
||||||
|
- 收口动作：
|
||||||
|
- 明确收口问题：“您看价格这一块可以接受么？”
|
||||||
|
- 明确动作闭环：加微完成截图回传
|
||||||
|
|
||||||
|
- 元数据配置项：
|
||||||
|
- 槽位定义（slot schema）：
|
||||||
|
- grade
|
||||||
|
- weak_subjects[]
|
||||||
|
- weak_skills[]（如举一反三、题型迁移）
|
||||||
|
- recent_exam_summary
|
||||||
|
- price_acceptance_status
|
||||||
|
- wechat_added_status
|
||||||
|
- live_attendance_intent
|
||||||
|
- 话术模板参数：
|
||||||
|
- promo_price=19
|
||||||
|
- original_price=299
|
||||||
|
- lesson_count=10
|
||||||
|
- has_replay=true
|
||||||
|
- has_tutor_1v1=true
|
||||||
|
- 触发条件配置：
|
||||||
|
- 未确认年级时，禁止进入报价节点
|
||||||
|
- 未完成价格确认时，优先输出价值外化话术
|
||||||
|
- 未加微完成时，优先输出加微引导
|
||||||
|
- 观测埋点建议：
|
||||||
|
- node_entered（分层/危机/方案/报价/加微）
|
||||||
|
- objection_type（价格/时间/效果/信任）
|
||||||
|
- conversion_step（接受报价、同意听直播、完成加微）
|
||||||
|
|
||||||
|
- 提示词约束项：
|
||||||
|
- 角色约束：
|
||||||
|
- 以课程顾问身份进行诊断式沟通，先分层再推荐，不直接硬推销。
|
||||||
|
- 对话策略约束：
|
||||||
|
- 必须先确认年级，再给课程针对性说明。
|
||||||
|
- 必须至少询问一个薄弱点或考试表现，再进入方案介绍。
|
||||||
|
- 报价后必须发起“价格可接受度确认”。
|
||||||
|
- 风格约束：
|
||||||
|
- 语气专业、关怀、不过度夸张。
|
||||||
|
- 用“问题-方案-结果-行动”结构表达。
|
||||||
|
- 合规约束：
|
||||||
|
- 对“清北老师主讲”“达成深度合作”等表述增加可校验开关，默认不做绝对化承诺。
|
||||||
|
- 禁止承诺“保证提分/保证结果”。
|
||||||
|
- 工具/事实优先级：
|
||||||
|
- 优先读取课程事实库（价格、节数、上课形式、回放、服务）再组织话术。
|
||||||
|
- 未命中事实时使用保守表述，并引导人工确认。
|
||||||
|
|
||||||
|
- 备注：
|
||||||
|
- 本条属于“销售转化脚本型资料”，不是完整产品手册；建议后续补充：适用年级范围、开班频次、退款规则、资质证明，用于增强可落库完整性。
|
||||||
|
|
@ -0,0 +1,89 @@
|
||||||
|
# 中台智能体运行时加固（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`
|
||||||
|
|
@ -0,0 +1,123 @@
|
||||||
|
openapi: 3.0.3
|
||||||
|
info:
|
||||||
|
title: Mid Agent Runtime Hardening Dependency API
|
||||||
|
version: 0.1.0
|
||||||
|
x-contract-level: L1
|
||||||
|
paths:
|
||||||
|
/deps/metadata/query:
|
||||||
|
post:
|
||||||
|
operationId: queryMetadata
|
||||||
|
summary: 元数据与知识检索
|
||||||
|
x-requirements:
|
||||||
|
- AC-MARH-05
|
||||||
|
- AC-MARH-06
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/MetadataQueryRequest'
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: 查询成功
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/MetadataQueryResponse'
|
||||||
|
|
||||||
|
/deps/guardrail/output-filter:
|
||||||
|
post:
|
||||||
|
operationId: filterOutput
|
||||||
|
summary: 输出护栏过滤
|
||||||
|
x-requirements:
|
||||||
|
- AC-MARH-01
|
||||||
|
- AC-MARH-02
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/OutputFilterRequest'
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: 过滤结果
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/OutputFilterResponse'
|
||||||
|
|
||||||
|
components:
|
||||||
|
schemas:
|
||||||
|
MetadataQueryRequest:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- intent
|
||||||
|
- query
|
||||||
|
properties:
|
||||||
|
intent:
|
||||||
|
type: string
|
||||||
|
query:
|
||||||
|
type: string
|
||||||
|
metadata_filter:
|
||||||
|
type: object
|
||||||
|
additionalProperties: true
|
||||||
|
top_k:
|
||||||
|
type: integer
|
||||||
|
minimum: 1
|
||||||
|
maximum: 20
|
||||||
|
|
||||||
|
MetadataQueryResponse:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- items
|
||||||
|
properties:
|
||||||
|
items:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/MetadataItem'
|
||||||
|
|
||||||
|
MetadataItem:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- id
|
||||||
|
- content
|
||||||
|
- score
|
||||||
|
properties:
|
||||||
|
id:
|
||||||
|
type: string
|
||||||
|
content:
|
||||||
|
type: string
|
||||||
|
score:
|
||||||
|
type: number
|
||||||
|
metadata:
|
||||||
|
type: object
|
||||||
|
additionalProperties: true
|
||||||
|
|
||||||
|
OutputFilterRequest:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- text
|
||||||
|
properties:
|
||||||
|
text:
|
||||||
|
type: string
|
||||||
|
mode:
|
||||||
|
type: string
|
||||||
|
enum: [agent, micro_flow, fixed, transfer]
|
||||||
|
context:
|
||||||
|
type: object
|
||||||
|
additionalProperties: true
|
||||||
|
|
||||||
|
OutputFilterResponse:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- blocked
|
||||||
|
- filtered_text
|
||||||
|
properties:
|
||||||
|
blocked:
|
||||||
|
type: boolean
|
||||||
|
filtered_text:
|
||||||
|
type: string
|
||||||
|
rule_id:
|
||||||
|
type: string
|
||||||
|
reason:
|
||||||
|
type: string
|
||||||
|
|
@ -0,0 +1,189 @@
|
||||||
|
openapi: 3.0.3
|
||||||
|
info:
|
||||||
|
title: Mid Agent Runtime Hardening Provider API
|
||||||
|
version: 0.1.0
|
||||||
|
x-contract-level: L2
|
||||||
|
paths:
|
||||||
|
/mid/dialogue/respond:
|
||||||
|
post:
|
||||||
|
operationId: respondDialogue
|
||||||
|
summary: 运行时加固后的中台对话响应
|
||||||
|
x-requirements:
|
||||||
|
- AC-MARH-01
|
||||||
|
- AC-MARH-02
|
||||||
|
- AC-MARH-03
|
||||||
|
- AC-MARH-04
|
||||||
|
- AC-MARH-05
|
||||||
|
- AC-MARH-06
|
||||||
|
- AC-MARH-07
|
||||||
|
- AC-MARH-08
|
||||||
|
- AC-MARH-09
|
||||||
|
- AC-MARH-10
|
||||||
|
- AC-MARH-11
|
||||||
|
- AC-MARH-12
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/DialogueRequest'
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: 成功响应
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/DialogueResponse'
|
||||||
|
'400':
|
||||||
|
description: 请求参数错误
|
||||||
|
'500':
|
||||||
|
description: 服务内部错误
|
||||||
|
|
||||||
|
components:
|
||||||
|
schemas:
|
||||||
|
DialogueRequest:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- session_id
|
||||||
|
- user_message
|
||||||
|
- history
|
||||||
|
properties:
|
||||||
|
session_id:
|
||||||
|
type: string
|
||||||
|
user_id:
|
||||||
|
type: string
|
||||||
|
user_message:
|
||||||
|
type: string
|
||||||
|
minLength: 1
|
||||||
|
maxLength: 2000
|
||||||
|
history:
|
||||||
|
type: array
|
||||||
|
description: 仅已送达历史
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/HistoryMessage'
|
||||||
|
interrupted_segments:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/InterruptedSegment'
|
||||||
|
humanize_config:
|
||||||
|
$ref: '#/components/schemas/HumanizeConfig'
|
||||||
|
|
||||||
|
HistoryMessage:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- role
|
||||||
|
- content
|
||||||
|
properties:
|
||||||
|
role:
|
||||||
|
type: string
|
||||||
|
enum: [user, assistant, human]
|
||||||
|
content:
|
||||||
|
type: string
|
||||||
|
|
||||||
|
InterruptedSegment:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- segment_id
|
||||||
|
- content
|
||||||
|
properties:
|
||||||
|
segment_id:
|
||||||
|
type: string
|
||||||
|
content:
|
||||||
|
type: string
|
||||||
|
|
||||||
|
HumanizeConfig:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
enabled:
|
||||||
|
type: boolean
|
||||||
|
min_delay_ms:
|
||||||
|
type: integer
|
||||||
|
minimum: 0
|
||||||
|
max_delay_ms:
|
||||||
|
type: integer
|
||||||
|
minimum: 0
|
||||||
|
length_bucket_strategy:
|
||||||
|
type: string
|
||||||
|
enum: [simple, semantic]
|
||||||
|
|
||||||
|
DialogueResponse:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- segments
|
||||||
|
- trace
|
||||||
|
properties:
|
||||||
|
segments:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/Segment'
|
||||||
|
trace:
|
||||||
|
$ref: '#/components/schemas/TraceInfo'
|
||||||
|
|
||||||
|
Segment:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- segment_id
|
||||||
|
- text
|
||||||
|
- delay_after
|
||||||
|
properties:
|
||||||
|
segment_id:
|
||||||
|
type: string
|
||||||
|
text:
|
||||||
|
type: string
|
||||||
|
delay_after:
|
||||||
|
type: integer
|
||||||
|
minimum: 0
|
||||||
|
|
||||||
|
SegmentStats:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
segment_count:
|
||||||
|
type: integer
|
||||||
|
avg_segment_length:
|
||||||
|
type: number
|
||||||
|
format: float
|
||||||
|
humanize_strategy:
|
||||||
|
type: string
|
||||||
|
|
||||||
|
TraceInfo:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- mode
|
||||||
|
properties:
|
||||||
|
mode:
|
||||||
|
type: string
|
||||||
|
enum: [agent, micro_flow, fixed, transfer]
|
||||||
|
request_id:
|
||||||
|
type: string
|
||||||
|
generation_id:
|
||||||
|
type: string
|
||||||
|
guardrail_triggered:
|
||||||
|
type: boolean
|
||||||
|
guardrail_rule_id:
|
||||||
|
type: string
|
||||||
|
interrupt_consumed:
|
||||||
|
type: boolean
|
||||||
|
kb_tool_called:
|
||||||
|
type: boolean
|
||||||
|
kb_hit:
|
||||||
|
type: boolean
|
||||||
|
fallback_reason_code:
|
||||||
|
type: string
|
||||||
|
react_iterations:
|
||||||
|
type: integer
|
||||||
|
minimum: 0
|
||||||
|
maximum: 5
|
||||||
|
timeout_profile:
|
||||||
|
$ref: '#/components/schemas/TimeoutProfile'
|
||||||
|
segment_stats:
|
||||||
|
$ref: '#/components/schemas/SegmentStats'
|
||||||
|
|
||||||
|
TimeoutProfile:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
per_tool_timeout_ms:
|
||||||
|
type: integer
|
||||||
|
maximum: 2000
|
||||||
|
end_to_end_timeout_ms:
|
||||||
|
type: integer
|
||||||
|
maximum: 8000
|
||||||
|
|
@ -0,0 +1,143 @@
|
||||||
|
---
|
||||||
|
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）
|
||||||
|
|
@ -0,0 +1,191 @@
|
||||||
|
# 中台运行时加固：迭代与工具追溯台账
|
||||||
|
|
||||||
|
> 文档目的：记录“已完成迭代需求”“待完成工具”“工具使用说明”，作为后续对齐与更新的追溯入口。
|
||||||
|
>
|
||||||
|
> 约定：本文件是工作台账，不替代 `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`
|
||||||
|
|
@ -0,0 +1,38 @@
|
||||||
|
# 中台智能体运行时加固 - 功能定界（MARH）
|
||||||
|
|
||||||
|
## 1. 功能边界（Scope）
|
||||||
|
|
||||||
|
### 1.1 覆盖范围（In Scope）
|
||||||
|
- 中台 `respond` 链路输出前护栏强制执行
|
||||||
|
- 打断信息（`interrupted_segments`）语义化处理与重规划
|
||||||
|
- Agent 模式下 KB 默认工具调用链路
|
||||||
|
- ReAct/工具/全链路超时口径统一（3~5次、2s、8s）
|
||||||
|
- 分段与 delay 的拟人策略增强（可配置）
|
||||||
|
- 运行时观测字段补齐（guardrail/interrupt/kb_hit/timeout/segment_stats）
|
||||||
|
|
||||||
|
### 1.2 不覆盖范围（Out of Scope）
|
||||||
|
- Java 渠道发送队列与取消令牌实现
|
||||||
|
- 前端终端 UI 深度改造
|
||||||
|
- 模型供应商替换或底层推理框架重构
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 依赖接口清单（Dependency Contracts）
|
||||||
|
|
||||||
|
### 2.1 对外提供（Provider）
|
||||||
|
- `POST /mid/dialogue/respond`
|
||||||
|
|
||||||
|
### 2.2 对外依赖（Deps）
|
||||||
|
- `POST /deps/metadata/query`（KB 元数据检索）
|
||||||
|
- `POST /deps/guardrail/output-filter`（输出护栏过滤）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 核心验收目标
|
||||||
|
|
||||||
|
- 输出护栏不可绕过（AC-MARH-01/02）
|
||||||
|
- 打断语义可消费、可兜底（AC-MARH-03/04）
|
||||||
|
- KB 默认工具链可降级（AC-MARH-05/06）
|
||||||
|
- 超时口径统一（AC-MARH-07/08/09）
|
||||||
|
- 分段拟人可配置（AC-MARH-10/11）
|
||||||
|
- 观测闭环完整（AC-MARH-12）
|
||||||
|
|
@ -0,0 +1,60 @@
|
||||||
|
# 中台智能体运行时加固（MARH）任务清单
|
||||||
|
|
||||||
|
## Phase 1：护栏与超时口径统一
|
||||||
|
|
||||||
|
- [x] T-MARH-01 在 `respond` 主流程接入输出护栏强制执行（关联：AC-MARH-01）
|
||||||
|
- [x] T-MARH-02 护栏触发信息写入 trace 与审计日志（关联：AC-MARH-02）
|
||||||
|
- [x] T-MARH-03 统一 ReAct 循环上限到 3~5（关联：AC-MARH-07）
|
||||||
|
- [x] T-MARH-04 统一单工具超时 <=2000ms（关联：AC-MARH-08）
|
||||||
|
- [x] T-MARH-05 统一全链路超时 <=8000ms 并降级（关联：AC-MARH-09）
|
||||||
|
|
||||||
|
## Phase 2：打断语义与 KB 默认工具链
|
||||||
|
|
||||||
|
- [x] T-MARH-06 实现 interrupted_segments 重规划输入处理（关联：AC-MARH-03）
|
||||||
|
- [x] T-MARH-07 实现中断异常兜底逻辑（关联：AC-MARH-04）
|
||||||
|
- [x] T-MARH-08 在 Agent 模式接入默认 KB 检索工具调用（关联：AC-MARH-05）
|
||||||
|
- [x] T-MARH-09 实现 KB 失败时可观测降级路径（关联：AC-MARH-06）
|
||||||
|
|
||||||
|
## Phase 3：拟人分段与观测闭环
|
||||||
|
|
||||||
|
- [x] T-MARH-10 实现分段策略组件（语义/长度切分）（关联：AC-MARH-10）
|
||||||
|
- [x] T-MARH-11 实现 delay 策略租户化配置（关联：AC-MARH-11）
|
||||||
|
- [x] T-MARH-12 补齐运行时观测字段与统计（关联：AC-MARH-12）
|
||||||
|
|
||||||
|
## Phase 4：KB 动态检索工具（元数据驱动）
|
||||||
|
|
||||||
|
- [x] T-MARH-13 实现 MetadataFilterBuilder 组件（关联：AC-MARH-05）
|
||||||
|
- [x] T-MARH-14 实现 kb_search_dynamic 工具并注册到 ToolRegistry（关联：AC-MARH-05/06）
|
||||||
|
- [x] T-MARH-15 在 Agent 主链路集成 kb_search_dynamic 工具（关联：AC-MARH-05）
|
||||||
|
- [x] T-MARH-16 添加 KbSearchDynamicResult 数据模型（关联：AC-MARH-05/06）
|
||||||
|
|
||||||
|
## Phase 5：高风险检测工具（元数据驱动）
|
||||||
|
|
||||||
|
- [x] T-MARH-17 实现 HighRiskCheckTool 工具（元数据驱动）（关联：AC-IDMP-05/20）
|
||||||
|
- [x] T-MARH-18 添加 HighRiskCheckResult 数据模型（关联：AC-IDMP-05/20）
|
||||||
|
- [x] T-MARH-19 注册 high_risk_check 工具到 ToolRegistry（关联：AC-IDMP-05）
|
||||||
|
- [x] T-MARH-20 在 dialogue 主链路集成 high_risk_check（高风险优先）（关联：AC-IDMP-05/20）
|
||||||
|
- [x] T-MARH-21 更新 policy_router 支持高风险检测结果（关联：AC-IDMP-05/20）
|
||||||
|
|
||||||
|
## 验收关卡（DoD）
|
||||||
|
|
||||||
|
- [x] openapi.provider.yaml 达到 L2 并可契约测试
|
||||||
|
- [x] 所有 AC 在 requirements/openapi/design/tasks 可追踪
|
||||||
|
- [x] 仅中台范围，不引入渠道侧实现耦合
|
||||||
|
|
||||||
|
## 实现文件清单
|
||||||
|
|
||||||
|
| 文件 | AC 关联 | 说明 |
|
||||||
|
|------|---------|------|
|
||||||
|
| `services/mid/output_guardrail_executor.py` | AC-MARH-01/02 | 输出护栏强制执行器 |
|
||||||
|
| `services/mid/interrupt_context_enricher.py` | AC-MARH-03/04 | 中断上下文增强器 |
|
||||||
|
| `services/mid/default_kb_tool_runner.py` | AC-MARH-05/06 | KB 默认工具执行器 |
|
||||||
|
| `services/mid/metadata_filter_builder.py` | AC-MARH-05 | 元数据过滤器构建器 |
|
||||||
|
| `services/mid/kb_search_dynamic_tool.py` | AC-MARH-05/06 | KB 动态检索工具 |
|
||||||
|
| `services/mid/high_risk_check_tool.py` | AC-IDMP-05/20 | 高风险检测工具（元数据驱动） |
|
||||||
|
| `services/mid/segment_humanizer.py` | AC-MARH-10/11 | 分段拟人化组件 |
|
||||||
|
| `services/mid/runtime_observer.py` | AC-MARH-12 | 运行时观测器 |
|
||||||
|
| `services/mid/timeout_governor.py` | AC-MARH-08/09 | 超时治理（已更新） |
|
||||||
|
| `services/mid/policy_router.py` | AC-IDMP-02/05/16/20 | 策略路由器（已更新支持高风险检测） |
|
||||||
|
| `api/mid/dialogue.py` | AC-MARH-01~12, AC-IDMP-05/20 | 主入口（已集成高风险检测） |
|
||||||
|
| `models/mid/schemas.py` | AC-MARH-05/11/12, AC-IDMP-05/20 | 数据模型（已更新） |
|
||||||
Loading…
Reference in New Issue