cotutor 0.3.0 → 0.4.1

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