url-to-obsidian

将任意网址的内容抓取、清理并保存为 Obsidian 笔记。专为技术文档类内容优化（安装指南、使用说明、API 文档、README 等）。

核心工作流

预检查工具链 → 信息收集(URL+名称+位置+翻译) → 智能抓取 → 清理格式化 → 写入笔记 → 验证输出

每步完成后验证结果再进入下一步。关键原则：先检查再执行，避免无效等待；信息不明确时主动询问用户并提供选项。

步骤 0：工具链可用性预检查

在抓取前先检测各工具的可用性，直接选择最高优先级可用工具，避免等待超时后再降级。

检测方法

1. opencli 检测：

   opencli web read --help >/dev/null 2>&1 && echo "AVAIL" || echo "UNAVAIL"
   

   如果返回 "AVAIL"，直接使用 opencli（优先级 1）。

2. 如果 opencli 不可用：跳过 opencli，直接尝试 MCP 工具。MCP 工具通过 ToolSearch 检测：

   • mcp__firecrawl-mcp__firecrawl_scrape → 优先级 2
   • mcp__web-search__fetchWebContent → 优先级 3
   • mcp__fetch__fetch → 优先级 4

3. 告知用户当前使用的工具和原因：

   • 成功检测：使用 opencli 抓取（已检测可用）
   • 降级时：opencli daemon 未运行，降级使用 Firecrawl

如果所有工具都不可用

报告可用工具检测结果，请用户手动粘贴网页内容或检查工具安装状态。

步骤 1：信息收集（三阶段）

从用户消息中提取关键信息：链接地址、笔记名称、存储位置、翻译偏好。信息不完整时主动询问用户，提供合理选项供选择。

1.1 判断已有信息

从用户消息中解析已提供的信息：

快速路径判断：如果用户消息中同时明确提供了 URL + 笔记名称 + 存储位置，直接跳到步骤 2 执行抓取，不进行询问。

1.2 阶段一：确保 URL

URL 已提供 → 进入阶段二。

URL 未提供 → 反问用户：

请提供要保存的网页链接地址。例如：
• 一篇技术文档的 URL
• 一个 GitHub 仓库地址
• 一篇博客文章链接

多个 URL → 逐个处理，每个 URL 独立走完整流程（独立询问名称和位置）。

1.3 阶段二：预抓取 + 目录探测

当用户未同时提供"笔记名称"和"存储位置"时，先做准备工作：

预抓取标题（不做完整翻译和格式化，仅提取标题）：

1. 按步骤 0 检测工具链，选择可用工具
2. 快速抓取网页内容（不执行步骤 3 的完整清理流程）
3. 从抓取内容中提取标题：
   • 匹配第一个 # 标题（Markdown H1）
   • 或从 <title> 标签提取
   • 或从 URL 路径最后一段推断
4. 对标题做基础清理：去除尾部站点名（如 | Example Site）、去除多余空格

索引导航页检测： 在预抓取后，判断当前页面是否为索引导航页（即页面主要内容为子页面链接列表，而非详细文档正文）。满足以下 任意 2 项 即判定为索引导航页：

1. 内容长度 < 3KB（去除 opencli 元数据后）
2. Markdown 链接数量 ≥ 5 个，且链接数占比 > 正文行数的 30%
3. 标题含 "Guides"、"Quickstart"、"目录"、"索引"、"Index" 等导航关键词
4. 正文以链接列表为主，缺少实质性段落描述（段落行数 < 5 行）

索引导航页处理：

• 提取所有子页面链接（同域名下、路径相关的 Markdown 链接）
• 去重后列出供用户选择
• 在步骤 1.4 中额外询问子页面处理方式

存储位置选项生成：

1. 默认提供常用路径作为选项（不扫描 vault）：
   • ~/Obsidian/ 根目录（默认）
   • ~/Obsidian/技术文档/
   • ~/Obsidian/收藏/
2. 仅在用户明确要求（如"帮我看看有哪些目录"、"列出已有的文件夹"）时，才调用 obsidian_list_files_in_vault 探查目录结构

1.4 阶段三：结构化询问

使用 AskUserQuestion 工具一次性询问用户。根据阶段二的探测结果动态生成选项。

问题 1：笔记名称（如果用户未指定名称）

问题 2：存储位置（如果用户未指定位置）

问题 3：是否翻译为中文（始终询问，除非用户在消息中已明确指示）

问题 4：子页面处理（仅在步骤 1.3 检测到索引导航页时询问）

当预抓取判定为索引导航页时，列出检测到的子页面链接数量，询问用户如何处理：

选项 1「合并到同一笔记」的后续流程：

• 用户选择后，立即列出检测到的子页面链接，用 AskUserQuestion（multiSelect）让用户勾选要抓取的子页面
• 默认全部选中，用户可取消勾选不需要的子页面
• 子页面数量 ≤ 8 时直接列出全部；> 8 时仅展示前 8 项 + "全部选中"选项
• 确认选择后进入步骤 2 开始抓取主页面 + 所有选中的子页面

选项 2「保存为独立笔记」的后续流程：

• 同选项 1，先让用户勾选要保存的子页面
• 每个子页面独立走完整流程（独立 frontmatter、标签、来源信息）
• 文件名默认使用子页面标题，用户可通过 AskUserQuestion 确认/修改

AskUserQuestion 调用示例（含索引导航页检测）：

问题1 header: "笔记名称"
  - "React 18 安装与使用指南"（根据网页标题生成，推荐）
  - "react-installation-guide"（根据 URL 路径推断）
  - "自定义名称..."
问题2 header: "存储位置"
  - "~/Obsidian/ 根目录"（默认）
  - "~/Obsidian/React 文档/"（已有目录）
  - "自定义目录..."
问题3 header: "翻译选项"
  - "保留原文不翻译"（默认）
  - "翻译为简体中文"

--- 以下仅在检测到索引导航页时出现 ---

问题4 header: "子页面处理"
  - "合并到同一笔记"（推荐）-- 子页面内容追加到主笔记
  - "保存为独立笔记" -- 每个子页面单独一个文件
  - "仅保存当前页面" -- 只保存概览索引

--- 选择合并或独立后，进一步勾选子页面 ---

问题5 header: "选择子页面"（multiSelect）
  - "全部子页面 (5个)"（推荐）
  - "命令行方式"
  - "Docker 方式"
  - "Maven 方式"
  - "Gradle 方式"
  - "Desktop 方式"

注意：

• 如果用户已指定了名称，问题 1 跳过，只问位置和翻译
• 如果用户已指定了位置，问题 2 跳过，只问名称和翻译
• 如果用户在消息中已明确指示翻译偏好（如"翻译成中文"、"不用翻译"），问题 3 跳过
• 如果未检测到索引导航页，问题 4 跳过（不询问用户）
• 如果用户在消息中已指示子页面处理方式（如"合并子页面"、"单独保存"、"只要主页面"），问题 4 跳过
• 三者都已指定 → 快速路径，不询问直接执行
• 子页面处理必须遵循：当用户选择合并或独立保存子页面后，必须先询问用户勾选哪些子页面（用 multiSelect），不要自作主张全部抓取

1.5 信息确认

询问完成后，向用户展示确认摘要：

确认信息：
  🔗 链接：https://example.com/doc
  📝 笔记名称：React 18 安装指南
  📁 存储位置：~/Obsidian/React 文档/
  🌐 翻译：保留原文 / 翻译为简体中文
  📑 子页面：合并到同一笔记（3个子页面） / 独立笔记（3个） / 不抓取

然后进入步骤 2 开始抓取。

步骤 2：抓取网页内容（智能降级链）

按预检查结果选择工具。以下为完整优先级表：

优先级 1：opencli web read（推荐）

opencli web read --url "<url>" --stdout

• 优势：支持 JS 渲染、输出干净 Markdown、处理 SPA 页面
• 前提：opencli daemon 运行 + Chrome 扩展已连接（opencli doctor 绿色）
• 额外参数（按需使用）：
  • --wait <秒> — 页面加载后额外等待（默认 3 秒，内容多的页面可设为 5-8 秒）
  • --wait-for "<CSS选择器>" — 等待特定元素出现后再抓取
  • --wait-until networkidle — 等待网络空闲
• 降级条件：daemon 未运行、扩展未连接、命令执行超时、返回错误
• 降级时记录原因：如 opencli daemon 未运行，自动降级到 Firecrawl

优先级 2：Firecrawl scrape

使用 ToolSearch 加载 mcp__firecrawl-mcp__firecrawl_scrape，然后调用：

url: "<url>"
formats: ["markdown"]
onlyMainContent: true

• 优势：功能全面、支持 JS 渲染（waitFor 参数）、自动提取主体内容
• 降级条件：MCP 工具不可用、API 配额耗尽、返回错误
• 降级时记录原因

优先级 3：fetchWebContent

使用 ToolSearch 加载 mcp__web-search__fetchWebContent，然后调用：

url: "<url>"
readability: true
maxChars: 50000

• 优势：轻量级，适合静态文档页面
• 限制：不支持 JS 渲染
• 降级时记录原因

优先级 4：fetch（兜底）

使用 ToolSearch 加载 mcp__fetch__fetch，然后调用：

url: "<url>"
max_length: 10000

• 限制：仅返回简化内容，上限 10000 字符
• 全部失败：报告错误（列出失败原因），询问用户是否手动提供内容

特殊情况：GitHub URL

如果 URL 匹配 github.com/*/*（仓库 README 页面），跳过降级链，直接使用：

使用 ToolSearch 加载 mcp__web-search__fetchGithubReadme，然后调用。

如果 fetchGithubReadme 不可用，再走正常降级链。

步骤 2.5：子页面抓取与合并（按需执行）

仅在步骤 1 中用户选择了「合并到同一笔记」或「保存为独立笔记」时执行此步骤。

2.5.1 并行抓取子页面

对用户勾选的所有子页面，使用与主页面相同的工具链并行抓取。所有子页面抓取命令使用相同工具参数，并行发起以节省时间。

注意：

• 子页面抓取使用与主页面相同的工具（已通过步骤 0 预检查）
• 如果某个子页面抓取失败（如 404），跳过该子页面，在最终报告中标注
• 抓取超时设置与主页面一致

2.5.2 子页面内容清理

对每个子页面的抓取内容进行与步骤 3 相同的清理：

• 去除 opencli 元数据头
• 去除页面噪音（Page last updated、版权信息、论坛链接等）
• 提取子页面标题作为章节名

2.5.3 合并模式：追加到主笔记

当用户选择「合并到同一笔记」时：

1. 先保存主页面内容（概览索引部分）
2. 每个子页面作为一个 H2 章节追加，格式：

   ---
   
   ## 子页面标题
   
   > 来源：[原始子页面标题](子页面URL)
   
   子页面正文内容...
   

3. 章节排序：子页面按用户勾选顺序或字母顺序排列
4. 来源标注：每个子章节上方用 > 引用块标注子页面原始链接
5. 分隔线：章节间用 --- 分隔线区分
6. 标签合并：主笔记的 tags 合并所有子页面的关键标签（去重）

合并模式示例结构：

# 主标题

> [!note]- 来源信息
> - **URL**: 主页面URL

## 概述
主页面的概览内容...

---

## 命令行方式

> 来源：[Quickstart - Command-line](子页面URL)

子页面正文内容...

---

## Docker 方式

> 来源：[Quickstart - Docker](子页面URL)

子页面正文内容...

2.5.4 独立笔记模式：逐个保存

当用户选择「保存为独立笔记」时：

• 每个子页面独立走步骤 3→4→5 完整流程
• 每个独立笔记有完整的 frontmatter、来源信息、标签
• 主页面笔记保留概览索引 + 指向独立笔记的 Obsidian wikilink：[[子页面笔记名称]]

独立笔记模式下的主页面优化： 主页面笔记中的链接列表替换为 Obsidian wikilink 格式，方便 Obsidian 内跳转：

## 快速开始指南

- [[Flyway 命令行快速开始]]
- [[Flyway Docker 快速开始]]
- [[Flyway Maven 快速开始]]

2.5.5 部分失败处理

如果部分子页面抓取失败：

• 合并模式：跳过失败的子页面，在对应位置标注 > [!warning] 子页面抓取失败：[URL]
• 独立笔记模式：不创建失败的子页面笔记，在主页面中保留原始链接（不转 wikilink）
• 最终报告中列出成功/失败数量

步骤 3：内容清理与格式化

3.1 提取标题

按优先级尝试：

1. 从抓取内容中匹配第一个 # 标题（Markdown H1）
2. 从内容开头提取 <title> 标签文本
3. 从 URL 路径最后一段推断（去除扩展名、替换连字符为空格）
4. 如果以上都失败，使用域名作为标题

标题清理规则：

• 去除尾部站点名（如 | Example Site、 - Blog Name）
• 去除多余空格和特殊符号（如 ®、™）
• 限制 120 字符

3.2 内容清理

• 去除冗余元数据：移除抓取工具添加的元数据头（如 opencli 的 # 站点名\n> 作者: ...\n> 原文链接: ... 块）
• 去除页面噪音：移除网页中残留的交互标签和导航残留，包括但不限于：
  • Copy link、复制链接 等复制按钮文字
  • Terminal、bash、text、css、tsx 等单独成行的代码块标签（保留代码块内的语言标记如 ```bash）
  • 底部导航菜单链接（如页脚"Docs | Components | Blog"等）
  • 社交媒体链接列表
• 去除重复标题：如果内容第一行 H1 与提取的标题相同，保留一个即可
• 保留代码块：确保 ``` 代码块完整，语法高亮标记不丢失
• 保留表格：Markdown 表格格式保持
• 链接处理：相对链接转为绝对链接（基于原始 URL 的 base）
• 去除广告：如果内容包含明显的广告文本，尽量清理

3.3 边界感知截断

对大内容按边界截断，避免破坏 Markdown 结构：

截断后添加标记：

> [!warning] 内容过长已截断
> 原始约 X KB，保存约 Y KB。完整内容请访问原始 URL: <url>

禁止在以下位置截断：代码块内部、表格中间、列表中间。

3.4 技术文档优化

识别到技术文档特征时（包含代码块、命令行示例、API 端点等）：

• 确保 bash、shell、json、yaml 等代码块语言标记正确
• 保留安装命令的完整性（npm install、pip install、brew install、git clone 等）
• 如内容包含步骤编号（1. 2. 3.），保持其格式

3.5 中文化翻译（按需执行）

仅在步骤 1 中用户选择了"翻译为简体中文"时才执行此步骤。默认保留原文不翻译。

翻译原则：

翻译质量标准：

• 使用自然流畅的中文表达，避免生硬的直译
• 技术术语保持英文（如 CSS、API、CLI），但上下文用中文说明
• 代码块上方的描述性标签（如 globals.css、app/page.tsx）保留原样，下方的说明文字翻译
• 章节标题简洁有力，如 "Getting Started" → "快速开始"，"Install" → "安装"

步骤 4：确定存储位置与文件名

4.1 文件名

直接使用步骤 1 中用户确认的笔记名称作为文件名。

安全处理（对用户输入做基本清理）：

1. 移除非法字符：/ : \ * ? " < > |
2. 去除首尾空格和点号
3. 如果处理后为空，使用 未命名-<时间戳>

命名风格：保留中文和英文混合，不强制翻译。尊重用户的选择。

4.2 存储位置

直接使用步骤 1 中用户选择的存储位置：

默认：~/Obsidian/<用户指定名称>.md
指定目录：~/Obsidian/<用户选择的目录>/<用户指定名称>.md
自定义路径：~/Obsidian/<用户自定义路径>/<用户指定名称>.md

• 目录不存在时自动创建（使用 mkdir -p）
• 用户选择"存档模式"时 → 保存到 .raw/articles/<文件名>-<YYYY-MM-DD>.md

4.3 冲突处理

如果目标文件已存在：

1. 比较内容是否相同（相同则跳过）
2. 内容不同时，询问用户选择：
   • 覆盖：替换原文件
   • 追加：在现有文件末尾添加新内容，用 --- 分隔
   • 重命名：文件名加 -2、-3 后缀
   • 归档：保存到 .raw/articles/<slug>-<日期>.md，原文件不动
   • 跳过：不保存

步骤 5：生成并保存笔记

5.1 笔记模板

标准技术文档模板（翻译状态取决于用户选择）：

---
title: "<中文标题>"
source: "<原始URL>"
created: <YYYY-MM-DD>
fetch_tool: "<opencli | firecrawl | fetchWebContent | fetch | fetchGithubReadme>"
tags:
  - web-clip
  - <域名标签>
  - <内容标签1>
  - <内容标签2>
---

# <中文标题>

> [!note]- 来源信息
> - **URL**: <原始URL>
> - **抓取时间**: <YYYY-MM-DD>
> - **抓取工具**: <工具名>

<中文正文内容>

GitHub README 模板（fetch_tool 为 fetchGithubReadme 时）：

---
title: "<仓库名> - <描述（翻译为中文）>"
source: "<GitHub URL>"
created: <YYYY-MM-DD>
fetch_tool: "fetchGithubReadme"
tags:
  - web-clip
  - github
  - readme
  - <语言标签>
---

# <仓库名>

> [!note]- 来源信息
> - **仓库**: <GitHub URL>
> - **抓取时间**: <YYYY-MM-DD>
> - **抓取工具**: fetchGithubReadme

<README 正文（翻译为中文）>

排版简洁原则：

• 正文直接从 H2 章节开始，无引言段落
• 章节标题简洁（2-6 字），如"安装"、"快速开始"、"示例应用"
• 不保留"内容大小"字段（已在来源信息中体现）
• 来源信息使用折叠 callout（[!note]-），默认收起减少视觉干扰

5.2 标签自动生成规则

• 必加标签：web-clip
• 来源域名标签（从 URL 域名推断）：

• 内容关键词标签（从标题和内容提取，最多 5 个）：
  • 技术名词：如 react、api、docker、cli、kubernetes
  • 文档类型：tutorial、installation、guide、reference、readme、changelog
  • 编程语言：javascript、python、rust、go、typescript
• 用户自定义标签：如果用户指定了标签（如"标签：docker, tutorial"），追加到列表

5.3 frontmatter 格式规范（强制执行）

严格遵循 Obsidian YAML frontmatter 格式，这是不可协商的规则：

• ✅ 标签必须用多行列表格式：

  tags:
    - web-clip
    - docker
  

• ❌ 禁止 inline 格式：tags: [web-clip, docker] ← 绝对不会使用
• ✅ 日期格式：YYYY-MM-DD（如 2026-07-02）
• ❌ 禁止 ISO datetime：2026-07-02T00:00:00Z ← 错误格式
• ✅ 值包含特殊字符时加引号：title: "包含:冒号的标题"
• ✅ 纯平 YAML，不允许嵌套对象
• ✅ fetch_tool 字段：记录使用的抓取工具，便于追溯

5.4 写入操作与验证

写入：使用 Write 工具直接写入绝对路径：

Write: ~/Obsidian/<目录>/<文件名>.md

写入后验证（必须执行）：

1. 使用 Read 回读文件的前 20 行，检查：
   • tags: 字段是否使用了多行列表格式（绝对不能是 inline [a, b]）
   • created: 日期格式是否为 YYYY-MM-DD
   • source: 和 fetch_tool: 字段是否存在
   • 来源信息 callout 是否完整
2. 如果验证失败，使用 Edit 工具修正格式，再次验证
3. 检查文件大小是否合理（不为空、不被意外截断）

步骤 6：执行后输出

完成后向用户报告：

✅ 笔记已创建：~/Obsidian/<目录>/<文件名>.md
   - 标题：<标题>
   - 来源：<URL>
   - 抓取工具：<工具名><降级说明>
   - 内容大小：<约 X>KB

多 URL 时汇总报告所有结果（成功/失败/跳过的数量和详情）。

错误处理一览

与其他技能的关系

• claude-obsidian:save：保存当前对话，本技能保存外部网页
• claude-obsidian:wiki-ingest：深度知识整合（提取实体/概念/交叉引用）。互补用法：
  • 快速存档 → url-to-obsidian
  • 深度整合 → 先用 url-to-obsidian 保存到 .raw/articles/，再 wiki-ingest 处理
• claude-obsidian:defuddle：如 defuddle-cli 已安装，可在步骤 3 可选使用
• claude-obsidian:obsidian-markdown：本技能遵循其 wikilinks、callouts、frontmatter 规范
• opencli-usage：了解 opencli 全局标志和适配器发现

注意事项

• 务必在保存前使用 AskUserQuestion 收集确认笔记名称和存储位置（除非用户已在消息中明确提供）
• 务必提供合理的默认选项（标题建议名称 + 常用目录），确保用户可一键确认不过度负担
• 务必提供合理的默认存储路径（~/Obsidian/ 根目录 + 常用子目录），仅在用户明确要求时才扫描 vault 目录结构
• 如果 obsidian MCP 工具不可用，使用固定常用路径列表作为降级方案并告知用户
• 不要在步骤 1 已经提供了名称/位置的情况下重复询问（快速路径）
• 绝对不要在 frontmatter 中使用 inline 列表（tags: [a, b]），始终用多行格式
• 绝对不要在 frontmatter 中使用嵌套对象，保持纯平 YAML
• 绝对不要在代码块或表格中间截断内容
• 绝对不要在用户未选择翻译的情况下自动翻译内容——翻译必须是用户明确选择后的行为
• 务必在步骤 1 的 AskUserQuestion 中提供"保留原文"和"翻译为中文"两个选项，默认"保留原文"
• 务必在写入后回读验证 frontmatter 格式
• 务必在预检查阶段确定可用工具链，避免无效等待
• 务必告知用户降级发生时使用的具体工具和原因
• 务必清理页面噪音：去除 "Copy link"、代码块标签、导航页脚等残留
• 不要修改 Obsidian vault 中已有的不相关文件
• 不要对非 GitHub 的 URL 使用 fetchGithubReadme
• 不要创建空的笔记文件
• 不要保留冗余的引言段落，正文直接从 H2 章节开始
• 务必在预抓取阶段检测页面是否为索引导航页，并据此询问用户子页面处理方式
• 务必在用户选择合并或独立保存子页面后，让用户勾选具体子页面（不要自作主张全部抓取）
• 务必在合并模式中为每个子章节标注来源链接（> 来源：[原标题](URL)）
• 务必在合并模式中用 --- 分隔不同子页面内容
• 不要在用户未确认子页面选择前就开始抓取子页面