cotutor 0.4.4 → 0.4.5

package/dist/app/cli/init.js

@@ -1,11 +1,11 @@
 /**
- * cotutor init <slug>:建 ~/cotutor/<slug>/ 骨架。语义是**幂等补缺**——已有的文件与目录一律不动,缺什么补什么。
+ * cotutor init <slug>:建 ~/cotutor/<slug>/ 骨架,vault 建在旁边的 ~/cotutor/<slug>-vault/(--vault 另指;2026-11-09 起两边分开)。语义是**幂等补缺**——已有的文件与目录一律不动,缺什么补什么。
  * 三条边界(沿 drawtell init):政策文件只在缺失时写模板;用户配置只在还没指定 workspace 时补;不动 git。
  * 老师文件**拷贝**进 agents/<name>.md:拷进来就是家长的,想改就改;出厂 hash 记 .cotutor/shipped.json,
- * cotutor upgrade 据此换新或报 diff。老布局(.claude/agents、.claude/skills)先原样挪到新位置(migrate.ts 的 migrateLayout)。
+ * cotutor refresh 据此换新或报 diff。老布局(.claude/agents、.claude/skills)先原样挪到新位置(migrate.ts 的 migrateLayout)。
  */
 import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
-import { dirname, join, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 import { DIRS, GITIGNORE, LEDGER_FILES, REFERENCE_README, configTemplate, profileTemplate, shippedAgents, writeSchemaFile } from "./skeleton.js";
 import { installTutors, readManifest, writeManifest } from "./tutors.js";
 import { DEFAULT_GRADE, LEGACY_GRADE, requireGradePack } from "./grades.js";
@@ -16,10 +16,39 @@ import { migrateLayout } from "./migrate.js";
 import { choiceNote, choosePort, knownPorts } from "./port.js";
 import { installThemes } from "./themes.js";
 import { scanVault } from "../../memory/vault.js";
-import { CONFIG_FILE, ConfigError, UsageError, HOME_ROOT, USER_CONFIG, expandPath, loadWorkspace, parseConfig, readJson, redactHome } from "../workspace.js";
+import { CONFIG_FILE, ConfigError, UsageError, HOME_ROOT, USER_CONFIG, defaultVaultOf, expandPath, homePath, isInside, knownWorkspaces, loadWorkspace, parseConfig, readJson, redactHome, vaultSeparate } from "../workspace.js";
 async function exists(p) {
     return (await stat(p).catch(() => null)) !== null;
 }
+/** 新建时 vault 能不能放那:和 workspace 谁也不在谁里面,不是别的孩子的 workspace,不和别的孩子共用(一孩一 vault)。报错里 workspace 说「cotutor 文件夹」、vault 说「笔记文件夹」(docs/词表.md) */
+async function checkVaultPlace(root, vault) {
+    if (isInside(vault, root))
+        throw new UsageError(`笔记文件夹(vault)不能放在孩子的 cotutor 文件夹里(${redactHome(vault)}):笔记是家长的,cotutor 文件夹是程序的运行记录,两边分开放。换个 --vault,缺省是旁边的 ${basename(defaultVaultOf(root))}`);
+    if (isInside(root, vault))
+        throw new UsageError(`孩子的 cotutor 文件夹不能放在笔记文件夹(vault)里面(${redactHome(root)} 在 ${redactHome(vault)} 里):两边分开放,换个 --dir 或 --vault`);
+    const st = await stat(vault).catch(() => null);
+    if (st && !st.isDirectory())
+        throw new UsageError(`笔记文件夹(vault)要是一个目录,${redactHome(vault)} 是文件;换个 --vault`);
+    if (await exists(join(vault, CONFIG_FILE)))
+        throw new UsageError(`${redactHome(vault)} 是一个孩子的 cotutor 文件夹(有 ${CONFIG_FILE}),不能当笔记文件夹;换个 --vault`);
+    for (const other of knownWorkspaces()) {
+        if (other === root)
+            continue;
+        if (isInside(vault, other) || isInside(other, vault))
+            throw new UsageError(`${redactHome(vault)} 和 ${redactHome(other)}(别的孩子的 cotutor 文件夹)叠在一起了,不能当笔记文件夹;换个 --vault`);
+        let theirs;
+        try {
+            theirs = loadWorkspace(other).paths.vault;
+        }
+        catch {
+            continue; // 那边配置坏了,doctor 去报
+        }
+        if (isInside(root, theirs))
+            throw new UsageError(`${redactHome(root)} 在 ${redactHome(other)} 的笔记文件夹里,不能在这里建 cotutor 文件夹;换个短名或 --dir`);
+        if (isInside(vault, theirs) || isInside(theirs, vault))
+            throw new UsageError(`${redactHome(vault)} 和 ${redactHome(other)} 的笔记文件夹(${redactHome(theirs)})重了:一个孩子一个笔记文件夹,换个 --vault`);
+    }
+}
 export async function initWorkspace(opts) {
     const root = opts.dir ? expandPath(opts.dir, resolve(process.cwd())) : join(HOME_ROOT, opts.slug);
     const steps = [];
@@ -33,6 +62,18 @@ export async function initWorkspace(opts) {
     if (installed !== undefined && installed !== grade)
         throw new UsageError(`已安装 ${installed} 年级包,init 不切换年级`);
     const agents = await shippedAgents(pack.agentsDir);
+    // vault 只在新建 cotutor.json 时定(写进 paths.vault),以后 init 不改向;已有的再给 --vault,对不上就报错,不悄悄换
+    const vaultArg = opts.vault ? resolve(expandPath(opts.vault, resolve(process.cwd()))) : undefined; // resolve 去掉末尾的 /,好比较
+    let newVault;
+    if (!existing) {
+        newVault = vaultArg ?? defaultVaultOf(root);
+        await checkVaultPlace(root, newVault);
+    }
+    else if (vaultArg) {
+        const now = loadWorkspace(root).paths.vault;
+        if (resolve(now) !== vaultArg)
+            throw new UsageError(`已有 ${CONFIG_FILE},笔记文件夹(vault)在 ${redactHome(now)};init 只补缺,不换笔记文件夹。要换先把里面的笔记挪过去,再改 ${CONFIG_FILE} 的 paths.vault`);
+    }
     const rootExisted = await exists(root);
     if (!rootExisted)
         await mkdir(root, { recursive: true });
@@ -57,7 +98,7 @@ export async function initWorkspace(opts) {
     else {
         // 端口只在这里选一次,写进文件以后不变(port.ts);--port 给了就听它的
         const chosen = opts.port === undefined ? await choosePort(knownPorts()) : null;
-        await writeFile(config, configTemplate({ slug: opts.slug, name: opts.name, port: opts.port ?? chosen?.port, tutors: agents }));
+        await writeFile(config, configTemplate({ slug: opts.slug, name: opts.name, port: opts.port ?? chosen?.port, vault: newVault && homePath(newVault), tutors: agents }));
         steps.push({ item: CONFIG_FILE, action: 'created', ...(chosen ? { note: choiceNote(chosen) } : {}) });
     }
     // 老师按 cotutor.json 里有谁走(家长自己加的也补目录与链);配置坏了就只管出厂的,doctor 去报
@@ -93,8 +134,18 @@ export async function initWorkspace(opts) {
     }
     // vault 侧(《obsidian仓库设计.md》§2):只补档案与参考 README,缺了才写;档案按 cotutor: profile 找(2026-09-17),vault 里已有一篇就不补;
     // 入口文件(每科每学期一篇)不自动建,doctor 提醒;日记由记账现建,计划家长自己写
+    let vaultAt = null;
     try {
         const ws = loadWorkspace(root);
+        vaultAt = ws.paths.vault;
+        if (!vaultSeparate(root, vaultAt))
+            steps.push({ item: 'vault', action: 'kept', note: '笔记文件夹(vault)在 cotutor 文件夹里(旧版 init 的布局),照旧能用;要分开看 cotutor doctor 的 vault.separate' });
+        else {
+            const there = await exists(vaultAt);
+            if (!there)
+                await mkdir(vaultAt, { recursive: true });
+            steps.push({ item: redactHome(vaultAt), action: there ? 'exists' : 'created', note: '笔记文件夹:档案、日记、老师的记忆,都是普通 markdown' });
+        }
         const profile = ws.paths.profile;
         const found = (await scanVault(ws)).notes.find((n) => n.props.cotutor === 'profile');
         if (found)
@@ -152,7 +203,10 @@ export async function initWorkspace(opts) {
     const suggestions = [];
     if (!(await exists(join(root, '.git'))))
         suggestions.push('git init(建议:老师记忆、账本、政策都是不可再生状态,git 是破坏后的兜底)');
-    suggestions.push(`${opts.grade === undefined ? '档案里填 school_start(读一年级的年月,如 2025-09),老师才知道现在是几年级哪个学期;' : ''}想用自己的 Obsidian 库,改 cotutor.json 的 paths.vault`);
+    if (opts.grade === undefined)
+        suggestions.push('档案里填 school_start(读一年级的年月,如 2025-09),老师才知道现在是几年级哪个学期');
+    if (vaultAt && vaultSeparate(root, vaultAt))
+        suggestions.push(`孩子的档案、日记、老师的记忆在笔记文件夹(${redactHome(vaultAt)}):普通 markdown,不用装 Obsidian;想用 Obsidian 看,就把这个目录当库打开`);
     suggestions.push('cotutor service install 装成后台服务(登录后自己起来、关了终端照样跑;在终端里调试用 cotutor serve),第一次装会打开家长端(以后 cotutor open),在「首页」填百炼的按量 API Key 与业务空间 ID(老师的嘴和脑都用它;没填孩子端只出「老师们还没到」)');
     suggestions.push('在平板、手机上用:cotutor cert 签证书(要 mkcert),根证书装到设备上并打开信任,iPad / iPhone 的步骤见 README 里的《iPad 与 iPhone》');
     suggestions.push('可选:点读、单词卡的配音用百炼(和老师的嘴同一把 key),到家长端首页点老师的「样子与声音」挑声音;cotutor pin 给家长端与工作台加锁');

package/dist/app/cli/main.js

@@ -11,10 +11,11 @@ import { basename, join } from 'node:path';
 import { doctorWorkspace } from "./doctor.js";
 import { initWorkspace } from "./init.js";
 import { gradePacks } from "./grades.js";
+import { guideText } from "./guide.js";
 import { makeCert } from "./cert.js";
 import { PIN_RE, USER_PIN_FILE, clearPin, readPin, setPin } from "../http/access.js";
-import { addTutorFile, upgradeTutors } from "./tutors.js";
-import { activityRunFor, checkActivities, upgradeActivities } from "./activities.js";
+import { addTutorFile, restoreTutor, upgradeTutors } from "./tutors.js";
+import { activityRunFor, checkActivities, restoreActivity, upgradeActivities } from "./activities.js";
 import { configGapsOf, migrateLayout, upgradeConfig } from "./migrate.js";
 import { linkClaudeSkills, upgradeSkills } from "./skills.js";
 import { addTheme, upgradeThemes } from "./themes.js";
@@ -32,7 +33,8 @@ import { startUpdateChecks } from "../machine/update.js";
 import { isNewer, upgradeSteps } from "../../shared/upgrade.js";
 import { serveMock } from "../mock/mock.js";
 import { UsageError, loadWorkspace, redactDeep, redactHome, workspaceReport } from "../workspace.js";
-import { USAGE } from "./usage.js";
+import { checkArgs, commandHelp, topHelp, unknownCommand } from "./usage.js";
+import { VALUED_FLAGS, commandSpec } from "./commands.js";
 import { PHOTO_MAX_BYTES, createContext } from "../http/app.js";
 import { MESSAGE_FROM } from "../../schema/index.js";
 import { formatEvent, laneFilter, parseEvents } from "../../runtime/journal/events.js";
@@ -47,6 +49,9 @@ function version() {
 function interactive(json) {
     return !json && Boolean(process.stdin.isTTY && process.stdout.isTTY);
 }
+/** 参数写错了(不是运行时的状况):报错时补一句去看这条命令的帮助 */
+class ArgError extends UsageError {
+}
 function parseArgs(argv, valued) {
     const flags = {};
     const positionals = [];
@@ -57,13 +62,13 @@ function parseArgs(argv, valued) {
             const key = a.slice(2);
             if (valued.includes(key)) {
                 const next = argv[i + 1];
-                // --force 的值可省:upgrade --force <老师>,home publish --force
+                // --force 的值可省:upgrade --force <老师>(旧名),home publish --force
                 if ((next === undefined || next.startsWith('--')) && key === 'force') {
                     flags[key] = true;
                     continue;
                 }
                 if (next === undefined || next.startsWith('--'))
-                    throw new UsageError(`选项 --${key} 需要一个值。\n${USAGE}`);
+                    throw new ArgError(`选项 --${key} 需要一个值`);
                 flags[key] = next;
                 i++;
             }
@@ -103,12 +108,12 @@ async function backupBeforeUpgrade(root) {
         return `! 这次没备份成:${err instanceof Error ? err.message : String(err)}`;
     }
 }
-/** 不用 workspace 的命令:--sandbox 对它们没有意义 */
-const NO_WORKSPACE = ['grades', 'init', 'mock', 'pin', 'cert', 'tray', 'update'];
 export async function main(argv) {
     let json = false;
+    let helpFor;
     try {
-        const { cmd, positionals, flags } = parseArgs(argv, ['workspace', 'dir', 'name', 'grade', 'port', 'from', 'runtime', 'force', 'display', 'subject', 'avatar', 'description', 'scenario', 'delay', 'lane', 'job', 'date', 'thread', 'at', 'photo', 'activity', 'param', 'runs', 'only', 'kid-model', 'pin', 'out', 'bundles', 'step', 'voice', 'tutor', 'instruction', 'log-dir', 'lines']);
+        const { cmd, positionals, flags } = parseArgs(argv, VALUED_FLAGS);
+        helpFor = cmd;
         json = flags.json === true;
         let workspace = typeof flags.workspace === 'string' ? flags.workspace : undefined;
         // --version / --help 是旗标不是命令,parseArgs 把它们收进 flags,cmd 拿不到,所以在 switch 前处理
@@ -116,18 +121,32 @@ export async function main(argv) {
             process.stdout.write(`${version()}\n`);
             return;
         }
-        if (flags.help === true || cmd === undefined || cmd === '-h') {
-            process.stdout.write(USAGE);
+        // 帮助:裸跑与 --help 是顶层(--all 连开发与调试的),cotutor <命令> --help 与 cotutor help <命令> 是那条命令的
+        if (cmd === 'help' && positionals[0] && commandSpec(positionals[0])) {
+            process.stdout.write(commandHelp(positionals[0]));
+            return;
+        }
+        if (flags.help === true || cmd === undefined || cmd === '-h' || cmd === 'help') {
+            process.stdout.write(cmd && commandSpec(cmd) ? commandHelp(cmd) : topHelp({ all: flags.all === true }));
             return;
         }
+        // 照命令表先查一遍:打错的旗标、用错子命令的旗标、多余的参数都报错,不悄悄忽略
+        const spec = commandSpec(cmd);
+        if (!spec) {
+            helpFor = undefined;
+            throw new ArgError(unknownCommand(cmd));
+        }
+        const wrong = checkArgs(spec, positionals, flags);
+        if (wrong)
+            throw new ArgError(wrong);
         // --sandbox:要 workspace 的命令都换到它的试用副本(src/app/cli/sandbox.ts),下面照常把它当 --workspace
         if (flags.fresh === true && flags.sandbox !== true)
             throw new UsageError('--fresh 只跟 --sandbox 一起用:cotutor serve --sandbox --fresh 重新分出试用 workspace');
         if (flags.sandbox === true) {
-            if (NO_WORKSPACE.includes(cmd))
-                throw new UsageError(`${cmd} 不用 workspace,--sandbox 没有意义`);
             if (cmd === 'service')
                 throw new UsageError('试用 workspace 不装后台服务:试的时候 cotutor serve --sandbox 在前台跑');
+            if (!spec.sandbox)
+                throw new UsageError(`${cmd} 不用 workspace,--sandbox 没有意义`);
             const sb = await openSandbox(workspace, { fresh: flags.fresh === true });
             workspace = sb.root;
             if (!json) {
@@ -137,6 +156,10 @@ export async function main(argv) {
             }
         }
         switch (cmd) {
+            case 'guide': {
+                process.stdout.write(guideText(version()));
+                return;
+            }
             case 'grades': {
                 const packs = (await gradePacks()).map(({ grade }) => ({ grade }));
                 process.stdout.write(json ? `${JSON.stringify(packs, null, 2)}\n` : `可安装的教学包:${packs.map((p) => `${p.grade} 年级`).join('、') || '无'}\n`);
@@ -145,13 +168,13 @@ export async function main(argv) {
             case 'init': {
                 const slug = positionals[0];
                 if (!slug || !/^[a-z0-9][a-z0-9-]*$/.test(slug))
-                    throw new UsageError(`init 需要一个 slug(小写字母数字连字符,是短名不是真名),如 cotutor init ming。\n${USAGE}`);
+                    throw new ArgError(`init 需要一个 slug(小写字母数字连字符,是短名不是真名),如 cotutor init ming`);
                 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 的整数');
                 if (flags.grade !== undefined && (typeof flags.grade !== 'string' || !/^[1-6]$/.test(flags.grade)))
                     throw new UsageError('--grade 要是 1–6 的整数,如 --grade 2');
-                const r = await initWorkspace({ slug, grade: flags.grade === undefined ? undefined : Number(flags.grade), dir: typeof flags.dir === 'string' ? flags.dir : undefined, name: typeof flags.name === 'string' ? flags.name : undefined, port });
+                const r = await initWorkspace({ slug, grade: flags.grade === undefined ? undefined : Number(flags.grade), dir: typeof flags.dir === 'string' ? flags.dir : undefined, vault: typeof flags.vault === 'string' ? flags.vault : undefined, name: typeof flags.name === 'string' ? flags.name : undefined, port });
                 if (json)
                     process.stdout.write(`${JSON.stringify(redactDeep(r), null, 2)}\n`);
                 else {
@@ -179,9 +202,13 @@ export async function main(argv) {
                 const [sub, name] = positionals;
                 if (!sub) {
                     const b = await backup.makeBackup(target, { why: 'manual', version: BUILD.version });
+                    if (json) {
+                        process.stdout.write(`${JSON.stringify(redactDeep({ ok: true, backup: b, dir: backup.backupsOf(ws.root), vault: b.vault ?? null }), null, 2)}\n`);
+                        return;
+                    }
                     process.stdout.write(`备份好了:${backup.describeBackup(b)}\n  在 ${redactHome(backup.backupsOf(ws.root))}\n  不含录音(wav)和能重新生成的文件${b.audioSkipped ? `,这次跳过 ${b.audioSkipped} 个录音` : ''}\n`);
                     if (b.vault === 'unreadable')
-                        process.stdout.write(`! vault 读不了(${redactHome(ws.paths.vault)}),这份里没有它\n`);
+                        process.stdout.write(`! 笔记文件夹(vault)读不了(${redactHome(ws.paths.vault)}),这份里没有它\n`);
                     return;
                 }
                 if (sub === 'list') {
@@ -197,11 +224,17 @@ export async function main(argv) {
                     return;
                 }
                 if (sub !== 'restore' || !name)
-                    throw new UsageError(`cotutor backup [list | restore <名字> [--yes]]\n${USAGE}`);
+                    throw new ArgError('backup restore 要备份的名字,如 cotutor backup restore <名字> --yes(cotutor backup list 看有哪些)');
                 if (!(await backup.listBackups(ws.root)).some((b) => b.name === name))
                     throw new UsageError(`没有这份备份:${name}(cotutor backup list 看有哪些)`);
                 if (flags.yes !== true) {
-                    process.stdout.write(`会把孩子的文件夹恢复成 ${name} 那时的样子:备份里有的文件都覆盖回去,之后新多出来的不删。\n恢复前会先把现在的样子也备份一份,恢复错了还能回来。服务会停一下。录音不在备份里,不受影响。\n确定的话加 --yes\n`);
+                    // 不加 --yes 只说会做什么,以 1 退:agent 拿到 needsYes 也不能自己补,要家长明确说要恢复
+                    if (json) {
+                        process.stdout.write(`${JSON.stringify({ ok: false, needsYes: true, backup: name, would: '备份里有的文件覆盖回去,之后新多出来的不删;先把现在的也备一份;服务停一下;录音不受影响' }, null, 2)}\n`);
+                        process.exitCode = 1;
+                        return;
+                    }
+                    process.stdout.write(`会把孩子的 cotutor 文件夹恢复成 ${name} 那时的样子:备份里有的文件都覆盖回去,之后新多出来的不删。\n恢复前会先把现在的样子也备份一份,恢复错了还能回来。服务会停一下。录音不在备份里,不受影响。\n确定的话加 --yes\n`);
                     process.exitCode = 1;
                     return;
                 }
@@ -216,13 +249,18 @@ export async function main(argv) {
                 if (service && health)
                     await controlService(host, ws.root, 'stop');
                 const r = await backup.restoreBackup(target, name, { version: BUILD.version });
+                const restart = Boolean(service && health);
+                if (restart)
+                    await controlService(host, ws.root, 'start');
+                if (json) {
+                    process.stdout.write(`${JSON.stringify(redactDeep({ ok: true, backup: name, files: r.files, safety: r.safety, vaultCopy: r.vaultCopy, restarted: restart }), null, 2)}\n`);
+                    return;
+                }
                 process.stdout.write(`恢复好了:${r.files} 个文件。恢复前的样子留在 ${r.safety}\n`);
                 if (r.vaultCopy)
-                    process.stdout.write(`外面的 vault 没动;要拿回来,那一份的 md 在 ${redactHome(r.vaultCopy)}\n`);
-                if (service && health) {
-                    await controlService(host, ws.root, 'start');
+                    process.stdout.write(`笔记文件夹(vault)没动;要拿回来,那一份的 md 在 ${redactHome(r.vaultCopy)}\n`);
+                if (restart)
                     process.stdout.write('服务重起了\n');
-                }
                 return;
             }
             case 'doctor': {
@@ -331,7 +369,7 @@ export async function main(argv) {
                 // 菜单栏 / 任务栏图标(tray.ts);tray run 由 bin/cotutor.js 直接走轻入口,不到这里
                 const sub = positionals[0];
                 if (sub !== 'on' && sub !== 'off' && sub !== 'status')
-                    throw new UsageError(`tray 后面跟 on / off / status 之一。\n${USAGE}`);
+                    throw new ArgError(`tray 后面跟 on / off / status 之一`);
                 const host = realHost();
                 if (!traySupported(host.platform))
                     throw new UsageError(`${host.platform} 上没做托盘图标(GNOME 缺省不显示托盘):cotutor service status 看服务状态`);
@@ -378,7 +416,7 @@ export async function main(argv) {
                 }
                 const SUBS = ['install', 'uninstall', 'start', 'stop', 'restart', 'status', 'logs'];
                 if (!sub || !SUBS.includes(sub))
-                    throw new UsageError(`service 后面跟 ${SUBS.join(' / ')} 之一。\n${USAGE}`);
+                    throw new ArgError(`service 后面跟 ${SUBS.join(' / ')} 之一`);
                 const host = realHost();
                 const platform = servicePlatform(host.platform);
                 const ws = loadWorkspace(workspace);
@@ -624,7 +662,7 @@ export async function main(argv) {
                 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}`);
+                    throw new ArgError(`add 需要老师名和 --display 显示名,如 cotutor add science-tutor --display 科学老师 --subject 科学 --avatar 🔬`);
                 const ws = loadWorkspace(workspace);
                 if (ws.config.tutors[name])
                     throw new UsageError(`cotutor.json 里已经有 ${name} 了;要改人设去老师团页或直接改文件`);
@@ -642,7 +680,7 @@ export async function main(argv) {
             case 'add-theme': {
                 const name = positionals[0];
                 if (!name)
-                    throw new UsageError(`add-theme 需要主题名,如 cotutor add-theme dark。\n${USAGE}`);
+                    throw new ArgError(`add-theme 需要主题名,如 cotutor add-theme dark`);
                 const { root } = resolveRoot(workspace);
                 const r = await addTheme(root, name, typeof flags.from === 'string' ? flags.from : 'default');
                 if (json)
@@ -661,9 +699,32 @@ export async function main(argv) {
                 } }), { anyway: flags.anyway === true });
                 return;
             }
-            case 'upgrade': {
+            case 'reset': {
+                // 只把点名的出厂老师 / activity 换回出厂那份(工作台「恢复出厂」同一条路),别的不碰;现在那份存 .bak
+                if (!positionals.length)
+                    throw new ArgError('reset 要说换回哪几份,如 cotutor reset math-tutor 或 cotutor reset chinese-tutor/你说我画');
+                const { root } = resolveRoot(workspace);
+                const said = await backupBeforeUpgrade(root);
+                if (said && !json)
+                    process.stdout.write(`${said}\n`);
+                const done = [];
+                for (const name of positionals) {
+                    const [tutor, activity] = name.split('/');
+                    const r = activity ? await restoreActivity(root, tutor, activity) : await restoreTutor(root, tutor);
+                    done.push({ name, bak: r.bak });
+                }
+                if (json)
+                    process.stdout.write(`${JSON.stringify(redactDeep({ ok: true, reset: done }), null, 2)}\n`);
+                else
+                    for (const d of done)
+                        process.stdout.write(`✓ ${d.name} 换回出厂的${d.bak ? `;你那份存在 ${redactHome(d.bak)}` : '(本来就和出厂的一样)'}\n`);
+                return;
+            }
+            // upgrade 是 refresh 的旧名:0.4.x 的 cotutor update 换完程序会用新程序跑 upgrade --workspace <孩子>,一直要认;--force 的活现在归 reset
+            case 'upgrade':
+            case 'refresh': {
                 if (flags.grade !== undefined)
-                    throw new UsageError('upgrade 只更新已安装的教学包,不能用 --grade 切换年级');
+                    throw new UsageError(`${cmd} 只更新已安装的教学包,不能用 --grade 切换年级`);
                 const { root } = resolveRoot(workspace);
                 // 升级前留一份:新代码弄坏了能回来。备份不成不拦升级,说一声。--dry-run 不动文件,不用
                 if (flags['dry-run'] !== true) {
@@ -685,7 +746,7 @@ export async function main(argv) {
                         for (const st of r.installed)
                             process.stdout.write(`✓ ${st.item.padEnd(24)} ${st.note ?? '建好了'}\n`);
                         process.stdout.write(dryRun
-                            ? `\n${r.gaps.length} 项要改,还没动文件:cotutor upgrade --config 真改(只加缺的、删不再用的出厂段,你改过的值不动)\n`
+                            ? `\n${r.gaps.length} 项要改,还没动文件:cotutor refresh --config 真改(只加缺的、删不再用的出厂段,你改过的值不动)\n`
                             : `\n改了 ${r.gaps.length} 项到 ${redactHome(r.file)};服务在跑的话不用重启(改了就热重载)。\n`);
                     }
                     return;
@@ -715,7 +776,7 @@ export async function main(argv) {
                     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`);
+                            process.stdout.write(`    你的 vs 新版(- 你的 / + 新版),想用新版:cotutor reset ${s.name}\n`);
                             for (const l of s.diff.slice(0, 40))
                                 process.stdout.write(`    ${l}\n`);
                             if (s.diff.length > 40)
@@ -725,7 +786,7 @@ export async function main(argv) {
                     for (const s of activitySteps) {
                         process.stdout.write(`${s.action === 'kept-custom' ? '!' : '✓'} activity ${s.key.padEnd(18)} ${word[s.action]}${s.from ? `(原来叫「${s.from}」)` : ''}${s.basedOn && s.action !== 'latest' ? `(基于 ${s.basedOn})` : ''}\n`);
                         if (s.diff?.length) {
-                            process.stdout.write(`    你的 vs 新版(- 你的 / + 新版),想用新版:cotutor upgrade --force ${s.key}\n`);
+                            process.stdout.write(`    你的 vs 新版(- 你的 / + 新版),想用新版:cotutor reset ${s.key}\n`);
                             for (const l of s.diff.slice(0, 40))
                                 process.stdout.write(`    ${l}\n`);
                             if (s.diff.length > 40)
@@ -733,19 +794,19 @@ export async function main(argv) {
                         }
                     }
                     if (gaps.length)
-                        process.stdout.write(`! 配置有 ${gaps.length} 项要改(新出厂老师 / 运行时 / 命令模板旗标 / 不再用的段):cotutor upgrade --config --dry-run 先看\n`);
+                        process.stdout.write(`! 配置有 ${gaps.length} 项要改(新出厂老师 / 运行时 / 命令模板旗标 / 不再用的段):cotutor refresh --config --dry-run 先看\n`);
                 }
                 return;
             }
             case 'activity': {
                 const sub = positionals[0];
                 if (sub !== 'check' && sub !== 'eval')
-                    throw new UsageError(`activity 后面跟 check / eval,如 cotutor activity check chinese-tutor 你说我画。\n${USAGE}`);
+                    throw new ArgError(`activity 后面跟 check / eval,如 cotutor activity check chinese-tutor 你说我画`);
                 const ws = loadWorkspace(workspace);
                 const [, tutor, name] = positionals;
                 if (sub === 'eval') {
                     if (!tutor || !name)
-                        throw new UsageError(`activity eval 要老师和名字,如 cotutor activity eval chinese-tutor 你说我画。\n${USAGE}`);
+                        throw new ArgError(`activity eval 要老师和名字,如 cotutor activity eval chinese-tutor 你说我画`);
                     const runs = typeof flags.runs === 'string' ? Number(flags.runs) : 3;
                     if (!Number.isInteger(runs) || runs < 1 || runs > 10)
                         throw new UsageError('--runs 要是 1–10 的整数');
@@ -777,7 +838,7 @@ export async function main(argv) {
                 }
                 const results = await checkActivities(ws.root, ws.config.tutors, { tutor, name });
                 if (!results.length)
-                    throw new UsageError(tutor ? `agents/${tutor}/activities/ 里没有${name ? ` ${name}.md` : ' activity 文件'}` : '这个 workspace 里还没有 activity 文件(cotutor upgrade 补出厂的)');
+                    throw new UsageError(tutor ? `agents/${tutor}/activities/ 里没有${name ? ` ${name}.md` : ' activity 文件'}` : '这个 workspace 里还没有 activity 文件(cotutor refresh 补出厂的)');
                 const fixes = results.reduce((n, r) => n + r.issues.filter((i) => i.level === 'fix').length, 0);
                 if (json)
                     process.stdout.write(`${JSON.stringify(redactDeep({ ok: fixes === 0, activities: results.map((r) => ({ tutor: r.tutor, name: r.name, file: r.file, issues: r.issues, params: r.activity?.params ?? [], state: r.activity?.state ?? [], gates: r.activity?.gates ?? [], tools: r.activity?.tools.map((t) => t.tool) ?? [] })) }), null, 2)}\n`);
@@ -849,7 +910,7 @@ export async function main(argv) {
             case 'pack': {
                 const [tutor, ...rest] = positionals;
                 if (!tutor)
-                    throw new UsageError(`pack 需要老师名,如 cotutor pack math-tutor "讲讲退位"。\n${USAGE}`);
+                    throw new ArgError(`pack 需要老师名,如 cotutor pack math-tutor "讲讲退位"`);
                 const ws = loadWorkspace(workspace);
                 const { packDryRun } = await import("../../runtime/runner.js");
                 const from = typeof flags.from === 'string' ? flags.from : 'kid';
@@ -890,7 +951,7 @@ export async function main(argv) {
             case 'show': {
                 const [tutor, jobArg, dateArg] = positionals;
                 if (!tutor || !jobArg)
-                    throw new UsageError(`show 需要老师名和 job,如 cotutor show math-tutor 1620-1 2026-09-12(日期缺省今天)。\n${USAGE}`);
+                    throw new ArgError(`show 需要老师名和 job,如 cotutor show math-tutor 1620-1 2026-09-12(日期缺省今天)`);
                 const ws = loadWorkspace(workspace);
                 const { rawView } = await import("../http/raw-view.js");
                 const { localDate } = await import("../../shared/time.js");
@@ -929,7 +990,7 @@ export async function main(argv) {
             case 'replay': {
                 const [tutor, jobArg, dateArg] = positionals;
                 if (!tutor || !jobArg)
-                    throw new UsageError(`replay 需要老师名和 job,如 cotutor replay math-tutor 1620-1 2026-09-12(日期缺省今天)。\n${USAGE}`);
+                    throw new ArgError(`replay 需要老师名和 job,如 cotutor replay math-tutor 1620-1 2026-09-12(日期缺省今天)`);
                 const ws = loadWorkspace(workspace);
                 const { compareReplay, formatCompare, startReplay } = await import("../replay.js");
                 const { localDate } = await import("../../shared/time.js");
@@ -950,7 +1011,7 @@ export async function main(argv) {
             case 'compare': {
                 const [tutor, evalJobArg, dateArg] = positionals;
                 if (!tutor)
-                    throw new UsageError(`compare 需要老师名,如 cotutor compare math-tutor 1712-1 2026-09-12。\n${USAGE}`);
+                    throw new ArgError(`compare 需要老师名,如 cotutor compare math-tutor 1712-1 2026-09-12`);
                 const ws = loadWorkspace(workspace);
                 const { compareReplay, formatCompare, listReplays } = await import("../replay.js");
                 const { localDate } = await import("../../shared/time.js");
@@ -978,7 +1039,7 @@ export async function main(argv) {
             case 'trace': {
                 const [tutor, jobArg, dateArg] = positionals;
                 if (!tutor || !jobArg)
-                    throw new UsageError(`trace 需要老师名和 job,如 cotutor trace math-tutor 1620-1 2026-09-12(日期缺省今天)。\n${USAGE}`);
+                    throw new ArgError(`trace 需要老师名和 job,如 cotutor trace math-tutor 1620-1 2026-09-12(日期缺省今天)`);
                 const ws = loadWorkspace(workspace);
                 const { localDate } = await import("../../shared/time.js");
                 const { conversationFiles } = await import("../../schema/index.js");
@@ -1003,7 +1064,7 @@ export async function main(argv) {
                 const [tutor, thread, score] = positionals;
                 const n = Number(score);
                 if (!tutor || !thread || !(n >= 1 && n <= 5 && Number.isInteger(n)))
-                    throw new UsageError(`rate 需要老师名、话题 id 和 1–5 的星,如 cotutor rate math-tutor 1620-1 4。\n${USAGE}`);
+                    throw new ArgError(`rate 需要老师名、话题 id 和 1–5 的星,如 cotutor rate math-tutor 1620-1 4`);
                 const ws = loadWorkspace(workspace);
                 const date = typeof flags.date === 'string' ? flags.date : localDate(new Date());
                 const index = await rateThread(ws, tutor, date, thread, n);
@@ -1016,7 +1077,7 @@ export async function main(argv) {
             case 'bookkeep': {
                 const [tutor] = positionals;
                 if (!tutor)
-                    throw new UsageError(`bookkeep 需要老师名,如 cotutor bookkeep math-tutor。\n${USAGE}`);
+                    throw new ArgError(`bookkeep 需要老师名,如 cotutor bookkeep math-tutor`);
                 const ctx = createContext(loadWorkspace(workspace));
                 const date = typeof flags.date === 'string' ? flags.date : localDate(new Date());
                 const only = typeof flags.thread === 'string' ? [flags.thread] : undefined;
@@ -1047,7 +1108,7 @@ export async function main(argv) {
             case 'home': {
                 const sub = positionals[0];
                 if (sub !== 'check' && sub !== 'publish' && sub !== 'show')
-                    throw new UsageError(`home 后面跟 check / publish / show,如 cotutor home check。\n${USAGE}`);
+                    throw new ArgError(`home 后面跟 check / publish / show,如 cotutor home check`);
                 const ws = loadWorkspace(workspace);
                 const now = new Date();
                 const home = await import("../../runtime/home/store.js");
@@ -1109,7 +1170,7 @@ export async function main(argv) {
                 const activityName = typeof flags.activity === 'string' ? flags.activity : undefined;
                 const text = words.join(' ') || activityName || '';
                 if (!tutor || (!text && !photoFiles.length))
-                    throw new UsageError(`send 需要老师名和消息,如 cotutor send math-tutor "这一步为什么要借位"。\n${USAGE}`);
+                    throw new ArgError(`send 需要老师名和消息,如 cotutor send math-tutor "这一步为什么要借位"`);
                 const from = typeof flags.from === 'string' ? flags.from : 'kid';
                 if (!MESSAGE_FROM.includes(from))
                     throw new UsageError(`--from 只能是 ${MESSAGE_FROM.join(' / ')}`);
@@ -1165,15 +1226,17 @@ export async function main(argv) {
                 return;
             }
             default:
-                throw new UsageError(`未知命令 '${cmd}'。\n${USAGE}`);
+                throw new ArgError(unknownCommand(cmd));
         }
     }
     catch (err) {
         if (err instanceof UsageError) {
+            // 参数写错了:一句话 + 去哪看用法,不再把整篇帮助倒出来
+            const help = err instanceof ArgError ? (helpFor && commandSpec(helpFor) ? `cotutor ${helpFor} --help` : 'cotutor --help') : undefined;
             if (json)
-                process.stdout.write(`${JSON.stringify({ ok: false, error: 'usage', message: err.message })}\n`);
+                process.stdout.write(`${JSON.stringify({ ok: false, error: 'usage', message: err.message, ...(help ? { help } : {}) })}\n`);
             else
-                process.stderr.write(`cotutor: ${err.message}\n`);
+                process.stderr.write(`cotutor: ${err.message}\n${help ? `  用法:${help}\n` : ''}`);
             process.exitCode = 2;
             return;
         }

package/dist/app/cli/migrate.js

@@ -4,7 +4,7 @@
  * cotutor.json 是**政策文件**:init 只在缺失时写模板,已有的那份机器永不改(家长的决定不由机器代做)。
  * 代价是包更新带来的新出厂件不会自己出现在老 workspace 里,而且「没有」的表现是**静默**的——
  * 所以有这一层:把「出厂模板有、你这份没有」算出来(doctor 的 `config.migrate` 点名、家长端设置页顶部提示),
- * `cotutor upgrade --config` 只**补缺**——加缺的键;家长写过的值一个都不动(改小的预算、换掉的 default 运行时全都原样留着)。
+ * `cotutor refresh --config` 只**补缺**——加缺的键;家长写过的值一个都不动(改小的预算、换掉的 default 运行时全都原样留着)。
  * 唯一删的是 RETIRED 里点了名的出厂段(机器写进去、应用已经不读的,如 2026-10-31 的 tts);家长自己加的键不在表里,不碰。
  *
  * 差异是**现算的**:拿家长自己的 slug / name / port 生成一份出厂模板,和她这份逐项比,

package/dist/app/cli/port.js

@@ -7,12 +7,11 @@
  * 旧 workspace 写着什么就是什么;cotutor.json 没写端口的走 DEFAULT_PORT,不跟着这里变。
  */
 import { createConnection, createServer } from 'node:net';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { DEFAULT_PORT } from "../../schema/index.js";
 import { holderScript, parseHolder, parseLsof, portHolder } from "./port-holder.js";
 import { probeHealth } from "./service.js";
-import { CONFIG_FILE, USER_CONFIG, UsageError, expandPath, homeWorkspaces, readJson } from "../workspace.js";
+import { CONFIG_FILE, UsageError, knownWorkspaces, readJson } from "../workspace.js";
 export const PORT_CANDIDATES = [443, ...Array.from({ length: 9 }, (_, i) => 8443 + i * 2)];
 /** sandbox 用哪个端口 */
 export const sandboxPort = (port) => (port === 65535 ? port - 1 : port + 1);
@@ -70,15 +69,8 @@ export function choiceNote(c) {
 }
 /** 这台电脑上别的 workspace 写着的端口(~/cotutor/ 下的,加上用户配置指的那个):还没起的也要让开 */
 export function knownPorts() {
-    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 去报 */ }
     const ports = [];
-    for (const root of roots) {
+    for (const root of knownWorkspaces()) {
         try {
             const raw = readJson(join(root, CONFIG_FILE));
             if (!raw)

package/dist/app/cli/sandbox.js

@@ -5,21 +5,16 @@
  * 已经在 sandbox 里(cwd 在里面、--workspace 指过来)就用它;--fresh 从它记着的真 workspace 重新分,不套娃。
  */
 import { copyFile, cp, mkdir, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
-import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path';
+import { basename, dirname, join, relative } from 'node:path';
 import { PATH_ROLES, ROLE_DEFAULTS, WORKSPACE_ROLES } from "../../schema/index.js";
 import { SANDBOX_DIR, SANDBOX_KEEP_MACHINE, SANDBOX_MARK, SANDBOX_SKIP, SANDBOX_TITLE, SANDBOX_VAULT } from "../../schema/workspace.js";
-import { CONFIG_FILE, UsageError, expandPath, loadWorkspace, parseConfig, readJson, readSandboxMark, redactHome, resolveRoot } from "../workspace.js";
+import { CONFIG_FILE, UsageError, expandPath, isInside as inside, loadWorkspace, parseConfig, readJson, readSandboxMark, redactHome, resolveRoot } from "../workspace.js";
 import { sandboxPort } from "./port.js";
 import { DIRS, LEDGER_FILES } from "./skeleton.js";
 /** vault 侧指在外面也不怕的角色:只读的材料,老师不往里写 */
 const READ_ONLY_ROLES = ['textbooks', 'reference'];
 /** ~/cotutor/ray → ~/cotutor/.sandbox/ray */
 export const sandboxRootOf = (real) => join(dirname(real), SANDBOX_DIR, basename(real));
-/** p 是 dir 本身或在它里面 */
-function inside(p, dir) {
-    const r = relative(dir, p);
-    return r === '' || (r !== '..' && !r.startsWith(`..${sep}`) && !isAbsolute(r));
-}
 async function exists(p) {
     return stat(p).then(() => true, () => false);
 }

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

@@ -82,7 +82,10 @@ export interface ServiceSpec {
 export declare const xml: (s: string) => string;
 /** macOS 的 LaunchAgent */
 export declare function launchdPlist(s: ServiceSpec): string;
-/** Linux 的 systemd 用户服务 */
+/**
+ * Linux 的 systemd 用户服务。WorkingDirectory= 不认引号(只有 ExecStart=、Environment= 这种列表才认),
+ * 加了引号 systemd 当它是相对路径,整个服务起不来(2026-11-09 在 Ubuntu 22.04 / systemd 249 上撞到);它只要 % 写两个
+ */
 export declare function systemdUnit(s: ServiceSpec): string;
 /** 从服务文件里读回跑的参数(找它是哪个 workspace 的) */
 export declare function serviceArgs(text: string): string[];

package/dist/app/cli/service.js

@@ -218,7 +218,10 @@ ${s.args.map((a) => `    ${str(a)}`).join('\n')}
 }
 /** systemd 的一个参数:双引号括起来,反斜杠与引号转义,% 写两个 */
 const sd = (v) => `"${v.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%')}"`;
-/** Linux 的 systemd 用户服务 */
+/**
+ * Linux 的 systemd 用户服务。WorkingDirectory= 不认引号(只有 ExecStart=、Environment= 这种列表才认),
+ * 加了引号 systemd 当它是相对路径,整个服务起不来(2026-11-09 在 Ubuntu 22.04 / systemd 249 上撞到);它只要 % 写两个
+ */
 export function systemdUnit(s) {
     return `# cotutor service install 写的;改了会被下次 install 盖掉。卸掉:cotutor service uninstall --workspace ${s.root}
 [Unit]
@@ -227,7 +230,7 @@ After=network-online.target
 
 [Service]
 ExecStart=${s.args.map(sd).join(' ')}
-WorkingDirectory=${sd(s.root)}
+WorkingDirectory=${s.root.replaceAll('%', '%%')}
 Environment=${sd(`PATH=${s.path}`)}
 Environment=${sd(`COTUTOR_SERVICE=${s.label}`)}
 Restart=on-failure