--- 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 工具"