url-to-markdown

URL 转 Markdown

概述

使用此技能抓取公开 URL，将其转换为 Markdown，并保存为带时间戳的 Markdown 文件，供 Agent 后续使用。

转换优先级固定：

1. https://r.jina.ai/<url>（主要方式）
2. https://markdown.new/（仅在 r.jina.ai 不可用时作为备用方式）

此技能以执行为导向。优先运行随附脚本，而非手动重现工作流。

使用场景

用户提出以下任一需求时，使用此技能：

• 将 URL 或网页转换为 Markdown
• 将文章、文档页面或博客文章保存为 .md
• 获取公开网页内容，以供后续摘要或提取
• 将页面内容保留为便于机器处理的文本格式
• 将文档页面导入本地 Markdown 文件

以下情况不要使用此技能：

• 需要通过浏览器登录的私有页面
• 用户无权访问的网站
• 需要抓取整个网站，而非仅获取单个页面的任务

输入

运行脚本前，确定以下输入：

• url：必填（单 URL 模式）；必须是公开 URL
• urls：可选；用于批量转换多个 URL（与位置参数 url 互斥）
• concurrency：可选；并行转换数量（默认 3）；用于批量模式
• output_dir：可选；批量转换的输出目录；会创建基于 slug 的文件名
• method：可选；取值为 auto、ai、browser 之一；默认 auto；用于 markdown.new 备用方式
• retain_images：可选；默认 false；用于 markdown.new 备用方式
• transport：可选；取值为 auto、get、post 之一；默认 auto；用于 markdown.new 备用方式
• timeout：可选；默认 30
• force_markdown_new：可选；默认 false；为 true 时，跳过 r.jina.ai，直接调用 markdown.new
• output：默认 ./output/（当前目录下的 output/）；如果用户在提示词中明确提供输出路径，则使用该路径

如果用户未指定这些选项，保留默认值。

输出路径规则：

• 调用 url_to_md.py 时始终传入 --output。
• 如果用户提示词明确指定输出路径，则使用该路径。
• 否则使用 --output "output/"（相对于当前工作目录）。

运行脚本

在技能目录中运行：

python scripts/url_to_md.py "<url>" --output "output/"

常见变体：

python scripts/url_to_md.py "<url>" --output "output/"
python scripts/url_to_md.py "<url>" --method browser --retain-images --output "output/"
python scripts/url_to_md.py "<url>" --transport post --timeout 45 --output "output/"
python scripts/url_to_md.py "<url>" --force-markdown-new --output "output/"
python scripts/url_to_md.py "<url>" --output "<user_explicit_path>"

批量转换：

# Batch convert multiple URLs with parallel processing (default concurrency=3)
python scripts/url_to_md.py --urls "https://example.com" "https://example.org" "https://example.net" --output-dir "output/"

# Batch with custom concurrency
python scripts/url_to_md.py --urls "https://a.com" "https://b.com" "https://c.com" "https://d.com" "https://e.com" --concurrency 5 --output-dir "output/"

# Single URL in batch mode
python scripts/url_to_md.py --urls "https://example.com" --output-dir "output/"

行为说明：

• 脚本始终先尝试 r.jina.ai。
• 如果设置了 --force-markdown-new，脚本会跳过 r.jina.ai，直接使用 markdown.new。
• 仅当 r.jina.ai 不可用时，才会回退到 markdown.new（例如超时、网络故障、5xx 或速率限制）。
• 技能级默认输出目录为 ./output/，调用时始终应包含 --output。
• 如果 --output 是文件名，脚本会在扩展名前追加时间戳。
• 如果 --output 是目录，脚本会创建基于 slug 且带时间戳的文件名。

必需的输出行为

优先同时提供：

1. 已保存的 Markdown 文件。
2. 简短的对话摘要。

摘要应包含：

• 来源 URL
• 转换是否成功
• 使用的提供方：r.jina.ai 或 markdown.new
• 保存的文件路径（如果已写入文件）
• 使用的非默认关键选项：method、retain_images、transport、timeout

摘要模板

使用以下结构：

Source URL: <url>
Status: success
Provider: <r.jina.ai|markdown.new>
Saved Markdown: <path>
Options: method=<value>, retain_images=<value>, transport=<value>, timeout=<value>

如果使用了默认值，Options 部分应简洁。

错误处理

如果脚本失败：

• 说明 URL 转 Markdown 转换失败
• 简要说明主要错误
• 不要编造页面内容
• 明显时提及可能的原因：网络问题、超时、速率限制或不支持的页面访问

如果两个提供方都失败，说明哪个提供方先失败、哪个最后失败。 如果服务返回速率限制，直接报告，不要声称重试成功。

备注

• 优先使用保存的 Markdown，而不是原始标准输出，因为 Agent 可以更可靠地重复使用本地文件。
• 随附脚本仅使用 Python 标准库。
• 该脚本既支持导入使用，也支持通过 CLI 执行，但此技能通常应使用 CLI 方式。