Baoyu Url To Markdown

核心用法

baoyu-url-to-markdown 是一个基于 Chrome DevTools Protocol (CDP) 的网页抓取与转换工具，通过真实浏览器渲染 JavaScript 后再提取内容，确保动态网页的完整性。

执行流程：
1. 通过 Bun/Node 运行 TypeScript 脚本，启动 Chrome（默认 headless，失败自动降级到可视模式）
2. 等待页面 network idle 后捕获渲染后的 HTML，保存为 *-captured.html
3. 经多层转换管道生成 Markdown：URL 特定解析器 → Defuddle → 传统降级方案 → 托管 API 兜底
4. 可选下载图片/视频到本地并重写链接

关键特性：

• 双模式捕获：auto（自动）与 --wait（用户确认后捕获，用于登录墙、付费墙）
• 智能降级链：本地 headless → 本地可视 Chrome → 托管 defuddle.md API
• 专项优化：X/Twitter 文章解析、YouTube 字幕提取、Shadow DOM 序列化、archive.ph 原链还原
• 媒体本地化：--download-media 将远程资源下载至 imgs/、videos/

显著优点

• 高保真渲染：CDP 确保 SPA、懒加载、动态注入内容完整捕获
• 多层容错：四级降级策略（parser → Defuddle → legacy → API）大幅降低失败率
• 登录/付费墙支持：--wait 模式允许用户手动完成验证后捕获
• 结构化输出：YAML frontmatter 包含标题、作者、发布时间、封面图等元数据
• 透明可审计：保留原始 HTML 快照，便于质量回溯

潜在局限

• 依赖 Chrome：需本地安装 Chrome，无浏览器环境完全失效
• Bun/Node 运行时：依赖 Bun 或 npx，Windows PowerShell 路径处理需额外注意
• 反爬对抗：部分站点检测 headless Chrome，需 --browser headed 绕过
• 托管 API 降级损失：极端情况下 fallback 到 defuddle.md 时丢失本地 HTML 快照
• 质量门人工介入：Agent 需主动检查输出，低质量内容不会自动触发重试

适合人群

• 需要批量归档网页、构建知识库的内容工作者
• 处理动态内容（Notion、X/Twitter、YouTube）的开发者
• 需要绕过简单反爬、处理登录后内容的自动化场景

常规风险

• 隐私泄露：--wait 模式可能捕获用户登录后的敏感页面内容
• 存储膨胀：--download-media 大量图片/视频可能快速占用磁盘
• 版权风险：自动下载媒体可能违反网站 ToS 或版权法
• 误捕获风险：headless 模式可能捕获到错误页、登录壳而未报错，需人工质量检查
• API 依赖：极端降级依赖第三方 defuddle.md 服务可用性

安全评估

• 本地执行：核心逻辑本地 Chrome/CDP 完成，无强制云端传输
• 可控降级：托管 API 仅在本地完全失败后启用，非默认路径
• 无持久凭据：不存储用户密码，登录态依赖用户本地 Chrome profile