Project-N-E-K-O · wehos · May 7, 2026 · May 6, 2026 · May 6, 2026 · May 6, 2026
diff --git a/plugin/plugins/galgame_plugin/__init__.py b/plugin/plugins/galgame_plugin/__init__.py
@@ -763,8 +763,12 @@ def __init__(self, ctx):
         self._bridge_poll_task_lock = threading.RLock()
         self._textractor_install_lock = threading.Lock()
         self._tesseract_install_lock = threading.Lock()
-        # rapidocr/dxcam install locks removed: both bundled into main program
-        # (see pyproject.toml [dependency-groups] galgame).
+        # rapidocr/dxcam *install* locks removed: both bundled into main program.
+        # rapidocr_models download lock is separate — it's not installing the
+        # package, it's pulling the user-selected language pack into the
+        # plugin model cache so RapidOCR can serve a non-bundled (lang, version)
+        # combo (e.g. japan + PP-OCRv4).
+        self._rapidocr_models_lock = threading.Lock()
         self._cfg = None
         self._state = build_initial_state(
             mode=MODE_COMPANION,
@@ -4452,6 +4456,59 @@ async def galgame_install_tesseract(self, force: bool = False, **_):
     # [dependency-groups] galgame). Run `uv sync --group galgame` for source
     # installs; packaged builds always include them.
 
+    @plugin_entry(
+        id="galgame_download_rapidocr_models",
+        name=tr("entries.galgame_download_rapidocr_models.name", default='下载 RapidOCR 模型'),
+        description=tr("entries.galgame_download_rapidocr_models.description", default='为当前 (lang_type, ocr_version) 选择从 ModelScope 下载缺失的 RapidOCR 模型文件到插件模型缓存目录。bundled 默认（ch+PP-OCRv4）不需要下载。'),
+        input_schema={
+            "type": "object",
+            "properties": {
+                "force": {"type": "boolean", "default": False},
+            },
+        },
+        timeout=600.0,
+        llm_result_fields=["summary"],
+    )
+    async def galgame_download_rapidocr_models(self, force: bool = False, **_):
+        if self._cfg is None:
+            return Err(SdkError(self._not_configured_message()))
+        if not self._rapidocr_models_lock.acquire(blocking=False):
+            return Err(SdkError(self._install_in_progress_message("RapidOCR Models")))
+        current_run_id = self._resolve_current_run_id()
+        progress_callback = self._resolve_install_progress_callback(current_run_id)
+        try:
+            from .rapidocr_support import download_rapidocr_models
+
+            download_result = await download_rapidocr_models(
+                logger=self.logger,
+                install_target_dir_raw=self._cfg.ocr_reader_install_target_dir,
+                ocr_version=self._cfg.rapidocr_ocr_version,
+                lang_type=self._cfg.rapidocr_lang_type,
+                timeout_seconds=float(self._cfg.ocr_reader_install_timeout_seconds or 180.0),
+                force=bool(force),
+                task_id=current_run_id or None,
+                progress_callback=progress_callback,
+            )
+            clear_install_inspection_cache()
+            await self._poll_bridge(force=True)
+            downloaded = download_result.get("downloaded") or []
+            summary = (
+                f"RapidOCR models ready ({len(downloaded)} file(s) downloaded)"
+                if downloaded
+                else "RapidOCR models already present"
+            )
+            return Ok(
+                {
+                    "summary": summary,
+                    "download_result": download_result,
+                    "status": await self._build_status_payload_async(),
+                }
+            )
+        except Exception as exc:
+            return Err(SdkError(self._format_install_entry_error("rapidocr_models", "RapidOCR Models", exc)))
+        finally:
+            self._rapidocr_models_lock.release()
+
     @plugin_entry(
         id="galgame_get_snapshot",
         name=tr("entries.galgame_get_snapshot.name", default='获取 galgame 快照'),

diff --git a/plugin/plugins/galgame_plugin/docs/quickstart.md b/plugin/plugins/galgame_plugin/docs/quickstart.md
@@ -0,0 +1,129 @@
+# Galgame 游玩助手 - 快速开始
+
+按步骤完成配置 OCR 截图识别，让猫娘陪你一起玩 Galgame。
+
+---
+
+## 一、OCR 引擎与模型
+
+插件需要 OCR 引擎来识别游戏画面中的文字。RapidOCR 与 DXcam 已经随主程序打包，**默认不需要单独安装**：
+
+- **RapidOCR**（主后端）：轻量 ONNX OCR，已打包；wheel 内置 **`ch + PP-OCRv4`** 三件模型，galgame 插件**默认识别组合**为 `lang_type=japan + ocr_version=PP-OCRv4`
+- **Tesseract**（兼容兜底）：传统 OCR，需要单独安装；只在 RapidOCR 不可用时才使用
+
+> **首次运行下载日文模型**：插件默认 `lang_type=japan`，但日文 rec 模型 (`japan_PP-OCRv4_rec_mobile.onnx`, ~10 MB) 不在 wheel 内。RapidOCR 横幅会提示"模型未下载"，点击横幅上的「**立即下载模型**」按钮会从 RapidAI ModelScope 拉取，下载完成后立即生效。如果你只玩中文 galgame，把 `lang_type` 改成 `ch` 即可走 wheel 内置模型，不需要任何下载。
+>
+> 想用其他语言（korean / en / v5 ch）也是同样的流程：在 `[rapidocr] lang_type` / `ocr_version` 改成你需要的组合，按横幅提示下载。
+>
+> 如果下载失败，横幅会显示具体的错误（HTTP 状态、超时、校验和不匹配等）和恢复路径（"国内可能需要代理；或手动从源 URL 下载到模型缓存目录后刷新"）。
+
+---
+
+## 二、截图后端
+
+OCR 需要稳定截取游戏画面。DXcam 已随主程序打包，截图后端可在 `auto / smart / DXcam / MSS / PyAutoGUI / PrintWindow` 中选择：
+
+- **DXcam**（推荐）：Windows 高性能截图，延迟低、帧率高
+- **MSS / PyAutoGUI**：跨平台兜底，无需额外安装
+- **PrintWindow**：可截取被遮挡的窗口，但部分 DirectX/Unity 游戏会拿到旧帧
+
+> 默认采用 smart 链：`DXcam → MSS → PyAutoGUI`。如果 DXcam 截图黑屏，可在「高级设置 → 截图后端」切到 MSS / PyAutoGUI / PrintWindow。
+>
+> **Textractor 不是截图后端**，而是内存读取（Memory Reader）兜底方案。部分游戏引擎（如 Unity、Kirikiri）可在「高级设置 → 内存读取」中接入 Textractor，跳过截图直接提取文字。
+
+---
+
+## 三、启动游戏
+
+1. 打开你要玩的 Galgame
+2. 停在**有文字的画面**（对话、旁白均可）
+3. 回到插件页面
+
+插件会自动检测运行中的游戏进程和窗口。
+
+---
+
+## 四、刷新窗口列表
+
+点击「刷新窗口」按钮，插件会扫描当前运行的所有窗口并匹配游戏进程。
+
+如果自动匹配正确，窗口会自动选中，无需手动操作。
+
+---
+
+## 五、选择游戏窗口
+
+如果游戏窗口没有自动选中，可以手动选择：
+
+1. 点击「选择识别窗口」按钮
+2. 在弹出列表中选择正确的游戏窗口
+3. 确认后，该窗口将作为 OCR 识别目标
+
+> 如果窗口列表为空，请确认游戏已经启动并停在有文字的画面。
+
+---
+
+## 六、校准截图区域
+
+自动校准可以裁剪掉窗口边框、菜单栏等无关区域，让 OCR 更精准：
+
+1. 展开「高级设置」
+2. 找到「OCR 截图校准」
+3. 点击「自动校准」— 插件会根据当前窗口内容自动识别文字区域
+
+也可以手动调整裁剪比例（上下左右边距）以适配不同游戏布局。
+
+---
+
+## 七、开始识别
+
+一切就绪后，插件会自动开始识别：
+
+| 模式 | 说明 |
+|------|------|
+| 自动推进 | 持续识别画面文字，检测到新台词时推送给 AI |
+| 静默模式 | 仅识别与展示，不执行自动推进 |
+| 伴读模式 | 自动识别 + AI 根据台词生成陪伴对话 |
+
+当前识别到的文字会显示在「当前台词」区域，历史台词在「台词历史」中查看。
+
+---
+
+## 八、主诊断面板
+
+顶部卡片实时显示插件运行状态：
+
+| 指标 | 含义 |
+|------|------|
+| 游戏会话 | 当前检测到的游戏进程/窗口 |
+| OCR 状态 | OCR 引擎运行状态（就绪/识别中/错误） |
+| 截图状态 | 截图工具状态（运行中/未安装） |
+| 当前台词 | 最新识别到的台词内容 |
+| 活跃模式 | 当前工作模式（自动/手动/伴读） |
+
+---
+
+## 九、高级设置
+
+展开「高级设置」区域可以配置：
+
+- **OCR 引擎选择**：RapidOCR / Tesseract 切换
+- **截图后端**：auto / smart / DXcam / MSS / PyAutoGUI / PrintWindow 切换
+- **内存读取**：Textractor 等内存读取方案的接入与开关（部分引擎可跳过截图）
+- **轮询间隔**：OCR 识别和状态刷新的频率
+- **OCR 截图校准**：文字区域裁剪参数
+- **屏幕感知**：画面类型识别和场景切换检测
+- **依赖管理**：安装/更新 RapidOCR / DXcam / Tesseract / Textractor
+
+---
+
+## 常见问题
+
+| 问题 | 解决方法 |
+|------|--------|
+| OCR 安装失败 | 检查网络连接，确保可以访问 GitHub Release 页面 |
+| 找不到游戏窗口 | 确认游戏已启动，窗口未最小化，点击「刷新窗口」重试 |
+| 识别不出文字 | 检查截图区域是否正确，尝试重新校准；确认游戏文字在画面中可见 |
+| DXcam 截图黑屏 | 部分游戏有反截图保护，可在「高级设置 → 截图后端」切换到 MSS / PrintWindow，或在「内存读取」中接入 Textractor 跳过截图 |
+| AI 不回复 | 确认陪伴模式已开启，目标 AI 已配置，AI 服务正常运行 |
+| 识别结果乱码 | 在 OCR 设置中调整识别语言（中文/日文/英文） |
diff --git a/plugin/plugins/galgame_plugin/i18n/ui/en.json b/plugin/plugins/galgame_plugin/i18n/ui/en.json
@@ -480,7 +480,9 @@
   "ui.action.recalibrate_ocr": "Recalibrate OCR",
   "ui.action.line_details": "View Recognition Details",
   "ui.action.choice_advisor": "Switch to Auto Advance",
-  "ui.action.install_rapidocr": "View RapidOCR setup hint",
+  "ui.action.install_rapidocr": "View RapidOCR status",
+  "ui.action.install_dxcam": "Install DXcam",
+  "ui.action.reset_tutorial": "Reopen Setup Guide",
   "ui.action.refresh_status": "Refresh Status",
   "ui.pending.locking": "Locking...",
   "ui.pending.clearing": "Clearing...",
@@ -734,6 +736,24 @@
   "ui.first_run.recognize.done": "A line has been read.",
   "ui.first_run.recognize.pending": "Start automatic recognition, or advance to the next line in the game.",
   "ui.first_run.done_marker": "Done",
+  "ui.first_run.install_ocr.title": "OCR Models",
+  "ui.first_run.install_ocr.done": "OCR engine and selected models are ready.",
+  "ui.first_run.install_ocr.pending": "RapidOCR is unavailable. Use the packaged build, or from source run `uv sync --group galgame` and restart.",
+  "ui.first_run.install_capture.title": "Install Capture Tool",
+  "ui.first_run.install_capture.done": "Capture tool is ready.",
+  "ui.first_run.install_capture.pending": "Go to \"Dependencies\" panel and install DXcam.",
+  "ui.first_run.calibrate.title": "Calibrate Capture Area",
+  "ui.first_run.calibrate.done": "Capture area calibrated.",
+  "ui.first_run.calibrate.pending": "Open \"Advanced Settings\" and set crop ratios in OCR Capture Calibration.",
+  "ui.first_run.action.install_rapidocr": "Install RapidOCR",
+  "ui.first_run.action.install_dxcam": "Install DXcam",
+  "ui.first_run.action.select_window": "Select Window",
+  "ui.first_run.action.auto_calibrate": "Auto Calibrate",
+  "ui.first_run.action.refresh_all": "Refresh Status",
+  "ui.first_run.action.start_recognition": "Start Recognition",
+  "ui.first_run.action.reset_tutorial": "Reopen Setup Guide",
+  "ui.first_run.install_progress": "Installing: {status} {percent}%",
+  "ui.first_run.skip_confirm": "Skip the setup guide? You can re-open it later in Advanced Settings.",
   "ui.flash.screen_templates_saving": "Saving screen templates...",
   "ui.flash.screen_templates_saved": "Screen templates saved",
   "ui.error.template_json_parse_failed": "Template JSON parse failed",
@@ -1008,12 +1028,27 @@
   "ui.settings.saving_hint": "Saving...",
   "ui.common.auto_value": "(auto)",
   "ui.common.none_value": "(none)",
+  "ui.first_run.install_ocr.pending_tesseract": "Go to \"Dependencies\" panel and install Tesseract.",
   "ui.install.rapidocr.bundled_hint": "RapidOCR is now bundled with the main program. If you're running the packaged build, please reinstall it; if you're running from source, run `uv sync --group galgame` and restart.",
   "ui.install.rapidocr.unavailable_title": "RapidOCR unavailable — use the packaged build, or run `uv sync --group galgame` from source",
   "ui.install.dxcam.bundled_hint": "DXcam is now bundled with the main program (Windows only). If you're running the packaged build, please reinstall it; if from source, run `uv sync --group galgame` and restart. The capture chain falls back to MSS / PyAutoGUI automatically.",
   "ui.install.dxcam.unavailable_title": "DXcam unavailable — Windows only, requires packaged build or `uv sync --group galgame`",
   "ui.install.pyautogui.use": "Use PyAutoGUI",
   "ui.install.pyautogui.using": "Using PyAutoGUI",
   "ui.install.pyautogui.title": "Use the cross-platform PyAutoGUI screenshot backend (slower on macOS/Linux)",
-  "ui.flash.rapidocr_hint_revealed": "Scrolled to the RapidOCR status banner. Follow the on-banner steps (reinstall packaged build / uv sync --group galgame)."
+  "ui.flash.rapidocr_hint_revealed": "Scrolled to the RapidOCR status banner. Follow the on-banner steps (reinstall packaged build / uv sync --group galgame).",
+  "ui.flash.dxcam_hint_revealed": "Scrolled to the DXcam status banner. Follow the on-banner steps (reinstall packaged build / uv sync --group galgame).",
+  "ui.install.rapidocr.missing_models_kicker": "OCR Primary Backend - Models Not Downloaded",
+  "ui.install.rapidocr.missing_models_title": "RapidOCR is ready, but the selected language models haven't been downloaded",
+  "ui.install.rapidocr.missing_models_body": "Current selection lang_type={lang} + ocr_version={version} requires the following model files in the local cache ({count} files, ~{size} MB total). Click the button below to download them; downloads come from RapidAI's ModelScope mirror.",
+  "ui.install.rapidocr.download_models.action": "Download Models Now",
+  "ui.install.rapidocr.download_models.retry": "Retry Model Download",
+  "ui.install.rapidocr.download_models.running": "Downloading models in background...",
+  "ui.install.rapidocr.download_models.queued": "Model download task created. Files will be fetched from ModelScope and progress streamed via SSE.",
+  "ui.install.rapidocr.download_models.success": "RapidOCR models downloaded",
+  "ui.install.rapidocr.download_models.failure": "RapidOCR model download failed",
+  "ui.install.rapidocr.download_failure_proxy_hint": "Last download failed: {error}\nMainland China networks may need a proxy. You can also manually download the missing files from {source} into {dir}, then click \"Refresh Status\".",
+  "ui.install.rapidocr.download_source": "Download source",
+  "ui.first_run.action.download_rapidocr_models": "Download Models Now",
+  "ui.first_run.install_ocr.pending_models": "The selected language models ({lang} + {version}) are not downloaded. Click \"Download Models Now\" to fetch them from ModelScope (~{size} MB)."
 }