cotutor 0.1.0 → 0.2.0

package/dist/cli/doctor.js

@@ -1,5 +1,5 @@
 /**
- * cotutor doctor:环境 + 工作区逐项体检,失败项附修复命令(错误信息即修复指南)。
+ * cotutor doctor:环境 + workspace逐项体检,失败项附修复命令(错误信息即修复指南)。
  * 静默失败摆到明面:配置坏了、老师链断了、账本有坏行、角色指向踩空。
  * exit 约定同 drawtell / voxtell doctor:必需项全过 exit 0,否则 1;--json 带 ok 与整份 checks。
  */
@@ -9,7 +9,10 @@ import { basename, join } from 'node:path';
 import { promisify } from 'node:util';
 import { parseAgentFile } from "../lib/agent-file.js";
 import { parseArtifactEvents, parseObservations } from "../lib/ledger.js";
+import { parseTimetable } from "../lib/timetable.js";
+import { httpsFiles } from "./serve.js";
 import { DIRS } from "./skeleton.js";
+import { tutorStatuses } from "./tutors.js";
 import { CONFIG_FILE, ConfigError, USER_CONFIG, UsageError, assembleWorkspace, expandPath, parseConfig, readJson, redactHome, resolveRoot, } from "./workspace.js";
 const execFileP = promisify(execFile);
 async function statOrNull(p) {
@@ -23,17 +26,113 @@ async function evictedCount(dir) {
         return 0;
     }
 }
-/** 预设的 CLI 名(run[0] 的 basename):决定链在 .claude 还是 .qwen 下 */
-export function presetCli(run) {
+/** 运行时的 CLI 名(run[0] 的 basename):决定链在 .claude 还是 .qwen 下 */
+export function runtimeCli(run) {
     return basename(run[0] ?? '');
 }
+/** 已知的环境坑,从 CLI 的输出里认出来给修复命令(错误信息即修复指南) */
+export function explainLlmFailure(text, runtime) {
+    const bin = runtimeCli(runtime);
+    if (/does not support this model|version [\d.]+ or newer is required/i.test(text)) {
+        return `这版 ${bin} 不认全局 settings 里的模型:给 cotutor.json 的 ${bin} 运行时 run / resume 末尾加 "--model", "sonnet"(或 ${bin} update 升级)`;
+    }
+    if (/nested|CLAUDECODE|already running inside/i.test(text))
+        return '在 Claude Code 会话里嵌套起 claude 被拒:换个普通终端,或 unset CLAUDECODE 及 CLAUDE_CODE_* 后再跑';
+    if (/not logged in|login|authentication|401|unauthorized/i.test(text))
+        return `${bin} 没登录或 key 失效:先在终端跑一次 ${bin} 登录`;
+    if (/ENOENT|command not found/i.test(text))
+        return `PATH 里没有 ${bin}`;
+    if (/budget|max_budget/i.test(text))
+        return '预算旗太小:调大运行时模板里的 --max-budget-usd';
+    return `看上面的原文;不认识的错先在终端手跑一次同样的命令`;
+}
+/**
+ * --live:真起一次老师(运行时的 run 模板,第一位开着的老师,只回一个字),把 API 层的坑(模型不认、没登录)摆到明面。
+ * 花一分钱级别的费用,所以缺省不跑。配音同理:老师配了 voice 就合成一句。
+ */
+async function probeLive(ws, push, env) {
+    const { spawn } = await import('node:child_process');
+    const { fillRuntime, fillTts, listTutors } = await import("../schema/index.js");
+    const { parseTranscript } = await import("../lib/transcript.js");
+    const { parseAgentFile } = await import("../lib/agent-file.js");
+    const { tmpdir } = await import('node:os');
+    const { mkdtemp, rm } = await import('node:fs/promises');
+    const tutors = listTutors(ws.config).filter((t) => t.enabled);
+    const first = tutors[0];
+    if (!first) {
+        push({ name: 'live.agent', ok: false, required: false, detail: '没有开着的老师,没法探', fix: 'cotutor.json 里至少开一位' });
+        return;
+    }
+    const runtimeName = ws.config.runtimes.default;
+    const runtime = ws.config.runtimes[runtimeName];
+    if (!runtime || typeof runtime === 'string')
+        return;
+    let agentBody;
+    try {
+        agentBody = parseAgentFile(await readFile(join(ws.dirs.claudeAgents, `${first.name}.md`), 'utf8')).body;
+    }
+    catch {
+        /* 上面 tutor.* 已报 */
+    }
+    const argv = fillRuntime(runtime.run, { agent: first.name, prompt: '只回一个字:好', agentBody });
+    const cwd = join(ws.dirs.agents, first.name);
+    const run = await new Promise((resolveRun) => {
+        let out = '';
+        let err = '';
+        const child = spawn(argv[0], argv.slice(1), { cwd, env: { ...env, COTUTOR_WORKSPACE: ws.root }, stdio: ['ignore', 'pipe', 'pipe'] });
+        const timer = setTimeout(() => child.kill(), 120_000);
+        child.stdout.on('data', (d) => (out += d.toString()));
+        child.stderr.on('data', (d) => (err += d.toString()));
+        child.once('error', (e) => {
+            clearTimeout(timer);
+            resolveRun({ out, err, code: null, spawnErr: e.message });
+        });
+        child.once('close', (code) => {
+            clearTimeout(timer);
+            resolveRun({ out, err, code });
+        });
+    });
+    const t = parseTranscript(run.out);
+    const said = t.items.filter((i) => i.kind === 'text' && !i.sub).map((i) => i.text).join(' ');
+    const ok = Boolean(t.final?.ok) && !run.spawnErr;
+    const raw = run.spawnErr ?? (t.final ? `${t.final.reason ?? ''} ${said}`.trim() : `没有 result 事件(exit ${run.code}):${run.err.trim().split('\n').slice(-3).join(' / ')}`);
+    push({
+        name: `live.${runtimeName}`,
+        ok,
+        required: false,
+        detail: ok ? `${first.display} 回了「${(t.final?.text ?? '').slice(0, 20)}」${t.final?.costUsd !== undefined ? ` · $${t.final.costUsd.toFixed(3)}` : ''}` : `起不来或没答上:${raw.slice(0, 300)}`,
+        fix: ok ? undefined : explainLlmFailure(raw, runtime.run),
+    });
+    const voiced = tutors.find((x) => x.voice);
+    if (!voiced) {
+        push({ name: 'live.tts', ok: true, required: false, detail: '没有老师配 voice,不探配音(孩子端用浏览器的声)' });
+        return;
+    }
+    const dir = await mkdtemp(join(tmpdir(), 'cotutor-doctor-'));
+    const out = join(dir, 'probe.mp3');
+    const argvT = fillTts(ws.config.tts.say, { text: '你好', voice: voiced.voice, out });
+    const r = await new Promise((resolveTts) => {
+        execFile(argvT[0], argvT.slice(1), { env, timeout: 60_000 }, async (e, _o, se) => {
+            if (e)
+                return resolveTts({ ok: false, msg: e.code === 'ENOENT' ? `PATH 里没有 ${argvT[0]}` : `${e.message} ${String(se).trim().slice(-200)}` });
+            const st = await stat(out).catch(() => null);
+            resolveTts(st?.isFile() && st.size > 0 ? { ok: true, msg: `${voiced.display} 的音色 ${voiced.voice} 能合成(${st.size} 字节)` } : { ok: false, msg: '命令跑完但没出文件' });
+        });
+    });
+    await rm(dir, { recursive: true, force: true });
+    push({ name: 'live.tts', ok: r.ok, required: false, detail: r.msg, fix: r.ok ? undefined : `改 cotutor.json 的 tts.say(voxtell 不在 PATH 就写完整路径),或查 voxtell doctor` });
+}
 export async function doctorWorkspace(override, opts = {}) {
     const probeEnv = opts.probeEnv ?? true;
+    const env = opts.env ?? process.env;
     const checks = [];
     const push = (c) => checks.push(c);
     const [maj, min] = process.versions.node.split('.').map(Number);
     const nodeOk = maj > 22 || (maj === 22 && min >= 18);
     push({ name: 'node', ok: nodeOk, required: true, detail: `node ${process.versions.node}`, fix: nodeOk ? undefined : '需要 Node ≥ 22.18' });
+    if (env.CLAUDECODE) {
+        push({ name: 'env.nested', ok: false, required: false, detail: '现在在 Claude Code 会话里(CLAUDECODE 已设),从这里起的 claude 老师会被当嵌套拒掉', fix: '换个普通终端跑 cotutor serve;或 unset CLAUDECODE CLAUDE_CODE_ENTRYPOINT CLAUDE_CODE_SESSION_ID CLAUDE_CODE_CHILD_SESSION CLAUDE_PID CLAUDE_EFFORT' });
+    }
     let root = null;
     let source = null;
     try {
@@ -67,7 +166,7 @@ export async function doctorWorkspace(override, opts = {}) {
                 name: CONFIG_FILE,
                 ok: true,
                 required: true,
-                detail: `kid ${config.kid.slug}、${Object.keys(config.teachers).length} 位老师、预设 ${config.agents.default}、端口 ${config.server.port}`,
+                detail: `kid ${config.kid.slug}、${Object.keys(config.tutors).length} 位老师、运行时 ${config.runtimes.default}、端口 ${config.server.port}`,
             });
         }
     }
@@ -97,9 +196,11 @@ export async function doctorWorkspace(override, opts = {}) {
         fix: rulesMissing.length ? 'cotutor init 补上(已有的不动)' : undefined,
     });
     if (ws) {
-        // ---- 老师:定义链 + 名字一致 + 老师目录 ----
-        const defaultCli = presetCli(ws.config.agents[ws.config.agents.default]?.run ?? []);
-        for (const name of Object.keys(ws.config.teachers)) {
+        // ---- 老师:定义文件(拷贝)+ 名字一致 + 出厂 / 自定义状态 + 老师目录 ----
+        const defaultCli = runtimeCli(ws.config.runtimes[ws.config.runtimes.default]?.run ?? []);
+        const statuses = new Map((await tutorStatuses(root)).map((s) => [s.name, s]));
+        for (const name of Object.keys(ws.config.tutors)) {
+            const shipped = statuses.has(name);
             for (const [cli, dir] of [
                 ['claude', ws.dirs.claudeAgents],
                 ['qwen', ws.dirs.qwenAgents],
@@ -117,16 +218,53 @@ export async function doctorWorkspace(override, opts = {}) {
                     detail = `${redactHome(file)} 读不到(链断了或没建)`;
                 }
                 push({
-                    name: `teacher.${name}.${cli}`,
+                    name: `tutor.${name}.${cli}`,
                     ok,
                     required,
                     detail,
-                    fix: ok ? undefined : `cotutor init 重链(链到本包 agents/${name}.md),或把老师键改成文件里的 name`,
+                    fix: ok
+                        ? undefined
+                        : shipped
+                            ? `cotutor init 补拷(拷自本包 agents/${name}.md),或把老师键改成文件里的 name`
+                            : cli === 'qwen'
+                                ? 'cotutor init 补链(.qwen/agents/ 指向 .claude/agents/)'
+                                : `这是自家加的老师:写 .claude/agents/${name}.md(frontmatter name: ${name}),cotutor add ${name} --display <显示名> 可出模板;或把 cotutor.json 里这条删掉`,
+                });
+            }
+            const st = statuses.get(name);
+            if (!st)
+                push({ name: `tutor.${name}.origin`, ok: true, required: false, detail: '自家加的老师(不是出厂件,upgrade 不碰)' });
+            if (st) {
+                const label = { latest: '出厂件,最新', upgradable: `出厂件,基于 ${st.basedOn},包已更新`, custom: `自定义(基于 ${st.basedOn})`, untracked: '自定义(没有出厂记录)', missing: '缺', broken: '读不到' };
+                push({
+                    name: `tutor.${name}.origin`,
+                    ok: st.state !== 'upgradable' && !st.legacyLink,
+                    required: false,
+                    detail: st.legacyLink ? '还是指向包的旧链(改它会改到包里)' : label[st.state],
+                    fix: st.legacyLink ? 'cotutor init 换成拷贝' : st.state === 'upgradable' ? 'cotutor upgrade 换新版' : undefined,
                 });
             }
             const home = join(ws.dirs.agents, name);
             const there = (await statOrNull(home))?.isDirectory() ?? false;
-            push({ name: `teacher.${name}.home`, ok: there, required: true, detail: there ? `agents/${name}/ 在(会话 cwd)` : `agents/${name}/ 不在`, fix: there ? undefined : 'cotutor init 补建' });
+            push({ name: `tutor.${name}.home`, ok: there, required: true, detail: there ? `agents/${name}/ 在(会话 cwd)` : `agents/${name}/ 不在`, fix: there ? undefined : 'cotutor init 补建' });
+        }
+        // ---- 板书语法表:老师讲解前读它;机器文件,init / upgrade 刷新 ----
+        {
+            const { SYNTAX_FILE } = await import("./skeleton.js");
+            const there = (await statOrNull(join(root, SYNTAX_FILE)))?.isFile() ?? false;
+            push({ name: 'board.syntax', ok: there, required: true, detail: there ? `${SYNTAX_FILE} 在(老师讲解前读的语法表)` : `${SYNTAX_FILE} 不在,老师不知道卡怎么写`, fix: there ? undefined : 'cotutor init 或 cotutor upgrade 生成' });
+            // 舞台包与 drawtell:场景卡 / 画板卡要它们;没有只是重卡打不开,轻卡与对话照常
+            const { stageBuilt } = await import("../server/stage.js");
+            const built = stageBuilt();
+            push({ name: 'stage.bundle', ok: built, required: false, detail: built ? 'dist/stage/ 在(舞台包:场景卡与画板卡的播放器)' : 'dist/stage/ 不在,场景卡与画板卡的舞台打不开(轻卡照常)', fix: built ? undefined : '仓库根 pnpm run build:stage(npm 装的包自带)' });
+            const { TOOL_SHIM, drawtellBin, skillStatuses } = await import("./skills.js");
+            const dt = drawtellBin();
+            const shim = (await statOrNull(join(root, TOOL_SHIM)))?.isFile() ?? false;
+            push({ name: 'drawtell', ok: dt !== null && shim, required: false, detail: !dt ? 'node_modules 里没有 drawtell,场景作业跑不了' : shim ? `${TOOL_SHIM} 在,指向本包的 drawtell(scene-maker 用它 check / build / dub / snap)` : `${TOOL_SHIM} 不在,scene-maker 找不到 drawtell`, fix: !dt ? '仓库根 pnpm install' : shim ? undefined : 'cotutor init 或 cotutor upgrade 生成' });
+            for (const sk of await skillStatuses(root)) {
+                const label = { latest: '出厂件,最新', upgradable: `出厂件,基于 ${sk.basedOn},包已更新`, custom: `自定义(基于 ${sk.basedOn})`, untracked: '自定义(没有出厂记录)', missing: '缺', unavailable: 'drawtell-skills 没装,没法拷' };
+                push({ name: `skill.${sk.name}`, ok: sk.state !== 'missing' && sk.state !== 'unavailable' && sk.state !== 'upgradable', required: false, detail: `.claude/skills/${sk.name}/:${label[sk.state]}`, fix: sk.state === 'missing' ? 'cotutor init 补拷' : sk.state === 'upgradable' ? 'cotutor upgrade 换新版' : sk.state === 'unavailable' ? '仓库根 pnpm install' : undefined });
+            }
         }
         // ---- paths 角色指向:配了就该在 ----
         for (const [role, value] of Object.entries(ws.config.paths)) {
@@ -153,23 +291,50 @@ export async function doctorWorkspace(override, opts = {}) {
                 push({ name: `ledger.${name}`, ok: true, required: false, detail: '没有(还没记过);cotutor init 会建空文件' });
             }
         }
-        // ---- 预设的 CLI 在不在 ----
+        // ---- 课程表:有就要能解析(孩子端首页与上下文包的 slot 靠它;没有不算错)----
+        try {
+            const tt = parseTimetable(await readFile(ws.paths.timetable, 'utf8'));
+            push({
+                name: 'timetable',
+                ok: tt.found && tt.errors.length === 0,
+                required: false,
+                detail: tt.found ? (tt.errors.length ? tt.errors.slice(0, 3).join(';') : `${tt.entries.length} 个时段`) : tt.errors[0],
+                fix: tt.found && !tt.errors.length ? undefined : `改 ${redactHome(ws.paths.timetable)}:表头 星期/时间/学科(孩子列可选),时间形如 19:00–19:40`,
+            });
+        }
+        catch {
+            push({ name: 'timetable', ok: true, required: false, detail: `没有课程表(${redactHome(ws.paths.timetable)});孩子端「今天」只画老师,不画时段` });
+        }
+        // ---- HTTPS:iPad 上录音要;没有只提醒 ----
+        const tls = httpsFiles(ws);
+        push({ name: 'https', ok: tls !== null, required: false, detail: tls ? `${redactHome(tls.cert)}` : '没有证书,serve 走 HTTP(iPad Safari 上按住说话不可用)', fix: tls ? undefined : 'cotutor cert(需要 mkcert:brew install mkcert && mkcert -install)' });
+        // ---- 运行时的 CLI 在不在 ----
         if (probeEnv) {
-            for (const [preset, p] of Object.entries(ws.config.agents)) {
-                if (preset === 'default' || typeof p === 'string')
+            const ttsBin = runtimeCli(ws.config.tts.say);
+            try {
+                await execFileP(ttsBin, ['--version'], { timeout: 8000 });
+                push({ name: 'tts', ok: true, required: false, detail: `${ttsBin} 在;老师配了 voice 的回复会配音` });
+            }
+            catch {
+                push({ name: 'tts', ok: false, required: false, detail: `PATH 里没有 ${ttsBin},回复不配音(孩子端用浏览器的声)`, fix: `装 ${ttsBin},或改 cotutor.json 的 tts.say` });
+            }
+            for (const [runtime, p] of Object.entries(ws.config.runtimes)) {
+                if (runtime === 'default' || typeof p === 'string')
                     continue;
-                const bin = presetCli(p.run);
-                const required = preset === ws.config.agents.default;
+                const bin = runtimeCli(p.run);
+                const required = runtime === ws.config.runtimes.default;
                 try {
                     const { stdout } = await execFileP(bin, ['--version'], { timeout: 8000 });
-                    push({ name: `agents.${preset}`, ok: true, required, detail: `${bin} ${stdout.trim().split('\n')[0]}` });
+                    push({ name: `runtime.${runtime}`, ok: true, required, detail: `${bin} ${stdout.trim().split('\n')[0]}` });
                 }
                 catch {
-                    push({ name: `agents.${preset}`, ok: false, required, detail: `PATH 里没有 ${bin}`, fix: required ? `装 ${bin},或把 agents.default 改成装了的那个预设` : undefined });
+                    push({ name: `runtime.${runtime}`, ok: false, required, detail: `PATH 里没有 ${bin}`, fix: required ? `装 ${bin},或把 runtimes.default 改成装了的那个运行时` : undefined });
                 }
             }
         }
     }
+    if (ws && opts.live)
+        await probeLive(ws, push, env);
     // ---- 用户配置 ----
     try {
         const text = await readFile(USER_CONFIG, 'utf8');
@@ -185,6 +350,6 @@ export async function doctorWorkspace(override, opts = {}) {
         push({ name: 'user-config', ok: true, required: false, detail: `未配置(可选):{"workspace": "…"} 写进 ${redactHome(USER_CONFIG)};cotutor init 会代劳` });
     }
     const gitThere = (await statOrNull(join(root, '.git'))) !== null;
-    push({ name: 'git', ok: gitThere, required: false, detail: gitThere ? '工作区是 git 仓' : '工作区不在 git 里', fix: gitThere ? undefined : '建议 git init:老师记忆、账本、政策都是不可再生状态' });
+    push({ name: 'git', ok: gitThere, required: false, detail: gitThere ? 'workspace是 git 仓' : 'workspace不在 git 里', fix: gitThere ? undefined : '建议 git init:老师记忆、账本、政策都是不可再生状态' });
     return { ok: checks.filter((c) => c.required).every((c) => c.ok), root, source, checks };
 }

package/dist/cli/init.d.ts

@@ -1,6 +1,6 @@
 export interface InitStep {
     item: string;
-    action: 'created' | 'exists' | 'kept';
+    action: 'created' | 'exists' | 'kept' | 'replaced';
     note?: string;
 }
 export interface InitResult {

package/dist/cli/init.js

@@ -1,19 +1,18 @@
 /**
  * cotutor init <slug>:建 ~/cotutor/<slug>/ 骨架。语义是**幂等补缺**——已有的文件与目录一律不动,缺什么补什么。
  * 三条边界(沿 drawtell init):政策文件只在缺失时写模板;用户配置只在还没指定 workspace 时补;不动 git。
- * 老师定义不拷贝,**链**到本包 agents/(共享的是定义,不共享记忆与账本);链已存在(哪怕是实体文件)就不动。
+ * 老师文件**拷贝**进 .claude/agents/(2026-09-09 拍板,原来是链):拷进来就是家长的,想改就改;出厂 hash 记 .cotutor/shipped.json,
+ * cotutor upgrade 据此换新或报 diff。旧workspace里指向包的链会被换成拷贝。.qwen/agents/ 是指向 .claude/agents/ 的相对链。
  */
-import { mkdir, readFile, stat, symlink, writeFile } from 'node:fs/promises';
-import { basename, dirname, join, resolve } from 'node:path';
-import { DIRS, GITIGNORE, LEDGER_FILES, RULES, configTemplate, shippedAgents } from "./skeleton.js";
-import { CONFIG_FILE, HOME_ROOT, USER_CONFIG, expandPath } from "./workspace.js";
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { DIRS, GITIGNORE, LEDGER_FILES, RULES, SYNTAX_FILE, configTemplate, shippedAgents, writeSchemaFile, writeSyntaxFile } from "./skeleton.js";
+import { installTutors } from "./tutors.js";
+import { TOOL_SHIM, installSkills, writeToolShim } from "./skills.js";
+import { CONFIG_FILE, ConfigError, HOME_ROOT, USER_CONFIG, expandPath, parseConfig, readJson } from "./workspace.js";
 async function exists(p) {
     return (await stat(p).catch(() => null)) !== null;
 }
-async function lexists(p) {
-    const { lstat } = await import('node:fs/promises');
-    return (await lstat(p).catch(() => null)) !== null;
-}
 export async function initWorkspace(opts) {
     const root = opts.dir ? expandPath(opts.dir, resolve(process.cwd())) : join(HOME_ROOT, opts.slug);
     const steps = [];
@@ -31,26 +30,36 @@ export async function initWorkspace(opts) {
         await mkdir(p, { recursive: true });
         steps.push({ item: `${dir}/`, action: 'created' });
     }
-    for (const a of agents) {
-        const home = join(root, 'agents', a.name);
-        if (await exists(home)) {
-            steps.push({ item: `agents/${a.name}/`, action: 'exists' });
-        }
-        else {
-            await mkdir(home, { recursive: true });
-            await writeFile(join(home, '.gitkeep'), '');
-            steps.push({ item: `agents/${a.name}/`, action: 'created' });
-        }
-        for (const sub of ['.claude/agents', '.qwen/agents']) {
-            const link = join(root, sub, basename(a.file));
-            if (await lexists(link)) {
-                steps.push({ item: `${sub}/${basename(a.file)}`, action: 'exists' });
-                continue;
-            }
-            await symlink(a.file, link);
-            steps.push({ item: `${sub}/${basename(a.file)}`, action: 'created', note: `→ ${a.file}` });
-        }
+    const config = join(root, CONFIG_FILE);
+    if (await exists(config))
+        steps.push({ item: CONFIG_FILE, action: 'kept', note: '政策文件不覆盖(家长的决定)' });
+    else {
+        await writeFile(config, configTemplate({ slug: opts.slug, name: opts.name, port: opts.port, tutors: agents }));
+        steps.push({ item: CONFIG_FILE, action: 'created' });
     }
+    // 老师按 cotutor.json 里有谁走(家长自己加的也补目录与链);配置坏了就只管出厂的,doctor 去报
+    let tutorNames = [];
+    try {
+        const raw = readJson(config);
+        if (raw !== null)
+            tutorNames = Object.keys(parseConfig(raw, config).tutors);
+    }
+    catch (err) {
+        if (!(err instanceof ConfigError))
+            throw err;
+    }
+    steps.push(...(await installTutors(root, tutorNames)));
+    const schemaThere = await exists(join(root, '.cotutor', 'cotutor.schema.json'));
+    await writeSchemaFile(root);
+    steps.push({ item: '.cotutor/cotutor.schema.json', action: schemaThere ? 'exists' : 'created', note: schemaThere ? '已按本包刷新(机器文件)' : 'cotutor.json 的 JSON Schema,编辑器补全用' });
+    const syntaxThere = await exists(join(root, SYNTAX_FILE));
+    await writeSyntaxFile(root);
+    steps.push({ item: SYNTAX_FILE, action: syntaxThere ? 'exists' : 'created', note: syntaxThere ? '已按本包刷新(机器文件)' : '给老师看的板书语法表,从卡的注册表生成' });
+    // 出厂 skill(scene-maker 的四个领域 skill)与 drawtell 壳脚本
+    steps.push(...(await installSkills(root)));
+    const shimThere = await exists(join(root, TOOL_SHIM));
+    const shim = await writeToolShim(root);
+    steps.push({ item: TOOL_SHIM, action: shimThere ? 'exists' : 'created', note: shim.available ? (shimThere ? '已按本包刷新(机器文件)' : 'drawtell CLI 的壳,scene-maker 用 ../../.cotutor/drawtell 跑它') : 'node_modules 里没有 drawtell,壳只会报错' });
     for (const f of LEDGER_FILES) {
         const p = join(root, f);
         if (await exists(p))
@@ -60,13 +69,6 @@ export async function initWorkspace(opts) {
             steps.push({ item: f, action: 'created' });
         }
     }
-    const config = join(root, CONFIG_FILE);
-    if (await exists(config))
-        steps.push({ item: CONFIG_FILE, action: 'kept', note: '政策文件不覆盖(家长的决定)' });
-    else {
-        await writeFile(config, configTemplate({ slug: opts.slug, name: opts.name, port: opts.port, teachers: agents }));
-        steps.push({ item: CONFIG_FILE, action: 'created' });
-    }
     for (const f of ['CLAUDE.md', 'QWEN.md']) {
         const p = join(root, f);
         if (await exists(p))
@@ -97,18 +99,18 @@ export async function initWorkspace(opts) {
         steps.push({ item: 'user-config', action: 'kept', note: '解析失败,未动(cotutor doctor 可体检)' });
     else if (configured) {
         steps.push(expandPath(configured, root) === root
-            ? { item: 'user-config', action: 'exists', note: '已指向本工作区' }
-            : { item: 'user-config', action: 'kept', note: '已指向别的工作区,未改;多孩子时一 workspace 一进程,用 --workspace / COTUTOR_WORKSPACE 指定' });
+            ? { item: 'user-config', action: 'exists', note: '已指向本workspace' }
+            : { item: 'user-config', action: 'kept', note: '已指向别的workspace,未改;多孩子时一 workspace 一进程,用 --workspace / COTUTOR_WORKSPACE 指定' });
     }
     else {
         await mkdir(dirname(USER_CONFIG), { recursive: true });
         await writeFile(USER_CONFIG, `${JSON.stringify({ ...(user ?? {}), workspace: root }, null, 2)}\n`);
-        steps.push({ item: 'user-config', action: 'created', note: 'workspace 指向本工作区' });
+        steps.push({ item: 'user-config', action: 'created', note: 'workspace 指向本workspace' });
     }
     const suggestions = [];
     if (!(await exists(join(root, '.git'))))
         suggestions.push('git init(建议:老师记忆、账本、政策都是不可再生状态,git 是破坏后的兜底)');
-    suggestions.push(`改 ${CONFIG_FILE}:paths.vault 指到孩子的 Obsidian vault,teachers.*.voice 填 voxtell 音色 id`);
+    suggestions.push(`改 ${CONFIG_FILE}:paths.vault 指到孩子的 Obsidian vault,tutors.*.voice 填 voxtell 音色 id`);
     suggestions.push('cotutor doctor 逐项体检;cotutor serve 起服务');
     return { root, steps, suggestions };
 }

package/dist/cli/main.js

@@ -6,14 +6,27 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { doctorWorkspace } from "./doctor.js";
 import { initWorkspace } from "./init.js";
+import { makeCert } from "./cert.js";
+import { addTutorFile, upgradeTutors } from "./tutors.js";
+import { upgradeSkills, writeToolShim } from "./skills.js";
+import { patchConfig } from "../server/store.js";
+import { resolveRoot } from "./workspace.js";
 import { serveWorkspace } from "./serve.js";
-import { UsageError, redactDeep, redactHome, workspaceReport } from "./workspace.js";
+import { serveMock } from "../server/mock.js";
+import { UsageError, loadWorkspace, redactDeep, redactHome, workspaceReport } from "./workspace.js";
+import { createContext } from "../server/app.js";
+import { MESSAGE_FROM } from "../schema/index.js";
 const USAGE = `用法:
   cotutor init <slug> [--dir <path>] [--name <孩子名>] [--port <n>]   建 ~/cotutor/<slug>/ 骨架(幂等补缺)
-  cotutor doctor [--workspace <dir>] [--json]                          逐项体检
-  cotutor serve [--workspace <dir>] [--port <n>]                        起服务(一 workspace 一进程)
+  cotutor doctor [--workspace <dir>] [--json] [--live]                 逐项体检;--live 真起一次老师与配音(花一分钱)把 API 层的坑摆出来
+  cotutor upgrade [--workspace <dir>] [--force <老师>]...                老师文件换新版:没改过的直接换,改过的只报 diff(--force 才覆盖,原文留 .bak)
+  cotutor add <老师名> --display <显示名> [--subject <学科>] [--avatar <emoji>] [--hidden]   加一位自家的老师:出模板文件、进 cotutor.json、建目录
+  cotutor serve [--workspace <dir>] [--port <n>] [--http]               起服务(一 workspace 一进程;~/.config/cotutor/certs/ 有证书就走 HTTPS)
+  cotutor cert [--host <名或IP>]...                                      用 mkcert 建这台机器的自签证书到 ~/.config/cotutor/certs/(iPad 上录音要 HTTPS;所有 workspace 共用)
+  cotutor send <老师> <消息> [--from parent|kid|system] [--runtime <名>]   终端里发一条,等老师说完打印结果(与页面同一条路)
+  cotutor mock [--port <n>] [--scenario normal|limit|offline] [--delay <ms>] [--http]   不经真实老师与配音,用固定的板书 JSON 起孩子端,测前端交互与渲染(不需要 workspace)
   cotutor --version | --help
-工作区解析:--workspace > COTUTOR_WORKSPACE > cwd 或祖先有 cotutor.json > ~/.config/cotutor/config.json > ~/cotutor/ 下唯一的孩子目录
+workspace解析:--workspace > COTUTOR_WORKSPACE > cwd 或祖先有 cotutor.json > ~/.config/cotutor/config.json > ~/cotutor/ 下唯一的孩子目录
 `;
 function version() {
     const pkg = JSON.parse(readFileSync(fileURLToPath(new URL('../../package.json', import.meta.url)), 'utf8'));
@@ -47,7 +60,7 @@ function parseArgs(argv, valued) {
 export async function main(argv) {
     let json = false;
     try {
-        const { cmd, positionals, flags } = parseArgs(argv, ['workspace', 'dir', 'name', 'port']);
+        const { cmd, positionals, flags } = parseArgs(argv, ['workspace', 'dir', 'name', 'port', 'from', 'runtime', 'force', 'display', 'subject', 'avatar', 'description', 'scenario', 'delay']);
         json = flags.json === true;
         const workspace = typeof flags.workspace === 'string' ? flags.workspace : undefined;
         // --version / --help 是旗标不是命令,parseArgs 把它们收进 flags,cmd 拿不到,所以在 switch 前处理
@@ -81,7 +94,7 @@ export async function main(argv) {
                 return;
             }
             case 'doctor': {
-                const r = await doctorWorkspace(workspace);
+                const r = await doctorWorkspace(workspace, { live: flags.live === true });
                 if (json)
                     process.stdout.write(`${JSON.stringify(redactDeep(r), null, 2)}\n`);
                 else {
@@ -98,11 +111,118 @@ export async function main(argv) {
             }
             case 'serve': {
                 const port = typeof flags.port === 'string' ? Number(flags.port) : undefined;
-                const r = await serveWorkspace({ workspace, port });
+                const r = await serveWorkspace({ workspace, port, http: flags.http === true });
                 process.stdout.write(`cotutor serve ${JSON.stringify(workspaceReport(r.ws))}\n`);
                 for (const w of r.warnings)
                     process.stdout.write(`  ! ${w}\n`);
-                process.stdout.write(`  ${r.url}\n`);
+                if (!r.https)
+                    process.stdout.write('  ! HTTP:iPad Safari 上按住说话要 HTTPS;cotutor cert 建证书后重启即走 HTTPS\n');
+                for (const u of r.urls)
+                    process.stdout.write(`  ${u}\n`);
+                process.stdout.write(`  孩子端 /,家长端 /parent\n`);
+                return;
+            }
+            case 'mock': {
+                const port = typeof flags.port === 'string' ? Number(flags.port) : undefined;
+                if (port !== undefined && !(Number.isInteger(port) && port > 0 && port < 65536))
+                    throw new UsageError('--port 要是 1–65535 的整数');
+                const scenario = typeof flags.scenario === 'string' ? flags.scenario : 'normal';
+                if (!['normal', 'limit', 'offline'].includes(scenario))
+                    throw new UsageError('--scenario 只能是 normal / limit / offline');
+                const delayMs = typeof flags.delay === 'string' ? Number(flags.delay) : undefined;
+                if (delayMs !== undefined && !(Number.isInteger(delayMs) && delayMs >= 0))
+                    throw new UsageError('--delay 要是非负整数(毫秒)');
+                const r = await serveMock({ port, scenario: scenario, delayMs, http: flags.http === true });
+                process.stdout.write(`cotutor mock 场景 ${scenario}(不经真实老师与配音;配音退回浏览器合成声)\n`);
+                if (!r.https)
+                    process.stdout.write('  ! HTTP:iPad Safari 上按住说话要 HTTPS;cotutor cert 建证书后重启即走 HTTPS\n');
+                for (const u of r.urls)
+                    process.stdout.write(`  ${u}\n`);
+                process.stdout.write('  孩子端 /;直接开某位老师并停在某句:/?tutor=chinese-tutor&step=0.3\n');
+                return;
+            }
+            case 'add': {
+                const name = positionals[0];
+                const display = typeof flags.display === 'string' ? flags.display : undefined;
+                if (!name || !display)
+                    throw new UsageError(`add 需要老师名和 --display 显示名,如 cotutor add science-tutor --display 科学老师 --subject 科学 --avatar 🔬。\n${USAGE}`);
+                const ws = loadWorkspace(workspace);
+                if (ws.config.tutors[name])
+                    throw new UsageError(`cotutor.json 里已经有 ${name} 了;要改人设去老师团页或直接改文件`);
+                const subject = typeof flags.subject === 'string' ? flags.subject : undefined;
+                const r = await addTutorFile(ws.root, { name, display, subject, description: typeof flags.description === 'string' ? flags.description : undefined });
+                await patchConfig(ws, { tutors: { [name]: { display, ...(subject ? { subject } : {}), ...(typeof flags.avatar === 'string' ? { avatar: flags.avatar } : {}), enabled: true, ...(flags.hidden === true ? { hidden: true } : {}) } } });
+                if (json)
+                    process.stdout.write(`${JSON.stringify(redactDeep(r), null, 2)}\n`);
+                else {
+                    process.stdout.write(`加了 ${display}(${name}):\n  ${redactHome(r.file)}  ← 老师文件,打开把括号里那句换成这位老师的性子\n  cotutor.json tutors.${name}  ← 人设与政策(老师团页也能改)\n  ${redactHome(r.home)}/  ← 它的家\n`);
+                    process.stdout.write('服务不用重启;孩子端和家长端刷新就有。\n');
+                }
+                return;
+            }
+            case 'upgrade': {
+                const { root } = resolveRoot(workspace);
+                const force = typeof flags.force === 'string' ? [flags.force, ...positionals] : positionals;
+                const steps = await upgradeTutors(root, { force });
+                const skillSteps = await upgradeSkills(root);
+                await writeToolShim(root);
+                if (json)
+                    process.stdout.write(`${JSON.stringify(redactDeep({ root, steps, skills: skillSteps }), null, 2)}\n`);
+                else {
+                    const word = { upgraded: '已换新', latest: '已是最新', 'kept-custom': '自定义,保留', forced: '已覆盖(原文 .bak)', installed: '补上了', unavailable: 'drawtell-skills 没装,没法换' };
+                    for (const s of skillSteps)
+                        process.stdout.write(`${s.action === 'kept-custom' || s.action === 'unavailable' ? '!' : '✓'} skill ${s.name.padEnd(18)} ${word[s.action]}${s.basedOn && s.action !== 'latest' ? `(基于 ${s.basedOn})` : ''}\n`);
+                    for (const s of steps) {
+                        process.stdout.write(`${s.action === 'kept-custom' ? '!' : '✓'} ${s.name.padEnd(18)} ${word[s.action]}${s.basedOn && s.action !== 'latest' ? `(基于 ${s.basedOn})` : ''}\n`);
+                        if (s.diff?.length) {
+                            process.stdout.write(`    你的 vs 新版(- 你的 / + 新版),想用新版:cotutor upgrade --force ${s.name}\n`);
+                            for (const l of s.diff.slice(0, 40))
+                                process.stdout.write(`    ${l}\n`);
+                            if (s.diff.length > 40)
+                                process.stdout.write(`    …还有 ${s.diff.length - 40} 行\n`);
+                        }
+                    }
+                }
+                return;
+            }
+            case 'cert': {
+                const r = await makeCert(positionals.concat(typeof flags.host === 'string' ? [flags.host] : []));
+                if (json)
+                    process.stdout.write(`${JSON.stringify(redactDeep(r), null, 2)}\n`);
+                else {
+                    process.stdout.write(`证书:${redactHome(r.cert)}\n私钥:${redactHome(r.key)}\n主机:${r.hosts.join(' ')}\n`);
+                    process.stdout.write(`iPad 要先信任这台机器的根证书:把 ${redactHome(r.caRoot)}/rootCA.pem 隔空投送到 iPad → 设置里安装描述文件 → 通用 › 关于本机 › 证书信任设置里打开;然后重启 cotutor serve,用 https 打开。\n`);
+                }
+                return;
+            }
+            case 'send': {
+                const [tutor, ...words] = positionals;
+                const text = words.join(' ');
+                if (!tutor || !text)
+                    throw new UsageError(`send 需要老师名和消息,如 cotutor send math-tutor "这一步为什么要借位"。\n${USAGE}`);
+                const from = typeof flags.from === 'string' ? flags.from : 'parent';
+                if (!MESSAGE_FROM.includes(from))
+                    throw new UsageError(`--from 只能是 ${MESSAGE_FROM.join(' / ')}`);
+                const ctx = createContext(loadWorkspace(workspace));
+                const started = await ctx.runner.send(tutor, { from: from, text, runtime: typeof flags.runtime === 'string' ? flags.runtime : undefined });
+                if (!json)
+                    process.stdout.write(`→ ${tutor} ${started.date} ${started.job}(${started.plan.runtime}${started.plan.resume ? ',resume ' + started.plan.session : ',新会话'})…\n`);
+                const index = await started.done;
+                const m = index.messages.find((x) => x.job === started.job);
+                if (json)
+                    process.stdout.write(`${JSON.stringify({ tutor, date: started.date, job: started.job, runtime: started.plan.runtime, resume: started.plan.resume, message: m, session: index.session, costUsd: index.costUsd }, null, 2)}\n`);
+                else if (!m || m.result !== 'ok') {
+                    process.stdout.write(`本轮出错:${m?.error ?? '未知'};看 conversations/${tutor}/${started.date}.${started.job}.err.log\n`);
+                    process.exitCode = 1;
+                }
+                else {
+                    process.stdout.write(`孩子看到:${m.kidText ?? '(没有给孩子的话)'}\n`);
+                    if (m.holdup)
+                        process.stdout.write(`待裁量:${m.holdup.question}${m.holdup.options.length ? ' → ' + m.holdup.options.map((o) => o.label).join(' / ') : ''}\n`);
+                    if (m.handoff)
+                        process.stdout.write(`转交:${m.handoff.to}${m.handoff.why ? ' — ' + m.handoff.why : ''}\n`);
+                    process.stdout.write(`会话 ${index.session?.id ?? '?'} · 本轮 $${(m.costUsd ?? 0).toFixed(2)} · 今日 $${index.costUsd.toFixed(2)}\n`);
+                }
                 return;
             }
             default:

package/dist/cli/serve.d.ts

@@ -1,19 +1,30 @@
-/**
- * cotutor serve:一 workspace 一进程(2026-09-08 拍板),端口读 cotutor.json(--port 覆盖)。
- * 启动打印解析结果与体检警告(配置坏了直接不起,骨架缺失只警告)。
- */
 import { type Server } from 'node:http';
+import { type AppContext } from '../server/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[];
+    /** 兼容:urls[0] */
     url: 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 用它访问;.local 名不一定解析得到) */
+export declare function lanAddresses(): string[];
 export declare function serveWorkspace(opts?: ServeOptions): Promise<ServeResult>;