cotutor 0.2.0 → 0.4.0

package/dist/schema/conversation.js

@@ -1,23 +1,52 @@
 /**
- * 对话索引:一老师一天一份(《cotutor契约草案.md》§3)。每条消息 = 一次 -p 运行 = 一份 NDJSON 转录;
- * 索引里的 kidText / artifacts 是孩子视图的物化结果,孩子端不解析日志。跨天自动新开(2026-09-08 拍板)。
+ * 对话索引:一老师一天一份。每条消息 = 一次 -p 运行 = 一份 NDJSON 转录;
+ * 索引里的 kidText / artifacts 是孩子视图的物化结果,孩子端不解析日志。跨天自动新开。
  */
 import { z } from 'zod';
 import { FocusSchema, MESSAGE_FROM } from "./context-pack.js";
-import { BoardSectionSchema } from "./board.js";
-import { HandoffSchema, HoldupAskSchema } from "./sections.js";
+import { BoardSectionSchema, DeviceSchema } from "./board.js";
+import { BookkeepingSchema } from "./sections.js";
+import { MessageViaSchema } from "./home.js";
+import { ActivityRunSchema } from "./activity.js";
+import { MemoryLineSchema, MemoryProposalSchema, PendingCommitSchema } from "./memory.js";
 export const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
-export const ConversationMessageSchema = z.object({
+/** 孩子端设备的编号:服务端种的 cookie,随机 12 位十六进制 */
+export const DEVICE_ID_RE = /^[0-9a-f]{12}$/;
+export const TimingSchema = z.object({
+    /** 进程起来的时刻(ISO,精确到毫秒;消息的 at 只到分钟) */
+    startedAt: z.string().min(1),
+    /** 这轮用的是提前起好的老师进程(预热,2026-09-29);startedAt 仍是孩子开口那刻 */
+    warm: z.literal(true).optional(),
+    /** 流式时第一张卡闭合(孩子端第一次看到东西);整块出的运行时没有 */
+    firstCardMs: z.number().int().nonnegative().optional(),
+    /** 首句就绪:嘴能开口的那一刻(头号埋点),第一拍关了就算(讲稿不配音) */
+    firstReadyMs: z.number().int().nonnegative().optional(),
+    /** 老师进程退出 */
+    doneMs: z.number().int().nonnegative().optional(),
+    /** 每拍(2026-09-13,从事件推):关、就绪 */
+    beats: z.array(z.object({ card: z.number().int().nonnegative().nullable(), closedMs: z.number().int().nonnegative().optional(), readyMs: z.number().int().nonnegative().optional() })).optional(),
+});
+export const SessionSchema = z.object({ id: z.string().min(1), runtime: z.string().min(1) });
+const MessageObjectSchema = z.object({
     /** 一轮的 id(job),也是转录文件名的一段:<date>.<job>.log */
     job: z.string().min(1),
+    /** 话题 id = 话题第一条消息的 job(一个话题 = 一段连续问答 = 老师的一个会话;一天可多个)。旧索引没有:读时按 threadOf 现算 */
+    thread: z.string().optional(),
     at: z.string().min(1),
+    /** 谁发的:孩子(孩子端、工作台、cotutor send 都算)或应用派的任务 */
     from: z.enum(MESSAGE_FROM),
     /** 消息原文(不含上下文包) */
     text: z.string(),
     focus: FocusSchema.optional(),
-    /** 孩子端的两个不打字的动作:继续(不计每日上限)/ 交给老师(把卡上的状态交出去) */
-    action: z.enum(['continue', 'submit']).optional(),
+    /** 孩子端不打字的动作:交给老师(把卡上的状态交出去) */
+    action: z.enum(['submit']).optional(),
+    /** 这条消息带的作业照片(R5,2026-09-14):相对 workspace 根的路径(captures/<日期>/<HHMM>-<n>.jpg),上下文包 photos: 段原样给老师 Read;日记永不引用它 */
+    photos: z.array(z.string().min(1)).optional(),
     result: z.enum(['running', 'ok', 'error']).default('running'),
+    /** 这一轮的 token:输入(含缓存读)与输出;记账、显示都按它(src/shared/tokens.ts)。运行时没报(出错没收尾)就没有 */
+    /** cached = 输入里命中缓存的,context = 最后一次请求的输入(这一轮结束时上下文多大);这两样只有 API 运行时报 */
+    tokens: z.object({ in: z.number().int().nonnegative(), out: z.number().int().nonnegative(), cached: z.number().int().nonnegative().optional(), context: z.number().int().nonnegative().optional() }).optional(),
+    /** 老数据:2026-10-28 之前 claude 那几轮记的美元。不再写、不显示,留在这里免得改写索引时丢掉 */
     costUsd: z.number().optional(),
     /** 孩子视图文本;null = 这次运行没有给孩子的话(出错或空) */
     kidText: z.string().nullable().optional(),
@@ -25,30 +54,117 @@ export const ConversationMessageSchema = z.object({
     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 起给家长的尾巴(「## 家长」等),孩子看不到 */
+    /** 最终文本里第一个 H2 起给家长的尾巴(老师写的任何标题段),孩子看不到 */
     parentText: z.string().optional(),
     /** 解析板书时的提醒(卡没解析成等),家长视图显示;孩子端不报 */
     warnings: z.array(z.string()).optional(),
+    /** 这轮「## 记忆」段真落进 vault 记忆文件的改动:新增的行(带日期)、「改:旧 → 新」、「删:旧」;进孩子的记忆的前面加「孩子的记忆:」;家长视图显示 */
+    remembered: z.array(z.string()).optional(),
+    /** 同一批改动的整行原文(删话题时按它撤销,2026-10-05):before = 改之前那行(新增的为 null),after = 改之后那行(删掉的为 null) */
+    memoryLines: z.array(MemoryLineSchema).optional(),
+    /** 同上,写进孩子的记忆(`agent: all`)的那几行(2026-10-30) */
+    childLines: z.array(MemoryLineSchema).optional(),
+    /** 记账那轮追加进日记的那一段原文(删话题时从日记里摘掉,2026-10-05) */
+    diaryBlock: z.string().optional(),
+    /** 这轮「## 记忆」段的每一条建议与证据对没对上(2026-10-30,schema/memory.ts);家长视图看哪些没证据、哪些对不上没记 */
+    memoryProposals: z.array(MemoryProposalSchema).optional(),
+    /** 写 vault 之前记的一笔,写完就没了;还在 = 写到一半断了,下次记账、删话题之前对照文件补记或丢掉(schema/memory.ts) */
+    pending: PendingCommitSchema.optional(),
+    /** 这轮上下文包里家长笔记的版本:role(profile / entry)→ `路径@hash`;同一话题下一轮对得上就只写「未变」(2026-09-17) */
+    notes: z.record(z.string(), 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(),
+    /** 这轮的用时(埋点,2026-09-11):都是从 startedAt 起的毫秒数;家长视图每轮一行「首卡 10s · 整轮 23s」 */
+    timing: TimingSchema.optional(),
+    /** 发这条时孩子端是什么端(缺省当平板横屏) */
+    device: DeviceSchema.optional(),
+    /** 哪一台设备:服务端种的 cookie 编号;工作台、cotutor send 发的没有 */
+    deviceId: z.string().regex(DEVICE_ID_RE).optional(),
+    /** 这轮是给某个话题记账的任务(from: system,resume 那个话题的会话);跑完老师回的「## 记账」段经应用落进日记 */
+    bookkeep: z.object({ thread: z.string().min(1) }).optional(),
+    /** 这轮是记账后整理记忆的任务(from: system,新会话;2026-09-18):老师回「## 记忆」段的一串增 / 改 / 删,不受每轮条数上限;孩子端看不到 */
+    tidy: z.literal(true).optional(),
+    /** 这一轮整段压缩过(API 运行时,上一轮结束时上下文过了 32k):之前的模型历史不再发,前情由应用照索引拼(src/runtime/context/thread-digest.ts) */
+    compacted: z.literal(true).optional(),
+    /** 最终文本里剥出来的「## 记账」段(物化;日记已按它写好);null = 这轮没有 */
+    bookkeeping: BookkeepingSchema.nullable().optional(),
+    /** 这轮模型用了哪些工具、读了什么(2026-09-15,从 .log 抽,brain/transcript.ts toolCalls):名字、最要紧的参数、成没成、结果多少字。家长端「看原文」的「读了什么」站;cotutor show 也吐 */
+    tools: z.array(z.object({ name: z.string().min(1), arg: z.string(), ok: z.boolean().nullable(), chars: z.number().int().nonnegative(), sub: z.boolean().optional() })).optional(),
+    /** 这条是回放(cotutor replay,app/replay.ts):原轮的 job。回放落在 evals/ 里,不在 conversations/ */
+    replayOf: z.string().min(1).optional(),
+    /** 这条是 cotutor activity eval 跑的(落在 evals/,模拟孩子):同回放,不写记忆、不预热 */
+    eval: z.literal(true).optional(),
+    /** 这一轮走实时:讲稿没配音,由 realtime 模型(嘴)照念;孩子端放的是嘴的声音,以前的话题里这几句不出声 */
+    live: z.literal(true).optional(),
+    /**
+     * 这条是孩子看完小课堂后的第一条:哪份课包、课名、看了多久、看完没、停过几次、画过的几处;节前的小课堂卡与画的卡从这里画。
+     * again = 问过以后「再看一遍」又画了,这条只为带上新画的(节前只画画的卡)。一处画:时刻、SVG 停在哪(缩略图)、几笔(课包坐标)、给老师的那段话、截图
+     */
+    lecture: z
+        .object({
+        bundle: z.string().min(1),
+        title: z.string(),
+        watchedMs: z.number().nonnegative(),
+        finished: z.boolean(),
+        pauses: z.number().int().nonnegative(),
+        again: z.literal(true).optional(),
+        /** 视频小课堂(lectures/<id>/);没有 = 课包 */
+        video: z.literal(true).optional(),
+        /** 一处 = 停在同一刻画的几笔;截图在 captures/ 里(画面叠上那几笔;路径相对 workspace 根)。2026-10-19 以前一笔一处(path),读成一笔的 strokes */
+        marks: z.array(z.object({ atMs: z.number().nonnegative(), svgMs: z.number().nonnegative(), strokes: z.array(z.array(z.tuple([z.number(), z.number()]))), text: z.string().optional(), image: z.string().optional(), t: z.number().optional() })).optional(),
+        /**
+         * 看的过程(录像用第 5 步):放 / 停 / 拖到哪 / 放完,一次一条。t = 离这条消息发出去多少毫秒(≤ 0,孩子端自己的钟算,
+         * 不用对钟);pos = 那时停在课里的哪一刻;play = 那之后在放。画的 t 同理(这一处第一笔画下去的那一刻)
+         */
+        log: z.array(z.object({ t: z.number(), pos: z.number().nonnegative(), play: z.boolean() })).optional(),
+    })
+        .optional(),
+    /**
+     * 孩子从左栏的纸「给老师看」交的画:图在 captures/(相对 workspace 根)、几笔、各颜色几笔(「黑 12、红 40」)、
+     * 画了多久(第一笔到最后一笔,算上清空前那几版)、清空前存的那几版的图。板上节前一张孩子的画卡从这里画;图和清掉的那几版进上下文包 photos 给老师 Read
+     */
+    drawing: z
+        .object({
+        image: z.string().min(1),
+        strokes: z.number().int().nonnegative(),
+        colors: z.string().optional(),
+        ms: z.number().nonnegative().optional(),
+        cleared: z.array(z.string().min(1)).optional(),
+    })
+        .optional(),
+    /** 孩子从首页哪个按钮进来的;开场按钮的 text 就是按钮上的字,不是孩子说的 */
+    via: MessageViaSchema.optional(),
+    /** 这个话题是从哪个 activity 起的(只记在话题第一条):名字与点的那一刻的参数,话题后面每条都照它带 */
+    activity: ActivityRunSchema.optional(),
+    /** 口语课页的哪份口语单起的这个话题(talk/<id>/ 4,只记在话题第一条) */
+    talk: z.string().optional(),
+    /** 这个话题接着以前哪天的哪个话题(首页的「接着」按钮;新会话,上下文包带那个话题的尾巴) */
+    continues: z.object({ date: z.string().regex(DATE_RE), thread: z.string().min(1) }).optional(),
 });
+export const ConversationMessageSchema = MessageObjectSchema;
 export const ConversationIndexSchema = z.object({
     tutor: z.string().min(1),
     date: z.string().regex(DATE_RE),
-    /** 当天会话;首条消息跑完后写入,之后每条 --resume 它 */
-    session: z.object({ id: z.string().min(1), runtime: z.string().min(1) }).nullable().default(null),
+    /** 当前话题(末条消息所在)的会话;首条消息跑完后写入。每个话题自己的会话在 sessions 里,这里只是最新那条(旧索引只有它) */
+    session: SessionSchema.nullable().default(null),
+    /** 话题 id → 那个话题的会话;今天的旧话题接着聊就 resume 它 */
+    sessions: z.record(z.string(), SessionSchema).default({}),
     messages: z.array(ConversationMessageSchema).default([]),
-    costUsd: z.number().default(0),
+    /** 话题 id → 家长打的星(1–5;《obsidian仓库设计.md》§4:打分的单位是话题;≥ vault.keepScore 记账时才沉淀摘要) */
+    ratings: z.record(z.string(), z.number().int().min(1).max(5)).default({}),
+    /** 话题 id → 记账那轮的 job(记过的不再记;日记里已有这个话题的一段) */
+    booked: z.record(z.string(), z.string().min(1)).default({}),
 });
+/**
+ * 每条消息的话题 id(与 messages 对齐)。有 thread 字段照它;没有(旧索引)按规则现算:第一条 = 自己的 job,
+ * from: system 的(记账、整理记忆这类)永远开新话题,其余跟前一条。写新消息时 runner 已经填了 thread,这里只是兜底。
+ */
+export function threads(messages) {
+    const out = [];
+    messages.forEach((m, i) => out.push(m.thread ?? (i === 0 || m.from === 'system' ? m.job : out[i - 1])));
+    return out;
+}

package/dist/schema/events.d.ts

@@ -0,0 +1,138 @@
+/**
+ * 一轮运行的事件(<日期>.<job>.events.jsonl 的一行;控制台与时间线的唯一来源)。格式化与读在 runtime/journal/events.ts。
+ */
+import type { Tokens } from '../shared/tokens.ts';
+export type Lane = 'main' | 'tts' | 'ready' | 'index' | 'ledger' | 'mouth';
+export declare const LANES: readonly Lane[];
+export type RunEvent = {
+    t: number;
+} & (
+/** warmMs:用的是提前起好的进程(预热),它等了多久 */
+{
+    lane: 'main';
+    kind: 'start';
+    cli: string;
+    runtime: string;
+    resume: boolean;
+    warmMs?: number;
+} | {
+    lane: 'main';
+    kind: 'card';
+    card: number;
+    label: string;
+}
+/** play:这句的 [[play]] 锚着小课堂卡(念完放那一段;实时时服务端等孩子端放完再交后面的句子);echo / call:热身的 [[echo 词]] [[say 词]] 与 [[call]](实时时服务端等孩子跟、进打电话) */
+ | {
+    lane: 'main';
+    kind: 'line';
+    line: number;
+    text: string;
+    play?: true;
+    echo?: {
+        word: string;
+        say?: true;
+    };
+    call?: true;
+} | {
+    lane: 'main';
+    kind: 'tool';
+    name: string;
+    sub: boolean;
+} | {
+    lane: 'main';
+    kind: 'exit';
+    ok: boolean;
+    reason?: string;
+    tokens?: Tokens;
+    turns?: number;
+}
+/** 断流:老师进程 idleMs 没吐一个字节(工具不在跑),杀掉;retry = 接着跑第几次(0 = 次数用完,不再跑),kept = 断前已写出的正文字数 */
+ | {
+    lane: 'main';
+    kind: 'stall';
+    idleMs: number;
+    retry: number;
+    kept: number;
+} | {
+    lane: 'tts';
+    kind: 'queued';
+    label: string;
+} | {
+    lane: 'tts';
+    kind: 'done';
+    label: string;
+    ms: number;
+    file: string;
+} | {
+    lane: 'tts';
+    kind: 'failed';
+    label: string;
+    ms: number;
+    error: string;
+} | {
+    lane: 'ready';
+    kind: 'beat';
+    beat: number;
+    card: number | null;
+    first: boolean;
+}
+/** 第一句配好了,能开口了(首句就绪;2026-10-08 起比第一拍早) */
+ | {
+    lane: 'ready';
+    kind: 'speak';
+} | {
+    lane: 'ready';
+    kind: 'all';
+    cards: number;
+    lines: number;
+} | {
+    lane: 'index';
+    kind: 'written';
+    warnings: number;
+}
+/** 记账:话题的一段写进了 vault 的日记(file 是日记文件名) */
+ | {
+    lane: 'ledger';
+    kind: 'diary';
+    thread: string;
+    file: string;
+}
+/** 实时老师的嘴:孩子按下 · 松手(voice)或发了不是说的(text / photo / card;ask 是卡上的「?」 撤了,旧记录里还有)· 嘴接住的声音开始在孩子端放 ·
+ *  讲稿第几句开始放 · 孩子按下打断了这一轮(line = 正念到第几句,0 起;还没念到讲稿 = null) */
+ | {
+    lane: 'mouth';
+    kind: 'hold';
+}
+/** vad = 一直听时孩子说完(服务端 VAD 判的、应用收下了) */
+ | {
+    lane: 'mouth';
+    kind: 'release';
+    how: 'voice' | 'vad' | 'text' | 'photo' | 'card' | 'ask';
+} | {
+    lane: 'mouth';
+    kind: 'catch';
+    text: string;
+} | {
+    lane: 'mouth';
+    kind: 'read';
+    line: number;
+} | {
+    lane: 'mouth';
+    kind: 'cut';
+    line: number | null;
+}
+/** 脑想得久(松手几秒了讲稿还一句没有),嘴垫了一句(开始放) */
+ | {
+    lane: 'mouth';
+    kind: 'fill';
+    text: string;
+});
+/** 发事件时给的形状:少一个 t(runner 补);Omit 直接套在联合上会塌成公共键,所以逐个分发 */
+export type RunEventInput = RunEvent extends infer E ? (E extends RunEvent ? Omit<E, 't'> : never) : never;
+/** 内存订阅者拿到的:事件 + 是谁的哪一轮 */
+export interface RunEventEnvelope {
+    tutor: string;
+    date: string;
+    job: string;
+    event: RunEvent;
+}

package/dist/schema/events.js

@@ -0,0 +1 @@
+export const LANES = ['main', 'tts', 'ready', 'index', 'ledger', 'mouth'];

package/dist/schema/home.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 首页:家长批准后发布的那页卡。草稿 home/draft.md 是板书同一套围栏语法(src/runtime/home/home.ts 解析),
+ * `cotutor home publish` 校验后写 home/published.json,孩子端只读它。卡的 props 契约在 src/board/cards/<kind>.ts(老师卡的讲法留在这里,下发孩子前剥掉)。
+ */
+import { z } from 'zod';
+/** 发布的 id:发布时刻 YYYY-MM-DD-HHMM,同一分钟再发加 -2、-3 */
+export declare const HOME_ID_RE: RegExp;
+export declare const PublishedHomeSchema: z.ZodObject<{
+    id: z.ZodString;
+    publishedAt: z.ZodString;
+    for: z.ZodOptional<z.ZodString>;
+    source: z.ZodString;
+    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>>;
+        look: z.ZodOptional<z.ZodObject<{
+            tint: z.ZodOptional<z.ZodString>;
+            look: z.ZodOptional<z.ZodString>;
+            emoji: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    note: z.ZodDefault<z.ZodString>;
+    warnings: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type PublishedHome = z.infer<typeof PublishedHomeSchema>;
+/** 孩子从首页哪个按钮进来的:home = 发布的 id(没发布过的缺省首页是 null),button = 老师卡上文件里的第几个按钮,或应用加的 new / recent,或常驻的方砖(HOME_TILES 的 id) */
+export declare const HomeViaSchema: z.ZodObject<{
+    home: z.ZodNullable<z.ZodString>;
+    button: z.ZodUnion<readonly [z.ZodNumber, z.ZodEnum<{
+        check: "check";
+        recent: "recent";
+        preview: "preview";
+        review: "review";
+        new: "new";
+    }>]>;
+}, z.core.$strip>;
+/** 这一下发出去的字是按钮上的字、不是孩子说的(家长排的按钮、方砖);新话题、接着刚才的不算 */
+export declare function viaSendsLabel(via: {
+    button: number | string;
+}): boolean;
+export type HomeVia = z.infer<typeof HomeViaSchema>;
+/** 消息里记的 via:再带上按钮上的字(发布的首页以后会换,记下来 home show 才说得清) */
+export declare const MessageViaSchema: z.ZodObject<{
+    home: z.ZodNullable<z.ZodString>;
+    button: z.ZodUnion<readonly [z.ZodNumber, z.ZodEnum<{
+        check: "check";
+        recent: "recent";
+        preview: "preview";
+        review: "review";
+        new: "new";
+    }>]>;
+    label: z.ZodString;
+}, z.core.$strip>;
+export type MessageVia = z.infer<typeof MessageViaSchema>;

package/dist/schema/home.js

@@ -0,0 +1,35 @@
+/**
+ * 首页:家长批准后发布的那页卡。草稿 home/draft.md 是板书同一套围栏语法(src/runtime/home/home.ts 解析),
+ * `cotutor home publish` 校验后写 home/published.json,孩子端只读它。卡的 props 契约在 src/board/cards/<kind>.ts(老师卡的讲法留在这里,下发孩子前剥掉)。
+ */
+import { z } from 'zod';
+import { BoardCardSchema } from "./board.js";
+import { HOME_TILE_IDS } from "./config.js";
+const DAY_RE = /^\d{4}-\d{2}-\d{2}$/;
+/** 发布的 id:发布时刻 YYYY-MM-DD-HHMM,同一分钟再发加 -2、-3 */
+export const HOME_ID_RE = /^\d{4}-\d{2}-\d{2}-\d{4}(?:-\d+)?$/;
+export const PublishedHomeSchema = z.object({
+    id: z.string().regex(HOME_ID_RE),
+    publishedAt: z.string().min(1),
+    /** 草稿 frontmatter 的 for:给哪天用的 */
+    for: z.string().regex(DAY_RE).optional(),
+    /** 这份的原文(相对 workspace 根,home/history/<id>.md) */
+    source: z.string().min(1),
+    /** 解析后的卡,文件顺序;老师卡带讲法(brief),孩子端下发前剥 */
+    cards: z.array(BoardCardSchema),
+    /** 家长段(第一个 H2 起),孩子看不到 */
+    note: z.string().default(''),
+    /** 发布时还在的提醒(家长端「首页」页显示) */
+    warnings: z.array(z.string()).default([]),
+});
+/** 孩子从首页哪个按钮进来的:home = 发布的 id(没发布过的缺省首页是 null),button = 老师卡上文件里的第几个按钮,或应用加的 new / recent,或常驻的方砖(HOME_TILES 的 id) */
+export const HomeViaSchema = z.object({
+    home: z.string().regex(HOME_ID_RE).nullable(),
+    button: z.union([z.number().int().nonnegative(), z.enum(['new', 'recent', ...HOME_TILE_IDS])]),
+});
+/** 这一下发出去的字是按钮上的字、不是孩子说的(家长排的按钮、方砖);新话题、接着刚才的不算 */
+export function viaSendsLabel(via) {
+    return typeof via.button === 'number' || HOME_TILE_IDS.includes(via.button);
+}
+/** 消息里记的 via:再带上按钮上的字(发布的首页以后会换,记下来 home show 才说得清) */
+export const MessageViaSchema = HomeViaSchema.extend({ label: z.string() });

package/dist/schema/index.d.ts

@@ -2,20 +2,31 @@
  * cotutor 契约(类型即文档)。每个文件一个契约面:
  *  config        cotutor.json(老师表、政策、运行时、paths 角色)
  *  context-pack  每条消息前的上下文包
- *  conversation  一老师一天一份的对话索引
- *  ledger        观察与产物两本追加式账本
- *  sections      最终文本里的「待裁量」「转交」段
+ *  conversation  一老师一天一份的对话索引;conversation-files 它在 conversations/ 下的文件布局
+ *  ledger        产物账本(追加式)
+ *  events        一轮运行的事件(events.jsonl)
+ *  sections      最终文本里的「记账」「记忆」段
+ *  memory        「记忆」段的建议与证据、写 vault 前记下的那一笔(pending)
  *  plan          计划文件
  *  timetable     课程表(vault 里的 markdown 表)
+ *  theme         主题清单(themes/<name>/theme.json:底色槽、字形槽、笔)
+ *  activity      activity 文件(agents/<老师>/activities/<名>.md:家长填的、应用算的、应用拦的、老师怎么带、工具人收到什么)
  * 运行时校验用 zod,失败信息经 explainIssues 变成修复指南。
  */
 export * from './issues.ts';
 export * from './config.ts';
+export * from './workspace.ts';
 export * from './context-pack.ts';
 export * from './conversation.ts';
+export * from './conversation-files.ts';
 export * from './ledger.ts';
+export * from './events.ts';
 export * from './sections.ts';
+export * from './memory.ts';
 export * from './board.ts';
 export * from './plan.ts';
 export * from './timetable.ts';
 export * from './json-schema.ts';
+export * from './theme.ts';
+export * from './home.ts';
+export * from './activity.ts';

package/dist/schema/index.js

@@ -2,20 +2,31 @@
  * cotutor 契约(类型即文档)。每个文件一个契约面:
  *  config        cotutor.json(老师表、政策、运行时、paths 角色)
  *  context-pack  每条消息前的上下文包
- *  conversation  一老师一天一份的对话索引
- *  ledger        观察与产物两本追加式账本
- *  sections      最终文本里的「待裁量」「转交」段
+ *  conversation  一老师一天一份的对话索引;conversation-files 它在 conversations/ 下的文件布局
+ *  ledger        产物账本(追加式)
+ *  events        一轮运行的事件(events.jsonl)
+ *  sections      最终文本里的「记账」「记忆」段
+ *  memory        「记忆」段的建议与证据、写 vault 前记下的那一笔(pending)
  *  plan          计划文件
  *  timetable     课程表(vault 里的 markdown 表)
+ *  theme         主题清单(themes/<name>/theme.json:底色槽、字形槽、笔)
+ *  activity      activity 文件(agents/<老师>/activities/<名>.md:家长填的、应用算的、应用拦的、老师怎么带、工具人收到什么)
  * 运行时校验用 zod,失败信息经 explainIssues 变成修复指南。
  */
 export * from "./issues.js";
 export * from "./config.js";
+export * from "./workspace.js";
 export * from "./context-pack.js";
 export * from "./conversation.js";
+export * from "./conversation-files.js";
 export * from "./ledger.js";
+export * from "./events.js";
 export * from "./sections.js";
+export * from "./memory.js";
 export * from "./board.js";
 export * from "./plan.js";
 export * from "./timetable.js";
 export * from "./json-schema.js";
+export * from "./theme.js";
+export * from "./home.js";
+export * from "./activity.js";

package/dist/schema/kid-device.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 孩子端的设备:服务端种的一枚 cookie 算一台,编号是随机的 12 位十六进制。
+ * 自动标签由浏览器信息算:「iPad · Safari 27 · 主屏幕」。纯函数,离屏可测。
+ */
+/** 设备 cookie 的名字;活 400 天(浏览器允许的最长) */
+export declare const DEVICE_COOKIE = "cotutor_kid";
+export declare const DEVICE_COOKIE_DAYS = 400;
+export { DEVICE_ID_RE } from './conversation.ts';
+/** 认设备要的那几样:浏览器信息、触点数、是不是从主屏幕打开 */
+export interface DeviceHint {
+    ua: string;
+    touch?: number;
+    standalone?: boolean;
+}
+/**
+ * 「iPad · Safari 27 · 主屏幕」。
+ * iPad 的 Safari 缺省请求桌面网站,浏览器信息写 Macintosh,要看触点数;新版 iOS 浏览器信息里的系统版本冻住了,只写浏览器的版本。
+ * 从主屏幕图标打开的 iOS 页面浏览器信息里没有 Safari 版本,只写「主屏幕」。
+ */
+export declare function deviceLabel(d: DeviceHint): string;

package/dist/schema/kid-device.js

@@ -0,0 +1,32 @@
+/**
+ * 孩子端的设备:服务端种的一枚 cookie 算一台,编号是随机的 12 位十六进制。
+ * 自动标签由浏览器信息算:「iPad · Safari 27 · 主屏幕」。纯函数,离屏可测。
+ */
+/** 设备 cookie 的名字;活 400 天(浏览器允许的最长) */
+export const DEVICE_COOKIE = 'cotutor_kid';
+export const DEVICE_COOKIE_DAYS = 400;
+export { DEVICE_ID_RE } from "./conversation.js";
+/**
+ * 「iPad · Safari 27 · 主屏幕」。
+ * iPad 的 Safari 缺省请求桌面网站,浏览器信息写 Macintosh,要看触点数;新版 iOS 浏览器信息里的系统版本冻住了,只写浏览器的版本。
+ * 从主屏幕图标打开的 iOS 页面浏览器信息里没有 Safari 版本,只写「主屏幕」。
+ */
+export function deviceLabel(d) {
+    const ua = d.ua;
+    const mac = /Macintosh/.test(ua);
+    const kind = /iPad/.test(ua) || (mac && (d.touch ?? 0) > 1) ? 'iPad'
+        : /iPhone/.test(ua) ? 'iPhone'
+            : /Android/.test(ua) ? (/Mobile/.test(ua) ? 'Android 手机' : 'Android 平板')
+                : mac ? 'Mac'
+                    : /Windows/.test(ua) ? 'Windows'
+                        : /Linux/.test(ua) ? 'Linux'
+                            : '';
+    const major = (re) => re.exec(ua)?.[1] ?? '';
+    const browser = /EdgiOS|Edg\//.test(ua) ? `Edge ${major(/(?:EdgiOS|Edg)\/(\d+)/)}`
+        : /CriOS|Chrome\//.test(ua) ? `Chrome ${major(/(?:CriOS|Chrome)\/(\d+)/)}`
+            : /FxiOS|Firefox\//.test(ua) ? `Firefox ${major(/(?:FxiOS|Firefox)\/(\d+)/)}`
+                : /Safari\//.test(ua) && /Version\//.test(ua) ? `Safari ${major(/Version\/(\d+)/)}`
+                    : '';
+    const parts = [kind, browser.trim(), d.standalone ? '主屏幕' : ''].filter(Boolean);
+    return parts.length ? parts.join(' · ') : '不认得的浏览器';
+}

package/dist/schema/ledger.d.ts

@@ -1,72 +1,16 @@
 /**
- * 公共账本(《cotutor契约草案.md》§5):observations.jsonl 与 artifacts.jsonl,追加式、一行一条、id 唯一;
- * 改状态追加新行,同 id 后者为准,不改历史。retracted 用追加行(2026-09-08 拍板)。
+ * 产物账本:artifacts.jsonl,追加式、一行一条、id 唯一;改状态追加新行,同 id 后者为准,不改历史。
+ * 观察不在这里:观察的真相是 vault 的日记(《obsidian仓库设计.md》§1),老师记账时回「## 记账」段、应用写日记。
  */
 import { z } from 'zod';
-export declare const EvidenceSchema: z.ZodUnion<readonly [z.ZodObject<{
-    conversation: z.ZodString;
-    job: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>, z.ZodObject<{
-    artifact: z.ZodString;
-}, z.core.$strip>]>;
-export type Evidence = z.infer<typeof EvidenceSchema>;
-/** 完整观察行 */
-export declare const ObservationSchema: z.ZodObject<{
-    id: z.ZodString;
-    date: z.ZodString;
-    author: z.ZodString;
-    subject: z.ZodOptional<z.ZodString>;
-    topic: z.ZodOptional<z.ZodString>;
-    claim: z.ZodString;
-    evidence: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
-        conversation: z.ZodString;
-        job: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>, z.ZodObject<{
-        artifact: z.ZodString;
-    }, z.core.$strip>]>>;
-    retracted: z.ZodDefault<z.ZodBoolean>;
-}, z.core.$strip>;
-export type Observation = z.infer<typeof ObservationSchema>;
-/** 纠错行:只带 id + retracted + 谁 + 何时 */
-export declare const ObservationRetractSchema: z.ZodObject<{
-    id: z.ZodString;
-    retracted: z.ZodLiteral<true>;
-    by: z.ZodString;
-    date: z.ZodString;
-}, z.core.$strip>;
-export type ObservationRetract = z.infer<typeof ObservationRetractSchema>;
-export declare const ObservationLineSchema: z.ZodUnion<readonly [z.ZodObject<{
-    id: z.ZodString;
-    date: z.ZodString;
-    author: z.ZodString;
-    subject: z.ZodOptional<z.ZodString>;
-    topic: z.ZodOptional<z.ZodString>;
-    claim: z.ZodString;
-    evidence: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
-        conversation: z.ZodString;
-        job: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>, z.ZodObject<{
-        artifact: z.ZodString;
-    }, z.core.$strip>]>>;
-    retracted: z.ZodDefault<z.ZodBoolean>;
-}, z.core.$strip>, z.ZodObject<{
-    id: z.ZodString;
-    retracted: z.ZodLiteral<true>;
-    by: z.ZodString;
-    date: z.ZodString;
-}, z.core.$strip>]>;
-export type ObservationLine = z.infer<typeof ObservationLineSchema>;
-export declare const ARTIFACT_KINDS: readonly ["课包", "补讲", "批改", "计划", "其它"];
-export declare const ARTIFACT_STATUS: readonly ["draft", "ready", "accepted", "retired"];
+export declare const ARTIFACT_KINDS: readonly ["课包", "其它"];
+export declare const ARTIFACT_STATUS: readonly ["draft", "ready", "retired"];
 export type ArtifactStatus = (typeof ARTIFACT_STATUS)[number];
 /** 产物事件行:首行要带 kind / by / path,后续行只带变化的字段 */
 export declare const ArtifactEventSchema: z.ZodObject<{
     id: z.ZodString;
     kind: z.ZodOptional<z.ZodEnum<{
         课包: "课包";
-        补讲: "补讲";
-        批改: "批改";
-        计划: "计划";
         其它: "其它";
     }>>;
     by: z.ZodOptional<z.ZodString>;
@@ -74,7 +18,6 @@ export declare const ArtifactEventSchema: z.ZodObject<{
     status: z.ZodOptional<z.ZodEnum<{
         ready: "ready";
         draft: "draft";
-        accepted: "accepted";
         retired: "retired";
     }>>;
     path: z.ZodOptional<z.ZodString>;
@@ -82,7 +25,8 @@ export declare const ArtifactEventSchema: z.ZodObject<{
         conversation: z.ZodString;
         job: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
-    hash: z.ZodOptional<z.ZodString>;
+    costUsd: z.ZodOptional<z.ZodNumber>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type ArtifactEvent = z.infer<typeof ArtifactEventSchema>;
 /** 折叠后的产物 */
@@ -94,7 +38,8 @@ export interface Artifact {
     status: ArtifactStatus;
     path?: string;
     source?: ArtifactEvent['source'];
-    hash?: string;
+    costUsd?: number;
+    durationMs?: number;
     /** 最后一次事件时间 */
     updatedAt: string;
 }