cotutor 0.4.3 → 0.4.5

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/serve.d.ts

@@ -1,4 +1,5 @@
-import { type Server } from 'node:http';
+import { type RequestListener, type Server } from 'node:http';
+import { type Server as NetServer } from 'node:net';
 import { siteUrl } from '../../shared/site-url.ts';
 import type { ListenInfo } from '../../ui/parent/qr-page.ts';
 import { type AppContext } from '../http/app.ts';
@@ -14,7 +15,8 @@ export interface ServeOptions extends ResolveOptions {
     awake?: boolean;
 }
 export interface ServeResult {
-    server: Server;
+    /** 用 https 时是前面那层(同一个端口分给 https 和 http);不用 https 就是 http 服务本身 */
+    server: NetServer;
     ctx: AppContext;
     ws: Workspace;
     port: number;
@@ -42,6 +44,13 @@ export declare function localName(name?: string): string;
 export declare function certCovers(certFile: string, host: string): boolean;
 /** 扫码页要的三样;listen 之后才知道真端口 */
 export declare function listenInfo(https: boolean, port: number): ListenInfo;
+/**
+ * 用 https 时 http 那一面只做两件事:给根证书(平板扫码装证书,这时还不信任 https,所以走 http)、别的都跳到 https
+ * (切到 https 以前开着的页面、旧书签、手输的 http 地址)。只给 rootCA.pem,私钥永远不给;找不到就说怎么弄。
+ */
+export declare function plainHandler(caFile: () => string | null): RequestListener;
+/** 同一个端口既认 https 又认 http:看第一个字节,TLS 握手(0x16)交给 https,别的交给 http 那一面 */
+export declare function httpAndHttps(secure: Server, plain: Server): NetServer;
 export declare function serveWorkspace(opts?: ServeOptions): Promise<ServeResult>;
 /**
  * busy() 为真就起一个拦闲置睡眠的子进程,为假就停;serve 没了它自己退:macOS 是 caffeinate -i -w <pid>,Windows 是一段 PowerShell(service-windows.ts 的 awakeScript);Linux 什么都不做。

package/dist/app/cli/serve.js

@@ -7,9 +7,11 @@
  */
 import { execFileSync, spawn } from 'node:child_process';
 import { X509Certificate } from 'node:crypto';
-import { readFileSync } from 'node:fs';
+import { createReadStream, existsSync, readFileSync } from 'node:fs';
 import { createServer as createHttp } from 'node:http';
 import { createServer as createHttps } from 'node:https';
+import { createServer as createNetServer } from 'node:net';
+import { rootCaFile } from "./root-ca.js";
 import { hostname, networkInterfaces } from 'node:os';
 import { join } from 'node:path';
 import { siteUrl } from "../../shared/site-url.js";
@@ -91,6 +93,47 @@ export function listenInfo(https, port) {
     const ip = lanAddresses()[0];
     return { name: siteUrl(scheme, localName(), port), ip: ip ? siteUrl(scheme, ip, port) : null, https };
 }
+/**
+ * 用 https 时 http 那一面只做两件事:给根证书(平板扫码装证书,这时还不信任 https,所以走 http)、别的都跳到 https
+ * (切到 https 以前开着的页面、旧书签、手输的 http 地址)。只给 rootCA.pem,私钥永远不给;找不到就说怎么弄。
+ */
+export function plainHandler(caFile) {
+    return (req, res) => {
+        const path = (req.url ?? '/').split('?')[0];
+        if (req.method === 'GET' && (path === '/ca.crt' || path === '/ca')) {
+            const file = caFile();
+            if (file && existsSync(file)) {
+                res.writeHead(200, { 'content-type': 'application/x-x509-ca-cert', 'content-disposition': 'attachment; filename="cotutor-ca.crt"', 'cache-control': 'no-store' });
+                createReadStream(file).pipe(res);
+                return;
+            }
+            res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+            res.end('这台电脑上没找到根证书:先在电脑上跑 mkcert -install 和 cotutor cert');
+            return;
+        }
+        res.writeHead(301, { location: `https://${req.headers.host ?? 'localhost'}${req.url ?? '/'}`, 'cache-control': 'no-store' });
+        res.end();
+    };
+}
+/** 同一个端口既认 https 又认 http:看第一个字节,TLS 握手(0x16)交给 https,别的交给 http 那一面 */
+export function httpAndHttps(secure, plain) {
+    const front = createNetServer((sock) => {
+        sock.on('error', () => undefined);
+        sock.once('data', (first) => {
+            sock.pause();
+            sock.unshift(first);
+            (first[0] === 0x16 ? secure : plain).emit('connection', sock);
+            process.nextTick(() => sock.resume());
+        });
+    });
+    front.once('close', () => {
+        for (const s of [secure, plain]) {
+            s.close();
+            s.closeAllConnections();
+        }
+    });
+    return front;
+}
 export async function serveWorkspace(opts = {}) {
     const ws = loadWorkspace(opts.workspace, opts);
     // 不探 CLI(起服务不用等它);防火墙要查:平板连不上时这里是家长唯一看得到提醒的地方
@@ -101,10 +144,13 @@ export async function serveWorkspace(opts = {}) {
     ctx.openCalls = () => liveUpgrade.openCalls();
     const handler = createHandler(ctx);
     const tls = opts.http ? null : httpsFiles(ws);
-    const server = tls ? createHttps({ cert: readFileSync(tls.cert), key: readFileSync(tls.key) }, handler) : createHttp(handler);
+    const app = tls ? createHttps({ cert: readFileSync(tls.cert), key: readFileSync(tls.key) }, handler) : createHttp(handler);
     // WebSocket:实时老师的那条线(src/app/ws/);不认就关掉
-    server.on('upgrade', (req, socket, head) => { void liveUpgrade(req, socket, head, ctx).then((took) => { if (!took)
+    app.on('upgrade', (req, socket, head) => { void liveUpgrade(req, socket, head, ctx).then((took) => { if (!took)
         socket.destroy(); }, () => socket.destroy()); });
+    // 用 https 时同一个端口也认 http(给平板装根证书、把 http 的跳过去)
+    const caFile = tls ? await rootCaFile() : null;
+    const server = tls ? httpAndHttps(app, createHttp(plainHandler(() => caFile))) : app;
     // 别的程序只占着 127.0.0.1 时,绑通配地址照样成功:平板连到这边,这台电脑上开 localhost 却到了别的程序。先问一声,当被占处理(main.ts 接)
     if (port !== 0 && (await answersLocally(port)))
         throw Object.assign(new Error(`port ${port} answers on 127.0.0.1`), { code: 'EADDRINUSE', port });

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

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;