diff --git a/src/app/(cn)/xyzen/advanced/page.mdx b/src/app/(cn)/xyzen/advanced/page.mdx
new file mode 100644
index 0000000..e698bed
--- /dev/null
+++ b/src/app/(cn)/xyzen/advanced/page.mdx
@@ -0,0 +1,364 @@
+# 高级功能
+
+Xyzen 提供了一系列强大的高级功能，使你能够集成多种模型提供商、
+管理用户消费记录，以及创建可重用的 Agent 框架。
+本文档将详细介绍这些高级功能的使用方法。
+
+## 1. 多模型提供商管理
+
+### 概述
+
+Xyzen 支持与多个 LLM 提供商集成，包括：
+
+- **OpenAI** - GPT-4, GPT-4 Turbo, GPT-3.5 等
+- **Google Gemini** - Gemini Pro 等
+- **Claude (Anthropic)** - Claude 2, Claude Instant 等
+- **本地模型** - 通过 Ollama 或其他本地部署
+
+### 提供商配置
+
+#### 创建新提供商
+
+```bash
+POST /api/v1/providers
+Content-Type: application/json
+
+{
+  "name": "My OpenAI Account",
+  "type": "openai",
+  "config": {
+    "api_key": "sk-...",
+    "base_url": "https://api.openai.com/v1",
+    "model_list": ["gpt-4", "gpt-3.5-turbo"]
+  },
+  "is_default": true
+}
+```
+
+#### 支持的提供商配置
+
+| 提供商 | 必填字段 | 可选字段 |
+|--------|---------|---------|
+| **OpenAI** | `api_key` | `base_url`, `organization_id` |
+| **Google Gemini** | `api_key` | `base_url` |
+| **Claude** | `api_key` | `base_url` |
+| **本地 (Ollama)** | `base_url` | 无 |
+
+### 动态模型选择
+
+在 Agent 中动态选择模型：
+
+```python
+# 服务端示例
+from core.providers import get_user_provider_manager
+
+async def execute_with_model_selection(user_id: str, query: str):
+    provider_manager = await get_user_provider_manager(user_id, db)
+    
+    # 根据查询复杂度选择模型
+    if len(query) > 1000:
+        # 复杂查询使用高级模型
+        llm = provider_manager.get_llm("gpt-4")
+    else:
+        # 简单查询使用低成本模型
+        llm = provider_manager.get_llm("gpt-3.5-turbo")
+    
+    response = await llm.apredict(query)
+    return response
+```
+
+### 成本优化
+
+Xyzen 支持根据任务成本进行模型的自动选择：
+
+```python
+# 按成本优化的 Agent 配置
+agent_config = {
+    "name": "Cost-Aware Agent",
+    "routing_strategy": "cost_optimized",
+    "models": [
+        {
+            "model": "gpt-3.5-turbo",
+            "cost_per_1k_tokens": 0.0015,
+            "suitability": ["simple_qa", "summarization"]
+        },
+        {
+            "model": "gpt-4",
+            "cost_per_1k_tokens": 0.03,
+            "suitability": ["complex_reasoning", "code_generation"]
+        }
+    ]
+}
+```
+
+---
+
+## 2. MCP（Model Context Protocol）服务器集成
+
+### 概述
+
+MCP 是一个开放协议，允许 AI 模型通过标准化的接口访问外部工具和数据源。Xyzen 原生支持 MCP 服务器集成。
+
+### 注册 MCP 服务器
+
+#### 通过 API 注册
+
+```bash
+POST /api/v1/mcp-servers
+Content-Type: application/json
+
+{
+  "name": "Scientific Tools",
+  "description": "A collection of scientific computing tools",
+  "url": "http://localhost:3000/mcp",
+  "token": "optional-auth-token",
+  "tags": ["science", "computing"]
+}
+```
+
+#### 服务器健康检查
+
+```bash
+GET /api/v1/mcp-servers/{server_id}/health
+```
+
+Xyzen 会自动：
+1. 连接到 MCP 服务器
+2. 列出所有可用工具
+3. 验证工具的可访问性
+4. 定期检查服务器状态
+
+### 在 Agent 中使用 MCP 工具
+
+#### 配置 Agent 使用 MCP
+
+```json
+{
+  "name": "Research Assistant",
+  "agent_type": "regular",
+  "mcp_servers": [
+    {
+      "mcp_server_id": "server-uuid-1",
+      "enabled": true
+    },
+    {
+      "mcp_server_id": "server-uuid-2",
+      "enabled": true
+    }
+  ]
+}
+```
+
+#### MCP 工具调用流程
+
+<Mermaid chart={`
+graph TD
+    START["用户输入"] --> RECEIVE["Agent 收到请求"]
+    RECEIVE --> ANALYZE["LLM 分析是否需要工具"]
+    ANALYZE --> DECIDE{"需要工具?"}
+    
+    DECIDE -->|否| RESPONSE["直接生成响应"]
+    RESPONSE --> END1["返回最终答案"]
+    
+    DECIDE -->|是| CONFIRM{"需要确认?"}
+    CONFIRM -->|是| CONFIRM_UI["工具确认<br/>用户审批"]
+    CONFIRM -->|否| EXECUTE
+    CONFIRM_UI --> EXECUTE["MCP 服务器执行"]
+    EXECUTE --> RESULT["返回工具结果"]
+    RESULT --> SYNTHESIS["Agent 综合结果"]
+    SYNTHESIS --> END1
+    
+    style START fill:#4f46e5,stroke:#312e81,stroke-width:2px,color:#fff
+    style RECEIVE fill:#7c3aed,stroke:#5b21b6,stroke-width:2px,color:#fff
+    style ANALYZE fill:#7c3aed,stroke:#5b21b6,stroke-width:2px,color:#fff
+    style DECIDE fill:#ec4899,stroke:#be185d,stroke-width:2px,color:#fff
+    style CONFIRM fill:#ec4899,stroke:#be185d,stroke-width:2px,color:#fff
+    style CONFIRM_UI fill:#f59e0b,stroke:#d97706,stroke-width:2px,color:#fff
+    style EXECUTE fill:#06b6d4,stroke:#0e7490,stroke-width:2px,color:#fff
+    style RESULT fill:#06b6d4,stroke:#0e7490,stroke-width:2px,color:#fff
+    style RESPONSE fill:#10b981,stroke:#047857,stroke-width:2px,color:#fff
+    style SYNTHESIS fill:#8b5cf6,stroke:#6d28d9,stroke-width:2px,color:#fff
+    style END1 fill:#10b981,stroke:#047857,stroke-width:2px,color:#fff
+`} />
+
+### 工具使用确认机制
+
+为了提高安全性，Xyzen 支持在执行工具前进行确认：
+
+```bash
+POST /api/v1/chat/messages
+Content-Type: application/json
+
+{
+  "agent_id": "agent-uuid",
+  "content": "计算 123 + 456",
+  "require_tool_confirmation": true
+}
+```
+
+响应（等待确认）：
+
+```json
+{
+  "message_id": "msg-uuid",
+  "status": "pending_tool_confirmation",
+  "pending_tools": [
+    {
+      "name": "add",
+      "description": "Add two numbers",
+      "arguments": {
+        "a": 123,
+        "b": 456
+      }
+    }
+  ]
+}
+```
+
+用户确认后：
+
+```bash
+POST /api/v1/chat/messages/{message_id}/confirm-tools
+Content-Type: application/json
+
+{
+  "confirmed": true
+}
+```
+
+### 内置 MCP 服务器
+
+Xyzen 预置了几个常用的 MCP 服务器：
+
+| 服务器 | 功能 | 工具示例 |
+|--------|------|---------|
+| **BioYond** | 生物科学工具 | 蛋白质序列分析、基因搜索 |
+| **Lab** | 实验室工具 | 数据处理、可视化 |
+| **Dify** | 工作流集成 | 调用 Dify 工作流 |
+
+---
+
+
+## 3. 内置 Agent 系统
+
+### 概述
+
+Xyzen 提供了两个预定义的系统 Agent，可供所有用户使用：
+
+#### 随便聊聊 Assistants Agent
+- **用途**：通用对话和问题解答
+- **特点**：友好、有用、支持工具调用
+- **适用场景**：日常提问、信息查询、任务协助
+
+#### 创作工坊 Development Agent
+- **用途**：AI Agent 设计和优化
+- **特点**：专业、深入、提供架构建议
+- **适用场景**：Agent 设计、提示词工程、工作流优化
+
+### 系统 Agent 配置
+
+```python
+# 系统 Agent 配置示例
+SYSTEM_AGENTS = {
+    "chat": {
+        "name": "随便聊聊",
+        "capabilities": ["general_chat", "qa", "assistance", "tools"],
+        "tags": ["助手", "对话", "工具"],
+    },
+    "workshop": {
+        "name": "创作工坊",
+        "capabilities": ["agent_design", "tool_selection", "prompt_engineering"],
+        "tags": ["设计", "创作", "优化"],
+    }
+}
+```
+
+### 创建内置 Graph Agent
+
+Xyzen 支持将 Python 类自动注册为内置 Graph Agent：
+
+```python
+# 示例：创建科研论文分析 Agent
+from handler.builtin_agents.base_graph_agent import BaseBuiltinGraphAgent
+from langgraph.graph import StateGraph
+
+class ScientificFigureAgent(BaseBuiltinGraphAgent):
+    """分析科研论文中的图表的内置 Agent"""
+    
+    def __init__(self):
+        super().__init__(
+            name="Scientific Figure Analyzer",
+            description="分析并解释科研论文中的图表、数据和可视化",
+            version="1.0.0",
+            capabilities=[
+                "figure_analysis",
+                "data_extraction",
+                "interpretation"
+            ],
+            tags=["science", "analysis", "figures"],
+            author="Xyzen Team",
+            license_="Apache 2.0"
+        )
+    
+    def build_graph(self) -> CompiledStateGraph:
+        """构建工作流"""
+        workflow = StateGraph(GraphState)
+        
+        # 添加节点
+        workflow.add_node("extract", self._extract_figure_data)
+        workflow.add_node("analyze", self._analyze_content)
+        workflow.add_node("generate_report", self._generate_report)
+        
+        # 添加边
+        workflow.add_edge("extract", "analyze")
+        workflow.add_edge("analyze", "generate_report")
+        
+        # 设置入出口
+        workflow.set_entry_point("extract")
+        workflow.set_finish_point("generate_report")
+        
+        return workflow.compile()
+    
+    def get_state_schema(self) -> dict:
+        """返回状态模式"""
+        return {
+            "image": "bytes",
+            "extracted_data": "dict",
+            "analysis": "str",
+            "report": "str"
+        }
+    
+    async def _extract_figure_data(self, state: dict) -> dict:
+        """提取图表数据"""
+        # 实现数据提取逻辑
+        return {
+            **state,
+            "extracted_data": {...}
+        }
+    
+    async def _analyze_content(self, state: dict) -> dict:
+        """分析内容"""
+        # 实现分析逻辑
+        return {
+            **state,
+            "analysis": "..."
+        }
+    
+    async def _generate_report(self, state: dict) -> dict:
+        """生成报告"""
+        # 实现报告生成逻辑
+        return {
+            **state,
+            "report": "..."
+        }
+```
+
+内置 Agent 会自动注册到系统中，用户可以直接使用。
+
+---
+
+
+## 相关资源
+
+- [图 Agent API 文档](/xyzen/api)
+- [MCP 服务器开发指南](/mcp/development)
\ No newline at end of file
diff --git a/src/app/(cn)/xyzen/architecture/page.mdx b/src/app/(cn)/xyzen/architecture/page.mdx
new file mode 100644
index 0000000..b707cf2
--- /dev/null
+++ b/src/app/(cn)/xyzen/architecture/page.mdx
@@ -0,0 +1,714 @@
+# Xyzen 架构设计
+
+Xyzen 采用现代化的分层架构设计，通过清晰的关注点分离和模块化设计，实现了一个高效、可扩展的 AI 服务平台。本文档详细介绍系统的整体架构、核心模块、数据流以及技术选型。
+
+## 系统架构概览
+
+```mermaid
+graph TB
+    Client["🖥️ 客户端<br/>Web / Desktop"]
+    
+    subgraph "API 层"
+        REST["REST API<br/>/xyzen/api/v1/*"]
+        WS["WebSocket<br/>/xyzen/ws/v1/*"]
+        
+    end
+    
+    subgraph "中间件层"
+        Auth["🔐 身份认证中间件<br/>JWT Token Validation"]
+    end
+    
+    subgraph "服务层"
+        AgentService["Agent Service<br/>agent_service.py"]
+        ChatService["Chat Service<br/>chat/"]
+        MCPService["MCP Service<br/>mcp.py"]
+        ProviderService["Provider Service<br/>providers/"]
+        AuthService["Auth Service<br/>auth/"]
+        ConsumeService["Consumption Service<br/>consume.py"]
+    end
+    
+    subgraph "数据层"
+        Repository["Repository Layer<br/>repo/*"]
+        SQLModel["SQLModel ORM<br/>models/*"]
+        PostgreSQL["🗄️ PostgreSQL"]
+        SQLite["📊 SQLite<sub>optional</sub>"]
+    end
+    
+    subgraph "外部集成"
+        LLMProviders["🤖 LLM Providers<br/>OpenAI, Claude, etc."]
+        MCPServers["🔧 MCP Servers<br/>Tool Ecosystem"]
+        LangChain["🔗 LangChain<br/>Agent Framework"]
+        LangGraph["📊 LangGraph<br/>Workflow Engine"]
+        Smithery["📦 Smithery Registry<br/>Tool Discovery"]
+    end
+    
+    Client -->|HTTP/WebSocket| REST
+    Client -->|WebSocket| WS
+    
+    REST --> Auth
+    WS --> Auth
+    
+    Auth --> ChatService
+    Auth --> AgentService
+    Auth --> MCPService
+    Auth --> ConsumeService
+    
+    ChatService --> LangChain
+    ChatService --> LangGraph
+    ChatService --> ProviderService
+    ChatService --> MCPService
+    
+    AgentService --> Repository
+    ProviderService --> Repository
+    MCPService --> Repository
+    ConsumeService --> Repository
+    
+    Repository --> SQLModel
+    SQLModel --> PostgreSQL
+    SQLModel --> SQLite
+    
+    LangChain --> LLMProviders
+    LangGraph --> MCPServers
+    MCPService --> Smithery
+    
+    style Client fill:#e1f5fe
+    style REST fill:#fff3e0
+    style WS fill:#fff3e0
+    style Auth fill:#f3e5f5
+    
+    style AgentService fill:#fce4ec
+    style ChatService fill:#fce4ec
+    style MCPService fill:#fce4ec
+    style PostgreSQL fill:#c8e6c9
+    style LLMProviders fill:#bbdefb
+    style LangChain fill:#bbdefb
+```
+
+## 分层架构详解
+
+### 1. 表现层 (Presentation Layer)
+
+表现层作为系统的入口点，处理来自客户端的所有请求。
+
+#### API 入口点
+
+**REST API 路由**
+
+```
+/xyzen/api/v1/
+  ├── /agents          # 代理管理
+  ├── /sessions        # 会话管理
+  ├── /topics          # 主题管理
+  ├── /mcps            # MCP 服务器管理
+  ├── /providers       # 提供者管理
+  └── /auth            # 身份认证
+```
+
+**WebSocket 入口**
+
+```
+/xyzen/ws/v1/
+  └── /chat/[session_id]  # 实时聊天连接
+```
+
+**健康检查**
+
+```
+/xyzen/api/health  # 服务健康状态检查
+```
+
+#### FastAPI 应用结构
+
+```python
+# FastAPI 应用初始化流程
+app = FastAPI(
+    title="Xyzen FastAPI Service",
+    lifespan=lifespan,  # 生命周期管理
+    docs_url="/xyzen/api/docs",
+)
+
+# CORS 中间件
+app.add_middleware(CORSMiddleware, allow_origins=["*"])
+
+# 根路由器
+app.include_router(root_router, prefix="/xyzen")
+
+# MCP 路由自动注册
+app.router.routes.extend(setup_mcp_routes(app.state))
+```
+
+### 2. 中间件层 (Middleware Layer)
+
+中间件负责横切关注点的处理，在请求-响应周期中执行统一的处理逻辑。
+
+#### 身份认证中间件 (auth/)
+
+验证 Bearer Token JWT，提取用户身份信息：
+- 支持多个认证提供者 (Casdoor, Bohrium, BohrApp)
+- 从 Token 中提取 \`user_id\` 和 \`provider\`
+- 为后续服务层注入当前用户上下文
+
+#### 数据库连接中间件 (database/)
+
+管理 SQLAlchemy 数据库连接池：
+- 创建 \`AsyncSessionLocal\` 连接
+- 使用 FastAPI 的 \`Depends\` 机制依赖注入
+- 支持事务管理和自动回滚
+
+#### 日志中间件 (logger/)
+
+结构化日志记录：
+- 请求入口日志
+- 错误堆栈跟踪
+- 服务启动和关闭日志
+
+#### 动态 MCP 服务器中间件 (dynamic_mcp_server.py)
+
+动态创建和挂载 MCP HTTP 服务器：
+- 为每个注册的 MCP 服务器创建独立的 FastMCP 应用
+- 处理 MCP 生命周期管理
+- 错误隔离和恢复
+
+### 3. API 处理层 (Handler Layer)
+
+处理层包含所有的 HTTP 路由处理器和 WebSocket 事件处理器。
+
+#### REST API 处理器 (handler/api/v1/)
+
+| 模块 | 职责 | 核心端点 |
+|-----|------|--------|
+| **agents.py** | 代理 CRUD 和配置 | POST /agents，GET /agents/id，PUT /agents/id，DELETE /agents/id |
+| **sessions.py** | 会话和主题管理 | POST /sessions，GET /sessions，自动创建默认主题 |
+| **topics.py** | 主题和消息 | GET /topics/id/messages，DELETE /topics/id |
+| **mcps.py** | MCP 服务器集成 | GET /mcps，POST /mcps/tools/test，Smithery 激活 |
+| **providers.py** | 提供者配置 | GET /providers，POST /providers，PUT /providers/id，DELETE /providers/id |
+| **auth.py** | 认证状态 | GET /auth/status，GET /auth/config |
+
+#### WebSocket 处理器 (handler/ws/v1/)
+
+实时聊天通信通道：
+- 连接建立与关闭
+- 消息发送和接收
+- 流式响应处理
+
+#### 内置代理处理器 (handler/builtin_agents/)
+
+预定义的系统级代理：
+- 注册表管理
+- 代理发现和加载
+- 代理启动时数据库种子化
+
+### 4. 服务层 (Service Layer)
+
+服务层包含业务逻辑和复杂的计算，是应用的核心逻辑所在。
+
+#### Agent Service (core/agent_service.py)
+
+统一的代理管理服务：
+- `UnifiedAgentRead` 模型用于读取常规代理和图代理
+- 代理类型检测 (regular vs graph vs builtin)
+- 代理验证和配置加载
+
+#### Chat Service (core/chat/)
+
+对话执行引擎：
+- 与 LangChain 集成用于标准 LLM 调用
+- 与 LangGraph 集成用于复杂工作流
+- 流式响应处理
+- 工具调用和确认机制
+
+#### MCP Service (core/mcp.py)
+
+MCP (Model Context Protocol) 服务：
+- MCP 服务器客户端管理
+- Smithery 注册表集成
+- 工具状态检查和健康检测
+- 异步广播更新
+
+#### Provider Service (core/providers/)
+
+LLM 提供者管理：
+- 提供者初始化 (`initialize_providers_on_startup`)
+- 凭证安全存储和掩码
+- 多提供者支持 (OpenAI, Azure, Anthropic, Google)
+- 模板管理
+
+#### Auth Service (core/auth/)
+
+身份认证和授权：
+- Token 验证
+- 用户上下文管理
+- 多提供者认证
+
+#### Consumption Service (core/consume.py)
+
+使用量跟踪和计费：
+- 记录每次 API 调用的消费
+- 远程计费集成 (Bohrium)
+- 消费记录持久化
+- 幂等性保证
+
+### 5. 数据层 (Data Layer)
+
+#### Repository 层 (repo/)
+
+数据访问抽象：
+
+| 文件 | 功能 |
+|-----|------|
+| agent.py | Agent CRUD |
+| session.py | Session/Topic CRUD |
+| message.py | Message CRUD |
+| provider.py | Provider CRUD |
+| mcp.py | MCP 服务器 CRUD |
+| consume.py | ConsumeRecord CRUD |
+| graph.py | GraphAgent CRUD |
+
+Repository 模式的好处：
+- 解耦业务逻辑和数据访问
+- 支持单元测试和 Mock
+- 便于切换数据源
+
+#### SQLModel ORM (models/)
+
+类型安全的 ORM 模型，基于 Pydantic V2 和 SQLAlchemy 2.0：
+
+```python
+class Agent(SQLModel, table=True):
+    id: UUID = Field(default_factory=uuid4, primary_key=True)
+    name: str
+    description: str | None = None
+    temperature: float | None = None
+    prompt: str | None = None
+    user_id: str = Field(index=True)
+    provider_id: UUID | None = Field(index=True)
+    require_tool_confirmation: bool = False
+    created_at: datetime  # TIMESTAMP with timezone
+    updated_at: datetime  # TIMESTAMP with timezone
+```
+
+#### 数据库支持
+
+**PostgreSQL** (生产环境)
+- 完整的事务支持
+- JSONB 用于存储复杂结构
+- 全文搜索能力
+- 高并发性能
+
+**SQLite** (开发环境)
+- 无需外部服务
+- 快速本地开发
+
+## 核心数据模型
+
+### 数据模型关系
+
+系统的核心数据模型包括以下实体及其关系：
+
+**用户与资源关系**
+- 用户拥有多个代理 (Agent)
+- 用户创建多个会话 (Session)
+- 用户创建多个图代理 (GraphAgent)
+- 用户生成消费记录 (ConsumeRecord)
+
+**代理与配置关系**
+- 代理使用多个 MCP 服务器
+- 代理关联一个提供者 (Provider)
+
+**会话层级关系**
+- 会话包含多个主题 (Topic)
+- 主题包含多个消息 (Message)
+
+**工作流关系**
+- 图代理包含多个节点 (GraphNode)
+- 图代理定义多个边 (GraphEdge)
+
+**提供者关系**
+- 提供者定义多个工具 (Tool)
+
+### 关键模型详解
+
+#### User 上下文
+
+虽然 User 信息不直接存储在数据库中，但通过 \`user_id\` 和 \`auth_provider\` 字段维护用户上下文：
+- 多租户隔离：每个 user_id 拥有独立的 agents、sessions 等
+- 认证提供者跟踪：支持多个身份提供者
+
+#### Agent (代理)
+
+```python
+class Agent(SQLModel, table=True):
+    # 基本信息
+    name: str              # 代理名称
+    description: str       # 代理描述
+    avatar: str            # 头像 URL
+    tags: list[str]        # 标签分类
+    
+    # 配置
+    model: str             # 使用的 LLM 模型
+    temperature: float     # 温度参数 (0-1)
+    prompt: str            # 系统提示词
+    
+    # 关联
+    user_id: str           # 所有者用户 ID
+    provider_id: UUID      # 关联的提供者 UUID
+    
+    # 工具确认
+    require_tool_confirmation: bool  # 调用工具前是否需要用户确认
+    
+    # 时间戳
+    created_at: datetime   # 创建时间
+    updated_at: datetime   # 更新时间
+```
+
+#### Session & Topic & Message
+
+会话是多轮对话的容器：
+- **Session**: 一次完整的会话，包含一个默认主题
+- **Topic**: 主题是消息的分组，一个会话可有多个主题
+- **Message**: 单条消息，包含 role (user/assistant) 和 content
+
+```python
+# 创建流程
+POST /sessions
+  └─ 自动创建一个 Topic
+      └─ Topic 包含 Messages
+```
+
+#### GraphAgent (图代理)
+
+基于 LangGraph 的工作流代理：
+
+```python
+class GraphAgent(SQLModel, table=True):
+    name: str
+    description: str
+    state_schema: dict    # JSON - 定义状态结构
+    is_active: bool       # 是否激活
+    is_published: bool    # 是否发布
+    is_official: bool     # 是否为官方代理
+    parent_agent_id: UUID # 版本控制 - 指向上一版本
+```
+
+#### ConsumeRecord (消费记录)
+
+记录每次 API 使用的消费：
+
+```python
+class ConsumeRecord(SQLModel, table=True):
+    user_id: str           # 用户 ID
+    amount: int            # 消费数量
+    auth_provider: str     # 认证提供者
+    
+    # 业务关联
+    session_id: UUID       # 关联的会话
+    topic_id: UUID         # 关联的主题
+    message_id: UUID       # 关联的消息
+    
+    # 计费状态
+    consume_state: str     # pending/success/failed
+    remote_response: str   # 远程计费系统响应
+    
+    # 幂等性
+    biz_no: int           # 业务编号（自增，用于去重）
+```
+
+## 通信流程
+
+### 请求-响应流程
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant API as API Handler
+    participant Auth as Auth Middleware
+    participant Service as Service Layer
+    participant Repo as Repository
+    participant DB as Database
+    
+    Client->>API: HTTP Request + Bearer Token
+    API->>Auth: 验证 Token
+    Auth->>Auth: 提取 user_id & provider
+    Auth->>Service: 注入用户上下文
+    Service->>Repo: 调用 CRUD 方法
+    Repo->>DB: SQL 查询/插入/更新
+    DB->>Repo: 返回结果
+    Repo->>Service: 返回数据
+    Service->>Service: 业务逻辑处理
+    Service->>API: 返回响应
+    API->>Client: HTTP Response (JSON)
+```
+
+### WebSocket 流程
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant WS as WebSocket Handler
+    participant Chat as Chat Service
+    participant LLM as LLM Provider
+    
+    Client->>WS: WebSocket 连接
+    WS->>WS: 认证和初始化
+    Client->>WS: 发送消息
+    WS->>Chat: 执行聊天逻辑
+    Chat->>LLM: 调用 LLM API
+    LLM->>Chat: 流式响应
+    Chat->>WS: 转发流
+    WS->>Client: WebSocket 消息 (分块)
+    Client->>WS: 关闭连接
+```
+
+## 生命周期管理
+
+### 应用启动流程
+
+```mermaid
+graph TD
+    A["应用启动"] -->|lifespan 上下文| B["创建数据库表<br/>create_db_and_tables"]
+    B --> C["初始化提供者<br/>initialize_providers_on_startup"]
+    C --> D["初始化系统代理<br/>Chat Agent & Workshop Agent"]
+    D --> E["种子化内置图代理<br/>builtin_agents.seed_to_database"]
+    E --> F["设置 MCP 服务器<br/>create MCP HTTP apps"]
+    F --> G["启动 FastAPI 应用"]
+    G --> H["准备接收请求"]
+```
+
+### 关键启动步骤
+
+1. **数据库表创建**: 使用 SQLModel 创建或迁移所有表
+2. **提供者初始化**: 从环境变量加载 API 密钥
+3. **系统代理创建**: 确保 Chat 和 Workshop 代理存在
+4. **内置代理种子化**: 将预定义的图代理加载到数据库
+5. **MCP 服务器设置**: 为每个已注册的 MCP 服务器创建 HTTP 应用
+6. **生命周期上下文管理**: 使用 AsyncExitStack 管理所有异步资源
+
+## API 设计模式
+
+### RESTful 设计
+
+遵循 REST 最佳实践：
+
+| HTTP 方法 | 操作 | 路由示例 |
+|----------|------|---------|
+| GET | 读取 | /agents 列表，/agents/id 详情 |
+| POST | 创建 | /agents 创建新代理，自动关联 user_id |
+| PUT | 更新 | /agents/id 更新代理配置 |
+| DELETE | 删除 | /agents/id 删除代理 |
+
+### 请求/响应模式
+
+**请求模型** (Pydantic)
+
+```python
+class AgentCreate(SQLModel):
+    name: str
+    description: str | None = None
+    model: str | None = None
+    temperature: float | None = None
+    provider_id: UUID | None = None
+    mcp_server_ids: list[UUID] = []
+```
+
+**响应模式**
+
+```python
+class AgentRead(AgentBase):
+    id: UUID
+    created_at: datetime
+    updated_at: datetime
+    # 关联数据
+    mcp_servers: list[MCPServerRead]
+    provider: ProviderRead
+```
+
+### 错误处理
+
+统一的 HTTP 异常处理：
+
+- 400 Bad Request - 请求参数错误
+- 401 Unauthorized - 认证失败
+- 403 Forbidden - 权限不足
+- 404 Not Found - 资源不存在
+- 409 Conflict - 业务冲突 (如重名)
+- 500 Internal Server Error - 服务错误
+
+## 外部集成
+
+### LLM 提供者集成
+
+\`\`\`mermaid
+graph LR
+    ChatService["Chat Service<br/>core/chat/"] -->|langchain| OpenAI["OpenAI"]
+    ChatService -->|langchain| Claude["Anthropic Claude"]
+    ChatService -->|langchain| Gemini["Google Gemini"]
+    ChatService -->|langchain| Azure["Azure OpenAI"]
+    
+    style ChatService fill:#fce4ec
+    style OpenAI fill:#bbdefb
+    style Claude fill:#bbdefb
+    style Gemini fill:#bbdefb
+    style Azure fill:#bbdefb
+\`\`\`
+
+通过 LangChain 的 LLMBase 抽象，支持多个 LLM 提供者。每个提供者通过 \`Provider\` 模型存储其 API 密钥和配置。
+
+### MCP (Model Context Protocol) 集成
+
+MCP 提供工具和资源的标准化接口：
+
+1. **MCP 服务器注册**: 在 `handler/mcp/` 中注册 MCP 服务器
+2. **工具发现**: 通过 Smithery 注册表发现可用工具
+3. **工具调用**: Chat Service 通过 MCP 调用外部工具
+4. **健康检查**: 定期检查 MCP 服务器可用性
+
+### LangChain & LangGraph
+
+- **LangChain**: 用于构建简单的 LLM 调用链
+- **LangGraph**: 用于构建复杂的工作流图 (状态机)
+
+Graph Agents 利用 LangGraph 定义：
+- **Nodes**: 执行步骤 (LLM 调用、工具调用等)
+- **Edges**: 条件转移逻辑
+- **State Schema**: 整个工作流的状态定义
+
+## 部署架构
+
+### Docker 容器化
+
+```dockerfile
+# 基础镜像: Python 3.13.5-slim
+FROM python:3.13.5-slim
+
+# 依赖管理: uv (快速 Python 包管理器)
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+# 环境变量
+ENV TZ=Asia/Shanghai
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+# 安装依赖
+RUN uv sync --locked
+
+# 暴露端口
+EXPOSE 48196
+
+# 启动命令
+CMD ["uv", "run", "python", "-m", "app.main"]
+```
+
+### 环境配置
+
+通过环境变量配置应用：
+
+```bash
+# 数据库
+DATABASE_URL=postgresql://user:password@host:5432/xyzen
+
+# LLM 提供者
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+GOOGLE_API_KEY=...
+
+# 认证
+CASDOOR_ENDPOINT=https://...
+BOHRIUM_API_KEY=...
+
+# 应用
+DEBUG=false
+HOST=0.0.0.0
+PORT=48196
+```
+
+### 多环境部署
+
+- **开发环境**: SQLite + 快速迭代
+- **测试环境**: PostgreSQL + 完整功能测试
+- **生产环境**: PostgreSQL + 高可用配置 + 监控日志
+
+## 技术栈总结
+
+| 分层 | 技术 | 说明 |
+|-----|------|------|
+| **Web 框架** | FastAPI | 高性能异步 Web 框架 |
+| **异步运行时** | AsyncIO | Python 异步编程 |
+| **ORM** | SQLModel + SQLAlchemy | 类型安全的 ORM |
+| **数据库** | PostgreSQL / SQLite | 关系型数据库 |
+| **迁移工具** | Alembic | 数据库版本管理 |
+| **AI/Agent** | LangChain | LLM 调用框架 |
+| **工作流引擎** | LangGraph | 复杂业务流程编排 |
+| **实时通信** | WebSocket | 双向实时通信 |
+| **工具协议** | MCP | 标准化工具接口 |
+| **容器化** | Docker | 标准化部署 |
+| **包管理** | uv | 快速依赖管理 |
+| **认证** | JWT + 多提供者 | 安全身份验证 |
+| **日志** | 结构化日志 | 便于调试和监控 |
+
+## 设计原则
+
+### 1. 关注点分离 (Separation of Concerns)
+
+每个模块专注于单一职责：
+- API Handler: 请求/响应处理
+- Service: 业务逻辑
+- Repository: 数据访问
+- Model: 数据定义
+
+### 2. 依赖注入 (Dependency Injection)
+
+使用 FastAPI 的 `Depends` 机制实现：
+
+```python
+async def get_current_user(token: str = Depends(oauth2_scheme)) -> User:
+    return validate_token(token)
+
+@router.get("/agents")
+async def list_agents(current_user: User = Depends(get_current_user)):
+    return await agent_service.list_agents(current_user.id)
+```
+
+### 3. 异步优先 (Async-First)
+
+充分利用 Python AsyncIO：
+- 非阻塞 I/O 操作
+- 高并发处理能力
+- 更好的资源利用
+
+### 4. 类型安全 (Type Safety)
+
+使用 Python 类型注解和 Pydantic：
+- 编译时类型检查
+- 运行时数据验证
+- 更好的 IDE 支持
+
+### 5. 多租户隔离 (Multi-Tenancy)
+
+通过 `user_id` 字段实现：
+- 每个用户的数据完全隔离
+- 数据库查询自动带上 user_id 过滤
+- 无需修改核心逻辑即可支持多用户
+
+## 可扩展性考虑
+
+### 水平扩展
+
+- **无状态 API**: 可运行多个副本
+- **共享数据库**: PostgreSQL 支持并发访问
+- **负载均衡**: 通过 Nginx/HAProxy 分发请求
+
+### 垂直扩展
+
+- **异步处理**: 使用后台任务处理耗时操作
+- **缓存层**: 可添加 Redis 缓存热数据
+- **CDN**: 静态资源通过 CDN 加速
+
+### 功能扩展
+
+- **插件系统**: MCP 服务器作为插件机制
+- **自定义 Agent**: 用户可创建自己的代理
+- **工作流编排**: LangGraph 支持复杂工作流
+
+<Note>
+完整的架构文档涵盖了从宏观系统设计到微观实现细节的各个层面。建议结合[高级功能](../advanced)文档了解具体功能，以及[API 参考](../api)了解接口细节。
+</Note>
diff --git a/src/app/(cn)/xyzen/chat/mcp/page.mdx b/src/app/(cn)/xyzen/chat/mcp/page.mdx
deleted file mode 100644
index dfd0e2f..0000000
--- a/src/app/(cn)/xyzen/chat/mcp/page.mdx
+++ /dev/null
@@ -1,62 +0,0 @@
-# 自定义 MCP 服务
-
-<Note>
-如果用户希望使用自定义的 MCP 服务，可以仔细阅读以下步骤
-</Note>
-
-
-
-## Xyzen仓库里新建 MCP 服务
-
-1. 克隆 Xyzen 仓库到本地：
-
-```bash
-git clone https://github.com/sciol/xyzen.git
-cd Xyzen
-yarn install
-```
-
-2. 在 `service/handler/mcp/` 目录下创建一个python可执行文件（.py），命名为你的 MCP 服务名称（例如 `my-custom-mcp.py`）。
-可以参考仓库中现有的 MCP 服务脚本进行编写，确保实现 MCP 协议所需的接口和功能。
-
-<Note>
-确保你的 MCP 服务脚本在 `service/handler/mcp/` 目录下，并且可执行。
-例如，可以使用以下命令赋予执行权限：
-
-```bash
-chmod +x service/handler/mcp/my-custom-mcp.py
-```
-</Note>
-
-3. 在本地添加 MCP 服务后，启动Xyzen服务：
-
-```bash
-cd Xyzen
-./launch/dev.sh
-```
-此处运行`dev.sh`启动本地服务器如果遇到问题可参考[部署与使用](/xyzen/deploy)。
-
-4. 在 Xyzen 平台上添加自定义 MCP 服务：
-
-<img alt={'添加自定义MCP服务'} src={'https://storage.sciol.ac.cn/library/docs/Xyzen/custom_server.png'} />
-如上图所示依次填入`Server Name、Description（可选）`和`Server URL`，点击右下角Add Server按钮，即可完成MCP服务的添加。其中Server URL为提供服务的MCP Server地址，例如`http://localhost:8000/xyzen/mcp/my-custom-mcp`。
-添加助手教程和MCP工具调用请参阅[快速开始 - MCP工具调用](/xyzen/quickstart#mcp-tool-call)。
-
-## 从外部网站导入 MCP 服务器的链接
-
-如果你已经有成熟的 MCP 库想把它导入到Xyzen平台使用或者想使用其他开发者的 MCP 库，
-则只需把对应 MCP 服务器的 URL 填入 `Server URL` 即可完成导入。具体获取 MCP 服务器 URL 的方式请参考对应 MCP 服务器的文档说明（以[Smithery](https://smithery.ai/docs/getting_started/quickstart_connect)网站为例）。
-
-<img alt={'添加自定义MCP服务'} src={'https://storage.sciol.ac.cn/library/docs/Xyzen/smithery_mcp.png'} />
-
-Xyzen 支持通过一键部署多个 MCP 社区的服务器，下面的视频是以 MCP Forge 中的Remote MCP Servers 为例，
-展示如何将外部 MCP 服务器导入到 Xyzen 平台中使用。
-
-<div style={{ display: 'flex', gap: '12px' }}>
-  <div style={{ flex: 1 }}>
-    <video src="https://storage.sciol.ac.cn/library/docs/Xyzen/MCP_forge.mov" controls style={{ width: '100%', borderRadius: '8px' }} />
-  </div>
-</div>
-
-更多详情请参阅：[外部MCP工具调用](https://mcpservers.org/remote-mcp-servers)<br />
-欢迎大家贡献新的 MCP 服务到 Xyzen 平台中使用！👏
\ No newline at end of file
diff --git a/src/app/(cn)/xyzen/deploy/frontend_integration/page.mdx b/src/app/(cn)/xyzen/deploy/frontend_integration/page.mdx
new file mode 100644
index 0000000..e69de29
diff --git a/src/app/(cn)/xyzen/deploy/graph_agent/page.mdx b/src/app/(cn)/xyzen/deploy/graph_agent/page.mdx
new file mode 100644
index 0000000..751643e
--- /dev/null
+++ b/src/app/(cn)/xyzen/deploy/graph_agent/page.mdx
@@ -0,0 +1,176 @@
+## 1. 图 Agent（Graph Agent）
+
+### 概述
+
+图 Agent 是 Xyzen 中最强大的功能之一，它突破了传统单轮对话的局限，
+允许你构建复杂的、多步骤的 AI 工作流。与简单的聊天 Assistant 不同，
+图 Agent 采用 **LangGraph** 技术栈，能够处理：
+
+**核心能力**
+- **多节点编排**：将复杂任务分解为多个独立的处理节点，每个节点专注于特定功能
+- **条件分支控制**：根据实时执行结果动态选择执行路径，支持 if-else 分支和动态路由
+- **状态管理**：在整个工作流中维护和传递执行上下文，节点间可以共享和修改状态
+- **循环和递归**：支持需要重复迭代的任务，如多轮对话、数据清理等
+- **多轮推理**：实现复杂的思维链（Chain of Thought），逐步推导出最终答案
+
+### 核心概念
+
+#### 状态图（State Graph）
+
+**状态图**是图 Agent 的核心架构。它用来定义工作流中所有数据的结构和流向。
+简单来说，状态图就像是一个包含了所有变量的"上下文对象"，
+工作流中的每个节点都可以读取这个状态，并根据需要修改它。
+
+**状态通常包含**：
+- **输入数据**：用户的查询、上传的文件等初始信息
+- **中间结果**：各个节点的处理结果，用于后续节点参考
+- **执行上下文**：当前的执行步骤、错误信息、临时计算结果等
+- **最终输出**：工作流的最终结果，返回给用户
+
+通过良好的状态设计，你可以确保工作流的各个部分能够有效地协作。
+
+#### 节点类型
+
+节点是图 Agent 的基本执行单元。Xyzen 提供了多种预定义的节点类型，每种类型服务于不同的目的：
+
+**LLM 节点** - 调用大语言模型进行推理。这类节点可以：
+- 分析用户的查询意图和复杂度
+- 生成文本内容、代码、分析报告等
+- 制定执行计划和策略
+- 总结和综合多个源的信息
+
+**工具节点** - 执行外部工具和 `MCP Server`。典型用途包括：
+- 调用数据库查询或搜索服务
+- 执行计算密集的操作
+- 与第三方 API 交互
+- 文件处理和数据转换
+
+**路由节点** - 作为工作流的"决策中心"。路由节点：
+- 根据条件判断工作流应该走哪个分支
+- 支持多条件的复杂判断逻辑
+- 避免不必要的计算成本
+
+**子 Agent 节点** - 调用其他已有的 Agent。这使你能够：
+- 复用已有的 Agent，避免重复开发
+- 构建分层的 Agent 架构
+- 委派特定的专业任务给专门的 Agent
+
+**特殊节点** - `START` 和 `END` 节点标记工作流的入口和出口点。
+
+#### 边（Edges）
+
+边定义了节点之间的连接关系和执行流向。在图 Agent 中，边有两种主要类型：
+
+**简单边** - 最直接的连接方式。当一个节点完成执行时，工作流无条件地流向下一个节点。
+这种边适用于流程是固定的、无需根据前一个节点的结果进行判断的场景。
+
+**条件边** - 根据执行结果进行动态路由。条件边允许你定义一个判断条件，
+根据状态的值决定工作流走哪条分支。例如，如果用户的查询被判定为"简单问题"，
+则走快速回答路径；如果是"复杂问题"，则走深度分析路径。
+这种灵活的路由机制使得工作流能够适应不同的输入场景。
+
+### 构建图 Agent
+
+构建一个有效的图 Agent 需要经历三个关键步骤。这个过程既是技术性的，
+也是创意性的——你需要思考如何最优地分解问题。
+
+#### 第一步：定义状态模式
+
+在开始构建图 Agent 前，你需要明确定义在整个工作流中会用到哪些数据。
+`状态模式`就像是你的工作流的"蓝图"，明确指出**工作流需要处理哪些类型的数据、
+每个数据字段的含义是什么、这些数据如何在节点间流动**。
+
+良好的状态设计应该：
+- **清晰完整**：包含所有必需的数据，避免遗漏
+- **避免冗余**：不要存储可以由其他数据派生出来的信息
+- **易于扩展**：当工作流演进时，容易添加新的状态字段
+
+例如，在一个文档分析工作流中，你的状态可能包括用户的**查询、文档内容、分析结果和最终答案**。这样，无论工作流有多复杂，每个节点都能获取它需要的信息。
+
+#### 第二步：创建节点
+
+完成状态设计后，接下来创建节点。每个节点都是工作流中的一个处理单元，你需要为它定义：
+
+**节点的职责** - 清晰地描述这个节点做什么。是分析用户意图、搜索数据库、调用 API，还是生成报告。
+
+**节点的配置** - 取决于节点类型：
+- LLM 节点需要选择模型、设置温度参数（控制创意度）、编写系统提示
+- 工具节点需要指定调用哪个外部服务或 API
+- 路由节点需要定义判断条件
+
+**节点的输入输出** - 明确指出节点从状态中读取哪些字段，以及修改或添加哪些字段。
+
+#### 第三步：连接节点
+
+节点创建完成后，你需要通过边（Edges）将它们连接起来，形成完整的工作流。这是最关键的一步，因为：
+
+**执行顺序** - 边决定了工作流的执行顺序。你需要思考：哪个节点应该先执行？哪个节点的输出是另一个节点的输入？
+
+**条件分支** - 通过添加条件边，你可以根据节点的输出进行分支。例如，在分析用户查询后，可以根据复杂度判断是直接回答还是进行深度分析。
+
+**错误处理** - 你可以添加错误处理分支，当某个节点执行失败时，工作流转向错误处理节点。
+
+在可视化编辑器中，连接节点就像在 Figma 中绘制连线一样直观——拖拽从一个节点到另一个节点，然后配置边的条件（如果是条件边）。
+
+<Note>
+**最佳实践**：避免创建过于复杂的工作流。一般来说，超过 10-15 个节点的工作流会变得难以理解和维护。
+如果工作流变得太复杂，考虑拆分为多个子 Agent。
+</Note>
+
+### 实战示例：科研论文分析工作流
+
+我们来看一个完整的实际案例，了解如何将上述概念应用到真实场景中。
+
+<Mermaid chart={`
+graph TD
+    START["START<br/>用户输入论文"] --> EXTRACT["EXTRACT_TEXT<br/>提取论文文本"]
+    EXTRACT --> ANALYZE["ANALYZE_QUERY<br/>分析用户问题"]
+    ANALYZE --> ROUTER{"问题复杂度<br/>判断"}
+    ROUTER -->|简单问题<br/>complexity < 5| QUICK["QUICK_ANSWER<br/>快速回答"]
+    ROUTER -->|复杂问题<br/>complexity ≥ 5| DEEP["DEEP_ANALYSIS<br/>深度分析"]
+    QUICK --> SYNTHESIS["SYNTHESIS<br/>综合答案"]
+    DEEP --> SYNTHESIS
+    SYNTHESIS --> END["END<br/>输出结果"]
+    
+    style START fill:#4f46e5,stroke:#312e81,stroke-width:2px,color:#fff
+    style EXTRACT fill:#7c3aed,stroke:#5b21b6,stroke-width:2px,color:#fff
+    style ANALYZE fill:#7c3aed,stroke:#5b21b6,stroke-width:2px,color:#fff
+    style ROUTER fill:#ec4899,stroke:#be185d,stroke-width:2px,color:#fff
+    style QUICK fill:#06b6d4,stroke:#0e7490,stroke-width:2px,color:#fff
+    style DEEP fill:#06b6d4,stroke:#0e7490,stroke-width:2px,color:#fff
+    style SYNTHESIS fill:#8b5cf6,stroke:#6d28d9,stroke-width:2px,color:#fff
+    style END fill:#10b981,stroke:#047857,stroke-width:2px,color:#fff
+`} />
+
+这个工作流展示了图 Agent 的几个关键特性：
+
+**提取节点** - 首先解析上传的论文文件，提取其中的文本内容。这个节点调用文本处理工具，输出清理后的论文文本。
+
+**分析节点** - 接收用户的问题和论文文本，使用 LLM 分析这个问题的复杂度。分析的结果（一个 0-10 的分数）被保存到状态中。
+
+**路由分支** - 这是工作流的核心决策点。根据分析得出的复杂度分数：
+- 如果是简单问题（比如"这篇论文的作者是谁"），直接进入快速回答路径
+- 如果是复杂问题（比如"这篇论文与之前的研究相比有哪些创新"），进入深度分析路径
+
+**并行处理** - 两个分支最终汇聚到综合节点，无论采用哪个路径，最后都要生成最终答案。
+
+**优势** - 这个设计既保证了简单问题的快速响应（降低成本），又能处理复杂问题（提升质量）。
+
+### 执行图 Agent
+
+图 Agent 构建完成后，你可以通过两种方式执行它，取决于你的应用场景：
+
+**流式执行（WebSocket）** - 这是实时交互式应用的首选。当用户在前端提交查询时，后端通过 WebSocket 连接向前端实时推送工作流的执行进度。这样用户可以看到：
+- 当前正在执行哪个节点
+- 节点的中间输出（如思考过程、数据库查询结果等）
+- 最终答案生成的过程
+
+这种方式特别适合需要用户交互、需要中间确认的场景。例如，在执行某个危险操作前，可以暂停工作流，等待用户确认。
+
+**同步执行（REST API）** - 当你的应用是后端服务，或者不需要实时反馈时，可以直接调用 REST API。工作流会在后端完整执行，最后返回结果。这种方式更简单，适合批量处理任务。
+
+**关键区别**：
+- 流式执行适合用户交互场景，提升用户体验
+- 同步执行适合服务端场景，更容易集成
+
+无论选择哪种方式，Xyzen 都会自动记录执行过程、性能指标和消费成本，帮助你监控和优化工作流。
\ No newline at end of file
diff --git a/src/app/(cn)/xyzen/deploy/page.mdx b/src/app/(cn)/xyzen/deploy/page.mdx
deleted file mode 100644
index 01d152c..0000000
--- a/src/app/(cn)/xyzen/deploy/page.mdx
+++ /dev/null
@@ -1,188 +0,0 @@
-# 部署与使用
-
-Xyzen 支持多种部署方式，满足不同的使用场景。
-
-## 部署方式
-
-### 1. 全栈部署（推荐用于生产环境）
-
-将 Xyzen 作为完整的全栈应用部署，包含前端界面和后端服务。
-
-#### 前置要求
-
-- Docker 和 Docker Compose
-- 至少 2GB 可用内存
-- 网络连接（用于下载依赖）
-
-#### 部署步骤
-
-1. **克隆项目**
-
-```bash
-git clone https://github.com/sciol/xyzen.git
-cd xyzen
-yarn install
-```
-
-2. **配置环境变量**
-
-```bash
-cp .env.example .env
-# 编辑 .env 文件，配置必要的环境变量
-```
-
-3. **启动中间件**
-
-```bash
-docker compose -f ./docker/docker-compose.mid.yaml --env-file ".env.example" up -d
-```
-
-4. **启动后端服务**
-
-```bash
-# 进入后端项目
-cd service 
-# 安装依赖
-uv sync -dev
-# 激活环境
-source ./.venv/bin/activate
-# 启动服务
-python -m cmd.main
-```
-
-5. **访问应用**
-
-打开浏览器访问 `http://localhost:3000` 即可使用 Xyzen。
-
-### 2. 前端 NPM 包集成
-
-如果你已经有自己的前端项目，可以通过 NPM 包的方式集成 Xyzen 的前端组件。
-
-#### 安装包
-
-```bash
-yarn add @sciol/xyzen
-```
-
-#### 基本使用
-
-```tsx
-import { XyzenProvider, useXyzen } from '@sciol/xyzen'
-
-function App() {
-  return (
-    <XyzenProvider 
-      apiKey="your-api-key"
-      endpoint="https://your-xyzen-server.com"
-    >
-      <YourApp />
-    </XyzenProvider>
-  )
-}
-```
-
-#### 配置说明
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `apiKey` | string | 是 | 你的 API 密钥 |
-| `endpoint` | string | 是 | Xyzen 后端服务地址 |
-| `model` | string | 否 | 默认使用的模型，如 'gpt-4' |
-| `timeout` | number | 否 | 请求超时时间（毫秒），默认 30000 |
-
-#### 本地测试
-
-在集成到生产环境之前，建议先在本地测试：
-
-```bash
-# 克隆示例项目
-git clone https://github.com/sciol/xyzen-examples.git
-cd xyzen-examples
-
-# 安装依赖
-yarn install
-
-# 配置环境变量
-cp .env.example .env
-# 编辑 .env 文件
-
-# 启动开发服务器
-yarn dev
-```
-
-## 环境配置
-
-### 必需的环境变量
-
-```bash
-# 数据库配置
-DATABASE_URL=postgresql://username:password@localhost:5432/xyzen
-
-# Redis 配置
-REDIS_URL=redis://localhost:6379
-
-# API 密钥
-XYZEN_API_KEY=your-secret-api-key
-
-# AI 服务商配置
-OPENAI_API_KEY=your-openai-key
-ALIYUN_API_KEY=your-aliyun-key
-# ... 其他 AI 服务商配置
-```
-
-### 可选配置
-
-```bash
-# 日志级别
-LOG_LEVEL=info
-
-# 服务端口
-PORT=8000
-
-# CORS 配置
-CORS_ORIGINS=http://localhost:3000,https://yourdomain.com
-```
-
-## 性能优化
-
-### 生产环境建议
-
-1. **使用反向代理**：配置 Nginx 或 Apache 作为反向代理
-2. **启用 HTTPS**：使用 Let's Encrypt 或商业证书
-3. **数据库优化**：根据数据量调整 PostgreSQL 配置
-4. **缓存策略**：合理配置 Redis 缓存
-5. **监控告警**：设置系统监控和告警
-
-### 资源需求
-
-| 组件 | 最小配置 | 推荐配置 |
-|------|----------|----------|
-| CPU | 1 核 | 2 核 |
-| 内存 | 2GB | 4GB |
-| 存储 | 10GB | 50GB |
-| 网络 | 10Mbps | 100Mbps |
-
-## 故障排除
-
-### 常见问题
-
-1. **服务启动失败**
-   - 检查端口是否被占用
-   - 确认环境变量配置正确
-   - 查看日志文件排查错误
-
-2. **数据库连接失败**
-   - 确认数据库服务正在运行
-   - 检查连接字符串格式
-   - 验证用户名密码权限
-
-3. **AI 服务调用失败**
-   - 检查 API 密钥是否有效
-   - 确认网络连接正常
-   - 查看 AI 服务商状态
-
-### 获取帮助
-
-- [GitHub Issues](https://github.com/sciol/xyzen/issues)
-- [文档讨论](https://github.com/sciol/xyzen/discussions)
-- [社区支持](https://discord.gg/sciol)
\ No newline at end of file
diff --git a/src/app/(cn)/xyzen/deploy/primary_deploy/page.mdx b/src/app/(cn)/xyzen/deploy/primary_deploy/page.mdx
new file mode 100644
index 0000000..65587cf
--- /dev/null
+++ b/src/app/(cn)/xyzen/deploy/primary_deploy/page.mdx
@@ -0,0 +1,12 @@
+# 集成与使用
+
+Xyzen 支持侧边栏集成方式，可满足不同项目的使用场景。
+
+## 集成方法
+1
+### 
+### 获取帮助
+
+- [GitHub Issues](https://github.com/sciol/xyzen/issues)
+- [文档讨论](https://github.com/sciol/xyzen/discussions)
+- [社区支持](https://discord.gg/sciol)
\ No newline at end of file
diff --git a/src/app/(cn)/xyzen/design/page.mdx b/src/app/(cn)/xyzen/design/page.mdx
new file mode 100644
index 0000000..aad2a18
--- /dev/null
+++ b/src/app/(cn)/xyzen/design/page.mdx
@@ -0,0 +1,9 @@
+# UI 使用及设计规范
+本章节介绍 Xyzen 的 UI 设计规范和原则，帮助开发者和设计师创建一致且用户友好的界面。
+
+## @sciol/ui 组件库
+
+Xyzen 使用 [@sciol/ui](https://www.npmjs.com/package/@sciol/ui) 
+作为主要的前端组件库。
+该组件库基于 shadcn 和 vercel 构建，提供了一套高度可定制且易于使用的 UI 组件。
+<img src="/xyzen/sciol_ui.pnghttps://storage.sciol.ac.cn/library/docs/Xyzen/sciol_ui.png" alt="UI 组件库示例" />
\ No newline at end of file
diff --git a/src/app/(cn)/xyzen/faq/page.mdx b/src/app/(cn)/xyzen/faq/page.mdx
index 86a5165..c72d731 100644
--- a/src/app/(cn)/xyzen/faq/page.mdx
+++ b/src/app/(cn)/xyzen/faq/page.mdx
@@ -2,15 +2,16 @@
 # ❓ Xyzen 常见问题 - FAQ
 
 <Note>
-如果你在使用 Xyzen 过程中遇到问题，欢迎查阅以下常见问题解答。如果没有找到答案，可以通过 GitHub Issues 或 Discussions 寻求帮助。 
+如果你在使用 Xyzen 过程中遇到问题，欢迎查阅以下常见问题解答。
+如果没有找到答案，可以通过 `GitHub Issues` 或 `Discussions` 寻求帮助。 
 </Note>
 
 ## 基础问题
 
 ### Q: Xyzen 是什么？
 
-**A:** Xyzen（玄藏）是一个开源的、轻量级的 AI 聊天和智能体框架，
-支持通过 NPM Package 方式快速集成到现有的 React 应用中，而无需整站部署。
+**A:** `Xyzen（玄藏）`是一个开源的、轻量级的 AI 聊天和智能体框架，
+支持通过 `NPM Package` 方式快速集成到现有的 React 应用中，而无需整站部署。
 Xyzen 专注于核心的 LLM 业务逻辑，提供可高度定制化的解决方案。
 
 ### Q: Xyzen 与其他聊天应用有什么区别？
@@ -25,7 +26,8 @@ Xyzen 专注于核心的 LLM 业务逻辑，提供可高度定制化的解决方
 
 ### Q: Xyzen 免费吗？
 
-**A:** 是的，Xyzen 完全免费且开源，基于 GPLv3 许可证。你可以自由地在遵循许可证条款的前提下使用、修改和分发。
+**A:** 是的，Xyzen 完全免费且开源，基于 `GPLv3` 许可证。
+你可以自由地在遵循许可证条款的前提下使用、修改和分发。
 
 ## 集成与使用
 
@@ -82,13 +84,14 @@ function App() {
 - 集成你的设计系统
 - 支持深色/浅色模式
 
-你可以通过 CSS 变量或 API 配置来实现这些定制。
+你可以通过 `CSS 变量`或 `API 配置`来实现这些定制。
 
 ## 功能特性
 
 ### Q: 什么是 MCP（Model Context Protocol）？
 
-**A:** MCP 是模型上下文协议（Model Context Protocol），Xyzen 支持通过一键部署创建 MCP 服务器，实现以下功能：
+**A:** **MCP 是模型上下文协议（Model Context Protocol）**，
+Xyzen 支持通过一键部署创建 MCP 服务器，实现以下功能：
 
 - **统一模型管理** - 在一个地方管理多个 AI 模型
 - **智能路由** - 根据任务特性自动选择最优模型
@@ -102,7 +105,7 @@ function App() {
 
 **A:** 可以的，Xyzen 支持本地 LLM：
 
-1. **部署本地模型** - 使用 Ollama、LLaMA 等开源模型
+1. **部署本地模型** - 使用 `Ollama`、`LLaMA` 等开源模型
 2. **完全离线运行** - 数据不发送到任何云服务
 3. **隐私保护** - 所有对话和数据都在本地存储
 4. **性能权衡** - 速度可能比云服务慢，但完全隐私
@@ -114,7 +117,7 @@ function App() {
 **A:** Xyzen 采用现代化架构：
 
 **前端：**
-- React + TypeScript
+- `React` + `TypeScript`
 - 响应式设计，支持移动端
 - 渐进式 Web 应用 (PWA)
 
@@ -198,7 +201,7 @@ yarn dev
 4. **提交测试** - 确保测试通过：`uv run pytest`
 5. **代码检查** - 运行质量检查：`uv run pre-commit run --all-files`
 6. **提交 PR** - 向主仓库提交 Pull Request
-
+更多详情请参考 [贡献指南](/xyzen/dev)。
 
 ### Q: 代码质量有什么标准吗？
 
diff --git a/src/app/(cn)/xyzen/mcp/page.mdx b/src/app/(cn)/xyzen/mcp/page.mdx
index e69de29..dfd0e2f 100644
--- a/src/app/(cn)/xyzen/mcp/page.mdx
+++ b/src/app/(cn)/xyzen/mcp/page.mdx
@@ -0,0 +1,62 @@
+# 自定义 MCP 服务
+
+<Note>
+如果用户希望使用自定义的 MCP 服务，可以仔细阅读以下步骤
+</Note>
+
+
+
+## Xyzen仓库里新建 MCP 服务
+
+1. 克隆 Xyzen 仓库到本地：
+
+```bash
+git clone https://github.com/sciol/xyzen.git
+cd Xyzen
+yarn install
+```
+
+2. 在 `service/handler/mcp/` 目录下创建一个python可执行文件（.py），命名为你的 MCP 服务名称（例如 `my-custom-mcp.py`）。
+可以参考仓库中现有的 MCP 服务脚本进行编写，确保实现 MCP 协议所需的接口和功能。
+
+<Note>
+确保你的 MCP 服务脚本在 `service/handler/mcp/` 目录下，并且可执行。
+例如，可以使用以下命令赋予执行权限：
+
+```bash
+chmod +x service/handler/mcp/my-custom-mcp.py
+```
+</Note>
+
+3. 在本地添加 MCP 服务后，启动Xyzen服务：
+
+```bash
+cd Xyzen
+./launch/dev.sh
+```
+此处运行`dev.sh`启动本地服务器如果遇到问题可参考[部署与使用](/xyzen/deploy)。
+
+4. 在 Xyzen 平台上添加自定义 MCP 服务：
+
+<img alt={'添加自定义MCP服务'} src={'https://storage.sciol.ac.cn/library/docs/Xyzen/custom_server.png'} />
+如上图所示依次填入`Server Name、Description（可选）`和`Server URL`，点击右下角Add Server按钮，即可完成MCP服务的添加。其中Server URL为提供服务的MCP Server地址，例如`http://localhost:8000/xyzen/mcp/my-custom-mcp`。
+添加助手教程和MCP工具调用请参阅[快速开始 - MCP工具调用](/xyzen/quickstart#mcp-tool-call)。
+
+## 从外部网站导入 MCP 服务器的链接
+
+如果你已经有成熟的 MCP 库想把它导入到Xyzen平台使用或者想使用其他开发者的 MCP 库，
+则只需把对应 MCP 服务器的 URL 填入 `Server URL` 即可完成导入。具体获取 MCP 服务器 URL 的方式请参考对应 MCP 服务器的文档说明（以[Smithery](https://smithery.ai/docs/getting_started/quickstart_connect)网站为例）。
+
+<img alt={'添加自定义MCP服务'} src={'https://storage.sciol.ac.cn/library/docs/Xyzen/smithery_mcp.png'} />
+
+Xyzen 支持通过一键部署多个 MCP 社区的服务器，下面的视频是以 MCP Forge 中的Remote MCP Servers 为例，
+展示如何将外部 MCP 服务器导入到 Xyzen 平台中使用。
+
+<div style={{ display: 'flex', gap: '12px' }}>
+  <div style={{ flex: 1 }}>
+    <video src="https://storage.sciol.ac.cn/library/docs/Xyzen/MCP_forge.mov" controls style={{ width: '100%', borderRadius: '8px' }} />
+  </div>
+</div>
+
+更多详情请参阅：[外部MCP工具调用](https://mcpservers.org/remote-mcp-servers)<br />
+欢迎大家贡献新的 MCP 服务到 Xyzen 平台中使用！👏
\ No newline at end of file
diff --git a/src/app/(cn)/xyzen/navigation.ts b/src/app/(cn)/xyzen/navigation.ts
index 3ec04fb..3e8dd5c 100644
--- a/src/app/(cn)/xyzen/navigation.ts
+++ b/src/app/(cn)/xyzen/navigation.ts
@@ -4,24 +4,36 @@ const navigation: Array<NavGroup> = [
   {
     title: 'Xyzen 玄藏',
     links: [
-      { title: '介绍', href: `/xyzen` },
+      { title: '总览', href: `/xyzen` },
       { title: '快速开始', href: `/xyzen/quickstart` },
-      // { title: 'MCP', href: `/xyzen/mcp` },
       { title: '示例演示', href: `/xyzen/demo` },
-      {title:'自定义MCP服务', href:`/xyzen/chat/mcp`},
-      {title:'常见问题', href:`/xyzen/faq`},
+      { title: '路线图', href: `/xyzen/roadmap` },
+      { title: 'Xyzen 架构', href: `/xyzen/architecture` },
     ],
   },
   {
-    title: 'Self-Host',
+    title: '用户指南',
     links: [
-      { title: '部署与使用', href: `/xyzen/deploy` },
+      { title: '功能特性', href: `/xyzen/user_guide` },
+      { title: '自定义 MCP 服务', href: `/xyzen/mcp` },
+      { title: '常见问题', href: `/xyzen/faq` },
+      { title: '高级功能', href: `/xyzen/advanced` },
+    ],
+  },
+  {
+    title: '私有化部署',
+    links: [
+      { title: '部署使用', href: `/xyzen/deploy/primary_deploy` },
+      { title: '与前端项目集成', href: `/xyzen/deploy/frontend_integration` },
+      { title: '创建图 Agent', href: `/xyzen/deploy/graph_agent` },
     ],
   },
   {
     title: 'Contribution',
     links: [
       { title: '贡献与开发', href: `/xyzen/dev` },
+      { title: 'API 参考', href: `/xyzen/api` },
+      { title: 'UI 设计规范', href: `/xyzen/design` },
     ],
   },
 ]
diff --git a/src/app/(cn)/xyzen/roadmap/page.mdx b/src/app/(cn)/xyzen/roadmap/page.mdx
new file mode 100644
index 0000000..e69de29