Refinex Agent

企业级通用智能体平台。基于 Spring AI、Spring AI Alibaba、MySQL、Elasticsearch、Redis、MinIO 构建，面向企业内部知识问答、文件问答、多模态理解、RAG 知识库、Tool Calling、MCP、Skill、DataAgent、Deep Research 与可观测治理等场景。

Refinex Agent 不是对某一个示例项目的整仓二开，而是一个从零开始设计的企业级 AI Agent 工程。项目以 Spring AI 作为模型、Embedding、Tool Calling、RAG、MCP 等原子能力抽象层，以 Spring AI Alibaba 作为 Agent Framework、Graph、Skill、MCP、Workflow、多智能体和企业工程化能力的重要底座，同时吸收 AssistantAgent、dataagent、deepresearch、jmanus/Lynxe 等生态项目的成熟设计。

当前仓库仍处于 0→1 规划与基础工程初始化阶段。README.md 只描述目标架构和阶段性落地路径；具体可执行命令以对应脚手架、配置文件和模块实际落地后为准。

1. 项目定位

Refinex Agent 的目标是沉淀一个可长期演进、可私有化部署、可被多个业务系统集成的企业智能体平台。

核心目标：

统一企业大模型接入、会话、文件、知识库、工具、技能、MCP、Agent Runtime 和可观测能力。
支持普通聊天、文件问答、知识库问答、数据问答、深度研究、复杂任务执行、多模态理解等多类场景。
支持多租户、多用户、多应用、多 Agent、多知识库、多模型供应商。
支持 MySQL 作为主业务元数据存储，Elasticsearch 作为 RAG 混合检索引擎。
支持企业级安全、审计、成本统计、质量评估、灰度发布和运维观测。
避免将演示工程直接带入生产系统，所有能力通过清晰模块、稳定接口和可测试工程化方式落地。

2. 核心能力

2.1 聊天对话

普通同步对话。
SSE 流式对话。
多轮上下文。
会话标题生成。
消息引用和追溯。
模型调用日志、Token 统计、成本统计。
Prompt 模板化与版本管理。

2.2 文件问答

支持 PDF、Word、Excel、PowerPoint、Markdown、HTML、TXT、CSV、JSON 等文件类型。
文件上传、存储、解析、分块、Embedding、索引、检索、问答全流程。
原文引用、页码引用、段落引用、表格引用。
文件级权限控制和租户隔离。

2.3 RAG 知识库

MySQL 存储知识库、文档、Chunk、索引任务、版本、权限等元数据。
Elasticsearch 存储全文索引、向量索引和检索字段。
支持 BM25、Dense Vector、Metadata Filter、Hybrid Retrieval、RRF 融合排序。
支持按知识库、文档、标签、部门、租户、时间范围过滤。
支持答案引用 citations，避免无来源回答。

2.4 Tool Calling

Java Bean Tool。
Function Tool。
OpenAPI Tool。
HTTP Tool。
Database Tool。
Script/Sandbox Tool。
Tool 权限、参数校验、执行审计、超时控制、重试控制。

2.5 MCP

MCP Client：接入外部 MCP Server，转换为内部 Tool。
MCP Server：将 Refinex Agent 的知识库检索、文件检索、业务工具、数据分析工具对外暴露。
支持 STDIO、SSE、Streamable HTTP 等传输形态的扩展规划。
支持 MCP 工具白名单、租户隔离、执行审计。

2.6 Skill

技能注册、启停、版本化、参数 Schema、权限控制。
支持 Prompt Skill、Tool Skill、Workflow Skill、Agent Skill。
支持技能组合、技能路由和技能发布。
支持后续接入 Spring AI Alibaba Skills 体系。

2.7 DataAgent

自然语言转 SQL。
数据源管理。
Schema 同步。
语义模型。
业务术语映射。
SQL 安全校验。
只读查询策略。
查询结果解释和报告生成。

2.8 Deep Research

长任务研究型 Agent。
Plan and Execute。
多 Agent 协作。
Graph 编排。
反思与修正。
Human-in-the-loop。
多源检索与引用组织。
Markdown、HTML、PDF 报告生成。

2.9 多模态

图片理解。
文件图文混合理解。
OCR 扩展接口。
表格和图表分析扩展。
多模态模型能力抽象，避免业务直接绑定具体供应商。

2.10 企业治理

多租户。
RBAC 权限。
API Key 管理。
审计日志。
敏感信息脱敏。
模型供应商限流。
成本统计。
质量评估。
可观测 Trace。
生产配置外置化。

3. 技术栈

类别	选型	说明
语言	Java	编译基线 JDK 17，运行兼容 JDK 17/21
框架	Spring Boot 3.5.x	企业主应用框架
AI 抽象	Spring AI 1.1.2	ChatClient、Embedding、VectorStore、Tool Calling、MCP、RAG
Agent 工程化	Spring AI Alibaba 1.1.2.0 / 1.1.2.2	1.1.2.0 作为文档推荐兼容基线，1.1.2.2 作为 Maven profile 升级验证线
Agent 扩展	Spring AI Alibaba Extensions 1.1.2.1 / 1.1.2.2	与 Spring AI Alibaba 版本线联动验证
构建	Maven	多模块工程，统一依赖管理
数据库	MySQL 8.0+	业务元数据、会话、审计、配置、任务
数据迁移	Flyway	生产可控迁移，禁止依赖 ddl-auto
ORM	MyBatis-Plus	SQL 可控、便于租户拦截、审计和复杂查询
搜索	Elasticsearch 8.x	BM25、dense_vector、Hybrid RAG
缓存	Redis 7.x	限流、短期状态、分布式锁、异步任务状态
文件存储	MinIO / S3	原始文件、解析产物、报告、导出文件
API	Spring MVC + SSE	REST API 与流式响应
可观测	Micrometer + OpenTelemetry	Trace、Metrics、Logs、模型调用观测
测试	JUnit 5、Testcontainers、ArchUnit	单元、集成、架构约束测试
部署	Docker、Docker Compose、Kubernetes	本地、测试、生产多环境部署

4. 架构概览

┌───────────────────────────────────────────────────────────────────────┐
│ API / Admin Layer                                                     │
│ REST / SSE / WebSocket / MCP Server / OpenAPI / Admin Console         │
└───────────────────────────────────────────────────────────────────────┘
                                  │
┌───────────────────────────────────────────────────────────────────────┐
│ Agent Application Layer                                               │
│ Chat / File QA / RAG / Skill / MCP / DataAgent / Research / Multimodal│
└───────────────────────────────────────────────────────────────────────┘
                                  │
┌───────────────────────────────────────────────────────────────────────┐
│ Agent Runtime Layer                                                   │
│ Agent Router / ReactAgent / Graph Runtime / Memory / HITL / Event Bus │
└───────────────────────────────────────────────────────────────────────┘
                                  │
┌───────────────────────────────────────────────────────────────────────┐
│ Capability Layer                                                      │
│ Tool Calling / MCP Client / RAG Retriever / File Parser / Sandbox     │
└───────────────────────────────────────────────────────────────────────┘
                                  │
┌───────────────────────────────────────────────────────────────────────┐
│ Infrastructure Layer                                                  │
│ MySQL / Elasticsearch / Redis / MinIO-S3 / Observability / Scheduler  │
└───────────────────────────────────────────────────────────────────────┘
                                  │
┌───────────────────────────────────────────────────────────────────────┐
│ Model Provider Layer                                                  │
│ DashScope / OpenAI-compatible / Qwen / Private Model Gateway          │
└───────────────────────────────────────────────────────────────────────┘

5. 模块结构

refinex-agent/
├── pom.xml
├── README.md
├── PLANS.md
├── .gitignore
├── docs/
├── scripts/
├── deploy/
├── references/                         # 本地 clone 参考源码，不提交
├── refinex-agent-common/
├── refinex-agent-api/
├── refinex-agent-domain/
├── refinex-agent-security/
├── refinex-agent-infra-mysql/
├── refinex-agent-infra-redis/
├── refinex-agent-infra-es/
├── refinex-agent-infra-objectstore/
├── refinex-agent-ai-core/
├── refinex-agent-runtime/
├── refinex-agent-chat/
├── refinex-agent-file/
├── refinex-agent-rag/
├── refinex-agent-tool/
├── refinex-agent-mcp/
├── refinex-agent-skill/
├── refinex-agent-sandbox/
├── refinex-agent-assistant/
├── refinex-agent-data/
├── refinex-agent-research/
├── refinex-agent-multimodal/
├── refinex-agent-observability/
├── refinex-agent-admin/
└── refinex-agent-app/

模块原则：

domain 不依赖具体中间件。
api 负责 DTO、VO、Command、Query 和 API contract。
infra-* 模块分别适配 MySQL、Redis、Elasticsearch、MinIO/S3 等外部系统。
ai-core 统一模型供应商、ChatClient、Embedding、Rerank、Prompt 和模型调用日志。
runtime 承载 AgentDefinition、AgentExecutor、Graph Runtime、HITL 和事件流。
app 只做装配和启动，不写复杂业务逻辑。
AI 能力不直接散落在 Controller 中，统一经过 Runtime、Service、Registry 抽象。

6. 生态项目吸收

6.1 AssistantAgent

吸收方向：企业助手运行时、Code-as-Action 思路、动态 Prompt、SearchProvider SPI、Tool SPI、经验学习、触发器、回复渠道。

落地方式：

不整仓二开。
将 AssistantAgent 的 Assistant Runtime、Prompt Builder、Tool 接入、Search Provider 设计吸收到 refinex-agent-runtime、refinex-agent-tool、refinex-agent-rag、refinex-agent-skill。
企业生产实现中统一接入 Refinex 的租户、权限、审计、模型路由、配置中心和任务状态。

6.2 DataAgent

吸收方向：NL2SQL、数据源管理、Schema 召回、语义模型、业务知识、SQL 安全、分析报告。

落地方式：

作为 refinex-agent-data 插件能力。
不作为平台主入口。
所有 SQL 只读执行。
默认禁止 DDL、DML、危险函数和跨租户查询。
查询结果和生成 SQL 必须审计入库。

6.3 DeepResearch

吸收方向：长任务、多 Agent、Graph 编排、Plan/Execute、反思、HITL、研究报告、引用组织。

落地方式：

作为 refinex-agent-research 插件能力。
通过 refinex-agent-runtime 提供 Graph Runtime、HITL 和事件流能力。
研究任务状态、步骤、引用、报告都必须持久化。
支持人工审批、暂停、继续、取消、重试。

6.4 JManus / Lynxe

吸收方向：确定性任务执行、Func-Agent、HTTP 工具调用、MCP 集成、任务运行台状态模型。

落地方式：

只吸收运行时思想和工具模式。
不直接采用其默认数据库自动建表策略。
任务执行结果统一进入 Refinex Agent 的 Agent Run / Agent Step / Agent Event 表。

7. 数据存储设计原则

7.1 MySQL

MySQL 是主业务事实来源，负责存储：

租户、用户、应用、权限。
模型供应商和模型配置。
Agent 定义、Agent 版本、Prompt 版本。
会话、消息、附件、引用。
文件、知识库、文档、Chunk 元数据。
Tool、MCP、Skill 定义和执行日志。
DataAgent 数据源、Schema、语义模型、SQL 执行记录。
DeepResearch 任务、步骤、报告、引用。
模型调用日志、Token、成本、错误、Trace。
审计日志、人工审批、反馈、评估结果。

生产原则：

核心业务表必须有 tenant_id。
所有主表必须有 id、public_id、created_at、updated_at、created_by、updated_by、deleted_at、version。
逻辑删除统一使用 deleted_at。
所有 schema 变更必须走 Flyway。
禁止生产环境使用 JPA ddl-auto=update。
对外部模型请求、Tool 执行、SQL 执行必须保留审计日志。

7.2 Elasticsearch

Elasticsearch 是 RAG 检索引擎，负责存储：

Chunk 文本。
Chunk 向量。
文档元数据。
权限过滤字段。
标签和业务过滤字段。
BM25 检索字段。
Hybrid Retrieval 排序所需字段。

索引原则：

使用 alias 管理知识库索引。
支持按租户和知识库隔离。
支持索引版本重建和零停机切换。
支持 dense_vector、text、keyword、date 等字段。
检索结果必须返回可追溯引用信息。

8. 快速开始

8.1 环境要求

JDK 17 或 JDK 21。
Maven 3.9+。
Docker 24+。
Docker Compose v2+。
MySQL 8.0+。
Elasticsearch 8.x。
Redis 7.x。
MinIO 或兼容 S3 的对象存储。

8.2 克隆项目

git clone https://github.com/Refinex-Space/refinex-agent.git
cd refinex-agent

8.3 当前阶段

当前仓库处于阶段 0/1 之间，重点是空仓库、参考源码、版本基线和 Maven 多模块骨架。以下文件和能力按 PLANS.md 逐阶段落地：

scripts/clone-references.sh
docs/version-baseline.md
deploy/docker-compose.yml
.env.example
根 pom.xml 和各 Maven 子模块
refinex-agent-app 启动应用

在这些文件落地前，不应把本仓库视为可直接启动的应用。

8.4 计划中的本地环境变量

阶段 1.4 落地 .env.example 后，计划包含以下本地环境变量：

REFINEX_AGENT_PROFILE=local

MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_DATABASE=refinex_agent
MYSQL_USERNAME=refinex
MYSQL_PASSWORD=refinex

REDIS_HOST=127.0.0.1
REDIS_PORT=6379

ELASTICSEARCH_URIS=http://127.0.0.1:9200

MINIO_ENDPOINT=http://127.0.0.1:9000
MINIO_ACCESS_KEY=refinex
MINIO_SECRET_KEY=refinex123456

DASHSCOPE_API_KEY=replace-with-your-key
OPENAI_API_KEY=replace-with-your-key

8.5 计划中的本地基础设施

阶段 1.4 落地 deploy/docker-compose.yml 后，本地基础设施启动命令为：

docker compose -f deploy/docker-compose.yml up -d

计划中的本地基础设施包括：

MySQL。
Redis。
Elasticsearch。
MinIO。

8.6 计划中的编译与启动

阶段 1 的 Maven 多模块骨架落地后，基础验证命令为：

mvn -q -DskipTests package

阶段 1.3 的启动应用落地后，本地启动命令为：

mvn -pl refinex-agent-app spring-boot:run \
  -Dspring-boot.run.profiles=local

默认地址：

http://localhost:18080

健康检查：

curl http://localhost:18080/api/health

9. 配置示例

9.1 application-local.yml

server:
  port: 18080

spring:
  application:
    name: refinex-agent
  datasource:
    url: jdbc:mysql://${MYSQL_HOST:127.0.0.1}:${MYSQL_PORT:3306}/${MYSQL_DATABASE:refinex_agent}?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai
    username: ${MYSQL_USERNAME:refinex}
    password: ${MYSQL_PASSWORD:refinex}
  data:
    redis:
      host: ${REDIS_HOST:127.0.0.1}
      port: ${REDIS_PORT:6379}
  flyway:
    enabled: true
    locations: classpath:db/migration
    baseline-on-migrate: true

refinex:
  agent:
    tenant:
      default-tenant-id: default
    storage:
      type: minio
      endpoint: ${MINIO_ENDPOINT:http://127.0.0.1:9000}
      access-key: ${MINIO_ACCESS_KEY:refinex}
      secret-key: ${MINIO_SECRET_KEY:refinex123456}
      bucket: refinex-agent
    search:
      elasticsearch:
        uris: ${ELASTICSEARCH_URIS:http://127.0.0.1:9200}
        index-prefix: refinex-agent
    model:
      default-chat-model: qwen-plus
      default-embedding-model: text-embedding-v3
      providers:
        dashscope:
          enabled: true
          api-key: ${DASHSCOPE_API_KEY:}
        openai:
          enabled: false
          api-key: ${OPENAI_API_KEY:}

9.2 生产配置原则

生产环境不要提交真实配置到 Git。

必须通过以下方式之一注入配置：

Kubernetes Secret。
Nacos Config。
环境变量。
云厂商 Secret Manager。
Vault。

10. API 示例

以下 API 是目标接口形态示例，需在对应阶段实现后才能执行。

10.1 创建聊天会话

curl -X POST http://localhost:18080/api/v1/chat/sessions \
  -H 'Content-Type: application/json' \
  -H 'X-Tenant-Id: default' \
  -d '{
    "agentCode": "default-assistant",
    "title": "企业知识问答"
  }'

10.2 普通聊天

curl -X POST http://localhost:18080/api/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'X-Tenant-Id: default' \
  -d '{
    "sessionId": "replace-session-id",
    "message": "请介绍 Refinex Agent 的核心能力",
    "stream": false
  }'

10.3 流式聊天

curl -N -X POST http://localhost:18080/api/v1/chat/completions/stream \
  -H 'Content-Type: application/json' \
  -H 'X-Tenant-Id: default' \
  -d '{
    "sessionId": "replace-session-id",
    "message": "基于知识库总结一下最新制度",
    "knowledgeBaseIds": ["replace-kb-id"],
    "stream": true
  }'

10.4 上传文件

curl -X POST http://localhost:18080/api/v1/files \
  -H 'X-Tenant-Id: default' \
  -F 'file=@./docs/example.pdf' \
  -F 'visibility=PRIVATE'

10.5 创建知识库

curl -X POST http://localhost:18080/api/v1/knowledge-bases \
  -H 'Content-Type: application/json' \
  -H 'X-Tenant-Id: default' \
  -d '{
    "name": "企业制度知识库",
    "description": "用于企业内部制度问答",
    "retrievalMode": "HYBRID"
  }'

10.6 知识库问答

curl -X POST http://localhost:18080/api/v1/rag/answer \
  -H 'Content-Type: application/json' \
  -H 'X-Tenant-Id: default' \
  -d '{
    "question": "请说明年假审批流程",
    "knowledgeBaseIds": ["replace-kb-id"],
    "topK": 8,
    "withCitations": true
  }'

11. RAG 流程

文件上传
  ↓
对象存储保存原文
  ↓
文件解析
  ↓
文本清洗
  ↓
Chunk 分块
  ↓
Embedding 生成
  ↓
MySQL 保存元数据
  ↓
Elasticsearch 建立全文索引和向量索引
  ↓
用户提问
  ↓
Query Rewrite / Expansion
  ↓
BM25 检索 + Vector 检索 + Metadata Filter
  ↓
RRF 融合排序
  ↓
可选 Rerank
  ↓
构造上下文
  ↓
模型生成答案
  ↓
返回答案和 citations

RAG 回答必须满足：

没有检索证据时明确说明无法从知识库确认。
所有引用必须能定位到知识库、文档、Chunk、页码或段落。
不允许把模型猜测伪装成知识库事实。
检索、重排、生成链路必须记录 Trace。

12. Tool Calling 设计

Tool 分为四类：

类型	说明
Java Tool	本地 Java Bean 方法暴露为工具
HTTP Tool	HTTP API 或 OpenAPI 接口暴露为工具
MCP Tool	外部 MCP Server 的工具映射为内部工具
Sandbox Tool	受控脚本、Python、数据分析、报表生成等工具

Tool 执行原则：

所有 Tool 必须注册。
所有 Tool 必须声明输入参数 JSON Schema。
所有 Tool 必须有租户级权限控制。
所有 Tool 必须有超时限制。
高风险 Tool 必须支持人工审批。
Tool 输入输出必须审计。
Tool 错误不能直接泄漏内部敏感信息给终端用户。

13. MCP 设计

13.1 MCP Client

Refinex Agent 作为 MCP Client 时：

连接外部 MCP Server。
获取工具列表。
将 MCP Tool 映射为内部 Tool Definition。
根据租户、Agent、用户权限过滤可用工具。
统一执行审计和 Trace。

13.2 MCP Server

Refinex Agent 作为 MCP Server 时，可对外暴露：

知识库检索工具。
文件检索工具。
企业业务查询工具。
DataAgent 查询工具。
DeepResearch 任务创建工具。
报告查询工具。

MCP Server 默认不开启生产公网访问。生产环境必须配置认证、授权、限流和审计。

14. Skill 设计

Skill 是对 Prompt、Tool、Workflow、Agent 的可治理封装。

典型 Skill：

企业制度问答 Skill。
合同审查 Skill。
周报生成 Skill。
数据分析 Skill。
工单摘要 Skill。
代码解释 Skill。
深度研究 Skill。

Skill 生命周期：

DRAFT → TESTING → PUBLISHED → DEPRECATED → ARCHIVED

Skill 必须具备：

唯一编码。
名称和描述。
输入参数 Schema。
输出格式定义。
版本号。
适用模型。
关联 Tool / Knowledge Base / Prompt / Workflow。
权限策略。
测试样例。
发布记录。

15. DataAgent 安全原则

DataAgent 适合处理企业数据问答，但必须严格约束。

默认策略：

只允许 SELECT。
禁止 INSERT、UPDATE、DELETE、DROP、ALTER、TRUNCATE、CREATE。
禁止多语句执行。
禁止访问未授权表。
禁止跨租户查询。
必须设置最大返回行数。
必须设置查询超时。
必须记录自然语言问题、生成 SQL、最终 SQL、执行耗时、结果行数和用户信息。
高敏感数据必须脱敏后返回。

DataAgent 不直接暴露数据库账号给模型。模型只生成候选 SQL，最终由 Refinex Agent 的 SQL Guard、权限系统和执行器验证后执行。

16. DeepResearch 任务模型

DeepResearch 是长任务，不应作为普通 HTTP 短请求处理。

推荐流程：

创建研究任务
  ↓
生成研究计划
  ↓
人工可选确认
  ↓
执行检索 / 工具 / 代码 / 文件分析
  ↓
阶段性反思
  ↓
补充检索或修正计划
  ↓
生成报告草稿
  ↓
人工可选审阅
  ↓
生成最终报告
  ↓
归档引用和运行记录

任务状态：

CREATED → PLANNING → WAITING_APPROVAL → RUNNING → REVIEWING → SUCCEEDED
                                               ↘ FAILED / CANCELLED / TIMEOUT

DeepResearch 必须支持：

异步运行。
暂停。
继续。
取消。
步骤重试。
人工审批。
任务事件流。
报告导出。
引用追溯。

17. 安全与权限

企业生产环境必须启用：

认证：JWT、OAuth2、OIDC、企业 SSO 或网关认证。
授权：RBAC + 资源级权限。
租户隔离：所有核心表和检索索引必须包含 tenant_id。
API Key 管理：应用级密钥、有效期、限流、撤销。
数据脱敏：手机号、身份证、银行卡、邮箱、地址等敏感信息。
Prompt Injection 防护：系统 Prompt、工具说明、RAG 上下文分层隔离。
Tool 安全：参数校验、权限验证、审计、超时、熔断。
文件安全：类型校验、大小限制、病毒扫描扩展点。
模型安全：供应商密钥不入库明文，配置集中管理。
审计：登录、配置变更、模型调用、工具调用、数据查询、文件访问。

18. 可观测与评估

18.1 Trace

需要追踪：

用户请求。
Agent 路由。
Prompt 构造。
模型调用。
RAG 检索。
Tool 调用。
MCP 调用。
Graph 节点执行。
DataAgent SQL 生成与执行。
DeepResearch 步骤。

18.2 Metrics

核心指标：

请求量。
成功率。
错误率。
P50 / P90 / P99 延迟。
模型调用次数。
输入 Token。
输出 Token。
估算成本。
RAG 命中率。
引用覆盖率。
Tool 成功率。
MCP 工具成功率。
SQL 拦截次数。

18.3 Evaluation

评估维度：

回答正确性。
引用正确性。
忠实性。
上下文相关性。
检索召回率。
工具调用准确率。
SQL 生成准确率。
安全拦截有效性。
多轮记忆一致性。

19. 开发规范

19.1 分支规范

main        # 稳定主分支
release/*   # 发布分支
feature/*   # 功能分支
fix/*       # 缺陷修复
chore/*     # 工程治理
experiment/*# 实验分支

19.2 Commit 规范

采用 Conventional Commits：

feat: 新功能
fix: 缺陷修复
docs: 文档
style: 格式调整
refactor: 重构
perf: 性能优化
test: 测试
build: 构建
ci: CI 配置
chore: 杂项
revert: 回滚

示例：

feat(rag): add elasticsearch hybrid retriever
fix(tool): prevent unsafe http tool invocation
docs(readme): add local quick start guide

19.3 代码规范

Controller 只处理协议转换，不写复杂业务逻辑。
Service 编排用例，不直接拼接复杂 SQL。
Domain 层不依赖 Spring Web、MyBatis、Elasticsearch Client。
infra-* 层负责外部系统适配。
所有外部调用必须设置超时。
所有异步任务必须有任务状态。
所有模型调用必须有日志和 Trace。
所有表结构变更必须提供 Flyway migration。
所有公共接口必须有测试。

20. 测试策略

测试类型	工具	目标
单元测试	JUnit 5、Mockito	领域逻辑、服务逻辑、工具校验
集成测试	Testcontainers	MySQL、Redis、Elasticsearch、MinIO 集成验证
API 测试	MockMvc / REST Assured	REST、SSE、错误码、权限
架构测试	ArchUnit	模块依赖和分层约束
RAG 测试	自建 evaluation dataset	检索召回、引用正确性、忠实性
Agent 测试	Golden Cases	Tool 调用、Graph 路径、任务状态
安全测试	自建攻击样例	Prompt Injection、SQL 注入、越权访问

Maven 工程落地后的本地执行：

mvn test

Maven 工程落地后的完整验证：

mvn clean verify

21. 部署建议

21.1 本地开发

阶段 1.3/1.4 落地启动应用和本地 Compose 后：

docker compose -f deploy/docker-compose.yml up -d
mvn -pl refinex-agent-app spring-boot:run -Dspring-boot.run.profiles=local

21.2 测试环境

MySQL、Redis、Elasticsearch、MinIO 使用独立实例。
开启 Flyway migration。
开启 Trace 和 Metrics。
使用测试模型 Key。
开启 RAG 评估和 API 自动化测试。

21.3 生产环境

生产环境建议：

Kubernetes 部署。
多副本无状态应用。
独立异步任务 Worker。
Elasticsearch 独立集群。
MySQL 主从或云托管高可用。
Redis 高可用。
MinIO 集群或云对象存储。
OpenTelemetry Collector 统一采集。
Prometheus + Grafana 指标监控。
Loki / ELK 日志检索。
灰度发布和回滚策略。

22. 生产检查清单

上线前必须检查：

23. Roadmap

23.1 Phase 1：基础平台 MVP

多模块工程。
MySQL/Flyway。
用户、租户、应用基础模型。
模型供应商接入。
普通聊天。
SSE 流式聊天。
会话和消息持久化。
模型调用日志。

23.2 Phase 2：文件问答与 RAG

文件上传。
文档解析。
Chunk 分块。
Embedding。
Elasticsearch 索引。
Hybrid Retrieval。
RAG 问答。
citations 引用。

23.3 Phase 3：Tool、MCP、Skill

Tool Registry。
Java Tool。
HTTP/OpenAPI Tool。
MCP Client。
MCP Server。
Skill Registry。
Tool 审计和权限。

23.4 Phase 4：DataAgent

数据源管理。
Schema 同步。
语义模型。
NL2SQL。
SQL Guard。
数据分析报告。

23.5 Phase 5：DeepResearch 与 Graph

Graph Runtime。
Plan/Execute。
HITL。
长任务状态。
报告生成。
引用归档。

23.6 Phase 6：企业生产治理

观测平台。
评估平台。
成本平台。
安全治理。
多租户增强。
管理端控制台。
Kubernetes 生产部署。

24. 参考项目

本项目吸收以下生态项目的设计思想，但不直接整仓二开：

https://github.com/spring-ai-alibaba/AssistantAgent
https://github.com/spring-ai-alibaba/dataagent
https://github.com/spring-ai-alibaba/deepresearch
https://github.com/spring-ai-alibaba/jmanus
https://github.com/alibaba/spring-ai-alibaba
https://github.com/spring-projects/spring-ai

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

Refinex Agent

1. 项目定位

2. 核心能力

2.1 聊天对话

2.2 文件问答

2.3 RAG 知识库

2.4 Tool Calling

2.5 MCP

2.6 Skill

2.7 DataAgent

2.8 Deep Research

2.9 多模态

2.10 企业治理

3. 技术栈

4. 架构概览

5. 模块结构

6. 生态项目吸收

6.1 AssistantAgent

6.2 DataAgent

6.3 DeepResearch

6.4 JManus / Lynxe

7. 数据存储设计原则

7.1 MySQL

7.2 Elasticsearch

8. 快速开始

8.1 环境要求

8.2 克隆项目

8.3 当前阶段

8.4 计划中的本地环境变量

8.5 计划中的本地基础设施

8.6 计划中的编译与启动

9. 配置示例

9.1 application-local.yml

9.2 生产配置原则

10. API 示例

10.1 创建聊天会话

10.2 普通聊天

10.3 流式聊天

10.4 上传文件

10.5 创建知识库

10.6 知识库问答

11. RAG 流程

12. Tool Calling 设计

13. MCP 设计

13.1 MCP Client

13.2 MCP Server

14. Skill 设计

15. DataAgent 安全原则

16. DeepResearch 任务模型

17. 安全与权限

18. 可观测与评估

18.1 Trace

18.2 Metrics

18.3 Evaluation

19. 开发规范

19.1 分支规范

19.2 Commit 规范

19.3 代码规范

20. 测试策略

21. 部署建议

21.1 本地开发

21.2 测试环境

21.3 生产环境

22. 生产检查清单

23. Roadmap

23.1 Phase 1：基础平台 MVP

23.2 Phase 2：文件问答与 RAG

23.3 Phase 3：Tool、MCP、Skill

23.4 Phase 4：DataAgent

23.5 Phase 5：DeepResearch 与 Graph

23.6 Phase 6：企业生产治理

24. 参考项目

25. License

详见 Apache License 2.0。

About

Topics

Packages