代码'格式；如果是不需要执行仅用于展示的代码，使用'
+ 
+
+
+#### 🌐 Add External A2A Agents
+
+Nexent supports communication with third-party agents through the A2A protocol. You can discover external A2A agents in the following two ways:
+
+##### Discover Agent via URL
+
+If you know the Agent Card address of the target agent, you can use the URL discovery method:
+
+
+
+ 
+
+
+1. In the External A2A Agent list, click the "Add External Agent" button
+2. Select the "URL Discovery" tab
+3. Fill in the Agent Card URL address, for example: `https://example.com/.well-known/agent.json`
+4. Click the "Discover" button; the system will automatically retrieve the agent's related information
+5. After successful discovery, you can view the agent's name, description, capabilities and other information
+6. Click "Add to List" to complete the addition
+
+> 💡 **Tip**: The Agent Card is an Agent description file that complies with the A2A 1.0 specification, containing the agent's name, description, calling address, capabilities and other information.
+
+##### Discover Agent via Nacos
+
+If your agent is registered with the Nacos service discovery platform, you can use the Nacos discovery method:
+
- 
+ 
+1. In the External A2A Agent list, click the "Add External Agent" button
+2. Select the "Nacos Discovery" tab
+3. For first-time use, you need to configure the Nacos connection information:
+ - **Nacos Server Address**: Fill in the Nacos server address, such as `http://127.0.0.1:8848`
+ - **Namespace ID**: Fill in the Nacos namespace ID (optional)
+ - **Group Name**: Fill in the service group name, default is `DEFAULT_GROUP`
+ - **Username/Password**: Fill in the Nacos access credentials (optional)
+4. Click "Save Configuration" to save the Nacos connection information
+5. Fill in the Agent service name to scan
+6. Click the "Scan" button; the system will obtain matching Agent information from Nacos
+7. The scan results will list all matching Agents. You can select the agents you need and add them to the list
+
+> ⚠️ **Note**: Make sure the Nacos service is running properly and the target Agent is correctly registered with Nacos.
+
+##### Manage Discovered External Agents
+
+In the External A2A Agent list, you can view and manage all discovered external agents:
+
+
+
+ 
+
+
+1. **View Agent Details**: Click on the agent card to view its complete information, including name, description, URL, capability list, etc.
+2. **Test Agent**: Click the "Test" button to send a test message to the agent and verify if it is working properly
+3. **Chat with Agent**: Click the "Chat" button to open a chat window and interact with the agent in real time
+4. **Configure Calling Protocol**: Click the "Protocol Configuration" button to select the calling protocol for this agent:
+ - **HTTP + JSON**: Use REST API style calls
+ - **JSON-RPC**: Use JSON-RPC protocol calls
+5. **Refresh Agent Information**: If the agent information changes, click the "Refresh" button to re-fetch the latest Agent Card
+6. **Remove Agent**: Click the "Remove" button to delete the agent from the discovered list
+
+> 💡 **Use Cases**:
+> - Quickly integrate known third-party agent services through URL discovery
+> - Batch integrate all agents from the same service registry through Nacos discovery
+> - Configure protocols to meet the requirements of different agent service providers
+
### 🛠️ Select Agent Tools
Agents can use various tools to complete tasks, such as knowledge base search, file parsing, image parsing, email sending/receiving, file management, and other local tools. They can also integrate third-party MCP tools or custom tools.
@@ -60,6 +131,8 @@ Agents can use various tools to complete tasks, such as knowledge base search, f
> 2. Please select the `analyze_text_file` tool to enable the parsing function for document and text files.
> 3. Please select the `analyze_image` tool to enable the parsing function for image files.
>
+> ⚠️ **Embedding Model Configuration**: When using the `knowledge_base_search` tool, ensure that the knowledge base has an embedding model configured. For existing knowledge bases, the system will prompt you to select an embedding model. Make sure to select **the same embedding model used when creating the knowledge base**. If the selected model differs from the one used during knowledge base creation, it may cause search failures or inaccurate results.
+>
> 📚 Want to learn about all the built-in local tools available in the system? Please refer to [Local Tools Overview](./local-tools/index.md).
### 🔌 Add MCP Tools
@@ -108,6 +181,39 @@ You can add MCP services to Nexent in the following two ways:
Many third-party services such as [ModelScope](https://www.modelscope.cn/mcp) provide MCP services, which you can quickly integrate and use.
You can also develop your own MCP services and connect them to Nexent; see [MCP Tool Development](../backend/tools/mcp).
+**3️⃣ Convert Stock API to MCP Service**
+
+🔔 This method is suitable for quickly converting existing REST API endpoints into MCP tools without additional development, allowing agents to call existing API capabilities:
+
+>1. In the MCP Config module, select **"API to MCP"** as the access type
+>
+>2. Fill in the API basic information in the input box below:
+> - **Service Name**: Display name for the MCP service
+> - **OpenAPI JSON**: OpenAPI 3.x specification in JSON format
+> - **Base Service URL**: Base address of the API service (supports http/https)
+>
+>3. Click the **+ Add** button in the lower right corner to complete the MCP service conversion
+
+
+
+ 
+
+
+>4. After conversion, you can view all externally converted MCP tools in the **Outer APIs** tab
+
+
+
+ 
+
+
+
+
+ 
+
+
+>💡 **Use Cases**:
+>- Quickly integrate internal enterprise REST API endpoints
+>- Convert third-party service HTTP APIs into MCP tools
+>- Generate tools directly from OpenAPI specifications without writing MCP Server code
+
+
### ⚙️ Custom Tools
You can refer to the following guides to develop your own tools and integrate them into Nexent to enrich agent capabilities:
@@ -129,7 +235,7 @@ Nexent provides a "Tool Testing" capability for all types of tools—whether the
- The test `query`, such as "benefits of vitamin C"
- The search `search_mode` (default is `hybrid`)
- The target index list `index_names`, such as `["Medical", "Vitamin Encyclopedia"]`
- - If `index_names` is not entered, it will default to searching all knowledge bases selected on the knowledge base page
+ - If `index_names` is not entered, it will default to searching all knowledge bases selected on the knowledge base page
6. After entering the parameters, click "Execute Test" to start the test and view the test results below
+
@@ -181,6 +287,134 @@ After completing the initial agent configuration, you can debug the agent and fi
After successful debugging, click the "Save" button in the lower right corner, and the agent will be saved and appear in the agent list.
+## 📋 Version Management
+
+Nexent supports agent version management. You can save different versions of agent configurations during the debugging process.
+
+Once the agent configuration is verified, you can publish the agent. After publishing, the agent will be visible in the Agent Space and Start Chat pages.
+
+
+
+If you need to rollback to a previous version, click the "Rollback" button on the version management page.
+
+
+
+### 🚀 Publish as A2A Agent
+
+Nexent supports exposing published agents as A2A Agents for external systems to call. When publishing a version, you can check the "Publish as A2A Agent" option to register the current agent as an A2A 1.0 compliant Agent.
+
+
+ description: "English description of the parameter"
+ description_zh: "Chinese description of the parameter"
+```
+
+**Supported types**: `string`, `number`, `boolean`, `array`, `object`
+
+**Complete example**:
+
+```yaml
+query:
+ type: string
+ required: true
+ description: "Search query string"
+ description_zh: "Search keyword"
+ default: ""
+
+top_k:
+ type: number
+ required: false
+ description: "Number of results to return"
+ description_zh: "Number of returned results"
+ default: 3
+
+enable_rerank:
+ type: boolean
+ required: false
+ description: "Enable result reranking"
+ description_zh: "Whether to enable result reranking"
+ default: false
+```
+
+### config/config.yaml: Setting Parameter Defaults
+
+If you want certain parameters to have default values, create `config/config.yaml`:
+
+```yaml
+# Initial workspace path
+init_path: "/mnt/nexent"
+
+# Maximum number of results
+top_k: 5
+```
+
+### Special Tags
+
+You can use the following special tags in the SKILL.md body:
+
+#### ``: Lazy-loading Example Files
+
+Use the `` tag to reference external files. The referenced file is loaded only when needed, keeping the main `SKILL.md` file lightweight.
+
+```markdown
+## Example Reference
+
+> **Note**: Only load the reference example file when the default Usage examples cannot meet your needs.
+
+`: Declaring Bundled Scripts
+
+If the skill package contains Python or Shell scripts, declare them in `SKILL.md`:
+
+```markdown
+
+#### 语音合成模型
+语音合成模型用于将文本内容即时转换为自然流畅的语音输出，使系统能够以接近真人的方式进行语音交互与反馈。通过低延迟、高拟真度的语音生成能力，确保用户在对话过程中获得连贯、自然的听觉体验。配置合适的实时语音合成模型，可以显著提升语音交互系统的表现力和用户体验。
+- 点击语音合成模型下拉框，从已添加的视觉语言模型中选择一个。
+
+#### 语音识别模型
+语音识别模型用于将用户输入的语音内容实时转换为文本，实现对语音指令和自然语言的准确理解与解析。通过高精度的语音转写与噪声鲁棒能力，确保在复杂环境下依然能够稳定识别用户意图。配置合适的语音识别模型，可以显著提升语音交互系统的理解能力和整体响应效率。
+- 点击语音识别模型下拉框，从已添加的视觉语言模型中选择一个。
+
### ✅ 检查模型连通性
定期检查模型连通性是确保系统稳定运行的重要环节。通过连通性检查功能，您可以及时发现和解决模型连接问题，保证服务的连续性和可靠性。
@@ -224,18 +232,29 @@ Nexent 支持任何 **遵循OpenAI API规范** 的大语言模型供应商，包
使用与大语言模型相同的API Key，但模型URL一般会有所差异，一般以`/v1/rerank`为结尾。
#### 🎤 语音模型
-目前仅支持火山引擎语音，且需要在`.env`中进行配置
+目前支持阿里灵积和火山引擎语音模型，阿里灵积需配置与大语言模型相同的apikey，火山引擎模型需配置appid与token
+**火山引擎**
- **网站**: [volcengine.com/product/voice-tech](https://www.volcengine.com/product/voice-tech)
- **免费额度**: 个人使用可用
- **特色**: 高质量中英文语音合成
-**开始使用**:
+- **开始使用**:
+
+ 1. 注册火山引擎账户
+ 2. 访问语音技术服务
+ 3. 创建应用并获取appid和token
+ 4. 在添加模型页面中配置 TTS/STT 设置
+
+**阿里灵积**
+- **网站**: [aliyun.com/benefit/scene/voice](https://www.aliyun.com/benefit/scene/voice)
+
+- **开始使用**:
-1. 注册火山引擎账户
-2. 访问语音技术服务
-3. 创建应用并获取 API Key
-4. 在环境中配置 TTS/STT 设置
+ 1. 注册阿里云账户
+ 2. 访问阿里千问实时语音技术服务
+ 3. 创建应用并获取 API Key
+ 4. 在添加模型页面中配置 TTS/STT 设置
## 💡 需要帮助
diff --git a/doc/docs/zh/user-guide/skills.md b/doc/docs/zh/user-guide/skills.md
new file mode 100644
index 000000000..54d0f97bb
--- /dev/null
+++ b/doc/docs/zh/user-guide/skills.md
@@ -0,0 +1,476 @@
+---
+title: 技能管理
+---
+
+# 技能管理
+
+技能（Skill）是 Nexent 为智能体扩展能力的核心机制。每个技能将多个工具与使用文档打包为一个可复用的能力单元，可以像搭积木一样为智能体赋予复杂的工作能力。
+
+## 目录
+
+- [技能与工具的关系](#-技能与工具的关系)：理解技能的核心概念
+- [技能使用指南](#-技能使用指南)：如何在智能体开发中使用技能
+- [技能管理](#-技能管理)：创建、编辑、安装外部技能
+- [技能上传指南](#-技能上传指南)：SKILL.md 格式、ZIP 结构、特殊标签与书写规范
+- [NL-to-Skill](#-nl-to-skill)：通过自然语言描述自动生成技能
+- [官方技能一览](#-官方技能一览)：预置技能及其能力说明
+
+## 技能与工具的关系
+
+在 Nexent 中，**工具（Tool）** 与 **技能（Skill）** 是两个不同层次的概念，理解它们的区别有助于更好地为智能体配置能力。
+
+**工具**是智能体可调用的单个原子操作。为智能体启用工具时，LLM 的每次思考都会在工具列表中搜索——这意味着即使某个工具本次对话完全不需要，LLM 仍然会消耗上下文额度去"看到"它。
+
+**技能**则通过 `SKILL.md` 将多个工具的能力组合为一个完整的工作流，并附带参数配置与使用文档。LLM 不需要预先"看到"所有工具，而是根据用户的实际需求，自行判断是否激活某个技能。激活后，系统才会加载对应的工具集——从而有效节省 Token 消耗。
+
+| 维度 | 工具 | 技能 |
+|------|------|------|
+| 粒度 | 单个原子操作 | 多个工具 + 配置 + 文档的组合 |
+| Token 消耗 | 每次对话都占用上下文 | 仅在激活时才加载 |
+| 参数 | 固定参数 schema | 可自定义参数模板 |
+| 分发 | 代码级 | ZIP 包分发，即插即用 |
+
+## 技能使用指南
+
+### 为智能体配置技能
+
+1. 打开 **[智能体开发](./agent-development)** 页面
+2. 在"选择智能体的工具"页签中，找到 **技能（Skills）** 分组
+3. 点击技能名称即可选中，再次点击取消选择
+4. 保存智能体配置
+
+## 技能管理
+
+### 查看已安装的技能
+
+在"选择智能体的工具"技能分组中，系统会展示所有已安装的技能列表，包括：
+- 官方技能
+- 自定义技能
+
+### 创建自定义技能
+
+Nexent 支持两种方式创建自定义技能：上传技能包文件，或通过自然语言描述自动生成。
+
+#### 方式一：上传 SKILL.md 或 ZIP
+
+1. 进入技能配置界面
+2. 点击"上传技能"按钮
+3. 选择 `SKILL.md` 文件（单文件）或 `.zip` 压缩包（完整技能包）
+4. 系统自动解析并创建技能
+
+#### 方式二：NL-to-Skill 自然语言创建
+
+在技能管理页面，点击"**NL 创建技能**"按钮即可进入。具体用法详见下方 [NL-to-Skill](#-nl-to-skill) 专区。
+
+## 技能上传指南
+
+### 技能包结构
+
+技能包可以是单个文件，也可以是包含多个文件的 ZIP 包：
+
+```
+skill-name/
+├── SKILL.md # 技能定义文件（必需）
+├── config/
+│ ├── config.yaml # 参数默认值
+│ └── schema.yaml # 参数类型与说明
+├── scripts/
+│ └── *.py # Python 脚本
+├── examples.md # 使用示例
+└── assets/ # 静态资源
+```
+
+### SKILL.md 格式详解
+
+`SKILL.md` 是技能的核心文件，分为 YAML 元数据区和正文两部分。
+
+**YAML 元数据（必需）**
+
+文件顶部必须有 YAML frontmatter，格式如下：
+
+```yaml
+---
+name: skill-name
+description: |
+ 一段描述，说明这个技能是做什么的、什么时候该用它。
+ 建议用第三人称书写。
+tags:
+ - tag1
+ - tag2
+---
+```
+
+| 字段 | 必填 | 说明 | 示例 |
+|------|------|------|------|
+| `name` | 是 | 技能名称，全英文、小写、单词间用连字符 | `github-repo-analyzer` |
+| `description` | 是 | 技能功能描述，建议 1-3 句话，包含使用场景 | `这个技能用于分析 GitHub 仓库并提取关键指标` |
+| `tags` | 否 | 技能标签列表，便于分类检索 | `["code", "github", "analysis"]` |
+
+**正文**
+
+元数据下方可以写 Markdown 正文，包含技能的使用说明、最佳实践、示例代码等。
+
+### 两种技能类型
+
+根据用途，技能分为两类，书写方式有所不同：
+
+**工具类技能**：用于暴露工具能力。正文应包含工具的参数说明、调用示例、返回格式、错误处理等。
+
+**智能体类技能**：用于教智能体执行复杂任务。正文应包含工作流程、领域知识、边界条件、最佳实践等。
+
+### config/schema.yaml：定义参数表单
+
+如果技能需要用户填写参数，可以创建 `config/schema.yaml` 文件。系统会根据此文件在前端自动生成参数配置表单。
+
+```yaml
+param_name:
+ type: string | number | boolean | array | object
+ required: true | false
+ default: <默认值>
+ description: "参数的英文说明"
+ description_zh: "参数的中文说明"
+```
+
+**支持的类型**：`string`、`number`、`boolean`、`array`、`object`
+
+**完整示例**：
+
+```yaml
+query:
+ type: string
+ required: true
+ description: "Search query string"
+ description_zh: "搜索关键词"
+ default: ""
+
+top_k:
+ type: number
+ required: false
+ description: "Number of results to return"
+ description_zh: "返回结果数量"
+ default: 3
+
+enable_rerank:
+ type: boolean
+ required: false
+ description: "Enable result reranking"
+ description_zh: "是否启用结果重排序"
+ default: false
+```
+
+### config/config.yaml：设置参数默认值
+
+如果希望某些参数有默认值，可以创建 `config/config.yaml`：
+
+```yaml
+# Initial workspace path
+init_path: "/mnt/nexent"
+
+# Maximum number of results
+top_k: 5
+```
+
+### 特殊标签
+
+在 SKILL.md 正文中，可以使用以下特殊标签：
+
+#### `
+ 
+
+
+After successful publishing, the system will display the A2A Agent's call information:
+
+
+
+ 
+
+
+| Field | Description |
+|-------|-------------|
+| **Endpoint ID** | Unique identifier for the A2A Agent |
+| **Agent Card URL** | Agent discovery endpoint; external systems use this address to retrieve Agent descriptions |
+| **Protocol Version** | A2A protocol version; currently 1.0 |
+| **REST Endpoints** | REST-style API endpoints |
+| **JSON-RPC Endpoint** | JSON-RPC 2.0 protocol calling endpoint |
+
+#### Calling Methods
+
+The published A2A Agent supports the following two calling protocols:
+
+##### REST API
+
+```bash
+# Get Agent Card (for Agent discovery)
+GET /nb/a2a/{endpoint_id}/.well-known/agent-card.json
+
+# Send synchronous message
+POST /nb/a2a/{endpoint_id}/message:send
+Content-Type: application/json
+
+{
+ "message": {
+ "role": "user",
+ "content": "Please help me complete a task"
+ }
+}
+
+# Send streaming message (SSE)
+POST /nb/a2a/{endpoint_id}/message:stream
+Content-Type: application/json
+
+{
+ "message": {
+ "role": "user",
+ "content": "Please help me complete a task"
+ }
+}
+
+# Get task status
+GET /nb/a2a/{endpoint_id}/tasks/{task_id}
+```
+
+##### JSON-RPC 2.0
+
+```bash
+POST /nb/a2a/{endpoint_id}/v1
+Content-Type: application/json
+
+# Send synchronous message
+{
+ "jsonrpc": "2.0",
+ "method": "SendMessage",
+ "params": {
+ "message": {
+ "role": "user",
+ "content": "Please help me complete a task"
+ }
+ },
+ "id": 1
+}
+
+# Send streaming message
+{
+ "jsonrpc": "2.0",
+ "method": "SendStreamingMessage",
+ "params": {
+ "message": {
+ "role": "user",
+ "content": "Please help me complete a task"
+ }
+ },
+ "id": 2
+}
+
+# Get task status
+{
+ "jsonrpc": "2.0",
+ "method": "GetTask",
+ "params": {
+ "taskId": "task_abc123"
+ },
+ "id": 3
+}
+```
+
+> 💡 **Tips**:
+> - For local development, replace the `/nb/a2a` prefix with `http://localhost:5013/nb/a2a`
+> - For production environments, replace the prefix with your server domain name or public IP address
+
+> ⚠️ **Notes**:
+> - Calling A2A Agents requires carrying valid authentication information in the request headers
+> - Agent Card information is cached with a refresh interval of 1 hour
+> - If you need to update Agent information, you need to republish the agent version
+
+When an agent is published as an A2A-compliant Agent, users can view the detailed A2A Agent calling information by clicking the button shown below in the agent list:
+
+
+
+ 
+
+
## 📋 Manage Agents
In the agent list on the left, you can perform the following operations on existing agents:
diff --git a/doc/docs/en/user-guide/assets/agent-development/a2a-detail.jpg b/doc/docs/en/user-guide/assets/agent-development/a2a-detail.jpg
new file mode 100644
index 000000000..399af1c56
Binary files /dev/null and b/doc/docs/en/user-guide/assets/agent-development/a2a-detail.jpg differ
diff --git a/doc/docs/en/user-guide/assets/agent-development/a2a-discovery-list.jpg b/doc/docs/en/user-guide/assets/agent-development/a2a-discovery-list.jpg
new file mode 100644
index 000000000..5c523f7b1
Binary files /dev/null and b/doc/docs/en/user-guide/assets/agent-development/a2a-discovery-list.jpg differ
diff --git a/doc/docs/en/user-guide/assets/agent-development/a2a-find-detail.jpg b/doc/docs/en/user-guide/assets/agent-development/a2a-find-detail.jpg
new file mode 100644
index 000000000..4c42104ec
Binary files /dev/null and b/doc/docs/en/user-guide/assets/agent-development/a2a-find-detail.jpg differ
diff --git a/doc/docs/en/user-guide/assets/agent-development/a2a-nacos-discovery.jpg b/doc/docs/en/user-guide/assets/agent-development/a2a-nacos-discovery.jpg
new file mode 100644
index 000000000..fdfa2e826
Binary files /dev/null and b/doc/docs/en/user-guide/assets/agent-development/a2a-nacos-discovery.jpg differ
diff --git a/doc/docs/en/user-guide/assets/agent-development/a2a-published-as.jpg b/doc/docs/en/user-guide/assets/agent-development/a2a-published-as.jpg
new file mode 100644
index 000000000..5c523f7b1
Binary files /dev/null and b/doc/docs/en/user-guide/assets/agent-development/a2a-published-as.jpg differ
diff --git a/doc/docs/en/user-guide/assets/agent-development/a2a-url-discovery.jpg b/doc/docs/en/user-guide/assets/agent-development/a2a-url-discovery.jpg
new file mode 100644
index 000000000..4632206fb
Binary files /dev/null and b/doc/docs/en/user-guide/assets/agent-development/a2a-url-discovery.jpg differ
diff --git a/doc/docs/en/user-guide/assets/agent-development/add_mcp_from_api.png b/doc/docs/en/user-guide/assets/agent-development/add_mcp_from_api.png
new file mode 100644
index 000000000..2cce2a44a
Binary files /dev/null and b/doc/docs/en/user-guide/assets/agent-development/add_mcp_from_api.png differ
diff --git a/doc/docs/en/user-guide/assets/agent-development/add_mcp_from_api_1.png b/doc/docs/en/user-guide/assets/agent-development/add_mcp_from_api_1.png
new file mode 100644
index 000000000..12e9358c5
Binary files /dev/null and b/doc/docs/en/user-guide/assets/agent-development/add_mcp_from_api_1.png differ
diff --git a/doc/docs/en/user-guide/assets/agent-development/add_mcp_from_api_2.png b/doc/docs/en/user-guide/assets/agent-development/add_mcp_from_api_2.png
new file mode 100644
index 000000000..4221b41f5
Binary files /dev/null and b/doc/docs/en/user-guide/assets/agent-development/add_mcp_from_api_2.png differ
diff --git a/doc/docs/en/user-guide/assets/agent-development/set-collaboration.jpg b/doc/docs/en/user-guide/assets/agent-development/set-collaboration.jpg
new file mode 100644
index 000000000..fdfa2e826
Binary files /dev/null and b/doc/docs/en/user-guide/assets/agent-development/set-collaboration.jpg differ
diff --git a/doc/docs/en/user-guide/assets/agent-development/set-collaboration.png b/doc/docs/en/user-guide/assets/agent-development/set-collaboration.png
deleted file mode 100644
index 7f47ba1a2..000000000
Binary files a/doc/docs/en/user-guide/assets/agent-development/set-collaboration.png and /dev/null differ
diff --git a/doc/docs/en/user-guide/knowledge-base.md b/doc/docs/en/user-guide/knowledge-base.md
index e5e5714ff..05456e5fa 100644
--- a/doc/docs/en/user-guide/knowledge-base.md
+++ b/doc/docs/en/user-guide/knowledge-base.md
@@ -26,12 +26,14 @@ Create and manage knowledge bases, upload documents, and generate summaries. Kno
### Supported File Formats
Nexent supports multiple file formats, including:
-- **Text:** .txt, .md
+- **Text:** .txt, .md, .csv, .json
- **PDF:** .pdf
- **Word:** .docx
- **PowerPoint:** .pptx
+- **EPUB:** .epub
- **Excel:** .xlsx
- **Data files:** .csv
+- **Web content:** .html, .xml
## 📊 Knowledge Base Summary
diff --git a/doc/docs/en/user-guide/skills.md b/doc/docs/en/user-guide/skills.md
new file mode 100644
index 000000000..0cdc2a288
--- /dev/null
+++ b/doc/docs/en/user-guide/skills.md
@@ -0,0 +1,572 @@
+---
+title: Skill Management
+---
+
+# Skill Management
+
+A Skill is a core mechanism in Nexent for extending agent capabilities. Each skill packages multiple tools with usage documentation into a reusable unit of capability, enabling agents to handle complex tasks like assembling building blocks — without consuming excessive context space.
+
+## Table of Contents
+
+- [Skills vs. Tools](#-skills-vs-tools): Understanding the core concepts
+- [Using Skills](#-using-skills): How to use skills in agent development
+- [Skill Management](#-skill-management): Create, edit, import, and export skills
+- [Skill Upload Guide](#-skill-upload-guide): SKILL.md format, ZIP structure, special tags, and writing standards
+- [NL-to-Skill](#-nl-to-skill): Automatically generate skills from natural language descriptions
+- [Official Skills Overview](#-official-skills-overview): Built-in skills and their capabilities
+
+## The Relationship Between Skills and Tools
+
+In Nexent, **Tools** and **Skills** are two distinct layers. Understanding their differences helps you configure agent capabilities more effectively.
+
+A **Tool** is a single atomic operation the agent can call, such as `read_file` or `tavily_search`. When a tool is enabled for an agent, the LLM searches through the tool list on every turn — meaning even if a tool is completely unnecessary for the current conversation, the LLM still consumes context tokens to "see" it.
+
+A **Skill** bundles the capabilities of multiple tools into a complete workflow, complete with parameter configuration and usage documentation via `SKILL.md`. The LLM does not need to "see" all tools in advance. Based on the user's actual needs, it decides whether to activate a skill. Only when activated does the system load the corresponding toolset — effectively saving Token consumption.
+
+| Dimension | Tool | Skill |
+|-----------|------|-------|
+| Granularity | Single atomic operation | Bundle of multiple tools + configuration + documentation |
+| Token consumption | Occupies context on every turn | Loaded only when activated |
+| Parameters | Fixed parameter schema | Customizable parameter templates |
+| Versioning | No version management | Supports draft/published versions |
+| Distribution | Code-level | ZIP package distribution, plug-and-play |
+
+**Analogy**: Tools are individual items like a screwdriver, hammer, or saw. A Skill is a toolbox — with tools pre-matched for a work scenario and accompanied by usage instructions. Open the right toolbox for the task at hand.
+
+## Using Skills
+
+### Configuring Skills for an Agent
+
+1. Open the **[Agent Development](./agent-development)** page
+2. On the "Select Tools" tab, find the **Skills** group
+3. Click a skill name to select it; click again to deselect
+4. After selecting a skill, click the ⚙️ button next to it to configure skill parameters
+5. Save the agent configuration
+
+
+
+ 
+
+
+> 💡 **Tip**: If a skill has required parameters that are not configured, a guided parameter-filling prompt will appear upon selection.
+
+### Skill Parameters
+
+Each skill's parameter definitions come from the `config/schema.yaml` file in the skill package. The configuration interface auto-generates a parameter form based on the schema, including:
+
+- **Parameter name and description** (bilingual: English and Chinese)
+- **Required/optional markers**
+- **Default values**
+- **Parameter types** (string, number, boolean, array, object)
+- **YAML comment auto-mapped tooltips**
+
+### Skill Versions
+
+Each skill supports multi-version management:
+
+- **Draft version (version=0)**: Development and debugging stage; changes take effect immediately
+- **Published version (version>=1)**: Production use; parameters are locked
+
+When configuring the same skill for different agents, you can set different parameter values independently.
+
+## Skill Management
+
+### Viewing Installed Skills
+
+The "Select Tools" skill group displays all installed skills, including:
+- Official skills (`official` source)
+- Custom skills (`custom` source)
+
+### Creating Custom Skills
+
+Nexent supports two ways to create custom skills: uploading a skill package file, or generating one automatically from a natural language description.
+
+#### Method 1: Upload SKILL.md or ZIP
+
+1. Go to the skill configuration interface
+2. Click the "Upload Skill" button
+3. Select a `SKILL.md` file (single file) or a `.zip` package (complete skill package)
+4. The system automatically parses and creates the skill
+
+#### Method 2: NL-to-Skill Natural Language Creation
+
+Click the **"NL Create Skill"** button on the skill management page. See the [NL-to-Skill](#-nl-to-skill) section below for details.
+
+### Editing Skills
+
+1. Find the target skill in the skill list
+2. Click the skill card to enter the edit page
+3. Modify the skill name, description, tags, parameter configuration, etc.
+4. Save changes
+
+### Importing/Exporting Skills
+
+- **Export**: Click "Export" on the skill detail page to download as a JSON configuration file
+- **Import**: Click "Import Skill" on the Agent Development page to upload a JSON configuration file
+
+> ⚠️ **Note**: When importing skills containing knowledge base tools (such as `knowledge_base_search`), these tools will only search **knowledge bases that the currently logged-in user is permitted to access in this environment**. The original skill's knowledge base configuration will not be automatically inherited.
+
+## Skill Upload Guide
+
+### Skill Package Structure
+
+A skill can be a single file or a ZIP package containing multiple files:
+
+```
+skill-name/
+├── SKILL.md # Skill definition file (required)
+├── config/
+│ ├── config.yaml # Default parameter values
+│ └── schema.yaml # Parameter types and descriptions
+├── scripts/
+│ └── *.py # Python scripts
+├── examples.md # Usage examples
+└── assets/ # Static assets
+```
+
+### SKILL.md Format in Detail
+
+`SKILL.md` is the core file of a skill, consisting of a YAML frontmatter section and a body section.
+
+**YAML Frontmatter (required)**
+
+The file must start with YAML frontmatter:
+
+```yaml
+---
+name: skill-name
+description: |
+ A description of what this skill does and when to use it.
+ Write in third person.
+tags:
+ - tag1
+ - tag2
+---
+```
+
+| Field | Required | Description | Example |
+|-------|----------|-------------|---------|
+| `name` | Yes | Skill name; English only, lowercase, hyphenated | `github-repo-analyzer` |
+| `description` | Yes | Skill function description; 1-3 sentences, include use case | `This skill analyzes GitHub repositories and extracts key metrics` |
+| `tags` | No | Skill tag list for categorization and search | `["code", "github", "analysis"]` |
+| `allowed-tools` | No | List of allowed tools (all available by default) | `[file_read, web_search]` |
+| `always` | No | Whether to auto-activate on every turn (default: false) | `false` |
+
+**Body (optional)**
+
+Below the frontmatter, you can write Markdown content including usage instructions, best practices, example code, and more.
+
+### Two Skill Types
+
+Based on their purpose, skills fall into two categories with different writing styles:
+
+**Tool Skills**: Used to expose tool capabilities. The body should include tool parameter descriptions, usage examples, return formats, and error handling.
+
+**Agent Skills**: Used to teach the agent how to perform a complex task. The body should include workflow instructions, domain knowledge, boundary conditions, and best practices.
+
+### config/schema.yaml: Defining Parameter Forms
+
+If a skill requires user-supplied parameters, create a `config/schema.yaml` file. The system will auto-generate a parameter configuration form in the frontend based on this file.
+
+```yaml
+param_name:
+ type: string | number | boolean | array | object
+ required: true | false
+ default:
+`: Displaying Executable Code Examples
+
+Use the `` tag to wrap executable code examples (usually Python code):
+
+```markdown
+
+result = run_skill_script(
+ "code-reviewer",
+ "scripts/analyze.py",
+ {"--target": "/path/to/file.py", "--verbose": True}
+)
+print(result)
+
+```
+
+### Helper Functions
+
+In agent skill bodies and examples, you can use the following functions:
+
+**`run_skill_script(skill_name, script_path, params)`**: Execute a script bundled in the skill package
+
+```python
+# Execute a Python script
+result = run_skill_script(
+ "code-reviewer",
+ "scripts/analyze.py",
+ {"--target": "/path/to/file.py"}
+)
+
+# Execute a Shell script
+result = run_skill_script(
+ "database-migration",
+ "scripts/migrate.sh",
+ {"--direction": "up", "--steps": 1}
+)
+```
+
+**`read_skill_md(skill_name, files)`**: Read files from the skill package
+
+```python
+# By default, only reads SKILL.md (referenced files are not auto-included)
+content = read_skill_md("my-skill")
+
+# Explicitly specify which files to read
+full_content = read_skill_md("my-skill", [
+ "SKILL.md",
+ "reference/api-reference.md"
+])
+```
+
+### Writing Standards and Best Practices
+
+**SKILL.md Writing Standards**:
+
+1. **Be specific**: Explain when to use the skill, not just what it does
+ - ✓ "Used when you need to analyze GitHub repository popularity metrics"
+ - ✗ "GitHub search function"
+
+2. **Avoid time-sensitive information**: Do not include specific dates, version numbers, or other content that will become outdated
+
+3. **Stay concise**: Keep the `SKILL.md` body under 500 lines. Use `` for complex content that can be lazy-loaded
+
+4. **Path format**: Always use forward slashes `/`, even on Windows
+ - ✓ `src/services/payment_service.py`
+ - ✗ `src\services\payment_service.py`
+
+5. **Consistent parameter naming**: Use the same terminology and naming style throughout
+
+6. **Include boundary conditions**: Explain the skill's scope and limitations
+
+**Parameter Description Best Practices**:
+
+```yaml
+# ✓ Good: Clearly specify purpose and format
+query:
+ type: string
+ required: true
+ description: "GitHub repository owner/name or full URL"
+ description_zh: "GitHub repository in owner/name format or full URL"
+
+# ✗ Bad: Too vague
+query:
+ type: string
+ required: true
+ description: "Search query"
+ description_zh: "Query"
+```
+
+**Code Example Best Practices**:
+
+- Provide at least 2 different-scenario examples for each tool
+- Include common parameter combinations in examples
+- Demonstrate both successful calls and common error handling
+
+### Learning from Existing Skills
+
+The system includes several complete skill reference examples in `test_skill_examples/official-skills/`:
+
+| Skill Name | Reference Value |
+|-----------|-----------------|
+| `create-file-directory` | Standard writing for tool skills, with complete parameter tables, usage examples, and error handling tables |
+| `search-knowledge-base` | Parameter configuration for search skills, with complete `schema.yaml` and `config.yaml` examples |
+| `analyze-image` | Multimodal tool example with `` call format |
+| `code_review_expert` | Agent skill reference with bundled scripts and `` tag usage |
+
+### FAQ
+
+**Q: Upload reports "SKILL.md not found"**
+
+Make sure the `SKILL.md` file is in the ZIP package's root directory, not inside a subfolder.
+
+**Q: Parameter form didn't generate correctly**
+
+Check that `config/schema.yaml` is formatted correctly. Ensure each field has both `type` and `description` fields.
+
+**Q: Skill description isn't taking effect**
+
+The skill description should be written in the YAML frontmatter's `description` field, not in the Markdown body section. Body content is not parsed as the skill description.
+
+## NL-to-Skill
+
+NL-to-Skill is an intelligent creation feature provided by Nexent. You simply describe a skill requirement in natural language, and the system automatically generates a complete skill package — including skill definition, parameter configuration, and even accompanying script code. The entire generation process is visible in real time, as if an AI assistant is writing code for you.
+
+In simple terms:
+
+> You say "I want a skill that can search GitHub repositories and extract Star counts," and the system automatically generates a complete, usable skill for you.
+
+### Quick Start
+
+#### Step 1: Describe Your Requirement
+
+In the input box, describe the skill you want in natural language. The clearer your description, the better the generated result.
+
+**Good examples**:
+- "Create a skill that searches GitHub repositories by keywords and returns Star counts, descriptions, and links"
+- "Create a skill that reads an Excel file, calculates statistics for each column, and generates a chart"
+- "Create a skill that extracts order numbers, amounts, and dates from emails and compiles them into a table"
+
+**Bad examples**:
+- "Help me make a chat skill" (too vague)
+- "Search tool" (lacks specific capability description)
+
+#### Step 2: Watch the Generation Process
+
+After clicking "Generate," the page displays the AI's thinking and writing process in real time:
+- See the AI analyzing your requirement
+- See it writing the skill definition file
+- See it planning the parameter structure
+
+This process is like watching AI write code live. You can click "Stop" at any time to interrupt.
+
+#### Step 3: Preview and Save
+
+After generation completes, the system displays the complete skill content:
+- Skill name and description
+- Parameter list (what each parameter is, whether required)
+- Usage examples
+
+Check the preview carefully:
+- To make adjustments, click "Edit" to fine-tune
+- If it meets your expectations, click "Save" to add the skill to your skill library
+
+### Writing Tips
+
+#### How to Write a Good Skill Description
+
+**1. Clarify inputs and outputs**
+
+Tell the system what information the skill needs and what it will return.
+
+```
+✓ "Input a GitHub repository address; return the repository name, Star count, Fork count, and last update time"
+✗ "Search GitHub" (too vague)
+```
+
+**2. Explain the use case**
+
+Help the AI understand in what situations this skill would be used.
+
+```
+✓ "Used to quickly query the popularity of open-source projects and assist with technical selection decisions"
+✗ "Get data" (no context)
+```
+
+**3. Describe boundary conditions**
+
+If there are special processing logic or limitations, mention them.
+
+```
+✓ "If the repository doesn't exist, return a friendly message instead of an error"
+✓ "Skip invalid image URLs and log them"
+```
+
+**4. Explicitly request examples**
+
+If the skill has complex usage scenarios with high accuracy requirements, explicitly request detailed examples.
+
+```
+✓ "Generate comprehensive and detailed usage examples"
+```
+
+#### Usage Scenario Examples
+
+| Scenario | Description Example |
+|---------|-------------------|
+| **Data collection** | "Search Zhihu for Q&A related to the keywords and extract summaries of the highest-liked answers" |
+| **File processing** | "Upload a CSV file; automatically calculate statistics for each column and generate a line chart" |
+| **API encapsulation** | "Create a skill that calls a weather API and returns a three-day forecast" |
+| **Multi-tool combination** | "Input a product link; automatically compare prices (calling multiple e-commerce searches) and return the lowest-price link" |
+| **Data cleaning** | "Read a messy text block; extract emails, phone numbers, and dates, and format the output" |
+
+### What You Can Do During Generation
+
+#### Real-time Preview
+
+During generation, skill content progressively appears in the preview area:
+- `SKILL.md` content: skill definition, description, tags
+- `examples.md`: skill usage examples
+- `scripts/*.py`: tool scripts (in complex mode)
+
+#### Stop Anytime
+
+If the generation direction deviates from expectations:
+- Click the "Stop" button; the AI immediately stops
+- Existing generated results are preserved; you can review or discard them
+
+#### Multiple Attempts
+
+If the first generation result is unsatisfactory:
+- Directly add more requirement details; modify based on the existing result
+- Or manually adjust in the preview
+- If you want to start completely fresh, click the "trash" icon in the upper right corner to clear all skill content
+
+### Limitations and Notes
+
+#### Model Capability Affects Quality
+
+NL-to-Skill uses the LLM model configured for your tenant to generate skills. The model's capability directly determines the generation quality:
+- Smarter models accurately understand requirements and generate well-structured, easy-to-understand skills
+- Weaker models may produce incomplete or misleading content, affecting agent efficiency and accuracy
+
+If the generation result is unsatisfactory, try:
+1. Simplify the requirement description
+2. Switch to a smarter, more capable model
+3. Create in steps (make a simple version first, then manually expand)
+
+#### Token Consumption
+
+Complex skill generation consumes more tokens:
+- **Simple mode**: Usually consumes less; suitable for quick validation
+- **Complex mode**: Consumes more; suitable for formally creating complete skills
+
+It is recommended to first test the idea in simple mode, then use complex mode for formal creation after confirming feasibility.
+
+#### Not All Requirements Can Be Realized
+
+NL-to-Skill excels at generating skills for:
+- Single tool wrapping (e.g., encapsulating a search capability)
+- Simple multi-tool chaining (e.g., search → read → summarize)
+- Common data processing flows (e.g., file format conversion, data extraction)
+
+The following types of skills may be beyond its capabilities:
+- Requiring external APIs that are not integrated
+- Involving complex state management or concurrency logic
+- Requiring access to underlying platform interfaces that are not open
+
+When encountering requirements that cannot be fulfilled, the system will provide a prompt. You can consider creating manually or contacting technical support.
+
+#### Modifying Skills
+
+In the NL-to-Skill interface, you can select an existing skill. After selecting, the skill information loads automatically. You can then use natural language to attempt updating the skill in the left dialog.
+
+If the skill name you create conflicts with an existing skill, Nexent will automatically switch from skill creation mode to skill update mode. All content will overwrite the original skill.
+
+## Official Skills Overview
+
+### File Operations
+
+| Skill Name | Description | Main Tools |
+|-----------|-------------|------------|
+| `read-file` | Read file content and metadata within the workspace | `read_file` |
+| `create-file-directory` | Create files or directories | `create_file`, `create_directory` |
+| `delete-file-directory` | Delete files or directories (irreversible) | `delete_file`, `delete_directory` |
+| `move-file-directory` | Move or rename files/directories | `move_item` |
+| `list-directory` | List directory structure in a tree view | `list_directory` |
+
+### Knowledge Base Search
+
+| Skill Name | Description | Main Tools |
+|-----------|-------------|------------|
+| `search-knowledge-base` | Local knowledge base semantic search | `knowledge_base_search` |
+| `search-dify` | Dify knowledge base search (supports semantic / keyword / full_text / hybrid modes) | `dify_search` |
+| `search-idata` | iData knowledge base search | `idata_search` |
+| `search-datamate` | DataMate knowledge base search (with similarity threshold control) | `datamate_search` |
+
+### Web Search
+
+| Skill Name | Description | Main Tools |
+|-----------|-------------|------------|
+| `search-web-tavily` | Tavily real-time web search | `tavily_search` |
+| `search-web-linkup` | Linkup image and text mixed search | `linkup_search` |
+| `search-web-exa` | Exa deep web search | `exa_search` |
+
+### Multimodal Analysis
+
+| Skill Name | Description | Main Tools |
+|-----------|-------------|------------|
+| `analyze-image` | VLM-based image content analysis and Q&A | `analyze_image` |
+| `analyze-text-file` | PDF/Word/Excel file content extraction and Q&A | `analyze_text_file` |
+
+### Communication and Remote Operations
+
+| Skill Name | Description | Main Tools |
+|-----------|-------------|------------|
+| `email-utils` | IMAP receive / SMTP send (supports HTML / CC / BCC) | `get_email`, `send_email` |
+| `run-shell-ssh` | Persistent SSH session for remote command execution | `terminal` |
+
+## Security and Best Practices
+
+- **Knowledge base access control**: When importing skills containing knowledge base tools, actual search scope is limited by the current user's permissions
+- **Web search**: Tavily / Linkup / Exa web search requires the corresponding API Key to be configured in the platform security settings first
+- **Path security**: File operations within skill packages are limited to the skill directory scope and cannot access arbitrary system paths
+- **Irreversible operations**: Delete and move operations are irreversible; confirm the target before executing
+- **NL-to-Skill Token consumption**: Complex skill generation consumes more model tokens; it is recommended to test in simple mode first
+
+## Related References
+
+- [Agent Development](./agent-development)
+- [Local Tools Overview](./local-tools/index)
+- [MCP Tool Configuration](./mcp-tools)
+- [Skills System Overview](../backend/skills/overview)
diff --git a/doc/docs/en/user-guide/start-chat.md b/doc/docs/en/user-guide/start-chat.md
index 9593cb6ec..5834521ea 100644
--- a/doc/docs/en/user-guide/start-chat.md
+++ b/doc/docs/en/user-guide/start-chat.md
@@ -79,8 +79,8 @@ You can upload files during a chat so the agent can reason over their content:
- Or drag files directly into the chat area
2. **Supported File Formats**
- - **Documents:** PDF, Word (.docx), PowerPoint (.pptx), Excel (.xlsx)
- - **Text:** Markdown (.md), Plain text (.txt)
+ - **Documents:** PDF, Word (.docx), PowerPoint (.pptx), Excel (.xlsx), EPUB (.epub), HTML (.html), XML (.xml)
+ - **Text & Data:** Markdown (.md), Plain text (.txt), JSON (.json), CSV (.csv)
- **Images:** JPG, PNG, GIF, and other common formats
3. **File Processing Flow**
diff --git a/doc/docs/zh/backend/skills/index.md b/doc/docs/zh/backend/skills/index.md
new file mode 100644
index 000000000..10b37bc90
--- /dev/null
+++ b/doc/docs/zh/backend/skills/index.md
@@ -0,0 +1,37 @@
+# 后端技能（Skill）文档
+
+本节介绍 Nexent 后端基础设施中 Skills 技能系统的完整生态，包括技能定义、技能包结构与系统架构。
+
+## 可用文档
+
+### 概览与架构
+- [技能系统概览](./overview)：技能类型、生命周期与版本管理
+
+## 技能与工具的关系
+
+在 Nexent 中，**工具（Tool）** 与 **技能（Skill）** 是两个不同层次的概念：
+
+- **工具**：智能体可调用的单个原子操作。启用后，LLM 的每次思考都会在工具列表中搜索——即使本次对话完全不需要某个工具，LLM 仍然会消耗上下文额度。
+- **技能**：通过 `SKILL.md` 将多个工具的能力组合为一个完整的工作流，并附带参数配置与使用文档。LLM 根据用户实际需求自行判断是否激活技能，激活后才加载对应工具集——有效节省 Token 消耗。
+
+## 快速开始
+
+1. **了解能力**：阅读 [技能系统概览](./overview) 了解已支持的技能类型
+2. **体验创建**：在 [技能管理](../../user-guide/skills) 页面体验 NL-to-Skill 创建
+3. **手动创建**：上传 `SKILL.md` 或 ZIP 包创建自定义技能
+4. **为智能体配置**：在智能体工具配置中勾选技能
+
+## 相关参考
+
+- [技能管理（用户指南）](../../user-guide/skills)
+- [智能体开发指南](../../user-guide/agent-development)
+- [本地工具概览](../../user-guide/local-tools/index)
+- [SDK 工具开发规范](../../sdk/core/tools)
+- [MCP 工具开发](../tools/mcp)
+- [常见问题](../../quick-start/faq)
+
+## 获取帮助
+
+- 查看 [常见问题](../../quick-start/faq) 了解常见技能使用问题
+- 在 [GitHub Discussions](https://github.com/ModelEngine-Group/nexent/discussions) 中提问
+- 查看 [GitHub Issues](https://github.com/ModelEngine-Group/nexent/issues) 了解已知问题
diff --git a/doc/docs/zh/backend/skills/overview.md b/doc/docs/zh/backend/skills/overview.md
new file mode 100644
index 000000000..f3d866f78
--- /dev/null
+++ b/doc/docs/zh/backend/skills/overview.md
@@ -0,0 +1,138 @@
+# 技能系统概览
+
+技能（Skill）是 Nexent 为智能体扩展能力的方式。每个技能由以下部分组成：
+
+- **技能描述**：这个技能是做什么的、什么时候该用它
+- **工具组合**：一个或多个 nexent sdk方法或用户自定义工具的打包
+- **参数模板**：用户可为技能填写哪些参数
+- **使用示例**：这个技能通常怎么用
+
+与直接选择一个一个工具相比，技能让复杂能力的配置变得简单——只需安装一个技能包，无需分别配置每个工具。
+
+## 技能包结构
+
+技能包可以是单个 `SKILL.md` 文件，也可以是包含多个文件的 ZIP 包：
+
+```
+skill-name/
+├── SKILL.md # 技能定义文件（必需）
+├── config/
+│ ├── config.yaml # 参数默认值（可选）
+│ └── schema.yaml # 参数类型与说明（可选）
+├── scripts/
+│ └── *.py # Python 脚本（可选）
+├── examples.md # 使用示例（可选）
+└── assets/ # 静态资源（可选）
+```
+
+### SKILL.md 的结构
+
+每个技能必须有一个 `SKILL.md` 文件，分为两部分：
+
+**第一部分：YAML 元数据（必须）**
+
+```yaml
+---
+name: skill-name
+description: |
+ 一段描述，说明这个技能是做什么的、什么时候该用它。
+ 建议用第三人称书写，如："这个技能用于..."
+tags:
+ - tag1
+ - tag2
+---
+```
+
+**第二部分：技能正文**
+
+元数据下方可以继续写 Markdown 内容，包括：
+- 技能的详细说明与使用指南
+- 工具调用方式的示例代码
+- 错误处理说明
+- 使用限制与注意事项
+
+### 两种技能类型
+
+根据用途，技能分为两类：
+
+**工具类技能**：用于暴露一个或多个 Nexent sdk方法的能力，包含工具的参数说明、调用示例、返回格式、错误处理等。用户配置好参数后，智能体即可调用这些工具。
+
+**智能体类技能**：用于教智能体如何执行一个复杂任务，包含工作流程说明、领域知识、最佳实践，有时附带辅助脚本。这类技能的正文会包含详细的步骤指引。
+
+## 官方技能一览
+
+### 文件操作类
+
+| 技能名称 | 能力说明 |
+|---------|---------|
+| `read-file` | 读取工作空间内文件内容与元信息 |
+| `create-file-directory` | 创建文件或目录 |
+| `delete-file-directory` | 删除文件或目录 |
+| `move-file-directory` | 移动或重命名文件/目录 |
+| `list-directory` | 树形列出目录结构 |
+
+### 知识库搜索类
+
+| 技能名称 | 能力说明 |
+|---------|---------|
+| `search-knowledge-base` | 本地知识库语义检索（支持 hybrid / accurate / semantic 模式） |
+| `search-dify` | Dify 知识库检索 |
+| `search-idata` | iData 知识库检索 |
+| `search-datamate` | DataMate 知识库检索（支持相似度阈值控制） |
+
+### 公网搜索类
+
+| 技能名称 | 能力说明 |
+|---------|---------|
+| `search-web-tavily` | Tavily 公网实时搜索 |
+| `search-web-linkup` | Linkup 图文混合搜索 |
+| `search-web-exa` | Exa 深度网页搜索 |
+
+### 多模态分析类
+
+| 技能名称 | 能力说明 |
+|---------|---------|
+| `analyze-image` | 基于 VLM 的图片内容分析问答 |
+| `analyze-text-file` | PDF/Word/Excel 等文件内容提取与问答 |
+
+### 通信与远程操作类
+
+| 技能名称 | 能力说明 |
+|---------|---------|
+| `email-utils` | IMAP 收件 / SMTP 发件（支持 HTML / CC / BCC） |
+| `run-shell-ssh` | 持久化 SSH 会话远程执行命令 |
+
+## 技能生命周期
+
+### 版本管理
+
+每个技能支持两个版本状态：
+
+- **草稿版本（version=0）**：开发调试阶段，修改即时生效，适合反复调整
+- **已发布版本（version>=1）**：正式使用，参数锁定，防止误改
+
+### 技能实例
+
+同一个技能可以为不同的智能体配置不同的参数值，互不影响。
+
+例如，搜索技能可以为"技术文档 Agent"配置只搜索技术知识库，为"客服 Agent"配置只搜索客服知识库。
+
+### 常见操作流程
+
+```
+创建技能 → 配置参数 → 为智能体选择技能 → 调试 → 发布
+ ↓
+ 修改草稿版本
+```
+
+## 安全说明
+
+- **路径隔离**：技能包内文件仅能在技能目录范围内访问
+- **参数校验**：schema.yaml 中定义的参数均经过前端表单校验
+- **权限控制**：技能实例按租户隔离，API 需携带认证 Token
+
+## 相关参考
+
+- [技能管理（用户指南）](../../user-guide/skills)
+- [智能体开发指南](../../user-guide/agent-development)
+- [本地工具概览](../../user-guide/local-tools/index)
diff --git a/doc/docs/zh/backend/tools/index.md b/doc/docs/zh/backend/tools/index.md
index 94e1fe36e..88560fdcf 100644
--- a/doc/docs/zh/backend/tools/index.md
+++ b/doc/docs/zh/backend/tools/index.md
@@ -12,6 +12,10 @@
模型上下文协议工具，用于标准化 AI 智能体通信。
→ [MCP 工具开发](./mcp)
+### Skills 技能系统
+通过自然语言或 ZIP 包创建可复用的技能包，为智能体赋予更加灵活的工具调用能力。
+→ [Skills 技能文档](../skills/index)
+
## 快速开始
1. **选择工具类型**: LangChain 用于通用 AI 工作流，MCP 用于标准化智能体通信
@@ -28,4 +32,4 @@
- 查看我们的 [常见问题](../../quick-start/faq) 了解常见工具集成问题
- 加入我们的 [Discord 社区](https://discord.gg/tb5H3S3wyv) 获取实时支持
-- 查看 [GitHub Issues](https://github.com/ModelEngine-Group/nexent/issues) 了解已知问题
\ No newline at end of file
+- 查看 [GitHub Issues](https://github.com/ModelEngine-Group/nexent/issues) 了解已知问题
diff --git a/doc/docs/zh/getting-started/features.md b/doc/docs/zh/getting-started/features.md
index 15db67357..658a89e18 100644
--- a/doc/docs/zh/getting-started/features.md
+++ b/doc/docs/zh/getting-started/features.md
@@ -25,7 +25,7 @@ Nexent 支持 **Agent-to-Agent（A2A）** 通信协议，让多个智能体能
## 📝 Skill 渐进式披露
-Nexent 引入了 **渐进式 Skill 披露**机制。当用户输入任务时，系统会根据当前上下文动态揭示最相关的 Skill 建议，帮助用户快速找到适合当前任务的工具和方法。这一机制让新用户能够渐进式地探索系统能力，同时不增加高级用户的操作复杂度。
+Nexent 引入了 **渐进式 Skill 披露**机制。当用户输入任务时，系统会根据当前上下文动态揭示最相关的 Skill 建议，帮助用户快速找到适合当前任务的工具和方法。这一机制能够防止上下文爆炸，高效利用上下文窗口。
## 🗄️ 个人级知识库
diff --git a/doc/docs/zh/sdk/data-process.md b/doc/docs/zh/sdk/data-process.md
index a887c8442..1f1c27fde 100644
--- a/doc/docs/zh/sdk/data-process.md
+++ b/doc/docs/zh/sdk/data-process.md
@@ -98,6 +98,9 @@ def file_process(self,
- `.odt` - OpenDocument文本
- `.pptx` - PowerPoint 2007及更高版本
- `.ppt` - PowerPoint 97-2003版本
+- `.xml` - XML数据文件
+- `.json` - JSON数据文件
+- `.csv` - 逗号分隔值文件
## 💡 使用示例
diff --git a/doc/docs/zh/user-guide/agent-development.md b/doc/docs/zh/user-guide/agent-development.md
index 67d3c8311..a8cca4a33 100644
--- a/doc/docs/zh/user-guide/agent-development.md
+++ b/doc/docs/zh/user-guide/agent-development.md
@@ -31,15 +31,88 @@
### 🤝 协作 Agent
+协作智能体用于帮助当前智能体完成复杂任务。协作智能体的来源分为两类：
+
+- **内部 Agent**：平台已发布的智能体
+- **外部 A2A Agent**：通过 A2A 协议发现的第三方 Agent
+
1. 点击"协作 Agent"页签下的加号，弹出可选择的智能体列表
-2. 在下拉列表中选择要添加的智能体
-3. 允许选择多个协作智能体
-4. 可点击 × 取消选择此智能体
+2. 智能体列表分为"内部 Agent"和"外部 A2A Agent"两个页签，您可以根据需要选择
+3. 在下拉列表中选择要添加的智能体
+4. 允许选择多个协作智能体
+5. 可点击 × 取消选择此智能体
+
+
+
+
+
+#### 🌐 添加外部 A2A Agent
+
+Nexent 支持通过 A2A 协议与第三方 Agent 进行通信。您可以通过以下两种方式发现外部 A2A Agent：
+
+##### 通过 URL 发现 Agent
+
+如果您知道目标 Agent 的 Agent Card 地址，可以使用 URL 发现方式：
+
+
+
+
+
+1. 在外部 A2A Agent 列表中，点击"添加外部 Agent"按钮
+2. 选择"URL 发现"页签
+3. 填写 Agent Card URL 地址，例如：`https://example.com/.well-known/agent.json`
+4. 点击"发现"按钮，系统会自动获取 Agent 的相关信息
+5. 发现成功后，可以查看 Agent 的名称、描述、能力等信息
+6. 点击"添加到列表"完成添加
+
+> 💡 **提示**：Agent Card 是符合 A2A 1.0 规范的 Agent 描述文件，包含了 Agent 的名称、描述、调用地址、能力等信息。
+
+##### 通过 Nacos 发现 Agent
+
+如果您的 Agent 注册在 Nacos 服务发现平台，可以使用 Nacos 发现方式：
-
+
+1. 在外部 A2A Agent 列表中，点击"添加外部 Agent"按钮
+2. 选择"Nacos 发现"页签
+3. 首次使用时，需要先配置 Nacos 连接信息：
+ - **Nacos 服务器地址**：填写 Nacos 服务器地址，如 `http://127.0.0.1:8848`
+ - **命名空间 ID**：填写 Nacos 命名空间 ID（可选）
+ - **分组名**：填写服务分组名，默认为 `DEFAULT_GROUP`
+ - **用户名/密码**：填写 Nacos 访问凭证（可选）
+4. 点击"保存配置"保存 Nacos 连接信息
+5. 填写要扫描的 Agent 服务名称
+6. 点击"扫描"按钮，系统会从 Nacos 中获取匹配的 Agent 信息
+7. 扫描结果会列出所有匹配的 Agent，可以选择需要的 Agent 添加到列表
+
+> ⚠️ **注意**：确保 Nacos 服务正常运行，且目标 Agent 已正确注册到 Nacos。
+
+##### 管理已发现的外部 Agent
+
+在外部 A2A Agent 列表中，您可以查看和管理所有已发现的外部 Agent：
+
+
+
+
+
+
+
+1. **查看 Agent 详情**：点击 Agent 卡片，可以查看其完整信息，包括名称、描述、URL、能力列表等
+2. **测试 Agent**：点击"测试"按钮，可以向该 Agent 发送测试消息，验证其是否正常工作
+3. **与 Agent 对话**：点击"对话"按钮，可以打开对话窗口，与该 Agent 进行实时交互
+4. **配置调用协议**：点击"协议配置"按钮，可以选择该 Agent 的调用协议：
+ - **HTTP + JSON**：使用 REST API 风格调用
+ - **JSON-RPC**：使用 JSON-RPC 协议调用
+5. **刷新 Agent 信息**：如果 Agent 信息发生变化，可以点击"刷新"按钮重新获取最新的 Agent Card
+6. **移除 Agent**：点击"移除"按钮，可以将该 Agent 从已发现列表中删除
+
+> 💡 **使用场景**：
+> - 通过 URL 发现快速接入已知的第三方 Agent 服务
+> - 通过 Nacos 发现批量接入同一服务注册中心的所有 Agent
+> - 配置协议以兼容不同 Agent 服务提供商的要求
+
### 🛠️ 选择智能体的工具
智能体可以使用各种工具来完成任务，如知识库检索、文件解析、图片解析、收发邮件、文件管理等本地工具，也可接入第三方 MCP 工具，或自定义工具。
@@ -60,7 +133,10 @@
> 2. 请选择 `analyze_text_file` 工具，启用文档类、文本类文件的解析功能。
> 3. 请选择 `analyze_image` 工具，启用图片类文件的解析功能。
>
+> ⚠️ **向量化模型配置**：使用 `knowledge_base_search` 工具时，需要确保知识库已配置向量化模型。对于存量知识库，系统会提示选择向量化模型，请务必选择**创建该知识库时使用的向量化模型**。若选择的模型与知识库创建时使用的模型不一致，可能导致检索失败或结果不准确。
+>
> 📚 想了解系统已经内置的所有本地工具能力？请参阅 [本地工具概览](./local-tools/index.md)。
+> 📚 想了解技能能力？请参阅 [技能管理](./skills.md)。
### 🔌 添加 MCP 工具
@@ -108,6 +184,40 @@
有许多第三方服务如 [ModelScope](https://www.modelscope.cn/mcp) 提供了 MCP 服务，您可以快速接入使用。
您也可以自行开发 MCP 服务并接入 Nexent 使用，参考文档 [MCP 工具开发](../backend/tools/mcp)。
+**3️⃣ 存量 API 转换为 MCP 服务**
+
+🔔 该方法适用于将已有的 REST API 接口快速转换为 MCP 工具，无需额外开发即可让智能体调用现有 API 能力：
+
+>1. 在 MCP 配置模块选择 **"API 转换为 MCP"** 接入类型
+>
+>2. 在下方的输入框中填写 API 基础信息：
+> - **服务名称**：MCP 服务的展示名称
+> - **OpenAPI JSON**：OpenAPI 3.x 规范的 JSON 内容
+> - **基础服务 URL**：API 服务的基础地址（支持 http/https）
+>
+>3. 点击右下角 **+ 添加** 按钮，完成对应 MCP 服务的转换
+
+
+
+
+
+>
+>4. 转换完成后，可在 **Outer APIs** 页签下查看所有外部 API 转换的 MCP 工具
+
+
+
+
+
+
+
+
+
+>💡 **使用场景**：
+>- 快速接入企业内部的 REST API 接口
+>- 将第三方服务的 HTTP API 转换为 MCP 工具
+>- 无需编写 MCP Server 代码，直接通过 OpenAPI 规范生成工具
+
+
### ⚙️ 自定义工具
您可参考以下指导文档，开发自己的工具，并接入 Nexent 使用，丰富智能体能力。
@@ -129,8 +239,8 @@
- 测试的 `query`，例如"维生素C的功效"
- 检索的模式 `search_mode`（默认为 `hybrid`）
- 目标检索的知识库列表 `index_names`，如 `["医疗", "维生素知识大全"]`
- - 若不输入 `index_names`，则默认检索知识库页面所选中的全部知识库
- - 是否启用重排模型（默认为 `false`），启用后配置重排模型，实现对检索结果的重排优化
+ - 若不输入 `index_names`，则默认检索知识库页面所选中的全部知识库
+ - 是否启用重排模型（默认为 `false`），启用后配置重排模型，实现对检索结果的重排优化
6. 输入完成后点击"执行测试"开始测试，并在下方查看测试结果
@@ -172,7 +282,8 @@
-### 🐛 调试与保存
+## 🐛 调试与保存
+
在完成初步智能体配置后，您可以对智能体进行调试，根据调试结果微调提示词，持续提升智能体表现。
@@ -182,7 +293,7 @@
调试成功后，可点击右下角"保存"按钮，此智能体将会被保存并出现在智能体列表中。
-### 🐛 版本管理
+## 🐛 版本管理
Nexent 支持智能体的版本管理，您可以在调试过程中，保存不同版本的智能体配置。
@@ -194,6 +305,121 @@ Nexent 支持智能体的版本管理，您可以在调试过程中，保存不
+### 🚀 发布为 A2A Agent
+
+Nexent 支持将已发布的智能体作为 A2A Agent 暴露给外部系统调用。在发布版本时，您可以勾选"发布为 A2A Agent"选项，将当前智能体注册为符合 A2A 1.0 规范的 Agent。
+
+
+
+
+
+发布成功后，系统会显示 A2A Agent 的调用信息，包括：
+
+
+
+
+
+| 信息项 | 说明 |
+|--------|------|
+| **Endpoint ID** | A2A Agent 的唯一标识符 |
+| **Agent Card URL** | Agent 发现端点，外部系统通过此地址获取 Agent 描述 |
+| **协议版本** | A2A 协议版本，当前为 1.0 |
+| **REST 端点** | 基于 REST 风格的 API 端点 |
+| **JSON-RPC 端点** | 基于 JSON-RPC 2.0 协议的调用端点 |
+
+#### 调用方式
+
+发布后的 A2A Agent 支持以下两种调用协议：
+
+##### REST API
+
+```bash
+# 获取 Agent Card（用于 Agent 发现）
+GET /nb/a2a/{endpoint_id}/.well-known/agent-card.json
+
+# 发送同步消息
+POST /nb/a2a/{endpoint_id}/message:send
+Content-Type: application/json
+
+{
+ "message": {
+ "role": "user",
+ "content": "请帮我完成某个任务"
+ }
+}
+
+# 发送流式消息（SSE）
+POST /nb/a2a/{endpoint_id}/message:stream
+Content-Type: application/json
+
+{
+ "message": {
+ "role": "user",
+ "content": "请帮我完成某个任务"
+ }
+}
+
+# 获取任务状态
+GET /nb/a2a/{endpoint_id}/tasks/{task_id}
+```
+
+##### JSON-RPC 2.0
+
+```bash
+POST /nb/a2a/{endpoint_id}/v1
+Content-Type: application/json
+
+# 发送同步消息
+{
+ "jsonrpc": "2.0",
+ "method": "SendMessage",
+ "params": {
+ "message": {
+ "role": "user",
+ "content": "请帮我完成某个任务"
+ }
+ },
+ "id": 1
+}
+
+# 发送流式消息
+{
+ "jsonrpc": "2.0",
+ "method": "SendStreamingMessage",
+ "params": {
+ "message": {
+ "role": "user",
+ "content": "请帮我完成某个任务"
+ }
+ },
+ "id": 2
+}
+
+# 获取任务状态
+{
+ "jsonrpc": "2.0",
+ "method": "GetTask",
+ "params": {
+ "taskId": "task_abc123"
+ },
+ "id": 3
+}
+```
+
+> 💡 **提示**：
+> - 本地开发时，请将路径前面的 `/nb/a2a` 部分替换为 `http://localhost:5013/nb/a2a`
+> - 生产环境请将路径替换为您的服务器域名或公网 IP 地址
+
+> ⚠️ **注意事项**：
+> - 调用 A2A Agent 需要在请求头中携带有效的认证信息
+> - Agent Card 信息会被缓存，刷新间隔为 1 小时
+> - 如需更新 Agent 信息，需要重新发布智能体版本
+
+当发布的Agent为符合A2A协议的Agent时，在智能体列表中，用户可以在智能体列表中点击下面这个按钮查看A2A Agent调用具体信息：
+
+
+
+
## 🔧 管理智能体
diff --git a/doc/docs/zh/user-guide/assets/agent-development/a2a-detail.jpg b/doc/docs/zh/user-guide/assets/agent-development/a2a-detail.jpg
new file mode 100644
index 000000000..e0ce35f1f
Binary files /dev/null and b/doc/docs/zh/user-guide/assets/agent-development/a2a-detail.jpg differ
diff --git a/doc/docs/zh/user-guide/assets/agent-development/a2a-discovery-list.jpg b/doc/docs/zh/user-guide/assets/agent-development/a2a-discovery-list.jpg
new file mode 100644
index 000000000..0464ce760
Binary files /dev/null and b/doc/docs/zh/user-guide/assets/agent-development/a2a-discovery-list.jpg differ
diff --git a/doc/docs/zh/user-guide/assets/agent-development/a2a-find-detail.jpg b/doc/docs/zh/user-guide/assets/agent-development/a2a-find-detail.jpg
new file mode 100644
index 000000000..ed9912627
Binary files /dev/null and b/doc/docs/zh/user-guide/assets/agent-development/a2a-find-detail.jpg differ
diff --git a/doc/docs/zh/user-guide/assets/agent-development/a2a-nacos-discovery.jpg b/doc/docs/zh/user-guide/assets/agent-development/a2a-nacos-discovery.jpg
new file mode 100644
index 000000000..f1fba231d
Binary files /dev/null and b/doc/docs/zh/user-guide/assets/agent-development/a2a-nacos-discovery.jpg differ
diff --git a/doc/docs/zh/user-guide/assets/agent-development/a2a-published-as.jpg b/doc/docs/zh/user-guide/assets/agent-development/a2a-published-as.jpg
new file mode 100644
index 000000000..7bfc7d170
Binary files /dev/null and b/doc/docs/zh/user-guide/assets/agent-development/a2a-published-as.jpg differ
diff --git a/doc/docs/zh/user-guide/assets/agent-development/a2a-url-discovery.jpg b/doc/docs/zh/user-guide/assets/agent-development/a2a-url-discovery.jpg
new file mode 100644
index 000000000..a6e244ff1
Binary files /dev/null and b/doc/docs/zh/user-guide/assets/agent-development/a2a-url-discovery.jpg differ
diff --git a/doc/docs/zh/user-guide/assets/agent-development/add_mcp_from_api.png b/doc/docs/zh/user-guide/assets/agent-development/add_mcp_from_api.png
new file mode 100644
index 000000000..ed03af94f
Binary files /dev/null and b/doc/docs/zh/user-guide/assets/agent-development/add_mcp_from_api.png differ
diff --git a/doc/docs/zh/user-guide/assets/agent-development/add_mcp_from_api_1.png b/doc/docs/zh/user-guide/assets/agent-development/add_mcp_from_api_1.png
new file mode 100644
index 000000000..4dda4579d
Binary files /dev/null and b/doc/docs/zh/user-guide/assets/agent-development/add_mcp_from_api_1.png differ
diff --git a/doc/docs/zh/user-guide/assets/agent-development/add_mcp_from_api_2.png b/doc/docs/zh/user-guide/assets/agent-development/add_mcp_from_api_2.png
new file mode 100644
index 000000000..faba05fec
Binary files /dev/null and b/doc/docs/zh/user-guide/assets/agent-development/add_mcp_from_api_2.png differ
diff --git a/doc/docs/zh/user-guide/assets/agent-development/set-collaboration.jpg b/doc/docs/zh/user-guide/assets/agent-development/set-collaboration.jpg
new file mode 100644
index 000000000..ccb8a2f6b
Binary files /dev/null and b/doc/docs/zh/user-guide/assets/agent-development/set-collaboration.jpg differ
diff --git a/doc/docs/zh/user-guide/assets/agent-development/set-collaboration.png b/doc/docs/zh/user-guide/assets/agent-development/set-collaboration.png
deleted file mode 100644
index 719f9b6ac..000000000
Binary files a/doc/docs/zh/user-guide/assets/agent-development/set-collaboration.png and /dev/null differ
diff --git a/doc/docs/zh/user-guide/knowledge-base.md b/doc/docs/zh/user-guide/knowledge-base.md
index fa98eac62..b0ebb53f5 100644
--- a/doc/docs/zh/user-guide/knowledge-base.md
+++ b/doc/docs/zh/user-guide/knowledge-base.md
@@ -26,12 +26,14 @@
Nexent支持多种文件格式，包括：
-- **文本**: .txt, .md文件
+- **文本**: .txt, .md, .json文件
- **PDF**: .pdf文件
- **Word**: .docx文件
- **PowerPoint**: .pptx文件
- **Excel**: .xlsx文件
+- **EPUB** .epub文件
- **数据文件**: .csv文件
+- **Web content**: .html, .xml文件
## 📊 知识库总结
diff --git a/doc/docs/zh/user-guide/local-tools/index.md b/doc/docs/zh/user-guide/local-tools/index.md
index ebd7de972..ceaac3f54 100644
--- a/doc/docs/zh/user-guide/local-tools/index.md
+++ b/doc/docs/zh/user-guide/local-tools/index.md
@@ -9,6 +9,7 @@
- [搜索工具](./search-tools)：本地/DataMate/Dify 知识库检索与 Exa/Tavily/Linkup 公网搜索。
- [多模态工具](./multimodal-tools)：文本文件与图片的下载、解析、模型分析。
- [终端工具](./terminal-tool)：持久化 SSH 会话，远程执行命令。
+- [技能（Skills）](../skills)：Nexent内置工具组合或自定义能力包，支持 NL 生成与版本管理。
## ⚙️ 配置入口
@@ -21,4 +22,4 @@
- 路径类操作仅限工作空间范围，请使用相对路径。
- 公网搜索需先在平台安全配置中填写 API Key。
- 终端工具涉及远程主机，请确认网络与账号安全策略。
-- 删除、移动类操作不可恢复，执行前先确认目标。
\ No newline at end of file
+- 删除、移动类操作不可恢复，执行前先确认目标。
diff --git a/doc/docs/zh/user-guide/model-management.md b/doc/docs/zh/user-guide/model-management.md
index 46c1b25b4..c8f07c0c3 100644
--- a/doc/docs/zh/user-guide/model-management.md
+++ b/doc/docs/zh/user-guide/model-management.md
@@ -169,6 +169,14 @@ Nexent支持与ModelEngine平台的无缝对接
`：展示可执行代码示例
+
+使用 `` 标签包裹可执行的代码示例（通常为 Python 代码）：
+
+```markdown
+
+result = run_skill_script(
+ "code-reviewer",
+ "scripts/analyze.py",
+ {"--target": "/path/to/file.py", "--verbose": True}
+)
+print(result)
+
+```
+
+### 辅助函数
+
+在智能体类技能的正文和示例中，可以使用以下函数：
+
+**`run_skill_script(skill_name, script_path, params)`**：执行技能包中的脚本
+
+```python
+# 执行 Python 脚本
+result = run_skill_script(
+ "code-reviewer",
+ "scripts/analyze.py",
+ {"--target": "/path/to/file.py"}
+)
+
+# 执行 Shell 脚本
+result = run_skill_script(
+ "database-migration",
+ "scripts/migrate.sh",
+ {"--direction": "up", "--steps": 1}
+)
+```
+
+**`read_skill_md(skill_name, files)`**：读取技能包中的文件内容
+
+```python
+# 默认只读取 SKILL.md（如果存在引用文件，不会自动包含）
+content = read_skill_md("my-skill")
+
+# 显式指定要读取的文件
+full_content = read_skill_md("my-skill", [
+ "SKILL.md",
+ "reference/api-reference.md"
+])
+```
+
+### 书写规范与最佳实践
+
+**SKILL.md 书写规范**：
+
+1. **描述要具体**：说明技能在什么场景下使用，而不是仅仅描述功能
+ - ✓ "当用户需要分析 GitHub 仓库的流行度指标时使用"
+ - ✗ "GitHub 搜索功能"
+
+2. **避免时间敏感信息**：不要包含具体日期、版本号等会过期的内容
+
+3. **保持简洁**：SKILL.md 正文建议控制在 500 行以内。复杂内容用 `` 按需加载
+
+4. **路径格式**：始终使用正斜杠 `/`，即使在 Windows 下也如此
+ - ✓ `src/services/payment_service.py`
+ - ✗ `src\services\payment_service.py`
+
+5. **参数命名一致**：全文统一使用相同的术语和命名风格
+
+6. **包含边界条件**：说明技能的适用范围和限制
+
+**参数描述最佳实践**：
+
+```yaml
+# ✓ 好：明确说明用途和格式
+query:
+ type: string
+ required: true
+ description: "GitHub repository owner/name or full URL"
+ description_zh: "GitHub 仓库的 owner/name 格式或完整 URL"
+
+# ✗ 差：过于模糊
+query:
+ type: string
+ required: true
+ description: "Search query"
+ description_zh: "查询"
+```
+
+**代码示例最佳实践**：
+
+- 每个工具至少提供 2 个不同场景的示例
+- 示例中包含常见参数组合
+- 示例展示成功调用和常见错误处理
+
+### 从现有技能学习
+
+系统内置了多个完整技能的参考示例，您可以在 `test_skill_examples/official-skills/` 目录下找到它们：
+
+| 技能名 | 参考价值 |
+|--------|---------|
+| `create-file-directory` | 工具类技能的标准写法，包含完整参数表、调用示例、错误处理表 |
+| `search-knowledge-base` | 搜索类技能的参数配置，包含 schema.yaml 和 config.yaml 的完整示例 |
+| `analyze-image` | 多模态工具的示例，包含 `` 调用格式 |
+| `code_review_expert` | 智能体类技能的参考，包含捆绑脚本和 `` 标签用法 |
+
+### 常见问题
+
+**Q: 上传 ZIP 包时报错"缺少 SKILL.md"**
+
+确保 ZIP 包根目录下包含 `SKILL.md` 文件，而不是将其放在子文件夹中。
+
+**Q: 技能描述不生效**
+
+技能描述应写在 YAML frontmatter 的 `description` 字段中，而非正文的 Markdown 部分。正文内容不会被解析为技能描述。
+
+## NL-to-Skill
+
+NL-to-Skill 是 Nexent 提供的一项智能创建功能。您只需要用**自然语言描述**一个技能的需求，系统就能自动生成完整的技能包，包括技能定义、参数配置、甚至配套的脚本代码。整个生成过程实时可见，就像有一个 AI 助手在帮您写代码一样。
+
+简单来说：
+
+> 您说"我想要一个能搜索 GitHub 仓库并提取 Star 数的技能"，系统就自动为您生成一个完整可用的技能。
+
+### 快速上手
+
+#### 第一步：描述您的需求
+
+在输入框中，用自然语言描述您想要的技能。描述越清晰，生成效果越好。
+
+**正例**：
+- "创建一个技能，可以根据关键词搜索 GitHub 仓库并返回 Star 数、描述和链接"
+- "创建一个读取 Excel 文件、统计各列数据并生成图表的技能"
+- "创建一个技能，能从邮件中提取订单号、金额和日期，汇总成表格"
+
+**反例**：
+- "帮我做一个聊天技能"（太模糊）
+- "搜索工具"（缺少具体能力描述）
+
+#### 第二步：查看生成过程
+
+点击"生成"后，页面会实时展示 AI 的思考和编写过程：
+- 看到 AI 在分析您的需求
+- 看到它正在编写技能定义文件
+- 看到它在规划参数结构
+
+这个过程就像看 AI 现场写代码，您可以随时点击"停止"中断。
+
+#### 第三步：预览并保存
+
+生成完成后，系统会展示技能的完整内容：
+- 技能名称和描述
+- 参数列表（每个参数是什么、是否必填）
+- 使用示例
+
+仔细检查预览内容：
+- 如需调整，点击"编辑"微调
+- 如符合预期，点击"保存"将技能添加到您的技能库
+
+### 写作技巧
+
+#### 如何写好技能描述
+
+**1. 明确输入输出**
+
+告诉系统这个技能需要什么信息、会返回什么结果。
+
+```
+✓ "输入一个 GitHub 仓库地址，返回仓库名称、Star 数、Fork 数和最新更新时间"
+✗ "搜索 GitHub"（太模糊）
+```
+
+**2. 说明使用场景**
+
+让 AI 理解在什么情况下会用到这个技能。
+
+```
+✓ "用于快速查询开源项目的流行程度，帮助做技术选型决策"
+✗ "查数据"（没有场景）
+```
+
+**3. 描述边界条件**
+
+如果有特殊的处理逻辑或限制，一并说明。
+
+```
+✓ "如果仓库不存在，返回友好提示而不是报错"
+✓ "图片 URL 无效时跳过该图片并记录日志"
+```
+
+**4. 显式要求生成示例**
+
+如果技能使用场景复杂，且对边缘场景响应准确率要求较高，则可以在要求中明确提出生成更详细的示例。
+
+```
+✓ "生成全面且详细的使用示例"
+```
+
+#### 适用场景举例
+
+| 场景 | 描述示例 |
+|------|---------|
+| **数据采集** | "输入关键词，在知乎上搜索相关问答并提取最高赞回答的摘要" |
+| **文件处理** | "上传一个 CSV 文件，自动统计各列数据并生成折线图" |
+| **API 封装** | "创建一个调用天气 API 并返回未来三天预报的技能" |
+| **多工具组合** | "输入商品链接，自动比价（调用多个电商搜索）并返回最低价链接" |
+| **数据清洗** | "读取一段混乱的文本，提取其中的邮箱、手机号、日期并格式化输出" |
+
+### 生成过程中可以做什么
+
+#### 实时预览
+
+生成过程中，技能内容会逐步显示在预览区域：
+- `SKILL.md` 内容：技能定义、描述、标签
+- `examples.md`：技能使用示例
+- `scripts/*.py`：工具脚本（复杂模式下）
+
+#### 随时停止
+
+如果生成方向偏离预期：
+- 点击"停止"按钮，AI 立即停止
+- 已有生成结果会保留，您可以查看或放弃
+
+#### 多次尝试
+
+如果第一次生成结果不理想：
+- 直接补充需求细节，在原有基础上直接修改
+- 或者在预览中手动调整
+- 不满意当前生成的技能，希望重新再来时，您可以点击右上角的"垃圾桶"图标清空所有技能内容
+
+### 使用限制与注意事项
+
+#### 模型能力影响质量
+
+NL-to-Skill 使用您租户配置的 LLM 模型来生成技能。模型的能力直接决定生成质量：
+- 聪明的模型能准确理解需求，生成结构清晰、易于理解的技能
+- 较弱的模型可能生成不完整或有误导性的内容，影响智能体的效率与准确率
+
+如果生成结果不理想，可以尝试：
+1. 简化需求描述
+2. 切换到更聪明、更强大的模型
+3. 分步骤创建（先做简单版本，再手动扩展）
+
+#### Token 消耗
+
+复杂技能生成会消耗更多 Token：
+- **简单模式**：通常消耗较少，适合快速验证
+- **复杂模式**：消耗较多，适合正式创建完整技能
+
+建议先用简单模式测试想法，确认可行后再用复杂模式正式创建。
+
+#### 并非所有需求都能实现
+
+NL-to-Skill 擅长生成以下类型的技能：
+- 单一工具的包装（如封装一个搜索能力）
+- 多工具的简单串联（如搜 → 读 → 总结）
+- 常见数据处理流程（如文件格式转换、数据提取）
+
+以下类型的技能可能超出能力范围：
+- 需要调用未接入的外部 API
+- 涉及复杂的状态管理或并发逻辑
+- 需要访问平台未开放的底层接口
+
+遇到无法实现的需求时，系统会给出提示，您可以考虑手动创建或联系技术支持。
+
+#### 技能修改
+
+在 NL-to-Skill 界面可以选中已经存在的技能。选中技能后，该技能信息将自动加载。您可以在左侧对话框中使用自然语言尝试对该技能进行更新。
+
+如果您创建的技能名与已有技能重名，Nexent 将自动从技能创建模式切换为技能更新模式。所有内容将覆盖更新至原有技能。
+
+## 安全与最佳实践
+
+- **知识库访问控制**：导入包含知识库工具的技能时，实际检索范围受当前用户权限限制
+- **公网搜索**：Tavily / Linkup / Exa 等公网搜索需先在平台安全配置中填写对应 API Key
+- **路径安全**：技能包内文件操作仅限技能目录范围内，无法访问系统任意路径
+
+## 相关参考
+
+- [智能体开发](./agent-development)
+- [本地工具概览](./local-tools/index)
+- [MCP 工具配置](./mcp-tools)
+- [技能系统概览](../backend/skills/overview)
diff --git a/doc/docs/zh/user-guide/start-chat.md b/doc/docs/zh/user-guide/start-chat.md
index 4e9dce692..fb3e4f0c6 100644
--- a/doc/docs/zh/user-guide/start-chat.md
+++ b/doc/docs/zh/user-guide/start-chat.md
@@ -80,8 +80,8 @@ Nexent支持语音输入功能，让您可以通过语音与智能体交互。
- 或直接将文件拖拽到对话区域
2. **支持的文件格式**
- - **文档类**：PDF、Word (.docx)、PowerPoint (.pptx)、Excel (.xlsx)
- - **文本类**：Markdown (.md)、纯文本 (.txt)
+ - **文档类**：PDF、Word (.docx)、PowerPoint (.pptx)、Excel (.xlsx), EPUB (.epub), HTML (.html), XML (.xml)
+ - **文本类**：Markdown (.md)、纯文本 (.txt), JSON (.json), CSV (.csv)
- **图片类**：JPG、PNG、GIF 等常见图片格式
3. **文件处理流程**
diff --git a/docker/init.sql b/docker/init.sql
index 2df9665c7..2e494fc72 100644
--- a/docker/init.sql
+++ b/docker/init.sql
@@ -175,6 +175,8 @@ CREATE TABLE IF NOT EXISTS "model_record_t" (
"updated_by" varchar(100) COLLATE "pg_catalog"."default",
"created_by" varchar(100) COLLATE "pg_catalog"."default",
"tenant_id" varchar(100) COLLATE "pg_catalog"."default" DEFAULT 'tenant_id',
+ "model_appid" varchar(100) COLLATE "pg_catalog"."default" DEFAULT '',
+ "access_token" varchar(100) COLLATE "pg_catalog"."default" DEFAULT '',
CONSTRAINT "nexent_models_t_pk" PRIMARY KEY ("model_id")
);
ALTER TABLE "model_record_t" OWNER TO "root";
@@ -198,6 +200,8 @@ COMMENT ON COLUMN "model_record_t"."update_time" IS 'Update time, audit field';
COMMENT ON COLUMN "model_record_t"."updated_by" IS 'Last updater ID, audit field';
COMMENT ON COLUMN "model_record_t"."created_by" IS 'Creator ID, audit field';
COMMENT ON COLUMN "model_record_t"."tenant_id" IS 'Tenant ID for filtering';
+COMMENT ON COLUMN "model_record_t"."model_appid" IS 'Application ID for model authentication.';
+COMMENT ON COLUMN "model_record_t"."access_token" IS 'Access token for model authentication.';
COMMENT ON TABLE "model_record_t" IS 'List of models defined by users in the configuration page';
INSERT INTO "nexent"."model_record_t" ("model_repo", "model_name", "model_factory", "model_type", "api_key", "base_url", "max_tokens", "used_token", "display_name", "connect_status") VALUES ('', 'volcano_tts', 'OpenAI-API-Compatible', 'tts', '', '', 0, 0, 'volcano_tts', 'unavailable');
@@ -211,6 +215,7 @@ CREATE TABLE IF NOT EXISTS "knowledge_record_t" (
"tenant_id" varchar(100) COLLATE "pg_catalog"."default",
"knowledge_sources" varchar(100) COLLATE "pg_catalog"."default",
"embedding_model_name" varchar(200) COLLATE "pg_catalog"."default",
+ "embedding_model_id" INTEGER,
"group_ids" varchar,
"ingroup_permission" varchar(30),
"create_time" timestamp(0) DEFAULT CURRENT_TIMESTAMP,
@@ -218,6 +223,9 @@ CREATE TABLE IF NOT EXISTS "knowledge_record_t" (
"delete_flag" varchar(1) COLLATE "pg_catalog"."default" DEFAULT 'N'::character varying,
"updated_by" varchar(100) COLLATE "pg_catalog"."default",
"created_by" varchar(100) COLLATE "pg_catalog"."default",
+ "summary_frequency" varchar(10) COLLATE "pg_catalog"."default",
+ "last_summary_time" timestamp(0),
+ "last_doc_update_time" timestamp(0),
CONSTRAINT "knowledge_record_t_pk" PRIMARY KEY ("knowledge_id")
);
ALTER TABLE "knowledge_record_t" OWNER TO "root";
@@ -228,11 +236,17 @@ COMMENT ON COLUMN "knowledge_record_t"."knowledge_describe" IS 'Knowledge base d
COMMENT ON COLUMN "knowledge_record_t"."tenant_id" IS 'Tenant ID';
COMMENT ON COLUMN "knowledge_record_t"."knowledge_sources" IS 'Knowledge base sources';
COMMENT ON COLUMN "knowledge_record_t"."embedding_model_name" IS 'Embedding model name, used to record the embedding model used by the knowledge base';
+COMMENT ON COLUMN "knowledge_record_t"."embedding_model_id" IS 'Embedding model ID, foreign key reference to model_record_t.model_id';
COMMENT ON COLUMN "knowledge_record_t"."group_ids" IS 'Knowledge base group IDs list';
COMMENT ON COLUMN "knowledge_record_t"."ingroup_permission" IS 'In-group permission: EDIT, READ_ONLY, PRIVATE';
COMMENT ON COLUMN "knowledge_record_t"."create_time" IS 'Creation time, audit field';
COMMENT ON COLUMN "knowledge_record_t"."update_time" IS 'Update time, audit field';
COMMENT ON COLUMN "knowledge_record_t"."delete_flag" IS 'When deleted by user frontend, delete flag will be set to true, achieving soft delete effect. Optional values Y/N';
+COMMENT ON COLUMN "knowledge_record_t"."updated_by" IS 'User who last updated the record, audit field';
+COMMENT ON COLUMN "knowledge_record_t"."created_by" IS 'User who created the record, audit field';
+COMMENT ON COLUMN "knowledge_record_t"."summary_frequency" IS 'Auto-summary frequency: 1h, 3h, 6h, 1d, 1w, or NULL (disabled)';
+COMMENT ON COLUMN "knowledge_record_t"."last_summary_time" IS 'Timestamp of last summary generation';
+COMMENT ON COLUMN "knowledge_record_t"."last_doc_update_time" IS 'Timestamp of last document add/delete operation, used for auto-summary optimization to skip unnecessary summary regeneration';
COMMENT ON COLUMN "knowledge_record_t"."updated_by" IS 'Last updater ID, audit field';
COMMENT ON COLUMN "knowledge_record_t"."created_by" IS 'Creator ID, audit field';
COMMENT ON TABLE "knowledge_record_t" IS 'Records knowledge base description and status information';
@@ -1306,6 +1320,9 @@ CREATE TABLE IF NOT EXISTS nexent.ag_a2a_external_agent_t (
nacos_config_id VARCHAR(64),
nacos_agent_name VARCHAR(255),
+ -- Base URL for infrastructure health checks
+ base_url VARCHAR(512),
+
-- Tenant isolation
tenant_id VARCHAR(100) NOT NULL,
created_by VARCHAR(100) NOT NULL,
@@ -1352,6 +1369,7 @@ COMMENT ON COLUMN nexent.ag_a2a_external_agent_t.last_check_result IS 'Last heal
COMMENT ON COLUMN nexent.ag_a2a_external_agent_t.create_time IS 'Record creation timestamp';
COMMENT ON COLUMN nexent.ag_a2a_external_agent_t.update_time IS 'Record last update timestamp';
COMMENT ON COLUMN nexent.ag_a2a_external_agent_t.delete_flag IS 'Soft delete flag: Y/N'; -- NOSONAR
+COMMENT ON COLUMN nexent.ag_a2a_external_agent_t.base_url IS 'Base URL for health checks (service root address)';
CREATE TABLE IF NOT EXISTS nexent.ag_a2a_external_agent_relation_t (
@@ -1365,8 +1383,7 @@ CREATE TABLE IF NOT EXISTS nexent.ag_a2a_external_agent_relation_t (
create_time TIMESTAMP(6) DEFAULT CURRENT_TIMESTAMP,
update_time TIMESTAMP(6) DEFAULT CURRENT_TIMESTAMP,
delete_flag VARCHAR(1) DEFAULT 'N',
- CONSTRAINT uq_local_external_agent UNIQUE (local_agent_id, external_agent_id),
- CONSTRAINT fk_external_agent FOREIGN KEY (external_agent_id) REFERENCES nexent.ag_a2a_external_agent_t(id)
+ CONSTRAINT uq_local_external_agent UNIQUE (local_agent_id, external_agent_id)
);
ALTER TABLE nexent.ag_a2a_external_agent_relation_t OWNER TO "root";
@@ -1476,9 +1493,7 @@ CREATE TABLE IF NOT EXISTS nexent.ag_a2a_message_t (
extensions JSONB, -- Extension URI list
reference_task_ids JSONB, -- Referenced task IDs array
create_time TIMESTAMP(6) DEFAULT CURRENT_TIMESTAMP,
- UNIQUE(task_id, message_index),
- CONSTRAINT ag_a2a_message_t_task_id_fk FOREIGN KEY (task_id)
- REFERENCES nexent.ag_a2a_task_t(id) ON DELETE CASCADE
+ UNIQUE(task_id, message_index)
);
ALTER TABLE nexent.ag_a2a_message_t OWNER TO "root";
@@ -1504,8 +1519,6 @@ CREATE TABLE IF NOT EXISTS nexent.ag_a2a_artifact_t (
meta_data JSONB, -- Metadata
extensions JSONB, -- Extension URI list
create_time TIMESTAMP(6) DEFAULT CURRENT_TIMESTAMP,
- CONSTRAINT fk_artifact_task FOREIGN KEY (task_id)
- REFERENCES nexent.ag_a2a_task_t(id) ON DELETE CASCADE,
UNIQUE(task_id, artifact_id)
);
diff --git a/docker/sql/v2.0.4_0506_add_base_url_in_external_agent.sql b/docker/sql/v2.0.4_0506_add_base_url_in_external_agent.sql
new file mode 100644
index 000000000..e4723bc96
--- /dev/null
+++ b/docker/sql/v2.0.4_0506_add_base_url_in_external_agent.sql
@@ -0,0 +1,13 @@
+ALTER TABLE nexent.ag_a2a_external_agent_t
+ADD COLUMN IF NOT EXISTS base_url VARCHAR(512);
+
+COMMENT ON COLUMN nexent.ag_a2a_external_agent_t.base_url IS 'Base URL for health checks (service root address)';
+
+ALTER TABLE nexent.ag_a2a_message_t
+ DROP CONSTRAINT IF EXISTS ag_a2a_message_t_task_id_fk;
+
+ALTER TABLE nexent.ag_a2a_external_agent_relation_t
+ DROP CONSTRAINT IF EXISTS fk_external_agent;
+
+ALTER TABLE nexent.ag_a2a_artifact_t
+ DROP CONSTRAINT IF EXISTS fk_artifact_task;
\ No newline at end of file
diff --git a/docker/sql/v2.0.5_0511_add_auto_summary_fields_to_knowledge_record_t.sql b/docker/sql/v2.0.5_0511_add_auto_summary_fields_to_knowledge_record_t.sql
new file mode 100644
index 000000000..491f6b27b
--- /dev/null
+++ b/docker/sql/v2.0.5_0511_add_auto_summary_fields_to_knowledge_record_t.sql
@@ -0,0 +1,21 @@
+-- Migration: Add auto-summary fields to knowledge_record_t table
+-- Date: 2026-05-11
+-- Description: Add summary_frequency, last_summary_time, and last_doc_update_time fields for auto-summary feature
+-- This SQL consolidates fields added in multiple commits for clean upgrade path
+
+-- Add summary_frequency column (auto-summary frequency configuration)
+ALTER TABLE nexent.knowledge_record_t
+ADD COLUMN IF NOT EXISTS summary_frequency VARCHAR(10);
+
+-- Add last_summary_time column (timestamp of last summary generation)
+ALTER TABLE nexent.knowledge_record_t
+ADD COLUMN IF NOT EXISTS last_summary_time TIMESTAMP;
+
+-- Add last_doc_update_time column (timestamp of last document add/delete operation)
+ALTER TABLE nexent.knowledge_record_t
+ADD COLUMN IF NOT EXISTS last_doc_update_time TIMESTAMP;
+
+-- Add comments to the columns
+COMMENT ON COLUMN nexent.knowledge_record_t.summary_frequency IS 'Auto-summary frequency: 1h, 3h, 6h, 1d, 1w, or NULL (disabled)';
+COMMENT ON COLUMN nexent.knowledge_record_t.last_summary_time IS 'Timestamp of last summary generation';
+COMMENT ON COLUMN nexent.knowledge_record_t.last_doc_update_time IS 'Timestamp of last document add/delete operation, used for auto-summary optimization to skip unnecessary summary regeneration';
\ No newline at end of file
diff --git a/docker/sql/v2.1.1_0508_add_embedding_model_id_to_knowledge_record_t.sql b/docker/sql/v2.1.1_0508_add_embedding_model_id_to_knowledge_record_t.sql
new file mode 100644
index 000000000..0305a2590
--- /dev/null
+++ b/docker/sql/v2.1.1_0508_add_embedding_model_id_to_knowledge_record_t.sql
@@ -0,0 +1,9 @@
+-- Add embedding_model_id column to knowledge_record_t table
+-- This field stores the ID of the embedding model used by the knowledge base
+
+-- Add embedding_model_id column
+ALTER TABLE "knowledge_record_t"
+ADD COLUMN IF NOT EXISTS "embedding_model_id" INTEGER;
+
+-- Add column comment
+COMMENT ON COLUMN "knowledge_record_t"."embedding_model_id" IS 'Embedding model ID, foreign key reference to model_record_t.model_id';
diff --git a/docker/sql/v2.1.1_0509_add_model_appid_token_to_model_record_t.sql b/docker/sql/v2.1.1_0509_add_model_appid_token_to_model_record_t.sql
new file mode 100644
index 000000000..521fa38a4
--- /dev/null
+++ b/docker/sql/v2.1.1_0509_add_model_appid_token_to_model_record_t.sql
@@ -0,0 +1,9 @@
+ALTER TABLE nexent.model_record_t
+ADD COLUMN IF NOT EXISTS model_appid VARCHAR(100) DEFAULT '';
+
+
+ALTER TABLE nexent.model_record_t
+ADD COLUMN IF NOT EXISTS access_token VARCHAR(100) DEFAULT '';
+
+COMMENT ON COLUMN nexent.model_record_t.model_appid IS 'Application ID for model authentication.';
+COMMENT ON COLUMN nexent.model_record_t.access_token IS 'Access token for model authentication.';
diff --git a/frontend/app/[locale]/agents/components/a2a/A2AAgentDiscoveryModal.tsx b/frontend/app/[locale]/agents/components/a2a/A2AAgentDiscoveryModal.tsx
index 1988d6a8d..bc9260a29 100644
--- a/frontend/app/[locale]/agents/components/a2a/A2AAgentDiscoveryModal.tsx
+++ b/frontend/app/[locale]/agents/components/a2a/A2AAgentDiscoveryModal.tsx
@@ -33,8 +33,9 @@ import {
Settings,
MessageCircle,
} from "lucide-react";
-import { a2aClientService, A2AExternalAgent, NacosConfig } from "@/services/a2aService";
+import { a2aClientService, A2AExternalAgent } from "@/services/a2aService";
import A2AChatModal from "./A2AChatModal";
+import NacosDiscoveryPanel from "./NacosDiscoveryPanel";
import log from "@/lib/logger";
const { Text, Title } = Typography;
@@ -195,7 +196,7 @@ export default function A2AAgentDiscoveryModal({
const [chatAgent, setChatAgent] = useState(null);
// Discovery mode
- const [mode, setMode] = useState<"url" | "nacos">("url");
+ const [mode, setMode] = useState<"url" | "nacos" | "list">("url");
const [loading, setLoading] = useState(false);
const [discoveredAgents, setDiscoveredAgents] = useState([]);
@@ -203,47 +204,11 @@ export default function A2AAgentDiscoveryModal({
const [url, setUrl] = useState("");
const [selectedAgent, setSelectedAgent] = useState(null);
- // Nacos mode state - Add new config form (toggleable)
- const [showAddNacosForm, setShowAddNacosForm] = useState(false);
- const [newNacosConfig, setNewNacosConfig] = useState({
- name: "",
- nacos_addr: "",
- username: "",
- password: "",
- namespace_id: "public",
- });
- const [savingNacosConfig, setSavingNacosConfig] = useState(false);
-
- // Nacos mode state - Existing configs list
- const [nacosConfigs, setNacosConfigs] = useState([]);
- const [loadingNacosConfigs, setLoadingNacosConfigs] = useState(false);
- const [selectedNacosConfigId, setSelectedNacosConfigId] = useState(null);
-
- // Nacos scan state
- const [agentNames, setAgentNames] = useState([]);
- const [scanning, setScanning] = useState(false);
-
// List mode state
const [agents, setAgents] = useState([]);
const [loadingAgents, setLoadingAgents] = useState(false);
const [refreshingId, setRefreshingId] = useState(null);
- // Load Nacos configs and existing agents on mount
- useEffect(() => {
- if (open) {
- loadNacosConfigs();
- loadAgents();
- }
- }, [open]);
-
- const loadNacosConfigs = async () => {
- setLoadingNacosConfigs(true);
- const result = await a2aClientService.listNacosConfigs();
- if (result.success && result.data) {
- setNacosConfigs(result.data);
- }
- setLoadingNacosConfigs(false);
- };
const loadAgents = async () => {
setLoadingAgents(true);
@@ -275,7 +240,6 @@ export default function A2AAgentDiscoveryModal({
if (result.success && result.data) {
setSelectedAgent(result.data);
setDiscoveredAgents([result.data]);
- loadAgents();
if (onDiscoverSuccess) {
onDiscoverSuccess();
}
@@ -285,90 +249,6 @@ export default function A2AAgentDiscoveryModal({
}
};
- // Add new Nacos config
- const handleAddNacosConfig = async () => {
- if (!newNacosConfig.name.trim()) {
- messageApi.error(t("a2a.discovery.nacosNameRequired"));
- return;
- }
- if (!newNacosConfig.nacos_addr.trim()) {
- messageApi.error(t("a2a.discovery.nacosAddrRequired"));
- return;
- }
-
- setSavingNacosConfig(true);
- try {
- const result = await a2aClientService.createNacosConfig({
- name: newNacosConfig.name.trim(),
- nacos_addr: newNacosConfig.nacos_addr.trim(),
- namespace_id: newNacosConfig.namespace_id || "public",
- nacos_username: newNacosConfig.username.trim() || undefined,
- nacos_password: newNacosConfig.password.trim() || undefined,
- });
-
- if (result.success && result.data) {
- messageApi.success(t("a2a.discovery.addNacosConfigSuccess"));
- await loadNacosConfigs();
- setSelectedNacosConfigId(result.data.config_id);
- setNewNacosConfig({ name: "", nacos_addr: "", username: "", password: "", namespace_id: "public" });
- } else {
- messageApi.error(result.message || t("a2a.discovery.addNacosConfigFailed"));
- }
- } catch (error) {
- log.error("Failed to add Nacos config:", error);
- messageApi.error(t("a2a.discovery.addNacosConfigFailed"));
- }
- setSavingNacosConfig(false);
- };
-
- // Delete Nacos config
- const handleDeleteNacosConfig = async (configId: string) => {
- const result = await a2aClientService.deleteNacosConfig(configId);
- if (result.success) {
- messageApi.success(t("a2a.discovery.deleteNacosConfigSuccess"));
- if (selectedNacosConfigId === configId) {
- setSelectedNacosConfigId(null);
- }
- await loadNacosConfigs();
- } else {
- messageApi.error(result.message || t("a2a.discovery.deleteNacosConfigFailed"));
- }
- };
-
- // Discover from Nacos
- const handleDiscoverFromNacos = async () => {
- if (!selectedNacosConfigId) {
- messageApi.error(t("a2a.discovery.selectNacosConfig"));
- return;
- }
-
- if (agentNames.length === 0) {
- messageApi.error(t("a2a.discovery.enterAgentNames"));
- return;
- }
-
- setScanning(true);
- const result = await a2aClientService.discoverFromNacos({
- nacos_config_id: selectedNacosConfigId,
- agent_names: agentNames,
- namespace: newNacosConfig.namespace_id || "public",
- });
- setScanning(false);
-
- if (result.success && result.data) {
- setDiscoveredAgents(result.data);
- if (result.data.length === 0) {
- messageApi.warning(t("a2a.discovery.noAgentsFound"));
- } else {
- messageApi.success(
- t("a2a.discovery.foundAgents", { count: result.data.length })
- );
- }
- } else {
- messageApi.error(result.message || t("a2a.discovery.failed"));
- }
- };
-
// Refresh agent card
const handleRefresh = async (agentId: string) => {
setRefreshingId(agentId);
@@ -456,59 +336,6 @@ export default function A2AAgentDiscoveryModal({
);
};
- // Nacos config table columns
- const nacosConfigColumns = [
- {
- title: t("a2a.discovery.nacosName"),
- dataIndex: "name",
- key: "name",
- width: "30%",
- ellipsis: true,
- render: (text: string) => {text} ,
- },
- {
- title: t("a2a.discovery.nacosAddr"),
- dataIndex: "nacos_addr",
- key: "nacos_addr",
- width: "40%",
- ellipsis: true,
- render: (text: string) => {text} ,
- },
- {
- title: t("a2a.discovery.namespace"),
- dataIndex: "namespace_id",
- key: "namespace_id",
- width: "15%",
- render: (text: string) => {text} ,
- },
- {
- title: t("common.actions"),
- key: "action",
- width: "15%",
- render: (_: any, record: NacosConfig) => (
-
-
- }
- onClick={() => setSelectedNacosConfigId(record.config_id)}
- />
-
-
- }
- onClick={() => handleDeleteNacosConfig(record.config_id)}
- />
-
-
- ),
- },
- ];
-
// Agent columns for table
const agentColumns = [
{
@@ -624,9 +451,12 @@ export default function A2AAgentDiscoveryModal({
{
- setMode(key as "url" | "nacos");
+ setMode(key as "url" | "nacos" | "list");
setDiscoveredAgents([]);
setSelectedAgent(null);
+ if (key === "list") {
+ loadAgents();
+ }
}}
items={[
// URL Discovery Tab
@@ -689,212 +519,22 @@ export default function A2AAgentDiscoveryModal({
),
},
- // Nacos Discovery Tab (disabled - feature pending)
+ // Nacos Discovery Tab
{
key: "nacos",
label: (
Coming Soon
),
- disabled: true,
+ disabled: false,
children: (
-
- {/* Existing Nacos Configs List */}
-
-
-
- {t("a2a.discovery.nacosConfigList")}
-
-
- }
- onClick={() => setShowAddNacosForm(!showAddNacosForm)}
- >
- {t("a2a.discovery.addNacosConfig")}
-
- }
- onClick={loadNacosConfigs}
- loading={loadingNacosConfigs}
- >
- {t("common.refresh")}
-
-
-
-
- {/* Add Nacos Config Form - Toggleable */}
- {showAddNacosForm && (
-
-
-
- )}
-
-
- record.config_id === selectedNacosConfigId ? "bg-blue-50" : ""
- }
- onRow={(record) => ({
- onClick: () => setSelectedNacosConfigId(record.config_id),
- style: { cursor: "pointer" },
- })}
- />
-
-
- {/* Scan Section - Only show when config is selected */}
- {selectedNacosConfigId && (
-
-
-
- )}
-
- {/* Discovered Agents */}
- {discoveredAgents.length > 0 && (
-
-
- {t("a2a.discovery.discoveredAgents", {
- count: discoveredAgents.length,
- })}
-
- {discoveredAgents.map((agent) => (
- handleAddToLocalAgent(agent)
- : undefined
- }
- />
- ))}
-
- )}
-
+ (null);
+ const [nacosConfig, setNacosConfig] = useState({
+ name: "",
+ nacos_addr: "",
+ username: "",
+ password: "",
+ namespace_id: "public",
+ });
+ const [savingNacosConfig, setSavingNacosConfig] = useState(false);
+ const [testingConnection, setTestingConnection] = useState(false);
+
+ // Existing configs list state
+ const [nacosConfigs, setNacosConfigs] = useState([]);
+ const [loadingNacosConfigs, setLoadingNacosConfigs] = useState(false);
+ const [selectedNacosConfigId, setSelectedNacosConfigId] = useState(null);
+ const [testingConfigId, setTestingConfigId] = useState(null);
+
+ // Scan state
+ const [agentNames, setAgentNames] = useState([]);
+ const [scanning, setScanning] = useState(false);
+ const [discoveredAgents, setDiscoveredAgents] = useState([]);
+
+ // Load configs on mount
+ useEffect(() => {
+ loadNacosConfigs();
+ }, []);
+
+ const loadNacosConfigs = async () => {
+ setLoadingNacosConfigs(true);
+ const result = await a2aClientService.listNacosConfigs();
+ if (result.success && result.data) {
+ setNacosConfigs(result.data);
+ }
+ setLoadingNacosConfigs(false);
+ };
+
+ const handleTestNacosConnection = async (configToTest?: NacosConfig) => {
+ const addr = configToTest?.nacos_addr ?? nacosConfig.nacos_addr;
+ if (!addr.trim()) {
+ messageApi.error(t("a2a.discovery.nacosAddrRequired"));
+ return;
+ }
+
+ const isTestingExisting = !!configToTest;
+ if (isTestingExisting) {
+ setTestingConfigId(configToTest!.config_id);
+ } else {
+ setTestingConnection(true);
+ }
+ try {
+ const result = await a2aClientService.testNacosConnection({
+ nacos_addr: addr.trim(),
+ namespace_id: configToTest?.namespace_id || nacosConfig.namespace_id || "public",
+ nacos_username: configToTest?.nacos_username ?? (nacosConfig.username.trim() || undefined),
+ nacos_password: configToTest?.nacos_password ?? (nacosConfig.password.trim() || undefined),
+ });
+
+ if (result.success) {
+ messageApi.success(result.message || t("a2a.discovery.testConnectionSuccess"));
+ } else {
+ messageApi.error(result.message || t("a2a.discovery.testConnectionFailed"));
+ }
+ } catch (error) {
+ log.error("Failed to test Nacos connection:", error);
+ messageApi.error(t("a2a.discovery.testConnectionFailed"));
+ }
+ if (isTestingExisting) {
+ setTestingConfigId(null);
+ } else {
+ setTestingConnection(false);
+ }
+ };
+
+ const handleAddNacosConfig = async () => {
+ if (!nacosConfig.name.trim()) {
+ messageApi.error(t("a2a.discovery.nacosNameRequired"));
+ return;
+ }
+ if (!nacosConfig.nacos_addr.trim()) {
+ messageApi.error(t("a2a.discovery.nacosAddrRequired"));
+ return;
+ }
+
+ setSavingNacosConfig(true);
+ try {
+ const result = await a2aClientService.createNacosConfig({
+ name: nacosConfig.name.trim(),
+ nacos_addr: nacosConfig.nacos_addr.trim(),
+ namespace_id: nacosConfig.namespace_id || "public",
+ nacos_username: nacosConfig.username.trim() || undefined,
+ nacos_password: nacosConfig.password.trim() || undefined,
+ });
+
+ if (result.success && result.data) {
+ messageApi.success(t("a2a.discovery.addNacosConfigSuccess"));
+ await loadNacosConfigs();
+ setSelectedNacosConfigId(result.data.config_id);
+ setNacosConfig({ name: "", nacos_addr: "", username: "", password: "", namespace_id: "public" });
+ setShowAddNacosForm(false);
+ } else {
+ messageApi.error(result.message || t("a2a.discovery.addNacosConfigFailed"));
+ }
+ } catch (error) {
+ log.error("Failed to add Nacos config:", error);
+ messageApi.error(t("a2a.discovery.addNacosConfigFailed"));
+ }
+ setSavingNacosConfig(false);
+ };
+
+ const handleDeleteNacosConfig = async (configId: string) => {
+ const result = await a2aClientService.deleteNacosConfig(configId);
+ if (result.success) {
+ messageApi.success(t("a2a.discovery.deleteNacosConfigSuccess"));
+ if (selectedNacosConfigId === configId) {
+ setSelectedNacosConfigId(null);
+ }
+ await loadNacosConfigs();
+ } else {
+ messageApi.error(result.message || t("a2a.discovery.deleteNacosConfigFailed"));
+ }
+ };
+
+ const handleEditNacosConfig = (config: NacosConfig) => {
+ setEditingConfigId(config.config_id);
+ setNacosConfig({
+ name: config.name,
+ nacos_addr: config.nacos_addr,
+ username: config.nacos_username || "",
+ password: config.nacos_password || "",
+ namespace_id: config.namespace_id || "public",
+ });
+ setShowAddNacosForm(true);
+ };
+
+ const handleUpdateNacosConfig = async () => {
+ if (!editingConfigId) return;
+
+ if (!nacosConfig.name.trim()) {
+ messageApi.error(t("a2a.discovery.nacosNameRequired"));
+ return;
+ }
+ if (!nacosConfig.nacos_addr.trim()) {
+ messageApi.error(t("a2a.discovery.nacosAddrRequired"));
+ return;
+ }
+
+ setSavingNacosConfig(true);
+ try {
+ const result = await a2aClientService.updateNacosConfig(editingConfigId, {
+ name: nacosConfig.name.trim(),
+ nacos_addr: nacosConfig.nacos_addr.trim(),
+ namespace_id: nacosConfig.namespace_id || "public",
+ nacos_username: nacosConfig.username.trim() || undefined,
+ nacos_password: nacosConfig.password.trim() || undefined,
+ });
+
+ if (result.success) {
+ messageApi.success(t("a2a.discovery.updateNacosConfigSuccess"));
+ setShowAddNacosForm(false);
+ handleCancelEdit();
+ await loadNacosConfigs();
+ } else {
+ messageApi.error(result.message || t("a2a.discovery.updateNacosConfigFailed"));
+ }
+ } catch (error) {
+ log.error("Failed to update Nacos config:", error);
+ messageApi.error(t("a2a.discovery.updateNacosConfigFailed"));
+ }
+ setSavingNacosConfig(false);
+ };
+
+ const handleCancelEdit = () => {
+ setEditingConfigId(null);
+ setNacosConfig({
+ name: "",
+ nacos_addr: "",
+ username: "",
+ password: "",
+ namespace_id: "public",
+ });
+ };
+
+ const handleDiscoverFromNacos = async () => {
+ if (!selectedNacosConfigId) {
+ messageApi.error(t("a2a.discovery.selectNacosConfig"));
+ return;
+ }
+
+ if (agentNames.length === 0) {
+ messageApi.error(t("a2a.discovery.enterAgentNames"));
+ return;
+ }
+
+ const selectedConfig = nacosConfigs.find(c => c.config_id === selectedNacosConfigId);
+ setScanning(true);
+ const result = await a2aClientService.discoverFromNacos({
+ nacos_config_id: selectedNacosConfigId,
+ agent_names: agentNames.map(name => name.trim()).filter(name => name.length > 0),
+ namespace: selectedConfig?.namespace_id || "public",
+ });
+ setScanning(false);
+
+ if (result.success && result.data) {
+ setDiscoveredAgents(result.data);
+ if (result.data.length === 0) {
+ messageApi.warning(t("a2a.discovery.noAgentsFound"));
+ } else {
+ messageApi.success(
+ t("a2a.discovery.foundAgents", { count: result.data.length })
+ );
+ result.data.forEach((agent) => {
+ if (onAgentDiscovered) {
+ onAgentDiscovered(agent);
+ }
+ });
+ if (onDiscoverSuccess) {
+ onDiscoverSuccess();
+ }
+ }
+ } else {
+ messageApi.error(result.message || t("a2a.discovery.scanFailed"));
+ }
+ };
+
+ const handleAddToLocalAgent = async (agent: A2AExternalAgent) => {
+ if (!localAgentId) return;
+
+ const result = await a2aClientService.addRelation(localAgentId, agent.id);
+ if (result.success) {
+ messageApi.success(t("a2a.discovery.addToLocalAgentSuccess"));
+ } else {
+ messageApi.error(result.message || t("a2a.discovery.addToLocalAgentFailed"));
+ }
+ };
+
+ // Nacos config table columns
+ const nacosConfigColumns = [
+ {
+ title: t("a2a.discovery.nacosName"),
+ dataIndex: "name",
+ key: "name",
+ width: "20%",
+ ellipsis: true,
+ render: (text: string) => {text} ,
+ },
+ {
+ title: t("a2a.discovery.nacosAddr"),
+ dataIndex: "nacos_addr",
+ key: "nacos_addr",
+ width: "40%",
+ ellipsis: true,
+ render: (text: string) => {text} ,
+ },
+ {
+ title: t("a2a.discovery.namespace"),
+ dataIndex: "namespace_id",
+ key: "namespace_id",
+ width: "20%",
+ render: (text: string) => {text} ,
+ },
+ {
+ title: t("common.actions"),
+ key: "action",
+ width: "15%",
+ render: (_: any, record: NacosConfig) => (
+
+
+ }
+ onClick={() => handleEditNacosConfig(record)}
+ />
+
+
+ }
+ loading={testingConfigId === record.config_id}
+ onClick={() => handleTestNacosConnection(record)}
+ />
+
+
+ }
+ onClick={() => setSelectedNacosConfigId(record.config_id)}
+ />
+
+
+ }
+ onClick={() => handleDeleteNacosConfig(record.config_id)}
+ />
+
+
+ ),
+ },
+ ];
+
+ return (
+ <>
+ {contextHolder}
+
+ {/* Existing Nacos Configs List */}
+
+
+
+ {t("a2a.discovery.nacosConfigList")}
+
+
+ }
+ onClick={() => {
+ setEditingConfigId(null);
+ setNacosConfig({
+ name: "",
+ nacos_addr: "",
+ username: "",
+ password: "",
+ namespace_id: "public",
+ });
+ setShowAddNacosForm(true);
+ }}
+ >
+ {t("a2a.discovery.addNacosConfig")}
+
+ }
+ onClick={loadNacosConfigs}
+ loading={loadingNacosConfigs}
+ >
+ {t("common.refresh")}
+
+
+
+
+ {/* Add/Edit Nacos Config Form - Toggleable */}
+ {showAddNacosForm && (
+
+
+
+ )}
+
+
+ record.config_id === selectedNacosConfigId ? "bg-blue-50" : ""
+ }
+ onRow={(record) => ({
+ onClick: () => setSelectedNacosConfigId(record.config_id),
+ style: { cursor: "pointer" },
+ })}
+ />
+
+
+ {/* Scan Section - Only show when config is selected */}
+ {selectedNacosConfigId && (
+
+
+
+ )}
+
+ {/* Discovered Agents */}
+ {discoveredAgents.length > 0 && (
+
+
+ {t("a2a.discovery.discoveredAgents", {
+ count: discoveredAgents.length,
+ })}
+
+ {discoveredAgents.map((agent) => (
+ handleAddToLocalAgent(agent)
+ : undefined
+ }
+ />
+ ))}
+
+ )}
+
+
+ );
+}
+
+// Agent Detail Card Component
+interface AgentDetailCardProps {
+ agent: A2AExternalAgent;
+ onAddToLocalAgent?: () => void;
+}
+
+function AgentDetailCard({ agent, onAddToLocalAgent }: AgentDetailCardProps) {
+ const { t } = useTranslation("common");
+
+ return (
+
+
+
+
+ {agent.name}
+
+ {agent.source_type === "url" ? "URL" : "Nacos"}
+
+
+
+ {agent.description || t("a2a.discovery.noDescription")}
+
+
+ {agent.agent_url || agent.source_url}
+
+
+ {onAddToLocalAgent && (
+ }
+ onClick={onAddToLocalAgent}
+ >
+ {t("a2a.discovery.addToLocalAgent")}
+
+ )}
+
+
+ );
+}
diff --git a/frontend/app/[locale]/agents/components/agentConfig/tool/ToolConfigModal.tsx b/frontend/app/[locale]/agents/components/agentConfig/tool/ToolConfigModal.tsx
index a476a568a..53c6d3f03 100644
--- a/frontend/app/[locale]/agents/components/agentConfig/tool/ToolConfigModal.tsx
+++ b/frontend/app/[locale]/agents/components/agentConfig/tool/ToolConfigModal.tsx
@@ -27,7 +27,7 @@ import HaotianKnowledgeSelectorModal, {
HaotianKnowledgeSet,
} from "@/components/tool-config/HaotianKnowledgeSelectorModal";
import { useConfig } from "@/hooks/useConfig";
-import { useKnowledgeBasesForToolConfig } from "@/hooks/useKnowledgeBaseSelector";
+import { useKnowledgeBasesForToolConfig, knowledgeBaseKeys } from "@/hooks/useKnowledgeBaseSelector";
import {
useKnowledgeBaseConfigChangeHandler,
ToolKbType,
@@ -1101,6 +1101,15 @@ export default function ToolConfigModal({
setTestPanelVisible(false);
// Reset user modification tracking state for datamate URL
setHasUserModifiedDatamateUrl(false);
+
+ // Clear knowledge base cache to ensure fresh data on next open
+ // This is especially important after saving tool config with KB changes
+ if (toolKbType) {
+ queryClient.invalidateQueries({
+ queryKey: knowledgeBaseKeys.list(toolKbType),
+ });
+ }
+
onCancel();
};
diff --git a/frontend/app/[locale]/agents/components/agentConfig/tool/ToolTestPanel.tsx b/frontend/app/[locale]/agents/components/agentConfig/tool/ToolTestPanel.tsx
index b6af20594..6c12f7132 100644
--- a/frontend/app/[locale]/agents/components/agentConfig/tool/ToolTestPanel.tsx
+++ b/frontend/app/[locale]/agents/components/agentConfig/tool/ToolTestPanel.tsx
@@ -581,9 +581,8 @@ export default function ToolTestPanel({
) : (
// Parsed parameters mode
- Object.keys(parameterValues).length > 0 && (
- <>
- {Object.keys(parameterValues).map((paramName) => {
+ <>
+ {Object.keys(parameterValues).map((paramName) => {
const paramInfo = parsedInputs[paramName];
const description =
paramInfo &&
@@ -784,7 +783,6 @@ export default function ToolTestPanel({
);
})}
- )
)}
diff --git a/frontend/app/[locale]/agents/components/agentInfo/AgentGenerateDetail.tsx b/frontend/app/[locale]/agents/components/agentInfo/AgentGenerateDetail.tsx
index 1dd8422fa..c7c238a83 100644
--- a/frontend/app/[locale]/agents/components/agentInfo/AgentGenerateDetail.tsx
+++ b/frontend/app/[locale]/agents/components/agentInfo/AgentGenerateDetail.tsx
@@ -755,18 +755,32 @@ export default function AgentGenerateDetail({
// On same agent: proceed with updating form values and store
// After generation completes, get all form values and update parent component state
- // Use generatedContent state as fallback to ensure we get the streamed data
+ // CRITICAL: Read from localStorage cache FIRST as the primary source, because:
+ // 1. localStorage is written synchronously with each streaming update (always up-to-date)
+ // 2. generatedContent React state may have closure staleness issues
+ // 3. form.getFieldsValue() depends on React state updates which may lag
const formValues = form.getFieldsValue();
+
+ // Read cached values as primary source (always fresh due to sync writes)
+ const cached = getAgentGenerationCache(generationAgentId);
+ const cachedDutyPrompt = cached?.dutyPrompt || "";
+ const cachedConstraintPrompt = cached?.constraintPrompt || "";
+ const cachedFewShotsPrompt = cached?.fewShotsPrompt || "";
+ const cachedAgentName = cached?.agentName || "";
+ const cachedAgentDisplayName = cached?.agentDisplayName || "";
+ const cachedAgentDescription = cached?.agentDescription || "";
+
const profileUpdates: AgentProfileInfo = {
- name: generatedContent.agentName || formValues.agentName,
- display_name: generatedContent.agentDisplayName || formValues.agentDisplayName,
+ // Use cached values as primary source, fallback to form values
+ name: cachedAgentName || generatedContent.agentName || formValues.agentName,
+ display_name: cachedAgentDisplayName || generatedContent.agentDisplayName || formValues.agentDisplayName,
author: formValues.agentAuthor,
model: formValues.mainAgentModel,
max_step: formValues.mainAgentMaxStep,
- description: generatedContent.agentDescription || formValues.agentDescription,
- duty_prompt: generatedContent.dutyPrompt || formValues.dutyPrompt,
- constraint_prompt: generatedContent.constraintPrompt || formValues.constraintPrompt,
- few_shots_prompt: generatedContent.fewShotsPrompt || formValues.fewShotsPrompt,
+ description: cachedAgentDescription || generatedContent.agentDescription || formValues.agentDescription,
+ duty_prompt: cachedDutyPrompt || generatedContent.dutyPrompt || formValues.dutyPrompt,
+ constraint_prompt: cachedConstraintPrompt || generatedContent.constraintPrompt || formValues.constraintPrompt,
+ few_shots_prompt: cachedFewShotsPrompt || generatedContent.fewShotsPrompt || formValues.fewShotsPrompt,
ingroup_permission: formValues.ingroup_permission || "READ_ONLY",
provide_run_summary: formValues.provideRunSummary || false,
};
diff --git a/frontend/app/[locale]/agents/components/agentInfo/DebugConfig.tsx b/frontend/app/[locale]/agents/components/agentInfo/DebugConfig.tsx
index fb1679b0b..b01506c80 100644
--- a/frontend/app/[locale]/agents/components/agentInfo/DebugConfig.tsx
+++ b/frontend/app/[locale]/agents/components/agentInfo/DebugConfig.tsx
@@ -381,7 +381,10 @@ export default function DebugConfig({ agentId }: DebugConfigProps) {
.filter(msg => msg.isComplete !== false) // Only pass completed messages
.map(msg => ({
role: msg.role,
- content: msg.content
+ content:
+ msg.role === MESSAGE_ROLES.ASSISTANT
+ ? msg.finalAnswer?.trim() || msg.content || ""
+ : msg.content || "",
})),
is_debug: true, // Add debug mode flag
agent_id: agentIdValue, // Use the properly parsed agent_id
diff --git a/frontend/app/[locale]/chat/components/chatInput.tsx b/frontend/app/[locale]/chat/components/chatInput.tsx
index 64891c5d9..8de0d17eb 100644
--- a/frontend/app/[locale]/chat/components/chatInput.tsx
+++ b/frontend/app/[locale]/chat/components/chatInput.tsx
@@ -158,7 +158,7 @@ export function ChatInput({
const { t } = useTranslation("common");
// Use the configuration hook to get the application avatar
- const { appConfig, getAppAvatarUrl } = useConfig();
+ const { appConfig, getAppAvatarUrl, modelConfig } = useConfig();
const avatarUrl = getAppAvatarUrl(40); // Avatar size is 40 in initial mode
// When the recording status changes, notify the parent component
@@ -407,6 +407,31 @@ export function ChatInput({
ws.onopen = () => {
setIsRecording(true);
setRecordingStatus("recording");
+
+ // Send STT config to backend
+ const sttConfig: Record = {
+ language: "zh",
+ };
+
+ // Check if using Volcano Engine STT
+ const isVolcSTT = modelConfig?.stt?.modelFactory === "volcengine";
+
+ if (isVolcSTT) {
+ // Volcano Engine STT requires modelFactory, modelAppid, and accessToken
+ sttConfig.model_factory = "volcengine";
+ sttConfig.model_appid = modelConfig?.stt?.modelAppid || "";
+ sttConfig.access_token = modelConfig?.stt?.accessToken || "";
+ sttConfig.base_url = modelConfig?.stt?.apiConfig?.modelUrl || "wss://openspeech.bytedance.com/api/v3/sauc/bigmodel";
+ } else {
+ // Ali/DashScope STT uses api_key and model name
+ sttConfig.api_key = modelConfig?.stt?.apiConfig?.apiKey || "sk-no-api-key";
+ sttConfig.model = modelConfig?.stt?.modelName || "qwen3-asr-flash-realtime";
+ sttConfig.base_url = modelConfig?.stt?.apiConfig?.modelUrl || "";
+ }
+
+ const configJson = JSON.stringify(sttConfig);
+ ws.send(configJson);
+
try {
mediaRecorder.start(250);
} catch (error) {
@@ -421,16 +446,27 @@ export function ChatInput({
try {
const response = JSON.parse(event.data);
+ // Handle server ready signal
+ if (response.status === "ready") {
+ return;
+ }
+
+ // Handle transcription results - display all results for real-time feedback
if (response.result && response.result.text) {
+ // Ali STT format with nested result
onInputChange(response.result.text);
} else if (response.text) {
+ // Direct text format (阿里/火山)
onInputChange(response.text);
- } else if (response.status === "ready") {
} else if (response.error) {
log.error("❌ STT service error:", response.error);
setRecordingStatus("error");
setIsRecording(false);
cleanup();
+ } else if (response.vad === "started") {
+ // VAD detected speech start
+ } else if (response.vad === "stopped") {
+ // VAD detected speech stop
}
} catch (error) {
log.error("⚠️ Failed to parse STT response:", error);
diff --git a/frontend/app/[locale]/chat/streaming/chatStreamFinalMessage.tsx b/frontend/app/[locale]/chat/streaming/chatStreamFinalMessage.tsx
index 25cb8d0d6..e5809c435 100644
--- a/frontend/app/[locale]/chat/streaming/chatStreamFinalMessage.tsx
+++ b/frontend/app/[locale]/chat/streaming/chatStreamFinalMessage.tsx
@@ -35,6 +35,7 @@ import { Tooltip, TooltipProvider } from "@/components/ui/tooltip";
import { ChatMessageType, MaxStepsInfo } from "@/types/chat";
import { chatConfig, Opinion } from "@/const/chatConfig";
import { conversationService } from "@/services/conversationService";
+import { useConfig } from "@/hooks/useConfig";
import { copyToClipboard } from "@/lib/clipboard";
import log from "@/lib/logger";
import { AttachmentItem } from "@/types/chat";
@@ -90,6 +91,10 @@ function ChatStreamFinalMessageInner({
typeof conversationService.tts.createTTSService
> | null>(null);
+ // Get TTS model config for model selection
+ const { modelConfig } = useConfig();
+ const ttsModelName = modelConfig?.tts?.modelName;
+
// Animation effect - message enters and fades in
useEffect(() => {
const timer = setTimeout(() => {
@@ -194,9 +199,20 @@ function ChatStreamFinalMessageInner({
}
try {
- await ttsServiceRef.current.playAudio(contentToPlay, (status) => {
- setTtsStatus(status);
- });
+ await ttsServiceRef.current.playAudio(
+ contentToPlay,
+ (status) => {
+ setTtsStatus(status);
+ },
+ {
+ model_name: ttsModelName,
+ model_factory: modelConfig?.tts?.modelFactory,
+ api_key: modelConfig?.tts?.apiConfig?.apiKey,
+ model_appid: modelConfig?.tts?.modelAppid,
+ access_token: modelConfig?.tts?.accessToken,
+ base_url: modelConfig?.tts?.apiConfig?.modelUrl
+ }
+ );
} catch (error) {
setTtsStatus(chatConfig.ttsStatus.ERROR);
setTimeout(() => setTtsStatus(chatConfig.ttsStatus.IDLE), 2000);
diff --git a/frontend/app/[locale]/knowledges/KnowledgeBaseConfiguration.tsx b/frontend/app/[locale]/knowledges/KnowledgeBaseConfiguration.tsx
index a5e7d52d1..b3ed52f0c 100644
--- a/frontend/app/[locale]/knowledges/KnowledgeBaseConfiguration.tsx
+++ b/frontend/app/[locale]/knowledges/KnowledgeBaseConfiguration.tsx
@@ -10,7 +10,7 @@ import {
} from "react";
import { useTranslation } from "react-i18next";
-import { App, Modal, Row, Col, theme, Button, Input, Form } from "antd";
+import { App, Modal, Row, Col, theme, Button, Input } from "antd";
import {
ExclamationCircleFilled,
WarningFilled,
@@ -160,6 +160,7 @@ function DataConfig({ isActive }: DataConfigProps) {
createKnowledgeBase,
deleteKnowledgeBase,
setActiveKnowledgeBase,
+ updateKnowledgeBase,
hasKnowledgeBaseModelMismatch,
refreshKnowledgeBaseData,
refreshKnowledgeBaseDataWithDataMate,
@@ -900,7 +901,8 @@ function DataConfig({ isActive }: DataConfigProps) {
containerHeight={SETUP_PAGE_CONTAINER.MAIN_CONTENT_HEIGHT}
onKnowledgeBaseChange={() => {}} // No need to trigger repeatedly here as it's already handled in handleKnowledgeBaseClick
onKnowledgeBaseUpdate={(updatedKnowledgeBase) => {
- // Update active knowledge base in context when it's updated
+ // Update knowledge base in list and active knowledge base
+ updateKnowledgeBase(updatedKnowledgeBase);
if (kbState.activeKnowledgeBase && kbState.activeKnowledgeBase.id === updatedKnowledgeBase.id) {
setActiveKnowledgeBase(updatedKnowledgeBase);
}
@@ -991,6 +993,24 @@ function DataConfig({ isActive }: DataConfigProps) {
knowledgeBasePollingService.triggerKnowledgeBaseListUpdate(true);
}}
permission={kbState.activeKnowledgeBase?.permission}
+ summaryFrequency={kbState.activeKnowledgeBase?.summaryFrequency}
+ onSummaryFrequencyChange={(frequency) => {
+ if (kbState.activeKnowledgeBase) {
+ knowledgeBaseService.updateSummaryFrequency(
+ kbState.activeKnowledgeBase.id,
+ frequency
+ ).then(() => {
+ const updatedKB: KnowledgeBase = {
+ ...kbState.activeKnowledgeBase!,
+ summaryFrequency: frequency
+ };
+ updateKnowledgeBase(updatedKB);
+ setActiveKnowledgeBase(updatedKB);
+ }).catch((error) => {
+ log.error("Failed to update summary frequency:", error);
+ });
+ }
+ }}
// Upload related props
isDragging={uiState.isDragging}
onDragOver={handleDragOver}
@@ -1074,26 +1094,26 @@ function DataConfig({ isActive }: DataConfigProps) {
{t("knowledgeBase.modal.dataMateConfig.description")}
-
+
+
+ setDataMateUrl(e.target.value)}
+ onBlur={() => {
+ // Validate on blur
+ const error = validateDataMateUrl(dataMateUrl);
+ setDataMateUrlError(error);
+ }}
+ placeholder={t(
+ "knowledgeBase.modal.dataMateConfig.urlPlaceholder"
+ )}
+ />
+ {dataMateUrlError && (
+ {dataMateUrlError}
+ )}
+
diff --git a/frontend/app/[locale]/knowledges/components/document/DocumentList.tsx b/frontend/app/[locale]/knowledges/components/document/DocumentList.tsx
index 06940d9f0..023f2205a 100644
--- a/frontend/app/[locale]/knowledges/components/document/DocumentList.tsx
+++ b/frontend/app/[locale]/knowledges/components/document/DocumentList.tsx
@@ -21,6 +21,7 @@ import {
LAYOUT,
DOCUMENT_STATUS,
} from "@/const/knowledgeBase";
+import { SUMMARY_FREQUENCY_OPTIONS_API, FrequencyOption } from "@/const/scheduler";
import knowledgeBaseService from "@/services/knowledgeBaseService";
import { modelService } from "@/services/modelService";
import { getTenantDefaultGroupId } from "@/services/groupService";
@@ -80,6 +81,10 @@ interface DocumentListProps {
selectedEmbeddingModel?: string;
onEmbeddingModelChange?: (value: string) => void;
permission?: string; // User's permission for this knowledge base (READ_ONLY, EDIT, etc.)
+
+ // Auto-summary frequency
+ summaryFrequency?: string | null;
+ onSummaryFrequencyChange?: (frequency: string | null) => void;
// Upload related props
isDragging?: boolean;
@@ -123,6 +128,10 @@ const DocumentListContainer = forwardRef(
selectedEmbeddingModel,
onEmbeddingModelChange,
permission,
+
+ // Auto-summary frequency
+ summaryFrequency,
+ onSummaryFrequencyChange,
// Upload related props
isDragging = false,
@@ -227,13 +236,14 @@ const DocumentListContainer = forwardRef(
const [showDetail, setShowDetail] = React.useState(false);
const [showChunk, setShowChunk] = React.useState(false);
const [summary, setSummary] = useState("");
- const [isSummarizing, setIsSummarizing] = useState(false);
- const [isEditing, setIsEditing] = useState(false);
- const [isSaving, setIsSaving] = useState(false);
- const [selectedModel, setSelectedModel] = useState(0);
- const [availableModels, setAvailableModels] = useState([]);
- const [isLoadingModels, setIsLoadingModels] = useState(false);
- const { t } = useTranslation();
+const [isSummarizing, setIsSummarizing] = useState(false);
+ const [isEditing, setIsEditing] = useState(false);
+ const [isSaving, setIsSaving] = useState(false);
+ const [selectedModel, setSelectedModel] = useState(0);
+ const [availableModels, setAvailableModels] = useState([]);
+ const [isLoadingModels, setIsLoadingModels] = useState(false);
+ const [frequencyOptions, setFrequencyOptions] = useState([]);
+ const { t } = useTranslation();
const isDataMate = (knowledgeBaseSource || "").toLowerCase() === "datamate";
// Determine if user has read-only permission
@@ -304,10 +314,30 @@ const DocumentListContainer = forwardRef(
// Check if group select should be disabled (when permission is PRIVATE)
const isGroupSelectDisabled = ingroupPermission === "PRIVATE";
- // Load available models when showing detail
- useEffect(() => {
- const loadModels = async () => {
- if (showDetail && availableModels.length === 0) {
+ // Load frequency options from backend API
+ useEffect(() => {
+ const loadFrequencyOptions = async () => {
+ if (showDetail && frequencyOptions.length === 0) {
+ try {
+ const response = await fetch(SUMMARY_FREQUENCY_OPTIONS_API);
+ const data = await response.json();
+ setFrequencyOptions(data.options || []);
+ } catch (error) {
+ log.error("Failed to load frequency options:", error);
+ // Fallback to default options if API fails
+ setFrequencyOptions([
+ { value: "disabled", label: t("knowledgeBase.tag.autoSummary.off") },
+ ]);
+ }
+ }
+ };
+ loadFrequencyOptions();
+ }, [showDetail, frequencyOptions.length, t]);
+
+ // Load available models when showing detail
+ useEffect(() => {
+ const loadModels = async () => {
+ if (showDetail && availableModels.length === 0) {
setIsLoadingModels(true);
try {
const models = await modelService.getLLMModels();
@@ -625,7 +655,7 @@ const DocumentListContainer = forwardRef(
/>
) : showDetail ? (
-
+
{t("document.summary.title")}
@@ -649,6 +679,29 @@ const DocumentListContainer = forwardRef(
}))}
/>
+
+
+ {t("knowledgeBase.tag.autoSummary.label")}
+
+
- {/* Model tag - only show when model is not "unknown" */}
+{/* Model tag - only show when model is not "unknown" */}
{kb.embeddingModel !== "unknown" && (
(
fileList,
onChange: handleChange,
customRequest: handleCustomRequest,
- accept: ".pdf,.docx,.pptx,.xlsx,.md,.txt,.csv",
+ accept: ".pdf,.docx,.pptx,.xlsx,.md,.txt,.csv,.json,.epub,.xml,.html",
showUploadList: true,
disabled: disabled,
progress: {
diff --git a/frontend/app/[locale]/knowledges/contexts/KnowledgeBaseContext.tsx b/frontend/app/[locale]/knowledges/contexts/KnowledgeBaseContext.tsx
index 5985c4b08..3c5946bd4 100644
--- a/frontend/app/[locale]/knowledges/contexts/KnowledgeBaseContext.tsx
+++ b/frontend/app/[locale]/knowledges/contexts/KnowledgeBaseContext.tsx
@@ -71,6 +71,13 @@ const knowledgeBaseReducer = (
...state,
knowledgeBases: [...state.knowledgeBases, action.payload],
};
+ case KNOWLEDGE_BASE_ACTION_TYPES.UPDATE_KNOWLEDGE_BASE:
+ return {
+ ...state,
+ knowledgeBases: state.knowledgeBases.map((kb) =>
+ kb.id === action.payload.id ? action.payload : kb
+ ),
+ };
case KNOWLEDGE_BASE_ACTION_TYPES.LOADING:
return {
...state,
@@ -115,6 +122,7 @@ export const KnowledgeBaseContext = createContext<{
deleteKnowledgeBase: (id: string) => Promise;
selectKnowledgeBase: (id: string) => void;
setActiveKnowledgeBase: (kb: KnowledgeBase | null) => void;
+ updateKnowledgeBase: (kb: KnowledgeBase) => void;
isKnowledgeBaseSelectable: (kb: KnowledgeBase) => boolean;
hasKnowledgeBaseModelMismatch: (kb: KnowledgeBase) => boolean;
refreshKnowledgeBaseData: (forceRefresh?: boolean) => Promise;
@@ -135,6 +143,7 @@ export const KnowledgeBaseContext = createContext<{
deleteKnowledgeBase: async () => false,
selectKnowledgeBase: () => {},
setActiveKnowledgeBase: () => {},
+ updateKnowledgeBase: () => {},
isKnowledgeBaseSelectable: () => false,
hasKnowledgeBaseModelMismatch: () => false,
refreshKnowledgeBaseData: async () => {},
@@ -303,6 +312,11 @@ export const KnowledgeBaseProvider: React.FC = ({
dispatch({ type: KNOWLEDGE_BASE_ACTION_TYPES.SET_ACTIVE, payload: kb });
}, []);
+ // Update knowledge base in list - memoized with useCallback
+ const updateKnowledgeBase = useCallback((kb: KnowledgeBase) => {
+ dispatch({ type: KNOWLEDGE_BASE_ACTION_TYPES.UPDATE_KNOWLEDGE_BASE, payload: kb });
+ }, []);
+
// Create knowledge base - memoized with useCallback
const createKnowledgeBase = useCallback(
async (
@@ -596,6 +610,7 @@ export const KnowledgeBaseProvider: React.FC = ({
deleteKnowledgeBase,
selectKnowledgeBase,
setActiveKnowledgeBase,
+ updateKnowledgeBase,
isKnowledgeBaseSelectable,
hasKnowledgeBaseModelMismatch,
refreshKnowledgeBaseData,
@@ -603,12 +618,15 @@ export const KnowledgeBaseProvider: React.FC = ({
}),
[
state,
+ dispatch,
fetchKnowledgeBases,
createKnowledgeBase,
deleteKnowledgeBase,
selectKnowledgeBase,
setActiveKnowledgeBase,
+ updateKnowledgeBase,
isKnowledgeBaseSelectable,
+ hasKnowledgeBaseModelMismatch,
refreshKnowledgeBaseData,
refreshKnowledgeBaseDataWithDataMate,
]
diff --git a/frontend/app/[locale]/models/components/model/ModelAddDialog.tsx b/frontend/app/[locale]/models/components/model/ModelAddDialog.tsx
index 7cbf5192e..11391c133 100644
--- a/frontend/app/[locale]/models/components/model/ModelAddDialog.tsx
+++ b/frontend/app/[locale]/models/components/model/ModelAddDialog.tsx
@@ -13,7 +13,7 @@ import {
import { useConfig } from "@/hooks/useConfig";
import { getConnectivityMeta, ConnectivityStatusType } from "@/lib/utils";
import { modelService } from "@/services/modelService";
-import { ModelType, SingleModelConfig } from "@/types/modelConfig";
+import { ModelType, SingleModelConfig, STTModelConfig } from "@/types/modelConfig";
import { MODEL_TYPES, PROVIDER_LINKS } from "@/const/modelConfig";
import { useSiliconModelList } from "@/hooks/model/useSiliconModelList";
import { useDashscopeModelList } from "@/hooks/model/useDashscopeModelList";
@@ -60,6 +60,10 @@ const DEFAULT_FORM_STATE = {
number,
],
chunkingBatchSize: "10",
+ // STT specific fields
+ sttProvider: "dashscope", // dashscope or volcengine
+ modelAppid: "",
+ accessToken: "",
};
// Connectivity status type comes from utils
@@ -314,6 +318,13 @@ export const ModelAddDialog = ({
}));
}, [isOpen, defaultProvider, defaultIsBatchImport]);
+ // Switch to LLM when batch import is enabled while STT/TTS is selected
+ useEffect(() => {
+ if (form.isBatchImport && (form.type === MODEL_TYPES.STT || form.type === MODEL_TYPES.TTS)) {
+ handleFormChange("type", MODEL_TYPES.LLM);
+ }
+ }, [form.isBatchImport]);
+
const parseModelName = (name: string): string => {
if (!name) return "";
const parts = name.split("/");
@@ -421,7 +432,24 @@ export const ModelAddDialog = ({
);
}
if (form.type === MODEL_TYPES.RERANK) {
- return form.name.trim() !== "" && form.url.trim() !== "";
+ return (
+ form.name.trim() !== "" &&
+ form.url.trim() !== "" &&
+ form.apiKey.trim() !== ""
+ );
+ }
+ if (form.type === MODEL_TYPES.STT) {
+ // For STT models, validate based on provider type
+ if (form.sttProvider === "volcengine") {
+ // Volcano Engine requires appid and access_token
+ return (
+ form.modelAppid.trim() !== "" &&
+ form.accessToken.trim() !== ""
+ );
+ } else {
+ // DashScope requires API Key and model name
+ return form.apiKey.trim() !== "" && form.name.trim() !== "";
+ }
}
return (
form.name.trim() !== "" &&
@@ -449,49 +477,66 @@ export const ModelAddDialog = ({
? (MODEL_TYPES.MULTI_EMBEDDING as ModelType)
: form.type;
- const config = {
- modelName: form.name,
- modelType: modelType,
- baseUrl: form.url,
- apiKey: form.apiKey.trim() === "" ? "sk-no-api-key" : form.apiKey,
- maxTokens:
- form.type === MODEL_TYPES.EMBEDDING
- ? parseInt(form.vectorDimension)
- : form.type === MODEL_TYPES.RERANK
- ? 0
- : parseInt(form.maxTokens),
- embeddingDim:
- form.type === MODEL_TYPES.EMBEDDING
- ? parseInt(form.vectorDimension)
- : undefined,
- };
+ let connectivity = false;
+
+ // Use manage interface if tenantId is provided
+ if (tenantId) {
+ connectivity = await modelService.checkManageTenantModelConnectivity(
+ tenantId,
+ form.displayName || form.name
+ );
+ } else {
+ // For STT models, build the appropriate config based on provider
+ if (form.type === MODEL_TYPES.STT) {
+ const sttConfig: any = {
+ modelType: modelType,
+ };
+
+ if (form.sttProvider === "volcengine") {
+ sttConfig.modelFactory = "volcengine";
+ sttConfig.modelAppid = form.modelAppid.trim();
+ sttConfig.accessToken = form.accessToken.trim();
+ } else {
+ sttConfig.apiKey = form.apiKey.trim() === "" ? "sk-no-api-key" : form.apiKey;
+ sttConfig.modelFactory = "dashscope";
+ sttConfig.modelName = form.name;
+ sttConfig.baseUrl = form.url;
+ }
+
+ const result = await modelService.verifyModelConfigConnectivity(sttConfig);
+ connectivity = result.connectivity;
+ } else {
+ const config = {
+ modelName: form.name,
+ modelType: modelType,
+ baseUrl: form.url,
+ apiKey: form.apiKey.trim() === "" ? "sk-no-api-key" : form.apiKey,
+ maxTokens:
+ form.type === MODEL_TYPES.EMBEDDING
+ ? parseInt(form.vectorDimension)
+ : parseInt(form.maxTokens),
+ embeddingDim:
+ form.type === MODEL_TYPES.EMBEDDING
+ ? parseInt(form.vectorDimension)
+ : undefined,
+ };
- const result = await modelService.verifyModelConfigConnectivity(config);
+ const result = await modelService.verifyModelConfigConnectivity(config);
+ connectivity = result.connectivity;
+ }
+ }
// Set connectivity status
- if (result.connectivity) {
+ if (connectivity) {
setConnectivityStatus({
status: "available",
message: t("model.dialog.connectivity.status.available"),
});
} else {
- // Set status to unavailable
setConnectivityStatus({
status: "unavailable",
message: t("model.dialog.connectivity.status.unavailable"),
});
- // Show detailed error message using internationalized component (same as add failure)
- if (result.error) {
- const translatedError = translateError(result.error, t);
- // Ensure translatedError is a valid string, fallback to original error if needed
- const errorText =
- translatedError && translatedError.length > 0
- ? translatedError
- : result.error || "Unknown error";
- message.error(
- t("model.dialog.error.connectivityFailed", { error: errorText })
- );
- }
}
} catch (error) {
const errorMessage =
@@ -500,15 +545,11 @@ export const ModelAddDialog = ({
status: "unavailable",
message: t("model.dialog.connectivity.status.unavailable"),
});
- // Show error message using internationalized component (same as add failure)
- const translatedError = translateError(
- errorMessage || t("model.dialog.connectivity.status.unavailable"),
- t
- );
- // Ensure translatedError is a valid string
- const errorText = translatedError
- ? translatedError
- : errorMessage || t("model.dialog.connectivity.status.unavailable");
+ const translatedError = translateError(errorMessage, t);
+ const errorText =
+ translatedError && translatedError.length > 0
+ ? translatedError
+ : errorMessage;
message.error(
t("model.dialog.error.connectivityFailed", { error: errorText })
);
@@ -641,16 +682,15 @@ export const ModelAddDialog = ({
let maxTokensValue = parseInt(form.maxTokens);
if (
form.type === MODEL_TYPES.EMBEDDING ||
- form.type === MODEL_TYPES.MULTI_EMBEDDING ||
- form.type === MODEL_TYPES.RERANK
+ form.type === MODEL_TYPES.MULTI_EMBEDDING
) {
- // For embedding/rerank models, the backend does not rely on max_tokens in the same way as LLM.
+ // For embedding models, use the vector dimension as maxTokens
maxTokensValue = 0;
}
// Add to the backend service - use manage interface if tenantId is provided
if (tenantId) {
- await modelService.createManageTenantModel({
+ const modelParams: any = {
tenantId,
name: form.name,
type: modelType,
@@ -658,37 +698,56 @@ export const ModelAddDialog = ({
apiKey: form.apiKey.trim() === "" ? "sk-no-api-key" : form.apiKey,
maxTokens: maxTokensValue,
displayName: form.displayName || form.name,
- expectedChunkSize: isEmbeddingModel
- ? form.chunkSizeRange[0]
- : undefined,
- maximumChunkSize: isEmbeddingModel
- ? form.chunkSizeRange[1]
- : undefined,
- chunkingBatchSize: isEmbeddingModel
- ? parseInt(form.chunkingBatchSize) || 10
- : undefined,
- });
+ };
+
+ // Add STT specific fields
+ if (form.type === MODEL_TYPES.STT) {
+ modelParams.modelFactory = form.sttProvider === "volcengine" ? "volcengine" : "dashscope";
+ if (form.sttProvider === "volcengine") {
+ modelParams.modelAppid = form.modelAppid;
+ modelParams.accessToken = form.accessToken;
+ }
+ }
+
+ // Add embedding specific fields
+ if (isEmbeddingModel) {
+ modelParams.expectedChunkSize = form.chunkSizeRange[0];
+ modelParams.maximumChunkSize = form.chunkSizeRange[1];
+ modelParams.chunkingBatchSize = parseInt(form.chunkingBatchSize) || 10;
+ }
+
+ await modelService.createManageTenantModel(modelParams);
} else {
- await modelService.addCustomModel({
+ const modelParams: any = {
name: form.name,
type: modelType,
url: form.url,
apiKey: form.apiKey.trim() === "" ? "sk-no-api-key" : form.apiKey,
maxTokens: maxTokensValue,
displayName: form.displayName || form.name,
- // Send chunk size range for embedding models
- ...(isEmbeddingModel
- ? {
- expectedChunkSize: form.chunkSizeRange[0],
- maximumChunkSize: form.chunkSizeRange[1],
- chunkingBatchSize: parseInt(form.chunkingBatchSize) || 10,
- }
- : {}),
- });
+ };
+
+ // Add STT specific fields
+ if (form.type === MODEL_TYPES.STT) {
+ modelParams.modelFactory = form.sttProvider === "volcengine" ? "volcengine" : "dashscope";
+ if (form.sttProvider === "volcengine") {
+ modelParams.modelAppid = form.modelAppid;
+ modelParams.accessToken = form.accessToken;
+ }
+ }
+
+ // Add embedding specific fields
+ if (isEmbeddingModel) {
+ modelParams.expectedChunkSize = form.chunkSizeRange[0];
+ modelParams.maximumChunkSize = form.chunkSizeRange[1];
+ modelParams.chunkingBatchSize = parseInt(form.chunkingBatchSize) || 10;
+ }
+
+ await modelService.addCustomModel(modelParams);
}
// Create the model configuration object
- const modelConfig: SingleModelConfig = {
+ let modelConfig: SingleModelConfig | STTModelConfig = {
modelName: form.name,
displayName: form.displayName || form.name,
apiConfig: {
@@ -697,6 +756,15 @@ export const ModelAddDialog = ({
},
};
+ // Add STT specific fields to config
+ if (form.type === MODEL_TYPES.STT) {
+ (modelConfig as STTModelConfig).modelFactory = form.sttProvider === "volcengine" ? "volcengine" : "dashscope";
+ if (form.sttProvider === "volcengine") {
+ (modelConfig as STTModelConfig).modelAppid = form.modelAppid;
+ (modelConfig as STTModelConfig).accessToken = form.accessToken;
+ }
+ }
+
// Add the dimension field for embedding models
if (form.type === MODEL_TYPES.EMBEDDING) {
modelConfig.dimension = parseInt(form.vectorDimension);
@@ -761,7 +829,7 @@ export const ModelAddDialog = ({
};
const isEmbeddingModel = form.type === MODEL_TYPES.EMBEDDING;
- const isRerankModel = form.type === MODEL_TYPES.RERANK;
+ const isSTTModel = form.type === MODEL_TYPES.STT;
return (
)}
+ {/* API Key (shown only when batch import is enabled) */}
+ {form.isBatchImport && (
+
+
+ handleFormChange("apiKey", e.target.value)}
+ autoComplete="new-password"
+ />
+
+ )}
+
{/* Model Type */}
-
- 💬
-
- {t("auth.inviteCodeHint.step2")}
-
- {t("auth.inviteCodeHint.contributionWallLink")}
-
- {t("auth.inviteCodeHint.step2Action")}
-
- {getDialogDescription()}
+
+ {modelsLoading ? (
+
+
+ {t("knowledgeBase.embeddingModel.noModelsAvailable")}
+
+
+ {t("knowledgeBase.embeddingModel.noModelsAvailableDesc")}
+
+
+ ) : (
+
+
+
+ )}
+
+ {kbIdsToUpdate.length > 1 && (
+
+ {t("knowledgeBase.embeddingModel.batchUpdateNote", {
+ count: kbIdsToUpdate.length,
+ })}
+
+ )}
+
+
+ );
+}
diff --git a/frontend/components/tool-config/KnowledgeBaseSelectorModal.tsx b/frontend/components/tool-config/KnowledgeBaseSelectorModal.tsx
index 017b0afdf..9e30f323a 100644
--- a/frontend/components/tool-config/KnowledgeBaseSelectorModal.tsx
+++ b/frontend/components/tool-config/KnowledgeBaseSelectorModal.tsx
@@ -21,6 +21,10 @@ import {
import { KnowledgeBase } from "@/types/knowledgeBase";
import { ToolKbType } from "@/hooks/useKnowledgeBaseConfigChangeHandler";
import { KB_LAYOUT, KB_TAG_VARIANTS } from "@/const/knowledgeBaseLayout";
+import { useModelList } from "@/hooks/model/useModelList";
+import knowledgeBaseService from "@/services/knowledgeBaseService";
+import log from "@/lib/logger";
+import EmbeddingModelConfigDialog from "./EmbeddingModelConfigDialog";
interface KnowledgeBaseSelectorProps {
isOpen: boolean;
@@ -102,6 +106,22 @@ export default function KnowledgeBaseSelectorModal({
difyConfig,
}: KnowledgeBaseSelectorModalProps) {
const { t } = useTranslation("common");
+ const { data: allModels = [] } = useModelList();
+
+ // Memoized lookup function for model display names using the fetched model list
+ const resolveModelDisplayName = useMemo(() => {
+ const modelLookup = new Map();
+ allModels.forEach((model) => {
+ const displayName = model.displayName || model.name || "";
+ if (model.displayName) modelLookup.set(model.displayName, displayName);
+ if (model.name) modelLookup.set(model.name, displayName);
+ if (model.id) modelLookup.set(String(model.id), displayName);
+ });
+ return (modelId: string) => modelLookup.get(modelId) || modelId;
+ }, [allModels]);
+
+ // Use the internal model lookup to get display names
+ const effectiveGetModelDisplayName = resolveModelDisplayName;
// Selection state (kept for internal logic but not displayed)
const [tempSelectedIds, setTempSelectedIds] = useState([]);
@@ -121,6 +141,20 @@ export default function KnowledgeBaseSelectorModal({
newKBName: string;
} | null>(null);
+ // Embedding model config dialog state
+ const [embeddingModelDialogOpen, setEmbeddingModelDialogOpen] = useState(false);
+ const [embeddingModelDialogData, setEmbeddingModelDialogData] = useState<{
+ indexName: string;
+ knowledgeName: string;
+ } | null>(null);
+ const [embeddingModelDialogMismatch, setEmbeddingModelDialogMismatch] = useState(false);
+ const [configuringKbIds, setConfiguringKbIds] = useState>(new Set());
+
+ // Track configured models for display - use model display name instead of ID
+ const [configuredModels, setConfiguredModels] = useState>(new Map());
+ // Track index names of KBs that have been configured (so they won't be checked again)
+ const [configuredKbIndexNames, setConfiguredKbIndexNames] = useState>(new Set());
+
// Initialize selection state when modal opens
useEffect(() => {
if (isOpen) {
@@ -128,6 +162,11 @@ export default function KnowledgeBaseSelectorModal({
setSearchKeyword("");
setSelectedSources([]);
setSelectedModels([]);
+ setEmbeddingModelDialogOpen(false);
+ setEmbeddingModelDialogData(null);
+ setEmbeddingModelDialogMismatch(false);
+ setConfiguringKbIds(new Set());
+ setConfiguredModels(new Map());
}
}, [isOpen]);
@@ -343,18 +382,143 @@ export default function KnowledgeBaseSelectorModal({
setSelectedModels([]); // Clear the model filter as well
}, []);
+ // Handle embedding model configuration complete
+ const handleEmbeddingModelConfigComplete = useCallback(
+ (indexNames: string, modelId: string, modelDisplayName?: string) => {
+ // Parse comma-separated index names
+ const indexNameList = indexNames.split(",").filter(Boolean);
+
+ // Find KBs matching the index names
+ const matchingKBs = knowledgeBases.filter((k) =>
+ indexNameList.includes(k.index_name || k.name) || tempSelectedIds.includes(k.id)
+ );
+
+ // Deduplicate - keep unique KBs
+ const seen = new Set();
+ const selectedKBs = matchingKBs.filter((kb) => {
+ if (seen.has(kb.id)) return false;
+ seen.add(kb.id);
+ return true;
+ });
+
+ // Update the configured models map with model display name for all KBs
+ if (modelDisplayName) {
+ setConfiguredModels((prev) => {
+ const newMap = new Map(prev);
+ selectedKBs.forEach((kb) => {
+ newMap.set(kb.id, modelDisplayName);
+ });
+ return newMap;
+ });
+ }
+
+ // Track these index names as configured so they won't be checked again
+ setConfiguredKbIndexNames((prev) => {
+ const newSet = new Set(prev);
+ indexNameList.forEach((idxName) => newSet.add(idxName.trim()));
+ return newSet;
+ });
+
+ // Close the embedding model dialog first
+ setEmbeddingModelDialogOpen(false);
+ setEmbeddingModelDialogData(null);
+ setEmbeddingModelDialogMismatch(false);
+ setConfiguringKbIds(new Set());
+ },
+ [knowledgeBases, tempSelectedIds]
+ );
+
// Handle confirm
- const handleConfirm = useCallback(() => {
- const selectedKnowledgeBases = knowledgeBases.filter((kb) =>
+ const handleConfirm = useCallback(async () => {
+ const selectedKBs = knowledgeBases.filter((kb) =>
tempSelectedIds.includes(kb.id)
);
- onConfirm(selectedKnowledgeBases);
+
+ // Check for model mismatch among selected nexent KBs
+ const nexentKBs = selectedKBs.filter((kb) => kb.source === "nexent");
+ const nexentModelIds = [...new Set(nexentKBs.map((kb) => kb.embeddingModel).filter((m) => m && m !== "unknown"))];
+
+ if (nexentModelIds.length > 1) {
+ // Multiple different models - show the embedding model config dialog
+ // to allow user to select a unified model
+ const firstKB = nexentKBs[0];
+ setEmbeddingModelDialogData({
+ indexName: firstKB.index_name || firstKB.name,
+ knowledgeName: `${nexentKBs.length} knowledge bases`,
+ });
+ setEmbeddingModelDialogMismatch(true);
+ setEmbeddingModelDialogOpen(true);
+ // Track all selected nexent KB index names for batch update
+ setConfiguringKbIds(new Set(nexentKBs.map((k) => k.index_name || k.name)));
+ return; // Wait for user to configure before confirming
+ }
+
+ // Collect all KBs that need embedding model configuration
+ const kbIdsNeedingConfig: string[] = [];
+ const kbNamesNeedingConfig: string[] = [];
+
+ // Check each nexent KB that needs config
+ for (const kb of selectedKBs) {
+ if (kb.source !== "nexent") {
+ continue;
+ }
+
+ const kbIndexName = kb.index_name || kb.name;
+
+ // Skip if already configured (either in current session or previously)
+ if (configuringKbIds.has(kb.id) || configuredKbIndexNames.has(kbIndexName)) {
+ continue;
+ }
+
+ try {
+ const status = await knowledgeBaseService.getEmbeddingModelStatus(kbIndexName);
+
+ if (status.needs_config) {
+ kbIdsNeedingConfig.push(kbIndexName);
+ kbNamesNeedingConfig.push(kb.name);
+ }
+ } catch (error) {
+ log.error("Failed to check embedding model status:", error);
+ // If API fails, check if the KB might be missing model_id by checking local state
+ // If embeddingModel is empty/unknown, add to list needing config
+ if (!kb.embeddingModel || kb.embeddingModel === "unknown") {
+ kbIdsNeedingConfig.push(kbIndexName);
+ kbNamesNeedingConfig.push(kb.name);
+ }
+ }
+ }
+
+ // If any KBs need configuration, show the dialog with all of them
+ if (kbIdsNeedingConfig.length > 0) {
+ const firstIndexName = kbIdsNeedingConfig[0];
+ const knowledgeBaseName = kbIdsNeedingConfig.length === 1
+ ? kbNamesNeedingConfig[0]
+ : `${kbIdsNeedingConfig.length} knowledge bases`;
+
+ setEmbeddingModelDialogData({
+ indexName: firstIndexName,
+ knowledgeName: knowledgeBaseName,
+ });
+ setEmbeddingModelDialogMismatch(false);
+ setEmbeddingModelDialogOpen(true);
+ // Track all KBs that need configuration for batch update
+ setConfiguringKbIds(new Set(kbIdsNeedingConfig));
+ return; // Wait for user to configure before confirming
+ }
+
+ // All checks passed, proceed with confirm
+ onConfirm(selectedKBs);
onClose();
- }, [knowledgeBases, tempSelectedIds, onConfirm, onClose]);
+ }, [knowledgeBases, tempSelectedIds, configuringKbIds, configuredKbIndexNames, onConfirm, onClose]);
// Handle cancel
const handleCancel = useCallback(() => {
setTempSelectedIds(selectedIds);
+ // Reset embedding model dialog state to prevent it from staying open
+ setEmbeddingModelDialogOpen(false);
+ setEmbeddingModelDialogData(null);
+ setEmbeddingModelDialogMismatch(false);
+ setConfiguringKbIds(new Set());
onClose();
}, [selectedIds, onClose]);
@@ -744,7 +908,8 @@ export default function KnowledgeBaseSelectorModal({
- {getModelDisplayName(kb.embeddingModel)}
+ {/* Use configuredModels state for updated display name, fallback to effectiveGetModelDisplayName */}
+ {configuredModels.get(kb.id) || effectiveGetModelDisplayName(kb.embeddingModel)}
{t("knowledgeBase.tag.model", {
model: "",
})}
@@ -867,6 +1032,22 @@ export default function KnowledgeBaseSelectorModal({
+
+ {/* Embedding Model Config Dialog */}
+ {
+ setEmbeddingModelDialogOpen(false);
+ setEmbeddingModelDialogData(null);
+ setEmbeddingModelDialogMismatch(false);
+ setConfiguringKbIds(new Set());
+ }}
+ onConfigComplete={handleEmbeddingModelConfigComplete}
+ />
);
}
diff --git a/frontend/components/ui/PdfViewer.tsx b/frontend/components/ui/PdfViewer.tsx
index df4226595..ea56a2b56 100644
--- a/frontend/components/ui/PdfViewer.tsx
+++ b/frontend/components/ui/PdfViewer.tsx
@@ -5,16 +5,18 @@ import { useTranslation } from 'react-i18next';
import { Document, Page, pdfjs } from 'react-pdf';
import type { PDFDocumentProxy } from 'pdfjs-dist';
import { InputNumber } from 'antd';
-import {
- ChevronLeft,
- ChevronRight,
+import {
+ ChevronLeft,
+ ChevronRight,
Plus,
Minus,
Minimize2,
Maximize2,
Menu,
- X
+ X
} from 'lucide-react';
+import { OutlineItem, PdfViewerProps, ScaleMode, ViewportAnchor } from '@/types/file';
+import { ignoreAbortError, getPageWrapperStyle } from '@/lib/filePreviewUtils';
import log from '@/lib/logger';
pdfjs.GlobalWorkerOptions.workerSrc = new URL(
@@ -22,25 +24,6 @@ pdfjs.GlobalWorkerOptions.workerSrc = new URL(
import.meta.url,
).toString();
-interface OutlineItem {
- title: string;
- dest: string | null;
- items?: OutlineItem[];
- pageNumber?: number;
-}
-
-interface PdfViewerProps {
- url: string;
- fileName: string;
-}
-
-type ScaleMode = 'fit-width' | 'fit-page' | 'actual-size' | 'custom';
-
-interface ViewportAnchor {
- page: number;
- pageOffsetRatio: number;
-}
-
const PDF_DOCUMENT_OPTIONS = { rangeChunkSize: 65536 };
const OVERSCAN = 3;
@@ -57,17 +40,6 @@ function binarySearchPageAtOffset(cumulativeHeights: number[], offset: number):
return lo + 1;
}
-function ignoreAbortError(error: unknown): boolean {
- const errorName = typeof error === 'object' && error !== null && 'name' in error
- ? String((error as { name?: unknown }).name)
- : '';
- const errorMessage = typeof error === 'object' && error !== null && 'message' in error
- ? String((error as { message?: unknown }).message)
- : '';
-
- return errorName === 'AbortException' || errorMessage.includes('TextLayer task cancelled');
-}
-
function buildRawOutline(items: any[]): OutlineItem[] {
return items.map(item => ({
title: item.title,
@@ -117,23 +89,6 @@ async function resolveOutlineItemPageNumber(
}
}
-function getPageWrapperStyle(
- isRendered: boolean,
- hasMeasuredHeight: boolean,
- placeholderHeight: number,
- placeholderWidth: number,
-) {
- if (!isRendered) {
- return { height: placeholderHeight, width: placeholderWidth };
- }
-
- if (hasMeasuredHeight) {
- return undefined;
- }
-
- return { minHeight: placeholderHeight, width: placeholderWidth };
-}
-
export function PdfViewer({ url, fileName }: Readonly) {
const { t } = useTranslation('common');
diff --git a/frontend/components/ui/filePreviewDrawer.tsx b/frontend/components/ui/filePreviewDrawer.tsx
index 5203c64fc..a65eb037b 100644
--- a/frontend/components/ui/filePreviewDrawer.tsx
+++ b/frontend/components/ui/filePreviewDrawer.tsx
@@ -1,14 +1,35 @@
"use client";
-import { useState, useEffect, useCallback, useMemo, useRef } from 'react';
+import { useState, useEffect, useCallback, useMemo, useRef, type PointerEvent as ReactPointerEvent, type WheelEvent as ReactWheelEvent } from 'react';
import { useTranslation } from 'react-i18next';
import dynamic from 'next/dynamic';
import { Drawer, Spin, Button, Table } from 'antd';
-import { Download, Minus, Plus, RotateCw, X } from 'lucide-react';
-import Papa from 'papaparse';
+import { Download, Maximize2, Minimize2, Minus, Plus, RotateCw, X } from 'lucide-react';
import { FilePreviewProps } from '@/types/chat';
+import { DetectedFileType, ImageBaseMode } from '@/types/file';
+import {
+ CHUNK_SIZE,
+ TEXT_RENDER_BLOCK_SIZE,
+ CSV_ROW_HEIGHT,
+ isValidContainerElement,
+ updateChunkRangeState,
+ ensurePreviewTextDecoder,
+ decodePreviewChunk,
+ decodeLocalTextFile,
+ splitPreviewSafeText,
+ shouldStopFetchingChunk,
+ handlePreviewChunkBoundaryResponse,
+ appendTextPreviewContent,
+ parseCsvLine,
+ detectCsvDelimiter,
+ computeRotateFitScale,
+ clamp,
+ ignoreAbortError,
+ getPageWrapperStyle,
+} from '@/lib/filePreviewUtils';
import { storageService } from '@/services/storageService';
import { MarkdownRenderer, extractMarkdownHeadings, type MarkdownHeading } from '@/components/ui/markdownRenderer';
+import { formatFileSize } from '@/lib/utils';
import log from '@/lib/logger';
const PdfViewer = dynamic(() => import('@/components/ui/PdfViewer').then(mod => ({ default: mod.PdfViewer })), {
@@ -20,330 +41,6 @@ const PdfViewer = dynamic(() => import('@/components/ui/PdfViewer').then(mod =>
),
});
-const CHUNK_SIZE = 128 * 1024;
-
-const CSV_ROW_HEIGHT = 40;
-const TEXT_RENDER_BLOCK_SIZE = 200;
-const CSV_DELIMITER_CANDIDATES = [',', ';', '\t', '|'] as const;
-const CHARSET_PATTERN = /charset\s*=\s*([^;\s]+)/i;
-const CONTENT_RANGE_PATTERN = /bytes (\d+)-(\d+)\/(\d+)/;
-const INVALID_CONTAINER_TAGS = new Set(['head', 'style', 'script', 'link', 'meta']);
-
-function isValidContainerElement(el: Element | null): el is HTMLDivElement {
- if (!(el instanceof HTMLDivElement)) {
- return false;
- }
-
- if (!el.isConnected) {
- return false;
- }
-
- const tagName = el.tagName.toLowerCase();
- return !INVALID_CONTAINER_TAGS.has(tagName);
-}
-
-function normalizeCharsetLabel(value: string): string {
- const normalized = value.trim().toLowerCase();
- if (normalized === 'gbk' || normalized === 'gb2312' || normalized === 'cp936') {
- return 'gb18030';
- }
- return normalized;
-}
-
-function extractCharsetFromContentType(contentType: string | null): string | null {
- if (!contentType) return null;
- const match = CHARSET_PATTERN.exec(contentType);
- if (!match?.[1]) return null;
- return normalizeCharsetLabel(match[1].replaceAll(/^"|"$/g, ''));
-}
-
-function updateChunkRangeState(
- contentRange: string | null,
- byteLength: number,
- byteOffsetRef: React.MutableRefObject,
- totalBytesRef: React.MutableRefObject,
-): boolean {
- if (!contentRange) {
- byteOffsetRef.current += byteLength;
- return false;
- }
-
- const match = CONTENT_RANGE_PATTERN.exec(contentRange);
- if (!match) {
- byteOffsetRef.current += byteLength;
- return false;
- }
-
- const fetchedEnd = Number(match[2]);
- const total = Number(match[3]);
- byteOffsetRef.current = fetchedEnd + 1;
- totalBytesRef.current = total;
- return fetchedEnd + 1 < total;
-}
-
-function ensurePreviewTextDecoder(
- contentType: string | null,
- textDecoderRef: React.MutableRefObject,
- decoderEncodingRef: React.MutableRefObject,
- decoderHasExplicitCharsetRef: React.MutableRefObject,
- decoderAllowGbFallbackRef: React.MutableRefObject,
-): void {
- if (textDecoderRef.current) {
- return;
- }
-
- const headerCharset = extractCharsetFromContentType(contentType);
- if (headerCharset) {
- const normalized = normalizeCharsetLabel(headerCharset);
- const isUtf8 = normalized === 'utf-8' || normalized === 'utf8';
-
- textDecoderRef.current = isUtf8
- ? new TextDecoder('utf-8', { fatal: true })
- : new TextDecoder(normalized);
- decoderEncodingRef.current = isUtf8 ? 'utf-8' : normalized;
- decoderHasExplicitCharsetRef.current = true;
- decoderAllowGbFallbackRef.current = isUtf8;
- return;
- }
-
- // Start with strict UTF-8; if invalid bytes appear in later chunks, fallback to GB18030.
- textDecoderRef.current = new TextDecoder('utf-8', { fatal: true });
- decoderEncodingRef.current = 'utf-8';
- decoderHasExplicitCharsetRef.current = false;
- decoderAllowGbFallbackRef.current = true;
-}
-
-function decodePreviewChunk(
- buf: ArrayBuffer,
- hasMore: boolean,
- textDecoderRef: React.MutableRefObject,
- decoderEncodingRef: React.MutableRefObject,
- decoderAllowGbFallbackRef: React.MutableRefObject,
-): string {
- if (!textDecoderRef.current) {
- throw new Error('Text decoder is not initialized');
- }
-
- try {
- let raw = textDecoderRef.current.decode(buf, { stream: hasMore });
- if (!hasMore) {
- raw += textDecoderRef.current.decode();
- }
- return raw;
- } catch (decodeErr) {
- const canFallbackToGb18030 =
- decoderAllowGbFallbackRef.current &&
- decoderEncodingRef.current === 'utf-8';
-
- if (!canFallbackToGb18030) {
- throw decodeErr;
- }
-
- log.warn('UTF-8 decode failed for preview stream, fallback to GB18030:', decodeErr);
- textDecoderRef.current = new TextDecoder('gb18030');
- decoderEncodingRef.current = 'gb18030';
- decoderAllowGbFallbackRef.current = false;
-
- let raw = textDecoderRef.current.decode(buf, { stream: hasMore });
- if (!hasMore) {
- raw += textDecoderRef.current.decode();
- }
- return raw;
- }
-}
-
-async function decodeLocalTextFile(file: File): Promise {
- const buf = await file.arrayBuffer();
-
- try {
- return new TextDecoder('utf-8', { fatal: true }).decode(buf);
- } catch {
- return new TextDecoder('gb18030').decode(buf);
- }
-}
-
-function splitPreviewSafeText(
- raw: string,
- remainder: string,
- hasMore: boolean,
- detectedFileType: DetectedFileType,
-): { remainder: string; safeText: string } {
- const mergedText = remainder + raw;
- const shouldKeepTrailingLine = hasMore && detectedFileType !== 'markdown';
- if (!shouldKeepTrailingLine) {
- return { remainder: '', safeText: mergedText };
- }
-
- const lastNl = mergedText.lastIndexOf('\n');
- if (lastNl === -1) {
- return { remainder: mergedText, safeText: '' };
- }
-
- return {
- remainder: mergedText.slice(lastNl + 1),
- safeText: mergedText.slice(0, lastNl + 1),
- };
-}
-
-function shouldStopFetchingChunk(
- activeSessionId: number,
- currentSessionId: number,
-): boolean {
- return activeSessionId !== currentSessionId;
-}
-
-function handlePreviewChunkBoundaryResponse(
- status: number,
- isFirst: boolean,
- setServerTooLarge: React.Dispatch>,
- setLoading: React.Dispatch>,
- setLoadingMore: React.Dispatch>,
- observerRef: React.MutableRefObject,
- isFetchingRef: React.MutableRefObject,
-): boolean {
- if (status === 413) {
- setServerTooLarge(true);
- if (isFirst) {
- setLoading(false);
- } else {
- setLoadingMore(false);
- }
- isFetchingRef.current = false;
- return true;
- }
-
- if (status === 416) {
- observerRef.current?.disconnect();
- if (isFirst) {
- setLoading(false);
- } else {
- setLoadingMore(false);
- }
- isFetchingRef.current = false;
- return true;
- }
-
- return false;
-}
-
-function appendTextPreviewContent(
- params: {
- detectedFileType: DetectedFileType;
- safeText: string;
- byteOffset: number;
- currentChunkLength: number;
- csvDelimiterRef: React.MutableRefObject;
- setTxtLines: React.Dispatch>;
- setCsvRows: React.Dispatch>;
- setTextContent: React.Dispatch>;
- },
-): void {
- const {
- detectedFileType,
- safeText,
- byteOffset,
- currentChunkLength,
- csvDelimiterRef,
- setTxtLines,
- setCsvRows,
- setTextContent,
- } = params;
-
- if (!safeText) {
- return;
- }
-
- if (detectedFileType === 'text') {
- const newLines = safeText.split('\n');
- if (newLines.at(-1) === '') {
- newLines.pop();
- }
- setTxtLines(prev => [...prev, ...newLines]);
- return;
- }
-
- if (detectedFileType === 'csv') {
- if (byteOffset === currentChunkLength) {
- csvDelimiterRef.current = detectCsvDelimiter(safeText);
- }
- const newLines = safeText.split('\n').filter(line => line.trim().length > 0);
- setCsvRows(prev => [...prev, ...newLines.map((line) => parseCsvLine(line, csvDelimiterRef.current))]);
- return;
- }
-
- setTextContent(prev => prev + safeText);
-}
-
-function parseCsvLine(line: string, delimiter: string): string[] {
- const parsed = Papa.parse(line, {
- header: false,
- skipEmptyLines: false,
- dynamicTyping: false,
- delimiter,
- quoteChar: '"',
- escapeChar: '"',
- });
-
- const row = parsed.data[0];
- if (Array.isArray(row)) {
- return row.map((cell) => (typeof cell === 'string' ? cell.trim() : String(cell ?? '').trim()));
- }
-
- return line.split(delimiter).map((cell) => cell.trim());
-}
-
-function detectCsvDelimiter(sampleText: string): string {
- const lines = sampleText
- .split('\n')
- .map((line) => line.trim())
- .filter((line) => line.length > 0)
- .slice(0, 5);
-
- if (lines.length === 0) {
- return ',';
- }
-
- let bestDelimiter = ',';
- let bestScore = -1;
-
- for (const delimiter of CSV_DELIMITER_CANDIDATES) {
- const columnCounts = lines.map((line) => {
- const parsed = Papa.parse(line, {
- header: false,
- skipEmptyLines: false,
- dynamicTyping: false,
- delimiter,
- quoteChar: '"',
- escapeChar: '"',
- });
-
- const row = parsed.data[0];
- return Array.isArray(row) ? row.length : 1;
- });
-
- const minColumns = Math.min(...columnCounts);
- const maxColumns = Math.max(...columnCounts);
- const averageColumns =
- columnCounts.reduce((sum, count) => sum + count, 0) / columnCounts.length;
-
- if (averageColumns <= 1) {
- continue;
- }
-
- const consistencyBonus = maxColumns === minColumns ? 100 : 0;
- const score = consistencyBonus + averageColumns;
-
- if (score > bestScore) {
- bestScore = score;
- bestDelimiter = delimiter;
- }
- }
-
- return bestDelimiter;
-}
-
-type DetectedFileType = 'pdf' | 'image' | 'markdown' | 'csv' | 'text' | 'office' | 'unknown';
-
export function FilePreviewDrawer(props: Readonly) {
const { open, onClose } = props;
const { t } = useTranslation('common');
@@ -376,6 +73,29 @@ export function FilePreviewDrawer(props: Readonly) {
const [imageScale, setImageScale] = useState(1);
const [imageRotation, setImageRotation] = useState(0);
const [imageLoadError, setImageLoadError] = useState(false);
+ const [imageNaturalSize, setImageNaturalSize] = useState({ width: 0, height: 0 });
+ const [imageViewportSize, setImageViewportSize] = useState({ width: 0, height: 0 });
+ const [imageBaseMode, setImageBaseMode] = useState('fit');
+ const imageViewportResizeObserverRef = useRef(null);
+ const [imagePan, setImagePan] = useState({ x: 0, y: 0 });
+ const [isImageDragging, setIsImageDragging] = useState(false);
+ const imagePanRef = useRef({ x: 0, y: 0 });
+ const imageScaleRef = useRef(1);
+ const dragStateRef = useRef<{
+ isDragging: boolean;
+ pointerId: number | null;
+ startX: number;
+ startY: number;
+ startPanX: number;
+ startPanY: number;
+ }>({
+ isDragging: false,
+ pointerId: null,
+ startX: 0,
+ startY: 0,
+ startPanX: 0,
+ startPanY: 0,
+ });
const [serverTooLarge, setServerTooLarge] = useState(false);
@@ -469,6 +189,206 @@ export function FilePreviewDrawer(props: Readonly) {
const isEmptyFile = fileSize === 0;
const isTooLargeToPreview = !!(fileSize && fileSize > 100 * 1024 * 1024);
+ const normalizedImageRotation = ((imageRotation % 360) + 360) % 360;
+ const imageFitScale = useMemo(
+ () => computeRotateFitScale(normalizedImageRotation, imageNaturalSize, imageViewportSize),
+ [imageNaturalSize, imageViewportSize, normalizedImageRotation],
+ );
+ const imageBaseScale = imageBaseMode === 'fit' ? imageFitScale : 1;
+ const effectiveImageScale = imageScale * imageBaseScale;
+ const imageScaleMin = imageBaseScale > 0 ? 0.25 / imageBaseScale : 0.25;
+ const imageScaleMax = imageBaseScale > 0 ? 6 / imageBaseScale : 6;
+
+ const imageDisplaySize = useMemo(() => {
+ const { width: naturalWidth, height: naturalHeight } = imageNaturalSize;
+ if (naturalWidth <= 0 || naturalHeight <= 0) {
+ return { width: 0, height: 0 };
+ }
+ const isQuarterTurn = normalizedImageRotation === 90 || normalizedImageRotation === 270;
+ const displayWidth = (isQuarterTurn ? naturalHeight : naturalWidth) * effectiveImageScale;
+ const displayHeight = (isQuarterTurn ? naturalWidth : naturalHeight) * effectiveImageScale;
+ return { width: displayWidth, height: displayHeight };
+ }, [imageNaturalSize, normalizedImageRotation, effectiveImageScale]);
+
+ const clampImagePan = useCallback((pan: { x: number; y: number }) => {
+ const { width: viewportWidth, height: viewportHeight } = imageViewportSize;
+ const { width: displayWidth, height: displayHeight } = imageDisplaySize;
+ if (viewportWidth <= 0 || viewportHeight <= 0 || displayWidth <= 0 || displayHeight <= 0) {
+ return { x: 0, y: 0 };
+ }
+
+ const maxPanX = Math.max(0, (displayWidth - viewportWidth) / 2);
+ const maxPanY = Math.max(0, (displayHeight - viewportHeight) / 2);
+ return {
+ x: clamp(pan.x, -maxPanX, maxPanX),
+ y: clamp(pan.y, -maxPanY, maxPanY),
+ };
+ }, [imageDisplaySize, imageViewportSize]);
+
+ useEffect(() => {
+ imagePanRef.current = imagePan;
+ }, [imagePan]);
+
+ useEffect(() => {
+ imageScaleRef.current = imageScale;
+ }, [imageScale]);
+
+ useEffect(() => {
+ if (!open) return;
+ if (imageNaturalSize.width === 0 || imageNaturalSize.height === 0) return;
+ if (imageViewportSize.width === 0 || imageViewportSize.height === 0) return;
+ const normalizedRotation = ((imageRotation % 360) + 360) % 360;
+ const isQuarterTurn = normalizedRotation === 90 || normalizedRotation === 270;
+ const rotatedWidth = isQuarterTurn ? imageNaturalSize.height : imageNaturalSize.width;
+ const rotatedHeight = isQuarterTurn ? imageNaturalSize.width : imageNaturalSize.height;
+ if (rotatedWidth > imageViewportSize.width || rotatedHeight > imageViewportSize.height) {
+ setImageBaseMode('fit');
+ } else {
+ setImageBaseMode('actual');
+ }
+ }, [open, imageNaturalSize, imageViewportSize, imageRotation]);
+
+ const handleImageViewportRef = useCallback((el: HTMLDivElement | null) => {
+ imageViewportResizeObserverRef.current?.disconnect();
+ imageViewportResizeObserverRef.current = null;
+
+ if (!el) {
+ setImageViewportSize({ width: 0, height: 0 });
+ return;
+ }
+
+ const updateViewportSize = () => {
+ setImageViewportSize({ width: el.clientWidth, height: el.clientHeight });
+ };
+
+ const observer = new ResizeObserver(updateViewportSize);
+ observer.observe(el);
+ imageViewportResizeObserverRef.current = observer;
+ updateViewportSize();
+ }, []);
+
+ const handleImagePanReset = useCallback(() => {
+ const nextPan = { x: 0, y: 0 };
+ setImagePan(nextPan);
+ imagePanRef.current = nextPan;
+ setIsImageDragging(false);
+ }, []);
+
+ const applyImageScale = useCallback((nextScale: number, anchorX = 0, anchorY = 0) => {
+ const currentScale = imageScaleRef.current;
+ if (nextScale === currentScale) {
+ return;
+ }
+ const scaleRatio = nextScale / currentScale;
+ const currentPan = imagePanRef.current;
+ const nextPan = clampImagePan({
+ x: anchorX - scaleRatio * (anchorX - currentPan.x),
+ y: anchorY - scaleRatio * (anchorY - currentPan.y),
+ });
+ imagePanRef.current = nextPan;
+ setImagePan(nextPan);
+ imageScaleRef.current = nextScale;
+ setImageScale(nextScale);
+ }, [clampImagePan]);
+
+ const handleImageWheel = useCallback((event: ReactWheelEvent) => {
+ if (imageLoadError) {
+ return;
+ }
+
+ event.preventDefault();
+
+ const currentScale = imageScaleRef.current;
+ const zoomFactor = Math.exp(-event.deltaY * 0.0015);
+ const nextScale = clamp(currentScale * zoomFactor, imageScaleMin, imageScaleMax);
+ if (nextScale === currentScale) {
+ return;
+ }
+
+ const rect = event.currentTarget.getBoundingClientRect();
+ const cursorX = event.clientX - rect.left - rect.width / 2;
+ const cursorY = event.clientY - rect.top - rect.height / 2;
+ applyImageScale(nextScale, cursorX, cursorY);
+ }, [applyImageScale, imageLoadError, imageScaleMin, imageScaleMax]);
+
+ const handleImagePointerDown = useCallback((event: ReactPointerEvent) => {
+ if (imageLoadError || event.button !== 0) {
+ return;
+ }
+
+ event.preventDefault();
+ event.currentTarget.setPointerCapture(event.pointerId);
+ setIsImageDragging(true);
+ dragStateRef.current = {
+ isDragging: true,
+ pointerId: event.pointerId,
+ startX: event.clientX,
+ startY: event.clientY,
+ startPanX: imagePanRef.current.x,
+ startPanY: imagePanRef.current.y,
+ };
+ }, [imageLoadError]);
+
+ const handleImagePointerMove = useCallback((event: ReactPointerEvent) => {
+ const dragState = dragStateRef.current;
+ if (!dragState.isDragging || dragState.pointerId !== event.pointerId) {
+ return;
+ }
+
+ event.preventDefault();
+ const nextPan = {
+ x: dragState.startPanX + (event.clientX - dragState.startX),
+ y: dragState.startPanY + (event.clientY - dragState.startY),
+ };
+ const clamped = clampImagePan(nextPan);
+ imagePanRef.current = clamped;
+ setImagePan(clamped);
+ }, [clampImagePan]);
+
+ const handleImagePointerEnd = useCallback((event: ReactPointerEvent) => {
+ const dragState = dragStateRef.current;
+ if (dragState.pointerId !== event.pointerId) {
+ return;
+ }
+
+ dragStateRef.current = {
+ isDragging: false,
+ pointerId: null,
+ startX: 0,
+ startY: 0,
+ startPanX: 0,
+ startPanY: 0,
+ };
+ setIsImageDragging(false);
+ }, []);
+
+ const handleImageDoubleClick = useCallback(() => {
+ if (imageScale !== 1 || imageBaseMode !== 'fit') {
+ setImageBaseMode('fit');
+ setImageScale(1);
+ imageScaleRef.current = 1;
+ } else {
+ setImageBaseMode('actual');
+ }
+ }, [imageBaseMode, imageScale]);
+
+ const toggleImageBaseMode = useCallback(() => {
+ if (imageBaseMode === 'fit') {
+ setImageBaseMode('actual');
+ } else {
+ setImageBaseMode('fit');
+ }
+ setImageScale(1);
+ imageScaleRef.current = 1;
+ handleImagePanReset();
+ }, [handleImagePanReset, imageBaseMode]);
+
+ useEffect(() => {
+ const clamped = clampImagePan(imagePanRef.current);
+ imagePanRef.current = clamped;
+ setImagePan(clamped);
+ }, [clampImagePan, effectiveImageScale, normalizedImageRotation, imageViewportSize]);
+
const fetchTextChunk = useCallback(async (url: string, isFirst = false, sessionId?: number): Promise => {
const activeSessionId = sessionId ?? textFetchSessionRef.current;
if (!url) {
@@ -678,6 +598,10 @@ export function FilePreviewDrawer(props: Readonly) {
setServerTooLarge(false);
setImageScale(1);
setImageRotation(0);
+ setImageNaturalSize({ width: 0, height: 0 });
+ setImageViewportSize({ width: 0, height: 0 });
+ setImageBaseMode('fit');
+ handleImagePanReset();
setTextContent('');
setTxtLines([]);
setCsvRows([]);
@@ -698,6 +622,8 @@ export function FilePreviewDrawer(props: Readonly) {
decoderAllowGbFallbackRef.current = false;
observerRef.current?.disconnect();
observerRef.current = null;
+ imageViewportResizeObserverRef.current?.disconnect();
+ imageViewportResizeObserverRef.current = null;
if (previousPreviewUrl.startsWith('blob:')) {
URL.revokeObjectURL(previousPreviewUrl);
}
@@ -705,6 +631,13 @@ export function FilePreviewDrawer(props: Readonly) {
}
}, [open]);
+ useEffect(() => {
+ return () => {
+ imageViewportResizeObserverRef.current?.disconnect();
+ imageViewportResizeObserverRef.current = null;
+ };
+ }, []);
+
useEffect(() => {
if (!open) return;
@@ -776,14 +709,6 @@ export function FilePreviewDrawer(props: Readonly) {
}
}, []);
- const formatFileSize = (size: number): string => {
- if (size < 1024) return `${size} B`;
- if (size < 1024 * 1024) return `${(size / 1024).toFixed(1)} KB`;
- return `${(size / (1024 * 1024)).toFixed(2)} MB`;
- };
-
-
-
const renderLoading = () => (
@@ -812,33 +737,60 @@ export function FilePreviewDrawer(props: Readonly) {
const renderImageViewer = () => (
-
- {imageLoadError ? (
- renderCenteredErrorState()
- ) : (
- 
setImageLoadError(true)}
- />
- )}
+
+
+ {imageLoadError ? (
+ renderCenteredErrorState()
+ ) : (
+
+
+ {
+ const img = e.currentTarget;
+ setImageNaturalSize({ width: img.naturalWidth, height: img.naturalHeight });
+ }}
+ onError={() => setImageLoadError(true)}
+ />
+
+
+ )}
+
{!imageLoadError && (
- {Math.round(imageScale * 100)}%
+ {Math.round(effectiveImageScale * 100)}%