cotutor 0.1.0 → 0.2.0

package/dist/cli/serve.js

@@ -1,22 +1,56 @@
 /**
  * cotutor serve:一 workspace 一进程(2026-09-08 拍板),端口读 cotutor.json(--port 覆盖)。
  * 启动打印解析结果与体检警告(配置坏了直接不起,骨架缺失只警告)。
+ * HTTPS(iPad 上录音要):server.https 指了证书就用它(单个 workspace 的例外);没指就看机器级 ~/.config/cotutor/certs/(cotutor cert 用 mkcert 建);都没有走 HTTP。
  */
-import { createServer } from 'node:http';
-import { hostname } from 'node:os';
+import { readFileSync } from 'node:fs';
+import { createServer as createHttp } from 'node:http';
+import { createServer as createHttps } from 'node:https';
+import { hostname, networkInterfaces } from 'node:os';
+import { join } from 'node:path';
 import { doctorWorkspace } from "./doctor.js";
-import { createHandler } from "../server/app.js";
-import { loadWorkspace } from "./workspace.js";
+import { createContext, createHandler } from "../server/app.js";
+import { USER_CERT_DIR, expandPath, loadWorkspace } from "./workspace.js";
+/** 证书路径:cotutor.json 的 server.https 优先(相对 workspace 根),否则机器级 ~/.config/cotutor/certs/;都没有 → null */
+export function httpsFiles(ws) {
+    const h = ws.config.server.https;
+    if (h)
+        return { cert: expandPath(h.cert, ws.root), key: expandPath(h.key, ws.root) };
+    const cert = join(USER_CERT_DIR, 'cert.pem');
+    const key = join(USER_CERT_DIR, 'key.pem');
+    try {
+        readFileSync(cert);
+        readFileSync(key);
+        return { cert, key };
+    }
+    catch {
+        return null;
+    }
+}
+/** 局域网 IPv4(iPad 用它访问;.local 名不一定解析得到) */
+export function lanAddresses() {
+    const out = [];
+    for (const list of Object.values(networkInterfaces()))
+        for (const i of list ?? [])
+            if (i.family === 'IPv4' && !i.internal)
+                out.push(i.address);
+    return out;
+}
 export async function serveWorkspace(opts = {}) {
     const ws = loadWorkspace(opts.workspace, opts);
     const report = await doctorWorkspace(ws.root, { ...opts, probeEnv: false });
     const warnings = report.checks.filter((c) => !c.ok).map((c) => `${c.name}:${c.detail}${c.fix ? `(${c.fix})` : ''}`);
     const port = opts.port ?? ws.config.server.port;
-    const server = createServer(createHandler(ws));
+    const ctx = createContext(ws);
+    const handler = createHandler(ctx);
+    const tls = opts.http ? null : httpsFiles(ws);
+    const server = tls ? createHttps({ cert: readFileSync(tls.cert), key: readFileSync(tls.key) }, handler) : createHttp(handler);
     await new Promise((resolveListen, reject) => {
         server.once('error', reject);
         server.listen(port, opts.host ?? '0.0.0.0', () => resolveListen());
     });
     const actual = server.address().port;
-    return { server, ws, port: actual, url: `http://${hostname()}:${actual}/`, warnings };
+    const scheme = tls ? 'https' : 'http';
+    const urls = [hostname(), ...lanAddresses()].map((h) => `${scheme}://${h}:${actual}/`);
+    return { server, ctx, ws, port: actual, https: Boolean(tls), urls, url: urls[0], warnings };
 }

package/dist/cli/skeleton.d.ts

@@ -1,21 +1,39 @@
-export declare const DIRS: readonly ["agents", "ledger", "conversations", ".claude/agents", ".qwen/agents"];
+export declare const DIRS: readonly ["agents", "ledger", "conversations", ".claude/agents", ".qwen/agents", "scenes", "bundles", "snaps"];
 export declare const LEDGER_FILES: readonly ["ledger/observations.jsonl", "ledger/artifacts.jsonl"];
-/** 本包自带的老师定义目录(仓库检出与 npm 安装都在包根 agents/) */
+/** 本包自带的老师文件目录(仓库检出与 npm 安装都在包根 agents/) */
 export declare const PACKAGE_AGENTS_DIR: string;
+/** 本包版本(出厂件的 hash 记录带它,升级时知道基于哪版) */
+export declare const PACKAGE_VERSION: string;
 export interface ShippedAgent {
     name: string;
     file: string;
     description: string;
 }
 export declare function shippedAgents(dir?: string): Promise<ShippedAgent[]>;
-export declare const GITIGNORE = "# \u8F6C\u5F55\u65E5\u5FD7\u4F53\u79EF\u5927\u3001\u53EF\u4ECE\u4F1A\u8BDD\u7D22\u5F15\u91CD\u5EFA\u5173\u952E\u4FE1\u606F;\u8981\u7559\u5168\u6863\u5C31\u5220\u6389\u4E0B\u9762\u8FD9\u884C\nconversations/**/*.log\nnode_modules/\n.DS_Store\n";
+export declare const GITIGNORE = "# \u8F6C\u5F55\u65E5\u5FD7\u4F53\u79EF\u5927\u3001\u53EF\u4ECE\u5BF9\u8BDD\u7D22\u5F15\u91CD\u5EFA\u5173\u952E\u4FE1\u606F;\u8981\u7559\u5168\u6863\u5C31\u5220\u6389\u4E0B\u9762\u8FD9\u884C\nconversations/**/*.log\n# \u914D\u97F3\u53EF\u91CD\u65B0\u5408\u6210\nconversations/**/*.mp3\n# \u8BFE\u5305\u4E0E\u622A\u56FE\u662F drawtell build / snap \u7684\u6D3E\u751F\u7269,\u573A\u666F\u6E90\u5728 scenes/\nbundles/\nsnaps/\nnode_modules/\n.DS_Store\n";
 /** 家规:所有老师常驻(CLAUDE.md 与 QWEN.md 同一份)。故意短。 */
-export declare const RULES = "# \u5BB6\u89C4\n\n- \u5173\u4E8E\u5B69\u5B50\u7684\u89C2\u5BDF,\u5199\u4E00\u6761\u5230 ledger/observations.jsonl(\u4E00\u884C JSON:id\u3001date\u3001author=\u4F60\u7684\u540D\u5B57\u3001claim \u4E00\u53E5\u8BDD\u3001evidence \u6307\u5411\u4F1A\u8BDD\u6216\u4EA7\u7269),\u522B\u7684\u8001\u5E08\u548C\u89C4\u5212\u8001\u5E08\u4ECE\u90A3\u91CC\u8BFB\u3002\n- \u4F60\u81EA\u5DF1\u7684\u7ECF\u9A8C\u8BB0\u8FDB\u4F60\u7684\u8BB0\u5FC6\u76EE\u5F55(MEMORY.md \u4E00\u884C\u7D22\u5F15 + \u4E3B\u9898\u6587\u4EF6)\u3002\n- \u4F60\u8BF4\u7ED9\u5B69\u5B50\u542C\u7684\u8BDD\u653E\u5728\u56DE\u590D\u7684**\u6700\u540E\u4E00\u6BB5**,\u5B69\u5B50\u53EA\u770B\u5F97\u5230\u6700\u540E\u4E00\u6BB5;\u4E2D\u95F4\u7684\u8BDD\u548C\u5DE5\u5177\u8FC7\u7A0B\u53EA\u6709\u5BB6\u957F\u770B\u3002\n- \u9700\u8981\u5BB6\u957F\u62CD\u677F\u7684\u4E8B\u5199\u6210\u4E00\u6BB5\u300C## \u5F85\u88C1\u91CF\u300D(question: \u4E00\u53E5\u8BDD;options: \u5217\u8868),\u4E0D\u8981\u505C\u4E0B\u6765\u7B49\u3002\n- \u8981\u4EA4\u7ED9\u522B\u7684\u8001\u5E08\u7684\u4E8B\u5199\u6210\u4E00\u6BB5\u300C## \u8F6C\u4EA4\u300D(to: \u8001\u5E08\u540D;why: \u4E00\u53E5\u8BDD;refs: \u76F8\u5173\u6587\u4EF6),\u7B2C\u4E00\u671F\u53EA\u5141\u8BB8\u4E00\u8DF3\u3002\n- \u4F1A\u8BDD\u6309\u5929,\u660E\u5929\u4ECE\u8D26\u672C\u548C\u4F60\u7684\u8BB0\u5FC6\u63A5\u7740\u6765,\u4E0D\u8981\u6307\u671B\u4ECA\u5929\u7684\u5BF9\u8BDD\u8FD8\u5728\u3002\n";
+export declare const RULES = "# \u5BB6\u89C4\n\n- \u5173\u4E8E\u5B69\u5B50\u7684\u89C2\u5BDF,\u5199\u4E00\u6761\u5230 ledger/observations.jsonl(\u4E00\u884C JSON:id\u3001date\u3001author=\u4F60\u7684\u540D\u5B57\u3001claim \u4E00\u53E5\u8BDD\u3001evidence \u6307\u5411\u5BF9\u8BDD\u6216\u4EA7\u7269),\u522B\u7684\u8001\u5E08\u548C\u89C4\u5212\u8001\u5E08\u4ECE\u90A3\u91CC\u8BFB\u3002\n- \u4F60\u81EA\u5DF1\u7684\u7ECF\u9A8C\u8BB0\u8FDB\u4F60\u7684\u8BB0\u5FC6\u76EE\u5F55(MEMORY.md \u4E00\u884C\u7D22\u5F15 + \u4E3B\u9898\u6587\u4EF6)\u3002\n- \u56DE\u590D\u6B63\u6587\u5C31\u662F\u5B69\u5B50\u770B\u5230\u7684\u677F\u4E66:\u666E\u901A\u6BB5\u843D\u662F\u4F60\u8BF4\u7ED9\u5B69\u5B50\u542C\u7684\u8BDD(\u4E00\u884C\u4E00\u53E5,\u4F1A\u88AB\u5FF5\u51FA\u6765;\u65B9\u62EC\u53F7\u6807\u51FA\u8981\u5728\u677F\u4E0A\u6572\u7684\u8BCD;\u672B\u53E5\u662F\u95EE\u53E5\u5C31\u505C\u4E0B\u7B49\u5B69\u5B50),\u56F4\u680F\u662F\u677F\u4E0A\u7684\u5361(\u56F4\u680F\u6807\u7B7E\u662F\u5361\u7684\u79CD\u7C7B;\u5361\u7684\u5199\u6CD5\u5728\u8001\u5E08\u6587\u4EF6\u91CC)\u3002\u968F\u53E3\u95EE\u7B54\u5C31\u4E00\u4E24\u53E5\u8BDD,\u6CA1\u6709\u5361\u3002\u677F\u4E66\u5199\u5B8C\u5C31\u505C,\u4E0D\u518D\u8865\u8BDD\u3001\u4E0D\u518D\u7528\u5DE5\u5177\u2014\u2014\u5B69\u5B50\u770B\u5230\u7684\u53EA\u662F\u8FD9\u8F6E\u6700\u540E\u4E00\u6BB5\u8BDD\u3002\n- \u5BF9\u5BB6\u957F\u8BF4\u7684\u8BDD\u5199\u6210\u4E00\u6BB5\u300C## \u5BB6\u957F\u300D;\u9700\u8981\u5BB6\u957F\u62CD\u677F\u7684\u4E8B\u5199\u6210\u4E00\u6BB5\u300C## \u5F85\u88C1\u91CF\u300D(question: \u4E00\u53E5\u8BDD;options: \u5217\u8868),\u4E0D\u8981\u505C\u4E0B\u6765\u7B49;\u8981\u4EA4\u7ED9\u522B\u7684\u8001\u5E08\u7684\u4E8B\u5199\u6210\u4E00\u6BB5\u300C## \u8F6C\u4EA4\u300D(to: \u8001\u5E08\u540D;why: \u4E00\u53E5\u8BDD;refs: \u76F8\u5173\u6587\u4EF6),\u7B2C\u4E00\u671F\u53EA\u5141\u8BB8\u4E00\u8DF3;**\u8F6C\u4EA4\u53EA\u5199\u8FD9\u4E2A\u6BB5,\u4E0D\u8981\u81EA\u5DF1\u7528 Task / \u5B50\u4EE3\u7406\u53BB\u53EB\u90A3\u4F4D\u8001\u5E08**\u2014\u2014\u5E94\u7528\u770B\u5230\u6BB5\u4F1A\u81EA\u52A8\u8D77\u5979\u7684\u4E00\u8F6E\u3002\u8FD9\u4E09\u4E2A\u6BB5\u653E\u5728\u6B63\u6587\u672B\u5C3E,\u5B69\u5B50\u770B\u4E0D\u5230\u3002\n- \u5BF9\u8BDD\u6309\u5929,\u660E\u5929\u4ECE\u8D26\u672C\u548C\u4F60\u7684\u8BB0\u5FC6\u63A5\u7740\u6765,\u4E0D\u8981\u6307\u671B\u4ECA\u5929\u7684\u5BF9\u8BDD\u8FD8\u5728\u3002\n";
+export interface TutorTemplateInput {
+    name: string;
+    display: string;
+    subject?: string;
+    description?: string;
+}
+/**
+ * 家长自己加老师时的文件模板:与出厂老师同一套约定(cwd、账本、家规、上下文包、问答 / 讲解 / 任务三种回复、
+ * 板书写法、不评判、不造课件、家长 / 待裁量 / 转交段),只有第一句人设是这位老师自己的。
+ */
+export declare function tutorTemplate(t: TutorTemplateInput): string;
 export interface ConfigTemplateInput {
     slug: string;
     name?: string;
     port?: number;
-    teachers: ShippedAgent[];
+    tutors: ShippedAgent[];
 }
 /** cotutor.json 模板:只在文件不存在时写入;政策文件永不自动重建或覆盖(家长的决定不由机器替她拍板)。 */
 export declare function configTemplate(input: ConfigTemplateInput): string;
+/** 把 JSON Schema 写进 workspace(机器文件,每次 init / upgrade 都刷新) */
+/** 给老师看的板书语法表:从卡的注册表现生成,机器文件,init / upgrade 每次刷新;老师文件正文让老师讲解前读它 */
+export declare const SYNTAX_FILE = ".cotutor/\u677F\u4E66\u8BED\u6CD5.md";
+export declare function writeSyntaxFile(root: string): Promise<string>;
+export declare function writeSchemaFile(root: string): Promise<string>;

package/dist/cli/skeleton.js

@@ -1,17 +1,23 @@
 /**
- * 工作区骨架清单:init 建、doctor 查,同一张清单(两边各写一遍必然漂移)。
+ * workspace骨架清单:init 建、doctor 查,同一张清单(两边各写一遍必然漂移)。
  * 布局见《cotutor-agent层设计.md》§2:
- *   cotutor.json / CLAUDE.md QWEN.md(家规)/ .claude/agents .qwen/agents(老师定义链自本包 agents/)
- *   agents/<name>/(老师的家 = 会话 cwd)/ ledger/(两本账)/ conversations/(会话索引与转录)
+ *   cotutor.json / CLAUDE.md QWEN.md(家规)/ .claude/agents(老师文件,拷自本包 agents/,是家长的)/ .qwen/agents(相对链)/ .cotutor/shipped.json(出厂 hash)
+ *   agents/<name>/(老师的家 = 会话 cwd)/ ledger/(两本账)/ conversations/(对话索引与转录)
  */
+import { readFileSync } from 'node:fs';
 import { readFile, readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseAgentFile } from "../lib/agent-file.js";
-export const DIRS = ['agents', 'ledger', 'conversations', '.claude/agents', '.qwen/agents'];
+import { CONFIG_SCHEMA_FILE, TTS_DEFAULT, cotutorJsonSchema } from "../schema/index.js";
+import { boardSyntaxDoc } from "../cards/index.js";
+import { mkdir, writeFile } from 'node:fs/promises';
+export const DIRS = ['agents', 'ledger', 'conversations', '.claude/agents', '.qwen/agents', 'scenes', 'bundles', 'snaps'];
 export const LEDGER_FILES = ['ledger/observations.jsonl', 'ledger/artifacts.jsonl'];
-/** 本包自带的老师定义目录(仓库检出与 npm 安装都在包根 agents/) */
+/** 本包自带的老师文件目录(仓库检出与 npm 安装都在包根 agents/) */
 export const PACKAGE_AGENTS_DIR = fileURLToPath(new URL('../../agents/', import.meta.url));
+/** 本包版本(出厂件的 hash 记录带它,升级时知道基于哪版) */
+export const PACKAGE_VERSION = JSON.parse(readFileSync(fileURLToPath(new URL('../../package.json', import.meta.url)), 'utf8')).version;
 export async function shippedAgents(dir = PACKAGE_AGENTS_DIR) {
     const out = [];
     for (const f of (await readdir(dir)).filter((f) => f.endsWith('.md')).sort()) {
@@ -22,61 +28,157 @@ export async function shippedAgents(dir = PACKAGE_AGENTS_DIR) {
     }
     return out;
 }
-export const GITIGNORE = `# 转录日志体积大、可从会话索引重建关键信息;要留全档就删掉下面这行
+export const GITIGNORE = `# 转录日志体积大、可从对话索引重建关键信息;要留全档就删掉下面这行
 conversations/**/*.log
+# 配音可重新合成
+conversations/**/*.mp3
+# 课包与截图是 drawtell build / snap 的派生物,场景源在 scenes/
+bundles/
+snaps/
 node_modules/
 .DS_Store
 `;
 /** 家规:所有老师常驻(CLAUDE.md 与 QWEN.md 同一份)。故意短。 */
 export const RULES = `# 家规
 
-- 关于孩子的观察,写一条到 ledger/observations.jsonl(一行 JSON:id、date、author=你的名字、claim 一句话、evidence 指向会话或产物),别的老师和规划老师从那里读。
+- 关于孩子的观察,写一条到 ledger/observations.jsonl(一行 JSON:id、date、author=你的名字、claim 一句话、evidence 指向对话或产物),别的老师和规划老师从那里读。
 - 你自己的经验记进你的记忆目录(MEMORY.md 一行索引 + 主题文件)。
-- 你说给孩子听的话放在回复的**最后一段**,孩子只看得到最后一段;中间的话和工具过程只有家长看。
-- 需要家长拍板的事写成一段「## 待裁量」(question: 一句话;options: 列表),不要停下来等。
-- 要交给别的老师的事写成一段「## 转交」(to: 老师名;why: 一句话;refs: 相关文件),第一期只允许一跳。
-- 会话按天,明天从账本和你的记忆接着来,不要指望今天的对话还在。
+- 回复正文就是孩子看到的板书:普通段落是你说给孩子听的话(一行一句,会被念出来;方括号标出要在板上敲的词;末句是问句就停下等孩子),围栏是板上的卡(围栏标签是卡的种类;卡的写法在老师文件里)。随口问答就一两句话,没有卡。板书写完就停,不再补话、不再用工具——孩子看到的只是这轮最后一段话。
+- 对家长说的话写成一段「## 家长」;需要家长拍板的事写成一段「## 待裁量」(question: 一句话;options: 列表),不要停下来等;要交给别的老师的事写成一段「## 转交」(to: 老师名;why: 一句话;refs: 相关文件),第一期只允许一跳;**转交只写这个段,不要自己用 Task / 子代理去叫那位老师**——应用看到段会自动起她的一轮。这三个段放在正文末尾,孩子看不到。
+- 对话按天,明天从账本和你的记忆接着来,不要指望今天的对话还在。
 `;
-const TEACHER_PRESETS = {
-    'math-teacher': { display: '数学老师', subject: '数学', avatar: '🧮' },
-    'chinese-teacher': { display: '语文老师', subject: '语文', avatar: '📚' },
-    'reading-teacher': { display: '朗读老师', subject: '英语', avatar: '📖' },
-    'homework-aide': { display: '作业助教', avatar: '📷' },
+/**
+ * 家长自己加老师时的文件模板:与出厂老师同一套约定(cwd、账本、家规、上下文包、问答 / 讲解 / 任务三种回复、
+ * 板书写法、不评判、不造课件、家长 / 待裁量 / 转交段),只有第一句人设是这位老师自己的。
+ */
+export function tutorTemplate(t) {
+    const what = t.subject ? `${t.subject}的事` : '孩子问的事';
+    return `---
+name: ${t.name}
+description: ${t.description ?? `${t.display}。${what}都找它;随口问的一两句答完,要讲的在板书上一节一节讲`}
+maxTurns: 40
+permissionMode: bypassPermissions
+memory: project
+---
+你是这个家的${t.display},面对的是一个小学生和他的家长。cwd 是你的家(agents/${t.name}/),账本在 ../../ledger/,家规在 ../../CLAUDE.md。消息前面有一段 \`cotutor:\` 开头的上下文包(谁在说、几点、正在看什么、本周计划、最近观察),先看它再答。
+
+(在这里写这位老师自己的性子和讲法:比如「说话慢一点,爱打比方」「英文后面跟中文」。一两句就够。)
+
+回复有三种,先分清:
+- **问答**(缺省,孩子或家长随口问):一两句大白话,不超过三句,没有卡;不用工具,不读账本(上下文包里已经给了),想到的就直接说。
+- **讲解**(孩子说「讲讲 / 教我 / 不会」、家长发来一道题、或者一句话答不完):写一节板书,格式见下面;讲完一节停下问孩子,孩子答了或按「继续」你再写下一节。
+- **任务**(上下文包里 \`from: system\`,或家长明确写了「记账 / 做计划」):按任务做,做完在正文里报告结果。
+
+现在没有别的课件通道:**不要写文件、不要造课件**,板书就是你的课件。
+
+## 板书怎么写(讲解时)
+
+回复正文就是孩子看到的板书,只有两种东西:
+
+- **普通段落 = 你说的话。** 一行一句,每句会被念出来、显示在字幕行,所以不要写标题、列表、粗体、括号注释。句子里用方括号标出要在板上敲的词,那个词要在某张卡上出现。末句写成问句就停下等孩子。
+- **围栏 = 板上的卡。** 围栏的语言标签是卡的种类,正文按各种卡的写法。卡写在讲它的那句话前面,卡与话交错。
+- **板书写完就停。** 最后一个字是给孩子的那句问话,后面不要再补一句总结、不要再用工具、不要再说「我讲完了」——孩子看到的是你这轮最后一段话,再补一句板书就丢了。
+
+卡有哪几种、各自怎么写,在 ../../.cotutor/板书语法.md(text / read / choice / fill / image…);第一次讲解前读一遍,之后不用再读。上下文包里 \`board: off\` 时只说话不出卡。
+
+一节 4–8 张卡、6–12 句话;一次只讲一个想法,讲完就问。孩子的话不上板;孩子答了,你的口头回应直接写成一句话。不打分、不说「错了」:答对了直接往下讲,答偏了就从他的答案往回讲一步。
+
+例子(一节的骨架):
+
+\`\`\`\`
+开场的一句话。
+
+\`\`\`text cover
+标题
+副标题
+\`\`\`
+
+讲这张卡的一句话,[要敲的词]在卡上。
+
+\`\`\`choice
+问题?
+- [ ] 选项一
+- [x] 选项二
+\`\`\`
+
+末句是问句?
+\`\`\`\`
+
+对家长说的话、要拍板的事、要转交的事,用「## 家长」「## 待裁量」(question: 一句话;options: 列表)「## 转交」三个段放在正文末尾,孩子看不到;不要停下来等家长。
+
+记账与记忆(只在任务里做,问答和讲解不做):值得别的老师知道的观察,追加一行到 ../../ledger/observations.jsonl;你自己的经验记进你的记忆目录。
+`;
+}
+const TUTOR_DEFAULTS = {
+    'math-tutor': { display: '数学老师', subject: '数学', avatar: '🧮' },
+    'chinese-tutor': { display: '语文老师', subject: '语文', avatar: '📚' },
+    'reading-tutor': { display: '朗读老师', subject: '英语', avatar: '📖' },
+    'homework-tutor': { display: '作业老师', avatar: '📷' },
     planner: { display: '规划老师', avatar: '🗓', hidden: true },
+    'scene-maker': { display: '画图老师', avatar: '🎨', hidden: true, runtime: 'claude-scene' },
 };
 /** cotutor.json 模板:只在文件不存在时写入;政策文件永不自动重建或覆盖(家长的决定不由机器替她拍板)。 */
 export function configTemplate(input) {
-    const teachers = {};
-    for (const a of input.teachers) {
-        const p = TEACHER_PRESETS[a.name];
-        teachers[a.name] = p
-            ? { display: p.display, ...(p.subject ? { subject: p.subject } : {}), avatar: p.avatar, enabled: true, ...(p.hidden ? { hidden: true } : {}) }
+    const tutors = {};
+    for (const a of input.tutors) {
+        const p = TUTOR_DEFAULTS[a.name];
+        tutors[a.name] = p
+            ? { display: p.display, ...(p.subject ? { subject: p.subject } : {}), avatar: p.avatar, enabled: true, ...(p.hidden ? { hidden: true } : {}), ...(p.runtime ? { runtime: p.runtime } : {}) }
             : { display: a.name, enabled: true };
     }
     const cfg = {
+        $schema: CONFIG_SCHEMA_FILE,
         version: 1,
-        title: input.name ? `${input.name}的书房` : 'cotutor',
+        title: input.name ? `${input.name}的老师们` : 'cotutor',
         kid: { slug: input.slug, ...(input.name ? { name: input.name } : {}) },
         server: { port: input.port ?? 5180 },
         paths: {},
         policyDefaults: {},
-        teachers,
-        agents: {
+        tutors,
+        runtimes: {
             default: 'claude',
+            // 普通老师不许派子代理(--disallowedTools Agent):claude 会把 .claude/agents/ 里的老师文件当可派的子代理,老师自己去叫 scene-maker 就把预算烧在自己这轮里;转交只写「## 转交」段
             claude: {
-                run: ['claude', '--agent', '{agent}', '-p', '{prompt}', '--dangerously-skip-permissions', '--output-format', 'stream-json', '--verbose', '--max-budget-usd', '2'],
-                resume: ['claude', '--agent', '{agent}', '-p', '--resume', '{session}', '{prompt}', '--dangerously-skip-permissions', '--output-format', 'stream-json', '--verbose', '--max-budget-usd', '2'],
+                run: ['claude', '--agent', '{agent}', '-p', '{prompt}', '--dangerously-skip-permissions', '--disallowedTools', 'Agent', '--output-format', 'stream-json', '--verbose', '--include-partial-messages', '--max-budget-usd', '2'],
+                resume: ['claude', '--agent', '{agent}', '-p', '--resume', '{session}', '{prompt}', '--dangerously-skip-permissions', '--disallowedTools', 'Agent', '--output-format', 'stream-json', '--verbose', '--include-partial-messages', '--max-budget-usd', '2'],
             },
             qwen: {
                 run: ['qwen', '-p', '{prompt}', '--append-system-prompt', '{agentBody}', '--yolo', '--output-format', 'stream-json', '--max-wall-time', '10m'],
                 resume: ['qwen', '-p', '{prompt}', '--resume', '{session}', '--append-system-prompt', '{agentBody}', '--yolo', '--output-format', 'stream-json', '--max-wall-time', '10m'],
             },
+            // 场景作业(scene-maker):分钟级、几美元一个,预算与时限比问答大;老师条目 runtime 指到它
+            'claude-scene': {
+                run: ['claude', '--agent', '{agent}', '-p', '{prompt}', '--dangerously-skip-permissions', '--output-format', 'stream-json', '--verbose', '--max-budget-usd', '8'],
+                resume: ['claude', '--agent', '{agent}', '-p', '--resume', '{session}', '{prompt}', '--dangerously-skip-permissions', '--output-format', 'stream-json', '--verbose', '--max-budget-usd', '8'],
+            },
+            'qwen-scene': {
+                run: ['qwen', '-p', '{prompt}', '--append-system-prompt', '{agentBody}', '--yolo', '--output-format', 'stream-json', '--max-wall-time', '25m'],
+                resume: ['qwen', '-p', '{prompt}', '--resume', '{session}', '--append-system-prompt', '{agentBody}', '--yolo', '--output-format', 'stream-json', '--max-wall-time', '25m'],
+            },
         },
+        tts: TTS_DEFAULT,
         _note: '一孩一 workspace 的政策文件,家长改这里;机器不会自动重建或覆盖,写坏了靠 git 回退,cotutor doctor 可体检。' +
-            'teachers = 老师表(key 与 .claude/agents/<key>.md 的 name 一致):display 显示名、avatar、voice 用 voxtell 音色 id、enabled 开关、hidden 孩子端不露、policy 覆盖 policyDefaults。' +
-            'policyDefaults 缺省:replyMaxChars 60、dailyMessages 30、dailyRegen 3、reviewGate false、contextPack {recent 10, planLines 10}。' +
+            'tutors = 老师表(key 与 .claude/agents/<key>.md 的 name 一致):display 显示名、avatar、voice 用 voxtell 音色 id、enabled 开关、hidden 孩子端不露、policy 覆盖 policyDefaults。' +
+            'policyDefaults 缺省:replyMaxChars 60(每句)、dailyMessages 30、dailyRegen 3、reviewGate false、contextPack {recent 10, planLines 10}、board auto(off = 只说话不出卡)。' +
             'paths = 角色映射:vault 指 Obsidian vault 根(一孩一 vault),photos/diary/plans/profile/timetable 相对 vault。' +
-            'agents = 运行时预设,占位 {agent} {agentBody} {prompt} {session};政策旋钮(预算、时限)写进模板。',
+            'runtimes = 运行时,占位 {agent} {agentBody} {prompt} {session};政策旋钮(预算、时限、模型)写进模板;老师条目的 runtime 可指定用哪个(scene-maker 用 claude-scene:预算 8 美元)。scenes.dailyMax(缺省 2)= 每天最多起几个场景作业。' +
+            'tts = 配音命令,占位 {text} {voice} {out};老师没配 voice 就不合成,孩子端用浏览器的声。' +
+            'server.https = {cert, key} 只给这个 workspace 用的证书路径(相对 workspace 根);不配则用机器级 ~/.config/cotutor/certs/(cotutor cert 用 mkcert 建,所有 workspace 共用)。',
     };
     return `${JSON.stringify(cfg, null, 2)}\n`;
 }
+/** 把 JSON Schema 写进 workspace(机器文件,每次 init / upgrade 都刷新) */
+/** 给老师看的板书语法表:从卡的注册表现生成,机器文件,init / upgrade 每次刷新;老师文件正文让老师讲解前读它 */
+export const SYNTAX_FILE = '.cotutor/板书语法.md';
+export async function writeSyntaxFile(root) {
+    const file = join(root, SYNTAX_FILE);
+    await mkdir(join(root, '.cotutor'), { recursive: true });
+    await writeFile(file, boardSyntaxDoc());
+    return file;
+}
+export async function writeSchemaFile(root) {
+    const file = join(root, CONFIG_SCHEMA_FILE);
+    await mkdir(join(root, '.cotutor'), { recursive: true });
+    await writeFile(file, `${JSON.stringify(cotutorJsonSchema(), null, 2)}\n`);
+    return file;
+}

package/dist/cli/skills.d.ts

@@ -0,0 +1,40 @@
+export declare const SHIPPED_SKILLS: readonly ["drawtell-scene", "drawtell-teaching", "drawtell-cli", "drawtell-verify"];
+export type ShippedSkillName = (typeof SHIPPED_SKILLS)[number];
+/** drawtell-skills 包的 skills/ 目录;包没装 → null(doctor 点名,init 跳过) */
+export declare function packageSkillsDir(): string | null;
+/** drawtell CLI 的入口(本包 node_modules 里);没装 → null */
+export declare function drawtellBin(): string | null;
+export declare const TOOL_SHIM = ".cotutor/drawtell";
+/** 一个目录的内容 hash:相对路径 + 内容,按路径排序 */
+export declare function dirHash(dir: string): Promise<string>;
+export type SkillState = 'latest' | 'upgradable' | 'custom' | 'untracked' | 'missing' | 'unavailable';
+export interface SkillStatus {
+    name: ShippedSkillName;
+    state: SkillState;
+    dir: string;
+    basedOn?: string;
+}
+export declare function skillDirs(root: string, name: string): {
+    claude: string;
+    qwen: string;
+};
+export declare function skillStatuses(root: string): Promise<SkillStatus[]>;
+export interface SkillStep {
+    item: string;
+    action: 'created' | 'exists' | 'kept' | 'replaced';
+    note?: string;
+}
+/** init 用:缺的拷,有的不动;drawtell-skills 没装就只报一行 */
+export declare function installSkills(root: string): Promise<SkillStep[]>;
+export interface SkillUpgradeStep {
+    name: string;
+    action: 'upgraded' | 'latest' | 'kept-custom' | 'installed' | 'unavailable';
+    basedOn?: string;
+}
+/** upgrade 用:latest 跳过;upgradable 换新;custom / untracked 保留只报;缺的补 */
+export declare function upgradeSkills(root: string): Promise<SkillUpgradeStep[]>;
+/** .cotutor/drawtell:壳脚本,老师在 agents/<name>/ 里用 ../../.cotutor/drawtell 跑 drawtell CLI;机器文件,init / upgrade 每次刷新 */
+export declare function writeToolShim(root: string): Promise<{
+    file: string;
+    available: boolean;
+}>;

package/dist/cli/skills.js

@@ -0,0 +1,170 @@
+/**
+ * 出厂 skill(scene-maker 用的四个领域 skill,来自 drawtell-skills 包):与老师文件同一套「拷不链」机制——
+ * init 拷进 workspace 的 .claude/skills/<name>/(拷进来就是家长的),hash 记 .cotutor/shipped.json 的 skills,
+ * upgrade 没改过的换新、改过的报 diff 保留;.qwen/skills/<name> 是相对链。工作流 skill(math-explainer 等)不拷,
+ * scene-maker 的工作流写在它的老师文件正文里(《drawtell接入与场景卡.md》§3)。
+ * 顺带一个机器文件 .cotutor/drawtell:指向本包 node_modules 里 drawtell CLI 的壳脚本,老师用相对路径就能跑它。
+ */
+import { createHash } from 'node:crypto';
+import { chmod, cp, lstat, mkdir, readFile, readdir, readlink, rm, symlink, unlink, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, join, relative } from 'node:path';
+import { PACKAGE_VERSION } from "./skeleton.js";
+import { readManifest, writeManifest } from "./tutors.js";
+export const SHIPPED_SKILLS = ['drawtell-scene', 'drawtell-teaching', 'drawtell-cli', 'drawtell-verify'];
+/** drawtell-skills 包的 skills/ 目录;包没装 → null(doctor 点名,init 跳过) */
+export function packageSkillsDir() {
+    try {
+        return join(dirname(createRequire(import.meta.url).resolve('drawtell-skills/package.json')), 'skills');
+    }
+    catch {
+        return null;
+    }
+}
+/** drawtell CLI 的入口(本包 node_modules 里);没装 → null */
+export function drawtellBin() {
+    try {
+        return join(dirname(createRequire(import.meta.url).resolve('drawtell/package.json')), 'bin', 'drawtell.js');
+    }
+    catch {
+        return null;
+    }
+}
+export const TOOL_SHIM = '.cotutor/drawtell';
+/** 一个目录的内容 hash:相对路径 + 内容,按路径排序 */
+export async function dirHash(dir) {
+    const files = [];
+    const walk = async (d) => {
+        for (const e of (await readdir(d, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+            const p = join(d, e.name);
+            if (e.isDirectory())
+                await walk(p);
+            else if (e.isFile())
+                files.push(p);
+        }
+    };
+    await walk(dir);
+    const h = createHash('sha256');
+    for (const f of files.sort()) {
+        h.update(relative(dir, f));
+        h.update('\0');
+        h.update(await readFile(f));
+        h.update('\0');
+    }
+    return `sha256:${h.digest('hex')}`;
+}
+export function skillDirs(root, name) {
+    return { claude: join(root, '.claude', 'skills', name), qwen: join(root, '.qwen', 'skills', name) };
+}
+async function readState(root, name, manifest, src) {
+    const { claude } = skillDirs(root, name);
+    const st = await lstat(claude).catch(() => null);
+    if (!st?.isDirectory())
+        return { name, state: src ? 'missing' : 'unavailable', dir: claude };
+    const rec = manifest.skills?.[name];
+    const mine = await dirHash(claude);
+    if (src) {
+        const shipped = await dirHash(join(src, name)).catch(() => null);
+        if (shipped && mine === shipped)
+            return { name, state: 'latest', dir: claude, basedOn: rec?.version };
+    }
+    if (rec && rec.hash === mine)
+        return { name, state: src ? 'upgradable' : 'latest', dir: claude, basedOn: rec.version };
+    return { name, state: rec ? 'custom' : 'untracked', dir: claude, basedOn: rec?.version };
+}
+export async function skillStatuses(root) {
+    const manifest = await readManifest(root);
+    const src = packageSkillsDir();
+    const out = [];
+    for (const name of SHIPPED_SKILLS)
+        out.push(await readState(root, name, manifest, src));
+    return out;
+}
+async function installOne(root, name, src, manifest) {
+    const { claude } = skillDirs(root, name);
+    await rm(claude, { recursive: true, force: true });
+    await mkdir(dirname(claude), { recursive: true });
+    await cp(join(src, name), claude, { recursive: true });
+    manifest.skills ??= {};
+    manifest.skills[name] = { hash: await dirHash(claude), version: PACKAGE_VERSION };
+}
+async function ensureQwenLink(root, name) {
+    const { claude, qwen } = skillDirs(root, name);
+    await mkdir(dirname(qwen), { recursive: true });
+    const want = relative(dirname(qwen), claude);
+    const st = await lstat(qwen).catch(() => null);
+    if (st?.isSymbolicLink() && (await readlink(qwen).catch(() => '')) === want)
+        return 'exists';
+    if (st) {
+        if (!st.isSymbolicLink())
+            return 'exists';
+        await unlink(qwen);
+        await symlink(want, qwen);
+        return 'replaced';
+    }
+    await symlink(want, qwen);
+    return 'created';
+}
+/** init 用:缺的拷,有的不动;drawtell-skills 没装就只报一行 */
+export async function installSkills(root) {
+    const steps = [];
+    const src = packageSkillsDir();
+    if (!src)
+        return [{ item: '.claude/skills/', action: 'kept', note: 'drawtell-skills 没装,四个领域 skill 没拷(scene-maker 作业要它们);仓库根 pnpm install' }];
+    const manifest = await readManifest(root);
+    let touched = false;
+    for (const name of SHIPPED_SKILLS) {
+        const s = await readState(root, name, manifest, src);
+        const item = `.claude/skills/${name}/`;
+        if (s.state === 'missing') {
+            await installOne(root, name, src, manifest);
+            touched = true;
+            steps.push({ item, action: 'created', note: `拷自 drawtell-skills` });
+        }
+        else
+            steps.push({ item, action: 'exists', note: s.state === 'custom' ? `自定义(基于 ${s.basedOn})` : s.state === 'upgradable' ? '可升级(cotutor upgrade)' : s.state === 'untracked' ? '已有(没有出厂记录);升级时当自定义对待' : undefined });
+        const q = await ensureQwenLink(root, name);
+        steps.push({ item: `.qwen/skills/${name}`, action: q, note: q === 'exists' ? undefined : '→ ../../.claude/skills/' });
+    }
+    if (touched)
+        await writeManifest(root, { ...manifest, version: PACKAGE_VERSION });
+    return steps;
+}
+/** upgrade 用:latest 跳过;upgradable 换新;custom / untracked 保留只报;缺的补 */
+export async function upgradeSkills(root) {
+    const src = packageSkillsDir();
+    const steps = [];
+    if (!src)
+        return SHIPPED_SKILLS.map((name) => ({ name, action: 'unavailable' }));
+    const manifest = await readManifest(root);
+    for (const name of SHIPPED_SKILLS) {
+        const s = await readState(root, name, manifest, src);
+        if (s.state === 'latest')
+            steps.push({ name, action: 'latest', basedOn: s.basedOn });
+        else if (s.state === 'missing') {
+            await installOne(root, name, src, manifest);
+            steps.push({ name, action: 'installed' });
+        }
+        else if (s.state === 'upgradable') {
+            await installOne(root, name, src, manifest);
+            steps.push({ name, action: 'upgraded', basedOn: s.basedOn });
+        }
+        else
+            steps.push({ name, action: 'kept-custom', basedOn: s.basedOn });
+        await ensureQwenLink(root, name);
+    }
+    await writeManifest(root, { ...manifest, version: PACKAGE_VERSION });
+    return steps;
+}
+/** .cotutor/drawtell:壳脚本,老师在 agents/<name>/ 里用 ../../.cotutor/drawtell 跑 drawtell CLI;机器文件,init / upgrade 每次刷新 */
+export async function writeToolShim(root) {
+    const file = join(root, TOOL_SHIM);
+    const bin = drawtellBin();
+    await mkdir(dirname(file), { recursive: true });
+    const body = bin
+        ? `#!/bin/sh\n# cotutor 生成的机器文件:drawtell CLI 的壳,指向本包 node_modules 里的 drawtell;init / upgrade 会刷新\nexec node "${bin}" "$@"\n`
+        : `#!/bin/sh\necho "cotutor: node_modules 里没有 drawtell(仓库根 pnpm install),场景作业跑不了" >&2\nexit 1\n`;
+    await writeFile(file, body);
+    await chmod(file, 0o755);
+    return { file, available: bin !== null };
+}

package/dist/cli/tutors.d.ts

@@ -0,0 +1,84 @@
+import { type TutorTemplateInput } from './skeleton.ts';
+export declare const SHIPPED_FILE = ".cotutor/shipped.json";
+export interface ShippedManifest {
+    /** 出厂 skill(drawtell-skills 的四个领域 skill)的 hash,与 tutors 同一套机制(src/cli/skills.ts) */
+    skills?: Record<string, {
+        hash: string;
+        version: string;
+    }>;
+    version: string;
+    tutors: Record<string, {
+        hash: string;
+        version: string;
+    }>;
+}
+export declare const sha256: (text: string) => string;
+export declare function readManifest(root: string): Promise<ShippedManifest>;
+export declare function writeManifest(root: string, m: ShippedManifest): Promise<void>;
+export type TutorState = 'latest' | 'upgradable' | 'custom' | 'untracked' | 'missing' | 'broken';
+export interface TutorStatus {
+    name: string;
+    state: TutorState;
+    /** workspace 里那份 */
+    file: string;
+    /** 记录的出厂版本(custom / upgradable 时有) */
+    basedOn?: string;
+    /** 是否还是指向包的旧链(init 会换成拷贝) */
+    legacyLink?: boolean;
+}
+/** 老师文件在 workspace 里的位置:.claude/agents/<name>.md 是真相,.qwen/agents/<name>.md 是相对链 */
+export declare function tutorFiles(root: string, name: string): {
+    claude: string;
+    qwen: string;
+};
+export declare function tutorStatuses(root: string): Promise<TutorStatus[]>;
+export interface InstallStep {
+    item: string;
+    action: 'created' | 'exists' | 'kept' | 'replaced';
+    note?: string;
+}
+/**
+ * init 用。出厂的:缺的拷,旧的包内链换成拷贝,家长的文件不动;
+ * cotutor.json 里的每一位(含家长自己加的):补老师目录 agents/<name>/ 与 .qwen 链——「加老师 = 加文件 + 目录,没有注册表」,
+ * 自己加的老师文件不在这里生成(cotutor add 生成模板),缺了由 doctor 点名。
+ */
+export declare function installTutors(root: string, configured?: string[]): Promise<InstallStep[]>;
+export interface AddResult {
+    name: string;
+    file: string;
+    home: string;
+}
+/**
+ * cotutor add <name>:按出厂老师的结构写一份模板(约定都带上,人设一句留给家长填)、建目录与 .qwen 链。
+ * 不动 cotutor.json——那是调用方(main / 页面)用 patchConfig 加的,同一条路。已有同名文件就拒,不覆盖。
+ */
+export declare function addTutorFile(root: string, input: TutorTemplateInput): Promise<AddResult>;
+export interface UpgradeStep {
+    name: string;
+    action: 'upgraded' | 'latest' | 'kept-custom' | 'forced' | 'installed';
+    basedOn?: string;
+    /** custom 时的行级 diff(出厂新版 vs 你的) */
+    diff?: string[];
+}
+/** 最小行 diff(LCS),只为让家长看清改了哪几行;不追求 git 那么好 */
+export declare function lineDiff(a: string, b: string): string[];
+/**
+ * cotutor upgrade:latest 跳过;upgradable 换新;custom / untracked 只报 diff 并保留(--force <name> 才覆盖,原文留 .bak);缺的补。
+ */
+export declare function upgradeTutors(root: string, opts?: {
+    force?: string[];
+}): Promise<UpgradeStep[]>;
+export interface TutorFileView {
+    name: string;
+    text: string;
+    /** 出厂件的状态;自家加的是 own */
+    state: TutorState | 'own';
+    basedOn?: string;
+}
+export declare function readTutorFile(root: string, name: string): Promise<TutorFileView>;
+/** 页面上改老师正文:frontmatter 的 name 必须还是它;写完 doctor 会把它标成自定义 */
+export declare function writeTutorFile(root: string, name: string, text: string): Promise<TutorFileView>;
+/** 删自家加的老师文件:改名成 .removed-<时间>(不真删;记忆目录与对话不动);出厂的不让删,用开关 */
+export declare function removeTutorFile(root: string, name: string): Promise<{
+    moved: string | null;
+}>;