# 配置说明（`~/.dsh/kon-fee-widget.json`）

轻音部费罐的设置分两半：

- **页面里能改的**：设置页「坐上桌的人」、齿轮菜单「大小 / 声音 / 回到右下角」——
  这些会**直接写回**配置文件；
- **其余旋钮**：写在 `~/.dsh/kon-fee-widget.json` 里，手改即可（也可以在设置页点
  「编辑配置」用弹窗改）。

配置文件是**带注释的 JSON（JSONC）**，首次启动自动生成。读取时会剥掉注释，所以注释不会影响运行。

---

## 1. 生效方式

| 场景 | 什么时候生效 |
|---|---|
| 页面里改（角色 / 大小 / 声音） | 立即 |
| 手改配置文件 | 刷新页面后（宿主每次请求都重新读盘） |
| 文件写坏（非法 JSON） | 自动回落到默认值，并重写一份带注释的默认配置 |

> 桌面端的插件包在 DSH 启动时加载，所以**升级插件**需要重启 DSH；只改配置不用重启。

---

## 2. 逐行注释版

默认生成的文件长这样（注释就是解释，`//` 后面的内容会被忽略）：

```jsonc
{
  // ── 总开关 ────────────────────────────────────────────────
  // 整个挂件是否显示。false = 茶桌、气泡全部消失（相当于临时关掉挂件）
  "visible": true,

  // ── 桌上的人 ──────────────────────────────────────────────
  // 五个人谁坐上桌；false 的人连同他/她那一段桌子一起收起。
  // 可选 id：mio（澪）ritsu（律）yui（唯）tsumugi（䌷）azusa（梓）
  // 五个人全是 false 时，整张桌子都不显示。
  "characters": { "mio": true, "ritsu": true, "yui": true, "tsumugi": true, "azusa": true },
  // 整张茶桌缩放，0.5 ~ 1.6；1 = 原尺寸（288×160 逻辑像素）
  "scale": 1,
  // 拖到屏幕边缘松手后是否自动贴边（吸附距离 24px）
  "snap": true,

  // ── 余额 ──────────────────────────────────────────────────
  // 余额自动刷新间隔（秒，15 ~ 600）。点一下茶桌也会立即刷新。
  "refreshSeconds": 60,
  // 余额低于这个金额（元）时：账本数字变红、台词换成"省钱"版。
  "warnBelow": 5,

  // ── 每轮消耗 ──────────────────────────────────────────────
  // 每轮对话结束后是否弹「本轮 ¥x.xxx」小气泡（宿主按 DSH 会话事件结算）。
  "turnBubble": true,

  // ── 账本气泡 ──────────────────────────────────────────────
  // 账本气泡停留时长（毫秒，2000 ~ 60000）；点茶桌 / 点空白也会立刻收起。
  "panelDurationMs": 8000,
  // 气泡背景：
  //   "cassette"      = 卡带（裁到卡带本体，默认）
  //   "cassette-full" = 整张卡带原图（含灰底和右下角 Logo）
  //   "mascot"        = 动物玩偶图（整张）
  //   "plain"         = 无背景的奶油色卡片
  "bubbleStyle": "cassette",
  // 气泡面积 =（桌子 + 人物）面积 × 这个比例，默认 1.3（130%），范围 0.5 ~ 3。
  // 人少时桌子会变短，气泡也跟着变小。
  "bubbleAreaRatio": 1.3,

  // ── 双击彩蛋 ──────────────────────────────────────────────
  // 双击茶桌是否弹一句台词。
  "easterEgg": true,
  // 按「在场的人」分配台词：
  //   "角色id": [ ... ]          单人台词（只有这个人在场时用）
  //   "角色id+角色id": [ ... ]   组合台词（两人都在场时按概率触发，顺序无关）
  // 每条可以写成：
  //   "一句中文"                                            （中日共用）
  //   { "zh": "中文", "ja": "日本語", "voice": "mio_01.mp3" }（中日各一份，可带配音）
  // 例子：
  //   "mio": [ { "zh": "澪：今天先到这里吧…", "ja": "澪：今、今日はこのへんで…", "voice": "mio_01.mp3" } ],
  //   "azusa+yui": [ { "zh": "唯：梓喵，一起练琴吧！", "ja": "唯：あずにゃん、一緒に練習しよう！" } ]
  // 每个池子最多 30 条，每条 120 字以内。
  "eggLines": {},
  // 组合台词触发概率 0 ~ 1（默认 0.5 = 一半几率）。
  // 没命中时退回「在场某一个人的单人台词」；单人在场时永远只出本人台词。
  "eggComboChance": 0.5,
  // 台词语言："zh" 中文 / "ja" 日文。只写一种语言的条目会两边都出。
  "lang": "zh",
  // 有配音文件时是否播放；语音文件放到插件目录 assets/voices/ 下（mp3/ogg/wav/m4a）。
  "voice": true,
  // 兜底台词：eggLines 里找不到时从这里随机挑。留空数组 = 用内置的十句。
  "easterEggLines": []
}
```

---

## 3. 字段速查

| 键 | 类型 | 默认 | 范围 | 说明 |
|---|---|---|---|---|
| `visible` | boolean | `true` | — | 整个挂件是否显示；`false` 时茶桌完全消失 |
| `characters` | object | 五人全 `true` | — | 五个人谁坐上桌，见 [3.1](#31-characters) |
| `scale` | number | `1` | 0.5 ~ 1.6 | 整张茶桌缩放（气泡按面积比例跟着变） |
| `snap` | boolean | `true` | — | 拖到屏幕边缘松手后是否自动贴边 |
| `refreshSeconds` | number | `60` | 15 ~ 600 | 余额自动刷新间隔（点茶桌也会刷新） |
| `warnBelow` | number | `5` | 0 ~ 10000 | 余额低于这个金额时，数字变红 |
| `turnBubble` | boolean | `true` | — | 每轮对话结束是否弹「本轮消耗」小气泡 |
| `panelDurationMs` | number | `8000` | 2000 ~ 60000 | 账本气泡停留时长（毫秒） |
| `bubbleStyle` | string | `"cassette"` | `cassette` / `cassette-full` / `mascot` / `plain` | 气泡背景，见 [3.2](#32-bubblestyle) |
| `bubbleAreaRatio` | number | `1.3` | 0.5 ~ 3 | 气泡面积 =（桌子+人物）面积 × 这个比例 |
| `easterEgg` | boolean | `true` | — | 双击茶桌是否弹彩蛋台词 |
| `eggLines` | object | `{}` | — | 按在场角色的彩蛋台词，见 [3.3](#33-egglines) |
| `eggComboChance` | number | `0.5` | 0 ~ 1 | 组合台词触发概率 |
| `eggSequential` | array | `["mio+ritsu"]` | 最多 8 个键 | 按剧本顺序播放的组合：命中就不看概率，点一次播一句、播完循环 |
| `lang` | string | `"zh"` | `zh` / `ja` | 彩蛋台词语言 |
| `voice` | boolean | `true` | — | 有配音文件时是否播放 |
| `easterEggLines` | array | `[]` | — | 兜底台词池（字符串或 `{zh,ja,voice}`），留空用内置十句 |

### 3.1 characters

```jsonc
"characters": { "mio": true, "ritsu": true, "yui": true, "tsumugi": true, "azusa": true }
```

| id | 角色 |
|---|---|
| `mio` | 秋山澪 |
| `ritsu` | 田井中律 |
| `yui` | 平泽唯 |
| `tsumugi` | 琴吹䌷 |
| `azusa` | 中野梓 |

- 关掉谁：谁消失，**桌子对应的那一段也一起收起**（整张桌子变短）；
- 五个全关：**整张桌子都不显示**（等同于隐藏挂件）。

### 3.2 bubbleStyle

| 值 | 效果 |
|---|---|
| `cassette` | 裁到卡带本体，气泡就是卡带（默认） |
| `cassette-full` | 整张卡带原图（含灰底与右下角 Logo） |
| `mascot` | 动物玩偶图（整张） |
| `plain` | 无背景的奶油色卡片 |

### 3.3 eggLines

按「在场的人」分配台词：

```jsonc
"eggLines": {
  "mio": [
    { "zh": "澪：今天先到这里吧…", "ja": "澪：今、今日はこのへんで…", "voice": "mio_01.mp3" },
    { "zh": "澪：别、别盯着我看啦！", "ja": "澪：見、見ないでよ！" }
  ],
  "yui": ["唯：蛋糕！蛋糕！"],
  "azusa+yui": [
    { "zh": "唯：梓喵，一起练琴吧！", "ja": "唯：あずにゃん、一緒に練習しよう！" }
  ]
}
```

规则：

| 在场情况 | 行为 |
|---|---|
| 只有 1 个人 | 只出这个人的台词（100%） |
| 多人在场 | 先找组合台词，按 `eggComboChance` 概率触发；没命中退回在场某人的单人台词 |
| 组合优先级 | 人多的组合先试（5 人 → 4 人 → … → 2 人），命中即用 |
| 键的顺序 | 无关：`"ritsu+mio"` 与 `"mio+ritsu"` 等价 |

条目写法：

- 纯字符串 = 中文，切到日文也出这句；
- `{ "zh": "...", "ja": "...", "voice": "文件名" }`：中日各一份，可带配音；
- 每个池子最多 30 条，每条最多 120 字。
- `eggSequential` 里的组合（默认 `mio+ritsu`）走「剧本模式」：按数组顺序逐句播放，点一次一句，不随机、不看 `eggComboChance`。
- 剧本台词**内置在代码里**（阳台相会 17 句 + `assets/voices/balcony/` 配音）：`eggLines` 留空就自动用内置版；写了自定义内容则优先用你的，键顺序无关（`mio+ritsu` 与 `ritsu+mio` 等价）。
- 多说话人的组合台词用 `｜` 分隔（如 `"唯：梓喵！｜梓：唯学姐！"`），双击后会**一句接一句**地播放；单条台词只有一句。

### 3.4 语音

台词里写 `"voice": "mio_01.mp3"` 时，从插件目录 `assets/voices/mio_01.mp3` 播放。支持 mp3 / ogg / wav / m4a。
`"voice": false` 或齿轮菜单里关掉声音，就不播。文件不存在时静默跳过。

---

## 4. 常见问题

**Q：改完没反应？**
刷新页面（配置每次请求都重新读盘）。改了插件文件才需要重启 DSH。

**Q：文件被我写坏了？**
下一次读取自动回默认，并把文件重写成带注释的默认内容，不会把挂件弄挂。

**Q：挂件突然完全不显示了？**
先看安装副本有没有缺文件：`node scripts/verify-install.mjs <安装目录>`，或访问 `GET /dsh-kon-fee-widget/health`（返回 `{ ok, missing, version }`）。最常见的坑是 `assets/table/` 整目录没拷过去——画布拿不到贴图就全空，看起来像"挂件消失"，而宿主接口仍然正常。

**Q：节假日的价格怎么算？**
工作日 9:00–12:00、14:00–18:00 高峰，其余谷时；周末全天谷价；**法定节假日全天谷价**（`src/core.cjs` 与 `lib/index.js` 里的 `HOLIDAY_VALLEY` 表，目前覆盖 2026 年）。每年 11 月国务院公布次年安排后需要补表，否则次年节假日会按高峰算。

**Q：`scale` 和 `bubbleAreaRatio` 冲突吗？**
不冲突：`scale` 是整体缩放（连气泡一起），`bubbleAreaRatio` 只决定气泡相对桌子的大小。

**Q：为什么单人在场时气泡很小？**
气泡面积是「桌子+人物面积 × 1.3」，只有一个人时桌子被切得很短，气泡自然小。
想要固定大小可以把 `bubbleAreaRatio` 调大。