cotutor 0.2.0 → 0.4.0

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

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

package/dist/app/cli/migrate.js

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

package/dist/app/cli/port-holder.d.ts

@@ -0,0 +1,16 @@
+import type { ServiceHost } from './service.ts';
+export interface PortHolder {
+    pid: number;
+    name: string;
+}
+/** lsof -Fpc 的输出:一行 p<pid>,一行 c<命令名> */
+export declare function parseLsof(out: string): PortHolder | null;
+/**
+ * 谁在监听(Windows):只认对端端口是 0,不看 State。2026-11-06 Windows 11 build 26300 上监听的 socket 状态是乱的:
+ * netstat 显示 CLOSED、FIN_WAIT_1,-State Listen 查不到,读 State 还可能抛异常
+ */
+export declare function holderScript(port: number): string;
+/** 上面那段的输出;坏的、空的当不知道 */
+export declare function parseHolder(text: string): PortHolder | null;
+/** 谁在监听这个端口;查不到(别人的进程、没装 lsof)→ null */
+export declare function portHolder(host: Pick<ServiceHost, 'platform' | 'run'>, port: number): Promise<PortHolder | null>;

package/dist/app/cli/port-holder.js

@@ -0,0 +1,34 @@
+/** 谁在监听这个端口:port.ts(端口的规矩)和托盘(tray.ts)都用,单独一个文件,托盘进程才不用加载 workspace 与 zod */
+import { psArgs } from "./service-windows.js";
+/** lsof -Fpc 的输出:一行 p<pid>,一行 c<命令名> */
+export function parseLsof(out) {
+    const pid = /^p(\d+)$/m.exec(out)?.[1];
+    const name = /^c(.+)$/m.exec(out)?.[1];
+    return pid && name ? { pid: Number(pid), name } : null;
+}
+/**
+ * 谁在监听(Windows):只认对端端口是 0,不看 State。2026-11-06 Windows 11 build 26300 上监听的 socket 状态是乱的:
+ * netstat 显示 CLOSED、FIN_WAIT_1,-State Listen 查不到,读 State 还可能抛异常
+ */
+export function holderScript(port) {
+    return [
+        `$c = Get-NetTCPConnection -LocalPort ${port} | Where-Object { $_.RemotePort -eq 0 } | Select-Object -First 1`,
+        'if ($c) { $p = Get-Process -Id $c.OwningProcess; ConvertTo-Json -Compress @{ pid = [int]$c.OwningProcess; name = $p.ProcessName } }',
+    ].join('\n');
+}
+/** 上面那段的输出;坏的、空的当不知道 */
+export function parseHolder(text) {
+    try {
+        const o = JSON.parse(text.trim());
+        return typeof o.pid === 'number' && typeof o.name === 'string' && o.name ? { pid: o.pid, name: o.name } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 谁在监听这个端口;查不到(别人的进程、没装 lsof)→ null */
+export async function portHolder(host, port) {
+    if (host.platform === 'win32')
+        return parseHolder((await host.run('powershell.exe', psArgs(holderScript(port)))).stdout);
+    return parseLsof((await host.run('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-Fpc'])).stdout);
+}

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

@@ -0,0 +1,37 @@
+import { holderScript, parseHolder, parseLsof, portHolder, type PortHolder } from './port-holder.ts';
+import { type ServiceHost } from './service.ts';
+export declare const PORT_CANDIDATES: readonly number[];
+/** sandbox 用哪个端口 */
+export declare const sandboxPort: (port: number) => number;
+export type PortState = 'free' | 'busy' | 'denied';
+/**
+ * 真绑一下就放开,看系统让不让用这个端口(被占主要靠 portState 先问的那一声)。Windows 上绑通配地址会弹防火墙的窗(还会立刻建 Block 规则),探一下不该弹,所以绑 127.0.0.1,那边也没有低端口的限制;
+ * macOS 反过来,只能绑通配;别的系统同 macOS
+ */
+export declare function tryBind(port: number, platform?: NodeJS.Platform): Promise<PortState>;
+/** 本机这个端口上有人答应吗 */
+export declare function answersLocally(port: number, timeoutMs?: number): Promise<boolean>;
+/** 先问一声再绑:别的程序只占着 127.0.0.1:443 时,绑 0.0.0.0:443 照样成功(2026-11-06 macOS、Windows 都试过),光绑看不出被占 */
+export declare function portState(port: number): Promise<PortState>;
+export interface PortChoice {
+    port: number;
+    skipped: {
+        port: number;
+        why: PortState | 'taken';
+    }[];
+}
+/** taken:别的 workspace 写着的端口,连同它们的 sandbox 都让开;选不出来报用法错误 */
+export declare function choosePort(taken: Iterable<number>, probe?: (port: number) => Promise<PortState>, candidates?: readonly number[]): Promise<PortChoice>;
+/** init 里 cotutor.json 那一行的说明 */
+export declare function choiceNote(c: PortChoice): string;
+/** 这台电脑上别的 workspace 写着的端口(~/cotutor/ 下的,加上用户配置指的那个):还没起的也要让开 */
+export declare function knownPorts(): number[];
+export { holderScript, parseHolder, parseLsof, portHolder, type PortHolder };
+export interface Holder {
+    /** 「nginx(pid 12)」;不知道是谁 → null */
+    text: string | null;
+    cotutor: 'service' | 'serve' | null;
+}
+export declare function whoHolds(host: Pick<ServiceHost, 'platform' | 'run'>, port: number): Promise<Holder>;
+/** serve 绑不上时那句话;service = 后台服务里(不重试,说怎么腾) */
+export declare function bindFailure(code: 'EACCES' | 'EADDRINUSE', port: number, who: Holder | null, service: boolean): string;

package/dist/app/cli/port.js

@@ -0,0 +1,116 @@
+/**
+ * 端口的规矩:新 workspace 只在 cotutor init 选一次,写进 cotutor.json,以后不变。
+ * 不变是因为平板上的主屏幕图标、页面存的设置都绑在「协议 + 主机 + 端口」上:换一次,平板要重新扫码、重加图标。所以运行时被占了只报错说清楚,不像 Vite 那样自动换下一个。
+ * 依次试 443(地址里不用写端口)、8443、8445…:系统不让用、被占着、留给了别的孩子就看下一个,不按系统写分支。
+ *   macOS 普通用户绑得上 0.0.0.0:443,绑 127.0.0.1:443 反而不行(Mojave 起如此,苹果没写文档,2026-11-06 在 27.2 上试过);Linux 默认 1024 以下要 root,落到 8443。
+ * 隔一个号给 sandbox 留的:它的端口是真 workspace 的 +1。
+ * 旧 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";
+export const PORT_CANDIDATES = [443, ...Array.from({ length: 9 }, (_, i) => 8443 + i * 2)];
+/** sandbox 用哪个端口 */
+export const sandboxPort = (port) => (port === 65535 ? port - 1 : port + 1);
+/**
+ * 真绑一下就放开,看系统让不让用这个端口(被占主要靠 portState 先问的那一声)。Windows 上绑通配地址会弹防火墙的窗(还会立刻建 Block 规则),探一下不该弹,所以绑 127.0.0.1,那边也没有低端口的限制;
+ * macOS 反过来,只能绑通配;别的系统同 macOS
+ */
+export function tryBind(port, platform = process.platform) {
+    return new Promise((resolve) => {
+        const s = createServer();
+        s.once('error', (e) => resolve(e.code === 'EACCES' ? 'denied' : 'busy'));
+        s.listen(port, platform === 'win32' ? '127.0.0.1' : '0.0.0.0', () => s.close(() => resolve('free')));
+    });
+}
+/** 本机这个端口上有人答应吗 */
+export function answersLocally(port, timeoutMs = 400) {
+    return new Promise((resolve) => {
+        const c = createConnection({ host: '127.0.0.1', port });
+        const finish = (yes) => { c.destroy(); resolve(yes); };
+        c.setTimeout(timeoutMs, () => finish(false));
+        c.once('connect', () => finish(true));
+        c.once('error', () => finish(false));
+    });
+}
+/** 先问一声再绑:别的程序只占着 127.0.0.1:443 时,绑 0.0.0.0:443 照样成功(2026-11-06 macOS、Windows 都试过),光绑看不出被占 */
+export async function portState(port) {
+    return (await answersLocally(port)) ? 'busy' : tryBind(port);
+}
+/** taken:别的 workspace 写着的端口,连同它们的 sandbox 都让开;选不出来报用法错误 */
+export async function choosePort(taken, probe = portState, candidates = PORT_CANDIDATES) {
+    const used = new Set();
+    for (const p of taken) {
+        used.add(p);
+        used.add(sandboxPort(p));
+    }
+    const skipped = [];
+    for (const port of candidates) {
+        if (used.has(port) || used.has(sandboxPort(port))) {
+            skipped.push({ port, why: 'taken' });
+            continue;
+        }
+        const state = await probe(port);
+        if (state === 'free')
+            return { port, skipped };
+        skipped.push({ port, why: state });
+    }
+    throw new UsageError(`端口 ${candidates.join('、')} 都用不了:cotutor init 加 --port <n> 指定一个`);
+}
+/** init 里 cotutor.json 那一行的说明 */
+export function choiceNote(c) {
+    const WHY = { busy: '被占着', denied: '这个系统不让普通用户用', taken: '留给了另一个孩子', free: '' };
+    const first = c.skipped[0];
+    const head = c.port === 443 ? '端口 443,地址里不用写端口' : `端口 ${c.port}${first ? `(${first.port} ${WHY[first.why]})` : ''}`;
+    return `${head};选定了就不再变,改了平板要重新扫码`;
+}
+/** 这台电脑上别的 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) {
+        try {
+            const raw = readJson(join(root, CONFIG_FILE));
+            if (!raw)
+                continue;
+            ports.push(typeof raw.server?.port === 'number' ? raw.server.port : DEFAULT_PORT);
+        }
+        catch { /* 配置坏了:那边 doctor 去报,这里当它没有 */ }
+    }
+    return ports;
+}
+export { holderScript, parseHolder, parseLsof, portHolder };
+export async function whoHolds(host, port) {
+    const h = await probeHealth(port);
+    const pid = h?.pid ? `(pid ${h.pid})` : '';
+    if (h)
+        return h.mode === 'service' ? { text: `cotutor 的后台服务${pid}`, cotutor: 'service' } : { text: `另一个 cotutor serve${pid}`, cotutor: 'serve' };
+    const p = await portHolder(host, port);
+    return { text: p ? `${p.name}(pid ${p.pid})` : null, cotutor: null };
+}
+const CHANGE_PORT = '要换端口就改 cotutor.json 的 server.port,平板要重新扫码、重加主屏幕图标';
+/** serve 绑不上时那句话;service = 后台服务里(不重试,说怎么腾) */
+export function bindFailure(code, port, who, service) {
+    if (code === 'EACCES') {
+        const head = `系统不让这个用户监听端口 ${port}(Linux 上 1024 以下要管理员权限,Windows 上可能落在系统保留的端口段)`;
+        return service ? `${head},后台服务先不起。${CHANGE_PORT},然后 cotutor service start` : `${head}。--port 临时换一个;${CHANGE_PORT}`;
+    }
+    const head = `端口 ${port} 被占着${who?.text ? `:${who.text} 在用` : ''}`;
+    if (service)
+        return who?.cotutor ? `${head},后台服务先不起;关掉它以后 cotutor service start` : `${head},后台服务先不起;腾出来以后 cotutor service start。${CHANGE_PORT}`;
+    if (who?.cotutor === 'service')
+        return `${head}。要在终端里调试先 cotutor service stop(cotutor service status 看状态);也可以 --port 临时换一个`;
+    if (who?.cotutor === 'serve')
+        return `${head}。关掉那个终端里的它;也可以 --port 临时换一个`;
+    return `${head}。关掉它,或 --port 临时换一个;${CHANGE_PORT}`;
+}

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

@@ -0,0 +1,25 @@
+import { type Workspace } from '../../schema/workspace.ts';
+import { type ResolveOptions } from '../workspace.ts';
+export interface SandboxResult {
+    /** sandbox 的根:后面的命令都当 --workspace 用它 */
+    root: string;
+    /** 从哪个真 workspace 分出来的 */
+    from: string;
+    /** 这次新分的(第一次,或 --fresh) */
+    created: boolean;
+    /** 分的时候 paths 怎么处理的(指在外面、只读照旧用的那几个) */
+    notes: string[];
+}
+export interface SandboxOptions extends ResolveOptions {
+    fresh?: boolean;
+    now?: Date;
+}
+/** ~/cotutor/ray → ~/cotutor/.sandbox/ray */
+export declare const sandboxRootOf: (real: string) => string;
+export declare function openSandbox(override: string | undefined, opts?: SandboxOptions): Promise<SandboxResult>;
+/**
+ * sandbox 的 cotutor.json:在真的那份原文上改(_note 这些机器不认识的键照留)。
+ * 标题加「试用 · 」、端口 +1、证书改绝对路径、自动记账关掉;paths 里每个配过的角色照它在真 workspace 里落在哪,改成指 sandbox 里对应的那处(写相对的,sandbox 挪了也不断)。
+ * 落在 workspace 与 vault 外面的:只读的材料照旧指那份,captures 改回缺省,其余会写的拦下——试用写进去的会混进真的。
+ */
+export declare function sandboxConfig(raw: Record<string, unknown>, ws: Workspace, box: string, notes: string[]): Record<string, unknown>;

package/dist/app/cli/sandbox.js

@@ -0,0 +1,166 @@
+/**
+ * --sandbox:命令换到真 workspace 旁边的试用 workspace(位置、拷什么、cotutor.json 改哪几处见 src/schema/workspace.ts 的 SANDBOX_*)。
+ * 没有就分一个;有了就接着用(试过的对话留着,能接着聊、能试记账);--fresh 重新分。
+ * 重新分先分到临时目录,成了才换掉旧的:中途断了旧的还在,半截的不会被当成分好的(标记最后写)。
+ * 已经在 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 { 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 { 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);
+}
+export async function openSandbox(override, opts = {}) {
+    const { root } = resolveRoot(override, opts);
+    const here = readSandboxMark(root);
+    const real = here ? here.from : root;
+    const box = here ? root : sandboxRootOf(real);
+    const existing = here ?? ((await exists(box)) ? readSandboxMark(box) : null);
+    if (!existing && (await exists(box)))
+        throw new UsageError(`${redactHome(box)} 已经有了,但不是 sandbox(没有 ${SANDBOX_MARK}),不动它;挪走再试`);
+    if (existing && !opts.fresh) {
+        const moved = await followPort(box, existing.from);
+        return { root: box, from: existing.from, created: false, notes: moved ? [moved] : [] };
+    }
+    if (!(await exists(join(real, CONFIG_FILE))))
+        throw new UsageError(`这个 sandbox 是从 ${redactHome(real)} 分出来的,那里已经没有 workspace 了,重新分不了`);
+    const notes = await fork(real, box, opts);
+    return { root: box, from: real, created: true, notes };
+}
+/** 试用的端口永远是真 workspace 的 +1:真的搬了端口,试用下次打开跟过去,不用记两套规矩;返回说明,没动 → null */
+async function followPort(box, real) {
+    const file = join(box, CONFIG_FILE);
+    try {
+        const realRaw = readJson(join(real, CONFIG_FILE));
+        const raw = readJson(file);
+        if (realRaw === null || raw === null)
+            return null;
+        const want = sandboxPort(parseConfig(realRaw, join(real, CONFIG_FILE)).server.port);
+        const server = (raw.server && typeof raw.server === 'object' ? raw.server : {});
+        if (server.port === want)
+            return null;
+        await writeFile(file, `${JSON.stringify({ ...raw, server: { ...server, port: want } }, null, 2)}\n`);
+        return `真 workspace 换了端口,试用跟着改成 ${want}`;
+    }
+    catch {
+        return null; // 真的那份坏了或没了:试用照旧
+    }
+}
+/** 真 workspace → box:根下照拷(跳过状态),外面的 vault 拷进来,补骨架,写改过的 cotutor.json,最后写标记再换上 */
+async function fork(real, box, opts) {
+    const ws = loadWorkspace(real, opts);
+    if (ws.sandbox)
+        throw new UsageError(`${redactHome(real)} 本身就是 sandbox,不从它再分`);
+    const vault = ws.paths.vault;
+    if (!(await stat(vault).then((s) => s.isDirectory(), () => false)))
+        throw new UsageError(`vault 不在:${redactHome(vault)}(cotutor.json 的 paths.vault);先修好真 workspace(cotutor doctor)再分`);
+    const notes = [];
+    const config = sandboxConfig(readJson(ws.files.config), ws, box, notes);
+    parseConfig(config, join(box, CONFIG_FILE));
+    const skip = new Set(SANDBOX_SKIP.map((n) => join(real, n)));
+    if (inside(ws.paths.captures, real))
+        skip.add(ws.paths.captures);
+    const keep = (src) => basename(src) !== '.git' && !skip.has(src);
+    const tmp = `${box}.tmp-${process.pid}`;
+    await rm(tmp, { recursive: true, force: true });
+    await mkdir(tmp, { recursive: true });
+    try {
+        for (const name of await readdir(real)) {
+            const src = join(real, name);
+            if (name === CONFIG_FILE || !keep(src))
+                continue;
+            // 链照原样拷(.claude/skills → ../.agents/skills 在 sandbox 里还是指自己那份)
+            await cp(src, join(tmp, name), { recursive: true, verbatimSymlinks: true, filter: keep });
+        }
+        await mkdir(join(tmp, '.cotutor'), { recursive: true });
+        for (const f of SANDBOX_KEEP_MACHINE)
+            await copyFile(join(real, '.cotutor', f), join(tmp, '.cotutor', f)).catch(() => undefined);
+        if (!inside(vault, real)) {
+            if (await exists(join(tmp, SANDBOX_VAULT)))
+                throw new UsageError(`workspace 根下已经有 ${SANDBOX_VAULT},外面的 vault 拷不进 sandbox;把它改个名再分`);
+            await cp(vault, join(tmp, SANDBOX_VAULT), { recursive: true, verbatimSymlinks: true, filter: (src) => basename(src) !== '.git' });
+        }
+        for (const d of DIRS)
+            await mkdir(join(tmp, d), { recursive: true });
+        for (const f of LEDGER_FILES)
+            await writeFile(join(tmp, f), '');
+        await writeFile(join(tmp, CONFIG_FILE), `${JSON.stringify(config, null, 2)}\n`);
+        const mark = { from: real, vault, forkedAt: (opts.now ?? new Date()).toISOString() };
+        await writeFile(join(tmp, SANDBOX_MARK), `${JSON.stringify(mark, null, 2)}\n`);
+        // 旧的到这里才删:openSandbox 查过它带标记
+        if (await exists(box))
+            await rm(box, { recursive: true, force: true });
+        await rename(tmp, box);
+    }
+    catch (err) {
+        await rm(tmp, { recursive: true, force: true });
+        throw err;
+    }
+    return notes;
+}
+/**
+ * sandbox 的 cotutor.json:在真的那份原文上改(_note 这些机器不认识的键照留)。
+ * 标题加「试用 · 」、端口 +1、证书改绝对路径、自动记账关掉;paths 里每个配过的角色照它在真 workspace 里落在哪,改成指 sandbox 里对应的那处(写相对的,sandbox 挪了也不断)。
+ * 落在 workspace 与 vault 外面的:只读的材料照旧指那份,captures 改回缺省,其余会写的拦下——试用写进去的会混进真的。
+ */
+export function sandboxConfig(raw, ws, box, notes) {
+    const real = ws.root;
+    const vault = ws.paths.vault;
+    const isObj = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+    const cfg = structuredClone(raw);
+    cfg.title = `${SANDBOX_TITLE} · ${ws.config.title}`;
+    const port = ws.config.server.port;
+    const server = { ...(isObj(raw.server) ? raw.server : {}), port: sandboxPort(port) };
+    const https = ws.config.server.https;
+    if (https)
+        server.https = { cert: expandPath(https.cert, real), key: expandPath(https.key, real) };
+    cfg.server = server;
+    // 自动记账关掉:试出来的话题不值得每个花一轮老师去记;要试记账,家长端点「记账」或在 sandbox 的 cotutor.json 打开
+    if (ws.config.vault.autoBookkeep) {
+        cfg.vault = { ...(isObj(raw.vault) ? raw.vault : {}), autoBookkeep: false };
+        notes.push('自动记账在 sandbox 里关了(试出来的话题不值得花钱记);要试记账,家长端点「记账」,或在 sandbox 的 cotutor.json 打开 vault.autoBookkeep');
+    }
+    const paths = isObj(raw.paths) ? { ...raw.paths } : {};
+    const vaultInside = inside(vault, real);
+    const newVault = vaultInside ? join(box, relative(real, vault)) : join(box, SANDBOX_VAULT);
+    if (!vaultInside)
+        paths.vault = SANDBOX_VAULT;
+    else if ('vault' in paths)
+        paths.vault = relative(real, vault) || '.';
+    for (const role of Object.keys(paths)) {
+        if (role === 'vault')
+            continue;
+        const abs = ws.paths[role];
+        const workspaceSide = PATH_ROLES.includes(role) && WORKSPACE_ROLES.includes(role);
+        const target = inside(abs, vault) ? join(newVault, relative(vault, abs)) : inside(abs, real) ? join(box, relative(real, abs)) : null;
+        if (target) {
+            paths[role] = relative(workspaceSide ? box : newVault, target) || '.';
+        }
+        else if (READ_ONLY_ROLES.includes(role)) {
+            paths[role] = abs;
+            notes.push(`paths.${role} 在 workspace 与 vault 外面(${redactHome(abs)}):只读,照旧用那份`);
+        }
+        else if (workspaceSide) {
+            delete paths[role];
+            notes.push(`paths.${role} 在 workspace 外面(${redactHome(abs)}):sandbox 里改用缺省的 ${ROLE_DEFAULTS[role]}`);
+        }
+        else {
+            throw new UsageError(`paths.${role} 指到 workspace 与 vault 外面(${redactHome(abs)}),试用时写进去的会混进真的。改成 vault 里的路径再分,或者另建一个试用 workspace(cotutor init <slug> --dir <dir>)`);
+        }
+    }
+    cfg.paths = paths;
+    return cfg;
+}