cotutor 0.4.3 → 0.4.5

package/dist/app/cli/usage.js

@@ -1,38 +1,167 @@
-/** 命令用法(cotutor --help;技能 cotutor-analyze 的 references/命令与文件.md 从这里取分析用的那几行,所以放单独文件,别的模块 import 不会跑到 CLI) */
-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] [--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 补缺:新出厂老师 / 运行时 / 命令模板旗标(只加缺的,你改过的值不动)
-  cotutor add <老师名> --display <显示名> [--subject <学科>] [--avatar <emoji|图片相对路径>] [--hidden]   加一位自家的老师:出模板文件、进 cotutor.json、建目录(名字以 -tutor 结尾的是老师,figshot 给它做头像)
-  cotutor add-theme <主题名> [--from <主题>] [--workspace <dir>]       加一个自家的主题:拷一份(缺省出厂的 default)到 themes/<主题名>/,改 cotutor.json 的 kid.theme 换过去
-  cotutor serve [--workspace <dir>] [--port <n>] [--http] [--trace] [--open] [--log-dir <目录>]   在终端里起服务(一 workspace 一进程;~/.config/cotutor/certs/ 有证书就走 HTTPS;--trace 每一轮的事件按道打印;只打印家长端首页的地址,孩子的平板在那里扫码;--open 顺手打开,旧名 --open-qr 照样认;--log-dir 输出按天落文件,后台服务用;关了终端就停,一直开着用 cotutor service)
-  cotutor open [--workspace <dir>] [--sandbox] [--print] [--json]        打开家长端(读 cotutor.json,不用记端口);--sandbox 开试用的那个(端口永远是真的 +1);--print 只打印地址;没在跑就说怎么起,以 1 退
-  cotutor service install | uninstall | start | stop | restart [--workspace <dir>] [--no-tray] [--no-open]   把 serve 装成这台电脑的后台服务(macOS launchd、Linux systemd 用户服务、Windows 用户的登录项,都不要管理员):登录后自己起来、崩了 10 秒后再起、日志按天落文件留 14 天;一个 workspace 一个;第一次 install 打开一次家长端(--no-open 不开),以后的启动都不开;换了 node 版本或包挪了地方再 install 一次
-  cotutor tray on | off | status [--json]                             菜单栏 / 任务栏图标(macOS、Windows;service install 时一起装,--no-tray 不带):正常时只有 logo,有事出橙点,没在跑时变淡加红点并通知一次;点它看状态、打开家长端、重启、看日志、退出;off 关掉并记住
-  cotutor service status [--json] | logs [--lines <n>] [--follow]      后台服务在不在跑、端口答不答应、跑的哪个版本、vault 读不读得到、日志在哪;--json 还答平板地址、证书、百炼配没配、图标;logs 看最近的日志
-  cotutor pin [off | status] [--pin <数字>] [--json]                       家长端 /parent 与工作台 /dev 的锁:机器级 PIN(所有 workspace 共用),iPad 上输一次、这台电脑免密;没设就全开(家长在旁边可以不设);off 撤掉
-  cotutor cert [--host <名或IP>]...                                      用 mkcert 建这台机器的自签证书到 ~/.config/cotutor/certs/(平板、手机上录音要 HTTPS;所有 workspace 共用)
-  cotutor send <老师> [<消息>] [--from kid|system] [--runtime <名>] [--new] [--photo a.jpg,b.png] [--activity <名> [--param '名=值;名=值']] [--lane main,tts] [--quiet]   终端里发一条,现场按道打印每道工序的事件,说完打印结果(孩子的话照实时写,同孩子端:上下文包带 live:、不补提问卡,只是没有嘴;--from system 不算;--new 开新话题;--photo 带作业照片,拷进 captures/,有照片时消息可以空;--activity 像孩子点了首页的 activity 按钮,新开话题,参数同按钮下面那几行;--quiet 只要结果)
-  cotutor pack <老师> [<消息>] [--from kid|system] [--at <ISO时间>] [--activity <名> [--param '名=值;名=值']] [--json]   干跑上下文包(--activity 看 activity 话题第一条老师拿到什么):不起模型,打印现在会发给老师的那份 + 每段来自哪个文件、那里一共几条、按政策带了几条(改了档案 / 日记 / 计划立刻看效果)
-  cotutor replay <老师> <job> [<日期>] [--runtime <名>] [--json]   回放一轮:同一问按现在的 vault 与提示词再跑一遍(落 evals/,不进孩子的对话、不配音),跑完并排打印上下文包 / 讲稿 / 卡 / 读了什么的 diff
-  cotutor compare <老师> [<evalJob>] [<日期>] [--json]                   再看一次回放的对照(不给 evalJob 就列这天回放过哪些)
-  cotutor show <老师> <job> [<日期>] [--json] [--evals] [--workspace <dir>]   看一轮:问了什么、上下文包、当时的老师文件与技能 hash、讲稿与卡、读了什么、token 与用时、给家长的尾巴;--json 是家长端「看原文」同一份数据,给编程助手分析用
-  cotutor trace <老师> <job> [<日期>] [--lane …] [--workspace <dir>]     回放一轮的事件(<日期>.<job>.events.jsonl;排查昨天那轮用)
-  cotutor rate <老师> <话题> <1-5> [--date <日期>]                       给一个话题打星(与家长端同一条路;≥ vault.keepScore 的话题记账时摘要才进日记)
-  cotutor bookkeep <老师> [--date <日期>] [--thread <话题>]...           记账:这天每个还没记过的话题各起一轮记账任务,老师回「## 记账」,应用写进 vault 的日记(话题名、孩子问、摘要、观察)
-  cotutor home check [--published] [--json]                           检查首页草稿 home/draft.md(或已发布的那份):孩子会看到哪几张卡、每位老师的按钮、要改的与提醒(带行号);不花钱
-  cotutor home publish [--force] [--from <文件>] [--json]              发布首页:检查 → 留历史 home/history/<id>.md → 写 home/published.json(孩子端只读它);有要改的不发,--force 丢掉那几张照发;--from 发另一份(如历史)
-  cotutor home show [--json]                                          现在发布的是哪份、几天前、每个按钮被点了几次(哪天、哪个话题)
-  cotutor activity check [<老师> [<名>]] [--json]                      检查 activity 文件(agents/<老师>/activities/<名>.md):家长填的、应用算的、应用拦的、裁段、插槽、正文用的卡、第一句与收(带行号);不花钱
-  cotutor activity eval <老师> <名> [--runs <n>] [--only <例子>] [--kid-model <千问模型>] [--json]   照 <名>.例子.md 跑:真老师 + 模拟孩子(千问,缺省 qwen3.8-flash,有 Token Plan 走它)多轮(照实时写,同孩子端),判只看板书;一个例子跑 n 次(缺省 3)次次都过才算过;落 evals/,画家是假的;花钱
-  cotutor chalk <check|build|bake|snap|dub> <scene.ts|课包 id> [...]   做小课堂的课包:check 校验场景、build 出课包到 bundles/、bake 烤画面、snap 每步截图、dub 配音(cotutor chalk 看各自的选项;bake / snap 要本机的 Chrome)
-  cotutor mock [--port <n>] [--scenario normal|nokey] [--delay <ms>] [--http]   不经真实老师与百炼,用固定的板书 JSON 起孩子端,测前端交互与渲染(不需要 workspace;老师都走实时老师页,假嘴照脚本念静音的声音;nokey = 没配百炼,孩子端只出「老师们还没到」)
-  cotutor --version | --help
-workspace解析:--workspace > COTUTOR_WORKSPACE > cwd 或祖先有 cotutor.json > ~/.config/cotutor/config.json > ~/cotutor/ 下唯一的孩子目录
-试用:要 workspace 的命令加 --sandbox,换到真 workspace 旁边的 .sandbox/<目录名>/,试的对话与 vault 的写入不进孩子的记录(第一次自动分:设置照拷,对话与照片不带,vault 拷一份;标题前加「试用」、端口 +1、自动记账关掉);--sandbox --fresh 重新分
-`;
+/**
+ * 帮助与参数检查,都从命令表(commands.ts)来:顶层帮助只列命令和一句话,参数、例子在 cotutor <命令> --help。
+ * 纯函数、不碰 I/O:技能生成(app/skills/*-doc.ts)和测试都 import 它,不能把 CLI 带进去。
+ */
+import { COMMANDS, GROUP_TITLE, commandSpec } from "./commands.js";
+const WORKSPACE_DESC = '哪个孩子的 cotutor 文件夹(缺省:COTUTOR_WORKSPACE → 当前目录往上找 → ~/.config/cotutor/config.json → ~/cotutor/ 下唯一的那个)';
+const SANDBOX_DESC = '在试用副本里跑(旁边的 .sandbox/,写的东西不进孩子的记录;--fresh 重新分一份)';
+/** 顶层帮助;all 时连开发与调试的命令也列 */
+export function topHelp(opts = {}) {
+    const groups = opts.all ? ['setup', 'daily', 'custom', 'debug'] : ['setup', 'daily', 'custom'];
+    const width = Math.max(...COMMANDS.map((c) => c.name.length)) + 2;
+    const out = ['cotutor — 家里的 AI 老师团', '', '用法:cotutor <命令> [选项]'];
+    for (const g of groups) {
+        out.push('', GROUP_TITLE[g]);
+        for (const c of COMMANDS.filter((x) => x.group === g && !x.hidden))
+            out.push(`  ${pad(c.name, width)}${c.summary}`);
+    }
+    out.push('', '常用选项:', '  --workspace <目录>  选哪个孩子(缺省自动找)', '  --json              机器可读的输出', '  --sandbox           在试用副本里跑,不进孩子的记录', '  --version           版本号', '各命令认哪些,看它的帮助;不认的选项、多余的参数都报错,不会悄悄忽略。', '退出码:0 成功 · 1 没通过(体检、检查有要改的) · 2 用法错 · 4 内部错误', '', '参数和例子:cotutor <命令> --help');
+    if (!opts.all)
+        out.push(`开发与调试的命令(${COMMANDS.filter((c) => c.group === 'debug' && !c.hidden).map((c) => c.name).join('、')}):cotutor --help --all`);
+    return `${out.join('\n')}\n`;
+}
+/** 一条命令的全部选项(连同它认的全局选项),帮助和检查共用 */
+function flagsOf(c, opts = {}) {
+    const out = [...(c.flags ?? [])];
+    const place = opts.place !== false;
+    if (c.workspace)
+        out.push({ name: 'workspace', value: '<目录>', desc: WORKSPACE_DESC, ...(place ? {} : { hidden: true }) });
+    if (c.sandbox)
+        out.push({ name: 'sandbox', desc: SANDBOX_DESC, ...(place ? {} : { hidden: true }) }, { name: 'fresh', desc: '', hidden: true });
+    if (c.json)
+        out.push({ name: 'json', desc: '机器可读的输出', ...(Array.isArray(c.json) ? { subs: c.json } : {}) });
+    return out;
+}
+/** 终端里占几格:中文、全角两格 */
+const cells = (s) => [...s].reduce((n, ch) => n + (/[ᄀ-ᅟ⺀-꓏가-힣豈-﫿︰-﹏＀-｠￠-￦]/.test(ch) ? 2 : 1), 0);
+const pad = (s, width) => s + ' '.repeat(Math.max(0, width - cells(s)));
+/** 帮助里旗标说明前面的 [install];'' 是不带子命令的那种 */
+const subsTag = (subs) => `[${subs.map((s) => (s === '' ? '不带子命令' : s)).join('、')}] `;
+/** 报错里说「只给谁用」 */
+const subsWho = (c, subs) => subs.map((s) => (s === '' ? `cotutor ${c.name}(不带子命令)` : `${c.name} ${s}`)).join('、');
+/** cotutor <命令> --help;place: false 不列 --workspace / --sandbox(技能参考里统一说一次) */
+export function commandHelp(name, opts = {}) {
+    const c = commandSpec(name);
+    if (!c)
+        return topHelp();
+    const out = [`cotutor ${c.name} — ${c.summary}`, '', '用法:', ...c.usage.map((u) => `  ${u}`)];
+    const shown = flagsOf(c, opts).filter((f) => !f.hidden);
+    if (shown.length) {
+        const label = (f) => `--${f.name}${f.value ? ` ${f.value}` : ''}`;
+        const width = Math.min(26, Math.max(...shown.map((f) => cells(label(f)))) + 2);
+        out.push('', '选项:');
+        for (const f of shown) {
+            const l = label(f);
+            out.push(`  ${cells(l) >= width ? `${l}\n  ${' '.repeat(width)}` : pad(l, width)}${f.subs ? subsTag(f.subs) : ''}${f.desc}`);
+        }
+    }
+    if (c.notes?.length)
+        out.push('', '说明:', ...c.notes.map((n) => `  - ${n}`));
+    if (c.effects?.length)
+        out.push('', '注意:', ...c.effects.map((n) => `  - ${n}`));
+    out.push('', '例子:', ...c.examples.map((e) => `  ${e}`));
+    return `${out.join('\n')}\n`;
+}
+/** 技能里的命令参考:这几条命令各自的帮助;--workspace、--sandbox 在开头说一次 */
+export function commandsReference(names) {
+    return [
+        '这些命令都认 --workspace <目录>(在 workspace 根跑可以不写)和 --sandbox(在试用副本里跑,不进孩子的记录)。',
+        ...names.map((n) => commandHelp(n, { place: false }).trimEnd()),
+    ].join('\n\n');
+}
+/** 编辑距离,给打错的字找最像的 */
+function distance(a, b) {
+    const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+    for (let j = 1; j <= b.length; j++)
+        d[0][j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+            // 两个字母打反了(josn → json)算一步
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1])
+                d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
+        }
+    }
+    return d[a.length][b.length];
+}
+function closest(word, candidates) {
+    let best;
+    let score = Infinity;
+    for (const c of candidates) {
+        const s = c.startsWith(word) || word.startsWith(c) ? 1 : distance(word, c);
+        if (s < score) {
+            score = s;
+            best = c;
+        }
+    }
+    return score <= Math.max(1, Math.floor(word.length / 3)) ? best : undefined;
+}
+/** 不认识的命令:一句话,带最像的那个 */
+export function unknownCommand(cmd) {
+    const near = closest(cmd, COMMANDS.filter((c) => !c.hidden).map((c) => c.name));
+    return `没有 '${cmd}' 这条命令${near ? `,是不是 cotutor ${near}?` : ''}`;
+}
+/**
+ * 照命令表检查参数:不认识的旗标、用错子命令的旗标、不认识的子命令、多余的参数。
+ * 通过返回 null,不通过返回一句话(调用方补「看 cotutor <命令> --help」)。命令本身认不认识由调用方先判。
+ */
+export function checkArgs(c, positionals, flags) {
+    const sub = positionals[0];
+    if (c.subs && (sub !== undefined || c.subRequired) && !c.subs.includes(sub ?? '') && !c.hiddenSubs?.includes(sub ?? '')) {
+        const near = sub === undefined ? undefined : closest(sub, c.subs);
+        return `${c.name} 后面跟 ${c.subs.join(' / ')}${c.subRequired ? ' 之一' : ''}${sub === undefined ? '' : `,不认识 '${sub}'`}${near ? `,是不是 ${near}?` : ''}`;
+    }
+    if (positionals.length > c.maxArgs) {
+        const extra = positionals[c.maxArgs];
+        return c.maxArgs === 0 ? `${c.name} 不带参数,多了 '${extra}'` : `多余的参数 '${extra}':${c.name} 最多 ${c.maxArgs} 个${extra.includes(' ') ? '(带空格的值要加引号)' : ''}`;
+    }
+    const known = flagsOf(c);
+    const actualSub = c.subs?.includes(sub ?? '') || c.hiddenSubs?.includes(sub ?? '') ? (sub ?? '') : '';
+    for (const key of Object.keys(flags)) {
+        // --sandbox / --fresh 由 main 自己说清楚(这条命令为什么不用试用副本),这里不抢
+        if (key === 'help' || key === 'all' || key === 'version' || key === 'sandbox' || key === 'fresh')
+            continue;
+        const f = known.find((x) => x.name === key);
+        if (!f) {
+            const near = closest(key, known.filter((x) => !x.hidden).map((x) => x.name));
+            return `${c.name} 不认识 --${key}${near ? `,是不是 --${near}?` : ''}`;
+        }
+        if (f.subs && !f.subs.includes(actualSub))
+            return `--${key} 只给 ${subsWho(c, f.subs)} 用`;
+        if (f.value && flags[key] === true && key !== 'force')
+            return `--${key} 要一个值:--${key} ${f.value}`;
+    }
+    return null;
+}
+/** 一行 cotutor 命令(文档、测试里写的)照命令表对不对得上;对得上返回 null */
+export function checkCommandLine(line) {
+    const words = line.trim().split(/\s+/);
+    if (words[0] !== 'cotutor' && words[0] !== 'cotutor.cmd')
+        return `不是 cotutor 命令:${line}`;
+    const [cmd, ...rest] = words.slice(1);
+    if (cmd === '--version' || cmd === '--help')
+        return null;
+    const c = commandSpec(cmd);
+    if (!c)
+        return unknownCommand(cmd);
+    if (rest.includes('--help'))
+        return null;
+    const positionals = [];
+    const flags = {};
+    for (let i = 0; i < rest.length; i++) {
+        const w = rest[i];
+        if (!w.startsWith('--')) {
+            positionals.push(w);
+            continue;
+        }
+        const key = w.slice(2).split('=')[0];
+        const spec = flagsOf(c).find((f) => f.name === key);
+        if (spec?.value && rest[i + 1] !== undefined && !rest[i + 1].startsWith('--'))
+            flags[key] = rest[++i];
+        else
+            flags[key] = true;
+    }
+    return checkArgs(c, positionals, flags);
+}
+/** 旧名:顶层帮助 */
+export const USAGE = topHelp();

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";
@@ -624,7 +625,7 @@ export async function route(method, path, ctx, body, who = 'local', client = {})
             }
             return { status: 405, json: { error: 'method_not_allowed' } };
         }
-        // 政策文件补缺(与 cotutor upgrade --config 同一条路):只加缺的出厂件,家长写过的值不动
+        // 政策文件补缺(与 cotutor refresh --config 同一条路):只加缺的出厂件,家长写过的值不动
         if (p === '/api/config/migrate' && method === 'POST') {
             const r = await upgradeConfig(ws.root);
             await ctx.reload();
@@ -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

@@ -26,6 +26,7 @@ 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 结尾)、开着的;藏着的也列(家长要能把他放回首页) */
@@ -154,9 +155,13 @@ 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,
     };
 }

package/dist/app/http/stage.js

@@ -1,6 +1,6 @@
 /**
- * 舞台包的静态文件:dist/stage/(esbuild 打的 stage.js / stage.css / index.html)+ /stage/fonts/(excalidraw 的字体:dist/stage/fonts/ 在就给它,
- * 不在从 node_modules 现取;部署包把字体拷进 dist/stage/fonts/、去掉 excalidraw 依赖,见 docs/wip/deploy/)。
+ * 舞台包的静态文件:dist/stage/(esbuild 打的 stage.js / stage.css / index.html)+ /stage/fonts/(excalidraw 的字体)。
+ * 字体由 build:stage 拷进 dist/stage/fonts/,npm 装的包里没有 excalidraw(它只在打包时用);开发时没打包就从 node_modules 现取。
  * serve 与 mock 共用;没打包(开发时没跑 pnpm run build:stage)→ null,页面开重卡舞台时什么都不出现,doctor 点名。
  */
 import { existsSync } from 'node:fs';

package/dist/app/mock/mock.js

@@ -74,6 +74,7 @@ import { kidThreads } from "../../runtime/kid-view.js";
 import { ICON_SIZES, appIconPng, webManifest } from "../../ui/shared/icon.js";
 import { faviconResponse } from "../../ui/shared/favicon.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 { arrangeHome, homeOwners, kidButtons, kidTiles, parseHome } from "../../runtime/home/home.js";
 import { packageTheme } from "../cli/themes.js";
@@ -644,6 +645,8 @@ export function createMock(opts = {}) {
             return { status: 200, html: VOICE_GALLERY_PAGE };
         if (p === '/manifest.webmanifest')
             return { status: 200, json: webManifest(title), contentType: 'application/manifest+json; charset=utf-8' };
+        if (p === '/sw.js')
+            return { status: 200, body: Buffer.from(KID_SW_JS), contentType: 'text/javascript; charset=utf-8', cacheControl: 'no-cache' };
         // 家长端「记录」:自己的一页(parent-page.ts);清单接口照真服务(答案不剥,第一节带一条给家长的尾巴与记忆)。mock 没有工作台 /dev
         if (p === '/parent')
             return { status: 200, html: parentPage(title) };

package/dist/app/skills/analyze-doc.js

@@ -1,18 +1,14 @@
 /**
- * cotutor-analyze 技能的生成部分(2026-09-15):references/命令与文件.md 从 CLI 的用法文本(app/cli/usage.ts)与对话文件的命名规则(runtime/journal/conversation.ts
+ * cotutor-analyze 技能的生成部分(2026-09-15):references/命令与文件.md 从命令表(app/cli/commands.ts,经 usage.ts 的 commandsReference)与对话文件的命名规则(runtime/journal/conversation.ts
  * conversationFiles)现生成,scripts/gen-skills.ts 写进包根 skills/cotutor-analyze/,tests/skills.test.ts 断言入库的和生成的一致——
  * 技能里的命令与文件名永远和代码同源。SKILL.md 本体(怎么查、禁区)是手写的。
  */
-import { USAGE } from "../cli/usage.js";
+import { commandsReference } from "../cli/usage.js";
 import { conversationFiles } from "../../schema/index.js";
 export const ANALYZE_SKILL = 'cotutor-analyze';
 /** 分析用的那几条命令(按用法文本里的第二个词挑) */
 const ANALYZE_COMMANDS = ['show', 'pack', 'replay', 'compare', 'trace', 'doctor', 'send', 'rate', 'bookkeep'];
 export function analyzeReferenceDoc() {
-    const cmds = USAGE.split('\n').filter((l) => {
-        const m = /^\s+cotutor (\S+)/.exec(l);
-        return m !== null && ANALYZE_COMMANDS.includes(m[1]);
-    });
     const f = conversationFiles('conversations', '<老师>', '<日期>');
     const rows = [
         [f.index, '一天的索引:每条消息物化了 text / kidText / section(卡与讲稿)/ tools(读了什么)/ timing / tokens(这轮老师用的 token:输入 / 输出)/ warnings / bookkeeping;顶层 sessions / ratings / booked(老数据里还有 costUsd,是 claude 时代的美元,不用管)'],
@@ -25,10 +21,10 @@ export function analyzeReferenceDoc() {
     ];
     return `# 命令与文件(机器生成,别改)
 
-## 分析用的命令(在 workspace 根跑;完整用法 cotutor --help)
+## 分析用的命令(在 workspace 根跑;每条就是 cotutor <命令> --help 的内容)
 
 \`\`\`
-${cmds.join('\n')}
+${commandsReference(ANALYZE_COMMANDS)}
 \`\`\`
 
 ## 一轮的文件(conversations/ 下;回放的在 evals/ 下,同一套名字)

package/dist/app/skills/home-doc.js

@@ -3,7 +3,7 @@
  * tests/skills.test.ts 断言入库的和生成的一致。首页语法.md 从首页能用的卡的 card.md 拼(首页专属的全文,和板书共用的只给一句 + 指向 cotutor-board),
  * <kind>.md 是首页专属卡的协议全文,命令.md 从 CLI 用法文本取。SKILL.md 本体(流程、铁律)是手写的。
  */
-import { USAGE } from "../cli/usage.js";
+import { commandsReference } from "../cli/usage.js";
 import { BUTTON_LABEL_MAX, TUTOR_BUTTONS_MAX, kindsFor } from "../../board/cards/index.js";
 import { PACKAGE_CARDS_DIR, readCardDoc } from "../../board/cards/docs.js";
 export const HOME_SKILL = 'cotutor-home';
@@ -81,16 +81,12 @@ for: 2026-09-18
 `;
 }
 export function homeCommandsDoc() {
-    const cmds = USAGE.split('\n').filter((l) => {
-        const m = /^\s+cotutor (\S+)/.exec(l);
-        return m !== null && HOME_COMMANDS.includes(m[1]);
-    });
     return `# 命令(机器生成,别改)
 
-在 workspace 根跑;完整用法 cotutor --help。
+在 workspace 根跑;每条就是 cotutor <命令> --help 的内容。
 
 \`\`\`
-${cmds.join('\n')}
+${commandsReference(HOME_COMMANDS)}
 \`\`\`
 
 ## 文件

package/dist/app/skills/tune-doc.js

@@ -4,11 +4,11 @@
  * tests/skills.test.ts 断言入库的和生成的一致——改老师团时能改哪些字段、缺省是什么,永远和契约同源。SKILL.md 本体(三条路子、禁区)是手写的。
  */
 import { z } from 'zod';
-import { USAGE } from "../cli/usage.js";
+import { commandsReference } from "../cli/usage.js";
 import { POLICY_DEFAULTS, PolicySchema, TutorSchema } from "../../schema/config.js";
 import { AGENT_FRONTMATTER_KEYS } from "../../runtime/agent-file.js";
 export const TUNE_SKILL = 'cotutor-tune';
-const TUNE_COMMANDS = ['add', 'add-theme', 'upgrade', 'doctor', 'pack', 'replay', 'compare', 'show'];
+const TUNE_COMMANDS = ['add', 'add-theme', 'refresh', 'reset', 'doctor', 'pack', 'replay', 'compare', 'show'];
 function unwrap(s) {
     let cur = s;
     for (let i = 0; i < 5; i++) {
@@ -39,10 +39,6 @@ function rows(shape, defaults, prefix = '') {
     return out;
 }
 export function tuneReferenceDoc() {
-    const cmds = USAGE.split('\n').filter((l) => {
-        const m = /^\s+cotutor (\S+)/.exec(l);
-        return m !== null && TUNE_COMMANDS.includes(m[1]);
-    });
     // tutors 字段的缺省从 zod 的 .default() 取(enabled / hidden);display 是必需的,给个占位再抹掉
     const tutorDefaults = TutorSchema.parse({ display: 'x' });
     delete tutorDefaults.display;
@@ -68,10 +64,10 @@ ${tutorRows.join('\n')}
 |---|---|---|---|
 ${policyRows.join('\n')}
 
-## 相关命令(完整用法 cotutor --help)
+## 相关命令(每条就是 cotutor <命令> --help 的内容)
 
 \`\`\`
-${cmds.join('\n')}
+${commandsReference(TUNE_COMMANDS)}
 \`\`\`
 `;
 }

package/dist/app/workspace.d.ts

@@ -1,8 +1,8 @@
 import { ConfigError, UsageError } from '../shared/errors.ts';
-import { redactDeep, redactHome } from '../shared/home.ts';
+import { expandPath, redactDeep, redactHome } from '../shared/home.ts';
 import { type RootSource, type SandboxMark, type Workspace } from '../schema/workspace.ts';
 import { type CotutorConfig } from '../schema/index.ts';
-export { ConfigError, UsageError, redactDeep, redactHome };
+export { ConfigError, UsageError, expandPath, redactDeep, redactHome };
 export type { RootSource, Workspace };
 export declare const CONFIG_FILE = "cotutor.json";
 export declare const USER_CONFIG: string;
@@ -13,13 +13,26 @@ export interface ResolvedRoot {
     root: string;
     source: RootSource;
 }
-export declare function expandPath(p: string, base: string): string;
+/** p 是 dir 本身或在它里面 */
+export declare function isInside(p: string, dir: string): boolean;
+/**
+ * vault 与 workspace 分开:谁也不在谁里面(2026-11-09)。vault 是家长的长期记忆,workspace 是机器的运行记录;
+ * 混在一起时 Obsidian 里满是 agents/、conversations/,扫 vault 要走遍对话与照片,备份恢复把家长的笔记跟着 workspace 一起盖掉。
+ * 旧版 init 不写 paths.vault(缺省 `.`,vault 就是 workspace 根),那样的照旧读得进来,doctor 的 vault.separate 提一句。
+ */
+export declare const vaultSeparate: (root: string, vault: string) => boolean;
+/** init 缺省的 vault:workspace 旁边的 <目录名>-vault(~/cotutor/ming → ~/cotutor/ming-vault;不在「文稿」与 iCloud 里,后台服务读得到) */
+export declare const defaultVaultOf: (root: string) => string;
+/** 写进 cotutor.json 的路径:家目录下的写成 ~/…(输出里不带用户名,换了用户名也对得上),别处写绝对路径 */
+export declare function homePath(abs: string): string;
 /** 读 JSON:不存在 → null;坏 → ConfigError */
 export declare function readJson(file: string): unknown | null;
 /** 从 dir 向上找 cotutor.json,找到返回目录 */
 export declare function findUp(dir: string): string | null;
 /** ~/cotutor/ 下带 cotutor.json 的子目录 */
 export declare function homeWorkspaces(homeRoot?: string): string[];
+/** 这台电脑上认得的孩子:~/cotutor/ 下的,加用户配置指的那个(在别处 --dir 建的) */
+export declare function knownWorkspaces(): string[];
 export interface ResolveOptions {
     env?: NodeJS.ProcessEnv;
     cwd?: string;

package/dist/app/workspace.js

@@ -9,24 +9,35 @@
 import { readFileSync, readdirSync, statSync } from 'node:fs';
 import { readFile, writeFile, rename } from 'node:fs/promises';
 import { ConfigError, UsageError } from "../shared/errors.js";
-import { redactDeep, redactHome } from "../shared/home.js";
+import { expandPath, redactDeep, redactHome } from "../shared/home.js";
 import { SANDBOX_MARK, SKILLS_DIR, SandboxMarkSchema } from "../schema/workspace.js";
 import { homedir } from 'node:os';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { CotutorConfigSchema, PATH_ROLES, ROLE_DEFAULTS, WORKSPACE_ROLES, explainIssues, } from "../schema/index.js";
 // 挪走了的几样照旧从这里转出(旧的引法不用改)
-export { ConfigError, UsageError, redactDeep, redactHome };
+export { ConfigError, UsageError, expandPath, redactDeep, redactHome };
 export const CONFIG_FILE = 'cotutor.json';
 export const USER_CONFIG = join(homedir(), '.config', 'cotutor', 'config.json');
 /** 机器级自签证书目录(cotutor cert 写 cert.pem + key.pem):证书签的是本机名与局域网 IP,与孩子无关,所以不在 workspace 里 */
 export const USER_CERT_DIR = join(homedir(), '.config', 'cotutor', 'certs');
 export const HOME_ROOT = join(homedir(), 'cotutor');
-export function expandPath(p, base) {
-    if (p === '~')
-        return homedir();
-    if (p.startsWith('~/'))
-        return join(homedir(), p.slice(2));
-    return isAbsolute(p) ? p : resolve(base, p);
+/** p 是 dir 本身或在它里面 */
+export function isInside(p, dir) {
+    const r = relative(dir, p);
+    return r === '' || (r !== '..' && !r.startsWith(`..${sep}`) && !isAbsolute(r));
+}
+/**
+ * vault 与 workspace 分开:谁也不在谁里面(2026-11-09)。vault 是家长的长期记忆,workspace 是机器的运行记录;
+ * 混在一起时 Obsidian 里满是 agents/、conversations/,扫 vault 要走遍对话与照片,备份恢复把家长的笔记跟着 workspace 一起盖掉。
+ * 旧版 init 不写 paths.vault(缺省 `.`,vault 就是 workspace 根),那样的照旧读得进来,doctor 的 vault.separate 提一句。
+ */
+export const vaultSeparate = (root, vault) => !isInside(vault, root) && !isInside(root, vault);
+/** init 缺省的 vault:workspace 旁边的 <目录名>-vault(~/cotutor/ming → ~/cotutor/ming-vault;不在「文稿」与 iCloud 里,后台服务读得到) */
+export const defaultVaultOf = (root) => join(dirname(root), `${basename(root)}-vault`);
+/** 写进 cotutor.json 的路径:家目录下的写成 ~/…(输出里不带用户名,换了用户名也对得上),别处写绝对路径 */
+export function homePath(abs) {
+    const rel = relative(homedir(), abs);
+    return rel && !rel.startsWith('..') && !isAbsolute(rel) ? `~/${rel.split(sep).join('/')}` : abs;
 }
 const isDir = (p) => {
     try {
@@ -84,6 +95,17 @@ export function homeWorkspaces(homeRoot = HOME_ROOT) {
         return [];
     }
 }
+/** 这台电脑上认得的孩子:~/cotutor/ 下的,加用户配置指的那个(在别处 --dir 建的) */
+export function knownWorkspaces() {
+    const roots = new Set(homeWorkspaces());
+    try {
+        const user = readJson(USER_CONFIG);
+        if (typeof user?.workspace === 'string' && user.workspace)
+            roots.add(expandPath(user.workspace, homedir()));
+    }
+    catch { /* 用户配置坏了 doctor 去报 */ }
+    return [...roots];
+}
 export function resolveRoot(override, opts = {}) {
     const env = opts.env ?? process.env;
     const cwd = resolve(opts.cwd ?? process.cwd());

package/dist/runtime/home/home.js

@@ -127,7 +127,7 @@ export function homeIssues(doc, ctx) {
             if (act && ctx.activities) {
                 const got = ctx.activities.get(`${name}/${act.name}`);
                 if (!got)
-                    out.push({ level: 'fix', line, card: n, button: k, text: b.kind === 'lecture' && !b.activity ? `${t.display}的「${b.label}」:看完怎么聊写在 agents/${name}/activities/${LECTURE_ACTIVITY}.md,这份不在(cotutor upgrade 补出厂的;或按钮下面写一行 activity: <名> 换一个)` : `${t.display}的「${b.label}」:agents/${name}/activities/${act.name}.md 不在(cotutor activity check ${name} 看这位老师有哪些)` });
+                    out.push({ level: 'fix', line, card: n, button: k, text: b.kind === 'lecture' && !b.activity ? `${t.display}的「${b.label}」:看完怎么聊写在 agents/${name}/activities/${LECTURE_ACTIVITY}.md,这份不在(cotutor refresh 补出厂的;或按钮下面写一行 activity: <名> 换一个)` : `${t.display}的「${b.label}」:agents/${name}/activities/${act.name}.md 不在(cotutor activity check ${name} 看这位老师有哪些)` });
                 else {
                     if (got.fixes)
                         out.push({ level: 'fix', line, card: n, button: k, text: `${t.display}的「${b.label}」:activity 文件 ${act.name}.md 有 ${got.fixes} 处要改(cotutor activity check ${name} ${act.name})` });

package/dist/runtime/runner.js

@@ -92,7 +92,7 @@ export async function gatherContext(ws, tutor, input, report) {
             pack.rules = TUTOR_RULES_PATH;
         }
         catch {
-            pack.rules = `缺:${TUTOR_RULES_PATH} 不在(cotutor upgrade 补),照你老师文件里的做`;
+            pack.rules = `缺:${TUTOR_RULES_PATH} 不在(cotutor refresh 补),照你老师文件里的做`;
         }
     }
     pack.notes.push(...mem.notes);
@@ -186,7 +186,7 @@ async function systemParts(ws, tutor, policy, pack, act = null) {
         return { systemBody: agentBody, activityInSystem: false };
     const guide = await boardGuideOf(ws, tutor);
     if (!guide) {
-        pack.boardGuide = `缺:${BOARD_GUIDE_PATH} 不在(cotutor upgrade 补),照你会的写`;
+        pack.boardGuide = `缺:${BOARD_GUIDE_PATH} 不在(cotutor refresh 补),照你会的写`;
         return { systemBody: agentBody, activityInSystem: false };
     }
     pack.boardGuide = BOARD_GUIDE_IN_SYSTEM;

package/dist/shared/home.d.ts

@@ -1,2 +1,4 @@
+/** cotutor.json 里的路径:~ 与 ~/ 是家目录,绝对的照用,相对的相对 base(从 app/workspace.ts 挪来,2026-11-09:托盘不带 zod 也要用) */
+export declare function expandPath(p: string, base: string): string;
 export declare function redactHome(value: string): string;
 export declare function redactDeep<T>(value: T): T;

package/dist/shared/home.js

@@ -1,5 +1,14 @@
 /** 给人看的路径里把家目录换成 $HOME(报错、doctor、--json 输出不带出用户名;从 app/workspace.ts 挪来,2026-10-29) */
 import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+/** cotutor.json 里的路径:~ 与 ~/ 是家目录,绝对的照用,相对的相对 base(从 app/workspace.ts 挪来,2026-11-09:托盘不带 zod 也要用) */
+export function expandPath(p, base) {
+    if (p === '~')
+        return homedir();
+    if (p.startsWith('~/'))
+        return join(homedir(), p.slice(2));
+    return isAbsolute(p) ? p : resolve(base, p);
+}
 export function redactHome(value) {
     const home = homedir();
     return home && value.startsWith(home) ? '$HOME' + value.slice(home.length) : value;