cotutor 0.3.0 → 0.4.0

package/dist/app/cli/main.js

@@ -1,5 +1,5 @@
 /**
- * cotutor CLI 入口。命令:init / doctor / serve;全局 --workspace <dir>、--json。
+ * cotutor CLI 入口。命令:init / doctor / serve;全局 --workspace <dir>、--sandbox [--fresh]、--json。
  * exit:0 通过 / 1 体检不过 / 2 用法错误 / 4 内部错误。
  */
 import { createInterface } from 'node:readline/promises';
@@ -7,6 +7,7 @@ import { readFileSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { constants as osConstants } from 'node:os';
+import { basename, join } from 'node:path';
 import { doctorWorkspace } from "./doctor.js";
 import { initWorkspace } from "./init.js";
 import { gradePacks } from "./grades.js";
@@ -19,7 +20,12 @@ import { linkClaudeSkills, upgradeSkills } from "./skills.js";
 import { addTheme, upgradeThemes } from "./themes.js";
 import { patchConfig } from "../workspace.js";
 import { resolveRoot } from "../workspace.js";
-import { serveWorkspace } from "./serve.js";
+import { bindFailure, portHolder, whoHolds } from "./port.js";
+import { httpsFiles, serveWorkspace, siteUrl } from "./serve.js";
+import { teeLogs } from "./serve-log.js";
+import { controlService, earlyLogHint, findService, installService, listServices, probeHealth, realHost, runKeeper, servicePlatform, serviceStatus, tailLog, uninstallService, waitHealthy } from "./service.js";
+import { openSandbox } from "./sandbox.js";
+import { dropTrayIfNoServices, ensureTray, installTray, removeTray, trayDir, trayStatus, traySupported } from "./tray.js";
 import { serveMock } from "../mock/mock.js";
 import { UsageError, loadWorkspace, redactDeep, redactHome, workspaceReport } from "../workspace.js";
 import { USAGE } from "./usage.js";
@@ -67,21 +73,27 @@ function parseArgs(argv, valued) {
     }
     return { cmd, positionals, flags };
 }
-/** 扫码页那一行(地址独占行尾:后面紧跟全角括号的话,终端不把它认成链接);--open-qr 顺手用默认浏览器打开(各系统各自的打开命令,失败不吭声) */
-async function printQr(page, open) {
-    process.stdout.write(`  扫码页 ${page}\n         在这台电脑上打开,iPad / iPhone 用相机扫;--open-qr 顺手打开\n`);
-    if (!open)
-        return;
+/** 用默认浏览器打开(各系统各自的打开命令,失败不吭声) */
+async function openInBrowser(page) {
     const { spawn } = await import('node:child_process');
     const [cmd, args] = process.platform === 'darwin' ? ['open', [page]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', page]] : ['xdg-open', [page]];
     spawn(cmd, args, { stdio: 'ignore', detached: true }).on('error', () => { }).unref();
 }
+/** 打开哪一页的那一行(地址独占行尾:后面紧跟全角括号的话,终端不把它认成链接);--open(旧名 --open-qr)顺手打开 */
+async function printOpen(label, page, hint, open) {
+    process.stdout.write(`  ${label} ${page}\n${' '.repeat(label.length * 2 + 3)}${hint}\n`);
+    if (open)
+        await openInBrowser(page);
+}
+const wantsOpen = (flags) => flags.open === true || flags['open-qr'] === true;
+/** 不用 workspace 的命令:--sandbox 对它们没有意义 */
+const NO_WORKSPACE = ['grades', 'init', 'mock', 'pin', 'cert', 'tray'];
 export async function main(argv) {
     let json = false;
     try {
-        const { cmd, positionals, flags } = parseArgs(argv, ['workspace', 'dir', 'name', 'grade', 'port', 'from', 'runtime', 'force', 'display', 'subject', 'avatar', 'description', 'scenario', 'delay', 'lane', 'job', 'date', 'thread', 'at', 'photo', 'activity', 'param', 'runs', 'only', 'kid-model', 'pin', 'out', 'bundles', 'step', 'voice', 'tutor', 'instruction']);
+        const { cmd, positionals, flags } = parseArgs(argv, ['workspace', 'dir', 'name', 'grade', 'port', 'from', 'runtime', 'force', 'display', 'subject', 'avatar', 'description', 'scenario', 'delay', 'lane', 'job', 'date', 'thread', 'at', 'photo', 'activity', 'param', 'runs', 'only', 'kid-model', 'pin', 'out', 'bundles', 'step', 'voice', 'tutor', 'instruction', 'log-dir', 'lines']);
         json = flags.json === true;
-        const workspace = typeof flags.workspace === 'string' ? flags.workspace : undefined;
+        let workspace = typeof flags.workspace === 'string' ? flags.workspace : undefined;
         // --version / --help 是旗标不是命令,parseArgs 把它们收进 flags,cmd 拿不到,所以在 switch 前处理
         if (flags.version === true || cmd === '-v') {
             process.stdout.write(`${version()}\n`);
@@ -91,6 +103,22 @@ export async function main(argv) {
             process.stdout.write(USAGE);
             return;
         }
+        // --sandbox:要 workspace 的命令都换到它的试用副本(src/app/cli/sandbox.ts),下面照常把它当 --workspace
+        if (flags.fresh === true && flags.sandbox !== true)
+            throw new UsageError('--fresh 只跟 --sandbox 一起用:cotutor serve --sandbox --fresh 重新分出试用 workspace');
+        if (flags.sandbox === true) {
+            if (NO_WORKSPACE.includes(cmd))
+                throw new UsageError(`${cmd} 不用 workspace,--sandbox 没有意义`);
+            if (cmd === 'service')
+                throw new UsageError('试用 workspace 不装后台服务:试的时候 cotutor serve --sandbox 在前台跑');
+            const sb = await openSandbox(workspace, { fresh: flags.fresh === true });
+            workspace = sb.root;
+            if (!json) {
+                process.stderr.write(sb.created ? `分出试用 workspace → ${redactHome(sb.root)}(从 ${redactHome(sb.from)};设置照拷,对话与照片不带,vault 拷了一份)\n` : `试用 workspace ${redactHome(sb.root)}\n`);
+                for (const n of sb.notes)
+                    process.stderr.write(`  ${n}\n`);
+            }
+        }
         switch (cmd) {
             case 'grades': {
                 const packs = (await gradePacks()).map(({ grade }) => ({ grade }));
@@ -137,21 +165,310 @@ export async function main(argv) {
             }
             case 'serve': {
                 const port = typeof flags.port === 'string' ? Number(flags.port) : undefined;
-                const r = await serveWorkspace({ workspace, port, http: flags.http === true });
+                // 后台服务(cotutor service 装的)带 --log-dir:输出按天落文件
+                const logDir = typeof flags['log-dir'] === 'string' ? flags['log-dir'] : undefined;
+                if (logDir)
+                    teeLogs(logDir);
+                // 没接住的错误:记一笔再以非 0 退(后台服务隔 10 秒再起);和 Node 缺省一样会退,只是日志里有时刻和这句
+                const fatal = (what) => (err) => {
+                    process.stderr.write(`cotutor serve: ${what},退出${process.env.COTUTOR_SERVICE ? '(后台服务十秒后自己再起)' : ''}\n${err instanceof Error ? err.stack : String(err)}\n`);
+                    process.exit(1);
+                };
+                process.on('uncaughtException', fatal('没接住的错误'));
+                process.on('unhandledRejection', fatal('没接住的 Promise 错误'));
+                let r;
+                try {
+                    r = await serveWorkspace({ workspace, port, http: flags.http === true });
+                }
+                catch (err) {
+                    const code = err.code;
+                    if (code !== 'EADDRINUSE' && code !== 'EACCES')
+                        throw err;
+                    const busy = err.port ?? port ?? 0;
+                    // 后台服务以 0 退:launchd / systemd 只在崩了时拉起,不一直重试抢端口;系统不让绑的,重试也没用
+                    const service = Boolean(process.env.COTUTOR_SERVICE);
+                    const who = code === 'EADDRINUSE' ? await whoHolds(realHost(), busy) : null;
+                    process.stderr.write(`cotutor serve: ${bindFailure(code, busy, who, service)}\n`);
+                    process.exitCode = service ? 0 : 1;
+                    return;
+                }
                 if (flags.trace === true) {
                     const keep = laneFilter(typeof flags.lane === 'string' ? flags.lane : undefined);
                     r.ctx.runner.onEvent((e) => { if (keep(e.event))
                         process.stdout.write(`${e.tutor} ${e.job} ${formatEvent(e.event)}\n`); });
                 }
                 process.stdout.write(`cotutor serve ${JSON.stringify(workspaceReport(r.ws))}\n`);
+                if (r.ws.sandbox)
+                    process.stdout.write(`  试用:从 ${redactHome(r.ws.sandbox.from)} 分出来,对话、照片、vault 的写入都留在这里,不进孩子的记录;--sandbox --fresh 重新分\n`);
                 for (const w of r.warnings)
                     process.stdout.write(`  ! ${w}\n`);
                 if (!r.https)
-                    process.stdout.write('  ! HTTP:iPad / iPhone 上按住说话要 HTTPS;cotutor cert 建证书后重启即走 HTTPS\n');
-                for (const u of r.urls)
-                    process.stdout.write(`  ${u}\n`);
-                process.stdout.write(`  孩子端 /,家长端 /parent,工作台 /dev(设置、老师团、看原文)\n`);
-                await printQr(r.qrPage, flags['open-qr'] === true);
+                    process.stdout.write('  ! HTTP:平板、手机上按住说话要 HTTPS;cotutor cert 建证书后重启即走 HTTPS\n');
+                // 只给家长端一个入口:孩子的平板扫码、排首页、记录都在里面,工作台从它的右上角进
+                await printOpen('家长端', r.parentPage, '在这台电脑上打开:孩子的平板扫码、排首页、看记录都在里面;--open 顺手打开', wantsOpen(flags));
+                return;
+            }
+            case 'open': {
+                // 不用记端口:读 cotutor.json 打开家长端;--sandbox 开试用的那个(上面已经换了 workspace),--print 只打印不开
+                const ws = loadWorkspace(workspace);
+                const port = ws.config.server.port;
+                const page = siteUrl(httpsFiles(ws) ? 'https' : 'http', 'localhost', port, '/parent/home');
+                const running = Boolean(await probeHealth(port));
+                if (json)
+                    process.stdout.write(`${JSON.stringify({ url: page, running }, null, 2)}\n`);
+                else if (running)
+                    process.stdout.write(`${page}\n`);
+                else
+                    process.stderr.write(`${page} 没在跑(端口 ${port}):${ws.sandbox ? 'cotutor serve --sandbox 起试用的' : 'cotutor service start,或在终端里 cotutor serve'}\n`);
+                if (!running) {
+                    process.exitCode = 1;
+                    return;
+                }
+                if (!json && flags.print !== true)
+                    await openInBrowser(page);
+                return;
+            }
+            case 'tray': {
+                // 菜单栏 / 任务栏图标(tray.ts);tray run 由 bin/cotutor.js 直接走轻入口,不到这里
+                const sub = positionals[0];
+                if (sub !== 'on' && sub !== 'off' && sub !== 'status')
+                    throw new UsageError(`tray 后面跟 on / off / status 之一。\n${USAGE}`);
+                const host = realHost();
+                if (!traySupported(host.platform))
+                    throw new UsageError(`${host.platform} 上没做托盘图标(GNOME 缺省不显示托盘):cotutor service status 看服务状态`);
+                const word = host.platform === 'darwin' ? '菜单栏图标' : '任务栏图标';
+                if (sub === 'on') {
+                    if (!(await listServices(host)).length)
+                        throw new UsageError('还没装后台服务,图标没东西可看:cotutor service install 会一起装上图标');
+                    const r = await installTray(host);
+                    if (json)
+                        process.stdout.write(`${JSON.stringify(redactDeep(r), null, 2)}\n`);
+                    else
+                        process.stdout.write(r.started ? `${word}起来了:登录后自己出现,点它看状态、打开家长端${host.platform === 'win32' ? '(新图标先收在任务栏右下角的 ^ 里)' : ''}\n` : `${word}的登录项写好了,这个会话里没起来,下次登录出现\n`);
+                    return;
+                }
+                if (sub === 'off') {
+                    const had = await removeTray(host, { remember: true });
+                    if (json)
+                        process.stdout.write(`${JSON.stringify({ removed: had })}\n`);
+                    else
+                        process.stdout.write(`${had ? `关了${word}` : `${word}本来就没开`};后台服务不受影响,以后 service install 也不再带上。要回来:cotutor tray on\n`);
+                    return;
+                }
+                const st = await trayStatus(host);
+                if (json) {
+                    process.stdout.write(`${JSON.stringify(redactDeep({ ...st, dir: trayDir(host) }), null, 2)}\n`);
+                    return;
+                }
+                process.stdout.write(!st.installed ? `${word}:没开${st.off ? '(家长关掉的)' : ''};cotutor tray on\n` : `${word}:${st.running ? `在跑,pid ${st.pid ?? '?'}` : '没在跑(点过退出就是这样,下次登录回来)'}\n`);
+                if (st.autostart === false)
+                    process.stdout.write('  ! 下次登录不会自己起来:登录项被关掉或删掉了(任务管理器的「启动应用」、杀毒软件)。要它:cotutor tray on\n');
+                if (st.installed)
+                    process.stdout.write(`  日志 ${redactHome(join(trayDir(host), 'tray.log'))}\n`);
+                return;
+            }
+            case 'service': {
+                const sub = positionals[0];
+                // 看护进程(Windows 的启动器起的,不是给人敲的):起 serve,崩了再起
+                if (sub === 'run') {
+                    const logDir = flags['log-dir'];
+                    if (typeof workspace !== 'string' || typeof logDir !== 'string')
+                        throw new UsageError('service run 要 --workspace 与 --log-dir');
+                    process.exitCode = await runKeeper({ root: workspace, logDir, label: `cotutor-${basename(logDir)}` });
+                    return;
+                }
+                const SUBS = ['install', 'uninstall', 'start', 'stop', 'restart', 'status', 'logs'];
+                if (!sub || !SUBS.includes(sub))
+                    throw new UsageError(`service 后面跟 ${SUBS.join(' / ')} 之一。\n${USAGE}`);
+                const host = realHost();
+                const platform = servicePlatform(host.platform);
+                const ws = loadWorkspace(workspace);
+                if (ws.sandbox)
+                    throw new UsageError('试用 workspace 不装后台服务:试的时候 cotutor serve --sandbox 在前台跑');
+                const root = ws.root;
+                const port = ws.config.server.port;
+                const scheme = httpsFiles(ws) ? 'https' : 'http';
+                const parentPage = siteUrl(scheme, 'localhost', port, '/parent/home');
+                const when = (iso) => { const d = new Date(iso); const ago = Math.round((Date.now() - d.getTime()) / 60_000); return `${localDate(d)} ${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}(${ago < 60 ? `${ago} 分钟` : ago < 2880 ? `${Math.round(ago / 60)} 小时` : `${Math.round(ago / 1440)} 天`}前)`; };
+                // 后台读不到 vault(macOS 拦着后台进程读「文稿」、iCloud 云盘)、版本对不上:装完、起完、看状态都提
+                const notes = (h) => {
+                    const out = [];
+                    if (h?.vault === 'denied')
+                        out.push(platform === 'darwin'
+                            ? `! 后台服务读不到 vault(${redactHome(ws.paths.vault)}):macOS 不让后台进程读「文稿」「桌面」和 iCloud 云盘,也不弹窗问。系统设置 › 隐私与安全性 › 完全磁盘访问权限,点 + 加上 ${process.execPath}(或把 vault 挪出这几处),然后 cotutor service restart`
+                            : `! 后台服务读不到 vault(${redactHome(ws.paths.vault)}):看看这个目录的权限,然后 cotutor service restart`);
+                    if (h?.version && h.version !== version())
+                        out.push(`! 在跑的是 ${h.version},装的是 ${version()}:cotutor service restart 换上新的`);
+                    return out;
+                };
+                const tellLog = async (dir) => {
+                    const t = dir ? await tailLog(dir, 15) : null;
+                    if (t) {
+                        process.stdout.write(`  ${redactHome(t.file)} 最后几行:\n`);
+                        for (const l of t.lines)
+                            process.stdout.write(`    ${l}\n`);
+                    }
+                    else if (dir)
+                        process.stdout.write(`  日志还没有;起来之前的输出看 ${redactHome(earlyLogHint(platform, { label: `cotutor-${basename(dir)}`, logDir: dir }))}\n`);
+                };
+                if (sub === 'install') {
+                    const before = await probeHealth(port);
+                    const had = await findService(host, root);
+                    if (before && before.mode !== 'service')
+                        throw new UsageError(`端口 ${port} 上有一个 cotutor serve 在终端里跑着${before.pid ? `(pid ${before.pid})` : ''}:先关掉它(那个终端里 Ctrl-C),再 cotutor service install`);
+                    if (before && !had)
+                        throw new UsageError(`端口 ${port} 上已经是另一个 workspace 的后台服务:两个孩子各用各的端口(cotutor.json 的 server.port)`);
+                    const r = await installService(host, root);
+                    const h = await waitHealthy(port, 20_000, before?.started);
+                    // 菜单栏图标一起装:它出问题不能让服务也算没装好
+                    let tray = 'skipped';
+                    if (flags['no-tray'] !== true) {
+                        try {
+                            tray = await ensureTray(host);
+                        }
+                        catch {
+                            tray = 'failed';
+                        }
+                    }
+                    if (json) {
+                        process.stdout.write(`${JSON.stringify(redactDeep({ ...r, healthy: Boolean(h), health: h, tray }), null, 2)}\n`);
+                        return;
+                    }
+                    process.stdout.write(`${r.replaced ? '重装了' : '装好了'}后台服务 ${r.spec.label}(${redactHome(r.file)})\n`);
+                    process.stdout.write(`  登录这台电脑后自己起来,崩了隔 10 秒再起;关了终端照样跑。日志 ${redactHome(join(r.spec.logDir, '<日期>.log'))},留 14 天\n`);
+                    if (platform !== 'linux')
+                        process.stdout.write(`  电脑睡着时平板连不上:有通话时 cotutor 拦着它闲置睡眠,别的时候看系统设置(cotutor doctor 会提);合盖照样睡\n`);
+                    if (platform === 'win32') {
+                        process.stdout.write('  没有黑窗口。任务管理器的「启动应用」里看不到 cotutor 这个名字,显示的是 Windows Based Script Host;登录后约一分钟起来,在不在跑看 cotutor service status\n');
+                        // 平板连不连得进来:Windows 第一次监听时弹一次「允许访问」,点了取消(或没看见)就再也连不上;不在终端里跑了,这里不说就没地方说了
+                        const { judgeFirewall, probeFirewall } = await import("./firewall.js");
+                        const state = await probeFirewall(port);
+                        const v = state && judgeFirewall(state, port, process.execPath);
+                        if (v && !v.ok)
+                            process.stdout.write(`  ! ${v.detail}\n    修复:${v.fix ?? ''}\n    弄好以后 cotutor doctor 再查一次\n`);
+                    }
+                    if (platform === 'linux') {
+                        const lg = await host.run('loginctl', ['show-user', process.env.USER ?? '', '-p', 'Linger']);
+                        if (/Linger=no/.test(lg.stdout))
+                            process.stdout.write(`  ! 现在只在你登录着时跑;不登录也要跑:sudo loginctl enable-linger ${process.env.USER ?? '<用户名>'}\n`);
+                    }
+                    if (tray === 'started' || tray === 'later')
+                        process.stdout.write(`  ${platform === 'darwin' ? '菜单栏' : '任务栏'}多了 cotutor 图标:不用开终端就能看状态、打开家长端${tray === 'later' ? '(这个会话里没起来,下次登录出现)' : platform === 'win32' ? '(新图标先收在右下角的 ^ 里)' : ''};不要它:cotutor tray off\n`);
+                    else if (tray === 'failed')
+                        process.stdout.write('  ! 图标没装上,服务不受影响;cotutor tray on 再试\n');
+                    if (h) {
+                        await printOpen('家长端', parentPage, '孩子的平板扫码、排首页、看记录都在里面', wantsOpen(flags));
+                        for (const n of notes(h))
+                            process.stdout.write(`${n}\n`);
+                    }
+                    else {
+                        process.stdout.write(`! 装上了,但 20 秒内没答应(端口 ${port})。cotutor service logs 看看:\n`);
+                        await tellLog(r.spec.logDir);
+                        process.exitCode = 1;
+                    }
+                    return;
+                }
+                if (sub === 'uninstall') {
+                    const s = await uninstallService(host, root);
+                    // 这是最后一个服务:图标也没事可做了
+                    const trayGone = s ? await dropTrayIfNoServices(host).catch(() => false) : false;
+                    if (json) {
+                        process.stdout.write(`${JSON.stringify(redactDeep({ removed: s, trayRemoved: trayGone }), null, 2)}\n`);
+                        return;
+                    }
+                    process.stdout.write(s ? `卸了后台服务 ${s.label};日志留在 ${redactHome(s.logDir ?? '')},不要了自己删\n要在终端里跑:cotutor serve\n` : '这个 workspace 没装后台服务\n');
+                    return;
+                }
+                if (sub === 'start' || sub === 'stop' || sub === 'restart') {
+                    const before = sub === 'stop' ? null : await probeHealth(port);
+                    if (sub === 'start' && before?.mode === 'service') {
+                        process.stdout.write(`后台服务已经在跑了(pid ${before.pid ?? '?'})\n`);
+                        return;
+                    }
+                    if (sub !== 'stop' && before && before.mode !== 'service')
+                        throw new UsageError(`端口 ${port} 上有一个 cotutor serve 在终端里跑着:先关掉它(Ctrl-C)`);
+                    const s = await controlService(host, root, sub);
+                    if (sub === 'stop') {
+                        process.stdout.write(`停了 ${s.label}(下次${platform === 'linux' ? '开机' : '登录'}又会自己起来;一直不要它:cotutor service uninstall)\n`);
+                        return;
+                    }
+                    const h = await waitHealthy(port, 20_000, before?.started);
+                    if (h) {
+                        process.stdout.write(`${sub === 'start' ? '起来了' : '重起了'}:pid ${h.pid ?? '?'},版本 ${h.version ?? '?'}\n`);
+                        for (const n of notes(h))
+                            process.stdout.write(`${n}\n`);
+                    }
+                    else {
+                        process.stdout.write(`! 20 秒内没答应(端口 ${port}):\n`);
+                        await tellLog(s.logDir);
+                        process.exitCode = 1;
+                    }
+                    return;
+                }
+                if (sub === 'status') {
+                    const st = await serviceStatus(host, root, port);
+                    // 没答应时看看是不是别的程序占着:后台服务遇到这种情况只写一句日志就不起了,这里要说得出来
+                    const holder = st.health ? null : await portHolder(host, port);
+                    if (json) {
+                        process.stdout.write(`${JSON.stringify(redactDeep({ ...st, portHolder: holder, version: version(), parentPage }), null, 2)}\n`);
+                        return;
+                    }
+                    if (!st.installed)
+                        process.stdout.write('后台服务:没装(cotutor service install)\n');
+                    else
+                        process.stdout.write(`后台服务:装了 ${st.installed.label}(${redactHome(st.installed.file)})\n  ${st.running ? `在跑:pid ${st.pid ?? '?'}` : `没在跑${st.lastExit ? `(上次退出:${st.lastExit})` : ''};cotutor service start`}\n`);
+                    const h = st.health;
+                    if (h)
+                        process.stdout.write(`  端口 ${port} 答应:${h.mode === 'service' ? '后台服务' : `终端里的 cotutor serve(pid ${h.pid ?? '?'})`},版本 ${h.version ?? '?'},起来于 ${when(h.started)}\n  家长端 ${parentPage}\n`);
+                    else
+                        process.stdout.write(holder ? `  端口 ${port} 没答应,被占着:${holder.name}(pid ${holder.pid})在用。腾出来以后 cotutor service start;或改 cotutor.json 的 server.port,平板要重新扫码、重加主屏幕图标\n` : `  端口 ${port} 没答应\n`);
+                    for (const n of notes(h))
+                        process.stdout.write(`${n}\n`);
+                    if (st.autostart === false)
+                        process.stdout.write('  ! 下次登录不会自己起来:登录项被关掉或删掉了(任务管理器的「启动应用」、杀毒软件)。要它:cotutor service install 再装一次\n');
+                    if (st.installed?.logDir)
+                        process.stdout.write(`  日志 ${redactHome(st.installed.logDir)}(cotutor service logs)\n`);
+                    if (st.installed && !h)
+                        await tellLog(st.installed.logDir);
+                    return;
+                }
+                // logs
+                const s = await findService(host, root);
+                if (!s?.logDir)
+                    throw new UsageError('这个 workspace 没装后台服务,没有日志;终端里跑的 cotutor serve 输出就在那个终端里');
+                const n = typeof flags.lines === 'string' ? Number(flags.lines) : 50;
+                if (!(Number.isInteger(n) && n > 0))
+                    throw new UsageError('--lines 要是正整数');
+                const t = await tailLog(s.logDir, n);
+                if (t)
+                    for (const l of t.lines)
+                        process.stdout.write(`${l}\n`);
+                else
+                    process.stdout.write(`还没有日志;起来之前的输出看 ${redactHome(earlyLogHint(platform, s))}\n`);
+                if (flags.follow === true) {
+                    const { open: openFile, stat: statFile } = await import('node:fs/promises');
+                    const { logFileFor } = await import("./serve-log.js");
+                    let file = t?.file ?? logFileFor(s.logDir, new Date());
+                    let pos = (await statFile(file).catch(() => null))?.size ?? 0;
+                    setInterval(() => {
+                        void (async () => {
+                            const today = logFileFor(s.logDir, new Date());
+                            if (today !== file && (await statFile(today).catch(() => null))) {
+                                file = today;
+                                pos = 0;
+                            }
+                            const st = await statFile(file).catch(() => null);
+                            if (!st || st.size <= pos)
+                                return;
+                            const fh = await openFile(file, 'r');
+                            const buf = Buffer.alloc(st.size - pos);
+                            await fh.read(buf, 0, buf.length, pos);
+                            await fh.close();
+                            pos = st.size;
+                            process.stdout.write(buf);
+                        })();
+                    }, 500);
+                }
                 return;
             }
             case 'mock': {
@@ -170,11 +487,11 @@ export async function main(argv) {
                     process.once(s, () => process.exit(128 + osConstants.signals[s]));
                 process.stdout.write(`cotutor mock 场景 ${scenario}(不经真实老师与百炼:老师都走实时老师页,假嘴念静音的声音)\n`);
                 if (!r.https)
-                    process.stdout.write('  ! HTTP:iPad / iPhone 上按住说话要 HTTPS;cotutor cert 建证书后重启即走 HTTPS\n');
+                    process.stdout.write('  ! HTTP:平板、手机上按住说话要 HTTPS;cotutor cert 建证书后重启即走 HTTPS\n');
                 for (const u of r.urls)
                     process.stdout.write(`  ${u}\n`);
                 process.stdout.write('  孩子端 /,家长端 /parent;直接开某位老师:/?tutor=chinese-tutor\n');
-                await printQr(r.qrPage, flags['open-qr'] === true);
+                await printOpen('扫码页', r.qrPage, '在这台电脑上打开,平板、手机用相机扫;--open 顺手打开', wantsOpen(flags));
                 return;
             }
             case 'add': {
@@ -227,7 +544,7 @@ export async function main(argv) {
                             process.stdout.write(`✓ ${st.item.padEnd(24)} ${st.note ?? '建好了'}\n`);
                         process.stdout.write(dryRun
                             ? `\n${r.gaps.length} 项要改,还没动文件:cotutor upgrade --config 真改(只加缺的、删不再用的出厂段,你改过的值不动)\n`
-                            : `\n改了 ${r.gaps.length} 项到 ${redactHome(r.file)};服务在跑的话不用重启(按 mtime 热重载)。\n`);
+                            : `\n改了 ${r.gaps.length} 项到 ${redactHome(r.file)};服务在跑的话不用重启(改了就热重载)。\n`);
                     }
                     return;
                 }
@@ -248,7 +565,7 @@ export async function main(argv) {
                         process.stdout.write(`${s.action === 'kept' ? '!' : '✓'} ${s.item.padEnd(24)} ${s.note ?? ''}\n`);
                     if (link.action !== 'exists')
                         process.stdout.write(`${link.action === 'kept' ? '!' : '✓'} ${link.item.padEnd(24)} ${link.note ?? ''}\n`);
-                    const word = { upgraded: '已换新', latest: '已是最新', 'kept-custom': '自定义,保留', forced: '已覆盖(原文 .bak)', installed: '补上了', retired: '不再出厂,删了' };
+                    const word = { upgraded: '已换新', latest: '已是最新', 'kept-custom': '自定义,保留', forced: '已覆盖(原文 .bak)', installed: '补上了', retired: '不再出厂,删了', renamed: '改了名' };
                     for (const s of skillSteps)
                         process.stdout.write(`${s.action === 'kept-custom' ? '!' : '✓'} skill ${s.name.padEnd(18)} ${word[s.action]}${s.basedOn && s.action !== 'latest' ? `(基于 ${s.basedOn})` : ''}${s.machine ? '(机器件)' : ''}\n`);
                     for (const s of themeSteps)
@@ -264,7 +581,7 @@ export async function main(argv) {
                         }
                     }
                     for (const s of activitySteps) {
-                        process.stdout.write(`${s.action === 'kept-custom' ? '!' : '✓'} activity ${s.key.padEnd(18)} ${word[s.action]}${s.basedOn && s.action !== 'latest' ? `(基于 ${s.basedOn})` : ''}\n`);
+                        process.stdout.write(`${s.action === 'kept-custom' ? '!' : '✓'} activity ${s.key.padEnd(18)} ${word[s.action]}${s.from ? `(原来叫「${s.from}」)` : ''}${s.basedOn && s.action !== 'latest' ? `(基于 ${s.basedOn})` : ''}\n`);
                         if (s.diff?.length) {
                             process.stdout.write(`    你的 vs 新版(- 你的 / + 新版),想用新版:cotutor upgrade --force ${s.key}\n`);
                             for (const l of s.diff.slice(0, 40))
@@ -375,7 +692,13 @@ export async function main(argv) {
                     process.stdout.write(`${JSON.stringify(redactDeep(r), null, 2)}\n`);
                 else {
                     process.stdout.write(`证书:${redactHome(r.cert)}\n私钥:${redactHome(r.key)}\n主机:${r.hosts.join(' ')}\n`);
-                    process.stdout.write(`iPad / iPhone 要先信任这台机器的根证书:把 ${redactHome(r.caRoot)}/rootCA.pem 隔空投送过去 → 设置里安装描述文件 → 通用 › 关于本机 › 证书信任设置里**把开关打开**(装了不等于信任,每台设备各做一次);然后重启 cotutor serve,在这台电脑上打开它打印的扫码页,用相机扫(个别设备扫完一直转圈,就改手输打印的 https://<局域网 IP>:<端口>/)。详见 docs/iPad与iPhone.md\n`);
+                    // 根证书怎么到设备上:Mac 隔空投送;Windows 等没有,用微信、邮件或网盘传
+                    const rootCa = redactHome(join(r.caRoot, 'rootCA.pem'));
+                    const send = process.platform === 'darwin' ? '隔空投送过去' : '用微信、邮件或网盘传到设备上';
+                    process.stdout.write(`平板、手机要先信任这台机器的根证书 ${rootCa}(每台设备各做一次):\n`);
+                    process.stdout.write(`  iPad / iPhone:${send} → 设置里安装描述文件 → 通用 › 关于本机 › 证书信任设置里**把开关打开**(装了不等于信任)\n`);
+                    process.stdout.write(`  安卓:${process.platform === 'darwin' ? '传到设备上' : send} → 设置里搜「CA 证书」,按提示安装(各家菜单不一样,会提示「网络可能受到监控」)\n`);
+                    process.stdout.write(`然后 cotutor service restart(在终端里跑的就重开 cotutor serve),cotutor open 打开家长端,用相机扫「扫码打开」那张。地址认电脑名,换 Wi-Fi、IP 变了都不用重签;改了电脑名才要重跑这条。详见 docs/iPad与iPhone.md\n`);
                 }
                 return;
             }
@@ -662,8 +985,7 @@ export async function main(argv) {
                         throw new UsageError(`--photo ${f} 太大(${(data.length / 1e6).toFixed(1)} MB,最多 ${PHOTO_MAX_BYTES / 1e6} MB);先缩,如 sips -s format jpeg -Z 2000 ${f} --out x.jpg`);
                     photos.push(await writeCapture(ws, new Date(), data, ext === 'png' ? 'png' : 'jpg'));
                 }
-                // 不预热:send 跑完就退,备用进程会把这个进程挂住(WARM_IDLE_MS)
-                const ctx = createContext(ws, { warm: false });
+                const ctx = createContext(ws);
                 // 现场打印每道工序的事件(--quiet / --json 不打);事件同时落在 events.jsonl,事后 cotutor trace 能回放
                 if (!json && flags.quiet !== true) {
                     const keep = laneFilter(typeof flags.lane === 'string' ? flags.lane : undefined);
@@ -671,7 +993,8 @@ export async function main(argv) {
                         process.stdout.write(`${formatEvent(e.event)}\n`); });
                 }
                 const activity = activityName ? await activityRunFor(ws.root, tutor, activityName, typeof flags.param === 'string' ? flags.param : '') : undefined;
-                const started = await ctx.runner.send(tutor, { from: from, text, runtime: typeof flags.runtime === 'string' ? flags.runtime : undefined, newThread: flags.new === true || Boolean(activity), ...(photos.length ? { photos } : {}), ...(activity ? { activity } : {}) });
+                // 孩子的话照实时写(同孩子端:上下文包带 live:、不补提问卡、讲稿不截;嘴不在,接住与打断不带);--from system 不算
+                const started = await ctx.runner.send(tutor, { from: from, text, runtime: typeof flags.runtime === 'string' ? flags.runtime : undefined, newThread: flags.new === true || Boolean(activity), ...(photos.length ? { photos } : {}), ...(activity ? { activity } : {}), ...(from === 'kid' ? { live: {} } : {}) });
                 if (!json)
                     process.stdout.write(`→ ${tutor} ${started.date} ${started.job} 话题 ${started.thread}(${started.plan.runtime}${started.plan.resume ? ',resume ' + started.plan.session : ',新会话'})…\n`);
                 const index = await started.done;

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

@@ -1,24 +1,15 @@
 import { type InstallStep } from './tutors.ts';
 /** section:出厂模板里有的整段(dictation 这种后加的),你这份没有;retired:出厂写进去、应用已经不读的整段,补缺时删掉 */
-export type GapKind = 'tutor' | 'runtime' | 'flag' | 'cards' | 'section' | 'retired';
+export type GapKind = 'tutor' | 'runtime' | 'cards' | 'section' | 'retired';
 export interface ConfigGap {
     kind: GapKind;
-    /** 点位:tutors.math-tutor / runtimes.qwen / runtimes.qwen.run */
+    /** 点位:tutors.math-tutor / runtimes.api-flash / dictation */
     path: string;
     /** 人话:缺的是什么、补上有什么用 */
     detail: string;
     /** 补上之后这个点位的值(--dry-run 打印、页面提示用);retired 是 undefined(删掉) */
     value: unknown;
 }
-/**
- * 把出厂模板里有、这份没有的旗标插进来,**位置照出厂模板**:
- * 插到「出厂模板里排在它前面、这份也有」的那个旗标之后;一个都找不到就放末尾。
- * 已经有的旗标一律不碰——值被家长改过(预算 2 → 5)是她的决定。
- */
-export declare function insertMissingFlags(mine: readonly string[], factory: readonly string[]): {
-    argv: string[];
-    added: string[];
-};
 /**
  * 这份 cotutor.json 比出厂模板少了什么。只看「有没有」,不看值——值是家长的。
  * 注意:出厂老师是家长手动从 tutors 里删掉的(页面删不了出厂老师),这里也会当成缺,

package/dist/app/cli/migrate.js

@@ -4,8 +4,7 @@
  * cotutor.json 是**政策文件**:init 只在缺失时写模板,已有的那份机器永不改(家长的决定不由机器代做)。
  * 代价是包更新带来的新出厂件不会自己出现在老 workspace 里,而且「没有」的表现是**静默**的——
  * 所以有这一层:把「出厂模板有、你这份没有」算出来(doctor 的 `config.migrate` 点名、家长端设置页顶部提示),
- * `cotutor upgrade --config` 只**补缺**——加缺的键、往命令模板里插缺的旗标;家长写过的值一个都不动
- * (改小的预算、加过的 `-m qwen3.8-flash`、换掉的 default 运行时全都原样留着)。
+ * `cotutor upgrade --config` 只**补缺**——加缺的键;家长写过的值一个都不动(改小的预算、换掉的 default 运行时全都原样留着)。
  * 唯一删的是 RETIRED 里点了名的出厂段(机器写进去、应用已经不读的,如 2026-10-31 的 tts);家长自己加的键不在表里,不碰。
  *
  * 差异是**现算的**:拿家长自己的 slug / name / port 生成一份出厂模板,和她这份逐项比,
@@ -19,42 +18,6 @@ import { configTemplate, shippedAgents } from "./skeleton.js";
 import { installTutors } from "./tutors.js";
 import { CONFIG_FILE, ConfigError, readJson } from "../workspace.js";
 const isObj = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
-/** 命令模板里一个旗标带几个词:`--output-format stream-json` 是两个,`--include-partial-messages` 是一个(值不以 - 打头) */
-function flagSpan(argv, i) {
-    const span = [argv[i]];
-    for (let j = i + 1; j < argv.length && !argv[j].startsWith('-'); j++)
-        span.push(argv[j]);
-    return span;
-}
-/**
- * 把出厂模板里有、这份没有的旗标插进来,**位置照出厂模板**:
- * 插到「出厂模板里排在它前面、这份也有」的那个旗标之后;一个都找不到就放末尾。
- * 已经有的旗标一律不碰——值被家长改过(预算 2 → 5)是她的决定。
- */
-export function insertMissingFlags(mine, factory) {
-    const argv = [...mine];
-    const added = [];
-    for (let i = 0; i < factory.length; i++) {
-        const tok = factory[i];
-        if (!tok.startsWith('-') || argv.includes(tok))
-            continue;
-        const span = flagSpan(factory, i);
-        let at = argv.length;
-        for (let j = i - 1; j >= 0; j--) {
-            const prev = factory[j];
-            if (!prev.startsWith('-'))
-                continue;
-            const k = argv.indexOf(prev);
-            if (k === -1)
-                continue;
-            at = k + flagSpan(argv, k).length;
-            break;
-        }
-        argv.splice(at, 0, ...span);
-        added.push(...span);
-    }
-    return { argv, added };
-}
 /** 出厂模板:拿这份配置自己的 slug / name / port 生成,免得差异里混进「孩子叫什么」这种无关项 */
 async function factoryConfig(raw, agentsDir) {
     const kid = isObj(raw.kid) ? raw.kid : {};
@@ -98,27 +61,6 @@ export async function configGaps(raw, agentsDir) {
             continue;
         gaps.push({ kind: 'runtime', path: `runtimes.${name}`, detail: `出厂运行时 ${name} 不在 runtimes 里`, value: rt });
     }
-    for (const [name, rt] of Object.entries(factoryRuntimes)) {
-        if (name === 'default' || !isObj(rt))
-            continue;
-        const mine = mineRuntimes[name];
-        if (!isObj(mine))
-            continue; // 整个运行时都缺,上面那轮已经报了
-        // 出厂模板换了说话方式(消息改走 stdin)而你的改过:逐个补旗标会拼出过不了契约的模板,不动(家长的决定)
-        if (rt.stdin && !mine.stdin)
-            continue;
-        for (const key of ['run', 'resume']) {
-            const f = rt[key];
-            const u = mine[key];
-            if (!Array.isArray(f) || !Array.isArray(u))
-                continue;
-            const { argv, added } = insertMissingFlags(u, f);
-            if (!added.length)
-                continue;
-            const what = `缺出厂旗标 ${added.join(' ')}`;
-            gaps.push({ kind: 'flag', path: `runtimes.${name}.${key}`, detail: `${name} 的 ${key} 命令模板${what}`, value: argv });
-        }
-    }
     // 后加的整段(2026-10-10 听写的拍照认词要求):写进文件家长才看得见、改得动;已经有这一段就不碰
     for (const key of SECTIONS) {
         if (key in raw || !(key in factory))

package/dist/app/cli/port-holder.d.ts

@@ -0,0 +1,16 @@
+import type { ServiceHost } from './service.ts';
+export interface PortHolder {
+    pid: number;
+    name: string;
+}
+/** lsof -Fpc 的输出:一行 p<pid>,一行 c<命令名> */
+export declare function parseLsof(out: string): PortHolder | null;
+/**
+ * 谁在监听(Windows):只认对端端口是 0,不看 State。2026-11-06 Windows 11 build 26300 上监听的 socket 状态是乱的:
+ * netstat 显示 CLOSED、FIN_WAIT_1,-State Listen 查不到,读 State 还可能抛异常
+ */
+export declare function holderScript(port: number): string;
+/** 上面那段的输出;坏的、空的当不知道 */
+export declare function parseHolder(text: string): PortHolder | null;
+/** 谁在监听这个端口;查不到(别人的进程、没装 lsof)→ null */
+export declare function portHolder(host: Pick<ServiceHost, 'platform' | 'run'>, port: number): Promise<PortHolder | null>;