cotutor 0.1.0 → 0.2.0

package/dist/schema/config.d.ts

@@ -1,8 +1,8 @@
 /**
  * cotutor.json:每个 workspace 一份,一孩一 workspace。承接 drawtell.json 的做法——
- * `paths` 角色映射 + `agents` 的 {run, resume} 命令模板——再加老师表与政策。
+ * `paths` 角色映射 + `runtimes` 的 {run, resume} 命令模板——再加老师表与政策。
  * 字段归属铁律:老师的 .md 文件里只有 name / description / maxTurns / permissionMode / memory + 正文;
- * 人设(display / avatar / voice)、政策、开关全在这里。助教团页只改本文件,永不改链进来的定义文件。
+ * 人设(display / avatar / voice)、政策、开关全在这里。老师团页只改本文件,永不改链进来的定义文件。
  */
 import { z } from 'zod';
 /** 回复形式阶梯(《cotutor产品规划.md》):L0 确定性资源 / L1 口答 / L2 快卡 / L3 补讲 / L4 整包 */
@@ -24,6 +24,13 @@ export declare const PolicySchema: z.ZodObject<{
         recent: z.ZodNumber;
         planLines: z.ZodNumber;
     }, z.core.$strip>;
+    board: z.ZodEnum<{
+        auto: "auto";
+        off: "off";
+    }>;
+    scenes: z.ZodObject<{
+        dailyMax: z.ZodNumber;
+    }, z.core.$strip>;
 }, z.core.$strip>;
 export type Policy = z.infer<typeof PolicySchema>;
 /** 政策补丁:老师条目与 policyDefaults 都是补丁,逐层盖在 POLICY_DEFAULTS 上 */
@@ -43,13 +50,20 @@ export declare const PolicyPatchSchema: z.ZodObject<{
         recent: z.ZodOptional<z.ZodNumber>;
         planLines: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
+    board: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        off: "off";
+    }>>;
+    scenes: z.ZodOptional<z.ZodObject<{
+        dailyMax: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type PolicyPatch = z.infer<typeof PolicyPatchSchema>;
 /** 2026-09-08 拍板的缺省:60 字、30 条/日、3 次重生、验收关、上下文包各 10 */
 export declare const POLICY_DEFAULTS: Policy;
 /** agent 名:与 .claude/agents/<name>.md 的 frontmatter name 一致,小写字母数字连字符 */
 export declare const AGENT_NAME_RE: RegExp;
-export declare const TeacherSchema: z.ZodObject<{
+export declare const TutorSchema: z.ZodObject<{
     display: z.ZodString;
     subject: z.ZodOptional<z.ZodString>;
     avatar: z.ZodOptional<z.ZodString>;
@@ -72,25 +86,42 @@ export declare const TeacherSchema: z.ZodObject<{
             recent: z.ZodOptional<z.ZodNumber>;
             planLines: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
+        board: z.ZodOptional<z.ZodEnum<{
+            auto: "auto";
+            off: "off";
+        }>>;
+        scenes: z.ZodOptional<z.ZodObject<{
+            dailyMax: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
+    runtime: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-export type Teacher = z.infer<typeof TeacherSchema>;
+export type Tutor = z.infer<typeof TutorSchema>;
 /**
- * 运行时预设:一个 CLI 一组 {run, resume} 命令模板。占位符:
+ * 运行时:一个 CLI 一组 {run, resume} 命令模板。占位符:
  * {agent} 老师名 / {agentBody} 老师文件正文(给没有 --agent 的 CLI 塞系统提示)/ {prompt} 消息 / {session} 会话 id。
- * 政策旋钮(预算、轮数、模型)写进模板,换 agent 只换预设。
+ * 政策旋钮(预算、轮数、模型)写进模板,换 agent 只换运行时。
  */
-export declare const AgentPresetSchema: z.ZodObject<{
+export declare const RuntimeSchema: z.ZodObject<{
     run: z.ZodArray<z.ZodString>;
     resume: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
-export type AgentPreset = z.infer<typeof AgentPresetSchema>;
-export declare const AgentsSchema: z.ZodObject<{
+export type Runtime = z.infer<typeof RuntimeSchema>;
+export declare const RuntimesSchema: z.ZodObject<{
     default: z.ZodString;
 }, z.core.$catchall<z.ZodObject<{
     run: z.ZodArray<z.ZodString>;
     resume: z.ZodArray<z.ZodString>;
 }, z.core.$strip>>>;
+/**
+ * 配音运行时:老师说完,应用把 kidText 合成一段音频给孩子端播。占位符 {text} {voice} {out}(输出文件路径)。
+ * 命令要把音频写到 {out};没配、没装、失败 → 这条没有音频,孩子端退回浏览器自带的合成声。
+ */
+export declare const TtsSchema: z.ZodObject<{
+    say: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type Tts = z.infer<typeof TtsSchema>;
+export declare const TTS_DEFAULT: Tts;
 /** paths 里 CLI 认识的角色;其余角色原样保留给应用层。vault 侧角色相对 vault 解析,没配 vault 就相对 workspace 根 */
 export declare const PATH_ROLES: readonly ["vault", "photos", "diary", "plans", "profile", "timetable"];
 export type PathRole = (typeof PATH_ROLES)[number];
@@ -105,6 +136,10 @@ export declare const CotutorConfigSchema: z.ZodObject<{
     }, z.core.$strip>;
     server: z.ZodDefault<z.ZodObject<{
         port: z.ZodDefault<z.ZodNumber>;
+        https: z.ZodOptional<z.ZodObject<{
+            cert: z.ZodString;
+            key: z.ZodString;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
     paths: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
     policyDefaults: z.ZodDefault<z.ZodObject<{
@@ -123,8 +158,15 @@ export declare const CotutorConfigSchema: z.ZodObject<{
             recent: z.ZodOptional<z.ZodNumber>;
             planLines: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
+        board: z.ZodOptional<z.ZodEnum<{
+            auto: "auto";
+            off: "off";
+        }>>;
+        scenes: z.ZodOptional<z.ZodObject<{
+            dailyMax: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
-    teachers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+    tutors: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         display: z.ZodString;
         subject: z.ZodOptional<z.ZodString>;
         avatar: z.ZodOptional<z.ZodString>;
@@ -147,19 +189,30 @@ export declare const CotutorConfigSchema: z.ZodObject<{
                 recent: z.ZodOptional<z.ZodNumber>;
                 planLines: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
+            board: z.ZodOptional<z.ZodEnum<{
+                auto: "auto";
+                off: "off";
+            }>>;
+            scenes: z.ZodOptional<z.ZodObject<{
+                dailyMax: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
         }, z.core.$strip>>;
+        runtime: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
-    agents: z.ZodObject<{
+    runtimes: z.ZodObject<{
         default: z.ZodString;
     }, z.core.$catchall<z.ZodObject<{
         run: z.ZodArray<z.ZodString>;
         resume: z.ZodArray<z.ZodString>;
     }, z.core.$strip>>>;
+    tts: z.ZodDefault<z.ZodObject<{
+        say: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type CotutorConfig = z.infer<typeof CotutorConfigSchema>;
-/** 老师的有效政策 = POLICY_DEFAULTS ← policyDefaults ← teachers[name].policy */
-export declare function resolvePolicy(config: CotutorConfig, teacher: string): Policy;
-export interface TeacherView {
+/** 老师的有效政策 = POLICY_DEFAULTS ← policyDefaults ← tutors[name].policy */
+export declare function resolvePolicy(config: CotutorConfig, tutor: string): Policy;
+export interface TutorView {
     name: string;
     display: string;
     subject?: string;
@@ -170,13 +223,18 @@ export interface TeacherView {
     policy: Policy;
 }
 /** 老师列表(带有效政策);kidOnly = 只要孩子端能看到的(enabled 且不 hidden) */
-export declare function listTeachers(config: CotutorConfig, opts?: {
+export declare function listTutors(config: CotutorConfig, opts?: {
     kidOnly?: boolean;
-}): TeacherView[];
-/** 预设模板填占位符;{agentBody} 只在给了正文时替换,否则原样留着(doctor 会报) */
-export declare function fillPreset(argv: readonly string[], vars: {
+}): TutorView[];
+/** 运行时模板填占位符;{agentBody} 只在给了正文时替换,否则原样留着(doctor 会报) */
+export declare function fillRuntime(argv: readonly string[], vars: {
     agent: string;
     prompt: string;
     session?: string;
     agentBody?: string;
 }): string[];
+export declare function fillTts(argv: readonly string[], vars: {
+    text: string;
+    voice: string;
+    out: string;
+}): string[];

package/dist/schema/config.js

@@ -1,25 +1,29 @@
 /**
  * cotutor.json:每个 workspace 一份,一孩一 workspace。承接 drawtell.json 的做法——
- * `paths` 角色映射 + `agents` 的 {run, resume} 命令模板——再加老师表与政策。
+ * `paths` 角色映射 + `runtimes` 的 {run, resume} 命令模板——再加老师表与政策。
  * 字段归属铁律:老师的 .md 文件里只有 name / description / maxTurns / permissionMode / memory + 正文;
- * 人设(display / avatar / voice)、政策、开关全在这里。助教团页只改本文件,永不改链进来的定义文件。
+ * 人设(display / avatar / voice)、政策、开关全在这里。老师团页只改本文件,永不改链进来的定义文件。
  */
 import { z } from 'zod';
 /** 回复形式阶梯(《cotutor产品规划.md》):L0 确定性资源 / L1 口答 / L2 快卡 / L3 补讲 / L4 整包 */
 export const REPLY_FORMS = ['L0', 'L1', 'L2', 'L3', 'L4'];
 export const PolicySchema = z.object({
-    /** 老师单条回复给孩子看的字数上限;超出截断并改走 L3(《cotutor契约草案.md》§4) */
-    replyMaxChars: z.number().int().positive(),
+    /** 老师说给孩子听的每一句的字数上限;超出在句末截断(《cotutor契约草案.md》§4;板书后按句算) */
+    replyMaxChars: z.number().int().positive().describe('老师说给孩子听的每一句的字数上限(板书讲稿一行一句,按句截);超出在句末截断'),
     /** 每孩每日消息上限;超限老师头像灰掉 */
-    dailyMessages: z.number().int().nonnegative(),
+    dailyMessages: z.number().int().nonnegative().describe('孩子每日可发消息条数(家长发的不算);到了头像灰'),
     /** 每日重生上限 */
-    dailyRegen: z.number().int().nonnegative(),
+    dailyRegen: z.number().int().nonnegative().describe('每日重生上限'),
     /** 验收开关:false = 产物直接给孩子(缺省);true = 先经家长验收 */
-    reviewGate: z.boolean(),
+    reviewGate: z.boolean().describe('验收开关:true = 产物先经家长验收才给孩子;false = 直接给(缺省)'),
     /** 这位老师可用的回复形式 */
-    forms: z.array(z.enum(REPLY_FORMS)),
+    forms: z.array(z.enum(REPLY_FORMS)).describe('这位老师可用的回复形式:L0 确定性资源 / L1 口答 / L2 快卡 / L3 补讲 / L4 整包'),
     /** 上下文包的两个数:最近观察条数、计划行数 */
     contextPack: z.object({ recent: z.number().int().nonnegative(), planLines: z.number().int().nonnegative() }),
+    /** 板书开关:auto = 老师判断要不要出卡(缺省);off = 只说话不出卡 */
+    board: z.enum(['auto', 'off']).describe('板书:auto = 讲题讲概念时老师出卡(缺省);off = 只说话不出卡'),
+    /** 场景作业(scene-maker 做课包,$3–5 / 10–15 分钟一个):每天最多起几个;配在 scene-maker 身上或 policyDefaults */
+    scenes: z.object({ dailyMax: z.number().int().nonnegative().describe('每天最多起几个场景作业(一个 ≈ 一轮问答的 30 倍费用)') }),
 });
 /** 政策补丁:老师条目与 policyDefaults 都是补丁,逐层盖在 POLICY_DEFAULTS 上 */
 export const PolicyPatchSchema = z.object({
@@ -29,6 +33,8 @@ export const PolicyPatchSchema = z.object({
     reviewGate: PolicySchema.shape.reviewGate.optional(),
     forms: PolicySchema.shape.forms.optional(),
     contextPack: z.object({ recent: z.number().int().nonnegative().optional(), planLines: z.number().int().nonnegative().optional() }).optional(),
+    board: PolicySchema.shape.board.optional(),
+    scenes: z.object({ dailyMax: z.number().int().nonnegative().optional() }).optional(),
 });
 /** 2026-09-08 拍板的缺省:60 字、30 条/日、3 次重生、验收关、上下文包各 10 */
 export const POLICY_DEFAULTS = {
@@ -38,29 +44,39 @@ export const POLICY_DEFAULTS = {
     reviewGate: false,
     forms: ['L0', 'L1', 'L3', 'L4'],
     contextPack: { recent: 10, planLines: 10 },
+    board: 'auto',
+    scenes: { dailyMax: 2 },
 };
 /** agent 名:与 .claude/agents/<name>.md 的 frontmatter name 一致,小写字母数字连字符 */
 export const AGENT_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
-export const TeacherSchema = z.object({
+export const TutorSchema = z.object({
     /** 显示名(孩子端头像下的字、计划文件的 H2 标题) */
-    display: z.string().min(1),
-    subject: z.string().optional(),
+    display: z.string().min(1).describe('显示名:孩子端头像下的字,计划文件的 H2 标题'),
+    subject: z.string().optional().describe('学科:与课程表的学科列、观察的 subject 对齐即归到这位老师'),
     /** 头像:一个 emoji 或图片相对路径 */
-    avatar: z.string().optional(),
+    avatar: z.string().optional().describe('头像:一个 emoji'),
     /** voxtell 音色 id(2026-09-08 拍板);没有 = 用 voxtell 缺省 */
-    voice: z.string().optional(),
-    enabled: z.boolean().default(true),
+    voice: z.string().optional().describe('voxtell 音色 id(voxtell voices 可查);不配就不配音,孩子端用浏览器的声'),
+    enabled: z.boolean().default(true).describe('开关:false 时两端都不见'),
     /** 孩子端不露(规划老师、记账员这类) */
-    hidden: z.boolean().default(false),
-    policy: PolicyPatchSchema.optional(),
+    hidden: z.boolean().default(false).describe('孩子端不露(规划老师这类只和家长打交道的)'),
+    policy: PolicyPatchSchema.optional().describe('覆盖 policyDefaults 的字段,没写的继承'),
+    /** 这位老师用哪个运行时(runtimes 里的键);不配用 runtimes.default。scene-maker 这种要更大预算与时限的配一个自己的 */
+    runtime: z.string().optional().describe('这位老师用的运行时(runtimes 里的键;不配用 default)——预算、时限不同的老师配自己的'),
 });
 /**
- * 运行时预设:一个 CLI 一组 {run, resume} 命令模板。占位符:
+ * 运行时:一个 CLI 一组 {run, resume} 命令模板。占位符:
  * {agent} 老师名 / {agentBody} 老师文件正文(给没有 --agent 的 CLI 塞系统提示)/ {prompt} 消息 / {session} 会话 id。
- * 政策旋钮(预算、轮数、模型)写进模板,换 agent 只换预设。
+ * 政策旋钮(预算、轮数、模型)写进模板,换 agent 只换运行时。
  */
-export const AgentPresetSchema = z.object({ run: z.array(z.string()).min(1), resume: z.array(z.string()).min(1) });
-export const AgentsSchema = z.object({ default: z.string().min(1) }).catchall(AgentPresetSchema);
+export const RuntimeSchema = z.object({ run: z.array(z.string()).min(1), resume: z.array(z.string()).min(1) });
+export const RuntimesSchema = z.object({ default: z.string().min(1) }).catchall(RuntimeSchema);
+/**
+ * 配音运行时:老师说完,应用把 kidText 合成一段音频给孩子端播。占位符 {text} {voice} {out}(输出文件路径)。
+ * 命令要把音频写到 {out};没配、没装、失败 → 这条没有音频,孩子端退回浏览器自带的合成声。
+ */
+export const TtsSchema = z.object({ say: z.array(z.string()).min(1) });
+export const TTS_DEFAULT = { say: ['voxtell', 'say', '{text}', '--voice', '{voice}', '--json', '-o', '{out}'] };
 /** paths 里 CLI 认识的角色;其余角色原样保留给应用层。vault 侧角色相对 vault 解析,没配 vault 就相对 workspace 根 */
 export const PATH_ROLES = ['vault', 'photos', 'diary', 'plans', 'profile', 'timetable'];
 export const ROLE_DEFAULTS = {
@@ -75,32 +91,39 @@ export const CotutorConfigSchema = z
     .object({
     version: z.literal(1),
     /** 孩子端标题,无品牌 */
-    title: z.string().default('cotutor'),
+    title: z.string().default('cotutor').describe('孩子端标题,无品牌'),
     kid: z.object({
         /** 短名,进路径 ~/cotutor/<slug>/,不是真名 */
         slug: z.string().regex(AGENT_NAME_RE),
         name: z.string().optional(),
         grade: z.string().optional(),
     }),
-    server: z.object({ port: z.number().int().min(1).max(65535).default(5180) }).default({ port: 5180 }),
-    paths: z.record(z.string(), z.string()).default({}),
-    policyDefaults: PolicyPatchSchema.default({}),
-    teachers: z.record(z.string().regex(AGENT_NAME_RE), TeacherSchema).default({}),
-    agents: AgentsSchema,
+    server: z
+        .object({
+        port: z.number().int().min(1).max(65535).default(5180),
+        /** 只给这个 workspace 用的证书(相对 workspace 根),是例外;不配则用机器级 ~/.config/cotutor/certs/(cotutor cert 会建,所有 workspace 共用;iPad 上录音要 HTTPS) */
+        https: z.object({ cert: z.string().min(1), key: z.string().min(1) }).optional(),
+    })
+        .default({ port: 5180 }),
+    paths: z.record(z.string(), z.string()).default({}).describe('角色 → 目录:vault 指 Obsidian vault 根;photos / diary / plans / profile / timetable 相对 vault;不配 vault 就相对 workspace 根'),
+    policyDefaults: PolicyPatchSchema.default({}).describe('所有老师的政策缺省;没写的用出厂缺省(60 字 / 30 条 / 3 次 / 验收关 / L0,L1,L3,L4 / 10,10)'),
+    tutors: z.record(z.string().regex(AGENT_NAME_RE), TutorSchema).default({}).describe('老师表:键 = .claude/agents/<键>.md 的 frontmatter name;人设、开关、政策都在这里,老师文件里只有正文'),
+    runtimes: RuntimesSchema.describe('运行时:default 指一个键;每个运行时 {run, resume} 命令模板,占位 {agent} {agentBody} {prompt} {session};模型、预算、时限写在这里'),
+    tts: TtsSchema.default(TTS_DEFAULT).describe('配音命令模板,占位 {text} {voice} {out}'),
 })
     .superRefine((c, ctx) => {
-    if (!(c.agents.default in c.agents) || c.agents.default === 'default') {
+    if (!(c.runtimes.default in c.runtimes) || c.runtimes.default === 'default') {
         ctx.addIssue({
             code: 'custom',
-            path: ['agents', 'default'],
-            message: `预设 "${c.agents.default}" 不存在;agents 里要有同名的 {run, resume}`,
+            path: ['runtimes', 'default'],
+            message: `运行时 "${c.runtimes.default}" 不存在;runtimes 里要有同名的 {run, resume}`,
         });
     }
 });
-/** 老师的有效政策 = POLICY_DEFAULTS ← policyDefaults ← teachers[name].policy */
-export function resolvePolicy(config, teacher) {
-    const layers = [config.policyDefaults, config.teachers[teacher]?.policy ?? {}];
-    const out = { ...POLICY_DEFAULTS, contextPack: { ...POLICY_DEFAULTS.contextPack } };
+/** 老师的有效政策 = POLICY_DEFAULTS ← policyDefaults ← tutors[name].policy */
+export function resolvePolicy(config, tutor) {
+    const layers = [config.policyDefaults, config.tutors[tutor]?.policy ?? {}];
+    const out = { ...POLICY_DEFAULTS, contextPack: { ...POLICY_DEFAULTS.contextPack }, scenes: { ...POLICY_DEFAULTS.scenes } };
     for (const p of layers) {
         if (p.replyMaxChars !== undefined)
             out.replyMaxChars = p.replyMaxChars;
@@ -116,12 +139,16 @@ export function resolvePolicy(config, teacher) {
             out.contextPack.recent = p.contextPack.recent;
         if (p.contextPack?.planLines !== undefined)
             out.contextPack.planLines = p.contextPack.planLines;
+        if (p.board !== undefined)
+            out.board = p.board;
+        if (p.scenes?.dailyMax !== undefined)
+            out.scenes.dailyMax = p.scenes.dailyMax;
     }
     return out;
 }
 /** 老师列表(带有效政策);kidOnly = 只要孩子端能看到的(enabled 且不 hidden) */
-export function listTeachers(config, opts = {}) {
-    return Object.entries(config.teachers)
+export function listTutors(config, opts = {}) {
+    return Object.entries(config.tutors)
         .filter(([, t]) => !opts.kidOnly || (t.enabled && !t.hidden))
         .map(([name, t]) => ({
         name,
@@ -134,11 +161,14 @@ export function listTeachers(config, opts = {}) {
         policy: resolvePolicy(config, name),
     }));
 }
-/** 预设模板填占位符;{agentBody} 只在给了正文时替换,否则原样留着(doctor 会报) */
-export function fillPreset(argv, vars) {
+/** 运行时模板填占位符;{agentBody} 只在给了正文时替换,否则原样留着(doctor 会报) */
+export function fillRuntime(argv, vars) {
     return argv.map((a) => a
         .replaceAll('{agent}', vars.agent)
         .replaceAll('{prompt}', vars.prompt)
         .replaceAll('{session}', vars.session ?? '')
         .replaceAll('{agentBody}', vars.agentBody ?? '{agentBody}'));
 }
+export function fillTts(argv, vars) {
+    return argv.map((a) => a.replaceAll('{text}', vars.text).replaceAll('{voice}', vars.voice).replaceAll('{out}', vars.out));
+}

package/dist/schema/context-pack.d.ts

@@ -9,6 +9,7 @@ export declare const FocusSchema: z.ZodObject<{
     artifact: z.ZodOptional<z.ZodString>;
     step: z.ZodOptional<z.ZodNumber>;
     circled: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    card: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type Focus = z.infer<typeof FocusSchema>;
 export declare const ContextPackSchema: z.ZodObject<{
@@ -23,11 +24,17 @@ export declare const ContextPackSchema: z.ZodObject<{
         artifact: z.ZodOptional<z.ZodString>;
         step: z.ZodOptional<z.ZodNumber>;
         circled: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        card: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     plan: z.ZodDefault<z.ZodArray<z.ZodString>>;
     recent: z.ZodDefault<z.ZodArray<z.ZodObject<{
         date: z.ZodString;
         claim: z.ZodString;
     }, z.core.$strip>>>;
+    board: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        off: "off";
+    }>>;
+    cards: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export type ContextPack = z.infer<typeof ContextPackSchema>;

package/dist/schema/context-pack.js

@@ -11,6 +11,8 @@ export const FocusSchema = z.object({
     step: z.number().int().nonnegative().optional(),
     /** 圈了什么 */
     circled: z.array(z.string()).optional(),
+    /** 孩子发消息时正开着的那张卡(<job>/<n>) */
+    card: z.string().optional(),
 });
 export const ContextPackSchema = z.object({
     from: z.enum(MESSAGE_FROM),
@@ -23,4 +25,8 @@ export const ContextPackSchema = z.object({
     plan: z.array(z.string()).default([]),
     /** 最近 N 条本学科观察(已按 recent 截) */
     recent: z.array(z.object({ date: z.string(), claim: z.string() })).default([]),
+    /** 政策旋钮 board = off 时带上,老师只说话不出卡;auto 不写 */
+    board: z.enum(['auto', 'off']).optional(),
+    /** 上一轮之后孩子改过状态的卡,每张一句(「<job>/<n> choice「问题」 选了「B …」(答案:「…」)」) */
+    cards: z.array(z.string()).optional(),
 });

package/dist/schema/conversation.d.ts

@@ -1,6 +1,6 @@
 /**
- * 会话索引:一老师一天一份(《cotutor契约草案.md》§3)。每条消息 = 一次 -p 运行 = 一份 NDJSON 转录;
- * 索引里的 kidText / artifacts 是精简视图的物化结果,孩子端不解析日志。跨天自动新开(2026-09-08 拍板)。
+ * 对话索引:一老师一天一份(《cotutor契约草案.md》§3)。每条消息 = 一次 -p 运行 = 一份 NDJSON 转录;
+ * 索引里的 kidText / artifacts 是孩子视图的物化结果,孩子端不解析日志。跨天自动新开(2026-09-08 拍板)。
  */
 import { z } from 'zod';
 export declare const DATE_RE: RegExp;
@@ -17,7 +17,12 @@ export declare const ConversationMessageSchema: z.ZodObject<{
         artifact: z.ZodOptional<z.ZodString>;
         step: z.ZodOptional<z.ZodNumber>;
         circled: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        card: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    action: z.ZodOptional<z.ZodEnum<{
+        continue: "continue";
+        submit: "submit";
+    }>>;
     result: z.ZodDefault<z.ZodEnum<{
         error: "error";
         running: "running";
@@ -26,14 +31,64 @@ export declare const ConversationMessageSchema: z.ZodObject<{
     costUsd: z.ZodOptional<z.ZodNumber>;
     kidText: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     artifacts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    runtime: z.ZodOptional<z.ZodString>;
+    holdup: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        question: z.ZodString;
+        options: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            note: z.ZodOptional<z.ZodString>;
+            recommended: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+    handoff: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        to: z.ZodString;
+        why: z.ZodOptional<z.ZodString>;
+        refs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    handoffJob: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        tutor: z.ZodString;
+        job: z.ZodString;
+    }, z.core.$strip>>>;
+    error: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    section: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        cards: z.ZodArray<z.ZodObject<{
+            kind: z.ZodString;
+            props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            state: z.ZodOptional<z.ZodUnknown>;
+            assets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+        lines: z.ZodArray<z.ZodObject<{
+            text: z.ZodString;
+            audio: z.ZodNullable<z.ZodString>;
+            marks: z.ZodArray<z.ZodObject<{
+                card: z.ZodNumber;
+                phrase: z.ZodString;
+            }, z.core.$strip>>;
+            ask: z.ZodBoolean;
+            anchor: z.ZodNullable<z.ZodNumber>;
+            cues: z.ZodArray<z.ZodObject<{
+                card: z.ZodNumber;
+                name: z.ZodString;
+                arg: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        partial: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    parentText: z.ZodOptional<z.ZodString>;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    cards: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        card: z.ZodString;
+        text: z.ZodString;
+    }, z.core.$strip>>>;
+    audio: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 export type ConversationMessage = z.infer<typeof ConversationMessageSchema>;
 export declare const ConversationIndexSchema: z.ZodObject<{
-    teacher: z.ZodString;
+    tutor: z.ZodString;
     date: z.ZodString;
     session: z.ZodDefault<z.ZodNullable<z.ZodObject<{
         id: z.ZodString;
-        agent: z.ZodString;
+        runtime: z.ZodString;
     }, z.core.$strip>>>;
     messages: z.ZodDefault<z.ZodArray<z.ZodObject<{
         job: z.ZodString;
@@ -48,7 +103,12 @@ export declare const ConversationIndexSchema: z.ZodObject<{
             artifact: z.ZodOptional<z.ZodString>;
             step: z.ZodOptional<z.ZodNumber>;
             circled: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            card: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
+        action: z.ZodOptional<z.ZodEnum<{
+            continue: "continue";
+            submit: "submit";
+        }>>;
         result: z.ZodDefault<z.ZodEnum<{
             error: "error";
             running: "running";
@@ -57,6 +117,56 @@ export declare const ConversationIndexSchema: z.ZodObject<{
         costUsd: z.ZodOptional<z.ZodNumber>;
         kidText: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         artifacts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        runtime: z.ZodOptional<z.ZodString>;
+        holdup: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            question: z.ZodString;
+            options: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                note: z.ZodOptional<z.ZodString>;
+                recommended: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>>;
+        handoff: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            to: z.ZodString;
+            why: z.ZodOptional<z.ZodString>;
+            refs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>>;
+        handoffJob: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            tutor: z.ZodString;
+            job: z.ZodString;
+        }, z.core.$strip>>>;
+        error: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        section: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            cards: z.ZodArray<z.ZodObject<{
+                kind: z.ZodString;
+                props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                state: z.ZodOptional<z.ZodUnknown>;
+                assets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>>;
+            lines: z.ZodArray<z.ZodObject<{
+                text: z.ZodString;
+                audio: z.ZodNullable<z.ZodString>;
+                marks: z.ZodArray<z.ZodObject<{
+                    card: z.ZodNumber;
+                    phrase: z.ZodString;
+                }, z.core.$strip>>;
+                ask: z.ZodBoolean;
+                anchor: z.ZodNullable<z.ZodNumber>;
+                cues: z.ZodArray<z.ZodObject<{
+                    card: z.ZodNumber;
+                    name: z.ZodString;
+                    arg: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+            partial: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
+        parentText: z.ZodOptional<z.ZodString>;
+        warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        cards: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            card: z.ZodString;
+            text: z.ZodString;
+        }, z.core.$strip>>>;
+        audio: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>>>;
     costUsd: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;

package/dist/schema/conversation.js

@@ -1,30 +1,54 @@
 /**
- * 会话索引:一老师一天一份(《cotutor契约草案.md》§3)。每条消息 = 一次 -p 运行 = 一份 NDJSON 转录;
- * 索引里的 kidText / artifacts 是精简视图的物化结果,孩子端不解析日志。跨天自动新开(2026-09-08 拍板)。
+ * 对话索引:一老师一天一份(《cotutor契约草案.md》§3)。每条消息 = 一次 -p 运行 = 一份 NDJSON 转录;
+ * 索引里的 kidText / artifacts 是孩子视图的物化结果,孩子端不解析日志。跨天自动新开(2026-09-08 拍板)。
  */
 import { z } from 'zod';
 import { FocusSchema, MESSAGE_FROM } from "./context-pack.js";
+import { BoardSectionSchema } from "./board.js";
+import { HandoffSchema, HoldupAskSchema } from "./sections.js";
 export const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 export const ConversationMessageSchema = z.object({
-    /** 任务 id,同时是转录文件名的一段:<date>.<job>.log */
+    /** 一轮的 id(job),也是转录文件名的一段:<date>.<job>.log */
     job: z.string().min(1),
     at: z.string().min(1),
     from: z.enum(MESSAGE_FROM),
     /** 消息原文(不含上下文包) */
     text: z.string(),
     focus: FocusSchema.optional(),
+    /** 孩子端的两个不打字的动作:继续(不计每日上限)/ 交给老师(把卡上的状态交出去) */
+    action: z.enum(['continue', 'submit']).optional(),
     result: z.enum(['running', 'ok', 'error']).default('running'),
     costUsd: z.number().optional(),
     /** 孩子视图文本;null = 这次运行没有给孩子的话(出错或空) */
     kidText: z.string().nullable().optional(),
     /** 本次运行新增的产物 id */
     artifacts: z.array(z.string()).default([]),
+    /** 跑这条用的运行时名(runtimes 里的键);换运行时时新开会话 */
+    runtime: z.string().optional(),
+    /** 最终文本里剥出来的「待裁量」段:家长视图渲染成选项按钮(R2 物化,免得页面再解析日志) */
+    holdup: HoldupAskSchema.nullable().optional(),
+    /** 最终文本里剥出来的「转交」段:应用据此自动起目标老师的一轮(from: system) */
+    handoff: HandoffSchema.nullable().optional(),
+    /** 自动转交起的那一轮:目标老师与 job;没起(上限、忙、老师不在)的原因在 warnings */
+    handoffJob: z.object({ tutor: z.string(), job: z.string() }).nullable().optional(),
+    /** 不 ok 时的原因(subtype / terminal_reason),家长视图红条 */
+    error: z.string().nullable().optional(),
+    /** 最终文本解析出的板书节(卡 + 讲稿;孩子端下发前剥答案);null = 这轮没有 */
+    section: BoardSectionSchema.nullable().optional(),
+    /** 最终文本里第一个 H2 起给家长的尾巴(「## 家长」等),孩子看不到 */
+    parentText: z.string().optional(),
+    /** 解析板书时的提醒(卡没解析成等),家长视图显示;孩子端不报 */
+    warnings: z.array(z.string()).optional(),
+    /** 这条消息带给老师的卡(上一轮之后孩子改过状态的):id 与 describe 出的那句;家长视图显示「孩子在板书上做的」 */
+    cards: z.array(z.object({ card: z.string().min(1), text: z.string() })).optional(),
+    /** kidText 的配音文件名(conversations/<老师>/ 下,如 2026-09-09.1620-1.mp3);null = 没合成(老师没配音色、tts 运行时没配或失败) */
+    audio: z.string().nullable().optional(),
 });
 export const ConversationIndexSchema = z.object({
-    teacher: z.string().min(1),
+    tutor: z.string().min(1),
     date: z.string().regex(DATE_RE),
     /** 当天会话;首条消息跑完后写入,之后每条 --resume 它 */
-    session: z.object({ id: z.string().min(1), agent: z.string().min(1) }).nullable().default(null),
+    session: z.object({ id: z.string().min(1), runtime: z.string().min(1) }).nullable().default(null),
     messages: z.array(ConversationMessageSchema).default([]),
     costUsd: z.number().default(0),
 });

package/dist/schema/index.d.ts

@@ -1,11 +1,12 @@
 /**
  * cotutor 契约(类型即文档)。每个文件一个契约面:
- *  config        cotutor.json(老师表、政策、运行时预设、paths 角色)
+ *  config        cotutor.json(老师表、政策、运行时、paths 角色)
  *  context-pack  每条消息前的上下文包
- *  conversation  一老师一天一份的会话索引
+ *  conversation  一老师一天一份的对话索引
  *  ledger        观察与产物两本追加式账本
  *  sections      最终文本里的「待裁量」「转交」段
  *  plan          计划文件
+ *  timetable     课程表(vault 里的 markdown 表)
  * 运行时校验用 zod,失败信息经 explainIssues 变成修复指南。
  */
 export * from './issues.ts';
@@ -14,4 +15,7 @@ export * from './context-pack.ts';
 export * from './conversation.ts';
 export * from './ledger.ts';
 export * from './sections.ts';
+export * from './board.ts';
 export * from './plan.ts';
+export * from './timetable.ts';
+export * from './json-schema.ts';