README file from
GithubBangumi Sync
把 Bangumi 收藏、观看进度和个人数据同步到 Obsidian，并保留可自定义的 Markdown 与 frontmatter。
安装 · 快速开始 · 模板指南 · 版本与更新 · 问题反馈
为什么使用 Bangumi Sync
- 将动画、游戏、书籍、音乐和三次元收藏保存为本地 Markdown。
- 同步评分、短评、标签、收藏状态和单集进度。
- 使用模板控制路径、frontmatter、正文和本地自定义属性。
- 支持增量同步、强制同步、状态同步、搜索添加和批量编辑。
- 导入、导出个人数据，保留本地记录和自定义字段。
- 通过事务回滚和 Recovery Center 保护同步期间的本地文件。
效果预览
同步后的条目以 Markdown 和 frontmatter 保存在 Vault 中；默认模板可配合 Dataview 展示封面、条目信息与观看进度。
安装
GitHub Release
- 打开 GitHub Releases。
- 下载同一版本的
main.js、manifest.json和styles.css。 - 将三个文件放入
你的Vault/.obsidian/plugins/bangumi-sync/。 - 在 Obsidian 的“社区插件”设置中启用 Bangumi Sync。
也可以使用 BRAT 安装仓库 threeyang3/bangumi-sync。
从源码构建
git clone https://github.com/threeyang3/bangumi-sync.git
cd bangumi-sync
npm ci
npm run build
构建产物位于 release/。开发环境和贡献流程见开发指南。
快速开始
1. 准备 Dataview
默认模板使用 Dataview 内联查询。请先安装并启用 Obsidian Dataview；否则表格可能显示原始查询文本。
2. 获取 Access Token
打开 Bangumi Access Token 页面，生成并复制 Token。不要把 Token 写入模板、截图、Issue 或日志。
3. 配置插件
在 Obsidian 设置中打开 Bangumi Sync：
- 粘贴 Access Token。
- 设置条目扫描目录和路径模板，例如
ACGN/{{type}}/{{name_cn_with_type}}.md。 - 为需要的条目类型选择模板。
- 按需配置封面下载和用户数据保护。
4. 同步第一批条目
- 点击左侧 Ribbon 的数据库图标，或运行“同步 Bangumi 收藏”。
- 选择条目类型、收藏状态和数量。
- 在预览中勾选条目；模板定义了本地属性时可在此填写。
- 点击“只导入选中的”。
常用功能
| 功能 | 用途 |
|---|---|
| 同步 Bangumi 收藏 | 预览并选择要导入的收藏 |
| 快速同步 | 使用默认条件增量同步 |
| 控制面板 | 筛选收藏、打开文件、同步和批量编辑 |
| 搜索条目 | 搜索、收藏并创建本地条目 |
| 检查并同步状态 | 对比本地与云端评分、短评、标签、状态和进度 |
| 批量下载封面 | 下载封面并更新 Markdown 引用 |
| 导入 / 导出用户数据 | 备份和恢复本地字段及正文内容 |
| 创建或追加条目笔记 | 将相关条目的笔记汇聚到共享文件 |
普通同步会按 Bangumi Subject ID 识别条目。只要文件仍在扫描目录中并保留有效 id，你可以手工重命名文件，插件不会仅凭标题重新创建副本。
模板与自定义属性
模板决定文件路径、frontmatter 和正文。常用变量包括：
| 变量 | 含义 |
|---|---|
{{id}} |
Bangumi Subject ID |
{{type}} / {{category}} |
条目类型与细分类别 |
{{name}} / {{name_cn}} |
原名与中文名 |
{{name_cn_with_type}} |
带类型消歧的中文名 |
{{my_rate}} / {{my_status}} |
个人评分与收藏状态 |
{{my_comment}} / {{my_tags}} |
短评与个人标签 |
{{cover}} / {{related}} |
封面与相关条目 |
普通 frontmatter 字段可作为本地自定义属性：
剧情评分:
资源属性: []
已购: false
完整变量表、条件语法、默认值、字段类型和模板来源以模板指南为准。
数据安全
Bangumi Sync 使用持久恢复日志保护本地文件事务。异常中断或回滚不完整时，插件会暂停新的写入，并通过 Recovery Center 引导恢复。
遇到恢复提示时：
- 先停止新的同步和批量编辑。
- 不要直接删除未知的
.bangumi-sync-recovery*或.bangumi-sync-*.tmp.md文件。 - 按 Recovery Center 显示的按钮操作，必要时先备份 Vault。
常见问题
为什么扫描不到条目？
确认 Markdown frontmatter 中存在有效的 id，且文件位于配置的扫描目录内。路径与身份规则见身份与路径模型。
强制同步会覆盖本地数据吗？
插件会按设置保留本地自定义属性以及正文中的记录和感想。执行大范围强制同步前仍建议导出用户数据。
同名作品如何保存？
无冲突时使用简洁名称；发生规范化路径冲突时依次使用年份和 Bangumi ID 消歧。后续加入第三个同名条目时，插件会按已保存的碰撞组信息统一重规划 managed 路径；手工重命名的文件不会被移动。Subject ID 始终是身份，文件名不是身份。
修改路径模板会自动移动旧文件吗？
不会。先运行本地诊断，再使用路径迁移预览显式确认。升级与迁移步骤见迁移指南。
图片下载失败怎么办？
检查图片路径模板、目录权限和网络。若 Recovery Center 同时出现，先完成恢复，不要反复重试写入操作。
文档导航
- 文档索引：按普通用户、高级用户、维护者和历史资料导航。
- 模板指南：模板系统的完整用户参考。
- 迁移指南：升级、改模板、改路径和 legacy recovery 处理。
- 恢复指南：Recovery Center 操作手册。
- 架构：模块职责和数据流。
- 开发指南：环境、测试、PR 和发布流程。
版本与更新
- GitHub Releases：下载稳定版并查看每个版本的完整发布说明。
- 版本历史：浏览各版本重点和历史索引。
版本信息与项目介绍分开维护；已发布内容以 GitHub Releases 为准。
开发与贡献
Canonical package manager 是 npm。提交前至少运行：
npm ci
npm run lint
npm run test
npm run build
git diff --check
请从独立 feature、fix 或 docs 分支提交 Pull Request，不要直接把未审查修改发布为稳定版。
相关链接
支持开发
许可证
MIT License