cotutor 0.3.0 → 0.4.0

package/dist/app/cli/tray-icons.js

@@ -0,0 +1,87 @@
+/**
+ * 托盘图标的 PNG:现画,不往仓里塞图片文件(同 favicon.ts);几何都来自 logo.ts 的双 C,16、18 px 这种小尺寸用小号那档。
+ * 正常时只有 logo;有事在右边缺口放状态点,橙 = 要处理,红 = 没在跑(同时 logo 变淡,不只靠颜色区分)。
+ *   macOS:logo 一张模板图(系统按菜单栏深浅着色),状态点一张模板图(叠在上面单独着色),18 pt @2x
+ *   Windows:没有底色,white 给深色任务栏、ink 给浅色任务栏,每种状态各画几档尺寸,按系统要的尺寸挑;变淡后对比度要过 3:1
+ * 菜单第一行的小圆点两边共用。
+ */
+import { LOGO_INK, LOGO_SMALL, logoHit } from "../../ui/shared/logo.js";
+import { encodePng } from "../../ui/shared/png.js";
+const rgb = (hex) => {
+    const v = parseInt(hex.slice(1), 16);
+    return [(v >> 16) & 0xff, (v >> 8) & 0xff, v & 0xff];
+};
+export const TRAY_DOT = { r: 14, cx: 85.5 };
+/** 没在跑时 logo 的不透明度(#F3F3F3 上墨色对比度 3.3,#202020 上白色 5.8) */
+export const TRAY_DIM = 0.55;
+export const TRAY_WIN_SIZES = [16, 20, 24, 32, 40, 48];
+const SS = 8;
+/** at 返回这一点的颜色与不透明度,null = 透明 */
+function draw(n, at) {
+    const px = Buffer.alloc(n * n * 4);
+    const unit = 100 / n;
+    for (let y = 0; y < n; y++) {
+        for (let x = 0; x < n; x++) {
+            let r = 0;
+            let g = 0;
+            let b = 0;
+            let a = 0;
+            for (let sy = 0; sy < SS; sy++) {
+                for (let sx = 0; sx < SS; sx++) {
+                    const p = at((x + (sx + 0.5) / SS) * unit, (y + (sy + 0.5) / SS) * unit);
+                    if (!p)
+                        continue;
+                    r += p.c[0] * p.a;
+                    g += p.c[1] * p.a;
+                    b += p.c[2] * p.a;
+                    a += p.a;
+                }
+            }
+            if (a <= 0)
+                continue;
+            const off = (y * n + x) * 4;
+            px[off] = Math.round(r / a);
+            px[off + 1] = Math.round(g / a);
+            px[off + 2] = Math.round(b / a);
+            px[off + 3] = Math.round((255 * a) / (SS * SS));
+        }
+    }
+    return encodePng(n, px, 4);
+}
+const inDot = (u, v) => Math.hypot(u - TRAY_DOT.cx, v - 50) <= TRAY_DOT.r;
+const BLACK = [0, 0, 0];
+/** 菜单里的小圆点(10 pt @2x) */
+const MENU_DOT = { ok: '#1F9D55', warn: '#E8830C', bad: '#D92D20' };
+const menuDot = (hex) => draw(20, (u, v) => (Math.hypot(u - 50, v - 50) <= 42 ? { c: rgb(hex), a: 1 } : null));
+/** 文件名 → 内容:macOS 那几张 */
+export function macTrayIcons() {
+    const out = {
+        'logo.png': draw(36, (u, v) => (logoHit(u, v, LOGO_SMALL) ? { c: BLACK, a: 1 } : null)),
+        'dotmark.png': draw(36, (u, v) => (inDot(u, v) ? { c: BLACK, a: 1 } : null)),
+    };
+    for (const [s, c] of Object.entries(MENU_DOT))
+        out[`dot-${s}.png`] = menuDot(c);
+    return out;
+}
+const WIN_THEMES = {
+    white: { fg: [255, 255, 255], warn: rgb('#FFA938'), bad: rgb('#FF5A4F') },
+    ink: { fg: rgb(LOGO_INK), warn: rgb('#C96A00'), bad: rgb('#D92D20') },
+};
+/** 文件名 → 内容:Windows 那几张(<white|ink>-<ok|warn|bad>-<尺寸>.png、dot-<状态>.png) */
+export function windowsTrayIcons() {
+    const out = {};
+    for (const [name, t] of Object.entries(WIN_THEMES)) {
+        for (const s of ['ok', 'warn', 'bad']) {
+            for (const n of TRAY_WIN_SIZES) {
+                out[`${name}-${s}-${n}.png`] = draw(n, (u, v) => {
+                    if (s !== 'ok' && inDot(u, v))
+                        return { c: t[s], a: 1 };
+                    return logoHit(u, v, LOGO_SMALL) ? { c: t.fg, a: s === 'bad' ? TRAY_DIM : 1 } : null;
+                });
+            }
+        }
+    }
+    for (const [s, c] of Object.entries(MENU_DOT))
+        out[`dot-${s}.png`] = menuDot(c);
+    return out;
+}

package/dist/app/cli/tray-ids.d.ts

@@ -0,0 +1,6 @@
+/** 托盘的几个名字。不和后台服务撞:服务的 Label 是 com.tarslab.cotutor.<名>、Run 项是 cotutor-<名>,workspace 叫 tray 也不会认错 */
+export declare const TRAY_LABEL = "com.tarslab.cotutor-tray";
+export declare const TRAY_RUN_VALUE = "cotutorTray";
+export declare const TRAY_AUMID = "cotutor.tray";
+/** 显示脚本发现没有桌面(ssh 进来的会话)时的退出码:node 不再起它 */
+export declare const HELPER_NO_SESSION = 3;

package/dist/app/cli/tray-ids.js

@@ -0,0 +1,6 @@
+/** 托盘的几个名字。不和后台服务撞:服务的 Label 是 com.tarslab.cotutor.<名>、Run 项是 cotutor-<名>,workspace 叫 tray 也不会认错 */
+export const TRAY_LABEL = 'com.tarslab.cotutor-tray';
+export const TRAY_RUN_VALUE = 'cotutorTray';
+export const TRAY_AUMID = 'cotutor.tray';
+/** 显示脚本发现没有桌面(ssh 进来的会话)时的退出码:node 不再起它 */
+export const HELPER_NO_SESSION = 3;

package/dist/app/cli/tray-mac.d.ts

@@ -0,0 +1,8 @@
+/**
+ * macOS 菜单栏图标的显示脚本:osascript -l JavaScript 跑,系统自带,不用签名、不用装东西(tray.ts 每次起来写到托盘目录再跑)。
+ * 这里只管画和回报,不判断状态:从 stdin 收一行一条 JSON(show / notify / confirm / inspect / press / quit),从 stdout 回一行一条 JSON(ready / click / confirm / state)。
+ * stdin 断了就退:看护它的 node 没了,图标也不该留着。
+ * JXA 的坑(2026-11-06 在 macOS 27.2 上试的):$.NSAttributedString.alloc.initWithStringAttributes 不存在,要 NSMutableAttributedString.alloc.init 再填;枚举常量取不到值,写数字(NSImageScaleProportionallyUpOrDown = 3);返回整数的方法给的是字符串,比较前要 Number()。
+ * 状态点是叠在按钮上的一层,系统的模板图才能继续跟着菜单栏深浅变;试过不挡点击。
+ */
+export declare const MAC_TRAY_SCRIPT: string;

package/dist/app/cli/tray-mac.js

@@ -0,0 +1,140 @@
+/**
+ * macOS 菜单栏图标的显示脚本:osascript -l JavaScript 跑,系统自带,不用签名、不用装东西(tray.ts 每次起来写到托盘目录再跑)。
+ * 这里只管画和回报,不判断状态:从 stdin 收一行一条 JSON(show / notify / confirm / inspect / press / quit),从 stdout 回一行一条 JSON(ready / click / confirm / state)。
+ * stdin 断了就退:看护它的 node 没了,图标也不该留着。
+ * JXA 的坑(2026-11-06 在 macOS 27.2 上试的):$.NSAttributedString.alloc.initWithStringAttributes 不存在,要 NSMutableAttributedString.alloc.init 再填;枚举常量取不到值,写数字(NSImageScaleProportionallyUpOrDown = 3);返回整数的方法给的是字符串,比较前要 Number()。
+ * 状态点是叠在按钮上的一层,系统的模板图才能继续跟着菜单栏深浅变;试过不挡点击。
+ */
+export const MAC_TRAY_SCRIPT = String.raw `ObjC.import('Cocoa');
+const app = Application.currentApplication();
+app.includeStandardAdditions = true;
+const dir = $.NSProcessInfo.processInfo.environment.objectForKey('COTUTOR_TRAY_DIR').js;
+const stdout = $.NSFileHandle.fileHandleWithStandardOutput;
+const stdin = $.NSFileHandle.fileHandleWithStandardInput;
+const emit = (o) => stdout.writeData($(JSON.stringify(o) + '\n').dataUsingEncoding($.NSUTF8StringEncoding));
+let item, menu, tray, dotView, current = 'ok', pending = $.NSMutableData.alloc.init;
+let ids = [];
+
+const image = (name, size, template) => {
+  const i = $.NSImage.alloc.initWithContentsOfFile($(dir + '/icons/' + name));
+  i.setSize($.NSMakeSize(size, size));
+  if (template) i.setTemplate(true);
+  return i;
+};
+const styled = (text, font, color) => {
+  const t = $.NSMutableAttributedString.alloc.init;
+  t.replaceCharactersInRangeWithString($.NSMakeRange(0, 0), $(text));
+  t.setAttributesRange($.NSDictionary.dictionaryWithObjectsForKeys($([font, color]), $([$.NSFontAttributeName, $.NSForegroundColorAttributeName])), $.NSMakeRange(0, text.length));
+  return t;
+};
+function center() {
+  const b = item.button.bounds;
+  dotView.frame = $.NSMakeRect((b.size.width - 18) / 2, (b.size.height - 18) / 2, 18, 18);
+}
+function fill(entries) {
+  menu.removeAllItems;
+  ids = [];
+  for (const e of entries) {
+    if (e.kind === 'sep') { menu.addItem($.NSMenuItem.separatorItem); continue; }
+    const m = $.NSMenuItem.alloc.initWithTitleActionKeyEquivalent($(e.title), e.kind === 'action' ? 'clicked:' : null, $(''));
+    if (e.kind === 'action') {
+      m.target = tray;
+      m.enabled = true;
+      // 标号从 1 起:别的行缺省是 0,按标号找会找到它们
+      ids.push(e.id);
+      m.tag = ids.length;
+      if (e.primary) m.attributedTitle = styled(e.title, $.NSFont.boldSystemFontOfSize(13), $.NSColor.labelColor);
+    } else if (e.kind === 'info') {
+      m.enabled = false;
+      m.attributedTitle = styled(e.title, $.NSFont.boldSystemFontOfSize(13), $.NSColor.labelColor);
+      if (e.level) m.image = image('dot-' + e.level + '.png', 10, false);
+    } else {
+      m.enabled = false;
+      m.attributedTitle = styled(e.title, $.NSFont.systemFontOfSize(11), $.NSColor.secondaryLabelColor);
+    }
+    menu.addItem(m);
+  }
+}
+function show(m) {
+  current = m.icon;
+  dotView.setHidden(m.icon === 'ok');
+  dotView.contentTintColor = m.icon === 'warn' ? $.NSColor.systemOrangeColor : $.NSColor.systemRedColor;
+  item.button.appearsDisabled = m.icon === 'bad';
+  item.button.toolTip = $(m.tip);
+  fill(m.menu);
+  center();
+}
+function quit() {
+  $.NSStatusBar.systemStatusBar.removeStatusItem(item);
+  $.NSApp.terminate(null);
+}
+function confirm(m) {
+  const a = $.NSAlert.alloc.init;
+  a.messageText = $(m.title);
+  a.informativeText = $(m.body);
+  // 第一个按钮是回车默认的那个:默认不退出
+  a.addButtonWithTitle($(m.no));
+  a.addButtonWithTitle($(m.yes));
+  $.NSApp.activateIgnoringOtherApps(true);
+  // 桥接把整数返回成字符串("1001"),不转就永远不等
+  emit({ type: 'confirm', id: m.id, yes: Number(a.runModal) === 1001 });
+}
+function handle(m) {
+  if (m.type === 'show') show(m);
+  else if (m.type === 'notify') { try { app.displayNotification(m.body, { withTitle: m.title }); } catch (e) { emit({ type: 'error', message: String(e) }); } }
+  else if (m.type === 'confirm') confirm(m);
+  else if (m.type === 'quit') quit();
+  else if (m.type === 'inspect') {
+    const titles = [];
+    for (let i = 0; i < menu.numberOfItems; i++) titles.push(menu.itemAtIndex(i).title.js);
+    emit({ type: 'state', icon: current, dot: !dotView.isHidden, dim: item.button.appearsDisabled, visible: (item.button.window.occlusionState & 2) === 2, appearance: item.button.effectiveAppearance.name.js, menu: titles });
+  } else if (m.type === 'press') {
+    const n = ids.indexOf(m.id);
+    if (n >= 0) { const at = menu.indexOfItemWithTag(n + 1); if (at >= 0) menu.performActionForItemAtIndex(at); }
+  }
+}
+function received() {
+  const data = stdin.availableData;
+  if (Number(data.length) === 0) { quit(); return; }
+  pending.appendData(data);
+  const text = $.NSString.alloc.initWithDataEncoding(pending, $.NSUTF8StringEncoding);
+  // 一个汉字被切在两块之间时解不出来:等下一块
+  if (!text.isNil()) {
+    const lines = text.js.split('\n');
+    const rest = lines.pop();
+    pending = $.NSMutableData.alloc.init;
+    if (rest) pending.appendData($(rest).dataUsingEncoding($.NSUTF8StringEncoding));
+    for (const line of lines) {
+      if (!line) continue;
+      try { handle(JSON.parse(line)); } catch (e) { emit({ type: 'error', message: String(e) }); }
+    }
+  }
+  stdin.waitForDataInBackgroundAndNotify;
+}
+ObjC.registerSubclass({
+  name: 'CotutorTray',
+  methods: {
+    'clicked:': { types: ['void', ['id']], implementation: function (sender) { emit({ type: 'click', id: ids[Number(sender.tag) - 1] }); } },
+    'received:': { types: ['void', ['id']], implementation: function () { received(); } },
+  },
+});
+const nsapp = $.NSApplication.sharedApplication;
+nsapp.setActivationPolicy($.NSApplicationActivationPolicyAccessory);
+tray = $.CotutorTray.alloc.init;
+item = $.NSStatusBar.systemStatusBar.statusItemWithLength(28);
+item.button.image = image('logo.png', 18, true);
+item.button.setAccessibilityLabel($('cotutor'));
+dotView = $.NSImageView.alloc.initWithFrame($.NSMakeRect(5, 2, 18, 18));
+dotView.image = image('dotmark.png', 18, true);
+dotView.imageScaling = 3;
+dotView.setHidden(true);
+item.button.addSubview(dotView);
+menu = $.NSMenu.alloc.init;
+menu.autoenablesItems = false;
+item.menu = menu;
+center();
+$.NSNotificationCenter.defaultCenter.addObserverSelectorNameObject(tray, 'received:', $.NSFileHandleDataAvailableNotification, stdin);
+stdin.waitForDataInBackgroundAndNotify;
+emit({ type: 'ready' });
+nsapp.run;
+`;

package/dist/app/cli/tray-run.d.ts

@@ -0,0 +1 @@
+export declare function main(argv: string[]): Promise<void>;

package/dist/app/cli/tray-run.js

@@ -0,0 +1,33 @@
+/**
+ * cotutor tray run 的轻入口:bin/cotutor.js 直接到这里,不经 main.ts。
+ * 托盘进程一直开着,main.ts 把所有命令都加载进来要多占近一百 MB(2026-11-06 量的,源码直跑 140 MB 对 63 MB);这里和 tray.ts 引的东西都不带 zod。
+ */
+import { mkdirSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { realHost } from "./service.js";
+import { realTrayDeps, runTray, trayDir, trayNote, traySupported, writeTrayFiles } from "./tray.js";
+const version = () => JSON.parse(readFileSync(fileURLToPath(new URL('../../../package.json', import.meta.url)), 'utf8')).version;
+export async function main(argv) {
+    const host = realHost();
+    if (!traySupported(host.platform)) {
+        process.stderr.write(`${host.platform} 上没做托盘图标\n`);
+        process.exitCode = 0;
+        return;
+    }
+    const at = argv.indexOf('--dir');
+    const dir = at >= 0 && argv[at + 1] ? argv[at + 1] : trayDir(host);
+    mkdirSync(dir, { recursive: true });
+    const note = trayNote(dir);
+    // 没接住的错误:记一笔再以非 0 退(macOS 上 launchd 隔 10 秒再起)
+    const fatal = (what) => (err) => {
+        note(`${what}:${err instanceof Error ? err.stack : String(err)}`);
+        process.exit(1);
+    };
+    process.on('uncaughtException', fatal('没接住的错误'));
+    process.on('unhandledRejection', fatal('没接住的 Promise 错误'));
+    const file = await writeTrayFiles(host.platform, dir);
+    note(`起来了,node ${process.versions.node},pid ${process.pid}`);
+    const code = await runTray(realTrayDeps(host, dir, file, version()));
+    note(`退出 ${code}`);
+    process.exit(code);
+}

package/dist/app/cli/tray-windows.d.ts

@@ -0,0 +1,5 @@
+export declare const WINDOWS_TRAY_SCRIPT: string;
+/** 找这台电脑上这个用户的托盘进程(命令行里带 tray run 和这个用户自己的托盘目录) */
+export declare function findTrayScript(dir: string): string;
+/** 启动器:wscript 跑它,藏着窗口起 node(和后台服务同一个办法,见 service-windows.ts) */
+export declare function trayLauncher(commandLine: string): string;

package/dist/app/cli/tray-windows.js

@@ -0,0 +1,166 @@
+/**
+ * Windows 托盘图标的显示脚本:Windows PowerShell + WinForms 的 NotifyIcon,系统自带,不用装东西(tray.ts 每次起来写到托盘目录再跑,存 UTF-8 带 BOM,不然中文按系统代码页读)。
+ * 这里只管画和回报,不判断状态:从 stdin 收一行一条 JSON(show / notify / confirm / inspect / press / quit),从 stdout 回一行一条 JSON(ready / click / confirm / state)。
+ * stdin 断了就退:看护它的 node 没了,图标也不该留着。没有桌面的会话(ssh 进来)里图标没人看得见,以 3 退,node 也不再起。
+ * 深浅自己看:每两秒读一次 SystemUsesLightTheme(任务栏跟它走,不是 AppsUseLightTheme;在深色任务栏上用白色 logo,浅色用墨色)。
+ * 通知走 WinRT 的 ToastNotifier + 注册的应用 ID,来源才写 cotutor;直接用 NotifyIcon 的气泡,来源是 Windows PowerShell(2026-11-06 build 26300 上都试过)。不行就退回气泡。
+ * 点通知没有动作:PowerShell 5.1 接不了 WinRT 的事件(Register-ObjectEvent 报 INVALID_REGISTRATION,脚本块直接接又在别的线程上没有 runspace),所以文案同 macOS,请家长点图标。
+ */
+import { TRAY_AUMID } from "./tray-ids.js";
+export const WINDOWS_TRAY_SCRIPT = String.raw `Add-Type -AssemblyName System.Windows.Forms, System.Drawing
+$dir = $env:COTUTOR_TRAY_DIR
+$aumid = '${TRAY_AUMID}'
+if ((Get-Process -Id $PID).SessionId -eq 0) { exit 3 }
+$utf8 = New-Object System.Text.UTF8Encoding($false)
+# stderr 进 tray.log:不设的话是系统代码页,中文 Windows 上读出来是乱码
+try { [Console]::OutputEncoding = $utf8 } catch { }
+$stdin = New-Object System.IO.StreamReader([Console]::OpenStandardInput(), $utf8)
+$stdout = [Console]::OpenStandardOutput()
+function Emit($o) {
+  $b = $utf8.GetBytes((ConvertTo-Json -Compress -InputObject $o) + [char]10)
+  $stdout.Write($b, 0, $b.Length)
+  $stdout.Flush()
+}
+$want = [System.Windows.Forms.SystemInformation]::SmallIconSize.Width
+$size = (@(16, 20, 24, 32, 40, 48) | Where-Object { $_ -ge $want } | Select-Object -First 1)
+if (-not $size) { $size = 48 }
+$icons = @{}; $dots = @{}
+foreach ($t in 'white', 'ink') { foreach ($s in 'ok', 'warn', 'bad') { $icons["$t-$s"] = [System.Drawing.Icon]::FromHandle(([System.Drawing.Bitmap]::new("$dir\icons\$t-$s-$size.png")).GetHicon()) } }
+foreach ($s in 'ok', 'warn', 'bad') { $dots[$s] = [System.Drawing.Bitmap]::new("$dir\icons\dot-$s.png") }
+$themeKey = 'HKCU:\Software\Microsoft\Windows\CurrentVersion\Themes\Personalize'
+function ThemeNow { try { if ((Get-ItemProperty $themeKey).SystemUsesLightTheme -eq 1) { 'ink' } else { 'white' } } catch { 'white' } }
+$amKey = "HKCU:\Software\Classes\AppUserModelId\$aumid"
+$script:toastReady = $false
+$script:theme = ThemeNow
+function RegisterToast {
+  New-Item $amKey -Force | Out-Null
+  Set-ItemProperty $amKey -Name DisplayName -Value 'cotutor'
+  Set-ItemProperty $amKey -Name IconUri -Value "$dir\icons\$($script:theme)-ok-48.png"
+}
+try {
+  RegisterToast
+  [void][Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime]
+  [void][Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType = WindowsRuntime]
+  $script:toastReady = $true
+} catch { Emit @{ type = 'error'; message = "toast: $_" } }
+$ni = New-Object System.Windows.Forms.NotifyIcon
+$script:level = 'ok'
+$ni.Icon = $icons["$($script:theme)-ok"]; $ni.Text = 'cotutor'; $ni.Visible = $true
+$menu = New-Object System.Windows.Forms.ContextMenuStrip
+$menu.ShowImageMargin = $false
+$menu.Font = New-Object System.Drawing.Font('Microsoft YaHei UI', 9)
+$bold = New-Object System.Drawing.Font('Microsoft YaHei UI', 9, [System.Drawing.FontStyle]::Bold)
+$tiny = New-Object System.Drawing.Font('Microsoft YaHei UI', 8)
+$grey = [System.Drawing.Color]::FromArgb(90, 90, 90)
+$ni.ContextMenuStrip = $menu
+$showMenu = [System.Windows.Forms.NotifyIcon].GetMethod('ShowContextMenu', [Reflection.BindingFlags]'Instance,NonPublic')
+$ni.add_MouseUp({ param($s, $e) if ($e.Button -eq 'Left') { try { $showMenu.Invoke($ni, $null) | Out-Null } catch { } } })
+function Quit {
+  $ni.Visible = $false
+  $ni.Dispose()
+  [System.Windows.Forms.Application]::Exit()
+}
+function Fill($entries) {
+  while ($menu.Items.Count) { $x = $menu.Items[0]; $menu.Items.RemoveAt(0); $x.Dispose() }
+  foreach ($e in $entries) {
+    if ($e.kind -eq 'sep') { [void]$menu.Items.Add((New-Object System.Windows.Forms.ToolStripSeparator)); continue }
+    if ($e.kind -eq 'action') {
+      $i = New-Object System.Windows.Forms.ToolStripMenuItem $e.title
+      $i.Tag = $e.id
+      if ($e.primary) { $i.Font = $bold }
+      $i.add_Click({ param($s, $a) Emit @{ type = 'click'; id = $s.Tag } })
+    } elseif ($e.kind -eq 'info') {
+      $i = New-Object System.Windows.Forms.ToolStripLabel $e.title
+      $i.Font = $bold
+      if ($e.level) { $i.Image = $dots[$e.level]; $i.ImageAlign = 'MiddleLeft' }
+      $i.TextAlign = 'MiddleLeft'
+    } else {
+      $i = New-Object System.Windows.Forms.ToolStripLabel $e.title
+      $i.Font = $tiny
+      $i.ForeColor = $grey
+      $i.TextAlign = 'MiddleLeft'
+    }
+    [void]$menu.Items.Add($i)
+  }
+}
+function Show($m) {
+  $script:level = $m.icon
+  $ni.Icon = $icons["$($script:theme)-$($m.icon)"]
+  $t = [string]$m.tip
+  if ($t.Length -gt 63) { $t = $t.Substring(0, 63) }
+  $ni.Text = $t
+  Fill $m.menu
+}
+function Notify($title, $body) {
+  if ($script:toastReady) {
+    try {
+      $esc = { param($v) [System.Security.SecurityElement]::Escape([string]$v) }
+      $xml = New-Object Windows.Data.Xml.Dom.XmlDocument
+      $xml.LoadXml("<toast><visual><binding template='ToastGeneric'><text>$(& $esc $title)</text><text>$(& $esc $body)</text></binding></visual></toast>")
+      $toast = [Windows.UI.Notifications.ToastNotification]::new($xml)
+      [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier($aumid).Show($toast)
+      return
+    } catch { Emit @{ type = 'error'; message = "toast: $_" } }
+  }
+  $ni.ShowBalloonTip(8000, $title, $body, [System.Windows.Forms.ToolTipIcon]::None)
+}
+function Confirm($m) {
+  $owner = New-Object System.Windows.Forms.Form
+  $owner.TopMost = $true
+  $answer = [System.Windows.Forms.MessageBox]::Show($owner, $m.body, $m.title, 'YesNo', 'Warning', 'Button2')
+  $owner.Dispose()
+  Emit @{ type = 'confirm'; id = $m.id; yes = ($answer -eq 'Yes') }
+}
+function Handle($m) {
+  switch ($m.type) {
+    'show' { Show $m }
+    'notify' { Notify $m.title $m.body }
+    'confirm' { Confirm $m }
+    'quit' { Quit }
+    'inspect' {
+      $titles = @(); foreach ($i in $menu.Items) { $titles += [string]$i.Text }
+      $p = Get-Process -Id $PID
+      Emit @{ type = 'state'; icon = $script:level; theme = $script:theme; size = $size; privateMb = [int]($p.PrivateMemorySize64 / 1MB); workingMb = [int]($p.WorkingSet64 / 1MB); menu = $titles }
+    }
+    'press' { foreach ($i in $menu.Items) { if ($i.Tag -eq $m.id) { $i.PerformClick(); break } } }
+  }
+}
+$script:reading = $stdin.ReadLineAsync()
+$script:themeAt = Get-Date
+$timer = New-Object System.Windows.Forms.Timer
+$timer.Interval = 200
+$timer.add_Tick({
+  while ($script:reading.IsCompleted) {
+    $line = $script:reading.Result
+    if ($null -eq $line) { $timer.Stop(); Quit; return }
+    $script:reading = $stdin.ReadLineAsync()
+    if ($line) { try { Handle (ConvertFrom-Json $line) } catch { Emit @{ type = 'error'; message = [string]$_ } } }
+  }
+  if (((Get-Date) - $script:themeAt).TotalSeconds -ge 2) {
+    $script:themeAt = Get-Date
+    $t = ThemeNow
+    if ($t -ne $script:theme) {
+      $script:theme = $t
+      $ni.Icon = $icons["$t-$($script:level)"]
+      if ($script:toastReady) { try { RegisterToast } catch { } }
+    }
+  }
+})
+$timer.Start()
+Emit @{ type = 'ready' }
+[System.Windows.Forms.Application]::Run()
+`;
+/** 找这台电脑上这个用户的托盘进程(命令行里带 tray run 和这个用户自己的托盘目录) */
+export function findTrayScript(dir) {
+    return [
+        `$dir = '${dir.replaceAll("'", "''")}'`,
+        "$found = @(Get-CimInstance Win32_Process -Filter \"Name='node.exe'\" | Where-Object { $c = $_.CommandLine; $c -and $c.Contains($dir) -and $c.Contains(' tray run ') })",
+        'ConvertTo-Json -Compress -InputObject @($found | ForEach-Object { @{ pid = $_.ProcessId; keeper = $true } })',
+    ].join('\n');
+}
+/** 启动器:wscript 跑它,藏着窗口起 node(和后台服务同一个办法,见 service-windows.ts) */
+export function trayLauncher(commandLine) {
+    return `// cotutor tray on 写的;改了会被下次盖掉。关掉:cotutor tray off
+new ActiveXObject("WScript.Shell").Run(${JSON.stringify(commandLine)}, 0, false);
+`;
+}

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

@@ -0,0 +1,205 @@
+import { type Health, type InstalledService, type ServiceHost } from './service.ts';
+import { HELPER_NO_SESSION, TRAY_AUMID, TRAY_LABEL, TRAY_RUN_VALUE } from './tray-ids.ts';
+export { HELPER_NO_SESSION, TRAY_AUMID, TRAY_LABEL, TRAY_RUN_VALUE };
+/** 多久问一次 */
+export declare const TRAY_POLL_MS = 5000;
+/** 连着几次问不到才算没在跑:重起一下、网络抖一下不报 */
+export declare const TRAY_STRIKES = 2;
+/** 图标刚起来时服务可能还没起来:这么久里问不到算「正在启动」(Windows 登录后约一分钟才跑 Run 项) */
+export declare const TRAY_START_GRACE_MS = 90000;
+/** 点了启动、重启以后等多久 */
+export declare const TRAY_RESTART_GRACE_MS = 30000;
+/** 两次问之间隔太久 = 刚睡醒:网络还没回来,先别报 */
+export declare const TRAY_WAKE_GAP_MS = 30000;
+export declare const TRAY_WAKE_GRACE_MS = 30000;
+export type TrayLevel = 'ok' | 'warn' | 'bad';
+export type RowLevel = TrayLevel | 'starting';
+export type TrayFix = {
+    kind: 'open';
+    target: string;
+} | {
+    kind: 'restart';
+};
+/** 一个服务这一轮问到的 */
+export interface TrayProbe {
+    name: string;
+    kid: string;
+    root: string;
+    logDir: string | null;
+    port: number;
+    health: Health | null;
+    /** 问不到时端口被谁占着(「nginx」);不知道 → null */
+    holder: string | null;
+}
+/** 一个服务现在的样子 */
+export interface TrayRow {
+    name: string;
+    kid: string;
+    logDir: string | null;
+    level: RowLevel;
+    /** 家长端地址;服务没答应 → null */
+    url: string | null;
+    /** 第二行小字 */
+    detail: string;
+    /** 有几件事要处理 */
+    issues: number;
+    fix: TrayFix | null;
+    calls: number;
+}
+export type TrayEntry = {
+    kind: 'info';
+    title: string;
+    level?: TrayLevel;
+} | {
+    kind: 'sub';
+    title: string;
+} | {
+    kind: 'sep';
+} | {
+    kind: 'action';
+    id: string;
+    title: string;
+    primary?: boolean;
+};
+export interface TrayShow {
+    type: 'show';
+    icon: TrayLevel;
+    tip: string;
+    menu: TrayEntry[];
+}
+export interface TrayNote {
+    type: 'notify';
+    title: string;
+    body: string;
+}
+/** 跑了多久,给家长看 */
+export declare function uptimeText(startedMs: number, now: number): string;
+/** 服务在跑,但有事要家长处理:先后就是轻重,菜单上只说第一件 */
+export declare function issuesOf(p: TrayProbe, o: {
+    platform: NodeJS.Platform;
+    version: string;
+}): {
+    text: string;
+    fix: TrayFix;
+}[];
+/** 记着每个服务上一轮的样子,算这一轮的样子和要不要通知;不碰任何系统,测试直接喂 */
+export declare class TrayModel {
+    private readonly mem;
+    private last;
+    private readonly o;
+    constructor(o: {
+        platform: NodeJS.Platform;
+        version: string;
+    });
+    /** 刚点了启动、重启:这一阵问不到是正常的 */
+    expect(name: string, now: number): void;
+    update(probes: TrayProbe[], now: number): {
+        rows: TrayRow[];
+        notes: TrayNote[];
+    };
+    private healthy;
+    private placeholder;
+}
+/** 这一轮显示什么 */
+export declare function trayShow(rows: TrayRow[]): TrayShow;
+export interface HelperMessage {
+    type: string;
+    id?: string;
+    yes?: boolean;
+    message?: string;
+}
+export interface TrayHelper {
+    send(m: unknown): void;
+    /** 关 stdin:显示脚本读到头自己退 */
+    close(): void;
+}
+export interface TrayDeps {
+    platform: NodeJS.Platform;
+    version: string;
+    now(): number;
+    list(): Promise<InstalledService[]>;
+    /** 读 cotutor.json:孩子叫什么、哪个端口 */
+    inspect(s: InstalledService): Promise<{
+        kid: string;
+        port: number;
+    }>;
+    probe(port: number): Promise<Health | null>;
+    holder(port: number): Promise<string | null>;
+    control(root: string, what: 'start' | 'stop' | 'restart'): Promise<unknown>;
+    open(target: string): void;
+    spawnHelper(on: {
+        message(m: HelperMessage): void;
+        exit(code: number | null): void;
+    }): TrayHelper;
+    note(text: string): void;
+    pollMs?: number;
+    helperRestartMs?: number;
+}
+export declare const QUIT_CONFIRM: {
+    id: string;
+    title: string;
+    body: string;
+    yes: string;
+    no: string;
+};
+/** 主循环:问状态、发给显示脚本、接点击;都退了才返回退出码。0 = 不用再起(点了退出、没有服务了、没有桌面) */
+export declare function runTray(d: TrayDeps): Promise<number>;
+export declare const traySupported: (platform: NodeJS.Platform) => boolean;
+type HostPaths = Pick<ServiceHost, 'platform' | 'home' | 'env'>;
+/** 显示脚本、图标、日志放哪 */
+export declare function trayDir(host: HostPaths): string;
+/** 写显示脚本(每次起来都写,升级后马上生效)和图标(版本变了才画,画一次要几百毫秒) */
+export declare function writeTrayFiles(platform: NodeJS.Platform, dir: string): Promise<string>;
+/** 起显示脚本 */
+export declare function spawnTrayHelper(platform: NodeJS.Platform, file: string, dir: string, note: (t: string) => void, on: {
+    message(m: HelperMessage): void;
+    exit(code: number | null): void;
+}): TrayHelper;
+/** 打开地址或目录(Windows 不弹黑窗口) */
+export declare function openTarget(platform: NodeJS.Platform, target: string): void;
+/** 日志:一个文件,过 1 MB 换一次,只留上一份 */
+export declare function trayNote(dir: string): (text: string) => void;
+/** 孩子叫什么、哪个端口:只读这两样,不加载 zod(托盘进程常驻,要轻);读不了就用服务名和缺省端口 */
+export declare function inspectService(s: InstalledService): Promise<{
+    kid: string;
+    port: number;
+}>;
+/** 真的依赖,给 runTray */
+export declare function realTrayDeps(host: ServiceHost, dir: string, file: string, version: string): TrayDeps;
+/** 登录项跑的命令 */
+export declare const trayArgs: (host: HostPaths, o?: {
+    node?: string;
+    bin?: string;
+}) => string[];
+/** macOS 的 LaunchAgent:登录就起,崩了拉起,以 0 退(点了退出)不拉 */
+export declare function trayPlist(args: string[], dir: string, path: string): string;
+/** 装上并起来;已经装过就照现在的 node、bin 重写一遍再起(升级后新代码才生效)。started = false:登录项写好了,这个会话里起不来,下次登录出现 */
+export declare function installTray(host: ServiceHost, o?: {
+    node?: string;
+    bin?: string;
+}): Promise<{
+    file: string;
+    started: boolean;
+}>;
+/** 卸掉:停下、删登录项。remember = 家长说不要(以后 service install 也不再装) */
+export declare function removeTray(host: ServiceHost, o?: {
+    remember?: boolean;
+}): Promise<boolean>;
+export interface TrayStatus {
+    supported: boolean;
+    installed: boolean;
+    running: boolean;
+    pid: number | null;
+    /** 家长关掉过(cotutor tray off) */
+    off: boolean;
+    /** Windows:下次登录还会不会起来;别的系统 null */
+    autostart: boolean | null;
+}
+export declare function trayStatus(host: ServiceHost): Promise<TrayStatus>;
+/** service install 时跟着装:没做的系统、家长关掉过都跳过;返回给人看的结果 */
+export declare function ensureTray(host: ServiceHost, o?: {
+    node?: string;
+    bin?: string;
+}): Promise<'unsupported' | 'off' | 'started' | 'later'>;
+/** 服务卸完了:图标也撤(不算家长说不要,以后再装服务还会带上) */
+export declare function dropTrayIfNoServices(host: ServiceHost): Promise<boolean>;