tuzi-url-to-markdown

URL 转 Markdown

通过 Chrome CDP 获取任意 URL，并将 HTML 转换为简洁的 Markdown。

脚本目录

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

Agent 执行说明：

1. 确定此 SKILL.md 文件所在目录的路径，并将其记为 SKILL_DIR
2. 脚本路径 = ${SKILL_DIR}/scripts/<script-name>.ts
3. 将本文档中所有 ${SKILL_DIR} 替换为实际路径

脚本参考：

脚本	用途
scripts/main.ts	URL 获取的 CLI 入口

偏好设置（EXTEND.md）

使用 Bash 按优先级顺序检查是否存在 EXTEND.md：

# Check project-level first
test -f .tuzi-skills/tuzi-url-to-markdown/EXTEND.md && echo "project"

# Then user-level (cross-platform: $HOME works on macOS/Linux/WSL)
test -f "$HOME/.tuzi-skills/tuzi-url-to-markdown/EXTEND.md" && echo "user"

┌────────────────────────────────────────────────────────┬───────────────────┐ │ 路径 │ 位置 │ ├────────────────────────────────────────────────────────┼───────────────────┤ │ .tuzi-skills/tuzi-url-to-markdown/EXTEND.md │ 项目目录 │ ├────────────────────────────────────────────────────────┼───────────────────┤ │ $HOME/.tuzi-skills/tuzi-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/{domain}/{slug}.md
• （用户也可以选择「其他」并输入自定义路径）

问题 3 — 标题：「保存」，问题：「将偏好设置保存到哪里？」

• 「用户（推荐）」——~/.tuzi-skills/（适用于所有项目）
• 「项目」——.tuzi-skills/（仅适用于此项目）

用户回答后，在所选位置创建 EXTEND.md，确认「偏好设置已保存到 [path]」，然后继续。

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

支持的键

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

取值优先级：

1. CLI 参数（--download-media、-o）
2. EXTEND.md
3. 技能默认值

功能

• 使用 Chrome CDP 完整渲染 JavaScript
• 两种捕获模式：自动或等待用户
• 输出简洁的 Markdown，并附带元数据
• 通过等待模式处理需要登录的页面
• 将图片和视频下载到本地目录

用法

# Auto mode (default) - capture when page loads
npx -y bun ${SKILL_DIR}/scripts/main.ts <url>

# Wait mode - wait for user signal before capture
npx -y bun ${SKILL_DIR}/scripts/main.ts <url> --wait

# Save to specific file
npx -y bun ${SKILL_DIR}/scripts/main.ts <url> -o output.md

# Download images and videos to local directories
npx -y bun ${SKILL_DIR}/scripts/main.ts <url> --download-media

选项

选项	描述
<url>	要抓取的 URL
-o <path>	输出文件路径（默认：自动生成）
--wait	等待用户发出信号后再抓取
--timeout <ms>	页面加载超时时间（默认：30000）
--download-media	将图片/视频素材下载到本地 imgs/ 和 videos/，并将 Markdown 链接改写为本地相对路径

抓取模式

模式	行为	适用场景
自动（默认）	网络空闲时抓取	公开页面、静态内容
等待（--wait）	用户发出就绪信号	需要登录的页面、延迟加载、付费墙

等待模式工作流：

1. 使用 --wait 运行 → 脚本输出「准备就绪时按 Enter」
2. 询问用户确认页面已就绪
3. 向 stdin 发送换行符以触发抓取

输出格式

YAML front matter，包含 url、title、description、author、published、captured_at 字段，后接转换后的 Markdown 内容。

输出目录

url-to-markdown/<domain>/<slug>.md

• <slug>：根据页面标题或 URL 路径生成（kebab-case，2-6 个词）
• 冲突处理：追加时间戳 <slug>-YYYYMMDD-HHMMSS.md

启用 --download-media 时：

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

媒体下载工作流

根据 EXTEND.md 中的 download_media 设置：

设置	行为
1（始终）	使用 --download-media 标志运行脚本
0（从不）	不使用 --download-media 标志运行脚本
ask（默认）	按照下方的逐次询问流程操作

逐次询问流程

1. 不使用 --download-media 运行脚本 → 保存 Markdown
2. 检查已保存的 Markdown 中是否有远程媒体 URL（图片/视频链接中的 https://）
3. 如果没有远程媒体 → 完成，无需询问
4. 如果发现远程媒体 → 使用 AskUserQuestion：
   • 标题：「媒体」，问题：「将 N 张图片/视频下载到本地文件吗？」
   • 「是」— 下载到本地目录
   • 「否」— 保留远程 URL
5. 如果用户确认 → 再次使用 --download-media 运行脚本（覆盖 Markdown，并将链接改为本地路径）

环境变量

变量	描述
URL_CHROME_PATH	自定义 Chrome 可执行文件路径
URL_DATA_DIR	自定义数据目录
URL_CHROME_PROFILE_DIR	自定义 Chrome 配置目录

故障排查：未找到 Chrome → 设置 URL_CHROME_PATH。超时 → 增大 --timeout。复杂页面 → 尝试使用 --wait 模式。

扩展支持

通过 EXTEND.md 使用自定义配置。路径和支持的选项请参阅偏好设置部分。