cotutor 0.1.0 → 0.3.0

package/dist/memory/retrieval.js

@@ -0,0 +1,157 @@
+/**
+ * 取材(《vault重构方案》§6,2026-10-30):孩子的话缺省不带工具,讲之前该查的由应用替老师查好,放进上下文包的 lookup 与 <vault-note role="lesson">。
+ * 只读、确定性,只做关键词与标题匹配(不做向量检索,vault 是唯一的真相):
+ *  - 生字表:孩子问到的字(「X字怎么写」「X怎么读」「“X”」这几种说法)落在这科这学期教材哪一课的 识字: / 写字: 行,或都没有
+ *  - 那一课的口径:孩子提到的课(课题、第 N 课),或问到的字要会写的那一课;家长在那一节下写了 `### 口径` 就带原文
+ *  - 以前讲过:最近日记里链到那一课(`[[册#节]]`)的段,最新一条的 `骨架:` 行
+ * 每一样都记来源路径、hash 与为什么查它(retrieved),进这一轮的运行记录(《vault重构方案》§7)。
+ * 教材的形状见《obsidian仓库设计.md》§3.3:一课一个 H2,节下 `识字:` `写字:` 行(字用空格隔开),`### 口径` 是家长写的讲法。
+ */
+import { textHash } from "./vault-notes.js";
+const HAN = '\\p{Script=Han}';
+/** 孩子问字的几种说法;抓到的是要查的字词 */
+const ASKS = [
+    new RegExp(`(${HAN}{1,2}?)(?:这个字|字)?怎么(?:写|读|念|拼|组词)`, 'gu'),
+    new RegExp(`(${HAN})字(?=的|是|不|能|要|有|怎|呢)`, 'gu'),
+    new RegExp(`[「“"](${HAN}{1,4})[」”"]`, 'gu'),
+];
+/** 抓到了也不是在问字的 */
+const NOT_WORDS = new Set(['拼音', '作文', '句子', '题目', '这题', '这道', '这个', '那个', '怎么', '这样', '那样']);
+/** 孩子这句话里问到的字(去重,按出现先后,最多 6 个);没在问字 → [] */
+export function askedChars(text) {
+    const out = [];
+    for (const re of ASKS) {
+        for (const m of text.matchAll(re)) {
+            if (NOT_WORDS.has(m[1]))
+                continue;
+            for (const c of Array.from(m[1]))
+                if (c !== '字' && !out.includes(c))
+                    out.push(c);
+        }
+    }
+    return out.slice(0, 6);
+}
+/** 读一册教材:每个 H2 一课;围栏里的不算 */
+export function parseTextbook(book, text) {
+    const out = [];
+    let cur = null;
+    let inCaliber = false;
+    let fence = false;
+    const caliber = [];
+    const close = () => {
+        if (cur)
+            cur.caliber = caliber.join('\n').trim() || null;
+        caliber.length = 0;
+        inCaliber = false;
+    };
+    for (const line of text.split('\n')) {
+        if (/^\s*```/.test(line))
+            fence = !fence;
+        if (fence) {
+            if (inCaliber)
+                caliber.push(line);
+            continue;
+        }
+        const h2 = /^##\s+(.+?)\s*$/.exec(line);
+        if (h2) {
+            close();
+            cur = { book, title: h2[1], recognize: [], write: [], caliber: null };
+            out.push(cur);
+            continue;
+        }
+        if (!cur)
+            continue;
+        if (/^#{1,3}\s/.test(line)) {
+            inCaliber = /^###\s+口径\s*$/.test(line);
+            continue;
+        }
+        if (inCaliber) {
+            caliber.push(line);
+            continue;
+        }
+        const row = /^(识字|写字)[:：]\s*(.*)$/.exec(line);
+        if (row)
+            (row[1] === '识字' ? cur.recognize : cur.write).push(...row[2].split(/\s+/).filter(Boolean));
+    }
+    close();
+    return out;
+}
+/** 课题去掉「课文 2」「识字 1」这种编号后的那截(「我是什么」) */
+const titleCore = (title) => title.replace(/^(课文|识字|语文园地|口语交际|快乐读书吧)\s*[0-9一二三四五六七八九十]*\s*/, '').trim();
+/** 孩子这句话提到的课:课题(去掉编号后至少两个字)出现在话里,或「课文 N」「第 N 课」 */
+function mentioned(lessons, text) {
+    const n = /(?:课文|第)\s*([0-9]{1,2})\s*课?/.exec(text)?.[1];
+    return lessons.filter((l) => {
+        const core = titleCore(l.title);
+        return (Array.from(core).length >= 2 && text.includes(core)) || (n !== undefined && new RegExp(`^课文\\s*${n}(?!\\d)`).test(l.title));
+    });
+}
+/** 一个字落在哪几课、会认还是会写:「海」:课文 2 我是什么 会写 */
+function charLine(c, lessons, books) {
+    const hits = lessons.flatMap((l) => {
+        const kinds = [l.recognize.includes(c) ? '会认' : '', l.write.includes(c) ? '会写' : ''].filter(Boolean);
+        return kinds.length ? [`${l.title} ${kinds.join('、')}`] : [];
+    });
+    return hits.length ? `「${c}」:${hits.join(';')}` : `「${c}」:不在这学期的识字、写字表里(${books})`;
+}
+/** 日记里链到这一课的段,最新那条的 `骨架:` 行(日期新的在前找) */
+function lastSteps(lesson, diaries) {
+    const link = `[[${lesson.book}#${lesson.title}]]`;
+    for (const d of [...diaries].sort((a, b) => (a.date < b.date ? 1 : -1))) {
+        for (const block of d.text.split(/^(?=## )/m).reverse()) {
+            if (!block.includes(link))
+                continue;
+            const steps = /^骨架[:：]\s*(.+)$/m.exec(block)?.[1];
+            if (steps)
+                return { line: `以前讲过「${lesson.title}」(${d.date}):骨架:${steps}`, from: d };
+        }
+    }
+    return null;
+}
+/**
+ * 这一轮替老师查的:query = 孩子这句话(加首页按钮的讲法);textbooks = 这科这学期的教材(cotutor: textbook);diaries = 最近的日记。
+ * lines 进上下文包的 lookup;caliber 是要带原文的口径(没有 = null);retrieved 记来源。什么都没查到 → 全空
+ */
+export function lookup(o) {
+    const books = o.textbooks.map((t) => ({ ...t, book: t.path.replace(/^.*\//, '').replace(/\.md$/, ''), lessons: parseTextbook(t.path.replace(/^.*\//, '').replace(/\.md$/, ''), t.text) }));
+    const lessons = books.flatMap((b) => b.lessons);
+    const lines = [];
+    const retrieved = [];
+    const used = (path, text, why) => {
+        const hit = retrieved.find((r) => r.path === path);
+        if (hit) {
+            if (!hit.why.includes(why))
+                hit.why += `;${why}`;
+        }
+        else
+            retrieved.push({ path, hash: textHash(text), why });
+    };
+    // 生字表:教材里有识字、写字行才查(数学的教材没有,别报一串「没有」)
+    const chars = lessons.some((l) => l.recognize.length || l.write.length) ? askedChars(o.query) : [];
+    for (const c of chars)
+        lines.push(charLine(c, lessons, books.map((b) => b.book).join('、')));
+    for (const b of books)
+        if (chars.length && b.lessons.some((l) => l.recognize.length || l.write.length))
+            used(b.path, b.text, `问到的字:${chars.join('、')}`);
+    // 那一课:提到的课,加问到的字要会写的那一课;最多两课
+    const hit = [...new Set([...mentioned(lessons, o.query), ...lessons.filter((l) => chars.some((c) => l.write.includes(c)))])].slice(0, 2);
+    const calibers = hit.filter((l) => l.caliber);
+    for (const l of hit) {
+        const b = books.find((x) => x.lessons.includes(l));
+        if (l.caliber)
+            used(b.path, b.text, `口径:${l.title}`);
+        const s = lastSteps(l, o.diaries);
+        if (s) {
+            lines.push(s.line);
+            used(s.from.path, s.from.text, `以前讲过:${l.title}`);
+        }
+    }
+    const max = o.maxCaliber ?? 1200;
+    const caliberText = calibers.map((l) => `## ${l.title}\n### 口径\n${l.caliber}`).join('\n\n');
+    const caliberPath = calibers.length ? books.find((x) => x.lessons.includes(calibers[0])).path : null;
+    return {
+        lines,
+        caliber: caliberPath ? { path: caliberPath, text: caliberText.length > max ? `${caliberText.slice(0, max)}\n……(后面截掉了)` : caliberText } : null,
+        retrieved,
+    };
+}

package/dist/memory/timetable.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 课程表解析(抄自 growth-apps apps/web/src/timetable.ts,2026-09-09;孩子列改为可选)。
+ * 表头须含 星期/时间/学科 三列(孩子列可有可无,顺序不限,多余列忽略);可以有多张表;列名对不上的表整张跳过。
+ * 错误即修复指南,带行号;解析尽量往下走,一次报全。
+ */
+import type { TimetableEntry } from '../schema/index.ts';
+export interface TimetableParse {
+    entries: TimetableEntry[];
+    /** 没找到任何课程表时 entries 为空且这里有整体指南 */
+    errors: string[];
+    found: boolean;
+}
+export declare function parseTimetable(md: string): TimetableParse;
+/** js Date → 1–7(周一–周日) */
+export declare function dayOf(now: Date): number;
+/** 当前正在进行的时段(第一条命中;不在任何时段 = null,不猜) */
+export declare function currentSlot(entries: readonly TimetableEntry[], now: Date): TimetableEntry | null;
+/** 上下文包的 slot 字段:「数学 16:00-17:00」 */
+export declare function slotLabel(e: TimetableEntry): string;

package/dist/memory/timetable.js

@@ -0,0 +1,95 @@
+const REQUIRED = ['星期', '时间', '学科'];
+const DAY_MAP = { 一: 1, 二: 2, 三: 3, 四: 4, 五: 5, 六: 6, 日: 7, 天: 7 };
+const cells = (line) => line
+    .replace(/^\s*\|/, '')
+    .replace(/\|\s*$/, '')
+    .split('|')
+    .map((c) => c.trim());
+const isTableRow = (line) => /^\s*\|.*\|\s*$/.test(line);
+const isSeparatorRow = (line) => isTableRow(line) && cells(line).every((c) => /^:?-{2,}:?$/.test(c) || c === '');
+function parseDay(raw) {
+    const s = raw.replace(/^(星期|周)/, '').trim();
+    if (/^[1-7]$/.test(s))
+        return Number(s);
+    return DAY_MAP[s] ?? null;
+}
+const TIME_RE = /^(\d{1,2}):(\d{2})\s*[-–—~至]+\s*(\d{1,2}):(\d{2})$/;
+function parseTime(raw) {
+    const m = TIME_RE.exec(raw.trim());
+    if (!m)
+        return null;
+    const [h1, m1, h2, m2] = [Number(m[1]), Number(m[2]), Number(m[3]), Number(m[4])];
+    if (h1 > 23 || h2 > 23 || m1 > 59 || m2 > 59)
+        return null;
+    const start = `${String(h1).padStart(2, '0')}:${m[2]}`;
+    const end = `${String(h2).padStart(2, '0')}:${m[4]}`;
+    if (start >= end)
+        return null;
+    return { start, end };
+}
+export function parseTimetable(md) {
+    const lines = md.split('\n');
+    const errors = [];
+    const entries = [];
+    let found = false;
+    let i = 0;
+    while (i < lines.length) {
+        if (!isTableRow(lines[i])) {
+            i++;
+            continue;
+        }
+        const header = cells(lines[i]);
+        const col = { 星期: header.indexOf('星期'), 时间: header.indexOf('时间'), 学科: header.indexOf('学科'), 孩子: header.indexOf('孩子') };
+        if (REQUIRED.some((name) => col[name] < 0)) {
+            i++;
+            while (i < lines.length && isTableRow(lines[i]))
+                i++;
+            continue;
+        }
+        found = true;
+        i++;
+        if (i < lines.length && isSeparatorRow(lines[i]))
+            i++;
+        for (; i < lines.length && isTableRow(lines[i]); i++) {
+            const row = cells(lines[i]);
+            const ln = i + 1;
+            const get = (name) => (col[name] >= 0 ? (row[col[name]] ?? '') : '');
+            const day = parseDay(get('星期'));
+            if (day === null) {
+                errors.push(`第 ${ln} 行:星期「${get('星期')}」认不出;写 一/二/…/日(或 1–7)`);
+                continue;
+            }
+            const time = parseTime(get('时间'));
+            if (!time) {
+                errors.push(`第 ${ln} 行:时间「${get('时间')}」应形如 19:00–19:40(起止用 – 或 - 连接,且结束晚于开始)`);
+                continue;
+            }
+            const subject = get('学科');
+            if (!subject) {
+                errors.push(`第 ${ln} 行:学科为空;写 语文/数学/英语 等(与 cotutor.json 里老师的 subject 对齐即归到那位老师)`);
+                continue;
+            }
+            const kid = get('孩子');
+            entries.push({ day, ...time, subject, ...(kid ? { kid } : {}) });
+        }
+    }
+    if (!found)
+        return { entries: [], errors: ['没找到课程表:课程表.md 里需要一张含 星期/时间/学科 三列表头的 markdown 表(孩子列可选)'], found: false };
+    entries.sort((a, b) => a.day - b.day || a.start.localeCompare(b.start));
+    return { entries, errors, found: true };
+}
+/** js Date → 1–7(周一–周日) */
+export function dayOf(now) {
+    const d = now.getDay();
+    return d === 0 ? 7 : d;
+}
+/** 当前正在进行的时段(第一条命中;不在任何时段 = null,不猜) */
+export function currentSlot(entries, now) {
+    const day = dayOf(now);
+    const hm = `${String(now.getHours()).padStart(2, '0')}:${String(now.getMinutes()).padStart(2, '0')}`;
+    return entries.find((e) => e.day === day && e.start <= hm && hm < e.end) ?? null;
+}
+/** 上下文包的 slot 字段:「数学 16:00-17:00」 */
+export function slotLabel(e) {
+    return `${e.subject} ${e.start}-${e.end}`;
+}

package/dist/memory/vault-notes.d.ts

@@ -0,0 +1,165 @@
+/**
+ * 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),中文键是给人看的描述,这里不读。
+ */
+import type { MemoryLine } from '../schema/index.ts';
+export declare const NOTE_KINDS: readonly ["profile", "subject", "textbook", "memory"];
+export type NoteKind = (typeof NOTE_KINDS)[number];
+export interface VaultNote {
+    /** 相对 vault 根,`/` 分隔 */
+    path: string;
+    props: Record<string, string>;
+    /** 整篇原文(含 frontmatter) */
+    text: string;
+}
+/** 只认平铺的 `key: value`;值去掉成对引号。没有 frontmatter → {} */
+export declare function frontmatter(md: string): Record<string, string>;
+/**
+ * 某天是几年级的哪个学期 / 假期:9–1 月上学期、2 月寒假、3–6 月下学期、7–8 月暑假(刚读完的那个年级的暑假)。
+ * 学年从 9 月算;`school_start` 是读一年级那年的 9 月(写别的月份也按它所在学年算)。年级不在 1–12 → null。
+ */
+export declare function semesterAt(schoolStart: string, date: string): string | null;
+/** 正文里的 `[[目标]]` / `![[目标|别名]]`:去掉 #节 与 |别名,去重,按出现顺序 */
+export declare function wikilinks(md: string): string[];
+/** 像 Obsidian 那样解析链接:先按相对根的完整路径(可省 .md),再按文件名(同名取路径最短的);找不到 → null */
+export declare function resolveLink(target: string, files: readonly string[]): string | null;
+export interface VaultPick {
+    profile: VaultNote | null;
+    /** 不止一个 `cotutor: profile` 时的其余几个(用写了 school_start / semester 的、再按路径的第一篇,doctor 报) */
+    extraProfiles: string[];
+    /** 当前学期;档案没有、没写 school_start 也没写 semester、或年级算不出 → null */
+    semester: string | null;
+    /** 这科这学期的入口文件;没有 → null(不沿用上学期的) */
+    entry: VaultNote | null;
+    /** 同一科同一学期不止一个入口文件时的其余几个 */
+    extraEntries: string[];
+    /** 这位 agent 的记忆文件;还没有 → null */
+    memory: VaultNote | null;
+    extraMemories: string[];
+    /** 孩子的记忆(`agent: all`);还没有 → null */
+    child: VaultNote | null;
+    /** 参考资料的路径:这科这学期的教材 + 档案与入口文件里的 [[链接]](去重,不含它俩自己) */
+    refs: string[];
+    /** 这科这学期的教材(取材用,memory/retrieval.ts) */
+    textbooks: VaultNote[];
+}
+/**
+ * 从扫出来的笔记里挑一位老师要的:档案、当前学期、入口文件、参考路径。
+ * `files` 是 vault 里所有文件的相对路径(解析 [[链接]] 用,不限 .md)。subject 没配 → 没有入口文件。
+ */
+export declare function pickNotes(notes: readonly VaultNote[], files: readonly string[], opts: {
+    date: string;
+    subject?: string;
+    agent?: string;
+}): VaultPick;
+/** 入口文件缺了为什么(进上下文包 entry: 与这条消息的 warnings;家长端就看得到) */
+export declare function missingEntry(subject: string | undefined, pick: {
+    profile: unknown;
+    semester: string | null;
+}): string;
+/** 记忆文件缺省位置:记忆/<显示名>.md(显示名里的 / 换掉) */
+export declare function memoryPath(display: string): string;
+/** 新建的记忆文件 */
+export declare function memoryTemplate(agent: string, display: string): string;
+/** 孩子的记忆(2026-10-30):`agent: all` 的那篇,缺省在 记忆/孩子.md;满了(列表行到 CHILD_MEMORY_CAP 条)新的不再进,提醒家长删 */
+export declare const CHILD_MEMORY_AGENT = "all";
+export declare const CHILD_MEMORY_PATH = "\u8BB0\u5FC6/\u5B69\u5B50.md";
+export declare const CHILD_MEMORY_CAP = 20;
+/** 新建的孩子的记忆 */
+export declare function childMemoryTemplate(): string;
+/**
+ * 往记忆文件末尾追加:每条一行 `- <日期> <原话>`(老师自己写了日期开头就不再加);文里已有同样的话就跳过。
+ * cap:列表行最多这么多条,满了的不加,进 full。返回新全文与真加上的行;一条都没加 → text 原样。
+ */
+export declare function appendMemory(existing: string, items: readonly string[], date: string, cap?: number): {
+    text: string;
+    added: string[];
+    full: string[];
+};
+/**
+ * 「## 记忆」段的一条(2026-09-18):缺省是新增;`改:原话 → 新的` 改一行;`删:原话` 删一行。
+ * 冒号全角半角都认,箭头认 → 与 ->。原话或新的里也有箭头(「宇宙→太空员」、骨架「数一数 → 分一分」)时切法不止一种:
+ * from / to 是从第一个箭头切的,alt 是其余箭头的切法(从左到右),applyMemoryOps 挑原话对得上的那种(2026-10-31)。
+ */
+export type MemoryOp = {
+    op: 'add';
+    text: string;
+} | {
+    op: 'change';
+    from: string;
+    to: string;
+    alt?: {
+        from: string;
+        to: string;
+    }[];
+} | {
+    op: 'delete';
+    from: string;
+};
+export declare function parseMemoryOp(item: string): MemoryOp;
+/** 一行改动给家长看的样子:新增的原话、「改:旧 → 新」、「删:旧」(家长端「记录」的「记住了」) */
+export declare function memoryLineText(l: MemoryLine): string;
+/**
+ * 按原话找一行:正文(frontmatter 之后)里原话一字不差的那行;没有就找唯一一行包含它的(原话至少 4 个字);都不是 → -1。
+ * 不分老师写的、家长写的(2026-09-18 定:机器一律可以改)。fuzzy = false 只认一字不差的(这轮里家长改过文件,2026-10-30)。
+ */
+export declare function findMemoryLine(lines: readonly string[], from: string, bodyStart: number, fuzzy?: boolean): number;
+export interface MemoryApplied {
+    text: string;
+    /** 给家长看的改动,一条一行:新增的原样(`- <日期> …`),改的「改:旧 → 新」,删的「删:旧」 */
+    changes: string[];
+    /** 找不到原话的改 / 删 */
+    misses: string[];
+    /** 满了没加上的新增(有 cap 时) */
+    full: string[];
+    /** 同一批改动的整行原文:before = 改之前那行(新增为 null),after = 改之后那行(删掉为 null);删话题时 undoMemoryLines 按它撤销 */
+    lines: MemoryLine[];
+}
+export type { MemoryLine };
+/**
+ * 把一串操作落到记忆全文上:先改、删(按原话找行,见 findMemoryLine),再把新增的追加到末尾(appendMemory,去重)。
+ * 改过的列表行换成 `- <今天> 新的`(新的自己带着日期就去掉,不写两个日期);不是列表的行整行换成新的。strict:改、删只认一字不差的原话;cap:新增后最多几条(先删后加,删掉的腾出地方)。
+ * 改有几种切法(parseMemoryOp 的 alt)时:先挑原话一字不差的那种;都不是再模糊找,原话长的先(短的是长的前缀,会把原话后半截切进新的里)。
+ */
+export declare function applyMemoryOps(existing: string, ops: readonly MemoryOp[], date: string, opts?: {
+    strict?: boolean;
+    cap?: number;
+}): MemoryApplied;
+/**
+ * 撤销一串改动(删话题时,2026-10-05):倒着来——改了的换回原来那行,新增的删掉,删了的接回末尾(原来的位置不记)。
+ * 按整行原文找;家长或整理那轮后来又改过那行就找不到,进 misses,不动。
+ */
+export declare function undoMemoryLines(existing: string, edits: readonly MemoryLine[]): {
+    text: string;
+    undone: number;
+    misses: string[];
+};
+/** 记忆文件里有几条(frontmatter 之后的列表行) */
+export declare function memoryCount(text: string): number;
+/**
+ * 记账后整理记忆那轮的消息正文(2026-09-18):新会话、from: system;记忆原文在上下文包的 <vault-note role="memory">。
+ * 回的「## 记忆」段不受每轮条数上限,应用照单落盘、不问家长(家长在 Obsidian 里兜底)。
+ */
+export declare function tidyMemoryPrompt(opts: {
+    date: string;
+    count: number;
+    cap: number;
+    diaryFile: string;
+}): string;
+/**
+ * 按 entryChars 截一篇笔记带进上下文包。档案、入口文件留开头(家长写在前面的最要紧);
+ * 记忆留末尾——应用往末尾追加,最新的在后面,截开头丢的是旧的(2026-09-18 之前留的是开头,越记越看不到新的)。
+ * 末尾那头从一行的开头起,不截半行。
+ */
+export declare function clipNote(text: string, limit: number, keep: 'head' | 'tail'): {
+    text: string;
+    cut: boolean;
+};
+/** 短 hash(FNV-1a 32 位):同一话题里判断「这篇上次带过、没改」 */
+export declare function textHash(s: string): string;