1. 项目概述HAMA为Plex而生的动漫元数据管家如果你和我一样是个动漫爱好者同时又重度依赖Plex来管理自己的媒体库那你一定遇到过这个经典难题Plex自带的TVDB或TMDB代理Agent对动漫剧集的识别简直是一场灾难。季Season和集Episode的错乱匹配、OVA和剧场版被错误归类、番剧标题全是罗马音或英文译名……这些问题足以让任何一个强迫症患者抓狂。今天要聊的就是专门为解决这些问题而生的神器——HAMAHTTP AniDB Metadata Agent。简单来说HAMA是一个第三方的Plex元数据代理插件。它的核心使命就是充当Plex与AniDB一个专注于动漫的庞大数据库之间的桥梁同时巧妙地整合TVDB、TMDB等其他数据源最终为你的动漫库提供精准、美观且符合习惯的元数据。这包括了正确的剧集标题支持中文、日文原名、海报、背景图、剧情简介、演职员表甚至是主题曲。它不是一个扫描器不负责识别你的文件结构和命名那是像Absolute Series Scanner (ASS)这样的扫描器的工作。但HAMA和ASS是一对黄金搭档一个负责“找到文件”一个负责“贴上标签”两者结合才能打造出完美的Plex动漫体验。2. HAMA的核心工作原理与设计思路2.1 为什么需要HAMA传统代理的“水土不服”要理解HAMA的价值得先明白Plex默认代理在处理动漫时的局限性。TVDB等西方主流数据库的剧集划分逻辑是基于“季Season”的。一季通常对应一个播出年份或一个连贯的故事单元。但动漫的发布模式复杂得多有通常按季度播出的TV动画但可能分为多“季”或“期”有直接发售的OVA原创动画录像带有剧场版电影还有总集篇、特别篇等等。例如一部名为《Fate/stay night [Unlimited Blade Works]》的动漫在TVDB上可能被拆分为两季2014年和2015年播出而在AniDB上它可能就是一个完整的系列OVA和特典被清晰地标记为“特殊集”。如果你用TVDB代理Plex会试图把你的文件按TVDB的季集结构去匹配如果你的文件命名是遵循AniDB或更常见的“S01E01-E13”格式结果就是一片混乱。HAMA的设计哲学是“以AniDB为源多源聚合智能映射”。它并不取代TVDB而是利用ScudLee等人维护的映射文件anime-list-master.xml建立AniDB ID到TVDB/TMDB ID的对应关系。这样HAMA首先通过AniDB识别你的动漫然后利用映射关系去TVDB获取高质量的海报、背景图和英文简介去TMDB获取电影信息实现最佳的数据融合。2.2 核心数据流与文件解析HAMA的工作流程可以概括为以下几个关键步骤理解它们对后续排查问题至关重要本地搜索与识别当Plex触发元数据更新时HAMA首先在本地的anime-titles.xml文件中进行搜索。这个文件是从AniDB API定期下载的包含了所有动漫的ID和多语言标题。这意味着搜索过程是离线的速度快且不依赖AniDB网站的实时访问。ID映射找到匹配的AniDB ID后HAMA会查询anime-list-master.xml映射文件找到对应的TVDB系列ID或TMDB电影ID。这个映射文件是社区维护的精华不仅包含ID对应还包含了剧集顺序的映射因为AniDB和TVDB的集数编号可能不同以及制作公司Studio信息。元数据聚合拿到TVDB/TMDB ID后HAMA开始从各个数据源抓取元数据。它会根据你在代理设置中配置的“语言优先级”和“数据源优先级”决定最终显示哪个标题、哪张海报。标题可以从AniDB支持日文原名、罗马音、多种语言译名或TVDB获取。海报与背景主要从TVDB剧集或TMDB电影获取。HAMA有一个智能机制如果映射文件中为同一AniDB ID指定了多个TVDB ID常见于不同季它会根据AniDB的排名来轮换使用这些海报避免重复。简介与截图剧集简介和截图来自TVDB。合集如果动漫属于某个系列如《物语》系列、《Fate》系列HAMA会利用anime-movieset-list.xml文件或AniDB的“相关动漫”字段自动将它们归入同一个合集Collection中。本地资产优先HAMA完美支持Plex的“本地媒体资产”功能。这意味着你可以将精心挑选的海报命名为poster.jpg、背景图命名为fanart.jpg、字幕文件.srt等和主题曲theme.mp3放在剧集文件夹内HAMA会优先采用这些本地文件实现完全自定义。注意HAMA的“更新”机制。代理的update()方法仅在向库添加新项目、执行“刷新所有元数据”或“修正错误匹配”时被调用。日常的库扫描不会触发完整的元数据更新。这意味着如果你修改了本地资产文件可能需要对该项目手动“刷新元数据”。3. 实战部署从零开始搭建完美的Plex动漫库理论讲完我们来动手。假设你已经在服务器上安装好了Plex Media Server并且有一个专门存放动漫的文件夹。3.1 准备工作文件命名与结构在安装任何插件之前良好的文件命名习惯是基石。虽然ASS扫描器非常强大但遵循规范能让一切更顺利。对于动漫我强烈推荐以下命名约定TV动画/OVA系列名称/Season XX/系列名称 - SXXEYY - 可选集标题.ext例如Attack on Titan/Season 01/Attack on Titan - S01E01 - To You, 2,000 Years in the Future.mkv对于OVA或特别篇通常放在Season 00文件夹下。例如S00E01。剧场版电影电影名称 (发行年份)/电影名称 (发行年份).ext例如Your Name. (2016)/Your Name. (2016).mkv本地资产文件放在剧集或电影的同级或上级目录poster.jpg系列或电影的海报。fanart.jpg或background.jpg背景艺术图。banner.jpg横幅图较少用。theme.mp3主题曲。MovieName-trailer.ext预告片。3.2 安装Absolute Series Scanner (ASS)正如HAMA文档强调的ASS扫描器是必选项。它比Plex默认的扫描器更擅长处理复杂的动漫文件结构尤其是那些不按传统季划分的剧集。访问ASS的GitHub仓库https://github.com/ZeroQI/Absolute-Series-Scanner。找到Scanners/Series/Absolute Series Scanner.py这个文件。你可以直接点击RAW按钮查看然后全选复制内容。在你的Plex服务器上找到Plex的插件目录。通常路径如下请根据你的操作系统调整Windows%LOCALAPPDATA%\Plex Media Server\Scanners\Series\macOS~/Library/Application Support/Plex Media Server/Scanners/Series/Linux (常见)/var/lib/plexmediaserver/Library/Application Support/Plex Media Server/Scanners/Series/群晖NAS/volume1/Plex/Library/Application Support/Plex Media Server/Scanners/Series/(路径可能因型号和PMS套件版本而异)如果Scanners/Series文件夹不存在就创建它。在Series文件夹内创建一个新的文本文件命名为Absolute Series Scanner.py将第2步复制的代码粘贴进去保存。3.3 安装HAMA代理插件接下来安装主角HAMA。访问HAMA的GitHub仓库https://github.com/ZeroQI/Hama.bundle。点击绿色的“Code”按钮选择“Download ZIP”下载源码压缩包。解压下载的ZIP文件你会得到一个名为Hama.bundle-master的文件夹。关键一步将这个文件夹重命名为Hama.bundle去掉-master。将这个Hama.bundle文件夹放入Plex的Plug-ins目录。这个目录通常与Scanners目录在同一父目录下Windows%LOCALAPPDATA%\Plex Media Server\Plug-ins\macOS~/Library/Application Support/Plex Media Server/Plug-ins/Linux/var/lib/plexmediaserver/Library/Application Support/Plex Media Server/Plug-ins/群晖NAS/volume1/Plex/Library/Application Support/Plex Media Server/Plug-ins/确保文件夹权限正确特别是在Linux系统上。通常需要让Plex服务运行的用户如plex有读取和执行权限。如果遇到问题可以尝试sudo chmod -R 755 /path/to/Hama.bundle。重启Plex Media Server服务。3.4 在Plex中配置动漫库安装完插件后需要在Plex界面进行配置。打开Plex Web界面进入“设置” - “管理” - “库”。如果你还没有动漫库点击“添加资料库”类型选择“电视节目”即使包含OVA和剧场版也建议先以TV库为主电影可以单独建库或用HAMA的电影代理。给资料库起个名字比如“Anime”。在添加文件夹的页面指向你存放动漫的根目录。进入“高级”设置找到“扫描器”选项将其从“Plex电视节目扫描器”改为“Absolute Series Scanner”。找到“代理”选项将其从“Plex电视节目”改为“HamaTV”。点击“添加资料库”完成创建。3.5 深度配置HAMA代理库创建好后还需要对代理进行精细设置以匹配个人偏好。进入“设置” - “代理” - “电视节目”。在“代理”列表中找到“HamaTV”。点击右侧的齿轮图标进入HAMA的设置页面。这里的设置非常强大语言顺序这是最重要的设置之一。你可以设置“系列标题”和“剧集标题”分别优先采用哪种语言。例如我喜欢系列名显示为日文罗马字x-jat剧集标题显示为英文en。你可以按喜好拖拽排序。数据源覆盖你可以为每一个元数据字段标题、简介、海报、背景图等指定优先使用的数据源。例如你可以让“海报”优先使用“TheTVDB”如果找不到再使用“AniDB”。本地媒体资产务必勾选“Local Media Assets (TV)”并把它拖动到列表的最顶端。这确保了Plex会优先使用你放在文件夹里的poster.jpg等文件而不是从网上下载。OMDb API密钥如果你希望从OMDb获取评分等信息可以在此处填写你的API密钥免费申请。实操心得对于“工作室/制作公司”这个字段我建议在HAMA设置里将其数据源设置为“AnimeLists | AniDB”。因为映射文件anime-list-master.xml中的工作室信息通常比AniDB更准确、更完整特别是对于老番。AniDB的工作室字段有时会缺失。4. 高级技巧与疑难杂症排查实录即使一切安装正确在实际使用中仍可能遇到各种问题。以下是我多年使用中总结的经验和常见问题的解决方法。4.1 元数据匹配失败或错误症状Plex无法识别剧集或识别成了错误的动漫。排查步骤检查文件命名这是最常见的原因。确保文件名清晰包含关键信息。对于ASS扫描器在文件名中包含AniDB ID是终极解决方案。你可以在文件夹或文件名末尾加上[anidb-xxxxx]例如Sword Art Online [anidb-8692]。这样HAMA会直接使用此ID进行匹配百发百中。查看扫描日志HAMA会在其数据目录下生成详细的日志。路径通常为Plex Media Server/Plug-in Support/Data/com.plexapp.agents.hama/DataItems/_Logs/。查看以你的资料库名和根文件夹命名的.agent-search.log文件里面会记录匹配过程看它尝试了哪些关键词最终匹配到了哪个AniDB ID。手动修正匹配在Plex Web界面中进入识别错误的剧集点击右上角的“…”选择“修正匹配…”。在搜索框中尝试输入日文原名、罗马字或英文名。如果还不行直接输入anidb-xxxxxxxxxx为正确的AniDB ID进行搜索。更新映射文件HAMA会缓存映射文件约一周。如果你添加的是一部非常新的动漫可能社区映射还未更新。你可以尝试对资料库或单个剧集执行“刷新所有元数据”这会强制HAMA重新下载最新的映射文件。4.2 海报、背景图或主题曲缺失症状剧集有了正确的标题和简介但没有海报或背景。排查步骤确认数据目录权限HAMA需要在其数据目录.../Plug-in Support/Data/com.plexapp.agents.hama/DataItems/下创建缓存文件夹来存储下载的图片和主题曲。如果权限不足下载会失败。检查该目录的所有者是否为Plex服务用户并具有写权限。可以参考文档中的命令进行修复。检查HTML报告HAMA的一个强大功能是生成HTML格式的错误报告。在上述DataItems目录中查找类似TVDB posters missing.htm、AniDB posters missing.htm的文件。打开它们你会看到直接链接到缺失海报的TVDB或AniDB页面。这通常意味着该条目在数据源中确实没有海报或者映射关系有误。你可以自己到TVDB上上传一张海报或者等待社区更新。利用本地资产这是最可靠的解决方案。去动漫资源站或自行制作一张高清海报命名为poster.jpg放在剧集文件夹的根目录对于系列或季文件夹对于某一季。同样背景图命名为fanart.jpg主题曲命名为theme.mp3。确保在HAMA代理设置中“Local Media Assets”已启用且优先级最高。主题曲的特殊性Plex对主题曲有官方仓库但HAMA也支持从TVTunes等源获取或播放本地文件。本地主题曲文件需命名为theme.mp3并放在正确位置。有时Plex服务器可能不会自动索引音频文件重启Plex服务或刷新元数据可能有效。4.3 季和集编号混乱症状剧集顺序错乱OVA被塞进了正片或者总集篇被当成了独立季。原因与解决这通常是TVDB与AniDB之间集数映射不完美导致的。HAMA依赖于anime-list-master.xml中的episodeoffset等映射规则。查看映射文件你可以直接打开anime-list-master.xml文件在线或本地缓存搜索你的AniDB ID查看其mapping标签内的细节了解它是如何映射到TVDB季和集的。使用“剧集排序”功能Plex本身提供了“剧集排序”选项。在剧集视图的右上角你可以选择按“DVD顺序”、“绝对顺序”或“故事顺序”排列。对于动漫有时选择“DVD顺序”或“绝对顺序”能得到更符合碟片发行或原始播放列表的排列。终极方案手动编辑如果映射严重错误你可以考虑手动编辑本地的映射文件缓存或者更实际一点在Plex中使用“拆分”、“合并”或“编辑剧集”功能手动调整。但这只影响本地库。4.4 日志分析与高级调试当遇到无法解决的诡异问题时系统日志是最后的救命稻草。请严格按照以下步骤收集日志才能在社区或GitHub上有效求助清理环境停止Plex服务。删除Plex日志目录Plex Media Server/Logs/下的所有.log文件保留文件夹结构。这能确保你获取到最新的、纯净的日志。重现问题启动Plex对出问题的资料库执行一次“刷新所有元数据”或尝试添加一部新剧集来触发问题。收集日志你需要以下关键日志文件Plex Media Server/Logs/PMS Plugin Logs/com.plexapp.agents.hama.logHAMA代理的核心日志包含所有元数据获取和处理的详细信息。Plex Media Server/Logs/PMS Plugin Logs/com.plexapp.system.log系统日志记录插件加载错误等。.../Data/com.plexapp.agents.hama/DataItems/_Logs/[你的资料库名称]_[你的媒体文件夹路径].agent-search.log记录匹配过程的日志。.../Data/com.plexapp.agents.hama/DataItems/_Logs/[你的资料库名称]_[你的媒体文件夹路径].agent-update.log记录元数据更新过程的日志。提交问题将以上日志文件的内容注意去除个人路径信息连同问题的清晰描述如Plex版本、HAMA版本、操作系统一并提交到HAMA的GitHub Issues页面。清晰的日志能极大帮助开发者定位问题。5. 性能优化与维护建议一个运行良好的HAMA库需要一点日常维护。定期更新插件关注HAMA和ASS的GitHub仓库社区会持续修复bug和添加新功能如对新的数据源的支持。更新时记得先备份你的Hama.bundle文件夹然后下载新版覆盖重启Plex服务。管理缓存HAMA的缓存文件图片、主题曲会随时间增长。它们位于DataItems下的各个子文件夹中。如果你磁盘空间紧张可以定期清理HAMA会在需要时重新下载。但请注意清理AniDB、TheTVDB等文件夹里的.xml缓存文件会导致HAMA重新下载映射文件可能会暂时增加元数据刷新时间。利用合集功能HAMA自动创建的合集Collection功能非常有用。你可以在Plex中进一步美化合集为其添加自定义海报和描述让整个动漫系列看起来更有条理。例如所有《Fate》系列的作品都会被自动归入一个合集。备份代理设置一旦你在HAMA代理设置中调校好了完美的语言优先级和数据源顺序建议截个图或记录下来。因为如果未来重建Plex库或迁移服务器这些设置需要重新配置。最后我想分享一个个人体会HAMAASS的组合虽然初始配置略显复杂但它带来的体验提升是巨大的。它让Plex从一个“勉强能用”的动漫管理器变成了一个高度定制化、信息准确、符合动漫迷习惯的专业媒体中心。这个过程就像在打磨一件收藏品当看到自己的动漫库整整齐齐海报精美信息准确那种满足感是对折腾过程的最好回报。如果在配置过程中遇到任何坎别忘了查阅详细的日志和社区文档几乎所有问题都有先行者遇到过并找到了解决方案。