Cloud-Code 小云 Agent 助理 — 后端服务
基于多智能体协作的 AI 对话平台，支持 Skill 工作流、HITL 人工审批、知识库 PDF 入库与检索、长期记忆 / 宠物记忆
🎯 核心特性
#WfAvXIEINvgE text { white-space: pre; }#WfAvXIEINvgE .fb0 { stroke: var(--N900-FG, 0.15); }#WfAvXIEINvgE .fb0 {stroke: rgba(31,35,41, 0.15)}#WfAvXIEINvgE .fx0 { stroke-miterlimit: 10; }#WfAvXIEINvgE .fx0 {stroke-miterlimit: 10}#WfAvXIEINvgE .fa1 { fill: rgb(187, 191, 196); }#WfAvXIEINvgE .fa1 {fill: rgb(187, 191, 196)}#WfAvXIEINvgE .fx1 { font: 400 12px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#WfAvXIEINvgE .fx1 {font-style: normal}#WfAvXIEINvgE .fx2 { text-anchor: middle; }#WfAvXIEINvgE .fx2 {text-anchor: middle}#WfAvXIEINvgE .fx3 { dominant-baseline: central; }#WfAvXIEINvgE .fx3 {dominant-baseline: central}#WfAvXIEINvgE .fx4 { stroke: none; }#WfAvXIEINvgE .fx4 {stroke: none}#WfAvXIEINvgE .fc0 { fill: var(--text-caption); }#WfAvXIEINvgE .fc0 {fill: #646a73}#WfAvXIEINvgE .fa2 { fill: var(--text-link-disabled); }#WfAvXIEINvgE .fa2 {fill: rgb(187, 191, 196)}#WfAvXIEINvgE .fx5 { font: 400 13px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#WfAvXIEINvgE .fx5 {font-style: normal}#WfAvXIEINvgE .fx6 { text-anchor: start; }#WfAvXIEINvgE .fx6 {text-anchor: start}#WfAvXIEINvgE .fx7 { dominant-baseline: alphabetic; }#WfAvXIEINvgE .fx7 {dominant-baseline: alphabetic}#WfAvXIEINvgE .fc1 { fill: rgb(0, 0, 0); }#WfAvXIEINvgE .fc1 {fill: rgb(0, 0, 0)}#WfAvXIEINvgE .fx8 { font: 400 13px LarkHackSafariFont, LarkEmojiFont, ui-monospace, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Helvetica, "Noto Sans", Tahoma, "Nimbus Sans L", Arial, "Liberation Sans", "PingFang SC", "Hiragino Sans GB", "Noto Sans CJK SC", "Source Han Sans SC", "Source Han Sans CN", "Microsoft YaHei", "Wenquanyi Micro Hei", "WenQuanYi Zen Hei", STHeiti, SimHei, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji", system-ui; }#WfAvXIEINvgE .fx8 {font-style: normal}#WfAvXIEINvgE .fb1 { fill: var(--N900-FG, 0.15); }#WfAvXIEINvgE .fb1 {fill: rgba(31,35,41, 0.15)}#WfAvXIEINvgE .fb2 { fill: rgb(209, 217, 224); }#WfAvXIEINvgE .fb2 {fill: rgb(209, 217, 224)}#WfAvXIEINvgE .fa3 { fill: var(--bg-body); }#WfAvXIEINvgE .fa3 {fill: #fff}AB123456789特性🤖 多模式 Agent🧩 Multi-Agent 协调🧩 Skill 工作流✋ HITL 人工审批📚 知识库🐾 长期记忆📡 SSE 流式输出🌐 API 文档说明 快速模式 + 深度思考模式 + Multi-Agent 协调者模式Expert 模式下协调者拆解任务，Worker 并行执行，统一汇总6 节点编排，自动识别相关 Skill，支持 Python 脚本执行敏感操作拦截，支持批准 / 拒绝 / 修改参数后继续执行PDF 入库、多模态解析（文本 + 图片描述）、混合检索（关键词 + 向量）向量召回相似记忆，定时扫描兜底，宠物形象情绪展示思考过程、最终回答、HITL 中断、知识库命中图片实时推送Knife4j 自动生成，启动即可访问fastthinkingexpert
🎬 功能演示
专家模式 多Agent协作
思考模式 绑定 skill 执行个税脚本
思考模式 不绑定 skill 执行个税脚本
快速模式 对话问答 执行个税脚本
知识库创建
知识库检索 支持图像
个人宠物 长期记忆
✨ 功能详情
Agent 编排
表格加载中...
请求主链路（AgentServiceImpl.call()）：
SSE 事件类型：
Multi-Agent 协调者
EXPERT 模式使用 CoordinatorAgent 实现多智能体协作：
分析：协调者接收用户问题，分析任务复杂度
拆解：将任务拆解为多个子任务，使用 dispatch_to_worker 工具派发
并行执行：WorkerPool 管理 Worker 池，WorkerAgent 独立执行（仅配备 search 工具）
汇总：收集所有 Worker 结果，经上下文压缩后生成最终答案
Agent 工具池
Agent 运行时仅暴露 commonTools（@Qualifier("commonTools")），包含 2 个工具：
全部 9 个已注册工具（allTools bean，按类名排序）：
search、knowledge_hybrid_search、knowledge_scalar_search、knowledge_vector_search、list_skill_resources、read_skill_resource、read_skill、dispatch_to_worker、execute_skill_script
另有 2 组条件注册的工具 Bean：
知识库检索工具（knowledge_*）只存在于 allTools，不在 commonTools。Agent 运行时无法调用，知识库检索走服务层预检索（KnowledgePreprocessServiceImpl.preprocess()）。
Skill 工作流
•
项目内建 Skill（src/main/resources/skills）：计算个人所得税、两数之和
•
用户自定义 Skill（src/main/resources/user-skills）：可通过文件系统注册
•
Skill 注册：FileSystemSkillRegistry 作为委托，CachingSkillRegistry 缓存，SkillConfig 装配
•
6 节点顺序工作流（SkillWorkflowConfig）：加载已绑定 Skill → 加载对话历史 → 识别相关性 → 发现候选 Skill → 加载 SKILL.md 内容 → 构建 SkillRuntimeContext
•
工作流结果 SkillWorkflowResult 包含 selectedSkills 和 selectedSkillContexts
HITL 人工审批
代码块
Plain Text
工具调用 → 拦截检查 → 创建 hitl_checkpoint → SSE 推送 hitl_interrupt → 前端审批 → POST /agent/resume 恢复
•
默认拦截工具：execute_skill_script（通过 cloudcold.hitl.intercept-tool-names 配置）。Multi-Agent 的 dispatch_to_worker 工具不被拦截
•
HITLState 使用 ConcurrentHashMap<String, Set
•
AgentServiceImpl.resume() 根据 agentType 路由到对应 Agent（PlanExecuteAgent 或 CoordinatorAgent）
知识库 PDF 入库
代码块
Plain Text
PDF 上传 → MinIO 存储 → 临时落盘 → PdfMultimodalProcessor 读取
→ 提取正文文本 + 抽取 PDF 图片 → 多模态模型（qwen3-vl-plus）生成描述
→ 图像描述注入文本原位 → 段落切分父块（PARENT）→ 子块切分（TEXT，200 字符）
→ ES 关键词索引（rag_docs，父块+子块）+ 向量索引（rag_docs_vector，仅 TEXT 子块，1536 维，cosine 相似度）
•
两级分块：父块（PARENT）含完整段落 + metadata.imageIds；子块（TEXT）含 parentChunkId 指向父块
•
标量检索查父块，向量检索查子块，向量结果在 RRF 融合前 resolve 回父块
•
图像描述通过
•
入库同步完成，返回时已是 INDEXED 或 FAILED
•
当前仅支持 PDF，PdfMultimodalProcessor 是 DocumentReaderStrategy 的唯一实现
•
预检索链路：会话绑定 selectedKnowledgeId → KnowledgeService.hybridSearch()（最多 8 个片段、4000 字符）→ 父块 imageIds 查 MySQL 获取 MinIO presigned URL → SSE knowledge_retrieval 事件
长期记忆 / 宠物记忆
聊天记忆
•
MysqlChatMemoryRepository 实现 ChatMemoryRepository，持久化到 chat_memory_history 表
•
窗口大小：maxMessages=20（cloudcold.agent.memory.max-messages）
•
不持久化实时思考过程，只持久化用户消息、助手最终回答和已回绑知识库图片（ChatMemoryHistoryImageRelation）
🛠 技术栈
🚀 快速开始
环境要求
•
JDK 21+
•
Maven 3.9+（或使用 ./mvnw）
•
MySQL 8.x
•
Redis 6.x / 7.x
•
Elasticsearch 8.x
•
MinIO
初始化数据库
代码块
Plain Text
mysql -uroot -p < src/main/java/com/shenchen/cloudcoldagent/database/init.sql
配置密钥
编辑 src/main/resources/application.yml，搜索 TODO 并替换为你的实际配置：
代码块
YAML
spring:
ai:
openai:
api-key: your-dashscope-api-key-here # TODO: DashScope API Key（必填）
datasource:
password: your-mysql-password-here # TODO: MySQL 密码（必填）
minio:
accessKey: your-minio-access-key-here # TODO: MinIO 凭证（必填）
secretKey: your-minio-secret-key-here
启动后端
代码块
Plain Text
./mvnw -q -DskipTests compile # 编译检查
./mvnw spring-boot:run # 启动服务
服务地址：http://localhost:8081/api
API 文档：http://localhost:8081/api/doc.html
📁 项目结构
代码块
Bash