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，你可以手工重命名文件，插件不会仅凭标题重新创建副本。

扫描目录留空时，会从默认及各分类节点的有效路径模板推导共同静态目录。例如 Media/{{type}}/{{name_cn}}.md 扫描 Media；模板分布在不同根目录或根目录由变量决定时，扫描整个 Vault。显式目录必须覆盖所有模板，填 / 可明确选择 Vault 根目录。目录不存在却在其他位置发现已有条目时，会停止比较并提示检查目录，避免误建重复笔记；首次使用且没有条目时，仍允许创建输出目录。

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

“全面同步”比较当前账号全部类型和收藏状态，不受同步收藏的类型筛选或数量限制影响。先选择要比较的用户／平台字段，再查看待新增、已有差异、无差异和比较失败项。新增笔记默认选中，已有条目默认跳过；点击“审阅本页差异”选择逐字段的同步方向，保存选择后统一确认。列表按每页 40 条显示。本地独有笔记会保留。

如果部分导入成功、部分失败，结果页提供“查看导入结果与恢复操作”，可保留或回滚待决导入。该回滚只作用于这批本地导入，不会撤销此前完成的状态更新或云端修改。预览后笔记／设置变化、身份冲突或数据读取不完整时，需要刷新比较；执行过的预览不能再次提交。

全面同步在首次写入前重新读取所有选中条目的云端收藏，以及比较范围内的章节状态和平台数据。若发现取消收藏、数据变化或无法完成校验，整次执行停止并要求重新比较。新增笔记使用重新获取的详情；此安全校验会增加所选条目的读取请求，不会为跳过条目重复获取数据。校验完成后的其他设备修改仍可能与执行交错，Bangumi 与本地文件不支持跨系统原子提交。

选中新增笔记时，全面同步也会在首次写入前重新扫描本地身份；同 ID 笔记已出现、重复 ID 或身份冲突会使整次执行停止。最终路径规划和写回仍会再次检查，校验后发生的外部修改可能导致部分成功，请以结果页为准。单条收藏无法读取时不会直接判定为取消收藏：它也可能受 NSFW 等账号可见性设置限制，请检查账号设置后刷新比较；无法复核时不会绕过保护继续写入。

执行失败且预览已被消费或过期时，界面只保留刷新预览和关闭入口，需重新比较后才能确认；执行前的属性表单失败或取消不会自行废弃有效预览。

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

状态同步只修改选中的字段。“看到第 N 集”会保留范围外的章节标记；章节“以本地为准”也会清除云端已取消的标记。预览后笔记被编辑或替换时，请刷新预览再执行；部分章节上传失败会计为失败。若提示“云端已保存，但本地同步失败”，云端修改已经生效。

普通“同步状态”同样会在写入前复核所选条目的云端收藏与选中的章节／平台数据。若账号或数据变化、读取失败，请关闭比较窗口并重新比较。复核只针对选中条目，增加必要的读取请求；不为跳过条目发请求。ep_statuses 支持合法 YAML 列表写法，无法识别的状态项会阻止操作，请修复该属性后重试，不会将解析失败当作清空指令。

批量编辑的撤销仅在文件仍与本次操作后的内容一致时恢复；出现后续编辑或文件移动、消失就停止，历史记录保留供重试。撤销未完成时，部分文件可能已经恢复；请恢复预期文件后重试。用户数据导入写回前也会核对文件是否发生变化，冲突时请重新比较。

搜索结果先显示，再逐项确认收藏状态；确认前添加／编辑按钮暂不可用，确认失败时可点击该条目的“刷新”重试。已知展示限制：保存条目后若立即发起新搜索，旧条目的后台刷新可能使其重新出现在新列表中；可重新搜索刷新列表。

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

搜索分页忽略重复条目；服务器返回空页或没有新增条目时，会停止加载并在仍有未返回结果时提示重新搜索。请求失败可重试，不会跳过该页。收藏保存期间禁止重复提交。

需要恢复时，控制面板显示“打开恢复中心”，写操作保持阻断。恢复中心的技术诊断默认折叠，执行失败提示保持可见；只有恢复服务确认成功后才解除阻断。

模板与自定义属性

模板决定文件路径、frontmatter 和正文。

“作品模板”和“输出与命名”共用分类树，内容与路径分别继承，并显示生效来源。书籍下的小说、漫画、画集可单独配置；切换来源保留草稿。共享笔记独立管理，“模板管理”提供升级报告、验证和不覆盖已有文件的 manifest 导入导出。

常用变量包括：

普通 frontmatter 字段可作为本地自定义属性：

剧情评分:
资源属性: []
已购: false

完整变量表、条件语法、默认值、字段类型和模板来源以模板指南为准。

数据安全

Bangumi Sync 使用持久恢复日志保护本地文件事务。异常中断或回滚不完整时，插件会暂停新的写入，并通过 Recovery Center 引导恢复。

遇到恢复提示时：

• 先停止新的同步和批量编辑。
• 不要直接删除未知的 .bangumi-sync-recovery* 或 .bangumi-sync-*.tmp.md 文件。
• 按 Recovery Center 显示的按钮操作，必要时先备份 Vault。

操作步骤见恢复指南。内部状态和安全不变量见恢复模型。

常见问题

为什么扫描不到条目？

确认 Markdown frontmatter 中存在有效的 id，且文件位于配置的扫描目录内。路径与身份规则见身份与路径模型。

强制同步会覆盖本地数据吗？

插件会按设置保留本地自定义属性以及正文中的记录和感想。开启“保留本地自定义 frontmatter 属性”时，表单中未修改的模板默认值不会覆盖旧笔记；主动修改的字段才会作为覆盖值提交。新笔记仍使用模板默认值。执行大范围强制同步前仍建议导出用户数据。

同名作品如何保存？

无冲突时使用简洁名称；发生规范化路径冲突时依次使用年份和 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