URL 转 Markdown

通过 baoyu-fetch CLI（基于 Chrome CDP + 站点专属适配器）抓取任意 URL，并将其转换为干净的 Markdown 格式。

用户输入工具

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

1. 优先使用当前 agent runtime 暴露的内置用户输入工具 — 例如 AskUserQuestion、request_user_input、clarify、ask_user 或其等效实现。
2. 降级方案：若无此类工具，则以编号纯文本形式发出消息，并请用户针对每个问题，以所选编号/答案进行回复。
3. 批量处理：若该工具支持单次调用中提交多个问题，则将所有适用问题合并为一次调用；若仅支持单问题调用，则按上述优先级顺序逐一提问。

下方出现的具体 AskUserQuestion 引用仅为示例 — 在其他 runtime 中应替换为对应本地等效工具。

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 — 首个匹配项即生效：

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”）：“偏好设置应保存至何处？”
  • “User（推荐）” — ~/.baoyu-skills/（全局生效，适用于所有项目）
  • “Project” — .baoyu-skills/（仅对当前项目生效）

获取用户回答后，写入 EXTEND.md，确认提示“Preferences saved to [path]”，然后继续后续流程。

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

支持的配置键

EXTEND.md → CLI 参数映射关系：

值优先级顺序：CLI 参数 > EXTEND.md > 技能默认值。

使用方式

# 默认：无头模式抓取，Markdown 输出至 stdout
${READER} 

# 保存至文件
${READER}  --output article.md

# 同时保存并下载媒体资源
${READER}  --output article.md --download-media

# 等待用户交互（如登录/CAPTCHA）——自动检测并继续
${READER}  --wait-for interaction --output article.md

# 等待用户交互——手动控制（按 Enter 继续）
${READER}  --wait-for force --output article.md

# JSON 格式输出
${READER}  --format json --output article.json

# 强制指定适配器
${READER}  --adapter youtube --output transcript.md

选项说明

Agent 质量守门机制

关键提醒：请将默认的无头模式抓取结果视为临时性输出。部分网站在无头模式下渲染效果不同，可能在不报错的情况下静默返回低质量内容。

每次无头模式运行完成后，务必检查生成的 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（小写短横线格式，长度为 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、generic）、各适配器注意事项、媒体下载策略（ask / always / never）以及 JSON 输出结构定义，请参阅 references/adapters.md。在回答适配器相关问题或处理媒体提示前，请务必先阅读该文档。

环境变量

常见问题排查：Chrome 未找到 → 使用 --browser-path；超时 → 增大 --timeout；需处理登录/CAPTCHA → 使用 --wait-for interaction；调试需求 → 使用 --debug-dir 查看捕获的 HTML 与网络日志。

扩展支持

通过 EXTEND.md 实现自定义配置。具体路径与支持的配置键详见上方 偏好设置 小节。