dsh-whale-live 0.1.0 → 0.2.0

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,8 @@ 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 { 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 +33,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 +53,15 @@ export async function apply(ctx, config = {}) {
   store.ensure();
   const danmaku = createDanmaku(settings, ctx.logger);
   const avatar = createAvatar(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, 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/store.js

@@ -23,7 +23,7 @@ const DOC_FILES = {
 const CONSCIOUSNESS_SEED = `# 意识
 
 > 这是我自己的经历。不是聊天记录，是我记得、会影响我的那些事。
-> 每场直播结束，我会挑几件最核心的写进来。主人也可以改。
+> 每场直播结束，我会挑几件最核心的写进来。你也可以改。
 
 ## 我是谁
 

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, 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', 'stage', 'diagnose'],
           description: '要做什么。',
         },
         kind: {
@@ -303,6 +305,34 @@ export function createTools({ ctx, store, danmaku, voice, avatar, config }) {
         }
       }
 
+      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)}` };
     },
   };

package/package.json

@@ -1,76 +1,78 @@
-{
-  "name": "dsh-whale-live",
-  "version": "0.1.0",
-  "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.",
-  "type": "module",
-  "main": "./index.js",
-  "icon": "./icon.svg",
-  "exports": {
-    ".": "./index.js",
-    "./client": "./client.js",
-    "./package.json": "./package.json",
-    "./locale/*.json": "./locale/*.json",
-    "./icon": "./icon.svg"
-  },
-  "files": [
-    "index.js",
-    "client.js",
-    "lib",
-    "runtime",
-    "cordis.patch.yml",
-    "locale/*.json",
-    "icon.svg",
-    "README.md",
-    "LICENSE"
-  ],
-  "dsh": {
-    "manifestVersion": 1,
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    },
-    "client": {
-      "platform": "web",
-      "immediately": true,
-      "inject": []
-    },
-    "compatibility": {
-      "dsh": ">=0.2.1-rc.2 <0.4.0",
-      "node": ">=20",
-      "profiles": [
-        "desktop",
-        "web"
-      ]
-    }
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "os": [
-    "win32"
-  ],
-  "scripts": {
-    "check": "node --check index.js && node --check client.js",
-    "test": "node --test test/store.test.mjs && node test/apply.test.mjs"
-  },
-  "keywords": [
-    "dsh",
-    "dsh-plugin",
-    "deepseek-harness",
-    "cordis-plugin",
-    "bilibili",
-    "live",
-    "persona",
-    "edge-tts",
-    "vtuber"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Lh1314-China/dsh-whale-live.git"
-  },
-  "homepage": "https://github.com/Lh1314-China/dsh-whale-live#readme",
-  "bugs": {
-    "url": "https://github.com/Lh1314-China/dsh-whale-live/issues"
-  },
-  "author": "Lh1314-China",
-  "license": "MIT"
-}
+{
+    "name":  "dsh-whale-live",
+    "version":  "0.2.0",
+    "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",
+    "exports":  {
+                    ".":  "./index.js",
+                    "./client":  "./client.js",
+                    "./package.json":  "./package.json",
+                    "./locale/*.json":  "./locale/*.json",
+                    "./icon":  "./icon.svg"
+                },
+    "files":  [
+                  "index.js",
+                  "client.js",
+                  "lib",
+                  "runtime",
+                  "cordis.patch.yml",
+                  "locale/*.json",
+                  "icon.svg",
+                  "README.md",
+                  "LICENSE"
+              ],
+    "dsh":  {
+                "manifestVersion":  1,
+                "bundle":  {
+                               "patch":  "./cordis.patch.yml"
+                           },
+                "client":  {
+                               "platform":  "web",
+                               "immediately":  true,
+                               "inject":  [
+
+                                          ]
+                           },
+                "compatibility":  {
+                                      "dsh":  "\u003e=0.2.1-rc.2 \u003c0.4.0",
+                                      "node":  "\u003e=20",
+                                      "profiles":  [
+                                                       "desktop",
+                                                       "web"
+                                                   ]
+                                  }
+            },
+    "engines":  {
+                    "node":  "\u003e=20"
+                },
+    "os":  [
+               "win32"
+           ],
+    "scripts":  {
+                    "check":  "node --check index.js \u0026\u0026 node --check client.js",
+                    "test":  "node --test test/store.test.mjs \u0026\u0026 node test/apply.test.mjs"
+                },
+    "keywords":  [
+                     "dsh",
+                     "dsh-plugin",
+                     "deepseek-harness",
+                     "cordis-plugin",
+                     "bilibili",
+                     "live",
+                     "persona",
+                     "edge-tts",
+                     "vtuber"
+                 ],
+    "repository":  {
+                       "type":  "git",
+                       "url":  "git+https://github.com/Lh1314-China/dsh-whale-live.git"
+                   },
+    "homepage":  "https://github.com/Lh1314-China/dsh-whale-live#readme",
+    "bugs":  {
+                 "url":  "https://github.com/Lh1314-China/dsh-whale-live/issues"
+             },
+    "author":  "Lh1314-China",
+    "license":  "MIT"
+}