AGENTS.md — 给 Coding Agent 的仓库入口

这是 数值卡牌 · 自动 PK（numerical-battle-lab）的工作指引。

项目是什么

一个多数值自动卡牌 PK 游戏：选两张卡 → 调等级（1–100）→ 开始战斗 → 看谁赢。不做生成器、不做技能系统、不做多队伍、不做沙盒编辑。旧版本全部在 Git 历史里，当前产品树只维护这一个版本。

三套核心实力系统

Level — 第一维度，超指数成长：g(L) = exp(0.02143L + 0.0002253L²)
Rarity — 第二维度，12 档（C…XS Collector），显式倍率表（src/power.js 的 RARITY_MULT）： C=1.00, C+=1.15, B=1.35, B+=1.60, A=1.90, A+=2.30, S=2.90, SS=3.75, SSS=4.90, SSS Collector=6.60, XS=9.10, XS Collector=13.20。Rarity 越高相邻档差距越明显，Collector 档跳升明显。
Battle Power — 只读最终属性的透明非线性评价，不参与战斗，只是给玩家的综合实力数字

HP/ATK/DEF/SPD = 基准 × 卡牌形状 × g(L)×rarityMul(稀有度)；其余八项属性保持卡牌固定值。

产品关系：g(55) × 13.20 ≈ g(100)（p ≈ 84.8 vs 81.1）→ Lv55 XS Collector vs Lv100 C 有悬念（XS-C 总胜率约 45%–65%）。

关键设计约定（改动前必读）

卡牌只读：src/cards.js 固定 96 张卡（12 档 × 8 张），玩家不生成/导入/编辑卡。原始 24 张通过 LEGACY_CARDS 保留为冻结 BP v4 参考集；新增 72 张不引入技能系统。
形状归一化：每张卡的“战斗强度” hp·atk²/(atk+def) 与百分比属性都收窄在窄带内，稀有度差距只由 Rarity 倍率表表达。因此：
- 同级 C vs XS Collector = 13.2 倍 → 压倒性；
- Lv55 XS Collector vs Lv100 C（p ≈ 84.8 vs 81.1）→ 悬念；
- 同档对抗互有胜负；S 以上相邻档高档明显占优，Collector 跳升明显。调平衡时改某张卡的 base/百分比即可，不要加新系统；若战斗结果与产品目标有偏差，可微调 RARITY_MULT 表（保持显式表，不做公式拟合）。
确定性：战斗内所有随机必须走 src/battle.js 的 Mulberry32 PRNG。禁止 Math.random()。同 Match Seed → 完全相同的对局。
先模拟后播放：simulate() 生成完整事件列表，UI 只按慢/快/瞬的延迟回放。播放速度绝不能改变回合/命中/暴击/伤害/胜者。
1v1 only：没有队伍、没有多目标。

数值公式（src/power.js 与 src/battle.js）

命中率 = clamp(0.90 + (ACC−EVA)×0.004, 0.45, 0.99)
基础伤害 = ATK² / (ATK + DEF×(1−PEN))，再 × 波动(±volatility) × 暴击(×critDmg)
Battle Power 参考属性与系数见 src/power.js::battlePower，修改公式要同时跑 npm test 看排序测试。

常用命令

npm test          # node:test 全量测试（零依赖）
npm run verify    # 静态检查（文件集合=期望清单）+ 全量测试 + 产品实战验收 + BattlePower 审计
npm run serve     # 本地静态服务器 http://127.0.0.1:8774

修改卡牌/数值后的检查清单

npm test（BP 排序、确定性、验收匹配全部要绿）
npm run verify（含 scripts/battlepower-audit.js：Lv25/55/100 循环赛胜率与 BP 排名 Spearman 相关 ≥ 0.90 + 跨 Level/Rarity 抽查）
如果改了 index.html 的 script 标签或新增/删除文件，同步更新 scripts/static-check.js 的期望清单

BP 评价与验证

BP 对七组固定参考属性估计命中、穿透后伤害、暴击期望、生存与有限续航，再取几何平均；只用最终属性，不读等级、稀有度、身份或当前 HP。速度仅估计先手价值，波动取中性，单一 BP 不表达尾部风险，也不是胜率百分比。公式及参考常量见 src/power.js。

scripts/bp-evaluation.js 固定卡对划分、等级组合、seeds 与门槛，输出 SHA-256。BP v4 深度校准/保留池继续只使用原始 24 张 LEGACY_CARDS，避免扩卡改写历史冻结清单；96 张全卡池由产品验收中的轻量循环赛相关性检查补充覆盖。校准和保留池卡对、seed 隔离；历史全卡池诊断已被查看，因此保留池是系数拟合独立数据，不声称卡牌身份从未被观察。全共同对手仅作最终回归：Lv25/55/100 分别 rho≥0.90，每 seed 聚合 22 对手和两个座位，用 512 个配对差计算 t 区间；按实测及用户批准，显著差门槛为 1 个百分点。

近/中/远 BP 分别为 ≤1.06、(1.06,1.25)、≥1.25。近 BP 全部检查双方 wins/total≥5%（total 包括平局），同时约束数量和类别/等级覆盖。远 BP 要求总体得分≥70%，且至少85%组合的高BP方实际胜率≥70%。常数、Level×Rarity、反向负面对照必须按预期原因失败。保留集一旦用于调参，永久转为回归集，不可继续称为保留集。完整审计失败意味着 BP 尚未完成，不得降低门槛。

评价清单 v4：v2、v3 保留池永久转为历史回归并全量保留。新保留池使用 [14,31,57,81,94] 级锚点与新的 seeds，排除参与拟合的全部修复卡对；保持与校准/修复卡对隔离，并与历史池的单位等级组合及 seeds 不重叠。历史上出现过的卡牌身份不被宣称为从未观察。先手收益与参考属性已重新校准；再生采用 50% 的可用性估计系数，模拟器规则不变。

FilesExpand file tree

AGENTS.md

Latest commit

History