# AI Agent 智能RAG决策引擎

**Repository Path**: get2bad/drone-ai-qa-system

## Basic Information

- **Project Name**: AI Agent 智能RAG决策引擎
- **Description**: AI Agent智能RAG系统
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-15
- **Last Updated**: 2026-03-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# tuanshu-ai-agent

> 多能力 AI Agent 平台

tuanshu-ai-agent 是一个围绕 LLM、MCP、RAG、长期记忆、定时任务与工程化运维能力构建的智能体平台。项目目标不是提供一个单一聊天页面，而是将模型调用、工具执行、知识检索、长期记忆、任务调度、计费追踪和容器化运行环境统一纳入一套可持续演进的 Agent 编排体系。

## 项目简介

tuanshu-ai-agent 采用前后端分离架构：

- 前端负责工作区、Agent 配置、聊天交互、模型选择、工具与知识库管理。
- 后端负责 Agent 生命周期管理、对话编排、模型接入、工具调用、RAG 检索、长期记忆、定时任务、计费和追踪。
- 基础设施层负责数据库、消息队列、对象存储、向量检索、容器管理与外部模型服务接入。

从平台定位上看，tuanshu-ai-agent 同时覆盖 3 个层面：

- 产品层：支持创建、配置、发布和使用 AI Agent。
- AI 层：将 LLM、Tools、RAG、Memory、Task 纳入统一执行链路。
- 工程层：提供分层架构、异步处理、高可用、计费、追踪、部署与运维能力。

## 核心能力

- Agent 创建、编辑、发布、版本管理、工作区管理
- 流式对话、会话管理、上下文构建、中断处理
- 模型服务商接入、多模型配置与高可用选择
- MCP 工具市场、工具安装、工具调用编排
- **Skills 技能系统**：在 LLM 调用工具前注入自定义步骤链，支持工具拦截（TOOL_OVERRIDE）和独立工具（STANDALONE）两种模式
- RAG 知识库上传、切片、OCR、向量化、检索增强问答
- RAG 语义查询缓存：相似问题跨用户命中，跳过向量检索与 LLM 调用
- 长期记忆抽取、存储、向量召回与提示词增强
- 定时任务创建、调度、异步执行与循环重入
- Token 超限治理，支持无策略、滑动窗口与摘要策略
- 计费、订单、支付、调用追踪、链路审计
- Widget 嵌入、开放能力接入、容器与 MCP 网关管理

## 技术栈

| 层级 | 技术选型 |
|------|------|
| 前端 | Next.js 15、React 19、TypeScript、Tailwind CSS、shadcn/ui |
| 后端 | Spring Boot 3、Java 17、MyBatis-Plus |
| 数据存储 | PostgreSQL、pgvector、对象存储 |
| 消息系统 | RabbitMQ |
| AI 能力 | LLM 服务商接入、LangChain4j、MCP、RAG、Embedding、Rerank、语义查询缓存 |
| 部署方式 | Docker、Docker Compose |

## 总体架构

### 系统架构图

```mermaid
flowchart TD
  U[用户 / 外部系统] --> FE[Next.js 前端]
  U --> W[Widget / Open API]

  FE -->|HTTP / SSE| BE[Spring Boot 后端]
  W -->|HTTP / SSE| BE

  BE --> I[Interfaces 接口层]
  I --> A[Application 应用层]
  A --> D[Domain 领域层]
  D --> INF[Infrastructure 基础设施层]

  INF --> DB[(PostgreSQL)]
  INF --> MQ[(RabbitMQ)]
  INF --> VS[(pgvector / 向量存储)]
  INF --> OSS[(文件存储 / 对象存储)]
  INF --> LLM[外部模型服务]
  INF --> MCP[MCP Gateway / Tool Services]
  INF --> CT[容器运行环境]

  D --> MOD1[Agent / Workspace]
  D --> MOD2[Conversation / Context]
  D --> MOD3[Tool / MCP]
  D --> MOD4[RAG / Retrieval]
  D --> MOD5[Memory]
  D --> MOD6[Scheduled Task]
  D --> MOD7[Billing / Trace / HA]
  D --> MOD8[RAG 语义查询缓存]
  D --> MOD9[Skills 技能系统]
```

### 部署架构图

```mermaid
flowchart LR
  DEV[浏览器 / 客户端] --> N1[tuanshu-ai-agent Frontend]
  N1 --> N2[tuanshu-ai-agent Backend]
  N2 --> N3[(PostgreSQL)]
  N2 --> N4[(RabbitMQ)]
  N2 --> N5[对象存储 / 本地存储]
  N2 --> N6[模型服务商 API]
  N2 --> N7[MCP Gateway]
  N2 --> N8[向量检索 / pgvector]
  N2 --> N8B[RAG 查询缓存 / pgvector]
  N2 --> N9[Docker Runtime]
```

## 分层设计

tuanshu-ai-agent 后端采用典型的 DDD 风格分层，职责边界比较清晰。

| 层级 | 主要职责 |
|------|------|
| interfaces | Controller、鉴权上下文、参数校验、统一响应 |
| application | 业务流程编排、跨模块协调、事务入口 |
| domain | 核心业务规则、状态流转、能力组合 |
| infrastructure | 数据访问、MQ、存储、外部模型、容器、第三方服务 |

这种分层方式使系统能够同时承载复杂业务编排和外部能力接入，避免 Controller 直接承载业务逻辑，也避免领域规则被基础设施细节污染。

## 业务模块说明

### 后端核心模块

- `agent`：Agent 创建、编辑、状态管理、版本发布、市场流转
- `conversation`：聊天请求处理、上下文构建、SSE 流式输出、中断控制
- `llm`：模型配置、服务商管理、高可用降级与 provider 选择
- `tool`：工具上传、审核、安装、市场管理、MCP 适配
- `rag`：数据集、文件、切片、OCR、向量化、召回与问答；内含语义查询缓存模块
- `memory`：长期记忆抽取、持久化、相关记忆召回
- `scheduledtask`：定时任务定义、延迟队列调度、事件执行
- `trace`：记录一次 Agent 执行中模型调用、工具调用与异常链路
- `billing` / `order` / `payment`：调用计费、订单与支付闭环
- `container`：容器模板、用户容器、MCP 运行环境管理

### 前端核心结构

- `app/`：页面路由与页面级组合
- `components/`：聊天面板、会话列表、模型选择器、配置弹窗等通用组件
- `lib/`：接口服务封装、模块 service、请求统一处理
- `contexts/`：账户、工作区、RAG 会话等全局状态
- `hooks/`：中断式聊天、Agent 编辑、工具操作等复用逻辑

## 仓库结构

```text
tuanshu-ai-agent
├─ tuanshu-ai-agent/                  # Java 后端
│  ├─ src/main/java/org/xhy
│  │  ├─ interfaces         # 接口层
│  │  ├─ application        # 应用层
│  │  ├─ domain             # 领域层
│  │  └─ infrastructure     # 基础设施层
│  ├─ src/main/resources    # 配置与数据库迁移
│  └─ docs/                 # 后端专题文档
├─ tuanshu-ai-agent-frontend-plus/    # Next.js 前端
│  ├─ app                   # 页面路由
│  ├─ components            # 组件层
│  ├─ lib                   # API 与服务封装
│  ├─ contexts              # 全局状态
│  └─ hooks                 # 交互逻辑复用
├─ deploy/                  # 开发部署脚本与 Compose 配置
├─ docker/                  # 容器构建相关文件
├─ production/              # 生产部署配置
├─ docs/                    # 总体设计与专题文档
└─ README.md                # 仓库主文档
```

## 核心链路

### 1. Agent 生命周期

Agent 并不是一段 Prompt，而是一组完整配置的聚合体，通常包含：

- 基础信息：名称、头像、描述、欢迎语、系统提示词
- 模型配置：模型、温度、上下文策略、降级链路
- 能力配置：工具列表、知识库、记忆、Widget、任务能力
- 发布配置：版本记录、市场状态、审核与上下架

### 2. 对话主链路

用户发起一次对话时，系统会依次完成以下步骤：

1. 查找当前会话与关联 Agent
2. 读取 Agent 工作区配置与模型配置
3. 加载工具、知识库、上下文策略、长期记忆
4. 根据配置执行 Token 超限治理
5. 构建 ChatContext 与消息处理器
6. 调用模型并通过 SSE 向前端流式返回
7. 在对话结束后保存消息、执行计费、抽取记忆、记录 Trace

### 对话运行时序图

```mermaid
sequenceDiagram
  participant User as 用户
  participant FE as Frontend
  participant API as ConversationAppService
  participant Ctx as Context Builder
  participant Cache as RAG 语义缓存
  participant LLM as LLM Client
  participant Skill as SkillAwareToolProvider
  participant MCP as MCP Tool
  participant Store as Message / Trace / Billing

  User->>FE: 发送消息
  FE->>API: 发起聊天请求
  API->>Ctx: 加载 Agent / Session / Model / Tools / Memory / Skills
  Ctx-->>API: 返回 ChatContext

  alt RAG 对话模式
    API->>Cache: 问题向量化 → 查询缓存向量库
    alt 缓存命中（cos_sim ≥ 阈值）
      Cache-->>API: 返回缓存答案
      API-->>FE: SSE 流式返回缓存答案（跳过 LLM）
    else 缓存未命中
      Cache-->>API: 未命中
      API->>LLM: 知识片段注入 + 发起流式推理
      LLM-->>API: 流式 token
      API-->>FE: SSE 增量返回
      API->>Cache: 异步写入缓存（answer + embedding）
    end
  else 普通 Agent 对话模式
    API->>LLM: 发起流式推理
    LLM-->>API: 流式 token
    API-->>FE: SSE 增量返回
  end

  LLM->>Skill: 发起工具调用
  alt TOOL_OVERRIDE Skill 匹配
    Skill->>MCP: Skill 步骤内调用真实 MCP 工具
    MCP-->>Skill: 工具结果
    Skill->>Skill: TRANSFORM / CONDITION 步骤处理
    Skill-->>LLM: 返回 Skill 最终输出
  else STANDALONE Skill 调用
    Skill->>MCP: Skill 步骤内调用 MCP 工具（可选）
    MCP-->>Skill: 工具结果
    Skill-->>LLM: 返回 Skill 最终输出
  else 无匹配 Skill（直连 MCP）
    Skill->>MCP: 透传调用原始 MCP 工具
    MCP-->>Skill: 工具结果
    Skill-->>LLM: 返回工具结果
  end

  LLM-->>API: 最终答案
  API->>Store: 保存消息 / 计费 / Trace / 记忆抽取
  API-->>FE: 结束响应
```

## 关键流程图

### Agent 执行总流程

```mermaid
flowchart TD
  A[用户消息] --> B[读取 Session 与 Agent]
  B --> C[加载模型配置]
  C --> D[加载工具、知识库、长期记忆]
  D --> E[执行 Token 超限策略]
  E --> F[构建 ChatContext]
  F --> G[创建消息处理器]
  G --> H[调用 LLM 流式生成]
  H --> I{是否需要工具}
  I -- 是 --> J[执行工具调用]
  J --> H
  I -- 否 --> K[输出最终回复]
  K --> L[保存消息]
  L --> M[计费与 Trace]
  M --> N[异步抽取长期记忆]
```

### 工具调用与 Skill 拦截流程图

```mermaid
flowchart TD
  A[用户发起聊天] --> B[ConversationAppService.prepareEnvironment]
  B --> C[读取 Agent.toolIds]
  C --> D[按 userId 查询已安装工具 UserTool]
  D --> E[提取 mcpServerName 列表]
  E --> F[写入 ChatContext.mcpServerNames]
  F --> G[消息处理器 provideTools]
  G --> H[AgentToolManager.createToolProvider]
  H --> I[McpUrlProviderService 生成工具地址]
  I --> J[创建 McpClient → McpToolProvider]
  J --> K[SkillAwareToolProvider 包装]
  K --> K1[SkillRegistry 查找 TOOL_OVERRIDE Skill<br/>按 agentId + toolName]
  K --> K2[SkillRegistry 查找 STANDALONE Skill<br/>注册为新工具名]
  K1 --> L[组装最终 ToolProvider]
  K2 --> L
  L --> M[挂载到 LangChain4j Agent]
  M --> N{模型推理：是否调用工具?}
  N -- 否 --> O[输出最终回复]
  N -- 是 --> P{SkillAwareToolProvider 路由}
  P -- TOOL_OVERRIDE 命中 --> Q[SkillExecutionEngine 执行步骤链]
  P -- STANDALONE 调用 --> Q
  P -- 无匹配 Skill --> R[直接调用原始 MCP]
  Q --> S{步骤类型}
  S -- CALL_TOOL --> R
  S -- TRANSFORM --> T[本地文本处理]
  S -- CONDITION --> U{条件满足?}
  U -- 是 --> S
  U -- 否 --> V[提前终止返回当前结果]
  R --> W[MCP 工具返回结果]
  W --> Q
  T --> Q
  V --> N
  Q --> X[步骤链执行完毕]
  X --> N
```

### RAG 文档处理、检索与语义缓存流程图

```mermaid
flowchart TD
  A[上传文件到数据集] --> B[保存文件元数据]
  B --> C[进入异步处理队列]
  C --> D[文档解析 / OCR]
  D --> E[切片与 Document Unit 生成]
  E --> F[Embedding 向量化]
  F --> G[写入知识库向量存储]

  G --> H[用户发起 RAG 对话]
  H --> I[计算 cache scope]
  I --> J[问题向量化]
  J --> K{查询缓存向量库<br/>cos_sim ≥ 0.92?}

  K -- 命中 --> L[读取 rag_query_cache<br/>缓存答案]
  L --> M[检查 TTL 是否过期]
  M -- 未过期 --> N[流式返回缓存答案<br/>跳过向量检索与 LLM]
  M -- 已过期 --> O[走完整 RAG 流程]

  K -- 未命中 --> O
  O --> P[语义召回 + Rerank + 过滤]
  P --> Q[拼接知识片段]
  Q --> R[注入对话上下文]
  R --> S[模型流式生成回答]
  S --> T[异步写入 rag_query_cache<br/>+ 缓存向量库]
```

#### RAG 语义缓存架构图

```mermaid
flowchart LR
  subgraph 写入路径
    W1[问题文本] -->|embed| W2[question embedding]
    W2 --> W3[(rag_query_cache_vector_store\npgvector)]
    W2 -. metadata: rag_scope / cache_id .-> W3
    W1 --> W4[(rag_query_cache\nPostgreSQL)]
    W4 -. 存储答案文本 .-> W4
  end

  subgraph 查询路径
    Q1[新问题] -->|embed| Q2[query embedding]
    Q2 -->|cosine search\nfilter: rag_scope| W3
    W3 -->|匹配 score ≥ threshold| Q3[取出 cache_id]
    Q3 --> W4
    W4 -->|答案文本| Q4[直接返回给用户]
    W3 -->|score < threshold| Q5[调用完整 RAG + LLM 流程]
    Q5 -->|完成后异步| W1
  end
```

### 长期记忆流程图

```mermaid
flowchart TD
  A[用户发消息] --> B[Agent 正常聊天]
  B --> C[对话成功结束]
  C --> D[onChatCompleted]
  D --> E[异步调用 MemoryExtractorService]
  E --> F[抽取候选记忆]
  F --> G[MemoryDomainService.saveMemories]
  G --> H[写入记忆元数据]
  G --> I[生成向量并写入记忆库]

  J[下一次用户再发消息] --> K[构建历史消息]
  K --> L[搜索相关长期记忆]
  L --> M[向量召回 + 重要性排序]
  M --> N[生成记忆摘要]
  N --> O[注入系统提示词]
  O --> P[模型基于记忆继续回答]
```

### 定时任务流程图

```mermaid
flowchart TD
  A[用户创建定时任务] --> B[ScheduledTaskAppService.createScheduledTask]
  B --> C[TaskScheduleService 计算下次执行时间]
  C --> D[保存任务定义]
  D --> E[放入延迟队列]
  E --> F[到期后消费线程取出任务]
  F --> G[ScheduleTaskExecutor.executeTask]
  G --> H[发布 ScheduledTaskExecuteEvent]
  H --> I[ConversationEventListener 监听事件]
  I --> J[构造 ChatRequest]
  J --> K[ConversationAppService.chat]
  K --> L[按标准聊天链路执行 Agent]
  L --> M[记录本次执行时间]
  M --> N[计算下一次执行时间]
```

### 模型选择流程图

```mermaid
flowchart TD
  A[用户发起聊天] --> B[prepareEnvironmentWithModel]
  B --> C{请求是否显式指定 modelId}
  C -- 是 --> D[直接使用指定 modelId]
  C -- 否 --> E{Agent 工作区是否配置模型}
  E -- 是 --> F[使用工作区 modelId]
  E -- 否 --> G[读取用户默认模型]
  D --> H[获取模型配置]
  F --> H
  G --> H
  H --> I[校验模型可用性]
  I --> J[读取 fallbackChain]
  J --> K[高可用服务选择 provider]
  K --> L[返回 provider + model + instanceId]
  L --> M[写入 ChatContext]
  M --> N[创建实际 LLM 客户端]
  N --> O[开始推理]
```

## Token 超限治理

长对话是 Agent 系统的基础问题之一。tuanshu-ai-agent 在上下文管理中支持多种 Token 超限策略：

- 无策略：直接发送完整上下文，适合短对话或手动管理场景
- 滑动窗口：按 Token 上限保留最新消息，成本低、处理快
- 摘要策略：将早期消息压缩为摘要，兼顾长期信息保留与上下文成本

### Token 管理逻辑

```mermaid
flowchart TD
  A[用户发送新消息] --> B[保存消息]
  B --> C[检查当前上下文 Token 使用量]
  C --> D{是否超过阈值}
  D -- 否 --> E[直接构建上下文]
  D -- 是 --> F{当前策略类型}
  F -- 无策略 --> G[继续执行 可能发生超限]
  F -- 滑动窗口 --> H[丢弃较早消息 保留最新窗口]
  F -- 摘要策略 --> I[生成历史摘要]
  H --> J[更新 active_messages]
  I --> K[更新 summary 与 active_messages]
  J --> E
  K --> E
  E --> L[发送给 LLM]
```

## 工程化特性

### 高可用与模型治理

- 支持多模型服务商接入
- 支持默认模型、工作区模型和显式请求模型的优先级选择
- 支持 fallbackChain 与高可用 provider 选择
- 支持网关式模型调用治理

### 异步处理与解耦

- 使用 RabbitMQ 解耦文档处理、异步事件和部分后台任务
- 定时任务通过延迟队列与事件机制接入主聊天链路
- 文档 OCR、切片、向量化采用异步处理流程

### 追踪与计费

- 对模型调用、工具调用、失败阶段与耗时进行 Trace 记录
- 对话结束后执行计费逻辑，支撑调用成本管理
- 支持订单与支付系统扩展

### RAG 语义查询缓存

对相似问题实现跨用户共享响应，显著降低重复推理开销：

- 每次 RAG 对话先对问题做向量化，与 `rag_query_cache_vector_store`（pgvector）做相似度检索
- 相似度 ≥ 0.92（可配置）视为命中，直接返回缓存答案，跳过知识库检索与 LLM 调用
- 缓存按 `rag_scope`（userRagId 或 datasetId 组合）隔离，不同知识库间互不干扰
- LLM 首次生成答案后异步写入缓存（`@Async`），不阻塞当前响应
- 支持 TTL 过期（默认 24 小时）和命中次数统计
- 开关与阈值均可通过环境变量动态控制（`RAG_QUERY_CACHE_ENABLED`、`RAG_QUERY_CACHE_THRESHOLD`）

```
性能对比（典型场景）
  缓存未命中：embed → pgvector 知识库检索 → Rerank → LLM 流式推理    ~2-5s
  缓存命中：  embed → pgvector 缓存检索 → 直接返回答案               ~100-300ms
```

### Skills 技能系统

Skills 在 LLM 选择工具之后、实际执行 MCP 工具之前注入自定义逻辑，实现对工具调用的无侵入增强。

#### 触发模式

| 模式 | 说明 |
|------|------|
| `TOOL_OVERRIDE` | 拦截同名 MCP 工具调用，改为执行 Skill 步骤链；LLM 无感知，仍然「以为」自己在调用原工具 |
| `STANDALONE` | Skill 以全新工具名暴露给 LLM，LLM 主动选择调用；步骤内仍可调用真实 MCP 工具 |

#### 步骤类型

| 类型 | 说明 |
|------|------|
| `CALL_TOOL` | 调用一个 MCP 工具，结果存入上下文 `stepN.result` |
| `TRANSFORM` | 对上一步结果做文本变换，支持 `${prev.result}`、`${stepN.result}`、`${input.param}` 占位符 |
| `CONDITION` | 条件判断（`contains:keyword` / `not_contains:keyword`），不满足则终止执行链 |

#### 执行流程

```mermaid
flowchart TD
    LLM[LLM 发起工具调用] --> SAP[SkillAwareToolProvider]
    SAP -->|TOOL_OVERRIDE 已配置?| CKOVR{检查 SkillRegistry}
    CKOVR -->|命中| ENGINE[SkillExecutionEngine 执行步骤链]
    CKOVR -->|未命中| MCP[原始 MCP 工具执行器]
    SAP -->|STANDALONE Skill| STD[注册为新工具 <br/> LLM 直接选用]
    STD --> ENGINE2[SkillExecutionEngine 执行步骤链]
    ENGINE --> RESULT[返回结果给 LLM]
    ENGINE2 --> RESULT
    MCP --> RESULT

    ENGINE -->|CALL_TOOL 步骤| MCP2[调用 MCP 工具获得中间结果]
    ENGINE2 -->|CALL_TOOL 步骤| MCP2
    MCP2 --> CTX[写入执行上下文 stepN.result]
    CTX --> ENGINE
```

#### 占位符语法

步骤定义中的 `paramMapping`（CALL_TOOL）和 `promptTemplate`（TRANSFORM）均支持 `${…}` 占位符：

| 占位符 | 含义 |
|--------|------|
| `${input.xxx}` | 初始输入参数中字段 `xxx` 的值 |
| `${step0.result}` | 第 0 步的输出结果 |
| `${prev.result}` | 上一步的输出结果（等价于 `${stepN-1.result}`） |

#### 步骤 JSON 示例

```json
[
  {
    "stepIndex": 0,
    "stepType": "CALL_TOOL",
    "description": "调用搜索工具获取原始结果",
    "toolName": "web_search",
    "paramMapping": { "query": "${input.query}" }
  },
  {
    "stepIndex": 1,
    "stepType": "CONDITION",
    "description": "确保搜索有结果",
    "condition": "not_contains:error"
  },
  {
    "stepIndex": 2,
    "stepType": "TRANSFORM",
    "description": "提炼关键信息",
    "promptTemplate": "请根据以下搜索结果提取关键信息：\n${step0.result}"
  }
]
```

#### REST API

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/skills` | 创建 Skill |
| `PUT` | `/skills/{id}` | 更新 Skill |
| `DELETE` | `/skills/{id}` | 删除 Skill |
| `GET` | `/skills?agentId=xxx` | 查询 Skill 列表（可按 agentId 过滤） |
| `POST` | `/skills/{id}/enable` | 启用 Skill |
| `POST` | `/skills/{id}/disable` | 禁用 Skill |
| `POST` | `/skills/{id}/test` | 测试执行（CALL_TOOL 步骤使用 stub，不调用真实 MCP） |

#### 创建请求示例

```json
{
  "name": "enhanced_search",
  "description": "带结果提炼的增强型搜索工具",
  "agentId": "agent-uuid-here",
  "triggerMode": "TOOL_OVERRIDE",
  "triggerTool": "web_search",
  "steps": "[{\"stepIndex\":0,\"stepType\":\"CALL_TOOL\",\"toolName\":\"web_search\",\"paramMapping\":{\"query\":\"${input.query}\"}},{\"stepIndex\":1,\"stepType\":\"TRANSFORM\",\"promptTemplate\":\"请提取关键信息：${step0.result}\"}]"
}
```

#### 架构要点

- **零侵入**：无需修改 LLM 提示词，`SkillAwareToolProvider` 在 `AgentToolManager` 创建工具提供者时自动包装 `McpToolProvider`
- **热重载**：Skill 增删改后调用 `SkillRegistry.reload()` 立即生效，无需重启
- **作用域**：`agentId = null` 表示全局 Skill，对所有 Agent 生效；非 null 仅对指定 Agent 生效
- **调用链**：STANDALONE Skill 的 `CALL_TOOL` 步骤可以调用同一 Agent 配置的任意 MCP 工具

### 容器与 MCP 运行环境

- 支持 MCP Gateway 统一管理工具能力
- 支持容器模板与用户容器隔离运行
- 支持工具以外部能力方式接入 Agent 对话过程

## 适用场景

- 企业内部知识问答与业务助理
- 可配置 Agent 市场与多租户 Agent 平台
- 带工具调用的流程型智能助手
- 需要长期记忆和定时执行能力的自动化 Agent
- 需要 Widget 嵌入或开放接入能力的 AI 产品

## 快速开始

### 一键部署

适合快速体验完整能力。

```bash
cp .env.example .env
```

根据需要修改 `.env`，然后启动服务：

```bash
docker run -d \
  --name tuanshu-ai-agent \
  -p 3000:3000 \
  -p 8088:8088 \
  -p 5432:5432 \
  -p 5672:5672 \
  -p 15672:15672 \
  --env-file .env \
  -v tuanshu-ai-agent-data:/var/lib/postgresql/data \
  -v tuanshu-ai-agent-storage:/app/storage \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --add-host=localhost:host-gateway \
  <your-tuanshu-ai-agent-image>
```

将 `<your-tuanshu-ai-agent-image>` 替换为实际可用的 tuanshu-ai-agent 镜像地址。

如果需要 API 高可用网关，可额外部署：

```bash
docker run -d \
  --name tuanshu-ai-agent-gateway \
  -p 8081:8081 \
  <your-gateway-image>
```

将 `<your-gateway-image>` 替换为实际可用的高可用网关镜像地址。

### 开发环境启动

```bash
cd deploy

# Linux / macOS
./start.sh

# Windows
start.bat
```

### 部署模式

| 模式 | 特点 | 适用场景 |
|------|------|------|
| `local` | 内置 PostgreSQL，适合本地开发 | 日常开发调试 |
| `production` | 生产优化配置 | 中小型生产部署 |
| `external` | 连接外部 PostgreSQL | 数据库分离部署 |
| `dev` | 带数据库管理工具 | 需要调试管理界面 |

### 默认账号

- 管理员：`admin@tuanshu-ai-agent.ai` / `admin123`
- 测试用户：`test@tuanshu-ai-agent.ai` / `test123`

### 访问地址

| 服务 | 地址 | 说明 |
|------|------|------|
| 主应用 | http://localhost:3000 | 前端界面 |
| 后端 API | http://localhost:8088 | 接口服务 |
| PostgreSQL | localhost:5432 | 数据库端口 |
| RabbitMQ | amqp://localhost:5672 | 消息队列端口 |
| RabbitMQ 管理台 | http://localhost:15672 | 队列管理界面 |

## 环境变量

项目通过 `.env` 管理配置，优先关注以下项目：

| 配置项 | 说明 |
|------|------|
| `SERVER_PORT` | 后端端口 |
| `DB_PASSWORD` | PostgreSQL 密码 |
| `RABBITMQ_PASSWORD` | RabbitMQ 密码 |
| `JWT_SECRET` | JWT 密钥，生产环境必须修改 |
| `TUANSHU_AI_AGENT_ADMIN_PASSWORD` | 管理员密码 |
| `EXTERNAL_DB_HOST` | 外部数据库地址 |
| `EXTERNAL_RABBITMQ_HOST` | 外部消息队列地址 |

完整配置请查看 `.env.example`。

### 生产环境建议

- 修改默认账号密码与 JWT 密钥
- 为数据库和 RabbitMQ 设置独立密码与访问控制
- 通过反向代理启用 HTTPS
- 限制数据库与消息队列端口的外部暴露
- 为后端、数据库和容器运行环境增加监控与日志采集

## 文档入口

| 文档 | 说明 |
|------|------|
| `docs/agent_design.md` | Agent 模块设计文档 |
| `docs/token_overflow_strategy.md` | Token 超限处理方案 |
| `deploy/README.md` | 开发环境部署说明 |
| `production/docker-compose.yml` | 生产部署基础配置 |
| `tuanshu-ai-agent/docs/` | 后端模块专题文档 |

## 总结

tuanshu-ai-agent 的重点不在于“接了一个大模型”，而在于把 Agent 配置、对话上下文、工具执行、RAG 检索、长期记忆、任务调度和工程化运维能力编排到一套统一平台中。这使其既适合作为 AI Agent 产品原型，也适合作为具备扩展性的工程化基础设施项目。