cotutor 0.3.0 → 0.4.0

package/dist/app/cli/doctor.js

@@ -6,19 +6,18 @@
 import { isRealtimeVoice } from "../../realtime/voices.js";
 import { dashscopeAuth } from "../../realtime/bailian.js";
 import { TTS_MODEL, ttsTarget } from "../../media/tts.js";
-import { adapterFor, parserOf, prepareCli, processEnv, runtimeIssue } from "../../brain/index.js";
-import { execFile } from 'node:child_process';
+import { compatibleLine, isPlanKey, tokenPlanKey } from "../../shared/qianwen.js";
+import { runtimeIssue } from "../../brain/index.js";
+import { homedir } from 'node:os';
 import { access, lstat, readFile, readdir, stat } from 'node:fs/promises';
-import { constants as fsConstants } from 'node:fs';
-import { basename, dirname, join, relative, resolve, sep } from 'node:path';
-import { promisify } from 'node:util';
-import { boardPreloaded, planRun, runtimeUses } from "../../brain/cli/run-plan.js";
-import { BOARD_GUIDE_PATH, boardGuideBody, takesTutorRules } from "../../runtime/context/tutor-rules.js";
+import { constants as fsConstants, existsSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { takesTutorRules } from "../../runtime/context/tutor-rules.js";
 import { parseAgentFile } from "../../runtime/agent-file.js";
 import { localDate } from "../../shared/time.js";
 import { MIN_CONTRAST, contrastWithWhite } from "../../ui/shared/tutor-color.js";
 import { memoryPath, missingEntry, pickNotes } from "../../memory/vault-notes.js";
-import { SKILLS_DIR, isApiRuntime, listTutors, mouthVoice, resolvePolicy, tutorFilePath } from "../../schema/index.js";
+import { SKILLS_DIR, cardVoice, isApiRuntime, listTutors, mouthVoice, resolvePolicy, tutorFilePath } from "../../schema/index.js";
 import { kindsFor, tutorCardKinds } from "../../board/cards/index.js";
 import { scanVault } from "../../memory/vault.js";
 import { parseArtifactEvents } from "../../runtime/journal/ledger.js";
@@ -29,12 +28,8 @@ import { readPin } from "../http/access.js";
 import { gradeOfSemester } from "../../memory/grade.js";
 import { DIRS } from "./skeleton.js";
 import { tutorStatuses, readManifest } from "./tutors.js";
-import { tokenText } from "../../shared/tokens.js";
 import { workspaceGradePack } from "./grades.js";
 import { CONFIG_FILE, ConfigError, USER_CONFIG, UsageError, assembleWorkspace, expandPath, parseConfig, readJson, redactHome, resolveRoot, } from "../workspace.js";
-const execFileP = promisify(execFile);
-/** doctor --live 发给老师的那句 */
-const LIVE_PROMPT = '只回一个字:好';
 async function statOrNull(p) {
     return stat(p).catch(() => null);
 }
@@ -46,113 +41,19 @@ async function evictedCount(dir) {
         return 0;
     }
 }
-/** 运行时的 CLI 名(run[0] 的 basename) */
-export function runtimeCli(run) {
-    return basename(run[0] ?? '');
-}
-/** 已知的环境坑,从 CLI 的输出里认出来给修复命令(错误信息即修复指南) */
-export function explainLlmFailure(text, runtime) {
-    const bin = runtimeCli(runtime);
-    if (/does not support this model|version [\d.]+ or newer is required/i.test(text)) {
-        return `这版 ${bin} 不认模型:检查 cotutor.json 的运行时 run / resume 中 -m 后的模型名,或运行 ${bin} update 升级`;
-    }
-    if (/403|request not allowed/i.test(text))
-        return `API 拒了(403):检查 ${bin} 使用的千问 key、端点与模型权限`;
-    if (/not logged in|login|authentication|401|unauthorized/i.test(text))
-        return `${bin} 的 key 无效:检查 QWENCLOUD_TOKEN_PLAN_API_KEY 或 DASHSCOPE_API_KEY,再跑 cotutor doctor`;
-    if (/ENOENT|command not found/i.test(text))
-        return `PATH 里没有 ${bin}`;
-    return `看上面的原文;不认识的错先在终端手跑一次同样的命令`;
-}
 /**
- * --live:真起一次老师(运行时的 run 模板,第一位开着的老师,只回一个字),把 API 层的坑(模型不认、没登录)摆到明面。
- * 花一分钱级别的费用,所以缺省不跑。配音同理:老师配了 voice 就合成一句。
+ * --live:老师用的是 API 运行时,不在这里真起一轮(真跑一轮用 cotutor send);配音照真合成一句(老师配了 voice 的),花一分钱级别,所以缺省不跑。
  */
 async function probeLive(ws, push, env) {
-    const { spawn } = await import('node:child_process');
     const { listTutors } = await import("../../schema/index.js");
     const { synthesize } = await import("../../media/tts.js");
-    const { parseTranscript } = await import("../../brain/transcript.js");
-    const { parseAgentFile } = await import("../../runtime/agent-file.js");
     const { tmpdir } = await import('node:os');
     const { mkdtemp, rm } = await import('node:fs/promises');
     const tutors = listTutors(ws.config).filter((t) => t.enabled);
-    const first = tutors[0];
-    if (!first) {
-        push({ name: 'live.agent', ok: false, required: false, detail: '没有开着的老师,没法探', fix: 'cotutor.json 里至少开一位' });
-        return;
-    }
     const runtimeName = ws.config.runtimes.default;
     const runtime = ws.config.runtimes[runtimeName];
-    if (!runtime || typeof runtime === 'string')
-        return;
-    if (isApiRuntime(runtime)) {
-        push({ name: `live.${runtimeName}`, ok: true, required: false, detail: `API 运行时(百炼 ${runtime.model}),不起 CLI;真跑一轮用 cotutor send` });
-        return;
-    }
-    if (runtimeIssue(runtime))
-        return; // 静态体检已报退役,不启动旧 CLI
-    let agentBody;
-    try {
-        agentBody = parseAgentFile(await readFile(tutorFilePath(ws.dirs.agents, first.name), 'utf8')).body;
-    }
-    catch {
-        /* 上面 tutor.* 已报 */
-    }
-    let boardBody;
-    try {
-        boardBody = boardGuideBody(await readFile(join(ws.root, BOARD_GUIDE_PATH), 'utf8'));
-    }
-    catch {
-        /* skills.* 已报 */
-    }
-    const systemBody = agentBody !== undefined ? (boardBody && takesTutorRules(first.name) ? `${agentBody}\n\n${boardBody}` : agentBody) : undefined;
-    // 和真跑同一条规划:命令行、stdin 那行、环境变量都由这个运行时的 CLI 适配器定
-    const plan = planRun(ws.config, { session: null }, { agent: first.name, prompt: LIVE_PROMPT, agentBody, systemBody, boardFile: join(ws.root, BOARD_GUIDE_PATH), runtime: runtimeName, root: ws.root, readDirs: [...new Set([ws.root, ws.paths.vault])] });
-    const { argv } = plan;
-    const parse = parserOf(plan.cli);
-    await prepareCli(plan.cli, ws.root);
-    const cwd = join(ws.dirs.agents, first.name);
-    const run = await new Promise((resolveRun) => {
-        let out = '';
-        let err = '';
-        const child = spawn(argv[0], argv.slice(1), { cwd, env: processEnv(plan, { ...env, COTUTOR_WORKSPACE: ws.root }), stdio: [plan.stdin ? 'pipe' : 'ignore', 'pipe', 'pipe'] });
-        const timer = setTimeout(() => child.kill(), 120_000);
-        // 消息走 stdin 的运行时:写一条,看到收尾就关 stdin
-        if (plan.stdin) {
-            child.stdin?.on('error', () => { });
-            child.stdin?.write(plan.stdin);
-        }
-        let rest = '';
-        child.stdout?.on('data', (d) => {
-            out += d.toString();
-            rest += d.toString();
-            const lines = rest.split('\n');
-            rest = lines.pop() ?? '';
-            if (plan.stdin && lines.some((l) => parse(l).some((e) => e.kind === 'result')))
-                child.stdin?.end();
-        });
-        child.stderr?.on('data', (d) => (err += d.toString()));
-        child.once('error', (e) => {
-            clearTimeout(timer);
-            resolveRun({ out, err, code: null, spawnErr: e.message });
-        });
-        child.once('close', (code) => {
-            clearTimeout(timer);
-            resolveRun({ out, err, code });
-        });
-    });
-    const t = parseTranscript(run.out, parse);
-    const said = t.items.filter((i) => i.kind === 'text' && !i.sub).map((i) => i.text).join(' ');
-    const ok = Boolean(t.final?.ok) && !run.spawnErr;
-    const raw = run.spawnErr ?? (t.final ? `${t.final.reason ?? ''} ${said}`.trim() : `没有 result 事件(exit ${run.code}):${run.err.trim().split('\n').slice(-3).join(' / ')}`);
-    push({
-        name: `live.${runtimeName}`,
-        ok,
-        required: false,
-        detail: ok ? `${first.display} 回了「${(t.final?.text ?? '').slice(0, 20)}」${t.final?.inTokens !== undefined ? ` · ${tokenText({ in: t.final.inTokens, out: t.final.outTokens ?? 0 })}` : ''}` : `起不来或没答上:${raw.slice(0, 300)}`,
-        fix: ok ? undefined : explainLlmFailure(raw, runtime.run),
-    });
+    if (runtime && typeof runtime !== 'string' && isApiRuntime(runtime))
+        push({ name: `live.${runtimeName}`, ok: true, required: false, detail: `API 运行时(百炼 ${runtime.model}),不起老师;真跑一轮用 cotutor send` });
     const voiced = tutors.find((x) => x.voice);
     if (!voiced) {
         push({ name: 'live.tts', ok: true, required: false, detail: '没有老师配 voice,不探配音(点读、单词卡没有声音)' });
@@ -163,7 +64,7 @@ async function probeLive(ws, push, env) {
     const r = await synthesize({ text: '你好', voice: voiced.voice }, { cacheDir: dir, env });
     const size = r.file ? ((await stat(r.file).catch(() => null))?.size ?? 0) : 0;
     await rm(dir, { recursive: true, force: true });
-    push({ name: 'live.tts', ok: Boolean(r.file), required: false, detail: r.file ? `${voiced.display} 的音色 ${voiced.voice} 能合成(${size} 字节)` : `${voiced.display} 的音色 ${voiced.voice} 没合成:${r.error}`, fix: r.file ? undefined : '家长端「首页」里填百炼的 key 与业务空间 id;音色到工作台音色页「卡的配音」重挑' });
+    push({ name: 'live.tts', ok: Boolean(r.file), required: false, detail: r.file ? `${voiced.display} 的音色 ${voiced.voice} 能合成(${size} 字节)` : `${voiced.display} 的音色 ${voiced.voice} 没合成:${r.error}`, fix: r.file ? undefined : '家长端「首页」里填百炼的 key 与业务空间 id;音色到家长端首页的「样子与声音」重挑' });
 }
 export async function doctorWorkspace(override, opts = {}) {
     const probeEnv = opts.probeEnv ?? true;
@@ -258,7 +159,7 @@ export async function doctorWorkspace(override, opts = {}) {
     push({ name: 'rules', ok: true, required: false, detail: rulesThere.length ? `家长自建的家规 ${rulesThere.join(' ')} 在,所有老师每轮都读` : '没有根目录的 QWEN.md(不需要:老师要知道的都在老师文件与技能里)' });
     if (ws) {
         // ---- 老师:定义文件(拷贝)+ 名字一致 + 出厂 / 自定义状态 + 老师目录 ----
-        // 老师文件只有 agents/<name>.md 这一份:应用读正文递进系统提示({agentBody} / {systemBody})
+        // 老师文件只有 agents/<name>.md 这一份:应用读正文递进系统提示
         const statuses = new Map((teachingPack ? await tutorStatuses(root) : []).map((s) => [s.name, s]));
         for (const name of Object.keys(ws.config.tutors)) {
             const shipped = statuses.has(name);
@@ -302,8 +203,8 @@ export async function doctorWorkspace(override, opts = {}) {
             push({ name: `tutor.${name}.home`, ok: there, required: true, detail: there ? `agents/${name}/ 在(会话 cwd)` : `agents/${name}/ 不在`, fix: there ? undefined : 'cotutor init 补建' });
             // 音色:一老师一音色走 API 是正路;没配的孩子端只剩浏览器合成声(只该在测试里);hidden 的老师不对孩子说话,不用音色
             const tc = ws.config.tutors[name];
-            if (tc.enabled && !tc.hidden && !tc.voice)
-                push({ name: `tutor.${name}.voice`, ok: false, required: false, detail: `${tc.display} 没配音色(cotutor.json tutors.${name}.voice),卡上的声音(点读卡、单词卡)配不了——只适合测试`, fix: '工作台 /dev 的「音色」页「卡的配音」能听着挑(挑中直接写进去)' });
+            if (tc.enabled && !tc.hidden && !cardVoice(ws.config.tutors, name))
+                push({ name: `tutor.${name}.voice`, ok: false, required: false, detail: `${tc.display} 没配音色(cotutor.json tutors.${name}.voice),卡上的声音(点读卡、单词卡)配不了——只适合测试`, fix: '家长端「首页」点这位老师的「样子与声音」挑一个' });
             // 卡的清单(《卡片协议.md》「谁拿到哪些卡」):有脸的老师才递板书写法;只是报一声讲哪几种
             if (takesTutorRules(name)) {
                 const kinds = tutorCardKinds(tc.cards);
@@ -317,6 +218,36 @@ export async function doctorWorkspace(override, opts = {}) {
                 push({ name: `tutor.${name}.avatar`, ok: there, required: false, detail: there ? `头像 ${tc.avatar}` : inside ? `头像 ${tc.avatar} 不在,孩子端退回显示首字` : `头像 ${tc.avatar} 在 workspace 根之外,页面不给`, fix: there ? undefined : `figshot pick --workspace ${redactHome(root)} 存一张,或把 cotutor.json 的 tutors.${name}.avatar 改回 emoji` });
             }
         }
+        if (process.platform === 'win32' && (opts.firewall ?? probeEnv)) {
+            // 平板连不连得进来:Windows 只在第一次监听时问一次「允许访问」,点了取消就再也连不上(firewall.ts)
+            const { judgeFirewall, probeFirewall } = await import("./firewall.js");
+            const port = opts.port ?? ws.config.server.port;
+            const state = await probeFirewall(port);
+            if (state) {
+                const v = judgeFirewall(state, port, process.execPath);
+                push({ name: 'firewall', ok: v.ok, required: false, detail: v.detail, fix: v.fix });
+            }
+        }
+        if (probeEnv) {
+            // 端口起不起得来:被别的程序占了,后台服务只在日志里写一句就不起了(serve 自己要绑,它起来时不查这项)
+            const { probeHealth, realHost } = await import("./service.js");
+            const { portHolder, portState } = await import("./port.js");
+            const port = opts.port ?? ws.config.server.port;
+            const fix = '腾出这个端口;或改 cotutor.json 的 server.port,平板要重新扫码、重加主屏幕图标';
+            if (await probeHealth(port))
+                push({ name: 'server.port', ok: true, required: false, detail: `端口 ${port} 上 cotutor 在答应` });
+            else {
+                const state = await portState(port);
+                if (state === 'free')
+                    push({ name: 'server.port', ok: true, required: false, detail: `端口 ${port} 空着,起得来` });
+                else if (state === 'denied')
+                    push({ name: 'server.port', ok: false, required: false, detail: `系统不让这个用户监听端口 ${port},服务起不来`, fix });
+                else {
+                    const p = await portHolder(realHost(), port);
+                    push({ name: 'server.port', ok: false, required: false, detail: `端口 ${port} 被占着${p ? `:${p.name}(pid ${p.pid})在用` : ''},服务起不来`, fix });
+                }
+            }
+        }
         {
             // 舞台包:小课堂 / 画板卡要它;没有只是重卡打不开,轻卡与对话照常。做课包(cotutor chalk bake / snap)与服务端烤画面也开它,在本机的 Chrome 里
             const { stageBuilt } = await import("../http/stage.js");
@@ -324,7 +255,7 @@ export async function doctorWorkspace(override, opts = {}) {
             push({ name: 'stage.bundle', ok: built, required: false, detail: built ? 'dist/stage/ 在(舞台包:小课堂与画板卡的舞台)' : 'dist/stage/ 不在,小课堂与画板卡的舞台打不开(轻卡照常)', fix: built ? undefined : '仓库根 pnpm run build:stage(npm 装的包自带)' });
             const { chromePath } = await import("./chalk/browser.js");
             const chrome = chromePath(env);
-            push({ name: 'chalk.chrome', ok: chrome !== null, required: false, detail: chrome ? `本机的 Chrome 在(${redactHome(chrome)}):做课包截图、烤画面用它` : '找不到 Chrome:cotutor chalk bake / snap 做不了,没烤过的课包孩子端在浏览器里现画(慢、iPad 上可能不顺)', fix: chrome ? undefined : '装 Google Chrome,或环境变量 CHROME 指到 Chrome / Chromium 的可执行文件' });
+            push({ name: 'chalk.chrome', ok: chrome !== null, required: false, detail: chrome ? `本机的浏览器在(${redactHome(chrome)}):做课包截图、烤画面用它` : '找不到 Chrome:cotutor chalk bake / snap 做不了,没烤过的课包孩子端在浏览器里现画(慢、iPad 上可能不顺)', fix: chrome ? undefined : '装 Google Chrome,或环境变量 CHROME 指到 Chrome / Chromium / Edge 的可执行文件' });
             const { CLAUDE_SKILLS_LINK, skillStatuses } = await import("./skills.js");
             for (const sk of teachingPack ? await skillStatuses(root) : []) {
                 const label = { latest: sk.machine ? '机器件,最新' : '出厂件,最新', upgradable: sk.machine ? '机器件,和包里不一样(改过或包已更新)' : `出厂件,基于 ${sk.basedOn},包已更新`, custom: `自定义(基于 ${sk.basedOn})`, untracked: '自定义(没有出厂记录)', missing: sk.machine ? '缺(机器件,老师或家长的技能靠它)' : '缺' };
@@ -508,36 +439,22 @@ export async function doctorWorkspace(override, opts = {}) {
         }
         // ---- 家长端与工作台的锁(src/app/http/access.ts):机器级 PIN;没设不算错,提一句 ----
         const pin = await readPin();
-        push({ name: 'server.access', ok: pin !== null, required: false, detail: pin ? '设了 PIN:家长端 /parent 与工作台 /dev 要输一次,本机免密' : 'serve 对局域网全开,家长端 /parent 与工作台 /dev 没有锁:孩子在 iPad 上输 /parent 能看到答案,输 /dev 能改配置。家长在旁边、用完收回 iPad 的可以不设', fix: pin ? undefined : 'cotutor pin(机器级,所有 workspace 共用;cotutor pin off 撤掉)' });
+        push({ name: 'server.access', ok: pin !== null, required: false, detail: pin ? '已设 PIN' : '家长端、工作台没上锁', fix: pin ? undefined : 'cotutor pin' });
         // ---- HTTPS:iPad 上录音要;没有只提醒 ----
         const tls = httpsFiles(ws);
-        push({ name: 'https', ok: tls !== null, required: false, detail: tls ? `${redactHome(tls.cert)}` : '没有证书,serve 走 HTTP(iPad / iPhone 上按住说话不可用)', fix: tls ? undefined : 'cotutor cert(需要 mkcert:brew install mkcert && mkcert -install)' });
-        // ---- 板书写法怎么递给老师:有脸的老师用到的运行时逐个说清,run / resume 不一致点名 ----
-        {
-            const used = new Set();
-            for (const [name, t] of Object.entries(ws.config.tutors))
-                if (takesTutorRules(name) && t.enabled !== false)
-                    used.add(t.runtime ?? ws.config.runtimes.default);
-            for (const name of used) {
-                const rt = ws.config.runtimes[name];
-                if (!rt || typeof rt === 'string')
-                    continue;
-                if (isApiRuntime(rt)) {
-                    push({ name: `runtime.${name}.board`, ok: true, required: false, detail: 'API 运行时:板书写法连老师正文一起进系统提示' });
-                    continue;
-                }
-                const inRun = boardPreloaded({ run: rt.run, resume: rt.run });
-                const inResume = boardPreloaded({ run: rt.resume, resume: rt.resume });
-                const how = runtimeUses(rt, '{boardFile}') ? '{boardFile} 追加进系统提示' : runtimeUses(rt, '{systemBody}') ? '{systemBody} 连老师正文一起进系统提示' : '模板里写死的 SKILL.md 路径';
-                if (inRun !== inResume)
-                    push({ name: `runtime.${name}.board`, ok: false, required: false, detail: `板书写法的预载只在 ${inRun ? 'run' : 'resume'} 模板里,两边不一致(压缩后系统提示按 resume 的旗标重建)`, fix: 'cotutor upgrade --config 补旗标,或手改 cotutor.json 让两条模板一致' });
-                else
-                    push({ name: `runtime.${name}.board`, ok: true, required: false, detail: inRun ? `板书写法预载进系统提示(${how}),各话题共享缓存` : '板书写法由应用放进每个话题第一条(<cotutor-board>);这个 CLI 能从文件或参数收系统提示的话,模板里用 {boardFile} / {systemBody} 更省' });
-            }
-        }
+        const { mkcertHint } = await import("./cert.js");
+        push({ name: 'https', ok: tls !== null, required: false, detail: tls ? `${redactHome(tls.cert)}` : '没有证书,serve 走 HTTP(平板、手机上按住说话不可用)', fix: tls ? undefined : `cotutor cert(需要 mkcert:${mkcertHint()})` });
         // ---- 百炼:老师靠实时模型开口,没配孩子端打不开;--live 真试连一次(握手就挂,不花钱) ----
+        // key 只认 ~/.config/cotutor/(2026-11-02 起);shell 里还 export 着旧的,说一句免得以为配了
         const bl = dashscopeAuth(env);
-        push({ name: 'bailian', ok: Boolean(bl), required: true, detail: bl ? `百炼按量 key …${bl.key.slice(-4)}、业务空间 ${bl.workspaceId}` : '没有百炼按量的 key 或业务空间 id:孩子端打不开(只出「老师们还没到」)', fix: bl ? undefined : '家长端「首页」里配(在这台电脑上开,或者先 cotutor pin 设家长密码);Token Plan 的 sk-sp- 不行' });
+        const oldEnv = env.DASHSCOPE_API_KEY ? '(环境变量 DASHSCOPE_API_KEY 已经不读了)' : '';
+        push({ name: 'bailian', ok: Boolean(bl), required: true, detail: bl ? `百炼按量 key …${bl.key.slice(-4)}、业务空间 ${bl.workspaceId}` : `没有百炼按量的 key 或业务空间 id:孩子端打不开(只出「老师们还没到」)${oldEnv}`, fix: bl ? undefined : '家长端「首页」里配(在这台电脑上开,或者先 cotutor pin 设家长密码),存在 ~/.config/cotutor/bailian.json;Token Plan 的 sk-sp- 不行' });
+        // Token Plan 只有开发机有,没有就不提
+        const plan = tokenPlanKey(env.HOME || homedir());
+        if (plan)
+            push({ name: 'token-plan', ok: isPlanKey(plan), required: false, detail: isPlanKey(plan) ? `Token Plan key …${plan.slice(-4)}:Token Plan 有的模型先走它` : 'token-plan.json 里的 key 不是 sk-sp- 开头,不认', fix: isPlanKey(plan) ? undefined : '换成千问 Token Plan 的 key,或删掉 ~/.config/cotutor/token-plan.json' });
+        else if (env.QWENCLOUD_TOKEN_PLAN_API_KEY)
+            push({ name: 'token-plan', ok: false, required: false, detail: '环境变量 QWENCLOUD_TOKEN_PLAN_API_KEY 已经不读了,全走百炼按量', fix: '写进 ~/.config/cotutor/token-plan.json:{"apiKey": "sk-sp-…"}' });
         if (bl && opts.live) {
             const { probeRealtime } = await import("../../realtime/preview.js");
             const { probeMessage } = await import("../machine/bailian.js");
@@ -552,51 +469,65 @@ export async function doctorWorkspace(override, opts = {}) {
         {
             const bad = Object.entries(lv.voices).filter(([, v]) => !isRealtimeVoice(v));
             const who = listTutors(ws.config, { kidOnly: true }).map((t) => `${t.name} 用 ${mouthVoice(lv, t.name)}`).join('、') || '没有有脸的老师';
-            push({ name: 'live.voices', ok: !bad.length, required: false, detail: bad.length ? `${bad.map(([t, v]) => `${t} 的「${v}」`).join('、')}:这个模型不认,嘴会一直不出声` : `嘴的音色:${who}`, fix: bad.length ? '工作台「音色」页「实时的嘴」里换一个(这个模型认的 56 个在 src/realtime/voices.ts),或改 cotutor.json 的 live.voices' : undefined });
+            push({ name: 'live.voices', ok: !bad.length, required: false, detail: bad.length ? `${bad.map(([t, v]) => `${t} 的「${v}」`).join('、')}:这个模型不认,嘴会一直不出声` : `嘴的音色:${who}`, fix: bad.length ? '家长端首页的「样子与声音」里换一个说话的声音,或改 cotutor.json 的 live.voices' : undefined });
         }
-        // 旧配置允许加载与升级;退役运行时不探版本、不启动。
+        // 旧配置里的命令行运行时(Qwen Code 等)读得进来,用不了:用到它的老师发不出去
         const usedRuntimes = new Set([ws.config.runtimes.default, ...Object.values(ws.config.tutors).filter((t) => t.enabled).map((t) => t.runtime ?? ws.config.runtimes.default)]);
         for (const [name, rt] of Object.entries(ws.config.runtimes)) {
             if (typeof rt === 'string' || isApiRuntime(rt))
                 continue;
             const issue = runtimeIssue(rt);
             if (issue)
-                push({ name: `runtime.${name}`, ok: false, required: usedRuntimes.has(name), detail: issue, fix: '按 README.md 的「旧 workspace 换运行时」说明迁移' });
+                push({ name: `runtime.${name}`, ok: false, required: usedRuntimes.has(name), detail: issue, fix: '按 README.md 的「旧 workspace 换运行时」说明改' });
         }
-        // ---- 运行时的 CLI 在不在 ----
+        // ---- 运行时:API 的走哪条线 ----
         if (probeEnv) {
             for (const [runtime, p] of Object.entries(ws.config.runtimes)) {
-                if (runtime === 'default' || typeof p === 'string')
-                    continue;
-                if (isApiRuntime(p)) {
-                    push({ name: `runtime.${runtime}`, ok: true, required: usedRuntimes.has(runtime), detail: `API 运行时(百炼 ${p.model}),不用装 CLI;凭证看 bailian 那条` });
-                    continue;
-                }
-                if (runtimeIssue(p))
+                if (runtime === 'default' || typeof p === 'string' || !isApiRuntime(p))
                     continue;
-                const bin = runtimeCli(p.run);
-                const required = usedRuntimes.has(runtime);
-                // 没有老师用的 CLI 运行时(新装缺省 api,Qwen Code 那两条是备用):不探,免得没装 qwen 的家长看到一串「起不来」
-                if (!required) {
-                    push({ name: `runtime.${runtime}`, ok: true, required: false, detail: `备用(${bin}),没有老师用它;要用就把老师的 runtime 改成 ${runtime},再跑一次 doctor` });
-                    continue;
-                }
-                try {
-                    const { stdout } = await execFileP(bin, ['--version'], { timeout: 8000 });
-                    const version = stdout.trim().split('\n')[0];
-                    push({ name: `runtime.${runtime}`, ok: true, required, detail: `${bin} ${version}` });
-                    // 这个 CLI 的适配器要多看的几样(qwen:版本、百炼 key)
-                    for (const c of adapterFor(p).check?.({ version, env }) ?? [])
-                        push({ name: `runtime.${runtime}.${c.name}`, ok: c.ok, required, detail: c.detail, fix: c.fix });
-                }
-                catch {
-                    push({ name: `runtime.${runtime}`, ok: false, required, detail: `PATH 里没有 ${bin}`, fix: required ? `装 ${bin},或把 runtimes.default 改成装了的那个运行时` : undefined });
-                }
+                const via = compatibleLine(p.model, env)?.plan ? '走 Token Plan' : '走百炼按量';
+                push({ name: `runtime.${runtime}`, ok: true, required: usedRuntimes.has(runtime), detail: `API 运行时(${p.model},${via});凭证看 bailian 那条` });
             }
         }
     }
     if (ws && opts.live)
         await probeLive(ws, push, env);
+    // ---- 后台服务(cotutor service):装了没有、写死的 node 与 bin 还在不在;接着电源会不会闲置睡眠(睡着时平板连不上) ----
+    if (probeEnv && root && (process.platform === 'darwin' || process.platform === 'linux' || process.platform === 'win32')) {
+        const { findService, realHost } = await import("./service.js");
+        const s = await findService({ ...realHost(), env }, root).catch(() => null);
+        if (s) {
+            // 菜单栏 / 任务栏图标:家长不开终端看状态靠它;家长自己关掉的不提
+            const { trayStatus, traySupported } = await import("./tray.js");
+            if (traySupported(process.platform)) {
+                const t = await trayStatus({ ...realHost(), env }).catch(() => null);
+                if (t && !t.off)
+                    push({ name: 'tray', ok: t.installed, required: false, detail: t.installed ? `托盘图标装了${t.running ? ',在跑' : ',现在没在跑(点过退出,下次登录回来)'}` : '没装托盘图标:看状态只能开终端', fix: t.installed ? undefined : 'cotutor tray on' });
+            }
+        }
+        if (!s)
+            push({ name: 'service', ok: false, required: false, detail: '没装后台服务:在终端里跑的 cotutor serve,关了终端就停', fix: 'cotutor service install(登录后自己起来、崩了自己再起)' });
+        else {
+            const gone = s.args.slice(0, 2).filter((f) => !existsSync(f));
+            push({ name: 'service', ok: !gone.length, required: false, detail: gone.length ? `后台服务 ${s.label} 指的 ${gone.map((f) => redactHome(f)).join('、')} 不在了(换了 node 版本、包挪了地方)` : `后台服务 ${s.label}(cotutor service status 看在不在跑)`, fix: gone.length ? 'cotutor service install(照现在的 node 与包重写一遍)' : undefined });
+        }
+    }
+    if (probeEnv && process.platform === 'darwin') {
+        const { acSleepMinutes } = await import("./service.js");
+        const { execFile } = await import('node:child_process');
+        const text = await new Promise((resolve) => execFile('/usr/bin/pmset', ['-g', 'custom'], { timeout: 5000, encoding: 'utf8' }, (_e, out) => resolve(String(out ?? ''))));
+        const min = acSleepMinutes(text);
+        if (min !== null)
+            push({ name: 'mac.sleep', ok: min === 0, required: false, detail: min === 0 ? '接着电源时不闲置睡眠' : `接着电源 ${min} 分钟没人碰就睡,睡着时平板连不上(有通话时 cotutor 拦着它睡,别的时候拦不了)`, fix: min === 0 ? undefined : '系统设置 › 电池 › 选项,打开「显示器关闭时,防止接通电源的 Mac 自动进入睡眠」(台式 Mac 在 系统设置 › 节能);合盖照样睡' });
+    }
+    if (probeEnv && process.platform === 'win32') {
+        const { winAcSleepSeconds } = await import("./service-windows.js");
+        const { execFile } = await import('node:child_process');
+        const text = await new Promise((resolve) => execFile('powercfg.exe', ['/query', 'SCHEME_CURRENT', 'SUB_SLEEP', 'STANDBYIDLE'], { timeout: 5000, encoding: 'latin1', windowsHide: true }, (_e, out) => resolve(String(out ?? ''))));
+        const sec = winAcSleepSeconds(text);
+        if (sec !== null)
+            push({ name: 'windows.sleep', ok: sec === 0, required: false, detail: sec === 0 ? '接着电源时不闲置睡眠' : `接着电源 ${Math.round(sec / 60)} 分钟没人碰就睡,睡着时平板连不上(有通话时 cotutor 拦着它睡,别的时候拦不了)`, fix: sec === 0 ? undefined : '设置 › 系统 › 电源和电池 › 屏幕、睡眠和休眠超时,「插入电源时,使设备在以下时间后进入睡眠状态」选「从不」;合盖看「电源按钮和盖子」那一项' });
+    }
     // ---- 用户配置 ----
     try {
         const text = await readFile(USER_CONFIG, 'utf8');
@@ -611,7 +542,12 @@ export async function doctorWorkspace(override, opts = {}) {
     catch {
         push({ name: 'user-config', ok: true, required: false, detail: `未配置(可选):{"workspace": "…"} 写进 ${redactHome(USER_CONFIG)};cotutor init 会代劳` });
     }
-    const gitThere = (await statOrNull(join(root, '.git'))) !== null;
-    push({ name: 'git', ok: gitThere, required: false, detail: gitThere ? 'workspace是 git 仓' : 'workspace不在 git 里', fix: gitThere ? undefined : '建议 git init:老师记忆、账本、政策都是不可再生状态' });
+    // sandbox(--sandbox 分出来的试用 workspace)随时能重新分,不要 git;说一句它是从哪分出来的
+    if (ws?.sandbox)
+        push({ name: 'sandbox', ok: true, required: false, detail: `试用 workspace:${ws.sandbox.forkedAt.slice(0, 10)} 从 ${redactHome(ws.sandbox.from)} 分出来;--sandbox --fresh 重新分` });
+    else {
+        const gitThere = (await statOrNull(join(root, '.git'))) !== null;
+        push({ name: 'git', ok: gitThere, required: false, detail: gitThere ? 'workspace是 git 仓' : 'workspace不在 git 里', fix: gitThere ? undefined : '建议 git init:老师记忆、账本、政策都是不可再生状态' });
+    }
     return { ok: checks.filter((c) => c.required).every((c) => c.ok), root, source, checks };
 }

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

@@ -0,0 +1,24 @@
+/** 查到的样子;配置名是 Domain / Private / Public,规则上的 Any 覆盖全部 */
+export interface FirewallState {
+    /** 连着的网络的类型(Get-NetConnectionProfile 的 NetworkCategory:Private / Public / DomainAuthenticated) */
+    networks: string[];
+    /** 防火墙开着的配置 */
+    enabled: string[];
+    /** 放行的规则(入站、允许、启用,按这个 node 或这个端口)各覆盖哪些配置,如 "Private"、"Private, Public"、"Any" */
+    allowed: string[];
+    /** 拦着这个 node 的规则覆盖哪些配置(家长在「允许访问」那一步点了取消,Windows 会建这种规则) */
+    blocked: string[];
+}
+export interface FirewallVerdict {
+    ok: boolean;
+    detail: string;
+    fix?: string;
+}
+/** 查一次的 PowerShell 脚本;node 的路径与端口写进去(单引号里的单引号写两个) */
+export declare function firewallScript(node: string, port: number): string;
+/** PowerShell 回的 JSON → 样子;一个元素的数组可能被拆成字符串,null 当空 */
+export declare function parseFirewall(text: string): FirewallState | null;
+/** 平板连不连得进来,怎么修 */
+export declare function judgeFirewall(s: FirewallState, port: number, node: string): FirewallVerdict;
+/** 真查一次(只在 Windows 上);查不了是 null */
+export declare function probeFirewall(port: number, node?: string): Promise<FirewallState | null>;

package/dist/app/cli/firewall.js

@@ -0,0 +1,79 @@
+/**
+ * Windows 防火墙放没放行 cotutor:平板连不上多半是它。Windows 只在第一次监听时弹一次「允许访问」,家长点了取消(或没看见)就再也连不上,
+ * cotutor 什么都不说(2026-10-31 实测:服务在本机回 200,从局域网超时;网络是「专用」,没有 node 的规则,也没有端口的规则)。
+ * 2026-11-06 实测(Windows 11 build 26300,普通权限的账户):node 第一次监听的同一秒,防火墙服务自己建好两条 Block 规则(名字带 Query User)再弹窗问;点「允许」才改成 Allow。
+ * 所以刚起来时查到「拦着」,可能只是弹窗还没回答,不一定点了取消。
+ * 用 PowerShell 的 NetSecurity 命令查(输出与系统语言无关;netsh 的输出是本地化的,中文 Windows 上解析不了);查不了(没有 PowerShell、超时)就不报,不瞎猜。
+ */
+import { execFile } from 'node:child_process';
+const PS_TIMEOUT_MS = 20_000;
+/** 查一次的 PowerShell 脚本;node 的路径与端口写进去(单引号里的单引号写两个) */
+export function firewallScript(node, port) {
+    const q = (s) => `'${s.replaceAll("'", "''")}'`;
+    return [
+        "$ErrorActionPreference = 'SilentlyContinue'",
+        `$node = ${q(node)}`,
+        `$port = ${q(String(port))}`,
+        '$nets = @(Get-NetConnectionProfile | ForEach-Object { [string]$_.NetworkCategory })',
+        "$on = @(Get-NetFirewallProfile | Where-Object { [string]$_.Enabled -eq 'True' } | ForEach-Object { [string]$_.Name })",
+        // 规则里的程序可能写成 %ProgramFiles%\…,也可能是小写(Windows 弹窗建的):展开了比,-eq 本来就不分大小写
+        '$byApp = @(Get-NetFirewallApplicationFilter | Where-Object { [Environment]::ExpandEnvironmentVariables([string]$_.Program) -eq $node } | Get-NetFirewallRule)',
+        '$byPort = @(Get-NetFirewallPortFilter -Protocol TCP | Where-Object { @($_.LocalPort) -contains $port } | Get-NetFirewallRule)',
+        "$live = { [string]$_.Direction -eq 'Inbound' -and [string]$_.Enabled -eq 'True' }",
+        "$allow = @(($byApp + $byPort) | Where-Object $live | Where-Object { [string]$_.Action -eq 'Allow' } | ForEach-Object { [string]$_.Profile })",
+        "$block = @($byApp | Where-Object $live | Where-Object { [string]$_.Action -eq 'Block' } | ForEach-Object { [string]$_.Profile })",
+        'ConvertTo-Json -Compress -InputObject @{ networks = $nets; enabled = $on; allowed = $allow; blocked = $block }',
+    ].join('\n');
+}
+/** PowerShell 回的 JSON → 样子;一个元素的数组可能被拆成字符串,null 当空 */
+export function parseFirewall(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text.trim());
+    }
+    catch {
+        return null;
+    }
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const list = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string') : typeof v === 'string' ? [v] : []);
+    const r = raw;
+    return { networks: list(r.networks), enabled: list(r.enabled), allowed: list(r.allowed), blocked: list(r.blocked) };
+}
+/** 平板连不连得进来,怎么修 */
+export function judgeFirewall(s, port, node) {
+    const nets = [...new Set(s.networks.map((n) => (n === 'DomainAuthenticated' ? 'Domain' : n)))];
+    const covers = (rules, profile) => rules.some((r) => r.split(/,\s*/).some((p) => p === 'Any' || p === profile));
+    const guarded = nets.filter((n) => s.enabled.includes(n));
+    const allowCmd = `netsh advfirewall firewall add rule name="cotutor" dir=in action=allow protocol=TCP localport=${port} profile=private`;
+    if (!nets.length)
+        return { ok: true, detail: '没连上网络,查不了防火墙(连上 Wi-Fi 再跑一次 doctor)' };
+    if (!guarded.length)
+        return { ok: true, detail: `防火墙在连着的网络上关着(${nets.join('、')}),平板连得进来` };
+    if (guarded.some((n) => covers(s.blocked, n))) {
+        return {
+            ok: false,
+            detail: '防火墙拦着这个 node(第一次起服务时 Windows 先拦着、再弹窗问「允许访问」:还没回答,或者点了取消):平板连不上,这台电脑上照常',
+            fix: `屏幕上有「允许访问」的窗口就点「允许」;没有窗口(点过取消了):管理员终端里先删拦截规则:netsh advfirewall firewall delete rule name=all dir=in program="${node}";再放行:${allowCmd}`,
+        };
+    }
+    if (guarded.every((n) => covers(s.allowed, n)))
+        return { ok: true, detail: `防火墙放行了(端口 ${port} 或这个 node)` };
+    if (guarded.includes('Public') && !covers(s.allowed, 'Public')) {
+        return {
+            ok: false,
+            detail: '这台电脑连的网络是「公用」,防火墙不让平板连进来;这台电脑上照常',
+            fix: `设置 › 网络和 Internet › 这个网络的属性,改成「专用」;再在管理员终端里放行:${allowCmd}`,
+        };
+    }
+    return { ok: false, detail: `防火墙没放行端口 ${port}:平板连不上,这台电脑上照常`, fix: `管理员终端(右键「终端」选「以管理员身份运行」)里跑:${allowCmd}` };
+}
+/** 真查一次(只在 Windows 上);查不了是 null */
+export function probeFirewall(port, node = process.execPath) {
+    const encoded = Buffer.from(firewallScript(node, port), 'utf16le').toString('base64');
+    return new Promise((resolve) => {
+        execFile('powershell.exe', ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', encoded], { timeout: PS_TIMEOUT_MS, windowsHide: true }, (err, stdout) => {
+            resolve(err ? null : parseFirewall(String(stdout)));
+        });
+    });
+}

package/dist/app/cli/init.js

@@ -12,6 +12,7 @@ import { DEFAULT_GRADE, LEGACY_GRADE, requireGradePack } from "./grades.js";
 import { installActivities } from "./activities.js";
 import { installSkills, linkClaudeSkills } from "./skills.js";
 import { migrateLayout } from "./migrate.js";
+import { choiceNote, choosePort, knownPorts } from "./port.js";
 import { installThemes } from "./themes.js";
 import { scanVault } from "../../memory/vault.js";
 import { CONFIG_FILE, ConfigError, UsageError, HOME_ROOT, USER_CONFIG, expandPath, loadWorkspace, parseConfig, readJson, redactHome } from "../workspace.js";
@@ -53,8 +54,10 @@ export async function initWorkspace(opts) {
     if (await exists(config))
         steps.push({ item: CONFIG_FILE, action: 'kept', note: '政策文件不覆盖(家长的决定)' });
     else {
-        await writeFile(config, configTemplate({ slug: opts.slug, name: opts.name, port: opts.port, tutors: agents }));
-        steps.push({ item: CONFIG_FILE, action: 'created' });
+        // 端口只在这里选一次,写进文件以后不变(port.ts);--port 给了就听它的
+        const chosen = opts.port === undefined ? await choosePort(knownPorts()) : null;
+        await writeFile(config, configTemplate({ slug: opts.slug, name: opts.name, port: opts.port ?? chosen?.port, tutors: agents }));
+        steps.push({ item: CONFIG_FILE, action: 'created', ...(chosen ? { note: choiceNote(chosen) } : {}) });
     }
     // 老师按 cotutor.json 里有谁走(家长自己加的也补目录与链);配置坏了就只管出厂的,doctor 去报
     let tutorNames = [];
@@ -147,9 +150,9 @@ export async function initWorkspace(opts) {
     if (!(await exists(join(root, '.git'))))
         suggestions.push('git init(建议:老师记忆、账本、政策都是不可再生状态,git 是破坏后的兜底)');
     suggestions.push('档案里填 school_start(读一年级的年月,如 2025-09),老师才知道现在是几年级哪个学期;想用自己的 Obsidian 库,改 cotutor.json 的 paths.vault');
-    suggestions.push('cotutor serve 起服务,在这台电脑上打开家长端 /parent 的「首页」,填百炼的按量 API Key 与业务空间 ID(老师的嘴和脑都用它;没填孩子端只出「老师们还没到」)');
-    suggestions.push('在 iPad / iPhone 上用:cotutor cert 签证书(要 mkcert),根证书装到设备上并打开信任,步骤见 README 里的《iPad 与 iPhone》');
-    suggestions.push('可选:点读、单词卡的配音用百炼(和老师的嘴同一把 key),到工作台 /dev 的「音色」页给老师挑声音;cotutor pin 给家长端与工作台加锁');
+    suggestions.push('cotutor service install 装成后台服务(登录后自己起来、关了终端照样跑;在终端里调试用 cotutor serve),cotutor open 打开家长端,在「首页」填百炼的按量 API Key 与业务空间 ID(老师的嘴和脑都用它;没填孩子端只出「老师们还没到」)');
+    suggestions.push('在平板、手机上用:cotutor cert 签证书(要 mkcert),根证书装到设备上并打开信任,iPad / iPhone 的步骤见 README 里的《iPad 与 iPhone》');
+    suggestions.push('可选:点读、单词卡的配音用百炼(和老师的嘴同一把 key),到家长端首页点老师的「样子与声音」挑声音;cotutor pin 给家长端与工作台加锁');
     suggestions.push('cotutor doctor 逐项体检');
     return { root, steps, suggestions };
 }