cotutor 0.3.0 → 0.4.1

package/dist/schema/config.js

@@ -5,6 +5,8 @@
  * 人设(display / avatar / voice)、政策、开关全在这里。
  */
 import { z } from 'zod';
+import { DEFAULT_PORT } from "../shared/default-port.js";
+export { DEFAULT_PORT };
 export const PolicySchema = z.object({
     /** 老师说给孩子听的每一句的字数上限;超出在句末截断(板书后按句算) */
     replyMaxChars: z.number().int().positive().describe('老师说给孩子听的每一句的字数上限(板书讲稿一行一句,按句截);超出在句末截断'),
@@ -24,7 +26,7 @@ export const PolicySchema = z.object({
      * 孩子的话,老师带不带工具(2026-10-04):填进运行时模板的 {tools}。ray 9 月的真实对话,用了工具的轮首拍就绪中位数 31.7 秒(24 轮),没用的 6.8 秒(37 轮);
      * 孩子最喜欢的是回得快的那位老师。off 时要用的东西由应用放进上下文包
      */
-    tools: z.enum(['off', 'on']).describe('孩子说的话,老师带不带工具:off = 不带,只凭上下文包答,开口快(缺省);on = 带只读工具(查教材、读 vault,慢)。带照片的那条、记账,总是带只读工具(read_file / glob / grep_search)。模板里没有 {tools} / {toolArgs} 的运行时不受影响'),
+    tools: z.enum(['off', 'on']).describe('孩子说的话,老师带不带工具:off = 不带,只凭上下文包答,开口快(缺省);on = 带只读工具(查教材、读 vault,慢)。带照片的那条、记账,总是带只读工具(read_file / glob / grep_search)'),
     /** 板书开关:auto = 老师判断要不要出卡(缺省);off = 只说话不出卡 */
     board: z.enum(['auto', 'off']).describe('板书:auto = 讲题讲概念时老师出卡(缺省);off = 只说话不出卡'),
     /**
@@ -60,12 +62,23 @@ export const BOARD_CARD_KINDS = ['text', 'read', 'choice', 'image', 'tianzige',
 export const AGENT_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
 /** 老师卡上的常驻入口:不经首页发布、一直在那位老师的卡上 */
 export const TUTOR_EXTRAS = ['dictation', 'talk'];
+/**
+ * 老师卡上常驻的三块方砖(设计稿 https://claude.ai/artifact/NpPFoyvuF17dbRSEUuRJfW):先后就是牌上的先后。
+ * id 记在消息的 via.button;activity 是老师家里同名的文件(agents/<老师>/activities/<名>.md),孩子看到的字也是它。
+ * 家里有那个文件才出那一块(三门主科出厂都有);cotutor.json 的 tiles 只记关掉的,升级来的老 workspace 自动就有
+ */
+export const HOME_TILES = [
+    { id: 'preview', activity: '预习' },
+    { id: 'check', activity: '检查作业' },
+    { id: 'review', activity: '复习' },
+];
+export const HOME_TILE_IDS = HOME_TILES.map((t) => t.id);
 export const TutorSchema = z.object({
     /** 显示名(孩子端头像下的字、计划文件的 H2 标题) */
     display: z.string().min(1).describe('显示名:孩子端头像下的字,计划文件的 H2 标题'),
     subject: z.string().optional().describe('学科:与课程表的学科列、观察的 subject、vault 入口文件的 subject 属性对齐即归到这位老师'),
     /** 头像:一个 emoji 或图片相对路径 */
-    avatar: z.string().optional().describe('头像:一个 emoji,或 workspace 根以内的图片相对路径(如 avatars/math-tutor.png;figshot pick --workspace 会写这个)'),
+    avatar: z.string().optional().describe('头像:一个 emoji,或 workspace 根以内的图片相对路径(如 avatars/math-tutor.png;figshot pick --workspace 会写这个);不写 = 语文、数学、英语用出厂头像,其余显示学科首字'),
     /** 学科色:头像的环、牌的边、新话题气泡(白字压在上面)、听写页的按钮;不写 = 自动(src/ui/shared/tutor-color.ts) */
     color: z.string().regex(/^#[0-9a-fA-F]{6}$/, '要 #rrggbb').optional().describe('学科色 #rrggbb:头像的环、牌的边、新话题气泡(白字压在上面,要够深,doctor 会查)、听写页的按钮;不写 = 语文粉、数学蓝、英语绿,其余按先后自动分、不撞色'),
     /** 卡的配音音色 id(src/media/tts-voices.ts);没有 = 卡不配音 */
@@ -79,6 +92,8 @@ export const TutorSchema = z.object({
     /** 这位老师用哪个运行时(runtimes 里的键);不配用 runtimes.default。要更大预算与时限的老师配一个自己的 */
     runtime: z.string().optional().describe('这位老师用的运行时(runtimes 里的键;不配用 default)——预算、时限不同的老师配自己的'),
     extras: z.array(z.enum(TUTOR_EXTRAS)).optional().describe('老师卡上的常驻入口:dictation 听写(含拍照听写)、talk 口语课(要 talk.enabled);不写按学科给缺省:语文有听写,其余没有;[] = 都不要'),
+    /** 三块方砖(HOME_TILES)哪块关掉:只记 false;没写 = 开着(家里有那个 activity 文件才出) */
+    tiles: z.object(Object.fromEntries(HOME_TILE_IDS.map((id) => [id, z.boolean().optional()]))).strict().optional().describe('老师卡上常驻的方砖:preview 预习、check 检查作业、review 复习;写 false 关掉,没写 = 开着(老师家里有那个 activity 文件才出)'),
 });
 /** 三门主科的别名:学科写「英文」「English」也认作英语,颜色、听写用英文、语文缺省带听写都照它 */
 const SUBJECT_ALIASES = {
@@ -106,26 +121,23 @@ export function tutorExtras(t, talkOn = false) {
     const s = canonicalSubject(t.subject);
     return s === '语文' ? ['dictation'] : s === '英语' && talkOn ? ['talk'] : [];
 }
+/** 这位老师开着的方砖(牌上的先后);家里有没有那个 activity 文件不在这里管 */
+export function tutorTiles(t) {
+    return HOME_TILE_IDS.filter((id) => t.tiles?.[id] !== false);
+}
 /**
- * 运行时:一个 CLI 一组 {run, resume} 命令模板。占位符:
- * {agent} 老师名 / {agentBody} 老师文件正文(给没有 --agent 的 CLI 塞系统提示)/ {prompt} 消息 / {session} 会话 id。
- * 板书写法的两种预载({boardFile} 板书技能 SKILL.md 的绝对路径,给能从文件追加系统提示的 CLI;{systemBody} 老师正文 + 板书写法,给只收一段系统提示文字的 CLI):
- * 模板里用了其中一个,应用就当板书写法已在系统提示里;都没用,应用在话题第一条消息里注入 <cotutor-board>(任何 CLI 都成立的退路)。
- * {effort} 这位老师的政策 effort(low / medium / high),qwen 由适配器写入思考量配置。
- * 带不带工具由适配器展开(src/brain/cli/):{tools} 填一串工具名,独占一个参数的 {toolArgs} 展开成几个参数。
- * 政策旋钮(预算、轮数、模型)写进模板,换 agent 只换运行时。
- * stdin: "stream-json":消息不进命令行,写进 stdin(`--input-format stream-json`),
- * 模板里就不写 {prompt};argv 与消息无关,应用把下一轮的进程提前起好等着。
+ * 旧的命令行运行时:一组 {run, resume} 命令模板(起 Qwen Code;更早是 Claude CLI)。2026-11-02 起不再支持,
+ * 留着这个形状只为旧 cotutor.json 读得进来:doctor 报出来,用到它的老师发不出去(src/brain/runtime.ts)。
  */
 export const CliRuntimeSchema = z.object({
-    cli: z.string().min(1).optional().describe('这是哪个 CLI(src/brain/cli/ 里的适配器名:qwen);不写按 run 的第一个词认。套了壳脚本的运行时要写'),
+    cli: z.string().min(1).optional(),
     run: z.array(z.string()).min(1),
     resume: z.array(z.string()).min(1),
-    stdin: z.literal('stream-json').optional().describe('消息写进 stdin(模板带 --input-format stream-json、不写 {prompt});这样的运行时,应用提前把下一轮的老师进程起好等着(预热)'),
-});
+    stdin: z.literal('stream-json').optional(),
+}).describe('旧的命令行运行时(Qwen Code 等),2026-11-02 起不再支持:改成 {api, model}');
 /**
- * 内置 API 运行时(2026-10-29):应用自己直连模型(src/brain/api.ts),不起 CLI、不用装 Qwen Code。
- * 现在只有百炼(OpenAI 兼容的 Chat Completions,端点是业务空间 id 的域名);凭证是机器级的百炼配置(家长端「首页」里填的按量 key 与业务空间 id)。
+ * API 运行时(2026-10-29;2026-11-02 起只有它):应用自己直连模型(src/brain/api.ts)。
+ * 现在只有百炼(OpenAI 兼容的 Chat Completions);凭证是机器级的 ~/.config/cotutor/(家长端「首页」填的按量 key 与业务空间 id,开发机还有 Token Plan)。
  * 系统提示 = 老师正文 + 板书写法;同一话题的模型历史由应用存;effort 映射成思考开关与思考量;工具只有只读的三样。
  */
 export const ApiRuntimeSchema = z.object({
@@ -193,6 +205,14 @@ export const LiveSchema = z.object({
 });
 /** 这位老师的嘴用哪个音色 */
 export const mouthVoice = (live, tutor) => live.voices[tutor] ?? SHIPPED_MOUTHS[tutor] ?? MOUTH_VOICE;
+/** 卡的配音(点读、单词卡、听写念词)的缺省:出厂三位各一个(2026-11-03 照 Ray 那里用着的),不写进 cotutor.json;别的老师没配就不配音 */
+export const SHIPPED_CARD_VOICES = {
+    'chinese-tutor': 'qwen-audio-3.0-tts-plus-longfengyutong',
+    'math-tutor': 'qwen-audio-3.0-tts-plus-longyingsongliu',
+    'english-tutor': 'qwen-audio-3.0-tts-plus-loongnorahu',
+};
+/** 这位老师卡的配音用哪个音色:家长挑的,没挑用出厂的;都没有 undefined(不配音) */
+export const cardVoice = (tutors, tutor) => tutors[tutor]?.voice ?? SHIPPED_CARD_VOICES[tutor];
 /**
  * 听写:拍照认词表用哪个模型。挑词的要求在听写 activity 文件「认字收到什么」;
  * 下面两份是出厂那节的原文,workspace 里没有听写 activity 文件时照它。回什么格式(一行一段 JSON)由应用填(src/scenes/dictation/recognize.ts 的 FORMAT)。
@@ -256,21 +276,21 @@ export const CotutorConfigSchema = z
         grade: z.string().optional(),
         /** 孩子端用哪个主题(themes/<name>/);缺省 default(出厂主题,init 拷进 workspace) */
         theme: z.string().regex(AGENT_NAME_RE).default('default').describe('孩子端的主题:themes/<名字>/(theme.json + kid.css);cotutor add-theme <名字> 拷一份出厂的来改'),
-        /** 孩子的惯用手:left = 左撇子,平板横屏实时老师页的左栏浮层挪到右边(写字的手空着,另一只手按住说话);缺省右手,不写进文件 */
-        hand: z.enum(['right', 'left']).optional().describe('孩子的惯用手:left = 左撇子,平板横屏实时老师页的浮层(按住说话)挪到右边;缺省右手(浮层在左边)。工作台设置页能切'),
+        /** 按住说话那一栏放哪边:left = 平板横屏实时老师页的那一栏(与画板那列工具)挪到右边,写字的在左边;缺省 right(那一栏在左边),不写进文件 */
+        hand: z.enum(['right', 'left']).optional().describe('按住说话那一栏放哪边:left = 平板横屏实时老师页的那一栏挪到右边;缺省 right(在左边)。家长端设置页能切'),
     }),
     server: z
         .object({
-        port: z.number().int().min(1).max(65535).default(5180),
+        port: z.number().int().min(1).max(65535).default(DEFAULT_PORT).describe('端口。cotutor init 选一次写在这里(443 优先);改了平板要重新扫码、重加主屏幕图标'),
         /** 只给这个 workspace 用的证书(相对 workspace 根),是例外;不配则用机器级 ~/.config/cotutor/certs/(cotutor cert 会建,所有 workspace 共用;iPad 上录音要 HTTPS) */
         https: z.object({ cert: z.string().min(1), key: z.string().min(1) }).optional(),
     })
-        .default({ port: 5180 }),
+        .default({ port: DEFAULT_PORT }),
     paths: z.record(z.string(), z.string()).default({}).describe('角色 → 目录:vault 指 Obsidian vault 根;diary / plans / profile / timetable / textbooks / reference 相对 vault(缺省 日记 / 计划 / 孩子.md / 课程表.md / 教材 / 参考),不配 vault 就相对 workspace 根;profile 只是 init 新建档案的位置,老师按 cotutor: profile 属性找;captures(作业照片)相对 workspace 根'),
     vault: VaultPolicySchema.default({ keepScore: 4, autoBookkeep: false }).describe('vault 的写入政策:keepScore 话题打几星起才把摘要沉淀进日记(缺省 4);autoBookkeep 自动记账(缺省关)'),
     policyDefaults: PolicyPatchSchema.default({}).describe('所有老师的政策缺省;没写的用出厂缺省(60 字 / 板书 auto / 观察 10 条、计划 10 行、原文 4000 字)'),
     tutors: z.record(z.string().regex(AGENT_NAME_RE), TutorSchema).default({}).describe('老师表:键 = agents/<键>.md 的 frontmatter name;人设、开关、政策都在这里,老师文件里只有正文'),
-    runtimes: RuntimesSchema.describe('运行时:default 指一个键;每个运行时是 {run, resume} 命令模板(起 CLI)或 {api, model}(应用直连模型),占位 {agent} {agentBody} {systemBody} {boardFile} {prompt} {session};模型、预算、时限写在这里'),
+    runtimes: RuntimesSchema.describe('运行时:default 指一个键;每个运行时是 {api, model}(应用直连百炼);老师用哪个模型写在这里'),
     figshot: z
         .object({ port: z.number().int().min(1).max(65535).default(8477) })
         .optional()
@@ -278,7 +298,7 @@ export const CotutorConfigSchema = z
     dictation: DictationSchema.default(DICTATION_DEFAULT).describe('听写(/dictation):拍照认词表用的模型(改了不用重起服务);挑词的要求在听写 activity 文件「认字收到什么」'),
     paint: PaintSchema.default(PAINT_DEFAULT).describe('你说我画:画图卡(paint)用的文生图模型、尺寸(改了不用重起服务);画风在 activity 文件「画家收到什么」'),
     talk: TalkSchema.default(TALK_DEFAULT).describe('口语课(/talk):孩子拍一张今天学的,改好口语单交给英语老师的实时页(先热身、再打电话);enabled 出厂 false'),
-    live: LiveSchema.default(LIVE_DEFAULT).describe('实时老师:有脸的老师都由 realtime 模型开口、老师 CLI 在后面写板书(讲稿不配音、嘴照念);voices 挑嘴的音色;要百炼按量 key 与业务空间 id'),
+    live: LiveSchema.default(LIVE_DEFAULT).describe('实时老师:有脸的老师都由 realtime 模型开口、脑在后面写板书(讲稿不配音、嘴照念);voices 挑嘴的音色;要百炼按量 key 与业务空间 id'),
 })
     .superRefine((c, ctx) => {
     for (const name of Object.keys(c.live.voices)) {
@@ -289,20 +309,9 @@ export const CotutorConfigSchema = z
         ctx.addIssue({
             code: 'custom',
             path: ['runtimes', 'default'],
-            message: `运行时 "${c.runtimes.default}" 不存在;runtimes 里要有同名的 {run, resume}(或 API 运行时 {api, model})`,
+            message: `运行时 "${c.runtimes.default}" 不存在;runtimes 里要有同名的 {api, model}`,
         });
     }
-    for (const [name, r] of Object.entries(c.runtimes)) {
-        if (typeof r === 'string' || isApiRuntime(r) || !r.stdin)
-            continue;
-        for (const key of ['run', 'resume']) {
-            const argv = r[key];
-            const at = argv.indexOf('--input-format');
-            if (argv.some((a) => a.includes('{prompt}')) || at < 0 || argv[at + 1] !== 'stream-json') {
-                ctx.addIssue({ code: 'custom', path: ['runtimes', name, key], message: `运行时 "${name}" 设了 stdin: "stream-json",${key} 模板要带 --input-format stream-json、不写 {prompt}` });
-            }
-        }
-    }
 });
 /** 老师的有效政策 = POLICY_DEFAULTS ← policyDefaults ← tutors[name].policy */
 export function resolvePolicy(config, tutor) {
@@ -340,22 +349,11 @@ export function listTutors(config, opts = {}) {
         subject: t.subject,
         avatar: t.avatar,
         color: t.color,
-        voice: t.voice,
+        voice: cardVoice(config.tutors, name),
         enabled: t.enabled,
         hidden: t.hidden,
         policy: resolvePolicy(config, name),
         extras: tutorExtras(t, config.talk.enabled),
+        tiles: tutorTiles(t),
     }));
 }
-/** 运行时模板填占位符;{tools} 填适配器给的工具名单(src/brain/cli/ 的 fillArgs 先算好,没给就填空);{agentBody} / {systemBody} / {boardFile} 只在给了值时替换,否则原样留着(doctor 会报);{effort} 没给用出厂缺省(课文件排版这类不认老师政策的调用) */
-export function fillRuntime(argv, vars) {
-    return argv.map((a) => a
-        .replaceAll('{agent}', vars.agent)
-        .replaceAll('{prompt}', vars.prompt)
-        .replaceAll('{session}', vars.session ?? '')
-        .replaceAll('{agentBody}', vars.agentBody ?? '{agentBody}')
-        .replaceAll('{systemBody}', vars.systemBody ?? '{systemBody}')
-        .replaceAll('{boardFile}', vars.boardFile ?? '{boardFile}')
-        .replaceAll('{effort}', vars.effort ?? POLICY_DEFAULTS.effort)
-        .replaceAll('{tools}', vars.tools ?? ''));
-}

package/dist/schema/conversation.d.ts

@@ -240,7 +240,10 @@ export declare const ConversationMessageSchema: z.ZodObject<{
     via: z.ZodOptional<z.ZodObject<{
         home: z.ZodNullable<z.ZodString>;
         button: z.ZodUnion<readonly [z.ZodNumber, z.ZodEnum<{
+            check: "check";
             recent: "recent";
+            preview: "preview";
+            review: "review";
             new: "new";
         }>]>;
         label: z.ZodString;
@@ -483,7 +486,10 @@ export declare const ConversationIndexSchema: z.ZodObject<{
         via: z.ZodOptional<z.ZodObject<{
             home: z.ZodNullable<z.ZodString>;
             button: z.ZodUnion<readonly [z.ZodNumber, z.ZodEnum<{
+                check: "check";
                 recent: "recent";
+                preview: "preview";
+                review: "review";
                 new: "new";
             }>]>;
             label: z.ZodString;

package/dist/schema/home.d.ts

@@ -25,20 +25,30 @@ export declare const PublishedHomeSchema: z.ZodObject<{
     warnings: z.ZodDefault<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export type PublishedHome = z.infer<typeof PublishedHomeSchema>;
-/** 孩子从首页哪个按钮进来的:home = 发布的 id(没发布过的缺省首页是 null),button = 老师卡上文件里的第几个按钮,或应用加的 new / recent */
+/** 孩子从首页哪个按钮进来的:home = 发布的 id(没发布过的缺省首页是 null),button = 老师卡上文件里的第几个按钮,或应用加的 new / recent,或常驻的方砖(HOME_TILES 的 id) */
 export declare const HomeViaSchema: z.ZodObject<{
     home: z.ZodNullable<z.ZodString>;
     button: z.ZodUnion<readonly [z.ZodNumber, z.ZodEnum<{
+        check: "check";
         recent: "recent";
+        preview: "preview";
+        review: "review";
         new: "new";
     }>]>;
 }, z.core.$strip>;
+/** 这一下发出去的字是按钮上的字、不是孩子说的(家长排的按钮、方砖);新话题、接着刚才的不算 */
+export declare function viaSendsLabel(via: {
+    button: number | string;
+}): boolean;
 export type HomeVia = z.infer<typeof HomeViaSchema>;
 /** 消息里记的 via:再带上按钮上的字(发布的首页以后会换,记下来 home show 才说得清) */
 export declare const MessageViaSchema: z.ZodObject<{
     home: z.ZodNullable<z.ZodString>;
     button: z.ZodUnion<readonly [z.ZodNumber, z.ZodEnum<{
+        check: "check";
         recent: "recent";
+        preview: "preview";
+        review: "review";
         new: "new";
     }>]>;
     label: z.ZodString;

package/dist/schema/home.js

@@ -4,6 +4,7 @@
  */
 import { z } from 'zod';
 import { BoardCardSchema } from "./board.js";
+import { HOME_TILE_IDS } from "./config.js";
 const DAY_RE = /^\d{4}-\d{2}-\d{2}$/;
 /** 发布的 id:发布时刻 YYYY-MM-DD-HHMM,同一分钟再发加 -2、-3 */
 export const HOME_ID_RE = /^\d{4}-\d{2}-\d{2}-\d{4}(?:-\d+)?$/;
@@ -21,10 +22,14 @@ export const PublishedHomeSchema = z.object({
     /** 发布时还在的提醒(家长端「首页」页显示) */
     warnings: z.array(z.string()).default([]),
 });
-/** 孩子从首页哪个按钮进来的:home = 发布的 id(没发布过的缺省首页是 null),button = 老师卡上文件里的第几个按钮,或应用加的 new / recent */
+/** 孩子从首页哪个按钮进来的:home = 发布的 id(没发布过的缺省首页是 null),button = 老师卡上文件里的第几个按钮,或应用加的 new / recent,或常驻的方砖(HOME_TILES 的 id) */
 export const HomeViaSchema = z.object({
     home: z.string().regex(HOME_ID_RE).nullable(),
-    button: z.union([z.number().int().nonnegative(), z.enum(['new', 'recent'])]),
+    button: z.union([z.number().int().nonnegative(), z.enum(['new', 'recent', ...HOME_TILE_IDS])]),
 });
+/** 这一下发出去的字是按钮上的字、不是孩子说的(家长排的按钮、方砖);新话题、接着刚才的不算 */
+export function viaSendsLabel(via) {
+    return typeof via.button === 'number' || HOME_TILE_IDS.includes(via.button);
+}
 /** 消息里记的 via:再带上按钮上的字(发布的首页以后会换,记下来 home show 才说得清) */
 export const MessageViaSchema = HomeViaSchema.extend({ label: z.string() });

package/dist/schema/workspace.d.ts

@@ -2,6 +2,7 @@
  * 一个孩子的 workspace 解析好的样子(app/workspace.ts 的 loadWorkspace 给;从那边挪来,2026-10-29):根、从哪认出来的、cotutor.json、各角色的绝对路径、几个目录。
  * 类型放在 schema:运行层、记忆、场景都按它取自己要的那几样,不用去引命令行那一层。
  */
+import { z } from 'zod';
 import type { CotutorConfig, PathRole } from './config.ts';
 /**
  * 技能目录,相对 workspace 根(2026-10-30 从 .claude/skills 挪来):Codex、Qwen Code 在 workspace 里对话时直接读它;
@@ -12,10 +13,36 @@ export declare const SKILLS_DIR = ".agents/skills";
 export declare function tutorFilePath(agentsDir: string, name: string): string;
 /** workspace 是怎么找到的:--workspace / COTUTOR_WORKSPACE / cwd 祖先 / ~/.config/cotutor/config.json / ~/cotutor/ 唯一目录 */
 export type RootSource = 'flag' | 'env' | 'cwd' | 'user-config' | 'home-single';
+/**
+ * sandbox(2026-11-04):手动试功能用的 workspace,从真的那个分出来;对话、照片、vault 的写入都留在它里面,不进孩子的记录。
+ * 命令加 --sandbox 就换到它(src/app/cli/sandbox.ts),下游照常当一个 workspace 用。
+ * 位置:真 workspace 旁边的 .sandbox/<目录名>/(~/cotutor/ray → ~/cotutor/.sandbox/ray);点开头,「~/cotutor 下唯一目录」的兜底看不见它。
+ * 分的时候根下照拷,只跳过孩子的状态(SANDBOX_SKIP;.cotutor/ 只拷 SANDBOX_KEEP_MACHINE);vault 在 workspace 外面就整份拷到 sandbox 的 vault/。
+ * cotutor.json 改几处:标题前加「试用 · 」(孩子端、家长端、扫码页都看得出)、端口 +1(和真的并排开)、paths 指进 sandbox、自动记账关掉(试出来的话题不值得花钱记)。
+ * 标记 .cotutor/sandbox.json 最后写:有它才算分完;--fresh 只删带这个标记的目录。
+ */
+export declare const SANDBOX_DIR = ".sandbox";
+export declare const SANDBOX_MARK = ".cotutor/sandbox.json";
+/** 标题前缀:「试用 · Ray的老师们」 */
+export declare const SANDBOX_TITLE = "\u8BD5\u7528";
+/** 外面的 vault 拷进 sandbox 后的目录名(相对 sandbox 根) */
+export declare const SANDBOX_VAULT = "vault";
+/** workspace 根下是孩子的状态、不拷进 sandbox 的;其余都算设置,照拷(拷多了无妨,拷少了试的就不像真的) */
+export declare const SANDBOX_SKIP: readonly string[];
+/** .cotutor/ 里照拷的;其余是缓存、设备表、孩子端流水 */
+export declare const SANDBOX_KEEP_MACHINE: readonly string[];
+export declare const SandboxMarkSchema: z.ZodObject<{
+    from: z.ZodString;
+    vault: z.ZodString;
+    forkedAt: z.ZodString;
+}, z.core.$strip>;
+export type SandboxMark = z.infer<typeof SandboxMarkSchema>;
 export interface Workspace {
     root: string;
     source: RootSource;
     config: CotutorConfig;
+    /** 这是个 sandbox(根下有 .cotutor/sandbox.json)就有,记着从哪分出来的 */
+    sandbox?: SandboxMark;
     /** 角色 → 绝对路径;vault 侧角色相对 vault 解析,没配 vault 就相对 workspace 根;captures 相对 workspace 根 */
     paths: Record<PathRole, string> & Record<string, string>;
     dirs: {

package/dist/schema/workspace.js

@@ -1,3 +1,8 @@
+/**
+ * 一个孩子的 workspace 解析好的样子(app/workspace.ts 的 loadWorkspace 给;从那边挪来,2026-10-29):根、从哪认出来的、cotutor.json、各角色的绝对路径、几个目录。
+ * 类型放在 schema:运行层、记忆、场景都按它取自己要的那几样,不用去引命令行那一层。
+ */
+import { z } from 'zod';
 /**
  * 技能目录,相对 workspace 根(2026-10-30 从 .claude/skills 挪来):Codex、Qwen Code 在 workspace 里对话时直接读它;
  * Claude Code 只认 .claude/skills,那里是一条指过来的相对链(init / upgrade 建)
@@ -7,3 +12,26 @@ export const SKILLS_DIR = '.agents/skills';
 export function tutorFilePath(agentsDir, name) {
     return `${agentsDir}/${name}.md`;
 }
+/**
+ * sandbox(2026-11-04):手动试功能用的 workspace,从真的那个分出来;对话、照片、vault 的写入都留在它里面,不进孩子的记录。
+ * 命令加 --sandbox 就换到它(src/app/cli/sandbox.ts),下游照常当一个 workspace 用。
+ * 位置:真 workspace 旁边的 .sandbox/<目录名>/(~/cotutor/ray → ~/cotutor/.sandbox/ray);点开头,「~/cotutor 下唯一目录」的兜底看不见它。
+ * 分的时候根下照拷,只跳过孩子的状态(SANDBOX_SKIP;.cotutor/ 只拷 SANDBOX_KEEP_MACHINE);vault 在 workspace 外面就整份拷到 sandbox 的 vault/。
+ * cotutor.json 改几处:标题前加「试用 · 」(孩子端、家长端、扫码页都看得出)、端口 +1(和真的并排开)、paths 指进 sandbox、自动记账关掉(试出来的话题不值得花钱记)。
+ * 标记 .cotutor/sandbox.json 最后写:有它才算分完;--fresh 只删带这个标记的目录。
+ */
+export const SANDBOX_DIR = '.sandbox';
+export const SANDBOX_MARK = '.cotutor/sandbox.json';
+/** 标题前缀:「试用 · Ray的老师们」 */
+export const SANDBOX_TITLE = '试用';
+/** 外面的 vault 拷进 sandbox 后的目录名(相对 sandbox 根) */
+export const SANDBOX_VAULT = 'vault';
+/** workspace 根下是孩子的状态、不拷进 sandbox 的;其余都算设置,照拷(拷多了无妨,拷少了试的就不像真的) */
+export const SANDBOX_SKIP = ['conversations', 'ledger', 'captures', 'talk', 'dictation', 'evals', 'snaps', '.cotutor', '.git', 'node_modules', '.DS_Store'];
+/** .cotutor/ 里照拷的;其余是缓存、设备表、孩子端流水 */
+export const SANDBOX_KEEP_MACHINE = ['shipped.json', 'cotutor.schema.json'];
+export const SandboxMarkSchema = z.object({
+    from: z.string().min(1).describe('从哪个 workspace 分出来的(绝对路径)'),
+    vault: z.string().min(1).describe('分的时候拷的是哪个 vault(绝对路径)'),
+    forkedAt: z.string().min(1).describe('什么时候分的(ISO)'),
+});

package/dist/shared/default-port.d.ts

@@ -0,0 +1,2 @@
+/** cotutor.json 没写端口时用的,只给旧配置:改了它们的地址就变了,平板要重新扫码。新 workspace 的端口 init 选好写进文件(src/app/cli/port.ts) */
+export declare const DEFAULT_PORT = 5180;

package/dist/shared/default-port.js

@@ -0,0 +1,2 @@
+/** cotutor.json 没写端口时用的,只给旧配置:改了它们的地址就变了,平板要重新扫码。新 workspace 的端口 init 选好写进文件(src/app/cli/port.ts) */
+export const DEFAULT_PORT = 5180;

package/dist/shared/qianwen.d.ts

@@ -1,6 +1,5 @@
 export declare const TOKEN_PLAN_HOST = "token-plan.maas.qianwenaiapi.com";
 export declare const DASHSCOPE_HOST = "dashscope.aliyuncs.com";
-export declare const TOKEN_PLAN_KEY_ENV = "QWENCLOUD_TOKEN_PLAN_API_KEY";
 /**
  * Token Plan 个人版调得通的模型(2026-10-13:文档表、token-plan 的 /models、实测三处对过)。
  * 没有 omni 系列、qwen-image-2.0、qwen-plus
@@ -13,24 +12,20 @@ export interface QianwenKeys {
     /** 百炼按量的 key */
     payg: string | null;
 }
-/** 本机 qwen 配好的百炼 key(~/.qwen/settings.json 的 env);读不到就是 null */
-export declare function localDashscopeKey(home?: string): string | null;
-/** voxtell 的配置(~/.config/voxtell/config.json):按量 key 与业务空间 id */
-export declare function voxtellConfig(home?: string): {
-    apiKey: string | null;
-    workspaceId: string | null;
-};
 /** 家长端配的百炼(机器级,几个孩子的 workspace 共用;写在 src/app/machine/bailian.ts):按量 key 与业务空间 id */
 export declare const bailianFile: (home?: string) => string;
 export declare function cotutorBailian(home?: string): {
     apiKey: string | null;
     workspaceId: string | null;
 };
-/** 百炼的业务空间 id(按量的 realtime、配音走它的域名):先看家长端配的,再看环境,再看 voxtell 的配置 */
+/** 开发机的 Token Plan:{"apiKey": "sk-sp-…"},手写;家长端存 bailian.json 是整份重写,所以不和它放一起 */
+export declare const tokenPlanFile: (home?: string) => string;
+export declare const tokenPlanKey: (home?: string) => string | null;
+/** 百炼的业务空间 id(按量的 realtime、配音走它的域名) */
 export declare function bailianWorkspaceId(env?: NodeJS.ProcessEnv): string | null;
 /** 业务空间的域名(北京地域);公网域名连 realtime 1 秒就断、配音不认 */
 export declare const workspaceHost: (workspaceId: string) => string;
-/** 本机的两把 key:先看家长端配的,再看环境,再看 qwen、voxtell 的配置;哪处放错了套(按量的位置放了 `sk-sp-`)就挪到对的那格 */
+/** 本机的两把 key(env 只取 HOME,测试拿它指别的家);放错了套(bailian.json 里放了 `sk-sp-`)就挪到对的那格 */
 export declare function qianwenKeys(env?: NodeJS.ProcessEnv): QianwenKeys;
 export interface QianwenLine {
     /** 域名(不带协议):https 与 wss 都是它 */
@@ -44,6 +39,15 @@ export declare function qianwenLine(model: string, keys: QianwenKeys): QianwenLi
 /** 几种接口的地址 */
 export declare const chatUrl: (host: string) => string;
 export declare const compatibleBase: (host: string) => string;
+/**
+ * 兼容接口(老师的脑,src/brain/api.ts)这个模型发到哪:Token Plan 有它、本机有 token-plan.json 就走 Token Plan(2026-11-02 起,同配音、画图);
+ * 否则百炼按量,知道业务空间 id 走它的域名,不知道走公网域名
+ */
+export declare function compatibleLine(model: string, env?: NodeJS.ProcessEnv): {
+    baseURL: string;
+    key: string;
+    plan: boolean;
+} | null;
 export declare const imageUrl: (host: string) => string;
 export declare const ttsUrl: (host: string) => string;
 /** 兼容接口的流(data: {...} 一行一块):拼出 delta.content;流里报错 → null */

package/dist/shared/qianwen.js

@@ -2,16 +2,15 @@
  * 千问的两套账:千问 AI 平台的 Token Plan(`sk-sp-`,只认 token-plan 域名,按订阅 Credits 抵)
  * 与百炼按量(`sk-` / `sk-ws-`,dashscope 域名)。两把 key 互不通用。
  * 一条线调哪个模型:Token Plan 有这个模型、本机又有它的 key 就走 Token Plan,否则走按量(2026-10-13 定)。key 只进请求头与子进程环境。
- * - Token Plan 的 key:环境变量 QWENCLOUD_TOKEN_PLAN_API_KEY(Qwen Code 官方页用的名字);DASHSCOPE_API_KEY 里放的是 `sk-sp-` 也认作它。
- * - 按量的 key:先看家长在家长端配的(~/.config/cotutor/bailian.json),再看 DASHSCOPE_API_KEY(不是 `sk-sp-` 时),
- *   再看本机 qwen(~/.qwen/settings.json 的 env)、voxtell(~/.config/voxtell/config.json)的配置。
+ * key 只放机器级的 ~/.config/cotutor/(2026-11-02 起,所有命令读同一处;环境变量、本机 qwen、voxtell 的配置都不看):
+ * - bailian.json:百炼按量 key + 业务空间 id,家长端「首页」写(src/app/machine/bailian.ts),每台都要有;
+ * - token-plan.json:Token Plan 的 key,只有开发机有,手写;文件在就是开关。
  */
 import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 export const TOKEN_PLAN_HOST = 'token-plan.maas.qianwenaiapi.com';
 export const DASHSCOPE_HOST = 'dashscope.aliyuncs.com';
-export const TOKEN_PLAN_KEY_ENV = 'QWENCLOUD_TOKEN_PLAN_API_KEY';
 /**
  * Token Plan 个人版调得通的模型(2026-10-13:文档表、token-plan 的 /models、实测三处对过)。
  * 没有 omni 系列、qwen-image-2.0、qwen-plus
@@ -40,37 +39,29 @@ function readJson(file) {
     }
 }
 const text = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null);
-/** 本机 qwen 配好的百炼 key(~/.qwen/settings.json 的 env);读不到就是 null */
-export function localDashscopeKey(home = homedir()) {
-    const env = readJson(join(home, '.qwen', 'settings.json'))?.env;
-    return env && typeof env === 'object' ? text(env.DASHSCOPE_API_KEY) : null;
-}
-/** voxtell 的配置(~/.config/voxtell/config.json):按量 key 与业务空间 id */
-export function voxtellConfig(home = homedir()) {
-    const v = readJson(join(home, '.config', 'voxtell', 'config.json'));
-    return { apiKey: text(v?.apiKey), workspaceId: text(v?.workspaceId) };
-}
 /** 家长端配的百炼(机器级,几个孩子的 workspace 共用;写在 src/app/machine/bailian.ts):按量 key 与业务空间 id */
 export const bailianFile = (home = homedir()) => join(home, '.config', 'cotutor', 'bailian.json');
 export function cotutorBailian(home = homedir()) {
     const v = readJson(bailianFile(home));
     return { apiKey: text(v?.apiKey), workspaceId: text(v?.workspaceId) };
 }
-/** 百炼的业务空间 id(按量的 realtime、配音走它的域名):先看家长端配的,再看环境,再看 voxtell 的配置 */
+/** 开发机的 Token Plan:{"apiKey": "sk-sp-…"},手写;家长端存 bailian.json 是整份重写,所以不和它放一起 */
+export const tokenPlanFile = (home = homedir()) => join(home, '.config', 'cotutor', 'token-plan.json');
+export const tokenPlanKey = (home = homedir()) => text(readJson(tokenPlanFile(home))?.apiKey);
+/** 百炼的业务空间 id(按量的 realtime、配音走它的域名) */
 export function bailianWorkspaceId(env = process.env) {
-    const home = env.HOME || homedir();
-    return cotutorBailian(home).workspaceId || text(env.DASHSCOPE_WORKSPACE_ID) || voxtellConfig(home).workspaceId;
+    return cotutorBailian(env.HOME || homedir()).workspaceId;
 }
 /** 业务空间的域名(北京地域);公网域名连 realtime 1 秒就断、配音不认 */
 export const workspaceHost = (workspaceId) => `${workspaceId}.cn-beijing.maas.aliyuncs.com`;
-/** 本机的两把 key:先看家长端配的,再看环境,再看 qwen、voxtell 的配置;哪处放错了套(按量的位置放了 `sk-sp-`)就挪到对的那格 */
+/** 本机的两把 key(env 只取 HOME,测试拿它指别的家);放错了套(bailian.json 里放了 `sk-sp-`)就挪到对的那格 */
 export function qianwenKeys(env = process.env) {
     const home = env.HOME || homedir();
-    const named = text(env[TOKEN_PLAN_KEY_ENV]);
-    const candidates = [cotutorBailian(home).apiKey, text(env.DASHSCOPE_API_KEY), localDashscopeKey(home), voxtellConfig(home).apiKey];
+    const plan = tokenPlanKey(home);
+    const payg = cotutorBailian(home).apiKey;
     return {
-        plan: named ?? candidates.find((k) => k && isPlanKey(k)) ?? null,
-        payg: candidates.find((k) => k && !isPlanKey(k)) ?? null,
+        plan: plan && isPlanKey(plan) ? plan : payg && isPlanKey(payg) ? payg : null,
+        payg: payg && !isPlanKey(payg) ? payg : null,
     };
 }
 /** 这个模型走哪条线;两把 key 都用不上 → null */
@@ -84,6 +75,19 @@ export function qianwenLine(model, keys) {
 /** 几种接口的地址 */
 export const chatUrl = (host) => `https://${host}/compatible-mode/v1/chat/completions`;
 export const compatibleBase = (host) => `https://${host}/compatible-mode/v1`;
+/**
+ * 兼容接口(老师的脑,src/brain/api.ts)这个模型发到哪:Token Plan 有它、本机有 token-plan.json 就走 Token Plan(2026-11-02 起,同配音、画图);
+ * 否则百炼按量,知道业务空间 id 走它的域名,不知道走公网域名
+ */
+export function compatibleLine(model, env = process.env) {
+    const line = qianwenLine(model, qianwenKeys(env));
+    if (!line)
+        return null;
+    if (line.plan)
+        return { baseURL: compatibleBase(line.host), key: line.key, plan: true };
+    const ws = bailianWorkspaceId(env);
+    return { baseURL: compatibleBase(ws ? workspaceHost(ws) : line.host), key: line.key, plan: false };
+}
 export const imageUrl = (host) => `https://${host}/api/v1/services/aigc/multimodal-generation/generation`;
 export const ttsUrl = (host) => `https://${host}/api/v1/services/audio/tts/SpeechSynthesizer`;
 /** 兼容接口的流(data: {...} 一行一块):拼出 delta.content;流里报错 → null */

package/dist/shared/site-url.d.ts

@@ -0,0 +1,2 @@
+/** 地址:默认端口不写(https 的 443、http 的 80)。不用 new URL:它会把主机名压成小写 */
+export declare function siteUrl(scheme: 'http' | 'https', host: string, port: number, path?: string): string;

package/dist/shared/site-url.js

@@ -0,0 +1,5 @@
+/** 地址:默认端口不写(https 的 443、http 的 80)。不用 new URL:它会把主机名压成小写 */
+export function siteUrl(scheme, host, port, path = '/') {
+    const isDefault = (scheme === 'https' && port === 443) || (scheme === 'http' && port === 80);
+    return `${scheme}://${host}${isDefault ? '' : `:${port}`}${path}`;
+}

package/dist/shared/upgrade.d.ts

@@ -0,0 +1,9 @@
+/** 版本比较与升级步骤:服务、托盘(轻入口,不带 zod)、家长端、doctor 共用 */
+/** 升级程序的三步。分开写不用 &&:Windows 默认的 PowerShell 5.1 不认 &&;顺序是先换文件再重起,新代码不会读到旧文件;restart 顺手把图标也换上新代码 */
+export declare const UPGRADE_STEPS: readonly ["npm i -g cotutor", "cotutor upgrade", "cotutor service restart"];
+/** 给家长看的那份。Windows 上带 .cmd:PowerShell 缺省禁止跑脚本,不带后缀找到的是被拦的 .ps1,第一条就报错;.cmd 在 PowerShell 和 cmd.exe 里都能跑(2026-11-07 真机) */
+export declare function upgradeSteps(platform?: NodeJS.Platform): string[];
+/** 正式版的版本号。预发布不算;从网上拿来的还要显示给家长,其余一律不认 */
+export declare function isPlainVersion(v: unknown): v is string;
+/** a 比 b 新;任一边不是正式版的版本号 → false,宁可不提醒 */
+export declare function isNewer(a: unknown, b: unknown): boolean;

package/dist/shared/upgrade.js

@@ -0,0 +1,23 @@
+/** 版本比较与升级步骤:服务、托盘(轻入口,不带 zod)、家长端、doctor 共用 */
+/** 升级程序的三步。分开写不用 &&:Windows 默认的 PowerShell 5.1 不认 &&;顺序是先换文件再重起,新代码不会读到旧文件;restart 顺手把图标也换上新代码 */
+export const UPGRADE_STEPS = ['npm i -g cotutor', 'cotutor upgrade', 'cotutor service restart'];
+/** 给家长看的那份。Windows 上带 .cmd:PowerShell 缺省禁止跑脚本,不带后缀找到的是被拦的 .ps1,第一条就报错;.cmd 在 PowerShell 和 cmd.exe 里都能跑(2026-11-07 真机) */
+export function upgradeSteps(platform = process.platform) {
+    return UPGRADE_STEPS.map((s) => (platform === 'win32' ? s.replace(' ', '.cmd ') : s));
+}
+const PLAIN = /^(\d+)\.(\d+)\.(\d+)$/;
+/** 正式版的版本号。预发布不算;从网上拿来的还要显示给家长,其余一律不认 */
+export function isPlainVersion(v) {
+    return typeof v === 'string' && v.length <= 32 && PLAIN.test(v);
+}
+/** a 比 b 新;任一边不是正式版的版本号 → false,宁可不提醒 */
+export function isNewer(a, b) {
+    if (!isPlainVersion(a) || !isPlainVersion(b))
+        return false;
+    const x = a.split('.').map(Number);
+    const y = b.split('.').map(Number);
+    for (let i = 0; i < 3; i++)
+        if (x[i] !== y[i])
+            return x[i] > y[i];
+    return false;
+}