cotutor 0.3.0 → 0.4.1

package/dist/app/cli/service.js

@@ -0,0 +1,443 @@
+/**
+ * cotutor service:把一个 workspace 的 serve 装成这台电脑的后台服务——登录后自己起来、崩了自己拉起、日志按天落文件(serve-log.ts)。
+ *   macOS:用户级 LaunchAgent ~/Library/LaunchAgents/com.tarslab.cotutor.<名>.plist(launchctl bootstrap gui/<uid>);日志 ~/Library/Logs/cotutor/<名>/
+ *   Linux:systemd 用户服务 ~/.config/systemd/user/cotutor-<名>.service(systemctl --user);日志 ~/.local/state/cotutor/logs/<名>/;不登录也要跑要 loginctl enable-linger
+ *   Windows:用户的 Run 注册表项 + wscript 跑的隐藏启动器 %LOCALAPPDATA%\cotutor\service\cotutor-<名>.js + 看护进程 cotutor service run(runKeeper);为什么这样见 service-windows.ts;日志 %LOCALAPPDATA%\cotutor\logs\<名>\
+ * 一个 workspace 一个服务;找服务按文件里写的 --workspace 找,不按名字推(两个同名目录的 workspace 不会认错)。
+ * 装的那一刻把 node、bin、PATH 写死:launchd 的 PATH 里没有 Homebrew 和 nvm;换了 node 版本、包挪了地方,再 install 一次(幂等)。
+ * 退出码 0 不拉起(端口被别人占着时 serve 以 0 退,不一直重试);崩了(非 0、被杀)隔 10 秒拉起。
+ */
+import { execFile, spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, realpathSync, renameSync, statSync } from 'node:fs';
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { UsageError } from "../../shared/errors.js";
+import { logFileFor } from "./serve-log.js";
+import { RUN_KEY, STARTUP_APPROVED_KEY, decodeServiceFile, encodeLauncher, findProcsScript, launcherArgs, parseProcs, psArgs, runValue, startupDisabled, windowsLauncher } from "./service-windows.js";
+/** 命令的输出:先按 UTF-8;中文 Windows 上 reg、taskkill 这些回的是 GBK */
+function decodeOutput(buf) {
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(buf);
+    }
+    catch {
+        return new TextDecoder('gbk').decode(buf);
+    }
+}
+export const realHost = () => ({
+    platform: process.platform,
+    home: homedir(),
+    uid: process.getuid?.() ?? 0,
+    env: process.env,
+    run: (cmd, args) => new Promise((resolve) => {
+        execFile(cmd, args, { timeout: 30_000, encoding: 'buffer', windowsHide: true }, (err, stdout, stderr) => {
+            const code = err ? (typeof err.code === 'number' ? err.code : 1) : 0;
+            const errText = decodeOutput(stderr ?? Buffer.alloc(0));
+            resolve({ code, stdout: decodeOutput(stdout ?? Buffer.alloc(0)), stderr: errText || (err ? err.message : '') });
+        });
+    }),
+});
+const LABEL_PREFIX = 'com.tarslab.cotutor.';
+const UNIT_PREFIX = 'cotutor-';
+/** 这个系统做没做 */
+export function servicePlatform(platform) {
+    if (platform === 'darwin' || platform === 'linux' || platform === 'win32')
+        return platform;
+    throw new UsageError(`${platform} 上没做后台服务,用 cotutor serve 在前台跑`);
+}
+const winLocal = (host) => host.env.LOCALAPPDATA || join(host.home, 'AppData', 'Local');
+/** 服务名:workspace 目录名的小写字母数字连字符;撞了别的 workspace 加路径的短 hash */
+export function serviceName(root, taken = false) {
+    const base = basename(root).toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '') || 'workspace';
+    return taken ? `${base}-${createHash('sha256').update(root).digest('hex').slice(0, 6)}` : base;
+}
+/** 服务文件放哪 */
+export function serviceDir(host) {
+    const p = servicePlatform(host.platform);
+    if (p === 'darwin')
+        return join(host.home, 'Library', 'LaunchAgents');
+    if (p === 'win32')
+        return join(winLocal(host), 'cotutor', 'service');
+    return join(host.env.XDG_CONFIG_HOME || join(host.home, '.config'), 'systemd', 'user');
+}
+/** 日志放哪(一个服务一个目录) */
+export function serviceLogDir(host, name) {
+    const p = servicePlatform(host.platform);
+    if (p === 'darwin')
+        return join(host.home, 'Library', 'Logs', 'cotutor', name);
+    if (p === 'win32')
+        return join(winLocal(host), 'cotutor', 'logs', name);
+    return join(host.env.XDG_STATE_HOME || join(host.home, '.local', 'state'), 'cotutor', 'logs', name);
+}
+const fileOf = (host, name) => {
+    const p = servicePlatform(host.platform);
+    return join(serviceDir(host), p === 'darwin' ? `${LABEL_PREFIX}${name}.plist` : p === 'win32' ? `${UNIT_PREFIX}${name}.js` : `${UNIT_PREFIX}${name}.service`);
+};
+const labelOf = (platform, name) => (platform === 'darwin' ? `${LABEL_PREFIX}${name}` : `${UNIT_PREFIX}${name}`);
+/** serve 起来之前的输出(node 自己报的、模块没加载上)去哪:给人看的一句 */
+export function earlyLogHint(platform, s) {
+    if (platform === 'linux')
+        return `journalctl --user -u ${s.label}.service`;
+    return join(s.logDir ?? '', platform === 'win32' ? KEEPER_LOG : 'launchd.log');
+}
+/** 看护进程的日志(Windows):serve 退了几次、起来之前的输出 */
+export const KEEPER_LOG = 'keeper.log';
+const KEEPER_LOG_MAX = 5 * 1024 * 1024;
+const KEEPER_RESTART_MS = 10_000;
+/**
+ * service install 之后开不开家长端:只有这个孩子第一次装时开,下一步就是填百炼、扫码。
+ * 别的启动都不开:登录、崩溃重起、升级、重启都不是人要看页面;放进 serve 的话,一直崩就隔 10 秒开一个标签页。
+ * ssh 进来的不开:没人看,macOS 的 open 还会开到那台电脑的屏幕上。Linux 要有图形会话。--open 是人明说的,重装也开;--no-open 最大
+ */
+export function opensAfterInstall(o) {
+    if (o.noOpen)
+        return false;
+    if (o.open)
+        return true;
+    if (!o.firstTime || o.env.SSH_CONNECTION || o.env.SSH_TTY)
+        return false;
+    return o.platform !== 'linux' || Boolean(o.env.DISPLAY || o.env.WAYLAND_DISPLAY);
+}
+/**
+ * 看护进程(Windows;cotutor service run):起 serve,非 0 隔 10 秒再起,0 不起(端口被占着);同 launchd 的 KeepAlive、systemd 的 Restart=on-failure。
+ * 给 serve 带上 COTUTOR_SERVICE(mode 算后台服务、端口被占以 0 退);返回退出码
+ */
+export async function runKeeper(o) {
+    mkdirSync(o.logDir, { recursive: true });
+    const logFile = join(o.logDir, KEEPER_LOG);
+    const note = (text) => { try {
+        appendFileSync(logFile, `${new Date().toISOString()} ${text}\n`);
+    }
+    catch { /* 写不了日志不能把看护带倒 */ } };
+    for (;;) {
+        try {
+            if (statSync(logFile).size > KEEPER_LOG_MAX)
+                renameSync(logFile, `${logFile}.1`);
+        }
+        catch { /* 还没有 */ }
+        const fd = openSync(logFile, 'a');
+        const child = spawn(o.node ?? process.execPath, [o.bin ?? binPath(), 'serve', '--workspace', o.root, '--log-dir', o.logDir], { stdio: ['ignore', fd, fd], windowsHide: true, env: { ...process.env, COTUTOR_SERVICE: o.label } });
+        const code = await new Promise((resolve) => {
+            child.once('error', (err) => { note(`serve 起不来:${err.message}`); resolve(null); });
+            child.once('exit', (c) => resolve(c));
+        });
+        closeSync(fd);
+        if (code === 0) {
+            note('serve 以 0 退(端口被占着?),不再起;cotutor service start 再起');
+            return 0;
+        }
+        note(`serve 退了(${code ?? '没起来'}),${Math.round((o.restartMs ?? KEEPER_RESTART_MS) / 1000)} 秒后再起`);
+        await new Promise((r) => setTimeout(r, o.restartMs ?? KEEPER_RESTART_MS));
+    }
+}
+export const wscriptPath = (host) => join(host.env.SystemRoot || 'C:\\Windows', 'System32', 'wscript.exe');
+/** 这个 workspace 的看护进程与 serve 现在的进程 */
+async function windowsProcs(host, root) {
+    return parseProcs((await host.run('powershell.exe', psArgs(findProcsScript(root)))).stdout);
+}
+/** 停:看护进程连着子进程一起杀;看护没了留下的 serve 也杀 */
+async function stopWindows(host, root) {
+    const procs = await windowsProcs(host, root);
+    for (const p of [...procs].sort((a, b) => Number(b.keeper) - Number(a.keeper)))
+        await host.run('taskkill.exe', ['/PID', String(p.pid), '/T', '/F']);
+}
+/** 起:wscript 跑启动器,藏着窗口起看护进程,马上回来 */
+async function startWindows(host, file) {
+    const r = await host.run(wscriptPath(host), ['//B', '//Nologo', file]);
+    if (r.code !== 0)
+        throw new UsageError(`wscript 没成(系统可能关了 Windows Script Host):${(r.stderr || r.stdout).trim()}`);
+}
+export const xml = (s) => s.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
+const unxml = (s) => s.replaceAll('&lt;', '<').replaceAll('&gt;', '>').replaceAll('&quot;', '"').replaceAll('&apos;', "'").replaceAll('&amp;', '&');
+/** macOS 的 LaunchAgent */
+export function launchdPlist(s) {
+    const str = (v) => `<string>${xml(v)}</string>`;
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!-- cotutor service install 写的;改了会被下次 install 盖掉。卸掉:cotutor service uninstall --workspace ${xml(s.root)} -->
+<plist version="1.0">
+<dict>
+  <key>Label</key>${str(s.label)}
+  <key>ProgramArguments</key>
+  <array>
+${s.args.map((a) => `    ${str(a)}`).join('\n')}
+  </array>
+  <key>WorkingDirectory</key>${str(s.root)}
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>${str(s.path)}
+    <key>COTUTOR_SERVICE</key>${str(s.label)}
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key><false/>
+  </dict>
+  <key>ThrottleInterval</key><integer>10</integer>
+  <key>ProcessType</key><string>Interactive</string>
+  <key>StandardOutPath</key>${str(join(s.logDir, 'launchd.log'))}
+  <key>StandardErrorPath</key>${str(join(s.logDir, 'launchd.log'))}
+</dict>
+</plist>
+`;
+}
+/** systemd 的一个参数:双引号括起来,反斜杠与引号转义,% 写两个 */
+const sd = (v) => `"${v.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%')}"`;
+/** Linux 的 systemd 用户服务 */
+export function systemdUnit(s) {
+    return `# cotutor service install 写的;改了会被下次 install 盖掉。卸掉:cotutor service uninstall --workspace ${s.root}
+[Unit]
+Description=cotutor (${s.name})
+After=network-online.target
+
+[Service]
+ExecStart=${s.args.map(sd).join(' ')}
+WorkingDirectory=${sd(s.root)}
+Environment=${sd(`PATH=${s.path}`)}
+Environment=${sd(`COTUTOR_SERVICE=${s.label}`)}
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=default.target
+`;
+}
+/** 从服务文件里读回跑的参数(找它是哪个 workspace 的) */
+export function serviceArgs(text) {
+    const js = launcherArgs(text);
+    if (js)
+        return js;
+    const plist = /<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(text);
+    if (plist)
+        return [...plist[1].matchAll(/<string>([\s\S]*?)<\/string>/g)].map((m) => unxml(m[1]));
+    const line = /^ExecStart=(.*)$/m.exec(text)?.[1];
+    if (!line)
+        return [];
+    const out = [];
+    for (const m of line.matchAll(/"((?:[^"\\]|\\.)*)"|(\S+)/g))
+        out.push(m[1] !== undefined ? m[1].replace(/\\(.)/g, '$1').replaceAll('%%', '%') : m[2]);
+    return out;
+}
+const workspaceOf = (args) => { const i = args.indexOf('--workspace'); return i >= 0 && args[i + 1] ? args[i + 1] : null; };
+const real = (p) => { try {
+    return realpathSync(p);
+}
+catch {
+    return p;
+} };
+/** 这台电脑上 cotutor 装的服务(各是哪个 workspace 的) */
+export async function listServices(host) {
+    const dir = serviceDir(host);
+    const platform = servicePlatform(host.platform);
+    const pattern = platform === 'darwin' ? /^com\.tarslab\.cotutor\.(.+)\.plist$/ : platform === 'win32' ? /^cotutor-(.+)\.js$/ : /^cotutor-(.+)\.service$/;
+    const out = [];
+    for (const f of (await readdir(dir).catch(() => [])).sort()) {
+        const m = pattern.exec(f);
+        if (!m)
+            continue;
+        const args = serviceArgs(decodeServiceFile(await readFile(join(dir, f)).catch(() => Buffer.alloc(0))));
+        const root = workspaceOf(args);
+        if (!root)
+            continue;
+        const li = args.indexOf('--log-dir');
+        out.push({ name: m[1], label: labelOf(platform, m[1]), file: join(dir, f), args, root, logDir: li >= 0 ? args[li + 1] ?? null : null });
+    }
+    return out;
+}
+/** 这个 workspace 的服务;没装 → null(Windows 上路径不分大小写) */
+export async function findService(host, root) {
+    const norm = (p) => (host.platform === 'win32' ? real(p).toLowerCase() : real(p));
+    const want = norm(root);
+    return (await listServices(host)).find((s) => norm(s.root) === want) ?? null;
+}
+/** cotutor 的 bin(npm 装的是 dist/app/cli → 包根;仓里直跑是 src/app/cli → 仓根,一样往上三层) */
+export const binPath = () => fileURLToPath(new URL('../../../bin/cotutor.js', import.meta.url));
+/** 装:写服务文件、交给 launchd / systemd 起来;已经装过就照现在的 node、bin、PATH 重写一遍再起 */
+export async function installService(host, root, opts = {}) {
+    const platform = servicePlatform(host.platform);
+    const had = await findService(host, root);
+    let name = had?.name ?? serviceName(root);
+    if (!had && existsSync(fileOf(host, name)))
+        name = serviceName(root, true);
+    const label = labelOf(platform, name);
+    const logDir = serviceLogDir(host, name);
+    // Windows 上跑的是看护进程,它再起 serve(那边没有 launchd / systemd 替你拉起)
+    const run = platform === 'win32' ? ['service', 'run'] : ['serve'];
+    const spec = { name, label, root, logDir, path: host.env.PATH ?? '/usr/bin:/bin', args: [opts.node ?? process.execPath, opts.bin ?? binPath(), ...run, '--workspace', root, '--log-dir', logDir] };
+    const file = fileOf(host, name);
+    await mkdir(serviceDir(host), { recursive: true });
+    await mkdir(logDir, { recursive: true });
+    if (platform === 'win32') {
+        if (had)
+            await stopWindows(host, root);
+        await writeFile(file, encodeLauncher(windowsLauncher(spec.args, root)));
+        const reg = await host.run('reg.exe', ['add', RUN_KEY, '/v', label, '/t', 'REG_SZ', '/d', runValue(wscriptPath(host), file), '/f']);
+        if (reg.code !== 0)
+            throw new UsageError(`写登录项没成:${(reg.stderr || reg.stdout).trim()}`);
+        // 再装一次 = 要它:以前在任务管理器里关掉的记录也去掉(没有这一笔时报错,不管)
+        await host.run('reg.exe', ['delete', STARTUP_APPROVED_KEY, '/v', label, '/f']);
+        await startWindows(host, file);
+    }
+    else if (platform === 'darwin') {
+        // 先卸下旧的(没装过会报错,不管),再装上;bootstrap 会按 RunAtLoad 马上起
+        await host.run('launchctl', ['bootout', `gui/${host.uid}/${label}`]);
+        await writeFile(file, launchdPlist(spec));
+        const r = await host.run('launchctl', ['bootstrap', `gui/${host.uid}`, file]);
+        if (r.code !== 0)
+            throw new UsageError(`launchctl bootstrap 没成:${(r.stderr || r.stdout).trim()}`);
+    }
+    else {
+        await writeFile(file, systemdUnit(spec));
+        await host.run('systemctl', ['--user', 'daemon-reload']);
+        const r = await host.run('systemctl', ['--user', 'enable', '--now', `${label}.service`]);
+        if (r.code !== 0)
+            throw new UsageError(`systemctl --user enable 没成:${(r.stderr || r.stdout).trim()}`);
+        if (had)
+            await host.run('systemctl', ['--user', 'restart', `${label}.service`]);
+    }
+    return { spec, file, replaced: Boolean(had) };
+}
+/** 卸:停下、删服务文件;日志留着 */
+export async function uninstallService(host, root) {
+    const s = await findService(host, root);
+    if (!s)
+        return null;
+    const platform = servicePlatform(host.platform);
+    if (platform === 'win32') {
+        await stopWindows(host, s.root);
+        await host.run('reg.exe', ['delete', RUN_KEY, '/v', s.label, '/f']);
+        await host.run('reg.exe', ['delete', STARTUP_APPROVED_KEY, '/v', s.label, '/f']);
+    }
+    else if (platform === 'darwin')
+        await host.run('launchctl', ['bootout', `gui/${host.uid}/${s.label}`]);
+    else
+        await host.run('systemctl', ['--user', 'disable', '--now', `${s.label}.service`]);
+    await rm(s.file, { force: true });
+    if (host.platform === 'linux')
+        await host.run('systemctl', ['--user', 'daemon-reload']);
+    return s;
+}
+const need = async (host, root) => {
+    const s = await findService(host, root);
+    if (!s)
+        throw new UsageError('这个 workspace 没装后台服务:cotutor service install');
+    return s;
+};
+/** 起 / 停 / 重起。macOS 的停是从 launchd 卸下、Windows 的停是杀进程(服务文件都还在,下次登录又会起;要一直不起用 uninstall) */
+export async function controlService(host, root, what) {
+    const s = await need(host, root);
+    const platform = servicePlatform(host.platform);
+    if (platform === 'win32') {
+        if (what !== 'start')
+            await stopWindows(host, s.root);
+        if (what === 'stop')
+            return s;
+        // 已经在跑就不再起一个(再起一个也会因为端口被占以 0 退,只是多转一圈)
+        if (!(await windowsProcs(host, s.root)).some((p) => p.keeper))
+            await startWindows(host, s.file);
+        return s;
+    }
+    if (platform === 'darwin') {
+        const target = `gui/${host.uid}/${s.label}`;
+        const loaded = (await host.run('launchctl', ['print', target])).code === 0;
+        if (what === 'stop') {
+            if (loaded)
+                await host.run('launchctl', ['bootout', target]);
+            return s;
+        }
+        const r = loaded ? await host.run('launchctl', what === 'restart' ? ['kickstart', '-k', target] : ['kickstart', target]) : await host.run('launchctl', ['bootstrap', `gui/${host.uid}`, s.file]);
+        if (r.code !== 0)
+            throw new UsageError(`launchctl 没成:${(r.stderr || r.stdout).trim()}`);
+        return s;
+    }
+    const r = await host.run('systemctl', ['--user', what, `${s.label}.service`]);
+    if (r.code !== 0)
+        throw new UsageError(`systemctl --user ${what} 没成:${(r.stderr || r.stdout).trim()}`);
+    return s;
+}
+/** launchctl print 那一大段里要的几行(一层缩进的 state / pid / last exit code) */
+export function parseLaunchctlPrint(text) {
+    const field = (k) => new RegExp(`^\\t${k} = (.*)$`, 'm').exec(text)?.[1]?.trim() ?? null;
+    const pid = Number(field('pid'));
+    return { running: field('state') === 'running', pid: Number.isInteger(pid) && pid > 0 ? pid : null, lastExit: field('last exit code') };
+}
+/** systemctl show -p ActiveState,MainPID,ExecMainStatus 的输出 */
+export function parseSystemctlShow(text) {
+    const kv = Object.fromEntries(text.split('\n').map((l) => l.split('=')).filter((p) => p.length >= 2).map(([k, ...v]) => [k.trim(), v.join('=').trim()]));
+    const pid = Number(kv.MainPID);
+    return { running: kv.ActiveState === 'active', pid: pid > 0 ? pid : null, lastExit: kv.ExecMainStatus ?? null };
+}
+/** 本机问一下 serve 起来没有(自签证书不验);先 https 再 http */
+export async function probeHealth(port, timeoutMs = 1500) {
+    const get = (secure) => new Promise((resolve) => {
+        const req = (secure ? httpsRequest : httpRequest)({ host: '127.0.0.1', port, path: '/api/health', method: 'GET', timeout: timeoutMs, ...(secure ? { rejectUnauthorized: false } : {}) }, (res) => {
+            let body = '';
+            res.setEncoding('utf8');
+            res.on('data', (c) => { body += c; });
+            res.on('end', () => { try {
+                const j = JSON.parse(body);
+                resolve(j.ok ? { ...j, scheme: secure ? 'https' : 'http' } : null);
+            }
+            catch {
+                resolve(null);
+            } });
+        });
+        req.on('timeout', () => req.destroy());
+        req.on('error', () => resolve(null));
+        req.end();
+    });
+    return (await get(true)) ?? (await get(false));
+}
+/** 装没装、在不在跑、问得到不(端口来自 cotutor.json 或 --port) */
+export async function serviceStatus(host, root, port) {
+    const s = await findService(host, root);
+    let st = { running: false, pid: null, lastExit: null };
+    let autostart = null;
+    if (s && host.platform === 'win32') {
+        const procs = await windowsProcs(host, s.root);
+        st = { running: procs.some((p) => p.keeper), pid: (procs.find((p) => !p.keeper) ?? procs[0])?.pid ?? null, lastExit: null };
+        autostart = (await host.run('reg.exe', ['query', RUN_KEY, '/v', s.label])).code === 0 && !startupDisabled((await host.run('reg.exe', ['query', STARTUP_APPROVED_KEY, '/v', s.label])).stdout);
+    }
+    else if (s) {
+        const r = host.platform === 'darwin'
+            ? await host.run('launchctl', ['print', `gui/${host.uid}/${s.label}`])
+            : await host.run('systemctl', ['--user', 'show', '-p', 'ActiveState,MainPID,ExecMainStatus', `${s.label}.service`]);
+        if (r.code === 0)
+            st = host.platform === 'darwin' ? parseLaunchctlPrint(r.stdout) : parseSystemctlShow(r.stdout);
+    }
+    const health = await probeHealth(port);
+    return { installed: s, ...st, health, logFile: s?.logDir ? logFileFor(s.logDir, new Date()) : null, autostart };
+}
+/** 起来以后等它答应(装完、重起完);等不到 → null */
+export async function waitHealthy(port, ms = 15_000, since) {
+    const until = Date.now() + ms;
+    while (Date.now() < until) {
+        const h = await probeHealth(port, 1000);
+        if (h && (!since || h.started > since))
+            return h;
+        await new Promise((r) => setTimeout(r, 300));
+    }
+    return null;
+}
+/** 日志的最后 n 行(今天的没有就找最近一天的) */
+export async function tailLog(logDir, n = 50) {
+    const files = (await readdir(logDir).catch(() => [])).filter((f) => /^\d{4}-\d{2}-\d{2}\.log$/.test(f)).sort();
+    const last = files.at(-1);
+    if (!last)
+        return null;
+    const file = join(logDir, last);
+    const lines = (await readFile(file, 'utf8').catch(() => '')).split('\n');
+    if (lines.at(-1) === '')
+        lines.pop();
+    return { file, lines: lines.slice(-n) };
+}
+/** pmset -g custom 里「AC Power:」那一段的 sleep(接着电源几分钟没人碰就睡,0 = 不睡);没有那一段 → null */
+export function acSleepMinutes(pmset) {
+    const ac = /^AC Power:\s*$([\s\S]*?)(?=^\S|(?![\s\S]))/m.exec(pmset)?.[1];
+    const v = ac ? /^\s+sleep\s+(\d+)/m.exec(ac)?.[1] : undefined;
+    return v === undefined ? null : Number(v);
+}

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

@@ -10,7 +10,7 @@ export interface ShippedAgent {
     description: string;
 }
 export declare function shippedAgents(dir?: string): Promise<ShippedAgent[]>;
-export declare const GITIGNORE = "# \u8F6C\u5F55\u65E5\u5FD7\u4F53\u79EF\u5927\u3001\u53EF\u4ECE\u5BF9\u8BDD\u7D22\u5F15\u91CD\u5EFA\u5173\u952E\u4FE1\u606F;\u8981\u7559\u5168\u6863\u5C31\u5220\u6389\u4E0B\u9762\u8FD9\u884C\nconversations/**/*.log\n# \u914D\u97F3\u53EF\u91CD\u65B0\u5408\u6210\nconversations/**/*.mp3\n# \u56DE\u653E(cotutor replay)\u662F\u8C03\u63D0\u793A\u8BCD\u4E0E vault \u65F6\u7684\u5BF9\u7167,\u4E0D\u662F\u5B69\u5B50\u7684\u5BF9\u8BDD\nevals/\n# \u505A\u597D\u7684\u8BFE(\u8BFE\u5305\u3001\u89C6\u9891\u8BFE)\u4E0E\u8BFE\u5305\u622A\u56FE:\u4F53\u79EF\u5927,\u6E90\u5728\u5BB6\u957F\u505A\u8BFE\u7684\u5730\u65B9\nbundles/\nlectures/\nsnaps/\n# \u53E3\u8BED\u8BFE(\u5B69\u5B50\u7684\u539F\u58F0\u3001\u7167\u7247)\ntalk/\n# \u4F5C\u4E1A\u7167\u7247(\u5B69\u5B50\u5728\u8001\u5E08\u9875\u4E0A\u62CD\u7684;paths.captures):\u4F53\u79EF\u5927\u3001\u53EA\u662F\u8FD9\u4E00\u8F6E\u7684\u7D20\u6750,\u8BA4\u51FA\u7684\u6587\u5B57\u5728\u65E5\u8BB0\u91CC\ncaptures/\n# \u5BB6\u957F\u5728 workspace \u91CC\u7528 Claude Code \u65F6\u5B83\u7684\u4E2A\u4EBA\u8BBE\u7F6E\n.claude/settings.local.json\n# .cotutor/ \u662F\u673A\u5668\u6587\u4EF6(\u677F\u4E66\u5199\u6CD5\u7F13\u5B58\u3001\u914D\u97F3\u7F13\u5B58\u3001\u4E8C\u7EF4\u7801\u3001\u65E5\u5FD7\u3001CLI \u58F3\u3001qwen \u7684\u5BB6),\u53EA\u7559\u51FA\u5382 hash \u4E0E schema\n.cotutor/*\n!.cotutor/shipped.json\n!.cotutor/cotutor.schema.json\nnode_modules/\n.DS_Store\n";
+export declare const GITIGNORE = "# \u8F6C\u5F55\u65E5\u5FD7\u4F53\u79EF\u5927\u3001\u53EF\u4ECE\u5BF9\u8BDD\u7D22\u5F15\u91CD\u5EFA\u5173\u952E\u4FE1\u606F;\u8981\u7559\u5168\u6863\u5C31\u5220\u6389\u4E0B\u9762\u8FD9\u884C\nconversations/**/*.log\n# \u914D\u97F3\u53EF\u91CD\u65B0\u5408\u6210\nconversations/**/*.mp3\n# \u56DE\u653E(cotutor replay)\u662F\u8C03\u63D0\u793A\u8BCD\u4E0E vault \u65F6\u7684\u5BF9\u7167,\u4E0D\u662F\u5B69\u5B50\u7684\u5BF9\u8BDD\nevals/\n# \u505A\u597D\u7684\u8BFE(\u8BFE\u5305\u3001\u89C6\u9891\u8BFE)\u4E0E\u8BFE\u5305\u622A\u56FE:\u4F53\u79EF\u5927,\u6E90\u5728\u5BB6\u957F\u505A\u8BFE\u7684\u5730\u65B9\nbundles/\nlectures/\nsnaps/\n# \u53E3\u8BED\u8BFE(\u5B69\u5B50\u7684\u539F\u58F0\u3001\u7167\u7247)\ntalk/\n# \u4F5C\u4E1A\u7167\u7247(\u5B69\u5B50\u5728\u8001\u5E08\u9875\u4E0A\u62CD\u7684;paths.captures):\u4F53\u79EF\u5927\u3001\u53EA\u662F\u8FD9\u4E00\u8F6E\u7684\u7D20\u6750,\u8BA4\u51FA\u7684\u6587\u5B57\u5728\u65E5\u8BB0\u91CC\ncaptures/\n# \u5BB6\u957F\u5728 workspace \u91CC\u7528 Claude Code \u65F6\u5B83\u7684\u4E2A\u4EBA\u8BBE\u7F6E\n.claude/settings.local.json\n# .cotutor/ \u662F\u673A\u5668\u6587\u4EF6(\u677F\u4E66\u5199\u6CD5\u7F13\u5B58\u3001\u914D\u97F3\u7F13\u5B58\u3001\u4E8C\u7EF4\u7801\u3001\u65E5\u5FD7),\u53EA\u7559\u51FA\u5382 hash \u4E0E schema\n.cotutor/*\n!.cotutor/shipped.json\n!.cotutor/cotutor.schema.json\nnode_modules/\n.DS_Store\n";
 /** 档案模板(paths.profile,缺了才写):cotutor: profile 的那篇,原文整篇进每个话题的第一条 */
 export declare function profileTemplate(name: string): string;
 /** 参考目录的 README(缺了才写) */

package/dist/app/cli/skeleton.js

@@ -11,8 +11,8 @@ import { readFile, readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseAgentFile } from "../../runtime/agent-file.js";
-import { CONFIG_SCHEMA_FILE, DICTATION_DEFAULT, cotutorJsonSchema } from "../../schema/index.js";
-import { FACTORY_API_RUNTIMES, factoryRuntimes } from "../../brain/index.js";
+import { CONFIG_SCHEMA_FILE, DEFAULT_PORT, DICTATION_DEFAULT, cotutorJsonSchema } from "../../schema/index.js";
+import { FACTORY_API_RUNTIMES } from "../../brain/index.js";
 import { DEFAULT_GRADE, PACKAGE_GRADES_DIR } from "./grades.js";
 import { mkdir, writeFile } from 'node:fs/promises';
 export const DIRS = ['agents', 'ledger', 'conversations', 'bundles'];
@@ -47,7 +47,7 @@ talk/
 captures/
 # 家长在 workspace 里用 Claude Code 时它的个人设置
 .claude/settings.local.json
-# .cotutor/ 是机器文件(板书写法缓存、配音缓存、二维码、日志、CLI 壳、qwen 的家),只留出厂 hash 与 schema
+# .cotutor/ 是机器文件(板书写法缓存、配音缓存、二维码、日志),只留出厂 hash 与 schema
 .cotutor/*
 !.cotutor/shipped.json
 !.cotutor/cotutor.schema.json
@@ -113,16 +113,17 @@ permissionMode: bypassPermissions
 (孩子常见的说法或答偏了,怎么接。)
 `;
 }
-/** 出厂老师的条目;cards = 板书写法里讲哪几种卡(《卡片协议.md》「谁拿到哪些卡」,2026-10-07),text 总在 */
+/** 出厂老师的条目;cards = 板书写法里讲哪几种卡(《卡片协议.md》「谁拿到哪些卡」,2026-10-07),text 总在;
+ *  不写 avatar:三门主科用包里的出厂头像(src/app/http/avatars.ts) */
 const TUTOR_DEFAULTS = {
-    // 数学多想一会儿:算错的代价大(别的老师用缺省 low);走 qwen3.8-max(同语文老师)。运行时 api = 应用直连百炼(2026-10-31 起出厂缺省;Qwen Code 那条是 qwen)
-    'math-tutor': { display: '数学老师', subject: '数学', avatar: '🧮', runtime: 'api', cards: ['text', 'choice', 'image', 'lecture', 'canvas', 'code'], policy: { effort: 'medium' } },
+    // 数学多想一会儿:算错的代价大(别的老师用缺省 low);走 qwen3.8-max(同语文老师)。运行时 api = 应用直连百炼(2026-10-31 起出厂缺省)
+    'math-tutor': { display: '数学老师', subject: '数学', runtime: 'api', cards: ['text', 'choice', 'image', 'lecture', 'canvas', 'code'], policy: { effort: 'medium' } },
     // 画图卡(paint)不在这里:只在「你说我画」activity 的话题里有(agents/chinese-tutor/activities/你说我画.md 头上的 cards)
     // 语文老师走 qwen3.8-max(你说我画、看图说话两套 activity eval 在它上面验证;2026-10-31 Ray 上 API 与 Qwen Code 对照过)
-    'chinese-tutor': { display: '语文老师', subject: '语文', avatar: '📚', runtime: 'api', cards: ['text', 'read', 'choice', 'image', 'tianzige', 'lecture', 'canvas'] },
+    'chinese-tutor': { display: '语文老师', subject: '语文', runtime: 'api', cards: ['text', 'read', 'choice', 'image', 'tianzige', 'lecture', 'canvas'] },
     // 英语也走 api(qwen3.8-max):2026-10-31 api-flash 真跑英语四个 activity,13 次里 5 次第一轮只出一张拍照卡、没有讲稿(实时页嘴没话可念);max 在 Ray 上都过。
     // 想省钱改 api-flash,先跑 activity eval。medium 是 2026-10-27 给 flash 加的(low 偶尔只出卡或念规则,详见年级教学包验证记录)
-    'english-tutor': { display: '英语老师', subject: '英语', avatar: '🔤', runtime: 'api', cards: ['text', 'read', 'choice', 'image', 'word', 'lecture'], policy: { effort: 'medium' } },
+    'english-tutor': { display: '英语老师', subject: '英语', runtime: 'api', cards: ['text', 'read', 'choice', 'image', 'word', 'lecture'], policy: { effort: 'medium' } },
 };
 /** cotutor.json 模板:只在文件不存在时写入;政策文件永不自动重建或覆盖(家长的决定不由机器代做)。 */
 export function configTemplate(input) {
@@ -130,7 +131,7 @@ export function configTemplate(input) {
     for (const a of input.tutors) {
         const p = TUTOR_DEFAULTS[a.name];
         tutors[a.name] = p
-            ? { display: p.display, ...(p.subject ? { subject: p.subject } : {}), avatar: p.avatar, enabled: p.enabled ?? true, ...(p.hidden ? { hidden: true } : {}), ...(p.runtime ? { runtime: p.runtime } : {}), ...(p.cards ? { cards: p.cards } : {}), ...(p.policy ? { policy: p.policy } : {}) }
+            ? { display: p.display, ...(p.subject ? { subject: p.subject } : {}), enabled: p.enabled ?? true, ...(p.hidden ? { hidden: true } : {}), ...(p.runtime ? { runtime: p.runtime } : {}), ...(p.cards ? { cards: p.cards } : {}), ...(p.policy ? { policy: p.policy } : {}) }
             : { display: a.name, enabled: true };
     }
     const cfg = {
@@ -138,13 +139,12 @@ export function configTemplate(input) {
         version: 1,
         title: input.name ? `${input.name}的老师们` : 'cotutor',
         kid: { slug: input.slug, ...(input.name ? { name: input.name } : {}) },
-        server: { port: input.port ?? 5180 },
+        server: { port: input.port ?? DEFAULT_PORT },
         paths: {},
         policyDefaults: {},
         tutors,
-        // 缺省 api:应用直连百炼,家长端「首页」填一次按量 key + 业务空间 id 就能用(2026-10-31)。
-        // Qwen Code 那两条留作备用(开发者、有 Token Plan 的):由适配器给(src/brain/cli/<cli>.ts 的 runtimes(),旗标为什么这么写的注释也在那里)
-        runtimes: { default: 'api', ...FACTORY_API_RUNTIMES, ...factoryRuntimes() },
+        // 缺省 api:应用直连百炼,家长端「首页」填一次按量 key + 业务空间 id 就能用(2026-10-31);2026-11-02 起只有 API 运行时
+        runtimes: { default: 'api', ...FACTORY_API_RUNTIMES },
         // 听写的拍照认词:模型与挑词要求(prompt 一行一个字符串)写进文件,家长看得见、改得动
         dictation: DICTATION_DEFAULT,
         // 字段说明不写在这里:一写进去就冻住(政策文件永不覆盖),$schema 指的 schema 文件每次 init / upgrade 从 zod 的 .describe() 刷新

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

@@ -51,5 +51,9 @@ export interface SkillUpgradeStep {
 export declare function upgradeSkills(root: string): Promise<SkillUpgradeStep[]>;
 /** Claude Code 只认 .claude/skills(Codex、Qwen Code 认 .agents/skills):在那里放一条相对链,两边看到的是同一份 */
 export declare const CLAUDE_SKILLS_LINK = ".claude/skills";
-/** init / upgrade 用:没有就建链;已经是链不动;是实体目录(老 workspace 没搬完)不碰,报一声 */
+/**
+ * init / upgrade 用:没有就建链;已经是链不动;是实体目录(老 workspace 没搬完)不碰,报一声。
+ * Windows 上建目录联接(junction):符号链接要「创建符号链接」权限,家长平常开的终端没有(UAC 拿掉了,开发者模式也多半没开)。
+ * 联接读回来是绝对路径,所以按指到哪儿比、不按字面比。还是建不了就跳过:这条链只给在 workspace 里用 Claude Code 的人,cotutor 自己不读它。
+ */
 export declare function linkClaudeSkills(root: string): Promise<SkillStep>;

package/dist/app/cli/skills.js

@@ -8,7 +8,7 @@
  */
 import { createHash } from 'node:crypto';
 import { cp, lstat, mkdir, readFile, readdir, readlink, rm, symlink } from 'node:fs/promises';
-import { dirname, join, relative } from 'node:path';
+import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { BOARD_SKILL } from "../../board/cards/docs.js";
 import { ANALYZE_SKILL } from "../skills/analyze-doc.js";
@@ -171,7 +171,11 @@ export async function upgradeSkills(root) {
 }
 /** Claude Code 只认 .claude/skills(Codex、Qwen Code 认 .agents/skills):在那里放一条相对链,两边看到的是同一份 */
 export const CLAUDE_SKILLS_LINK = '.claude/skills';
-/** init / upgrade 用:没有就建链;已经是链不动;是实体目录(老 workspace 没搬完)不碰,报一声 */
+/**
+ * init / upgrade 用:没有就建链;已经是链不动;是实体目录(老 workspace 没搬完)不碰,报一声。
+ * Windows 上建目录联接(junction):符号链接要「创建符号链接」权限,家长平常开的终端没有(UAC 拿掉了,开发者模式也多半没开)。
+ * 联接读回来是绝对路径,所以按指到哪儿比、不按字面比。还是建不了就跳过:这条链只给在 workspace 里用 Claude Code 的人,cotutor 自己不读它。
+ */
 export async function linkClaudeSkills(root) {
     const link = join(root, CLAUDE_SKILLS_LINK);
     const target = join('..', SKILLS_DIR);
@@ -179,11 +183,17 @@ export async function linkClaudeSkills(root) {
     const st = await lstat(link).catch(() => null);
     if (st?.isSymbolicLink()) {
         const to = await readlink(link);
-        return to === target ? { item, action: 'exists' } : { item, action: 'kept', note: `已经是指向 ${to} 的链,没动` };
+        const key = (p) => (process.platform === 'win32' ? p.toLowerCase() : p);
+        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` };
     await mkdir(dirname(link), { recursive: true });
-    await symlink(target, link);
+    try {
+        await symlink(target, link, process.platform === 'win32' ? 'junction' : undefined);
+    }
+    catch (err) {
+        return { item, action: 'kept', note: `建不了链(${err.code ?? err}),跳过:只影响在 workspace 里用 Claude Code 看技能,cotutor 照常用` };
+    }
     return { item, action: 'created', note: 'Claude Code 只认 .claude/skills,链到同一份' };
 }

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

@@ -0,0 +1,11 @@
+export declare const TRAY_DOT: {
+    r: number;
+    cx: number;
+};
+/** 没在跑时 logo 的不透明度(#F3F3F3 上墨色对比度 3.3,#202020 上白色 5.8) */
+export declare const TRAY_DIM = 0.55;
+export declare const TRAY_WIN_SIZES: readonly [16, 20, 24, 32, 40, 48];
+/** 文件名 → 内容:macOS 那几张 */
+export declare function macTrayIcons(): Record<string, Buffer>;
+/** 文件名 → 内容:Windows 那几张(<white|ink>-<ok|warn|bad>-<尺寸>.png、dot-<状态>.png) */
+export declare function windowsTrayIcons(): Record<string, Buffer>;