lioensky · lioensky · Mar 3, 2026 · Mar 3, 2026 · Mar 3, 2026
diff --git a/Plugin/JapaneseHelper/JapaneseHelper.py b/Plugin/JapaneseHelper/JapaneseHelper.py
diff --git a/Plugin/JapaneseHelper/README.md b/Plugin/JapaneseHelper/README.md
@@ -0,0 +1,137 @@
+# JapaneseHelper 日语学习插件 (VCP)
+
+本插件是面向 VCP 工具链的日语学习增强插件，围绕“**一句话输入 → 解析理解 → 练习测验 → 复习巩固**”构建完整学习闭环。
+
+**核心定位**：无需额外改造调用链，接入 `JapaneseHelper` 后即可获得句子解析、查词消歧、语法讲解、测验、SRS 复习与学习数据管理能力。
+
+## 功能与相比基础查词工具的加强点
+
+- **句子级理解**：支持分词、词性、原形、读音、释义与句法提示（`analyze_sentence`）。
+- **假名标注**：支持整句振假名标注，Sudachi 优先并自动 fallback（`add_furigana`）。
+- **语法解释**：输出语法点含义、接续、易错点、例句、JLPT 参考等级（`grammar_explain`）。
+- **助词与改写**：支持助词启发式检查与文体改写（敬体/简体/书面）（`particle_check` / `rewrite_sentence`）。
+- **查词增强**：本地词典 + 在线并联检索，支持 `race/aggregate`、上下文轻量消歧（`lookup_word` / `lookup_word_json`）。
+- **JLPT 能力**：整句 JLPT 分级标注与词汇提取优先级建议（`jlpt_tag` / `extract_vocab`）。
+- **活用与声调**：支持动词活用还原与重音查询（`conjugate_verb` / `pitch_accent`）。
+- **测验系统**：自动出题、单题判题、批量判题、易混项训练与错因解释（`quiz_generate` / `quiz_check` / `quiz_check_batch` / `minimal_pair_quiz` / `error_explain`）。
+- **双复习排程**：支持 SM-2 与 FSRS 简化排程并存（`srs_schedule` / `fsrs_schedule`）。
+- **学习数据闭环**：错题本、学习会话、进度报告、自定义词典、导入导出、健康检查一体化（`wrongbook_*` / `study_session_*` / `lexicon_*` / `import_export_data` / `health_check`）。
+
+## 安装与使用
+
+1. 将本目录放置于 VCP 的 `Plugin` 目录中（或保持当前目录结构）。
+2. 安装依赖：`pip install -r requirements.txt`
+3. 在 `config.env` 中按需配置在线查询、缓存与日志参数。
+4. 确保 `plugin-manifest.json` 已被 VCP 正确识别并加载。
+
+## 配置说明（config.env 常用项）
+
+```env
+REQUEST_TIMEOUT=10
+JISHO_API_ENABLED=true
+SUDACHI_SPLIT_MODE=C
+USER_LEXICON_PATH=./user_lexicon.json
+DOMAIN_LEXICON_PATH=./domain_lexicon.json
+
+ONLINE_DICT_MODE=race
+ONLINE_DICT_TIMEOUT=1.2
+ONLINE_DICT_GLOBAL_TIMEOUT=2.5
+ONLINE_DICT_RETRY=1
+
+ONLINE_CACHE_TTL_SEC=86400
+ONLINE_CACHE_MAX_ITEMS=2000
+ONLINE_CACHE_FLUSH_INTERVAL_SEC=2.0
+ONLINE_CACHE_STALE_IF_ERROR_SEC=600
+
+OBSERVABILITY_LOG_PATH=./observability.log
+```
+
+## AI 调用工具说明
+
+### 1.1 JapaneseHelper（通用学习入口）
+
+**说明**：通过 `command` 指定具体能力。  
+**调用格式**：
+
+```text
+tool_name: JapaneseHelper,
+command: [具体指令],
+text: [可选，句子/文本],
+word: [可选，单词],
+...其它参数按 command 传入
+```
+
+---
+
+### 1.2 句子解析（analyze_sentence）
+
+**说明**：解析句子并给出词项信息。  
+**示例**：
+
+```text
+tool_name: JapaneseHelper,
+command: analyze_sentence,
+text: 昨日友達と映画を見に行きました。
+```
+
+### 1.3 查词（lookup_word / lookup_word_json）
+
+**说明**：查词并支持并联在线检索与轻量消歧。  
+**示例**：
+
+```text
+tool_name: JapaneseHelper,
+command: lookup_word,
+word: 利害関係者,
+use_parallel_online: true,
+force_online: true,
+online_mode: aggregate
+```
+
+```text
+tool_name: JapaneseHelper,
+command: lookup_word_json,
+word: 勉強,
+context: 私は毎日日本語を勉強しています。
+```
+
+### 1.4 语法讲解（grammar_explain）
+
+```text
+tool_name: JapaneseHelper,
+command: grammar_explain,
+text: 私は毎日日本語を勉強しています。
+```
+
+### 1.5 批量判题（quiz_check_batch）
+
+**说明**：支持 `answers/user_answers` 与 `expected_answers/correct_answers` 双别名参数。  
+**示例**：
+
+```text
+tool_name: JapaneseHelper,
+command: quiz_check_batch,
+answers: 昨日,日本語,行く,
+expected_answers: 昨日,日本語,行く,
+readings: きのう,にほんご,いく
+```
+
+### 1.6 学习会话（study_session_start）
+
+```text
+tool_name: JapaneseHelper,
+command: study_session_start,
+text: 私は毎日日本語を勉強しています。,
+count: 5,
+adaptive: true
+```
+
+## 重要提示
+
+1. `lookup_word_json` 返回结构化结果，更适合前端直接渲染。  
+2. 在线查询链路建议结合缓存参数使用，以平衡延迟与稳定性。  
+3. 训练场景建议结合：`extract_vocab` → `quiz_generate` → `quiz_check_batch` → `srs_schedule/fsrs_schedule`。
+
+## 一句话总结
+
+**JapaneseHelper = 面向 VCP 的一站式日语学习插件：能拆句、能查词、能讲语法、能出题、能复习，并具备长期学习数据管理能力。**
diff --git a/Plugin/JapaneseHelper/config.env b/Plugin/JapaneseHelper/config.env
@@ -0,0 +1,28 @@
+# JapaneseHelper optional config
+REQUEST_TIMEOUT=10
+JISHO_API_ENABLED=true
+SUDACHI_SPLIT_MODE=C
+USER_LEXICON_PATH=./user_lexicon.json
+DOMAIN_LEXICON_PATH=./domain_lexicon.json
+ENABLE_ADAPTIVE_SESSION=true
+
+# Online dictionary parallel mode
+ONLINE_DICT_MODE=race
+ONLINE_DICT_TIMEOUT=1.2
+ONLINE_DICT_GLOBAL_TIMEOUT=2.5
+ONLINE_DICT_RETRY=1
+ONLINE_CACHE_TTL_SEC=86400
+ONLINE_PROVIDER_ORDER=jisho,jotoba
+JOTOBA_API_ENABLED=false
+
+# P0 stability knobs
+ONLINE_CACHE_MAX_ITEMS=2000
+ONLINE_CACHE_FLUSH_INTERVAL_SEC=2.0
+ONLINE_CACHE_STALE_IF_ERROR_SEC=600
+ONLINE_CACHE_LOCK_TIMEOUT_SEC=2.0
+ONLINE_DICT_BACKOFF_BASE_SEC=0.15
+ONLINE_DICT_BACKOFF_MAX_SEC=1.2
+ONLINE_PROVIDER_CB_FAIL_THRESHOLD=3
+ONLINE_PROVIDER_CB_COOLDOWN_SEC=20
+ONLINE_PROVIDER_CB_HALFOPEN_PROB=0.25
+OBSERVABILITY_LOG_PATH=./observability.log
diff --git a/Plugin/JapaneseHelper/config.env.example b/Plugin/JapaneseHelper/config.env.example
@@ -0,0 +1,53 @@
+# JapaneseHelper 可选配置
+
+# 基础请求超时（单位：秒）
+REQUEST_TIMEOUT=10
+# 是否启用 Jisho 在线词典
+JISHO_API_ENABLED=true
+# Sudachi 分词模式（A/B/C，C 最粗粒度）
+SUDACHI_SPLIT_MODE=C
+# 用户自定义词典路径
+USER_LEXICON_PATH=./user_lexicon.json
+# 领域词典路径（如商务/医疗等术语）
+DOMAIN_LEXICON_PATH=./domain_lexicon.json
+# 是否启用自适应学习会话
+ENABLE_ADAPTIVE_SESSION=true
+
+# 在线词典并行查询模式（race=谁快用谁，aggregate=聚合结果）
+ONLINE_DICT_MODE=race
+# 单个在线词典请求超时（秒）
+ONLINE_DICT_TIMEOUT=1.2
+# 整体并行查询全局超时（秒）
+ONLINE_DICT_GLOBAL_TIMEOUT=2.5
+# 在线请求失败后的重试次数
+ONLINE_DICT_RETRY=1
+# 在线缓存有效期 TTL（秒，86400=1天）
+ONLINE_CACHE_TTL_SEC=86400
+# 在线词典提供方顺序（按优先级）
+ONLINE_PROVIDER_ORDER=jisho,jotoba
+# 是否启用 Jotoba 词典
+JOTOBA_API_ENABLED=false
+
+# ===== P0 稳定性参数（高优先级稳定性开关）=====
+# 在线缓存最大条目数（LRU）
+ONLINE_CACHE_MAX_ITEMS=2000
+# 缓存落盘刷新间隔（秒）
+ONLINE_CACHE_FLUSH_INTERVAL_SEC=2.0
+# 在线服务异常时，允许返回过期缓存的时间窗口（秒）
+ONLINE_CACHE_STALE_IF_ERROR_SEC=600
+# 缓存文件锁等待超时（秒）
+ONLINE_CACHE_LOCK_TIMEOUT_SEC=2.0
+# 重试退避基础时间（秒）
+ONLINE_DICT_BACKOFF_BASE_SEC=0.15
+# 重试退避最大时间（秒）
+ONLINE_DICT_BACKOFF_MAX_SEC=1.2
+# 熔断触发阈值（连续失败次数）
+ONLINE_PROVIDER_CB_FAIL_THRESHOLD=3
+# 熔断后冷却时间（秒）
+ONLINE_PROVIDER_CB_COOLDOWN_SEC=20
+# 半开状态探活概率（0~1）
+ONLINE_PROVIDER_CB_HALFOPEN_PROB=0.25
+# Provider 状态落盘刷新间隔（秒）
+ONLINE_PROVIDER_STATE_FLUSH_INTERVAL_SEC=1.0
+# 可观测日志输出路径
+OBSERVABILITY_LOG_PATH=./observability.log
diff --git a/Plugin/JapaneseHelper/install_plugin_requirements.bat b/Plugin/JapaneseHelper/install_plugin_requirements.bat
@@ -0,0 +1,99 @@
+@echo off
+setlocal EnableExtensions
+
+REM ===== Click-safe relaunch: force a persistent cmd window =====
+if /I not "%~1"=="__KEEP__" (
+  start "JapaneseHelper Installer" cmd /k ""%~f0" __KEEP__ %*"
+  exit /b 0
+)
+
+shift
+chcp 65001 >nul
+title JapaneseHelper Installer (Persistent)
+
+set "SCRIPT_DIR=%~dp0"
+set "PS1=%SCRIPT_DIR%install_plugin_requirements.ps1"
+set "MODE=%~1"
+set "DOCKER_CID=%~2"
+set "PYTHON_EXE=%~3"
+
+if "%MODE%"=="" set "MODE=menu"
+if "%PYTHON_EXE%"=="" set "PYTHON_EXE=python"
+
+set "LOG_DIR=%SCRIPT_DIR%logs"
+if not exist "%LOG_DIR%" mkdir "%LOG_DIR%" >nul 2>nul
+set "BOOT_LOG=%LOG_DIR%\bootstrap_latest.log"
+set "LOG_FILE=%LOG_DIR%\install_latest.log"
+
+(
+  echo [BOOT] %DATE% %TIME%
+  echo [BOOT] Script=%~f0
+  echo [BOOT] Mode=%MODE%
+  echo [BOOT] DockerCID=%DOCKER_CID%
+  echo [BOOT] PythonExe=%PYTHON_EXE%
+) > "%BOOT_LOG%" 2>&1
+
+if not exist "%PS1%" (
+  echo [ERROR] Missing PowerShell script: "%PS1%"
+  echo [ERROR] Missing PowerShell script: "%PS1%" >> "%BOOT_LOG%"
+  goto :finish
+)
+
+if /I "%MODE%"=="menu" goto :menu
+if /I "%MODE%"=="auto" goto :run
+if /I "%MODE%"=="host" goto :run
+if /I "%MODE%"=="docker" goto :run
+set "MODE=menu"
+goto :menu
+
+:menu
+echo.
+echo ============ JapaneseHelper Installer ============
+echo [1] auto   (prefer docker, fallback host)
+echo [2] host   (install on host python)
+echo [3] docker (install in running container)
+echo [4] exit
+echo.
+set /p PICK=Choose 1/2/3/4: 
+if "%PICK%"=="1" set "MODE=auto" & goto :run
+if "%PICK%"=="2" set "MODE=host" & goto :run
+if "%PICK%"=="3" set "MODE=docker" & goto :run
+if "%PICK%"=="4" goto :finish
+echo Invalid input.
+goto :menu
+
+:run
+echo ===== START %DATE% %TIME% ===== > "%LOG_FILE%"
+echo MODE=%MODE% >> "%LOG_FILE%"
+echo DOCKER_CID=%DOCKER_CID% >> "%LOG_FILE%"
+echo PYTHON_EXE=%PYTHON_EXE% >> "%LOG_FILE%"
+
+if /I "%MODE%"=="docker" (
+  if not "%DOCKER_CID%"=="" (
+    powershell -NoProfile -ExecutionPolicy Bypass -File "%PS1%" -Mode docker -DockerContainerId "%DOCKER_CID%" -PythonExe "%PYTHON_EXE%" -UseTsinghuaMirror -BreakSystemPackages -UpgradePip >> "%LOG_FILE%" 2>&1
+  ) else (
+    powershell -NoProfile -ExecutionPolicy Bypass -File "%PS1%" -Mode docker -PythonExe "%PYTHON_EXE%" -UseTsinghuaMirror -BreakSystemPackages -UpgradePip >> "%LOG_FILE%" 2>&1
+  )
+) else (
+  powershell -NoProfile -ExecutionPolicy Bypass -File "%PS1%" -Mode %MODE% -PythonExe "%PYTHON_EXE%" -UseTsinghuaMirror -BreakSystemPackages -UpgradePip >> "%LOG_FILE%" 2>&1
+)
+
+set "RC=%ERRORLEVEL%"
+echo ===== END RC=%RC% %DATE% %TIME% ===== >> "%LOG_FILE%"
+
+echo.
+echo ---------- INSTALL LOG BEGIN ----------
+type "%LOG_FILE%"
+echo ---------- INSTALL LOG END ------------
+
+if "%RC%"=="0" (
+  echo [OK] Install finished.
+) else (
+  echo [ERROR] Install failed. RC=%RC%
+)
+
+:finish
+echo.
+echo [INFO] BOOT_LOG : "%BOOT_LOG%"
+echo [INFO] INSTALL_LOG: "%LOG_FILE%"
+echo [INFO] You can close this window safely.