cotutor 0.2.0 → 0.4.0

package/dist/schema/context-pack.js

@@ -1,32 +1,113 @@
 /**
- * 上下文包:应用在每条消息前拼的固定 YAML 块(《cotutor契约草案.md》§2)。老师不用自己找上下文。
+ * 上下文包:应用在每条消息前拼的固定 YAML 块,后面接家长笔记的原文段。老师不用自己找上下文。
  * 孩子由 workspace 决定,不进包。
  */
 import { z } from 'zod';
-export const MESSAGE_FROM = ['kid', 'parent', 'system'];
+import { ActivityValueSchema } from "./activity.js";
+/** 消息是谁发的:孩子(孩子端、工作台、cotutor send),或应用派的任务(记账、整理记忆、画图作业)。上下文包里不写,老师面前只有孩子;系统任务的消息正文自己说明是什么活 */
+export const MESSAGE_FROM = ['kid', 'system'];
 export const FocusSchema = z.object({
-    /** 当前对象(产物 id) */
-    artifact: z.string().optional(),
-    /** 正在看的 step */
-    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),
     /** 本地时间,分钟精度,如 2026-09-08T16:20 */
     at: z.string().min(1),
     /** 课程表命中的时段,如「数学 16:00-17:00」 */
     slot: z.string().optional(),
     focus: FocusSchema.optional(),
+    /** 老师守则(机器技能 cotutor-tutor 的 SKILL.md,有脸的老师才带):相对 workspace 根的路径 + 状态(未变 / 缺);原文在 notes */
+    rules: z.string().optional(),
+    /** 当前学期(档案的 school_start 按日期算,或档案 semester 覆盖),如「二年级上」;算不出不写 */
+    semester: z.string().optional(),
+    /** 板书写法(机器技能 cotutor-board)在哪:「已在系统提示里」,或相对 workspace 根的路径 + 状态(未变 / 缺),原文在 notes(<cotutor-board>);board: off 时不带 */
+    boardGuide: z.string().optional(),
+    /** 档案(vault 里 `cotutor: profile` 的那篇):相对 vault 根的路径 + 状态(未变 / 截断 / 缺);原文在 notes */
+    profile: z.string().optional(),
+    /** 这位老师的入口文件(`cotutor: subject`,subject 与学期对上的那篇):路径 + 状态;原文在 notes(《obsidian仓库设计.md》2026-09-17) */
+    entry: z.string().optional(),
+    /** 这位 agent 的记忆文件(`cotutor: memory`、`agent: <名>`):路径 + 状态,或「还没有」;原文在 notes */
+    memory: z.string().optional(),
+    /** 孩子的记忆(`cotutor: memory`、`agent: all`,所有有脸的老师共用,2026-10-30):路径 + 状态,或「还没有」;原文在 notes。有脸的老师才带 */
+    child: z.string().optional(),
+    /** 应用替老师查好的(memory/retrieval.ts,2026-10-30):孩子问到的字在这学期生字表的哪一课、会认还是会写;以前讲过那一课的骨架。孩子的话不带工具,这几行代替老师自己 Grep */
+    lookup: z.array(z.string()).optional(),
+    /** 家长写的那一课的口径(教材那一节的 `### 口径`)在哪:路径 + 课题 + 状态;原文在 notes(<vault-note role="lesson">)。孩子提到那一课、或问到那一课要会写的字时才有 */
+    lesson: z.string().optional(),
+    /** 参考资料的绝对路径:这科这学期的教材 + 档案与入口文件里的 [[链接]];只给路径,老师要用自己 Read(这轮带工具才给) */
+    refs: z.array(z.string()).optional(),
+    /** 整篇带进来的原文(话题第一条、或话题里改过了才带):老师守则(rules)与家长笔记;接在 YAML 块后面,不进 YAML */
+    notes: z.array(z.object({ role: z.enum(['rules', 'boardGuide', 'activityGuide', 'profile', 'child', 'entry', 'memory', 'lesson']), path: z.string().min(1), text: z.string(), cut: z.literal(true).optional() })).optional(),
+    /** 这个话题的 activity 文件(「老师怎么带」那节,按参数裁过,后面接这个 activity 多带的卡的写法):相对 workspace 根的路径 + 状态(未变 / 缺);原文在 notes(<cotutor-activity>) */
+    activityGuide: z.string().optional(),
     /** 本周计划里与本老师相关的行(已按 planLines 截) */
     plan: z.array(z.string()).default([]),
-    /** 最近 N 条本学科观察(已按 recent 截) */
+    /** 最近 N 条本学科观察(从日记的「- 观察:」行抽,最近 14 天,已按 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(),
+    /** 孩子刚看完小课堂:课名、哪份课包、课长、每句的起点与原话、看的情况、画过的几处;看完后的第一条,和问过以后再看一遍又画了的那条 */
+    lecture: z
+        .object({
+        title: z.string().min(1),
+        source: z.string().min(1),
+        length: z.string().min(1),
+        lines: z.array(z.string()).default([]),
+        watched: z.string().min(1),
+        /** 孩子画过的几处,每处一段话(storedMarks):时刻、那时在讲哪句、截图是 photos 第几张、课包的再说画的地方盖着什么 */
+        marks: z.array(z.string()).default([]),
+    })
+        .optional(),
+    /** 孩子从首页的按钮进来:按钮上的字与家长备好的讲法;只在带按钮的那条 */
+    home: z.object({ button: z.string().min(1), brief: z.string().optional() }).optional(),
+    /** 接着以前的话题:那个话题是哪天哪个、叫什么、最后一节的讲稿与卡、索引在哪;只在新话题的第一条 */
+    continue: z
+        .object({
+        from: z.string().min(1),
+        title: z.string().optional(),
+        said: z.array(z.string()).default([]),
+        cards: z.array(z.string()).default([]),
+        index: z.string().min(1),
+    })
+        .optional(),
+    /**
+     * 这一轮走实时:嘴(realtime 模型)已经替老师接住了孩子,讲稿交给嘴照念、不配音。caught = 嘴接住时说的那句;cut = 上一轮的讲稿念到第几句被孩子打断(1 起;0 = 一句都没念到就被打断了;没打断不写)。
+     * 口语课:warmup = 热身的摸底,一拍一行(应用按转写记);phone = 打电话打了几分钟(0 起,还没打不写);
+     * app = 这一轮不是孩子说的:call = 你念了 [[call]],现在开始打电话;quiet = 热身里孩子连着两拍没开口。
+     * draw = 边画边聊:这张画画着的时候孩子说的和你(嘴)说的,一句一行,按先后
+     */
+    live: z
+        .object({
+        caught: z.string().optional(),
+        cut: z.number().int().nonnegative().optional(),
+        warmup: z.array(z.string()).optional(),
+        phone: z.number().int().nonnegative().optional(),
+        app: z.enum(['call', 'quiet']).optional(),
+        draw: z.array(z.string()).optional(),
+    })
+        .optional(),
+    /** 孩子从左栏的纸交来的画:一句话说它是 photos 第几张、几笔、各颜色几笔、画了多久、清空过几次(清掉的那几版是 photos 第几张) */
+    drawing: z.string().optional(),
+    /**
+     * 孩子从首页的 activity 进来的话题:哪个 activity、家长填的参数(点的那一刻,补了缺省)、应用算的值。
+     * 话题里每条都带;放在 YAML 块最后,键序固定(name、params、state;参数照文件「家长填的」的顺序)
+     */
+    activity: z.object({ name: z.string().min(1), params: z.record(z.string(), ActivityValueSchema).default({}), state: z.record(z.string(), ActivityValueSchema).default({}) }).optional(),
+    /** 这条消息带的作业照片(相对 workspace 根,一行一张;老师先 Read 再答;R5) */
+    photos: z.array(z.string()).optional(),
+    /** photos 里同一批照片的绝对路径,顺序一一对应:Read 工具只认绝对路径,老师的 cwd 在 agents/<名>/,不给就得先 find 一轮(2026-09-18 真跑) */
+    photoFiles: z.array(z.string()).optional(),
+    /** 家长的 Obsidian 仓库在哪(《obsidian仓库设计.md》§7):root 绝对路径,其余角色相对 root(在 root 外面就是绝对路径) */
+    vault: z
+        .object({
+        root: z.string().min(1),
+        diary: z.string().optional(),
+        plans: z.string().optional(),
+        timetable: z.string().optional(),
+        reference: z.string().optional(),
+    })
+        .optional(),
 });
+export const VAULT_PACK_ROLES = ['diary', 'plans', 'timetable', 'reference'];

package/dist/{lib/conversation.d.ts → schema/conversation-files.d.ts}

@@ -1,23 +1,18 @@
 /**
- * 对话索引的纯函数:日期与 job 命名、空索引、把一次运行的结果并进索引(不改旧对象)。
+ * 一老师一天的对话在 conversations/ 下的文件布局、卡的 id 与资产名、卡的状态文件(落盘的契约;读写在 runtime/journal/)。
  */
-import { type ConversationIndex, type ConversationMessage } from '../schema/index.ts';
-import type { KidView } from './kid-view.ts';
-import type { Transcript } from './transcript.ts';
-/** 本地日期 YYYY-MM-DD(对话按本地日切) */
-export declare function localDate(d: Date): string;
-/** 本地时间到分钟 YYYY-MM-DDTHH:MM(上下文包的 at) */
-export declare function localMinute(d: Date): string;
-/** HHMM-<序号>,同一天内不重复 */
-export declare function jobId(d: Date, seq: number): string;
-export declare function emptyIndex(tutor: string, date: string): ConversationIndex;
 export interface ConversationFiles {
     index: string;
     log: (job: string) => string;
     err: (job: string) => string;
-    audio: (job: string) => string;
-    /** 板书讲稿第 n 句的配音(n 从 1 起) */
-    lineAudio: (job: string, n: number) => string;
+    /** 这一轮真发出去的东西:上下文包 + 完整命令行(家长端「看原文」第一站;跑完就丢的话,「老师为什么没看见」永远查不了) */
+    run: (job: string) => string;
+    /** 这一轮的事件流 <date>.<job>.events.jsonl(runtime/journal/events.ts;控制台与时间线的唯一来源) */
+    events: (job: string) => string;
+    /** 录像的实录 <date>.<job>.play.jsonl:孩子端报上来的记在话题当时的末条 job 上,卡的每次存记在卡所在那轮;删话题一起删 */
+    play: (job: string) => string;
+    /** 实时那一轮嘴照念的声音 <date>.<job>.mouth.wav 与每句的起点 .mouth.json(字幕重放,src/runtime/journal/mouth-index.ts;删话题时按 <date>.<job>.* 一起删) */
+    mouth: (job: string, ext: 'wav' | 'json') => string;
     /** 这一轮各张卡的状态目录 <date>.<job>.cards/ */
     cardsDir: (job: string) => string;
     /** 第 n 张卡(0 起)的状态文件 <date>.<job>.cards/<n>.json */
@@ -26,6 +21,8 @@ export interface ConversationFiles {
     cardAssetsDir: (job: string, n: number) => string;
     /** 第 n 张卡的一个资产文件(点读第 k 段 = <k>.mp3) */
     cardAsset: (job: string, n: number, file: string) => string;
+    /** API 运行时这个话题的模型历史 <date>.<话题>.brain.jsonl(src/brain/api.ts;话题 id 就是第一轮的 job,删话题按 <date>.<job>.* 一起删) */
+    brain: (thread: string) => string;
 }
 /** conversations/<tutor>/<date>.json 与 <date>.<job>.log / .err.log / .mp3(整段配音)/ .<n>.mp3(讲稿第 n 句)/ .cards/<n>.json(卡的状态) */
 export declare function conversationFiles(conversationsDir: string, tutor: string, date: string): ConversationFiles;
@@ -44,22 +41,3 @@ export interface CardStateFile {
 export type CardStates = Record<string, Record<number, CardStateFile>>;
 /** job → 卡下标 → 已生成好的资产名(相对 conversations/<老师>/) */
 export type CardAssets = Record<string, Record<number, string[]>>;
-/** 上一轮之后改过状态的卡(按 job、下标排):发消息时逐张 describe 进上下文包 */
-export declare function changedCards(index: {
-    messages: readonly {
-        job: string;
-    }[];
-}, states: CardStates): {
-    job: string;
-    n: number;
-    file: CardStateFile;
-}[];
-export declare function addMessage(index: ConversationIndex, msg: ConversationMessage): ConversationIndex;
-/** 一次运行收尾:写 result / cost / kidText / artifacts,首次拿到 session 就记下 */
-export declare function applyRun(index: ConversationIndex, job: string, run: {
-    transcript: Transcript;
-    kidView: KidView;
-    runtime: string;
-    artifacts?: string[];
-    audio?: string | null;
-}): ConversationIndex;

package/dist/schema/conversation-files.js

@@ -0,0 +1,26 @@
+/** conversations/<tutor>/<date>.json 与 <date>.<job>.log / .err.log / .mp3(整段配音)/ .<n>.mp3(讲稿第 n 句)/ .cards/<n>.json(卡的状态) */
+export function conversationFiles(conversationsDir, tutor, date) {
+    const base = `${conversationsDir}/${tutor}/${date}`;
+    return {
+        index: `${base}.json`,
+        log: (job) => `${base}.${job}.log`,
+        err: (job) => `${base}.${job}.err.log`,
+        run: (job) => `${base}.${job}.run.json`,
+        events: (job) => `${base}.${job}.events.jsonl`,
+        play: (job) => `${base}.${job}.play.jsonl`,
+        mouth: (job, ext) => `${base}.${job}.mouth.${ext}`,
+        cardsDir: (job) => `${base}.${job}.cards`,
+        card: (job, n) => `${base}.${job}.cards/${n}.json`,
+        cardAssetsDir: (job, n) => `${base}.${job}.cards/${n}`,
+        cardAsset: (job, n, file) => `${base}.${job}.cards/${n}/${file}`,
+        brain: (thread) => `${base}.${thread}.brain.jsonl`,
+    };
+}
+/** 资产在孩子端的名字:相对 conversations/<老师>/,/api/audio 认它 */
+export function cardAssetName(date, job, n, file) {
+    return `${date}.${job}.cards/${n}/${file}`;
+}
+/** 卡的 id:<job>/<n>(n 是节里的下标,0 起);页面、上下文包、状态文件名都用它 */
+export function cardId(job, n) {
+    return `${job}/${n}`;
+}