维护者看
PROJECT.md：状态、待办、维护规矩、本机环境。
Jellyfin 人物资料（头像 / 简介）的本地兜底方案。跟 MetaTube 这类远程刮削器互补： 排在它们之后，只在字段为空时才补，永不覆盖远程刮到的内容。
针对 Jellyfin 10.11.6 开发，已在 12.1.0 上完成升级验证与适配（数据目录、数据库 schema、插件加载三项均实测通过，见 docs/10-升级适配-Jellyfin-12.1.0.md）。
刮削链路上，演员资料缺失分三层，只有第三层是本地能救的：
| 层 | 症状 | 本方案能救吗 |
|---|---|---|
| 网络层 | 上游超时、连不上 | ❌ 改不了网络 |
| 源覆盖层 | 上游库里根本没这条数据 | ❌ 不能凭空造数据 |
| 自动化层 | 一次性脚本补过，但会回退、新片子进来又缺 | ✅ 这才是这里解决的 |
所以定位是兜底 + 防回退，不是"再去刨新数据源"。
插件挂在 Jellyfin 的 provider 链上，靠 Order = 100 排在 MetaTube 等远程刮削器之后，
所以它天然"上游没刮到才兜"，不需要写任何互斥判断。两条触发路径：
| 路径 | 触发时机 | 作用 |
|---|---|---|
ILocalMetadataProvider<Person> + IRemoteImageProvider |
人物页刷新、元数据重刮、新演员入库 | 当场兜底，不用等定时任务 |
IScheduledTask（默认每 24 小时） |
定时全量扫描 | 补漏：历史条目、provider 没覆盖到的情况 |
两条路径共用同一套判定逻辑，行为一致。
PROJECT.md 项目维护入口：状态、待办、维护规矩、本机环境
README.md 本文件：产品说明
b-plugin/ 插件（C#，net10.0）
├─ Jellyfin.Plugin.LocalMeta/
│ ├─ Plugin.cs 插件入口
│ ├─ PluginConfiguration.cs 配置模型
│ ├─ Sources/LocalMetaSources.cs 源抽象 + JavBoss sqlite + Gfriends 头像
│ ├─ Providers/ Person 文字 / 图片 provider
│ ├─ Tasks/ IScheduledTask
│ └─ Configuration/configPage.html 配置页（内嵌资源）
├─ build.ps1 编译 + 部署 / 卸载
└─ README.md 详细说明 + 实测接口签名清单
tools/
├─ apiprobe/ 元数据取证工具：读 DLL 打印真实接口签名
└─ loadtest/ 加载验证工具：反射确认宿主能识别 provider
docs/
├─ 10-升级适配-Jellyfin-12.1.0.md 12.1.0 适配说明（schema 变更、数据目录坑）
├─ 11-兼容性检查报告-12.1.0.md 升级后的检查过程与证据
├─ 20-插件方案-实施版.md 实施方案与取舍记录
├─ 30-演员资料体检与修复报告.md 数据来源与缺口分析
└─ 40-协作-GitHub推送与上传.md SSH 推送配置与常见故障
:: 需要 .NET 10 SDK（12.1.0 宿主是 net10.0，插件 TFM 已同步）
cd b-plugin
powershell -ExecutionPolicy Bypass -File build.ps1 -PackOnly :: 只编译
powershell -ExecutionPolicy Bypass -File deploy.ps1 :: 部署 + 重启脚本会自动停 Jellyfin、备份旧目录、按白名单复制、校验、重启。
部署规则坑较多（Jellyfin 会递归扫描插件目录下每个 dll，原生库会导致整个插件
被标 Malfunctioned），务必看 b-plugin/README.md 的「部署规则」章节，别自己手工拷 dll。
- 只补空，永不覆盖。 目标字段已有内容就跳过。
靠
Order = 100排在远程 provider 之后，天然"它没刮到才兜"， 不需要写任何互斥判断。 - 幂等。 重复执行结果不变，跑一百次和跑一次一样。
- 配置驱动。 数据源、阈值、输出格式全在配置文件 / 配置页， 加新源不用改代码。
| 源 | 提供什么 | 说明 |
|---|---|---|
| Gfriends | 头像（图片文件） | 纯图仓库，不提供简介/资料 |
JavBoss jav_idol |
三围/罩杯/身高/出道日 | 用于拼简介文本 |
| MetaTube（已装插件） | 影片元数据 | 远程，通常够用 |
新增数据源：实现 ILocalMetaProfileSource（两个方法）→ 在工厂挂一行 → 配置加一项。
provider 和任务代码不用动。
jav_idol.cup 存的是数字索引不是字母，规则是 字母 = chr(65 + cup)（0→A）。
用 bust - waist 差值反推验证过：cup=6→G(差30)、7→H(32)、8→I(35)、9→J(37) 全部自洽；
反过来按"cup=1 是 A"推则全盘不自洽。
字母表必须够长 —— JavBoss 实际有到 15 的值，字母表短了会静默丢弃高 cup 数据 （不报错，只是数据消失，很容易漏查）。
插件涉及的所有扩展点都从本地 DLL 元数据取证，不是照抄教程 （10.11 相比 10.9 有八处实质变动，照老教程写必编译不过）：
| 接口 / 类型 | 真实位置 |
|---|---|
ILocalMetadataProvider<T> |
MediaBrowser.Controller.Providers（不是 IMetadataProvider<T>） |
GetMetadata(ItemInfo, IDirectoryService, ct) |
同上，10.x 不再是 (result, ct) |
GetSupportedImages |
返回 IEnumerable<ImageType>（不是 BaseItemKind） |
RemoteImageInfo |
MediaBrowser.Model.Providers |
BaseItemKind |
Jellyfin.Data.Enums |
| 配置基类 | BasePluginConfiguration（IPluginConfiguration 已移除） |
| 配置序列化 | IXmlSerializer（XML，不是 JSON） |
IScheduledTask |
10.11 新增 Key；ExecuteAsync(progress, ct) |
升级 Jellyfin 前先取证，别先改代码：
cd tools\apiprobe
dotnet build -c Release
dotnet bin\Release\net10.0\apiprobe.dll "C:\Jellyfin" IRemoteImageProvider
dotnet bin\Release\net10.0\apiprobe.dll "C:\Jellyfin" NS:MediaBrowser.Controller.Providers取证目录必须是真正跑着的那个 Jellyfin。 本机就踩过：
C:\Program Files\Jellyfin\Server是旧 10.11 的残留（runtimeconfig 写着net8.0），而 12.1.0 实际装在C:\Jellyfin（net10.0）。对着旧目录取证等于没取证。 判断依据：看jellyfin.runtimeconfig.json里的tfm，或日志里的Storage path。
- 只补空字段，不覆盖已有内容。
- 写
jellyfin.db前自动备份，按时间轮转保留最近 N 份（配置页可调）。 - 配置页可关掉备份（不建议）。
- 部署插件时只部署插件自己的 dll，宿主程序集由 csproj 目标自动剔除 ——
覆盖
MediaBrowser.*/Jellyfin.*会导致版本冲突甚至 Jellyfin 起不来。
| 要求 | |
|---|---|
| Jellyfin | 10.11.x 或 12.1.x；其他版本需先跑 tools/apiprobe 取证，见下 |
| 构建 | .NET 10 SDK（插件 TFM net10.0，引用 Jellyfin.Controller 12.1.0） |
| 运行 | 无额外依赖，Jellyfin 宿主自带 runtime |
12.1.0 改了三处数据库 schema，其中一条会让按旧写法直查数据库的代码误判全员缺图：
| # | 变更 | 10.11 | 12.1.0 |
|---|---|---|---|
| 1 | BaseItems.Type 值 |
Person / Movie |
MediaBrowser.Controller.Entities.Person |
| 2 | Person 条目 Id 与 Peoples.Id |
同一个 GUID | 两个不同 GUID |
| 3 | PeopleBaseItemMap.PeopleId 指向 |
两者皆可 | Peoples.Id |
插件已适配：PersonEntityType 用完整类名，头像判定以 Person 条目 Id 为准、
查不到再退回 Peoples.Id，两个 Id 都要写图记录（否则影片页和人物页只有一个有图）。
升级 Jellyfin 后不用改配置，但要按 docs/10-升级适配-Jellyfin-12.1.0.md 里的自检清单核一遍，重点是数据目录有没有换。
| 状态 | |
|---|---|
| 插件 | 已部署到本地 Jellyfin 12.1.0，加载成功（status: Active），TFM net10.0 + 引用 Jellyfin.Controller 12.1.0 |
| 数据源 | 已配置（头像源 + javboss.db，日志「载入资料源 2 个」） |
| 补数据效果 | 数据源命中已验证；实际写入待跑一次计划任务后确认 |
代码部分可自由使用。数据源（Gfriends / JavBoss）各自独立，请自行遵守其许可与当地法规。