cotutor 0.4.1 → 0.4.3

package/README.md

@@ -100,15 +100,36 @@ import { loadWorkspace } from 'cotutor/workspace';                        // 解
 
 换了运行时,之前的话题接不上,也不导入历史:孩子接着说会开新话题;换之前聊的话题不记账,家长端卡上标「换过运行时 · 不记账」,记录照样能看。模型、预算与老师运行时都在 workspace 的 `cotutor.json` 里,编辑器按首行 `$schema` 提供字段说明。
 
-`cotutor doctor` 检查缺失配置并给修复建议;`--live` 会实际连接服务。页面上的老师起不来时,先看 doctor 和 `conversations/<老师>/<日期>.<job>.err.log`。家长端与工作台需要访问锁时,运行 `cotutor pin` 设置本机 PIN。
+百炼欠费、key 失效或这台电脑连不上百炼时,图标出橙点并通知,家长端首页说清楚是哪一种;要家长动手的那几种,孩子端显示「老师们还没到,叫爸爸妈妈来看一下」。处理好以后几分钟内自己恢复,也可以在家长端点「试连」。
+
+`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 默认的 PowerShell 不认 `&&`):
+升级挑孩子不用的时候,运行一条命令就够了(Windows 上写成 `cotutor.cmd update`,因为 PowerShell 缺省禁止运行脚本,提示里给的就是这样):
+
+```sh
+cotutor update
+```
+
+它问 npm 有没有新版本,换上新程序,把每个孩子未修改的出厂老师、activity、主题与技能更新掉,再重起服务和图标。孩子正在通话时它不动;下载没成时服务也不动,还跑旧版。每个版本改了什么见 [更新说明](CHANGELOG.md)。
+
+0.4.1 及更早的版本还没有这条命令,第一次要依次运行下面三条,Windows 上同样写成 `npm.cmd`、`cotutor.cmd`。几个孩子的话,后两条每个孩子各跑一次,加 `--workspace ~/cotutor/<孩子>`:
 
 ```sh
 npm i -g cotutor                      # 换上新版程序
@@ -116,12 +137,9 @@ cotutor upgrade                       # 更新未修改的出厂老师、activit
 cotutor service restart               # 服务和图标换上新代码(在终端里跑的就重开 serve)
 ```
 
-Windows 上写成 `npm.cmd`、`cotutor.cmd`(PowerShell 缺省禁止运行脚本),提示里给的就是这样。
-
-几个孩子的话,后两条每个孩子各跑一次,加 `--workspace ~/cotutor/<孩子>`。然后看一眼体检,它提示要迁移配置时再跑后面两条:
+升完它提示要迁移配置时再跑:
 
 ```sh
-cotutor doctor
 cotutor upgrade --config --dry-run    # 预览 cotutor.json 的迁移
 cotutor upgrade --config              # 执行配置迁移
 ```

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

@@ -263,8 +263,13 @@ export async function doctorWorkspace(override, opts = {}) {
             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))
+            const running = await probeHealth(port);
+            if (running) {
                 push({ name: 'server.port', ok: true, required: false, detail: `端口 ${port} 上 cotutor 在答应` });
+                // 配好了不等于用得了:欠费、key 失效是跑起来才知道的,问在跑的那个服务
+                if (running.bailianTrouble)
+                    push({ name: 'bailian.runtime', ok: false, required: false, detail: `${running.bailianTrouble.message}(${running.bailianTrouble.why ?? ''})`, fix: running.bailianTrouble.fix });
+            }
             else {
                 const state = await portState(port);
                 if (state === 'free')
@@ -540,7 +545,11 @@ export async function doctorWorkspace(override, opts = {}) {
         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 { stableNode } = await import("./service.js");
             const gone = s.args.slice(0, 2).filter((f) => !existsSync(f));
+            // 还没坏,但 brew upgrade 以后就坏了,而且坏的时候图标也起不来,没人报警
+            if (!gone.length && stableNode(s.args[0]) !== s.args[0])
+                push({ name: 'service.node', ok: false, required: false, detail: `后台服务写死了带版本号的 node(${redactHome(s.args[0])}),brew upgrade 以后服务和图标都起不来`, fix: 'cotutor service install(换成不带版本号的路径)', cmd: `cotutor service install --no-open${flag}` });
             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 });
         }
     }
@@ -560,12 +569,20 @@ 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");
         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(' ; ')}` });
+            push({ name: 'update', ok: false, required: false, detail: `有新版本 ${u.latest}(现在是 ${BUILD.version})`, fix: `挑孩子不用的时候,运行:${upgradeSteps().join(' ; ')}` });
     }
     // ---- 用户配置 ----
     try {

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 给家长端与工作台加锁');