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