fixed # 新增羁绊系统

fixed # 新增遗物系统
fixed # 梦三模式下移除护甲上限限制

mengsan/docs/bonds.md

@@ -0,0 +1,115 @@
+# 梦三羁绊与助战
+
+## 当前规则
+
+- 行军菜单 → 羁绊：可结识多名 NPC，但只能指定一名助战；允许不指定。
+- 羁绊仅随本次征程保存，新征程重置。刘备先天技能“桃园羁绊”
+  初始结识 `guanyu`、`zhangfei`，均为 8 级、升级进度 0%，默认未指定助战。
+- 普通事件结识默认 1 级、进度 0%。每级助战概率为 `(level - 1) / 9`，
+  1 级为 0%，10 级为 100%。
+- 战前在地图切换助战；开战只判定一次。成功后占玩家下家，AI 自动行动。
+  原有剧情与道具支援保留，原有 8 席校验和座次代码保留。
+- 完成战斗结算：指定 NPC 到场 +50%，未到场 +25%。
+  濒死、战斗配置未补齐也属于未到场。不要求 NPC 存活，不限定胜利。
+  退出或重载未完成战斗不增长；重复结算不重复增长。
+- 100% 进度升一级并保留溢出，最高 10 级，满级不再积累进度。
+  升级数值与新增技能从下一场生效。
+- 存活 NPC 下一场恢复满血、重建自己的抽牌堆/弃牌堆/消耗牌堆。
+  抽牌堆耗尽后洗回自身弃牌堆，无可用牌时不使玩家征程失败。
+- NPC 在自身出牌阶段前消耗 1 费用执行当前意图，然后照常使用手牌。
+  意图在开场及玩家新一轮行动时预告，按 NPC 自身已执行次数循环。
+  NPC 获得的护甲在其下次主循环回合开始时清除，与劫掠者一致。
+- 原生死亡结算后离场，存档标记 `down: true`，界面显示“濒死”。
+  未救助前不能参战，但仍可指定助战并获得未到场的 25% 进度。
+- 怪物意图攻击、负面效果作用于全部存活敌对单位，含剧情与道具友军。
+  每个目标承受完整段数，各自结算易伤、护甲与技能；怪物自身增益只执行一次。
+  意图伤害数字在目标状态不同时显示伤害范围，护甲仍由伤害流程抵扣。
+
+## 手动补充 NPC
+
+配置位置：`bonds/definitions.js` 的 `bondDefinitions`。
+
+关羽、张飞的 `portrait` 以及 10 个 `growth` 行目前均预留。
+成长数值与技能未填写完整前可以结识、选择与成长，但不能参战；
+不继承原版武将技能。`deck` 和 `intents` 无需预先填写，已有默认兜底。
+`portrait` 为空时不显示原版立绘。
+
+每个成长行的字段：
+
+| 字段 | 含义 |
+| --- | --- |
+| `maxHp` | 该等级的最大生命，参战时满血，正整数 |
+| `hand` | 初始手牌数量，非负整数 |
+| `draw` | 自身摸牌阶段摸牌数，非负整数 |
+| `handLimit` | 手牌上限，非负整数 |
+| `energy` | 每回合费用，正整数 |
+| `skills` | 本等级新解锁技能 ID 数组；无新增时填写 `[]`，低等级已解锁技能累计保留 |
+
+`growth[0]` 对应 1 级，`growth[9]` 对应 10 级。数值逐行填写，不自动插值。
+当前关卡校验要求生命及初始手牌不超过 99。
+`deck` 为该 NPC 独立的基础牌组，填写牌名数组，或 `{name,suit,number}` 数组。
+牌名必须已在游戏注册。每场创建新的卡牌实例，不与其他 NPC 或玩家共享实例。
+
+## 默认牌库和意图
+
+`deck` 未填写、为 `null` 或 `[]` 时，使用 `DEFAULT_BOND_DECK`：
+3 张【杀】、2 张【闪】、1 张【桃】、1 张【无中生有】，每场独立生成并洗牌。
+
+NPC 的 `intents` 未填写、为 `null` 或 `[]` 时，使用
+`bonds/intents.js` 的 `DEFAULT_BOND_INTENTS`，按下列顺序循环：
+
+| 意图 | 效果 |
+| --- | --- |
+| 援击 | 对每名存活敌对单位造成 6 点攻击伤害 |
+| 连击 | 对每名存活敌对单位造成 2 段攻击伤害，每段 3 点 |
+| 整备 | 自身获得 5 点护甲 |
+
+默认意图数值不随等级自动插值。NPC 可以在 `bondDefinitions` 中
+填写独立的 `intents` 数组来覆盖默认组，例如：
+
+```js
+intents: [
+    { id: "strike", name: "重击", damage: 8 },
+    { id: "break", name: "破阵", damage: 3, hits: 2,
+        debuff: "易伤", stacks: 1 },
+    { id: "guard", name: "坚守", block: 6 },
+],
+```
+
+每项需要 `id`、`name`，可配置 `damage`、`hits`、`debuff`、`stacks`、
+`block`、`strength`。伤害和增益为非负整数，攻击段数为正整数；
+负面效果目前支持“脆弱”“易伤”。`intentType: "death_blow"`
+可选，但只允许单段攻击，并沿用出牌阶段结束后自身死亡的规则。
+显式填写的无效意图会报错，避免将错误配置静默替换成默认值。
+
+所有攻击目标各自结算护甲、易伤及技能；自身护甲、力量增益只执行一次。
+费用不足时该项不产生效果，轮次仍向后推进；每场重新从第一项开始。
+
+## 事件结识接口
+
+剧情选项的 `outcome` 可填写：
+
+```js
+outcome: {
+    bonds: ["guanyu", { id: "zhangfei", level: 3 }],
+}
+```
+
+已结识 NPC 再次结识不会重置等级、进度或濒死状态。
+也可从 `bonds/state.js` 导入 `meetBond(run, id, level)`，
+在现有事件结算中调用并使用现有征程存档流程保存。
+
+## 救助接口预留
+
+`bonds/state.js` 导出 `rescueBond(run, id)`：
+仅解除该 NPC 的濒死标记，返回是否发生状态变化。
+当前没有绑定道具或取得途径，菜单仅显示禁用的“救助道具待补充”按钮。
+以后接入地图道具时，应在同一次存档中完成道具扣除与状态解除；
+不能把此接口作为免费救助按钮。救助后下一场按当前等级满血参战。
+
+## 验证
+
+`tools/test_bonds.mjs` 覆盖初始化、事件重复结识、单选、概率边界、
+成长溢出/上限、濒死/救助、独立牌组、结算重复提交和多目标意图。
+另覆盖默认牌库与意图兜底、独立循环、费用不足、自定义意图和击晕期间禁止执行。
+这些检查不等同于游戏原生战斗运行验证；空缺战斗配置待补充后再实机验收。