web-to-markdown

web-to-markdown

通过驱动本地安装的浏览器（经由 web2md）将网页转换为干净的 Markdown。

硬性触发条件（必须强制执行）

除非用户明确写出恰好类似以下的短语，否则绝不能使用本技能：

• use the skill web-to-markdown ...
• use a skill web-to-markdown ...

如果用户没有明确按名称请求本技能，请停止并让用户重新发起请求，并在请求中包含：use the skill web-to-markdown。

本技能的功能

• 处理 JS 渲染的页面（Puppeteer → 用户的 Chrome）。
• 通过 puppeteer-core 在 Chromium 系浏览器（Chrome/Chromium/Brave/Edge）上效果最佳。
• 提取主要内容（Readability）。
• 转换为 Markdown（Turndown），并清理链接和可选的 YAML frontmatter。

非目标

• 不要使用 Playwright 或其他浏览器自动化方案；本机制是 web2md。

你应收集的输入（仅在缺失时询问）

• url（或 URL 列表）
• 输出偏好：
  • 打印到 stdout（--print），或
  • 保存到文件（--out ./file.md），或
  • 保存到目录（--out ./some-dir/，按页面标题自动命名）
• 针对棘手页面的可选渲染控制项：
  • --chrome-path <path>（如果 Chrome 自动检测失败）
  • --interactive（显示 Chrome 并暂停，以便用户完成人工检查/登录，然后按 Enter）
  • --wait-until load|domcontentloaded|networkidle0|networkidle2
  • --wait-for '<css selector>'
  • --wait-ms <milliseconds>
  • --headful（调试）
  • --no-sandbox（在容器/CI 中有时需要）
  • --user-data-dir <dir>（登录/会话；请使用专用配置文件目录）

工作流

1. 确认用户明确调用了本技能（use the skill web-to-markdown）。
2. 验证 URL 以 http:// 或 https:// 开头。
3. 确保已安装 web2md：
   • 运行：command -v web2md
   • 如果缺失，指导用户安装：
     • 如果可通过 npm 获取：npm install -g web2md
     • 如果从源码安装：克隆仓库，然后运行 npm install && npm run build && npm link
4. 转换：
   • 单个 URL → 文件：
     • web2md '<url>' --out ./page.md
   • 单个 URL → 目录中自动命名的文件：
     • mkdir -p ./out && web2md '<url>' --out ./out/
   • 人工验证/登录墙（交互式）：
     • mkdir -p ./out && web2md '<url>' --interactive --user-data-dir ./tmp/web2md-profile --out ./out/
     • 然后：在浏览器窗口中完成检查，并在终端中按 Enter 继续。
   • 打印到 stdout：
     • web2md '<url>' --print
   • 多个 URL（批量）：
     • 创建输出目录（例如 ./out/），然后对每个 URL 使用 --out ./out/ 运行一条 web2md 命令
5. 验证输出：
   • 如果写入文件，请验证它们存在且非空（例如 ls -la <path> 和 wc -c <path>）。
6. 返回：
   • 保存的文件路径，或 Markdown（stdout 模式）。

默认值（推荐）

• 对大多数页面：--wait-until networkidle2
• 对重型应用：先使用 --wait-until domcontentloaded --wait-ms 2000，然后如有需要再添加 --wait-for 'main'（或其他稳定的选择器）。