MerCry
/
ai-robot-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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 2026-03-05 17:50:59 +08:00
parent 1b325f5aeb
commit 3d9f718f5f
17 changed files with 2490 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

147
spec/intent-driven-mid-platform/design.md Normal file
View File

@ -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`

161
spec/intent-driven-mid-platform/openapi.deps.yaml Normal file
View File

@ -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: 本轮会话摘要（可选，由中台异步生成后回写）

338
spec/intent-driven-mid-platform/openapi.provider.yaml Normal file
View File

@ -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]

107
spec/intent-driven-mid-platform/requirements.md Normal file
View File

@ -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 | 高风险最小场景集 |

47
spec/intent-driven-mid-platform/scope.md Normal file
View File

@ -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：稳定性治理与灰度回滚

117
spec/intent-driven-mid-platform/tasks.md Normal file
View File

@ -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 |

202
spec/intent-driven-script/metadata-intent-flow-operations.md Normal file
View File

@ -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
目标：持续提高“命中率、相关性、可用率”。

200
spec/intent-driven-script/solution-java-channel-side.md Normal file
View File

@ -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 的价值会显著放大。

201
spec/intent-driven-script/solution-python-mid-platform.md Normal file
View File

@ -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 护栏保证可控。
- 以观测与治理机制保障可回放、可归因、可灰度演进。
在不扩展渠道实现细节与不引入语言实现绑定的前提下，可支撑中台能力平滑升级。

137
spec/mid-agent-runtime-hardening/customer-material-classification-todo.md Normal file
View File

@ -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（接受报价、同意听直播、完成加微）
- 提示词约束项：
- 角色约束：
- 以课程顾问身份进行诊断式沟通，先分层再推荐，不直接硬推销。
- 对话策略约束：
- 必须先确认年级，再给课程针对性说明。
- 必须至少询问一个薄弱点或考试表现，再进入方案介绍。
- 报价后必须发起“价格可接受度确认”。
- 风格约束：
- 语气专业、关怀、不过度夸张。
- 用“问题-方案-结果-行动”结构表达。
- 合规约束：
- 对“清北老师主讲”“达成深度合作”等表述增加可校验开关，默认不做绝对化承诺。
- 禁止承诺“保证提分/保证结果”。
- 工具/事实优先级：
- 优先读取课程事实库（价格、节数、上课形式、回放、服务）再组织话术。
- 未命中事实时使用保守表述，并引导人工确认。
- 备注：
- 本条属于“销售转化脚本型资料”，不是完整产品手册；建议后续补充：适用年级范围、开班频次、退款规则、资质证明，用于增强可落库完整性。

89
spec/mid-agent-runtime-hardening/design.md Normal file
View File

@ -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`

123
spec/mid-agent-runtime-hardening/openapi.deps.yaml Normal file
View File

@ -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

189
spec/mid-agent-runtime-hardening/openapi.provider.yaml Normal file
View File

@ -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

143
spec/mid-agent-runtime-hardening/requirements.md Normal file
View File

@ -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）

191
spec/mid-agent-runtime-hardening/runtime-iteration-and-tools-tracking.md Normal file
View File

@ -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`

38
spec/mid-agent-runtime-hardening/scope.md Normal file
View File

@ -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）

60
spec/mid-agent-runtime-hardening/tasks.md Normal file
View File

@ -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 | 数据模型（已更新） |