cotutor 0.4.0 → 0.4.2

package/dist/app/machine/update.js

@@ -0,0 +1,109 @@
+/**
+ * 有没有新版本:服务每天问一次 npm 的 latest,结果存机器级 ~/.config/cotutor/update.json(几个孩子的服务共用,一天只问一次,重起不重问)。
+ * /api/health 带上 latest(比在跑的新才有),托盘、家长端、service status 都从它拿;doctor 只读这份文件,不上网。
+ * 更新说明写在 package.json 的 releaseNotes,跟着 npm 一起下来(npm、npmmirror 都留自定义字段,2026-11-07 查过),国内连不上 GitHub 也看得到。
+ * 只发一个普通的 GET,不带孩子或使用的任何信息;问不到(断网、被墙)不报错,下个小时再问。先问 npm,不通再问 npmmirror(中国家庭常连不上 npm)。
+ * latest 这个标签要等 npm 扫描通过才变(2026-07 起发布后先扫描),不会提前提醒。
+ * 不自动升级:升级要重起服务,孩子可能正在上课;老师文件的更新也要家长知道。
+ * 不想让它问:update.json 写 {"off": true}。从仓库跑的(BUILD.commit 有值)不问,见 main.ts。
+ */
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { isPlainVersion } from "../../shared/upgrade.js";
+export const UPDATE_URLS = ['https://registry.npmjs.org/cotutor/latest', 'https://registry.npmmirror.com/cotutor/latest'];
+const DAY_MS = 24 * 3600_000;
+const HOUR_MS = 3600_000;
+const FIRST_MS = 60_000;
+const TIMEOUT_MS = 8000;
+export const updateFile = () => join(homedir(), '.config', 'cotutor', 'update.json');
+/** 网上来的,要显示给家长:只留几行短的纯文本 */
+export function cleanNotes(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((x) => typeof x === 'string').map((x) => x.replace(/[\u0000-\u001f\u007f]+/g, ' ').trim()).filter((x) => x && x.length <= 140).slice(0, 8);
+}
+/** 读不到、写坏了 → 空的,当作没问过 */
+export async function readUpdateRecord(file = updateFile()) {
+    try {
+        const j = JSON.parse(await readFile(file, 'utf8'));
+        return {
+            ...(typeof j.checkedAt === 'string' ? { checkedAt: j.checkedAt } : {}),
+            ...(isPlainVersion(j.latest) ? { latest: j.latest, notes: cleanNotes(j.notes) } : {}),
+            ...(j.off === true ? { off: true } : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+/** engines.node 里的下限;只认 >=22.18 这种,看不懂的不拦 */
+function minNodeOf(raw) {
+    const m = /^\s*>=\s*(\d+)(?:\.(\d+))?/.exec(typeof raw === 'string' ? raw : '');
+    return m ? [Number(m[1]), Number(m[2] ?? 0)] : null;
+}
+/** 依次问,谁先答谁算;都问不到 → null */
+export async function fetchRelease(fetchFn = fetch, urls = UPDATE_URLS) {
+    for (const [i, url] of urls.entries()) {
+        try {
+            const r = await fetchFn(url, { signal: AbortSignal.timeout(TIMEOUT_MS), headers: { accept: 'application/json' } });
+            if (!r.ok)
+                continue;
+            const j = (await r.json());
+            if (isPlainVersion(j.version))
+                return { version: j.version, notes: cleanNotes(j.releaseNotes), minNode: minNodeOf(j.engines?.node), mirror: i > 0 };
+        }
+        catch {
+            /* 这家不通,问下一家 */
+        }
+    }
+    return null;
+}
+let known = null;
+let knownNoteLines = [];
+/** 这个进程现在知道的最新版本;还不知道、关掉了 → null */
+export const knownLatest = () => known;
+/** 那个版本的更新说明 */
+export const knownNotes = () => knownNoteLines;
+const remember = (latest, notes = []) => {
+    known = latest;
+    knownNoteLines = latest ? notes : [];
+    return latest;
+};
+/** 文件里的还新鲜就用它,否则问一次并存下;问不到就继续用上次的 */
+export async function refreshLatest(o = {}) {
+    const file = o.file ?? updateFile();
+    const now = o.now ?? Date.now();
+    const rec = await readUpdateRecord(file);
+    if (rec.off)
+        return remember(null);
+    const at = rec.checkedAt ? Date.parse(rec.checkedAt) : Number.NaN;
+    // 时间在将来(改过系统时间)算不新鲜
+    if (rec.latest && now >= at && now - at < DAY_MS)
+        return remember(rec.latest, rec.notes);
+    const release = await fetchRelease(o.fetch);
+    if (!release)
+        return remember(rec.latest ?? null, rec.notes);
+    const { version: latest, notes } = release;
+    remember(latest, notes);
+    try {
+        await mkdir(dirname(file), { recursive: true });
+        const tmp = `${file}.${process.pid}.tmp`;
+        await writeFile(tmp, `${JSON.stringify({ checkedAt: new Date(now).toISOString(), latest, notes }, null, 2)}\n`);
+        await rename(tmp, file);
+    }
+    catch {
+        /* 写不了:下个小时再问一次,不影响别的 */
+    }
+    return latest;
+}
+/** serve 起来时调:先用存着的那份,一分钟后问(刚开机网可能还没好),之后每小时看一眼,过了一天才真的问。定时器不拦进程退出 */
+export function startUpdateChecks(o = {}) {
+    void readUpdateRecord(o.file).then((rec) => { remember(rec.off ? null : rec.latest ?? null, rec.notes); });
+    const run = () => { void refreshLatest(o).catch(() => { }); };
+    const first = setTimeout(run, o.firstMs ?? FIRST_MS);
+    first.unref();
+    const every = setInterval(run, o.everyMs ?? HOUR_MS);
+    every.unref();
+    return () => { clearTimeout(first); clearInterval(every); };
+}

package/dist/brain/api.js

@@ -76,10 +76,13 @@ export function effortFetch(effort, base = fetch) {
         return base(input, { ...init, body: JSON.stringify({ ...body, reasoning_effort: effort }) });
     };
 }
-/** 报错只说状态码:SDK 的异常里带着整个请求 */
+/** 报错只说状态码和错误码(欠费、key 失效靠它分):SDK 的异常里带着整个请求,别的都不要 */
 function failure(err) {
-    const status = err && typeof err === 'object' && 'statusCode' in err ? err.statusCode : undefined;
-    return typeof status === 'number' ? `api:HTTP ${status}` : 'api:请求或流断了';
+    const e = err && typeof err === 'object' ? err : {};
+    if (typeof e.statusCode !== 'number')
+        return 'api:请求或流断了';
+    const code = typeof e.responseBody === 'string' ? /"code"\s*:\s*"([A-Za-z0-9_.-]{2,64})"/.exec(e.responseBody)?.[1] : undefined;
+    return `api:HTTP ${e.statusCode}${code ? ` ${code}` : ''}`;
 }
 const outputText = (o) => (o && typeof o === 'object' && typeof o.text === 'string' ? o.text : JSON.stringify(o) ?? '');
 const errorText = (e) => (e instanceof Error ? e.message : String(e));

package/dist/realtime/preview.d.ts

@@ -21,3 +21,19 @@ export declare function probeRealtime(o?: {
     endpoint?: string;
     timeoutMs?: number;
 }): Promise<string | null>;
+export declare const unclearWhy: (why: string) => boolean;
+/**
+ * 连不上时问清原因。Node 的 WebSocket 客户端握手被拒只给 error,看不到状态码,key 错和断网一个样;
+ * 同一个地址发一次普通的升级请求,被拒时百炼回 401 和 {"code":"InvalidApiKey"}(2026-11-07 假 key 实测)。不花钱,升级成了也当场断。
+ * 回错误码,没有错误码回 http:<状态码>;答应升级了回 null(key 是好的,刚才那次是别的原因);根本连不上回 network。
+ */
+export declare function askRealtime(o?: {
+    auth?: {
+        key: string;
+        workspaceId: string;
+    };
+    model?: string;
+    env?: NodeJS.ProcessEnv;
+    endpoint?: string;
+    timeoutMs?: number;
+}): Promise<string | null>;

package/dist/realtime/preview.js

@@ -2,9 +2,12 @@
  * 试听嘴的一个音色(工作台音色页「实时的嘴」):真连一次百炼 realtime,让它照念一句(同实时老师的照念指令),收下 24k PCM 包成 wav。
  * 几分钱一次;调用方按「音色 + 句子」缓存,同一句同一个音色只念一次。
  */
+import { randomBytes } from 'node:crypto';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
 import { readCue } from "./cues.js";
 import { wavOfPcm } from "../shared/wav.js";
-import { OUTPUT_RATE, RealtimeSession } from "./bailian.js";
+import { OUTPUT_RATE, REALTIME_MODEL, RealtimeSession, dashscopeAuth, endpointOf } from "./bailian.js";
 export async function previewVoice(o) {
     const chunks = [];
     let err = '';
@@ -34,5 +37,44 @@ export async function probeRealtime(o = {}) {
     const s = new RealtimeSession({ instructions: '试连。', turn: 'manual', model: o.model, auth: o.auth, env: o.env, endpoint: o.endpoint, timeoutMs: o.timeoutMs }, {});
     const why = await s.connect();
     s.close('probe');
+    if (why !== null && UNCLEAR.test(why))
+        return (await askRealtime(o)) ?? why;
     return why;
 }
+/** WebSocket 只告诉我们「连不上」的那几种:握手被拒、连上又断 */
+const UNCLEAR = /^(connect|closed:)/;
+export const unclearWhy = (why) => UNCLEAR.test(why);
+/**
+ * 连不上时问清原因。Node 的 WebSocket 客户端握手被拒只给 error,看不到状态码,key 错和断网一个样;
+ * 同一个地址发一次普通的升级请求,被拒时百炼回 401 和 {"code":"InvalidApiKey"}(2026-11-07 假 key 实测)。不花钱,升级成了也当场断。
+ * 回错误码,没有错误码回 http:<状态码>;答应升级了回 null(key 是好的,刚才那次是别的原因);根本连不上回 network。
+ */
+export function askRealtime(o = {}) {
+    const auth = o.endpoint ? null : o.auth ?? dashscopeAuth(o.env);
+    if (!o.endpoint && !auth)
+        return Promise.resolve('no_auth');
+    const url = new URL((o.endpoint ?? endpointOf(auth.workspaceId, o.model ?? REALTIME_MODEL)).replace(/^ws/, 'http'));
+    return new Promise((resolve) => {
+        const send = url.protocol === 'https:' ? httpsRequest : httpRequest;
+        const req = send(url, {
+            method: 'GET',
+            timeout: o.timeoutMs ?? 5000,
+            headers: { authorization: `Bearer ${auth?.key ?? 'sk-test'}`, connection: 'Upgrade', upgrade: 'websocket', 'sec-websocket-version': '13', 'sec-websocket-key': randomBytes(16).toString('base64') },
+        });
+        req.on('upgrade', (_res, socket) => { socket.destroy(); resolve(null); });
+        req.on('response', (res) => {
+            let body = '';
+            res.setEncoding('utf8');
+            res.on('data', (c) => { if (body.length < 4096)
+                body += c; });
+            res.on('end', () => {
+                // 只取错误码:别的留给人看没用,也不让对面的长文本跟着往下传
+                const code = /"code"\s*:\s*"([A-Za-z0-9_.-]{2,64})"/.exec(body)?.[1];
+                resolve(code ?? `http:${res.statusCode ?? 0}`);
+            });
+        });
+        req.on('timeout', () => req.destroy());
+        req.on('error', () => resolve('network'));
+        req.end();
+    });
+}

package/dist/runtime/live/call.d.ts

@@ -9,6 +9,8 @@ export interface KidSocket {
 export interface LiveApp {
     readonly runner: Runner;
     now(): Date;
+    /** 嘴连上了(null)、连不上(原因)、通话中百炼报错(midCall):app 那层记下,给家长看 */
+    mouthHealth?(why: string | null, midCall?: boolean): Promise<void>;
 }
 export interface LiveDeps {
     ctx: LiveApp;

package/dist/runtime/live/call.js

@@ -401,6 +401,7 @@ export class LiveCall {
                 if (this.session !== s)
                     return;
                 this.send({ t: 'err', status: 502, error: m });
+                void this.deps.ctx.mouthHealth?.(m, true);
                 // commit 没收下(声音太少):这一句不会有转写,照转写是空的办
                 if ((this.pendingVoice || this.echoHeld) && /committing input audio buffer/i.test(m))
                     this.heard('');
@@ -419,8 +420,12 @@ export class LiveCall {
     /** 开一条嘴的会话并换上(第一次、断了以后现连) */
     async connectMouth() {
         const { why, s, open } = await this.openMouth();
-        if (why === null)
+        if (why === null) {
             this.mounted(s, open);
+            void this.deps.ctx.mouthHealth?.(null);
+        }
+        else
+            await this.deps.ctx.mouthHealth?.(why);
         return why;
     }
     /** 换上一条嘴的会话:一直听的状态都从头来 */

package/dist/shared/upgrade.d.ts

@@ -0,0 +1,9 @@
+/** 版本比较与升级步骤:服务、托盘(轻入口,不带 zod)、家长端、doctor 共用 */
+/** 升级要跑的命令:cotutor update 一条管到底(换程序、更新每个孩子的出厂文件、重起服务和图标,update-cmd.ts) */
+export declare const UPGRADE_STEPS: readonly ["cotutor update"];
+/** 给家长看的那份。Windows 上带 .cmd:PowerShell 缺省禁止跑脚本,不带后缀找到的是被拦的 .ps1,一跑就报错;.cmd 在 PowerShell 和 cmd.exe 里都能跑(2026-11-07 真机) */
+export declare function upgradeSteps(platform?: NodeJS.Platform): string[];
+/** 正式版的版本号。预发布不算;从网上拿来的还要显示给家长,其余一律不认 */
+export declare function isPlainVersion(v: unknown): v is string;
+/** a 比 b 新;任一边不是正式版的版本号 → false,宁可不提醒 */
+export declare function isNewer(a: unknown, b: unknown): boolean;

package/dist/shared/upgrade.js

@@ -0,0 +1,23 @@
+/** 版本比较与升级步骤:服务、托盘(轻入口,不带 zod)、家长端、doctor 共用 */
+/** 升级要跑的命令:cotutor update 一条管到底(换程序、更新每个孩子的出厂文件、重起服务和图标,update-cmd.ts) */
+export const UPGRADE_STEPS = ['cotutor update'];
+/** 给家长看的那份。Windows 上带 .cmd:PowerShell 缺省禁止跑脚本,不带后缀找到的是被拦的 .ps1,一跑就报错;.cmd 在 PowerShell 和 cmd.exe 里都能跑(2026-11-07 真机) */
+export function upgradeSteps(platform = process.platform) {
+    return UPGRADE_STEPS.map((s) => (platform === 'win32' ? s.replace(' ', '.cmd ') : s));
+}
+const PLAIN = /^(\d+)\.(\d+)\.(\d+)$/;
+/** 正式版的版本号。预发布不算;从网上拿来的还要显示给家长,其余一律不认 */
+export function isPlainVersion(v) {
+    return typeof v === 'string' && v.length <= 32 && PLAIN.test(v);
+}
+/** a 比 b 新;任一边不是正式版的版本号 → false,宁可不提醒 */
+export function isNewer(a, b) {
+    if (!isPlainVersion(a) || !isPlainVersion(b))
+        return false;
+    const x = a.split('.').map(Number);
+    const y = b.split('.').map(Number);
+    for (let i = 0; i < 3; i++)
+        if (x[i] !== y[i])
+            return x[i] > y[i];
+    return false;
+}

package/dist/ui/kid/kid-page.js

@@ -1066,7 +1066,12 @@ ${HOME_TILES_JS}
     try { S.home = await api('GET', '/api/kid/home'); setOffline(false); document.body.classList.toggle('hand-left', S.home.hand === 'left'); setGated(!REEL && S.home.ready === false); renderHome(); phIdle(); }
     catch { setOffline(true); }
   };
-  /** 百炼没配:首页的老师灰着点不进去;在老师页上就回首页。家长配好了下一次读首页自己就好 */
+  /** 嘴连不上时:要家长动手的(欠费、key 失效,服务端的 ready 变 false)回首页说「叫爸爸妈妈」,别的(网络抖)留在原地接着重连 */
+  const gateCheck = async () => {
+    if (REEL) return;
+    try { const d = await api('GET', '/api/kid/home'); if (d.ready === false) { S.home = d; setGated(true); renderHome(); } } catch {}
+  };
+  /** 百炼没配、欠费、key 失效:首页的老师灰着点不进去;在老师页上就回首页。家长弄好了下一次读首页自己就好 */
   const setGated = (on) => {
     if (S.gated === on) return;
     S.gated = on;
@@ -3130,7 +3135,8 @@ __REEL_DOCK_JS__
       case 'vad': if (m.on) lvSend({ t: 'ctx', body: liveBody() }); liveDispatch({ type: 'vad', on: Boolean(m.on) }); break;
       case 'duck': liveDispatch({ type: 'duck' }); break;
       case 'unduck': liveDispatch({ type: 'unduck' }); break;
-      case 'down': case 'end': liveDispatch({ type: 'drop' }); break;
+      case 'down': liveDispatch({ type: 'drop' }); gateCheck(); break;
+      case 'end': liveDispatch({ type: 'drop' }); break;
       case 'tutor':
         // 嘴接住的字一到就上字幕;照念的字幕跟 read 走(到点才亮)
         if (m.of !== 'catch') break;

package/dist/ui/parent/parent-home-page.js

@@ -10,6 +10,7 @@
 import { faviconLinks } from "../shared/favicon.js";
 import { BRAND_CSS, BRAND_FOOTER, BRAND_JS, titleLogo } from "../shared/brand.js";
 import { pageDomJs } from "../shared/page-dom.js";
+import { upgradeSteps } from "../../shared/upgrade.js";
 export const PARENT_HOME_PAGE = String.raw `<!doctype html>
 <html lang="zh-CN"><head><meta charset="utf-8">
 <meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
@@ -216,9 +217,17 @@ ${BRAND_CSS}
     .main { display:grid; grid-template-columns:minmax(0,1fr) 380px; gap:22px; align-items:start; }
     .gh { padding:0 6px 6px; }
   }
+  .upd { position:relative; display:flex; flex-direction:column; gap:6px; margin:0 0 12px; padding:12px 14px; border-radius:14px; background:var(--card); box-shadow:0 0 0 1px var(--line); font-size:15px; }
+  .upd.bad { box-shadow:0 0 0 1px var(--accent); }
+  .upd ul { margin:0; padding-left:18px; font-size:14px; }
+  .upd .sub { color:var(--dim); font-size:14px; padding-right:64px; }
+  .upd pre { margin:2px 0 0; padding:10px 12px; border-radius:10px; background:var(--paper); font:13px/1.6 ui-monospace,Menlo,Consolas,monospace; white-space:pre-wrap; overflow-wrap:anywhere; user-select:all; -webkit-user-select:all; }
+  .upd button { position:absolute; top:6px; right:6px; min-height:44px; padding:0 10px; border:0; background:transparent; color:var(--accent); font-size:15px; cursor:pointer; }
 </style></head><body>
 <div class="wrap" id="main">
   <div class="top"><span class="ttl"><span id="ct-mark" class="ct-draw ct-hover">${titleLogo(true)}</span><b id="title">家长</b></span><nav class="seg"><a class="on" href="/parent/home">首页</a><a href="/parent">记录</a><a href="/parent/settings">设置</a></nav><small id="pub"></small><a class="devl" href="/dev" target="_blank" title="工作台:细调老师文件、activity(新窗口)">工作台<svg width="11" height="11" viewBox="0 0 12 12" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" aria-hidden="true"><path d="M4 2h6v6"/><path d="M10 2 3 9"/></svg></a></div>
+  <div id="troublebar"></div>
+  <div id="updatebar"></div>
   <div id="qrtop"></div>
   <div class="main">
     <section id="pv" aria-label="孩子看到的首页">
@@ -291,7 +300,7 @@ ${pageDomJs(3200)}
   window.addEventListener('resize', fit);
 
   // ---- 百炼:老师开口靠它,没配孩子那边打不开。一块常驻的元素,重画只挪它的位置,输着的 key 不会被抹掉 ----
-  const BL = { st: null, open: false, busy: false, msg: '' };
+  const BL = { st: null, open: false, opened: false, busy: false, msg: '' };
   const blEl = h('div', { id: 'bailian' });
   const blKey = h('input', { class: 'fld', id: 'bl-key', type: 'password', autocomplete: 'off', spellcheck: 'false', placeholder: 'sk- 开头' });
   const blWs = h('input', { class: 'fld', id: 'bl-ws', autocomplete: 'off', spellcheck: 'false', autocapitalize: 'off', placeholder: '如 llm-xxxxxxxx' });
@@ -363,7 +372,40 @@ ${pageDomJs(3200)}
       h('div', { class: 'note' }, d.https ? (d.notes[0] || '') : '', d.devices ? '' : (d.https ? ' ' : '') + '还没有平板连进来过,所以这块先开着;连过以后自动收起。'));
   };
 
+  // 有新版本(服务每天问一次 npm,machine/update.ts):只在家长端说,孩子端不说;点「知道了」这个版本不再提,读不了 localStorage 就每次都说
+  const UPGRADE_STEPS = ${JSON.stringify(upgradeSteps())};
+  // 跑起来以后百炼出的问题(欠费、key 失效、连不上,machine/bailian.ts):配好了不等于用得了。试连通了就没了
+  const showTrouble = (hh) => {
+    const box = $('#troublebar');
+    const t = hh && hh.bailianTrouble;
+    if (!t) { box.replaceChildren(); return; }
+    box.replaceChildren(h('div', { class: 'upd bad' },
+      h('b', {}, t.message),
+      h('span', { class: 'sub' }, t.fix + (t.blocked ? ' 现在孩子那边显示「老师们还没到」。' : '')),
+      t.why ? h('small', { class: 'sub' }, '百炼说:' + t.why) : null,
+      h('button', { type: 'button', on: { click: async () => {
+        try { const r = await api('POST', '/api/parent/bailian/test'); toast(r.ok ? '通了' : '还是没通:' + r.message); } catch (e) { toast('没试成:' + e.message); }
+        load();
+      } } }, '试连')));
+  };
+  const showUpdate = async () => {
+    const box = $('#updatebar');
+    const hh = await api('GET', '/api/health').catch(() => null);
+    showTrouble(hh);
+    const latest = hh && hh.latest;
+    let seen = null;
+    try { seen = localStorage.getItem('cotutor.updateSeen'); } catch {}
+    if (!latest || seen === latest) { box.replaceChildren(); return; }
+    box.replaceChildren(h('div', { class: 'upd' },
+      h('b', {}, '有新版本 ' + latest),
+      h('span', { class: 'sub' }, '现在是 ' + hh.version + (hh.latestNotes && hh.latestNotes.length ? '。这次改了:' : '。')),
+      hh.latestNotes && hh.latestNotes.length ? h('ul', {}, hh.latestNotes.map((n) => h('li', {}, n))) : null,
+      h('span', { class: 'sub' }, '挑孩子不用的时候,在这台电脑的终端里运行(服务会重起,孩子在通话时不会动):'),
+      h('pre', {}, UPGRADE_STEPS.map((s) => h('div', {}, s))),
+      h('button', { type: 'button', on: { click: () => { try { localStorage.setItem('cotutor.updateSeen', latest); } catch {} box.replaceChildren(); } } }, '知道了')));
+  };
   const load = async () => {
+    showUpdate();
     try { D = await api('GET', '/api/parent/home'); } catch (e) { toast('读不到:' + e.message); return; }
     BL.st = await api('GET', '/api/parent/bailian').catch(() => null);
     QR.d = await api('GET', '/api/parent/qr').catch(() => null);
@@ -480,7 +522,10 @@ ${pageDomJs(3200)}
       : inlineForm(t, sel);
     blDraw();
     qrDraw();
-    const blTop = BL.st && !BL.st.ready;
+    // 没配、key 或业务空间不对:要改的就是这一块,放最上面、展开,别让家长往下翻
+    const blFix = BL.st && BL.st.trouble && (BL.st.trouble.kind === 'key' || BL.st.trouble.kind === 'space');
+    if (blFix && BL.st.canEdit && !BL.opened) { BL.opened = true; BL.open = true; }
+    const blTop = BL.st && (!BL.st.ready || blFix);
     if (wide) $('#qrtop').replaceChildren(); else $('#qrtop').replaceChildren(qrEl);
     $('#body').replaceChildren(h('div', {}, blTop ? blEl : null, wide ? qrEl : null, pane, extras, self, blTop ? null : blEl));
   };

package/package.json

@@ -1,10 +1,19 @@
 {
   "name": "cotutor",
-  "version": "0.4.0",
+  "version": "0.4.2",
+  "releaseNotes": [
+    "百炼欠费、key 失效或连不上时,图标和家长端会说清楚,孩子那边会请爸爸妈妈来看,不再一直转",
+    "升级只要一条命令 cotutor update,几个孩子一次升好,孩子在通话时不动",
+    "用 Homebrew 装 Node 的电脑:Node 升级后服务和图标不会再起不来",
+    "有新版本时能直接看到这次改了什么"
+  ],
   "description": "AI tutors that co-teach with parents at home: real-time voice, an interactive whiteboard, and learning memory in your own Obsidian vault. Self-hosted; built for China's elementary curriculum.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
-  "repository": "github:TarsLab/cotutor",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TarsLab/cotutor.git"
+  },
   "homepage": "https://github.com/TarsLab/cotutor#readme",
   "bugs": "https://github.com/TarsLab/cotutor/issues",
   "keywords": [

package/skills/cotutor-analyze/references//345/221/275/344/273/244/344/270/216/346/226/207/344/273/266.md

@@ -3,7 +3,7 @@
 ## 分析用的命令(在 workspace 根跑;完整用法 cotutor --help)
 
 ```
-  cotutor doctor [--workspace <dir>] [--json] [--live]                 逐项体检;--live 真连一次百炼实时模型、真合成一句配音(花一分钱)把 API 层的坑摆出来(真跑老师用 cotutor send)
+  cotutor doctor [--workspace <dir>] [--json] [--live]                 逐项体检;--live 真连一次百炼实时模型、真合成一句配音(花一分钱)把 API 层的坑摆出来(真跑老师用 cotutor send);--json 里不过的项带 cmd(能直接跑)或 human(要人来)
   cotutor send <老师> [<消息>] [--from kid|system] [--runtime <名>] [--new] [--photo a.jpg,b.png] [--activity <名> [--param '名=值;名=值']] [--lane main,tts] [--quiet]   终端里发一条,现场按道打印每道工序的事件,说完打印结果(孩子的话照实时写,同孩子端:上下文包带 live:、不补提问卡,只是没有嘴;--from system 不算;--new 开新话题;--photo 带作业照片,拷进 captures/,有照片时消息可以空;--activity 像孩子点了首页的 activity 按钮,新开话题,参数同按钮下面那几行;--quiet 只要结果)
   cotutor pack <老师> [<消息>] [--from kid|system] [--at <ISO时间>] [--activity <名> [--param '名=值;名=值']] [--json]   干跑上下文包(--activity 看 activity 话题第一条老师拿到什么):不起模型,打印现在会发给老师的那份 + 每段来自哪个文件、那里一共几条、按政策带了几条(改了档案 / 日记 / 计划立刻看效果)
   cotutor replay <老师> <job> [<日期>] [--runtime <名>] [--json]   回放一轮:同一问按现在的 vault 与提示词再跑一遍(落 evals/,不进孩子的对话、不配音),跑完并排打印上下文包 / 讲稿 / 卡 / 读了什么的 diff

package/skills/cotutor-tune/references//345/255/227/346/256/265.md

@@ -41,7 +41,7 @@ frontmatter 只写应用支持的这几个键:`name`、`description`、`maxTurns
 ## 相关命令(完整用法 cotutor --help)
 
 ```
-  cotutor doctor [--workspace <dir>] [--json] [--live]                 逐项体检;--live 真连一次百炼实时模型、真合成一句配音(花一分钱)把 API 层的坑摆出来(真跑老师用 cotutor send)
+  cotutor doctor [--workspace <dir>] [--json] [--live]                 逐项体检;--live 真连一次百炼实时模型、真合成一句配音(花一分钱)把 API 层的坑摆出来(真跑老师用 cotutor send);--json 里不过的项带 cmd(能直接跑)或 human(要人来)
   cotutor upgrade [--workspace <dir>] [--force <老师>]...                老师文件、activity 与 skill 换新版:没改过的直接换,改过的只报 diff(--force <老师> 或 --force <老师>/<名> 才覆盖,原文留 .bak)
   cotutor upgrade --config [--dry-run] [--workspace <dir>]              cotutor.json 补缺:新出厂老师 / 运行时 / 命令模板旗标(只加缺的,你改过的值不动)
   cotutor add <老师名> --display <显示名> [--subject <学科>] [--avatar <emoji|图片相对路径>] [--hidden]   加一位自家的老师:出模板文件、进 cotutor.json、建目录(名字以 -tutor 结尾的是老师,figshot 给它做头像)