cotutor 0.1.0 → 0.2.0

package/dist/server/store.js

@@ -0,0 +1,210 @@
+/**
+ * 对话与配置的文件层:索引读写(坏索引响亮报错,不静默覆盖)、日期列表、转录读取、老师正文、cotutor.json 补丁写回。
+ * 纯函数在 lib/,这里只碰文件系统。
+ */
+import { mkdir, readFile, readdir, rename, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseAgentFile } from "../lib/agent-file.js";
+import { cardAssetName, conversationFiles, emptyIndex } from "../lib/conversation.js";
+import { parseTranscript } from "../lib/transcript.js";
+import { ConversationIndexSchema, CotutorConfigSchema, DATE_RE, explainIssues, } from "../schema/index.js";
+import { ConfigError, assembleWorkspace, parseConfig, readJson, redactHome } from "../cli/workspace.js";
+export class IndexError extends Error {
+    constructor(file, cause) {
+        super(`对话索引用不了:${redactHome(file)}\n${cause}\n修好它或改名挪开(转录 .log 还在,能重建);不要删。`);
+    }
+}
+export async function readIndex(ws, tutor, date) {
+    const file = conversationFiles(ws.dirs.conversations, tutor, date).index;
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch {
+        return emptyIndex(tutor, date);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (err) {
+        throw new IndexError(file, `不是合法 JSON:${err instanceof Error ? err.message : String(err)}`);
+    }
+    const r = ConversationIndexSchema.safeParse(raw);
+    if (!r.success)
+        throw new IndexError(file, explainIssues(r.error.issues).map((l) => `  - ${l}`).join('\n'));
+    return r.data;
+}
+/** 先写 .tmp 再 rename:进程半路死掉不会留下半份索引 */
+export async function writeIndex(ws, index) {
+    const { index: file } = conversationFiles(ws.dirs.conversations, index.tutor, index.date);
+    await mkdir(join(ws.dirs.conversations, index.tutor), { recursive: true });
+    const tmp = `${file}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(index, null, 2)}\n`);
+    await rename(tmp, file);
+}
+/** 有过对话的日期,新的在前 */
+export async function listDates(ws, tutor) {
+    try {
+        return (await readdir(join(ws.dirs.conversations, tutor)))
+            .filter((f) => /^\d{4}-\d{2}-\d{2}\.json$/.test(f))
+            .map((f) => f.slice(0, 10))
+            .filter((d) => DATE_RE.test(d))
+            .sort()
+            .reverse();
+    }
+    catch {
+        return [];
+    }
+}
+export async function readTranscript(ws, tutor, date, job) {
+    try {
+        return parseTranscript(await readFile(conversationFiles(ws.dirs.conversations, tutor, date).log(job), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 一天里卡的目录 <date>.<job>.cards/ 全扫一遍:<n>.json 是孩子做的事(坏文件跳过,孩子端不报),<n>/<k>.mp3 是后台生成好的资产。
+ */
+export async function scanCards(ws, tutor, date) {
+    const dir = join(ws.dirs.conversations, tutor);
+    const states = {};
+    const assets = {};
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return { states, assets };
+    }
+    for (const name of names) {
+        const m = new RegExp(`^${date}\\.(\\d{4}-\\d+)\\.cards$`).exec(name);
+        if (!m)
+            continue;
+        const job = m[1];
+        let files;
+        try {
+            files = await readdir(join(dir, name), { withFileTypes: true }).then((es) => es.map((e) => (e.isDirectory() ? `${e.name}/` : e.name)));
+        }
+        catch {
+            continue;
+        }
+        for (const f of files) {
+            const n = /^(\d+)\.json$/.exec(f);
+            if (n) {
+                try {
+                    const raw = JSON.parse(await readFile(join(dir, name, f), 'utf8'));
+                    if (raw && typeof raw.at === 'string' && typeof raw.turn === 'string' && 'state' in raw)
+                        (states[job] ??= {})[Number(n[1])] = raw;
+                }
+                catch {
+                    /* 坏文件:当没做过 */
+                }
+                continue;
+            }
+            const d = /^(\d+)\/$/.exec(f);
+            if (!d)
+                continue;
+            try {
+                const inner = (await readdir(join(dir, name, d[1]))).filter((x) => /^\d+\.mp3$/.test(x)).sort((a, b) => parseInt(a, 10) - parseInt(b, 10));
+                if (inner.length)
+                    (assets[job] ??= {})[Number(d[1])] = inner.map((x) => cardAssetName(date, job, Number(d[1]), x));
+            }
+            catch {
+                /* 目录没了:当没有 */
+            }
+        }
+    }
+    return { states, assets };
+}
+/** 只要孩子做的事(发消息时挑「上一轮之后改过的」) */
+export async function readCardStates(ws, tutor, date) {
+    return (await scanCards(ws, tutor, date)).states;
+}
+/** 存一张卡的状态(先 .tmp 再 rename);turn = 存的时候索引里最后一条的 job */
+export async function writeCardState(ws, tutor, date, job, n, file) {
+    const files = conversationFiles(ws.dirs.conversations, tutor, date);
+    await mkdir(files.cardsDir(job), { recursive: true });
+    const target = files.card(job, n);
+    await writeFile(`${target}.tmp`, `${JSON.stringify(file, null, 2)}\n`);
+    await rename(`${target}.tmp`, target);
+}
+/** 画板导出的 png:<date>.<job>.cards/<n>.png;返回相对 conversations/<老师>/ 的名字 */
+export async function writeCardImage(ws, tutor, date, job, n, png) {
+    const files = conversationFiles(ws.dirs.conversations, tutor, date);
+    await mkdir(files.cardsDir(job), { recursive: true });
+    const target = `${files.cardsDir(job)}/${n}.png`;
+    await writeFile(target, png);
+    return `${date}.${job}.cards/${n}.png`;
+}
+export async function readErrLog(ws, tutor, date, job) {
+    try {
+        return await readFile(conversationFiles(ws.dirs.conversations, tutor, date).err(job), 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+/** 老师文件正文(系统提示),给 {agentBody};从 .claude/agents/ 读,那里的链是必需项 */
+export async function readAgentBody(ws, name) {
+    for (const dir of [ws.dirs.claudeAgents, ws.dirs.qwenAgents]) {
+        try {
+            return parseAgentFile(await readFile(join(dir, `${name}.md`), 'utf8')).body;
+        }
+        catch {
+            /* 试下一处 */
+        }
+    }
+    throw new ConfigError(join(ws.dirs.claudeAgents, `${name}.md`), '老师文件读不到;cotutor init 补拷');
+}
+/** PATCH 允许改的顶层键(老师团页与设置页);kid / version / 运行时模板走编辑器 */
+export const CONFIG_PATCH_KEYS = ['title', 'policyDefaults', 'tutors', 'agents', 'paths', 'server', 'tts'];
+const isObj = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+/** 深合并:对象递归、其余覆盖、null 删键(老师条目可整体删:tutors.x = null) */
+export function deepMerge(base, patch) {
+    if (!isObj(base) || !isObj(patch))
+        return patch;
+    const out = { ...base };
+    for (const [k, v] of Object.entries(patch)) {
+        if (v === null)
+            delete out[k];
+        else
+            out[k] = deepMerge(out[k], v);
+    }
+    return out;
+}
+/**
+ * 补丁合到原始 JSON 上(保留 _note 等机器不认识的键),整份过契约再写;写坏了不落盘。
+ * 返回新配置;agents 只允许改 default(运行时模板走编辑器,页面上改错一个引号就把老师全弄哑)。
+ */
+export async function patchConfig(ws, patch) {
+    const unknown = Object.keys(patch).filter((k) => !CONFIG_PATCH_KEYS.includes(k));
+    if (unknown.length)
+        throw new ConfigError(ws.files.config, `页面只能改 ${CONFIG_PATCH_KEYS.join(' / ')},不认识:${unknown.join(', ')};其余字段请直接编辑文件`);
+    if (isObj(patch.agents) && Object.keys(patch.agents).some((k) => k !== 'default')) {
+        throw new ConfigError(ws.files.config, 'agents 只能在页面上改 default;运行时模板请直接编辑文件');
+    }
+    const raw = readJson(ws.files.config);
+    if (raw === null)
+        throw new ConfigError(ws.files.config, '不存在');
+    const merged = deepMerge(raw, patch);
+    const r = CotutorConfigSchema.safeParse(merged);
+    if (!r.success)
+        throw new ConfigError(ws.files.config, `补丁应用后不合契约,未写入:\n${explainIssues(r.error.issues).map((l) => `  - ${l}`).join('\n')}`);
+    const tmp = `${ws.files.config}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(merged, null, 2)}\n`);
+    await rename(tmp, ws.files.config);
+    return r.data;
+}
+/** 文件改了(页面写的、或家长在编辑器改的)就重读;坏了抛 ConfigError,调用方决定是留旧的还是响 */
+export async function reloadIfChanged(ws, lastMtime) {
+    const st = await stat(ws.files.config);
+    if (st.mtimeMs === lastMtime)
+        return { ws, mtime: lastMtime };
+    const raw = readJson(ws.files.config);
+    if (raw === null)
+        throw new ConfigError(ws.files.config, '不存在了');
+    return { ws: assembleWorkspace(ws.root, ws.source, parseConfig(raw, ws.files.config)), mtime: st.mtimeMs };
+}

package/dist/server/tts.d.ts

@@ -0,0 +1,51 @@
+import { type Tts } from '../schema/index.ts';
+export interface TtsResult {
+    /** 成功 → 输出文件路径;失败 → null */
+    file: string | null;
+    error: string | null;
+}
+export declare function synthesize(tts: Tts, vars: {
+    text: string;
+    voice: string;
+    out: string;
+}, opts?: {
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+}): Promise<TtsResult>;
+/** 合成一条并把失败原因追加到 err.log;返回文件名(相对 conversations/<老师>/)或 null */
+export declare function dubReply(tts: Tts, text: string, voice: string, files: {
+    audio: string;
+    err: string;
+}, env?: NodeJS.ProcessEnv): Promise<string | null>;
+/**
+ * 一轮的配音队列:讲稿句与点读段同一条队,三个并行,先进先出(讲稿句在流式时就进了,自然排在点读段前面)。
+ * 每个文件一项;失败写 err.log、结果 null。
+ */
+export declare class DubQueue {
+    private readonly queue;
+    private running;
+    private readonly tts;
+    private readonly voice;
+    private readonly err;
+    private readonly env?;
+    constructor(tts: Tts, voice: string, err: string, env?: NodeJS.ProcessEnv);
+    /** 合成 text 到 out;resolve 成文件名(最后一段)或 null;label 是 err.log 里的称呼 */
+    add(out: string, text: string, label: string): Promise<string | null>;
+    private pump;
+}
+/**
+ * 边讲边配:流式时讲稿每写完一句就交进来(add),整轮跑完 finish(最终句子)——同下标同文本的直接用,
+ * 不一样的(极少:末句被截、partial 与最终切句不同)重配到同一个文件。失败句 null。
+ */
+export declare class LineDubber {
+    private readonly jobs;
+    private readonly q;
+    private readonly lineAudio;
+    constructor(q: DubQueue, lineAudio: (n: number) => string);
+    /** 第 i 句(0 起)定稿了;同下标同文本不重配 */
+    add(i: number, text: string): void;
+    /** 最终讲稿:每句拿文件名(已配的直接用,没配的现配) */
+    finish(lines: readonly {
+        text: string;
+    }[]): Promise<(string | null)[]>;
+}

package/dist/server/tts.js

@@ -0,0 +1,99 @@
+/**
+ * 配音:老师说完,把 kidText 按 cotutor.json 的 tts 运行时合成到 conversations/<老师>/<日期>.<job>.mp3。
+ * 失败不响、不阻塞对话:这条没有音频,孩子端退回浏览器自带的声;原因写进 err.log 供家长看。
+ * 音色是人设(tutors[].voice),没配就不合成——「无缺省音色」是 voxtell 的政策,这里照办。
+ */
+import { execFile } from 'node:child_process';
+import { appendFile, stat } from 'node:fs/promises';
+import { fillTts } from "../schema/index.js";
+export function synthesize(tts, vars, opts = {}) {
+    const argv = fillTts(tts.say, vars);
+    return new Promise((resolveResult) => {
+        execFile(argv[0], argv.slice(1), { env: opts.env ?? process.env, timeout: opts.timeoutMs ?? 60_000, maxBuffer: 1 << 20 }, async (err, _stdout, stderr) => {
+            if (err) {
+                const code = err.code;
+                const why = code === 'ENOENT' ? `PATH 里没有 ${argv[0]}` : `${err.message}${stderr ? `\n${String(stderr).trim().slice(-500)}` : ''}`;
+                return resolveResult({ file: null, error: why });
+            }
+            const st = await stat(vars.out).catch(() => null);
+            if (!st?.isFile() || st.size === 0)
+                return resolveResult({ file: null, error: `命令跑完了但 ${vars.out} 没有内容` });
+            resolveResult({ file: vars.out, error: null });
+        });
+    });
+}
+/** 合成一条并把失败原因追加到 err.log;返回文件名(相对 conversations/<老师>/)或 null */
+export async function dubReply(tts, text, voice, files, env) {
+    const r = await synthesize(tts, { text, voice, out: files.audio }, { env });
+    if (r.error)
+        await appendFile(files.err, `cotutor tts: 没合成(${r.error});孩子端用浏览器的声\n`).catch(() => { });
+    return r.file ? files.audio.slice(files.audio.lastIndexOf('/') + 1) : null;
+}
+/**
+ * 一轮的配音队列:讲稿句与点读段同一条队,三个并行,先进先出(讲稿句在流式时就进了,自然排在点读段前面)。
+ * 每个文件一项;失败写 err.log、结果 null。
+ */
+export class DubQueue {
+    queue = [];
+    running = 0;
+    tts;
+    voice;
+    err;
+    env;
+    constructor(tts, voice, err, env) {
+        this.tts = tts;
+        this.voice = voice;
+        this.err = err;
+        this.env = env;
+    }
+    /** 合成 text 到 out;resolve 成文件名(最后一段)或 null;label 是 err.log 里的称呼 */
+    add(out, text, label) {
+        return new Promise((resolve) => {
+            this.queue.push(async () => {
+                const r = await synthesize(this.tts, { text, voice: this.voice, out }, { env: this.env });
+                if (r.error)
+                    await appendFile(this.err, `cotutor tts: ${label}没合成(${r.error});用浏览器的声\n`).catch(() => { });
+                resolve(r.error ? null : out.slice(out.lastIndexOf('/') + 1));
+            });
+            this.pump();
+        });
+    }
+    pump() {
+        while (this.running < 3 && this.queue.length) {
+            const job = this.queue.shift();
+            this.running++;
+            void job().finally(() => {
+                this.running--;
+                this.pump();
+            });
+        }
+    }
+}
+/**
+ * 边讲边配:流式时讲稿每写完一句就交进来(add),整轮跑完 finish(最终句子)——同下标同文本的直接用,
+ * 不一样的(极少:末句被截、partial 与最终切句不同)重配到同一个文件。失败句 null。
+ */
+export class LineDubber {
+    jobs = new Map();
+    q;
+    lineAudio;
+    constructor(q, lineAudio) {
+        this.q = q;
+        this.lineAudio = lineAudio;
+    }
+    /** 第 i 句(0 起)定稿了;同下标同文本不重配 */
+    add(i, text) {
+        const t = text.trim();
+        const had = this.jobs.get(i);
+        if (!t || (had && had.text === t))
+            return;
+        const after = had ? had.done.catch(() => null) : Promise.resolve(null);
+        const done = after.then(() => this.q.add(this.lineAudio(i + 1), t, `第 ${i + 1} 句`));
+        this.jobs.set(i, { text: t, done });
+    }
+    /** 最终讲稿:每句拿文件名(已配的直接用,没配的现配) */
+    async finish(lines) {
+        lines.forEach((l, i) => this.add(i, l.text));
+        return Promise.all(lines.map((l, i) => (l.text.trim() ? this.jobs.get(i).done : Promise.resolve(null))));
+    }
+}

package/dist/stage/index.html

@@ -0,0 +1,10 @@
+<!doctype html>
+<html lang="zh-CN">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1,user-scalable=no">
+<title>stage</title>
+<script>window.EXCALIDRAW_ASSET_PATH = '/stage/';</script>
+<link rel="stylesheet" href="/stage/stage.css">
+<div id="root"></div>
+<script type="module" src="/stage/stage.js"></script>
+</html>