cotutor 0.2.0 → 0.4.0

package/dist/app/cli/main.js

@@ -0,0 +1,1038 @@
+/**
+ * cotutor CLI 入口。命令:init / doctor / serve;全局 --workspace <dir>、--sandbox [--fresh]、--json。
+ * exit:0 通过 / 1 体检不过 / 2 用法错误 / 4 内部错误。
+ */
+import { createInterface } from 'node:readline/promises';
+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";
+import { makeCert } from "./cert.js";
+import { PIN_RE, USER_PIN_FILE, clearPin, readPin, setPin } from "../http/access.js";
+import { addTutorFile, upgradeTutors } from "./tutors.js";
+import { activityRunFor, checkActivities, upgradeActivities } from "./activities.js";
+import { configGapsOf, migrateLayout, upgradeConfig } from "./migrate.js";
+import { linkClaudeSkills, upgradeSkills } from "./skills.js";
+import { addTheme, upgradeThemes } from "./themes.js";
+import { patchConfig } from "../workspace.js";
+import { resolveRoot } from "../workspace.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";
+import { PHOTO_MAX_BYTES, createContext } from "../http/app.js";
+import { MESSAGE_FROM } from "../../schema/index.js";
+import { formatEvent, laneFilter, parseEvents } from "../../runtime/journal/events.js";
+import { localDate } from "../../shared/time.js";
+import { sumTokens, tokenText } from "../../shared/tokens.js";
+import { rateThread, writeCapture } from "../../runtime/journal/store.js";
+function version() {
+    const pkg = JSON.parse(readFileSync(fileURLToPath(new URL('../../../package.json', import.meta.url)), 'utf8'));
+    return pkg.version;
+}
+/** 能不能问人:真终端、不要 JSON */
+function interactive(json) {
+    return !json && Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+function parseArgs(argv, valued) {
+    const flags = {};
+    const positionals = [];
+    let cmd;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith('--')) {
+            const key = a.slice(2);
+            if (valued.includes(key)) {
+                const next = argv[i + 1];
+                // --force 的值可省:upgrade --force <老师>,home publish --force
+                if ((next === undefined || next.startsWith('--')) && key === 'force') {
+                    flags[key] = true;
+                    continue;
+                }
+                if (next === undefined || next.startsWith('--'))
+                    throw new UsageError(`选项 --${key} 需要一个值。\n${USAGE}`);
+                flags[key] = next;
+                i++;
+            }
+            else
+                flags[key] = true;
+        }
+        else if (cmd === undefined)
+            cmd = a;
+        else
+            positionals.push(a);
+    }
+    return { cmd, positionals, flags };
+}
+/** 用默认浏览器打开(各系统各自的打开命令,失败不吭声) */
+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', 'log-dir', 'lines']);
+        json = flags.json === true;
+        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`);
+            return;
+        }
+        if (flags.help === true || cmd === undefined || cmd === '-h') {
+            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 }));
+                process.stdout.write(json ? `${JSON.stringify(packs, null, 2)}\n` : `可安装的教学包:${packs.map((p) => `${p.grade} 年级`).join('、') || '无'}\n`);
+                return;
+            }
+            case 'init': {
+                const slug = positionals[0];
+                if (!slug || !/^[a-z0-9][a-z0-9-]*$/.test(slug))
+                    throw new UsageError(`init 需要一个 slug(小写字母数字连字符,是短名不是真名),如 cotutor init ming。\n${USAGE}`);
+                const port = typeof flags.port === 'string' ? Number(flags.port) : undefined;
+                if (port !== undefined && !(Number.isInteger(port) && port > 0 && port < 65536))
+                    throw new UsageError('--port 要是 1–65535 的整数');
+                if (flags.grade !== undefined && (typeof flags.grade !== 'string' || !/^[1-6]$/.test(flags.grade)))
+                    throw new UsageError('--grade 要是 1–6 的整数,如 --grade 2');
+                const r = await initWorkspace({ slug, grade: flags.grade === undefined ? undefined : Number(flags.grade), dir: typeof flags.dir === 'string' ? flags.dir : undefined, name: typeof flags.name === 'string' ? flags.name : undefined, port });
+                if (json)
+                    process.stdout.write(`${JSON.stringify(redactDeep(r), null, 2)}\n`);
+                else {
+                    process.stdout.write(`cotutor init → ${redactHome(r.root)}\n`);
+                    for (const s of r.steps)
+                        process.stdout.write(`  ${s.action.padEnd(7)} ${s.item}${s.note ? `  (${s.note})` : ''}\n`);
+                    process.stdout.write('下一步:\n');
+                    for (const s of r.suggestions)
+                        process.stdout.write(`  - ${s}\n`);
+                }
+                return;
+            }
+            case 'doctor': {
+                const r = await doctorWorkspace(workspace, { live: flags.live === true });
+                if (json)
+                    process.stdout.write(`${JSON.stringify(redactDeep(r), null, 2)}\n`);
+                else {
+                    for (const c of r.checks) {
+                        process.stdout.write(`${c.ok ? '✓' : c.required ? '✗' : '!'} ${c.name.padEnd(28)} ${c.detail}\n`);
+                        if (!c.ok && c.fix)
+                            process.stdout.write(`    修复:${c.fix}\n`);
+                    }
+                    process.stdout.write(r.ok ? '体检通过\n' : '体检不过(✗ 是必需项)\n');
+                }
+                if (!r.ok)
+                    process.exitCode = 1;
+                return;
+            }
+            case 'serve': {
+                const port = typeof flags.port === 'string' ? Number(flags.port) : undefined;
+                // 后台服务(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:平板、手机上按住说话要 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': {
+                const port = typeof flags.port === 'string' ? Number(flags.port) : undefined;
+                if (port !== undefined && !(Number.isInteger(port) && port > 0 && port < 65536))
+                    throw new UsageError('--port 要是 1–65535 的整数');
+                const scenario = typeof flags.scenario === 'string' ? flags.scenario : 'normal';
+                if (!['normal', 'nokey'].includes(scenario))
+                    throw new UsageError('--scenario 只能是 normal / nokey');
+                const delayMs = typeof flags.delay === 'string' ? Number(flags.delay) : undefined;
+                if (delayMs !== undefined && !(Number.isInteger(delayMs) && delayMs >= 0))
+                    throw new UsageError('--delay 要是非负整数(毫秒)');
+                const r = await serveMock({ port, scenario: scenario, delayMs, http: flags.http === true });
+                // 被杀(Ctrl-C、探针收尾)也走 exit,mock 的临时目录才删得掉
+                for (const s of ['SIGINT', 'SIGTERM', 'SIGHUP'])
+                    process.once(s, () => process.exit(128 + osConstants.signals[s]));
+                process.stdout.write(`cotutor mock 场景 ${scenario}(不经真实老师与百炼:老师都走实时老师页,假嘴念静音的声音)\n`);
+                if (!r.https)
+                    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 printOpen('扫码页', r.qrPage, '在这台电脑上打开,平板、手机用相机扫;--open 顺手打开', wantsOpen(flags));
+                return;
+            }
+            case 'add': {
+                const name = positionals[0];
+                const display = typeof flags.display === 'string' ? flags.display : undefined;
+                if (!name || !display)
+                    throw new UsageError(`add 需要老师名和 --display 显示名,如 cotutor add science-tutor --display 科学老师 --subject 科学 --avatar 🔬。\n${USAGE}`);
+                const ws = loadWorkspace(workspace);
+                if (ws.config.tutors[name])
+                    throw new UsageError(`cotutor.json 里已经有 ${name} 了;要改人设去老师团页或直接改文件`);
+                const subject = typeof flags.subject === 'string' ? flags.subject : undefined;
+                const r = await addTutorFile(ws.root, { name, display, subject, description: typeof flags.description === 'string' ? flags.description : undefined });
+                await patchConfig(ws, { tutors: { [name]: { display, ...(subject ? { subject } : {}), ...(typeof flags.avatar === 'string' ? { avatar: flags.avatar } : {}), enabled: true, ...(flags.hidden === true ? { hidden: true } : {}) } } });
+                if (json)
+                    process.stdout.write(`${JSON.stringify(redactDeep(r), null, 2)}\n`);
+                else {
+                    process.stdout.write(`加了 ${display}(${name}):\n  ${redactHome(r.file)}  ← 老师文件,打开把括号里那句换成这位老师的性子\n  cotutor.json tutors.${name}  ← 人设与政策(老师团页也能改)\n  ${redactHome(r.home)}/  ← 它的家\n`);
+                    process.stdout.write('服务不用重启;孩子端和家长端刷新就有。\n');
+                }
+                return;
+            }
+            case 'add-theme': {
+                const name = positionals[0];
+                if (!name)
+                    throw new UsageError(`add-theme 需要主题名,如 cotutor add-theme dark。\n${USAGE}`);
+                const { root } = resolveRoot(workspace);
+                const r = await addTheme(root, name, typeof flags.from === 'string' ? flags.from : 'default');
+                if (json)
+                    process.stdout.write(`${JSON.stringify(redactDeep(r), null, 2)}\n`);
+                else
+                    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 'upgrade': {
+                if (flags.grade !== undefined)
+                    throw new UsageError('upgrade 只更新已安装的教学包,不能用 --grade 切换年级');
+                const { root } = resolveRoot(workspace);
+                // --config 是另一件事:政策文件补缺(老师文件与 skill 不碰)
+                if (flags.config === true) {
+                    const dryRun = flags['dry-run'] === true;
+                    const r = await upgradeConfig(root, { dryRun });
+                    if (json)
+                        process.stdout.write(`${JSON.stringify(redactDeep(r), null, 2)}\n`);
+                    else if (!r.gaps.length)
+                        process.stdout.write(`cotutor.json 不缺什么:出厂模板里的老师、运行时、命令模板旗标都有,也没有不再用的段。\n`);
+                    else {
+                        for (const g of r.gaps)
+                            process.stdout.write(`${dryRun ? '·' : '✓'} ${g.path.padEnd(24)} ${g.detail}\n`);
+                        for (const st of r.installed)
+                            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)};服务在跑的话不用重启(改了就热重载)。\n`);
+                    }
+                    return;
+                }
+                const force = typeof flags.force === 'string' ? [flags.force, ...positionals] : positionals;
+                // 老布局先原样搬到新位置,下面再照常比新旧
+                const layoutSteps = await migrateLayout(root);
+                const steps = await upgradeTutors(root, { force });
+                const activitySteps = await upgradeActivities(root, { force });
+                const skillSteps = await upgradeSkills(root);
+                const link = await linkClaudeSkills(root);
+                const themeSteps = await upgradeThemes(root);
+                // 老师文件换新了,政策文件却不会自动多出新老师与新运行时(cotutor.json 是家长的),提一句
+                const gaps = await configGapsOf(root);
+                if (json)
+                    process.stdout.write(`${JSON.stringify(redactDeep({ root, layout: layoutSteps, steps, activities: activitySteps, skills: skillSteps, claudeSkills: link, themes: themeSteps, configGaps: gaps }), null, 2)}\n`);
+                else {
+                    for (const s of layoutSteps)
+                        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: '不再出厂,删了', 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)
+                        process.stdout.write(`${s.action === 'kept-custom' ? '!' : '✓'} theme ${s.name.padEnd(18)} ${word[s.action]}${s.basedOn && s.action !== 'latest' ? `(基于 ${s.basedOn})` : ''}${s.action === 'kept-custom' ? '(themes/ 里改过的主题不动)' : ''}\n`);
+                    for (const s of steps) {
+                        process.stdout.write(`${s.action === 'kept-custom' ? '!' : '✓'} ${s.name.padEnd(18)} ${word[s.action]}${s.basedOn && s.action !== 'latest' ? `(基于 ${s.basedOn})` : ''}\n`);
+                        if (s.diff?.length) {
+                            process.stdout.write(`    你的 vs 新版(- 你的 / + 新版),想用新版:cotutor upgrade --force ${s.name}\n`);
+                            for (const l of s.diff.slice(0, 40))
+                                process.stdout.write(`    ${l}\n`);
+                            if (s.diff.length > 40)
+                                process.stdout.write(`    …还有 ${s.diff.length - 40} 行\n`);
+                        }
+                    }
+                    for (const s of activitySteps) {
+                        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))
+                                process.stdout.write(`    ${l}\n`);
+                            if (s.diff.length > 40)
+                                process.stdout.write(`    …还有 ${s.diff.length - 40} 行\n`);
+                        }
+                    }
+                    if (gaps.length)
+                        process.stdout.write(`! 配置有 ${gaps.length} 项要改(新出厂老师 / 运行时 / 命令模板旗标 / 不再用的段):cotutor upgrade --config --dry-run 先看\n`);
+                }
+                return;
+            }
+            case 'activity': {
+                const sub = positionals[0];
+                if (sub !== 'check' && sub !== 'eval')
+                    throw new UsageError(`activity 后面跟 check / eval,如 cotutor activity check chinese-tutor 你说我画。\n${USAGE}`);
+                const ws = loadWorkspace(workspace);
+                const [, tutor, name] = positionals;
+                if (sub === 'eval') {
+                    if (!tutor || !name)
+                        throw new UsageError(`activity eval 要老师和名字,如 cotutor activity eval chinese-tutor 你说我画。\n${USAGE}`);
+                    const runs = typeof flags.runs === 'string' ? Number(flags.runs) : 3;
+                    if (!Number.isInteger(runs) || runs < 1 || runs > 10)
+                        throw new UsageError('--runs 要是 1–10 的整数');
+                    const { evalActivity, makeKidModel } = await import("../activity-eval.js");
+                    const r = await evalActivity(ws, tutor, name, {
+                        runs,
+                        ...(typeof flags.only === 'string' ? { only: flags.only } : {}),
+                        kid: makeKidModel(typeof flags['kid-model'] === 'string' ? { model: flags['kid-model'] } : {}),
+                        onTurn: json ? undefined : (e) => process.stdout.write(`  ${e.example} #${e.run} 第 ${e.turn} 轮  孩子:${e.kid}\n      老师:${e.said.slice(0, 90)}${e.said.length > 90 ? '…' : ''}${e.paint ? '  [画图卡]' : ''}\n`),
+                    });
+                    if (json)
+                        process.stdout.write(`${JSON.stringify(redactDeep(r), null, 2)}\n`);
+                    else {
+                        process.stdout.write('\n');
+                        for (const x of r.examples) {
+                            process.stdout.write(`${x.pass ? '✓' : '✗'} ${x.name}  ${x.runs.filter((y) => y.pass).length}/${x.runs.length} 次过\n`);
+                            x.runs.forEach((y, k) => {
+                                for (const g of y.grades.filter((g) => !g.pass))
+                                    process.stdout.write(`    #${k + 1} ${g.check}:${g.why ?? ''}\n`);
+                                if (y.error)
+                                    process.stdout.write(`    #${k + 1} ${y.error}\n`);
+                            });
+                        }
+                        process.stdout.write(`用了 ${tokenText(r.tokens)}(老师;模拟孩子另算,很少)· 报告 ${r.file} · 每轮在 evals/${tutor}/ 里,cotutor show ${tutor} <job> --evals 看\n`);
+                    }
+                    if (r.examples.some((x) => !x.pass))
+                        process.exitCode = 1;
+                    return;
+                }
+                const results = await checkActivities(ws.root, ws.config.tutors, { tutor, name });
+                if (!results.length)
+                    throw new UsageError(tutor ? `agents/${tutor}/activities/ 里没有${name ? ` ${name}.md` : ' activity 文件'}` : '这个 workspace 里还没有 activity 文件(cotutor upgrade 补出厂的)');
+                const fixes = results.reduce((n, r) => n + r.issues.filter((i) => i.level === 'fix').length, 0);
+                if (json)
+                    process.stdout.write(`${JSON.stringify(redactDeep({ ok: fixes === 0, activities: results.map((r) => ({ tutor: r.tutor, name: r.name, file: r.file, issues: r.issues, params: r.activity?.params ?? [], state: r.activity?.state ?? [], gates: r.activity?.gates ?? [], tools: r.activity?.tools.map((t) => t.tool) ?? [] })) }), null, 2)}\n`);
+                else {
+                    for (const r of results) {
+                        const bad = r.issues.filter((i) => i.level === 'fix').length;
+                        const a = r.activity;
+                        process.stdout.write(`${bad ? '✗' : '✓'} ${r.tutor}/${r.name}  ${redactHome(r.file)}\n`);
+                        if (a)
+                            process.stdout.write(`    家长填的:${a.params.map((p) => `${p.name}(${p.type}${p.optional ? ',可空' : ''}${p.default !== undefined ? `,缺省 ${p.default}` : ''})`).join(' ') || '无'} · 应用算的:${a.state.map((x) => x.name).join(' ') || '无'} · 应用拦的:${a.gates.map((g) => g.rule).join(' ') || '无'} · 工具人:${a.tools.map((t) => t.tool).join(' ') || '无'}\n`);
+                        for (const i of r.issues)
+                            process.stdout.write(`    ${i.level === 'fix' ? '要改' : '提醒'}${i.line ? ` 第 ${i.line} 行` : ''}:${i.text}\n`);
+                    }
+                    process.stdout.write(fixes ? `有 ${fixes} 条要改\n` : '都对得上\n');
+                }
+                if (fixes)
+                    process.exitCode = 1;
+                return;
+            }
+            case 'pin': {
+                // cotutor pin [off | status] [--pin <数字>]:家长端与工作台的锁(src/app/http/access.ts)。机器级,不要 workspace;没设就全开
+                const arg = positionals[0];
+                if (arg === 'off')
+                    await clearPin();
+                else if (arg !== 'status') {
+                    let pin = typeof flags.pin === 'string' ? flags.pin : '';
+                    if (!pin && arg === undefined && interactive(json)) {
+                        const rl = createInterface({ input: process.stdin, output: process.stdout });
+                        try {
+                            pin = (await rl.question('家长 PIN(4 到 8 位数字;iPad 上开 /parent、/dev 时输一次,留空只看现状):')).trim();
+                        }
+                        finally {
+                            rl.close();
+                        }
+                    }
+                    if (pin) {
+                        if (!PIN_RE.test(pin))
+                            throw new UsageError('PIN 要 4 到 8 位数字:cotutor pin --pin 2468');
+                        await setPin(pin);
+                    }
+                    else if (arg !== undefined)
+                        throw new UsageError(`不认识 ${arg}:cotutor pin [off | status] [--pin <数字>]`);
+                }
+                const rec = await readPin();
+                if (json)
+                    process.stdout.write(`${JSON.stringify({ pin: rec !== null, at: rec?.at ?? null, file: redactHome(USER_PIN_FILE) }, null, 2)}\n`);
+                else
+                    process.stdout.write(rec ? `设了 PIN(${rec.at.slice(0, 10)},${redactHome(USER_PIN_FILE)}):iPad 上开 /parent、/dev 要输一次,这台电脑免密;刚改过的话以前登录过的设备要重输。撤掉:cotutor pin off\n` : '没设 PIN:家长端与工作台对局域网全开(家长在旁边、用完收回 iPad 可以这样)。设一个:cotutor pin --pin 2468\n');
+                return;
+            }
+            case 'cert': {
+                const r = await makeCert(positionals.concat(typeof flags.host === 'string' ? [flags.host] : []));
+                if (json)
+                    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`);
+                    // 根证书怎么到设备上: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;
+            }
+            case 'pack': {
+                const [tutor, ...rest] = positionals;
+                if (!tutor)
+                    throw new UsageError(`pack 需要老师名,如 cotutor pack math-tutor "讲讲退位"。\n${USAGE}`);
+                const ws = loadWorkspace(workspace);
+                const { packDryRun } = await import("../../runtime/runner.js");
+                const from = typeof flags.from === 'string' ? flags.from : 'kid';
+                if (from !== 'kid' && from !== 'system')
+                    throw new UsageError('--from 只能是 kid / system');
+                const at = typeof flags.at === 'string' ? new Date(flags.at) : new Date();
+                if (Number.isNaN(at.getTime()))
+                    throw new UsageError(`--at 不是时间:${flags.at}`);
+                const activity = typeof flags.activity === 'string' ? await activityRunFor(ws.root, tutor, flags.activity, typeof flags.param === 'string' ? flags.param : '') : undefined;
+                const r = await packDryRun(ws, tutor, { from, at, text: rest.join(' ') || activity?.name || '(干跑)', ...(activity ? { activity } : {}) });
+                if (json) {
+                    process.stdout.write(`${JSON.stringify(redactDeep(r), null, 2)}\n`);
+                    return;
+                }
+                const rel = (f) => redactHome(f.startsWith(ws.root) ? f.slice(ws.root.length + 1) : f);
+                const rp = r.report;
+                const out = [];
+                out.push(`发给 ${tutor} 的上下文包(干跑,${r.prompt.length} 字):`);
+                out.push(...r.prompt.split('\n').map((l) => `  │ ${l}`));
+                out.push('来源:');
+                out.push(`  slot     ${rel(rp.timetable.file)} · ${rp.timetable.found ? (rp.timetable.slot ? `命中「${rp.timetable.slot}」` : '现在不在任何时段') : '课程表读不到'}`);
+                const v = rp.vault;
+                const chars = (n, tail = false) => (n > v.limit ? `${n} 字,${tail ? `只带最近 ${v.limit}` : `截到 ${v.limit}`}` : `${n} 字`);
+                out.push(`  vault    ${redactHome(v.root)} · 学期 ${v.semester ?? '算不出'}`);
+                out.push(`  profile  ${v.profile ? `${v.profile}(${chars(v.chars.profile)})` : '没有 cotutor: profile 的笔记'}${v.extraProfiles.length ? ` · 另有 ${v.extraProfiles.join('、')} 没用` : ''}`);
+                out.push(`  entry    ${v.entry ? `${v.entry}(${chars(v.chars.entry)})` : v.subject ? `没有 subject: ${v.subject}、semester: ${v.semester ?? '?'} 的入口文件` : '这位老师没配 subject'}${v.extraEntries.length ? ` · 另有 ${v.extraEntries.join('、')} 没用` : ''}`);
+                out.push(`  memory   ${v.memory ? `${v.memory}(${chars(v.chars.memory, true)})` : '还没有(第一次写「## 记忆」时建)'}${v.extraMemories.length ? ` · 另有 ${v.extraMemories.join('、')} 没用` : ''}`);
+                if (v.refs.length)
+                    out.push(`  refs     ${v.refs.join('、')}(只给路径)`);
+                out.push(`  plan     ${rel(rp.plan.file)} · ${rp.plan.found ? `这位老师 ${rp.plan.total} 行,带了 ${rp.plan.kept}(上限 ${rp.plan.limit})` : '本周计划不在'}`);
+                out.push(`  recent   ${rel(rp.recent.dir)}/ 最近 ${rp.recent.days} 天 · 有 ${rp.recent.filesFound.length} 天的日记${rp.recent.filesFound.length ? `(${rp.recent.filesFound[0]} … ${rp.recent.filesFound[rp.recent.filesFound.length - 1]})` : ''} · ${rp.recent.subject ? `学科「${rp.recent.subject}」` : '不按学科过滤'}的观察行共 ${rp.recent.total},带了 ${rp.recent.kept}(上限 ${rp.recent.limit},取最新的)`);
+                const cut = [v.chars.profile > v.limit ? '档案原文截了' : '', v.chars.entry > v.limit ? '入口文件原文截了' : '', v.chars.memory > v.limit ? '记忆原文截了' : '', rp.plan.total > rp.plan.kept ? `计划截掉 ${rp.plan.total - rp.plan.kept} 行` : '', rp.recent.total > rp.recent.kept ? `观察截掉 ${rp.recent.total - rp.recent.kept} 条` : ''].filter(Boolean);
+                out.push(cut.length ? `截掉的:${cut.join(';')}(改 cotutor.json policyDefaults.contextPack 的 entryChars / planLines / recent)` : '没截掉什么。');
+                out.push('这份不进任何文件;老师真跑时还会多 cards:(孩子在卡上做的)与 photos: 两段;同一话题续聊时没改过的笔记只写「未变」。');
+                process.stdout.write(`${out.join('\n')}\n`);
+                return;
+            }
+            case 'show': {
+                const [tutor, jobArg, dateArg] = positionals;
+                if (!tutor || !jobArg)
+                    throw new UsageError(`show 需要老师名和 job,如 cotutor show math-tutor 1620-1 2026-09-12(日期缺省今天)。\n${USAGE}`);
+                const ws = loadWorkspace(workspace);
+                const { rawView } = await import("../http/raw-view.js");
+                const { localDate } = await import("../../shared/time.js");
+                const date = dateArg ?? localDate(new Date());
+                const { evalWorkspace } = await import("../replay.js");
+                const v = await rawView(flags.evals === true ? evalWorkspace(ws) : ws, tutor, date, jobArg);
+                if (!v)
+                    throw new UsageError(`${tutor} ${date} 没有 ${jobArg} 这一轮(cotutor show 的日期缺省今天;job 与日期对不对?回放那轮要加 --evals)`);
+                if (json) {
+                    process.stdout.write(`${JSON.stringify(redactDeep(v), null, 2)}\n`);
+                    return;
+                }
+                const secs = (ms) => (ms === undefined ? '?' : `${(ms / 1000).toFixed(1)}s`);
+                const out = [];
+                out.push(`${v.tutor} ${v.date} ${v.job} · ${v.from} 问 · ${v.result}${v.error ? ` · 出错 ${v.error}` : ''}${v.tokens ? ` · ${tokenText(v.tokens)}` : ''}${v.timing ? ` · 首句就绪 ${secs(v.timing.firstReadyMs)} 老师写完 ${secs(v.timing.doneMs)}` : ''}`);
+                out.push(`问:${v.text}`);
+                const src = v.pack?.sources;
+                out.push(`上下文包:${v.pack ? `${v.pack.prompt.length} 字 · ${v.pack.resume ? 'resume' : '新开'} · ${v.pack.runtime}` : '没落(老轮次)'}${src ? ` · 老师文件 ${src.agent ? `${src.agent.file} ${src.agent.hash.slice(7)}` : '读不到'} · 技能 ${Object.entries(src.skills).map(([k, h]) => `${k} ${h.slice(7, 13)}`).join(' / ') || '无'}` : ''}`);
+                if (v.pack)
+                    out.push(...v.pack.prompt.split('\n').map((l) => `  │ ${l}`));
+                out.push(`读了什么:${v.tools.length ? '' : '没用工具'}`);
+                for (const t of v.tools)
+                    out.push(`  ${t.ok === false ? '✗' : t.ok === null ? '?' : '·'} ${t.name}${t.sub ? '(子代理)' : ''} ${t.arg}${t.chars ? ` → ${t.chars} 字` : ''}`);
+                out.push(`卡 ${v.kid.cards.length}:${v.kid.cards.map((c) => `${v.job}/${c.n} ${c.kind} ${c.label}`.trim()).join(' | ')}`);
+                out.push(`讲稿 ${v.kid.lines.length}:`);
+                for (const l of v.kid.lines)
+                    out.push(`  ${l.text}${l.cut ? `〔截:${l.cut}〕` : ''}`);
+                if (v.stored.parentText)
+                    out.push(`给家长的尾巴:\n${v.stored.parentText.split('\n').map((l) => `  ${l}`).join('\n')}`);
+                if (v.stored.warnings.length)
+                    out.push(`提醒:${v.stored.warnings.join(';')}`);
+                out.push(`文件:conversations/${tutor}/${v.files.log}${v.files.run ? ` · ${v.files.run}` : ''}`);
+                process.stdout.write(`${out.join('\n')}\n`);
+                return;
+            }
+            case 'replay': {
+                const [tutor, jobArg, dateArg] = positionals;
+                if (!tutor || !jobArg)
+                    throw new UsageError(`replay 需要老师名和 job,如 cotutor replay math-tutor 1620-1 2026-09-12(日期缺省今天)。\n${USAGE}`);
+                const ws = loadWorkspace(workspace);
+                const { compareReplay, formatCompare, startReplay } = await import("../replay.js");
+                const { localDate } = await import("../../shared/time.js");
+                const date = dateArg ?? localDate(new Date());
+                const r = await startReplay(ws, tutor, date, jobArg, { runtime: typeof flags.runtime === 'string' ? flags.runtime : undefined, env: process.env });
+                if (!json)
+                    process.stdout.write(`回放起了:evals/${tutor}/${date}.${r.evalJob}.*(原轮 ${jobArg}),等老师说完……\n`);
+                await r.done;
+                const c = await compareReplay(ws, tutor, date, r.evalJob);
+                if (!c)
+                    throw new UsageError(`回放跑完了但读不到结果:evals/${tutor}/${date}.json`);
+                if (json)
+                    process.stdout.write(`${JSON.stringify(redactDeep(c), null, 2)}\n`);
+                else
+                    process.stdout.write(formatCompare(c));
+                return;
+            }
+            case 'compare': {
+                const [tutor, evalJobArg, dateArg] = positionals;
+                if (!tutor)
+                    throw new UsageError(`compare 需要老师名,如 cotutor compare math-tutor 1712-1 2026-09-12。\n${USAGE}`);
+                const ws = loadWorkspace(workspace);
+                const { compareReplay, formatCompare, listReplays } = await import("../replay.js");
+                const { localDate } = await import("../../shared/time.js");
+                const date = dateArg ?? localDate(new Date());
+                if (!evalJobArg) {
+                    const rows = await listReplays(ws, tutor, date);
+                    if (json)
+                        process.stdout.write(`${JSON.stringify(rows, null, 2)}\n`);
+                    else if (!rows.length)
+                        process.stdout.write(`${tutor} ${date} 没有回放过(cotutor replay ${tutor} <job> ${date})\n`);
+                    else
+                        for (const r of rows)
+                            process.stdout.write(`${r.evalJob}  ← ${r.replayOf}  ${r.at.slice(11)}  ${r.result}${r.tokens ? `  ${tokenText(r.tokens)}` : ''}${r.runtime ? `  ${r.runtime}` : ''}\n`);
+                    return;
+                }
+                const c = await compareReplay(ws, tutor, date, evalJobArg);
+                if (!c)
+                    throw new UsageError(`${tutor} ${date} 没有回放 ${evalJobArg}(cotutor compare ${tutor} ${date} 列这天的)`);
+                if (json)
+                    process.stdout.write(`${JSON.stringify(redactDeep(c), null, 2)}\n`);
+                else
+                    process.stdout.write(formatCompare(c));
+                return;
+            }
+            case 'trace': {
+                const [tutor, jobArg, dateArg] = positionals;
+                if (!tutor || !jobArg)
+                    throw new UsageError(`trace 需要老师名和 job,如 cotutor trace math-tutor 1620-1 2026-09-12(日期缺省今天)。\n${USAGE}`);
+                const ws = loadWorkspace(workspace);
+                const { localDate } = await import("../../shared/time.js");
+                const { conversationFiles } = await import("../../schema/index.js");
+                const date = dateArg ?? localDate(new Date());
+                const file = conversationFiles(ws.dirs.conversations, tutor, date).events(jobArg);
+                let text;
+                try {
+                    text = readFileSync(file, 'utf8');
+                }
+                catch {
+                    throw new UsageError(`没有这轮的事件文件:${redactHome(file)}(2026-09-13 之前的轮次没有事件;job 与日期对不对?)`);
+                }
+                const events = parseEvents(text).filter(laneFilter(typeof flags.lane === 'string' ? flags.lane : undefined));
+                if (json)
+                    process.stdout.write(`${JSON.stringify(events, null, 2)}\n`);
+                else
+                    for (const e of events)
+                        process.stdout.write(`${formatEvent(e)}\n`);
+                return;
+            }
+            case 'rate': {
+                const [tutor, thread, score] = positionals;
+                const n = Number(score);
+                if (!tutor || !thread || !(n >= 1 && n <= 5 && Number.isInteger(n)))
+                    throw new UsageError(`rate 需要老师名、话题 id 和 1–5 的星,如 cotutor rate math-tutor 1620-1 4。\n${USAGE}`);
+                const ws = loadWorkspace(workspace);
+                const date = typeof flags.date === 'string' ? flags.date : localDate(new Date());
+                const index = await rateThread(ws, tutor, date, thread, n);
+                if (json)
+                    process.stdout.write(`${JSON.stringify({ tutor, date, thread, rating: index.ratings[thread] })}\n`);
+                else
+                    process.stdout.write(`${tutor} ${date} 话题 ${thread}:${'★'.repeat(n)}${n >= ws.config.vault.keepScore ? '(记账时摘要进日记)' : `(不到 ${ws.config.vault.keepScore} 星,记账只记孩子问的话与观察)`}\n`);
+                return;
+            }
+            case 'bookkeep': {
+                const [tutor] = positionals;
+                if (!tutor)
+                    throw new UsageError(`bookkeep 需要老师名,如 cotutor bookkeep math-tutor。\n${USAGE}`);
+                const ctx = createContext(loadWorkspace(workspace));
+                const date = typeof flags.date === 'string' ? flags.date : localDate(new Date());
+                const only = typeof flags.thread === 'string' ? [flags.thread] : undefined;
+                if (!json && flags.quiet !== true)
+                    ctx.runner.onEvent((e) => { if (e.tutor === tutor && (e.event.lane === 'ledger' || e.event.lane === 'main' || e.event.lane === 'index'))
+                        process.stdout.write(`${formatEvent(e.event)}\n`); });
+                const r = await ctx.runner.bookkeep(tutor, date, only);
+                if (!json) {
+                    for (const sk of r.skipped)
+                        process.stdout.write(`话题 ${sk.thread} 跳过:${sk.why}\n`);
+                    if (!r.queued.length)
+                        process.stdout.write('没有要记的话题\n');
+                    else
+                        process.stdout.write(`记账 ${r.queued.length} 个话题:${r.queued.join('、')}…\n`);
+                }
+                await ctx.runner.flush();
+                const { readIndex } = await import("../../runtime/journal/store.js");
+                const index = await readIndex(ctx.ws, tutor, date);
+                if (json)
+                    process.stdout.write(`${JSON.stringify({ tutor, date, queued: r.queued, skipped: r.skipped, booked: index.booked }, null, 2)}\n`);
+                else
+                    for (const th of r.queued) {
+                        const m = index.messages.find((x) => x.bookkeep?.thread === th && x.result !== 'running');
+                        process.stdout.write(`话题 ${th}:${index.booked[th] ? '记进日记了' : `没记成${m?.warnings?.length ? ' — ' + m.warnings.join(';') : m?.error ? ' — ' + m.error : ''}`}\n`);
+                    }
+                return;
+            }
+            case 'home': {
+                const sub = positionals[0];
+                if (sub !== 'check' && sub !== 'publish' && sub !== 'show')
+                    throw new UsageError(`home 后面跟 check / publish / show,如 cotutor home check。\n${USAGE}`);
+                const ws = loadWorkspace(workspace);
+                const now = new Date();
+                const home = await import("../../runtime/home/store.js");
+                if (sub === 'show') {
+                    const s = await home.homeStats(ws, now);
+                    process.stdout.write(json ? `${JSON.stringify(s, null, 2)}\n` : `${home.formatStats(ws, s)}\n`);
+                    return;
+                }
+                if (sub === 'check') {
+                    const published = flags.published === true;
+                    let md;
+                    if (published) {
+                        const { home: pub, error } = await home.readPublished(ws);
+                        if (!pub)
+                            throw new UsageError(error ?? '还没发布过首页');
+                        md = await home.publishedSource(ws, pub);
+                        if (md === null)
+                            throw new UsageError(`已发布那份的原文 ${pub.source} 不在了`);
+                    }
+                    else {
+                        md = await home.readDraft(ws);
+                        if (md === null)
+                            throw new UsageError('还没有草稿 home/draft.md(用 cotutor-home 技能写一份)');
+                    }
+                    const check = await home.checkHome(ws, md, now);
+                    const kid = await home.kidHomeView(ws, now, { source: published ? 'published' : 'draft' });
+                    if (json)
+                        process.stdout.write(`${JSON.stringify({ ok: check.fixes === 0, for: check.doc.for ?? null, issues: check.issues, cards: check.doc.cards, kid: kid.cards, note: check.doc.note }, null, 2)}\n`);
+                    else
+                        process.stdout.write(`${home.formatCheck(ws, check, published ? '已发布的那份' : '草稿 home/draft.md', kid)}\n`);
+                    if (check.fixes)
+                        process.exitCode = 1;
+                    return;
+                }
+                const r = await home.publishHome(ws, { force: flags.force === true, from: typeof flags.from === 'string' ? flags.from : undefined, now });
+                if (json)
+                    process.stdout.write(`${JSON.stringify({ ok: r.ok, id: r.home?.id ?? null, source: r.source, issues: r.check.issues, dropped: r.dropped }, null, 2)}\n`);
+                else if (!r.ok) {
+                    const kid = await home.kidHomeView(ws, now, { source: 'draft' });
+                    process.stdout.write(`${home.formatCheck(ws, r.check, r.source, kid)}\n没发布:有 ${r.check.fixes} 条要改;改好再发,或 --force 丢掉那几张照发\n`);
+                }
+                else {
+                    const h = r.home;
+                    process.stdout.write(`发布了 ${h.id}(${r.source} → ${h.source},home/published.json)· ${h.cards.length} 张卡${h.for ? ` · for ${h.for}` : ''}\n`);
+                    for (const d of r.dropped)
+                        process.stdout.write(`  丢掉:${d}\n`);
+                    for (const w of h.warnings)
+                        process.stdout.write(`  提醒:${w}\n`);
+                    process.stdout.write('孩子端刷新就是新首页(不用重起服务)\n');
+                }
+                if (!r.ok)
+                    process.exitCode = 1;
+                return;
+            }
+            case 'send': {
+                const [tutor, ...words] = positionals;
+                const photoFiles = typeof flags.photo === 'string' ? flags.photo.split(',').filter(Boolean) : [];
+                // --activity:像孩子点了首页的 activity 按钮,新开话题;没写消息就发 activity 的名字(按钮上的字)
+                const activityName = typeof flags.activity === 'string' ? flags.activity : undefined;
+                const text = words.join(' ') || activityName || '';
+                if (!tutor || (!text && !photoFiles.length))
+                    throw new UsageError(`send 需要老师名和消息,如 cotutor send math-tutor "这一步为什么要借位"。\n${USAGE}`);
+                const from = typeof flags.from === 'string' ? flags.from : 'kid';
+                if (!MESSAGE_FROM.includes(from))
+                    throw new UsageError(`--from 只能是 ${MESSAGE_FROM.join(' / ')}`);
+                const ws = loadWorkspace(workspace);
+                // --photo:和孩子端拍照同一条路,先拷进 captures/ 再随消息发;孩子端会先缩到长边 2000 的 jpeg,这里不缩,太大就拒
+                const photos = [];
+                if (photoFiles.length > 9)
+                    throw new UsageError('--photo 一次最多 9 张');
+                for (const f of photoFiles) {
+                    const ext = /\.(jpe?g|png)$/i.exec(f)?.[1]?.toLowerCase();
+                    if (!ext)
+                        throw new UsageError(`--photo 只认 jpg / png:${f}`);
+                    const data = await readFile(f).catch(() => null);
+                    if (!data)
+                        throw new UsageError(`--photo 读不到:${f}`);
+                    if (data.length > PHOTO_MAX_BYTES)
+                        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'));
+                }
+                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);
+                    ctx.runner.onEvent((e) => { if (e.tutor === tutor && keep(e.event))
+                        process.stdout.write(`${formatEvent(e.event)}\n`); });
+                }
+                const activity = activityName ? await activityRunFor(ws.root, tutor, activityName, typeof flags.param === 'string' ? flags.param : '') : undefined;
+                // 孩子的话照实时写(同孩子端:上下文包带 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;
+                const m = index.messages.find((x) => x.job === started.job);
+                if (json)
+                    process.stdout.write(`${JSON.stringify({ tutor, date: started.date, job: started.job, runtime: started.plan.runtime, resume: started.plan.resume, message: m, session: index.session, tokens: sumTokens(index.messages) }, null, 2)}\n`);
+                else if (!m || m.result !== 'ok') {
+                    process.stdout.write(`本轮出错:${m?.error ?? '未知'};看 conversations/${tutor}/${started.date}.${started.job}.err.log\n`);
+                    process.exitCode = 1;
+                }
+                else {
+                    process.stdout.write(`孩子看到:${m.kidText ?? '(没有给孩子的话)'}\n`);
+                    const secs = (ms) => (ms < 120000 ? `${Math.round(ms / 100) / 10}s` : `${Math.round(ms / 6000) / 10}min`);
+                    const timing = [m.timing?.firstReadyMs !== undefined ? `首句就绪 ${secs(m.timing.firstReadyMs)}` : null, m.timing?.firstCardMs !== undefined ? `首卡 ${secs(m.timing.firstCardMs)}` : null, m.timing?.doneMs !== undefined ? `整轮 ${secs(m.timing.doneMs)}` : null].filter(Boolean);
+                    if (m.artifacts.length)
+                        process.stdout.write(`课包:${m.artifacts.join(', ')}\n`);
+                    process.stdout.write(`会话 ${index.session?.id ?? '?'}${timing.length ? ' · ' + timing.join(' · ') : ''}${m.tokens ? ` · 本轮 ${tokenText(m.tokens)}` : ''}${sumTokens(index.messages) ? ` · 今日 ${tokenText(sumTokens(index.messages))}` : ''}\n`);
+                }
+                return;
+            }
+            case 'chalk': {
+                const { chalkCommand } = await import("./chalk/main.js");
+                await chalkCommand(positionals, flags, { workspace, json });
+                return;
+            }
+            default:
+                throw new UsageError(`未知命令 '${cmd}'。\n${USAGE}`);
+        }
+    }
+    catch (err) {
+        if (err instanceof UsageError) {
+            if (json)
+                process.stdout.write(`${JSON.stringify({ ok: false, error: 'usage', message: err.message })}\n`);
+            else
+                process.stderr.write(`cotutor: ${err.message}\n`);
+            process.exitCode = 2;
+            return;
+        }
+        throw err;
+    }
+}