diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..fbb04696
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,300 @@
+# BuildingAI - Agent Coding Guidelines
+
+This document provides essential information for agentic coding assistants working in this repository.
+
+## Essential Commands
+
+### Building
+```bash
+# Build all packages
+pnpm run build
+
+# Build specific package
+cd packages/api && pnpm run build
+cd packages/web/buildingai-ui && pnpm run generate
+```
+
+### Development
+```bash
+# Start all services (API + Web)
+pnpm dev
+
+# Start specific service
+pnpm dev:api        # NestJS API backend (port 4090)
+pnpm dev:web        # Nuxt 4 frontend (port 4091)
+```
+
+### Linting & Formatting
+```bash
+# Lint all packages
+pnpm run lint
+pnpm run lint:fix   # Auto-fix lint issues
+
+# Format code
+pnpm run format     # Prettier formatting
+
+# Type checking
+pnpm run typecheck  # TypeScript type validation
+```
+
+### Testing
+```bash
+# Run all tests
+cd packages/api && pnpm test
+
+# Run specific test file
+jest path/to/test.spec.ts
+
+# Run tests in watch mode
+pnpm test:watch
+
+# Run tests with coverage
+pnpm test:cov
+
+# Debug tests
+pnpm test:debug
+```
+
+### Docker
+```bash
+# Start PostgreSQL and Redis containers
+pnpm docker:up
+
+# Stop containers
+pnpm docker:down
+```
+
+## Code Style Guidelines
+
+### Formatting (Prettier)
+- Print width: 100 characters
+- Tab width: 4 spaces
+- Semicolons: required
+- Quotes: double quotes (not single)
+- Trailing commas: all
+- End of line: LF (Unix-style)
+
+### ESLint Configuration
+- Uses TypeScript ESLint with flat config
+- `@typescript-eslint/no-explicit-any`: off
+- `@typescript-eslint/no-unsafe-*`: off/warn
+- `@typescript-eslint/no-floating-promises`: warn
+- `no-undef`: off (TypeScript handles this)
+
+### Naming Conventions
+- **Classes/PascalCase**: `TagService`, `CreateTagDto`, `TagController`
+- **Variables/Functions/camelCase**: `tagService`, `createTag`, `findById`
+- **Files/kebab-case**: `tag.service.ts`, `create-tag.dto.ts`, `tag.controller.ts`
+- **Constants/SCREAMING_SNAKE_CASE**: `TAG_TYPE`, `MAX_RETRY_COUNT`
+- **Interfaces/PascalCase**: `TagService`, `TagController`, `IOptions` (if needed)
+
+### Import Organization
+Order imports in this specific sequence:
+1. Node.js built-in modules
+2. Third-party packages
+3. Internal @buildingai packages (workspace:*)
+4. Internal @modules and @common imports
+5. Relative imports (./ or ../)
+
+Example:
+```typescript
+import fs from "node:fs";
+import { Injectable } from "@nestjs/common";
+import { BaseService } from "@buildingai/base";
+import { HttpErrorFactory } from "@buildingai/errors";
+import { CreateTagDto } from "@modules/tag/dto";
+import { findStackTargetFile } from "@common/utils";
+```
+
+### JSDoc Comments
+Always add JSDoc comments for classes and public methods:
+```typescript
+/**
+ * Tag service for managing tag entities
+ */
+@Injectable()
+export class TagService extends BaseService<Tag> {
+    /**
+     * Create a new tag
+     *
+     * @param createTagDto - DTO for creating a tag
+     * @returns The created tag
+     */
+    async createTag(createTagDto: CreateTagDto): Promise<Partial<Tag>> {
+        // Implementation
+    }
+}
+```
+
+### Error Handling
+Use the centralized error factory:
+```typescript
+// Services: throw errors directly
+throw HttpErrorFactory.badRequest("A tag with the same name already exists");
+throw HttpErrorFactory.notFound(`Tag ${id} does not exist`);
+
+// Controllers: try-catch and return response objects
+async batchRemove(@Body("ids") ids: string[]) {
+    try {
+        await this.tagService.batchDelete(ids);
+        return { success: true, message: "Batch deletion succeeded" };
+    } catch (error) {
+        return { success: false, message: error.message };
+    }
+}
+```
+
+### TypeScript Best Practices
+- Always use type annotations for function parameters and return values
+- Prefer `type` over `interface` unless you need interface features
+- Use utility types: `Partial`, `Pick`, `Omit`, `Record`
+- Avoid `any` when possible; use `unknown` for truly dynamic data
+
+## Backend (NestJS) Patterns
+
+### Module Structure
+```
+modules/feature-name/
+├── feature-name.module.ts      # Module definition
+├── controllers/
+│   ├── console/               # Admin/management endpoints
+│   └── web/                   # Public/client endpoints
+├── services/
+│   └── feature-name.service.ts # Business logic
+├── dto/                       # Data Transfer Objects
+│   ├── create-feature.dto.ts
+│   ├── update-feature.dto.ts
+│   └── query-feature.dto.ts
+└── interfaces/                # TypeScript interfaces (if needed)
+```
+
+### Service Patterns
+```typescript
+@Injectable()
+export class FeatureService extends BaseService<Feature> {
+    constructor(@InjectRepository(Feature) private readonly repo: Repository<Feature>) {
+        super(repo);
+    }
+
+    async createFeature(dto: CreateFeatureDto): Promise<Partial<Feature>> {
+        // Validation
+        const existing = await this.repo.findOne({ where: { name: dto.name } });
+        if (existing) {
+            throw HttpErrorFactory.badRequest("Name already exists");
+        }
+
+        // Create
+        return super.create(dto);
+    }
+}
+```
+
+### Controller Patterns
+```typescript
+@Controller("feature")
+export class FeatureController extends BaseController {
+    constructor(private readonly featureService: FeatureService) {
+        super();
+    }
+
+    @Get()
+    async findAll(@Query() queryDto: QueryFeatureDto) {
+        return this.featureService.list(queryDto);
+    }
+
+    @Post()
+    async create(@Body() createDto: CreateFeatureDto) {
+        return this.featureService.createFeature(createDto);
+    }
+}
+```
+
+### DTO Validation
+```typescript
+import { IsString, IsOptional, Length } from "class-validator";
+
+export class CreateFeatureDto {
+    @IsString({ message: "Name must be a string" })
+    @Length(1, 100, { message: "Name length must be between 1 and 100" })
+    name: string;
+
+    @IsOptional()
+    @IsString()
+    description?: string;
+}
+```
+
+## Frontend (Nuxt 4) Patterns
+
+### File Structure
+```
+app/
+├── pages/                     # File-based routing
+│   ├── console/              # Admin console pages
+│   └── index.vue
+├── components/               # Reusable components
+├── layouts/                  # Layout components
+├── middleware/               # Route middleware
+├── stores/                   # Pinia stores
+└── utils/                    # Utility functions
+```
+
+### Component Naming
+- Use PascalCase for component filenames: `UserCard.vue`, `DataTable.vue`
+- Use kebab-case in templates: `<user-card />`, `<data-table />`
+
+### Type Definitions
+```typescript
+// interfaces/api.ts
+export interface User {
+    id: string;
+    name: string;
+    email: string;
+}
+
+export interface ApiResponse<T> {
+    code: number;
+    message: string;
+    data: T;
+}
+```
+
+## Monorepo Architecture
+
+This is a pnpm workspace with Turbo for build orchestration:
+- `packages/@buildingai/*`: Shared packages (22 packages)
+- `packages/api`: NestJS backend
+- `packages/web/buildingai-ui`: Nuxt 4 frontend
+- `packages/cli`: CLI tools
+- `extensions/`: Extension plugins
+
+When adding internal imports, always use workspace protocol:
+```json
+{
+  "dependencies": {
+    "@buildingai/base": "workspace:*",
+    "@buildingai/errors": "workspace:*"
+  }
+}
+```
+
+## Environment Requirements
+- **Node.js**: >=22.20.x <23
+- **pnpm**: 10.x
+- **PostgreSQL**: 17.x
+- **Redis**: 8.x
+
+## Before Committing
+Always run:
+```bash
+pnpm run lint       # Ensure no lint errors
+pnpm run typecheck  # Ensure TypeScript compiles
+pnpm test           # Ensure tests pass (if applicable)
+```
+
+## Key Technologies
+- **Backend**: NestJS 11.x, TypeORM 0.3.x, BullMQ 5.x
+- **Frontend**: Nuxt 4, Vue 3.5.x, Pinia 3.x, NuxtUI 3.x
+- **Database**: PostgreSQL 17.x with pgvector extension
+- **Cache**: Redis 8.x
+- **Build**: Turbo 2.6.x, Vite 7.2.x, SWC
diff --git "a/\346\236\266\346\236\204\350\256\276\350\256\241\346\226\207\346\241\243.md" "b/\346\236\266\346\236\204\350\256\276\350\256\241\346\226\207\346\241\243.md"
new file mode 100644
index 00000000..5fff0cc0
--- /dev/null
+++ "b/\346\236\266\346\236\204\350\256\276\350\256\241\346\226\207\346\241\243.md"
@@ -0,0 +1,1003 @@
+# BuildingAI 技术架构文档
+
+> **BuildingAI** - 企业级开源智能体搭建平台
+>
+> 版本：v25.3.0
+>
+> 文档更新时间：2026-01-23
+
+---
+
+## 目录
+
+- [项目概述](#项目概述)
+- [技术栈](#技术栈)
+    - [前端技术栈](#前端技术栈)
+    - [后端技术栈](#后端技术栈)
+    - [基础设施](#基础设施)
+    - [开发工具](#开发工具)
+- [架构设计](#架构设计)
+    - [Monorepo 架构](#monorepo-架构)
+    - [后端架构](#后端架构)
+    - [前端架构](#前端架构)
+    - [扩展机制](#扩展机制)
+- [核心模块](#核心模块)
+    - [AI 模块](#ai-模块)
+    - [用户认证与授权](#用户认证与授权)
+    - [会员体系](#会员体系)
+    - [支付与充值](#支付与充值)
+- [数据库设计](#数据库设计)
+    - [实体分类](#实体分类)
+    - [数据库技术](#数据库技术)
+- [前端技术细节](#前端技术细节)
+    - [路由与权限系统](#路由与权限系统)
+    - [状态管理](#状态管理)
+    - [HTTP 客户端](#http-客户端)
+    - [插件系统](#插件系统)
+- [后端技术细节](#后端技术细节)
+    - [启动流程](#启动流程)
+    - [守卫体系](#守卫体系)
+    - [统一响应处理](#统一响应处理)
+    - [AI SDK 架构](#ai-sdk-架构)
+- [前后端交互](#前后端交互)
+- [部署架构](#部署架构)
+- [技术亮点](#技术亮点)
+
+---
+
+## 项目概述
+
+BuildingAI 是一款面向 AI 开发者、AI 创业者和先进组织打造的企业级开源智能体搭建平台。通过可视化配置界面（Do
+It
+Yourself）零代码搭建具备智能体、MCP、RAG 管道、知识库、大模型聚合、上下文工程等原生 AI 能力，以及用户注册、会员订阅、算力计费等商业闭环能力的原生企业智能体应用。
+
+### 核心特性
+
+- **AI 对话**：基于 LLM 模型进行对话、文本生成，支持多模态模型调用
+- **AI 智能体**：支持创建具备记忆、目标和工具使用能力的智能体，实现自主任务执行
+- **知识库**：通过文档构建知识库，支持向量检索与 RAG 增强生成
+- **MCP 调用**：支持以 SSE、StreamableHTTP 方式调用 MCP 工具
+- **模型管理**：支持主流大模型集成，统一 API 规范
+- **拓展机制**：通过安装拓展丰富系统功能和 AI 能力
+- **充值计费**：内置会员管理、计费管理、支付功能，开箱即用
+
+---
+
+## 技术栈
+
+### 前端技术栈
+
+| 类别           | 技术           | 版本   | 用途                             |
+| -------------- | -------------- | ------ | -------------------------------- |
+| **框架**       | Nuxt 4         | 4.1.2  | Vue 元框架，支持 SSR/SPA         |
+| **核心库**     | Vue.js         | 3.5.24 | 渐进式 JavaScript 框架           |
+| **UI 库**      | NuxtUI         | 3.3.7  | 基于 Radix Vue 的组件库          |
+| **样式**       | TailwindCSS    | 4.1.17 | 原子化 CSS 框架                  |
+| **构建工具**   | Vite           | 7.2.2  | 新一代前端构建工具               |
+| **状态管理**   | Pinia          | 3.0.4  | Vue 官方状态管理库               |
+| **富文本**     | TipTap         | 2.27.1 | 无头富文本编辑器                 |
+| **拖拽**       | VueDraggable   | 4.1.0  | 基于 Sortable.js 的 Vue 拖拽组件 |
+| **画布**       | Panzoom        | 9.4.3  | 支持 SVG/HTML 元素的缩放和平移   |
+| **HTTP**       | Axios          | 1.13.2 | HTTP 客户端                      |
+| **图表**       | ECharts        | 5.6.0  | 数据可视化库                     |
+| **国际化**     | @nuxtjs/i18n   | 10.2.0 | Vue I18n 集成                    |
+| **PWA**        | @vite-pwa/nuxt | 0.10.8 | PWA 支持                         |
+| **TypeScript** | TypeScript     | 5.9.2  | 类型安全                         |
+
+### 后端技术栈
+
+| 类别           | 技术             | 版本   | 用途                  |
+| -------------- | ---------------- | ------ | --------------------- |
+| **框架**       | NestJS           | 11.1.8 | Node.js 企业级框架    |
+| **语言**       | TypeScript       | 5.9.2  | 类型安全的 JavaScript |
+| **ORM**        | TypeORM          | 0.3.27 | TypeScript ORM        |
+| **数据库**     | PostgreSQL       | 17.x   | 关系型数据库          |
+| **向量数据库** | pgvector         | 0.8.1  | PostgreSQL 向量扩展   |
+| **缓存**       | Redis            | 8.x    | 内存数据库            |
+| **任务队列**   | BullMQ           | 5.63.0 | 基于 Redis 的任务队列 |
+| **认证**       | @nestjs/jwt      | 11.0.1 | JWT 认证              |
+| **验证**       | class-validator  | 0.14.2 | 基于装饰器的验证      |
+| **调度**       | @nestjs/schedule | 6.0.1  | 定时任务调度          |
+| **监控**       | @nestjs/terminus | 11.0.0 | 健康检查和监控        |
+| **文件处理**   | Multer           | 2.0.2  | 文件上传中间件        |
+| **CSV 解析**   | XLSX             | 0.18.5 | Excel 文件处理        |
+| **PDF 解析**   | pdf-parse        | 1.1.4  | PDF 文件解析          |
+| **中文分词**   | @node-rs/jieba   | 2.0.1  | Rust 实现的中文分词   |
+
+### 基础设施
+
+| 服务        | 版本    | 用途                                   |
+| ----------- | ------- | -------------------------------------- |
+| **Node.js** | 22.20.x | JavaScript 运行时                      |
+| **pnpm**    | 10.20.0 | 快速、节省磁盘空间的包管理器           |
+| **Turbo**   | 2.6.0   | JavaScript/TypeScript 单体仓库构建系统 |
+| **PM2**     | 6.0.13  | Node.js 进程管理器                     |
+| **Docker**  | Latest  | 容器化部署（可选）                     |
+
+### 开发工具
+
+| 工具          | 版本   | 用途                    |
+| ------------- | ------ | ----------------------- |
+| **ESLint**    | 9.39.1 | 代码质量检查            |
+| **Prettier**  | 3.6.2  | 代码格式化              |
+| **Vue TSC**   | 2.2.12 | Vue TypeScript 类型检查 |
+| **Storybook** | 9.1.8  | UI 组件文档和测试       |
+| **SWC**       | Latest | 超快 JavaScript 编译器  |
+
+---
+
+## 架构设计
+
+### Monorepo 架构
+
+BuildingAI 采用 Monorepo 架构，使用 **pnpm workspace** 进行包管理，**Turbo** 进行构建优化。
+
+```
+BuildingAI/
+├── packages/
+│   ├── @buildingai/          # 共享基础包 (22个)
+│   │   ├── ai-sdk           # AI 模型统一接口
+│   │   ├── alipay-sdk       # 支付宝支付
+│   │   ├── base             # 基础工具
+│   │   ├── cache            # 缓存服务
+│   │   ├── config           # 配置管理
+│   │   ├── constants        # 常量定义
+│   │   ├── db               # 数据库配置和实体
+│   │   ├── decorators       # 自定义装饰器
+│   │   ├── di               # 依赖注入
+│   │   ├── dict             # 字典服务
+│   │   ├── dto              # 数据传输对象
+│   │   ├── errors           # 错误处理
+│   │   ├── eslint-config    # ESLint 配置
+│   │   ├── extension-sdk    # 扩展开发 SDK
+│   │   ├── logger           # 日志服务
+│   │   ├── pipe             # 数据管道
+│   │   ├── types            # TypeScript 类型定义
+│   │   ├── typescript-config # TypeScript 配置
+│   │   ├── upgrade          # 升级工具
+│   │   ├── utils            # 工具函数
+│   │   └── wechat-sdk       # 微信支付
+│   ├── api/                 # NestJS 后端
+│   ├── web/                 # Nuxt 4 前端
+│   │   ├── buildingai-ui/   # 主应用
+│   │   └── @buildingai/     # 前端共享包 (14个)
+│   │       ├── designer       # 可视化设计器
+│   │       ├── hooks         # 自定义 Hooks
+│   │       ├── http          # HTTP 客户端
+│   │       ├── i18n-config   # 国际化配置
+│   │       ├── layouts       # 布局组件
+│   │       ├── nuxt          # Nuxt 模块
+│   │       ├── service       # 业务服务
+│   │       ├── stores        # 状态管理
+│   │       ├── storybook     # 组件文档
+│   │       ├── ui            # UI 组件库
+│   │       ├── upload        # 上传组件
+│   │       └── web-config    # Web 配置
+│   ├── cli/                 # 命令行工具
+│   ├── core/                # 核心模块
+│   └── desktop/             # Tauri 桌面应用
+├── extensions/              # 扩展插件
+│   └── buildingai-simple-blog/
+├── docker/                 # Docker 配置
+├── public/                 # 静态资源
+├── scripts/                # 脚本工具
+├── templates/              # 模板文件
+├── storage/                # 存储目录
+├── package.json            # 根 package.json
+├── pnpm-workspace.yaml    # pnpm workspace 配置
+├── turbo.json             # Turbo 配置
+└── docker-compose.yml     # Docker Compose 配置
+```
+
+### 后端架构
+
+#### 模块化设计
+
+基于 NestJS 的模块化架构，主要业务模块：
+
+```
+packages/api/src/modules/
+├── ai/                    # AI 能力模块
+│   ├── agent/              # 智能体管理
+│   ├── chat/               # 对话管理
+│   ├── datasets/           # 知识库管理
+│   ├── mcp/                # MCP 工具调用
+│   ├── model/              # 模型管理
+│   ├── provider/           # AI 提供商管理
+│   └── secret/             # 密钥管理
+├── analyse/                # 数据分析
+├── auth/                   # 认证授权
+├── channel/                # 渠道管理
+├── config/                 # 系统配置
+├── decorate/               # 装饰管理
+├── extension/              # 扩展管理
+├── finance/                # 财务管理
+├── health/                 # 健康检查
+├── membership/             # 会员体系
+├── menu/                   # 菜单管理
+├── pay/                    # 支付集成
+├── permission/             # 权限管理
+├── pm2/                    # PM2 管理
+├── recharge/               # 充值管理
+├── role/                   # 角色管理
+├── schedule/               # 定时任务
+├── system/                 # 系统管理
+├── tag/                    # 标签管理
+├── upload/                 # 文件上传
+└── user/                   # 用户管理
+```
+
+#### 目录结构
+
+```
+packages/api/src/
+├── main.ts                # 应用启动入口
+├── modules/               # 业务模块
+├── common/                # 公共模块
+│   ├── constants/         # 常量定义
+│   ├── decorators/       # 自定义装饰器
+│   ├── filters/          # 异常过滤器
+│   ├── guards/           # 守卫（权限控制）
+│   ├── interceptors/     # 拦截器
+│   ├── interfaces/       # 接口定义
+│   └── utils/           # 工具函数
+└── core/                 # 核心模块
+    ├── database/         # 数据库初始化
+    ├── logger/           # 日志服务
+    └── queue/           # 任务队列
+```
+
+### 前端架构
+
+#### 应用结构
+
+```
+packages/web/buildingai-ui/app/
+├── pages/                 # 页面路由（文件路由）
+│   ├── console/          # 管理后台（动态路由）
+│   ├── login/            # 登录页
+│   ├── install/          # 系统初始化
+│   └── index.vue         # 首页
+├── components/            # 组件库
+├── layouts/              # 布局组件
+├── plugins/              # Nuxt 插件
+├── middleware/           # 路由中间件
+├── stores/               # Pinia 状态管理
+├── utils/                # 工具函数
+├── assets/               # 静态资源
+│   ├── icons/            # 图标（自定义 collection）
+│   └── styles/           # 全局样式
+├── types/                # TypeScript 类型
+├── i18n/                # 国际化文件
+└── app.vue              # 根组件
+```
+
+### 扩展机制
+
+#### 后端扩展
+
+每个扩展拥有独立的 PostgreSQL Schema，实现数据隔离：
+
+```typescript
+// 1. 扫描 extensions 目录
+getEnabledExtensionsFromConfig();
+
+// 2. 初始化扩展缓存
+initExtensionCache();
+
+// 3. 为每个扩展创建独立的 Schema
+createExtensionSchemas();
+
+// 4. 动态注册扩展模块
+await ExtensionCoreModule.register();
+```
+
+#### 前端插件
+
+基于插槽机制的插件系统：
+
+```typescript
+defineNuxtPlugin(() => {
+    definePlugin({
+        id: "agent-third-party-integration",
+        contributions: [
+            {
+                id: "dify-config",
+                slot: "agent:config:third-party",
+                component: () => import("xxx.vue"),
+                meta: { platform: "dify", label: "Dify" },
+                order: 1,
+            },
+        ],
+    });
+});
+```
+
+**支持的插槽类型**：
+
+- `agent:config:third-party` - 智能体第三方配置
+- `agent:config:advanced` - 智能体高级配置
+- `chat:message:actions` - 对话消息操作按钮
+- `console:menu` - 控制台菜单扩展
+
+---
+
+## 核心模块
+
+### AI 模块
+
+#### 智能体管理 (Agent)
+
+- **智能体配置**：创建、编辑、删除智能体
+- **智能体执行**：基于目标和工具的自主任务执行
+- **智能体记忆**：短期和长期记忆管理
+- **第三方集成**：支持 Dify、Coze 等第三方平台
+
+#### 对话管理 (Chat)
+
+- **流式对话**：SSE / StreamableHTTP
+- **对话历史**：消息记录与检索
+- **多模态支持**：文本、图片、语音
+- **实时渲染**：Markdown + 代码高亮
+
+#### 知识库管理 (Datasets)
+
+- **文档上传**：支持 PDF、Word、Excel、Markdown
+- **文档解析**：文本提取、分块处理
+- **向量化**：Embedding 生成（支持多种模型）
+- **向量检索**：相似度搜索、RAG 增强
+- **全文检索**：PostgreSQL 全文搜索
+
+#### MCP 工具调用
+
+- **MCP 服务器管理**：添加、配置、启用 MCP 服务器
+- **工具列表**：自动获取可用工具
+- **工具调用**：SSE / StreamableHTTP 协议
+- **调用历史**：工具使用记录
+
+#### 模型管理
+
+- **提供商管理**：OpenAI、通义千问、文心一言、智谱 AI、Moonshot、DeepSeek、Google、火山引擎等
+- **模型配置**：API Key、参数配置
+- **模型选择**：按场景推荐模型
+- **成本统计**：Token 使用量与费用
+
+### 用户认证与授权
+
+#### JWT 认证
+
+- **登录**：用户名/密码 + JWT 生成
+- **Token 管理**：存储在 `user_token` 表
+- **滑动刷新**：Token 即将过期时自动续签
+- **多端登录**：支持多个 Token
+
+#### RBAC 权限
+
+- **角色**：超级管理员、管理员、普通用户
+- **权限**：基于权限码的细粒度控制
+- **菜单**：动态菜单生成
+- **守卫**：6 层权限守卫体系
+
+### 会员体系
+
+#### 会员等级
+
+- **等级配置**：创建会员等级（如 VIP、SVIP）
+- **权益配置**：每个等级对应的权益（AI 对话次数、存储空间等）
+- **等级升级**：基于订单自动升级
+
+#### 会员订阅
+
+- **套餐管理**：创建订阅套餐（月付、年付）
+- **套餐关联**：套餐与会员等级关联
+- **订阅订单**：订单创建、支付、生效
+
+#### 用户订阅
+
+- **订阅记录**：用户订阅历史
+- **自动续费**：支持开启自动续费
+- **权益使用**：统计已使用的权益
+
+### 支付与充值
+
+#### 支付集成
+
+- **支付宝**：扫码支付、网页支付
+- **微信支付**：扫码支付、小程序支付
+- **支付回调**：异步通知处理
+- **退款功能**：订单退款
+
+#### 充值管理
+
+- **充值记录**：充值流水记录
+- **余额查询**：用户当前余额
+- **充值订单**：充值订单状态管理
+
+#### 财务管理
+
+- **账户日志**：所有收支记录
+- **财务统计**：收入、支出统计
+- **退款日志**：退款记录
+
+---
+
+## 数据库设计
+
+### 实体分类
+
+#### AI 核心
+
+| 实体                    | 说明                |
+| ----------------------- | ------------------- |
+| `ai-agent`              | 智能体配置          |
+| `ai-agent-chat-record`  | 智能体对话记录      |
+| `ai-agent-chat-message` | 智能体对话消息      |
+| `ai-chat-record`        | 普通对话记录        |
+| `ai-chat-message`       | 普通对话消息        |
+| `ai-model`              | AI 模型配置         |
+| `ai-provider`           | AI 提供商配置       |
+| `ai-mcp-server`         | MCP 服务器配置      |
+| `ai-mcp-tool`           | MCP 工具列表        |
+| `ai-user-mcp-server`    | 用户 MCP 服务器关联 |
+| `ai-agent-annotation`   | 智能体标注          |
+
+#### 知识库
+
+| 实体                | 说明           |
+| ------------------- | -------------- |
+| `datasets`          | 知识库         |
+| `datasets-document` | 文档           |
+| `datasets-segments` | 文档分块       |
+| `datasets-member`   | 知识库成员权限 |
+
+#### 用户体系
+
+| 实体                | 说明       |
+| ------------------- | ---------- |
+| `user`              | 用户       |
+| `user-token`        | 用户 Token |
+| `user-subscription` | 用户订阅   |
+
+#### 权限控制
+
+| 实体         | 说明 |
+| ------------ | ---- |
+| `role`       | 角色 |
+| `permission` | 权限 |
+| `menu`       | 菜单 |
+
+#### 会员体系
+
+| 实体                | 说明     |
+| ------------------- | -------- |
+| `membership-plans`  | 会员套餐 |
+| `membership-levels` | 会员等级 |
+| `membership-order`  | 会员订单 |
+
+#### 财务
+
+| 实体             | 说明     |
+| ---------------- | -------- |
+| `recharge`       | 充值配置 |
+| `recharge-order` | 充值订单 |
+| `refund-log`     | 退款日志 |
+| `account-log`    | 账户日志 |
+
+#### 扩展
+
+| 实体                 | 说明       |
+| -------------------- | ---------- |
+| `extension`          | 扩展信息   |
+| `extension-feature`  | 扩展功能   |
+| `decorate-micropage` | 装饰微页面 |
+| `decorate-page`      | 装饰页面   |
+
+#### 其他
+
+| 实体              | 说明     |
+| ----------------- | -------- |
+| `dict`            | 字典     |
+| `tag`             | 标签     |
+| `file`            | 文件     |
+| `secret`          | 密钥     |
+| `secret-template` | 密钥模板 |
+| `storage-config`  | 存储配置 |
+| `payconfig`       | 支付配置 |
+| `analyse`         | 分析统计 |
+
+### 数据库技术
+
+- **PostgreSQL 17**：主数据库
+- **pgvector 0.8.1**：向量扩展，用于 RAG 检索
+- **zhparser**：中文分词扩展，用于全文搜索
+- **Schema 隔离**：每个扩展使用独立 Schema
+- **TypeORM**：ORM 框架，支持装饰器定义实体
+- **迁移**：自动生成和应用数据库迁移
+
+---
+
+## 前端技术细节
+
+### 路由与权限系统
+
+#### 全局路由中间件
+
+```typescript
+// packages/web/buildingai-ui/app/middleware/route.global.ts
+
+export default defineNuxtRouteMiddleware(async (to, from) => {
+    // 1. 系统初始化检查
+    const initRedirect = await appStore.checkSystemInitialization(to.path);
+    if (initRedirect) return initRedirect;
+
+    // 2. 登录和重定向控制
+    const authRedirect = await handleAuth();
+    if (authRedirect) return authRedirect;
+
+    // 3. 控制台菜单预检查
+    if (permissionStore.menus?.length && isConsoleMenuMatched(to.fullPath)) {
+        return;
+    }
+
+    // 4. 加载权限和注册控制台路由
+    await permissionStore.loadPermissions();
+    const routes = buildRoutes(permissionStore.menus, userStore.userInfo?.isRoot, modules);
+    routes.forEach((route) => router.addRoute(route));
+
+    // 5. 权限验证
+    if (to.meta.permissionCode && !permissionStore.hasPermission(to.meta.permissionCode)) {
+        return ROUTES.FORBIDDEN;
+    }
+
+    // 6. 匹配注册后的路由
+    if (!isConsoleMenuMatched(to.fullPath)) {
+        return "/not-found";
+    }
+
+    return to.fullPath;
+});
+```
+
+#### 动态路由生成
+
+```typescript
+const routes = buildRoutes(
+    permissionStore.menus, // 从 API 获取的菜单数据
+    userStore.userInfo?.isRoot, // 是否超级管理员
+    modules, // 控制台页面模块
+);
+```
+
+### 状态管理
+
+#### 核心 Store
+
+| Store        | 职责       | 关键方法                                           |
+| ------------ | ---------- | -------------------------------------------------- |
+| `app`        | 应用状态   | `checkSystemInitialization()`, `getSystemConfig()` |
+| `user`       | 用户信息   | `getUser()`, `refreshToken()`, `logout()`          |
+| `permission` | 权限控制   | `loadPermissions()`, `hasPermission()`             |
+| `controls`   | 控制器状态 | 对话控制、上传控制等                               |
+
+#### 状态持久化
+
+使用 `pinia-plugin-persistedstate` 自动同步到 localStorage。
+
+### HTTP 客户端
+
+#### 请求拦截器
+
+```typescript
+// 自动添加 Authorization: Bearer {token}
+// 处理响应头 x-new-token → 自动更新本地 token
+// 统一错误处理 → Toast 提示
+```
+
+#### 响应拦截器
+
+```typescript
+// 统一解析 { code, message, data, timestamp } 格式
+// code === BusinessCode.SUCCESS → 返回 data
+// code !== SUCCESS → 抛出 HttpError
+```
+
+#### 类型安全
+
+完整的 TypeScript 类型定义，所有 API 请求都有类型提示。
+
+### 插件系统
+
+#### 插件注册机制
+
+```typescript
+// packages/web/buildingai-ui/app/plugins/agent-third-party.client.ts
+
+defineNuxtPlugin(() => {
+    definePlugin({
+        id: "agent-third-party-integration",
+        contributions: [
+            {
+                id: "dify-config",
+                slot: "agent:config:third-party",
+                component: () => import("xxx.vue"),
+                meta: { platform: "dify", label: "Dify" },
+                order: 1,
+            },
+        ],
+    });
+});
+```
+
+#### UI 组件库
+
+**技术栈**：
+
+- 基于 NuxtUI 3.x（Radix Vue + Headless UI）
+- TailwindCSS 4.x 样式
+- TypeScript 完整类型
+- Storybook 文档
+
+**核心组件**：
+
+- 表单组件（支持验证）
+- 数据表格（支持分页、排序、筛选）
+- 对话组件（Markdown 渲染、代码高亮）
+- 可视化拖拽（智能体流程编排）
+- 上传组件（支持分片上传、断点续传）
+
+---
+
+## 后端技术细节
+
+### 启动流程
+
+```typescript
+// packages/api/src/main.ts
+
+async function bootstrap() {
+    // 1. 动态加载 AppModule
+    const dynamicAppModule = await AppModule.register();
+
+    // 2. 创建 NestJS 应用
+    const app = await NestFactory.create<NestExpressApplication>(dynamicAppModule, {
+        logger: appLogger,
+    });
+
+    // 3. 配置中间件
+    app.use(bodyParser.xml({...}));
+    app.use(cookieParser());
+    app.set("trust proxy", true);
+
+    // 4. 启用 CORS
+    if (corsEnabled) {
+        app.enableCors({ origin: process.env.SERVER_CORS_ORIGIN || "*", credentials: true });
+    }
+
+    // 5. 全局管道（DTO 验证）
+    app.useGlobalPipes(
+        new ValidationPipe({
+            transform: true,
+            whitelist: true,
+            forbidNonWhitelisted: true,
+        }),
+    );
+
+    // 6. 全局拦截器（响应转换、日志）
+    app.useGlobalInterceptors(
+        new TransformInterceptor(reflector, fileUrlService),
+        new HttpLoggerInterceptor(appLogger),
+    );
+
+    // 7. 全局过滤器（异常处理）
+    app.useGlobalFilters(new HttpExceptionFilter());
+
+    // 8. 启动监听
+    await app.listen(port);
+}
+```
+
+### 守卫体系
+
+#### 6 层安全防护
+
+| 守卫类型           | 功能                             | 优先级 |
+| ------------------ | -------------------------------- | ------ |
+| `DemoGuard`        | 演示环境限制（限制 POST/DELETE） | 1      |
+| `AuthGuard`        | JWT 认证 + Token 滑动刷新        | 2      |
+| `ExtensionGuard`   | 扩展访问权限控制                 | 3      |
+| `PermissionsGuard` | RBAC 权限验证                    | 4      |
+| `SuperAdminGuard`  | 超级管理员验证                   | 5      |
+| `MemberOnlyGuard`  | 会员专属功能限制                 | 6      |
+
+#### Token 滑动刷新
+
+```typescript
+// packages/api/src/common/guards/auth.guard.ts
+
+private async handleTokenRefresh(token, tokenRecord, user, response) {
+    const refreshResult = await this.AuthService.userTokenService
+        .refreshTokenIfNeeded(token, tokenRecord, user);
+
+    if (refreshResult) {
+        response.setHeader('x-new-token', refreshResult.newToken);
+        response.setHeader('Access-Control-Expose-Headers', 'x-new-token');
+        response.setHeader('Cache-Control', 'no-store');
+    }
+}
+```
+
+### 统一响应处理
+
+#### TransformInterceptor
+
+```typescript
+// packages/api/src/common/interceptors/transform.interceptor.ts
+
+{
+    code: BusinessCode.SUCCESS,  // 业务状态码
+    message: "ok",                // 消息
+    data: {...},                  // 数据（自动处理文件URL）
+    timestamp: Date.now()         // 时间戳
+}
+```
+
+#### 智能文件 URL 处理
+
+- 支持嵌套对象中的文件路径自动转换
+- 自动识别域名（支持反向代理）
+- 性能优化：缓存处理结果，定期清理
+
+#### HttpExceptionFilter
+
+**异常分类处理**：
+
+- `HttpError` - 业务异常（自定义错误码）
+- `HttpException` - HTTP 标准异常
+- `Error` - 未知异常
+
+### AI SDK 架构
+
+#### 统一接口层
+
+```typescript
+// packages/@buildingai/ai-sdk/src/
+
+├── core/
+│   ├── generator/          # 文本生成
+│   ├── embedding.ts        # 向量化
+│   └── rerank.ts          # 重排序
+├── providers/
+│   ├── openai.ts          # OpenAI
+│   ├── tongyi.ts          # 通义千问
+│   ├── wenxin.ts          # 文心一言
+│   ├── zhipuai.ts         # 智谱 AI
+│   ├── moonshot.ts        # Moonshot
+│   ├── deepseek.ts        # DeepSeek
+│   ├── google.ts         # Google
+│   ├── volcengine.ts     # 火山引擎
+│   └── custom.ts         # 自定义提供商
+└── utils/
+    ├── mcp/              # MCP 工具调用
+    │   ├── http.ts       # StreamableHTTP
+    │   ├── sse.ts        # SSE
+    │   └── type.ts       # 类型定义
+    └── document-parser.ts # 文档解析
+```
+
+#### 支持的提供商
+
+- **OpenAI**：GPT-4, GPT-3.5
+- **阿里云**：通义千问
+- **百度**：文心一言
+- **智谱 AI**：ChatGLM
+- **Moonshot**：Kimi
+- **DeepSeek**：DeepSeek 系列
+- **Google**：Gemini
+- **火山引擎**：豆包
+
+#### MCP 集成
+
+支持两种调用方式：
+
+1. **SSE (Server-Sent Events)**
+2. **StreamableHTTP**
+
+---
+
+## 前后端交互
+
+### 认证流程
+
+```
+前端 → POST /api/auth/login
+     ↓
+后端 AuthGuard → 验证用户名密码
+     ↓
+生成 JWT → 存入 user_token 表
+     ↓
+返回 { token, user }
+     ↓
+前端存储 token → localStorage + Pinia
+     ↓
+后续请求 → Authorization: Bearer {token}
+     ↓
+后端 AuthGuard → 验证 JWT
+     ↓
+Token 即将过期 → 滑动刷新
+     ↓
+响应头 x-new-token → 前端自动更新
+```
+
+### 对话流程
+
+```
+前端 → POST /api/ai/chat/stream
+     ↓
+后端 ChatHandler → 流式响应 (SSE)
+     ↓
+前端 EventSource → 接收消息片段
+     ↓
+实时渲染 Markdown → 对话界面
+```
+
+### 扩展动态加载
+
+```
+启动 → 扫描 extensions/ 目录
+     ↓
+加载 extension.json → 注册扩展模块
+     ↓
+创建 PostgreSQL Schema → 隔离数据
+     ↓
+前端 → 加载扩展 UI 组件
+     ↓
+动态注册路由 → 访问扩展功能
+```
+
+---
+
+## 部署架构
+
+### Docker Compose 多容器部署
+
+```yaml
+services:
+    nodejs: # 应用服务容器
+    postgres: # PostgreSQL 数据库容器
+    redis: # Redis 缓存容器
+```
+
+#### 环境变量
+
+| 变量             | 说明         | 默认值     |
+| ---------------- | ------------ | ---------- |
+| `SERVER_PORT`    | 服务端口     | 4090       |
+| `DB_HOST`        | 数据库主机   | localhost  |
+| `DB_PORT`        | 数据库端口   | 5432       |
+| `DB_USERNAME`    | 数据库用户名 | postgres   |
+| `DB_PASSWORD`    | 数据库密码   | postgres   |
+| `DB_DATABASE`    | 数据库名称   | buildingai |
+| `REDIS_HOST`     | Redis 主机   | localhost  |
+| `REDIS_PORT`     | Redis 端口   | 6379       |
+| `JWT_SECRET`     | JWT 密钥     | buildingai |
+| `JWT_EXPIRES_IN` | JWT 过期时间 | 30d        |
+
+#### 启动命令
+
+```bash
+# 复制环境变量
+cp .env.example .env
+
+# 启动容器
+docker compose up -d
+
+# 查看日志
+docker compose logs -f nodejs
+
+# 停止容器
+docker compose down
+```
+
+---
+
+## 技术亮点
+
+### 后端
+
+1. **高度模块化**：NestJS 模块化 + Monorepo 包隔离
+2. **扩展友好**：Schema 隔离 + 动态模块加载
+3. **安全体系**：6 层守卫 + Token 滑动刷新
+4. **统一规范**：全局拦截器 + 统一异常处理
+5. **AI 原生**：统一 SDK + 多提供商支持
+6. **性能优化**：SWC 编译 + Redis 缓存 + BullMQ 异步处理
+7. **数据库设计**：PostgreSQL + pgvector + zhparser，支持向量和全文搜索
+
+### 前端
+
+1. **现代化框架**：Nuxt 4 + Vue 3 + TypeScript
+2. **动态路由**：权限驱动的路由注册
+3. **插件系统**：插槽机制 + 第三方集成
+4. **状态管理**：Pinia + 自动持久化
+5. **类型安全**：完整的 TypeScript 类型覆盖
+6. **性能优化**：Vite 构建 + 按需加载 + PWA 支持
+7. **开发体验**：Hot Module Replacement + Storybook 文档
+
+### AI 能力
+
+1. **多模型支持**：10+ 主流 LLM 提供商
+2. **智能体编排**：可视化流程编排 + 拖拽编辑
+3. **RAG 增强**：向量检索 + 全文搜索 + 多文档解析
+4. **MCP 集成**：标准化工具调用协议
+5. **流式响应**：实时对话 + Markdown 渲染
+
+---
+
+## 开发指南
+
+### 环境要求
+
+- **Node.js**: >=22.20.x <23
+- **pnpm**: 10.x
+- **PostgreSQL**: 17.x
+- **Redis**: 8.x
+- **Docker** (可选)
+
+### 快速开始
+
+```bash
+# 1. 安装依赖
+pnpm install
+
+# 2. 配置环境变量
+cp .env.example .env
+
+# 3. 启动数据库
+docker compose up -d
+
+# 4. 启动项目
+pnpm start
+```
+
+### 开发命令
+
+```bash
+# 启动后端 API
+pnpm dev:api
+
+# 启动前端 Web
+pnpm dev:web
+
+# 构建所有包
+pnpm run build
+
+# 代码检查
+pnpm run lint
+
+# 类型检查
+pnpm run typecheck
+```
+
+### 访问地址
+
+- **前端 Web**: http://localhost:4091
+- **后端 API**: http://localhost:4090
+- **安装页面**: http://localhost:4090/install
+
+---
+
+## 附录
+
+### 相关链接
+
+- **在线演示**: http://demo.buildingai.cc/
+- **官方网站**: https://www.buildingai.cc/
+- **GitHub**: https://github.com/BidingCC/BuildingAI
+- **部署文档**: https://www.buildingai.cc/docs/introduction/install
+
+### 许可证
+
+[Apache License 2.0](./LICENSE)
+
+---
+
+**文档维护**：BuildingAI Team **最后更新**：2026-01-23