SkillHub

obsidian-save-article

v1.1.0

将网页文章保存到本地 Obsidian Vault，支持图片抓取、Markdown 转换、YAML frontmatter 和用户笔记附加。

Sourced from ClawHub, Authored by liz-npa

Installation

Please help me install the skill `obsidian-save-article` from SkillHub official store. npx skills add liz-npa/obsidian-save-article

Obsidian Save Article

将网页文章保存到本地 Obsidian Vault，支持图片抓取。

触发方式

当用户发送：

  • 一个网页链接
  • 可选的 notes 或 comments
  • 明确要求"保存到 Obsidian"或"收藏文章"

例如：

  • https://example.com/article 这篇文章不错
  • 帮我保存这个：https://xxx.com 内容：我的笔记

首次使用：路径配置

第一次运行时的引导流程

首次使用该技能时，系统会自动检测是否已配置保存路径。如果没有配置，会引导用户完成设置：

🔷 欢迎使用 Obsidian 文章保存功能！

请选择您要保存到的 Obsidian Vault 类型：

1️⃣ 本地 Obsidian（本地磁盘）
2️⃣ iCloud Obsidian（云端同步）

请回复数字或选项名称。

选项 1：本地 Obsidian

如果用户选择本地 Vault：

📂 请告诉我您的 Obsidian Vault 路径。

例如：~/Documents/Obsidian Vault

或者直接拖拽文件夹到聊天窗口，我会自动识别路径。

用户输入路径后，验证路径有效性：

✅ 找到 Vault：My Notes
   路径：/Users/liz/Documents/Obsidian Vault/My Notes

📁 请输入要保存文章的子文件夹名称（可选）。

例如：Articles、ReadLater、收藏夹
直接回车将保存到根目录。

选项 2：iCloud Obsidian

如果用户选择 iCloud Vault：

☁️ iCloud Obsidian 路径查找指南：

1. 打开 Finder
2. 在左侧边栏找到 "iCloud"
3. 点击 "iCloud Drive"
4. 找到您的 Obsidian Vault 文件夹
5. 右键点击 → "复制路径"

请将路径粘贴到聊天中。

用户输入 iCloud 路径后，类似本地流程询问子文件夹。

路径配置存储

配置完成后，路径信息会保存在：

~/.obsidian-save-article-config.json

内容示例：

{
  "type": "local",
  "vault_path": "/Users/liz/Documents/Obsidian Vault/My Notes",
  "subfolder": "Articles",
  "full_path": "/Users/liz/Documents/Obsidian Vault/My Notes/Articles",
  "configured": true,
  "configured_at": "2026-03-18T01:00:00Z"
}

重新配置路径

用户可以随时重新配置路径： - 说"更改 Obsidian 保存路径"或"重新配置" - 说"查看当前保存路径"查看配置

保存格式

YAML Frontmatter

---
title: "文章标题"
url: "原始链接"
created: "YYYY/MM/DD"
pagecomment: "用户添加的页面评论"
---

全文内容

重要：图片必须放在 Full Article callout 内部，位于内容之前！

> [!note]- 📄 Full Article
> ![](images/img-xxxxxx.png)
> ![](images/img-yyyyyy.png)
> 文章第一段内容...
> 文章第二段内容...

错误格式（图片在 callout 外部）：

> ![](images/img-xxxxxx.png)  ← 错误！在 callout 外面
> [!note]- 📄 Full Article
> 文章内容...

正确格式（图片在 callout 内部）：

> [!note]- 📄 Full Article  ← callout 头部先
> ![](images/img-xxxxxx.png)  ← 图片在 callout 内部
> 文章第一段内容...
> 文章第二段内容...

用户 Notes

> 用户笔记内容
^note-xxx

内容抓取方法

该技能支持两种内容抓取方法，系统会自动选择最合适的方式。

方法 1：Jina.ai Reader（首选）

  • 原理：使用 https://r.jina.ai/<URL> 抓取网页内容
  • 优点：快速、返回干净的 Markdown 格式
  • 适用：大多数网站、博客、新闻文章

方法 2：Browser 工具（Fallback）

当 Jina.ai 失败时，自动使用浏览器工具抓取内容。

触发条件： - Jina.ai 返回错误 - Jina.ai 返回空内容或无效内容 - 连接超时 - 网站阻止 Jina.ai 访问（如微信公众号文章、付费内容）

操作步骤： 1. 使用 browser 工具打开目标 URL 2. 获取页面快照（snapshot） 3. 提取页面文本内容 4. 清理和格式化内容

Browser 工具调用示例

# Step 1: 打开页面
browser(action="open", url="https://example.com/article")

# Step 2: 获取快照（使用 aria 模式获取结构化内容）
browser(action="snapshot", snapshotFormat="aria")

# Step 3: 提取文本内容并清理

内容清理规则

从浏览器获取内容后，需要进行清理： - 移除导航栏、页脚、广告等无关内容 - 保留文章标题和正文 - 转换 HTML 标签为 Markdown 格式 - 处理特殊字符和编码问题

工作流程

带路径配置的工作流程

  1. 检查配置：读取 ~/.obsidian-save-article-config.json
  2. 如果未配置 → 触发首次配置流程（见上文）

  3. 如果已配置 → 继续第 2 步

  4. 解析输入：提取 URL 和用户 notes

  5. 抓取内容：

  6. Step 1：优先使用 Jina.ai Reader (https://r.jina.ai/<URL>)
  7. Step 2 (Fallback)：如果 Jina.ai 失败，使用 browser 工具：
    • 执行 browser action=open url="<URL>" 打开页面
    • 执行 browser action=snapshot 获取页面内容
    • 提取文本并清理格式

  8. Step 3：继续图片提取和保存流程

  9. 提取图片：从 HTML 中提取正文图片

  10. 下载图片：调用 download_images.py 保存到配置的 Vault 的 images/ 目录

  11. 转换 Markdown：将图片路径转为本地相对路径

  12. 构建文件：

  13. Frontmatter（标题、URL、日期、评论）
  14. Full Article callout（图片在前，内容在后）

  15. 用户 notes

  16. 保存文件：写入配置的 Vault 路径

路径配置检测逻辑

import os
import json

CONFIG_PATH = os.path.expanduser("~/.obsidian-save-article-config.json")

def load_config():
    """加载配置文件，如果不存在返回 None"""
    if os.path.exists(CONFIG_PATH):
        with open(CONFIG_PATH, 'r') as f:
            return json.load(f)
    return None

def save_config(config):
    """保存配置到文件"""
    with open(CONFIG_PATH, 'w') as f:
        json.dump(config, f, indent=2)

def get_save_path():
    """获取当前配置的保存路径"""
    config = load_config()
    if config and config.get("configured"):
        return config.get("full_path")
    return None

图片下载脚本

调用方式

python ~/.openclaw/workspace/skills/obsidian-save-article/scripts/download_images.py "<URL>" "<Vault子目录路径>"

参数说明： - <URL>：要抓取的网页 URL - <Vault子目录路径>：Obsidian Vault 的路径（脚本会自动在此创建 images/ 子目录）

示例：

# 保存到本地 Vault 的 Articles 文件夹
python ~/.openclaw/workspace/skills/obsidian-save-article/scripts/download_images.py 
  "https://example.com/article" 
  "~/Documents/Obsidian Vault/My Notes/Articles"

# 保存到 iCloud Vault 的 ReadLater 文件夹
python ~/.openclaw/workspace/skills/obsidian-save-article/scripts/download_images.py 
  "https://example.com/article" 
  "~/Library/Mobile Documents/iCloud~com~obsidian~md/Documents/我的 Vault/ReadLater"

返回结果

脚本返回 JSON：

{
  "html": "原始 HTML",
  "images": [["original_url", "local_filename"]],
  "markdown": "转换后的 Markdown"
}

图片处理规则

  • 支持格式：jpg、jpeg、png、gif、webp、svg、bmp
  • 跳过 data:、javascript:、base64 小图
  • 使用 URL 的 MD5 前 12 位作为本地文件名
  • Markdown 中使用相对路径 images/img-xxxx.png

常见问题

Q: 如何查看当前保存路径？

A: 说"查看保存路径"或"我的 Obsidian 配置"

Q: 如何更改保存位置？

A: 说"更改保存路径"或"重新配置"来重新设置

Q: iCloud 路径找不到怎么办？

A: 1. 确保 macOS 已登录 iCloud 2. 打开 Finder → iCloud Drive 3. 找到 Obsidian 文件夹，右键"复制路径"

Q: 图片下载失败怎么办？

A: 文章仍会保存，只是图片位置会保留原始 URL。不影响主要功能。

Q: 什么情况下会使用浏览器抓取？

A: 系统会自动判断。当 Jina.ai 无法使用时，会自动切换到浏览器方式： - 微信公众号文章 - 需要登录的内容 - 阻止爬虫的网站 - 返回空内容的页面

Q: 两种抓取方式有什么区别？

A: | 特性 | Jina.ai Reader | Browser 工具 | |------|----------------|--------------| | 速度 | 快 | 较慢 | | 格式 | 干净 Markdown | 需要清理 | | 适用 | 大多数网站 | 复杂页面 | | 登录 | 不支持 | 可支持 |

注意事项

  • Jina.ai Reader URL 格式：https://r.jina.ai/<原始URL>
  • X 链接使用：https://r.jina.ai/https://x.com/...
  • 当 Jina.ai 失败时，自动使用 browser 工具作为后备方案
  • 微信公众号文章通常需要使用 browser 工具抓取
  • 图片下载失败不应阻断文章保存
  • 文件名中的特殊字符 <>:"|?* 需要替换
  • 页面正文超过 50000 字符时应截断