cotutor 0.2.0 → 0.3.0

package/dist/runtime/live/turns.d.ts

@@ -0,0 +1,48 @@
+import type { ContextPack } from '../../schema/index.ts';
+import { type Runner, type SendStarted } from '../runner.ts';
+import type { Echo } from '../delivery/queue.ts';
+export interface TurnsDeps {
+    runner: Runner;
+    now(): Date;
+    tutor: string;
+    /** 哪一台设备(升级请求里的设备 cookie):孩子发的每一条记上 */
+    deviceId?: string | null;
+    /** 这一轮实时的那些(接住时说的、念到第几句被打断、摸底、打电话几分钟…);body = 孩子端发来的那条(收下了才问) */
+    live(body: Record<string, unknown>): NonNullable<ContextPack['live']>;
+    /** 发给孩子端 */
+    send(o: Record<string, unknown>): void;
+    /** 脑开始写这一轮 */
+    started(s: SendStarted): void;
+    /** 一轮写完了,正式的那一节的讲稿(流式时没发出来的由调用方按序号补) */
+    lines(job: string, lines: {
+        i: number;
+        text: string;
+        play?: boolean;
+        echo?: Echo;
+        call?: true;
+    }[]): void;
+    /** 一轮写完了(成没成都算)、排着的也发出去了 */
+    settled(): void;
+    /** 定时器交给调用方收(挂电话时清) */
+    timer(t: NodeJS.Timeout): void;
+    ended(): boolean;
+}
+export declare class Turns {
+    private running;
+    /** 脑忙时孩子又说的:等它写完合并成一条 */
+    private waiting;
+    /** 脑最近写的那一轮的话题(应用起的那一轮接在它后面) */
+    private last;
+    private readonly deps;
+    constructor(deps: TurnsDeps);
+    /** 脑在写 */
+    get busy(): boolean;
+    get thread(): string | null;
+    /** 交给脑;脑在写就排着,它写完合并发 */
+    submit(body: Record<string, unknown>): Promise<void>;
+    private dispatch;
+    /** 别处在写:等那一轮完了再发排着的 */
+    private afterBusy;
+    /** 脑忙时孩子说的几句:合并成一条(话题等照最后一句的),发 */
+    private flushWaiting;
+}

package/dist/runtime/live/turns.js

@@ -0,0 +1,102 @@
+/**
+ * 实时那一轮交给脑(从 call.ts 拆出来,2026-10-29,行为不变;以后是 runtime/turn):
+ * 孩子端发来的那条验过、拼好(runner.accept,和 HTTP 共用),带上这一轮实时的那些(live:)交给 runner.send;
+ * 这位老师别处正在写(BusyError)就排着,它写完把排着的几句合并成一条再发;脑在写时孩子又说的(submit 时 running)也排着,这一轮写完一起发。
+ * 一轮写完,收尾时把流式没发出来的讲稿从正式的一节补上(整块出的运行时、最后几句)。
+ */
+import { lineFlags } from "../../board/parse.js";
+import { localDate } from "../../shared/time.js";
+import { adoptPaper } from "../../board/paper.js";
+import { BusyError } from "../runner.js";
+import { readIndex } from "../journal/store.js";
+export class Turns {
+    running = null;
+    /** 脑忙时孩子又说的:等它写完合并成一条 */
+    waiting = [];
+    /** 脑最近写的那一轮的话题(应用起的那一轮接在它后面) */
+    last = null;
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** 脑在写 */
+    get busy() {
+        return this.running !== null;
+    }
+    get thread() {
+        return this.last;
+    }
+    /** 交给脑;脑在写就排着,它写完合并发 */
+    async submit(body) {
+        if (this.running) {
+            this.waiting.push(body);
+            return;
+        }
+        await this.dispatch(body);
+    }
+    async dispatch(body) {
+        const { runner, tutor } = this.deps;
+        const { app: _app, ...rest } = body;
+        const r = await runner.accept(tutor, rest, localDate(this.deps.now()), this.deps.deviceId);
+        if ('reject' in r) {
+            this.deps.send({ t: 'err', status: r.reject.status, error: r.reject.error });
+            return;
+        }
+        const live = this.deps.live(body);
+        let started;
+        try {
+            started = await runner.send(tutor, { ...r.input, live });
+        }
+        catch (err) {
+            // 别处(页面、工作台)正在让这位老师写:排着,它写完再发
+            if (err instanceof BusyError) {
+                this.waiting.push(body);
+                this.afterBusy();
+                return;
+            }
+            this.deps.send({ t: 'err', status: 500, error: err instanceof Error ? err.message : String(err) });
+            return;
+        }
+        this.running = started;
+        this.deps.started(started);
+        this.last = started.thread;
+        // 新话题的第一条:话题还没有时画的那张纸归它
+        if (started.thread === started.job)
+            void adoptPaper(runner.ws, tutor, started.date, started.thread);
+        const job = started.job;
+        void started.done
+            .then(async (index) => {
+            // 收尾:整块出的运行时、或流式时没发出来的最后几句,从正式的一节补上
+            const m = index.messages.find((x) => x.job === job) ?? (await readIndex(runner.ws, tutor, started.date)).messages.find((x) => x.job === job);
+            const sec = m?.section;
+            if (sec)
+                this.deps.lines(job, sec.lines.map((l, i) => ({ i, text: l.text, ...lineFlags(l, sec.cards) })));
+        }, () => { })
+            .finally(() => {
+            if (this.running === started)
+                this.running = null;
+            this.flushWaiting();
+            this.deps.settled();
+        });
+    }
+    /** 别处在写:等那一轮完了再发排着的 */
+    afterBusy() {
+        const { runner, tutor } = this.deps;
+        const busy = runner.running(tutor);
+        const poll = setInterval(() => {
+            if (this.deps.ended() || runner.running(tutor)?.job === busy?.job)
+                return;
+            clearInterval(poll);
+            this.flushWaiting();
+        }, 200);
+        this.deps.timer(poll);
+    }
+    /** 脑忙时孩子说的几句:合并成一条(话题等照最后一句的),发 */
+    flushWaiting() {
+        if (this.deps.ended() || this.running || !this.waiting.length)
+            return;
+        const all = this.waiting.splice(0);
+        const last = all[all.length - 1];
+        void this.dispatch({ ...last, text: all.map((b) => String(b.text ?? '').trim()).filter(Boolean).join('\n') });
+    }
+}

package/dist/runtime/runner.d.ts

@@ -0,0 +1,289 @@
+/**
+ * 发消息 = 拼上下文包 → 按运行时 spawn / resume → stream-json 落 conversations/<老师>/<日期>.<job>.log → 索引更新
+ * (最终文本 → 板书节 section + 家长尾巴 parentText + 解析提醒 warnings)。
+ * 流式:stdout 经本进程落盘,同时喂 PartialReader 拼当前回复正文 → parseBoard(partial) → 内存里的 partial section
+ * (孩子端 pending 条目带着它,卡随围栏闭合逐张出现);讲稿不配音,交给实时的嘴照念。
+ * 点读段、单词等卡的资产在索引写好之后后台配,孩子端点到还没好的段等它到,等不到就不出声。
+ * 一老师同时只跑一条(老师还在回上一条就 409),跨天自动新开(索引按本地日期分文件,新文件没 session 就不带 --resume)。
+ * 话题(2026-09-11):一天可多个,每个话题自己的会话(index.sessions[thread]);newThread / 系统消息 / 今天第一条开新话题(不 resume、不带旧卡),
+ * 指定 thread 接着今天的旧话题(resume 它的会话),缺省接当前话题。
+ * 埋点(2026-09-11):每轮记 timing(进程起的时刻、首卡、进程退出、配音收尾,毫秒),家长视图每轮一行。
+ * 进程 cwd 是老师目录 agents/<name>/。
+ */
+import { type IncomingMark } from './lecture.ts';
+import { type BrainExecutor, type Slot } from '../brain/index.ts';
+import { type BoardSection, type Device } from '../board/presentation.ts';
+import { type RunPlan } from '../brain/cli/run-plan.ts';
+import { type RunEvent, type RunEventEnvelope } from '../schema/index.ts';
+import { type ContextPack, type ConversationIndex, type ActivityRun, type ConversationMessage, type Focus, type MessageFrom, type MessageVia } from '../schema/index.ts';
+import type { Workspace } from '../schema/index.ts';
+import { type PackReport } from '../memory/context.ts';
+import type { Retrieved } from '../memory/retrieval.ts';
+import { type KidAccept } from './kid-input.ts';
+import { type Draw } from '../media/draw.ts';
+export declare class BusyError extends Error {
+    constructor(tutor: string, job: string);
+}
+export interface SendInput {
+    from: MessageFrom;
+    /** 从首页的 activity 按钮起的新话题(或 cotutor send --activity):哪个 activity、点的那一刻的参数;记在这条消息上,话题后面每条照它带 */
+    activity?: ActivityRun;
+    /** 口语课页的哪份口语单(只在话题第一条) */
+    talk?: string;
+    /** 带 action 时可以是空的:交给老师 → 「(交了答案,没说话)」 */
+    text: string;
+    focus?: Focus;
+    /** 孩子端的动作:继续 / 交给老师(把改过的卡交出去) */
+    action?: 'submit';
+    /** 运行时名,缺省 cotutor.json 的 runtimes.default */
+    runtime?: string;
+    /** 开新话题:不 resume、不带旧话题卡上的状态;话题 id = 这条的 job */
+    newThread?: boolean;
+    /** 接着今天的某个话题聊(话题 id);缺省 = 当前(末条所在的)话题。from: system 的永远开新话题 */
+    thread?: string;
+    /** 孩子端是什么端(记进消息);缺省当平板横屏 */
+    device?: Device;
+    /** 哪一台设备(服务端从 cookie 取) */
+    deviceId?: string;
+    /** 记到哪一天的索引(缺省今天);记账给昨天的话题用 */
+    date?: string;
+    /** 这轮是记账任务(《obsidian仓库设计.md》§6):resume 那个话题的会话,老师回「## 记账」段,应用写日记 */
+    bookkeep?: {
+        thread: string;
+    };
+    /** 这轮是记账后整理记忆(2026-09-18):新会话,「## 记忆」段不受每轮条数上限,孩子端看不到 */
+    tidy?: boolean;
+    /** 这条带的作业照片(相对 workspace 根,已由路由验过在 captures/ 里;R5):进上下文包 photos: 段,老师自己 Read 看图;文字可以空 */
+    photos?: string[];
+    /** 孩子从左栏的纸交的画(路由已验过图在 captures/、摘要按纸上的笔迹算好):图与清掉的那几版排在照片后面进 photos:,上下文包 drawing: 一句;消息记 drawing */
+    drawing?: NonNullable<ConversationMessage['drawing']>;
+    /** 这条是回放(app/replay.ts):原轮的 job,记进消息;调用方已经把 Runner 指到 evals/ */
+    replayOf?: string;
+    /** cotutor activity eval 跑的一轮:不写记忆、不预热(画照画,画家由 eval 换成假的) */
+    eval?: true;
+    /** 孩子看完小课堂后的第一条:上下文包带 lecture:(课的每句、看的情况、画过的几处),消息记 lecture;again = 问过以后再看一遍又画了 */
+    lecture?: {
+        bundle: string;
+        watchedMs: number;
+        finished: boolean;
+        pauses: number;
+        again?: boolean;
+        marks?: IncomingMark[];
+        log?: {
+            t: number;
+            pos: number;
+            play: boolean;
+        }[];
+    };
+    /** 孩子从首页哪个按钮进来的,记进消息 */
+    via?: MessageVia;
+    /** 按钮的字与家长备好的讲法(服务端从发布件查的),进上下文包 home: 段 */
+    home?: {
+        button: string;
+        brief?: string;
+    };
+    /** 这一轮走实时:讲稿不配音(拍关就就绪)、交给嘴照念;消息记 live,上下文包带 live:(嘴接住时说的、上一轮念到第几句被打断;口语课的摸底、打电话几分钟、应用起的这一轮) */
+    live?: NonNullable<ContextPack['live']>;
+    /** 接着以前哪天的哪个话题:这条开新话题时上下文包带那个话题的尾巴(continue: 段),消息记 continues;pack 给了就不现读(回放从原 workspace 读好的) */
+    continues?: {
+        date: string;
+        thread: string;
+        pack?: NonNullable<ContextPack['continue']>;
+    };
+}
+export interface SendStarted {
+    tutor: string;
+    date: string;
+    job: string;
+    /** 这条消息所在的话题 */
+    thread: string;
+    plan: RunPlan;
+    /** 老师说完(进程退出、索引写好)后 resolve */
+    done: Promise<ConversationIndex>;
+}
+export type { PackReport } from '../memory/context.ts';
+/** API 运行时的长话题:上一轮结束时上下文(tokens.context)过了这么多,这一轮整段压缩(2026-10-29 定 32k) */
+export declare const COMPACT_TOKENS = 32000;
+/**
+ * 上下文包的取材(《obsidian仓库设计.md》§7 每轮那行,2026-09-17 改):课程表命中的时段 + 老师守则(有脸的老师)+ 当前学期 + 档案与入口文件的原文(按 entryChars 截)
+ * + 参考路径 + 本周计划里本老师的行 + 最近 14 天日记里本学科的「- 观察:」行。
+ * 守则与笔记原文总是带上;同一话题里没改过的由 send 换成「未变」。
+ */
+export declare function gatherContext(ws: Workspace, tutor: string, input: {
+    from: MessageFrom;
+    at: Date;
+    focus?: Focus;
+    agent?: string;
+    kinds?: readonly string[];
+    query?: string;
+}, report?: PackReport): Promise<ContextPack & {
+    retrieved: Retrieved[];
+}>;
+/**
+ * activity 的那两段:`activity:`(名字、参数、应用算的)每条都带;
+ * 「老师怎么带」那节(按参数与这个话题的卡裁过、剥了注释)+ 这个 activity 多带的卡的写法,作为一条笔记放进话题第一条(<cotutor-activity>),
+ * 续话题没改过写「未变」(同守则)。文件不在、读不了 → activityGuide 写「缺」,老师照自己的文件做。返回给这轮的提醒。
+ */
+export declare function attachActivity(ws: Workspace, tutor: string, pack: ContextPack, run: ActivityRun, where: {
+    date: string;
+    messages: readonly ConversationMessage[];
+    thread: string;
+    now: number;
+}, inSystem?: boolean): Promise<string[]>;
+/** 按老师裁的板书写法落在哪(相对 workspace 根;机器文件,内容变了文件名跟着变) */
+export declare const TUTOR_BOARD_DIR = ".cotutor/board";
+/** activity 在系统提示里时,上下文包 activityGuide 那一行 */
+export declare const ACTIVITY_IN_SYSTEM = "\u5DF2\u5728\u4F60\u7684\u7CFB\u7EDF\u63D0\u793A\u91CC(\u8FD9\u4E2A\u8BDD\u9898\u7684 activity,\u7167\u5B83\u5E26)";
+/**
+ * activity 话题的系统提示(九点五):不读老师文件,人设与做法都是 activity 自己的。
+ *   body   「老师怎么带」按参数与这个话题的卡裁好、剥了注释
+ *   kinds  这个话题的卡:activity 头上的 cards 加 text(不并老师的)
+ *   guide  只讲这几种卡的板书写法,写到 .cotutor/board/
+ *   memory 这个 activity 自己的记忆:agent: <老师>/<activity>,文件名 <老师显示名>·<activity>
+ * activity 文件不在、没有「老师怎么带」→ null(退回老师文件)。
+ */
+export interface ActivityParts {
+    body: string;
+    kinds: string[];
+    guide: {
+        body: string;
+        path: string;
+    };
+    memory: {
+        agent: string;
+        display: string;
+    };
+}
+export declare function activityParts(ws: Workspace, tutor: string, run: ActivityRun): Promise<ActivityParts | null>;
+/**
+ * 这位老师的板书写法:正文 + 相对 workspace 根的路径(给 {boardFile} 与上下文包)。
+ * 没写 cards → 出厂的 cotutor-board SKILL.md;写了 → 按清单从包里现拼(boardGuideFor),写到 .cotutor/board/<老师>-<hash>.md,
+ * 文件名带内容的 hash:清单一改路径就变,预热进程的 argv 对不上,不会拿着旧写法去答。读不到 SKILL.md → null。
+ */
+export declare function boardGuideOf(ws: Workspace, tutor: string): Promise<{
+    body: string;
+    path: string;
+} | null>;
+/**
+ * 板书写法怎么递给老师(2026-09-19):有脸的老师、板书没关才带。运行时预载了 → 上下文包只写一行事实;
+ * 没预载 → 原文作为一条笔记放进话题第一条(<cotutor-board>),排在守则后面,续话题没改过写「未变」。返回板书写法(给 {systemBody} 与 {boardFile})。
+ */
+export declare function attachBoardGuide(ws: Workspace, tutor: string, pack: ContextPack, o: {
+    preloaded: boolean;
+    boardOff: boolean;
+}): Promise<{
+    body: string;
+    path: string;
+} | null>;
+/** 这轮带的笔记版本:role → `路径@hash`(记进消息;同一话题下一轮对得上就不再带原文) */
+export declare function noteVersions(pack: ContextPack): Record<string, string>;
+/** 续会话时:上一轮这个话题已经带过、版本没变的笔记去掉原文,YAML 里注明「未变」 */
+export declare function dropSeenNotes(pack: ContextPack, seen: Record<string, string>): ContextPack;
+/** 这个话题里最近一次记下的笔记版本(新话题、没记过 → {}) */
+export declare function seenNotes(messages: readonly ConversationMessage[], thread: string): Record<string, string>;
+/** 老师该读得到的目录:workspace 根(作业照片、技能)与 vault(教材、日记);会话 cwd 是老师目录,这些在它外面(qwen 读外面要先划进来) */
+export declare function readDirsOf(ws: Workspace): string[];
+/** 干跑:现在给这位老师发这句话,上下文包会是什么样、每段从哪来、截了多少;不起模型、不写盘 */
+export declare function packDryRun(ws: Workspace, tutor: string, input: {
+    from: MessageFrom;
+    at: Date;
+    text: string;
+    activity?: ActivityRun;
+}): Promise<{
+    prompt: string;
+    pack: ContextPack;
+    report: PackReport;
+}>;
+/** 上下文包的 vault: 段:root 绝对,其余角色相对 root;在 root 外面(家长把日记指到别处)就给绝对路径 */
+export declare function vaultPack(paths: Workspace['paths']): NonNullable<ContextPack['vault']>;
+export declare class Runner {
+    private readonly active;
+    /** 还在后台跑的资产生成(测试与关服前 flush) */
+    private readonly background;
+    private readonly getWs;
+    private readonly opts;
+    private readonly listeners;
+    /** noteEvent 每个事件文件一条追加链 */
+    private readonly notes;
+    /** 脑执行:起老师、读输出、断流接着跑、预热下一轮(src/brain/) */
+    readonly brain: BrainExecutor;
+    /** 预热池的旧入口(测试看有没有、杀掉);迁完删 */
+    get spares(): {
+        has(tutor: string, slot?: Slot): boolean;
+        drop(tutor: string, slot?: Slot): void;
+    };
+    /** 页面拉今天时的预热:每位老师(与带的话题)上次看的时刻 */
+    private readonly prewarmedAt;
+    /** 起子进程用的环境(测试注入) */
+    get env(): NodeJS.ProcessEnv | undefined;
+    /** 当前的 workspace(cotutor.json 热重载后是新的;实时老师经它拿) */
+    get ws(): Workspace;
+    /** 画图卡交给谁画(测试与 mock 注入假的) */
+    readonly draw: Draw;
+    constructor(getWs: () => Workspace, opts?: {
+        now?: () => Date;
+        env?: NodeJS.ProcessEnv;
+        warmIdleMs?: number;
+        warm?: boolean;
+        draw?: Draw;
+    });
+    /** 孩子端发一条的验与拼(HTTP 与实时老师共用,./kid-input.ts):拼成 send 的入参,或回 reject;不起老师 */
+    accept(tutor: string, body: unknown, date: string, deviceId?: string | null): Promise<KidAccept>;
+    running(tutor: string): {
+        job: string;
+        date: string;
+    } | null;
+    /** 等所有后台资产生成完(测试用) */
+    flush(): Promise<void>;
+    /** 订阅每一轮的事件(runtime/journal/events.ts;cotutor send 现场打印、serve --trace);返回退订函数。事件同时追加到 <日期>.<job>.events.jsonl */
+    onEvent(fn: (e: RunEventEnvelope) => void): () => void;
+    /** 别处给某一轮补事件(实时老师的嘴,src/runtime/live/call.ts;t 已经换成离这一轮老师进程起来的毫秒):追加到 events.jsonl、给订阅者;这一轮跑完了也行 */
+    noteEvent(tutor: string, date: string, job: string, event: RunEvent): Promise<void>;
+    /** 杀掉所有预热的进程(测试收尾;服务退出时它们的 stdin 断了会自己退) */
+    close(): void;
+    /**
+     * 预热:给这位老师起好下一轮的进程,两个位置都补齐——
+     * fresh:新开会话(新话题、接着上次都用它);
+     * resume:接 thread(页面选着的话题;不给或今天没有 = 当天末条所在的话题,和 send 缺省一样)的会话,它没有会话就不留。
+     * 只给有脸的、开着的、运行时 stdin: "stream-json"、这会儿没在跑的老师起;throttleMs 内同一话题看过就不再看(页面轮询今天)。
+     * 起了返回 true;起不了不报错,下一轮冷起。warm: false(cotutor send:跑完就退,留着备用进程会把它挂一小时)不起。
+     */
+    prewarm(tutor: string, opts?: {
+        throttleMs?: number;
+        thread?: string;
+    }): Promise<boolean>;
+    /** 正在回的那条已经出来的板书(流式);没在跑或还没出卡 → null */
+    partial(tutor: string): BoardSection | null;
+    send(tutor: string, input: SendInput): Promise<SendStarted>;
+    /** send 的后半:占位已在 active 里,这里读索引、拼包、起进程;抛了由 send 放掉占位 */
+    private begin;
+    /**
+     * 记账(《obsidian仓库设计.md》§4 / §6):家长晚上点一次。这天索引里每个还没记过、有孩子的话或打了分的话题,各起一轮记账任务
+     * (from: system、resume 那个话题的会话,消息正文是 bookkeepingPrompt),顺着跑,老师回的「## 记账」段由 settleDiary 落进日记。
+     * 立刻返回排了哪些、跳过哪些;链在后台跑(flush 会等,done 也行)。老师正忙 → BusyError。
+     * tidy: false 记完不整理记忆(自动记账记今天的话题时,孩子晚上可能还来,src/runtime/auto-bookkeep.ts)。
+     */
+    bookkeep(tutor: string, date: string, only?: string[], opts?: {
+        tidy?: boolean;
+    }): Promise<{
+        queued: string[];
+        skipped: {
+            thread: string;
+            why: string;
+            oldRuntime?: string;
+        }[];
+        done: Promise<void>;
+    }>;
+    /**
+     * 记账后整理记忆:这位老师有记忆文件、里面有条目才起一轮(新会话、from: system、tidy);没有就返回 null。
+     * 老师回的「## 记忆」段照单落盘(settleMemory 不限条数)。
+     */
+    tidyMemory(tutor: string, date: string): Promise<SendStarted | null>;
+    /**
+     * 「## 记忆」段 → 建议与要怎么改,还不写:讲课的轮每轮最多 MEMORY_MAX_PER_TURN 条(整理轮不限);回放、eval 不写。
+     * 证据对孩子在这个话题里说过的话(整理轮自成话题,对这一天的);有脸的老师写的 `孩子:` 进孩子的记忆。
+     * seen = 这轮上下文包里老师看到的那两篇的版本(消息的 notes.memory / notes.child,`路径@hash`)
+     */
+    private planMemoryOf;
+    private spawn;
+}