cotutor 0.4.3 → 0.4.4

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# 更新说明
+
+写给家长：每个版本改了什么。升级跑 `cotutor update`（Windows 上 `cotutor.cmd update`），详见 README 的「数据与升级」。
+
+## 0.4.4
+
+- 装得快多了:安装从 275 个包变成 15 个,Windows 上第一次装从 3 分钟左右变成 1 分钟左右
+- 平板第一次用:在家长端「扫码打开」点「装证书」,用平板相机扫一下就能装根证书
+- 电脑关了或睡着时,孩子在平板上打开看到「老师们还没到」,不再是浏览器的报错;电脑好了自己回来
+- 有了一行安装命令(Mac、Windows 都有),README 里也写了怎么卸载
+
+## 0.4.3
+
+- 自动备份:服务开着时每天一份,升级前一份,可以恢复;录音占地方,不在备份里
+- 家长端首页多了「还差几步」,第一次打开就知道接下来做什么;选一下年级老师就知道孩子上几年级
+- 遇到问题时,家长端「设置」能生成诊断信息,不含孩子的对话和 key,先看再发
+- `cotutor init --grade` 自动算好学期,`cotutor doctor --fix` 一次修掉能自动修的
+
+## 0.4.2
+
+- 百炼欠费、key 失效或连不上时,图标和家长端会说清楚,孩子那边会请爸爸妈妈来看,不再一直转
+- 升级只要一条命令 cotutor update,几个孩子一次升好,孩子在通话时不动
+- 用 Homebrew 装 Node 的电脑:Node 升级后服务和图标不会再起不来
+- 有新版本时能直接看到这次改了什么
+
+## 0.4.1
+
+- 有新版本时,图标菜单和家长端首页会提醒,孩子端不说,也不会自动升级
+- 第一次装好后台服务时自动打开家长端
+- 升级后图标不再误报“要重启”
+- Windows 上给家长看的命令带 `.cmd`,新电脑的 PowerShell 不会拦
+- `cotutor cert` 发现这台电脑没信任根证书时会提醒
+- 新增 `INSTALL.md`:可以让 AI 助手照着替你安装
+
+## 0.4.0
+
+- 后台服务 `cotutor service`:登录后自己起来,崩了自己再起,关了终端照样跑
+- 菜单栏(任务栏)图标 `cotutor tray`:不开终端也能看状态、打开家长端、重启
+- 端口只在 `init` 时选一次,以后不变;地址认电脑名,换网络不用重扫

package/README.md

@@ -12,7 +12,21 @@
 请阅读 https://raw.githubusercontent.com/TarsLab/cotutor/main/INSTALL.md ,照着在这台电脑上安装 cotutor
 ```
 
-**自己装:** 需要一台电脑(Mac 最省事)、Node ≥ 22.18,和一个百炼账号(北京地域,按量付费)。老师的嘴和脑都走百炼,由应用直接调用,不用另装模型客户端:嘴是 `qwen3.8-omni-flash-realtime`,听孩子说、照着讲稿念;脑是 `qwen3.8-max`,写讲稿和板书。
+**自己装:** 需要一台电脑(Mac 最省事)、[Node.js](https://nodejs.org) ≥ 22.18(装 LTS 版),和一个百炼账号(北京地域,按量付费)。老师的嘴和脑都走百炼,由应用直接调用,不用另装模型客户端:嘴是 `qwen3.8-omni-flash-realtime`,听孩子说、照着讲稿念;脑是 `qwen3.8-max`,写讲稿和板书。
+
+一行装好(会查 Node 的版本、连不上 npm 就用国内镜像;不用 sudo、不改系统设置)。最后那三个是孩子的短名(小写字母,不用真名)、称呼、年级,不写就只装程序:
+
+```sh
+# Mac(终端里)
+curl -fsSL https://raw.githubusercontent.com/TarsLab/cotutor/main/install.sh | sh -s -- ming 小明 2
+```
+
+```powershell
+# Windows(PowerShell 里)
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/TarsLab/cotutor/main/install.ps1))) ming 小明 2
+```
+
+连不上 GitHub 就把地址换成 `https://cdn.jsdelivr.net/npm/cotutor@latest/install.sh`(Windows 是 `install.ps1`)。也可以一条条自己来:
 
 ```sh
 npm i -g cotutor
@@ -162,6 +176,23 @@ cotutor send math-tutor 你好 --sandbox
 cotutor serve --sandbox --fresh       # 丢掉试过的,从真 workspace 重新分(真的那边改了老师文件、vault 也用这个带过来)
 ```
 
+## 卸载
+
+孩子的文件夹(`~/cotutor/<孩子>/`)和备份(`~/cotutor/.backups/`)是家里的记录,删了找不回来,卸载程序不会碰它们;真不要了自己删。Windows 上命令写成 `cotutor.cmd`、`npm.cmd`。
+
+```sh
+cotutor service uninstall --workspace ~/cotutor/<孩子>   # 每个孩子一次;最后一个卸掉时,菜单栏(任务栏)图标也一起卸
+npm rm -g cotutor
+```
+
+还留在电脑上的,不要了可以删:
+
+- `~/.config/cotutor/`:百炼的 key、证书、家长端密码、几项设置
+- 日志:Mac 在 `~/Library/Logs/cotutor/`,Windows 在 `%LOCALAPPDATA%\cotutor\`(里面还有图标的文件),Linux 在 `~/.local/state/cotutor/`;Mac 的图标文件在 `~/Library/Application Support/cotutor/`
+- 签证书时装的根证书:跑 `mkcert -uninstall` 从这台电脑的信任里拿掉,再删 `mkcert -CAROOT` 说的那个目录
+- 平板上:设置 › 通用 › VPN 与设备管理里删掉那个描述文件,主屏幕上的图标长按删掉
+- Windows 防火墙里给 Node.js 开的「允许」:Windows 安全中心 › 防火墙和网络保护 › 允许应用通过防火墙,别的程序也用 Node.js 时留着
+
 ## 开发
 
 ```sh

package/dist/app/cli/root-ca.d.ts

@@ -0,0 +1,8 @@
+export declare const ROOT_CA = "rootCA.pem";
+export declare function defaultCaRoot(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv, home?: string): string;
+export declare function rootCaFile(o?: {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    home?: string;
+    askMkcert?: () => Promise<string>;
+}): Promise<string | null>;

package/dist/app/cli/root-ca.js

@@ -0,0 +1,33 @@
+/**
+ * 根证书(mkcert 的 rootCA.pem,公钥)在哪:平板扫码装证书时从这里给(serve.ts 的 http 那一面,GET /ca.crt)。
+ * 只认 rootCA.pem;同目录的 rootCA-key.pem 是私钥,永远不读、不给。
+ * 先看 CAROOT 环境变量和 mkcert 的缺省目录(后台服务的 PATH 里不一定有 mkcert),都没有再问 mkcert -CAROOT。
+ */
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+const execFileP = promisify(execFile);
+export const ROOT_CA = 'rootCA.pem';
+export function defaultCaRoot(platform = process.platform, env = process.env, home = homedir()) {
+    if (platform === 'darwin')
+        return join(home, 'Library', 'Application Support', 'mkcert');
+    if (platform === 'win32')
+        return join(env.LOCALAPPDATA || join(home, 'AppData', 'Local'), 'mkcert');
+    return join(env.XDG_DATA_HOME || join(home, '.local', 'share'), 'mkcert');
+}
+export async function rootCaFile(o = {}) {
+    const env = o.env ?? process.env;
+    for (const dir of [env.CAROOT, defaultCaRoot(o.platform, env, o.home)]) {
+        if (dir && existsSync(join(dir, ROOT_CA)))
+            return join(dir, ROOT_CA);
+    }
+    try {
+        const dir = await (o.askMkcert ?? (async () => (await execFileP('mkcert', ['-CAROOT'], { timeout: 5000, env })).stdout.trim()))();
+        if (dir && existsSync(join(dir, ROOT_CA)))
+            return join(dir, ROOT_CA);
+    }
+    catch { /* 没装 mkcert */ }
+    return null;
+}

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

@@ -1,4 +1,5 @@
-import { type Server } from 'node:http';
+import { type RequestListener, type Server } from 'node:http';
+import { type Server as NetServer } from 'node:net';
 import { siteUrl } from '../../shared/site-url.ts';
 import type { ListenInfo } from '../../ui/parent/qr-page.ts';
 import { type AppContext } from '../http/app.ts';
@@ -14,7 +15,8 @@ export interface ServeOptions extends ResolveOptions {
     awake?: boolean;
 }
 export interface ServeResult {
-    server: Server;
+    /** 用 https 时是前面那层(同一个端口分给 https 和 http);不用 https 就是 http 服务本身 */
+    server: NetServer;
     ctx: AppContext;
     ws: Workspace;
     port: number;
@@ -42,6 +44,13 @@ export declare function localName(name?: string): string;
 export declare function certCovers(certFile: string, host: string): boolean;
 /** 扫码页要的三样;listen 之后才知道真端口 */
 export declare function listenInfo(https: boolean, port: number): ListenInfo;
+/**
+ * 用 https 时 http 那一面只做两件事:给根证书(平板扫码装证书,这时还不信任 https,所以走 http)、别的都跳到 https
+ * (切到 https 以前开着的页面、旧书签、手输的 http 地址)。只给 rootCA.pem,私钥永远不给;找不到就说怎么弄。
+ */
+export declare function plainHandler(caFile: () => string | null): RequestListener;
+/** 同一个端口既认 https 又认 http:看第一个字节,TLS 握手(0x16)交给 https,别的交给 http 那一面 */
+export declare function httpAndHttps(secure: Server, plain: Server): NetServer;
 export declare function serveWorkspace(opts?: ServeOptions): Promise<ServeResult>;
 /**
  * busy() 为真就起一个拦闲置睡眠的子进程,为假就停;serve 没了它自己退:macOS 是 caffeinate -i -w <pid>,Windows 是一段 PowerShell(service-windows.ts 的 awakeScript);Linux 什么都不做。

package/dist/app/cli/serve.js

@@ -7,9 +7,11 @@
  */
 import { execFileSync, spawn } from 'node:child_process';
 import { X509Certificate } from 'node:crypto';
-import { readFileSync } from 'node:fs';
+import { createReadStream, existsSync, readFileSync } from 'node:fs';
 import { createServer as createHttp } from 'node:http';
 import { createServer as createHttps } from 'node:https';
+import { createServer as createNetServer } from 'node:net';
+import { rootCaFile } from "./root-ca.js";
 import { hostname, networkInterfaces } from 'node:os';
 import { join } from 'node:path';
 import { siteUrl } from "../../shared/site-url.js";
@@ -91,6 +93,47 @@ export function listenInfo(https, port) {
     const ip = lanAddresses()[0];
     return { name: siteUrl(scheme, localName(), port), ip: ip ? siteUrl(scheme, ip, port) : null, https };
 }
+/**
+ * 用 https 时 http 那一面只做两件事:给根证书(平板扫码装证书,这时还不信任 https,所以走 http)、别的都跳到 https
+ * (切到 https 以前开着的页面、旧书签、手输的 http 地址)。只给 rootCA.pem,私钥永远不给;找不到就说怎么弄。
+ */
+export function plainHandler(caFile) {
+    return (req, res) => {
+        const path = (req.url ?? '/').split('?')[0];
+        if (req.method === 'GET' && (path === '/ca.crt' || path === '/ca')) {
+            const file = caFile();
+            if (file && existsSync(file)) {
+                res.writeHead(200, { 'content-type': 'application/x-x509-ca-cert', 'content-disposition': 'attachment; filename="cotutor-ca.crt"', 'cache-control': 'no-store' });
+                createReadStream(file).pipe(res);
+                return;
+            }
+            res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+            res.end('这台电脑上没找到根证书:先在电脑上跑 mkcert -install 和 cotutor cert');
+            return;
+        }
+        res.writeHead(301, { location: `https://${req.headers.host ?? 'localhost'}${req.url ?? '/'}`, 'cache-control': 'no-store' });
+        res.end();
+    };
+}
+/** 同一个端口既认 https 又认 http:看第一个字节,TLS 握手(0x16)交给 https,别的交给 http 那一面 */
+export function httpAndHttps(secure, plain) {
+    const front = createNetServer((sock) => {
+        sock.on('error', () => undefined);
+        sock.once('data', (first) => {
+            sock.pause();
+            sock.unshift(first);
+            (first[0] === 0x16 ? secure : plain).emit('connection', sock);
+            process.nextTick(() => sock.resume());
+        });
+    });
+    front.once('close', () => {
+        for (const s of [secure, plain]) {
+            s.close();
+            s.closeAllConnections();
+        }
+    });
+    return front;
+}
 export async function serveWorkspace(opts = {}) {
     const ws = loadWorkspace(opts.workspace, opts);
     // 不探 CLI(起服务不用等它);防火墙要查:平板连不上时这里是家长唯一看得到提醒的地方
@@ -101,10 +144,13 @@ export async function serveWorkspace(opts = {}) {
     ctx.openCalls = () => liveUpgrade.openCalls();
     const handler = createHandler(ctx);
     const tls = opts.http ? null : httpsFiles(ws);
-    const server = tls ? createHttps({ cert: readFileSync(tls.cert), key: readFileSync(tls.key) }, handler) : createHttp(handler);
+    const app = tls ? createHttps({ cert: readFileSync(tls.cert), key: readFileSync(tls.key) }, handler) : createHttp(handler);
     // WebSocket:实时老师的那条线(src/app/ws/);不认就关掉
-    server.on('upgrade', (req, socket, head) => { void liveUpgrade(req, socket, head, ctx).then((took) => { if (!took)
+    app.on('upgrade', (req, socket, head) => { void liveUpgrade(req, socket, head, ctx).then((took) => { if (!took)
         socket.destroy(); }, () => socket.destroy()); });
+    // 用 https 时同一个端口也认 http(给平板装根证书、把 http 的跳过去)
+    const caFile = tls ? await rootCaFile() : null;
+    const server = tls ? httpAndHttps(app, createHttp(plainHandler(() => caFile))) : app;
     // 别的程序只占着 127.0.0.1 时,绑通配地址照样成功:平板连到这边,这台电脑上开 localhost 却到了别的程序。先问一声,当被占处理(main.ts 接)
     if (port !== 0 && (await answersLocally(port)))
         throw Object.assign(new Error(`port ${port} answers on 127.0.0.1`), { code: 'EADDRINUSE', port });

package/dist/app/http/access.js

@@ -23,7 +23,7 @@ export const PIN_RE = /^\d{4,8}$/;
 const MAX_FAILS = 5;
 const LOCK_MS = 60_000;
 /** 孩子端的路径:设了 PIN 也开;别的都要凭证。改孩子端加了新接口要来这里登记(tests/access.test.ts 盯着孩子端页面源码里用到的每条) */
-const KID_EXACT = new Set(['/', '/manifest.webmanifest', '/favicon.svg', '/favicon-32.png', '/favicon.ico', '/api/health', '/api/auth', '/dictation', '/dictation/', '/talk', '/talk/', '/api/dictation', '/api/talk']);
+const KID_EXACT = new Set(['/', '/sw.js', '/manifest.webmanifest', '/favicon.svg', '/favicon-32.png', '/favicon.ico', '/api/health', '/api/auth', '/dictation', '/dictation/', '/talk', '/talk/', '/api/dictation', '/api/talk']);
 const KID_PREFIX = ['/kid/', '/stage/', '/api/kid/', '/api/audio/', '/api/bundles/', '/api/dictation/', '/api/talk/', '/api/live/'];
 export function isKidPath(p) {
     return KID_EXACT.has(p) || KID_PREFIX.some((x) => p.startsWith(x)) || /^\/icon-\d{2,4}\.png$/.test(p);

package/dist/app/http/app.js

@@ -37,6 +37,7 @@ import { knownLatest, knownNotes } from "../machine/update.js";
 import { isNewer } from "../../shared/upgrade.js";
 import { qrPage } from "../../ui/parent/qr-page.js";
 import { kidPage } from "../../ui/kid/kid-page.js";
+import { KID_SW_JS } from "../../ui/kid/offline-sw.js";
 import { parentPage } from "../../ui/parent/parent-page.js";
 import { kidHomeView } from "../../runtime/home/store.js";
 import { photosOf } from "../../runtime/kid-input.js";
@@ -1070,6 +1071,9 @@ export async function route(method, path, ctx, body, who = 'local', client = {})
         // 主屏幕(iPad「添加到主屏幕」):清单与图标都按标题现生成,没有静态资源
         if (p === '/manifest.webmanifest')
             return { status: 200, json: webManifest(ws.config.title), contentType: 'application/manifest+json; charset=utf-8' };
+        // 孩子端的离线页(offline-sw.ts):平板打开时电脑关了、睡着了,给「老师们还没到」,不给浏览器的报错
+        if (p === '/sw.js')
+            return { status: 200, body: Buffer.from(KID_SW_JS), contentType: 'text/javascript; charset=utf-8', cacheControl: 'no-cache' };
         const icon = /^\/icon-(\d{2,4})\.png$/.exec(p);
         if (icon) {
             const n = Number(icon[1]);

package/dist/app/http/parent-home.js

@@ -26,6 +26,7 @@ import { shownAvatar } from "./avatars.js";
 import { qrNotes, qrSvg } from "../../ui/shared/qr-svg.js";
 import { readDevices } from "../../runtime/journal/kid-log.js";
 import { parentSetupRoute } from "./parent-setup.js";
+import { rootCaFile } from "../cli/root-ca.js";
 const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
 const bad = (message) => ({ status: 400, json: { error: 'bad_request', message } });
 /** 家长端列的老师:有脸的(-tutor 结尾)、开着的;藏着的也列(家长要能把他放回首页) */
@@ -154,9 +155,13 @@ async function kidQr(ctx) {
     const devices = Object.values(await readDevices(ctx.ws));
     const last = devices.map((d) => d.last).sort().at(-1) ?? null;
     const parent = { url: `${info.name}parent`, ip: info.ip ? `${info.ip}parent` : null };
+    // 装根证书:走同一个端口的 http 那一面(serve.ts 的 plainHandler),平板这时还不信任 https;端口照写,http 缺省是 80
+    const caUrl = (u) => { const x = new URL(u); return `http://${x.hostname}:${x.port || '443'}/ca.crt`; };
+    const ca = info.https && (await rootCaFile()) ? { url: caUrl(info.name), ip: info.ip ? caUrl(info.ip) : null } : null;
     return {
         ready: true, https: info.https, url: info.name, svg: qrSvg(info.name), ip: info.ip, svgIp: info.ip ? qrSvg(info.ip) : null,
         parent: { ...parent, svg: qrSvg(parent.url), svgIp: parent.ip ? qrSvg(parent.ip) : null },
+        ca: ca ? { ...ca, svg: qrSvg(ca.url), svgIp: ca.ip ? qrSvg(ca.ip) : null } : null,
         notes: qrNotes(info.https).slice(1), devices: devices.length, last,
     };
 }

package/dist/app/http/stage.js

@@ -1,6 +1,6 @@
 /**
- * 舞台包的静态文件:dist/stage/(esbuild 打的 stage.js / stage.css / index.html)+ /stage/fonts/(excalidraw 的字体:dist/stage/fonts/ 在就给它,
- * 不在从 node_modules 现取;部署包把字体拷进 dist/stage/fonts/、去掉 excalidraw 依赖,见 docs/wip/deploy/)。
+ * 舞台包的静态文件:dist/stage/(esbuild 打的 stage.js / stage.css / index.html)+ /stage/fonts/(excalidraw 的字体)。
+ * 字体由 build:stage 拷进 dist/stage/fonts/,npm 装的包里没有 excalidraw(它只在打包时用);开发时没打包就从 node_modules 现取。
  * serve 与 mock 共用;没打包(开发时没跑 pnpm run build:stage)→ null,页面开重卡舞台时什么都不出现,doctor 点名。
  */
 import { existsSync } from 'node:fs';

package/dist/app/mock/mock.js

@@ -74,6 +74,7 @@ import { kidThreads } from "../../runtime/kid-view.js";
 import { ICON_SIZES, appIconPng, webManifest } from "../../ui/shared/icon.js";
 import { faviconResponse } from "../../ui/shared/favicon.js";
 import { kidPage } from "../../ui/kid/kid-page.js";
+import { KID_SW_JS } from "../../ui/kid/offline-sw.js";
 import { parentPage } from "../../ui/parent/parent-page.js";
 import { arrangeHome, homeOwners, kidButtons, kidTiles, parseHome } from "../../runtime/home/home.js";
 import { packageTheme } from "../cli/themes.js";
@@ -644,6 +645,8 @@ export function createMock(opts = {}) {
             return { status: 200, html: VOICE_GALLERY_PAGE };
         if (p === '/manifest.webmanifest')
             return { status: 200, json: webManifest(title), contentType: 'application/manifest+json; charset=utf-8' };
+        if (p === '/sw.js')
+            return { status: 200, body: Buffer.from(KID_SW_JS), contentType: 'text/javascript; charset=utf-8', cacheControl: 'no-cache' };
         // 家长端「记录」:自己的一页(parent-page.ts);清单接口照真服务(答案不剥,第一节带一条给家长的尾巴与记忆)。mock 没有工作台 /dev
         if (p === '/parent')
             return { status: 200, html: parentPage(title) };