URL 转 Markdown

通过 Chrome CDP 获取任意 URL，保存渲染后的 HTML 快照，并将其转换为干净的 Markdown。

脚本目录

重要：所有脚本都位于此技能的 scripts/ 子目录中。

代理执行说明：

1. 确定此 SKILL.md 文件所在的目录路径，记为 {baseDir}
2. 脚本路径 = {baseDir}/scripts/<脚本名称>.ts
3. 解析 ${BUN_X} 运行时：如果已安装 bun → 使用 bun；如果 npx 可用 → 使用 npx -y bun；否则建议安装 bun
4. 将本文档中的所有 {baseDir} 和 ${BUN_X} 替换为实际值

脚本参考：

首选项 (EXTEND.md)

检查 EXTEND.md 是否存在（优先级顺序）：

# macOS, Linux, WSL, Git Bash
test -f .baoyu-skills/baoyu-url-to-markdown/EXTEND.md && echo "project"
test -f "${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-url-to-markdown/EXTEND.md" && echo "xdg"
test -f "$HOME/.baoyu-skills/baoyu-url-to-markdown/EXTEND.md" && echo "user"

# PowerShell (Windows)
if (Test-Path .baoyu-skills/baoyu-url-to-markdown/EXTEND.md) { "project" }
$xdg = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { "$HOME/.config" }
if (Test-Path "$xdg/baoyu-skills/baoyu-url-to-markdown/EXTEND.md") { "xdg" }
if (Test-Path "$HOME/.baoyu-skills/baoyu-url-to-markdown/EXTEND.md") { "user" }

┌────────────────────────────────────────────────────────┬───────────────────┐
│ 路径 │ 位置 │
├────────────────────────────────────────────────────────┼───────────────────┤
│ .baoyu-skills/baoyu-url-to-markdown/EXTEND.md │ 项目目录 │
├────────────────────────────────────────────────────────┼───────────────────┤
│ $HOME/.baoyu-skills/baoyu-url-to-markdown/EXTEND.md │ 用户主目录 │
└────────────────────────────────────────────────────────┴───────────────────┘

┌───────────┬───────────────────────────────────────────────────────────────────────────┐
│ 结果 │ 操作 │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ 找到 │ 读取、解析、应用设置 │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ 未找到 │ 必须运行首次设置（见下文）—— 不要静默创建默认配置 │
└───────────┴───────────────────────────────────────────────────────────────────────────┘

EXTEND.md 支持：默认是否下载媒体 | 默认输出目录 | 默认捕获模式 | 超时设置

首次设置（阻塞操作）

关键：当未找到 EXTEND.md 时，您必须使用 AskUserQuestion 询问用户的首选项，然后再创建 EXTEND.md。切勿在未询问的情况下使用默认值创建 EXTEND.md。这是一个阻塞操作——在设置完成之前，不要继续进行任何转换。

在一次调用中使用 AskUserQuestion 询问所有问题：

问题 1 — 标题：”媒体”，问题：”如何处理页面中的图片和视频？”

• “每次都询问（推荐）” — 保存 Markdown 后，询问是否下载媒体
• “始终下载” — 始终将媒体下载到本地的 imgs/ 和 videos/ 目录
• “从不下载” — 在 Markdown 中保留原始远程 URL

问题 2 — 标题：”输出”，问题：”默认输出目录？”

• “url-to-markdown（推荐）” — 保存到 ./url-to-markdown/{域名}/{短名称}.md
• （用户可选择”其他”来输入自定义路径）

问题 3 — 标题：”保存”，问题：”首选项保存位置？”

• “用户（推荐）” — ~/.baoyu-skills/（所有项目）
• “项目” — .baoyu-skills/（仅此项目）

用户回答后，在所选位置创建 EXTEND.md，确认”首选项已保存至 [路径]”，然后继续。

完整参考：references/config/first-time-setup.md

支持的键

EXTEND.md → 命令行参数映射：

值优先级：

1. 命令行参数（--download-media、-o、--output-dir）
2. EXTEND.md
3. 技能默认值

功能特性

• 使用 Chrome CDP 实现完整的 JavaScript 渲染
• 两种捕获模式：自动或等待用户
• 将渲染后的 HTML 保存为同级的 -captured.html 文件
• 生成带有元数据的干净 Markdown 输出
• 优先使用 Defuddle 进行 Markdown 转换，并自动回退到从 git 历史中恢复的 Defuddle 之前的提取器
• 通过等待模式处理需要登录的页面
• 将图片和视频下载到本地目录

使用方法

# 自动模式（默认）- 页面加载时捕获
${BUN_X} {baseDir}/scripts/main.ts <url>

# 等待模式 - 等待用户信号再捕获
${BUN_X} {baseDir}/scripts/main.ts <url> --wait

# 保存到特定文件
${BUN_X} {baseDir}/scripts/main.ts <url> -o output.md

# 保存到自定义输出目录（自动生成文件名）
${BUN_X} {baseDir}/scripts/main.ts <url> --output-dir ./posts/

# 下载图片和视频到本地目录
${BUN_X} {baseDir}/scripts/main.ts <url> --download-media

选项

捕获模式

等待模式工作流程：

1. 使用 --wait 运行 → 脚本输出”准备就绪时按回车键”
2. 要求用户确认页面已准备就绪
3. 向标准输入发送换行符以触发捕获

输出格式

每次运行会并排保存两个文件：

• Markdown：包含 YAML 前置元数据，包括 url、title、description、author、published、可选的 coverImage 和 captured_at，后跟转换后的 Markdown 内容
• HTML 快照：*-captured.html，包含从 Chrome 捕获的渲染后页面 HTML

HTML 快照在任何 Markdown 媒体本地化之前保存，因此它保持用于转换的页面 DOM 的忠实捕获。

输出目录

默认：url-to-markdown/<域名>/<短名称>.md
使用 --output-dir ./posts/：./posts/<域名>/<短名称>.md

HTML 快照路径使用相同的基本名称：

• url-to-markdown/<域名>/<短名称>-captured.html
• ./posts/<域名>/<短名称>-captured.html
• <短名称>：来自页面标题或 URL 路径（短横线命名，2-6 个单词）
• 冲突解决：附加时间戳 <短名称>-YYYYMMDD-HHMMSS.md

当启用 --download-media 时：

• 图片保存到 Markdown 文件旁边的 imgs/ 目录
• 视频保存到 Markdown 文件旁边的 videos/ 目录
• Markdown 中的媒体链接被重写为本地相对路径

转换回退

转换顺序：

1. 首先尝试使用 Defuddle
2. 如果 Defuddle 抛出错误、无法加载、返回明显不完整的 Markdown，或捕获的内容质量低于旧版管道，则自动回退到 Defuddle 之前的提取器
3. 回退路径使用从 git 历史中恢复的基于旧版 Readability/选择器/Next.js 数据的 HTML 转 Markdown 实现

命令行输出将显示：

• Converter: defuddle 当 Defuddle 成功时
• Converter: legacy:... 加上 Fallback used: ... 当需要回退时

媒体下载工作流程

基于 EXTEND.md 中的 download_media 设置：

每次都询问流程

1. 运行脚本 不带 --download-media → 保存 Markdown
2. 检查保存的 Markdown 中是否有远程媒体 URL（图片/视频链接中的 https://）
3. 如果没有找到远程媒体 → 完成，无需提示
4. 如果找到远程媒体 → 使用 AskUserQuestion：
   • 标题：”媒体”，问题：”下载 N 个图片/视频到本地文件？”
   • “是” — 下载到本地目录
   • “否” — 保留远程 URL
5. 如果用户确认 → 再次使用 --download-media 运行脚本（用本地化链接覆盖 Markdown）

环境变量

故障排除：找不到 Chrome → 设置 URL_CHROME_PATH。超时 → 增加 --timeout。复杂页面 → 尝试 --wait 模式。如果 Markdown 质量差，检查保存的 -captured.html 并查看运行是否记录了旧版回退。

扩展支持

通过 EXTEND.md 进行自定义配置。有关路径和受支持选项，请参阅首选项部分。