From 2c02096298c70a2604fcc82bfbd986ecaf7165c7 Mon Sep 17 00:00:00 2001
From: Meiam <91270@qq.com>
Date: Mon, 22 Dec 2025 20:08:26 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=B1=E5=BA=A6=E7=BE=8E=E5=8C=96=20?=
=?UTF-8?q?README.md=20=E6=8E=92=E7=89=88=E5=B9=B6=E6=9B=B4=E6=96=B0?=
=?UTF-8?q?=E7=89=B9=E6=80=A7=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
README.md | 173 ++++++++++++++++++++++--------------------------------
1 file changed, 70 insertions(+), 103 deletions(-)
diff --git a/README.md b/README.md
index aa82570..f89f89c 100644
--- a/README.md
+++ b/README.md
@@ -1,133 +1,100 @@
-# MeiamSubtitles
-Emby & Jellyfin 中文字幕插件，支持 **迅雷影音**、**射手网** 字幕自动下载与精准 Hash 匹配。
+# 🎬 MeiamSubtitles
-[](#)
-[](#)
-[](#)
-[](https://github.com/91270/Emby.MeiamSub)
-[](https://github.com/91270/Emby.MeiamSub/fork)
-[](https://www.592.la/)
+**MeiamSubtitles** 是一款专为 **Emby** 和 **Jellyfin** 媒体服务器打造的中文字幕下载插件。它集成了 **迅雷影音** 与 **射手网** 的强大搜索能力，支持精准的视频哈希（Hash）匹配，让您的媒体库自动补全高质量字幕。
-
+---
-## 给个星星! ⭐️
+
+ 
+ 
+ 
+ 
+ 
+
-如果你喜欢这个项目或者它帮助你, 请给 Star~（辛苦咯）
+## ✨ 核心特性
-如果你能赞助稳定 Google Drive 团队盘用于媒体库插件测试, 请于我联系 91270#QQ.COM
+- **🚀 精准匹配**: 支持迅雷看看 (CID) 和射手网 (Hash) 双重校验逻辑，确保字幕与视频内容完美同步。
+- **⚡ 极致性能**: 核心采样算法全面采用**异步 I/O (Async/Await)** 模式，在大规模媒体库扫描时不会阻塞服务器线程。
+- **🌐 广泛兼容**: 深度适配 **Jellyfin 10.11+** 及 **Emby v4.9+**，支持 `zho`、`chi` 等多种国际化语言代码映射。
+- **🛡️ 稳定可靠**: 针对射手网 API 的老化问题增加了防御性校验，能有效处理乱码返回，保证系统长效稳定。
+- **📝 详尽日志**: 记录哈希计算耗时与接口原始响应，让问题排查不再是黑盒。
-
+## 📦 项目组件说明
-## 广告时间 📣
+| 组件名称 | 适用平台 | 目标框架 | 说明 |
+| :--- | :--- | :--- | :--- |
+| **Emby.MeiamSub.Thunder** | Emby | .NET Standard 2.1 | 迅雷看看字幕插件 |
+| **Emby.MeiamSub.Shooter** | Emby | .NET Standard 2.1 | 射手影音字幕插件 |
+| **Jellyfin.MeiamSub.Thunder** | Jellyfin | .NET 9.0 | 迅雷看看字幕插件 (现代 DI 架构) |
+| **Jellyfin.MeiamSub.Shooter** | Jellyfin | .NET 9.0 | 射手影音字幕插件 (现代 DI 架构) |
+| **Emby.MeiamSub.DevTool** | 开发调试 | .NET 8.0 | 哈希算法测试与 API 模拟工具 |
-搬瓦工 $99 年付, 建站神器重出江湖，THE PLAN V1 传家宝套餐，18机房随意切换
+---
-循环优惠码：BWHCCNCXVV（6.77%）
+## 🚀 快速安装
-[直达通道(传家宝套餐)](https://bwh88.net/aff.php?aff=117&pid=87)
+### 第一步：获取插件
+前往 [GitHub Releases](https://github.com/91270/Emby.MeiamSub/releases) 下载最新版本的发布包。
-
+> **🔔 推荐建议**：在媒体库设置中**不勾选**本插件作为默认自动下载器。建议仅在手动“搜索字幕”时使用，以获得更精准的人工筛选体验。
-## 功能介绍
+### 第二步：部署插件
-- [x] **迅雷影音**: 支持通过文件 Hash (CID) 精准匹配字幕。
-- [x] **射手网**: 支持通过文件 Hash 精准匹配字幕。
-- [x] **高性能**: 核心哈希计算采用异步 I/O (Async/Await) 模式，避免阻塞服务器线程。
-- [x] **稳定性**: 内置重试机制与异常处理，Jellyfin 版本采用现代化的依赖注入架构。
+#### 🔹 方式 A：Jellyfin 存储库安装 (强烈推荐)
+Jellyfin 用户可直接添加官方存储库，实现一键安装与自动更新：
+1. 控制台 -> **插件** -> **存储库** -> 点击“添加”。
+2. 输入名称 `MeiamSub` 和 URL：
+ `https://github.com/91270/MeiamSubtitles.Release/raw/main/Plugin/manifest-stable.json`
+3. 在“目录”中找到插件并安装，重启服务即可。
-## 项目说明
+#### 🔹 方式 B：手动安装 (Emby/通用)
+将下载的 `.dll` 文件（Jellyfin 用户请下载 `.zip` 并解压完整目录）放入服务器的 `plugins` 文件夹：
-| # | 模块功能 | 项目名称 | 说明 |
-|---|---|---|---|
-| 1 | Emby 插件 | `Emby.MeiamSub.Thunder` | 迅雷看看字幕插件 (.NET Standard 2.1) |
-| 2 | Emby 插件 | `Emby.MeiamSub.Shooter` | 射手影音字幕插件 (.NET Standard 2.1) |
-| 3 | Jellyfin 插件 | `Jellyfin.MeiamSub.Thunder` | 迅雷看看字幕插件 (.NET 9.0) |
-| 4 | Jellyfin 插件 | `Jellyfin.MeiamSub.Shooter` | 射手影音字幕插件 (.NET 9.0) |
-| 5 | 开发工具 | `Emby.MeiamSub.DevTool` | 哈希算法测试与调试工具 |
+- **Windows**: `AppData\Local\jellyfin\plugins` 或 `Emby-Server\programdata\plugins`
+- **Linux/Docker**: `/config/plugins` 或 `/var/lib/emby/plugins`
+- **群晖/威联通**: 对应套件安装目录下的 `plugins` 文件夹
-## 使用插件
+---
-首先下载已编译好的插件 [Release 下载](https://github.com/91270/Emby.MeiamSub/releases)。
+## ❓ 常见问题排查 (FAQ)
-**注意**：建议在媒体库设置中**不勾选**本插件作为默认下载器，仅在手动“编辑字幕”或“搜索字幕”时使用，以获得最佳体验。
+
+1. 为什么在 Jellyfin 10.11+ 中搜不到字幕？
+新版 Jellyfin 采用了三位字母的语言代码（如 zho）。请确保您已升级至本插件的 v1.0.13.0 或更高版本，该版本已完美解决语言映射兼容性。
+
-## 常见问题排查 (FAQ)
+
+2. 为什么射手网有时候返回结果为空？
+由于射手网 API 维护状态不佳，对于部分冷门资源或 Hash 不匹配的文件，API 可能会返回非法数据。插件目前已增加防御逻辑，会自动忽略这些无效返回以保护服务器稳定。
+
-如果您在搜索字幕时遇到“未找到结果”，请按以下步骤排查：
+
+3. 安装本插件后会影响 Open Subtitles 吗？
+不会。本插件已将优先级 (Order) 调整为 100（低优先级），并在代码层面优化了并发逻辑，确保官方插件能优先获取请求机会。
+
-### 1. 语言代码识别
-- **现象**: 在 Jellyfin 10.11+ 中搜索不到字幕。
-- **原因**: 新版 Jellyfin 可能会传递三位字母代码 (如 `zho`)。
-- **解决**: 本插件最新版已修复该问题，支持 `zho`、`chi`、`zh-CN` 等多种映射。请确保您使用的是最新版本的 DLL。
+
+4. 如何提供有效的错误反馈？
+如果确定有字幕但搜不到，请在 Issue 中提供日志里的 Target 文件名、计算出的 FileHash 以及 ResponseBody 内容。
+
-### 2. 射手网 API 状态
-- **现象**: 部分电影能搜到，部分完全搜不到。
-- **原因**: 射手网 API 年久失修，对于无资源或 Hash 不匹配的文件，API 可能返回异常内容（如乱码）。
-- **表现**: 插件已增加防御性校验，若检测到 API 返回异常，会自动过滤并返回空结果以保证系统稳定。
+---
-### 3. 如何反馈问题
-如果遇到确定有字幕但搜不到的情况，请查看服务器日志并提供以下关键信息：
-- 搜索开始时的 `Target` 文件名。
-- 接口返回的 `ResponseBody` 内容。
-- 计算得到的 `FileHash` 值。
+## 🤝 贡献与感谢
-## Jellyfin 安装 (推荐)
+欢迎通过提交 Issue 或 Pull Request 来完善本项目。
-Jellyfin 用户可以通过添加插件存储库实现一键安装和自动更新：
+- **开发守则**: 遵循异步命名规范，所有修改请标注 `修改人: Meiam`。
+- **致谢**: 感谢 [Emby.Subtitle.Subscene](https://github.com/nRafinia/Emby.Subtitle.Subscene) 提供的灵感与参考。
-1. 打开 Jellyfin 控制台 -> **插件** -> **存储库**。
-2. 点击添加，输入名称 (如 MeiamSub) 和以下 URL：
- ```
- https://github.com/91270/MeiamSubtitles.Release/raw/main/Plugin/manifest-stable.json
- ```
-3. 保存后在插件目录中找到 **MeiamSub.Thunder** 和 **MeiamSub.Shooter** 进行安装。
-4. 重启 Jellyfin 服务。
+---
-### 手动安装 (Emby / 通用)
+## ⭐️ 给个星星
-将下载的 `.dll` 文件复制到服务器的插件目录，然后重启服务。
+如果你喜欢这个项目，请给一个 **Star**！这对我非常重要。
-#### Windows
-```bash
-# 路径可能因安装方式不同而异
-Emby-Server\Programdata\Plugins\
-# 或
-Emby-Server\System\Plugins\
-```
+如果你有稳定的 Google Drive 团队盘资源可供媒体库插件测试，欢迎联系：`91270#QQ.COM`
-#### Linux / Docker
-```bash
-# 常见路径
-/opt/emby-server/system/plugins
-# 或
-/var/lib/emby/plugins
-```
-
-#### 群晖 (Synology)
-
-```bash
-/var/packages/EmbyServer/var/plugins
-# 或
-/var/packages/EmbyServer/target/system/plugins
-```
-
-#### 威联通 (QNAP)
-
-```bash
-# 其中`CACHEDEV{num}_DATA`的名称取决于你的qpkg安装位置
-/share/CACHEDEV1_DATA/.qpkg/EmbyServer/programdata/plugins
-/share/CACHEDEV1_DATA/.qpkg/EmbyServer/system/plugins
-```
-
-
-
-## 贡献
-
-欢迎提交 Issue 反馈问题，或提交 Pull Request 贡献代码。
-
-* **开发分支**: `master`
-* **代码风格**: 请遵循现有的 C# 代码风格，异步方法请使用 `Async` 后缀。
-
-## 致谢
-
-[Emby.Subtitle.Subscene](https://github.com/nRafinia/Emby.Subtitle.Subscene)
\ No newline at end of file
+---
+*Powered by Meiam*