ForcePilot/CODE_WIKI.md

# Yuxi 项目 Code Wiki

> 本文档是 Yuxi（语析）项目的结构化代码百科，涵盖项目整体架构、主要模块职责、关键类与函数说明、依赖关系以及项目运行方式等关键信息。
> 
> 项目版本：v0.6.2 | 最后更新：2026-05-14

---

## 目录

1. [项目概述](#1-项目概述)
2. [整体架构](#2-整体架构)
3. [后端核心模块](#3-后端核心模块)
4. [前端核心模块](#4-前端核心模块)
5. [关键类与函数详解](#5-关键类与函数详解)
6. [数据流与运行链路](#6-数据流与运行链路)
7. [依赖关系](#7-依赖关系)
8. [项目运行方式](#8-项目运行方式)
9. [测试体系](#9-测试体系)
10. [附录：目录结构总览](#10-附录目录结构总览)

---

## 1. 项目概述

**Yuxi（语析）** 是一个基于大模型的智能知识库与知识图谱智能体开发平台，融合了 RAG 技术与知识图谱技术，基于 **LangGraph v1 + Vue.js + FastAPI + LightRAG** 架构构建。

### 核心特性

- **智能体开发**：基于 LangGraph，支持子智能体、Skills、MCPs、Tools 与中间件机制
- **知识库（RAG）**：多格式文档解析，支持 Embedding / Rerank 配置及知识库评估
- **知识图谱**：基于 LightRAG 的图谱构建与可视化，支持属性图谱并参与智能体推理
- **平台与工程化**：Vue + FastAPI 架构，支持暗黑模式、Docker 与生产级部署
- **多渠道网关**：支持 Slack、Discord、Telegram、飞书、微信、QQ 等 20+ 渠道接入

### 技术栈

| 层级 | 技术 |
|------|------|
| 前端 | Vue 3 + Vite + Pinia + Ant Design Vue + Sigma.js/G6 |
| 后端 API | FastAPI + Uvicorn |
| 智能体框架 | LangGraph + LangChain |
| 任务队列 | ARQ (Redis) |
| 数据库 | PostgreSQL (业务数据) + Neo4j (图谱) + Milvus (向量) |
| 对象存储 | MinIO |
| 缓存/消息 | Redis |
| 文档解析 | MinerU + PaddleX + RapidOCR + DeepSeek OCR |
| 沙盒执行 | Docker Sandbox |

---

## 2. 整体架构

### 2.1 架构分层

```
┌─────────────────────────────────────────────────────────────┐
│                        前端层 (Frontend)                      │
│  Vue 3 + Vite + Pinia + Ant Design Vue + Sigma.js/G6       │
│  web/src/                                                   │
├─────────────────────────────────────────────────────────────┤
│                      API 网关层 (Gateway)                     │
│  FastAPI + 路由注册 + 认证中间件 + CORS + 限流               │
│  backend/server/                                            │
├─────────────────────────────────────────────────────────────┤
│                     业务服务层 (Services)                     │
│  聊天服务、运行队列、知识库、Skills、MCP、SubAgents         │
│  backend/package/yuxi/services/                             │
├─────────────────────────────────────────────────────────────┤
│                     智能体层 (Agents)                         │
│  BaseAgent + LangGraph + 中间件 + 工具集 + 沙盒后端         │
│  backend/package/yuxi/agents/                               │
├─────────────────────────────────────────────────────────────┤
│                     数据访问层 (Repositories)                 │
│  SQLAlchemy + 异步会话 + 业务模型                           │
│  backend/package/yuxi/repositories/                         │
├─────────────────────────────────────────────────────────────┤
│                     基础设施层 (Infrastructure)               │
│  PostgreSQL + Neo4j + Milvus + Redis + MinIO              │
│  backend/package/yuxi/storage/                              │
└─────────────────────────────────────────────────────────────┘
```

### 2.2 Docker Compose 服务拓扑

| 服务 | 容器名 | 端口 | 职责 |
|------|--------|------|------|
| api-dev | api-dev | 5050 | FastAPI 主服务（热重载） |
| worker-dev | worker-dev | - | ARQ 异步任务 Worker |
| web-dev | web-dev | 5173 | Vue 前端（热重载） |
| sandbox-provisioner | sandbox-provisioner | 8002 | 沙盒环境供应器 |
| postgres | postgres | 5432 | 业务与知识库元数据 |
| redis | redis | 6379 | 运行事件、队列状态、缓存 |
| minio | minio | 9000/9001 | 对象存储 |
| milvus | milvus | 19530 | 向量检索 |
| graph | graph | 7474/7687 | Neo4j 知识图谱 |
| mineru-vllm-server | mineru-vllm-server | 30000 | 文档解析 VLLM 服务（profile: all） |
| mineru-api | mineru-api | 30001 | 文档解析 API（profile: all） |
| paddlex | paddlex-ocr | 8080 | PaddleX OCR（profile: all） |

---

## 3. 后端核心模块

后端分为两个顶层边界：`backend/server` 是 Web 应用入口与 HTTP 适配层，`backend/package/yuxi` 是可复用业务包。

### 3.1 入口与路由层 (`backend/server/`)

#### 3.1.1 主入口 (`server/main.py`)

- 创建 FastAPI 应用，注册 lifespan 生命周期
- 挂载所有业务路由到 `/api` 前缀
- 注册中间件：CORS、访问日志、登录限流、认证
- 集成 WebSocket 聊天端点和 Slack Webhook

#### 3.1.2 路由注册 (`server/routers/__init__.py`)

| 路由模块 | API 前缀 | 职责 | LITE 模式 |
|----------|----------|------|-----------|
| `system_router.py` | `/api/system/*` | 健康检查、全局配置 | ✓ |
| `auth_router.py` | `/api/auth/*` | 登录、用户信息、OIDC | ✓ |
| `chat_router.py` | `/api/chat/*` | 对话、消息流、运行态 | ✓ |
| `dashboard_router.py` | `/api/dashboard/*` | 仪表盘聚合数据 | ✓ |
| `auth_dept_router.py` | `/api/departments/*` | 部门与权限 | ✓ |
| `system_task_router.py` | `/api/tasks/*` | 后台任务管理 | ✓ |
| `mcp_router.py` | `/api/system/mcp-servers/*` | MCP 服务管理 | ✓ |
| `model_provider_router.py` | `/api/system/model-providers/*` | 模型供应商配置 | ✓ |
| `skill_router.py` | `/api/system/skills/*` | Skills 管理 | ✓ |
| `subagent_router.py` | `/api/system/subagents/*` | 子智能体管理 | ✓ |
| `tool_router.py` | `/api/system/tools/*` | 工具列表与配置 | ✓ |
| `auth_apikey_router.py` | `/api/apikey/*` | API Key 管理 | ✓ |
| `filesystem_router.py` | `/api/viewer/filesystem/*` | 工作台文件系统视图 | ✓ |
| `workspace_router.py` | `/api/workspace/*` | 用户个人工作区 | ✓ |
| `channels_router.py` | `/api/channels/*` | 多渠道网关管理 | ✓ |
| `webhook_router.py` | `/api/webhook/*` | 统一 Webhook 分发 | ✓ |
| `knowledge_router.py` | `/api/knowledge/*` | 知识库管理与检索 | ✗ |
| `knowledge_eval_router.py` | `/api/evaluation/*` | 知识库评估 | ✗ |
| `knowledge_mindmap_router.py` | `/api/mindmap/*` | 思维导图生成与查询 | ✗ |
| `graph_router.py` | `/api/graph/*` | 图谱查询与管理 | ✗ |

#### 3.1.3 Worker 入口 (`server/worker_main.py`)

- ARQ Worker 入口，导入 `WorkerSettings`
- 处理智能体运行等异步任务

### 3.2 智能体体系 (`backend/package/yuxi/agents/`)

#### 3.2.1 核心基类

| 文件 | 类/函数 | 职责 |
|------|---------|------|
| `base.py` | `BaseAgent` | 智能体基类，定义 graph 编译、消息流式处理、历史记录、checkpointer 管理 |
| `context.py` | `BaseContext` | 智能体运行配置上下文，包含模型、工具、知识库、MCP、Skills、子智能体等配置 |
| `state.py` | `BaseState` | LangGraph 状态定义，包含 messages 和 artifacts |
| `state.py` | `AgentStatePayload` | 前端可消费的序列化状态结构 |
| `models.py` | `load_chat_model()` | 根据 v1/v2 spec 加载聊天模型，支持多供应商 |

#### 3.2.2 内置智能体 (`agents/buildin/`)

| 智能体 | 文件 | 职责 |
|--------|------|------|
| ChatbotAgent | `chatbot/graph.py` | 基础对话机器人，支持文件上传、知识库、MCP、Skills、子智能体 |
| DeepAgent | `deep_agent/graph.py` | 深度研究智能体，用于复杂任务分解与执行 |

#### 3.2.3 中间件 (`agents/middlewares/`)

中间件负责把各种能力挂载到智能体运行时：

| 中间件 | 职责 |
|--------|------|
| `KnowledgeBaseMiddleware` | 知识库检索工具注入 |
| `SkillsMiddleware` | Skills 提示词注入、依赖展开、动态激活 |
| `RuntimeConfigMiddleware` | 运行时配置应用（模型/工具/MCP/提示词） |
| `SummaryOffloadMiddleware` | 上下文摘要优化（token 阈值触发） |
| `SubAgentMiddleware` | 子智能体调度 |
| `FilesystemMiddleware` | 沙盒文件系统后端 |
| `TodoListMiddleware` | 待办事项管理 |
| `PatchToolCallsMiddleware` | 工具调用补丁 |
| `ModelRetryMiddleware` | 模型重试机制 |

#### 3.2.4 工具集 (`agents/toolkits/`)

| 模块 | 职责 |
|------|------|
| `buildin/tools.py` | 内置工具（如 tavily_search、ask_user_question） |
| `kbs/tools.py` | 知识库相关工具 |
| `mysql/tools.py` | MySQL 数据库工具 |
| `registry.py` | 工具注册中心 |

#### 3.2.5 后端执行 (`agents/backends/`)

| 模块 | 职责 |
|------|------|
| `sandbox/backend.py` | 沙盒执行后端 |
| `sandbox/paths.py` | 沙盒路径管理 |
| `composite.py` | 复合后端（知识库 + Skills + 沙盒） |
| `skills_backend.py` | Skills 执行后端 |

### 3.3 服务层 (`backend/package/yuxi/services/`)

服务层是用例层，负责串联 repositories、agents、knowledge、storage 和外部系统。

| 服务文件 | 职责 | 关键函数 |
|----------|------|----------|
| `chat_service.py` | 聊天核心服务 | `agent_chat()`, `stream_agent_chat()`, `stream_agent_resume()`, `get_agent_state_view()` |
| `agent_run_service.py` | Agent 运行管理（创建/轮询/取消） | `create_agent_run_view()`, `stream_agent_run_events()`, `cancel_agent_run_view()` |
| `run_worker.py` | ARQ Worker 任务处理 | `process_agent_run()`, `RunContext`, `ChunkedEventWriter` |
| `run_queue_service.py` | 运行队列与事件流 | `get_arq_pool()`, `append_run_stream_event()`, `publish_cancel_signal()` |
| `skill_service.py` | Skills 业务逻辑 | `import_skill_zip()`, `list_skills()`, `install_builtin_skill()`, `update_builtin_skill()` |
| `mcp_service.py` | MCP 服务管理 | `get_mcp_tools()`, `get_enabled_mcp_server_config()`, `ensure_builtin_mcp_servers_in_db()` |
| `subagent_service.py` | 子智能体管理 | `get_subagents_from_names()`, `init_builtin_subagents()` |
| `langfuse_service.py` | 可观测性追踪 | `build_run_context()`, `get_trace_info()`, `flush_langfuse()` |
| `model_provider_service.py` | 模型供应商配置 | `ensure_builtin_model_providers_in_db()`, `get_all_model_providers()` |
| `model_cache.py` | 模型信息缓存 | `model_cache.rebuild()`, `is_v2_spec_format()` |
| `conversation_service.py` | 对话管理 | - |
| `filesystem_service.py` | 文件系统服务 | - |
| `knowledge_fs_service.py` | 知识库文件服务 | - |
| `task_service.py` | 后台任务调度 | `tasker.start()`, `tasker.shutdown()` |
| `upload_utils.py` | 文件上传工具 | - |
| `workspace_service.py` | 工作区服务 | - |
| `evaluation_service.py` | 知识库评估 | - |
| `feedback_service.py` | 反馈服务 | - |
| `oidc_service.py` | OIDC 认证 | - |
| `tool_service.py` | 工具元数据 | `get_tool_metadata()` |

### 3.4 知识库领域 (`backend/package/yuxi/knowledge/`)

| 文件 | 类/函数 | 职责 |
|------|---------|------|
| `base.py` | `KnowledgeBase` (ABC) | 知识库抽象基类，定义统一接口（创建/删除/查询/文件管理） |
| `manager.py` | `KnowledgeBaseManager` | 知识库管理器，统一管理多种类型知识库实例 |
| `factory.py` | `KnowledgeBaseFactory` | 知识库工厂，根据类型创建实例 |
| `implementations/dify.py` | `DifyKnowledgeBase` | Dify 知识库实现 |
| `implementations/milvus.py` | `MilvusKnowledgeBase` | Milvus 向量知识库实现 |
| `chunking/` | - | 文档分块策略（RAGflow-like 语义分块） |
| `graphs/adapters/` | - | 图谱适配与上传服务 |
| `utils/kb_utils.py` | - | 知识库通用工具 |

### 3.5 数据访问层 (`backend/package/yuxi/repositories/`)

| 仓库文件 | 职责 |
|----------|------|
| `skill_repository.py` | Skills CRUD |
| `task_repository.py` | 后台任务 CRUD |
| `user_repository.py` | 用户 CRUD |
| `agent_config_repository.py` | 智能体配置 CRUD |
| `agent_run_repository.py` | 智能体运行记录 CRUD |
| `conversation_repository.py` | 对话与消息 CRUD |
| `knowledge_base_repository.py` | 知识库元数据 CRUD |
| `knowledge_file_repository.py` | 知识库文件 CRUD |
| `evaluation_repository.py` | 评估基准与结果 CRUD |

### 3.6 存储层 (`backend/package/yuxi/storage/`)

| 模块 | 职责 |
|------|------|
| `postgres/manager.py` | `PostgresManager` - 数据库连接池、会话管理、schema 迁移 |
| `postgres/models_business.py` | 业务数据模型（User、Conversation、AgentRun 等） |
| `postgres/models_knowledge.py` | 知识库数据模型（KnowledgeBase、KnowledgeFile 等） |
| `postgres/models_channels.py` | 渠道网关数据模型 |
| `minio/client.py` | MinIO 客户端封装 |

### 3.7 多渠道网关 (`backend/package/yuxi/channels/`)

支持 20+ 即时通讯渠道接入：

| 渠道 | 适配器位置 |
|------|-----------|
| Slack | `channels/adapters/slack/` |
| Discord | `channels/adapters/discord/` |
| Telegram | `channels/adapters/telegram/` |
| 飞书 (Feishu) | `channels/adapters/feishu/` |
| 微信 (WeChat) | `channels/adapters/wechat/` |
| QQ 机器人 | `channels/adapters/qqbot/` |
| 钉钉 | `channels/adapters/dingding/` |
| Microsoft Teams | `channels/adapters/msteams/` |
| Matrix | `channels/adapters/matrix/` |
| IRC | `channels/adapters/irc/` |
| Line | `channels/adapters/line/` |
| Twitch | `channels/adapters/twitch/` |
| Nostr | `channels/adapters/nostr/` |
| Signal | `channels/adapters/signal/` |
| WhatsApp | `channels/adapters/whatsapp/` |
| Urbit | `channels/adapters/urbit/` |
| 元宝 (Yuanbao) | `channels/adapters/yuanbao/` |
| Zalo | `channels/adapters/zalo_oa/`, `zalo_user/` |

核心文件：
- `channels/manager.py` - 渠道管理器
- `channels/base.py` - 渠道基类
- `channels/router.py` - 消息路由
- `channels/message_actions.py` - 消息动作处理

### 3.8 配置与模型 (`backend/package/yuxi/config/`, `models/`)

| 文件 | 职责 |
|------|------|
| `config/app.py` | 应用配置管理 |
| `config/builtin_providers.py` | 内置模型供应商配置 |
| `config/static/models.py` | 静态模型信息 |
| `models/chat.py` | 聊天模型适配 |
| `models/embed.py` | Embedding 模型适配 |
| `models/rerank.py` | Rerank 模型适配 |

### 3.9 文档解析 (`backend/package/yuxi/plugins/parser/`)

| 文件 | 职责 |
|------|------|
| `unified.py` | `Parser` 统一入口，封装所有解析实现 |
| `factory.py` | 解析器工厂 |
| `base.py` | 解析器抽象基类 |
| `mineru.py` | MinerU 解析实现 |
| `mineru_official.py` | MinerU 官方 API 实现 |
| `pp_structure_v3.py` | PaddleX 结构解析 |
| `rapid_ocr.py` | RapidOCR 实现 |
| `deepseek_ocr.py` | DeepSeek OCR 实现 |

---

## 4. 前端核心模块

前端是 Vue 3 + Vite 应用，业务入口集中在 `web/src/`。

### 4.1 入口与路由 (`web/src/`)

| 文件 | 职责 |
|------|------|
| `main.js` | 应用挂载入口 |
| `App.vue` | 根组件 |
| `router/index.js` | 路由配置，含权限守卫（requiresAuth/requiresAdmin/requiresSuperAdmin） |

**路由表：**

| 路径 | 页面 | 权限 |
|------|------|------|
| `/` | HomeView | 公开 |
| `/login` | LoginView | 公开 |
| `/agent` | AgentView | 登录用户 |
| `/agent/:thread_id` | AgentView（带线程ID） | 登录用户 |
| `/workspace` | WorkspaceView | 登录用户 |
| `/graph` | GraphView | 管理员 |
| `/database` | DataBaseView | 管理员 |
| `/database/:database_id` | DataBaseInfoView | 管理员 |
| `/dashboard` | DashboardView | 管理员 |
| `/model-config` | ModelConfigView | 管理员 |
| `/channels` | ChannelManageView | 管理员 |
| `/extensions` | ExtensionsView | 超级管理员 |

### 4.2 API 封装 (`web/src/apis/`)

所有后端接口统一封装，复用 `base.js` 的请求、鉴权和错误处理。

| API 文件 | 职责 |
|----------|------|
| `base.js` | HTTP 客户端、请求/响应拦截、权限头处理 |
| `agent_api.js` | 智能体管理、聊天接口 |
| `knowledge_api.js` | 知识库管理、文档管理、查询 |
| `graph_api.js` | 知识图谱操作 |
| `mcp_api.js` | MCP 服务器管理 |
| `skill_api.js` | Skills 管理 |
| `subagent_api.js` | 子智能体管理 |
| `system_api.js` | 系统状态、配置 |
| `auth_api.js` | 认证、用户信息 |
| `dashboard_api.js` | 仪表盘数据 |
| `department_api.js` | 部门管理 |
| `channel_api.js` | 渠道管理 |
| `tool_api.js` | 工具信息 |
| `tasker.js` | 任务管理 |
| `mindmap_api.js` | 思维导图 |
| `workspace_api.js` | 工作区 |
| `viewer_filesystem.js` | 文件系统视图 |
| `apikey_api.js` | API Key 管理 |

### 4.3 状态管理 (`web/src/stores/`)

使用 Pinia + `pinia-plugin-persistedstate` 持久化。

| Store 文件 | 职责 |
|-----------|------|
| `user.js` | 用户信息、登录状态、权限 |
| `agent.js` | 智能体配置、初始化状态 |
| `chatThreads.js` | 聊天线程列表、当前线程 |
| `database.js` | 知识库列表、当前知识库 |
| `graphStore.js` | 图谱数据、可视化状态 |
| `theme.js` | 主题（暗黑/亮色） |
| `config.js` | 系统配置 |
| `chatUI.js` | 聊天界面状态 |
| `tasker.js` | 任务状态 |
| `channel.js` | 渠道配置 |
| `info.js` | 系统信息 |

### 4.4 可组合逻辑 (`web/src/composables/`)

| 文件 | 职责 |
|------|------|
| `useAgentStreamHandler.js` | Agent 流式响应处理 |
| `useAgentRunStream.js` | Agent runs SSE 流处理 |
| `useApproval.js` | 审批逻辑处理 |
| `useMention.js` | @提及功能 |
| `useStreamSmoother.js` | 流式消息平滑调度 |

### 4.5 视图与组件 (`web/src/views/`, `components/`)

| 视图 | 职责 |
|------|------|
| `AgentView.vue` | 智能体对话主页面 |
| `WorkspaceView.vue` | 个人工作区（文件管理） |
| `DataBaseView.vue` | 知识库列表与管理 |
| `DataBaseInfoView.vue` | 知识库详情与文件管理 |
| `GraphView.vue` | 知识图谱可视化 |
| `DashboardView.vue` | 数据统计仪表盘 |
| `ModelConfigView.vue` | 模型供应商配置 |
| `ChannelManageView.vue` | 渠道网关管理 |
| `ExtensionsView.vue` | 扩展管理（Skills/MCP/SubAgents） |
| `LoginView.vue` | 登录页面 |
| `HomeView.vue` | 首页 |

---

## 5. 关键类与函数详解

### 5.1 智能体基类

#### `BaseAgent` (`agents/base.py`)

```python
class BaseAgent:
    name = "base_agent"
    description = "base_agent"
    capabilities: list[str] = []
    context_schema: type[BaseContext] = BaseContext

    # 核心方法
    async def get_graph(self, **kwargs) -> CompiledStateGraph  # 子类必须实现
    async def stream_messages(self, messages, input_context=None, **kwargs)  # 流式消息
    async def stream_messages_with_state(self, messages, input_context=None, **kwargs)  # 流式消息+状态
    async def invoke_messages(self, messages, input_context=None, **kwargs)  # 同步调用
    async def get_history(self, user_id, thread_id) -> list[dict]  # 获取历史
    async def get_info(self, include_configurable_items=True)  # 获取元数据
    def reload_graph(self)  # 重置 graph 缓存
```

#### `BaseContext` (`agents/context.py`)

```python
@dataclass(kw_only=True)
class BaseContext:
    thread_id: str           # 对话线程ID
    user_id: str             # 用户ID
    system_prompt: str       # 系统提示词
    model: str               # 主模型（v2 spec: provider_id:model_id）
    tools: list[str]         # 启用工具列表
    knowledges: list[str]    # 启用知识库列表
    mcps: list[str]          # 启用 MCP 服务器列表
    skills: list[str]        # 启用 Skills 列表
    subagents_model: str     # 子智能体默认模型
    subagents: list[str]     # 启用子智能体列表
    summary_threshold: int   # 上下文摘要触发阈值（KB）
```

### 5.2 聊天服务

#### `chat_service.py` 核心函数

| 函数 | 职责 |
|------|------|
| `agent_chat()` | 非流式对话，返回完整响应 |
| `stream_agent_chat()` | 流式对话，yield 事件块 |
| `stream_agent_resume()` | 恢复中断的对话（处理 human-in-the-loop） |
| `get_agent_state_view()` | 获取 Agent 当前状态 |
| `save_messages_from_langgraph_state()` | 从 LangGraph state 持久化消息 |
| `extract_agent_state()` | 从 state 提取 todos/files/artifacts |

### 5.3 Agent Run 服务

#### `agent_run_service.py` 核心函数

| 函数 | 职责 |
|------|------|
| `create_agent_run_view()` | 创建后台运行任务，入队 ARQ |
| `stream_agent_run_events()` | SSE 流式推送运行事件 |
| `cancel_agent_run_view()` | 取消运行任务 |
| `get_active_run_by_thread()` | 获取线程的活跃运行 |

### 5.4 Worker 任务处理

#### `run_worker.py` 核心类/函数

| 类/函数 | 职责 |
|---------|------|
| `process_agent_run()` | ARQ 任务主函数，消费流并写入 Redis |
| `RunContext` | 运行上下文，管理取消信号监听 |
| `ChunkedEventWriter` | 事件块缓冲写入器 |
| `WorkerSettings` | ARQ Worker 配置（max_tries=2, job_timeout=900s） |

### 5.5 知识库管理

#### `KnowledgeBaseManager` (`knowledge/manager.py`)

```python
class KnowledgeBaseManager:
    async def create_database(name, description, kb_type="lightrag", ...)  # 创建知识库
    async def delete_database(db_id)  # 删除知识库
    async def add_file_record(db_id, item, params)  # 添加文件记录
    async def parse_file(db_id, file_id)  # 解析文件为 Markdown
    async def index_file(db_id, file_id)  # 索引文件到向量库
    async def aquery(query_text, db_id, **kwargs)  # 异步查询
    def get_retrievers() -> dict[str, dict]  # 获取所有检索器
```

### 5.6 MCP 服务

#### `mcp_service.py` 核心函数

| 函数 | 职责 |
|------|------|
| `get_mcp_tools()` | 获取指定服务器的工具（带缓存） |
| `get_enabled_mcp_tools()` | Agent 统一入口（自动过滤 disabled_tools） |
| `get_tools_from_all_servers()` | 获取所有启用服务器的工具 |
| `ensure_builtin_mcp_servers_in_db()` | 同步内置 MCP 配置到数据库 |
| `create_mcp_server()` / `update_mcp_server()` / `delete_mcp_server()` | CRUD |

### 5.7 Skills 服务

#### `skill_service.py` 核心函数

| 函数 | 职责 |
|------|------|
| `import_skill_zip()` | 从 ZIP 导入 Skill |
| `list_skills()` | 列出所有 Skills |
| `install_builtin_skill()` | 安装内置 Skill |
| `update_builtin_skill()` | 更新内置 Skill（带覆盖确认） |
| `sync_thread_visible_skills()` | 同步线程可见 Skills 到沙盒 |

### 5.8 数据库管理

#### `PostgresManager` (`storage/postgres/manager.py`)

```python
class PostgresManager(metaclass=SingletonMeta):
    def initialize()  # 初始化连接池
    async def create_business_tables()  # 创建业务表
    async def ensure_business_schema()  # 确保业务 schema（增量迁移）
    async def ensure_knowledge_schema()  # 确保知识库 schema
    async def get_async_session_context()  # 异步会话上下文管理器
```

---

## 6. 数据流与运行链路

### 6.1 典型智能体对话流程

```
1. AgentView 收集输入、附件、配置
        ↓
2. web/src/apis/agent_api.js 调用 /api/chat/*
        ↓
3. server/routers/chat_router.py → chat_service / agent_run_service
        ↓
4. 服务层读取 conversation、agent_config、tools、skills、knowledge
        ↓
5a. 同步模式: 直接调用 stream_agent_chat() → 返回 SSE 流
5b. 异步模式: create_agent_run_view() → ARQ 入队 → worker 执行
        ↓
6. worker 执行 LangGraph 智能体
   - 中间件挂载知识库、工具、Skills、MCP、附件、沙盒
   - 运行事件写入 Redis
        ↓
7. 最终状态和业务记录写入 Postgres
   文件和产物落到 saves/、MinIO 或沙盒映射目录
        ↓
8. 前端通过 SSE/轮询消费运行事件
   渲染消息、工具调用、引用来源、产物卡片、文件预览
```

### 6.2 Agent Run 异步流程

```
用户请求
    ↓
create_agent_run_view()
    - 创建 AgentRun 记录（status=pending）
    - ARQ enqueue_job("process_agent_run", run.id)
    ↓
worker process_agent_run()
    - 加载用户和配置
    - mark_run_running()
    - stream_agent_chat() 消费流
    - ChunkedEventWriter 缓冲写入 Redis
    - 处理取消信号
    - mark_run_terminal(status=completed/failed/cancelled)
    ↓
前端 SSE 连接 /api/chat/runs/{run_id}/events
    - 轮询 Redis 事件
    - 心跳保活
    - 终端状态返回 close 事件
```

### 6.3 知识库文档处理流程

```
上传文件
    ↓
add_file_record() → status=UPLOADED
    ↓
parse_file() → 调用 Parser.aparse()
    - status=PARSING
    - 解析为 Markdown
    - 保存到 MinIO
    - status=PARSED / ERROR_PARSING
    ↓
index_file() → 向量化和图谱构建
    - status=INDEXING
    - 分块 → Embedding → 向量库
    - status=INDEXED / ERROR_INDEXING
    ↓
aquery() → 检索 → Rerank → 返回结果
```

---

## 7. 依赖关系

### 7.1 后端核心依赖

```
fastapi>=0.121          # Web 框架
uvicorn[standard]>=0.34 # ASGI 服务器
arq>=0.26.3             # 异步任务队列
langgraph>=1.0.1        # 智能体编排
langchain>=1.2.0        # LLM 框架
langchain-openai>=1.0   # OpenAI 兼容层
langchain-mcp-adapters  # MCP 适配
lightrag-hku>=1.4.6     # 知识图谱
neo4j>=5.28             # 图数据库
pymilvus>=2.5           # 向量数据库
asyncpg>=0.30           # PostgreSQL 异步驱动
psycopg[binary,pool]    # PostgreSQL 连接池
redis>=5.2              # 缓存/消息
minio>=7.2              # 对象存储
sqlalchemy[asyncio]>=2  # ORM
langfuse>=4.0           # 可观测性
pydantic                # 数据验证
pyjwt>=2.8              # JWT 认证
```

### 7.2 前端核心依赖

```
vue@^3.5                # 框架
vue-router@^4.6         # 路由
pinia@^3.0              # 状态管理
pinia-plugin-persistedstate # 状态持久化
ant-design-vue@^4.2     # UI 组件库
lucide-vue-next         # 图标库
@antv/g6@^5.0           # 图谱可视化
sigma@^3.0              # 图谱渲染
@vueuse/core            # 组合式工具
vite@^7.3               # 构建工具
less@^4.5               # CSS 预处理器
marked@^16              # Markdown 渲染
highlight.js            # 代码高亮
```

### 7.3 模块依赖图

```
server/main.py
    ├── server/routers/*
    │   └── yuxi.services.*
    │       ├── yuxi.agents.* (BaseAgent, agent_manager)
    │       ├── yuxi.knowledge.* (KnowledgeBaseManager)
    │       ├── yuxi.repositories.* (SQLAlchemy CRUD)
    │       ├── yuxi.storage.* (Postgres, MinIO)
    │       └── yuxi.channels.* (多渠道网关)
    └── server/utils/* (lifespan, auth, middleware)

yuxi.agents.base.BaseAgent
    ├── yuxi.agents.context.BaseContext
    ├── yuxi.agents.models.load_chat_model
    └── yuxi.storage.postgres.manager.pg_manager

yuxi.services.chat_service
    ├── yuxi.agents.buildin.agent_manager
    ├── yuxi.repositories.conversation_repository
    ├── yuxi.services.langfuse_service
    └── yuxi.plugins.guard.content_guard
```

---

## 8. 项目运行方式

### 8.1 环境要求

- Docker & Docker Compose
- Python 3.12+（后端开发）
- Node.js 20+ + pnpm（前端开发）
- Git

### 8.2 快速启动

```bash
# 1. 克隆项目
git clone --branch v0.6.2 --depth 1 https://github.com/xerrors/Yuxi.git
cd Yuxi

# 2. 初始化（创建 .env 等）
# Linux/macOS
./scripts/init.sh
# Windows PowerShell
.\scripts\init.ps1

# 3. 启动全部服务
docker compose up -d

# 或使用 Makefile
make up

# 4. 访问前端
open http://localhost:5173
```

### 8.3 LITE 模式（轻量启动）

跳过知识库、图谱、评估等重依赖：

```bash
make up-lite
# 等效于:
# LITE_MODE=true VITE_USE_RUNS_API=false docker compose up -d postgres redis minio api web
```

### 8.4 开发常用命令

```bash
# 查看日志
make logs
docker logs api-dev --tail 100
docker logs worker-dev --tail 100

# 代码格式化
make format
# 等效于:
cd backend && uv run ruff format package
cd backend && uv run ruff check package --fix
cd web && pnpm run format
cd web && pnpm run lint

# 运行测试
cd backend && uv run --group test pytest

# 停止服务
make down
```

### 8.5 开发环境特性

- **热重载**：`api-dev` 和 `web-dev` 服务均配置热重载，本地修改代码后无需重启容器
- **代码挂载**：`backend/server`、`backend/package`、`web/src` 等目录挂载到容器
- **调试**：使用 `docker logs` 查看实时日志

---

## 9. 测试体系

测试代码放在 `backend/test/`，按三层组织：

| 层级 | 目录 | 职责 |
|------|------|------|
| 单元测试 | `test/unit/` | 不依赖外部服务的纯逻辑测试 |
| 集成测试 | `test/integration/` | API 路由测试（需运行中的服务） |
| 端到端测试 | `test/e2e/` | 完整业务流程测试 |

### 9.1 运行测试

```bash
cd backend
uv run --group test pytest

# 带覆盖率
uv run --group test pytest --cov=yuxi --cov-report=html

# 仅运行单元测试
uv run --group test pytest -m unit

# 仅运行集成测试
uv run --group test pytest -m integration

# 仅运行 e2e 测试
uv run --group test pytest -m e2e
```

### 9.2 测试配置

- `pytest.ini` 配置在 `backend/pyproject.toml` 中
- 全局 fixtures 在 `test/conftest.py`
- 各层独立 `conftest.py` 管理层级 fixtures

---

## 10. 附录：目录结构总览

```
ForcePilot/
├── .github/                    # GitHub 配置（Issue 模板、工作流）
│   ├── ISSUE_TEMPLATE/
│   └── workflows/
├── backend/                    # 后端代码
│   ├── package/                # 可复用业务包
│   │   └── yuxi/               # 核心包
│   │       ├── agents/         # 智能体体系
│   │       │   ├── backends/   # 执行后端（沙盒、Skills）
│   │       │   ├── buildin/    # 内置智能体
│   │       │   ├── middlewares/# 中间件
│   │       │   ├── toolkits/   # 工具注册与实现
│   │       │   ├── base.py     # BaseAgent
│   │       │   ├── context.py  # BaseContext
│   │       │   ├── models.py   # 模型加载
│   │       │   └── state.py    # 状态定义
│   │       ├── channels/       # 多渠道网关
│   │       │   └── adapters/   # 各渠道适配器
│   │       ├── config/         # 应用配置
│   │       ├── gateway/        # 网关协议
│   │       ├── knowledge/      # 知识库领域
│   │       │   ├── chunking/   # 分块策略
│   │       │   ├── graphs/     # 图谱适配
│   │       │   └── implementations/ # 具体实现
│   │       ├── models/         # 模型适配（chat/embed/rerank）
│   │       ├── plugins/        # 插件
│   │       │   └── parser/     # 文档解析
│   │       ├── repositories/   # 数据访问层
│   │       ├── services/       # 业务服务层
│   │       ├── storage/        # 存储基础设施
│   │       │   ├── minio/      # 对象存储
│   │       │   └── postgres/   # PostgreSQL
│   │       └── utils/          # 通用工具
│   ├── server/                 # Web 应用入口
│   │   ├── routers/            # HTTP 路由
│   │   ├── utils/              # Web 层工具
│   │   ├── main.py             # FastAPI 入口
│   │   └── worker_main.py      # Worker 入口
│   ├── test/                   # 测试代码
│   │   ├── unit/               # 单元测试
│   │   ├── integration/        # 集成测试
│   │   └── e2e/                # 端到端测试
│   └── pyproject.toml          # 后端项目配置
├── web/                        # 前端代码
│   ├── src/
│   │   ├── apis/               # API 封装
│   │   ├── components/         # 可复用组件
│   │   ├── composables/        # 可组合逻辑
│   │   ├── layouts/            # 布局组件
│   │   ├── router/             # 路由配置
│   │   ├── stores/             # Pinia 状态
│   │   ├── utils/              # 前端工具
│   │   ├── views/              # 页面级视图
│   │   ├── App.vue             # 根组件
│   │   └── main.js             # 入口
│   ├── public/
│   ├── index.html
│   ├── package.json
│   └── vite.config.js
├── docker/                     # Docker 配置
│   ├── api.Dockerfile
│   ├── web.Dockerfile
│   ├── sandbox_provisioner/    # 沙盒供应器
│   └── volumes/                # 数据卷挂载点
├── docs/                       # 项目文档
│   ├── .vitepress/             # VitePress 配置
│   ├── agents/                 # Agent 开发文档
│   ├── develop-guides/         # 开发指南
│   └── vibe/                   # 开发者笔记
├── docker-compose.yml          # Docker Compose 配置
├── Makefile                    # 快捷命令
├── README.md                   # 项目说明
├── ARCHITECTURE.md             # 架构文档
├── AGENTS.md                   # 开发准则
└── .env.template               # 环境变量模板
```

---

## 参考文档

- [ARCHITECTURE.md](ARCHITECTURE.md) - 架构代码地图
- [AGENTS.md](AGENTS.md) - 开发准则与行为规范
- [README.md](README.md) - 项目快速开始
- [docker-compose.yml](docker-compose.yml) - 服务拓扑与配置
- [backend/package/pyproject.toml](backend/package/pyproject.toml) - Python 依赖
- [web/package.json](web/package.json) - Node.js 依赖