把规则、架构与实现路线写成仓库文档。

后续改内容或结算顺序时有冻结依据，不必再翻原始稿才能对齐。

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/AI.md

@@ -0,0 +1,40 @@
+# AI
+
+AI v1 consumes `Game.Core`. It does not reimplement rules.
+
+## Scope
+
+- Own current turn only
+- Not: MCTS, minimax, multi-turn planning, predicting the player’s next turn, predicting player responses, LLM play
+
+Pipeline: legal actions → simulate (`Clone` + `Execute`) → evaluate → shallow beam search → near-optimal pick.
+
+Implemented in `TurnBeamSearch` (Game.Core). Playtest client shows each AI step’s top scored candidates.
+
+## Core loop
+
+```
+state
+  → GetLegalActions
+  → simulate each action (CloneState + Execute)
+  → evaluate
+  → keep best candidates (beam width)
+  → expand
+  → stop at EndTurn or depth limit
+```
+
+After each **real** action, search again. Do not search the opponent’s next turn.
+
+## Evaluation terms
+
+`PlayerDamage`, `EnemyUnitRemoved`, `OwnBoardValue`, `EnemyBoardValue`, `Heal`, `Draw`, `Energy`, `HandValue`, `CountdownValue`, `StatusValue`.
+
+Killing the player: `WIN_SCORE` far above ordinary terms. Weights per enemy and board (e.g. more draw weight on empty hand). Do not show weights in UI.
+
+## Near-optimal randomness
+
+Compute `BestScore`. Sample uniformly (via `GameRng`) among lines with `Score >= BestScore * Threshold`. Avoids both obvious blunders and fully deterministic puppeteering.
+
+## Performance
+
+Limit beam width and action depth. Dedupe identical/equivalent states. Do not simulate player responses in v1. Deep-copy until clone/`Execute` is the measured bottleneck.