cotutor 0.4.0 → 0.4.2

package/README.md

@@ -6,15 +6,24 @@
 
 ## 五分钟用起来
 
-需要一台电脑(Mac 最省事)、Node ≥ 22.18,和一个百炼账号(北京地域,按量付费)。老师的嘴和脑都走百炼,由应用直接调用,不用另装模型客户端:嘴是 `qwen3.8-omni-flash-realtime`,听孩子说、照着讲稿念;脑是 `qwen3.8-max`,写讲稿和板书。
+**让 AI 助手帮你装:** 把这句话发给编程助手(Claude Code、Codex 这类能在电脑上跑命令的),或者网页版的聊天机器人,它会一步步带你做。百炼的 Key 由你自己填在页面上,不用告诉它。
+
+```text
+请阅读 https://raw.githubusercontent.com/TarsLab/cotutor/main/INSTALL.md ,照着在这台电脑上安装 cotutor
+```
+
+**自己装:** 需要一台电脑(Mac 最省事)、Node ≥ 22.18,和一个百炼账号(北京地域,按量付费)。老师的嘴和脑都走百炼,由应用直接调用,不用另装模型客户端:嘴是 `qwen3.8-omni-flash-realtime`,听孩子说、照着讲稿念;脑是 `qwen3.8-max`,写讲稿和板书。
 
 ```sh
 npm i -g cotutor
 cotutor init ming --name 小明 --grade 2     # 建 ~/cotutor/ming/:三位老师、技能、账本、对话目录、cotutor.json
-cotutor service install                    # 装成这台电脑的后台服务,打印家长端首页的地址,孩子的平板在那里扫码
-cotutor open                               # 打开家长端,不用记地址
+cotutor service install                    # 装成这台电脑的后台服务,第一次装会打开家长端,孩子的平板在那里扫码
 ```
 
+Windows 的 PowerShell 缺省禁止运行脚本,报这个错时把 `npm`、`cotutor` 写成 `npm.cmd`、`cotutor.cmd`,不用改系统设置。
+
+以后要打开家长端,点菜单栏(任务栏)的 cotutor 图标或跑 `cotutor open`,服务重启、登录电脑都不会自己弹出来。不想第一次弹,安装时加 `--no-open`。
+
 后台服务登录后自己起来、崩了自己再起、关了终端照样跑,日志按天落文件:`cotutor service status` 看在不在跑,`cotutor service logs` 看日志,`cotutor service restart` 重起。Mac 上用 launchd,Linux 上用 systemd 用户服务,Windows 上是一条用户自己的登录项(不用管理员、没有黑窗口);第一次起来 Windows 可能弹窗问「允许访问」,点允许,平板才连得进来。要在终端里调试用 `cotutor serve`,先 `cotutor service stop` 让出端口。
 
 Mac 和 Windows 上,`service install` 会一起装一个菜单栏(任务栏)图标,不用开终端就能看状态:正常时就是 logo;有事要处理出橙点;后台服务没在跑时 logo 变淡并出红点。状态变差时通知一次。点开图标能看原因、打开家长端、重启服务、看日志。「退出 cotutor」会停掉这台电脑上所有孩子的后台服务,平板打不开,下次登录自动恢复。Windows 的新图标先收在任务栏右下角的 `^` 里。不要图标就 `cotutor tray off`,装服务时加 `--no-tray` 也行。Linux 上没做,用 `cotutor service status` 看。
@@ -25,7 +34,9 @@ Mac 和 Windows 上,`service install` 会一起装一个菜单栏(任务栏)图
 
 1. **填百炼**:在这台电脑上打开家长端 `/parent` 的「首页」,填百炼「按量付费」的 API Key 和业务空间 ID,保存前会先试连。API Key 在百炼控制台的「密钥管理」里创建,业务空间 ID 在控制台的业务空间详情里看,以百炼文档为准:[获取与配置 API Key](https://help.aliyun.com/zh/model-studio/get-api-key)、[首次调用千问 API](https://help.aliyun.com/zh/model-studio/first-api-call-to-qwen)(里面讲了业务空间 ID)。Key 跟地域绑定,控制台右上角先选北京。Token Plan 的 `sk-sp-` 不行。没填时孩子端只出「老师们还没到」。
 2. **填档案**:workspace 里的 `孩子.md` 填 `school_start`(读一年级的年月,如 `2025-09`),老师据此知道现在是几年级哪个学期。想用自己的 Obsidian 库,改 `cotutor.json` 的 `paths.vault`。
-3. **体检**:`cotutor doctor` 逐项检查,不过的每条都带修复命令。
+3. **体检**:`cotutor doctor` 逐项检查,不过的每条都带修法。
+
+装好以后也可以让编程助手帮你管:在孩子的文件夹(`~/cotutor/<孩子>/`)里打开 Claude Code 或 Codex,已带的技能直接能用。`cotutor-home` 排孩子的首页,`cotutor-tune` 调老师的口气和规矩,`cotutor-analyze` 分析某次对话为什么那样答。
 
 `init` 把出厂老师拷进 `agents/<老师>.md`,把做课包用的四个技能 chalk-* 和五个机器件 cotutor-tutor / cotutor-board / cotutor-analyze / cotutor-tune / cotutor-home 拷进 `.agents/skills/`(Codex、Qwen Code 直接读;Claude Code 读的 `.claude/skills` 是链到它的);
 做小课堂的课包用 `cotutor chalk`(check / build / bake / snap / dub),烤画面与截图用本机的 Chrome(Windows 上没有 Chrome 就用 Edge)。要在平板上用(按住说话要 HTTPS):`cotutor cert` 签一张
@@ -89,20 +100,40 @@ import { loadWorkspace } from 'cotutor/workspace';                        // 解
 
 换了运行时,之前的话题接不上,也不导入历史:孩子接着说会开新话题;换之前聊的话题不记账,家长端卡上标「换过运行时 · 不记账」,记录照样能看。模型、预算与老师运行时都在 workspace 的 `cotutor.json` 里,编辑器按首行 `$schema` 提供字段说明。
 
+百炼欠费、key 失效或这台电脑连不上百炼时,图标出橙点并通知,家长端首页说清楚是哪一种;要家长动手的那几种,孩子端显示「老师们还没到,叫爸爸妈妈来看一下」。处理好以后几分钟内自己恢复,也可以在家长端点「试连」。
+
 `cotutor doctor` 检查缺失配置并给修复建议;`--live` 会实际连接服务。页面上的老师起不来时,先看 doctor 和 `conversations/<老师>/<日期>.<job>.err.log`。家长端与工作台需要访问锁时,运行 `cotutor pin` 设置本机 PIN。
 
 ## 数据与升级
 
 默认 workspace 是 `~/cotutor/<孩子>/`:配置在 `cotutor.json`,老师在 `agents/<老师>.md`,activity 在 `agents/<老师>/activities/`,技能在 `.agents/skills/`,对话在 `conversations/`,账本在 `ledger/`,照片在 `captures/`,课包在 `bundles/`,首页在 `home/`。长期档案、记忆和日记在配置的 Obsidian vault,规则见 [obsidian 仓库设计](docs/obsidian仓库设计.md)。备份时保留整个 workspace 与 vault。
 
+**有新版本时**,后台服务每天问一次 npm(只发一个普通请求,不带孩子或使用的任何信息),菜单栏(任务栏)图标的菜单和家长端「首页」顶部会说,通知一次,孩子端不说。不会自动升级,因为要重启服务,孩子可能正在上课。不想让它问:在 `~/.config/cotutor/update.json` 写 `{"off": true}`。
+
+升级挑孩子不用的时候,运行一条命令就够了(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                      # 换上新版程序
+cotutor upgrade                       # 更新未修改的出厂老师、activity、主题与技能
+cotutor service restart               # 服务和图标换上新代码(在终端里跑的就重开 serve)
+```
+
+升完它提示要迁移配置时再跑:
+
 ```sh
-cotutor upgrade                      # 更新未修改的出厂老师、activity、主题与技能
 cotutor upgrade --config --dry-run    # 预览 cotutor.json 的迁移
 cotutor upgrade --config              # 执行配置迁移
-cotutor doctor
 ```
 
-家长改过的老师与主题保留并显示差异;机器技能会随版本覆盖。配置迁移补缺,并更新未自定义的旧命令模板,保留自定义配置。升级程序后 `cotutor service restart`(在终端里跑的就重开 `serve`);换了 Node 版本、或包装到了别处,再 `cotutor service install` 一次。
+家长改过的老师与主题保留并显示差异;机器技能会随版本覆盖。配置迁移补缺,并更新未自定义的旧命令模板,保留自定义配置。换了 Node 版本、或包装到了别处,再 `cotutor service install` 一次。
 
 2026-10-30 之前建的 workspace,老师在 `.claude/agents/`、技能在 `.claude/skills/`。`cotutor upgrade`(或 `init`)先把它们原样挪到新位置,再照常升级;新位置已有同名的不挪,会点名。`.claude/` 里别的文件不动。
 
@@ -135,7 +166,7 @@ node bin/cotutor.js mock         # 假模型接口,查看前端
 
 改卡片文档或技能生成代码后运行 `pnpm gen:skills`。开发约定与分模块验证见 [AGENTS.md](AGENTS.md) 和 [CONTRIBUTING.md](CONTRIBUTING.md)。
 
-正式文档只保留以下六篇,历史讨论查 Git:
+根目录的 [INSTALL.md](INSTALL.md) 给替家长安装的 AI 助手看。`docs/` 只保留以下六篇,历史讨论查 Git:
 
 - [iPad 与 iPhone](docs/iPad与iPhone.md)
 - [obsidian 仓库设计](docs/obsidian仓库设计.md)

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

@@ -3,10 +3,16 @@
  * 没有 winget 的(11-02 那台就没有)下官方的 exe。
  */
 export declare function mkcertHint(platform?: NodeJS.Platform): string;
+/** mkcert 在、根证书建过了:cotutor cert 不用人就能跑。mkcert -install 要开机密码或点弹窗,那一步是人的 */
+export declare function mkcertReady(caRootOf?: () => Promise<string>): Promise<boolean>;
+/** 根证书没进这台电脑的系统信任。mkcert 没有根证书时自己建一个、照样签成功,只在 stderr 说一句(Firefox、Java 的信任库它也说,那些不算);没有单独的查询命令,只能这样看 */
+export declare const mkcertUntrusted: (stderr: string) => boolean;
 export interface CertResult {
     cert: string;
     key: string;
     hosts: string[];
     caRoot: string;
+    /** 这台电脑信任根证书了;false 时证书能用,但这台电脑的浏览器会报警告 */
+    trusted: boolean;
 }
 export declare function makeCert(extraHosts?: string[]): Promise<CertResult>;

package/dist/app/cli/cert.js

@@ -6,6 +6,7 @@
  * 地址认电脑名,IP 变了不用重签;证书里的 IP 只给手输数字地址的退路用。改了电脑名才要重签。
  */
 import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
 import { mkdir } from 'node:fs/promises';
 import { hostname } from 'node:os';
 import { join } from 'node:path';
@@ -24,6 +25,17 @@ export function mkcertHint(platform = process.platform) {
         return 'winget install FiloSottile.mkcert(没有 winget 就到 https://github.com/FiloSottile/mkcert/releases 下 windows-amd64 那个,改名 mkcert.exe 放进 PATH),重开终端跑 mkcert -install(弹窗问装不装根证书,点「是」)';
     return '用系统的包管理器装 mkcert(如 apt install mkcert),再 mkcert -install';
 }
+/** mkcert 在、根证书建过了:cotutor cert 不用人就能跑。mkcert -install 要开机密码或点弹窗,那一步是人的 */
+export async function mkcertReady(caRootOf = async () => (await execFileP('mkcert', ['-CAROOT'], { timeout: 8000 })).stdout.trim()) {
+    try {
+        return existsSync(join(await caRootOf(), 'rootCA.pem'));
+    }
+    catch {
+        return false;
+    }
+}
+/** 根证书没进这台电脑的系统信任。mkcert 没有根证书时自己建一个、照样签成功,只在 stderr 说一句(Firefox、Java 的信任库它也说,那些不算);没有单独的查询命令,只能这样看 */
+export const mkcertUntrusted = (stderr) => stderr.includes('not installed in the system trust store');
 export async function makeCert(extraHosts = []) {
     let caRoot;
     try {
@@ -39,11 +51,13 @@ export async function makeCert(extraHosts = []) {
     await mkdir(dir, { recursive: true });
     const cert = join(dir, 'cert.pem');
     const key = join(dir, 'key.pem');
+    let trusted;
     try {
-        await execFileP('mkcert', ['-cert-file', cert, '-key-file', key, ...hosts], { timeout: 60_000 });
+        const { stderr } = await execFileP('mkcert', ['-cert-file', cert, '-key-file', key, ...hosts], { timeout: 60_000 });
+        trusted = !mkcertUntrusted(stderr);
     }
     catch (err) {
         throw new UsageError(`mkcert 签证书失败:${err instanceof Error ? err.message : String(err)}\n先跑 mkcert -install,再重试。`);
     }
-    return { cert, key, hosts, caRoot };
+    return { cert, key, hosts, caRoot, trusted };
 }

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

@@ -4,7 +4,12 @@ export interface DoctorCheck {
     ok: boolean;
     required: boolean;
     detail: string;
+    /** 给人看的修法 */
     fix?: string;
+    /** 不过时能直接跑的修复命令:幂等、不碰孩子的数据、不用人输东西(INSTALL.md 让 agent 照跑) */
+    cmd?: string;
+    /** 不过、又没有 cmd:要人来(填 key、输开机密码、点弹窗、写孩子的情况),agent 别动手。finish 统一补 */
+    human?: true;
 }
 export interface DoctorReport {
     ok: boolean;

package/dist/app/cli/doctor.js

@@ -25,11 +25,23 @@ import { parseTimetable } from "../../memory/timetable.js";
 import { configGapsOf, legacyLayout } from "./migrate.js";
 import { httpsFiles } from "./serve.js";
 import { readPin } from "../http/access.js";
+import { BUILD } from "../build.js";
+import { isNewer, upgradeSteps } from "../../shared/upgrade.js";
 import { gradeOfSemester } from "../../memory/grade.js";
 import { DIRS } from "./skeleton.js";
 import { tutorStatuses, readManifest } from "./tutors.js";
 import { workspaceGradePack } from "./grades.js";
 import { CONFIG_FILE, ConfigError, USER_CONFIG, UsageError, assembleWorkspace, expandPath, parseConfig, readJson, redactHome, resolveRoot, } from "../workspace.js";
+/** 每条不过的要么能跑(cmd)要么要人来(human),没有第三种:新加的检查项忘了写 cmd,也只是交给人,不会让 agent 瞎猜 */
+function finish(report) {
+    for (const c of report.checks) {
+        if (c.ok)
+            delete c.cmd;
+        else if (!c.cmd)
+            c.human = true;
+    }
+    return report;
+}
 async function statOrNull(p) {
     return stat(p).catch(() => null);
 }
@@ -89,9 +101,14 @@ export async function doctorWorkspace(override, opts = {}) {
             detail: err.message,
             fix: err instanceof ConfigError ? `修复 ${redactHome(err.file)} 的 JSON,或删掉它` : 'cotutor init <slug>,或用 --workspace / COTUTOR_WORKSPACE 指定',
         });
-        return { ok: false, root: null, source: null, checks };
+        return finish({ ok: false, root: null, source: null, checks });
     }
     push({ name: 'workspace', ok: true, required: true, detail: `${redactHome(root)}(来源:${source})` });
+    // cmd 要能照原样跑:体检时用 --workspace 指的,修的时候也得指
+    // 路径写 $HOME/…,和别的字段一样:用户名不传给 agent 的厂商;redactDeep 只换开头,管不到命令中间的路径;sh 与 PowerShell 都展开
+    const quoted = `"${redactHome(root)}"`;
+    const flag = source === 'flag' ? ` --workspace ${quoted}` : '';
+    const upgrade = `cotutor upgrade${flag}`;
     // ---- cotutor.json ----
     let ws = null;
     const configFile = join(root, CONFIG_FILE);
@@ -117,12 +134,20 @@ export async function doctorWorkspace(override, opts = {}) {
         push({ name: CONFIG_FILE, ok: false, required: true, detail: err.message, fix: '按上面逐条修;政策文件机器不重建,改坏了靠 git 回退' });
     }
     let teachingPack = null;
+    // 补缺的 init:slug 从配置来;年级照已装的写(init 不切换年级);建在缺省位置的不用写 --dir
+    const initCmd = () => {
+        if (!ws)
+            return undefined;
+        const slug = ws.config.kid.slug;
+        const grade = teachingPack ? ` --grade ${teachingPack.grade}` : '';
+        return `cotutor init ${slug}${grade}${root === join(homedir(), 'cotutor', slug) ? '' : ` --dir ${quoted}`}`;
+    };
     try {
         const manifest = await readManifest(root);
         teachingPack = await workspaceGradePack(root);
         push({ name: 'teachingPack', ok: true, required: true, detail: `${teachingPack.grade} 年级教学包 · ${redactHome(teachingPack.dir)}` });
         if (!manifest.teachingPack)
-            push({ name: 'teachingPack.origin', ok: false, required: false, detail: '旧版出厂内容按二年级来源读取,尚未补记;孩子档案不变', fix: 'cotutor upgrade 补记来源,保留自定义文件与原 hash' });
+            push({ name: 'teachingPack.origin', ok: false, required: false, detail: '旧版出厂内容按二年级来源读取,尚未补记;孩子档案不变', fix: 'cotutor upgrade 补记来源,保留自定义文件与原 hash', cmd: upgrade });
     }
     catch (err) {
         push({ name: 'teachingPack', ok: false, required: true, detail: err.message, fix: '检查 .cotutor/shipped.json 的 teachingPack 与本包 grades/;恢复原来源记录或安装包含该年级的版本,不要改成其他年级绕过' });
@@ -136,6 +161,7 @@ export async function doctorWorkspace(override, opts = {}) {
             required: false,
             detail: gaps.length ? `${gaps.length} 项要改:${gaps.map((g) => g.detail).join(';')}` : 'cotutor.json 有出厂模板里的全部老师、运行时与旗标,也没有不再用的段',
             fix: gaps.length ? 'cotutor upgrade --config --dry-run 先看,再 cotutor upgrade --config 改(只加缺的、删不再用的出厂段,你改过的值不动)' : undefined,
+            cmd: gaps.length ? `cotutor upgrade --config${flag}` : undefined,
         });
     }
     // ---- 骨架 ----
@@ -149,11 +175,12 @@ export async function doctorWorkspace(override, opts = {}) {
         required: true,
         detail: missing.length ? `缺 ${missing.join(' ')}` : [...DIRS].map((d) => `${d}/`).join(' '),
         fix: missing.length ? `cotutor init <slug> --dir ${redactHome(root)}(幂等补缺)` : undefined,
+        cmd: missing.length ? initCmd() : undefined,
     });
     // 老布局(2026-10-30 之前):老师文件在 .claude/agents/、技能在 .claude/skills/,现在都读不到了
     const legacy = await legacyLayout(root);
     if (legacy.length)
-        push({ name: 'layout', ok: false, required: true, detail: `${legacy.join(' ')} 是老位置:老师文件现在在 agents/<老师>.md,技能在 ${SKILLS_DIR}/`, fix: 'cotutor upgrade(原样挪过去,不改内容;新位置已有同名的不挪、会点名)' });
+        push({ name: 'layout', ok: false, required: true, detail: `${legacy.join(' ')} 是老位置:老师文件现在在 agents/<老师>.md,技能在 ${SKILLS_DIR}/`, fix: 'cotutor upgrade(原样挪过去,不改内容;新位置已有同名的不挪、会点名)', cmd: upgrade });
     // 家规(根的 QWEN.md)2026-09-15 起不出厂:有就是家长自建的共同规矩,提一句;没有不缺
     const rulesThere = (await Promise.all(['QWEN.md'].map(async (f) => ((await statOrNull(join(root, f))) ? f : null)))).filter(Boolean);
     push({ name: 'rules', ok: true, required: false, detail: rulesThere.length ? `家长自建的家规 ${rulesThere.join(' ')} 在,所有老师每轮都读` : '没有根目录的 QWEN.md(不需要:老师要知道的都在老师文件与技能里)' });
@@ -184,6 +211,7 @@ export async function doctorWorkspace(override, opts = {}) {
                     : shipped
                         ? `cotutor init 补拷(拷自本包 agents/${name}.md),或把老师键改成文件里的 name`
                         : `这是自家加的老师:写 agents/${name}.md(frontmatter name: ${name}),cotutor add ${name} --display <显示名> 可出模板;或把 cotutor.json 里这条删掉`,
+                cmd: !ok && shipped ? initCmd() : undefined,
             });
             const st = statuses.get(name);
             if (!st)
@@ -196,11 +224,12 @@ export async function doctorWorkspace(override, opts = {}) {
                     required: false,
                     detail: label[st.state],
                     fix: st.state === 'upgradable' ? 'cotutor upgrade 换新版' : undefined,
+                    cmd: st.state === 'upgradable' ? upgrade : undefined,
                 });
             }
             const home = join(ws.dirs.agents, name);
             const there = (await statOrNull(home))?.isDirectory() ?? false;
-            push({ name: `tutor.${name}.home`, ok: there, required: true, detail: there ? `agents/${name}/ 在(会话 cwd)` : `agents/${name}/ 不在`, fix: there ? undefined : 'cotutor init 补建' });
+            push({ name: `tutor.${name}.home`, ok: there, required: true, detail: there ? `agents/${name}/ 在(会话 cwd)` : `agents/${name}/ 不在`, fix: there ? undefined : 'cotutor init 补建', cmd: there ? undefined : initCmd() });
             // 音色:一老师一音色走 API 是正路;没配的孩子端只剩浏览器合成声(只该在测试里);hidden 的老师不对孩子说话,不用音色
             const tc = ws.config.tutors[name];
             if (tc.enabled && !tc.hidden && !cardVoice(ws.config.tutors, name))
@@ -234,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')
@@ -259,11 +293,11 @@ export async function doctorWorkspace(override, opts = {}) {
             const { CLAUDE_SKILLS_LINK, skillStatuses } = await import("./skills.js");
             for (const sk of teachingPack ? await skillStatuses(root) : []) {
                 const label = { latest: sk.machine ? '机器件,最新' : '出厂件,最新', upgradable: sk.machine ? '机器件,和包里不一样(改过或包已更新)' : `出厂件,基于 ${sk.basedOn},包已更新`, custom: `自定义(基于 ${sk.basedOn})`, untracked: '自定义(没有出厂记录)', missing: sk.machine ? '缺(机器件,老师或家长的技能靠它)' : '缺' };
-                push({ name: `skill.${sk.name}`, ok: sk.state !== 'missing' && sk.state !== 'upgradable', required: Boolean(sk.machine), detail: `${SKILLS_DIR}/${sk.name}/:${label[sk.state]}`, fix: sk.state === 'missing' ? 'cotutor init 补拷' : sk.state === 'upgradable' ? 'cotutor upgrade 换新版' : undefined });
+                push({ name: `skill.${sk.name}`, ok: sk.state !== 'missing' && sk.state !== 'upgradable', required: Boolean(sk.machine), detail: `${SKILLS_DIR}/${sk.name}/:${label[sk.state]}`, fix: sk.state === 'missing' ? 'cotutor init 补拷' : sk.state === 'upgradable' ? 'cotutor upgrade 换新版' : undefined, cmd: sk.state === 'missing' ? initCmd() : sk.state === 'upgradable' ? upgrade : undefined });
             }
             // Claude Code 只认 .claude/skills:那里该是指向 .agents/skills 的链;老师用不到,家长在 workspace 里用 Claude Code 才要
             const linked = (await lstat(join(root, CLAUDE_SKILLS_LINK)).catch(() => null))?.isSymbolicLink() ?? false;
-            push({ name: 'skills.claude', ok: linked, required: false, detail: linked ? `${CLAUDE_SKILLS_LINK} 链到 ${SKILLS_DIR}(Claude Code 读的是同一份)` : `${CLAUDE_SKILLS_LINK} 不是链,在 workspace 里用 Claude Code 看不到 ${SKILLS_DIR}/ 的技能`, fix: linked ? undefined : 'cotutor upgrade 建链(是实体目录的话先把里面的挪进 .agents/skills/ 再删掉)' });
+            push({ name: 'skills.claude', ok: linked, required: false, detail: linked ? `${CLAUDE_SKILLS_LINK} 链到 ${SKILLS_DIR}(Claude Code 读的是同一份)` : `${CLAUDE_SKILLS_LINK} 不是链,在 workspace 里用 Claude Code 看不到 ${SKILLS_DIR}/ 的技能`, fix: linked ? undefined : 'cotutor upgrade 建链(是实体目录的话先把里面的挪进 .agents/skills/ 再删掉)', cmd: linked ? undefined : upgrade });
             // ---- activity:老师的家里 agents/<老师>/activities/<名>.md;出厂的看新旧,每份都过一遍 activity check ----
             {
                 const { activityStatuses, checkActivities } = await import("./activities.js");
@@ -271,7 +305,7 @@ export async function doctorWorkspace(override, opts = {}) {
                 const label = { latest: '出厂件,最新', upgradable: '出厂件,包已更新', custom: '自定义', untracked: '自定义(没有出厂记录)', missing: '缺', broken: '读不到' };
                 for (const s of states.values())
                     if (s.state === 'missing')
-                        push({ name: `activity.${s.key}`, ok: false, required: false, detail: `agents/${s.key.replace('/', '/activities/')}.md 不在`, fix: 'cotutor init 补拷' });
+                        push({ name: `activity.${s.key}`, ok: false, required: false, detail: `agents/${s.key.replace('/', '/activities/')}.md 不在`, fix: 'cotutor init 补拷', cmd: initCmd() });
                 // 学科色:手改 cotutor.json 写的颜色,新话题气泡的白字要压得住
                 for (const [name, t] of Object.entries(ws.config.tutors)) {
                     if (!t.color)
@@ -295,6 +329,7 @@ export async function doctorWorkspace(override, opts = {}) {
                         required: false,
                         detail: fixes.length ? `${origin};${fixes.length} 条要改,第一条:${fixes[0].line ? `第 ${fixes[0].line} 行 ` : ''}${fixes[0].text}` : origin,
                         fix: fixes.length ? `cotutor activity check ${r.tutor} ${r.name} 看全` : st?.state === 'upgradable' ? 'cotutor upgrade 换新版' : undefined,
+                        cmd: !fixes.length && st?.state === 'upgradable' ? upgrade : undefined,
                     });
                 }
             }
@@ -308,7 +343,7 @@ export async function doctorWorkspace(override, opts = {}) {
                     push({ name: 'theme.manifest', ok: true, required: false, detail: `themes/${name}/:${Object.keys(t.manifest.tints).length} 个底色槽、${Object.keys(t.manifest.looks).length} 个字形槽、${Object.keys(t.manifest.pens).length} 支笔,default = ${t.manifest.default}` });
                 }
                 catch (err) {
-                    push({ name: 'theme.manifest', ok: false, required: false, detail: `themes/${name}/ 用不了(服务退回出厂 default):${err instanceof Error ? err.message : String(err)}`, fix: name === 'default' ? 'cotutor init 补拷(已有的不动)或 cotutor upgrade' : `修 themes/${name}/theme.json 与 kid.css,或把 cotutor.json 的 kid.theme 改回 default` });
+                    push({ name: 'theme.manifest', ok: false, required: false, detail: `themes/${name}/ 用不了(服务退回出厂 default):${err instanceof Error ? err.message : String(err)}`, fix: name === 'default' ? 'cotutor init 补拷(已有的不动)或 cotutor upgrade' : `修 themes/${name}/theme.json 与 kid.css,或把 cotutor.json 的 kid.theme 改回 default`, cmd: name === 'default' ? initCmd() : undefined });
                 }
                 for (const th of teachingPack ? await themeStatuses(root) : []) {
                     if (!th.shipped) {
@@ -316,7 +351,7 @@ export async function doctorWorkspace(override, opts = {}) {
                         continue;
                     }
                     const label = { latest: '出厂件,最新', upgradable: `出厂件,基于 ${th.basedOn},包已更新`, custom: `自定义(基于 ${th.basedOn})`, untracked: '自定义(没有出厂记录)', missing: '缺' };
-                    push({ name: `theme.${th.name}.origin`, ok: th.state !== 'missing' && th.state !== 'upgradable', required: false, detail: `themes/${th.name}/:${label[th.state]}`, fix: th.state === 'missing' ? 'cotutor init 补拷' : th.state === 'upgradable' ? 'cotutor upgrade 换新版' : undefined });
+                    push({ name: `theme.${th.name}.origin`, ok: th.state !== 'missing' && th.state !== 'upgradable', required: false, detail: `themes/${th.name}/:${label[th.state]}`, fix: th.state === 'missing' ? 'cotutor init 补拷' : th.state === 'upgradable' ? 'cotutor upgrade 换新版' : undefined, cmd: th.state === 'missing' ? initCmd() : th.state === 'upgradable' ? upgrade : undefined });
                 }
             }
         }
@@ -442,8 +477,10 @@ export async function doctorWorkspace(override, opts = {}) {
         push({ name: 'server.access', ok: pin !== null, required: false, detail: pin ? '已设 PIN' : '家长端、工作台没上锁', fix: pin ? undefined : 'cotutor pin' });
         // ---- HTTPS:iPad 上录音要;没有只提醒 ----
         const tls = httpsFiles(ws);
-        const { mkcertHint } = await import("./cert.js");
-        push({ name: 'https', ok: tls !== null, required: false, detail: tls ? `${redactHome(tls.cert)}` : '没有证书,serve 走 HTTP(平板、手机上按住说话不可用)', fix: tls ? undefined : `cotutor cert(需要 mkcert:${mkcertHint()})` });
+        const { mkcertHint, mkcertReady } = await import("./cert.js");
+        // mkcert -install 要开机密码或点弹窗,是人的事;做过了,签证书就不用人了
+        const canSign = !tls && probeEnv && await mkcertReady();
+        push({ name: 'https', ok: tls !== null, required: false, detail: tls ? `${redactHome(tls.cert)}` : '没有证书,serve 走 HTTP(平板、手机上按住说话不可用)', fix: tls ? undefined : `cotutor cert(需要 mkcert:${mkcertHint()}),签完 cotutor service restart`, cmd: canSign ? 'cotutor cert' : undefined });
         // ---- 百炼:老师靠实时模型开口,没配孩子端打不开;--live 真试连一次(握手就挂,不花钱) ----
         // key 只认 ~/.config/cotutor/(2026-11-02 起);shell 里还 export 着旧的,说一句免得以为配了
         const bl = dashscopeAuth(env);
@@ -502,14 +539,18 @@ export async function doctorWorkspace(override, opts = {}) {
             if (traySupported(process.platform)) {
                 const t = await trayStatus({ ...realHost(), env }).catch(() => null);
                 if (t && !t.off)
-                    push({ name: 'tray', ok: t.installed, required: false, detail: t.installed ? `托盘图标装了${t.running ? ',在跑' : ',现在没在跑(点过退出,下次登录回来)'}` : '没装托盘图标:看状态只能开终端', fix: t.installed ? undefined : 'cotutor tray on' });
+                    push({ name: 'tray', ok: t.installed, required: false, detail: t.installed ? `托盘图标装了${t.running ? ',在跑' : ',现在没在跑(点过退出,下次登录回来)'}` : '没装托盘图标:看状态只能开终端', fix: t.installed ? undefined : 'cotutor tray on', cmd: t.installed ? undefined : 'cotutor tray on' });
             }
         }
         if (!s)
-            push({ name: 'service', ok: false, required: false, detail: '没装后台服务:在终端里跑的 cotutor serve,关了终端就停', fix: 'cotutor service install(登录后自己起来、崩了自己再起)' });
+            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));
-            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 });
+            // 还没坏,但 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 });
         }
     }
     if (probeEnv && process.platform === 'darwin') {
@@ -528,6 +569,13 @@ 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 : '设置 › 系统 › 电源和电池 › 屏幕、睡眠和休眠超时,「插入电源时,使设备在以下时间后进入睡眠状态」选「从不」;合盖看「电源按钮和盖子」那一项' });
     }
+    // ---- 有没有新版本:只看服务问来存下的那份,体检不上网;什么时候升级家长定(要重起服务,孩子可能在上课),所以没有 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(' ; ')}` });
+    }
     // ---- 用户配置 ----
     try {
         const text = await readFile(USER_CONFIG, 'utf8');
@@ -547,7 +595,7 @@ export async function doctorWorkspace(override, opts = {}) {
         push({ name: 'sandbox', ok: true, required: false, detail: `试用 workspace:${ws.sandbox.forkedAt.slice(0, 10)} 从 ${redactHome(ws.sandbox.from)} 分出来;--sandbox --fresh 重新分` });
     else {
         const gitThere = (await statOrNull(join(root, '.git'))) !== null;
-        push({ name: 'git', ok: gitThere, required: false, detail: gitThere ? 'workspace是 git 仓' : 'workspace不在 git 里', fix: gitThere ? undefined : '建议 git init:老师记忆、账本、政策都是不可再生状态' });
+        push({ name: 'git', ok: gitThere, required: false, detail: gitThere ? 'workspace是 git 仓' : 'workspace不在 git 里', fix: gitThere ? undefined : '建议 git init:老师记忆、账本、政策都是不可再生状态', cmd: gitThere ? undefined : `git init ${quoted}` });
     }
-    return { ok: checks.filter((c) => c.required).every((c) => c.ok), root, source, checks };
+    return finish({ ok: checks.filter((c) => c.required).every((c) => c.ok), root, source, checks });
 }

package/dist/app/cli/init.js

@@ -150,7 +150,7 @@ 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 service install 装成后台服务(登录后自己起来、关了终端照样跑;在终端里调试用 cotutor serve),cotutor open 打开家长端,在「首页」填百炼的按量 API Key 与业务空间 ID(老师的嘴和脑都用它;没填孩子端只出「老师们还没到」)');
+    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 逐项体检');

package/dist/app/cli/main.js

@@ -21,11 +21,15 @@ import { addTheme, upgradeThemes } from "./themes.js";
 import { patchConfig } from "../workspace.js";
 import { resolveRoot } from "../workspace.js";
 import { bindFailure, portHolder, whoHolds } from "./port.js";
-import { httpsFiles, serveWorkspace, siteUrl } from "./serve.js";
+import { certCovers, httpsFiles, localName, serveWorkspace, siteUrl } from "./serve.js";
+import { dashscopeAuth } from "../../realtime/bailian.js";
 import { teeLogs } from "./serve-log.js";
-import { controlService, earlyLogHint, findService, installService, listServices, probeHealth, realHost, runKeeper, servicePlatform, serviceStatus, tailLog, uninstallService, waitHealthy } from "./service.js";
+import { controlService, earlyLogHint, findService, installService, listServices, opensAfterInstall, probeHealth, realHost, runKeeper, servicePlatform, serviceStatus, tailLog, uninstallService, waitHealthy } from "./service.js";
 import { openSandbox } from "./sandbox.js";
-import { dropTrayIfNoServices, ensureTray, installTray, removeTray, trayDir, trayStatus, traySupported } from "./tray.js";
+import { dropTrayIfNoServices, ensureTray, installTray, openTarget, refreshTray, removeTray, trayDir, trayStatus, traySupported } from "./tray.js";
+import { BUILD } from "../build.js";
+import { startUpdateChecks } from "../machine/update.js";
+import { isNewer, upgradeSteps } from "../../shared/upgrade.js";
 import { serveMock } from "../mock/mock.js";
 import { UsageError, loadWorkspace, redactDeep, redactHome, workspaceReport } from "../workspace.js";
 import { USAGE } from "./usage.js";
@@ -74,20 +78,15 @@ function parseArgs(argv, valued) {
     return { cmd, positionals, flags };
 }
 /** 用默认浏览器打开(各系统各自的打开命令,失败不吭声) */
-async function openInBrowser(page) {
-    const { spawn } = await import('node:child_process');
-    const [cmd, args] = process.platform === 'darwin' ? ['open', [page]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', page]] : ['xdg-open', [page]];
-    spawn(cmd, args, { stdio: 'ignore', detached: true }).on('error', () => { }).unref();
-}
 /** 打开哪一页的那一行(地址独占行尾:后面紧跟全角括号的话,终端不把它认成链接);--open(旧名 --open-qr)顺手打开 */
-async function printOpen(label, page, hint, open) {
+function printOpen(label, page, hint, open) {
     process.stdout.write(`  ${label} ${page}\n${' '.repeat(label.length * 2 + 3)}${hint}\n`);
     if (open)
-        await openInBrowser(page);
+        openTarget(process.platform, page);
 }
 const wantsOpen = (flags) => flags.open === true || flags['open-qr'] === true;
 /** 不用 workspace 的命令:--sandbox 对它们没有意义 */
-const NO_WORKSPACE = ['grades', 'init', 'mock', 'pin', 'cert', 'tray'];
+const NO_WORKSPACE = ['grades', 'init', 'mock', 'pin', 'cert', 'tray', 'update'];
 export async function main(argv) {
     let json = false;
     try {
@@ -197,6 +196,9 @@ export async function main(argv) {
                     r.ctx.runner.onEvent((e) => { if (keep(e.event))
                         process.stdout.write(`${e.tutor} ${e.job} ${formatEvent(e.event)}\n`); });
                 }
+                // 有没有新版本:从仓库跑的是开发,不问(npm 的提醒对它没意义);测试起的 serve 也都在仓库里
+                if (!BUILD.commit)
+                    startUpdateChecks();
                 process.stdout.write(`cotutor serve ${JSON.stringify(workspaceReport(r.ws))}\n`);
                 if (r.ws.sandbox)
                     process.stdout.write(`  试用:从 ${redactHome(r.ws.sandbox.from)} 分出来,对话、照片、vault 的写入都留在这里,不进孩子的记录;--sandbox --fresh 重新分\n`);
@@ -205,7 +207,7 @@ export async function main(argv) {
                 if (!r.https)
                     process.stdout.write('  ! HTTP:平板、手机上按住说话要 HTTPS;cotutor cert 建证书后重启即走 HTTPS\n');
                 // 只给家长端一个入口:孩子的平板扫码、排首页、记录都在里面,工作台从它的右上角进
-                await printOpen('家长端', r.parentPage, '在这台电脑上打开:孩子的平板扫码、排首页、看记录都在里面;--open 顺手打开', wantsOpen(flags));
+                printOpen('家长端', r.parentPage, '在这台电脑上打开:孩子的平板扫码、排首页、看记录都在里面;--open 顺手打开', wantsOpen(flags));
                 return;
             }
             case 'open': {
@@ -225,7 +227,7 @@ export async function main(argv) {
                     return;
                 }
                 if (!json && flags.print !== true)
-                    await openInBrowser(page);
+                    openTarget(process.platform, page);
                 return;
             }
             case 'tray': {
@@ -299,6 +301,12 @@ export async function main(argv) {
                             : `! 后台服务读不到 vault(${redactHome(ws.paths.vault)}):看看这个目录的权限,然后 cotutor service restart`);
                     if (h?.version && h.version !== version())
                         out.push(`! 在跑的是 ${h.version},装的是 ${version()}:cotutor service restart 换上新的`);
+                    if (h?.bailianTrouble)
+                        out.push(`! ${h.bailianTrouble.message}:${h.bailianTrouble.fix}`);
+                    if (h?.scheme === 'http' && httpsFiles(ws))
+                        out.push('! 证书有了,服务还在走 HTTP(平板上按住说话不可用):cotutor service restart');
+                    if (isNewer(h?.latest, version()))
+                        out.push(`! 有新版本 ${h?.latest}(现在是 ${version()}),升级运行:${upgradeSteps().join(' ; ')}`);
                     return out;
                 };
                 const tellLog = async (dir) => {
@@ -356,8 +364,9 @@ export async function main(argv) {
                         process.stdout.write(`  ${platform === 'darwin' ? '菜单栏' : '任务栏'}多了 cotutor 图标:不用开终端就能看状态、打开家长端${tray === 'later' ? '(这个会话里没起来,下次登录出现)' : platform === 'win32' ? '(新图标先收在右下角的 ^ 里)' : ''};不要它:cotutor tray off\n`);
                     else if (tray === 'failed')
                         process.stdout.write('  ! 图标没装上,服务不受影响;cotutor tray on 再试\n');
+                    const opening = opensAfterInstall({ firstTime: !had, open: wantsOpen(flags), noOpen: flags['no-open'] === true, platform, env: process.env });
                     if (h) {
-                        await printOpen('家长端', parentPage, '孩子的平板扫码、排首页、看记录都在里面', wantsOpen(flags));
+                        printOpen('家长端', parentPage, `${opening ? '刚帮你打开了:' : ''}孩子的平板扫码、排首页、看记录都在里面`, opening);
                         for (const n of notes(h))
                             process.stdout.write(`${n}\n`);
                     }
@@ -393,6 +402,9 @@ export async function main(argv) {
                         return;
                     }
                     const h = await waitHealthy(port, 20_000, before?.started);
+                    // 升级后跑的就是这一条:图标进程不归服务管,不换就还是旧代码,要等下次登录。它出问题不算重起失败
+                    if (sub === 'restart')
+                        await refreshTray(host).catch(() => false);
                     if (h) {
                         process.stdout.write(`${sub === 'start' ? '起来了' : '重起了'}:pid ${h.pid ?? '?'},版本 ${h.version ?? '?'}\n`);
                         for (const n of notes(h))
@@ -409,8 +421,25 @@ export async function main(argv) {
                     const st = await serviceStatus(host, root, port);
                     // 没答应时看看是不是别的程序占着:后台服务遇到这种情况只写一句日志就不起了,这里要说得出来
                     const holder = st.health ? null : await portHolder(host, port);
+                    // 地址按实际走的协议算:签了证书还没重起时仍是 http
+                    const served = st.health?.scheme ?? scheme;
+                    const page = siteUrl(served, 'localhost', port, '/parent/home');
                     if (json) {
-                        process.stdout.write(`${JSON.stringify(redactDeep({ ...st, portHolder: holder, version: version(), parentPage }), null, 2)}\n`);
+                        // 一次答清「装好没有」(INSTALL.md 靠它):服务、平板地址、证书、百炼、图标、版本
+                        const name = localName();
+                        const tls = httpsFiles(ws);
+                        const tray = traySupported(host.platform) ? await trayStatus(host) : null;
+                        process.stdout.write(`${JSON.stringify(redactDeep({
+                            ...st,
+                            portHolder: holder,
+                            version: version(),
+                            parentPage: page,
+                            tabletUrl: siteUrl(served, name, port),
+                            cert: { present: Boolean(tls), coversName: tls ? certCovers(tls.cert, name) : false, serving: st.health?.scheme === 'https' },
+                            bailian: Boolean(dashscopeAuth()),
+                            tray: tray && { installed: tray.installed, running: tray.running },
+                            latest: isNewer(st.health?.latest, version()) ? st.health?.latest : null,
+                        }), null, 2)}\n`);
                         return;
                     }
                     if (!st.installed)
@@ -419,7 +448,7 @@ export async function main(argv) {
                         process.stdout.write(`后台服务:装了 ${st.installed.label}(${redactHome(st.installed.file)})\n  ${st.running ? `在跑:pid ${st.pid ?? '?'}` : `没在跑${st.lastExit ? `(上次退出:${st.lastExit})` : ''};cotutor service start`}\n`);
                     const h = st.health;
                     if (h)
-                        process.stdout.write(`  端口 ${port} 答应:${h.mode === 'service' ? '后台服务' : `终端里的 cotutor serve(pid ${h.pid ?? '?'})`},版本 ${h.version ?? '?'},起来于 ${when(h.started)}\n  家长端 ${parentPage}\n`);
+                        process.stdout.write(`  端口 ${port} 答应:${h.mode === 'service' ? '后台服务' : `终端里的 cotutor serve(pid ${h.pid ?? '?'})`},版本 ${h.version ?? '?'},起来于 ${when(h.started)}\n  家长端 ${page}\n`);
                     else
                         process.stdout.write(holder ? `  端口 ${port} 没答应,被占着:${holder.name}(pid ${holder.pid})在用。腾出来以后 cotutor service start;或改 cotutor.json 的 server.port,平板要重新扫码、重加主屏幕图标\n` : `  端口 ${port} 没答应\n`);
                     for (const n of notes(h))
@@ -491,7 +520,7 @@ export async function main(argv) {
                 for (const u of r.urls)
                     process.stdout.write(`  ${u}\n`);
                 process.stdout.write('  孩子端 /,家长端 /parent;直接开某位老师:/?tutor=chinese-tutor\n');
-                await printOpen('扫码页', r.qrPage, '在这台电脑上打开,平板、手机用相机扫;--open 顺手打开', wantsOpen(flags));
+                printOpen('扫码页', r.qrPage, '在这台电脑上打开,平板、手机用相机扫;--open 顺手打开', wantsOpen(flags));
                 return;
             }
             case 'add': {
@@ -525,6 +554,16 @@ export async function main(argv) {
                     process.stdout.write(`加了主题 ${name}(拷自 ${r.from}):\n  ${redactHome(r.dir)}/theme.json  ← 槽的清单(名字 + 给什么用)\n  ${redactHome(r.dir)}/kid.css     ← 样式,改了刷新就有\n把 cotutor.json 的 kid.theme 改成 "${name}" 就换过去了(服务不用重启)。\n`);
                 return;
             }
+            case 'update': {
+                const { realUpdateDeps, runUpdate } = await import("./update-cmd.js");
+                process.exitCode = await runUpdate(realUpdateDeps(() => { try {
+                    return resolveRoot(workspace).root;
+                }
+                catch {
+                    return null;
+                } }), { anyway: flags.anyway === true });
+                return;
+            }
             case 'upgrade': {
                 if (flags.grade !== undefined)
                     throw new UsageError('upgrade 只更新已安装的教学包,不能用 --grade 切换年级');
@@ -699,6 +738,8 @@ export async function main(argv) {
                     process.stdout.write(`  iPad / iPhone:${send} → 设置里安装描述文件 → 通用 › 关于本机 › 证书信任设置里**把开关打开**(装了不等于信任)\n`);
                     process.stdout.write(`  安卓:${process.platform === 'darwin' ? '传到设备上' : send} → 设置里搜「CA 证书」,按提示安装(各家菜单不一样,会提示「网络可能受到监控」)\n`);
                     process.stdout.write(`然后 cotutor service restart(在终端里跑的就重开 cotutor serve),cotutor open 打开家长端,用相机扫「扫码打开」那张。地址认电脑名,换 Wi-Fi、IP 变了都不用重签;改了电脑名才要重跑这条。详见 docs/iPad与iPhone.md\n`);
+                    if (!r.trusted)
+                        process.stdout.write(`! 这台电脑还没信任根证书,浏览器打开家长端会报证书警告。请在这台电脑的终端里自己跑一次 mkcert -install(${process.platform === 'win32' ? '弹窗问时点「是」' : '要输开机密码'}),不用重签\n`);
                 }
                 return;
             }

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

@@ -25,7 +25,6 @@ export interface ServeResult {
     parentPage: string;
     warnings: string[];
 }
-/** 证书路径:cotutor.json 的 server.https 优先(相对 workspace 根),否则机器级 ~/.config/cotutor/certs/;都没有 → null */
 export declare function httpsFiles(ws: Workspace): {
     cert: string;
     key: string;