行程规划智能体的功能介绍及开发

用户 ──→ MasterAgent（路由/意图识别）
             │
             ├── ItineraryPlanAgent ←── 本文主角（搜索规划审核）
             ├── ItineraryManageAgent（差旅单/冲突检测）
             └── BookingAgent（预订/退改）

① 拿需求   → 查审批单 / 读对话 / 追问用户
② 拿约束   → 召回偏好(长期记忆) + 查差旅政策
③ 做计划   → create_plan（写进 PlanNotebook）
④ 搜候选   → 加载 tuniu-cli → 搜去程/返程/酒店
⑤ 打偏好分 → LLM 对每条候选打 0-100 分
⑥ 组合排序 → plan_itinerary（客观计算引擎，存 Redis）
⑦ 审核     → itinerary_review_agent（五维检查）
⑧ 判修复   → 有 FAIL/WARNING 就剔除违规候选，回到 ⑥（最多 2 轮）
⑨ 出方案   → 倒金字塔 Markdown，停下等用户确认

// ItineraryPlanAgent.java —— @Configuration + @Scope("prototype")
// 关键模型与参数
private static final int MAX_ITERATIONS = 15;

@Bean(name = "itineraryPlanAgent")
@Scope("prototype")   // 每次对话新建一个实例，避免状态串扰
public ReActAgent build() {

    // ① 工具注册——并行执行开启
    Toolkit toolkit = new Toolkit(ToolkitConfig.builder()
            .parallel(true)  // 允许同一轮推理中并发调多工具
            .build());
    toolkit.registration().tool(policyTools).apply();           // 差旅政策查询
    toolkit.registration().tool(travelOrderReadTools).apply();  // 已审批差旅单
    toolkit.registration().tool(bookingReadTools).apply();      // 外部预订记录
    toolkit.registration().tool(queryUserInfoTools).apply();    // 用户信息+base城市
    toolkit.registration().tool(apiKeyTools).apply();           // 第三方 API Key
    toolkit.registration().tool(destinationLiveTools).apply();  // 天气+目的地新闻
    toolkit.registration().tool(itineraryPlannerTool).apply();  // 核心组合排序引擎
    toolkit.registration()
        .mcpClient(weatherMcpClient)
        .enableTools(weatherMcpEnabledTools).apply();           // 天气 MCP
    toolkit.registration()
        .mcpClient(oriznVisaMcpClient)
        .enableTools(oriznMcpEnabledTools).apply();             // 签证 MCP

    // ② 子智能体作为工具——委托审核
    toolkit.registration()
        .subAgent((SubAgentProvider<ReActAgent>) () ->
                applicationContext.getBean("itineraryReviewAgent", ReActAgent.class),
            SubAgentConfig.builder()
                .toolName("itinerary_review_agent")
                .description("委托行程审核子智能体对行程方案进行五维结构化审核")
                .forwardEvents(false)  // 不把子 agent 事件冒泡到父
                .build())
        .apply();

    // ③ Skill（tuniu-cli 搜索）
    SkillBox skillBox = buildPlanningSkillBox(toolkit);

    // ④ PlanNotebook —— Plan-and-Execute 核心组件
    PlanNotebook planNotebook = PlanNotebook.builder()
            .needUserConfirm(false)  // 自动执行，无需等用户逐步确认
            .build();
    // 注册变化钩子：步骤状态变更时实时推送前端
    if (capturedSessionId != null) {
        planNotebook.addChangeHook("plan_progress_notifier",
            (nb, plan) -> progressNotifierHook.sendPlanUpdate(capturedSessionId, plan));
    }

    // ⑤ AutoContextMemory —— 超长对话自动压缩
    AutoContextMemory memory = AgentMemoryFactory.create(stableModel);

    // ⑥ 组装 ReActAgent
    ReActAgent agent = ReActAgent.builder()
            .name("ItineraryPlanAgent")
            .model(strongModelWithThinking)            // qwen3.7-max + enableThinking
            .memory(memory)
            .longTermMemory(longTermMemory)            // 跨会话偏好记忆
            .longTermMemoryMode(LongTermMemoryMode.AGENT_CONTROL) // Agent 自主决定何时读写
            .toolkit(toolkit)
            .toolExecutionContext(createToolCtx())     // 注入 sessionCtx（userId 等透明参数）
            .skillBox(skillBox)
            .hooks(List.of(
                dynamicTimeInjectionHook,              // 优先级 1：稳定前缀 + 动态时间
                new AutoContextHook(),                 // 上下文超长时自动压缩
                new PlanAwareThinkingHook(planNotebook, 2048), // 按阶段开关深度思考
                cliResultCompressHook,                 // CLI 结果去重压缩
                flightApiKeyHook,                      // 航班 API Key 注入
                tuniuApiKeyHook,                       // 途牛 API Key 注入
                rghUserIsolationHook,                  // 用户隔离
                skillContentCollapseHook,              // Skill 内容折叠
                sessionPersistenceHook,                // 会话持久化
                executionLoggerHook,                   // 执行日志
                toolCircuitBreakerHook,                // 工具熔断器
                progressNotifierHook,                  // 前端进度推送
                activeAgentPersistenceHook,            // 活跃 agent 记录
                new PendingToolRecoveryHook()          // 断点续跑恢复
            ))
            .planNotebook(planNotebook)
            .toolExecutionConfig(getToolConfig())       // 工具超时 1min/重试 3 次
            .sysPrompt(PromptLoader.loadStatic("itinerary-plan-agent-system.md"))
            .maxIters(MAX_ITERATIONS)                   // 最多 15 轮 ReAct
            .generateOptions(getEnableThinkingGenerateOptions(2048)) // 缓存 + 思考预算
            .build();

    return agent;
}

查审批单 → 查偏好(LTM) → 查政策 → 加载 Skill → 搜交通 → 搜酒店
→ 打分 → plan_itinerary → itinerary_review_agent → 判断修复
→ [可选: 重跑 plan_itinerary → 重审核] → 输出 Markdown

多目标方案 + 审核 + 修复闭环（必走，不可跳过）
严禁跳过工具、直接在文案里虚构"修复版"方案
方案输出后必须停止，等待用户确认（最高优先级约束）

搜索类 skill（如 tuniu-cli）必须在本步骤开始时才加载，
严禁在最初查审批单/常驻地/偏好/政策那一批调用里提前加载。
原因：技能正文加载后若长时间不用会被上下文折叠，
等到真正搜索时说明已丢失。

.longTermMemory(longTermMemory)
.longTermMemoryMode(LongTermMemoryMode.AGENT_CONTROL)