cotutor 0.1.0 → 0.2.0

package/dist/cli/tutors.js

@@ -0,0 +1,274 @@
+/**
+ * 老师文件的安装与升级(2026-09-09 拍板:**拷贝,不链**)。
+ * 包里的 agents/<name>.md 是出厂件;init 把它拷进 workspace 的 .claude/agents/<name>.md(这份是家长的,想改就改),
+ * .qwen/agents/<name>.md 是指向它的相对链(一份真相两处可见,链在 workspace 内,不怕包搬家或 npx 缓存回收)。
+ * 出厂时的内容 hash 记在 .cotutor/shipped.json(机器文件,家长不用管),据此分三种状态:
+ *   latest     与本包一致
+ *   upgradable 与记录的出厂 hash 一致(没改过,只是包更新了)→ cotutor upgrade 直接换新
+ *   custom     改过 → upgrade 只报 diff,不动
+ *   untracked  没有记录(旧workspace、或家长手写的老师)→ 当 custom 对待
+ */
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, readFile, readlink, rename, symlink, unlink, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, relative } from 'node:path';
+import { PACKAGE_AGENTS_DIR, PACKAGE_VERSION, shippedAgents, tutorTemplate, writeSchemaFile, writeSyntaxFile } from "./skeleton.js";
+import { AGENT_NAME_RE } from "../schema/index.js";
+import { UsageError } from "./workspace.js";
+export const SHIPPED_FILE = '.cotutor/shipped.json';
+export const sha256 = (text) => `sha256:${createHash('sha256').update(text).digest('hex')}`;
+export async function readManifest(root) {
+    try {
+        const raw = JSON.parse(await readFile(join(root, SHIPPED_FILE), 'utf8'));
+        return { version: raw.version ?? '0', tutors: raw.tutors ?? {} };
+    }
+    catch {
+        return { version: '0', tutors: {} };
+    }
+}
+export async function writeManifest(root, m) {
+    const file = join(root, SHIPPED_FILE);
+    await mkdir(dirname(file), { recursive: true });
+    const tmp = `${file}.tmp`;
+    await writeFile(tmp, `${JSON.stringify({ ...m, _note: '出厂时老师文件的 hash,cotutor upgrade 据此分辨「没改过」与「改过」;机器写,不用手改' }, null, 2)}\n`);
+    await rename(tmp, file);
+}
+/** 老师文件在 workspace 里的位置:.claude/agents/<name>.md 是真相,.qwen/agents/<name>.md 是相对链 */
+export function tutorFiles(root, name) {
+    return { claude: join(root, '.claude', 'agents', `${name}.md`), qwen: join(root, '.qwen', 'agents', `${name}.md`) };
+}
+async function readState(root, a, manifest) {
+    const { claude } = tutorFiles(root, a.name);
+    const st = await lstat(claude).catch(() => null);
+    if (!st)
+        return { name: a.name, state: 'missing', file: claude };
+    let legacyLink = false;
+    if (st.isSymbolicLink()) {
+        const target = await readlink(claude).catch(() => '');
+        legacyLink = target.startsWith(PACKAGE_AGENTS_DIR) || target === a.file;
+    }
+    let text;
+    try {
+        text = await readFile(claude, 'utf8');
+    }
+    catch {
+        return { name: a.name, state: 'broken', file: claude, legacyLink };
+    }
+    const shipped = await readFile(a.file, 'utf8');
+    const h = sha256(text);
+    const rec = manifest.tutors[a.name];
+    if (h === sha256(shipped))
+        return { name: a.name, state: 'latest', file: claude, basedOn: rec?.version, legacyLink };
+    if (rec && rec.hash === h)
+        return { name: a.name, state: 'upgradable', file: claude, basedOn: rec.version, legacyLink };
+    return { name: a.name, state: rec ? 'custom' : 'untracked', file: claude, basedOn: rec?.version, legacyLink };
+}
+export async function tutorStatuses(root) {
+    const manifest = await readManifest(root);
+    const out = [];
+    for (const a of await shippedAgents())
+        out.push(await readState(root, a, manifest));
+    return out;
+}
+/** 把出厂件写进 workspace(覆盖),并记 hash */
+async function installOne(root, a, manifest) {
+    const { claude } = tutorFiles(root, a.name);
+    await mkdir(dirname(claude), { recursive: true });
+    const text = await readFile(a.file, 'utf8');
+    await unlink(claude).catch(() => { });
+    await writeFile(claude, text);
+    manifest.tutors[a.name] = { hash: sha256(text), version: PACKAGE_VERSION };
+}
+/** .qwen/agents/<name>.md → ../../.claude/agents/<name>.md;已是这条链就不动;是旧的包内链或别的东西就换 */
+async function ensureQwenLink(root, name) {
+    const { claude, qwen } = tutorFiles(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()) {
+            // 家长手放了实体文件在 .qwen 下:留着,当作她的
+            return 'exists';
+        }
+        await unlink(qwen);
+        await symlink(want, qwen);
+        return 'replaced';
+    }
+    await symlink(want, qwen);
+    return 'created';
+}
+/**
+ * init 用。出厂的:缺的拷,旧的包内链换成拷贝,家长的文件不动;
+ * cotutor.json 里的每一位(含家长自己加的):补老师目录 agents/<name>/ 与 .qwen 链——「加老师 = 加文件 + 目录,没有注册表」,
+ * 自己加的老师文件不在这里生成(cotutor add 生成模板),缺了由 doctor 点名。
+ */
+export async function installTutors(root, configured = []) {
+    const steps = [];
+    const manifest = await readManifest(root);
+    let touched = false;
+    const shipped = await shippedAgents();
+    for (const a of shipped) {
+        const s = await readState(root, a, manifest);
+        const item = `.claude/agents/${basename(a.file)}`;
+        if (s.state === 'missing' || s.legacyLink || s.state === 'broken') {
+            await installOne(root, a, manifest);
+            touched = true;
+            steps.push({ item, action: s.state === 'missing' ? 'created' : 'replaced', note: s.legacyLink ? '旧的包内链换成拷贝(2026-09-09 起老师文件是你的)' : s.state === 'broken' ? '读不到,重新拷贝' : `拷自本包 ${PACKAGE_VERSION}` });
+        }
+        else if (s.state === 'untracked') {
+            // 没记录但内容在:当家长的,记一笔当前 hash 免得以后一直是 untracked?不记——记了就等于宣称它是出厂件。留 untracked。
+            steps.push({ item, action: 'kept', note: '已有(不是出厂件,或没有记录);升级时当自定义对待' });
+        }
+        else {
+            steps.push({ item, action: 'exists', note: s.state === 'custom' ? `自定义(基于 ${s.basedOn})` : s.state === 'upgradable' ? `可升级(cotutor upgrade)` : undefined });
+        }
+        const q = await ensureQwenLink(root, a.name);
+        steps.push({ item: `.qwen/agents/${basename(a.file)}`, action: q, note: q === 'exists' ? undefined : '→ ../../.claude/agents/' });
+    }
+    for (const name of configured.filter((n) => !shipped.some((a) => a.name === n))) {
+        const { claude } = tutorFiles(root, name);
+        if (await lstat(claude).catch(() => null)) {
+            const q = await ensureQwenLink(root, name);
+            steps.push({ item: `.qwen/agents/${name}.md`, action: q, note: q === 'exists' ? undefined : '→ ../../.claude/agents/(自家的老师)' });
+        }
+        else
+            steps.push({ item: `.claude/agents/${name}.md`, action: 'kept', note: `缺:cotutor.json 里有 ${name},文件还没写;cotutor add ${name} 出模板,或自己写(frontmatter name: ${name})` });
+    }
+    for (const name of [...new Set([...shipped.map((a) => a.name), ...configured])]) {
+        const home = join(root, 'agents', name);
+        if (await lstat(home).catch(() => null)) {
+            steps.push({ item: `agents/${name}/`, action: 'exists' });
+            continue;
+        }
+        await mkdir(home, { recursive: true });
+        await writeFile(join(home, '.gitkeep'), '');
+        steps.push({ item: `agents/${name}/`, action: 'created' });
+    }
+    if (touched || !(await lstat(join(root, SHIPPED_FILE)).catch(() => null)))
+        await writeManifest(root, { ...manifest, version: PACKAGE_VERSION });
+    return steps;
+}
+/**
+ * cotutor add <name>:按出厂老师的结构写一份模板(约定都带上,人设一句留给家长填)、建目录与 .qwen 链。
+ * 不动 cotutor.json——那是调用方(main / 页面)用 patchConfig 加的,同一条路。已有同名文件就拒,不覆盖。
+ */
+export async function addTutorFile(root, input) {
+    if (!AGENT_NAME_RE.test(input.name))
+        throw new UsageError(`老师名 "${input.name}" 不合规:小写字母数字连字符,如 science-tutor`);
+    const { claude } = tutorFiles(root, input.name);
+    if (await lstat(claude).catch(() => null))
+        throw new UsageError(`${claude} 已经在了;要改就直接改它,要重来先把它挪开`);
+    await mkdir(dirname(claude), { recursive: true });
+    await writeFile(claude, tutorTemplate(input));
+    await ensureQwenLink(root, input.name);
+    const home = join(root, 'agents', input.name);
+    await mkdir(home, { recursive: true });
+    await writeFile(join(home, '.gitkeep'), '').catch(() => { });
+    return { name: input.name, file: claude, home };
+}
+/** 最小行 diff(LCS),只为让家长看清改了哪几行;不追求 git 那么好 */
+export function lineDiff(a, b) {
+    const A = a.split('\n');
+    const B = b.split('\n');
+    const n = A.length;
+    const m = B.length;
+    const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i--)
+        for (let j = m - 1; j >= 0; j--)
+            dp[i][j] = A[i] === B[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+    const out = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (A[i] === B[j]) {
+            i++;
+            j++;
+        }
+        else if (dp[i + 1][j] >= dp[i][j + 1])
+            out.push(`- ${A[i++]}`);
+        else
+            out.push(`+ ${B[j++]}`);
+    }
+    while (i < n)
+        out.push(`- ${A[i++]}`);
+    while (j < m)
+        out.push(`+ ${B[j++]}`);
+    return out;
+}
+/**
+ * cotutor upgrade:latest 跳过;upgradable 换新;custom / untracked 只报 diff 并保留(--force <name> 才覆盖,原文留 .bak);缺的补。
+ */
+export async function upgradeTutors(root, opts = {}) {
+    const manifest = await readManifest(root);
+    const steps = [];
+    for (const a of await shippedAgents()) {
+        const s = await readState(root, a, manifest);
+        const force = opts.force?.includes(a.name) ?? false;
+        if (s.state === 'latest' && !s.legacyLink) {
+            steps.push({ name: a.name, action: 'latest', basedOn: s.basedOn });
+        }
+        else if (s.state === 'missing' || s.state === 'broken') {
+            await installOne(root, a, manifest);
+            steps.push({ name: a.name, action: 'installed' });
+        }
+        else if (s.state === 'upgradable' || s.legacyLink || (s.state === 'latest' && s.legacyLink)) {
+            await installOne(root, a, manifest);
+            steps.push({ name: a.name, action: 'upgraded', basedOn: s.basedOn });
+        }
+        else if (force) {
+            const mine = await readFile(s.file, 'utf8');
+            await writeFile(`${s.file}.bak`, mine);
+            await installOne(root, a, manifest);
+            steps.push({ name: a.name, action: 'forced', basedOn: s.basedOn });
+        }
+        else {
+            const mine = await readFile(s.file, 'utf8');
+            const shipped = await readFile(a.file, 'utf8');
+            steps.push({ name: a.name, action: 'kept-custom', basedOn: s.basedOn, diff: lineDiff(mine, shipped) });
+        }
+        await ensureQwenLink(root, a.name);
+    }
+    await writeManifest(root, { ...manifest, version: PACKAGE_VERSION });
+    await writeSchemaFile(root);
+    await writeSyntaxFile(root);
+    return steps;
+}
+export async function readTutorFile(root, name) {
+    const { claude } = tutorFiles(root, name);
+    const text = await readFile(claude, 'utf8').catch(() => null);
+    if (text === null)
+        throw new UsageError(`老师文件不在:${claude};cotutor add ${name} --display <显示名> 可出模板`);
+    const st = (await tutorStatuses(root)).find((s) => s.name === name);
+    return { name, text, state: st?.state ?? 'own', basedOn: st?.basedOn };
+}
+/** 页面上改老师正文:frontmatter 的 name 必须还是它;写完 doctor 会把它标成自定义 */
+export async function writeTutorFile(root, name, text) {
+    const { parseAgentFile } = await import("../lib/agent-file.js");
+    const fm = parseAgentFile(text).frontmatter;
+    if (fm.name !== name)
+        throw new UsageError(`frontmatter 的 name 要是 ${name}(现在是 "${fm.name ?? ''}"),老师键靠它对上`);
+    const { claude } = tutorFiles(root, name);
+    await mkdir(dirname(claude), { recursive: true });
+    const tmp = `${claude}.tmp`;
+    await writeFile(tmp, text.endsWith('\n') ? text : `${text}\n`);
+    await rename(tmp, claude);
+    await ensureQwenLink(root, name);
+    return readTutorFile(root, name);
+}
+/** 删自家加的老师文件:改名成 .removed-<时间>(不真删;记忆目录与对话不动);出厂的不让删,用开关 */
+export async function removeTutorFile(root, name) {
+    if ((await shippedAgents()).some((a) => a.name === name))
+        throw new UsageError(`${name} 是出厂老师,不删文件;不想用就在老师团页关掉`);
+    const { claude, qwen } = tutorFiles(root, name);
+    await unlink(qwen).catch(() => { });
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const moved = `${claude}.removed-${stamp}`;
+    try {
+        await rename(claude, moved);
+        return { moved };
+    }
+    catch {
+        return { moved: null };
+    }
+}

package/dist/cli/workspace.d.ts

@@ -9,6 +9,8 @@ export declare class ConfigError extends UsageError {
 }
 export declare const CONFIG_FILE = "cotutor.json";
 export declare const USER_CONFIG: string;
+/** 机器级自签证书目录(cotutor cert 写 cert.pem + key.pem):证书签的是本机名与局域网 IP,与孩子无关,所以不在 workspace 里(2026-09-09 拍板) */
+export declare const USER_CERT_DIR: string;
 export declare const HOME_ROOT: string;
 export type RootSource = 'flag' | 'env' | 'cwd' | 'user-config' | 'home-single';
 export interface ResolvedRoot {
@@ -42,6 +44,12 @@ export interface Workspace {
         conversations: string;
         claudeAgents: string;
         qwenAgents: string;
+        /** 场景源(scene-maker 写的 scenes/<id>.ts 与说明文件) */
+        scenes: string;
+        /** 课包(drawtell build 的产物,场景卡从这里播;派生物,gitignore) */
+        bundles: string;
+        /** 关键帧截图(drawtell snap;派生物) */
+        snaps: string;
     };
     files: {
         config: string;
@@ -57,5 +65,5 @@ export declare function resolvePaths(root: string, paths: Record<string, string>
 export declare function assembleWorkspace(root: string, source: RootSource, config: CotutorConfig): Workspace;
 /** 定根 + 读配置 + 校验 + 展开角色。cotutor.json 缺失也是错(它是必需的)。 */
 export declare function loadWorkspace(override?: string, opts?: ResolveOptions): Workspace;
-/** --json / 启动日志里回报工作区(脱敏) */
+/** --json / 启动日志里回报workspace(脱敏) */
 export declare function workspaceReport(ws: Workspace): Record<string, unknown>;

package/dist/cli/workspace.js

@@ -1,5 +1,5 @@
 /**
- * 工作区解析:一孩一 workspace(`~/cotutor/<slug>/`,2026-09-08 拍板)。
+ * workspace解析:一孩一 workspace(`~/cotutor/<slug>/`,2026-09-08 拍板)。
  * 解析链(定根):`--workspace <dir>` → 环境变量 COTUTOR_WORKSPACE → cwd 或其祖先有 cotutor.json
  * (老师的 cwd 是 <ws>/agents/<name>/,从那里跑 doctor 也要找得到根)→ 用户配置
  * ~/.config/cotutor/config.json 的 workspace → ~/cotutor/ 下**唯一**的一个孩子目录 → 都没有就报错附修复指南。
@@ -23,6 +23,8 @@ export class ConfigError extends UsageError {
 }
 export const CONFIG_FILE = 'cotutor.json';
 export const USER_CONFIG = join(homedir(), '.config', 'cotutor', 'config.json');
+/** 机器级自签证书目录(cotutor cert 写 cert.pem + key.pem):证书签的是本机名与局域网 IP,与孩子无关,所以不在 workspace 里(2026-09-09 拍板) */
+export const USER_CERT_DIR = join(homedir(), '.config', 'cotutor', 'certs');
 export const HOME_ROOT = join(homedir(), 'cotutor');
 export function expandPath(p, base) {
     if (p === '~')
@@ -135,6 +137,22 @@ export function resolveRoot(override, opts = {}) {
 }
 /** 校验 cotutor.json 的形状;失败 → ConfigError,信息是逐条修复指南 */
 export function parseConfig(raw, file) {
+    // 2026-09-09 术语统一(teacher → tutor,homework-aide → homework-tutor):旧键旧名响亮报,不静默变成零位老师
+    if (raw && typeof raw === 'object') {
+        const o = raw;
+        if ('teachers' in o && !('tutors' in o)) {
+            throw new ConfigError(file, '  - teachers:这个键 2026-09-09 起叫 tutors(术语统一为 tutor / 老师);把 "teachers" 改成 "tutors",老师名 *-teacher 改成 *-tutor、homework-aide 改成 homework-tutor,.claude/agents/ 下的文件同名改,然后 cotutor init 补齐');
+        }
+        if ('agents' in o && !('runtimes' in o)) {
+            throw new ConfigError(file, '  - agents:这个键 2026-09-09 起叫 runtimes(它是跑老师的运行时,与 .claude/agents/ 的 agent 文件、agents/<老师>/ 的老师目录是三回事);把 "agents" 改成 "runtimes" 即可,模板内容与占位 {agent} {agentBody} 不变');
+        }
+        const tutors = o.tutors;
+        if (tutors && typeof tutors === 'object') {
+            const old = Object.keys(tutors).filter((k) => k.endsWith('-teacher') || k === 'homework-aide');
+            if (old.length)
+                throw new ConfigError(file, `  - tutors:${old.join('、')} 是旧名;2026-09-09 起叫 ${old.map((k) => (k === 'homework-aide' ? 'homework-tutor' : k.replace(/-teacher$/, '-tutor'))).join('、')}(文件名与 frontmatter name 一起改),然后 cotutor init 补齐`);
+        }
+    }
     const r = CotutorConfigSchema.safeParse(raw);
     if (r.success)
         return r.data;
@@ -165,6 +183,9 @@ export function assembleWorkspace(root, source, config) {
             conversations: join(root, 'conversations'),
             claudeAgents: join(root, '.claude', 'agents'),
             qwenAgents: join(root, '.qwen', 'agents'),
+            scenes: join(root, 'scenes'),
+            bundles: join(root, 'bundles'),
+            snaps: join(root, 'snaps'),
         },
         files: {
             config: join(root, CONFIG_FILE),
@@ -184,7 +205,7 @@ export function loadWorkspace(override, opts = {}) {
         throw new ConfigError(file, `不存在。cotutor init <slug> --dir ${redactHome(root)} 可生成模板(已有文件不动)。`);
     return assembleWorkspace(root, source, parseConfig(raw, file));
 }
-/** --json / 启动日志里回报工作区(脱敏) */
+/** --json / 启动日志里回报workspace(脱敏) */
 export function workspaceReport(ws) {
     return redactDeep({
         workspace: ws.root,
@@ -193,7 +214,7 @@ export function workspaceReport(ws) {
         title: ws.config.title,
         port: ws.config.server.port,
         vault: ws.paths.vault,
-        teachers: Object.keys(ws.config.teachers),
-        agent: ws.config.agents.default,
+        tutors: Object.keys(ws.config.tutors),
+        runtime: ws.config.runtimes.default,
     });
 }

package/dist/lib/agent-file.d.ts

@@ -1,5 +1,5 @@
 /**
- * 老师定义文件(.claude/agents/<name>.md 同一份链到 .qwen/agents/):YAML frontmatter + 正文即系统提示。
+ * 老师文件文件(.claude/agents/<name>.md 同一份链到 .qwen/agents/):YAML frontmatter + 正文即系统提示。
  * 这里只认平铺的 `key: value` frontmatter(两个 CLI 的公共子集:name / description / maxTurns / permissionMode / memory);
  * 正文给没有 --agent 的 CLI 经 {agentBody} 塞进 --append-system-prompt。
  */

package/dist/lib/board.d.ts

@@ -0,0 +1,15 @@
+import { type BoardSection } from './kid-board.ts';
+export interface ParseBoardOptions {
+    /** 文本还在长(流式):压住没闭合的围栏与没换行结束的最后一行 */
+    partial?: boolean;
+}
+export interface ParsedBoard {
+    section: BoardSection;
+    /** 没解析成的卡等,家长视图转录里显示;孩子端不报 */
+    warnings: string[];
+    /** 第一个 H2 起的尾巴(「## 家长」等,原文含标题行);没有 = 空串 */
+    tail: string;
+}
+/** 讲稿一行的清洗:去掉老师不该写但常写的标题号、列表号、引用号、粗体号;整行的 HTML 注释不算话 */
+export declare function cleanSpeech(line: string): string;
+export declare function parseBoard(text: string, opts?: ParseBoardOptions): ParsedBoard;

package/dist/lib/board.js

@@ -0,0 +1,107 @@
+/**
+ * 板书解析器:老师的回复正文(已剥掉「待裁量」「转交」段)→ 一节 BoardSection。
+ * 三条规则(《板书卡片设计.md》§2):围栏 = 卡(标签第一个词是 kind),普通行 = 讲稿一句,第一个 H2 起是给家长的尾巴。
+ * 讲稿句里 [词] 是标注(落到第一张含这个词的卡,整节找,卡在前在后都行),[[名 参数]] 是对上一张卡的动作(cue)。
+ * partial 模式给流式用:没闭合的围栏和没换行结束的最后一行压着不算,下次整段重解析自然补上。
+ * 永不抛错:围栏没闭合当到文末,卡解析不出退成文字卡并记一句 warning。
+ */
+import { parseCard } from "../cards/index.js";
+import { anchorMarks, isQuestion, phrasesIn, plainLine } from "./kid-board.js";
+const FENCE_OPEN = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+const H2 = /^##\s+\S/;
+const CUE = /\[\[([^\[\]]+)\]\]/g;
+function fenceClose(line, fence) {
+    const m = /^ {0,3}(`{3,}|~{3,})\s*$/.exec(line);
+    return Boolean(m && m[1][0] === fence[0] && m[1].length >= fence.length);
+}
+/** 讲稿一行的清洗:去掉老师不该写但常写的标题号、列表号、引用号、粗体号;整行的 HTML 注释不算话 */
+export function cleanSpeech(line) {
+    const t = line.trim();
+    if (/^<!--.*-->$/.test(t))
+        return '';
+    return t
+        .replace(/^#{1,6}\s+/, '')
+        .replace(/^(?:[-*+]|\d+[.)])\s+/, '')
+        .replace(/^>\s*/, '')
+        .replace(/\*\*/g, '')
+        .trim();
+}
+function rawLine(line, cards) {
+    const anchor = cards.length ? cards.length - 1 : null;
+    const cues = [];
+    const text = line
+        .replace(CUE, (_, inner) => {
+        const [name, ...rest] = inner.trim().split(/\s+/);
+        if (name && anchor !== null)
+            cues.push({ card: anchor, name: name.toLowerCase(), ...(rest.length ? { arg: rest.join(' ') } : {}) });
+        return '';
+    })
+        .replace(/\s{2,}/g, ' ')
+        .trim();
+    return { text, anchor, cues };
+}
+export function parseBoard(text, opts = {}) {
+    const partial = opts.partial === true;
+    const all = text.split('\n');
+    const lines = partial && !text.endsWith('\n') ? all.slice(0, -1) : all;
+    const cards = [];
+    const raws = [];
+    const warnings = [];
+    let tail = null;
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (tail) {
+            tail.push(line);
+            i++;
+            continue;
+        }
+        const open = FENCE_OPEN.exec(line);
+        if (open) {
+            const fence = open[1];
+            const tag = open[2].trim();
+            const body = [];
+            let j = i + 1;
+            let closed = false;
+            for (; j < lines.length; j++) {
+                if (fenceClose(lines[j], fence)) {
+                    closed = true;
+                    break;
+                }
+                body.push(lines[j]);
+            }
+            if (!closed && partial)
+                break;
+            if (!closed)
+                warnings.push(`围栏没闭合(${tag || '无标签'}),当到文末`);
+            const r = parseCard(tag, body.join('\n'));
+            cards.push(r.card);
+            if (r.warning)
+                warnings.push(r.warning);
+            i = closed ? j + 1 : j;
+            continue;
+        }
+        if (H2.test(line)) {
+            tail = [line];
+            i++;
+            continue;
+        }
+        const speech = cleanSpeech(line);
+        if (speech)
+            raws.push(rawLine(speech, cards));
+        i++;
+    }
+    // 标注整节找(老师把卡写在句子后面也认),所以卡收齐了再落
+    const out = raws
+        .filter((r) => r.text)
+        .map((r) => {
+        const marks = anchorMarks(cards, phrasesIn(r.text));
+        const plain = plainLine(r.text);
+        return { text: plain, audio: null, marks, ask: isQuestion(plain), anchor: r.anchor, cues: r.cues };
+    });
+    return {
+        section: { cards, lines: out, ...(partial ? { partial: true } : {}) },
+        warnings,
+        tail: tail ? tail.join('\n').trim() : '',
+    };
+}

package/dist/lib/context-pack.js

@@ -14,7 +14,7 @@ export function renderContextPack(pack) {
     const out = ['cotutor:', `  from: ${p.from}`, `  at: ${yamlScalar(p.at)}`];
     if (p.slot)
         out.push(`  slot: ${yamlScalar(p.slot)}`);
-    if (p.focus && (p.focus.artifact || p.focus.step !== undefined || p.focus.circled?.length)) {
+    if (p.focus && (p.focus.artifact || p.focus.step !== undefined || p.focus.circled?.length || p.focus.card)) {
         out.push('  focus:');
         if (p.focus.artifact)
             out.push(`    artifact: ${yamlScalar(p.focus.artifact)}`);
@@ -22,6 +22,8 @@ export function renderContextPack(pack) {
             out.push(`    step: ${p.focus.step}`);
         if (p.focus.circled?.length)
             out.push(`    circled: [${p.focus.circled.map(yamlScalar).join(', ')}]`);
+        if (p.focus.card)
+            out.push(`    card: ${yamlScalar(p.focus.card)}`);
     }
     if (p.plan.length) {
         out.push('  plan:');
@@ -33,6 +35,13 @@ export function renderContextPack(pack) {
         for (const r of p.recent)
             out.push(`    - ${yamlScalar(`${r.date} ${r.claim}`)}`);
     }
+    if (p.board === 'off')
+        out.push('  board: off');
+    if (p.cards?.length) {
+        out.push('  cards:');
+        for (const c of p.cards)
+            out.push(`    - ${yamlScalar(c)}`);
+    }
     return out.join('\n');
 }
 /** 按政策截 plan / recent,再拼成「YAML 块 --- 消息」 */

package/dist/lib/conversation.d.ts

@@ -1,28 +1,65 @@
 /**
- * 会话索引的纯函数:日期与 job 命名、空索引、把一次运行的结果并进索引(不改旧对象)。
+ * 对话索引的纯函数:日期与 job 命名、空索引、把一次运行的结果并进索引(不改旧对象)。
  */
 import { type ConversationIndex, type ConversationMessage } from '../schema/index.ts';
 import type { KidView } from './kid-view.ts';
 import type { Transcript } from './transcript.ts';
-/** 本地日期 YYYY-MM-DD(会话按本地日切) */
+/** 本地日期 YYYY-MM-DD(对话按本地日切) */
 export declare function localDate(d: Date): string;
 /** 本地时间到分钟 YYYY-MM-DDTHH:MM(上下文包的 at) */
 export declare function localMinute(d: Date): string;
 /** HHMM-<序号>,同一天内不重复 */
 export declare function jobId(d: Date, seq: number): string;
-export declare function emptyIndex(teacher: string, date: string): ConversationIndex;
+export declare function emptyIndex(tutor: string, date: string): ConversationIndex;
 export interface ConversationFiles {
     index: string;
     log: (job: string) => string;
     err: (job: string) => string;
+    audio: (job: string) => string;
+    /** 板书讲稿第 n 句的配音(n 从 1 起) */
+    lineAudio: (job: string, n: number) => string;
+    /** 这一轮各张卡的状态目录 <date>.<job>.cards/ */
+    cardsDir: (job: string) => string;
+    /** 第 n 张卡(0 起)的状态文件 <date>.<job>.cards/<n>.json */
+    card: (job: string, n: number) => string;
+    /** 第 n 张卡的资产目录 <date>.<job>.cards/<n>/ */
+    cardAssetsDir: (job: string, n: number) => string;
+    /** 第 n 张卡的一个资产文件(点读第 k 段 = <k>.mp3) */
+    cardAsset: (job: string, n: number, file: string) => string;
 }
-/** conversations/<teacher>/<date>.json 与 <date>.<job>.log / .err.log */
-export declare function conversationFiles(conversationsDir: string, teacher: string, date: string): ConversationFiles;
+/** conversations/<tutor>/<date>.json 与 <date>.<job>.log / .err.log / .mp3(整段配音)/ .<n>.mp3(讲稿第 n 句)/ .cards/<n>.json(卡的状态) */
+export declare function conversationFiles(conversationsDir: string, tutor: string, date: string): ConversationFiles;
+/** 资产在孩子端的名字:相对 conversations/<老师>/,/api/audio 认它 */
+export declare function cardAssetName(date: string, job: string, n: number, file: string): string;
+/** 卡的 id:<job>/<n>(n 是节里的下标,0 起);页面、上下文包、状态文件名都用它 */
+export declare function cardId(job: string, n: number): string;
+/** 一张卡的状态文件:孩子做的事 + 什么时候做的 + 做的时候最后一轮是谁(下一条消息只带「上一轮之后改过的」) */
+export interface CardStateFile {
+    at: string;
+    /** 存的时候索引里最后一条消息的 job;下一条消息发出时 turn === 当时的末条 → 这张卡要带上 */
+    turn: string;
+    state: unknown;
+}
+/** 索引里每条消息 job → 它那节里卡下标 → 状态文件(没做过的卡不在) */
+export type CardStates = Record<string, Record<number, CardStateFile>>;
+/** job → 卡下标 → 已生成好的资产名(相对 conversations/<老师>/) */
+export type CardAssets = Record<string, Record<number, string[]>>;
+/** 上一轮之后改过状态的卡(按 job、下标排):发消息时逐张 describe 进上下文包 */
+export declare function changedCards(index: {
+    messages: readonly {
+        job: string;
+    }[];
+}, states: CardStates): {
+    job: string;
+    n: number;
+    file: CardStateFile;
+}[];
 export declare function addMessage(index: ConversationIndex, msg: ConversationMessage): ConversationIndex;
 /** 一次运行收尾:写 result / cost / kidText / artifacts,首次拿到 session 就记下 */
 export declare function applyRun(index: ConversationIndex, job: string, run: {
     transcript: Transcript;
     kidView: KidView;
-    agent: string;
+    runtime: string;
     artifacts?: string[];
+    audio?: string | null;
 }): ConversationIndex;