cotutor 0.1.0 → 0.3.0

package/dist/memory/vault-notes.js

@@ -0,0 +1,359 @@
+/**
+ * vault 里家长写的笔记按 frontmatter 定位(《obsidian仓库设计.md》):
+ * `cotutor: profile | subject | textbook`,不认文件名与目录——家长会改名、挪位置。
+ *  - profile:孩子档案,一个 vault 一个;`school_start: YYYY-MM` 算当前学期,`semester` 可覆盖
+ *  - subject:一科一学期一个,就是这位老师的**入口文件**,原文整篇进上下文包
+ *  - textbook:可以没有、可以多本;只给路径,老师要用自己 Read
+ *  - memory:一个 agent 一篇(`agent: <name>`),老师在回复里写「## 记忆」、应用追加;家长可读可改,原文整篇进上下文包。
+ *    `agent: all` 那篇是孩子的记忆(2026-10-30):关于孩子本人、换一科也成立的,所有有脸的老师共用,老师写 `孩子:` 开头的行进这里
+ * 程序读的键用英文(cotutor / subject / semester / school_start / agent),中文键是给人看的描述,这里不读。
+ */
+export const NOTE_KINDS = ['profile', 'subject', 'textbook', 'memory'];
+/** 只认平铺的 `key: value`;值去掉成对引号。没有 frontmatter → {} */
+export function frontmatter(md) {
+    const lines = md.replace(/^\uFEFF/, '').split(/\r?\n/);
+    if (lines[0]?.trim() !== '---')
+        return {};
+    const out = {};
+    for (let i = 1; i < lines.length; i++) {
+        const l = lines[i];
+        if (l.trim() === '---')
+            return out;
+        const m = /^([^\s:#][^:]*?)\s*:\s*(.*)$/.exec(l);
+        if (!m)
+            continue;
+        let v = m[2].trim();
+        if (v.length >= 2 && ((v[0] === '"' && v.at(-1) === '"') || (v[0] === "'" && v.at(-1) === "'")))
+            v = v.slice(1, -1);
+        out[m[1]] = v;
+    }
+    return {};
+}
+const CN_DIGITS = ['', '一', '二', '三', '四', '五', '六', '七', '八', '九', '十', '十一', '十二'];
+/**
+ * 某天是几年级的哪个学期 / 假期:9–1 月上学期、2 月寒假、3–6 月下学期、7–8 月暑假(刚读完的那个年级的暑假)。
+ * 学年从 9 月算;`school_start` 是读一年级那年的 9 月(写别的月份也按它所在学年算)。年级不在 1–12 → null。
+ */
+export function semesterAt(schoolStart, date) {
+    const s = /^(\d{4})-(\d{1,2})$/.exec(schoolStart.trim());
+    const d = /^(\d{4})-(\d{2})-\d{2}/.exec(date);
+    if (!s || !d)
+        return null;
+    const sm = Number(s[2]);
+    if (sm < 1 || sm > 12)
+        return null;
+    const startYear = sm >= 9 ? Number(s[1]) : Number(s[1]) - 1;
+    const y = Number(d[1]);
+    const m = Number(d[2]);
+    const schoolYear = m >= 9 ? y : y - 1;
+    const grade = schoolYear - startYear + 1;
+    if (grade < 1 || grade >= CN_DIGITS.length)
+        return null;
+    const term = m >= 9 || m === 1 ? '上' : m === 2 ? '寒假' : m <= 6 ? '下' : '暑假';
+    return `${CN_DIGITS[grade]}年级${term}`;
+}
+/** 正文里的 `[[目标]]` / `![[目标|别名]]`:去掉 #节 与 |别名,去重,按出现顺序 */
+export function wikilinks(md) {
+    const out = [];
+    for (const m of md.matchAll(/!?\[\[([^\]|#]*)(?:#[^\]|]*)?(?:\|[^\]]*)?\]\]/g)) {
+        const t = m[1].trim();
+        if (t && !out.includes(t))
+            out.push(t);
+    }
+    return out;
+}
+/** 像 Obsidian 那样解析链接:先按相对根的完整路径(可省 .md),再按文件名(同名取路径最短的);找不到 → null */
+export function resolveLink(target, files) {
+    const t = target.replace(/^\/+/, '');
+    const exact = files.find((f) => f === t || f === `${t}.md`);
+    if (exact)
+        return exact;
+    const base = t.includes('/') ? null : t;
+    if (!base)
+        return null;
+    const hits = files.filter((f) => {
+        const name = f.slice(f.lastIndexOf('/') + 1);
+        return name === base || name === `${base}.md`;
+    });
+    return hits.sort((a, b) => a.length - b.length || a.localeCompare(b))[0] ?? null;
+}
+const byPath = (a, b) => a.path.localeCompare(b.path);
+/**
+ * 从扫出来的笔记里挑一位老师要的:档案、当前学期、入口文件、参考路径。
+ * `files` 是 vault 里所有文件的相对路径(解析 [[链接]] 用,不限 .md)。subject 没配 → 没有入口文件。
+ */
+export function pickNotes(notes, files, opts) {
+    const of = (k) => notes.filter((n) => n.props.cotutor === k).sort(byPath);
+    // 不止一篇时先要写了学期信息的那篇
+    const dated = (n) => (n.props.semester?.trim() || n.props.school_start?.trim() ? 0 : 1);
+    const profiles = of('profile').sort((a, b) => dated(a) - dated(b));
+    const profile = profiles[0] ?? null;
+    const semester = profile ? (profile.props.semester?.trim() || (profile.props.school_start ? semesterAt(profile.props.school_start, opts.date) : null)) : null;
+    const same = (n) => !!opts.subject && !!semester && n.props.subject?.trim() === opts.subject && n.props.semester?.trim() === semester;
+    const entries = of('subject').filter(same);
+    const entry = entries[0] ?? null;
+    const memories = of('memory').filter((n) => !!opts.agent && n.props.agent?.trim() === opts.agent);
+    const child = of('memory').find((n) => n.props.agent?.trim() === CHILD_MEMORY_AGENT) ?? null;
+    const textbooks = of('textbook').filter(same);
+    const refs = textbooks.map((n) => n.path);
+    for (const n of [profile, entry]) {
+        if (!n)
+            continue;
+        for (const l of wikilinks(n.text)) {
+            const p = resolveLink(l, files);
+            if (p)
+                refs.push(p);
+        }
+    }
+    const self = new Set([profile?.path, entry?.path]);
+    return {
+        profile,
+        extraProfiles: profiles.slice(1).map((n) => n.path),
+        semester,
+        entry,
+        extraEntries: entries.slice(1).map((n) => n.path),
+        memory: memories[0] ?? null,
+        extraMemories: memories.slice(1).map((n) => n.path),
+        child,
+        refs: [...new Set(refs)].filter((p) => !self.has(p)),
+        textbooks,
+    };
+}
+/** 入口文件缺了为什么(进上下文包 entry: 与这条消息的 warnings;家长端就看得到) */
+export function missingEntry(subject, pick) {
+    if (!subject)
+        return '缺:cotutor.json 里这位老师没配 subject';
+    if (!pick.profile)
+        return '缺:vault 里没有 cotutor: profile 的档案,算不出学期';
+    if (!pick.semester)
+        return '缺:档案没写 school_start(或 semester),算不出学期';
+    return `缺:vault 里没有 cotutor: subject、subject: ${subject}、semester: ${pick.semester} 的文件`;
+}
+/** 记忆文件缺省位置:记忆/<显示名>.md(显示名里的 / 换掉) */
+export function memoryPath(display) {
+    return `记忆/${display.replace(/[\\/:]/g, '-')}.md`;
+}
+/** 新建的记忆文件 */
+export function memoryTemplate(agent, display) {
+    return `---
+cotutor: memory
+agent: ${agent}
+---
+
+${display}自己记下的,每个话题开头会整篇读到。你可以随便改、删、分小节;新的加在末尾,老师也会改、删这里的任何一行(记账后整理一次)。
+
+`;
+}
+/** 孩子的记忆(2026-10-30):`agent: all` 的那篇,缺省在 记忆/孩子.md;满了(列表行到 CHILD_MEMORY_CAP 条)新的不再进,提醒家长删 */
+export const CHILD_MEMORY_AGENT = 'all';
+export const CHILD_MEMORY_PATH = '记忆/孩子.md';
+export const CHILD_MEMORY_CAP = 20;
+/** 新建的孩子的记忆 */
+export function childMemoryTemplate() {
+    return `---
+cotutor: memory
+agent: ${CHILD_MEMORY_AGENT}
+---
+
+关于孩子本人、换一科也成立的事(情绪、读写、注意力、家里谁在旁边),每位老师每个话题开头都会读到。老师在「## 记忆」里写「孩子:」开头的行,应用记在这里;你可以随便改、删。和档案说的不一样时,以档案为准。最多 ${CHILD_MEMORY_CAP} 条,满了就不再记,删几条才有地方。
+
+`;
+}
+/**
+ * 往记忆文件末尾追加:每条一行 `- <日期> <原话>`(老师自己写了日期开头就不再加);文里已有同样的话就跳过。
+ * cap:列表行最多这么多条,满了的不加,进 full。返回新全文与真加上的行;一条都没加 → text 原样。
+ */
+export function appendMemory(existing, items, date, cap) {
+    const has = (s) => existing.split('\n').some((l) => l.replace(/^\s*[-*]\s+(\d{4}-\d{2}-\d{2}\s+)?/, '').trim() === s);
+    const added = [];
+    const full = [];
+    const room = cap === undefined ? Infinity : cap - memoryCount(existing);
+    for (const raw of items) {
+        const s = raw.replace(/\s+/g, ' ').trim();
+        const bare = s.replace(/^\d{4}-\d{2}-\d{2}\s+/, '');
+        if (!bare || has(bare) || added.some((a) => a.endsWith(` ${bare}`)))
+            continue;
+        if (added.length >= room) {
+            full.push(bare);
+            continue;
+        }
+        added.push(`- ${/^\d{4}-\d{2}-\d{2}\s/.test(s) ? s : `${date} ${s}`}`);
+    }
+    if (!added.length)
+        return { text: existing, added, full };
+    const base = existing.replace(/\s*$/, '');
+    return { text: `${base}\n${/^\s*[-*]\s/.test(base.split('\n').at(-1) ?? '') ? '' : '\n'}${added.join('\n')}\n`, added, full };
+}
+export function parseMemoryOp(item) {
+    const s = item.replace(/\s+/g, ' ').trim();
+    const del = /^删[:：]\s*(.+)$/.exec(s);
+    if (del)
+        return { op: 'delete', from: del[1].trim() };
+    const body = /^改[:：]\s*(.+)$/.exec(s)?.[1] ?? '';
+    const cuts = [...body.matchAll(/\s*(?:→|->)\s*/g)].map((m) => ({ from: body.slice(0, m.index).trim(), to: body.slice(m.index + m[0].length).trim() })).filter((c) => c.from && c.to);
+    if (cuts.length)
+        return { op: 'change', ...cuts[0], ...(cuts.length > 1 ? { alt: cuts.slice(1) } : {}) };
+    return { op: 'add', text: s };
+}
+/** 一行记忆去掉列表点与日期前缀后的原话(比对用) */
+const bareLine = (l) => l.replace(/^\s*[-*]\s+/, '').replace(/^\d{4}-\d{2}-\d{2}\s+/, '').replace(/\s+/g, ' ').trim();
+/** 一行改动给家长看的样子:新增的原话、「改:旧 → 新」、「删:旧」(家长端「记录」的「记住了」) */
+export function memoryLineText(l) {
+    if (l.before === null)
+        return bareLine(l.after ?? '');
+    if (l.after === null)
+        return `删:${bareLine(l.before)}`;
+    return `改:${bareLine(l.before)} → ${bareLine(l.after)}`;
+}
+/**
+ * 按原话找一行:正文(frontmatter 之后)里原话一字不差的那行;没有就找唯一一行包含它的(原话至少 4 个字);都不是 → -1。
+ * 不分老师写的、家长写的(2026-09-18 定:机器一律可以改)。fuzzy = false 只认一字不差的(这轮里家长改过文件,2026-10-30)。
+ */
+export function findMemoryLine(lines, from, bodyStart, fuzzy = true) {
+    const want = bareLine(from);
+    if (!want)
+        return -1;
+    const exact = lines.findIndex((l, i) => i >= bodyStart && bareLine(l) === want);
+    if (exact >= 0)
+        return exact;
+    if (!fuzzy || Array.from(want).length < 4)
+        return -1;
+    const hits = lines.map((l, i) => (i >= bodyStart && l.trim() && bareLine(l).includes(want) ? i : -1)).filter((i) => i >= 0);
+    return hits.length === 1 ? hits[0] : -1;
+}
+/**
+ * 把一串操作落到记忆全文上:先改、删(按原话找行,见 findMemoryLine),再把新增的追加到末尾(appendMemory,去重)。
+ * 改过的列表行换成 `- <今天> 新的`(新的自己带着日期就去掉,不写两个日期);不是列表的行整行换成新的。strict:改、删只认一字不差的原话;cap:新增后最多几条(先删后加,删掉的腾出地方)。
+ * 改有几种切法(parseMemoryOp 的 alt)时:先挑原话一字不差的那种;都不是再模糊找,原话长的先(短的是长的前缀,会把原话后半截切进新的里)。
+ */
+export function applyMemoryOps(existing, ops, date, opts = {}) {
+    const lines = existing.split('\n');
+    const fm = /^\uFEFF?---\s*$/.test(lines[0] ?? '') ? lines.findIndex((l, i) => i > 0 && /^---\s*$/.test(l)) : -1;
+    const bodyStart = fm > 0 ? fm + 1 : 0;
+    const changes = [];
+    const misses = [];
+    const edits = [];
+    const gone = new Set();
+    const locate = (o) => {
+        const cuts = o.op === 'change' ? [{ from: o.from, to: o.to }, ...(o.alt ?? [])] : [{ from: o.from, to: '' }];
+        const free = (i) => i >= 0 && !gone.has(i);
+        for (const c of cuts) {
+            const i = findMemoryLine(lines, c.from, bodyStart, false);
+            if (free(i))
+                return { i, to: c.to };
+        }
+        if (!opts.strict)
+            for (const c of [...cuts].reverse()) {
+                const i = findMemoryLine(lines, c.from, bodyStart, true);
+                if (free(i))
+                    return { i, to: c.to };
+            }
+        return { i: -1, to: '' };
+    };
+    for (const o of ops) {
+        if (o.op === 'add')
+            continue;
+        const { i, to } = locate(o);
+        if (i < 0) {
+            misses.push(o.op === 'change' ? `改:${o.from}` : `删:${o.from}`);
+            continue;
+        }
+        const old = bareLine(lines[i]);
+        if (o.op === 'delete') {
+            gone.add(i);
+            changes.push(`删:${old}`);
+            edits.push({ before: lines[i], after: null });
+        }
+        else {
+            const bullet = /^(\s*[-*]\s+)/.exec(lines[i]);
+            const before = lines[i];
+            const fresh = to.replace(/^\d{4}-\d{2}-\d{2}\s+/, '');
+            lines[i] = bullet ? `${bullet[1]}${date} ${fresh}` : fresh;
+            changes.push(`改:${old} → ${fresh}`);
+            edits.push({ before, after: lines[i] });
+        }
+    }
+    const kept = lines.filter((_, i) => !gone.has(i)).join('\n');
+    const adds = ops.flatMap((o) => (o.op === 'add' ? [o.text] : []));
+    const r = appendMemory(kept, adds, date, opts.cap);
+    return { text: r.text, changes: [...changes, ...r.added], misses, full: r.full, lines: [...edits, ...r.added.map((after) => ({ before: null, after }))] };
+}
+/**
+ * 撤销一串改动(删话题时,2026-10-05):倒着来——改了的换回原来那行,新增的删掉,删了的接回末尾(原来的位置不记)。
+ * 按整行原文找;家长或整理那轮后来又改过那行就找不到,进 misses,不动。
+ */
+export function undoMemoryLines(existing, edits) {
+    let lines = existing.split('\n');
+    let undone = 0;
+    const misses = [];
+    const back = [];
+    for (const e of [...edits].reverse()) {
+        if (e.after === null) {
+            if (e.before !== null) {
+                back.unshift(e.before);
+                undone++;
+            }
+            continue;
+        }
+        const i = lines.findIndex((l) => l === e.after);
+        if (i < 0) {
+            misses.push(bareLine(e.after));
+            continue;
+        }
+        lines = e.before === null ? lines.filter((_, k) => k !== i) : lines.map((l, k) => (k === i ? e.before : l));
+        undone++;
+    }
+    let text = lines.join('\n');
+    if (back.length) {
+        const base = text.replace(/\s*$/, '');
+        text = `${base}\n${/^\s*[-*]\s/.test(base.split('\n').at(-1) ?? '') ? '' : '\n'}${back.join('\n')}\n`;
+    }
+    return { text, undone, misses };
+}
+/** 记忆文件里有几条(frontmatter 之后的列表行) */
+export function memoryCount(text) {
+    const body = text.replace(/^\uFEFF?---\s*\n[\s\S]*?\n---\s*(\n|$)/, '');
+    return body.split('\n').filter((l) => /^\s*[-*]\s+\S/.test(l)).length;
+}
+/**
+ * 记账后整理记忆那轮的消息正文(2026-09-18):新会话、from: system;记忆原文在上下文包的 <vault-note role="memory">。
+ * 回的「## 记忆」段不受每轮条数上限,应用照单落盘、不问家长(家长在 Obsidian 里兜底)。
+ */
+export function tidyMemoryPrompt(opts) {
+    return [
+        `学习结束、账记完了,把你的记忆整理一遍。记忆文件的原文在上下文包的 <vault-note role="memory">(现在 ${opts.count} 条;截了就自己 Read 全文),今天(${opts.date})的日记在 ${opts.diaryFile},读你这一科的几段对照一下。`,
+        '',
+        '只回一段「## 记忆」,一行一条,别的一个字都不用写:',
+        '',
+        '## 记忆',
+        '- 删:原话(过时的、今天看出来不对的、和别的重复的)',
+        '- 改:原话 → 新的(要更新的,比如「还没学竖式 → 9 月中学会了两位数竖式」;几条说一件事就改成一条、删掉其余)',
+        '- 新的一条(今天日记里看出来、以后还用得上、记忆里还没有的)',
+        '',
+        `原话照记忆文件里那一行抄,日期可以不抄;谁写的行都可以改、删。整理完不超过 ${opts.cap} 条。都不用动就只回一句「记忆不用整理」,不写「## 记忆」段。`,
+    ].join('\n');
+}
+/**
+ * 按 entryChars 截一篇笔记带进上下文包。档案、入口文件留开头(家长写在前面的最要紧);
+ * 记忆留末尾——应用往末尾追加,最新的在后面,截开头丢的是旧的(2026-09-18 之前留的是开头,越记越看不到新的)。
+ * 末尾那头从一行的开头起,不截半行。
+ */
+export function clipNote(text, limit, keep) {
+    if (text.length <= limit)
+        return { text, cut: false };
+    if (keep === 'head')
+        return { text: `${text.slice(0, limit)}\n……(后面截掉了,要看全文自己 Read)`, cut: true };
+    const tail = text.slice(-limit);
+    const nl = tail.indexOf('\n');
+    const aligned = text.at(-limit - 1) === '\n' || nl < 0 ? tail : tail.slice(nl + 1);
+    return { text: `……(前面旧的截掉了,下面是最近的;要看全文自己 Read)\n${aligned}`, cut: true };
+}
+/** 短 hash(FNV-1a 32 位):同一话题里判断「这篇上次带过、没改」 */
+export function textHash(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(16).padStart(8, '0');
+}

package/dist/memory/vault.d.ts

@@ -0,0 +1,70 @@
+import { type MemoryLine, type VaultNote } from './vault-notes.ts';
+import type { ConversationMessage, PathRole } from '../schema/index.ts';
+/** vault 在哪:workspace 的 paths(vault、diary、plans、textbooks…);传整个 workspace 也行 */
+export interface Vault {
+    paths: Readonly<Record<PathRole, string>>;
+}
+/** 删话题撤销了多少:记忆几行、日记几段;找不到原文没撤的(家长或整理那轮后来改过)一条一句 */
+export interface ThreadUndo {
+    memory: number;
+    diary: number;
+    misses: string[];
+}
+/**
+ * 删话题时撤回它留在 vault 里的:各轮写进记忆的行(memoryLines;孩子的记忆是 childLines)倒着撤、记账写进日记的那段(diaryBlock)摘掉;
+ * 找不到原文的(家长或整理那轮后来改过)不撤,一条一句列进 misses
+ */
+export declare function undoThreadVault(v: Vault, tutor: string, date: string, gone: readonly ConversationMessage[]): Promise<ThreadUndo>;
+/** 这几天的日记(<日记目录>/<日期>.md);没有的跳过 */
+export declare function readDiaries(v: Vault, dates: readonly string[]): Promise<{
+    date: string;
+    text: string;
+}[]>;
+/** 当天的日记:update 拿现有内容(没有 → null)回新内容;先 .tmp 再 rename。返回文件名(<日期>.md) */
+export declare function writeDiary(v: Vault, date: string, update: (existing: string | null) => string): Promise<string>;
+/** 教材目录下的每册文件(<教材目录>/<册>.md),给 textbookHeadings;没有目录 → [] */
+export declare function readTextbooks(v: Vault): Promise<{
+    name: string;
+    text: string;
+}[]>;
+/**
+ * 扫 vault:所有文件的相对路径(解析 [[链接]] 用)+ 带 `cotutor:` 属性的 md(按属性定位,《obsidian仓库设计.md》2026-09-17)。
+ * 跳过点开头的目录(.obsidian / .git)与日记、计划目录(机器写的,不带属性,越积越多)。读不到的文件跳过;vault 不在 → 全空。
+ */
+export declare function scanVault(v: Vault): Promise<{
+    notes: VaultNote[];
+    files: string[];
+}>;
+/** 要写进记忆文件的一次改动(还没写):planVaultMemory 算,writeVaultMemory 写 */
+export interface MemoryPlan {
+    /** 相对 vault 根 */
+    file: string;
+    /** 算的时候文件的原文;新建 = null */
+    base: string | null;
+    text: string;
+    changes: string[];
+    lines: MemoryLine[];
+}
+/**
+ * 「## 记忆」段 → 这位 agent 的记忆文件要怎么改(按 `cotutor: memory` + `agent:` 找;没有就建 记忆/<显示名>.md,孩子的记忆建 记忆/孩子.md),只算不写:
+ * 新增追加到末尾,「改:」「删:」按原话找行改、删(任何一行都能动,2026-09-18);缺省位置已有一篇没属性的同名文件就不碰,进提醒。
+ * seen = 这一轮上下文包里老师看到的那版(截过的那段的 textHash 与截的字数):文件和它对不上 = 这轮里家长改过,
+ * 改、删只认一字不差的原话,找不到的不改——按「包含」找会把家长刚补上的半句一起盖掉(2026-10-30)。
+ * 孩子的记忆(agent: all)最多 CHILD_MEMORY_CAP 条,满了新增的不进,提醒家长删几条。
+ */
+export declare function planVaultMemory(v: Vault, o: {
+    agent: string;
+    display: string;
+    items: readonly string[];
+    date: string;
+    seen?: {
+        path: string;
+        hash: string;
+        clip: number;
+    };
+}): Promise<{
+    plan: MemoryPlan | null;
+    warnings: string[];
+}>;
+/** 写下 planVaultMemory 算好的:先重读,和算的时候不一样(家长刚存了一版)就不写,回为什么;写成回 null。先 .tmp 再 rename */
+export declare function writeVaultMemory(v: Vault, plan: MemoryPlan): Promise<string | null>;

package/dist/memory/vault.js

@@ -0,0 +1,169 @@
+import { mkdir, readFile, readdir, rename, stat, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, relative, sep } from 'node:path';
+import { removeDiaryBlock } from "./diary.js";
+import { CHILD_MEMORY_AGENT, CHILD_MEMORY_CAP, CHILD_MEMORY_PATH, applyMemoryOps, childMemoryTemplate, clipNote, frontmatter, memoryPath, memoryTemplate, parseMemoryOp, textHash, undoMemoryLines } from "./vault-notes.js";
+/**
+ * 删话题时撤回它留在 vault 里的:各轮写进记忆的行(memoryLines;孩子的记忆是 childLines)倒着撤、记账写进日记的那段(diaryBlock)摘掉;
+ * 找不到原文的(家长或整理那轮后来改过)不撤,一条一句列进 misses
+ */
+export async function undoThreadVault(v, tutor, date, gone) {
+    const undo = { memory: 0, diary: 0, misses: [] };
+    // activity 话题写的是 activity 自己的记忆(agent: <老师>/<activity>);孩子的记忆大家共用一篇
+    const run = gone.find((m) => m.activity)?.activity;
+    const files = [
+        { agent: run ? `${tutor}/${run.name}` : tutor, edits: gone.flatMap((m) => m.memoryLines ?? []), name: '记忆' },
+        { agent: CHILD_MEMORY_AGENT, edits: gone.flatMap((m) => m.childLines ?? []), name: '孩子的记忆' },
+    ].filter((f) => f.edits.length);
+    const notes = files.length ? (await scanVault(v)).notes : [];
+    for (const f of files) {
+        const found = notes.find((n) => n.props.cotutor === 'memory' && n.props.agent?.trim() === f.agent);
+        if (!found) {
+            undo.misses.push(`${f.name}文件不在了,${f.name}没撤`);
+            continue;
+        }
+        const r = undoMemoryLines(found.text, f.edits);
+        undo.memory += r.undone;
+        undo.misses.push(...r.misses.map((l) => `${f.name}:找不到这行,没撤:${l}`));
+        if (r.undone) {
+            const file = join(v.paths.vault, found.path);
+            await writeFile(`${file}.tmp`, r.text);
+            await rename(`${file}.tmp`, file);
+        }
+    }
+    for (const m of gone) {
+        if (!m.diaryBlock)
+            continue;
+        const existing = await readFile(join(v.paths.diary, `${date}.md`), 'utf8').catch(() => null);
+        const out = existing === null ? null : removeDiaryBlock(existing, m.diaryBlock);
+        if (out === null) {
+            undo.misses.push(`日记:${date} 里找不到这个话题记的那段,没摘`);
+            continue;
+        }
+        await writeDiary(v, date, () => out);
+        undo.diary++;
+    }
+    return undo;
+}
+/** 这几天的日记(<日记目录>/<日期>.md);没有的跳过 */
+export async function readDiaries(v, dates) {
+    const out = [];
+    for (const date of dates) {
+        try {
+            out.push({ date, text: await readFile(join(v.paths.diary, `${date}.md`), 'utf8') });
+        }
+        catch {
+            /* 那天没写 */
+        }
+    }
+    return out;
+}
+/** 当天的日记:update 拿现有内容(没有 → null)回新内容;先 .tmp 再 rename。返回文件名(<日期>.md) */
+export async function writeDiary(v, date, update) {
+    await mkdir(v.paths.diary, { recursive: true });
+    const file = join(v.paths.diary, `${date}.md`);
+    const existing = await readFile(file, 'utf8').catch(() => null);
+    const tmp = `${file}.tmp`;
+    await writeFile(tmp, update(existing));
+    await rename(tmp, file);
+    return basename(file);
+}
+/** 教材目录下的每册文件(<教材目录>/<册>.md),给 textbookHeadings;没有目录 → [] */
+export async function readTextbooks(v) {
+    let names;
+    try {
+        names = (await readdir(v.paths.textbooks)).filter((f) => f.endsWith('.md') && !f.startsWith('.')).sort();
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        try {
+            out.push({ name, text: await readFile(join(v.paths.textbooks, name), 'utf8') });
+        }
+        catch {
+            /* 读不到就跳过 */
+        }
+    }
+    return out;
+}
+/**
+ * 扫 vault:所有文件的相对路径(解析 [[链接]] 用)+ 带 `cotutor:` 属性的 md(按属性定位,《obsidian仓库设计.md》2026-09-17)。
+ * 跳过点开头的目录(.obsidian / .git)与日记、计划目录(机器写的,不带属性,越积越多)。读不到的文件跳过;vault 不在 → 全空。
+ */
+export async function scanVault(v) {
+    const root = v.paths.vault;
+    const skip = new Set([v.paths.diary, v.paths.plans]);
+    const notes = [];
+    const files = [];
+    const walk = async (dir) => {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.name.startsWith('.'))
+                continue;
+            const abs = join(dir, e.name);
+            if (e.isDirectory()) {
+                if (!skip.has(abs))
+                    await walk(abs);
+                continue;
+            }
+            if (!e.isFile())
+                continue;
+            const rel = relative(root, abs).split(sep).join('/');
+            files.push(rel);
+            if (!e.name.endsWith('.md'))
+                continue;
+            try {
+                const text = await readFile(abs, 'utf8');
+                const props = frontmatter(text);
+                if (props.cotutor)
+                    notes.push({ path: rel, props, text });
+            }
+            catch {
+                /* 读不到(iCloud 占位)就跳过 */
+            }
+        }
+    };
+    await walk(root);
+    return { notes, files: files.sort() };
+}
+/**
+ * 「## 记忆」段 → 这位 agent 的记忆文件要怎么改(按 `cotutor: memory` + `agent:` 找;没有就建 记忆/<显示名>.md,孩子的记忆建 记忆/孩子.md),只算不写:
+ * 新增追加到末尾,「改:」「删:」按原话找行改、删(任何一行都能动,2026-09-18);缺省位置已有一篇没属性的同名文件就不碰,进提醒。
+ * seen = 这一轮上下文包里老师看到的那版(截过的那段的 textHash 与截的字数):文件和它对不上 = 这轮里家长改过,
+ * 改、删只认一字不差的原话,找不到的不改——按「包含」找会把家长刚补上的半句一起盖掉(2026-10-30)。
+ * 孩子的记忆(agent: all)最多 CHILD_MEMORY_CAP 条,满了新增的不进,提醒家长删几条。
+ */
+export async function planVaultMemory(v, o) {
+    const found = (await scanVault(v)).notes.find((n) => n.props.cotutor === 'memory' && n.props.agent?.trim() === o.agent);
+    const child = o.agent === CHILD_MEMORY_AGENT;
+    const file = found?.path ?? (child ? CHILD_MEMORY_PATH : memoryPath(o.display));
+    if (!found && (await stat(join(v.paths.vault, file)).catch(() => null)) !== null)
+        return { plan: null, warnings: [`记忆没写:${file} 已经有了但没有 cotutor: memory / agent: ${o.agent} 属性;加上属性,或挪开它`] };
+    const base = found?.text ?? null;
+    const strict = base !== null && o.seen?.path === file && textHash(clipNote(base, o.seen.clip, 'tail').text) !== o.seen.hash;
+    const r = applyMemoryOps(base ?? (child ? childMemoryTemplate() : memoryTemplate(o.agent, o.display)), o.items.map(parseMemoryOp), o.date, { strict, ...(child ? { cap: CHILD_MEMORY_CAP } : {}) });
+    const name = child ? '孩子的记忆' : '记忆';
+    const warnings = !r.misses.length ? [] : strict ? [`${name}:这轮里家长改过记忆文件,找不到原话的没改(不盖掉家长改的):${r.misses.join(';')}`] : [`${name}:找不到原话,没改:${r.misses.join(';')}`];
+    if (r.full.length)
+        warnings.push(`孩子的记忆满了(${CHILD_MEMORY_CAP} 条),这几条没记:${r.full.join(';')};在 Obsidian 里删几条才有地方`);
+    if (!r.changes.length)
+        return { plan: null, warnings };
+    return { plan: { file, base, text: r.text, changes: r.changes, lines: r.lines }, warnings };
+}
+/** 写下 planVaultMemory 算好的:先重读,和算的时候不一样(家长刚存了一版)就不写,回为什么;写成回 null。先 .tmp 再 rename */
+export async function writeVaultMemory(v, plan) {
+    const file = join(v.paths.vault, plan.file);
+    if ((await readFile(file, 'utf8').catch(() => null)) !== plan.base)
+        return `记忆没写:${plan.file} 刚被改过,这轮的记忆没写:${plan.changes.join(';')}`;
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(`${file}.tmp`, plan.text);
+    await rename(`${file}.tmp`, file);
+    return null;
+}