dsh-her 0.0.1 → 0.1.0

package/lib/dsh/plugin.js

@@ -0,0 +1,1010 @@
+/**
+ * The DSH shell: opens her session as soon as DSH's agent services are ready,
+ * serves the body protocol, starts the body, and exposes `/her`. Everything
+ * hangs off `ctx.effect`, so disabling or uninstalling the plugin closes her
+ * session handle and the server (the body stays up and waits, asleep).
+ *
+ * Every reply of her session, whoever prompted it (the body's input box or
+ * microphone, the DSH page, `/her`), goes to connected bodies as `speak.*`
+ * sentences, each with its synthesized audio (or, without a voice, timed by
+ * reading speed). Replies are live only: a body that connects later never gets
+ * earlier ones replayed.
+ *
+ * Listening: a body sends what you said as audio; it is recognized here and
+ * goes to her like typed text. When a body cuts her off (you started talking),
+ * it reports how far she got; her next turn is told what you actually heard.
+ *
+ * Performing: the connected body's pack decides what she can do. Her prompt
+ * lists it; inline tags in her reply become cues on the sentence they are in,
+ * and longer performances go through her `play_action` tool, which waits for
+ * the body's `act.done`.
+ *
+ * Memory: files under `<home>/characters/<cid>/memory/` (src/memory). She
+ * writes with `remember`, reads with `recall`, and her prompt carries what she
+ * knows about you, her last diary days and what has a date today or tomorrow.
+ * A minute after each talk, a short note picks out of the new turns what is
+ * worth keeping (as candidates), so it shows on the "她记得的事" page at once.
+ * Once a day (30 minutes after you last talked, or from 23:30) a digest reads
+ * the day back from her session and writes her diary page and candidates.
+ *
+ * Her replies are also logged with timings to `<home>/logs/stream.jsonl`.
+ */
+import { spawn } from 'node:child_process';
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildSystemPrompt, extractCues, herPaths, invalidCharacter, judgeBargeIn, loadCharacter, memoryContext, performanceSection, readingMs, saveCharacter, serviceOf, speakable } from "../core/index.js";
+import { digestPrompt, notePrompt, parseDigest, transcriptOf } from "../memory/digest.js";
+import { dayOf, FileMemory } from "../memory/store.js";
+import { PROTOCOL_VERSION } from "../protocol/index.js";
+import { BrainServer } from "../server/brain-server.js";
+import { API_BASE, apiHandlers, handle } from "./api.js";
+import { bodyRunning, findDevBody, launchBody } from "./body-launcher.js";
+import { compareVersions, fetchManifest, install, installedBody, installedPlan } from "./body-install.js";
+import { IDLE_IMPORT } from "./import-status.js";
+import { DESK_DIR, newProject, sceneDir } from "../core/workshop.js";
+import { exampleFile, examples, exportProject, findProject, importProject, listProjects, prepareImport, projectStatus, saveProject } from "./workshop.js";
+import { HerSession } from "./her-session.js";
+import { heardText, SpeechQueue } from "../voice/speech-queue.js";
+import { Voice } from "../voice/voice.js";
+const SERVICES = ['agents', 'agentDefaultModel', 'workspaceRegistry', 'sessionTitle', 'sessionQuery', 'llm'];
+/** The digest runs this long after you last talked, or from DIGEST_HOUR:DIGEST_MINUTE. */
+const DIGEST_IDLE_MS = 30 * 60_000;
+const DIGEST_HOUR = 23;
+const DIGEST_MINUTE = 30;
+const DIGEST_CHECK_MS = 5 * 60_000;
+/** A note is taken once you have been quiet this long and her reply is over. */
+const NOTE_QUIET_MS = 60_000;
+const NOTE_CHECK_MS = 15_000;
+const STOP_WORDS = new Set(['停', '停下', 'stop']);
+const MEMORY_WORDS = new Set(['记忆', 'memory']);
+const INTERRUPT_CHECK = '测打断';
+const DIAGNOSE = '诊断';
+/** How long after DSH starts to wait for a running body before starting one. */
+const LAUNCH_AFTER_MS = 3000;
+/** The installed body checks the release for a newer version this soon after start, then this often. */
+const UPDATE_FIRST_MS = 60_000;
+const UPDATE_CHECK_MS = 6 * 60 * 60_000;
+/**
+ * A turn that has not started this long after you spoke is stuck. Seen in M4:
+ * an effort id the route does not accept (`off`) left her session silent with
+ * no error at all.
+ */
+const STUCK_AFTER_MS = 20_000;
+export function apply(ctx, config) {
+    const paths = herPaths(config.home);
+    const cid = config.character.id;
+    const dir = join(paths.characters, cid);
+    let services;
+    let session;
+    let server;
+    let sentAt;
+    let current;
+    const finished = [];
+    /** Resolves on the first sentence of the next reply. */
+    let onFirstSentence;
+    let voice;
+    let speech;
+    let nextStream = 1;
+    /** What you heard of her last cut-off reply; told to her before your next turn. */
+    let cutNote;
+    let stuckTimer;
+    const memory = new FileMemory(join(dir, 'memory'));
+    /** Who she is: the "她" page's saved settings over the plugin config's defaults. */
+    let character = loadCharacter(dir, {
+        name: config.character.name,
+        persona: config.character.persona,
+        callYou: '',
+        pronoun: '他',
+        voice: { id: config.voice.voice, speed: config.voice.speed },
+        onboarded: false,
+    });
+    /** When you last talked to her, and the day of it (for the digest). */
+    let lastTalkAt = 0;
+    let digesting;
+    /** Write her diary page for `day` and keep what is worth keeping; a short report. */
+    const digest = (day) => {
+        digesting ??= runDigest(day).finally(() => { digesting = undefined; });
+        return digesting;
+    };
+    /** One model call outside her session (digest, persona drafts): the whole answer as text. */
+    const complete = async (system, user, maxTokens) => {
+        const llm = services?.llm;
+        const target = route();
+        if (llm === undefined || target === undefined)
+            throw new Error('dsh 的模型服务还没准备好');
+        let answer = '';
+        for await (const chunk of llm.stream({
+            provider: target.provider, model: target.model, ...(target.reasoningEffort === undefined ? {} : { reasoningEffort: target.reasoningEffort }),
+            system, messages: [{ role: 'user', content: [{ type: 'text', text: user }] }], maxTokens,
+        })) {
+            if (chunk.type === 'text-delta' && typeof chunk.text === 'string')
+                answer += chunk.text;
+        }
+        return answer.trim();
+    };
+    const runDigest = async (day) => {
+        const id = session?.sessionId;
+        const query = services?.sessionQuery;
+        if (id === undefined || query === undefined)
+            return '整理不了：dsh 的服务还没准备好';
+        const [y, m, d] = day.split('-').map(Number);
+        const start = new Date(y, m - 1, d).getTime();
+        const lines = transcriptOf((await query.readSession(id)).events, start, start + 86_400_000);
+        if (lines.length === 0) {
+            memory.applyDigest(day, { diary: '', facts: [], episodes: [] }, new Date());
+            return `${day} 没有聊天，不用整理`;
+        }
+        const { facts, episodes } = memory.list();
+        const prompt = digestPrompt(character.name, day, lines, facts.map(f => f.text), episodes.map(e => (e.due === undefined ? e.text : `${e.text}（${e.due}）`)), character.pronoun);
+        const answer = await complete(prompt.system, prompt.user, 2000);
+        const parsed = parseDigest(answer);
+        if (parsed === undefined) {
+            log({ event: 'digest', day, error: 'unparsable', answer: answer.slice(0, 400) });
+            return `${day} 整理失败：模型没有给出能读懂的结果`;
+        }
+        const added = memory.applyDigest(day, parsed, new Date());
+        log({ event: 'digest', day, lines: lines.length, ...added });
+        return `${day} 整理好了：日记 1 篇，新的候选事实 ${added.facts} 条，事件 ${added.episodes} 条`;
+    };
+    /** Turns up to here have been noted (the daily digest still reads the whole day). */
+    let notedUntil = Date.now();
+    let noting;
+    /** Note what in the turns since the last note is worth keeping; never throws. */
+    const runNote = async () => {
+        const id = session?.sessionId;
+        const query = services?.sessionQuery;
+        if (id === undefined || query === undefined)
+            return;
+        const from = notedUntil;
+        const to = Date.now();
+        notedUntil = to;
+        const lines = transcriptOf((await query.readSession(id)).events, from, to);
+        if (!lines.some(l => l.who === 'you'))
+            return;
+        const now = new Date();
+        const { facts, episodes } = memory.list();
+        const prompt = notePrompt(character.name, dayOf(now), lines, facts.map(f => f.text), episodes.map(e => (e.due === undefined ? e.text : `${e.text}（${e.due}）`)), character.pronoun);
+        const parsed = parseDigest(await complete(prompt.system, prompt.user, 800));
+        if (parsed === undefined) {
+            log({ event: 'note', error: 'unparsable' });
+            return;
+        }
+        log({ event: 'note', lines: lines.length, ...memory.keep(parsed, now) });
+    };
+    const noteTick = () => {
+        if (noting !== undefined || current !== undefined || lastTalkAt <= notedUntil || Date.now() - lastTalkAt < NOTE_QUIET_MS)
+            return;
+        noting = runNote()
+            .catch((error) => ctx.logger.warn(`dsh-her: note failed (${error.message})`))
+            .finally(() => { noting = undefined; });
+    };
+    /** Every few minutes: settle old candidates, and digest a day that has ended its talking. */
+    const digestTick = () => {
+        const now = new Date();
+        memory.settle(now);
+        const done = memory.lastDigestDay();
+        if (lastTalkAt === 0) {
+            // DSH restarted since you last talked: catch up on yesterday, if it was never digested.
+            const yesterday = dayOf(new Date(now.getFullYear(), now.getMonth(), now.getDate() - 1));
+            if (done === undefined || done < yesterday)
+                void digest(yesterday).then(report => ctx.logger.info(`dsh-her: ${report}`), () => { });
+            return;
+        }
+        const talkedDay = dayOf(new Date(lastTalkAt));
+        if (done !== undefined && done >= talkedDay)
+            return;
+        const late = now.getHours() > DIGEST_HOUR || (now.getHours() === DIGEST_HOUR && now.getMinutes() >= DIGEST_MINUTE);
+        const quiet = now.getTime() - lastTalkAt >= DIGEST_IDLE_MS;
+        const nextDay = dayOf(now) !== talkedDay;
+        if (quiet || late || nextDay)
+            void digest(talkedDay).then(report => ctx.logger.info(`dsh-her: ${report}`), (error) => ctx.logger.warn(`dsh-her: digest failed (${error.message})`));
+    };
+    const aboutYou = () => {
+        const now = new Date();
+        return memoryContext({ profile: memory.profile(), recent: memory.recent(now), due: memory.due(now) });
+    };
+    /** The last barge-in, to check the utterance that follows it for echo. */
+    let lastCut;
+    /** The pack of the most recently connected body: what she can perform. */
+    let bodyPack;
+    /** What the body reports about itself, for the "她" page. */
+    let bodyPacks = [];
+    let activePack;
+    let bodyLook;
+    let bodyMode;
+    let importStatus = IDLE_IMPORT;
+    let lastHeard;
+    let discovery;
+    /** Actions sent to a body, waiting for its `act.done`. */
+    /** The installed body: download, check, install, update (body-install.ts). */
+    const devBody = () => (config.body.useDev ? findDevBody() : { missing: 'useDev is off' });
+    let installState = { state: 'idle', dev: !('missing' in devBody()) };
+    /** The body to start: the development one in the repository when there is one, else the installed app. */
+    const bodyPlan = () => {
+        const dev = devBody();
+        if (!('missing' in dev))
+            return dev;
+        return installedPlan(paths.root) ?? { missing: '还没有安装，在「她」页面点"下载安装身体"' };
+    };
+    /**
+     * Install the release's body when there is none, or a newer one (`asked`:
+     * the user pressed the button, so a first install starts the body too).
+     * A development setup never updates itself.
+     */
+    const installLatest = async (asked) => {
+        if (installState.dev && !asked)
+            return;
+        const before = installedBody(paths.root);
+        if (!asked && before === undefined)
+            return;
+        installState = { ...installState, state: 'checking' };
+        try {
+            const manifest = await fetchManifest(config.body.releases);
+            installState = { ...installState, latest: manifest.version };
+            if (before !== undefined && compareVersions(manifest.version, before.version) <= 0) {
+                installState = { ...installState, state: 'idle' };
+                return;
+            }
+            installState = { ...installState, state: 'downloading', done: 0, total: 0 };
+            const installed = await install(paths.root, config.body.releases, manifest, (done, total) => {
+                installState = { ...installState, state: done < total ? 'downloading' : 'installing', done, total };
+            });
+            installState = { ...installState, state: 'idle', installed: installed.version, restart: before !== undefined && (server?.bodies.length ?? 0) > 0 };
+            log({ event: 'body-installed', version: installed.version });
+            if (before === undefined && discovery !== undefined && (server?.bodies.length ?? 0) === 0 && !bodyRunning(paths.root)) {
+                const plan = bodyPlan();
+                if (!('missing' in plan))
+                    launchBody(plan, { url: discovery.url, token: discovery.token, home: paths.root, pack: config.body.pack });
+            }
+        }
+        catch (error) {
+            installState = { ...installState, state: 'failed', error: error.message };
+            ctx.logger.warn(`dsh-her: body install/update failed (${error.message})`);
+        }
+    };
+    /** Stop the running body (it writes its pid to body.json) and wait for it to go. */
+    const stopBody = async () => {
+        let pid;
+        try {
+            pid = JSON.parse(readFileSync(join(paths.root, 'body.json'), 'utf8')).pid;
+        }
+        catch {
+            return;
+        }
+        if (typeof pid !== 'number')
+            return;
+        try {
+            process.kill(pid);
+        }
+        catch {
+            return;
+        }
+        for (let i = 0; i < 50 && bodyRunning(paths.root); i++)
+            await new Promise(r => setTimeout(r, 100));
+    };
+    /** Folder dialogs open on the body, waiting for the user's choice. */
+    const folderPicks = new Map();
+    /** Ask the body to show a folder dialog; undefined when cancelled. */
+    const pickFolder = (title, button, file) => {
+        const body = server?.bodies.at(-1);
+        if (body === undefined)
+            return Promise.reject(new Error('身体还没连上：选文件夹的窗口要在身体那边弹出来'));
+        const id = `f${Date.now().toString(36)}`;
+        return new Promise(resolve => {
+            const timer = setTimeout(() => { folderPicks.delete(id); resolve(undefined); }, 10 * 60_000);
+            folderPicks.set(id, path => { clearTimeout(timer); resolve(path); });
+            body.send({ t: 'folder.pick', id, title, button, ...(file === undefined ? {} : { file }) });
+        });
+    };
+    /** Actions sent to a body and not done yet, with the body doing each. */
+    const pendingActs = new Map();
+    let nextAct = 1;
+    /** Have the body perform an action and wait (at most 90 s) for it to finish. */
+    const playAction = (action) => {
+        // The latest body that shows her (has packs), not a text-only client that connected after it.
+        const bodies = server?.bodies ?? [];
+        const body = [...bodies].reverse().find(b => b.hello.packs.length > 0) ?? bodies.at(-1);
+        log({ event: 'play-action', action, body: body?.id ?? null, packActions: bodyPack?.actions.map(a => a.id) ?? null });
+        if (body === undefined)
+            return Promise.resolve({ ok: false, reason: 'no body' });
+        const known = bodyPack?.actions.find(a => a.id === action);
+        if (known === undefined)
+            return Promise.resolve({ ok: false, reason: 'unsupported' });
+        const id = `a${nextAct++}`;
+        return new Promise(resolve => {
+            const timer = setTimeout(() => {
+                pendingActs.delete(id);
+                resolve({ ok: false, reason: 'timeout' });
+            }, 90_000);
+            pendingActs.set(id, {
+                body: body.id,
+                settle: result => {
+                    clearTimeout(timer);
+                    log({ event: 'act', action, ...result });
+                    resolve(known.transcript === undefined || !result.ok ? result : { ...result, transcript: known.transcript });
+                },
+            });
+            body.send({ t: 'act', cid, id, action });
+        });
+    };
+    const log = (entry) => {
+        try {
+            appendFileSync(join(paths.logs, 'stream.jsonl'), `${JSON.stringify({ at: new Date().toISOString(), cid, ...entry })}\n`);
+        }
+        catch (error) {
+            ctx.logger.warn(`dsh-her: stream log failed (${error.message})`);
+        }
+    };
+    const broadcast = (message) => server?.broadcast(message);
+    /** A reply with no words: record what the turn did instead (tool calls, reasoning only, errors). */
+    const logQuietTurn = async () => {
+        const id = session?.sessionId;
+        const query = services?.sessionQuery;
+        if (id === undefined || query === undefined)
+            return;
+        try {
+            const events = (await query.readSession(id)).events.slice(-12);
+            log({
+                event: 'quiet-turn',
+                events: events.map(e => {
+                    const data = e.data;
+                    if (e.type === 'tool/call')
+                        return `tool/call ${data.name} ${data.arguments ?? ''}`;
+                    if (e.type === 'assistant/message')
+                        return `assistant/message [${data.message?.content?.map(b => `${b.type}${b.text === undefined ? '' : `:${b.text.slice(0, 40)}`}`).join(', ') ?? ''}]`;
+                    if (e.type === 'turn/end')
+                        return `turn/end ${JSON.stringify(data.reason).slice(0, 120)}`;
+                    return e.type;
+                }),
+            });
+        }
+        catch (error) {
+            log({ event: 'quiet-turn', error: error.message });
+        }
+    };
+    /** Her model: the "她" page's choice, else the plugin config's, else DSH's default. */
+    const route = () => {
+        const chosen = character.model;
+        if (chosen !== undefined)
+            return { provider: chosen.provider, model: chosen.model, ...(chosen.effort ? { reasoningEffort: chosen.effort } : {}) };
+        const effort = config.reasoningEffort === '' ? {} : { reasoningEffort: config.reasoningEffort };
+        if (config.provider !== '' && config.model !== '')
+            return { provider: config.provider, model: config.model, ...effort };
+        const selected = services?.agentDefaultModel?.currentSelection();
+        return selected === undefined ? undefined : { provider: selected.provider, model: selected.model, ...effort };
+    };
+    const open = () => {
+        session?.ensure().catch(error => ctx.logger.warn(`dsh-her: her session not ready (${error.message})`));
+    };
+    /** Stop her current reply: generation, synthesis and every body's playback. */
+    const cut = () => {
+        if (current === undefined)
+            return;
+        session?.interrupt();
+        speech?.cancel(current.attemptId);
+        broadcast({ t: 'speak.cancel', cid, uid: current.attemptId });
+    };
+    /** You said something (typed or spoken): cut her off if she is talking, then pass it on. */
+    const hear = (text, via) => {
+        if (session === undefined)
+            return;
+        cut();
+        sentAt = Date.now();
+        lastTalkAt = sentAt;
+        broadcast({ t: 'state', cid, state: 'think' });
+        clearTimeout(stuckTimer);
+        stuckTimer = setTimeout(() => {
+            log({ event: 'stuck', text, waitedMs: STUCK_AFTER_MS });
+            void logQuietTurn();
+            broadcast({ t: 'state', cid, state: 'idle' });
+            broadcast({ t: 'bubble', cid, text: '（我好像卡住了，没能开始回答。看看 dsh 里她的会话和模型设置？）', ttlMs: 8000 });
+        }, STUCK_AFTER_MS);
+        stuckTimer.unref();
+        const her = session;
+        const note = cutNote;
+        cutNote = undefined;
+        (note === undefined ? Promise.resolve() : her.note(note))
+            .then(() => her.say(text, via))
+            .catch((error) => {
+            broadcast({ t: 'state', cid, state: 'idle' });
+            broadcast({ t: 'bubble', cid, text: `（我还没准备好：${error.message}）`, ttlMs: 6000 });
+        });
+    };
+    /** A body cut her off at `seq`, `playedMs` into it: remember what you heard and stop the rest. */
+    const interrupted = (uid, seq, playedMs) => {
+        const heard = heardText(speech?.sentOf(uid) ?? [], seq, playedMs);
+        cutNote = heard === ''
+            ? '（备注：你上一段话刚开口就被对方打断了，对方什么都没听到。）'
+            : `（备注：你上一段话只说到"${heard}"就被对方打断了，后面的部分对方没有听到。）`;
+        log({ event: 'interrupted', uid, seq, playedMs, heard });
+        lastCut = { uid, at: Date.now() };
+        if (current?.attemptId === uid)
+            session?.interrupt();
+        speech?.cancel(uid);
+    };
+    const onBodyMessage = (message, audio) => {
+        switch (message.t) {
+            case 'user.text': {
+                voice?.warm();
+                const text = message.text.trim();
+                if (text !== '')
+                    hear(text, 'text');
+                break;
+            }
+            case 'user.utterance': {
+                voice?.warm();
+                if (message.text !== undefined) {
+                    broadcast({ t: 'heard', cid, uttId: message.uttId, text: message.text });
+                    if (message.text.trim() !== '')
+                        hear(message.text.trim(), 'voice');
+                    break;
+                }
+                if (audio === undefined || voice === undefined)
+                    break;
+                const rate = Number(/@(\d+)k/.exec(message.format)?.[1] ?? 16) * 1000;
+                const endedAt = Date.now();
+                voice.recognize(audio, rate).then(({ text, ms }) => {
+                    // Right after a barge-in: was it you, or her own voice through the speakers?
+                    const barge = lastCut !== undefined && endedAt - lastCut.at < 10_000 ? lastCut : undefined;
+                    lastCut = undefined;
+                    const verdict = barge === undefined ? 'you' : judgeBargeIn(text, (speech?.sentOf(barge.uid) ?? []).map(s => s.text).join(''));
+                    log({ event: 'heard', uttId: message.uttId, text, asrMs: ms, audioMs: message.durationMs, verdict });
+                    if (verdict !== 'you') {
+                        cutNote = undefined;
+                        broadcast({ t: 'heard', cid, uttId: message.uttId, text: '', ignored: verdict });
+                        return;
+                    }
+                    broadcast({ t: 'heard', cid, uttId: message.uttId, text });
+                    lastHeard = { text, at: Date.now() };
+                    if (text !== '')
+                        hear(text, 'voice');
+                    sentAt = endedAt;
+                }, (error) => {
+                    broadcast({ t: 'heard', cid, uttId: message.uttId, text: '' });
+                    broadcast({ t: 'bubble', cid, text: `（我没听清：${error.message}）`, ttlMs: 5000 });
+                });
+                break;
+            }
+            case 'interrupt':
+                interrupted(message.uid, message.seq, message.playedMs);
+                break;
+            case 'act.done': {
+                const settle = pendingActs.get(message.id)?.settle;
+                pendingActs.delete(message.id);
+                settle?.({ ok: message.ok, ...(message.reason === undefined ? {} : { reason: message.reason }) });
+                break;
+            }
+            case 'pack.list':
+                bodyPacks = message.packs;
+                activePack = message.active;
+                bodyPack = message.packs.find(p => p.packId === message.active) ?? bodyPack;
+                break;
+            case 'mode.changed':
+                bodyMode = message.mode;
+                break;
+            case 'folder.picked':
+                folderPicks.get(message.id)?.(message.path);
+                folderPicks.delete(message.id);
+                break;
+            case 'look.state':
+                bodyLook = message.look ?? undefined;
+                break;
+            case 'pack.progress':
+                importStatus = { ...importStatus, state: 'running', done: message.done, total: message.total, step: message.step };
+                break;
+            case 'pack.report':
+                importStatus = { ...importStatus, state: message.ok ? 'done' : 'failed', lines: message.lines };
+                break;
+            case 'panel.get':
+                broadcast(panel());
+                break;
+            case 'panel.set': {
+                let error;
+                try {
+                    if (message.character !== undefined)
+                        api.saveCharacter(message.character);
+                    if (message.forget !== undefined)
+                        api.memoryRemove(message.forget);
+                    if (message.confirm !== undefined)
+                        api.memoryConfirm(message.confirm);
+                }
+                catch (failure) {
+                    error = failure.message;
+                }
+                broadcast(panel(error));
+                break;
+            }
+        }
+    };
+    /** The body's main screen in device pixels, for photo sizes in the prompts. */
+    const mainScreen = () => {
+        const first = server?.bodies.at(-1)?.hello.caps.screens[0];
+        return first === undefined ? undefined : { width: Math.round(first.w * first.scale), height: Math.round(first.h * first.scale) };
+    };
+    /** Who she is and what she remembers, for the body's settings window. */
+    const panel = (error) => {
+        const { facts, episodes, diary } = memory.list();
+        const { name, persona, callYou, pronoun } = character;
+        return { t: 'panel', cid, character: { name, persona, callYou, pronoun }, memory: { facts, episodes, diary }, ...(error === undefined ? {} : { error }) };
+    };
+    /** The "她" page's view of everything, and what it can change. */
+    const api = {
+        state: () => {
+            const body = server?.bodies.at(-1);
+            const target = route();
+            const { facts, episodes, diary } = memory.list();
+            return {
+                platform: process.platform,
+                character,
+                model: target === undefined ? null : { provider: target.provider, model: target.model, ...(target.reasoningEffort === undefined ? {} : { effort: target.reasoningEffort }), chosen: character.model !== undefined },
+                voice: { status: voice?.status ?? 'off', speaking: voice?.speaking ?? { status: 'off', service: serviceOf(character.voice.id) }, id: character.voice.id, speed: character.voice.speed },
+                body: {
+                    connected: body !== undefined,
+                    running: body !== undefined || bodyRunning(paths.root),
+                    canStart: !('missing' in bodyPlan()),
+                    install: { ...installState, ...(installedBody(paths.root) === undefined ? {} : { installed: installedBody(paths.root).version }) },
+                    ...(body === undefined ? {} : { info: { kind: body.hello.body.kind, version: body.hello.body.version, os: body.hello.body.os } }),
+                    ...(bodyPack === undefined ? {} : { pack: bodyPack }),
+                    packs: bodyPacks,
+                    ...(activePack === undefined ? {} : { activePack }),
+                    ...(bodyMode === undefined ? {} : { mode: bodyMode }),
+                    ...(bodyLook === undefined ? {} : { look: bodyLook }),
+                    ...(body === undefined ? {} : { screens: body.hello.caps.screens.map(({ w, h, scale }) => ({ w, h, scale })) }),
+                },
+                import: importStatus,
+                ...(lastHeard === undefined ? {} : { heard: lastHeard }),
+                memory: { facts, episodes, diary, lastDigestDay: memory.lastDigestDay() ?? null },
+            };
+        },
+        saveCharacter: patch => {
+            const next = { ...character, ...patch, voice: { ...character.voice, ...patch.voice } };
+            if ('model' in patch && patch.model === undefined)
+                delete next.model;
+            const problem = invalidCharacter(next);
+            if (problem !== undefined)
+                throw new Error(problem);
+            const modelChanged = JSON.stringify(next.model) !== JSON.stringify(character.model);
+            saveCharacter(dir, next);
+            character = next;
+            if (modelChanged) {
+                // The model is fixed when her session is opened: reopen it on the new one (her history stays).
+                cut();
+                void session?.dispose().then(open);
+                log({ event: 'model', ...(route() ?? {}) });
+            }
+            voice?.setVoice(next.voice.id, next.voice.speed);
+            log({ event: 'character', name: next.name, voice: next.voice.id, onboarded: next.onboarded });
+            return next;
+        },
+        expandPersona: async ({ name, idea, callYou, pronoun }) => complete([
+            '你在帮用户写一个桌面陪伴角色的人设。她住在用户电脑桌面上，陪用户聊天，会记得用户说过的事。',
+            '根据用户的一句话描述，写成完整人设：150 到 300 字，用第二人称"你是……"开头。',
+            '写清楚：年龄感和性格、说话方式（口头禅、语气）、自己的喜好和小习惯、和对方的关系。',
+            `对方的称呼是"${callYou || '对方'}"，提到对方时用"${pronoun}"。`,
+            '不要写她能做什么、不能做什么（这部分另有规定）；不要成人内容；只输出人设正文。',
+        ].join('\n'), `名字：${name}\n用户的描述：${idea}`, 800),
+        tryPersona: async ({ name, persona, callYou, pronoun, history, message }) => complete(buildSystemPrompt({ name, persona, you: { call: callYou, pronoun }, now: new Date() }), [...history.map(h => `${h.who === 'you' ? '对方' : '你'}：${h.text}`), `对方：${message}`, '（只回复你接下来说的话，不要带"你："前缀。）'].join('\n'), 300),
+        previewVoice: async (id, speed, text) => {
+            if (voice === undefined)
+                throw new Error('她的声音还没准备好');
+            const audio = await voice.preview(text, id, speed);
+            return { audio: Buffer.from(audio.audio).toString('base64'), format: audio.format, durationMs: audio.durationMs };
+        },
+        startBody: () => {
+            if (server?.bodies.length)
+                return '身体已经连上了';
+            if (bodyRunning(paths.root))
+                return '身体已经在运行，正在连接';
+            const plan = bodyPlan();
+            if ('missing' in plan)
+                return `找不到身体程序：${plan.missing}`;
+            if (discovery === undefined)
+                return '大脑还没准备好';
+            launchBody(plan, { url: discovery.url, token: discovery.token, home: paths.root, pack: config.body.pack });
+            return '已经启动，几秒钟后会连上';
+        },
+        installBody: () => {
+            if (installState.state === 'downloading' || installState.state === 'installing' || installState.state === 'checking')
+                return;
+            void installLatest(true);
+        },
+        restartBody: async () => {
+            if (discovery === undefined)
+                throw new Error('大脑还没准备好');
+            await stopBody();
+            const plan = bodyPlan();
+            if ('missing' in plan)
+                throw new Error(`找不到身体程序：${plan.missing}`);
+            launchBody(plan, { url: discovery.url, token: discovery.token, home: paths.root, pack: config.body.pack });
+            installState = { ...installState, restart: false };
+        },
+        setMode: mode => broadcast({ t: 'mode', cid, mode }),
+        pickPack: () => {
+            const body = server?.bodies.at(-1);
+            if (body === undefined)
+                throw new Error('身体还没连上，导入素材要在身体所在的电脑上选文件夹');
+            importStatus = { ...IDLE_IMPORT, state: 'picking' };
+            body.send({ t: 'pack.pick', id: `i${Date.now()}` });
+        },
+        usePack: packId => {
+            if (!bodyPacks.some(p => p.packId === packId))
+                throw new Error('没有这个外形包');
+            broadcast({ t: 'pack.use', packId });
+        },
+        workshopList: () => listProjects(),
+        workshopNew: name => {
+            if (name === '')
+                throw new Error('先给形象起个名字');
+            return saveProject(newProject(`p${Date.now().toString(36)}`, name), mainScreen());
+        },
+        workshopSave: project => saveProject(project, mainScreen()),
+        workshopExport: async (id, media) => {
+            const dest = await pickFolder('导出到哪个文件夹', '导出到这里');
+            return dest === undefined ? undefined : exportProject(id, dest, media);
+        },
+        workshopImportProject: async () => {
+            const path = await pickFolder('选一个形象项目（文件夹，或里面的 形象.json）', '导入', '形象.json');
+            return path === undefined ? undefined : importProject(path, mainScreen());
+        },
+        workshopExamples: () => examples(paths.root),
+        workshopOpen: id => {
+            const found = findProject(id);
+            if (found === undefined)
+                throw new Error('找不到这个项目');
+            const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'explorer' : 'xdg-open';
+            spawn(opener, [found.dir], { detached: true, stdio: 'ignore' }).unref();
+        },
+        workshopFrame: (id, sceneId) => {
+            const found = findProject(id);
+            const scene = found?.project.scenes.find(s => s.id === sceneId);
+            if (found === undefined || scene === undefined)
+                throw new Error('找不到这个场景');
+            const body = server?.bodies.at(-1);
+            if (body === undefined)
+                throw new Error('身体还没连上：框人物区要在身体那边的窗口里做');
+            body.send({ t: 'scene.frame', dir: join(found.dir, sceneDir(scene)), name: scene.name });
+        },
+        workshopImport: id => {
+            const found = findProject(id);
+            if (found === undefined)
+                throw new Error('找不到这个项目');
+            const body = server?.bodies.at(-1);
+            if (body === undefined)
+                throw new Error('身体还没连上，导入要在身体所在的电脑上做');
+            const status = projectStatus(found.project, found.dir);
+            if (!status.importable)
+                throw new Error('还没有可以导入的部分：至少要有参考图和桌宠的 3 段，或者一个框好人物区的场景和它的 3 段');
+            prepareImport(found.project, found.dir);
+            const ready = (folder) => status.parts.find(p => p.folder === folder)?.enough === true;
+            const { project } = found;
+            importStatus = { ...IDLE_IMPORT, state: 'running' };
+            body.send({
+                t: 'look.import', id: project.id, name: project.name, dir: found.dir,
+                ...(project.desk.on && ready(DESK_DIR) ? { desk: DESK_DIR } : {}),
+                ...(project.default === undefined ? {} : { default: project.default }),
+                scenes: project.scenes.filter(s => ready(sceneDir(s)) && status.parts.find(p => p.folder === sceneDir(s))?.framed === true).map(s => ({
+                    id: s.id, name: s.name, folder: sceneDir(s),
+                    ...(s.hours !== undefined || s.user !== undefined ? { when: { ...(s.hours === undefined ? {} : { hours: s.hours }), ...(s.user === undefined ? {} : { user: s.user }) } } : {}),
+                })),
+            });
+        },
+        setLook: change => {
+            if (bodyLook === undefined)
+                throw new Error('现在用的不是多场景的形象');
+            if (change.go !== undefined && !bodyLook.scenes.some(s => s.id === change.go))
+                throw new Error('没有这个场景');
+            broadcast({ t: 'look.set', ...change });
+        },
+        memoryRemove: ids => memory.remove(ids),
+        memoryConfirm: ids => memory.confirm(ids),
+        digest: () => digest(dayOf(new Date())),
+        exportMemory: () => memory.exportMarkdown(),
+    };
+    ctx.effect(() => {
+        mkdirSync(dir, { recursive: true });
+        mkdirSync(paths.logs, { recursive: true });
+        session = new HerSession({
+            cid,
+            character: () => character,
+            performance: () => performanceSection(bodyPack),
+            playAction,
+            aboutYou,
+            memory,
+            dir,
+            get route() { return route(); },
+            services: () => services,
+            logger: ctx.logger,
+            events: {
+                start(attemptId) {
+                    clearTimeout(stuckTimer);
+                    current = { attemptId, startedAt: Date.now(), sentences: [] };
+                    log({ event: 'start', attemptId, sinceSendMs: sentAt === undefined ? null : current.startedAt - sentAt });
+                    broadcast({ t: 'speak.begin', cid, uid: attemptId });
+                },
+                sentence(attemptId, text) {
+                    const now = Date.now();
+                    let seq = 0;
+                    if (current?.attemptId === attemptId) {
+                        current.firstSentenceAt ??= now;
+                        current.sentences.push(text);
+                        seq = current.sentences.length - 1;
+                    }
+                    onFirstSentence?.();
+                    onFirstSentence = undefined;
+                    log({ event: 'sentence', attemptId, text, sinceSendMs: sentAt === undefined ? null : now - sentAt });
+                    const performed = extractCues(text, bodyPack);
+                    if (performed.text !== '' || performed.cues.length > 0)
+                        speech?.say(attemptId, seq, performed.text, performed.cues);
+                },
+                end(attemptId, outcome) {
+                    log({ event: 'end', attemptId, outcome, sinceSendMs: sentAt === undefined ? null : Date.now() - sentAt });
+                    if (current?.attemptId === attemptId) {
+                        current.outcome = outcome;
+                        if (current.sentences.length === 0 && outcome !== 'committed') {
+                            broadcast({ t: 'bubble', cid, text: '（我刚才没说出话来，模型可能出错了）', ttlMs: 6000 });
+                        }
+                        if (current.sentences.length === 0)
+                            void logQuietTurn();
+                        finished.push(current);
+                        if (finished.length > 20)
+                            finished.shift();
+                    }
+                    speech?.end(attemptId);
+                    current = undefined;
+                },
+            },
+        });
+        if (services !== undefined)
+            open();
+        voice = new Voice(paths.models, join(paths.root, 'edge-tts'), { ...config.voice, voice: character.voice.id, speed: character.voice.speed }, ctx.logger);
+        const herVoice = voice;
+        void herVoice.start();
+        speech = new SpeechQueue(text => herVoice.synthesize(speakable(text)), {
+            sentence(uid, seq, text, audio, cues) {
+                const withCues = cues.length === 0 ? {} : { cues };
+                if (audio === undefined) {
+                    broadcast({ t: 'speak.seg', cid, uid, seq, text, durationMs: text === '' ? 300 : readingMs(text), ...withCues });
+                    return;
+                }
+                const stream = nextStream++;
+                if (seq === 0)
+                    log({ event: 'first-audio', uid, sinceSendMs: sentAt === undefined ? null : Date.now() - sentAt, durationMs: audio.durationMs });
+                server?.broadcastWithAudio({ t: 'speak.seg', cid, uid, seq, text, durationMs: audio.durationMs, format: audio.format, stream, ...withCues }, stream, audio.audio);
+            },
+            end(uid) {
+                broadcast({ t: 'speak.end', cid, uid });
+            },
+        });
+        const brain = new BrainServer({
+            tokenFile: join(paths.root, 'token'),
+            discoveryFile: paths.discovery,
+            preferredPort: config.port,
+            logger: ctx.logger,
+            welcome: client => {
+                bodyPack = client.hello.packs[0] ?? bodyPack;
+                return {
+                    t: 'welcome',
+                    v: PROTOCOL_VERSION,
+                    sessionId: session?.sessionId ?? '',
+                    characters: [{ cid, name: character.name, mode: 'overlay' }],
+                    config: { mic: config.voice.mic, bargeIn: true },
+                };
+            },
+            message: (_client, message, audio) => onBodyMessage(message, audio),
+            closed: client => {
+                bodyPack = server?.bodies.at(-1)?.hello.packs[0];
+                // Only what that body was doing is lost; another body (or a text-only client) leaving changes nothing.
+                for (const [id, pending] of pendingActs) {
+                    if (pending.body !== client.id)
+                        continue;
+                    pendingActs.delete(id);
+                    pending.settle({ ok: false, reason: 'no body' });
+                }
+            },
+        });
+        let launchTimer;
+        brain.start().then(started => {
+            server = brain;
+            discovery = started;
+            if (config.body.launch !== 'auto')
+                return;
+            launchTimer = setTimeout(() => {
+                if (brain.bodies.length > 0 || bodyRunning(paths.root))
+                    return;
+                const plan = bodyPlan();
+                if ('missing' in plan) {
+                    ctx.logger.info(`dsh-her: no body to start yet (${plan.missing}); the "她" page offers to install it`);
+                    return;
+                }
+                const pid = launchBody(plan, { url: started.url, token: started.token, home: paths.root, pack: config.body.pack });
+                ctx.logger.info(`dsh-her: started the body (pid ${pid})`);
+            }, LAUNCH_AFTER_MS);
+            launchTimer.unref();
+        }, (error) => ctx.logger.warn(`dsh-her: body server failed to start (${error.message})`));
+        // The installed body keeps itself up to date: a check soon after start, then every few hours.
+        const updateFirst = setTimeout(() => void installLatest(false), UPDATE_FIRST_MS);
+        const updateTimer = setInterval(() => void installLatest(false), UPDATE_CHECK_MS);
+        updateFirst.unref();
+        updateTimer.unref();
+        const digestTimer = setInterval(digestTick, DIGEST_CHECK_MS);
+        const noteTimer = setInterval(noteTick, NOTE_CHECK_MS);
+        noteTimer.unref();
+        digestTimer.unref();
+        return async () => {
+            clearTimeout(launchTimer);
+            clearTimeout(updateFirst);
+            clearInterval(updateTimer);
+            clearInterval(digestTimer);
+            clearInterval(noteTimer);
+            clearTimeout(stuckTimer);
+            herVoice.stop();
+            voice = undefined;
+            speech = undefined;
+            const closing = session;
+            session = undefined;
+            server = undefined;
+            closing?.interrupt();
+            await Promise.all([closing?.dispose(), brain.stop()]);
+        };
+    });
+    // The "她" page's API, on DSH's own authenticated `/api` channel.
+    ctx.inject(['connection'], (webCtx) => {
+        const connection = webCtx.connection;
+        for (const [path, handler] of Object.entries(apiHandlers(api))) {
+            webCtx.effect(() => connection.fetch.register({ path: `${API_BASE}${path}`, methods: ['POST'], requestBody: 'buffered', fetch: request => handle(handler, request) }));
+        }
+        // 形象工坊's example pictures and clips, as files (`?f=reference.png`); only the named slots.
+        webCtx.effect(() => connection.fetch.register({
+            path: `${API_BASE}/example`, methods: ['GET'], requestBody: 'buffered',
+            fetch: async (request) => {
+                const file = exampleFile(paths.root, new URL(request.url).searchParams.get('f') ?? '');
+                if (file === undefined)
+                    return new Response('not found', { status: 404 });
+                const type = file.endsWith('.mp4') ? 'video/mp4' : file.endsWith('.png') ? 'image/png' : 'application/octet-stream';
+                return new Response(readFileSync(file), { headers: { 'content-type': type, 'cache-control': 'no-cache' } });
+            },
+        }));
+    });
+    ctx.inject([...SERVICES], (serviceCtx) => {
+        serviceCtx.effect(() => {
+            services = serviceCtx;
+            open();
+            return () => { services = undefined; };
+        });
+    });
+    /**
+     * M0 spike: send a prompt, interrupt right after her first sentence, then
+     * read her session back and report what DSH recorded for the cut reply.
+     */
+    const checkInterrupt = async (her, prompt) => {
+        const query = services?.sessionQuery;
+        const id = her.sessionId;
+        const before = query === undefined || id === undefined ? -1 : Math.max(-1, ...(await query.readSession(id)).events.map(e => e.seq));
+        const first = new Promise(resolve => { onFirstSentence = resolve; });
+        sentAt = Date.now();
+        const agent = await her.say(prompt, 'command');
+        const timeout = new Promise(resolve => setTimeout(() => resolve('timeout'), 60_000).unref());
+        if (await Promise.race([first, timeout]) === 'timeout')
+            return { kind: 'error', text: '60 秒内没有等到第一句' };
+        const cutAt = Date.now();
+        her.interrupt();
+        await agent.whenIdle();
+        const idleMs = Date.now() - cutAt;
+        const events = query === undefined || her.sessionId === undefined ? [] : (await query.readSession(her.sessionId)).events.filter(e => e.seq > before);
+        const message = events.filter(e => e.type === 'assistant/message').at(-1)?.data;
+        const kept = message?.message?.content?.filter(b => b.type === 'text').map(b => b.text ?? '').join('') ?? '';
+        const end = events.filter(e => e.type === 'turn/end').at(-1)?.data;
+        log({ event: 'interrupt-check', idleMs, turnEnd: end?.reason?.kind ?? null, interrupted: message?.interrupted ?? null, kept, usage: message?.usage ?? null, eventTypes: events.map(e => e.type) });
+        return {
+            kind: 'success',
+            text: [
+                `第一句后 ${idleMs} ms 停稳`,
+                `turn/end：${end?.reason?.kind ?? '（无）'}`,
+                `assistant/message.interrupted：${message?.interrupted === true ? 'true' : String(message?.interrupted)}`,
+                `DSH 记下的前半段（${[...kept].length} 字）：${kept.slice(0, 120)}${[...kept].length > 120 ? '…' : ''}`,
+            ].join('\n'),
+        };
+    };
+    /** M0 spike: what her last model request carried (tools, system prompt) and what it cost. */
+    const diagnose = async (her) => {
+        const query = services?.sessionQuery;
+        const id = her.sessionId;
+        if (query === undefined || id === undefined)
+            return { kind: 'error', text: '会话还没建好' };
+        const events = (await query.readSession(id)).events;
+        const header = events.filter(e => e.type === 'request/header').at(-1)?.data;
+        const usage = events.filter(e => e.type === 'assistant/message' && e.data.usage !== undefined).at(-1)?.data;
+        const system = events.filter(e => e.type === 'system/message').at(-1)?.data;
+        const result = {
+            headerKeys: header === undefined ? null : Object.keys(header),
+            systemChars: system === undefined ? null : JSON.stringify(system.message).length,
+            usage: usage?.usage ?? null,
+            bodies: server?.bodies.map(b => `${b.hello.body.kind} ${b.hello.body.version} ${b.hello.body.os}`) ?? [],
+            voice: voice?.status ?? null,
+            server: server?.url ?? null,
+        };
+        log({ event: 'diagnose', ...result });
+        return { kind: 'success', text: JSON.stringify(result, null, 2) };
+    };
+    /**
+     * `/her 记忆`: what she remembers, with ids. `/her 确认 f3 f4`, `/her 忘掉 f3 e2`,
+     * `/her 整理` (digest today now), `/her 导出记忆` (a Markdown file).
+     */
+    const memoryCommand = (text) => {
+        const [word = '', ...rest] = text.split(/\s+/);
+        const ids = rest.map(id => id.replace(/^#/, '')).filter(Boolean);
+        if (MEMORY_WORDS.has(word)) {
+            const { facts, episodes, diary } = memory.list();
+            const lines = [
+                `关于你（${facts.length}）：`,
+                ...facts.map(f => `  ${f.id} ${f.text}${f.status === 'candidate' ? '（待确认）' : ''}${f.sensitive ? '（敏感）' : ''}`),
+                `事件（${episodes.length}）：`,
+                ...episodes.map(e => `  ${e.id} ${e.at.slice(0, 10)} ${e.text}${e.due === undefined ? '' : `（${e.due}）`}`),
+                `日记：${diary.length === 0 ? '还没有' : diary.join('、')}`,
+                `文件在 ${join(dir, 'memory')}`,
+                '确认：/her 确认 f3 ｜ 删除：/her 忘掉 f3 e2 ｜ 现在整理今天：/her 整理 ｜ 导出：/her 导出记忆',
+            ];
+            return Promise.resolve({ kind: 'success', text: lines.join('\n') });
+        }
+        if (word === '确认')
+            return Promise.resolve({ kind: 'success', text: `确认了 ${memory.confirm(ids)} 条。` });
+        if (word === '忘掉' || word === 'forget') {
+            if (ids.length === 0)
+                return Promise.resolve({ kind: 'error', text: '用法：/her 忘掉 f3 e2（编号见 /her 记忆）' });
+            return Promise.resolve({ kind: 'success', text: `删掉了 ${memory.remove(ids)} 条。` });
+        }
+        if (word === '整理')
+            return digest(dayOf(new Date())).then(report => ({ kind: 'success', text: report }));
+        if (word === '导出记忆') {
+            const file = join(dir, 'memory', `她记得的事-${dayOf(new Date())}.md`);
+            writeFileSync(file, memory.exportMarkdown());
+            return Promise.resolve({ kind: 'success', text: `导出到 ${file}` });
+        }
+        return undefined;
+    };
+    ctx.inject(['commands'], (commandCtx) => {
+        const commands = commandCtx.commands;
+        commandCtx.effect(() => commands.register({
+            name: 'her',
+            description: 'dsh-her: talk to her (`/her 你好`), stop her (`/her 停`), or show her session',
+            input: { hint: '[想对她说的话 | 停]' },
+            async handler(invocation) {
+                if (session === undefined)
+                    return { kind: 'error', text: 'dsh-her：还没有启动' };
+                const text = invocation.rawInput.trim();
+                if (text === '') {
+                    const id = session.sessionId;
+                    const bodies = server?.bodies.length ?? 0;
+                    return {
+                        kind: 'success',
+                        text: `${session.title}\n会话：${id ?? '还没建好'}\n身体：${bodies} 个已连接（${server?.url ?? '服务未启动'}）\n日志：${join(paths.logs, 'stream.jsonl')}`,
+                    };
+                }
+                if (STOP_WORDS.has(text.toLowerCase())) {
+                    cut();
+                    return { kind: 'success', text: '已让她停下。' };
+                }
+                if (text.startsWith(INTERRUPT_CHECK))
+                    return checkInterrupt(session, text.slice(INTERRUPT_CHECK.length).trim() || '给我讲一个很长很长的睡前故事，至少讲十句。');
+                if (text === DIAGNOSE)
+                    return diagnose(session);
+                const memoryReply = memoryCommand(text);
+                if (memoryReply !== undefined)
+                    return memoryReply;
+                sentAt = Date.now();
+                broadcast({ t: 'state', cid, state: 'think' });
+                const before = finished.length;
+                const agent = await session.say(text, 'command');
+                await agent.whenIdle();
+                const reply = finished.slice(before).at(-1);
+                if (reply === undefined)
+                    return { kind: 'error', text: '她没有回复（看 DSH 日志里的模型错误）' };
+                const firstMs = reply.firstSentenceAt === undefined ? '—' : `${reply.firstSentenceAt - sentAt} ms`;
+                return {
+                    kind: 'success',
+                    text: `${reply.sentences.map((s, i) => `${i + 1}. ${s}`).join('\n')}\n\n（开始生成 ${reply.startedAt - sentAt} ms · 第一句 ${firstMs} · ${reply.outcome}）`,
+                };
+            },
+        }));
+    });
+}