cotutor 0.3.0 → 0.4.1

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;
+}

package/dist/app/cli/serve-log.d.ts

@@ -0,0 +1,13 @@
+export declare const LOG_KEEP_DAYS = 14;
+/** 删 keepDays 天以前的(按文件名的日期,不看修改时间);返回删了哪些 */
+export declare function pruneLogs(dir: string, now: Date, keepDays?: number): string[];
+/** 今天写的是哪个文件 */
+export declare const logFileFor: (dir: string, now: Date) => string;
+/**
+ * 把 process.stdout / stderr 改写进按天的文件(不再写到原来的地方,免得 launchd.log 里再有一份);返回撤掉的函数(测试用)。
+ * 一行开头加「时:分:秒 」;一次写进来的不一定是整行,接着上一次的不再加
+ */
+export declare function teeLogs(dir: string, opts?: {
+    now?: () => Date;
+    keepDays?: number;
+}): () => void;

package/dist/app/cli/serve-log.js

@@ -0,0 +1,90 @@
+/**
+ * 后台服务的日志(cotutor serve --log-dir <目录>,cotutor service 装的就带它):stdout / stderr 改写进 <目录>/<日期>.log,一天一个,每行带时分秒;
+ * 留 LOG_KEEP_DAYS 天,起来时、换天时删更早的。一跑几个星期,不按天切就一个文件越长越大(launchd、systemd 都不替你切)。
+ * 起来之前的输出(node 自己报的、模块没加载上)还是走原来的 stdout / stderr:macOS 是 launchd 接着的 <目录>/launchd.log,Linux 是 journal。
+ */
+import { closeSync, mkdirSync, openSync, readdirSync, rmSync, writeSync } from 'node:fs';
+import { join } from 'node:path';
+import { localDate } from "../../shared/time.js";
+export const LOG_KEEP_DAYS = 14;
+const LOG_RE = /^(\d{4}-\d{2}-\d{2})\.log$/;
+/** 删 keepDays 天以前的(按文件名的日期,不看修改时间);返回删了哪些 */
+export function pruneLogs(dir, now, keepDays = LOG_KEEP_DAYS) {
+    const oldest = localDate(new Date(now.getTime() - (keepDays - 1) * 86_400_000));
+    const gone = [];
+    let names = [];
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return gone;
+    }
+    for (const f of names) {
+        const m = LOG_RE.exec(f);
+        if (m && m[1] < oldest) {
+            rmSync(join(dir, f), { force: true });
+            gone.push(f);
+        }
+    }
+    return gone;
+}
+/** 今天写的是哪个文件 */
+export const logFileFor = (dir, now) => join(dir, `${localDate(now)}.log`);
+/**
+ * 把 process.stdout / stderr 改写进按天的文件(不再写到原来的地方,免得 launchd.log 里再有一份);返回撤掉的函数(测试用)。
+ * 一行开头加「时:分:秒 」;一次写进来的不一定是整行,接着上一次的不再加
+ */
+export function teeLogs(dir, opts = {}) {
+    const now = opts.now ?? (() => new Date());
+    mkdirSync(dir, { recursive: true });
+    let day = '';
+    let fd = null;
+    let atLineStart = true;
+    const open = (d) => {
+        const today = localDate(d);
+        if (fd !== null && today === day)
+            return fd;
+        if (fd !== null)
+            closeSync(fd);
+        day = today;
+        fd = openSync(logFileFor(dir, d), 'a');
+        pruneLogs(dir, d, opts.keepDays);
+        return fd;
+    };
+    const write = (chunk, encoding) => {
+        const text = typeof chunk === 'string' ? chunk : Buffer.isBuffer(chunk) || chunk instanceof Uint8Array ? Buffer.from(chunk).toString(typeof encoding === 'string' ? encoding : 'utf8') : String(chunk);
+        if (!text)
+            return;
+        const d = now();
+        const stamp = `${[d.getHours(), d.getMinutes(), d.getSeconds()].map((n) => String(n).padStart(2, '0')).join(':')} `;
+        let out = '';
+        for (const part of text.split(/(?<=\n)/)) {
+            out += (atLineStart ? stamp : '') + part;
+            atLineStart = part.endsWith('\n');
+        }
+        try {
+            writeSync(open(d), out);
+        }
+        catch { /* 写不了日志不能把服务带倒 */ }
+    };
+    const wrap = (stream) => {
+        const original = stream.write;
+        stream.write = ((chunk, encoding, cb) => {
+            write(chunk, encoding);
+            const done = typeof encoding === 'function' ? encoding : cb;
+            if (typeof done === 'function')
+                queueMicrotask(() => done());
+            return true;
+        });
+        return () => { stream.write = original; };
+    };
+    const undo = [wrap(process.stdout), wrap(process.stderr)];
+    open(now());
+    return () => {
+        for (const u of undo)
+            u();
+        if (fd !== null)
+            closeSync(fd);
+        fd = null;
+    };
+}

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

@@ -1,13 +1,17 @@
 import { type Server } from 'node:http';
-import type { ListenInfo } from '../../ui/dev/qr-page.ts';
+import { siteUrl } from '../../shared/site-url.ts';
+import type { ListenInfo } from '../../ui/parent/qr-page.ts';
 import { type AppContext } from '../http/app.ts';
 import { type ResolveOptions, type Workspace } from '../workspace.ts';
+export { siteUrl };
 export interface ServeOptions extends ResolveOptions {
     workspace?: string;
     port?: number;
     host?: string;
     /** 强制走 HTTP(哪怕证书在) */
     http?: boolean;
+    /** 有事时拦着睡眠;缺省开 */
+    awake?: boolean;
 }
 export interface ServeResult {
     server: Server;
@@ -17,8 +21,8 @@ export interface ServeResult {
     https: boolean;
     /** 本机名与局域网 IPv4 各一条 */
     urls: string[];
-    /** 扫码页:在这台电脑上打开的那条(localhost,证书里签了) */
-    qrPage: string;
+    /** 家长端首页:在这台电脑上打开的那条(localhost,证书里签了);serve 只打印它,扫码在它里面 */
+    parentPage: string;
     warnings: string[];
 }
 /** 证书路径:cotutor.json 的 server.https 优先(相对 workspace 根),否则机器级 ~/.config/cotutor/certs/;都没有 → null */
@@ -28,10 +32,20 @@ export declare function httpsFiles(ws: Workspace): {
 } | null;
 /** 局域网 IPv4(iPad / iPhone 用它访问;.local 名不一定解析得到,有些设备还会挑中走不通的 IPv6) */
 export declare function lanAddresses(): string[];
+/**
+ * 这台电脑在局域网里的名字(不带 .local)。macOS 读「本地主机名」(系统设置 › 通用 › 共享 里那个,就是 Bonjour 名,改了系统才变);
+ * 别的系统用 os.hostname()。读不到退回 os.hostname()。serve、证书、二维码都从这里拿
+ */
+export declare function computerName(platform?: NodeJS.Platform, read?: () => string, fallback?: string): string;
 /** 本机的 mDNS 名(与 cotutor cert 签的那条同一个写法) */
-export declare function localName(host?: string): string;
+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;
 export declare function serveWorkspace(opts?: ServeOptions): Promise<ServeResult>;
+/**
+ * busy() 为真就起一个拦闲置睡眠的子进程,为假就停;serve 没了它自己退:macOS 是 caffeinate -i -w <pid>,Windows 是一段 PowerShell(service-windows.ts 的 awakeScript);Linux 什么都不做。
+ * 合盖照样睡(那是家长的事,iPad 那篇写着);返回停掉的函数
+ */
+export declare function holdAwake(busy: () => boolean, platform?: NodeJS.Platform, everyMs?: number): () => void;