cotutor 0.3.0 → 0.4.0

package/dist/app/cli/tray.js

@@ -0,0 +1,618 @@
+/**
+ * 托盘图标(macOS 菜单栏、Windows 任务栏;Linux 没做,GNOME 缺省不显示托盘):家长不开终端也看得到服务好不好、点得开家长端。
+ * 三层:
+ *   node 进程(cotutor tray run,tray-run.ts 是它的轻入口):隔几秒问每个后台服务的 /api/health,判断状态,决定显示什么、要不要通知;这里全是能测的 TS。
+ *   显示脚本(tray-mac.ts 的 JXA、tray-windows.ts 的 PowerShell,都是系统自带、不用签名):只管画和回报点击,不判断。
+ *   登录项:macOS 一个 LaunchAgent,Windows 一条 Run 项 + wscript 隐藏启动器;service install 时一起装(--no-tray 不装,cotutor tray off 关掉并记住)。
+ * 为什么不放在 serve 里:服务挂了图标也没了,就说不出「没在跑」;多个孩子时一台电脑也只该有一个图标。
+ * 为什么不用 npm 的托盘库、Electron:见 docs/wip;systray2 只有 x86 的 Mac 二进制且没签名,Electron 要多下一百多 MB。
+ * 状态:正常只有 logo(和菜单栏别的图标一样单色);有事才出状态点,橙 = 要处理,红 = 没在跑(logo 同时变淡)。正常 → 有事、→ 没在跑时通知一次,恢复不通知。
+ * 「退出 cotutor」= 停掉所有后台服务并退出图标,下次登录自己回来;正开着电话时先问一声。
+ */
+import { spawn } from 'node:child_process';
+import { appendFileSync, existsSync, renameSync, statSync } from 'node:fs';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { DEFAULT_PORT } from "../../shared/default-port.js";
+import { UsageError } from "../../shared/errors.js";
+import { siteUrl } from "../../shared/site-url.js";
+import { portHolder } from "./port-holder.js";
+import { RUN_KEY, STARTUP_APPROVED_KEY, encodeLauncher, parseProcs, psArgs, runValue, startupDisabled, winCommandLine } from "./service-windows.js";
+import { binPath, controlService, listServices, parseLaunchctlPrint, probeHealth, wscriptPath, xml } from "./service.js";
+import { macTrayIcons, windowsTrayIcons } from "./tray-icons.js";
+import { HELPER_NO_SESSION, TRAY_AUMID, TRAY_LABEL, TRAY_RUN_VALUE } from "./tray-ids.js";
+import { MAC_TRAY_SCRIPT } from "./tray-mac.js";
+import { WINDOWS_TRAY_SCRIPT, findTrayScript, trayLauncher } from "./tray-windows.js";
+export { HELPER_NO_SESSION, TRAY_AUMID, TRAY_LABEL, TRAY_RUN_VALUE };
+/** 多久问一次 */
+export const TRAY_POLL_MS = 5_000;
+/** 连着几次问不到才算没在跑:重起一下、网络抖一下不报 */
+export const TRAY_STRIKES = 2;
+/** 图标刚起来时服务可能还没起来:这么久里问不到算「正在启动」(Windows 登录后约一分钟才跑 Run 项) */
+export const TRAY_START_GRACE_MS = 90_000;
+/** 点了启动、重启以后等多久 */
+export const TRAY_RESTART_GRACE_MS = 30_000;
+/** 两次问之间隔太久 = 刚睡醒:网络还没回来,先别报 */
+export const TRAY_WAKE_GAP_MS = 30_000;
+export const TRAY_WAKE_GRACE_MS = 30_000;
+const HOLDER_EVERY_MS = 60_000;
+const HELPER_RESTART_MS = 10_000;
+const LOG_MAX = 1024 * 1024;
+const MAC_FULL_DISK = 'x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles';
+/** 跑了多久,给家长看 */
+export function uptimeText(startedMs, now) {
+    const min = Math.max(0, (now - startedMs) / 60_000);
+    if (min < 60)
+        return '不到 1 小时';
+    if (min < 48 * 60)
+        return `${Math.floor(min / 60)} 小时`;
+    return `${Math.floor(min / 1440)} 天`;
+}
+/** 服务在跑,但有事要家长处理:先后就是轻重,菜单上只说第一件 */
+export function issuesOf(p, o) {
+    const h = p.health;
+    if (!h)
+        return [];
+    const url = siteUrl(h.scheme ?? 'https', 'localhost', p.port, '/parent/home');
+    const out = [];
+    if (h.configError)
+        out.push({ text: 'cotutor.json 写坏了:改的没生效', fix: { kind: 'open', target: p.root } });
+    if (h.vault === 'denied')
+        out.push(o.platform === 'darwin' ? { text: '读不到 vault:要给 node 开磁盘权限', fix: { kind: 'open', target: MAC_FULL_DISK } } : { text: '读不到 vault:看看这个目录的权限', fix: { kind: 'open', target: p.root } });
+    else if (h.vault === 'missing')
+        out.push({ text: 'vault 不在了:看看 cotutor.json 的 paths.vault', fix: { kind: 'open', target: p.root } });
+    if (h.bailian === false)
+        out.push({ text: '还没填百炼:老师们到不了', fix: { kind: 'open', target: url } });
+    if (h.version && h.version !== o.version)
+        out.push({ text: `在跑的是 ${h.version},装的是 ${o.version}:重启一下`, fix: { kind: 'restart' } });
+    return out;
+}
+const rank = (l) => (l === 'bad' ? 2 : l === 'warn' ? 1 : 0);
+/** 记着每个服务上一轮的样子,算这一轮的样子和要不要通知;不碰任何系统,测试直接喂 */
+export class TrayModel {
+    mem = new Map();
+    last = 0;
+    o;
+    constructor(o) { this.o = o; }
+    /** 刚点了启动、重启:这一阵问不到是正常的 */
+    expect(name, now) {
+        const m = this.mem.get(name);
+        if (!m)
+            return;
+        m.row = null;
+        m.misses = 0;
+        m.graceUntil = now + TRAY_RESTART_GRACE_MS;
+    }
+    update(probes, now) {
+        const woke = this.last > 0 && now - this.last > TRAY_WAKE_GAP_MS;
+        this.last = now;
+        const rows = [];
+        const notes = [];
+        const multi = probes.length > 1;
+        for (const p of probes) {
+            let m = this.mem.get(p.name);
+            if (!m) {
+                m = { row: null, misses: 0, graceUntil: now + TRAY_START_GRACE_MS };
+                this.mem.set(p.name, m);
+            }
+            if (woke)
+                m.graceUntil = Math.max(m.graceUntil, now + TRAY_WAKE_GRACE_MS);
+            let row;
+            if (p.health) {
+                m.misses = 0;
+                m.graceUntil = 0;
+                row = this.healthy(p, now);
+            }
+            else {
+                m.misses++;
+                if (now < m.graceUntil)
+                    row = m.row ?? this.placeholder(p, 'starting', '');
+                else if (m.misses < TRAY_STRIKES && m.row && m.row.level !== 'starting')
+                    row = m.row;
+                else
+                    row = this.placeholder(p, 'bad', p.holder ? `端口 ${p.port} 被占着:${p.holder} 在用` : '孩子的平板现在打不开');
+            }
+            const prev = m.level;
+            // 第一次看到就是「要处理」不通知(每次登录都弹太烦,菜单里看得到);变差才通知
+            if (rank(row.level) > rank(prev) && !(row.level === 'warn' && (prev === undefined || prev === 'starting')))
+                notes.push(noteFor(row, multi, this.o.platform));
+            m.level = row.level;
+            m.row = row;
+            rows.push(row);
+        }
+        for (const name of [...this.mem.keys()])
+            if (!probes.some((p) => p.name === name))
+                this.mem.delete(name);
+        return { rows, notes };
+    }
+    healthy(p, now) {
+        const h = p.health;
+        const issues = issuesOf(p, this.o);
+        const started = Date.parse(h.started);
+        const running = h.mode === 'foreground' ? '在终端里跑,关了终端就停' : `已运行 ${uptimeText(Number.isNaN(started) ? now : started, now)}`;
+        return {
+            name: p.name,
+            kid: p.kid,
+            logDir: p.logDir,
+            level: issues.length ? 'warn' : 'ok',
+            url: siteUrl(h.scheme ?? 'https', 'localhost', p.port, '/parent/home'),
+            detail: issues.length ? issues[0].text : `${running} · 版本 ${h.version ?? '?'}`,
+            issues: issues.length,
+            fix: issues[0]?.fix ?? null,
+            calls: h.calls ?? 0,
+        };
+    }
+    placeholder(p, level, detail) {
+        return { name: p.name, kid: p.kid, logDir: p.logDir, level, url: null, detail, issues: 0, fix: null, calls: 0 };
+    }
+}
+const titleOf = (r, multi) => {
+    if (!multi)
+        return r.level === 'ok' ? 'cotutor 正常' : r.level === 'warn' ? `有 ${r.issues} 件事要处理` : r.level === 'bad' ? '后台服务没在跑' : 'cotutor 正在启动';
+    return `${r.kid} · ${r.level === 'ok' ? '正常' : r.level === 'warn' ? `有 ${r.issues} 件事要处理` : r.level === 'bad' ? '没在跑' : '正在启动'}`;
+};
+function noteFor(r, multi, platform) {
+    // 点通知回不到这里(Mac 的来源是系统的脚本程序;Windows 的 PowerShell 5.1 接不了 WinRT 的事件),只能请家长去点图标
+    const hint = platform === 'darwin' ? '点菜单栏的 cotutor 图标看看' : '点任务栏的 cotutor 图标看看';
+    const who = multi ? r.kid : 'cotutor ';
+    if (r.level === 'bad')
+        return { type: 'notify', title: `${who}${multi ? '的' : ''}后台服务没在跑`, body: `孩子的平板现在打不开,${hint}` };
+    return { type: 'notify', title: `${who}有 ${r.issues} 件事要处理`, body: `${r.detail},${hint}` };
+}
+/** 这一轮显示什么 */
+export function trayShow(rows) {
+    const multi = rows.length > 1;
+    const worst = rows.reduce((a, r) => (!a || rank(r.level) > rank(a.level) ? r : a), null);
+    const level = (worst?.level ?? 'ok');
+    const menu = [];
+    for (const r of rows) {
+        menu.push({ kind: 'info', title: titleOf(r, multi), ...(r.level === 'starting' ? {} : { level: r.level }) });
+        if (r.detail && (!multi || r.level !== 'ok'))
+            menu.push({ kind: 'sub', title: r.detail });
+        if (!multi)
+            menu.push({ kind: 'sep' });
+        const act = (what, title, primary = false) => { menu.push({ kind: 'action', id: `${what}:${r.name}`, title, ...(primary ? { primary } : {}) }); };
+        if (r.level === 'ok' || r.level === 'warn') {
+            if (r.level === 'warn')
+                act('fix', '看看怎么修', true);
+            act('open', '打开家长端');
+            if (!multi)
+                menu.push({ kind: 'sep' });
+            act('restart', '重启服务');
+            act('logs', '看日志');
+        }
+        else if (r.level === 'bad') {
+            act('start', '启动服务', true);
+            act('logs', '看日志');
+        }
+        else
+            act('logs', '看日志');
+        menu.push({ kind: 'sep' });
+    }
+    menu.push({ kind: 'action', id: 'quit', title: '退出 cotutor' });
+    return { type: 'show', icon: level === 'starting' ? 'ok' : level, tip: worst ? titleOf(worst, multi) : 'cotutor', menu };
+}
+export const QUIT_CONFIRM = {
+    id: 'quit',
+    title: '孩子正在和老师通话',
+    body: '现在退出会挂断这通电话,孩子的平板也打不开了,下次登录这台电脑后自动恢复。确定退出吗?',
+    yes: '退出',
+    no: '先不退出',
+};
+/** 主循环:问状态、发给显示脚本、接点击;都退了才返回退出码。0 = 不用再起(点了退出、没有服务了、没有桌面) */
+export function runTray(d) {
+    return new Promise((resolve) => {
+        const model = new TrayModel({ platform: d.platform, version: d.version });
+        const pollMs = d.pollMs ?? TRAY_POLL_MS;
+        const holders = new Map();
+        let helper = null;
+        let shown = '';
+        let rows = [];
+        let services = [];
+        let stopping = false;
+        let ticking = false;
+        let again = false;
+        let timer = null;
+        let finished = false;
+        const finish = (code) => {
+            if (finished)
+                return;
+            finished = true;
+            stopping = true;
+            if (timer)
+                clearTimeout(timer);
+            resolve(code);
+        };
+        const quitAll = async () => {
+            stopping = true;
+            if (timer)
+                clearTimeout(timer);
+            for (const s of services) {
+                try {
+                    await d.control(s.root, 'stop');
+                }
+                catch (err) {
+                    d.note(`停 ${s.name} 没成:${String(err)}`);
+                }
+            }
+            d.note('退出:服务都停了');
+            if (helper) {
+                helper.send({ type: 'quit' });
+                helper.close();
+            }
+            // 显示脚本不退也不等它
+            setTimeout(() => finish(0), 3000).unref();
+        };
+        const control = (name, what) => {
+            const s = services.find((x) => x.name === name);
+            if (!s)
+                return;
+            model.expect(name, d.now());
+            void d.control(s.root, what).catch((err) => {
+                d.note(`${what} ${name} 没成:${String(err)}`);
+                helper?.send({ type: 'notify', title: 'cotutor 没起来', body: err instanceof UsageError ? err.message : '看看日志' });
+            }).finally(() => { void tick(); });
+            void tick();
+        };
+        const onClick = (id) => {
+            d.note(`点了 ${id}`);
+            if (id === 'quit') {
+                if (rows.some((r) => r.calls > 0))
+                    helper?.send({ type: 'confirm', ...QUIT_CONFIRM });
+                else
+                    void quitAll();
+                return;
+            }
+            const at = id.indexOf(':');
+            const what = id.slice(0, at);
+            const r = rows.find((x) => x.name === id.slice(at + 1));
+            if (!r)
+                return;
+            if (what === 'open' && r.url)
+                d.open(r.url);
+            else if (what === 'logs' && r.logDir)
+                d.open(r.logDir);
+            else if (what === 'start' || what === 'restart')
+                control(r.name, what);
+            else if (what === 'fix' && r.fix) {
+                if (r.fix.kind === 'restart')
+                    control(r.name, 'restart');
+                else
+                    d.open(r.fix.target);
+            }
+        };
+        const startHelper = () => {
+            helper = d.spawnHelper({
+                message(m) {
+                    if (m.type === 'ready') {
+                        shown = '';
+                        void tick();
+                    }
+                    else if (m.type === 'click' && m.id)
+                        onClick(m.id);
+                    else if (m.type === 'confirm' && m.id === 'quit' && m.yes)
+                        void quitAll();
+                    else if (m.type === 'error')
+                        d.note(`显示脚本:${m.message ?? ''}`);
+                },
+                exit(code) {
+                    helper = null;
+                    if (stopping) {
+                        finish(0);
+                        return;
+                    }
+                    if (code === HELPER_NO_SESSION) {
+                        d.note('这个会话没有桌面,不显示图标');
+                        finish(0);
+                        return;
+                    }
+                    d.note(`显示脚本退了(${code ?? '?'}),隔一会儿再起`);
+                    setTimeout(() => { if (!stopping)
+                        startHelper(); }, d.helperRestartMs ?? HELPER_RESTART_MS).unref();
+                },
+            });
+        };
+        const tick = async () => {
+            if (stopping)
+                return;
+            if (ticking) {
+                again = true;
+                return;
+            }
+            ticking = true;
+            if (timer)
+                clearTimeout(timer);
+            try {
+                services = await d.list();
+                if (!services.length) {
+                    // 服务都卸了:图标也没事可做
+                    stopping = true;
+                    d.note('没有后台服务了,退出');
+                    if (helper) {
+                        helper.send({ type: 'quit' });
+                        helper.close();
+                    }
+                    setTimeout(() => finish(0), 3000).unref();
+                    return;
+                }
+                const now = d.now();
+                const probes = [];
+                for (const s of services) {
+                    const w = await d.inspect(s);
+                    const health = await d.probe(w.port);
+                    let holder = null;
+                    if (!health) {
+                        const c = holders.get(s.name);
+                        if (c && now - c.at < HOLDER_EVERY_MS)
+                            holder = c.who;
+                        else {
+                            holder = await d.holder(w.port);
+                            holders.set(s.name, { at: now, who: holder });
+                        }
+                    }
+                    else
+                        holders.delete(s.name);
+                    probes.push({ name: s.name, kid: w.kid, root: s.root, logDir: s.logDir, port: w.port, health, holder });
+                }
+                const r = model.update(probes, d.now());
+                rows = r.rows;
+                const show = trayShow(rows);
+                const text = JSON.stringify(show);
+                if (helper && text !== shown) {
+                    helper.send(show);
+                    shown = text;
+                    d.note(`显示:${show.icon} ${show.tip}`);
+                }
+                for (const n of r.notes) {
+                    helper?.send(n);
+                    d.note(`通知:${n.title}`);
+                }
+            }
+            catch (err) {
+                d.note(`这一轮出错:${String(err)}`);
+            }
+            finally {
+                ticking = false;
+                if (!stopping) {
+                    if (again) {
+                        again = false;
+                        void tick();
+                    }
+                    else
+                        timer = setTimeout(() => { void tick(); }, pollMs);
+                }
+            }
+        };
+        startHelper();
+    });
+}
+// ---- 真的那一套:文件放哪、怎么起显示脚本、登录项 ----
+export const traySupported = (platform) => platform === 'darwin' || platform === 'win32';
+/** 显示脚本、图标、日志放哪 */
+export function trayDir(host) {
+    if (host.platform === 'win32')
+        return join(host.env.LOCALAPPDATA || join(host.home, 'AppData', 'Local'), 'cotutor', 'tray');
+    return join(host.home, 'Library', 'Application Support', 'cotutor', 'tray');
+}
+const offMark = (dir) => join(dir, 'off');
+const plistFile = (host) => join(host.home, 'Library', 'LaunchAgents', `${TRAY_LABEL}.plist`);
+const launcherFile = (dir) => join(dir, 'start.js');
+/** 图标改了画法就改这个数,已经写过的会重写 */
+const ASSETS_VERSION = 1;
+/** 写显示脚本(每次起来都写,升级后马上生效)和图标(版本变了才画,画一次要几百毫秒) */
+export async function writeTrayFiles(platform, dir) {
+    const icons = join(dir, 'icons');
+    await mkdir(icons, { recursive: true });
+    const stamp = join(icons, `v${ASSETS_VERSION}`);
+    if (!existsSync(stamp)) {
+        const all = platform === 'win32' ? windowsTrayIcons() : macTrayIcons();
+        for (const [name, png] of Object.entries(all))
+            await writeFile(join(icons, name), png);
+        await writeFile(stamp, '');
+    }
+    if (platform === 'win32') {
+        const file = join(dir, 'tray.ps1');
+        await writeFile(file, Buffer.concat([Buffer.from([0xef, 0xbb, 0xbf]), Buffer.from(WINDOWS_TRAY_SCRIPT, 'utf8')]));
+        return file;
+    }
+    const file = join(dir, 'tray.js');
+    await writeFile(file, MAC_TRAY_SCRIPT);
+    return file;
+}
+/** 起显示脚本 */
+export function spawnTrayHelper(platform, file, dir, note, on) {
+    const env = { ...process.env, COTUTOR_TRAY_DIR: dir };
+    const child = platform === 'win32'
+        ? spawn('powershell.exe', ['-STA', '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', file], { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true, env })
+        : spawn('/usr/bin/osascript', ['-l', 'JavaScript', file], { stdio: ['pipe', 'pipe', 'pipe'], env });
+    child.once('error', (err) => { note(`显示脚本起不来:${err.message}`); });
+    child.once('exit', (code) => on.exit(code));
+    child.stdin?.on('error', () => undefined);
+    if (child.stdout)
+        createInterface({ input: child.stdout }).on('line', (line) => {
+            try {
+                on.message(JSON.parse(line));
+            }
+            catch {
+                note(`显示脚本:${line}`);
+            }
+        });
+    if (child.stderr)
+        createInterface({ input: child.stderr }).on('line', (line) => { if (line.trim())
+            note(`显示脚本:${line}`); });
+    return {
+        send(m) { child.stdin?.write(`${JSON.stringify(m)}\n`); },
+        close() { child.stdin?.end(); },
+    };
+}
+/** 打开地址或目录(Windows 不弹黑窗口) */
+export function openTarget(platform, target) {
+    const [cmd, args] = platform === 'darwin' ? ['/usr/bin/open', [target]] : platform === 'win32' ? ['cmd', ['/c', 'start', '', target]] : ['xdg-open', [target]];
+    const child = spawn(cmd, args, { stdio: 'ignore', windowsHide: true });
+    child.on('error', () => undefined);
+    child.unref();
+}
+/** 日志:一个文件,过 1 MB 换一次,只留上一份 */
+export function trayNote(dir) {
+    const file = join(dir, 'tray.log');
+    return (text) => {
+        try {
+            try {
+                if (statSync(file).size > LOG_MAX)
+                    renameSync(file, `${file}.1`);
+            }
+            catch { /* 还没有 */ }
+            appendFileSync(file, `${new Date().toISOString()} ${text}\n`);
+        }
+        catch { /* 写不了日志不能把图标带倒 */ }
+    };
+}
+/** 孩子叫什么、哪个端口:只读这两样,不加载 zod(托盘进程常驻,要轻);读不了就用服务名和缺省端口 */
+export async function inspectService(s) {
+    try {
+        const c = JSON.parse(await readFile(join(s.root, 'cotutor.json'), 'utf8'));
+        const kid = typeof c.kid?.name === 'string' && c.kid.name ? c.kid.name : typeof c.kid?.slug === 'string' && c.kid.slug ? c.kid.slug : s.name;
+        return { kid, port: typeof c.server?.port === 'number' ? c.server.port : DEFAULT_PORT };
+    }
+    catch {
+        return { kid: s.name, port: DEFAULT_PORT };
+    }
+}
+/** 真的依赖,给 runTray */
+export function realTrayDeps(host, dir, file, version) {
+    const note = trayNote(dir);
+    return {
+        platform: host.platform,
+        version,
+        note,
+        now: () => Date.now(),
+        list: () => listServices(host),
+        inspect: inspectService,
+        probe: (port) => probeHealth(port),
+        holder: async (port) => (await portHolder(host, port))?.name ?? null,
+        control: (root, what) => controlService(host, root, what),
+        open: (target) => openTarget(host.platform, target),
+        spawnHelper: (on) => spawnTrayHelper(host.platform, file, dir, note, on),
+    };
+}
+/** 登录项跑的命令 */
+export const trayArgs = (host, o = {}) => [o.node ?? process.execPath, o.bin ?? binPath(), 'tray', 'run', '--dir', trayDir(host)];
+/** macOS 的 LaunchAgent:登录就起,崩了拉起,以 0 退(点了退出)不拉 */
+export function trayPlist(args, dir, path) {
+    const str = (v) => `<string>${xml(v)}</string>`;
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!-- cotutor tray on 写的;改了会被下次盖掉。关掉:cotutor tray off -->
+<plist version="1.0">
+<dict>
+  <key>Label</key>${str(TRAY_LABEL)}
+  <key>ProgramArguments</key>
+  <array>
+${args.map((a) => `    ${str(a)}`).join('\n')}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>${str(path)}
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key><false/>
+  </dict>
+  <key>ThrottleInterval</key><integer>10</integer>
+  <key>ProcessType</key><string>Interactive</string>
+  <key>LimitLoadToSessionType</key><string>Aqua</string>
+  <key>StandardOutPath</key>${str(join(dir, 'launchd.log'))}
+  <key>StandardErrorPath</key>${str(join(dir, 'launchd.log'))}
+</dict>
+</plist>
+`;
+}
+async function stopWindowsTray(host, dir) {
+    const procs = parseProcs((await host.run('powershell.exe', psArgs(findTrayScript(dir)))).stdout);
+    for (const p of procs)
+        await host.run('taskkill.exe', ['/PID', String(p.pid), '/T', '/F']);
+}
+/** 装上并起来;已经装过就照现在的 node、bin 重写一遍再起(升级后新代码才生效)。started = false:登录项写好了,这个会话里起不来,下次登录出现 */
+export async function installTray(host, o = {}) {
+    if (!traySupported(host.platform))
+        throw new UsageError(`${host.platform} 上没做托盘图标:cotutor service status 看状态`);
+    const dir = trayDir(host);
+    await mkdir(dir, { recursive: true });
+    await rm(offMark(dir), { force: true });
+    const args = trayArgs(host, o);
+    if (host.platform === 'win32') {
+        await stopWindowsTray(host, dir);
+        const file = launcherFile(dir);
+        await writeFile(file, encodeLauncher(trayLauncher(winCommandLine(args))));
+        const reg = await host.run('reg.exe', ['add', RUN_KEY, '/v', TRAY_RUN_VALUE, '/t', 'REG_SZ', '/d', runValue(wscriptPath(host), file), '/f']);
+        if (reg.code !== 0)
+            throw new UsageError(`写登录项没成:${(reg.stderr || reg.stdout).trim()}`);
+        await host.run('reg.exe', ['delete', STARTUP_APPROVED_KEY, '/v', TRAY_RUN_VALUE, '/f']);
+        const r = await host.run(wscriptPath(host), ['//B', '//Nologo', file]);
+        return { file, started: r.code === 0 };
+    }
+    const file = plistFile(host);
+    await mkdir(join(host.home, 'Library', 'LaunchAgents'), { recursive: true });
+    await host.run('launchctl', ['bootout', `gui/${host.uid}/${TRAY_LABEL}`]);
+    await writeFile(file, trayPlist(args, dir, host.env.PATH ?? '/usr/bin:/bin'));
+    const r = await host.run('launchctl', ['bootstrap', `gui/${host.uid}`, file]);
+    return { file, started: r.code === 0 };
+}
+/** 卸掉:停下、删登录项。remember = 家长说不要(以后 service install 也不再装) */
+export async function removeTray(host, o = {}) {
+    if (!traySupported(host.platform))
+        return false;
+    const dir = trayDir(host);
+    const had = (await trayStatus(host)).installed;
+    if (host.platform === 'win32') {
+        await stopWindowsTray(host, dir);
+        await host.run('reg.exe', ['delete', RUN_KEY, '/v', TRAY_RUN_VALUE, '/f']);
+        await host.run('reg.exe', ['delete', STARTUP_APPROVED_KEY, '/v', TRAY_RUN_VALUE, '/f']);
+        await host.run('reg.exe', ['delete', `HKCU\\Software\\Classes\\AppUserModelId\\${TRAY_AUMID}`, '/f']);
+        await host.run('reg.exe', ['delete', `HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Notifications\\Settings\\${TRAY_AUMID}`, '/f']);
+        await rm(launcherFile(dir), { force: true });
+    }
+    else {
+        await host.run('launchctl', ['bootout', `gui/${host.uid}/${TRAY_LABEL}`]);
+        await rm(plistFile(host), { force: true });
+    }
+    if (o.remember) {
+        await mkdir(dir, { recursive: true });
+        await writeFile(offMark(dir), '');
+    }
+    return had;
+}
+export async function trayStatus(host) {
+    if (!traySupported(host.platform))
+        return { supported: false, installed: false, running: false, pid: null, off: false, autostart: null };
+    const dir = trayDir(host);
+    const off = existsSync(offMark(dir));
+    if (host.platform === 'win32') {
+        const installed = existsSync(launcherFile(dir));
+        const procs = parseProcs((await host.run('powershell.exe', psArgs(findTrayScript(dir)))).stdout);
+        const autostart = installed && (await host.run('reg.exe', ['query', RUN_KEY, '/v', TRAY_RUN_VALUE])).code === 0 && !startupDisabled((await host.run('reg.exe', ['query', STARTUP_APPROVED_KEY, '/v', TRAY_RUN_VALUE])).stdout);
+        return { supported: true, installed, running: procs.length > 0, pid: procs[0]?.pid ?? null, off, autostart };
+    }
+    const installed = existsSync(plistFile(host));
+    const r = await host.run('launchctl', ['print', `gui/${host.uid}/${TRAY_LABEL}`]);
+    const st = r.code === 0 ? parseLaunchctlPrint(r.stdout) : { running: false, pid: null };
+    return { supported: true, installed, running: st.running, pid: st.pid, off, autostart: null };
+}
+/** service install 时跟着装:没做的系统、家长关掉过都跳过;返回给人看的结果 */
+export async function ensureTray(host, o = {}) {
+    if (!traySupported(host.platform))
+        return 'unsupported';
+    if (existsSync(offMark(trayDir(host))))
+        return 'off';
+    return (await installTray(host, o)).started ? 'started' : 'later';
+}
+/** 服务卸完了:图标也撤(不算家长说不要,以后再装服务还会带上) */
+export async function dropTrayIfNoServices(host) {
+    if (!traySupported(host.platform))
+        return false;
+    if ((await listServices(host)).length)
+        return false;
+    return removeTray(host);
+}

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

@@ -1,2 +1,2 @@
 /** 命令用法(cotutor --help;技能 cotutor-analyze 的 references/命令与文件.md 从这里取分析用的那几行,所以放单独文件,别的模块 import 不会跑到 CLI) */
-export declare const USAGE = "\u7528\u6CD5:\n  cotutor init <slug> [--dir <path>] [--name <\u5B69\u5B50\u540D>] [--grade <1-6>] [--port <n>]   \u5EFA ~/cotutor/<slug>/ \u9AA8\u67B6(\u5E42\u7B49\u8865\u7F3A;\u9ED8\u8BA4\u4E8C\u5E74\u7EA7\u6559\u5B66\u5305)\n  cotutor grades [--json]                                          \u5217\u51FA\u672C\u5305\u53EF\u5B89\u88C5\u7684\u5E74\u7EA7\u6559\u5B66\u5305\n  cotutor doctor [--workspace <dir>] [--json] [--live]                 \u9010\u9879\u4F53\u68C0;--live \u771F\u8D77\u4E00\u6B21\u8001\u5E08\u4E0E\u914D\u97F3(\u82B1\u4E00\u5206\u94B1)\u628A API \u5C42\u7684\u5751\u6446\u51FA\u6765\n  cotutor upgrade [--workspace <dir>] [--force <\u8001\u5E08>]...                \u8001\u5E08\u6587\u4EF6\u3001activity \u4E0E skill \u6362\u65B0\u7248:\u6CA1\u6539\u8FC7\u7684\u76F4\u63A5\u6362,\u6539\u8FC7\u7684\u53EA\u62A5 diff(--force <\u8001\u5E08> \u6216 --force <\u8001\u5E08>/<\u540D> \u624D\u8986\u76D6,\u539F\u6587\u7559 .bak)\n  cotutor upgrade --config [--dry-run] [--workspace <dir>]              cotutor.json \u8865\u7F3A:\u65B0\u51FA\u5382\u8001\u5E08 / \u8FD0\u884C\u65F6 / \u547D\u4EE4\u6A21\u677F\u65D7\u6807(\u53EA\u52A0\u7F3A\u7684,\u4F60\u6539\u8FC7\u7684\u503C\u4E0D\u52A8)\n  cotutor add <\u8001\u5E08\u540D> --display <\u663E\u793A\u540D> [--subject <\u5B66\u79D1>] [--avatar <emoji|\u56FE\u7247\u76F8\u5BF9\u8DEF\u5F84>] [--hidden]   \u52A0\u4E00\u4F4D\u81EA\u5BB6\u7684\u8001\u5E08:\u51FA\u6A21\u677F\u6587\u4EF6\u3001\u8FDB cotutor.json\u3001\u5EFA\u76EE\u5F55(\u540D\u5B57\u4EE5 -tutor \u7ED3\u5C3E\u7684\u662F\u8001\u5E08,figshot \u7ED9\u5B83\u505A\u5934\u50CF)\n  cotutor add-theme <\u4E3B\u9898\u540D> [--from <\u4E3B\u9898>] [--workspace <dir>]       \u52A0\u4E00\u4E2A\u81EA\u5BB6\u7684\u4E3B\u9898:\u62F7\u4E00\u4EFD(\u7F3A\u7701\u51FA\u5382\u7684 default)\u5230 themes/<\u4E3B\u9898\u540D>/,\u6539 cotutor.json \u7684 kid.theme \u6362\u8FC7\u53BB\n  cotutor serve [--workspace <dir>] [--port <n>] [--http] [--trace] [--open-qr]   \u8D77\u670D\u52A1(\u4E00 workspace \u4E00\u8FDB\u7A0B;~/.config/cotutor/certs/ \u6709\u8BC1\u4E66\u5C31\u8D70 HTTPS;--trace \u6BCF\u4E00\u8F6E\u7684\u4E8B\u4EF6\u6309\u9053\u6253\u5370;/dev/qr \u662F\u626B\u7801\u9875,--open-qr \u987A\u624B\u6253\u5F00)\n  cotutor pin [off | status] [--pin <\u6570\u5B57>] [--json]                       \u5BB6\u957F\u7AEF /parent \u4E0E\u5DE5\u4F5C\u53F0 /dev \u7684\u9501:\u673A\u5668\u7EA7 PIN(\u6240\u6709 workspace \u5171\u7528),iPad \u4E0A\u8F93\u4E00\u6B21\u3001\u8FD9\u53F0\u7535\u8111\u514D\u5BC6;\u6CA1\u8BBE\u5C31\u5168\u5F00(\u5BB6\u957F\u5728\u65C1\u8FB9\u53EF\u4EE5\u4E0D\u8BBE);off \u64A4\u6389\n  cotutor cert [--host <\u540D\u6216IP>]...                                      \u7528 mkcert \u5EFA\u8FD9\u53F0\u673A\u5668\u7684\u81EA\u7B7E\u8BC1\u4E66\u5230 ~/.config/cotutor/certs/(iPad / iPhone \u4E0A\u5F55\u97F3\u8981 HTTPS;\u6240\u6709 workspace \u5171\u7528)\n  cotutor send <\u8001\u5E08> [<\u6D88\u606F>] [--from kid|system] [--runtime <\u540D>] [--new] [--photo a.jpg,b.png] [--activity <\u540D> [--param '\u540D=\u503C;\u540D=\u503C']] [--lane main,tts] [--quiet]   \u7EC8\u7AEF\u91CC\u53D1\u4E00\u6761,\u73B0\u573A\u6309\u9053\u6253\u5370\u6BCF\u9053\u5DE5\u5E8F\u7684\u4E8B\u4EF6,\u8BF4\u5B8C\u6253\u5370\u7ED3\u679C(\u4E0E\u9875\u9762\u540C\u4E00\u6761\u8DEF;--new \u5F00\u65B0\u8BDD\u9898;--photo \u5E26\u4F5C\u4E1A\u7167\u7247,\u62F7\u8FDB captures/,\u6709\u7167\u7247\u65F6\u6D88\u606F\u53EF\u4EE5\u7A7A;--activity \u50CF\u5B69\u5B50\u70B9\u4E86\u9996\u9875\u7684 activity \u6309\u94AE,\u65B0\u5F00\u8BDD\u9898,\u53C2\u6570\u540C\u6309\u94AE\u4E0B\u9762\u90A3\u51E0\u884C;--quiet \u53EA\u8981\u7ED3\u679C)\n  cotutor pack <\u8001\u5E08> [<\u6D88\u606F>] [--from kid|system] [--at <ISO\u65F6\u95F4>] [--activity <\u540D> [--param '\u540D=\u503C;\u540D=\u503C']] [--json]   \u5E72\u8DD1\u4E0A\u4E0B\u6587\u5305(--activity \u770B activity \u8BDD\u9898\u7B2C\u4E00\u6761\u8001\u5E08\u62FF\u5230\u4EC0\u4E48):\u4E0D\u8D77\u6A21\u578B,\u6253\u5370\u73B0\u5728\u4F1A\u53D1\u7ED9\u8001\u5E08\u7684\u90A3\u4EFD + \u6BCF\u6BB5\u6765\u81EA\u54EA\u4E2A\u6587\u4EF6\u3001\u90A3\u91CC\u4E00\u5171\u51E0\u6761\u3001\u6309\u653F\u7B56\u5E26\u4E86\u51E0\u6761(\u6539\u4E86\u6863\u6848 / \u65E5\u8BB0 / \u8BA1\u5212\u7ACB\u523B\u770B\u6548\u679C)\n  cotutor replay <\u8001\u5E08> <job> [<\u65E5\u671F>] [--runtime <\u540D>] [--json]   \u56DE\u653E\u4E00\u8F6E:\u540C\u4E00\u95EE\u6309\u73B0\u5728\u7684 vault \u4E0E\u63D0\u793A\u8BCD\u518D\u8DD1\u4E00\u904D(\u843D evals/,\u4E0D\u8FDB\u5B69\u5B50\u7684\u5BF9\u8BDD\u3001\u4E0D\u914D\u97F3),\u8DD1\u5B8C\u5E76\u6392\u6253\u5370\u4E0A\u4E0B\u6587\u5305 / \u8BB2\u7A3F / \u5361 / \u8BFB\u4E86\u4EC0\u4E48\u7684 diff\n  cotutor compare <\u8001\u5E08> [<evalJob>] [<\u65E5\u671F>] [--json]                   \u518D\u770B\u4E00\u6B21\u56DE\u653E\u7684\u5BF9\u7167(\u4E0D\u7ED9 evalJob \u5C31\u5217\u8FD9\u5929\u56DE\u653E\u8FC7\u54EA\u4E9B)\n  cotutor show <\u8001\u5E08> <job> [<\u65E5\u671F>] [--json] [--evals] [--workspace <dir>]   \u770B\u4E00\u8F6E:\u95EE\u4E86\u4EC0\u4E48\u3001\u4E0A\u4E0B\u6587\u5305\u3001\u5F53\u65F6\u7684\u8001\u5E08\u6587\u4EF6\u4E0E\u6280\u80FD hash\u3001\u8BB2\u7A3F\u4E0E\u5361\u3001\u8BFB\u4E86\u4EC0\u4E48\u3001token \u4E0E\u7528\u65F6\u3001\u7ED9\u5BB6\u957F\u7684\u5C3E\u5DF4;--json \u662F\u5BB6\u957F\u7AEF\u300C\u770B\u539F\u6587\u300D\u540C\u4E00\u4EFD\u6570\u636E,\u7ED9\u7F16\u7A0B\u52A9\u624B\u5206\u6790\u7528\n  cotutor trace <\u8001\u5E08> <job> [<\u65E5\u671F>] [--lane \u2026] [--workspace <dir>]     \u56DE\u653E\u4E00\u8F6E\u7684\u4E8B\u4EF6(<\u65E5\u671F>.<job>.events.jsonl;\u6392\u67E5\u6628\u5929\u90A3\u8F6E\u7528)\n  cotutor rate <\u8001\u5E08> <\u8BDD\u9898> <1-5> [--date <\u65E5\u671F>]                       \u7ED9\u4E00\u4E2A\u8BDD\u9898\u6253\u661F(\u4E0E\u5BB6\u957F\u7AEF\u540C\u4E00\u6761\u8DEF;\u2265 vault.keepScore \u7684\u8BDD\u9898\u8BB0\u8D26\u65F6\u6458\u8981\u624D\u8FDB\u65E5\u8BB0)\n  cotutor bookkeep <\u8001\u5E08> [--date <\u65E5\u671F>] [--thread <\u8BDD\u9898>]...           \u8BB0\u8D26:\u8FD9\u5929\u6BCF\u4E2A\u8FD8\u6CA1\u8BB0\u8FC7\u7684\u8BDD\u9898\u5404\u8D77\u4E00\u8F6E\u8BB0\u8D26\u4EFB\u52A1,\u8001\u5E08\u56DE\u300C## \u8BB0\u8D26\u300D,\u5E94\u7528\u5199\u8FDB vault \u7684\u65E5\u8BB0(\u8BDD\u9898\u540D\u3001\u5B69\u5B50\u95EE\u3001\u6458\u8981\u3001\u89C2\u5BDF)\n  cotutor home check [--published] [--json]                           \u68C0\u67E5\u9996\u9875\u8349\u7A3F home/draft.md(\u6216\u5DF2\u53D1\u5E03\u7684\u90A3\u4EFD):\u5B69\u5B50\u4F1A\u770B\u5230\u54EA\u51E0\u5F20\u5361\u3001\u6BCF\u4F4D\u8001\u5E08\u7684\u6309\u94AE\u3001\u8981\u6539\u7684\u4E0E\u63D0\u9192(\u5E26\u884C\u53F7);\u4E0D\u82B1\u94B1\n  cotutor home publish [--force] [--from <\u6587\u4EF6>] [--json]              \u53D1\u5E03\u9996\u9875:\u68C0\u67E5 \u2192 \u7559\u5386\u53F2 home/history/<id>.md \u2192 \u5199 home/published.json(\u5B69\u5B50\u7AEF\u53EA\u8BFB\u5B83);\u6709\u8981\u6539\u7684\u4E0D\u53D1,--force \u4E22\u6389\u90A3\u51E0\u5F20\u7167\u53D1;--from \u53D1\u53E6\u4E00\u4EFD(\u5982\u5386\u53F2)\n  cotutor home show [--json]                                          \u73B0\u5728\u53D1\u5E03\u7684\u662F\u54EA\u4EFD\u3001\u51E0\u5929\u524D\u3001\u6BCF\u4E2A\u6309\u94AE\u88AB\u70B9\u4E86\u51E0\u6B21(\u54EA\u5929\u3001\u54EA\u4E2A\u8BDD\u9898)\n  cotutor activity check [<\u8001\u5E08> [<\u540D>]] [--json]                      \u68C0\u67E5 activity \u6587\u4EF6(agents/<\u8001\u5E08>/activities/<\u540D>.md):\u5BB6\u957F\u586B\u7684\u3001\u5E94\u7528\u7B97\u7684\u3001\u5E94\u7528\u62E6\u7684\u3001\u88C1\u6BB5\u3001\u63D2\u69FD\u3001\u6B63\u6587\u7528\u7684\u5361\u3001\u7B2C\u4E00\u53E5\u4E0E\u6536(\u5E26\u884C\u53F7);\u4E0D\u82B1\u94B1\n  cotutor activity eval <\u8001\u5E08> <\u540D> [--runs <n>] [--only <\u4F8B\u5B50>] [--kid-model <\u5343\u95EE\u6A21\u578B>] [--json]   \u7167 <\u540D>.\u4F8B\u5B50.md \u8DD1:\u771F\u8001\u5E08 + \u6A21\u62DF\u5B69\u5B50(\u5343\u95EE,\u7F3A\u7701 qwen3.8-flash,\u6709 Token Plan \u8D70\u5B83)\u591A\u8F6E,\u5224\u53EA\u770B\u677F\u4E66;\u4E00\u4E2A\u4F8B\u5B50\u8DD1 n \u6B21(\u7F3A\u7701 3)\u6B21\u6B21\u90FD\u8FC7\u624D\u7B97\u8FC7;\u843D evals/,\u753B\u5BB6\u662F\u5047\u7684;\u82B1\u94B1\n  cotutor chalk <check|build|bake|snap|dub> <scene.ts|\u8BFE\u5305 id> [...]   \u505A\u5C0F\u8BFE\u5802\u7684\u8BFE\u5305:check \u6821\u9A8C\u573A\u666F\u3001build \u51FA\u8BFE\u5305\u5230 bundles/\u3001bake \u70E4\u753B\u9762\u3001snap \u6BCF\u6B65\u622A\u56FE\u3001dub \u914D\u97F3(cotutor chalk \u770B\u5404\u81EA\u7684\u9009\u9879;bake / snap \u8981\u672C\u673A\u7684 Chrome)\n  cotutor mock [--port <n>] [--scenario normal|nokey] [--delay <ms>] [--http]   \u4E0D\u7ECF\u771F\u5B9E\u8001\u5E08\u4E0E\u767E\u70BC,\u7528\u56FA\u5B9A\u7684\u677F\u4E66 JSON \u8D77\u5B69\u5B50\u7AEF,\u6D4B\u524D\u7AEF\u4EA4\u4E92\u4E0E\u6E32\u67D3(\u4E0D\u9700\u8981 workspace;\u8001\u5E08\u90FD\u8D70\u5B9E\u65F6\u8001\u5E08\u9875,\u5047\u5634\u7167\u811A\u672C\u5FF5\u9759\u97F3\u7684\u58F0\u97F3;nokey = \u6CA1\u914D\u767E\u70BC,\u5B69\u5B50\u7AEF\u53EA\u51FA\u300C\u8001\u5E08\u4EEC\u8FD8\u6CA1\u5230\u300D)\n  cotutor --version | --help\nworkspace\u89E3\u6790:--workspace > COTUTOR_WORKSPACE > cwd \u6216\u7956\u5148\u6709 cotutor.json > ~/.config/cotutor/config.json > ~/cotutor/ \u4E0B\u552F\u4E00\u7684\u5B69\u5B50\u76EE\u5F55\n";
+export declare const USAGE = "\u7528\u6CD5:\n  cotutor init <slug> [--dir <path>] [--name <\u5B69\u5B50\u540D>] [--grade <1-6>] [--port <n>]   \u5EFA ~/cotutor/<slug>/ \u9AA8\u67B6(\u5E42\u7B49\u8865\u7F3A;\u9ED8\u8BA4\u4E8C\u5E74\u7EA7\u6559\u5B66\u5305;\u7AEF\u53E3\u5728\u8FD9\u91CC\u9009\u4E00\u6B21\u5199\u8FDB cotutor.json:443 \u4F18\u5148,\u4E0D\u884C\u5C31 8443\u30018445\u2026,\u4EE5\u540E\u4E0D\u53D8)\n  cotutor grades [--json]                                          \u5217\u51FA\u672C\u5305\u53EF\u5B89\u88C5\u7684\u5E74\u7EA7\u6559\u5B66\u5305\n  cotutor doctor [--workspace <dir>] [--json] [--live]                 \u9010\u9879\u4F53\u68C0;--live \u771F\u8FDE\u4E00\u6B21\u767E\u70BC\u5B9E\u65F6\u6A21\u578B\u3001\u771F\u5408\u6210\u4E00\u53E5\u914D\u97F3(\u82B1\u4E00\u5206\u94B1)\u628A API \u5C42\u7684\u5751\u6446\u51FA\u6765(\u771F\u8DD1\u8001\u5E08\u7528 cotutor send)\n  cotutor upgrade [--workspace <dir>] [--force <\u8001\u5E08>]...                \u8001\u5E08\u6587\u4EF6\u3001activity \u4E0E skill \u6362\u65B0\u7248:\u6CA1\u6539\u8FC7\u7684\u76F4\u63A5\u6362,\u6539\u8FC7\u7684\u53EA\u62A5 diff(--force <\u8001\u5E08> \u6216 --force <\u8001\u5E08>/<\u540D> \u624D\u8986\u76D6,\u539F\u6587\u7559 .bak)\n  cotutor upgrade --config [--dry-run] [--workspace <dir>]              cotutor.json \u8865\u7F3A:\u65B0\u51FA\u5382\u8001\u5E08 / \u8FD0\u884C\u65F6 / \u547D\u4EE4\u6A21\u677F\u65D7\u6807(\u53EA\u52A0\u7F3A\u7684,\u4F60\u6539\u8FC7\u7684\u503C\u4E0D\u52A8)\n  cotutor add <\u8001\u5E08\u540D> --display <\u663E\u793A\u540D> [--subject <\u5B66\u79D1>] [--avatar <emoji|\u56FE\u7247\u76F8\u5BF9\u8DEF\u5F84>] [--hidden]   \u52A0\u4E00\u4F4D\u81EA\u5BB6\u7684\u8001\u5E08:\u51FA\u6A21\u677F\u6587\u4EF6\u3001\u8FDB cotutor.json\u3001\u5EFA\u76EE\u5F55(\u540D\u5B57\u4EE5 -tutor \u7ED3\u5C3E\u7684\u662F\u8001\u5E08,figshot \u7ED9\u5B83\u505A\u5934\u50CF)\n  cotutor add-theme <\u4E3B\u9898\u540D> [--from <\u4E3B\u9898>] [--workspace <dir>]       \u52A0\u4E00\u4E2A\u81EA\u5BB6\u7684\u4E3B\u9898:\u62F7\u4E00\u4EFD(\u7F3A\u7701\u51FA\u5382\u7684 default)\u5230 themes/<\u4E3B\u9898\u540D>/,\u6539 cotutor.json \u7684 kid.theme \u6362\u8FC7\u53BB\n  cotutor serve [--workspace <dir>] [--port <n>] [--http] [--trace] [--open] [--log-dir <\u76EE\u5F55>]   \u5728\u7EC8\u7AEF\u91CC\u8D77\u670D\u52A1(\u4E00 workspace \u4E00\u8FDB\u7A0B;~/.config/cotutor/certs/ \u6709\u8BC1\u4E66\u5C31\u8D70 HTTPS;--trace \u6BCF\u4E00\u8F6E\u7684\u4E8B\u4EF6\u6309\u9053\u6253\u5370;\u53EA\u6253\u5370\u5BB6\u957F\u7AEF\u9996\u9875\u7684\u5730\u5740,\u5B69\u5B50\u7684\u5E73\u677F\u5728\u90A3\u91CC\u626B\u7801;--open \u987A\u624B\u6253\u5F00,\u65E7\u540D --open-qr \u7167\u6837\u8BA4;--log-dir \u8F93\u51FA\u6309\u5929\u843D\u6587\u4EF6,\u540E\u53F0\u670D\u52A1\u7528;\u5173\u4E86\u7EC8\u7AEF\u5C31\u505C,\u4E00\u76F4\u5F00\u7740\u7528 cotutor service)\n  cotutor open [--workspace <dir>] [--sandbox] [--print] [--json]        \u6253\u5F00\u5BB6\u957F\u7AEF(\u8BFB cotutor.json,\u4E0D\u7528\u8BB0\u7AEF\u53E3);--sandbox \u5F00\u8BD5\u7528\u7684\u90A3\u4E2A(\u7AEF\u53E3\u6C38\u8FDC\u662F\u771F\u7684 +1);--print \u53EA\u6253\u5370\u5730\u5740;\u6CA1\u5728\u8DD1\u5C31\u8BF4\u600E\u4E48\u8D77,\u4EE5 1 \u9000\n  cotutor service install | uninstall | start | stop | restart [--workspace <dir>] [--no-tray]   \u628A serve \u88C5\u6210\u8FD9\u53F0\u7535\u8111\u7684\u540E\u53F0\u670D\u52A1(macOS launchd\u3001Linux systemd \u7528\u6237\u670D\u52A1\u3001Windows \u7528\u6237\u7684\u767B\u5F55\u9879,\u90FD\u4E0D\u8981\u7BA1\u7406\u5458):\u767B\u5F55\u540E\u81EA\u5DF1\u8D77\u6765\u3001\u5D29\u4E86 10 \u79D2\u540E\u518D\u8D77\u3001\u65E5\u5FD7\u6309\u5929\u843D\u6587\u4EF6\u7559 14 \u5929;\u4E00\u4E2A workspace \u4E00\u4E2A;\u6362\u4E86 node \u7248\u672C\u6216\u5305\u632A\u4E86\u5730\u65B9\u518D install \u4E00\u6B21\n  cotutor tray on | off | status [--json]                             \u83DC\u5355\u680F / \u4EFB\u52A1\u680F\u56FE\u6807(macOS\u3001Windows;service install \u65F6\u4E00\u8D77\u88C5,--no-tray \u4E0D\u5E26):\u6B63\u5E38\u65F6\u53EA\u6709 logo,\u6709\u4E8B\u51FA\u6A59\u70B9,\u6CA1\u5728\u8DD1\u65F6\u53D8\u6DE1\u52A0\u7EA2\u70B9\u5E76\u901A\u77E5\u4E00\u6B21;\u70B9\u5B83\u770B\u72B6\u6001\u3001\u6253\u5F00\u5BB6\u957F\u7AEF\u3001\u91CD\u542F\u3001\u770B\u65E5\u5FD7\u3001\u9000\u51FA;off \u5173\u6389\u5E76\u8BB0\u4F4F\n  cotutor service status [--json] | logs [--lines <n>] [--follow]      \u540E\u53F0\u670D\u52A1\u5728\u4E0D\u5728\u8DD1\u3001\u7AEF\u53E3\u7B54\u4E0D\u7B54\u5E94\u3001\u8DD1\u7684\u54EA\u4E2A\u7248\u672C\u3001vault \u8BFB\u4E0D\u8BFB\u5F97\u5230\u3001\u65E5\u5FD7\u5728\u54EA;logs \u770B\u6700\u8FD1\u7684\u65E5\u5FD7\n  cotutor pin [off | status] [--pin <\u6570\u5B57>] [--json]                       \u5BB6\u957F\u7AEF /parent \u4E0E\u5DE5\u4F5C\u53F0 /dev \u7684\u9501:\u673A\u5668\u7EA7 PIN(\u6240\u6709 workspace \u5171\u7528),iPad \u4E0A\u8F93\u4E00\u6B21\u3001\u8FD9\u53F0\u7535\u8111\u514D\u5BC6;\u6CA1\u8BBE\u5C31\u5168\u5F00(\u5BB6\u957F\u5728\u65C1\u8FB9\u53EF\u4EE5\u4E0D\u8BBE);off \u64A4\u6389\n  cotutor cert [--host <\u540D\u6216IP>]...                                      \u7528 mkcert \u5EFA\u8FD9\u53F0\u673A\u5668\u7684\u81EA\u7B7E\u8BC1\u4E66\u5230 ~/.config/cotutor/certs/(\u5E73\u677F\u3001\u624B\u673A\u4E0A\u5F55\u97F3\u8981 HTTPS;\u6240\u6709 workspace \u5171\u7528)\n  cotutor send <\u8001\u5E08> [<\u6D88\u606F>] [--from kid|system] [--runtime <\u540D>] [--new] [--photo a.jpg,b.png] [--activity <\u540D> [--param '\u540D=\u503C;\u540D=\u503C']] [--lane main,tts] [--quiet]   \u7EC8\u7AEF\u91CC\u53D1\u4E00\u6761,\u73B0\u573A\u6309\u9053\u6253\u5370\u6BCF\u9053\u5DE5\u5E8F\u7684\u4E8B\u4EF6,\u8BF4\u5B8C\u6253\u5370\u7ED3\u679C(\u5B69\u5B50\u7684\u8BDD\u7167\u5B9E\u65F6\u5199,\u540C\u5B69\u5B50\u7AEF:\u4E0A\u4E0B\u6587\u5305\u5E26 live:\u3001\u4E0D\u8865\u63D0\u95EE\u5361,\u53EA\u662F\u6CA1\u6709\u5634;--from system \u4E0D\u7B97;--new \u5F00\u65B0\u8BDD\u9898;--photo \u5E26\u4F5C\u4E1A\u7167\u7247,\u62F7\u8FDB captures/,\u6709\u7167\u7247\u65F6\u6D88\u606F\u53EF\u4EE5\u7A7A;--activity \u50CF\u5B69\u5B50\u70B9\u4E86\u9996\u9875\u7684 activity \u6309\u94AE,\u65B0\u5F00\u8BDD\u9898,\u53C2\u6570\u540C\u6309\u94AE\u4E0B\u9762\u90A3\u51E0\u884C;--quiet \u53EA\u8981\u7ED3\u679C)\n  cotutor pack <\u8001\u5E08> [<\u6D88\u606F>] [--from kid|system] [--at <ISO\u65F6\u95F4>] [--activity <\u540D> [--param '\u540D=\u503C;\u540D=\u503C']] [--json]   \u5E72\u8DD1\u4E0A\u4E0B\u6587\u5305(--activity \u770B activity \u8BDD\u9898\u7B2C\u4E00\u6761\u8001\u5E08\u62FF\u5230\u4EC0\u4E48):\u4E0D\u8D77\u6A21\u578B,\u6253\u5370\u73B0\u5728\u4F1A\u53D1\u7ED9\u8001\u5E08\u7684\u90A3\u4EFD + \u6BCF\u6BB5\u6765\u81EA\u54EA\u4E2A\u6587\u4EF6\u3001\u90A3\u91CC\u4E00\u5171\u51E0\u6761\u3001\u6309\u653F\u7B56\u5E26\u4E86\u51E0\u6761(\u6539\u4E86\u6863\u6848 / \u65E5\u8BB0 / \u8BA1\u5212\u7ACB\u523B\u770B\u6548\u679C)\n  cotutor replay <\u8001\u5E08> <job> [<\u65E5\u671F>] [--runtime <\u540D>] [--json]   \u56DE\u653E\u4E00\u8F6E:\u540C\u4E00\u95EE\u6309\u73B0\u5728\u7684 vault \u4E0E\u63D0\u793A\u8BCD\u518D\u8DD1\u4E00\u904D(\u843D evals/,\u4E0D\u8FDB\u5B69\u5B50\u7684\u5BF9\u8BDD\u3001\u4E0D\u914D\u97F3),\u8DD1\u5B8C\u5E76\u6392\u6253\u5370\u4E0A\u4E0B\u6587\u5305 / \u8BB2\u7A3F / \u5361 / \u8BFB\u4E86\u4EC0\u4E48\u7684 diff\n  cotutor compare <\u8001\u5E08> [<evalJob>] [<\u65E5\u671F>] [--json]                   \u518D\u770B\u4E00\u6B21\u56DE\u653E\u7684\u5BF9\u7167(\u4E0D\u7ED9 evalJob \u5C31\u5217\u8FD9\u5929\u56DE\u653E\u8FC7\u54EA\u4E9B)\n  cotutor show <\u8001\u5E08> <job> [<\u65E5\u671F>] [--json] [--evals] [--workspace <dir>]   \u770B\u4E00\u8F6E:\u95EE\u4E86\u4EC0\u4E48\u3001\u4E0A\u4E0B\u6587\u5305\u3001\u5F53\u65F6\u7684\u8001\u5E08\u6587\u4EF6\u4E0E\u6280\u80FD hash\u3001\u8BB2\u7A3F\u4E0E\u5361\u3001\u8BFB\u4E86\u4EC0\u4E48\u3001token \u4E0E\u7528\u65F6\u3001\u7ED9\u5BB6\u957F\u7684\u5C3E\u5DF4;--json \u662F\u5BB6\u957F\u7AEF\u300C\u770B\u539F\u6587\u300D\u540C\u4E00\u4EFD\u6570\u636E,\u7ED9\u7F16\u7A0B\u52A9\u624B\u5206\u6790\u7528\n  cotutor trace <\u8001\u5E08> <job> [<\u65E5\u671F>] [--lane \u2026] [--workspace <dir>]     \u56DE\u653E\u4E00\u8F6E\u7684\u4E8B\u4EF6(<\u65E5\u671F>.<job>.events.jsonl;\u6392\u67E5\u6628\u5929\u90A3\u8F6E\u7528)\n  cotutor rate <\u8001\u5E08> <\u8BDD\u9898> <1-5> [--date <\u65E5\u671F>]                       \u7ED9\u4E00\u4E2A\u8BDD\u9898\u6253\u661F(\u4E0E\u5BB6\u957F\u7AEF\u540C\u4E00\u6761\u8DEF;\u2265 vault.keepScore \u7684\u8BDD\u9898\u8BB0\u8D26\u65F6\u6458\u8981\u624D\u8FDB\u65E5\u8BB0)\n  cotutor bookkeep <\u8001\u5E08> [--date <\u65E5\u671F>] [--thread <\u8BDD\u9898>]...           \u8BB0\u8D26:\u8FD9\u5929\u6BCF\u4E2A\u8FD8\u6CA1\u8BB0\u8FC7\u7684\u8BDD\u9898\u5404\u8D77\u4E00\u8F6E\u8BB0\u8D26\u4EFB\u52A1,\u8001\u5E08\u56DE\u300C## \u8BB0\u8D26\u300D,\u5E94\u7528\u5199\u8FDB vault \u7684\u65E5\u8BB0(\u8BDD\u9898\u540D\u3001\u5B69\u5B50\u95EE\u3001\u6458\u8981\u3001\u89C2\u5BDF)\n  cotutor home check [--published] [--json]                           \u68C0\u67E5\u9996\u9875\u8349\u7A3F home/draft.md(\u6216\u5DF2\u53D1\u5E03\u7684\u90A3\u4EFD):\u5B69\u5B50\u4F1A\u770B\u5230\u54EA\u51E0\u5F20\u5361\u3001\u6BCF\u4F4D\u8001\u5E08\u7684\u6309\u94AE\u3001\u8981\u6539\u7684\u4E0E\u63D0\u9192(\u5E26\u884C\u53F7);\u4E0D\u82B1\u94B1\n  cotutor home publish [--force] [--from <\u6587\u4EF6>] [--json]              \u53D1\u5E03\u9996\u9875:\u68C0\u67E5 \u2192 \u7559\u5386\u53F2 home/history/<id>.md \u2192 \u5199 home/published.json(\u5B69\u5B50\u7AEF\u53EA\u8BFB\u5B83);\u6709\u8981\u6539\u7684\u4E0D\u53D1,--force \u4E22\u6389\u90A3\u51E0\u5F20\u7167\u53D1;--from \u53D1\u53E6\u4E00\u4EFD(\u5982\u5386\u53F2)\n  cotutor home show [--json]                                          \u73B0\u5728\u53D1\u5E03\u7684\u662F\u54EA\u4EFD\u3001\u51E0\u5929\u524D\u3001\u6BCF\u4E2A\u6309\u94AE\u88AB\u70B9\u4E86\u51E0\u6B21(\u54EA\u5929\u3001\u54EA\u4E2A\u8BDD\u9898)\n  cotutor activity check [<\u8001\u5E08> [<\u540D>]] [--json]                      \u68C0\u67E5 activity \u6587\u4EF6(agents/<\u8001\u5E08>/activities/<\u540D>.md):\u5BB6\u957F\u586B\u7684\u3001\u5E94\u7528\u7B97\u7684\u3001\u5E94\u7528\u62E6\u7684\u3001\u88C1\u6BB5\u3001\u63D2\u69FD\u3001\u6B63\u6587\u7528\u7684\u5361\u3001\u7B2C\u4E00\u53E5\u4E0E\u6536(\u5E26\u884C\u53F7);\u4E0D\u82B1\u94B1\n  cotutor activity eval <\u8001\u5E08> <\u540D> [--runs <n>] [--only <\u4F8B\u5B50>] [--kid-model <\u5343\u95EE\u6A21\u578B>] [--json]   \u7167 <\u540D>.\u4F8B\u5B50.md \u8DD1:\u771F\u8001\u5E08 + \u6A21\u62DF\u5B69\u5B50(\u5343\u95EE,\u7F3A\u7701 qwen3.8-flash,\u6709 Token Plan \u8D70\u5B83)\u591A\u8F6E(\u7167\u5B9E\u65F6\u5199,\u540C\u5B69\u5B50\u7AEF),\u5224\u53EA\u770B\u677F\u4E66;\u4E00\u4E2A\u4F8B\u5B50\u8DD1 n \u6B21(\u7F3A\u7701 3)\u6B21\u6B21\u90FD\u8FC7\u624D\u7B97\u8FC7;\u843D evals/,\u753B\u5BB6\u662F\u5047\u7684;\u82B1\u94B1\n  cotutor chalk <check|build|bake|snap|dub> <scene.ts|\u8BFE\u5305 id> [...]   \u505A\u5C0F\u8BFE\u5802\u7684\u8BFE\u5305:check \u6821\u9A8C\u573A\u666F\u3001build \u51FA\u8BFE\u5305\u5230 bundles/\u3001bake \u70E4\u753B\u9762\u3001snap \u6BCF\u6B65\u622A\u56FE\u3001dub \u914D\u97F3(cotutor chalk \u770B\u5404\u81EA\u7684\u9009\u9879;bake / snap \u8981\u672C\u673A\u7684 Chrome)\n  cotutor mock [--port <n>] [--scenario normal|nokey] [--delay <ms>] [--http]   \u4E0D\u7ECF\u771F\u5B9E\u8001\u5E08\u4E0E\u767E\u70BC,\u7528\u56FA\u5B9A\u7684\u677F\u4E66 JSON \u8D77\u5B69\u5B50\u7AEF,\u6D4B\u524D\u7AEF\u4EA4\u4E92\u4E0E\u6E32\u67D3(\u4E0D\u9700\u8981 workspace;\u8001\u5E08\u90FD\u8D70\u5B9E\u65F6\u8001\u5E08\u9875,\u5047\u5634\u7167\u811A\u672C\u5FF5\u9759\u97F3\u7684\u58F0\u97F3;nokey = \u6CA1\u914D\u767E\u70BC,\u5B69\u5B50\u7AEF\u53EA\u51FA\u300C\u8001\u5E08\u4EEC\u8FD8\u6CA1\u5230\u300D)\n  cotutor --version | --help\nworkspace\u89E3\u6790:--workspace > COTUTOR_WORKSPACE > cwd \u6216\u7956\u5148\u6709 cotutor.json > ~/.config/cotutor/config.json > ~/cotutor/ \u4E0B\u552F\u4E00\u7684\u5B69\u5B50\u76EE\u5F55\n\u8BD5\u7528:\u8981 workspace \u7684\u547D\u4EE4\u52A0 --sandbox,\u6362\u5230\u771F workspace \u65C1\u8FB9\u7684 .sandbox/<\u76EE\u5F55\u540D>/,\u8BD5\u7684\u5BF9\u8BDD\u4E0E vault \u7684\u5199\u5165\u4E0D\u8FDB\u5B69\u5B50\u7684\u8BB0\u5F55(\u7B2C\u4E00\u6B21\u81EA\u52A8\u5206:\u8BBE\u7F6E\u7167\u62F7,\u5BF9\u8BDD\u4E0E\u7167\u7247\u4E0D\u5E26,vault \u62F7\u4E00\u4EFD;\u6807\u9898\u524D\u52A0\u300C\u8BD5\u7528\u300D\u3001\u7AEF\u53E3 +1\u3001\u81EA\u52A8\u8BB0\u8D26\u5173\u6389);--sandbox --fresh \u91CD\u65B0\u5206\n";