# 媒体服务器查询优化记录

本次基于 `05967cdc0` 实现查询内容选择，范围为 Emby、Jellyfin、Plex、Navidrome。
极空间、飞牛、绿联、Vyo 按用户要求跳过，其适配器源码无改动。

调用方使用统一的 `MediaServerQueryOptions.fields`；省略选项保留原有内容，显式空集合只取操作必需信息。
同步、查重、分集、首页、播放入口及壁纸分别声明所需内容，适配器保留身份匹配与范围过滤依赖。
完整内容组、协议映射及调用文件清单见 [查询内容契约](media-server-query.md)。

| 服务 | 主要变化 |
| --- | --- |
| Emby / Jellyfin | 按需追加 Fields，独立控制图片和用户数据；精简详情按 Ids 查询，递归及失效缓存回退保留选项 |
| Plex | 下发 excludeFields / excludeElements，按需请求 Guid / Media，避免 SDK 自动补查；原生音乐条目标识规范为字符串 |
| Navidrome | 精简列表及最新专辑使用服务端 size / offset，跳过不用的数量与封面工作；Subsonic 不提供通用字段裁剪 |

旧模块 provider 只对已登记的可选 query 参数兼容省略。未改造的四种服务继续按旧客户端签名调用，Agent 原生动作连接前拒绝它们的 query 参数。
未新增 REST 查询参数；Python 门面与 Agent 使用同一内容模型，工具 Schema 从该模型推导。
部分服务端基础属性无法裁剪，Plex 旧版本还可能忽略排除参数；本次未连接真实媒体服务器测量响应字节或耗时。

## 验证记录

验证使用锁定环境的 Python 3.14.7，pytest 隔离配置、数据库和外部网络。依赖声明及锁文件无改动。

| 检查 | 结果 |
| --- | --- |
| 最终媒体查询、调用方、Agent 与文档生成回归 | 221 通过 |
| 最终架构依赖、Adapter 导入、出站及事件策略 | 168 通过 |
| 最终架构契约、Schema 导出与基线 CLI | 45 通过 |
| 修改的 34 个 Python 文件 Pylint | 10.00/10，无诊断 |
| 全应用 Pylint 建议性扫描 | 无诊断 |
| 严格 mypy、mypy / Ruff / 复杂度 ratchet | 通过 |
| 并发、异步阻塞、任务归属、运行时服务定位门禁 | 通过 |
| 启动性能，三次采样 | 通过 |
| 锁文件与离线环境一致性 | 通过，197 个包无需调整 |

全量 `python tests/run.py` 首次运行结果为 **16,316 通过、30 失败、15 跳过**。
本次发现的契约、导出清单、文档及测试替身遗漏已修正并在上述最终专项中复测。
全量首次结果不代表最终专项结果，也未声称全量通过；修正后未再重复运行全部分片。

另在未修改的 `05967cdc0` 独立检出中复现了部分音乐标签/封面写入、资源扫描缓存、Windows Shell 环境与性能预算失败。
本机继承的 `DEBUG=release` 使四个更新配置用例额外记录 DEBUG 规范化；设置测试进程 `DEBUG=false` 后这组用例通过。
日志关闭用例单独复跑通过。历史无源码字节码目录曾干扰模块清单检查，移出源码树保留后该检查通过。
这些结果保留了全量验证的限制，未通过修改不相关实现或放宽门禁消除失败。

本次架构快照仅登记新增查询契约、两个 SDK 导出及对应依赖；Plex 出站指纹变化只增加 LibrarySection 类型绑定，外连操作集合不变。
同步统计重构清除了两处 Optional 赋值诊断，mypy 基线仅下调该项，没有增加债务额度。