AI algorithm

StrongStrategy is the default solo autoplay pipeline (no LLM). Maintainer deep-dive: code under src/AI/, regression via tools/ai-bench/, mod hooks in Mod AI integration. Full write-up in Chinese below.

DevMode AI Host → AutoPlay 默认使用 StrongStrategy（设置项 AutoPlayStrategy: Strong）。这是一套纯规则、无 LLM 的单机自动化决策管线，目标是在 A10 左右具备可玩的宏观路线与战斗表现。

相关代码：src/AI/ · 回归脚本：tools/ai-bench/ · Mod 扩展说明：Mod AI 集成

策略解析顺序（Companion / 多人场景同样适用）：netId 注册表 → 角色 CharacterAiRegistry → 默认 StrongStrategy（AutoPlayStrategy=Simple 时回退 SimpleStrategy）。

1. 单机 Run 开始且 AutoPlayEnabled=true 时，AiPlayModule 启动 GameLoop。
2. 每 PollIntervalMs 轮询一次当前 GamePhase；Harmony patch 也会在决策点调用 OnDecisionPoint。
3. Sts2StateProvider 调用 GameSnapshot.Capture，再经 GameSnapshotPhaseCapture.Enrich 补充 overlay 数据。
4. IDecisionMaker.DecideAsync 返回 GameAction（含 Type、TargetIndex、Reason）。
5. Sts2ActionExecutor 执行动作；Reason 写入日志，便于复盘。

多人 hand-play 时 AutoPlay 自动关闭；LAN / Pseudo Co-op 走独立队列，见 LAN host-drive & AFK co-op。

Mod 扩展写入 snapshot["extensions"][yourKey]，StrongStrategy 不会读取 mod 专有字段，需注册自定义 IDecisionMaker 或 IAiMoveModifier（经 SimMoveScoring 作用于 beam / QuickScore）。

DeckPlanInferer.Infer(snapshot) 在每次宏观决策前构建规划，供所有 Scorer 共用。

• Attack +1.0，Block +0.8，Draw +0.6
• 牌组含 ≥3 张 Exhaust 卡或 Exhaust 遗物 → Exhaust +1.2
• A7+ → Block +0.4；A10+ → Attack +0.3

最后调用 DeckPlanContributorHub：原版五角色在 src/AI/Characters/Vanilla/*Pack.cs 注册额外权重与 TargetDeckSize（Silent/Defect 15、Ironclad 17、Necrobinder/Regent 16）。

离线从 Spire Codex A10 宏观样本训练（tools/codex-train/ → 嵌入 src/AI/Data/codex-priors.json）。启动时由 AiKnowledgeBootstrap 加载；不替代规则层，只在各 *Scorer 上叠加有界 bonus（±15，× CodexPriorWeight，默认 1，settings.json 可调 0 关闭）。

NormalizeContext 支持 shop、event、combat_reward（此前 event 被误映射为 combat_reward，已修复）。

重训流程：tools/codex-crawl export-parquet → uv run codex-train --parquet ../codex-crawl/data/macro_samples.parquet train → dotnet build。

Holdout（v1，4944 runs）：card_choice top-1 56.7%（随机 33%）；rest 60.4%。

DeckEvaluator.Evaluate(snapshot, plan) 是删牌 / skip / 选牌删谁 的单一真相源（src/AI/Planning/DeckEvaluator.cs）。

DeckPlan 续航目标（*Pack.cs）：Silent block/draw 1/3；Ironclad/Defect 2/2；默认 block/draw 2/2。Strike/Defend 目标：Silent 0/1；Ironclad 2/2。

宏观选牌续航 bonus（MacroScorerHelper）：过渡防 +6+BlockDeficit×4；抽牌源 +4+DrawDeficit×3。Skip：BlockDeficit≥2 → −6；DrawDeficit≥2 且 deck 厚 → −4；续航满且 MeanValue≥12 → +4。

已在牌组内的卡，不含 dilution 项，但含冗余惩罚：

RemovalUplift = (MeanValue - WorstValue)
              + StarterBloat × 4
              + round(DilutionPenalty(deckSize))
              + FutureThinBonus(actIndex, floor)
              + round(CardsNeedingBurn × 1.5)

• StarterBloat：StrikeSurplus + DefendSurplus×0.8 + 每张诅咒 +3（目标来自 TargetStrikeCount / TargetDefendCount）
• CardsNeedingBurn：ThinGap + StrikeSurplus + DefendSurplus；若 IsExhaustFocused，再加 max(0, nonExhaustFiller − ExhaustCount×2)
• FutureThinBonus：Act1 +5/+3，Act2 +2，Act3 +0（越早删，长期收益越高）
• 门槛：RemovalUplift < MinRemovalUplift(11) 时不买商店删牌（无 deckSize 硬门槛）

示例：12 张牌、4 Strike、均分 14、最差 Strike 值 2 → uplift ≈ (14−2)+8+future ≈ 24，小卡组仍会删 Strike。

Attack, Block, Draw, Exhaust, Scaling, Thin, Energy, Aoe, Setup, Utility

• 启动时在 ModelDb.Init 之后索引全卡（AiKnowledgeBootstrap + ModelDbInitPatch）。
• CardTagRules 从 卡 id 前缀、CardType、CardKeyword（Exhaust/Retain 等）推断 tag，避免逐卡硬编码。
• CardMechanicIndex + OfficialMechanicProbe：CardKeyword / DynamicVars / 类型图 / LocString key / 字段引用 → CardMechanicFlags（含 AddsCardsToDeck 如劫掠）；DeckSynergyEvaluator 按机制类型算 deck 协同；仅无结构信号时才用英文描述 fallback。
• Mod 可通过 ICardTagProvider 合并额外 tag。

• 从遗物 id 推断 tag（如 Exhaust、Thin），用于 DeckPlanInferer 与遗物评分。
• RelicMechanicIndex 通过 OfficialMechanicProbe 解析 RelicModel 结构与 loc key（如 HeftyTablet → 稀有三选一 + Injury）；描述文本为最后兜底。

用于 deckSelectContext == "reward"。

单卡得分（MacroScorerHelper.ScoreCardOffer）— 边际牌组模型：

marginal = DeckQualityScore(deck ∪ {card}) − DeckQualityScore(deck)
score    = marginal
         + DeckSynergyEvaluator（机制协同，如变形×攻击池）
         + ScoreDeckDilutionOffer（AddsCardsToDeck 如劫掠）
         + EarlyCardRewardAdjustments
         + CodexBonus × deckFitFactor

DeckQualityScore 综合 TotalValue、MeanValue、DilutionPenalty、SurvivalGap、StarterBloat、ConsistencyScore（与删牌评估同一套 DeckEvaluator）。

deckFitFactor：缺口已填（BlockDeficit=0 且 DrawDeficit=0）、ThinGap>0、MeanValue≥12、已有变形核心且候选非变形 → 衰减 Codex 先验。

RarityScore（在 ScoreInDeck 内）：Ancient 30 · Rare 25 · Uncommon 15 · Common 8 · Starter 3 · Event 12

跳过逻辑（DeckEvaluator.SkipOpportunityCost，与边际 pick 同一质量模型）：

skipScore = ThinPreference×14
          + DilutionPenalty×8
          + ThinGap×3
          + max(0, DeckSize − TargetDeckSize)×2
          + max(0, DeckQualityScore/DeckSize − 12)×2
          + (SurvivalGap=0 ? 5 : 0)
          + 后期 act/floor 加厚项
          + Codex skip offset

• StarterBloat≥3 / StrikeSurplus≥3 → 降低 skip（更倾向拿牌或去删敲）
• SurvivalGap≥2 且 BlockDeficit≥2 → 降低 skip（前期仍缺过渡）
• exhaust 构筑且 CardsNeedingBurn≥5 → +8 skip
• 若 bestScore < max(MinPickScore, skipScore) → SkipCardReward（日志含 quality / thin / survival）

由 deckSelectContext 分流：

篝火 smith 实际由 CardSelectCmd → AiCombatCardSelector 选牌（非 UI 点击路径时也走同一评分）。ScoreUpgradeCandidate = ScoreInDeck + 机制协同 + 变形/脆弱加分 − strike/defend/基础牌惩罚。

约束：购物后至少保留 MinGoldAfterShopping = 25 金币。

删牌分（边际对比，非牌数门槛）：

removeScore = RemovalUplift - cost/4 - OpportunityCost + 金币充裕加成

• RemovalUplift < 11 → 不删
• OpportunityCost：Act3 或 gold 紧张时额外扣分（留金给后续商店）
• 日志示例：Remove [Strike] uplift=28 strikes+2 burnDebt=5 score=24 vs buy=relic(22)

购买分：

• card → ScoreCardOffer − cost/8
• relic → ScoreRelicOffer − cost/12
• potion → PotionInventoryScorer.ValueOffer − cost/25（瓶满且不值得腾槽 → 0）

决策：若 removeScore > 0 且 removeScore ≥ bestPurchaseScore → 删牌；否则买最高分商品；都不值得 → LeaveShop。

购买 TargetIndex 与快照一致：仅计 card/relic/potion 顺序，不含 removal slot。

1. restProceedReady 或 无 rest 选项 → 立即 Proceed 离开。
2. heal 已消耗（healIdx < 0）→ 仅 HP≥75% 且有升级目标时 smith，否则 Proceed（避免 heal 后 poll 误触 SMITH）。
3. 否则按 HP、路径与选项 id：
   • HP <55%，或 HP <70% 且 planner 下一步为 Elite → heal
   • Codex rest prior（HP 45–85%）；若 prior 为 SMITH 且 HP<75% 且下一步 Elite → 跳过 prior
   • HP≥75% 且无 Elite ahead → smith（有升级目标）
   • HP <75% → heal
   • 否则 smith 或 Proceed

TargetIndex 为休息站按钮在 UI 中的绝对索引（与快照 restOptions[].index 对齐）。

score = RarityScore + Σ(plan.GetWeight(tag) × 3) + CodexRelicBonus(context)

已拥有同名/id → −100。context 来自快照 relicChoiceContext（EventRoom → event，Boss/精英 → combat_reward），同一遗物在 event/combat 下 Codex bonus 可不同。

替代原单步贪心 MapScorer：对 RunState.Map 做 Boss 后向 DP（DAG 拓扑序 O(V+E)），选「当前 → Boss 总分最高」路径上的下一步。

文献依据：STS 地图为 DAG，MIT 15.053 最长路径 DP；Bazzaz & Cooper (FDG 2025) 路径枚举；Miles Oram macro 三要素 flexibility/safety/resource。

算法：

bestToBoss(p) = nodeScore(p, ctx) + max_{c ∈ children} ( edgeBonus(p,c) + bestToBoss(c) )

• ctx = MapRouteContext（HP、gold、DeckPlan、DeckMetrics、WantsShopRemoval）
• 决策：从当前位置选 argmax bestToBoss(child)；日志 path=Rest→Shop→M→…

MapNodeWeightScorer 节点分（动态）：

邻接边加成：Rest→Elite（低 HP −10）；Shop→*（需删牌 +6）；Elite→Elite（低 HP −12）；Rest→Rest −5；Treasure→Elite +4；pathRisk 高时 Rest→Elite、Elite→Elite 额外扣分。

连战续航（MapSurvivalIndex + PathSurvivalRisk）：

• 自 Boss 行反向 DP：每格 CombatsToRest（到下 Rest 的预期战斗数）、ElitesToRest
• 战斗权重：M/Elite=1，Unknown=0.7，Ancient=0.5
• PathRisk = combats×10×blockFactor×drawFactor×hpFactor + elites×12×hpFactor（block/draw deficit 来自 DeckMetrics）
• DP 选边时对 child 叠加 PathRiskNodeAdjust：Rest +risk；Elite −risk；Monster/Shop/Unknown 高压时略降
• 日志：risk=N fightsToRest=M blockDef=D；Rest 在 CombatsToRest≥3 && BlockDeficit≥1 时 heal 阈值 55%→65%

MapScorer：委托 MapPathPlanner；无 run 数据时 greedy fallback。

地图画线（仅 AutoPlayEnabled + loop 运行中）：

• 打开地图：MapPathPlanner.Plan + MapPathOverlay 将规划边染为金色
• 关闭地图：恢复 path dot 原色；MapPathPlanner.ClearCache

源码：MapPathPlanner.cs、MapNodeWeightScorer.cs、MapPathOverlay.cs

• 识别 Neow（eventId 或 option textKey 含 NEOW）。
• 快照 eventOptions[] 含 optionKey（EventOptionInfer：textKey/modelId/中文标题）。
• 评分：keyword baseline + GetEventOptionBonus（无 event prior 时 fallback GetRelicBonus）+ DeckSynergyEvaluator 机制分（遗物/卡选项）。
• 当 event prior n≥20 时 Codex 权重 ×1.5（codex_primary 模式，keyword 降为 baseline 10）。
• Reason 日志：Neow pick [title] score=N key=HEFTY_TABLET codex=+4 synergy=+12 codex_primary。
• 普通事件同样接 GetEventOptionBonus；无 prior 时保留关键词兜底。

主战斗决策只信 beam + 贪心线评估；CanSkipBlockForKill / CombatScorer 不参与起手选择。

贪心攻击（本回合有伤害时）：OrderEnemiesForGreedyAttacks 先打 EffectiveIncoming>0 的敌人；incomingSlack=0（不为集火容忍本回合挨打）。攻击清掉威胁后 SimulateGreedyBlock 不跑 → 线评估自然体现「能杀就不防」。

快路径启发式（不决定 beam 起手，仅辅助排序 / fallback / 药水）：

启动时 PotionMechanicIndex 索引官方 PotionModel（category / usage / rarity）；PotionTierCatalog 提供 retain 分（potion-tiers.json）。

对 potions[] 每格按 category + IntentCalculator + DeckPlan 打分，日志 potion candidates [ID:+score] …；TargetIndex 为 slot（非枚举序）。

DiscardPotion / UsePotion 均使用 slot index（player.GetPotionAtSlotIndex）。

集中「本回合受伤风险」判定，供 IntentCalculator、CombatScorer、CombatSearch 共用：

从 snapshot 实时比较 setup vs 立刻攻击（无固定阶段门）：

集中挡牌 vs 击杀权衡（snapshot + sim 共用）：

仅在 CombatPlanner beam 无可用路径时使用；不参与主路径起手。无 IAiMoveModifier、无完整机制分。

完整单步评分（挡牌权重、易伤 defer、机制分等）已迁移至 beam + CombatSetupEvaluator 与 CombatActionHeuristic.QuickScore。

机制驱动加分（主路径在 beam / QuickScore，非 CombatScorer）：

伤害读取：CombatCardStats.ResolveDamage — 快照 damage 缺失时回退 CardMechanicIndex.Damage（修复巨石 0 伤评分）。

战斗日志（AiCombatVerboseLog=true，默认开）：每次出牌记录 top pick + 最多 4 个备选，含分项 [attack:+31, mechanic:+48, …]。见 CombatDecisionLog。

Mod 可通过 IAiMoveModifier.ModifyScore 调整 beam / QuickScore 中的 move 分数（经 SimMoveScoring；调试日志可见 mod:+N）。

启动时镜像卡牌 CardMechanicIndex：MonsterMechanicIndex 从 ModelDb.AllEncounters 枚举怪物，经 OfficialMonsterProbe + MonsterMoveScanner 探测：

运行时快照 enrich（GameSnapshot.CaptureEnemies）：

• mechanicFlags、intentTags[]、nonDamageThreat
• intentSteps[] 扩展为 { moveId, intentDamage, intentTypes[], nonDamageThreat, isUncertain }
• CombatEnemyGraph 观测召唤并写入 summonerIndex

验证：MCP dev_dump_monster_mechanics；tools/monster-probe-dump/dump-monster-mechanics.ps1 导出 JSON。

调优边界：当前数据支持权重网格（EnemyThreatWeights）+ tools/ai-bench 胜率；不支持端到端 ML（缺目标选择标签）。场景回归见 tools/ai-bench/scenarios.json。

isMinion（IsSecondaryEnemy + power）标记爪牙。MinionEngagementPolicy 按 mechanicFlags 动态偏置（替代固定 ±30）：

ThreatModel.EffectiveIncoming = intentDamage（挡牌/净伤仅计攻击）。nonDamageThreat（塞牌/debuff）与 NextTurnIncoming（下一步攻击）分开：ScaledNonDamagePressure 在「本回合无攻击、下回合大伤害」时降权；ScaledNextTurnPressure 在安全回合给满下回合攻击权重以推动 kill-before-hit。幻象爪牙（HasIllusionRevive）在主体存活时不进入 beam 攻击枚举。OrderByPriority 与 LethalChecker 使用上述策略。

对每个存活敌人（经 OrderByPriority 排序）：若 EstimateMaxDamage(手牌, 能量) ≥ hp + block，判定可斩杀并返回 targetIndex。EstimateMaxDamage 按伤害降序贪心消耗能量（含 id 猜测伤害）。

战斗层采用 Immutable State → Legal Actions → Apply → Evaluate → Bounded Search 前向模拟。动机是修正常见 STS 战斗 bot 的静态威胁求和、AOE 误枚举、召唤目标错误等问题；模块位于 src/AI/Combat/Simulation/，CombatSearch.PickBestMove 仅委托 CombatPlanner。

架构思路：为何从权重走向 Deck EV ​

早期做法把 nonDamageThreat（塞牌 / debuff / 召唤）压成单一 magic number（EnemyThreatWeights），与 intentDamage 相加后触发挡牌。这在官方 STS2 语义下是错的：

Intent 只有 UI 元数据；牌 ID、目标堆、power 类型都在 move handler 的 imperative C# 里。因此 L3 的核心思路是：

1. 解析 move → 效果（MoveEffectIndex = 运行时 intent 扫描 + monster-move-effects.json 静态提取）
2. 在战斗堆上推进（CombatTurnResolver：EndTurn 时弃牌、敌人行动、塞牌、召唤、抽 5）
3. 同尺比较路径效用（ThreatEconomy：HP 伤害 vs 污染 EV vs power debuff，而非混在一个 incoming 里）

塞牌的真实代价是「未来抽到废牌、少打伤害」，不是「本回合挨打」；应在 DeckPollutionEvaluator 里用堆组成估算，并与 KillBeforeHitBonus（下回合攻击）放在同一把尺子上比。

决策流：beam 展开玩家出牌 → 叶节点 EndTurn 时先跑 CombatTurnResolver（模拟敌人回合与抽牌）→ 在推进后状态上由 CombatEvaluator + ThreatEconomy 评分。这样 FOGMOG 召唤回合能「看到」：若不过牌 rush 雾菇，下回合会挨 9 点且每回合多 3 张 Dazed，而非把 debuff 当成 8 点 incoming 去挡。

设计原则与常见局限 ​

常见 STS 战斗 bot 往往在以下环节失真；DevMode 模拟层针对这些点做了显式建模：

已知局限（不假装完美）：非完整协程/动画时序；无 rngShuffle seed 时回洗用牌堆哈希确定性 RNG；Confused 抽牌费用为 EV 近似（非逐张 CombatEnergyCosts 回放）；遗物仅白名单规则（relic-combat-effects.json 中 simulatable）；复杂遗物（PenNib、VelvetChoker 等 needsManual）仍忽略；偷牌不模拟死亡还牌。

CombatPlanner 参数（按可出牌数自适应，迭代加深 3→6→…→MaxDepth）：

CombatActionHeuristic 为 beam 排序：未挡满时剪枝非击杀攻击；挡牌 > 易伤 setup > 击杀攻击。叶节点用 survival-first EvaluateTerminal + ConsiderLeaf 满挡奖励区分「挡满结束」与「换血快攻」。

无 lethal 快捷路径：所有 combat poll 走 beam；日志仅 [beam d=…] / [beam end …]，不出现 [lethal] / [aoe-lethal] / [lethal-transform]。

L4 打牌节奏（pile + shuffle + beam）：

• 抽牌堆非空时：DrawPlanner.PeekTop 精确预知下 N 张；CombatSimulator 出牌更新 discard/exhaust。
• 抽牌堆空且弃牌堆非空：CombatPileSimulator.ReshuffleIfNeeded 使用官方 StableShuffle(Rng.Shuffle)，beam 分支各自携带 ShuffleRngCounter。
• 日志：NEXT= 顶牌、RESHUF=1 将回洗、POST_PLAY= / POST_BLK= 过回合后新手牌期望、OUTLOOK= 牌堆节奏价值。

L5 职业级模拟（pro pile + full next-turn beam）：

• PostTurnSimulator：EndTurn 评分前对整段下回合做 mini-beam（打满能量或无可出牌），而非仅 2 张。
• CardPileEffectResolver：从官方 DynamicVars 解析 draw/discard/scry 数量；CombatSimulator 模拟弃牌、窥视沉底。
• PileRhythmEvaluator：10 张顶牌视野 + 回洗污染惩罚，接入 EvaluateMidTurn / EvaluateTerminal。
• Beam 参数（职业级）：深度 10–16、宽度 24–48、预算 480–650 ms；迭代加深从 depth 5 起。

故意不模拟（Phase D 后仍保留）：通用 Hook 链（事件房/商店/奖励副作用）、多玩家时序、Scry UI 等价控牌、Innate/PerfectFit 回合初排序、偷牌死亡还牌、计数/状态型遗物（PenNib、Shuriken 等）。已模拟：有序 move 效果、力敏/debuff、Swipe 偷牌、Confused EV；遗物白名单（抽牌/保留/空手无歇/开战 block/开战 power）。

效果数据：

• tools/monster-move-effect-dump/extract-move-effects.py → monster-move-effects.json（怪物 move handler）
• tools/relic-combat-effect-dump/extract-relic-combat-effects.py → relic-combat-effects.json（扫描 RelicModel 覆写的战斗 Hook + 可解析的 DynamicVar / PowerCmd.Apply / CardPileCmd.Draw）；simulatable: true 的条目由 RelicCombatRules 接入 beam。

NeedsBlock 与多攻击者：CanEliminateIncomingThreats 不再要求单一威胁；可 AOE/逐个斩杀全部 intentDamage>0 敌人，或模拟击杀最高 intent 后 Incoming 归零且 net ≤ SafeLethalNetMax。

快照 enrich：GameSnapshot.CaptureEnemies 调用 MonsterIntentReader.CaptureIntentSteps，每敌最多 3 步 { moveId, intentDamage, intentTypes[], nonDamageThreat, isUncertain }。

战斗日志（AiCombatVerboseLog）：CombatDecisionLog 输出 IN= / ND= / NXT= / JUNK= / POLL= / PLAY= / NEXT= / RESHUF= / POST_PLAY= 与 tgt= bias= flags= 便于 bench 调参。

CombatScorer 保留为 最小 fallback（beam 无结果时）。Mod IAiMoveModifier 经 SimMoveScoring 作用于 beam 排序与 QuickScore，不再挂 CombatScorer。

单机开启 AI Host 且 AiHudEnabled=true 时，AiHudOverlayUI 在 NGlobalUi 左上角以纯文字堆叠显示：

显示条件：AutoPlayEnabled && AiPlayModule.IsRunning && !多人联机。

与侧边栏 AI Terminal 分工：HUD 只展示当前一步与少量参数；完整决策历史仍在 AiDecisionLog / session log。设置项在 AI Host 面板 Controls 区。

AiPlayModule 每 500ms 轮询当前 phase；GameLoop 在决策前：

• Combat 且 isPlayPhaseActive=false → 跳过（等敌方回合/动画）；Sts2StateProvider 在 CombatManager.IsInProgress 时仍返回 Combat（避免敌方回合误判为 Unknown → AdvanceOverlay 刷屏）
• EndTurn 已提交（_endTurnPending）→ 跳过，直到 phase 变化或 play phase 结束
• 相同 fingerprint（phase+action+target）2s 内 → 跳过（避免 EndTurn 刷屏、Rest 双动作）

出牌同步由 Sts2ActionExecutor 内 TryManualPlay + WaitForManualPlayAsync 阻塞完成，不在 loop 层做 fingerprint / 能量账本等待。

快照手牌 cost 使用 EnergyCost.GetWithModifiers(All)（实战费用），不再只用 Canonical。

Run 结束时 ResetDedupeState() 清空状态。

决策日志中的 Reason= 字段与上述 Scorer 字符串一一对应，调参时优先看日志。

设置 AutoPlayStrategy: Simple 启用旧版启发式：

注册入口：CompanionBridge.Register*（见 README）。

• 固定 seed 列表：tools/ai-bench/seeds.json
• 跑完一局后：powershell -File tools/ai-bench/run-bench.ps1
• 目标：各角色 A10 胜率约 40–50%（见 bench README）

常用调参旋钮：