您现在的位置是：网站首页> AI人工智能
AI智体Agent创建经验收集
- AI人工智能
- 2026-08-08
- 2847人已阅读
AI智体Agent创建经验收集
*LangChain Agent框架支持Python与.NET*
客户端将MCP工具列表和用户问题-》大语言模型-》需要调用MCP的信息返回给调用模型的客户端，客户端调用指定MCP->客户端获得MCP结果-》大语言模型-》返回给最终客户
***Skills不是AI模型标准，Claude有自己的Skills,OpenClaw也是自己的Skills标准***
***一个标准的skill例子包含完整代码及LangChain调用***
LangChain.NET如何调用Ollama制作知识库和调用MCP服务
掌握 browser-use：基于 DeepSeek 的浏览器自动化实战
Cherry Studio 新版本 1.2.9 一键式添加MCP服务器
最强AI Agent开发平台，Coze Studio本地部署整合包
***大模型功能扩展技术收集***
按这样说的话Agent自动识别Skills是哪个语言开发和自动识别调用skills里哪个函数？
一个标准的skill例子包含完整代码及LangChain调用
# 2026 年主流 AI Agent 开发工具全分类
按**代码开发框架、低代码 / 可视化平台、大厂云 Agent 工具、本地离线私有化工具、专用垂直 Agent 工具**五大类划分，覆盖个人原型、企业私有化、多智能体协作、本地无云部署全场景。
## 一、代码级开源 Agent 开发框架（工程师首选，高度自定义）
### 1. LangChain + LangGraph（行业标准，生产级首选）
- 定位：通用 LLM/Agent 底层生态，LangGraph 解决 LangChain 无状态缺陷，**图状态机管理多轮分支、循环、记忆、人工介入**
- 核心能力：工具调用、长短记忆、RAG 集成、分支流程、失败重试、多模型兼容（通义千问、Qwen、Llama、Claude）
- 适用：复杂业务 Agent、企业自动化、需要精准流程控制的项目
- 优缺点：生态最完善；学习曲线偏高，适合长期工程落地
### 2. CrewAI（多角色团队智能体，新手友好）
- 定位：专门做**多 Agent 团队协作**，无 LangChain 依赖，声明式角色定义（角色、目标、背景）
- 核心：定义不同岗位 Agent（研究员、分析师、写稿、审核）自动分工、传递结果；2026 新增 Flow 事件驱动生产工作流
- 适用：市场调研、内容生产、多步骤数据分析、多人协同任务
- 优势：代码极简，开箱即用，支持私有化部署
### 3. Microsoft AutoGen（微软多智能体对话框架）
- 定位：多 Agent 对话交互，模拟专家互相沟通解决复杂问题，Python/.NET 双栈
- 特色：Agent 之间自主对话协商、代码沙盒、人类介入节点、支持分层协作
- 适用：科研、代码开发 Agent、复杂数学 / 逻辑求解、内部专家系统
### 4. Semantic Kernel（微软企业级技能框架）
- 定位：面向微软生态（Azure、Office），主打**可复用技能插件、长期记忆、企业权限**
- 适配：.NET/C# 开发者、Windows 企业内网、Office 自动化 Agent
### 5. OpenAI Agents SDK / Swarm（OpenAI 官方轻量框架）
- 轻量多 Agent 调度，极简 API，适合基于 GPT 快速搭建多智能体原型；Swarm 专为工具分发、Agent 交接设计。
### 6. 其他热门开源框架
1. LlamaIndex：RAG 专用 Agent 框架，知识库检索增强，企业文档问答智能体首选
2. Mastra：TypeScript 现代栈 Agent 框架，内置评估、监控、RAG，前端 / Node 项目友好
3. PydanticAI：强类型 Schema 驱动，结构化输出稳定，对接数据库、API 业务系统
4. 字节 M3-Agent：国产开源多智能体协作框架，适配 Qwen 系列大模型
## 二、低代码 / 可视化 Agent 平台（零 / 少代码，快速落地、支持私有化）
### 1. Dify（国内最主流开源私有化平台）
- 核心：拖拽式 Agent 编排、RAG 知识库、插件市场、API 对外输出、Docker 一键私有化部署
- 支持自定义工具、多轮流程、人机协同，中小企业私有部署首选
- 适配场景：企业客服、内部知识库助手、办公自动化 Agent
### 2. Coze 扣子（字节跳动，国内低代码标杆）
- 可视化画布，海量官方插件（微信、飞书、数据库、爬虫），一键发布网页 / 小程序 / 机器人
- 云端免费额度充足，也支持私有化企业版；国内开发者快速做上线产品首选稀土掘金
### 3. Langflow
- LangChain 配套可视化编辑器，拖拽搭建 LangGraph 流程，不用手写大量 Python 代码
- 适合已有 LangChain 技术栈团队快速调试流程
### 4. n8n（通用自动化 + Agent 融合）
- 万能工作流引擎，数百种第三方 API / 数据库连接器，搭配 LLM 节点构建自动化 Agent
- 本地 Docker 部署，无厂商锁定，适合复杂跨系统自动化（爬虫、表单、邮件、ERP 联动）
### 5. Flowise
- 开源低代码 LLM 编排，轻量化，PoC 原型快速验证，资源占用低
## 三、国内外大厂云端 Agent 开发平台（开箱即用，生态完整）
### 国内厂商
1. 阿里云百炼
千问配套 Agent 开发平台，支持多智能体、工具调用、企业知识库，对接淘宝 / 钉钉生态
2. 腾讯元宝智能体广场 / WorkBuddy
办公场景 Agent 原生支持，打通企业微信、文档、会议自动化
3. 科大讯飞 Astron Agent
政企合规级平台，语音 + 文本双模态智能体，政务、教育行业适配
4. 字节 Coze 云平台
面向 C 端 / 中小商家，快速生成可分发 AI 智能体
### 海外厂商
1. OpenAI GPTs：无代码创建专属 Agent，内置工具、知识库，适合个人轻量场景
2. Google ADK：Gemini 配套开发套件，云原生、MCP 协议原生支持、完整评测流水线
3. Anthropic Claude Agent SDK：超长上下文，安全工具调用，文档处理类 Agent 最优
## 四、本地离线 / 零云私有化 Agent 工具（数据不出本地，隐私优先）
适合涉密、内网、不想走第三方 API 场景，搭配 Ollama/LocalAI 本地大模型运行：
1. OpenClaw（龙虾）
现象级本地自主 Agent 引擎，支持联网、终端操作、多任务循环，全开源自托管
2. Agentix
单 HTML 文件运行，纯浏览器本地执行，对接 Ollama 离线模型，零服务端依赖GitHub
3. Nuwax（国产开源）
面向企业内网本地 Agent 服务，图形化编排、沙箱隔离、岗位化智能体设计
4. LocalAGI
基于 LocalAI 本地推理引擎，微服务一键 Docker 部署，记忆、工具、任务规划全离线
5. Stick.ai
TypeScript 本地优先框架，多 Agent 编排、完整可观测监控、自定义插件
## 五、专用垂直 Agent 工具（细分场景专用）
1. 代码自主 Agent
OpenHands (OpenDevin)：开源 Devin，可操作终端、编辑器、自主写代码调试部署
2. 对话 / 客服 Agent
Botpress、Rasa：传统企业级对话智能体，多轮对话管理、私有化合规部署
3. 自主通用 AGI 原型
AutoGPT、BabyAGI：初代自主循环 Agent，开放式目标自动拆解（偏实验研究）
4. MCP 协议工具集（2026 Agent 基础设施）
Model Context Protocol，让 Agent 操控浏览器、Figma、Office、数据库，是所有框架通用工具标准
# 快速选型建议
1. 自研工程、复杂流程、私有化部署：LangGraph + Dify
2. 多角色分工、内容 / 调研团队智能体：CrewAI
3. 国内快速上线、无代码、对接微信 / 飞书：Coze 扣子
4. 内网离线、数据完全本地：OpenClaw / Nuwax + Ollama
5. .NET/ 微软企业生态：Semantic Kernel + AutoGen
6. 文档问答、知识库 RAG 智能体：LlamaIndex + Dify
7. 跨系统自动化、ERP / 表单 / 爬虫联动：n8n
Agent几大技能组合
Memory（记忆）：维持多轮交互的状态和用户偏好。
RAG（知识）：提供执行任务所需的垂直领域信息。
MCP（工具）：赋予系统改变外部状态的操作能力。
Skills（流程）：提供特定场景下的执行框架。
创建的编程智体
# 角色
你是一位经验丰富的资深程序员，熟练掌握多种开发语言和框架，如 Go、C#、VC、Python、Java、Flutter 等。
## 技能
- 能够使用各种编程语言进行开发工作，包括但不限于 Go、C#、VC、Python、Java、Flutter 等。
- 具备丰富的软件开发经验，能够独立完成项目的开发和维护工作。
- 能够根据项目需求选择合适的技术栈和开发框架，提高开发效率和代码质量。
- 能够进行代码优化和性能调优，提高软件的运行效率和稳定性。
- 能够进行技术选型和架构设计，保证项目的可扩展性和可维护性。
- 能够进行团队协作和沟通，提高项目的开发效率和质量。
## 限制
- 只讨论与开发相关的内容，拒绝回答与开发无关的话题。
- 所输出的内容必须按照给定的格式进行组织，不能偏离框架要求。
创建的教师智体
# 角色
你是一个专业且经验丰富的教学机器人，能够熟练解答高中阶段各科目的问题，以通俗易懂的方式为学生阐释知识要点，给予学生高效的学习指导与切实的帮助。
## 技能
### 技能 1: 解答高中科目问题
1. 当学生提出高中某科目问题时，准确且详细地进行解答。
2. 对于复杂问题，分步骤进行讲解。回复示例：
=====
- **科目**：<具体科目>
- **问题**：<学生提出的问题>
- **解答**：<详细的解答过程>
=====
### 技能 2: 提供学习指导
1. 根据学生的具体情况，为其提供个性化的学习方法与策略。
2. 结合学科特点，给予针对性的学习建议。回复示例：
=====
- **科目**：<具体科目>
- **针对学生**：<学生的具体情况描述>
- **学习指导**：<具体的指导内容>
=====
## 限制:
- 只专注于高中阶段各科目的教学相关内容，拒绝回答与高中学习无关的话题。
- 所输出的内容必须按照给定的格式进行组织，不能偏离框架要求。
- 解答过程需详细准确。
掌握 browser-use：基于 DeepSeek 的浏览器自动化实战
一、项目定位与技术价值
1.1 智能体开发新范式
Browser-Use 作为开源 AI 自动化工具，通过集成 DeepSeek 等大模型与 Playwright 浏览器引擎，实现自然语言驱动的浏览器操作。其技术价值体现在：
低代码开发：仅需自然语言指令即可生成自动化脚本
多模态交互：融合 DOM 解析（精度99%）+视觉识别
企业级扩展：支持私有化部署与多智能体协同
1.2 与 DeepSeek 的深度整合
Browser-Use 对 DeepSeek 的适配优势：
模型微调支持：可针对电商、金融等场景优化提示词
API 调用优化：支持流式响应与长文本处理
成本控制：DeepSeek 推理成本仅为 GPT-4 的 1/5
二、核心架构解析
2.1 模块化设计
模块 核心功能 DeepSeek 整合点
Agent 任务规划与状态管理 调用 deepseek-chat 生成操作链
Controller 动作注册与执行 解析模型输出的 JSON 指令
Browser 浏览器实例控制 结合视觉模型处理验证码
DOM 元素定位与信息提取 生成 XPath 供模型决策
2.2 执行流程时序
1. 初始化阶段：
加载 DeepSeek API 密钥
启动带 Cookie 的 Chrome 实例
2. 决策阶段：
# 模型输出示例
{
"action": "click_element",
"params": {"xpath": "//button[@id='submit-order']"}
}
3. 执行阶段：
Playwright 执行点击/输入等操作
失败时自动重试（最大重试次数3次）
三、环境配置指南
3.1 基础安装
# 创建 Python 3.11 虚拟环境
conda create -n browser_use python=3.11
conda activate browser_use
# 安装核心依赖
pip install browser-use playwright -i https://pypi.tuna.tsinghua.edu.cn/simple
playwright install chromium # 安装 Chromium 浏览器
3.2 DeepSeek 配置
1. 获取 API Key：
登录 DeepSeek 控制台
2. 配置环境变量：
echo "DEEPSEEK_API_KEY=sk-your-key-here" >> .env
四、实战案例：电商自动下单
4.1 场景设计
完成淘宝购物全流程：
登录账号（使用本地保存的 Cookie）
搜索「机械键盘」并筛选「销量排序」
选择第一个商品加入购物车
提交订单并填写收货地址
4.2 代码实现
from langchain_openai import ChatOpenAI
from browser_use import Agent, BrowserConfig, Browser
import asyncio
import os
# 配置本地 Chrome 路径（需提前登录淘宝）
config = BrowserConfig(
chrome_instance_path="C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
headless=False # 显示浏览器界面（网页10）
)
async def taobao_order():
browser = Browser(config=config)
llm = ChatOpenAI(
base_url="https://api.deepseek.com/v1",
model="deepseek-chat",
api_key=os.getenv("DEEPSEEK_API_KEY")
)
agent = Agent(
browser=browser,
task='''
1. 打开 taobao.com 并等待登录完成
2. 搜索"机械键盘"，按销量排序
3. 选择第一个商品进入详情页
4. 点击"加入购物车"
5. 进入购物车提交订单
6. 选择默认地址并支付
''',
llm=llm,
max_steps=20 # 最大执行步骤（网页6）
)
await agent.run()
await browser.close()
asyncio.run(taobao_order())
4.3 关键技术点
登录态保持：利用已登录的 Chrome 实例绕过验证
元素定位策略：
# DeepSeek 生成的 XPath
"//div[contains(text(),'销量')]/ancestor::button"
异常处理：
商品缺货时自动选择下一商品
支付失败时截图保存
五、进阶应用：数据采集与RAG
5.1 竞品价格监控系统
task = '''
1. 打开 jd.com 搜索"无线鼠标"
2. 采集前10个商品的：
- 名称
- 价格
- 评论数
3. 保存为 CSV 文件
'''
# 输出数据结构化
class Product(BaseModel):
name: str
price: float
reviews: int
controller = Controller(output_model=List[Product])
5.2 技术增强点
动态页面处理：
await page.wait_for_selector("//div[@class='price']", timeout=5000)
反爬对抗：
随机滑动速度模拟
IP 轮换机制（需配合代理池）
六、常见问题排查
问题现象 解决方案
DeepSeek 返回内容为空 检查 .env 文件密钥格式
浏览器无法启动 确认 Chrome 路径与版本匹配
元素定位失败 启用 use_vision=True 增强识别
执行速度过慢 设置 headless=True 启用无头模式
下一个AI风口：这四款 Agent 已开源
1. AgenticSeek - 完全本地的AI任务执行中枢
GitHub: Fosowl/agenticSeek
隐私优先：所有数据处理均在本地完成，彻底规避云端AI的隐私风险，适合医疗、金融等敏感场景。
多模态执行：支持代码生成（Python/Go）、网页自主搜索、复杂任务拆解（如"规划三日旅游行程并预订酒店"）。
Manus AI替代方案：提供类似云端AI助手的体验，但完全离线运行。
技术亮点：▸ 内置RAG引擎，本地知识库实时更新▸ 任务分解树可视化，调试复杂逻辑更直观
2. PySpur - 拖拽式AI工作流工厂
GitHub: PySpur-Dev/pyspur
LEGO式搭建：通过拖拽100+预制模块（LLM调用/向量检索/多模态处理），15分钟构建定制化AI流水线。
全栈支持：无缝对接HuggingFace/OpenAI等模型，兼容Pinecone/Milvus等主流向量数据库。
实时热调试：工作流运行时修改节点参数，结果即时刷新，加速实验迭代。
3. AgentGPT - 云端AI代理调度器
GitHub: reworkd/AgentGPT
任务自动化引擎：输入"开发一个贪吃蛇游戏"，自动分解为代码编写→测试→优化子任务。
互联网级操作：直接调用搜索引擎/API获取实时数据（如股价查询、竞品分析）。
人类监督模式：关键节点暂停等待确认，平衡自动化与可控性。
4. Activepieces - 企业级自动化乐高
GitHub: activepieces/activepieces
300+即插即用组件：从Slack消息推送到Stripe支付处理，开箱即用。
混合部署：支持SaaS模式或Docker全本地化部署，满足不同合规要求。
AI增强：内置LLM模块，可组合传统自动化与AI能力（如邮件自动分类+智能回复）
关于AI工具
Github开源文本转语音神器Spark-TTS开源了，克隆声音仅需3秒？
github开源B站UP主都在用的下载神器！Cobalt让你轻松搬运高清素材！
Github 开源无代码的 Web 数据提取平台，2分钟内训练机器人自动抓取网页数据
Cherry Studio 新版本 1.2.9 一键式添加MCP服务器
Cherry Studio MCP 使用入门教程：从配置到使用
客户端将MCP工具列表和用户问题-》大语言模型-》需要调用MCP的信息返回给调用模型的客户端，客户端调用指定MCP->客户端获得MCP结果-》大语言模型-》返回给最终客户
最强AI Agent开发平台，Coze Studio本地部署整合包
————整合包下载地址 (解压即用，良心分享，完全免费😊😊)————
国内：https://pan.quark.cn/s/1eb30690774b
国外：可加入Telegram，在群文件中查找下载。https://t.me/%20hjgDJ5bwUzc4Yjdl
MCP与Skills介绍
Q:Skills和MCP区别
A:...
Q:skills是如何使用的
A:...
Q:给一个完整可使用的skills例子
A:...
Q:写一个第三方软件可调用skills例子比如豆包能用的完整例子
A:...
Q:Skills看来不是标准啊
A:...
Q:modelscope社区知道吗？
A:...
Q:他的Skills中心我看到一个summarize skills，但下载文件的skills文件里只有一个md说明文件，没有执行文件，他如何执行他的例子，如：summarize "https://example.com" --model google/gemini-3-flash-preview
A:...
ModelScope Skills 中心里的技能（比如 summarize），本身不带可执行文件，只给说明文档（skill.md）。
它不是 “下载即用的程序”，而是给 AI Agent 用的 “执行说明书 + 接口定义”，需要配合 ms-agent 框架 才能跑起来。
下面我把完整执行流程、环境、代码、命令行用法一次性讲清楚，让你能直接跑通 summarize "https://example.com" --model google/gemini-3-flash-preview。
一、先搞懂：ModelScope Skills 是什么
不是可执行程序，而是一个技能定义包
核心文件：skill.md（含：元数据、参数、示例、执行逻辑）
执行依赖：ms-agent 框架（ModelScope 官方 Agent 运行时）
运行方式：
用 ms-agent 加载 Skills 目录
由 LLM 解析 skill.md 并决定是否调用
框架自动执行对应的逻辑（调用 API / 模型 / 脚本）
二、环境准备（必须）
1. 安装 ms-agent
bash
运行
pip install ms-agent modelscope
2. 获取 ModelScope Access Token
登录 ModelScope → 右上角头像 → Access Token
保存到环境变量：
bash
运行
export MS_ACCESS_TOKEN="你的token"
3. 下载 summarize Skill
bash
运行
# 克隆官方 Skills 仓库（含 summarize）
git clone https://www.modelscope.cn/studios/modelscope-agent/skills.git
cd skills
你会看到：
plaintext
skills/
├── summarize/
│ └── skill.md # 只有说明，没有 .py/.sh
└── ...
三、两种执行方式（都能跑通你的示例）
方式一：命令行（最接近你给的示例）
1. 用 ms-agent 命令行运行
bash
运行
ms-agent run \
--skills ./summarize \
--model google/gemini-3-flash-preview \
--query "summarize https://example.com"
2. 等效简写（更贴近你给的命令）
bash
运行
ms-agent run \
--skills ./summarize \
--model google/gemini-3-flash-preview \
"summarize https://example.com"
方式二：Python 代码（更灵活、可嵌入）
python
运行
import os
from ms_agent import create_agent_skill
# 1. 配置
os.environ["MS_ACCESS_TOKEN"] = "你的token"
skills_dir = "./summarize" # 技能目录
model = "google/gemini-3-flash-preview"
# 2. 创建 Agent
agent = create_agent_skill(
skills=skills_dir,
model=model,
api_key=os.getenv("MS_ACCESS_TOKEN"),
base_url="https://api-inference.modelscope.cn/v1/",
)
# 3. 执行：summarize https://example.com
response = agent.run(query="summarize https://example.com")
print("摘要结果：", response)
四、背后原理（为什么只有 skill.md 也能跑）
skill.md 里包含了 AI 执行所需的全部信息，ms-agent 会自动解析：
1. 元数据（YAML 头部）
yaml
---
name: summarize
description: 对网页/文本进行摘要
parameters:
type: object
properties:
url:
type: string
description: 网页 URL
model:
type: string
description: 模型 ID，如 google/gemini-3-flash-preview
required: [url]
---
2. 执行逻辑（Markdown 正文）
markdown
## 执行步骤
1. 读取输入参数：url、model
2. 调用 ModelScope API 抓取网页内容
3. 调用指定模型（如 gemini-3-flash-preview）做摘要
4. 返回结构化结果
3. 示例（你看到的命令）
plaintext
summarize "https://example.com" --model google/gemini-3-flash-preview
ms-agent 会自动：
解析 skill.md 得到参数 schema
解析用户命令，映射到参数
调用 ModelScope 模型 API 执行
返回结果
五、常见问题
Q1：为什么下载后只有 skill.md，没有代码？
ModelScope Skills 是 声明式技能，不是命令式脚本
执行逻辑由 ms-agent 框架 + LLM 共同完成
框架内置了网页抓取、模型调用等通用能力
Q2：必须用 ms-agent 吗？
是的。ModelScope Skills 基于 ms-agent 协议（兼容 Anthropic Agent Skills）
其他框架（如 LangChain）需要自己适配解析 skill.md
Q3：可以自定义执行逻辑吗？
可以。在 skill.md 里写更详细的执行步骤
或在 ms-agent 中注册自定义函数，覆盖默认逻辑
六、完整可运行示例（复制即跑）
1. 目录结构
plaintext
your_project/
├── skills/
│ └── summarize/
│ └── skill.md # 从 ModelScope 下载
└── run_summarize.py # 下面的代码
2. run_summarize.py
python
运行
import os
from ms_agent import create_agent_skill
# 配置
os.environ["MS_ACCESS_TOKEN"] = "你的 ModelScope Token"
skills_dir = "./skills/summarize"
model = "google/gemini-3-flash-preview"
# 创建并运行 Agent
agent = create_agent_skill(
skills=skills_dir,
model=model,
api_key=os.getenv("MS_ACCESS_TOKEN"),
base_url="https://api-inference.modelscope.cn/v1/",
)
# 执行
result = agent.run(query="summarize https://example.com")
print("="*50)
print("摘要结果：")
print(result)
print("="*50)
3. 运行
bash
运行
python run_summarize.py
七、总结
ModelScope Skills = 声明式技能定义（skill.md）+ 执行框架（ms-agent）
没有可执行文件，靠框架解析并执行
你的示例命令 summarize "https://example.com" --model google/gemini-3-flash-preview，用 ms-agent run 即可直接运行
Q:Agent的技能skills 有统一规范吗？
A:...
目前没有官方 ISO/IEC 标准，但自 2026 年初起形成了事实上的开放标准（de facto standard），主流平台（Anthropic、OpenAI、Google DeepMind、Cursor、Claude Code 等）已广泛趋同并兼容。
一、核心事实
非官方标准化组织发布：由 Anthropic（Claude）率先提出，后被 OpenAI、Google 等跟进，形成行业共识而非强制国标。
统一核心格式：SKILL.md + 目录结构
必须：SKILL.md（YAML 头 + 流程指令）
可选：scripts/（脚本）、references/（参考文档）、assets/（资源）、examples/（示例）。
主流平台兼容：Claude Code、GPT-4o、Gemini、Cursor、VS Code Agent、OpenClaw 等均支持该格式，跨平台迁移成本低。
二、SKILL.md 规范（事实标准）
1. YAML 元数据（必填，约 30–100 token）
yaml
name: pdf-fill-form
version: 1.0.0
description: 提取PDF文本并填充表单
author: your-name
license: MIT
tags: [pdf, form, automation]
2. 正文指令（Markdown，触发时加载）
目标（Goal）、用途（Purpose）、执行逻辑（Logic）、约束（Constraints）、输入输出（Input/Output）。
三、目录结构规范（事实标准）
plaintext
my-skill/
├── SKILL.md # 必需：定义与指令
├── README.md # 可选：人类说明
├── scripts/ # 可选：Python/Shell等
├── references/ # 可选：API/文档
├── assets/ # 可选：模板/配置
└── examples/ # 可选：使用示例
四、与 MCP 的区别
Skills（SKILL.md）：侧重能力定义与流程，可移植、轻量、按需加载，适合 Agent 决策调用。
MCP（Model Control Protocol）：侧重模型通信协议，底层交互，不直接定义技能内容。
五、现状与趋势
2026 年 5 月：已有30 + 产品支持，形成跨平台开放标准，官网：agentskills.io。
未完全统一：部分平台有私有目录（如.claude/、.cursor/），但核心SKILL.md兼容。
标准化推进：社区在完善规范，未来可能提交官方标准化组织。
六、总结
Agent Skills无官方强制标准，但有行业统一事实规范：以SKILL.md为核心、固定目录结构，主流平台广泛兼容，可直接用于生产环境。
例子：
说明：本示例严格遵循Agent Skills行业事实标准，包含所有必写/可选文件，所有代码可直接复制运行，参数可灵活替换，适配Claude Code、GPT-4o、Gemini等主流Agent平台，无需修改目录结构和核心格式。
一、完整目录结构（固定规范）
pdf-text-extract/ # 技能根目录（命名规范：全小写+下划线）
├── SKILL.md # 技能核心配置+执行逻辑【必写】
├── config.json # 入参/出参/权限配置【必写】
├── examples/ # 调用示例（可选，便于测试和参考）
│ └── call-example.json # 多场景调用示例（成功/失败）
├── tools/ # 依赖工具/核心脚本（可选，实现技能功能）
│ └── pdf_extract.py # PDF提取核心Python脚本
└── docs/ # 补充说明（可选，便于使用和维护）
└── usage.md # 技能使用文档、依赖说明、常见问题
二、所有文件完整内容（可直接复制部署）
1. 必写文件：SKILL.md（技能核心定义，Agent识别核心）
---
# 技能元数据（YAML头部，所有Agent通用解析，必填项不缺失）
skill_id: skill_pdf_extract_001 # 唯一标识，格式：skill_技能名_序号
name: PDF文本提取与关键词提取 # 中文技能名，简洁明了
name_en: PDFTextExtractAndKeyword # 英文技能名，适配多语言Agent
version: 1.0.0 # 版本规范：主版本.次版本.迭代号
author: AgentDev # 开发者/团队名称
create_time: 2026-05-21 # 创建时间（格式：YYYY-MM-DD）
update_time: 2026-05-21 # 更新时间（与创建时间一致，后续迭代更新）
category: 办公/文档处理 # 技能分类，贴合实际使用场景
tags: [pdf, 文本提取, 关键词提取, 文档处理, 自动化] # 标签，便于Agent检索
scope: 全局可用 # 可用范围：全局/限定场景
permission: public # 权限：公开/私有/管理员可见
status: online # 状态：在线/离线/测试中
---
# 技能功能说明（Agent执行的核心依据，统一结构）
## 1. 核心能力
提取PDF文件中所有可复制文本，自动识别并提取文本中的核心关键词（按出现频率降序排列，取前10个），解决PDF文本无法直接编辑、关键词手动筛选繁琐的问题，支持全页提取和单页提取，适配大多数办公场景的PDF处理需求。
## 2. 适用场景
- 场景1：办公场景中，提取PDF简历、工作报告、合同、会议纪要中的文本内容，用于二次编辑
- 场景2：快速筛选PDF文档核心关键词，用于文档分类、摘要生成、重点提炼
- 场景3：批量处理PDF文件（需Agent配合批量调用），提取文本后导出为Word、TXT等格式
- 触发关键词：PDF提取、提取PDF文本、PDF关键词、PDF内容提取、PDF文本导出
## 3. 输入参数规范（严格定义，Agent传参依据）
- 必填参数1：file_path | string | PDF文件的绝对路径（示例：D:/docs/test.pdf、/Users/test/Documents/report.pdf）
- 必填参数2：extract_type | string | 提取类型（仅支持两个值：all=全页提取，page=单页提取）
- 选填参数：page_num | int | 单页提取时的页码（默认值：1，仅当extract_type=page时生效，必须为正整数）
## 4. 输出返回规范（统一格式，Agent解析依据）
统一返回JSON格式，无多余内容，核心字段固定，具体如下：
{
"status": "success/fail", // 执行状态：成功/失败
"text_content": "提取的文本内容", // 提取的PDF文本（全页提取则拼接所有页面，空文本返回空字符串）
"keywords": ["关键词1", "关键词2", ...] // 核心关键词（按频率降序，最多10个，无关键词返回空数组）
}
补充：失败时，额外增加message字段，返回具体失败原因（遵循异常处理标准）。
## 5. 执行流程（Agent执行逻辑，固定顺序，不可乱序）
1. 校验用户输入合法性：检查file_path是否存在、extract_type是否为指定值、page_num是否为正整数（若有）
2. 匹配内置规则：根据extract_type判断提取模式（全页/单页），确定执行逻辑
3. 调用底层能力：执行tools目录下的pdf_extract.py脚本，传入所有输入参数，执行文本提取
4. 数据格式化处理：对提取的文本进行清洗（去除空白字符、多余换行），对关键词进行频率统计和排序
5. 结果标准化输出：按上述JSON格式整理结果，确保字段完整、格式正确
6. 异常捕获与友好提示：捕获所有可能的异常（文件不存在、PDF加密、页码异常等），返回对应失败提示
## 6. 约束规则（全局统一，不可违规）
1. 不越权执行危险操作：不读取系统敏感目录（如C:/Windows、/root等）下的PDF文件，不修改原PDF文件内容
2. 输出格式严格对齐约定：仅返回指定JSON格式，不添加任何无关文本、注释
3. 无结果时统一固定话术：若PDF无可提取文本（如图片型PDF），返回{"status":"success","text_content":"","keywords":[]}
4. 兼容多模型Agent调用：适配主流Agent平台，不使用平台私有语法，确保跨平台迁移无成本
## 7. 异常处理标准（统一提示，Agent友好）
- 参数缺失：返回{"status":"fail","message":"缺少必要参数，请补充file_path和extract_type参数"}
- 文件不存在：返回{"status":"fail","message":"技能执行异常，PDF文件路径不存在，请检查路径是否正确"}
- PDF加密：返回{"status":"fail","message":"技能执行异常，该PDF文件已加密，无法提取文本"}
- 页码异常：返回{"status":"fail","message":"技能执行异常，指定页码超出PDF总页数，请调整页码"}
- 未知错误：返回{"status":"fail","message":"技能执行异常，未知错误，请重试"}
- 权限不足：返回{"status":"fail","message":"暂无该技能调用权限，请联系管理员开通"}
2. 必写文件：config.json（参数配置，Agent传参校验依据）
{
"skillName": "PDF文本提取与关键词提取",
"skillDesc": "提取PDF文件中的可复制文本，并自动提取核心关键词（按出现频率降序排列），支持全页/单页提取，适用于办公文档处理场景，可直接被主流Agent平台调用",
"triggerWords": ["PDF提取", "提取PDF文本", "PDF关键词", "PDF内容提取", "PDF文本导出"],
"inputSchema": {
"type": "object",
"required": ["file_path", "extract_type"],
"properties": {
"file_path": {
"type": "string",
"description": "PDF文件的绝对路径，需包含完整路径和文件名（如D:/docs/test.pdf）",
"example": "D:/work/2026年度工作报告.pdf"
},
"extract_type": {
"type": "string",
"description": "提取类型，仅支持all（全页提取）和page（单页提取）两个值，不可传入其他值",
"enum": ["all", "page"]
},
"page_num": {
"type": "integer",
"description": "单页提取时的页码，仅当extract_type=page时生效，必须为正整数",
"default": 1,
"minimum": 1
}
}
},
"outputSchema": {
"formatType": "json",
"maxLength": 10000,
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": ["success", "fail"],
"description": "技能执行状态，成功为success，失败为fail"
},
"text_content": {
"type": "string",
"description": "提取的PDF文本内容，全页提取则拼接所有页面文本，无文本则返回空字符串"
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "按出现频率降序排列的核心关键词，最多返回10个，无关键词则返回空数组"
},
"message": {
"type": "string",
"description": "仅失败时存在，返回具体的失败原因"
}
}
}
},
"timeout": 30,
"maxRetry": 2,
"dependSkills": [],
"disableRule": [
"不允许提取加密PDF文件",
"不允许读取系统敏感目录（如C:/Windows、/root等）下的文件",
"不允许批量提取超过10个PDF文件（避免资源占用过高）",
"不允许修改原PDF文件的内容和属性"
]
}
3. 可选文件：examples/call-example.json（调用示例，便于测试）
{
"示例1：全页提取（成功场景）": {
"input": {
"file_path": "D:/work/2026年度工作报告.pdf",
"extract_type": "all"
},
"output": {
"status": "success",
"text_content": "2026年度工作报告\n一、工作概述\n本年度，公司围绕核心业务目标，稳步推进各项工作，实现营收同比增长15%，完成年度目标的108%。核心业务板块中，产品迭代、市场拓展、客户服务三大板块表现突出，为公司营收增长提供了有力支撑。\n二、核心工作成果\n1. 产品迭代：完成3个核心产品的版本更新，优化功能20余项，用户满意度提升20%，活跃用户数量同比增长25%...（此处省略完整文本）",
"keywords": ["工作报告", "营收", "核心业务", "产品迭代", "市场拓展", "客户服务", "用户满意度", "活跃用户"]
}
},
"示例2：单页提取（成功场景）": {
"input": {
"file_path": "D:/work/2026年度工作报告.pdf",
"extract_type": "page",
"page_num": 3
},
"output": {
"status": "success",
"text_content": "二、核心工作成果\n1. 产品迭代：完成3个核心产品的版本更新，优化功能20余项，用户满意度提升20%，活跃用户数量同比增长25%。2. 市场拓展：新增3个区域市场，与5家大型企业达成合作，市场份额提升8%。3. 客户服务：优化服务流程，响应时间缩短30%，客户投诉率下降15%...（此处省略单页完整文本）",
"keywords": ["产品迭代", "市场拓展", "客户服务", "用户满意度", "市场份额", "服务流程"]
}
},
"示例3：参数缺失（失败场景）": {
"input": {
"file_path": "D:/work/2026年度工作报告.pdf"
},
"output": {
"status": "fail",
"message": "缺少必要参数，请补充file_path和extract_type参数"
}
},
"示例4：文件不存在（失败场景）": {
"input": {
"file_path": "D:/work/不存在的文件.pdf",
"extract_type": "all"
},
"output": {
"status": "fail",
"message": "技能执行异常，PDF文件路径不存在，请检查路径是否正确"
}
},
"示例5：PDF加密（失败场景）": {
"input": {
"file_path": "D:/work/加密PDF文件.pdf",
"extract_type": "all"
},
"output": {
"status": "fail",
"message": "技能执行异常，该PDF文件已加密，无法提取文本"
}
},
"示例6：页码异常（失败场景）": {
"input": {
"file_path": "D:/work/2026年度工作报告.pdf",
"extract_type": "page",
"page_num": 20
},
"output": {
"status": "fail",
"message": "技能执行异常，指定页码超出PDF总页数（总页数：10），请调整页码"
}
}
}
4. 可选文件：tools/pdf_extract.py（核心脚本，实现技能功能）
import PyPDF2
import os
from collections import Counter
import re
def extract_pdf_text(file_path, extract_type="all", page_num=1):
"""
PDF文本提取与关键词提取核心函数（Agent调用的核心逻辑）
:param file_path: PDF文件绝对路径（必填）
:param extract_type: 提取类型（all：全页，page：单页，必填）
:param page_num: 单页提取时的页码（默认1，选填）
:return: dict，符合SKILL.md约定的输出格式
"""
# 初始化返回结果，严格贴合输出规范
result = {
"status": "success",
"text_content": "",
"keywords": []
}
# 1. 校验文件路径合法性
if not os.path.exists(file_path):
result["status"] = "fail"
result["message"] = "技能执行异常，PDF文件路径不存在，请检查路径是否正确"
return result
# 2. 打开PDF文件，执行提取逻辑
try:
with open(file_path, 'rb') as f:
pdf_reader = PyPDF2.PdfReader(f)
total_pages = len(pdf_reader.pages) # 获取PDF总页数
# 校验页码（仅单页提取时生效）
if extract_type == "page" and (page_num < 1 or page_num > total_pages):
result["status"] = "fail"
result["message"] = f"技能执行异常，指定页码超出PDF总页数（总页数：{total_pages}），请调整页码"
return result
# 提取文本（区分全页/单页）
text_content = ""
if extract_type == "all":
# 全页提取：遍历所有页面，拼接文本
for page in pdf_reader.pages:
page_text = page.extract_text() or "" # 处理无文本的页面
text_content += page_text + "\n"
else: # extract_type == "page"
# 单页提取：获取指定页码的页面（注意：PDF页码从0开始，需减1）
target_page = pdf_reader.pages[page_num - 1]
text_content = target_page.extract_text() or ""
# 文本清洗：去除多余空白字符、换行符，统一格式
text_content = re.sub(r'\s+', ' ', text_content).strip()
result["text_content"] = text_content
# 3. 提取关键词（仅当有文本时执行）
if text_content:
# 定义常见停用词（可根据实际需求扩展）
stop_words = ["的", "了", "是", "在", "和", "与", "及", "一个", "一种", "我们", "你们", "他们",
"这", "那", "因为", "所以", "如果", "虽然", "但是", "而且", "或者", "关于", "对于",
"主要", "重要", "相关", "通过", "实现", "完成", "达到", "提升", "降低", "增长"]
# 提取中文关键词（过滤非中文字符，仅保留2个及以上汉字的词）
chinese_words = re.findall(r'[\u4e00-\u9fa5]{2,}', text_content)
# 过滤停用词，得到有效关键词
valid_words = [word for word in chinese_words if word not in stop_words]
# 按出现频率降序排列，取前10个
if valid_words:
keyword_counter = Counter(valid_words)
result["keywords"] = [word for word, _ in keyword_counter.most_common(10)]
# 捕获PDF加密异常
except PyPDF2.errors.PdfReadError:
result["status"] = "fail"
result["message"] = "技能执行异常，该PDF文件已加密，无法提取文本"
# 捕获其他未知异常
except Exception as e:
result["status"] = "fail"
result["message"] = f"技能执行异常，未知错误：{str(e)}"
return result
# 说明：main函数仅用于【本地测试】，并非接收Agent调用的入口
# Agent调用时，会直接调用extract_pdf_text核心函数，并传入配置好的参数（对应SKILL.md的输入规范）
# 以下补充Agent调用适配逻辑，确保脚本可直接被Agent调用，同时保留本地测试功能
if __name__ == "__main__":
# 本地测试代码（运行脚本即可直接测试，无需Agent调用）
# 测试1：全页提取（替换为自己的PDF路径）
test_all = extract_pdf_text(file_path="D:/work/2026年度工作报告.pdf", extract_type="all")
print("=== 全页提取测试结果 ===")
print(test_all)
# 测试2：单页提取（替换为自己的PDF路径和有效页码）
test_page = extract_pdf_text(file_path="D:/work/2026年度工作报告.pdf", extract_type="page", page_num=3)
print("\n=== 单页提取测试结果 ===")
print(test_page)
# 测试3：文件不存在（测试失败场景）
test_fail = extract_pdf_text(file_path="D:/work/不存在的文件.pdf", extract_type="all")
print("\n=== 文件不存在测试结果 ===")
print(test_fail)
# Agent调用适配入口（新增，确保Agent可正常传入参数调用）
def agent_call_handler(params):
"""
Agent调用入口函数，接收Agent传入的参数（JSON格式解析后的字典）
:param params: Agent传入的参数字典，对应SKILL.md的输入参数规范
:return: dict，符合SKILL.md约定的输出格式
"""
# 提取Agent传入的参数，适配可选参数默认值
file_path = params.get("file_path")
extract_type = params.get("extract_type")
page_num = params.get("page_num", 1) # 可选参数，默认值1
# 调用核心函数，返回结果（直接对接Agent输出规范）
return extract_pdf_text(file_path, extract_type, page_num)
5. 可选文件：docs/usage.md（使用文档，便于维护和使用）
# PDF文本提取与关键词提取技能使用说明
## 一、技能概述
本技能是基于Agent Skills行业标准开发的办公类技能，用于提取PDF文件中的可复制文本，并自动识别核心关键词（按出现频率排序），支持全页提取和单页提取，可直接被主流Agent平台调用，也可本地运行测试，适用于各类PDF文档处理场景。
## 二、环境依赖（本地运行/Agent部署需满足）
1. 运行环境：Python 3.8及以上版本（兼容3.8-3.11）
2. 依赖库：PyPDF2（用于PDF文件解析和文本提取）
3. 安装命令：pip install PyPDF2 （执行该命令即可安装依赖）
4. 系统兼容：Windows、MacOS、Linux均可运行，无系统限制
## 三、调用方式（两种方式，灵活使用）
### 1. Agent平台调用（推荐，符合技能设计初衷）
- 触发方式：
1. 输入触发关键词（如“PDF提取”“提取PDF文本”），Agent自动识别并调用本技能
2. 直接调用技能ID：skill_pdf_extract_001，精准触发
- 传参要求：严格按照config.json中的inputSchema规范，传入JSON格式参数，不可遗漏必填参数
- 返回结果：JSON格式，字段含义参考SKILL.md中的输出返回规范，失败时会返回具体原因
### 2. 本地脚本调用（用于测试和调试）
1. 复制tools/pdf_extract.py文件到本地
2. 安装依赖库：pip install PyPDF2
3. 修改脚本中main函数的测试参数（替换file_path为自己的PDF路径）
4. 运行脚本，即可看到测试结果（控制台输出）
## 四、使用注意事项（必看）
1. 仅支持**可复制文本**的PDF文件，图片型PDF（无法选中复制文本）会返回空文本，加密PDF会返回加密提示
2. 传入的file_path必须是**绝对路径**，相对路径会导致文件无法找到，路径中不可包含中文空格、特殊符号（如@、#、$等）
3. 单页提取时，page_num必须是正整数，且不超过PDF总页数，否则会返回页码异常提示
4. 关键词提取仅识别**中文关键词**（2个及以上汉字），过滤常见停用词，可在pdf_extract.py中扩展停用词列表
5. 文本提取最大长度为10000字符，超出部分会自动截断（遵循config.json中的限制）
6. 不支持批量提取多个PDF文件（需Agent配合循环调用），单次仅可提取1个PDF文件
## 五、常见问题（FAQ）
Q1：运行脚本时提示“ModuleNotFoundError: No module named 'PyPDF2'”怎么办？
A1：未安装依赖库，执行命令“pip install PyPDF2”即可解决。
Q2：提示“PDF文件路径不存在”，但路径是正确的，怎么办？
A2：检查路径是否为绝对路径，路径中是否包含中文空格或特殊符号，替换为无特殊符号的绝对路径即可。
Q3：提取的文本为空，怎么办？
A3：确认PDF文件是否为可复制文本（图片型PDF无法提取），或PDF是否加密，加密PDF需先解密后再提取。
Q4：关键词提取不准确，如何优化？
A4：打开tools/pdf_extract.py，扩展stop_words列表（添加更多无关词汇），或修改正则表达式（调整关键词提取规则）。
Q5：Agent调用时返回“权限不足”，怎么办？
A5：联系Agent管理员，开通本技能的调用权限（本技能默认权限为public，若被修改需重新设置）。
## 六、版本更新记录
- v1.0.0（2026-05-21）：初始版本，完成核心功能（全页/单页提取、关键词提取），完善异常处理和参数校验，适配主流Agent平台。
## 七、维护说明
1. 若需新增功能（如支持批量提取、支持图片型PDF识别），可修改pdf_extract.py脚本，并同步更新SKILL.md和config.json中的相关配置
2. 若需修改异常提示、关键词提取规则，需同步更新SKILL.md中的异常处理标准和执行流程
3. 版本迭代时，需更新SKILL.md中的version和update_time，保持版本一致性
三、完整技能使用步骤（可直接落地）
1. 创建文件夹：新建名为“pdf-text-extract”的文件夹（严格按此命名，符合规范）；
2. 创建子文件夹：在根目录下新建examples、tools、docs三个子文件夹（与目录结构一致）；
3. 复制文件内容：将上述5个文件（SKILL.md、config.json、call-example.json、pdf_extract.py、usage.md）分别复制到对应目录，替换file_path等示例参数为自己的实际路径；
4. 本地测试：安装PyPDF2依赖，运行tools/pdf_extract.py，查看控制台输出，确认技能可正常运行；
5. Agent部署：将整个“pdf-text-extract”文件夹上传至Agent技能目录，Agent会自动识别技能，即可通过关键词或技能ID调用。
按这样说的话Agent自动识别Skills是哪个语言开发和自动识别调用skills里哪个函数？
Agent 自动识别 Skills 的开发语言和调用函数，核心遵循 Agent Skills 行业事实标准，无需手动配置，结合当前打开的技能示例（agent-skill-complete-example），具体逻辑如下：
一、Agent 自动识别 Skills 开发语言（无需手动指定）
识别依据：Agent 通过技能根目录下「脚本文件的后缀」和「配置文件约定」，自动判断开发语言，无需额外配置。
本技能示例对应：
核心脚本为 tools/pdf_extract.py，脚本后缀为 .py，Agent 自动识别为 Python 语言；
若脚本后缀为 .js（如 pdf_extract.js），则识别为 JavaScript；后缀为 .java 则识别为 Java，以此类推（主流语言均支持）。
补充：Agent 内置对主流开发语言（Python、JavaScript、Java 等）的解析逻辑，只要脚本后缀符合语言规范，即可自动识别，无需在 SKILL.md、config.json 中标注语言类型。
二、Agent 自动识别调用函数（无需手动指定）
识别原则：优先匹配「参数格式、返回格式与 SKILL.md 输入 / 输出规范一致」的函数，与函数名无关（本技能中为 agent_call_handler）。
本技能示例对应：
Agent 先通过 SKILL.md 的「执行流程」，明确需调用 tools/pdf_extract.py 脚本；
自动扫描该脚本中，「接收参数字典、返回符合 SKILL.md 输出规范结果」的函数，即 agent_call_handler；
若脚本中有多个函数，仅匹配与配置规范一致的函数（本技能中仅 agent_call_handler 符合），无需手动指定函数名。
三、关键总结
开发语言：由 tools 目录下核心脚本的「文件后缀」自动识别（如.py→Python）；
调用函数：由脚本中「参数、返回格式与配置文件一致」的函数自动匹配，无需手动指定。
当前打开的技能示例，Agent 可自动识别为 Python 开发，且自动匹配 agent_call_handler 作为调用入口，完全符合规范。
需要我帮你在 SKILL.md 中补充标注，明确开发语言和调用函数的识别逻辑，避免后续混淆吗？
SKILL.md：
---
# 技能元数据（YAML头部，所有Agent通用解析，必填项不缺失）
skill_id: skill_pdf_extract_001 # 唯一标识，格式：skill_技能名_序号
name: PDF文本提取与关键词提取 # 中文技能名，简洁明了
name_en: PDFTextExtractAndKeyword # 英文技能名，适配多语言Agent
version: 1.0.0 # 版本规范：主版本.次版本.迭代号
author: AgentDev # 开发者/团队名称
create_time: 2026-05-21 # 创建时间（格式：YYYY-MM-DD）
update_time: 2026-05-21 # 更新时间（与创建时间一致，后续迭代更新）
category: 办公/文档处理 # 技能分类，贴合实际使用场景
tags: [pdf, 文本提取, 关键词提取, 文档处理, 自动化] # 标签，便于Agent检索
scope: 全局可用 # 可用范围：全局/限定场景
permission: public # 权限：公开/私有/管理员可见
status: online # 状态：在线/离线/测试中
---
# 技能功能说明（Agent执行的核心依据，统一结构）
## 1. 核心能力
提取PDF文件中所有可复制文本，自动识别并提取文本中的核心关键词（按出现频率降序排列，取前10个），解决PDF文本无法直接编辑、关键词手动筛选繁琐的问题，支持全页提取和单页提取，适配大多数办公场景的PDF处理需求。
## 2. 适用场景
- 场景1：办公场景中，提取PDF简历、工作报告、合同、会议纪要中的文本内容，用于二次编辑
- 场景2：快速筛选PDF文档核心关键词，用于文档分类、摘要生成、重点提炼
- 场景3：批量处理PDF文件（需Agent配合批量调用），提取文本后导出为Word、TXT等格式
- 触发关键词：PDF提取、提取PDF文本、PDF关键词、PDF内容提取、PDF文本导出
## 3. 输入参数规范（严格定义，Agent传参依据）
- 必填参数1：file_path | string | PDF文件的绝对路径（示例：D:/docs/test.pdf、/Users/test/Documents/report.pdf）
- 必填参数2：extract_type | string | 提取类型（仅支持两个值：all=全页提取，page=单页提取）
- 选填参数：page_num | int | 单页提取时的页码（默认值：1，仅当extract_type=page时生效，必须为正整数）
## 4. 输出返回规范（统一格式，Agent解析依据）
统一返回JSON格式，无多余内容，核心字段固定，具体如下：
{
"status": "success/fail", // 执行状态：成功/失败
"text_content": "提取的文本内容", // 提取的PDF文本（全页提取则拼接所有页面，空文本返回空字符串）
"keywords": ["关键词1", "关键词2", ...] // 核心关键词（按频率降序，最多10个，无关键词返回空数组）
}
补充：失败时，额外增加message字段，返回具体失败原因（遵循异常处理标准）。
## 5. 执行流程（Agent执行逻辑，固定顺序，不可乱序）
1. 校验用户输入合法性：检查file_path是否存在、extract_type是否为指定值、page_num是否为正整数（若有）
2. 匹配内置规则：根据extract_type判断提取模式（全页/单页），确定执行逻辑
3. 调用底层能力：执行tools目录下的pdf_extract.py脚本，传入所有输入参数，执行文本提取
4. 数据格式化处理：对提取的文本进行清洗（去除空白字符、多余换行），对关键词进行频率统计和排序
5. 结果标准化输出：按上述JSON格式整理结果，确保字段完整、格式正确
6. 异常捕获与友好提示：捕获所有可能的异常（文件不存在、PDF加密、页码异常等），返回对应失败提示
## 6. 约束规则（全局统一，不可违规）
1. 不越权执行危险操作：不读取系统敏感目录（如C:/Windows、/root等）下的PDF文件，不修改原PDF文件内容
2. 输出格式严格对齐约定：仅返回指定JSON格式，不添加任何无关文本、注释
3. 无结果时统一固定话术：若PDF无可提取文本（如图片型PDF），返回{"status":"success","text_content":"","keywords":[]}
4. 兼容多模型Agent调用：适配主流Agent平台，不使用平台私有语法，确保跨平台迁移无成本
## 7. 异常处理标准（统一提示，Agent友好）
- 参数缺失：返回{"status":"fail","message":"缺少必要参数，请补充file_path和extract_type参数"}
- 文件不存在：返回{"status":"fail","message":"技能执行异常，PDF文件路径不存在，请检查路径是否正确"}
- PDF加密：返回{"status":"fail","message":"技能执行异常，该PDF文件已加密，无法提取文本"}
- 页码异常：返回{"status":"fail","message":"技能执行异常，指定页码超出PDF总页数，请调整页码"}
- 未知错误：返回{"status":"fail","message":"技能执行异常，未知错误，请重试"}
- 权限不足：返回{"status":"fail","message":"暂无该技能调用权限，请联系管理员开通"}
一个标准的skill例子包含完整代码及LangChain调用
一、Skill 目录结构
按照 Agent Skills Specification，一个 Skill 至少是一个目录，里面必须包含 SKILL.md：
text
pdf_processor/
├── SKILL.md # 必需：入口文件
├── scripts/ # 可选：可执行脚本
│ ├── extract_text.py # 提取PDF文本
│ └── merge_pdfs.py # 合并PDF文件
├── references/ # 可选：参考文档
│ └── api_guide.md
└── assets/ # 可选：模板、资源文件
└── template.pdf
scripts/、references/、assets/ 都是可选的，但正是 scripts/ 让 Skill 具备了操作本地资源的能力。
二、SKILL.md 文件（核心入口）
markdown
---
name: pdf-processor
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
license: MIT
compatibility: requires Python 3.8+, PyPDF2, pdfplumber
---
# PDF 处理技能
你是一位 PDF 处理专家。当用户需要处理 PDF 文件时，请使用本技能。
## 可用工具
本技能提供以下脚本，位于 `scripts/` 目录下：
### 1. 提取 PDF 文本
- 脚本: `scripts/extract_text.py`
- 用法: `python scripts/extract_text.py <pdf_path> [--output <output_path>]`
- 功能: 提取 PDF 中的所有文本内容，可选保存为 txt 文件
### 2. 合并多个 PDF
- 脚本: `scripts/merge_pdfs.py`
- 用法: `python scripts/merge_pdfs.py <pdf1> <pdf2> ... --output <output_path>`
- 功能: 将多个 PDF 文件合并为一个
## 工作流程
1. 当用户提出 PDF 相关需求时，首先确认文件路径
2. 根据需求选择合适的脚本
3. 执行脚本并将结果反馈给用户
4. 如遇错误，检查文件路径和 Python 环境
## 常见场景示例
- **用户**: "帮我提取这个 PDF 里的文字" → 使用 `extract_text.py`
- **用户**: "把这两个 PDF 合并成一个" → 使用 `merge_pdfs.py`
## 注意事项
- 确保 Python 环境已安装依赖: `pip install PyPDF2 pdfplumber`
- 处理大文件时可能需要较长时间
关键点说明：
name 必须全小写，只能包含小写字母、数字和连字符，且必须与父目录名一致
description 需要同时描述做什么和什么时候触发
Markdown 正文包含详细的步骤指引、输入输出示例和边界情况
三、脚本实现（scripts/extract_text.py）
python
#!/usr/bin/env python3
"""
提取 PDF 文本内容的脚本
用法: python extract_text.py <pdf_path> [--output <output_path>]
"""
import argparse
import sys
from pathlib import Path
try:
import PyPDF2
except ImportError:
print("错误: 请先安装 PyPDF2: pip install PyPDF2")
sys.exit(1)
def extract_text_from_pdf(pdf_path: str) -> str:
"""从 PDF 文件中提取所有文本"""
text = []
try:
with open(pdf_path, 'rb') as file:
reader = PyPDF2.PdfReader(file)
for page_num, page in enumerate(reader.pages, 1):
page_text = page.extract_text()
if page_text:
text.append(f"--- 第 {page_num} 页 ---\n{page_text}")
return "\n\n".join(text)
except Exception as e:
return f"错误: {str(e)}"
def main():
parser = argparse.ArgumentParser(description="从 PDF 文件中提取文本")
parser.add_argument("pdf_path", help="PDF 文件路径")
parser.add_argument("--output", "-o", help="输出文件路径（可选）")
args = parser.parse_args()
# 检查文件是否存在
if not Path(args.pdf_path).exists():
print(f"错误: 文件 '{args.pdf_path}' 不存在")
sys.exit(1)
# 提取文本
result = extract_text_from_pdf(args.pdf_path)
# 输出结果
if args.output:
with open(args.output, 'w', encoding='utf-8') as f:
f.write(result)
print(f"文本已保存到: {args.output}")
else:
print(result)
if __name__ == "__main__":
main()
四、LangChain 调用 Skills
LangChain 官方文档提供了完整的 Skills 实现模式。核心思路是：创建一个 load_skill 工具，让 Agent 按需加载 Skill 的完整指令。
完整代码
python
# pip install langchain langchain-openai
import os
from pathlib import Path
from typing import Dict, Optional
from langchain.agents import create_agent
from langchain.tools import tool
from langchain_openai import ChatOpenAI
# ============================================================
# 1. Skill 存储（实际项目可从文件系统/数据库加载）
# ============================================================
class SkillStore:
"""Skill 存储与加载管理"""
def __init__(self, skills_dir: str):
self.skills_dir = Path(skills_dir)
def list_skills(self) -> Dict[str, str]:
"""列出所有可用 Skill 的名称和描述（仅元数据）"""
skills = {}
for skill_dir in self.skills_dir.iterdir():
if skill_dir.is_dir():
skill_md = skill_dir / "SKILL.md"
if skill_md.exists():
name, desc = self._parse_metadata(skill_md)
if name:
skills[name] = desc
return skills
def load_skill(self, skill_name: str) -> Optional[str]:
"""加载指定 Skill 的完整指令"""
for skill_dir in self.skills_dir.iterdir():
if skill_dir.is_dir() and skill_dir.name == skill_name:
skill_md = skill_dir / "SKILL.md"
if skill_md.exists():
return skill_md.read_text(encoding='utf-8')
return None
def _parse_metadata(self, skill_md_path: Path):
"""解析 SKILL.md 的 YAML frontmatter"""
content = skill_md_path.read_text(encoding='utf-8')
lines = content.split('\n')
if lines and lines[0].strip() == '---':
in_frontmatter = True
name = None
desc = None
for line in lines[1:]:
if line.strip() == '---':
break
if in_frontmatter and ':' in line:
key, value = line.split(':', 1)
if key.strip() == 'name':
name = value.strip()
elif key.strip() == 'description':
desc = value.strip()
return name, desc
# ============================================================
# 2. 创建 LangChain Tools
# ============================================================
def create_skill_tools(skill_store: SkillStore):
"""创建 Skill 相关的 LangChain 工具"""
@tool
def list_skills() -> str:
"""
列出所有可用的技能及其简要描述。
当用户询问你有哪些能力时，调用此工具。
"""
skills = skill_store.list_skills()
if not skills:
return "当前没有可用的技能。"
result = "可用的技能列表:\n"
for name, desc in skills.items():
result += f"- {name}: {desc}\n"
return result
@tool
def load_skill(skill_name: str) -> str:
"""
加载一个专业技能的完整指令。技能可以让你获得特定领域的专业知识。
Args:
skill_name: 技能名称（如 'pdf-processor'）
"""
content = skill_store.load_skill(skill_name)
if content is None:
available = ", ".join(skill_store.list_skills().keys())
return f"错误: 未找到名为 '{skill_name}' 的技能。可用技能: {available}"
return content
return [list_skills, load_skill]
# ============================================================
# 3. 创建 Agent
# ============================================================
def create_skill_agent(skills_dir: str):
"""创建支持 Skills 的 Agent"""
skill_store = SkillStore(skills_dir)
tools = create_skill_tools(skill_store)
# 获取所有可用技能的描述，注入 system prompt（Level 1: 元数据）
skills_meta = skill_store.list_skills()
skills_desc = "\n".join([f"- {name}: {desc}" for name, desc in skills_meta.items()])
system_prompt = f"""
你是一个乐于助人的助手，拥有可动态加载的专业技能。
可用技能:
{skills_desc}
工作流程:
1. 当用户的问题涉及某个专业领域时，首先调用 list_skills() 确认可用技能
2. 然后调用 load_skill(<技能名>) 获取完整的操作指令
3. 根据指令中的步骤和脚本，帮助用户完成任务
注意: 不要一次性加载所有技能，只加载当前任务需要的那个。
"""
model = ChatOpenAI(model="gpt-4o")
return create_agent(
model=model,
tools=tools,
system_prompt=system_prompt
)
# ============================================================
# 4. 运行示例
# ============================================================
if __name__ == "__main__":
# 假设你的 skills 目录在 ./skills 下
# 目录结构:
# ./skills/
# └── pdf-processor/
# ├── SKILL.md
# └── scripts/
# └── extract_text.py
agent = create_skill_agent("./skills")
# 测试：用户请求处理 PDF
response = agent.invoke({
"messages": [{"role": "user", "content": "帮我提取这个 PDF 文件的内容: /path/to/doc.pdf"}]
})
print(response)
实际对话流程示例：
用户: "帮我提取这个 PDF 的内容: report.pdf"
↓
Agent: 判断涉及 PDF 处理 → 调用 load_skill("pdf-processor")
↓
Agent: 读取 SKILL.md 指令，获知应执行 scripts/extract_text.py
↓
Agent: 执行 python scripts/extract_text.py report.pdf --output result.txt
↓
Agent: 读取 result.txt 内容，返回给用户
上一篇：AI人工智能的基础知识&资讯
下一篇：AI人工智能开发技术收集目录结构