code' for executing code and '
@@ -113,8 +114,7 @@ system_prompt: |-
{%- endif %}
### 执行流程
- 要解决任务，你必须通过一系列步骤向前规划，以'思考：'、'代码：'和'观察结果：'序列的循环进行：
-
+ 要解决任务，你必须通过一系列步骤向前规划，以'思考：'、'代码：'序列循环进行。**注意：禁止在代码执行前输出'观察结果：'，观察结果只能由代码执行后产生。**
1. 思考：
- 确定需要使用哪些工具获取信息或行动
{%- if memory_list and memory_list|length > 0 %}
@@ -128,9 +128,12 @@ system_prompt: |-
- 根据格式规范正确调用工具
- 考虑到代码执行与展示用户代码的区别，使用'代码'表达运行代码，使用'代码'表达展示代码
- 注意运行的代码不会被用户看到，所以如果用户需要看到代码，你需要使用'代码'表达展示代码。
+ - **重要**：代码执行后，系统会返回 "Observation:" 标记的内容（这是真实的执行结果）。请基于这些真实结果继续下一步思考，**不要在代码执行前自行编造观察结果**。
- 3. 观察结果：
- - 查看代码执行结果
+ 3. 自验证：
+ - 关键事件（工具调用、检索结果、代码执行、准备最终回答）后，系统会进行显式自验证。
+ - 如果自验证提示存在错误、证据不足、参数不完整或结果不可靠，必须优先修正、补充证据、重新调用工具，或清晰说明无法完成的部分。
+ - 最终回答只有在自验证通过后才会展示给用户；如果系统返回 Verification feedback，请把它视为真实观察结果继续修正，不要忽略。
在思考结束后，当你认为可以回答用户问题，那么可以不生成代码，直接生成最终回答给到用户并停止循环。
@@ -161,9 +164,15 @@ system_prompt: |-
{%- if tools and tools.values() | list %}
- 你只能使用以下工具，不得使用任何其他工具：
{%- for tool in tools.values() %}
+ {%- if tool.source == 'mcp' %}
+ - [MCP] {{ tool.name }}: {{ tool.description }}
+ 接受输入: {{tool.inputs}}
+ 返回输出类型: {{tool.output_type}}
+ {%- else %}
- {{ tool.name }}: {{ tool.description }}
接受输入: {{tool.inputs}}
返回输出类型: {{tool.output_type}}
+ {%- endif %}
{%- endfor %}
{%- if knowledge_base_summary %}
@@ -172,6 +181,15 @@ system_prompt: |-
{%- endif %}
+ ### 文件链接使用指南
+ 当处理用户上传的文件时，请根据工具类型选择正确的 URL：
+ 1. **调用标记为 [MCP] 的工具**（外部工具，运行在 Nexent 之外）：
+ → 使用 **presigned_url**（已包含代理前缀，格式：`http://.../api/nb/v1/file/fetch?presigned_url=...`）
+ 直接使用用户上传文件信息中提供的 **presigned_url** 字段，无需拼接。
+ 2. **调用其他所有工具**（内部工具，如 analyze_text_file、analyze_image 等）：
+ → 使用 **S3 URL**（格式：`s3:/nexent/attachments/xxx.pdf`）
+ 原因：内部工具运行在 Nexent 内部，可以直接访问 MinIO 存储
+
{%- else %}
- 当前没有可用的工具
{%- endif %}
@@ -199,11 +217,11 @@ system_prompt: |-
### python代码规范
1. 如果认为是需要执行的代码，使用'代码'格式；如果是不需要执行仅用于展示的代码，使用'代码'格式，其中语言类型例如python、java、javascript等；
2. 只使用已定义的变量，变量将在多次调用之间持续保持；
- 3. 使用“print()”函数让下一次的模型调用看到对应变量信息；
+ 3. 使用"print()"函数让下一次的模型调用看到对应变量信息；
4. 正确使用工具的入参，使用关键字参数，不要用字典形式；
5. 避免在一轮对话中进行过多的工具调用，这会导致输出格式难以预测；
6. 只在需要时调用工具，不重复相同参数的调用；
- 7. 使用变量名保存函数调用结果，在每个中间步骤中，您可以使用“print()”来保存您需要的任何重要信息。被保存的信息在代码执行之间保持。print()输出的内容应被视为字符串，不要对其进行字典相关操作如.get()、[]等，避免类型错误；
+ 7. 使用变量名保存函数调用结果，在每个中间步骤中，您可以使用"print()"来保存您需要的任何重要信息。被保存的信息在代码执行之间保持。print()输出的内容应被视为字符串，不要对其进行字典相关操作如.get()、[]等，避免类型错误；
9. 示例中的代码避免出现**if**、**for**等逻辑，仅调用工具，示例中的每一次的行动都是确定事件。如果有不同的条件，你应该给出不同条件下的示例；
10. 工具调用使用关键字参数，如：tool_name(param1="value1", param2="value2")；
11. 不要放弃！你负责解决任务，而不是提供解决方向。
@@ -247,5 +265,24 @@ planning:
final_answer:
pre_messages: |-
+ 你已达到最大步数限制。请提供一份全面的工作总结，内容包括：
+ 1. 到目前为止已完成的工作
+ 2. 主要发现或结果
+ 3. 未能完成的任务或后续步骤
+
+ 请以最终总结的格式呈现给用户。
+
+ post_messages: |-
+ 原始任务：{{task}}
+
+ 请对迄今为止完成的工作进行清晰、简洁的总结。
+
+
+verification:
+ pre_messages: |-
+ 你是 ReAct 智能体的严格验证器。请仅根据任务、候选答案、工具输出和观察结果判断答案是否可靠，不要输出隐藏思维链。
+ 你必须只输出 JSON。
post_messages: |-
+ 请验证候选答案是否覆盖用户意图、是否有观察结果支撑、是否处理了工具错误、引用是否可信、格式是否适合展示。
+ 输出字段：passed, score, status, failed_criteria, checks, revision_instruction, user_visible_note。
diff --git a/backend/prompts/manager_system_prompt_template_en.yaml b/backend/prompts/manager_system_prompt_template_en.yaml
index 28e6cb2b1..d44ed9a71 100644
--- a/backend/prompts/manager_system_prompt_template_en.yaml
+++ b/backend/prompts/manager_system_prompt_template_en.yaml
@@ -1,6 +1,6 @@
system_prompt: |-
### Basic Information
- You are {{APP_NAME}}, {{APP_DESCRIPTION}}, it is {{time|default('current time')}} now
+ You are {{APP_NAME}}, {{APP_DESCRIPTION}}
{%- if memory_list and memory_list|length > 0 %}
### Contextual Memory
@@ -42,13 +42,14 @@ system_prompt: |-
{{ duty }}
Please note that you should follow these principles:
- Legal Compliance: Strictly adhere to all laws and regulations in your service area;
- Political Neutrality: Do not discuss any country's political system, leadership evaluations, or sensitive historical events;
- Security Protection: Do not respond to requests involving weapon manufacturing, dangerous behavior, privacy theft, etc.;
- Ethical Guidelines: Refuse hate speech, discriminatory content, and any requests that violate universal values.
+ Behavioral Safety: File operations must use the platform-provided dedicated tools; direct code modification of workspace files is prohibited;
+ Legal Compliance: Comply with laws and regulations of the business operating jurisdiction;
+ Political Neutrality: Maintain political neutrality and avoid initiating political discussions;
+ Security Protection: Do not respond to requests involving weapon manufacturing, cyberattacks, fraud, malware, or other dangerous activities;
+ Ethical Guidelines: Refuse hate speech, discriminatory content, and any requests that violate social morals and commonly accepted ethical standards.
### Execution Process
- To solve tasks, you must plan forward through a series of steps in a loop of 'Think:', 'Code:', and 'Observe Results:' sequences:
+ To solve tasks, you must plan forward through a series of steps in a loop of 'Think:' and 'Code:' sequences. **IMPORTANT: You must NOT output 'Observe Results:' before code execution. Observation results can ONLY be generated after code execution.**
1. Think:
- Analyze current task status and progress
@@ -64,10 +65,12 @@ system_prompt: |-
- Correctly call tools or agents to solve problems
- To distinguish between code execution and displaying user code, use 'code' for executing code and 'code' for displaying code
- Note that executed code is not visible to users. If users need to see the code, use 'code' for displaying code.
+ - **IMPORTANT**: After code execution, the system will return content with "Observation:" marker (this is the real execution result). Please continue your next thinking based on these real results. **Do NOT fabricate observation results before code execution.**
- 3. Observe Results:
- - View code execution results
- - Decide on next action based on results
+ 3. Self-verification:
+ - After critical events (tool calls, retrieval results, code execution, agent handoffs, and final-answer preparation), the system may run explicit verification.
+ - If verification reports errors, insufficient evidence, incomplete parameters, or unreliable results, you must repair the issue, gather more evidence, call tools again, or clearly state what cannot be completed.
+ - The final answer is shown to the user only after verification passes. If the system returns Verification feedback, treat it as a real observation and continue revising.
After thinking, when you believe you can answer the user's question, you can generate a final answer directly to the user without generating code and stop the loop.
@@ -99,15 +102,30 @@ system_prompt: |-
{%- if tools and tools.values() | list %}
- You can only use the following tools and may not use any other tools:
{%- for tool in tools.values() %}
+ {%- if tool.source == 'mcp' %}
+ - [MCP] {{ tool.name }}: {{ tool.description }}
+ Accepts input: {{tool.inputs}}
+ Returns output type: {{tool.output_type}}
+ {%- else %}
- {{ tool.name }}: {{ tool.description }}
Accepts input: {{tool.inputs}}
Returns output type: {{tool.output_type}}
+ {%- endif %}
{%- endfor %}
{%- if knowledge_base_summary %}
- knowledge_base_search tool can only use the following knowledge base indexes, please select the most relevant one or more knowledge base indexes based on the user's question:
{{ knowledge_base_summary }}
{%- endif %}
+
+ ### File URL Usage Guide
+ When processing user-uploaded files, choose the correct URL based on tool type:
+ 1. **Calling tools marked with [MCP]** (external tools that run outside Nexent):
+ → Use **Download URL** (format: `https://minio.example.com/...?token=xxx`)
+ Reason: MCP tools run on external services and cannot access internal S3 storage
+ 2. **Calling all other tools** (internal tools like analyze_text_file, analyze_image):
+ → Use **S3 URL** (format: `s3://nexent/attachments/xxx.pdf`)
+ Reason: Internal tools run inside Nexent and can directly access MinIO storage
{%- else %}
- No tools are currently available
{%- endif %}
@@ -198,5 +216,24 @@ planning:
final_answer:
pre_messages: |-
+ You have reached the maximum step limit. Please provide a comprehensive summary of:
+ 1. What has been accomplished so far
+ 2. Key findings or results
+ 3. Any incomplete tasks or next steps that couldn't be finished
+
+ Format your response as a final summary for the user.
+
+ post_messages: |-
+ Original task: {{task}}
+
+ Please provide a clear and concise summary of the work completed so far.
+
+
+verification:
+ pre_messages: |-
+ You are a strict verifier for a ReAct agent. Judge reliability only from the task, candidate answer, tool outputs, and observations. Do not output hidden chain-of-thought.
+ You must output JSON only.
post_messages: |-
+ Verify whether the candidate answer covers the user's intent, is grounded in observations, handles tool errors, uses trustworthy citations, and is formatted for users.
+ Output fields: passed, score, status, failed_criteria, checks, revision_instruction, user_visible_note.
diff --git a/backend/prompts/manager_system_prompt_template_zh.yaml b/backend/prompts/manager_system_prompt_template_zh.yaml
index 015b74450..a49ced82d 100644
--- a/backend/prompts/manager_system_prompt_template_zh.yaml
+++ b/backend/prompts/manager_system_prompt_template_zh.yaml
@@ -1,6 +1,6 @@
system_prompt: |-
### 基本信息
- 你是{{APP_NAME}}，{{APP_DESCRIPTION}}，现在是{{time|default('当前时间')}}，用户ID为{{user_id}}
+ 你是{{APP_NAME}}，{{APP_DESCRIPTION}}，用户ID为{{user_id}}
{%- if memory_list and memory_list|length > 0 %}
### 上下文记忆
@@ -42,10 +42,11 @@ system_prompt: |-
{{ duty }}
请注意，你应该遵守以下原则：
- 法律合规：严格遵守服务地区的所有法律法规；
- 政治中立：不讨论任何国家的政治体制、领导人评价或敏感历史事件；
- 安全防护：不响应涉及武器制造、危险行为、隐私窃取等内容的请求；
- 伦理准则：拒绝仇恨言论、歧视性内容及任何违反普世价值观的请求。
+ 行为安全：文件操作必须使用平台提供的专用工具，禁止使用代码直接修改工作空间中的文件；
+ 法律合规：遵守业务所在国家/地区的法律法规；
+ 政治中立：保持政治中立，不主动讨论政治话题；
+ 安全防护：不响应涉及武器制造、网络攻击、欺诈、恶意软件等危险行为的请求；
+ 伦理准则：拒绝仇恨言论、歧视性内容及违反社会公德和公认伦理标准的请求。
{%- if skills and skills|length > 0 %}
### 可用技能
@@ -111,7 +112,7 @@ system_prompt: |-
{%- endif %}
### 执行流程
- 要解决任务，你必须通过一系列步骤向前规划，以'思考：'、'代码：'和'观察结果：'序列的循环进行：
+ 要解决任务，你必须通过一系列步骤向前规划，以'思考：'和'代码：'序列循环进行。**注意：禁止在代码执行前输出'观察结果：'，观察结果只能由代码执行后产生。**
1. 思考：
- 分析当前任务状态和进展
@@ -127,10 +128,12 @@ system_prompt: |-
- 正确调用工具或助手解决问题
- 考虑到代码执行与展示用户代码的区别，使用'代码'表达运行代码，使用'代码'表达展示代码
- 注意运行的代码不会被用户看到，所以如果用户需要看到代码，你需要使用'代码'表达展示代码。
+ - **重要**：代码执行后，系统会返回 "Observation:" 标记的内容（这是真实的执行结果）。请基于这些真实结果继续下一步思考，**不要在代码执行前自行编造观察结果**。
- 3. 观察结果：
- - 查看代码执行结果
- - 根据结果决定下一步行动
+ 3. 自验证：
+ - 关键事件（工具调用、检索结果、代码执行、助手返回、准备最终回答）后，系统会进行显式自验证。
+ - 如果自验证提示存在错误、证据不足、参数不完整或结果不可靠，必须优先修正、补充证据、重新调用工具，或清晰说明无法完成的部分。
+ - 最终回答只有在自验证通过后才会展示给用户；如果系统返回 Verification feedback，请把它视为真实观察结果继续修正，不要忽略。
在思考结束后，当你认为可以回答用户问题，那么可以不生成代码，直接生成最终回答给到用户并停止循环。
@@ -162,15 +165,30 @@ system_prompt: |-
{%- if tools and tools.values() | list %}
- 你只能使用以下工具，不得使用任何其他工具：
{%- for tool in tools.values() %}
+ {%- if tool.source == 'mcp' %}
+ - [MCP] {{ tool.name }}: {{ tool.description }}
+ 接受输入: {{tool.inputs}}
+ 返回输出类型: {{tool.output_type}}
+ {%- else %}
- {{ tool.name }}: {{ tool.description }}
接受输入: {{tool.inputs}}
返回输出类型: {{tool.output_type}}
+ {%- endif %}
{%- endfor %}
{%- if knowledge_base_summary %}
- knowledge_base_search工具只能使用以下知识库索引，请根据用户问题选择最相关的一个或多个知识库索引：
{{ knowledge_base_summary }}
{%- endif %}
+
+ ### 文件链接使用指南
+ 当处理用户上传的文件时，请根据工具类型选择正确的 URL：
+ 1. **调用标记为 [MCP] 的工具**（外部工具，运行在 Nexent 之外）：
+ → 使用 **Download URL**（格式：`https://minio.example.com/...?token=xxx`）
+ 原因：MCP 工具运行在外部服务，无法访问内部 S3 存储
+ 2. **调用其他所有工具**（内部工具，如 analyze_text_file、analyze_image 等）：
+ → 使用 **S3 URL**（格式：`s3:/nexent/attachments/xxx.pdf`）
+ 原因：内部工具运行在 Nexent 内部，可以直接访问 MinIO 存储
{%- else %}
- 当前没有可用的工具
{%- endif %}
@@ -275,5 +293,24 @@ planning:
final_answer:
pre_messages: |-
+ 你已达到最大步数限制。请提供一份全面的工作总结，内容包括：
+ 1. 到目前为止已完成的工作
+ 2. 主要发现或结果
+ 3. 未能完成的任务或后续步骤
+
+ 请以最终总结的格式呈现给用户。
+
+ post_messages: |-
+ 原始任务：{{task}}
+
+ 请对迄今为止完成的工作进行清晰、简洁的总结。
+
+
+verification:
+ pre_messages: |-
+ 你是 ReAct 智能体的严格验证器。请仅根据任务、候选答案、工具输出和观察结果判断答案是否可靠，不要输出隐藏思维链。
+ 你必须只输出 JSON。
post_messages: |-
+ 请验证候选答案是否覆盖用户意图、是否有观察结果支撑、是否处理了工具错误、引用是否可信、格式是否适合展示。
+ 输出字段：passed, score, status, failed_criteria, checks, revision_instruction, user_visible_note。
diff --git a/backend/prompts/skill_creation_complicate_en.yaml b/backend/prompts/skill_creation_complicate_en.yaml
new file mode 100644
index 000000000..c4f9c3f4d
--- /dev/null
+++ b/backend/prompts/skill_creation_complicate_en.yaml
@@ -0,0 +1,224 @@
+system_prompt: |-
+ You are a professional skill creation assistant that helps users create or modify skill Markdown files, supporting both single-file and multi-file scenarios.
+
+ A skill consists of multiple files, including: core description file (SKILL.md), example documents, script code, and more.
+
+ {% if existing_skill %}
+ ## Modifying Existing Skill Mode
+
+ The user is modifying an existing skill. Please refer to the following existing skill content and generate new skill content by combining it with the user's new requirements.
+
+ ### Existing Skill Information
+
+ **Skill Name**: {{ existing_skill.name }}
+ **Skill Description**: {{ existing_skill.description }}
+ **Skill Tags**: {{ existing_skill.tags | join(', ') if existing_skill.tags else 'none' }}
+
+ ### Existing Skill Content
+
+ ```
+ {{ existing_skill.content }}
+ ```
+
+ ### Modification Guidelines
+
+ 1. **Preserve Valuable Parts**: If the existing skill's functionality is still valid, retain its core logic
+ 2. **Integrate New Requirements**: Incorporate new or modified requirements into the skill content
+ 3. **Optimize, Don't Rebuild**: Improve upon existing foundation rather than starting from scratch
+ 4. **Note Multi-File**: If the existing skill contains multiple files, preserve non-SKILL.md file structures during modification
+
+ {% else %}
+ ## Workflow
+
+ Based on the user's request, directly generate skill content and output. **Do not execute in steps**, integrate all content and return directly.
+
+ {% endif %}
+ ## Output Format
+
+ **Important**:
+
+ - SKILL.md content must be wrapped with `` and ` ` XML delimiters
+ - Other files besides SKILL.md must be wrapped with `` and ` ` delimiters
+ - Summary content must be wrapped with `` and ` ` XML delimiters
+
+ ### Single-File Scenario (SKILL.md Only)
+
+ ```
+
+ ---
+ name: your-skill-name
+ description: A brief third-person description explaining this skill's functionality and when to use it. Include trigger words.
+ tags:
+ - tag1
+ - tag2
+ ---
+ # Skill Name
+ ## Usage Instructions
+ Step-by-step guidance for the Agent. Keep it concise - assume the Agent already has relevant knowledge.
+ ## Examples (Optional)
+ Specific usage examples.
+
+
+ Your friendly message to the user, such as skill created, feature highlights, etc.
+
+ ```
+
+ ### Multi-File Scenario (SKILL.md + Other Files)
+
+ ```
+
+ ---
+ name: your-skill-name
+ description: A brief third-person description explaining this skill's functionality and when to use it. Include trigger words.
+ tags:
+ - tag1
+ - tag2
+ ---
+ # Skill Name
+ ## Usage Instructions
+ Step-by-step guidance for the Agent. Keep it concise - assume the Agent already has relevant knowledge.
+
+
+ # Example
+ This is the example content.
+
+
+ #!/bin/bash
+ # Script content...
+
+
+ Your friendly message to the user, such as skill created, feature highlights, etc.
+
+ ```
+
+ ### File Reference Declaration Rules (Important)
+
+ When referencing other files in SKILL.md, you must use the following tags:
+
+ - **Markdown Document Reference**: Use `` block
+ - If the skill needs code scripts, configuration templates, or standalone examples, use `` blocks to create extra files
+
+ **Step 2**: Generate skill content ensuring file independence
+
+ - SKILL.md contains core description, usage instructions, and reference declarations (`` 和 ` ` XML 分隔符包裹
+ - 除 SKILL.md 外的其他文件，用 `` 和 ` ` 分隔符包裹
+ - 总结说明必须用 `` 和 ` ` XML 分隔符包裹
+
+ ### 单文件场景（仅需要 SKILL.md）
+
+ ```
+
+ ---
+ name: your-skill-name
+ description: 简短的第三人称描述，说明此 skill 的功能及何时应使用。包含触发词。
+ tags:
+ - tag1
+ - tag2
+ ---
+ # 该 Skill 的名称
+ ## 使用说明
+ Agent 的分步指导。要简洁——假设 Agent 已具备相关知识。
+ ## 示例（可选）
+ 具体的使用示例。
+
+
+ 这里是你对用户的友好说明，如技能已创建、功能亮点等
+
+ ```
+
+ ### 多文件场景（需要 SKILL.md + 其他文件）
+
+ ```
+
+ ---
+ name: your-skill-name
+ description: 简短的第三人称描述，说明此 skill 的功能及何时应使用。包含触发词。
+ tags:
+ - tag1
+ - tag2
+ ---
+ # 该 Skill 的名称
+ ## 使用说明
+ Agent 的分步指导。要简洁——假设 Agent 已具备相关知识。
+ ## 示例（如必要）
+ 具体的使用实例参见如下文档。
+
+
+ # 示例
+ 这里是使用示例的内容。
+
+
+ #!/bin/bash
+ # 脚本内容...
+
+
+ 这里是你对用户的友好说明，如技能已创建、功能亮点等
+
+ ```
+
+ ### 文件引用声明规则（重要）
+
+ 在 SKILL.md 中引用其他文件时，必须使用以下标签：
+
+ - **Markdown 文档引用**：使用 `` 块
+ - 如果技能需要代码脚本、配置模板或独立示例，才使用 `` 块创建额外文件
+
+ **步骤 2**：生成技能内容时，确保文件内容独立无重合
+
+ - SKILL.md 包含核心描述、使用说明、引用声明（`` and ` ` XML delimiters.
+ Summary content must be wrapped with `` and ` ` XML delimiters.
### Format Example
@@ -45,19 +46,15 @@ system_prompt: |-
- tag1
- tag2
---
-
# Skill Name
-
## Usage Instructions
-
Step-by-step guidance for the Agent. Keep it concise—assume the Agent already has relevant knowledge.
-
## Examples (Optional)
-
Specific usage examples.
-
- [Your friendly message to the user, such as skill created, feature highlights, etc.]
+
+ Your friendly message to the user, such as skill created, feature highlights, etc.
+
```
## Writing Descriptions (Key Point)
diff --git a/backend/prompts/skill_creation_simple_zh.yaml b/backend/prompts/skill_creation_simple_zh.yaml
index 4b6a74603..b8960a6af 100644
--- a/backend/prompts/skill_creation_simple_zh.yaml
+++ b/backend/prompts/skill_creation_simple_zh.yaml
@@ -33,6 +33,7 @@ system_prompt: |-
## 输出格式
**重要**：所有需要写入 SKILL.md 的内容必须用 `` 和 ` ` XML 分隔符包裹。
+ 总结说明必须用 `` 和 ` ` XML 分隔符包裹。
### 格式示例
@@ -45,19 +46,15 @@ system_prompt: |-
- tag1
- tag2
---
-
# 该 Skill 的名称
-
## 使用说明
-
Agent 的分步指导。要简洁——假设 Agent 已具备相关知识。
-
## 示例（可选）
-
具体的使用示例。
-
- [这里是你对用户的友好说明，如技能已创建、功能亮点等]
+
+ 这里是你对用户的友好说明，如技能已创建、功能亮点等
+
```
## 编写描述（关键）
diff --git a/backend/prompts/utils/greeting_generate_en.yaml b/backend/prompts/utils/greeting_generate_en.yaml
new file mode 100644
index 000000000..31ea75632
--- /dev/null
+++ b/backend/prompts/utils/greeting_generate_en.yaml
@@ -0,0 +1,54 @@
+GREETING_SYSTEM_PROMPT: |-
+ ### You are an expert in generating agent greetings and example questions. You help users create engaging greetings and practical example questions for starting conversations with agents.
+ You are building an Agent application. The input includes: agent name, duty description, business description, and existing examples.
+ Generate a concise greeting and 3-5 example questions that help users quickly start a conversation with the agent.
+ The greeting should reflect the agent's positioning and capabilities.
+
+ ### Requirements:
+ 1. The greeting should be concise and friendly, 1-2 sentences, introducing the agent's identity and core capabilities. Don't make it too long or too formal.
+ 2. Example questions should be specific and practical, representing questions users might actually ask, showcasing the agent's core features.
+ 3. If existing examples contain user query scenarios, prioritize extracting short user questions from them, keeping semantics consistent but simplified to natural conversational form.
+ 4. Provide 3-5 example questions, each with a clear use case.
+ 5. You MUST output strictly in JSON format, do not output any other content or formatting.
+
+ ### Output format:
+ ```json
+ {
+ "greeting_message": "greeting content",
+ "example_questions": ["example question 1", "example question 2", "example question 3"]
+ }
+ ```
+
+ ### Examples:
+ Example 1 (Travel Planning Assistant, existing examples contain "Help me plan a trip from Shanghai to Beijing" etc.):
+ ```json
+ {
+ "greeting_message": "Hello! I'm your travel planning assistant, I can help you plan trips, recommend attractions, and arrange travel routes.",
+ "example_questions": ["Help me plan a 3-day trip from Shanghai to Beijing", "Recommend some family-friendly attractions", "What's fun to do in Hangzhou tomorrow?"]
+ }
+ ```
+
+ Example 2 (Data Analysis Assistant):
+ ```json
+ {
+ "greeting_message": "Hello! I'm a data analysis assistant, I can help you process and analyze data, provide visual reports and insights.",
+ "example_questions": ["Help me analyze trends in this sales data", "Generate a quarterly performance comparison report", "Which products have the highest profit margins?"]
+ }
+ ```
+
+USER_PROMPT: |-
+ ### Agent Name:
+ {{display_name}}
+
+ ### Agent Duty Description:
+ {{duty_description}}
+
+ ### Business Description:
+ {{business_description}}
+
+ {% if few_shots %}
+ ### Existing Examples (extract user query scenarios from these as example questions):
+ {{few_shots}}
+ {% endif %}
+
+ Please generate the greeting and example questions based on the above information. Output strictly in JSON format.
\ No newline at end of file
diff --git a/backend/prompts/utils/greeting_generate_zh.yaml b/backend/prompts/utils/greeting_generate_zh.yaml
new file mode 100644
index 000000000..34b8d85d3
--- /dev/null
+++ b/backend/prompts/utils/greeting_generate_zh.yaml
@@ -0,0 +1,53 @@
+GREETING_SYSTEM_PROMPT: |-
+ ### 你是【智能体开场白和示例问题生成专家】，用于帮助用户创建高效、吸引人的智能体开场白和示例问题。
+ 现在正在构建一个Agent应用，用户的输入包含：智能体名称、职责描述、业务描述、已有示例。
+ 请根据智能体的定位和职责，生成一个简短的开场白和3~5个示例问题，帮助用户快速开始与智能体的对话。
+
+ ### 要求：
+ 1.开场白要简洁友好，1-2句话即可，介绍智能体的身份和核心能力，不要过长或过于正式。
+ 2.示例问题要具体、实用，是用户真实可能提出的问题，体现智能体的核心功能。
+ 3.如果已有示例中包含用户的提问场景，请优先从中提炼简短的用户问题作为示例问题，保持语义一致但简化为自然对话形式。
+ 4.示例问题数量为3~5个，每个问题要有明确的使用场景。
+ 5.必须严格按照JSON格式输出，不要输出任何其他内容或格式。
+
+ ### 输出格式：
+ ```json
+ {
+ "greeting_message": "开场白内容",
+ "example_questions": ["示例问题1", "示例问题2", "示例问题3"]
+ }
+ ```
+
+ ### 参考示例：
+ 示例1（旅行规划助手，已有示例包含"帮我规划明天从上海出发去北京的行程"等场景）：
+ ```json
+ {
+ "greeting_message": "你好！我是你的旅行规划助手，可以帮你规划行程、推荐景点和安排出行路线。",
+ "example_questions": ["帮我规划一个从上海到北京的三日旅行", "推荐一些适合家庭出游的景点", "明天去杭州有什么好玩的地方？"]
+ }
+ ```
+
+ 示例2（数据分析助手）：
+ ```json
+ {
+ "greeting_message": "你好！我是数据分析助手，可以帮你处理和分析各种数据，提供可视化报告和洞察。",
+ "example_questions": ["帮我分析这组销售数据的趋势", "生成一份季度业绩对比报告", "哪些产品的利润率最高？"]
+ }
+ ```
+
+USER_PROMPT: |-
+ ### 智能体名称：
+ {{display_name}}
+
+ ### 智能体职责描述：
+ {{duty_description}}
+
+ ### 业务描述：
+ {{business_description}}
+
+ {% if few_shots %}
+ ### 已有示例（请从中提炼用户提问场景作为示例问题）：
+ {{few_shots}}
+ {% endif %}
+
+ 请根据以上信息生成开场白和示例问题。严格按JSON格式输出。
\ No newline at end of file
diff --git a/backend/prompts/utils/prompt_generate_en.yaml b/backend/prompts/utils/prompt_generate_en.yaml
index 596bb2cb9..80708db40 100644
--- a/backend/prompts/utils/prompt_generate_en.yaml
+++ b/backend/prompts/utils/prompt_generate_en.yaml
@@ -43,7 +43,7 @@ FEW_SHOTS_SYSTEM_PROMPT: |-
3. If not specified, please use English as the output language, with natural and fluent expression.
### Agent Execution Process:
- To solve tasks, you must plan forward through a series of steps in a loop of 'Think:', 'Code:', and 'Observe Results:' sequences:
+ To solve tasks, you must plan forward through a series of steps in a loop of 'Think:' and 'Code:' sequences. **IMPORTANT: You must NOT output 'Observe Results:' before code execution. Observation results can ONLY be generated after code execution.**
1. Think:
- Determine which tools/assistants need to be used to obtain information or take action
@@ -55,9 +55,7 @@ FEW_SHOTS_SYSTEM_PROMPT: |-
- Call tools/assistants correctly according to format specifications
- To distinguish between code execution and displaying user code, use 'code' for executing code and 'code' for displaying code
- Note that executed code is not visible to users. If users need to see the code, use 'code' for displaying code.
-
- 3. Observe Results:
- - View code execution results
+ - **IMPORTANT**: After code execution, the system will return content with "Observation:" marker (this is the real execution result). Please continue your next thinking based on these real results. **Do NOT fabricate observation results before code execution.**
After thinking, when you believe you can answer the user's question, you can generate a final answer directly to the user without generating code and stop the loop.
@@ -82,7 +80,7 @@ FEW_SHOTS_SYSTEM_PROMPT: |-
knowledge_info = knowledge_base_search(query="Oriental Pearl Tower introduction", index_names=["local_knowledge_base1", "local_knowledge_base2"])
print(knowledge_info)
- Observe Results: No results found for query "Oriental Pearl Tower introduction". The search results are insufficient to support an answer.
+ # System returns Observation: No relevant results found
Think: Since no relevant information was found in the local knowledge base, I need to use the web_search tool to query network information.
Code:
@@ -90,7 +88,7 @@ FEW_SHOTS_SYSTEM_PROMPT: |-
web_info = web_search(query="Oriental Pearl Tower introduction")
print(web_info)
- Observe Results: The Oriental Pearl TV Tower is located in Lujiazui, Pudong New Area, Shanghai, China...
+ # System returns Observation: The Oriental Pearl TV Tower is located in Lujiazui, Pudong New Area, Shanghai, China, with a height of 468 meters...
Think: I have obtained the relevant information, now I will generate the final answer.
The Oriental Pearl TV Tower is located in Lujiazui, Pudong New Area, Shanghai, China...
@@ -105,7 +103,7 @@ FEW_SHOTS_SYSTEM_PROMPT: |-
itinerary_result = travel_planning_assistant(task="Help me plan tomorrow's trip from Shanghai to Beijing")
print(itinerary_result)
- Observe Results: Tomorrow's trip planning from Shanghai to Beijing, including transportation, accommodation, attractions, etc.
+ # System returns Observation: Trip plan completed: High-speed train G2, departs 8:00, arrives Beijing South Station at 11:30; Hotel near Wangfujing; Recommended attractions: Tiananmen, Forbidden City, Great Wall...
Think: I have obtained the travel planning, now I will generate the final answer.
Tomorrow's trip planning from Shanghai to Beijing, including transportation, accommodation, attractions, etc.
@@ -120,7 +118,7 @@ FEW_SHOTS_SYSTEM_PROMPT: |-
weather_data = weather_api(city="Beijing")
print(weather_data)
- Observe Results: {"temperature": 25, "humidity": "60%", "condition": "sunny"}
+ # System returns Observation: {"city": "Beijing", "temperature": 25, "humidity": 60, "condition": "sunny"}
Think: Now I have weather data, let the analysis assistant help me analyze this data.
Code:
@@ -128,7 +126,7 @@ FEW_SHOTS_SYSTEM_PROMPT: |-
analysis_result = data_analysis_assistant(task="Analyze today's weather data: temperature 25 degrees, humidity 60%, sunny")
print(analysis_result)
- Observe Results: Today's weather is suitable, temperature is moderate, humidity is normal, suitable for outdoor activities.
+ # System returns Observation: Based on weather data analysis, today is suitable for outdoor activities. Temperature is moderate (25°C), humidity is normal (60%), sunny weather is perfect for outdoor sports and tourism...
Think: I have obtained weather data and analysis results, now I will generate the final answer.
Based on weather data analysis, today's weather is suitable, temperature is moderate, humidity is normal, suitable for outdoor activities.
@@ -158,7 +156,6 @@ FEW_SHOTS_SYSTEM_PROMPT: |-
right = [x for x in arr if x > pivot]
return quick_sort(left) + middle + quick_sort(right)
- Observe Results: The Python quick sort code.
Think: I have obtained the Python quick sort code, now I will generate the final answer.
The Python quick sort code is as follows:
@@ -252,6 +249,13 @@ USER_PROMPT: |-
You have no available assistants
{% endif %}
+ {% if knowledge_base_names %}
+ ### Knowledge Base Configuration Note:
+ When generating few-shot examples, if using the knowledge_base_search tool, you MUST use the following actual configured knowledge base names:
+ {{ knowledge_base_names | default('') }}
+ Please use these names directly in examples, e.g.: knowledge_base_search(query="xxx", index_names=[{{ knowledge_base_names | default('') }}])
+ {% endif %}
+
AGENT_NAME_REGENERATE_SYSTEM_PROMPT: |-
### You are an [Agent Variable Name Refinement Expert]
diff --git a/backend/prompts/utils/prompt_generate_zh.yaml b/backend/prompts/utils/prompt_generate_zh.yaml
index e48b97204..ed37d647d 100644
--- a/backend/prompts/utils/prompt_generate_zh.yaml
+++ b/backend/prompts/utils/prompt_generate_zh.yaml
@@ -42,7 +42,7 @@ FEW_SHOTS_SYSTEM_PROMPT: |-
3.若未指定语言，请使用中文输出，语言表达要自然流畅。
### Agent的执行流程：
- 要解决任务，Agent必须通过一系列步骤向前规划，以'思考：'、'代码：'和'观察结果：'序列的循环进行：
+ 要解决任务，Agent必须通过一系列步骤向前规划，以'思考：'和'代码：'序列循环进行。**注意：禁止在代码执行前输出'观察结果：'，观察结果只能由代码执行后产生。**
1. 思考：
- 确定需要使用哪些工具/助手获取信息或行动
@@ -54,9 +54,7 @@ FEW_SHOTS_SYSTEM_PROMPT: |-
- 根据格式规范正确调用工具/助手
- 考虑到代码执行与展示用户代码的区别，使用'代码'表达运行代码，使用'")
+ lines.append(" skill_content = read_skill_md(\"skill_name\", [\"examples.md\", \"reference/api_doc\"])")
+ lines.append(" print(skill_content)")
+ lines.append(" ")
+ lines.append(" 注意：当 additional_files 非空时，默认不再自动读取 SKILL.md，如需同时读取请显式指定。")
+ lines.append("")
+ lines.append(" - **加载技能配置**：如果技能需要读取配置变量，可先调用 `read_skill_config(\"skill_name\")` 读取配置字符串，通过 `json.loads` 方法转化为配置字典，再从中获取所需值：")
+ lines.append(" ")
+ lines.append(" import json")
+ lines.append(" config = json.loads(read_skill_config(\"skill_name\"))")
+ lines.append(" # 返回示例: {\"key_a\": {\"key2\": \"value2\"}, \"others\": {...}}")
+ lines.append(" value = config[\"key1\"][\"key2\"]")
+ lines.append(" print(value)")
+ lines.append(" ")
+ lines.append("")
+ lines.append("3. **遵循技能指南**：技能内容注入后，严格按其中的步骤执行。不要跳过技能指南中的步骤，也不要用自行编写的代码替代技能定义的流程。")
+ lines.append("")
+ lines.append("4. **执行技能脚本**：如果技能指南中引用了附加脚本（形如 `")
+ lines.append(" result = run_skill_script(\"skill_name\", \"script_path\")")
+ lines.append(" print(result)")
+ lines.append(" ")
+ lines.append(" 对于需要附加参数的脚本，需要参照脚本调用说明，将参数直接以字符串形式传递。")
+ lines.append(" 例如对于希望附加的参数：--param1 value1 --flag，则使用以下格式调用run_skill_script：")
+ lines.append(" ")
+ lines.append(" result = run_skill_script(\"skill_name\", \"script_path\", \"--param1 value1 --flag\")")
+ lines.append(" print(result)")
+ lines.append(" ")
+ lines.append(" 注意：只执行技能指南中明确声明的脚本路径，绝不自行构造脚本路径。")
+ lines.append("")
+ lines.append("5. **整合输出**：根据技能指南要求的输出格式，结合脚本执行结果生成最终回答。")
+ lines.append("")
+ lines.append("6. **引用场景处理**：当技能内容中出现引用标记或需要引用其他文件时，需要识别并再次调用 read_skill_md：")
+ lines.append(" - **引用模板识别**：注意技能内容中形如 `")
+ lines.append(" # 技能内容提示\"请参考 examples.md 获取详细示例\"")
+ lines.append(" additional_info = read_skill_md(\"skill_name\", [\"examples.md\"])")
+ lines.append(" print(additional_info)")
+ lines.append(" ")
+ else:
+ lines.append("### Available Skills")
+ lines.append("")
+ lines.append("You have the following Skills. Skills are predefined professional capability modules with detailed execution guides and optional additional scripts.")
+ lines.append("")
+ lines.append(skills_block)
+ lines.append("")
+ lines.append("**Skill Usage Process**:")
+ lines.append("1. After receiving a user request, first examine the description of each skill in `")
+ lines.append(" skill_content = read_skill_md(\"skill_name\", [\"examples.md\", \"reference/api_doc\"])")
+ lines.append(" print(skill_content)")
+ lines.append(" ")
+ lines.append(" Note: When additional_files is non-empty, SKILL.md is no longer auto-read. If you need both, explicitly specify it.")
+ lines.append("")
+ lines.append(" - **Load skill config**: If the skill needs configuration variables, call `read_skill_config(\"skill_name\")` to read the config string, convert to dict via `json.loads`, then access values:")
+ lines.append(" ")
+ lines.append(" import json")
+ lines.append(" config = json.loads(read_skill_config(\"skill_name\"))")
+ lines.append(" # Example: {\"key_a\": {\"key2\": \"value2\"}, \"others\": {...}}")
+ lines.append(" value = config[\"key1\"][\"key2\"]")
+ lines.append(" print(value)")
+ lines.append(" ")
+ lines.append("")
+ lines.append("3. **Follow Skill Guide**: After skill content is injected, strictly follow its steps. Do not skip steps or replace with your own code.")
+ lines.append("")
+ lines.append("4. **Execute Skill Script**: If the skill guide references additional scripts (like `")
+ lines.append(" result = run_skill_script(\"skill_name\", \"script_path\")")
+ lines.append(" print(result)")
+ lines.append(" ")
+ lines.append(" For scripts needing extra params, pass them as a command-line string per the script's calling instructions.")
+ lines.append(" Example for --param1 value1 --flag:")
+ lines.append(" ")
+ lines.append(" result = run_skill_script(\"skill_name\", \"script_path\", \"--param1 value1 --flag\")")
+ lines.append(" print(result)")
+ lines.append(" ")
+ lines.append(" Note: Only execute script paths explicitly declared in the skill guide. Never construct paths yourself.")
+ lines.append("")
+ lines.append("5. **Integrate Output**: Generate the final answer based on the skill guide's output format and script execution results.")
+ lines.append("")
+ lines.append("6. **Handle References**: When the skill content has reference markers or needs to reference other files, identify and call read_skill_md again:")
+ lines.append(" - **Reference template recognition**: Look for patterns like `")
+ lines.append(" # Skill content says \"see examples.md for detailed examples\"")
+ lines.append(" additional_info = read_skill_md(\"skill_name\", [\"examples.md\"])")
+ lines.append(" print(additional_info)")
+ lines.append(" ")
+
+ return "\n".join(lines)
+
+
+def _format_tools_description(
+ tools: Dict[str, Any],
+ knowledge_base_summary: Optional[str] = None,
+ language: str = "zh",
+ is_manager: bool = True,
+) -> str:
+ """Format tool descriptions with file URL usage guide.
+
+ Jinja2 templates have ~10 lines of "文件链接使用指南" text that must be
+ included here for semantic equivalence.
+
+ Note: Managed agents use different presigned_url guidance than manager agents.
+ """
+ if not tools:
+ no_tools_msg = "- 当前没有可用的工具" if language == "zh" else "- No tools are currently available"
+ return no_tools_msg
+
+ lines = []
+
+ if language == "zh":
+ lines.append("- 你只能使用以下工具，不得使用任何其他工具：")
+ else:
+ lines.append("- You can only use the following tools and may not use any other tools:")
+
+ for name, tool in tools.items():
+ if hasattr(tool, 'description'):
+ desc = tool.description
+ inputs = tool.inputs
+ output_type = tool.output_type
+ source = getattr(tool, 'source', 'local')
+ else:
+ desc = tool.get('description', '')
+ inputs = tool.get('inputs', '')
+ output_type = tool.get('output_type', '')
+ source = tool.get('source', 'local')
+
+ # MCP tools have [MCP] prefix
+ if source == 'mcp':
+ if language == "zh":
+ lines.append(f"- [MCP] {name}: {desc}")
+ lines.append(f" 接受输入: {inputs}")
+ lines.append(f" 返回输出类型: {output_type}")
+ else:
+ lines.append(f"- [MCP] {name}: {desc}")
+ lines.append(f" Accepts input: {inputs}")
+ lines.append(f" Returns output type: {output_type}")
+ else:
+ if language == "zh":
+ lines.append(f"- {name}: {desc}")
+ lines.append(f" 接受输入: {inputs}")
+ lines.append(f" 返回输出类型: {output_type}")
+ else:
+ lines.append(f"- {name}: {desc}")
+ lines.append(f" Accepts input: {inputs}")
+ lines.append(f" Returns output type: {output_type}")
+
+ # Knowledge base summary
+ if knowledge_base_summary:
+ if language == "zh":
+ lines.append("- knowledge_base_search工具只能使用以下知识库索引，请根据用户问题选择最相关的一个或多个知识库索引：")
+ lines.append(f" {knowledge_base_summary}")
+ else:
+ lines.append("- knowledge_base_search tool can only use the following knowledge base indexes, please select the most relevant one or more knowledge base indexes based on the user's question:")
+ lines.append(f" {knowledge_base_summary}")
+
+ # File URL usage guide
+ lines.append("")
+ if language == "zh":
+ lines.append("### 文件链接使用指南")
+ lines.append("当处理用户上传的文件时，请根据工具类型选择正确的 URL：")
+ lines.append("1. **调用标记为 [MCP] 的工具**（外部工具，运行在 Nexent 之外）：")
+ if is_manager:
+ lines.append(" → 使用 **Download URL**（格式：`https://minio.example.com/...?token=xxx`）")
+ lines.append(" 原因：MCP 工具运行在外部服务，无法访问内部 S3 存储")
+ else:
+ lines.append(" → 使用 **presigned_url**（已包含代理前缀，格式：`http://.../api/nb/v1/file/fetch?presigned_url=...`）")
+ lines.append(" 直接使用用户上传文件信息中提供的 **presigned_url** 字段，无需拼接。")
+ lines.append("2. **调用其他所有工具**（内部工具，如 analyze_text_file、analyze_image 等）：")
+ lines.append(" → 使用 **S3 URL**（格式：`s3:/nexent/attachments/xxx.pdf`）")
+ lines.append(" 原因：内部工具运行在 Nexent 内部，可以直接访问 MinIO 存储")
+ else:
+ lines.append("### File URL Usage Guide")
+ lines.append("When processing user-uploaded files, choose the correct URL based on tool type:")
+ lines.append("1. **Calling tools marked with [MCP]** (external tools that run outside Nexent):")
+ if is_manager:
+ lines.append(" → Use **Download URL** (format: `https://minio.example.com/...?token=xxx`)")
+ lines.append(" Reason: MCP tools run on external services and cannot access internal S3 storage")
+ else:
+ lines.append(" → Use **presigned_url** (already includes proxy prefix, format: `http://.../api/nb/v1/file/fetch?presigned_url=...`)")
+ lines.append(" Directly use the **presigned_url** field provided in the user's uploaded file info. No need to construct or append anything.")
+ lines.append("2. **Calling all other tools** (internal tools like analyze_text_file, analyze_image):")
+ lines.append(" → Use **S3 URL** (format: `s3:/nexent/attachments/xxx.pdf`)")
+ lines.append(" Reason: Internal tools run inside Nexent and can directly access MinIO storage")
+
+ return "\n".join(lines)
+
+
+def _format_managed_agents_description(
+ managed_agents: Dict[str, Any],
+ language: str = "zh",
+) -> str:
+ """Format managed sub-agent descriptions with calling specifications.
+
+ Jinja2 templates have ~15 lines of "内部助手调用规范" text that must be
+ included here for semantic equivalence.
+ """
+ if not managed_agents:
+ return ""
+
+ lines = []
+
+ if language == "zh":
+ lines.append("你可以使用以下内部助手（通过函数调用方式协作）：")
+ for name, agent in managed_agents.items():
+ desc = agent.description if hasattr(agent, 'description') else agent.get('description', '')
+ lines.append(f" - {name}: {desc}")
+ lines.append("")
+ lines.append("内部助手调用规范：")
+ lines.append(" 1. 调用方式：")
+ lines.append(" - 接受输入：{\"task\": {\"type\": \"string\", \"description\": \"任务描述\"}}")
+ lines.append(" - 返回输出类型：{\"type\": \"string\", \"description\": \"执行结果\"}")
+ lines.append(" 2. 使用策略：")
+ lines.append(" - 任务分解：单次调用中不要让助手一次做过多的事情，任务拆分是你的工作，你需要将复杂任务分解为可管理的子任务")
+ lines.append(" - 专业匹配：根据助手的专长分配任务")
+ lines.append(" - 信息整合：整合不同助手的输出生成连贯解决方案")
+ lines.append(" - 效率优化：避免重复工作")
+ lines.append(" 3. 协作要求：")
+ lines.append(" - 评估助手返回的结果")
+ lines.append(" - 必要时提供额外指导或重新分配任务")
+ lines.append(" - 在助手结果基础上进行工作，避免重复工作")
+ lines.append(" - 注意保留子助手回答中的特殊符号，如索引溯源信息等")
+ else:
+ lines.append("You can use the following internal agents (via function calls):")
+ for name, agent in managed_agents.items():
+ desc = agent.description if hasattr(agent, 'description') else agent.get('description', '')
+ lines.append(f" - {name}: {desc}")
+ lines.append("")
+ lines.append("Internal agent calling specifications:")
+ lines.append(" 1. Calling method:")
+ lines.append(" - Accepts input: {\"task\": {\"type\": \"string\", \"description\": \"task description\"}}")
+ lines.append(" - Returns output type: {\"type\": \"string\", \"description\": \"execution result\"}")
+ lines.append(" 2. Usage strategy:")
+ lines.append(" - Task decomposition: Don't let agents do too many things in a single call, task breakdown is your job, you need to decompose complex tasks into manageable subtasks")
+ lines.append(" - Professional matching: Assign tasks based on agent expertise")
+ lines.append(" - Information integration: Integrate outputs from different agents to generate coherent solutions")
+ lines.append(" - Efficiency optimization: Avoid duplicate work")
+ lines.append(" 3. Collaboration requirements:")
+ lines.append(" - Evaluate agent returned results")
+ lines.append(" - Provide additional guidance or reassign tasks when necessary")
+ lines.append(" - Work based on agent results, avoid duplicate work")
+ lines.append(" - Pay attention to preserving special symbols in sub-agent answers, such as index traceability information")
+
+ return "\n".join(lines)
+
+
+def _format_external_agents_description(
+ external_a2a_agents: Dict[str, Any],
+ language: str = "zh",
+) -> str:
+ """Format external A2A agent descriptions with calling specifications.
+
+ Jinja2 templates have ~5 lines of "外部助手调用规范" text that must be
+ included here for semantic equivalence.
+ """
+ if not external_a2a_agents:
+ return ""
+
+ lines = []
+
+ if language == "zh":
+ lines.append("你还可以使用以下外部助手（通过 A2A 协议远程调用）：")
+ for agent_id, agent in external_a2a_agents.items():
+ name = agent.name if hasattr(agent, 'name') else agent.get('name', '')
+ desc = agent.description if hasattr(agent, 'description') else agent.get('description', '')
+ lines.append(f" - {name}: {desc}")
+ lines.append("")
+ lines.append("外部助手调用规范：")
+ lines.append(" 1. 调用格式：`agent_name(task=\"自然语言任务描述\")`，注意：只需要 task 参数，不需要其他参数")
+ lines.append(" 2. 例如：`tool_assistant(task=\"北京天气怎么样\")`")
+ lines.append(" 3. 任务描述使用自然语言，让外部助手自动识别和处理")
+ else:
+ lines.append("You can also use the following external agents (called via A2A protocol remotely):")
+ for agent_id, agent in external_a2a_agents.items():
+ name = agent.name if hasattr(agent, 'name') else agent.get('name', '')
+ desc = agent.description if hasattr(agent, 'description') else agent.get('description', '')
+ lines.append(f" - {name}: {desc}")
+ lines.append("")
+ lines.append("External agent calling specifications:")
+ lines.append(" 1. Call format: `agent_name(task=\"natural language task description\")`, NOTE: only task parameter is needed, no other parameters")
+ lines.append(" 2. Example: `tool_assistant(task=\"What's the weather in Beijing?\")`")
+ lines.append(" 3. Use natural language for task description, let the external agent handle the rest")
+
+ return "\n".join(lines)
+
+
+def _format_skills_usage_requirements(
+ skills: List[Dict[str, str]],
+ language: str = "zh",
+) -> str:
+ """Format skills usage requirements section.
+
+ This is the "技能使用要求" section that appears after the skills reference
+ in the Available Resources section.
+ """
+ if not skills:
+ no_skills_msg = "- 当前没有可用的技能" if language == "zh" else "- No skills are currently available"
+ return no_skills_msg
+
+ lines = []
+
+ if language == "zh":
+ lines.append("- 你拥有上述 `代码'表达运行代码，使用'code' for executing code and '代码'格式；如果是不需要执行仅用于展示的代码，使用'code'. If the code does not need to be executed for display only, use '
+ 
+
+
+#### 🌐 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
+
+###### Integrate [DataAgent](https://gitcode.com/datagallery/dataagent) A2A Agent via URL
+
+1. Refer to the [DataAgent documentation](https://gitcode.com/datagallery/dataagent#%F0%9F%8C%90-a2a-10-%E6%9C%8D%E5%8A%A1%E6%A8%A1%E5%BC%8F) and start DataAgent in A2A service mode.
+ > Nexent does not currently support agents that require authentication. Do not set `auth-token` when starting DataAgent.
+
+
+
+ 
+
+
+2. Refer to [Discover Agent via URL](#discover-agent-via-url) to integrate the agent. The URL is `http://
+
+ 
+
+
+>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 +247,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 +299,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. 创建应用并获取 API Key
-4. 在环境中配置 TTS/STT 设置
+- 推荐使用**豆包语音合成模型2.0和大模型流式语音识别模型**
+- **开始使用**:
+
+ 1. 注册火山引擎账户
+ 2. 访问语音技术服务
+ 3. 创建应用并获取appid和token
+ 4. 在添加模型页面中配置 TTS/STT 设置
+
+**阿里灵积**
+- **网站**: [aliyun.com/benefit/scene/voice](https://www.aliyun.com/benefit/scene/voice)
+- 推荐使用**千问3-TTS-Instruct-Flash-Realtime/千问3-TTS-Flash-Realtime和千问3-ASR-Flash-Realtime**
+- **开始使用**:
+
+ 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/dataagent_deploy.png b/doc/docs/en/user-guide/assets/agent-development/dataagent_deploy.png
new file mode 100644
index 000000000..46fa9fde3
Binary files /dev/null and b/doc/docs/en/user-guide/assets/agent-development/dataagent_deploy.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/local-tools/index.md b/doc/docs/en/user-guide/local-tools/index.md
index 27dc72ebc..9006f415c 100644
--- a/doc/docs/en/user-guide/local-tools/index.md
+++ b/doc/docs/en/user-guide/local-tools/index.md
@@ -9,6 +9,8 @@ Local tools let agents interact with the workspace, remote hosts, and external s
- [Search Tools](./search-tools): Local/DataMate KB search plus Exa/Tavily/Linkup web search.
- [Multimodal Tools](./multimodal-tools): Download/parse/analyze text files and images.
- [Terminal Tool](./terminal-tool): Persistent SSH sessions for remote commands.
+- [SQL Tools](./sql-tools): Connect to MySQL, PostgreSQL, SQL Server to execute SQL queries.
+- [Skills](../skills): Nexent's built-in tool combinations or custom capability packs with NL generation and version management.
## ⚙️ Configuration Entry
diff --git a/doc/docs/en/user-guide/local-tools/multimodal-tools.md b/doc/docs/en/user-guide/local-tools/multimodal-tools.md
index 6780f5f1e..986682c40 100644
--- a/doc/docs/en/user-guide/local-tools/multimodal-tools.md
+++ b/doc/docs/en/user-guide/local-tools/multimodal-tools.md
@@ -4,18 +4,22 @@ title: Multimodal Tools
# Multimodal Tools
-Multimodal tools analyze text files and images with model support. URLs can be S3, HTTP, or HTTPS.
+Multimodal tools analyze text files, images, videos, and audio with model support. URLs can be S3, HTTP, or HTTPS.
## 🧭 Tool List
- `analyze_text_file`: Download and extract text, then analyze per question
- `analyze_image`: Download images and interpret them with a vision-language model
+- `analyze_video`: Download videos and analyze them with a video understanding model
+- `analyze_audio`: Download audio and analyze it with an audio understanding model
## 🧰 Example Use Cases
- Summarize documents stored in buckets
- Explain screenshots, product photos, or chart images
-- Produce per-file or per-image answers aligned with the input order
+- Understand video content, such as extracting key frame information, human actions, or scene descriptions
+- Analyze audio content, such as transcription, speaker identification, or content summarization
+- Produce per-file or per-image/video/audio answers aligned with the input order
## 🧾 Parameters & Behavior
@@ -29,16 +33,26 @@ Multimodal tools analyze text files and images with model support. URLs can be S
- `query`: User focus/question.
- Downloads each image, runs VLM analysis, and returns an array matching input order.
+### analyze_video
+- `video_url`: Video URL (`s3://bucket/key`, `/bucket/key`, `http(s)://`).
+- `query`: User focus/question.
+- Downloads the video, runs video understanding model analysis, and returns the result.
+
+### analyze_audio
+- `audio_url`: Audio URL (`s3://bucket/key`, `/bucket/key`, `http(s)://`).
+- `query`: User focus/question.
+- Downloads the audio, runs audio understanding model analysis, and returns the result.
+
## ⚙️ Prerequisites
- Configure storage access (e.g., MinIO/S3) and data processing service to fetch files.
-- Provide an LLM for `analyze_text_file` and a VLM for `analyze_image`.
+- Provide an LLM for `analyze_text_file`, a VLM for `analyze_image`, and a video understanding model for `analyze_video` and `analyze_audio` (must support audio/video input, e.g., Qwen3-Omni series).
## 🛠️ How to Use
-1. Prepare accessible URLs and confirm permissions.
-2. Call the corresponding tool with the URL list and question; multiple resources are supported at once.
-3. Use results in the same order as inputs for display or follow-up steps.
+1. Prepare accessible URLs for files, images, videos, or audio; confirm permissions.
+2. Call the corresponding tool with the URL and question; multiple resources are supported at once.
+3. Verify results before using them in follow-up steps.
## 💡 Best Practices
diff --git a/doc/docs/en/user-guide/local-tools/sql-tools.md b/doc/docs/en/user-guide/local-tools/sql-tools.md
new file mode 100644
index 000000000..859b5fbba
--- /dev/null
+++ b/doc/docs/en/user-guide/local-tools/sql-tools.md
@@ -0,0 +1,78 @@
+---
+title: SQL Database Tools
+---
+
+# SQL Database Tools
+
+The SQL database toolset enables AI agents to connect to and query relational databases such as MySQL, PostgreSQL, and SQL Server, allowing direct data access and manipulation.
+
+## Tool List
+
+- `mysql_database`: Connect to MySQL and execute SQL queries
+- `postgres_database`: Connect to PostgreSQL and execute SQL queries
+- `mssql_database`: Connect to SQL Server and execute SQL queries
+
+## Usage Scenarios
+
+- Query report data from business databases for agent analysis and summarization
+- Cross-database joins to retrieve related information scattered across multiple tables
+- Real-time queries of business status to provide agents with up-to-date data
+
+## Parameters and Behavior
+
+### Common Parameters
+
+- `sql`: The SQL query to execute (required)
+- `parameters`: Parameter values for parameterized queries (optional)
+- `max_rows`: Maximum number of rows to return (default: 100)
+- `timeout`: Query timeout in seconds (default: 10)
+
+### Database Connection Parameters
+
+| Database | Connection Parameters |
+|-------------|---------------------------------------------------------------------------|
+| MySQL | `host`, `user`, `password`, `database`, `port` (default 3306) |
+| PostgreSQL | `host`, `user`, `password`, `database`, `port` (default 5432) |
+| SQL Server | `host`, `user`, `password`, `database`, `port` (default 1433) |
+
+### Security Restrictions
+
+- Forbidden operations: `DROP DATABASE`, `GRANT`, `REVOKE`, `CREATE USER`, `INTO OUTFILE`, `LOAD DATA INFILE`
+- `UPDATE` and `DELETE` statements must include a `WHERE` clause
+- `LIMIT` is automatically added to restrict returned rows
+
+### Response Format
+
+```json
+{
+ "status": "success",
+ "columns": ["id", "name", "email"],
+ "rows": [[1, "John Doe", "john@example.com"]],
+ "row_count": 1,
+ "execution_time_ms": 45.23
+}
+```
+
+## Getting Started
+
+1. **Prepare connection info**: Obtain host address, port, database name, username, and password
+2. **Configure the tool**: Add the appropriate database tool in agent configuration and fill in connection parameters
+3. **Test connection**: Use a simple query to verify connectivity
+4. **Construct queries**: Let the agent understand natural language requirements and generate corresponding SQL
+
+## Security Best Practices
+
+- Use read-only accounts in production to limit operation permissions
+- Store sensitive information like database passwords in a key management service
+- Set reasonable `max_rows` values to avoid returning excessive data at once
+- Enable SSL/TLS encryption for database connections
+
+## Common Database Connection Examples
+
+| Database | Connection Example | Parameter Placeholder |
+|-------------|-------------------|---------------------|
+| MySQL | `localhost:3306` | `?` |
+| PostgreSQL | `localhost:5432` | `$1, $2, ...` |
+| SQL Server | `localhost:1433` | `?` |
+
+> Note: Different databases use different parameter placeholder formats. PostgreSQL uses `$1, $2`, while others use `?`.
diff --git a/doc/docs/en/user-guide/mcp-tools.md b/doc/docs/en/user-guide/mcp-tools.md
index b55859cbe..cd1190e0e 100644
--- a/doc/docs/en/user-guide/mcp-tools.md
+++ b/doc/docs/en/user-guide/mcp-tools.md
@@ -1,28 +1,159 @@
# MCP Tools
-The upcoming MCP Tools management module will let you centrally manage MCP servers and tools on a single page, easily completing connection configuration, tool synchronization, and health status monitoring.
+In the MCP Tools module, you can centrally manage all MCP (Model Context Protocol) servers and tools. It supports custom addition, Registry import, and Community import, covering connection configuration, tool synchronization, health monitoring, and community sharing.
-## 🎯 Feature Preview
+The MCP Tools page has two parallel tabs:
-1. Register and manage multiple MCP servers
-2. Quickly sync, view, and organize MCP tool lists
-3. Monitor MCP connection status and usage in real time
+- **Imported Services**: Manage MCP services already accessed by the current tenant — configure, monitor, and maintain your MCP services here.
+- **Published Services**: Manage the MCP services you have published to the community — browse, edit, and unpublish.
-## ⏳ Stay Tuned
+---
-The MCP Tools management feature is under development. We are committed to building an efficient and intuitive management platform that enables you to:
+## ➕ Add MCP Services
-1. Centrally manage all MCP servers
-2. Conveniently sync and organize tools
-3. Monitor server connections and tool runtime status in real time
+Click the **Add MCP Service** button to open the add dialog. The dialog provides three tabs, each corresponding to a different source.
-## 🚀 Related Features
+### Local Add
-While waiting for **MCP Tools** to launch, you can:
+The **Local Add** tab lets you manually configure an MCP service with two transport types.
-1. Manage your MCP tools in **[Agent Development](./agent-development)**
-2. View agent and MCP collaboration relationships through **[Agent Space](./agent-space)**
-3. Experience platform features in **[Start Chat](./start-chat)**
+#### Add via URL
-If you encounter any issues during use, please refer to our **[FAQ](../quick-start/faq)** or ask for support in [GitHub Discussions](https://github.com/ModelEngine-Group/nexent/discussions).
+For independently deployed MCP services (HTTP / SSE), connect by entering the endpoint URL.
+
+1. In the **Local Add** tab, set **Transport Type** to "URL"
+2. Fill in the service details:
+ - **Service Name (required)**: A recognizable name for the MCP service
+ - **Service URL (required)**: The MCP service endpoint address
+ - **Description** (optional): A brief description of the service
+ - **Authorization Token** (optional): Bearer token if the service requires authentication
+3. Click **Confirm** — the system will connect to the service and retrieve the available tool list
+
+#### Add via Container Configuration
+
+For MCP services that need to run locally in a container (e.g., services launched via npx), the system automatically creates and manages a container based on your JSON configuration.
+
+1. In the **Local Add** tab, set **Transport Type** to "Container"
+2. Fill in the container configuration:
+ - **Service Name (required)**: A recognizable name for the MCP service
+ - **Description** (optional): A brief description of the service
+ - **Container Configuration JSON (required)**: Enter the standard MCP configuration format, for example:
+ ```json
+ {
+ "mcpServers": {
+ "service-name": {
+ "args": ["mcp-package-name@version"],
+ "command": "npx",
+ "env": {
+ "API_KEY": "xxxx"
+ }
+ }
+ }
+ }
+ ```
+ - **Port**: The port exposed by the container service — the system automatically detects port conflicts and suggests available ports
+3. Click **Confirm** — the system parses the JSON, creates the container, and registers the service
+
+### Import from MCP Registry
+
+Nexent integrates with the MCP Registry, allowing you to browse and import community-maintained MCP services in one click.
+
+1. Switch to the **MCP Registry** tab
+2. Browse the available MCP services — search by name or tags
+3. Click a service to view its details (description, version, required parameters, etc.)
+4. Configure required parameters (e.g., API Key and other environment variables)
+5. Click **Import** — the system automatically installs and configures the service
+
+### Import from Community
+
+Browse MCP services published by other Nexent users and quickly import them.
+
+1. Switch to the **Community Market** tab
+2. Browse published community MCP services — filter by name, tags, or transport type
+3. Click a service to view details, then click **Import** to add it to your service list
+
+---
+
+## 📋 Imported Services
+
+The **Imported Services** tab displays all MCP services accessed by the current tenant as cards. View, edit, monitor, and publish your services here.
+
+### View & Filter
+
+Each service card shows:
+
+- Service name and description
+- Source indicator (Custom / Registry / Community)
+- Enable / Disable toggle
+- Tags
+
+Use the filter bar at the top to filter by **Source**, **Transport Type**, and **Tags**, or use the search box to quickly locate services by name.
+
+### Edit Service Details
+
+Click any service card to open the detail modal, where you can:
+
+- **Edit basic info**: Modify name, description, URL, Authorization Token, and tags
+- **Enable / Disable**: Toggle the service on or off — tools from a disabled service will not appear in agent tool selection
+- **Delete**: Remove the MCP service record — containerized services will also have their container resources cleaned up
+
+### View Tool List
+
+In the service detail modal, click **Tool List** to view all tools provided by this MCP service.
+
+### Health Check
+
+Click the **Health Check** button in the detail modal to test the connection to the MCP service. Possible statuses:
+
+- **Healthy**: The service is reachable
+- **Unhealthy**: The service cannot be reached or responded abnormally
+- **Unchecked**: A health check has not been performed yet
+
+### Container Management
+
+For containerized MCP services, the detail modal also provides:
+
+- **View Container Logs**: Real-time logs from the running container for troubleshooting
+- **View Container Config**: The configuration JSON used when creating the container
+
+### Publish to Community
+
+In the service detail modal, click **Publish to Community**:
+
+1. Review or edit the publication info (name, description, tags, etc.)
+2. Click **Confirm Publish** — the service will be published to the community
+3. Other users can then browse and import it from the **Community Market** tab in the add dialog
+
+---
+
+## 🌐 Published Services
+
+The **Published Services** tab shows all MCP services you have published to the community. Manage your published content here.
+
+Each card shows the service name, description, version, and tags. Filter by name, tags, and transport type.
+
+Click a service card to view details, where you can:
+
+- **Edit published service**: Modify the published service's name, description, and tags
+- **Delete published service**: Withdraw the service from the community — it will no longer be visible to other users
+
+---
+
+## 🔗 Integrating with Agents
+
+Once an MCP service is added, its tools are automatically synced to the agent tool selection list. When configuring an agent on the **[Agent Development](./agent-development)** page:
+
+1. In the **Select Agent Tools** tab, locate the corresponding MCP service group
+2. Click a tool name to enable it
+3. Click ⚙️ to view the tool description and configure its parameters
+
+## 🚀 Next Steps
+
+After configuring MCP services, we recommend:
+
+1. **[Agent Development](./agent-development)** — Assign MCP tools to your agents
+2. **[Agent Space](./agent-space)** — View collaboration between agents and MCP services
+3. **[Start Chat](./start-chat)** — Experience agents calling MCP tools in conversations
+
+If you encounter any issues, please refer to our **[FAQ](../quick-start/faq)** or ask for support in [GitHub Discussions](https://github.com/ModelEngine-Group/nexent/discussions).
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/deployment/devcontainer.md b/doc/docs/zh/deployment/devcontainer.md
index 2ce184901..b5b934187 100644
--- a/doc/docs/zh/deployment/devcontainer.md
+++ b/doc/docs/zh/deployment/devcontainer.md
@@ -25,7 +25,7 @@
1. 克隆项目到本地
2. 在 Cursor 中打开项目文件夹
-3. 运行 `docker/deploy.sh` 脚本，在`infrastructure` 模式下启动容器
+3. 在 `docker` 目录运行 `./deploy.sh --components infrastructure,application --port-policy development` 启动基础容器
4. 进入 `nexent-minio` 与 `nexent-elasticsearch` 容器, 将 `MINIO_ACCESS_KEY`, `MINIO_SECRET_KEY`, `ELASTICSEARCH_API_KEY` 环境变量复制到 `docker/docker-compose.dev.yml` 中的相应环境变量位置
5. 按下 `F1` 或 `Ctrl+Shift+P`，输入 `Dev Containers: Reopen in Container ...`
6. Cursor 将根据 `.devcontainer` 目录中的配置启动开发容器
diff --git a/doc/docs/zh/deployment/docker-build.md b/doc/docs/zh/deployment/docker-build.md
index 8dad0612e..8e360d95d 100644
--- a/doc/docs/zh/deployment/docker-build.md
+++ b/doc/docs/zh/deployment/docker-build.md
@@ -160,6 +160,11 @@ docker rm nexent-docs
## 🚀 部署建议
-构建完成后，可以使用 `docker/deploy.sh` 脚本进行部署，或者直接使用 `docker-compose` 启动服务。
+构建完成后，可以进入 `docker` 目录使用部署脚本启动本地镜像：
-> 启动测试本地构建的镜像时，需要修改下`docker/deploy.sh`中的`APP_VERSION="$(get_app_version)"` -> `APP_VERSION="latest"`，因为部署时默认会使用当前版本对应的镜像。
\ No newline at end of file
+```bash
+cd docker
+bash deploy.sh --image-source local-latest
+```
+
+> `local-latest` 会使用本地 `latest` Nexent 应用镜像并避免重新拉取这些镜像，无需修改 `docker/deploy.sh`。
diff --git a/doc/docs/zh/developer-guide/environment-setup.md b/doc/docs/zh/developer-guide/environment-setup.md
index 0a81ca10d..cc98ff58a 100644
--- a/doc/docs/zh/developer-guide/environment-setup.md
+++ b/doc/docs/zh/developer-guide/environment-setup.md
@@ -23,7 +23,7 @@ title: 环境准备
```bash
# 在项目根目录的 docker 目录执行
cd docker
-./deploy.sh --mode infrastructure
+./deploy.sh --components infrastructure --port-policy development
```
:::: info 重要提示
@@ -131,4 +131,3 @@ uv pip install -e ".[dev]"
- 测试框架（pytest）
- 数据处理依赖（unstructured）
- 其他开发辅助依赖
-
diff --git a/doc/docs/zh/getting-started/features.md b/doc/docs/zh/getting-started/features.md
index 8d1adf47c..658a89e18 100644
--- a/doc/docs/zh/getting-started/features.md
+++ b/doc/docs/zh/getting-started/features.md
@@ -1,45 +1,74 @@
# 核心特性
-Nexent 提供强大的功能来构建和部署 AI 智能体，只需最少的工作量。以下是让 Nexent 独特的核心特性。
+Nexent v2.0 提供了强大的 AI 智能体构建与部署能力，以下是让 Nexent 与众不同的核心特性。
-## 🧠 智能体提示词生成
+## ⚙️ 多模型集成
-将自然语言转换为可执行的提示词。Nexent 自动选择正确的工具并为每个请求规划最佳的执行路径。
+Nexent 支持 OpenAI 兼容任意模型提供商，一站式覆盖 LLM、Embedding、VLM、STT、TTS 全类型模型。支持与 ModelEngine 平台无缝同步。平台支持接入任意兼容 OpenAI API 协议的服务商，轻松实现模型多样化与国产化切换。
-
+## 🤖 智能体零代码生成
-## ⚡ 可扩展的数据处理引擎
+只需用自然语言描述你的需求，Nexent 便能自动将意图转化为可执行的智能体配置。系统会智能选择合适的工具，规划最优的执行路径，并生成专业的提示词。无需编写代码，无需拖拽配置，真正实现"所想即所得"的智能体创建体验。同时支持智能体导入导出，方便分享与复用；提供在线调试能力，边调边改，快速迭代。
-处理 20+ 种数据格式，具备快速 OCR 和表格结构提取能力，从单一流程平滑扩展到大批量管道处理。
+## 🤝 A2A 协议与智能体协作
-
+Nexent 支持 **Agent-to-Agent（A2A）** 通信协议，让多个智能体能够无缝协作。主智能体可以调用子智能体完成特定任务，子智能体执行完成后将结果汇总给主智能体。支持配置多个协作型子智能体，每个子智能体可拥有独立的工具集、模型配置和执行策略，轻松构建复杂的分布式智能体工作流。
-## 📚 个人级知识库
+## 🧠 分层记忆机制
-实时导入文件，自动总结内容，让智能体能够即时访问个人和全局知识，并知道从每个知识库能获取什么。
+智能的上下文管理是智能体真正"懂你"的关键。Nexent 提供两层记忆体系：
-
+- **用户级记忆**：个人偏好、习惯和使用方式
+- **用户-智能体级记忆**：特定用户在特定智能体中的协作历史与上下文
-## 🌐 互联网知识搜索
+系统自动从对话中提取关键信息生成记忆条目，无需手动输入；记忆条目支持手工添加修改，更加灵活；智能检索机制确保每次对话都能自动获取最相关的上下文记忆，实现真正的个性化服务。
-连接 5+ 个网络搜索提供商，让智能体能够将最新的互联网信息与你的私有数据相结合。
+## 📝 Skill 渐进式披露
-
+Nexent 引入了 **渐进式 Skill 披露**机制。当用户输入任务时，系统会根据当前上下文动态揭示最相关的 Skill 建议，帮助用户快速找到适合当前任务的工具和方法。这一机制能够防止上下文爆炸，高效利用上下文窗口。
-## 🔍 知识级溯源
+## 🗄️ 个人级知识库
-提供来自网络和知识库来源的精确引用，让每个事实都可验证。
+支持用户在 Nexent 平台创建个人知识库，支持实时导入文件，自动解析并向量化内容，让智能体能够即时访问私有数据。支持 20+ 种文档格式，包括文本、PDF、Word、PowerPoint、Excel、CSV 等，并提供快速 OCR 和表格结构提取能力。自动为每个知识库生成摘要，帮助智能体准确判断何时应该从该知识库检索信息。可设置细粒度的访问权限：私有、部门级共享或全组织可见。
-
+## 🔧 MCP 工具生态系统
-## 🎭 多模态理解与对话
+Nexent 基于 **Model Context Protocol（MCP）** 构建工具生态，MCP 被誉为"AI 的 USB-C"，是连接 AI 智能体与外部世界的通用接口标准。
-支持语音、文字、文件或图像输入。Nexent 理解语音、文本和图片，甚至可以按需生成新图像。
+- 支持通过 URL 或 JSON 配置快速添加第三方 MCP 服务
+- 支持本地 MCP 工具开发，可接入 LangChain 工具、自定义 Python 插件
+- 可热插拔地更换工具、模型和工具链，无需触碰核心代码
+- 内置工具测试能力，创建智能体前即可验证工具是否按预期工作
-
+## 🌐 互联网知识集成
-## 🔧 MCP 工具生态系统
+连接多个网络搜索提供商，让智能体能够将最新鲜的互联网信息与私有数据相结合。支持混合搜索模式，兼顾实时性和准确性。
+
+## 🔍 知识溯源与引用
+
+每个回答都附带精确的引用来源，来自网络搜索结果或知识库文档，让每个事实都透明可查。来源信息可一键追溯，增强回答的可信度。
+
+## 🎭 多模态交互
+
+支持语音、文本、图像和文件多种输入方式。智能体能够理解语音、文本和图片，可以按需生成新图像，提供真正自然的多模态对话体验。
+
+## 🔢 智能体版本管理
+
+完善的版本控制体系，支持智能体的版本迭代与历史回溯。每个版本独立存档，可随时查看变更历史、比较版本差异，并在必要时回退到历史版本。支持智能体配置导入导出（JSON 格式），方便跨环境迁移和团队协作。
+
+## 🏪 智能体市场
+
+内置智能体市场，汇聚官方和社区创建的优质智能体。一键下载即可使用，也可将其作为子智能体集成到自己的智能体工作流中，快速构建复杂应用。
+
+## 👥 分权分域与用户管理
+
+Nexent 提供完善的多租户、分角色权限管理体系：
+
+- **四层角色**：超级管理员、租户管理员、开发者、普通用户，职责分明
+- **多租户隔离**：租户间数据完全隔离，支持跨租户的平台级管理
+- **用户组机制**：通过用户组管理资源和访问权限，支持灵活的权限委托
+- **邀请码机制**：受控注册，保障平台安全性
+- **资源级权限**：智能体、知识库等资源可精细控制到用户组级别
-插入或构建遵循 MCP 规范的 Python 插件；在不触及核心代码的情况下交换模型、工具和链。
+关于 Nexent 软件架构和技术优势的详细信息，请参阅我们的**[软件架构](./software-architecture)**指南。
-
diff --git a/doc/docs/zh/getting-started/overview.md b/doc/docs/zh/getting-started/overview.md
index e5bc95549..77aa78f71 100644
--- a/doc/docs/zh/getting-started/overview.md
+++ b/doc/docs/zh/getting-started/overview.md
@@ -17,10 +17,10 @@ Nexent 是一个基于 **Harness Engineering** 原则打造的零代码智能体
> *If you want to go fast, go alone; if you want to go far, go together.*
-我们已经发布了 **Nexent v1**，目前功能已经相对稳定，但仍可能存在一些 bug，我们会持续改进并不断增加新功能。敬请期待，我们很快也会公布 **v2.0** 版本！
+我们已发布 **Nexent v2.0**！在 v1.0 的基础上全面升级，带来 A2A 协议支持、Skill 渐进式披露、分层记忆机制、用户管理与分权分域、智能体版本管理、智能体市场等重磅功能。同时保留并强化了知识库集成、多模态交互、MCP 工具生态等核心能力。平台功能日趋完善，欢迎试用并提出您的宝贵意见。
-* **🗺️ 查看我们的 [功能地图](https://github.com/orgs/ModelEngine-Group/projects/6)** 探索当前和即将推出的功能。
-* **🔍 试用当前版本** 并在 [问题反馈](https://github.com/ModelEngine-Group/nexent/issues) 中留下想法或报告错误。
+- **🗺️ 查看我们的 [功能地图](https://github.com/orgs/ModelEngine-Group/projects/6)** 探索当前和即将推出的功能。
+- **🔍 试用当前版本** 并在 [问题反馈](https://github.com/ModelEngine-Group/nexent/issues) 中留下想法或报告错误。
> *Rome wasn't built in a day.*
@@ -28,19 +28,25 @@ Nexent 是一个基于 **Harness Engineering** 原则打造的零代码智能体
早期贡献者不会被忽视：从特殊徽章和纪念品到其他实质性奖励，我们致力于感谢那些帮助 Nexent 诞生的先驱者。
-最重要的是，我们需要关注度。请 [前往GitHub](https://github.com/ModelEngine-Group/nexent) 为我们点星 ⭐ 并关注，与朋友分享，帮助更多开发者发现 Nexent —— 您的每一次点击都能为项目带来新的参与者，保持发展势头。
+最重要的是，我们需要关注度。请 [前往 GitHub](https://github.com/ModelEngine-Group/nexent) 为我们点星 ⭐ 并关注，与朋友分享，帮助更多开发者发现 Nexent —— 您的每一次点击都能为项目带来新的参与者，保持发展势头。
## ✨ 核心特性
-Nexent 为构建强大的 AI 智能体提供全面的功能集：
-
-- **🤖 智能体生成** - 使用自然语言进行零代码智能体创建
-- **📊 可扩展数据处理** - 处理 20+ 种文件格式和智能提取
-- **🧠 个人知识库** - 实时文件导入和自动摘要
-- **🌐 互联网集成** - 连接多个搜索提供商和网络资源
-- **🔍 知识溯源** - 精确引用和来源验证
-- **🎭 多模态支持** - 语音、文本、图像和文件处理
-- **🔧 MCP 生态系统** - 可扩展的工具集成和自定义开发
+Nexent v2.0 为构建强大的 AI 智能体提供全面的功能集：
+
+- **⚙️ 多模型集成** — OpenAI 兼容任意提供商，Embedding/VLM/STT/TTS 全覆盖
+- **🤖 智能体零代码生成** — 纯自然语言描述需求，一键生成可执行智能体
+- **🤝 A2A 智能体协作** — Agent-to-Agent 协议支持多智能体无缝协作
+- **🧠 分层记忆机制** — 两层记忆体系，跨对话持续积累上下文
+- **📝 Skill 渐进式披露** — 动态揭示最相关工具，渐进探索系统能力
+- **🗄️ 个人级知识库** — 20+ 格式文档实时导入与智能检索
+- **🔧 MCP 工具生态** — 即插即用的扩展工具体系，可自定义开发
+- **🌐 互联网知识集成** — 多搜索源混合，实时信息与私有数据融合
+- **🔍 知识级溯源** — 精确引用与来源验证，每个事实透明可查
+- **🎭 多模态交互** — 语音、文字、图像、文件，全方位自然对话
+- **🔢 智能体版本管理** — 版本迭代与历史回溯，安全可控
+- **🏪 智能体市场** — 官方与社区优质智能体，一键安装即用
+- **👥 分权分域管理** — 多租户隔离，RBAC 权限体系，精细化资源管控
有关详细的功能信息和示例，请参阅我们的 **[核心特性](./features)**。
@@ -49,20 +55,23 @@ Nexent 为构建强大的 AI 智能体提供全面的功能集：
Nexent 采用现代化的分布式微服务架构，专为高性能、可扩展的 AI 智能体平台而设计。整个系统基于容器化部署，支持云原生和企业级应用场景。
### 🌐 分层架构设计
-- **前端层** - Next.js + React + TypeScript 构建的现代化用户界面
-- **API 网关层** - FastAPI 高性能 Web 框架，负责请求路由和负载均衡
-- **业务逻辑层** - 智能体管理、对话管理、知识库管理和模型管理
-- **数据层** - PostgreSQL、Elasticsearch、Redis、MinIO 分布式存储架构
+
+- **前端层** — Next.js + React + TypeScript 构建的现代化用户界面
+- **API 网关层** — FastAPI 高性能 Web 框架，负责请求路由和负载均衡
+- **业务逻辑层** — 智能体管理、对话管理、知识库管理和模型管理
+- **数据层** — PostgreSQL、Elasticsearch、Redis、MinIO 分布式存储架构
### 🚀 核心服务架构
-- **智能体服务** - 基于 SmolAgents 框架的智能体生成和执行
-- **数据处理服务** - 支持 20+ 种文件格式的实时和批量处理
-- **MCP 生态系统** - 标准化的工具接口和插件架构
+
+- **智能体服务** — 基于 SmolAgents 框架的智能体生成和执行
+- **数据处理服务** — 支持 20+ 种文件格式的实时和批量处理
+- **MCP 生态系统** — 标准化的工具接口和插件架构
### ⚡ 分布式特性
-- **异步处理** - 基于 asyncio 的高性能异步处理架构
-- **微服务设计** - 服务解耦，独立扩展和部署
-- **容器化部署** - Docker Compose 服务编排，支持云原生部署
+
+- **异步处理** — 基于 asyncio 的高性能异步处理架构
+- **微服务设计** — 服务解耦，独立扩展和部署
+- **容器化部署** — Docker Compose 服务编排，支持云原生部署
有关详细的架构设计和技术实现，请参阅我们的 **[软件架构](./software-architecture)**。
@@ -70,9 +79,9 @@ Nexent 采用现代化的分布式微服务架构，专为高性能、可扩展
准备好开始了吗？以下是您的下一步：
-1. **📋 [安装部署](../quick-start/installation)** - 系统要求和部署指南
-2. **🔧 [开发者指南](../developer-guide/overview)** - 从源码构建和自定义
-3. **❓ [常见问题](../quick-start/faq)** - 常见问题和故障排除
+1. **📋 [安装部署](../quick-start/installation)** — 系统要求和部署指南
+2. **🔧 [开发者指南](../developer-guide/overview)** — 从源码构建和自定义
+3. **❓ [常见问题](../quick-start/faq)** — 常见问题和故障排除
## 💬 社区与联系方式
diff --git a/doc/docs/zh/getting-started/software-architecture.md b/doc/docs/zh/getting-started/software-architecture.md
index 620d476ef..8676992a4 100644
--- a/doc/docs/zh/getting-started/software-architecture.md
+++ b/doc/docs/zh/getting-started/software-architecture.md
@@ -11,156 +11,284 @@ Nexent 的软件架构遵循分层设计原则，从上到下分为以下几个
### 🌐 前端层（Frontend Layer）
- **技术栈**：Next.js + React + TypeScript
- **功能**：用户界面、智能体交互、多模态输入处理
-- **特性**：响应式设计、实时通信、国际化支持
+- **特性**：响应式设计、WebSocket 实时通信、国际化（i18n）支持
### 🔌 API 网关层（API Gateway Layer）
-- **核心服务**：FastAPI 高性能 Web 框架
-- **职责**：请求路由、身份验证、API 版本管理、负载均衡
-- **端口**：5010（主服务）、5012（数据处理服务）
+基于 FastAPI 构建的分布式 API 服务：
+
+| 服务 | 端口 | 说明 |
+|------|------|------|
+| **nexent-config** | 5010 | 主 API 服务 - 智能体 CRUD、配置管理 |
+| **nexent-runtime** | 5014 | 运行时服务 - 智能体执行、流式响应 |
+| **nexent-mcp** | 5011/5015 | MCP 服务 - 工具协议管理、FastMCP 服务器 |
+| **nexent-northbound** | 5013 | 外部 API 服务 - A2A 协议、合作伙伴集成 |
+| **nexent-data-process** | 5012 | 数据处理服务 - 文档解析、向量化 |
### 🧠 业务逻辑层（Business Logic Layer）
-- **智能体管理**：智能体生成、执行、监控
-- **会话管理**：多轮对话、上下文维护、历史记录
-- **知识库管理**：文档处理、向量化、检索
-- **模型管理**：多模型支持、健康检查、负载均衡
+后端采用清晰的分层架构：
+
+#### App 层（`backend/apps/`）
+- **职责**：HTTP 边界层 - 解析/验证输入、调用服务、映射错误到 HTTP
+- **核心模块**：
+ - `agent_app.py` - 智能体 CRUD、版本管理、流式执行
+ - `conversation_management_app.py` - 多轮对话、历史追踪
+ - `model_managment_app.py` - 模型配置、健康检查
+ - `skill_app.py` - 技能创建与管理
+ - `knowledge_summary_app.py` - 知识库操作
+ - `remote_mcp_app.py` - 远程 MCP 工具管理
+ - `a2a_client_app.py` / `a2a_server_app.py` - A2A 协议支持
+
+#### Service 层（`backend/services/`）
+- **职责**：核心业务逻辑编排，协调仓库/SDK
+- **核心模块**：
+ - `agent_service.py` - 智能体生命周期、执行编排、记忆管理
+ - `agent_version_service.py` - 版本发布、回滚、对比
+ - `model_management_service.py` - 多模型支持、负载均衡
+ - `memory_config_service.py` - 记忆配置、上下文构建
+ - `conversation_management_service.py` - 会话管理、历史持久化
+ - `skill_service.py` - 技能生成、模板处理
+ - `data_process_service.py` - 文档处理管道
+ - `mcp_container_service.py` - MCP 容器生命周期管理
+ - `remote_mcp_service.py` - 远程 MCP 服务器集成
+ - `a2a_client_service.py` / `a2a_server_service.py` - A2A 智能体通信
+ - `redis_service.py` - 缓存、分布式锁、会话存储
+
+#### 智能体核心层（`backend/agents/`）
+- **职责**：基于 SmolAgents 的智能体执行框架
+- **核心组件**：
+ - `agent_run_manager.py` - 智能体运行生命周期、流式协调
+ - `create_agent_info.py` - 智能体配置构建、工具集成
+ - `preprocess_manager.py` - 文档预处理编排
+ - `skill_creation_agent.py` - LLM 驱动的技能生成
### 📊 数据层（Data Layer）
分布式数据存储架构，包含多种专用数据库：
#### 🗄️ 结构化数据存储
-- **PostgreSQL**：主数据库，存储用户信息、智能体配置、会话记录
-- **端口**：5434
-- **特性**：ACID 事务、关系型数据完整性
-
-#### 🔍 搜索引擎
-- **Elasticsearch**：向量数据库和全文搜索引擎
-- **端口**：9210
-- **功能**：向量相似度搜索、混合搜索、大规模优化
+- **PostgreSQL**（端口 5434）：主关系型数据库
+ - 用户和租户管理（`user_tenant_db.py`）
+ - 智能体配置和版本（`agent_db.py`、`agent_version_db.py`）
+ - 工具定义和实例（`tool_db.py`）
+ - 对话历史（`conversation_db.py`）
+ - 群组和权限管理（`group_db.py`、`role_permission_db.py`）
+ - 记忆配置（`memory_config_db.py`）
+ - 技能定义（`skill_db.py`）
+- **特性**：ACID 事务、关系完整性、多租户支持
+
+#### 🔍 向量搜索与全文搜索
+- **Elasticsearch**（端口 9210）：向量和全文搜索引擎
+ - 知识库存储（`knowledge_db.py`）
+ - 向量相似度搜索、混合搜索
+ - 语义分块和索引
+- **特性**：可扩展搜索、相关性排序、大规模优化
#### 💾 缓存层
-- **Redis**：高性能内存数据库
-- **端口**：6379
-- **用途**：会话缓存、临时数据、分布式锁
+- **Redis**（端口 6379）：高性能内存数据库
+ - 会话缓存
+ - 临时数据存储
+ - 分布式锁（`redis_service.py`）
+ - Celery 任务队列的消息代理
+- **特性**：亚毫秒级延迟、AOF 持久化
#### 📁 对象存储
-- **MinIO**：分布式对象存储服务
-- **端口**：9010
-- **功能**：文件存储、多媒体资源管理、大文件处理
+- **MinIO**（端口 9010/9011）：分布式对象存储
+ - 文件上传和附件（`attachment_db.py`）
+ - 知识库文档存储
+ - 预览生成和临时文件
+- **特性**：S3 兼容 API、大文件处理
## 🔧 核心服务架构
### 🤖 智能体服务（Agent Services）
```
-智能体框架基于 SmolAgents，提供：
-├── 智能体生成与配置
-├── 工具调用与集成
-├── 推理与决策执行
+智能体框架（基于 SmolAgents）：
+├── 智能体创建与配置
+│ ├── 名称/显示名生成（LLM 驱动）
+│ ├── 工具集成与选择
+│ ├── 子智能体关系管理
+│ └── 版本控制与发布
+├── 智能体执行引擎
+│ ├── 流式响应（SSE）
+│ ├── 工具调用与编排
+│ ├── 多模型支持（LLM + 业务逻辑）
+│ └── 记忆上下文构建
+├── 版本管理
+│ ├── 发布与回滚
+│ ├── 版本对比
+│ └── A2A 智能体卡片注册
└── 生命周期管理
+ ├── 运行注册与追踪
+ ├── 停止与清理
+ └── 预处理协调
```
### 📈 数据处理服务（Data Processing Services）
```
-分布式数据处理架构：
-├── 实时文档处理（20+ 格式支持）
-├── 批量数据处理管道
-├── OCR 与表格结构提取
-└── 向量化与索引构建
+分布式数据处理管道：
+├── 文档摄入
+│ ├── 多格式支持（20+ 格式）
+│ ├── PDF 解析与 OCR
+│ └── 表格结构提取
+├── 分块与处理
+│ ├── 语义分块算法
+│ ├── Celery 批量处理
+│ └── Ray 分布式计算
+├── 向量化与索引
+│ ├── Embedding 生成
+│ ├── Elasticsearch 索引
+│ └── 增量更新
+└── 预览生成
+ ├── PDF 预览转换
+ └── 图片缩略图生成
```
### 🌐 MCP 生态系统（MCP Ecosystem）
```
-模型上下文协议工具集成：
-├── 标准化工具接口
-├── 插件化架构
-├── 第三方服务集成
-└── 自定义工具开发
+模型上下文协议集成：
+├── 本地 MCP 服务
+│ ├── 稳定的内置工具
+│ └── Docker 容器化工具
+├── 远程 MCP 服务
+│ ├── 动态远程 MCP 服务器代理
+│ └── 外部 API 工具集成
+├── MCP 容器管理
+│ ├── 容器生命周期（Docker）
+│ ├── 日志聚合
+│ └── 资源监控
+└── FastMCP 服务器
+ ├── 工具注册与发现
+ └── 标准化工具接口
+```
+
+### 🔄 A2A 协议支持（A2A Protocol Support）
+```
+智能体间通信：
+├── A2A 客户端
+│ ├── 智能体卡片发现
+│ ├── 任务提交与流式处理
+│ └── 响应处理
+├── A2A 服务器
+│ ├── 智能体卡片注册
+│ ├── 任务处理
+│ └── 消息流式传输
+└── 智能体适配器
+ ├── Nexent ↔ A2A 协议转换
+ └── 技能执行协调
```
## 🚀 分布式架构特性
### ⚡ 异步处理架构
- **基础框架**：基于 asyncio 的高性能异步处理
+- **任务队列**：Celery + Redis 分布式任务执行
+- **计算框架**：Ray 用于数据处理中的分布式计算
+- **流式处理**：Server-Sent Events（SSE）实现实时流式响应
- **并发控制**：线程安全的并发处理机制
-- **任务队列**：Celery + Ray 分布式任务执行
-- **流式处理**：实时数据流和响应流处理
### 🔄 微服务设计
```
服务拆分策略：
-├── nexent（主服务）- 智能体核心逻辑
-├── nexent-data-process（数据处理）- 文档处理管道
-├── nexent-mcp-service（MCP服务）- 工具协议服务
-└── 可选服务（SSH、监控等）
+├── nexent-config (5010)
+│ └── 智能体 CRUD、配置、用户管理
+├── nexent-runtime (5014)
+│ └── 智能体执行、流式响应
+├── nexent-mcp (5011/5015)
+│ └── MCP 工具协议、容器管理
+├── nexent-northbound (5013)
+│ └── 外部 API、A2A 协议、合作伙伴集成
+├── nexent-data-process (5012)
+│ └── 文档处理、向量化、Celery 工作者
+├── nexent-web (3000)
+│ └── 前端 Next.js 应用
+└── 可选服务
+ ├── nexent-redis (6379) - 缓存和消息代理
+ ├── nexent-elasticsearch (9210) - 向量搜索
+ ├── nexent-postgresql (5434) - 关系数据
+ └── nexent-minio (9010) - 对象存储
```
### 🌍 容器化部署
```
-Docker Compose 服务编排：
+Docker Compose 编排：
├── 应用服务容器化
├── 数据库服务隔离
-├── 网络层安全配置
-└── 卷挂载数据持久化
+├── 网络层安全配置（bridge 网络）
+├── 卷挂载数据持久化
+├── 健康检查与自动重启
+└── Kubernetes 支持（IS_DEPLOYED_BY_KUBERNETES）
```
## 🔐 安全与扩展性
### 🛡️ 安全架构
- **身份验证**：多租户支持、用户权限管理
-- **数据安全**：端到端加密、安全传输协议
-- **网络安全**：服务间安全通信、防火墙配置
+- **授权**：基于角色的访问控制（RBAC）、群组权限
+- **数据安全**：租户数据隔离、安全传输（HTTPS）
+- **网络安全**：服务间安全通信、Docker 网络隔离
### 📈 可扩展性设计
- **水平扩展**：微服务独立扩展、负载均衡
- **垂直扩展**：资源池管理、智能调度
-- **存储扩展**：分布式存储、数据分片
+- **存储扩展**：分布式存储（MinIO）、数据分片（Elasticsearch）
+- **缓存扩展**：Redis 集群用于会话和数据缓存
### 🔧 模块化架构
- **松耦合设计**：服务间低依赖、接口标准化
- **插件化架构**：工具和模型的热插拔
- **配置管理**：环境隔离、动态配置更新
+- **单一数据源**：环境变量集中管理于 `backend/consts/const.py`
## 🔄 数据流架构
### 📥 用户请求流
```
-用户输入 → 前端验证 → API网关 → 路由分发 → 业务服务 → 数据访问 → 数据库
+用户输入 → 前端验证 → API 网关（nexent-config）
+ → 路由分发 → 业务服务（Service 层）
+ → 数据访问（Database 层）→ PostgreSQL/Elasticsearch/Redis/MinIO
```
### 🤖 智能体执行流
```
-用户消息 → 智能体创建 → 工具调用 → 模型推理 → 流式响应 → 结果存储
+用户消息 → nexent-runtime → Agent Service
+ → 记忆上下文构建 → 工具解析
+ → 模型推理（流式）→ SSE 响应
+ → 对话保存 → 历史存储
```
### 📚 知识库处理流
```
-文件上传 → 临时存储 → 数据处理 → 向量化 → 知识库存储 → 索引更新
+文件上传 → nexent-config → nexent-data-process
+ → 文档解析 → 分块 → 向量化
+ → Elasticsearch 索引 → 搜索就绪
```
### ⚡ 实时处理流
```
-实时输入 → 即时处理 → 智能体响应 → 流式输出
+实时输入 → 流式端点 → 异步处理
+ → SSE 流 → 前端展示
```
## 🎯 架构优势
### 🏢 企业级特性
-- **高可用性**：多层冗余、故障转移
-- **高性能**：异步处理、智能缓存
+- **高可用性**：多服务冗余、健康检查、自动重启
+- **高性能**：异步处理、Redis 缓存、向量搜索优化
- **高并发**：分布式架构、负载均衡
-- **监控友好**：完善的日志和状态监控
+- **监控友好**：OpenTelemetry 可观测性、Grafana Tempo 追踪、结构化日志
### 🔧 开发友好
-- **模块化开发**：清晰的层次结构
-- **标准化接口**：统一的 API 设计
-- **灵活配置**：环境适配、功能开关
-- **易于测试**：单元测试、集成测试支持
+- **模块化开发**：清晰的分层架构（App → Service → Database）
+- **标准化接口**：统一的 API 设计（FastAPI）
+- **灵活配置**：环境配置、热重载
+- **易于测试**：完善的测试套件、依赖注入
### 🌱 生态兼容
-- **MCP 标准**：遵循模型上下文协议
-- **开源生态**：集成丰富的开源工具
-- **云原生**：支持 Kubernetes、Docker 部署
+- **MCP 标准**：完整的模型上下文协议实现
+- **A2A 协议**：智能体间通信支持
+- **开源生态**：集成 SmolAgents、FastMCP、LangChain
+- **云原生**：支持 Docker Compose 和 Kubernetes 部署
- **多模型支持**：兼容主流 AI 模型提供商
---
-这种架构设计确保了 Nexent 能够在保持高性能的同时，为用户提供稳定、可扩展的 AI 智能体服务平台。无论是个人用户还是企业级部署，都能够获得优秀的使用体验和技术保障。
\ No newline at end of file
+这种架构设计确保了 Nexent 能够在保持高性能的同时，为用户提供稳定、可扩展的 AI 智能体服务平台。无论是个人用户还是企业级部署，都能够获得优秀的使用体验和技术保障。
diff --git a/doc/docs/zh/quick-start/installation.md b/doc/docs/zh/quick-start/installation.md
index 87df5abde..6d3538b90 100644
--- a/doc/docs/zh/quick-start/installation.md
+++ b/doc/docs/zh/quick-start/installation.md
@@ -1,13 +1,16 @@
-# 安装部署
+# 基于 Docker 安装部署
## 🎯 系统要求
-| 资源 | 最低要求 |
-|----------|---------|
-| **CPU** | 2 核 |
-| **内存** | 6 GiB |
-| **架构** | x86_64 / ARM64 |
-| **软件** | 已安装 Docker 和 Docker Compose |
+| 资源 | 最低要求 | 推荐配置 |
+|----------|---------|-------------|
+| **CPU** | 4 核 | 8 核 |
+| **内存** | 8 GiB | 16 GiB |
+| **磁盘** | 40 GiB | 100 GiB |
+| **架构** | x86_64 / ARM64 | |
+| **软件** | 已安装 Docker 和 Docker Compose | Docker 24+, Docker Compose v2+ |
+
+> **💡 注意**：推荐的 **8 核 16 GiB 内存** 配置可确保生产环境下的良好性能。
## 🚀 快速开始
@@ -16,10 +19,9 @@
```bash
git clone https://github.com/ModelEngine-Group/nexent.git
cd nexent/docker
-cp .env.example .env # 复制环境变量配置文件
```
-> **💡 提示**: 若无特殊需求，您可直接使用 `.env.example` 进行部署，无需进行任何修改。若您需要配置语音模型（STT/TTS），则需要在 `.env` 中配置相关参数。我们会尽快将此部分配置前端化，敬请期待。
+> **💡 提示**: `deploy.sh` 会在 `docker/.env` 不存在时自动从 `.env.example` 复制一份。若无特殊需求，可直接部署；若需要配置语音模型（STT/TTS），请部署前或部署后修改 `docker/.env` 中的相关参数。
### 2. 部署选项
@@ -29,23 +31,46 @@ cp .env.example .env # 复制环境变量配置文件
bash deploy.sh
```
-执行此命令后，系统会提供两个不同的版本供您选择：
+执行此命令后，系统会通过 Bash TUI 选择部署参数。可使用方向键或 `j/k` 移动，空格切换多选项，回车确认，`b`/Backspace 返回上一步，`q` 退出。
+
+**组件组合:**
+- **infrastructure（必选）**: Elasticsearch、PostgreSQL、Redis、MinIO
+- **application（默认选中，可取消）**: config、runtime、mcp、northbound、web
+- **data-process（可选）**: 数据处理服务
+- **supabase（可选）**: 启用用户、租户和认证能力
+- **terminal（可选）**: 启用 OpenSSH 终端工具
+- **monitoring（可选）**: 启用观测组件，选择后会继续选择 provider
+
+**端口策略:**
+- **development（默认）**: 暴露调试和内部服务端口，便于本地排查
+- **production**: 仅发布生产入口端口
+
+**镜像来源:**
+- **general（默认）**: 使用标准公开镜像仓库
+- **mainland**: 使用中国大陆镜像源
+- **local-latest**: 使用本地 `latest` 镜像，避免拉取 Nexent 应用镜像
+
+您也可以通过参数跳过交互：
-**版本选择:**
-- **Speed version（轻量快速部署，默认）**: 快速启动核心功能，适合个人用户和小团队使用
-- **Full version（完整功能版）**: 提供企业级租户管理和资源隔离等高级功能，但安装时间略长，适合企业用户
+```bash
+# 默认组件组合，development 端口策略，标准镜像源
+bash deploy.sh --components infrastructure,application --port-policy development --image-source general
+
+# 启用用户/租户能力、数据处理和终端工具
+bash deploy.sh --components infrastructure,application,supabase,data-process,terminal
+
+# 使用中国大陆镜像源
+bash deploy.sh --image-source mainland
+
+# 使用本地 latest 镜像
+bash deploy.sh --image-source local-latest
+```
-**部署模式:**
-- **开发模式 (默认)**: 暴露所有服务端口以便调试
-- **基础设施模式**: 仅启动基础设施服务
-- **生产模式**: 为安全起见仅暴露端口 3000
+部署成功后，非敏感部署选项会保存到 `docker/deploy.options`。下次交互部署时可选择复用本地配置或重新全量配置。
-**可选组件:**
-- **终端工具**: 启用 openssh-server 供 AI 智能体执行 shell 命令
-- **区域优化**: 中国大陆用户可使用优化的镜像源
+#### ⚠️ 重要提示
-### ⚠️ 重要提示
1️⃣ **首次部署 v1.8.0 及以上版本时**，需特别留意 Docker 日志中输出的 `suadmin` 超级管理员账号信息。该账号为系统最高权限账户，密码仅在首次生成时显示，后续无法再次查看，请务必妥善保存。
> 该账号仅用于权限管理，无权开发智能体或创建知识库。请登录该账号，依次完成：访问租户资源→创建租户→创建租户管理员，然后使用租户管理员账号登录,即可使用全部功能。角色权限详情参见 [用户管理](../user-guide/user-management)
@@ -55,16 +80,16 @@ bash deploy.sh
docker exec -it supabase-db-mini bash
psql -U postgres
select id, email from auth.users;
-#获取到suadmin@nexent.com账号的user_id
-delete from auth.users where id = '你的user_id';
-delete from auth.identities where user_id = '你的user_id';
+# 获取 suadmin@nexent.com 账号的 user_id
+delete from auth.users where id = 'your_user_id';
+delete from auth.identities where user_id = 'your_user_id';
-#Step2：在nexent的数据库中删除su账号记录
+# Step 2: 在 nexent 数据库中删除 su 账号记录
docker exec -it nexent-postgresql bash
psql -U root -d nexent
-delete from nexent.user_tenant_t where user_id = '你的user_id';
+delete from nexent.user_tenant_t where user_id = 'your_user_id';
-#Step3：重新部署并记录su账号密码
+# Step 3: 重新部署并记录 su 账号密码
```
### 3. 访问您的安装
@@ -73,26 +98,57 @@ delete from nexent.user_tenant_t where user_id = '你的user_id';
2. 登录超级管理员账号
3. 访问租户资源 → 创建租户及租户管理员
4. 登录租户管理员账号
-2. 参考 [用户指南](../user-guide/home-page) 进行智能体的开发
+5. 参考 [用户指南](../user-guide/home-page) 进行智能体的开发
## 📦 服务架构
-Nexent 采用微服务架构，包含以下核心服务：
+Nexent 采用微服务架构，通过 Docker Compose 进行部署。
-**核心服务:**
-- `nexent`: 后端服务 (端口 5010)
-- `nexent-web`: 前端界面 (端口 3000)
-- `nexent-data-process`: 数据处理服务 (端口 5012)
+**应用服务:**
+| 服务 | 描述 | 默认端口 |
+|---------|-------------|--------------|
+| nexent | 后端服务 | 5010 |
+| nexent-web | Web 前端 | 3000 |
+| nexent-data-process | 数据处理服务 | 5012 |
+| nexent-northbound | 北向 API 服务 | 5013 |
**基础设施服务:**
-- `nexent-postgresql`: 数据库 (端口 5434)
-- `nexent-elasticsearch`: 搜索引擎 (端口 9210)
-- `nexent-minio`: 对象存储 (端口 9010，控制台 9011)
-- `redis`: 缓存服务 (端口 6379)
+| 服务 | 描述 |
+|---------|-------------|
+| nexent-postgresql | 关系型数据库 |
+| nexent-elasticsearch | 搜索引擎和索引服务 |
+| nexent-minio | S3 兼容对象存储 |
+| redis | 缓存层 |
+
+**Supabase 服务（选择 `supabase` 组件时）:**
+| 服务 | 描述 |
+|---------|-------------|
+| supabase-kong | API 网关 |
+| supabase-auth | 认证服务 |
+| supabase-db-mini | 数据库服务 |
**可选服务:**
-- `nexent-openssh-server`: 终端工具的 SSH 服务器 (端口 2222)
+| 服务 | 描述 |
+|---------|-------------|
+| nexent-openssh-server | AI 智能体 SSH 终端 |
+| nexent-monitoring | 可选观测组件 |
+
+## 💾 数据持久化
+
+Nexent 使用 Docker volumes 进行数据持久化：
+
+| 数据类型 | Volume 名称 | 默认宿主机路径 |
+|-----------|------------------|-------------------|
+| PostgreSQL | nexent-postgresql-data | `{dataDir}/postgresql` |
+| Elasticsearch | nexent-elasticsearch-data | `{dataDir}/elasticsearch` |
+| Redis | nexent-redis-data | `{dataDir}/redis` |
+| MinIO | nexent-minio-data | `{dataDir}/minio` |
+| Supabase DB（选择 supabase 时）| nexent-supabase-db-data | `{dataDir}/supabase-db` |
+
+默认 `dataDir` 为 `./volumes`（可在 `.env` 中配置 `ROOT_DIR`）。
+
+卸载由 `docker/uninstall.sh` 负责。默认交互询问是否删除持久化数据；也可使用 `--delete-volumes true|false`、`--remove-volumes`、`--keep-volumes`，或使用 `bash uninstall.sh delete-all` 删除容器和持久化数据。
## 🔌 端口映射
@@ -101,6 +157,7 @@ Nexent 采用微服务架构，包含以下核心服务：
| Web 界面 | 3000 | 3000 | 主应用程序访问 |
| 后端 API | 5010 | 5010 | 后端服务 |
| 数据处理 | 5012 | 5012 | 数据处理 API |
+| 北向 API | 5013 | 5013 | 北向接口服务 (A2A/MCP 集成) |
| PostgreSQL | 5432 | 5434 | 数据库连接 |
| Elasticsearch | 9200 | 9210 | 搜索引擎 API |
| MinIO API | 9000 | 9010 | 对象存储 API |
@@ -110,6 +167,237 @@ Nexent 采用微服务架构，包含以下核心服务：
有关完整的端口映射详细信息，请参阅我们的 [开发容器指南](../deployment/devcontainer.md#port-mapping)。
+## 🔧 高级配置
+
+### 监控配置
+
+部署时在脚本交互界面中选择 `monitoring` 组件即可启用 OpenTelemetry 监控。脚本会同步更新 `docker/.env` 中的 `ENABLE_TELEMETRY`、`MONITORING_PROVIDER` 和 `MONITORING_DASHBOARD_URL`，并启动 `docker/docker-compose-monitoring.yml` 中对应的观测组件。
+
+```bash
+cd nexent/docker
+bash deploy.sh
+```
+
+如果本地已有 `docker/deploy.options`，脚本会询问是否复用本地配置。请选择重新配置/覆盖本地配置，然后在组件选择界面勾选 `monitoring`，再在 provider 选择界面手动选择 `grafana`、`phoenix`、`langfuse`、`langsmith`、`zipkin` 或 `otlp`。
+
+支持的 provider：
+
+| Provider | 用途 | 默认访问地址 |
+|----------|------|--------------|
+| `otlp` | 仅启动 OpenTelemetry Collector，适合转发到外部平台 | 无 Dashboard |
+| `phoenix` | 本地 Phoenix 追踪分析 | `http://localhost:6006` |
+| `langfuse` | 本地 Langfuse 观测栈 | `http://localhost:3001` |
+| `langsmith` | 转发到托管 LangSmith | `https://smith.langchain.com/` |
+| `grafana` | 本地 Grafana + Tempo | `http://localhost:3002/d/nexent-llm-agent/nexent-agent-trace-monitoring?orgId=1` |
+| `zipkin` | 本地 Zipkin | `http://localhost:9411` |
+
+如需调整端口、镜像版本或 Langfuse 初始账号，请先复制并编辑监控环境变量：
+
+```bash
+cp docker/monitoring/monitoring.env.example docker/monitoring/monitoring.env
+```
+
+常用变量：
+
+| 变量 | 说明 |
+|------|------|
+| `MONITORING_PROVIDER` | 默认监控 provider；部署脚本中手动选择 provider 后会同步更新 |
+| `OTEL_COLLECTOR_HTTP_PORT` / `OTEL_COLLECTOR_GRPC_PORT` | Collector 对外暴露的 OTLP HTTP/gRPC 端口 |
+| `LANGSMITH_API_KEY` / `LANGSMITH_PROJECT` | LangSmith 转发配置 |
+| `LANGFUSE_INIT_USER_EMAIL` / `LANGFUSE_INIT_USER_PASSWORD` | 本地 Langfuse 初始管理员账号 |
+| `GRAFANA_ADMIN_USER` / `GRAFANA_ADMIN_PASSWORD` | 本地 Grafana 管理员账号 |
+
+选择 `langsmith` provider 前，请先在 `docker/monitoring/monitoring.env` 中配置 `LANGSMITH_API_KEY`。如果只需要连接已有外部 Collector，也可以在 `docker/.env` 中调整 OTLP 目标地址：
+
+```bash
+ENABLE_TELEMETRY=true
+MONITORING_PROVIDER=otlp
+OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
+OTEL_EXPORTER_OTLP_PROTOCOL=http
+MONITORING_DASHBOARD_URL=
+```
+
+> **生产建议**：请替换示例中的默认密码、密钥和 Langfuse `ENCRYPTION_KEY`，并通过反向代理或防火墙限制 Dashboard、Collector 端口的访问范围。
+
+### OAuth 登录配置
+
+OAuth 登录依赖 `supabase` 组件。启用第三方登录时，请同时部署 `supabase`，并将 `OAUTH_CALLBACK_BASE_URL` 设置为浏览器可访问的 Nexent Web 地址。
+
+```bash
+bash deploy.sh --components infrastructure,application,supabase
+```
+
+Docker 部署在 `docker/.env` 中配置 OAuth：
+
+```bash
+# Web 入口地址。回调完整路径会自动拼接为：
+# {OAUTH_CALLBACK_BASE_URL}/api/user/oauth/callback?provider=
+OAUTH_CALLBACK_BASE_URL=http://localhost:3000
+
+# GitHub OAuth
+GITHUB_OAUTH_CLIENT_ID=
+GITHUB_OAUTH_CLIENT_SECRET=
+
+# GDE OAuth
+GDE_URL=
+GDE_OAUTH_CLIENT_ID=
+GDE_OAUTH_CLIENT_SECRET=
+
+# Link App OAuth
+LINK_APP_URL=
+LINK_APP_OAUTH_CLIENT_ID=
+LINK_APP_OAUTH_CLIENT_SECRET=
+
+# WeChat OAuth
+ENABLE_WECHAT_OAUTH=false
+WECHAT_OAUTH_APP_ID=
+WECHAT_OAUTH_APP_SECRET=
+
+# 访问 OAuth provider 时的 TLS 校验
+OAUTH_SSL_VERIFY=true
+OAUTH_CA_BUNDLE=
+```
+
+Provider 启用规则：
+
+| Provider | 必填变量 | 回调地址 |
+|----------|----------|----------|
+| GitHub | `GITHUB_OAUTH_CLIENT_ID`、`GITHUB_OAUTH_CLIENT_SECRET` | `{OAUTH_CALLBACK_BASE_URL}/api/user/oauth/callback?provider=github` |
+| GDE | `GDE_URL`、`GDE_OAUTH_CLIENT_ID`、`GDE_OAUTH_CLIENT_SECRET` | `{OAUTH_CALLBACK_BASE_URL}/api/user/oauth/callback?provider=gde` |
+| Link App | `LINK_APP_URL`、`LINK_APP_OAUTH_CLIENT_ID`、`LINK_APP_OAUTH_CLIENT_SECRET` | `{OAUTH_CALLBACK_BASE_URL}/api/user/oauth/callback?provider=link_app` |
+| WeChat | `ENABLE_WECHAT_OAUTH=true`、`WECHAT_OAUTH_APP_ID`、`WECHAT_OAUTH_APP_SECRET` | `{OAUTH_CALLBACK_BASE_URL}/api/user/oauth/callback?provider=wechat` |
+
+本地默认回调示例为 `http://localhost:3000/api/user/oauth/callback?provider=github`。生产环境应改为公网 HTTPS 域名，例如 `https://nexent.example.com/api/user/oauth/callback?provider=github`，并在 OAuth provider 控制台中登记相同地址。
+
+### CAS 登录配置
+
+CAS SSO 不依赖 `supabase`。启用 CAS 时，请将 `CAS_CALLBACK_BASE_URL` 设置为浏览器可访问的 Nexent Web 地址，且不要带结尾 `/`。`CAS_SERVER_URL` 是 CAS Server 根地址，也不要带结尾 `/`。
+
+Docker 部署在 `docker/.env` 中配置 CAS：
+
+```bash
+CAS_ENABLED=true
+CAS_SERVER_URL=http://localhost:8080/cas
+CAS_VALIDATE_PATH=/p3/serviceValidate
+CAS_CALLBACK_BASE_URL=http://localhost:3000
+
+# disabled: 禁用 CAS 登录入口和自动跳转
+# button: 在登录页显示 CAS 登录按钮
+# force: 未登录访问 Nexent 时自动跳转到 CAS
+CAS_LOGIN_MODE=force
+
+# 为空时使用 ；填写 userName 时从 取用户标识
+CAS_USER_ATTRIBUTE=
+CAS_EMAIL_ATTRIBUTE=email
+CAS_ROLE_ATTRIBUTE=role
+CAS_TENANT_ATTRIBUTE=tenant_id
+CAS_ROLE_MAP_JSON={"cas-admin":"ADMIN","cas-user":"USER"}
+CAS_SESSION_MAX_AGE_SECONDS=3600
+LOCAL_SESSION_MAX_AGE_SECONDS=3600
+CAS_RENEW_BEFORE_SECONDS=300
+CAS_RENEW_TIMEOUT_SECONDS=10
+CAS_SYNTHETIC_EMAIL_DOMAIN=cas.local
+
+# 为空时 Nexent 主动退出不会调用 CAS Server 登出接口。
+# 可配置为 /logout，系统会基于 CAS_SERVER_URL 拼接。
+CAS_LOGOUT_URL=/logout
+CAS_SSL_VERIFY=true
+CAS_CA_BUNDLE=
+```
+
+常用 CAS 地址：
+
+| 用途 | 地址 |
+|------|------|
+| Nexent 登录入口 | `{CAS_CALLBACK_BASE_URL}/api/user/cas/login?redirect=/` |
+| CAS service 回调 | `{CAS_CALLBACK_BASE_URL}/api/user/cas/callback` |
+| CAS 无感续期回调 | `{CAS_CALLBACK_BASE_URL}/api/user/cas/renew_callback` |
+| CAS 单点登出回调 | `POST {CAS_CALLBACK_BASE_URL}/api/user/cas/logout_callback` |
+
+Apereo CAS 使用 JSON Service Registry 时，可以新增一个服务注册文件，例如 `Nexent-10001.json`。文件需要放到 CAS 部署配置的 service registry 目录中，`id` 必须全局唯一。下面是本地 Docker 示例：
+
+```json
+{
+ "@class": "org.apereo.cas.services.RegexRegisteredService",
+ "serviceId": "http://localhost:3000.*",
+ "name": "Nexent CAS Client",
+ "id": 10001,
+ "description": "Nexent CAS SSO client",
+ "evaluationOrder": 1,
+ "logoutType": "BACK_CHANNEL",
+ "logoutUrl": "http://localhost:3000/api/user/cas/logout_callback"
+}
+```
+
+生产环境建议保持 `CAS_SSL_VERIFY=true`；自签名证书优先配置 `CAS_CA_BUNDLE`，仅本地验证时再临时设置 `CAS_SSL_VERIFY=false`。
+
+#### CAS对接ModelEngine
+当使用CAS协议对接ModelEngine时，可以使用如下配置部署Nexent：
+```bash
+CAS_ENABLED=true
+CAS_SERVER_URL=https://:5443/SSOSvr
+CAS_VALIDATE_PATH=/p3/serviceValidate
+CAS_CALLBACK_BASE_URL=http://:3000
+CAS_LOGIN_MODE=force
+CAS_USER_ATTRIBUTE=userName
+CAS_EMAIL_ATTRIBUTE=email
+CAS_ROLE_ATTRIBUTE=userType
+CAS_TENANT_ATTRIBUTE=tenant_id
+CAS_ROLE_MAP_JSON={"1":"ADMIN","3":"DEV"}
+CAS_SESSION_MAX_AGE_SECONDS=3600
+LOCAL_SESSION_MAX_AGE_SECONDS=3600
+CAS_RENEW_BEFORE_SECONDS=300
+CAS_RENEW_TIMEOUT_SECONDS=10
+CAS_SYNTHETIC_EMAIL_DOMAIN=cas.local
+CAS_LOGOUT_URL=/logout?service=http://:3000
+CAS_SSL_VERIFY=false
+CAS_CA_BUNDLE=
+```
+
+同时，需要进入oms容器添加cas client的注册配置文件，参考如下步骤：
+```bash
+# 创建注册配置文件，将json部分输入文件并保存
+vim Nexent-10000001.json
+{
+ "@class": "org.apereo.cas.services.CasRegisteredService",
+ "serviceId": "http://:3000.*",
+ "name": "Nexent CAS Client",
+ "id": 1000001,
+ "description": "Nexent CAS SSO client",
+ "evaluationOrder": 1,
+ "logoutType": "BACK_CHANNEL",
+ "logoutUrl": "http://:3000/api/user/cas/logout_callback"
+}
+
+# 执行如下命令，将配置文件拷贝到容器中
+kubectl cp Nexent-10000001.json model-engine/$(kubectl get pods -n model-engine -l app=oms --no-headers | awk '{print $1}'):/opt/huawei/fce/apps/platform/webapps/SSOSvr/WEB-INF/classes/services/Nexent-10000001.json
+kubectl exec -i -n model-engine $(kubectl get pods -n model-engine -l app=oms --no-headers | awk '{print $1}') -- chown tomcat:fusioncube /opt/huawei/fce/apps/platform/webapps/SSOSvr/WEB-INF/classes/services/Nexent-10000001.json
+```
+
+### 北向接口配置 (NORTHBOUND_EXTERNAL_URL)
+
+如果您需要使用以下功能，需要配置 `NORTHBOUND_EXTERNAL_URL` 环境变量：
+
+1. **A2A 协议集成** - 第三方系统通过 A2A 协议调用 Nexent 智能体
+2. **MCP 工具访问** - 使用第三方 MCP 工具访问 Nexent 文档文件等资源
+
+**配置方法：**
+
+在 `.env` 文件中设置公网可访问的 URL：
+
+```bash
+# 格式：协议://主机:端口/api
+# 本地开发（默认）:
+NORTHBOUND_EXTERNAL_URL=http://localhost:5013/api
+
+# 生产环境 - 使用您的公网 IP 或域名:
+NORTHBOUND_EXTERNAL_URL=http://your-public-ip:5013/api
+# 或
+NORTHBOUND_EXTERNAL_URL=https://api.yourdomain.com/api
+```
+
+> **重要**: URL 必须包含 `/api` 后缀，因为 Northbound 服务使用 FastAPI 的 `root_path="/api"` 配置。
+
## 💡 需要帮助
- 浏览 [常见问题](./faq) 了解常见安装问题
@@ -120,4 +408,4 @@ Nexent 采用微服务架构，包含以下核心服务：
想要从源码构建或添加新功能？查看 [Docker 构建指南](../deployment/docker-build) 获取详细说明。
-有关详细的安装说明和自定义选项，请查看我们的 [开发者指南](../developer-guide/overview)。
\ No newline at end of file
+有关详细的安装说明和自定义选项，请查看我们的 [开发者指南](../developer-guide/overview)。
diff --git a/doc/docs/zh/quick-start/kubernetes-installation.md b/doc/docs/zh/quick-start/kubernetes-installation.md
index be7857fb2..7229f1ea8 100644
--- a/doc/docs/zh/quick-start/kubernetes-installation.md
+++ b/doc/docs/zh/quick-start/kubernetes-installation.md
@@ -35,21 +35,29 @@ cd nexent/k8s/helm
运行部署脚本：
```bash
-./deploy-helm.sh apply
+./deploy.sh
```
-执行此命令后，系统会提示您选择配置选项：
+执行此命令后，系统会通过 Bash TUI 选择配置选项。可使用方向键或 `j/k` 移动，空格切换多选项，回车确认，`b`/Backspace 返回上一步，`q` 退出。
-**版本选择:**
-- **Speed version（轻量快速部署，默认）**: 快速启动核心功能，适合个人用户和小团队使用
-- **Full version（完整功能版）**: 提供企业级租户管理和资源隔离等高级功能，包含 Supabase 认证服务
+**组件组合:**
+- **infrastructure（必选）**: Elasticsearch、PostgreSQL、Redis、MinIO
+- **application（默认选中，可取消）**: config、runtime、mcp、northbound、web
+- **data-process（可选）**: 数据处理服务
+- **supabase（可选）**: 启用用户、租户和认证能力
+- **terminal（可选）**: 启用 OpenSSH 终端工具
+- **monitoring（可选）**: 启用观测组件，选择后会继续选择 provider
-**镜像源选择:**
-- **中国大陆**: 使用优化的区域镜像源，加快镜像拉取速度
-- **通用**: 使用标准 Docker Hub 镜像源
+**端口策略:**
+- **development（默认）**: 使用 NodePort 暴露 Web 和调试/内部服务
+- **production**: 内部服务使用 ClusterIP，仅暴露生产入口
-**可选组件:**
-- **终端工具**: 启用 openssh-server 供 AI 智能体执行 shell 命令
+**镜像来源:**
+- **general（默认）**: 使用标准公开镜像仓库
+- **mainland**: 使用中国大陆镜像源
+- **local-latest**: 使用本地 `latest` 镜像，并将 Nexent 应用镜像的拉取策略设为本地优先
+
+部署成功后，非敏感部署选项会保存到 `k8s/helm/deploy.options`。下次交互部署时可选择复用本地配置或重新全量配置。
### ⚠️ 重要提示
@@ -72,7 +80,7 @@ kubectl exec -it -n nexent deploy/nexent-postgresql -- psql -U root -d nexent -c
"DELETE FROM nexent.user_tenant_t WHERE user_id='your_user_id';"
# Step 3: 重新部署并记录 su 账号密码
-./deploy-helm.sh apply
+./deploy.sh
```
### 4. 访问您的安装
@@ -113,7 +121,7 @@ Nexent 采用微服务架构，通过 Helm Chart 进行部署：
| nexent-redis | 缓存层 |
| nexent-minio | S3 兼容对象存储 |
-**Supabase 服务（完整版独有）:**
+**Supabase 服务（选择 `supabase` 组件时）:**
| 服务 | 描述 |
|---------|-------------|
| nexent-supabase-kong | API 网关 |
@@ -124,13 +132,14 @@ Nexent 采用微服务架构，通过 Helm Chart 进行部署：
| 服务 | 描述 |
|---------|-------------|
| nexent-openssh-server | AI 智能体 SSH 终端 |
+| nexent-monitoring | 可选观测组件 |
## 🔌 端口映射
| 服务 | 内部端口 | NodePort | 描述 |
|---------|---------------|----------|-------------|
| Web 界面 | 3000 | 30000 | 主应用程序访问 |
-| Northbound API | 5010 | 30013 | 北向 API 服务 |
+| Northbound API | 5013 | 30013 | 北向 API 服务 |
| SSH 服务器 | 22 | 30022 | 终端工具访问 |
内部服务通信使用 Kubernetes 内部 DNS（例如 `http://nexent-config:5010`）。
@@ -141,34 +150,261 @@ Nexent 使用 PersistentVolume 进行数据持久化：
| 数据类型 | PersistentVolume | 默认宿主机路径 |
|-----------|------------------|-------------------|
-| Elasticsearch | nexent-elasticsearch-pv | `{dataDir}/elasticsearch` |
-| PostgreSQL | nexent-postgresql-pv | `{dataDir}/postgresql` |
-| Redis | nexent-redis-pv | `{dataDir}/redis` |
-| MinIO | nexent-minio-pv | `{dataDir}/minio` |
-| Supabase DB（完整版）| nexent-supabase-db-pv | `{dataDir}/supabase-db` |
+| Elasticsearch | nexent-elasticsearch-pv | `/var/lib/nexent-data/nexent-elasticsearch` |
+| PostgreSQL | nexent-postgresql-pv | `/var/lib/nexent-data/nexent-postgresql` |
+| Redis | nexent-redis-pv | `/var/lib/nexent-data/nexent-redis` |
+| MinIO | nexent-minio-pv | `/var/lib/nexent-data/nexent-minio` |
+| Supabase DB（选择 supabase 时）| nexent-supabase-db-pv | `/var/lib/nexent-data/nexent-supabase-db` |
-默认 `dataDir` 为 `/var/lib/nexent-data`（可在 `values.yaml` 中配置）。
+卸载 Helm release 默认不会删除本地 hostPath 数据。可使用 `./uninstall.sh --delete-local-data true` 删除 `/var/lib/nexent-data/nexent-*` 下的 Nexent 本地卷内容，使用 `--keep-local-data` 显式保留。
## 🔧 部署命令
```bash
# 交互式部署
-./deploy-helm.sh apply
+./deploy.sh
+
+# 非交互式部署默认组件
+./deploy.sh --components infrastructure,application --port-policy development --image-source general
+
+# 启用用户/租户能力、数据处理和终端工具
+./deploy.sh --components infrastructure,application,supabase,data-process,terminal
# 使用中国大陆镜像源部署
-./deploy-helm.sh apply --is-mainland Y
+./deploy.sh --image-source mainland
-# 部署完整版本（包含 Supabase）
-./deploy-helm.sh apply --deployment-version full
+# 使用本地 latest 镜像
+./deploy.sh --image-source local-latest
# 仅清理 Helm 状态（修复卡住的发布）
-./deploy-helm.sh clean
+./uninstall.sh clean
+
+# 卸载，默认保留本地数据；交互确认是否删除 namespace 和本地数据
+./uninstall.sh
+
+# 卸载并删除 namespace
+./uninstall.sh --delete-namespace true
+
+# 卸载并删除本地 hostPath 数据
+./uninstall.sh --delete-local-data true
+
+# 完全卸载，包括 namespace 和本地 hostPath 数据
+./uninstall.sh delete-all
+
+# 完全卸载但保留本地 hostPath 数据
+./uninstall.sh delete-all --keep-local-data
+```
+
+## 🔧 高级配置
+
+### 监控配置
+
+Kubernetes 部署通过脚本交互界面中的 `monitoring` 组件启用监控。部署脚本会生成运行时 Helm values，设置 `global.monitoring.enabled`、`global.monitoring.provider`、`global.monitoring.dashboardUrl`，并启用 `nexent-monitoring` 子 Chart。
+
+```bash
+cd nexent/k8s/helm
+./deploy.sh
+```
+
+如果本地已有 `k8s/helm/deploy.options`，脚本会询问是否复用本地配置。请选择重新配置/覆盖本地配置，然后在组件选择界面勾选 `monitoring`，再在 provider 选择界面手动选择 `grafana`、`phoenix`、`langfuse`、`langsmith`、`zipkin` 或 `otlp`。
+
+支持的 provider：
+
+| Provider | 用途 | 默认访问地址 |
+|----------|------|--------------|
+| `otlp` | 仅启动 OpenTelemetry Collector，适合转发到外部平台 | 无 Dashboard |
+| `phoenix` | 本地 Phoenix 追踪分析 | `http://localhost:30006` |
+| `langfuse` | 本地 Langfuse 观测栈 | `http://localhost:30001` |
+| `langsmith` | 转发到托管 LangSmith | `https://smith.langchain.com/` |
+| `grafana` | 本地 Grafana + Tempo | `http://localhost:30002/d/nexent-llm-agent/nexent-agent-trace-monitoring?orgId=1` |
+| `zipkin` | 本地 Zipkin | `http://localhost:30011` |
+
+选择 `langsmith` provider 前，请先在 `k8s/helm/nexent/values.yaml` 中配置 `global.monitoring.langsmithApiKey` 和 `global.monitoring.langsmithProject`。如需修改本地 Grafana、Langfuse 或各 Dashboard 的端口，也建议先在 values 文件中调整，再通过部署脚本重新配置并手动选择 `monitoring`。
+
+常用 Helm values：
+
+| Values | 说明 |
+|--------|------|
+| `global.monitoring.enabled` | 是否让 Nexent 后端开启 OpenTelemetry 上报 |
+| `global.monitoring.provider` | 后端 provider 标识：`otlp`、`phoenix`、`langfuse`、`langsmith`、`grafana`、`zipkin` |
+| `global.monitoring.otlpEndpoint` | 后端 OTLP HTTP 上报地址，默认 `http://nexent-otel-collector:4318` |
+| `global.monitoring.dashboardUrl` | 前端监控入口地址，留空则隐藏入口 |
+| `global.monitoring.traceContentMode` | Trace 内容采集模式：`summary`、`metrics`、`full` |
+| `nexent-monitoring..service.nodePort` | 调整各 Dashboard 的 NodePort |
+| `nexent-monitoring.langfuse.init.*` | 本地 Langfuse 初始组织、项目和管理员账号 |
+| `nexent-monitoring.grafana.adminUser` / `adminPassword` | 本地 Grafana 管理员账号 |
+
+查看监控组件状态：
+
+```bash
+kubectl get pods -n nexent | grep -E 'otel|phoenix|grafana|tempo|zipkin|langfuse'
+kubectl get svc -n nexent | grep -E 'otel|phoenix|grafana|zipkin|langfuse'
+```
-# 卸载但保留数据
-./deploy-helm.sh delete
+> **生产建议**：请替换默认密码、密钥和 Langfuse `encryptionKey`，并将 Dashboard Service 改为 ClusterIP 或通过受控 Ingress 暴露。
-# 完全卸载包括所有数据
-./deploy-helm.sh delete-all
+### OAuth 登录配置
+
+OAuth 登录依赖 `supabase` 组件。启用第三方登录时，请同时部署 `supabase`，并将 `config.oauth.callbackBaseUrl` 设置为浏览器可访问的 Nexent Web 地址。
+
+```bash
+./deploy.sh --components infrastructure,application,supabase
+```
+
+Kubernetes 部署通过 `nexent-common` 的 `config.oauth.*` values 写入后端环境变量：
+
+```bash
+helm upgrade --install nexent nexent \
+ --namespace nexent --create-namespace \
+ --set global.deploymentComponents.supabase=true \
+ --set nexent-supabase-kong.enabled=true \
+ --set nexent-supabase-auth.enabled=true \
+ --set nexent-supabase-db.enabled=true \
+ --set nexent-common.config.oauth.callbackBaseUrl=https://nexent.example.com \
+ --set nexent-common.config.oauth.githubClientId=your_github_client_id \
+ --set nexent-common.config.oauth.githubClientSecret=your_github_client_secret
+```
+
+可配置的 OAuth values：
+
+| Values | 对应环境变量 | 说明 |
+|--------|--------------|------|
+| `nexent-common.config.oauth.callbackBaseUrl` | `OAUTH_CALLBACK_BASE_URL` | Web 入口地址，回调路径会自动拼接 |
+| `nexent-common.config.oauth.githubClientId` | `GITHUB_OAUTH_CLIENT_ID` | GitHub OAuth Client ID |
+| `nexent-common.config.oauth.githubClientSecret` | `GITHUB_OAUTH_CLIENT_SECRET` | GitHub OAuth Client Secret |
+| `nexent-common.config.oauth.gdeUrl` | `GDE_URL` | GDE OAuth 服务地址 |
+| `nexent-common.config.oauth.gdeClientId` | `GDE_OAUTH_CLIENT_ID` | GDE OAuth Client ID |
+| `nexent-common.config.oauth.gdeClientSecret` | `GDE_OAUTH_CLIENT_SECRET` | GDE OAuth Client Secret |
+| `nexent-common.config.oauth.enableWechat` | `ENABLE_WECHAT_OAUTH` | 是否启用 WeChat OAuth |
+| `nexent-common.config.oauth.wechatClientId` | `WECHAT_OAUTH_APP_ID` | WeChat App ID |
+| `nexent-common.config.oauth.wechatClientSecret` | `WECHAT_OAUTH_APP_SECRET` | WeChat App Secret |
+| `nexent-common.config.oauth.sslVerify` | `OAUTH_SSL_VERIFY` | 访问 OAuth provider 时是否校验证书 |
+| `nexent-common.config.oauth.caBundle` | `OAUTH_CA_BUNDLE` | 自定义 CA bundle 路径 |
+
+Provider 回调地址：
+
+| Provider | 回调地址 |
+|----------|----------|
+| GitHub | `{OAUTH_CALLBACK_BASE_URL}/api/user/oauth/callback?provider=github` |
+| GDE | `{OAUTH_CALLBACK_BASE_URL}/api/user/oauth/callback?provider=gde` |
+| WeChat | `{OAUTH_CALLBACK_BASE_URL}/api/user/oauth/callback?provider=wechat` |
+
+本地 NodePort 默认回调示例为 `http://localhost:30000/api/user/oauth/callback?provider=github`。生产环境应改为公网 HTTPS 域名，并在 OAuth provider 控制台中登记相同地址。
+
+### CAS 登录配置
+
+CAS SSO 不依赖 `supabase`。启用 CAS 时，请将 `nexent-common.config.cas.callbackBaseUrl` 设置为浏览器可访问的 Nexent Web 地址，且不要带结尾 `/`。`nexent-common.config.cas.serverUrl` 是 CAS Server 根地址，也不要带结尾 `/`。
+
+Kubernetes 部署通过 `nexent-common` 的 `config.cas.*` values 写入后端环境变量：
+
+```bash
+helm upgrade --install nexent nexent \
+ --namespace nexent --create-namespace \
+ --set nexent-common.config.cas.enabled=true \
+ --set nexent-common.config.cas.serverUrl=https://cas.example.com/cas \
+ --set nexent-common.config.cas.callbackBaseUrl=https://nexent.example.com \
+ --set nexent-common.config.cas.loginMode=force \
+ --set nexent-common.config.cas.logoutUrl=/logout
+```
+
+可配置的 CAS values：
+
+| Values | 对应环境变量 | 说明 |
+|--------|--------------|------|
+| `nexent-common.config.cas.enabled` | `CAS_ENABLED` | 是否启用 CAS |
+| `nexent-common.config.cas.serverUrl` | `CAS_SERVER_URL` | CAS Server 根地址 |
+| `nexent-common.config.cas.validatePath` | `CAS_VALIDATE_PATH` | serviceValidate 路径，默认 `/p3/serviceValidate` |
+| `nexent-common.config.cas.callbackBaseUrl` | `CAS_CALLBACK_BASE_URL` | Web 入口地址，CAS 回调路径会自动拼接 |
+| `nexent-common.config.cas.loginMode` | `CAS_LOGIN_MODE` | `disabled`、`button` 或 `force` |
+| `nexent-common.config.cas.userAttribute` | `CAS_USER_ATTRIBUTE` | 用户标识属性。为空时使用 `` |
+| `nexent-common.config.cas.emailAttribute` | `CAS_EMAIL_ATTRIBUTE` | 邮箱属性 |
+| `nexent-common.config.cas.roleAttribute` | `CAS_ROLE_ATTRIBUTE` | 角色属性 |
+| `nexent-common.config.cas.tenantAttribute` | `CAS_TENANT_ATTRIBUTE` | 租户属性 |
+| `nexent-common.config.cas.roleMapJson` | `CAS_ROLE_MAP_JSON` | CAS 角色到 Nexent 角色的 JSON 映射 |
+| `nexent-common.config.cas.sessionMaxAgeSeconds` | `CAS_SESSION_MAX_AGE_SECONDS` | CAS 本地会话最长有效期 |
+| `nexent-common.config.cas.localSessionMaxAgeSeconds` | `LOCAL_SESSION_MAX_AGE_SECONDS` | Nexent 本地会话有效期 |
+| `nexent-common.config.cas.renewBeforeSeconds` | `CAS_RENEW_BEFORE_SECONDS` | 距离过期多少秒内触发无感续期 |
+| `nexent-common.config.cas.renewTimeoutSeconds` | `CAS_RENEW_TIMEOUT_SECONDS` | 无感续期等待超时时间 |
+| `nexent-common.config.cas.syntheticEmailDomain` | `CAS_SYNTHETIC_EMAIL_DOMAIN` | CAS 未返回邮箱时生成邮箱使用的域名 |
+| `nexent-common.config.cas.logoutUrl` | `CAS_LOGOUT_URL` | CAS 登出地址。为空时 Nexent 主动退出不调用 CAS Server 登出接口 |
+| `nexent-common.config.cas.sslVerify` | `CAS_SSL_VERIFY` | 访问 CAS Server 时是否校验证书 |
+| `nexent-common.config.cas.caBundle` | `CAS_CA_BUNDLE` | 自定义 CA bundle 路径 |
+
+常用 CAS 地址：
+
+| 用途 | 地址 |
+|------|------|
+| Nexent 登录入口 | `{CAS_CALLBACK_BASE_URL}/api/user/cas/login?redirect=/` |
+| CAS service 回调 | `{CAS_CALLBACK_BASE_URL}/api/user/cas/callback` |
+| CAS 无感续期回调 | `{CAS_CALLBACK_BASE_URL}/api/user/cas/renew_callback` |
+| CAS 单点登出回调 | `POST {CAS_CALLBACK_BASE_URL}/api/user/cas/logout_callback` |
+
+Apereo CAS 使用 JSON Service Registry 时，可以新增一个服务注册文件，例如 `Nexent-10001.json`。文件需要放到 CAS 部署配置的 service registry 目录中，`id` 必须全局唯一。本地 NodePort 示例：
+
+```json
+{
+ "@class": "org.apereo.cas.services.RegexRegisteredService",
+ "serviceId": "http://localhost:30000.*",
+ "name": "Nexent CAS Client",
+ "id": 10001,
+ "description": "Nexent CAS SSO client",
+ "evaluationOrder": 1,
+ "logoutType": "BACK_CHANNEL",
+ "logoutUrl": "http://localhost:30000/api/user/cas/logout_callback"
+}
+```
+
+生产环境建议保持 `CAS_SSL_VERIFY=true`；自签名证书优先配置 `CAS_CA_BUNDLE`，仅本地验证时再临时设置 `CAS_SSL_VERIFY=false`。
+
+#### CAS 对接 ModelEngine
+
+当使用 CAS 协议对接 ModelEngine 时，建议通过 values 文件配置 Nexent，避免 `CAS_ROLE_MAP_JSON` 在命令行中转义复杂。
+
+创建 `cas-modelengine-values.yaml`：
+
+```yaml
+nexent-common:
+ config:
+ cas:
+ enabled: true
+ serverUrl: "https://:5443/SSOSvr"
+ validatePath: "/p3/serviceValidate"
+ callbackBaseUrl: "http://:30000"
+ loginMode: "force"
+ userAttribute: "userName"
+ emailAttribute: "email"
+ roleAttribute: "userType"
+ tenantAttribute: "tenant_id"
+ roleMapJson: '{"1":"ADMIN","3":"DEV"}'
+ sessionMaxAgeSeconds: 3600
+ localSessionMaxAgeSeconds: 3600
+ renewBeforeSeconds: 300
+ renewTimeoutSeconds: 10
+ syntheticEmailDomain: "cas.local"
+ logoutUrl: "/logout?service=http://:30000"
+ sslVerify: false
+ caBundle: ""
+```
+
+同时，需要进入 OMS 容器添加 CAS client 的注册配置文件，参考如下步骤：
+
+```bash
+# 创建注册配置文件，将 JSON 部分输入文件并保存
+vim Nexent-10000001.json
+{
+ "@class": "org.apereo.cas.services.CasRegisteredService",
+ "serviceId": "http://:30000.*",
+ "name": "Nexent CAS Client",
+ "id": 1000001,
+ "description": "Nexent CAS SSO client",
+ "evaluationOrder": 1,
+ "logoutType": "BACK_CHANNEL",
+ "logoutUrl": "http://:30000/api/user/cas/logout_callback"
+}
+
+# 执行如下命令，将配置文件拷贝到容器中
+kubectl cp Nexent-10000001.json model-engine/$(kubectl get pods -n model-engine -l app=oms --no-headers | awk '{print $1}'):/opt/huawei/fce/apps/platform/webapps/SSOSvr/WEB-INF/classes/services/Nexent-10000001.json
+kubectl exec -i -n model-engine $(kubectl get pods -n model-engine -l app=oms --no-headers | awk '{print $1}') -- chown tomcat:fusioncube /opt/huawei/fce/apps/platform/webapps/SSOSvr/WEB-INF/classes/services/Nexent-10000001.json
```
## 🔍 故障排查
diff --git a/doc/docs/zh/quick-start/kubernetes-upgrade-guide.md b/doc/docs/zh/quick-start/kubernetes-upgrade-guide.md
index 43f5c1d49..f2ec9226a 100644
--- a/doc/docs/zh/quick-start/kubernetes-upgrade-guide.md
+++ b/doc/docs/zh/quick-start/kubernetes-upgrade-guide.md
@@ -15,7 +15,7 @@
更新之前，先记录下当前部署的版本和数据目录信息。
- 当前部署版本信息的位置：`backend/consts/const.py` 中的 `APP_VERSION`
-- 数据目录信息的位置：`k8s/helm/nexent/values.yaml` 中的 `global.dataDir`
+- 本地卷目录信息的位置：各 Helm 子 chart 的 `storage.hostPath`，默认位于 `/var/lib/nexent-data/nexent-*`
**git 方式下载的代码**
@@ -28,7 +28,7 @@ git pull
**zip 包等方式下载的代码**
1. 需要去 GitHub 上重新下载一份最新代码，并解压缩。
-2. 将之前执行部署脚本目录下 `k8s/helm` 目录中的 `.deploy.options` 文件拷贝到新代码目录的 `k8s/helm` 目录中。（如果不存在该文件则忽略此步骤）。
+2. 将之前执行部署脚本目录下 `k8s/helm` 目录中的 `deploy.options` 文件拷贝到新代码目录的 `k8s/helm` 目录中。（如果不存在该文件则忽略此步骤）。
## 🔄 步骤二：执行升级
@@ -36,10 +36,10 @@ git pull
```bash
cd k8s/helm
-./deploy-helm.sh apply
+./deploy.sh
```
-脚本会自动检测您之前的部署设置（版本、镜像源等）。如果 `.deploy.options` 文件不存在，系统会提示您输入配置信息。
+脚本会自动检测您之前保存的部署设置（组件组合、端口策略、镜像来源等）。如果 `deploy.options` 文件不存在，系统会提示您输入配置信息。
> 💡 提示
> - 若需配置语音模型（STT/TTS），请在对应的 `values.yaml` 中修改相关配置，或通过命令行参数传入。
@@ -137,7 +137,7 @@ kubectl exec -i $POSTGRES_POD -n nexent -- psql -U root -d nexent < ./sql/v2.0.0
kubectl exec nexent/$POSTGRES_POD -n nexent -- pg_dump -U root nexent > backup_$(date +%F).sql
```
-> - 对于 Supabase 数据库（仅完整版本），请使用 `nexent-supabase-db` Pod：
+> - 对于 Supabase 数据库（选择 `supabase` 组件时），请使用 `nexent-supabase-db` Pod：
```bash
SUPABASE_POD=$(kubectl get pods -n nexent -l app=nexent-supabase-db -o jsonpath='{.items[0].metadata.name}')
diff --git a/doc/docs/zh/quick-start/upgrade-guide.md b/doc/docs/zh/quick-start/upgrade-guide.md
index b888e2ada..4f8b429e0 100644
--- a/doc/docs/zh/quick-start/upgrade-guide.md
+++ b/doc/docs/zh/quick-start/upgrade-guide.md
@@ -37,11 +37,11 @@ git pull
bash upgrade.sh
```
-缺少 deploy.options 的情况下，会提示需要手动输入之前部署的一些配置，比如：当前部署版本、数据目录等。按照提示输入之前记录的信息即可。
+缺少 deploy.options 的情况下，会提示需要重新选择部署配置，例如组件组合、端口策略、镜像来源等。按照您之前的部署方式重新选择即可。
> 💡 提示
-> - 默认为快速部署场景，使用 `.env.example`。
-> - 若需配置语音模型（STT/TTS），请提前在 `.env.example` 中补充相关变量，我们将尽快提供前端配置入口。
+> - 若 `docker/.env` 不存在，部署脚本会从 `.env.example` 自动复制一份。
+> - 若需配置语音模型（STT/TTS），请在 `docker/.env` 中补充相关变量，我们将尽快提供前端配置入口。
## 🌐 步骤三：验证部署
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/sdk/monitoring.md b/doc/docs/zh/sdk/monitoring.md
index c592df267..2483b505b 100644
--- a/doc/docs/zh/sdk/monitoring.md
+++ b/doc/docs/zh/sdk/monitoring.md
@@ -1,289 +1,473 @@
-# 🚀 Nexent LLM 监控系统
+# Nexent Agent 可观测性（OTLP）
-专门监控大模型 Token 生成速度和性能的企业级监控解决方案。
+基于 OpenTelemetry OTLP 协议的 AI Agent 企业级可观测性方案。支持对接 Arize Phoenix、Langfuse、LangSmith、Grafana Tempo、Zipkin 等可观测性平台。
-## 📊 系统架构
+## 系统架构
```
-┌─────────────────────────────────────────────────────────┐
-│ Nexent LLM 监控系统 │
-├─────────────────────────────────────────────────────────┤
-│ │
-│ Nexent API ──► OpenTelemetry ──► Jaeger (链路追踪) │
-│ │ │ │
-│ │ └──────► Prometheus (指标收集) │
-│ │ │ │
-│ └─► OpenAI LLM └──► Grafana (可视化) │
-│ (Token 监控) │
-└─────────────────────────────────────────────────────────┘
+NexentAgent ──► OpenTelemetry SDK ──► OTLP Collector ──► Arize Phoenix / Langfuse / LangSmith / Grafana Tempo / Zipkin / OTLP Backend
+ │ │
+ │ OpenInference 语义约定 │
+ │ (llm.*, agent.* 属性) │
+ └────────────────────────────────────────┘
```
-## ⚡ 快速启动（5分钟）
+## 快速启动
```bash
-# 1. 启动监控服务
-./docker/start-monitoring.sh
+cd docker
+[ -f .env ] || cp .env.example .env
+cp monitoring/monitoring.env.example monitoring/monitoring.env
-# 2. 安装性能监控依赖
-uv sync --extra performance
+vim .env
+ENABLE_TELEMETRY=true
+MONITORING_PROVIDER=otlp
+OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
+OTEL_EXPORTER_OTLP_PROTOCOL=http
-# 3. 启用监控
-export ENABLE_TELEMETRY=true
+vim monitoring/monitoring.env
+MONITORING_PROVIDER=otlp
-# 4. 启动后端服务
-python backend/config_service.py
-python backend/runtime_service.py
+./start-monitoring.sh --stack collector
```
-## 📊 访问监控界面
+## 本地化部署形态
-| 界面 | 地址 | 用途 |
-|------|------|------|
-| **Grafana 仪表板** | http://localhost:3005 | LLM 性能监控 |
-| **Jaeger 链路追踪** | http://localhost:16686 | 请求链路分析 |
-| **Prometheus 指标** | http://localhost:9090 | 原始监控数据 |
+`docker/start-monitoring.sh` 支持多种形态，均以 OpenTelemetry Collector 作为统一入口。业务服务只需要把 OTLP 发到 Collector，不需要感知后端平台差异。
-### 🔐 Grafana 登录信息
+| 形态 | 命令 | 包含服务 | 适用场景 |
+|------|------|----------|----------|
+| `collector` | `./start-monitoring.sh --stack collector` | OpenTelemetry Collector | 只验证埋点、或转发到外部云端平台 |
+| `phoenix` | `./start-monitoring.sh --stack phoenix` | Collector + Phoenix | 本地 trace 调试、OpenInference 属性查看、实验分析 |
+| `langfuse` | `./start-monitoring.sh --stack langfuse` | Collector + Langfuse Web/Worker + Postgres + ClickHouse + MinIO + Redis | 本地完整 LLMOps 体验、会话/用户/反馈/成本分析 |
+| `langsmith` | `./start-monitoring.sh --stack langsmith` | OpenTelemetry Collector | 转发 traces 到在线 LangSmith 平台 |
+| `grafana` | `./start-monitoring.sh --stack grafana` | Collector + Grafana + Tempo | 本地 Tempo trace 查询 |
+| `zipkin` | `./start-monitoring.sh --stack zipkin` | Collector + Zipkin | 本地 trace 查询 |
-首次访问 Grafana (http://localhost:3005) 时需要登录：
+也可以在 `docker/monitoring/monitoring.env` 中设置默认形态：
+```bash
+MONITORING_PROVIDER=phoenix
```
-用户名: admin
-密码: admin
+
+### 本地 Phoenix
+
+Phoenix 本地部署使用 `arizephoenix/phoenix` 镜像，默认 UI 端口为 `6006`，gRPC OTLP 端口映射为 `4319`，数据持久化到 Docker volume `phoenix-data`。
+
+```bash
+cd docker
+./start-monitoring.sh --stack phoenix
```
-**首次登录后会要求修改密码，可以：**
-- 设置新密码（推荐）
-- 点击 "Skip" 跳过（开发环境）
+访问地址：
-**登录后可以看到：**
-- 📊 **LLM Performance Dashboard** - 预配置的性能仪表板
-- 📈 **数据源配置** - 自动连接到 Prometheus 和 Jaeger
-- 🎯 **实时监控面板** - Token 生成速度、延迟等关键指标
+- Phoenix UI：`http://localhost:6006`
+- Collector OTLP HTTP：`http://localhost:4318`
+- Collector OTLP gRPC：`localhost:4317`
-## 🎯 核心功能特性
+Nexent 后端在 Docker 网络内运行时：
-### ⚡ LLM 专用监控
-- **Token 生成速度**: 实时监控每秒生成的 token 数量
-- **TTFT (Time to First Token)**: 首个 token 返回延迟
-- **流式响应分析**: 每个 token 的生成时间戳
-- **模型性能对比**: 不同模型的性能基准
+```bash
+ENABLE_TELEMETRY=true
+OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
+OTEL_EXPORTER_OTLP_PROTOCOL=http
+OTEL_EXPORTER_OTLP_METRICS_ENABLED=false
+```
-### 🔍 分布式链路追踪
-- **完整请求链路**: 从 HTTP 到 LLM 的端到端追踪
-- **性能瓶颈识别**: 自动定位慢查询和异常
-- **错误根因分析**: 快速定位问题根源
+后端直接在宿主机运行时，把 endpoint 改为 `http://localhost:4318`。
-### 🛠️ 开发友好设计
-- **一行代码接入**: 使用装饰器快速添加监控
-- **零依赖降级**: 未安装监控依赖时自动跳过
-- **零感知使用**: 无需手动检查监控状态，自动处理
-- **灵活配置**: 环境变量控制监控行为
+### 本地 Langfuse
-## 🛠️ 添加监控到代码
+Langfuse 本地部署使用 v3 架构：Web、Worker、Postgres、ClickHouse、MinIO、Redis。默认 UI 端口为 `3001`，初始化项目和 API Key 来自 `monitoring.env`。
-### 🎯 推荐方式：单例模式 (v2.1+)
+```bash
+cd docker
+./start-monitoring.sh --stack langfuse
+```
-```python
-# 后端服务中使用 - 直接使用全局配置好的 monitoring_manager
-from utils.monitoring import monitoring_manager
+访问地址：
-# API 端点监控
-@monitoring_manager.monitor_endpoint("my_service.my_function")
-async def my_api_function():
- return {"status": "ok"}
+- Langfuse UI：`http://localhost:3001`
+- 默认管理员：`admin@nexent.local` / `nexent-langfuse-admin`
+- 默认项目 Key：`pk-lf-nexent-local` / `sk-lf-nexent-local`
-# LLM 调用监控
-@monitoring_manager.monitor_llm_call("gpt-4", "chat_completion")
-def call_llm(messages):
- # 自动获得 Token 级别监控
- return llm_response
+启动脚本会在 `LANGFUSE_OTLP_AUTH_HEADER` 为空时自动生成 `Basic base64(public_key:secret_key)`，并让 Collector 将 trace 转发到 `http://langfuse-web:3000/api/public/otel`。本地默认密钥只适合开发验证，生产部署必须替换 `LANGFUSE_NEXTAUTH_SECRET`、`LANGFUSE_SALT`、`LANGFUSE_ENCRYPTION_KEY`、数据库密码和对象存储密钥。
+
+### 在线 LangSmith
+
+LangSmith 支持通过在线 OTLP endpoint 摄取 traces。Nexent 可以先把 OTLP 发到本地 Collector，再由 Collector 转发到 LangSmith，业务服务无需直接保存 LangSmith API Key。
+
+```bash
+cd docker
+vim monitoring/monitoring.env
+
+MONITORING_PROVIDER=langsmith
+LANGSMITH_API_KEY=lsv2_xxx
+LANGSMITH_PROJECT=nexent
+LANGSMITH_OTLP_TRACES_ENDPOINT=https://api.smith.langchain.com/otel/v1/traces
-# 手动添加监控事件
-monitoring_manager.add_span_event("custom_event", {"key": "value"})
-monitoring_manager.set_span_attributes(user_id="123", action="process")
+./start-monitoring.sh --stack langsmith
```
-### 📦 SDK中直接使用
+后端在 Docker 网络内运行时：
-```python
-from nexent.monitor import get_monitoring_manager
-
-# 获取全局监控管理器 - 在backend已自动配置
-monitor = get_monitoring_manager()
-
-# 使用装饰器
-@monitor.monitor_llm_call("claude-3", "completion")
-def my_llm_function():
- return "response"
-
-# 或者在业务逻辑中直接使用
-with monitor.trace_llm_request("custom_operation", "my_model") as span:
- # 执行业务逻辑
- result = process_data()
- monitor.add_span_event("processing_completed")
- return result
+```bash
+ENABLE_TELEMETRY=true
+MONITORING_PROVIDER=langsmith
+OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
+OTEL_EXPORTER_OTLP_PROTOCOL=http
+OTEL_EXPORTER_OTLP_METRICS_ENABLED=false
```
-### ✨ 全局配置自动化
+LangSmith 当前配置只转发 traces，OTLP metrics 会留在 Collector debug pipeline。若需要后端直接写入 LangSmith，可设置 `OTEL_EXPORTER_OTLP_ENDPOINT=https://api.smith.langchain.com/otel`、`LANGSMITH_API_KEY` 和可选的 `LANGSMITH_PROJECT`。
-监控配置已在 `backend/utils/monitoring.py` 中自动初始化：
+### 本地 Grafana + Tempo
-```python
-# 无需手动配置 - 系统启动时自动完成
-# monitoring_manager 已经使用环境变量配置完成
-from utils.monitoring import monitoring_manager
+Grafana 本地部署使用 Grafana Tempo 存储 traces，并启用 Tempo `metrics-generator` 的 `local-blocks` processor 支持 Grafana trace breakdown 中的 TraceQL metrics 查询。Collector 接收 Nexent 后端的 OTLP traces/metrics，其中 traces 通过 OTLP gRPC 转发到 Tempo；OTLP metrics 只进入 Collector debug pipeline，不提供独立指标存储或指标 dashboard。
+
+```bash
+cd docker
+./start-monitoring.sh --stack grafana
+```
-# 直接使用即可，无需检查是否开启
-@monitoring_manager.monitor_endpoint("my_function")
-def my_function():
- pass
+后端 `.env` 使用 `MONITORING_DASHBOARD_URL` 控制前端顶栏监控入口：
-# FastAPI应用初始化
-monitoring_manager.setup_fastapi_app(app)
+```bash
+ENABLE_TELEMETRY=true
+MONITORING_PROVIDER=grafana
+MONITORING_DASHBOARD_URL=http://localhost:3002/d/nexent-llm-agent/nexent-agent-trace-monitoring?orgId=1
+OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
```
-### 🔒 自动启停设计
+访问地址：
-- **智能监控**: 根据 `ENABLE_TELEMETRY` 环境变量自动启停
-- **零感知使用**: 外部代码无需检查监控状态，直接使用所有功能
-- **优雅降级**: 未开启时静默无效果，开启时正常工作
-- **默认关闭**: 未配置时自动视为关闭状态
+- Grafana UI：`http://localhost:3002`
+- 默认管理员：`admin` / `nexent-grafana-admin`
+- Tempo API：`http://localhost:3200`
-```bash
-# 开启监控
-export ENABLE_TELEMETRY=true
+Grafana 会自动预置 Tempo datasource，并加载 `Nexent Agent Trace Monitoring` dashboard。Trace 查询入口在 Grafana Explore 中选择 `Tempo` datasource，示例 TraceQL 为 `{ resource.service.name = "nexent-backend" }`。
-# 关闭监控
-export ENABLE_TELEMETRY=false
-```
+### 本地 Zipkin
-## 📊 核心监控指标
+Zipkin 本地部署使用 `openzipkin/zipkin` 镜像。Collector 接收 Nexent 后端的 OTLP traces/metrics，其中 traces 转发到 Zipkin v2 spans endpoint；OTLP metrics 当前只进入 Collector debug pipeline。
-| 指标 | 描述 | 重要性 |
-|------|------|-------|
-| `llm_token_generation_rate` | Token 生成速度 (tokens/s) | ⭐⭐⭐ |
-| `llm_time_to_first_token_seconds` | 首 Token 延迟 | ⭐⭐⭐ |
-| `llm_request_duration_seconds` | 完整请求耗时 | ⭐⭐⭐ |
-| `llm_total_tokens` | 输入/输出 Token 数量 | ⭐⭐ |
-| `llm_error_count` | LLM 调用错误数 | ⭐⭐⭐ |
+```bash
+cd docker
+./start-monitoring.sh --stack zipkin
+```
-## 🔧 环境配置
+后端 `.env`：
```bash
-# 添加到 .env 文件
-cat >> .env << EOF
ENABLE_TELEMETRY=true
-SERVICE_NAME=nexent-backend
-JAEGER_ENDPOINT=http://localhost:14268/api/traces
-LLM_SLOW_REQUEST_THRESHOLD_SECONDS=5.0
-LLM_SLOW_TOKEN_RATE_THRESHOLD=10.0
-TELEMETRY_SAMPLE_RATE=1.0 # 开发环境，生产环境推荐 0.1
-EOF
+MONITORING_PROVIDER=zipkin
+OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
+OTEL_EXPORTER_OTLP_PROTOCOL=http
+OTEL_EXPORTER_OTLP_METRICS_ENABLED=false
+MONITORING_DASHBOARD_URL=http://localhost:9411
```
-## 🛠️ 验证系统
+访问地址：
-```bash
-# 检查指标端点
-curl http://localhost:8000/metrics
+- Zipkin UI：`http://localhost:9411`
+
+## AI 可观测性平台对接
+
+### Arize Phoenix
-# 验证依赖安装
-python -c "from backend.utils.monitoring import MONITORING_AVAILABLE; print(f'监控可用: {MONITORING_AVAILABLE}')"
+Arize Phoenix 提供针对 AI 的专业可观测性，原生支持 OpenInference 语义。
+
+**配置：**
+
+```bash
+MONITORING_PROVIDER=phoenix
+OTEL_EXPORTER_OTLP_ENDPOINT=https://app.phoenix.arize.com/s/YOUR_SPACE
+OTEL_EXPORTER_OTLP_AUTHORIZATION="Bearer YOUR_PHOENIX_API_KEY"
+OTEL_EXPORTER_OTLP_PROTOCOL=http
+OTEL_EXPORTER_OTLP_METRICS_ENABLED=false
```
-## 🆘 故障排除
+**功能特性：**
+- LLM 调用链可视化（Prompt/Completion）
+- Token 级性能指标
+- Agent 步骤追踪
+- 成本分析
+
+### Langfuse
+
+Langfuse 提供 Prompt 管理和 LLM 可观测性，支持 OTLP 协议。
+
+**配置：**
-### 监控数据为空？
```bash
-# 检查服务状态
-docker-compose -f docker/docker-compose-monitoring.yml ps
+MONITORING_PROVIDER=langfuse
+OTEL_EXPORTER_OTLP_ENDPOINT=https://cloud.langfuse.com/api/public/otel
+
+LANGFUSE_PUBLIC_KEY=pk-xxx
+LANGFUSE_SECRET_KEY=sk-xxx
-# 检查依赖安装
-python -c "import opentelemetry; print('✅ 监控依赖已安装')"
+OTEL_EXPORTER_OTLP_AUTHORIZATION=Basic BASE64_ENCODED_KEY
+OTEL_EXPORTER_OTLP_LANGFUSE_INGESTION_VERSION=4
```
-### 端口冲突？
+生成认证 Key：
+
```bash
-# 检查端口占用
-lsof -i :3005 -i :9090 -i :16686
+echo -n "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" | base64
```
-### 依赖安装问题？
-```bash
-# 重新安装性能依赖
-uv sync --extra performance
+**功能特性：**
+- Prompt 版本管理
+- 会话级 Trace 分组
+- 用户反馈收集
+- 模型成本追踪
+
+## 环境变量
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `ENABLE_TELEMETRY` | `false` | 启用/禁用监控 |
+| `MONITORING_PROVIDER` | `otlp` | 平台配置和本地部署形态：`otlp`、`phoenix`、`langfuse`、`langsmith`、`grafana`、`zipkin` |
+| `MONITORING_DASHBOARD_URL` | （空） | 前端顶栏监控入口跳转 URL，需配置为浏览器可访问地址 |
+| `MONITORING_PROJECT_NAME` | `nexent` | 监控平台项目名 |
+| `MONITORING_TRACE_CONTENT_MODE` | `summary` | Trace payload 记录模式：`summary` 写入有界预览和结构元数据，`metrics` 只写结构/大小元数据，`full` 在 `MONITORING_TRACE_MAX_CHARS` 限制内保留完整 payload |
+| `MONITORING_TRACE_MAX_CHARS` | `4000` | 每个 payload 预览最多写入的字符数 |
+| `MONITORING_TRACE_MAX_ITEMS` | `20` | dict/list 预览最多写入的 key 或 item 数 |
+| `OTEL_SERVICE_NAME` | `nexent-backend` | 服务标识 |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4318` | OTLP base endpoint，SDK 会派生 `/v1/traces` 和 `/v1/metrics` |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | （空） | 可选 trace 专用 endpoint |
+| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | （空） | 可选 metric 专用 endpoint |
+| `OTEL_EXPORTER_OTLP_PROTOCOL` | `http` | 协议：`http` 或 `grpc` |
+| `OTEL_EXPORTER_OTLP_HEADERS` | （空） | 通用认证头（逗号分隔） |
+| `OTEL_EXPORTER_OTLP_AUTHORIZATION` | （空） | `Authorization` header，常用于 Phoenix bearer auth 和 Langfuse |
+| `OTEL_EXPORTER_OTLP_X_API_KEY` | （空） | `x-api-key` header，用于兼容需要该 header 的平台 |
+| `OTEL_EXPORTER_OTLP_LANGFUSE_INGESTION_VERSION` | （空） | Langfuse 实时摄取版本，例如 `4` |
+| `OTEL_EXPORTER_OTLP_METRICS_ENABLED` | `true` | 是否导出 OTLP metrics |
+| `LANGSMITH_API_KEY` | （空） | LangSmith API Key，会映射为 OTLP `x-api-key` header |
+| `LANGSMITH_PROJECT` | （空） | 可选 LangSmith project header |
+| `LANGSMITH_OTLP_TRACES_ENDPOINT` | `https://api.smith.langchain.com/otel/v1/traces` | Collector 转发到在线 LangSmith 的 trace endpoint |
+| `MONITORING_INSTRUMENT_REQUESTS` | `false` | 是否启用 requests 自动 HTTP client span；默认关闭，避免 AI trace 被普通 HTTP 请求刷屏 |
+| `MONITORING_FASTAPI_EXCLUDED_URLS` | （空） | FastAPI 自动埋点排除 URL，逗号分隔正则；例如只看 agent 业务 span 时可设为 `/agent/run` |
+| `MONITORING_FASTAPI_EXCLUDE_SPANS` | `receive,send` | 排除 ASGI 内部 `receive/send` span；流式接口建议保持默认值 |
+| `OTEL_COLLECTOR_VERSION` | `0.150.0` | 本地 OpenTelemetry Collector Contrib 镜像版本 |
+| `PHOENIX_VERSION` | `15` | 本地 Phoenix 镜像版本 |
+| `LANGFUSE_VERSION` | `3` | 本地 Langfuse Web/Worker 镜像版本 |
+| `LANGFUSE_POSTGRES_VERSION` | `15-alpine` | 本地 Langfuse Postgres 镜像版本 |
+| `LANGFUSE_CLICKHOUSE_VERSION` | `26.3-alpine` | 本地 Langfuse ClickHouse 镜像版本 |
+| `LANGFUSE_MINIO_VERSION` | `RELEASE.2023-12-20T01-00-02Z` | 本地 Langfuse MinIO 镜像版本 |
+| `LANGFUSE_REDIS_VERSION` | `alpine` | 本地 Langfuse Redis 镜像版本 |
+| `GRAFANA_VERSION` | `12.4` | 本地 Grafana 镜像版本 |
+| `GRAFANA_PORT` | `3002` | 本地 Grafana UI 端口 |
+| `GRAFANA_ADMIN_USER` | `admin` | 本地 Grafana 管理员用户名 |
+| `GRAFANA_ADMIN_PASSWORD` | `nexent-grafana-admin` | 本地 Grafana 管理员密码 |
+| `GRAFANA_DEFAULT_LANGUAGE` | `zh-Hans` | 本地 Grafana 默认界面语言 |
+| `TEMPO_VERSION` | `2.10.5` | 本地 Tempo 镜像版本，避免浮动 tag 带来的配置兼容性漂移 |
+| `TEMPO_PORT` | `3200` | 本地 Tempo HTTP API 端口 |
+| `ZIPKIN_VERSION` | `latest` | 本地 Zipkin 镜像版本 |
+| `ZIPKIN_PORT` | `9411` | 本地 Zipkin UI/API 端口 |
+
+## 代码集成
+
+### Agent 边界上下文
+
+业务层只需要在请求入口解析出用户和 Agent 信息后绑定一次上下文，后续 Agent、LLM、Tool span 由 SDK 生命周期自动生成：
-# 检查 pyproject.toml 中的 performance 配置
-cat backend/pyproject.toml | grep -A 20 "performance"
+```python
+from nexent.monitor.agent_observability import AgentRunMetadata
+from utils.monitoring import monitoring_manager
+
+monitoring_manager.bind_agent_context(AgentRunMetadata(
+ tenant_id=tenant_id,
+ user_id=user_id,
+ agent_id=agent_request.agent_id,
+ conversation_id=agent_request.conversation_id,
+ query=agent_request.query,
+ is_debug=agent_request.is_debug,
+ language=language,
+))
```
-### 服务名显示为 unknown_service？
-```bash
-# 检查环境变量配置
-echo "SERVICE_NAME: $SERVICE_NAME"
+`monitor_endpoint` 仍保留为兼容 API 和低层 escape hatch，不建议业务层新增常规埋点时继续使用。
+
+### Trace Payload 策略
+
+工具输入输出、检索输出，以及 OpenInference 的 `input.value` / `output.value` 属性统一使用同一套 payload 策略。默认写入有界预览，并额外写入 `type`、`size_chars`、`item_count`、`truncated`、`keys` 等结构化属性。记忆检索 span 只记录结果摘要和统计信息，不写完整 memory 正文。
-# 重启监控服务以应用新配置
-./docker/start-monitoring.sh
+Agent 上下文指标由 SDK 生命周期自动写入。每个 action step 会产生 `agent.step.metrics` event，包含上下文 token 估算、压缩调用数、缓存命中、压缩率和 token 阈值。Agent 结束时还会在顶层 span 写入聚合 step 数、最大上下文 token、平均压缩率、压缩调用总数和缓存命中总数。
+
+### LLM 调用监控
+
+```python
+@monitoring_manager.monitor_llm_call("gpt-4", "chat_completion")
+def call_llm(messages):
+ return llm_response
```
-## 🧹 数据管理
+### Agent 步骤追踪
-### 清理 Jaeger 追踪数据
-```bash
-# 方法1: 重启 Jaeger 容器（最简单）
-docker-compose -f docker/docker-compose-monitoring.yml restart nexent-jaeger
+```python
+with monitoring_manager.trace_agent_step("web_search", step_type="tool_call") as span:
+ result = execute_tool()
+ monitoring_manager.set_tool_output(result)
+```
-# 方法2: 完全重建 Jaeger 容器和数据
-docker-compose -f docker/docker-compose-monitoring.yml stop nexent-jaeger
-docker-compose -f docker/docker-compose-monitoring.yml rm -f nexent-jaeger
-docker-compose -f docker/docker-compose-monitoring.yml up -d nexent-jaeger
+### 工具调用追踪
-# 方法3: 清理所有监控数据（重建所有容器）
-docker-compose -f docker/docker-compose-monitoring.yml down
-docker-compose -f docker/docker-compose-monitoring.yml up -d
+```python
+with monitoring_manager.trace_tool_call("web_search", "agent_name", {"query": "test"}) as span:
+ results = search_web("test")
+ monitoring_manager.set_tool_output({"results": results})
```
-### 清理 Prometheus 指标数据
-```bash
-# 重启 Prometheus 容器
-docker-compose -f docker/docker-compose-monitoring.yml restart nexent-prometheus
+### Phoenix 自定义层级埋点
+
+如果希望 Phoenix 展示 `agent -> chain -> llm/retriever/tool` 的层级结构，使用 SDK Agent 生命周期入口和 OpenInference span kind 封装方法：
+
+```python
+from nexent.monitor.agent_observability import AgentRunMetadata, get_monitoring_manager
+
+monitoring_manager = get_monitoring_manager()
+
+metadata = AgentRunMetadata(
+ tenant_id="tenant_id",
+ user_id="user_id",
+ agent_id=1,
+ conversation_id=1001,
+ agent_name="TestAgent",
+ query="你好",
+)
+
+with monitoring_manager.start_agent_run(metadata):
+ with monitoring_manager.trace_agent_step("Step 0", metadata, step_type="agent_loop"):
+ with monitoring_manager.trace_llm_request("OpenAIModel.generate", "gpt-4"):
+ result = call_llm()
+
+ with monitoring_manager.trace_retriever_call(
+ "knowledge_base_search",
+ "TestAgent",
+ {"query": "你好"},
+ ):
+ documents = search_knowledge_base("你好")
+ monitoring_manager.set_retriever_output(documents)
+
+ with monitoring_manager.trace_tool_call("FinalAnswerTool", "TestAgent", {"query": "你好"}):
+ monitoring_manager.set_tool_output({"answer": result})
+
+ monitoring_manager.set_openinference_output({"answer": result})
+```
-# 完全清理 Prometheus 数据
-docker-compose -f docker/docker-compose-monitoring.yml stop nexent-prometheus
-docker volume rm docker_prometheus_data 2>/dev/null || true
-docker-compose -f docker/docker-compose-monitoring.yml up -d nexent-prometheus
+Phoenix 左侧的 `agent`、`chain`、`llm`、`retriever`、`tool` 标签来自 `openinference.span.kind`。span 必须通过嵌套 `with` 创建，Phoenix 才会显示成树形结构。
+
+同一套方法只写入通用 OpenInference / Nexent 属性，不再写入 Langfuse 专用 span 字段。Langfuse provider 仍通过 OTLP endpoint 接收 trace，但展示和过滤以通用 OTLP/OpenInference 属性为准。
+
+## OpenInference 语义属性
+
+系统使用 OpenInference 语义约定，专为 AI 可观测性设计：
+
+### LLM 属性
+
+| 属性 | 说明 |
+|------|------|
+| `llm.model_name` | 模型标识（如 `gpt-4`） |
+| `llm.operation.name` | 操作类型（如 `chat_completion`） |
+| `llm.token_count.prompt` | 输入 Token 数 |
+| `llm.token_count.completion` | 输出 Token 数 |
+| `llm.invocation_parameters` | 模型参数（JSON） |
+| `llm.time_to_first_token` | TTFT（秒） |
+
+### Agent 属性
+
+| 属性 | 说明 |
+|------|------|
+| `agent.name` | Agent 标识 |
+| `agent.step.name` | 步骤名称（如 `web_search`） |
+| `agent.step.type` | 步骤类型：`tool_call`、`reasoning`、`action_selection` |
+| `agent.tool.name` | 工具名称 |
+| `agent.tool.input` | 按 trace payload 策略处理后的工具输入预览 |
+| `agent.tool.input.*` | 工具输入结构化元数据：类型、大小、item 数、截断状态、keys |
+| `agent.tool.output` | 按 trace payload 策略处理后的工具输出预览 |
+| `agent.tool.output.*` | 工具输出结构化元数据：类型、大小、item 数、截断状态、keys |
+| `agent.tool.success` | 工具调用是否成功 |
+| `agent.tool.duration_ms` | 工具调用耗时 |
+| `retriever.name` | 检索器名称 |
+| `retrieval.query` | 检索查询 |
+| `retrieval.results.count` | 检索结果数量 |
+| `retrieval.top_score` | 可用时记录最高检索分数 |
+| `retriever.input.*` | 检索输入结构化元数据 |
+| `retriever.output` | 按 trace payload 策略处理后的检索输出预览 |
+| `retriever.output.*` | 检索输出结构化元数据 |
+| `context.tokens.estimated_input` | 每个 Agent step event 的上下文输入 token 估算 |
+| `context.tokens.uncompressed_estimated` | 每个 Agent step event 的未压缩上下文 token 估算 |
+| `context.compression.calls` | 每个 Agent step event 的压缩调用数 |
+| `context.compression.cache_hits` | 每个 Agent step event 的压缩缓存命中数 |
+| `context.compression.ratio` | 每个 Agent step event 的压缩率 |
+
+## 指标
+
+| 指标 | 说明 |
+|------|------|
+| `llm.request.duration` | 请求延迟 |
+| `llm.token.generation_rate` | Token 生成速率 |
+| `llm.time_to_first_token` | TTFT |
+| `llm.token_count.prompt` | 输入 Token |
+| `llm.token_count.completion` | 输出 Token |
+| `agent.step.count` | Agent 步骤数 |
+| `agent.execution.duration` | Agent 执行时间 |
+| `agent.error.count` | Agent 错误数 |
+
+## Collector 配置
+
+OpenTelemetry Collector 默认只通过 debug exporter 打印数据，避免没有外部后端时把数据转发回自身。需要通过 Collector 转发到平台时，增加对应 exporter：
+
+```yaml
+exporters:
+ otlphttp/langsmith:
+ traces_endpoint: https://api.smith.langchain.com/otel/v1/traces
+ headers:
+ x-api-key: YOUR_LANGSMITH_API_KEY
+ Langsmith-Project: nexent
+
+service:
+ pipelines:
+ traces:
+ exporters: [otlphttp/langsmith, debug]
```
-### 清理 Grafana 配置
-```bash
-# 重置 Grafana 配置和仪表板
-docker-compose -f docker/docker-compose-monitoring.yml stop nexent-grafana
-docker volume rm docker_grafana_data 2>/dev/null || true
-docker-compose -f docker/docker-compose-monitoring.yml up -d nexent-grafana
+本地 Phoenix 和 Langfuse 分别使用独立 Collector 配置：
+
+- `docker/monitoring/otel-collector-phoenix-config.yml`
+- `docker/monitoring/otel-collector-langfuse-config.yml`
+- `docker/monitoring/otel-collector-langsmith-config.yml`
+
+基础 debug 配置见 `docker/monitoring/otel-collector-config.yml`。
+
+## 优雅降级
+
+未安装 OpenTelemetry 依赖时，监控自动禁用：
+
+```python
+pip install nexent # 基础包 - 无监控
+pip install nexent[performance] # 包含 OTLP 支持
```
-## 📈 典型问题分析
+禁用时所有监控方法均正常工作 - 装饰器透传，上下文管理器返回 None。
-### Token 生成速度慢 (< 5 tokens/s)
-1. **分析**: Grafana → Token Generation Rate 面板
-2. **解决**: 检查模型服务负载、优化输入 prompt 长度
+## 故障排除
-### 请求响应慢 (> 10s)
-1. **分析**: Jaeger → 查看完整链路追踪
-2. **解决**: 定位瓶颈环节（数据库/LLM/网络）
+### 数据未显示
-### 错误率突增 (> 10%)
-1. **分析**: Prometheus → llm_error_count 指标
-2. **解决**: 检查模型服务可用性、验证 API 密钥
+1. 检查 `.env` 中 `ENABLE_TELEMETRY=true`
+2. 验证 OTLP 端点可访问
+3. 检查认证头配置正确
-## 🎉 开始使用
+### 连接错误
-设置完成后你可以：
+1. 测试端点：`curl -v $OTEL_EXPORTER_OTLP_ENDPOINT/v1/traces`
+2. 确认协议匹配端点（`http` vs `grpc`）
+3. 查看 Collector 日志：`docker logs nexent-otel-collector`
-1. 📊 在 Grafana 中查看 **LLM Performance Dashboard**
-2. 🔍 在 Jaeger 中追踪每个请求的完整链路
-3. 📈 分析 Token 生成速度和性能瓶颈
-4. 🚨 设置性能告警和阈值
+### 属性错误
-享受高效的 LLM 性能监控！ 🚀
+1. 在平台 UI 中验证 OpenInference 属性
+2. 检查 Span 属性命名：使用 `llm.model_name` 而非 `model_name`
+3. 查看平台特定属性要求
diff --git a/doc/docs/zh/sdk/opentelemetry-design.md b/doc/docs/zh/sdk/opentelemetry-design.md
new file mode 100644
index 000000000..2f8f0a678
--- /dev/null
+++ b/doc/docs/zh/sdk/opentelemetry-design.md
@@ -0,0 +1,699 @@
+# Nexent OpenTelemetry 可观测性设计
+
+生成日期：2026-05-06
+基准分支：当前 OpenTelemetry 功能分支
+
+## 可观测性基础
+
+可观测性关注的是系统在运行过程中是否能够被理解和定位问题。相比只回答“系统是否还活着”的传统监控，可观测性更强调从运行时信号反推出系统内部状态，帮助研发和运维回答以下问题：
+
+- 当前请求为什么慢？
+- Agent 在哪一步失败？
+- 大模型调用耗时、首 token 时间和 token 速率是否异常？
+- 某个用户、会话或 Agent 的完整执行链路是什么？
+- 问题发生时有哪些输入、输出、工具调用和错误上下文？
+
+业界通常把可观测性拆成三大支柱：Metrics、Logs、Traces。三者解决的问题不同，需要组合使用。
+
+| 支柱 | 核心问题 | 典型数据 | 适合场景 | 在 Nexent 中的作用 |
+|------|----------|----------|----------|--------------------|
+| Metrics | “整体是否异常？” | 计数器、直方图、速率、分位数 | 看趋势、告警、容量评估、SLO/SLA | 统计 LLM 请求耗时、TTFT、token 速率、错误数、Agent step/tool 调用数 |
+| Logs | “当时发生了什么？” | 按时间顺序输出的文本或结构化事件 | 查看异常上下文、排查单点错误、审计关键行为 | 保留运行日志，并通过 span event/attribute 记录关键 Agent、LLM、Tool 事件 |
+| Traces | “一次请求经历了哪些步骤？” | trace、span、span event、上下游关系 | 分布式调用链、流式 Agent 执行链路、跨服务耗时定位 | 串联 HTTP 接口、Agent run、LLM generate、Tool call 和最终答案 |
+
+三大支柱之间不是替代关系。Metrics 适合发现问题，例如某段时间 LLM 错误数上升；Traces 适合定位问题，例如找到某次 `agent.run` 卡在某个 tool；Logs 适合补充细节，例如错误堆栈、原始提示词摘要或工具返回内容。对于 LLM Agent 场景，单纯的 HTTP 接口指标不足以解释 Agent 行为，因此必须把 Agent、LLM、Tool 等业务语义写入 trace 层级中。
+
+## 智能体可观测性行业洞察
+
+截至当前，智能体可观测性正在从传统 APM 的“接口是否健康、服务是否变慢”，扩展到“智能体为什么这样决策、哪一步引入了错误上下文、工具或检索是否误导了模型、成本和质量是否可控”。这类系统的核心难点不是单次 LLM 调用本身，而是一次用户请求会跨越路由、记忆、规划、检索、工具调用、模型生成、最终答案和反馈评价等多个阶段，并且每个阶段都可能影响最终结果。
+
+智能体可观测性的接入路径通常有几类：
+
+| 接入路径 | 典型方式 | 适合场景 | 需要注意 |
+|----------|----------|----------|----------|
+| 平台 SDK 直连 | Langfuse SDK、LangSmith SDK、Datadog / New Relic SDK、框架 callback | 快速接入某个平台的专有能力，例如 prompt 管理、评分、评估、成本分析 | 平台绑定更强，后续迁移或双写到其他后端成本较高 |
+| OpenTelemetry SDK 直连平台 OTLP endpoint | 应用直接用 OTLP HTTP/gRPC exporter 写入 Phoenix、Langfuse、LangSmith、Datadog 等兼容入口 | 希望保留 OTel 埋点模型，同时减少本地组件 | 鉴权、脱敏、采样、多后端分发逻辑会落在应用配置或平台侧 |
+| OpenTelemetry Collector 中转 | 应用只写 Collector，由 Collector 转发到 Phoenix、Langfuse、LangSmith、Grafana Tempo、Zipkin 或企业 APM | 需要统一批处理、采样、脱敏、header 注入、多后端转发和私有化部署 | 多一个运行组件，需要维护 Collector 配置和部署可用性 |
+| 平台 agent / 网关中转 | Datadog Agent、New Relic agent 或企业内部 telemetry gateway | 企业已有 APM 基础设施、权限、网络出口和审计要求明确 | 数据模型可能会被平台转换，AI 语义字段需要确认兼容性 |
+
+从知名 Agent/LLM 框架和平台的公开文档看，可观测性方案已经明显分成两层：框架或平台负责表达 Agent/LLM 运行时语义，OpenTelemetry/OTLP 负责把 trace、metric、log 导出到后端。差异主要在于：有些框架原生使用 OTel，有些通过 OpenInference/OpenLIT/OpenLLMetry 等 instrumentation 转成 OTel span，有些则先进入自有 tracing SDK，再通过 processor、callback 或平台集成转发。
+
+| Agent / 平台 | 原生可观测性能力 | 常用观测框架 / SDK | OTel / OTLP 路径 | 语义覆盖重点 | 局限与注意 |
+|--------------|------------------|--------------------|------------------|--------------|------------|
+| LangChain / LangGraph | LangSmith tracing、thread、feedback、evaluation，面向 chain、graph、run 的调试和评估 | LangSmith SDK、LangSmith OTel、OpenTelemetry SDK、Collector | `LANGSMITH_OTEL_ENABLED=true` 后可生成 OTel spans；LangSmith 提供 OTLP traces endpoint；也支持经 Collector fan-out 到多后端 | chain、graph node、LLM、tool、retriever、thread、feedback、eval | LangSmith 语义最完整；若只使用通用 OTel 后端，需要自行补齐 graph/thread/eval 维度 |
+| LlamaIndex | 内置 instrumentation/callback 体系，官方观测页覆盖 LlamaTrace、Phoenix、SigNoz、MLflow、Langfuse、OpenLLMetry、OpenLIT、AgentOps 等 | OpenInference LlamaIndex instrumentation、LlamaTrace/Phoenix、Langfuse、OpenLLMetry、OpenLIT、MLflow | Phoenix/LlamaTrace、SigNoz、Langfuse、OpenLIT 等路径都可通过 OTel/OTLP 导出；常见方式是 `openinference-instrumentation-llama-index` + OTLP exporter | RAG query engine、retriever、index、agent workflow、LLM、tool、token、latency | RAG 语义强，但不同集成对属性映射和评估能力不完全一致 |
+| OpenAI Agents SDK | SDK 内置 tracing，默认记录 runner、agent、generation、function tool、guardrail、handoff、speech 等 span | OpenAI Traces dashboard、custom trace processor、外部 tracing processors（Phoenix、MLflow、LangSmith、Langfuse、AgentOps、Datadog 等） | 默认不是 OTel span，而是 OpenAI Agents tracing 模型；要进入 OTLP 通常需要外部 tracing processor 或自定义 processor 做 OTel/OTLP 适配 | agent run、LLM generation、function tool、handoff、guardrail、自定义事件、会话分组 | Agent 语义完整，但与标准 OTel 数据模型之间需要转换层；敏感输入输出默认可能被采集，需显式配置 |
+| AutoGen | 新版 AutoGen 内置 tracing/observability，运行时支持 OpenTelemetry，并遵循 agent/tool 与 GenAI 语义约定；旧版 0.2 主要是 logging 和 partner providers | OpenTelemetry SDK、OTLP exporter、Jaeger/Zipkin、OpenAI instrumentor、AgentOps 等 | 可直接配置 OTel `TracerProvider` 和 OTLP exporter，把 AgentChat/GroupChat 运行时事件发到 OTel 兼容后端 | 多 Agent 消息、agent runtime、tool、LLM 调用、group chat、消息元数据 | 版本差异明显；需确认使用的是新版 AgentChat/Core 还是旧版 0.2 logging 集成 |
+| Dify | 产品内置 Monitoring Dashboard 和 Run History，可查看应用指标、workflow/node tracing；外部监控支持 Langfuse、LangSmith | Dify 内置监控、Langfuse integration、LangSmith integration | 官方文档主要体现为平台到 Langfuse/LangSmith 的集成和字段映射 | app、workflow/chatflow、node、message、dataset retrieval、tool、moderation、token、user/session | 产品语义强，适合低代码应用监控；开放 OTLP 可迁移性弱于原生 OTel instrumentation |
+| CrewAI | CrewAI AMP 内置 tracing，可通过 `tracing=True` 或 `CREWAI_TRACING_ENABLED=true` 追踪 crew/flow；官方观测页列出多种外部平台 | CrewAI AMP、OpenLIT、Langfuse、LangSmith OTel、Langtrace、Arize Phoenix、MLflow、Opik、Weave、Portkey 等 | OpenLIT 是 OTel-native，可配置 `OTEL_EXPORTER_OTLP_ENDPOINT`；LangSmith/CrewAI 集成使用 `opentelemetry-instrumentation-crewai`；Langfuse 可通过 OpenInference CrewAI instrumentation 产生 OTel spans | agent、task、crew、flow、tool、LLM、任务序列、成本、延迟 | 集成选择多但语义不完全统一；CrewAI AMP 与第三方 OTel 路径需要明确数据归属和脱敏策略 |
+| smolagents | 官方“Inspecting runs with OpenTelemetry”明确采用 OpenTelemetry 标准记录 agent runs | `smolagents[telemetry]`、OpenInference `SmolagentsInstrumentor`、Phoenix、Langfuse、OpenTelemetry SDK | 使用 `SmolagentsInstrumentor` 生成 OTel spans，可通过 `OTLPSpanExporter` 写 Phoenix，也可通过 Langfuse/其他 OTel 兼容平台接收 | CodeAgent、ToolCallingAgent、managed agents、工具调用、LLM 交互、多步执行 | 轻量、OTel 路径清晰；复杂评估、反馈和产品内权限仍依赖后端平台补齐 |
+
+从对比结果看，行业并不是简单地“统一使用某一个观测平台”，而是在向三种形态收敛：
+
+- 框架原生 OTel：AutoGen 新版、smolagents、Vercel AI SDK、Semantic Kernel 这类更容易直接进入 OTLP/Collector/企业 APM。
+- OTel instrumentation 桥接：LlamaIndex、CrewAI、LangChain/LangGraph 常通过 OpenInference、OpenLIT、OpenLLMetry、LangSmith OTel 等层把框架语义转成 OTel span。
+- 平台私有 tracing 再导出：OpenAI Agents SDK、Dify、CrewAI AMP 这类先保留自有产品语义，再通过 processor、callback、外部平台集成或字段映射与 OTel/LLMOps 平台互通。
+
+对 Nexent 来说，比较稳妥的策略是：核心埋点直接生成 OpenTelemetry span，并在 span 属性上兼容 OpenInference、OpenTelemetry GenAI、Langfuse/LangSmith 等主流语义；对外只承诺 OTLP 可导出，不把业务链路绑定到某一个平台 SDK。这样既能接入 Phoenix/Langfuse/LangSmith 这类 LLMOps 平台，也能接入 Grafana Tempo、Zipkin、Datadog、New Relic、Elastic、Honeycomb 等通用或企业级观测后端。
+
+因此，智能体可观测性的关键不是选择一个“唯一平台”，也不是强制所有链路都经过 Collector，而是先把遥测数据建模成可迁移、可组合、可扩展的结构：底层用标准 trace/metric/log 表达运行路径和性能，上层用 Agent/LLM/Tool/Retriever/Session/User/Evaluation 等语义补足业务解释能力。这样既能直连 Phoenix、Langfuse、LangSmith 等 AI 可观测平台，也能通过 Collector 接入 Grafana Tempo、Zipkin 或企业已有 APM，避免在产品早期把监控能力锁死在某个供应商或某套私有 SDK 中。
+
+## 为什么使用 OpenTelemetry
+
+```mermaid
+timeline
+ title 可观测性框架与协议演进时间线
+ 2010 : Google 发表 Dapper 论文
+ 2012 : Prometheus 在 SoundCloud 起步
+ 2015 : Jaeger 在 Uber 内部形成并发展
+ 2016 : OpenTracing 进入 CNCF
+ 2017 : OpenCensus 推广 tracing + stats/metrics + tags
+ 2019 : OpenTracing 与 OpenCensus 合并为 OpenTelemetry
+ 2021 : OpenTelemetry 晋升 CNCF Incubating
+ 2022 : OpenTracing 被归档；OpenTelemetry Metrics 发布 RC 并进入 GA 周期
+ 2023 : OpenCensus 于 7 月 31 日后停止维护
+ 2024 : Prometheus 持续增强对 OpenTelemetry/OTLP 的互操作
+ 2026 : OpenTelemetry 于 5 月 11 日 Graduated；OpenTracing compatibility 于 3 月被 deprecated
+```
+
+OpenTelemetry 是当前主流的可观测性开放标准，提供统一的 API、SDK、语义约定和 OTLP 传输协议。Nexent 选择 OpenTelemetry 作为监控主干，主要基于以下原因：
+
+- 标准化：用统一的 span、event、metric 表达 HTTP、Agent、LLM、Tool 等运行时信号，减少平台私有模型对业务代码的侵入。
+- 可移植：同一套埋点可以通过 OTLP 上报到 Phoenix、Langfuse、LangSmith、Grafana Tempo、Zipkin 或其他兼容后端，切换平台主要调整配置和 Collector pipeline。
+- 可扩展：OpenTelemetry Collector 可以在不改业务代码的情况下完成转发、过滤、批处理、认证 header 注入和多后端分发。
+- 生态成熟：FastAPI、requests 等基础组件已有自动埋点能力，Nexent 只需要补充 Agent/LLM/Tool 的业务 span。
+- 避免锁定：监控平台 SDK 可以作为增强层，但核心链路不依赖某一家平台 SDK，避免平台迁移或本地化部署时重写埋点。
+- 适合 Agent 场景：trace 的父子 span 结构天然适合表达 `agent.run -> chain step -> LLM generate/tool call -> final answer` 这类多步骤执行过程。
+
+因此，Nexent 的实现原则是：业务代码只产生 OpenTelemetry 标准信号和少量平台兼容属性，平台差异收敛在配置、Collector 和展示层。
+
+## OTel 规范概要
+
+本文中的 OTel 规范通常指 OpenTelemetry Specification 及其配套规范。它不是某个 SDK，也不是某个监控平台，而是一套兼容性契约：规定可观测性数据应该如何生成、命名、传播、处理和导出。各语言 SDK、Collector、后端平台和自动埋点库按这套契约实现，才能保证跨语言、跨框架、跨后端互通。
+
+一句话概括：OTel 规范是 OpenTelemetry 为 traces、metrics、logs 等可观测性数据制定的一套标准，保证不同语言、框架、Collector 和后端之间能够互通。
+
+OpenTelemetry 规范按 signal 维度独立演进。Tracing、Metrics、Logs、Baggage 是当前主要 signal；Profiles 正在发展中，Events 通常作为 Logs 的特定事件形态讨论。每个成熟 signal 通常由 API、SDK、OTLP、Collector 和 instrumentation/contrib 生态共同组成，语义约定用于保证不同语言和组件在观测同类操作时输出一致的数据。
+
+从实现视角看，OTel 规范可以拆成六个常用层面：
+
+| 规范领域 | 核心概念 | 作用 |
+|----------|----------|------|
+| Signals | Traces、Metrics、Logs、Baggage、Profiles | 定义可观测性数据类型。Nexent 当前重点使用 Traces 和 Metrics，Logs 通过应用日志与 span event 补充上下文；Profiles 暂不接入 |
+| API | Tracer、Meter、Logger、Context、Propagator | 面向业务代码和 instrumentation 的稳定接口，业务埋点只依赖 API，不直接绑定具体 exporter |
+| SDK | TracerProvider、MeterProvider、SpanProcessor、MetricReader、Sampler、Resource | 提供采样、批处理、资源描述、导出等运行时能力 |
+| Data Model | Span、Metric、LogRecord、Resource、Instrumentation Scope | 定义 telemetry 数据结构，确保不同语言和平台对数据有一致理解 |
+| Context Propagation | Context、SpanContext、Baggage、Propagator | 在服务、线程、异步任务和下游请求之间传递 trace 上下文，保证调用链可以串起来 |
+| OTLP | OTLP HTTP、OTLP gRPC、protobuf payload | OpenTelemetry 原生传输协议，负责把 traces、metrics、logs 从应用或 Collector 发到后端 |
+| Semantic Conventions | 标准属性名、span name、metric name、单位和枚举值 | 统一 HTTP、数据库、RPC、Messaging 等通用语义；AI 场景中 Nexent 额外兼容 OpenInference 和 Langfuse 属性 |
+
+### Signals
+
+OTel 把可观测性数据抽象为多个 signal。每个 signal 有独立 API 和数据模型，但共享 Resource、Context 和传播机制。
+
+- Traces：由一组具有父子关系的 span 构成，用于描述一次逻辑操作的完整路径。Nexent 用 trace 表达 `agent.run` 到 LLM、Tool、Final Answer 的执行链路。
+- Metrics：由 counter、histogram、gauge 等 instrument 产生，用于描述聚合后的趋势和分布。Nexent 用 metrics 统计 LLM 延迟、TTFT、token 速率和错误数。
+- Logs：以 LogRecord 或传统日志集成的方式表达离散事件。Nexent 当前不把 Logs signal 作为主链路 exporter，但会通过应用日志和 span event 补充错误上下文。
+- Baggage：跨进程传播的键值上下文，适合传递租户、用户、实验分组等需要参与过滤和关联的业务标签。使用时需要控制基数和敏感信息。
+- Profiles：用于记录代码级资源消耗画像，当前在 OpenTelemetry 体系中仍处于发展阶段。Nexent 暂不采集 profiles，避免引入额外运行时开销。
+
+Nexent 的当前落地策略是：Traces 优先，因为 Agent 运行链路需要父子 span 表达；Metrics 保留，用于趋势、告警和 dashboard；Logs 暂以应用日志和 span event 形态承载，后续如需统一日志采集，可以通过 Collector 增加 Logs pipeline。
+
+### API 与 SDK
+
+OTel 区分 API 和 SDK：
+
+- API 是埋点代码依赖的稳定接口，例如 `trace.get_tracer()`、`start_as_current_span()`、`meter.create_counter()`。
+- SDK 是运行时实现，负责创建 provider、处理 span/metric、采样、批量导出和错误处理。
+
+这种分层让库代码可以只依赖 API，而应用在启动时统一配置 SDK。Nexent 的 SDK 埋点遵循这个模型：业务函数只创建 span、event、metric；是否启用、导出到哪里、使用 HTTP 还是 gRPC，全部由 `MonitoringConfig` 和环境变量决定。
+
+这种分层也决定了 Nexent 的边界：
+
+- 业务代码不直接创建 exporter，也不直接引用 Phoenix、Langfuse、Tempo 等平台客户端。
+- 初始化层负责创建 SDK provider、resource、processor、reader 和 exporter。
+- 平台差异通过 provider profile、OTLP endpoint、header 和 Collector pipeline 表达。
+
+### Resource 与 Instrumentation Scope
+
+Resource 描述 telemetry 来源实体，例如服务名、版本、实例、部署环境、项目名。Nexent 当前写入：
+
+- `service.name`：默认 `nexent-backend`
+- `service.version`：当前固定为 `1.0.0`
+- `service.instance.id`：当前固定为 `nexent-instance-1`
+- `telemetry.provider`：当前 provider profile，例如 `otlp`、`phoenix`、`langfuse`、`grafana`、`zipkin`
+- `project.name`：当配置 `MONITORING_PROJECT_NAME` 时写入
+
+Instrumentation Scope 描述产生 telemetry 的 instrumentation 库或模块。后续如果需要区分 Nexent SDK、FastAPI 自动埋点、第三方库埋点，可以在 scope 层面辅助过滤。
+
+### Context Propagation
+
+Trace 的核心是上下文传播。一个请求从 HTTP 入口进入后，后续 Agent step、LLM 调用、Tool 调用必须处在同一个 trace 上下文中，监控页面才能显示正确的父子层级。
+
+OTel 的 Context 是执行范围内的不可变上下文容器，用于承载当前 span、baggage 等跨切面数据。Propagator 负责把这些上下文编码到请求边界，例如 HTTP header，再由下游服务还原。对 Nexent 来说，同进程内的 async、generator、线程和工具调用上下文保持比跨服务 header 传播更关键。
+
+Nexent 的关键处理包括：
+
+- 业务入口只绑定一次 `AgentRunMetadata`，保存 tenant、user、agent、conversation、query、language、memory 等请求级元数据。
+- SDK 在 `NexentAgent.agent_run_with_observer` 中创建顶层 `agent.run` span，并在 Agent loop、LLM、Tool 等生命周期中自动继承上下文。
+- `monitor_endpoint` 保留为兼容 API 和低层 escape hatch，不再作为业务层新增埋点的推荐方式。
+- Agent、LLM、Tool span 统一写入 OpenInference 和 Nexent 自定义属性，避免业务 trace 绑定到单一平台字段。
+
+### Semantic Conventions
+
+Semantic Conventions 规定常见遥测字段的命名和含义，例如 HTTP 方法、URL、状态码、错误类型、metric 单位等。使用语义约定的价值是让不同服务、语言和平台对同一类数据有一致理解。
+
+Nexent 采用三层语义：
+
+- OTel 通用语义：用于 service、resource、HTTP 自动埋点、metric instrument 等基础字段。
+- OpenInference 语义：用于 AI span 类型，例如 `openinference.span.kind=AGENT|CHAIN|LLM|TOOL|RETRIEVER`，适配 Phoenix 等 AI observability 平台。
+
+当平台展示存在差异时，Nexent 优先保持业务 span 的通用 OpenTelemetry / OpenInference 语义，不写入平台专用字段。
+
+### OTLP 与 Collector Pipeline
+
+OTLP 是 OpenTelemetry 原生传输协议，支持 HTTP 和 gRPC。Nexent 后端只需要把数据发到 OTLP endpoint，后端平台差异交给 Collector 处理。
+
+Collector pipeline 通常由三部分组成：
+
+- Receiver：接收应用上报的 OTLP traces/metrics/logs。
+- Processor：执行批处理、内存限制、资源属性补充、过滤、采样等处理。
+- Exporter：把数据转发到 Phoenix、Langfuse、Tempo 或其他 OTLP 兼容后端。
+
+OTLP 是 request/response 风格协议，客户端发送 export 请求，服务端返回成功、部分成功或失败响应。Nexent 当前支持：
+
+- OTLP HTTP：默认协议，便于通过网关、云平台和本地 Collector 接入。
+- OTLP gRPC：适合内部网络或偏高吞吐场景。
+- base endpoint 与 signal endpoint：支持配置 base endpoint，再由 SDK 推导 `/v1/traces` 和 `/v1/metrics`，也支持直接配置 signal-specific endpoint，避免路径重复拼接。
+
+这种架构的好处是：应用侧配置保持稳定，平台迁移和本地化部署主要改 Collector 配置。例如 `grafana` 形态下 traces 转发到 Tempo；`phoenix` 形态下 traces 转发到 Phoenix；`otlp` 形态下先通过 debug exporter 验证数据是否产生。
+
+## 设计目标
+
+Nexent 的监控能力以 OpenTelemetry 为主干，SDK 和后端只负责生成标准 span、event、metric，并通过 OTLP 导出。Phoenix、Langfuse、LangSmith、Grafana Tempo、Zipkin 和标准 OTLP 后端作为可配置 exporter 接入，业务代码不绑定单一平台。
+
+核心目标：
+
+- Agent 流式运行期间保持 trace 上下文，覆盖 API、服务准备、Agent 异步 generator、Agent 线程、LLM 流式输出、Python 解释器执行、真实工具调用和最终答案。
+- 通过 OpenInference 属性描述 Agent/LLM/Tool/Retriever 语义，同一套业务埋点可服务多个 OTLP 后端。
+- 支持 `otlp`、`phoenix`、`langfuse`、`langsmith`、`grafana`、`zipkin` provider profile。
+- 通过环境变量统一控制后端导出配置、本地部署形态和前端监控入口。
+- 支持 base endpoint 和 signal-specific endpoint，避免 `/v1/traces`、`/v1/metrics` 路径重复拼接。
+- FastAPI/requests 自动埋点可配置，默认压制流式接口中的 ASGI `receive/send` 噪声。
+
+## 技术栈
+
+| 分类 | 实现 |
+|------|------|
+| 标准框架 | OpenTelemetry API/SDK |
+| 导出协议 | OTLP HTTP、OTLP gRPC |
+| Trace exporter | `opentelemetry-exporter-otlp` HTTP/gRPC trace exporter |
+| Metric exporter | `opentelemetry-exporter-otlp` HTTP/gRPC metric exporter |
+| 自动埋点 | FastAPI instrumentation、requests instrumentation；requests 默认关闭 |
+| AI 语义 | OpenInference 属性、Langfuse OTel 属性、Nexent 自定义业务属性 |
+| Agent 框架 | SmolAgents `CodeAgent` 扩展、Nexent `CoreAgent`、`NexentAgent` |
+| 配置 | 环境变量 |
+| Collector | `otel/opentelemetry-collector-contrib`，支持 debug、Phoenix、Langfuse、LangSmith、Grafana/Tempo、Zipkin 部署形态 |
+
+## 总体架构
+
+```mermaid
+flowchart LR
+ Backend[Nexent Backend / SDK] --> OTel[OpenTelemetry TracerProvider / MeterProvider]
+ OTel --> Exporter[OTLP Trace / Metric Exporter]
+ Exporter --> Collector[OpenTelemetry Collector]
+ Collector --> Phoenix[Arize Phoenix]
+ Collector --> Langfuse[Langfuse]
+ Collector --> Tempo[Grafana Tempo]
+ Collector --> Zipkin[Zipkin]
+ Collector --> Other[OTLP Backend]
+
+ Backend --> FastAPI[FastAPI Auto Instrumentation]
+ Backend --> Manual[Manual AI Spans]
+ Manual --> OI[OpenInference Attributes]
+ Manual --> LF[Langfuse Attributes]
+```
+
+## 配置模型
+
+### 环境变量
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `ENABLE_TELEMETRY` | `false` | 监控总开关 |
+| `MONITORING_PROVIDER` | `otlp` | 监控 provider 和部署形态：`otlp`、`phoenix`、`langfuse`、`langsmith`、`grafana`、`zipkin` |
+| `MONITORING_DASHBOARD_URL` | 空 | 前端顶栏监控入口跳转 URL，后端只读取并透传该值 |
+| `MONITORING_PROJECT_NAME` | `nexent` | 平台项目名 |
+| `OTEL_SERVICE_NAME` | `nexent-backend` | OpenTelemetry service name |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4318` | OTLP base endpoint |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | 空 | 可选 trace 专用 endpoint |
+| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | 空 | 可选 metric 专用 endpoint |
+| `OTEL_EXPORTER_OTLP_PROTOCOL` | `http` | `http` 或 `grpc` |
+| `OTEL_EXPORTER_OTLP_HEADERS` | 空 | 通用 `key=value,key2=value2` header |
+| `OTEL_EXPORTER_OTLP_AUTHORIZATION` | 空 | `Authorization` header，常用于 Phoenix bearer auth 和 Langfuse Basic Auth |
+| `OTEL_EXPORTER_OTLP_X_API_KEY` | 空 | `x-api-key` header，用于兼容需要该 header 的平台 |
+| `OTEL_EXPORTER_OTLP_LANGFUSE_INGESTION_VERSION` | 空 | Langfuse 摄取版本，例如 `4` |
+| `LANGSMITH_API_KEY` | 空 | LangSmith API Key，后端直连时映射为 `x-api-key`，Collector 转发时注入 exporter header |
+| `LANGSMITH_PROJECT` | 空 | 可选 LangSmith project header |
+| `LANGSMITH_OTLP_TRACES_ENDPOINT` | `https://api.smith.langchain.com/otel/v1/traces` | Collector 转发到在线 LangSmith 的 trace endpoint |
+| `OTEL_EXPORTER_OTLP_METRICS_ENABLED` | `true` | 是否导出 metric |
+| `MONITORING_INSTRUMENT_REQUESTS` | `false` | 是否启用 requests 自动 HTTP client span |
+| `MONITORING_FASTAPI_EXCLUDED_URLS` | 空 | FastAPI 自动埋点排除 URL，逗号分隔正则 |
+| `MONITORING_FASTAPI_EXCLUDE_SPANS` | `receive,send` | 排除 ASGI 内部 `receive/send` span，流式接口建议保持默认 |
+| `OTEL_COLLECTOR_VERSION` | `0.150.0` | 本地 OpenTelemetry Collector Contrib 镜像版本 |
+| `PHOENIX_VERSION` | `15` | 本地 Phoenix 镜像版本 |
+| `LANGFUSE_VERSION` | `3` | 本地 Langfuse Web/Worker 镜像版本 |
+| `LANGFUSE_POSTGRES_VERSION` | `15-alpine` | 本地 Langfuse Postgres 镜像版本 |
+| `LANGFUSE_CLICKHOUSE_VERSION` | `26.3-alpine` | 本地 Langfuse ClickHouse 镜像版本 |
+| `LANGFUSE_MINIO_VERSION` | `RELEASE.2023-12-20T01-00-02Z` | 本地 Langfuse MinIO 镜像版本 |
+| `LANGFUSE_REDIS_VERSION` | `alpine` | 本地 Langfuse Redis 镜像版本 |
+| `GRAFANA_VERSION` | `12.4` | 本地 Grafana 镜像版本 |
+| `GRAFANA_PORT` | `3002` | 本地 Grafana UI 端口 |
+| `GRAFANA_DEFAULT_LANGUAGE` | `zh-Hans` | 本地 Grafana 默认界面语言 |
+| `TEMPO_VERSION` | `2.10.5` | 本地 Tempo 镜像版本，避免浮动 tag 带来的配置兼容性漂移 |
+| `TEMPO_PORT` | `3200` | 本地 Tempo HTTP API 端口 |
+| `ZIPKIN_VERSION` | `latest` | 本地 Zipkin 镜像版本 |
+| `ZIPKIN_PORT` | `9411` | 本地 Zipkin UI/API 端口 |
+
+## Endpoint 规则
+
+HTTP exporter 支持两种输入：
+
+- base endpoint：`https://cloud.langfuse.com/api/public/otel`
+- signal endpoint：`https://cloud.langfuse.com/api/public/otel/v1/traces`
+
+SDK 会按 signal 派生最终地址：
+
+| 输入 | Trace endpoint | Metric endpoint |
+|------|----------------|-----------------|
+| `https://host/api/public/otel` | `https://host/api/public/otel/v1/traces` | `https://host/api/public/otel/v1/metrics` |
+| `https://host/api/public/otel/v1/traces` | 原值 | `https://host/api/public/otel/v1/metrics` |
+| `https://host/api/public/otel/v1/metrics` | `https://host/api/public/otel/v1/traces` | 原值 |
+
+## 平台接入
+
+### 纯 OTLP / 自建 Collector
+
+```bash
+MONITORING_PROVIDER=otlp
+OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
+OTEL_EXPORTER_OTLP_PROTOCOL=http
+```
+
+前端顶栏监控入口不再根据 provider 在代码中映射 UI 端口和路径。后端读取 `MONITORING_DASHBOARD_URL` 并通过 `/monitoring/status` 返回给前端；该值为空时前端不显示监控入口。因此本地 Grafana 形态需要在后端 `.env` 中设置：
+
+```bash
+MONITORING_PROVIDER=grafana
+MONITORING_DASHBOARD_URL=http://localhost:3002/d/nexent-llm-agent/nexent-agent-trace-monitoring?orgId=1
+```
+
+### Phoenix
+
+Phoenix 通过 OpenInference 属性识别 AI span 类型，核心字段是 `openinference.span.kind`。
+
+```bash
+MONITORING_PROVIDER=phoenix
+OTEL_EXPORTER_OTLP_ENDPOINT=https://app.phoenix.arize.com/s/YOUR_SPACE
+OTEL_EXPORTER_OTLP_AUTHORIZATION="Bearer YOUR_PHOENIX_API_KEY"
+OTEL_EXPORTER_OTLP_METRICS_ENABLED=false
+MONITORING_PROJECT_NAME=nexent-production
+```
+
+### Langfuse
+
+Langfuse 的 OTLP HTTP base endpoint 是 `/api/public/otel`，使用 Basic Auth。实时摄取建议带 `x-langfuse-ingestion-version=4`。
+
+```bash
+MONITORING_PROVIDER=langfuse
+OTEL_EXPORTER_OTLP_ENDPOINT=https://cloud.langfuse.com/api/public/otel
+OTEL_EXPORTER_OTLP_AUTHORIZATION="Basic BASE64_PUBLIC_SECRET"
+OTEL_EXPORTER_OTLP_LANGFUSE_INGESTION_VERSION=4
+OTEL_EXPORTER_OTLP_METRICS_ENABLED=false
+```
+
+当前实现不写入 `langfuse.*` 专用 span 属性，Langfuse 通过 OTLP 接收通用 OpenTelemetry / OpenInference span。
+
+### LangSmith
+
+LangSmith 的在线 OTLP trace endpoint 为 `https://api.smith.langchain.com/otel/v1/traces`，使用 `x-api-key` header 认证，可通过 `Langsmith-Project` header 指定项目。推荐仍让 Nexent 后端上报到本地 Collector，由 Collector 注入 LangSmith API Key 并转发 traces：
+
+```bash
+MONITORING_PROVIDER=langsmith
+OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
+OTEL_EXPORTER_OTLP_PROTOCOL=http
+OTEL_EXPORTER_OTLP_METRICS_ENABLED=false
+```
+
+Collector 侧配置 `LANGSMITH_API_KEY`、`LANGSMITH_PROJECT` 和 `LANGSMITH_OTLP_TRACES_ENDPOINT`。LangSmith 当前形态只转发 traces，metrics 进入 Collector debug pipeline。
+
+### Zipkin
+
+Zipkin 通过 Collector 的 Zipkin exporter 接收 traces。推荐 Nexent 后端仍然只上报到本地 Collector，由 Collector 转发到 Zipkin v2 spans endpoint：
+
+```bash
+MONITORING_PROVIDER=zipkin
+OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
+OTEL_EXPORTER_OTLP_PROTOCOL=http
+OTEL_EXPORTER_OTLP_METRICS_ENABLED=false
+MONITORING_DASHBOARD_URL=http://localhost:9411
+```
+
+Zipkin 当前本地形态只转发 traces；metrics 进入 Collector debug pipeline。
+
+## 本地化部署设计
+
+本地化部署通过 `docker/start-monitoring.sh` 选择形态。所有形态都保留 OpenTelemetry Collector 作为入口，Nexent 后端统一上报到 `http://otel-collector:4318` 或宿主机的 `http://localhost:4318`，平台差异只体现在 Collector exporter 和本地服务组合上。
+
+| 形态 | Collector 配置 | 本地服务 | 数据去向 | 说明 |
+|------|----------------|----------|----------|------|
+| `otlp` | `otel-collector-config.yml` | Collector | debug exporter | 最小形态，用于验证 span/metric 是否产生，或手动改配置转发到云端平台；`collector` 仅作为启动脚本兼容别名 |
+| `phoenix` | `otel-collector-phoenix-config.yml` | Collector + Phoenix | `http://phoenix:6006/v1/traces` | Phoenix 容器同时提供 UI 和 OTLP HTTP/gRPC trace collector，适合本地 trace debug |
+| `langfuse` | `otel-collector-langfuse-config.yml` | Collector + Langfuse Web/Worker + Postgres + ClickHouse + MinIO + Redis | `http://langfuse-web:3000/api/public/otel/v1/traces` | Langfuse v3 依赖多组件，适合完整 LLMOps 能力验证 |
+| `langsmith` | `otel-collector-langsmith-config.yml` | Collector | `https://api.smith.langchain.com/otel/v1/traces` | 在线 LangSmith trace 分析；API Key 只配置在 Collector 环境 |
+| `grafana` | `otel-collector-grafana-config.yml` | Collector + Grafana + Tempo | traces 转发到 `tempo:4317`，metrics 只进入 Collector debug pipeline | Grafana + Tempo trace 查询 |
+| `zipkin` | `otel-collector-zipkin-config.yml` | Collector + Zipkin | traces 转发到 `zipkin:9411/api/v2/spans`，metrics 只进入 Collector debug pipeline | Zipkin trace 查询 |
+
+启动命令：
+
+```bash
+cd docker
+./start-monitoring.sh --stack otlp
+./start-monitoring.sh --stack phoenix
+./start-monitoring.sh --stack langfuse
+./start-monitoring.sh --stack langsmith
+./start-monitoring.sh --stack grafana
+./start-monitoring.sh --stack zipkin
+```
+
+部署脚本职责：
+
+- 创建或复用 `nexent-network`。
+- 首次启动时从 `monitoring.env.example` 生成 `monitoring.env`。
+- 根据 `MONITORING_PROVIDER` 或 `--stack` 选择 Docker Compose profile。
+- 根据部署形态设置 `OTEL_COLLECTOR_CONFIG_FILE`。
+- Langfuse 本地形态下，如果 `LANGFUSE_OTLP_AUTH_HEADER` 未显式配置，则使用初始化项目的 public/secret key 生成 Basic Auth header。
+- LangSmith 在线形态要求 `LANGSMITH_API_KEY`，启动时会校验该变量，避免 Collector 静默丢弃鉴权失败的 trace。
+
+### Phoenix 本地形态
+
+Phoenix 使用 `arizephoenix/phoenix` 镜像，默认暴露：
+
+| 端口 | 用途 |
+|------|------|
+| `6006` | Phoenix UI 和 OTLP HTTP `/v1/traces` |
+| `4319` | 映射到容器内 gRPC OTLP `4317`，避免与 Collector gRPC 端口冲突 |
+
+Compose 中设置 `PHOENIX_WORKING_DIR=/mnt/data` 并挂载 `phoenix-data` volume，确保本地重启后 trace 数据不丢失。Collector 使用 `otlphttp/phoenix` exporter 的 base endpoint `http://phoenix:6006`，由 Collector 按 OTLP HTTP 规则追加 `/v1/traces`。
+
+### Langfuse 本地形态
+
+Langfuse v3 本地形态按自托管架构拆分为应用容器和存储组件：
+
+| 组件 | 用途 |
+|------|------|
+| `langfuse-web` | UI、API、OTLP HTTP ingestion |
+| `langfuse-worker` | 异步消费和处理 trace 事件 |
+| `langfuse-postgres` | 事务型元数据 |
+| `langfuse-clickhouse` | trace/observation/score 分析数据 |
+| `langfuse-minio` | S3 兼容对象存储，保存事件和大对象 |
+| `langfuse-redis` | 队列和缓存 |
+
+初始化参数通过 `LANGFUSE_INIT_*` 配置，默认创建 `nexent-local` 项目和本地 API Key。Collector 使用 `otlphttp/langfuse` exporter，endpoint 为 `http://langfuse-web:3000/api/public/otel`，并携带：
+
+```yaml
+headers:
+ Authorization: ${env:LANGFUSE_OTLP_AUTH_HEADER}
+ x-langfuse-ingestion-version: "4"
+```
+
+默认密钥仅用于本地验证。生产或共享环境必须替换认证密钥、数据库密码、对象存储密钥和 `LANGFUSE_ENCRYPTION_KEY`，并补充备份、高可用和升级策略。
+
+### Grafana 本地形态
+
+Grafana 本地形态面向 trace 调试：
+
+| 组件 | 用途 |
+|------|------|
+| `grafana` | 展示 Nexent Agent trace dashboard，并预置 Tempo datasource |
+| `tempo` | 接收 Collector 转发的 OTLP traces，并提供 Grafana Explore 查询后端 |
+
+Collector trace pipeline 使用 `otlp/tempo` exporter 转发到 `tempo:4317`。Tempo 启用 `metrics-generator` 的 `local-blocks` processor，用于支持 Grafana trace breakdown 中的 TraceQL metrics 查询。Collector metrics pipeline 保留为 debug exporter，用于兼容后端仍开启 OTLP metrics 的场景，但本地 Grafana 形态不提供独立指标存储和指标 dashboard。
+
+### Zipkin 本地形态
+
+Zipkin 本地形态面向轻量 trace 查询：
+
+| 组件 | 用途 |
+|------|------|
+| `zipkin` | 接收 Collector 转发的 traces，并提供 trace 查询 UI |
+
+Collector trace pipeline 使用 `zipkin` exporter 转发到 `http://zipkin:9411/api/v2/spans`。Collector metrics pipeline 保留为 debug exporter。
+
+默认访问地址：
+
+- Zipkin UI：`http://localhost:9411`
+
+## Span 语义映射
+
+| Nexent 场景 | OpenInference |
+|-------------|---------------|
+| Agent 入口 | `openinference.span.kind=AGENT` |
+| 服务准备、流式生成、线程执行、普通步骤 | `openinference.span.kind=CHAIN` |
+| LLM 调用 | `openinference.span.kind=LLM` |
+| 工具调用 | `openinference.span.kind=TOOL` |
+| 检索类调用 | `openinference.span.kind=RETRIEVER` |
+
+上下文属性：
+
+| 属性 | 说明 |
+|------|------|
+| `input.value` / `output.value` | OpenInference 输入输出 |
+| `metadata` | OpenInference JSON metadata |
+| `session.id` / `user.id` | OpenInference 会话和用户 |
+| `tag.tags` | OpenInference tags |
+
+## 埋点信息
+
+| 埋点 | 位置 | 类型 | 内容 | 目的 |
+|------|------|------|------|------|
+| FastAPI 自动 span | `MonitoringManager.setup_fastapi_app` | HTTP server | route、method、status、duration | API 入口耗时和错误定位 |
+| FastAPI `receive/send` 排除 | `fastapi_exclude_spans` | 降噪配置 | 默认 `receive,send` | 避免 SSE 流式接口生成大量 `unknown POST /agent/run http ...` |
+| requests 自动 span | `MonitoringConfig.instrument_requests` | HTTP client | 外部请求 URL、method、status | 默认关闭；需要分析外部 HTTP 依赖时开启 |
+| `AgentRunMetadata` | `run_agent_stream` 边界 | context | tenant、user、agent、conversation、query、language、memory、文件数 | 业务层只绑定一次请求上下文，后续 span 由 SDK 自动继承 |
+| `agent.run` | `NexentAgent.agent_run_with_observer` | AGENT | query、session、user、tenant、agent、metadata、tags | 作为一次 Agent 运行的顶层业务 trace |
+| `agent.run.loop` | `NexentAgent.agent_run_with_observer` | CHAIN | Agent loop、step、最终输出 | 追踪实际 Agent 执行生命周期 |
+| `{display_name or model_id}.generate` | `sdk/nexent/core/models/openai_llm.py` | LLM / generation | 模型、温度、top_p、消息、输入输出、token、TTFT、chunk 数 | LLM 性能、成本、输出和异常分析 |
+| `python_interpreter` | `sdk/nexent/core/agents/core_agent.py` | TOOL | 生成代码、step number、执行输出、日志、是否最终答案 | 观测 CodeAgent 解释器执行 |
+| 真实工具名 | `sdk/nexent/core/agents/nexent_agent.py` | TOOL | local/MCP/langchain/builtin 工具输入输出 | 观测真实工具可用性、延迟、错误和输入输出 |
+| `FinalAnswerTool` | `sdk/nexent/core/agents/core_agent.py` | TOOL | 最终答案输出 | 让 Phoenix/Langfuse 中能明确看到最终答案节点 |
+| `monitor_endpoint` | SDK 兼容 API | AGENT / CHAIN | 自定义 operation、参数、错误 | 低层 escape hatch；不推荐业务层新增常规埋点 |
+| `start_agent_run` / `trace_agent_step` / `trace_retriever_call` | SDK 公共 API | AGENT / CHAIN / RETRIEVER | Agent metadata、输入输出、session、user | SDK 生命周期埋点和少量自定义层级埋点 |
+| `trace_tool_call` | SDK 公共 API | TOOL | 工具名、输入、输出、耗时、错误 | SDK 用户自定义工具埋点 |
+
+### 事件清单
+
+| Span / 位置 | Event | 主要属性 | 目的 |
+|-------------|-------|----------|------|
+| `agent.run` | `agent.run.started` / `agent.run.completed` / `agent.run.error` | `error.*` | 观测一次 Agent 运行的开始、结束和异常 |
+| LLM span | `completion_started` / `first_token_received` / `token_generated` / `completion_finished` / `model_stopped` / `error_occurred` | `model_id`、`temperature`、`top_p`、`message_count`、`total_duration`、`output_length`、`chunk_count`、`error.*` | 分析模型参数、流式输出耗时、停止和异常 |
+| Tool span | span 属性 `agent.tool.input` / `agent.tool.output` | JSON 字符串、`agent.tool.duration_ms`、`error.*` | 分析工具输入输出、耗时和异常 |
+
+## 指标
+
+| 指标 | 类型 | 维度 | 用途 |
+|------|------|------|------|
+| `llm.request.duration` | histogram | model、operation | LLM 请求延迟 |
+| `llm.token.generation_rate` | histogram | model | token/s |
+| `llm.time_to_first_token` | histogram | model | 首 token 延迟 |
+| `llm.token_count.prompt` | counter | model | 输入 token 成本 |
+| `llm.token_count.completion` | counter | model | 输出 token 成本 |
+| `llm.error.count` | counter | model、operation | LLM 错误率 |
+| `agent.step.count` | counter | agent、step type、tool | Agent 步骤和工具调用量 |
+| `agent.execution.duration` | histogram | agent、status | Agent 总耗时 |
+| `agent.error.count` | counter | agent、error type | Agent 异常统计 |
+
+## Agent 运行数据流
+
+```mermaid
+flowchart TD
+ U[用户] --> FE[前端 Chat]
+ FE --> API[POST /agent/run]
+ API --> HTTP[FastAPI HTTP span: 可配置隐藏]
+ API --> Bind[绑定 AgentRunMetadata]
+ Bind --> Mem[解析 memory 开关]
+ Mem --> Strategy{with_memory / no_memory}
+ Strategy -->|with_memory| G1[generate_stream_with_memory]
+ Strategy -->|no_memory| G2[generate_stream_no_memory]
+ G1 --> AR[agent_run async generator]
+ G2 --> AR
+ AR --> Thread[agent_run_thread]
+ Thread --> NX[NexentAgent / CoreAgent]
+ NX --> A0[agent.run span: AGENT]
+ A0 --> Step[agent.run.loop: CHAIN]
+ Step --> LLM[Model.generate: LLM / generation]
+ Step --> PY[python_interpreter: TOOL]
+ PY --> Tool[Real local / MCP / langchain / builtin tool: TOOL]
+ PY --> Final[FinalAnswerTool: TOOL]
+ LLM --> Attr1[OpenInference + Langfuse attrs]
+ Tool --> Attr1
+ Final --> Attr1
+ Attr1 --> OTel[OpenTelemetry Tracer/Meter Provider]
+ OTel --> Collector[OTLP Collector]
+ Collector --> Phoenix[Phoenix]
+ Collector --> Langfuse[Langfuse]
+ Collector --> Tempo[Grafana Tempo]
+ Collector --> Zipkin[Zipkin]
+ Collector --> Other[OTLP Backend]
+```
+
+预期平台树形结构：
+
+```text
+agent.run agent
+└─ agent.run.loop chain
+ ├─ Model.generate llm / generation
+ ├─ python_interpreter tool
+ │ └─ RealTool tool
+ └─ FinalAnswerTool tool
+```
+
+FastAPI HTTP span 可以保留在最上层用于接口视角，也可以通过 `MONITORING_FASTAPI_EXCLUDED_URLS=/agent/run` 在 AI trace 视图中隐藏。
+
+## 监控页面结构
+
+```mermaid
+flowchart TB
+ Page[Agent 监控页] --> Filters[筛选区: 时间 / 租户 / 用户 / Agent / 会话 / 模型 / 状态]
+ Page --> KPIs[指标区: 成功率 / P95 / TTFT / tokens/s / token 成本 / 工具错误数]
+ Page --> TraceList[Trace 列表: Agent / 会话 / 用户 / 状态 / 耗时 / Token / 模型 / 最后错误]
+ Page --> Detail[Trace 详情]
+ Detail --> Waterfall[Span 瀑布图: agent / chain / llm / tool]
+ Detail --> Timeline[Agent 时间线: 准备 / 记忆 / LLM / 工具 / 最终答案]
+ Detail --> LLMPanel[LLM 面板: prompt / output / token / TTFT / generation rate]
+ Detail --> ToolPanel[工具面板: 工具名 / 输入 / 输出 / 耗时 / 错误]
+ Detail --> Session[会话和用户上下文]
+ Detail --> Raw[原始 OTel 属性和 events]
+ Detail --> Eval[反馈、评分和评估]
+```
+
+监控平台之间不能只按“是否能收 trace”比较。对智能体场景，更关键的是是否理解 LLM/Agent 语义、是否支持评估和反馈、是否适合本地化部署、是否能与企业已有 APM 合流。下面按 Nexent 可能接入的平台做比较：
+
+| 平台 | 类型 | 部署形态 | 主要接入方式 | AI / Agent 语义 | Metrics / Logs | 评估 / 反馈 | 适合场景 | Nexent 当前适配 |
+|------|------|----------|--------------|-----------------|----------------|-------------|----------|----------------|
+| Phoenix | AI 原生可观测性 / 实验分析 | 云服务或自托管 | OTLP、OpenInference、Phoenix SDK | OpenInference 生态匹配好，适合展示 LLM、retriever、agent、tool 等语义 | 重点在 trace 和实验分析，通用 infra 监控不是核心 | 支持 eval、dataset、实验分析 | 本地 trace debug、RAG/LLM 质量分析、OpenInference 语义验证 | 写入 OpenInference 属性；支持本地 Phoenix stack 和 OTLP 转发 |
+| Langfuse | LLMOps / Prompt 与 Trace 平台 | 云服务或自托管 | OTLP、Langfuse SDK、API | 对 trace、observation、session、user、prompt、metadata 支持完整 | 提供 LLM 应用维度 dashboard，通用 infra 监控不是重点 | 支持 score、feedback、eval、prompt 管理 | 需要 prompt 管理、用户会话、反馈和成本闭环的 LLM 应用 | 支持本地 Langfuse stack 和 OTLP 转发；业务 span 不写入 `langfuse.*` 专用属性 |
+| LangSmith | LangChain / LangGraph 生态观测与评估 | 云服务为主 | LangSmith SDK、OTLP endpoint | 与 LangChain/LangGraph run、thread、feedback、evaluation 生态贴合 | 重点在应用 trace 和评估，不替代通用 APM | 评估、dataset、反馈、回归测试能力强 | 使用 LangChain/LangGraph 或需要在线评估闭环 | 支持 Collector 注入 `x-api-key` 和 `Langsmith-Project` 转发 traces |
+| Grafana Tempo + Grafana | 通用 trace 后端 / Dashboard | 自托管或云服务 | OTLP、Jaeger、Zipkin 等，经 Collector 常见 | 不内置 LLM/Agent 专用语义，需要 dashboard 和属性约定补充 | Grafana 生态可接 Prometheus、Loki、Tempo 组合 | 不提供原生 LLM 评估，需要外部系统 | 私有化、本地化、已有 Grafana/Prometheus/Loki 体系 | 支持本地 Tempo + Grafana stack，预置 Tempo datasource 和 trace dashboard |
+| Zipkin | 轻量分布式 tracing | 自托管 | Zipkin API，通常由 Collector exporter 转发 | 只理解通用 trace/span，不理解 LLM/Agent 语义 | 不提供 metrics/logs 平台能力 | 不提供评估能力 | 最小本地 trace 查询、验证转发链路、低成本调试 | 支持本地 Zipkin stack，Collector 转发 traces |
+| Datadog LLM Observability | 全栈 APM + LLM Observability | 云服务 / Agent | Datadog SDK、Agent、OTel/OTLP 等 | 支持 LLM 应用 traces、prompt/completion、成本、质量和安全维度 | 全栈 metrics/logs/traces/APM/infra 能力强 | 支持 LLM evaluations、质量和安全监控 | 企业已有 Datadog，需把 AI 应用纳入统一生产监控 | 可通过标准 OTLP/Collector 或平台 SDK 接入，当前未内置本地 stack |
+| New Relic AI Monitoring | 全栈 APM + AI Monitoring | 云服务 / Agent | New Relic agent、OTel/OTLP 等 | 关注 LLM app 性能、错误、成本和模型交互 | 全栈 APM、infra、logs、browser/mobile 生态完整 | 提供 AI 应用监控与分析能力，评估深度依赖平台能力 | 企业已有 New Relic，关注生产运行和统一告警 | 可通过标准 OTLP/Collector 或平台 agent 接入，当前未内置本地 stack |
+| Elastic Observability | 全栈可观测性 / 搜索分析 | 云服务或自托管 | Elastic APM agent、OTel/OTLP、EDOT | 支持 LLM observability 和 OTel 语义，适合把 AI trace 与日志、指标、搜索分析合并 | logs、metrics、traces、搜索分析能力强 | 侧重监控、分析和 dashboard，业务评估闭环仍需额外设计 | 已有 Elastic Stack、重视日志检索、私有化和统一搜索分析 | 可通过 OTLP/Collector 对接，当前未内置本地 stack |
+| Honeycomb | 事件驱动可观测性 / 高基数分析 | 云服务 | OTLP、OpenTelemetry SDK、Events API / libhoney | 擅长高基数 trace/event 分析，AI 语义通过属性和 OTel GenAI 约定表达 | 强在 trace/event 和指标分析，日志通常通过事件化方式分析 | 不提供完整 LLMOps 评估闭环 | 需要按租户、用户、agent、tool 做高维切片分析 | 可通过 OTLP/Collector 对接，当前未内置本地 stack |
+| Nexent 自建页 | 产品内业务观测 | 自建 | 复用 OTel 属性和业务数据库 | 最能理解租户、会话、Agent 配置、权限、版本和业务动作 | 需要自建指标、查询、存储和告警 | 可与产品反馈、评分和评估闭环深度结合 | 产品内闭环、权限隔离、面向终端用户或运维角色的监控页 | 当前先通过 OTLP 对接外部平台，后续可基于同一批属性构建自有页面 |
+
+从选型上可以把平台分成三类：
+
+- AI 原生平台优先解决“Agent 为什么这样回答、prompt/tool/retrieval 是否有效、质量如何评估”的问题，适合研发调试和 LLMOps 闭环。
+- 通用 trace 后端优先解决“链路是否完整、哪一步慢、部署是否轻量和可私有化”的问题，适合本地调试和私有化基础能力。
+- 全栈 APM 优先解决“生产系统整体是否健康、AI 服务如何纳入企业统一监控、告警和审计”的问题，适合已有企业监控体系的团队。
+
+按使用场景选择时，可以简化成下面的矩阵：
+
+| 场景 | 优先平台 | 原因 | 代价 |
+|------|----------|------|------|
+| 本地开发和快速看 trace | Phoenix、Zipkin、Grafana Tempo | 自托管简单，能快速验证 span 层级、Collector 转发和属性是否正确 | 对质量评估、prompt 管理和业务闭环支持有限 |
+| RAG / Agent 质量分析 | Phoenix、Langfuse、LangSmith | 更理解 prompt、completion、retriever、tool、session、feedback 和 eval | 平台语义差异较大，需要保留可迁移的 OTel 属性 |
+| 企业生产统一监控 | Datadog、New Relic、Elastic、Honeycomb | 能和服务、基础设施、日志、指标、告警、权限体系合流 | AI 业务语义需要通过 OTel GenAI/OpenInference/自定义属性补齐 |
+| 产品内用户态监控页 | Nexent 自建页 + 外部 trace 后端 | 能结合租户、权限、Agent 配置、会话、反馈和产品操作 | 需要自建查询、聚合、权限隔离和可视化能力 |
+
+因此 Nexent 的策略不是只绑定一个平台，而是以 OpenTelemetry/OTLP 和兼容语义属性作为主干：本地默认支持 Phoenix、Langfuse、Grafana Tempo、Zipkin 等便于验证的形态；线上或企业环境可以把同一批 traces 转发到 LangSmith、Datadog、New Relic、Elastic、Honeycomb 或其他 OTLP 兼容后端。
+
+推荐路径：
+
+1. 短期使用 OTLP 对接 Phoenix/Langfuse/LangSmith，满足调试和分析。
+2. 中期在 Nexent 增加 trace 跳转、轻量指标概览和异常聚合。
+3. 长期按租户、会话、Agent 版本建立自有监控页，同时保留 OTLP 双写能力。
+
+## 已修复的设计风险
+
+| 风险 | 修复 |
+|------|------|
+| 业务层埋点耦合过高 | 业务入口只绑定 `AgentRunMetadata`，Agent/LLM/Tool 语义 span 下沉到 SDK 生命周期 |
+| `/v1/traces` 路径重复拼接 | SDK 支持 base endpoint 和 signal endpoint 自动归一化 |
+| Collector header 无法兼容平台 | Collector 默认只 debug；平台转发配置拆分 `Authorization`、`x-api-key`、`x-langfuse-ingestion-version` |
+| Phoenix 只看到接口看不到 Agent | SDK 顶层 `agent.run` 标记为 AGENT，内部 `agent.run.loop` 标记为 CHAIN |
+| Phoenix/Langfuse 中出现大量 `unknown POST /agent/run http ...` | 默认排除 FastAPI ASGI `receive/send` span；requests 自动埋点默认关闭；可配置隐藏 `/agent/run` HTTP span |
+| Langfuse 字段耦合过重 | 不写入 `langfuse.*` 专用 span 属性，仅保留 OTLP 转发和 OpenInference 语义 |
+| LLM span 不明显或缺输出 | LLM span 命名为 `{display_name or model_id}.generate`，并写入 `output.value` |
+| 工具 span 缺失 | 在 `NexentAgent.create_single_agent` 统一包装 local/MCP/langchain/builtin 工具，并在 `CoreAgent` 增加 `python_interpreter` 和 `FinalAnswerTool` span |
+| 单测漏掉 SDK 生命周期路径 | 增加 AgentRunMetadata、Agent/chain、LLM/Tool 继承上下文测试 |
+
+## 使用建议
+
+只看 Agent 业务链路时：
+
+```bash
+MONITORING_FASTAPI_EXCLUDE_SPANS=receive,send
+MONITORING_FASTAPI_EXCLUDED_URLS=/agent/run
+MONITORING_INSTRUMENT_REQUESTS=false
+```
+
+同时看接口入口和 Agent 业务链路时：
+
+```bash
+MONITORING_FASTAPI_EXCLUDE_SPANS=receive,send
+MONITORING_FASTAPI_EXCLUDED_URLS=
+MONITORING_INSTRUMENT_REQUESTS=false
+```
+
+需要排查外部 HTTP 依赖时：
+
+```bash
+MONITORING_INSTRUMENT_REQUESTS=true
+```
+
+## 参考
+
+- OpenTelemetry Collector: https://opentelemetry.io/docs/collector/
+- OpenTelemetry OTLP Specification: https://opentelemetry.io/docs/specs/otlp/
+- OpenTelemetry GenAI Semantic Conventions: https://opentelemetry.io/docs/specs/semconv/gen-ai/
+- OpenInference Semantic Conventions: https://arize-ai.github.io/openinference/spec/semantic_conventions.html
+- LangSmith Trace with OpenTelemetry: https://docs.langchain.com/langsmith/trace-with-opentelemetry
+- LangGraph Observability: https://docs.langchain.com/langgraph-platform/langsmith-observability
+- LlamaIndex Observability: https://docs.llamaindex.ai/en/stable/module_guides/observability/
+- LlamaIndex OpenTelemetry Integration: https://docs.llamaindex.ai/en/stable/api_reference/observability/otel/
+- OpenAI Agents SDK Tracing: https://openai.github.io/openai-agents-python/tracing/
+- Semantic Kernel Telemetry: https://learn.microsoft.com/en-us/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-console
+- CrewAI Tracing: https://docs.crewai.com/en/observability/tracing
+- CrewAI OpenTelemetry Export: https://docs.crewai.com/en/enterprise/guides/capture_telemetry_logs
+- CrewAI OpenLIT Integration: https://docs.crewai.com/en/observability/openlit
+- AgentOps CrewAI Integration: https://docs.agentops.ai/v1/integrations/crewai
+- AutoGen Agent Observability: https://microsoft.github.io/autogen/stable/user-guide/agentchat-user-guide/agent-observability.html
+- AutoGen Tracing and Observability: https://microsoft.github.io/autogen/stable/user-guide/agentchat-user-guide/tracing.html
+- Dify Monitoring Dashboard: https://docs.dify.ai/en/use-dify/monitor/analysis
+- Dify Langfuse Integration: https://docs.dify.ai/en/use-dify/monitor/integrations/integrate-langfuse
+- Dify LangSmith Integration: https://docs.dify.ai/en/use-dify/monitor/integrations/integrate-langsmith
+- Dify Agent Node: https://docs.dify.ai/en/guides/workflow/node/agent
+- smolagents Inspecting runs with OpenTelemetry: https://huggingface.co/docs/smolagents/en/tutorials/inspect_runs
+- smolagents Phoenix tracing guide: https://huggingface.co/blog/smolagents-phoenix
+- Vercel AI SDK Telemetry: https://ai-sdk.dev/docs/ai-sdk-core/telemetry
+- Haystack Tracing: https://docs.haystack.deepset.ai/docs/tracing
+- Phoenix Setup Tracing: https://arize.com/docs/phoenix/tracing/how-to-tracing/setup-tracing
+- Phoenix Setup OTEL: https://arize.com/docs/phoenix/tracing/how-to-tracing/setup-tracing/setup-using-phoenix-otel
+- Phoenix Authentication: https://arize.com/docs/phoenix/deployment/authentication
+- Phoenix Self-Hosting: https://arize.com/docs/phoenix/self-hosting
+- Phoenix Docker Deployment: https://arize.com/docs/phoenix/self-hosting/deployment-options/docker
+- Langfuse OpenTelemetry: https://langfuse.com/integrations/native/opentelemetry
+- Langfuse Self-Hosting: https://langfuse.com/self-hosting
+- Langfuse Docker Compose: https://langfuse.com/self-hosting/local
+- Langfuse Overview: https://langfuse.com/docs
+- LangSmith OpenTelemetry: https://docs.langchain.com/langsmith/otel-gateway-trace-redaction
+- Datadog LLM Observability: https://docs.datadoghq.com/llm_observability/
+- New Relic AI Monitoring: https://docs.newrelic.com/docs/ai-monitoring/intro-to-ai-monitoring/
+- Elastic OpenTelemetry: https://www.elastic.co/docs/solutions/observability/apm/opentelemetry/
+- Elastic EDOT data streams: https://www.elastic.co/docs/reference/opentelemetry/data-streams
+- Honeycomb Send Data: https://docs.honeycomb.io/send-data/
+- Honeycomb for LLMs: https://docs.honeycomb.io/send-data/llm/
+- Grafana Tempo: https://grafana.com/docs/tempo/latest/
+- Zipkin OpenTelemetry Collector exporter: https://opentelemetry.io/docs/collector/configuration/#exporters
+- Zipkin Docker image: https://hub.docker.com/r/openzipkin/zipkin
diff --git a/doc/docs/zh/sdk/vector-database.md b/doc/docs/zh/sdk/vector-database.md
index 940af9c33..b940400fd 100644
--- a/doc/docs/zh/sdk/vector-database.md
+++ b/doc/docs/zh/sdk/vector-database.md
@@ -579,7 +579,11 @@ python -m nexent.service.vectordatabase_service
- 参数:
- `index_name`: 索引名称 (路径参数)
- `path_or_url`: 文档路径或URL (查询参数)
- - 返回示例: `{"status": "success", "deleted_count": 1}`
+ - `scope`: 删除范围 (查询参数，默认 `full`)
+ - `source_only`: 仅删除 MinIO 源文件，保留 ES 中的切片与向量（检索仍可用，预览不可用）
+ - `full`: 删除 ES 文档、MinIO 源文件，并清理相关 Redis 任务记录
+ - 返回示例 (`source_only`): `{"status": "success", "scope": "source_only", "deleted_es_count": 0, "deleted_minio": true, "source_available": false}`
+ - 返回示例 (`full`): `{"status": "success", "scope": "full", "deleted_es_count": 5, "deleted_minio": true}`
#### 搜索操作
@@ -728,8 +732,11 @@ curl -X POST "http://localhost:8000/indices/search/hybrid" \
"weight_accurate": 0.3
}'
-# 删除文档
-curl -X DELETE "http://localhost:8000/indices/my_documents/documents?path_or_url=https://example.com/doc1"
+# 删除源文件（保留索引）
+curl -X DELETE "http://localhost:8000/indices/my_documents/documents?path_or_url=knowledge_base/doc1.pdf&scope=source_only"
+
+# 从知识库彻底移除文档
+curl -X DELETE "http://localhost:8000/indices/my_documents/documents?path_or_url=knowledge_base/doc1.pdf&scope=full"
# 创建索引
curl -X POST "http://localhost:8000/indices/my_documents"
diff --git a/doc/docs/zh/user-guide/agent-development.md b/doc/docs/zh/user-guide/agent-development.md
index 67d3c8311..40805aeea 100644
--- a/doc/docs/zh/user-guide/agent-development.md
+++ b/doc/docs/zh/user-guide/agent-development.md
@@ -31,15 +31,99 @@
### 🤝 协作 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 服务提供商的要求
+
+
+###### 通过URL对接[DataAgent](https://gitcode.com/datagallery/dataagent) A2A Agent
+1. 参考[DataAgent文档](https://gitcode.com/datagallery/dataagent#%F0%9F%8C%90-a2a-10-%E6%9C%8D%E5%8A%A1%E6%A8%A1%E5%BC%8F)以A2A服务模式启动DataAgent
+ >当前Nexent不支持带认证的agent，启动DataAgent时请勿设置auth-token
+
+
+
+
+2. 参考[通过 URL 发现 Agent](#通过-url-发现-agent)接入agent，url为http://\:9999/.well-known/agent-card.json
+3. 参考[管理已发现的外部 Agent](#管理已发现的外部-agent)配置调用协议，选择HTTP+JSON方式接入
+
### 🛠️ 选择智能体的工具
智能体可以使用各种工具来完成任务，如知识库检索、文件解析、图片解析、收发邮件、文件管理等本地工具，也可接入第三方 MCP 工具，或自定义工具。
@@ -60,7 +144,10 @@
> 2. 请选择 `analyze_text_file` 工具，启用文档类、文本类文件的解析功能。
> 3. 请选择 `analyze_image` 工具，启用图片类文件的解析功能。
>
+> ⚠️ **向量化模型配置**：使用 `knowledge_base_search` 工具时，需要确保知识库已配置向量化模型。对于存量知识库，系统会提示选择向量化模型，请务必选择**创建该知识库时使用的向量化模型**。若选择的模型与知识库创建时使用的模型不一致，可能导致检索失败或结果不准确。
+>
> 📚 想了解系统已经内置的所有本地工具能力？请参阅 [本地工具概览](./local-tools/index.md)。
+> 📚 想了解技能能力？请参阅 [技能管理](./skills.md)。
### 🔌 添加 MCP 工具
@@ -108,6 +195,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 +250,8 @@
- 测试的 `query`，例如"维生素C的功效"
- 检索的模式 `search_mode`（默认为 `hybrid`）
- 目标检索的知识库列表 `index_names`，如 `["医疗", "维生素知识大全"]`
- - 若不输入 `index_names`，则默认检索知识库页面所选中的全部知识库
- - 是否启用重排模型（默认为 `false`），启用后配置重排模型，实现对检索结果的重排优化
+ - 若不输入 `index_names`，则默认检索知识库页面所选中的全部知识库
+ - 是否启用重排模型（默认为 `false`），启用后配置重排模型，实现对检索结果的重排优化
6. 输入完成后点击"执行测试"开始测试，并在下方查看测试结果
@@ -172,7 +293,8 @@
-### 🐛 调试与保存
+## 🐛 调试与保存
+
在完成初步智能体配置后，您可以对智能体进行调试，根据调试结果微调提示词，持续提升智能体表现。
@@ -182,7 +304,7 @@
调试成功后，可点击右下角"保存"按钮，此智能体将会被保存并出现在智能体列表中。
-### 🐛 版本管理
+## 🐛 版本管理
Nexent 支持智能体的版本管理，您可以在调试过程中，保存不同版本的智能体配置。
@@ -194,6 +316,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/dataagent_deploy.png b/doc/docs/zh/user-guide/assets/agent-development/dataagent_deploy.png
new file mode 100644
index 000000000..46fa9fde3
Binary files /dev/null and b/doc/docs/zh/user-guide/assets/agent-development/dataagent_deploy.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..71ba3e950 100644
--- a/doc/docs/zh/user-guide/local-tools/index.md
+++ b/doc/docs/zh/user-guide/local-tools/index.md
@@ -9,6 +9,8 @@
- [搜索工具](./search-tools)：本地/DataMate/Dify 知识库检索与 Exa/Tavily/Linkup 公网搜索。
- [多模态工具](./multimodal-tools)：文本文件与图片的下载、解析、模型分析。
- [终端工具](./terminal-tool)：持久化 SSH 会话，远程执行命令。
+- [SQL 工具](./sql-tools)：连接 MySQL、PostgreSQL、SQL Server 执行 SQL 查询。
+- [技能（Skills）](../skills)：Nexent内置工具组合或自定义能力包，支持 NL 生成与版本管理。
## ⚙️ 配置入口
@@ -21,4 +23,4 @@
- 路径类操作仅限工作空间范围，请使用相对路径。
- 公网搜索需先在平台安全配置中填写 API Key。
- 终端工具涉及远程主机，请确认网络与账号安全策略。
-- 删除、移动类操作不可恢复，执行前先确认目标。
\ No newline at end of file
+- 删除、移动类操作不可恢复，执行前先确认目标。
diff --git a/doc/docs/zh/user-guide/local-tools/multimodal-tools.md b/doc/docs/zh/user-guide/local-tools/multimodal-tools.md
index 114504365..3470a2c1c 100644
--- a/doc/docs/zh/user-guide/local-tools/multimodal-tools.md
+++ b/doc/docs/zh/user-guide/local-tools/multimodal-tools.md
@@ -4,18 +4,22 @@ title: 多模态工具
# 多模态工具
-多模态工具组支持分析文本文件与图片，结合模型能力生成用户问题相关的解读结果。支持 S3、HTTP、HTTPS 等 URL。
+多模态工具组支持分析文本文件、图片、视频与音频，结合模型能力生成用户问题相关的解读结果。支持 S3、HTTP、HTTPS 等 URL。
## 🧭 工具清单
- `analyze_text_file`：下载并提取文本文件内容后进行分析
- `analyze_image`：下载图片并使用视觉语言模型进行理解与描述
+- `analyze_video`：下载视频并使用视频理解模型进行分析
+- `analyze_audio`：下载音频并使用音频理解模型进行分析
## 🧰 使用场景示例
- 对上传到存储桶的文档进行快速摘要或要点提取
- 对截图、产品图片、报表图进行内容解读或关键信息提取
-- 结合问题指令，对多份文件/图片分别生成答案列表
+- 对上传的视频进行内容理解，如提取关键帧信息、人物动作、场景描述等
+- 对音频文件进行内容分析，如转录、说话人识别、内容摘要等
+- 结合问题指令，对多份文件/图片/视频/音频分别生成答案列表
## 🧾 参数要求与行为
@@ -29,16 +33,26 @@ title: 多模态工具
- `query`：用户问题/关注点。
- 会逐张图片下载并调用视觉语言模型，返回与顺序对应的描述或答案数组。
+### analyze_video
+- `video_url`：视频 URL，支持 `s3://bucket/key`、`/bucket/key`、`http(s)://`。
+- `query`：用户问题/关注点。
+- 下载视频后调用视频理解模型，返回视频分析结果。
+
+### analyze_audio
+- `audio_url`：音频 URL，支持 `s3://bucket/key`、`/bucket/key`、`http(s)://`。
+- `query`：用户问题/关注点。
+- 下载音频后调用音频理解模型，返回音频分析结果。
+
## ⚙️ 前置配置
- 确保已在平台配置可用的存储客户端（如 MinIO/S3）及数据处理服务地址，保证能下载文件。
-- 为 `analyze_text_file` 配置可用的 LLM；为 `analyze_image` 配置可用的视觉语言模型。
+- 为 `analyze_text_file` 配置可用的 LLM；为 `analyze_image` 配置可用的视觉语言模型；为 `analyze_video` 和 `analyze_audio` 配置可用的视频理解模型（需支持音视频输入，如 Qwen3-Omni 系列模型）。
## 🛠️ 操作指引
-1. 准备文件或图片的可访问 URL，确认权限与路径正确。
-2. 调用相应工具，填写 URL 列表与问题描述；支持一次处理多条资源。
-3. 检查返回的数组结果顺序与输入列表一致，便于继续引用或展示。
+1. 准备文件、图片、视频或音频的可访问 URL，确认权限与路径正确。
+2. 调用相应工具，填写 URL 与问题描述；支持一次处理多条资源。
+3. 检查返回结果，确认内容符合预期后再继续引用或展示。
## 💡 最佳实践
diff --git a/doc/docs/zh/user-guide/local-tools/sql-tools.md b/doc/docs/zh/user-guide/local-tools/sql-tools.md
new file mode 100644
index 000000000..b5b50af59
--- /dev/null
+++ b/doc/docs/zh/user-guide/local-tools/sql-tools.md
@@ -0,0 +1,75 @@
+---
+title: SQL 数据库工具
+---
+
+# SQL 数据库工具
+
+SQL 数据库工具组支持连接和查询 MySQL、PostgreSQL、SQL Server 等关系型数据库，让 AI 智能体能够直接读取和操作数据库数据。
+
+## 工具清单
+
+- `mysql_database`：连接 MySQL 数据库执行 SQL 查询
+- `postgres_database`：连接 PostgreSQL 数据库执行 SQL 查询
+- `mssql_database`：连接 SQL Server 数据库执行 SQL 查询
+
+## 使用场景示例
+
+- 从业务数据库中查询报表数据，供智能体分析汇总
+- 跨数据库关联查询，获取分散在多个表中的关联信息
+- 实时查询业务状态，为智能体提供最新数据参考
+
+## 参数要求与行为
+
+### 通用参数
+- `sql`：要执行的 SQL 查询语句，必填
+- `parameters`：参数化查询的参数值列表，可选
+- `max_rows`：最大返回行数，默认 100
+- `timeout`：查询超时时间（秒），默认 10
+
+### 数据库连接参数
+
+| 数据库 | 连接参数 |
+|--------|----------|
+| MySQL | `host`、`user`、`password`、`database`、`port`（默认 3306） |
+| PostgreSQL | `host`、`user`、`password`、`database`、`port`（默认 5432） |
+| SQL Server | `host`、`user`、`password`、`database`、`port`（默认 1433） |
+
+### 安全限制
+- 禁止执行 `DROP DATABASE`、`GRANT`、`REVOKE`、`CREATE USER`、`INTO OUTFILE`、`LOAD DATA INFILE` 等危险操作
+- `UPDATE` 和 `DELETE` 语句必须包含 `WHERE` 子句
+- 自动添加 `LIMIT` 限制返回行数
+
+### 返回格式
+```json
+{
+ "status": "success",
+ "columns": ["id", "name", "email"],
+ "rows": [[1, "张三", "zhang@example.com"]],
+ "row_count": 1,
+ "execution_time_ms": 45.23
+}
+```
+
+## 操作指引
+
+1. **准备数据库连接信息**：获取主机地址、端口、数据库名、用户名和密码
+2. **配置工具**：在智能体工具配置中添加对应数据库工具，填写连接参数
+3. **测试连接**：使用简单查询验证连接是否正常
+4. **构造查询**：让智能体理解自然语言需求，生成对应 SQL 执行
+
+## 安全与最佳实践
+
+- 生产环境建议使用只读账号，限制操作权限
+- 敏感信息如数据库密码可通过密钥管理服务存储
+- 合理设置 `max_rows` 避免一次性返回过多数据
+- 建议开启数据库连接的 SSL/TLS 加密选项
+
+## 常见数据库连接示例
+
+| 数据库 | 连接地址示例 | 参数占位符 |
+|--------|-------------|------------|
+| MySQL | `localhost:3306` | `?` |
+| PostgreSQL | `localhost:5432` | `$1, $2, ...` |
+| SQL Server | `localhost:1433` | `?` |
+
+> 不同数据库的参数占位符格式不同，PostgreSQL 使用 `$1, $2` 格式，其他使用 `?`。
diff --git a/doc/docs/zh/user-guide/mcp-tools.md b/doc/docs/zh/user-guide/mcp-tools.md
index 912306284..94bf7c656 100755
--- a/doc/docs/zh/user-guide/mcp-tools.md
+++ b/doc/docs/zh/user-guide/mcp-tools.md
@@ -1,27 +1,158 @@
# MCP 工具
-即将推出的 MCP 工具管理模块将让您在一个页面集中管理 MCP 服务器与工具，轻松完成连接配置、工具同步和健康状态监控
+在 MCP 工具模块中，您可以集中管理所有 MCP（Model Context Protocol）服务器与工具，支持自定义添加、注册表导入和社区导入等多种接入方式，完成连接配置、工具同步、健康监控以及社区共享。
-## 🎯 功能预览
+MCP 工具页面包含两个并列页签：
-1. 注册并管理多个 MCP 服务器
-2. 快速同步、查看并整理 MCP 工具列表
-3. 实时监控 MCP 连接状态和使用情况
+- **导入的服务**：管理当前租户已接入的 MCP 服务，在此配置、监控和维护您的 MCP 服务。
+- **发布的服务**：管理当前租户发布到社区的 MCP 服务，支持浏览、编辑和取消发布。
-## ⏳ 敬请期待
+---
-MCP 工具管理功能正在开发中，我们致力于打造一个高效、直观的管理平台，让您能够：
+## ➕ 添加 MCP 服务
-1. 集中管理所有 MCP 服务器
-2. 便捷同步和组织工具
-3. 实时掌握服务器连接与工具运行状态
+点击页面上的"添加 MCP 服务"按钮，打开添加弹窗。弹窗提供三个页签，对应不同的接入来源。
-## 🚀 相关功能
+### 自定义添加
-在等待 **MCP 工具** 上线期间，您可以：
+"自定义添加"页签支持手动配置 MCP 服务，分为两种传输类型。
-1. 在 **[智能体开发](./agent-development)** 中管理您的 MCP 工具
-2. 通过 **[智能体空间](./agent-market)** 查看智能体与 MCP 的协作关系
-3. 在 **[开始问答](./start-chat)** 中体验平台功能
+#### 通过 URL 添加
-如果您在使用过程中遇到任何问题，请参考我们的 **[常见问题](../quick-start/faq)** 或在[GitHub Discussions](https://github.com/ModelEngine-Group/nexent/discussions)中进行提问获取支持。
\ No newline at end of file
+适用于已有独立部署的 MCP 服务（支持 HTTP / SSE 协议），通过输入端点 URL 直接接入。
+
+1. 在"本地添加"页签中，**传输类型**选择"URL"
+2. 填写服务信息：
+ - **服务名称（必填）**：为 MCP 服务设置一个易于识别的名称
+ - **服务 URL（必填）**：输入 MCP 服务的端点地址
+ - **描述**：可选，填写服务的用途说明
+ - **Authorization Token**：可选，若服务需要认证，在此填入 Bearer Token
+3. 点击"确定"完成添加，系统会自动连接服务并获取可用工具列表
+
+#### 通过容器配置添加
+
+适用于需要本地容器化运行的 MCP 服务（如通过 npx 启动的服务），系统会根据您提供的 JSON 配置自动创建并管理容器。
+
+1. 在"本地添加"页签中，**传输类型**选择"容器"
+2. 填写容器配置信息：
+ - **服务名称（必填）**：为 MCP 服务设置一个易于识别的名称
+ - **描述**：可选，填写服务的用途说明
+ - **容器配置 JSON（必填）**：按标准 MCP 配置格式填写，例如：
+ ```json
+ {
+ "mcpServers": {
+ "service-name": {
+ "args": ["mcp-package-name@version"],
+ "command": "npx",
+ "env": {
+ "API_KEY": "xxxx"
+ }
+ }
+ }
+ }
+ ```
+ - **端口号**：填写容器服务暴露的端口，系统会自动检测端口冲突并提示可用端口
+3. 点击"确定"，系统将解析 JSON 配置、创建容器并完成服务注册
+
+### 从 MCP Registry 导入
+
+Nexent 集成了 MCP Registry，您可以浏览并一键导入社区维护的 MCP 服务。
+
+1. 切换到"外部市场"页签
+2. 浏览可用的 MCP 服务列表，支持按名称或标签搜索
+3. 点击目标服务，查看服务详情（描述、版本、所需参数等）
+4. 配置必填参数（如 API Key 等环境变量）
+5. 点击"导入"，系统会自动安装并配置该 MCP 服务
+
+### 从社区导入
+
+浏览其他用户在 Nexent 平台内发布的 MCP 服务，快速导入使用。
+
+1. 切换到"社区市场"页签
+2. 浏览社区已发布的 MCP 服务，支持按名称、标签或传输协议筛选
+3. 点击目标服务查看详情，点击"导入"即可添加到您的服务列表中
+
+---
+
+## 📋 导入的服务
+
+"导入的服务"页签以卡片形式展示当前租户所有已接入的 MCP 服务，您可以在此查看、编辑、监控和发布。
+
+### 查看与筛选
+
+每张服务卡片展示以下信息：
+
+- 服务名称与描述
+- 来源标识（本地 / 注册表 / 社区）
+- 启用 / 禁用开关
+- 标签
+
+您可以使用顶部的筛选栏，按**来源**、**传输类型**和**标签**进行过滤，也可以通过搜索框按名称快速定位服务。
+
+### 编辑服务详情
+
+点击任意服务卡片，打开详情弹窗，可以进行以下操作：
+
+- **编辑基本信息**：修改服务名称、描述、URL、Authorization Token 和标签
+- **启用 / 禁用服务**：通过开关控制服务的启用状态，禁用后该服务的工具将不会出现在智能体工具选择中
+- **删除服务**：移除 MCP 服务记录，容器化服务会同步清理容器资源
+
+### 查看工具列表
+
+在服务详情弹窗中，点击"工具列表"按钮，可以查看该 MCP 服务提供的所有工具。
+
+### 健康检查
+
+点击详情弹窗中的"健康检查"按钮，系统会对 MCP 服务发起连接测试并返回当前状态：
+
+- **正常**：服务可正常连接
+- **异常**：服务无法连接或响应异常
+- **未检测**：尚未进行健康检查
+
+### 容器管理
+
+对于容器化部署的 MCP 服务，详情弹窗中还提供以下操作：
+
+- **查看容器日志**：实时查看运行中容器的输出日志，方便排查问题
+- **查看容器配置**：查看创建容器时使用的配置 JSON
+
+### 发布到社区
+
+在服务详情弹窗中，点击"发布到社区"按钮：
+
+1. 确认或修改发布信息（名称、描述、标签等）
+2. 点击"确认发布"，该服务将发布到社区
+3. 发布后其他用户可在添加服务的"社区市场"页签中浏览和导入
+
+---
+
+## 🌐 发布的服务
+
+"发布的服务"页签展示您自己发布到社区的所有 MCP 服务，您可以在此集中管理已发布的内容。
+
+每张卡片展示服务名称、描述、版本和标签，支持按名称、标签和传输协议进行筛选。
+
+点击服务卡片可查看详细信息，您可以：
+
+- **编辑发布的服务**：修改已发布服务的名称、描述和标签
+- **删除发布的服务**：将服务从社区撤回，不再对其他用户可见
+
+---
+
+## 🔗 与智能体协作
+
+添加 MCP 服务后，其提供的工具会自动同步到智能体的工具选择列表中。在 **[智能体开发](./agent-development)** 页面配置智能体时：
+
+1. 在"选择智能体的工具"页签下，找到对应 MCP 服务分组
+2. 点击工具名称即可启用该工具
+3. 可点击 ⚙️ 查看工具描述并进行参数配置
+
+## 🚀 下一步
+
+完成 MCP 服务配置后，建议您：
+
+1. **[智能体开发](./agent-development)** - 将 MCP 工具配置给智能体使用
+2. **[智能体空间](./agent-space)** - 查看智能体与 MCP 的协作关系
+3. **[开始问答](./start-chat)** - 在对话中体验智能体调用 MCP 工具的效果
+
+如果您在使用过程中遇到任何问题，请参考我们的 **[常见问题](../quick-start/faq)** 或在 [GitHub Discussions](https://github.com/ModelEngine-Group/nexent/discussions) 中进行提问获取支持。
\ 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..6870f5544 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/doc/procedural-memory-verification.md b/doc/procedural-memory-verification.md
new file mode 100644
index 000000000..ea9f53290
--- /dev/null
+++ b/doc/procedural-memory-verification.md
@@ -0,0 +1,315 @@
+# Procedural Memory Verification Report
+
+## Summary
+**Status: ⚠️ FULLY SUPPORTED but REQUIRES OPTIONAL DEPENDENCY**
+
+Procedural memory is a fully implemented feature in mem0ai version 0.1.117, **BUT it requires `langchain-core` to be installed separately**. Without this dependency, the feature will fail at runtime.
+
+---
+
+## ⚠️ CRITICAL FINDING: Optional Dependency Required
+
+**Your colleague is partially correct.** The procedural memory code is NOT empty (it's 50 lines of real implementation), but it has a critical dependency issue:
+
+### The Problem
+
+The `_create_procedural_memory()` method contains:
+
+```python
+try:
+ from langchain_core.messages.utils import convert_to_messages
+except Exception:
+ logger.error(
+ "Import error while loading langchain-core. "
+ "Please install 'langchain-core' to use procedural memory."
+ )
+ raise # ← Fails here if langchain-core not installed
+```
+
+### Reality Check
+
+| Aspect | Status |
+|--------|--------|
+| Code exists? | ✅ Yes, 50 lines of real implementation |
+| Code is empty/stub? | ❌ No, it's fully implemented |
+| Works out of the box? | ❌ **NO** - requires `langchain-core` package |
+| Documented requirement? | ⚠️ Only in error message, not in main docs |
+
+### Why Your Colleague Thought It Was Empty
+
+1. They called `memory.add(..., memory_type="procedural_memory")`
+2. Got `ImportError: No module named 'langchain_core'`
+3. Saw the error and concluded "it doesn't work" or "it's empty"
+4. This is understandable - the feature exists but is **disabled by default**
+
+---
+
+## Verification Results
+
+### 1. API Support ✅
+The `memory_type` parameter is available in both `AsyncMemory.add()` and `Memory.add()`:
+
+```python
+async def add(
+ self,
+ messages,
+ *,
+ user_id: Optional[str] = None,
+ agent_id: Optional[str] = None,
+ run_id: Optional[str] = None,
+ metadata: Optional[Dict[str, Any]] = None,
+ infer: bool = True,
+ memory_type: Optional[str] = None, # ✅ SUPPORTED
+ prompt: Optional[str] = None,
+ llm=None
+)
+```
+
+### 2. MemoryType Enum ✅
+Located in `mem0.configs.enums.MemoryType`:
+
+```python
+class MemoryType(Enum):
+ SEMANTIC = "semantic_memory"
+ EPISODIC = "episodic_memory"
+ PROCEDURAL = "procedural_memory" # ✅ AVAILABLE
+```
+
+### 3. Implementation ✅
+The `_create_procedural_memory()` method exists in both `AsyncMemory` and `Memory` classes:
+
+**AsyncMemory signature:**
+```python
+async def _create_procedural_memory(
+ self,
+ messages,
+ metadata=None,
+ llm=None,
+ prompt=None
+)
+```
+
+**Memory (sync) signature:**
+```python
+def _create_procedural_memory(
+ self,
+ messages,
+ metadata=None,
+ prompt=None
+)
+```
+
+### 4. Validation Logic ✅
+The `add()` method validates `memory_type` and enforces constraints:
+
+```python
+# Only "procedural_memory" is accepted
+if memory_type is not None and memory_type != MemoryType.PROCEDURAL.value:
+ raise ValueError(
+ f"Invalid 'memory_type'. Please pass {MemoryType.PROCEDURAL.value} "
+ "to create procedural memories."
+ )
+
+# agent_id is REQUIRED for procedural memory
+if agent_id is not None and memory_type == MemoryType.PROCEDURAL.value:
+ results = await self._create_procedural_memory(
+ messages, metadata=processed_metadata, prompt=prompt, llm=llm
+ )
+ return results
+```
+
+### 5. System Prompt ✅
+A comprehensive 5,100-character system prompt exists in `mem0.configs.prompts.PROCEDURAL_MEMORY_SYSTEM_PROMPT`:
+
+**Purpose:** Records and preserves complete interaction history between human and AI agent
+
+**Structure:**
+- Overview (Global Metadata)
+ - Task Objective
+ - Progress Status
+- Sequential Agent Actions (Numbered Steps)
+ - Agent Action
+ - Action Result (Mandatory, Unmodified)
+ - Embedded Metadata (Key Findings, Navigation History, Errors, Current Context)
+
+**Key Guidelines:**
+1. Preserve every output verbatim
+2. Maintain chronological order
+3. Include exact data (URLs, element indexes, error messages, JSON responses)
+4. Output only the structured summary
+
+---
+
+## Usage Example
+
+```python
+from mem0 import AsyncMemory
+
+# Initialize memory
+memory = await AsyncMemory.from_config(config)
+
+# Create procedural memory
+messages = [
+ {"role": "user", "content": "Search for AI news"},
+ {"role": "assistant", "content": "I'll search for recent AI news..."},
+ # ... more conversation history
+]
+
+result = await memory.add(
+ messages=messages,
+ user_id="user_123",
+ agent_id="research_agent", # ⚠️ REQUIRED for procedural memory
+ memory_type="procedural_memory",
+ metadata={
+ "task": "AI news research",
+ "session_id": "session_456"
+ }
+)
+
+# Result format:
+# {
+# "results": [
+# {
+# "id": "memory_id_here",
+# "memory": "## Summary of the agent's execution history...",
+# "event": "ADD"
+# }
+# ]
+# }
+```
+
+---
+
+## Requirements & Constraints
+
+### Required Parameters
+- ✅ `agent_id`: **MUST** be provided when using `memory_type="procedural_memory"`
+- ✅ `metadata`: **MUST** be provided (cannot be None)
+- ✅ `messages`: List of conversation messages to summarize
+
+### Optional Parameters
+- `prompt`: Custom prompt to override default `PROCEDURAL_MEMORY_SYSTEM_PROMPT`
+- `llm`: Custom LangChain ChatModel (async version only)
+
+### Validation Rules
+1. `memory_type` must be exactly `"procedural_memory"` (or None)
+2. If `memory_type="procedural_memory"` is set, `agent_id` must be provided
+3. `metadata` cannot be None for procedural memories
+
+---
+
+## Implementation Details
+
+### How It Works
+1. **Validation**: Checks `memory_type` and required parameters
+2. **Prompt Construction**: Uses default or custom system prompt
+3. **LLM Summarization**: Calls LLM to generate comprehensive execution summary
+4. **Embedding**: Generates embedding for the summary
+5. **Storage**: Stores in vector database with `metadata["memory_type"] = "procedural_memory"`
+6. **Return**: Returns memory ID and summary text
+
+### Async vs Sync
+- **AsyncMemory**: Supports custom LangChain `llm` parameter
+- **Memory**: Uses internal LLM from config only
+
+---
+
+## Integration with Nexent
+
+### Current Status
+The Nexent codebase does **NOT** currently use procedural memory. The `memory_type` parameter is not passed in any `add_memory()` calls.
+
+### Recommended Integration Points
+
+1. **Agent Service** (`backend/services/agent_service.py`):
+ - Detect when agent completes a multi-step task
+ - Call `add_memory_in_levels()` with `memory_type="procedural_memory"`
+ - Pass the full conversation history as messages
+
+2. **Memory Service** (`sdk/nexent/memory/memory_service.py`):
+ - Add `memory_type` parameter to `add_memory()` and `add_memory_in_levels()`
+ - Pass through to mem0's `add()` method
+
+3. **Agent Run Info** (`sdk/nexent/core/agents/agent_model.py`):
+ - Add `memory_type` field to track if current run should create procedural memory
+
+### Example Integration
+
+```python
+# In agent_service.py, after agent completes a complex task
+if task_complexity >= threshold: # Your logic here
+ await add_memory_in_levels(
+ messages=conversation_history,
+ memory_config=memory_ctx.memory_config,
+ tenant_id=memory_ctx.tenant_id,
+ user_id=memory_ctx.user_id,
+ agent_id=memory_ctx.agent_id,
+ memory_levels=["agent", "user_agent"],
+ memory_type="procedural_memory", # ✅ NEW PARAMETER
+ metadata={
+ "task_type": "complex_research",
+ "duration_seconds": duration,
+ "steps_completed": step_count
+ }
+ )
+```
+
+---
+
+## Conclusion
+
+Procedural memory is a **fully functional feature** in mem0ai==0.1.117, **BUT it requires an optional dependency**. It provides:
+
+- ✅ Complete API support
+- ✅ Comprehensive system prompt (5,100 characters)
+- ✅ Proper validation and error handling
+- ✅ Both sync and async implementations
+- ✅ Integration with existing memory infrastructure
+- ⚠️ **REQUIRES `langchain-core` package to be installed**
+
+### The Truth About "Empty Function" Claims
+
+**The code is NOT empty.** It's a 50-line implementation that:
+1. Calls LLM to generate execution summary
+2. Creates embeddings
+3. Stores in vector database
+4. Returns proper results
+
+**However, it fails at runtime** if `langchain-core` is not installed, which is why your colleague might have thought it was a no-op.
+
+### How to Enable
+
+**Option 1: Install the dependency**
+```bash
+pip install langchain-core
+```
+
+**Option 2: Add to Nexent's dependencies**
+```toml
+# In sdk/pyproject.toml
+dependencies = [
+ # ... existing deps ...
+ "langchain-core>=0.1.0", # Required for procedural memory
+]
+```
+
+**Option 3: Make it optional with fallback**
+```python
+try:
+ result = await memory.add(..., memory_type="procedural_memory")
+except ImportError as e:
+ if "langchain-core" in str(e):
+ logger.warning("Procedural memory requires langchain-core. Using regular memory.")
+ result = await memory.add(...) # Fallback
+ else:
+ raise
+```
+
+### Final Recommendation
+
+This feature **can be integrated into Nexent**, but you must:
+1. Add `langchain-core` to dependencies, OR
+2. Implement graceful fallback when dependency is missing, OR
+3. Document it as an optional feature requiring extra installation
+
+Without addressing the dependency issue, procedural memory will fail at runtime despite having complete implementation code.
diff --git a/docker/.env.example b/docker/.env.example
index a8ec6dedb..3970efb95 100644
--- a/docker/.env.example
+++ b/docker/.env.example
@@ -22,6 +22,13 @@ SPEED_RATIO=1.3
CLIP_MODEL_PATH=/opt/models/clip-vit-base-patch32
NLTK_DATA=/opt/models/nltk_data
+# ===== Table and Structure Recognition Models =====
+
+# Table Transformer and YOLOX models for extracting tables and layout structure from PDF/DOC/DOCX files.
+# Both paths must be set to valid directories/files to enable extraction; if either is left empty, the feature is disabled.
+TABLE_TRANSFORMER_MODEL_PATH=/opt/models/table-transformer-structure-recognition
+UNSTRUCTURED_DEFAULT_MODEL_INITIALIZE_PARAMS_JSON_PATH=/opt/models/yolox/config.json
+
# Elasticsearch Service
ELASTICSEARCH_HOST=http://nexent-elasticsearch:9200
ELASTIC_PASSWORD=nexent@2025
@@ -52,11 +59,12 @@ DATA_PROCESS_SERVICE=http://nexent-data-process:5012/api
# Northbound service (port 5013) - Northbound API service
NORTHBOUND_API_SERVER=http://nexent-northbound:5013/api
-# Northbound External URL (for A2A Agent Card URLs when behind reverse proxy)
+# Northbound External URL
# Defaults to http://localhost:5013 for local development
# Set this to the public-facing URL for external A2A clients
-# Example: https://api.yourdomain.com or http://your-public-ip:5013
-# NORTHBOUND_EXTERNAL_URL=http://your-public-url:5013
+# Must include /api prefix since FastAPI uses root_path="/api"
+# Example: https://api.yourdomain.com/api or http://your-public-ip:5013/api
+# NORTHBOUND_EXTERNAL_URL=http://your-public-url:5013/api
# Postgres Config
POSTGRES_HOST=nexent-postgresql
@@ -150,16 +158,95 @@ WORKER_NAME=
WORKER_CONCURRENCY=4
# Skills Configuration
-SKILLS_PATH=/mnt/nexent/skills
+SKILLS_PATH=/mnt/nexent-data/skills
-# Telemetry and Monitoring Configuration
+# Telemetry and Monitoring Configuration (OTLP Protocol)
+# Enable OpenTelemetry monitoring for agent observability
ENABLE_TELEMETRY=false
-SERVICE_NAME=nexent-backend
-JAEGER_ENDPOINT=http://localhost:14268/api/traces
-PROMETHEUS_PORT=8000
+# Provider profile: otlp, phoenix, langfuse, langsmith, grafana, zipkin
+MONITORING_PROVIDER=otlp
+MONITORING_PROJECT_NAME=nexent
+# Browser-accessible monitoring UI URL. Leave empty to hide the frontend entry.
+MONITORING_DASHBOARD_URL=
+# Trace payload capture mode:
+# summary: bounded preview + type/size/count metadata; metrics: metadata only; full: full preview capped by max chars.
+# MAX_CHARS limits preview length; MAX_ITEMS limits dict/list preview items.
+MONITORING_TRACE_CONTENT_MODE=full
+MONITORING_TRACE_MAX_CHARS=4000
+MONITORING_TRACE_MAX_ITEMS=20
+# Service name for identifying traces in observability platforms
+OTEL_SERVICE_NAME=nexent-backend
+OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
+# Optional signal-specific endpoints. Leave empty unless the backend requires them.
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=
+OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=
+# Protocol: "http" or "grpc"
+OTEL_EXPORTER_OTLP_PROTOCOL=http
+
+# Authentication headers (format: key1=value1,key2=value2)
+# Prefer platform-specific variables when using the Collector.
+OTEL_EXPORTER_OTLP_HEADERS=
+OTEL_EXPORTER_OTLP_AUTHORIZATION=
+OTEL_EXPORTER_OTLP_X_API_KEY=
+OTEL_EXPORTER_OTLP_LANGFUSE_INGESTION_VERSION=
+OTEL_EXPORTER_OTLP_METRICS_ENABLED=true
+MONITORING_INSTRUMENT_REQUESTS=false
+# FastAPI endpoint monitoring filters. Values are comma-separated regex patterns.
+# Excluded URLs are always skipped. If included URLs is empty, all non-excluded endpoints are monitored.
+# If included URLs is non-empty, only matching endpoints are monitored.
+MONITORING_FASTAPI_INCLUDED_URLS=
+MONITORING_FASTAPI_EXCLUDED_URLS=
+MONITORING_FASTAPI_EXCLUDE_SPANS=receive,send
+
TELEMETRY_SAMPLE_RATE=1.0
-LLM_SLOW_REQUEST_THRESHOLD_SECONDS=5.0
-LLM_SLOW_TOKEN_RATE_THRESHOLD=10.0
# Market Backend Address
MARKET_BACKEND=http://60.204.251.153:8010
+
+# ===== OAuth Configuration =====
+# GitHub OAuth - get credentials from https://github.com/settings/developers
+GITHUB_OAUTH_CLIENT_ID=
+GITHUB_OAUTH_CLIENT_SECRET=
+# GDE OAuth
+GDE_URL=
+GDE_OAUTH_CLIENT_ID=
+GDE_OAUTH_CLIENT_SECRET=
+# Link App OAuth
+LINK_APP_URL=
+LINK_APP_OAUTH_CLIENT_ID=
+LINK_APP_OAUTH_CLIENT_SECRET=
+# WeChat OAuth (set ENABLE_WECHAT_OAUTH=true to enable)
+ENABLE_WECHAT_OAUTH=false
+WECHAT_OAUTH_APP_ID=
+WECHAT_OAUTH_APP_SECRET=
+# Base URL for OAuth callback (e.g., http://localhost:3000 for local dev)
+OAUTH_SSL_VERIFY=true
+OAUTH_CA_BUNDLE=
+OAUTH_CALLBACK_BASE_URL=http://localhost:3000
+
+# Asset owner role (opt-in; default false). Set true to enable ASSET_OWNER.
+ENABLE_ASSET_OWNER_ROLE=false
+
+# ===== CAS SSO Configuration =====
+CAS_ENABLED=false
+CAS_SERVER_URL=
+CAS_VALIDATE_PATH=/p3/serviceValidate
+CAS_CALLBACK_BASE_URL=http://localhost:3000
+# Supported values:
+# - disabled: disable CAS login entry and automatic CAS redirects.
+# - button: show CAS as an optional login entry.
+# - force: automatically redirect unauthenticated users to CAS login.
+CAS_LOGIN_MODE=disabled
+CAS_USER_ATTRIBUTE=
+CAS_EMAIL_ATTRIBUTE=email
+CAS_ROLE_ATTRIBUTE=role
+CAS_TENANT_ATTRIBUTE=tenant_id
+CAS_ROLE_MAP_JSON=
+CAS_SESSION_MAX_AGE_SECONDS=3600
+LOCAL_SESSION_MAX_AGE_SECONDS=3600
+CAS_RENEW_BEFORE_SECONDS=300
+CAS_RENEW_TIMEOUT_SECONDS=10
+CAS_SYNTHETIC_EMAIL_DOMAIN=cas.local
+CAS_LOGOUT_URL=/logout
+CAS_SSL_VERIFY=true
+CAS_CA_BUNDLE=
diff --git a/docker/create-su.sh b/docker/create-su.sh
old mode 100644
new mode 100755
diff --git a/docker/deploy.sh b/docker/deploy.sh
index e30e6e75a..fbf3664b5 100755
--- a/docker/deploy.sh
+++ b/docker/deploy.sh
@@ -13,16 +13,37 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
CONST_FILE="$PROJECT_ROOT/backend/consts/const.py"
DEPLOY_OPTIONS_FILE="$SCRIPT_DIR/deploy.options"
+DEPLOYMENT_COMMON="$PROJECT_ROOT/scripts/deployment/common.sh"
+ORIGINAL_ARGS=("$@")
+
+if [ -f "$DEPLOYMENT_COMMON" ]; then
+ # shellcheck source=/dev/null
+ source "$DEPLOYMENT_COMMON"
+else
+ echo "❌ Shared deployment helper not found: $DEPLOYMENT_COMMON"
+ exit 1
+fi
MODE_CHOICE_SAVED=""
VERSION_CHOICE_SAVED=""
IS_MAINLAND_SAVED=""
+ENABLE_SKILLS_SAVED="Y"
ENABLE_TERMINAL_SAVED="N"
TERMINAL_MOUNT_DIR_SAVED="${TERMINAL_MOUNT_DIR:-}"
APP_VERSION=""
cd "$SCRIPT_DIR"
+if [ ! -f ".env" ]; then
+ if [ -f ".env.example" ]; then
+ cp .env.example .env
+ echo "✅ Created docker/.env from docker/.env.example"
+ else
+ echo "❌ .env not found and .env.example is missing in $SCRIPT_DIR"
+ exit 1
+ fi
+fi
+
set -a
source .env
@@ -38,6 +59,25 @@ export COMPOSE_IGNORE_ORPHANS=True
while [[ $# -gt 0 ]]; do
case "$1" in
+ delete|delete-all|--delete-volumes|--remove-volumes|--keep-volumes)
+ echo "❌ Docker uninstall has moved to uninstall.sh. Use: bash uninstall.sh"
+ exit 1
+ ;;
+ --help|-h)
+ echo "Usage: $0 [options]"
+ echo ""
+ echo "Deploy options:"
+ echo " --components LIST"
+ echo " --port-policy development|production"
+ echo " --image-source general|mainland|local-latest"
+ echo " --use-local-config"
+ echo " --reconfigure"
+ echo " --config PATH"
+ echo " --root-dir PATH"
+ echo ""
+ echo "Uninstall: bash uninstall.sh"
+ exit 0
+ ;;
--mode)
MODE_CHOICE="$2"
shift 2
@@ -111,6 +151,49 @@ is_port_in_use() {
return 1
}
+is_nexent_container_name() {
+ local container_name="$1"
+
+ case "$container_name" in
+ nexent-*|nexent_*|supabase-*-mini)
+ return 0
+ ;;
+ *)
+ return 1
+ ;;
+ esac
+}
+
+docker_containers_using_host_port() {
+ local port="$1"
+
+ if ! command -v docker >/dev/null 2>&1; then
+ return 0
+ fi
+
+ while IFS=$'\t' read -r container_name published_ports; do
+ if [ -n "$container_name" ] && [[ "$published_ports" == *":${port}->"* ]]; then
+ echo "$container_name"
+ fi
+ done < <(docker ps --format '{{.Names}}\t{{.Ports}}' 2>/dev/null)
+}
+
+is_port_used_by_nexent_only() {
+ local port="$1"
+ local container_name
+ local found="false"
+
+ while IFS= read -r container_name; do
+ [ -n "$container_name" ] || continue
+ found="true"
+ if ! is_nexent_container_name "$container_name"; then
+ return 1
+ fi
+ done < <(docker_containers_using_host_port "$port")
+
+ [ "$found" = "true" ]
+}
+
add_port_if_new() {
# Helper to add a port to global arrays only if not already present
local port="$1"
@@ -193,6 +276,8 @@ check_ports_in_env_files() {
echo "🔍 Checking port availability defined in environment files..."
local occupied_ports=()
local occupied_sources=()
+ local ignored_nexent_ports=0
+ local free_ports=0
local idx
for idx in "${!PORTS_TO_CHECK[@]}"; do
@@ -200,14 +285,26 @@ check_ports_in_env_files() {
local source="${PORT_SOURCES[$idx]}"
if is_port_in_use "$port"; then
+ if is_port_used_by_nexent_only "$port"; then
+ ignored_nexent_ports=$((ignored_nexent_ports + 1))
+ continue
+ fi
occupied_ports+=("$port")
occupied_sources+=("$source")
echo " ❌ Port $port is already in use."
else
- echo " ✅ Port $port is free."
+ free_ports=$((free_ports + 1))
fi
done
+ if [ "$free_ports" -gt 0 ]; then
+ echo " ✅ $free_ports port(s) available."
+ fi
+
+ if [ "$ignored_nexent_ports" -gt 0 ]; then
+ echo " ↺ Ignored $ignored_nexent_ports port(s) already used by Nexent containers."
+ fi
+
if [ ${#occupied_ports[@]} -gt 0 ]; then
echo ""
echo "❌ Port conflict detected. The following ports required by Nexent are already in use:"
@@ -236,6 +333,72 @@ check_ports_in_env_files() {
echo ""
}
+check_deployment_ports() {
+ PORTS_TO_CHECK=()
+ PORT_SOURCES=()
+
+ local port
+ for port in $DEPLOYMENT_DOCKER_PORTS; do
+ add_port_if_new "$port" "deployment port policy: $DEPLOYMENT_PORT_POLICY"
+ done
+
+ if [ ${#PORTS_TO_CHECK[@]} -eq 0 ]; then
+ echo "🔍 No host ports are published by the selected deployment configuration."
+ echo ""
+ echo "--------------------------------"
+ echo ""
+ return 0
+ fi
+
+ echo "🔍 Checking port availability for selected deployment policy..."
+ local occupied_ports=()
+ local ignored_nexent_ports=0
+ local free_ports=0
+ local idx
+ for idx in "${!PORTS_TO_CHECK[@]}"; do
+ local selected_port="${PORTS_TO_CHECK[$idx]}"
+ if is_port_in_use "$selected_port"; then
+ if is_port_used_by_nexent_only "$selected_port"; then
+ ignored_nexent_ports=$((ignored_nexent_ports + 1))
+ continue
+ fi
+ occupied_ports+=("$selected_port")
+ echo " ❌ Port $selected_port is already in use."
+ else
+ free_ports=$((free_ports + 1))
+ fi
+ done
+
+ if [ "$free_ports" -gt 0 ]; then
+ echo " ✅ $free_ports port(s) available."
+ fi
+
+ if [ "$ignored_nexent_ports" -gt 0 ]; then
+ echo " ↺ Ignored $ignored_nexent_ports port(s) already used by Nexent containers."
+ fi
+
+ if [ ${#occupied_ports[@]} -gt 0 ]; then
+ echo ""
+ echo "❌ Port conflict detected for selected deployment policy:"
+ local occupied
+ for occupied in "${occupied_ports[@]}"; do
+ echo " - Port $occupied"
+ done
+ echo ""
+ local confirm_continue
+ read -p "👉 Do you still want to continue deployment even though some ports are in use? [y/N]: " confirm_continue
+ confirm_continue=$(sanitize_input "$confirm_continue")
+ if ! [[ "$confirm_continue" =~ ^[Yy]$ ]]; then
+ echo "🚫 Deployment aborted due to port conflicts."
+ exit 1
+ fi
+ fi
+
+ echo ""
+ echo "--------------------------------"
+ echo ""
+}
+
trim_quotes() {
local value="$1"
value="${value%$'\r'}"
@@ -266,12 +429,22 @@ persist_deploy_options() {
echo "MODE_CHOICE=\"${MODE_CHOICE_SAVED}\""
echo "VERSION_CHOICE=\"${VERSION_CHOICE_SAVED}\""
echo "IS_MAINLAND=\"${IS_MAINLAND_SAVED}\""
+ echo "ENABLE_SKILLS=\"${ENABLE_SKILLS_SAVED}\""
echo "ENABLE_TERMINAL=\"${ENABLE_TERMINAL_SAVED}\""
echo "TERMINAL_MOUNT_DIR=\"${TERMINAL_MOUNT_DIR_SAVED}\""
} > "$DEPLOY_OPTIONS_FILE"
}
generate_minio_ak_sk() {
+ if [ -n "${MINIO_ACCESS_KEY:-}" ] && [ -n "${MINIO_SECRET_KEY:-}" ]; then
+ echo " Reusing existing MinIO access keys from docker/.env"
+ export MINIO_ACCESS_KEY
+ export MINIO_SECRET_KEY
+ update_env_var "MINIO_ACCESS_KEY" "$MINIO_ACCESS_KEY"
+ update_env_var "MINIO_SECRET_KEY" "$MINIO_SECRET_KEY"
+ return 0
+ fi
+
echo "🔑 Generating MinIO keys..."
if [ "$(uname -s | tr '[:upper:]' '[:lower:]')" = "mingw" ] || [ "$(uname -s | tr '[:upper:]' '[:lower:]')" = "msys" ]; then
@@ -365,7 +538,7 @@ generate_elasticsearch_api_key() {
generate_env_for_infrastructure() {
# Function to generate complete environment file for infrastructure mode using generate_env.sh
- echo "🔑 Generating complete environment file in root directory..."
+ echo "🔑 Updating docker/.env for infrastructure mode..."
echo " 🚀 Running generate_env.sh..."
# Check if generate_env.sh exists
@@ -381,16 +554,14 @@ generate_env_for_infrastructure() {
export DEPLOYMENT_VERSION
if ./generate_env.sh; then
- echo " ✅ Environment file generated successfully for infrastructure mode!"
- # Source the generated .env file to make variables available
- if [ -f "../.env" ]; then
- echo " ⏏️ Sourcing generated root .env file..."
+ echo " ✅ docker/.env updated successfully for infrastructure mode!"
+ if [ -f ".env" ]; then
set -a
- source ../.env
+ source .env
set +a
- echo " ✅ Environment variables loaded from ../.env"
+ echo " ✅ Environment variables loaded from docker/.env"
else
- echo " ⚠️ Warning: ../.env file not found after generation"
+ echo " ⚠️ Warning: docker/.env file not found after generation"
return 1
fi
else
@@ -407,7 +578,7 @@ get_compose_version() {
# Function to get the version of docker compose
if command -v docker &> /dev/null; then
version_output=$(docker compose version 2>/dev/null)
- if [[ $version_output =~ (v[0-9]+\.[0-9]+\.[0-9]+) ]]; then
+ if [[ $version_output =~ v([0-9]+\.[0-9]+\.[0-9]+) ]]; then
echo "v2 ${BASH_REMATCH[1]}"
return 0
fi
@@ -430,7 +601,21 @@ disable_dashboard() {
update_env_var "DISABLE_CELERY_FLOWER" "true"
}
+sync_monitoring_env_vars() {
+ update_env_var "ENABLE_TELEMETRY" "$(deployment_monitoring_enabled)"
+ update_env_var "MONITORING_PROVIDER" "$DEPLOYMENT_MONITORING_PROVIDER"
+ update_env_var "MONITORING_DASHBOARD_URL" "$(deployment_monitoring_dashboard_url docker)"
+}
+
pull_mcp_image() {
+ if [ "$DEPLOYMENT_IMAGE_SOURCE" = "local-latest" ]; then
+ echo "🔄 Skipping MCP image pull because image source is local-latest."
+ echo ""
+ echo "--------------------------------"
+ echo ""
+ return 0
+ fi
+
echo "🔄 Checking MCP Docker image..."
# Get MCP image name from environment or use default
@@ -538,9 +723,6 @@ clean() {
if [ -f ".env.bak" ]; then
rm .env.bak
fi
- if [ -f "../.env.bak" ]; then
- rm ../.env.bak
- fi
}
update_env_var() {
@@ -614,6 +796,15 @@ prepare_directory_and_data() {
create_dir_with_permission "$NEXENT_USER_DIR" 775
echo " 🖥️ Nexent user workspace: $NEXENT_USER_DIR"
+ # Copy official-skills-zip folder to /mnt/nexent
+ if [ -d "official-skills-zip" ]; then
+ cp -rn official-skills-zip "$NEXENT_USER_DIR/"
+ chmod -R 775 "$NEXENT_USER_DIR/official-skills-zip"
+ echo " 📦 Official skills copied to $NEXENT_USER_DIR/official-skills-zip"
+ else
+ echo " ⚠️ official-skills-zip directory not found, skipping skills copy"
+ fi
+
# Export for docker-compose
export NEXENT_USER_DIR
@@ -624,35 +815,69 @@ prepare_directory_and_data() {
deploy_core_services() {
# Function to deploy core services
- echo "👀 Starting core services..."
- if ! ${docker_compose_command} -p nexent -f "docker-compose${COMPOSE_FILE_SUFFIX}" up -d nexent-config nexent-runtime nexent-mcp nexent-northbound nexent-web nexent-data-process; then
+ local core_services=()
+ local service
+ for service in $DEPLOYMENT_SELECTED_DOCKER_SERVICES; do
+ case "$service" in
+ nexent-config|nexent-runtime|nexent-mcp|nexent-northbound|nexent-web|nexent-data-process)
+ core_services+=("$service")
+ ;;
+ esac
+ done
+
+ if [ ${#core_services[@]} -eq 0 ]; then
+ echo "👀 No core services selected, skipping core service startup."
+ return 0
+ fi
+
+ echo "👀 Starting core services: ${core_services[*]}"
+ if ! ${docker_compose_command} -p nexent -f "docker-compose${COMPOSE_FILE_SUFFIX}" up -d "${core_services[@]}"; then
echo " ❌ ERROR Failed to start core services"
return 1
fi
}
+stop_unselected_data_process_service() {
+ deployment_csv_contains "$DEPLOYMENT_COMPONENTS" "data-process" && return 0
+
+ local compose_file="docker-compose${COMPOSE_FILE_SUFFIX}"
+ [ -f "$compose_file" ] || return 0
+
+ echo "data-process is not selected; stopping existing Docker container if present..."
+ ${docker_compose_command} -p nexent -f "$compose_file" stop nexent-data-process >/dev/null 2>&1 || true
+ ${docker_compose_command} -p nexent -f "$compose_file" rm -f nexent-data-process >/dev/null 2>&1 || true
+}
+
deploy_infrastructure() {
# Start infrastructure services (basic services only)
echo "🔧 Starting infrastructure services..."
- INFRA_SERVICES="nexent-elasticsearch nexent-postgresql nexent-minio redis"
+ INFRA_SERVICES=""
+
+ if deployment_csv_contains "$DEPLOYMENT_COMPONENTS" "infrastructure"; then
+ INFRA_SERVICES="nexent-elasticsearch nexent-postgresql nexent-minio redis"
+ fi
# Add openssh-server if Terminal tool container is enabled
- if [ "$ENABLE_TERMINAL_TOOL_CONTAINER" = "true" ]; then
+ if deployment_csv_contains "$DEPLOYMENT_COMPONENTS" "terminal"; then
INFRA_SERVICES="$INFRA_SERVICES nexent-openssh-server"
echo "🔧 Terminal tool container enabled - openssh-server will be included in infrastructure"
fi
- if ! ${docker_compose_command} -p nexent -f "docker-compose${COMPOSE_FILE_SUFFIX}" up -d $INFRA_SERVICES; then
- echo " ❌ ERROR Failed to start infrastructure services"
- return 1
+ if [ -n "$INFRA_SERVICES" ]; then
+ if ! ${docker_compose_command} -p nexent -f "docker-compose${COMPOSE_FILE_SUFFIX}" up -d $INFRA_SERVICES; then
+ echo " ❌ ERROR Failed to start infrastructure services"
+ return 1
+ fi
+ else
+ echo "🔧 No infrastructure services selected, skipping infrastructure startup."
fi
- if [ "$ENABLE_TERMINAL_TOOL_CONTAINER" = "true" ]; then
+ if deployment_csv_contains "$DEPLOYMENT_COMPONENTS" "terminal"; then
echo "🔧 Terminal tool container (openssh-server) is now available for AI agents"
fi
- # Deploy Supabase services based on DEPLOYMENT_VERSION
- if [ "$DEPLOYMENT_VERSION" = "full" ]; then
+ # Deploy Supabase services based on selected components
+ if deployment_csv_contains "$DEPLOYMENT_COMPONENTS" "supabase"; then
echo ""
echo "🔧 Starting Supabase services..."
# Check if the supabase compose file exists
@@ -675,6 +900,105 @@ deploy_infrastructure() {
echo " ✅ Infrastructure services started successfully"
}
+deploy_monitoring() {
+ deployment_csv_contains "$DEPLOYMENT_COMPONENTS" "monitoring" || return 0
+
+ if [ ! -f "docker-compose-monitoring.yml" ]; then
+ echo " ❌ ERROR Monitoring compose file not found: docker-compose-monitoring.yml"
+ return 1
+ fi
+
+ local profile_args=()
+ case "$DEPLOYMENT_MONITORING_PROVIDER" in
+ phoenix|grafana|zipkin|langfuse)
+ profile_args+=(--profile "$DEPLOYMENT_MONITORING_PROVIDER")
+ ;;
+ esac
+
+ echo "🔭 Starting monitoring services..."
+ if ! ${docker_compose_command} "${profile_args[@]}" -f "docker-compose-monitoring.yml" up -d; then
+ echo " ❌ ERROR Failed to start monitoring services"
+ return 1
+ fi
+}
+
+configure_root_dir_from_env() {
+ if [ -n "$ROOT_DIR_PARAM" ]; then
+ ROOT_DIR="$ROOT_DIR_PARAM"
+ echo " 📁 Using ROOT_DIR from parameter: $ROOT_DIR"
+ update_env_var "ROOT_DIR" "$ROOT_DIR"
+ elif grep -q "^ROOT_DIR=" .env; then
+ ROOT_DIR="$(grep "^ROOT_DIR=" .env | cut -d'=' -f2 | sed 's/^"//;s/"$//')"
+ echo " 📁 Use existing ROOT_DIR path: $ROOT_DIR"
+ else
+ local default_root_dir="$HOME/nexent-data"
+ if [ -t 0 ]; then
+ local user_root_dir
+ read -p " 📁 Enter ROOT_DIR path (default: $default_root_dir): " user_root_dir
+ ROOT_DIR="${user_root_dir:-$default_root_dir}"
+ else
+ ROOT_DIR="$default_root_dir"
+ fi
+ update_env_var "ROOT_DIR" "$ROOT_DIR"
+ fi
+ export ROOT_DIR
+ echo ""
+ echo "--------------------------------"
+ echo ""
+}
+
+apply_deployment_common_config() {
+ deployment_prepare_config "${ORIGINAL_ARGS[@]}" || return 1
+
+ if deployment_csv_contains "$DEPLOYMENT_COMPONENTS" "supabase"; then
+ export DEPLOYMENT_VERSION="full"
+ else
+ export DEPLOYMENT_VERSION="speed"
+ fi
+ update_env_var "DEPLOYMENT_VERSION" "$DEPLOYMENT_VERSION"
+
+ if [ "$DEPLOYMENT_PORT_POLICY" = "production" ]; then
+ export DEPLOYMENT_MODE="production"
+ export COMPOSE_FILE_SUFFIX=".prod.yml"
+ disable_dashboard
+ elif [ "$DEPLOYMENT_COMPONENTS" = "infrastructure" ]; then
+ export DEPLOYMENT_MODE="infrastructure"
+ export COMPOSE_FILE_SUFFIX=".yml"
+ else
+ export DEPLOYMENT_MODE="development"
+ export COMPOSE_FILE_SUFFIX=".yml"
+ fi
+
+ if deployment_csv_contains "$DEPLOYMENT_COMPONENTS" "terminal"; then
+ ENABLE_TERMINAL_SAVED="Y"
+ export ENABLE_TERMINAL_TOOL_CONTAINER="true"
+ export COMPOSE_PROFILES="${COMPOSE_PROFILES:+$COMPOSE_PROFILES,}terminal"
+ else
+ ENABLE_TERMINAL_SAVED="N"
+ export ENABLE_TERMINAL_TOOL_CONTAINER="false"
+ fi
+
+ export APP_VERSION="$DEPLOYMENT_APP_VERSION"
+ case "$DEPLOYMENT_REGISTRY_PROFILE" in
+ mainland)
+ IS_MAINLAND_SAVED="Y"
+ source .env.mainland
+ ;;
+ general|local-latest)
+ IS_MAINLAND_SAVED="N"
+ source .env.general
+ ;;
+ esac
+
+ deployment_apply_image_source
+ deployment_render_docker_env "$SCRIPT_DIR/.env.generated"
+ set -a
+ source "$SCRIPT_DIR/.env.generated"
+ set +a
+ sync_monitoring_env_vars
+ deployment_print_summary docker
+}
+
select_deployment_version() {
# Function to select deployment version
echo "🚀 Please select deployment version:"
@@ -867,7 +1191,7 @@ select_terminal_tool() {
check_super_admin_user_exists() {
# Check if super admin user exists in Supabase
- local email="suadmin@nexent.com"
+ local email="${1:-suadmin@nexent.com}"
local curl_container="nexent-config"
# Determine which container to use for curl command
@@ -1003,8 +1327,10 @@ create_default_super_admin_user() {
# Execute the script with password as argument
if bash "$script_path" "$password"; then
+ unset password
return 0
else
+ unset password
return 1
fi
}
@@ -1048,14 +1374,15 @@ main_deploy() {
fi
echo "🌐 App version: $APP_VERSION"
- # Check all relevant ports from environment files before starting deployment
- check_ports_in_env_files
+ # Select deployment components, port policy and image source via shared config.
+ apply_deployment_common_config || { echo "❌ Deployment configuration failed"; exit 1; }
- # Select deployment version, mode and image source
- select_deployment_version || { echo "❌ Deployment version selection failed"; exit 1; }
- select_deployment_mode || { echo "❌ Deployment mode selection failed"; exit 1; }
- select_terminal_tool || { echo "❌ Terminal tool container configuration failed"; exit 1; }
- choose_image_env || { echo "❌ Image environment setup failed"; exit 1; }
+ deployment_persist_local_config
+
+ # Check only the ports published by the selected deployment configuration.
+ check_deployment_ports
+
+ configure_root_dir_from_env || { echo "❌ ROOT_DIR configuration failed"; exit 1; }
# Set NEXENT_MCP_DOCKER_IMAGE in .env file
if [ -n "${NEXENT_MCP_DOCKER_IMAGE:-}" ]; then
@@ -1076,6 +1403,10 @@ main_deploy() {
# Deploy infrastructure services
deploy_infrastructure || { echo "❌ Infrastructure deployment failed"; exit 1; }
+ deploy_monitoring || { echo "❌ Monitoring deployment failed"; exit 1; }
+
+ stop_unselected_data_process_service
+
# Generate Elasticsearch API key
generate_elasticsearch_api_key || { echo "❌ Elasticsearch API key generation failed"; exit 1; }
@@ -1094,13 +1425,14 @@ main_deploy() {
echo "🎉 Infrastructure deployment completed successfully!"
echo " You can now start the core services manually using dev containers"
- echo " Environment file available at: $(cd .. && pwd)/.env"
- echo "💡 Use 'source .env' to load environment variables in your development shell"
+ echo " Environment file available at: $SCRIPT_DIR/.env"
+ echo "💡 Use 'source docker/.env' from the project root to load environment variables"
# Pull MCP image for later use
pull_mcp_image
persist_deploy_options
+ deployment_persist_local_config
return 0
fi
@@ -1118,6 +1450,7 @@ main_deploy() {
fi
persist_deploy_options
+ deployment_persist_local_config
# Pull MCP image for later use
pull_mcp_image
@@ -1142,7 +1475,7 @@ docker_compose_command=""
case $version_type in
"v1")
echo "Detected Docker Compose V1, version: $version_number"
- # The version v1.28.0 is the minimum requirement in Docker Compose v1 that explicitly supports interpolation syntax with default values like ${VAR:-default}
+ # The version 1.28.0 is the minimum requirement in Docker Compose v1 for default interpolation syntax.
if [[ $version_number < "1.28.0" ]]; then
echo "Warning: V1 version is too old, consider upgrading to V2"
exit 1
diff --git a/docker/docker-compose-monitoring.yml b/docker/docker-compose-monitoring.yml
index fb4aa5eaf..976a57c97 100644
--- a/docker/docker-compose-monitoring.yml
+++ b/docker/docker-compose-monitoring.yml
@@ -1,88 +1,268 @@
+name: monitor
+
services:
- # Jaeger - Distributed Tracing
- jaeger:
- image: jaegertracing/all-in-one:1.52
- container_name: nexent-jaeger
- ports:
- - "16686:16686" # Jaeger UI
- - "14268:14268" # Jaeger collector HTTP
- - "14250:14250" # Jaeger collector gRPC
- - "6831:6831/udp" # Agent UDP
- - "6832:6832/udp" # Agent UDP
+ otel-collector:
+ image: otel/opentelemetry-collector-contrib:${OTEL_COLLECTOR_VERSION:-0.151.0}
+ container_name: nexent-otel-collector
+ command: ["--config=/etc/otel-collector-config.yml"]
environment:
- - COLLECTOR_OTLP_ENABLED=true
- - COLLECTOR_ZIPKIN_HOST_PORT=:9411
+ LANGFUSE_OTLP_AUTH_HEADER: ${LANGFUSE_OTLP_AUTH_HEADER:-}
+ LANGSMITH_API_KEY: ${LANGSMITH_API_KEY:-}
+ LANGSMITH_PROJECT: ${LANGSMITH_PROJECT:-nexent}
+ LANGSMITH_OTLP_TRACES_ENDPOINT: ${LANGSMITH_OTLP_TRACES_ENDPOINT:-https://api.smith.langchain.com/otel/v1/traces}
+ volumes:
+ - ${OTEL_COLLECTOR_CONFIG_FILE:-./monitoring/otel-collector-config.yml}:/etc/otel-collector-config.yml
+ ports:
+ - "${OTEL_COLLECTOR_GRPC_PORT:-4317}:4317"
+ - "${OTEL_COLLECTOR_HTTP_PORT:-4318}:4318"
networks:
- - nexent-network
+ - nexent
restart: unless-stopped
- volumes:
- - jaeger-data:/tmp
- # Prometheus - Metrics Collection
- prometheus:
- image: prom/prometheus:v2.48.0
- container_name: nexent-prometheus
+ phoenix:
+ image: arizephoenix/phoenix:${PHOENIX_VERSION:-15}
+ container_name: nexent-phoenix
+ profiles: ["phoenix"]
+ environment:
+ PHOENIX_WORKING_DIR: /mnt/data
+ volumes:
+ - phoenix-data:/mnt/data
ports:
- - "9090:9090"
- command:
- - '--config.file=/etc/prometheus/prometheus.yml'
- - '--storage.tsdb.path=/prometheus'
- - '--web.console.libraries=/etc/prometheus/console_libraries'
- - '--web.console.templates=/etc/prometheus/consoles'
- - '--storage.tsdb.retention.time=15d'
- - '--web.enable-lifecycle'
- - '--web.enable-admin-api'
+ - "${PHOENIX_PORT:-6006}:6006"
+ - "${PHOENIX_GRPC_HOST_PORT:-4319}:4317"
+ networks:
+ - nexent
+ restart: unless-stopped
+
+ tempo:
+ image: grafana/tempo:${TEMPO_VERSION:-2.10.5}
+ container_name: nexent-tempo
+ profiles: ["grafana"]
+ command: ["--config.file=/etc/tempo.yml"]
volumes:
- - ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml
- - prometheus-data:/prometheus
+ - ./monitoring/tempo.yml:/etc/tempo.yml:ro
+ - tempo-data:/var/tempo
+ ports:
+ - "${TEMPO_PORT:-3200}:3200"
networks:
- - nexent-network
+ - nexent
restart: unless-stopped
- # Grafana - Metrics Visualization
grafana:
- image: grafana/grafana:10.2.0
+ image: grafana/grafana:${GRAFANA_VERSION:-12.4}
container_name: nexent-grafana
- ports:
- - "3005:3000"
+ profiles: ["grafana"]
environment:
- - GF_SECURITY_ADMIN_PASSWORD=admin
- - GF_USERS_ALLOW_SIGN_UP=false
- - GF_INSTALL_PLUGINS=grafana-piechart-panel
+ GF_SECURITY_ADMIN_USER: ${GRAFANA_ADMIN_USER:-admin}
+ GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_ADMIN_PASSWORD:-nexent-grafana-admin}
+ GF_USERS_ALLOW_SIGN_UP: "false"
+ GF_USERS_DEFAULT_LANGUAGE: ${GRAFANA_DEFAULT_LANGUAGE:-zh-Hans}
+ GF_PLUGINS_PREINSTALL_AUTO_UPDATE: "false"
volumes:
- grafana-data:/var/lib/grafana
- - ./monitoring/grafana/provisioning:/etc/grafana/provisioning
- - ./monitoring/grafana/dashboards:/var/lib/grafana/dashboards
+ - ./monitoring/grafana/provisioning:/etc/grafana/provisioning:ro
+ - ./monitoring/grafana/dashboards:/var/lib/grafana/dashboards:ro
+ ports:
+ - "${GRAFANA_PORT:-3002}:3000"
+ depends_on:
+ - tempo
networks:
- - nexent-network
+ - nexent
restart: unless-stopped
- depends_on:
- - prometheus
- # OpenTelemetry Collector (Optional - for advanced setups)
- otel-collector:
- image: otel/opentelemetry-collector-contrib:0.89.0
- container_name: nexent-otel-collector
- command: ["--config=/etc/otel-collector-config.yml"]
+ zipkin:
+ image: openzipkin/zipkin:${ZIPKIN_VERSION:-latest}
+ container_name: nexent-zipkin
+ profiles: ["zipkin"]
+ ports:
+ - "${ZIPKIN_PORT:-9411}:9411"
+ networks:
+ - nexent
+ restart: unless-stopped
+
+ langfuse-worker:
+ image: docker.io/langfuse/langfuse-worker:${LANGFUSE_VERSION:-3}
+ container_name: nexent-langfuse-worker
+ profiles: ["langfuse"]
+ restart: unless-stopped
+ depends_on: &langfuse-depends-on
+ langfuse-postgres:
+ condition: service_healthy
+ langfuse-minio:
+ condition: service_healthy
+ langfuse-redis:
+ condition: service_healthy
+ langfuse-clickhouse:
+ condition: service_healthy
+ environment: &langfuse-env
+ NEXTAUTH_URL: ${LANGFUSE_NEXTAUTH_URL:-http://localhost:3001}
+ NEXTAUTH_SECRET: ${LANGFUSE_NEXTAUTH_SECRET:-nexent-langfuse-secret}
+ DATABASE_URL: postgresql://${LANGFUSE_POSTGRES_USER:-postgres}:${LANGFUSE_POSTGRES_PASSWORD:-postgres}@langfuse-postgres:5432/${LANGFUSE_POSTGRES_DB:-postgres}
+ SALT: ${LANGFUSE_SALT:-nexent-langfuse-salt}
+ ENCRYPTION_KEY: ${LANGFUSE_ENCRYPTION_KEY:-0000000000000000000000000000000000000000000000000000000000000000}
+ TELEMETRY_ENABLED: ${LANGFUSE_TELEMETRY_ENABLED:-false}
+ LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES: ${LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES:-false}
+ CLICKHOUSE_MIGRATION_URL: clickhouse://langfuse-clickhouse:9000
+ CLICKHOUSE_URL: http://langfuse-clickhouse:8123
+ CLICKHOUSE_USER: ${LANGFUSE_CLICKHOUSE_USER:-clickhouse}
+ CLICKHOUSE_PASSWORD: ${LANGFUSE_CLICKHOUSE_PASSWORD:-clickhouse}
+ CLICKHOUSE_CLUSTER_ENABLED: ${LANGFUSE_CLICKHOUSE_CLUSTER_ENABLED:-false}
+ REDIS_HOST: langfuse-redis
+ REDIS_PORT: 6379
+ REDIS_AUTH: ${LANGFUSE_REDIS_AUTH:-myredissecret}
+ REDIS_TLS_ENABLED: "false"
+ LANGFUSE_USE_AZURE_BLOB: "false"
+ LANGFUSE_USE_OCI_NATIVE_OBJECT_STORAGE: "false"
+ LANGFUSE_S3_EVENT_UPLOAD_BUCKET: ${LANGFUSE_S3_BUCKET:-langfuse}
+ LANGFUSE_S3_EVENT_UPLOAD_REGION: auto
+ LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID: ${LANGFUSE_MINIO_ROOT_USER:-minio}
+ LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY: ${LANGFUSE_MINIO_ROOT_PASSWORD:-miniosecret}
+ LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT: http://langfuse-minio:9000
+ LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE: "true"
+ LANGFUSE_S3_EVENT_UPLOAD_PREFIX: events/
+ LANGFUSE_S3_MEDIA_UPLOAD_BUCKET: ${LANGFUSE_S3_BUCKET:-langfuse}
+ LANGFUSE_S3_MEDIA_UPLOAD_REGION: auto
+ LANGFUSE_S3_MEDIA_UPLOAD_ACCESS_KEY_ID: ${LANGFUSE_MINIO_ROOT_USER:-minio}
+ LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY: ${LANGFUSE_MINIO_ROOT_PASSWORD:-miniosecret}
+ LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT: http://langfuse-minio:9000
+ LANGFUSE_S3_MEDIA_UPLOAD_FORCE_PATH_STYLE: "true"
+ LANGFUSE_S3_MEDIA_UPLOAD_PREFIX: media/
+ LANGFUSE_S3_BATCH_EXPORT_ENABLED: "false"
+ LANGFUSE_S3_BATCH_EXPORT_BUCKET: ${LANGFUSE_S3_BUCKET:-langfuse}
+ LANGFUSE_S3_BATCH_EXPORT_REGION: auto
+ LANGFUSE_S3_BATCH_EXPORT_ENDPOINT: http://langfuse-minio:9000
+ LANGFUSE_S3_BATCH_EXPORT_EXTERNAL_ENDPOINT: http://localhost:${LANGFUSE_MINIO_API_PORT:-9092}
+ LANGFUSE_S3_BATCH_EXPORT_ACCESS_KEY_ID: ${LANGFUSE_MINIO_ROOT_USER:-minio}
+ LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY: ${LANGFUSE_MINIO_ROOT_PASSWORD:-miniosecret}
+ LANGFUSE_S3_BATCH_EXPORT_FORCE_PATH_STYLE: "true"
+ networks:
+ - nexent
+
+ langfuse-web:
+ image: docker.io/langfuse/langfuse:${LANGFUSE_VERSION:-3}
+ container_name: nexent-langfuse-web
+ profiles: ["langfuse"]
+ restart: unless-stopped
+ depends_on: *langfuse-depends-on
+ environment:
+ <<: *langfuse-env
+ LANGFUSE_INIT_ORG_ID: ${LANGFUSE_INIT_ORG_ID:-nexent}
+ LANGFUSE_INIT_ORG_NAME: ${LANGFUSE_INIT_ORG_NAME:-Nexent}
+ LANGFUSE_INIT_PROJECT_ID: ${LANGFUSE_INIT_PROJECT_ID:-nexent-local}
+ LANGFUSE_INIT_PROJECT_NAME: ${LANGFUSE_INIT_PROJECT_NAME:-Nexent Local}
+ LANGFUSE_INIT_PROJECT_PUBLIC_KEY: ${LANGFUSE_INIT_PROJECT_PUBLIC_KEY:-pk-lf-nexent-local}
+ LANGFUSE_INIT_PROJECT_SECRET_KEY: ${LANGFUSE_INIT_PROJECT_SECRET_KEY:-sk-lf-nexent-local}
+ LANGFUSE_INIT_USER_EMAIL: ${LANGFUSE_INIT_USER_EMAIL:-admin@nexent.local}
+ LANGFUSE_INIT_USER_NAME: ${LANGFUSE_INIT_USER_NAME:-Nexent Admin}
+ LANGFUSE_INIT_USER_PASSWORD: ${LANGFUSE_INIT_USER_PASSWORD:-nexent-langfuse-admin}
+ ports:
+ - "${LANGFUSE_PORT:-3001}:3000"
+ networks:
+ - nexent
+
+ langfuse-clickhouse:
+ image: docker.io/clickhouse/clickhouse-server:${LANGFUSE_CLICKHOUSE_VERSION:-26.3-alpine}
+ container_name: nexent-langfuse-clickhouse
+ profiles: ["langfuse"]
+ restart: unless-stopped
+ user: "101:101"
+ environment:
+ CLICKHOUSE_DB: default
+ CLICKHOUSE_USER: ${LANGFUSE_CLICKHOUSE_USER:-clickhouse}
+ CLICKHOUSE_PASSWORD: ${LANGFUSE_CLICKHOUSE_PASSWORD:-clickhouse}
volumes:
- - ./monitoring/otel-collector-config.yml:/etc/otel-collector-config.yml
+ - langfuse-clickhouse-data:/var/lib/clickhouse
+ - langfuse-clickhouse-logs:/var/log/clickhouse-server
ports:
- - "4317:4317" # OTLP gRPC receiver
- - "4318:4318" # OTLP HTTP receiver
- - "8888:8888" # Prometheus metrics exposed by the collector
- - "8889:8889" # Prometheus exporter metrics
- depends_on:
- - jaeger
- - prometheus
+ - "127.0.0.1:${LANGFUSE_CLICKHOUSE_HTTP_PORT:-8124}:8123"
+ - "127.0.0.1:${LANGFUSE_CLICKHOUSE_NATIVE_PORT:-9002}:9000"
+ healthcheck:
+ test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://127.0.0.1:8123/ping || exit 1"]
+ interval: 5s
+ timeout: 5s
+ retries: 10
+ start_period: 1s
networks:
- - nexent-network
+ - nexent
+
+ langfuse-minio:
+ image: docker.io/minio/minio:${LANGFUSE_MINIO_VERSION:-RELEASE.2023-12-20T01-00-02Z}
+ container_name: nexent-langfuse-minio
+ profiles: ["langfuse"]
restart: unless-stopped
+ entrypoint: sh
+ command: -c 'mkdir -p /data/${LANGFUSE_S3_BUCKET:-langfuse} && minio server --address ":9000" --console-address ":9001" /data'
+ environment:
+ MINIO_ROOT_USER: ${LANGFUSE_MINIO_ROOT_USER:-minio}
+ MINIO_ROOT_PASSWORD: ${LANGFUSE_MINIO_ROOT_PASSWORD:-miniosecret}
+ ports:
+ - "${LANGFUSE_MINIO_API_PORT:-9092}:9000"
+ - "127.0.0.1:${LANGFUSE_MINIO_CONSOLE_PORT:-9093}:9001"
+ volumes:
+ - langfuse-minio-data:/data
+ healthcheck:
+ test: ["CMD", "mc", "ready", "local"]
+ interval: 1s
+ timeout: 5s
+ retries: 5
+ start_period: 1s
+ networks:
+ - nexent
-volumes:
- jaeger-data:
- prometheus-data:
- grafana-data:
+ langfuse-redis:
+ image: docker.io/redis:${LANGFUSE_REDIS_VERSION:-alpine}
+ container_name: nexent-langfuse-redis
+ profiles: ["langfuse"]
+ restart: unless-stopped
+ command: >
+ --requirepass ${LANGFUSE_REDIS_AUTH:-myredissecret}
+ --maxmemory-policy noeviction
+ ports:
+ - "127.0.0.1:${LANGFUSE_REDIS_PORT:-6380}:6379"
+ volumes:
+ - langfuse-redis-data:/data
+ healthcheck:
+ test: ["CMD-SHELL", "redis-cli -a ${LANGFUSE_REDIS_AUTH:-myredissecret} ping | grep PONG"]
+ interval: 3s
+ timeout: 10s
+ retries: 10
+ networks:
+ - nexent
+
+ langfuse-postgres:
+ image: docker.io/postgres:${LANGFUSE_POSTGRES_VERSION:-15-alpine}
+ container_name: nexent-langfuse-postgres
+ profiles: ["langfuse"]
+ restart: unless-stopped
+ environment:
+ POSTGRES_USER: ${LANGFUSE_POSTGRES_USER:-postgres}
+ POSTGRES_PASSWORD: ${LANGFUSE_POSTGRES_PASSWORD:-postgres}
+ POSTGRES_DB: ${LANGFUSE_POSTGRES_DB:-postgres}
+ TZ: UTC
+ PGTZ: UTC
+ ports:
+ - "127.0.0.1:${LANGFUSE_POSTGRES_PORT:-5440}:5432"
+ volumes:
+ - langfuse-postgres-data:/var/lib/postgresql/data
+ healthcheck:
+ test: ["CMD-SHELL", "pg_isready -U ${LANGFUSE_POSTGRES_USER:-postgres}"]
+ interval: 3s
+ timeout: 3s
+ retries: 10
+ networks:
+ - nexent
networks:
- nexent-network:
+ nexent:
+ name: nexent_network
external: true
+
+volumes:
+ phoenix-data:
+ langfuse-postgres-data:
+ langfuse-clickhouse-data:
+ langfuse-clickhouse-logs:
+ langfuse-minio-data:
+ langfuse-redis-data:
+ grafana-data:
+ tempo-data:
diff --git a/docker/docker-compose-supabase.prod.yml b/docker/docker-compose-supabase.prod.yml
index 234185b0b..6ad7ac134 100644
--- a/docker/docker-compose-supabase.prod.yml
+++ b/docker/docker-compose-supabase.prod.yml
@@ -142,4 +142,5 @@ volumes:
networks:
nexent:
- driver: bridge
\ No newline at end of file
+ name: nexent_network
+ driver: bridge
diff --git a/docker/docker-compose-supabase.yml b/docker/docker-compose-supabase.yml
index 21a4e6958..b781b4444 100644
--- a/docker/docker-compose-supabase.yml
+++ b/docker/docker-compose-supabase.yml
@@ -147,4 +147,5 @@ volumes:
networks:
nexent:
- driver: bridge
\ No newline at end of file
+ name: nexent_network
+ driver: bridge
diff --git a/docker/docker-compose.dev.yml b/docker/docker-compose.dev.yml
index cfb20f6e8..f23e4210c 100644
--- a/docker/docker-compose.dev.yml
+++ b/docker/docker-compose.dev.yml
@@ -95,4 +95,5 @@ services:
networks:
nexent:
+ name: nexent_network
driver: bridge
diff --git a/docker/docker-compose.prod.yml b/docker/docker-compose.prod.yml
index 934fe8b2f..29bd41d9f 100644
--- a/docker/docker-compose.prod.yml
+++ b/docker/docker-compose.prod.yml
@@ -75,6 +75,7 @@ services:
restart: always
volumes:
- ${NEXENT_USER_DIR:-$HOME/nexent}:/mnt/nexent
+ - ${ROOT_DIR}/skills:/mnt/nexent-data/skills
- ${ROOT_DIR}/openssh-server/ssh-keys:/opt/ssh-keys:ro
- ${ROOT_DIR}/scripts/sync_user_supabase2pg.py:/opt/sync_user_supabase2pg.py:ro
- /var/run/docker.sock:/var/run/docker.sock:ro # Docker socket for MCP container management
@@ -103,6 +104,7 @@ services:
restart: always
volumes:
- ${NEXENT_USER_DIR:-$HOME/nexent}:/mnt/nexent
+ - ${ROOT_DIR}/skills:/mnt/nexent-data/skills
- ${ROOT_DIR}/openssh-server/ssh-keys:/opt/ssh-keys:ro
environment:
<<: [*minio-vars, *es-vars]
@@ -155,6 +157,7 @@ services:
restart: always
volumes:
- ${NEXENT_USER_DIR:-$HOME/nexent}:/mnt/nexent
+ - ${ROOT_DIR}/skills:/mnt/nexent-data/skills
- ${ROOT_DIR}/openssh-server/ssh-keys:/opt/ssh-keys:ro
environment:
<<: [*minio-vars, *es-vars]
@@ -300,6 +303,7 @@ services:
networks:
nexent:
+ name: nexent_network
driver: bridge
volumes:
diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml
index 89088f2c3..fd3851ab4 100644
--- a/docker/docker-compose.yml
+++ b/docker/docker-compose.yml
@@ -86,6 +86,7 @@ services:
- "5010:5010" # Config service port
volumes:
- ${NEXENT_USER_DIR:-$HOME/nexent}:/mnt/nexent
+ - ${ROOT_DIR}/skills:/mnt/nexent-data/skills
- ${ROOT_DIR}/openssh-server/ssh-keys:/opt/ssh-keys:ro
- ${ROOT_DIR}/scripts/sync_user_supabase2pg.py:/opt/sync_user_supabase2pg.py:ro
- /var/run/docker.sock:/var/run/docker.sock:ro # Docker socket for MCP container management
@@ -116,6 +117,7 @@ services:
- "5014:5014" # Runtime service port
volumes:
- ${NEXENT_USER_DIR:-$HOME/nexent}:/mnt/nexent
+ - ${ROOT_DIR}/skills:/mnt/nexent-data/skills
- ${ROOT_DIR}/openssh-server/ssh-keys:/opt/ssh-keys:ro
environment:
<<: [*minio-vars, *es-vars]
@@ -173,6 +175,7 @@ services:
- "5013:5013" # Northbound service port
volumes:
- ${NEXENT_USER_DIR:-$HOME/nexent}:/mnt/nexent
+ - ${ROOT_DIR}/skills:/mnt/nexent-data/skills
- ${ROOT_DIR}/openssh-server/ssh-keys:/opt/ssh-keys:ro
environment:
<<: [*minio-vars, *es-vars]
@@ -327,6 +330,7 @@ services:
networks:
nexent:
+ name: nexent_network
driver: bridge
volumes:
diff --git a/docker/generate_env.sh b/docker/generate_env.sh
index 962102f1d..c6b20f0b1 100755
--- a/docker/generate_env.sh
+++ b/docker/generate_env.sh
@@ -2,34 +2,18 @@
# Exit immediately if a command exits with a non-zero status
set -e
-echo " 📁 Target .env location: Root directory (../)"
+echo " 📁 Target .env location: docker/.env"
# Function to copy and prepare .env file
prepare_env_file() {
- echo " 📝 Preparing root .env file..."
-
- # Check if .env already exists in root directory (parent directory)
- if [ -f "../.env" ]; then
- echo " ⚠️ .env already exists in root directory"
- echo ""
- read -p "👉 Do you want to overwrite it? [Y/N] (default: Y): " overwrite
- # If input is empty, use default "Y"
- overwrite=${overwrite:-Y}
- if [[ ! "$overwrite" =~ ^[Yy]$ ]]; then
- echo " Using existing .env file"
- return 0
- fi
- fi
+ echo " 📝 Preparing docker/.env file..."
- # Check if .env exists in current docker directory
if [ -f ".env" ]; then
- echo " 📋 Copying docker/.env to root directory..."
- cp ".env" "../.env"
- echo " ✅ Copied docker/.env to ../.env"
+ echo " ✅ Using existing docker/.env"
elif [ -f ".env.example" ]; then
- echo " 📋 docker/.env not found, copying .env.example to root directory..."
- cp ".env.example" "../.env"
- echo " ✅ Copied docker/.env.example to ../.env"
+ echo " 📋 docker/.env not found, copying docker/.env.example..."
+ cp ".env.example" ".env"
+ echo " ✅ Created docker/.env from docker/.env.example"
else
echo " ❌ ERROR Neither docker/.env nor docker/.env.example exists in docker directory"
ERROR_OCCURRED=1
@@ -39,57 +23,57 @@ prepare_env_file() {
# Function to update .env file with generated keys
update_env_file() {
- echo " 📝 Updating root .env file with generated keys..."
+ echo " 📝 Updating docker/.env file with generated keys..."
- if [ ! -f "../.env" ]; then
- echo " ❌ ERROR .env file does not exist in root directory"
+ if [ ! -f ".env" ]; then
+ echo " ❌ ERROR docker/.env file does not exist"
ERROR_OCCURRED=1
return 1
fi
# Update or add MINIO_ACCESS_KEY
- if grep -q "^MINIO_ACCESS_KEY=" ../.env; then
- sed -i.bak "s~^MINIO_ACCESS_KEY=.*~MINIO_ACCESS_KEY=$MINIO_ACCESS_KEY~" ../.env
+ if grep -q "^MINIO_ACCESS_KEY=" .env; then
+ sed -i.bak "s~^MINIO_ACCESS_KEY=.*~MINIO_ACCESS_KEY=$MINIO_ACCESS_KEY~" .env
else
- echo "" >> ../.env
- echo "# Generated MinIO Keys" >> ../.env
- echo "MINIO_ACCESS_KEY=$MINIO_ACCESS_KEY" >> ../.env
+ echo "" >> .env
+ echo "# Generated MinIO Keys" >> .env
+ echo "MINIO_ACCESS_KEY=$MINIO_ACCESS_KEY" >> .env
fi
# Update or add MINIO_SECRET_KEY
- if grep -q "^MINIO_SECRET_KEY=" ../.env; then
- sed -i.bak "s~^MINIO_SECRET_KEY=.*~MINIO_SECRET_KEY=$MINIO_SECRET_KEY~" ../.env
+ if grep -q "^MINIO_SECRET_KEY=" .env; then
+ sed -i.bak "s~^MINIO_SECRET_KEY=.*~MINIO_SECRET_KEY=$MINIO_SECRET_KEY~" .env
else
- echo "MINIO_SECRET_KEY=$MINIO_SECRET_KEY" >> ../.env
+ echo "MINIO_SECRET_KEY=$MINIO_SECRET_KEY" >> .env
fi
# Update or add ELASTICSEARCH_API_KEY (only if it was generated successfully)
if [ -n "$ELASTICSEARCH_API_KEY" ]; then
- if grep -q "^ELASTICSEARCH_API_KEY=" ../.env; then
- sed -i.bak "s~^ELASTICSEARCH_API_KEY=.*~ELASTICSEARCH_API_KEY=$ELASTICSEARCH_API_KEY~" ../.env
+ if grep -q "^ELASTICSEARCH_API_KEY=" .env; then
+ sed -i.bak "s~^ELASTICSEARCH_API_KEY=.*~ELASTICSEARCH_API_KEY=$ELASTICSEARCH_API_KEY~" .env
else
- echo "" >> ../.env
- echo "# Generated Elasticsearch API Key" >> ../.env
- echo "ELASTICSEARCH_API_KEY=$ELASTICSEARCH_API_KEY" >> ../.env
+ echo "" >> .env
+ echo "# Generated Elasticsearch API Key" >> .env
+ echo "ELASTICSEARCH_API_KEY=$ELASTICSEARCH_API_KEY" >> .env
fi
fi
# Update or add SSH credentials (only if they were set)
if [ -n "$SSH_USERNAME" ]; then
- if grep -q "^SSH_USERNAME=" ../.env; then
- sed -i.bak "s~^SSH_USERNAME=.*~SSH_USERNAME=$SSH_USERNAME~" ../.env
+ if grep -q "^SSH_USERNAME=" .env; then
+ sed -i.bak "s~^SSH_USERNAME=.*~SSH_USERNAME=$SSH_USERNAME~" .env
else
- echo "" >> ../.env
- echo "# SSH Terminal Tool Credentials" >> ../.env
- echo "SSH_USERNAME=$SSH_USERNAME" >> ../.env
+ echo "" >> .env
+ echo "# SSH Terminal Tool Credentials" >> .env
+ echo "SSH_USERNAME=$SSH_USERNAME" >> .env
fi
fi
if [ -n "$SSH_PASSWORD" ]; then
- if grep -q "^SSH_PASSWORD=" ../.env; then
- sed -i.bak "s~^SSH_PASSWORD=.*~SSH_PASSWORD=$SSH_PASSWORD~" ../.env
+ if grep -q "^SSH_PASSWORD=" .env; then
+ sed -i.bak "s~^SSH_PASSWORD=.*~SSH_PASSWORD=$SSH_PASSWORD~" .env
else
- echo "SSH_PASSWORD=$SSH_PASSWORD" >> ../.env
+ echo "SSH_PASSWORD=$SSH_PASSWORD" >> .env
fi
fi
echo " ✅ Generated keys updated successfully"
@@ -98,145 +82,145 @@ update_env_file() {
echo " 🔧 Updating service URLs for localhost development environment..."
# ELASTICSEARCH_HOST
- if grep -q "^ELASTICSEARCH_HOST=" ../.env; then
- sed -i.bak "s~^ELASTICSEARCH_HOST=.*~ELASTICSEARCH_HOST=http://localhost:9210~" ../.env
+ if grep -q "^ELASTICSEARCH_HOST=" .env; then
+ sed -i.bak "s~^ELASTICSEARCH_HOST=.*~ELASTICSEARCH_HOST=http://localhost:9210~" .env
else
- echo "" >> ../.env
- echo "# Development Environment URLs" >> ../.env
- echo "ELASTICSEARCH_HOST=http://localhost:9210" >> ../.env
+ echo "" >> .env
+ echo "# Development Environment URLs" >> .env
+ echo "ELASTICSEARCH_HOST=http://localhost:9210" >> .env
fi
# Main Services
# CONFIG_SERVICE_URL
- if grep -q "^CONFIG_SERVICE_URL=" ../.env; then
- sed -i.bak "s~^CONFIG_SERVICE_URL=.*~CONFIG_SERVICE_URL=http://localhost:5010~" ../.env
+ if grep -q "^CONFIG_SERVICE_URL=" .env; then
+ sed -i.bak "s~^CONFIG_SERVICE_URL=.*~CONFIG_SERVICE_URL=http://localhost:5010~" .env
else
- echo "" >> ../.env
- echo "# Main Services" >> ../.env
- echo "CONFIG_SERVICE_URL=http://localhost:5010" >> ../.env
+ echo "" >> .env
+ echo "# Main Services" >> .env
+ echo "CONFIG_SERVICE_URL=http://localhost:5010" >> .env
fi
# RUNTIME_SERVICE_URL
- if grep -q "^RUNTIME_SERVICE_URL=" ../.env; then
- sed -i.bak "s~^RUNTIME_SERVICE_URL=.*~RUNTIME_SERVICE_URL=http://localhost:5014~" ../.env
+ if grep -q "^RUNTIME_SERVICE_URL=" .env; then
+ sed -i.bak "s~^RUNTIME_SERVICE_URL=.*~RUNTIME_SERVICE_URL=http://localhost:5014~" .env
else
- echo "RUNTIME_SERVICE_URL=http://localhost:5014" >> ../.env
+ echo "RUNTIME_SERVICE_URL=http://localhost:5014" >> .env
fi
# ELASTICSEARCH_SERVICE
- if grep -q "^ELASTICSEARCH_SERVICE=" ../.env; then
- sed -i.bak "s~^ELASTICSEARCH_SERVICE=.*~ELASTICSEARCH_SERVICE=http://localhost:5010/api~" ../.env
+ if grep -q "^ELASTICSEARCH_SERVICE=" .env; then
+ sed -i.bak "s~^ELASTICSEARCH_SERVICE=.*~ELASTICSEARCH_SERVICE=http://localhost:5010/api~" .env
else
- echo "ELASTICSEARCH_SERVICE=http://localhost:5010/api" >> ../.env
+ echo "ELASTICSEARCH_SERVICE=http://localhost:5010/api" >> .env
fi
# NEXENT_MCP_SERVER
- if grep -q "^NEXENT_MCP_SERVER=" ../.env; then
- sed -i.bak "s~^NEXENT_MCP_SERVER=.*~NEXENT_MCP_SERVER=http://localhost:5011~" ../.env
+ if grep -q "^NEXENT_MCP_SERVER=" .env; then
+ sed -i.bak "s~^NEXENT_MCP_SERVER=.*~NEXENT_MCP_SERVER=http://localhost:5011~" .env
else
- echo "NEXENT_MCP_SERVER=http://localhost:5011" >> ../.env
+ echo "NEXENT_MCP_SERVER=http://localhost:5011" >> .env
fi
# DATA_PROCESS_SERVICE
- if grep -q "^DATA_PROCESS_SERVICE=" ../.env; then
- sed -i.bak "s~^DATA_PROCESS_SERVICE=.*~DATA_PROCESS_SERVICE=http://localhost:5012/api~" ../.env
+ if grep -q "^DATA_PROCESS_SERVICE=" .env; then
+ sed -i.bak "s~^DATA_PROCESS_SERVICE=.*~DATA_PROCESS_SERVICE=http://localhost:5012/api~" .env
else
- echo "DATA_PROCESS_SERVICE=http://localhost:5012/api" >> ../.env
+ echo "DATA_PROCESS_SERVICE=http://localhost:5012/api" >> .env
fi
# NORTHBOUND_API_SERVER
- if grep -q "^NORTHBOUND_API_SERVER=" ../.env; then
- sed -i.bak "s~^NORTHBOUND_API_SERVER=.*~NORTHBOUND_API_SERVER=http://localhost:5013/api~" ../.env
+ if grep -q "^NORTHBOUND_API_SERVER=" .env; then
+ sed -i.bak "s~^NORTHBOUND_API_SERVER=.*~NORTHBOUND_API_SERVER=http://localhost:5013/api~" .env
else
- echo "NORTHBOUND_API_SERVER=http://localhost:5013/api" >> ../.env
+ echo "NORTHBOUND_API_SERVER=http://localhost:5013/api" >> .env
fi
# MCP_MANAGEMENT_API
- if grep -q "^MCP_MANAGEMENT_API=" ../.env; then
- sed -i.bak "s~^MCP_MANAGEMENT_API=.*~MCP_MANAGEMENT_API=http://localhost:5015~" ../.env
+ if grep -q "^MCP_MANAGEMENT_API=" .env; then
+ sed -i.bak "s~^MCP_MANAGEMENT_API=.*~MCP_MANAGEMENT_API=http://localhost:5015~" .env
else
- echo "MCP_MANAGEMENT_API=http://localhost:5015" >> ../.env
+ echo "MCP_MANAGEMENT_API=http://localhost:5015" >> .env
fi
# MINIO_ENDPOINT
- if grep -q "^MINIO_ENDPOINT=" ../.env; then
- sed -i.bak "s~^MINIO_ENDPOINT=.*~MINIO_ENDPOINT=http://localhost:9010~" ../.env
+ if grep -q "^MINIO_ENDPOINT=" .env; then
+ sed -i.bak "s~^MINIO_ENDPOINT=.*~MINIO_ENDPOINT=http://localhost:9010~" .env
else
- echo "MINIO_ENDPOINT=http://localhost:9010" >> ../.env
+ echo "MINIO_ENDPOINT=http://localhost:9010" >> .env
fi
# REDIS_URL
- if grep -q "^REDIS_URL=" ../.env; then
- sed -i.bak "s~^REDIS_URL=.*~REDIS_URL=redis://localhost:6379/0~" ../.env
+ if grep -q "^REDIS_URL=" .env; then
+ sed -i.bak "s~^REDIS_URL=.*~REDIS_URL=redis://localhost:6379/0~" .env
else
- echo "REDIS_URL=redis://localhost:6379/0" >> ../.env
+ echo "REDIS_URL=redis://localhost:6379/0" >> .env
fi
# REDIS_BACKEND_URL
- if grep -q "^REDIS_BACKEND_URL=" ../.env; then
- sed -i.bak "s~^REDIS_BACKEND_URL=.*~REDIS_BACKEND_URL=redis://localhost:6379/1~" ../.env
+ if grep -q "^REDIS_BACKEND_URL=" .env; then
+ sed -i.bak "s~^REDIS_BACKEND_URL=.*~REDIS_BACKEND_URL=redis://localhost:6379/1~" .env
else
- echo "REDIS_BACKEND_URL=redis://localhost:6379/1" >> ../.env
+ echo "REDIS_BACKEND_URL=redis://localhost:6379/1" >> .env
fi
# POSTGRES_HOST
- if grep -q "^POSTGRES_HOST=" ../.env; then
- sed -i.bak "s~^POSTGRES_HOST=.*~POSTGRES_HOST=localhost~" ../.env
+ if grep -q "^POSTGRES_HOST=" .env; then
+ sed -i.bak "s~^POSTGRES_HOST=.*~POSTGRES_HOST=localhost~" .env
else
- echo "POSTGRES_HOST=localhost" >> ../.env
+ echo "POSTGRES_HOST=localhost" >> .env
fi
# POSTGRES_PORT
- if grep -q "^POSTGRES_PORT=" ../.env; then
- sed -i.bak "s~^POSTGRES_PORT=.*~POSTGRES_PORT=5434~" ../.env
+ if grep -q "^POSTGRES_PORT=" .env; then
+ sed -i.bak "s~^POSTGRES_PORT=.*~POSTGRES_PORT=5434~" .env
else
- echo "POSTGRES_PORT=5434" >> ../.env
+ echo "POSTGRES_PORT=5434" >> .env
fi
# Supabase Configuration (Only for full version)
if [ "$DEPLOYMENT_VERSION" = "full" ]; then
if [ -n "$SUPABASE_KEY" ]; then
- if grep -q "^SUPABASE_KEY=" ../.env; then
- sed -i.bak "s~^SUPABASE_KEY=.*~SUPABASE_KEY=$SUPABASE_KEY~" ../.env
+ if grep -q "^SUPABASE_KEY=" .env; then
+ sed -i.bak "s~^SUPABASE_KEY=.*~SUPABASE_KEY=$SUPABASE_KEY~" .env
else
- echo "" >> ../.env
- echo "# Supabase Keys" >> ../.env
- echo "SUPABASE_KEY=$SUPABASE_KEY" >> ../.env
+ echo "" >> .env
+ echo "# Supabase Keys" >> .env
+ echo "SUPABASE_KEY=$SUPABASE_KEY" >> .env
fi
fi
if [ -n "$SERVICE_ROLE_KEY" ]; then
- if grep -q "^SERVICE_ROLE_KEY=" ../.env; then
- sed -i.bak "s~^SERVICE_ROLE_KEY=.*~SERVICE_ROLE_KEY=$SERVICE_ROLE_KEY~" ../.env
+ if grep -q "^SERVICE_ROLE_KEY=" .env; then
+ sed -i.bak "s~^SERVICE_ROLE_KEY=.*~SERVICE_ROLE_KEY=$SERVICE_ROLE_KEY~" .env
else
- echo "SERVICE_ROLE_KEY=$SERVICE_ROLE_KEY" >> ../.env
+ echo "SERVICE_ROLE_KEY=$SERVICE_ROLE_KEY" >> .env
fi
fi
# Additional Supabase configuration
- if grep -q "^SUPABASE_URL=" ../.env; then
- sed -i.bak "s~^SUPABASE_URL=.*~SUPABASE_URL=http://localhost:8000~" ../.env
+ if grep -q "^SUPABASE_URL=" .env; then
+ sed -i.bak "s~^SUPABASE_URL=.*~SUPABASE_URL=http://localhost:8000~" .env
else
- echo "SUPABASE_URL=http://localhost:8000" >> ../.env
+ echo "SUPABASE_URL=http://localhost:8000" >> .env
fi
- if grep -q "^API_EXTERNAL_URL=" ../.env; then
- sed -i.bak "s~^API_EXTERNAL_URL=.*~API_EXTERNAL_URL=http://localhost:8000~" ../.env
+ if grep -q "^API_EXTERNAL_URL=" .env; then
+ sed -i.bak "s~^API_EXTERNAL_URL=.*~API_EXTERNAL_URL=http://localhost:8000~" .env
else
- echo "API_EXTERNAL_URL=http://localhost:8000" >> ../.env
+ echo "API_EXTERNAL_URL=http://localhost:8000" >> .env
fi
- if grep -q "^SITE_URL=" ../.env; then
- sed -i.bak "s~^SITE_URL=.*~SITE_URL=http://localhost:3011~" ../.env
+ if grep -q "^SITE_URL=" .env; then
+ sed -i.bak "s~^SITE_URL=.*~SITE_URL=http://localhost:3011~" .env
else
- echo "SITE_URL=http://localhost:3011" >> ../.env
+ echo "SITE_URL=http://localhost:3011" >> .env
fi
fi
# Remove backup file
- rm -f ../.env.bak
+ rm -f .env.bak
- echo " ✅ Root .env file updated successfully with localhost development URLs"
+ echo " ✅ docker/.env updated successfully with localhost development URLs"
}
# Function to show summary
diff --git a/docker/init.sql b/docker/init.sql
index 6ca77f731..046bdecf1 100644
--- a/docker/init.sql
+++ b/docker/init.sql
@@ -175,6 +175,10 @@ 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 '',
+ "concurrency_limit" INTEGER DEFAULT NULL,
+ "timeout_seconds" INTEGER DEFAULT 120,
CONSTRAINT "nexent_models_t_pk" PRIMARY KEY ("model_id")
);
ALTER TABLE "model_record_t" OWNER TO "root";
@@ -198,6 +202,10 @@ 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 COLUMN "model_record_t"."concurrency_limit" IS 'Maximum concurrent requests for this model. Default is NULL (unlimited).';
+COMMENT ON COLUMN "model_record_t"."timeout_seconds" IS 'Request timeout in seconds for this model. Default is 120 seconds.';
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 +219,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 +227,10 @@ 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),
+ "preserve_source_file" boolean NOT NULL DEFAULT true,
CONSTRAINT "knowledge_record_t_pk" PRIMARY KEY ("knowledge_id")
);
ALTER TABLE "knowledge_record_t" OWNER TO "root";
@@ -228,11 +241,18 @@ 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"."preserve_source_file" IS 'Whether to preserve uploaded source documents after vectorization';
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';
@@ -306,6 +326,8 @@ CREATE TABLE IF NOT EXISTS nexent.ag_tenant_agent_t (
model_id INTEGER,
business_logic_model_name VARCHAR(100),
business_logic_model_id INTEGER,
+ prompt_template_id INTEGER,
+ prompt_template_name VARCHAR(100),
max_steps INTEGER,
duty_prompt TEXT,
constraint_prompt TEXT,
@@ -316,9 +338,13 @@ CREATE TABLE IF NOT EXISTS nexent.ag_tenant_agent_t (
enabled BOOLEAN DEFAULT FALSE,
is_new BOOLEAN DEFAULT FALSE,
provide_run_summary BOOLEAN DEFAULT FALSE,
+ enable_context_manager BOOLEAN DEFAULT FALSE,
+ verification_config JSONB,
version_no INTEGER DEFAULT 0 NOT NULL,
current_version_no INTEGER NULL,
ingroup_permission VARCHAR(30),
+ greeting_message TEXT,
+ example_questions JSONB,
create_time TIMESTAMP WITHOUT TIME ZONE DEFAULT CURRENT_TIMESTAMP,
update_time TIMESTAMP WITHOUT TIME ZONE DEFAULT CURRENT_TIMESTAMP,
created_by VARCHAR(100),
@@ -355,6 +381,8 @@ COMMENT ON COLUMN nexent.ag_tenant_agent_t.model_name IS '[DEPRECATED] Name of t
COMMENT ON COLUMN nexent.ag_tenant_agent_t.model_id IS 'Model ID, foreign key reference to model_record_t.model_id';
COMMENT ON COLUMN nexent.ag_tenant_agent_t.business_logic_model_name IS 'Model name used for business logic prompt generation';
COMMENT ON COLUMN nexent.ag_tenant_agent_t.business_logic_model_id IS 'Model ID used for business logic prompt generation, foreign key reference to model_record_t.model_id';
+COMMENT ON COLUMN nexent.ag_tenant_agent_t.prompt_template_id IS 'Prompt template ID used for business logic prompt generation';
+COMMENT ON COLUMN nexent.ag_tenant_agent_t.prompt_template_name IS 'Prompt template name used for business logic prompt generation';
COMMENT ON COLUMN nexent.ag_tenant_agent_t.max_steps IS 'Maximum number of steps';
COMMENT ON COLUMN nexent.ag_tenant_agent_t.duty_prompt IS 'Duty prompt';
COMMENT ON COLUMN nexent.ag_tenant_agent_t.constraint_prompt IS 'Constraint prompt';
@@ -373,12 +401,107 @@ COMMENT ON COLUMN nexent.ag_tenant_agent_t.is_new IS 'Whether this agent is mark
COMMENT ON COLUMN nexent.ag_tenant_agent_t.version_no IS 'Version number. 0 = draft/editing state, >=1 = published snapshot';
COMMENT ON COLUMN nexent.ag_tenant_agent_t.current_version_no IS 'Current published version number. NULL means no version published yet';
COMMENT ON COLUMN nexent.ag_tenant_agent_t.ingroup_permission IS 'In-group permission: EDIT, READ_ONLY, PRIVATE';
+COMMENT ON COLUMN nexent.ag_tenant_agent_t.enable_context_manager IS 'Whether to enable context management (compression) for this agent';
+COMMENT ON COLUMN nexent.ag_tenant_agent_t.verification_config IS 'Layered ReAct self-verification configuration';
+COMMENT ON COLUMN nexent.ag_tenant_agent_t.greeting_message IS 'Agent greeting message displayed on chat initial screen';
+COMMENT ON COLUMN nexent.ag_tenant_agent_t.example_questions IS 'List of example questions for starting a conversation with this agent';
-- Create index for is_new queries
CREATE INDEX IF NOT EXISTS idx_ag_tenant_agent_t_is_new
ON nexent.ag_tenant_agent_t (tenant_id, is_new)
WHERE delete_flag = 'N';
+CREATE TABLE IF NOT EXISTS nexent.ag_prompt_template_t (
+ template_id SERIAL PRIMARY KEY,
+ template_name VARCHAR(100) NOT NULL,
+ description VARCHAR(500),
+ template_type VARCHAR(50) NOT NULL DEFAULT 'agent_generate',
+ tenant_id VARCHAR(100) NOT NULL,
+ user_id VARCHAR(100) NOT NULL,
+ template_content_zh JSONB NOT NULL,
+ template_content_en JSONB,
+ create_time TIMESTAMP WITHOUT TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+ update_time TIMESTAMP WITHOUT TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+ created_by VARCHAR(100),
+ updated_by VARCHAR(100),
+ delete_flag VARCHAR(1) DEFAULT 'N'
+);
+
+ALTER TABLE nexent.ag_prompt_template_t OWNER TO "root";
+
+CREATE OR REPLACE FUNCTION update_ag_prompt_template_update_time()
+RETURNS TRIGGER AS $$
+BEGIN
+ NEW.update_time = CURRENT_TIMESTAMP;
+ RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER update_ag_prompt_template_update_time_trigger
+BEFORE UPDATE ON nexent.ag_prompt_template_t
+FOR EACH ROW
+EXECUTE FUNCTION update_ag_prompt_template_update_time();
+
+COMMENT ON TABLE nexent.ag_prompt_template_t IS 'Prompt template table for user-defined business logic generation prompts';
+COMMENT ON COLUMN nexent.ag_prompt_template_t.template_id IS 'Prompt template ID';
+COMMENT ON COLUMN nexent.ag_prompt_template_t.template_name IS 'Prompt template name';
+COMMENT ON COLUMN nexent.ag_prompt_template_t.description IS 'Prompt template description';
+COMMENT ON COLUMN nexent.ag_prompt_template_t.template_type IS 'Prompt template type';
+COMMENT ON COLUMN nexent.ag_prompt_template_t.tenant_id IS 'Tenant ID';
+COMMENT ON COLUMN nexent.ag_prompt_template_t.user_id IS 'User ID';
+COMMENT ON COLUMN nexent.ag_prompt_template_t.template_content_zh IS 'Chinese prompt template content';
+COMMENT ON COLUMN nexent.ag_prompt_template_t.template_content_en IS 'English prompt template content';
+COMMENT ON COLUMN nexent.ag_prompt_template_t.create_time IS 'Creation time';
+COMMENT ON COLUMN nexent.ag_prompt_template_t.update_time IS 'Update time';
+COMMENT ON COLUMN nexent.ag_prompt_template_t.created_by IS 'Creator';
+COMMENT ON COLUMN nexent.ag_prompt_template_t.updated_by IS 'Updater';
+COMMENT ON COLUMN nexent.ag_prompt_template_t.delete_flag IS 'Whether it is deleted. Optional values: Y/N';
+
+CREATE UNIQUE INDEX IF NOT EXISTS uq_prompt_template_user_name_active
+ON nexent.ag_prompt_template_t (tenant_id, user_id, template_name)
+WHERE delete_flag = 'N';
+
+CREATE INDEX IF NOT EXISTS idx_ag_prompt_template_t_user
+ON nexent.ag_prompt_template_t (tenant_id, user_id, template_type)
+WHERE delete_flag = 'N';
+
+INSERT INTO nexent.ag_prompt_template_t (
+ template_id,
+ template_name,
+ description,
+ template_type,
+ tenant_id,
+ user_id,
+ template_content_zh,
+ template_content_en,
+ created_by,
+ updated_by,
+ delete_flag
+)
+VALUES (
+ 0,
+ 'system_default',
+ 'System default prompt template',
+ 'agent_generate',
+ 'tenant_id',
+ 'user_id',
+ '{}'::jsonb,
+ '{}'::jsonb,
+ 'user_id',
+ 'user_id',
+ 'N'
+)
+ON CONFLICT (template_id) DO UPDATE SET
+ template_name = EXCLUDED.template_name,
+ description = EXCLUDED.description,
+ template_type = EXCLUDED.template_type,
+ tenant_id = EXCLUDED.tenant_id,
+ user_id = EXCLUDED.user_id,
+ template_content_zh = EXCLUDED.template_content_zh,
+ template_content_en = EXCLUDED.template_content_en,
+ updated_by = EXCLUDED.updated_by,
+ delete_flag = 'N';
+
-- Create the ag_tool_instance_t table in the nexent schema
CREATE TABLE IF NOT EXISTS nexent.ag_tool_instance_t (
@@ -490,6 +613,14 @@ CREATE TABLE IF NOT EXISTS nexent.mcp_record_t (
status BOOLEAN DEFAULT NULL,
container_id VARCHAR(200) DEFAULT NULL,
authorization_token VARCHAR(500) DEFAULT NULL,
+ custom_headers JSON DEFAULT NULL,
+ source VARCHAR(30),
+ registry_json JSONB,
+ config_json JSON,
+ enabled BOOLEAN DEFAULT TRUE,
+ tags TEXT[],
+ description TEXT,
+ container_port INTEGER,
create_time TIMESTAMP WITHOUT TIME ZONE DEFAULT CURRENT_TIMESTAMP,
update_time TIMESTAMP WITHOUT TIME ZONE DEFAULT CURRENT_TIMESTAMP,
created_by VARCHAR(100),
@@ -509,11 +640,19 @@ COMMENT ON COLUMN nexent.mcp_record_t.mcp_server IS 'MCP server address';
COMMENT ON COLUMN nexent.mcp_record_t.status IS 'MCP server connection status, true=connected, false=disconnected, null=unknown';
COMMENT ON COLUMN nexent.mcp_record_t.container_id IS 'Docker container ID for MCP service, NULL for non-containerized MCP';
COMMENT ON COLUMN nexent.mcp_record_t.authorization_token IS 'Authorization token for MCP server authentication (e.g., Bearer token)';
+COMMENT ON COLUMN nexent.mcp_record_t.custom_headers IS 'Custom HTTP headers as JSON object for MCP server requests';
COMMENT ON COLUMN nexent.mcp_record_t.create_time IS 'Creation time, audit field';
COMMENT ON COLUMN nexent.mcp_record_t.update_time IS 'Update time, audit field';
COMMENT ON COLUMN nexent.mcp_record_t.created_by IS 'Creator ID, audit field';
COMMENT ON COLUMN nexent.mcp_record_t.updated_by IS 'Last updater ID, audit field';
COMMENT ON COLUMN nexent.mcp_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 nexent.mcp_record_t.source IS 'Source type: local/mcp_registry/community';
+COMMENT ON COLUMN nexent.mcp_record_t.registry_json IS 'Full MCP registry server.json snapshot';
+COMMENT ON COLUMN nexent.mcp_record_t.config_json IS 'MCP config data';
+COMMENT ON COLUMN nexent.mcp_record_t.enabled IS 'Enabled';
+COMMENT ON COLUMN nexent.mcp_record_t.tags IS 'Tags';
+COMMENT ON COLUMN nexent.mcp_record_t.description IS 'Description';
+COMMENT ON COLUMN nexent.mcp_record_t.container_port IS 'Host port bound for containerized MCP service';
-- Create a function to update the update_time column
CREATE OR REPLACE FUNCTION update_mcp_record_update_time()
@@ -536,6 +675,19 @@ EXECUTE FUNCTION update_mcp_record_update_time();
-- Add comment to the trigger
COMMENT ON TRIGGER update_mcp_record_update_time_trigger ON nexent.mcp_record_t IS 'Trigger to call update_mcp_record_update_time function before each update on mcp_record_t table';
+-- Add indexes for common management queries
+CREATE INDEX IF NOT EXISTS idx_mcp_record_t_tenant_delete
+ ON nexent.mcp_record_t (tenant_id, delete_flag);
+
+CREATE INDEX IF NOT EXISTS idx_mcp_record_t_tenant_name
+ ON nexent.mcp_record_t (tenant_id, mcp_name, delete_flag);
+
+CREATE INDEX IF NOT EXISTS idx_mcp_record_t_tenant_server
+ ON nexent.mcp_record_t (tenant_id, mcp_server, delete_flag);
+
+CREATE INDEX IF NOT EXISTS idx_mcp_record_t_tags_gin
+ ON nexent.mcp_record_t USING GIN (tags);
+
-- Create user tenant relationship table
CREATE TABLE IF NOT EXISTS nexent.user_tenant_t (
user_tenant_id SERIAL PRIMARY KEY,
@@ -571,6 +723,7 @@ CREATE TABLE IF NOT EXISTS nexent.ag_agent_relation_t (
parent_agent_id INTEGER,
tenant_id VARCHAR(100),
version_no INTEGER DEFAULT 0 NOT NULL,
+ selected_agent_version_no INTEGER,
create_time TIMESTAMP WITHOUT TIME ZONE DEFAULT CURRENT_TIMESTAMP,
update_time TIMESTAMP WITHOUT TIME ZONE DEFAULT CURRENT_TIMESTAMP,
created_by VARCHAR(100),
@@ -603,6 +756,7 @@ COMMENT ON COLUMN nexent.ag_agent_relation_t.selected_agent_id IS 'Selected agen
COMMENT ON COLUMN nexent.ag_agent_relation_t.parent_agent_id IS 'Parent agent ID';
COMMENT ON COLUMN nexent.ag_agent_relation_t.tenant_id IS 'Tenant ID';
COMMENT ON COLUMN nexent.ag_agent_relation_t.version_no IS 'Version number. 0 = draft/editing state, >=1 = published snapshot';
+COMMENT ON COLUMN nexent.ag_agent_relation_t.selected_agent_version_no IS 'Pinned version of selected_agent_id. NULL = use child current published version at runtime (legacy/draft).';
COMMENT ON COLUMN nexent.ag_agent_relation_t.create_time IS 'Creation time, audit field';
COMMENT ON COLUMN nexent.ag_agent_relation_t.update_time IS 'Update time, audit field';
COMMENT ON COLUMN nexent.ag_agent_relation_t.created_by IS 'Creator ID, audit field';
@@ -678,7 +832,7 @@ COMMENT ON COLUMN nexent.tenant_invitation_code_t.group_ids IS 'Associated group
COMMENT ON COLUMN nexent.tenant_invitation_code_t.capacity IS 'Invitation code capacity';
COMMENT ON COLUMN nexent.tenant_invitation_code_t.expiry_date IS 'Invitation code expiry date';
COMMENT ON COLUMN nexent.tenant_invitation_code_t.status IS 'Invitation code status: IN_USE, EXPIRE, DISABLE, RUN_OUT';
-COMMENT ON COLUMN nexent.tenant_invitation_code_t.code_type IS 'Invitation code type: ADMIN_INVITE, DEV_INVITE, USER_INVITE';
+COMMENT ON COLUMN nexent.tenant_invitation_code_t.code_type IS 'Invitation code type: ADMIN_INVITE, DEV_INVITE, USER_INVITE, ASSET_OWNER_INVITE';
COMMENT ON COLUMN nexent.tenant_invitation_code_t.create_time IS 'Create time';
COMMENT ON COLUMN nexent.tenant_invitation_code_t.update_time IS 'Update time';
COMMENT ON COLUMN nexent.tenant_invitation_code_t.created_by IS 'Created by';
@@ -959,7 +1113,42 @@ INSERT INTO nexent.role_permission_t (role_permission_id, user_role, permission_
(184, 'SPEED', 'RESOURCE', 'TENANT.INVITE', 'CREATE'),
(185, 'SPEED', 'RESOURCE', 'TENANT.INVITE', 'READ'),
(186, 'SPEED', 'RESOURCE', 'TENANT.INVITE', 'UPDATE'),
-(187, 'SPEED', 'RESOURCE', 'TENANT.INVITE', 'DELETE');
+(187, 'SPEED', 'RESOURCE', 'TENANT.INVITE', 'DELETE'),
+(188, 'SU', 'RESOURCE', 'INVITE.ASSET_OWNER', 'CREATE'),
+(189, 'SU', 'RESOURCE', 'INVITE.ASSET_OWNER', 'READ'),
+(190, 'SU', 'RESOURCE', 'INVITE.ASSET_OWNER', 'UPDATE'),
+(191, 'SU', 'RESOURCE', 'INVITE.ASSET_OWNER', 'DELETE'),
+(192, 'ASSET_OWNER', 'VISIBILITY', 'LEFT_NAV_MENU', '/'),
+(193, 'ASSET_OWNER', 'VISIBILITY', 'LEFT_NAV_MENU', '/agents'),
+(194, 'ASSET_OWNER', 'VISIBILITY', 'LEFT_NAV_MENU', '/knowledges'),
+(195, 'ASSET_OWNER', 'VISIBILITY', 'LEFT_NAV_MENU', '/chat'),
+(196, 'ASSET_OWNER', 'VISIBILITY', 'LEFT_NAV_MENU', '/space'),
+(197, 'ASSET_OWNER', 'VISIBILITY', 'LEFT_NAV_MENU', '/market'),
+(198, 'ASSET_OWNER', 'VISIBILITY', 'LEFT_NAV_MENU', '/models'),
+(199, 'ASSET_OWNER', 'RESOURCE', 'AGENT', 'CREATE'),
+(200, 'ASSET_OWNER', 'RESOURCE', 'AGENT', 'READ'),
+(201, 'ASSET_OWNER', 'RESOURCE', 'AGENT', 'UPDATE'),
+(202, 'ASSET_OWNER', 'RESOURCE', 'AGENT', 'DELETE'),
+(203, 'ASSET_OWNER', 'RESOURCE', 'SKILL', 'CREATE'),
+(204, 'ASSET_OWNER', 'RESOURCE', 'SKILL', 'READ'),
+(205, 'ASSET_OWNER', 'RESOURCE', 'SKILL', 'UPDATE'),
+(206, 'ASSET_OWNER', 'RESOURCE', 'SKILL', 'DELETE'),
+(207, 'ASSET_OWNER', 'RESOURCE', 'KB', 'CREATE'),
+(208, 'ASSET_OWNER', 'RESOURCE', 'KB', 'READ'),
+(209, 'ASSET_OWNER', 'RESOURCE', 'KB', 'UPDATE'),
+(210, 'ASSET_OWNER', 'RESOURCE', 'KB', 'DELETE'),
+(211, 'ASSET_OWNER', 'RESOURCE', 'MCP', 'CREATE'),
+(212, 'ASSET_OWNER', 'RESOURCE', 'MCP', 'READ'),
+(213, 'ASSET_OWNER', 'RESOURCE', 'MCP', 'UPDATE'),
+(214, 'ASSET_OWNER', 'RESOURCE', 'MCP', 'DELETE'),
+(215, 'ASSET_OWNER', 'RESOURCE', 'MODEL', 'CREATE'),
+(216, 'ASSET_OWNER', 'RESOURCE', 'MODEL', 'READ'),
+(217, 'ASSET_OWNER', 'RESOURCE', 'MODEL', 'UPDATE'),
+(218, 'ASSET_OWNER', 'RESOURCE', 'MODEL', 'DELETE'),
+(219, 'ASSET_OWNER', 'RESOURCE', 'USER.ROLE', 'READ'),
+(220, 'ASSET_OWNER', 'VISIBILITY', 'LEFT_NAV_MENU', '/users'),
+(221, 'SU', 'VISIBILITY', 'LEFT_NAV_MENU', '/asset-owner-resources')
+;
-- Insert SPEED role user into user_tenant_t table if not exists
INSERT INTO nexent.user_tenant_t (user_id, tenant_id, user_role, user_email, created_by, updated_by)
@@ -977,6 +1166,7 @@ CREATE TABLE IF NOT EXISTS nexent.ag_tenant_agent_version_t (
source_version_no INTEGER NULL,
source_type VARCHAR(30) NULL,
status VARCHAR(30) DEFAULT 'RELEASED',
+ is_a2a BOOLEAN DEFAULT FALSE,
created_by VARCHAR(100) NOT NULL,
create_time TIMESTAMP(6) DEFAULT CURRENT_TIMESTAMP,
updated_by VARCHAR(100),
@@ -1003,6 +1193,7 @@ COMMENT ON COLUMN nexent.ag_tenant_agent_version_t.release_note IS 'Release note
COMMENT ON COLUMN nexent.ag_tenant_agent_version_t.source_version_no IS 'Source version number. If this version is a rollback, record the source version number.';
COMMENT ON COLUMN nexent.ag_tenant_agent_version_t.source_type IS 'Source type: NORMAL (normal publish) / ROLLBACK (rollback and republish).';
COMMENT ON COLUMN nexent.ag_tenant_agent_version_t.status IS 'Version status: RELEASED / DISABLED / ARCHIVED';
+COMMENT ON COLUMN nexent.ag_tenant_agent_version_t.is_a2a IS 'Whether this version is published as an A2A Server agent';
COMMENT ON COLUMN nexent.ag_tenant_agent_version_t.created_by IS 'User who published this version';
COMMENT ON COLUMN nexent.ag_tenant_agent_version_t.create_time IS 'Version creation timestamp';
COMMENT ON COLUMN nexent.ag_tenant_agent_version_t.updated_by IS 'Last user who updated this version';
@@ -1072,10 +1263,12 @@ COMMENT ON COLUMN nexent.user_token_usage_log_t.delete_flag IS 'Soft delete flag
CREATE TABLE IF NOT EXISTS nexent.ag_skill_info_t (
skill_id SERIAL4 PRIMARY KEY NOT NULL,
skill_name VARCHAR(100) NOT NULL,
+ tenant_id VARCHAR(100),
skill_description VARCHAR(1000),
skill_tags JSON,
skill_content TEXT,
- params JSON,
+ config_schemas JSON,
+ config_values JSON,
source VARCHAR(30) DEFAULT 'official',
created_by VARCHAR(100),
create_time TIMESTAMP WITHOUT TIME ZONE DEFAULT CURRENT_TIMESTAMP,
@@ -1091,11 +1284,13 @@ COMMENT ON TABLE nexent.ag_skill_info_t IS 'Skill information table for managing
-- Add comments to the columns
COMMENT ON COLUMN nexent.ag_skill_info_t.skill_id IS 'Skill ID, unique primary key';
-COMMENT ON COLUMN nexent.ag_skill_info_t.skill_name IS 'Skill name, globally unique';
+COMMENT ON COLUMN nexent.ag_skill_info_t.skill_name IS 'Skill name, unique within tenant';
+COMMENT ON COLUMN nexent.ag_skill_info_t.tenant_id IS 'Tenant ID for multi-tenancy. NULL for pre-existing skills.';
COMMENT ON COLUMN nexent.ag_skill_info_t.skill_description IS 'Skill description text';
COMMENT ON COLUMN nexent.ag_skill_info_t.skill_tags IS 'Skill tags stored as JSON array';
COMMENT ON COLUMN nexent.ag_skill_info_t.skill_content IS 'Skill content or prompt text';
-COMMENT ON COLUMN nexent.ag_skill_info_t.params IS 'Skill configuration parameters stored as JSON object';
+COMMENT ON COLUMN nexent.ag_skill_info_t.config_schemas IS 'Parameter metadata from config/schema.yaml';
+COMMENT ON COLUMN nexent.ag_skill_info_t.config_values IS 'Runtime parameter values from config/config.yaml';
COMMENT ON COLUMN nexent.ag_skill_info_t.source IS 'Skill source: official, custom, or partner';
COMMENT ON COLUMN nexent.ag_skill_info_t.created_by IS 'Creator ID';
COMMENT ON COLUMN nexent.ag_skill_info_t.create_time IS 'Creation timestamp';
@@ -1141,6 +1336,8 @@ CREATE TABLE IF NOT EXISTS nexent.ag_skill_instance_t (
tenant_id VARCHAR(100),
enabled BOOLEAN DEFAULT TRUE,
version_no INTEGER DEFAULT 0 NOT NULL,
+ config_values JSON,
+ config_schemas JSON,
created_by VARCHAR(100),
create_time TIMESTAMP WITHOUT TIME ZONE DEFAULT CURRENT_TIMESTAMP,
updated_by VARCHAR(100),
@@ -1162,6 +1359,8 @@ COMMENT ON COLUMN nexent.ag_skill_instance_t.user_id IS 'User ID';
COMMENT ON COLUMN nexent.ag_skill_instance_t.tenant_id IS 'Tenant ID';
COMMENT ON COLUMN nexent.ag_skill_instance_t.enabled IS 'Whether this skill is enabled for the agent';
COMMENT ON COLUMN nexent.ag_skill_instance_t.version_no IS 'Version number. 0 = draft/editing state, >=1 = published snapshot';
+COMMENT ON COLUMN nexent.ag_skill_instance_t.config_values IS 'Per-agent runtime parameter values from config/config.yaml';
+COMMENT ON COLUMN nexent.ag_skill_instance_t.config_schemas IS 'Per-agent parameter schema overrides from config/schema.yaml';
COMMENT ON COLUMN nexent.ag_skill_instance_t.created_by IS 'Creator ID';
COMMENT ON COLUMN nexent.ag_skill_instance_t.create_time IS 'Creation timestamp';
COMMENT ON COLUMN nexent.ag_skill_instance_t.updated_by IS 'Last updater ID';
@@ -1302,6 +1501,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,
@@ -1348,6 +1550,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 (
@@ -1361,8 +1564,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";
@@ -1472,9 +1674,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";
@@ -1500,8 +1700,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)
);
@@ -1517,3 +1715,225 @@ COMMENT ON COLUMN nexent.ag_a2a_artifact_t.parts IS 'Artifact parts following A2
COMMENT ON COLUMN nexent.ag_a2a_artifact_t.meta_data IS 'Artifact metadata';
COMMENT ON COLUMN nexent.ag_a2a_artifact_t.extensions IS 'Extension URI list';
COMMENT ON COLUMN nexent.ag_a2a_artifact_t.create_time IS 'Artifact creation timestamp';
+
+-- Create the model_monitoring_record_t table for LLM performance metrics
+CREATE TABLE IF NOT EXISTS nexent.model_monitoring_record_t (
+ monitoring_id SERIAL PRIMARY KEY,
+ model_id INT4,
+ model_name VARCHAR(100) NOT NULL,
+ model_type VARCHAR(20) DEFAULT 'llm',
+ agent_id INT4,
+ agent_name VARCHAR(100),
+ conversation_id INT4,
+ tenant_id VARCHAR(100) NOT NULL,
+ user_id VARCHAR(100),
+ display_name VARCHAR(100),
+ request_duration_ms INT4,
+ ttft_ms INT4,
+ input_tokens INT4,
+ output_tokens INT4,
+ total_tokens INT4,
+ generation_rate FLOAT,
+ is_streaming BOOLEAN DEFAULT FALSE,
+ is_success BOOLEAN DEFAULT TRUE,
+ is_error BOOLEAN DEFAULT FALSE,
+ error_type VARCHAR(50),
+ error_message TEXT,
+ retry_count INT4 DEFAULT 0,
+ operation VARCHAR(50),
+ create_time TIMESTAMP DEFAULT NOW(),
+ delete_flag VARCHAR(1) DEFAULT 'N'
+);
+
+ALTER TABLE nexent.model_monitoring_record_t OWNER TO "root";
+
+COMMENT ON TABLE nexent.model_monitoring_record_t IS 'Per-request LLM performance metrics for model monitoring';
+COMMENT ON COLUMN nexent.model_monitoring_record_t.monitoring_id IS 'Monitoring record ID, unique primary key';
+COMMENT ON COLUMN nexent.model_monitoring_record_t.model_id IS 'Foreign key to model_record_t.model_id';
+COMMENT ON COLUMN nexent.model_monitoring_record_t.model_name IS 'Model identifier (repo/name format)';
+COMMENT ON COLUMN nexent.model_monitoring_record_t.model_type IS 'Model type: llm, vlm, embedding, multi_embedding, rerank';
+COMMENT ON COLUMN nexent.model_monitoring_record_t.agent_id IS 'Agent ID that initiated the request';
+COMMENT ON COLUMN nexent.model_monitoring_record_t.agent_name IS 'Agent display name';
+COMMENT ON COLUMN nexent.model_monitoring_record_t.conversation_id IS 'Conversation ID associated with the request';
+COMMENT ON COLUMN nexent.model_monitoring_record_t.tenant_id IS 'Tenant ID for multi-tenancy isolation';
+COMMENT ON COLUMN nexent.model_monitoring_record_t.user_id IS 'User ID who initiated the request';
+COMMENT ON COLUMN nexent.model_monitoring_record_t.display_name IS 'Human-readable model display name';
+COMMENT ON COLUMN nexent.model_monitoring_record_t.request_duration_ms IS 'Total request duration in milliseconds';
+COMMENT ON COLUMN nexent.model_monitoring_record_t.ttft_ms IS 'Time to first token in milliseconds (streaming only)';
+COMMENT ON COLUMN nexent.model_monitoring_record_t.input_tokens IS 'Number of input prompt tokens';
+COMMENT ON COLUMN nexent.model_monitoring_record_t.output_tokens IS 'Number of output completion tokens';
+COMMENT ON COLUMN nexent.model_monitoring_record_t.total_tokens IS 'Total tokens (input + output)';
+COMMENT ON COLUMN nexent.model_monitoring_record_t.generation_rate IS 'Token generation rate in tokens per second';
+COMMENT ON COLUMN nexent.model_monitoring_record_t.is_streaming IS 'Whether the request used streaming response';
+COMMENT ON COLUMN nexent.model_monitoring_record_t.is_success IS 'Whether the request completed successfully';
+COMMENT ON COLUMN nexent.model_monitoring_record_t.is_error IS 'Whether the request resulted in an error';
+COMMENT ON COLUMN nexent.model_monitoring_record_t.error_type IS 'Error exception class name';
+COMMENT ON COLUMN nexent.model_monitoring_record_t.error_message IS 'Error message text';
+COMMENT ON COLUMN nexent.model_monitoring_record_t.retry_count IS 'Number of retry attempts';
+COMMENT ON COLUMN nexent.model_monitoring_record_t.operation IS 'Operation type: chat_completion, title_generation, connectivity_check, embedding_call, system_prompt_generation';
+COMMENT ON COLUMN nexent.model_monitoring_record_t.create_time IS 'Record creation timestamp';
+COMMENT ON COLUMN nexent.model_monitoring_record_t.delete_flag IS 'Soft delete flag: Y/N';
+
+CREATE INDEX IF NOT EXISTS ix_monitoring_model_id ON nexent.model_monitoring_record_t (model_id);
+CREATE INDEX IF NOT EXISTS ix_monitoring_tenant_id ON nexent.model_monitoring_record_t (tenant_id);
+CREATE INDEX IF NOT EXISTS ix_monitoring_agent_id ON nexent.model_monitoring_record_t (agent_id);
+CREATE INDEX IF NOT EXISTS ix_monitoring_create_time ON nexent.model_monitoring_record_t (create_time);
+CREATE INDEX IF NOT EXISTS ix_monitoring_is_error ON nexent.model_monitoring_record_t (is_error);
+CREATE INDEX IF NOT EXISTS ix_monitoring_model_type ON nexent.model_monitoring_record_t (model_type);
+CREATE INDEX IF NOT EXISTS ix_monitoring_model_time ON nexent.model_monitoring_record_t (model_id, create_time);
+
+-- Create user OAuth account table for third-party login (GitHub, WeChat, etc.)
+CREATE TABLE IF NOT EXISTS nexent.user_oauth_account_t (
+ oauth_account_id SERIAL PRIMARY KEY,
+ user_id VARCHAR(100) NOT NULL,
+ provider VARCHAR(30) NOT NULL,
+ provider_user_id VARCHAR(200) NOT NULL,
+ provider_email VARCHAR(255),
+ provider_username VARCHAR(200),
+ tenant_id VARCHAR(100),
+ create_time TIMESTAMP WITHOUT TIME ZONE DEFAULT NOW(),
+ update_time TIMESTAMP WITHOUT TIME ZONE DEFAULT NOW(),
+ created_by VARCHAR(100),
+ updated_by VARCHAR(100),
+ delete_flag CHAR(1) DEFAULT 'N',
+ CONSTRAINT uq_oauth_provider_user UNIQUE (provider, provider_user_id)
+);
+
+ALTER TABLE nexent.user_oauth_account_t OWNER TO "root";
+
+-- Create a function to update the update_time column
+CREATE OR REPLACE FUNCTION update_user_oauth_account_t_update_time()
+RETURNS TRIGGER AS $$
+BEGIN
+ NEW.update_time = CURRENT_TIMESTAMP;
+ RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Create a trigger to call the function before each update
+CREATE TRIGGER update_user_oauth_account_t_update_time_trigger
+BEFORE UPDATE ON nexent.user_oauth_account_t
+FOR EACH ROW
+EXECUTE FUNCTION update_user_oauth_account_t_update_time();
+
+-- Add comments
+COMMENT ON TABLE nexent.user_oauth_account_t IS 'User OAuth account table - third-party login bindings';
+COMMENT ON COLUMN nexent.user_oauth_account_t.oauth_account_id IS 'OAuth account ID, primary key';
+COMMENT ON COLUMN nexent.user_oauth_account_t.user_id IS 'Nexent user ID (Supabase UUID)';
+COMMENT ON COLUMN nexent.user_oauth_account_t.provider IS 'OAuth provider name: github, wechat, gde, link_app';
+COMMENT ON COLUMN nexent.user_oauth_account_t.provider_user_id IS 'User ID from the OAuth provider';
+COMMENT ON COLUMN nexent.user_oauth_account_t.provider_email IS 'Email from the OAuth provider';
+COMMENT ON COLUMN nexent.user_oauth_account_t.provider_username IS 'Display name from the OAuth provider';
+COMMENT ON COLUMN nexent.user_oauth_account_t.tenant_id IS 'Tenant ID at time of linking';
+COMMENT ON COLUMN nexent.user_oauth_account_t.create_time IS 'Creation time';
+COMMENT ON COLUMN nexent.user_oauth_account_t.update_time IS 'Update time';
+COMMENT ON COLUMN nexent.user_oauth_account_t.created_by IS 'Creator';
+COMMENT ON COLUMN nexent.user_oauth_account_t.updated_by IS 'Updater';
+COMMENT ON COLUMN nexent.user_oauth_account_t.delete_flag IS 'Whether it is deleted. Optional values: Y/N';
+
+-- Create index for user_id queries
+CREATE INDEX IF NOT EXISTS idx_user_oauth_account_t_user_id
+ON nexent.user_oauth_account_t (user_id);
+
+-- mcp_community_record_t: Community MCP market table
+CREATE TABLE IF NOT EXISTS nexent.mcp_community_record_t (
+ community_id SERIAL PRIMARY KEY NOT NULL,
+ tenant_id VARCHAR(100),
+ user_id VARCHAR(100),
+ mcp_name VARCHAR(100) NOT NULL,
+ mcp_server VARCHAR(500) NOT NULL,
+ source VARCHAR(30) DEFAULT 'community',
+ version VARCHAR(50),
+ registry_json JSONB,
+ transport_type VARCHAR(30),
+ config_json JSON,
+ tags TEXT[],
+ description TEXT,
+ create_time TIMESTAMP WITHOUT TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+ update_time TIMESTAMP WITHOUT TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+ created_by VARCHAR(100),
+ updated_by VARCHAR(100),
+ delete_flag VARCHAR(1) DEFAULT 'N'
+);
+
+ALTER TABLE nexent.mcp_community_record_t OWNER TO root;
+
+COMMENT ON TABLE nexent.mcp_community_record_t IS 'Community MCP market records, publishable from tenant MCP services';
+COMMENT ON COLUMN nexent.mcp_community_record_t.community_id IS 'Community record ID, unique primary key';
+COMMENT ON COLUMN nexent.mcp_community_record_t.tenant_id IS 'Publisher tenant ID';
+COMMENT ON COLUMN nexent.mcp_community_record_t.user_id IS 'Publisher user ID';
+COMMENT ON COLUMN nexent.mcp_community_record_t.mcp_name IS 'MCP name';
+COMMENT ON COLUMN nexent.mcp_community_record_t.mcp_server IS 'MCP server URL';
+COMMENT ON COLUMN nexent.mcp_community_record_t.source IS 'Source type, fixed to community for this table';
+COMMENT ON COLUMN nexent.mcp_community_record_t.version IS 'MCP version';
+COMMENT ON COLUMN nexent.mcp_community_record_t.registry_json IS 'Full MCP server metadata JSON for discovery and quick import';
+COMMENT ON COLUMN nexent.mcp_community_record_t.transport_type IS 'Transport type: url/container';
+COMMENT ON COLUMN nexent.mcp_community_record_t.config_json IS 'Public-shareable MCP configuration JSON';
+COMMENT ON COLUMN nexent.mcp_community_record_t.tags IS 'Tags';
+COMMENT ON COLUMN nexent.mcp_community_record_t.description IS 'Description';
+COMMENT ON COLUMN nexent.mcp_community_record_t.create_time IS 'Creation time';
+COMMENT ON COLUMN nexent.mcp_community_record_t.update_time IS 'Update time';
+COMMENT ON COLUMN nexent.mcp_community_record_t.created_by IS 'Creator ID';
+COMMENT ON COLUMN nexent.mcp_community_record_t.updated_by IS 'Updater ID';
+COMMENT ON COLUMN nexent.mcp_community_record_t.delete_flag IS 'Soft delete flag: Y/N';
+
+CREATE INDEX IF NOT EXISTS idx_mcp_community_tenant_delete
+ ON nexent.mcp_community_record_t (tenant_id, delete_flag);
+
+CREATE INDEX IF NOT EXISTS idx_mcp_community_name_delete
+ ON nexent.mcp_community_record_t (mcp_name, delete_flag);
+
+CREATE INDEX IF NOT EXISTS idx_mcp_community_transport_delete
+ ON nexent.mcp_community_record_t (transport_type, delete_flag);
+
+CREATE INDEX IF NOT EXISTS idx_mcp_community_user_delete
+ ON nexent.mcp_community_record_t (user_id, delete_flag);
+
+CREATE INDEX IF NOT EXISTS idx_mcp_community_tags_gin
+ ON nexent.mcp_community_record_t USING GIN (tags);
+
+CREATE OR REPLACE FUNCTION update_mcp_community_record_update_time()
+RETURNS TRIGGER AS $$
+BEGIN
+ NEW.update_time = CURRENT_TIMESTAMP;
+ RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+COMMENT ON FUNCTION update_mcp_community_record_update_time() IS 'Auto-update update_time for mcp_community_record_t';
+
+DROP TRIGGER IF EXISTS update_mcp_community_record_update_time_trigger ON nexent.mcp_community_record_t;
+CREATE TRIGGER update_mcp_community_record_update_time_trigger
+BEFORE UPDATE ON nexent.mcp_community_record_t
+FOR EACH ROW
+EXECUTE FUNCTION update_mcp_community_record_update_time();
+
+COMMENT ON TRIGGER update_mcp_community_record_update_time_trigger ON nexent.mcp_community_record_t IS 'Trigger to maintain update_time';
+
+CREATE TABLE IF NOT EXISTS nexent.user_cas_session_t (
+ cas_session_id SERIAL PRIMARY KEY,
+ session_id VARCHAR(100) NOT NULL UNIQUE,
+ user_id VARCHAR(100) NOT NULL,
+ cas_user_id VARCHAR(200) NOT NULL,
+ cas_session_index VARCHAR(500),
+ status VARCHAR(30) NOT NULL DEFAULT 'active',
+ expires_at TIMESTAMP NOT NULL,
+ revoked_at TIMESTAMP,
+ create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+ update_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+ created_by VARCHAR(100),
+ updated_by VARCHAR(100),
+ delete_flag VARCHAR(1) DEFAULT 'N'
+);
+
+CREATE INDEX IF NOT EXISTS ix_user_cas_session_session_id
+ ON nexent.user_cas_session_t (session_id);
+CREATE INDEX IF NOT EXISTS ix_user_cas_session_user_id
+ ON nexent.user_cas_session_t (user_id);
+CREATE INDEX IF NOT EXISTS ix_user_cas_session_cas_user_id
+ ON nexent.user_cas_session_t (cas_user_id);
+
+COMMENT ON TABLE nexent.user_cas_session_t IS 'Server-side session records for CAS SSO login and logout synchronization';
+COMMENT ON COLUMN nexent.user_cas_session_t.session_id IS 'JWT sid claim for revocation checks';
+COMMENT ON COLUMN nexent.user_cas_session_t.cas_user_id IS 'User identifier returned by CAS';
+COMMENT ON COLUMN nexent.user_cas_session_t.cas_session_index IS 'CAS SessionIndex or service ticket';
diff --git a/docker/monitoring/grafana/dashboards/nexent-llm-agent.json b/docker/monitoring/grafana/dashboards/nexent-llm-agent.json
new file mode 100644
index 000000000..d4e2c321b
--- /dev/null
+++ b/docker/monitoring/grafana/dashboards/nexent-llm-agent.json
@@ -0,0 +1,150 @@
+{
+ "annotations": {
+ "list": [
+ {
+ "builtIn": 1,
+ "datasource": {
+ "type": "grafana",
+ "uid": "-- Grafana --"
+ },
+ "enable": true,
+ "hide": true,
+ "iconColor": "rgba(0, 211, 255, 1)",
+ "name": "Annotations & Alerts",
+ "type": "dashboard"
+ }
+ ]
+ },
+ "description": "Nexent Agent traces backed by Grafana Tempo.",
+ "editable": true,
+ "fiscalYearStartMonth": 0,
+ "graphTooltip": 0,
+ "id": null,
+ "links": [
+ {
+ "asDropdown": false,
+ "icon": "external link",
+ "includeVars": false,
+ "keepTime": true,
+ "tags": [],
+ "targetBlank": false,
+ "title": "Open Tempo Explore",
+ "tooltip": "Open Grafana Explore with the Tempo datasource",
+ "type": "link",
+ "url": "/explore?left=%7B%22datasource%22:%22Tempo%22,%22queries%22:%5B%7B%22refId%22:%22A%22,%22query%22:%22%7B%20resource.service.name%20%3D%20%5C%22nexent-backend%5C%22%20%7D%22,%22queryType%22:%22traceql%22%7D%5D%7D"
+ }
+ ],
+ "panels": [
+ {
+ "datasource": {
+ "type": "tempo",
+ "uid": "Tempo"
+ },
+ "description": "Recent traces for Nexent backend. Open a trace row to inspect the agent, chain, LLM, and tool span waterfall.",
+ "fieldConfig": {
+ "defaults": {
+ "custom": {
+ "align": "auto",
+ "cellOptions": {
+ "type": "auto"
+ },
+ "inspect": false
+ },
+ "mappings": [],
+ "thresholds": {
+ "mode": "absolute",
+ "steps": [
+ {
+ "color": "green",
+ "value": null
+ },
+ {
+ "color": "red",
+ "value": 80
+ }
+ ]
+ }
+ },
+ "overrides": []
+ },
+ "gridPos": {
+ "h": 16,
+ "w": 24,
+ "x": 0,
+ "y": 0
+ },
+ "id": 1,
+ "options": {
+ "cellHeight": "sm",
+ "footer": {
+ "countRows": false,
+ "fields": "",
+ "reducer": [
+ "sum"
+ ],
+ "show": false
+ },
+ "showHeader": true
+ },
+ "pluginVersion": "11.0.0",
+ "targets": [
+ {
+ "datasource": {
+ "type": "tempo",
+ "uid": "Tempo"
+ },
+ "limit": 100,
+ "query": "{ resource.service.name = \"nexent-backend\" }",
+ "queryType": "traceql",
+ "refId": "A",
+ "tableType": "traces"
+ }
+ ],
+ "title": "Recent Agent Traces",
+ "type": "table"
+ },
+ {
+ "description": "TraceQL shortcuts for common Nexent views.",
+ "gridPos": {
+ "h": 8,
+ "w": 24,
+ "x": 0,
+ "y": 16
+ },
+ "id": 2,
+ "options": {
+ "code": {
+ "language": "plaintext",
+ "showLineNumbers": false,
+ "showMiniMap": false
+ },
+ "content": "Service traces:\n{ resource.service.name = \"nexent-backend\" }\n\nAgent spans:\n{ resource.service.name = \"nexent-backend\" && span.openinference.span.kind = \"AGENT\" }\n\nLLM spans:\n{ resource.service.name = \"nexent-backend\" && span.openinference.span.kind = \"LLM\" }\n\nTool spans:\n{ resource.service.name = \"nexent-backend\" && span.openinference.span.kind = \"TOOL\" }\n\nError traces:\n{ resource.service.name = \"nexent-backend\" && status = error }",
+ "mode": "markdown"
+ },
+ "pluginVersion": "11.0.0",
+ "title": "TraceQL Examples",
+ "type": "text"
+ }
+ ],
+ "preload": false,
+ "refresh": "30s",
+ "schemaVersion": 39,
+ "tags": [
+ "nexent",
+ "agent",
+ "tempo"
+ ],
+ "templating": {
+ "list": []
+ },
+ "time": {
+ "from": "now-6h",
+ "to": "now"
+ },
+ "timepicker": {},
+ "timezone": "browser",
+ "title": "Nexent Agent Trace Monitoring",
+ "uid": "nexent-llm-agent",
+ "version": 1,
+ "weekStart": ""
+}
diff --git a/docker/monitoring/grafana/dashboards/nexent-llm-performance.json b/docker/monitoring/grafana/dashboards/nexent-llm-performance.json
deleted file mode 100644
index ec8d0434a..000000000
--- a/docker/monitoring/grafana/dashboards/nexent-llm-performance.json
+++ /dev/null
@@ -1,544 +0,0 @@
-{
- "annotations": {
- "list": [
- {
- "builtIn": 1,
- "datasource": {
- "type": "grafana",
- "uid": "-- Grafana --"
- },
- "enable": true,
- "hide": true,
- "iconColor": "rgba(0, 211, 255, 1)",
- "name": "Annotations & Alerts",
- "type": "dashboard"
- }
- ]
- },
- "editable": true,
- "fiscalYearStartMonth": 0,
- "graphTooltip": 0,
- "id": null,
- "links": [],
- "liveNow": false,
- "panels": [
- {
- "datasource": {
- "type": "prometheus",
- "uid": "prometheus"
- },
- "fieldConfig": {
- "defaults": {
- "color": {
- "mode": "palette-classic"
- },
- "custom": {
- "axisCenteredZero": false,
- "axisColorMode": "text",
- "axisLabel": "",
- "axisPlacement": "auto",
- "barAlignment": 0,
- "drawStyle": "line",
- "fillOpacity": 10,
- "gradientMode": "none",
- "hideFrom": {
- "legend": false,
- "tooltip": false,
- "vis": false
- },
- "lineInterpolation": "linear",
- "lineWidth": 1,
- "pointSize": 5,
- "scaleDistribution": {
- "type": "linear"
- },
- "showPoints": "never",
- "spanNulls": false,
- "stacking": {
- "group": "A",
- "mode": "none"
- },
- "thresholdsStyle": {
- "mode": "off"
- }
- },
- "mappings": [],
- "thresholds": {
- "mode": "absolute",
- "steps": [
- {
- "color": "green",
- "value": null
- },
- {
- "color": "red",
- "value": 80
- }
- ]
- },
- "unit": "s"
- },
- "overrides": []
- },
- "gridPos": {
- "h": 8,
- "w": 12,
- "x": 0,
- "y": 0
- },
- "id": 1,
- "options": {
- "legend": {
- "calcs": [],
- "displayMode": "list",
- "placement": "bottom",
- "showLegend": true
- },
- "tooltip": {
- "mode": "single",
- "sort": "none"
- }
- },
- "targets": [
- {
- "datasource": {
- "type": "prometheus",
- "uid": "prometheus"
- },
- "expr": "histogram_quantile(0.95, rate(llm_request_duration_seconds_bucket[5m]))",
- "interval": "",
- "legendFormat": "95th percentile",
- "refId": "A"
- },
- {
- "datasource": {
- "type": "prometheus",
- "uid": "prometheus"
- },
- "expr": "histogram_quantile(0.50, rate(llm_request_duration_seconds_bucket[5m]))",
- "interval": "",
- "legendFormat": "50th percentile (median)",
- "refId": "B"
- }
- ],
- "title": "LLM Request Duration",
- "type": "timeseries"
- },
- {
- "datasource": {
- "type": "prometheus",
- "uid": "prometheus"
- },
- "fieldConfig": {
- "defaults": {
- "color": {
- "mode": "palette-classic"
- },
- "custom": {
- "axisCenteredZero": false,
- "axisColorMode": "text",
- "axisLabel": "",
- "axisPlacement": "auto",
- "barAlignment": 0,
- "drawStyle": "line",
- "fillOpacity": 10,
- "gradientMode": "none",
- "hideFrom": {
- "legend": false,
- "tooltip": false,
- "vis": false
- },
- "lineInterpolation": "linear",
- "lineWidth": 1,
- "pointSize": 5,
- "scaleDistribution": {
- "type": "linear"
- },
- "showPoints": "never",
- "spanNulls": false,
- "stacking": {
- "group": "A",
- "mode": "none"
- },
- "thresholdsStyle": {
- "mode": "off"
- }
- },
- "mappings": [],
- "thresholds": {
- "mode": "absolute",
- "steps": [
- {
- "color": "green",
- "value": null
- },
- {
- "color": "red",
- "value": 80
- }
- ]
- },
- "unit": "tokens/s"
- },
- "overrides": []
- },
- "gridPos": {
- "h": 8,
- "w": 12,
- "x": 12,
- "y": 0
- },
- "id": 2,
- "options": {
- "legend": {
- "calcs": [],
- "displayMode": "list",
- "placement": "bottom",
- "showLegend": true
- },
- "tooltip": {
- "mode": "single",
- "sort": "none"
- }
- },
- "targets": [
- {
- "datasource": {
- "type": "prometheus",
- "uid": "prometheus"
- },
- "expr": "histogram_quantile(0.95, rate(llm_token_generation_rate_bucket[5m]))",
- "interval": "",
- "legendFormat": "95th percentile",
- "refId": "A"
- },
- {
- "datasource": {
- "type": "prometheus",
- "uid": "prometheus"
- },
- "expr": "histogram_quantile(0.50, rate(llm_token_generation_rate_bucket[5m]))",
- "interval": "",
- "legendFormat": "50th percentile (median)",
- "refId": "B"
- }
- ],
- "title": "Token Generation Rate",
- "type": "timeseries"
- },
- {
- "datasource": {
- "type": "prometheus",
- "uid": "prometheus"
- },
- "fieldConfig": {
- "defaults": {
- "color": {
- "mode": "palette-classic"
- },
- "custom": {
- "axisCenteredZero": false,
- "axisColorMode": "text",
- "axisLabel": "",
- "axisPlacement": "auto",
- "barAlignment": 0,
- "drawStyle": "line",
- "fillOpacity": 10,
- "gradientMode": "none",
- "hideFrom": {
- "legend": false,
- "tooltip": false,
- "vis": false
- },
- "lineInterpolation": "linear",
- "lineWidth": 1,
- "pointSize": 5,
- "scaleDistribution": {
- "type": "linear"
- },
- "showPoints": "never",
- "spanNulls": false,
- "stacking": {
- "group": "A",
- "mode": "none"
- },
- "thresholdsStyle": {
- "mode": "off"
- }
- },
- "mappings": [],
- "thresholds": {
- "mode": "absolute",
- "steps": [
- {
- "color": "green",
- "value": null
- },
- {
- "color": "red",
- "value": 80
- }
- ]
- },
- "unit": "s"
- },
- "overrides": []
- },
- "gridPos": {
- "h": 8,
- "w": 12,
- "x": 0,
- "y": 8
- },
- "id": 3,
- "options": {
- "legend": {
- "calcs": [],
- "displayMode": "list",
- "placement": "bottom",
- "showLegend": true
- },
- "tooltip": {
- "mode": "single",
- "sort": "none"
- }
- },
- "targets": [
- {
- "datasource": {
- "type": "prometheus",
- "uid": "prometheus"
- },
- "expr": "histogram_quantile(0.95, rate(llm_time_to_first_token_seconds_bucket[5m]))",
- "interval": "",
- "legendFormat": "95th percentile TTFT",
- "refId": "A"
- },
- {
- "datasource": {
- "type": "prometheus",
- "uid": "prometheus"
- },
- "expr": "histogram_quantile(0.50, rate(llm_time_to_first_token_seconds_bucket[5m]))",
- "interval": "",
- "legendFormat": "50th percentile TTFT",
- "refId": "B"
- }
- ],
- "title": "Time to First Token (TTFT)",
- "type": "timeseries"
- },
- {
- "datasource": {
- "type": "prometheus",
- "uid": "prometheus"
- },
- "fieldConfig": {
- "defaults": {
- "color": {
- "mode": "palette-classic"
- },
- "custom": {
- "axisCenteredZero": false,
- "axisColorMode": "text",
- "axisLabel": "",
- "axisPlacement": "auto",
- "barAlignment": 0,
- "drawStyle": "line",
- "fillOpacity": 10,
- "gradientMode": "none",
- "hideFrom": {
- "legend": false,
- "tooltip": false,
- "vis": false
- },
- "lineInterpolation": "linear",
- "lineWidth": 1,
- "pointSize": 5,
- "scaleDistribution": {
- "type": "linear"
- },
- "showPoints": "never",
- "spanNulls": false,
- "stacking": {
- "group": "A",
- "mode": "none"
- },
- "thresholdsStyle": {
- "mode": "off"
- }
- },
- "mappings": [],
- "thresholds": {
- "mode": "absolute",
- "steps": [
- {
- "color": "green",
- "value": null
- },
- {
- "color": "red",
- "value": 80
- }
- ]
- },
- "unit": "tokens"
- },
- "overrides": []
- },
- "gridPos": {
- "h": 8,
- "w": 12,
- "x": 12,
- "y": 8
- },
- "id": 4,
- "options": {
- "legend": {
- "calcs": [],
- "displayMode": "list",
- "placement": "bottom",
- "showLegend": true
- },
- "tooltip": {
- "mode": "single",
- "sort": "none"
- }
- },
- "targets": [
- {
- "datasource": {
- "type": "prometheus",
- "uid": "prometheus"
- },
- "expr": "rate(llm_total_tokens_total{type=\"input\"}[5m])",
- "interval": "",
- "legendFormat": "Input tokens/sec",
- "refId": "A"
- },
- {
- "datasource": {
- "type": "prometheus",
- "uid": "prometheus"
- },
- "expr": "rate(llm_total_tokens_total{type=\"output\"}[5m])",
- "interval": "",
- "legendFormat": "Output tokens/sec",
- "refId": "B"
- }
- ],
- "title": "Token Throughput",
- "type": "timeseries"
- },
- {
- "datasource": {
- "type": "prometheus",
- "uid": "prometheus"
- },
- "fieldConfig": {
- "defaults": {
- "color": {
- "mode": "palette-classic"
- },
- "custom": {
- "axisCenteredZero": false,
- "axisColorMode": "text",
- "axisLabel": "",
- "axisPlacement": "auto",
- "barAlignment": 0,
- "drawStyle": "line",
- "fillOpacity": 10,
- "gradientMode": "none",
- "hideFrom": {
- "legend": false,
- "tooltip": false,
- "vis": false
- },
- "lineInterpolation": "linear",
- "lineWidth": 1,
- "pointSize": 5,
- "scaleDistribution": {
- "type": "linear"
- },
- "showPoints": "never",
- "spanNulls": false,
- "stacking": {
- "group": "A",
- "mode": "none"
- },
- "thresholdsStyle": {
- "mode": "off"
- }
- },
- "mappings": [],
- "thresholds": {
- "mode": "absolute",
- "steps": [
- {
- "color": "green",
- "value": null
- },
- {
- "color": "red",
- "value": 80
- }
- ]
- },
- "unit": "errors/sec"
- },
- "overrides": []
- },
- "gridPos": {
- "h": 8,
- "w": 24,
- "x": 0,
- "y": 16
- },
- "id": 5,
- "options": {
- "legend": {
- "calcs": [],
- "displayMode": "list",
- "placement": "bottom",
- "showLegend": true
- },
- "tooltip": {
- "mode": "single",
- "sort": "none"
- }
- },
- "targets": [
- {
- "datasource": {
- "type": "prometheus",
- "uid": "prometheus"
- },
- "expr": "rate(llm_error_count_total[5m])",
- "interval": "",
- "legendFormat": "Error rate by model: {{model}}",
- "refId": "A"
- }
- ],
- "title": "LLM Error Rate",
- "type": "timeseries"
- }
- ],
- "refresh": "5s",
- "schemaVersion": 37,
- "style": "dark",
- "tags": ["nexent", "llm", "performance"],
- "templating": {
- "list": []
- },
- "time": {
- "from": "now-1h",
- "to": "now"
- },
- "timepicker": {},
- "timezone": "",
- "title": "Nexent LLM Performance Dashboard",
- "uid": "nexent-llm-perf",
- "version": 1,
- "weekStart": ""
-}
-
diff --git a/docker/monitoring/grafana/provisioning/dashboards/dashboards.yml b/docker/monitoring/grafana/provisioning/dashboards/dashboards.yml
index b89a1fa81..b863e9d16 100644
--- a/docker/monitoring/grafana/provisioning/dashboards/dashboards.yml
+++ b/docker/monitoring/grafana/provisioning/dashboards/dashboards.yml
@@ -1,13 +1,12 @@
apiVersion: 1
providers:
- - name: 'Nexent LLM Monitoring'
+ - name: Nexent Monitoring
orgId: 1
- folder: 'Nexent'
+ folder: Nexent
type: file
disableDeletion: false
- updateIntervalSeconds: 10
+ updateIntervalSeconds: 30
allowUiUpdates: true
options:
path: /var/lib/grafana/dashboards
-
diff --git a/docker/monitoring/grafana/provisioning/datasources/datasources.yml b/docker/monitoring/grafana/provisioning/datasources/datasources.yml
index 9bdc40d61..d23e4cba9 100644
--- a/docker/monitoring/grafana/provisioning/datasources/datasources.yml
+++ b/docker/monitoring/grafana/provisioning/datasources/datasources.yml
@@ -1,16 +1,23 @@
apiVersion: 1
datasources:
- - name: Prometheus
- type: prometheus
+ - name: Tempo
+ uid: Tempo
+ type: tempo
access: proxy
- url: http://prometheus:9090
+ url: http://nexent-tempo:3200
isDefault: true
editable: true
-
- - name: Jaeger
- type: jaeger
- access: proxy
- url: http://jaeger:16686
- editable: true
-
+ basicAuth: false
+ jsonData:
+ nodeGraph:
+ enabled: true
+ search:
+ hide: false
+ traceQuery:
+ timeShiftEnabled: true
+ spanStartTimeShift: "-1h"
+ spanEndTimeShift: "1h"
+ streamingEnabled:
+ search: false
+ metrics: false
diff --git a/docker/monitoring/monitoring.env b/docker/monitoring/monitoring.env
deleted file mode 100644
index 2506c03a6..000000000
--- a/docker/monitoring/monitoring.env
+++ /dev/null
@@ -1,21 +0,0 @@
-# Telemetry and Monitoring Configuration
-ENABLE_TELEMETRY=true
-SERVICE_NAME=nexent-backend
-JAEGER_ENDPOINT=http://localhost:14268/api/traces
-PROMETHEUS_PORT=8000
-TELEMETRY_SAMPLE_RATE=1.0
-
-# Performance monitoring thresholds
-LLM_SLOW_REQUEST_THRESHOLD_SECONDS=5.0
-LLM_SLOW_TOKEN_RATE_THRESHOLD=10.0
-
-# Grafana Configuration
-GF_SECURITY_ADMIN_PASSWORD=admin
-GF_USERS_ALLOW_SIGN_UP=false
-
-# Service ports
-JAEGER_UI_PORT=16686
-PROMETHEUS_UI_PORT=9090
-GRAFANA_UI_PORT=3000
-OTEL_COLLECTOR_GRPC_PORT=4317
-OTEL_COLLECTOR_HTTP_PORT=4318
diff --git a/docker/monitoring/monitoring.env.example b/docker/monitoring/monitoring.env.example
index 26ab041c8..17f75a3c9 100644
--- a/docker/monitoring/monitoring.env.example
+++ b/docker/monitoring/monitoring.env.example
@@ -1,22 +1,72 @@
-# Telemetry and Monitoring Configuration
-ENABLE_TELEMETRY=true
-SERVICE_NAME=nexent-backend
-JAEGER_ENDPOINT=http://localhost:14268/api/traces
-PROMETHEUS_PORT=8000
-TELEMETRY_SAMPLE_RATE=1.0
+# Monitoring stack selector for ./start-monitoring.sh.
+# Supported values: otlp, collector, phoenix, langfuse, langsmith, grafana, zipkin.
+MONITORING_PROVIDER=otlp
-# Performance monitoring thresholds
-LLM_SLOW_REQUEST_THRESHOLD_SECONDS=5.0
-LLM_SLOW_TOKEN_RATE_THRESHOLD=10.0
-
-# Grafana Configuration
-GF_SECURITY_ADMIN_PASSWORD=admin
-GF_USERS_ALLOW_SIGN_UP=false
-
-# Service ports
-JAEGER_UI_PORT=16686
-PROMETHEUS_UI_PORT=9090
-GRAFANA_UI_PORT=3000
OTEL_COLLECTOR_GRPC_PORT=4317
OTEL_COLLECTOR_HTTP_PORT=4318
+OTEL_COLLECTOR_CONFIG_FILE=
+OTEL_COLLECTOR_VERSION=0.151.0
+
+# Local Phoenix stack. Used by: ./start-monitoring.sh --stack phoenix
+PHOENIX_VERSION=15
+PHOENIX_PORT=6006
+PHOENIX_GRPC_HOST_PORT=4319
+
+# Local Langfuse stack. Used by: ./start-monitoring.sh --stack langfuse
+# Defaults are for local development only. Replace secrets before production use.
+LANGFUSE_VERSION=3
+LANGFUSE_PORT=3001
+LANGFUSE_NEXTAUTH_URL=http://localhost:3001
+LANGFUSE_NEXTAUTH_SECRET=nexent-langfuse-secret
+LANGFUSE_SALT=nexent-langfuse-salt
+LANGFUSE_ENCRYPTION_KEY=0000000000000000000000000000000000000000000000000000000000000000
+LANGFUSE_TELEMETRY_ENABLED=false
+LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES=false
+LANGFUSE_INIT_ORG_ID=nexent
+LANGFUSE_INIT_ORG_NAME=Nexent
+LANGFUSE_INIT_PROJECT_ID=nexent
+LANGFUSE_INIT_PROJECT_NAME=Nexent
+LANGFUSE_INIT_PROJECT_PUBLIC_KEY=pk-lf-nexent-local
+LANGFUSE_INIT_PROJECT_SECRET_KEY=sk-lf-nexent-local
+LANGFUSE_INIT_USER_EMAIL=admin@nexent.com
+LANGFUSE_INIT_USER_NAME=admin
+LANGFUSE_INIT_USER_PASSWORD=nexent@4321
+LANGFUSE_OTLP_AUTH_HEADER=
+LANGFUSE_POSTGRES_VERSION=15-alpine
+LANGFUSE_POSTGRES_USER=postgres
+LANGFUSE_POSTGRES_PASSWORD=nexent@4321
+LANGFUSE_POSTGRES_DB=postgres
+LANGFUSE_POSTGRES_PORT=5440
+LANGFUSE_CLICKHOUSE_VERSION=26.3-alpine
+LANGFUSE_CLICKHOUSE_USER=clickhouse
+LANGFUSE_CLICKHOUSE_PASSWORD=clickhouse
+LANGFUSE_CLICKHOUSE_HTTP_PORT=8124
+LANGFUSE_CLICKHOUSE_NATIVE_PORT=9002
+LANGFUSE_MINIO_VERSION=RELEASE.2023-12-20T01-00-02Z
+LANGFUSE_MINIO_ROOT_USER=minio
+LANGFUSE_MINIO_ROOT_PASSWORD=miniosecret
+LANGFUSE_MINIO_API_PORT=9092
+LANGFUSE_MINIO_CONSOLE_PORT=9093
+LANGFUSE_S3_BUCKET=langfuse
+LANGFUSE_REDIS_AUTH=myredissecret
+LANGFUSE_REDIS_VERSION=alpine
+LANGFUSE_REDIS_PORT=6380
+
+# Online LangSmith forwarding. Used by: ./start-monitoring.sh --stack langsmith
+# LangSmith currently ingests OTLP traces. Metrics remain in the Collector debug pipeline.
+LANGSMITH_API_KEY=
+LANGSMITH_PROJECT=nexent
+LANGSMITH_OTLP_TRACES_ENDPOINT=https://api.smith.langchain.com/otel/v1/traces
+
+# Local Grafana stack. Used by: ./start-monitoring.sh --stack grafana
+GRAFANA_VERSION=12.4
+GRAFANA_PORT=3002
+GRAFANA_ADMIN_USER=admin
+GRAFANA_ADMIN_PASSWORD=nexent@4321
+GRAFANA_DEFAULT_LANGUAGE=zh-Hans
+TEMPO_VERSION=2.10.5
+TEMPO_PORT=3200
+# Local Zipkin stack. Used by: ./start-monitoring.sh --stack zipkin
+ZIPKIN_VERSION=latest
+ZIPKIN_PORT=9411
diff --git a/docker/monitoring/otel-collector-config.yml b/docker/monitoring/otel-collector-config.yml
index f14f427b5..8d2332361 100644
--- a/docker/monitoring/otel-collector-config.yml
+++ b/docker/monitoring/otel-collector-config.yml
@@ -5,22 +5,16 @@ receivers:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
-
- # Prometheus receiver to collect metrics from instrumented apps
- prometheus:
- config:
- scrape_configs:
- - job_name: 'nexent-backend-otel'
- static_configs:
- - targets: ['host.docker.internal:8000']
- scrape_interval: 5s
processors:
batch:
timeout: 1s
send_batch_size: 512
-
- # Resource processor to add common attributes
+
+ memory_limiter:
+ limit_mib: 256
+ check_interval: 1s
+
resource:
attributes:
- key: service.name
@@ -30,51 +24,71 @@ processors:
from_attribute: version
action: insert
- # Memory limiter to prevent OOM
- memory_limiter:
- limit_mib: 256
- check_interval: 1s
-
- # Add attributes specifically for LLM monitoring
- attributes:
- actions:
- - key: llm.system
- value: openai
- action: insert
- - key: deployment.environment
- value: development
- action: insert
-
exporters:
- # Export traces to Jaeger via OTLP
- otlp/jaeger:
- endpoint: jaeger:14250
- tls:
- insecure: true
-
- # Export metrics to Prometheus
- prometheus:
- endpoint: "0.0.0.0:8889"
- resource_to_telemetry_conversion:
- enabled: true
-
- # Logging exporter for debugging
- logging:
+ debug:
verbosity: normal
service:
- extensions: []
pipelines:
traces:
receivers: [otlp]
processors: [memory_limiter, resource, batch]
- exporters: [otlp/jaeger, logging]
-
+ exporters: [debug]
+
metrics:
- receivers: [otlp, prometheus]
- processors: [memory_limiter, resource, attributes, batch]
- exporters: [prometheus, logging]
-
+ receivers: [otlp]
+ processors: [memory_limiter, resource, batch]
+ exporters: [debug]
+
telemetry:
logs:
level: "info"
+
+# Example configurations for AI observability platforms:
+#
+# === Arize Phoenix ===
+# Set environment variables:
+# OTEL_EXPORTER_OTLP_ENDPOINT=https://app.phoenix.arize.com/s/YOUR_SPACE
+# OTEL_EXPORTER_OTLP_AUTHORIZATION=Bearer YOUR_PHOENIX_API_KEY
+# OTEL_EXPORTER_OTLP_METRICS_ENABLED=false
+#
+# Or configure directly in exporters section:
+# otlphttp/arize:
+# endpoint: https://app.phoenix.arize.com/s/YOUR_SPACE
+# headers:
+# Authorization: Bearer YOUR_PHOENIX_API_KEY
+# Then add otlphttp/arize to the traces pipeline exporters.
+#
+# === Langfuse ===
+# Set environment variables:
+# OTEL_EXPORTER_OTLP_ENDPOINT=https://cloud.langfuse.com/api/public/otel
+# OTEL_EXPORTER_OTLP_AUTHORIZATION=Basic BASE64_ENCODED_KEY
+# OTEL_EXPORTER_OTLP_LANGFUSE_INGESTION_VERSION=4
+#
+# Where BASE64_ENCODED_KEY = base64(public_key:secret_key)
+#
+# Or configure directly:
+# otlphttp/langfuse:
+# endpoint: https://cloud.langfuse.com/api/public/otel
+# headers:
+# Authorization: Basic BASE64_ENCODED_KEY
+# x-langfuse-ingestion-version: "4"
+# Then add otlphttp/langfuse to the traces pipeline exporters.
+#
+# === LangSmith ===
+# Set environment variables:
+# LANGSMITH_API_KEY=lsv2_...
+# LANGSMITH_PROJECT=nexent
+#
+# Or configure directly:
+# otlphttp/langsmith:
+# traces_endpoint: https://api.smith.langchain.com/otel/v1/traces
+# headers:
+# x-api-key: YOUR_LANGSMITH_API_KEY
+# Langsmith-Project: nexent
+# Then add otlphttp/langsmith to the traces pipeline exporters.
+#
+# === Multiple Exporters ===
+# To export to multiple backends simultaneously, create multiple exporters
+# and add them to the pipelines:
+# exporters: [otlphttp/arize, otlphttp/langfuse, otlphttp/langsmith, debug]
diff --git a/docker/monitoring/otel-collector-grafana-config.yml b/docker/monitoring/otel-collector-grafana-config.yml
new file mode 100644
index 000000000..d69e69811
--- /dev/null
+++ b/docker/monitoring/otel-collector-grafana-config.yml
@@ -0,0 +1,50 @@
+receivers:
+ otlp:
+ protocols:
+ grpc:
+ endpoint: 0.0.0.0:4317
+ http:
+ endpoint: 0.0.0.0:4318
+
+processors:
+ batch:
+ timeout: 1s
+ send_batch_size: 512
+
+ memory_limiter:
+ limit_mib: 256
+ check_interval: 1s
+
+ resource:
+ attributes:
+ - key: service.name
+ value: nexent-backend
+ action: upsert
+ - key: service.version
+ from_attribute: version
+ action: insert
+
+exporters:
+ debug:
+ verbosity: normal
+
+ otlp/tempo:
+ endpoint: tempo:4317
+ tls:
+ insecure: true
+
+service:
+ pipelines:
+ traces:
+ receivers: [otlp]
+ processors: [memory_limiter, resource, batch]
+ exporters: [otlp/tempo, debug]
+
+ metrics:
+ receivers: [otlp]
+ processors: [memory_limiter, resource, batch]
+ exporters: [debug]
+
+ telemetry:
+ logs:
+ level: "info"
diff --git a/docker/monitoring/otel-collector-langfuse-config.yml b/docker/monitoring/otel-collector-langfuse-config.yml
new file mode 100644
index 000000000..9304d93e9
--- /dev/null
+++ b/docker/monitoring/otel-collector-langfuse-config.yml
@@ -0,0 +1,69 @@
+receivers:
+ otlp:
+ protocols:
+ grpc:
+ endpoint: 0.0.0.0:4317
+ http:
+ endpoint: 0.0.0.0:4318
+
+processors:
+ batch:
+ timeout: 1s
+ send_batch_size: 512
+
+ memory_limiter:
+ limit_mib: 256
+ check_interval: 1s
+
+ resource:
+ attributes:
+ - key: service.name
+ value: nexent-backend
+ action: upsert
+ - key: service.version
+ from_attribute: version
+ action: insert
+
+exporters:
+ debug:
+ verbosity: normal
+
+ otlphttp/langfuse:
+ endpoint: http://langfuse-web:3000/api/public/otel
+ headers:
+ Authorization: ${env:LANGFUSE_OTLP_AUTH_HEADER}
+ x-langfuse-ingestion-version: "4"
+ # 1. 超时控制 (Timeout)
+ # 防止 Collector 等待太久导致协程暴涨
+ timeout: 5s
+
+ # 2. 发送队列 (Sending Queue)
+ # 当后端处理变慢时，把数据先缓存在 Collector 内存中
+ sending_queue:
+ enabled: true
+ num_consumers: 10 # 并发发送的工作线程数（可提升发送吞吐量）
+ queue_size: 5000 # 队列最大可容纳的批次数。如果队列满了，新来的数据将被丢弃！
+
+ # 3. 失败重试 (Retry on Failure)
+ # 遇到网络抖动或后端返回 503 等临时性错误时，进行指数退避重试
+ retry_on_failure:
+ enabled: true
+ initial_interval: 1s # 第一次重试间隔 1s
+ max_interval: 30s # 最大重试间隔不超过 30s
+ max_elapsed_time: 300s # 一条数据最多重试 5 分钟，超过则彻底放弃并丢弃
+
+service:
+ pipelines:
+ traces:
+ receivers: [otlp]
+ processors: [memory_limiter, resource, batch]
+ exporters: [otlphttp/langfuse, debug]
+
+ metrics:
+ receivers: [otlp]
+ processors: [memory_limiter, resource, batch]
+ exporters: [debug]
+
+ telemetry:
+ logs:
+ level: "info"
diff --git a/docker/monitoring/otel-collector-langsmith-config.yml b/docker/monitoring/otel-collector-langsmith-config.yml
new file mode 100644
index 000000000..28222c1cf
--- /dev/null
+++ b/docker/monitoring/otel-collector-langsmith-config.yml
@@ -0,0 +1,63 @@
+receivers:
+ otlp:
+ protocols:
+ grpc:
+ endpoint: 0.0.0.0:4317
+ http:
+ endpoint: 0.0.0.0:4318
+
+processors:
+ batch:
+ timeout: 1s
+ send_batch_size: 512
+
+ memory_limiter:
+ limit_mib: 256
+ check_interval: 1s
+
+ resource:
+ attributes:
+ - key: service.name
+ value: nexent-backend
+ action: upsert
+ - key: service.version
+ from_attribute: version
+ action: insert
+
+exporters:
+ debug:
+ verbosity: normal
+
+ otlphttp/langsmith:
+ traces_endpoint: ${env:LANGSMITH_OTLP_TRACES_ENDPOINT}
+ headers:
+ x-api-key: ${env:LANGSMITH_API_KEY}
+ Langsmith-Project: ${env:LANGSMITH_PROJECT}
+ timeout: 10s
+
+ sending_queue:
+ enabled: true
+ num_consumers: 10
+ queue_size: 5000
+
+ retry_on_failure:
+ enabled: true
+ initial_interval: 1s
+ max_interval: 30s
+ max_elapsed_time: 300s
+
+service:
+ pipelines:
+ traces:
+ receivers: [otlp]
+ processors: [memory_limiter, resource, batch]
+ exporters: [otlphttp/langsmith, debug]
+
+ metrics:
+ receivers: [otlp]
+ processors: [memory_limiter, resource, batch]
+ exporters: [debug]
+
+ telemetry:
+ logs:
+ level: "info"
diff --git a/docker/monitoring/otel-collector-phoenix-config.yml b/docker/monitoring/otel-collector-phoenix-config.yml
new file mode 100644
index 000000000..0682a6e4d
--- /dev/null
+++ b/docker/monitoring/otel-collector-phoenix-config.yml
@@ -0,0 +1,66 @@
+receivers:
+ otlp:
+ protocols:
+ grpc:
+ endpoint: 0.0.0.0:4317
+ http:
+ endpoint: 0.0.0.0:4318
+
+processors:
+ batch:
+ timeout: 1s
+ send_batch_size: 512
+
+ memory_limiter:
+ limit_mib: 256
+ check_interval: 1s
+
+ resource:
+ attributes:
+ - key: service.name
+ value: nexent-backend
+ action: upsert
+ - key: service.version
+ from_attribute: version
+ action: insert
+
+exporters:
+ debug:
+ verbosity: normal
+
+ otlphttp/phoenix:
+ endpoint: http://phoenix:6006
+ # 1. 超时控制 (Timeout)
+ # 防止 Collector 等待太久导致协程暴涨
+ timeout: 5s
+
+ # 2. 发送队列 (Sending Queue)
+ # 当后端处理变慢时，把数据先缓存在 Collector 内存中
+ sending_queue:
+ enabled: true
+ num_consumers: 10 # 并发发送的工作线程数（可提升发送吞吐量）
+ queue_size: 5000 # 队列最大可容纳的批次数。如果队列满了，新来的数据将被丢弃！
+
+ # 3. 失败重试 (Retry on Failure)
+ # 遇到网络抖动或后端返回 503 等临时性错误时，进行指数退避重试
+ retry_on_failure:
+ enabled: true
+ initial_interval: 1s # 第一次重试间隔 1s
+ max_interval: 30s # 最大重试间隔不超过 30s
+ max_elapsed_time: 300s # 一条数据最多重试 5 分钟，超过则彻底放弃并丢弃
+
+service:
+ pipelines:
+ traces:
+ receivers: [otlp]
+ processors: [memory_limiter, resource, batch]
+ exporters: [otlphttp/phoenix, debug]
+
+ metrics:
+ receivers: [otlp]
+ processors: [memory_limiter, resource, batch]
+ exporters: [debug]
+
+ telemetry:
+ logs:
+ level: "info"
diff --git a/docker/monitoring/otel-collector-zipkin-config.yml b/docker/monitoring/otel-collector-zipkin-config.yml
new file mode 100644
index 000000000..ab26a84a9
--- /dev/null
+++ b/docker/monitoring/otel-collector-zipkin-config.yml
@@ -0,0 +1,49 @@
+receivers:
+ otlp:
+ protocols:
+ grpc:
+ endpoint: 0.0.0.0:4317
+ http:
+ endpoint: 0.0.0.0:4318
+
+processors:
+ batch:
+ timeout: 1s
+ send_batch_size: 512
+
+ memory_limiter:
+ limit_mib: 256
+ check_interval: 1s
+
+ resource:
+ attributes:
+ - key: service.name
+ value: nexent-backend
+ action: upsert
+ - key: service.version
+ from_attribute: version
+ action: insert
+
+exporters:
+ debug:
+ verbosity: normal
+
+ zipkin:
+ endpoint: http://zipkin:9411/api/v2/spans
+ format: proto
+
+service:
+ pipelines:
+ traces:
+ receivers: [otlp]
+ processors: [memory_limiter, resource, batch]
+ exporters: [zipkin, debug]
+
+ metrics:
+ receivers: [otlp]
+ processors: [memory_limiter, resource, batch]
+ exporters: [debug]
+
+ telemetry:
+ logs:
+ level: "info"
\ No newline at end of file
diff --git a/docker/monitoring/prometheus.yml b/docker/monitoring/prometheus.yml
deleted file mode 100644
index 49258c097..000000000
--- a/docker/monitoring/prometheus.yml
+++ /dev/null
@@ -1,39 +0,0 @@
-global:
- scrape_interval: 15s
- evaluation_interval: 15s
-
-rule_files:
- # Load rules once and periodically evaluate them according to the global 'evaluation_interval'.
- - "nexent_alerts.yml"
-
-scrape_configs:
- # Nexent Backend - LLM Metrics
- - job_name: 'nexent-backend'
- static_configs:
- - targets: ['host.docker.internal:8000'] # Adjust based on your backend service
- scrape_interval: 15s
- metrics_path: /metrics
- scrape_timeout: 10s
-
- # OpenTelemetry Collector
- - job_name: 'otel-collector'
- static_configs:
- - targets: ['otel-collector:8888']
- scrape_interval: 10s
-
- # Prometheus self-monitoring
- - job_name: 'prometheus'
- static_configs:
- - targets: ['localhost:9090']
-
- # Jaeger Metrics
- - job_name: 'jaeger'
- static_configs:
- - targets: ['jaeger:14269']
-
-# Alertmanager configuration (optional)
-# alerting:
-# alertmanagers:
-# - static_configs:
-# - targets:
-# - alertmanager:9093
diff --git a/docker/monitoring/tempo.yml b/docker/monitoring/tempo.yml
new file mode 100644
index 000000000..414ea42b9
--- /dev/null
+++ b/docker/monitoring/tempo.yml
@@ -0,0 +1,43 @@
+target: all
+multitenancy_enabled: false
+stream_over_http_enabled: true
+
+server:
+ http_listen_port: 3200
+
+distributor:
+ receivers:
+ otlp:
+ protocols:
+ grpc:
+ endpoint: 0.0.0.0:4317
+ http:
+ endpoint: 0.0.0.0:4318
+
+metrics_generator:
+ ring:
+ kvstore:
+ store: inmemory
+ storage:
+ path: /var/tempo/generator/wal
+ remote_write: []
+ traces_storage:
+ path: /var/tempo/generator/traces
+ processor:
+ local_blocks:
+ filter_server_spans: false
+ flush_to_storage: true
+
+storage:
+ trace:
+ backend: local
+ wal:
+ path: /var/tempo/wal
+ local:
+ path: /var/tempo/blocks
+
+overrides:
+ defaults:
+ metrics_generator:
+ processors:
+ - local-blocks
diff --git a/docker/official-skills-zip/analyze-image.zip b/docker/official-skills-zip/analyze-image.zip
new file mode 100644
index 000000000..9ec4c2fb1
Binary files /dev/null and b/docker/official-skills-zip/analyze-image.zip differ
diff --git a/docker/official-skills-zip/analyze-text-file.zip b/docker/official-skills-zip/analyze-text-file.zip
new file mode 100644
index 000000000..8c4478872
Binary files /dev/null and b/docker/official-skills-zip/analyze-text-file.zip differ
diff --git a/docker/official-skills-zip/create-docx.zip b/docker/official-skills-zip/create-docx.zip
new file mode 100644
index 000000000..aa53e82b0
Binary files /dev/null and b/docker/official-skills-zip/create-docx.zip differ
diff --git a/docker/official-skills-zip/create-file-directory.zip b/docker/official-skills-zip/create-file-directory.zip
new file mode 100644
index 000000000..1e2d21ef0
Binary files /dev/null and b/docker/official-skills-zip/create-file-directory.zip differ
diff --git a/docker/official-skills-zip/delete-file-directory.zip b/docker/official-skills-zip/delete-file-directory.zip
new file mode 100644
index 000000000..0f0067d02
Binary files /dev/null and b/docker/official-skills-zip/delete-file-directory.zip differ
diff --git a/docker/official-skills-zip/email-utils.zip b/docker/official-skills-zip/email-utils.zip
new file mode 100644
index 000000000..c708a252c
Binary files /dev/null and b/docker/official-skills-zip/email-utils.zip differ
diff --git a/docker/official-skills-zip/list-directory.zip b/docker/official-skills-zip/list-directory.zip
new file mode 100644
index 000000000..e3eaeba27
Binary files /dev/null and b/docker/official-skills-zip/list-directory.zip differ
diff --git a/docker/official-skills-zip/move-file-directory.zip b/docker/official-skills-zip/move-file-directory.zip
new file mode 100644
index 000000000..d01897231
Binary files /dev/null and b/docker/official-skills-zip/move-file-directory.zip differ
diff --git a/docker/official-skills-zip/read-file.zip b/docker/official-skills-zip/read-file.zip
new file mode 100644
index 000000000..b394c2b38
Binary files /dev/null and b/docker/official-skills-zip/read-file.zip differ
diff --git a/docker/official-skills-zip/run-shell-ssh.zip b/docker/official-skills-zip/run-shell-ssh.zip
new file mode 100644
index 000000000..868eee7c5
Binary files /dev/null and b/docker/official-skills-zip/run-shell-ssh.zip differ
diff --git a/docker/official-skills-zip/search-datamate.zip b/docker/official-skills-zip/search-datamate.zip
new file mode 100644
index 000000000..0cb18ded6
Binary files /dev/null and b/docker/official-skills-zip/search-datamate.zip differ
diff --git a/docker/official-skills-zip/search-dify.zip b/docker/official-skills-zip/search-dify.zip
new file mode 100644
index 000000000..2bd7c8ccf
Binary files /dev/null and b/docker/official-skills-zip/search-dify.zip differ
diff --git a/docker/official-skills-zip/search-idata.zip b/docker/official-skills-zip/search-idata.zip
new file mode 100644
index 000000000..85a7e1b72
Binary files /dev/null and b/docker/official-skills-zip/search-idata.zip differ
diff --git a/docker/official-skills-zip/search-knowledge-base.zip b/docker/official-skills-zip/search-knowledge-base.zip
new file mode 100644
index 000000000..48fabec2a
Binary files /dev/null and b/docker/official-skills-zip/search-knowledge-base.zip differ
diff --git a/docker/official-skills-zip/search-web-exa.zip b/docker/official-skills-zip/search-web-exa.zip
new file mode 100644
index 000000000..19c209588
Binary files /dev/null and b/docker/official-skills-zip/search-web-exa.zip differ
diff --git a/docker/official-skills-zip/search-web-linkup.zip b/docker/official-skills-zip/search-web-linkup.zip
new file mode 100644
index 000000000..4657bc165
Binary files /dev/null and b/docker/official-skills-zip/search-web-linkup.zip differ
diff --git a/docker/official-skills-zip/search-web-tavily.zip b/docker/official-skills-zip/search-web-tavily.zip
new file mode 100644
index 000000000..628f73ef6
Binary files /dev/null and b/docker/official-skills-zip/search-web-tavily.zip differ
diff --git a/docker/scripts/sync_skill_directory.py b/docker/scripts/sync_skill_directory.py
new file mode 100644
index 000000000..d5819d251
--- /dev/null
+++ b/docker/scripts/sync_skill_directory.py
@@ -0,0 +1,659 @@
+#!/usr/bin/env python3
+"""
+Skills Directory Migration Script for v2.2.0 upgrade.
+
+This script migrates skills from the legacy flat directory structure to
+tenant-isolated directories.
+
+Migration:
+ FROM: ${ROOT_DIR}/skills/ (flat directory, skills directly under skills/)
+ TO: ${ROOT_DIR}/skills/{tenant_id}/
+
+The tenant_id is determined by querying user_tenant_t for the first record
+where user_role = 'ADMIN'.
+
+Usage (run on host machine):
+ python sync_skill_directory.py [--dry-run]
+
+Options:
+ --dry-run: Show what would be migrated without making changes
+ --verbose: Enable verbose debug output
+"""
+
+import os
+import sys
+import argparse
+import logging
+import shutil
+import subprocess
+import base64
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+# Setup logging
+logging.basicConfig(
+ level=logging.INFO,
+ format='%(asctime)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+# Constants
+CONTAINER_NAME = "nexent-config"
+DEFAULT_TENANT_ID = "tenant_id"
+
+
+def get_env(key: str, default: str = "") -> str:
+ """Get environment variable with optional default."""
+ return os.environ.get(key, default)
+
+
+def load_environment_from_host():
+ """
+ Load environment variables from host .env file.
+ Looks for .env in the same directory as this script's parent (docker/).
+ """
+ script_dir = Path(__file__).resolve().parent
+ docker_dir = script_dir.parent
+ env_file = docker_dir / ".env"
+
+ if env_file.is_file():
+ logger.info(f"Loading environment from: {env_file}")
+ with open(env_file, 'r') as f:
+ for line in f:
+ line = line.strip()
+ if line and not line.startswith('#') and '=' in line:
+ key, _, value = line.partition('=')
+ key = key.strip()
+ value = value.strip().strip('"').strip("'")
+ if key and key not in os.environ:
+ os.environ[key] = value
+ return True
+ else:
+ logger.warning(f".env file not found at: {env_file}")
+ logger.info("Will use existing environment variables or defaults")
+ return False
+
+
+def get_root_dir() -> str:
+ """Get ROOT_DIR from environment, normalized for the current OS."""
+ root_dir = get_env("ROOT_DIR")
+ if not root_dir:
+ script_dir = Path(__file__).resolve().parent
+ docker_dir = script_dir.parent
+ env_file = docker_dir / ".env"
+ if env_file.is_file():
+ with open(env_file, 'r') as f:
+ for line in f:
+ if line.startswith("ROOT_DIR="):
+ root_dir = line.split("=", 1)[1].strip().strip('"').strip("'")
+ break
+
+ # Normalize path separators for current OS
+ if root_dir:
+ root_dir = str(Path(root_dir))
+ return root_dir
+
+
+def check_container_running():
+ """Check if nexent-config container is running."""
+ try:
+ result = subprocess.run(
+ ['docker', 'ps', '--format', '{{.Names}}'],
+ capture_output=True,
+ text=True,
+ timeout=10
+ )
+
+ if result.returncode == 0:
+ containers = result.stdout.strip().split('\n')
+ if CONTAINER_NAME in containers:
+ logger.info(f"Container '{CONTAINER_NAME}' is running")
+ return True
+ else:
+ logger.error(f"Container '{CONTAINER_NAME}' is not running")
+ logger.info("Please start the containers with: cd docker && docker compose up -d")
+ return False
+ else:
+ logger.error("Could not query Docker containers")
+ return False
+ except FileNotFoundError:
+ logger.error("Docker not available on this system")
+ return False
+ except Exception as e:
+ logger.error(f"Error checking Docker containers: {e}")
+ return False
+
+
+def exec_python_in_container(python_code: str) -> tuple:
+ """
+ Execute Python code inside the container using base64 encoding.
+
+ This approach avoids shell escaping issues by encoding the Python code
+ as base64 and decoding it inside the container.
+
+ Args:
+ python_code: Python code to execute inside the container
+
+ Returns:
+ Tuple of (return_code, stdout, stderr)
+ """
+ # Encode Python code as base64
+ encoded = base64.b64encode(python_code.encode('utf-8')).decode('ascii')
+
+ # Create the shell command that decodes and executes the Python code
+ shell_cmd = f'python3 -c "import base64, sys; exec(base64.b64decode(sys.stdin.read()).decode(\'utf-8\'))"'
+
+ try:
+ # Use stdin for the base64 data
+ full_cmd = ['docker', 'exec', '-i', CONTAINER_NAME, 'sh', '-c', shell_cmd]
+ result = subprocess.run(
+ full_cmd,
+ input=encoded,
+ capture_output=True,
+ text=True,
+ timeout=30
+ )
+ return result.returncode, result.stdout, result.stderr
+ except subprocess.TimeoutExpired:
+ logger.error("Command timed out")
+ return -1, "", "Command timed out"
+ except Exception as e:
+ logger.error(f"Failed to execute command in container: {e}")
+ return -1, "", str(e)
+
+
+def test_postgres_connection_in_container() -> bool:
+ """
+ Test PostgreSQL connection from inside the container using Python.
+
+ Returns:
+ True if connection successful, False otherwise
+ """
+ logger.info("Testing PostgreSQL connection from inside container...")
+
+ python_code = '''
+import os
+import sys
+try:
+ import psycopg2
+ conn = psycopg2.connect(
+ host=os.getenv('POSTGRES_HOST', 'nexent-postgresql'),
+ port=os.getenv('POSTGRES_PORT', '5432'),
+ database=os.getenv('POSTGRES_DB', 'nexent'),
+ user=os.getenv('POSTGRES_USER', 'nexent'),
+ password=os.getenv('NEXENT_POSTGRES_PASSWORD', '')
+ )
+ conn.close()
+ print("Connection successful")
+ sys.exit(0)
+except Exception as e:
+ print(f"Connection failed: {e}", file=sys.stderr)
+ sys.exit(1)
+'''
+
+ returncode, stdout, stderr = exec_python_in_container(python_code)
+
+ if returncode == 0:
+ logger.info("PostgreSQL connection test: SUCCESS")
+ return True
+ else:
+ logger.warning(f"PostgreSQL connection test failed: {stderr.strip()}")
+ return False
+
+
+def get_admin_tenant_id_in_container() -> Optional[str]:
+ """
+ Get tenant_id from the first user_tenant_t record where user_role = 'ADMIN'.
+
+ Executes the query inside the container using Python.
+
+ Returns:
+ tenant_id string or None if not found
+ """
+ logger.info("Querying admin tenant_id from inside container...")
+
+ python_code = '''
+import os
+import sys
+
+try:
+ import psycopg2
+
+ conn = psycopg2.connect(
+ host=os.getenv('POSTGRES_HOST', 'nexent-postgresql'),
+ port=os.getenv('POSTGRES_PORT', '5432'),
+ database=os.getenv('POSTGRES_DB', 'nexent'),
+ user=os.getenv('POSTGRES_USER', 'nexent'),
+ password=os.getenv('NEXENT_POSTGRES_PASSWORD', '')
+ )
+
+ cur = conn.cursor()
+ cur.execute("""
+ SELECT tenant_id
+ FROM nexent.user_tenant_t
+ WHERE user_role = 'ADMIN'
+ AND delete_flag = 'N'
+ AND tenant_id IS NOT NULL
+ AND tenant_id != ''
+ ORDER BY user_tenant_id ASC
+ LIMIT 1
+ """)
+
+ result = cur.fetchone()
+ cur.close()
+ conn.close()
+
+ if result:
+ print(result[0])
+ sys.exit(0)
+ else:
+ print("No ADMIN user found", file=sys.stderr)
+ sys.exit(1)
+
+except Exception as e:
+ print(f"Query failed: {e}", file=sys.stderr)
+ sys.exit(1)
+'''
+
+ returncode, stdout, stderr = exec_python_in_container(python_code)
+
+ if returncode == 0:
+ tenant_id = stdout.strip()
+ if tenant_id:
+ logger.info(f"Found ADMIN tenant_id: {tenant_id}")
+ return tenant_id
+ else:
+ logger.warning("No user with user_role='ADMIN' found in user_tenant_t")
+ return None
+ else:
+ logger.error(f"Failed to query admin tenant_id: {stderr.strip()}")
+ return None
+
+
+def discover_legacy_skills_dir(root_dir: str) -> str:
+ """
+ Discover the legacy skills directory.
+
+ The legacy skills are located in the old nexent folder (sibling to nexent-data).
+ The new skills base is under {root_dir}/skills/{tenant_id}.
+
+ Legacy path: {root_dir}/../nexent/skills (old nexent folder)
+ New base: {root_dir}/skills
+
+ Returns:
+ Path to the legacy skills directory (normalized for current OS)
+ """
+ candidates = []
+ if root_dir:
+ # Legacy path FIRST: check old nexent folder (nexent-data's sibling)
+ # This is the actual source of legacy skills
+ root_path = Path(root_dir)
+ legacy_candidate = root_path.parent / "nexent" / "skills"
+ candidates.append(str(legacy_candidate))
+ # New base path (NOT the legacy, this is the destination base)
+ candidates.append(str(Path(root_dir) / "skills"))
+ candidates.append("skills")
+ candidates.append("./skills")
+
+ for candidate in candidates:
+ if Path(candidate).is_dir():
+ logger.info(f"Found legacy skills directory: {candidate}")
+ return candidate
+
+ logger.warning("Could not find legacy skills directory")
+ return candidates[0] if candidates[0] else "skills"
+
+
+def discover_skill_directories(skills_path: str) -> list:
+ """
+ List all skill directories under the given base path.
+
+ A valid skill directory contains at least a SKILL.md file.
+
+ Args:
+ skills_path: Base skills directory path
+
+ Returns:
+ List of skill directory names (not full paths)
+ """
+ skills_path_obj = Path(skills_path)
+ if not skills_path_obj.is_dir():
+ logger.warning(f"Skills directory does not exist: {skills_path}")
+ return []
+
+ skills = []
+ try:
+ for item in skills_path_obj.iterdir():
+ if item.is_dir():
+ if (item / "SKILL.md").is_file():
+ skills.append(item.name)
+ else:
+ logger.debug(f"Skipping non-skill directory: {item.name}")
+ except Exception as e:
+ logger.error(f"Error listing skills directory: {e}")
+
+ return skills
+
+
+def validate_skill_directory(skill_dir: str) -> dict:
+ """
+ Validate a skill directory structure.
+
+ Args:
+ skill_dir: Path to the skill directory
+
+ Returns:
+ Dict with validation results
+ """
+ skill_dir_obj = Path(skill_dir)
+ result = {
+ "is_valid": True,
+ "skill_name": skill_dir_obj.name,
+ "files": [],
+ "errors": []
+ }
+
+ if not skill_dir_obj.is_dir():
+ result["is_valid"] = False
+ result["errors"].append("Directory does not exist")
+ return result
+
+ skill_md = skill_dir_obj / "SKILL.md"
+ if not skill_md.is_file():
+ result["is_valid"] = False
+ result["errors"].append("SKILL.md not found")
+
+ try:
+ for item in skill_dir_obj.rglob('*'):
+ if item.is_file():
+ rel_path = item.relative_to(skill_dir_obj)
+ result["files"].append(str(rel_path))
+ except Exception as e:
+ result["errors"].append(f"Error scanning files: {e}")
+
+ return result
+
+
+def migrate_skills(
+ legacy_dir: str,
+ target_dir: str,
+ skills: list,
+ dry_run: bool = False
+) -> dict:
+ """
+ Migrate skills from legacy directory to target directory.
+
+ Args:
+ legacy_dir: Source directory path (host path)
+ target_dir: Target directory path (host path)
+ skills: List of skill names to migrate
+ dry_run: If True, only show what would be done
+
+ Returns:
+ Migration results dict
+ """
+ results = {
+ "total": len(skills),
+ "migrated": 0,
+ "skipped": 0,
+ "failed": 0,
+ "details": []
+ }
+
+ legacy_dir_obj = Path(legacy_dir)
+ target_dir_obj = Path(target_dir)
+
+ for skill_name in skills:
+ source = legacy_dir_obj / skill_name
+ target = target_dir_obj / skill_name
+
+ logger.info(f"Processing skill: {skill_name}")
+
+ validation = validate_skill_directory(str(source))
+ if not validation["is_valid"]:
+ logger.warning(f" Invalid skill directory: {', '.join(validation['errors'])}")
+ results["skipped"] += 1
+ results["details"].append({
+ "skill": skill_name,
+ "status": "skipped",
+ "reason": f"Validation failed: {', '.join(validation['errors'])}"
+ })
+ continue
+
+ if target.exists():
+ logger.info(f" Target already exists, skipping: {target}")
+ results["skipped"] += 1
+ results["details"].append({
+ "skill": skill_name,
+ "status": "skipped",
+ "reason": "Already exists in target directory"
+ })
+ continue
+
+ if dry_run:
+ logger.info(f" [DRY-RUN] Would migrate to: {target}")
+ logger.info(f" Files: {', '.join(validation['files'])}")
+ results["migrated"] += 1
+ results["details"].append({
+ "skill": skill_name,
+ "status": "dry-run",
+ "source": str(source),
+ "target": str(target),
+ "files_count": len(validation["files"])
+ })
+ else:
+ try:
+ target.mkdir(parents=True, exist_ok=True)
+
+ for item in source.rglob('*'):
+ if item.is_file():
+ rel_path = item.relative_to(source)
+ dst_file = target / rel_path
+ dst_file.parent.mkdir(parents=True, exist_ok=True)
+ shutil.copy2(item, dst_file)
+
+ logger.info(f" Migrated successfully: {len(validation['files'])} files")
+ results["migrated"] += 1
+ results["details"].append({
+ "skill": skill_name,
+ "status": "success",
+ "source": str(source),
+ "target": str(target),
+ "files_count": len(validation["files"])
+ })
+
+ except Exception as e:
+ logger.error(f" Failed to migrate: {e}")
+ results["failed"] += 1
+ results["details"].append({
+ "skill": skill_name,
+ "status": "failed",
+ "reason": str(e)
+ })
+
+ return results
+
+
+def print_results(results: dict):
+ """Print migration results summary."""
+ logger.info("=" * 60)
+ logger.info("Migration Results:")
+ logger.info(f" Total skills found: {results['total']}")
+ logger.info(f" Migrated: {results['migrated']}")
+ logger.info(f" Skipped: {results['skipped']}")
+ logger.info(f" Failed: {results['failed']}")
+ logger.info("=" * 60)
+
+ if results['details']:
+ logger.info("\nDetails:")
+ for detail in results['details']:
+ status = detail['status']
+ skill = detail['skill']
+ if status == 'success':
+ logger.info(f" [OK] {skill}: {detail.get('files_count', 0)} files -> {detail.get('target', 'N/A')}")
+ elif status == 'dry-run':
+ logger.info(f" [DRY-RUN] {skill}: would migrate {detail.get('files_count', 0)} files to {detail.get('target', 'N/A')}")
+ elif status == 'skipped':
+ logger.info(f" [SKIP] {skill}: {detail.get('reason', 'unknown reason')}")
+ else:
+ logger.info(f" [FAIL] {skill}: {detail.get('reason', 'unknown error')}")
+
+
+def main():
+ """Main function."""
+ parser = argparse.ArgumentParser(
+ description='Migrate skills directory for v2.2.0 upgrade (run on host)'
+ )
+ parser.add_argument(
+ '--dry-run',
+ action='store_true',
+ help='Show what would be migrated without making changes'
+ )
+ parser.add_argument(
+ '--verbose',
+ action='store_true',
+ help='Enable verbose debug output'
+ )
+ parser.add_argument(
+ '--legacy-dir',
+ type=str,
+ default=None,
+ help='Override legacy skills directory path (host path)'
+ )
+ parser.add_argument(
+ '--target-dir',
+ type=str,
+ default=None,
+ help='Override target skills directory path (host path)'
+ )
+ parser.add_argument(
+ '--skip-db',
+ action='store_true',
+ help='Skip database connection and use existing tenant directories'
+ )
+ args = parser.parse_args()
+
+ if args.verbose:
+ logging.getLogger().setLevel(logging.DEBUG)
+
+ logger.info("=" * 60)
+ logger.info("Skills Directory Migration Script (v2.2.0)")
+ logger.info("=" * 60)
+
+ if args.dry_run:
+ logger.info("Mode: DRY-RUN (no changes will be made)")
+
+ # Step 1: Load environment from .env file
+ logger.info("\n[Step 1/6] Loading environment variables...")
+ load_environment_from_host()
+
+ # Get ROOT_DIR
+ root_dir = get_root_dir()
+ if root_dir:
+ logger.info(f" ROOT_DIR: {root_dir}")
+ else:
+ logger.warning(" ROOT_DIR not set, using current directory")
+
+ # Determine host paths
+ skills_base = str(Path(root_dir) / "skills") if root_dir else "skills"
+
+ # Step 2: Check if container is running
+ logger.info("\n[Step 2/6] Checking container status...")
+ container_running = check_container_running()
+ if not container_running:
+ logger.error("nexent-config container is not running")
+ sys.exit(1)
+
+ # Step 3: Test PostgreSQL connection and get tenant_id from container
+ tenant_id = None
+ if not args.skip_db:
+ logger.info("\n[Step 3/6] Testing PostgreSQL connection from inside container...")
+
+ if test_postgres_connection_in_container():
+ logger.info("\n[Step 4/6] Querying admin tenant_id...")
+ tenant_id = get_admin_tenant_id_in_container()
+
+ if not tenant_id:
+ logger.warning("Could not determine tenant_id from database")
+ else:
+ logger.warning("Could not connect to PostgreSQL")
+ else:
+ logger.info("\n[Step 3/6] Skipping database connection (--skip-db)")
+
+ # Fallback: check existing tenant directories on host
+ if not tenant_id:
+ logger.info("Checking for existing tenant directories...")
+ skills_base_obj = Path(skills_base)
+ if skills_base_obj.is_dir():
+ existing_tenants = [
+ d.name for d in skills_base_obj.iterdir()
+ if d.is_dir() and d.name not in ['.', '..']
+ ]
+ if existing_tenants:
+ tenant_id = existing_tenants[0]
+ logger.info(f"Using existing tenant directory: {tenant_id}")
+
+ # Step 5: Determine directories
+ legacy_dir = args.legacy_dir or discover_legacy_skills_dir(root_dir or ".")
+ logger.info(f"\n[Step 5/6] Migration paths:")
+ logger.info(f" Legacy directory (host): {legacy_dir}")
+ logger.info(f" Skills base (host): {skills_base}")
+
+ if args.target_dir:
+ target_base = args.target_dir
+ logger.info(f" Target directory (host): {target_base}")
+ elif tenant_id:
+ target_base = str(Path(skills_base) / tenant_id)
+ logger.info(f" Target directory (host): {target_base}")
+ else:
+ logger.error("Cannot determine target directory: no tenant_id found")
+ logger.info("Options:")
+ logger.info(" 1. Ensure user_tenant_t has at least one ADMIN user")
+ logger.info(" 2. Provide --target-dir explicitly")
+ logger.info(" 3. Use --skip-db and ensure existing tenant directories exist")
+ sys.exit(1)
+
+ # Step 6: Discover and migrate skills
+ logger.info("\n[Step 6/6] Discovering skills in legacy directory...")
+
+ if not Path(legacy_dir).is_dir():
+ logger.warning(f"Legacy directory does not exist: {legacy_dir}")
+ logger.info("No migration needed (source directory not found)")
+ return
+
+ skills = discover_skill_directories(legacy_dir)
+ if not skills:
+ logger.info("No skills found in legacy directory")
+ logger.info("Migration complete (nothing to migrate)")
+ return
+
+ logger.info(f"Found {len(skills)} skill(s): {', '.join(skills)}")
+
+ # Execute migration
+ results = migrate_skills(
+ legacy_dir=legacy_dir,
+ target_dir=target_base,
+ skills=skills,
+ dry_run=args.dry_run
+ )
+
+ print_results(results)
+
+ # Final summary
+ logger.info("\n" + "=" * 60)
+ if args.dry_run:
+ logger.info("DRY-RUN complete. To apply migration, run without --dry-run")
+ else:
+ logger.info("Migration completed")
+ if results['migrated'] > 0:
+ logger.info(f"\nSuccessfully migrated {results['migrated']} skill(s)")
+ logger.info(f"Skills are now available at: {target_base}")
+ logger.info("\nNote: The legacy directory has been preserved.")
+ logger.info("You can remove it manually after verifying the migration:")
+ logger.info(f" rm -rf {legacy_dir}")
+ logger.info("=" * 60)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/docker/scripts/v220_sync_skill_directory.sh b/docker/scripts/v220_sync_skill_directory.sh
new file mode 100644
index 000000000..572ffeb30
--- /dev/null
+++ b/docker/scripts/v220_sync_skill_directory.sh
@@ -0,0 +1,84 @@
+#!/bin/bash
+#
+# v2.2.0 Skills Directory Migration Script
+# Migrates skills from legacy location to tenant-isolated directories.
+#
+# Migration:
+# FROM: ${ROOT_DIR}/skills/ (flat directory, skills directly under skills/)
+# TO: ${ROOT_DIR}/skills/{tenant_id}/
+#
+# The tenant_id is determined by querying user_tenant_t for the first record
+# with user_role = 'ADMIN'.
+#
+# Usage:
+# ./v220_sync_skill_directory.sh [--dry-run]
+#
+# Options:
+# --dry-run Show what would be migrated without making changes
+#
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SCRIPT_PATH="${SCRIPT_DIR}/sync_skill_directory.py"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+log_info() {
+ echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+log_warn() {
+ echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+log_error() {
+ echo -e "${RED}[ERROR]${NC} $1"
+}
+
+DRY_RUN=false
+for arg in "$@"; do
+ case $arg in
+ --dry-run)
+ DRY_RUN=true
+ shift
+ ;;
+ *)
+ ;;
+ esac
+done
+
+if [ ! -f "$SCRIPT_PATH" ]; then
+ log_error "Script not found: $SCRIPT_PATH"
+ exit 1
+fi
+
+# Load environment from .env if exists
+ENV_FILE="${SCRIPT_DIR}/../.env"
+if [ -f "$ENV_FILE" ]; then
+ log_info "Loading environment from: $ENV_FILE"
+ set -a
+ source "$ENV_FILE"
+ set +a
+fi
+
+log_info "Executing migration script..."
+
+if [ "$DRY_RUN" = true ]; then
+ log_info "Mode: DRY-RUN (no changes will be made)"
+ python "$SCRIPT_PATH" --dry-run "$@"
+else
+ python "$SCRIPT_PATH" "$@"
+fi
+
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -eq 0 ]; then
+ log_info "Migration completed successfully"
+else
+ log_error "Migration failed with exit code: $EXIT_CODE"
+ exit $EXIT_CODE
+fi
diff --git a/docker/sql/v2.0.2_0425_add_is_a2a_to_ag_tenant_agent_version_t.sql b/docker/sql/v2.0.2_0425_add_is_a2a_to_ag_tenant_agent_version_t.sql
new file mode 100644
index 000000000..3eb6ac5e9
--- /dev/null
+++ b/docker/sql/v2.0.2_0425_add_is_a2a_to_ag_tenant_agent_version_t.sql
@@ -0,0 +1,7 @@
+-- Add is_a2a column to ag_tenant_agent_version_t for tracking A2A Server agent publish status
+-- This field indicates whether this version was published as an A2A Server agent
+
+ALTER TABLE nexent.ag_tenant_agent_version_t
+ADD COLUMN IF NOT EXISTS is_a2a BOOLEAN DEFAULT FALSE;
+
+COMMENT ON COLUMN nexent.ag_tenant_agent_version_t.is_a2a IS 'Whether this version is published as an A2A Server agent';
diff --git a/docker/sql/v2.0.3_0423_create_model_monitoring_record_t.sql b/docker/sql/v2.0.3_0423_create_model_monitoring_record_t.sql
new file mode 100644
index 000000000..438ca4863
--- /dev/null
+++ b/docker/sql/v2.0.3_0423_create_model_monitoring_record_t.sql
@@ -0,0 +1,42 @@
+-- Model Monitoring Record Table
+-- Stores per-request LLM performance metrics for the monitoring feature.
+-- Run this script against the 'nexent' schema in PostgreSQL.
+
+CREATE TABLE IF NOT EXISTS nexent.model_monitoring_record_t (
+ monitoring_id SERIAL PRIMARY KEY,
+ model_id INT4,
+ model_name VARCHAR(100) NOT NULL,
+ model_type VARCHAR(20) DEFAULT 'llm',
+ agent_id INT4,
+ agent_name VARCHAR(100),
+ conversation_id INT4,
+ tenant_id VARCHAR(100) NOT NULL,
+ user_id VARCHAR(100),
+ display_name VARCHAR(100),
+ request_duration_ms INT4,
+ ttft_ms INT4,
+ input_tokens INT4,
+ output_tokens INT4,
+ total_tokens INT4,
+ generation_rate FLOAT,
+ is_streaming BOOLEAN DEFAULT FALSE,
+ is_success BOOLEAN DEFAULT TRUE,
+ is_error BOOLEAN DEFAULT FALSE,
+ error_type VARCHAR(50),
+ error_message TEXT,
+ retry_count INT4 DEFAULT 0,
+ operation VARCHAR(50),
+ create_time TIMESTAMP DEFAULT NOW(),
+ delete_flag VARCHAR(1) DEFAULT 'N'
+);
+
+-- Single-column indexes for common query patterns
+CREATE INDEX IF NOT EXISTS ix_monitoring_model_id ON nexent.model_monitoring_record_t (model_id);
+CREATE INDEX IF NOT EXISTS ix_monitoring_tenant_id ON nexent.model_monitoring_record_t (tenant_id);
+CREATE INDEX IF NOT EXISTS ix_monitoring_agent_id ON nexent.model_monitoring_record_t (agent_id);
+CREATE INDEX IF NOT EXISTS ix_monitoring_create_time ON nexent.model_monitoring_record_t (create_time);
+CREATE INDEX IF NOT EXISTS ix_monitoring_is_error ON nexent.model_monitoring_record_t (is_error);
+CREATE INDEX IF NOT EXISTS ix_monitoring_model_type ON nexent.model_monitoring_record_t (model_type);
+
+-- Composite index for time-range queries per model
+CREATE INDEX IF NOT EXISTS ix_monitoring_model_time ON nexent.model_monitoring_record_t (model_id, create_time);
diff --git a/docker/sql/v2.0.3_0430_add_user_oauth_account_t.sql b/docker/sql/v2.0.3_0430_add_user_oauth_account_t.sql
new file mode 100644
index 000000000..faa9adab2
--- /dev/null
+++ b/docker/sql/v2.0.3_0430_add_user_oauth_account_t.sql
@@ -0,0 +1,52 @@
+-- Create user OAuth account table for third-party login (GitHub, WeChat, etc.)
+CREATE TABLE IF NOT EXISTS nexent.user_oauth_account_t (
+ oauth_account_id SERIAL PRIMARY KEY,
+ user_id VARCHAR(100) NOT NULL,
+ provider VARCHAR(30) NOT NULL,
+ provider_user_id VARCHAR(200) NOT NULL,
+ provider_email VARCHAR(255),
+ provider_username VARCHAR(200),
+ tenant_id VARCHAR(100),
+ create_time TIMESTAMP WITHOUT TIME ZONE DEFAULT NOW(),
+ update_time TIMESTAMP WITHOUT TIME ZONE DEFAULT NOW(),
+ created_by VARCHAR(100),
+ updated_by VARCHAR(100),
+ delete_flag CHAR(1) DEFAULT 'N',
+ CONSTRAINT uq_oauth_provider_user UNIQUE (provider, provider_user_id)
+);
+
+ALTER TABLE nexent.user_oauth_account_t OWNER TO "root";
+
+-- Create a function to update the update_time column
+CREATE OR REPLACE FUNCTION update_user_oauth_account_t_update_time()
+RETURNS TRIGGER AS $$
+BEGIN
+ NEW.update_time = CURRENT_TIMESTAMP;
+ RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Create a trigger to call the function before each update
+CREATE TRIGGER update_user_oauth_account_t_update_time_trigger
+BEFORE UPDATE ON nexent.user_oauth_account_t
+FOR EACH ROW
+EXECUTE FUNCTION update_user_oauth_account_t_update_time();
+
+-- Add comments
+COMMENT ON TABLE nexent.user_oauth_account_t IS 'User OAuth account table - third-party login bindings';
+COMMENT ON COLUMN nexent.user_oauth_account_t.oauth_account_id IS 'OAuth account ID, primary key';
+COMMENT ON COLUMN nexent.user_oauth_account_t.user_id IS 'Nexent user ID (Supabase UUID)';
+COMMENT ON COLUMN nexent.user_oauth_account_t.provider IS 'OAuth provider name: github, wechat, gde, link_app';
+COMMENT ON COLUMN nexent.user_oauth_account_t.provider_user_id IS 'User ID from the OAuth provider';
+COMMENT ON COLUMN nexent.user_oauth_account_t.provider_email IS 'Email from the OAuth provider';
+COMMENT ON COLUMN nexent.user_oauth_account_t.provider_username IS 'Display name from the OAuth provider';
+COMMENT ON COLUMN nexent.user_oauth_account_t.tenant_id IS 'Tenant ID at time of linking';
+COMMENT ON COLUMN nexent.user_oauth_account_t.create_time IS 'Creation time';
+COMMENT ON COLUMN nexent.user_oauth_account_t.update_time IS 'Update time';
+COMMENT ON COLUMN nexent.user_oauth_account_t.created_by IS 'Creator';
+COMMENT ON COLUMN nexent.user_oauth_account_t.updated_by IS 'Updater';
+COMMENT ON COLUMN nexent.user_oauth_account_t.delete_flag IS 'Whether it is deleted. Optional values: Y/N';
+
+-- Create index for user_id queries
+CREATE INDEX IF NOT EXISTS idx_user_oauth_account_t_user_id
+ON nexent.user_oauth_account_t (user_id);
diff --git a/docker/sql/v2.0.4_0427_add_enable_context_manager_to_ag_tenant_agent_t.sql b/docker/sql/v2.0.4_0427_add_enable_context_manager_to_ag_tenant_agent_t.sql
new file mode 100644
index 000000000..b89a19e04
--- /dev/null
+++ b/docker/sql/v2.0.4_0427_add_enable_context_manager_to_ag_tenant_agent_t.sql
@@ -0,0 +1,10 @@
+-- Migration: Add enable_context_manager column to ag_tenant_agent_t table
+-- Date: 2025-04-27
+-- Description: Add enable_context_manager field to control context management (compression) per agent
+
+-- Add enable_context_manager column to ag_tenant_agent_t table
+ALTER TABLE nexent.ag_tenant_agent_t
+ADD COLUMN IF NOT EXISTS enable_context_manager BOOLEAN DEFAULT FALSE;
+
+-- Add comment to the column
+COMMENT ON COLUMN nexent.ag_tenant_agent_t.enable_context_manager IS 'Whether to enable context management (compression) for this agent';
\ No newline at end of file
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.0_0503_add_prompt_template_t.sql b/docker/sql/v2.1.0_0503_add_prompt_template_t.sql
new file mode 100644
index 000000000..3db9a9701
--- /dev/null
+++ b/docker/sql/v2.1.0_0503_add_prompt_template_t.sql
@@ -0,0 +1,115 @@
+-- Migration: Add prompt template table and agent prompt template fields
+-- Date: 2026-05-03
+-- Description: Add user-scoped prompt template storage and bind selected prompt template to agents
+
+ALTER TABLE nexent.ag_tenant_agent_t
+ADD COLUMN IF NOT EXISTS prompt_template_id INTEGER;
+
+ALTER TABLE nexent.ag_tenant_agent_t
+ADD COLUMN IF NOT EXISTS prompt_template_name VARCHAR(100);
+
+COMMENT ON COLUMN nexent.ag_tenant_agent_t.prompt_template_id IS 'Prompt template ID used for business logic prompt generation';
+COMMENT ON COLUMN nexent.ag_tenant_agent_t.prompt_template_name IS 'Prompt template name used for business logic prompt generation';
+
+UPDATE nexent.ag_tenant_agent_t
+SET prompt_template_id = 0,
+ prompt_template_name = 'system_default'
+WHERE delete_flag = 'N'
+ AND (prompt_template_id IS NULL OR prompt_template_name IS NULL);
+
+CREATE TABLE IF NOT EXISTS nexent.ag_prompt_template_t (
+ template_id SERIAL PRIMARY KEY,
+ template_name VARCHAR(100) NOT NULL,
+ description VARCHAR(500),
+ template_type VARCHAR(50) NOT NULL DEFAULT 'agent_generate',
+ tenant_id VARCHAR(100) NOT NULL,
+ user_id VARCHAR(100) NOT NULL,
+ template_content_zh JSONB NOT NULL,
+ template_content_en JSONB,
+ create_time TIMESTAMP WITHOUT TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+ update_time TIMESTAMP WITHOUT TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+ created_by VARCHAR(100),
+ updated_by VARCHAR(100),
+ delete_flag VARCHAR(1) DEFAULT 'N'
+);
+
+ALTER TABLE nexent.ag_prompt_template_t OWNER TO "root";
+
+CREATE OR REPLACE FUNCTION update_ag_prompt_template_update_time()
+RETURNS TRIGGER AS $$
+BEGIN
+ NEW.update_time = CURRENT_TIMESTAMP;
+ RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS update_ag_prompt_template_update_time_trigger ON nexent.ag_prompt_template_t;
+
+CREATE TRIGGER update_ag_prompt_template_update_time_trigger
+BEFORE UPDATE ON nexent.ag_prompt_template_t
+FOR EACH ROW
+EXECUTE FUNCTION update_ag_prompt_template_update_time();
+
+ALTER TABLE nexent.ag_prompt_template_t
+DROP CONSTRAINT IF EXISTS uq_prompt_template_user_name;
+
+COMMENT ON TABLE nexent.ag_prompt_template_t IS 'Prompt template table for user-defined business logic generation prompts';
+COMMENT ON COLUMN nexent.ag_prompt_template_t.template_id IS 'Prompt template ID';
+COMMENT ON COLUMN nexent.ag_prompt_template_t.template_name IS 'Prompt template name';
+COMMENT ON COLUMN nexent.ag_prompt_template_t.description IS 'Prompt template description';
+COMMENT ON COLUMN nexent.ag_prompt_template_t.template_type IS 'Prompt template type';
+COMMENT ON COLUMN nexent.ag_prompt_template_t.tenant_id IS 'Tenant ID';
+COMMENT ON COLUMN nexent.ag_prompt_template_t.user_id IS 'User ID';
+COMMENT ON COLUMN nexent.ag_prompt_template_t.template_content_zh IS 'Chinese prompt template content';
+COMMENT ON COLUMN nexent.ag_prompt_template_t.template_content_en IS 'English prompt template content';
+COMMENT ON COLUMN nexent.ag_prompt_template_t.create_time IS 'Creation time';
+COMMENT ON COLUMN nexent.ag_prompt_template_t.update_time IS 'Update time';
+COMMENT ON COLUMN nexent.ag_prompt_template_t.created_by IS 'Creator';
+COMMENT ON COLUMN nexent.ag_prompt_template_t.updated_by IS 'Updater';
+COMMENT ON COLUMN nexent.ag_prompt_template_t.delete_flag IS 'Whether it is deleted. Optional values: Y/N';
+
+DROP INDEX IF EXISTS nexent.uq_prompt_template_user_name_active;
+CREATE UNIQUE INDEX IF NOT EXISTS uq_prompt_template_user_name_active
+ON nexent.ag_prompt_template_t (tenant_id, user_id, template_name)
+WHERE delete_flag = 'N';
+
+CREATE INDEX IF NOT EXISTS idx_ag_prompt_template_t_user
+ON nexent.ag_prompt_template_t (tenant_id, user_id, template_type)
+WHERE delete_flag = 'N';
+
+INSERT INTO nexent.ag_prompt_template_t (
+ template_id,
+ template_name,
+ description,
+ template_type,
+ tenant_id,
+ user_id,
+ template_content_zh,
+ template_content_en,
+ created_by,
+ updated_by,
+ delete_flag
+)
+VALUES (
+ 0,
+ 'system_default',
+ 'System default prompt template',
+ 'agent_generate',
+ 'tenant_id',
+ 'user_id',
+ '{}'::jsonb,
+ '{}'::jsonb,
+ 'user_id',
+ 'user_id',
+ 'N'
+)
+ON CONFLICT (template_id) DO UPDATE SET
+ template_name = EXCLUDED.template_name,
+ description = EXCLUDED.description,
+ template_type = EXCLUDED.template_type,
+ tenant_id = EXCLUDED.tenant_id,
+ user_id = EXCLUDED.user_id,
+ template_content_zh = EXCLUDED.template_content_zh,
+ template_content_en = EXCLUDED.template_content_en,
+ updated_by = EXCLUDED.updated_by,
+ delete_flag = 'N';
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/docker/sql/v2.2.0_0514_skill_config_schema.sql b/docker/sql/v2.2.0_0514_skill_config_schema.sql
new file mode 100644
index 000000000..12e549175
--- /dev/null
+++ b/docker/sql/v2.2.0_0514_skill_config_schema.sql
@@ -0,0 +1,30 @@
+-- Rename params -> config_values, add config_schemas to ag_skill_info_t
+-- Add tenant_id column for multi-tenancy support
+ALTER TABLE nexent.ag_skill_info_t ADD COLUMN IF NOT EXISTS tenant_id VARCHAR(100);
+
+-- Add config_values and config_schemas to ag_skill_info_t
+DO $$
+BEGIN
+ IF EXISTS (
+ SELECT 1 FROM information_schema.columns
+ WHERE table_schema = 'nexent'
+ AND table_name = 'ag_skill_info_t'
+ AND column_name = 'params'
+ ) THEN
+ ALTER TABLE nexent.ag_skill_info_t RENAME COLUMN params TO config_values;
+ END IF;
+END $$;
+ALTER TABLE nexent.ag_skill_info_t ADD COLUMN IF NOT EXISTS config_schemas JSON;
+
+-- Comments for ag_skill_info_t columns
+COMMENT ON COLUMN nexent.ag_skill_info_t.tenant_id IS 'Tenant ID for multi-tenancy. NULL for pre-existing skills.';
+COMMENT ON COLUMN nexent.ag_skill_info_t.config_values IS 'Runtime parameter values from config/config.yaml';
+COMMENT ON COLUMN nexent.ag_skill_info_t.config_schemas IS 'Parameter metadata list from config/schema.yaml';
+
+-- Add config_values and config_schemas to ag_skill_instance_t
+ALTER TABLE nexent.ag_skill_instance_t ADD COLUMN IF NOT EXISTS config_values JSON;
+ALTER TABLE nexent.ag_skill_instance_t ADD COLUMN IF NOT EXISTS config_schemas JSON;
+
+-- Comments for ag_skill_instance_t columns
+COMMENT ON COLUMN nexent.ag_skill_instance_t.config_values IS 'Per-agent runtime parameter values from config/config.yaml';
+COMMENT ON COLUMN nexent.ag_skill_instance_t.config_schemas IS 'Per-agent parameter schema overrides from config/schema.yaml';
diff --git a/docker/sql/v2.2.0_0520_add_concurrency_and_timeout_to_model_record_t.sql b/docker/sql/v2.2.0_0520_add_concurrency_and_timeout_to_model_record_t.sql
new file mode 100644
index 000000000..59632f8ed
--- /dev/null
+++ b/docker/sql/v2.2.0_0520_add_concurrency_and_timeout_to_model_record_t.sql
@@ -0,0 +1,13 @@
+-- Add concurrency_limit column to model_record_t table
+ALTER TABLE nexent.model_record_t
+ADD COLUMN IF NOT EXISTS concurrency_limit INTEGER DEFAULT NULL;
+
+-- Add comment to the column
+COMMENT ON COLUMN nexent.model_record_t.concurrency_limit IS 'Maximum concurrent requests for this model. Default is NULL (unlimited).';
+
+-- Add timeout_seconds column to model_record_t table
+ALTER TABLE nexent.model_record_t
+ADD COLUMN IF NOT EXISTS timeout_seconds INTEGER DEFAULT 120;
+
+-- Add comment to the column
+COMMENT ON COLUMN nexent.model_record_t.timeout_seconds IS 'Request timeout in seconds for this model. Default is 120 seconds.';
diff --git a/docker/sql/v2.2.0_0521_add_mcp_community_record_t.sql b/docker/sql/v2.2.0_0521_add_mcp_community_record_t.sql
new file mode 100644
index 000000000..83f9d9a56
--- /dev/null
+++ b/docker/sql/v2.2.0_0521_add_mcp_community_record_t.sql
@@ -0,0 +1,83 @@
+-- Migration: Add mcp_community_record_t table
+-- Date: 2026-03-26
+-- Description: Community MCP market table aligned with public-shareable fields from mcp_record_t.
+
+SET search_path TO nexent;
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS nexent.mcp_community_record_t (
+ community_id SERIAL PRIMARY KEY NOT NULL,
+ tenant_id VARCHAR(100),
+ user_id VARCHAR(100),
+ mcp_name VARCHAR(100) NOT NULL,
+ mcp_server VARCHAR(500) NOT NULL,
+ source VARCHAR(30) DEFAULT 'community',
+ version VARCHAR(50),
+ registry_json JSONB,
+ transport_type VARCHAR(30),
+ config_json JSON,
+ tags TEXT[],
+ description TEXT,
+ create_time TIMESTAMP WITHOUT TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+ update_time TIMESTAMP WITHOUT TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+ created_by VARCHAR(100),
+ updated_by VARCHAR(100),
+ delete_flag VARCHAR(1) DEFAULT 'N'
+);
+
+ALTER TABLE nexent.mcp_community_record_t OWNER TO root;
+
+COMMENT ON TABLE nexent.mcp_community_record_t IS 'Community MCP market records, publishable from tenant MCP services';
+COMMENT ON COLUMN nexent.mcp_community_record_t.community_id IS 'Community record ID, unique primary key';
+COMMENT ON COLUMN nexent.mcp_community_record_t.tenant_id IS 'Publisher tenant ID';
+COMMENT ON COLUMN nexent.mcp_community_record_t.user_id IS 'Publisher user ID';
+COMMENT ON COLUMN nexent.mcp_community_record_t.mcp_name IS 'MCP name';
+COMMENT ON COLUMN nexent.mcp_community_record_t.mcp_server IS 'MCP server URL';
+COMMENT ON COLUMN nexent.mcp_community_record_t.source IS 'Source type, fixed to community for this table';
+COMMENT ON COLUMN nexent.mcp_community_record_t.version IS 'MCP version';
+COMMENT ON COLUMN nexent.mcp_community_record_t.registry_json IS 'Full MCP server metadata JSON for discovery and quick import';
+COMMENT ON COLUMN nexent.mcp_community_record_t.transport_type IS 'Transport type: url/container';
+COMMENT ON COLUMN nexent.mcp_community_record_t.config_json IS 'Public-shareable MCP configuration JSON';
+COMMENT ON COLUMN nexent.mcp_community_record_t.tags IS 'Tags';
+COMMENT ON COLUMN nexent.mcp_community_record_t.description IS 'Description';
+COMMENT ON COLUMN nexent.mcp_community_record_t.create_time IS 'Creation time';
+COMMENT ON COLUMN nexent.mcp_community_record_t.update_time IS 'Update time';
+COMMENT ON COLUMN nexent.mcp_community_record_t.created_by IS 'Creator ID';
+COMMENT ON COLUMN nexent.mcp_community_record_t.updated_by IS 'Updater ID';
+COMMENT ON COLUMN nexent.mcp_community_record_t.delete_flag IS 'Soft delete flag: Y/N';
+
+CREATE INDEX IF NOT EXISTS idx_mcp_community_tenant_delete
+ ON nexent.mcp_community_record_t (tenant_id, delete_flag);
+
+CREATE INDEX IF NOT EXISTS idx_mcp_community_name_delete
+ ON nexent.mcp_community_record_t (mcp_name, delete_flag);
+
+CREATE INDEX IF NOT EXISTS idx_mcp_community_transport_delete
+ ON nexent.mcp_community_record_t (transport_type, delete_flag);
+
+CREATE INDEX IF NOT EXISTS idx_mcp_community_user_delete
+ ON nexent.mcp_community_record_t (user_id, delete_flag);
+
+CREATE INDEX IF NOT EXISTS idx_mcp_community_tags_gin
+ ON nexent.mcp_community_record_t USING GIN (tags);
+
+CREATE OR REPLACE FUNCTION update_mcp_community_record_update_time()
+RETURNS TRIGGER AS $$
+BEGIN
+ NEW.update_time = CURRENT_TIMESTAMP;
+ RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+COMMENT ON FUNCTION update_mcp_community_record_update_time() IS 'Auto-update update_time for mcp_community_record_t';
+
+DROP TRIGGER IF EXISTS update_mcp_community_record_update_time_trigger ON nexent.mcp_community_record_t;
+CREATE TRIGGER update_mcp_community_record_update_time_trigger
+BEFORE UPDATE ON nexent.mcp_community_record_t
+FOR EACH ROW
+EXECUTE FUNCTION update_mcp_community_record_update_time();
+
+COMMENT ON TRIGGER update_mcp_community_record_update_time_trigger ON nexent.mcp_community_record_t IS 'Trigger to maintain update_time';
+
+COMMIT;
diff --git a/docker/sql/v2.2.0_0521_expand_mcp_record_t.sql b/docker/sql/v2.2.0_0521_expand_mcp_record_t.sql
new file mode 100644
index 000000000..6c92a392e
--- /dev/null
+++ b/docker/sql/v2.2.0_0521_expand_mcp_record_t.sql
@@ -0,0 +1,41 @@
+-- Migration: Extend mcp_record_t for MCP tools (direct schema)
+-- Date: 2026-03-18
+-- Description: One-step schema extension for mcp_record_t. No table merge, no data migration.
+
+SET search_path TO nexent;
+
+BEGIN;
+
+-- 1) Extend mcp_record_t with final column names (idempotent)
+ALTER TABLE IF EXISTS nexent.mcp_record_t
+ ADD COLUMN IF NOT EXISTS source VARCHAR(30),
+ ADD COLUMN IF NOT EXISTS registry_json JSONB,
+ ADD COLUMN IF NOT EXISTS config_json JSON,
+ ADD COLUMN IF NOT EXISTS enabled BOOLEAN DEFAULT TRUE,
+ ADD COLUMN IF NOT EXISTS tags TEXT[],
+ ADD COLUMN IF NOT EXISTS description TEXT,
+ ADD COLUMN IF NOT EXISTS container_port INTEGER;
+
+-- 2) Add comments for new columns
+COMMENT ON COLUMN nexent.mcp_record_t.source IS 'Source type: local/mcp_registry/community';
+COMMENT ON COLUMN nexent.mcp_record_t.registry_json IS 'Full MCP registry server.json snapshot';
+COMMENT ON COLUMN nexent.mcp_record_t.config_json IS 'MCP config data';
+COMMENT ON COLUMN nexent.mcp_record_t.enabled IS 'Enabled';
+COMMENT ON COLUMN nexent.mcp_record_t.tags IS 'Tags';
+COMMENT ON COLUMN nexent.mcp_record_t.description IS 'Description';
+COMMENT ON COLUMN nexent.mcp_record_t.container_port IS 'Host port bound for containerized MCP service';
+
+-- 3) Add indexes for common management queries
+CREATE INDEX IF NOT EXISTS idx_mcp_record_t_tenant_delete
+ ON nexent.mcp_record_t (tenant_id, delete_flag);
+
+CREATE INDEX IF NOT EXISTS idx_mcp_record_t_tenant_name
+ ON nexent.mcp_record_t (tenant_id, mcp_name, delete_flag);
+
+CREATE INDEX IF NOT EXISTS idx_mcp_record_t_tenant_server
+ ON nexent.mcp_record_t (tenant_id, mcp_server, delete_flag);
+
+CREATE INDEX IF NOT EXISTS idx_mcp_record_t_tags_gin
+ ON nexent.mcp_record_t USING GIN (tags);
+
+COMMIT;
diff --git a/docker/sql/v2.2.0_0526_add_cas_session_t.sql b/docker/sql/v2.2.0_0526_add_cas_session_t.sql
new file mode 100644
index 000000000..3f1aab4fa
--- /dev/null
+++ b/docker/sql/v2.2.0_0526_add_cas_session_t.sql
@@ -0,0 +1,27 @@
+CREATE TABLE IF NOT EXISTS nexent.user_cas_session_t (
+ cas_session_id SERIAL PRIMARY KEY,
+ session_id VARCHAR(100) NOT NULL UNIQUE,
+ user_id VARCHAR(100) NOT NULL,
+ cas_user_id VARCHAR(200) NOT NULL,
+ cas_session_index VARCHAR(500),
+ status VARCHAR(30) NOT NULL DEFAULT 'active',
+ expires_at TIMESTAMP NOT NULL,
+ revoked_at TIMESTAMP,
+ create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+ update_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+ created_by VARCHAR(100),
+ updated_by VARCHAR(100),
+ delete_flag VARCHAR(1) DEFAULT 'N'
+);
+
+CREATE INDEX IF NOT EXISTS ix_user_cas_session_session_id
+ ON nexent.user_cas_session_t (session_id);
+CREATE INDEX IF NOT EXISTS ix_user_cas_session_user_id
+ ON nexent.user_cas_session_t (user_id);
+CREATE INDEX IF NOT EXISTS ix_user_cas_session_cas_user_id
+ ON nexent.user_cas_session_t (cas_user_id);
+
+COMMENT ON TABLE nexent.user_cas_session_t IS 'Server-side session records for CAS SSO login and logout synchronization';
+COMMENT ON COLUMN nexent.user_cas_session_t.session_id IS 'JWT sid claim for revocation checks';
+COMMENT ON COLUMN nexent.user_cas_session_t.cas_user_id IS 'User identifier returned by CAS';
+COMMENT ON COLUMN nexent.user_cas_session_t.cas_session_index IS 'CAS SessionIndex or service ticket';
diff --git a/docker/sql/v2.2.0_0527_add_custom_headers_to_mcp_record_t.sql b/docker/sql/v2.2.0_0527_add_custom_headers_to_mcp_record_t.sql
new file mode 100644
index 000000000..00933c523
--- /dev/null
+++ b/docker/sql/v2.2.0_0527_add_custom_headers_to_mcp_record_t.sql
@@ -0,0 +1,26 @@
+-- Migration: Add custom_headers column to mcp_record_t
+-- Date: 2026-05-26
+-- Description: Add custom_headers field to store custom HTTP headers for MCP server requests
+
+SET search_path TO nexent;
+
+BEGIN;
+
+-- Add custom_headers column if it doesn't exist
+DO $$
+BEGIN
+ IF NOT EXISTS (
+ SELECT 1 FROM information_schema.columns
+ WHERE table_schema = 'nexent'
+ AND table_name = 'mcp_record_t'
+ AND column_name = 'custom_headers'
+ ) THEN
+ ALTER TABLE nexent.mcp_record_t
+ ADD COLUMN custom_headers JSON DEFAULT NULL;
+ END IF;
+END $$;
+
+-- Add comment to the column
+COMMENT ON COLUMN nexent.mcp_record_t.custom_headers IS 'Custom HTTP headers as JSON object for MCP server requests';
+
+COMMIT;
diff --git a/docker/sql/v2.2.0_0529_add_asset_owner_role_permissions.sql b/docker/sql/v2.2.0_0529_add_asset_owner_role_permissions.sql
new file mode 100644
index 000000000..8f21b110b
--- /dev/null
+++ b/docker/sql/v2.2.0_0529_add_asset_owner_role_permissions.sql
@@ -0,0 +1,53 @@
+-- Migration: ASSET_OWNER role permissions and invitation type comment
+-- Date: 2026-05-29
+-- Description: Add ASSET_OWNER role permissions, SU asset-owner invite permissions,
+-- update invitation code_type comment, and ensure ag_skill_info_t.tenant_id exists
+-- Source: commit 15cece97692db2372a978cbdf21b5d5316e79f30 (init.sql)
+
+SET search_path TO nexent;
+
+BEGIN;
+
+COMMENT ON COLUMN nexent.tenant_invitation_code_t.code_type IS
+ 'Invitation code type: ADMIN_INVITE, DEV_INVITE, USER_INVITE, ASSET_OWNER_INVITE';
+
+INSERT INTO nexent.role_permission_t
+ (role_permission_id, user_role, permission_category, permission_type, permission_subtype)
+VALUES
+ (188, 'SU', 'RESOURCE', 'INVITE.ASSET_OWNER', 'CREATE'),
+ (189, 'SU', 'RESOURCE', 'INVITE.ASSET_OWNER', 'READ'),
+ (190, 'SU', 'RESOURCE', 'INVITE.ASSET_OWNER', 'UPDATE'),
+ (191, 'SU', 'RESOURCE', 'INVITE.ASSET_OWNER', 'DELETE'),
+ (192, 'ASSET_OWNER', 'VISIBILITY', 'LEFT_NAV_MENU', '/'),
+ (193, 'ASSET_OWNER', 'VISIBILITY', 'LEFT_NAV_MENU', '/agents'),
+ (194, 'ASSET_OWNER', 'VISIBILITY', 'LEFT_NAV_MENU', '/knowledges'),
+ (195, 'ASSET_OWNER', 'VISIBILITY', 'LEFT_NAV_MENU', '/chat'),
+ (196, 'ASSET_OWNER', 'VISIBILITY', 'LEFT_NAV_MENU', '/space'),
+ (197, 'ASSET_OWNER', 'VISIBILITY', 'LEFT_NAV_MENU', '/market'),
+ (198, 'ASSET_OWNER', 'VISIBILITY', 'LEFT_NAV_MENU', '/models'),
+ (199, 'ASSET_OWNER', 'RESOURCE', 'AGENT', 'CREATE'),
+ (200, 'ASSET_OWNER', 'RESOURCE', 'AGENT', 'READ'),
+ (201, 'ASSET_OWNER', 'RESOURCE', 'AGENT', 'UPDATE'),
+ (202, 'ASSET_OWNER', 'RESOURCE', 'AGENT', 'DELETE'),
+ (203, 'ASSET_OWNER', 'RESOURCE', 'SKILL', 'CREATE'),
+ (204, 'ASSET_OWNER', 'RESOURCE', 'SKILL', 'READ'),
+ (205, 'ASSET_OWNER', 'RESOURCE', 'SKILL', 'UPDATE'),
+ (206, 'ASSET_OWNER', 'RESOURCE', 'SKILL', 'DELETE'),
+ (207, 'ASSET_OWNER', 'RESOURCE', 'KB', 'CREATE'),
+ (208, 'ASSET_OWNER', 'RESOURCE', 'KB', 'READ'),
+ (209, 'ASSET_OWNER', 'RESOURCE', 'KB', 'UPDATE'),
+ (210, 'ASSET_OWNER', 'RESOURCE', 'KB', 'DELETE'),
+ (211, 'ASSET_OWNER', 'RESOURCE', 'MCP', 'CREATE'),
+ (212, 'ASSET_OWNER', 'RESOURCE', 'MCP', 'READ'),
+ (213, 'ASSET_OWNER', 'RESOURCE', 'MCP', 'UPDATE'),
+ (214, 'ASSET_OWNER', 'RESOURCE', 'MCP', 'DELETE'),
+ (215, 'ASSET_OWNER', 'RESOURCE', 'MODEL', 'CREATE'),
+ (216, 'ASSET_OWNER', 'RESOURCE', 'MODEL', 'READ'),
+ (217, 'ASSET_OWNER', 'RESOURCE', 'MODEL', 'UPDATE'),
+ (218, 'ASSET_OWNER', 'RESOURCE', 'MODEL', 'DELETE'),
+ (219, 'ASSET_OWNER', 'RESOURCE', 'USER.ROLE', 'READ'),
+ (220, 'ASSET_OWNER', 'VISIBILITY', 'LEFT_NAV_MENU', '/users'),
+ (221, 'SU', 'VISIBILITY', 'LEFT_NAV_MENU', '/asset-owner-resources')
+ON CONFLICT (role_permission_id) DO NOTHING;
+
+COMMIT;
diff --git a/docker/sql/v2.2.1_0601_add_agent_verification_config.sql b/docker/sql/v2.2.1_0601_add_agent_verification_config.sql
new file mode 100644
index 000000000..d3882e1e2
--- /dev/null
+++ b/docker/sql/v2.2.1_0601_add_agent_verification_config.sql
@@ -0,0 +1,7 @@
+-- Migration: Add layered ReAct self-verification config to agents
+-- Description: Stores per-agent verification controls for step-level and final-answer validation.
+
+ALTER TABLE nexent.ag_tenant_agent_t
+ADD COLUMN IF NOT EXISTS verification_config JSONB;
+
+COMMENT ON COLUMN nexent.ag_tenant_agent_t.verification_config IS 'Layered ReAct self-verification configuration';
diff --git a/docker/sql/v2.2.1_0601_add_preserve_source_file_to_knowledge_record_t.sql b/docker/sql/v2.2.1_0601_add_preserve_source_file_to_knowledge_record_t.sql
new file mode 100644
index 000000000..30b588a51
--- /dev/null
+++ b/docker/sql/v2.2.1_0601_add_preserve_source_file_to_knowledge_record_t.sql
@@ -0,0 +1,8 @@
+-- Migration: Add preserve_source_file to knowledge_record_t table
+-- Date: 2026-06-01
+-- Description: Whether to preserve uploaded source documents after vectorization (default: true)
+
+ALTER TABLE nexent.knowledge_record_t
+ADD COLUMN IF NOT EXISTS preserve_source_file BOOLEAN NOT NULL DEFAULT true;
+
+COMMENT ON COLUMN nexent.knowledge_record_t.preserve_source_file IS 'Whether to preserve uploaded source documents after vectorization';
diff --git a/docker/sql/v2.2.1_0603_add_greeting_fields_to_ag_tenant_agent_t.sql b/docker/sql/v2.2.1_0603_add_greeting_fields_to_ag_tenant_agent_t.sql
new file mode 100644
index 000000000..7786bb902
--- /dev/null
+++ b/docker/sql/v2.2.1_0603_add_greeting_fields_to_ag_tenant_agent_t.sql
@@ -0,0 +1,15 @@
+-- Migration: Add greeting_message and example_questions columns to ag_tenant_agent_t table
+-- Date: 2026-06-03
+-- Description: Add greeting message and example questions fields for agent chat initial screen
+
+-- Add greeting_message column to ag_tenant_agent_t table
+ALTER TABLE nexent.ag_tenant_agent_t
+ADD COLUMN IF NOT EXISTS greeting_message TEXT;
+
+-- Add example_questions column to ag_tenant_agent_t table
+ALTER TABLE nexent.ag_tenant_agent_t
+ADD COLUMN IF NOT EXISTS example_questions JSONB;
+
+-- Add comments to the columns
+COMMENT ON COLUMN nexent.ag_tenant_agent_t.greeting_message IS 'Agent greeting message displayed on chat initial screen';
+COMMENT ON COLUMN nexent.ag_tenant_agent_t.example_questions IS 'List of example questions for starting a conversation with this agent';
\ No newline at end of file
diff --git a/docker/sql/v2.2.1_0605_add_ag_agent_repository_t.sql b/docker/sql/v2.2.1_0605_add_ag_agent_repository_t.sql
new file mode 100644
index 000000000..d719fc5aa
--- /dev/null
+++ b/docker/sql/v2.2.1_0605_add_ag_agent_repository_t.sql
@@ -0,0 +1,96 @@
+-- Migration: Add ag_agent_repository_t table
+-- Date: 2026-06-05
+-- Description: Agent marketplace repository for frozen shareable agent snapshots.
+
+SET search_path TO nexent;
+
+BEGIN;
+
+CREATE SEQUENCE IF NOT EXISTS nexent.ag_agent_repository_t_agent_repository_id_seq;
+
+CREATE TABLE IF NOT EXISTS nexent.ag_agent_repository_t (
+ agent_repository_id BIGINT NOT NULL DEFAULT nextval('nexent.ag_agent_repository_t_agent_repository_id_seq'),
+ publisher_tenant_id VARCHAR(100) NOT NULL,
+ publisher_user_id VARCHAR(100) NOT NULL,
+ agent_id INTEGER NOT NULL,
+ source_version_no INTEGER NOT NULL,
+ name VARCHAR(100) NOT NULL,
+ display_name VARCHAR(100),
+ description TEXT,
+ author VARCHAR(100),
+ category_id INTEGER,
+ tags TEXT[],
+ tool_count INTEGER,
+ version_label VARCHAR(100),
+ agent_info_json JSONB NOT NULL,
+ status VARCHAR(30) DEFAULT 'NOT_SHARED',
+ create_time TIMESTAMP WITHOUT TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+ update_time TIMESTAMP WITHOUT TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+ created_by VARCHAR(100),
+ updated_by VARCHAR(100),
+ delete_flag VARCHAR(1) DEFAULT 'N',
+ CONSTRAINT ag_agent_repository_t_pkey PRIMARY KEY (agent_repository_id)
+);
+
+ALTER SEQUENCE nexent.ag_agent_repository_t_agent_repository_id_seq
+ OWNED BY nexent.ag_agent_repository_t.agent_repository_id;
+
+ALTER TABLE nexent.ag_agent_repository_t OWNER TO root;
+
+COMMENT ON TABLE nexent.ag_agent_repository_t IS 'Agent marketplace repository for frozen shareable agent snapshots';
+COMMENT ON COLUMN nexent.ag_agent_repository_t.agent_repository_id IS 'Agent repository listing ID, unique primary key';
+COMMENT ON COLUMN nexent.ag_agent_repository_t.publisher_tenant_id IS 'Publisher tenant ID';
+COMMENT ON COLUMN nexent.ag_agent_repository_t.publisher_user_id IS 'Publisher user ID';
+COMMENT ON COLUMN nexent.ag_agent_repository_t.agent_id IS 'Root agent ID from ag_tenant_agent_t; upsert key with publisher_tenant_id';
+COMMENT ON COLUMN nexent.ag_agent_repository_t.source_version_no IS 'Published version number frozen at share time';
+COMMENT ON COLUMN nexent.ag_agent_repository_t.name IS 'Root agent programmatic name for display and search';
+COMMENT ON COLUMN nexent.ag_agent_repository_t.display_name IS 'Root agent display name';
+COMMENT ON COLUMN nexent.ag_agent_repository_t.description IS 'Root agent description';
+COMMENT ON COLUMN nexent.ag_agent_repository_t.author IS 'Agent author';
+COMMENT ON COLUMN nexent.ag_agent_repository_t.category_id IS 'Optional marketplace category ID';
+COMMENT ON COLUMN nexent.ag_agent_repository_t.tags IS 'Marketplace tags';
+COMMENT ON COLUMN nexent.ag_agent_repository_t.tool_count IS 'Total tool count across all agents in the bundle (display only)';
+COMMENT ON COLUMN nexent.ag_agent_repository_t.version_label IS 'Repository entry version label for display (e.g. v1.0)';
+COMMENT ON COLUMN nexent.ag_agent_repository_t.agent_info_json IS 'Frozen ExportAndImportDataFormat snapshot with optional skills';
+COMMENT ON COLUMN nexent.ag_agent_repository_t.status IS 'Listing status: NOT_SHARED (未共享) / PENDING_REVIEW (待审核) / REJECTED (审核驳回) / SHARED (已共享)';
+COMMENT ON COLUMN nexent.ag_agent_repository_t.create_time IS 'Creation time';
+COMMENT ON COLUMN nexent.ag_agent_repository_t.update_time IS 'Update time';
+COMMENT ON COLUMN nexent.ag_agent_repository_t.created_by IS 'Creator ID';
+COMMENT ON COLUMN nexent.ag_agent_repository_t.updated_by IS 'Updater ID';
+COMMENT ON COLUMN nexent.ag_agent_repository_t.delete_flag IS 'Soft delete flag: Y/N';
+
+CREATE UNIQUE INDEX IF NOT EXISTS uq_agent_repository_tenant_agent_active
+ ON nexent.ag_agent_repository_t (publisher_tenant_id, agent_id)
+ WHERE delete_flag = 'N';
+
+CREATE INDEX IF NOT EXISTS idx_agent_repository_publisher_delete
+ ON nexent.ag_agent_repository_t (publisher_tenant_id, delete_flag);
+
+CREATE INDEX IF NOT EXISTS idx_agent_repository_status_delete
+ ON nexent.ag_agent_repository_t (status, delete_flag);
+
+CREATE INDEX IF NOT EXISTS idx_agent_repository_name_delete
+ ON nexent.ag_agent_repository_t (name, delete_flag);
+
+CREATE INDEX IF NOT EXISTS idx_agent_repository_tags_gin
+ ON nexent.ag_agent_repository_t USING GIN (tags);
+
+CREATE OR REPLACE FUNCTION update_ag_agent_repository_update_time()
+RETURNS TRIGGER AS $$
+BEGIN
+ NEW.update_time = CURRENT_TIMESTAMP;
+ RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+COMMENT ON FUNCTION update_ag_agent_repository_update_time() IS 'Auto-update update_time for ag_agent_repository_t';
+
+DROP TRIGGER IF EXISTS update_ag_agent_repository_update_time_trigger ON nexent.ag_agent_repository_t;
+CREATE TRIGGER update_ag_agent_repository_update_time_trigger
+BEFORE UPDATE ON nexent.ag_agent_repository_t
+FOR EACH ROW
+EXECUTE FUNCTION update_ag_agent_repository_update_time();
+
+COMMENT ON TRIGGER update_ag_agent_repository_update_time_trigger ON nexent.ag_agent_repository_t IS 'Trigger to maintain update_time';
+
+COMMIT;
diff --git a/docker/sql/v2.2.1_0609_add_selected_agent_version_no_to_agent_relation_t.sql b/docker/sql/v2.2.1_0609_add_selected_agent_version_no_to_agent_relation_t.sql
new file mode 100644
index 000000000..9a67c1ab2
--- /dev/null
+++ b/docker/sql/v2.2.1_0609_add_selected_agent_version_no_to_agent_relation_t.sql
@@ -0,0 +1,15 @@
+-- Migration: Add selected_agent_version_no to ag_agent_relation_t
+-- Date: 2026-06-09
+-- Description: Pin child agent version on parent-child relations at publish time.
+
+SET search_path TO nexent;
+
+BEGIN;
+
+ALTER TABLE nexent.ag_agent_relation_t
+ ADD COLUMN IF NOT EXISTS selected_agent_version_no INTEGER;
+
+COMMENT ON COLUMN nexent.ag_agent_relation_t.selected_agent_version_no IS
+ 'Pinned version of selected_agent_id. NULL = use child current published version at runtime (legacy/draft).';
+
+COMMIT;
diff --git a/docker/start-monitoring.sh b/docker/start-monitoring.sh
index 8cd8561f0..48ca6cd3f 100755
--- a/docker/start-monitoring.sh
+++ b/docker/start-monitoring.sh
@@ -1,53 +1,420 @@
#!/bin/bash
# Nexent LLM Performance Monitoring Setup Script
-# This script sets up OpenTelemetry + Jaeger + Prometheus + Grafana for monitoring
+# This script starts the OpenTelemetry Collector alone, or with a local
+# Phoenix/Langfuse/Grafana/Zipkin observability backend, or forwards to
+# online LangSmith.
set -e
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
MONITORING_DIR="$SCRIPT_DIR/monitoring"
+COMPOSE_FILE="$SCRIPT_DIR/docker-compose-monitoring.yml"
-echo "🚀 Starting Nexent LLM Performance Monitoring Setup..."
+SUPPORTED_STACKS="otlp, collector, phoenix, langfuse, langsmith, grafana, zipkin"
-# Check if Docker is running
-if ! docker info > /dev/null 2>&1; then
- echo "❌ Error: Docker is not running. Please start Docker first."
- exit 1
-fi
+usage() {
+ cat <
+ $(basename "$0") [stack]
+ $(basename "$0") [stack]
+ $(basename "$0") [stack]
-# Create external network if it doesn't exist
-if ! docker network ls | grep -q nexent-network; then
- echo "🔗 Creating nexent-network..."
- docker network create nexent-network
-else
- echo "✅ nexent-network already exists"
-fi
+Stacks are mutually exclusive. Starting one stack removes containers from the
+other monitoring stacks while preserving their data volumes.
+
+Stacks:
+ otlp Start OpenTelemetry Collector only. This is the default.
+ collector Alias for otlp.
+ phoenix Start Collector and local Arize Phoenix.
+ langfuse Start Collector and local Langfuse self-host stack.
+ langsmith Start Collector and forward traces to online LangSmith.
+ grafana Start Collector, Grafana, and Tempo.
+ zipkin Start Collector and local Zipkin.
+
+Actions:
+ start/up Start the selected stack and stop containers from other stacks.
+ stop/down Stop and remove containers for the selected stack. Data is kept.
+ uninstall Stop and remove containers and data volumes for the selected stack.
+
+Set MONITORING_PROVIDER in monitoring/monitoring.env to change the default stack.
+EOF
+}
+
+ACTION="start"
+STACK_ARG=""
+
+set_stack_arg() {
+ local value="$1"
+ if [ -n "$STACK_ARG" ] && [ "$STACK_ARG" != "$value" ]; then
+ echo "❌ Error: multiple monitoring stacks specified: '$STACK_ARG' and '$value'."
+ usage
+ exit 1
+ fi
+ STACK_ARG="$value"
+}
+
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --stack)
+ if [ $# -lt 2 ]; then
+ echo "❌ Error: --stack requires a value."
+ usage
+ exit 1
+ fi
+ set_stack_arg "$2"
+ shift 2
+ ;;
+ --stop|--down)
+ ACTION="stop"
+ shift
+ ;;
+ --uninstall|--remove)
+ ACTION="uninstall"
+ shift
+ ;;
+ start|up)
+ ACTION="start"
+ shift
+ ;;
+ stop|down)
+ ACTION="stop"
+ shift
+ ;;
+ uninstall|remove)
+ ACTION="uninstall"
+ shift
+ ;;
+ -h|--help)
+ usage
+ exit 0
+ ;;
+ otlp|collector|phoenix|langfuse|langsmith|grafana|zipkin)
+ set_stack_arg "$1"
+ shift
+ ;;
+ *)
+ echo "❌ Error: unknown argument '$1'."
+ usage
+ exit 1
+ ;;
+ esac
+done
-# Copy environment file if it doesn't exist
-if [ ! -f "$MONITORING_DIR/monitoring.env" ]; then
- echo "📋 Creating monitoring.env from example..."
- cp "$MONITORING_DIR/monitoring.env.example" "$MONITORING_DIR/monitoring.env"
- echo "⚠️ Please review and update $MONITORING_DIR/monitoring.env as needed"
+normalize_stack() {
+ case "$1" in
+ ""|otlp|collector)
+ echo "collector"
+ ;;
+ phoenix|langfuse|langsmith|grafana|zipkin)
+ echo "$1"
+ ;;
+ *)
+ echo "❌ Error: unsupported monitoring provider '$1'. Supported: $SUPPORTED_STACKS." >&2
+ exit 1
+ ;;
+ esac
+}
+
+if [ -n "$STACK_ARG" ]; then
+ normalize_stack "$STACK_ARG" > /dev/null
fi
-# Start monitoring services
-echo "🐳 Starting monitoring services..."
-docker-compose -f "$SCRIPT_DIR/docker-compose-monitoring.yml" --env-file "$MONITORING_DIR/monitoring.env" up -d
+remove_containers() {
+ if [ "$#" -eq 0 ]; then
+ return
+ fi
+
+ local existing=()
+ local container
+ for container in "$@"; do
+ if docker ps -a --format '{{.Names}}' | grep -qx "$container"; then
+ existing+=("$container")
+ fi
+ done
-# Wait for services to be ready
-echo "⏳ Waiting for services to start..."
-sleep 10
+ if [ "${#existing[@]}" -gt 0 ]; then
+ docker rm -f "${existing[@]}" > /dev/null
+ echo "🧹 Removed containers: ${existing[*]}"
+ fi
+}
-# Check service health with timeout
-echo "🔍 Checking service health..."
+remove_volumes() {
+ if [ "$#" -eq 0 ]; then
+ return
+ fi
+
+ local existing=()
+ local volume
+ for volume in "$@"; do
+ if docker volume ls --format '{{.Name}}' | grep -qx "$volume"; then
+ existing+=("$volume")
+ fi
+ done
+
+ if [ "${#existing[@]}" -gt 0 ]; then
+ docker volume rm "${existing[@]}" > /dev/null
+ echo "🧹 Removed volumes: ${existing[*]}"
+ fi
+}
+
+stack_containers() {
+ case "$1" in
+ collector|langsmith)
+ echo "nexent-otel-collector"
+ ;;
+ phoenix)
+ echo "nexent-otel-collector nexent-phoenix"
+ ;;
+ langfuse)
+ echo "nexent-otel-collector nexent-langfuse-worker nexent-langfuse-web nexent-langfuse-clickhouse nexent-langfuse-minio nexent-langfuse-redis nexent-langfuse-postgres"
+ ;;
+ grafana)
+ echo "nexent-otel-collector nexent-grafana nexent-tempo"
+ ;;
+ zipkin)
+ echo "nexent-otel-collector nexent-zipkin"
+ ;;
+ esac
+}
+
+stack_data_volumes() {
+ case "$1" in
+ phoenix)
+ echo "monitor_phoenix-data"
+ ;;
+ langfuse)
+ echo "monitor_langfuse-postgres-data monitor_langfuse-clickhouse-data monitor_langfuse-clickhouse-logs monitor_langfuse-minio-data monitor_langfuse-redis-data"
+ ;;
+ grafana)
+ echo "monitor_grafana-data monitor_tempo-data"
+ ;;
+ collector|langsmith|zipkin)
+ echo ""
+ ;;
+ esac
+}
+
+all_backend_containers() {
+ echo "nexent-phoenix nexent-langfuse-worker nexent-langfuse-web nexent-langfuse-clickhouse nexent-langfuse-minio nexent-langfuse-redis nexent-langfuse-postgres nexent-grafana nexent-tempo nexent-zipkin"
+}
+
+incompatible_containers() {
+ local stack="$1"
+ local containers
+ containers="$(all_backend_containers)"
+ case "$stack" in
+ phoenix)
+ echo "$containers" | sed 's/nexent-phoenix//g'
+ ;;
+ langfuse)
+ echo "$containers" | sed 's/nexent-langfuse-worker//g; s/nexent-langfuse-web//g; s/nexent-langfuse-clickhouse//g; s/nexent-langfuse-minio//g; s/nexent-langfuse-redis//g; s/nexent-langfuse-postgres//g'
+ ;;
+ grafana)
+ echo "$containers" | sed 's/nexent-grafana//g; s/nexent-tempo//g'
+ ;;
+ zipkin)
+ echo "$containers" | sed 's/nexent-zipkin//g'
+ ;;
+ collector|langsmith)
+ echo "$containers"
+ ;;
+ esac
+}
+
+configure_stack() {
+ MONITORING_PROVIDER="${STACK_ARG:-${MONITORING_PROVIDER:-otlp}}"
+ LOCAL_STACK="$(normalize_stack "$MONITORING_PROVIDER")"
+
+ case "$LOCAL_STACK" in
+ collector)
+ BACKEND_MONITORING_PROVIDER="otlp"
+ OTEL_COLLECTOR_CONFIG_FILE="${OTEL_COLLECTOR_CONFIG_FILE:-./monitoring/otel-collector-config.yml}"
+ COMPOSE_PROFILES=()
+ ;;
+ phoenix)
+ BACKEND_MONITORING_PROVIDER="phoenix"
+ OTEL_COLLECTOR_CONFIG_FILE="${OTEL_COLLECTOR_CONFIG_FILE:-./monitoring/otel-collector-phoenix-config.yml}"
+ COMPOSE_PROFILES=(--profile phoenix)
+ ;;
+ langfuse)
+ BACKEND_MONITORING_PROVIDER="langfuse"
+ OTEL_COLLECTOR_CONFIG_FILE="${OTEL_COLLECTOR_CONFIG_FILE:-./monitoring/otel-collector-langfuse-config.yml}"
+ COMPOSE_PROFILES=(--profile langfuse)
+ LANGFUSE_INIT_PROJECT_PUBLIC_KEY="${LANGFUSE_INIT_PROJECT_PUBLIC_KEY:-pk-lf-nexent-local}"
+ LANGFUSE_INIT_PROJECT_SECRET_KEY="${LANGFUSE_INIT_PROJECT_SECRET_KEY:-sk-lf-nexent-local}"
+ if [ -z "${LANGFUSE_OTLP_AUTH_HEADER:-}" ]; then
+ LANGFUSE_OTLP_AUTH_HEADER="Basic $(printf "%s:%s" "$LANGFUSE_INIT_PROJECT_PUBLIC_KEY" "$LANGFUSE_INIT_PROJECT_SECRET_KEY" | base64 | tr -d '\n')"
+ fi
+ export LANGFUSE_OTLP_AUTH_HEADER
+ ;;
+ langsmith)
+ BACKEND_MONITORING_PROVIDER="langsmith"
+ OTEL_COLLECTOR_CONFIG_FILE="${OTEL_COLLECTOR_CONFIG_FILE:-./monitoring/otel-collector-langsmith-config.yml}"
+ COMPOSE_PROFILES=()
+ LANGSMITH_OTLP_TRACES_ENDPOINT="${LANGSMITH_OTLP_TRACES_ENDPOINT:-https://api.smith.langchain.com/otel/v1/traces}"
+ LANGSMITH_PROJECT="${LANGSMITH_PROJECT:-nexent}"
+ if [ "$ACTION" = "start" ] && [ -z "${LANGSMITH_API_KEY:-}" ]; then
+ echo "❌ Error: LANGSMITH_API_KEY is required for the langsmith stack."
+ echo " Set it in $MONITORING_DIR/monitoring.env or export it before running this script."
+ exit 1
+ fi
+ export LANGSMITH_API_KEY LANGSMITH_PROJECT LANGSMITH_OTLP_TRACES_ENDPOINT
+ ;;
+ grafana)
+ BACKEND_MONITORING_PROVIDER="grafana"
+ OTEL_COLLECTOR_CONFIG_FILE="${OTEL_COLLECTOR_CONFIG_FILE:-./monitoring/otel-collector-grafana-config.yml}"
+ COMPOSE_PROFILES=(--profile grafana)
+ ;;
+ zipkin)
+ BACKEND_MONITORING_PROVIDER="zipkin"
+ OTEL_COLLECTOR_CONFIG_FILE="${OTEL_COLLECTOR_CONFIG_FILE:-./monitoring/otel-collector-zipkin-config.yml}"
+ COMPOSE_PROFILES=(--profile zipkin)
+ ;;
+ esac
+ export OTEL_COLLECTOR_CONFIG_FILE
+}
+
+dashboard_url() {
+ case "$LOCAL_STACK" in
+ phoenix)
+ echo "http://localhost:${PHOENIX_PORT:-6006}"
+ ;;
+ langfuse)
+ echo "http://localhost:${LANGFUSE_PORT:-3001}"
+ ;;
+ langsmith)
+ echo "https://smith.langchain.com/"
+ ;;
+ grafana)
+ echo "http://localhost:${GRAFANA_PORT:-3002}/d/nexent-llm-agent/nexent-agent-trace-monitoring?orgId=1"
+ ;;
+ zipkin)
+ echo "http://localhost:${ZIPKIN_PORT:-9411}"
+ ;;
+ collector)
+ echo ""
+ ;;
+ esac
+}
+
+print_access_hints() {
+ local dashboard
+ dashboard="$(dashboard_url)"
+
+ echo ""
+ echo "📊 Access your monitoring tools:"
+ echo " • OTLP HTTP receiver: http://localhost:${OTEL_COLLECTOR_HTTP_PORT:-4318}"
+ echo " • OTLP gRPC receiver: localhost:${OTEL_COLLECTOR_GRPC_PORT:-4317}"
+ echo " • Docker backend endpoint: http://otel-collector:4318"
+
+ case "$LOCAL_STACK" in
+ phoenix)
+ echo " • Phoenix UI: $dashboard"
+ echo " • Phoenix direct gRPC ingest: localhost:${PHOENIX_GRPC_HOST_PORT:-4319}"
+ ;;
+ langfuse)
+ echo " • Langfuse UI: $dashboard"
+ echo " • Langfuse admin: ${LANGFUSE_INIT_USER_EMAIL:-admin@nexent.com} / ${LANGFUSE_INIT_USER_PASSWORD:-nexent@4321}"
+ echo " • Langfuse project keys: ${LANGFUSE_INIT_PROJECT_PUBLIC_KEY:-pk-lf-nexent-local} / ${LANGFUSE_INIT_PROJECT_SECRET_KEY:-sk-lf-nexent-local}"
+ echo " • MinIO API: http://localhost:${LANGFUSE_MINIO_API_PORT:-9092}"
+ echo " • MinIO console: http://localhost:${LANGFUSE_MINIO_CONSOLE_PORT:-9093}"
+ ;;
+ langsmith)
+ echo " • LangSmith UI: $dashboard"
+ echo " • LangSmith project: ${LANGSMITH_PROJECT:-nexent}"
+ echo " • LangSmith OTLP traces endpoint: ${LANGSMITH_OTLP_TRACES_ENDPOINT:-https://api.smith.langchain.com/otel/v1/traces}"
+ echo " • No local LangSmith UI is started; open the hosted UI and select the project above."
+ ;;
+ grafana)
+ echo " • Grafana dashboard: $dashboard"
+ echo " • Grafana home: http://localhost:${GRAFANA_PORT:-3002}"
+ echo " • Grafana admin: ${GRAFANA_ADMIN_USER:-admin} / ${GRAFANA_ADMIN_PASSWORD:-nexent@4321}"
+ echo " • Tempo API: http://localhost:${TEMPO_PORT:-3200}"
+ ;;
+ zipkin)
+ echo " • Zipkin UI: $dashboard"
+ ;;
+ collector)
+ echo " • Collector-only mode has no monitoring UI."
+ echo " • View Collector logs: docker logs -f nexent-otel-collector"
+ echo " • Configure Phoenix, Langfuse, LangSmith, Grafana/Tempo, Zipkin, or another OTLP backend when you need a UI."
+ ;;
+ esac
+
+ echo ""
+ echo "🔗 Frontend monitoring entry:"
+ if [ -n "$dashboard" ]; then
+ echo " Set MONITORING_DASHBOARD_URL=$dashboard"
+ else
+ echo " Leave MONITORING_DASHBOARD_URL empty to hide the monitoring entry."
+ fi
+}
+
+print_backend_hints() {
+ echo ""
+ echo "🔧 To enable monitoring in your Nexent backend:"
+ echo " 1. Set ENABLE_TELEMETRY=true in docker/.env"
+ echo " 2. Set MONITORING_PROVIDER=$BACKEND_MONITORING_PROVIDER in docker/.env"
+ echo " 3. Set OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 for Docker services"
+ echo " or http://localhost:${OTEL_COLLECTOR_HTTP_PORT:-4318} for a backend running on the host"
+ echo " 4. Set MONITORING_DASHBOARD_URL as shown above when a UI is available"
+ echo " 5. Install performance dependencies:"
+ echo " uv sync --extra performance"
+ echo " 6. Restart your Nexent backend service"
+}
+
+print_uninstall_hints() {
+ echo ""
+ echo "🛑 Stop or uninstall this monitoring stack:"
+ echo " • Stop containers and keep data:"
+ echo " $(basename "$0") stop $LOCAL_STACK"
+ echo " • Remove containers and this stack's data volumes:"
+ echo " $(basename "$0") uninstall $LOCAL_STACK"
+ echo ""
+ echo " Stacks are mutually exclusive; do not run multiple monitoring providers in parallel."
+}
+
+load_env_for_start() {
+ if [ ! -f "$MONITORING_DIR/monitoring.env" ]; then
+ echo "📋 Creating monitoring.env from example..."
+ cp "$MONITORING_DIR/monitoring.env.example" "$MONITORING_DIR/monitoring.env"
+ echo "⚠️ Please review and update $MONITORING_DIR/monitoring.env as needed"
+ fi
+
+ set -a
+ # shellcheck disable=SC1091
+ . "$MONITORING_DIR/monitoring.env"
+ set +a
+}
+
+load_env_if_present() {
+ if [ -f "$MONITORING_DIR/monitoring.env" ]; then
+ set -a
+ # shellcheck disable=SC1091
+ . "$MONITORING_DIR/monitoring.env"
+ set +a
+ fi
+}
+
+resolve_compose_cmd() {
+ if docker compose version > /dev/null 2>&1; then
+ COMPOSE_CMD=(docker compose)
+ elif command -v docker-compose > /dev/null 2>&1; then
+ COMPOSE_CMD=(docker-compose)
+ else
+ echo "❌ Error: Docker Compose is not installed."
+ exit 1
+ fi
+}
-# Function to check service health with timeout
check_service() {
local name=$1
local url=$2
local port=$3
-
+
if curl -s --max-time 5 --connect-timeout 3 "$url" > /dev/null 2>&1; then
echo "✅ $name is running at http://localhost:$port"
return 0
@@ -57,33 +424,123 @@ check_service() {
fi
}
-# Check Jaeger
-check_service "Jaeger" "http://localhost:16686/api/services" "16686" || true
-
-# Check Prometheus
-check_service "Prometheus" "http://localhost:9090/-/healthy" "9090" || true
-
-# Check Grafana
-check_service "Grafana" "http://localhost:3005/api/health" "3005" || true
-
-echo ""
-echo "🎉 Monitoring setup complete!"
-echo ""
-echo "📊 Access your monitoring tools:"
-echo " • Jaeger UI: http://localhost:16686"
-echo " • Prometheus: http://localhost:9090"
-echo " • Grafana: http://localhost:3005 (admin/admin)"
-echo ""
-echo "🔧 To enable monitoring in your Nexent backend:"
-echo " 1. Set ENABLE_TELEMETRY=true in your .env file"
-echo " 2. Install performance dependencies:"
-echo " uv sync --extra performance"
-echo " 3. Restart your Nexent backend service"
-echo ""
-echo "📈 Key Metrics to Monitor:"
-echo " • Token Generation Rate (tokens/second)"
-echo " • Time to First Token (TTFT)"
-echo " • Request Duration"
-echo " • Error Rates"
-echo ""
-echo "🛑 To stop monitoring services: docker-compose -f docker-compose-monitoring.yml down"
+check_stack_health() {
+ echo "🔍 Checking service health..."
+ check_service "OpenTelemetry Collector HTTP receiver" "http://localhost:${OTEL_COLLECTOR_HTTP_PORT:-4318}" "${OTEL_COLLECTOR_HTTP_PORT:-4318}" || true
+
+ case "$LOCAL_STACK" in
+ phoenix)
+ check_service "Phoenix UI" "http://localhost:${PHOENIX_PORT:-6006}" "${PHOENIX_PORT:-6006}" || true
+ ;;
+ langfuse)
+ check_service "Langfuse UI" "http://localhost:${LANGFUSE_PORT:-3001}" "${LANGFUSE_PORT:-3001}" || true
+ ;;
+ langsmith)
+ echo "✅ LangSmith forwarding is configured for project: ${LANGSMITH_PROJECT:-nexent}"
+ ;;
+ grafana)
+ check_service "Grafana" "http://localhost:${GRAFANA_PORT:-3002}/api/health" "${GRAFANA_PORT:-3002}" || true
+ check_service "Tempo API" "http://localhost:${TEMPO_PORT:-3200}/ready" "${TEMPO_PORT:-3200}" || true
+ ;;
+ zipkin)
+ check_service "Zipkin UI" "http://localhost:${ZIPKIN_PORT:-9411}" "${ZIPKIN_PORT:-9411}" || true
+ ;;
+ esac
+}
+
+start_stack() {
+ echo "🚀 Starting Nexent LLM Performance Monitoring Setup..."
+
+ if ! docker info > /dev/null 2>&1; then
+ echo "❌ Error: Docker is not running. Please start Docker first."
+ exit 1
+ fi
+
+ resolve_compose_cmd
+
+ if ! docker network ls --format '{{.Name}}' | grep -qx nexent_network; then
+ echo "🔗 Creating nexent_network..."
+ docker network create nexent_network
+ else
+ echo "✅ nexent_network already exists"
+ fi
+
+ load_env_for_start
+ configure_stack
+
+ local incompatible
+ incompatible="$(incompatible_containers "$LOCAL_STACK")"
+ if [ -n "$incompatible" ]; then
+ # shellcheck disable=SC2086
+ remove_containers $incompatible
+ fi
+
+ echo "🐳 Starting monitoring services with provider: $MONITORING_PROVIDER"
+ echo " Selected stack: $LOCAL_STACK"
+ "${COMPOSE_CMD[@]}" -f "$COMPOSE_FILE" --env-file "$MONITORING_DIR/monitoring.env" "${COMPOSE_PROFILES[@]}" up -d --remove-orphans
+
+ echo "⏳ Waiting for services to start..."
+ sleep 10
+ check_stack_health
+
+ echo ""
+ echo "🎉 Monitoring setup complete!"
+ print_access_hints
+ print_backend_hints
+ echo ""
+ echo "🔎 Key Trace Data to Inspect:"
+ echo " • Agent span hierarchy"
+ echo " • LLM generation spans"
+ echo " • Retriever and memory spans"
+ echo " • Tool call spans"
+ echo " • Error events"
+ print_uninstall_hints
+}
+
+stop_or_uninstall_stack() {
+ local remove_data="$1"
+
+ if ! docker info > /dev/null 2>&1; then
+ echo "❌ Error: Docker is not running. Please start Docker first."
+ exit 1
+ fi
+
+ load_env_if_present
+ configure_stack
+
+ local containers
+ containers="$(stack_containers "$LOCAL_STACK")"
+ echo "🛑 Removing monitoring containers for stack: $LOCAL_STACK"
+ # shellcheck disable=SC2086
+ remove_containers $containers
+
+ if [ "$remove_data" = "true" ]; then
+ local volumes
+ volumes="$(stack_data_volumes "$LOCAL_STACK")"
+ if [ -n "$volumes" ]; then
+ echo "🧹 Removing data volumes for stack: $LOCAL_STACK"
+ # shellcheck disable=SC2086
+ remove_volumes $volumes
+ else
+ echo "ℹ️ Stack '$LOCAL_STACK' has no dedicated local data volumes."
+ fi
+ echo "✅ Monitoring stack '$LOCAL_STACK' has been uninstalled."
+ else
+ echo "✅ Monitoring stack '$LOCAL_STACK' has been stopped. Data volumes were kept."
+ fi
+
+ echo ""
+ echo "ℹ️ The shared Docker network 'nexent_network' is kept because it is also used by Nexent services."
+}
+
+case "$ACTION" in
+ start)
+ start_stack
+ ;;
+ stop)
+ stop_or_uninstall_stack false
+ ;;
+ uninstall)
+ stop_or_uninstall_stack true
+ ;;
+esac
diff --git a/docker/uninstall.sh b/docker/uninstall.sh
old mode 100644
new mode 100755
index a37ec3bf9..801a9f4f7
--- a/docker/uninstall.sh
+++ b/docker/uninstall.sh
@@ -1,13 +1,240 @@
#!/bin/bash
-docker rm -f nexent
-docker rm -f nexent-postgresql
-docker rm -f nexent-minio
-docker rm -f nexent-elasticsearch
-docker rm -f nexent-data-process
-docker rm -f nexent-web
-docker rm -f nexent-redis
-docker rm -f supabase-kong-mini
-docker rm -f supabase-auth-mini
-docker rm -f supabase-db-mini
-docker network rm nexent_nexent
\ No newline at end of file
+if [ -z "$BASH_VERSION" ]; then
+ echo "❌ This script must be run with bash. Please use: bash uninstall.sh or ./uninstall.sh"
+ exit 1
+fi
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+DELETE_VOLUMES=""
+
+print_usage() {
+ echo "Usage: $0 [delete-all] [options]"
+ echo ""
+ echo "Uninstall Docker deployment for Nexent."
+ echo ""
+ echo "Options:"
+ echo " --delete-volumes true|false Control whether persistent data is removed"
+ echo " --remove-volumes Alias for --delete-volumes true"
+ echo " --keep-volumes Alias for --delete-volumes false"
+ echo " --help, -h Show this help message"
+ echo ""
+ echo "Examples:"
+ echo " bash uninstall.sh"
+ echo " bash uninstall.sh --delete-volumes false"
+ echo " bash uninstall.sh --delete-volumes true"
+ echo " bash uninstall.sh delete-all"
+}
+
+sanitize_input() {
+ local input="$1"
+ printf "%s" "$input" | tr -d '\r'
+}
+
+parse_bool_option() {
+ local value
+ value="$(sanitize_input "${1:-}")"
+ case "$value" in
+ true|TRUE|True|yes|YES|Yes|y|Y|1) return 0 ;;
+ false|FALSE|False|no|NO|No|n|N|0) return 1 ;;
+ *)
+ echo "❌ Invalid boolean value: $value. Use true or false."
+ exit 1
+ ;;
+ esac
+}
+
+while [[ $# -gt 0 ]]; do
+ case "$1" in
+ delete-all)
+ DELETE_VOLUMES="true"
+ shift
+ ;;
+ --delete-volumes)
+ DELETE_VOLUMES="$2"
+ shift 2
+ ;;
+ --remove-volumes)
+ DELETE_VOLUMES="true"
+ shift
+ ;;
+ --keep-volumes)
+ DELETE_VOLUMES="false"
+ shift
+ ;;
+ --help|-h)
+ print_usage
+ exit 0
+ ;;
+ *)
+ echo "❌ Unknown option: $1"
+ print_usage
+ exit 1
+ ;;
+ esac
+done
+
+if [ -f ".env" ]; then
+ set -a
+ # shellcheck source=/dev/null
+ source .env
+ set +a
+fi
+
+if [ -f ".env.generated" ]; then
+ set -a
+ # shellcheck source=/dev/null
+ source .env.generated
+ set +a
+fi
+
+get_compose_version() {
+ if command -v docker &> /dev/null; then
+ local version_output
+ version_output=$(docker compose version 2>/dev/null)
+ if [[ $version_output =~ v([0-9]+\.[0-9]+\.[0-9]+) ]]; then
+ echo "v2 ${BASH_REMATCH[1]}"
+ return 0
+ fi
+ fi
+
+ if command -v docker-compose &> /dev/null; then
+ local version_output
+ version_output=$(docker-compose --version 2>/dev/null)
+ if [[ $version_output =~ ([0-9]+\.[0-9]+\.[0-9]+) ]]; then
+ echo "v1 ${BASH_REMATCH[1]}"
+ return 0
+ fi
+ fi
+
+ echo "unknown"
+ return 0
+}
+
+resolve_compose_command() {
+ local version_info
+ version_info="$(get_compose_version)"
+ if [[ $version_info == "unknown" ]]; then
+ echo "❌ Docker Compose not found or version detection failed"
+ exit 1
+ fi
+
+ local version_type version_number
+ version_type="$(echo "$version_info" | awk '{print $1}')"
+ version_number="$(echo "$version_info" | awk '{print $2}')"
+
+ case "$version_type" in
+ v1)
+ if [[ $version_number < "1.28.0" ]]; then
+ echo "❌ Docker Compose V1 version is too old; please upgrade to V1.28.0+ or V2."
+ exit 1
+ fi
+ docker_compose_command="docker-compose"
+ ;;
+ v2)
+ docker_compose_command="docker compose"
+ ;;
+ *)
+ echo "❌ Unknown Docker Compose version type: $version_type"
+ exit 1
+ ;;
+ esac
+}
+
+resolve_delete_volumes() {
+ if [ -n "$DELETE_VOLUMES" ]; then
+ parse_bool_option "$DELETE_VOLUMES"
+ return $?
+ fi
+
+ [ -t 0 ] || return 1
+
+ echo ""
+ echo "🧹 Delete Docker volumes and Nexent data directories?"
+ echo " This removes persistent data under ROOT_DIR, including elasticsearch, postgresql, redis, minio, scripts, and supabase volumes."
+ local answer
+ read -r -p " Delete data volumes? [y/N]: " answer
+ answer="$(sanitize_input "$answer")"
+ [[ "$answer" =~ ^[Yy]$ ]]
+}
+
+docker_compose_down_file() {
+ local compose_file="$1"
+ local use_project_name="$2"
+ local remove_volumes="$3"
+
+ [ -f "$compose_file" ] || return 0
+
+ local volume_args=()
+ if [ "$remove_volumes" = "true" ]; then
+ volume_args=(-v)
+ fi
+
+ if [ "$use_project_name" = "true" ]; then
+ $docker_compose_command -p nexent -f "$compose_file" down --remove-orphans "${volume_args[@]}" || true
+ else
+ $docker_compose_command -f "$compose_file" down --remove-orphans "${volume_args[@]}" || true
+ fi
+}
+
+remove_nexent_data_dirs() {
+ local root_dir="${ROOT_DIR:-$HOME/nexent-data}"
+ root_dir="${root_dir%/}"
+
+ if [ -z "$root_dir" ] || [ "$root_dir" = "/" ]; then
+ echo "❌ Refusing to remove unsafe ROOT_DIR: ${root_dir:-}"
+ return 1
+ fi
+
+ local dirs=(
+ "$root_dir/elasticsearch"
+ "$root_dir/postgresql"
+ "$root_dir/redis"
+ "$root_dir/minio"
+ "$root_dir/volumes"
+ "$root_dir/openssh-server"
+ "$root_dir/scripts"
+ )
+
+ local dir
+ for dir in "${dirs[@]}"; do
+ if [ -e "$dir" ]; then
+ echo "🧹 Removing data directory: $dir"
+ rm -rf "$dir"
+ fi
+ done
+}
+
+main() {
+ local remove_volumes="false"
+ if resolve_delete_volumes; then
+ remove_volumes="true"
+ fi
+
+ resolve_compose_command
+
+ echo "🛑 Stopping and removing Docker deployment..."
+ if [ "$remove_volumes" = "true" ]; then
+ echo "⚠️ Data volumes will be deleted."
+ else
+ echo "ℹ️ Data volumes will be preserved."
+ fi
+
+ docker_compose_down_file "docker-compose-monitoring.yml" false "$remove_volumes"
+ docker_compose_down_file "docker-compose-supabase.prod.yml" true "$remove_volumes"
+ docker_compose_down_file "docker-compose-supabase.yml" true "$remove_volumes"
+ docker_compose_down_file "docker-compose.prod.yml" true "$remove_volumes"
+ docker_compose_down_file "docker-compose.yml" true "$remove_volumes"
+
+ if [ "$remove_volumes" = "true" ]; then
+ remove_nexent_data_dirs
+ fi
+
+ echo "✅ Docker deployment removed."
+}
+
+main
diff --git a/frontend/app/[locale]/agents/AgentVersionCard.tsx b/frontend/app/[locale]/agents/AgentVersionCard.tsx
index 5eaa0e1e0..4ef6f052e 100644
--- a/frontend/app/[locale]/agents/AgentVersionCard.tsx
+++ b/frontend/app/[locale]/agents/AgentVersionCard.tsx
@@ -39,11 +39,13 @@ import type { Agent, Tool } from "@/types/agentConfig";
import { useToolList } from "@/hooks/agent/useToolList";
import { useAgentList } from "@/hooks/agent/useAgentList";
import { useAgentVersionList } from "@/hooks/agent/useAgentVersionList";
-import { useAgentInfo } from "@/hooks/agent/useAgentInfo";
import { useAgentVersionDetail } from "@/hooks/agent/useAgentVersionDetail";
import { rollbackVersion, compareVersions, deleteVersion } from "@/services/agentVersionService";
+import { searchAgentInfo } from "@/services/agentConfigService";
+import { useAgentConfigStore } from "@/stores/agentConfigStore";
import { useAuthorizationContext } from "@/components/providers/AuthorizationProvider";
import log from "@/lib/logger";
+import { resolveAgentListTenantKey } from "@/lib/agentListTenant";
import { message } from "antd";
import { useQueryClient } from "@tanstack/react-query";
import AgentVersionCompareModal from "./versions/AgentVersionCompareModal";
@@ -139,7 +141,6 @@ export function VersionCardItem({
// Get invalidate functions for refreshing data
const { agentVersionList, invalidate: invalidateAgentVersionList } = useAgentVersionList(agentId);
- const { invalidate: invalidateAgentInfo } = useAgentInfo(agentId);
// Fetch version detail when expanded
const { agentVersionDetail } = useAgentVersionDetail(
@@ -148,7 +149,7 @@ export function VersionCardItem({
);
const { tools: toolList } = useToolList();
- const { agents: agentList } = useAgentList(user?.tenantId ?? null);
+ const { agents: agentList } = useAgentList("");
// Get current agent's permission from agent list
const currentAgent = useMemo(() => {
@@ -246,8 +247,18 @@ export function VersionCardItem({
message.success(t("agent.version.rollbackSuccess"));
setCompareModalOpen(false);
invalidateAgentVersionList?.();
- invalidateAgentInfo?.();
+ queryClient.invalidateQueries({ queryKey: ["agentInfo", agentId] });
queryClient.invalidateQueries({ queryKey: ["agents"] });
+
+ // Refresh agent detail and sync to Zustand store
+ const store = useAgentConfigStore.getState();
+ if (store.currentAgentId === agentId) {
+ const agentResult = await searchAgentInfo(agentId);
+ if (agentResult.success && agentResult.data) {
+ store.setCurrentAgent(agentResult.data);
+ store.triggerForceRefresh();
+ }
+ }
} else {
message.error(result.message || t("agent.version.rollbackError"));
}
@@ -282,7 +293,7 @@ export function VersionCardItem({
message.success(t("agent.version.deleteSuccess"));
setDeleteModalOpen(false);
invalidateAgentVersionList?.();
- invalidateAgentInfo?.();
+ queryClient.invalidateQueries({ queryKey: ["agentInfo", agentId] });
queryClient.invalidateQueries({ queryKey: ["agents"] });
} else {
message.error(result.message || t("agent.version.deleteError"));
@@ -579,6 +590,7 @@ export function VersionCardItem({
initialValues={{
version_name: version.version_name,
release_note: version.release_note,
+ is_a2a: version.is_a2a,
}}
onUpdated={() => {
// Refresh version list using the proper invalidate function
diff --git a/frontend/app/[locale]/agents/components/AgentConfigComp.tsx b/frontend/app/[locale]/agents/components/AgentConfigComp.tsx
index 3a60e146d..1e750d5eb 100644
--- a/frontend/app/[locale]/agents/components/AgentConfigComp.tsx
+++ b/frontend/app/[locale]/agents/components/AgentConfigComp.tsx
@@ -1,6 +1,6 @@
"use client";
-import { useState, useCallback, useEffect } from "react";
+import { useState, useCallback } from "react";
import { useTranslation } from "react-i18next";
import { App, Button, Row, Col, Flex, Tooltip, Badge, Divider } from "antd";
import CollaborativeAgent from "./agentConfig/CollaborativeAgent";
@@ -12,12 +12,12 @@ import { updateToolList } from "@/services/mcpService";
import { useAgentConfigStore } from "@/stores/agentConfigStore";
import { useToolList } from "@/hooks/agent/useToolList";
import { useSkillList } from "@/hooks/agent/useSkillList";
-import { useAgentSkillInstances } from "@/hooks/agent/useAgentSkillInstances";
import { useExternalAgents } from "@/hooks/agent/useExternalAgents";
import McpConfigModal from "./agentConfig/McpConfigModal";
import A2AAgentDiscoveryModal from "./a2a/A2AAgentDiscoveryModal";
import { RefreshCw, Lightbulb, Plug, BlocksIcon, Globe } from "lucide-react";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
interface AgentConfigCompProps {}
@@ -28,26 +28,21 @@ export default function AgentConfigComp({}: AgentConfigCompProps) {
// Get state from store
const currentAgentId = useAgentConfigStore((state) => state.currentAgentId);
const isCreatingMode = useAgentConfigStore((state) => state.isCreatingMode);
+ const isReadOnly = useAgentConfigStore((state) => state.isReadOnly());
+ const selectedTools = useAgentConfigStore((state) => state.editedAgent.tools);
+ const selectedSkills = useAgentConfigStore((state) => state.editedAgent.skills);
const [isMcpModalOpen, setIsMcpModalOpen] = useState(false);
const [isSkillModalOpen, setIsSkillModalOpen] = useState(false);
const [isRefreshing, setIsRefreshing] = useState(false);
const [isRefreshingSkill, setIsRefreshingSkill] = useState(false);
const [showA2ADiscovery, setShowA2ADiscovery] = useState(false);
+ const showLegacyMcpConfig = false;
+
+ // Use tool list hook for data management
const { groupedTools, invalidate } = useToolList();
const { groupedSkills, invalidate: invalidateSkills } = useSkillList();
- const { skillInstances, invalidate: invalidateSkillInstances } = useAgentSkillInstances(
- currentAgentId ?? null
- );
const { invalidate: invalidateExternalAgents } = useExternalAgents();
- const setInitialSkills = useAgentConfigStore((state) => state.setInitialSkills);
-
- // Load skill instances when agent changes
- useEffect(() => {
- if (currentAgentId && skillInstances.length > 0) {
- setInitialSkills(skillInstances);
- }
- }, [currentAgentId, skillInstances, setInitialSkills]);
const handleRefreshTools = useCallback(async () => {
setIsRefreshing(true);
@@ -72,21 +67,17 @@ export default function AgentConfigComp({}: AgentConfigCompProps) {
setIsRefreshingSkill(true);
try {
invalidateSkills();
- invalidateSkillInstances();
message.success(t("skillManagement.message.refreshSuccess"));
} catch (error) {
message.error(t("skillManagement.message.refreshFailed"));
} finally {
setIsRefreshingSkill(false);
}
- }, [invalidateSkills, invalidateSkillInstances]);
+ }, [invalidateSkills]);
const handleSkillBuildSuccess = useCallback(() => {
invalidateSkills();
- if (currentAgentId) {
- invalidateSkillInstances();
- }
- }, [invalidateSkills, invalidateSkillInstances, currentAgentId]);
+ }, [invalidateSkills]);
return (
<>
@@ -95,15 +86,15 @@ export default function AgentConfigComp({}: AgentConfigCompProps) {
- {t("businessLogic.config.title")}
+ {t("businessLogic.config.title")}
+
{t("collaborativeAgent.title")}
@@ -116,7 +107,6 @@ export default function AgentConfigComp({}: AgentConfigCompProps) {
size="small"
icon={
-
+
-
-
- {t("toolPool.title")}
- {t("toolPool.tooltip.functionGuide")}}
- color="#ffffff"
- styles={{
- root: {
- backgroundColor: "#ffffff",
- border: "1px solid #e5e7eb",
- borderRadius: "6px",
- boxShadow: "0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)",
- maxWidth: "800px",
- minWidth: "700px",
- width: "fit-content",
- },
- }}
- >
-
-
-
-
- }
- onClick={handleRefreshTools}
- loading={isRefreshing}
- className="text-green-500 hover:!text-green-600 hover:!bg-green-50"
- title={t("toolManagement.refresh.title")}
- >
- {t("toolManagement.refresh.button.refresh")}
-
- }
- onClick={() => setIsMcpModalOpen(true)}
- className="text-blue-500 hover:!text-blue-600 hover:!bg-blue-50"
- title={t("toolManagement.mcp.title")}
- >
- {t("toolManagement.mcp.button")}
-
-
-
-
-
+
+
+
+ {t("toolPool.title")}
+ {selectedTools.length > 0 && (
+ {t("toolPool.tooltip.functionGuide")}}
+ color="#ffffff"
+ styles={{
+ root: {
+ backgroundColor: "#ffffff",
+ border: "1px solid #e5e7eb",
+ borderRadius: "6px",
+ boxShadow: "0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)",
+ maxWidth: "800px",
+ minWidth: "700px",
+ width: "fit-content",
+ },
+ }}
+ >
+
+
+
+
+ {t("skillPool.title")}
+ {selectedSkills && selectedSkills.length > 0 && (
+
+
-
-
+
-
-
- {t("skillPool.title")}
-
-
-
- }
- onClick={handleRefreshSkills}
- loading={isRefreshingSkill}
- className="text-green-500 hover:!text-green-600 hover:!bg-green-50"
- title={t("skillManagement.refresh.title")}
- >
- {t("skillManagement.refresh.button")}
-
- }
- onClick={() => setIsSkillModalOpen(true)}
- className="text-blue-500 hover:!text-blue-600 hover:!bg-blue-50"
- title={t("skillManagement.build.title")}
- >
- {t("skillManagement.build.button")}
-
-
-
-
+
+
+ }
+ onClick={handleRefreshTools}
+ loading={isRefreshing}
+ className="text-green-500 hover:!text-green-600 hover:!bg-green-50"
+ title={t("toolManagement.refresh.title")}
+ >
+ {t("toolManagement.refresh.button.refresh")}
+
+ }
+ onClick={() => setIsMcpModalOpen(true)}
+ className="text-blue-500 hover:!text-blue-600 hover:!bg-blue-50"
+ title={t("toolManagement.mcp.title")}
+ >
+ {t("toolManagement.mcp.button")}
+
+
+
+
-
+
+
-
-
+
+
+
+ }
+ onClick={handleRefreshSkills}
+ loading={isRefreshingSkill}
+ className="text-green-500 hover:!text-green-600 hover:!bg-green-50"
+ title={t("skillManagement.refresh.title")}
+ >
+ {t("skillManagement.refresh.button")}
+
+ }
+ onClick={() => setIsSkillModalOpen(true)}
+ className="text-blue-500 hover:!text-blue-600 hover:!bg-blue-50"
+ title={t("skillManagement.build.title")}
+ >
+ {t("skillManagement.build.button")}
+
+
+
+
+
+
+
+
+
setIsMcpModalOpen(false)} />
diff --git a/frontend/app/[locale]/agents/components/AgentInfoComp.tsx b/frontend/app/[locale]/agents/components/AgentInfoComp.tsx
index 9a9cd37c0..b49842fb7 100644
--- a/frontend/app/[locale]/agents/components/AgentInfoComp.tsx
+++ b/frontend/app/[locale]/agents/components/AgentInfoComp.tsx
@@ -16,22 +16,12 @@ import { useAgentVersionDetail } from "@/hooks/agent/useAgentVersionDetail";
import { useAgentInfo } from "@/hooks/agent/useAgentInfo";
import AgentVersionPubulishModal from "../versions/AgentVersionPubulishModal";
-export interface AgentInfoCompProps {
- isShowVersionManagePanel: boolean;
- openVersionManagePanel: () => void;
- closeVersionManagementPanel: () => void;
-}
-
-export default function AgentInfoComp({
- isShowVersionManagePanel,
- openVersionManagePanel,
- closeVersionManagementPanel,
-}: AgentInfoCompProps) {
+export default function AgentInfoComp() {
const { t } = useTranslation("common");
const isCreatingMode = useAgentConfigStore((state) => state.isCreatingMode);
- const currentAgentPermission = useAgentConfigStore((state) => state.currentAgentPermission);
const currentAgentId = useAgentConfigStore((state) => state.currentAgentId);
+ const isGenerating = useAgentConfigStore((state) => state.isGenerating);
const isPanelActive = (currentAgentId != null && currentAgentId != undefined) || isCreatingMode;
const { agentVersionList, total, invalidate: invalidateAgentVersionList } = useAgentVersionList(currentAgentId);
@@ -42,8 +32,7 @@ export default function AgentInfoComp({
currentAgentId, agentInfo?.current_version_no
);
- const isReadOnly = isPanelActive && !isCreatingMode && currentAgentPermission === "READ_ONLY";
- const isEditable = isPanelActive && !isReadOnly;
+ const isReadOnly = useAgentConfigStore((state) => state.isReadOnly());
// Save guard hook
const saveGuard = useSaveGuard();
@@ -51,13 +40,14 @@ export default function AgentInfoComp({
// Debug drawer state
const [isDebugDrawerOpen, setIsDebugDrawerOpen] = useState(false);
- // Generation state shared with AgentGenerateDetail
- const [isGenerating, setIsGenerating] = useState(false);
-
const [isPublishModalOpen, setIsPublishModalOpen] = useState(false);
const handlePublishClick = () => {
- setIsPublishModalOpen(true);
+ saveGuard.saveWithModal().then((success) => {
+ if (success) {
+ setIsPublishModalOpen(true);
+ }
+ });
};
const handlePublished = () => {
@@ -79,54 +69,21 @@ export default function AgentInfoComp({
className="w-full"
>
-
+
{t("guide.steps.describeBusinessLogic.title")}
- }
- onClick={isShowVersionManagePanel ? closeVersionManagementPanel : openVersionManagePanel}
- type={isShowVersionManagePanel ? "primary" : "default"}
- >
- {t("agent.version.manage")}
-
-
-
- {agentVersionDetail?.version.version_name}
-
-
- {t("agent.version.totalVersions", { count: total ?? 0 })}
-
-
-
-
- )}
-
diff --git a/frontend/app/[locale]/agents/components/AgentManageComp.tsx b/frontend/app/[locale]/agents/components/AgentManageComp.tsx
index c636486ab..7dabff4dd 100644
--- a/frontend/app/[locale]/agents/components/AgentManageComp.tsx
+++ b/frontend/app/[locale]/agents/components/AgentManageComp.tsx
@@ -7,20 +7,22 @@ import { FileInput, Plus, X } from "lucide-react";
import AgentList from "./agentManage/AgentList";
import { useAgentConfigStore } from "@/stores/agentConfigStore";
-import { importAgent } from "@/services/agentConfigService";
-import { useMutation, useQueryClient } from "@tanstack/react-query";
import { useAgentList } from "@/hooks/agent/useAgentList";
import { useAuthorizationContext } from "@/components/providers/AuthorizationProvider";
import log from "@/lib/logger";
import { useState } from "react";
-import { ImportAgentData } from "@/hooks/useAgentImport";
+import {
+ parseAgentImportFile,
+ selectFile,
+ type ImportAgentData,
+} from "@/lib/agentImportUtils";
import AgentImportWizard from "@/components/agent/AgentImportWizard";
export default function AgentManageComp() {
const { t } = useTranslation("common");
const { message } = App.useApp();
- const { user } = useAuthorizationContext();
+ useAuthorizationContext();
// Get state from store
const isCreatingMode = useAgentConfigStore((state) => state.isCreatingMode);
@@ -32,51 +34,27 @@ export default function AgentManageComp() {
const [importWizardData, setImportWizardData] =
useState(null);
- // Shared agent list via React Query
- const { agents: agentList, isLoading: loading, refetch } = useAgentList(user?.tenantId ?? null);
+ // Always resolve tenant from auth on the agent dev page (matches published_list; avoids stale/wrong tenant_id query params)
+ const { agents: agentList, isLoading: loading, refetch } = useAgentList("");
// Handle import agent for space view - open wizard instead of direct import
- const handleImportAgent = () => {
- const fileInput = document.createElement("input");
- fileInput.type = "file";
- fileInput.accept = ".json";
- fileInput.onchange = async (event) => {
- const file = (event.target as HTMLInputElement).files?.[0];
- if (!file) return;
-
- if (!file.name.endsWith(".json")) {
- message.error(t("businessLogic.config.error.invalidFileType"));
- return;
- }
-
- try {
- // Read and parse file
- const fileContent = await file.text();
- let agentData: ImportAgentData;
-
- try {
- agentData = JSON.parse(fileContent);
- } catch (parseError) {
- message.error(t("businessLogic.config.error.invalidFileType"));
- return;
- }
-
- // Validate structure
- if (!agentData.agent_id || !agentData.agent_info) {
- message.error(t("businessLogic.config.error.invalidFileType"));
- return;
- }
-
- // Open wizard with parsed data
- setImportWizardData(agentData);
- setImportWizardVisible(true);
- } catch (error) {
+ const handleImportAgent = async () => {
+ const file = await selectFile(".json");
+ if (!file) return;
+
+ const agentData = await parseAgentImportFile(file, {
+ onParseError: (msgKey) => message.error(t(msgKey)),
+ onValidationError: (msgKey) => message.error(t(msgKey)),
+ onGenericError: (error) => {
log.error("Failed to read import file:", error);
message.error(t("businessLogic.config.error.agentImportFailed"));
- }
- };
+ },
+ });
- fileInput.click();
+ if (!agentData) return;
+
+ setImportWizardData(agentData);
+ setImportWizardVisible(true);
};
return (
@@ -160,7 +138,7 @@ export default function AgentManageComp() {
void handleImportAgent()}
>
void;
+ isShowVersionManagePanel?: boolean;
+ onCloseVersionManagePanel?: () => void;
+}
+
+export default function AgentSelectorHeader({
+ onOpenVersionManage,
+ isShowVersionManagePanel = false,
+ onCloseVersionManagePanel,
+}: AgentSelectorHeaderProps) {
+ const { t } = useTranslation("common");
+ const { message } = App.useApp();
+ const queryClient = useQueryClient();
+ const checkUnsavedChanges = useSaveGuard();
+ const confirm = useConfirmModal();
+ const { token } = theme?.useToken?.() || {};
+ const { user } = useAuthorizationContext();
+
+ // Fetch agent list internally
+ const { agents } = useAgentList(user?.tenantId ?? null);
+
+ // Store state
+ const currentAgentId = useAgentConfigStore((state) => state.currentAgentId);
+ const setCurrentAgent = useAgentConfigStore((state) => state.setCurrentAgent);
+ const isCreatingMode = useAgentConfigStore((state) => state.isCreatingMode);
+ const enterCreateMode = useAgentConfigStore((state) => state.enterCreateMode);
+ const reset = useAgentConfigStore((state) => state.reset);
+ const hasUnsavedChanges = useAgentConfigStore((state) => state.hasUnsavedChanges);
+
+ const { agentInfo } = useAgentInfo(currentAgentId);
+ const { agentVersionList, total } = useAgentVersionList(currentAgentId);
+ const { agentVersionDetail } = useAgentVersionDetail(currentAgentId, agentInfo?.current_version_no);
+
+ // Call relationship modal state
+ const [callRelationshipModalVisible, setCallRelationshipModalVisible] = useState(false);
+ const [selectedAgentForRelationship, setSelectedAgentForRelationship] = useState(null);
+
+ // A2A settings modal state
+ const [showA2ASettings, setShowA2ASettings] = useState(false);
+ const [selectedAgentForA2A, setSelectedAgentForA2A] = useState(null);
+
+ // Dropdown open state
+ const [dropdownOpen, setDropdownOpen] = useState(false);
+
+ // Mutations
+ const updateAgentMutation = useMutation({
+ mutationFn: (payload: any) => updateAgentInfo(payload),
+ });
+
+ const deleteAgentMutation = useMutation({
+ mutationFn: (agentId: number) => deleteAgent(agentId),
+ });
+
+ // Fetch A2A Server Settings when modal opens
+ const { data: a2aSettingsData, isLoading: isLoadingA2ASettings } = useQuery({
+ queryKey: ["a2aServerSettings", selectedAgentForA2A?.id],
+ queryFn: () => a2aClientService.getServerSettings(Number(selectedAgentForA2A!.id)),
+ enabled: showA2ASettings && !!selectedAgentForA2A,
+ });
+
+ // Construct a2aAgentCard from supported_interfaces
+ const constructedA2AAgentCard = (() => {
+ const data = a2aSettingsData?.data;
+ if (!data?.supported_interfaces) return undefined;
+
+ const interfaces = data.supported_interfaces;
+ const endpointId = data.endpoint_id;
+ const restEndpoints = interfaces.filter(
+ (iface: any) => iface.protocolBinding.toLowerCase() === "http+json" || iface.protocolBinding.toLowerCase() === "httprest"
+ );
+ const jsonrpcEndpoints = interfaces.filter(
+ (iface: any) =>
+ iface.protocolBinding.toLowerCase() === "http-json-rpc" ||
+ iface.protocolBinding.toLowerCase() === "jsonrpc" ||
+ iface.protocolBinding.toLowerCase() === "httpjsonrpc"
+ );
+
+ return {
+ endpoint_id: endpointId,
+ name: data.name || "",
+ description: data.description,
+ version: data.version,
+ streaming: data.streaming,
+ agent_card_url: `/nb/a2a/${endpointId}/.well-known/agent-card.json`,
+ rest_endpoints: {
+ message_send: `${restEndpoints[0]?.url}/message:send`,
+ message_stream: `${restEndpoints[0]?.url}/message:stream`,
+ tasks_get: `${restEndpoints[0]?.url}/tasks/{task_id}`,
+ },
+ jsonrpc_url: jsonrpcEndpoints[0]?.url || "",
+ jsonrpc_methods: ["SendMessage", "SendStreamingMessage", "GetTask"],
+ };
+ })();
+
+ // Import wizard state
+ const [importWizardVisible, setImportWizardVisible] = useState(false);
+ const [importWizardData, setImportWizardData] = useState(null);
+
+ // Get current selected agent
+ const currentAgent = agents.find(
+ (agent: Agent) => currentAgentId !== null && String(agent.id) === String(currentAgentId)
+ );
+
+ // Handle import agent
+ const handleImportAgent = () => {
+ const fileInput = document.createElement("input");
+ fileInput.type = "file";
+ fileInput.accept = ".json";
+ fileInput.onchange = async (event) => {
+ const file = (event.target as HTMLInputElement).files?.[0];
+ if (!file) return;
+
+ if (!file.name.endsWith(".json")) {
+ message.error(t("businessLogic.config.error.invalidFileType"));
+ return;
+ }
+
+ try {
+ const fileContent = await file.text();
+ let agentData: ImportAgentData;
+
+ try {
+ agentData = JSON.parse(fileContent);
+ } catch (parseError) {
+ message.error(t("businessLogic.config.error.invalidFileType"));
+ return;
+ }
+
+ if (!agentData.agent_id || !agentData.agent_info) {
+ message.error(t("businessLogic.config.error.invalidFileType"));
+ return;
+ }
+
+ setImportWizardData(agentData);
+ setImportWizardVisible(true);
+ } catch (error) {
+ log.error("Failed to read import file:", error);
+ message.error(t("businessLogic.config.error.agentImportFailed"));
+ }
+ };
+
+ fileInput.click();
+ };
+
+ // Handle view call relationship
+ const handleViewCallRelationship = (agent: Agent) => {
+ setSelectedAgentForRelationship(agent);
+ setCallRelationshipModalVisible(true);
+ setDropdownOpen(false);
+ };
+
+ const handleCloseCallRelationshipModal = () => {
+ setCallRelationshipModalVisible(false);
+ setSelectedAgentForRelationship(null);
+ };
+
+ // Handle view A2A agent settings
+ const handleViewA2AAgentSettings = (agent: Agent) => {
+ setSelectedAgentForA2A(agent);
+ setShowA2ASettings(true);
+ setDropdownOpen(false);
+ };
+
+ // Handle export agent
+ const handleExportAgent = async (agent: Agent) => {
+ try {
+ const result = await exportAgent(Number(agent.id));
+ if (result.success && result.data) {
+ const blob = new Blob([JSON.stringify(result.data, null, 2)], {
+ type: "application/json",
+ });
+ const url = URL.createObjectURL(blob);
+ const link = document.createElement("a");
+ link.href = url;
+ link.download = `${agent.name || "agent"}.json`;
+ document.body.appendChild(link);
+ link.click();
+ document.body.removeChild(link);
+ URL.revokeObjectURL(url);
+ message.success(t("businessLogic.config.message.agentExportSuccess"));
+ } else {
+ message.error(
+ result.message || t("businessLogic.config.error.agentImportFailed")
+ );
+ }
+ } catch (error) {
+ message.error(t("businessLogic.config.error.agentExportFailed"));
+ }
+ };
+
+ // Handle copy agent
+ const handleCopyAgent = async (agent: Agent) => {
+ try {
+ const detailResult = await searchAgentInfo(Number(agent.id));
+ if (!detailResult.success || !detailResult.data) {
+ message.error(detailResult.message);
+ return;
+ }
+ const detail = detailResult.data;
+
+ const copyName = `${detail.name || "agent"}_copy`;
+ const copyDisplayName = `${
+ detail.display_name || t("agentConfig.agents.defaultDisplayName")
+ }${t("agent.copySuffix")}`;
+
+ const tools = Array.isArray(detail.tools) ? detail.tools : [];
+ const unavailableTools = tools.filter(
+ (tool: any) => tool && tool.is_available === false
+ );
+ const unavailableToolNames = unavailableTools
+ .map(
+ (tool: any) =>
+ tool?.display_name || tool?.name || tool?.tool_name || ""
+ )
+ .filter((name: string) => Boolean(name));
+
+ const enabledToolIds = tools
+ .filter((tool: any) => tool && tool.is_available !== false)
+ .map((tool: any) => Number(tool.id))
+ .filter((id: number) => Number.isFinite(id));
+
+ const subAgentIds = (
+ Array.isArray(detail.sub_agent_id_list) ? detail.sub_agent_id_list : []
+ )
+ .map((id: any) => Number(id))
+ .filter((id: number) => Number.isFinite(id));
+
+ const createResult = await updateAgentMutation.mutateAsync({
+ agent_id: undefined, // create
+ name: copyName,
+ display_name: copyDisplayName,
+ description: detail.description,
+ author: detail.author,
+ model_name: detail.model,
+ model_id: detail.model_id ?? undefined,
+ max_steps: detail.max_step,
+ provide_run_summary: detail.provide_run_summary,
+ enabled: detail.enabled,
+ business_description: detail.business_description,
+ duty_prompt: detail.duty_prompt,
+ constraint_prompt: detail.constraint_prompt,
+ few_shots_prompt: detail.few_shots_prompt,
+ business_logic_model_name: detail.business_logic_model_name ?? undefined,
+ business_logic_model_id: detail.business_logic_model_id ?? undefined,
+ enabled_tool_ids: enabledToolIds,
+ related_agent_ids: subAgentIds,
+ });
+
+ if (!createResult.success || !createResult.data?.agent_id) {
+ message.error(
+ createResult.message || t("agentConfig.agents.copyFailed")
+ );
+ return;
+ }
+ const newAgentId = Number(createResult.data.agent_id);
+
+ // Copy tool configuration
+ for (const tool of tools) {
+ if (!tool || tool.is_available === false) continue;
+ const params =
+ tool.initParams?.reduce((acc: Record, param: any) => {
+ acc[param.name] = param.value;
+ return acc;
+ }, {}) || {};
+ try {
+ await updateToolConfig(Number(tool.id), newAgentId, params, true);
+ } catch (error) {
+ log.error("Failed to copy tool configuration:", error);
+ message.error(t("agentConfig.agents.copyFailed"));
+ return;
+ }
+ }
+
+ // Refresh agent list
+ queryClient.invalidateQueries({ queryKey: ["agents"] });
+ message.success(t("agentConfig.agents.copySuccess"));
+
+ if (unavailableTools.length > 0) {
+ const names =
+ unavailableToolNames.join(", ") ||
+ unavailableTools
+ .map((tool: any) => Number(tool?.id))
+ .filter((id: number) => !Number.isNaN(id))
+ .join(", ");
+ message.warning(
+ t("agentConfig.agents.copyUnavailableTools", {
+ count: unavailableTools.length,
+ names,
+ })
+ );
+ }
+ } catch (error) {
+ log.error("Failed to copy agent:", error);
+ message.error(t("agentConfig.agents.copyFailed"));
+ }
+ };
+
+ // Handle copy with confirmation
+ const handleCopyAgentWithConfirm = (agent: Agent) => {
+ confirm.confirm({
+ title: t("agentConfig.agents.copyConfirmTitle"),
+ content: t("agentConfig.agents.copyConfirmContent", {
+ name: agent?.display_name || agent?.name || "",
+ }),
+ onOk: () => handleCopyAgent(agent),
+ });
+ };
+
+ // Handle delete agent
+ const handleDeleteAgent = async (agent: Agent) => {
+ deleteAgentMutation.mutate(Number(agent.id), {
+ onSuccess: () => {
+ message.success(
+ t("businessLogic.config.error.agentDeleteSuccess", {
+ name: agent.display_name || agent.name || "",
+ })
+ );
+
+ // Clear current agent if this was the selected agent
+ if (
+ currentAgentId !== null &&
+ String(currentAgentId) === String(agent.id)
+ ) {
+ setCurrentAgent(null);
+ }
+
+ // Refresh agent list
+ queryClient.invalidateQueries({ queryKey: ["agents"] });
+ },
+ onError: () => {
+ message.error(t("businessLogic.config.error.agentDeleteFailed"));
+ },
+ });
+ };
+
+ // Handle delete with confirmation
+ const handleDeleteAgentWithConfirm = (agent: Agent) => {
+ confirm.confirm({
+ title: t("businessLogic.config.modal.deleteTitle"),
+ content: t("businessLogic.config.modal.deleteContent", {
+ name: agent.display_name || agent.name || "",
+ }),
+ onOk: () => handleDeleteAgent(agent),
+ });
+ };
+
+ // Handle select agent from dropdown
+ const handleSelectAgent = async (agentId: number | null) => {
+ if (agentId === null) return;
+
+ const agent = agents.find((a: Agent) => String(a.id) === String(agentId));
+ if (!agent) return;
+
+ // Clear NEW mark when agent is selected for editing
+ if (agent.is_new === true) {
+ try {
+ const res = await clearAgentNewMark(agent.id);
+ if (!res?.success) {
+ log.warn("Failed to clear NEW mark on select:", res);
+ queryClient.invalidateQueries({ queryKey: ["agents"] });
+ }
+ } catch (err) {
+ log.error("Failed to clear NEW mark on select:", err);
+ }
+ }
+
+ // Guard unsaved changes
+ if (currentAgentId !== null || isCreatingMode) {
+ const canSwitch = await checkUnsavedChanges.saveWithModal();
+ if (!canSwitch) return;
+ }
+
+ // Load and set agent
+ try {
+ const result = await searchAgentInfo(Number(agent.id));
+ if (result.success && result.data) {
+ setCurrentAgent(result.data);
+ } else {
+ message.error(result.message || t("agentConfig.agents.detailsLoadFailed"));
+ }
+ } catch (error) {
+ log.error("Failed to load agent detail:", error);
+ message.error(t("agentConfig.agents.detailsLoadFailed"));
+ }
+ };
+
+ // Dropdown menu items (only agents)
+ const agentMenuItems = agents.flatMap((agent: Agent, index: number) => {
+ const isAvailable = agent.is_available !== false;
+ const displayName = agent.display_name || "";
+ const name = agent.name || "";
+
+ const agentItem = {
+ key: `agent-${agent.id}`,
+ label: (
+
+
+ {/* Row 1: Name + Status */}
+
+
+
+ {!isAvailable && (
+ {
+ const reasons = agent.unavailable_reasons || [];
+ if (reasons.includes('agent_not_found')) {
+ return t('subAgentPool.tooltip.unavailableAgent');
+ } else if (reasons.includes('tool_unavailable')) {
+ return t('toolPool.tooltip.unavailableTool');
+ } else if (reasons.includes('duplicate_name')) {
+ return t('agent.error.nameExists', { name });
+ } else if (reasons.includes('duplicate_display_name')) {
+ return t('agent.error.displayNameExists', { displayName });
+ } else if (reasons.includes('model_unavailable')) {
+ return t('agent.error.modelUnavailable');
+ }
+ return t('subAgentPool.tooltip.unavailableAgent');
+ })()}
+ >
+
+ )}
+ {agent.is_new && (
+
+
+ {t("space.new", "NEW")}
+
+
+ )}
+ {displayName && (
+ {displayName}
+ )}
+
+
+ {agent.is_a2a_server && (
+
+
+ }
+ onClick={(e) => {
+ e.preventDefault();
+ e.stopPropagation();
+ handleViewA2AAgentSettings(agent);
+ }}
+ className="agent-action-button agent-action-button-blue"
+ />
+
+
+ )}
+
+ }
+ disabled={!isAvailable}
+ className="agent-action-button agent-action-button-blue"
+ onClick={(e) => {
+ e.stopPropagation();
+ handleCopyAgentWithConfirm(agent);
+ }}
+ />
+
+
+ }
+ disabled={!isAvailable}
+ className="agent-action-button agent-action-button-blue"
+ onClick={(e) => {
+ e.stopPropagation();
+ handleViewCallRelationship(agent);
+ }}
+ />
+
+
+ }
+ disabled={!isAvailable}
+ className="agent-action-button agent-action-button-green"
+ onClick={(e) => {
+ e.stopPropagation();
+ handleExportAgent(agent);
+ }}
+ />
+
+
+ }
+ disabled={agent.permission === "READ_ONLY"}
+ className="agent-action-button agent-action-button-red"
+ onClick={(e) => {
+ e.stopPropagation();
+ handleDeleteAgentWithConfirm(agent);
+ }}
+ />
+
+
+
+
+ {/* Row 2: Description */}
+
+ {agent.description}
+
+
+
+ ),
+ onClick: () => handleSelectAgent(Number(agent.id)),
+ };
+
+ // Add divider after each item except the last one
+ const divider = index < agents.length - 1
+ ? { key: `divider-${agent.id}`, type: 'divider' as const }
+ : null;
+
+ return divider ? [agentItem, divider] : [agentItem];
+ });
+
+ return (
+ <>
+
+
+ {/* Left column: Agent Config */}
+ triggerNode.parentNode as HTMLElement}
+ styles={{
+ root: {
+ width: 'calc(100% - 32px)',
+ }
+ }}
+ >
+
+
+ {hasUnsavedChanges && (
+
+
+ )}
+ {!hasUnsavedChanges &&
+
+
+
+ {/* Right column: Agent Info */}
+
+
+ {agentVersionDetail?.version.version_name}
+
+
+ / {t("agent.version.totalVersions", { count: total ?? 0 })}
+
+
+ )}
+ {/* Right side: Agent count + Version management button */}
+
+ {/* Create and Import buttons outside dropdown */}
+
+
+
+
+
+ }
+ onClick={isShowVersionManagePanel ? onCloseVersionManagePanel : onOpenVersionManage}
+ type={isShowVersionManagePanel ? "primary" : "default"}
+ >
+ {t("agent.version.manage")}
+
+
+
+
+
+
+
+ {/* Import Wizard Modal */}
+ {
+ setImportWizardVisible(false);
+ setImportWizardData(null);
+ }}
+ initialData={importWizardData}
+ onImportComplete={() => {
+ setImportWizardVisible(false);
+ setImportWizardData(null);
+ queryClient.invalidateQueries({ queryKey: ["agents"] });
+ }}
+ />
+
+ {/* Call Relationship Modal */}
+ {selectedAgentForRelationship && (
+ {
+ setShowA2ASettings(false);
+ setSelectedAgentForA2A(null);
+ }}
+ loading={isLoadingA2ASettings}
+ footer={null}
+ zIndex={1050}
+ >
+ {selectedAgentForA2A && constructedA2AAgentCard ? (
+
+
+ );
+}
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/CollaborativeAgent.tsx b/frontend/app/[locale]/agents/components/agentConfig/CollaborativeAgent.tsx
index 9c664e8c3..d3090b369 100644
--- a/frontend/app/[locale]/agents/components/agentConfig/CollaborativeAgent.tsx
+++ b/frontend/app/[locale]/agents/components/agentConfig/CollaborativeAgent.tsx
@@ -16,7 +16,6 @@ export default function CollaborativeAgent() {
const currentAgentId = useAgentConfigStore((state) => state.currentAgentId);
const isCreatingMode = useAgentConfigStore((state) => state.isCreatingMode);
- const currentAgentPermission = useAgentConfigStore((state) => state.currentAgentPermission);
const editedAgent = useAgentConfigStore((state) => state.editedAgent);
const updateSubAgentIds = useAgentConfigStore((state) => state.updateSubAgentIds);
const updateExternalSubAgentIds = useAgentConfigStore((state) => state.updateExternalSubAgentIds);
@@ -35,7 +34,8 @@ export default function CollaborativeAgent() {
(agent: A2AExternalAgent) => externalSubAgentIdList.includes(agent.id)
);
- const editable = !!isCreatingMode || (currentAgentId != null && currentAgentPermission !== "READ_ONLY");
+ // isReadOnly from store: isCreatingMode → false, READ_ONLY permission → true
+ const isReadOnly = useAgentConfigStore((state) => state.isReadOnly());
// Related internal agent IDs
const relatedAgentIds = Array.isArray(editedAgent?.sub_agent_id_list) ? editedAgent.sub_agent_id_list : [];
@@ -93,6 +93,8 @@ export default function CollaborativeAgent() {
const result = await a2aClientService.addRelation(Number(currentAgentId), externalAgentId);
if (result.success) {
messageApi.success(t("a2a.service.addRelationSuccess"));
+ // Sync the store so save() sends the updated external_sub_agent_id_list
+ updateExternalSubAgentIds([...externalSubAgentIdList, externalAgentId]);
loadExternalRelatedAgents();
} else {
messageApi.error(result.message || t("a2a.service.addRelationFailed"));
@@ -117,6 +119,8 @@ export default function CollaborativeAgent() {
const result = await a2aClientService.removeRelation(Number(currentAgentId), agentId);
if (result.success) {
messageApi.success(t("a2a.service.removeRelationSuccess"));
+ // Sync the store so save() sends the updated external_sub_agent_id_list
+ updateExternalSubAgentIds(externalSubAgentIdList.filter((id) => id !== agentId));
loadExternalRelatedAgents();
} else {
messageApi.error(result.message || t("a2a.service.removeRelationFailed"));
@@ -163,14 +167,14 @@ export default function CollaborativeAgent() {
}
- disabled={!editable}
- className={`${editable ? "hover:!border-2 hover:!border-dashed hover:!border-blue-500 hover:!text-blue-500 hover:!bg-blue-50 transition-colors" : "!bg-gray-50"}`}
+ disabled={isReadOnly}
+ className={`${isReadOnly ? "!bg-gray-50" : "hover:!border-2 hover:!border-dashed hover:!border-blue-500 hover:!text-blue-500 hover:!bg-blue-50 transition-colors"}`}
style={{ border: '2px dashed #9ca3af' }}
>
@@ -183,8 +187,8 @@ export default function CollaborativeAgent() {
{relatedInternalAgents.map((agent: Agent) => (
handleRemoveInternalAgent(Number(agent.id)) : undefined}
+ closable={!isReadOnly}
+ onClose={!isReadOnly ? () => handleRemoveInternalAgent(Number(agent.id)) : undefined}
className="bg-blue-50 text-blue-700 border-blue-200"
>
{agent.display_name || agent.name}
@@ -199,8 +203,8 @@ export default function CollaborativeAgent() {
{displayExternalAgents.map((agent) => (
handleRemoveExternalAgent(agent.id) : undefined}
+ closable={!isReadOnly}
+ onClose={!isReadOnly ? () => handleRemoveExternalAgent(agent.id) : undefined}
className="bg-green-50 text-green-700 border-green-200"
>
diff --git a/frontend/app/[locale]/agents/components/agentConfig/McpConfigModal.tsx b/frontend/app/[locale]/agents/components/agentConfig/McpConfigModal.tsx
index fc14a89af..41c8baa45 100644
--- a/frontend/app/[locale]/agents/components/agentConfig/McpConfigModal.tsx
+++ b/frontend/app/[locale]/agents/components/agentConfig/McpConfigModal.tsx
@@ -16,6 +16,7 @@ import {
App,
Upload,
Tabs,
+ Tag,
} from "antd";
import {
Trash,
@@ -79,6 +80,7 @@ export default function McpConfigModal({
const [openApiJson, setOpenApiJson] = useState("");
const [openApiServiceName, setOpenApiServiceName] = useState("");
const [openApiServerUrl, setOpenApiServerUrl] = useState("");
+ const [openApiHeadersTemplate, setOpenApiHeadersTemplate] = useState("");
const [importingOpenApi, setImportingOpenApi] = useState(false);
const [openapiServices, setOpenapiServices] = useState([]);
const [loadingOpenapiServices, setLoadingOpenapiServices] = useState(false);
@@ -88,6 +90,7 @@ export default function McpConfigModal({
const [newServerName, setNewServerName] = useState("");
const [newServerUrl, setNewServerUrl] = useState("");
const [newServerAuthorizationToken, setNewServerAuthorizationToken] = useState("");
+ const [newServerCustomHeaders, setNewServerCustomHeaders] = useState("");
const [toolsModalVisible, setToolsModalVisible] = useState(false);
const [currentServerTools, setCurrentServerTools] = useState([]);
@@ -104,6 +107,7 @@ export default function McpConfigModal({
const [containerPort, setContainerPort] = useState(
undefined
);
+ const [containerServiceName, setContainerServiceName] = useState("");
const [logsModalVisible, setLogsModalVisible] = useState(false);
const [currentContainerId, setCurrentContainerId] = useState("");
@@ -172,16 +176,33 @@ export default function McpConfigModal({
return;
}
+ // Parse custom headers
+ let parsedCustomHeaders: Record | null = null;
+ if (newServerCustomHeaders.trim()) {
+ try {
+ parsedCustomHeaders = JSON.parse(newServerCustomHeaders.trim());
+ if (typeof parsedCustomHeaders !== 'object' || parsedCustomHeaders === null || Array.isArray(parsedCustomHeaders)) {
+ message.error(t("mcpConfig.message.invalidCustomHeaders"));
+ return;
+ }
+ } catch {
+ message.error(t("mcpConfig.message.invalidCustomHeadersJson"));
+ return;
+ }
+ }
+
setAddingServer(true);
const result = await handleAddServer(
newServerUrl.trim(),
serverName,
- newServerAuthorizationToken.trim() || null
+ newServerAuthorizationToken.trim() || null,
+ parsedCustomHeaders
);
if (result.success) {
setNewServerName("");
setNewServerUrl("");
setNewServerAuthorizationToken("");
+ setNewServerCustomHeaders("");
message.success(result.messageKey ? t(result.messageKey) : t("mcpService.message.addServerSuccess"));
} else {
message.error(result.messageKey ? t(result.messageKey) : (result.message || t("mcpConfig.message.addServerFailed")));
@@ -278,6 +299,7 @@ export default function McpConfigModal({
service_name: result.data.mcp_name,
mcp_url: result.data.mcp_server,
authorization_token: result.data.authorization_token,
+ custom_headers: result.data.custom_headers,
});
} else {
message.error(result.messageKey ? t(result.messageKey) : (result.message || t("mcpConfig.message.getMcpRecordFailed")));
@@ -286,7 +308,7 @@ export default function McpConfigModal({
setLoadingMcpRecord(false);
};
- const onSaveEditedServer = async (name: string, url: string, authorizationToken?: string | null) => {
+ const onSaveEditedServer = async (name: string, url: string, authorizationToken?: string | null, customHeaders?: Record | null) => {
if (!editingServer) return;
if (!name.trim() || !url.trim()) {
message.error(t("mcpConfig.message.nameAndUrlRequired"));
@@ -306,11 +328,11 @@ export default function McpConfigModal({
setUpdatingServer(true);
const result = await handleUpdateServer(
- editingServer.service_name,
- editingServer.mcp_url,
+ editingServer.mcp_id,
name.trim(),
url.trim(),
- authorizationToken
+ authorizationToken,
+ customHeaders
);
if (result.success) {
setEditServerModalVisible(false);
@@ -347,12 +369,13 @@ export default function McpConfigModal({
}
setAddingContainer(true);
- const result = await handleAddContainer(config, containerPort);
+ const result = await handleAddContainer(config, containerPort, containerServiceName.trim() || undefined);
if (!result.success) {
message.error(result.messageKey ? t(result.messageKey) : (result.message || t("mcpConfig.message.addContainerFailed")));
} else {
setContainerConfigJson("");
setContainerPort(undefined);
+ setContainerServiceName("");
message.success(result.messageKey ? t(result.messageKey) : t("mcpService.message.addContainerSuccess"));
}
setAddingContainer(false);
@@ -484,6 +507,7 @@ export default function McpConfigModal({
service_name: openApiServiceName.trim(),
server_url: openApiServerUrl.trim(),
openapi_json: parsedJson,
+ headers_template: openApiHeadersTemplate.trim() ? JSON.parse(openApiHeadersTemplate.trim()) : null,
}),
});
@@ -492,6 +516,7 @@ export default function McpConfigModal({
setOpenApiJson("");
setOpenApiServiceName("");
setOpenApiServerUrl("");
+ setOpenApiHeadersTemplate("");
await loadOpenapiServices();
await refreshToolsAndAgents();
} else {
@@ -561,9 +586,28 @@ export default function McpConfigModal({
title: t("mcpConfig.serverList.column.url"),
dataIndex: "mcp_url",
key: "mcp_url",
- width: "40%",
+ width: "30%",
ellipsis: true,
},
+ {
+ title: t("mcpConfig.serverList.column.enabled"),
+ key: "enabled",
+ width: "10%",
+ render: (_: any, record: any) => {
+ const isEnabled = record.enabled;
+ return isEnabled ? (
+
+ {t("mcpConfig.serverList.enabled.yes")}
+
+ ) : (
+
+
+ {t("mcpConfig.serverList.enabled.no")}
+
+
+ );
+ },
+ },
{
title: t("mcpConfig.serverList.column.action"),
key: "action",
@@ -831,7 +875,7 @@ export default function McpConfigModal({
children: (
-
+
+ setNewServerCustomHeaders(e.target.value)}
+ rows={2}
+ disabled={actionsLocked || addingServer}
+ style={{ fontSize: 14 }}
+ />
+ {t("mcpConfig.addContainer.serviceName")}:
+
+ setContainerServiceName(e.target.value)}
+ style={{ width: 150 }}
+ maxLength={20}
+ disabled={actionsLocked}
+ />
+
{t("mcpConfig.addContainer.port")}:
setOpenApiJson(e.target.value)}
- rows={6}
- disabled={actionsLocked || importingOpenApi}
- />
-
+ setOpenApiHeadersTemplate(e.target.value)}
+ rows={2}
+ disabled={actionsLocked || importingOpenApi}
+ />
+ setOpenApiJson(e.target.value)}
+ rows={6}
+ disabled={actionsLocked || importingOpenApi}
+ />
@@ -1253,7 +1322,6 @@ export default function McpConfigModal({
size="small"
pagination={false}
locale={{ emptyText: t("mcpConfig.containerList.empty") }}
- scroll={{ y: 300 }}
style={{ width: "100%" }}
/>
@@ -1277,7 +1345,6 @@ export default function McpConfigModal({
size="small"
pagination={false}
locale={{ emptyText: t("mcpConfig.openapiService.list.empty") }}
- scroll={{ y: 300 }}
style={{ width: "100%" }}
/>
@@ -1304,6 +1371,7 @@ export default function McpConfigModal({
initialName={editingServer?.service_name || ""}
initialUrl={editingServer?.mcp_url || ""}
initialAuthorizationToken={editingServer?.authorization_token || null}
+ initialCustomHeaders={editingServer?.custom_headers || null}
loading={updatingServer || loadingMcpRecord}
/>
diff --git a/frontend/app/[locale]/agents/components/agentConfig/SkillBuildModal.tsx b/frontend/app/[locale]/agents/components/agentConfig/SkillBuildModal.tsx
index eff41b6d9..8f040d4b3 100644
--- a/frontend/app/[locale]/agents/components/agentConfig/SkillBuildModal.tsx
+++ b/frontend/app/[locale]/agents/components/agentConfig/SkillBuildModal.tsx
@@ -15,6 +15,7 @@ import {
Row,
Col,
Spin,
+ Tooltip,
} from "antd";
import {
Upload as UploadIcon,
@@ -23,13 +24,19 @@ import {
MessagesSquare,
HardDriveUpload,
Loader2,
+ Plus,
+ X,
+ Pencil,
+ Square,
} from "lucide-react";
import { extractSkillInfo, extractSkillInfoFromContent } from "@/lib/skillFileUtils";
+import yaml from "js-yaml";
import {
MAX_RECENT_SKILLS,
THINKING_STEPS_ZH,
type SkillFormData,
type ChatMessage,
+ type SkillFileContent,
} from "@/types/skill";
import {
fetchSkillsList,
@@ -37,11 +44,19 @@ import {
submitSkillFromFile,
findSkillByName,
searchSkillsByName as searchSkillsByNameUtil,
- createSimpleSkillStream,
+ createSkillStream,
clearChatAndTempFile,
+ stopSkillCreation,
type SkillListItem,
+ type SkillData,
} from "@/services/skillService";
-import { MarkdownRenderer } from "@/components/ui/markdownRenderer";
+import {
+ fetchSkillFiles,
+ fetchSkillFileContent,
+ SkillFilesAccessDeniedError,
+ type SkillFileNode,
+} from "@/services/agentConfigService";
+import { MarkdownRenderer } from "@/components/common/markdownRenderer";
import log from "@/lib/logger";
const { TextArea } = Input;
@@ -72,19 +87,59 @@ export default function SkillBuildModal({
const [chatMessages, setChatMessages] = useState([]);
const [chatInput, setChatInput] = useState("");
const [isChatLoading, setIsChatLoading] = useState(false);
- const [thinkingStep, setThinkingStep] = useState(0);
const [thinkingDescription, setThinkingDescription] = useState("");
const [isThinkingVisible, setIsThinkingVisible] = useState(false);
const [interactiveSkillName, setInteractiveSkillName] = useState("");
const chatContainerRef = useRef(null);
- const contentTextAreaId = useRef("skill-content-textarea-" + Date.now());
- // Content input streaming state
- const [formStreamingContent, setFormStreamingContent] = useState("");
- const [isContentStreaming, setIsContentStreaming] = useState(false);
- const [thinkingStreamingContent, setThinkingStreamingContent] = useState("");
- const [summaryStreamingContent, setSummaryStreamingContent] = useState("");
- const [isSummaryVisible, setIsSummaryVisible] = useState(false);
+ // Content input streaming state - multi-file tabs
+ const [skillTabs, setSkillTabs] = useState([
+ { path: "SKILL.md", content: "" },
+ ]);
+ const [activeSkillTab, setActiveSkillTab] = useState("SKILL.md");
+ const [isStreaming, setIsStreaming] = useState(false);
+
+ // Tab management state
+ const [editingTabKey, setEditingTabKey] = useState(null);
+ const [editingTabName, setEditingTabName] = useState("");
+
+ // Summary content for chat bubble
+ const [summaryContent, setSummaryContent] = useState("");
+
+ // Frontmatter buffer for streaming - accumulate and parse at completion
+ const frontmatterBufferRef = useRef("");
+
+ // Refs for per-tab scroll state: tracks whether each textarea should auto-scroll
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ const textareaRefs = useRef>({});
+ const shouldAutoScrollRef = useRef>({});
+
+ // Detect if the textarea is currently near the bottom (within threshold pixels)
+ const isTextareaAtBottom = (tabPath: string): boolean => {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ const ref = textareaRefs.current[tabPath] as any;
+ const textarea = ref?.resizableTextArea?.textArea || ref?.textArea || ref;
+ if (!textarea) return true;
+ return textarea.scrollHeight - textarea.scrollTop - textarea.clientHeight < 20;
+ };
+
+ // Update shouldAutoScrollRef when user scrolls manually
+ const handleTextareaScroll = (tabPath: string) => {
+ shouldAutoScrollRef.current[tabPath] = isTextareaAtBottom(tabPath);
+ };
+
+ // Scroll textarea to bottom, respecting user scroll preference and throttled via RAF
+ const scrollTextareaToBottom = (tabPath: string) => {
+ if (!shouldAutoScrollRef.current[tabPath]) return;
+ requestAnimationFrame(() => {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ const ref = textareaRefs.current[tabPath] as any;
+ const textarea = ref?.resizableTextArea?.textArea || ref?.textArea || ref;
+ if (textarea) {
+ textarea.scrollTop = textarea.scrollHeight;
+ }
+ });
+ };
// Track if component is mounted to prevent state updates after unmount
const isMountedRef = useRef(true);
@@ -92,6 +147,29 @@ export default function SkillBuildModal({
// Track if streaming is complete to prevent late onFormContent callbacks from overwriting cleaned content
const isStreamingCompleteRef = useRef(false);
+ // Track current tabs during streaming to avoid stale closure issues
+ const streamingTabsRef = useRef([{ path: "SKILL.md", content: "" }]);
+
+ // AbortController ref for stopping streaming
+ const abortControllerRef = useRef(null);
+
+ // Task ID ref for backend stop API
+ const taskIdRef = useRef("");
+
+ // Multi-turn conversation state: accumulated skill draft from previous turns.
+ // When the user sends a follow-up message, this draft is passed as existing_skill
+ // so the backend can refine the skill rather than generating from scratch.
+ const [accumulatedDraft, setAccumulatedDraft] = useState<{
+ name: string;
+ description: string;
+ tags: string[];
+ content: string;
+ } | null>(null);
+
+ // Whether the user is in multi-turn refinement mode (has already received a draft).
+ // Used to switch the placeholder from "创建" to "继续修改" and to pass existing_skill.
+ const [isMultiTurn, setIsMultiTurn] = useState(false);
+
// Name input dropdown control
const [isNameDropdownOpen, setIsNameDropdownOpen] = useState(false);
const [isTagsFocused, setIsTagsFocused] = useState(false);
@@ -116,7 +194,9 @@ export default function SkillBuildModal({
let cancelled = false;
fetchSkillsList()
.then((list) => {
- if (!cancelled) setAllSkills(list);
+ if (!cancelled) {
+ setAllSkills(list);
+ }
})
.catch((err) => {
log.error("Failed to load skills for SkillBuildModal", err);
@@ -128,6 +208,13 @@ export default function SkillBuildModal({
useEffect(() => {
if (!isOpen) {
+ // Abort any ongoing streaming request
+ if (abortControllerRef.current) {
+ abortControllerRef.current.abort("Modal closed");
+ abortControllerRef.current = null;
+ }
+ // Reset task ID
+ taskIdRef.current = "";
form.resetFields();
setActiveTab("interactive");
setSelectedSkillName("");
@@ -141,15 +228,19 @@ export default function SkillBuildModal({
setIsCreateMode(true);
setUploadExtractingName(false);
setUploadExtractedSkillName("");
- setThinkingStep(0);
setThinkingDescription("");
setIsThinkingVisible(false);
- setFormStreamingContent("");
- setThinkingStreamingContent("");
- setSummaryStreamingContent("");
- setIsSummaryVisible(false);
- setIsContentStreaming(false);
+ setSkillTabs([{ path: "SKILL.md", content: "" }]);
+ streamingTabsRef.current = [{ path: "SKILL.md", content: "" }];
+ shouldAutoScrollRef.current = {};
+ setActiveSkillTab("SKILL.md");
+ setIsStreaming(false);
+ setSummaryContent("");
currentAssistantIdRef.current = "";
+ setAccumulatedDraft(null);
+ setIsMultiTurn(false);
+ setEditingTabKey(null);
+ setEditingTabName("");
}
}, [isOpen, form]);
@@ -161,26 +252,19 @@ export default function SkillBuildModal({
};
}, []);
- // Sync streaming content to the current assistant chat message for real-time display.
- // Show thinking content while thinking is visible, then switch to summary.
+ // Sync summary content to the current assistant chat message for real-time display.
useEffect(() => {
if (!currentAssistantIdRef.current) return;
- const displayContent = isSummaryVisible ? summaryStreamingContent : thinkingStreamingContent;
- if (!displayContent) return;
- setChatMessages((prev) =>
- prev.map((msg) =>
+ if (!summaryContent) return;
+ setChatMessages((prev) => {
+ if (!prev.some((m) => m.id === currentAssistantIdRef.current)) return prev;
+ return prev.map((msg) =>
msg.id === currentAssistantIdRef.current
- ? { ...msg, content: displayContent }
+ ? { ...msg, content: summaryContent }
: msg
- )
- );
- }, [thinkingStreamingContent, summaryStreamingContent, isSummaryVisible]);
-
- // Sync formStreamingContent to the form content field for real-time display
- useEffect(() => {
- if (!formStreamingContent) return;
- form.setFieldValue("content", formStreamingContent);
- }, [formStreamingContent, form]);
+ );
+ });
+ }, [summaryContent]);
// Detect create/update mode when skill name changes
useEffect(() => {
@@ -190,11 +274,8 @@ export default function SkillBuildModal({
setIsCreateMode(!matchedSkill);
if (matchedSkill) {
setSelectedSkillName(matchedSkill.name);
- form.setFieldsValue({
- description: matchedSkill.description || "",
- source: matchedSkill.source || "自定义",
- content: matchedSkill.content || "",
- });
+ // Load all skill data including files
+ loadSkillData(nameValue);
}
} else {
setIsCreateMode(true);
@@ -255,21 +336,32 @@ export default function SkillBuildModal({
setSelectedSkillName(value);
setInteractiveSkillName(value);
setIsNameDropdownOpen(false);
- const skill = allSkills.find((s) => s.name === value);
- if (skill) {
- form.setFieldsValue({
- name: skill.name,
- description: skill.description || "",
- source: skill.source || "自定义",
- content: skill.content || "",
- });
- }
+ };
+
+ // Load skill data when name is selected or typed
+ const loadSkillData = async (skillName: string) => {
+ const skill = allSkills.find((s) => s.name === skillName);
+ if (!skill) return;
+
+ const fieldsToSet = {
+ name: skill.name,
+ description: skill.description || "",
+ source: skill.source || "自定义",
+ tags: skill.tags || [],
+ content: skill.content || "",
+ };
+ form.setFieldsValue(fieldsToSet);
+
+ await loadSkillFiles(skillName);
};
const handleNameChange = (value: string) => {
setInteractiveSkillName(value);
if (!value || value.trim() === "") {
setSelectedSkillName("");
+ // Reset skillTabs when input is cleared
+ setSkillTabs([{ path: "SKILL.md", content: "" }]);
+ setActiveSkillTab("SKILL.md");
}
};
@@ -292,8 +384,19 @@ export default function SkillBuildModal({
try {
const values = await form.validateFields();
setIsSubmitting(true);
+
+ const skillTab = skillTabs.find(t => t.path === "SKILL.md");
+ const content = skillTab?.content || "";
+
+ const extraFiles = skillTabs
+ .filter(t => t.path !== "SKILL.md")
+ .map(t => ({
+ path: t.path,
+ content: t.content || "",
+ }));
+
await submitSkillForm(
- values,
+ { ...values, content, files: extraFiles.length > 0 ? extraFiles : undefined } as SkillData,
allSkills,
onSuccess,
onCancel,
@@ -332,6 +435,135 @@ export default function SkillBuildModal({
}
};
+ // Helper function to update tab content
+ const updateTabContent = (tabPath: string, content: string) => {
+ setSkillTabs((prev) => {
+ const newTabs = prev.map((tab) =>
+ tab.path === tabPath ? { ...tab, content: tab.content + content } : tab
+ );
+ streamingTabsRef.current = newTabs;
+ return newTabs;
+ });
+ // Scroll to bottom after content update during streaming
+ if (isStreaming) {
+ setTimeout(() => scrollTextareaToBottom(tabPath), 0);
+ }
+ };
+
+ // Assemble skill files into XML-like format for agent consumption
+ const assembleSkillContent = (tabs: SkillFileContent[]): string => {
+ const parts: string[] = [];
+
+ for (const tab of tabs) {
+ if (tab.path === "SKILL.md") {
+ parts.push(`\n${tab.content}\n `);
+ } else {
+ parts.push(`\n${tab.content}\n `);
+ }
+ }
+
+ return parts.join("\n\n");
+ };
+
+ // Load all files for a skill into skillTabs
+ const loadSkillFiles = async (skillName: string) => {
+ try {
+ const files = await fetchSkillFiles(skillName);
+ if (files.length === 0) {
+ // Fallback: load SKILL.md content from the skill list item
+ const skill = allSkills.find((s) => s.name === skillName);
+ if (skill?.content) {
+ setSkillTabs([{ path: "SKILL.md", content: skill.content }]);
+ }
+ return;
+ }
+
+ // Flatten file tree and get all file paths.
+ // The root node's name IS the skill_name — skip the root itself and
+ // start from its children so paths stay relative (e.g. "SKILL.md", not "skill_name/SKILL.md").
+ const flattenFiles = (nodes: SkillFileNode[], prefix = ""): string[] => {
+ const result: string[] = [];
+ for (const node of nodes) {
+ if (node.type === "directory" && node.name === skillName && prefix === "") {
+ // Root directory — recurse into children without prepending the root name
+ if (node.children) {
+ result.push(...flattenFiles(node.children, ""));
+ }
+ } else {
+ const fullPath = prefix ? `${prefix}/${node.name}` : node.name;
+ if (node.type === "file") {
+ result.push(fullPath);
+ } else if (node.children) {
+ result.push(...flattenFiles(node.children, fullPath));
+ }
+ }
+ }
+ return result;
+ };
+
+ const filePaths = flattenFiles(files);
+
+ // Load content for each file
+ const tabsContent: SkillFileContent[] = [];
+ for (const filePath of filePaths) {
+ const content = await fetchSkillFileContent(skillName, filePath);
+ tabsContent.push({ path: filePath, content: content || "" });
+ }
+
+ // Sort so SKILL.md is always first
+ tabsContent.sort((a, b) => {
+ if (a.path === "SKILL.md") return -1;
+ if (b.path === "SKILL.md") return 1;
+ return a.path.localeCompare(b.path);
+ });
+
+ setSkillTabs(tabsContent);
+ setActiveSkillTab("SKILL.md");
+ } catch (error) {
+ log.error("Failed to load skill files:", error);
+ if (error instanceof SkillFilesAccessDeniedError) {
+ message.warning(error.message);
+ return;
+ }
+ // Fallback to basic content
+ const skill = allSkills.find((s) => s.name === skillName);
+ if (skill?.content) {
+ setSkillTabs([{ path: "SKILL.md", content: skill.content }]);
+ setActiveSkillTab("SKILL.md");
+ }
+ }
+ };
+
+ // Parse frontmatter YAML and update form fields
+ const parseAndUpdateFrontmatter = (frontmatterYaml: string) => {
+ try {
+ // Parse the frontmatter using js-yaml
+ const parsed = yaml.load(frontmatterYaml) as Record | null;
+ if (parsed && typeof parsed === "object") {
+ const name = typeof parsed.name === "string" ? parsed.name.trim() : "";
+ const description = typeof parsed.description === "string" ? parsed.description.trim() : "";
+ const tags = Array.isArray(parsed.tags) ? parsed.tags.filter((t): t is string => typeof t === "string") : [];
+
+ if (name) {
+ form.setFieldsValue({ name });
+ setInteractiveSkillName(name);
+ const existingSkill = allSkills.find(
+ (s) => s.name.toLowerCase() === name.toLowerCase()
+ );
+ setIsCreateMode(!existingSkill);
+ }
+ if (description) {
+ form.setFieldsValue({ description });
+ }
+ if (tags.length > 0) {
+ form.setFieldsValue({ tags });
+ }
+ }
+ } catch (e) {
+ log.warn("Failed to parse frontmatter:", e);
+ }
+ };
+
// Handle chat send for interactive creation
const handleChatSend = async () => {
if (!chatInput.trim() || isChatLoading) return;
@@ -339,13 +571,17 @@ export default function SkillBuildModal({
const currentInput = chatInput.trim();
setChatInput("");
- // Read current form fields to provide context to the model
+ // Read current form fields to provide context to the model.
const formValues = form.getFieldsValue();
+ const draft = accumulatedDraft;
+
+ // Assemble skill content from all tabs
+ const assembledContent = assembleSkillContent(skillTabs);
const formContext = [
formValues.name ? `当前技能名称：${formValues.name}` : "",
formValues.description ? `当前技能描述：${formValues.description}` : "",
formValues.tags?.length ? `当前标签：${formValues.tags.join(", ")}` : "",
- formValues.content ? `当前内容：\n${formValues.content}` : "",
+ assembledContent ? `当前技能文件内容：\n${assembledContent}` : "",
].filter(Boolean).join("\n\n");
const userMessage: ChatMessage = {
@@ -357,18 +593,17 @@ export default function SkillBuildModal({
setChatMessages((prev) => [...prev, userMessage]);
setIsChatLoading(true);
- setThinkingStep(1);
- setThinkingDescription(THINKING_STEPS_ZH.find((s) => s.step === 1)?.description || "生成技能内容中 ...");
setIsThinkingVisible(true);
+ setThinkingDescription(t("skillManagement.generatingSkill") || "生成技能内容中 ...");
- // Clear content input before streaming
- form.setFieldValue("content", "");
- setFormStreamingContent("");
- setThinkingStreamingContent("");
- setSummaryStreamingContent("");
- setIsSummaryVisible(false);
- setIsContentStreaming(true);
- // Reset streaming complete flag
+ // Clear content input before streaming — start fresh so the streamed content
+ // reflects the (possibly refined) result of this turn.
+ setSkillTabs([{ path: "SKILL.md", content: "" }]);
+ streamingTabsRef.current = [{ path: "SKILL.md", content: "" }];
+ shouldAutoScrollRef.current = { "SKILL.md": true };
+ setActiveSkillTab("SKILL.md");
+ setIsStreaming(true);
+ setSummaryContent("");
isStreamingCompleteRef.current = false;
const assistantId = (Date.now() + 1).toString();
@@ -378,56 +613,143 @@ export default function SkillBuildModal({
{ id: assistantId, role: "assistant", content: "", timestamp: new Date() },
]);
- // Track current assistant message ID for streaming updates
currentAssistantIdRef.current = assistantId;
try {
- // Build user prompt with form context
+ // Create AbortController for this request
+ abortControllerRef.current = new AbortController();
+
+ // On first turn, no existing_skill is sent → backend creates from scratch.
+ // On subsequent turns (accumulatedDraft exists), existing_skill is passed
+ // → backend follows the modify-workflow template and refines the draft.
const userPrompt = formContext
? `用户需求：${currentInput}\n\n${formContext}`
: `用户需求：${currentInput}`;
- await createSimpleSkillStream(
+ await createSkillStream(
{
user_request: userPrompt,
- existing_skill: !isCreateMode ? {
- name: formValues.name || "",
- description: formValues.description || "",
- tags: formValues.tags || [],
- content: formValues.content || "",
+ existing_skill: draft ? {
+ name: draft.name || formValues.name || "",
+ description: draft.description || formValues.description || "",
+ tags: draft.tags?.length ? draft.tags : (formValues.tags || []),
+ content: assembledContent,
} : undefined,
+ complexity: "complicated",
+ language: "zh",
},
{
+ onTaskId: (taskId) => {
+ taskIdRef.current = taskId;
+ },
onThinkingUpdate: (step, desc) => {
- setThinkingStep(step);
- setThinkingDescription(desc || THINKING_STEPS_ZH.find((s) => s.step === step)?.description || "");
+ setThinkingDescription(desc || "生成技能内容中 ...");
},
onThinkingVisible: (visible) => {
setIsThinkingVisible(visible);
},
onStepCount: (step) => {
- setThinkingStep(step);
setThinkingDescription(THINKING_STEPS_ZH.find((s) => s.step === step)?.description || "生成技能内容中 ...");
},
- onFormContent: (content) => {
+ onFrontmatter: (content) => {
+ // Accumulate frontmatter content as it streams in
+ // Parse frontmatter incrementally as it streams to update form fields
+ frontmatterBufferRef.current += content;
+ // Try to parse incrementally for form field updates
+ try {
+ const parsed = yaml.load(frontmatterBufferRef.current) as Record | null;
+ if (parsed && typeof parsed === "object") {
+ const name = typeof parsed.name === "string" ? parsed.name.trim() : "";
+ const description = typeof parsed.description === "string" ? parsed.description.trim() : "";
+ const tags = Array.isArray(parsed.tags) ? parsed.tags.filter((t): t is string => typeof t === "string") : [];
+
+ if (name) {
+ form.setFieldsValue({ name });
+ setInteractiveSkillName(name);
+ }
+ if (description) {
+ form.setFieldsValue({ description });
+ }
+ if (tags.length > 0) {
+ form.setFieldsValue({ tags });
+ }
+ }
+ } catch {
+ // YAML not complete yet, will parse when skill body starts
+ }
+ },
+ onSkillBody: (content) => {
if (isStreamingCompleteRef.current) return;
- setFormStreamingContent((prev) => prev + content);
+ // Frontmatter is complete when skill_body starts - clear the buffer
+ frontmatterBufferRef.current = "";
+ // Only add body content to textarea (no frontmatter)
+ updateTabContent("SKILL.md", content);
+ },
+ onFileContent: (path, content, isNewFile) => {
+ if (isStreamingCompleteRef.current) return;
+
+ if (isNewFile) {
+ // New file detected, create a new tab
+ setSkillTabs((prev) => {
+ const newTabs = prev.find((t) => t.path === path) ? prev : [...prev, { path, content: "" }];
+ streamingTabsRef.current = newTabs;
+ shouldAutoScrollRef.current[path] = true;
+ return newTabs;
+ });
+ }
+
+ updateTabContent(path, content);
+ setActiveSkillTab(path);
},
- onSummaryContent: (content) => {
- setSummaryStreamingContent((prev) => prev + content);
- setIsSummaryVisible(true);
+ onSummary: (content) => {
+ if (isStreamingCompleteRef.current) return;
+ setSummaryContent((prev) => prev + content);
},
- onDone: (finalResult) => {
+ onDone: (result) => {
if (!isMountedRef.current) return;
setIsThinkingVisible(false);
- setIsContentStreaming(false);
+ setIsStreaming(false);
currentAssistantIdRef.current = "";
isStreamingCompleteRef.current = true;
- const finalFormContent = finalResult.formContent;
- if (finalFormContent) {
- const skillInfo = extractSkillInfoFromContent(finalFormContent);
+ // Get SKILL.md content and strip frontmatter for textarea display
+ const skillTab = result.skillTabs.find(t => t.path === "SKILL.md");
+ const fullContent = skillTab?.content || "";
+
+ if (fullContent || result.skillTabs.length > 0) {
+ // Strip frontmatter from SKILL.md content for textarea display
+ const skillInfo = extractSkillInfoFromContent(fullContent);
+ const contentWithoutFrontmatter = skillInfo?.contentWithoutFrontmatter || "";
+
+ // Use the current tabs from ref (avoids stale closure)
+ const currentTabs = streamingTabsRef.current;
+ // Build updated tabs: start with current tabs, update matching ones from backend
+ const updatedTabs = currentTabs.map((tab) => {
+ const backendTab = result.skillTabs.find((t) => t.path === tab.path);
+ if (tab.path === "SKILL.md") {
+ return { ...tab, content: contentWithoutFrontmatter };
+ }
+ if (backendTab) {
+ return { ...tab, content: backendTab.content || tab.content };
+ }
+ return tab;
+ });
+
+ // Add any new tabs from backend that don't exist in current tabs
+ const newTabsFromBackend = result.skillTabs.filter((t) => !currentTabs.find((tab) => tab.path === t.path));
+ const finalTabs = [...updatedTabs, ...newTabsFromBackend];
+
+ // Sort so SKILL.md is always first
+ finalTabs.sort((a, b) => {
+ if (a.path === "SKILL.md") return -1;
+ if (b.path === "SKILL.md") return 1;
+ return a.path.localeCompare(b.path);
+ });
+
+ setSkillTabs(finalTabs);
+
+ // Update form fields from parsed skill info
if (skillInfo && skillInfo.name) {
form.setFieldsValue({ name: skillInfo.name });
setInteractiveSkillName(skillInfo.name);
@@ -442,10 +764,21 @@ export default function SkillBuildModal({
if (skillInfo && skillInfo.tags && skillInfo.tags.length > 0) {
form.setFieldsValue({ tags: skillInfo.tags });
}
- if (skillInfo && skillInfo.contentWithoutFrontmatter) {
- form.setFieldsValue({ content: skillInfo.contentWithoutFrontmatter });
- setFormStreamingContent(skillInfo.contentWithoutFrontmatter);
- }
+
+ // Update accumulated draft with assembled content for next turn
+ const assembledDraft = assembleSkillContent(updatedTabs);
+ const newDraft = {
+ name: skillInfo?.name || draft?.name || "",
+ description: skillInfo?.description || draft?.description || "",
+ tags: skillInfo?.tags?.length ? skillInfo.tags : (draft?.tags || []),
+ content: assembledDraft,
+ };
+ setAccumulatedDraft(newDraft);
+ setIsMultiTurn(true);
+
+ // Scroll to bottom after content is fully loaded
+ setTimeout(() => scrollTextareaToBottom("SKILL.md"), 0);
+
message.success(t("skillManagement.message.skillReadyForSave"));
}
},
@@ -453,17 +786,28 @@ export default function SkillBuildModal({
log.error("Interactive skill creation error:", errorMsg);
message.error(t("skillManagement.message.chatError"));
setChatMessages((prev) => prev.filter((m) => m.id !== assistantId));
- setIsContentStreaming(false);
+ setIsStreaming(false);
currentAssistantIdRef.current = "";
},
- }
+ },
+ { signal: abortControllerRef.current.signal }
);
} catch (error) {
+ // Handle AbortError gracefully when user stops the stream
+ const err = error as Error;
+ if (err?.name === "AbortError") {
+ // User stopped - just reset states silently
+ setIsChatLoading(false);
+ setIsStreaming(false);
+ setIsThinkingVisible(false);
+ return;
+ }
log.error("Interactive skill creation error:", error);
message.error(t("skillManagement.message.chatError"));
setChatMessages((prev) => prev.filter((m) => m.id !== assistantId));
- setIsContentStreaming(false);
+ setIsStreaming(false);
} finally {
+ abortControllerRef.current = null;
setIsChatLoading(false);
}
};
@@ -474,10 +818,38 @@ export default function SkillBuildModal({
setChatMessages([]);
form.resetFields(["name", "description", "source", "tags", "content"]);
setInteractiveSkillName("");
- setFormStreamingContent("");
- setThinkingStreamingContent("");
- setSummaryStreamingContent("");
- setIsSummaryVisible(false);
+ setSkillTabs([{ path: "SKILL.md", content: "" }]);
+ streamingTabsRef.current = [{ path: "SKILL.md", content: "" }];
+ setActiveSkillTab("SKILL.md");
+ setSummaryContent("");
+ setAccumulatedDraft(null);
+ setIsMultiTurn(false);
+ };
+
+ // Handle stop - cancel the ongoing streaming request
+ const handleStop = async () => {
+ // Call backend stop API first
+ if (taskIdRef.current) {
+ try {
+ await stopSkillCreation(taskIdRef.current);
+ } catch (error) {
+ log.error("Failed to stop backend task:", error);
+ }
+ }
+
+ // Abort frontend fetch
+ if (abortControllerRef.current) {
+ abortControllerRef.current.abort("User stopped");
+ abortControllerRef.current = null;
+ }
+
+ // Reset all states
+ setIsChatLoading(false);
+ setIsStreaming(false);
+ setIsThinkingVisible(false);
+ currentAssistantIdRef.current = "";
+ taskIdRef.current = "";
+ isStreamingCompleteRef.current = true;
};
// Scroll to bottom of chat when new messages arrive
@@ -487,16 +859,6 @@ export default function SkillBuildModal({
}
}, [chatMessages]);
- // Scroll to bottom of content textarea when streaming content updates
- useEffect(() => {
- if (formStreamingContent) {
- const textarea = document.getElementById(contentTextAreaId.current);
- if (textarea) {
- textarea.scrollTop = textarea.scrollHeight;
- }
- }
- }, [formStreamingContent]);
-
const renderInteractiveTab = () => {
return (
@@ -543,7 +905,7 @@ export default function SkillBuildModal({
: "bg-gray-100 text-gray-800"
}`}
>
- {msg.role === "assistant" && isThinkingVisible && !isSummaryVisible ? (
+ {msg.role === "assistant" && msg.id === currentAssistantIdRef.current && isThinkingVisible ? (
+ }
+ onClick={handleStop}
+ style={{ backgroundColor: "#ef4444" }}
+ />
+
+ ) : (
+ }
+ onClick={handleChatSend}
+ disabled={!chatInput.trim()}
+ style={{ width: 30, height: 30, flexShrink: 0 }}
+ />
+ )}
{/* Right side: Form */}
-
-