核心用法
baoyu-url-to-markdown 是一款强大的网页内容抓取与转换工具，通过调用 baoyu-fetch CLI 将任意 URL 转换为结构清晰的 Markdown 文档。其核心工作流程包括：首先配置运行环境（依赖 Bun 或 npx），然后通过 Chrome DevTools Protocol (CDP) 驱动浏览器进行页面渲染，最后利用站点专属适配器提取干净内容。
使用时需先完成首次配置：Agent 会检测 EXTEND.md 配置文件，若不存在则通过交互式询问收集用户偏好（媒体下载策略、默认输出目录、配置保存位置）。随后即可通过 ${READER} <url> 执行抓取，支持多种输出模式（stdout/文件/JSON）和交互模式（headless 无头模式或 --wait-for interaction 手动交互模式处理登录/CAPTCHA）。
工具内置四大适配器自动识别站点：x 适配器提取推文串与 X 文章；youtube 适配器获取字幕与时间戳章节；hn 适配器解析嵌套评论线程；generic 适配器作为兜底方案，采用 Defuddle + Readability 双引擎提取。高级功能包括媒体本地下载、Chrome 会话持久化、调试产物输出等。
显著优点
多平台深度适配：区别于通用爬虫，本技能针对 X/Twitter、YouTube、Hacker News 三大内容平台开发了专属解析逻辑，能正确处理动态加载、线程嵌套、字幕分段等复杂场景，输出质量远超简单 HTML-to-Markdown 转换。
反爬虫与验证对抗能力：通过 Chrome CDP 实现完整 JavaScript 渲染，配合 --wait-for interaction 模式可自动检测并暂停等待 Cloudflare、reCAPTCHA、hCAPTCHA 等验证关卡，用户完成验证后自动继续抓取，有效解决现代网站的内容保护机制。
质量门控机制：内置 Agent 质量检查流程，要求 Agent 在 headless 抓取后主动校验输出内容（标题匹配度、正文完整性、错误页面识别），发现低质量结果时自动切换至交互模式重试，避免"静默失败"。
灵活的配置体系：通过 EXTEND.md 支持项目级/用户级配置，媒体下载策略可选"每次询问/总是下载/从不下载"，输出路径支持智能 slug 生成（{domain}/{slug}/{slug}.md），满足个人知识库搭建与团队协作的不同需求。
结构化数据输出：--format json 模式提供机器友好的结构化数据，包含适配器类型、登录状态、交互门详情、内容块、媒体资产等元信息，便于二次开发或自动化工作流集成。
潜在缺点与局限性
外部依赖较重：核心功能依赖 baoyu-fetch CLI（需单独安装）和 Chrome/Chromium 浏览器，首次部署需配置 Bun/NPX 运行时与浏览器路径，Windows 环境还需处理 PowerShell 脚本兼容性问题。
性能开销显著：CDP 驱动完整浏览器实例相比纯 HTTP 请求有数量级的资源消耗，大规模批量抓取时启动开销、内存占用、执行时间均会成为瓶颈，不适合高频自动化场景。
平台适配维护成本：站点专属适配器依赖目标网站的 DOM 结构稳定性，X/Twitter、YouTube 等平台的界面改版可能导致适配器失效，需要持续维护更新。
隐私与合规边界：虽然本 Skill 本身无数据收集，但 baoyu-fetch 执行的网络请求可能触及部分网站的 ToS，用户需自行评估抓取行为的合法性；--download-media 下载的版权素材也存在合规风险。
JSON 模式下的内容缺失：部分平台（如 YouTube 无字幕视频、受限播放内容）在特定条件下可能返回描述-only 或空内容，需结合 status 字段判断实际抓取质量。
适合的目标群体
知识管理用户：需要构建个人知识库、保存网络文章、归档社交媒体内容的效率工具用户，尤其是 Obsidian/Notion 等 Markdown 友好型笔记系统的使用者。
研究人员与记者：需要系统性地收集、标注、引用网络来源的学术研究者、调查记者，依赖结构化输出和 YAML front matter 进行元数据管理。
开发者与自动化工程师：需要网页内容作为 RAG 知识库输入、训练数据来源或自动化工作流节点的技术用户，可利用 JSON 输出模式集成至数据处理管道。
内容创作者：需要引用、备份、再加工社交媒体内容（推文串、视频字幕）的博主、编辑、策展人。
常规使用风险
运行时稳定性：Chrome 实例崩溃、CDP 连接超时、页面加载超时（默认 30s）等问题在高延迟网络或复杂页面下偶有发生，建议通过 --timeout、 --interaction-timeout 参数调优。
存储空间膨胀：启用 --download-media 后，图片视频本地下载可能快速消耗磁盘空间，且默认按 URL 隔离目录的策略会产生大量小文件，需定期清理或配置外部存储。
会话状态管理：Chrome profile 持久化虽能保留登录态，但长期使用可能积累 Cookie 膨胀、存储碎片，建议定期清理 ./baoyu-skills/chrome-profile 目录。
版本兼容性：baoyu-fetch CLI 与 Chrome 浏览器版本存在绑定关系， major 版本升级后可能出现 CDP 协议不兼容，需同步更新工具链。