feat: 重构智能体元数据系统，从集中式 YAML 迁移到分布式 TOML 配置

xerrors · xerrors · commit 99aae1c00a8a · 2025-11-07T12:28:58.000+08:00
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -1 +1 @@
-See AGENTS.md
+You MUST read `./AGENTS.md`
diff --git a/docs/advanced/agents-config.md b/docs/advanced/agents-config.md
@@ -6,6 +6,20 @@
 
 仓库预置了若干可直接运行的智能体：`chatbot` 聚焦对话与动态工具调度，`mini_agent` 提供精简模板，`reporter` 演示报告类链路。这些目录展示了上下文类、Graph 构造方式、子智能体引用以及中间件组合的范例，新增功能时可以直接复用。
 
+### 智能体元数据配置
+
+每个智能体可以通过在智能体目录下创建 `metadata.toml` 文件来配置元数据信息。这个文件使用 TOML 格式，包含以下字段：
+
+- `name`: 智能体显示名称
+- `description`: 智能体功能描述
+- `examples`: 示例问题列表（数组格式）
+
+例如，`src/agents/chatbot/metadata.toml`：
+
+<<< @/../src/agents/chatbot/metadata.toml
+
+**注意**：`metadata.toml` 文件是可选的，如果没有提供，系统将使用智能体类的基本属性。
+
 ### 创建新的智能体
 
 在 `src/agents` 下新建一个包，保持与现有目录一致的结构：放置 Graph 构造逻辑（通常命名为 `graph.py`），并在包内的 `__init__.py` 中暴露主类。
diff --git a/docs/changelog/roadmap.md b/docs/changelog/roadmap.md
@@ -2,46 +2,48 @@
 
 路线图可能会经常变更，如果有强烈的建议，可以在 [issue](https://github.com/xerrors/Yuxi-Know/issues) 中提。
 
-- **[2025/10/13]** v0.3 进入 beta 测试环节，不会再封装新的特性，仅作 bug 层面的修复
 
+## v0.4
 
-## Bugs
 
-- [ ] 无法展示图谱
 
-## Next
+### 看板
 
-- [ ] 新建 DeepAgents 智能体
-- [ ] 添加对于上传文件的支持
-- [ ] 统一图谱数据结构，优化可视化方式 [#298](https://github.com/xerrors/Yuxi-Know/issues/298) <Badge type="info" text="0.4" />
-- [ ] 集成智能体评估，首先使用命令行来实现，然后考虑放在 UI 里面展示
-- [ ] 开发与生产环境隔离，构建生产镜像 <Badge type="info" text="0.4" />
+- 新建 DeepAgents 智能体（暂时没有场景）
+- 添加对于上传文件的支持
+- 统一图谱数据结构，优化可视化方式 [#298](https://github.com/xerrors/Yuxi-Know/issues/298) [#273](https://github.com/xerrors/Yuxi-Know/issues/273) <Badge type="info" text="0.4" />
+- 集成智能体评估，首先使用命令行来实现，然后考虑放在 UI 里面展示
+- 开发与生产环境隔离，构建生产镜像 <Badge type="info" text="0.4" />
+- 集成 LangFuse (观望) 添加用户日志与用户反馈模块，可以在 AgentView 中查看信息
 
+### Bugs
+- 部分异常状态下，智能体的模型名称出现重叠[#279](https://github.com/xerrors/Yuxi-Know/issues/279)
 
-## Later
+### 新增
+- 优化知识库详情页面，更加简洁清晰
 
-下面的功能**可能**会放在后续版本实现，暂时未定
+### 修复
+- 修复重排序模型实际未生效的问题
 
-- [ ] 集成 LangFuse (观望) 添加用户日志与用户反馈模块，可以在 AgentView 中查看信息
 
-## Done
+## v0.3
+### Added
+- 添加测试脚本，覆盖最常见的功能（已覆盖API）
+- 新建 tasker 模块，用来管理所有的后台任务，UI 上使用侧边栏管理。Tasker 中获取历史任务的时候，仅获取 top100 个 task。
+- 优化对文档信息的检索展示（检索结果页、详情页）
+- 优化全局配置的管理模型，优化配置管理
+- 支持 MinerU 2.5 的解析方法 <Badge type="info" text="0.3.5" />
+- 修改现有的智能体Demo，并尽量将默认助手的特性兼容到 LangGraph 的 [`create_agent`](https://docs.langchain.com/oss/python/langchain/agents) 中
+- 基于 create_agent 创建 SQL Viewer 智能体 <Badge type="info" text="0.3.5" />
+- 优化 MCP 逻辑，支持 common + special 创建方式 <Badge type="info" text="0.3.5" />
+- LightRAG 知识库应该可以支持修改 LLM
 
-
-- [x] 添加测试脚本，覆盖最常见的功能（已覆盖API）
-- [x] 新建 tasker 模块，用来管理所有的后台任务，UI 上使用侧边栏管理。
-- [x] 优化对文档信息的检索展示（检索结果页、详情页）
-- [x] 当前 ReAct 智能体有消息顺序错乱的 bug，且不会默认调用工具
-- [x] 优化全局配置的管理模型，优化配置管理
-- [x] 支持 MinerU 2.5 的解析方法 <Badge type="info" text="0.3.5" />
-- [x] 文件管理：（1）文件选择的时候会跨数据库；（2）文件校验会算上失败的文件；
-- [x] Tasker 中获取历史任务的时候，仅获取 top100 个 task。
-- [x] 修改现有的智能体Demo，并尽量将默认助手的特性兼容到 LangGraph 的 [`create_agent`](https://docs.langchain.com/oss/python/langchain/agents) 中
-- [x] 基于 create_agent 创建 SQL Viewer 智能体 <Badge type="info" text="0.3.5" />
-- [x] 优化 MCP 逻辑，支持 common + special 创建方式 <Badge type="info" text="0.3.5" />
-- [x] 修复本地知识库的 metadata 和 向量数据库中不一致的情况。
-- [x] v1 版本的 LangGraph 的工具渲染有问题
-- [x] upload 接口会阻塞主进程
-- [x] LightRAG 知识库查看不了解析后的文本，偶然出现，未复现
-- [x] LightRAG 知识库应该可以支持修改 LLM
-- [x] 智能体的加载状态有问题：（1）智能体加载没有动画；（2）切换对话和加载中，使用同一个loading状态。
-- [x] 前端工具调用渲染出现问题
+### Fixed
+- 修复本地知识库的 metadata 和 向量数据库中不一致的情况。
+- v1 版本的 LangGraph 的工具渲染有问题
+- upload 接口会阻塞主进程
+- LightRAG 知识库查看不了解析后的文本，偶然出现，未复现
+- 智能体的加载状态有问题：（1）智能体加载没有动画；（2）切换对话和加载中，使用同一个loading状态。
+- 前端工具调用渲染出现问题
+- 当前 ReAct 智能体有消息顺序错乱的 bug，且不会默认调用工具
+- 修复文件管理：（1）文件选择的时候会跨数据库；（2）文件校验会算上失败的文件；
diff --git a/server/routers/chat_router.py b/server/routers/chat_router.py
@@ -2,7 +2,6 @@
 import json
 import traceback
 import uuid
-import yaml
 from pathlib import Path
 
 from fastapi import APIRouter, Body, Depends, HTTPException
@@ -304,13 +303,22 @@ async def call_async(query):
 @chat.get("/agent")
 async def get_agent(current_user: User = Depends(get_required_user)):
     """获取所有可用智能体（需要登录）"""
-    agents = await agent_manager.get_agents_info()
-    # logger.debug(f"agents: {agents}")
-    metadata = {}
-    if Path("src/config/static/agents_meta.yaml").exists():
-        with open("src/config/static/agents_meta.yaml") as f:
-            metadata = yaml.safe_load(f)
-    return {"agents": agents, "metadata": metadata}
+    agents_info = await agent_manager.get_agents_info()
+
+    # Return agents with complete information
+    agents = [
+        {
+            "id": agent_info["id"],
+            "name": agent_info.get("name", "Unknown"),
+            "description": agent_info.get("description", ""),
+            "examples": agent_info.get("examples", []),
+            "configurable_items": agent_info.get("configurable_items", []),
+            "has_checkpointer": agent_info.get("has_checkpointer", False)
+        }
+        for agent_info in agents_info
+    ]
+
+    return {"agents": agents}
 
 
 # TODO:[未完成]这个thread_id在前端是直接生成的1234，最好传入thread_id时做校验只允许uuid4
diff --git a/src/agents/chatbot/metadata.toml b/src/agents/chatbot/metadata.toml
@@ -0,0 +1,9 @@
+name = "智能聊天助手"
+description = "基础的AI对话助手，支持工具调用，MCP，并具备丰富的知识库。"
+examples = [
+    "你好，请介绍一下你自己",
+    "帮我写一封商务邮件",
+    "解释一下什么是机器学习",
+    "推荐几本好书",
+    "如何提高工作效率？"
+]
diff --git a/src/agents/common/base.py b/src/agents/common/base.py
@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import importlib.util
 import os
 from abc import abstractmethod
 from pathlib import Path
@@ -8,6 +9,8 @@
 from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver, aiosqlite
 from langgraph.graph.state import CompiledStateGraph
 
+import tomllib as tomli
+
 from src import config as sys_config
 from src.agents.common.context import BaseContext
 from src.utils import logger
@@ -27,6 +30,7 @@ def __init__(self, **kwargs):
         self.context_schema = BaseContext
         self.workdir = Path(sys_config.save_dir) / "agents" / self.module_name
         self.workdir.mkdir(parents=True, exist_ok=True)
+        self._metadata_cache = None  # Cache for metadata to avoid repeated file reads
 
     @property
     def module_name(self) -> str:
@@ -39,10 +43,15 @@ def id(self) -> str:
         return self.__class__.__name__
 
     async def get_info(self):
+        # Load metadata from file
+        metadata = self.load_metadata()
+
+        # Merge metadata with class attributes, metadata takes precedence
         return {
             "id": self.id,
-            "name": self.name if hasattr(self, "name") else "Unknown",
-            "description": self.description if hasattr(self, "description") else "Unknown",
+            "name": metadata.get("name", getattr(self, "name", "Unknown")),
+            "description": metadata.get("description", getattr(self, "description", "Unknown")),
+            "examples": metadata.get("examples", []),
             "configurable_items": self.context_schema.get_configurable_items(),
             "has_checkpointer": await self.check_checkpointer(),
         }
@@ -138,3 +147,43 @@ async def get_async_conn(self) -> aiosqlite.Connection:
     async def get_aio_memory(self) -> AsyncSqliteSaver:
         """获取异步存储实例"""
         return AsyncSqliteSaver(await self.get_async_conn())
+
+
+    def load_metadata(self) -> dict:
+        """Load metadata from metadata.toml file in the agent's source directory."""
+        if self._metadata_cache is not None:
+            return self._metadata_cache
+
+        # Try to find metadata.toml in the agent's source directory
+        try:
+            # Get the agent's source file directory
+            agent_module = self.__class__.__module__
+
+            # Use importlib to get the module's file path
+            spec = importlib.util.find_spec(agent_module)
+            if spec and spec.origin:
+                agent_file = Path(spec.origin)
+                agent_dir = agent_file.parent
+            else:
+                # Fallback: construct path from module name
+                module_path = agent_module.replace(".", "/")
+                agent_file = Path(f"src/{module_path}.py")
+                agent_dir = agent_file.parent
+
+            metadata_file = agent_dir / "metadata.toml"
+
+            if metadata_file.exists():
+                with open(metadata_file, "rb") as f:
+                    metadata = tomli.load(f)
+                    self._metadata_cache = metadata
+                    logger.debug(f"Loaded metadata from {metadata_file}")
+                    return metadata
+            else:
+                logger.debug(f"No metadata.toml found for {self.module_name} at {metadata_file}")
+                self._metadata_cache = {}
+                return {}
+
+        except Exception as e:
+            logger.error(f"Error loading metadata for {self.module_name}: {e}")
+            self._metadata_cache = {}
+            return {}
diff --git a/src/config/static/agents_meta.yaml b/src/config/static/agents_meta.yaml
diff --git a/web/src/components/AgentChatComponent.vue b/web/src/components/AgentChatComponent.vue
@@ -56,9 +56,8 @@
       </div>
 
       <div v-else-if="!conversations.length" class="chat-examples">
-        <img v-if="currentAgentMetadata?.icon" class="agent-icons" :src="currentAgentMetadata?.icon" alt="智能体图标" />
-        <div v-else style="margin-bottom: 150px"></div>
-        <h1>您好，我是{{ currentAgentName }}！有什么可以帮您？</h1>
+        <div style="margin-bottom: 150px"></div>
+        <h1>您好，我是{{ currentAgentName }}！</h1>
         <!-- <h1>{{ currentAgent ? currentAgent.name : '请选择一个智能体开始对话' }}</h1>
         <p>{{ currentAgent ? currentAgent.description : '不同的智能体有不同的专长和能力' }}</p> -->
 
@@ -190,7 +189,12 @@ const userInput = ref('');
 
 // 从智能体元数据获取示例问题
 const exampleQuestions = computed(() => {
-  const examples = currentAgentMetadata.value?.examples || [];
+  const agentId = currentAgentId.value;
+  let examples = [];
+  if (agentId && agents.value && agents.value.length > 0) {
+    const agent = agents.value.find(a => a.id === agentId);
+    examples = agent ? (agent.examples || []) : [];
+  }
   return examples.map((text, index) => ({
     id: index + 1,
     text: text
@@ -234,12 +238,14 @@ const currentAgentId = computed(() => {
   }
 });
 
-const currentAgentMetadata = computed(() => {
+const currentAgentName = computed(() => {
   const agentId = currentAgentId.value;
-  const metadata = agentStore?.metadata || {};
-  return agentId && metadata[agentId] ? metadata[agentId] : {};
+  if (agentId && agents.value && agents.value.length > 0) {
+    const agent = agents.value.find(a => a.id === agentId);
+    return agent ? agent.name : '智能体';
+  }
+  return '智能体';
 });
-const currentAgentName = computed(() => currentAgentMetadata.value?.name || currentAgent.value?.name || '智能体');
 
 const currentAgent = computed(() => agents.value[currentAgentId.value] || null);
 const chatsList = computed(() => threads.value || []);
@@ -947,10 +953,17 @@ const handleExampleClick = (questionText) => {
 };
 
 const buildExportPayload = () => {
+  const agentId = currentAgentId.value;
+  let agentDescription = '';
+  if (agentId && agents.value && agents.value.length > 0) {
+    const agent = agents.value.find(a => a.id === agentId);
+    agentDescription = agent ? (agent.description || '') : '';
+  }
+
   const payload = {
     chatTitle: currentThread.value?.title || '新对话',
     agentName: currentAgentName.value || currentAgent.value?.name || '智能助手',
-    agentDescription: currentAgentMetadata.value?.description || currentAgent.value?.description || '',
+    agentDescription: agentDescription || currentAgent.value?.description || '',
     messages: conversations.value ? JSON.parse(JSON.stringify(conversations.value)) : [],
     onGoingMessages: onGoingConvMessages.value ? JSON.parse(JSON.stringify(onGoingConvMessages.value)) : []
   };
diff --git a/web/src/components/ChatSidebarComponent.vue b/web/src/components/ChatSidebarComponent.vue
@@ -100,8 +100,8 @@ const props = defineProps({
     default: true
   },
   agents: {
-    type: Object,
-    default: () => ({})
+    type: Array,
+    default: () => []
   },
   selectedAgentId: {
     type: String,
@@ -112,8 +112,9 @@ const props = defineProps({
 const emit = defineEmits(['create-chat', 'select-chat', 'delete-chat', 'rename-chat', 'toggle-sidebar', 'open-agent-modal']);
 
 const selectedAgentName = computed(() => {
-  if (props.selectedAgentId && props.agents && props.agents[props.selectedAgentId]) {
-    return props.agents[props.selectedAgentId].name;
+  if (props.selectedAgentId && props.agents && props.agents.length > 0) {
+    const agent = props.agents.find(a => a.id === props.selectedAgentId);
+    return agent ? agent.name : '';
   }
   return '';
 });
diff --git a/web/src/stores/agent.js b/web/src/stores/agent.js
diff --git a/web/src/views/AgentView.vue b/web/src/views/AgentView.vue

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-See AGENTS.md`
	`1`	+You MUST read `./AGENTS.md`