cotutor 0.2.0 → 0.4.0

package/dist/cards/fill.js

@@ -1,64 +0,0 @@
-/** 填空卡:句子里 ___ 留空;答案行 `= 答案` 只有老师知道,不下发孩子端。状态 = 孩子按空的顺序填的字(舞台在步 5)。 */
-import { z } from 'zod';
-export const FillPropsSchema = z.object({
-    /** 句子,空一律写成 ___ */
-    text: z.string().min(1),
-    blanks: z.number().int().positive(),
-    /** 按空的顺序;老师没写就没有 */
-    answers: z.array(z.string()).optional(),
-});
-export const FillStateSchema = z.object({
-    /** 按空的顺序;没填的空是空串 */
-    answers: z.array(z.string().max(200)).max(20),
-});
-const BLANK = /_{2,}/g;
-const ANSWER = /^=\s*(.*)$/;
-export const fill = {
-    name: 'fill',
-    props: FillPropsSchema,
-    parse(body) {
-        const textLines = [];
-        const answers = [];
-        for (const raw of body.split('\n')) {
-            const line = raw.trim();
-            if (!line)
-                continue;
-            const m = ANSWER.exec(line);
-            if (m)
-                answers.push(m[1].trim());
-            else
-                textLines.push(line);
-        }
-        const text = textLines.join('\n').replace(BLANK, '___');
-        const blanks = (text.match(/___/g) ?? []).length;
-        if (!text)
-            throw new Error('没有句子');
-        if (!blanks)
-            throw new Error('句子里没有 ___ 留空');
-        return { text, blanks, ...(answers.length ? { answers } : {}) };
-    },
-    strip(p) {
-        const { answers: _drop, ...rest } = p;
-        return rest;
-    },
-    state: FillStateSchema,
-    describe(p, s) {
-        const parts = [];
-        for (let i = 0; i < p.blanks; i++) {
-            const got = (s.answers[i] ?? '').trim();
-            const key = p.answers?.[i];
-            parts.push(`第 ${i + 1} 空${got ? `填「${got}」` : '没填'}${key ? `(答案「${key}」)` : ''}`);
-        }
-        return parts.join(',');
-    },
-    doc: `### fill — 填空
-
-句子里用 \`___\` 留空,下一行 \`= 答案\`(多个空按顺序各一行)。答案孩子看不到;孩子填了、交给你,上下文包的 cards 段会写「第 1 空填「…」(答案「…」)」。
-
-\`\`\`\`
-\`\`\`fill
-三角形的面积等于底乘高再除以___。
-= 2
-\`\`\`
-\`\`\`\``,
-};

package/dist/cards/index.d.ts

@@ -1,48 +0,0 @@
-import type { BoardCard, BoardSection } from '../lib/kid-board.ts';
-import type { CardKind } from './kind.ts';
-export type { CardKind } 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 { fill, type FillProps } from './fill.ts';
-export { code, type CodeProps } from './code.ts';
-export { image, IMAGE_EXT, type ImageProps } from './image.ts';
-export { scene, BUNDLE_ID_RE, type SceneProps, type SceneState } from './scene.ts';
-export { canvas, type CanvasProps, type CanvasState } from './canvas.ts';
-export declare const CARD_KINDS: readonly CardKind<any>[];
-export declare function cardKind(name: string): CardKind | undefined;
-export interface ParsedCard {
-    card: BoardCard;
-    /** 没解析成时的一句(家长视图转录里显示);孩子端什么也不报 */
-    warning?: string;
-}
-/**
- * 围栏 → 卡。标签第一个词是 kind,其余是修饰;不认识的标签当代码卡原样显示;
- * 认识但正文解析不出 → 文字卡显示原文 + warning。永不抛错。
- */
-export declare function parseCard(tag: string, body: string): 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;
-/** 给老师看的语法表(出厂到 workspace 的 .cotutor/板书语法.md;从各种卡的 doc 拼出来,不手写) */
-export declare function boardSyntaxDoc(): string;

package/dist/cards/index.js

@@ -1,115 +0,0 @@
-/**
- * 卡的注册表:加一种卡 = 加一个文件 + 这里一行;解析器、语法表、孩子端剥秘密都从这里走。
- * 页面那一半在 kid-page.ts(渲染)与 kid-board.ts(标注落点),按 kind 名对上。
- */
-import { z } from 'zod';
-import { canvas } from "./canvas.js";
-import { choice } from "./choice.js";
-import { code } from "./code.js";
-import { fill } from "./fill.js";
-import { image } from "./image.js";
-import { read } from "./read.js";
-import { scene } from "./scene.js";
-import { text } from "./text.js";
-export { text, TEXT_STYLES } from "./text.js";
-export { read } from "./read.js";
-export { choice } from "./choice.js";
-export { fill } from "./fill.js";
-export { code } from "./code.js";
-export { image, IMAGE_EXT } from "./image.js";
-export { scene, BUNDLE_ID_RE } from "./scene.js";
-export { canvas } from "./canvas.js";
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export const CARD_KINDS = [text, read, choice, fill, image, scene, canvas, code];
-export function cardKind(name) {
-    return CARD_KINDS.find((k) => k.name === name);
-}
-/**
- * 围栏 → 卡。标签第一个词是 kind,其余是修饰;不认识的标签当代码卡原样显示;
- * 认识但正文解析不出 → 文字卡显示原文 + warning。永不抛错。
- */
-export function parseCard(tag, body) {
-    const [name, ...mods] = tag.trim().split(/\s+/).filter(Boolean);
-    if (!name)
-        return { card: { kind: 'code', props: code.parse(body, []) } };
-    const kind = cardKind(name.toLowerCase());
-    if (!kind)
-        return { card: { kind: 'code', props: code.parse(body, [name]) } };
-    try {
-        const props = kind.props.parse(kind.parse(body, mods));
-        return { card: { kind: kind.name, props } };
-    }
-    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 { card: { kind: 'text', props: { text: body.trim() || name } }, warning: `卡片没解析成:${name} — ${why}` };
-    }
-}
-/** 孩子端的一节:每张卡过本种卡的 strip(答案不下发);不认识的 kind 原样;孩子自己的状态与已生成的资产照给 */
-export function stripSecrets(section) {
-    return {
-        ...section,
-        cards: section.cards.map((c) => {
-            const k = cardKind(c.kind);
-            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.text) || s(p.caption) || s(p.prompt) || (Array.isArray(p.segments) ? s(p.segments[0]) : '');
-    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)}`;
-}
-/** 给老师看的语法表(出厂到 workspace 的 .cotutor/板书语法.md;从各种卡的 doc 拼出来,不手写) */
-export function boardSyntaxDoc() {
-    const kinds = CARD_KINDS.map((k) => k.doc.trim()).join('\n\n');
-    return `# 板书怎么写
-
-回复正文就是孩子看到的板书,只有两种东西:
-
-- **普通段落 = 你说的话。** 一行一句,每句会被念出来、显示在字幕行,所以不要写标题、列表、粗体、括号注释。句子里用方括号标出要在板上敲的词,如「这叫[底]」,那个词要在某张卡上出现。末句写成问句就停下等孩子。
-- **围栏 = 板上的卡。** 围栏的语言标签是卡的种类,后面的词是修饰;正文按各种卡的写法。卡写在讲它的那句话前面,卡与话交错。不认识的标签当代码卡原样显示;正文写得不对的卡退成一段文字,孩子端不会报错。
-
-一节 4–8 张卡、6–12 句话;一次只讲一个想法,讲完就问。随口问答就一两句话,没有卡。**板书写完就停**:最后一个字是问孩子的那句,后面不要再补总结、不要再用工具——孩子看到的是你这轮最后一段话,再补一句板书就丢了。
-
-孩子在卡上做的事(选了、填了)会在下一条消息的上下文包里以 \`cards:\` 段告诉你,一张卡一行(卡的编号、种类、标题、做了什么、答案);孩子只交答案没说话时消息正文是「(交了答案,没说话)」。孩子看到的卡上没有对错,对错由你口头说。上下文包里 \`focus.card\` 是孩子发消息时正开着的那张卡。
-
-对家长说的话、要拍板的事、要转交的事,用「## 家长」「## 待裁量」(question: 一句话;options: 列表)「## 转交」三个段放在正文末尾,孩子看不到;板书到第一个「## 」为止。
-
-## 卡的种类
-
-${kinds}
-`;
-}

package/dist/cards/kind.js

@@ -1,7 +0,0 @@
-/** 围栏正文 → 非空行(各自 trim) */
-export function bodyLines(body) {
-    return body
-        .split('\n')
-        .map((l) => l.trim())
-        .filter(Boolean);
-}

package/dist/cards/scene.d.ts

@@ -1,24 +0,0 @@
-/**
- * 场景卡(《drawtell接入与场景卡.md》§2):正文是课包 id,课包在 workspace 的 bundles/<id>/(drawtell build 的产物,scene-maker 作业出)。
- * 解析器只认 id;题面、步数、有没有做好(ready)、缩略图是服务端下发时从课包现读的快照(src/server/scene-props.ts),
- * 所以课包落地后卡自己变成可播,不用老师再说一遍。状态 = 孩子看到第几步、看完没;紧凑态「N 步 ▷」,舞台是 drawtell 播放器。
- */
-import { z } from 'zod';
-import { type CardKind } from './kind.ts';
-export declare const BUNDLE_ID_RE: RegExp;
-export declare const ScenePropsSchema: z.ZodObject<{
-    bundle: z.ZodString;
-    text: z.ZodOptional<z.ZodString>;
-    title: z.ZodOptional<z.ZodString>;
-    problem: z.ZodOptional<z.ZodString>;
-    steps: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    ready: z.ZodOptional<z.ZodBoolean>;
-    thumb: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export type SceneProps = z.infer<typeof ScenePropsSchema>;
-export declare const SceneStateSchema: z.ZodObject<{
-    step: z.ZodNumber;
-    done: z.ZodBoolean;
-}, z.core.$strip>;
-export type SceneState = z.infer<typeof SceneStateSchema>;
-export declare const scene: CardKind<SceneProps, SceneState>;

package/dist/cards/scene.js

@@ -1,67 +0,0 @@
-/**
- * 场景卡(《drawtell接入与场景卡.md》§2):正文是课包 id,课包在 workspace 的 bundles/<id>/(drawtell build 的产物,scene-maker 作业出)。
- * 解析器只认 id;题面、步数、有没有做好(ready)、缩略图是服务端下发时从课包现读的快照(src/server/scene-props.ts),
- * 所以课包落地后卡自己变成可播,不用老师再说一遍。状态 = 孩子看到第几步、看完没;紧凑态「N 步 ▷」,舞台是 drawtell 播放器。
- */
-import { z } from 'zod';
-import { bodyLines } from "./kind.js";
-export const BUNDLE_ID_RE = /^[a-z0-9][a-z0-9-]{0,80}$/;
-export const ScenePropsSchema = z.object({
-    /** 课包 id(bundles/<id>/) */
-    bundle: z.string().regex(BUNDLE_ID_RE),
-    /** 老师在 id 后面写的一句(课包还没到时孩子看到它) */
-    text: z.string().optional(),
-    /** 以下是下发时从课包读的快照;没到就没有 */
-    title: z.string().optional(),
-    problem: z.string().optional(),
-    /** 每步讲稿 */
-    steps: z.array(z.string()).optional(),
-    /** 课包在不在(scene.json + manifest.json 都在) */
-    ready: z.boolean().optional(),
-    /** 终帧缩略图(相对 workspace 根,/api/kid/image?p= 供图);没截过就没有 */
-    thumb: z.string().optional(),
-});
-export const SceneStateSchema = z.object({
-    /** 看到第几步(1 起;0 = 还没开始) */
-    step: z.number().int().nonnegative(),
-    done: z.boolean(),
-});
-export const scene = {
-    name: 'scene',
-    props: ScenePropsSchema,
-    parse(body) {
-        const [first, ...rest] = bodyLines(body);
-        if (!first)
-            throw new Error('第一行要是课包 id');
-        if (first.startsWith('{'))
-            throw new Error('行内 JSON 场景还没接(下一步);先写课包 id');
-        if (!BUNDLE_ID_RE.test(first))
-            throw new Error(`课包 id 只能是小写字母、数字、连字符:${first}`);
-        const text = rest.join(' ').trim();
-        return { bundle: first, ...(text ? { text } : {}) };
-    },
-    state: SceneStateSchema,
-    describe(p, s) {
-        const total = p.steps?.length ?? 0;
-        if (!p.ready)
-            return '课包还没做好,孩子看不了';
-        if (s.done)
-            return `看完了(共 ${total} 步)`;
-        if (s.step <= 0)
-            return '还没开始看';
-        return `看到第 ${s.step} 步(共 ${total} 步)停在气口`;
-    },
-    doc: `### scene — 讲解动画(课包)
-
-正文第一行是课包 id(bundles/<id>/,由 scene-maker 作业做出来;id 形如 \`2026-09-10-guilv\`),第二行可以写一句给孩子的话。
-课包没做好之前孩子看到「图还在路上」,做好了卡自己变成可播,舞台里是逐笔画出来的讲解,自带讲稿与声音。
-讲作业题、要画图才讲得清的题用它:回复里放这张卡 + 一句「我去把图画出来」,同时「## 转交」给 scene-maker(to: scene-maker;why: 题面与讲法要点;refs: 课包 id)。
-讲稿里 \`[[play]]\` 锚到它,念到那句就把动画铺满播,播完接着念下一句。一天最多起两个作业(policy scenes.dailyMax)。
-
-\`\`\`\`
-\`\`\`scene
-2026-09-10-guilv
-我去把这道题画出来,画好了我们一起看。
-\`\`\`
-\`\`\`\``,
-};

package/dist/cards/text.d.ts

@@ -1,18 +0,0 @@
-/** 文字卡:一段字;样式是修饰词(cover / note / quote / formula / step),不占种类。 */
-import { z } from 'zod';
-import type { CardKind } from './kind.ts';
-export declare const TEXT_STYLES: readonly ["cover", "note", "quote", "formula", "step"];
-export type TextStyle = (typeof TEXT_STYLES)[number];
-export declare const TextPropsSchema: z.ZodObject<{
-    style: z.ZodOptional<z.ZodEnum<{
-        step: "step";
-        cover: "cover";
-        note: "note";
-        formula: "formula";
-        quote: "quote";
-    }>>;
-    title: z.ZodOptional<z.ZodString>;
-    text: z.ZodString;
-}, z.core.$strip>;
-export type TextProps = z.infer<typeof TextPropsSchema>;
-export declare const text: CardKind<TextProps>;

package/dist/cards/text.js

@@ -1,41 +0,0 @@
-/** 文字卡:一段字;样式是修饰词(cover / note / quote / formula / step),不占种类。 */
-import { z } from 'zod';
-export const TEXT_STYLES = ['cover', 'note', 'quote', 'formula', 'step'];
-export const TextPropsSchema = z.object({
-    style: z.enum(TEXT_STYLES).optional(),
-    /** cover 的标题 / step 的名字 */
-    title: z.string().optional(),
-    /** 正文;cover 时是副标题(可空) */
-    text: z.string(),
-});
-export const text = {
-    name: 'text',
-    props: TextPropsSchema,
-    parse(body, mods) {
-        const style = mods.map((m) => m.toLowerCase()).find((m) => TEXT_STYLES.includes(m));
-        const trimmed = body.replace(/^\s*\n/, '').trimEnd();
-        if (!trimmed.trim())
-            throw new Error('正文是空的');
-        if (style === 'cover' || style === 'step') {
-            const nl = trimmed.indexOf('\n');
-            const title = (nl < 0 ? trimmed : trimmed.slice(0, nl)).trim();
-            const rest = nl < 0 ? '' : trimmed.slice(nl + 1).trim();
-            return { style, title, text: rest };
-        }
-        return { ...(style ? { style } : {}), text: trimmed.trim() };
-    },
-    doc: `### text — 一段字
-
-\`\`\`text\` 后可加一个修饰词定样子:\`cover\`(封面:第一行标题,第二行副标题)、\`step\`(一步:第一行是这步的名字,下面是内容)、\`formula\`(算式,单独一行)、\`note\`(一句要记住的话)、\`quote\`(引一句原文);不加修饰就是普通一段。
-
-\`\`\`\`
-\`\`\`text cover
-三角形的面积
-两个一样的三角形拼成一个平行四边形
-\`\`\`
-
-\`\`\`text formula
-三角形面积 = 底 × 高 ÷ 2
-\`\`\`
-\`\`\`\``,
-};

package/dist/cli/cert.d.ts

@@ -1,7 +0,0 @@
-export interface CertResult {
-    cert: string;
-    key: string;
-    hosts: string[];
-    caRoot: string;
-}
-export declare function makeCert(extraHosts?: string[]): Promise<CertResult>;

package/dist/cli/cert.js

@@ -1,36 +0,0 @@
-/**
- * cotutor cert:用 mkcert 给这台机器签一张证书到 ~/.config/cotutor/certs/(cert.pem + key.pem),serve 看到就走 HTTPS。
- * 为什么要:iPad Safari 的录音 / 语音识别只在安全上下文里给;局域网 IP 不是 localhost,得自签。
- * 为什么放机器级而不是 workspace:签的是本机名与局域网 IP,与孩子无关;多个 workspace 共用一张,IP 变了只重签一次(2026-09-09 拍板)。
- * 主机名 = 本机名、本机名.local、所有局域网 IPv4、localhost、127.0.0.1,再加 --host 给的。已有证书就覆盖(证书可再生)。不需要 workspace。
- */
-import { execFile } from 'node:child_process';
-import { mkdir } from 'node:fs/promises';
-import { hostname } from 'node:os';
-import { join } from 'node:path';
-import { promisify } from 'node:util';
-import { lanAddresses } from "./serve.js";
-import { USER_CERT_DIR, UsageError } from "./workspace.js";
-const execFileP = promisify(execFile);
-export async function makeCert(extraHosts = []) {
-    let caRoot;
-    try {
-        caRoot = (await execFileP('mkcert', ['-CAROOT'], { timeout: 8000 })).stdout.trim();
-    }
-    catch {
-        throw new UsageError('PATH 里没有 mkcert。装:brew install mkcert && mkcert -install(在 Mac 上信任一次根证书);iPad 端见 cert 命令输出的提示。');
-    }
-    const host = hostname();
-    const hosts = [...new Set([host, host.endsWith('.local') ? host : `${host}.local`, ...lanAddresses(), 'localhost', '127.0.0.1', ...extraHosts])];
-    const dir = USER_CERT_DIR;
-    await mkdir(dir, { recursive: true });
-    const cert = join(dir, 'cert.pem');
-    const key = join(dir, 'key.pem');
-    try {
-        await execFileP('mkcert', ['-cert-file', cert, '-key-file', key, ...hosts], { timeout: 60_000 });
-    }
-    catch (err) {
-        throw new UsageError(`mkcert 签证书失败:${err instanceof Error ? err.message : String(err)}\n先跑 mkcert -install,再重试。`);
-    }
-    return { cert, key, hosts, caRoot };
-}

package/dist/cli/doctor.d.ts

@@ -1,22 +0,0 @@
-import { type ResolveOptions, type RootSource } from './workspace.ts';
-export interface DoctorCheck {
-    name: string;
-    ok: boolean;
-    required: boolean;
-    detail: string;
-    fix?: string;
-}
-export interface DoctorReport {
-    ok: boolean;
-    root: string | null;
-    source: RootSource | null;
-    checks: DoctorCheck[];
-}
-/** 运行时的 CLI 名(run[0] 的 basename):决定链在 .claude 还是 .qwen 下 */
-export declare function runtimeCli(run: readonly string[]): string;
-/** 已知的环境坑,从 CLI 的输出里认出来给修复命令(错误信息即修复指南) */
-export declare function explainLlmFailure(text: string, runtime: readonly string[]): string;
-export declare function doctorWorkspace(override?: string, opts?: ResolveOptions & {
-    probeEnv?: boolean;
-    live?: boolean;
-}): Promise<DoctorReport>;