227 lines
11 KiB
Markdown
227 lines
11 KiB
Markdown
---
|
||
context:
|
||
module: "mid-agent-runtime-hardening"
|
||
feature: "MARH"
|
||
status: "🔄进行中"
|
||
version: "0.1.0"
|
||
active_ac_range: "AC-MARH-01~12, AC-IDMP-05/20, AC-IDMP-13"
|
||
|
||
spec_references:
|
||
requirements: "spec/mid-agent-runtime-hardening/requirements.md"
|
||
openapi_provider: "spec/mid-agent-runtime-hardening/openapi.provider.yaml"
|
||
openapi_deps: "spec/mid-agent-runtime-hardening/openapi.deps.yaml"
|
||
design: "spec/mid-agent-runtime-hardening/design.md"
|
||
tasks: "spec/mid-agent-runtime-hardening/tasks.md"
|
||
active_version: "0.1.0"
|
||
|
||
overall_progress:
|
||
- "[x] Phase 1: 护栏与超时口径统一 (100%) [T-MARH-01~05]"
|
||
- "[x] Phase 2: 打断语义处理 (100%) [T-MARH-06~07]"
|
||
- "[x] Phase 3: KB 默认工具链 (100%) [T-MARH-08~09]"
|
||
- "[x] Phase 4: KB 动态检索工具 (100%) [T-MARH-13~16]"
|
||
- "[x] Phase 5: 拟人分段与观测闭环 (100%) [T-MARH-10~12]"
|
||
- "[x] Phase 6: 高风险检测工具 (100%) [T-MARH-17~21]"
|
||
- "[x] Phase 7: 记忆召回工具 (100%) [T-MARH-22~24]"
|
||
|
||
current_phase:
|
||
goal: "memory_recall 工具已实现并集成到 Agent 主链路"
|
||
sub_tasks:
|
||
- "[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]"
|
||
- "[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]"
|
||
- "[x] T-MARH-10: 实现分段策略组件（语义/长度切分）[AC-MARH-10]"
|
||
- "[x] T-MARH-11: 实现 delay 策略租户化配置 [AC-MARH-11]"
|
||
- "[x] T-MARH-12: 补齐运行时观测字段与统计 [AC-MARH-12]"
|
||
- "[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]"
|
||
- "[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]"
|
||
- "[x] T-MARH-22: 实现 MemoryRecallTool 工具 [AC-IDMP-13]"
|
||
- "[x] T-MARH-23: 添加 MemoryRecallResult 数据模型 [AC-IDMP-13]"
|
||
- "[x] T-MARH-24: 在 Agent 主链路集成 memory_recall [AC-IDMP-13]"
|
||
|
||
next_action:
|
||
immediate: "验证代码编译和语法检查"
|
||
details:
|
||
file: "ai-service/app/services/mid/memory_recall_tool.py:1"
|
||
action: "执行 py_compile / ruff check 验证代码质量"
|
||
reference: "spec/mid-agent-runtime-hardening/runtime-iteration-and-tools-tracking.md:AC-IDMP-13"
|
||
constraints: "验证 AC-IDMP-13 验收标准"
|
||
|
||
technical_context:
|
||
module_structure: |
|
||
ai-service/app/
|
||
├── api/mid/dialogue.py # 主入口 respond_dialogue [AC-MARH-01~12, AC-IDMP-05/20, AC-IDMP-13]
|
||
├── services/mid/
|
||
│ ├── agent_orchestrator.py # ReAct 循环控制 [AC-MARH-07]
|
||
│ ├── timeout_governor.py # 超时治理 [AC-MARH-08/09]
|
||
│ ├── trace_logger.py # 追踪日志 [AC-MARH-02/03/12]
|
||
│ ├── output_guardrail_executor.py # 输出护栏执行器 [AC-MARH-01/02]
|
||
│ ├── interrupt_context_enricher.py# 中断上下文增强 [AC-MARH-03/04]
|
||
│ ├── default_kb_tool_runner.py # KB 默认工具执行器 [AC-MARH-05/06]
|
||
│ ├── metadata_filter_builder.py # 元数据过滤器构建器 [AC-MARH-05]
|
||
│ ├── kb_search_dynamic_tool.py # KB 动态检索工具 [AC-MARH-05/06]
|
||
│ ├── high_risk_check_tool.py # 高风险检测工具 [AC-IDMP-05/20]
|
||
│ ├── memory_recall_tool.py # 记忆召回工具 [AC-IDMP-13] ★新增
|
||
│ ├── policy_router.py # 策略路由器 [AC-IDMP-02/05/16/20]
|
||
│ ├── segment_humanizer.py # 分段拟人化组件 [AC-MARH-10/11]
|
||
│ └── runtime_observer.py # 运行时观测器 [AC-MARH-12]
|
||
├── services/guardrail/
|
||
│ └── output_filter.py # 输出护栏
|
||
└── models/mid/schemas.py # 数据模型 [AC-MARH-05/11/12, AC-IDMP-05/20, AC-IDMP-13]
|
||
|
||
key_decisions:
|
||
- decision: "复用现有 OutputFilter 组件，通过 OutputGuardrailExecutor 封装"
|
||
reason: "避免重复实现，保持代码一致性"
|
||
impact: "OutputGuardrailExecutor 在 dialogue.py 中注入并强制调用"
|
||
- decision: "全链路超时从 30000ms 调整为 8000ms"
|
||
reason: "AC-MARH-09 要求全链路 <=8000ms"
|
||
impact: "timeout_governor.py 的 DEFAULT_END_TO_END_TIMEOUT_MS 已调整为 8000"
|
||
- decision: "新增 InterruptContextEnricher 组件处理 interrupted_segments"
|
||
reason: "AC-MARH-03/04 要求打断语义可消费、可兜底"
|
||
impact: "新建组件文件，在 respond 流程中调用"
|
||
- decision: "新增 MetadataFilterBuilder 组件实现元数据驱动过滤"
|
||
reason: "支持动态参数生成，无需改代码即可生效"
|
||
impact: "复用现有元数据字段定义能力，基于字段配置动态装配过滤参数"
|
||
- decision: "新增 kb_search_dynamic 工具替代固定入参的 KB 检索"
|
||
reason: "AC-MARH-05 要求 Agent 默认基于 KB 事实回答"
|
||
impact: "工具注册到 ToolRegistry，在 Agent 模式下自动调用"
|
||
- decision: "新增 high_risk_check 工具实现元数据驱动的高风险检测"
|
||
reason: "AC-IDMP-05/20 要求高风险场景最小集可配置，支持多租户隔离"
|
||
impact: "工具从 HighRiskPolicy 表读取规则，支持关键词+正则匹配，高风险优先于普通意图路由"
|
||
- decision: "新增 memory_recall 工具实现短期可用记忆注入"
|
||
reason: "AC-IDMP-13 要求对话前读取用户可用记忆，减少重复追问"
|
||
impact: "工具读取 profile/facts/preferences/last_summary/slots，超时 <=1000ms，失败不阻断主链路"
|
||
|
||
code_snippets: |
|
||
# TraceInfo 新增字段 (schemas.py)
|
||
guardrail_triggered: bool | None
|
||
guardrail_rule_id: str | None
|
||
interrupt_consumed: bool | None
|
||
kb_tool_called: bool | None
|
||
kb_hit: bool | None
|
||
fallback_reason_code: str | None
|
||
react_iterations: int | None
|
||
timeout_profile: TimeoutProfile | None
|
||
segment_stats: SegmentStats | None
|
||
|
||
# TimeoutProfile 更新 (schemas.py)
|
||
end_to_end_timeout_ms: int = Field(default=8000, le=8000)
|
||
|
||
# KbSearchDynamicResult 新增 (schemas.py)
|
||
class KbSearchDynamicResultSchema(BaseModel):
|
||
success: bool
|
||
hits: list[KbSearchDynamicHit]
|
||
applied_filter: dict[str, Any]
|
||
missing_required_slots: list[MissingRequiredSlot]
|
||
filter_debug: dict[str, Any]
|
||
fallback_reason_code: str | None
|
||
duration_ms: int
|
||
|
||
# HighRiskCheckResult 新增 (schemas.py)
|
||
class HighRiskCheckResult(BaseModel):
|
||
matched: bool
|
||
risk_scenario: HighRiskScenario | None
|
||
confidence: float
|
||
recommended_mode: ExecutionMode | None
|
||
rule_id: str | None
|
||
reason: str | None
|
||
fallback_reason_code: str | None
|
||
duration_ms: int
|
||
matched_text: str | None
|
||
matched_pattern: str | None
|
||
|
||
# MemoryRecallResult 新增 (schemas.py)
|
||
class SlotSource(str, Enum):
|
||
USER_CONFIRMED = "user_confirmed"
|
||
RULE_EXTRACTED = "rule_extracted"
|
||
LLM_INFERRED = "llm_inferred"
|
||
DEFAULT = "default"
|
||
|
||
class MemorySlot(BaseModel):
|
||
key: str
|
||
value: Any
|
||
source: SlotSource
|
||
confidence: float
|
||
updated_at: str | None
|
||
|
||
class MemoryRecallResult(BaseModel):
|
||
profile: dict[str, Any]
|
||
facts: list[str]
|
||
preferences: dict[str, Any]
|
||
last_summary: str | None
|
||
slots: dict[str, MemorySlot]
|
||
missing_slots: list[str]
|
||
fallback_reason_code: str | None
|
||
duration_ms: int
|
||
|
||
session_history:
|
||
- session: "Session #1 (2026-03-05)"
|
||
completed:
|
||
- "T-MARH-01~07: Phase 1 护栏与超时口径统一 + Phase 2 打断语义处理"
|
||
changes:
|
||
- "创建 output_guardrail_executor.py [AC-MARH-01/02]"
|
||
- "创建 interrupt_context_enricher.py [AC-MARH-03/04]"
|
||
- "更新 timeout_governor.py 超时配置 [AC-MARH-08/09]"
|
||
- "更新 agent_orchestrator.py ReAct 循环控制 [AC-MARH-07]"
|
||
- "更新 trace_logger.py 添加新字段 [AC-MARH-02/03/12]"
|
||
- "更新 schemas.py 添加 trace 字段和 SegmentStats"
|
||
- "更新 dialogue.py 集成护栏和中断处理"
|
||
verification:
|
||
- "py_compile: 所有文件编译通过"
|
||
- "ruff check: 仅 4 个 F841 未使用变量警告（不影响功能）"
|
||
|
||
- session: "Session #2 (2026-03-05)"
|
||
completed:
|
||
- "T-MARH-13~16: Phase 4 KB 动态检索工具（元数据驱动）"
|
||
changes:
|
||
- "创建 metadata_filter_builder.py [AC-MARH-05]"
|
||
- "创建 kb_search_dynamic_tool.py [AC-MARH-05/06]"
|
||
- "更新 schemas.py 添加 KbSearchDynamicResult 相关模型 [AC-MARH-05/06]"
|
||
- "更新 dialogue.py 注册 kb_search_dynamic 工具并集成到 Agent 主链路 [AC-MARH-05]"
|
||
- "更新 tasks.md 添加 Phase 4 任务"
|
||
verification:
|
||
- "待执行: py_compile / ruff check"
|
||
|
||
- session: "Session #3 (2026-03-05)"
|
||
completed:
|
||
- "T-MARH-17~21: Phase 6 高风险检测工具（元数据驱动）"
|
||
changes:
|
||
- "创建 high_risk_check_tool.py [AC-IDMP-05/20]"
|
||
- "更新 schemas.py 添加 HighRiskCheckResult 模型 [AC-IDMP-05/20]"
|
||
- "更新 dialogue.py 注册 high_risk_check 工具并集成到主链路 [AC-IDMP-05/20]"
|
||
- "更新 policy_router.py 添加 route_with_high_risk_check 方法 [AC-IDMP-05/20]"
|
||
- "更新 tasks.md 添加 Phase 5 任务"
|
||
- "更新进度文档"
|
||
verification:
|
||
- "待执行: py_compile / ruff check"
|
||
|
||
- session: "Session #4 (2026-03-05)"
|
||
completed:
|
||
- "T-MARH-22~24: Phase 7 记忆召回工具"
|
||
changes:
|
||
- "创建 memory_recall_tool.py [AC-IDMP-13]"
|
||
- "更新 schemas.py 添加 MemoryRecallResult, MemorySlot, SlotSource 模型 [AC-IDMP-13]"
|
||
- "更新 dialogue.py 注册 memory_recall 工具并集成到 Agent 主链路 [AC-IDMP-13]"
|
||
- "更新 runtime-iteration-and-tools-tracking.md 工具台账"
|
||
- "更新进度文档"
|
||
verification:
|
||
- "待执行: py_compile / ruff check"
|
||
|
||
startup_guide:
|
||
- "Step 1: 读取本进度文档（了解当前位置与下一步）"
|
||
- "Step 2: 读取 spec/mid-agent-runtime-hardening/ 目录下的规范文件"
|
||
- "Step 3: 验证代码编译和语法检查"
|
||
- "Step 4: 执行联调测试验证 memory_recall 工具"
|