cotutor 0.2.0 → 0.4.0

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/grades.d.ts

@@ -0,0 +1,14 @@
+export declare const DEFAULT_GRADE = 2;
+/** 历史出厂内容永远归二年级,不能随未来新安装的默认年级变化。 */
+export declare const LEGACY_GRADE = 2;
+export declare const PACKAGE_GRADES_DIR: string;
+export interface GradePack {
+    grade: number;
+    dir: string;
+    agentsDir: string;
+}
+/** 不把任意字符串拼进路径。缺文件的包不算可安装。 */
+export declare function gradePacks(base?: string): Promise<GradePack[]>;
+export declare function requireGradePack(grade: number, base?: string): Promise<GradePack>;
+/** 没有来源字段的旧版内容来自现在的二年级包;不据此修改孩子档案。 */
+export declare function workspaceGradePack(root: string): Promise<GradePack>;

package/dist/app/cli/grades.js

@@ -0,0 +1,44 @@
+/** 年级包只负责出厂来源;运行时继续读 workspace 里的家长文件。 */
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readManifest } from "./shipped.js";
+import { UsageError } from "../workspace.js";
+export const DEFAULT_GRADE = 2;
+/** 历史出厂内容永远归二年级,不能随未来新安装的默认年级变化。 */
+export const LEGACY_GRADE = 2;
+export const PACKAGE_GRADES_DIR = fileURLToPath(new URL('../../../grades/', import.meta.url));
+/** 不把任意字符串拼进路径。缺文件的包不算可安装。 */
+export async function gradePacks(base = PACKAGE_GRADES_DIR) {
+    const entries = await readdir(base, { withFileTypes: true });
+    const packs = [];
+    for (const e of entries) {
+        const match = /^grade-([1-6])$/.exec(e.name);
+        if (!e.isDirectory() || !match)
+            continue;
+        const dir = join(base, e.name);
+        const agentsDir = join(dir, 'agents');
+        const required = ['chinese-tutor', 'math-tutor', 'english-tutor'];
+        if (!(await stat(join(dir, 'README.md')).catch(() => null))?.isFile())
+            continue;
+        if (!(await Promise.all(required.map(async (name) => (await stat(join(agentsDir, `${name}.md`)).catch(() => null))?.isFile()
+            && (await stat(join(agentsDir, name, 'activities')).catch(() => null))?.isDirectory()))).every(Boolean))
+            continue;
+        packs.push({ grade: Number(match[1]), dir, agentsDir });
+    }
+    return packs.sort((a, b) => a.grade - b.grade);
+}
+export async function requireGradePack(grade, base = PACKAGE_GRADES_DIR) {
+    if (!Number.isInteger(grade) || grade < 1 || grade > 6)
+        throw new UsageError('年级要是 1–6 的整数,如 --grade 2');
+    const packs = await gradePacks(base);
+    const pack = packs.find((p) => p.grade === grade);
+    if (!pack)
+        throw new UsageError(`本包没有完整的 ${grade} 年级教学包;可用年级:${packs.map((p) => p.grade).join('、') || '无'}。不会自动使用其他年级。`);
+    return pack;
+}
+/** 没有来源字段的旧版内容来自现在的二年级包;不据此修改孩子档案。 */
+export async function workspaceGradePack(root) {
+    const manifest = await readManifest(root);
+    return requireGradePack(manifest.teachingPack?.grade ?? LEGACY_GRADE);
+}

package/dist/{cli → app/cli}/init.d.ts

@@ -1,6 +1,6 @@
 export interface InitStep {
     item: string;
-    action: 'created' | 'exists' | 'kept' | 'replaced';
+    action: 'created' | 'exists' | 'kept' | 'replaced' | 'removed' | 'moved';
     note?: string;
 }
 export interface InitResult {
@@ -13,5 +13,7 @@ export interface InitOptions {
     dir?: string;
     name?: string;
     port?: number;
+    /** 出厂教学包年级,不是孩子档案的覆盖值。 */
+    grade?: number;
 }
 export declare function initWorkspace(opts: InitOptions): Promise<InitResult>;

package/dist/app/cli/init.js

@@ -0,0 +1,158 @@
+/**
+ * cotutor init <slug>:建 ~/cotutor/<slug>/ 骨架。语义是**幂等补缺**——已有的文件与目录一律不动,缺什么补什么。
+ * 三条边界(沿 drawtell init):政策文件只在缺失时写模板;用户配置只在还没指定 workspace 时补;不动 git。
+ * 老师文件**拷贝**进 agents/<name>.md:拷进来就是家长的,想改就改;出厂 hash 记 .cotutor/shipped.json,
+ * cotutor upgrade 据此换新或报 diff。老布局(.claude/agents、.claude/skills)先原样挪到新位置(migrate.ts 的 migrateLayout)。
+ */
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { DIRS, GITIGNORE, LEDGER_FILES, REFERENCE_README, configTemplate, profileTemplate, shippedAgents, writeSchemaFile } from "./skeleton.js";
+import { installTutors, readManifest, writeManifest } from "./tutors.js";
+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";
+async function exists(p) {
+    return (await stat(p).catch(() => null)) !== null;
+}
+export async function initWorkspace(opts) {
+    const root = opts.dir ? expandPath(opts.dir, resolve(process.cwd())) : join(HOME_ROOT, opts.slug);
+    const steps = [];
+    const manifest = await readManifest(root);
+    const installed = manifest.teachingPack?.grade;
+    const existing = await exists(join(root, CONFIG_FILE));
+    const grade = opts.grade ?? installed ?? (existing ? LEGACY_GRADE : DEFAULT_GRADE);
+    const pack = await requireGradePack(grade);
+    if (existing && grade !== (installed ?? LEGACY_GRADE))
+        throw new UsageError('init 只补缺,不能切换已有 workspace 的年级包;请另建 workspace,原有自定义文件和话题保持不动。');
+    if (installed !== undefined && installed !== grade)
+        throw new UsageError(`已安装 ${installed} 年级包,init 不切换年级`);
+    const agents = await shippedAgents(pack.agentsDir);
+    const rootExisted = await exists(root);
+    if (!rootExisted)
+        await mkdir(root, { recursive: true });
+    manifest.teachingPack = { grade };
+    await writeManifest(root, manifest);
+    steps.push({ item: 'teachingPack', action: installed === undefined ? 'created' : 'exists', note: `${grade} 年级教学包${existing && installed === undefined ? '(旧版来源补记,保留原 hash)' : opts.grade === undefined && installed === undefined ? '(默认)' : ''};孩子当前年级仍读档案` });
+    steps.push({ item: '.', action: rootExisted ? 'exists' : 'created' });
+    // 老布局先搬,再补缺:不然出厂件先占了新位置,家长改过的那份晾在老位置
+    steps.push(...(await migrateLayout(root)));
+    for (const dir of DIRS) {
+        const p = join(root, dir);
+        if (await exists(p)) {
+            steps.push({ item: `${dir}/`, action: 'exists' });
+            continue;
+        }
+        await mkdir(p, { recursive: true });
+        steps.push({ item: `${dir}/`, action: 'created' });
+    }
+    const config = join(root, CONFIG_FILE);
+    if (await exists(config))
+        steps.push({ item: CONFIG_FILE, action: 'kept', note: '政策文件不覆盖(家长的决定)' });
+    else {
+        // 端口只在这里选一次,写进文件以后不变(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 = [];
+    try {
+        const raw = readJson(config);
+        if (raw !== null)
+            tutorNames = Object.keys(parseConfig(raw, config).tutors);
+    }
+    catch (err) {
+        if (!(err instanceof ConfigError))
+            throw err;
+    }
+    steps.push(...(await installTutors(root, tutorNames)));
+    // 出厂 activity(老师的家里 agents/<老师>/activities/):缺的拷,有的不动
+    steps.push(...(await installActivities(root)));
+    const schemaThere = await exists(join(root, '.cotutor', 'cotutor.schema.json'));
+    await writeSchemaFile(root);
+    steps.push({ item: '.cotutor/cotutor.schema.json', action: schemaThere ? 'exists' : 'created', note: schemaThere ? '已按本包刷新(机器文件)' : 'cotutor.json 的 JSON Schema,编辑器补全用' });
+    // 出厂 skill(机器件 cotutor-board 等 + 做课包的四个 chalk-*)
+    steps.push(...(await installSkills(root)));
+    steps.push(await linkClaudeSkills(root));
+    // 出厂主题(孩子端板书的样子):拷进 themes/default/,是家长的
+    steps.push(...(await installThemes(root)));
+    for (const f of LEDGER_FILES) {
+        const p = join(root, f);
+        if (await exists(p))
+            steps.push({ item: f, action: 'exists' });
+        else {
+            await writeFile(p, '');
+            steps.push({ item: f, action: 'created' });
+        }
+    }
+    // vault 侧(《obsidian仓库设计.md》§2):只补档案与参考 README,缺了才写;档案按 cotutor: profile 找(2026-09-17),vault 里已有一篇就不补;
+    // 入口文件(每科每学期一篇)不自动建,doctor 提醒;日记由记账现建,计划家长自己写
+    try {
+        const ws = loadWorkspace(root);
+        const profile = ws.paths.profile;
+        const found = (await scanVault(ws)).notes.find((n) => n.props.cotutor === 'profile');
+        if (found)
+            steps.push({ item: redactHome(join(ws.paths.vault, found.path)), action: 'exists' });
+        else if (await exists(profile))
+            steps.push({ item: redactHome(profile), action: 'kept', note: '没有 cotutor: profile 属性,老师读不到;在 frontmatter 加上(cotutor doctor 有写法)' });
+        else {
+            await mkdir(dirname(profile), { recursive: true });
+            await writeFile(profile, profileTemplate(ws.config.kid.name ?? ws.config.kid.slug));
+            steps.push({ item: redactHome(profile), action: 'created', note: '档案:填 school_start 与孩子的情况,每个话题开头整篇进上下文包' });
+        }
+        const readme = join(ws.paths.reference, 'README.md');
+        if (await exists(readme))
+            steps.push({ item: redactHome(readme), action: 'exists' });
+        else {
+            await mkdir(ws.paths.reference, { recursive: true });
+            await writeFile(readme, REFERENCE_README);
+            steps.push({ item: redactHome(readme), action: 'created' });
+        }
+    }
+    catch {
+        /* 配置读不了(doctor 去体检):vault 侧不动 */
+    }
+    const gitignore = join(root, '.gitignore');
+    if (await exists(gitignore))
+        steps.push({ item: '.gitignore', action: 'kept' });
+    else {
+        await writeFile(gitignore, GITIGNORE);
+        steps.push({ item: '.gitignore', action: 'created' });
+    }
+    // 用户配置:补缺不改向;解析不了也不动(doctor 去体检)
+    let user = null;
+    let userBroken = false;
+    try {
+        user = JSON.parse(await readFile(USER_CONFIG, 'utf8'));
+    }
+    catch (err) {
+        userBroken = err.code !== 'ENOENT';
+    }
+    const configured = user && typeof user.workspace === 'string' && user.workspace ? user.workspace : null;
+    if (userBroken)
+        steps.push({ item: 'user-config', action: 'kept', note: '解析失败,未动(cotutor doctor 可体检)' });
+    else if (configured) {
+        steps.push(expandPath(configured, root) === root
+            ? { item: 'user-config', action: 'exists', note: '已指向本workspace' }
+            : { item: 'user-config', action: 'kept', note: '已指向别的workspace,未改;多孩子时一 workspace 一进程,用 --workspace / COTUTOR_WORKSPACE 指定' });
+    }
+    else {
+        await mkdir(dirname(USER_CONFIG), { recursive: true });
+        await writeFile(USER_CONFIG, `${JSON.stringify({ ...(user ?? {}), workspace: root }, null, 2)}\n`);
+        steps.push({ item: 'user-config', action: 'created', note: 'workspace 指向本workspace' });
+    }
+    const suggestions = [];
+    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 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 };
+}