当前位置：首页 > news >正文

AI Agent技能(Skill)深度解析：从架构设计到工程实践

news 2026/8/13 3:33:23

1. 项目概述：从“技能”到“超能力”的认知跃迁

最近在AI开发圈里，Superpowers这个词的热度居高不下，尤其是和“Skill”结合后，仿佛打开了一扇新世界的大门。我第一次接触这个概念时，也以为它只是某个特定框架里的一个插件功能，但深入研究后才发现，这其实代表了一种全新的AI智能体（Agent）构建范式。简单来说，Superpowers Skill不是指某个具体的工具，而是一种将复杂任务拆解为可复用、可组合、可解释的“技能单元”的方法论。它让AI Agent从一个只能执行简单指令的“实习生”，变成了一个拥有丰富工具箱、能自主规划并解决复杂问题的“专家”。

如果你正在学习或从事AI Agent开发，无论是想用Hermes Agent、Claude Code还是其他框架，理解Skill的深度解析都至关重要。这不仅仅是学会调用几个API，而是关乎你如何设计一个真正智能、可靠且可维护的AI系统。一个设计良好的Skill，就像给Agent装配了一个模块化的超能力模块，可以清晰地定义输入、输出、执行逻辑和错误处理。而逐行解析，正是我们从“会用”到“精通”，从“复制代码”到“创造价值”的关键一步。本文将从一个一线开发者的视角，带你彻底拆解Skill的构成，分享从设计、编码到调试的全流程实战经验，让你不仅能看懂别人的Skill，更能写出属于自己的、高效稳定的“超能力”。

2. 核心理念与架构设计拆解

2.1 为什么是“Skill”而非“Function”？

在传统编程中，我们习惯用“函数”（Function）来封装一段可复用的逻辑。但在AI Agent的语境下，“技能”（Skill）是一个更高级的抽象。两者的核心区别在于意图的明确性和上下文感知能力。

一个普通的函数，比如calculate_sum(a, b)，它的目的是明确的，就是求和。但一个Skill，例如AnalyzeMarketTrend(symbol, period)，它的意图不仅仅是执行一段分析代码，更重要的是，它需要让Agent“理解”这个技能是用来做什么的、在什么场景下使用、需要什么前置条件、会产生什么影响。Skill通常包含丰富的元数据（Metadata），例如自然语言描述、预期输入输出的格式、使用示例、甚至是对技能能力和局限性的说明。这使得Agent能够通过自然语言指令或规划器，动态地发现、选择和组合技能，而不是硬编码调用函数。

举个例子，你告诉Agent：“帮我分析一下最近三个月特斯拉的股价趋势，并总结可能的原因。” 一个基于Skill架构的Agent会这样思考：

技能发现：我需要“股价数据获取”技能和“市场趋势分析”技能。
技能编排：先调用“数据获取”技能，参数是symbol=TSLA和period=3months，拿到数据后，再将其作为输入传递给“趋势分析”技能。
执行与整合：按顺序执行，并将两个技能的结果整合成一份完整的报告。

这个过程中，Agent不需要事先被编程好“如何分析特斯拉”，它只需要知道有哪些可用的Skill以及如何组合它们。这种灵活性是构建通用型AI智能体的基石。

2.2 Superpowers Skill 的核心组件剖析

一个完整的、符合Superpowers理念的Skill，通常包含以下几个核心组件，我们可以将其视为一个标准的“技能契约”：

技能标识与元信息：这是技能的“身份证”。包括唯一的技能名称（如web_search）、版本号、作者、以及最重要的——自然语言描述。描述必须清晰，让LLM（大语言模型）能准确理解其用途。例如：“该技能用于在互联网上进行关键词搜索，并返回简洁的摘要和来源链接。”
输入模式：明确定义技能需要哪些参数。这不仅仅是类型检查（如字符串、数字），更包括参数的语义描述、是否可选、默认值等。例如，一个send_email技能，其输入模式需要定义recipient（收件人）、subject（主题）、body（正文）和可选的attachment_path（附件路径）。
输出模式：定义技能执行成功后返回的数据结构。同样，这需要清晰的语义。例如，web_search技能可能输出一个包含summary（摘要）、urls（链接列表）和search_query（使用的查询词）的对象。
执行体：这是技能的具体实现代码。它可以是调用一个外部API（如谷歌搜索）、执行一段本地计算、操作数据库，甚至是调用另一个AI模型。关键点在于，执行体内部需要处理各种边界情况和错误，并以定义好的输出模式返回结果，或以标准化的方式抛出异常。
错误处理与重试逻辑：一个健壮的Skill必须包含这部分。网络请求可能会超时，API可能有速率限制，输入可能不符合预期。技能内部需要捕获这些异常，并根据策略决定是直接失败、返回降级结果，还是进行有限次数的重试。
技能依赖与组合声明（高级）：某些复杂技能可能依赖于其他更基础的技能。在Skill的元信息中声明这种依赖关系，可以帮助Agent的规划器更优地进行任务分解。例如，“生成季度报告”技能可能依赖于“获取财务数据”技能和“生成图表”技能。

理解这个架构，是进行逐行深度解析的前提。接下来，我们将通过一个具体的实例，将上述每一个组件对应到真实的代码行中。

3. 逐行深度解析：一个“网页摘要”Skill实战

让我们以一个相对复杂但非常实用的“网页内容抓取与摘要”技能为例，进行逐行解析。这个技能的目标是：给定一个URL，抓取其主要文本内容，并利用LLM生成一段简洁的摘要。

3.1 技能定义与元信息声明

import asyncio from typing import Dict, Any, Optional from pydantic import BaseModel, Field import aiohttp from bs4 import BeautifulSoup import logging # 定义技能的输入模型 class WebSummarizeInput(BaseModel): """网页摘要技能的输入参数""" url: str = Field(..., description="需要摘要的网页URL地址，必须以http或https开头") summary_length: Optional[str] = Field("medium", description="摘要长度，可选 'short'（一句话）, 'medium'（一段话）, 'long'（多段落）") focus_on: Optional[str] = Field(None, description="摘要侧重点，例如 '技术细节'， '核心观点'， '事件脉络'") # 定义技能的输出模型 class WebSummarizeOutput(BaseModel): """网页摘要技能的输出结果""" url: str = Field(..., description="原始URL") title: str = Field(..., description="网页标题") summary: str = Field(..., description="生成的摘要内容") key_points: list[str] = Field(default_factory=list, description="关键要点列表") status: str = Field(..., description="执行状态：success, partial_success, failed") error_message: Optional[str] = Field(None, description="如果失败，错误信息") # 技能主类 class WebSummarizeSkill: """网页内容抓取与摘要生成技能""" def __init__(self, llm_client, http_timeout: int = 10): """ 初始化技能 :param llm_client: 配置好的LLM客户端（如OpenAI, Anthropic等） :param http_timeout: 网页请求超时时间（秒） """ self.llm = llm_client self.timeout = http_timeout self.logger = logging.getLogger(__name__) # 技能元信息 - 这是让Agent理解该技能的关键 self.metadata = { "name": "web_summarize", "version": "1.1.0", "description": "抓取指定URL的网页内容，并利用AI模型生成结构化的摘要和关键要点。适用于快速理解长篇文章、新闻或文档的核心内容。", "input_schema": WebSummarizeInput.schema(), "output_schema": WebSummarizeOutput.schema(), "examples": [ { "input": {"url": "https://example.com/blog/ai-trends-2024", "summary_length": "medium"}, "output": {"title": "2024年AI趋势预测", "summary": "文章讨论了...", "key_points": ["趋势1", "趋势2"], "status": "success"} } ] }

逐行解析与设计思考：

第1-6行（导入）：这是技能的基础依赖。asyncio和aiohttp用于异步HTTP请求，这是I/O密集型操作（网络请求）的最佳实践，能极大提升Agent并发执行多个技能时的效率。pydantic用于数据验证和序列化，它能确保输入输出数据的结构严格符合定义，避免后续处理中出现意外错误。BeautifulSoup是经典的HTML解析库。选择aiohttp而非requests，是因为在Agent这种高并发、异步调用的场景下，异步库能避免阻塞整个事件循环。
第9-15行（输入模型）：使用Pydantic的BaseModel定义输入。Field类的description参数至关重要，它为LLM提供了每个参数的语义信息。例如，LLM在思考如何使用这个技能时，会读到“必须以http或https开头”这个描述，从而避免提供无效的URL。Optional和默认值让技能更灵活。
第18-25行（输出模型）：输出模型同样重要。除了核心的summary，我们还定义了title、key_points（关键点列表）和status。status字段是一个很好的实践，它明确区分了完全成功、部分成功（如抓取成功但摘要生成不理想）和完全失败，便于上游调用者（Agent）进行决策。default_factory=list确保即使没有关键点，返回的也是一个空列表而非None，减少空指针错误。
第28-53行（技能类与元信息）：__init__方法接收外部依赖（llm_client），这是一种依赖注入模式，使得技能更容易测试和配置。metadata字典是这个技能的灵魂。description字段用自然语言清晰说明了技能的功能和适用场景。input_schema和output_schema通过Pydantic的schema()方法自动生成JSON Schema，这是机器可读的严格契约。examples提供了使用示例，能极大地帮助LLM理解如何调用此技能。在Hermes Agent、Claude Code等框架中，这些元信息通常会被自动收集并注册到技能库中，供规划器（Planner）检索和使用。

3.2 核心执行逻辑与错误处理

async def execute(self, input_data: WebSummarizeInput) -> WebSummarizeOutput: """ 执行技能的核心方法 """ self.logger.info(f"开始执行网页摘要技能，URL: {input_data.url}") result_template = { "url": input_data.url, "title": "", "summary": "", "key_points": [], "status": "failed", "error_message": None } try: # 步骤1: 抓取网页内容 html_content = await self._fetch_html(input_data.url) if not html_content: result_template["error_message"] = "无法获取网页内容或内容为空" result_template["status"] = "failed" return WebSummarizeOutput(**result_template) # 步骤2: 解析HTML，提取标题和正文 title, main_text = self._parse_html(html_content) if not main_text or len(main_text.strip()) < 50: # 简单的内容长度校验 self.logger.warning(f"网页内容过少或解析失败，URL: {input_data.url}") result_template["title"] = title if title else "Unknown" result_template["status"] = "partial_success" result_template["error_message"] = "成功获取网页但正文内容过少，摘要可能不准确" # 即使内容少，也继续尝试生成摘要 else: result_template["title"] = title result_template["status"] = "success" # 步骤3: 调用LLM生成摘要和关键点 summary_result = await self._generate_summary( main_text, input_data.summary_length, input_data.focus_on ) result_template["summary"] = summary_result.get("summary", "") result_template["key_points"] = summary_result.get("key_points", []) # 如果摘要生成失败，但网页抓取成功，更新状态为部分成功 if result_template["status"] == "success" and not result_template["summary"]: result_template["status"] = "partial_success" result_template["error_message"] = "网页抓取成功，但AI摘要生成失败" except aiohttp.ClientError as e: self.logger.error(f"网络请求错误: {e}", exc_info=True) result_template["error_message"] = f"网络请求失败: {str(e)}" except Exception as e: self.logger.error(f"技能执行过程中发生未知错误: {e}", exc_info=True) result_template["error_message"] = f"内部处理错误: {str(e)}" return WebSummarizeOutput(**result_template)

逐行解析与避坑指南：

第3-12行（方法定义与初始化）：execute方法是技能的单一入口，采用异步设计。一开始就初始化一个包含默认失败状态的result_template，这是一个防御性编程技巧，确保任何异常路径下都有返回值。
第15-22行（网页抓取与初级错误处理）：调用私有方法_fetch_html。如果返回空内容，立即返回失败状态。这里的关键是快速失败（Fail Fast）原则：对于明显无法继续的条件（如连网页都抓不到），尽早退出并给出明确错误，避免浪费计算资源进行后续无意义的处理。
第25-35行（内容解析与状态管理）：调用_parse_html解析内容。这里引入了一个“部分成功”（partial_success）的状态。这是处理现实世界复杂性的重要技巧。网页可能抓取成功，但内容可能是登录页、错误页或内容极少的页面。与其直接判为失败，不如标记为部分成功，并携带警告信息，让调用者（Agent）决定下一步动作（例如，尝试另一个URL，或直接使用有限的摘要）。len(main_text.strip()) < 50这个启发式规则非常实用，能过滤掉大量无意义的页面。
第38-48行（LLM调用与结果整合）：调用_generate_summary私有方法。注意，这里将LLM调用的结果与之前的结果模板进行了合并。并且增加了另一个检查：即使网页抓取标记为成功，如果LLM没有返回摘要，依然将状态降级为“部分成功”。这体现了结果导向的验证思想。
第51-58行（异常捕获）：使用try...except块捕获了特定异常（aiohttp.ClientError）和通用异常。记录详细的日志（exc_info=True包含堆栈跟踪）对于后期调试至关重要。错误信息被清晰地放入error_message字段，而不是抛出异常，这保证了execute方法总是返回一个WebSummarizeOutput对象，保持了接口的稳定性。在Skill设计中，应尽量避免让异常直接抛给Agent，而是将其转化为技能输出的一部分，这样Agent的规划器可以根据状态和错误信息进行更智能的后续规划（如重试、换用备用技能等）。

3.3 关键子方法实现与细节打磨

async def _fetch_html(self, url: str) -> Optional[str]: """异步抓取网页HTML内容""" headers = { 'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36' } try: timeout = aiohttp.ClientTimeout(total=self.timeout) async with aiohttp.ClientSession(timeout=timeout) as session: async with session.get(url, headers=headers) as response: response.raise_for_status() # 检查HTTP状态码是否为200 # 优先使用响应的编码，否则默认utf-8，并忽略解码错误 content = await response.read() charset = response.charset if response.charset else 'utf-8' try: return content.decode(charset) except UnicodeDecodeError: # 如果指定编码失败，尝试常用编码 for enc in ['utf-8', 'gbk', 'gb2312', 'iso-8859-1']: try: return content.decode(enc) except UnicodeDecodeError: continue self.logger.warning(f"无法解码网页内容，URL: {url}") return None except asyncio.TimeoutError: self.logger.error(f"请求超时，URL: {url}") return None except aiohttp.ClientResponseError as e: self.logger.error(f"HTTP错误 {e.status}: {e.message}, URL: {url}") return None def _parse_html(self, html: str) -> tuple[str, str]: """解析HTML，提取标题和正文""" soup = BeautifulSoup(html, 'html.parser') # 提取标题 title_tag = soup.find('title') title = title_tag.get_text(strip=True) if title_tag else "No Title" # 尝试多种策略提取正文 main_content = "" # 策略1: 寻找常见的正文容器标签（如<article>, <main>, 特定class的<div>） for tag in ['article', 'main']: element = soup.find(tag) if element: main_content = element.get_text(separator=' ', strip=True) break # 策略2: 如果策略1失败，使用启发式方法：寻找包含最多文本的<p>标签集合 if not main_content: paragraphs = soup.find_all('p') if paragraphs: # 过滤掉过短的段落（可能是导航、页脚等） meaningful_paras = [p.get_text(strip=True) for p in paragraphs if len(p.get_text(strip=True)) > 20] main_content = ' '.join(meaningful_paras) # 策略3: 作为最后手段，获取整个body的文本，但去除script, style等 if not main_content or len(main_content) < 100: for script in soup(["script", "style", "nav", "footer", "header"]): script.decompose() main_content = soup.get_text(separator=' ', strip=True) # 简单的文本清理：去除过多空白字符 import re main_content = re.sub(r'\s+', ' ', main_content).strip() return title, main_content async def _generate_summary(self, text: str, length: str, focus: Optional[str]) -> Dict[str, Any]: """调用LLM生成摘要和关键点""" if not text: return {"summary": "", "key_points": []} # 构造LLM提示词（Prompt） length_map = {"short": "一句话", "medium": "一个段落", "long": "三到四个段落"} length_desc = length_map.get(length, "一个段落") focus_instruction = f"请特别关注「{focus}」方面的内容。" if focus else "" prompt = f""" 请对以下文本内容生成摘要。 摘要要求：{length_desc}，语言简洁明了。 {focus_instruction} 同时，请提取3到5个最关键的要點，以列表形式呈现。 文本内容： {text[:6000]} # 限制输入长度，避免超出LLM上下文窗口 请严格按照以下JSON格式回复，不要包含任何其他说明： {{ "summary": "生成的摘要内容", "key_points": ["要点1", "要点2", "要点3"] }} """ try: # 调用LLM客户端（这里以OpenAI格式为例） response = await self.llm.chat.completions.create( model="gpt-3.5-turbo", # 或 "claude-3-haiku"等 messages=[{"role": "user", "content": prompt}], temperature=0.3, # 较低的温度使输出更稳定、更聚焦 response_format={"type": "json_object"} # 要求返回JSON，便于解析 ) import json result = json.loads(response.choices[0].message.content) return result except Exception as e: self.logger.error(f"LLM调用失败: {e}") # 降级方案：如果LLM调用失败，返回一个简单的基于规则的摘要 sentences = text.split('. ') simple_summary = '. '.join(sentences[:3]) + '.' if len(sentences) >= 3 else text[:300] + '...' return { "summary": f"(摘要生成服务暂不可用，以下是文本前导部分): {simple_summary}", "key_points": [] }

逐行解析与经验技巧：

_fetch_html方法：
- User-Agent设置：模拟浏览器访问，这是绕过简单反爬机制的基础。
- 编码处理：这是网页抓取中最常见的坑之一。代码中先尝试使用响应头声明的编码，失败后则遍历常见编码进行尝试。永远不要假设网页是UTF-8编码，特别是中文网站。
- 异常细分：明确区分了超时（asyncio.TimeoutError）和HTTP错误（aiohttp.ClientResponseError），便于上层进行不同的重试或降级策略。
_parse_html方法：
- 分层解析策略：采用了从精确到模糊的多层策略。优先寻找语义化标签（<article>,<main>），这能最准确地定位核心内容。如果失败，则寻找所有段落（<p>）并过滤掉过短的（可能是噪音）。最后的手段是获取清理后的全部文本。这种“策略链”模式在解析不规则HTML时非常有效。
- 文本清理：使用decompose()移除无关标签（script, style等），比简单的extract()更彻底。最后用正则表达式合并多余空白。
_generate_summary方法：
- Prompt工程：这是技能效果的核心。Prompt中明确了任务、要求（长度、焦点）、输出格式（JSON），并提供了示例结构。要求返回JSON格式并指定response_format，可以极大提高结果的可解析性和稳定性。
- 输入截断：text[:6000]是一个重要的安全措施，防止过长的文本超出LLM的上下文限制导致失败。
- 降级方案：在LLM调用失败的except块中，提供了一个基于规则的简单摘要作为降级方案。这是构建鲁棒性技能的关键：即使核心服务（LLM）不可用，技能也能提供某种程度的有用输出，而不是完全崩溃。
- Temperature参数：设置为较低的0.3，是为了让摘要生成更确定、更少“创造性”，更适合事实性内容的总结。

4. 技能注册、测试与集成到Agent

4.1 技能注册与发现机制

写好的Skill需要被Agent框架“知道”才能被调用。不同框架有不同方式，但核心思想一致：将技能的元信息注册到一个中央仓库。

# 假设在一个技能管理模块中 class SkillRegistry: def __init__(self): self._skills = {} def register(self, skill_instance): """注册一个技能实例""" skill_name = skill_instance.metadata["name"] if skill_name in self._skills: self.logger.warning(f"技能 '{skill_name}' 已存在，将被覆盖。") self._skills[skill_name] = { "instance": skill_instance, "metadata": skill_instance.metadata } print(f"技能已注册: {skill_name} (v{skill_instance.metadata['version']})") def get_skill(self, name): """根据名称获取技能""" return self._skills.get(name) def list_skills(self): """列出所有可用技能及其描述""" return [info["metadata"] for info in self._skills.values()] # 使用示例 registry = SkillRegistry() llm_client = OpenAI(api_key="your_key") # 初始化LLM客户端 summarize_skill = WebSummarizeSkill(llm_client=llm_client) registry.register(summarize_skill) # Agent的规划器可以查询技能列表 for skill_info in registry.list_skills(): print(f"- {skill_info['name']}: {skill_info['description']}")

关键点：注册中心不仅存储技能实例，更重要的是存储其元数据（metadata）。当Agent接收到一个自然语言任务时，规划器（通常也是一个LLM）会查询这个技能列表，通过对比任务描述和技能描述，来选择合适的技能进行组合。这就是为什么技能的description和examples字段如此重要。

4.2 单元测试与集成测试

一个没有经过充分测试的Skill是危险的，尤其是在生产环境中。测试应覆盖主要执行路径和异常情况。

import pytest from unittest.mock import AsyncMock, patch, MagicMock @pytest.mark.asyncio async def test_web_summarize_success(): """测试技能成功执行路径""" # 1. 创建Mock LLM客户端，模拟返回固定摘要 mock_llm = AsyncMock() fake_llm_response = MagicMock() fake_llm_response.choices[0].message.content = '{"summary": "这是一篇关于AI的测试文章摘要。", "key_points": ["要点A", "要点B"]}' mock_llm.chat.completions.create = AsyncMock(return_value=fake_llm_response) # 2. 创建技能实例 skill = WebSummarizeSkill(llm_client=mock_llm) # 3. Mock网络请求，返回模拟的HTML with patch('aiohttp.ClientSession.get') as mock_get: mock_resp = AsyncMock() mock_resp.raise_for_status = MagicMock() mock_resp.read = AsyncMock(return_value=b'<html><title>测试页面</title><article><p>这是一篇很长的测试文章内容。</p></article></html>') mock_resp.charset = 'utf-8' mock_get.return_value.__aenter__.return_value = mock_resp # 4. 执行技能 input_data = WebSummarizeInput(url="https://example.com/test") result = await skill.execute(input_data) # 5. 断言验证 assert result.status == "success" assert "测试页面" in result.title assert "摘要" in result.summary assert len(result.key_points) > 0 assert result.error_message is None @pytest.mark.asyncio async def test_web_summarize_network_failure(): """测试网络请求失败的情况""" mock_llm = AsyncMock() skill = WebSummarizeSkill(llm_client=mock_llm) with patch('aiohttp.ClientSession.get', side_effect=aiohttp.ClientError("Network unreachable")): input_data = WebSummarizeInput(url="https://example.com/test") result = await skill.execute(input_data) assert result.status == "failed" assert result.error_message is not None assert "Network" in result.error_message # 确保LLM没有被调用（因为前置步骤已失败） assert not mock_llm.chat.completions.create.called @pytest.mark.asyncio async def test_web_summarize_llm_fallback(): """测试LLM调用失败时，降级方案是否生效""" mock_llm = AsyncMock() # 模拟LLM调用抛出异常 mock_llm.chat.completions.create = AsyncMock(side_effect=Exception("API timeout")) skill = WebSummarizeSkill(llm_client=mock_llm) with patch('aiohttp.ClientSession.get'): # 模拟一个成功的网页响应 mock_resp = AsyncMock() mock_resp.raise_for_status = MagicMock() mock_resp.read = AsyncMock(return_value=b'<html><title>测试</title><body><p>一些文本内容。</p></body></html>') mock_resp.charset = 'utf-8' with patch('aiohttp.ClientSession.get', return_value=mock_resp): input_data = WebSummarizeInput(url="https://example.com/test") result = await skill.execute(input_data) # 状态应为部分成功，且摘要应包含降级提示 assert result.status == "partial_success" assert "摘要生成服务暂不可用" in result.summary or "(摘要生成服务暂不可用" in result.summary

测试经验：

Mock外部依赖：使用unittest.mock彻底模拟网络请求和LLM调用，使测试快速、稳定且不依赖外部服务。
测试异常流：不仅要测试“阳光路径”，更要测试各种失败场景（网络错误、解析失败、LLM异常）。这能确保技能的鲁棒性。
验证状态机：检查技能在不同错误条件下返回的status字段是否符合预期（success,partial_success,failed）。

4.3 在Agent工作流中调用

最后，我们看看这个Skill如何被一个简单的Agent工作流调用。

class SimpleAgent: def __init__(self, skill_registry): self.registry = skill_registry self.llm_planner = OpenAI(api_key="your_key") # 用于规划的LLM async def run_task(self, user_query: str): """运行一个用户任务""" print(f"用户请求: {user_query}") # 步骤1: 规划 - 决定使用哪个技能（这里简化，实际可能用LLM） # 假设我们根据关键词简单判断 if "总结" in user_query or "摘要" in user_query: skill_name = "web_summarize" # 这里可以更智能地用LLM从query中提取参数 # 例如，用另一个LLM调用将“总结一下https://xxx.com这篇文章”解析为 {"url": "https://xxx.com"} input_params = {"url": "https://example.com/ai-article"} # 简化示例 else: return "抱歉，暂无处理此请求的技能。" # 步骤2: 执行 skill_info = self.registry.get_skill(skill_name) if not skill_info: return f"未找到技能: {skill_name}" skill_instance = skill_info["instance"] # 将字典参数转换为技能期望的输入模型 input_model = skill_instance.metadata["input_schema"]["cls"] # 假设能从schema获取模型类 validated_input = input_model(**input_params) result = await skill_instance.execute(validated_input) # 步骤3: 后处理与响应 if result.status == "success": response = f"已完成摘要。标题：{result.title}\n\n摘要：{result.summary}\n\n关键点：\n" + "\n".join(f"- {kp}" for kp in result.key_points) elif result.status == "partial_success": response = f"任务部分完成。{result.error_message}\n\n以下是获取到的信息：\n标题：{result.title}\n摘要：{result.summary}" else: response = f"任务失败。错误：{result.error_message}" return response # 运行示例 async def main(): registry = SkillRegistry() llm = OpenAI(api_key="your_key") registry.register(WebSummarizeSkill(llm)) agent = SimpleAgent(registry) response = await agent.run_task("请总结一下这篇关于人工智能的文章") print(response)

在这个简化示例中，Agent根据用户查询决定调用web_summarize技能，构造输入，执行技能，并根据技能返回的status生成不同的最终回复。一个成熟的Agent框架（如Hermes）会有一个更复杂的规划器（Planner），它利用所有注册技能的元描述，动态地将复杂任务分解和映射到一系列技能上。

5. 高级技巧、常见问题与性能优化

5.1 技能设计的高级模式

技能编排：一个技能可以调用其他技能。例如，一个ResearchTopic技能内部可以编排调用web_search、web_summarize和save_to_database技能。设计时要注意避免循环依赖，并考虑错误在技能链中的传播。
技能参数化与配置化：将技能的行为通过配置暴露出来。例如，可以在Skill的metadata中增加一个config_schema，允许在注册时设置http_timeout、retry_times等，使技能更灵活。
技能版本管理：metadata中的version字段很重要。当技能逻辑更新时，应升级版本号。Agent框架可以支持多版本技能共存，由规划器根据需求选择特定版本。
技能的热重载与动态注册：在生产环境中，可能需要在不重启Agent的情况下更新或添加技能。这需要技能注册中心支持动态添加、移除和更新技能实例及其元数据。

5.2 常见问题排查清单

问题现象	可能原因	排查步骤与解决方案
Agent找不到技能	1. 技能未正确注册到Registry。 2. 技能名称在查询时拼写错误。 3. Registry实例在Agent中未正确注入。	1. 检查注册代码是否执行，打印`registry.list_skills()`确认。 2. 检查规划器调用技能时使用的名称是否与`metadata['name']`完全一致（大小写敏感）。 3. 确保Agent初始化时接收了正确的registry实例。
技能执行超时	1. 网络请求超时设置过短。 2. LLM响应慢。 3. 技能内部有同步阻塞操作。	1. 适当增加`http_timeout`和LLM调用的超时参数。 2. 为所有I/O操作（网络、LLM）添加显式超时控制。 3. 检查代码，确保在异步函数中使用了异步库，没有混用同步阻塞调用（如`requests`库）。
技能返回结果格式错误	1. LLM没有按照指定的JSON格式返回。 2. 技能输出模型与返回数据不匹配。 3. 网页解析提取到了非文本内容（如图片代码）。	1. 强化Prompt，明确要求JSON格式，并使用LLM的`response_format`参数（如果支持）。 2. 在技能`execute`方法中，对LLM返回结果增加`try...except json.JSONDecodeError`处理，提供默认值。 3. 在`_parse_html`方法中加强文本清洗，使用更严格的正则过滤或机器学习模型识别正文。
技能部分成功时，Agent处理不当	Agent的后续逻辑只处理了`success`状态，忽略了`partial_success`。	在Agent调用技能后，必须根据`status`字段进行分支处理。部分成功可能包含仍有价值的信息，应酌情使用或请求用户确认。
技能并发执行时性能低下	1. 技能内部是同步阻塞的。 2. 大量技能共享同一个LLM客户端导致瓶颈。	1. 将所有技能的核心方法改为异步（`async def`），并使用异步I/O库。 2. 考虑为LLM客户端配置连接池，或对高频率技能使用缓存机制（如对相同URL的摘要结果缓存一段时间）。

5.3 性能优化与最佳实践

缓存策略：对于web_summarize这类技能，可以对(url, summary_length, focus_on)三元组进行哈希，将结果缓存一段时间（如10分钟）。这能极大减少对同一资源的重复请求和LLM调用。可以使用functools.lru_cache（同步）或aiocache（异步）。
异步并发：确保技能从内到外都是异步的。如果技能内部有CPU密集型计算（如复杂的文本处理），应考虑使用asyncio.to_thread将其放到线程池中执行，避免阻塞事件循环。
资源限制与熔断：在技能级别或Agent级别实现限流和熔断。例如，限制web_summarize技能每分钟最多调用某个外部API 30次。当失败率超过一定阈值时，暂时熔断该技能，避免雪崩效应。
可观测性：在技能的关键节点（开始、结束、错误）记录结构化日志，并发送指标（如执行耗时、成功率）到监控系统（如Prometheus）。这能帮助你快速定位性能瓶颈和故障点。
测试覆盖率：为目标技能编写高覆盖率的单元测试和集成测试，特别是对于网络、解析和LLM调用的各种边缘情况。这能保证技能迭代时的质量。