cotutor 0.3.0 → 0.4.1

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";
@@ -26,15 +25,23 @@ import { parseTimetable } from "../../memory/timetable.js";
 import { configGapsOf, legacyLayout } from "./migrate.js";
 import { httpsFiles } from "./serve.js";
 import { readPin } from "../http/access.js";
+import { BUILD } from "../build.js";
+import { isNewer, upgradeSteps } from "../../shared/upgrade.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 = '只回一个字:好';
+/** 每条不过的要么能跑(cmd)要么要人来(human),没有第三种:新加的检查项忘了写 cmd,也只是交给人,不会让 agent 瞎猜 */
+function finish(report) {
+    for (const c of report.checks) {
+        if (c.ok)
+            delete c.cmd;
+        else if (!c.cmd)
+            c.human = true;
+    }
+    return report;
+}
 async function statOrNull(p) {
     return stat(p).catch(() => null);
 }
@@ -46,113 +53,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 +76,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;
@@ -188,9 +101,14 @@ export async function doctorWorkspace(override, opts = {}) {
             detail: err.message,
             fix: err instanceof ConfigError ? `修复 ${redactHome(err.file)} 的 JSON,或删掉它` : 'cotutor init <slug>,或用 --workspace / COTUTOR_WORKSPACE 指定',
         });
-        return { ok: false, root: null, source: null, checks };
+        return finish({ ok: false, root: null, source: null, checks });
     }
     push({ name: 'workspace', ok: true, required: true, detail: `${redactHome(root)}(来源:${source})` });
+    // cmd 要能照原样跑:体检时用 --workspace 指的,修的时候也得指
+    // 路径写 $HOME/…,和别的字段一样:用户名不传给 agent 的厂商;redactDeep 只换开头,管不到命令中间的路径;sh 与 PowerShell 都展开
+    const quoted = `"${redactHome(root)}"`;
+    const flag = source === 'flag' ? ` --workspace ${quoted}` : '';
+    const upgrade = `cotutor upgrade${flag}`;
     // ---- cotutor.json ----
     let ws = null;
     const configFile = join(root, CONFIG_FILE);
@@ -216,12 +134,20 @@ export async function doctorWorkspace(override, opts = {}) {
         push({ name: CONFIG_FILE, ok: false, required: true, detail: err.message, fix: '按上面逐条修;政策文件机器不重建,改坏了靠 git 回退' });
     }
     let teachingPack = null;
+    // 补缺的 init:slug 从配置来;年级照已装的写(init 不切换年级);建在缺省位置的不用写 --dir
+    const initCmd = () => {
+        if (!ws)
+            return undefined;
+        const slug = ws.config.kid.slug;
+        const grade = teachingPack ? ` --grade ${teachingPack.grade}` : '';
+        return `cotutor init ${slug}${grade}${root === join(homedir(), 'cotutor', slug) ? '' : ` --dir ${quoted}`}`;
+    };
     try {
         const manifest = await readManifest(root);
         teachingPack = await workspaceGradePack(root);
         push({ name: 'teachingPack', ok: true, required: true, detail: `${teachingPack.grade} 年级教学包 · ${redactHome(teachingPack.dir)}` });
         if (!manifest.teachingPack)
-            push({ name: 'teachingPack.origin', ok: false, required: false, detail: '旧版出厂内容按二年级来源读取,尚未补记;孩子档案不变', fix: 'cotutor upgrade 补记来源,保留自定义文件与原 hash' });
+            push({ name: 'teachingPack.origin', ok: false, required: false, detail: '旧版出厂内容按二年级来源读取,尚未补记;孩子档案不变', fix: 'cotutor upgrade 补记来源,保留自定义文件与原 hash', cmd: upgrade });
     }
     catch (err) {
         push({ name: 'teachingPack', ok: false, required: true, detail: err.message, fix: '检查 .cotutor/shipped.json 的 teachingPack 与本包 grades/;恢复原来源记录或安装包含该年级的版本,不要改成其他年级绕过' });
@@ -235,6 +161,7 @@ export async function doctorWorkspace(override, opts = {}) {
             required: false,
             detail: gaps.length ? `${gaps.length} 项要改:${gaps.map((g) => g.detail).join(';')}` : 'cotutor.json 有出厂模板里的全部老师、运行时与旗标,也没有不再用的段',
             fix: gaps.length ? 'cotutor upgrade --config --dry-run 先看,再 cotutor upgrade --config 改(只加缺的、删不再用的出厂段,你改过的值不动)' : undefined,
+            cmd: gaps.length ? `cotutor upgrade --config${flag}` : undefined,
         });
     }
     // ---- 骨架 ----
@@ -248,17 +175,18 @@ export async function doctorWorkspace(override, opts = {}) {
         required: true,
         detail: missing.length ? `缺 ${missing.join(' ')}` : [...DIRS].map((d) => `${d}/`).join(' '),
         fix: missing.length ? `cotutor init <slug> --dir ${redactHome(root)}(幂等补缺)` : undefined,
+        cmd: missing.length ? initCmd() : undefined,
     });
     // 老布局(2026-10-30 之前):老师文件在 .claude/agents/、技能在 .claude/skills/,现在都读不到了
     const legacy = await legacyLayout(root);
     if (legacy.length)
-        push({ name: 'layout', ok: false, required: true, detail: `${legacy.join(' ')} 是老位置:老师文件现在在 agents/<老师>.md,技能在 ${SKILLS_DIR}/`, fix: 'cotutor upgrade(原样挪过去,不改内容;新位置已有同名的不挪、会点名)' });
+        push({ name: 'layout', ok: false, required: true, detail: `${legacy.join(' ')} 是老位置:老师文件现在在 agents/<老师>.md,技能在 ${SKILLS_DIR}/`, fix: 'cotutor upgrade(原样挪过去,不改内容;新位置已有同名的不挪、会点名)', cmd: upgrade });
     // 家规(根的 QWEN.md)2026-09-15 起不出厂:有就是家长自建的共同规矩,提一句;没有不缺
     const rulesThere = (await Promise.all(['QWEN.md'].map(async (f) => ((await statOrNull(join(root, f))) ? f : null)))).filter(Boolean);
     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);
@@ -283,6 +211,7 @@ export async function doctorWorkspace(override, opts = {}) {
                     : shipped
                         ? `cotutor init 补拷(拷自本包 agents/${name}.md),或把老师键改成文件里的 name`
                         : `这是自家加的老师:写 agents/${name}.md(frontmatter name: ${name}),cotutor add ${name} --display <显示名> 可出模板;或把 cotutor.json 里这条删掉`,
+                cmd: !ok && shipped ? initCmd() : undefined,
             });
             const st = statuses.get(name);
             if (!st)
@@ -295,15 +224,16 @@ export async function doctorWorkspace(override, opts = {}) {
                     required: false,
                     detail: label[st.state],
                     fix: st.state === 'upgradable' ? 'cotutor upgrade 换新版' : undefined,
+                    cmd: st.state === 'upgradable' ? upgrade : undefined,
                 });
             }
             const home = join(ws.dirs.agents, name);
             const there = (await statOrNull(home))?.isDirectory() ?? false;
-            push({ name: `tutor.${name}.home`, ok: there, required: true, detail: there ? `agents/${name}/ 在(会话 cwd)` : `agents/${name}/ 不在`, fix: there ? undefined : 'cotutor init 补建' });
+            push({ name: `tutor.${name}.home`, ok: there, required: true, detail: there ? `agents/${name}/ 在(会话 cwd)` : `agents/${name}/ 不在`, fix: there ? undefined : 'cotutor init 补建', cmd: there ? undefined : initCmd() });
             // 音色:一老师一音色走 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 +247,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,15 +284,15 @@ 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 ? '缺(机器件,老师或家长的技能靠它)' : '缺' };
-                push({ name: `skill.${sk.name}`, ok: sk.state !== 'missing' && sk.state !== 'upgradable', required: Boolean(sk.machine), detail: `${SKILLS_DIR}/${sk.name}/:${label[sk.state]}`, fix: sk.state === 'missing' ? 'cotutor init 补拷' : sk.state === 'upgradable' ? 'cotutor upgrade 换新版' : undefined });
+                push({ name: `skill.${sk.name}`, ok: sk.state !== 'missing' && sk.state !== 'upgradable', required: Boolean(sk.machine), detail: `${SKILLS_DIR}/${sk.name}/:${label[sk.state]}`, fix: sk.state === 'missing' ? 'cotutor init 补拷' : sk.state === 'upgradable' ? 'cotutor upgrade 换新版' : undefined, cmd: sk.state === 'missing' ? initCmd() : sk.state === 'upgradable' ? upgrade : undefined });
             }
             // Claude Code 只认 .claude/skills:那里该是指向 .agents/skills 的链;老师用不到,家长在 workspace 里用 Claude Code 才要
             const linked = (await lstat(join(root, CLAUDE_SKILLS_LINK)).catch(() => null))?.isSymbolicLink() ?? false;
-            push({ name: 'skills.claude', ok: linked, required: false, detail: linked ? `${CLAUDE_SKILLS_LINK} 链到 ${SKILLS_DIR}(Claude Code 读的是同一份)` : `${CLAUDE_SKILLS_LINK} 不是链,在 workspace 里用 Claude Code 看不到 ${SKILLS_DIR}/ 的技能`, fix: linked ? undefined : 'cotutor upgrade 建链(是实体目录的话先把里面的挪进 .agents/skills/ 再删掉)' });
+            push({ name: 'skills.claude', ok: linked, required: false, detail: linked ? `${CLAUDE_SKILLS_LINK} 链到 ${SKILLS_DIR}(Claude Code 读的是同一份)` : `${CLAUDE_SKILLS_LINK} 不是链,在 workspace 里用 Claude Code 看不到 ${SKILLS_DIR}/ 的技能`, fix: linked ? undefined : 'cotutor upgrade 建链(是实体目录的话先把里面的挪进 .agents/skills/ 再删掉)', cmd: linked ? undefined : upgrade });
             // ---- activity:老师的家里 agents/<老师>/activities/<名>.md;出厂的看新旧,每份都过一遍 activity check ----
             {
                 const { activityStatuses, checkActivities } = await import("./activities.js");
@@ -340,7 +300,7 @@ export async function doctorWorkspace(override, opts = {}) {
                 const label = { latest: '出厂件,最新', upgradable: '出厂件,包已更新', custom: '自定义', untracked: '自定义(没有出厂记录)', missing: '缺', broken: '读不到' };
                 for (const s of states.values())
                     if (s.state === 'missing')
-                        push({ name: `activity.${s.key}`, ok: false, required: false, detail: `agents/${s.key.replace('/', '/activities/')}.md 不在`, fix: 'cotutor init 补拷' });
+                        push({ name: `activity.${s.key}`, ok: false, required: false, detail: `agents/${s.key.replace('/', '/activities/')}.md 不在`, fix: 'cotutor init 补拷', cmd: initCmd() });
                 // 学科色:手改 cotutor.json 写的颜色,新话题气泡的白字要压得住
                 for (const [name, t] of Object.entries(ws.config.tutors)) {
                     if (!t.color)
@@ -364,6 +324,7 @@ export async function doctorWorkspace(override, opts = {}) {
                         required: false,
                         detail: fixes.length ? `${origin};${fixes.length} 条要改,第一条:${fixes[0].line ? `第 ${fixes[0].line} 行 ` : ''}${fixes[0].text}` : origin,
                         fix: fixes.length ? `cotutor activity check ${r.tutor} ${r.name} 看全` : st?.state === 'upgradable' ? 'cotutor upgrade 换新版' : undefined,
+                        cmd: !fixes.length && st?.state === 'upgradable' ? upgrade : undefined,
                     });
                 }
             }
@@ -377,7 +338,7 @@ export async function doctorWorkspace(override, opts = {}) {
                     push({ name: 'theme.manifest', ok: true, required: false, detail: `themes/${name}/:${Object.keys(t.manifest.tints).length} 个底色槽、${Object.keys(t.manifest.looks).length} 个字形槽、${Object.keys(t.manifest.pens).length} 支笔,default = ${t.manifest.default}` });
                 }
                 catch (err) {
-                    push({ name: 'theme.manifest', ok: false, required: false, detail: `themes/${name}/ 用不了(服务退回出厂 default):${err instanceof Error ? err.message : String(err)}`, fix: name === 'default' ? 'cotutor init 补拷(已有的不动)或 cotutor upgrade' : `修 themes/${name}/theme.json 与 kid.css,或把 cotutor.json 的 kid.theme 改回 default` });
+                    push({ name: 'theme.manifest', ok: false, required: false, detail: `themes/${name}/ 用不了(服务退回出厂 default):${err instanceof Error ? err.message : String(err)}`, fix: name === 'default' ? 'cotutor init 补拷(已有的不动)或 cotutor upgrade' : `修 themes/${name}/theme.json 与 kid.css,或把 cotutor.json 的 kid.theme 改回 default`, cmd: name === 'default' ? initCmd() : undefined });
                 }
                 for (const th of teachingPack ? await themeStatuses(root) : []) {
                     if (!th.shipped) {
@@ -385,7 +346,7 @@ export async function doctorWorkspace(override, opts = {}) {
                         continue;
                     }
                     const label = { latest: '出厂件,最新', upgradable: `出厂件,基于 ${th.basedOn},包已更新`, custom: `自定义(基于 ${th.basedOn})`, untracked: '自定义(没有出厂记录)', missing: '缺' };
-                    push({ name: `theme.${th.name}.origin`, ok: th.state !== 'missing' && th.state !== 'upgradable', required: false, detail: `themes/${th.name}/:${label[th.state]}`, fix: th.state === 'missing' ? 'cotutor init 补拷' : th.state === 'upgradable' ? 'cotutor upgrade 换新版' : undefined });
+                    push({ name: `theme.${th.name}.origin`, ok: th.state !== 'missing' && th.state !== 'upgradable', required: false, detail: `themes/${th.name}/:${label[th.state]}`, fix: th.state === 'missing' ? 'cotutor init 补拷' : th.state === 'upgradable' ? 'cotutor upgrade 换新版' : undefined, cmd: th.state === 'missing' ? initCmd() : th.state === 'upgradable' ? upgrade : undefined });
                 }
             }
         }
@@ -508,36 +469,24 @@ 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, mkcertReady } = await import("./cert.js");
+        // mkcert -install 要开机密码或点弹窗,是人的事;做过了,签证书就不用人了
+        const canSign = !tls && probeEnv && await mkcertReady();
+        push({ name: 'https', ok: tls !== null, required: false, detail: tls ? `${redactHome(tls.cert)}` : '没有证书,serve 走 HTTP(平板、手机上按住说话不可用)', fix: tls ? undefined : `cotutor cert(需要 mkcert:${mkcertHint()}),签完 cotutor service restart`, cmd: canSign ? 'cotutor cert' : undefined });
         // ---- 百炼:老师靠实时模型开口,没配孩子端打不开;--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 +501,72 @@ 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))
-                    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` });
+                if (runtime === 'default' || typeof p === 'string' || !isApiRuntime(p))
                     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', cmd: t.installed ? undefined : 'cotutor tray on' });
+            }
+        }
+        if (!s)
+            push({ name: 'service', ok: false, required: false, detail: '没装后台服务:在终端里跑的 cotutor serve,关了终端就停', fix: 'cotutor service install(登录后自己起来、崩了自己再起)', cmd: `cotutor service install --no-open${flag}` });
+        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, cmd: gone.length ? `cotutor service install${flag}` : 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 : '设置 › 系统 › 电源和电池 › 屏幕、睡眠和休眠超时,「插入电源时,使设备在以下时间后进入睡眠状态」选「从不」;合盖看「电源按钮和盖子」那一项' });
+    }
+    // ---- 有没有新版本:只看服务问来存下的那份,体检不上网;什么时候升级家长定(要重起服务,孩子可能在上课),所以没有 cmd ----
+    {
+        const { readUpdateRecord } = await import("../machine/update.js");
+        const u = await readUpdateRecord();
+        if (!u.off && isNewer(u.latest, BUILD.version))
+            push({ name: 'update', ok: false, required: false, detail: `有新版本 ${u.latest}(现在是 ${BUILD.version})`, fix: `挑孩子不用的时候,依次运行:${upgradeSteps().join(' ; ')}` });
+    }
     // ---- 用户配置 ----
     try {
         const text = await readFile(USER_CONFIG, 'utf8');
@@ -611,7 +581,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:老师记忆、账本、政策都是不可再生状态' });
-    return { ok: checks.filter((c) => c.required).every((c) => c.ok), root, source, checks };
+    // 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:老师记忆、账本、政策都是不可再生状态', cmd: gitThere ? undefined : `git init ${quoted}` });
+    }
+    return finish({ 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>;