cotutor 0.4.4 → 0.4.5

package/dist/app/cli/commands.js

@@ -0,0 +1,353 @@
+/**
+ * 命令表:cotutor 每条命令的说明、参数和例子,只在这里写一次。
+ * 由它生成:顶层帮助与 cotutor <命令> --help(usage.ts)、技能里的命令参考(app/skills/*-doc.ts);
+ * main.ts 照它拦不认识的旗标、用错子命令的旗标和多余的参数(agent 打错一个字,不能悄悄当没看见)。
+ * 纯数据,不引别的模块:技能生成和测试都要读它。
+ */
+export const GROUP_TITLE = {
+    setup: '安装与设置',
+    daily: '日常使用',
+    custom: '定制教学',
+    debug: '开发与调试',
+};
+const DATE = { name: 'date', value: '<日期>', desc: '哪天(YYYY-MM-DD,缺省今天)' };
+const LANE = { name: 'lane', value: '<道>', desc: '只看这几道的事件,逗号分开,如 main,tts' };
+const ACTIVITY = { name: 'activity', value: '<名>', desc: '像孩子点了首页的 activity 按钮,新开话题' };
+const PARAM = { name: 'param', value: "'名=值;名=值'", desc: 'activity 的参数(按钮下面那几行)' };
+const FROM = { name: 'from', value: 'kid|system', desc: '谁说的(缺省 kid;system 不算孩子说的)' };
+const OPEN_QR = { name: 'open-qr', desc: '--open 的旧名', hidden: true };
+export const COMMANDS = [
+    // ---- 安装与设置 ----
+    {
+        name: 'guide', group: 'setup', summary: '给 AI 助手的安装说明(新电脑先跑这条)',
+        usage: ['cotutor guide'], maxArgs: 0,
+        notes: ['打印随包发的 INSTALL.md,和这个版本对得上', '还没装 cotutor 时:npx cotutor@latest guide', '第一行只用 ASCII:中文成了乱码,照它说的直接按 UTF-8 读文件'],
+        examples: ['npx cotutor@latest guide'],
+    },
+    {
+        name: 'init', group: 'setup', summary: '建孩子的 cotutor 文件夹和笔记文件夹',
+        usage: ['cotutor init <slug> [--name <称呼>] [--grade <1-6>] [--vault <目录>] [--dir <目录>] [--port <n>] [--json]'],
+        maxArgs: 1, json: true,
+        flags: [
+            { name: 'name', value: '<称呼>', desc: '老师怎么叫孩子,小名就行' },
+            { name: 'grade', value: '<1-6>', desc: '年级,决定装哪个教学包(cotutor grades 看有哪些)' },
+            { name: 'vault', value: '<目录>', desc: '用家长已有的笔记库(缺省在旁边建 <slug>-vault/);不能放在 cotutor 文件夹里' },
+            { name: 'dir', value: '<目录>', desc: 'cotutor 文件夹放哪(缺省 ~/cotutor/<slug>/)' },
+            { name: 'port', value: '<n>', desc: '端口(缺省 443,不行就 8443、8445…);选一次写进 cotutor.json,以后不变' },
+        ],
+        notes: ['<slug> 是孩子的短名:小写字母、数字、连字符,不用真名', '重复跑只补缺,已有的文件不动'],
+        examples: ['cotutor init ming --name 小明 --grade 2'],
+    },
+    {
+        name: 'grades', group: 'setup', summary: '列出能装的年级教学包',
+        usage: ['cotutor grades [--json]'], maxArgs: 0, json: true,
+        examples: ['cotutor grades --json'],
+    },
+    {
+        name: 'service', group: 'setup', summary: '后台服务:装、起停、状态、日志',
+        usage: [
+            'cotutor service install [--no-open] [--no-tray] [--json]',
+            'cotutor service uninstall | start | stop | restart',
+            'cotutor service status [--json]',
+            'cotutor service logs [--lines <n>] [--follow]',
+        ],
+        subs: ['install', 'uninstall', 'start', 'stop', 'restart', 'status', 'logs'], subRequired: true, hiddenSubs: ['run'],
+        maxArgs: 1, workspace: true, json: ['install', 'uninstall', 'status'],
+        flags: [
+            { name: 'no-open', desc: '装完不打开家长端(第一次装缺省会打开)', subs: ['install'] },
+            { name: 'open', desc: '装完打开家长端(重装缺省不开)', subs: ['install'] },
+            OPEN_QR,
+            { name: 'no-tray', desc: '不带菜单栏 / 任务栏图标', subs: ['install'] },
+            { name: 'lines', value: '<n>', desc: '看最后几行(缺省 50)', subs: ['logs'] },
+            { name: 'follow', desc: '一直跟着看新写的', subs: ['logs'] },
+            { name: 'log-dir', value: '<目录>', desc: '看护进程用', subs: ['run'], hidden: true },
+        ],
+        notes: [
+            '一个孩子一个服务,不要管理员:macOS launchd、Linux systemd 用户服务、Windows 登录项',
+            '登录后自己起来,崩了 10 秒后再起;日志按天留 14 天',
+            '换了 Node 版本或包挪了地方,再 install 一次',
+        ],
+        effects: ['install / uninstall 改这台电脑的登录项'],
+        examples: ['cotutor service install --no-open', 'cotutor service status --json', 'cotutor service logs --lines 100'],
+    },
+    {
+        name: 'cert', group: 'setup', summary: '签 HTTPS 证书(平板上说话要 HTTPS)',
+        usage: ['cotutor cert [<名或IP>]... [--json]'], maxArgs: Infinity, json: true,
+        flags: [{ name: 'host', value: '<名或IP>', desc: '多认一个名字或 IP(也可以直接写在后面)' }],
+        notes: ['要先装 mkcert;缺省认电脑名,换 Wi-Fi、IP 变了都不用重签', '所有孩子共用一张,在 ~/.config/cotutor/certs/', '签完 cotutor service restart 才走 HTTPS'],
+        effects: ['这台电脑信任根证书要人自己跑 mkcert -install(要输密码或点弹窗)'],
+        examples: ['cotutor cert', 'cotutor cert 192.168.1.20'],
+    },
+    {
+        name: 'pin', group: 'setup', summary: '家长端密码(PIN)',
+        usage: ['cotutor pin [--pin <4-8 位数字>]', 'cotutor pin off | status [--json]'],
+        subs: ['off', 'status'], maxArgs: 1, json: true,
+        flags: [{ name: 'pin', value: '<数字>', desc: '设成这个 PIN(不带它在终端里会问)', subs: [''] }],
+        notes: ['锁家长端 /parent 和工作台 /dev;没设就对局域网全开', '这台电脑上免密;所有孩子共用'],
+        effects: ['要人来:PIN 由家长自己设,不要说给 AI 助手'],
+        examples: ['cotutor pin status --json', 'cotutor pin off'],
+    },
+    // ---- 日常使用 ----
+    {
+        name: 'open', group: 'daily', summary: '打开家长端',
+        usage: ['cotutor open [--print] [--json]'], maxArgs: 0, workspace: true, sandbox: true, json: true,
+        flags: [{ name: 'print', desc: '只打印地址,不开浏览器' }],
+        notes: ['读 cotutor.json,不用记端口;没在跑就说怎么起,退出码 1'],
+        examples: ['cotutor open', 'cotutor open --print'],
+    },
+    {
+        name: 'doctor', group: 'daily', summary: '体检;--fix 修掉能自动修的',
+        usage: ['cotutor doctor [--json]', 'cotutor doctor --fix', 'cotutor doctor --live'],
+        maxArgs: 0, workspace: true, sandbox: true, json: true,
+        flags: [
+            { name: 'fix', desc: '修掉能自动修的(幂等,不碰孩子的数据,不用人输东西),要人来的留着' },
+            { name: 'live', desc: '真连一次百炼的嘴、真配一句音' },
+        ],
+        notes: ['--json 里没过的项带 cmd(能直接跑)或 human(要人来)', '有必需项没过,退出码 1'],
+        effects: ['--live 花一分钱'],
+        examples: ['cotutor doctor --fix', 'cotutor doctor --json'],
+    },
+    {
+        name: 'update', group: 'daily', summary: '升级程序,再更新每个孩子的出厂文件',
+        usage: ['cotutor update [--anyway]'], maxArgs: 0, workspace: true,
+        flags: [{ name: 'anyway', desc: '孩子在通话时也动(缺省等下课)' }],
+        notes: ['问 npm 有没有新版本 → 换程序 → 每个孩子换新出厂文件(cotutor refresh)、重起服务和图标', 'npm 没装成,服务不动', '「升级 cotutor」就是这条'],
+        examples: ['cotutor update'],
+    },
+    {
+        name: 'backup', group: 'daily', summary: '备份、看有哪些、恢复',
+        usage: ['cotutor backup', 'cotutor backup list [--json]', 'cotutor backup restore <名字> [--yes]'],
+        subs: ['list', 'restore'], maxArgs: 2, workspace: true, sandbox: true, json: true,
+        flags: [{ name: 'yes', desc: '真的恢复(不加只说会做什么)', subs: ['restore'] }],
+        notes: ['在孩子的 cotutor 文件夹旁边的 .backups/,不含录音', '服务开着时每天一份,升级前一份;恢复前先把现在的也备一份', 'restore 不加 --yes:只说会做什么,以 1 退(--json 时 needsYes: true)'],
+        effects: ['restore 覆盖孩子的文件:家长明确说要恢复才跑'],
+        examples: ['cotutor backup list', 'cotutor backup restore <名字> --yes'],
+    },
+    {
+        name: 'report', group: 'daily', summary: '诊断信息(不含孩子的对话和 key)',
+        usage: ['cotutor report'], maxArgs: 0, workspace: true, sandbox: true,
+        notes: ['版本、系统、服务、没过的体检、最近报错的原因;名字和 IP 已抹掉,先看再发', '给人看、贴进 issue 的,只出文字;要机器可读的用 cotutor doctor --json 和 cotutor service status --json'],
+        examples: ['cotutor report'],
+    },
+    {
+        name: 'tray', group: 'daily', summary: '菜单栏 / 任务栏图标',
+        usage: ['cotutor tray on | off | status [--json]'],
+        subs: ['on', 'off', 'status'], subRequired: true, maxArgs: 1, json: true,
+        notes: ['macOS、Windows;service install 时一起装', 'off 关掉并记住,以后装服务也不带'],
+        examples: ['cotutor tray status --json'],
+    },
+    // ---- 定制教学 ----
+    {
+        name: 'refresh', group: 'custom', summary: '换新这个孩子的出厂文件(不升级程序)',
+        usage: ['cotutor refresh [--json]', 'cotutor refresh --config [--dry-run] [--json]'],
+        maxArgs: 0, workspace: true, sandbox: true, json: true,
+        flags: [
+            { name: 'config', desc: '改的是 cotutor.json:只补缺的、删不再用的出厂段,改过的值不动' },
+            { name: 'dry-run', desc: '和 --config 一起:只看要改什么' },
+            { name: 'grade', value: '<1-6>', desc: '', hidden: true },
+        ],
+        notes: [
+            '出厂的老师、activity、技能、主题:没改过的换新,改过的保留并报 diff;换之前自动备份一份',
+            '升级程序用 cotutor update,它会对每个孩子跑这条;这条只在程序已经换过(手动 npm i -g、从仓库跑)时单独用',
+            '改过的想回出厂的:cotutor reset',
+        ],
+        examples: ['cotutor refresh', 'cotutor refresh --config --dry-run'],
+    },
+    {
+        name: 'reset', group: 'custom', summary: '把改过的出厂老师或 activity 换回出厂的',
+        usage: ['cotutor reset <老师>|<老师>/<activity>... [--json]'],
+        maxArgs: Infinity, workspace: true, sandbox: true, json: true,
+        notes: ['只动点名的这几份;你那份存成旁边的 .bak,换之前还自动备份一份', '自家加的老师、activity 没有出厂那份,换不了'],
+        effects: ['盖掉家长改过的老师文件:家长明确说要回出厂的才跑'],
+        examples: ['cotutor reset math-tutor', 'cotutor reset chinese-tutor/你说我画'],
+    },
+    {
+        // refresh 的旧名:0.4.x 的 cotutor update 换完程序,会用新程序跑 upgrade --workspace <孩子>,所以一直要认;不进帮助
+        name: 'upgrade', group: 'custom', hidden: true, summary: '旧名:升级程序用 cotutor update,换新出厂文件用 cotutor refresh,回出厂用 cotutor reset',
+        usage: ['cotutor upgrade [--force <老师>]... [--config [--dry-run]] [--json]'],
+        maxArgs: Infinity, workspace: true, sandbox: true, json: true,
+        flags: [
+            { name: 'force', value: '<老师>', desc: '同 cotutor reset' },
+            { name: 'config', desc: '同 cotutor refresh --config' },
+            { name: 'dry-run', desc: '和 --config 一起:只看要改什么' },
+            { name: 'grade', value: '<1-6>', desc: '', hidden: true },
+        ],
+        notes: ['还认,是为了旧版本的 cotutor update 和旧文档;新写的一律用 update / refresh / reset'],
+        examples: ['cotutor refresh'],
+    },
+    {
+        name: 'add', group: 'custom', summary: '加一位自家的老师',
+        usage: ['cotutor add <老师名> --display <显示名> [--subject <学科>] [--avatar <emoji|图片>] [--description <一句话>] [--hidden] [--json]'],
+        maxArgs: 1, workspace: true, sandbox: true, json: true,
+        flags: [
+            { name: 'display', value: '<显示名>', desc: '孩子看到的名字(必填)' },
+            { name: 'subject', value: '<学科>', desc: '学科' },
+            { name: 'avatar', value: '<emoji|图片>', desc: 'emoji,或 workspace 里图片的相对路径' },
+            { name: 'description', value: '<一句话>', desc: '写进老师文件的一句介绍' },
+            { name: 'hidden', desc: '孩子端不露(只和系统、家长打交道的工具人)' },
+        ],
+        notes: ['名字以 -tutor 结尾的是有脸的老师,其余是工具人', '出老师文件、写进 cotutor.json、建它的家;服务不用重启'],
+        examples: ['cotutor add science-tutor --display 科学老师 --subject 科学 --avatar 🔬'],
+    },
+    {
+        name: 'add-theme', group: 'custom', summary: '加一个自家的主题',
+        usage: ['cotutor add-theme <主题名> [--from <主题>] [--json]'], maxArgs: 1, workspace: true, sandbox: true, json: true,
+        flags: [{ name: 'from', value: '<主题>', desc: '从哪个主题拷(缺省 default)' }],
+        notes: ['拷到 themes/<主题名>/;cotutor.json 的 kid.theme 改成它就换过去'],
+        examples: ['cotutor add-theme dark'],
+    },
+    {
+        name: 'home', group: 'custom', summary: '检查和发布孩子端首页',
+        usage: ['cotutor home check [--published] [--json]', 'cotutor home publish [--force] [--from <文件>] [--json]', 'cotutor home show [--json]'],
+        subs: ['check', 'publish', 'show'], subRequired: true, maxArgs: 1, workspace: true, sandbox: true, json: true,
+        flags: [
+            { name: 'published', desc: '查已发布的那份(缺省查草稿 home/draft.md)', subs: ['check'] },
+            { name: 'force', desc: '有要改的卡,丢掉它们照发', subs: ['publish'] },
+            { name: 'from', value: '<文件>', desc: '发另一份(比如历史里的)', subs: ['publish'] },
+        ],
+        notes: ['check 不花钱:孩子会看到哪几张卡、每位老师的按钮、要改的(带行号)', 'publish 先检查,留历史 home/history/,写 home/published.json;孩子端刷新就是新的', 'show:现在发布的是哪份、每个按钮被点了几次'],
+        examples: ['cotutor home check', 'cotutor home publish'],
+    },
+    {
+        name: 'activity', group: 'custom', summary: '检查和评测 activity',
+        usage: ['cotutor activity check [<老师> [<名>]] [--json]', 'cotutor activity eval <老师> <名> [--runs <n>] [--only <例子>] [--kid-model <模型>] [--json]'],
+        subs: ['check', 'eval'], subRequired: true, maxArgs: 3, workspace: true, sandbox: true, json: true,
+        flags: [
+            { name: 'runs', value: '<n>', desc: '每个例子跑几次(1–10,缺省 3),次次都过才算过', subs: ['eval'] },
+            { name: 'only', value: '<例子>', desc: '只跑这个例子', subs: ['eval'] },
+            { name: 'kid-model', value: '<模型>', desc: '模拟孩子用的千问模型(缺省 qwen3.8-flash)', subs: ['eval'] },
+        ],
+        notes: ['activity 文件在 agents/<老师>/activities/<名>.md', 'check 不花钱;eval 照 <名>.例子.md 跑真老师 + 模拟孩子,落 evals/'],
+        effects: ['eval 花钱'],
+        examples: ['cotutor activity check', 'cotutor activity eval chinese-tutor 你说我画 --runs 1'],
+    },
+    {
+        name: 'chalk', group: 'custom', summary: '做小课堂的课包',
+        usage: [
+            'cotutor chalk check <scene.ts|目录> [--no-types] [--json]',
+            'cotutor chalk build <scene.ts|目录> [--out <目录>] [--json]',
+            'cotutor chalk bake <scene.ts|课包 id> [--bundles <目录>] [--json]',
+            'cotutor chalk snap <scene.ts|课包 id> [--step <n>] [--no-cursor] [--out <目录>] [--bundles <目录>] [--json]',
+            'cotutor chalk dub <scene.ts|课包 id> [--voice <音色>] [--tutor <老师>] [--instruction <语气>] [--dry-run] [--bundles <目录>] [--json]',
+        ],
+        subs: ['check', 'build', 'bake', 'snap', 'dub'], maxArgs: 2, workspace: true, sandbox: true, json: true,
+        flags: [
+            { name: 'no-types', desc: '不跑类型检查', subs: ['check'] },
+            { name: 'out', value: '<目录>', desc: 'build:课包放哪(缺省 bundles/<id>/);snap:截图放哪', subs: ['build', 'snap'] },
+            { name: 'bundles', value: '<目录>', desc: '课包目录(缺省 workspace 的 bundles/)', subs: ['bake', 'snap', 'dub'] },
+            { name: 'step', value: '<n>', desc: '只截这一步(0 = 空板)', subs: ['snap'] },
+            { name: 'no-cursor', desc: '截图里不画笔尖', subs: ['snap'] },
+            { name: 'voice', value: '<音色>', desc: '配音的音色(缺省用 --tutor 那位老师卡的音色)', subs: ['dub'] },
+            { name: 'tutor', value: '<老师>', desc: '用这位老师卡的音色(缺省 math-tutor)', subs: ['dub'] },
+            { name: 'instruction', value: '<语气>', desc: '配音的语气', subs: ['dub'] },
+            { name: 'dry-run', desc: '只算账(几步、多少计费字符),不合成', subs: ['dub'] },
+        ],
+        notes: ['check 校验场景;build 出课包;bake 烤画面;snap 每步截图;dub 配音', '给 .ts 的 bake / snap / dub 先 check + build;给课包 id 的直接用 bundles 里那份', '相对路径按当前目录'],
+        effects: ['bake / snap 要本机的 Chrome', 'dub 花钱'],
+        examples: ['cotutor chalk check scene.ts', 'cotutor chalk snap scene.ts'],
+    },
+    // ---- 开发与调试(顶层帮助缺省不列,cotutor --help --all 看) ----
+    {
+        name: 'serve', group: 'debug', summary: '在终端里起服务(关了终端就停)',
+        usage: ['cotutor serve [--port <n>] [--http] [--open] [--trace [--lane <道>]] [--log-dir <目录>]'],
+        maxArgs: 0, workspace: true, sandbox: true,
+        flags: [
+            { name: 'port', value: '<n>', desc: '这次换个端口' },
+            { name: 'http', desc: '不走 HTTPS' },
+            { name: 'open', desc: '顺手打开家长端' },
+            OPEN_QR,
+            { name: 'trace', desc: '每一轮的事件按道打印' },
+            LANE,
+            { name: 'log-dir', value: '<目录>', desc: '输出按天落文件(后台服务用)' },
+        ],
+        notes: ['一直开着用 cotutor service'],
+        examples: ['cotutor serve --sandbox'],
+    },
+    {
+        name: 'mock', group: 'debug', summary: '不花钱看前端:假老师、假嘴',
+        usage: ['cotutor mock [--port <n>] [--scenario normal|nokey] [--delay <ms>] [--http] [--open]'], maxArgs: 0,
+        flags: [
+            { name: 'port', value: '<n>', desc: '端口' },
+            { name: 'scenario', value: 'normal|nokey', desc: 'nokey = 没配百炼,孩子端只出「老师们还没到」' },
+            { name: 'delay', value: '<ms>', desc: '假老师的延迟(毫秒)' },
+            { name: 'http', desc: '不走 HTTPS' },
+            { name: 'open', desc: '顺手打开扫码页' },
+            OPEN_QR,
+        ],
+        notes: ['不需要 workspace'],
+        examples: ['cotutor mock --scenario nokey'],
+    },
+    {
+        name: 'send', group: 'debug', summary: '终端里给老师发一条',
+        usage: [
+            'cotutor send <老师> [<消息>] [--new] [--photo <图,图>] [--quiet] [--json]',
+            "cotutor send <老师> --activity <名> [--param '名=值;名=值']",
+        ],
+        maxArgs: Infinity, workspace: true, sandbox: true, json: true,
+        flags: [
+            { name: 'new', desc: '开新话题' },
+            { name: 'photo', value: '<图,图>', desc: '带作业照片(jpg / png,最多 9 张);有照片时消息可以空' },
+            ACTIVITY, PARAM, FROM,
+            { name: 'runtime', value: '<名>', desc: '换个运行时' },
+            LANE,
+            { name: 'quiet', desc: '只要结果,不打印过程' },
+        ],
+        notes: ['孩子的话照实时写(同孩子端),只是没有嘴;事件落 events.jsonl,事后 cotutor trace 看'],
+        effects: ['花钱', '写进孩子的对话记录(试一下用 --sandbox)'],
+        examples: ['cotutor send math-tutor "这一步为什么要借位"'],
+    },
+    {
+        name: 'pack', group: 'debug', summary: '干跑上下文包:不起模型,看老师会拿到什么',
+        usage: ["cotutor pack <老师> [<消息>] [--activity <名> [--param '名=值;名=值']] [--from kid|system] [--at <ISO时间>] [--json]"],
+        maxArgs: Infinity, workspace: true, sandbox: true, json: true,
+        flags: [ACTIVITY, PARAM, FROM, { name: 'at', value: '<ISO时间>', desc: '当作这个时间' }],
+        notes: ['每段来自哪个文件、一共几条、按政策带了几条;改了档案、日记、计划立刻看效果'],
+        examples: ['cotutor pack math-tutor "讲讲退位"'],
+    },
+    {
+        name: 'show', group: 'debug', summary: '看一轮:问了什么、上下文包、讲稿与卡、读了什么',
+        usage: ['cotutor show <老师> <job> [<日期>] [--evals] [--json]'], maxArgs: 3, workspace: true, sandbox: true, json: true,
+        flags: [{ name: 'evals', desc: '看回放的那轮(evals/ 里的)' }],
+        notes: ['日期缺省今天;--json 和家长端「看原文」是同一份'],
+        examples: ['cotutor show math-tutor 1620-1 2026-09-12 --json'],
+    },
+    {
+        name: 'trace', group: 'debug', summary: '回放一轮的事件',
+        usage: ['cotutor trace <老师> <job> [<日期>] [--lane <道>] [--json]'], maxArgs: 3, workspace: true, sandbox: true, json: true,
+        flags: [LANE],
+        notes: ['读 <日期>.<job>.events.jsonl;日期缺省今天'],
+        examples: ['cotutor trace math-tutor 1620-1 --lane main'],
+    },
+    {
+        name: 'replay', group: 'debug', summary: '同一问按现在的提示词再跑一遍,并排对照',
+        usage: ['cotutor replay <老师> <job> [<日期>] [--runtime <名>] [--json]'], maxArgs: 3, workspace: true, sandbox: true, json: true,
+        flags: [{ name: 'runtime', value: '<名>', desc: '换个运行时' }],
+        notes: ['落 evals/,不进孩子的对话、不配音'],
+        effects: ['花钱'],
+        examples: ['cotutor replay math-tutor 1620-1 2026-09-12'],
+    },
+    {
+        name: 'compare', group: 'debug', summary: '再看一次回放的对照',
+        usage: ['cotutor compare <老师> [<evalJob>] [<日期>] [--json]'], maxArgs: 3, workspace: true, sandbox: true, json: true,
+        notes: ['不给 evalJob 就列这天回放过哪些'],
+        examples: ['cotutor compare math-tutor'],
+    },
+    {
+        name: 'rate', group: 'debug', summary: '给一个话题打星(1–5)',
+        usage: ['cotutor rate <老师> <话题> <1-5> [--date <日期>] [--json]'], maxArgs: 3, workspace: true, sandbox: true, json: true,
+        flags: [DATE],
+        notes: ['和家长端同一条路;到 vault.keepScore 星的话题,记账时摘要才进日记'],
+        examples: ['cotutor rate math-tutor 1620-1 4'],
+    },
+    {
+        name: 'bookkeep', group: 'debug', summary: '记账:把这天的话题写进日记',
+        usage: ['cotutor bookkeep <老师> [--date <日期>] [--thread <话题>] [--quiet] [--json]'], maxArgs: 1, workspace: true, sandbox: true, json: true,
+        flags: [DATE, { name: 'thread', value: '<话题>', desc: '只记这个话题' }, { name: 'quiet', desc: '不打印过程' }],
+        notes: ['每个还没记过的话题起一轮记账,应用写进笔记文件夹的日记'],
+        effects: ['花钱', '写孩子的笔记文件夹'],
+        examples: ['cotutor bookkeep math-tutor'],
+    },
+];
+export const commandSpec = (name) => COMMANDS.find((c) => c.name === name);
+/** 所有命令里带值的旗标(parseArgs 要先知道哪些吃下一个词) */
+export const VALUED_FLAGS = [...new Set(['workspace', ...COMMANDS.flatMap((c) => (c.flags ?? []).filter((f) => f.value).map((f) => f.name))])];

package/dist/app/cli/doctor.js

@@ -31,7 +31,7 @@ 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";
+import { CONFIG_FILE, ConfigError, USER_CONFIG, UsageError, assembleWorkspace, defaultVaultOf, expandPath, homePath, isInside, parseConfig, readJson, redactHome, resolveRoot, vaultSeparate, } from "../workspace.js";
 /** 每条不过的要么能跑(cmd)要么要人来(human),没有第三种:新加的检查项忘了写 cmd,也只是交给人,不会让 agent 瞎猜 */
 function finish(report) {
     for (const c of report.checks) {
@@ -108,7 +108,7 @@ export async function doctorWorkspace(override, opts = {}) {
     // 路径写 $HOME/…,和别的字段一样:用户名不传给 agent 的厂商;redactDeep 只换开头,管不到命令中间的路径;sh 与 PowerShell 都展开
     const quoted = `"${redactHome(root)}"`;
     const flag = source === 'flag' ? ` --workspace ${quoted}` : '';
-    const upgrade = `cotutor upgrade${flag}`;
+    const refresh = `cotutor refresh${flag}`;
     // ---- cotutor.json ----
     let ws = null;
     const configFile = join(root, CONFIG_FILE);
@@ -147,7 +147,7 @@ export async function doctorWorkspace(override, opts = {}) {
         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', cmd: upgrade });
+            push({ name: 'teachingPack.origin', ok: false, required: false, detail: '旧版出厂内容按二年级来源读取,尚未补记;孩子档案不变', fix: 'cotutor refresh 补记来源,保留自定义文件与原 hash', cmd: refresh });
     }
     catch (err) {
         push({ name: 'teachingPack', ok: false, required: true, detail: err.message, fix: '检查 .cotutor/shipped.json 的 teachingPack 与本包 grades/;恢复原来源记录或安装包含该年级的版本,不要改成其他年级绕过' });
@@ -160,8 +160,8 @@ export async function doctorWorkspace(override, opts = {}) {
             ok: gaps.length === 0,
             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,
+            fix: gaps.length ? 'cotutor refresh --config --dry-run 先看,再 cotutor refresh --config 改(只加缺的、删不再用的出厂段,你改过的值不动)' : undefined,
+            cmd: gaps.length ? `cotutor refresh --config${flag}` : undefined,
         });
     }
     // ---- 骨架 ----
@@ -180,7 +180,7 @@ export async function doctorWorkspace(override, opts = {}) {
     // 老布局(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(原样挪过去,不改内容;新位置已有同名的不挪、会点名)', cmd: upgrade });
+        push({ name: 'layout', ok: false, required: true, detail: `${legacy.join(' ')} 是老位置:老师文件现在在 agents/<老师>.md,技能在 ${SKILLS_DIR}/`, fix: 'cotutor refresh(原样挪过去,不改内容;新位置已有同名的不挪、会点名)', cmd: refresh });
     // 家规(根的 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(不需要:老师要知道的都在老师文件与技能里)' });
@@ -215,7 +215,7 @@ export async function doctorWorkspace(override, opts = {}) {
             });
             const st = statuses.get(name);
             if (!st)
-                push({ name: `tutor.${name}.origin`, ok: true, required: false, detail: teachingPack ? '自家加的老师(不是出厂件,upgrade 不碰)' : '出厂来源无法确认,先修复 teachingPack 检查项' });
+                push({ name: `tutor.${name}.origin`, ok: true, required: false, detail: teachingPack ? '自家加的老师(不是出厂件,refresh 不碰)' : '出厂来源无法确认,先修复 teachingPack 检查项' });
             if (st) {
                 const label = { latest: '出厂件,最新', upgradable: `出厂件,基于 ${st.basedOn},包已更新`, custom: `自定义(基于 ${st.basedOn})`, untracked: '自定义(没有出厂记录)', missing: '缺', broken: '读不到' };
                 push({
@@ -223,8 +223,8 @@ export async function doctorWorkspace(override, opts = {}) {
                     ok: st.state !== 'upgradable',
                     required: false,
                     detail: label[st.state],
-                    fix: st.state === 'upgradable' ? 'cotutor upgrade 换新版' : undefined,
-                    cmd: st.state === 'upgradable' ? upgrade : undefined,
+                    fix: st.state === 'upgradable' ? 'cotutor refresh 换新版' : undefined,
+                    cmd: st.state === 'upgradable' ? refresh : undefined,
                 });
             }
             const home = join(ws.dirs.agents, name);
@@ -293,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, cmd: sk.state === 'missing' ? initCmd() : sk.state === 'upgradable' ? 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 refresh 换新版' : undefined, cmd: sk.state === 'missing' ? initCmd() : sk.state === 'upgradable' ? refresh : 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/ 再删掉)', cmd: linked ? undefined : upgrade });
+            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 refresh 建链(是实体目录的话先把里面的挪进 .agents/skills/ 再删掉)', cmd: linked ? undefined : refresh });
             // ---- activity:老师的家里 agents/<老师>/activities/<名>.md;出厂的看新旧,每份都过一遍 activity check ----
             {
                 const { activityStatuses, checkActivities } = await import("./activities.js");
@@ -316,7 +316,7 @@ export async function doctorWorkspace(override, opts = {}) {
                 }
                 for (const r of await checkActivities(root, ws.config.tutors)) {
                     const key = `${r.tutor}/${r.name}`;
-                    // 老 workspace 改过老师文件:upgrade 只报 diff,里面同名那节还在,两处说法会打架
+                    // 老 workspace 改过老师文件:refresh 只报 diff,里面同名那节还在,两处说法会打架
                     const agentText = await readFile(tutorFilePath(ws.dirs.agents, r.tutor), 'utf8').catch(() => '');
                     if (new RegExp(`^#{2,4}\\s*${r.name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`, 'm').test(agentText))
                         push({ name: `activity.${key}.dup`, ok: false, required: false, detail: `agents/${r.tutor}.md 里还有一节「${r.name}」,和 activity 文件两处说法会打架`, fix: `删掉老师文件里那一节(做法以 agents/${r.tutor}/activities/${r.name}.md 为准)` });
@@ -328,8 +328,8 @@ export async function doctorWorkspace(override, opts = {}) {
                         ok: !fixes.length && st?.state !== 'upgradable',
                         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,
+                        fix: fixes.length ? `cotutor activity check ${r.tutor} ${r.name} 看全` : st?.state === 'upgradable' ? 'cotutor refresh 换新版' : undefined,
+                        cmd: !fixes.length && st?.state === 'upgradable' ? refresh : undefined,
                     });
                 }
             }
@@ -343,15 +343,15 @@ 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`, cmd: name === 'default' ? initCmd() : undefined });
+                    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 refresh' : `修 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) {
-                        push({ name: `theme.${th.name}.origin`, ok: true, required: false, detail: `themes/${th.name}/:自家的主题(不是出厂件,upgrade 不碰)` });
+                        push({ name: `theme.${th.name}.origin`, ok: true, required: false, detail: `themes/${th.name}/:自家的主题(不是出厂件,refresh 不碰)` });
                         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, cmd: th.state === 'missing' ? initCmd() : th.state === 'upgradable' ? 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 refresh 换新版' : undefined, cmd: th.state === 'missing' ? initCmd() : th.state === 'upgradable' ? refresh : undefined });
                 }
             }
         }
@@ -402,6 +402,21 @@ export async function doctorWorkspace(override, opts = {}) {
             const n = there ? (await readdir(cap).catch(() => [])).filter((d) => /^\d{4}-\d{2}-\d{2}$/.test(d)).length : 0;
             push({ name: 'captures', ok: inside && writable, required: false, detail: !inside ? `${redactHome(cap)} 在 workspace 根以外,页面看不到照片(/api/kid/image 只给根以内的)` : !writable ? `${redactHome(cap)} 写不了(最近的已有目录 ${redactHome(dir)} 没有写权限)` : there ? `${redactHome(cap)}:${n} 天的作业照片` : `${redactHome(cap)} 还没有(第一张照片时建)`, fix: !inside ? '把 cotutor.json 的 paths.captures 改回根以内(缺省 captures)' : !writable ? '改目录权限,或换 paths.captures' : undefined });
         }
+        // ---- vault 与 workspace 分开(2026-11-09):旧版 init 不写 paths.vault,vault 就是 workspace 根;照旧能用,这里说怎么分。sandbox 的 vault 本来就拷在里面,不查 ----
+        if (!ws.sandbox) {
+            const vault = ws.paths.vault;
+            const separate = vaultSeparate(ws.root, vault);
+            const rootInVault = !separate && !isInside(vault, ws.root);
+            push({
+                name: 'vault.separate',
+                ok: separate,
+                required: false,
+                detail: separate ? `笔记文件夹(vault)在 ${redactHome(vault)},和 cotutor 文件夹分开` : rootInVault ? `孩子的 cotutor 文件夹在笔记文件夹(${redactHome(vault)})里面` : vault === ws.root ? '笔记文件夹(vault)就是孩子的 cotutor 文件夹(旧版 init 的布局):照旧能用,但用 Obsidian 打开满是程序的文件,恢复备份会连家长的笔记一起换掉' : `笔记文件夹(vault)在孩子的 cotutor 文件夹里(${redactHome(vault)})`,
+                fix: separate ? undefined : rootInVault
+                    ? '把孩子的 cotutor 文件夹挪到笔记文件夹外面(挪了要再 cotutor service install),或者笔记文件夹换一个地方'
+                    : `想分开:cotutor service stop,建笔记文件夹 ${homePath(defaultVaultOf(ws.root))},把档案、日记/、记忆/、计划/、教材/、参考/ 和你自己的笔记挪过去,cotutor.json 的 paths.vault 写成它,再 cotutor service start`,
+            });
+        }
         // ---- vault(《obsidian仓库设计.md》2026-09-17):档案与每位老师的入口文件按 frontmatter 找,原文整篇进上下文包 ----
         {
             const { notes, files } = await scanVault(ws);

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

@@ -0,0 +1,6 @@
+export declare const PACKAGE_INSTALL_MD: string;
+/**
+ * 第一行只用 ASCII:Windows PowerShell 5.1 把管道里的 UTF-8 按系统代码页(中文系统是 936)解,
+ * 下面的中文会成乱码,这一行还读得懂,告诉助手直接按 UTF-8 读文件。
+ */
+export declare function guideText(version: string): string;

package/dist/app/cli/guide.js

@@ -0,0 +1,17 @@
+/**
+ * cotutor guide:把随包发的 INSTALL.md 原样打印给替家长安装的 AI 助手。
+ * 家长只要打一句「先跑 npx cotutor@latest guide」,不用输网址;走 npm(国内能换镜像),说明和装上的版本对得上。
+ * src/app/cli/ 与 dist/app/cli/ 都在包根下三层,和 main.ts 读 package.json 一样往上找。
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { redactHome } from "../workspace.js";
+export const PACKAGE_INSTALL_MD = fileURLToPath(new URL('../../../INSTALL.md', import.meta.url));
+/**
+ * 第一行只用 ASCII:Windows PowerShell 5.1 把管道里的 UTF-8 按系统代码页(中文系统是 936)解,
+ * 下面的中文会成乱码,这一行还读得懂,告诉助手直接按 UTF-8 读文件。
+ */
+export function guideText(version) {
+    const head = `# cotutor ${version} INSTALL.md (for the AI assistant installing cotutor; if the text below is garbled, read this file as UTF-8: ${redactHome(PACKAGE_INSTALL_MD)} , $HOME is the home directory)`;
+    return `${head}\n\n${readFileSync(PACKAGE_INSTALL_MD, 'utf8')}`;
+}

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

@@ -11,6 +11,8 @@ export interface InitResult {
 export interface InitOptions {
     slug: string;
     dir?: string;
+    /** vault 放哪(家长已有的 Obsidian 库);缺省 workspace 旁边的 <目录名>-vault。只在新建 cotutor.json 时用 */
+    vault?: string;
     name?: string;
     port?: number;
     /** 出厂教学包年级,不是孩子档案的覆盖值。 */