cortico-world-hearthstone 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # 变更记录
 
+## 0.3.2
+
+**听歌时让路（可选，默认关）**
+
+设置页「高级」里多了一个开关。打开后，检测到 QQ 音乐 / 网易云在跑，就按安静处理：
+不主动解说回合和告警，你问的时候照答，关掉播放器自动恢复。
+
+默认关是有意的 —— 两件事同时进行、各说各的，很多人就喜欢那样，不该替人决定。
+觉得吵再打开。注意：播放器挂着没放也算「在跑」，这时同样会安静。
+
+**顺带修掉一个会让她「突然不说话」的问题**
+
+判断「日志文件被重写」的旧条件太松：读完 position 正好等于文件大小是常态，
+而炉石每写一次都会改 mtime，于是每轮都可能被误判成「文件被重写」——
+一旦误判，读取位置归零、整份日志同步重读一遍，而重读进来的回合会被去重挡掉，
+**外面看就是整段静默**。
+
+现在加了文件头 256 字节的指纹比对：只有内容真的变了才当重写。原有那条
+「同样大小被整体重写」的用例仍然通过。
+
+## 0.3.1
+
+**装完就能用：自己把炉石的 Power 日志打开**
+
+上一版只自动关掉了日志大小上限，**没管日志开没开** —— 而炉石的 Power 日志默认是关的，
+开关在用户目录：`%LOCALAPPDATA%\Blizzard\Hearthstone\log.config`。新机器上这个文件
+压根不存在，很多人也从没建过。
+
+症状很坑：`Power.log` 照样存在、照样能读、照样能监听，但里面只有几行错误，
+一行对局数据都没有。**它不报错**，所以看起来像「她一句话都不说」。实测新机器上是
+6 行 `SubSpellController ... Failed to load spell prefab`，`CREATE_GAME` 一次都没有。
+
+现在启动时检查 `[Power]` 段，缺了就补上（`LogLevel=1`、`FilePrinting=true`）：
+
+- 只动 `[Power]` 这一段，画质、分辨率、账号缓存那些一个字节都不碰
+- 改之前留 `log.config.bak`，备份失败就不改
+- 先写临时文件再改名，免得炉石正好启动读到半截配置（半截 ini 会被整段忽略，等于没开）
+- 补完要**重启一次炉石**才生效
+
+**状态灯不再说谎**
+
+日志文件在、但一行对局数据都没有时，以前照样亮绿灯写「已连上日志」。现在分两种情况：
+
+| 情况 | 灯 | 说什么 |
+|---|---|---|
+| 配置是这次才补的（还没重启炉石） | 红 | 「Power 日志之前没开，配置已经补好，重启一次炉石就生效」 |
+| 配置本来就开着，只是还没进对局 | 绿 | 「文件在，但里面还没有对局数据——炉石刚启动，或还没进对局」 |
+
+工具回执也直说原因，不再拿「现在没有进行中的对局」糊过去 —— 那句话会把正在打的人
+带进「我明明在打」的死胡同。
+
 ## 0.3.0
 
 首个公开发布版本。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cortico-world-hearthstone",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "type": "module",
   "description": "Cortico World: 陪打炉石 —— 读对局日志,知道双方的血量、场面、手牌与水晶,在关键节点开口。只看不动游戏,不代打。需要先打开炉石的 Power 日志。",
   "author": {

package/src/config.ts

@@ -31,6 +31,16 @@ export interface HearthstoneConfigSection extends WorldSection {
   speakAlerts: boolean;
   /** normal = 按上面两项自己开口;quiet = 只看不说,等被问。 */
   mode: 'normal' | 'quiet';
+  /**
+   * 听歌时让路。
+   *
+   * 打开后：检测到 QQ 音乐 / 网易云在跑，就按 `quiet` 处理——不主动解说回合和告警，
+   * 你问的时候照答。让的是「主动开口」这一层，工具调用不受影响。
+   *
+   * **默认关。** 两件事同时进行、各说各的，这是很多人喜欢的状态。
+   * 看到进程也不等于真在放歌，挂着不动也会让路。
+   */
+  yieldToMusic: boolean;
   /** 残血阈值:生命值降到这个数以下算告警。 */
   alertHealth: number;
   /** 对手场上随从达到这个数算被压场。 */
@@ -64,6 +74,7 @@ export const HEARTHSTONE_DEFAULTS = (): HearthstoneConfigSection => ({
   adviceInTurn: true,
   speakAlerts: true,
   mode: 'normal',
+  yieldToMusic: false,
   alertHealth: 10,
   swarmCount: 4,
   historySize: 200,
@@ -120,6 +131,11 @@ export function hearthstoneConfigGroups(): ConfigGroup[] {
         title: '高级（一般不用动）',
         description: '阈值和模型。默认值是按真实对局调过的,没遇到具体问题就别改。',
         properties: {
+          'worlds.hearthstone.yieldToMusic': {
+            type: 'boolean',
+            title: '听歌时让路',
+            description: '打开后：检测到 QQ 音乐 / 网易云在跑，就不主动解说（回合提醒和告警都停），你问的时候照答；关掉播放器自动恢复。默认关——两件事同时进行、各说各的，很多人反而喜欢。注意：播放器挂着没放也算「在跑」，这时同样会安静。',
+          },
           'worlds.hearthstone.alertHealth': {
             type: 'integer',
             title: '残血线',

package/src/log-config.ts

@@ -23,6 +23,7 @@
  * 所以唯一的正解是在它启动之前把上限关掉 —— 代价只是最后重启一次炉石。
  */
 import { copyFileSync, existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { basename, dirname, join } from 'node:path';
 
 /** 炉石默认的日志上限（KB）。 */
@@ -237,3 +238,175 @@ export function describeLimit(before: number | null): string {
   if (before === -1) return '已经关掉上限';
   return `${before}KB`;
 }
+
+/* ------------------------------------------------------------------ */
+/* 另一件事：让炉石真的往 Power.log 里写对局数据                       */
+/* ------------------------------------------------------------------ */
+
+/**
+ * 炉石的 Power 日志默认是**关的**。
+ *
+ * `Power.log` 文件会存在（炉石启动时自己建），但里面只有错误行 —— 新机器上实测是
+ * 6 行 `SubSpellController ... Failed to load spell prefab`，`CREATE_GAME` 一次都没有。
+ * 开关在**用户目录**，不在安装目录：
+ *
+ *     %LOCALAPPDATA%\Blizzard\Hearthstone\log.config
+ *     [Power]
+ *     LogLevel=1
+ *     FilePrinting=true
+ *
+ * 没有这个文件就不写 GameState，扩展读到的永远是个空壳。
+ *
+ * 更麻烦的是它**不报错**：文件在、能读、能监听，就是没有内容。用户看到的是「她一句话不说」，
+ * 而不是「日志没开」。所以这层自己补上 —— 装完即用，不能让用户去翻 ini。
+ *
+ * 只动 `[Power]` 这一段，别的段一个字节都不碰；编码走 latin1 逐字节保真。
+ */
+export interface PowerLogResult {
+  configPath: string;
+  /** 动手之前这个文件存在吗。 */
+  existed: boolean;
+  /** 动手之前的状态。 */
+  before: 'ok' | 'incomplete' | 'absent';
+  /** 这次有没有真的写文件。 */
+  changed: boolean;
+  /** 没改成功的原因。 */
+  problem?: string;
+  backup?: string;
+}
+
+/** 炉石日志配置的位置（用户目录，与安装目录无关）。 */
+export function logConfigPath(): string {
+  const local = process.env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local');
+  return join(local, 'Blizzard', 'Hearthstone', 'log.config');
+}
+
+/** `[Power]` 段里这两项齐了，炉石才把对局写进文件。 */
+const POWER_WANT: ReadonlyArray<readonly [string, string]> = [
+  ['LogLevel', '1'],
+  ['FilePrinting', 'true'],
+];
+
+/** 读一遍配置，判断 `[Power]` 段够不够用。 */
+export function powerLoggingState(text: string): 'ok' | 'incomplete' {
+  const seen = new Map<string, string>();
+  let section = '';
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#') || line.startsWith(';')) continue;
+    const sec = /^\[(.+)\]$/.exec(line);
+    if (sec) {
+      section = sec[1].trim().toLowerCase();
+      continue;
+    }
+    const eq = line.indexOf('=');
+    if (eq < 0 || section !== 'power') continue;
+    seen.set(line.slice(0, eq).trim().toLowerCase(), line.slice(eq + 1).trim().toLowerCase());
+  }
+  return POWER_WANT.every(([k, v]) => seen.get(k.toLowerCase()) === v) ? 'ok' : 'incomplete';
+}
+
+/**
+ * 把 `[Power]` 段补成能用的样子，其余原样：
+ * 已有的键只改值，缺的键插在该段末尾，整段都没有就在文件末尾补一段。
+ */
+export function patchPowerLogging(text: string): { text: string; changed: boolean } {
+  if (powerLoggingState(text) === 'ok') return { text, changed: false };
+  const eol = text.includes('\r\n') ? '\r\n' : '\n';
+  const lines = text.length ? text.split(/\r?\n/) : [];
+
+  let section = '';
+  let powerAt = -1;
+  let lastInPower = -1;
+  const have = new Set<string>();
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i].trim();
+    if (!line || line.startsWith('#') || line.startsWith(';')) continue;
+    const sec = /^\[(.+)\]$/.exec(line);
+    if (sec) {
+      section = sec[1].trim().toLowerCase();
+      if (section === 'power') powerAt = i;
+      continue;
+    }
+    const eq = line.indexOf('=');
+    if (eq < 0 || section !== 'power') continue;
+    lastInPower = i;
+    const key = line.slice(0, eq).trim().toLowerCase();
+    const want = POWER_WANT.find(([k]) => k.toLowerCase() === key);
+    if (!want) continue;
+    have.add(key);
+    if (line.slice(eq + 1).trim().toLowerCase() !== want[1]) {
+      lines[i] = `${lines[i].slice(0, eq)}=${want[1]}`;
+    }
+  }
+
+  const missing = POWER_WANT.filter(([k]) => !have.has(k.toLowerCase()));
+  if (powerAt >= 0) {
+    const at = (lastInPower >= 0 ? lastInPower : powerAt) + 1;
+    lines.splice(at, 0, ...missing.map(([k, v]) => `${k}=${v}`));
+    return { text: lines.join(eol), changed: true };
+  }
+
+  const block = ['[Power]', ...POWER_WANT.map(([k, v]) => `${k}=${v}`)];
+  const tail = text.length && !text.endsWith('\n') ? eol : '';
+  const gap = text.length ? eol : '';
+  return { text: `${text}${tail}${gap}${block.join(eol)}${eol}`, changed: true };
+}
+
+/**
+ * 确保炉石会把对局写进 `Power.log`。
+ *
+ * 与 `ensureLogSizeUnlimited` 同一套谨慎标准：先备份，写的时候先临时文件再改名 ——
+ * 免得炉石正好启动读到半截配置（半截 ini 会让它整段忽略，等于没开）。
+ */
+export function ensurePowerLogging(configPath = logConfigPath()): PowerLogResult {
+  const existed = existsSync(configPath);
+  const text = readText(configPath);
+  const base: PowerLogResult = {
+    configPath,
+    existed,
+    before: text === null ? 'absent' : powerLoggingState(text),
+    changed: false,
+  };
+  if (text === null && existed) return { ...base, problem: 'log.config 读不出来（权限或格式）' };
+
+  const patched = patchPowerLogging(text ?? '');
+  if (!patched.changed) return base;
+
+  let backup: string | undefined;
+  if (text !== null) {
+    const bak = `${configPath}.bak`;
+    if (!existsSync(bak)) {
+      try {
+        copyFileSync(configPath, bak);
+        backup = bak;
+      } catch {
+        return { ...base, problem: '备份 log.config 失败，没敢改' };
+      }
+    } else {
+      backup = bak;
+    }
+  }
+
+  try {
+    const tmp = `${configPath}.tmp`;
+    writeFileSync(tmp, patched.text, 'latin1');
+    renameSync(tmp, configPath);
+  } catch (error) {
+    return { ...base, backup, problem: `写不进去（${(error as Error).message}）` };
+  }
+
+  return { ...base, changed: true, backup };
+}
+
+/** 供诊断文案用：一句话交代日志开没开。 */
+export function describePowerLogging(result: PowerLogResult): string {
+  if (result.problem) return `开不起来：${result.problem}`;
+  if (result.changed) {
+    return result.before === 'absent'
+      ? '之前没有 log.config，已建好（重启炉石后生效）'
+      : '之前 [Power] 段不全，已补齐（重启炉石后生效）';
+  }
+  return 'Power 日志已开着';
+}

package/src/log-source.ts

@@ -169,6 +169,8 @@ export class PowerLogTail {
   private failures = 0;
   /** 上一次看到的修改时间:用来识别「文件被整体重写成同样大小」这种只比长度抓不到的情况。 */
   private lastMtimeMs = 0;
+  /** 文件开头 256 字节的内容指纹。只在怀疑被整体重写时读一次，不是每轮都读。 */
+  private headSig = '';
   /** 上次重新扫目录找日志的时刻。 */
   private lastResolveAt = 0;
   /** 上次定位的结果(含「没找到」)。缓存到下一次重扫。 */
@@ -250,6 +252,8 @@ export class PowerLogTail {
         this.decoder = new StringDecoder('utf8');
         this.partial = '';
         this.lastMtimeMs = 0;
+        // 换了文件，旧指纹作废，下一轮重新取
+        this.headSig = '';
         this.opts.log?.info(`开始读炉石日志:${nextPath}(${found?.why ?? ''},从第 ${this.offset} 字节起)`);
       }
       this.opts.onSwitch?.(nextPath);
@@ -262,18 +266,45 @@ export class PowerLogTail {
     this.drain(nextPath);
   }
 
+  /** 读文件开头一小段当指纹。读不到返回空串（空串不会等于任何已有指纹，因此不会误起重写）。 */
+  private headSignature(path: string): string {
+    try {
+      const size = statSize(path);
+      if (size <= 0) return '';
+      const fd = openSync(path, 'r');
+      const buf = Buffer.allocUnsafe(Math.min(256, size));
+      try {
+        readSync(fd, buf, 0, buf.length, 0);
+      } finally {
+        closeSync(fd);
+      }
+      return buf.toString('latin1');
+    } catch {
+      return '';
+    }
+  }
+
   private drain(path: string, initial = false): void {
     const stat = statOrNull(path);
     if (!stat) return;
     const { size, mtimeMs } = stat;
 
-    // 两种「文件被换掉」:变短了,或者长度没变但内容被整体重写(mtime 动了、长度没长)。
-    // 只看 size 会漏掉后一种 —— 新一局恰好和上一局同样大小时就会安静地卡住。
-    const rewritten = size < this.offset || (mtimeMs !== this.lastMtimeMs && size <= this.offset && size > 0);
+    // 「文件变短」一定是被换掉了。
+    //
+    // 「长度没变但 mtime 动了」必须再确认**内容真的变了**才算重写，否则正常轮询会误判 ——
+    // 读完 offset 正好等于 size 是常态，而炉石每写一次都会改 mtime。误判的代价是 offset 归零、
+    // 整份日志同步重读一遍，而重读进来的回合早被解析器 `lastQueuedTurn` 去重挡掉，
+    // **外面看着就是炉石这条链路突然不出声**（2026-10-27 实测：第 21、23 回合和结束事件
+    // 就这么丢的）。所以这里加一道 256 字节的内容比对，只在可疑时读一次。
+    const truncated = size < this.offset;
+    if (!this.headSig) this.headSig = this.headSignature(path);
+    const suspect = !truncated && size === this.offset && size > 0 && mtimeMs !== this.lastMtimeMs;
+    const rewritten = truncated || (suspect && this.headSignature(path) !== this.headSig);
     if (rewritten && this.offset > 0) {
       this.offset = startOffsetFor(path, size);
       this.decoder = new StringDecoder('utf8');
       this.partial = '';
+      this.headSig = this.headSignature(path);
     }
     this.lastMtimeMs = mtimeMs;
 

package/src/peer.ts

@@ -0,0 +1,56 @@
+/**
+ * 对端扩展对应的程序在不在跑。
+ *
+ * 为什么需要这一层：两个扩展装在同一个宿主里，各推各的事件，**互相不认识** ——
+ * 宿主只给了「往同一个对话推事件」这一条路，没有 world 之间互查状态的接口。
+ * 而「听歌的时候别解说」这种需求是真的，进程列表就是唯一不需要跨扩展通信、
+ * 也不用改宿主就能拿到的信号。
+ *
+ * 代价要说清楚：**看到进程 ≠ 正在听**。播放器挂着没放也算在跑，这时炉石同样会安静。
+ * 所以它只能躲在用户自己打开的开关后面，不能默认开。
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const run = promisify(execFile);
+
+/** 缓存时长：tasklist 一次要一两百毫秒，不能每次要判断都跑一遍。 */
+const TTL_MS = 15_000;
+
+let lastAt = 0;
+let lastHit = false;
+
+/**
+ * 名单里任一进程在跑就返回 true。
+ *
+ * 查询失败时返回 false（当作没在跑）—— 这个方向是刻意的：宁可多说几句，
+ * 也不要因为一次 tasklist 失败就让她整场闭麦，那种「突然不说话」最难排查。
+ */
+export async function isPeerRunning(names: readonly string[]): Promise<boolean> {
+  const now = Date.now();
+  if (now - lastAt < TTL_MS) return lastHit;
+
+  let hit = false;
+  try {
+    // /FO CSV 一行一个进程，形如 "QQMusic.exe","1234","Console","1","1,234 K"
+    const { stdout } = await run('tasklist', ['/NH', '/FO', 'CSV'], {
+      timeout: 4000,
+      windowsHide: true,
+      maxBuffer: 4 << 20,
+    });
+    const lower = stdout.toLowerCase();
+    hit = names.some((name) => lower.includes(`"${name.toLowerCase()}"`));
+  } catch {
+    hit = false;
+  }
+
+  lastAt = now;
+  lastHit = hit;
+  return hit;
+}
+
+/** 测试用：把缓存清掉。 */
+export function resetPeerCache(): void {
+  lastAt = 0;
+  lastHit = false;
+}

package/src/world.ts

@@ -21,7 +21,11 @@ import { PowerLogTail, describeSearch, looksLikePowerLog, resolvePowerLog } from
 import { PowerLogParser, renderSnapshot, type ActionRecord, type GameSnapshot, type SideState, type TurnPoint } from './parser.ts';
 import { detectAlerts, endMarker, endText, faceOf, lethalText, startText, surpriseAlerts, toneOf } from './alerts.ts';
 import { panelAdvice, panelAskText, panelStatus, type PanelAdvice, type PanelStatus } from './panel.ts';
-import { describeLimit, ensureLogSizeUnlimited, installDirFromLog } from './log-config.ts';
+import {
+  describeLimit, describePowerLogging, ensureLogSizeUnlimited, ensurePowerLogging, installDirFromLog,
+  logConfigPath, type PowerLogResult,
+} from './log-config.ts';
+import { isPeerRunning } from './peer.ts';
 import { advise, buildModelPrompt, renderAdvice } from './advice.ts';
 import { askModel, pickKey, type LlmConfig } from './llm.ts';
 import { composeTurnEvent, settleTurnWatermark, shouldAnnounceTurn } from './turn-event.ts';
@@ -135,6 +139,7 @@ export interface HearthstoneWorldOptions {
 
 type Phase = 'no-log' | 'watching' | 'in-game' | 'ended';
 
+
 interface WatchStatus {
   phase: Phase;
   path: string | null;
@@ -289,6 +294,21 @@ export class HearthstoneWorld implements World {
   private readonly parser = new PowerLogParser(nowIso);
   private tail: PowerLogTail | null = null;
   private status: WatchStatus = { phase: 'no-log', path: null, note: '还没开始读日志。' };
+  /**
+   * start() 时处理 log.config 的结果。
+   *
+   * 补过（changed=true）就说明这次还没重启过炉石 —— 在用户重启之前，
+   * 日志里不可能有对局数据，这时亮红灯是**如实报告**，不是误报。
+   */
+  private powerLog: PowerLogResult | null = null;
+  /**
+   * 播放器在不在跑（「听歌时让路」用）。
+   *
+   * 由定时器维护、`onLines` 里同步读 —— 那边是同步函数，不能在里面 await tasklist。
+   * 开关没开时常为 false，探测也直接跳过，不白花这一两百毫秒。
+   */
+  private musicRunning = false;
+  private peerTimer: ReturnType<typeof setInterval> | null = null;
   private chain: Promise<void> = Promise.resolve();
   private lastSnapshot: GameSnapshot | null = null;
   private announcedStart = false;
@@ -369,9 +389,36 @@ export class HearthstoneWorld implements World {
 
   /* ---------- 生命周期 ---------- */
 
+  /**
+   * 看一眼播放器在不在跑。只在「听歌时让路」打开时才真去查 tasklist。
+   *
+   * 单独拿出来是因为 `onLines` 是同步的 —— 那边不能 await，只能读这里维护的字段。
+   * 查询失败按「没在跑」处理：宁可多说几句，也不要因为一次查询失败整场闭麦。
+   */
+  private async probePeers(): Promise<void> {
+    if (!this.cfg.yieldToMusic) {
+      this.musicRunning = false;
+      return;
+    }
+    this.musicRunning = await isPeerRunning(['QQMusic.exe', 'cloudmusic.exe']);
+  }
+
   async start(host: WorldHost): Promise<void> {
     this.host = host;
     this.log = host.log;
+    // Power 日志默认是**关的**：开关在用户目录的 log.config 里，很多人从来没建过。
+    // 没开的时候炉石只往 Power.log 写错误行，扩展读到的是个空壳——而且不报错，
+    // 用户只会看到「她一句话不说」。和上面关日志上限是同一类事：装完即用，别让人翻 ini。
+    this.powerLog = ensurePowerLogging();
+    if (this.powerLog.problem) {
+      this.log?.warn(`炉石的 Power 日志开关没能处理:${this.powerLog.problem}`);
+    } else {
+      this.log?.info(`Power 日志:${describePowerLogging(this.powerLog)}`);
+    }
+    // 「听歌时让路」用：每 15 秒看一眼播放器在不在（开关没开就直接返回，不白跑 tasklist）。
+    void this.probePeers();
+    this.peerTimer = setInterval(() => void this.probePeers(), 15_000);
+    this.peerTimer.unref?.();
     this.parser.setHistoryLimit(this.opts.cfg.historySize);
     this.tail = new PowerLogTail({
       getPath: () => resolvePowerLog({ logPath: this.cfg.logPath, installDir: this.cfg.installDir }),
@@ -395,6 +442,10 @@ export class HearthstoneWorld implements World {
   }
 
   async stop(): Promise<void> {
+    if (this.peerTimer) {
+      clearInterval(this.peerTimer);
+      this.peerTimer = null;
+    }
     this.tail?.stop();
     this.tail = null;
     this.clearPendingEndTimer();
@@ -457,12 +508,28 @@ export class HearthstoneWorld implements World {
     // 用快照判,不要用 parser.inGame —— 后者只表示「日志里有过一局」,
     // 那局已经打完它也是 true,于是灯一直亮成「进行中」,她也会以为自己还在牌桌上。
     const s = this.parser.snapshot();
+    if (s) {
+      this.status = {
+        phase: s.ended ? 'ended' : 'in-game',
+        path,
+        note: s.ended ? '这局已经结束。' : `第 ${s.turn} 回合。`,
+      };
+      return;
+    }
+    // 文件在、却一行对局数据都没有:要么炉石刚启动还没进对局,要么 Power 日志根本没开。
+    // 这两种必须分开 —— 前者一开打就恢复,后者得重启炉石,红灯不能乱亮。
+    // 判据用 powerLog.changed:配置是这次才补上的,那就一定还没重启过,亮红灯是如实报告。
+    if (looksLikePowerLog(path)) {
+      this.status = { phase: 'watching', path, note: '已连上日志。' };
+      return;
+    }
+    const waitingRestart = this.powerLog?.changed === true;
     this.status = {
-      phase: s ? (s.ended ? 'ended' : 'in-game') : 'watching',
+      phase: waitingRestart ? 'no-log' : 'watching',
       path,
-      note: s
-        ? (s.ended ? '这局已经结束。' : `第 ${s.turn} 回合。`)
-        : (looksLikePowerLog(path) ? '已连上日志。' : '文件在,但里面还没有对局数据——炉石可能刚启动,或 Power 日志没开全。'),
+      note: waitingRestart
+        ? 'Power 日志之前没开,配置已经补好,重启一次炉石就生效。'
+        : '文件在,但里面还没有对局数据——炉石刚启动,或还没进对局。',
     };
   }
 
@@ -556,19 +623,21 @@ export class HearthstoneWorld implements World {
       this.enqueue(() => this.push('hearthstone.game.start', 'hearthstone.game.start', `[happy]${startText(snapshot)}`, 'flush'));
     }
 
-    const quiet = initial || this.cfg.mode === 'quiet';
+    // 「听歌时让路」：播放器在跑就按安静处理。让的是**主动解说**这一层（回合提醒、告警），
+    // 工具调用和被问时的回答不受影响 —— 让路不等于拒答。
+    const quiet = initial || this.cfg.mode === 'quiet' || this.musicRunning;
 
-    // 回合事件由解析器按「进入行动阶段」记下来,这里只管取走并开口。
-    // 不能在批次边界判断 isMyTurn —— 一批跨几个回合时,批末早不是当时的局面了。
-    // 回合提醒:由**这一批结束时算出来的快照**驱动,不再靠标签回调排队。
-    //
-    // 为什么改:以前在 CURRENT_PLAYER / STEP 的回调里排队,那条路依赖
-    // `isMyTurnNow()`(按玩家名分桶)判断轮次。长时间跑下来桶会失准,结果是整整一局
-    // 一个回合事件都排不出来。快照里的 isMyTurn 和后面算建议用的是同一份数据,
-    // 不会出现「判定说轮到我、数据却显示是对手」。
+    // 回合事件由解析器**逐回合**记下来（每进一次我的行动阶段就记一个点），这里逐个取走再开口。
     //
-    // 资源没刷新(水晶 0)时不更新 lastAnnouncedTurn,下一批自然重试;报过就不再报,
-    // 所以同一回合不会重复开口。
+    // 不能拿「这一批结束时的快照」代表整批 —— 那是以前的写法，也是漏报的病根。
+    // 同一份真实日志，只改批大小，实测：
+    //   批   400 行 → 报 1,3,5,...,23 共 12 次，全对
+    //   批  2000 行 → 只报 7 次，漏 5 个
+    //   批  6000 行 → 只报 2 次
+    //   批 15000 行 → 一次都不报
+    // 因为批末早不是那些回合的局面了：批尾落在对方回合或已结束时，中间所有回合一起被吞。
+    // 而 tail 一旦卡顿（文件被占用、休眠唤醒、大日志读得慢），积压就是几万行一起涌进来。
+    // 按队列补报与批大小无关，才是稳的。
     if (!quiet && this.cfg.speakTurns && shouldAnnounceTurn(snapshot, this.lastAnnouncedTurn)) {
       const point: TurnPoint = {
         turn: snapshot.turn,
@@ -1225,6 +1294,16 @@ export class HearthstoneWorld implements World {
         '要让她看得到,得先打开炉石的日志:在 %LOCALAPPDATA%\\Blizzard\\Hearthstone\\log.config 里写 [Power] 段(LogLevel=1、FilePrinting=true),然后重启炉石。装到别的盘的话,在设置里填一下「炉石安装目录」。',
       ].join('\n');
     }
+    // 日志文件在、但里面没有对局数据:最常见的原因不是「没在打」,是 Power 日志压根没开。
+    // 这时候只说「现在没有进行中的对局」等于把用户往「我明明在打」的死胡同里带。
+    if (this.powerLog?.changed) {
+      const where = this.powerLog.configPath || logConfigPath();
+      return [
+        `现在看不到对局:日志在 ${this.status.path},但里面一行对局数据都没有。`,
+        `原因是炉石的 Power 日志之前没开。已经补好 ${where}([Power] 段:LogLevel=1、FilePrinting=true),**重启一次炉石就生效**。`,
+        '之前已经打的对局补不回来 —— 那段时间炉石根本没往文件里写。',
+      ].join('\n');
+    }
     return `现在没有进行中的对局。日志在:${this.status.path}。${this.status.note}`;
   }