行程审核智能体的功能介绍及开发

// ItineraryPlanAgent.java —— 把审核子智能体注册成一把工具
toolkit.registration()
        .subAgent((SubAgentProvider<ReActAgent>) () ->
                        applicationContext.getBean("itineraryReviewAgent", ReActAgent.class), // 懒加载，每次取全新 prototype 实例
                SubAgentConfig.builder()
                        .toolName("itinerary_review_agent")
                        .description("委托行程审核子智能体对行程方案进行五维结构化审核（完整性/时间/出发目的地/预算/偏好/路径），" +
                                     "返回审核报告与具体修改建议。参数：message（包含审核所需的上下文说明，如政策/偏好）。")
                        .forwardEvents(false)
                        .build())
        .apply();

@Configuration("itineraryReviewAgentConfiguration")
public class ItineraryReviewAgent extends BaseSubAgent {

    /** 行程审核 Agent 最大推理迭代次数 */
    private static final int MAX_ITERATIONS = 8;

    @Autowired
    protected ItineraryReviewTools itineraryReviewTools;

    @Bean(name = "itineraryReviewAgent")
    @Scope("prototype")                              // 每次请求都拿一个全新实例，避免会话串味
    public ReActAgent build() {
        Toolkit toolkit = new Toolkit();
        // 只挂两把工具：政策查询 + 五维结构化校验
        toolkit.registration().tool(policyTools).apply();          // query_travel_policy / check_travel_policy
        toolkit.registration().tool(itineraryReviewTools).apply(); // review_planner_result

        ReActAgent agent = ReActAgent.builder()
                .name("ItineraryReviewAgent")
                .description("行程方案审核专家，对规划好的行程进行五维结构化审核（完整性/时间/出发目的地/预算/路径），输出审核报告和具体修改建议")
                // 规划和审核使用不同模型 —— 审核用更便宜的 GLM-5.1
                .model(stableModel)
                .toolkit(toolkit)
                .toolExecutionContext(createToolCtx())             // 从 ThreadLocal 注入当前用户会话上下文
                // 自动压缩/卸载大工具结果与历史，抑制多轮输入 token 膨胀（需搭配 AutoContextHook）
                .memory(AgentMemoryFactory.create(stableModel))
                .longTermMemory(createLongTermMemory(memoryFactory))
                .longTermMemoryMode(LongTermMemoryMode.AGENT_CONTROL)
                .hooks(List.of(new AutoContextHook(), executionLoggerHook, progressNotifierHook))
                .sysPrompt(PromptLoader.load("itinerary-review-agent-system.md"))
                .toolExecutionConfig(getToolConfig())              // 超时 1min，失败重试 3 次（仅 IOException）
                .maxIters(MAX_ITERATIONS)
                .build();

        return agent;
    }
}

@Tool(
        name = "review_planner_result",
        description = "从行程规划工具（plan_itinerary）存入 Redis 的规划结果中读取多方案并批量结构化审核" +
                      "（五维：行程完整性/时间/出发目的地/预算/路径，不含个人偏好）。" +
                      "规划结果按用户隔离存储在 Redis 中，无需也无法传入存储位置。" +
                      "工具直接从 Redis 读取解析，无需把庞大的方案 JSON 作为参数传入，避免上下文膨胀与 JSON 解析失败。" +
                      "返回 reviews 数组（每项含 proposal_id、overall_status、checks、issues、suggestions）、best_proposal_id 与 summary。"
)
public String reviewPlannerResult(
        @ToolParam(name = "policy",
                description = "差旅政策JSON（hotel_limit_per_night / transport_class / total_budget_limit 等）",
                required = false)
        String policy,
        AgentSessionContext sessionCtx) {

        String userId = sessionCtx != null ? sessionCtx.getUserId() : null;
        String redisKey = ItineraryPlanStore.keyOf(userId);       // 按用户隔离的 Redis Key
        // ... 从 Redis 读取 plan_itinerary 写入的方案 JSON ...
        String content = itineraryPlanStore.load(userId);
        // content 为 null / 读取失败 → 返回结构化 fail，提示"确认 plan_itinerary 已成功执行"
}

private JSONObject reviewSingle(JSONObject itineraryJson, JSONObject policyJson) {
    List<CheckResult> checks = new ArrayList<>();
    List<String> issues = new ArrayList<>();
    List<String> suggestions = new ArrayList<>();

    checkCompleteness(itineraryJson, checks, issues, suggestions);      // 1. 行程完整性
    checkTimingValidity(itineraryJson, checks, issues, suggestions);    // 2. 时间合理性
    checkOriginDestination(itineraryJson, checks, issues, suggestions); // 3. 出发地/目的地核实
    checkBudgetCompliance(itineraryJson, policyJson, checks, issues, suggestions); // 4. 预算合规
    checkRouteRationality(itineraryJson, checks, issues, suggestions);  // 5. 路径合理性

    String overallStatus = computeOverallStatus(checks);
    // 组装成 {overall_status, checks[], issues[], suggestions[]}
}

if (isBlank(itinerary.getString("origin")))       problems.add("出发地（origin）未填写");
// ...
// 最后一天不需要住宿（当天返回）
if (i < days.size() - 1 && !day.containsKey("hotel")) nightsWithoutHotel++;

private static final int MIN_DOMESTIC_TRANSFER_MINUTES = 60;  // 国内中转
private static final int MIN_INTL_TRANSFER_MINUTES = 90;      // 国际中转
private static final int MIN_ARRIVAL_BUFFER_MINUTES = 60;     // 到达→首个活动
private static final int MIN_RETURN_BUFFER_MINUTES = 60;      // 末个活动→返程出发

private boolean cityMatches(String actual, String approved) {
    if (approved == null || actual == null) return true; // 无审批信息时不做校验
    return actual.contains(approved) || approved.contains(actual);
}

if (policy.isEmpty()) {
    checks.add(new CheckResult("预算合规性", "warning", "未提供差旅政策，跳过预算校验"));
    suggestions.add("建议调用 check_travel_policy 获取差旅政策后再做预算校验");
    return;
}
// 逐晚酒店超限 & 总价超批准金额 → 记入 overBudget

private static final double MAX_HOTEL_DISTANCE_KM = 15.0;
// checkCityBacktrack：citySequence.get(i).equals(citySequence.get(i + 2)) → 折返
// checkHotelDistance：distance_to_main_venue_km > 15.0 → 建议选更近住宿

private String computeOverallStatus(List<CheckResult> checks) {
    boolean hasFail = checks.stream().anyMatch(c -> "fail".equals(c.status()));
    boolean hasWarning = checks.stream().anyMatch(c -> "warning".equals(c.status()));
    if (hasFail) return "fail";
    return hasWarning ? "warning" : "pass";
}

private int computeEffectiveScore(String status, JSONObject plannerScores) {
    double weight = switch (status) {
        case "pass" -> WEIGHT_PASS;      // 1.0
        case "warning" -> WEIGHT_WARNING;// 0.7
        default -> WEIGHT_FAIL;          // 0.0
    };
    double base = (plannerScores != null && plannerScores.getDouble("overall") != null)
            ? plannerScores.getDouble("overall") : 0.0;
    return (int) Math.round(base * weight);
}