docs/STRATEGY.md

策略说明（Strategy Reference）

本文档描述 strategies/heuristic.py 中 HeuristicStrategy 的实现策略， 以及 evolve/ 进化评估的对手分层与算法配置。内容以代码为准。

scope: "HeuristicStrategy 行为与进化评估配置"
strategy_file: strategies/heuristic.py
fitness_file: evolve/fitness.py
ga_file: evolve/ga.py
gene_count: 30
population_cap: 32        # 守库模式人口上限（v0.14 冻结）
resource_goal: 150        # 守库兑换目标
home_guard: "2 Vanguard + 1 Ranger"

1. 总体框架

HeuristicStrategy 是一个分兵种、多优先级的参数化启发式策略，全部行为由 30 个可进化基因控制。每个 tick 的决策流程：

decide(obs)
├── 记忆维护（视野更新 / 敌人遗忘 / 临时障碍清理 / 长跑淘汰）
├── 状态同步（守家小队补员 / 饥饿检测 / 冲突退避 / 目标认领重置）
├── 守库模式判定（资源 ≥150 → 冻结经济）
├── Core 决策（_decide_core）
└── 逐单位决策（_decide_unit）
    ├── Worker（采集 / 侦察 / 撤退 ...）
    ├── Vanguard（守家 / 战斗 / 驻位 ...）
    └── Ranger（射击 / 风筝 / 巡逻 ...）

2. 宏观行为模式

行为	触发条件	内容
守库模式	Core 资源 ≥ 150（RESOURCE_GOAL）	冻结 Core 全部支出（治疗 / 生产）；人口固定 32、容量 160；Worker 回撤 6-10 环、Vanguard 2-4 环、Ranger 3-6 环分层驻守；兑换后资源归零自动恢复采集
永久守家小队	常驻	稳定保留 2 Vanguard + 1 Ranger（半径 2-3 环），阵亡后由最近战斗单位接替，不参与远征
饥饿整体迁移	资源记忆长期为空、当前视野无资源/掉落 cargo、全员 cargo 为空	Core 向外迁移，所有单位优先编队跟随；发现资源或任一单位携货时取消，单位掉队/受阻或预测距离达到上限时 Core 原地等待，条件恢复后继续
冲突退避	连续 3 次移动失败	短停 2 tick，打破单位间同步互堵（长局 99% 移动失败为 DEPENDENCY 型互等）
饥饿检测	连续无采集成功	扩大侦察环带寻找新资源区（出生区资源枯竭场景）

3. Core 决策优先级

1. 普通整体迁移中 → 资源/cargo 出现则取消；人口掉队或受阻则等待，否则逐格向外迁移。紧急逃生优先于普通迁移约束
2. 资源 ≥ 150 → 冻结（攒兑换，不治疗不生产）
3. 治疗：HP < core_heal_hp × 最大 HP → HEAL
4. 修盾：盾 < shield_repair_hp × 容量 → REPAIR_SHIELD
5. 防御状态：仅当资源足以购买战斗单位时才生产（不回退到便宜 Worker 稀释守军比例）
6. 正常生产：按 守家缺员 → 战斗缺口 → worker_ratio 比例 依次决策兵种； 人口 30→32 用便宜 Worker 补容量保险（两名 Worker 比高价战斗单位更快把容量 从 150 推到 160）

4. 兵种行为

Worker

标签	行为
goto_resource / harvest / deposit	采集交付链路，资源任务 80 tick 粘性防振荡
scout	侦察：按 uid 固定 8 方向槽 + 环带轮换（10/20/30），饥饿时扩大到 40
return_core	低血撤退（worker_flee）
revisit	区域回访（revisit_ticks 周期）
block / siege_block	进攻时堵路（block_count）
harass	空闲时拦截敌方 Worker 压制经济（harass_workers）
hold_full / wait_resource	满载 / 目标不可达时等待

Vanguard

标签	行为
home_vanguard / vault_vanguard	守家 / 守库环带驻守
sweep / attack	邻格攻击 / 兵力占优追击（army_trigger）
siege_vanguard	围敌方 Core
raid	突袭确认静止的敌方 Core（连续观察 ≥ raid_min_obs 次、距离 ≤ raid_max_dist）
explore	空闲侦察（离家 ≤ 15 格，12 tick 目标粘性）
spread	叠格散开（优先于探索，防同步移动）
park	idle 驻位环（park_radius 势场，避 Core 门口 Worker 通道）
让位	堵 Core 门口时挪开

Ranger

标签	行为
shoot_stationary	supercover 射击线 + 命中格伤害认领
kite	风筝（kite_range）
patrol	环形巡逻（patrol_radius）
explore / track	侦察 / 追踪
ranger_disengage	脱离危险距离
siege_ranger	围点辅助

5. 记忆与寻路基础设施

• A* 版本化缓存：障碍变化才失效；Core 格为禁区，集结到四邻
• 敌人记忆：forget_ticks 后遗忘；追击超过 25 tick 未确认 → 放弃（防横跳）
• 目标认领：战斗目标（每格 ≤2）、资源点、驻位点、探索点、射击格均为本 tick 认领，防全员扑同一目标
• 满格管理：移动目标格被占时按最小冲突代价决策

6. 进化评估的对手分层（evolve/fitness.py）

模拟对局为 N 玩家 FFA（默认 8 玩家）。对手构成：

角色	策略	说明
被测	进化中的基因	slot 轮换消除位置偏差
老玩家 ×2-3	均衡（_balanced_genes）/ 激进（_aggressive_genes）	带兵出生、发育不同步
弃坑残骸 ×2	StaticStrategy	挂机死 Core（可掠夺）
新生弱号 ×1-2	RandomBot	远端弱对手

出生点位与人口档案按真实世界数据校准（最近邻 ~50 格密度）。

7. 进化算法（evolve/ga.py）

组件	配置
种群	默认 24；初始化 = 默认基因 ± 25% 高斯扰动（warm start 时为给定基因 ± 15%）
选择	锦标赛（tournament=3）
精英保留	前 2 名直接进入下一代
交叉	概率 0.8，均匀交叉（逐基因 50% 取自另一亲本）
变异	40% 概率，高斯扰动 σ = 基因范围 × 0.12
防过拟合	--holdout-seeds 独立验证集（不进选择压力）；--seed-rollover 滚动种子池
加速	进程池评估 + 基因指纹缓存 + 预筛（--prescreen）

8. 基因参数表（30 个）

基因	默认值	边界	含义
worker_ratio	0.55	0.10-0.90	目标 Worker 占人口比例
army_trigger	0.70	0.20-3.00	敌方/己方兵力比低于此才进攻（越高越敢打）
flee_hp	0.35	0.00-0.80	单位低血（比例）回 Core
heal_hp	0.65	0.20-1.00	单位血量低于此且在 Core 旁 → HEAL
core_heal_hp	0.40	0.00-1.00	Core HP 低于此 → HEAL
shield_repair_hp	0.35	0.00-1.00	Core 盾低于此且资源足 → REPAIR_SHIELD
spawn_worker_until	8.0	2.0-25.0	资源低于此值时优先造 Worker
vanguard_share	2/3	冻结	v0.14 固定 2V1R，保留字段兼容旧结果
rally_radius	6.0	2.0-15.0	集结半径
beacon_go_range	18.0	5.0-45.0	距 Beacon 小于此就去抢
max_population	32	冻结	32 人口容量 160，满仓守库
attack_core_first	0.55	0.00-1.00	进攻时优先 Core vs 单位
kite_range	2.0	1.0-3.0	Ranger 风筝距离
worker_flee	0.70	0.00-1.00	Worker 遇敌撤退倾向
patrol_radius	6.0	3.0-12.0	巡逻 Ranger 环形半径
defense_radius	10.0	4.0-20.0	Core 防御响应距离
forget_ticks	80.0	20.0-300.0	敌人消失多久后标记遗忘
revisit_ticks	150.0	40.0-400.0	区域回访周期
selfdestruct_pop	999.0	冻结	自毁转 Ranger 阈值（v0.14 禁用）
block_count	0.0	0.0-6.0	进攻时堵路的 Worker 数
harass_workers	0.0	0.0-1.0	空闲 Worker 拦截敌方 Worker
raid_stationary	0.5	0.0-1.0	突袭静止 Core 倾向
raid_min_obs	3.0	2.0-8.0	静止确认所需连续观察次数
raid_max_dist	40.0	20.0-60.0	突袭最大距离
park_radius	3.0	2.0-8.0	idle 驻留环带半径
park_spread_w	1.0	0.0-5.0	驻留点偏离偏好半径的惩罚权重
park_traffic_w	2.0	0.0-10.0	Core 四邻（Worker 交通）惩罚权重
migrate_starve_ticks	300	100-800	资源记忆持续为空多久后允许整体迁移
migrate_max_follow_dist	15	5-40	Core 下一格与最远人口的最大曼哈顿距离（达到即等待）
migrate_outward_bias	1.0	0.0-5.0	迁移选向时远离原点的评分权重

9. 当前线上基因（genes/evolve_overnight_best.json）

仓库附带的正式部署基因是在 v0.14 规则下训练、独立 holdout fitness 达到 48.975 的过夜冠军。加载时经 normalize_genes 规范化到当前规则：冻结基因 强制取边界值，旧规则遗留字段自动丢弃。