cotutor 0.4.2 → 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
@@ -102,12 +116,23 @@ import { loadWorkspace } from 'cotutor/workspace';                        // 解
 
 百炼欠费、key 失效或这台电脑连不上百炼时,图标出橙点并通知,家长端首页说清楚是哪一种;要家长动手的那几种,孩子端显示「老师们还没到,叫爸爸妈妈来看一下」。处理好以后几分钟内自己恢复,也可以在家长端点「试连」。
 
-`cotutor doctor` 检查缺失配置并给修复建议;`--live` 会实际连接服务。页面上的老师起不来时,先看 doctor 和 `conversations/<老师>/<日期>.<job>.err.log`。家长端与工作台需要访问锁时,运行 `cotutor pin` 设置本机 PIN。
+`cotutor doctor` 检查缺失配置并给修复建议;`--fix` 把能自动修的修掉,`--live` 会实际连接服务。页面上的老师起不来时,先看 doctor 和 `conversations/<老师>/<日期>.<job>.err.log`。家长端与工作台需要访问锁时,运行 `cotutor pin` 设置本机 PIN。
+
+## 遇到问题
+
+家长端「首页」顶部的「还差几步」和橙色提示会说要做什么。还解决不了,到家长端「设置」点「生成诊断信息」(或在电脑上跑 `cotutor report`),看一遍再复制,到 [GitHub Issues](https://github.com/TarsLab/cotutor/issues) 反馈,或者贴给帮你的 AI 助手。里面没有孩子的对话、照片、录音、档案和 key,名字和 IP 已经抹掉。
 
 ## 数据与升级
 
 默认 workspace 是 `~/cotutor/<孩子>/`:配置在 `cotutor.json`,老师在 `agents/<老师>.md`,activity 在 `agents/<老师>/activities/`,技能在 `.agents/skills/`,对话在 `conversations/`,账本在 `ledger/`,照片在 `captures/`,课包在 `bundles/`,首页在 `home/`。长期档案、记忆和日记在配置的 Obsidian vault,规则见 [obsidian 仓库设计](docs/obsidian仓库设计.md)。备份时保留整个 workspace 与 vault。
 
+**备份**放在孩子文件夹旁边的 `.backups/<孩子>/`,一份就是一个普通目录。服务开着时每天自动备一份(留 14 份),`cotutor upgrade` 前也备一份(留 5 份),没变的文件不占第二份地方;`cotutor backup` 随时手动备。**录音(wav)不在备份里**,它占了绝大部分地方;想留就自己拷 `conversations/`。硬盘坏了这些也跟着没了,重要的话把 `.backups` 再拷到别处。
+
+```sh
+cotutor backup list                   # 看有哪些
+cotutor backup restore <名字> --yes    # 恢复:先把现在的样子也备一份,再拷回去
+```
+
 **有新版本时**,后台服务每天问一次 npm(只发一个普通请求,不带孩子或使用的任何信息),菜单栏(任务栏)图标的菜单和家长端「首页」顶部会说,通知一次,孩子端不说。不会自动升级,因为要重启服务,孩子可能正在上课。不想让它问:在 `~/.config/cotutor/update.json` 写 `{"off": true}`。
 
 升级挑孩子不用的时候,运行一条命令就够了(Windows 上写成 `cotutor.cmd update`,因为 PowerShell 缺省禁止运行脚本,提示里给的就是这样):
@@ -151,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/backup.d.ts

@@ -0,0 +1,68 @@
+export declare const BACKUP_DIR = ".backups";
+/** 磁盘快满了不备份:备份不能把孩子正在用的电脑撑爆 */
+export declare const MIN_FREE_BYTES: number;
+export type BackupWhy = 'daily' | 'upgrade' | 'manual' | 'restore';
+export interface BackupMeta {
+    name: string;
+    at: string;
+    why: BackupWhy;
+    version: string | null;
+    files: number;
+    /** 这一份看上去多大 */
+    bytes: number;
+    /** 真正新占的地方(其余和上一份硬链接) */
+    newBytes: number;
+    /** 没备份的录音有几个 */
+    audioSkipped: number;
+    vault: 'inside' | 'copied' | 'unreadable' | 'none';
+}
+export interface BackupTarget {
+    root: string;
+    vault?: string;
+}
+export declare const backupsOf: (root: string) => string;
+/** 要不要进备份:rel 是相对 workspace 根的路径,统一成 / */
+export declare function wanted(rel: string): boolean;
+export declare function listBackups(root: string): Promise<BackupMeta[]>;
+export interface BackupOptions {
+    why: BackupWhy;
+    version?: string | null;
+    now?: Date;
+    /** 测试:这块盘还剩多少字节 */
+    freeBytes?: () => Promise<number>;
+}
+/** 备份一份。写到临时目录再改名,中途断了不会留下半份 */
+export declare function makeBackup(t: BackupTarget, o: BackupOptions): Promise<BackupMeta>;
+/** 每种留最近几份;刚做的那份不删。硬链接删了不影响别的份 */
+export declare function pruneBackups(root: string, keepName?: string): Promise<string[]>;
+/** 该不该做今天这份 */
+export declare function dailyDue(list: readonly BackupMeta[], now: number): boolean;
+/**
+ * 恢复:先把现在的样子也备份一份(恢复错了还能回来),再把那一份拷回去。只覆盖备份里有的文件,之后新多出来的不删。
+ * 服务要先停(main.ts 管)。外面的 vault 不动,回 vaultCopy 告诉家长在哪。
+ */
+export declare function restoreBackup(t: BackupTarget, name: string, o?: {
+    version?: string | null;
+    now?: Date;
+    freeBytes?: () => Promise<number>;
+}): Promise<{
+    files: number;
+    safety: string;
+    vaultCopy: string | null;
+}>;
+/** 一份给人看的样子 */
+export declare function describeBackup(b: BackupMeta): string;
+/**
+ * serve 起来时调:隔一阵看一眼,该备份了就备一份。孩子在通话时往后推(拷文件占磁盘,不和通话抢)。
+ * 备份失败不影响服务,只进日志,doctor 看「最近一份是多久以前」就知道了。定时器不拦进程退出。
+ */
+export declare function startDailyBackups(o: {
+    target: () => BackupTarget | null;
+    busy: () => boolean;
+    version: string | null;
+    now?: () => number;
+    firstMs?: number;
+    everyMs?: number;
+    note?: (text: string) => void;
+    freeBytes?: () => Promise<number>;
+}): () => void;

package/dist/app/cli/backup.js

@@ -0,0 +1,243 @@
+/**
+ * 备份:孩子的记录删了找不回来。升级前留一份,每天留一份,放在 workspace 旁边的 .backups/<目录名>/<名字>/,一份就是一个普通目录,打开就能看。
+ * 防的是升级弄坏、手滑改坏、误删文件夹;硬盘坏了防不住,要防就把 .backups 再拷到别处。
+ *
+ * 不备份录音(wav):2026-11-07 量真的 workspace,1.28 GB 里 1.21 GB 是录音,其余约 70 MB;这台电脑磁盘还只剩 4%。
+ * 也不备份能重新生成的(视频课 mp4、评测 evals、配音缓存)。保住的是文字记录、账本、照片、老师文件、配置。
+ *
+ * 没变的文件和上一份硬链接,不占第二份地方:每天一份也几乎不涨。一份里的文件不再改,所以硬链接是安全的;恢复时一律拷出去,不链回 workspace。
+ * vault 在 workspace 外面(Obsidian)的,只拷 md 到 _vault/,恢复时不动它:那是家长的,要不要拿回来家长定。macOS 上后台进程读不了「文稿」时记一笔,不算失败。
+ */
+import { copyFile, link, lstat, mkdir, readFile, readdir, rename, rm, stat, statfs, utimes, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { UsageError } from "../workspace.js";
+export const BACKUP_DIR = '.backups';
+const META = 'backup.json';
+const VAULT_DIR = '_vault';
+const TOP_SKIP = new Set(['.git', '.claude', '.sandbox', 'evals', 'node_modules']);
+/** .cotutor 里能重新生成的缓存;别的(设备表、孩子端流水、出厂 hash)留着 */
+const COTUTOR_SKIP = new Set(['qwen', 'live-preview', 'qr', 'board']);
+const SKIP_EXT = /\.(wav|mp4|tmp)$/i;
+const AUDIO = /\.wav$/i;
+const VAULT_MAX_FILES = 5000;
+const KEEP = { daily: 14, upgrade: 5, manual: 5, restore: 5 };
+/** 磁盘快满了不备份:备份不能把孩子正在用的电脑撑爆 */
+export const MIN_FREE_BYTES = 1024 ** 3;
+const DAILY_EVERY_MS = 20 * 3600_000;
+export const backupsOf = (root) => join(dirname(resolve(root)), BACKUP_DIR, basename(resolve(root)));
+const pad = (n) => String(n).padStart(2, '0');
+const stamp = (d) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}`;
+/** 要不要进备份:rel 是相对 workspace 根的路径,统一成 / */
+export function wanted(rel) {
+    const parts = rel.split('/');
+    if (TOP_SKIP.has(parts[0]))
+        return false;
+    if (parts[0] === '.cotutor' && parts.length > 1 && COTUTOR_SKIP.has(parts[1]))
+        return false;
+    return !SKIP_EXT.test(rel);
+}
+async function* walk(dir, base) {
+    for (const e of await readdir(dir, { withFileTypes: true })) {
+        const path = join(dir, e.name);
+        const rel = relative(base, path).split(sep).join('/');
+        // 只认普通文件和目录:链接(.claude/skills)不跟进去,不然会拷到 workspace 外面
+        if (e.isDirectory()) {
+            if (rel.split('/')[0] === BACKUP_DIR)
+                continue;
+            if (TOP_SKIP.has(rel) || (rel.startsWith('.cotutor/') && COTUTOR_SKIP.has(rel.slice('.cotutor/'.length))))
+                continue;
+            yield* walk(path, base);
+        }
+        else if (e.isFile()) {
+            const st = await lstat(path).catch(() => null);
+            if (st)
+                yield { path, rel, st };
+        }
+    }
+}
+/** 放一个文件:和上一份一样就硬链接,不一样(或链不了:跨盘、文件系统不支持)就拷。回新占了多少字节 */
+async function place(src, st, dest, prev) {
+    await mkdir(dirname(dest), { recursive: true });
+    if (prev) {
+        const p = await stat(prev).catch(() => null);
+        if (p && p.size === st.size && Math.abs(p.mtimeMs - st.mtimeMs) < 2) {
+            try {
+                await link(prev, dest);
+                return 0;
+            }
+            catch { /* 链不了就拷 */ }
+        }
+    }
+    await copyFile(src, dest);
+    await utimes(dest, st.atime, st.mtime).catch(() => undefined);
+    return st.size;
+}
+export async function listBackups(root) {
+    const dir = backupsOf(root);
+    const names = await readdir(dir).catch(() => []);
+    const out = [];
+    for (const name of names) {
+        if (name.startsWith('.'))
+            continue;
+        try {
+            out.push({ ...JSON.parse(await readFile(join(dir, name, META), 'utf8')), name });
+        }
+        catch { /* 不是一份完整的备份 */ }
+    }
+    return out.sort((a, b) => b.at.localeCompare(a.at) || b.name.localeCompare(a.name));
+}
+const freeOf = async (dir) => {
+    const s = await statfs(dir);
+    return Number(s.bavail) * Number(s.bsize);
+};
+/** 备份一份。写到临时目录再改名,中途断了不会留下半份 */
+export async function makeBackup(t, o) {
+    const root = resolve(t.root);
+    const dir = backupsOf(root);
+    await mkdir(dir, { recursive: true });
+    const free = await (o.freeBytes ?? (() => freeOf(dir)))().catch(() => Number.POSITIVE_INFINITY);
+    if (free < MIN_FREE_BYTES)
+        throw new UsageError(`磁盘只剩 ${(free / 1024 ** 3).toFixed(1)} GB,这次没备份:先腾点地方,备份不能把这台电脑撑爆`);
+    const now = o.now ?? new Date();
+    const list = await listBackups(root);
+    const prevDir = list[0] ? join(dir, list[0].name) : null;
+    let name = `${stamp(now)}-${o.why}`;
+    for (let i = 2; list.some((b) => b.name === name); i++)
+        name = `${stamp(now)}-${o.why}-${i}`;
+    const tmp = join(dir, `.tmp-${process.pid}-${now.getTime()}`);
+    await rm(tmp, { recursive: true, force: true });
+    await mkdir(tmp, { recursive: true });
+    const meta = { name, at: now.toISOString(), why: o.why, version: o.version ?? null, files: 0, bytes: 0, newBytes: 0, audioSkipped: 0, vault: 'none' };
+    try {
+        for await (const f of walk(root, root)) {
+            if (!wanted(f.rel)) {
+                if (AUDIO.test(f.rel))
+                    meta.audioSkipped++;
+                continue;
+            }
+            meta.newBytes += await place(f.path, f.st, join(tmp, ...f.rel.split('/')), prevDir && join(prevDir, ...f.rel.split('/')));
+            meta.files++;
+            meta.bytes += f.st.size;
+        }
+        const vault = t.vault ? resolve(t.vault) : null;
+        if (vault && (vault === root || vault.startsWith(root + sep)))
+            meta.vault = 'inside';
+        else if (vault) {
+            try {
+                let n = 0;
+                for await (const f of walk(vault, vault)) {
+                    if (!f.rel.endsWith('.md') || f.rel.split('/').some((p) => p.startsWith('.')))
+                        continue;
+                    if (++n > VAULT_MAX_FILES)
+                        break;
+                    meta.newBytes += await place(f.path, f.st, join(tmp, VAULT_DIR, ...f.rel.split('/')), prevDir && join(prevDir, VAULT_DIR, ...f.rel.split('/')));
+                    meta.files++;
+                    meta.bytes += f.st.size;
+                }
+                meta.vault = 'copied';
+            }
+            catch (err) {
+                const code = err.code;
+                // macOS 不让后台进程读「文稿」、iCloud 云盘;vault 不在了:都不拦这一份
+                if (code === 'EPERM' || code === 'EACCES' || code === 'ENOENT')
+                    meta.vault = 'unreadable';
+                else
+                    throw err;
+            }
+        }
+        await writeFile(join(tmp, META), `${JSON.stringify(meta, null, 2)}\n`);
+        await rename(tmp, join(dir, name));
+    }
+    catch (err) {
+        await rm(tmp, { recursive: true, force: true }).catch(() => undefined);
+        throw err;
+    }
+    await pruneBackups(root, name);
+    return meta;
+}
+/** 每种留最近几份;刚做的那份不删。硬链接删了不影响别的份 */
+export async function pruneBackups(root, keepName) {
+    const dir = backupsOf(root);
+    const list = await listBackups(root);
+    const gone = [];
+    const seen = {};
+    for (const b of list) {
+        seen[b.why] = (seen[b.why] ?? 0) + 1;
+        if (seen[b.why] > (KEEP[b.why] ?? 5) && b.name !== keepName) {
+            await rm(join(dir, b.name), { recursive: true, force: true });
+            gone.push(b.name);
+        }
+    }
+    // 上次断在半路留下的临时目录
+    for (const n of await readdir(dir).catch(() => [])) {
+        if (!n.startsWith('.tmp-'))
+            continue;
+        const st = await stat(join(dir, n)).catch(() => null);
+        if (st && Date.now() - st.mtimeMs > 24 * 3600_000)
+            await rm(join(dir, n), { recursive: true, force: true });
+    }
+    return gone;
+}
+/** 该不该做今天这份 */
+export function dailyDue(list, now) {
+    const last = list.find((b) => b.why === 'daily');
+    return !last || now - Date.parse(last.at) >= DAILY_EVERY_MS;
+}
+/**
+ * 恢复:先把现在的样子也备份一份(恢复错了还能回来),再把那一份拷回去。只覆盖备份里有的文件,之后新多出来的不删。
+ * 服务要先停(main.ts 管)。外面的 vault 不动,回 vaultCopy 告诉家长在哪。
+ */
+export async function restoreBackup(t, name, o = {}) {
+    const root = resolve(t.root);
+    const target = (await listBackups(root)).find((b) => b.name === name);
+    if (!target)
+        throw new UsageError(`没有这份备份:${name}(cotutor backup list 看有哪些)`);
+    const from = join(backupsOf(root), name);
+    const safety = await makeBackup(t, { why: 'restore', version: o.version, now: o.now, freeBytes: o.freeBytes });
+    let files = 0;
+    for await (const f of walk(from, from)) {
+        if (f.rel === META || f.rel.split('/')[0] === VAULT_DIR)
+            continue;
+        const dest = join(root, ...f.rel.split('/'));
+        await mkdir(dirname(dest), { recursive: true });
+        await copyFile(f.path, dest);
+        await utimes(dest, f.st.atime, f.st.mtime).catch(() => undefined);
+        files++;
+    }
+    return { files, safety: safety.name, vaultCopy: target.vault === 'copied' ? join(from, VAULT_DIR) : null };
+}
+/** 一份给人看的样子 */
+export function describeBackup(b) {
+    const mb = (n) => (n < 1024 * 1024 ? `${Math.max(1, Math.round(n / 1024))} KB` : `${(n / 1024 / 1024).toFixed(1)} MB`);
+    const why = { daily: '每天', upgrade: '升级前', manual: '手动', restore: '恢复前' }[b.why] ?? b.why;
+    return `${b.name}  ${why} · ${b.files} 个文件 · ${mb(b.bytes)}(新占 ${mb(b.newBytes)})${b.version ? ` · ${b.version}` : ''}`;
+}
+/**
+ * serve 起来时调:隔一阵看一眼,该备份了就备一份。孩子在通话时往后推(拷文件占磁盘,不和通话抢)。
+ * 备份失败不影响服务,只进日志,doctor 看「最近一份是多久以前」就知道了。定时器不拦进程退出。
+ */
+export function startDailyBackups(o) {
+    let running = false;
+    const now = o.now ?? Date.now;
+    const check = async () => {
+        const t = o.target();
+        if (running || !t || o.busy())
+            return;
+        running = true;
+        try {
+            if (dailyDue(await listBackups(t.root), now()))
+                await makeBackup(t, { why: 'daily', version: o.version, now: new Date(now()), freeBytes: o.freeBytes });
+        }
+        catch (err) {
+            (o.note ?? ((s) => console.error(s)))(`备份没成:${err instanceof Error ? err.message : String(err)}`);
+        }
+        finally {
+            running = false;
+        }
+    };
+    const first = setTimeout(() => { void check(); }, o.firstMs ?? 5 * 60_000);
+    first.unref();
+    const every = setInterval(() => { void check(); }, o.everyMs ?? 3600_000);
+    every.unref();
+    return () => { clearTimeout(first); clearInterval(every); };
+}

package/dist/app/cli/doctor-fix.d.ts

@@ -0,0 +1,18 @@
+import type { DoctorReport } from './doctor.ts';
+/** 按空格拆,双引号里的算一段;$HOME 换成真的家目录 */
+export declare function parseCmd(cmd: string, home?: string): string[];
+export interface FixDeps {
+    doctor(): Promise<DoctorReport>;
+    run(argv: string[]): Promise<{
+        code: number;
+        out: string;
+    }>;
+    print(line: string): void;
+}
+/** 修到没有可修的;同一条命令只跑一次,修不好的不反复试。回最后那次体检 */
+export declare function runFixes(d: FixDeps): Promise<DoctorReport>;
+/** 真的跑:cotutor 用现在这个 node 和 bin,不靠 PATH */
+export declare function runArgv(argv: string[]): Promise<{
+    code: number;
+    out: string;
+}>;

package/dist/app/cli/doctor-fix.js

@@ -0,0 +1,70 @@
+/**
+ * cotutor doctor --fix:把体检里能自动修的(带 cmd 的那些:幂等、不碰孩子的数据、不用人输东西)一条条跑掉,修完再查,直到没有可修的;要人来的留给人。
+ * cmd 是给人和 agent 看的字符串(路径写成 $HOME,用户名不传出去),这里拆成参数直接起进程,不经 shell:Windows 的 cmd.exe 不认 $HOME,脚本策略也拦不到这里。
+ * 只跑 cotutor 和 git:cmd 是我们自己写的,但万一哪天有一条写错了,不该变成任意命令。
+ */
+import { spawn } from 'node:child_process';
+import { homedir } from 'node:os';
+import { binPath } from "./service.js";
+/** 按空格拆,双引号里的算一段;$HOME 换成真的家目录 */
+export function parseCmd(cmd, home = homedir()) {
+    const out = [];
+    let cur = '';
+    let quoted = false;
+    let has = false;
+    for (const ch of cmd) {
+        if (ch === '"') {
+            quoted = !quoted;
+            has = true;
+            continue;
+        }
+        if (ch === ' ' && !quoted) {
+            if (has)
+                out.push(cur);
+            cur = '';
+            has = false;
+            continue;
+        }
+        cur += ch;
+        has = true;
+    }
+    if (has)
+        out.push(cur);
+    return out.map((a) => a.replaceAll('$HOME', home));
+}
+const ROUNDS = 12;
+/** 修到没有可修的;同一条命令只跑一次,修不好的不反复试。回最后那次体检 */
+export async function runFixes(d) {
+    const tried = new Set();
+    let report = await d.doctor();
+    for (let i = 0; i < ROUNDS; i++) {
+        const next = report.checks.find((c) => !c.ok && c.cmd && !tried.has(c.cmd));
+        if (!next?.cmd)
+            break;
+        tried.add(next.cmd);
+        const argv = parseCmd(next.cmd);
+        if (argv[0] !== 'cotutor' && argv[0] !== 'git') {
+            d.print(`! ${next.name}:不认识这条命令,没跑:${next.cmd}`);
+            continue;
+        }
+        const r = await d.run(argv);
+        d.print(`${r.code === 0 ? '✓' : '✗'} ${next.name}:${next.cmd}`);
+        if (r.code !== 0)
+            for (const l of r.out.trim().split('\n').slice(-4))
+                d.print(`    ${l}`);
+        report = await d.doctor();
+    }
+    return report;
+}
+/** 真的跑:cotutor 用现在这个 node 和 bin,不靠 PATH */
+export function runArgv(argv) {
+    const [cmd, args] = argv[0] === 'cotutor' ? [process.execPath, [binPath(), ...argv.slice(1)]] : [argv[0], argv.slice(1)];
+    return new Promise((resolve) => {
+        const child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+        let out = '';
+        child.stdout?.on('data', (c) => { out += c.toString('utf8'); });
+        child.stderr?.on('data', (c) => { out += c.toString('utf8'); });
+        child.on('error', (err) => resolve({ code: 1, out: `${out}${err.message}\n` }));
+        child.on('close', (code) => resolve({ code: code ?? 1, out }));
+    });
+}

package/dist/app/cli/doctor.js

@@ -569,6 +569,14 @@ export async function doctorWorkspace(override, opts = {}) {
         if (sec !== null)
             push({ name: 'windows.sleep', ok: sec === 0, required: false, detail: sec === 0 ? '接着电源时不闲置睡眠' : `接着电源 ${Math.round(sec / 60)} 分钟没人碰就睡,睡着时平板连不上(有通话时 cotutor 拦着它睡,别的时候拦不了)`, fix: sec === 0 ? undefined : '设置 › 系统 › 电源和电池 › 屏幕、睡眠和休眠超时,「插入电源时,使设备在以下时间后进入睡眠状态」选「从不」;合盖看「电源按钮和盖子」那一项' });
     }
+    // ---- 备份:服务开着时每天一份;好几天没有说明服务没在跑、或者备份一直失败(磁盘满、读不了) ----
+    if (probeEnv && ws && !ws.sandbox) {
+        const { backupsOf, listBackups } = await import("./backup.js");
+        const list = await listBackups(root).catch(() => []);
+        const last = list[0];
+        const ageMs = last ? (opts.now ?? new Date()).getTime() - Date.parse(last.at) : Number.POSITIVE_INFINITY;
+        push({ name: 'backup', ok: ageMs < 3 * 24 * 3600_000, required: false, detail: last ? `最近一份 ${last.at.slice(0, 10)},共 ${list.length} 份(${redactHome(backupsOf(root))})` : '还没有备份', fix: 'cotutor backup 备一份;服务开着时每天自己备', cmd: `cotutor backup${flag}` });
+    }
     // ---- 有没有新版本:只看服务问来存下的那份,体检不上网;什么时候升级家长定(要重起服务,孩子可能在上课),所以没有 cmd ----
     {
         const { readUpdateRecord } = await import("../machine/update.js");

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

@@ -15,5 +15,7 @@ export interface InitOptions {
     port?: number;
     /** 出厂教学包年级,不是孩子档案的覆盖值。 */
     grade?: number;
+    /** 测试:算学期用的今天 */
+    now?: Date;
 }
 export declare function initWorkspace(opts: InitOptions): Promise<InitResult>;

package/dist/app/cli/init.js

@@ -9,6 +9,7 @@ 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 { schoolStartFor } from "../../memory/vault-notes.js";
 import { installActivities } from "./activities.js";
 import { installSkills, linkClaudeSkills } from "./skills.js";
 import { migrateLayout } from "./migrate.js";
@@ -102,8 +103,10 @@ export async function initWorkspace(opts) {
             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 start = opts.grade === undefined ? undefined : schoolStartFor(opts.grade, opts.now ?? new Date());
+            await writeFile(profile, profileTemplate(ws.config.kid.name ?? ws.config.kid.slug, start));
+            steps.push({ item: redactHome(profile), action: 'created', note: start ? `档案:按 ${opts.grade} 年级算,读一年级是 ${start};孩子的情况写在正文,每个话题开头整篇进上下文包` : '档案:填 school_start 与孩子的情况,每个话题开头整篇进上下文包' });
         }
         const readme = join(ws.paths.reference, 'README.md');
         if (await exists(readme))
@@ -149,7 +152,7 @@ export async function initWorkspace(opts) {
     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(`${opts.grade === undefined ? '档案里填 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 给家长端与工作台加锁');