# GoGo 智能差旅助手 — 开发进展文档

# 一、项目概述

GoGo 智能差旅助手是一个基于多 Agent 协作架构的企业级差旅管理系统，通过 AI 智能体为用户提供从差旅申请、审批、行程规划、预订到报销的全流程自动化服务。

项目名称：gogo-agent 版本：1.0.0-SNAPSHOT JDK 版本：Java 21

# 二、技术架构

# 2.1 后端技术栈

# 2.2 前端技术栈

# 2.3 系统架构图

用户 → [React 前端] → SSE/REST → [Spring Boot 后端]
                                        │
                                  ┌─────┴──────┐
                                  │ ChatController │
                                  └─────┬──────┘
                                        │
                              ┌─────────┴─────────┐
                              │ AgentPipelineService │
                              └─────────┬─────────┘
                                        │
              ┌─────────────────────────┼─────────────────────────┐
              │                         │                         │
    QueryRewritingAgent     IntentRecognitionAgent         MasterAgent
                                                               │
                        ┌──────────┬───────────┬───────────────┤───────────────┐
                        │          │           │               │               │
             ItineraryManage  ItineraryPlan  Reimbursement   InfoAgent    BookingAgent
                  Agent           Agent          Agent               
                                   │
                            ItineraryReview   
                                 Agent        

外部能力挂载：
- SubAgentTool：MasterAgent 通过 subAgent 工具调用各子智能体
- SkillBox：tuniu-cli / flight-manager / flyai / rolling-go-hotel / reimbursement
- MCP：weather / orizn-visa
- 百炼长期记忆：MasterAgent / ItineraryPlanAgent AGENT_CONTROL 模式

# 三、核心模块开发进展

# 3.1 Agent 智能体系统

项目采用多 Agent 协作架构。严格意义上的 ReActAgent 共有 9 个；另有 2 个名字带「Agent」后缀的能力（ConversationTitleAgent / QuestionRecommendationAgent）是轻量 LLM 调用服务（@Service + 单次 fastModel.stream），不参与多轮推理与工具调度，详见下表后的说明。

# 9 个 ReActAgent

# 2 个轻量 LLM 服务（仅作 Agent 命名，非 ReActAgent）

提示词文件仍以 *-agent-system.md 命名（历史沿用），但实际实现是单次 LLM 调用的 @Service，不计入上述 ReActAgent 数量。这两个任务均为纯文本生成、无需工具调用、无需多轮推理，套 ReActAgent 包装会带来不必要的开销，因此直接走 fastModel.stream(...)：

Agent 执行流水线（条件式，详见 3.9）：

用户消息 → L1/L2 快速意图识别 →（命中→直接调度 / 未命中→QueryRewritingAgent 改写→完整 L1/L2/L3）→ 单意图直跳子智能体 或 MasterAgent 路由

重要架构决策：

• BaseSubAgent 抽象基类已沉淀统一 Hook 注入、toolExecutionContext、ToolConfig、长期记忆构造等通用能力，避免各 Agent 重复实现（BaseSubAgent.java）
• MasterAgent 通过 SubAgentProvider + SubAgentConfig 注册子智能体为可调用的"工具"，配合 forwardEvents(false) 避免子智能体事件冒泡
• BookingAgent 独立为与 ItineraryPlanAgent 平级的 ReActAgent，负责用户确认方案后的实际预订执行

# 3.2 Agent 生命周期 Hook

# 3.3 工具系统

# 通用工具

• UserInteractionTools — Human-in-the-Loop 主动提问（支持 text/select/multi_select/confirm/form/date/number 等 UI 类型）
• PolicyTools — 差旅政策精确查询（querytravelpolicy / checktravelpolicy）
• DestinationLiveTools — 目的地实时天气/新闻（已注册到 TOOLCIRCUITBREAKER_GROUP）
• QueryUserInfoTools — 用户常驻城市/档案/偏好查询
• InfoQueryTools — 通用信息检索
• ApiKeyTools — 统一 API_KEY 入口（含 tuniu-cli 凭证管理）
• ~~DestinationInfoTools~~ — ~~目的地信息查询~~ （已删除，景点查询改为通过 Knowledge 直出 Bean + RAGMode.AGENTIC）
• ~~UserPreferenceTools~~ — ~~用户偏好读取与记录~~ （已移除，改为通过百炼长期记忆 recordtomemory / retrievefrommemory 管理）

# 差旅单工具

• TravelOrderWriteTools — 差旅单 CRUD 操作（创建/提交审批/修改/取消）
• TravelOrderReadTools — 差旅单查询
• CloneItineraryTools — 行程复制
• TravelOrderConflictTools — 差旅单冲突检测（checktravelorder_conflicts：时间重叠 + 跨城交通衔接合理性，配合 CityTransitTimeService 城市间通行时长推断）

# 规划工具

• ItineraryReviewTools — 行程方案审核工具集
• ItineraryPlannerTool — 往返行程规划客观计算引擎（plan_roundtrip：去×住×返组合 / 时间价格归一化 / policy 软约束 / 偏好分合成，输出 4 类代表方案；由原 roundtrip-planner Python skill 平移为进程内 @Tool，去掉 python3/shell 依赖）

# 预订工具

• BookingReadTools — 外部预订记录查询（querybookingrecord，按 userId 租户隔离，支持按单号 / 业务类型 / 状态过滤）
• BookingWriteTools — 预订写操作（取消预订等）

# 3.4 Skill 外部能力

tuniu-cli 已统一整合 tuniu-flight / tuniu-hotel / tuniu-ticket / tuniu-train / tuniu-cruise 等单独服务，优先使用。 原 travel-planner / roundtrip-planner 行程优化 skill 已下沉为进程内 Java 工具 RoundtripPlannerTool（plan_roundtrip），不再以 Python skill 形式存在。

# 3.5 RAG 知识库

RAG 中间层（Knowledge/GenericRAGHook）已删除，Knowledge 改为直出 Spring Bean，由 InfoAgent 链上直接 .knowledge(...) 注入。

# 3.6 前端系统

前端通信方式：SSE（Server-Sent Events）实时推送，支持以下事件类型：

• message — Agent 文本回复（流式）
• thinking — Agent 思考过程
• progress — 执行进度步骤
• travel_data — 搜索结果数据（酒店/机票/火车票）
• plan_update — 任务计划变化
• user_interaction — 用户交互请求
• suggestions — 推荐问题
• agent-switch — 当前 Agent 切换
• interrupted — 中断通知
• done — 完成信号

# 3.7 业务模块

# 3.8 基础设施能力

• 集群支持：通过 Redis Pub/Sub 实现跨节点 Agent 中断广播（✅已完成）
• 会话持久化：AgentScope MysqlSession 存储多轮对话历史（✅已完成）
• 优雅中断：支持用户"停止生成"操作，Agent 可在任意 ReAct 循环中被安全终止（✅已完成）
• Tool Suspend/Resume：Human-in-the-Loop 支持，Agent 暂停等待用户输入后继续执行（✅已完成）
• PlanNotebook：任务规划可视化，前端实时展示子任务进度（✅已完成）
• ThreadLocal 传播：TransmittableThreadLocal 解决 Reactor 线程切换时上下文丢失（✅已完成）
• 工具级熔断：ToolCircuitBreakerHook 实现熔断/半开/关闭三态，支持指数退避与显式工具组关闭（✅已完成）
• 百炼长期记忆：MasterAgent/ItineraryPlanAgent 启用 AGENTCONTROL 模式，系统自动注册 recordtomemory / retrievefrom_memory（✅已完成）
• 请求级记忆内容缓存：当前请求内重复 retrievefrommemory 命中缓存，避免重复 LLM 调用（✅已完成）
• rgh 用户隔离：rolling-go-hotel Skill 通过 RghUserIsolationHook + RghTokenStore 实现多用户登录态隔离（✅已完成）
• 行程冲突检测：TravelOrderConflictTools 检测同一员工时间重叠（同城重复/跨城物理不可能）与跨城交通衔接合理性，分 HIGH/MEDIUM/LOW 三级输出（✅已完成）
• 行程智能优化：ItineraryPlannerTool（plan_roundtrip）采用双轨评分（LLM 软判断偏好分 + 工具硬指标加权融合），在时间/价格/偏好多目标间权衡并给出 4 类代表方案对比；已由原 roundtrip-planner Python skill 平移为进程内 Java @Tool，去掉 python3/shell 依赖（✅已完成）
• 外部预订记录管理：BookingPersistenceHook 监听 tuniu 下单/取消 CLI 结果，解析外部单号与状态写入 booking_record（对 LLM 透明）；BookingReadTools 供用户按租户隔离查询（✅已完成）
• 上下文 token 优化：CliResultCompressHook（MCP/CLI 结果去重压缩）+ SkillContentCollapseHook（历史技能正文折叠）显著降低多轮 reasoning 的 LLM 输入 token（✅已完成）
• 全链路敏感信息脱敏：SensitiveMasker 基于 houbb sensitive 框架，对日志（SensitiveMaskingConverter）与前端返回中的手机号/身份证/银行卡/邮箱/API Key/密钥键值对自动脱敏（✅已完成）
• 依赖注入规范统一：全局 33 个 Spring Bean 统一从构造器注入改为字段注入（@Autowired/@Value/@Qualifier），含构造逻辑/副作用的下沉到 @PostConstruct（✅已完成）
• 意图种子语料外置：L2 向量库种子语料从硬编码迁移至 intent-seed.yml，经 IntentSeedExamplesProperties 绑定，与 L1 规则分层去重（✅已完成）
• 动态时间注入与百炼缓存：DynamicTimeInjectionHook 在每轮 LLM 推理前向 inputMessages 插入当前时间 system 消息，保持主 system prompt 前缀稳定，利用百炼隐式缓存降低 LLM 调用成本（✅已完成）

# 3.9 意图识别与查询重写优化

针对「每次对话都要跑 QueryRewriting + IntentRecognition + MasterAgent 三次 LLM」的高延迟高成本问题，做了分层短路 + 条件触发 + 单意图直跳三项优化。

# 三层意图识别（L1 → L2 → L3）

由 IntentRecognitionRouter 编排，命中即短路，尽量绕开大模型：

• IntentRecognitionAgent 合并了「工厂配置 + Agent 实现」，@Scope("prototype") 保证每个 session 独立实例、中断状态互不污染。
• 三层结果统一为 IntentRecognitionResult（标注来源 RULE/VECTOR/LLM 与置信度），包装成与 LLM 输出同构的 JSON，下游 MasterAgent/流水线零改动。
• L2 种子语料外置 intent-seed.yml，刻意剔除 L1 能命中的表达（避免冗余），由 IntentRouterSeedExamplesTest 离线校验 L1/L2 不重叠。

# 查询重写条件触发 + 单意图直跳

AgentPipelineService 把「查询重写」从必经步骤改为「仅在 L1/L2 未命中时才触发」的条件步骤：

用户消息
  │
  ├─ 用原始问题跑 L1/L2 快速识别（不触发 L3）
  │     │
  │     ├─ 命中 ─► 跳过查询重写，直接调度
  │     │
  │     └─ 未命中 ─► QueryRewritingAgent 改写 ─► 重走完整 L1/L2/L3 ─► 调度
  │
  └─ 调度决策：
        单意图 + 高置信 + 命中子智能体白名单 ─► 直跳对应子智能体（跳过 MasterAgent）
        否则 ─► 走 MasterAgent 路由

• 省一次改写 LLM：高频、表达清晰的请求（L1/L2 直接命中）完全跳过 QueryRewritingAgent。
• 省一次 MasterAgent 推理：单意图高置信直跳子智能体，节省 1-3 秒额外延迟与一次模型调用；仅多意图/低置信/需澄清的请求才付出 MasterAgent 路由代价。
• continuation 场景另有 executeFromIntentRecognition（跳过改写）/ executeMasterAgentDirectly（跳过改写+识别）两条快捷入口。

# 四、数据库设计（已完成）

# 五、已完成的关键特性

1. 多 Agent 协作流水线：QueryRewriting → IntentRecognition → Master → SubAgents 三级串行流水线
2. 多意图支持：单次用户输入可识别并按顺序处理多个意图
3. Human-in-the-Loop：Agent 可通过结构化 UI 向用户主动提问并暂停等待
4. 实时进度推送：通过 SSE 将 Agent 思考过程、工具调用、搜索结果实时展示给用户
5. 搜索结果可视化：机票/火车票/酒店搜索结果以卡片形式展示，支持多数据源（tuniu-cli / flight-manager / flyai / rolling-go-hotel）格式归一化
6. 差旅政策合规检查：基于职级和城市等级的自动预算与舱位限制；InfoAgent 实现「RAG 通道（语义问答）+ PolicyTools 通道（精确身份绑定）」双通道决策
7. 百炼长期记忆：通过 AGENT_CONTROL 模式自动注册记忆工具，MasterAgent/ItineraryPlanAgent 主动召回差旅偏好
8. 请求级记忆内容缓存：当前请求生命周期内 retrievefrommemory 结果缓存，避免重复 LLM 调用
9. 工具级熔断：ToolCircuitBreakerHook 实现工具维度的熔断/半开/关闭，半开期失败显式关闭工具组
10. rgh 多用户隔离：rolling-go-hotel Skill 通过 Hook + TokenStore 隔离多用户登录态
11. 对话历史持久化：完整的会话管理、历史消息存储与恢复（含 progress / thinkingByAgent / planTasks / travelData / timeline 等结构化扩展）
12. 集群部署支持：Redis 中断广播 + 跨节点会话恢复
13. 自动会话标题生成：由 ConversationTitleService 在独立线程池 titleTaskExecutor 异步生成对话标题（轻量 LLM 服务，非 ReActAgent）
14. 时间轴对话展示：前端对话 UI 重构为按执行顺序的时间轴流式展示
15. 推荐问题按场景化使用：助手抛出澄清/选择题时禁止硬塞"确定/确认"，等待用户整体确认/修改时才优先用快速操作关键词
16. 行程冲突检测：提交/修改差旅单时自动检测与已有生效单的时间重叠与跨城交通衔接冲突，分级告警供 LLM 决策
17. 行程智能优化：ItineraryPlannerTool（plan_roundtrip）双轨评分（LLM 软判断偏好分 + 工具硬指标），多目标权衡输出 4 类代表方案对比；由 Python skill 平移为进程内 Java @Tool
18. 全链路敏感信息脱敏：基于 houbb sensitive 框架，日志与前端输出中的身份证/手机号/银行卡/邮箱/密钥自动脱敏
19. 依赖注入规范统一：全局 Spring Bean 由构造器注入统一改为字段注入，副作用下沉 @PostConstruct
20. 意图识别与查询重写优化：L1/L2/L3 三层分层短路 + 查询重写条件触发 + 单意图高置信直跳子智能体，高频请求可省去改写与 MasterAgent 两次 LLM 调用（详见 3.9）
21. 外部预订记录管理：BookingPersistenceHook 自动将 tuniu 下单/取消结果落库 booking_record，BookingReadTools 供用户按租户隔离查询预订
22. 上下文 token 优化：MCP/CLI 结果去重压缩（CliResultCompressHook）+ 历史技能正文折叠（SkillContentCollapseHook），压降多轮对话的 LLM 输入 token

# 六、项目统计

• 后端 Java 文件：144 个（src/main）
• 代码规模：后端 Java 约 19,532 行（src/main）+ 测试约 359 行；前端 TS/TSX 约 5,076 行；Agent Prompts 1,137 行；YAML 配置 291 行
• ReActAgent 智能体：9 个（新增 BookingAgent 预订执行）
• 轻量 LLM 服务（Agent 命名）：2 个（ConversationTitleService / QuestionRecommendationService，仅作 Agent 命名，非 ReActAgent）
• Agent 工具：15 个工具类（含 TravelOrderConflictTools 行程冲突检测、ItineraryPlannerTool 往返规划、BookingReadTools 预订查询、BookingWriteTools 预订写入）
• Skill 外部能力：5 个（travel-planner 已下沉为 Java 工具 ItineraryPlannerTool）
• 生命周期 Hook：14 个有效装配（新增 DynamicTimeInjectionHook）
• RAG 知识库：3 个（GENERIC + AGENTIC 双模式）
• 前端组件：12 个核心组件（新增 AdminApprovalPage / BookingResultCard / MyTravelPage / PreferencePage）
• 数据库表：11 张
• System Prompt：11 个 Markdown 文件（新增 booking-agent-system.md）

# 七、todo

1、通过A2A接入发票识别、做自动报销 2、基于AgentScope-Java 2.0做重构及改造 3、可观测性