cotutor 0.4.2 → 0.4.4

package/dist/app/cli/main.js

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

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

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

package/dist/app/cli/report.js

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

package/dist/app/cli/root-ca.d.ts

@@ -0,0 +1,8 @@
+export declare const ROOT_CA = "rootCA.pem";
+export declare function defaultCaRoot(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv, home?: string): string;
+export declare function rootCaFile(o?: {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    home?: string;
+    askMkcert?: () => Promise<string>;
+}): Promise<string | null>;

package/dist/app/cli/root-ca.js

@@ -0,0 +1,33 @@
+/**
+ * 根证书(mkcert 的 rootCA.pem,公钥)在哪:平板扫码装证书时从这里给(serve.ts 的 http 那一面,GET /ca.crt)。
+ * 只认 rootCA.pem;同目录的 rootCA-key.pem 是私钥,永远不读、不给。
+ * 先看 CAROOT 环境变量和 mkcert 的缺省目录(后台服务的 PATH 里不一定有 mkcert),都没有再问 mkcert -CAROOT。
+ */
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+const execFileP = promisify(execFile);
+export const ROOT_CA = 'rootCA.pem';
+export function defaultCaRoot(platform = process.platform, env = process.env, home = homedir()) {
+    if (platform === 'darwin')
+        return join(home, 'Library', 'Application Support', 'mkcert');
+    if (platform === 'win32')
+        return join(env.LOCALAPPDATA || join(home, 'AppData', 'Local'), 'mkcert');
+    return join(env.XDG_DATA_HOME || join(home, '.local', 'share'), 'mkcert');
+}
+export async function rootCaFile(o = {}) {
+    const env = o.env ?? process.env;
+    for (const dir of [env.CAROOT, defaultCaRoot(o.platform, env, o.home)]) {
+        if (dir && existsSync(join(dir, ROOT_CA)))
+            return join(dir, ROOT_CA);
+    }
+    try {
+        const dir = await (o.askMkcert ?? (async () => (await execFileP('mkcert', ['-CAROOT'], { timeout: 5000, env })).stdout.trim()))();
+        if (dir && existsSync(join(dir, ROOT_CA)))
+            return join(dir, ROOT_CA);
+    }
+    catch { /* 没装 mkcert */ }
+    return null;
+}

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

@@ -1,4 +1,5 @@
-import { type Server } from 'node:http';
+import { type RequestListener, type Server } from 'node:http';
+import { type Server as NetServer } from 'node:net';
 import { siteUrl } from '../../shared/site-url.ts';
 import type { ListenInfo } from '../../ui/parent/qr-page.ts';
 import { type AppContext } from '../http/app.ts';
@@ -14,7 +15,8 @@ export interface ServeOptions extends ResolveOptions {
     awake?: boolean;
 }
 export interface ServeResult {
-    server: Server;
+    /** 用 https 时是前面那层(同一个端口分给 https 和 http);不用 https 就是 http 服务本身 */
+    server: NetServer;
     ctx: AppContext;
     ws: Workspace;
     port: number;
@@ -42,6 +44,13 @@ export declare function localName(name?: string): string;
 export declare function certCovers(certFile: string, host: string): boolean;
 /** 扫码页要的三样;listen 之后才知道真端口 */
 export declare function listenInfo(https: boolean, port: number): ListenInfo;
+/**
+ * 用 https 时 http 那一面只做两件事:给根证书(平板扫码装证书,这时还不信任 https,所以走 http)、别的都跳到 https
+ * (切到 https 以前开着的页面、旧书签、手输的 http 地址)。只给 rootCA.pem,私钥永远不给;找不到就说怎么弄。
+ */
+export declare function plainHandler(caFile: () => string | null): RequestListener;
+/** 同一个端口既认 https 又认 http:看第一个字节,TLS 握手(0x16)交给 https,别的交给 http 那一面 */
+export declare function httpAndHttps(secure: Server, plain: Server): NetServer;
 export declare function serveWorkspace(opts?: ServeOptions): Promise<ServeResult>;
 /**
  * busy() 为真就起一个拦闲置睡眠的子进程,为假就停;serve 没了它自己退:macOS 是 caffeinate -i -w <pid>,Windows 是一段 PowerShell(service-windows.ts 的 awakeScript);Linux 什么都不做。

package/dist/app/cli/serve.js

@@ -7,9 +7,11 @@
  */
 import { execFileSync, spawn } from 'node:child_process';
 import { X509Certificate } from 'node:crypto';
-import { readFileSync } from 'node:fs';
+import { createReadStream, existsSync, readFileSync } from 'node:fs';
 import { createServer as createHttp } from 'node:http';
 import { createServer as createHttps } from 'node:https';
+import { createServer as createNetServer } from 'node:net';
+import { rootCaFile } from "./root-ca.js";
 import { hostname, networkInterfaces } from 'node:os';
 import { join } from 'node:path';
 import { siteUrl } from "../../shared/site-url.js";
@@ -18,6 +20,8 @@ import { answersLocally } from "./port.js";
 import { awakeScript, psArgs } from "./service-windows.js";
 import { createContext, createHandler } from "../http/app.js";
 import { liveUpgrade } from "../ws/route.js";
+import { startDailyBackups } from "./backup.js";
+import { BUILD } from "../build.js";
 import { AUTO_BOOKKEEP_EVERY_MS, autoBookkeep } from "../../runtime/auto-bookkeep.js";
 import { USER_CERT_DIR, expandPath, loadWorkspace } from "../workspace.js";
 export { siteUrl };
@@ -89,6 +93,47 @@ export function listenInfo(https, port) {
     const ip = lanAddresses()[0];
     return { name: siteUrl(scheme, localName(), port), ip: ip ? siteUrl(scheme, ip, port) : null, https };
 }
+/**
+ * 用 https 时 http 那一面只做两件事:给根证书(平板扫码装证书,这时还不信任 https,所以走 http)、别的都跳到 https
+ * (切到 https 以前开着的页面、旧书签、手输的 http 地址)。只给 rootCA.pem,私钥永远不给;找不到就说怎么弄。
+ */
+export function plainHandler(caFile) {
+    return (req, res) => {
+        const path = (req.url ?? '/').split('?')[0];
+        if (req.method === 'GET' && (path === '/ca.crt' || path === '/ca')) {
+            const file = caFile();
+            if (file && existsSync(file)) {
+                res.writeHead(200, { 'content-type': 'application/x-x509-ca-cert', 'content-disposition': 'attachment; filename="cotutor-ca.crt"', 'cache-control': 'no-store' });
+                createReadStream(file).pipe(res);
+                return;
+            }
+            res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+            res.end('这台电脑上没找到根证书:先在电脑上跑 mkcert -install 和 cotutor cert');
+            return;
+        }
+        res.writeHead(301, { location: `https://${req.headers.host ?? 'localhost'}${req.url ?? '/'}`, 'cache-control': 'no-store' });
+        res.end();
+    };
+}
+/** 同一个端口既认 https 又认 http:看第一个字节,TLS 握手(0x16)交给 https,别的交给 http 那一面 */
+export function httpAndHttps(secure, plain) {
+    const front = createNetServer((sock) => {
+        sock.on('error', () => undefined);
+        sock.once('data', (first) => {
+            sock.pause();
+            sock.unshift(first);
+            (first[0] === 0x16 ? secure : plain).emit('connection', sock);
+            process.nextTick(() => sock.resume());
+        });
+    });
+    front.once('close', () => {
+        for (const s of [secure, plain]) {
+            s.close();
+            s.closeAllConnections();
+        }
+    });
+    return front;
+}
 export async function serveWorkspace(opts = {}) {
     const ws = loadWorkspace(opts.workspace, opts);
     // 不探 CLI(起服务不用等它);防火墙要查:平板连不上时这里是家长唯一看得到提醒的地方
@@ -99,10 +144,13 @@ export async function serveWorkspace(opts = {}) {
     ctx.openCalls = () => liveUpgrade.openCalls();
     const handler = createHandler(ctx);
     const tls = opts.http ? null : httpsFiles(ws);
-    const server = tls ? createHttps({ cert: readFileSync(tls.cert), key: readFileSync(tls.key) }, handler) : createHttp(handler);
+    const app = tls ? createHttps({ cert: readFileSync(tls.cert), key: readFileSync(tls.key) }, handler) : createHttp(handler);
     // WebSocket:实时老师的那条线(src/app/ws/);不认就关掉
-    server.on('upgrade', (req, socket, head) => { void liveUpgrade(req, socket, head, ctx).then((took) => { if (!took)
+    app.on('upgrade', (req, socket, head) => { void liveUpgrade(req, socket, head, ctx).then((took) => { if (!took)
         socket.destroy(); }, () => socket.destroy()); });
+    // 用 https 时同一个端口也认 http(给平板装根证书、把 http 的跳过去)
+    const caFile = tls ? await rootCaFile() : null;
+    const server = tls ? httpAndHttps(app, createHttp(plainHandler(() => caFile))) : app;
     // 别的程序只占着 127.0.0.1 时,绑通配地址照样成功:平板连到这边,这台电脑上开 localhost 却到了别的程序。先问一声,当被占处理(main.ts 接)
     if (port !== 0 && (await answersLocally(port)))
         throw Object.assign(new Error(`port ${port} answers on 127.0.0.1`), { code: 'EADDRINUSE', port });
@@ -131,6 +179,13 @@ export async function serveWorkspace(opts = {}) {
     const recheck = setInterval(() => { void ctx.bailian.recheck().catch(() => undefined); }, BAILIAN_RECHECK_MS);
     recheck.unref();
     server.once('close', () => clearInterval(recheck));
+    // 每天备份一份(backup.ts):试用的不备;孩子在通话时往后推
+    const stopBackups = startDailyBackups({
+        target: () => (ctx.ws.sandbox ? null : { root: ctx.ws.root, vault: ctx.ws.paths.vault }),
+        busy: () => liveUpgrade.openCalls() > 0,
+        version: BUILD.version,
+    });
+    server.once('close', stopBackups);
     if (opts.awake !== false) {
         const stop = holdAwake(() => liveUpgrade.openCalls() > 0 || Object.keys(ctx.ws.config.tutors).some((t) => ctx.runner.running(t) !== null));
         server.once('close', stop);

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

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

package/dist/app/cli/skeleton.js

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

package/dist/app/cli/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;\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);--json \u91CC\u4E0D\u8FC7\u7684\u9879\u5E26 cmd(\u80FD\u76F4\u63A5\u8DD1)\u6216 human(\u8981\u4EBA\u6765)\n  cotutor update [--anyway]                                            \u5347\u7EA7\u4E00\u6761\u547D\u4EE4\u7BA1\u5230\u5E95:\u95EE npm \u6709\u6CA1\u6709\u65B0\u7248\u672C,\u6362\u7A0B\u5E8F,\u6BCF\u4E2A\u5B69\u5B50\u66F4\u65B0\u51FA\u5382\u6587\u4EF6\u3001\u91CD\u8D77\u670D\u52A1\u548C\u56FE\u6807;\u5B69\u5B50\u5728\u901A\u8BDD\u65F6\u4E0D\u52A8(--anyway \u624D\u52A8),npm \u6CA1\u6210\u670D\u52A1\u4E0D\u52A8\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] [--no-open]   \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;\u7B2C\u4E00\u6B21 install \u6253\u5F00\u4E00\u6B21\u5BB6\u957F\u7AEF(--no-open \u4E0D\u5F00),\u4EE5\u540E\u7684\u542F\u52A8\u90FD\u4E0D\u5F00;\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;--json \u8FD8\u7B54\u5E73\u677F\u5730\u5740\u3001\u8BC1\u4E66\u3001\u767E\u70BC\u914D\u6CA1\u914D\u3001\u56FE\u6807;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";
+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] [--fix]                 \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);--json \u91CC\u4E0D\u8FC7\u7684\u9879\u5E26 cmd(\u80FD\u76F4\u63A5\u8DD1)\u6216 human(\u8981\u4EBA\u6765);--fix \u628A\u5E26 cmd \u7684\u4E00\u6761\u6761\u4FEE\u6389,\u8981\u4EBA\u6765\u7684\u7559\u7740\n  cotutor report [--workspace <dir>]                                   \u8BCA\u65AD\u4FE1\u606F:\u7248\u672C\u3001\u7CFB\u7EDF\u3001\u670D\u52A1\u3001\u4F53\u68C0\u6CA1\u8FC7\u7684\u3001\u6700\u8FD1\u62A5\u9519\u7684\u539F\u56E0;\u4E0D\u542B\u5B69\u5B50\u7684\u5BF9\u8BDD\u3001\u7167\u7247\u3001\u5F55\u97F3\u3001\u6863\u6848\u548C key,\u540D\u5B57\u548C IP \u5DF2\u62B9\u6389,\u5148\u770B\u518D\u53D1\n  cotutor backup [list | restore <\u540D\u5B57> [--yes]] [--workspace <dir>]   \u5907\u4EFD\u5230 workspace \u65C1\u8FB9\u7684 .backups/:\u4E0D\u542B\u5F55\u97F3;\u670D\u52A1\u5F00\u7740\u65F6\u6BCF\u5929\u4E00\u4EFD(\u7559 14 \u4EFD),cotutor upgrade \u524D\u4E00\u4EFD(\u7559 5 \u4EFD);\u6CA1\u53D8\u7684\u6587\u4EF6\u786C\u94FE\u63A5,\u4E0D\u5360\u7B2C\u4E8C\u4EFD\u5730\u65B9;restore \u5148\u628A\u73B0\u5728\u7684\u4E5F\u5907\u4E00\u4EFD\u518D\u62F7\u56DE\u53BB,\u4E0D\u52A0 --yes \u53EA\u8BF4\u4F1A\u505A\u4EC0\u4E48\n  cotutor update [--anyway]                                            \u5347\u7EA7\u4E00\u6761\u547D\u4EE4\u7BA1\u5230\u5E95:\u95EE npm \u6709\u6CA1\u6709\u65B0\u7248\u672C,\u6362\u7A0B\u5E8F,\u6BCF\u4E2A\u5B69\u5B50\u66F4\u65B0\u51FA\u5382\u6587\u4EF6\u3001\u91CD\u8D77\u670D\u52A1\u548C\u56FE\u6807;\u5B69\u5B50\u5728\u901A\u8BDD\u65F6\u4E0D\u52A8(--anyway \u624D\u52A8),npm \u6CA1\u6210\u670D\u52A1\u4E0D\u52A8\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] [--no-open]   \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;\u7B2C\u4E00\u6B21 install \u6253\u5F00\u4E00\u6B21\u5BB6\u957F\u7AEF(--no-open \u4E0D\u5F00),\u4EE5\u540E\u7684\u542F\u52A8\u90FD\u4E0D\u5F00;\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;--json \u8FD8\u7B54\u5E73\u677F\u5730\u5740\u3001\u8BC1\u4E66\u3001\u767E\u70BC\u914D\u6CA1\u914D\u3001\u56FE\u6807;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";

package/dist/app/cli/usage.js

@@ -2,7 +2,9 @@
 export const USAGE = `用法:
   cotutor init <slug> [--dir <path>] [--name <孩子名>] [--grade <1-6>] [--port <n>]   建 ~/cotutor/<slug>/ 骨架(幂等补缺;默认二年级教学包;端口在这里选一次写进 cotutor.json:443 优先,不行就 8443、8445…,以后不变)
   cotutor grades [--json]                                          列出本包可安装的年级教学包
-  cotutor doctor [--workspace <dir>] [--json] [--live]                 逐项体检;--live 真连一次百炼实时模型、真合成一句配音(花一分钱)把 API 层的坑摆出来(真跑老师用 cotutor send);--json 里不过的项带 cmd(能直接跑)或 human(要人来)
+  cotutor doctor [--workspace <dir>] [--json] [--live] [--fix]                 逐项体检;--live 真连一次百炼实时模型、真合成一句配音(花一分钱)把 API 层的坑摆出来(真跑老师用 cotutor send);--json 里不过的项带 cmd(能直接跑)或 human(要人来);--fix 把带 cmd 的一条条修掉,要人来的留着
+  cotutor report [--workspace <dir>]                                   诊断信息:版本、系统、服务、体检没过的、最近报错的原因;不含孩子的对话、照片、录音、档案和 key,名字和 IP 已抹掉,先看再发
+  cotutor backup [list | restore <名字> [--yes]] [--workspace <dir>]   备份到 workspace 旁边的 .backups/:不含录音;服务开着时每天一份(留 14 份),cotutor upgrade 前一份(留 5 份);没变的文件硬链接,不占第二份地方;restore 先把现在的也备一份再拷回去,不加 --yes 只说会做什么
   cotutor update [--anyway]                                            升级一条命令管到底:问 npm 有没有新版本,换程序,每个孩子更新出厂文件、重起服务和图标;孩子在通话时不动(--anyway 才动),npm 没成服务不动
   cotutor upgrade [--workspace <dir>] [--force <老师>]...                老师文件、activity 与 skill 换新版:没改过的直接换,改过的只报 diff(--force <老师> 或 --force <老师>/<名> 才覆盖,原文留 .bak)
   cotutor upgrade --config [--dry-run] [--workspace <dir>]              cotutor.json 补缺:新出厂老师 / 运行时 / 命令模板旗标(只加缺的,你改过的值不动)

package/dist/app/http/access.js

@@ -23,7 +23,7 @@ export const PIN_RE = /^\d{4,8}$/;
 const MAX_FAILS = 5;
 const LOCK_MS = 60_000;
 /** 孩子端的路径:设了 PIN 也开;别的都要凭证。改孩子端加了新接口要来这里登记(tests/access.test.ts 盯着孩子端页面源码里用到的每条) */
-const KID_EXACT = new Set(['/', '/manifest.webmanifest', '/favicon.svg', '/favicon-32.png', '/favicon.ico', '/api/health', '/api/auth', '/dictation', '/dictation/', '/talk', '/talk/', '/api/dictation', '/api/talk']);
+const KID_EXACT = new Set(['/', '/sw.js', '/manifest.webmanifest', '/favicon.svg', '/favicon-32.png', '/favicon.ico', '/api/health', '/api/auth', '/dictation', '/dictation/', '/talk', '/talk/', '/api/dictation', '/api/talk']);
 const KID_PREFIX = ['/kid/', '/stage/', '/api/kid/', '/api/audio/', '/api/bundles/', '/api/dictation/', '/api/talk/', '/api/live/'];
 export function isKidPath(p) {
     return KID_EXACT.has(p) || KID_PREFIX.some((x) => p.startsWith(x)) || /^\/icon-\d{2,4}\.png$/.test(p);

package/dist/app/http/app.js

@@ -37,6 +37,7 @@ import { knownLatest, knownNotes } from "../machine/update.js";
 import { isNewer } from "../../shared/upgrade.js";
 import { qrPage } from "../../ui/parent/qr-page.js";
 import { kidPage } from "../../ui/kid/kid-page.js";
+import { KID_SW_JS } from "../../ui/kid/offline-sw.js";
 import { parentPage } from "../../ui/parent/parent-page.js";
 import { kidHomeView } from "../../runtime/home/store.js";
 import { photosOf } from "../../runtime/kid-input.js";
@@ -1070,6 +1071,9 @@ export async function route(method, path, ctx, body, who = 'local', client = {})
         // 主屏幕(iPad「添加到主屏幕」):清单与图标都按标题现生成,没有静态资源
         if (p === '/manifest.webmanifest')
             return { status: 200, json: webManifest(ws.config.title), contentType: 'application/manifest+json; charset=utf-8' };
+        // 孩子端的离线页(offline-sw.ts):平板打开时电脑关了、睡着了,给「老师们还没到」,不给浏览器的报错
+        if (p === '/sw.js')
+            return { status: 200, body: Buffer.from(KID_SW_JS), contentType: 'text/javascript; charset=utf-8', cacheControl: 'no-cache' };
         const icon = /^\/icon-(\d{2,4})\.png$/.exec(p);
         if (icon) {
             const n = Number(icon[1]);

package/dist/app/http/parent-home.js

@@ -25,6 +25,8 @@ import { wordEmoji } from "../../ui/kid/word-emoji.js";
 import { shownAvatar } from "./avatars.js";
 import { qrNotes, qrSvg } from "../../ui/shared/qr-svg.js";
 import { readDevices } from "../../runtime/journal/kid-log.js";
+import { parentSetupRoute } from "./parent-setup.js";
+import { rootCaFile } from "../cli/root-ca.js";
 const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
 const bad = (message) => ({ status: 400, json: { error: 'bad_request', message } });
 /** 家长端列的老师:有脸的(-tutor 结尾)、开着的;藏着的也列(家长要能把他放回首页) */
@@ -153,13 +155,20 @@ async function kidQr(ctx) {
     const devices = Object.values(await readDevices(ctx.ws));
     const last = devices.map((d) => d.last).sort().at(-1) ?? null;
     const parent = { url: `${info.name}parent`, ip: info.ip ? `${info.ip}parent` : null };
+    // 装根证书:走同一个端口的 http 那一面(serve.ts 的 plainHandler),平板这时还不信任 https;端口照写,http 缺省是 80
+    const caUrl = (u) => { const x = new URL(u); return `http://${x.hostname}:${x.port || '443'}/ca.crt`; };
+    const ca = info.https && (await rootCaFile()) ? { url: caUrl(info.name), ip: info.ip ? caUrl(info.ip) : null } : null;
     return {
         ready: true, https: info.https, url: info.name, svg: qrSvg(info.name), ip: info.ip, svgIp: info.ip ? qrSvg(info.ip) : null,
         parent: { ...parent, svg: qrSvg(parent.url), svgIp: parent.ip ? qrSvg(parent.ip) : null },
+        ca: ca ? { ...ca, svg: qrSvg(ca.url), svgIp: ca.ip ? qrSvg(ca.ip) : null } : null,
         notes: qrNotes(info.https).slice(1), devices: devices.length, last,
     };
 }
 export async function parentHomeRoute(method, p, ctx, body) {
+    const care = await parentSetupRoute(method, p, ctx, body);
+    if (care)
+        return care;
     if (p === '/api/parent/home' && method === 'GET')
         return { status: 200, json: await parentHome(ctx) };
     if (p === '/api/parent/qr' && method === 'GET')

package/dist/app/http/parent-setup.d.ts

@@ -0,0 +1,19 @@
+import type { AppContext, RouteResult } from './app.ts';
+export interface SetupStep {
+    id: string;
+    done: boolean;
+    /** true = 不做孩子用不了;false = 建议 */
+    required: boolean;
+    title: string;
+    detail: string;
+    /** 要在这台电脑的终端里跑的 */
+    commands?: string[];
+    /** 这一步直接在页面上选年级 */
+    grades?: boolean;
+    link?: {
+        href: string;
+        text: string;
+    };
+}
+export declare function setupSteps(ctx: AppContext): Promise<SetupStep[]>;
+export declare function parentSetupRoute(method: string, p: string, ctx: AppContext, body: unknown): Promise<RouteResult | null>;