cotutor 0.4.4 → 0.4.5

package/dist/app/skills/tune-doc.js

@@ -4,11 +4,11 @@
  * tests/skills.test.ts 断言入库的和生成的一致——改老师团时能改哪些字段、缺省是什么,永远和契约同源。SKILL.md 本体(三条路子、禁区)是手写的。
  */
 import { z } from 'zod';
-import { USAGE } from "../cli/usage.js";
+import { commandsReference } from "../cli/usage.js";
 import { POLICY_DEFAULTS, PolicySchema, TutorSchema } from "../../schema/config.js";
 import { AGENT_FRONTMATTER_KEYS } from "../../runtime/agent-file.js";
 export const TUNE_SKILL = 'cotutor-tune';
-const TUNE_COMMANDS = ['add', 'add-theme', 'upgrade', 'doctor', 'pack', 'replay', 'compare', 'show'];
+const TUNE_COMMANDS = ['add', 'add-theme', 'refresh', 'reset', 'doctor', 'pack', 'replay', 'compare', 'show'];
 function unwrap(s) {
     let cur = s;
     for (let i = 0; i < 5; i++) {
@@ -39,10 +39,6 @@ function rows(shape, defaults, prefix = '') {
     return out;
 }
 export function tuneReferenceDoc() {
-    const cmds = USAGE.split('\n').filter((l) => {
-        const m = /^\s+cotutor (\S+)/.exec(l);
-        return m !== null && TUNE_COMMANDS.includes(m[1]);
-    });
     // tutors 字段的缺省从 zod 的 .default() 取(enabled / hidden);display 是必需的,给个占位再抹掉
     const tutorDefaults = TutorSchema.parse({ display: 'x' });
     delete tutorDefaults.display;
@@ -68,10 +64,10 @@ ${tutorRows.join('\n')}
 |---|---|---|---|
 ${policyRows.join('\n')}
 
-## 相关命令(完整用法 cotutor --help)
+## 相关命令(每条就是 cotutor <命令> --help 的内容)
 
 \`\`\`
-${cmds.join('\n')}
+${commandsReference(TUNE_COMMANDS)}
 \`\`\`
 `;
 }

package/dist/app/workspace.d.ts

@@ -1,8 +1,8 @@
 import { ConfigError, UsageError } from '../shared/errors.ts';
-import { redactDeep, redactHome } from '../shared/home.ts';
+import { expandPath, redactDeep, redactHome } from '../shared/home.ts';
 import { type RootSource, type SandboxMark, type Workspace } from '../schema/workspace.ts';
 import { type CotutorConfig } from '../schema/index.ts';
-export { ConfigError, UsageError, redactDeep, redactHome };
+export { ConfigError, UsageError, expandPath, redactDeep, redactHome };
 export type { RootSource, Workspace };
 export declare const CONFIG_FILE = "cotutor.json";
 export declare const USER_CONFIG: string;
@@ -13,13 +13,26 @@ export interface ResolvedRoot {
     root: string;
     source: RootSource;
 }
-export declare function expandPath(p: string, base: string): string;
+/** p 是 dir 本身或在它里面 */
+export declare function isInside(p: string, dir: string): boolean;
+/**
+ * vault 与 workspace 分开:谁也不在谁里面(2026-11-09)。vault 是家长的长期记忆,workspace 是机器的运行记录;
+ * 混在一起时 Obsidian 里满是 agents/、conversations/,扫 vault 要走遍对话与照片,备份恢复把家长的笔记跟着 workspace 一起盖掉。
+ * 旧版 init 不写 paths.vault(缺省 `.`,vault 就是 workspace 根),那样的照旧读得进来,doctor 的 vault.separate 提一句。
+ */
+export declare const vaultSeparate: (root: string, vault: string) => boolean;
+/** init 缺省的 vault:workspace 旁边的 <目录名>-vault(~/cotutor/ming → ~/cotutor/ming-vault;不在「文稿」与 iCloud 里,后台服务读得到) */
+export declare const defaultVaultOf: (root: string) => string;
+/** 写进 cotutor.json 的路径:家目录下的写成 ~/…(输出里不带用户名,换了用户名也对得上),别处写绝对路径 */
+export declare function homePath(abs: string): string;
 /** 读 JSON:不存在 → null;坏 → ConfigError */
 export declare function readJson(file: string): unknown | null;
 /** 从 dir 向上找 cotutor.json,找到返回目录 */
 export declare function findUp(dir: string): string | null;
 /** ~/cotutor/ 下带 cotutor.json 的子目录 */
 export declare function homeWorkspaces(homeRoot?: string): string[];
+/** 这台电脑上认得的孩子:~/cotutor/ 下的,加用户配置指的那个(在别处 --dir 建的) */
+export declare function knownWorkspaces(): string[];
 export interface ResolveOptions {
     env?: NodeJS.ProcessEnv;
     cwd?: string;

package/dist/app/workspace.js

@@ -9,24 +9,35 @@
 import { readFileSync, readdirSync, statSync } from 'node:fs';
 import { readFile, writeFile, rename } from 'node:fs/promises';
 import { ConfigError, UsageError } from "../shared/errors.js";
-import { redactDeep, redactHome } from "../shared/home.js";
+import { expandPath, redactDeep, redactHome } from "../shared/home.js";
 import { SANDBOX_MARK, SKILLS_DIR, SandboxMarkSchema } from "../schema/workspace.js";
 import { homedir } from 'node:os';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { CotutorConfigSchema, PATH_ROLES, ROLE_DEFAULTS, WORKSPACE_ROLES, explainIssues, } from "../schema/index.js";
 // 挪走了的几样照旧从这里转出(旧的引法不用改)
-export { ConfigError, UsageError, redactDeep, redactHome };
+export { ConfigError, UsageError, expandPath, redactDeep, redactHome };
 export const CONFIG_FILE = 'cotutor.json';
 export const USER_CONFIG = join(homedir(), '.config', 'cotutor', 'config.json');
 /** 机器级自签证书目录(cotutor cert 写 cert.pem + key.pem):证书签的是本机名与局域网 IP,与孩子无关,所以不在 workspace 里 */
 export const USER_CERT_DIR = join(homedir(), '.config', 'cotutor', 'certs');
 export const HOME_ROOT = join(homedir(), 'cotutor');
-export function expandPath(p, base) {
-    if (p === '~')
-        return homedir();
-    if (p.startsWith('~/'))
-        return join(homedir(), p.slice(2));
-    return isAbsolute(p) ? p : resolve(base, p);
+/** p 是 dir 本身或在它里面 */
+export function isInside(p, dir) {
+    const r = relative(dir, p);
+    return r === '' || (r !== '..' && !r.startsWith(`..${sep}`) && !isAbsolute(r));
+}
+/**
+ * vault 与 workspace 分开:谁也不在谁里面(2026-11-09)。vault 是家长的长期记忆,workspace 是机器的运行记录;
+ * 混在一起时 Obsidian 里满是 agents/、conversations/,扫 vault 要走遍对话与照片,备份恢复把家长的笔记跟着 workspace 一起盖掉。
+ * 旧版 init 不写 paths.vault(缺省 `.`,vault 就是 workspace 根),那样的照旧读得进来,doctor 的 vault.separate 提一句。
+ */
+export const vaultSeparate = (root, vault) => !isInside(vault, root) && !isInside(root, vault);
+/** init 缺省的 vault:workspace 旁边的 <目录名>-vault(~/cotutor/ming → ~/cotutor/ming-vault;不在「文稿」与 iCloud 里,后台服务读得到) */
+export const defaultVaultOf = (root) => join(dirname(root), `${basename(root)}-vault`);
+/** 写进 cotutor.json 的路径:家目录下的写成 ~/…(输出里不带用户名,换了用户名也对得上),别处写绝对路径 */
+export function homePath(abs) {
+    const rel = relative(homedir(), abs);
+    return rel && !rel.startsWith('..') && !isAbsolute(rel) ? `~/${rel.split(sep).join('/')}` : abs;
 }
 const isDir = (p) => {
     try {
@@ -84,6 +95,17 @@ export function homeWorkspaces(homeRoot = HOME_ROOT) {
         return [];
     }
 }
+/** 这台电脑上认得的孩子:~/cotutor/ 下的,加用户配置指的那个(在别处 --dir 建的) */
+export function knownWorkspaces() {
+    const roots = new Set(homeWorkspaces());
+    try {
+        const user = readJson(USER_CONFIG);
+        if (typeof user?.workspace === 'string' && user.workspace)
+            roots.add(expandPath(user.workspace, homedir()));
+    }
+    catch { /* 用户配置坏了 doctor 去报 */ }
+    return [...roots];
+}
 export function resolveRoot(override, opts = {}) {
     const env = opts.env ?? process.env;
     const cwd = resolve(opts.cwd ?? process.cwd());

package/dist/runtime/home/home.js

@@ -127,7 +127,7 @@ export function homeIssues(doc, ctx) {
             if (act && ctx.activities) {
                 const got = ctx.activities.get(`${name}/${act.name}`);
                 if (!got)
-                    out.push({ level: 'fix', line, card: n, button: k, text: b.kind === 'lecture' && !b.activity ? `${t.display}的「${b.label}」:看完怎么聊写在 agents/${name}/activities/${LECTURE_ACTIVITY}.md,这份不在(cotutor upgrade 补出厂的;或按钮下面写一行 activity: <名> 换一个)` : `${t.display}的「${b.label}」:agents/${name}/activities/${act.name}.md 不在(cotutor activity check ${name} 看这位老师有哪些)` });
+                    out.push({ level: 'fix', line, card: n, button: k, text: b.kind === 'lecture' && !b.activity ? `${t.display}的「${b.label}」:看完怎么聊写在 agents/${name}/activities/${LECTURE_ACTIVITY}.md,这份不在(cotutor refresh 补出厂的;或按钮下面写一行 activity: <名> 换一个)` : `${t.display}的「${b.label}」:agents/${name}/activities/${act.name}.md 不在(cotutor activity check ${name} 看这位老师有哪些)` });
                 else {
                     if (got.fixes)
                         out.push({ level: 'fix', line, card: n, button: k, text: `${t.display}的「${b.label}」:activity 文件 ${act.name}.md 有 ${got.fixes} 处要改(cotutor activity check ${name} ${act.name})` });

package/dist/runtime/runner.js

@@ -92,7 +92,7 @@ export async function gatherContext(ws, tutor, input, report) {
             pack.rules = TUTOR_RULES_PATH;
         }
         catch {
-            pack.rules = `缺:${TUTOR_RULES_PATH} 不在(cotutor upgrade 补),照你老师文件里的做`;
+            pack.rules = `缺:${TUTOR_RULES_PATH} 不在(cotutor refresh 补),照你老师文件里的做`;
         }
     }
     pack.notes.push(...mem.notes);
@@ -186,7 +186,7 @@ async function systemParts(ws, tutor, policy, pack, act = null) {
         return { systemBody: agentBody, activityInSystem: false };
     const guide = await boardGuideOf(ws, tutor);
     if (!guide) {
-        pack.boardGuide = `缺:${BOARD_GUIDE_PATH} 不在(cotutor upgrade 补),照你会的写`;
+        pack.boardGuide = `缺:${BOARD_GUIDE_PATH} 不在(cotutor refresh 补),照你会的写`;
         return { systemBody: agentBody, activityInSystem: false };
     }
     pack.boardGuide = BOARD_GUIDE_IN_SYSTEM;

package/dist/shared/home.d.ts

@@ -1,2 +1,4 @@
+/** cotutor.json 里的路径:~ 与 ~/ 是家目录,绝对的照用,相对的相对 base(从 app/workspace.ts 挪来,2026-11-09:托盘不带 zod 也要用) */
+export declare function expandPath(p: string, base: string): string;
 export declare function redactHome(value: string): string;
 export declare function redactDeep<T>(value: T): T;

package/dist/shared/home.js

@@ -1,5 +1,14 @@
 /** 给人看的路径里把家目录换成 $HOME(报错、doctor、--json 输出不带出用户名;从 app/workspace.ts 挪来,2026-10-29) */
 import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+/** cotutor.json 里的路径:~ 与 ~/ 是家目录,绝对的照用,相对的相对 base(从 app/workspace.ts 挪来,2026-11-09:托盘不带 zod 也要用) */
+export function expandPath(p, base) {
+    if (p === '~')
+        return homedir();
+    if (p.startsWith('~/'))
+        return join(homedir(), p.slice(2));
+    return isAbsolute(p) ? p : resolve(base, p);
+}
 export function redactHome(value) {
     const home = homedir();
     return home && value.startsWith(home) ? '$HOME' + value.slice(home.length) : value;

package/dist/ui/dev/dev-page.js

@@ -1297,7 +1297,7 @@ ${pageDomJs(4000)}
         catch (e) { feedback(card, false, e.message); }
       } } }, '补上'))));
     card.append(h('ul', { class: 'gaps' }, ...gaps.map((g) => h('li', {}, h('span', { class: g.kind === 'retired' ? 'plus minus' : 'plus' }, g.kind === 'retired' ? '−' : '+'), h('span', {}, g.detail)))));
-    card.append(h('p', { class: 'hint' }, '新版 cotutor 带来的新老师、新运行时、命令模板里的新旗标(+),和新版不再读的出厂段(−)。cotutor.json 是你的政策文件,机器不会自己改它,所以要你点一下。只改上面这些,你改过的值一个都不动;终端里等同于 cotutor upgrade --config。'));
+    card.append(h('p', { class: 'hint' }, '新版 cotutor 带来的新老师、新运行时、命令模板里的新旗标(+),和新版不再读的出厂段(−)。cotutor.json 是你的政策文件,机器不会自己改它,所以要你点一下。只改上面这些,你改过的值一个都不动;终端里等同于 cotutor refresh --config。'));
     return card;
   };
 
@@ -1590,7 +1590,7 @@ ${pageDomJs(4000)}
     const rows = listRows();
     const first = (want && rows.find((r) => (isTutorFile(r) ? r.tutor : r.tutor + '/' + r.name) === want)) || rows[0];
     if (first) return openActivity(first.tutor, first.name, true, first.kind);
-    $('#activity').replaceChildren(h('div', { class: 'wrap act-wrap' }, actHead(), h('p', { class: 'note' }, '这个 workspace 里还没有 activity(agents/<老师>/activities/<名>.md);cotutor upgrade 会补上出厂的。')));
+    $('#activity').replaceChildren(h('div', { class: 'wrap act-wrap' }, actHead(), h('p', { class: 'note' }, '这个 workspace 里还没有 activity(agents/<老师>/activities/<名>.md);cotutor refresh 会补上出厂的。')));
   };
 
   const openActivity = async (t, n, force, kind) => {
@@ -1875,7 +1875,7 @@ ${pageDomJs(4000)}
     if (!r.diff) return [h('p', { class: 'note' }, tf ? '自家加的老师,没有出厂那份可比。' : '自家加的 activity,没有出厂那份可比。')];
     const out = [h('div', { class: 'srow' }, r.diff.length ? h('span', { class: 'st accent' }, '和出厂不一样 ' + r.diff.length + ' 处') : h('span', { class: 'st ok' }, '和出厂一样'), h('span', { class: 'note' }, '含没存的')),
       ...r.diff.map((d) => hunkEl(d, true))];
-    out.push(h('p', { class: 'note' }, c.state === 'upgradable' ? '这份没改过,是旧版出厂的;cotutor upgrade 会换成新的。' : c.state === 'latest' ? '存下以后就算改过的出厂件:cotutor upgrade 不再自动换新版,只报 diff。' : '改过的出厂件,cotutor upgrade 不再自动换新版,只报 diff。'));
+    out.push(h('p', { class: 'note' }, c.state === 'upgradable' ? '这份没改过,是旧版出厂的;cotutor refresh 会换成新的。' : c.state === 'latest' ? '存下以后就算改过的出厂件:cotutor refresh 不再自动换新版,只报 diff。' : '改过的出厂件,cotutor refresh 不再自动换新版,只报 diff。'));
     out.push(rule(), h('div', { class: 'srow' },
       h('button', { class: 'btn danger', type: 'button', disabled: !r.diff.length && !dirtyCount(), on: { click: restoreActivityBtn } }, '恢复出厂'),
       h('span', { class: 'note' }, c.state === 'latest' ? '磁盘上那份就是出厂的,恢复只是丢掉没存的改动。' : '换回出厂那份;你这份存成 ' + bakName(c) + '。' + (tf ? '别的老师、这位老师的 activity 都不碰。' : '别的 activity 不碰。'))));
@@ -1920,7 +1920,7 @@ ${pageDomJs(4000)}
     out.push(h('div', { class: 'srow' }, h('span', { class: 'note', style: 'flex:1;min-width:160px' }, '这就是新话题里老师的系统提示:老师文件去掉 frontmatter' + (pv.board ? ',后面再接板书写法' : '') + '。'), h('button', { class: 'btn small', type: 'button', on: { click: (e) => copy(pv.text, e.target) } }, '复制全文')));
     if (pv.rules) {
       out.push(rule(), h('h3', {}, '话题第一条还带守则'),
-        h('p', { class: 'note' }, '有脸的老师共用的 ' + pv.rules.path + ',机器件,cotutor upgrade 每次覆盖,这里不改。这位老师要不一样的做法,写进上面的老师文件,它优先。'),
+        h('p', { class: 'note' }, '有脸的老师共用的 ' + pv.rules.path + ',机器件,cotutor refresh 每次覆盖,这里不改。这位老师要不一样的做法,写进上面的老师文件,它优先。'),
         h('details', {}, h('summary', {}, '看守则原文'), h('pre', { class: 'pv tool' }, pv.rules.text)));
     }
     out.push(rule(), h('p', { class: 'note' }, '档案、日记、计划这些每轮现拼进上下文包,不在这里;看一轮会拼成什么(不花钱):'),
@@ -1965,7 +1965,7 @@ ${pageDomJs(4000)}
   const restoreActivityBtn = async () => {
     const c = act.cur;
     const tf = isTutorFile(c);
-    const lead = c.state === 'latest' ? '磁盘上那份就是出厂的;没存的 ' + dirtyCount() + ' 处丢掉。' : '你这份存成 ' + bakName(c) + (dirtyCount() ? ',没存的 ' + dirtyCount() + ' 处一起丢掉' : '') + '。和 cotutor upgrade --force ' + c.tutor + (tf ? '' : '/' + c.name) + ' 同一条路,' + (tf ? '别的老师不碰。' : '别的 activity 不碰。');
+    const lead = c.state === 'latest' ? '磁盘上那份就是出厂的;没存的 ' + dirtyCount() + ' 处丢掉。' : '你这份存成 ' + bakName(c) + (dirtyCount() ? ',没存的 ' + dirtyCount() + ' 处一起丢掉' : '') + '。和 cotutor reset ' + c.tutor + (tf ? '' : '/' + c.name) + ' 同一条路,' + (tf ? '别的老师不碰。' : '别的 activity 不碰。');
     if (!(await ask('换回出厂那份?', [lead], '恢复出厂', '算了'))) return;
     let r;
     try { r = await api('POST', docUrl(c) + '/restore', {}); } catch (e) { alert(e.message); return; }

package/dist/ui/parent/parent-home-page.js

@@ -337,7 +337,7 @@ ${pageDomJs(3200)}
     if (st.ready) rows.push(h('div', { class: 'it' }, h('span', { class: 'tx' }, h('b', {}, '配好了'), h('small', {}, (st.keyTail ? 'key …' + st.keyTail + ' · 业务空间 ' + st.workspaceId : '测试用的假百炼'))),
       h('button', { type: 'button', class: 'x', disabled: BL.busy || null, on: { click: blTest } }, BL.busy && !BL.open ? '在试…' : '试连'),
       st.canEdit ? h('button', { type: 'button', class: 'x', on: { click: () => { BL.open = !BL.open; BL.msg = ''; blDraw(); } } }, BL.open ? '收起' : '换一把') : null));
-    else rows.push(h('div', { class: 'box' }, h('b', {}, '还没配,孩子那边打不开'), h('div', { class: 'note', style: 'padding:0' }, '老师开口和想讲稿都走百炼,要百炼「按量付费」的 API key(控制台「密钥管理」里创建)和业务空间 id(控制台的业务空间详情里看);Token Plan 的 sk-sp- 不行。存在这台电脑上,不进孩子的文件夹。')));
+    else rows.push(h('div', { class: 'box' }, h('b', {}, '还没配,孩子那边打不开'), h('div', { class: 'note', style: 'padding:0' }, '老师开口和想讲稿都走百炼,要百炼「按量付费」的 API key(控制台「密钥管理」里创建)和业务空间 id(控制台的业务空间详情里看);Token Plan 的 sk-sp- 不行。存在这台电脑上,不进孩子的 cotutor 文件夹。')));
     if (!st.ready || BL.open) {
       if (!st.canEdit) rows.push(h('div', { class: 'box' }, h('div', { class: 'note', style: 'padding:0' }, '先设家长密码:在电脑上跑 cotutor pin;或者在这台电脑上打开家长端来配。')));
       else rows.push(h('div', { class: 'box' }, h('label', { class: 'lbl', for: 'bl-key' }, 'API key'), blKey, h('label', { class: 'lbl', for: 'bl-ws' }, '业务空间 id'), blWs,

package/install.ps1

@@ -1,9 +1,10 @@
 # cotutor 一行安装(Windows,在 PowerShell 里粘贴):
+#   & ([scriptblock]::Create([Text.Encoding]::UTF8.GetString((iwr -useb https://cdn.jsdelivr.net/npm/cotutor@latest/install.ps1).Content)))
+# (jsDelivr 不标编码,PowerShell 5.1 的 irm 会把中文按 Latin-1 读成乱码,所以自己按 UTF-8 解)
+# 连不上 jsDelivr 就从 GitHub 取(GitHub 标了 utf-8,irm 就行):
 #   irm https://raw.githubusercontent.com/TarsLab/cotutor/main/install.ps1 | iex
-# 连不上 GitHub 就换这个:
-#   irm https://cdn.jsdelivr.net/npm/cotutor@latest/install.ps1 | iex
-# 顺手建好孩子的文件夹、装好后台服务(短名 称呼 年级):
-#   & ([scriptblock]::Create((irm https://raw.githubusercontent.com/TarsLab/cotutor/main/install.ps1))) ming 小明 2
+# 顺手建好孩子的文件夹、装好后台服务(短名 称呼 年级),最后接上就行:
+#   & ([scriptblock]::Create([Text.Encoding]::UTF8.GetString((iwr -useb https://cdn.jsdelivr.net/npm/cotutor@latest/install.ps1).Content))) ming 小明 2
 #
 # 只做这几件事:查 Node 的版本;npm 连不上就用国内镜像;装 cotutor。
 # 不要管理员,不改执行策略:npm、cotutor 都用 .cmd 跑(PowerShell 缺省策略会拦 .ps1)。Node 没装或太旧时只说怎么装,不替你装。

package/install.sh

@@ -1,10 +1,10 @@
 #!/bin/sh
 # cotutor 一行安装(macOS、Linux):
-#   curl -fsSL https://raw.githubusercontent.com/TarsLab/cotutor/main/install.sh | sh
-# 连不上 GitHub 就换这个:
 #   curl -fsSL https://cdn.jsdelivr.net/npm/cotutor@latest/install.sh | sh
+# 连不上 jsDelivr 就从 GitHub 取:
+#   curl -fsSL https://raw.githubusercontent.com/TarsLab/cotutor/main/install.sh | sh
 # 顺手建好孩子的文件夹、装好后台服务(短名 称呼 年级):
-#   curl -fsSL https://raw.githubusercontent.com/TarsLab/cotutor/main/install.sh | sh -s -- ming 小明 2
+#   curl -fsSL https://cdn.jsdelivr.net/npm/cotutor@latest/install.sh | sh -s -- ming 小明 2
 #
 # 只做这几件事:查 Node 的版本;npm 连不上就用国内镜像;全局目录写不了就换到自己家目录下(不用 sudo);装 cotutor。
 # 不用 sudo,不改系统设置。Node 没装或太旧时只说怎么装,不替你装。

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "cotutor",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "releaseNotes": [
-    "装得快多了:安装从 275 个包变成 15 个,Windows 上第一次装从 3 分钟左右变成 1 分钟左右",
-    "平板第一次用:在家长端「扫码打开」点「装证书」,用平板相机扫一下就能装根证书",
-    "电脑关了或睡着时,孩子在平板上打开看到「老师们还没到」,不再是浏览器的报错;电脑好了自己回来",
-    "有了一行安装命令(Mac、Windows 都有),README 里也写了怎么卸载"
+    "让 AI 助手帮你装更省事:不用输网址,对它说「帮我在这台电脑上装 cotutor,先跑 npx cotutor@latest guide,照它说的一步步做」",
+    "孩子的笔记文件夹(档案、日记、老师的记忆)新装时放在 cotutor 文件夹旁边,也可以用你已有的 Obsidian 库;以前装的照旧能用",
+    "Linux 上的后台服务能起来了",
+    "命令更好懂:cotutor --help 只列命令,每条的用法和例子在它自己的帮助里;写错的选项会直接说哪里不对,不再悄悄忽略",
+    "换新出厂文件改叫 cotutor refresh,把改过的老师换回出厂的用 cotutor reset;升级还是 cotutor update"
   ],
   "description": "AI tutors that co-teach with parents at home: real-time voice, an interactive whiteboard, and learning memory in your own Obsidian vault. Self-hosted; built for China's elementary curriculum.",
   "type": "module",
@@ -58,6 +59,7 @@
     "cards",
     "skills",
     "README.md",
+    "INSTALL.md",
     "LICENSE",
     "NOTICE",
     "install.sh",

package/skills/cotutor-analyze/SKILL.md

@@ -5,7 +5,7 @@ description: 在 cotutor workspace 里分析 AI 老师的对话:某一轮传了
 
 <!-- 给人看
 谁读:家长在 workspace 根开的编程助手
-能改:机器件,upgrade 覆盖;references/命令与文件.md 由 src/app/skills/analyze-doc.ts 生成
+能改:机器件,refresh 覆盖;references/命令与文件.md 由 src/app/skills/analyze-doc.ts 生成
 改了:在试用 workspace 里开编程助手问一句「老师为什么…」(《写提示词.md》§一)
 -->
 

package/skills/cotutor-analyze/references//345/221/275/344/273/244/344/270/216/346/226/207/344/273/266.md

@@ -1,17 +1,175 @@
 # 命令与文件(机器生成,别改)
 
-## 分析用的命令(在 workspace 根跑;完整用法 cotutor --help)
+## 分析用的命令(在 workspace 根跑;每条就是 cotutor <命令> --help 的内容)
 
 ```
-  cotutor doctor [--workspace <dir>] [--json] [--live] [--fix]                 逐项体检;--live 真连一次百炼实时模型、真合成一句配音(花一分钱)把 API 层的坑摆出来(真跑老师用 cotutor send);--json 里不过的项带 cmd(能直接跑)或 human(要人来);--fix 把带 cmd 的一条条修掉,要人来的留着
-  cotutor send <老师> [<消息>] [--from kid|system] [--runtime <名>] [--new] [--photo a.jpg,b.png] [--activity <名> [--param '名=值;名=值']] [--lane main,tts] [--quiet]   终端里发一条,现场按道打印每道工序的事件,说完打印结果(孩子的话照实时写,同孩子端:上下文包带 live:、不补提问卡,只是没有嘴;--from system 不算;--new 开新话题;--photo 带作业照片,拷进 captures/,有照片时消息可以空;--activity 像孩子点了首页的 activity 按钮,新开话题,参数同按钮下面那几行;--quiet 只要结果)
-  cotutor pack <老师> [<消息>] [--from kid|system] [--at <ISO时间>] [--activity <名> [--param '名=值;名=值']] [--json]   干跑上下文包(--activity 看 activity 话题第一条老师拿到什么):不起模型,打印现在会发给老师的那份 + 每段来自哪个文件、那里一共几条、按政策带了几条(改了档案 / 日记 / 计划立刻看效果)
-  cotutor replay <老师> <job> [<日期>] [--runtime <名>] [--json]   回放一轮:同一问按现在的 vault 与提示词再跑一遍(落 evals/,不进孩子的对话、不配音),跑完并排打印上下文包 / 讲稿 / 卡 / 读了什么的 diff
-  cotutor compare <老师> [<evalJob>] [<日期>] [--json]                   再看一次回放的对照(不给 evalJob 就列这天回放过哪些)
-  cotutor show <老师> <job> [<日期>] [--json] [--evals] [--workspace <dir>]   看一轮:问了什么、上下文包、当时的老师文件与技能 hash、讲稿与卡、读了什么、token 与用时、给家长的尾巴;--json 是家长端「看原文」同一份数据,给编程助手分析用
-  cotutor trace <老师> <job> [<日期>] [--lane …] [--workspace <dir>]     回放一轮的事件(<日期>.<job>.events.jsonl;排查昨天那轮用)
-  cotutor rate <老师> <话题> <1-5> [--date <日期>]                       给一个话题打星(与家长端同一条路;≥ vault.keepScore 的话题记账时摘要才进日记)
-  cotutor bookkeep <老师> [--date <日期>] [--thread <话题>]...           记账:这天每个还没记过的话题各起一轮记账任务,老师回「## 记账」,应用写进 vault 的日记(话题名、孩子问、摘要、观察)
+这些命令都认 --workspace <目录>(在 workspace 根跑可以不写)和 --sandbox(在试用副本里跑,不进孩子的记录)。
+
+cotutor show — 看一轮:问了什么、上下文包、讲稿与卡、读了什么
+
+用法:
+  cotutor show <老师> <job> [<日期>] [--evals] [--json]
+
+选项:
+  --evals  看回放的那轮(evals/ 里的)
+  --json   机器可读的输出
+
+说明:
+  - 日期缺省今天;--json 和家长端「看原文」是同一份
+
+例子:
+  cotutor show math-tutor 1620-1 2026-09-12 --json
+
+cotutor pack — 干跑上下文包:不起模型,看老师会拿到什么
+
+用法:
+  cotutor pack <老师> [<消息>] [--activity <名> [--param '名=值;名=值']] [--from kid|system] [--at <ISO时间>] [--json]
+
+选项:
+  --activity <名>        像孩子点了首页的 activity 按钮,新开话题
+  --param '名=值;名=值'  activity 的参数(按钮下面那几行)
+  --from kid|system      谁说的(缺省 kid;system 不算孩子说的)
+  --at <ISO时间>         当作这个时间
+  --json                 机器可读的输出
+
+说明:
+  - 每段来自哪个文件、一共几条、按政策带了几条;改了档案、日记、计划立刻看效果
+
+例子:
+  cotutor pack math-tutor "讲讲退位"
+
+cotutor replay — 同一问按现在的提示词再跑一遍,并排对照
+
+用法:
+  cotutor replay <老师> <job> [<日期>] [--runtime <名>] [--json]
+
+选项:
+  --runtime <名>  换个运行时
+  --json          机器可读的输出
+
+说明:
+  - 落 evals/,不进孩子的对话、不配音
+
+注意:
+  - 花钱
+
+例子:
+  cotutor replay math-tutor 1620-1 2026-09-12
+
+cotutor compare — 再看一次回放的对照
+
+用法:
+  cotutor compare <老师> [<evalJob>] [<日期>] [--json]
+
+选项:
+  --json  机器可读的输出
+
+说明:
+  - 不给 evalJob 就列这天回放过哪些
+
+例子:
+  cotutor compare math-tutor
+
+cotutor trace — 回放一轮的事件
+
+用法:
+  cotutor trace <老师> <job> [<日期>] [--lane <道>] [--json]
+
+选项:
+  --lane <道>  只看这几道的事件,逗号分开,如 main,tts
+  --json       机器可读的输出
+
+说明:
+  - 读 <日期>.<job>.events.jsonl;日期缺省今天
+
+例子:
+  cotutor trace math-tutor 1620-1 --lane main
+
+cotutor doctor — 体检;--fix 修掉能自动修的
+
+用法:
+  cotutor doctor [--json]
+  cotutor doctor --fix
+  cotutor doctor --live
+
+选项:
+  --fix   修掉能自动修的(幂等,不碰孩子的数据,不用人输东西),要人来的留着
+  --live  真连一次百炼的嘴、真配一句音
+  --json  机器可读的输出
+
+说明:
+  - --json 里没过的项带 cmd(能直接跑)或 human(要人来)
+  - 有必需项没过,退出码 1
+
+注意:
+  - --live 花一分钱
+
+例子:
+  cotutor doctor --fix
+  cotutor doctor --json
+
+cotutor send — 终端里给老师发一条
+
+用法:
+  cotutor send <老师> [<消息>] [--new] [--photo <图,图>] [--quiet] [--json]
+  cotutor send <老师> --activity <名> [--param '名=值;名=值']
+
+选项:
+  --new                  开新话题
+  --photo <图,图>        带作业照片(jpg / png,最多 9 张);有照片时消息可以空
+  --activity <名>        像孩子点了首页的 activity 按钮,新开话题
+  --param '名=值;名=值'  activity 的参数(按钮下面那几行)
+  --from kid|system      谁说的(缺省 kid;system 不算孩子说的)
+  --runtime <名>         换个运行时
+  --lane <道>            只看这几道的事件,逗号分开,如 main,tts
+  --quiet                只要结果,不打印过程
+  --json                 机器可读的输出
+
+说明:
+  - 孩子的话照实时写(同孩子端),只是没有嘴;事件落 events.jsonl,事后 cotutor trace 看
+
+注意:
+  - 花钱
+  - 写进孩子的对话记录(试一下用 --sandbox)
+
+例子:
+  cotutor send math-tutor "这一步为什么要借位"
+
+cotutor rate — 给一个话题打星(1–5)
+
+用法:
+  cotutor rate <老师> <话题> <1-5> [--date <日期>] [--json]
+
+选项:
+  --date <日期>  哪天(YYYY-MM-DD,缺省今天)
+  --json         机器可读的输出
+
+说明:
+  - 和家长端同一条路;到 vault.keepScore 星的话题,记账时摘要才进日记
+
+例子:
+  cotutor rate math-tutor 1620-1 4
+
+cotutor bookkeep — 记账:把这天的话题写进日记
+
+用法:
+  cotutor bookkeep <老师> [--date <日期>] [--thread <话题>] [--quiet] [--json]
+
+选项:
+  --date <日期>    哪天(YYYY-MM-DD,缺省今天)
+  --thread <话题>  只记这个话题
+  --quiet          不打印过程
+  --json           机器可读的输出
+
+说明:
+  - 每个还没记过的话题起一轮记账,应用写进笔记文件夹的日记
+
+注意:
+  - 花钱
+  - 写孩子的笔记文件夹
+
+例子:
+  cotutor bookkeep math-tutor
 ```
 
 ## 一轮的文件(conversations/ 下;回放的在 evals/ 下,同一套名字)

package/skills/cotutor-home/SKILL.md

@@ -5,7 +5,7 @@ description: 排 cotutor 孩子端的首页。孩子学完之后,家长在 works
 
 <!-- 给人看
 谁读:家长在 workspace 根开的编程助手
-能改:机器件,upgrade 覆盖;references/ 下的首页语法.md、命令.md、tutor.md 由 src/app/skills/home-doc.ts 与 cards/tutor/card.md 生成
+能改:机器件,refresh 覆盖;references/ 下的首页语法.md、命令.md、tutor.md 由 src/app/skills/home-doc.ts 与 cards/tutor/card.md 生成
 改了:在试用 workspace 里开编程助手说一句「总结一下今天」(《写提示词.md》§一)
 -->
 

package/skills/cotutor-home/references//345/221/275/344/273/244.md

@@ -1,14 +1,82 @@
 # 命令(机器生成,别改)
 
-在 workspace 根跑;完整用法 cotutor --help。
+在 workspace 根跑;每条就是 cotutor <命令> --help 的内容。
 
 ```
-  cotutor show <老师> <job> [<日期>] [--json] [--evals] [--workspace <dir>]   看一轮:问了什么、上下文包、当时的老师文件与技能 hash、讲稿与卡、读了什么、token 与用时、给家长的尾巴;--json 是家长端「看原文」同一份数据,给编程助手分析用
-  cotutor rate <老师> <话题> <1-5> [--date <日期>]                       给一个话题打星(与家长端同一条路;≥ vault.keepScore 的话题记账时摘要才进日记)
-  cotutor bookkeep <老师> [--date <日期>] [--thread <话题>]...           记账:这天每个还没记过的话题各起一轮记账任务,老师回「## 记账」,应用写进 vault 的日记(话题名、孩子问、摘要、观察)
-  cotutor home check [--published] [--json]                           检查首页草稿 home/draft.md(或已发布的那份):孩子会看到哪几张卡、每位老师的按钮、要改的与提醒(带行号);不花钱
-  cotutor home publish [--force] [--from <文件>] [--json]              发布首页:检查 → 留历史 home/history/<id>.md → 写 home/published.json(孩子端只读它);有要改的不发,--force 丢掉那几张照发;--from 发另一份(如历史)
-  cotutor home show [--json]                                          现在发布的是哪份、几天前、每个按钮被点了几次(哪天、哪个话题)
+这些命令都认 --workspace <目录>(在 workspace 根跑可以不写)和 --sandbox(在试用副本里跑,不进孩子的记录)。
+
+cotutor home — 检查和发布孩子端首页
+
+用法:
+  cotutor home check [--published] [--json]
+  cotutor home publish [--force] [--from <文件>] [--json]
+  cotutor home show [--json]
+
+选项:
+  --published    [check] 查已发布的那份(缺省查草稿 home/draft.md)
+  --force        [publish] 有要改的卡,丢掉它们照发
+  --from <文件>  [publish] 发另一份(比如历史里的)
+  --json         机器可读的输出
+
+说明:
+  - check 不花钱:孩子会看到哪几张卡、每位老师的按钮、要改的(带行号)
+  - publish 先检查,留历史 home/history/,写 home/published.json;孩子端刷新就是新的
+  - show:现在发布的是哪份、每个按钮被点了几次
+
+例子:
+  cotutor home check
+  cotutor home publish
+
+cotutor show — 看一轮:问了什么、上下文包、讲稿与卡、读了什么
+
+用法:
+  cotutor show <老师> <job> [<日期>] [--evals] [--json]
+
+选项:
+  --evals  看回放的那轮(evals/ 里的)
+  --json   机器可读的输出
+
+说明:
+  - 日期缺省今天;--json 和家长端「看原文」是同一份
+
+例子:
+  cotutor show math-tutor 1620-1 2026-09-12 --json
+
+cotutor rate — 给一个话题打星(1–5)
+
+用法:
+  cotutor rate <老师> <话题> <1-5> [--date <日期>] [--json]
+
+选项:
+  --date <日期>  哪天(YYYY-MM-DD,缺省今天)
+  --json         机器可读的输出
+
+说明:
+  - 和家长端同一条路;到 vault.keepScore 星的话题,记账时摘要才进日记
+
+例子:
+  cotutor rate math-tutor 1620-1 4
+
+cotutor bookkeep — 记账:把这天的话题写进日记
+
+用法:
+  cotutor bookkeep <老师> [--date <日期>] [--thread <话题>] [--quiet] [--json]
+
+选项:
+  --date <日期>    哪天(YYYY-MM-DD,缺省今天)
+  --thread <话题>  只记这个话题
+  --quiet          不打印过程
+  --json           机器可读的输出
+
+说明:
+  - 每个还没记过的话题起一轮记账,应用写进笔记文件夹的日记
+
+注意:
+  - 花钱
+  - 写孩子的笔记文件夹
+
+例子:
+  cotutor bookkeep math-tutor
 ```
 
 ## 文件