[codex] Enhance Mahjong Soul strategy tooling

.gitignore

@@ -1,2 +1,5 @@
-build
-.scannerwork/
+build/*
+!build/
+!build/*.user.js
+.scannerwork/
+.DS_Store

RELEASE_NOTES_CN.md

@@ -0,0 +1,294 @@
+# AlphaJong 增强版更新说明
+
+> 面向雀魂 Web 端的中文增强版：修复关键策略 BUG，补齐运行诊断、中文界面、策略调参、三麻微调和导出能力。
+
+## 一句话总结
+
+这个版本不是简单汉化，而是把原项目从“能跑的自动打牌脚本”增强成“更容易安装、测试、调参、复盘和反馈问题的雀魂 Web 自动打牌工具”。
+
+## 软件包内容
+
+| 文件 | 用途 |
+|:---|:---|
+| `build/AlphaJong_1.3.8-beta-cn.user.js` | 可直接安装到 Tampermonkey 的完整 userscript |
+| `src/*.js` | 源码模块 |
+| `test/regression_tests.js` | 新增 Node 回归测试 |
+| `readme_cn.md` | 中文使用说明和增强版概览 |
+| `RELEASE_NOTES_CN.md` | 本文件，详细更新说明 |
+
+## 安装方式
+
+1. 安装 [Tampermonkey](https://www.tampermonkey.net/?locale=zh)。
+2. 打开 `build/AlphaJong_1.3.8-beta-cn.user.js`。
+3. 复制或通过 Tampermonkey 导入该 userscript。
+4. 打开雀魂 Web 端，进入对局后点击小型 `AJ` 悬浮按钮展开 AlphaJong 面板。
+
+## 核心更新
+
+### 1. 修复关键 BUG
+
+| 优先级 | 位置 | 问题 | 修复 |
+|:---|:---|:---|:---|
+| P1 | `src/ai_offense.js` | 开副露手牌在特定弃牌路径会访问不存在的 `tileLeft`，导致 `ReferenceError` 并中断出牌 | 改为正确的 `tilesLeft`，并加入回归测试 |
+| P2 | `src/ai_defense.js` | 役牌危险度加成调用参数顺序错误，导致字牌可用枚数始终错误 | 修正 `getNumberOfTilesAvailable(index, type)` 参数顺序 |
+| P2 | `src/utils.js` | 立直判断误把数值型 `tilePrio.dora` 当数组读取 `.length`，导致多宝牌指示牌分支永远不触发 | 改用全局 `dora.length` |
+| P2 | 多处 | 空牌墙、无可能听牌、空鸣牌组合等边界可能导致异常或无效数值 | 增加保护逻辑，避免 `Infinity`、`NaN` 和异常 |
+
+### 2. 雀魂 Web 端兼容性检查
+
+新增 `检查` 按钮，会检查：
+
+- `GameMgr`
+- `view.DesktopMgr`
+- `app.NetAgent`
+- `mjcore.E_PlayOperation`
+- `uiscript`
+- 房间配置
+- 对局内操作列表
+- 玩家数据
+- 手牌数据
+- 弃牌 API
+
+对局中还会显示：
+
+- 当前几人场
+- 剩余牌数
+- 可操作项数量
+- 当前房间编号
+
+### 3. 三麻 / 四麻适配增强
+
+原项目已经有三麻基础规则，本版本继续保留并增强：
+
+- 自动判断 3 人 / 4 人玩法
+- 三麻 2m-8m 不可用
+- 三麻北宝牌处理
+- 三麻拔北逻辑
+- 三麻牌山数量 55，四麻 70
+- 三麻只计算两名对手的危险度
+- 新增 `三麻策略微调` 开关
+
+三麻策略微调开启时：
+
+- 防守权重略微提高
+- 鸣牌倾向略微提高
+- 立直倾向略微提高
+
+这样做是保守增强，不会重写核心 AI，也尽量避免破坏原项目测试。
+
+### 4. 中文用户界面
+
+用户层可见内容已中文化：
+
+- `启动 / 暂停`
+- `自动 / 辅助`
+- `自动开局`
+- `检查`
+- `设置`
+- `记录`
+- `调试`
+- `收起`
+- `弃牌 / 吃 / 碰 / 杠 / 立直 / 自摸 / 荣和 / 九种九牌 / 拔北`
+- `常规 / 七对子 / 弃和防守 / 国士无双`
+
+控制台内部调试日志仍保留部分英文，便于和原项目代码对应。
+
+### 5. 策略设置面板
+
+新增 `设置` 小面板，支持网页内直接调整并持久保存：
+
+| 参数 | 作用 |
+|:---|:---|
+| 计算精度 | 影响计算深度和耗时 |
+| 进攻效率 | 越高越重视速度和牌效 |
+| 防守权重 | 越高越容易弃和防守 |
+| 先切权重 | 越高越倾向提前处理危险牌 |
+| 鸣牌倾向 | 越高越容易吃碰 |
+| 杠牌倾向 | 越高越容易杠 |
+| 立直倾向 | 越高越容易立直 |
+| 保留安牌 | 尽量留安全牌给防守 |
+| 标记摸切 | 标记对手摸切牌 |
+| 辅助高亮推荐牌 | 辅助模式下高亮推荐弃牌 |
+| 三麻策略微调 | 三麻场启用专门权重修正 |
+
+`v1.3.8-beta-cn` 起，数值参数支持手动输入，精度为 `0.01`，并带有上下限保护。设置面板还新增一键预设：
+
+- 稳健防守
+- 避四少放铳
+- 快速和牌
+- 三麻进攻
+
+### 6. 小型悬浮插件 UI
+
+原版 UI 会占用网页顶部一整条空间。本版本改为更小巧的悬浮插件：
+
+- 默认只显示一个 `46px × 46px` 的 `AJ` 方形入口。
+- 点击 `AJ` 后展开紧凑控制面板。
+- `AJ` 方形入口和展开面板标题栏可拖动移动。
+- 拖动后的位置会保存到浏览器本地，下次打开仍在原位置。
+- 启动、模式、检查、设置、记录、收起等功能集中在小面板内。
+- 设置面板改为单列紧凑布局，适配小窗口。
+- 设置面板增加最大高度和内部滚动，适配小分辨率屏幕。
+- 只保留顶部 `收起` 按钮，避免重复按钮。
+- 状态栏不再占满顶部，长状态文本可以通过鼠标悬停查看完整内容。
+- 按小键盘 `+` 或 `A` 仍可展开 / 收起。
+
+### 7. 非阻塞策略记录窗口
+
+新增 `记录` 小窗口，取代会卡住网页的 `alert()` 弹窗。
+
+功能：
+
+- 查看最近 20 次决策
+- 查看最近对局名次 / 分数
+- 刷新记录
+- 清空记录
+- 清空对局结果
+- 导出策略记录
+- 导出完整日志
+- 导出对局结果
+- 导出 BUG 数据
+- 关闭窗口
+
+记录窗口不会阻塞雀魂页面刷新和动画。
+
+`策略记录` 和 `牌局信息` 窗口都支持拖动，拖动后位置会保存。
+
+### 8. 牌局信息窗口
+
+新增 `牌局` 小窗口，用于快速查看当前对局全局状态：
+
+- 当前几人场、剩余牌数、房间、场风 / 自风
+- 宝牌指示牌
+- 自家名次、分数和相邻分差
+- 各家分数、立直、鸣牌、弃牌
+- 剩余牌数量摘要
+- 安全牌 / 危险牌摘要
+
+该窗口只读取当前雀魂 Web 端状态，不会触发自动操作。
+
+### 9. 导出策略记录和 BUG 数据
+
+#### 导出策略记录
+
+包含：
+
+- 导出时间
+- 脚本版本
+- 当前设置快照
+- 最近决策记录
+- 最近对局结果
+- 完整策略日志
+
+#### 导出 BUG 数据
+
+额外包含：
+
+- 兼容性检查结果
+- 当前运行态摘要
+- 最后一次决策详情
+- 当前调试串
+
+导出使用临时 `Blob URL`，下载后会释放，避免长期占用内存。
+
+### 10. 对局结果保存
+
+新增每局结算后的排名记录：
+
+- 保存结束时间
+- 保存三麻 / 四麻模式
+- 保存自家名次和分数
+- 保存各家分数、立直、鸣牌、弃牌
+- 保存当局最近策略决策和日志
+
+同时修复结算页分数动画或界面刷新导致同一局被重复记录的问题。
+
+### 11. 内存和稳定性优化
+
+- 决策记录限制为最近 20 条，避免无限增长。
+- 策略日志限制为最近 500 条，避免长时间运行无限增长。
+- 对局结果限制为最近 50 局。
+- 导出数据时复制记录数组，避免导出对象和运行态互相牵连。
+- 导出后释放临时 URL。
+- 收起主界面时同步关闭记录浮窗和牌局信息浮窗。
+- 雀魂弃牌追踪钩子按实际对象实例判断是否已挂载，减少换局后钩子失效或重复挂载风险。
+- 活动相关自动按钮暂时关闭，避免误识别影响雀魂 Web 正常操作。
+
+## 推荐参数
+
+### 新手稳健配置
+
+| 参数 | 建议 |
+|:---|:---|
+| 计算精度 | `3` |
+| 进攻效率 | `1.0` |
+| 防守权重 | `1.1` |
+| 先切权重 | `1.0` |
+| 鸣牌倾向 | `0.9` |
+| 杠牌倾向 | `0.6` |
+| 立直倾向 | `1.0` |
+| 保留安牌 | 开 |
+| 三麻策略微调 | 开 |
+
+### 少点炮配置
+
+| 参数 | 建议 |
+|:---|:---|
+| 防守权重 | `1.2 - 1.4` |
+| 鸣牌倾向 | `0.7 - 0.9` |
+| 杠牌倾向 | `0.3 - 0.6` |
+| 保留安牌 | 开 |
+
+### 更进攻配置
+
+| 参数 | 建议 |
+|:---|:---|
+| 进攻效率 | `1.1 - 1.3` |
+| 鸣牌倾向 | `1.0 - 1.2` |
+| 立直倾向 | `1.1` |
+| 防守权重 | `0.8 - 1.0` |
+
+## 验证结果
+
+```text
+python3 build.py
+node --check build/AlphaJong_1.3.8-beta-cn.user.js
+node test/regression_tests.js
+```
+
+新增回归测试通过：
+
+```text
+Regression tests passed.
+```
+
+原项目完整测试集通过：
+
+```text
+Efficiency: 17/17 passed
+Defense: 10/10 passed
+Dora: 5/5 passed
+Yaku: 19/19 passed
+Strategy: 4/4 passed
+Waits: 6/6 passed
+Call: 7/7 passed
+Issue: 5/5 passed
+Example: 7/7 passed
+```
+
+## 已知风险
+
+AlphaJong 依赖雀魂 Web 前端内部对象，例如：
+
+- `view.DesktopMgr`
+- `app.NetAgent`
+- `mjcore.E_PlayOperation`
+- `uiscript`
+
+如果雀魂更新前端结构，脚本可能需要重新适配。遇到问题时，请优先使用：
+
+1. `检查`
+2. `记录`
+3. `导出BUG数据`
+
+然后用导出的 JSON 复盘或反馈。

build.py

@@ -11,7 +11,7 @@ def addFileToString(inputString, filename):
 
     return inputString
 
-VERSION = "1.3.2_beta"
+VERSION = "1.3.8-beta-cn"
 
 data = f"""// ==UserScript==
 // @name         AlphaJong