本文说明 cloud-cold-agent 的本地开发、配置、启动、验证和排查方式。
- JDK 21
- Maven 3.9+,或仓库内
./mvnw - MySQL 8.x
- Redis 6.x / 7.x
- Elasticsearch 8.x
- MinIO
- OpenAI 兼容聊天模型
- OpenAI 兼容 Embedding 模型
- PDF 多模态模型
当前 src/main/resources/application.yml 的关键运行值:
| 配置项 | 当前值 |
|---|---|
server.port |
8081 |
server.servlet.context-path |
/api |
spring.profiles.active |
local |
spring.datasource.url |
jdbc:mysql://localhost:3306/cloud_cold |
spring.datasource.username |
root |
spring.datasource.password |
your-mysql-password-here |
spring.data.redis.host |
localhost |
spring.elasticsearch.uris |
http://localhost:9200 |
minio.endpoint |
http://localhost:9000 |
minio.bucketName |
cloud-cold |
spring.ai.openai.base-url |
https://dashscope.aliyuncs.com/compatible-mode/ |
spring.ai.openai.chat.options.model |
qwen-turbo |
spring.ai.openai.embedding.options.model |
text-embedding-v4 |
cloudcold.search.mock.enabled |
true |
cloudcold.hitl.enabled |
true |
cloudcold.hitl.intercept-tool-names |
execute_skill_script |
cloudcold.long-term-memory.enabled |
true |
cloudcold.long-term-memory.trigger-rounds |
5 |
cloudcold.long-term-memory.default-pet-name |
小云 |
cloudcold.pdf.multimodal.model |
qwen3-vl-plus |
注意:@ConfigurationProperties 类中的默认值不一定等于当前运行值。描述当前行为时以 application.yml 为准。
建议使用未提交的 src/main/resources/application-local.yml 覆盖账号、密码和密钥:
spring:
datasource:
username: root
password: your_mysql_password
ai:
openai:
api-key: your_api_key
base-url: https://your-openai-compatible-endpoint
chat:
options:
model: qwen-turbo
embedding:
options:
model: text-embedding-v4
cloudcold:
pdf:
multimodal:
api-key: your_multimodal_api_key
base-url: https://your-openai-compatible-endpoint
model: qwen3-vl-plus如果要关闭 mock 搜索并启用真实联网搜索,还需要:
spring:
ai:
alibaba:
toolcalling:
tavilysearch:
enabled: true
api-key: your_tavily_key
cloudcold:
search:
mock:
enabled: false初始化脚本:
src/main/java/com/shenchen/cloudcoldagent/database/init.sql
核心表包括:
userchat_memory_historychat_memory_history_image_relationchat_conversationuser_conversation_relationconversation_skill_relationconversation_knowledge_relationhitl_checkpointknowledgeknowledge_documentknowledge_document_imageuser_long_term_memoryuser_long_term_memory_source_relationuser_long_term_memory_conversation_state
脚本会写入测试账号:
admin / 12345678user / 12345678test / 12345678
密码加密方式是 MD5(password + "salt")。
先确保 MySQL、Redis、Elasticsearch、MinIO 和模型服务可用,然后运行:
./mvnw spring-boot:run默认地址:
也可以打包后启动:
./mvnw clean package
java -jar target/cloud-cold-agent-0.0.1-SNAPSHOT.jar当前 SkillConfig 从文件系统路径 src/main/resources/skills 加载本地 Skill。使用裸 JAR 启动时,工作目录仍然要能访问该路径,否则 SkillRegistry 初始化会失败。
编译检查:
./mvnw -q -DskipTests compile运行测试:
./mvnw test前端仓库是 cloud-cold-frontend。
- 普通 JSON 请求固定带
credentials: 'include'。 - 本地前端常见地址
http://localhost:5173会直接请求http://localhost:8081/api。 - Agent 流式接口使用
text/event-stream,前端通过fetch + getReader手动解析。 - Cookie / Redis Session 是登录态联调的第一排查点。
- 登录后仍提示未登录:检查 Cookie 是否携带,以及 Redis Session 是否可用。
- SSE 没有内容:检查
/agent/call响应头是否为text/event-stream。 - 搜索结果像假数据:当前默认
cloudcold.search.mock.enabled=true。 - 联网搜索不生效:确认关闭 mock,并配置 Tavily。
- 文档上传很慢:当前上传接口同步完成 PDF 解析、抽图、索引,不是异步任务队列。
- 文档上传失败:检查 MinIO、Elasticsearch、Embedding 模型和 PDF 多模态模型。
- 知识库图片不回显:检查父块
metadata.imageIds是否包含有效图片 ID,以及 MinIO 预签名 URL 是否生成成功。 - 长期记忆没有刷新:确认是否达到
trigger-rounds=5,再检查整点调度或手动/userMemory/rebuild。 - 前端 ID 比较异常:优先确认后端返回的
Long是否为字符串。