cotutor 0.4.4 → 0.4.5

package/dist/app/cli/shipped.js

@@ -42,6 +42,6 @@ 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 writeFile(tmp, `${JSON.stringify({ ...m, _note: '出厂时老师文件的 hash,cotutor refresh 据此分辨「没改过」与「改过」;机器写,不用手改' }, null, 2)}\n`);
     await rename(tmp, file);
 }

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

@@ -30,6 +30,8 @@ export interface ConfigTemplateInput {
     slug: string;
     name?: string;
     port?: number;
+    /** 写进 paths.vault 的(~/… 或绝对路径);不给就不写,vault 落在 workspace 根(旧版的布局) */
+    vault?: string;
     tutors: ShippedAgent[];
 }
 /** cotutor.json 模板:只在文件不存在时写入;政策文件永不自动重建或覆盖(家长的决定不由机器代做)。 */

package/dist/app/cli/skeleton.js

@@ -4,7 +4,8 @@
  *   cotutor.json / .cotutor/shipped.json(出厂 hash)/ .agents/skills/(技能;.claude/skills 是指过去的链,给 Claude Code)
  *   agents/<name>.md(老师文件,拷自本包 grades/grade-<n>/agents/,是家长的;所有运行时都从这里拿老师正文)与 agents/<name>/(老师的家 = 会话 cwd)
  *   ledger/(产物账本)/ conversations/(对话索引与转录)
- * vault 侧(《obsidian仓库设计.md》):档案 / 课程表 / 日记 / 教材 / 计划 / 参考,init 只建档案与参考 README(缺了才写)
+ * vault 侧(《obsidian仓库设计.md》):档案 / 课程表 / 日记 / 教材 / 计划 / 参考,init 只建档案与参考 README(缺了才写);
+ *   vault 不在 workspace 里,缺省是旁边的 <目录名>-vault/(2026-11-09;旧版没写 paths.vault 的落在 workspace 根)
  */
 import { readFileSync } from 'node:fs';
 import { readFile, readdir } from 'node:fs/promises';
@@ -140,7 +141,7 @@ export function configTemplate(input) {
         title: input.name ? `${input.name}的老师们` : 'cotutor',
         kid: { slug: input.slug, ...(input.name ? { name: input.name } : {}) },
         server: { port: input.port ?? DEFAULT_PORT },
-        paths: {},
+        paths: input.vault ? { vault: input.vault } : {},
         policyDefaults: {},
         tutors,
         // 缺省 api:应用直连百炼,家长端「首页」填一次按量 key + 业务空间 id 就能用(2026-10-31);2026-11-02 起只有 API 运行时

package/dist/app/cli/skills.js

@@ -124,7 +124,7 @@ export async function installSkills(root) {
             steps.push({ item, action: 'exists', note: s.state === 'latest' ? '已按本包刷新(机器件)' : '已按本包换新(机器件,不认改动)' });
         }
         else
-            steps.push({ item, action: 'exists', note: s.state === 'custom' ? `自定义(基于 ${s.basedOn})` : s.state === 'upgradable' ? '可升级(cotutor upgrade)' : s.state === 'untracked' ? '已有(没有出厂记录);升级时当自定义对待' : undefined });
+            steps.push({ item, action: 'exists', note: s.state === 'custom' ? `自定义(基于 ${s.basedOn})` : s.state === 'upgradable' ? '可升级(cotutor refresh)' : s.state === 'untracked' ? '已有(没有出厂记录);升级时当自定义对待' : undefined });
     }
     if (touched)
         await writeManifest(root, { ...manifest, version: PACKAGE_VERSION });
@@ -187,7 +187,7 @@ export async function linkClaudeSkills(root) {
         return key(resolve(dirname(link), to.replace(/^\\\\\?\\/, ''))) === key(resolve(root, SKILLS_DIR)) ? { item, action: 'exists' } : { item, action: 'kept', note: `已经是指向 ${to} 的链,没动` };
     }
     if (st)
-        return { item, action: 'kept', note: `${CLAUDE_SKILLS_LINK} 是实体目录,没建链:把里面的技能挪进 ${SKILLS_DIR}/、删掉它,再跑 cotutor upgrade` };
+        return { item, action: 'kept', note: `${CLAUDE_SKILLS_LINK} 是实体目录,没建链:把里面的技能挪进 ${SKILLS_DIR}/、删掉它,再跑 cotutor refresh` };
     await mkdir(dirname(link), { recursive: true });
     try {
         await symlink(target, link, process.platform === 'win32' ? 'junction' : undefined);

package/dist/app/cli/themes.js

@@ -1,7 +1,7 @@
 /**
  * 主题(themes/<name>/theme.json + kid.css):孩子端板书的样子。样子的真相在主题里,不在卡的协议里。
  * 出厂主题 default 在包根 themes/default/;init **拷贝**进 workspace 的 themes/default/(拷进来就是家长的,改了刷新就有),
- * 目录 hash 记 .cotutor/shipped.json 的 themes,与老师文件 / skill 同一套:没改过的随 cotutor upgrade 换新,改过的报 diff 保留。
+ * 目录 hash 记 .cotutor/shipped.json 的 themes,与老师文件 / skill 同一套:没改过的随 cotutor refresh 换新,改过的报 diff 保留。
  * 自家的主题(cotutor add-theme <name> 拷一份 default 来改,或直接建目录)永远 untracked,upgrade 不碰。
  */
 import { cp, lstat, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
@@ -103,7 +103,7 @@ export async function installThemes(root) {
             steps.push({ item, action: 'created', note: '孩子端的主题(theme.json 槽的清单 + kid.css 样式),拷自本包,改了刷新就有' });
         }
         else
-            steps.push({ item, action: 'exists', note: s.state === 'custom' ? `自定义(基于 ${s.basedOn})` : s.state === 'upgradable' ? '可升级(cotutor upgrade)' : s.state === 'untracked' ? '已有(没有出厂记录);升级时当自定义对待' : undefined });
+            steps.push({ item, action: 'exists', note: s.state === 'custom' ? `自定义(基于 ${s.basedOn})` : s.state === 'upgradable' ? '可升级(cotutor refresh)' : s.state === 'untracked' ? '已有(没有出厂记录);升级时当自定义对待' : undefined });
     }
     if (touched)
         await writeManifest(root, { ...manifest, version: PACKAGE_VERSION });

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

@@ -37,6 +37,8 @@ export interface TrayProbe {
     name: string;
     kid: string;
     root: string;
+    /** vault 在哪(cotutor.json 的 paths.vault;没写就是 root):Windows 上读不到 vault 时打开它 */
+    vault: string;
     logDir: string | null;
     port: number;
     health: Health | null;
@@ -142,6 +144,7 @@ export interface TrayDeps {
     inspect(s: InstalledService): Promise<{
         kid: string;
         port: number;
+        vault: string;
     }>;
     probe(port: number): Promise<Health | null>;
     holder(port: number): Promise<string | null>;
@@ -188,10 +191,12 @@ export declare function openCommand(platform: NodeJS.Platform, target: string):
 export declare function openTarget(platform: NodeJS.Platform, target: string): void;
 /** 日志:一个文件,过 1 MB 换一次,只留上一份 */
 export declare function trayNote(dir: string): (text: string) => void;
-/** 孩子叫什么、哪个端口:只读这两样,不加载 zod(托盘进程常驻,要轻);读不了就用服务名和缺省端口 */
+/** 孩子叫什么、哪个端口、vault 在哪:只读这三样,不加载 zod(托盘进程常驻,要轻);读不了就用服务名、缺省端口、workspace 根。
+ *  vault 照 workspace.ts 的 resolvePaths 算:paths.vault 相对 workspace 根,没写就是根(旧版的布局) */
 export declare function inspectService(s: InstalledService): Promise<{
     kid: string;
     port: number;
+    vault: string;
 }>;
 /** 真的依赖,给 runTray */
 export declare function realTrayDeps(host: ServiceHost, dir: string, file: string, version: () => string): TrayDeps;

package/dist/app/cli/tray.js

@@ -16,6 +16,7 @@ import { join } from 'node:path';
 import { createInterface } from 'node:readline';
 import { DEFAULT_PORT } from "../../shared/default-port.js";
 import { UsageError } from "../../shared/errors.js";
+import { expandPath } from "../../shared/home.js";
 import { siteUrl } from "../../shared/site-url.js";
 import { isNewer } from "../../shared/upgrade.js";
 import { portHolder } from "./port-holder.js";
@@ -60,7 +61,7 @@ export function issuesOf(p, o) {
     if (h.configError)
         out.push({ text: 'cotutor.json 写坏了:改的没生效', fix: { kind: 'open', target: p.root } });
     if (h.vault === 'denied')
-        out.push(o.platform === 'darwin' ? { text: '读不到 vault:要给 node 开磁盘权限', fix: { kind: 'open', target: MAC_FULL_DISK } } : { text: '读不到 vault:看看这个目录的权限', fix: { kind: 'open', target: p.root } });
+        out.push(o.platform === 'darwin' ? { text: '读不到 vault:要给 node 开磁盘权限', fix: { kind: 'open', target: MAC_FULL_DISK } } : { text: '读不到 vault:看看这个目录的权限', fix: { kind: 'open', target: p.vault } });
     else if (h.vault === 'missing')
         out.push({ text: 'vault 不在了:看看 cotutor.json 的 paths.vault', fix: { kind: 'open', target: p.root } });
     if (h.bailian === false)
@@ -371,7 +372,7 @@ export function runTray(d) {
                     }
                     else
                         holders.delete(s.name);
-                    probes.push({ name: s.name, kid: w.kid, root: s.root, logDir: s.logDir, port: w.port, health, holder });
+                    probes.push({ name: s.name, kid: w.kid, root: s.root, vault: w.vault, logDir: s.logDir, port: w.port, health, holder });
                 }
                 const r = model.update(probes, d.now());
                 rows = r.rows;
@@ -501,15 +502,17 @@ export function trayNote(dir) {
         catch { /* 写不了日志不能把图标带倒 */ }
     };
 }
-/** 孩子叫什么、哪个端口:只读这两样,不加载 zod(托盘进程常驻,要轻);读不了就用服务名和缺省端口 */
+/** 孩子叫什么、哪个端口、vault 在哪:只读这三样,不加载 zod(托盘进程常驻,要轻);读不了就用服务名、缺省端口、workspace 根。
+ *  vault 照 workspace.ts 的 resolvePaths 算:paths.vault 相对 workspace 根,没写就是根(旧版的布局) */
 export async function inspectService(s) {
     try {
         const c = JSON.parse(await readFile(join(s.root, 'cotutor.json'), 'utf8'));
         const kid = typeof c.kid?.name === 'string' && c.kid.name ? c.kid.name : typeof c.kid?.slug === 'string' && c.kid.slug ? c.kid.slug : s.name;
-        return { kid, port: typeof c.server?.port === 'number' ? c.server.port : DEFAULT_PORT };
+        const vault = typeof c.paths?.vault === 'string' && c.paths.vault ? expandPath(c.paths.vault, s.root) : s.root;
+        return { kid, port: typeof c.server?.port === 'number' ? c.server.port : DEFAULT_PORT, vault };
     }
     catch {
-        return { kid: s.name, port: DEFAULT_PORT };
+        return { kid: s.name, port: DEFAULT_PORT, vault: s.root };
     }
 }
 /** 真的依赖,给 runTray */

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

@@ -43,7 +43,7 @@ export interface UpgradeStep {
 /** 最小行 diff(LCS),只为让家长看清改了哪几行;不追求 git 那么好 */
 export declare function lineDiff(a: string, b: string): string[];
 /**
- * cotutor upgrade:latest 跳过;upgradable 换新;custom / untracked 只报 diff 并保留(--force <name> 才覆盖,原文留 .bak);缺的补。
+ * cotutor refresh:latest 跳过;upgradable 换新;custom / untracked 只报 diff 并保留(--force <name> 才覆盖,原文留 .bak);缺的补。
  */
 export declare function upgradeTutors(root: string, opts?: {
     force?: string[];
@@ -65,7 +65,7 @@ export declare function removeTutorFile(root: string, name: string): Promise<{
 /** 出厂那份老师文件的原文;不是出厂的 → null */
 export declare function shippedTutorText(name: string, root?: string): Promise<string | null>;
 /**
- * 只把一位出厂老师的文件换回出厂那份(工作台「恢复出厂」,与 upgrade --force <老师> 同一条路,但不碰别的老师):
+ * 只把一位出厂老师的文件换回出厂那份(工作台「恢复出厂」,与 cotutor reset <老师> 同一条路,但不碰别的老师):
  * 现在那份和出厂不一样就先存 .bak。不是出厂的 → UsageError。返回 .bak 的路径(没存就是 null)
  */
 export declare function restoreTutor(root: string, name: string): Promise<{

package/dist/app/cli/tutors.js

@@ -4,7 +4,7 @@
  * 和老师的家 agents/<name>/ 并排,同包里一样(2026-10-30 从 .claude/agents/ 挪来,老 workspace 由 migrate.ts 的 migrateLayout 搬)。
  * 出厂时的内容 hash 记在 .cotutor/shipped.json(机器文件,家长不用管),据此分三种状态:
  *   latest     与本包一致
- *   upgradable 与记录的出厂 hash 一致(没改过,只是包更新了)→ cotutor upgrade 直接换新
+ *   upgradable 与记录的出厂 hash 一致(没改过,只是包更新了)→ cotutor refresh 直接换新
  *   custom     改过 → upgrade 只报 diff,不动
  *   untracked  没有记录(旧workspace、或家长手写的老师)→ 当 custom 对待
  */
@@ -82,7 +82,7 @@ export async function installTutors(root, configured = []) {
             steps.push({ item, action: 'kept', note: '已有(不是出厂件,或没有记录);升级时当自定义对待' });
         }
         else {
-            steps.push({ item, action: 'exists', note: s.state === 'custom' ? `自定义(基于 ${s.basedOn})` : s.state === 'upgradable' ? `可升级(cotutor upgrade)` : undefined });
+            steps.push({ item, action: 'exists', note: s.state === 'custom' ? `自定义(基于 ${s.basedOn})` : s.state === 'upgradable' ? `可升级(cotutor refresh)` : undefined });
         }
     }
     for (const name of configured.filter((n) => !shipped.some((a) => a.name === n))) {
@@ -151,7 +151,7 @@ export function lineDiff(a, b) {
     return out;
 }
 /**
- * cotutor upgrade:latest 跳过;upgradable 换新;custom / untracked 只报 diff 并保留(--force <name> 才覆盖,原文留 .bak);缺的补。
+ * cotutor refresh:latest 跳过;upgradable 换新;custom / untracked 只报 diff 并保留(--force <name> 才覆盖,原文留 .bak);缺的补。
  */
 export async function upgradeTutors(root, opts = {}) {
     const manifest = await readManifest(root);
@@ -229,7 +229,7 @@ export async function shippedTutorText(name, root) {
     return a ? readFile(a.file, 'utf8') : null;
 }
 /**
- * 只把一位出厂老师的文件换回出厂那份(工作台「恢复出厂」,与 upgrade --force <老师> 同一条路,但不碰别的老师):
+ * 只把一位出厂老师的文件换回出厂那份(工作台「恢复出厂」,与 cotutor reset <老师> 同一条路,但不碰别的老师):
  * 现在那份和出厂不一样就先存 .bak。不是出厂的 → UsageError。返回 .bak 的路径(没存就是 null)
  */
 export async function restoreTutor(root, name) {

package/dist/app/cli/update-cmd.js

@@ -21,7 +21,7 @@ const nodeTooOld = (have, min) => {
 const worthSaying = (out) => out.split('\n').map((l) => l.trimEnd()).filter((l) => l.trim() && !/已是最新|已换新/.test(l));
 async function updateOne(d, s, target) {
     let ok = true;
-    const up = await d.cli(['upgrade', '--workspace', s.root]);
+    const up = await d.cli(['refresh', '--workspace', s.root]);
     for (const l of worthSaying(up.out))
         d.print(`  ${l}`);
     if (up.code !== 0) {
@@ -53,14 +53,14 @@ async function updateOne(d, s, target) {
         const checks = JSON.parse(doc.out).checks;
         const migrate = checks.find((c) => c.name === 'config.migrate' && !c.ok);
         if (migrate)
-            d.print(`  ! ${s.kid} 的配置要迁移:${migrate.cmd ?? 'cotutor upgrade --config'}`);
+            d.print(`  ! ${s.kid} 的配置要迁移:${migrate.cmd ?? 'cotutor refresh --config'}`);
     }
     catch { /* 体检读不了不影响升级 */ }
     return ok;
 }
 export async function runUpdate(d, o = {}) {
     if (d.fromRepo) {
-        d.print('这份是从仓库跑的:git pull,再 cotutor upgrade、cotutor service restart。cotutor update 只管 npm 装的。');
+        d.print('这份是从仓库跑的:git pull,再 cotutor refresh、cotutor service restart。cotutor update 只管 npm 装的。');
         return 1;
     }
     const services = await d.services();
@@ -114,7 +114,7 @@ export async function runUpdate(d, o = {}) {
     if (!services.length) {
         const root = d.workspace();
         if (root) {
-            const up = await d.cli(['upgrade', '--workspace', root]);
+            const up = await d.cli(['refresh', '--workspace', root]);
             for (const l of worthSaying(up.out))
                 d.print(`  ${l}`);
             if (up.code !== 0)

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

@@ -1,2 +1,26 @@
-/** 命令用法(cotutor --help;技能 cotutor-analyze 的 references/命令与文件.md 从这里取分析用的那几行,所以放单独文件,别的模块 import 不会跑到 CLI) */
-export declare const USAGE = "\u7528\u6CD5:\n  cotutor init <slug> [--dir <path>] [--name <\u5B69\u5B50\u540D>] [--grade <1-6>] [--port <n>]   \u5EFA ~/cotutor/<slug>/ \u9AA8\u67B6(\u5E42\u7B49\u8865\u7F3A;\u9ED8\u8BA4\u4E8C\u5E74\u7EA7\u6559\u5B66\u5305;\u7AEF\u53E3\u5728\u8FD9\u91CC\u9009\u4E00\u6B21\u5199\u8FDB cotutor.json:443 \u4F18\u5148,\u4E0D\u884C\u5C31 8443\u30018445\u2026,\u4EE5\u540E\u4E0D\u53D8)\n  cotutor grades [--json]                                          \u5217\u51FA\u672C\u5305\u53EF\u5B89\u88C5\u7684\u5E74\u7EA7\u6559\u5B66\u5305\n  cotutor doctor [--workspace <dir>] [--json] [--live] [--fix]                 \u9010\u9879\u4F53\u68C0;--live \u771F\u8FDE\u4E00\u6B21\u767E\u70BC\u5B9E\u65F6\u6A21\u578B\u3001\u771F\u5408\u6210\u4E00\u53E5\u914D\u97F3(\u82B1\u4E00\u5206\u94B1)\u628A API \u5C42\u7684\u5751\u6446\u51FA\u6765(\u771F\u8DD1\u8001\u5E08\u7528 cotutor send);--json \u91CC\u4E0D\u8FC7\u7684\u9879\u5E26 cmd(\u80FD\u76F4\u63A5\u8DD1)\u6216 human(\u8981\u4EBA\u6765);--fix \u628A\u5E26 cmd \u7684\u4E00\u6761\u6761\u4FEE\u6389,\u8981\u4EBA\u6765\u7684\u7559\u7740\n  cotutor report [--workspace <dir>]                                   \u8BCA\u65AD\u4FE1\u606F:\u7248\u672C\u3001\u7CFB\u7EDF\u3001\u670D\u52A1\u3001\u4F53\u68C0\u6CA1\u8FC7\u7684\u3001\u6700\u8FD1\u62A5\u9519\u7684\u539F\u56E0;\u4E0D\u542B\u5B69\u5B50\u7684\u5BF9\u8BDD\u3001\u7167\u7247\u3001\u5F55\u97F3\u3001\u6863\u6848\u548C key,\u540D\u5B57\u548C IP \u5DF2\u62B9\u6389,\u5148\u770B\u518D\u53D1\n  cotutor backup [list | restore <\u540D\u5B57> [--yes]] [--workspace <dir>]   \u5907\u4EFD\u5230 workspace \u65C1\u8FB9\u7684 .backups/:\u4E0D\u542B\u5F55\u97F3;\u670D\u52A1\u5F00\u7740\u65F6\u6BCF\u5929\u4E00\u4EFD(\u7559 14 \u4EFD),cotutor upgrade \u524D\u4E00\u4EFD(\u7559 5 \u4EFD);\u6CA1\u53D8\u7684\u6587\u4EF6\u786C\u94FE\u63A5,\u4E0D\u5360\u7B2C\u4E8C\u4EFD\u5730\u65B9;restore \u5148\u628A\u73B0\u5728\u7684\u4E5F\u5907\u4E00\u4EFD\u518D\u62F7\u56DE\u53BB,\u4E0D\u52A0 --yes \u53EA\u8BF4\u4F1A\u505A\u4EC0\u4E48\n  cotutor update [--anyway]                                            \u5347\u7EA7\u4E00\u6761\u547D\u4EE4\u7BA1\u5230\u5E95:\u95EE npm \u6709\u6CA1\u6709\u65B0\u7248\u672C,\u6362\u7A0B\u5E8F,\u6BCF\u4E2A\u5B69\u5B50\u66F4\u65B0\u51FA\u5382\u6587\u4EF6\u3001\u91CD\u8D77\u670D\u52A1\u548C\u56FE\u6807;\u5B69\u5B50\u5728\u901A\u8BDD\u65F6\u4E0D\u52A8(--anyway \u624D\u52A8),npm \u6CA1\u6210\u670D\u52A1\u4E0D\u52A8\n  cotutor upgrade [--workspace <dir>] [--force <\u8001\u5E08>]...                \u8001\u5E08\u6587\u4EF6\u3001activity \u4E0E skill \u6362\u65B0\u7248:\u6CA1\u6539\u8FC7\u7684\u76F4\u63A5\u6362,\u6539\u8FC7\u7684\u53EA\u62A5 diff(--force <\u8001\u5E08> \u6216 --force <\u8001\u5E08>/<\u540D> \u624D\u8986\u76D6,\u539F\u6587\u7559 .bak)\n  cotutor upgrade --config [--dry-run] [--workspace <dir>]              cotutor.json \u8865\u7F3A:\u65B0\u51FA\u5382\u8001\u5E08 / \u8FD0\u884C\u65F6 / \u547D\u4EE4\u6A21\u677F\u65D7\u6807(\u53EA\u52A0\u7F3A\u7684,\u4F60\u6539\u8FC7\u7684\u503C\u4E0D\u52A8)\n  cotutor add <\u8001\u5E08\u540D> --display <\u663E\u793A\u540D> [--subject <\u5B66\u79D1>] [--avatar <emoji|\u56FE\u7247\u76F8\u5BF9\u8DEF\u5F84>] [--hidden]   \u52A0\u4E00\u4F4D\u81EA\u5BB6\u7684\u8001\u5E08:\u51FA\u6A21\u677F\u6587\u4EF6\u3001\u8FDB cotutor.json\u3001\u5EFA\u76EE\u5F55(\u540D\u5B57\u4EE5 -tutor \u7ED3\u5C3E\u7684\u662F\u8001\u5E08,figshot \u7ED9\u5B83\u505A\u5934\u50CF)\n  cotutor add-theme <\u4E3B\u9898\u540D> [--from <\u4E3B\u9898>] [--workspace <dir>]       \u52A0\u4E00\u4E2A\u81EA\u5BB6\u7684\u4E3B\u9898:\u62F7\u4E00\u4EFD(\u7F3A\u7701\u51FA\u5382\u7684 default)\u5230 themes/<\u4E3B\u9898\u540D>/,\u6539 cotutor.json \u7684 kid.theme \u6362\u8FC7\u53BB\n  cotutor serve [--workspace <dir>] [--port <n>] [--http] [--trace] [--open] [--log-dir <\u76EE\u5F55>]   \u5728\u7EC8\u7AEF\u91CC\u8D77\u670D\u52A1(\u4E00 workspace \u4E00\u8FDB\u7A0B;~/.config/cotutor/certs/ \u6709\u8BC1\u4E66\u5C31\u8D70 HTTPS;--trace \u6BCF\u4E00\u8F6E\u7684\u4E8B\u4EF6\u6309\u9053\u6253\u5370;\u53EA\u6253\u5370\u5BB6\u957F\u7AEF\u9996\u9875\u7684\u5730\u5740,\u5B69\u5B50\u7684\u5E73\u677F\u5728\u90A3\u91CC\u626B\u7801;--open \u987A\u624B\u6253\u5F00,\u65E7\u540D --open-qr \u7167\u6837\u8BA4;--log-dir \u8F93\u51FA\u6309\u5929\u843D\u6587\u4EF6,\u540E\u53F0\u670D\u52A1\u7528;\u5173\u4E86\u7EC8\u7AEF\u5C31\u505C,\u4E00\u76F4\u5F00\u7740\u7528 cotutor service)\n  cotutor open [--workspace <dir>] [--sandbox] [--print] [--json]        \u6253\u5F00\u5BB6\u957F\u7AEF(\u8BFB cotutor.json,\u4E0D\u7528\u8BB0\u7AEF\u53E3);--sandbox \u5F00\u8BD5\u7528\u7684\u90A3\u4E2A(\u7AEF\u53E3\u6C38\u8FDC\u662F\u771F\u7684 +1);--print \u53EA\u6253\u5370\u5730\u5740;\u6CA1\u5728\u8DD1\u5C31\u8BF4\u600E\u4E48\u8D77,\u4EE5 1 \u9000\n  cotutor service install | uninstall | start | stop | restart [--workspace <dir>] [--no-tray] [--no-open]   \u628A serve \u88C5\u6210\u8FD9\u53F0\u7535\u8111\u7684\u540E\u53F0\u670D\u52A1(macOS launchd\u3001Linux systemd \u7528\u6237\u670D\u52A1\u3001Windows \u7528\u6237\u7684\u767B\u5F55\u9879,\u90FD\u4E0D\u8981\u7BA1\u7406\u5458):\u767B\u5F55\u540E\u81EA\u5DF1\u8D77\u6765\u3001\u5D29\u4E86 10 \u79D2\u540E\u518D\u8D77\u3001\u65E5\u5FD7\u6309\u5929\u843D\u6587\u4EF6\u7559 14 \u5929;\u4E00\u4E2A workspace \u4E00\u4E2A;\u7B2C\u4E00\u6B21 install \u6253\u5F00\u4E00\u6B21\u5BB6\u957F\u7AEF(--no-open \u4E0D\u5F00),\u4EE5\u540E\u7684\u542F\u52A8\u90FD\u4E0D\u5F00;\u6362\u4E86 node \u7248\u672C\u6216\u5305\u632A\u4E86\u5730\u65B9\u518D install \u4E00\u6B21\n  cotutor tray on | off | status [--json]                             \u83DC\u5355\u680F / \u4EFB\u52A1\u680F\u56FE\u6807(macOS\u3001Windows;service install \u65F6\u4E00\u8D77\u88C5,--no-tray \u4E0D\u5E26):\u6B63\u5E38\u65F6\u53EA\u6709 logo,\u6709\u4E8B\u51FA\u6A59\u70B9,\u6CA1\u5728\u8DD1\u65F6\u53D8\u6DE1\u52A0\u7EA2\u70B9\u5E76\u901A\u77E5\u4E00\u6B21;\u70B9\u5B83\u770B\u72B6\u6001\u3001\u6253\u5F00\u5BB6\u957F\u7AEF\u3001\u91CD\u542F\u3001\u770B\u65E5\u5FD7\u3001\u9000\u51FA;off \u5173\u6389\u5E76\u8BB0\u4F4F\n  cotutor service status [--json] | logs [--lines <n>] [--follow]      \u540E\u53F0\u670D\u52A1\u5728\u4E0D\u5728\u8DD1\u3001\u7AEF\u53E3\u7B54\u4E0D\u7B54\u5E94\u3001\u8DD1\u7684\u54EA\u4E2A\u7248\u672C\u3001vault \u8BFB\u4E0D\u8BFB\u5F97\u5230\u3001\u65E5\u5FD7\u5728\u54EA;--json \u8FD8\u7B54\u5E73\u677F\u5730\u5740\u3001\u8BC1\u4E66\u3001\u767E\u70BC\u914D\u6CA1\u914D\u3001\u56FE\u6807;logs \u770B\u6700\u8FD1\u7684\u65E5\u5FD7\n  cotutor pin [off | status] [--pin <\u6570\u5B57>] [--json]                       \u5BB6\u957F\u7AEF /parent \u4E0E\u5DE5\u4F5C\u53F0 /dev \u7684\u9501:\u673A\u5668\u7EA7 PIN(\u6240\u6709 workspace \u5171\u7528),iPad \u4E0A\u8F93\u4E00\u6B21\u3001\u8FD9\u53F0\u7535\u8111\u514D\u5BC6;\u6CA1\u8BBE\u5C31\u5168\u5F00(\u5BB6\u957F\u5728\u65C1\u8FB9\u53EF\u4EE5\u4E0D\u8BBE);off \u64A4\u6389\n  cotutor cert [--host <\u540D\u6216IP>]...                                      \u7528 mkcert \u5EFA\u8FD9\u53F0\u673A\u5668\u7684\u81EA\u7B7E\u8BC1\u4E66\u5230 ~/.config/cotutor/certs/(\u5E73\u677F\u3001\u624B\u673A\u4E0A\u5F55\u97F3\u8981 HTTPS;\u6240\u6709 workspace \u5171\u7528)\n  cotutor send <\u8001\u5E08> [<\u6D88\u606F>] [--from kid|system] [--runtime <\u540D>] [--new] [--photo a.jpg,b.png] [--activity <\u540D> [--param '\u540D=\u503C;\u540D=\u503C']] [--lane main,tts] [--quiet]   \u7EC8\u7AEF\u91CC\u53D1\u4E00\u6761,\u73B0\u573A\u6309\u9053\u6253\u5370\u6BCF\u9053\u5DE5\u5E8F\u7684\u4E8B\u4EF6,\u8BF4\u5B8C\u6253\u5370\u7ED3\u679C(\u5B69\u5B50\u7684\u8BDD\u7167\u5B9E\u65F6\u5199,\u540C\u5B69\u5B50\u7AEF:\u4E0A\u4E0B\u6587\u5305\u5E26 live:\u3001\u4E0D\u8865\u63D0\u95EE\u5361,\u53EA\u662F\u6CA1\u6709\u5634;--from system \u4E0D\u7B97;--new \u5F00\u65B0\u8BDD\u9898;--photo \u5E26\u4F5C\u4E1A\u7167\u7247,\u62F7\u8FDB captures/,\u6709\u7167\u7247\u65F6\u6D88\u606F\u53EF\u4EE5\u7A7A;--activity \u50CF\u5B69\u5B50\u70B9\u4E86\u9996\u9875\u7684 activity \u6309\u94AE,\u65B0\u5F00\u8BDD\u9898,\u53C2\u6570\u540C\u6309\u94AE\u4E0B\u9762\u90A3\u51E0\u884C;--quiet \u53EA\u8981\u7ED3\u679C)\n  cotutor pack <\u8001\u5E08> [<\u6D88\u606F>] [--from kid|system] [--at <ISO\u65F6\u95F4>] [--activity <\u540D> [--param '\u540D=\u503C;\u540D=\u503C']] [--json]   \u5E72\u8DD1\u4E0A\u4E0B\u6587\u5305(--activity \u770B activity \u8BDD\u9898\u7B2C\u4E00\u6761\u8001\u5E08\u62FF\u5230\u4EC0\u4E48):\u4E0D\u8D77\u6A21\u578B,\u6253\u5370\u73B0\u5728\u4F1A\u53D1\u7ED9\u8001\u5E08\u7684\u90A3\u4EFD + \u6BCF\u6BB5\u6765\u81EA\u54EA\u4E2A\u6587\u4EF6\u3001\u90A3\u91CC\u4E00\u5171\u51E0\u6761\u3001\u6309\u653F\u7B56\u5E26\u4E86\u51E0\u6761(\u6539\u4E86\u6863\u6848 / \u65E5\u8BB0 / \u8BA1\u5212\u7ACB\u523B\u770B\u6548\u679C)\n  cotutor replay <\u8001\u5E08> <job> [<\u65E5\u671F>] [--runtime <\u540D>] [--json]   \u56DE\u653E\u4E00\u8F6E:\u540C\u4E00\u95EE\u6309\u73B0\u5728\u7684 vault \u4E0E\u63D0\u793A\u8BCD\u518D\u8DD1\u4E00\u904D(\u843D evals/,\u4E0D\u8FDB\u5B69\u5B50\u7684\u5BF9\u8BDD\u3001\u4E0D\u914D\u97F3),\u8DD1\u5B8C\u5E76\u6392\u6253\u5370\u4E0A\u4E0B\u6587\u5305 / \u8BB2\u7A3F / \u5361 / \u8BFB\u4E86\u4EC0\u4E48\u7684 diff\n  cotutor compare <\u8001\u5E08> [<evalJob>] [<\u65E5\u671F>] [--json]                   \u518D\u770B\u4E00\u6B21\u56DE\u653E\u7684\u5BF9\u7167(\u4E0D\u7ED9 evalJob \u5C31\u5217\u8FD9\u5929\u56DE\u653E\u8FC7\u54EA\u4E9B)\n  cotutor show <\u8001\u5E08> <job> [<\u65E5\u671F>] [--json] [--evals] [--workspace <dir>]   \u770B\u4E00\u8F6E:\u95EE\u4E86\u4EC0\u4E48\u3001\u4E0A\u4E0B\u6587\u5305\u3001\u5F53\u65F6\u7684\u8001\u5E08\u6587\u4EF6\u4E0E\u6280\u80FD hash\u3001\u8BB2\u7A3F\u4E0E\u5361\u3001\u8BFB\u4E86\u4EC0\u4E48\u3001token \u4E0E\u7528\u65F6\u3001\u7ED9\u5BB6\u957F\u7684\u5C3E\u5DF4;--json \u662F\u5BB6\u957F\u7AEF\u300C\u770B\u539F\u6587\u300D\u540C\u4E00\u4EFD\u6570\u636E,\u7ED9\u7F16\u7A0B\u52A9\u624B\u5206\u6790\u7528\n  cotutor trace <\u8001\u5E08> <job> [<\u65E5\u671F>] [--lane \u2026] [--workspace <dir>]     \u56DE\u653E\u4E00\u8F6E\u7684\u4E8B\u4EF6(<\u65E5\u671F>.<job>.events.jsonl;\u6392\u67E5\u6628\u5929\u90A3\u8F6E\u7528)\n  cotutor rate <\u8001\u5E08> <\u8BDD\u9898> <1-5> [--date <\u65E5\u671F>]                       \u7ED9\u4E00\u4E2A\u8BDD\u9898\u6253\u661F(\u4E0E\u5BB6\u957F\u7AEF\u540C\u4E00\u6761\u8DEF;\u2265 vault.keepScore \u7684\u8BDD\u9898\u8BB0\u8D26\u65F6\u6458\u8981\u624D\u8FDB\u65E5\u8BB0)\n  cotutor bookkeep <\u8001\u5E08> [--date <\u65E5\u671F>] [--thread <\u8BDD\u9898>]...           \u8BB0\u8D26:\u8FD9\u5929\u6BCF\u4E2A\u8FD8\u6CA1\u8BB0\u8FC7\u7684\u8BDD\u9898\u5404\u8D77\u4E00\u8F6E\u8BB0\u8D26\u4EFB\u52A1,\u8001\u5E08\u56DE\u300C## \u8BB0\u8D26\u300D,\u5E94\u7528\u5199\u8FDB vault \u7684\u65E5\u8BB0(\u8BDD\u9898\u540D\u3001\u5B69\u5B50\u95EE\u3001\u6458\u8981\u3001\u89C2\u5BDF)\n  cotutor home check [--published] [--json]                           \u68C0\u67E5\u9996\u9875\u8349\u7A3F home/draft.md(\u6216\u5DF2\u53D1\u5E03\u7684\u90A3\u4EFD):\u5B69\u5B50\u4F1A\u770B\u5230\u54EA\u51E0\u5F20\u5361\u3001\u6BCF\u4F4D\u8001\u5E08\u7684\u6309\u94AE\u3001\u8981\u6539\u7684\u4E0E\u63D0\u9192(\u5E26\u884C\u53F7);\u4E0D\u82B1\u94B1\n  cotutor home publish [--force] [--from <\u6587\u4EF6>] [--json]              \u53D1\u5E03\u9996\u9875:\u68C0\u67E5 \u2192 \u7559\u5386\u53F2 home/history/<id>.md \u2192 \u5199 home/published.json(\u5B69\u5B50\u7AEF\u53EA\u8BFB\u5B83);\u6709\u8981\u6539\u7684\u4E0D\u53D1,--force \u4E22\u6389\u90A3\u51E0\u5F20\u7167\u53D1;--from \u53D1\u53E6\u4E00\u4EFD(\u5982\u5386\u53F2)\n  cotutor home show [--json]                                          \u73B0\u5728\u53D1\u5E03\u7684\u662F\u54EA\u4EFD\u3001\u51E0\u5929\u524D\u3001\u6BCF\u4E2A\u6309\u94AE\u88AB\u70B9\u4E86\u51E0\u6B21(\u54EA\u5929\u3001\u54EA\u4E2A\u8BDD\u9898)\n  cotutor activity check [<\u8001\u5E08> [<\u540D>]] [--json]                      \u68C0\u67E5 activity \u6587\u4EF6(agents/<\u8001\u5E08>/activities/<\u540D>.md):\u5BB6\u957F\u586B\u7684\u3001\u5E94\u7528\u7B97\u7684\u3001\u5E94\u7528\u62E6\u7684\u3001\u88C1\u6BB5\u3001\u63D2\u69FD\u3001\u6B63\u6587\u7528\u7684\u5361\u3001\u7B2C\u4E00\u53E5\u4E0E\u6536(\u5E26\u884C\u53F7);\u4E0D\u82B1\u94B1\n  cotutor activity eval <\u8001\u5E08> <\u540D> [--runs <n>] [--only <\u4F8B\u5B50>] [--kid-model <\u5343\u95EE\u6A21\u578B>] [--json]   \u7167 <\u540D>.\u4F8B\u5B50.md \u8DD1:\u771F\u8001\u5E08 + \u6A21\u62DF\u5B69\u5B50(\u5343\u95EE,\u7F3A\u7701 qwen3.8-flash,\u6709 Token Plan \u8D70\u5B83)\u591A\u8F6E(\u7167\u5B9E\u65F6\u5199,\u540C\u5B69\u5B50\u7AEF),\u5224\u53EA\u770B\u677F\u4E66;\u4E00\u4E2A\u4F8B\u5B50\u8DD1 n \u6B21(\u7F3A\u7701 3)\u6B21\u6B21\u90FD\u8FC7\u624D\u7B97\u8FC7;\u843D evals/,\u753B\u5BB6\u662F\u5047\u7684;\u82B1\u94B1\n  cotutor chalk <check|build|bake|snap|dub> <scene.ts|\u8BFE\u5305 id> [...]   \u505A\u5C0F\u8BFE\u5802\u7684\u8BFE\u5305:check \u6821\u9A8C\u573A\u666F\u3001build \u51FA\u8BFE\u5305\u5230 bundles/\u3001bake \u70E4\u753B\u9762\u3001snap \u6BCF\u6B65\u622A\u56FE\u3001dub \u914D\u97F3(cotutor chalk \u770B\u5404\u81EA\u7684\u9009\u9879;bake / snap \u8981\u672C\u673A\u7684 Chrome)\n  cotutor mock [--port <n>] [--scenario normal|nokey] [--delay <ms>] [--http]   \u4E0D\u7ECF\u771F\u5B9E\u8001\u5E08\u4E0E\u767E\u70BC,\u7528\u56FA\u5B9A\u7684\u677F\u4E66 JSON \u8D77\u5B69\u5B50\u7AEF,\u6D4B\u524D\u7AEF\u4EA4\u4E92\u4E0E\u6E32\u67D3(\u4E0D\u9700\u8981 workspace;\u8001\u5E08\u90FD\u8D70\u5B9E\u65F6\u8001\u5E08\u9875,\u5047\u5634\u7167\u811A\u672C\u5FF5\u9759\u97F3\u7684\u58F0\u97F3;nokey = \u6CA1\u914D\u767E\u70BC,\u5B69\u5B50\u7AEF\u53EA\u51FA\u300C\u8001\u5E08\u4EEC\u8FD8\u6CA1\u5230\u300D)\n  cotutor --version | --help\nworkspace\u89E3\u6790:--workspace > COTUTOR_WORKSPACE > cwd \u6216\u7956\u5148\u6709 cotutor.json > ~/.config/cotutor/config.json > ~/cotutor/ \u4E0B\u552F\u4E00\u7684\u5B69\u5B50\u76EE\u5F55\n\u8BD5\u7528:\u8981 workspace \u7684\u547D\u4EE4\u52A0 --sandbox,\u6362\u5230\u771F workspace \u65C1\u8FB9\u7684 .sandbox/<\u76EE\u5F55\u540D>/,\u8BD5\u7684\u5BF9\u8BDD\u4E0E vault \u7684\u5199\u5165\u4E0D\u8FDB\u5B69\u5B50\u7684\u8BB0\u5F55(\u7B2C\u4E00\u6B21\u81EA\u52A8\u5206:\u8BBE\u7F6E\u7167\u62F7,\u5BF9\u8BDD\u4E0E\u7167\u7247\u4E0D\u5E26,vault \u62F7\u4E00\u4EFD;\u6807\u9898\u524D\u52A0\u300C\u8BD5\u7528\u300D\u3001\u7AEF\u53E3 +1\u3001\u81EA\u52A8\u8BB0\u8D26\u5173\u6389);--sandbox --fresh \u91CD\u65B0\u5206\n";
+/**
+ * 帮助与参数检查,都从命令表(commands.ts)来:顶层帮助只列命令和一句话,参数、例子在 cotutor <命令> --help。
+ * 纯函数、不碰 I/O:技能生成(app/skills/*-doc.ts)和测试都 import 它,不能把 CLI 带进去。
+ */
+import { type CommandSpec } from './commands.ts';
+/** 顶层帮助;all 时连开发与调试的命令也列 */
+export declare function topHelp(opts?: {
+    all?: boolean;
+}): string;
+/** cotutor <命令> --help;place: false 不列 --workspace / --sandbox(技能参考里统一说一次) */
+export declare function commandHelp(name: string, opts?: {
+    place?: boolean;
+}): string;
+/** 技能里的命令参考:这几条命令各自的帮助;--workspace、--sandbox 在开头说一次 */
+export declare function commandsReference(names: readonly string[]): string;
+/** 不认识的命令:一句话,带最像的那个 */
+export declare function unknownCommand(cmd: string): string;
+/**
+ * 照命令表检查参数:不认识的旗标、用错子命令的旗标、不认识的子命令、多余的参数。
+ * 通过返回 null,不通过返回一句话(调用方补「看 cotutor <命令> --help」)。命令本身认不认识由调用方先判。
+ */
+export declare function checkArgs(c: CommandSpec, positionals: readonly string[], flags: Readonly<Record<string, string | true>>): string | null;
+/** 一行 cotutor 命令(文档、测试里写的)照命令表对不对得上;对得上返回 null */
+export declare function checkCommandLine(line: string): string | null;
+/** 旧名:顶层帮助 */
+export declare const USAGE: string;

package/dist/app/cli/usage.js

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

package/dist/app/http/app.js

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

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

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

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

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