---
context:
  module: "intent-driven-script"
  feature: "IDS-Backend"
  status: "✅已完成"
  version: "1.0.0"
  active_ac_range: "AC-IDS-01~13"
  role: "backend"

spec_references:
  requirements: "spec/intent-driven-script/requirements.md"
  design: "spec/intent-driven-script/design.md"
  tasks: "spec/intent-driven-script/tasks.md"
  openapi: "spec/intent-driven-script/openapi.admin.yaml"

overall_progress:
  - [x] Phase 1: 数据模型与 API 扩展 (100%)
  - [x] Phase 2: 后端话术生成引擎 (100%)
  - [x] Phase 4: 测试与验证 (100%)

current_phase:
  goal: "后端开发已完成"
  sub_tasks:
    - [x] Task 1.1: 扩展 Python 类型定义 ✅
    - [x] Task 1.3: 更新 OpenAPI 契约 ✅ (已定义在 spec/)
    - [x] Task 1.4: 验证 API 向后兼容性 ✅
    - [x] Task 2.1: 创建 ScriptGenerator 模块 ✅
    - [x] Task 2.2: 创建 TemplateEngine 模块 ✅
    - [x] Task 2.3: 扩展 FlowEngine ✅
    - [x] Task 2.4: 修改 FlowEngine.start() ✅
    - [x] Task 2.5: 修改 FlowEngine.advance() ✅
    - [x] Task 2.6: 实现 Fallback 机制 ✅
    - [x] Phase 4: 单元测试 ✅ (32 tests passed)
  
  next_action:
    immediate: "后端开发完成，等待前端联调"
    details:
      file: "N/A"
      action: "通知前端进行联调"
    constraints: "无"

technical_context:
  module_structure: "ai-service/app/services/flow/"
  key_decisions:
    - decision: "在现有 FlowStep SQLModel 中扩展字段"
      reason: "steps 字段已经是 JSON 类型，可以直接扩展，无需数据库迁移"
      impact: "保持向后兼容，现有流程无需修改"
    - decision: "ScriptGenerator 和 TemplateEngine 作为独立模块"
      reason: "遵循单一职责原则，便于测试和维护"
      impact: "需要在 FlowEngine 中注入 LLM 客户端"
    - decision: "LLM 调用超时设置为 2 秒"
      reason: "对话系统需要快速响应，2 秒是可接受的上限"
      impact: "超时后返回 fallback 话术"
  code_snippets: |
    # FlowStep 扩展字段
    script_mode: str = Field(default=ScriptMode.FIXED.value)
    intent: str | None = Field(default=None)
    intent_description: str | None = Field(default=None)
    script_constraints: list[str] | None = Field(default=None)
    expected_variables: list[str] | None = Field(default=None)

    # FlowEngine 话术生成
    async def _generate_step_content(step, context, history) -> str:
        script_mode = step.get("script_mode", "fixed")
        if script_mode == "fixed":
            return step.get("content", "")
        elif script_mode == "flexible":
            return await self._script_generator.generate(...)
        elif script_mode == "template":
            return await self._template_engine.fill_template(...)

session_history:
  - session: "Session #1 (2026-02-28)"
    completed:
      - Task 1.1: 扩展 Python 类型定义
      - Task 2.1: 创建 ScriptGenerator 模块
      - Task 2.2: 创建 TemplateEngine 模块
      - Task 2.3-2.6: 扩展 FlowEngine
      - Phase 4: 单元测试 (32 tests)
    changes:
      - ai-service/app/models/entities.py (新增 ScriptMode 枚举，扩展 FlowStep)
      - ai-service/app/services/flow/script_generator.py (新建)
      - ai-service/app/services/flow/template_engine.py (新建)
      - ai-service/app/services/flow/engine.py (重构)
      - ai-service/app/services/flow/__init__.py (更新导出)
      - ai-service/tests/test_script_generator.py (新建)
      - ai-service/tests/test_template_engine.py (新建)
      - ai-service/tests/test_flow_engine_script_generation.py (新建)

startup_guide:
  - "Step 1: 读取本进度文档"
  - "Step 2: 读取 spec_references 中的规范"
  - "Step 3: 执行 next_action"
---
