cotutor 0.2.0 → 0.3.0

package/dist/app/replay.d.ts

@@ -0,0 +1,94 @@
+import type { Workspace } from '../schema/index.ts';
+import { type DiffRow } from './diff.ts';
+import { type Tokens } from '../shared/tokens.ts';
+import { type ToolCall } from '../brain/transcript.ts';
+import type { ConversationMessage, Timing } from '../schema/index.ts';
+export declare const EVALS_DIR = "evals";
+export interface ReplayOptions {
+    /** 换个运行时跑(比模型 / 比 CLI);缺省老师自己的 */
+    runtime?: string;
+    now?: () => Date;
+    env?: NodeJS.ProcessEnv;
+}
+/** 回放用的 Workspace:对话目录换成 evals/、老师全部开着、不配音 */
+export declare function evalWorkspace(ws: Workspace): Workspace;
+export interface ReplayStarted {
+    tutor: string;
+    date: string;
+    /** 原轮 */
+    job: string;
+    /** 回放那轮在 evals/<老师>/<日期>.json 里的 job */
+    evalJob: string;
+    done: Promise<void>;
+}
+/**
+ * 起一次回放:原轮的问题(谁问的、文字、照片、动作、端)原样再发,上下文包按现在重拼。
+ * 原轮带的「孩子在卡上做的」(cards: 段)回放里没有——那是话题里上一轮的卡,回放是新话题;compare 的 notes 会标出来。
+ */
+export declare function startReplay(ws: Workspace, tutor: string, date: string, job: string, opts?: ReplayOptions): Promise<ReplayStarted>;
+/** 一轮的一侧(原轮或回放),给并排看 */
+export interface RunSide {
+    job: string;
+    at: string;
+    result: ConversationMessage['result'];
+    error: string | null;
+    runtime: string | null;
+    tokens: Tokens | null;
+    timing: Timing | null;
+    kidText: string | null;
+    lines: string[];
+    cards: string[];
+    tools: ToolCall[];
+    parentText: string;
+    warnings: string[];
+    /** 上下文包 + 消息(run.json 的 prompt);老 workspace 没落就 null */
+    prompt: string | null;
+    /** 当时的老师文件 hash(run.json sources);没记就 null */
+    agentHash: string | null;
+    /** 原轮带给老师的「孩子在卡上做的」几句(回放没有) */
+    cardsContext: string[];
+}
+export interface Compare {
+    tutor: string;
+    date: string;
+    job: string;
+    evalJob: string;
+    status: ConversationMessage['result'];
+    orig: RunSide;
+    next: RunSide;
+    /** 上下文包的 diff(只留变了的行前后两行) */
+    pack: DiffRow[];
+    lines: DiffRow[];
+    cards: DiffRow[];
+    tools: DiffRow[];
+    /** 看的时候要知道的:回放没带 cards: 段、老师文件变没变之类 */
+    notes: string[];
+}
+export declare function sideOf(m: ConversationMessage, run: {
+    prompt: string;
+    sources?: {
+        agent: {
+            hash: string;
+        } | null;
+    };
+} | null, tools: ToolCall[]): RunSide;
+/** 纯函数:两侧 → 并排 diff */
+export declare function compareSides(base: {
+    tutor: string;
+    date: string;
+    job: string;
+    evalJob: string;
+}, orig: RunSide, next: RunSide): Compare;
+export declare function compareReplay(ws: Workspace, tutor: string, date: string, evalJob: string): Promise<Compare | null>;
+export interface ReplayRow {
+    evalJob: string;
+    replayOf: string;
+    at: string;
+    result: ConversationMessage['result'];
+    tokens: Tokens | null;
+    runtime: string | null;
+}
+/** 这天回放过哪些(evals/<老师>/<日期>.json 里 replayOf 指向 job 的;不给 job 就全部) */
+export declare function listReplays(ws: Workspace, tutor: string, date: string, job?: string): Promise<ReplayRow[]>;
+/** 终端打印 */
+export declare function formatCompare(c: Compare): string;

package/dist/app/replay.js

@@ -0,0 +1,170 @@
+/**
+ * 回放(2026-09-15):把某一轮的问题,按**现在**的 vault / 老师文件 / 技能重新问一遍,和原轮并排比。
+ * 手改了提示词或 vault 之后「效果好不好」不靠打分,靠人眼看 diff:上下文包哪几行变了、讲稿哪几句变了、卡变没变、
+ * 读了什么文件、token 与用时。只有 CLI(`cotutor replay` / `cotutor compare`),家长端不露;给在 workspace 里开编程助手分析用。
+ *
+ * 落在 workspace 的 evals/(和 conversations/ 同一套文件:索引 / run.json / log / events),不进孩子的对话、
+ * 永远新话题新会话;不配音。做法是给 Runner 一个改了目录与配置的 Workspace,
+ * 跑的仍是同一条路(gatherContext → buildContextPack → spawn → 解析 → 物化),所以看到的就是真跑会看到的。
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { cardLabel } from "../board/cards/index.js";
+import { logParser } from "../brain/index.js";
+import { UsageError } from "../shared/errors.js";
+import { conversationFiles, threads } from "../schema/index.js";
+import { compactDiff, diffLines } from "./diff.js";
+import { tokenText } from "../shared/tokens.js";
+import { toolCalls } from "../brain/transcript.js";
+import { continueContext, homeButtonAt } from "../runtime/home/store.js";
+import { Runner } from "../runtime/runner.js";
+import { threadActivity } from "../runtime/activity-state.js";
+import { readIndex, readRunFile } from "../runtime/journal/store.js";
+export const EVALS_DIR = 'evals';
+/** 回放用的 Workspace:对话目录换成 evals/、老师全部开着、不配音 */
+export function evalWorkspace(ws) {
+    const tutors = Object.fromEntries(Object.entries(ws.config.tutors).map(([k, t]) => {
+        const { voice: _voice, ...rest } = t;
+        return [k, { ...rest, enabled: true }];
+    }));
+    return { ...ws, config: { ...ws.config, tutors }, dirs: { ...ws.dirs, conversations: join(ws.root, EVALS_DIR) } };
+}
+/**
+ * 起一次回放:原轮的问题(谁问的、文字、照片、动作、端)原样再发,上下文包按现在重拼。
+ * 原轮带的「孩子在卡上做的」(cards: 段)回放里没有——那是话题里上一轮的卡,回放是新话题;compare 的 notes 会标出来。
+ */
+export async function startReplay(ws, tutor, date, job, opts = {}) {
+    if (!ws.config.tutors[tutor])
+        throw new UsageError(`没有叫 ${tutor} 的老师;cotutor.json 的 tutors 里有:${Object.keys(ws.config.tutors).join('、')}`);
+    const index = await readIndex(ws, tutor, date);
+    const m = index.messages.find((x) => x.job === job);
+    if (!m)
+        throw new UsageError(`${tutor} ${date} 没有 ${job} 这一轮(日期缺省今天;job 与日期对不对?)`);
+    if (m.bookkeep)
+        throw new UsageError('记账那轮不回放(它 resume 话题的会话,单独跑没有意义)');
+    const evalWs = evalWorkspace(ws);
+    const runner = new Runner(() => evalWs, { now: opts.now, env: opts.env });
+    // 从首页按钮进来的那轮:讲法从当时发布的那份原文取,接着的话题从原 workspace 读(回放的 workspace 指到 evals/)
+    const button = m.via && typeof m.via.button === 'number' ? await homeButtonAt(ws, tutor, m.via) : null;
+    const continued = m.continues ? await continueContext(ws, tutor, m.continues.date, m.continues.thread) : null;
+    // activity 话题里的哪一轮:照话题第一条记的 activity 带(回放是新会话,activity 那段整篇带)
+    const activity = threadActivity(index.messages, threads(index.messages)[index.messages.indexOf(m)]);
+    const started = await runner.send(tutor, {
+        from: m.from,
+        text: m.text,
+        focus: m.focus,
+        action: m.action,
+        photos: m.photos,
+        device: m.device,
+        newThread: true,
+        date,
+        replayOf: job,
+        runtime: opts.runtime,
+        ...(m.via ? { via: m.via } : {}),
+        ...(m.via && typeof m.via.button === 'number' ? { home: { button: m.via.label, ...(button?.brief ? { brief: button.brief } : {}) } } : {}),
+        ...(m.continues && continued ? { continues: { ...m.continues, pack: continued } } : {}),
+        ...(activity ? { activity } : {}),
+        // 原轮是实时的:回放也按实时写(上下文包带 live:、不补提问卡);嘴不在,接住与打断的 caught / cut 不带
+        ...(m.live ? { live: {} } : {}),
+    });
+    return { tutor, date, job, evalJob: started.job, done: started.done.then(() => runner.flush()) };
+}
+const toolLine = (t) => `${t.name}${t.arg ? ` ${t.arg}` : ''}${t.ok === false ? ' ✗' : ''}${t.sub ? ' (子代理)' : ''}`;
+export function sideOf(m, run, tools) {
+    return {
+        job: m.job,
+        at: m.at,
+        result: m.result,
+        error: m.error ?? null,
+        runtime: m.runtime ?? null,
+        tokens: m.tokens ?? null,
+        timing: m.timing ?? null,
+        kidText: m.kidText ?? null,
+        lines: m.section?.lines.map((l) => l.text) ?? [],
+        cards: m.section?.cards.map((c, i) => `卡 ${i + 1}　${c.kind} ${cardLabel(c)}`.trim()) ?? [],
+        tools,
+        parentText: m.parentText ?? '',
+        warnings: m.warnings ?? [],
+        prompt: run?.prompt ?? null,
+        agentHash: run?.sources?.agent?.hash ?? null,
+        cardsContext: m.cards?.map((c) => `${c.card} ${c.text}`) ?? [],
+    };
+}
+/** 纯函数:两侧 → 并排 diff */
+export function compareSides(base, orig, next) {
+    const notes = [];
+    if (orig.cardsContext.length)
+        notes.push(`原轮带了孩子在卡上做的 ${orig.cardsContext.length} 条(cards: 段),回放是新话题,没带`);
+    if (orig.prompt === null)
+        notes.push('原轮没落 run.json(装新版之前跑的),上下文包比不了');
+    if (orig.agentHash && next.agentHash)
+        notes.push(orig.agentHash === next.agentHash ? '老师文件没变(hash 一样):差异来自 vault、技能或模型本身' : `老师文件变了:${orig.agentHash.slice(7)} → ${next.agentHash.slice(7)}`);
+    if (orig.runtime && next.runtime && orig.runtime !== next.runtime)
+        notes.push(`运行时不同:原轮 ${orig.runtime},回放 ${next.runtime}`);
+    const promptLines = (p) => (p === null ? [] : p.split('\n'));
+    return {
+        ...base,
+        status: next.result,
+        orig,
+        next,
+        pack: orig.prompt !== null && next.prompt !== null ? compactDiff(diffLines(promptLines(orig.prompt), promptLines(next.prompt))) : [],
+        lines: diffLines(orig.lines, next.lines),
+        cards: diffLines(orig.cards, next.cards),
+        tools: diffLines(orig.tools.map(toolLine), next.tools.map(toolLine)),
+        notes,
+    };
+}
+/** 一轮的工具调用:索引里物化过就用它,没有(老轮次)就从 .log 现抽 */
+async function toolsOf(ws, tutor, date, m) {
+    if (m.tools)
+        return m.tools;
+    const text = await readFile(conversationFiles(ws.dirs.conversations, tutor, date).log(m.job), 'utf8').catch(() => '');
+    return toolCalls(text, logParser(ws.config.runtimes, m.runtime));
+}
+export async function compareReplay(ws, tutor, date, evalJob) {
+    const evalWs = evalWorkspace(ws);
+    const evalIndex = await readIndex(evalWs, tutor, date);
+    const next = evalIndex.messages.find((x) => x.job === evalJob);
+    if (!next?.replayOf)
+        return null;
+    const index = await readIndex(ws, tutor, date);
+    const orig = index.messages.find((x) => x.job === next.replayOf);
+    if (!orig)
+        return null;
+    const [origRun, nextRun, origTools, nextTools] = await Promise.all([readRunFile(ws, tutor, date, orig.job), readRunFile(evalWs, tutor, date, evalJob), toolsOf(ws, tutor, date, orig), toolsOf(evalWs, tutor, date, next)]);
+    return compareSides({ tutor, date, job: orig.job, evalJob }, sideOf(orig, origRun, origTools), sideOf(next, nextRun, nextTools));
+}
+/** 这天回放过哪些(evals/<老师>/<日期>.json 里 replayOf 指向 job 的;不给 job 就全部) */
+export async function listReplays(ws, tutor, date, job) {
+    const evalIndex = await readIndex(evalWorkspace(ws), tutor, date);
+    return evalIndex.messages.filter((m) => m.replayOf && (!job || m.replayOf === job)).map((m) => ({ evalJob: m.job, replayOf: m.replayOf, at: m.at, result: m.result, tokens: m.tokens ?? null, runtime: m.runtime ?? null }));
+}
+/** 终端打印 */
+export function formatCompare(c) {
+    const out = [];
+    const side = (s) => `${s.tokens ? tokenText(s.tokens) : 'token ?'}${s.timing?.doneMs !== undefined ? ` · ${(s.timing.doneMs / 1000).toFixed(1)}s` : ''}${s.runtime ? ` · ${s.runtime}` : ''}`;
+    out.push(`回放 ${c.tutor} ${c.date} ${c.job} → evals/${c.tutor}/${c.date}.${c.evalJob}.*(${c.status})`);
+    out.push(`  - 原轮 ${c.orig.at} · ${side(c.orig)}${c.orig.error ? ` · 出错 ${c.orig.error}` : ''}`);
+    out.push(`  + 回放 ${c.next.at} · ${side(c.next)}${c.next.error ? ` · 出错 ${c.next.error}` : ''}`);
+    for (const n of c.notes)
+        out.push(`  ! ${n}`);
+    const section = (title, rows, empty) => {
+        const changed = rows.filter((r) => r.s !== '·').length;
+        out.push(`\n## ${title}${rows.length ? `(${changed ? `${changed} 处不同` : '一样'})` : `(${empty})`}`);
+        for (const r of rows)
+            out.push(`${r.s} ${r.text}`);
+    };
+    section('上下文包', c.pack, '没有可比的');
+    section('讲稿', c.lines, '两边都没有讲稿');
+    section('卡', c.cards, '两边都没有卡');
+    section('读了什么', c.tools, '两边都没用工具');
+    if (c.orig.parentText || c.next.parentText) {
+        out.push('\n## 给家长的尾巴');
+        out.push(`- ${c.orig.parentText || '(无)'}`);
+        out.push(`+ ${c.next.parentText || '(无)'}`);
+    }
+    if (c.orig.warnings.length || c.next.warnings.length)
+        out.push(`提醒:原轮 ${c.orig.warnings.join(';') || '无'} / 回放 ${c.next.warnings.join(';') || '无'}`);
+    out.push(`\n回放那轮自己的全部:cotutor show ${c.tutor} ${c.evalJob} ${c.date} --evals`);
+    return `${out.join('\n')}\n`;
+}

package/dist/app/skills/analyze-doc.d.ts

@@ -0,0 +1,3 @@
+export declare const ANALYZE_SKILL = "cotutor-analyze";
+export declare function analyzeReferenceDoc(): string;
+export declare function analyzeSkillGeneratedFiles(): Record<string, string>;

package/dist/app/skills/analyze-doc.js

@@ -0,0 +1,47 @@
+/**
+ * cotutor-analyze 技能的生成部分(2026-09-15):references/命令与文件.md 从 CLI 的用法文本(app/cli/usage.ts)与对话文件的命名规则(runtime/journal/conversation.ts
+ * conversationFiles)现生成,scripts/gen-skills.ts 写进包根 skills/cotutor-analyze/,tests/skills.test.ts 断言入库的和生成的一致——
+ * 技能里的命令与文件名永远和代码同源。SKILL.md 本体(怎么查、禁区)是手写的。
+ */
+import { USAGE } from "../cli/usage.js";
+import { conversationFiles } from "../../schema/index.js";
+export const ANALYZE_SKILL = 'cotutor-analyze';
+/** 分析用的那几条命令(按用法文本里的第二个词挑) */
+const ANALYZE_COMMANDS = ['show', 'pack', 'replay', 'compare', 'trace', 'doctor', 'send', 'rate', 'bookkeep'];
+export function analyzeReferenceDoc() {
+    const cmds = USAGE.split('\n').filter((l) => {
+        const m = /^\s+cotutor (\S+)/.exec(l);
+        return m !== null && ANALYZE_COMMANDS.includes(m[1]);
+    });
+    const f = conversationFiles('conversations', '<老师>', '<日期>');
+    const rows = [
+        [f.index, '一天的索引:每条消息物化了 text / kidText / section(卡与讲稿)/ tools(读了什么)/ timing / tokens(这轮老师用的 token:输入 / 输出)/ warnings / bookkeeping;顶层 sessions / ratings / booked(老数据里还有 costUsd,是 claude 时代的美元,不用管)'],
+        [f.run('<job>'), '这轮发给老师的:prompt(上下文包 + 消息)、argv(完整命令行)、resume / session、sources(当时的老师文件正文与 hash、技能 SKILL.md 的 hash)'],
+        [f.log('<job>'), '老师进程的 stdout 原样(stream-json):每次 tool_use 的完整参数、tool_result 的内容、文本、result(token、轮数)。最大最全,别整个读,按 job 与关键字 grep'],
+        [f.err('<job>'), 'stderr'],
+        [f.events('<job>'), '这轮的事件流,一行一条 {t, lane, kind, …}:main 老师 / tts 配音 / ready 就绪 / index / ledger;cotutor trace 读它'],
+        [f.card('<job>', 9999).replace('9999', '<n>'), '第 n 张卡的状态(孩子在卡上做的):{at, turn, state}'],
+        [f.cardAsset('<job>', 9999, '<k>.mp3').replace('9999', '<n>'), '卡的资产(点读段配音)'],
+    ];
+    return `# 命令与文件(机器生成,别改)
+
+## 分析用的命令(在 workspace 根跑;完整用法 cotutor --help)
+
+\`\`\`
+${cmds.join('\n')}
+\`\`\`
+
+## 一轮的文件(conversations/ 下;回放的在 evals/ 下,同一套名字)
+
+job 形如 1620-1(时分-当天序号)。
+
+| 文件 | 是什么 |
+|---|---|
+${rows.map(([p, d]) => `| \`${p}\` | ${d} |`).join('\n')}
+
+上下文包里每一行是什么、路径后面的状态怎么看,见 \`.agents/skills/cotutor-tutor/references/上下文包.md\`;截断的上限是哪个政策旋钮,见 cotutor-tune 的 references/字段.md。
+`;
+}
+export function analyzeSkillGeneratedFiles() {
+    return { 'references/命令与文件.md': analyzeReferenceDoc() };
+}

package/dist/app/skills/home-doc.d.ts

@@ -0,0 +1,5 @@
+export declare const HOME_SKILL = "cotutor-home";
+export declare function homeSyntaxDoc(dir?: string): string;
+export declare function homeCommandsDoc(): string;
+/** references/ 下的全部文件(相对技能根) */
+export declare function homeSkillGeneratedFiles(dir?: string): Record<string, string>;

package/dist/app/skills/home-doc.js

@@ -0,0 +1,112 @@
+/**
+ * cotutor-home 技能的生成部分:references/ 整个由这里现生成,scripts/gen-skills.ts 写进包根 skills/cotutor-home/,
+ * tests/skills.test.ts 断言入库的和生成的一致。首页语法.md 从首页能用的卡的 card.md 拼(首页专属的全文,和板书共用的只给一句 + 指向 cotutor-board),
+ * <kind>.md 是首页专属卡的协议全文,命令.md 从 CLI 用法文本取。SKILL.md 本体(流程、铁律)是手写的。
+ */
+import { USAGE } from "../cli/usage.js";
+import { BUTTON_LABEL_MAX, TUTOR_BUTTONS_MAX, kindsFor } from "../../board/cards/index.js";
+import { PACKAGE_CARDS_DIR, readCardDoc } from "../../board/cards/docs.js";
+export const HOME_SKILL = 'cotutor-home';
+const EXPECT_RE = /^\s*<!--\s*expect\b.*?-->\s*\n?/gm;
+const HOME_COMMANDS = ['home', 'show', 'rate', 'bookkeep'];
+/** 只用在首页的种类(板书里不能用的) */
+function homeOnly() {
+    return kindsFor('home').filter((k) => !(k.where ?? ['board']).includes('board')).map((k) => k.name);
+}
+export function homeSyntaxDoc(dir = PACKAGE_CARDS_DIR) {
+    const only = homeOnly();
+    const own = only.map((kind) => {
+        const d = readCardDoc(kind, dir);
+        return [`### ${d.headline}`, d.sections['是什么'], d.sections['写法'], d.sections['例子']?.replace(EXPECT_RE, '')].filter((x) => x && x.trim()).join('\n\n');
+    });
+    const shared = kindsFor('home')
+        .filter((k) => !only.includes(k.name))
+        .map((k) => {
+        const d = readCardDoc(k.name, dir);
+        const what = (d.sections['是什么'] ?? '').split('\n').find((l) => l.trim()) ?? '';
+        return `- \`${k.name}\`:${what} 写法见 ../../cotutor-board/references/${k.name}.md(首页上没有讲稿,那里说「讲到这张卡时」的动作不会发生;孩子点了照样能用)。`;
+    });
+    return `# 首页怎么写(机器生成,别改)
+
+首页文件是 workspace 的 home/draft.md,和板书同一个解析器:
+
+- **frontmatter**(可选):只认 \`for: YYYY-MM-DD\`(这份是给哪天用的)。
+- **围栏 = 卡**:标签第一个词是种类,其余是修饰。卡按文件顺序铺;老师卡永远排在最上面。
+- **第一个 \`## \` 起是给家长的**(「## 为什么这么排」),孩子看不到。
+- 围栏外的普通行首页不显示(检查会提醒),要给孩子看的写进卡里。
+
+应用保证的:每位孩子端露出的老师都有一张老师卡(没写就补一张只有「新话题」的);「新话题」永远是第一个按钮;应用不加「接着刚才的」——今天从同一个入口聊过的,孩子进老师页后在空白板上接(新话题是一个胶囊,activity、小课堂先问接着那个还是重新开始);引用坏了(话题找不到)的按钮不出现。
+
+老师卡的按钮最多 ${TUTOR_BUTTONS_MAX} 个,每个最多 ${BUTTON_LABEL_MAX} 个字。
+
+## 首页专属的卡
+
+${own.join('\n\n')}
+
+## 和板书共用的卡
+
+${shared.join('\n')}
+
+只能用在板书里的卡(选择题、填空、画板、讲解动画、代码)首页放不了——它们做完要交给某位老师。
+
+## 一份完整的草稿
+
+\`\`\`\`markdown
+---
+for: 2026-09-18
+---
+
+\`\`\`tutor chinese-tutor
+我要预习小蝌蚪找妈妈
+讲法: 第 22 课。先带他把 1–3 自然段读顺,重点字 塘、脑、袋;读完问他小蝌蚪先遇到了谁
+接着 2026-09-16 1930-1 接着写看图写话
+讲法: 上次第二句卡住了,先把他写的两句念给他听再往下
+\`\`\`
+
+\`\`\`tutor math-tutor
+再练两道退位减法
+讲法: 出 52−7、80−3,先让他说怎么想,跨十那一步慢一点
+\`\`\`
+
+\`\`\`tianzige
+塘脑袋
+\`\`\`
+
+## 为什么这么排
+
+- 语文:16 号小蝌蚪只读到第 1 段;看图写话第二句卡住,日记观察「句子接不上时会停很久」。
+- 数学:近两周观察里两次跨十停顿,计划里写了周五小测。
+- 英语老师今天没有要接的,只留新话题。
+\`\`\`\`
+`;
+}
+export function homeCommandsDoc() {
+    const cmds = USAGE.split('\n').filter((l) => {
+        const m = /^\s+cotutor (\S+)/.exec(l);
+        return m !== null && HOME_COMMANDS.includes(m[1]);
+    });
+    return `# 命令(机器生成,别改)
+
+在 workspace 根跑;完整用法 cotutor --help。
+
+\`\`\`
+${cmds.join('\n')}
+\`\`\`
+
+## 文件
+
+| 文件 | 是什么 |
+|---|---|
+| \`home/draft.md\` | 草稿:你写、家长可改;孩子端不读 |
+| \`home/published.json\` | 已发布的那份(publish 生成,机器件,别手改);孩子端只读它 |
+| \`home/history/<id>.md\` | 每次发布的原文 |
+| \`conversations/<老师>/<日期>.json\` | 一天的对话索引;消息的 \`via\` = 从首页哪个按钮进来的(\`{home, button, label}\`),\`continues\` = 接着哪天哪个话题 |
+`;
+}
+/** references/ 下的全部文件(相对技能根) */
+export function homeSkillGeneratedFiles(dir = PACKAGE_CARDS_DIR) {
+    const out = { 'references/首页语法.md': homeSyntaxDoc(dir), 'references/命令.md': homeCommandsDoc() };
+    for (const kind of homeOnly())
+        out[`references/${kind}.md`] = readCardDoc(kind, dir).md;
+    return out;
+}

package/dist/app/skills/tune-doc.d.ts

@@ -0,0 +1,3 @@
+export declare const TUNE_SKILL = "cotutor-tune";
+export declare function tuneReferenceDoc(): string;
+export declare function tuneSkillGeneratedFiles(): Record<string, string>;

package/dist/app/skills/tune-doc.js

@@ -0,0 +1,80 @@
+/**
+ * cotutor-tune 技能的生成部分(2026-09-15):references/字段.md 从 cotutor.json 的契约(schema/config.ts 的 .describe() 与 POLICY_DEFAULTS)、
+ * 老师文件 frontmatter 的允许键(runtime/agent-file.ts)与 CLI 用法(app/cli/usage.ts)现生成,scripts/gen-skills.ts 写进包根 skills/cotutor-tune/,
+ * tests/skills.test.ts 断言入库的和生成的一致——改老师团时能改哪些字段、缺省是什么,永远和契约同源。SKILL.md 本体(三条路子、禁区)是手写的。
+ */
+import { z } from 'zod';
+import { USAGE } from "../cli/usage.js";
+import { POLICY_DEFAULTS, PolicySchema, TutorSchema } from "../../schema/config.js";
+import { AGENT_FRONTMATTER_KEYS } from "../../runtime/agent-file.js";
+export const TUNE_SKILL = 'cotutor-tune';
+const TUNE_COMMANDS = ['add', 'add-theme', 'upgrade', 'doctor', 'pack', 'replay', 'compare', 'show'];
+function unwrap(s) {
+    let cur = s;
+    for (let i = 0; i < 5; i++) {
+        if (cur instanceof z.ZodOptional || cur instanceof z.ZodNullable)
+            cur = cur.unwrap();
+        else if (cur instanceof z.ZodDefault)
+            cur = cur.removeDefault();
+        else
+            break;
+    }
+    return cur;
+}
+/** 一个 zod object 的字段行;嵌套的 object 展开成 a.b */
+function rows(shape, defaults, prefix = '') {
+    const out = [];
+    for (const [k, s] of Object.entries(shape)) {
+        const inner = unwrap(s);
+        const key = `${prefix}${k}`;
+        if (inner instanceof z.ZodObject) {
+            out.push(...rows(inner.shape, defaults?.[k] ?? undefined, `${key}.`));
+            continue;
+        }
+        const optional = s.safeParse(undefined).success;
+        const d = defaults?.[k];
+        const dv = d === undefined ? '' : Array.isArray(d) ? d.join(',') : String(d);
+        out.push(`| \`${key}\` | ${optional ? '可选' : '必需'} | ${dv} | ${s.description ?? inner.description ?? ''} |`);
+    }
+    return out;
+}
+export function tuneReferenceDoc() {
+    const cmds = USAGE.split('\n').filter((l) => {
+        const m = /^\s+cotutor (\S+)/.exec(l);
+        return m !== null && TUNE_COMMANDS.includes(m[1]);
+    });
+    // tutors 字段的缺省从 zod 的 .default() 取(enabled / hidden);display 是必需的,给个占位再抹掉
+    const tutorDefaults = TutorSchema.parse({ display: 'x' });
+    delete tutorDefaults.display;
+    const tutorRows = rows(TutorSchema.shape, tutorDefaults).filter((r) => !r.startsWith('| `policy'));
+    const policyRows = rows(PolicySchema.shape, POLICY_DEFAULTS);
+    return `# 能改的字段(机器生成,别改)
+
+## 老师文件 agents/<name>.md
+
+frontmatter 只写应用支持的这几个键:${AGENT_FRONTMATTER_KEYS.map((k) => `\`${k}\``).join('、')}。\`name\` 必须等于文件名,也是 cotutor.json 里 tutors 的键,**不能改**。正文就是系统提示。
+
+## cotutor.json 的 tutors.<name>(人设、开关、运行时)
+
+| 字段 | 必需 | 缺省 | 说明 |
+|---|---|---|---|
+${tutorRows.join('\n')}
+
+\`policy\` 是下面这张表的子集,写了的覆盖 policyDefaults,没写的继承。
+
+## 政策(policyDefaults,或 tutors.<name>.policy 按老师覆盖)
+
+| 字段 | 必需 | 出厂缺省 | 说明 |
+|---|---|---|---|
+${policyRows.join('\n')}
+
+## 相关命令(完整用法 cotutor --help)
+
+\`\`\`
+${cmds.join('\n')}
+\`\`\`
+`;
+}
+export function tuneSkillGeneratedFiles() {
+    return { 'references/字段.md': tuneReferenceDoc() };
+}

package/dist/app/talk/list.d.ts

@@ -0,0 +1,11 @@
+import { type ListResult } from '../../scenes/talk/list.ts';
+export * from '../../scenes/talk/list.ts';
+export declare function readList(photo: {
+    data: Buffer;
+    mime: string;
+}, opts?: {
+    env?: NodeJS.ProcessEnv;
+    endpoint?: string;
+    model?: string;
+    timeoutMs?: number;
+}): Promise<ListResult>;

package/dist/app/talk/list.js

@@ -0,0 +1,9 @@
+/**
+ * 旧路径与接线:口语单的规则在 src/scenes/talk/list.ts,看图的请求在 src/media/vision.ts;readList 把两样接起来(路由、测试用)
+ */
+import { lookAt } from "../../media/vision.js";
+import { readListWith } from "../../scenes/talk/list.js";
+export * from "../../scenes/talk/list.js";
+export function readList(photo, opts = {}) {
+    return readListWith(lookAt, photo, opts);
+}

package/dist/app/talk/route.d.ts

@@ -0,0 +1,16 @@
+import type { AppContext, RouteResult } from '../http/app.ts';
+import { readList, type ListItem } from './list.ts';
+export interface TalkDeps {
+    /** 照片 → 口语单(测试换假的) */
+    readList: typeof readList;
+    env?: NodeJS.ProcessEnv;
+}
+/** data:image/…;base64,… → 字节;不是图、太大 → undefined */
+export declare function photoData(v: unknown): {
+    data: Buffer;
+    mime: string;
+} | undefined;
+/** 改过的口语单:两组各最多 12 / 8 条,去空去重;词带回来的 emoji 与分段再过一遍单词卡的 parse(改了词,旧分段拼不回就丢) */
+export declare function parseItems(v: unknown, max: number, card?: boolean): ListItem[] | null;
+export declare function makeTalkRoute(deps?: TalkDeps): (method: string, url: URL, ctx: AppContext, body: unknown) => Promise<RouteResult | null>;
+export declare const talkRoute: (method: string, url: URL, ctx: AppContext, body: unknown) => Promise<RouteResult | null>;