Phase 0-2: Schema cleanup, typed relations, event-driven automation

- Phase 0: AGENTS.md cleanup (dedup quotes, renumber sections, merge qmd) - Phase 1: typed relations (manage-relations.py, graph-search.py, check-staleness.py, detect-conflicts.py) - Phase 2: frontmatter validator, weekly lint, knowledge promotion, git hooks - Fix .gitignore to track tools/ and .githooks/ - Fix git remote URL (remove plaintext token) - New wiki pages: 504 pages, 34 raw sources
2026-07-01 08:05:43 +08:00
parent e544d6e04a
commit a6f05ab2d5
1067 changed files with 522992 additions and 819 deletions
@@ -0,0 +1,543 @@
+---
+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>
+
+---
+
+**开始构建你的个人图书知识库吧！** 🚀📚