web-to-markdown

用途

web-to-markdown 用于将网页 URL 转换为干净的 Markdown。它通过驱动本地已安装的浏览器（借助 web2md）来完成转换，能够处理 JS 渲染的页面（Puppeteer → 用户 Chrome）。

主要能力

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

硬性触发门槛

该技能必须且只能在用户明确写出类似以下短语时使用：

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

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

非目标

不要使用 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
   • 如果缺失，指导用户安装（假设项目位于 ~/workspace/softaworks/projects/web2md）：
     • cd ~/workspace/softaworks/projects/web2md && npm install && npm run build && npm link
     • 或：cd ~/workspace/softaworks/projects/web2md && npm install && npm run build && npm install -g .
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 运行一次 web2md 命令，使用 --out ./out/
5. 验证输出：
   • 如果写入文件，验证文件存在且非空（例如 ls -la <path> 和 wc -c <path>）。
6. 返回：
   • 保存的文件路径，或 Markdown（stdout 模式）。

默认值（推荐）

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

适用场景

• 需要将 JS 渲染的网页转换为 Markdown。
• 使用 Chromium 系浏览器进行转换。
• 需要提取主体内容并清理链接。
• 需要可选添加 YAML frontmatter。
• 需要处理登录墙或人工验证页面（通过交互模式）。
• 需要批量转换多个 URL。

限制

• 必须由用户明确按名称调用，否则不得使用。
• 不使用 Playwright 或其他浏览器自动化栈。
• 依赖本地已安装的 web2md 和浏览器。
• 某些页面可能需要额外的渲染控制选项。
• 在容器/CI 中有时需要 --no-sandbox。
• 登录/会话需要使用专用配置文件目录。