cotutor 0.2.0 → 0.3.0

package/dist/scenes/talk/list.js

@@ -0,0 +1,88 @@
+/**
+ * 照片 → 口语单:交给 qwen3.8-omni-flash(兼容接口,不想)读出今天学的词和句,各带中文。
+ * 只读印刷体(2026-10-10 实测:印刷稳、手写不稳);读出来的家长要看一眼改,孩子只拿改过的。
+ * 这里是口语课这个场景的规则(提示词、怎么解析、单词卡的那两样);看图的请求在 src/media/vision.ts(key:omni 只有百炼按量),由路由那层交进来。
+ */
+import { word as wordCard } from "../../board/cards/word.js";
+export const LIST_TIMEOUT_MS = 40_000;
+const MAX_WORDS = 12;
+const MAX_SENTENCES = 8;
+export const PROMPT = `这是家长拍的一页小学英语课本或练习册。把这一页上**印刷的**英文单词和英文句子读出来,给孩子跟读和口语练习用:
+- words:单词或短语(最多 ${MAX_WORDS} 个),每个带中文意思;再带两样给单词卡用:emoji——能画出来的东西配一个,抽象的词(like、the)不配;split——自然拼读分段,用 - 隔开(ap-ple、sh-ee-p、c-a-t),拼起来要和单词一模一样;
+- sentences:完整的英文句子(最多 ${MAX_SENTENCES} 句),每句带中文意思;
+- 只要印刷的,手写的不要;题号、页码、栏目名不要;拼音、音标不要;
+- 这一页没有英文就两个都空。
+只回一个 JSON 对象,形如 {"words":[{"en":"red","zh":"红色","emoji":"🔴","split":"r-e-d"}],"sentences":[{"en":"It's a red car.","zh":"这是一辆红色的车。"}]},不要别的字。`;
+/**
+ * 口语单的一个词 → 单词卡要的 emoji 与分段:拼成单词卡的正文过 cards/word 的 parse,
+ * 分段拼不回这个词就丢分段、emoji 不是 emoji 就丢——和老师写错时一个下场;词本身写不进四线三格(带标点、整句)两样都不要
+ */
+export function wordCardOf(en, emoji, split) {
+    const em = typeof emoji === 'string' ? emoji.trim().slice(0, 16) : '';
+    const sp = typeof split === 'string' ? split.trim() : '';
+    try {
+        const p = wordCard.parse(`${em} ${en}\n${sp}`, []);
+        if (p.word !== en)
+            return {};
+        return { ...(p.emoji ? { emoji: p.emoji } : {}), ...(p.chunks ? { chunks: p.chunks } : {}) };
+    }
+    catch {
+        return {};
+    }
+}
+/** 模型回的字 → 口语单;去掉围栏、找到第一个 {…};形状不对回 null */
+export function parseList(text) {
+    const body = text.replace(/```[a-z]*\n?/gi, '').trim();
+    const start = body.indexOf('{');
+    const end = body.lastIndexOf('}');
+    if (start < 0 || end <= start)
+        return null;
+    let v;
+    try {
+        v = JSON.parse(body.slice(start, end + 1));
+    }
+    catch {
+        return null;
+    }
+    if (typeof v !== 'object' || v === null)
+        return null;
+    const pick = (arr, max, card) => {
+        if (arr === undefined || arr === null)
+            return [];
+        if (!Array.isArray(arr))
+            return null;
+        const out = [];
+        for (const x of arr) {
+            if (typeof x !== 'object' || x === null)
+                continue;
+            const en = String(x.en ?? '').replace(/\s+/g, ' ').trim();
+            const zh = String(x.zh ?? '').replace(/\s+/g, ' ').trim();
+            if (!en || en.length > 120)
+                continue;
+            if (out.some((o) => o.en.toLowerCase() === en.toLowerCase()))
+                continue;
+            out.push(card ? { en, zh, ...wordCardOf(en, x.emoji, x.split) } : { en, zh });
+            if (out.length >= max)
+                break;
+        }
+        return out;
+    };
+    const words = pick(v.words, MAX_WORDS, true);
+    const sentences = pick(v.sentences, MAX_SENTENCES, false);
+    if (!words || !sentences)
+        return null;
+    return { words, sentences };
+}
+/** 读一张照片(look = 看图的请求,src/media/vision.ts 的 lookAt);不抛,出错回 {ok: false} */
+export async function readListWith(look, photo, opts = {}) {
+    const t0 = Date.now();
+    const ms = () => Date.now() - t0;
+    const model = opts.model ?? 'qwen3.8-omni-flash';
+    const r = await look({ image: photo, prompt: PROMPT, model, params: { modalities: ['text'], reasoning_effort: 'none' }, timeoutMs: opts.timeoutMs ?? LIST_TIMEOUT_MS, env: opts.env, endpoint: opts.endpoint });
+    if (!r.ok)
+        return { ok: false, error: r.error, ms: ms() };
+    const list = parseList(r.text);
+    if (!list)
+        return { ok: false, error: 'bad_json', ms: ms() };
+    return { ok: true, list, model, ms: ms() };
+}

package/dist/scenes/talk/store.d.ts

@@ -0,0 +1,27 @@
+import type { TalkList } from './list.ts';
+export declare const ID_RE: RegExp;
+/** draft = 还在改;ready = 改好了、交给老师了(「接着上」用它) */
+export type TalkStatus = 'draft' | 'ready';
+export interface TalkMeta {
+    id: string;
+    createdAt: string;
+    status: TalkStatus;
+    /** 照片文件名(目录里);没拍 = null */
+    photo: string | null;
+    list: TalkList;
+    /** 口语单从哪来:omni 读的 / 家长手填 / 还没有;读失败记原因 */
+    listBy: 'omni' | 'parent' | null;
+    listError?: string;
+    listMs?: number;
+}
+export declare const rootOf: (wsRoot: string) => string;
+export declare const dirOf: (wsRoot: string, id: string) => string;
+export declare const writeJson: (file: string, v: unknown) => Promise<void>;
+export declare function newId(root: string, now: Date): string;
+/** 开一次:目录 + talk.json(口语单先空着);照片有就落盘 */
+export declare function createTalk(root: string, now: Date, photo: Buffer | null): Promise<TalkMeta>;
+export declare const readMeta: (root: string, id: string) => Promise<TalkMeta | null>;
+export declare const writeMeta: (root: string, meta: TalkMeta) => Promise<void>;
+/** 全部,新的在前 */
+export declare function listTalks(root: string): Promise<TalkMeta[]>;
+export declare const deleteTalk: (root: string, id: string) => Promise<void>;

package/dist/scenes/talk/store.js

@@ -0,0 +1,61 @@
+/**
+ * 口语课的数据:workspace/talk/<id>/,一次一个目录。不进对话索引、不写 vault。
+ * 口语课页只拍照、改口语单,上课在英语老师的实时页(src/runtime/talk-run.ts 读这里的 talk.json,那一课的录像在那个话题里)。
+ *
+ *   talk.json   口语单(读出来的 + 改过的)、状态
+ *   photo.jpg   拍的那页
+ */
+import { existsSync } from 'node:fs';
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export const ID_RE = /^\d{4}-\d{2}-\d{2}-\d{4}(?:-\d{1,2})?$/;
+export const rootOf = (wsRoot) => join(wsRoot, 'talk');
+export const dirOf = (wsRoot, id) => join(rootOf(wsRoot), id);
+async function readJson(file) {
+    try {
+        return JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export const writeJson = (file, v) => writeFile(file, `${JSON.stringify(v, null, 2)}\n`);
+const pad = (n) => String(n).padStart(2, '0');
+export function newId(root, now) {
+    const base = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}`;
+    let id = base;
+    for (let k = 2; existsSync(dirOf(root, id)); k++)
+        id = `${base}-${k}`;
+    return id;
+}
+/** 开一次:目录 + talk.json(口语单先空着);照片有就落盘 */
+export async function createTalk(root, now, photo) {
+    const id = newId(root, now);
+    const dir = dirOf(root, id);
+    await mkdir(dir, { recursive: true });
+    if (photo)
+        await writeFile(join(dir, 'photo.jpg'), photo);
+    const meta = { id, createdAt: now.toISOString(), status: 'draft', photo: photo ? 'photo.jpg' : null, list: { words: [], sentences: [] }, listBy: null };
+    await writeJson(join(dir, 'talk.json'), meta);
+    return meta;
+}
+export const readMeta = (root, id) => readJson(join(dirOf(root, id), 'talk.json'));
+export const writeMeta = (root, meta) => writeJson(join(dirOf(root, meta.id), 'talk.json'), meta);
+/** 全部,新的在前 */
+export async function listTalks(root) {
+    let names = [];
+    try {
+        names = (await readdir(rootOf(root))).filter((n) => ID_RE.test(n));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const n of names.sort().reverse()) {
+        const m = await readMeta(root, n);
+        if (m)
+            out.push(m);
+    }
+    return out;
+}
+export const deleteTalk = (root, id) => rm(dirOf(root, id), { recursive: true, force: true });

package/dist/scenes/talk/warmup.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 跟读还是对老师说的:说出了记号里的词(「under under 在下面」也算);或四个英文词以内、没有中文(「Boss!」);
+ * 或三个汉字以内、没有英文(你先说时答的「鸭子」、学鸭子叫的「嘎嘎嘎」)。其余(「那我们直接打电话吧」「我不想读」)是对老师说的
+ */
+export declare function echoKind(text: string, word: string): 'said' | 'talk';
+/** 一拍:跟哪个词、是不是你先说、怎么样(说了 / 没开口 / 是对老师说的)、转写、念完到开口几毫秒、说出了记号里几成的词 */
+export interface WarmBeat {
+    word: string;
+    say: boolean;
+    outcome: 'said' | 'silent' | 'talk';
+    text?: string;
+    startMs?: number;
+    hit?: number;
+}
+/** 摸底,一拍一行(给脑看;家长那几句由脑写在尾巴里) */
+export declare function warmLines(beats: readonly WarmBeat[]): string[];

package/dist/scenes/talk/warmup.js

@@ -0,0 +1,39 @@
+/**
+ * 热身:讲稿 [[echo 词]] / [[say 词]] 那句念完,孩子说的是跟读(往下一拍)还是对老师说的(交给脑);
+ * 每拍记一条,拼成摸底交给脑(上下文包 live.warmup)。纯函数。
+ * 比的是转写的字:百炼的转写会往对的词上靠,所以摸底只说明开没开口、说出了哪些词、自己说不说得出,不说明发音。
+ */
+import { coverage, wordsOf } from "./en-words.js";
+const CJK = /[\u4e00-\u9fff]/g;
+const HAS_CJK = /[\u4e00-\u9fff]/;
+/**
+ * 跟读还是对老师说的:说出了记号里的词(「under under 在下面」也算);或四个英文词以内、没有中文(「Boss!」);
+ * 或三个汉字以内、没有英文(你先说时答的「鸭子」、学鸭子叫的「嘎嘎嘎」)。其余(「那我们直接打电话吧」「我不想读」)是对老师说的
+ */
+export function echoKind(text, word) {
+    if (word && coverage(word, text) > 0)
+        return 'said';
+    const en = wordsOf(text).length;
+    const zh = (text.match(CJK) ?? []).length;
+    if (!zh && en >= 1 && en <= 4)
+        return 'said';
+    if (!en && zh >= 1 && zh <= 3)
+        return 'said';
+    return 'talk';
+}
+const secs = (ms) => `${(ms / 1000).toFixed(1)} 秒`;
+/** 摸底,一拍一行(给脑看;家长那几句由脑写在尾巴里) */
+export function warmLines(beats) {
+    return beats.map((b) => {
+        const head = `${b.say ? '自己说' : '跟'} ${b.word || '(没写词)'}:`;
+        if (b.outcome === 'silent')
+            return `${head}没开口`;
+        if (b.outcome === 'talk')
+            return `${head}没跟,对你说「${b.text ?? ''}」`;
+        const n = new Set(wordsOf(b.word)).size;
+        const got = n > 1 && b.hit !== undefined ? `,说出 ${Math.round(b.hit * n)}/${n} 个词` : n === 1 && b.hit === 0 ? `(转写里没有 ${b.word})` : '';
+        const zh = HAS_CJK.test(b.text ?? '') ? ',带中文' : '';
+        const fast = b.startMs !== undefined ? `,开口 ${secs(b.startMs)}` : '';
+        return `${head}说了「${b.text ?? ''}」${got}${zh}${fast}`;
+    });
+}

package/dist/schema/activity.d.ts

@@ -0,0 +1,149 @@
+/**
+ * activity 文件:孩子从首页一个按钮进去的一种做法。一个 activity 一个文件,归一位老师,
+ * 放在老师的家 `agents/<老师>/activities/<名>.md`(仓里在 grades/grade-<n>/ 下同一个相对位置,init 拷进去,hash 记 shipped.json)。
+ *
+ * 头上平铺 `name` / `description` / `cards`(这个 activity 要用的卡,空格隔开);正文按 `## ` 节分读者,标题就是读者:
+ *   ## 家长填的       ```参数    一行一个:`名: 类型[,可空][,缺省 X][,A 到 B] —— 说明`
+ *   ## 应用算的       ```应用算  一行一个:`名: 类型 —— 说明`(名字是应用会算的,见 ACTIVITY_STATE)
+ *   ## 应用拦的       ```应用拦  一行一条:`规则 —— 说明`(规则是应用认得的,见 ACTIVITY_GATES)
+ *   ## 老师怎么带     给有脸的老师;参数不插值,只用 `{{有 名}}` … `{{/有}}` 裁段
+ *   ## <工具人>收到什么  ```<工具人> 一段模板,`{{插槽}}` 由应用填;```<工具人>不要 可选
+ * 别的节只给人看,应用不读。这里是解析出来的形状;解析与检查在 src/runtime/activity.ts。
+ */
+import { z } from 'zod';
+/** 家长填的参数能是哪几种 */
+export declare const ACTIVITY_PARAM_TYPES: readonly ["字", "词表", "数", "日期", "课包"];
+export type ActivityParamType = (typeof ACTIVITY_PARAM_TYPES)[number];
+/** 应用会算的值(名 → 类型);activity 文件「应用算的」只能列这里有的 */
+export declare const ACTIVITY_STATE: Readonly<Record<string, ActivityParamType>>;
+/** 应用认得的拦法(规则名 → 一句话);判断在 src/runtime/activity.ts gatePasses,画图前由 src/runtime/activity-state.ts 接上。activity 文件「应用拦的」只能列这里有的 */
+export declare const ACTIVITY_GATES: Readonly<Record<string, string>>;
+/** 工具人模板里的插槽 `{{名}}` */
+export declare const ACTIVITY_SLOT: RegExp;
+/** 工具人的模板填插槽;没给的插槽填空,填完连续空行并成一行 */
+export declare function fillSlots(template: string, values: Readonly<Record<string, string>>): string;
+/** 工具人与它认得的插槽(都要在模板里出现) */
+export declare const ACTIVITY_TOOLS: Readonly<Record<string, {
+    slots: readonly string[];
+}>>;
+/**
+ * 不起老师的会话、按钮进一页的 activity(头上 `page:`):名字、音色、牌还是那位老师的。
+ * dictation = 中文听写页,dictation-en = 英文单词听写页(四线三格)
+ */
+export declare const ACTIVITY_PAGES: Readonly<Record<string, string>>;
+/** 应用认的节标题;工具人那节是 `<工具人>收到什么` */
+export declare const ACTIVITY_SECTIONS: {
+    readonly params: "家长填的";
+    readonly state: "应用算的";
+    readonly gates: "应用拦的";
+    readonly tutor: "老师怎么带";
+};
+export declare const ACTIVITY_TOOL_SECTION_RE: RegExp;
+/** 首页按钮下面已经占用的行名,参数不能叫这些 */
+export declare const ACTIVITY_RESERVED_PARAMS: readonly ["讲法", "留到"];
+/** 小课堂按钮没写 `activity:` 时,看完照这位老师的这个 activity 聊 */
+export declare const LECTURE_ACTIVITY = "\u5C0F\u8BFE\u5802";
+export declare const ActivityParamSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        字: "字";
+        词表: "词表";
+        数: "数";
+        日期: "日期";
+        课包: "课包";
+    }>;
+    optional: z.ZodBoolean;
+    default: z.ZodOptional<z.ZodString>;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    note: z.ZodOptional<z.ZodString>;
+    line: z.ZodNumber;
+}, z.core.$strip>;
+export type ActivityParam = z.infer<typeof ActivityParamSchema>;
+export declare const ActivityStateSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        字: "字";
+        词表: "词表";
+        数: "数";
+        日期: "日期";
+        课包: "课包";
+    }>;
+    note: z.ZodOptional<z.ZodString>;
+    line: z.ZodNumber;
+}, z.core.$strip>;
+export type ActivityState = z.infer<typeof ActivityStateSchema>;
+export declare const ActivityGateSchema: z.ZodObject<{
+    rule: z.ZodString;
+    note: z.ZodOptional<z.ZodString>;
+    line: z.ZodNumber;
+}, z.core.$strip>;
+export type ActivityGate = z.infer<typeof ActivityGateSchema>;
+export declare const ActivityToolSchema: z.ZodObject<{
+    tool: z.ZodString;
+    prompt: z.ZodString;
+    negative: z.ZodOptional<z.ZodString>;
+    line: z.ZodNumber;
+    promptLine: z.ZodNumber;
+}, z.core.$strip>;
+export type ActivityTool = z.infer<typeof ActivityToolSchema>;
+export declare const ActivitySchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    cards: z.ZodArray<z.ZodString>;
+    params: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            字: "字";
+            词表: "词表";
+            数: "数";
+            日期: "日期";
+            课包: "课包";
+        }>;
+        optional: z.ZodBoolean;
+        default: z.ZodOptional<z.ZodString>;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        note: z.ZodOptional<z.ZodString>;
+        line: z.ZodNumber;
+    }, z.core.$strip>>;
+    state: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            字: "字";
+            词表: "词表";
+            数: "数";
+            日期: "日期";
+            课包: "课包";
+        }>;
+        note: z.ZodOptional<z.ZodString>;
+        line: z.ZodNumber;
+    }, z.core.$strip>>;
+    gates: z.ZodArray<z.ZodObject<{
+        rule: z.ZodString;
+        note: z.ZodOptional<z.ZodString>;
+        line: z.ZodNumber;
+    }, z.core.$strip>>;
+    page: z.ZodOptional<z.ZodString>;
+    tutor: z.ZodNullable<z.ZodObject<{
+        text: z.ZodString;
+        line: z.ZodNumber;
+    }, z.core.$strip>>;
+    tools: z.ZodArray<z.ZodObject<{
+        tool: z.ZodString;
+        prompt: z.ZodString;
+        negative: z.ZodOptional<z.ZodString>;
+        line: z.ZodNumber;
+        promptLine: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Activity = z.infer<typeof ActivitySchema>;
+/** 参数与应用算的值:词表是一串词,数是整数,别的是一段字 */
+export declare const ActivityValueSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodArray<z.ZodString>]>;
+export type ActivityValue = z.infer<typeof ActivityValueSchema>;
+/** 一个话题是从哪个 activity 起的:名字与孩子点的那一刻的参数(补了缺省);记在话题第一条消息上,整个话题都用这一份 */
+export declare const ActivityRunSchema: z.ZodObject<{
+    name: z.ZodString;
+    params: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodArray<z.ZodString>]>>;
+}, z.core.$strip>;
+export type ActivityRun = z.infer<typeof ActivityRunSchema>;

package/dist/schema/activity.js

@@ -0,0 +1,113 @@
+/**
+ * activity 文件:孩子从首页一个按钮进去的一种做法。一个 activity 一个文件,归一位老师,
+ * 放在老师的家 `agents/<老师>/activities/<名>.md`(仓里在 grades/grade-<n>/ 下同一个相对位置,init 拷进去,hash 记 shipped.json)。
+ *
+ * 头上平铺 `name` / `description` / `cards`(这个 activity 要用的卡,空格隔开);正文按 `## ` 节分读者,标题就是读者:
+ *   ## 家长填的       ```参数    一行一个:`名: 类型[,可空][,缺省 X][,A 到 B] —— 说明`
+ *   ## 应用算的       ```应用算  一行一个:`名: 类型 —— 说明`(名字是应用会算的,见 ACTIVITY_STATE)
+ *   ## 应用拦的       ```应用拦  一行一条:`规则 —— 说明`(规则是应用认得的,见 ACTIVITY_GATES)
+ *   ## 老师怎么带     给有脸的老师;参数不插值,只用 `{{有 名}}` … `{{/有}}` 裁段
+ *   ## <工具人>收到什么  ```<工具人> 一段模板,`{{插槽}}` 由应用填;```<工具人>不要 可选
+ * 别的节只给人看,应用不读。这里是解析出来的形状;解析与检查在 src/runtime/activity.ts。
+ */
+import { z } from 'zod';
+/** 家长填的参数能是哪几种 */
+export const ACTIVITY_PARAM_TYPES = ['字', '词表', '数', '日期', '课包'];
+/** 应用会算的值(名 → 类型);activity 文件「应用算的」只能列这里有的 */
+export const ACTIVITY_STATE = {
+    /** 这个话题还能画几张:参数「最多画」减已画;没填最多画 = 不限,不写(src/runtime/activity-state.ts) */
+    还能画: '数',
+    /** 上一张画图卡没画的原因(「应用拦的」哪一条没过);画了就是空的 */
+    缺: '字',
+};
+/** 应用认得的拦法(规则名 → 一句话);判断在 src/runtime/activity.ts gatePasses,画图前由 src/runtime/activity-state.ts 接上。activity 文件「应用拦的」只能列这里有的 */
+export const ACTIVITY_GATES = {
+    连说过一遍: '话题里有一张三行以上的 read 卡,孩子在它后面开过口',
+    还能画: '还能画大于 0;不限时照过',
+};
+/** 工具人模板里的插槽 `{{名}}` */
+export const ACTIVITY_SLOT = /\{\{([^{}\s]+)\}\}/g;
+/** 工具人的模板填插槽;没给的插槽填空,填完连续空行并成一行 */
+export function fillSlots(template, values) {
+    return template
+        .replace(ACTIVITY_SLOT, (_, name) => values[name] ?? '')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+/** 工具人与它认得的插槽(都要在模板里出现) */
+export const ACTIVITY_TOOLS = {
+    画家: { slots: ['版式', '角色', '分幅'] },
+    /** 听写的拍照认词(src/scenes/dictation/recognize.ts):格式 = 回什么格式,应用接(FORMAT / FORMAT_EN) */
+    认字: { slots: ['格式'] },
+};
+/**
+ * 不起老师的会话、按钮进一页的 activity(头上 `page:`):名字、音色、牌还是那位老师的。
+ * dictation = 中文听写页,dictation-en = 英文单词听写页(四线三格)
+ */
+export const ACTIVITY_PAGES = {
+    dictation: '中文听写页 /dictation',
+    'dictation-en': '英文单词听写页 /dictation?lang=en',
+};
+/** 应用认的节标题;工具人那节是 `<工具人>收到什么` */
+export const ACTIVITY_SECTIONS = { params: '家长填的', state: '应用算的', gates: '应用拦的', tutor: '老师怎么带' };
+export const ACTIVITY_TOOL_SECTION_RE = /^(.+?)收到什么$/;
+/** 首页按钮下面已经占用的行名,参数不能叫这些 */
+export const ACTIVITY_RESERVED_PARAMS = ['讲法', '留到'];
+/** 小课堂按钮没写 `activity:` 时,看完照这位老师的这个 activity 聊 */
+export const LECTURE_ACTIVITY = '小课堂';
+export const ActivityParamSchema = z.object({
+    name: z.string().min(1),
+    type: z.enum(ACTIVITY_PARAM_TYPES),
+    /** 可空:首页按钮可以不填 */
+    optional: z.boolean(),
+    /** 缺省值(原文) */
+    default: z.string().optional(),
+    /** 数的范围(含两头) */
+    min: z.number().int().optional(),
+    max: z.number().int().optional(),
+    note: z.string().optional(),
+    line: z.number().int(),
+});
+export const ActivityStateSchema = z.object({
+    name: z.string().min(1),
+    type: z.enum(ACTIVITY_PARAM_TYPES),
+    note: z.string().optional(),
+    line: z.number().int(),
+});
+export const ActivityGateSchema = z.object({
+    rule: z.string().min(1),
+    note: z.string().optional(),
+    line: z.number().int(),
+});
+export const ActivityToolSchema = z.object({
+    tool: z.string().min(1),
+    /** ```<工具人> 围栏里的模板,原样(插槽没填) */
+    prompt: z.string(),
+    /** ```<工具人>不要 围栏,一行或几行拼成一段 */
+    negative: z.string().optional(),
+    /** 那节标题的行号 */
+    line: z.number().int(),
+    /** 模板第一行的行号 */
+    promptLine: z.number().int(),
+});
+export const ActivitySchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    /** 头上 `cards:` 写的卡(原文,检查时对注册表) */
+    cards: z.array(z.string()),
+    params: z.array(ActivityParamSchema),
+    state: z.array(ActivityStateSchema),
+    gates: z.array(ActivityGateSchema),
+    /** 头上的 `page:`:不起老师、进这一页(见 ACTIVITY_PAGES);没写 = 起老师 */
+    page: z.string().optional(),
+    /** 「老师怎么带」那节的原文(没剥注释、没裁);没有这节就是 null(这个 activity 不起老师,如听写) */
+    tutor: z.object({ text: z.string(), line: z.number().int() }).nullable(),
+    tools: z.array(ActivityToolSchema),
+});
+/** 参数与应用算的值:词表是一串词,数是整数,别的是一段字 */
+export const ActivityValueSchema = z.union([z.string(), z.number(), z.array(z.string())]);
+/** 一个话题是从哪个 activity 起的:名字与孩子点的那一刻的参数(补了缺省);记在话题第一条消息上,整个话题都用这一份 */
+export const ActivityRunSchema = z.object({
+    name: z.string().min(1),
+    params: z.record(z.string(), ActivityValueSchema),
+});