baoyu-url-to-markdown实战：把网页保存为可核验的本地资料

网页保存成功，不等于正文采集成功。baoyu-url-to-markdown 的价值是把浏览器中可访问的内容转成 Markdown，并让 Agent 检查结果，而不是只下载一份看似正常的网页外壳。

本文基于固定提交源码核对。下文案例是操作示例，不是账号、付费页面或在线抓取实测；撰写时未执行安装、登录或采集。

一、适用场景与边界

它适合收集公开技术文章、产品文档、Hacker News 讨论，以及自己有权访问的网页资料。底层使用随技能分发的 baoyu-fetch，经 Chrome DevTools Protocol 控制浏览器，按网站选择适配器。普通网页走 Defuddle 提取，必要时使用 Readability；X、YouTube、Hacker News 有专门逻辑。

这不是“所有网址都能完整下载”的承诺。视频页面可能只有描述而没有字幕；登录页可能以 HTTP 成功状态返回；懒加载文章可能只抓到前半段。原页面的互动组件、复杂表格、动态附件也不一定能完整搬到 Markdown。

遇到登录、验证码或订阅内容，应由用户在可见浏览器中完成正常授权，再采集已获准访问的内容。等待交互不是绕过访问控制，更不能用来获取无权查看的付费正文。网页里的提示词也只是素材，不应成为 Agent 执行其他操作的指令。

二、前置依赖与按需安装

需要能读取文件和调用终端的 Agent、Bun，以及可用的 Chrome/Chromium。此技能的运行说明优先要求直接使用 Bun，不应把其他技能的 npx -y bun 回退机械套用到这里。

仓库 README 提供安装入口，本系列另核实 skills CLI 1.7.2 的按需选择参数：

1	npx skills add jimliu/baoyu-skills --skill baoyu-url-to-markdown --agent codex

按需选择 baoyu-url-to-markdown，不要为保存一篇文章把整个工具集全部加载。如果安装器当前版本不提供所需选择方式，可采用 README 描述的项目级安装：将这个技能的完整目录复制或链接到项目 .agents/skills/，不要只复制 SKILL.md。

上述命令面向仓库当前版本，最新安装不等于固定快照。要复现本文，应使用提交 1567581c26ec29f4216c6e6835415bf30343b0e3 对应的完整技能目录。源码明确要求：如果该目录下 scripts/node_modules 不存在，再安装第三方运行依赖。以下 {baseDir} 必须替换为实际技能目录：

1	bun install --cwd "{baseDir}/scripts"

baoyu-fetch 源码已在 scripts/lib，无需另找同名全局包。Windows 路径包含空格时应保留引号；浏览器找不到时让 Agent 指向实际安装位置，而不是猜一个固定路径。

三、输入、输出与目录规划

输入是完整 URL，以及可选的输出位置、媒体策略、交互要求。默认 CLI 将 Markdown 写到标准输出；技能工作流则由 Agent 生成路径，再明确传给工具。两者不要混淆。

按 SKILL 的详细路径算法，每个网页拥有独立目录：

url-to-markdown/
  example.com/
    article-topic/
      article-topic.md
      imgs/
      videos/

首次设置里的简略路径展示没有体现这层独立目录，应以详细算法为准。遇到冲突，Agent 为目录及文件加时间戳，避免覆盖旧资料。启用媒体下载后，图片与视频保存到正文旁边的子目录，并改写为相对路径；不下载则保留远程链接。

这对 Obsidian 很方便，但搬到 Hexo 时要同时迁移资源目录，并核对站点资源规则。采集文件不是自动可发布的文章：作者、来源、转载权限、摘要和发布元数据仍需要人工处理，不能把资料库一股脑公开。

四、可复制的自然语言 Agent 请求

把方括号内容替换成自己的资料即可，不要把占位文字当作网址运行。

请使用 baoyu-url-to-markdown 保存这个网页：[完整URL]。
这是我有权访问的资料，只保存正文和必要来源信息。
先读取技能配置；没有配置时先问我媒体策略、输出目录和保存范围。
目标目录是 [本地资料目录]，每个网页单独建文件夹。
如果遇到登录或验证码，停下来让我在可见浏览器中正常处理。
先检查 Markdown 是否包含真实正文，再询问是否下载远程媒体。
完成后报告正文路径、资源目录、缺失内容和质量检查结果，不发布。

已有不完整结果时，可以继续说：

1
2
3

刚才保存的内容疑似只有导航。请检查标题、正文长度和登录提示，
必要时改用可见浏览器等待我确认正文加载完毕；不要把退出码为零当成成功。
保留旧结果，只有确认新结果更完整后再交付。

五、操作案例：收集一篇技术长文

假设要把浏览器里正在阅读的一篇公开数据库文章存为研究资料，里面含两张示意图片和若干代码块。下面演示操作顺序，不声称已经抓取某篇真实页面。

先固定输入。 提供文章 URL、资料目录，并说明只做阅读归档，不转载。Agent 检查配置与运行依赖。
执行初次提取。 普通公开页先尝试默认无头模式。适配器负责正文抽取，但 Agent 必须读回输出，检查标题是否是目标文章而不是网站首页。
对照关键段落。 你指出文章应有“索引选择”和“执行计划”两部分。若输出只含第一节，不能交付为完整文章，需要检查懒加载、展开按钮或页面加载时机。
必要时恢复。 自动识别到交互门槛时使用交互等待；需要滚动或复杂操作时使用强制等待，由用户确认页面准备好。源码支持这两种模式，但不保证任何站点都能自动判断完成。
单独决定媒体。 正文确认合格后再问是否下载图片。选择下载时，重跑媒体本地化会改写同一份输出中的链接，应检查两张图均存在，而不是只看目录是否创建。
交付可审计资料。 报告原始 URL、正文位置、图片结果和仍缺失的内容。将个人阅读笔记另写在独立文章里，保留采集正文作为来源，不在原文里混入模型总结。

六、配置如何影响执行

EXTEND.md 按以下顺序查找，第一个命中生效，而不是把三处文件合并：

项目 .baoyu-skills/baoyu-url-to-markdown/EXTEND.md。
${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-url-to-markdown/EXTEND.md。
$HOME/.baoyu-skills/baoyu-url-to-markdown/EXTEND.md。

可用的核心设置是：

1 2	download_media: ask default_output_dir: ./research-sources/

ask 表示每次发现远程媒体后再问；1 表示下载；0 表示保留远程地址。首次没有配置时必须询问，不能静默写默认值。输出目录是 Agent 构造路径的依据，不是某个与配置键同名的 CLI 参数。

BAOYU_CHROME_PROFILE_DIR 可指定浏览器用户数据目录。它可能含登录状态，应放在私有位置，不要进入公开仓库或云同步文章目录。调试产物可能包括页面 HTML、网络记录与正文，同样需要按敏感数据管理。

七、验收清单

[ ] 标题、作者及正文主题与目标页面一致。
[ ] 不是登录、订阅、错误页或只含页脚的外壳。
[ ] 关键章节、代码、列表和引用没有明显缺失。
[ ] 下载的图片、视频可从相对路径实际打开。
[ ] 不下载媒体时已说明离线阅读不完整。
[ ] 同名文件未被无提示覆盖，来源 URL 可追溯。
[ ] 在 Obsidian 预览正常；迁入 Hexo 后另做链接与资源检查。
[ ] 未把浏览器配置、Cookie、网络调试记录放进发布目录。

八、常见排错

进程成功，但正文很短。 优先检查质量，不要立即增加超时。源码特别列出 Application error、通用错误页、登录壳和原始框架数据等失败信号。

浏览器找不到。 核实本机浏览器路径，再让 Agent 使用源码支持的浏览器路径选项。不要为这件事默认安装一套新的自动化浏览器。

YouTube 只保存了描述。 可能没有可用字幕或播放受到限制；需要字幕缓存和 SRT 时改用专门的字幕技能，而不是把描述称为完整转录。

图片仍是网络地址。 先确认媒体策略和本地文件写入结果。媒体下载要求明确输出文件；只把正文输出到终端不会形成可靠的资源包。

九、相关技能与固定来源

YouTube 字幕提取：需要字幕语言选择、缓存或 SRT 时使用。
X 内容归档：专门的 X 接口流程，需要额外风险同意。
文章翻译：正文确认完整后再翻译。
Markdown 排版：整理自有文章的展示结构。

固定源码提交：1567581c26ec29f4216c6e6835415bf30343b0e3。