cotutor 0.4.3 → 0.4.5

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# 更新说明
+
+写给家长：每个版本改了什么。升级跑 `cotutor update`（Windows 上 `cotutor.cmd update`），详见 README 的「数据与升级」。
+
+## 0.4.5
+
+- 让 AI 助手帮你装更省事:不用输网址,对它说「帮我在这台电脑上装 cotutor,先跑 npx cotutor@latest guide,照它说的一步步做」
+- 孩子的笔记文件夹(档案、日记、老师的记忆)新装时放在 cotutor 文件夹旁边,也可以用你已有的 Obsidian 库;以前装的照旧能用
+- Linux 上的后台服务能起来了
+- 命令更好懂:cotutor --help 只列命令,每条的用法和例子在它自己的帮助里;写错的选项会直接说哪里不对,不再悄悄忽略
+- 换新出厂文件改叫 cotutor refresh,把改过的老师换回出厂的用 cotutor reset;升级还是 cotutor update
+
+## 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/INSTALL.md

@@ -0,0 +1,159 @@
+# 在家长的电脑上安装 cotutor
+
+这篇写给替家长安装的 AI 助手。cotutor 是家里的 AI 老师团：程序装在家长的电脑上，孩子在平板上用。要开发本仓库，看 `AGENTS.md`。
+
+这篇随 npm 包发：`npx cotutor@latest guide` 打印的就是它，和 npm 上最新的版本对得上。npx 只是临时取来看，第 2 步照样要装；装好以后 `cotutor guide` 还能再看。
+
+- **能跑命令的：** 照下面一步步跑。每步先看「成功」；不符合再看「不成功」。这里没写的 cotutor 命令不要自己编，用法不确定就看那条命令的帮助，如 `cotutor service --help`。写错了的选项、多余的参数，cotutor 会报错（退出码 2）并说是哪里不对，照它改，不要换着写法硬试。
+- **不能跑命令的（网页聊天）：** 一次只告诉家长一步，等家长贴回结果再走下一步。
+- **【交给家长】的步骤必须停下：** 告诉家长做什么，等家长说做完了再继续。不要替家长做，也不要绕过去。
+
+跟家长说话时用家常话：`slug` 说成「孩子的短名」，workspace 说成「孩子的 cotutor 文件夹」（具体到人：「小明的 cotutor 文件夹」），vault 说成「孩子的笔记文件夹」。
+
+## 不能做
+
+- 不要让家长把百炼的 API Key 贴进对话，对话内容会传到你的厂商那里。家长贴了，提醒他们到百炼控制台换一把。也不要读 `~/.config/cotutor/bailian.json`。
+- 不要 `git clone` 本仓库，用 npm 装。
+- 不要用 `sudo` 跑 npm。
+- 不要跑 `cotutor reset`：它把家长改过的老师换回出厂的。家长明确说要回出厂的才跑。
+- 不要跑 `cotutor backup restore`，除非家长明确说要恢复。
+- 不要删孩子的 cotutor 文件夹（缺省 `~/cotutor/<slug>/`）和笔记文件夹（vault，缺省在旁边的 `~/cotutor/<slug>-vault/`），里面的记录删了找不回来。
+- 不要关防火墙，不要改系统安全设置或 PowerShell 执行策略。
+
+## 1. 看环境
+
+```sh
+node -v
+```
+
+**成功：** `v22.18` 或更高。系统是 macOS、Windows 或 Linux。
+
+**不成功：** 没有 Node 或版本太低：**【交给家长】** 到 https://nodejs.org 装 LTS 版，装完重开终端。Linux 上不要用系统自带的 `apt install nodejs`（Ubuntu 22.04 给的是 12，太旧），照 nodejs.org 上 Linux 的装法来；已经用 nvm、asdf 装了合适版本的不用动。
+
+**已经装过：** 如果 `cotutor doctor --json` 能跑，而且 `root` 不是 `null`，这台电脑已经有孩子的 cotutor 文件夹了。问家长是要升级，还是再加一个孩子。升级看 README 的「数据与升级」，这篇不用接着做。再加一个孩子就接着做，并且从第 4 步起，除 `cotutor cert` 外，每条 cotutor 命令都加 `--workspace ~/cotutor/<slug>`。
+
+## 2. 装程序
+
+```sh
+npm i -g cotutor
+cotutor --version
+```
+
+**成功：** 打印出版本号。
+
+**不成功：**
+- 下载慢或超时：加上 `--registry=https://registry.npmmirror.com` 再装一次。
+- 报 `EACCES`（没权限）：不要加 `sudo`。跑 `npm config set prefix ~/.npm-global`，把 `~/.npm-global/bin` 加进 PATH，再装一次。
+- 找不到 `cotutor`：重开终端再试。Node 是 asdf 装的，跑 `asdf reshim nodejs`。还不行，跑 `npm prefix -g` 看装到了哪，把那个目录下的 `bin`（Windows 上是目录本身）加进 PATH。
+- Windows 的 PowerShell 说禁止运行脚本：这篇里所有的 `npm`、`cotutor` 都改用 `npm.cmd`、`cotutor.cmd`。不要改执行策略。
+- Windows 的 PowerShell 里 cotutor 的中文成了乱码（中文系统按代码页 936 解）：先在这个终端里跑 `[Console]::OutputEncoding = [Text.Encoding]::UTF8` 再看。只管这个终端，不改系统设置。
+
+## 3. 建孩子的 cotutor 文件夹和笔记文件夹
+
+问家长三件事：
+- **短名（slug）：** 小写字母、数字、连字符，如 `ming`。不要用真名，它会出现在路径和对话里。
+- **称呼：** 老师怎么叫孩子，小名就行。
+- **年级：** 1 到 6。
+
+```sh
+cotutor grades --json
+cotutor init <slug> --name <称呼> --grade <年级>
+```
+
+**成功：** 第一行是「cotutor init →」加文件夹路径，缺省是 `~/cotutor/<slug>/`。cotutor 的输出把家目录写成 `$HOME`（为了不把用户名传出去），`$HOME/cotutor/<slug>` 就是这个文件夹，不是别的地方。重复跑只补缺，已有的文件不动。
+
+**笔记文件夹（vault）：** init 还在旁边建了笔记文件夹，缺省是 `~/cotutor/<slug>-vault/`，输出里括号写着「笔记文件夹」的那一行就是它。孩子的档案 `孩子.md`、日记、老师的记忆都在这里，和 cotutor 文件夹分开放。里面全是普通的 markdown 文件：
+- **不用装 Obsidian**，也不要问家长要 Obsidian 库。不要改 `cotutor.json` 的 `paths.vault`，也不要另建 vault。
+- 家长想用 Obsidian 看：装好以后用 Obsidian 打开 `<slug>-vault` 这个文件夹就行。
+- 家长主动说要用自己已有的 Obsidian 库：要在第一次 init 时加 `--vault <库的路径>`。一个孩子一个库，不能放在孩子的 cotutor 文件夹里。Mac 上别用「文稿」「桌面」、iCloud 云盘里的库，后台服务读不到；家长坚持的话，第 4 步会出一行 `!`，照它转告。init 已经跑过了就不要再换（init 会报「不换笔记文件夹」），请家长用 Obsidian 打开 `<slug>-vault`。
+
+**不成功：** 家长说的年级不在 `grades` 列出的里面：这个年级还没有教学包，不要换成别的年级。告诉家长，问他们想怎么办。
+
+## 4. 装后台服务
+
+```sh
+cotutor service install --no-open
+```
+
+`--no-open` 是先不打开家长端，第 7 步再开：第 6 步切到 HTTPS 后，之前开的页面会打不开。
+
+**成功：** 退出码 0，输出里有「后台服务」和「家长端」两行。Mac 和 Windows 上还会多一个菜单栏（任务栏）图标。以 `!` 开头的行都记下来，第 7 步转告家长。
+
+**不成功：**
+- 退出码不是 0：先看输出里说的原因（Linux 上 systemd 报的错也在里面），再跑 `cotutor service logs`，把原因告诉家长。
+- 说端口上有一个 `cotutor serve` 在终端里跑着：请家长关掉那个终端，再装一次。
+
+**【交给家长】（只在出现时）：**
+- Windows 弹窗问「允许访问」：点允许，平板才连得进来。
+- Linux 输出里有 `sudo loginctl enable-linger`：请家长自己跑那一行，不登录时服务才会继续跑。
+
+## 5. 体检
+
+```sh
+cotutor doctor --fix
+cotutor doctor --json
+```
+
+`--fix` 把能自动修的都修掉（幂等，不碰孩子的数据，不用人输东西）。然后看 `--json` 的输出：`checks` 是一个列表，逐条看 `ok` 为 `false` 的：
+
+- **有 `human: true`：** 不要动手。记下 `detail` 和 `fix`，第 7 步交给家长。
+- **还有 `cmd`：** `--fix` 跑过了还在，说明修不好。停下，把 `detail` 告诉家长，不要试别的办法。
+
+**成功：** 不过的条目里已经没有 `cmd`。这时退出码可能还是 1，没关系：百炼要家长自己填，填之前 `bailian` 这条过不了。
+
+## 6. 让平板能用
+
+平板上按住说话要 HTTPS，所以要签一张证书。
+
+```sh
+cotutor service status --json
+```
+
+`cert.serving` 已经是 `true` 就跳过这一步。
+
+先装 mkcert：
+- Mac：`brew install mkcert`。
+- Windows：`winget install FiloSottile.mkcert`，然后重开终端。
+- Linux（Ubuntu、Debian）：**【交给家长】** 请家长跑 `sudo apt install mkcert libnss3-tools`。`libnss3-tools` 让这台电脑上的 Chrome、Firefox 也认这张证书。
+- 别的情况（别的 Linux 发行版、没有 brew 或 winget）：**【交给家长】** 照 `cotutor doctor --json` 里 `https` 那条的 `fix` 装。
+
+**【交给家长】** 请家长在这台电脑的终端里自己跑 `mkcert -install`。Mac 上要输开机密码，Windows 上弹窗点「是」，Linux 上要输 sudo 密码。密码不要说给你听。Linux 上的 `apt install` 也一样由家长自己跑；不要主动问家长要 sudo 权限，也不要自己试 `sudo`。
+
+家长做完后：
+
+```sh
+cotutor cert
+cotutor service restart
+cotutor service status --json
+```
+
+**成功：** `cert.present`、`cert.coversName`、`cert.serving` 都是 `true`。
+
+**不成功：**
+- 说 PATH 里没有 mkcert：重开终端再试。
+- 说要先跑 `mkcert -install`（包括 `cotutor cert` 输出里以 `!` 开头的那行，这时证书签好了，但这台电脑的浏览器会报警告）：回到上面，交给家长。做完不用重签。
+
+平板上还要装根证书，第 7 步再交给家长：要在家长端里扫码装，家长端第 7 步才打开。
+
+## 7. 告诉家长
+
+```sh
+cotutor service status --json
+```
+
+**成功：** `health.mode` 是 `service`，`health.version` 和 `version` 一样。
+
+**不成功：** `health` 是 `null`：看 `portHolder`（端口被谁占着）和 `cotutor service logs`，把原因告诉家长。解决不了就跑 `cotutor report`，把输出给家长，请家长到 https://github.com/TarsLab/cotutor/issues 反馈；里面没有孩子的对话和 key。
+
+确认成功后，跑 `cotutor open`，在这台电脑上打开家长端。你是经 SSH 装的，或者这台电脑没有图形界面时，`cotutor open` 只打印地址、开不到屏幕上：请家长在这台电脑的浏览器里打开 `parentPage`。再告诉家长这些，安装就结束了：
+
+1. **家长端地址：** `parentPage`。以后 Mac、Windows 上点图标，或者跑 `cotutor open`；登录电脑时不会自己弹出来。
+2. **【交给家长】平板和手机：** 在家长端「首页」的「扫码打开」。每台设备第一次用，先扫「装证书」那张装根证书，再到设置里打开信任开关（步骤见 [iPad 与 iPhone](https://github.com/TarsLab/cotutor/blob/main/docs/iPad与iPhone.md) 的第 3、4 节；安卓的装法在 `cotutor cert` 的输出里）。然后孩子的平板扫「孩子的平板」那张，家长的手机扫「我的手机」那张。不扫码时，平板上要输的地址是 `tabletUrl`。
+3. **后台服务装好了：** 关了终端照样跑，登录这台电脑后自己起来。Mac 看菜单栏的 cotutor 图标，Windows 看任务栏右下角 `^` 里的图标；图标上出橙点是有事要处理，变淡加红点是没在跑。Linux 上没有图标，用 `cotutor service status` 看。
+4. **还要家长做的事：**
+   - **【交给家长】填百炼（必做）：** `bailian` 是 `false` 时，在这台电脑上打开家长端「首页」，填百炼「按量付费」的 API Key 和业务空间 ID，保存前会先试连。控制台右上角先选北京；`sk-sp-` 开头的 Token Plan 不行。没填时孩子端只显示「老师们还没到」。提醒家长：**直接填在页面上，不要贴到对话里。** 只有在这台电脑上打开的家长端才能填；家长不在这台电脑前（比如你是经 SSH 装的），请家长在自己的电脑上开一条转发 `ssh -L 18443:localhost:<parentPage 里的端口> <用户>@<这台电脑>`（`parentPage` 里没写端口就是 443），再打开 `https://localhost:18443/parent/home` 填，这样也算在这台电脑上。或者请家长先在这台电脑的终端里跑 `cotutor pin` 设家长密码，再从别的设备打开家长端填。
+   - **【交给家长】第 4 步记下的 `!` 行和第 5 步记下的 `human` 条目：** 逐条转告。常见的有：设家长端密码（`server.access`：不设的话，同一个网络里的设备都打得开家长端，孩子的平板也打得开；家长在旁边可以不设。要设，请家长自己在这台电脑的终端里跑 `cotutor pin`，密码不要说给你听）、电脑别睡（`mac.sleep`、`windows.sleep`，睡着时平板连不上）。`bailian`、`tts` 填好百炼就好了，不用另外说；档案算不出学期（`vault.profile`）只在 init 没给年级时才会有。
+   - **【交给家长】Linux 上的睡眠：** doctor 不查这一项，直接提醒家长：笔记本合盖默认会睡，要开着盖；GNOME「设置 › 电源」里的「自动挂起」，接着电源时要关。
+5. **孩子的记录在哪：** 档案、日记、老师的记忆在笔记文件夹里（第 3 步的 vault，缺省 `~/cotutor/<slug>-vault/`），用任何文本编辑器都能看能改，装了 Obsidian 就把这个文件夹当库打开。老师写进了什么，家长端「记录」右栏也列着，不要的可以一行一行撤回。档案 `孩子.md` 的正文可以写孩子的情况（性格、喜欢什么、要避开什么），每位老师每个话题开头都会读到。
+
+不用等家长填完。家长填好百炼后，`cotutor doctor --json` 的 `ok` 会变成 `true`。

package/README.md

@@ -2,21 +2,51 @@
 
 家里的 AI 老师团,和家长一起教。几位可以直接对话的老师(数学、语文、英语),孩子在 iPad 上按住说话就能问,家长在自己的页面上看全部过程、管每位老师的性子和规矩。数据全在自家电脑上。
 
-> 家长端与孩子端都能用:老师的回复是一页板书(卡 + 逐句讲稿),家长在幕后把要画出来讲的题做成小课堂;学完家长打星记账进 Obsidian 日记,作业照片在学科老师页上拍。
+> 家长端与孩子端都能用:老师的回复是一页板书(卡 + 逐句讲稿),家长在幕后把要画出来讲的题做成小课堂;学完家长打星记账进日记(普通 markdown,想用 Obsidian 看也行),作业照片在学科老师页上拍。
 
 ## 五分钟用起来
 
-**让 AI 助手帮你装:** 把这句话发给编程助手(Claude Code、Codex 这类能在电脑上跑命令的),或者网页版的聊天机器人,它会一步步带你做。百炼的 Key 由你自己填在页面上,不用告诉它。
+**让 AI 助手帮你装:** 把这句话发给能在电脑上跑命令的 AI 助手(WorkBuddy、Claude Code、Codex 这类),它会一步步带你做。不用输网址:安装说明跟着 npm 包走,和装上的版本对得上。百炼的 Key 由你自己填在页面上,不用告诉它。
 
 ```text
-请阅读 https://raw.githubusercontent.com/TarsLab/cotutor/main/INSTALL.md ,照着在这台电脑上安装 cotutor
+帮我在这台电脑上装 cotutor:先跑 npx cotutor@latest guide,照它说的一步步做。没有 Node 就先告诉我
 ```
 
-**自己装:** 需要一台电脑(Mac 最省事)、Node ≥ 22.18,和一个百炼账号(北京地域,按量付费)。老师的嘴和脑都走百炼,由应用直接调用,不用另装模型客户端:嘴是 `qwen3.8-omni-flash-realtime`,听孩子说、照着讲稿念;脑是 `qwen3.8-max`,写讲稿和板书。
+网页版的聊天机器人跑不了命令,换这句,它会一次告诉你一步:
+
+```text
+请阅读 https://cdn.jsdelivr.net/npm/cotutor@latest/INSTALL.md ,一步一步带我在这台电脑上安装 cotutor
+```
+
+**自己装:** 需要一台电脑(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://cdn.jsdelivr.net/npm/cotutor@latest/install.sh | sh -s -- ming 小明 2
+```
+
+```powershell
+# Windows(PowerShell 里;这行长一点:jsDelivr 不说文件是什么编码,要自己按 UTF-8 解开,不然中文是乱码)
+& ([scriptblock]::Create([Text.Encoding]::UTF8.GetString((iwr -useb https://cdn.jsdelivr.net/npm/cotutor@latest/install.ps1).Content))) ming 小明 2
+```
+
+连不上 jsDelivr 就从 GitHub 取:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/TarsLab/cotutor/main/install.sh | sh -s -- ming 小明 2
+```
+
+```powershell
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/TarsLab/cotutor/main/install.ps1))) ming 小明 2
+```
+
+也可以一条条自己来:
 
 ```sh
 npm i -g cotutor
-cotutor init ming --name 小明 --grade 2     # 建 ~/cotutor/ming/:三位老师、技能、账本、对话目录、cotutor.json
+cotutor init ming --name 小明 --grade 2     # 建 cotutor 文件夹 ~/cotutor/ming/(三位老师、技能、账本、对话目录、cotutor.json)和旁边的笔记文件夹 ~/cotutor/ming-vault/(档案、日记、记忆)
 cotutor service install                    # 装成这台电脑的后台服务,第一次装会打开家长端,孩子的平板在那里扫码
 ```
 
@@ -33,14 +63,14 @@ 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`。
+2. **填档案**:笔记文件夹(vault,`~/cotutor/<孩子>-vault/`)里的 `孩子.md` 写 `school_start`(读一年级的年月,如 `2025-09`;`init --grade` 已经算好了),老师据此知道现在是几年级哪个学期;正文写孩子的情况。笔记文件夹里全是普通 markdown,不用装 Obsidian,想用 Obsidian 看就把它当库打开。想用自己已有的 Obsidian 库,第一次 init 时加 `--vault <路径>`(一个孩子一个库;Mac 上别用「文稿」「桌面」和 iCloud 云盘里的,后台服务读不到)。
 3. **体检**:`cotutor doctor` 逐项检查,不过的每条都带修法。
 
-装好以后也可以让编程助手帮你管:在孩子的文件夹(`~/cotutor/<孩子>/`)里打开 Claude Code 或 Codex,已带的技能直接能用。`cotutor-home` 排孩子的首页,`cotutor-tune` 调老师的口气和规矩,`cotutor-analyze` 分析某次对话为什么那样答。
+装好以后也可以让编程助手帮你管:在孩子的 cotutor 文件夹(`~/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` 签一张
-自签证书(要 mkcert:Mac 上 `brew install mkcert && mkcert -install`;Windows 上 `winget install FiloSottile.mkcert`,重开终端再 `mkcert -install`),把根证书装到平板并打开信任,`cotutor service restart`(在终端里跑的就重开 `cotutor serve`),扫码打开。iPad 的步骤见 [iPad 与 iPhone](docs/iPad与iPhone.md)。
+自签证书(要 mkcert:Mac 上 `brew install mkcert && mkcert -install`;Windows 上 `winget install FiloSottile.mkcert`,重开终端再 `mkcert -install`;Ubuntu、Debian 上 `sudo apt install mkcert libnss3-tools && mkcert -install`),把根证书装到平板并打开信任,`cotutor service restart`(在终端里跑的就重开 `cotutor serve`),扫码打开。iPad 的步骤见 [iPad 与 iPhone](docs/iPad与iPhone.md)。
 
 然后在浏览器里:
 
@@ -57,11 +87,11 @@ Mac 和 Windows 上,`service install` 会一起装一个菜单栏(任务栏)图
 
 出厂文件在 `grades/grade-2/`。三科分别提供预习、检查作业、复习(孩子端老师牌上常驻三块方砖);语文有写话与看图写话,英语有口语课,数学小课堂配合提前做好的课包。家长按教材版本、学期和孩子实际进度设置材料。
 
-孩子当前学期仍由档案决定;升年级不会自动替换家长的老师文件。旧 workspace 执行 `cotutor upgrade` 补记二年级来源,保留自定义内容。贡献其他年级与验证方式见 [年级教学包设计](docs/年级教学包.md)。
+孩子当前学期仍由档案决定;升年级不会自动替换家长的老师文件。旧 workspace 执行 `cotutor refresh` 补记二年级来源,保留自定义内容。贡献其他年级与验证方式见 [年级教学包设计](docs/年级教学包.md)。
 
 ## 老师是文件
 
-每位老师 = 一个 Markdown 文件(frontmatter + 正文即系统提示)+ cotutor.json 里的一条(显示名、头像、音色、开关、政策)+ 自己的目录与对话。出厂三位(数学、语文、英语)随包发布,init **拷贝**进你的老师们,改了就是你家的;`cotutor upgrade` 只换没改过的,改过的打印差异让你定。再加一位:
+每位老师 = 一个 Markdown 文件(frontmatter + 正文即系统提示)+ cotutor.json 里的一条(显示名、头像、音色、开关、政策)+ 自己的目录与对话。出厂三位(数学、语文、英语)随包发布,init **拷贝**进你的老师们,改了就是你家的;`cotutor refresh` 只换没改过的,改过的打印差异让你定;想回出厂的那份,`cotutor reset <老师>`(你那份存成 .bak)。再加一位:
 
 ```sh
 cotutor add science-tutor --display 科学老师 --subject 科学 --avatar 🔬
@@ -110,9 +140,9 @@ import { loadWorkspace } from 'cotutor/workspace';                        // 解
 
 ## 数据与升级
 
-默认 workspace 是 `~/cotutor/<孩子>/`:配置在 `cotutor.json`,老师在 `agents/<老师>.md`,activity 在 `agents/<老师>/activities/`,技能在 `.agents/skills/`,对话在 `conversations/`,账本在 `ledger/`,照片在 `captures/`,课包在 `bundles/`,首页在 `home/`。长期档案、记忆和日记在配置的 Obsidian vault,规则见 [obsidian 仓库设计](docs/obsidian仓库设计.md)。备份时保留整个 workspace 与 vault。
+默认 workspace(孩子的 cotutor 文件夹)是 `~/cotutor/<孩子>/`:配置在 `cotutor.json`,老师在 `agents/<老师>.md`,activity 在 `agents/<老师>/activities/`,技能在 `.agents/skills/`,对话在 `conversations/`,账本在 `ledger/`,照片在 `captures/`,课包在 `bundles/`,首页在 `home/`。长期档案、记忆和日记在 vault(笔记文件夹),和 workspace 分开放:缺省是旁边的 `~/cotutor/<孩子>-vault/`,位置写在 `cotutor.json` 的 `paths.vault`(0.4.4 及以前建的没写,vault 就是 workspace 本身,照旧能用,`cotutor doctor` 的 `vault.separate` 说怎么分开),规则见 [obsidian 仓库设计](docs/obsidian仓库设计.md)。workspace 与 vault 都要留着。
 
-**备份**放在孩子文件夹旁边的 `.backups/<孩子>/`,一份就是一个普通目录。服务开着时每天自动备一份(留 14 份),`cotutor upgrade` 前也备一份(留 5 份),没变的文件不占第二份地方;`cotutor backup` 随时手动备。**录音(wav)不在备份里**,它占了绝大部分地方;想留就自己拷 `conversations/`。硬盘坏了这些也跟着没了,重要的话把 `.backups` 再拷到别处。
+**备份**放在 cotutor 文件夹旁边的 `.backups/<孩子>/`,一份就是一个普通目录。服务开着时每天自动备一份(留 14 份),`cotutor refresh` 前也备一份(留 5 份),没变的文件不占第二份地方;`cotutor backup` 随时手动备。**录音(wav)不在备份里**,它占了绝大部分地方;想留就自己拷 `conversations/`。笔记文件夹里的 md 也备一份(在那一份的 `_vault/` 里);恢复时不动笔记文件夹,只告诉你那份在哪,要不要拿回来你定。硬盘坏了这些也跟着没了,重要的话把 `.backups` 再拷到别处。
 
 ```sh
 cotutor backup list                   # 看有哪些
@@ -133,24 +163,24 @@ cotutor update
 
 ```sh
 npm i -g cotutor                      # 换上新版程序
-cotutor upgrade                       # 更新未修改的出厂老师、activity、主题与技能
+cotutor refresh                       # 更新未修改的出厂老师、activity、主题与技能
 cotutor service restart               # 服务和图标换上新代码(在终端里跑的就重开 serve)
 ```
 
 升完它提示要迁移配置时再跑:
 
 ```sh
-cotutor upgrade --config --dry-run    # 预览 cotutor.json 的迁移
-cotutor upgrade --config              # 执行配置迁移
+cotutor refresh --config --dry-run    # 预览 cotutor.json 的迁移
+cotutor refresh --config              # 执行配置迁移
 ```
 
 家长改过的老师与主题保留并显示差异;机器技能会随版本覆盖。配置迁移补缺,并更新未自定义的旧命令模板,保留自定义配置。换了 Node 版本、或包装到了别处,再 `cotutor service install` 一次。
 
-2026-10-30 之前建的 workspace,老师在 `.claude/agents/`、技能在 `.claude/skills/`。`cotutor upgrade`(或 `init`)先把它们原样挪到新位置,再照常升级;新位置已有同名的不挪,会点名。`.claude/` 里别的文件不动。
+2026-10-30 之前建的 workspace,老师在 `.claude/agents/`、技能在 `.claude/skills/`。`cotutor refresh`(或 `init`)先把它们原样挪到新位置,再照常升级;新位置已有同名的不挪,会点名。`.claude/` 里别的文件不动。
 
 ### 旧 workspace 换运行时
 
-2026-11-02 起不再起命令行(Qwen Code;Claude CLI 更早就去掉了),老师只走应用直连百炼。2026-10-31 之前建的 workspace 缺省走 Qwen Code,doctor 会报「命令行运行时不再支持」:先 `cotutor upgrade --config` 补上出厂的 `api` / `api-flash`,把 `runtimes.default` 和 `tutors.*.runtime` 改成 `api`,在家长端「首页」填好百炼,再删掉 `qwen`、`qwen-flash`(或更早的 Claude)条目。换之前聊的话题照上面「配置模型」说的办:记录照样能看,不导入、不记账。旧 `proxy` 字段可删除,对应命令已移除。
+2026-11-02 起不再起命令行(Qwen Code;Claude CLI 更早就去掉了),老师只走应用直连百炼。2026-10-31 之前建的 workspace 缺省走 Qwen Code,doctor 会报「命令行运行时不再支持」:先 `cotutor refresh --config` 补上出厂的 `api` / `api-flash`,把 `runtimes.default` 和 `tutors.*.runtime` 改成 `api`,在家长端「首页」填好百炼,再删掉 `qwen`、`qwen-flash`(或更早的 Claude)条目。换之前聊的话题照上面「配置模型」说的办:记录照样能看,不导入、不记账。旧 `proxy` 字段可删除,对应命令已移除。
 
 ### 试用不进孩子的记录
 
@@ -162,6 +192,23 @@ cotutor send math-tutor 你好 --sandbox
 cotutor serve --sandbox --fresh       # 丢掉试过的,从真 workspace 重新分(真的那边改了老师文件、vault 也用这个带过来)
 ```
 
+## 卸载
+
+孩子的 cotutor 文件夹(`~/cotutor/<孩子>/`)、笔记文件夹(`~/cotutor/<孩子>-vault/`)和备份(`~/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/activities.d.ts

@@ -37,7 +37,7 @@ export declare function upgradeActivities(root: string, opts?: {
     force?: string[];
 }): Promise<ActivityUpgradeStep[]>;
 /**
- * 只把一个出厂 activity 换回出厂那份(工作台「恢复出厂」,与 upgrade --force 老师/名 同一条路,但不碰别的):
+ * 只把一个出厂 activity 换回出厂那份(工作台「恢复出厂」,与 cotutor reset 老师/名 同一条路,但不碰别的):
  * 现在那份和出厂不一样就先存 .bak。不是出厂的 → UsageError。返回 .bak 的路径(没存就是 null)
  */
 export declare function restoreActivity(root: string, tutor: string, name: string): Promise<{

package/dist/app/cli/activities.js

@@ -102,7 +102,7 @@ export async function installActivities(root) {
             steps.push({ item, action: s.state === 'missing' ? 'created' : 'replaced', note: s.state === 'broken' ? '读不到,重新拷贝' : `拷自本包 ${PACKAGE_VERSION}` });
         }
         else
-            steps.push({ item, action: s.state === 'untracked' ? 'kept' : 'exists', note: s.state === 'custom' ? `自定义(基于 ${s.basedOn})` : s.state === 'upgradable' ? '可升级(cotutor upgrade)' : s.state === 'untracked' ? '已有(没有出厂记录);升级时当自定义对待' : undefined });
+            steps.push({ item, action: s.state === 'untracked' ? 'kept' : 'exists', note: s.state === 'custom' ? `自定义(基于 ${s.basedOn})` : s.state === 'upgradable' ? '可升级(cotutor refresh)' : s.state === 'untracked' ? '已有(没有出厂记录);升级时当自定义对待' : undefined });
     }
     if (touched)
         await writeManifest(root, { ...manifest, version: PACKAGE_VERSION });
@@ -137,7 +137,7 @@ export async function upgradeActivities(root, opts = {}) {
     return steps;
 }
 /**
- * 只把一个出厂 activity 换回出厂那份(工作台「恢复出厂」,与 upgrade --force 老师/名 同一条路,但不碰别的):
+ * 只把一个出厂 activity 换回出厂那份(工作台「恢复出厂」,与 cotutor reset 老师/名 同一条路,但不碰别的):
  * 现在那份和出厂不一样就先存 .bak。不是出厂的 → UsageError。返回 .bak 的路径(没存就是 null)
  */
 export async function restoreActivity(root, tutor, name) {

package/dist/app/cli/cert.js

@@ -23,7 +23,8 @@ export function mkcertHint(platform = process.platform) {
         return 'brew install mkcert && mkcert -install';
     if (platform === 'win32')
         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';
+    // libnss3-tools 给 mkcert 一个 certutil,这台电脑上的 Chrome、Firefox 才认证书(2026-11-09 Ubuntu 22.04 上装过)
+    return '用系统的包管理器装 mkcert(Ubuntu、Debian 上 sudo apt install mkcert libnss3-tools),再 mkcert -install(要 sudo 密码)';
 }
 /** mkcert 在、根证书建过了:cotutor cert 不用人就能跑。mkcert -install 要开机密码或点弹窗,那一步是人的 */
 export async function mkcertReady(caRootOf = async () => (await execFileP('mkcert', ['-CAROOT'], { timeout: 8000 })).stdout.trim()) {

package/dist/app/cli/chalk/main.d.ts

@@ -1,5 +1,4 @@
 type Flags = Record<string, string | true>;
-export declare const CHALK_USAGE = "\u7528\u6CD5:\n  cotutor chalk check <scene.ts|\u76EE\u5F55> [--no-types] [--json]\n  cotutor chalk build <scene.ts|\u76EE\u5F55> [--out <dir>] [--json]\n  cotutor chalk bake <scene.ts|\u8BFE\u5305 id> [--bundles <dir>] [--json]\n  cotutor chalk snap <scene.ts|\u8BFE\u5305 id> [--step <n>] [--no-cursor] [--out <dir>] [--bundles <dir>] [--json]\n  cotutor chalk dub <scene.ts|\u8BFE\u5305 id> [--voice <\u97F3\u8272>] [--tutor <\u8001\u5E08>] [--instruction <\u8BED\u6C14>] [--dry-run] [--bundles <dir>] [--json]\n\u8BFE\u5305\u7F3A\u7701\u5728 workspace \u7684 bundles/(--bundles \u6362);\u573A\u666F\u6E90\u4E0E --out / --bundles \u7684\u76F8\u5BF9\u8DEF\u5F84\u6309\u5F53\u524D\u76EE\u5F55\u3002\n";
 export declare function chalkCommand(args: string[], flags: Flags, opts: {
     workspace?: string;
     json: boolean;

package/dist/app/cli/chalk/main.js

@@ -14,14 +14,10 @@ import { UsageError, loadWorkspace, redactDeep, redactHome } from "../../workspa
 import { buildBundle, readBundle } from "./build.js";
 import { LoadError, NotFoundError, loadScene, loadSceneFiles, resolveSceneInput } from "./load-scene.js";
 import { typecheckScene } from "./typecheck.js";
-export const CHALK_USAGE = `用法:
-  cotutor chalk check <scene.ts|目录> [--no-types] [--json]
-  cotutor chalk build <scene.ts|目录> [--out <dir>] [--json]
-  cotutor chalk bake <scene.ts|课包 id> [--bundles <dir>] [--json]
-  cotutor chalk snap <scene.ts|课包 id> [--step <n>] [--no-cursor] [--out <dir>] [--bundles <dir>] [--json]
-  cotutor chalk dub <scene.ts|课包 id> [--voice <音色>] [--tutor <老师>] [--instruction <语气>] [--dry-run] [--bundles <dir>] [--json]
-课包缺省在 workspace 的 bundles/(--bundles 换);场景源与 --out / --bundles 的相对路径按当前目录。
-`;
+import { commandHelp } from "../usage.js";
+/** cotutor chalk 的用法从命令表来(app/cli/commands.ts),帮助和参数检查同源 */
+const CHALK_HELP = () => commandHelp('chalk');
+const SEE_HELP = '用法:cotutor chalk --help';
 const str = (v) => (typeof v === 'string' ? v : undefined);
 function report(json, r) {
     const errors = r.findings.filter((f) => f.level === 'error').length;
@@ -64,13 +60,13 @@ export async function chalkCommand(args, flags, opts) {
     const [sub, file, ...extra] = args;
     const json = opts.json;
     if (!sub || flags.help === true) {
-        process.stdout.write(CHALK_USAGE);
+        process.stdout.write(CHALK_HELP());
         return;
     }
     if (!file)
-        throw new UsageError(`cotutor chalk ${sub} 要一个场景文件(或课包 id)。\n${CHALK_USAGE}`);
+        throw new UsageError(`cotutor chalk ${sub} 要一个场景文件(或课包 id)。${SEE_HELP}`);
     if (extra.length)
-        throw new UsageError(`多余的参数 '${extra[0]}'。\n${CHALK_USAGE}`);
+        throw new UsageError(`多余的参数 '${extra[0]}'。${SEE_HELP}`);
     const bundlesOf = () => (str(flags.bundles) ? resolve(str(flags.bundles)) : loadWorkspace(opts.workspace).dirs.bundles);
     try {
         switch (sub) {
@@ -182,7 +178,7 @@ export async function chalkCommand(args, flags, opts) {
                 return;
             }
             default:
-                throw new UsageError(`cotutor chalk 没有 '${sub}'。\n${CHALK_USAGE}`);
+                throw new UsageError(`cotutor chalk 没有 '${sub}'。${SEE_HELP}`);
         }
     }
     catch (err) {

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

@@ -0,0 +1,50 @@
+/**
+ * 命令表:cotutor 每条命令的说明、参数和例子,只在这里写一次。
+ * 由它生成:顶层帮助与 cotutor <命令> --help(usage.ts)、技能里的命令参考(app/skills/*-doc.ts);
+ * main.ts 照它拦不认识的旗标、用错子命令的旗标和多余的参数(agent 打错一个字,不能悄悄当没看见)。
+ * 纯数据,不引别的模块:技能生成和测试都要读它。
+ */
+export type Group = 'setup' | 'daily' | 'custom' | 'debug';
+export declare const GROUP_TITLE: Record<Group, string>;
+export interface FlagSpec {
+    name: string;
+    /** 带值的旗标写值的占位,如 '<n>';不写就是开关 */
+    value?: string;
+    desc: string;
+    /** 只给这几个子命令用;空串是不带子命令的那种(如 cotutor backup) */
+    subs?: readonly string[];
+    /** 认,但不写进帮助(旧名、内部用的) */
+    hidden?: boolean;
+}
+export interface CommandSpec {
+    name: string;
+    group: Group;
+    /** 顶层帮助里的一句 */
+    summary: string;
+    /** 用法,一种写法一行 */
+    usage: readonly string[];
+    /** 认、但不进帮助(旧名) */
+    hidden?: boolean;
+    /** 第一个参数是子命令时列出来;subRequired 时必须给 */
+    subs?: readonly string[];
+    subRequired?: boolean;
+    /** 认、但不写进帮助的子命令(后台服务的看护进程用) */
+    hiddenSubs?: readonly string[];
+    /** 参数(含子命令)最多几个;Infinity 是不限 */
+    maxArgs: number;
+    flags?: readonly FlagSpec[];
+    /** 认 --workspace */
+    workspace?: boolean;
+    /** 认 --sandbox(在试用副本里跑) */
+    sandbox?: boolean;
+    /** 认 --json;给数组就是只有这几个子命令认 */
+    json?: boolean | readonly string[];
+    notes?: readonly string[];
+    /** 会花钱、会写孩子的数据、要人来:agent 跑之前要知道 */
+    effects?: readonly string[];
+    examples: readonly string[];
+}
+export declare const COMMANDS: readonly CommandSpec[];
+export declare const commandSpec: (name: string | undefined) => CommandSpec | undefined;
+/** 所有命令里带值的旗标(parseArgs 要先知道哪些吃下一个词) */
+export declare const VALUED_FLAGS: readonly string[];