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 访问（如微信公众号文章、付费内容）

操作步骤：

使用 browser 工具打开目标 URL
获取页面快照（snapshot）
提取页面文本内容
清理和格式化内容

Browser 工具调用示例

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

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

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

内容清理规则

从浏览器获取内容后，需要进行清理：

移除导航栏、页脚、广告等无关内容
保留文章标题和正文
转换 HTML 标签为 Markdown 格式
处理特殊字符和编码问题

工作流程

带路径配置的工作流程

检查配置：读取 ~/.obsidian-save-article-config.json
- 如果未配置 → 触发首次配置流程（见上文）
- 如果已配置 → 继续第 2 步
解析输入：提取 URL 和用户 notes
抓取内容：
- Step 1：优先使用 Jina.ai Reader (https://r.jina.ai/<URL>)
- Step 2 (Fallback)：如果 Jina.ai 失败，使用 browser 工具：
  - 执行 browser action=open url="<URL>" 打开页面
  - 执行 browser action=snapshot 获取页面内容
  - 提取文本并清理格式
- Step 3：继续图片提取和保存流程
提取图片：从 HTML 中提取正文图片
下载图片：调用 download_images.py 保存到配置的 Vault 的 images/ 目录
转换 Markdown：将图片路径转为本地相对路径
构建文件：
- Frontmatter（标题、URL、日期、评论）
- Full Article callout（图片在前，内容在后）
- 用户 notes
保存文件：写入配置的 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 路径找不到怎么办？

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

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

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

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

A: 系统会自动判断。当 Jina.ai 无法使用时，会自动切换到浏览器方式：

微信公众号文章
需要登录的内容
阻止爬虫的网站
返回空内容的页面

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

特性	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 字符时应截断