# Rollin' Ace 操作指南

> **用途**：本文件是**对外文档**，面向玩家与 AI 接入方 —— 操作指南的**完整版**（各模式、基本操作、道具系统与各场景）。
> 更紧凑的整理版见 wiki 页面：`basics.html`（基础操作）、`strategy.html`（策略玩法）、`nav.html`（页面导航）。
> 英文版：`skills/rollin-ace-game-guide.en.md`（与本文同步维护）。

> 本文档为智能体提供完整的 Rollin' Ace 棒球方块操作指南，涵盖所有模式、基本操作、道具系统和各场景玩法。

---

## 一、概述

Rollin' Ace 是一款**棒球方块 Web 应用**，核心玩法是复刻真实棒球名局的**一个半局**（通常为"九局下半"），玩家扮演**进攻方**，通过好坏球打席的「打/看」选择和使用道具来逆转比分。

### 核心机制

- **服务端权威**：所有掷方块概率、局面推进、过关判定、道具扣减与发奖均在服务端执行，前端只负责渲染和发送请求
- **好坏球打席博弈**：每个打席先选「打/看」，掷投手档位方块 + 命中后掷击球方块（含二选一决策），加上 6 种道具的战术博弈

---

## 二、基本操作

### 2.1 好坏球打席（看 / 打 · 唯一模式）

**唯一模式**（2026-09-21 起：普通掷方块已取消；好坏球开关与全局偏好**整体删除**，任何模式都**无法关闭**）。每个新打席先进入好坏球阶段，玩家不再点击独立的「Roll」按钮，而是每球选择「打（Swing）」或「看（Lay off）」：

1. 玩家选择「打（Swing）」或「看（Lay off）」
2. 服务端掷**该档位的投球方块**（6 面，五档投手风格见 2.3.1），方块面分布由当前「投手风格档位」决定；六面共 **5 种球种**，每种球种的「打/看」结算固定（见 2.3）：
   - 选「打」：按该球种的**挥空率**判定（未挥空即击中，改掷击球方块）
   - 选「看」：按球系结算（好球系看错记好球 +1 / 坏球系看对记坏球 +1）
3. **打席结算**（见 2.3）：好球 ≥3 → 三振出局；坏球 ≥4 → 四坏保送；击中 → 改掷「该球种」的击球方块；未满 → 继续选「打/看」

### 2.2 二选一决策

当击球方块掷出 `二选一` 面时，玩家需从两个选项中选择：

**选项 A：「拿下 1B」（保守）**
- 直接获得一垒安打，安全上垒
- 安打率更高（均衡档约 **48.7%**，对手偏好球档可达 58.8%）

**选项 B：「放手一搏」（激进）**
- 掷第二颗棒球方块，进入高风险高回报分支：

| 方块面 | 权重 | 结果 |
|---|---|---|
| DP（双杀） | 1 | 打者 + 最靠本垒跑者出局（2 出局前）；2 出局后仅打者出局 |
| BB（保送） | 1 | 打者上一垒，跑者推进 1 垒 |
| 2B（二垒安打） | 2 | 打者上二垒，跑者推进 2 垒 |
| 3B（三垒安打） | 1 | 打者上三垒，跑者推进 3 垒 |
| HR（本垒打） | 1 | 所有跑者 + 打者回本得分，垒清空 |

**归一化概率**：DP 16.67%、BB 16.67%、2B 33.33%、3B 16.67%、HR 16.67%。

**怎么选（一句话）**：**0 出局一律「拿下 1B」；1 出局看「三垒有没有人」；2 出局一律「放手一搏」，
唯一例外是「仅三垒有人」。** 理由与逐局面差值见《策略指南》§2 —— 注意 2 出局并不该保守：
双杀在 2 出局后只算打者出局（上表 DP 行），额外惩罚已经消失 ❌ 旧说法「2 出局选 1B 避免双杀」是错的。

### 2.3 球种与打/看结算

打席流程见 2.1。投球方块的六面共 **5 种球种**，每种球种的「打/看」结算固定：

| 球种 | 选「打」结果 | 选「看」结果 |
|---|---|---|
| 红中球（`s0`） | 挥空 10% / 击中 90% - 进击球方块 | 看错 - 好球 +1 |
| 好球（`s1`） | 挥空 20% / 击中 80% - 进击球方块 | 看错 - 好球 +1 |
| 刁钻好球（`s2`） | 挥空 50% / 击中 50% - 进击球方块 | 看错 - 好球 +1 |
| 坏球（`b1`） | 挥空 40% / 击中 60% - 进击球方块 | 看对 - 坏球 +1 |
| 偏出坏球（`b2`） | 挥空 80% / 击中 20% - 进击球方块 | 看对 - 坏球 +1 |

> **挥空率**：选「打」不再是「见红中必中、见偏出必空」，五种球种各带挥空概率
> （红中 10% / 好球 20% / 刁钻 50% / **坏球 40%** / 偏出 80%，坏球于 2026-09-27 由 20% 调整），未挥空即击中；
> 选「看」的结算与挥空率无关，恒为「好球系看错 / 坏球系看对」。
> 挥空率体现的是**这颗球好不好打到（接触难度）**，与好坏球计球无关：
> 红中最好打 → 好球 / 坏球 → 刁钻 → 偏出最难；所以「挥打坏球比挥打刁钻好球更容易碰到」是设定如此
> （`b1` 坏球是中立项，真正的坏球陷阱是 `b2` 偏出坏球）。

**击球方块（每种球种一颗，命中后掷，6 面）**：越好打的球，击中后也越强 ——

| 球种 | 出局 | 界外 | 一垒打 | 二选一 |
|---|---|---|---|---|
| 红中球 `s0` | 1 | 1 | 2 | 2 |
| 好球 `s1` | 2 | 1 | 2 | 1 |
| 刁钻好球 `s2` | 2 | 2 | 2 | 0 |
| 坏球 `b1` | 2 | 2 | 1 | 1 |
| 偏出坏球 `b2` | 3 | 2 | 1 | 0 |

> 二垒打 / 三垒打 / 全垒打**不再由击球方块直接产出**，仍只由【棒】把一垒打升级产生。
> 击球方块掷出「界外」= 打席记一好球（已 2 好球不再增加）后回到选「打/看」。

#### 2.3.1 投手风格档位（决定方块面分布）

「投手风格」五档各自是**一颗独立的 6 面方块**（不是同一颗方块调权重）—— 档位由偏坏球到偏好球排列（坏球面 5→1）：

| 档位 | 界面名 | 六面分布（张数：`s0` / `s1` / `s2` / `b1` / `b2`） | 坏:好 | 定位 |
|---|---|---|---|---|
| `bbb` | 极偏坏 | 1 / 0 / 0 / 1 / 4 | 5:1 | 极端保送向（主动放弃刁钻好球 · 面板上标红「危险」） |
| `bb` | 偏坏球 | 1 / 0 / 1 / 1 / 3 | 4:2 | 保送向 · 惩罚乱打、利好选球 |
| `bs` | 均衡（默认） | 1 / 1 / 1 / 1 / 2 | 3:3 | 稳妥默认 |
| `ss` | 偏好球 | 1 / 2 / 1 / 1 / 1 | 2:4 | 三振向 · 惩罚等球、利好出棒 |
| `sss` | 极偏好 | 1 / 3 / 1 / 1 / 0 | 1:5 | 极端三振向 |

- 每档**固定 1 面红中球 `s0`**（能力下限）+ **1 面坏球 `b1`**（中立项）；刁钻好球 `s2` 除 `bbb` 外固定 1 面。
- 坏球档惩罚乱打（多 `b2` ⇒ 80% 挥空）；好球档惩罚等球（多 `s1` ⇒ 等球即看错）。
- **挥空率使「打」与「看」不再零和**：「打」整体变强 —— 均衡档全打进击球方块 **89.8%**，
  `bbb` 极偏坏档也从旧模型的 42.1% 升到 **76.5%**（全打安打率 36.9%，不再是「纯死」）。

#### 2.3.2 档位从哪来（对战 / 单人差异）

- **对战房（Duel / PvP / AI 对战）**：防守方在**自己防御的每个半局开始前**选一次档位（**本半局所有打者沿用，换边后重新选**）；开赛前由先发防守方（主队房主）先选「先发投手」档位。**好坏球恒开启 ⇒ 档位恒生效**（已无「仅当对方开启好坏球时生效」这一条件）。
- **单机（九下挑战）**：不弹面板，每局按 **偏好球 30% · 均衡 50% · 偏坏球 20%** 加权随机（只用中间三档，不出现极偏好 / 极偏坏）。

**面板交互**：五档各是一张卡片，**点一下即选定**（150ms 定格反馈；刚弹出的 250ms 内忽略点击，防误触）；点卡片外的空白处 = 直接取默认「均衡」。**倒计时结束未操作也自动按「均衡」开始**。

**限时**：**5 秒**；只有「本场第一次选档且对手是 AI」时为 **10 秒**（其余情况——换半局、对真人、大会场次——一律 5 秒）。

**等待提示与结果回显**：
- 进攻方不展示该面板，等待期间显示「对方正在选择投球策略…」（对战 AI 时显示「AI 正在思考投球策略…」，AI 选档前会停顿约 2 秒）。
- 每个好坏球打席的结果（击中 / 挥空 / 看对 / 看错等）下方会单独显示一行：**「对方选择「打/看」· 方块面」**（红中球 / 好球 / 刁钻好球 / 坏球 / 偏出坏球），防守方与观众都能看清对手每个打席的选择与方块面。

### 2.4 过关与失败

- **过关（passed）**：比分反超（我方 score > 对方 score），半局立即结束
- **失败（failed）**：满 3 出局未反超

---

## 三、道具系统

### 3.1 道具总览

| 道具 | 名称 | 类型 | 描述 | 方块面分布（1~6） |
|---|---|---|---|---|
| bat | 棒 | 被动 | 安打自动升级一级（1B->2B->3B->HR） | 不掷方块 |
| steal | 盗 | 主动 | 一垒跑者盗二垒 | 成功x4 / 失败x2 |
| sac | 牺 | 主动 | 牺牲打：垒上跑者各进一垒，打者出局 | 成功x4 / 失败x2 |
| mist | 雾 | 主动 | 防守方失误，随机发生 | 捕逸/暴传/暴投/无事x2/Nice Play |
| lun | 抡 | 主动 | 盲炮选手，高风险大回报 | OUTx4 / 三垒打x1 / 本垒打x1 |
| ling | 令 | 主动 | 传令：成功则重置**本半局**技能使用次数 | 成功x3 / 失败x3 |

### 3.2 使用规则

- **每半局最多使用 3 个技能**（**换边自动重置**），同种技能本半局不能重复使用
- **令的刷新机制**：成功后重置**本半局**使用次数为 3 并清空已用集合，所有道具恢复可用
- **额度用满后任何道具都发不出去**（含【令】）—— 想用令，必须赶在「还剩最后一次额度」时
- **背包上限**：每种道具最多 20 个，总上限 120 个

### 3.3 使用条件

| 道具 | 使用条件 |
|---|---|
| 棒 | 无（选中后随击球方块安打自动生效） |
| 盗 | 一垒有人、二垒空 |
| 牺 | 两出局前且垒上有人 |
| 雾 | 无（但**只在 0 出局时值得用**，见 3.5） |
| 抡 | 无 |
| 令 | 无前置条件（成功即重置半局额度）；⚠️ **额度满时发不出去** |

### 3.4 好坏球模式下的技能限制

- **BS 打席进行中**：只有「盗」可用，其余主动技能禁用
- **棒**为被动始终生效（好坏球击中后击球方块掷出的 1B 同样升级为 2B）
- 雾/牺/抡只能在**打席未开始**时使用，用后直接结算打席并绕过好坏球流程

### 3.5 道具效果明细

**棒（bat）**：
- 击球方块掷出安打时自动升级：1B->2B、2B->3B、3B->HR
- OUT/DP/BB 等不生效
- 无论打席以何种方式结束都消耗

**盗（steal）**：
- 成功（4/6 = 66.67%）：一垒跑者盗上二垒
- 失败（2/6 = 33.33%）：一垒跑者出局

**牺（sac）**：
- 成功（4/6 = 66.67%）：垒上所有跑者各进一垒（含回本得分），打者出局
- 失败（2/6 = 33.33%）：打者出局，垒包不变

**雾（mist）**：

| 面 | 效果 |
|---|---|
| 1 捕逸 | 垒上跑者推进 1 垒；无跑者则无影响（逃过一劫） |
| 2 暴传 | 垒上跑者推进 **2 垒**；无跑者则无影响 |
| 3 暴投 | 垒上跑者推进 1 垒；无跑者则无影响 |
| 4-5 无事发生 | 局面不变，但**打席被吃掉**（白费一个打者） |
| 6 Nice Play | 垒上有人且 2 出局前 ⇒ **双杀**（打者 + **最接近回本**的跑者出局）；已 2 出局或垒上无人 ⇒ 仅打者出局 |

- ⚠️ **值得只有在「0 出局且垒上有人」时用**：1 出局时那 1/6 的双杀会凑满 3 出局、当场终结半局。
- ⚠️ 4/5 两面「无事发生」会**结束打席**（不是重掷）⇒ 有 1/3 概率白费一个打者，故它不能当「50% 推进技」看待。

**抡（lun）**：

| 面 | 效果 |
|---|---|
| 1-4 OUT | 打者出局（66.67%） |
| 5 三垒打 | 跑者各进三垒，打者上三垒（16.67%） |
| 6 本垒打 | 打者及所有跑者回本得分（16.67%） |

**令（ling）**：
- 成功（3/6 = 50%）：重置**本半局**技能使用次数 = 3，并清空「本半局已用」集合
- 失败（3/6 = 50%）：无效，但仍占 1 次额度
- ⚠️ **只有一个正确窗口**：本半局额度**只剩最后一次**时传令 —— 成功即白拿 3 次、失败则额度耗尽。
  额度满后传令**根本发不出去**；额度充裕时传令期望不升反降（还剩 3 次时传令期望 2.5 < 3）。

> 道具之间的相对强度、「额度该不该省着用」等实测结论，见《策略指南》§十（自对弈实测数据）。

### 3.6 道具获取途径

| 途径 | 奖励 |
|---|---|
| 新用户初始赠送 | 各 3 个 |
| 普通通关（逆转成功） | 6 选 4，各 1 个 |
| 再见本垒打（HR 且过关） | 棒 3 / 抡 3 / 盗 2 / 牺 2 / 雾 2 / 令 2 |
| 单独本垒打（未过关） | 棒 2 / 抡 2 |
| 3 OUT 局末（失败） | 加权随机送 1 个：盗/牺各 20%、棒/抡/雾/令各 15% |

---

## 四、模式

### 4.1 九下挑战（Challenge）

**入口**：首页（打开首页即是九下挑战，无独立按钮）

「九下挑战」= 多场连续闯关的挑战赛，进度与奖励独立结算。名称沿革：`锦标赛 →（09-20）挑战赛 →（09-21）九下挑战`；英文 `Series → Challenge`。

**玩法**：
1. 首页默认即为九下挑战，进入后系统下发当前挑战（由管理端发布）
2. 为一个半局（通常为九局下半），通过好坏球打席的「打/看」选择和使用道具，使比分逆转反超
3. 初始局面：我方落后，N 出局，特定垒包配置
4. 反超即过关（passed），满 3 出局未反超则失败（failed）

**特点**：
- 多场连续闯关，全部场次逆转通过则**通关**
- 进度独立结算；刷新/重进后从已通过的最高场次之后继续（续玩）
- 每日/每期由管理端更新挑战局面；每场可独立配置队名、比分、出局数、垒包、局数等
- 过关/通关后可获得道具奖励；每场也可由管理端单独配置奖励卡
- 好坏球为**唯一模式**（无开关，恒开启）

**API 流程**：
1. `GET /api/series` -> 读取当前九下挑战 + 进度
2. `POST /api/roll` -> 掷方块 + 局面推进
3. `POST /api/series action=progress` -> 上报进度/完成

---

## 五、其他场景

### 5.1 速报房（比赛速报 / Report）

**入口**：首页「NEWS」流水里的速报事件；也可直接进「速报大厅」挑选（观众端页面）

**概述**：
- 比赛实时转播场景，由后台程序创建与控制
- **只可观看**，无主播掷方块玩法

**核心特性**：
- R/H/E 记分牌（安打/失误自动累积）
- 垒包状态实时渲染
- 事件日志（投打对决、安打、出局等）
- 支持直播/重播两种模式
- 状态机：`created` -> `live` -> `ended` -> `closed`；`live` <-> `paused`；任意 -> `cancelled`

**观看方式**：
1. 从首页「NEWS」进入（report-viewer，不再有独立「报」入口）
2. 观众端通过 `GET /api/live` 增量拉取事件帧
3. 支持语音播报（TTS）：中文走腾讯云大模型语音合成（需管理端配置密钥），日文走浏览器本地语音
4. 加入时返回当前局面快照（`situation`），无需回放全部历史帧即可渲染当前局面

### 5.2 直播房（互动直播 / Live）

**页面**：
- 大厅：对战大厅（承载直播观战入口）
- 观众端：直播观战页

**概述**：
- 直播房由主播创建并逐帧 publish，观众只读镜像
- 2.0.0 起直播不再有独立「播」入口：直播观战并入首页「战」入口，经对战大厅进入

**主播操作流程**（创建自定义挑战功能已下线，直播由对战房开启直播产生）：
1. 在对战大厅创建对战并开启直播
2. 房间状态转为 `matchStatus=live` 后，观众即可观看
3. 逐帧 publish 同步给观众
4. 支持弹幕互动

**观众操作**：
1. 从首页「战」入口进入对战大厅，选择开启了直播的房间 -> 点击「观看」
2. 画面自动增量刷新（无需手动操作）
3. 可发弹幕（需站点开启弹幕功能）
4. 手动「刷新」按钮全量拉取最新帧

### 5.3 观战（Live Viewer）

**入口**：对战大厅中开启直播的房间 → 点击「观看」（直播观战页）

**概述**：
- 与直播房共用同一套观战逻辑
- 观众经首页「战」入口进入对战大厅，对开启直播的房间点击「观看」进入

### 5.4 对战房（Duel / PvP）

**页面**：
- 大厅：对战大厅
- 房间：对战房

**概述**：
- 主队 vs 客队的 PvP 比赛
- 支持 1~9 局制，攻守轮换
- 客场先攻

**对战大厅条目按钮**（按当前登录用户对该房的角色显示）：
- 我是该房主队或客队 -> 显示「返回」（直接回到对战房）
- 第三方且客队未加入（房间可加入）-> 显示「加入」（作为客队加入）
- 主客已满且该房开启了直播 -> 显示「观看」

**完整流程**：

1. **创建**（主队）
   - 在对战大厅点击「创建对战」
   - 设定预设局数（1~9）、是否开启直播
   - 房间状态：`matchStatus=waiting`

2. **客队加入**
   - 在大厅点击「加入对战」
   - `matchStatus=live`，比赛开始
   - **客场先攻**

3. **比赛进行**
   - 当前进攻方掷方块/使用道具 -> 上报一帧
   - 防守方与观众只读镜像
   - 每半局 3 出局后换边
   - 上半局结束 -> 下半局（主队攻）
   - 下半局结束 -> 下一局上半（客队攻）

4. **延长赛**
   - 超过预设局数仍平分 -> 延长赛
   - 0 出局、一、二垒有人

5. **比赛结束**
   - 主队下半局反超 = 再见，立即结束
   - 客队上半局不停止（打完整半局）
   - 结束后 **30 秒**房间自动关闭

**断线**：
- 掉线超过 **30 秒**视为离线；双方都掉线时房间会被回收

### 5.5 AI 对战（AI Duel / 智能体接入）

**入口**：
- 公开接口：`POST /api/ai`
- 接入流程、凭证申请与完整契约：**「AI 接入」站点**（`open.yakidev.top`）与公开契约仓库 `rollinace_duel_api`

**概述**：
- 外部 AI Agent / 服务端策略程序通过公开接口接入对战房
- 两种形态：**人机对战**（AI 加入真人创建的对战房，默认客场先攻）与 **AI vs AI 自对弈**（平台自用）
- 与真人端共用同一套状态机、规则引擎与观战帧通道：AI 每步操作广播一帧，真人端实时可观战
- 席位、鉴权、会话、同时参赛场次与配额等**接入细则**，以「AI 接入」站点的公开契约为准（见上）

**action 一览**（对局内动作；逐字段语义以公开契约为准）：

| action | 说明 |
|---|---|
| `state` | 读取局面 + 服务端给出的允许动作 + 是否轮到本方 |
| `act` | 执行操作（`roll` / `swing` / `read` / `take1b` / `roll2` / `item` / `init` / `duel_half_start` / `set_pitch`） |
| `heartbeat` | 保活（读局面 / 执行操作会顺带刷新在线时间） |
| `leave` | 退出房间 |

**AI 决策循环**：
1. `state`：轮到本方、且服务端给出的允许动作非空时才行动；服务端正在自动换边时稍后重试
2. `act`：按允许动作决策（决策规则与玩家策略一致，见策略指南）
3. 被拒绝的操作会回传可选动作，照它自我纠正即可
4. **换边与比赛结束由服务端自动推进**，AI 无需额外调用

**注意**：
- 规则结算由服务端权威引擎完成，AI 只按服务端给出的允许动作决策，不要本地自行推算结果
- 成功与失败的判定以服务端应答为准
- 正式接入请读 `rollinace_duel_api` 的 `doc/AI_DUEL_API.md` / `doc/QUICKSTART.md` / `doc/AI_DUEL_FAQ.md`（含多语言示例）

**防守选投手（好坏球）**：
- 好坏球**恒开启**，AI 房必然使用，无需任何开关
- AI 防守时按角色配置的「BS 打法」档位决策（全打 / 偏打 / 均衡 / 偏看 / 全看），并参考对方本场「打/看」习惯计数做针对性选档：对方 **打得多 → 偏坏球（保送向）**、对方 **看得多 → 偏好球（三振向）**；选定前停顿约 2 秒（对战 AI 时可见「AI 正在思考投球策略…」）。

---

## 六、历史战绩系统

### 6.1 跨模式战绩记录

**API**：`GET /api/history`

**存储**：与用户主档、背包相互独立的云端记录

**记录内容**：

| 模式 | 字段 | 说明 |
|---|---|---|
| 九下挑战 | `challenge_mode_data.succ_ids` | 通关的活动 id 列表（去重） |
| 系列赛 | `series_mode_data.win_ids` | 夺冠的系列赛 id 列表（去重） |
| 对战 | `duel_mode_data.wins / losses` | 累计胜/负场次 |

- 返回时自动把活动 id 解析成活动名称，找不到则回退为 id

---

## 七、音乐与声音系统

### 7.1 音效

- Web Audio 程序化合成，零外部素材
- `master` 总线控制

### 7.2 BGM 曲库

- mp3 格式，由管理端上传至云端曲库
- 分两个主题：`classic`（经典）和 `endless`（无尽）
- 每主题最多 10 首，单首 ≤ 10MB

### 7.3 场景槽位

每个主题三个槽位，各指定**一首**曲目：

| 槽位 | 触发时机 |
|---|---|
| `always`（全程） | 进入页面即播 |
| `idle`（空闲） | 开打（进入打席）之前 |
| `playing`（局中） | 开打（进入打席）之后 |

- **互斥规则**：全程与空闲/局中不可共存；空闲与局中可并存
- **局中自动降音量**：每主题一个系数（0.2~1.0，默认 0.5），0.3s 渐变，只降 BGM、音效不受影响
- **iOS 限制**：需首次用户手势才能出声（浏览器自动播放策略）

### 7.4 语音播报（TTS）

- 中文：默认走浏览器 `speechSynthesis` 本地免费语音；管理端配置腾讯云密钥后走云端高质量语音
- 日文：始终走浏览器本地语音
- 中文 TTS 音色由管理端配置

---

## 八、功能开关与守卫

### 8.1 站点配置

部分入口与能力由站点配置控制（**是否开放以站内显示为准**）：

| 开关 | 缺省 | 影响 |
|---|---|---|
| 直播 | 开 | 直播大厅 + 直播观战 |
| 速报 | 开 | 速报大厅 + 速报观战 |
| 对战 | 开 | 对战大厅 + 对战房 + 挑战房 |
| 弹幕 | 关 | 弹幕输入区 |
| 语音播报按钮 | 关 | 速报观战页的语音播报按钮 |
| 音乐 | 开 | 音乐总开关 |
| 中文 TTS 音色 | 空 | 空 = 使用浏览器本地免费语音 |
| 公众号文章链接 | 空 | 相关入口 |

> 2.0.0 起直播并入「战」入口：观战能力由「战」入口（对战大厅）承载；各入口是否开放以站内显示为准。

### 8.2 开关的生效方式

- **页面侧**：入口关闭时，对应页面会跳转到统一的不可用页面
- **服务端**：入口关闭时对应请求会被拒绝，不会拉取数据
- 关闭任一入口后，其余功能（掷方块、九下挑战、战绩等）均不受影响

---

## 九、棒球规则要点

### 9.1 出局与半局结束

- 3 出局 = 半局结束
- 三振、双杀、牺牲打失败等都会增加出局数

### 9.2 跑者推进

- 安打按垒数推进跑者（1B 推进 1 垒、2B 推进 2 垒、3B 推进 3 垒）
- HR（本垒打）：所有跑者 + 打者全部回本得分
- **反超即停止**：比分反超后，后续回本跑者不再得分（HR 除外）

### 9.3 双杀（DP）

- 2 出局前：打者出局 + 离本垒最近的跑者出局（2 人出局）
- 2 出局后：降级为普通 OUT（仅打者出局）

### 9.4 保送（BB）

- 打者上一垒
- 垒上跑者逐个推进 1 垒

---

## 十、界面元素说明

### 10.1 主页面

- **记分牌**：显示双方比分、局数、出局数
- **垒包图**：显示一二三垒占垒情况
- **棒球方块区**：投球方块（投手档位）+ 击球方块（命中后）+ 第二颗棒球方块（二选一时显示）
- **道具面板**：6 个技能格，显示库存和使用状态
- **好坏球灯**：3 个坏球灯（绿）+ 2 个好球灯（黄）
- **结果区**：显示本次掷方块结果文案
- **操作按钮**：打 / 看 / 拿下 1B / 放手一搏

### 10.2 模式与入口

- 首页默认即为**九下挑战**（多场连续闯关），打开即进入，无独立按钮
- 对战/速报分别经对战大厅、NEWS 进入（受功能开关控制）
- 首页入口按钮：左列 **NEWS / 战**，右列 **大会 / 技**，共四枚；2.0.0 起删除原「播」（直播）、「报」（速报）独立按钮，直播观战并入「战」、速报并入「NEWS」
- 国际版（`*.rollin-ace.live`）：默认只展示「技」按钮，其余入口（NEWS/战/大会）默认隐藏，除非管理端显式开启对应开关

---

## 十一、API 端点速查

| 端点 | 方法 | 说明 |
|---|---|---|
| `/api/roll` | POST | 掷方块 + 局面推进引擎 |
| `/api/series` | GET | 读取系列赛 + 进度 |
| `/api/series` | POST | 进度上报 |
| `/api/user` | GET | 读取道具背包 |
| `/api/user` | POST | 发奖 / 消耗 / 重置 |
| `/api/live` | GET | 大厅列表 / 增量拉流 |
| `/api/history` | GET | 玩家历史战绩（📜：普通通关/系列赛夺冠/对战胜负） |
| `/api/config` | GET | 公开站点配置（直播/速报/对战/弹幕/TTS/音乐开关等） |
| `/api/migrate` | POST | 找回旧身份（用旧 uid 切回，需 CSRF 头 `X-Requested-With: rollin`） |
| `/api/music` | GET | BGM 下发（`?theme=classic|endless` 按场景取曲目；`&id=` 取指定曲目） |
| `/api/tts` | GET | TTS 语音合成（探测配置状态/合成语音） |
| `/api/teams` | GET | 队伍数据（对战大厅随机队名等） |
| `/api/ai` | POST | AI 对战接口（公开契约：session / create / join / list / state / act / heartbeat / leave / close 等） |

> 管理端接口不在本表列出；速报 / 直播类的后台任务接口见公开仓库 `rollinace_live_api`。

---

## 十二、关键常量（玩家向）

| 常量 | 值 | 说明 |
|---|---|---|
| 击球方块（按球种，各 6 面） | `s0`: OUT×1/FOUL×1/1B×2/二选一×2 · `s1`: OUT×2/FOUL×1/1B×2/二选一×1 · `s2`: OUT×2/FOUL×2/1B×2 · `b1`: OUT×2/FOUL×2/1B×1/二选一×1 · `b2`: OUT×3/FOUL×2/1B×1 | 击中后掷 |
| 二选一方块权重 | DP:1 / BB:1 / 2B:2 / 3B:1 / HR:1 | 高风险分支 |
| 挥空率（按球种） | `s0`:10% / `s1`:20% / `s2`:50% / `b1`:40% / `b2`:80% | 选「打」时 |
| 单机投球档位权重 | 偏好球 30% / 均衡 50% / 偏坏球 20% | 单机每局随机 |
| 每半局技能上限 | 3 次 | 令成功可重置 |
| 背包单类上限 / 总上限 | 20 个 / 120 个 | 6 种各 20 |
| 投球档面板限时 | 5 秒（本场第一次选档且对手是 AI 时 10 秒） | 超时按「均衡」开始 |
| 掉线判定 / 房间自动关闭 | 30 秒 / 30 秒 | 掉线超 30 秒视为离线；比赛结束后 30 秒关房 |
| 新用户初始赠送 | 各 3 个 | 6 种道具 |
| 失败局末奖励权重 | 盗:20 / 牺:20 / 棒:15 / 抡:15 / 雾:15 / 令:15 | 加权随机送 1 个 |

> 接入相关的技术细节（凭证、会话、同时参赛场次与配额等）见「AI 接入」站点与对外契约文档，不在本页展开。