cotutor 0.4.3 → 0.4.5

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/kid/kid-page.js

@@ -3674,6 +3674,8 @@ __REEL_DOCK_JS__
     location.reload();
   };
   setInterval(() => { staleReload(); if (S.tutor) { if (!S.pending) loadDay(true); } else loadHome(); }, 5000);
+  // 离线页(offline-sw.ts):电脑关了、睡着了时,点开主屏幕图标看到「老师们还没到」,不是浏览器的报错。只在 https(或 localhost)上有;回放、预览里不装
+  if (!REEL && !PREVIEW && window.isSecureContext && 'serviceWorker' in navigator) navigator.serviceWorker.register('/sw.js').catch(() => {});
   document.addEventListener('visibilitychange', () => { if (!document.hidden) (S.tutor ? loadDay(true) : loadHome()); });
   // 孩子端刷新(手动的、Safari 自己重载的)回到手上这位老师;在首页刷新就回首页。只读回放不记(重载回来是今天的)
   if (!REEL && !PREVIEW) window.addEventListener('pagehide', () => { try { if (S.tutor && !S.readonly) sessionStorage.setItem('kid-resume', S.tutor.name); else sessionStorage.removeItem('kid-resume'); } catch {} });

package/dist/ui/kid/offline-sw.d.ts

@@ -0,0 +1 @@
+export declare const KID_SW_JS: string;

package/dist/ui/kid/offline-sw.js

@@ -0,0 +1,42 @@
+/**
+ * 孩子端的离线页(Service Worker,GET /sw.js):电脑关了、睡着了、服务没在跑时,平板上打开孩子端看到的不是浏览器的报错,是「老师们休息中」。
+ * 和页面开着时断线的样子(kid-page 的 #rest)同一句:都是「电脑那边连不上」;「老师们还没到」是百炼没配好,另一回事。
+ * 孩子端永远没有错误:这一页只说老师们休息、叫爸爸妈妈,不说连接、不说服务器。
+ * 页面开着时断线由页面自己管(灰掉、「老师们休息中」);这一页只在重新打开(iPad 把网页 App 清出内存后再点开、刷新)时出现。
+ *
+ * 只接管孩子端那几页的打开(导航);接口、静态文件、别的页面一律不碰。不缓存任何东西:平时原样走网络,孩子看不到旧页面;
+ * 连不上或 12 秒没回应才给离线页,它每 5 秒问一次 /api/health,通了就自己刷新回去。
+ * Service Worker 只在安全上下文里有(https 且平板信任了根证书,或 localhost);http 时孩子端照旧,什么都不变。
+ * 改了这个文件就改 VERSION:平板上的旧 worker 靠脚本内容变了才换。
+ */
+const VERSION = '2';
+/** 离线页本身:没有网可取,样式、脚本都内联 */
+const OFFLINE_HTML = [
+    '<!doctype html><html lang="zh-CN"><head><meta charset="utf-8">',
+    '<meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">',
+    '<meta name="apple-mobile-web-app-capable" content="yes"><title>老师们休息中</title>',
+    '<style>html,body{height:100%;margin:0}body{display:flex;align-items:center;justify-content:center;background:#f7f3ea;color:#3a352c;',
+    'font:22px/1.6 -apple-system,"PingFang SC","Microsoft YaHei",sans-serif;text-align:center;-webkit-user-select:none;user-select:none}',
+    'p{margin:0 24px}small{display:block;margin-top:12px;font-size:17px;color:#8a8273}</style></head>',
+    '<body><p id="off">老师们休息中<small>叫爸爸妈妈来看一下:家里那台电脑是不是关了、睡着了</small></p>',
+    '<script>setInterval(function(){fetch("/api/health",{cache:"no-store"}).then(function(r){if(r.ok)location.reload()}).catch(function(){})},5000)</script>',
+    '</body></html>',
+].join('');
+export const KID_SW_JS = `// cotutor 孩子端的离线页 v${VERSION}(src/ui/kid/offline-sw.ts)
+const KID = new Set(['/', '/dictation', '/dictation/', '/talk', '/talk/']);
+const WAIT_MS = 12000;
+const OFFLINE = ${JSON.stringify(OFFLINE_HTML)};
+self.addEventListener('install', () => { self.skipWaiting(); });
+self.addEventListener('activate', (e) => { e.waitUntil(self.clients.claim()); });
+self.addEventListener('fetch', (e) => {
+  const r = e.request;
+  if (r.mode !== 'navigate' || r.method !== 'GET') return;
+  const u = new URL(r.url);
+  if (u.origin !== self.location.origin || !KID.has(u.pathname)) return;
+  const offline = () => new Response(OFFLINE, { status: 200, headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' } });
+  e.respondWith(Promise.race([
+    fetch(r).catch(() => null),
+    new Promise((resolve) => { setTimeout(() => resolve(null), WAIT_MS); }),
+  ]).then((res) => res || offline()));
+});
+`;

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,
@@ -365,24 +365,27 @@ ${pageDomJs(3200)}
         h('span', { style: 'flex:none;display:flex', html: QR_ICON }), h('span', { class: 'tx' }, h('b', {}, '扫码打开'), h('small', {}, seen)), h('span', { class: 'lnk', style: 'font-size:14px' }, '展开'))));
       return;
     }
-    const kid = QR.to === 'kid', c = kid ? d : (d.parent || d);
+    if (QR.to === 'ca' && !d.ca) QR.to = 'kid';
+    const kid = QR.to === 'kid', ca = QR.to === 'ca', c = kid ? d : ca ? d.ca : (d.parent || d);
     const useIp = QR.ip && c.ip;
-    const seg = h('div', { class: 'seg', role: 'group', 'aria-label': '给谁扫' }, ...[['kid', '孩子的平板'], ['parent', '我的手机']].map(([k, l]) =>
+    // 装证书(serve.ts 的 http 那一面给根证书):平板第一次用之前扫一次;有证书、找得到根证书才有这一格
+    const tabs = [['kid', '孩子的平板'], ['parent', '我的手机']].concat(d.ca ? [['ca', '装证书']] : []);
+    const seg = h('div', { class: 'seg', role: 'group', 'aria-label': '给谁扫' }, ...tabs.map(([k, l]) =>
       h('button', { type: 'button', class: QR.to === k ? 'on' : '', 'aria-pressed': QR.to === k ? 'true' : 'false', on: { click: () => { QR.to = k; qrDraw(); } } }, l)));
     const print = '/parent/qr?' + new URLSearchParams(Object.assign({}, useIp ? { via: 'ip' } : {}, kid ? {} : { to: 'parent' })).toString();
     qrEl.replaceChildren(
       h('div', { class: 'gh' }, h('span', {}, '扫码打开'), h('button', { type: 'button', class: 'x', 'aria-expanded': 'true', on: { click: () => qrToggle(false) } }, '收起')),
       h('div', { class: 'grp' }, h('div', { class: 'box' }, seg,
         h('div', { class: 'qrrow' }, h('div', { class: 'qrimg', html: (useIp ? c.svgIp : c.svg) || '' }),
-          h('b', { style: 'font-weight:600' }, kid ? '用孩子平板的相机扫一下' : '用你自己的手机扫一下'),
-          h('span', { class: 'lbl', style: 'line-height:1.5' }, kid ? '打开的就是孩子的首页。在 Safari 里「添加到主屏幕」,以后点图标就进来。' : '打开的是家长端:看记录、排首页。也可以添加到主屏幕。')),
+          h('b', { style: 'font-weight:600' }, kid ? '用孩子平板的相机扫一下' : ca ? '平板第一次用:先扫这张装证书' : '用你自己的手机扫一下'),
+          h('span', { class: 'lbl', style: 'line-height:1.5' }, kid ? '打开的就是孩子的首页。在 Safari 里「添加到主屏幕」,以后点图标就进来。' : ca ? '扫了点「允许」下载描述文件;到「设置」最上面点「已下载描述文件」装上;再到「设置 › 通用 › 关于本机 › 证书信任设置」把开关打开。装好再扫「孩子的平板」那张。每台平板做一次。' : '打开的是家长端:看记录、排首页。也可以添加到主屏幕。')),
         h('div', { class: 'qrurl' }, useIp ? c.ip : c.url),
         d.https ? null : h('div', { class: 'qrwarn' }, d.notes[0] || ''),
         h('div', { class: 'row2', style: 'font-size:14px' },
           c.ip ? h('button', { type: 'button', class: 'x', style: 'height:auto;padding:0;font-size:14px;text-align:left', on: { click: () => { QR.ip = !QR.ip; qrDraw(); } } }, useIp ? '换回 ' + host(c.url) : '扫了打不开?换成 ' + host(c.ip)) : h('span'),
           h('span', { style: 'display:flex;gap:14px;flex:none' },
             h('a', { class: 'lnk kidl', style: 'font-size:14px', href: '/', target: '_blank' }, '孩子端 ↗'),
-            h('a', { class: 'lnk', style: 'font-size:14px', href: print, target: '_blank' }, '打印 ›'))))),
+            ca ? null : h('a', { class: 'lnk', style: 'font-size:14px', href: print, target: '_blank' }, '打印 ›'))))),
       h('div', { class: 'note' }, d.https ? (d.notes[0] || '') : '', d.devices ? '' : (d.https ? ' ' : '') + '还没有平板连进来过,所以这块先开着;连过以后自动收起。'));
   };
 

package/install.ps1

@@ -0,0 +1,67 @@
+# 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
+# 顺手建好孩子的文件夹、装好后台服务(短名 称呼 年级),最后接上就行:
+#   & ([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 没装或太旧时只说怎么装,不替你装。
+$ErrorActionPreference = 'Stop'
+
+function Say($text) { Write-Host $text }
+function Stop-Here($text) { Write-Host $text; throw 'cotutor-install-stopped' }
+
+$needMajor = 22
+$needMinor = 18
+
+try {
+  # ---- 1. Node ----
+  if (-not (Get-Command node -ErrorAction SilentlyContinue)) {
+    Stop-Here "这台电脑还没有 Node.js:到 https://nodejs.org 下载 LTS 版(Windows 安装程序)装上,或者跑 winget install OpenJS.NodeJS.LTS;装完重开 PowerShell 再跑这一行。"
+  }
+  $v = (& node -p 'process.versions.node').Trim()
+  $parts = $v.Split('.')
+  if ([int]$parts[0] -lt $needMajor -or ([int]$parts[0] -eq $needMajor -and [int]$parts[1] -lt $needMinor)) {
+    Stop-Here "Node.js 是 $v,cotutor 要 $needMajor.$needMinor 以上:到 https://nodejs.org 装新的 LTS 版,重开 PowerShell 再跑这一行。"
+  }
+  if (-not (Get-Command npm.cmd -ErrorAction SilentlyContinue)) { Stop-Here '有 Node.js 但找不到 npm:到 https://nodejs.org 重新装一次 LTS 版。' }
+  Say "Node.js $v"
+
+  # ---- 2. npm 连得上吗(国内常连不上,换镜像) ----
+  $registry = $null
+  try { Invoke-WebRequest -UseBasicParsing -TimeoutSec 8 'https://registry.npmjs.org/cotutor/latest' | Out-Null }
+  catch { $registry = 'https://registry.npmmirror.com'; Say "npm 连不上或太慢,用国内镜像 $registry" }
+
+  # ---- 3. 装 ----
+  Say '正在下载 cotutor,要一会儿……'
+  $npmArgs = @('i', '-g', 'cotutor', '--no-audit', '--no-fund')
+  if ($registry) { $npmArgs += "--registry=$registry" }
+  & npm.cmd @npmArgs
+  if ($LASTEXITCODE -ne 0) { Stop-Here 'npm 没装成:看上面的报错;连不上就过一会儿再试。' }
+  # 刚装上的 cotutor.cmd 在 npm 的全局目录里;这个窗口的 PATH 可能还没有它
+  $globalDir = (& npm.cmd prefix -g).Trim()
+  if (-not (Get-Command cotutor.cmd -ErrorAction SilentlyContinue)) { $env:Path = "$globalDir;$env:Path" }
+  if (-not (Get-Command cotutor.cmd -ErrorAction SilentlyContinue)) { Stop-Here "装好了但找不到 cotutor:重开 PowerShell 再试;还不行,把 $globalDir 加进 PATH。" }
+  Say ('cotutor ' + (& cotutor.cmd --version).Trim() + ' 装好了')
+
+  # ---- 4. 带了孩子的信息就接着建文件夹、装后台服务 ----
+  if ($args.Count -ge 1) {
+    $initArgs = @('init', $args[0])
+    if ($args.Count -ge 2 -and $args[1]) { $initArgs += @('--name', $args[1]) }
+    if ($args.Count -ge 3 -and $args[2]) { $initArgs += @('--grade', [string]$args[2]) }
+    & cotutor.cmd @initArgs
+    if ($LASTEXITCODE -ne 0) { Stop-Here '建孩子的文件夹没成:看上面的报错。' }
+    & cotutor.cmd service install
+    Say ''
+    Say '好了。家长端已经在浏览器里打开;以后点任务栏右下角 ^ 里的 cotutor 图标,或者跑 cotutor.cmd open。'
+  } else {
+    Say ''
+    Say '接下来(短名用小写字母,不用真名;年级 1 到 6):'
+    Say '  cotutor.cmd init ming --name 小明 --grade 2'
+    Say '  cotutor.cmd service install'
+  }
+} catch {
+  if ($_.Exception.Message -ne 'cotutor-install-stopped') { Write-Host ('出错了:' + $_.Exception.Message) }
+}

package/install.sh

@@ -0,0 +1,84 @@
+#!/bin/sh
+# cotutor 一行安装(macOS、Linux):
+#   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://cdn.jsdelivr.net/npm/cotutor@latest/install.sh | sh -s -- ming 小明 2
+#
+# 只做这几件事:查 Node 的版本;npm 连不上就用国内镜像;全局目录写不了就换到自己家目录下(不用 sudo);装 cotutor。
+# 不用 sudo,不改系统设置。Node 没装或太旧时只说怎么装,不替你装。
+set -eu
+
+say() { printf '%s\n' "$*"; }
+die() { say "$*"; exit 1; }
+
+NEED_MAJOR=22
+NEED_MINOR=18
+
+# ---- 1. Node ----
+command -v node >/dev/null 2>&1 || die "这台电脑还没有 Node.js:到 https://nodejs.org 下载 LTS 版装上,重开终端再跑这一行。"
+v=$(node -p 'process.versions.node')
+major=${v%%.*}
+rest=${v#*.}
+minor=${rest%%.*}
+if [ "$major" -lt "$NEED_MAJOR" ] || { [ "$major" -eq "$NEED_MAJOR" ] && [ "$minor" -lt "$NEED_MINOR" ]; }; then
+  die "Node.js 是 $v,cotutor 要 $NEED_MAJOR.$NEED_MINOR 以上:到 https://nodejs.org 装新的 LTS 版,重开终端再跑这一行。"
+fi
+command -v npm >/dev/null 2>&1 || die "有 Node.js 但找不到 npm:到 https://nodejs.org 重新装一次 LTS 版。"
+say "Node.js $v"
+
+# ---- 2. npm 连得上吗(国内常连不上,换镜像) ----
+REGISTRY=""
+if ! curl -fsS -o /dev/null --max-time 8 https://registry.npmjs.org/cotutor/latest 2>/dev/null; then
+  REGISTRY="https://registry.npmmirror.com"
+  say "npm 连不上或太慢,用国内镜像 $REGISTRY"
+fi
+
+# ---- 3. 全局目录写得了吗(官网的 Mac 安装包装在 /usr/local,要 sudo 才能写;不用 sudo,换到家目录下) ----
+root=$(npm root -g)
+target=$root
+[ -d "$target" ] || target=$(dirname "$target")
+if [ ! -w "$target" ]; then
+  prefix="$HOME/.npm-global"
+  say "npm 的全局目录 $root 这个账户写不了,改装到 $prefix(不用 sudo)"
+  mkdir -p "$prefix"
+  npm config set prefix "$prefix"
+  case "${SHELL:-}" in
+    */zsh) rc="$HOME/.zshrc" ;;
+    */bash) if [ "$(uname)" = Darwin ]; then rc="$HOME/.bash_profile"; else rc="$HOME/.bashrc"; fi ;;
+    *) rc="$HOME/.profile" ;;
+  esac
+  line='export PATH="$HOME/.npm-global/bin:$PATH"'
+  if ! grep -qsF "$line" "$rc"; then
+    printf '\n# cotutor 安装脚本加的:npm 全局命令装在家目录下\n%s\n' "$line" >> "$rc"
+    say "在 $rc 里加了一行 PATH,新开的终端就认得 cotutor"
+  fi
+  PATH="$prefix/bin:$PATH"
+  export PATH
+fi
+
+# ---- 4. 装 ----
+say "正在下载 cotutor,要一会儿……"
+if [ -n "$REGISTRY" ]; then npm i -g cotutor --no-audit --no-fund --registry="$REGISTRY"; else npm i -g cotutor --no-audit --no-fund; fi
+command -v cotutor >/dev/null 2>&1 || die "装好了但找不到 cotutor 命令:重开终端再试;还不行,把 $(npm prefix -g)/bin 加进 PATH。"
+say "cotutor $(cotutor --version) 装好了"
+
+# ---- 5. 带了孩子的信息就接着建文件夹、装后台服务 ----
+if [ $# -ge 1 ]; then
+  slug=$1
+  set -- "$@" "" ""
+  name=$2
+  grade=$3
+  if [ -n "$name" ] && [ -n "$grade" ]; then cotutor init "$slug" --name "$name" --grade "$grade"
+  elif [ -n "$name" ]; then cotutor init "$slug" --name "$name"
+  else cotutor init "$slug"; fi
+  cotutor service install
+  say ""
+  say "好了。家长端已经在浏览器里打开;以后点菜单栏的 cotutor 图标,或在终端跑 cotutor open。"
+else
+  say ""
+  say "接下来(短名用小写字母,不用真名;年级 1 到 6):"
+  say "  cotutor init ming --name 小明 --grade 2"
+  say "  cotutor service install"
+fi

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "cotutor",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "releaseNotes": [
-    "自动备份:服务开着时每天一份,升级前一份,可以恢复;录音占地方,不在备份里",
-    "家长端首页多了「还差几步」,第一次打开就知道接下来做什么;选一下年级老师就知道孩子上几年级",
-    "遇到问题时,家长端「设置」能生成诊断信息,不含孩子的对话和 key,先看再发",
-    "`cotutor init --grade` 自动算好学期,`cotutor doctor --fix` 一次修掉能自动修的"
+    "让 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,8 +59,12 @@
     "cards",
     "skills",
     "README.md",
+    "INSTALL.md",
     "LICENSE",
-    "NOTICE"
+    "NOTICE",
+    "install.sh",
+    "install.ps1",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "gen:skills": "node --experimental-strip-types scripts/gen-skills.ts",
@@ -75,18 +80,18 @@
   },
   "dependencies": {
     "@ai-sdk/alibaba": "2.0.78",
-    "@excalidraw/excalidraw": "0.18.1",
     "ai": "7.0.155",
     "hanzi-writer-data": "2.0.1",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
     "typescript": "^5.6.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@excalidraw/excalidraw": "0.18.1",
     "@types/node": "^22.20.1",
     "@types/react": "^18.3.31",
     "@types/react-dom": "^18.3.7",
-    "esbuild": "^0.28.2"
+    "esbuild": "^0.28.2",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
   }
 }

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》§一)
 -->