feat: 新增 Xyzen 完整文档 - 包括架构、API 参考、高级功能、部署指南等#40
Merged
Conversation
✅ Deploy Preview for cloudocs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
审阅者指南此 PR 为 Xyzen 平台添加了一整套中文文档，引入了涵盖自定义 MCP 服务、系统架构、高级功能、部署指南和 UI 设计指南的新 MDX 页面，并更新了导航结构和完善了现有 FAQ 内容。 Xyzen HTTP 请求/响应流程序列图（摘自文档）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)
Xyzen WebSocket 聊天流程序列图（摘自文档）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: 关闭连接
Xyzen 核心数据模型实体关系图（摘自架构文档）erDiagram
USER ||--o{ AGENT : owns
USER ||--o{ SESSION : creates
USER ||--o{ GRAPHAGENT : creates
USER ||--o{ CONSUMERECORD : generates
AGENT }o--|| PROVIDER : uses
AGENT }o--o{ MCPSERVER : uses
SESSION ||--o{ TOPIC : contains
TOPIC ||--o{ MESSAGE : contains
GRAPHAGENT ||--o{ GRAPHNODE : has
GRAPHAGENT ||--o{ GRAPHEDGE : defines
PROVIDER ||--o{ TOOL : defines
Agent、GraphAgent 和 ConsumeRecord 模型类图（摘自文档）classDiagram
class Agent {
+str name
+str description
+str avatar
+list~str~ tags
+str model
+float temperature
+str prompt
+str user_id
+UUID provider_id
+bool require_tool_confirmation
+datetime created_at
+datetime updated_at
}
class GraphAgent {
+str name
+str description
+dict state_schema
+bool is_active
+bool is_published
+bool is_official
+UUID parent_agent_id
}
class ConsumeRecord {
+str user_id
+int amount
+str auth_provider
+UUID session_id
+UUID topic_id
+UUID message_id
+str consume_state
+str remote_response
+int biz_no
}
MCP 工具调用流程图（摘自高级功能文档）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
Graph Agent 工作流程图（摘自部署指南）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
文件级别变更
提示与命令与 Sourcery 互动
自定义您的体验访问您的 仪表板 以：
获取帮助Original review guide in EnglishReviewer's GuideThis PR adds a complete set of Chinese documentation for the Xyzen platform by introducing new MDX pages covering custom MCP services, system architecture, advanced features, deployment guides, and UI design guidelines, as well as updating the navigation structure and refining existing FAQ content. Sequence diagram for Xyzen HTTP request/response flow (from documentation)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)
Sequence diagram for Xyzen WebSocket chat flow (from documentation)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: 关闭连接
Entity relationship diagram for Xyzen core data models (from architecture documentation)erDiagram
USER ||--o{ AGENT : owns
USER ||--o{ SESSION : creates
USER ||--o{ GRAPHAGENT : creates
USER ||--o{ CONSUMERECORD : generates
AGENT }o--|| PROVIDER : uses
AGENT }o--o{ MCPSERVER : uses
SESSION ||--o{ TOPIC : contains
TOPIC ||--o{ MESSAGE : contains
GRAPHAGENT ||--o{ GRAPHNODE : has
GRAPHAGENT ||--o{ GRAPHEDGE : defines
PROVIDER ||--o{ TOOL : defines
Class diagram for Agent, GraphAgent, and ConsumeRecord models (from documentation)classDiagram
class Agent {
+str name
+str description
+str avatar
+list~str~ tags
+str model
+float temperature
+str prompt
+str user_id
+UUID provider_id
+bool require_tool_confirmation
+datetime created_at
+datetime updated_at
}
class GraphAgent {
+str name
+str description
+dict state_schema
+bool is_active
+bool is_published
+bool is_official
+UUID parent_agent_id
}
class ConsumeRecord {
+str user_id
+int amount
+str auth_provider
+UUID session_id
+UUID topic_id
+UUID message_id
+str consume_state
+str remote_response
+int biz_no
}
Flow diagram for MCP tool invocation process (from advanced features documentation)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
Flow diagram for Graph Agent workflow (from deployment guide)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
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
你好 - 我已经审阅了你的更改 - 以下是一些反馈意见：
- deploy/primary_deploy/page.mdx 目前包含占位符，没有实际说明——如果尚未准备好，请充实内容或删除它。
- design/page.mdx 中的 img 标签的 src (
/xyzen/sciol_ui.pnghttps://...) 格式错误；请将 URL 更正为单个有效路径。 - 架构页面太长了——考虑将其拆分为子页面或部分，以提高可读性并与新的导航结构保持一致。
AI 代理提示
请处理此代码审查中的评论：
## 总体评论
- deploy/primary_deploy/page.mdx 目前包含占位符，没有实际说明——如果尚未准备好，请充实内容或删除它。
- design/page.mdx 中的 img 标签的 src (`/xyzen/sciol_ui.pnghttps://...`) 格式错误；请将 URL 更正为单个有效路径。
- 架构页面太长了——考虑将其拆分为子页面或部分，以提高可读性并与新的导航结构保持一致。
## 单独评论
### 评论 1
<location> `src/app/(cn)/xyzen/design/page.mdx:9` </location>
<code_context>
+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
</code_context>
<issue_to_address>
**问题 (bug_risk):** 图像 src 属性连接了两个 URL；这很可能会破坏图像渲染。
src 属性应仅使用一个有效 URL，以确保图像正确渲染。
</issue_to_address>帮助我变得更有用！请对每条评论点击 👍 或 👎，我将利用这些反馈来改进你的评论。
Original comment in English
Hey there - I've reviewed your changes - here's some feedback:
- The deploy/primary_deploy/page.mdx currently contains placeholders and no real instructions—please flesh it out or remove it if it’s not ready.
- The img tag in design/page.mdx has a malformed src (
/xyzen/sciol_ui.pnghttps://...); please correct the URL to a single valid path. - The architecture page is extremely long—consider breaking it into subpages or sections to improve readability and align with the new navigation structure.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The deploy/primary_deploy/page.mdx currently contains placeholders and no real instructions—please flesh it out or remove it if it’s not ready.
- The img tag in design/page.mdx has a malformed src (`/xyzen/sciol_ui.pnghttps://...`); please correct the URL to a single valid path.
- The architecture page is extremely long—consider breaking it into subpages or sections to improve readability and align with the new navigation structure.
## Individual Comments
### Comment 1
<location> `src/app/(cn)/xyzen/design/page.mdx:9` </location>
<code_context>
+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
</code_context>
<issue_to_address>
**issue (bug_risk):** Image src attribute concatenates two URLs; this will likely break image rendering.
Only one valid URL should be used for the src attribute to ensure the image renders correctly.
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Sourcery 总结
为 Xyzen 添加全面的中文文档，内容包括自定义 MCP 集成、系统架构、高级功能、部署指南和 UI 设计规范，并重新组织导航菜单以展示新章节。
文档：
杂项：
Original summary in English
Summary by Sourcery
Add comprehensive Chinese documentation for Xyzen, including custom MCP integration, system architecture, advanced features, deployment guides, and UI design guidelines, and reorganize the navigation menu to expose the new sections.
Documentation:
Chores: