cotutor 0.2.0 → 0.3.0

package/dist/board/cards/docs.d.ts

@@ -0,0 +1,47 @@
+import { type CardPlace } from './index.ts';
+/** 本包自带的卡协议目录(仓库检出与 npm 安装都在包根 cards/) */
+export declare const PACKAGE_CARDS_DIR: string;
+export interface CardDoc {
+    kind: string;
+    /** 整份 card.md */
+    md: string;
+    /** 各栏目正文(按 ## 标题切;没有的栏目是空串) */
+    sections: Record<string, string>;
+    /** 标题行后面那句(「text — 一段字」) */
+    headline: string;
+}
+/** md 按 `## ` 切栏目;`# ` 标题行单独取 */
+export declare function splitSections(md: string): {
+    headline: string;
+    sections: Record<string, string>;
+};
+export declare function readCardDoc(kind: string, dir?: string): CardDoc;
+/** 能用在某处的种类的协议(按注册表的顺序);缺省板书——cotutor-board 技能只列这些;给了 only 就只要这几种(按老师裁,boardGuideFor) */
+export declare function cardDocs(dir?: string, place?: CardPlace, only?: readonly string[]): CardDoc[];
+/** 板书写法的手写部分(开头的规矩、一节的例子、作业照片),人改的就是这一篇;`{{卡的种类}}` 那一行由下面拼的各种卡替换 */
+export declare const BOARD_GUIDE_SOURCE = "\u677F\u4E66\u600E\u4E48\u5199.md";
+/**
+ * 给老师看的语法表(SKILL.md 的正文):cards/板书怎么写.md(剥掉给人看的注释,按卡裁段落)+ 各 card.md 的「是什么 / 写法 / 例子」。
+ * kinds 不给 = 板书的全部种类(出厂的 SKILL.md);给了就只拼这几种(按老师裁,boardGuideFor)。
+ */
+export declare function boardSyntaxDoc(dir?: string, kinds?: readonly string[]): string;
+/** 板书写法以外多带的几种卡(activity 要用、老师的清单里没有的),同板书写法里那一段的样子;递给老师前剥掉给人看的注释 */
+export declare function cardGuidesFor(kinds: readonly string[], dir?: string): string;
+/** 按老师裁的板书写法(递给老师的正文,同 boardGuideBody(SKILL.md) 的形状:没有 frontmatter、没有给人看的注释) */
+export declare function boardGuideFor(kinds: readonly string[], dir?: string): string;
+/** references/README.md:一行一种——名字、一句是什么、何时用;老师按需 @ 单张 */
+export declare function cardsIndexDoc(dir?: string): string;
+/** 技能名;目录 .agents/skills/cotutor-board/ */
+export declare const BOARD_SKILL = "cotutor-board";
+/** SKILL.md:frontmatter(name / description)+ 语法表;description 列出卡的种类,让模型不读正文也知道有哪几种 */
+export declare function boardSkillDoc(dir?: string): string;
+/** 技能目录的全部文件(相对技能根):SKILL.md + references/README.md + references/<kind>.md;scripts/gen-skills.ts 写进包根 skills/cotutor-board/,tests/skills.test.ts 断言入库的和它一致 */
+export declare function boardSkillFiles(dir?: string): Record<string, string>;
+/** 各种卡的结构样式(cards/<kind>/card.css)拼成一段,放在主题 css 前面(主题能盖) */
+export declare function cardsCss(dir?: string): string;
+/** 例子即测试用:md 里每个围栏 + 它前面的 expect 注释 */
+export declare function docExamples(md: string): {
+    tag: string;
+    body: string;
+    expect: Record<string, unknown> | null;
+}[];

package/dist/board/cards/docs.js

@@ -0,0 +1,152 @@
+/**
+ * 卡的协议文件:每种能力型卡在包根 cards/<kind>/ 下有 card.md(协议:是什么 / 何时用 / 写法 / 例子 / 反例 /
+ * 孩子看到什么 / 你会收回什么 / 状态的形状)与 card.css(这种卡的结构样式,只用主题变量)。
+ * md 是可以单独 @ 的文件:init / upgrade 出厂成 workspace 里的**一个技能** .agents/skills/cotutor-board/:SKILL.md = 语法表(frontmatter + 各 md 的「是什么 / 写法 / 例子」拼),references/<kind>.md 逐张协议,
+ * references/README.md 索引;老师按需 @ 单张。写盘的在 app/cli/skills.ts `writeBoardSkill`。
+ * 例子即测试:tests/cards-doc.test.ts 把每个 card.md 里的围栏喂 parseCard,`<!-- expect {…} -->` 注释是期望。
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CARD_KINDS, kindsFor } from "./index.js";
+import { stripHumanNotes } from "../../shared/human-notes.js";
+import { applyCardGuards } from "../card-guards.js";
+/** 本包自带的卡协议目录(仓库检出与 npm 安装都在包根 cards/) */
+export const PACKAGE_CARDS_DIR = fileURLToPath(new URL('../../../cards/', import.meta.url));
+/** md 按 `## ` 切栏目;`# ` 标题行单独取 */
+export function splitSections(md) {
+    const lines = md.split('\n');
+    // 标题行 = 第一个 ## 之前的那行 `# …`;栏目里的 `# 认边`(例子围栏里的)照收
+    let headline = '';
+    const sections = {};
+    let cur = null;
+    const buf = [];
+    const flush = () => {
+        if (cur !== null)
+            sections[cur] = buf.join('\n').trim();
+        buf.length = 0;
+    };
+    for (const l of lines) {
+        if (l.startsWith('## ')) {
+            flush();
+            cur = l.slice(3).trim();
+        }
+        else if (cur === null) {
+            if (!headline && l.startsWith('# '))
+                headline = l.slice(2).trim();
+        }
+        else
+            buf.push(l);
+    }
+    flush();
+    return { headline, sections };
+}
+export function readCardDoc(kind, dir = PACKAGE_CARDS_DIR) {
+    const md = readFileSync(join(dir, kind, 'card.md'), 'utf8');
+    const { headline, sections } = splitSections(md);
+    return { kind, md, sections, headline };
+}
+/** 能用在某处的种类的协议(按注册表的顺序);缺省板书——cotutor-board 技能只列这些;给了 only 就只要这几种(按老师裁,boardGuideFor) */
+export function cardDocs(dir = PACKAGE_CARDS_DIR, place = 'board', only) {
+    return kindsFor(place)
+        .filter((k) => !only || only.includes(k.name))
+        .map((k) => readCardDoc(k.name, dir));
+}
+/** 例子里的 `<!-- expect {…} -->` 注释:给老师看的版本要去掉 */
+const EXPECT_RE = /^\s*<!--\s*expect\b.*?-->\s*\n?/gm;
+/** 板书写法的手写部分(开头的规矩、一节的例子、作业照片),人改的就是这一篇;`{{卡的种类}}` 那一行由下面拼的各种卡替换 */
+export const BOARD_GUIDE_SOURCE = '板书怎么写.md';
+const KINDS_SLOT = /^\{\{卡的种类\}\}$/m;
+/**
+ * 给老师看的语法表(SKILL.md 的正文):cards/板书怎么写.md(剥掉给人看的注释,按卡裁段落)+ 各 card.md 的「是什么 / 写法 / 例子」。
+ * kinds 不给 = 板书的全部种类(出厂的 SKILL.md);给了就只拼这几种(按老师裁,boardGuideFor)。
+ */
+export function boardSyntaxDoc(dir = PACKAGE_CARDS_DIR, kinds) {
+    const all = kindsFor('board').map((k) => k.name);
+    const want = kinds ? all.filter((k) => kinds.includes(k)) : all;
+    const docs = cardDocs(dir, 'board', want).map(cardGuide).join('\n\n');
+    const guide = applyCardGuards(stripHumanNotes(readFileSync(join(dir, BOARD_GUIDE_SOURCE), 'utf8')), want);
+    if (!KINDS_SLOT.test(guide))
+        throw new Error(`cards/${BOARD_GUIDE_SOURCE} 里没有「{{卡的种类}}」那一行`);
+    return `${guide.replace(KINDS_SLOT, () => docs)}\n`;
+}
+/** 一种卡给老师看的那段:标题 + 是什么 / 写法 / 例子(去掉 expect);板书写法里「卡的种类」一节就是一张张拼的它 */
+function cardGuide(d) {
+    const parts = [`### ${d.headline}`, d.sections['是什么'], d.sections['写法'], d.sections['例子']?.replace(EXPECT_RE, '')].filter((x) => x && x.trim());
+    return parts.join('\n\n').trim();
+}
+/** 板书写法以外多带的几种卡(activity 要用、老师的清单里没有的),同板书写法里那一段的样子;递给老师前剥掉给人看的注释 */
+export function cardGuidesFor(kinds, dir = PACKAGE_CARDS_DIR) {
+    return stripHumanNotes(cardDocs(dir, 'board', kinds).map(cardGuide).join('\n\n'));
+}
+/** 按老师裁的板书写法(递给老师的正文,同 boardGuideBody(SKILL.md) 的形状:没有 frontmatter、没有给人看的注释) */
+export function boardGuideFor(kinds, dir = PACKAGE_CARDS_DIR) {
+    return stripHumanNotes(boardSyntaxDoc(dir, kinds));
+}
+/** references/README.md:一行一种——名字、一句是什么、何时用;老师按需 @ 单张 */
+export function cardsIndexDoc(dir = PACKAGE_CARDS_DIR) {
+    const rows = cardDocs(dir).map((d) => {
+        const what = (d.sections['是什么'] ?? '').split('\n').find((l) => l.trim()) ?? '';
+        const when = (d.sections['什么时候用 / 别用'] ?? '').split('\n').filter((l) => l.startsWith('- 用:')).map((l) => `\n  - 用在:${l.slice(4).trim()}`).join('');
+        return `- **${d.kind}**(${d.kind}.md)—— ${what}${when}`;
+    });
+    return `# 卡的种类(索引)
+
+每种卡一份协议:是什么、什么时候用 / 别用、写法、例子、反例、孩子看到什么、你会收回什么、状态的形状。讲解前只读需要的那一两张;总表在 ../SKILL.md。机器文件,init / upgrade 刷新。
+
+${rows.join('\n')}
+`;
+}
+/** 技能名;目录 .agents/skills/cotutor-board/ */
+export const BOARD_SKILL = 'cotutor-board';
+/** SKILL.md:frontmatter(name / description)+ 语法表;description 列出卡的种类,让模型不读正文也知道有哪几种 */
+export function boardSkillDoc(dir = PACKAGE_CARDS_DIR) {
+    const kinds = kindsFor('board').map((k) => k.name).join(' / ');
+    const description = `cotutor 的板书怎么写:讲稿一行一句,围栏是卡(种类:${kinds})。应用已经递给老师,老师不用读;家长查阅用。每种卡完整的协议在 references/<种类>.md。机器生成,源在 cotutor 仓的 cards/,别在这里改。`;
+    return `---\nname: ${BOARD_SKILL}\ndescription: ${description}\n---\n\n${boardSyntaxDoc(dir)}`;
+}
+/** 技能目录的全部文件(相对技能根):SKILL.md + references/README.md + references/<kind>.md;scripts/gen-skills.ts 写进包根 skills/cotutor-board/,tests/skills.test.ts 断言入库的和它一致 */
+export function boardSkillFiles(dir = PACKAGE_CARDS_DIR) {
+    const out = { 'SKILL.md': boardSkillDoc(dir), 'references/README.md': cardsIndexDoc(dir) };
+    for (const d of cardDocs(dir))
+        out[`references/${d.kind}.md`] = d.md;
+    return out;
+}
+/** 各种卡的结构样式(cards/<kind>/card.css)拼成一段,放在主题 css 前面(主题能盖) */
+export function cardsCss(dir = PACKAGE_CARDS_DIR) {
+    return CARD_KINDS.map((k) => {
+        try {
+            return `/* ---- ${k.name}(cards/${k.name}/card.css)---- */\n${readFileSync(join(dir, k.name, 'card.css'), 'utf8').trim()}`;
+        }
+        catch {
+            return '';
+        }
+    })
+        .filter(Boolean)
+        .join('\n\n');
+}
+/** 例子即测试用:md 里每个围栏 + 它前面的 expect 注释 */
+export function docExamples(md) {
+    const out = [];
+    const lines = md.split('\n');
+    let expect = null;
+    for (let i = 0; i < lines.length; i++) {
+        const l = lines[i];
+        const ex = /^<!--\s*expect\s+(\{.*\})\s*-->$/.exec(l.trim());
+        if (ex) {
+            expect = JSON.parse(ex[1]);
+            continue;
+        }
+        const open = /^```(.*)$/.exec(l);
+        if (open && !l.startsWith('````')) {
+            const body = [];
+            let j = i + 1;
+            for (; j < lines.length && !/^```\s*$/.test(lines[j]); j++)
+                body.push(lines[j]);
+            out.push({ tag: open[1].trim(), body: body.join('\n'), expect });
+            expect = null;
+            i = j;
+        }
+    }
+    return out;
+}

package/dist/{cards → board/cards}/image.js

@@ -12,6 +12,7 @@ export const ImagePropsSchema = z.object({
 export const IMAGE_EXT = /\.(png|jpe?g|webp|gif|svg)$/i;
 export const image = {
     name: 'image',
+    where: ['board', 'home'],
     props: ImagePropsSchema,
     parse(body) {
         const [src, ...rest] = bodyLines(body);
@@ -22,14 +23,4 @@ export const image = {
         const caption = rest.join('\n');
         return { src, ...(caption ? { caption } : {}) };
     },
-    doc: `### image — 图片
-
-第一行是图:workspace 里的相对路径(产物、孩子拍的照片,如 \`vault/照片/2026-09-10-作业.jpg\`)或 http(s) 地址;后面几行是图注。孩子点开能放大。
-
-\`\`\`\`
-\`\`\`image
-vault/照片/2026-09-10-作业.jpg
-你昨天写的这道题,看第二行。
-\`\`\`
-\`\`\`\``,
 };

package/dist/board/cards/index.d.ts

@@ -0,0 +1,62 @@
+import type { BoardCard, BoardSection } from '../presentation.ts';
+import type { CardKind, CardPlace } from './kind.ts';
+export { BUNDLE_ID_RE, type CardKind, type CardPlace } from './kind.ts';
+export { text, TEXT_STYLES, type TextProps, type TextStyle } from './text.ts';
+export { read, type ReadProps } from './read.ts';
+export { choice, type ChoiceProps } from './choice.ts';
+export { code, type CodeProps } from './code.ts';
+export { image, IMAGE_EXT, type ImageProps } from './image.ts';
+export { lecture, type LectureProps, type LectureState } from './lecture.ts';
+export { canvas, type CanvasProps, type CanvasState } from './canvas.ts';
+export { paint, PaintPropsSchema, PAINT_PANELS_MAX, type PaintCast, type PaintProps } from './paint.ts';
+export { tianzige, HAN, TIANZIGE_MAX, type TianzigeProps } from './tianzige.ts';
+export { word, wordChunks, WORD_MAX, WORD_MAX_WORDS, WORD_RE, type WordProps } from './word.ts';
+export { tutor, BUTTON_LABEL_MAX, TUTOR_BUTTONS_MAX, TutorButtonSchema, type TutorButton, type TutorProps } from './tutor.ts';
+export { dictation, dictationEmoji, dictationWordLang, DictationPropsSchema, DICTATION_EN_MAX, DICTATION_SAY_MAX, DICTATION_WORD_MAX, DICTATION_WORDS_MAX, EN_WORD_RE, type DictationLang, type DictationProps, type DictationWord } from './dictation.ts';
+/** 全部种类:先板书的十一种(注册表顺序即技能里的顺序),再首页专属的 */
+export declare const CARD_KINDS: readonly CardKind<any>[];
+export declare function cardKind(name: string): CardKind | undefined;
+/** 这种卡能不能用在这里(没写 where 的只板书) */
+export declare function usableIn(kind: Pick<CardKind, 'where'>, place: CardPlace): boolean;
+/** 能用在某处的种类(注册表顺序) */
+export declare function kindsFor(place: CardPlace): readonly CardKind<any>[];
+/**
+ * 这位老师的板书写法里讲哪几种卡(cotutor.json tutors.<老师>.cards,《卡片协议.md》「谁拿到哪些卡」):
+ * 没写 = null(全部,递出厂的 cotutor-board SKILL.md);写了 = 板书能用的、按注册表顺序,text 总在(写坏的卡退成它)。
+ */
+export declare function tutorCardKinds(cards: readonly string[] | undefined): string[] | null;
+export interface ParsedCard {
+    card: BoardCard;
+    /** 没解析成时的一句(家长视图转录里显示);孩子端什么也不报 */
+    warning?: string;
+    /** 没照标签解析成(退成了文字卡 / 代码卡);首页检查据此判「要改」 */
+    fallback?: boolean;
+}
+/**
+ * 围栏 → 卡。标签第一个词是 kind,其余是修饰;不认识的标签:板书里当代码卡原样显示,首页里退文字卡;
+ * 认识但正文解析不出、或这种卡不能用在这里(place)→ 文字卡显示原文 + warning。永不抛错。
+ */
+export declare function parseCard(tag: string, body: string, place?: CardPlace): ParsedCard;
+/** 孩子端的一节:每张卡过本种卡的 strip(答案不下发);不认识的 kind 原样;孩子自己的状态与已生成的资产照给 */
+export declare function stripSecrets(section: BoardSection): BoardSection;
+/** 一张卡的标题(舞台顶栏、给老师的描述里用):文字卡的 title / text,选择题的问题,其余第一段有字的,田字格的字,单词卡的词,听写卡的词表 */
+export declare function cardLabel(card: BoardCard): string;
+/** 这张卡要后台预生成的配音(文件名相对它的资产目录);没有的种类 → [] */
+export declare function cardAssets(card: BoardCard): {
+    file: string;
+    text: string;
+}[];
+export type CardStateResult = {
+    ok: true;
+    state: unknown;
+} | {
+    ok: false;
+    why: string;
+};
+/** 孩子端 PUT 上来的状态过本种卡的契约;这种卡没有状态、或不认识的 kind → 不收 */
+export declare function parseCardState(card: BoardCard, raw: unknown): CardStateResult;
+/**
+ * 给老师的一句:「choice「问题」 选了「B …」(答案:「…」)」。props 用索引里的(带答案),状态是孩子的;
+ * 没有 describe 的种类把状态原样 JSON。id 由调用方拼在前面(<job>/<n>)。
+ */
+export declare function describeCard(card: BoardCard, state: unknown): string;

package/dist/board/cards/index.js

@@ -0,0 +1,144 @@
+/**
+ * 卡的注册表:加一种卡 = 加一个文件 + 这里一行;解析器、语法表、孩子端剥秘密都从这里走。
+ * 页面那一半在 kid-page.ts(渲染)与 board/presentation.ts(标注落点),按 kind 名对上。协议文档与结构样式在包根 cards/<kind>/(src/board/cards/docs.ts)。
+ */
+import { z } from 'zod';
+import { canvas } from "./canvas.js";
+import { choice } from "./choice.js";
+import { code } from "./code.js";
+import { tianzige } from "./tianzige.js";
+import { word } from "./word.js";
+import { image } from "./image.js";
+import { read } from "./read.js";
+import { paint } from "./paint.js";
+import { photo } from "./photo.js";
+import { lecture } from "./lecture.js";
+import { text } from "./text.js";
+import { tutor } from "./tutor.js";
+import { dictation } from "./dictation.js";
+export { BUNDLE_ID_RE } from "./kind.js";
+export { text, TEXT_STYLES } from "./text.js";
+export { read } from "./read.js";
+export { choice } from "./choice.js";
+export { code } from "./code.js";
+export { image, IMAGE_EXT } from "./image.js";
+export { lecture } from "./lecture.js";
+export { canvas } from "./canvas.js";
+export { paint, PaintPropsSchema, PAINT_PANELS_MAX } from "./paint.js";
+export { tianzige, HAN, TIANZIGE_MAX } from "./tianzige.js";
+export { word, wordChunks, WORD_MAX, WORD_MAX_WORDS, WORD_RE } from "./word.js";
+export { tutor, BUTTON_LABEL_MAX, TUTOR_BUTTONS_MAX, TutorButtonSchema } from "./tutor.js";
+export { dictation, dictationEmoji, dictationWordLang, DictationPropsSchema, DICTATION_EN_MAX, DICTATION_SAY_MAX, DICTATION_WORD_MAX, DICTATION_WORDS_MAX, EN_WORD_RE } from "./dictation.js";
+/** 全部种类:先板书的十一种(注册表顺序即技能里的顺序),再首页专属的 */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const CARD_KINDS = [text, read, choice, image, tianzige, word, lecture, canvas, paint, photo, code, tutor, dictation];
+export function cardKind(name) {
+    return CARD_KINDS.find((k) => k.name === name);
+}
+/** 这种卡能不能用在这里(没写 where 的只板书) */
+export function usableIn(kind, place) {
+    return (kind.where ?? ['board']).includes(place);
+}
+/** 能用在某处的种类(注册表顺序) */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function kindsFor(place) {
+    return CARD_KINDS.filter((k) => usableIn(k, place));
+}
+/**
+ * 这位老师的板书写法里讲哪几种卡(cotutor.json tutors.<老师>.cards,《卡片协议.md》「谁拿到哪些卡」):
+ * 没写 = null(全部,递出厂的 cotutor-board SKILL.md);写了 = 板书能用的、按注册表顺序,text 总在(写坏的卡退成它)。
+ */
+export function tutorCardKinds(cards) {
+    if (!cards)
+        return null;
+    return kindsFor('board').map((k) => k.name).filter((k) => k === 'text' || cards.includes(k));
+}
+/** 正文是「字」的卡:老师把讲稿的 [词] 标注语法写进这些卡时,把括号剥掉(2026-09-11 真跑:孩子看到了「[直角边]」);choice 的 - [ ] / - [x] 不动 */
+const TEXTUAL = new Set(['text', 'read', 'choice', 'image', 'word', 'paint']);
+const MARK_IN_CARD = /\[([^\[\]\n]+)\]/g;
+function unmark(body) {
+    let had = false;
+    const out = body.replace(MARK_IN_CARD, (m, inner) => {
+        if (/^[ xX]$/.test(inner))
+            return m;
+        had = true;
+        return inner;
+    });
+    return { body: out, had };
+}
+/**
+ * 围栏 → 卡。标签第一个词是 kind,其余是修饰;不认识的标签:板书里当代码卡原样显示,首页里退文字卡;
+ * 认识但正文解析不出、或这种卡不能用在这里(place)→ 文字卡显示原文 + warning。永不抛错。
+ */
+export function parseCard(tag, body, place = 'board') {
+    const [name, ...mods] = tag.trim().split(/\s+/).filter(Boolean);
+    const asText = (why) => ({ card: { kind: 'text', props: { text: body.trim() || name || '…' } }, warning: why, fallback: true });
+    if (!name)
+        return place === 'board' ? { card: { kind: 'code', props: code.parse(body, []) } } : asText('围栏没写种类');
+    const kind = cardKind(name.toLowerCase());
+    if (!kind)
+        return place === 'board' ? { card: { kind: 'code', props: code.parse(body, [name]) } } : asText(`不认识的卡:${name}`);
+    if (!usableIn(kind, place))
+        return asText(place === 'board' ? `${name} 是首页的卡,板书里不能用` : `首页放不了 ${name} 卡(它要交给某位老师,只能在板书里)`);
+    const um = TEXTUAL.has(kind.name) ? unmark(body) : { body, had: false };
+    try {
+        const props = kind.props.parse(kind.parse(um.body, mods));
+        const notes = [um.had ? `卡里的方括号去掉了:${name} — [词] 标注只写在讲稿句里,不写在卡里` : null, kind.note?.(um.body, props) ?? null].filter((x) => Boolean(x));
+        return { card: { kind: kind.name, props }, ...(notes.length ? { warning: notes.join(';') } : {}) };
+    }
+    catch (err) {
+        const why = err instanceof z.ZodError ? err.issues.map((i) => `${i.path.join('.')}:${i.message}`).join(';') : err instanceof Error ? err.message : String(err);
+        return asText(`卡片没解析成:${name} — ${why}`);
+    }
+}
+/** 孩子端的一节:每张卡过本种卡的 strip(答案不下发);不认识的 kind 原样;孩子自己的状态与已生成的资产照给 */
+export function stripSecrets(section) {
+    return {
+        ...section,
+        cards: section.cards.map((c) => {
+            // 认不出的种类(删掉的卡:场景 10-07、填空 10-22):老对话里存下的退成一段字,只留它的那句,别的字段(答案、题面)不下发
+            const k = cardKind(c.kind);
+            if (!k)
+                return { ...c, kind: 'text', props: { text: typeof c.props.text === 'string' ? c.props.text : cardLabel(c) } };
+            return k.strip ? { ...c, props: k.strip(c.props) } : c;
+        }),
+    };
+}
+/** 一张卡的标题(舞台顶栏、给老师的描述里用):文字卡的 title / text,选择题的问题,其余第一段有字的,田字格的字,单词卡的词,听写卡的词表 */
+export function cardLabel(card) {
+    const p = card.props;
+    const s = (v) => (typeof v === 'string' ? v.trim() : '');
+    const first = s(p.title) || s(p.question) || s(p.show) || s(p.text) || s(p.caption) || s(p.prompt) || (Array.isArray(p.segments) ? s(p.segments[0]) : '') || s(p.chars) || s(p.word) || (Array.isArray(p.words) ? p.words.map((w) => s(w?.chars)).filter(Boolean).join('、') : '');
+    const cps = Array.from(first.replace(/\s+/g, ' '));
+    return cps.length > 40 ? `${cps.slice(0, 40).join('')}…` : cps.join('');
+}
+/** 这张卡要后台预生成的配音(文件名相对它的资产目录);没有的种类 → [] */
+export function cardAssets(card) {
+    const k = cardKind(card.kind);
+    if (!k?.assets)
+        return [];
+    const r = k.props.safeParse(card.props);
+    return r.success ? k.assets(r.data) : [];
+}
+/** 孩子端 PUT 上来的状态过本种卡的契约;这种卡没有状态、或不认识的 kind → 不收 */
+export function parseCardState(card, raw) {
+    const k = cardKind(card.kind);
+    if (!k?.state)
+        return { ok: false, why: `${card.kind} 卡没有状态` };
+    const r = k.state.safeParse(raw);
+    if (!r.success)
+        return { ok: false, why: r.error.issues.map((i) => `${i.path.join('.')}:${i.message}`).join(';') };
+    return { ok: true, state: r.data };
+}
+/**
+ * 给老师的一句:「choice「问题」 选了「B …」(答案:「…」)」。props 用索引里的(带答案),状态是孩子的;
+ * 没有 describe 的种类把状态原样 JSON。id 由调用方拼在前面(<job>/<n>)。
+ */
+export function describeCard(card, state) {
+    const k = cardKind(card.kind);
+    const head = `${card.kind}「${cardLabel(card)}」`;
+    if (!k?.describe || !k.state)
+        return `${head} ${JSON.stringify(state)}`;
+    const r = k.state.safeParse(state);
+    return `${head} ${r.success ? k.describe(card.props, r.data) : JSON.stringify(state)}`;
+}

package/dist/{cards → board/cards}/kind.d.ts

@@ -1,14 +1,20 @@
 /**
- * 一种卡的服务端定义(《板书卡片设计.md》§1):props 契约、围栏正文怎么解析、哪些字段不下发孩子端、给老师看的写法;
+ * 一种卡的服务端定义(见 docs/卡片协议.md):props 契约、围栏正文怎么解析、哪些字段不下发孩子端;给老师看的写法在包根 cards/<kind>/card.md(src/board/cards/docs.ts 读它);
  * 有交互的卡再加 state 契约(孩子在卡上做的事,PUT 进来先过它)与 describe(把 props + state 说成给老师看的一句,进上下文包)。
- * 页面那一半(紧凑态怎么画、舞台里怎么交互、标注落在哪些字上)在 kid-page.ts / kid-board.ts;两边靠 kind 名对上。
+ * 页面那一半(紧凑态怎么画、舞台里怎么交互、标注落在哪些字上)在 kid-page.ts / board/presentation.ts;两边靠 kind 名对上。
  */
 import type { z } from 'zod';
+/** 卡用在哪:板书(老师的回复)/ 首页(家长批准的那页) */
+export type CardPlace = 'board' | 'home';
 export interface CardKind<P = Record<string, unknown>, S = unknown> {
     name: string;
+    /** 能用在哪;缺省只板书。首页专属的卡(tutor 等)不进 cotutor-board 技能,老师写了退文字卡 */
+    where?: readonly CardPlace[];
     props: z.ZodType<P>;
     /** 围栏正文 + 标签后的修饰词 → props;抛错 = 没解析成(退成文字卡显示原文,家长视图报一行) */
     parse(body: string, mods: readonly string[]): P;
+    /** 解析成了、但正文有一部分没用上(田字格的拼音对不上字数):给家长视图的一句;没有 / null = 不报 */
+    note?(body: string, props: P): string | null;
     /** 剥掉不下发孩子端的字段(答案);没有 = 全给 */
     strip?(props: P): P;
     /** 孩子在卡上做的事的形状;没有 = 这种卡没有状态,PUT 一律 400 */
@@ -20,8 +26,8 @@ export interface CardKind<P = Record<string, unknown>, S = unknown> {
         file: string;
         text: string;
     }[];
-    /** 语法表里的一段:写法 + 例子(给老师看),由 boardSyntaxDoc 拼成 .cotutor/板书语法.md */
-    doc: string;
 }
+/** 课包 / 视频小课堂的 id(bundles/<id>/、lectures/<id>/):lecture 卡、画板的底、首页的小课堂按钮共用 */
+export declare const BUNDLE_ID_RE: RegExp;
 /** 围栏正文 → 非空行(各自 trim) */
 export declare function bodyLines(body: string): string[];

package/dist/board/cards/kind.js

@@ -0,0 +1,9 @@
+/** 课包 / 视频小课堂的 id(bundles/<id>/、lectures/<id>/):lecture 卡、画板的底、首页的小课堂按钮共用 */
+export const BUNDLE_ID_RE = /^[a-z0-9][a-z0-9-]{0,80}$/;
+/** 围栏正文 → 非空行(各自 trim) */
+export function bodyLines(body) {
+    return body
+        .split('\n')
+        .map((l) => l.trim())
+        .filter(Boolean);
+}

package/dist/board/cards/lecture.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 小课堂卡:老师答孩子时放课里的一段,不另讲一遍。正文第一行「<课包或视频的 id> 0:19-0:30」,第二行可以写一句给孩子的话。
+ * 拿现成的课包或视频(家长做的);时间照上下文包 lecture.lines 抄。
+ * 课名、真放的起止(对齐到段界,board/lecture.ts lectureRange)、能不能放(ready)、末帧停在 SVG 的哪一刻,都是服务端下发时从课包现算的快照(src/runtime/lecture.ts 的 enrichLectures)。
+ * 状态 = 那一段看完没;讲稿 [[play]] 锚到它:念到那句,铺满放那一段(课里原来的声音),放完停在末帧接着念。
+ */
+import { z } from 'zod';
+import { type CardKind } from './kind.ts';
+export declare const LecturePropsSchema: z.ZodObject<{
+    bundle: z.ZodString;
+    from: z.ZodOptional<z.ZodNumber>;
+    to: z.ZodOptional<z.ZodNumber>;
+    text: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    start: z.ZodOptional<z.ZodNumber>;
+    end: z.ZodOptional<z.ZodNumber>;
+    still: z.ZodOptional<z.ZodNumber>;
+    ready: z.ZodOptional<z.ZodBoolean>;
+    video: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type LectureProps = z.infer<typeof LecturePropsSchema>;
+export declare const LectureStateSchema: z.ZodObject<{
+    done: z.ZodBoolean;
+}, z.core.$strip>;
+export type LectureState = z.infer<typeof LectureStateSchema>;
+export declare const lecture: CardKind<LectureProps, LectureState>;

package/dist/board/cards/lecture.js

@@ -0,0 +1,62 @@
+/**
+ * 小课堂卡:老师答孩子时放课里的一段,不另讲一遍。正文第一行「<课包或视频的 id> 0:19-0:30」,第二行可以写一句给孩子的话。
+ * 拿现成的课包或视频(家长做的);时间照上下文包 lecture.lines 抄。
+ * 课名、真放的起止(对齐到段界,board/lecture.ts lectureRange)、能不能放(ready)、末帧停在 SVG 的哪一刻,都是服务端下发时从课包现算的快照(src/runtime/lecture.ts 的 enrichLectures)。
+ * 状态 = 那一段看完没;讲稿 [[play]] 锚到它:念到那句,铺满放那一段(课里原来的声音),放完停在末帧接着念。
+ */
+import { z } from 'zod';
+import { BUNDLE_ID_RE, bodyLines } from "./kind.js";
+import { clockLabel, parseClock } from "../lecture.js";
+export const LecturePropsSchema = z.object({
+    /** 课包 id(bundles/<id>/) */
+    bundle: z.string().regex(BUNDLE_ID_RE),
+    /** 老师写的起止(毫秒);不写止 = 起点那一段放完;都不写 = 整堂课 */
+    from: z.number().int().nonnegative().optional(),
+    to: z.number().int().nonnegative().optional(),
+    /** 老师在第二行写的一句(卡上标题下面一行) */
+    text: z.string().optional(),
+    /** 以下是下发时从课包算的快照 */
+    title: z.string().optional(),
+    /** 真放的起止(毫秒,对齐到段界) */
+    start: z.number().nonnegative().optional(),
+    end: z.number().nonnegative().optional(),
+    /** 末帧停在 SVG 的哪一刻(紧凑态缩略图) */
+    still: z.number().nonnegative().optional(),
+    /** 课包读得出来、起止对得上 */
+    ready: z.boolean().optional(),
+    /** 这一课是视频(lectures/<id>/video.mp4),不是课包 */
+    video: z.boolean().optional(),
+});
+export const LectureStateSchema = z.object({ done: z.boolean() });
+export const lecture = {
+    name: 'lecture',
+    props: LecturePropsSchema,
+    parse(body) {
+        const [first, ...rest] = bodyLines(body);
+        const [bundle, range, ...more] = (first ?? '').split(/\s+/).filter(Boolean);
+        if (!bundle)
+            throw new Error('第一行要是课包 id 和一段时间,照上下文包 lecture.source 与 lines 抄,如 2026-09-18-po13-jian-8 0:19-0:30');
+        if (!BUNDLE_ID_RE.test(bundle))
+            throw new Error(`课包 id 只能是小写字母、数字、连字符:${bundle}`);
+        if (more.length)
+            throw new Error(`第一行只写课包 id 和一段时间:${first}`);
+        let from;
+        let to;
+        if (range) {
+            const [a, b, ...c] = range.split(/[-–~]/);
+            from = parseClock(a) ?? undefined;
+            to = b === undefined ? undefined : (parseClock(b) ?? undefined);
+            if (from === undefined || (b !== undefined && to === undefined) || c.length)
+                throw new Error(`时间写成「分:秒-分:秒」,如 0:19-0:30:${range}`);
+            if (to !== undefined && to <= from)
+                throw new Error(`止要在起之后:${range}`);
+        }
+        const text = rest.join(' ').trim();
+        return { bundle, ...(from !== undefined ? { from } : {}), ...(to !== undefined ? { to } : {}), ...(text ? { text } : {}) };
+    },
+    state: LectureStateSchema,
+    describe(p, s) {
+        const at = p.from !== undefined ? `(${clockLabel(p.from)}${p.to !== undefined ? `–${clockLabel(p.to)}` : ''})` : '';
+        return s.done ? `看完了这一段${at}` : `还没看完这一段${at}`;
+    },
+};

package/dist/board/cards/paint.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 画图卡(kind 名 paint):老师把孩子说清楚的故事分好幅,应用交给百炼画成一张连环画(四格时 2×2,同练习册)。
+ * 正文:`题:` 题干、`词:` 词语宝库(出题版才有)、`角色:` 一行一个(每幅都画同一个样子靠它)、`1.` 起一幅一行。
+ * 画是这张卡的资产:一轮跑完后台画(src/scenes/paint/),图落在 .cards/<n>/paint.png;下发时由 enrichPaints 补上画好没有。孩子端没有错误:没画成就停在分幅那几句。
+ */
+import { z } from 'zod';
+import { type CardKind } from './kind.ts';
+/** 最多几幅:四格(2×2)是练习册的样子 */
+export declare const PAINT_PANELS_MAX = 4;
+/** 一幅最多几个字 */
+export declare const PAINT_PANEL_MAX = 80;
+/** 最多几个角色(一幅最多画三个,整个故事给四个) */
+export declare const PAINT_CAST_MAX = 4;
+/** 词语宝库最多几个词 */
+export declare const PAINT_WORDS_MAX = 8;
+export declare const PaintCastSchema: z.ZodObject<{
+    name: z.ZodString;
+    look: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PaintCast = z.infer<typeof PaintCastSchema>;
+export declare const PaintPropsSchema: z.ZodObject<{
+    panels: z.ZodArray<z.ZodString>;
+    cast: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        look: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    ask: z.ZodOptional<z.ZodString>;
+    words: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    pic: z.ZodOptional<z.ZodString>;
+    drawn: z.ZodOptional<z.ZodEnum<{
+        done: "done";
+        drawing: "drawing";
+        none: "none";
+    }>>;
+    note: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PaintProps = z.infer<typeof PaintPropsSchema>;
+export declare const paint: CardKind<PaintProps>;