《七侠骰坊》实施切片 v1.2 · 玩法设计

从救急保底到高风险豪赌的施工蓝图

文档状态：T1-T3 已通过 / T4 等待共享锁 / T5-T8 未开始

日期：2026-07-27

0. 元信息

0.1 第一性原则

每个实施任务都必须同时回答：

是否直接改善“缺钱时有活路，富裕时可冒险”的目标？
是否保持救急和豪赌的边界，不把救急金变成套现工具？
是否能由纯逻辑回归、经济模拟或真实浏览器流程证明？

任一答案为“否”，不进入本期范围。

0.2 非目标

不允许押注装备、食材、木材、水、关中银票或江湖阅历。
不做赌场借贷、抵押、负债、赎回或现实货币入口。
不做联机赌局、排行榜、赛季、角色技能、成就和彩池联动。
不修改拍卖玩法，也不复用 AuctionPanel 的本地模拟钱包。
不在本切片内扩展赌场剧情、人物羁绊或随机事件数量。
不以“大文档完成”替代代码、测试、浏览器证据和 Owner 验收。

1. 已拍板产品规则

1.1 总体顺序

经营性缺钱
  -> 救急局（不扣本金，正收益保底）
  -> 资金恢复
  -> 娱乐局（真实押注，长期负期望）
  -> 每关选择收手或继续
  -> 暴富 / 铜钱归零

强制顺序：先完成并验收救急局，才允许开放娱乐局。

1.2 救急局

当现金低于 1.0 倍预计日支出时开放。
当现金低于 0.5 倍预计日支出时显示严重吃紧反馈。
每个游戏日最多领取 3 枚救急木筹。
救急木筹不从玩家铜钱扣款。
每局有保底工钱，猜中后追加奖金。
三局总收益不得为负，不得超过 1.0 倍预计日支出。
救急局不受昼夜时段限制，但终局或硬停业状态不开放。
玩家当天参加过娱乐局后，不再具备当天救急资格。

1.3 娱乐局押注档位

| 档位 ID | 玩家名称 | 押注比例 | 目标庄家优势 | 失败结果 | | :--- | :--- | ---: | ---: | :--- | | small | 小试手气 | 当前铜钱 5% | 2.5%-5% | 失去本档押注 | | standard | 赌坊正局 | 当前铜钱 15% | 7%-10% | 失去本档押注 | | high | 富贵险中求 | 当前铜钱 35% | 12%-15% | 失去本档押注 | | all_in | 一把定乾坤 | 当前铜钱 100% | 18%-22% | 当前铜钱归零 |

娱乐局仅在资金至少覆盖 2.0 倍预计日支出，且现有时间策略允许夜间风险时开放；UI 不自行复制时段判断。

已拍板首关分档返还为 1.98 / 1.88 / 1.78 / 1.65。所有娱乐派奖统一四舍五入；四档连续口径与代表性整数钱包均已通过 T3。

1.4 三关挑战

| 关卡 | 玩法 | 玩家操作 | 当前目标返还 | | :---: | :--- | :--- | :---: | | 第一关 | 猜大小 | 救急局可留 1 枚并重摇其余 2 枚一次；娱乐局首摇直接结算 | 救急工钱 / 娱乐分档返还 | | 第二关 | 猜点数区间 | 从配置提供的点数区间中选择；区间必须由 T3 概率模拟拍定 | 奖池约 3.5 倍 | | 第三关 | 指定总点数 | 选择允许的目标总点数后开摇；允许目标集合由 T3 拍定 | 奖池约 7 倍 |

每关成功后必须明确提供“见好就收”和“继续挑战”。
留骰重摇只属于救急局；娱乐局不得进入留骰或重摇阶段。
继续挑战时，当前可收奖池全部进入下一关。
任一关失败，失去当前押注或已推进的奖池。
豹子只作为特殊骰面结果和展示，不新增侧押玩法。
第一关遇到豹子时，娱乐局按本关失败结算；救急局只保留保底工钱。

1.5 “全部身家”的范围

玩家文案可以使用“倾家荡产”，但运行时只允许：

coins -> 0

以下内容必须保持不变：

装备和背包道具
木材、水、熟食
关中银票、山寨赃物
员工、菜谱、设施和剧情进度
江湖阅历与账号永久进度

1.6 冷静期

当天进入过任意娱乐局，记录 lastPaidPlayDay。
娱乐局导致铜钱归零后，记录次日才解除的冷静期。
冷静期内骰坊不再接受娱乐下注，也不补发救急木筹。
到达下一游戏日后，可重新根据现金覆盖率判定救急资格。
禁止形成“领救急金 -> 豪赌 -> 输光 -> 当天再领”的循环。

2. 当前仓库事实

2.1 经济口径

新开档真实运行值来自 src/data/playthroughs/freshRestart.ts，当前初始铜钱为 120。
src/data/economy/catalog.ts 的 500 铜钱标注为基线参考，不是当前新档真值。
src/App.tsx 当前以“员工欠薪合计 + 60”估算预计日支出。
src/utils/innStatusEngine.ts 已计算 cashRatio = cashOnHand / expectedDailyExpense。
现有现金压力规则已把 < 1.0 视为吃紧，把 < 0.5 视为严重风险。
Year 1 方向性模拟显示铜钱会快速放大，因此骰坊奖励不能长期写死为 10、20、30 铜钱，必须按日支出缩放并设上限。

2.2 可复用能力

src/utils/random/deterministicRandom.ts 已提供确定性随机数能力。
src/utils/saveVersioning.ts 已提供版本化主存档入口。
src/components/auction/ 可参考三层组织和拟物化界面，但不能参考其本地模拟钱包结算方式。
src/components/ConsoleTabsBar.tsx、src/components/DesktopConsolePanel.tsx 和 src/components/PortraitWorkspacePanel.tsx 是骰坊入口必须覆盖的桌面/竖屏表面。

2.3 当前约束

工作区存在大量无关未提交修改，任何施工不得清理、回滚或吸收这些修改。
src/App.tsx 当前在 docs/handoff/file-locks.md 中受锁。
src/types.ts 仍涉及共享运行时范围，不能在未释放时直接扩字段。
本文档只建立施工合同，不构成对上述共享文件的写入授权。

3. 三层架构落点

| 层 | 目录 | 本领域职责 | 禁止内容 | | :---: | :--- | :--- | :--- | | 数据层 | src/data/diceGame/ | 类型、押注档位、倍率、阈值、玩家文案配置 | 函数、随机、结算计算 | | 逻辑层 | src/utils/diceGame/ | 资格判断、状态机、确定性摇骰、概率、结算、存档归一化 | JSX、组件 import、原始配置常量 | | UI 层 | src/components/dice-game/ | 骰面、押注控件、留骰交互、风险阶梯、结算反馈 | 倍率计算、资格计算、随机数生成 |

Import 方向：

components/dice-game -> utils/diceGame -> data/diceGame
components/dice-game ------------------> data/diceGame（仅类型/展示常量）

所有 import 使用相对路径，不使用 @/。

3.1 计划文件

src/data/diceGame/
  types.ts
  config.ts
  index.ts

src/utils/diceGame/
  diceGameLogic.ts
  diceGameSaveLogic.ts
  diceGameLogic.regression.ts
  diceGameSaveLogic.regression.ts
  index.ts

src/components/dice-game/
  DiceGamePanel.tsx
  DiceBoard.tsx
  DiceStakeSelector.tsx
  DiceRiskLadder.tsx
  DiceSettlementDialog.tsx
  useDiceGameController.ts
  index.ts

docs/economy-sim/
  dice-game-sim.ts
  七侠骰坊概率与经济报告-v1.md

4. 状态机与交易边界

4.1 会话阶段

idle
  -> committed
  -> first_roll_revealed
  -> reroll_ready
  -> challenge_resolved
  -> cashout_ready / advance_ready
  -> settled

规则：

娱乐局从 idle -> committed 时一次性扣除押注。
救急局从 idle -> committed 时只消耗当日木筹，不扣铜钱。
committed 必须先写入会话种子和押注快照，再播放摇骰动画。
UI 动画只展示逻辑层已产生的结果，不得在动画结束时重新随机。
每个动作带会话 ID 和递增序号；旧动作、重复动作直接拒绝。
settled 会话不能再次应用铜钱变化。

4.2 最小运行状态

DiceGameRuntimeState 至少覆盖：

状态版本
当日剩余救急木筹
最近救急日、最近娱乐日、冷静期解除日
当前活动会话
最近已结算会话 ID

DiceGameSessionState 至少覆盖：

会话 ID、游戏日、模式、押注档位
入场前铜钱、押注金额、当前奖池
当前关卡、阶段、选择内容
确定性种子、摇骰序号、当前三枚骰子
保留骰子索引、是否已重摇
是否已应用结算

4.3 结算原子性

逻辑层结算返回完整计划：

previousCoins
coinDelta
nextCoins
nextDiceGameState
settlementId
playerFacingSummary

UI 只提交计划，不自行计算 nextCoins。运行时必须保证同一个 settlementId 只能应用一次。

5. 八个实施切片

| # | 任务 | 层级 | 风险 | 依赖 | 里程碑 | | :---: | :--- | :---: | :---: | :---: | :---: | | T1 | 领域类型与静态配置 | 数据 | 低 | - | A | | T2 | 确定性骰局状态机 | 逻辑 | 中 | T1 | A | | T3 | 概率枚举与经济模拟 | 验证 | 中 | T1-T2 | A | | T4 | 存档迁移与防刷新 | 逻辑/集成 | 高 | T3 | A | | T5 | 救急局真实运行闭环 | UI/集成 | 高 | T4 | A | | T6 | 四档娱乐局与三关加注 | 逻辑/UI | 高 | T5 验收 | B | | T7 | 豪赌反馈与响应式体验 | UI | 中 | T6 | B | | T8 | 全链路回归与浏览器验收 | 全层 | 中 | T1-T7 | B |

关键路径：

T1 -> T2 -> T3 -> T4 -> T5 [救急里程碑验收] -> T6 -> T7 -> T8

T1. 领域类型与静态配置

目标：建立骰坊领域，不接运行时。

新增文件：

src/data/diceGame/types.ts
src/data/diceGame/config.ts
src/data/diceGame/index.ts

必须包含：

DiceGameMode
DiceStakeTierId
DiceChallengeId
DiceGamePhase
DiceGameRuntimeState
DiceGameSessionState
救急阈值、每日木筹数、押注比例、目标倍率和庄家优势范围

验收：

数据层无任何函数。
数据层不 import utils/ 或 components/。
配置中不出现无法向玩家展示的技术文案。
npm run lint 无新增错误。

T2. 确定性骰局状态机

目标：在无 React、无 localStorage、无真实 UI 的条件下跑完整会话。

新增文件：

src/utils/diceGame/diceGameLogic.ts
src/utils/diceGame/diceGameLogic.regression.ts
src/utils/diceGame/index.ts

必须实现：

资格判断
开局与押注计划
三枚骰子的确定性生成
保留 1 枚、重摇 2 枚
大小、区间、指定总点数判定
收手、继续、失败和最终结算
冷静期与当天救急禁用
重复动作和重复结算拒绝

硬约束：

禁止 Math.random()。
状态转换保持纯函数和不可变更新。
不 import React 或 UI 文件。
不在逻辑层重新声明倍率、阈值和押注配置。

T3. 概率枚举与经济模拟

目标：用报告拍定第二关区间、第三关目标集合和最终倍率。

新增文件：

docs/economy-sim/dice-game-sim.ts
docs/economy-sim/七侠骰坊概率与经济报告-v1.md

方法：

穷举首摇三骰组合。
穷举可保留骰子及第二次摇骰组合。
分别计算无策略、合理策略和最优策略下的成功率。
分别计算四档娱乐局的长期期望。
将骰坊结果注入当前 Year 1 经济模型，检查是否制造通胀捷径。

放行门槛：

救急局三局总收益最小值约为 0.3 倍日支出。
救急局平均值位于 0.5-0.8 倍日支出。
救急局每日上限不超过 1.0 倍日支出。
四档庄家优势分别落入 2.5%-5%、7%-10%、12%-15%、18%-22%。
最优留骰策略也不能把娱乐局变为长期正收益。
T3 未通过时不得开始 T4。

T4. 存档迁移与防刷新

目标：让押注、骰面、奖池和结算跨刷新保持一致。

计划文件：

src/utils/diceGame/diceGameSaveLogic.ts
src/utils/diceGame/diceGameSaveLogic.regression.ts
src/utils/saveVersioning.ts
src/components/app/useSaveRestoreController.ts
src/version.ts
src/App.tsx（只允许骰局状态与保存接线）

存档合同：

主存档新增可选 diceGame 字段。
旧存档缺少字段时归一化为默认状态。
存档 schema 从 2.0 升级时必须提供明确迁移步骤，不能只改版本数字。
押注提交、骰面产生、收手/继续和结算后立即强制保存。
刷新恢复后继续当前阶段，不重新生成种子。
已结算会话刷新后不能再次领取奖励。

放行条件：共享文件锁明确释放，并获得 App.tsx、src/types.ts 或等价运行状态表面的写入边界。

T5. 救急局真实运行闭环

目标：只交付救急玩法，不展示娱乐入口。

计划文件：

src/components/dice-game/DiceGamePanel.tsx
src/components/dice-game/DiceBoard.tsx
src/components/dice-game/useDiceGameController.ts
src/components/dice-game/index.ts
src/utils/appUi.ts
src/utils/tabUnlockConfig.ts
src/components/ConsoleTabsBar.tsx
src/components/DesktopConsolePanel.tsx
src/components/PortraitWorkspacePanel.tsx
src/App.tsx（最小导航、真实铜钱和预计日支出接线）

用户闭环：

玩家现金进入吃紧区。
骰坊入口提示可领取 3 枚救急木筹。
玩家选择大小并摇骰。
玩家保留 1 枚骰子，选择收骰或重摇其余 2 枚。
系统结算保底工钱与猜中奖金。
铜钱真实进入当前存档。
当日木筹用完或现金脱离吃紧区后关闭救急入口。

里程碑 A 验收：

从 0 铜钱可以完成救急会话并获得真实铜钱。
救急局不存在任何负铜钱结果。
刷新不会改变已承诺骰面。
桌面和 390x844 竖屏都能完成全部操作。
未接入娱乐局时，T1-T5 已经是可独立运行的完整产品环。

T6. 四档娱乐局与三关加注

前置门：T5 必须先通过逻辑、存档和浏览器验收。

目标：开放真实押注、随时收手和梭哈归零。

新增/修改文件：

src/components/dice-game/DiceStakeSelector.tsx
src/components/dice-game/DiceRiskLadder.tsx
src/components/dice-game/DiceSettlementDialog.tsx
T2/T3 已建立的逻辑与配置文件（只按模拟报告调整）
src/components/dice-game/DiceGamePanel.tsx

验收：

四档押注均从真实当前铜钱计算。
押注在开局时扣除，不在结算时补扣。
第一、第二关成功后均可收手。
第三关成功后按配置支付最终奖池。
梭哈失败后 coins === 0。
梭哈不会修改任何其他资产。
当天参加娱乐局后救急入口锁定。

T7. 豪赌反馈与响应式体验

目标：玩家在每次继续前清楚知道收益和最坏结果。

必须展示的玩家信息：

当前身家
本局押注
当前收手可得
继续成功可得
继续失败后剩余铜钱

交互要求：

押注档位使用分段控件。
留骰使用骰面点击与明确选中态。
收手和继续是同层级的明确命令，不用含混图标。
35% 和 100% 档位需要确认步骤。
100% 档明确显示“失败后铜钱归零”。
骰子区域使用稳定尺寸，动画和文字变化不能推动布局跳动。
支持 prefers-reduced-motion，关闭运动后仍能看清每次骰面变化。
玩家界面不得显示 seed、sessionId、phase、actionId 等开发字段。

T8. 全链路回归与浏览器验收

新增脚本：

"test:dice": "tsx --test src/utils/diceGame/diceGameLogic.regression.ts src/utils/diceGame/diceGameSaveLogic.regression.ts"

工程门：

npm run test:dice
npm run test:year1
npm run test:w29
npm run lint
npm run build
git diff --check

浏览器场景：

旧存档载入后骰坊状态正常。
0 铜钱进入救急局并恢复到可经营状态。
押注后刷新，押注不返还、骰面不变化。
首关收手、次关收手、终关成功分别正确结算。
35% 和 100% 档位确认文案与结果一致。
梭哈失败后铜钱归零，其他资源逐项不变。
同日不能领取救急木筹，次日可重新判定。
连点按钮、双击结算和浏览器恢复都不会重复发钱。
390x844、桌面和宽屏均无文字溢出、按钮遮挡或骰面错位。
开档 -> 进游戏 -> 经营一个周期的原有流程未破坏。

6. 回归矩阵

7. 回滚策略

| 切片 | 回滚方式 | 注意事项 | | :---: | :--- | :--- | | T1-T3 | 删除纯新增领域、测试和模拟文件 | 未接运行时，风险低 | | T4 | 停止新会话并保留存档字段读取兼容 | 已发布后不得直接降低 schema 版本 | | T5 | 移除骰坊入口和运行接线，保留存档归一化 | 旧存档中的骰坊字段不得导致载入失败 | | T6-T7 | 关闭娱乐入口，保留救急局 | 救急闭环必须仍可独立运行 | | T8 | 无运行时行为 | 只包含测试、验收和证据 |

推荐保留数据层配置中的功能开关，使紧急回滚可以隐藏娱乐局而不删除存档兼容代码。

8. 文件锁与施工状态

截至 2026-07-27：

T1 数据层、T2 逻辑层与回归已经实现并通过定向验证。
T3 第二轮已通过：救急门、娱乐首摇直结、分档赔率、四舍五入整数派奖、长期负期望和 Year 1 无通胀捷径全部达标。
T4-T8 尚未开始；不得把纯领域内核和模拟报告描述为已接入真实运行时、存档或 UI。
T4-T8 涉及 src/App.tsx、存档和共享导航，必须先核对并释放当前文件锁。
不允许借骰坊需求顺手重构 App.tsx、拍卖、经济系统或现有导航。

状态必须分别记录：

documented
implemented
self_tested
browser_verified
owner_accepted
committed
pushed
published

前一状态不自动证明后一状态。

9. 实施启动条件

开始 T1 前必须满足：

[ ] Owner 明确下达开始实施指令。
[ ] 重读 AGENTS.md、docs/handoff/file-locks.md 和当前 dirty baseline。
[ ] 确认没有其他 writer 占用骰坊新目录。
[ ] 声明 T1-T3 与 T4-T8 的文件边界。

开始 T4 前必须额外满足：

[ ] T3 概率与经济报告通过全部放行门槛。
[ ] src/App.tsx 和存档相关共享文件锁已释放。
[ ] 存档 schema 迁移方案通过审查。

开始 T6 前必须额外满足：

[ ] T5 救急局真实铜钱闭环已通过浏览器验收。
[ ] 刷新改命、重复结算和救急套现三项 P0 风险全部关闭。

《七侠骰坊》实施切片 v1.0 完。