多维 AI 智能推荐 Agent 系统技术文档

版本号: v4.2 开发人: 尘小风 当前状态: 本地开发已完成

0.写在前面的话

记录第一个 100% 纯原创项目开发完成（借助Gemini辅助开发）。

First Question：为什么会想到做这样一个项目？

实际是纯粹是某天凌晨失眠睡不着，胡思乱想，突然冒出来的想法。

当前的推荐算法主要借助协同过滤与简单的用户标签，有些会结合一些图算法，但是总体而言，缺乏灵动的动态更新、自我迭代的能力。

而大模型本身就以深度语义理解为主，能够非常好的捕捉用户的深层需求，如果可以再加上用户的一些个性、行为特征，是不是能够实现更好的推荐效果呢？

Second Question：项目的核心定位

一句话概括就是：是一个可以根据用户的动态画像，结合多模态的输入，综合分析用户的深层需求，从而为用户推荐最适合的 商品/视频 的智能推荐系统。

Third Question：最初的实现构想

最初构想的实现其实很简单，总体的逻辑就是：先让用户回答设计好的问卷问题，然后通过调用大模型，来根据用户答案建立起他的用户画像；之后将用户画像和用户的需求一同输入给另一个Agent，作用是根据需求，提取用户画像中相关的关键词，共同构建用于商品/视频检索的关键词，然后通过一个编写好的爬虫工具，根据关键词去对应的平台进行信息检索，把最前面的几条结果进行返回。

Last Question：系统最终的核心模块

随着项目不断迭代（一共经过四次大版本的迭代，和中间N次小版本的优化），不断的在系统中加入了新的角色和功能：

1. 用户画像Agent，用不同的Prompt和参数配置去调用不同的模型去生成A/B两版画像和关键词标签（带权重），并允许用户对生成的画像进行反馈和再生成，最终实现最符合用户的“数字孪生”；
2. 可同时接收文本和图像双模态输入，具有自动的需求冲突检测功能、并允许用户进一步澄清需求的核心关键词提取Agent；
3. 具有对爬虫检索结果进行多重漏斗筛选的FilterAgent（用户需求中的硬性要求剔除 -> 根据检索结果与用户需求的相关性进行粗筛的embedding模型 -> 对粗筛结果进行进一步细排的LLM），同时还具有多重重试/兜底机制，确保筛选可靠性；
4. 接受用户对推荐结果反馈的自优化Agent，根据不同反馈情况去分别执行：用户画像关键词权重调节、用户画像关键词替换、画像重生成逻辑。
5. 多节点统一调度管理的中心编排器。

1. 项目概览

1.1 项目定位

本项目是一个基于 Multi-Agent（多智能体）架构 的工业级智能推荐系统。它突破了传统推荐系统仅依赖协同过滤或简单标签匹配的限制，通过构建用户的“数字孪生”画像，结合大语言模型（LLM）的深度语义理解与多模态（视觉+文本）分析能力，实现了跨平台（电商+视频）的实时精准检索与推荐。

项目概述图：

1.2 现状与痛点

1.3 核心建设目标

1. 构建深度用户认知模型：通过多轮问卷与 A/B Test 机制，生成具备心理洞察力的动态用户画像。
2. 实现复杂意图理解：解决“用户描述模糊”与“视觉/文本意图冲突”的搜索难题。
3. 全链路闭环优化：建立“推荐-反馈-修正”的自动化闭环，系统能随用户交互产生自我进化。

1.4 适用业务场景

• 智能导购：根据用户审美、预算、消费观进行全网电商（如苏宁）商品比价与推荐。
• 内容分发：基于用户兴趣图谱与当前情绪，推荐长/短视频（如 Bilibili）。
• 多模态检索：支持“拍图搜同款”或“拍图搜教程”，并自动纠正视觉与文本的冲突。

2. 核心功能

2.1 动态数字画像构建

• 业务价值：将静态的用户标签转化为具备权重的动态语义网络。
• 操作流程：用户注册 -> 完成 23 题心理问卷 -> 后端双模型 (DeepSeek/Qwen) 并行生成 A/B 两个画像版本 -> 用户选择激活 -> 生成 UserProfile。
• 核心支撑：
  • 后端: 使用 CompletableFuture 并行调用不同 Prompt (gen-a.st, gen-b.st) 生成候选画像。
  • 前端 : 展示 Deep Insight 与 Key Factors，支持多轮次迭代与用户澄清。

2.2 多模态智能检索

• 业务价值：支持“图文混排”输入，解决单一文本搜索的局限性。
• 核心支撑：
  • VisualAgent: 调用 Qwen-VL 模型解析图片主体与风格。
  • KeywordAgent: 执行“文本意图识别”与“视觉冲突检测”，融合生成最终搜索词。

2.3 实时跨平台爬虫与精排

• 业务价值：获取全网最新实时数据，而非依赖滞后的离线库。
• 核心代码支撑：
  • SuningCommodityTool / BilibiliVideoTool: 基于 Selenium 的无头浏览器实时抓取。
  • FilterAgent: 实现“硬性规则剔除” + “余弦相似度初筛” + “LLM 语义精排”的三阶段漏斗过滤。

2.4 负反馈自我修正机制

• 业务价值：系统能够理解用户的“不喜欢”，并自动调整画像权重。
• 核心代码支撑：
  • OptimizationAgent: 监听 feedback.task.queue，对负样本进行统计。
  • ProfileAgent: 当负样本达到阈值或某个关键词标签低于阈值时，自动触发 Prompt 修改画像关键词。

3. 项目亮点

3.1 架构设计：Agent Orchestration 编排模式

不同于松散的 Agent 交互，本项目采用了集中式的编排器模式。AgentOrchestratorService 作为“大脑”，严格控制任务流转（Keyword -> Filter -> Feedback），并集成了 异常熔断 与 自动重试 机制。

• 佐证代码: 完整的 try-catch-recovery 链路，包含从正常流程降级到 Keyword Regenerate 再降级到 Force Fallback 的三级防护。

3.2 业务创新：多模态冲突检测与融合

系统不仅是简单的图文拼接，还引入了“冲突检测”机制。当用户文本意图（如“洗面奶”）与图片内容（如“手机”）发生逻辑冲突时，Agent 会自动判定并触发澄清流程或按规则融合。

• 佐证代码: KeywordAgent 中的 checkConflict 方法，调用 conflict-check.st Prompt 进行逻辑判定。

3.3 性能优化：Embedding 向量缓存与延时双删

• 向量缓存: EmbeddingService 使用 Redis 缓存文本的向量结果 (CACHE:VECTOR:{MD5})，且支持批量切片调用 API，大幅降低 Token 消耗与延迟。
• 数据一致性: UserProfileService 实现了“数据库写 -> 缓存删 -> 延时 -> 缓存再删”的延时双删策略，确保高并发下画像更新的一致性。

3.4 交互体验：全异步任务轮询

前端采用长轮询（Polling）机制配合后端的 RabbitMQ 异步任务处理，彻底解决了大模型生成耗时长导致的 HTTP 超时问题，同时支持实时进度反馈。

• 佐证代码: 前端 App.jsx 中的 startTaskPolling 与后端 TaskService 的状态管理。

4. Agent 深度解析

4.1 单个 Agent 解析

(1) ProfileAgent (画像构建智能体)

• 核心职责: 负责用户数字孪生模型的创建、迭代与维护。
• 关键功能:
  • A/B 差异化生成: 通过 generateCandidates 方法并行调用 DeepSeek (Prompt A: 激进/心理侧写) 和 Qwen (Prompt B: 保守/事实标签)，生成两种风格迥异的画像供用户选择，解决单一模型偏差问题。
  • 画像激活: 处理用户选择 (activateProfile)，将候选画像 (ProfileCandidate) 转化为正式的用户配置 (UserProfile)。
  • 负样本修正: 提供 refineByNegative 能力。当收到优化指令时，利用 refine.st Prompt 分析负面关键词（如“性价比”），推测用户真实意图（如“可能偏向高品质”），并生成替代词。
• 输入输出: 输入问卷答案或负面词；输出结构化的 ProfileCandidate 对象或更新后的权重 Map。

(2) KeywordAgent (搜索意图智能体)

• 核心职责: 作为搜索入口，负责理解用户“想搜什么”，并结合“用户是谁”进行查询重写。
• 关键功能:
  • 多模态融合: process 方法首先并行调用文本分析 (analyzeText) 和视觉分析 (VisualAgent)。
  • 冲突检测: 在融合阶段，调用 conflict-check.st 判定文本与图片是否存在逻辑冲突（如文搜“洗面奶”图是“手机”）。若冲突，抛出 CLARIFICATION_NEEDED 异常，中断流程并请求用户澄清。
  • 画像混合 (Profile Mixing): 根据 mixing.st，将用户画像中的高权重标签（如“极简风”、“极客”）按照配置比例 (profileMixRatio) 注入到搜索关键词中，实现个性化搜索。
  • 自我反思: 提供 regenerate 方法。当搜索无结果时，Agent 会反思关键词是否过于生僻或具体，并重新生成更通用的关键词。
• 依赖: 强依赖 VisualAgent 进行图片解析，依赖 UserProfileService 获取画像数据。

(3) FilterAgent (过滤与精排智能体)

• 核心职责: 执行实际的数据获取与清洗，充当“漏斗”角色。
• 关键功能:
  • 工具调度: 根据搜索类型 (COMMODITY/VIDEO) 动态选择 SuningCommodityTool 或 BilibiliVideoTool 进行爬虫检索。
  • 约束过滤: 如果 KeywordAgent 提取了显性约束（如价格千元以内），优先执行硬性过滤 (processWithConstraints)。
  • 向量初筛: 调用 CosineSimilarityTool （内部借助embedding模型）计算 Query 向量与 Title 向量的相似度，从 Top 30 中筛选出 Top 12。
  • LLM 语义精排: 调用 rank.st，让大模型扮演选品专家，综合考虑性价比、风格、评论氛围等非结构化因素，输出最终 Top 6。
  • “漏斗式”兜底机制：
    • Level 1 (常规)：全量关键词检索 -> LLM 精排。若失败（LLM 认为均不相关），在 FilterAgent 内部进行“减词重试”。
    • Level 2 (认知重构)：若 Level 1 仍未返回规定数量的结果，Orchestrator 调度 KeywordAgent 进行“反思与重生成”，使用新关键词再次检索。
    • Level 3 (强制兜底)：若 Level 2 仍失败，Orchestrator 强制命令 FilterAgent 放弃 LLM 过滤，直接降级为纯数学逻辑（余弦相似度）返回 Top 6，确保系统高可用。

(4) OptimizationAgent (反馈闭环智能体)

• 核心职责: 系统的“进化引擎”，基于用户行为调整画像权重。
• 关键功能:
  • 权重自适应: processFeedback 方法接收用户的点赞/点踩数据。命中画像关键词时，动态调整权重（步长 ±0.05）。
  • 负样本累积: 维护一个计数器。当某个关键词（如“复古”）在短时间内被点踩超过阈值（默认 3 次）时，判定该标签与用户认知不符。
  • 触发修正: 主动调用 ProfileAgent.refineByNegative() 发起画像重构，形成“反馈->修正”的闭环。

(5) VisualAgent (视觉感知智能体)

• 核心职责: 系统的“眼睛”，负责将非结构化的图片转化为结构化的文本描述。
• 关键功能:
  • 场景化解析: 针对电商场景，提取“品类+品牌+核心卖点”；针对视频场景，提取“主体+氛围风格”。
  • 模型支撑: 底层对接阿里云 Qwen-VL 多模态大模型。

4.2 多 Agent 协同解析

系统采用 集中式编排 (Orchestration) 模式，由 AgentOrchestratorService 统一调度，而非 Agent 之间直接点对点调用。

协同流程详解：

1. 任务启动: Controller 接收请求 -> 生成 TaskID -> 推送 MQ。
2. Orchestrator 接管: Listener 消费消息，唤醒 Orchestrator。
3. 阶段一：意图理解:
   • Orchestrator 调用 KeywordAgent。
   • KeywordAgent 内部同步调用 VisualAgent 解析图片。
   • KeywordAgent 拉取 UserProfile 进行关键词混合。
   • 异常分支: 若发现冲突，Orchestrator 捕获 CLARIFICATION_NEEDED，直接终止并通知前端。
4. 阶段二：执行与过滤:
   • Orchestrator 将混合后的关键词传给 FilterAgent。
   • FilterAgent 调起爬虫工具 -> 向量服务 -> LLM 精排。
   • 重试分支: 若 FilterAgent 返回空，Orchestrator 指挥 KeywordAgent 执行 regenerate（自我反思），获取新词后再次调用 FilterAgent。
   • 兜底分支: 若重试仍为空，Orchestrator 指挥 FilterAgent 执行 executeForceFallback。

1. 阶段三：反馈进化 (异步):
   • 用户前端操作反馈 -> 推送 MQ。
   • FeedbackTaskListener 唤醒 OptimizationAgent。
   • OptimizationAgent 更新权重 -> 若达阈值，调用 ProfileAgent 修正画像。

场景举例：用户上传一张复古台灯图片，并输入“想要这个，但要便宜点”

1. 触发阶段: AgentController 接收请求，生成 taskId，通过 TaskService 将任务推入 RabbitMQ search.queue。
2. 调度阶段: SearchTaskListener 消费消息，唤醒 AgentOrchestratorService。
3. 协同执行流:
   • Step 1 (意图识别): Orchestrator 调用 KeywordAgent。
     • VisualAgent 识别图片为“复古 绿色 玻璃 台灯”。
     • KeywordAgent 识别文本约束“便宜点” -> 提取 constraint_price (低价策略)。
     • KeywordAgent 融合画像（假设用户画像有“极简”），生成关键词列表：["复古台灯", "绿色玻璃", "平价", "极简"]。
   • Step 2 (执行检索): Orchestrator 调用 FilterAgent。
     • FilterAgent 调用 SuningTool 爬取数据。
     • 应用 constraint_price 过滤掉高价商品。
     • 利用 Embedding + LLM 选出最符合“复古且平价”的商品。
   • Step 3 (异常容错):
     • 如果 FilterAgent 返回结果为空，Orchestrator 捕获异常，调用 KeywordAgent.regenerate() 尝试生成更宽泛的关键词（如去掉“绿色”），再次调用 FilterAgent。
4. 结果交付: 结果写入 MySQL search_histories，前端轮询到 COMPLETED 状态展示结果。

5. 技术架构

5.1 后端架构 (Spring Boot)

• 分层设计:
  • Controller Layer: AgentController (V3 API), AuthController (V2 API)。
  • Service Layer: AgentOrchestratorService (核心调度), UserProfileService (画像管理), TaskService (任务状态)。
  • Agent Layer: 封装具体智能体逻辑 (com.example.recommendagents.agent.*)。
  • Tool Layer: 封装基础设施 (Selenium, Embedding, Redis)。
• 数据存储:
  • MySQL: 存储用户 (users)、画像 (user_profiles)、历史记录 (search_histories)、日志 (agent_action_logs)。
  • Redis: 缓存画像 (CACHE:PROFILE:*)、向量 (CACHE:VECTOR:*)、搜索结果。
• 中间件: RabbitMQ (解耦耗时任务), Spring Security + JWT (无状态认证)。

5.2 前端架构 (React + Vite)

• 工程结构:
  • views/: 页面级组件 (Dashboard, Recommend, Profile)。
  • components/: 通用组件 (LoadingOverlay)。
  • api/: API 统一配置与拦截。
• 状态管理: 使用 React Hooks (useState, useEffect) 结合 localStorage 进行轻量级状态管理。
• 交互逻辑: 采用 Framer Motion 实现流畅的转场动画，利用 Polling (setInterval) 实现对后端异步任务的准实时响应。

5.3 基础设施与数据持久化

本系统强依赖 Redis、MySQL 和 RabbitMQ 构成了稳健的工业级底座，具体作用如下：

(1) Redis (高性能缓存与临时状态)

• 画像缓存 (CACHE:PROFILE:{UserId}):
  • 作用: UserProfileService 使用 Redis 缓存用户的活跃画像。
  • 策略: 采用 Cache-Aside 模式配合 延时双删 (Delayed Double Deletion) 策略。当画像更新时，先删缓存 -> 写库 -> 延时500ms -> 再删缓存，确保高并发下的数据一致性。
• 向量缓存 (CACHE:VECTOR:{MD5}):
  • 作用: EmbeddingService 缓存文本 Embedding 结果（有效期 7 天）。
  • 价值: 避免对相同文本（如高频关键词）重复调用收费的 Embedding API，显著降低成本并提升检索速度。
• 搜索结果缓存 (CACHE:SEARCH:{Type}:{QueryHash}):
  • 作用: 缓存特定 Query 的最终搜索结果（有效期 30 分钟）。
  • 价值: 应对短时间内的重复搜索请求，直接返回热数据，减轻爬虫压力。
• 上下文暂存: KeywordAgent 将提取的搜索约束（如价格区间）暂存 Redis，供后续 Agent 读取，实现跨 Agent 状态共享。

(2) MySQL (核心数据持久化)

系统使用 MySQL 存储所有关键业务数据，主要包含以下表结构 (DomainModels.java)：

• users: 存储用户基础认证信息（账号、密码）。
• user_profiles: 存储用户当前激活的画像（JSON 格式权重的关键词）。
• profile_candidates: 存储历史生成的 A/B 测试画像候选集，用于回溯和切换。
• search_histories: 完整记录用户的每一次搜索请求、AI 提取的关键词及最终结果 JSON。这是“未读消息”功能和 Dashboard 历史记录的数据源。
• agent_action_logs: 系统监控表。记录每个 Agent 的执行耗时、Token 消耗、输入输出快照，用于全链路追踪与成本核算。

(3) RabbitMQ (异步解耦与削峰填谷)

• 搜索任务队列 (search.task.queue):
  • 作用: 前端提交搜索请求后，Controller 仅生成 TaskID 并将负载推入此队列，立即返回。
  • 价值: 将耗时极长（爬虫+多轮LLM推理，可能超过30秒）的搜索任务从 HTTP 主线程剥离，防止网关超时，同时支持通过增加消费者实例实现水平扩展。
• 反馈任务队列 (feedback.task.queue):
  • 作用: 用户的点赞/点踩操作推入此队列。
  • 价值: 确保用户的交互操作（高频）不会因为后端的复杂优化计算（低频、耗资源）而感到卡顿，实现“由于反馈”的非阻塞处理。

6. 前端功能展示

6.1 身份认证页

定位: 进入系统的第一道门户，营造极具科技感的“数字身份”创建氛围。

• 视觉设计:
  • 背景: 采用深色玻璃拟态风格，配合动态光影。
  • 动效: 表单区域加载时带有 opacity 和 y 轴位移的淡入动画。
• 核心功能:
  1. 双模切换: 支持“登录”与“注册”模式一键切换。
  2. 即时反馈: 按钮内置 Loader2 旋转动画，防止重复提交。
  3. 键盘交互: 密码框支持回车键 (Enter) 直接触发提交。
• 代码映射: src/views/AuthView.jsx
• 页面展示：

注册与登录：

6.2 系统欢迎页

定位: 系统的 Landing Page，引导用户开启画像构建之旅。

• 布局结构:
  • 中心区: 巨大的 Slogan "多维 AI 智能推荐"，配合 CPU 核心图标。
  • 操作区: 提供“开启画像评测”主按钮（带流光特效）和“返回推荐中心”次级按钮。
• 逻辑细节:
  • 智能判断: 根据 hasProfile 属性动态改变按钮文案（“开启画像评测” vs “重新建立画像”）。
  • 状态保留: 如果用户已有画像，会额外显示“返回推荐中心”入口，避免老用户重复评测。
• 代码映射: src/views/WelcomeView.jsx
• 页面展示：

新用户：

老用户：

6.3 沉浸式心理评测页

定位: 采集用户数据的核心场景，设计上追求极简与专注。

• 功能模块:
  1. 动态进度条: 顶部实时渲染当前进度（如 Rank 1/23），采用渐变色填充。
  2. 问题展示:
     • 显示问题分类（如 Basic, Consumption）与具体题干。
     • 选项卡片化设计，支持 Hover 态高亮与箭头显现。
  3. 自动化流转: 用户点击选项后，自动跳转下一题，无需二次确认，提升填报效率。
  4. 导航控制: 底部提供“上一题”撤回功能（第一题禁用）和“退出”按钮。
• 代码映射: src/views/QuestionnaireView.jsx (依赖 src/data/questions.js)
• 页面展示：

沉浸式测评页面：

6.4 认知对齐与画像确认页

定位: A/B Test 结果展示场，让用户参与到 AI 决策过程中（Human-in-the-loop）。

• 双模型对比展示:
  • Model A (DeepSeek): 蓝色系卡片，侧重深层心理洞察 (Deep Insight)。
  • Model B (Qwen): 紫色系卡片，侧重客观事实标签 (Key Factors)。
• 交互逻辑:
  1. 多轮次导航: 顶部显示 Round X / Total，支持通过左右箭头查看历史生成轮次。
  2. 一键激活: 点击卡片底部的“确认选择此画像”，将临时 Candidate 转化为正式 Profile。
  3. 反思与重生成 (Refine):
     • 提供“都不满意”按钮。
     • 展开输入框，允许用户输入自然语言（如“太激进了，我比较保守”）。
     • 触发后端 ProfileAgent 的修正逻辑，生成下一轮 Candidate。
• 代码映射: src/views/profileCandidateView.jsx
• 页面展示：

生成等待页面：

双画像选择页面：

无满意结果时：

6.5 数字孪生画像详情页

定位: 用户数字身份的完整展示，是推荐系统的“元数据”。

• 可视化呈现:
  • 状态标签: 顶部显示 Profile Active (当前使用) 或 Historical Profile (历史记录)。
  • 核心描述卡片: 左侧大面积展示 AI 生成的 Summary，背景带有动态呼吸光晕。
  • 权重分布图: 右侧列出 weightedKeywords，并通过可视化的进度条展示每个关键词的权重值 (0.0 - 1.0)。
• 操作区:
  • 当前画像: 显示醒目的“进入推荐中心”按钮。
  • 历史画像: 显示“切换至此画像”按钮，支持一键回滚历史版本。
• 代码映射: src/views/ProfileView.jsx
• 页面展示：

用户画像详情页面：

6.6 多模态智能推荐中心

定位: 用户进行搜索与获取推荐的主战场，集成了图文输入与结果反馈。

• 输入区域 (Input Bar):
  • 类型切换: 胶囊式按钮切换 电商 / 视频 模式，切换时带有缩放动画。
  • 多模态输入:
    • 文本框支持自然语言输入。
    • 图片上传: 点击图标上传图片，并在输入框下方显示图片预览缩略图（带删除按钮）。
  • 智能提示: 输入框 Placeholder 根据选择的类型动态变化（如“想买什么？” vs “想看什么？”）。
• 结果展示区 (Result Feed):
  • 瀑布流卡片: 采用 Grid 布局，每张卡片包含标题、描述、价格/时长、来源标签。
  • 来源标识: 显式标注 Suning 或 Bilibili。
  • 新消息提示: 当轮询检测到新结果时，顶部弹出 AI 已为您找到新的推荐结果 Toast 提示。
• 反馈交互 (Feedback Loop):
  • 点赞/点踩: 每个卡片底部提供 ThumbsUp/ThumbsDown 按钮。点击后按钮变色，并异步发送反馈至后端 MQ。
• AI 澄清机制 (Clarification):
  • 当后端检测到意图冲突时，前端会渲染一个橙色警示卡片，显示 AI 的提问，并提供独立的输入框供用户回复补充说明。
• 代码映射: src/views/RecommendView.jsx
• 页面展示：

推荐中心首页：

多模态需求检索：

意图矛盾时的二次确认（比如上传手机图片，文本需求却是买衣服）：

结果推荐页面：

不满意结果反馈：

反馈后画像权重参数自动调整：

6.7 个人数字档案

定位: 系统的个人中心，查看历史轨迹。

• 数据概览:
  • Tab 切换: 在“推荐历史”与“画像记录”之间切换。
  • 红点消除: 当切换到“推荐历史” Tab 时，自动调用 API 消除未读消息红点。
• 列表渲染:
  • 画像列表: 复用卡片样式，展示历史生成的 Summary 和 Round 信息。
  • 搜索历史: 展示查询词、搜索时间、AI 提取的策略关键词 (aiKeywords) 以及简略的搜索结果预览。
• 代码映射: src/views/DashboardView.jsx
• 页面展示：

个人数字档案 - 推荐历史：

个人数字档案 - 画像记录（包含切换画像功能）：

7. 部署与配置

7.1 部署前置条件

• JDK: Java17+
• Node.js: v22+ (用于前端构建)
• Database: MySQL 5.7+
• Cache: Redis 6.0+
• Message Queue: RabbitMQ 3.8+
• Browser: Google Chrome (对应版本的 ChromeDriver，用于 Selenium)

7.2 核心配置文件说明 (application.yml)

• `ai.openai.api-key: DeepSeek API 密钥，用于核心逻辑推理。
• `app.vision.api-key: 阿里云密钥，用于 Text、Qwen-VL 和 Embedding。
• agent.config.filter.crawler: 配置爬虫抓取的最大条数。
• task.queue: 定义 RabbitMQ 的队列名称。

7.3 常见问题排查

• 爬虫失败: 检查服务器是否安装了 Chrome 浏览器，或是否被目标网站反爬（考虑接入代理 IP 池）。
• WebSocket/Polling 跨域: 检查 WebConfig.java 中的 addCorsMappings 配置。
• 任务一直 PROCESSING: 检查 RabbitMQ 消费者监听器是否正常启动 (@RabbitListener)。

8. 后续优化方向

8.1 架构微服务化

• 背景: 当前所有 Agent 跑在同一个 Spring Boot 进程中，爬虫任务易阻塞 CPU。
• 方案: 将 FilterAgent (爬虫) 和 VisualAgent (GPU 密集型) 拆分为独立的微服务，通过 Feign 或 Dubbo 调用。
• 收益: 提升系统吞吐量，故障隔离。

8.2 引入向量数据库

• 背景: 当前使用 Redis 存储向量，无法进行高效的 ANN (近似最近邻) 搜索，只能遍历计算 Cosine。
• 方案: 引入 Milvus 或 Pinecone 替代 Redis 存储向量。
• 收益: 支持百万级数据的毫秒级相似度检索，支持更复杂的语义召回。

8.3 增加数据源

• 背景: 目前仅支持苏宁和 B 站。
• 方案: 扩展 Tool 接口，增加 DouyinTool (抖音)、XiaohongshuTool (小红书) 实现。
• 收益: 覆盖更多生活场景，增强推荐丰富度。