cotutor 0.1.0 → 0.3.0

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

@@ -0,0 +1,58 @@
+import { type InstallStep } from './tutors.ts';
+/** section:出厂模板里有的整段(dictation 这种后加的),你这份没有;retired:出厂写进去、应用已经不读的整段,补缺时删掉 */
+export type GapKind = 'tutor' | 'runtime' | 'flag' | 'cards' | 'section' | 'retired';
+export interface ConfigGap {
+    kind: GapKind;
+    /** 点位:tutors.math-tutor / runtimes.qwen / runtimes.qwen.run */
+    path: string;
+    /** 人话:缺的是什么、补上有什么用 */
+    detail: string;
+    /** 补上之后这个点位的值(--dry-run 打印、页面提示用);retired 是 undefined(删掉) */
+    value: unknown;
+}
+/**
+ * 把出厂模板里有、这份没有的旗标插进来,**位置照出厂模板**:
+ * 插到「出厂模板里排在它前面、这份也有」的那个旗标之后;一个都找不到就放末尾。
+ * 已经有的旗标一律不碰——值被家长改过(预算 2 → 5)是她的决定。
+ */
+export declare function insertMissingFlags(mine: readonly string[], factory: readonly string[]): {
+    argv: string[];
+    added: string[];
+};
+/**
+ * 这份 cotutor.json 比出厂模板少了什么。只看「有没有」,不看值——值是家长的。
+ * 注意:出厂老师是家长手动从 tutors 里删掉的(页面删不了出厂老师),这里也会当成缺,
+ * 所以 `--dry-run` 先列、doctor 那条不是必需项。
+ */
+export declare function configGaps(raw: unknown, agentsDir?: string): Promise<ConfigGap[]>;
+export interface UpgradeConfigResult {
+    file: string;
+    gaps: ConfigGap[];
+    /** 真写了没有(--dry-run 与没有差异时都是 false) */
+    applied: boolean;
+    /** 新老师进了表之后顺带补的文件与目录(老师文件、agents/<name>/) */
+    installed: InstallStep[];
+}
+/**
+ * 补缺并落盘:补丁打在**原始 JSON** 上(`$schema` `_note` 这些机器不认识的键原样留着),
+ * 整份过契约才写;不过就抛,原文件不动。
+ */
+export declare function upgradeConfig(root: string, opts?: {
+    dryRun?: boolean;
+}): Promise<UpgradeConfigResult>;
+/** doctor 与家长端都要:读文件算差异;文件读不到 / 坏了就当没有差异(那边有别的检查在报) */
+export declare function configGapsOf(root: string): Promise<ConfigGap[]>;
+export interface LayoutStep {
+    item: string;
+    action: 'moved' | 'kept' | 'removed';
+    note?: string;
+}
+/** doctor 用:老位置里还有东西的那几个(相对 workspace 根) */
+export declare function legacyLayout(root: string): Promise<string[]>;
+/**
+ * init / upgrade 第一步:老位置里的东西原样挪到新位置(不改内容、不看 hash),出厂件新不新由后面安装那一步照常查。
+ * 必须在 installTutors / installSkills 之前:不然新位置是空的,出厂件先拷进去,家长改过的那份就晾在老位置。
+ * 新位置已经有同名的不挪、报一声;老目录搬空了删掉(.claude/skills 随后换成链,见 skills.ts 的 linkClaudeSkills),.claude/ 里别的东西不碰。
+ * 顺带删掉 RETIRED_FILES(机器文件,删了也只是缓存没了)。
+ */
+export declare function migrateLayout(root: string): Promise<LayoutStep[]>;

package/dist/app/cli/migrate.js

@@ -0,0 +1,253 @@
+/**
+ * 老 workspace 的迁移:cotutor.json 补缺(下面大半),和目录搬家、清掉不再用的机器文件(文件末尾的 migrateLayout)。
+ *
+ * cotutor.json 是**政策文件**:init 只在缺失时写模板,已有的那份机器永不改(家长的决定不由机器代做)。
+ * 代价是包更新带来的新出厂件不会自己出现在老 workspace 里,而且「没有」的表现是**静默**的——
+ * 所以有这一层:把「出厂模板有、你这份没有」算出来(doctor 的 `config.migrate` 点名、家长端设置页顶部提示),
+ * `cotutor upgrade --config` 只**补缺**——加缺的键、往命令模板里插缺的旗标;家长写过的值一个都不动
+ * (改小的预算、加过的 `-m qwen3.8-flash`、换掉的 default 运行时全都原样留着)。
+ * 唯一删的是 RETIRED 里点了名的出厂段(机器写进去、应用已经不读的,如 2026-10-31 的 tts);家长自己加的键不在表里,不碰。
+ *
+ * 差异是**现算的**:拿家长自己的 slug / name / port 生成一份出厂模板,和她这份逐项比,
+ * 所以以后模板再加东西,这里不用跟着改。
+ */
+import { workspaceGradePack } from "./grades.js";
+import { lstat, mkdir, readFile, readdir, rename, rm, rmdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CotutorConfigSchema, SKILLS_DIR, explainIssues } from "../../schema/index.js";
+import { configTemplate, shippedAgents } from "./skeleton.js";
+import { installTutors } from "./tutors.js";
+import { CONFIG_FILE, ConfigError, readJson } from "../workspace.js";
+const isObj = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+/** 命令模板里一个旗标带几个词:`--output-format stream-json` 是两个,`--include-partial-messages` 是一个(值不以 - 打头) */
+function flagSpan(argv, i) {
+    const span = [argv[i]];
+    for (let j = i + 1; j < argv.length && !argv[j].startsWith('-'); j++)
+        span.push(argv[j]);
+    return span;
+}
+/**
+ * 把出厂模板里有、这份没有的旗标插进来,**位置照出厂模板**:
+ * 插到「出厂模板里排在它前面、这份也有」的那个旗标之后;一个都找不到就放末尾。
+ * 已经有的旗标一律不碰——值被家长改过(预算 2 → 5)是她的决定。
+ */
+export function insertMissingFlags(mine, factory) {
+    const argv = [...mine];
+    const added = [];
+    for (let i = 0; i < factory.length; i++) {
+        const tok = factory[i];
+        if (!tok.startsWith('-') || argv.includes(tok))
+            continue;
+        const span = flagSpan(factory, i);
+        let at = argv.length;
+        for (let j = i - 1; j >= 0; j--) {
+            const prev = factory[j];
+            if (!prev.startsWith('-'))
+                continue;
+            const k = argv.indexOf(prev);
+            if (k === -1)
+                continue;
+            at = k + flagSpan(argv, k).length;
+            break;
+        }
+        argv.splice(at, 0, ...span);
+        added.push(...span);
+    }
+    return { argv, added };
+}
+/** 出厂模板:拿这份配置自己的 slug / name / port 生成,免得差异里混进「孩子叫什么」这种无关项 */
+async function factoryConfig(raw, agentsDir) {
+    const kid = isObj(raw.kid) ? raw.kid : {};
+    const server = isObj(raw.server) ? raw.server : {};
+    return JSON.parse(configTemplate({
+        slug: typeof kid.slug === 'string' ? kid.slug : 'kid',
+        name: typeof kid.name === 'string' ? kid.name : undefined,
+        port: typeof server.port === 'number' ? server.port : undefined,
+        tutors: await shippedAgents(agentsDir),
+    }));
+}
+/**
+ * 这份 cotutor.json 比出厂模板少了什么。只看「有没有」,不看值——值是家长的。
+ * 注意:出厂老师是家长手动从 tutors 里删掉的(页面删不了出厂老师),这里也会当成缺,
+ * 所以 `--dry-run` 先列、doctor 那条不是必需项。
+ */
+export async function configGaps(raw, agentsDir) {
+    if (!isObj(raw))
+        return [];
+    const factory = await factoryConfig(raw, agentsDir);
+    const gaps = [];
+    const mineTutors = isObj(raw.tutors) ? raw.tutors : {};
+    const factoryTutors = isObj(factory.tutors) ? factory.tutors : {};
+    for (const [name, entry] of Object.entries(factoryTutors)) {
+        if (name in mineTutors)
+            continue;
+        const display = isObj(entry) && typeof entry.display === 'string' ? entry.display : name;
+        gaps.push({ kind: 'tutor', path: `tutors.${name}`, detail: `出厂老师 ${display}(${name})不在 tutors 里`, value: entry });
+    }
+    // 卡的清单(2026-10-07,《卡片协议.md》「谁拿到哪些卡」):出厂老师有、你这份没写 → 补出厂的;不想裁就写全部种类,这条就不再提
+    for (const [name, entry] of Object.entries(factoryTutors)) {
+        const mine = mineTutors[name];
+        if (!isObj(mine) || 'cards' in mine || !isObj(entry) || !Array.isArray(entry.cards))
+            continue;
+        gaps.push({ kind: 'cards', path: `tutors.${name}.cards`, detail: `${name} 没写卡的清单,板书写法里讲全部卡;出厂清单 ${entry.cards.join(' ')}`, value: entry.cards });
+    }
+    const mineRuntimes = isObj(raw.runtimes) ? raw.runtimes : {};
+    const factoryRuntimes = isObj(factory.runtimes) ? factory.runtimes : {};
+    for (const [name, rt] of Object.entries(factoryRuntimes)) {
+        if (name === 'default' || name in mineRuntimes)
+            continue;
+        gaps.push({ kind: 'runtime', path: `runtimes.${name}`, detail: `出厂运行时 ${name} 不在 runtimes 里`, value: rt });
+    }
+    for (const [name, rt] of Object.entries(factoryRuntimes)) {
+        if (name === 'default' || !isObj(rt))
+            continue;
+        const mine = mineRuntimes[name];
+        if (!isObj(mine))
+            continue; // 整个运行时都缺,上面那轮已经报了
+        // 出厂模板换了说话方式(消息改走 stdin)而你的改过:逐个补旗标会拼出过不了契约的模板,不动(家长的决定)
+        if (rt.stdin && !mine.stdin)
+            continue;
+        for (const key of ['run', 'resume']) {
+            const f = rt[key];
+            const u = mine[key];
+            if (!Array.isArray(f) || !Array.isArray(u))
+                continue;
+            const { argv, added } = insertMissingFlags(u, f);
+            if (!added.length)
+                continue;
+            const what = `缺出厂旗标 ${added.join(' ')}`;
+            gaps.push({ kind: 'flag', path: `runtimes.${name}.${key}`, detail: `${name} 的 ${key} 命令模板${what}`, value: argv });
+        }
+    }
+    // 后加的整段(2026-10-10 听写的拍照认词要求):写进文件家长才看得见、改得动;已经有这一段就不碰
+    for (const key of SECTIONS) {
+        if (key in raw || !(key in factory))
+            continue;
+        gaps.push({ kind: 'section', path: key, detail: `缺 ${key} 这一段(${SECTION_WHAT[key]})`, value: factory[key] });
+    }
+    for (const key of RETIRED) {
+        if (key in raw)
+            gaps.push({ kind: 'retired', path: key, detail: `${key} 这一段不再用了(${RETIRED_WHAT[key]}),删掉`, value: undefined });
+    }
+    return gaps;
+}
+/** 补缺时会整段补上的配置段:出厂模板写了、写进文件才好改的 */
+const SECTIONS = ['dictation'];
+const SECTION_WHAT = { dictation: '听写拍照认词用的模型,补上就能在文件里改(挑词的要求在听写 activity 文件)' };
+/** 不再用的出厂段:老模板写进去的,应用已经不读(契约照样放过,只是留着让人以为还管用) */
+const RETIRED = ['tts'];
+const RETIRED_WHAT = { tts: '配音 2026-10-31 并进了应用,直连百炼,不再起 voxtell 命令' };
+function setAt(obj, path, value) {
+    const keys = path.split('.');
+    let cur = obj;
+    for (const k of keys.slice(0, -1)) {
+        if (!isObj(cur[k]))
+            cur[k] = {};
+        cur = cur[k];
+    }
+    const last = keys[keys.length - 1];
+    if (value === undefined)
+        delete cur[last];
+    else
+        cur[last] = value;
+}
+/**
+ * 补缺并落盘:补丁打在**原始 JSON** 上(`$schema` `_note` 这些机器不认识的键原样留着),
+ * 整份过契约才写;不过就抛,原文件不动。
+ */
+export async function upgradeConfig(root, opts = {}) {
+    const file = join(root, CONFIG_FILE);
+    const raw = readJson(file);
+    if (raw === null)
+        throw new ConfigError(file, '不存在:先 cotutor init <slug> 建 workspace');
+    if (!isObj(raw))
+        throw new ConfigError(file, '顶层不是一个 JSON 对象');
+    const gaps = await configGaps(raw, (await workspaceGradePack(root)).agentsDir);
+    if (opts.dryRun || !gaps.length)
+        return { file, gaps, applied: false, installed: [] };
+    const merged = JSON.parse(JSON.stringify(raw));
+    for (const g of gaps)
+        setAt(merged, g.path, g.value);
+    const r = CotutorConfigSchema.safeParse(merged);
+    if (!r.success) {
+        throw new ConfigError(file, `补完之后不合契约,没有写入:\n${explainIssues(r.error.issues).map((l) => `  - ${l}`).join('\n')}`);
+    }
+    const tmp = `${file}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(merged, null, 2)}\n`);
+    await rename(tmp, file);
+    // 新老师进了表,她的文件与家还得在,否则 doctor 立刻报「老师文件读不到」——
+    // 补缺就补到底(installTutors 是 init 用的同一条路:缺的拷、有的不动)
+    // 老布局先搬:不然新位置是空的,出厂老师先拷进去,家长改过的那份晾在 .claude/agents/
+    if (gaps.some((g) => g.kind === 'tutor'))
+        await migrateLayout(root);
+    const installed = gaps.some((g) => g.kind === 'tutor')
+        ? (await installTutors(root, Object.keys(r.data.tutors))).filter((s) => s.action === 'created' || s.action === 'replaced')
+        : [];
+    return { file, gaps, applied: true, installed };
+}
+/** doctor 与家长端都要:读文件算差异;文件读不到 / 坏了就当没有差异(那边有别的检查在报) */
+export async function configGapsOf(root) {
+    try {
+        return await configGaps(JSON.parse(await readFile(join(root, CONFIG_FILE), 'utf8')), (await workspaceGradePack(root)).agentsDir);
+    }
+    catch {
+        return [];
+    }
+}
+// ---- 目录搬家(2026-10-30):老师文件 .claude/agents/ → agents/,技能 .claude/skills/ → .agents/skills/ ----
+// 起因:Claude CLI 2026-10-28 移除后 .claude/ 只是历史名字;Codex、Qwen Code 认 .agents/skills,老师文件和老师的家并排才和包里一样。
+// 老 workspace 都搬完了这一段就删(同 2026-10-22 删 .qwen 链的迁移)。
+/** 还没搬完的老位置(实体目录才算;.claude/skills 是链就是新布局) */
+const LEGACY_DIRS = [
+    { from: '.claude/agents', to: 'agents' },
+    { from: '.claude/skills', to: SKILLS_DIR },
+];
+/**
+ * 不再用的机器文件(相对 workspace 根):2026-10-31 配音的缓存合成一份 .cotutor/tts/,试听、听写念词原来各存一处,设置页的「试一句」也去掉了;
+ * 同日 drawtell 并进本包,做课包是 cotutor chalk,不再要指向 drawtell CLI 的壳 .cotutor/drawtell
+ */
+const RETIRED_FILES = ['.cotutor/tts-preview', '.cotutor/dictation-say', '.cotutor/tts-try.mp3', '.cotutor/drawtell'];
+/** doctor 用:老位置里还有东西的那几个(相对 workspace 根) */
+export async function legacyLayout(root) {
+    const out = [];
+    for (const { from } of LEGACY_DIRS) {
+        const st = await lstat(join(root, from)).catch(() => null);
+        if (st?.isDirectory() && (await readdir(join(root, from))).some((n) => n !== '.DS_Store'))
+            out.push(`${from}/`);
+    }
+    return out;
+}
+/**
+ * init / upgrade 第一步:老位置里的东西原样挪到新位置(不改内容、不看 hash),出厂件新不新由后面安装那一步照常查。
+ * 必须在 installTutors / installSkills 之前:不然新位置是空的,出厂件先拷进去,家长改过的那份就晾在老位置。
+ * 新位置已经有同名的不挪、报一声;老目录搬空了删掉(.claude/skills 随后换成链,见 skills.ts 的 linkClaudeSkills),.claude/ 里别的东西不碰。
+ * 顺带删掉 RETIRED_FILES(机器文件,删了也只是缓存没了)。
+ */
+export async function migrateLayout(root) {
+    const steps = [];
+    for (const { from, to } of LEGACY_DIRS) {
+        const dir = join(root, from);
+        if (!(await lstat(dir).catch(() => null))?.isDirectory())
+            continue;
+        await rm(join(dir, '.DS_Store'), { force: true });
+        for (const name of (await readdir(dir)).sort()) {
+            const dest = join(root, to, name);
+            if (await lstat(dest).catch(() => null)) {
+                steps.push({ item: `${from}/${name}`, action: 'kept', note: `${to}/${name} 已经有了,没挪;对一下要哪份,删掉另一份` });
+                continue;
+            }
+            await mkdir(join(root, to), { recursive: true });
+            await rename(join(dir, name), dest);
+            steps.push({ item: `${to}/${name}`, action: 'moved', note: `从 ${from}/ 挪来` });
+        }
+        if (await rmdir(dir).then(() => true, () => false))
+            steps.push({ item: `${from}/`, action: 'removed', note: '搬空了' });
+    }
+    for (const rel of RETIRED_FILES) {
+        if (!(await lstat(join(root, rel)).catch(() => null)))
+            continue;
+        await rm(join(root, rel), { recursive: true, force: true });
+        steps.push({ item: rel, action: 'removed', note: '不再用的机器文件' });
+    }
+    return steps;
+}

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

@@ -0,0 +1,37 @@
+import { type Server } from 'node:http';
+import type { ListenInfo } from '../../ui/dev/qr-page.ts';
+import { type AppContext } from '../http/app.ts';
+import { type ResolveOptions, type Workspace } from '../workspace.ts';
+export interface ServeOptions extends ResolveOptions {
+    workspace?: string;
+    port?: number;
+    host?: string;
+    /** 强制走 HTTP(哪怕证书在) */
+    http?: boolean;
+}
+export interface ServeResult {
+    server: Server;
+    ctx: AppContext;
+    ws: Workspace;
+    port: number;
+    https: boolean;
+    /** 本机名与局域网 IPv4 各一条 */
+    urls: string[];
+    /** 扫码页:在这台电脑上打开的那条(localhost,证书里签了) */
+    qrPage: string;
+    warnings: string[];
+}
+/** 证书路径:cotutor.json 的 server.https 优先(相对 workspace 根),否则机器级 ~/.config/cotutor/certs/;都没有 → null */
+export declare function httpsFiles(ws: Workspace): {
+    cert: string;
+    key: string;
+} | null;
+/** 局域网 IPv4(iPad / iPhone 用它访问;.local 名不一定解析得到,有些设备还会挑中走不通的 IPv6) */
+export declare function lanAddresses(): string[];
+/** 本机的 mDNS 名(与 cotutor cert 签的那条同一个写法) */
+export declare function localName(host?: string): string;
+/** 证书认不认这个主机名;读不了当作不认 */
+export declare function certCovers(certFile: string, host: string): boolean;
+/** 扫码页要的三样;listen 之后才知道真端口 */
+export declare function listenInfo(https: boolean, port: number): ListenInfo;
+export declare function serveWorkspace(opts?: ServeOptions): Promise<ServeResult>;

package/dist/app/cli/serve.js

@@ -0,0 +1,98 @@
+/**
+ * cotutor serve:一 workspace 一进程,端口读 cotutor.json(--port 覆盖)。
+ * 启动打印解析结果与体检警告(配置坏了直接不起,骨架缺失只警告)。
+ * 扫码页:/qr 现画一张二维码(编 <本机名>.local 那条,不随 Wi-Fi 变),iPad 用相机扫;listen 之后把真端口交给 ctx.listen。
+ * HTTPS(iPad 上录音要):server.https 指了证书就用它(单个 workspace 的例外);没指就看机器级 ~/.config/cotutor/certs/(cotutor cert 用 mkcert 建);都没有走 HTTP。
+ */
+import { X509Certificate } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { createServer as createHttp } from 'node:http';
+import { createServer as createHttps } from 'node:https';
+import { hostname, networkInterfaces } from 'node:os';
+import { join } from 'node:path';
+import { doctorWorkspace } from "./doctor.js";
+import { createContext, createHandler } from "../http/app.js";
+import { liveUpgrade } from "../ws/route.js";
+import { AUTO_BOOKKEEP_EVERY_MS, autoBookkeep } from "../../runtime/auto-bookkeep.js";
+import { USER_CERT_DIR, expandPath, loadWorkspace } from "../workspace.js";
+/** 证书路径:cotutor.json 的 server.https 优先(相对 workspace 根),否则机器级 ~/.config/cotutor/certs/;都没有 → null */
+export function httpsFiles(ws) {
+    const h = ws.config.server.https;
+    if (h)
+        return { cert: expandPath(h.cert, ws.root), key: expandPath(h.key, ws.root) };
+    const cert = join(USER_CERT_DIR, 'cert.pem');
+    const key = join(USER_CERT_DIR, 'key.pem');
+    try {
+        readFileSync(cert);
+        readFileSync(key);
+        return { cert, key };
+    }
+    catch {
+        return null;
+    }
+}
+/** 局域网 IPv4(iPad / iPhone 用它访问;.local 名不一定解析得到,有些设备还会挑中走不通的 IPv6) */
+export function lanAddresses() {
+    const out = [];
+    for (const list of Object.values(networkInterfaces()))
+        for (const i of list ?? [])
+            if (i.family === 'IPv4' && !i.internal)
+                out.push(i.address);
+    return out;
+}
+/** 本机的 mDNS 名(与 cotutor cert 签的那条同一个写法) */
+export function localName(host = hostname()) {
+    return host.endsWith('.local') ? host : `${host}.local`;
+}
+/** 证书认不认这个主机名;读不了当作不认 */
+export function certCovers(certFile, host) {
+    try {
+        return new X509Certificate(readFileSync(certFile)).checkHost(host) !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+/** 扫码页要的三样;listen 之后才知道真端口 */
+export function listenInfo(https, port) {
+    const scheme = https ? 'https' : 'http';
+    const ip = lanAddresses()[0];
+    return { name: `${scheme}://${localName()}:${port}/`, ip: ip ? `${scheme}://${ip}:${port}/` : null, https };
+}
+export async function serveWorkspace(opts = {}) {
+    const ws = loadWorkspace(opts.workspace, opts);
+    const report = await doctorWorkspace(ws.root, { ...opts, probeEnv: false });
+    const warnings = report.checks.filter((c) => !c.ok).map((c) => `${c.name}:${c.detail}${c.fix ? `(${c.fix})` : ''}`);
+    const port = opts.port ?? ws.config.server.port;
+    const ctx = createContext(ws);
+    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);
+    // WebSocket:实时老师的那条线(src/app/ws/);不认就关掉
+    server.on('upgrade', (req, socket, head) => { void liveUpgrade(req, socket, head, ctx).then((took) => { if (!took)
+        socket.destroy(); }, () => socket.destroy()); });
+    await new Promise((resolveListen, reject) => {
+        server.once('error', reject);
+        server.listen(port, opts.host ?? '0.0.0.0', () => resolveListen());
+    });
+    const actual = server.address().port;
+    const scheme = tls ? 'https' : 'http';
+    const urls = [hostname(), ...lanAddresses()].map((h) => `${scheme}://${h}:${actual}/`);
+    ctx.listen = () => listenInfo(Boolean(tls), actual);
+    // 自动记账(cotutor.json vault.autoBookkeep,缺省关;src/runtime/auto-bookkeep.ts):隔一阵看一次,开关跟着 cotutor.json 热重载;上一次没跑完不叠
+    let booking = false;
+    const timer = setInterval(() => {
+        if (booking)
+            return;
+        booking = true;
+        void (async () => {
+            await ctx.reload();
+            await autoBookkeep(ctx.runner, ctx.ws, ctx.now());
+        })().catch(() => undefined).finally(() => { booking = false; });
+    }, AUTO_BOOKKEEP_EVERY_MS);
+    timer.unref();
+    server.once('close', () => clearInterval(timer));
+    if (tls && !certCovers(tls.cert, localName()))
+        warnings.push(`证书不含 ${localName()}:扫码打开会报「不安全」(重跑 cotutor cert,再重启 serve)`);
+    return { server, ctx, ws, port: actual, https: Boolean(tls), urls, qrPage: `${scheme}://localhost:${actual}/dev/qr`, warnings };
+}

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

@@ -0,0 +1,30 @@
+export declare const SHIPPED_FILE = ".cotutor/shipped.json";
+export interface ShippedManifest {
+    /** 已安装的出厂教学包;旧版缺省按二年级迁移,与孩子当前年级分开。 */
+    teachingPack?: {
+        grade: number;
+    };
+    /** 出厂 skill(做课包的四个 chalk-* + 本包的机器件)的 hash,与 tutors 同一套机制(src/app/cli/skills.ts) */
+    skills?: Record<string, {
+        hash: string;
+        version: string;
+    }>;
+    /** 出厂主题(themes/<name>/)的目录 hash,同一套机制(src/app/cli/themes.ts) */
+    themes?: Record<string, {
+        hash: string;
+        version: string;
+    }>;
+    /** 出厂 activity(agents/<老师>/activities/<名>.md,键是「老师/名」),同一套机制(src/app/cli/activities.ts) */
+    activities?: Record<string, {
+        hash: string;
+        version: string;
+    }>;
+    version: string;
+    tutors: Record<string, {
+        hash: string;
+        version: string;
+    }>;
+}
+export declare const sha256: (text: string) => string;
+export declare function readManifest(root: string): Promise<ShippedManifest>;
+export declare function writeManifest(root: string, m: ShippedManifest): Promise<void>;

package/dist/app/cli/shipped.js

@@ -0,0 +1,47 @@
+/** 所有出厂件共用的来源记录;修改时保留其他种类的 hash。 */
+import { createHash } from 'node:crypto';
+import { readFile, mkdir, writeFile, rename } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { UsageError } from "../workspace.js";
+export const SHIPPED_FILE = '.cotutor/shipped.json';
+export const sha256 = (text) => `sha256:${createHash('sha256').update(text).digest('hex')}`;
+export async function readManifest(root) {
+    let text;
+    try {
+        text = await readFile(join(root, SHIPPED_FILE), 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { version: '0', tutors: {} };
+        throw err;
+    }
+    try {
+        const raw = JSON.parse(text);
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            throw new Error('顶层要是对象');
+        if (raw.teachingPack !== undefined && (!raw.teachingPack || !Number.isInteger(raw.teachingPack.grade) || raw.teachingPack.grade < 1 || raw.teachingPack.grade > 6))
+            throw new Error('teachingPack.grade 要是 1–6 的整数');
+        for (const key of ['tutors', 'activities', 'skills', 'themes']) {
+            const records = raw[key];
+            if (records === undefined)
+                continue;
+            if (!records || typeof records !== 'object' || Array.isArray(records))
+                throw new Error(`${key} 要是对象`);
+            for (const rec of Object.values(records)) {
+                if (!rec || typeof rec.hash !== 'string' || typeof rec.version !== 'string')
+                    throw new Error(`${key} 的记录要有 hash 和 version`);
+            }
+        }
+        return { ...raw, version: raw.version ?? '0', tutors: raw.tutors ?? {} };
+    }
+    catch (err) {
+        throw new UsageError(`${join(root, SHIPPED_FILE)} 出厂记录用不了:${err.message}。请恢复或修复记录,不会重置 hash 或猜测年级。`);
+    }
+}
+export async function writeManifest(root, m) {
+    const file = join(root, SHIPPED_FILE);
+    await mkdir(dirname(file), { recursive: true });
+    const tmp = `${file}.tmp`;
+    await writeFile(tmp, `${JSON.stringify({ ...m, _note: '出厂时老师文件的 hash,cotutor upgrade 据此分辨「没改过」与「改过」;机器写,不用手改' }, null, 2)}\n`);
+    await rename(tmp, file);
+}

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

@@ -0,0 +1,38 @@
+export declare const DIRS: readonly ["agents", "ledger", "conversations", "bundles"];
+export declare const LEDGER_FILES: readonly ["ledger/artifacts.jsonl"];
+/** 默认年级的出厂老师目录;workspace 的操作用 workspaceGradePack 选来源 */
+export declare const PACKAGE_AGENTS_DIR: string;
+/** 本包版本(出厂件的 hash 记录带它,升级时知道基于哪版) */
+export declare const PACKAGE_VERSION: string;
+export interface ShippedAgent {
+    name: string;
+    file: string;
+    description: string;
+}
+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\u3001CLI \u58F3\u3001qwen \u7684\u5BB6),\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;
+/** 参考目录的 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 {
+    name: string;
+    display: string;
+    subject?: string;
+    description?: string;
+}
+/**
+ * 家长自己加老师时的文件模板:和出厂老师一样只有人设与这一科的做法;
+ * 公共的守则(上下文包、三种回复、记忆段、不变的规矩)在机器技能 cotutor-tutor,应用每个话题第一条放进上下文包。
+ */
+export declare function tutorTemplate(t: TutorTemplateInput): string;
+export interface ConfigTemplateInput {
+    slug: string;
+    name?: string;
+    port?: number;
+    tutors: ShippedAgent[];
+}
+/** cotutor.json 模板:只在文件不存在时写入;政策文件永不自动重建或覆盖(家长的决定不由机器代做)。 */
+export declare function configTemplate(input: ConfigTemplateInput): string;
+/** 把 JSON Schema 写进 workspace(机器文件,每次 init / upgrade 都刷新);板书语法表出厂成技能 cotutor-board,见 skills.ts `writeBoardSkill` */
+export declare function writeSchemaFile(root: string): Promise<string>;