From 3d9f718f5f8ad3fbfa6b4e185c80b43518e0f24b Mon Sep 17 00:00:00 2001 From: MerCry Date: Thu, 5 Mar 2026 17:50:59 +0800 Subject: [PATCH] spec: add intent-driven-mid-platform and mid-agent-runtime-hardening specifications [AC-IDMP-01~20, AC-MARH-01~12] --- spec/intent-driven-mid-platform/design.md | 147 ++++++++ .../openapi.deps.yaml | 161 +++++++++ .../openapi.provider.yaml | 338 ++++++++++++++++++ .../requirements.md | 107 ++++++ spec/intent-driven-mid-platform/scope.md | 47 +++ spec/intent-driven-mid-platform/tasks.md | 117 ++++++ .../metadata-intent-flow-operations.md | 202 +++++++++++ .../solution-java-channel-side.md | 200 +++++++++++ .../solution-python-mid-platform.md | 201 +++++++++++ .../customer-material-classification-todo.md | 137 +++++++ spec/mid-agent-runtime-hardening/design.md | 89 +++++ .../openapi.deps.yaml | 123 +++++++ .../openapi.provider.yaml | 189 ++++++++++ .../requirements.md | 143 ++++++++ .../runtime-iteration-and-tools-tracking.md | 191 ++++++++++ spec/mid-agent-runtime-hardening/scope.md | 38 ++ spec/mid-agent-runtime-hardening/tasks.md | 60 ++++ 17 files changed, 2490 insertions(+) create mode 100644 spec/intent-driven-mid-platform/design.md create mode 100644 spec/intent-driven-mid-platform/openapi.deps.yaml create mode 100644 spec/intent-driven-mid-platform/openapi.provider.yaml create mode 100644 spec/intent-driven-mid-platform/requirements.md create mode 100644 spec/intent-driven-mid-platform/scope.md create mode 100644 spec/intent-driven-mid-platform/tasks.md create mode 100644 spec/intent-driven-script/metadata-intent-flow-operations.md create mode 100644 spec/intent-driven-script/solution-java-channel-side.md create mode 100644 spec/intent-driven-script/solution-python-mid-platform.md create mode 100644 spec/mid-agent-runtime-hardening/customer-material-classification-todo.md create mode 100644 spec/mid-agent-runtime-hardening/design.md create mode 100644 spec/mid-agent-runtime-hardening/openapi.deps.yaml create mode 100644 spec/mid-agent-runtime-hardening/openapi.provider.yaml create mode 100644 spec/mid-agent-runtime-hardening/requirements.md create mode 100644 spec/mid-agent-runtime-hardening/runtime-iteration-and-tools-tracking.md create mode 100644 spec/mid-agent-runtime-hardening/scope.md create mode 100644 spec/mid-agent-runtime-hardening/tasks.md diff --git a/spec/intent-driven-mid-platform/design.md b/spec/intent-driven-mid-platform/design.md new file mode 100644 index 0000000..666487e --- /dev/null +++ b/spec/intent-driven-mid-platform/design.md @@ -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` diff --git a/spec/intent-driven-mid-platform/openapi.deps.yaml b/spec/intent-driven-mid-platform/openapi.deps.yaml new file mode 100644 index 0000000..76ccb89 --- /dev/null +++ b/spec/intent-driven-mid-platform/openapi.deps.yaml @@ -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: 本轮会话摘要（可选，由中台异步生成后回写） diff --git a/spec/intent-driven-mid-platform/openapi.provider.yaml b/spec/intent-driven-mid-platform/openapi.provider.yaml new file mode 100644 index 0000000..efed36a --- /dev/null +++ b/spec/intent-driven-mid-platform/openapi.provider.yaml @@ -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] diff --git a/spec/intent-driven-mid-platform/requirements.md b/spec/intent-driven-mid-platform/requirements.md new file mode 100644 index 0000000..b5bfb15 --- /dev/null +++ b/spec/intent-driven-mid-platform/requirements.md @@ -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 | 高风险最小场景集 | diff --git a/spec/intent-driven-mid-platform/scope.md b/spec/intent-driven-mid-platform/scope.md new file mode 100644 index 0000000..e5d25a5 --- /dev/null +++ b/spec/intent-driven-mid-platform/scope.md @@ -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：稳定性治理与灰度回滚 diff --git a/spec/intent-driven-mid-platform/tasks.md b/spec/intent-driven-mid-platform/tasks.md new file mode 100644 index 0000000..3d98e35 --- /dev/null +++ b/spec/intent-driven-mid-platform/tasks.md @@ -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 | diff --git a/spec/intent-driven-script/metadata-intent-flow-operations.md b/spec/intent-driven-script/metadata-intent-flow-operations.md new file mode 100644 index 0000000..fd0948d --- /dev/null +++ b/spec/intent-driven-script/metadata-intent-flow-operations.md @@ -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 + +目标：持续提高“命中率、相关性、可用率”。 diff --git a/spec/intent-driven-script/solution-java-channel-side.md b/spec/intent-driven-script/solution-java-channel-side.md new file mode 100644 index 0000000..929d649 --- /dev/null +++ b/spec/intent-driven-script/solution-java-channel-side.md @@ -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 的价值会显著放大。 diff --git a/spec/intent-driven-script/solution-python-mid-platform.md b/spec/intent-driven-script/solution-python-mid-platform.md new file mode 100644 index 0000000..f8a9e25 --- /dev/null +++ b/spec/intent-driven-script/solution-python-mid-platform.md @@ -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 护栏保证可控。 +- 以观测与治理机制保障可回放、可归因、可灰度演进。 + +在不扩展渠道实现细节与不引入语言实现绑定的前提下，可支撑中台能力平滑升级。 \ No newline at end of file diff --git a/spec/mid-agent-runtime-hardening/customer-material-classification-todo.md b/spec/mid-agent-runtime-hardening/customer-material-classification-todo.md new file mode 100644 index 0000000..fe12541 --- /dev/null +++ b/spec/mid-agent-runtime-hardening/customer-material-classification-todo.md @@ -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（接受报价、同意听直播、完成加微） + + - 提示词约束项： + - 角色约束： + - 以课程顾问身份进行诊断式沟通，先分层再推荐，不直接硬推销。 + - 对话策略约束： + - 必须先确认年级，再给课程针对性说明。 + - 必须至少询问一个薄弱点或考试表现，再进入方案介绍。 + - 报价后必须发起“价格可接受度确认”。 + - 风格约束： + - 语气专业、关怀、不过度夸张。 + - 用“问题-方案-结果-行动”结构表达。 + - 合规约束： + - 对“清北老师主讲”“达成深度合作”等表述增加可校验开关，默认不做绝对化承诺。 + - 禁止承诺“保证提分/保证结果”。 + - 工具/事实优先级： + - 优先读取课程事实库（价格、节数、上课形式、回放、服务）再组织话术。 + - 未命中事实时使用保守表述，并引导人工确认。 + +- 备注： + - 本条属于“销售转化脚本型资料”，不是完整产品手册；建议后续补充：适用年级范围、开班频次、退款规则、资质证明，用于增强可落库完整性。 diff --git a/spec/mid-agent-runtime-hardening/design.md b/spec/mid-agent-runtime-hardening/design.md new file mode 100644 index 0000000..0691d7f --- /dev/null +++ b/spec/mid-agent-runtime-hardening/design.md @@ -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` diff --git a/spec/mid-agent-runtime-hardening/openapi.deps.yaml b/spec/mid-agent-runtime-hardening/openapi.deps.yaml new file mode 100644 index 0000000..fc4f23f --- /dev/null +++ b/spec/mid-agent-runtime-hardening/openapi.deps.yaml @@ -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 diff --git a/spec/mid-agent-runtime-hardening/openapi.provider.yaml b/spec/mid-agent-runtime-hardening/openapi.provider.yaml new file mode 100644 index 0000000..400ef1c --- /dev/null +++ b/spec/mid-agent-runtime-hardening/openapi.provider.yaml @@ -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 diff --git a/spec/mid-agent-runtime-hardening/requirements.md b/spec/mid-agent-runtime-hardening/requirements.md new file mode 100644 index 0000000..82733fa --- /dev/null +++ b/spec/mid-agent-runtime-hardening/requirements.md @@ -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） diff --git a/spec/mid-agent-runtime-hardening/runtime-iteration-and-tools-tracking.md b/spec/mid-agent-runtime-hardening/runtime-iteration-and-tools-tracking.md new file mode 100644 index 0000000..2b48f2b --- /dev/null +++ b/spec/mid-agent-runtime-hardening/runtime-iteration-and-tools-tracking.md @@ -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` diff --git a/spec/mid-agent-runtime-hardening/scope.md b/spec/mid-agent-runtime-hardening/scope.md new file mode 100644 index 0000000..344f349 --- /dev/null +++ b/spec/mid-agent-runtime-hardening/scope.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） diff --git a/spec/mid-agent-runtime-hardening/tasks.md b/spec/mid-agent-runtime-hardening/tasks.md new file mode 100644 index 0000000..5974821 --- /dev/null +++ b/spec/mid-agent-runtime-hardening/tasks.md @@ -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 | 数据模型（已更新） |