dsh-whale-live 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.2.1 — 2026-11-11
+
+### Fixed
+- **Mouth sync failed on non-ASCII data paths.** `miniaudio` could not decode the synthesized mp3 when the audio folder contained Chinese characters (`failed to decode file, -7`), so speech fell back to silent, mouth-less playback. The mp3 is now copied to an ASCII temp path before decoding.
+- `whale_say` now surfaces the mouth-sync error instead of quietly omitting the "mouth moved" marker.
+
+### Added
+- `whale_live action=vts`: trigger VTube Studio hotkeys / toggle expressions / set the mouth while live, so the model can act on its own judgement.
+
+### Known issues in 0.2.0
+- Mouth movement during plugin speech could silently fail whenever `dataDir` contained non-ASCII characters.
+- No plugin-side way to trigger expressions or hotkeys during a stream.

package/README.md

@@ -74,6 +74,21 @@ The model acts **through** these tools; the plugin never writes to DSH long-term
 - **Bilibili**: uses the unofficial `ajax/msg` endpoint; it can change or rate-limit, and some rooms return empty. Read-only — the plugin never sends danmaku.
 - **VTube Studio**: optional. Without a mouth driver directory the plugin degrades to plain audio playback.
 
+## Compatibility range (explicit)
+
+| Axis | Declared | Notes |
+| --- | --- | --- |
+| OS | `win32` only | `os: ["win32"]`; MCI playback and the app launch helpers are Windows APIs |
+| DSH | `>=0.2.1-rc.2 <0.4.0` | Verified on `0.2.2-rc.1` (desktop profile) |
+| Node | `>=20` | Uses global `fetch`, ESM top-level await |
+| Python | 3.10+ with `edge-tts` | Required only for speech; omit `pythonPath` to run silent |
+| Bilibili | cookie JSON | Uses the unofficial `ajax/msg` endpoint; read-only; may break or rate-limit |
+| VTube Studio | optional | Set `vtsPath` or leave it empty to launch through Steam; `vtubeDir` enables mouth sync |
+| OBS / 直播姬 | optional | Launch helpers only; the plugin never starts the stream |
+
+Anything outside these ranges is unsupported. DSH slot/service APIs are the main
+breaking risk across minor releases.
+
 ## Privacy
 
 - No telemetry; no accounts; nothing is uploaded.

package/client.js

@@ -23,6 +23,12 @@ window.__ModuleLoader__.load({
         tabConsciousness: '意识',
         tabDiary: '观察日记',
         tabCandidates: '入忆候选',
+        tabPrepare: '准备',
+        prepareHint: '开播前先把设备架好：拉起 VTube Studio / OBS / 直播间页面，只准备，不推流；自检会逐项报告缺什么。',
+        stageBtn: '架好设备',
+        diagnoseBtn: '自检',
+        prepareSummary: '{ok}/{total} 通过 · {failed} 项必须修 · {warned} 项可选',
+        stageDone: '设备已拉起（没有自动推流）。',
         stateLive: '直播中',
         stateIdle: '未开播',
         stat: '说话 {says} · 弹幕 {danmaku} · 记 {notes}',
@@ -65,6 +71,12 @@ window.__ModuleLoader__.load({
         tabConsciousness: 'Consciousness',
         tabDiary: 'Field diary',
         tabCandidates: 'Memory inbox',
+        tabPrepare: 'Prepare',
+        prepareHint: 'Set the gear up before going live: VTube Studio, OBS and the room page. Preparation only — nothing starts streaming.',
+        stageBtn: 'Set up',
+        diagnoseBtn: 'Self-check',
+        prepareSummary: '{ok}/{total} passed · {failed} required · {warned} optional',
+        stageDone: 'Gear is up (streaming was not started).',
         stateLive: 'Live',
         stateIdle: 'Off air',
         stat: '{says} spoken · {danmaku} danmaku · {notes} notes',
@@ -196,6 +208,8 @@ window.__ModuleLoader__.load({
       const [draft, setDraft] = useState('');
       const [doc, setDoc] = useState({ kind: '', text: '', loading: false, error: '' });
       const [docTick, setDocTick] = useState(0);
+      const [diag, setDiag] = useState(null);
+      const [diagLoading, setDiagLoading] = useState(false);
       const alive = useRef(true);
 
       useEffect(() => {
@@ -258,6 +272,22 @@ window.__ModuleLoader__.load({
         }
       }, [flash, t]);
 
+      const loadDiag = useCallback(async () => {
+        setDiagLoading(true);
+        try {
+          const data = await getJson('/diagnose');
+          if (alive.current) setDiag(data);
+        } catch (cause) {
+          flash(`${t('actionFailed')}：${cause instanceof Error ? cause.message : String(cause)}`);
+        } finally {
+          if (alive.current) setDiagLoading(false);
+        }
+      }, [flash, t]);
+
+      useEffect(() => {
+        if (tab === 'prepare') loadDiag();
+      }, [tab, loadDiag]);
+
       const onSay = useCallback(async () => {
         const text = draft.trim();
         if (!text) return;
@@ -278,6 +308,7 @@ window.__ModuleLoader__.load({
 
       const tabs = [
         ['live', t('tabLive')],
+        ['prepare', t('tabPrepare')],
         ['consciousness', t('tabConsciousness')],
         ['diary', t('tabDiary')],
         ['candidates', t('tabCandidates')],
@@ -397,6 +428,56 @@ window.__ModuleLoader__.load({
               : h('p', { key: 'none', className: 'dshwl-muted' }, t('noEvents')),
           ]);
         }
+      } else if (tab === 'prepare') {
+        body = h('div', {}, [
+          h('p', { key: 'hint', className: 'dshwl-hint' }, t('prepareHint')),
+          h('div', { key: 'actions', className: 'dshwl-actions' }, [
+            h('button', {
+              key: 'stage',
+              type: 'button',
+              className: 'dshwl-btn primary',
+              disabled: busy !== '',
+              onClick: async () => {
+                const result = await run('stage', 'stage');
+                if (result) {
+                  flash(t('stageDone'));
+                  loadDiag();
+                }
+              },
+            }, t('stageBtn')),
+            h('button', {
+              key: 'diag',
+              type: 'button',
+              className: 'dshwl-btn',
+              disabled: diagLoading,
+              onClick: loadDiag,
+            }, diagLoading ? '…' : t('diagnoseBtn')),
+            session ? null : h('button', {
+              key: 'live',
+              type: 'button',
+              className: 'dshwl-btn',
+              disabled: busy !== '',
+              onClick: () => run('session', 'open'),
+            }, t('open')),
+          ]),
+          diag
+            ? h('p', { key: 'sum', className: 'dshwl-muted' }, fill(t('prepareSummary'), diag.summary))
+            : (diagLoading ? h('p', { key: 'load', className: 'dshwl-muted' }, t('loading')) : null),
+          diag
+            ? h('div', { key: 'list', className: 'dshwl-checks' }, diag.checks.map((item) => h('div', {
+              key: item.id,
+              className: 'dshwl-check',
+            }, [
+              h('span', {
+                key: 'mark',
+                className: `dshwl-check-mark ${item.ok ? 'ok' : item.optional ? 'warn' : 'fail'}`,
+              }, item.ok ? '✓' : item.optional ? '!' : '✗'),
+              h('span', { key: 'label', className: 'dshwl-check-label' }, item.label),
+              h('span', { key: 'detail', className: 'dshwl-check-detail' }, item.detail),
+              !item.ok && item.hint ? h('span', { key: 'hint', className: 'dshwl-check-hint' }, item.hint) : null,
+            ])))
+            : null,
+        ]);
       } else if (tab === 'candidates') {
         body = h('div', {}, [
           h('p', { key: 'note', className: 'dshwl-hint' }, t('candNote')),
@@ -517,6 +598,15 @@ window.__ModuleLoader__.load({
 .dshwl-toolbar{display:flex;align-items:center;gap:10px;flex-wrap:wrap;margin-bottom:8px}
 .dshwl-muted{color:var(--dsw-alias-label-secondary,#6b7280);font-size:11px;margin:4px 0}
 .dshwl-error{border:1px solid var(--dsw-alias-state-error-primary,#d33);color:var(--dsw-alias-state-error-primary,#d33);border-radius:8px;padding:7px 10px;margin:10px 0;font-size:12px;word-break:break-word}
+.dshwl-checks{display:flex;flex-direction:column;gap:6px;margin-top:12px}
+.dshwl-check{display:grid;grid-template-columns:24px 120px 1fr;gap:8px;align-items:baseline;padding:7px 10px;border:1px solid var(--dsw-alias-border-l1,#e5e7eb);border-radius:9px;background:var(--dsw-alias-bg-layer-1,#fff);font-size:12px}
+.dshwl-check-mark{font-weight:700;text-align:center}
+.dshwl-check-mark.ok{color:var(--dsw-alias-state-success-primary,#15803d)}
+.dshwl-check-mark.warn{color:var(--dsw-alias-state-warn-primary,#b45309)}
+.dshwl-check-mark.fail{color:var(--dsw-alias-state-error-primary,#d33)}
+.dshwl-check-label{font-weight:600}
+.dshwl-check-detail{color:var(--dsw-alias-label-secondary,#6b7280);word-break:break-word}
+.dshwl-check-hint{grid-column:2 / 4;color:var(--dsw-alias-state-warn-primary,#b45309);font-size:11px}
 .dshwl-foot{margin:22px 0 0;padding-top:10px;border-top:1px solid var(--dsw-alias-border-l1,#e5e7eb);color:var(--dsw-alias-label-secondary,#6b7280);font-size:11px;line-height:1.6}
 .dshwl-notice{position:sticky;bottom:0;margin-top:12px;border:1px solid var(--dsw-alias-border-l2,#d1d5db);background:var(--dsw-alias-bg-overlay,#fff);border-radius:8px;padding:7px 10px;font-size:12px;color:var(--dsw-alias-label-primary,#1f2329);box-shadow:0 2px 10px rgba(0,0,0,.06);word-break:break-word}
 `;

package/cordis.patch.yml

@@ -1,12 +1,11 @@
 # dsh-whale-live bundle patch.
 #
-# One Host row: live sessions, the two persona documents (consciousness / diary),
-# Bilibili danmaku, edge-tts speech and the memory-candidate inbox. The Client
-# half adds the left-sidebar entry and the panel.
+# One Host row: live sessions, the persona documents, Bilibili danmaku,
+# edge-tts speech, the memory inbox, and the pre-live "set up the gear" helper.
 #
-# Defaults below are placeholders. Fill `roomId`, `credentialFile` and
-# `pythonPath` before going live. An empty `dataDir` uses
-# `~/.dsh/whale-live`; `vtubeDir` is optional (VTube Studio mouth sync).
+# Defaults are placeholders. Fill `roomId`, `credentialFile`, `pythonPath`
+# before going live. Empty paths disable that integration (VTS / OBS / 直播姬).
+# Compatibility: Windows only, DSH >=0.2.1-rc.2 <0.4.0 (tested 0.2.2-rc.1).
 - insert:
     - id: whale-live
       name: 'dsh-whale-live'
@@ -17,7 +16,12 @@
         credentialFile: ''
         pythonPath: ''
         vtubeDir: ''
+        obsPath: ''
+        livehimePath: ''
+        vtsPath: ''
+        stageWaitSec: 90
+        openRoomPage: true
         voice: zh-CN-XiaoyiNeural
         rate: '+8%'
         pitch: '+4Hz'
-        listenWaitSec: 45
+        listenWaitSec: 45

package/index.js

@@ -15,6 +15,9 @@ import { createStore } from './lib/store.js';
 import { createDanmaku } from './lib/bili.js';
 import { createVoice } from './lib/voice.js';
 import { createAvatar } from './lib/avatar.js';
+import { createVts } from './lib/vts.js';
+import { createStage } from './lib/stage.js';
+import { diagnose } from './lib/diagnostics.js';
 import { createTools } from './lib/tools.js';
 import { registerHttp } from './lib/http.js';
 
@@ -31,6 +34,11 @@ export async function apply(ctx, config = {}) {
     vtubeDir: '',
     vtsPort: 8001,
     vtsSteamApp: '1325860',
+    obsPath: '',
+    livehimePath: '',
+    vtsPath: '',
+    stageWaitSec: 90,
+    openRoomPage: true,
     voice: 'zh-CN-XiaoyiNeural',
     rate: '+8%',
     pitch: '+4Hz',
@@ -46,14 +54,16 @@ export async function apply(ctx, config = {}) {
   store.ensure();
   const danmaku = createDanmaku(settings, ctx.logger);
   const avatar = createAvatar(settings, ctx.logger);
+  const vts = createVts(settings, ctx.logger);
+  const stage = createStage(settings, avatar, ctx.logger);
   const voice = createVoice(settings, store, ctx.logger, avatar);
-  const tools = createTools({ ctx, store, danmaku, voice, avatar, config: settings });
+  const tools = createTools({ ctx, store, danmaku, voice, avatar, vts, stage, diagnose, config: settings });
 
   ctx.effect(() => {
     const disposers = [];
     try {
       for (const tool of tools) disposers.push(ctx.tools.register(tool));
-      const disposeHttp = registerHttp(ctx, { store, danmaku, voice, avatar, config: settings, logger: ctx.logger });
+      const disposeHttp = registerHttp(ctx, { store, danmaku, voice, avatar, stage, diagnose, config: settings, logger: ctx.logger });
       if (disposeHttp) disposers.push(disposeHttp);
       disposers.push(() => voice.dispose());
     } catch (error) {

package/lib/diagnostics.js

@@ -0,0 +1,98 @@
+/**
+ * 装好之后的自检：不装任何东西，只如实报告「少了什么、去哪补」。
+ * 软件（OBS / VTube Studio / 直播姬）需要人自己装；Python 依赖给 pip 提示。
+ */
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+function run(file, args, timeoutMs = 12000) {
+  return new Promise((resolve) => {
+    execFile(file, args, { timeout: timeoutMs, windowsHide: true }, (error, stdout, stderr) => {
+      resolve({ ok: !error, out: String(stdout ?? '').trim(), err: String(stderr ?? '').trim(), error: error ? error.message : null });
+    });
+  });
+}
+
+function check(id, label, ok, detail, hint = '', optional = false) {
+  return { id, label, ok: Boolean(ok), detail: String(detail ?? ''), hint: String(hint ?? ''), optional };
+}
+
+export async function diagnose({ store, danmaku, avatar, stage, config }) {
+  const checks = [];
+
+  try {
+    fs.accessSync(store.paths.dataDir, fs.constants.W_OK);
+    checks.push(check('data', '数据目录', true, store.paths.dataDir));
+  } catch (error) {
+    checks.push(check('data', '数据目录', false, String(error?.message ?? error), '把 dataDir 改到可写目录'));
+  }
+
+  for (const [id, label, file] of [
+    ['consciousness', '意识卡', store.paths.docs.consciousness],
+    ['diary', '观察日记', store.paths.docs.diary],
+  ]) {
+    try {
+      const size = Math.round(fs.statSync(file).size / 1024);
+      checks.push(check(id, label, true, `${size} KB`));
+    } catch {
+      checks.push(check(id, label, false, '文件不存在', '插件启动时会自动种一份'));
+    }
+  }
+
+  const pythonPath = String(config.pythonPath || '');
+  if (!pythonPath) {
+    checks.push(check('python', 'Python / edge-tts', false, '没配 pythonPath', '填一个装了 edge-tts 的 python.exe', true));
+  } else if (!fs.existsSync(pythonPath)) {
+    checks.push(check('python', 'Python / edge-tts', false, `找不到 ${pythonPath}`, '检查路径'));
+  } else {
+    const r = await run(pythonPath, ['-c', 'import edge_tts; print(getattr(edge_tts, "__version__", "ok"))']);
+    checks.push(check('python', 'Python / edge-tts', r.ok, r.ok ? `edge-tts ${r.out}` : (r.err || r.error || '导入失败'), r.ok ? '' : 'pip install edge-tts'));
+  }
+
+  const credentialFile = String(config.credentialFile || '');
+  if (!credentialFile) {
+    checks.push(check('cred', 'B站凭据', false, '没配 credentialFile', '导出 cookie JSON 后填路径', true));
+  } else if (!fs.existsSync(credentialFile)) {
+    checks.push(check('cred', 'B站凭据', false, `找不到 ${credentialFile}`, '检查路径'));
+  } else {
+    try {
+      const data = JSON.parse(fs.readFileSync(credentialFile, 'utf8'));
+      const missing = ['sessdata', 'bili_jct', 'buvid3', 'dedeuserid'].filter((key) => !data[key]);
+      checks.push(check('cred', 'B站凭据', missing.length === 0, missing.length ? `缺 ${missing.join(',')}` : '字段齐全'));
+    } catch {
+      checks.push(check('cred', 'B站凭据', false, 'JSON 解析失败', '重新导出 cookie'));
+    }
+  }
+
+  const room = await danmaku.roomInfo();
+  if (room?.roomId) {
+    checks.push(check('room', '直播间', true, `${room.title || '(无标题)'} · ${room.liveStatus ? '直播中' : '未开播'} · 在线 ${room.online ?? '?'}`));
+  } else {
+    checks.push(check('room', '直播间', false, '房号没配或接口不可达', '检查 roomId / 网络', true));
+  }
+
+  const skin = await avatar.status();
+  checks.push(check('vts', 'VTube Studio', skin.up, skin.up ? `8001 端口可用` : '还没开', '面板点「架好设备」会拉起', true));
+
+  const vtubeDir = String(config.vtubeDir || '');
+  if (!vtubeDir) {
+    checks.push(check('bridge', 'VTS 嘴型驱动', false, '没配 vtubeDir', '可选：有驱动目录才能动嘴', true));
+  } else {
+    const missing = ['vts_speak.py', 'vts_client.py'].filter((file) => !fs.existsSync(path.join(vtubeDir, file)));
+    checks.push(check('bridge', 'VTS 嘴型驱动', missing.length === 0, missing.length ? `缺 ${missing.join(',')}` : '就绪', '', true));
+  }
+
+  const apps = await stage.appStatus();
+  checks.push(check('obs', 'OBS', apps.obs.running || (apps.obs.configured && apps.obs.exists),
+    apps.obs.running ? '运行中' : apps.obs.configured ? (apps.obs.exists ? '没运行（架设备时会拉起）' : '路径不存在') : '没配 obsPath',
+    '可选；填 obs64.exe 路径', true));
+  checks.push(check('livehime', '直播姬', apps.livehime.running || (apps.livehime.configured && apps.livehime.exists),
+    apps.livehime.running ? '运行中' : apps.livehime.configured ? (apps.livehime.exists ? '没运行（架设备时会拉起）' : '路径不存在') : '没配 livehimePath',
+    '可选；填 livehime.exe 路径', true));
+
+  const ok = checks.filter((item) => item.ok).length;
+  const failed = checks.filter((item) => !item.ok && !item.optional).length;
+  const warned = checks.filter((item) => !item.ok && item.optional).length;
+  return { checks, summary: { total: checks.length, ok, failed, warned } };
+}

package/lib/http.js

@@ -83,7 +83,7 @@ function sendJson(response, status, value) {
   response.end(JSON.stringify(value));
 }
 
-export function registerHttp(ctx, { store, danmaku, voice, avatar, config, logger }) {
+export function registerHttp(ctx, { store, danmaku, voice, avatar, stage, diagnose, config, logger }) {
   async function snapshot() {
     const state = store.state();
     const skin = await avatar.status();
@@ -147,6 +147,12 @@ export function registerHttp(ctx, { store, danmaku, voice, avatar, config, logge
       }
       return { avatar: await avatar.status() };
     }
+    if (action === 'stage') {
+      return { stage: await stage.stage() };
+    }
+    if (action === 'diagnose') {
+      return { diagnose: await diagnose({ store, danmaku, avatar, stage, config }) };
+    }
     if (action === 'note') {
       const text = String(body.text ?? '').trim();
       if (!text) throw Object.assign(new Error('没有要记的内容'), { code: 'INVALID_INPUT' });
@@ -212,6 +218,10 @@ export function registerHttp(ctx, { store, danmaku, voice, avatar, config, logge
             sendJson(response, 200, { ok: true, data: info });
             return;
           }
+          if (route === '/diagnose') {
+            sendJson(response, 200, { ok: true, data: await diagnose({ store, danmaku, avatar, stage, config }) });
+            return;
+          }
           sendJson(response, 404, { ok: false, error: 'not found' });
           return;
         }

package/lib/stage.js

@@ -0,0 +1,123 @@
+/**
+ * 开播前的「架设备」：Steam / VTube Studio / OBS / 直播姬 / 直播间页面。
+ * 只负责“准备好”，不开始推流；已经在跑的不会重复拉。
+ */
+import { execFile, spawn } from 'node:child_process';
+import fs from 'node:fs';
+
+function run(file, args, timeoutMs = 12000) {
+  return new Promise((resolve) => {
+    execFile(file, args, { timeout: timeoutMs, windowsHide: true }, (error, stdout, stderr) => {
+      resolve({ ok: !error, out: String(stdout ?? ''), err: String(stderr ?? ''), error: error ? error.message : null });
+    });
+  });
+}
+
+function tasklistHas(imageName) {
+  return run('tasklist', ['/FI', `IMAGENAME eq ${imageName}`, '/NH']).then((result) => {
+    if (!result.ok) return false;
+    return result.out.toLowerCase().includes(imageName.toLowerCase());
+  });
+}
+
+export function createStage(config = {}, avatar, logger = null) {
+  const obsPath = String(config.obsPath || '');
+  const livehimePath = String(config.livehimePath || '');
+  const vtsPath = String(config.vtsPath || '');
+  const stageWaitSec = Math.max(20, Math.min(180, Number(config.stageWaitSec) || 90));
+  const roomId = Number(config.roomId) || 0;
+  const roomUrl = String(config.roomUrl || (roomId ? `https://live.bilibili.com/${roomId}` : ''));
+  const openRoomPage = config.openRoomPage !== false;
+
+  async function appStatus() {
+    const [skin, obs, livehime, steam] = await Promise.all([
+      avatar.status(),
+      tasklistHas('obs64.exe'),
+      tasklistHas('livehime.exe'),
+      tasklistHas('steam.exe'),
+    ]);
+    return {
+      steam: { running: steam },
+      vts: { running: skin.up },
+      obs: { configured: Boolean(obsPath), exists: Boolean(obsPath) && fs.existsSync(obsPath), running: obs, path: obsPath },
+      livehime: {
+        configured: Boolean(livehimePath),
+        exists: Boolean(livehimePath) && fs.existsSync(livehimePath),
+        running: livehime,
+        path: livehimePath,
+      },
+    };
+  }
+
+  function launch(file, args, label) {
+    try {
+      const child = spawn(file, args, { detached: true, stdio: 'ignore', windowsHide: true });
+      child.unref();
+      logger?.info?.(`whale-live: 已启动 ${label || file}`);
+      return { ok: true };
+    } catch (error) {
+      return { ok: false, error: error?.message ?? String(error) };
+    }
+  }
+
+  /** 架镜头：四件软件 + 直播间页面，全部只“准备好”。 */
+  async function stage() {
+    const steps = [];
+    const apps = await appStatus();
+
+    steps.push({
+      id: 'steam',
+      ok: apps.steam.running,
+      optional: true,
+      text: apps.steam.running ? 'Steam 已在运行' : 'Steam 没开（VTS 要靠它拉起）',
+    });
+
+    if (apps.vts.running) {
+      steps.push({ id: 'vts', ok: true, text: 'VTube Studio 已在运行' });
+    } else if (vtsPath && fs.existsSync(vtsPath)) {
+      const started = launch(vtsPath, [], 'VTube Studio');
+      steps.push({ id: 'vts', ok: started.ok, text: started.ok ? 'VTube Studio 已直接拉起（等它开 API）' : `VTS 启动失败：${started.error}` });
+    } else {
+      const opened = avatar.open();
+      steps.push({
+        id: 'vts',
+        ok: opened.launched === true,
+        text: opened.launched ? '已请 Steam 拉起 VTube Studio（冷启动会慢）' : `VTS 拉不起来：${opened.error || '未知'}`,
+      });
+    }
+
+    if (!apps.obs.configured) {
+      steps.push({ id: 'obs', ok: false, optional: true, text: '没配 obsPath，跳过 OBS' });
+    } else if (!apps.obs.exists) {
+      steps.push({ id: 'obs', ok: false, text: `OBS 路径不存在：${obsPath}` });
+    } else if (apps.obs.running) {
+      steps.push({ id: 'obs', ok: true, text: 'OBS 已在运行（没推流）' });
+    } else {
+      const started = launch(obsPath, [], 'OBS');
+      steps.push({ id: 'obs', ok: started.ok, text: started.ok ? 'OBS 已拉起（没推流）' : `OBS 启动失败：${started.error}` });
+    }
+
+    if (!apps.livehime.configured) {
+      steps.push({ id: 'livehime', ok: false, optional: true, text: '没配 livehimePath，跳过直播姬' });
+    } else if (!apps.livehime.exists) {
+      steps.push({ id: 'livehime', ok: false, text: `直播姬路径不存在：${livehimePath}` });
+    } else if (apps.livehime.running) {
+      steps.push({ id: 'livehime', ok: true, text: '直播姬已在运行' });
+    } else {
+      const started = launch(livehimePath, [], '直播姬');
+      steps.push({ id: 'livehime', ok: started.ok, text: started.ok ? '直播姬已拉起' : `直播姬启动失败：${started.error}` });
+    }
+
+    if (openRoomPage && roomUrl) {
+      const page = launch('cmd.exe', ['/c', 'start', '', roomUrl], '直播间页面');
+      steps.push({ id: 'room', ok: page.ok, text: page.ok ? `已打开直播间页面：${roomUrl}` : `打开页面失败：${page.error}` });
+    } else {
+      steps.push({ id: 'room', ok: false, optional: true, text: '没开直播间页面（房号为空或 openRoomPage=false）' });
+    }
+
+    const ready = await avatar.wait(stageWaitSec);
+    return { steps, avatar: ready, apps };
+  }
+
+  return { stage, appStatus, roomUrl };
+}

package/lib/tools.js

@@ -31,7 +31,7 @@ function timeOf(iso) {
   }
 }
 
-export function createTools({ ctx, store, danmaku, voice, avatar, config }) {
+export function createTools({ ctx, store, danmaku, voice, avatar, vts, stage, diagnose, config }) {
   const roomName = config.roomName || '直播间';
   const roomId = config.roomId;
 
@@ -72,6 +72,8 @@ export function createTools({ ctx, store, danmaku, voice, avatar, config }) {
 - close：下播，给你本场摘要，让你自己挑 1-3 件最想留下的。
 - propose / memory_list / commit / reject：入忆候选的流转。propose 只是排队，不是写记忆；真正写记忆要你自己调用 cortex_write。
 - avatar：皮套（VTube Studio）——status 看开没开，open 让 Steam 拉起来，wait 等它的 8001 就绪。
+- stage：架设备——拉起 VTS / OBS / 直播间页面，但不开始推流，方便开播前调试。
+- diagnose：自检——数据目录、两本戏本、Python/edge-tts、B站凭据、直播间、VTS、嘴型驱动、OBS 逐项报告。
 - read / status：翻文件、看状态。
 
 那条线要记住：直播里说的话、聊的人，只活在 dataDir 的两个文件里；cortex 只收你下播后亲手挑过、写过的几件事。`,
@@ -82,7 +84,7 @@ export function createTools({ ctx, store, danmaku, voice, avatar, config }) {
       properties: {
         action: {
           type: 'string',
-          enum: ['open', 'status', 'read', 'note', 'listen', 'close', 'propose', 'memory_list', 'commit', 'reject', 'avatar'],
+          enum: ['open', 'status', 'read', 'note', 'listen', 'close', 'propose', 'memory_list', 'commit', 'reject', 'avatar', 'vts', 'stage', 'diagnose'],
           description: '要做什么。',
         },
         kind: {
@@ -141,6 +143,22 @@ export function createTools({ ctx, store, danmaku, voice, avatar, config }) {
           enum: ['status', 'open', 'wait'],
           description: 'avatar：看状态 / 让 Steam 拉起 VTS / 等 8001 就绪。',
         },
+        hotkey: {
+          type: 'string',
+          description: 'vts：触发的热键名（例如 脸红、爱心眼、流泪、＞＜、前倾、尾巴开关）。',
+        },
+        expression: {
+          type: 'string',
+          description: 'vts：要开关的表情文件名（例如 脸红、黑脸）。',
+        },
+        expressionOn: {
+          type: 'boolean',
+          description: 'vts：表情开（默认）还是关。',
+        },
+        mouth: {
+          type: 'number',
+          description: 'vts：直接把 MouthOpen 设成 0~1（调试用）。',
+        },
       },
     },
     output: TEXT_OUTPUT,
@@ -303,6 +321,55 @@ export function createTools({ ctx, store, danmaku, voice, avatar, config }) {
         }
       }
 
+      if (action === 'vts') {
+        try {
+          if (args.hotkey) {
+            const result = await vts.hotkey(args.hotkey);
+            return { text: result.ok ? `热键已触发：${args.hotkey}` : `热键没触发：${result.error || result.err || '未知'}` };
+          }
+          if (args.expression) {
+            const on = args.expressionOn !== false;
+            const result = await vts.expression(args.expression, on);
+            return { text: result.ok ? `表情 ${args.expression} 已${on ? '开' : '关'}` : `表情失败：${result.error || result.err || '未知'}` };
+          }
+          if (args.mouth !== undefined && args.mouth !== null) {
+            const result = await vts.mouth(args.mouth);
+            return { text: result.ok ? `嘴型已设为 ${Number(args.mouth) || 0}` : `嘴型失败：${result.error || result.err || '未知'}` };
+          }
+          return { text: '要给 hotkey / expression / mouth 其中一个。' };
+        } catch (error) {
+          return { text: `VTS 操作出错：${error instanceof Error ? error.message : String(error)}` };
+        }
+      }
+
+      if (action === 'stage') {
+        const result = await stage.stage();
+        const lines = result.steps.map((step) => `${step.ok ? '✓' : step.optional ? '·' : '✗'} ${step.text}`);
+        return {
+          text: [
+            '架设备完成（不会开始推流，OBS 里还要你自己点「开始推流」）：',
+            ...lines,
+            '',
+            `VTS：${result.avatar?.up ? '就绪' : '还没就绪（可能要等几十秒）'}；OBS：${result.apps?.obs?.running ? '在运行' : '未运行'}；直播姬：${result.apps?.livehime?.running ? '在运行' : '未运行'}`,
+          ].join('\n'),
+        };
+      }
+
+      if (action === 'diagnose') {
+        const result = await diagnose({ store, danmaku, avatar, stage, config });
+        const lines = result.checks.map((item) => {
+          const mark = item.ok ? '✓' : item.optional ? '!' : '✗';
+          const hint = item.ok || !item.hint ? '' : `（${item.hint}）`;
+          return `${mark} ${item.label}：${item.detail}${hint}`;
+        });
+        return {
+          text: [
+            `自检：${result.summary.ok}/${result.summary.total} 通过 · ${result.summary.failed} 项必须修 · ${result.summary.warned} 项可选`,
+            ...lines,
+          ].join('\n'),
+        };
+      }
+
       return { text: `不认识的动作：${String(action)}` };
     },
   };
@@ -347,7 +414,10 @@ export function createTools({ ctx, store, danmaku, voice, avatar, config }) {
       if (!result.ok) return { text: `没念出来：${result.error}` };
       if (session) store.appendEvent({ kind: 'say', text });
       const seconds = Math.round((result.ms ?? 0) / 100) / 10;
-      return { text: `${result.interrupted ? '（上一句被掐断）' : ''}念了 ${seconds} 秒${result.avatar ? '（皮套跟着动了嘴）' : ''}：${text}${session ? `\n（已记进本场，第 ${store.state().session?.says ?? '?'} 句）` : ''}` };
+      const mouth = result.avatar
+        ? '（皮套跟着动了嘴）'
+        : `（嘴型没连上${result.vtsError ? `：${result.vtsError.replace(/\s+/g, ' ').slice(0, 160)}` : ''}）`;
+      return { text: `${result.interrupted ? '（上一句被掐断）' : ''}念了 ${seconds} 秒${mouth}：${text}${session ? `\n（已记进本场，第 ${store.state().session?.says ?? '?'} 句）` : ''}` };
     },
   };
 

package/lib/voice.js

@@ -79,15 +79,8 @@ export function createVoice(config = {}, store = null, logger = null, avatar = n
       return { ok: false, busy: true, error: '上一句还在说（要打断请带 interrupt）' };
     }
 
-    let useVts = false;
-    if (vtubeDir) {
-      try {
-        const status = avatar ? await avatar.status() : { up: false };
-        useVts = status.up === true;
-      } catch {
-        useVts = false;
-      }
-    }
+    // 不靠端口探测决定：只要配了 vtubeDir 就带上，say.py 自己连不上会安静回退。
+    const useVts = Boolean(vtubeDir) && fs.existsSync(path.join(vtubeDir, 'vts_speak.py'));
 
     cleanup();
     fs.mkdirSync(audioDir, { recursive: true });
@@ -164,6 +157,7 @@ export function createVoice(config = {}, store = null, logger = null, avatar = n
             ms: payload.ms ?? Date.now() - started,
             interrupted: payload.interrupted === true,
             avatar: payload.avatar === true,
+            vtsError: payload.avatar === true ? '' : stderr.trim().slice(-240),
             text,
           });
           return;

package/lib/vts.js

@@ -0,0 +1,65 @@
+/**
+ * VTube Studio 的“手”：热键、表情、嘴型。
+ * 走 vtube-bridge 里现成的 vts_client.py，不重复造轮子。
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function createVts(config = {}, logger = null) {
+  const dir = String(config.vtubeDir || '');
+  const pythonPath = String(config.pythonPath || '');
+
+  function runCli(args, timeoutMs = 10000) {
+    return new Promise((resolve) => {
+      const script = dir ? path.join(dir, 'vts_client.py') : '';
+      if (!dir || !pythonPath || !fs.existsSync(script)) {
+        resolve({ ok: false, error: '没配 vtubeDir / pythonPath，或找不到 vts_client.py' });
+        return;
+      }
+      const child = spawn(pythonPath, [script, ...args], {
+        cwd: dir,
+        windowsHide: true,
+        env: { ...process.env, PYTHONIOENCODING: 'utf-8', PYTHONUTF8: '1' },
+      });
+      let out = '';
+      let err = '';
+      child.stdout?.setEncoding('utf8');
+      child.stderr?.setEncoding('utf8');
+      child.stdout?.on('data', (chunk) => { out += chunk; });
+      child.stderr?.on('data', (chunk) => { err += chunk; });
+      const killer = setTimeout(() => {
+        try {
+          child.kill();
+        } catch {
+          /* 已退出 */
+        }
+      }, timeoutMs);
+      child.on('error', (error) => {
+        clearTimeout(killer);
+        resolve({ ok: false, error: error.message });
+      });
+      child.on('close', (code) => {
+        clearTimeout(killer);
+        resolve({ ok: code === 0, out: out.trim().slice(-600), err: err.trim().slice(-300) });
+      });
+    });
+  }
+
+  return {
+    async hotkey(name) {
+      const result = await runCli(['hotkey', String(name ?? '')]);
+      logger?.info?.(`whale-live: VTS hotkey ${name} ok=${result.ok}`);
+      return { ...result, action: `hotkey:${name}` };
+    },
+    async expression(name, on = true) {
+      const result = await runCli(['expr', String(name ?? ''), on ? 'on' : 'off']);
+      logger?.info?.(`whale-live: VTS expr ${name} ${on ? 'on' : 'off'} ok=${result.ok}`);
+      return { ...result, action: `expr:${name}:${on ? 'on' : 'off'}` };
+    },
+    async mouth(value) {
+      const result = await runCli(['mouth', String(Number(value) || 0)]);
+      return { ...result, action: `mouth:${Number(value) || 0}` };
+    },
+  };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name":  "dsh-whale-live",
-    "version":  "0.1.1",
-    "description":  "A left-sidebar live console for DeepSeek Harness: persona script, per-stream log, Bilibili danmaku, edge-tts speech and a hand-picked memory inbox. Windows only.",
+    "version":  "0.2.1",
+    "description":  "Left-sidebar live console for DeepSeek Harness: persona script, stream log, Bilibili danmaku, edge-tts speech, optional VTube Studio/OBS/直播姬 launch helpers and a memory inbox. Windows only.",
     "type":  "module",
     "main":  "./index.js",
     "icon":  "./icon.svg",
@@ -21,7 +21,8 @@
                   "locale/*.json",
                   "icon.svg",
                   "README.md",
-                  "LICENSE"
+                  "LICENSE",
+                  "CHANGELOG.md"
               ],
     "dsh":  {
                 "manifestVersion":  1,

package/runtime/say.py

@@ -195,11 +195,24 @@ def main():
 
     mouth = None
     if args.vts_dir:
+        # miniaudio 在 Windows 上打不开含中文的路径（error -7），
+        # 解码前先复制到英文临时文件，播放也用这份。
+        import shutil
+        import tempfile
+
+        ascii_path = os.path.join(tempfile.gettempdir(), "dsh-whale-say-%d.mp3" % os.getpid())
+        try:
+            shutil.copyfile(path, ascii_path)
+            probe_path = ascii_path
+        except Exception:
+            probe_path = path
         mouth = Mouth(args.vts_dir)
         if mouth.vts is not None:
-            if not mouth.load(path):
+            if not mouth.load(probe_path):
                 print("[vts] 包络算不出来，只出声：%s" % mouth.error, file=sys.stderr)
                 mouth = None
+            else:
+                path = probe_path
         else:
             print("[vts] 皮套没连上，只出声：%s" % mouth.error, file=sys.stderr)
             mouth = None