[codex] Enhance Mahjong Soul strategy tooling

[Kuma1338]

Overview

This PR turns the existing AlphaJong userscript into a more testable, Chinese-friendly, Mahjong Soul Web oriented build with safer runtime diagnostics and strategy controls.

It keeps the original algorithmic approach intact while fixing several decision-path bugs, adding regression coverage, improving 3-player handling, and making the bot easier to tune and inspect from the in-game overlay.

Packaged release for direct testing:

• https://github.com/Kuma1338/AlphaJong/releases/tag/v1.3.2-beta-cn

Highlights

Area	What changed	Impact
Runtime stability	Fixed crash and invalid-value edge cases in discard, defense, riichi and call logic	Reduces interrupted turns and broken strategy branches
Mahjong Soul compatibility	Added a compatibility checker for key Web client objects and current match state	Easier to detect when Mahjong Soul frontend changes break the script
3P / 4P support	Kept existing 3P rules and added a 3P strategy tuning profile	Better defaults for sanma without rewriting the core AI
Chinese UX	Localized user-facing controls, status text, operation names and strategy names	Easier for Chinese users to run and understand
Compact overlay	Replaced the full-width top bar with a small floating AJ launcher and compact panel	Less screen space is occupied during Mahjong Soul gameplay
Strategy tuning	Added an in-game settings panel with persistent controls	Users can tune offense, defense, riichi, calls and safety without editing source
Decision review	Added a non-blocking strategy record window	No blocking alert() popups during gameplay
Diagnostics export	Added JSON export for strategy logs and bug reports	Easier to reproduce and debug real match issues
Packaged userscript	Added build/AlphaJong_1.3.2_beta.user.js to the repository package	Users can install directly from the source package without running build.py
Release notes	Added RELEASE_NOTES_CN.md	Chinese users can review a detailed, structured changelog
Tests	Added Node regression tests for fixed bugs and new features	Prevents important regressions from returning

Fixed Bugs

Priority	File	Root cause	Fix
P1	src/ai_offense.js	Open-hand discard path referenced undefined tileLeft	Use tilesLeft and cover with regression test
P2	src/ai_defense.js	Yakuhai danger check passed (type, index) into (index, type) API	Correct argument order
P2	src/utils.js	Riichi dora-indicator branch checked .length on numeric tilePrio.dora	Use global dora.length
P2	multiple	Empty wall / empty call combinations / no possible waits could produce invalid values	Added defensive guards and regression tests

New User-Facing Features

Direct Install Package

The generated userscript is now tracked in:

build/AlphaJong_1.3.2_beta.user.js

This makes the GitHub source package immediately usable in Tampermonkey. Users no longer need to run python3 build.py just to get the installable script.

Detailed Chinese Release Notes

Added:

RELEASE_NOTES_CN.md

It documents:

• software package contents
• install path
• fixed bugs
• Mahjong Soul compatibility checks
• 3P / 4P support
• Chinese UI changes
• settings panel
• strategy record window
• export format
• memory and stability notes
• recommended tuning presets
• validation results

Compact Floating UI

The old full-width top menu has been replaced with a compact plugin-like overlay:

• collapsed state is a small square AJ button
• clicking it opens a compact control panel
• settings are shown in a single-column compact layout
• history stays in a separate non-blocking floating window
• keyboard toggle still works with numpad + / A

Settings Panel

The overlay now exposes persistent tuning controls for:

• calculation precision
• offensive efficiency
• defense weight
• sakigiri weight
• pon / chi tendency
• kan tendency
• riichi tendency
• keeping safe tiles
• tsumogiri marking
• recommendation highlighting
• 3-player strategy profile

Strategy Record Window

The 记录 button opens an in-page floating panel instead of a blocking browser popup. It supports:

• refresh
• export strategy log
• export bug report
• clear history
• close

The history is bounded to the latest 20 entries to avoid unbounded memory growth.

Bug Report Export

The exported JSON includes:

• script version
• current config snapshot
• effective 3P/4P strategy weights
• recent decisions
• last decision detail
• compatibility check result
• runtime summary
• debug string when available

Temporary download URLs are revoked after export.

Validation

python3 build.py
node --check build/AlphaJong_1.3.2_beta.user.js
node test/regression_tests.js

Full original test suite:

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

Notes

The script still depends on Mahjong Soul Web internal objects such as view.DesktopMgr, app.NetAgent, and mjcore.E_PlayOperation. The new compatibility checker is intended to make future frontend breakage easier to diagnose, but it cannot guarantee compatibility with every future Mahjong Soul update.