cotutor 0.4.1 → 0.4.3

package/dist/app/cli/main.js

@@ -85,8 +85,26 @@ function printOpen(label, page, hint, open) {
         openTarget(process.platform, page);
 }
 const wantsOpen = (flags) => flags.open === true || flags['open-qr'] === true;
+/** 升级前的备份;试用的不备 */
+async function backupBeforeUpgrade(root) {
+    const { describeBackup, makeBackup } = await import("./backup.js");
+    let vault;
+    try {
+        const ws = loadWorkspace(root);
+        if (ws.sandbox)
+            return null;
+        vault = ws.paths.vault;
+    }
+    catch { /* 配置读不了(老布局、写坏了):workspace 照样备,vault 不管 */ }
+    try {
+        return `升级前留了一份备份:${describeBackup(await makeBackup({ root, vault }, { why: 'upgrade', version: BUILD.version }))}`;
+    }
+    catch (err) {
+        return `! 这次没备份成:${err instanceof Error ? err.message : String(err)}`;
+    }
+}
 /** 不用 workspace 的命令:--sandbox 对它们没有意义 */
-const NO_WORKSPACE = ['grades', 'init', 'mock', 'pin', 'cert', 'tray'];
+const NO_WORKSPACE = ['grades', 'init', 'mock', 'pin', 'cert', 'tray', 'update'];
 export async function main(argv) {
     let json = false;
     try {
@@ -146,7 +164,86 @@ export async function main(argv) {
                 }
                 return;
             }
+            case 'report': {
+                const { buildReport } = await import("./report.js");
+                const ws = loadWorkspace(workspace);
+                process.stdout.write(await buildReport(ws, { health: await probeHealth(ws.config.server.port) }));
+                return;
+            }
+            case 'backup': {
+                const backup = await import("./backup.js");
+                const ws = loadWorkspace(workspace);
+                if (ws.sandbox)
+                    throw new UsageError('试用的 workspace 不备份');
+                const target = { root: ws.root, vault: ws.paths.vault };
+                const [sub, name] = positionals;
+                if (!sub) {
+                    const b = await backup.makeBackup(target, { why: 'manual', version: BUILD.version });
+                    process.stdout.write(`备份好了:${backup.describeBackup(b)}\n  在 ${redactHome(backup.backupsOf(ws.root))}\n  不含录音(wav)和能重新生成的文件${b.audioSkipped ? `,这次跳过 ${b.audioSkipped} 个录音` : ''}\n`);
+                    if (b.vault === 'unreadable')
+                        process.stdout.write(`! vault 读不了(${redactHome(ws.paths.vault)}),这份里没有它\n`);
+                    return;
+                }
+                if (sub === 'list') {
+                    const list = await backup.listBackups(ws.root);
+                    if (json) {
+                        process.stdout.write(`${JSON.stringify(list, null, 2)}\n`);
+                        return;
+                    }
+                    if (!list.length)
+                        process.stdout.write('还没有备份:cotutor backup 备一份\n');
+                    for (const b of list)
+                        process.stdout.write(`${backup.describeBackup(b)}\n`);
+                    return;
+                }
+                if (sub !== 'restore' || !name)
+                    throw new UsageError(`cotutor backup [list | restore <名字> [--yes]]\n${USAGE}`);
+                if (!(await backup.listBackups(ws.root)).some((b) => b.name === name))
+                    throw new UsageError(`没有这份备份:${name}(cotutor backup list 看有哪些)`);
+                if (flags.yes !== true) {
+                    process.stdout.write(`会把孩子的文件夹恢复成 ${name} 那时的样子:备份里有的文件都覆盖回去,之后新多出来的不删。\n恢复前会先把现在的样子也备份一份,恢复错了还能回来。服务会停一下。录音不在备份里,不受影响。\n确定的话加 --yes\n`);
+                    process.exitCode = 1;
+                    return;
+                }
+                const host = realHost();
+                const port = ws.config.server.port;
+                const health = await probeHealth(port);
+                if (health && health.mode !== 'service')
+                    throw new UsageError(`端口 ${port} 上有一个 cotutor serve 在终端里跑着:先关掉它(那个终端里 Ctrl-C),再恢复`);
+                if ((health?.calls ?? 0) > 0)
+                    throw new UsageError('孩子正在和老师通话,恢复要停服务:等下课再来');
+                const service = await findService(host, ws.root);
+                if (service && health)
+                    await controlService(host, ws.root, 'stop');
+                const r = await backup.restoreBackup(target, name, { version: BUILD.version });
+                process.stdout.write(`恢复好了:${r.files} 个文件。恢复前的样子留在 ${r.safety}\n`);
+                if (r.vaultCopy)
+                    process.stdout.write(`外面的 vault 没动;要拿回来,那一份的 md 在 ${redactHome(r.vaultCopy)}\n`);
+                if (service && health) {
+                    await controlService(host, ws.root, 'start');
+                    process.stdout.write('服务重起了\n');
+                }
+                return;
+            }
             case 'doctor': {
+                if (flags.fix === true) {
+                    const { runArgv, runFixes } = await import("./doctor-fix.js");
+                    const r = await runFixes({ doctor: () => doctorWorkspace(workspace, {}), run: runArgv, print: (l) => process.stdout.write(`${l}\n`) });
+                    const left = r.checks.filter((c) => !c.ok);
+                    const manual = left.filter((c) => c.human);
+                    const stuck = left.filter((c) => c.cmd);
+                    if (manual.length) {
+                        process.stdout.write('还要人来的:\n');
+                        for (const c of manual)
+                            process.stdout.write(`  ${c.required ? '✗' : '!'} ${c.name.padEnd(26)} ${c.detail}\n`);
+                    }
+                    for (const c of stuck)
+                        process.stdout.write(`修不好:${c.name} ${c.detail}\n`);
+                    process.stdout.write(r.ok ? '体检通过\n' : '体检不过(✗ 是必需项)\n');
+                    if (!r.ok)
+                        process.exitCode = 1;
+                    return;
+                }
                 const r = await doctorWorkspace(workspace, { live: flags.live === true });
                 if (json)
                     process.stdout.write(`${JSON.stringify(redactDeep(r), null, 2)}\n`);
@@ -301,10 +398,12 @@ export async function main(argv) {
                             : `! 后台服务读不到 vault(${redactHome(ws.paths.vault)}):看看这个目录的权限,然后 cotutor service restart`);
                     if (h?.version && h.version !== version())
                         out.push(`! 在跑的是 ${h.version},装的是 ${version()}:cotutor service restart 换上新的`);
+                    if (h?.bailianTrouble)
+                        out.push(`! ${h.bailianTrouble.message}:${h.bailianTrouble.fix}`);
                     if (h?.scheme === 'http' && httpsFiles(ws))
                         out.push('! 证书有了,服务还在走 HTTP(平板上按住说话不可用):cotutor service restart');
                     if (isNewer(h?.latest, version()))
-                        out.push(`! 有新版本 ${h?.latest}(现在是 ${version()}),升级依次运行:${upgradeSteps().join(' ; ')}`);
+                        out.push(`! 有新版本 ${h?.latest}(现在是 ${version()}),升级运行:${upgradeSteps().join(' ; ')}`);
                     return out;
                 };
                 const tellLog = async (dir) => {
@@ -552,10 +651,26 @@ export async function main(argv) {
                     process.stdout.write(`加了主题 ${name}(拷自 ${r.from}):\n  ${redactHome(r.dir)}/theme.json  ← 槽的清单(名字 + 给什么用)\n  ${redactHome(r.dir)}/kid.css     ← 样式,改了刷新就有\n把 cotutor.json 的 kid.theme 改成 "${name}" 就换过去了(服务不用重启)。\n`);
                 return;
             }
+            case 'update': {
+                const { realUpdateDeps, runUpdate } = await import("./update-cmd.js");
+                process.exitCode = await runUpdate(realUpdateDeps(() => { try {
+                    return resolveRoot(workspace).root;
+                }
+                catch {
+                    return null;
+                } }), { anyway: flags.anyway === true });
+                return;
+            }
             case 'upgrade': {
                 if (flags.grade !== undefined)
                     throw new UsageError('upgrade 只更新已安装的教学包,不能用 --grade 切换年级');
                 const { root } = resolveRoot(workspace);
+                // 升级前留一份:新代码弄坏了能回来。备份不成不拦升级,说一声。--dry-run 不动文件,不用
+                if (flags['dry-run'] !== true) {
+                    const said = await backupBeforeUpgrade(root);
+                    if (said && !json)
+                        process.stdout.write(`${said}\n`);
+                }
                 // --config 是另一件事:政策文件补缺(老师文件与 skill 不碰)
                 if (flags.config === true) {
                     const dryRun = flags['dry-run'] === true;

package/dist/app/cli/report.d.ts

@@ -0,0 +1,11 @@
+import type { Workspace } from '../workspace.ts';
+import { type Health } from './service.ts';
+/** 抹掉能认出这家人的东西。太短的(一个字的小名)不抹,不然满篇都被替换 */
+export declare function scrub(text: string, secrets: readonly (string | null | undefined)[]): string;
+export interface ReportOptions {
+    /** 在跑的服务答的;没在跑 null */
+    health: Health | null;
+    now?: Date;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function buildReport(ws: Workspace, o: ReportOptions): Promise<string>;

package/dist/app/cli/report.js

@@ -0,0 +1,110 @@
+/**
+ * 诊断信息(cotutor report、家长端「设置」里的「生成诊断信息」):出了问题时一次说清,发给开发者或帮忙的 AI 助手,不用来回问。
+ * 不含孩子的对话、照片、录音、档案和 key。只收:版本和系统、服务状态、体检没过的、最近出错的那几轮的原因(不要孩子说了什么)、日志里报错的行、孩子端页面的报错。
+ * 孩子的名字、key、业务空间、电脑名、IP、用户名一律抹掉(scrub),最后整篇再抹一遍。给人先看再发,不自动上传。
+ */
+import { arch, homedir, hostname, platform, release, userInfo } from 'node:os';
+import { localDate } from "../../shared/time.js";
+import { dashscopeAuth } from "../../realtime/bailian.js";
+import { listDates, readIndex } from "../../runtime/journal/store.js";
+import { readKidLog } from "../../runtime/journal/kid-log.js";
+import { BUILD } from "../build.js";
+import { listTutors } from "../../schema/config.js";
+import { doctorWorkspace } from "./doctor.js";
+import { listBackups } from "./backup.js";
+import { findService, realHost, tailLog } from "./service.js";
+import { trayStatus } from "./tray.js";
+import { computerName } from "./serve.js";
+const DAYS = 7;
+const MAX_LINE = 180;
+const MAX_ERRORS = 15;
+const LOG_ERROR = /error|fail|失败|没成|崩|exception|ENO[A-Z]+|EADDR|EPERM|EACCES/i;
+const cut = (s, n = MAX_LINE) => (s.length > n ? `${s.slice(0, n)}…` : s);
+/** 抹掉能认出这家人的东西。太短的(一个字的小名)不抹,不然满篇都被替换 */
+export function scrub(text, secrets) {
+    let out = text.replace(/sk-[A-Za-z0-9._-]{4,}/g, 'sk-***').replace(/\b(?:\d{1,3}\.){3}\d{1,3}\b/g, (ip) => (ip === '127.0.0.1' ? ip : '<IP>'));
+    const home = homedir();
+    if (home)
+        out = out.split(home).join('$HOME');
+    const list = [...new Set(secrets.filter((s) => typeof s === 'string' && s.trim().length >= 2))].sort((a, b) => b.length - a.length);
+    for (const s of list)
+        out = out.split(s).join('<隐去>');
+    return out;
+}
+/** 这家人的名字们 */
+function secretsOf(ws, env) {
+    const auth = dashscopeAuth(env);
+    let user = '';
+    try {
+        user = userInfo().username;
+    }
+    catch { /* 没有也行 */ }
+    const name = computerName();
+    return [ws.config.kid.name, ws.config.kid.slug, ws.config.title, auth?.workspaceId, auth?.key, user, name, `${name}.local`, hostname()].filter((s) => Boolean(s));
+}
+const DATE_N = (now, n) => Array.from({ length: n }, (_, i) => localDate(new Date(now.getTime() - i * 24 * 3600_000)));
+/** 最近几天没成的那几轮:只要原因,不要内容 */
+async function failedTurns(ws, now) {
+    const out = [];
+    const since = DATE_N(now, DAYS).at(-1);
+    for (const t of listTutors(ws.config)) {
+        for (const date of (await listDates(ws, t.name).catch(() => [])).filter((d) => d >= since)) {
+            const index = await readIndex(ws, t.name, date).catch(() => null);
+            for (const m of index?.messages ?? [])
+                if (m.result === 'error')
+                    out.push(`${date} ${t.name} ${cut(String(m.error ?? '没说原因'), 120)}`);
+        }
+    }
+    return out.sort().reverse().slice(0, MAX_ERRORS);
+}
+/** 孩子端页面报的错:错误信息和位置,不要上下文(ctx 里可能有孩子正在做的) */
+async function kidErrors(ws, now) {
+    const rows = await readKidLog(ws, DATE_N(now, DAYS)).catch(() => []);
+    const seen = new Map();
+    for (const r of rows)
+        if (r.k === 'error') {
+            const key = `${r.page} ${cut(r.msg, 120)} @ ${cut(r.where, 60)}`;
+            seen.set(key, (seen.get(key) ?? 0) + 1);
+        }
+    return [...seen].slice(-MAX_ERRORS).map(([k, n]) => (n > 1 ? `${k} ×${n}` : k));
+}
+/** 服务日志里报错的行 */
+async function logErrors(logDir) {
+    if (!logDir)
+        return [];
+    const t = await tailLog(logDir, 400).catch(() => null);
+    return (t?.lines ?? []).filter((l) => LOG_ERROR.test(l)).slice(-MAX_ERRORS).map((l) => cut(l));
+}
+export async function buildReport(ws, o) {
+    const now = o.now ?? new Date();
+    const env = o.env ?? process.env;
+    const host = realHost();
+    const h = o.health;
+    const lines = [];
+    const section = (title, items) => {
+        lines.push('', `## ${title}`);
+        lines.push(...(items.length ? items.map((s) => `- ${s}`) : ['- 没有']));
+    };
+    lines.push('# cotutor 诊断信息', '不含孩子的对话、照片、录音、档案和 key;孩子的名字、电脑名、IP 已隐去。', '');
+    lines.push(`- 版本:${BUILD.version ?? '?'}${BUILD.commit ? `(从仓库跑的,${BUILD.commit.slice(0, 7)})` : ''}`);
+    lines.push(`- 系统:${platform()} ${release()} ${arch()};Node ${process.version}`);
+    lines.push(`- 时间:${now.toISOString()}`);
+    const s = await findService(host, ws.root).catch(() => null);
+    const tray = await trayStatus(host).catch(() => null);
+    const running = h ? `在跑(${h.mode === 'service' ? '后台服务' : '终端里'},版本 ${h.version ?? '?'},起来于 ${h.started},走 ${h.scheme ?? '?'})` : '没答应';
+    section('服务', [
+        running,
+        `后台服务:${s ? '装了' : '没装'}`,
+        tray?.supported ? `图标:${tray.installed ? (tray.running ? '在跑' : '装了,没在跑') : '没装'}` : '图标:这个系统上没有',
+        ...(h?.bailianTrouble ? [`百炼故障:${h.bailianTrouble.kind}(${h.bailianTrouble.why ?? ''})`] : []),
+        ...(h?.configError ? [`配置:${cut(h.configError)}`] : []),
+    ]);
+    const doc = await doctorWorkspace(ws.root, { probeEnv: true, firewall: false, now, env }).catch(() => null);
+    section('体检没过的', doc ? doc.checks.filter((c) => !c.ok).map((c) => `${c.required ? '必需' : '建议'} ${c.name}:${cut(c.detail, 140)}`) : ['体检没跑成']);
+    const backups = await listBackups(ws.root).catch(() => []);
+    section('备份', backups[0] ? [`最近一份 ${backups[0].at}(${backups[0].why}),共 ${backups.length} 份`] : ['还没有']);
+    section(`最近 ${DAYS} 天没成的话题(只有原因)`, await failedTurns(ws, now));
+    section('服务日志里报错的行', await logErrors(s?.logDir ?? null));
+    section(`孩子端页面最近 ${DAYS} 天的报错`, await kidErrors(ws, now));
+    return `${scrub(lines.join('\n'), secretsOf(ws, env))}\n`;
+}

package/dist/app/cli/serve.d.ts

@@ -25,7 +25,6 @@ export interface ServeResult {
     parentPage: string;
     warnings: string[];
 }
-/** 证书路径:cotutor.json 的 server.https 优先(相对 workspace 根),否则机器级 ~/.config/cotutor/certs/;都没有 → null */
 export declare function httpsFiles(ws: Workspace): {
     cert: string;
     key: string;

package/dist/app/cli/serve.js

@@ -18,10 +18,13 @@ import { answersLocally } from "./port.js";
 import { awakeScript, psArgs } from "./service-windows.js";
 import { createContext, createHandler } from "../http/app.js";
 import { liveUpgrade } from "../ws/route.js";
+import { startDailyBackups } from "./backup.js";
+import { BUILD } from "../build.js";
 import { AUTO_BOOKKEEP_EVERY_MS, autoBookkeep } from "../../runtime/auto-bookkeep.js";
 import { USER_CERT_DIR, expandPath, loadWorkspace } from "../workspace.js";
 export { siteUrl };
 /** 证书路径:cotutor.json 的 server.https 优先(相对 workspace 根),否则机器级 ~/.config/cotutor/certs/;都没有 → null */
+const BAILIAN_RECHECK_MS = 120_000;
 export function httpsFiles(ws) {
     const h = ws.config.server.https;
     if (h)
@@ -126,6 +129,17 @@ export async function serveWorkspace(opts = {}) {
     }, AUTO_BOOKKEEP_EVERY_MS);
     timer.unref();
     server.once('close', () => clearInterval(timer));
+    // 嘴连不上时隔一阵再试:充上钱、网回来了,没人点也会恢复,孩子端和图标跟着好
+    const recheck = setInterval(() => { void ctx.bailian.recheck().catch(() => undefined); }, BAILIAN_RECHECK_MS);
+    recheck.unref();
+    server.once('close', () => clearInterval(recheck));
+    // 每天备份一份(backup.ts):试用的不备;孩子在通话时往后推
+    const stopBackups = startDailyBackups({
+        target: () => (ctx.ws.sandbox ? null : { root: ctx.ws.root, vault: ctx.ws.paths.vault }),
+        busy: () => liveUpgrade.openCalls() > 0,
+        version: BUILD.version,
+    });
+    server.once('close', stopBackups);
     if (opts.awake !== false) {
         const stop = holdAwake(() => liveUpgrade.openCalls() > 0 || Object.keys(ctx.ws.config.tutors).some((t) => ctx.runner.running(t) !== null));
         server.once('close', stop);

package/dist/app/cli/service.d.ts

@@ -28,6 +28,22 @@ export declare function earlyLogHint(platform: ServicePlatform, s: {
 }): string;
 /** 看护进程的日志(Windows):serve 退了几次、起来之前的输出 */
 export declare const KEEPER_LOG = "keeper.log";
+/**
+ * launchctl bootout 发完信号就回,进程还没退;这时 bootstrap 报 5: Input/output error,服务就停在那儿了(2026-11-07 实测重装 12 次失败 10 次)。
+ * 等它真的卸下来再往下走。launchd 最多等进程 20 秒(ExitTimeOut 缺省),再不走它自己会杀。
+ */
+export declare function launchdUnload(host: Pick<ServiceHost, 'run'>, target: string, waitMs?: number): Promise<void>;
+/** 装上;刚卸下的那一下还可能报错,隔一秒再试几次,真的不行才算不行 */
+export declare function launchdLoad(host: Pick<ServiceHost, 'run' | 'uid'>, file: string, tries?: number): Promise<{
+    code: number;
+    stdout: string;
+    stderr: string;
+}>;
+/**
+ * 写进服务文件、登录项的 node。Homebrew 的 process.execPath 是带版本号的路径(实测 /opt/homebrew/Cellar/node/26.12.1_1/bin/node),
+ * brew upgrade 清掉旧版后,服务和图标下次登录都起不来,连报警的都没了;opt/<formula> 这个链接 brew 一直维护。别的管理器(nvm、asdf)不会自己删旧版,不动。
+ */
+export declare function stableNode(execPath: string, exists?: (p: string) => boolean): string;
 /**
  * service install 之后开不开家长端:只有这个孩子第一次装时开,下一步就是填百炼、扫码。
  * 别的启动都不开:登录、崩溃重起、升级、重启都不是人要看页面;放进 serve 的话,一直崩就隔 10 秒开一个标签页。
@@ -120,8 +136,18 @@ export interface Health {
     calls?: number;
     /** 百炼配了没有(托盘:没配算有事要处理) */
     bailian?: boolean;
+    /** 跑起来以后百炼出的问题(欠费、key 失效、连不上);没有 → null(machine/bailian.ts) */
+    bailianTrouble?: {
+        kind: string;
+        message: string;
+        fix: string;
+        why?: string;
+        blocked?: boolean;
+    } | null;
     /** npm 上比在跑的这份新的版本;没有 → null(machine/update.ts) */
     latest?: string | null;
+    /** 那个版本写的更新说明 */
+    latestNotes?: string[];
     configError?: string | null;
     /** 问到的是 https 还是 http(这边加的,不是服务回的) */
     scheme?: 'https' | 'http';

package/dist/app/cli/service.js

@@ -88,6 +88,37 @@ export function earlyLogHint(platform, s) {
 export const KEEPER_LOG = 'keeper.log';
 const KEEPER_LOG_MAX = 5 * 1024 * 1024;
 const KEEPER_RESTART_MS = 10_000;
+const sleep = (ms) => new Promise((r) => { setTimeout(r, ms); });
+/**
+ * launchctl bootout 发完信号就回,进程还没退;这时 bootstrap 报 5: Input/output error,服务就停在那儿了(2026-11-07 实测重装 12 次失败 10 次)。
+ * 等它真的卸下来再往下走。launchd 最多等进程 20 秒(ExitTimeOut 缺省),再不走它自己会杀。
+ */
+export async function launchdUnload(host, target, waitMs = 25_000) {
+    await host.run('launchctl', ['bootout', target]);
+    const until = Date.now() + waitMs;
+    while ((await host.run('launchctl', ['print', target])).code === 0 && Date.now() < until)
+        await sleep(200);
+}
+/** 装上;刚卸下的那一下还可能报错,隔一秒再试几次,真的不行才算不行 */
+export async function launchdLoad(host, file, tries = 5) {
+    let r = await host.run('launchctl', ['bootstrap', `gui/${host.uid}`, file]);
+    for (let i = 1; i < tries && r.code !== 0; i++) {
+        await sleep(1000);
+        r = await host.run('launchctl', ['bootstrap', `gui/${host.uid}`, file]);
+    }
+    return r;
+}
+/**
+ * 写进服务文件、登录项的 node。Homebrew 的 process.execPath 是带版本号的路径(实测 /opt/homebrew/Cellar/node/26.12.1_1/bin/node),
+ * brew upgrade 清掉旧版后,服务和图标下次登录都起不来,连报警的都没了;opt/<formula> 这个链接 brew 一直维护。别的管理器(nvm、asdf)不会自己删旧版,不动。
+ */
+export function stableNode(execPath, exists = existsSync) {
+    const m = /^(.*)\/Cellar\/(node(?:@\d+)?)\/[^/]+\/bin\/node$/.exec(execPath);
+    if (!m)
+        return execPath;
+    const opt = `${m[1]}/opt/${m[2]}/bin/node`;
+    return exists(opt) ? opt : execPath;
+}
 /**
  * service install 之后开不开家长端:只有这个孩子第一次装时开,下一步就是填百炼、扫码。
  * 别的启动都不开:登录、崩溃重起、升级、重启都不是人要看页面;放进 serve 的话,一直崩就隔 10 秒开一个标签页。
@@ -267,7 +298,7 @@ export async function installService(host, root, opts = {}) {
     const logDir = serviceLogDir(host, name);
     // Windows 上跑的是看护进程,它再起 serve(那边没有 launchd / systemd 替你拉起)
     const run = platform === 'win32' ? ['service', 'run'] : ['serve'];
-    const spec = { name, label, root, logDir, path: host.env.PATH ?? '/usr/bin:/bin', args: [opts.node ?? process.execPath, opts.bin ?? binPath(), ...run, '--workspace', root, '--log-dir', logDir] };
+    const spec = { name, label, root, logDir, path: host.env.PATH ?? '/usr/bin:/bin', args: [opts.node ?? stableNode(process.execPath), opts.bin ?? binPath(), ...run, '--workspace', root, '--log-dir', logDir] };
     const file = fileOf(host, name);
     await mkdir(serviceDir(host), { recursive: true });
     await mkdir(logDir, { recursive: true });
@@ -284,9 +315,9 @@ export async function installService(host, root, opts = {}) {
     }
     else if (platform === 'darwin') {
         // 先卸下旧的(没装过会报错,不管),再装上;bootstrap 会按 RunAtLoad 马上起
-        await host.run('launchctl', ['bootout', `gui/${host.uid}/${label}`]);
+        await launchdUnload(host, `gui/${host.uid}/${label}`);
         await writeFile(file, launchdPlist(spec));
-        const r = await host.run('launchctl', ['bootstrap', `gui/${host.uid}`, file]);
+        const r = await launchdLoad(host, file);
         if (r.code !== 0)
             throw new UsageError(`launchctl bootstrap 没成:${(r.stderr || r.stdout).trim()}`);
     }
@@ -346,10 +377,10 @@ export async function controlService(host, root, what) {
         const loaded = (await host.run('launchctl', ['print', target])).code === 0;
         if (what === 'stop') {
             if (loaded)
-                await host.run('launchctl', ['bootout', target]);
+                await launchdUnload(host, target);
             return s;
         }
-        const r = loaded ? await host.run('launchctl', what === 'restart' ? ['kickstart', '-k', target] : ['kickstart', target]) : await host.run('launchctl', ['bootstrap', `gui/${host.uid}`, s.file]);
+        const r = loaded ? await host.run('launchctl', what === 'restart' ? ['kickstart', '-k', target] : ['kickstart', target]) : await launchdLoad(host, s.file);
         if (r.code !== 0)
             throw new UsageError(`launchctl 没成:${(r.stderr || r.stdout).trim()}`);
         return s;

package/dist/app/cli/skeleton.d.ts

@@ -12,7 +12,7 @@ export interface ShippedAgent {
 export declare function shippedAgents(dir?: string): Promise<ShippedAgent[]>;
 export declare const GITIGNORE = "# \u8F6C\u5F55\u65E5\u5FD7\u4F53\u79EF\u5927\u3001\u53EF\u4ECE\u5BF9\u8BDD\u7D22\u5F15\u91CD\u5EFA\u5173\u952E\u4FE1\u606F;\u8981\u7559\u5168\u6863\u5C31\u5220\u6389\u4E0B\u9762\u8FD9\u884C\nconversations/**/*.log\n# \u914D\u97F3\u53EF\u91CD\u65B0\u5408\u6210\nconversations/**/*.mp3\n# \u56DE\u653E(cotutor replay)\u662F\u8C03\u63D0\u793A\u8BCD\u4E0E vault \u65F6\u7684\u5BF9\u7167,\u4E0D\u662F\u5B69\u5B50\u7684\u5BF9\u8BDD\nevals/\n# \u505A\u597D\u7684\u8BFE(\u8BFE\u5305\u3001\u89C6\u9891\u8BFE)\u4E0E\u8BFE\u5305\u622A\u56FE:\u4F53\u79EF\u5927,\u6E90\u5728\u5BB6\u957F\u505A\u8BFE\u7684\u5730\u65B9\nbundles/\nlectures/\nsnaps/\n# \u53E3\u8BED\u8BFE(\u5B69\u5B50\u7684\u539F\u58F0\u3001\u7167\u7247)\ntalk/\n# \u4F5C\u4E1A\u7167\u7247(\u5B69\u5B50\u5728\u8001\u5E08\u9875\u4E0A\u62CD\u7684;paths.captures):\u4F53\u79EF\u5927\u3001\u53EA\u662F\u8FD9\u4E00\u8F6E\u7684\u7D20\u6750,\u8BA4\u51FA\u7684\u6587\u5B57\u5728\u65E5\u8BB0\u91CC\ncaptures/\n# \u5BB6\u957F\u5728 workspace \u91CC\u7528 Claude Code \u65F6\u5B83\u7684\u4E2A\u4EBA\u8BBE\u7F6E\n.claude/settings.local.json\n# .cotutor/ \u662F\u673A\u5668\u6587\u4EF6(\u677F\u4E66\u5199\u6CD5\u7F13\u5B58\u3001\u914D\u97F3\u7F13\u5B58\u3001\u4E8C\u7EF4\u7801\u3001\u65E5\u5FD7),\u53EA\u7559\u51FA\u5382 hash \u4E0E schema\n.cotutor/*\n!.cotutor/shipped.json\n!.cotutor/cotutor.schema.json\nnode_modules/\n.DS_Store\n";
 /** 档案模板(paths.profile,缺了才写):cotutor: profile 的那篇,原文整篇进每个话题的第一条 */
-export declare function profileTemplate(name: string): string;
+export declare function profileTemplate(name: string, schoolStart?: string): string;
 /** 参考目录的 README(缺了才写) */
 export declare const REFERENCE_README = "# \u53C2\u8003\n\n\u8FD9\u91CC\u653E\u653F\u7B56\u4E0E\u4F60\u81EA\u5DF1\u7684\u7B14\u8BB0:\u8BB2\u67D0\u7C7B\u9898\u7684\u504F\u597D\u3001\u8584\u5F31\u70B9\u3001\u5FCC\u8BB3\u3001\u6309\u9898\u578B\u6574\u7406\u7684\u4E1C\u897F\u2014\u2014\u968F\u4FBF\u5EFA,\u673A\u5668\u53EA\u8BFB\u4E0D\u5199\u3002\n\u8BA9\u8001\u5E08\u770B\u5230\u7684\u529E\u6CD5:\u5728\u6863\u6848\u6216\u8FD9\u4F4D\u8001\u5E08\u7684\u5165\u53E3\u6587\u4EF6(`cotutor: subject` \u7684\u90A3\u7BC7)\u91CC\u94FE\u8FC7\u53BB(`[[\u627E\u89C4\u5F8B\u586B\u6570]]`);\u8001\u5E08\u62FF\u5230\u8DEF\u5F84,\u8981\u7528\u65F6\u81EA\u5DF1\u8BFB\u3002\n";
 export interface TutorTemplateInput {

package/dist/app/cli/skeleton.js

@@ -55,12 +55,12 @@ node_modules/
 .DS_Store
 `;
 /** 档案模板(paths.profile,缺了才写):cotutor: profile 的那篇,原文整篇进每个话题的第一条 */
-export function profileTemplate(name) {
+export function profileTemplate(name, schoolStart) {
     return `---
 cotutor: profile
 nickname: ${name}
 birthday:
-school_start:
+school_start:${schoolStart ? ` ${schoolStart}` : ''}
 city:
 ---
 

package/dist/app/cli/tray.js

@@ -20,7 +20,7 @@ import { siteUrl } from "../../shared/site-url.js";
 import { isNewer } from "../../shared/upgrade.js";
 import { portHolder } from "./port-holder.js";
 import { RUN_KEY, STARTUP_APPROVED_KEY, encodeLauncher, parseProcs, psArgs, runValue, startupDisabled, winCommandLine } from "./service-windows.js";
-import { binPath, controlService, listServices, parseLaunchctlPrint, probeHealth, wscriptPath, xml } from "./service.js";
+import { binPath, controlService, listServices, parseLaunchctlPrint, probeHealth, wscriptPath, xml, launchdLoad, launchdUnload, stableNode } from "./service.js";
 import { macTrayIcons, windowsTrayIcons } from "./tray-icons.js";
 import { HELPER_NO_SESSION, TRAY_AUMID, TRAY_LABEL, TRAY_RUN_VALUE } from "./tray-ids.js";
 import { MAC_TRAY_SCRIPT } from "./tray-mac.js";
@@ -65,6 +65,8 @@ export function issuesOf(p, o) {
         out.push({ text: 'vault 不在了:看看 cotutor.json 的 paths.vault', fix: { kind: 'open', target: p.root } });
     if (h.bailian === false)
         out.push({ text: '还没填百炼:老师们到不了', fix: { kind: 'open', target: url } });
+    else if (h.bailianTrouble)
+        out.push({ text: h.bailianTrouble.message, fix: { kind: 'open', target: url } });
     if (h.version && h.version !== o.version)
         out.push({ text: `在跑的是 ${h.version},装的是 ${o.version}:重启一下`, fix: { kind: 'restart' } });
     return out;
@@ -540,7 +542,7 @@ export function realTrayDeps(host, dir, file, version) {
     };
 }
 /** 登录项跑的命令 */
-export const trayArgs = (host, o = {}) => [o.node ?? process.execPath, o.bin ?? binPath(), 'tray', 'run', '--dir', trayDir(host)];
+export const trayArgs = (host, o = {}) => [o.node ?? stableNode(process.execPath), o.bin ?? binPath(), 'tray', 'run', '--dir', trayDir(host)];
 /** macOS 的 LaunchAgent:登录就起,崩了拉起,以 0 退(点了退出)不拉 */
 export function trayPlist(args, dir, path) {
     const str = (v) => `<string>${xml(v)}</string>`;
@@ -598,9 +600,9 @@ export async function installTray(host, o = {}) {
     }
     const file = plistFile(host);
     await mkdir(join(host.home, 'Library', 'LaunchAgents'), { recursive: true });
-    await host.run('launchctl', ['bootout', `gui/${host.uid}/${TRAY_LABEL}`]);
+    await launchdUnload(host, `gui/${host.uid}/${TRAY_LABEL}`);
     await writeFile(file, trayPlist(args, dir, host.env.PATH ?? '/usr/bin:/bin'));
-    const r = await host.run('launchctl', ['bootstrap', `gui/${host.uid}`, file]);
+    const r = await launchdLoad(host, file);
     return { file, started: r.code === 0 };
 }
 /** 卸掉:停下、删登录项。remember = 家长说不要(以后 service install 也不再装) */

package/dist/app/cli/update-cmd.d.ts

@@ -0,0 +1,38 @@
+import { type Release } from '../machine/update.ts';
+import { type Health } from './service.ts';
+export interface UpdateService {
+    name: string;
+    kid: string;
+    root: string;
+    port: number;
+    node: string;
+    health: Health | null;
+}
+export interface UpdateDeps {
+    current: string;
+    /** 从仓库跑的:版本跟着 git 走,npm 不管 */
+    fromRepo: boolean;
+    nodeVersion: string;
+    release(): Promise<Release | null>;
+    services(): Promise<UpdateService[]>;
+    health(port: number): Promise<Health | null>;
+    npm(spec: string, registry: string | null): Promise<{
+        code: number;
+        out: string;
+    }>;
+    /** 现在装着的版本:读文件,npm 刚换过 */
+    installed(): string | null;
+    /** 跑新的 bin */
+    cli(args: string[]): Promise<{
+        code: number;
+        out: string;
+    }>;
+    /** 没有后台服务时,在终端里跑 serve 的那个孩子 */
+    workspace(): string | null;
+    stableNode(path: string): string;
+    print(line: string): void;
+}
+export declare function runUpdate(d: UpdateDeps, o?: {
+    anyway?: boolean;
+}): Promise<number>;
+export declare function realUpdateDeps(workspace: () => string | null): UpdateDeps;