llm_wiki/wiki/README_Douban_Clipper.md

---
categories:
  - "[[LLM Wiki]]"
tags:
  - wiki
  - reference
  - tool
  - obsidian
created: 2026-04-10
source: "[[README_Douban_Clipper]]"
type: reference
---

# 豆瓣图书 Web Clipper 模板 - 使用指南

> 自动化收集豆瓣图书信息到你的 Obsidian 知识库

---

## 📚 简介

这是一个为 **Obsidian Web Clipper** 设计的豆瓣图书采集模板，可以自动从豆瓣图书页面提取书籍信息，并以符合 [AGENTS.md](AGENTS.md) 规范的格式保存到你的 Obsidian vault 中。

### 主要功能

✅ **自动识别豆瓣图书页面** - URL 触发器自动匹配

✅ **智能字段提取** - 提取书名、作者、ISBN、评分等 13 个字段

✅ **标准 YAML 格式** - 完全符合 Obsidian 和 AGENTS.md 规范

✅ **Markdown 转换** - 内容简介自动转换为 Markdown 格式

✅ **零配置使用** - 导入模板后即可使用

### 提取的字段

| 字段 | 说明 | 类型 |
|------|------|------|
| **categories** | 分类（[[Books]]） | multitext |
| **author** | 作者 | multitext |
| **cover** | 封面图片 URL | text |
| **isbn** | ISBN 号码 | text |
| **scoreGr** | 豆瓣评分 | number |
| **rating_people** | 评分人数 | number |
| **pages** | 页数 | number |
| **year** | 出版年份 | number |
| **publisher** | 出版社 | text |
| **rating** | 你的评分（待填写） | number |
| **translator** | 译者（暂未实现） | multitext |
| **genre** | 类型（暂未实现） | multitext |
| **created** | 创建日期 | date |
| **tags** | 标签（books, references） | multitext |
| **content** | 内容简介 | Markdown |

---

## 🚀 快速开始

### 前置要求

- ✅ Obsidian 应用（版本 ≥ 1.7.2）
- ✅ Microsoft Edge 浏览器（最新版本）
- ✅ Obsidian Web Clipper 扩展

### 安装步骤（5 分钟）

#### 1. 安装 Obsidian Web Clipper

**Windows 11 + Edge 浏览器**：

1. 打开 Microsoft Edge 浏览器
2. 访问：<https://microsoftedge.microsoft.com/addons>
3. 搜索"Obsidian Web Clipper"
4. 点击"获取"按钮安装
5. 安装完成后，工具栏会出现 Web Clipper 图标

#### 2. 连接 Obsidian Vault

1. 打开 Obsidian 应用
2. 点击 Edge 工具栏的 Web Clipper 图标
3. 按照连接向导选择你的 Vault
4. 确认连接成功

#### 3. 导入豆瓣模板

1. 打开 Edge 浏览器
2. 点击 Web Clipper 图标
3. 点击右上角的齿轮图标 ⚙️ 进入设置
4. 点击"Import"按钮
5. 选择文件：`douban-book-clipper.json`
6. 确认导入成功

#### 4. 开始使用

1. 访问任意豆瓣图书页面：<https://book.douban.com/subject/37900003/>
2. 点击 Web Clipper 图标
3. 模板会自动选中（通过 URL 匹配）
4. 预览提取的字段
5. 点击"Save"保存到 Obsidian
6. 完成！✨

---

## 📖 详细使用指南

### 第一次使用

#### 步骤 1：访问豆瓣图书

在 Edge 浏览器中访问任意豆瓣图书页面，例如：

- <https://book.douban.com/subject/37900003/>（年轻医生手记）
- <https://book.douban.com/subject/26954709/>（三体）
- <https://book.douban.com/subject/1292052/>（哈利波特）

#### 步骤 2：打开 Web Clipper

点击 Edge 工具栏中的 Web Clipper 图标（紫色的 Obsidian logo）

#### 步骤 3：自动匹配模板

由于模板中配置了触发器 `https://book.douban.com/subject/`，Web Clipper 会：

1. 检测到当前 URL 匹配
2. 自动选中"Douban Books"模板
3. 显示提取的字段预览

**如果没有自动选中**：
- 手动从模板列表选择"Douban Books"

#### 步骤 4：预览和编辑

在预览面板中，你可以：

✅ **查看提取的字段** - 所有字段都会显示在预览中

✅ **编辑字段值** - 点击任意字段可以修改

✅ **添加个人标签** - 在 tags 字段中添加你的标签

✅ **修改保存路径** - 默认为 `References` 文件夹

✅ **修改文件名** - 默认为 `{{title}}`（书名）

#### 步骤 5：保存到 Obsidian

确认无误后，点击"Save"按钮

Web Clipper 会：

1. 创建新的 Markdown 文件
2. 保存到 `References` 文件夹
3. 文件名为书名（如：`年轻医生手记.md`）
4. 自动应用 Linter 格式化（如果已启用）

#### 步骤 6：验证结果

打开 Obsidian，检查生成的笔记：

- 文件是否在 `References` 文件夹
- YAML frontmatter 是否正确
- 内容是否完整

---

### 日常使用流程

一旦设置完成，日常使用非常简单：

```
访问豆瓣图书 → 点击 Web Clipper → 确认字段 → 保存 ✅
```

**仅需 10 秒！**

---

## 🎯 高级功能

### 自定义保存路径

默认保存路径为 `References`，你可以修改：

1. 在 Web Clipper 中打开模板设置
2. 找到"Path"字段
3. 修改为你想要的路径（如：`Books/Collecting`）

### 自定义文件名

默认文件名格式为 `{{title}}`（书名），你可以修改：

1. 在 Web Clipper 中打开模板设置
2. 找到"Note name format"字段
3. 使用模板变量自定义，例如：

```
{{title}} - {{year}}
{{isbn}}
{{selector:#info|split:"作者:"|slice:1}}
```

**可用变量**：

- `{{title}}` - 页面标题
- `{{date}}` - 当前日期
- `{{url}}` - 页面 URL
- `{{selector:…}}` - 任意选择器

### 添加个人评分

`rating` 字段预留给你填写自己的评分：

1. 在 Web Clipper 预览中
2. 找到 `rating` 字段
3. 输入你的评分（1-7）
4. 保存

评分参考（AGENTS.md）：

- 1 = Evil
- 2 = Very Poor
- 3 = Poor
- 4 = Below Average
- 5 = Average
- 6 = Good
- 7 = Perfect

### 添加个人标签

在 `tags` 字段中添加你的标签：

```
tags:
  - books
  - references
  - to-read
  - fiction
  - 2026
```

---

## 🛠️ 模板配置详解

### 文件结构

```
douban-book-clipper.json
├── schemaVersion    # 模板版本
├── name             # 模板名称
├── behavior         # 行为模式（create）
├── noteNameFormat   # 文件名格式
├── path             # 保存路径
├── noteContentFormat # 内容格式
├── properties       # 字段列表
└── triggers         # URL 触发器
```

### 字段配置详解

#### 1. 基本字段

```json
{
  "name": "categories",
  "value": "[[Books]]",
  "type": "multitext"
}
```

- **name**: 字段名（YAML 键）
- **value**: 字段值（可以使用模板变量）
- **type**: 字段类型
  - `text` - 文本
  - `number` - 数字
  - `multitext` - 多值列表
  - `date` - 日期

#### 2. 使用选择器

```json
{
  "name": "scoreGr",
  "value": "{{selector:.rating_num[property=\"v:average\"]|trim|number}}",
  "type": "number"
}
```

- **selector**: CSS 选择器语法
- **过滤器链**: `|trim|number`
  - `trim` - 去除首尾空格
  - `number` - 转换为数字类型

#### 3. 使用 Meta 数据

```json
{
  "name": "isbn",
  "value": "{{meta:book:isbn}}",
  "type": "text"
}
```

- **meta**: 提取 HTML meta 标签
  - `{{meta:og:image}}` - Open Graph 图片
  - `{{meta:book:isbn}}` - Schema.org ISBN
  - `{{meta:book:author}}` - Schema.org 作者

#### 4. 复杂过滤器链

```json
{
  "name": "year",
  "value": "{{selector:#info|split:\"出版年:\"|slice:1|split:\"<\"|slice:0|split:\"-\"|slice:0|trim}}",
  "type": "number"
}
```

解析流程：

1. `selector:#info` - 获取整个 info 区域的文本
2. `|split:"出版年:"` - 分割，获取"出版年:"之后的部分
3. `|slice:1` - 取第二部分（索引从 0 开始）
4. `|split:"<"` - 按 HTML 标签分割
5. `|slice:0` - 取第一部分（纯文本）
6. `|split:"-"` - 按"-"分割（如：2026-1）
7. `|slice:0` - 取"2026"部分
8. `|trim` - 去除空格

### 触发器配置

```json
"triggers": [
  "https://book.douban.com/subject/"
]
```

- 当访问匹配该 URL 模式的页面时，自动选中此模板
- 支持通配符和正则表达式

---

## 🔧 故障排除

### 问题 1：模板导入失败

**症状**：导入 JSON 文件时报错

**解决方案**：

1. 检查 JSON 文件格式是否正确
2. 确认文件编码为 UTF-8
3. 尝试重新下载模板文件
4. 更新 Web Clipper 到最新版本

---

### 问题 2：某些字段为空

**症状**：预览中某些字段没有值

**可能原因**：
- 豆瓣页面结构变化
- CSS 选择器不匹配
- 字段在特定页面不存在

**解决方案**：

1. 检查豆瓣页面是否有该字段
2. 使用浏览器开发者工具（F12）查看 HTML 结构
3. 更新 CSS 选择器
4. 为该字段添加默认值

---

### 问题 3：笔记保存失败

**症状**：点击保存后没有反应

**解决方案**：

1. 确认 Obsidian 正在运行
2. 重新连接 Vault
3. 检查 `References` 文件夹是否存在
4. 查看 Edge 浏览器控制台（F12）是否有错误

---

### 问题 4：YAML 格式错误

**症状**：Obsidian 显示 YAML 解析错误

**解决方案**：

1. 检查 YAML 语法（冒号后面要有空格）
2. 确保缩进使用空格（不是 Tab）
3. 特殊字符需要用引号包裹
4. 使用 YAML 验证工具检查语法

---

### 问题 5：内容简介包含 HTML 标签

**症状**：Markdown 中残留 `<p>`, `<div>` 等标签

**解决方案**：

1. 检查 `selectorHtml` 选择器是否正确
2. 确认 `markdown` 过滤器在过滤器链中
3. 使用 `replace` 过滤器移除残留标签：
   ```json
   "value": "{{selectorHtml:#link-report .intro|replace:\"</p>\":\"\\n\\n\"|markdown}}"
   ```

---

### 问题 6：多作者显示不正确

**症状**：多作者显示为单行，没有分隔符

**解决方案**：

使用 `join` 过滤器：

```json
{
  "name": "author",
  "value": "{{meta:book:author|replace:\" / \":\", \"}}",
  "type": "multitext"
}
```

或：

```json
{
  "name": "author",
  "value": "{{selector:#info a:first-of-type|join:\", \"}}",
  "type": "multitext"
}
```

---

## 📝 生成的笔记示例

### 完整示例

```markdown
---
categories:
  - "[[Books]]"
author:
  - "［俄］米哈伊尔·布尔加科夫"
cover: "https://img1.doubanio.com/view/subject/s/public/s35336248.jpg"
isbn: "9787549646609"
scoreGr: 9
rating_people: 39
pages: 264
year: 2026
publisher: "文汇出版社"
rating:
translator:
genre:
created: 2026-01-22
tags:
  - books
  - references
---

💉"我们的整个生活就是由这类笑话组成的。"

术业未精、孤立无援、焦头烂额、生死一线……

🌨️在毫无准备之时被抛向命运的暴风雪

一个菜鸟医生的乡村奇遇

🎖️《大师和玛格丽特》作者 布尔加科夫

半自传体短篇小说集 全新中文译本

同名剧集由"哈利·波特"丹尼尔·雷德克里夫主演

冷峻写实×黑色幽默

魔幻之外的布尔加科夫

+++

四十八天前,我以优等成绩从医学院毕业,被派来主管一家乡村医院。可优等成绩是一回事,治病又是另一回事。

截肢、难产、白喉、梅毒,愚昧的巫医术,无知的村民,还有暴风雪里的狼群!命运将我引向黑暗之中,直面危险、恐惧与孤独。寒冬长夜,我思考着自己的职责,写下这些笔记……

+++

【编辑推荐】

"有时候,我真遗憾自己不是个作家。"

❄️《大师和玛格丽特》作者、俄语文学巨匠布尔加科夫半自传性短篇小说集,看见魔幻现实主义之外的布尔加科夫。

毕业于医...
```

---

## 📚 相关文档

- [TESTING.md](./TESTING.md) - 完整的测试步骤指南
- [TEST_REPORT.md](./TEST_REPORT.md) - 测试报告模板
- [AGENTS.md](AGENTS.md) - Obsidian vault 规范文档
- [Obsidian Web Clipper 官方文档](https://help.obsidian.md/web-clipper)
- [kepano/clipper-templates](https://github.com/kepano/clipper-templates) - 官方模板仓库

---

## 🤝 贡献

如果你发现了问题或有改进建议：

1. 查看 [TESTING.md](./TESTING.md) 进行测试
2. 使用 [TEST_REPORT.md](./TEST_REPORT.md) 记录问题
3. 在 GitHub 提交 Issue 或 Pull Request

---

## 📄 许可证

本模板基于 MIT 许可证开源

---

## 🔗 链接

- **Obsidian**: <https://obsidian.md>
- **Obsidian Web Clipper**: <https://github.com/obsidianmd/obsidian-clipper>
- **豆瓣图书**: <https://book.douban.com>

---

**开始构建你的个人图书知识库吧！** 🚀📚