网页秒变Markdown笔记:agent-plugin的web-to-markdown插件实战教程
网页秒变Markdown笔记:agent-plugin的web-to-markdown插件实战教程
agent-plugin 是 openJiuwen 社区的官方插件仓库,其中 web-to-markdown 插件可以把任意网页正文一键抓取并转换为结构清晰的 Markdown 笔记,支持保存为 .md 文件与二次编辑,是知识整理与收藏归档的轻量工具。本文将带你快速上手:从安装到实战,几分钟让网页"秒变"可编辑的 Markdown 笔记 📝
web-to-markdown 插件是什么?
web-to-markdown 由两类组件协作完成,遵循 agent-plugin 的插件包规范(详见 docs/plugin-spec.md):
| 组件 | 类型 | 职责 |
|---|---|---|
web-to-markdown |
skill(技能) | 接到"把网页转成 Markdown 笔记"类请求时,指导智能体组织输出格式 |
web_to_markdown |
tool(工具) | 按 url 抓取网页正文,用纯 Python 标准库转换为 Markdown 文本 |
一句话概括:技能负责"怎么说",工具负责"怎么抓",两者组合后,你只需丢一个链接给智能体即可。
插件目录结构:先看一眼都有什么
plugins/web-to-markdown/
├── manifest.json # 插件包清单(组件声明 + 双语展示字段)
├── README.md # 插件详情页正文
├── skills/
│ └── web-to-markdown/
│ └── SKILL.md # 技能入口
└── tools/
└── web_to_markdown_tool.py # 抓取 + 转换核心实现
核心文件相对路径:
- 插件清单:plugins/web-to-markdown/manifest.json
- 技能定义:plugins/web-to-markdown/skills/web-to-markdown/SKILL.md
- 工具源码:plugins/web-to-markdown/tools/web_to_markdown_tool.py
- 插件说明:plugins/web-to-markdown/README.md
一键安装:3 种方式任选
agent-plugin 支持三种安装途径(见 README.md):
- Hub 在线安装(推荐新手):在扩展中心搜索
web-to-markdown即可安装,发布流程详见 docs/hub-publish.md; - 产品内置:旗舰插件随 jiuwenswarm 的
built_in目录分发,开箱即用; - 开发者直装:把
plugins/web-to-markdown/整个目录拷贝到本地插件目录:
# 克隆插件仓库
git clone https://gitcode.com/openJiuwen/agent-plugin
# 拷贝插件到本地插件包目录
cp -r agent-plugin/plugins/web-to-markdown ~/.jiuwenswarm/agent/workspace/plugins/plugin_packages/local/
实战:3 个高频使用场景
安装完成后,直接对智能体说人话就行。以下话术来自插件预设的 quick_inputs(定义在 plugins/web-to-markdown/manifest.json):
场景一:把网页转成 Markdown 笔记
把这篇网页转成 Markdown 笔记:https://example.com/article
智能体会调用 web_to_markdown 工具,按 SKILL.md 中的模板输出:
# {标题}
> 来源:{url}
{正文 Markdown}
场景二:抓取链接并整理成笔记
抓取这个链接的正文并整理成笔记:https://example.com/post
适合阅读博客、技术文章时"先存下来再细读",标题、链接、列表、引用、代码块都会按 Markdown 结构保留。
场景三:保存为 .md 文件
把这篇网页内容保存为 .md 文件
智能体会将笔记写入以标题命名的 .md 文件(自动去除文件名非法字符),方便归档到知识库。不要求保存时,笔记会直接在对话中展示。
工作原理:skill 与 tool 如何协作
用户给 URL ──► web-to-markdown skill(工作流指导)
│ 调用
▼
web_to_markdown tool(抓取 + 转 Markdown)
│ 返回 {title, markdown}
▼
智能体按 skill 模板输出笔记(可选保存 .md)
工具入参很简单:
url(必填):完整网页地址,需含http://或https://;timeout_seconds(可选):抓取超时秒数,默认 15 秒。
返回值为 success + title + markdown 字段;抓取失败时会返回 success=false 与明确错误原因,不会用空内容冒充产物。
安全性设计:新手也可以放心用
这个插件虽然是"轻量"实现,但安全边界做得很扎实(实现见 plugins/web-to-markdown/tools/web_to_markdown_tool.py):
- 纯标准库实现:仅用
urllib+html.parser,无第三方依赖,import期无副作用; - SSRF 防护:解析主机名后拒绝回环、私网、链路本地等地址,且重定向会逐跳复检,防止绕过;
- 响应体限长:最多读取 2MB,并校验
Content-Type,避免把二进制大文件读入内存; - 不写文件:工具只返回 Markdown 文本,文件保存由智能体按技能指导完成。
常见问题(FAQ)
问:为什么我给了链接却提示失败?
答:查看返回的 error 字段——常见原因是网络不通、页面无正文、目标为内网地址被安全策略拦截、或响应超过 2MB 上限。
问:转换后的 Markdown 支持哪些格式?
答:支持标题(h1–h6)、段落、链接、图片、加粗/斜体、列表、引用与代码块;script、style 等元内容会被自动跳过。
问:能批量转换多个网页吗? 答:可以逐个发送链接让智能体连续处理,每次转换相互独立,互不影响。
写在最后
web-to-markdown 用"1 skill + 1 tool"的最小组合,演示了 agent-plugin 插件体系"像搭积木一样集成能力"的设计思路。如果你想继续探索:
- 插件包完整规范:docs/plugin-spec.md
- 官方参考插件(含 skill/tool/rail 三类组件):plugins/example-plugin
- 插件目录清单:catalog/catalog.json
- 贡献与发布流程:CONTRIBUTING.md
现在,把你收藏夹里那篇"一直没空读"的网页丢给智能体,让它秒变一份干净的 Markdown 笔记吧 ✨