cotutor 0.2.0 → 0.4.0

package/dist/media/tts.d.ts

@@ -0,0 +1,56 @@
+export { TTS_VOICES, type TtsVoice } from './tts-voices.ts';
+/** 音色 id 不带模型前缀时用的合成模型 */
+export declare const TTS_MODEL = "qwen-audio-3.0-tts-plus";
+export interface TtsResult {
+    /** 成功 → 音频文件路径(给了 out 就是 out,不然是缓存里那份);失败 → null */
+    file: string | null;
+    error: string | null;
+}
+export interface TtsOptions {
+    /** 缓存目录(workspace 的 dirs.tts) */
+    cacheDir: string;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+}
+/** 音色 id 的前缀就是模型 */
+export declare function ttsModelOf(voice: string): string;
+/** 这个模型发到哪、带哪把 key;两把 key 都用不上、按量又没有业务空间 id → 原因 */
+export declare function ttsTarget(model: string, env?: NodeJS.ProcessEnv): {
+    url: string;
+    key: string;
+    plan: boolean;
+} | {
+    error: string;
+};
+/** 一句要合成的:字、音色、语气;给了 out 就把音频放到那里(缓存里留一份) */
+export interface Say {
+    text: string;
+    voice: string;
+    instruction?: string;
+    out?: string;
+}
+/** 合成一句 */
+export declare function synthesize(say: Say, opts: TtsOptions): Promise<TtsResult>;
+/**
+ * 一轮的配音队列:卡自己的声音(点读段、单词),三个并行,先进先出。
+ * 每个文件一项;失败写 err.log、结果 null。
+ */
+export declare class DubQueue {
+    private readonly queue;
+    private running;
+    private readonly voice;
+    private readonly err;
+    private readonly opts;
+    /** 每条的进展(排队 / 完成 / 失败)报给谁:runner 把它变成 tts 道的事件 */
+    report?: (e: {
+        kind: 'queued' | 'done' | 'failed';
+        label: string;
+        ms: number;
+        file?: string;
+        error?: string;
+    }) => void;
+    constructor(voice: string, err: string, opts: TtsOptions);
+    /** 合成 text 到 out;resolve 成文件名(最后一段)或 null;label 是 err.log 里的称呼 */
+    add(out: string, text: string, label: string): Promise<string | null>;
+    private pump;
+}

package/dist/media/tts.js

@@ -0,0 +1,174 @@
+/**
+ * 配音:卡自己的声音(点读段、单词、听写念的词)与音色页的试听;讲稿不配音,由实时的嘴照念。
+ * 百炼 Qwen-Audio-TTS 的非实时合成(2026-10-31 从 voxtell 并进来,不再起子进程):POST 回一个 24 小时有效的音频地址,马上下载。
+ * 走哪条线按模型定(src/shared/qianwen.ts):Token Plan 有这个模型就走它;否则百炼按量,端点是业务空间的域名(voxtell 2026-08-07 实测,公网域名不认)。
+ * 模型看音色 id 的前缀(qwen-audio-3.0-tts-plus-xxx / -flash-xxx,flash 的音色给 plus 回 400);没前缀的老短名走 TTS_MODEL。
+ * 缓存:按「模型 + 音色 + 字 + 格式(+ 语气)」寻址,放在调用方给的目录(workspace 的 .cotutor/tts/);同一句同一个音色合成过就直接给那个文件,不再花钱。
+ * 语气(instruction)只有课包配音用(cotutor chalk dub --instruction),卡的配音不带。
+ * 失败不抛、不响:结果带原因(不含 key),调用方写进 err.log 或回给家长端;孩子端点了不出声。
+ * 测试与探针:COTUTOR_TTS_ENDPOINT 指到假百炼(tests/_fake-tts.ts)。
+ */
+import { createHash } from 'node:crypto';
+import { appendFile, copyFile, mkdir, rename, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { bailianWorkspaceId, qianwenKeys, qianwenLine, ttsUrl, workspaceHost } from "../shared/qianwen.js";
+export { TTS_VOICES } from "./tts-voices.js";
+/** 音色 id 不带模型前缀时用的合成模型 */
+export const TTS_MODEL = 'qwen-audio-3.0-tts-plus';
+const FORMAT = 'mp3';
+const SAMPLE_RATE = 24000;
+/** 网络错、5xx、429 最多试几次(间隔 1.5 秒、3 秒);参数与鉴权错不重试 */
+const ATTEMPTS = 3;
+/** 音色 id 的前缀就是模型 */
+export function ttsModelOf(voice) {
+    return /^(qwen-audio-[\d.]+-tts-[a-z]+)-/.exec(voice)?.[1] ?? TTS_MODEL;
+}
+/** 这个模型发到哪、带哪把 key;两把 key 都用不上、按量又没有业务空间 id → 原因 */
+export function ttsTarget(model, env = process.env) {
+    const line = qianwenLine(model, qianwenKeys(env));
+    const fake = env.COTUTOR_TTS_ENDPOINT?.trim();
+    if (fake)
+        return { url: fake, key: line?.key ?? 'sk-test', plan: false };
+    if (!line)
+        return { error: '没有百炼的 key(家长端「首页」里填)' };
+    if (line.plan)
+        return { url: ttsUrl(line.host), key: line.key, plan: true };
+    const ws = bailianWorkspaceId(env);
+    if (!ws)
+        return { error: '按量的配音要百炼的业务空间 id(家长端「首页」里填)' };
+    return { url: ttsUrl(workspaceHost(ws)), key: line.key, plan: false };
+}
+/** 同一个文件正在合成:后来的等它,不再花一次钱 */
+const inflight = new Map();
+/** 合成一句 */
+export async function synthesize(say, opts) {
+    const model = ttsModelOf(say.voice);
+    const key = createHash('sha256').update(JSON.stringify({ format: FORMAT, ...(say.instruction ? { instruction: say.instruction } : {}), model, sampleRate: SAMPLE_RATE, text: say.text, voice: say.voice })).digest('hex');
+    const cached = join(opts.cacheDir, `${key.slice(0, 24)}.${FORMAT}`);
+    let r;
+    if ((await stat(cached).catch(() => null))?.size)
+        r = { file: cached, error: null };
+    else {
+        let p = inflight.get(cached);
+        if (!p) {
+            p = fetchAudio(model, say, cached, opts).finally(() => inflight.delete(cached));
+            inflight.set(cached, p);
+        }
+        r = await p;
+    }
+    if (!r.file || !say.out)
+        return r;
+    try {
+        await copyFile(r.file, say.out);
+        return { file: say.out, error: null };
+    }
+    catch (err) {
+        return { file: null, error: `合成好了但放不到 ${say.out}:${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function fetchAudio(model, say, file, opts) {
+    const fail = (error) => ({ file: null, error });
+    const target = ttsTarget(model, opts.env ?? process.env);
+    if ('error' in target)
+        return fail(target.error);
+    const timeoutMs = opts.timeoutMs ?? 60_000;
+    let last = '';
+    for (let attempt = 1; attempt <= ATTEMPTS; attempt++) {
+        if (attempt > 1)
+            await sleep(1500 * (attempt - 1));
+        try {
+            const res = await fetch(target.url, {
+                method: 'POST',
+                headers: { authorization: `Bearer ${target.key}`, 'content-type': 'application/json' },
+                body: JSON.stringify({ model, input: { text: say.text, voice: say.voice, format: FORMAT, sample_rate: SAMPLE_RATE, ...(say.instruction ? { instruction: say.instruction } : {}) } }),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            const raw = await res.text();
+            let j = {};
+            try {
+                j = JSON.parse(raw);
+            }
+            catch {
+                /* 不是 JSON:按状态码说 */
+            }
+            const detail = `${j.code ?? ''} ${j.message ?? raw.slice(0, 200)}`.trim();
+            if (res.status === 401 || res.status === 403)
+                return fail(`百炼不认这把 key(HTTP ${res.status}:${detail});看家长端「首页」里填的 key${target.plan ? '' : '与业务空间'},业务空间要开通 ${model}`);
+            if (res.status === 429 || res.status >= 500) {
+                last = `百炼${res.status === 429 ? '限流或额度不够' : '出错'}(HTTP ${res.status}:${detail})`;
+                continue;
+            }
+            if (!res.ok)
+                return fail(`合成被拒(HTTP ${res.status}:${detail});核对音色 ${say.voice} 和字`);
+            const url = j.output?.audio?.url;
+            if (!url)
+                return fail(`百炼没给音频地址(request_id ${j.request_id ?? '?'})`);
+            const audio = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+            if (!audio.ok) {
+                last = `下载音频失败(HTTP ${audio.status})`;
+                continue;
+            }
+            const bytes = Buffer.from(await audio.arrayBuffer());
+            if (!bytes.length)
+                return fail('百炼给的音频是空的');
+            // 先写到旁边再改名:缓存里只有整份(别的请求看见就能直接给)
+            await mkdir(opts.cacheDir, { recursive: true });
+            const tmp = `${file}.${process.pid}.tmp`;
+            await writeFile(tmp, bytes);
+            await rename(tmp, file);
+            return { file, error: null };
+        }
+        catch (err) {
+            last = err instanceof Error && err.name === 'TimeoutError' ? `等了 ${timeoutMs / 1000} 秒没合成完` : `连不上百炼:${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    return fail(last);
+}
+/**
+ * 一轮的配音队列:卡自己的声音(点读段、单词),三个并行,先进先出。
+ * 每个文件一项;失败写 err.log、结果 null。
+ */
+export class DubQueue {
+    queue = [];
+    running = 0;
+    voice;
+    err;
+    opts;
+    /** 每条的进展(排队 / 完成 / 失败)报给谁:runner 把它变成 tts 道的事件 */
+    report;
+    constructor(voice, err, opts) {
+        this.voice = voice;
+        this.err = err;
+        this.opts = opts;
+    }
+    /** 合成 text 到 out;resolve 成文件名(最后一段)或 null;label 是 err.log 里的称呼 */
+    add(out, text, label) {
+        return new Promise((resolve) => {
+            this.report?.({ kind: 'queued', label, ms: 0 });
+            const t0 = Date.now();
+            this.queue.push(async () => {
+                const r = await synthesize({ text, voice: this.voice, out }, this.opts);
+                if (r.error)
+                    await appendFile(this.err, `cotutor tts: ${label}没合成(${r.error});这段不出声\n`).catch(() => { });
+                const file = out.slice(out.lastIndexOf('/') + 1);
+                if (r.error)
+                    this.report?.({ kind: 'failed', label, ms: Date.now() - t0, error: r.error });
+                else
+                    this.report?.({ kind: 'done', label, ms: Date.now() - t0, file });
+                resolve(r.error ? null : file);
+            });
+            this.pump();
+        });
+    }
+    pump() {
+        while (this.running < 3 && this.queue.length) {
+            const job = this.queue.shift();
+            this.running++;
+            void job().finally(() => {
+                this.running--;
+                this.pump();
+            });
+        }
+    }
+}

package/dist/media/vision.d.ts

@@ -0,0 +1,25 @@
+export type Seen = {
+    ok: true;
+    text: string;
+    ms: number;
+} | {
+    ok: false;
+    error: string;
+    ms: number;
+};
+export interface LookAt {
+    image: {
+        data: Buffer;
+        mime: string;
+    };
+    prompt: string;
+    model: string;
+    /** 请求体里多带的(modalities、reasoning_effort、temperature、enable_thinking…) */
+    params?: Record<string, unknown>;
+    timeoutMs: number;
+    env?: NodeJS.ProcessEnv;
+    /** 测试与探针:假的接口地址 */
+    endpoint?: string;
+    onDelta?: (text: string) => void;
+}
+export declare function lookAt(o: LookAt): Promise<Seen>;

package/dist/media/vision.js

@@ -0,0 +1,71 @@
+/**
+ * 看一张图(百炼 Chat Completions 的流式接口:一张图 + 一段提示词)。从 app/talk/list.ts、app/dictation/recognize.ts 拆出来(2026-10-29,行为不变):
+ * key 与端点按模型定(src/shared/qianwen.ts:Token Plan 有这个模型就走它,否则百炼按量),key 只进请求头;出错、超时都不抛。
+ * 两种读法:
+ * - 不给 onDelta:整段收完再拼(readStream),流里有一块报错就算没成(bad_reply)。口语单这样读
+ * - 给 onDelta:一块一块交出去(拍照认词要边认边出),读不懂的行跳过
+ * 怎么写提示词、回的字怎么解析是场景的事(scenes/),这里只管请求。
+ */
+import { chatUrl, qianwenKeys, qianwenLine, readStream } from "../shared/qianwen.js";
+/** 兼容接口的流(data: {...} 一行一块)里的一块 → delta.content;不是内容块 → '' */
+function deltaOf(line) {
+    const s = line.trim();
+    if (!s.startsWith('data:') || s === 'data: [DONE]')
+        return '';
+    try {
+        const j = JSON.parse(s.slice(5));
+        const c = j.choices?.[0]?.delta?.content;
+        return typeof c === 'string' ? c : '';
+    }
+    catch {
+        return '';
+    }
+}
+export async function lookAt(o) {
+    const env = o.env ?? process.env;
+    const t0 = Date.now();
+    const fail = (error) => ({ ok: false, error, ms: Date.now() - t0 });
+    const line = qianwenLine(o.model, qianwenKeys(env));
+    if (!line)
+        return fail('no_key');
+    try {
+        const res = await fetch(o.endpoint ?? chatUrl(line.host), {
+            method: 'POST',
+            headers: { authorization: `Bearer ${line.key}`, 'content-type': 'application/json' },
+            body: JSON.stringify({ model: o.model, stream: true, ...o.params, messages: [{ role: 'user', content: [{ type: 'image_url', image_url: { url: `data:${o.image.mime};base64,${o.image.data.toString('base64')}` } }, { type: 'text', text: o.prompt }] }] }),
+            signal: AbortSignal.timeout(o.timeoutMs),
+        });
+        if (o.onDelta) {
+            if (!res.ok || !res.body)
+                return fail(`http_${res.status}`);
+            const dec = new TextDecoder();
+            let sse = '';
+            let text = '';
+            for await (const chunk of res.body) {
+                sse += dec.decode(chunk, { stream: true });
+                let i;
+                while ((i = sse.indexOf('\n')) >= 0) {
+                    const d = deltaOf(sse.slice(0, i));
+                    sse = sse.slice(i + 1);
+                    if (d) {
+                        text += d;
+                        o.onDelta(d);
+                    }
+                }
+            }
+            const d = deltaOf(sse);
+            text += d;
+            o.onDelta(d);
+            return { ok: true, text, ms: Date.now() - t0 };
+        }
+        if (!res.ok)
+            return fail(`http_${res.status}`);
+        const text = readStream(await res.text());
+        if (text === null)
+            return fail('bad_reply');
+        return { ok: true, text, ms: Date.now() - t0 };
+    }
+    catch (err) {
+        return fail(err instanceof Error && err.name === 'TimeoutError' ? 'timeout' : 'network');
+    }
+}

package/dist/memory/commit.d.ts

@@ -0,0 +1,67 @@
+import { type MemoryLine } from './vault-notes.ts';
+import type { Bookkeeping, ConversationIndex, MemoryProposal } from '../schema/index.ts';
+import { type MemoryPlan, type Vault } from './vault.ts';
+type Seen = {
+    path: string;
+    hash: string;
+    clip: number;
+};
+/**
+ * 「## 记忆」段 → 建议与要怎么改(不写)。said = 孩子说过的话(proposals.ts 的 kidSaid),证据拿它对;
+ * shared = 这位是有脸的老师,`孩子:` 的那几条进孩子的记忆(不是的照旧进自己的,前缀留着);
+ * seen / childSeen = 这轮上下文包里老师看到的两篇的版本(见 planVaultMemory)。写不进(vault 不在、同名文件没属性)进提醒,不影响这一轮
+ */
+export declare function planMemory(v: Vault, o: {
+    agent: string;
+    display: string;
+    items: readonly string[];
+    max: number | null;
+    date: string;
+    said: readonly string[];
+    shared: boolean;
+    seen?: Seen;
+    childSeen?: Seen;
+}): Promise<{
+    proposals: MemoryProposal[];
+    plan: MemoryPlan | null;
+    child: MemoryPlan | null;
+    warnings: string[];
+}>;
+/** 进孩子的记忆的那几条,在这轮的 remembered 里前面标一下(家长视图分得清) */
+export declare const childChanges: (changes: readonly string[]) => string[];
+/**
+ * 记账那轮的「## 记账」段 → 这个话题在日记里的一段(不写);算成了回那段原文与文件名(notes 是要提醒家长的),没有回为什么。
+ * 孩子问:老师挑的 asked 拿孩子在这个话题里的话核对(同记忆的证据,proposals.ts),对上的最多 3 句;一句都没对上就由 tidyQuestions 筛
+ */
+export declare function planDiary(o: {
+    date: string;
+    index: ConversationIndex;
+    thread: string;
+    bookkeeping: Bookkeeping | null;
+    subject: string;
+    keepScore: number;
+}): {
+    block: string;
+    file: string;
+    notes: string[];
+} | {
+    warning: string;
+};
+/** 把算好的那段追加到当天日记 */
+export declare function writeDiaryBlock(v: Vault, date: string, block: string): Promise<void>;
+/** 记忆那笔写成了没有:文件就是写成之后的版本;是写之前的版本 → 没有;都不是(后来又有人改过)就看每一行:改后的那行在、删掉的那行不在 */
+export declare function memoryLanded(text: string, p: {
+    base: string | null;
+    hash: string;
+    lines: readonly MemoryLine[];
+}): boolean;
+/**
+ * 写到一半断了的那几笔(索引上还带着 pending 的消息,《运行层行为设计》§5):对照文件里的实际结果补记或丢掉,不重写一遍。
+ * 记忆写成了 → 补 remembered / memoryLines(孩子的记忆是 childLines;删话题才撤得回);日记里有那段 → 补 diaryBlock 与 booked(不再记第二遍)。
+ * 没写成的丢掉:记账再点一次会重记。都进那条消息的提醒。没有 pending → 原样(changed: false)
+ */
+export declare function recoverPending(v: Vault, index: ConversationIndex): Promise<{
+    index: ConversationIndex;
+    changed: boolean;
+}>;
+export {};

package/dist/memory/commit.js

@@ -0,0 +1,130 @@
+/**
+ * 老师回的结构化段落进 vault(从 runner 拆出来,2026-10-29):老师(LLM)不直接写 vault,回结构化段由应用落盘,
+ * 写了什么、没写成为什么都回给调用方,进这一轮的提醒。
+ * - 「## 记忆」:每条先成建议、证据对孩子说过的话(proposals.ts),对不上的不记;其余增 / 改 / 删落进这位 agent 的记忆文件,
+ *   `孩子:` 开头的(有脸的老师写的)落进孩子的记忆(agent: all,所有有脸的老师共用);讲课的轮每轮最多 max 条,多的丢(整理轮 max = null 不限)
+ * - 「## 记账」:这个话题在日记里的一段(打分不够只留孩子问与观察),追加到当天日记
+ * 只算不写(planMemory、planDiary):调用方先在这一轮的索引上记 pending,再写(writeVaultMemory、writeDiaryBlock),
+ * 写完把 pending 换成 memoryLines / diaryBlock / booked(《运行层行为设计》§5,2026-10-30)。中间断了由 recoverPending 补。
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { appendDiary, diaryTopic, entryFor, kidQuestions, renderDiaryBlock, tidyQuestions } from "./diary.js";
+import { checkEvidence, childItem, proposalsOf } from "./proposals.js";
+import { CHILD_MEMORY_AGENT, textHash } from "./vault-notes.js";
+import { planVaultMemory, writeDiary } from "./vault.js";
+/**
+ * 「## 记忆」段 → 建议与要怎么改(不写)。said = 孩子说过的话(proposals.ts 的 kidSaid),证据拿它对;
+ * shared = 这位是有脸的老师,`孩子:` 的那几条进孩子的记忆(不是的照旧进自己的,前缀留着);
+ * seen / childSeen = 这轮上下文包里老师看到的两篇的版本(见 planVaultMemory)。写不进(vault 不在、同名文件没属性)进提醒,不影响这一轮
+ */
+export async function planMemory(v, o) {
+    const warnings = [];
+    if (o.max !== null && o.items.length > o.max)
+        warnings.push(`记忆:一轮最多记 ${o.max} 条,丢了 ${o.items.length - o.max} 条:${o.items.slice(o.max).join(';')}`);
+    const proposals = proposalsOf(o.max === null ? o.items : o.items.slice(0, o.max), o.said);
+    const rejected = proposals.filter((p) => p.check === 'rejected');
+    if (rejected.length)
+        warnings.push(`记忆:证据对不上孩子说过的话,没记:${rejected.map((p) => `${p.item}(证据「${p.quote}」)`).join(';')}`);
+    const kept = proposals.filter((p) => p.check !== 'rejected');
+    const toChild = (p) => o.shared && p.target === 'child';
+    const plans = { plan: null, child: null };
+    for (const [key, agent, display, items, seen] of [
+        ['plan', o.agent, o.display, kept.filter((p) => !toChild(p)).map((p) => p.item), o.seen],
+        ['child', CHILD_MEMORY_AGENT, '孩子', kept.filter(toChild).map((p) => childItem(p.item)), o.childSeen],
+    ]) {
+        if (!items.length)
+            continue;
+        try {
+            const r = await planVaultMemory(v, { agent, display, items, date: o.date, seen });
+            plans[key] = r.plan;
+            warnings.push(...r.warnings);
+        }
+        catch (err) {
+            warnings.push(`${key === 'child' ? '孩子的记忆' : '记忆'}没写进去:${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return { proposals, ...plans, warnings };
+}
+/** 进孩子的记忆的那几条,在这轮的 remembered 里前面标一下(家长视图分得清) */
+export const childChanges = (changes) => changes.map((c) => `孩子的记忆:${c}`);
+/**
+ * 记账那轮的「## 记账」段 → 这个话题在日记里的一段(不写);算成了回那段原文与文件名(notes 是要提醒家长的),没有回为什么。
+ * 孩子问:老师挑的 asked 拿孩子在这个话题里的话核对(同记忆的证据,proposals.ts),对上的最多 3 句;一句都没对上就由 tidyQuestions 筛
+ */
+export function planDiary(o) {
+    if (!o.bookkeeping)
+        return { warning: '记账:老师没回「## 记账」段,日记没写;再点一次记账' };
+    const entry = entryFor(o.bookkeeping, o.thread);
+    if (!entry)
+        return { warning: `记账:「## 记账」段里没有话题 ${o.thread} 的那条,日记没写` };
+    const said = kidQuestions(o.index.messages, o.thread);
+    const asked = (entry.asked ?? []).map((q) => ({ q, check: checkEvidence(q, said) }));
+    const picked = asked.filter((a) => a.check === 'verified').map((a) => a.q).slice(0, 3);
+    const wrong = asked.filter((a) => a.check === 'rejected').map((a) => a.q);
+    const block = renderDiaryBlock(diaryTopic(o.index, entry, { subject: o.subject, keepScore: o.keepScore, questions: picked.length ? picked : tidyQuestions(said) }));
+    if (!block)
+        return { warning: '记账:这个话题没有孩子的话、摘要、观察,日记没写' };
+    return { block, file: `${o.date}.md`, notes: wrong.length ? [`记账:老师挑的孩子问有 ${wrong.length} 句孩子没说过,没进日记:${wrong.join(';')}`] : [] };
+}
+/** 把算好的那段追加到当天日记 */
+export async function writeDiaryBlock(v, date, block) {
+    await writeDiary(v, date, (existing) => appendDiary(existing, block));
+}
+/** 记忆那笔写成了没有:文件就是写成之后的版本;是写之前的版本 → 没有;都不是(后来又有人改过)就看每一行:改后的那行在、删掉的那行不在 */
+export function memoryLanded(text, p) {
+    const h = textHash(text);
+    if (h === p.hash)
+        return true;
+    if (h === p.base)
+        return false;
+    const has = new Set(text.split('\n'));
+    return p.lines.every((l) => (l.after !== null ? has.has(l.after) : l.before !== null && !has.has(l.before)));
+}
+/**
+ * 写到一半断了的那几笔(索引上还带着 pending 的消息,《运行层行为设计》§5):对照文件里的实际结果补记或丢掉,不重写一遍。
+ * 记忆写成了 → 补 remembered / memoryLines(孩子的记忆是 childLines;删话题才撤得回);日记里有那段 → 补 diaryBlock 与 booked(不再记第二遍)。
+ * 没写成的丢掉:记账再点一次会重记。都进那条消息的提醒。没有 pending → 原样(changed: false)
+ */
+export async function recoverPending(v, index) {
+    if (!index.messages.some((m) => m.pending))
+        return { index, changed: false };
+    let booked = index.booked;
+    const messages = [];
+    for (const m of index.messages) {
+        if (!m.pending) {
+            messages.push(m);
+            continue;
+        }
+        const { pending: p, ...rest } = m;
+        let next = rest;
+        const notes = [];
+        const remembered = [];
+        for (const [pm, child] of [[p.memory, false], [p.child, true]]) {
+            if (!pm)
+                continue;
+            const text = await readFile(join(v.paths.vault, pm.file), 'utf8').catch(() => null);
+            if (text !== null && memoryLanded(text, pm)) {
+                remembered.push(...(child ? childChanges(pm.changes) : pm.changes));
+                next = child ? { ...next, childLines: pm.lines } : { ...next, memoryLines: pm.lines };
+                notes.push(`${child ? '孩子的记忆' : '记忆'}:上次写完 ${pm.file} 就断了,这轮的改动已补记`);
+            }
+            else
+                notes.push(`${child ? '孩子的记忆' : '记忆'}:上次写 ${pm.file} 之前断了,这轮的记忆没写进去`);
+        }
+        if (remembered.length)
+            next = { ...next, remembered };
+        if (p.diary) {
+            const text = await readFile(join(v.paths.diary, p.diary.file), 'utf8').catch(() => null);
+            if (text?.includes(p.diary.block.trim())) {
+                next = { ...next, diaryBlock: p.diary.block };
+                booked = { ...booked, [p.diary.thread]: m.job };
+                notes.push(`记账:上次写完日记 ${p.diary.file} 就断了,已补记为记过`);
+            }
+            else
+                notes.push(`记账:上次写日记 ${p.diary.file} 之前断了,日记没写;再点一次记账`);
+        }
+        messages.push({ ...next, warnings: [...(next.warnings ?? []), ...notes] });
+    }
+    return { index: { ...index, messages, booked }, changed: true };
+}

package/dist/memory/context.d.ts

@@ -0,0 +1,86 @@
+import { type Retrieved } from './retrieval.ts';
+import type { ContextPack } from '../schema/index.ts';
+import { type Vault } from './vault.ts';
+/**
+ * 上下文包的来源清单(2026-09-15,`cotutor pack` 干跑用):每段来自哪个文件、那里一共有多少、按政策带了几条。
+ * 家长改了档案 / 入口文件 / 日记 / 计划,不起模型就能看到老师下一轮会看见什么、什么被截掉了。
+ */
+export interface PackReport {
+    timetable: {
+        file: string;
+        found: boolean;
+        slot: string | null;
+    };
+    vault: {
+        root: string;
+        semester: string | null;
+        profile: string | null;
+        extraProfiles: string[];
+        entry: string | null;
+        extraEntries: string[];
+        memory: string | null;
+        extraMemories: string[];
+        subject: string | null;
+        refs: string[];
+        limit: number;
+        chars: {
+            profile: number;
+            entry: number;
+            memory: number;
+        };
+    };
+    plan: {
+        file: string;
+        found: boolean;
+        total: number;
+        kept: number;
+        limit: number;
+    };
+    recent: {
+        dir: string;
+        days: number;
+        filesFound: string[];
+        total: number;
+        kept: number;
+        limit: number;
+        subject: string | null;
+    };
+}
+export interface LearningContext {
+    slot?: string;
+    semester?: string;
+    /** 档案、孩子的记忆、入口文件、记忆的原文(截过) */
+    notes: NonNullable<ContextPack['notes']>;
+    /** 上下文包里那几行:路径(截了注明)或「缺:…」「还没有」 */
+    profile: string;
+    /** 孩子的记忆:有脸的老师才带 */
+    child?: string;
+    entry?: string;
+    memory: string;
+    refs?: string[];
+    plan: string[];
+    recent: ContextPack['recent'];
+    /** 替老师查好的(retrieval.ts);口径原文在 notes(role: lesson),lesson 是它在哪 */
+    lookup: string[];
+    lesson?: string;
+    /** 取材用到的文件与为什么查(进这一轮的运行记录) */
+    retrieved: Retrieved[];
+}
+/**
+ * 这一轮从 vault 取的材。agent = 记忆认谁的(activity 话题是 <老师>/<activity>,档案、入口文件、日记观察照旧共用);
+ * teacher = 这位是有脸的老师(没有入口文件时写「缺」;带孩子的记忆——它是有意的例外,activity 话题也带同一篇);display = 计划里认他的名字(不在 tutors 里就不带计划)
+ * query = 孩子这一轮说的话(加首页按钮的讲法):有脸的老师才拿它替老师查生字表、口径、以前讲过的骨架(retrieval.ts)
+ */
+export declare function learningContext(v: Vault, o: {
+    at: Date;
+    agent: string;
+    subject?: string;
+    display?: string;
+    teacher: boolean;
+    query?: string;
+    limits: {
+        entryChars: number;
+        planLines: number;
+        recent: number;
+    };
+}, report?: PackReport): Promise<LearningContext>;