Bangumi Sync

把 Bangumi 收藏、观看进度和个人数据同步到 Obsidian，并保留可自定义的 Markdown 与 frontmatter。

安装 · 快速开始 · 模板指南 · 版本与更新 · 问题反馈

为什么使用 Bangumi Sync

• 将动画、游戏、书籍、音乐和三次元收藏保存为本地 Markdown。
• 同步评分、短评、标签、收藏状态和单集进度。
• 使用模板控制路径、frontmatter、正文和本地自定义属性。
• 支持增量同步、强制同步、状态同步、搜索添加和批量编辑。
• 导入、导出个人数据，保留本地记录和自定义字段。
• 通过事务回滚和 Recovery Center 保护同步期间的本地文件。

效果预览

同步后的条目以 Markdown 和 frontmatter 保存在 Vault 中；默认模板可配合 Dataview 展示封面、条目信息与观看进度。

安装

GitHub Release

1. 打开 GitHub Releases。
2. 下载同一版本的 main.js、manifest.json 和 styles.css。
3. 将三个文件放入 你的Vault/.obsidian/plugins/bangumi-sync/。
4. 在 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：

1. 粘贴 Access Token。
2. 设置条目扫描目录和路径模板，例如 ACGN/{{type}}/{{name_cn_with_type}}.md。
3. 为需要的条目类型选择模板。
4. 按需配置封面下载和用户数据保护。

默认仅输出批次摘要、警告和错误。排查问题时，可在插件设置的“高级”页启用“详细诊断日志”，查看逐条目和请求信息；关闭后立即停止这些详细输出。请求正文不会输出，诊断完成后建议关闭此开关。

4. 同步第一批条目

1. 点击左侧 Ribbon 的数据库图标，或运行“同步 Bangumi 收藏”。
2. 选择条目类型、收藏状态和数量。
3. 在预览中勾选条目；模板定义了本地属性时可在此填写。
4. 点击“只导入选中的”。

同步进度按阶段显示资料加载、路径规划、内容生成、文件写入、恢复日志收尾与关联链接补全。阶段中的计数表示已处理的项目（包含失败），不是整个同步的完成百分比；最终成功与失败数量以结果为准。日志收尾、补链或等待用户决策时，总工作量未确定则不显示百分比。

结果中的“正式执行耗时”统计本次执行中的资料准备、写入、日志收尾和补链，不包含预览前加载及等待确认。对部分成功或取消的批次，后续点击保留/回滚的处理耗时单独显示，等待用户操作的时间不计入。

预览前的详情加载使用同步并发设置（1–5，默认 3）。同一次预览成功获取的完整详情会在导入时复用；失败或超时可使用收藏简版信息完成预览，导入时重新获取完整详情。缓存仅属于本次操作，取消、完成、插件卸载或账号变更后失效；预览期间修改同步配置后需重新发起同步。

关联链接在主事务提交后按目标文件整批合并，保留已有链接和正文，内容无变化时跳过修改。补链失败会记入警告，不撤销已提交的文件；部分成功批次在选择保留后补链，选择回滚则不补链。补链中取消会停止余下补链并显示已取消，已提交的文件仍会保留。

同步按实际生效的模板获取角色、制作公司兜底及章节显示所需资料，完整条目详情仍用于路径与模板。启用关联链接时仍会获取关联资料供补链使用。Bangumi API 请求共用并发上限，避免每个条目的多类请求各自占满并发；模板依赖说明见模板指南。

常用功能

普通同步会按 Bangumi Subject ID 识别条目。只要文件仍在扫描目录中并保留有效 id，你可以手工重命名文件，插件不会仅凭标题重新创建副本。

控制面板默认显示搜索、同步状态、同步收藏和“更多”。选择条目后，主栏切换为同步所选、批量编辑、撤销和“更多”；刷新、强制同步、删除、下载封面与关联扫描等操作仍可在“更多”中找到。需要先选择条目的操作会明确提示。

手机端可展开“筛选与排序”，搜索框始终可见；按钮上的数量提示表示正在使用的筛选或排序条件。批量编辑逐项显示属性名，导入对比和状态同步明确标注本地值与另一来源的值。设置页标签可使用 Tab 聚焦、Enter 或空格切换。

搜索结果先显示，再逐项确认收藏状态；确认前添加／编辑按钮暂不可用，确认失败时可点击该条目的“刷新”重试。清空或发起新搜索后，旧请求不会覆盖当前结果。

更改搜索类型或排序会从第一页重新查询。保存云端收藏后，会刷新该条目的收藏信息，确保再次编辑使用最新值；取消编辑不会保留未提交的标签。控制面板随窗口宽度切换布局，同时保留当前选择与分页。

模板与自定义属性

模板决定文件路径、frontmatter 和正文。常用变量包括：

普通 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，不要直接把未审查修改发布为稳定版。

相关链接

• Bangumi API
• 获取 Access Token
• GitHub 仓库

支持开发

许可证

MIT License