baoyu-url-to-markdown

URL 转 Markdown

通过 baoyu-fetch CLI（Chrome CDP + 网站专用适配器）抓取任意 URL，并将其转换为整洁的 Markdown。

用户输入工具

当此技能向用户提问时，请遵循以下工具选择规则（按优先级排序）：

1. 优先使用当前 Agent 运行时提供的内置用户输入工具，例如 AskUserQuestion、request_user_input、clarify、ask_user 或任何等效工具。
2. 回退方案：如果没有此类工具，请发送带编号的纯文本消息，并请用户针对每个问题回复所选编号或答案。
3. 批量提问：如果工具支持每次调用多个问题，请将所有适用问题合并到一次调用中；如果每次只能提一个问题，请按优先级逐一提问。

下方的 AskUserQuestion 示例仅供参考，请替换为其他运行时中的本地等效工具。

CLI 设置

重要：CLI 源代码以 vendored 形式存放在 {baseDir}/scripts/lib 中。scripts/package.json 仅安装第三方运行时依赖。

Agent 执行说明：

1. 将此 SKILL.md 文件所在目录路径确定为 {baseDir}
2. 解析 ${BUN} 运行时：如果已安装 bun → 使用 bun；否则建议安装 Bun
3. 如果 {baseDir}/scripts/node_modules 不存在，则运行 ${BUN} install --cwd {baseDir}/scripts
4. ${READER} = {baseDir}/scripts/baoyu-fetch
5. 将本文档中的所有 ${READER} 替换为解析后的值

偏好设置（EXTEND.md）

按优先级检查 EXTEND.md，找到的第一个文件优先：

优先级	路径	范围
1	.baoyu-skills/baoyu-url-to-markdown/EXTEND.md	项目
2	${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-url-to-markdown/EXTEND.md	XDG
3	$HOME/.baoyu-skills/baoyu-url-to-markdown/EXTEND.md	用户主目录

结果	操作
找到	读取、解析并应用设置
未找到	必须运行首次设置（见下文）——不得静默创建默认设置

EXTEND.md 支持：默认下载媒体、默认输出目录。

首次设置 ⛔ 阻塞

找不到 EXTEND.md 时，必须使用 AskUserQuestion 收集偏好设置，然后才能创建 EXTEND.md。绝不能静默使用默认设置创建 EXTEND.md。设置完成前，禁止生成内容。将以下三个问题合并到一次调用中：

• Q1 — 媒体（标题 "Media"）："如何处理网页中的图片和视频？"
  • "每次询问（推荐）" — 每次保存后询问
  • "始终下载" — 下载到本地 imgs/ 和 videos/
  • "从不下载" — 保留远程 URL
• Q2 — 输出（标题 "Output"）："默认输出目录是什么？"
  • "url-to-markdown（推荐）" — 保存到 ./url-to-markdown/{domain}/{slug}.md
  • 用户可以选择 "Other" 并输入自定义路径
• Q3 — 保存（标题 "Save"）："将偏好设置保存到哪里？"
  • "用户（推荐）" — ~/.baoyu-skills/（适用于所有项目）
  • "项目" — .baoyu-skills/（仅适用于此项目）

收到回答后，写入 EXTEND.md，确认“偏好设置已保存到 [path]”，然后继续。

完整模板：references/config/first-time-setup.md。

支持的键

键	默认值	取值	说明
download_media	ask	ask / 1 / 0	ask = 每次询问，1 = 始终下载，0 = 从不下载
default_output_dir	空	路径或空	默认输出目录（空 = ./url-to-markdown/）

EXTEND.md → CLI 映射：

EXTEND.md 键	CLI 参数	备注
download_media: 1	--download-media	需要设置 --output
default_output_dir: ./posts/	Agent 构造 --output ./posts/{domain}/{slug}.md	Agent 生成路径，不是直接传递的标志

取值优先级：CLI 参数 → EXTEND.md → 技能默认值。

用法

# Default: headless capture, markdown to stdout
${READER} <url>

# Save to file
${READER} <url> --output article.md

# Save with media download
${READER} <url> --output article.md --download-media

# Wait for interaction (login/CAPTCHA) — auto-detect and continue
${READER} <url> --wait-for interaction --output article.md

# Wait for interaction — manual control (Enter to continue)
${READER} <url> --wait-for force --output article.md

# JSON output
${READER} <url> --format json --output article.json

# Force specific adapter
${READER} <url> --adapter youtube --output transcript.md

选项

选项	描述
<url>	要抓取的 URL
--output <path>	输出文件路径（默认：标准输出）
--format <type>	输出格式：markdown（默认）或 json
--json	--format json 的简写
--adapter <name>	强制使用适配器：x、youtube、hn 或 generic（默认：自动检测）
--headless	强制使用无头 Chrome（不显示窗口）
--wait-for <mode>	交互等待模式：none（默认）、interaction 或 force
--wait-for-interaction	--wait-for interaction 的别名
--wait-for-login	--wait-for interaction 的别名
--timeout <ms>	页面加载超时时间（默认：30000）
--interaction-timeout <ms>	登录／CAPTCHA 等待超时时间（默认：600000 = 10 分钟）
--interaction-poll-interval <ms>	交互检查轮询间隔（默认：1500）
--download-media	将图片／视频下载到本地 imgs/ 和 videos/，并重写 Markdown 链接。需要 --output
--media-dir <dir>	下载媒体的基础目录（默认：与 --output 相同的目录）
--cdp-url <url>	重用现有的 Chrome DevTools Protocol 端点
--browser-path <path>	自定义 Chrome／Chromium 二进制文件路径
--chrome-profile-dir <path>	Chrome 用户数据目录（默认：BAOYU_CHROME_PROFILE_DIR 环境变量指定的目录或 ./baoyu-skills/chrome-profile）
--debug-dir <dir>	写入调试产物（document.json、markdown.md、page.html、network.json）

Agent 质量门槛

重要：将默认的无头抓取视为暂定结果。一些网站在无头模式下的渲染方式不同，即使 CLI 没有报错，也可能会悄无声息地返回低质量内容。

每次无头运行后，都要检查保存的 Markdown。完整清单、恢复工作流和抓取模式表请参阅 references/quality-gate.md。如果运行结果看起来可疑，或用户询问登录／CAPTCHA 处理方式，请阅读该文档。

输出路径生成

Agent 必须构建输出文件路径——baoyu-fetch 不会自动生成路径。

算法：

1. 从 EXTEND.md 的 default_output_dir 或默认值 ./url-to-markdown/ 确定基础目录
2. 从 URL 提取域名（例如，example.com）
3. 根据 URL 路径或页面标题生成 slug（kebab-case，2-6 个词）
4. 构建路径：{base_dir}/{domain}/{slug}/{slug}.md——每个 URL 都有自己的目录，以便媒体文件彼此隔离
5. 冲突处理：追加时间戳 {slug}-YYYYMMDD-HHMMSS/{slug}-YYYYMMDD-HHMMSS.md

将构建好的路径传给 --output。媒体文件（--download-media）会保存到 Markdown 文件旁的子目录中，确保每个 URL 的资源各自独立。

适配器与媒体

适配器目录（X、YouTube、Hacker News、通用）、各适配器说明、媒体下载流程（ask / 始终／从不）和 JSON 输出架构请参阅 references/adapters.md。回答适配器相关问题或处理媒体提示词前，请先阅读该文档。

环境变量

变量	描述
BAOYU_CHROME_PROFILE_DIR	Chrome 用户数据目录（也可使用 --chrome-profile-dir）

故障排查：未找到 Chrome → 使用 --browser-path。超时 → 增大 --timeout。登录／CAPTCHA → 使用 --wait-for interaction。调试 → 使用 --debug-dir 检查已抓取的 HTML 和网络日志。

扩展支持

通过 EXTEND.md 使用自定义配置。路径和支持的键请参阅上方的首选项部分。