cotutor 0.4.1 → 0.4.3

package/dist/app/machine/bailian.js

@@ -10,31 +10,111 @@
  *
  * 改 key 要么在这台电脑上(本机免密),要么设了家长密码:没设 PIN 时局域网谁都进得了家长端,不让别的设备往这台电脑写 key。
  * 测试与探针指了假的实时端点(COTUTOR_LIVE_ENDPOINT)就当配好了,试连也连那个。
+ *
+ * 跑起来以后也会坏(欠费、key 失效、这台电脑断网):ready 只说「填过」,看不出来。嘴和脑出错时记一笔(note),/api/health 带给图标和家长端;
+ * 要家长动手的那几类,孩子端显示「叫爸爸妈妈」(blocked)。错误码照官方错误码表(help.aliyun.com/zh/model-studio/error-code);欠费没法真测,是照表写的,假 key 是真跑过的。
  */
 import { mkdir, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname } from 'node:path';
 import { bailianFile } from "../../shared/qianwen.js";
 import { dashscopeAuth } from "../../realtime/bailian.js";
-import { probeRealtime } from "../../realtime/preview.js";
+import { askRealtime, probeRealtime, unclearWhy } from "../../realtime/preview.js";
+const TROUBLE_TEXT = {
+    key: { message: '百炼的 key 不对或失效了', fix: '到家长端「首页」换一把百炼按量的 key。' },
+    money: { message: '百炼欠费或没开通按量付费', fix: '到百炼控制台充值或开通,好了几分钟内自己恢复。' },
+    space: { message: '这把 key 用不了这个业务空间', fix: '到家长端「首页」核对业务空间 id。' },
+    network: { message: '这台电脑连不上百炼', fix: '看看这台电脑的网络,好了几分钟内自己恢复。' },
+    other: { message: '百炼这几次都没连上', fix: '过一会儿再看;一直这样,到家长端「首页」点试连。' },
+};
+/** 按错误码分类;官方表里没有的算 other */
+export function troubleKind(why) {
+    if (/InvalidApiKey|invalid_api_key|\b401\b/i.test(why))
+        return 'key';
+    if (/Arrearage|BillOverdue|AllocationQuota|CommodityNotPurchased|Unpurchased|insufficient_quota/i.test(why))
+        return 'money';
+    if (/AccessDenied|\b403\b/i.test(why))
+        return 'space';
+    if (/^network$|^timeout$|请求或流断了/.test(why))
+        return 'network';
+    return 'other';
+}
+/** 这几类等不好,要家长动手,一次就算;网络和别的可能只是抖一下,连着两次才算 */
+const needsParent = (kind) => kind === 'key' || kind === 'money' || kind === 'space';
+const STRIKES = 2;
+/** 脑和通话中的错没法自己再试(再试要花钱),多久没再犯就算过去了;还在坏的话孩子下一次用又会记上 */
+const EVENT_TTL_MS = 3600_000;
 export function createBailian(opts = {}) {
     const env = opts.env ?? process.env;
     const home = env.HOME || homedir();
     const fake = env.COTUTOR_LIVE_ENDPOINT || undefined;
-    return {
+    const now = opts.now ?? Date.now;
+    const ask = opts.ask ?? (() => askRealtime({ env, endpoint: fake }));
+    const notes = new Map();
+    const probe = opts.probe ?? ((auth) => probeRealtime({ auth, env, endpoint: fake }));
+    const counted = (source) => {
+        const n = notes.get(source);
+        if (!n)
+            return null;
+        if (source !== 'mouth' && now() - n.at > EVENT_TTL_MS) {
+            notes.delete(source);
+            return null;
+        }
+        return needsParent(n.kind) || n.count >= STRIKES ? n : null;
+    };
+    const bailian = {
         status() {
             const auth = dashscopeAuth(env);
             if (!auth)
                 return { ready: Boolean(fake), keyTail: null, workspaceId: null };
             return { ready: true, keyTail: auth.key.slice(-4), workspaceId: auth.workspaceId };
         },
-        probe: opts.probe ?? ((auth) => probeRealtime({ auth, env, endpoint: fake })),
+        probe,
         async save(auth) {
             const file = bailianFile(home);
             await mkdir(dirname(file), { recursive: true });
             await writeFile(file, `${JSON.stringify({ apiKey: auth.key, workspaceId: auth.workspaceId, at: new Date().toISOString() }, null, 2)}\n`, { mode: 0o600 });
+            notes.clear();
+        },
+        trouble() {
+            const n = counted('mouth') ?? counted('call') ?? counted('brain');
+            return n ? { kind: n.kind, ...TROUBLE_TEXT[n.kind], why: n.why.slice(0, 200), blocked: bailian.blocked() } : null;
+        },
+        blocked() {
+            const n = counted('mouth');
+            return Boolean(n && needsParent(n.kind));
+        },
+        async note(source, why) {
+            // 通话自己结束了、还没配:都不是故障(没配有 ready 管)
+            if (why === 'ended' || why === 'no_auth')
+                return;
+            const real = unclearWhy(why) ? (await ask().catch(() => null)) ?? why : why;
+            if (real === 'no_auth')
+                return;
+            const kind = troubleKind(real);
+            // 通话中百炼报的多半是这一句的事(声音太短之类),只认要家长动手的
+            if (source === 'call' && !needsParent(kind))
+                return;
+            const was = notes.get(source);
+            notes.set(source, { why: real, kind, count: (was?.count ?? 0) + 1, at: now() });
+        },
+        fine(source) {
+            if (source)
+                notes.delete(source);
+            else
+                notes.clear();
+        },
+        async recheck() {
+            if (!notes.has('mouth'))
+                return;
+            const why = await probe();
+            if (why === null || why === 'no_auth')
+                notes.delete('mouth');
+            else
+                notes.set('mouth', { why, kind: troubleKind(why), count: STRIKES, at: now() });
         },
     };
+    return bailian;
 }
 /** 试连没通的原因,写给家长看 */
 export function probeMessage(why) {
@@ -44,6 +124,9 @@ export function probeMessage(why) {
         return '连不上:key 或业务空间 id 不对,或者这台电脑上不了网';
     if (why === 'timeout')
         return '连上了,等不到回音(超时),过一会儿再试';
+    const kind = troubleKind(why);
+    if (kind !== 'other')
+        return `${TROUBLE_TEXT[kind].message}。${TROUBLE_TEXT[kind].fix}`;
     return `百炼说:${why}`;
 }
 const KEY_RE = /^sk-[A-Za-z0-9._-]{16,}$/;
@@ -54,12 +137,16 @@ export async function bailianRoute(method, p, ctx, body, who) {
     if (p !== '/api/parent/bailian' && p !== '/api/parent/bailian/test')
         return null;
     const canEdit = who === 'local' || (await ctx.access.pinSet());
-    const view = () => ({ ...ctx.bailian.status(), canEdit });
+    const view = () => ({ ...ctx.bailian.status(), canEdit, trouble: ctx.bailian.trouble() });
     if (p === '/api/parent/bailian/test') {
         if (method !== 'POST')
             return { status: 405, json: { error: 'method_not_allowed' } };
         const t0 = Date.now();
         const why = await ctx.bailian.probe();
+        if (why === null)
+            ctx.bailian.fine();
+        else
+            await ctx.bailian.note('mouth', why);
         return { status: 200, json: { ok: why === null, ms: Date.now() - t0, ...(why === null ? {} : { message: probeMessage(why) }) } };
     }
     if (method === 'GET')

package/dist/app/machine/update.d.ts

@@ -3,14 +3,27 @@ export declare const updateFile: () => string;
 export interface UpdateRecord {
     checkedAt?: string;
     latest?: string;
+    notes?: string[];
     off?: boolean;
 }
+/** 网上来的,要显示给家长:只留几行短的纯文本 */
+export declare function cleanNotes(raw: unknown): string[];
 /** 读不到、写坏了 → 空的,当作没问过 */
 export declare function readUpdateRecord(file?: string): Promise<UpdateRecord>;
+export interface Release {
+    version: string;
+    notes: string[];
+    /** 新版本要的 Node 主次版本,如 [22, 18];没写 → null */
+    minNode: [number, number] | null;
+    /** 答的是不是 npm 本家;不是就说明 npm 不通,下载也要走镜像 */
+    mirror: boolean;
+}
 /** 依次问,谁先答谁算;都问不到 → null */
-export declare function fetchLatest(fetchFn?: typeof fetch, urls?: string[]): Promise<string | null>;
+export declare function fetchRelease(fetchFn?: typeof fetch, urls?: string[]): Promise<Release | null>;
 /** 这个进程现在知道的最新版本;还不知道、关掉了 → null */
 export declare const knownLatest: () => string | null;
+/** 那个版本的更新说明 */
+export declare const knownNotes: () => string[];
 export interface UpdateOptions {
     now?: number;
     fetch?: typeof fetch;

package/dist/app/machine/update.js

@@ -1,6 +1,7 @@
 /**
  * 有没有新版本:服务每天问一次 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 起发布后先扫描),不会提前提醒。
  * 不自动升级:升级要重起服务,孩子可能正在上课;老师文件的更新也要家长知道。
@@ -16,13 +17,19 @@ 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 } : {}),
+            ...(isPlainVersion(j.latest) ? { latest: j.latest, notes: cleanNotes(j.notes) } : {}),
             ...(j.off === true ? { off: true } : {}),
         };
     }
@@ -30,16 +37,21 @@ export async function readUpdateRecord(file = updateFile()) {
         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 fetchLatest(fetchFn = fetch, urls = UPDATE_URLS) {
-    for (const url of urls) {
+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 v = (await r.json()).version;
-            if (isPlainVersion(v))
-                return v;
+            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 {
             /* 这家不通,问下一家 */
@@ -48,27 +60,36 @@ export async function fetchLatest(fetchFn = fetch, urls = UPDATE_URLS) {
     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 (known = null);
+        return remember(null);
     const at = rec.checkedAt ? Date.parse(rec.checkedAt) : Number.NaN;
     // 时间在将来(改过系统时间)算不新鲜
     if (rec.latest && now >= at && now - at < DAY_MS)
-        return (known = rec.latest);
-    const latest = await fetchLatest(o.fetch);
-    if (!latest)
-        return (known = rec.latest ?? null);
-    known = latest;
+        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 }, null, 2)}\n`);
+        await writeFile(tmp, `${JSON.stringify({ checkedAt: new Date(now).toISOString(), latest, notes }, null, 2)}\n`);
         await rename(tmp, file);
     }
     catch {
@@ -78,7 +99,7 @@ export async function refreshLatest(o = {}) {
 }
 /** serve 起来时调:先用存着的那份,一分钟后问(刚开机网可能还没好),之后每小时看一眼,过了一天才真的问。定时器不拦进程退出 */
 export function startUpdateChecks(o = {}) {
-    void readUpdateRecord(o.file).then((rec) => { known = rec.off ? null : rec.latest ?? null; });
+    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();

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/memory/vault-notes.d.ts

@@ -20,6 +20,10 @@ export interface VaultNote {
 }
 /** 只认平铺的 `key: value`;值去掉成对引号。没有 frontmatter → {} */
 export declare function frontmatter(md: string): Record<string, string>;
+/** 现在读 grade 年级的孩子,读一年级是哪年 9 月(学年从 9 月算,同下面的 semesterAt;7、8 月算刚读完的那个年级) */
+export declare function schoolStartFor(grade: number, now: Date): string;
+/** 把 school_start 写进档案的 frontmatter:有空着的那行就填,没有就加在第一行 --- 后面;别的一个字不动 */
+export declare function setSchoolStart(md: string, value: string): string;
 /**
  * 某天是几年级的哪个学期 / 假期:9–1 月上学期、2 月寒假、3–6 月下学期、7–8 月暑假(刚读完的那个年级的暑假)。
  * 学年从 9 月算;`school_start` 是读一年级那年的 9 月(写别的月份也按它所在学年算)。年级不在 1–12 → null。

package/dist/memory/vault-notes.js

@@ -30,6 +30,17 @@ export function frontmatter(md) {
     return {};
 }
 const CN_DIGITS = ['', '一', '二', '三', '四', '五', '六', '七', '八', '九', '十', '十一', '十二'];
+/** 现在读 grade 年级的孩子,读一年级是哪年 9 月(学年从 9 月算,同下面的 semesterAt;7、8 月算刚读完的那个年级) */
+export function schoolStartFor(grade, now) {
+    const year = now.getMonth() + 1 >= 9 ? now.getFullYear() : now.getFullYear() - 1;
+    return `${year - (grade - 1)}-09`;
+}
+/** 把 school_start 写进档案的 frontmatter:有空着的那行就填,没有就加在第一行 --- 后面;别的一个字不动 */
+export function setSchoolStart(md, value) {
+    if (/^school_start:.*$/m.test(md))
+        return md.replace(/^school_start:.*$/m, `school_start: ${value}`);
+    return md.replace(/^---\r?\n/, (m) => `${m}school_start: ${value}\n`);
+}
 /**
  * 某天是几年级的哪个学期 / 假期:9–1 月上学期、2 月寒假、3–6 月下学期、7–8 月暑假(刚读完的那个年级的暑假)。
  * 学年从 9 月算;`school_start` 是读一年级那年的 9 月(写别的月份也按它所在学年算)。年级不在 1–12 → null。

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

@@ -1,8 +1,10 @@
 /** 版本比较与升级步骤:服务、托盘(轻入口,不带 zod)、家长端、doctor 共用 */
-/** 升级程序的三步。分开写不用 &&:Windows 默认的 PowerShell 5.1 不认 &&;顺序是先换文件再重起,新代码不会读到旧文件;restart 顺手把图标也换上新代码 */
-export declare const UPGRADE_STEPS: readonly ["npm i -g cotutor", "cotutor upgrade", "cotutor service restart"];
-/** 给家长看的那份。Windows 上带 .cmd:PowerShell 缺省禁止跑脚本,不带后缀找到的是被拦的 .ps1,第一条就报错;.cmd 在 PowerShell 和 cmd.exe 里都能跑(2026-11-07 真机) */
+/** 升级要跑的命令: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[];
+/** 给家长抄的一条命令:Windows 上第一个词带 .cmd,原因同上 */
+export declare function cliLine(cmd: string, platform?: NodeJS.Platform): string;
 /** 正式版的版本号。预发布不算;从网上拿来的还要显示给家长,其余一律不认 */
 export declare function isPlainVersion(v: unknown): v is string;
 /** a 比 b 新;任一边不是正式版的版本号 → false,宁可不提醒 */

package/dist/shared/upgrade.js

@@ -1,9 +1,13 @@
 /** 版本比较与升级步骤:服务、托盘(轻入口,不带 zod)、家长端、doctor 共用 */
-/** 升级程序的三步。分开写不用 &&:Windows 默认的 PowerShell 5.1 不认 &&;顺序是先换文件再重起,新代码不会读到旧文件;restart 顺手把图标也换上新代码 */
-export const UPGRADE_STEPS = ['npm i -g cotutor', 'cotutor upgrade', 'cotutor service restart'];
-/** 给家长看的那份。Windows 上带 .cmd:PowerShell 缺省禁止跑脚本,不带后缀找到的是被拦的 .ps1,第一条就报错;.cmd 在 PowerShell 和 cmd.exe 里都能跑(2026-11-07 真机) */
+/** 升级要跑的命令: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));
+    return UPGRADE_STEPS.map((s) => cliLine(s, platform));
+}
+/** 给家长抄的一条命令:Windows 上第一个词带 .cmd,原因同上 */
+export function cliLine(cmd, platform = process.platform) {
+    return platform === 'win32' ? cmd.replace(/^(cotutor|npm)(?= |$)/, '$1.cmd') : cmd;
 }
 const PLAIN = /^(\d+)\.(\d+)\.(\d+)$/;
 /** 正式版的版本号。预发布不算;从网上拿来的还要显示给家长,其余一律不认 */

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

@@ -218,12 +218,29 @@ ${BRAND_CSS}
     .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); }
+  .setup { position:relative; display:flex; flex-direction:column; gap:2px; margin:0 0 12px; padding:12px 14px; border-radius:14px; background:var(--card); box-shadow:0 0 0 1px var(--line); font-size:15px; }
+  .setup > b { padding-right:64px; }
+  .setup .sp { display:flex; gap:10px; padding:8px 0; border-top:1px solid var(--line); }
+  .setup .sp:first-of-type { border-top:0; }
+  .setup .mk { flex:none; width:20px; text-align:center; color:var(--dim); }
+  .setup .sp.on .mk { color:var(--accent); }
+  .setup .sp.on b { font-weight:500; color:var(--dim); }
+  .setup .tx { display:flex; flex-direction:column; gap:4px; min-width:0; flex:1; }
+  .setup small { color:var(--dim); font-size:14px; line-height:1.5; }
+  .setup 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; }
+  .setup .gr { display:flex; flex-wrap:wrap; gap:6px; margin-top:2px; }
+  .setup .gr button { min-height:44px; padding:0 12px; border:0; border-radius:10px; background:var(--paper); box-shadow:0 0 0 1px var(--line); color:inherit; font-size:15px; cursor:pointer; }
+  .setup .hide { position:absolute; top:6px; right:6px; min-height:44px; padding:0 10px; border:0; background:transparent; color:var(--accent); font-size:15px; cursor:pointer; }
+  .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="setupbar"></div>
   <div id="updatebar"></div>
   <div id="qrtop"></div>
   <div class="main">
@@ -297,7 +314,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' });
@@ -371,21 +388,65 @@ ${pageDomJs(3200)}
 
   // 有新版本(服务每天问一次 npm,machine/update.ts):只在家长端说,孩子端不说;点「知道了」这个版本不再提,读不了 localStorage 就每次都说
   const UPGRADE_STEPS = ${JSON.stringify(upgradeSteps())};
+  // 还差几步(parent-setup.ts):第一次打开家长端,告诉家长接下来做什么。必需的都好了就只剩建议,「知道了」以后不再提
+  const showSetup = async () => {
+    const box = $('#setupbar');
+    const d = await api('GET', '/api/parent/setup').catch(() => null);
+    if (!d) { box.replaceChildren(); return; }
+    let hidden = false;
+    try { hidden = localStorage.getItem('cotutor.setupHidden') === '1'; } catch {}
+    const must = d.steps.filter((s) => s.required);
+    const left = must.filter((s) => !s.done);
+    const extra = d.steps.filter((s) => !s.required && !s.done);
+    if (!left.length && (hidden || !extra.length)) { box.replaceChildren(); return; }
+    const pickGrade = async (g) => {
+      try { await api('POST', '/api/parent/setup/grade', { grade: g }); toast('记下了:' + g + ' 年级'); } catch (e) { toast(e.message); }
+      showSetup();
+    };
+    const row = (s) => h('div', { class: 'sp' + (s.done ? ' on' : '') },
+      h('span', { class: 'mk' }, s.done ? '✓' : '○'),
+      h('span', { class: 'tx' }, h('b', {}, s.title),
+        s.done ? null : h('small', {}, s.detail, s.link ? ' ' : null, s.link ? h('a', { class: 'lnk', href: s.link.href, target: '_blank', rel: 'noopener' }, s.link.text) : null),
+        !s.done && s.commands ? h('pre', {}, s.commands.map((c) => h('div', {}, c))) : null,
+        !s.done && s.grades ? h('span', { class: 'gr' }, [1, 2, 3, 4, 5, 6].map((g) => h('button', { type: 'button', on: { click: () => pickGrade(g) } }, g + ' 年级'))) : null));
+    box.replaceChildren(h('div', { class: 'setup' },
+      h('b', {}, left.length ? '还差 ' + left.length + ' 步,孩子就能用了' : '都好了,还有几件可以做的'),
+      ...(left.length ? must.concat(extra) : extra).map(row),
+      left.length ? null : h('button', { type: 'button', class: 'hide', on: { click: () => { try { localStorage.setItem('cotutor.setupHidden', '1'); } catch {} box.replaceChildren(); } } }, '知道了')));
+  };
+  // 跑起来以后百炼出的问题(欠费、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 + '。挑孩子不用的时候,在这台电脑的终端里依次运行:'),
+      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();
+    showSetup();
     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);
@@ -502,7 +563,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));
   };