dsh-her 0.0.1 → 0.1.0

package/lib/protocol/index.js

@@ -0,0 +1,39 @@
+/**
+ * Body protocol v1: the messages between the brain (this plugin) and a body
+ * (the Electron desktop app, later Unity or a phone). Design: docs/身体协议.md.
+ *
+ * Text frames carry one JSON message each. Binary frames carry audio: a 4-byte
+ * big-endian header holding the stream id, then the payload. The audio frame
+ * is sent first, then the `speak.seg` or `user.utterance` naming its stream.
+ *
+ * This file has no runtime dependencies so the body can import the same source.
+ */
+export const PROTOCOL_VERSION = 1;
+/** Parse one text frame. Unknown `t` values pass through so newer peers degrade instead of failing. */
+export function parseMessage(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const t = value.t;
+    return typeof t === 'string' && t !== '' ? value : undefined;
+}
+/** Prefix an audio payload with its stream id. */
+export function encodeAudioFrame(stream, payload) {
+    const frame = new Uint8Array(4 + payload.byteLength);
+    new DataView(frame.buffer).setUint32(0, stream >>> 0);
+    frame.set(payload, 4);
+    return frame;
+}
+/** Split a binary frame into its stream id and payload; undefined when it is too short. */
+export function decodeAudioFrame(frame) {
+    if (frame.byteLength < 4)
+        return undefined;
+    const stream = new DataView(frame.buffer, frame.byteOffset, 4).getUint32(0);
+    return { stream, payload: frame.subarray(4) };
+}

package/lib/server/brain-server.js

@@ -0,0 +1,219 @@
+/**
+ * The brain's side of the body protocol: a WebSocket server on loopback.
+ * Design: docs/身体协议.md §2–3.
+ *
+ * - Port: the preferred one, else the next free ones, else any free port.
+ * - Token: created once and kept in `<home>/token` (mode 600); a body proves
+ *   itself with it in `hello`, never in the URL.
+ * - Discovery: `<home>/brain.json` (mode 600) says where the brain listens and
+ *   carries the token, so a body started by hand can find it; it is rewritten
+ *   on every start because the port may change, and removed on stop.
+ * - Heartbeat: a body pings every 15 s; one silent for 45 s is dropped.
+ * - Audio: a binary frame (4-byte stream id + payload) comes first, then the
+ *   JSON message naming its stream; the server pairs them, both directions.
+ *
+ * The server knows nothing about DSH or sessions; the plugin wires it.
+ */
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { WebSocketServer } from 'ws';
+import { decodeAudioFrame, encodeAudioFrame, parseMessage, PROTOCOL_VERSION } from "../protocol/index.js";
+export const DEFAULT_PORT = 38100;
+const PORT_TRIES = 20;
+const DEAD_AFTER_MS = 45_000;
+/** Audio frames waiting for the message that names them, per body; older ones are dropped. */
+const MAX_PENDING_AUDIO = 8;
+function writePrivate(file, text) {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, text, { mode: 0o600 });
+    try {
+        chmodSync(file, 0o600);
+    }
+    catch {
+        // Windows: the user's profile directory is already private.
+    }
+}
+/** The brain's token: read, or created on first start. */
+export function loadToken(file) {
+    if (existsSync(file)) {
+        const token = readFileSync(file, 'utf8').trim();
+        if (token.length >= 32)
+            return token;
+    }
+    const token = randomBytes(32).toString('base64url');
+    writePrivate(file, `${token}\n`);
+    return token;
+}
+function sameToken(a, b) {
+    const x = Buffer.from(a);
+    const y = Buffer.from(b);
+    return x.byteLength === y.byteLength && timingSafeEqual(x, y);
+}
+async function listen(port) {
+    return new Promise((resolve, reject) => {
+        const server = new WebSocketServer({ host: '127.0.0.1', port, maxPayload: 32 * 1024 * 1024 });
+        server.once('listening', () => resolve(server));
+        server.once('error', reject);
+    });
+}
+export class BrainServer {
+    server;
+    token = '';
+    nextId = 1;
+    clients = new Map();
+    reaper;
+    lastSeen = new Map();
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    get port() {
+        const address = this.server?.address();
+        return typeof address === 'object' && address !== null ? address.port : undefined;
+    }
+    get url() {
+        return this.port === undefined ? undefined : `ws://127.0.0.1:${this.port}`;
+    }
+    get bodies() {
+        return [...this.clients.values()];
+    }
+    async start() {
+        this.token = loadToken(this.options.tokenFile);
+        const first = this.options.preferredPort ?? DEFAULT_PORT;
+        let lastError;
+        for (let i = 0; i <= PORT_TRIES && this.server === undefined; i++) {
+            try {
+                this.server = await listen(i === PORT_TRIES ? 0 : first + i);
+            }
+            catch (error) {
+                lastError = error;
+            }
+        }
+        if (this.server === undefined)
+            throw lastError;
+        this.server.on('connection', socket => this.accept(socket));
+        this.reaper = setInterval(() => this.reap(), 15_000);
+        this.reaper.unref();
+        const discovery = { url: this.url, token: this.token, pid: process.pid, protocol: PROTOCOL_VERSION, startedAt: new Date().toISOString() };
+        writePrivate(this.options.discoveryFile, `${JSON.stringify(discovery, null, 2)}\n`);
+        this.options.logger?.info(`dsh-her: brain listening on ${this.url}`);
+        return discovery;
+    }
+    broadcast(message) {
+        for (const client of this.clients.values())
+            client.send(message);
+    }
+    /** Send audio and then the message naming its stream to every body. */
+    broadcastWithAudio(message, stream, payload) {
+        for (const client of this.clients.values()) {
+            client.sendAudio(stream, payload);
+            client.send(message);
+        }
+    }
+    async stop() {
+        clearInterval(this.reaper);
+        const server = this.server;
+        this.server = undefined;
+        for (const socket of this.clients.keys())
+            socket.close(1001, 'brain stopping');
+        this.clients.clear();
+        try {
+            const current = JSON.parse(readFileSync(this.options.discoveryFile, 'utf8'));
+            if (current.pid === process.pid)
+                rmSync(this.options.discoveryFile, { force: true });
+        }
+        catch {
+            // already gone
+        }
+        await new Promise(resolve => server === undefined ? resolve() : server.close(() => resolve()));
+    }
+    accept(socket) {
+        this.lastSeen.set(socket, Date.now());
+        const send = (message) => {
+            if (socket.readyState === socket.OPEN)
+                socket.send(JSON.stringify(message));
+        };
+        const sendAudio = (stream, payload) => {
+            if (socket.readyState === socket.OPEN)
+                socket.send(encodeAudioFrame(stream, payload));
+        };
+        const pendingAudio = new Map();
+        // The first message must be a valid hello within 10 s.
+        const helloTimer = setTimeout(() => socket.close(4000, 'no hello'), 10_000);
+        socket.on('message', (data, isBinary) => {
+            this.lastSeen.set(socket, Date.now());
+            if (isBinary) {
+                if (!this.clients.has(socket))
+                    return;
+                const bytes = data instanceof Buffer ? data : Buffer.concat(Array.isArray(data) ? data : [Buffer.from(data)]);
+                const frame = decodeAudioFrame(new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength));
+                if (frame === undefined)
+                    return;
+                pendingAudio.set(frame.stream, frame.payload);
+                while (pendingAudio.size > MAX_PENDING_AUDIO)
+                    pendingAudio.delete(pendingAudio.keys().next().value);
+                return;
+            }
+            const message = parseMessage(data.toString());
+            if (message === undefined)
+                return;
+            const client = this.clients.get(socket);
+            if (client === undefined) {
+                clearTimeout(helloTimer);
+                this.admit(socket, message, send, sendAudio);
+                return;
+            }
+            if (message.t === 'ping') {
+                client.send({ t: 'pong', at: message.at });
+                return;
+            }
+            const stream = message.stream;
+            const audio = typeof stream === 'number' ? pendingAudio.get(stream) : undefined;
+            if (typeof stream === 'number')
+                pendingAudio.delete(stream);
+            try {
+                this.options.message(client, message, audio);
+            }
+            catch (error) {
+                this.options.logger?.warn(`dsh-her: body message ${message.t} failed (${error.message})`);
+            }
+        });
+        socket.on('close', () => {
+            clearTimeout(helloTimer);
+            this.lastSeen.delete(socket);
+            const client = this.clients.get(socket);
+            this.clients.delete(socket);
+            if (client !== undefined)
+                this.options.closed?.(client);
+        });
+        socket.on('error', () => socket.close());
+    }
+    admit(socket, message, send, sendAudio) {
+        if (message.t !== 'hello') {
+            socket.close(4001, 'hello first');
+            return;
+        }
+        if (typeof message.token !== 'string' || !sameToken(message.token, this.token)) {
+            send({ t: 'reject', reason: 'token', message: '令牌不对：请重新配对，或让 dsh 重新拉起身体' });
+            socket.close(4003, 'token');
+            return;
+        }
+        if (message.v !== PROTOCOL_VERSION) {
+            send({ t: 'reject', reason: 'version', message: `协议版本不一致（身体 ${message.v}，大脑 ${PROTOCOL_VERSION}），请更新` });
+            socket.close(4004, 'version');
+            return;
+        }
+        const client = { id: this.nextId++, hello: message, send, sendAudio };
+        this.clients.set(socket, client);
+        send(this.options.welcome(client));
+        this.options.logger?.info(`dsh-her: body #${client.id} connected (${message.body.kind} ${message.body.version}, ${message.body.os})`);
+    }
+    reap() {
+        const now = Date.now();
+        for (const [socket, seen] of this.lastSeen) {
+            if (now - seen > DEAD_AFTER_MS)
+                socket.terminate();
+        }
+    }
+}

package/lib/types/core/character.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Who she is, as the wizard and the "她" page set it: `<home>/characters/<cid>/character.json`.
+ * The plugin config only gives the first defaults; once saved here, this file
+ * wins, and changes apply from her next model request (her prompt is rebuilt
+ * every time) without restarting DSH.
+ */
+export type Pronoun = '他' | '她' | 'TA';
+export interface Character {
+    name: string;
+    persona: string;
+    /** What she calls you; empty = she has not been told. */
+    callYou: string;
+    /** How she refers to you in her notes and memories. */
+    pronoun: Pronoun;
+    /** A CosyVoice voice id (voices.ts), and how fast she talks. */
+    voice: {
+        id: string;
+        speed: number;
+    };
+    /** Her model; undefined = the plugin config's, else DSH's default. `effort` empty = the route's default. */
+    model?: {
+        provider: string;
+        model: string;
+        effort?: string;
+    };
+    /** The wizard has been completed once. */
+    onboarded: boolean;
+}
+export declare function loadCharacter(dir: string, defaults: Character): Character;
+export declare function saveCharacter(dir: string, character: Character): void;
+/** Check a patch from the page; returns the error message, or undefined when it is fine. */
+export declare function invalidCharacter(c: Character): string | undefined;

package/lib/types/core/cues.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Inline performance tags (docs/大脑与dsh会话.md §6): she writes 〔开心〕 or
+ * 〔动作:wave〕 in her reply; they are taken out of the text (never shown,
+ * never spoken) and sent as cues with the sentence, so the body acts them out
+ * when that sentence starts. Only what the connected pack can do is kept.
+ *
+ * The prompt section that teaches her the tags is generated from the same
+ * pack summary, so she only ever hears of moves her body has.
+ */
+import type { Cue, PackSummary } from '../protocol/index.ts';
+/** Chinese names for the emotions a pack may have. */
+export declare const EMOTION_WORDS: Record<string, string>;
+/** Light actions are acted inline; heavy ones (outfits, stored lines) go through the play_action tool. */
+export declare function isHeavy(action: PackSummary['actions'][number]): boolean;
+export declare function extractCues(text: string, pack: PackSummary | undefined): {
+    text: string;
+    cues: Cue[];
+};
+/** The "表演" section of her system prompt, for what this pack can do; empty without a pack. */
+export declare function performanceSection(pack: PackSummary | undefined): string;

package/lib/types/core/echo.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Was that you, or her own voice coming back through the speakers?
+ *
+ * Right after a barge-in the brain checks what was recognized against what
+ * she was saying. Mostly her own words (character-bigram overlap), or only a
+ * filler sound (嗯, 啊…), means it was not you: it is dropped instead of
+ * becoming your turn, and the body counts it toward turning barge-in off.
+ */
+export type EchoVerdict = 'you' | 'echo' | 'filler';
+export declare function judgeBargeIn(heard: string, herWords: string): EchoVerdict;

package/lib/types/core/index.d.ts

@@ -0,0 +1,10 @@
+/** Pure logic with no DSH imports. */
+export { FIRST_SOFT_CUT_AT, readingMs, SentenceSplitter, SOFT_CUT_AT } from './sentences.ts';
+export { speakable } from './speakable.ts';
+export { judgeBargeIn, type EchoVerdict } from './echo.ts';
+export { EMOTION_WORDS, extractCues, isHeavy, performanceSection } from './cues.ts';
+export { buildSystemPrompt, memoryContext, SAMPLE_PERSONA, type MemoryContext, type PromptParts } from './prompt.ts';
+export { herPaths, type HerPaths } from './paths.ts';
+export { DEFAULT_VOICE, SERVICE_NAMES, serviceOf, VOICE_MODEL, VOICES, voiceName, type VoiceOption, type VoiceService } from './voices.ts';
+export { invalidCharacter, loadCharacter, saveCharacter, type Character, type Pronoun } from './character.ts';
+export { decodeWav, encodeWav, wavFromPcm16 } from './wav.ts';

package/lib/types/core/paths.d.ts

@@ -0,0 +1,11 @@
+export interface HerPaths {
+    root: string;
+    /** brain.json: where the brain listens and its token, for a body the user started by hand. */
+    discovery: string;
+    characters: string;
+    packs: string;
+    models: string;
+    logs: string;
+}
+/** Everything dsh-her writes lives under one home outside DSH (`~` expands). */
+export declare function herPaths(home: string): HerPaths;

package/lib/types/core/prompt.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Her system prompt. It replaces DSH's default ("You are a coding agent …")
+ * for her session only. Sections are joined in a fixed order; design:
+ * docs/大脑与dsh会话.md §5.
+ */
+export interface PromptParts {
+    name: string;
+    /** Who she is, how she talks, how she relates to you (from the character settings). */
+    persona: string;
+    /** Inline performance tags she may use, generated from the body's pack; empty when no body is connected. */
+    performance?: string;
+    /** What she remembers, already rendered (memoryContext); empty until there is any. */
+    aboutYou?: string;
+    /** Today, so "tomorrow" and "next Wednesday" mean something. */
+    now?: Date;
+    /** What she calls you, and the pronoun for you in her notes. */
+    you?: {
+        call: string;
+        pronoun: string;
+    };
+}
+export interface MemoryContext {
+    profile: string;
+    recent: string;
+    due: Array<{
+        text: string;
+        due?: string;
+    }>;
+}
+/**
+ * The part of the day, not the minute: her prompt is rebuilt on every request,
+ * and a clock that changes each minute would defeat the provider's prompt cache.
+ */
+export declare function partOfDay(now: Date): string;
+/** "关于对方": facts, the last diary days, and what has a date today or tomorrow. */
+export declare function memoryContext(memory: MemoryContext): string;
+export declare function buildSystemPrompt(parts: PromptParts): string;
+/** Development placeholder until the wizard writes a real persona. */
+export declare const SAMPLE_PERSONA: string;

package/lib/types/core/sentences.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Streaming sentence splitter for speech: the reply is spoken sentence by
+ * sentence, so synthesis starts on the first sentence while the model is
+ * still writing the rest.
+ *
+ * A sentence ends at a terminator (。！？!?… or a line break); closing quotes
+ * and brackets right after it stay with the sentence. A long run with no
+ * terminator is cut at the last soft pause (，、；：,;) so the first audio is
+ * never held back by one endless clause. The first sentence of a reply is cut
+ * much earlier (FIRST_SOFT_CUT_AT): the sooner the first audio is synthesized,
+ * the sooner she starts talking. Fragments with no letters or digits (a lone
+ * "！", stray markdown) are dropped: they must never reach the TTS. Nothing is
+ * ever cut inside a performance tag 〔…〕.
+ */
+/** Characters after which a run without a terminator is cut at its last soft pause. */
+export declare const SOFT_CUT_AT = 48;
+/** The same, for the first sentence of a reply. */
+export declare const FIRST_SOFT_CUT_AT = 8;
+/**
+ * How long a sentence takes to say or read, for showing it when there is no
+ * audio to time it by: about 4.5 Chinese characters a second, at least 1.2 s.
+ */
+export declare function readingMs(text: string): number;
+export declare class SentenceSplitter {
+    private buffer;
+    /** A terminated sentence held until the next character shows whether a closer follows. */
+    private pending;
+    /** Sentences released since the last reset. */
+    private released;
+    /** Inside a 〔…〕 tag. */
+    private inTag;
+    /** Feed a streamed delta; returns the sentences it completed, in order. */
+    push(delta: string): string[];
+    /** The held sentence and the unterminated rest, once the reply has ended. */
+    flush(): string[];
+    /** Forget everything (the reply was interrupted). */
+    reset(): void;
+    private release;
+    private cutAtSoftPause;
+}

package/lib/types/core/speakable.d.ts

@@ -0,0 +1,6 @@
+/**
+ * What of a sentence can be said aloud. Her system prompt asks for plain
+ * spoken text, but models still slip in markdown, links and code; those are
+ * dropped or reduced before synthesis. The subtitle keeps the original text.
+ */
+export declare function speakable(text: string): string;

package/lib/types/core/voices.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Her voices, shared by the brain and the "她" page. Which service speaks
+ * follows from the voice she uses:
+ * - edge: Microsoft Edge "Read aloud" voices via the edge-tts tool (free,
+ *   needs the internet; voice/edge.ts);
+ * - cosyvoice: Alibaba Cloud Model Studio (百炼) CosyVoice, model
+ *   cosyvoice-v3-flash (needs a key and paid quota; voice/cosyvoice.ts). Its
+ *   ids are the API's `voice` parameter, exactly as listed.
+ */
+export declare const VOICE_MODEL = "cosyvoice-v3-flash";
+export type VoiceService = 'edge' | 'cosyvoice';
+export interface VoiceOption {
+    id: string;
+    name: string;
+    desc: string;
+    service: VoiceService;
+}
+export declare const VOICES: readonly VoiceOption[];
+export declare const DEFAULT_VOICE = "zh-CN-XiaoxiaoNeural";
+export declare function voiceName(id: string): string;
+/** Which service a voice belongs to; an id not in the list goes by its shape (Edge ids end in "Neural"). */
+export declare function serviceOf(id: string): VoiceService;
+export declare const SERVICE_NAMES: Record<VoiceService, string>;

package/lib/types/core/wav.d.ts

@@ -0,0 +1,9 @@
+/** Minimal PCM16 mono WAV encoding/decoding for speech audio. */
+export declare function encodeWav(samples: Float32Array, sampleRate: number): Uint8Array;
+/** Wrap raw little-endian PCM16 mono (as a cloud voice sends it) in a WAV header. */
+export declare function wavFromPcm16(pcm: Uint8Array, sampleRate: number): Uint8Array;
+/** Decode a PCM16 mono WAV (as produced by encodeWav or a mic capture). */
+export declare function decodeWav(bytes: Uint8Array): {
+    samples: Float32Array;
+    sampleRate: number;
+};

package/lib/types/core/workshop.d.ts

@@ -0,0 +1,156 @@
+/**
+ * 形象工坊 (docs/形象工坊与多场景.md §4): a look as a project the user fills in,
+ * and the prompts and files made from it. Pure: the brain writes the files
+ * (dsh/workshop.ts), the "她" page edits the project.
+ *
+ * Prompts come in three layers:
+ * - rules: fixed, by kind (desk pet or scene);
+ * - who she is: one sentence from the character card, the same in every
+ *   image and every clip, so she stays the same person;
+ * - the action: one per clip, preset or the user's own.
+ */
+export declare const PROJECT_FORMAT = "dsh-her-workshop@1";
+export declare const PROJECT_FILE = "\u5F62\u8C61.json";
+export declare const REFERENCE_FILE = "\u53C2\u8003\u56FE.png";
+export declare const DESK_DIR = "\u684C\u5BA0";
+export declare const sceneDir: (scene: {
+    name: string;
+}) => string;
+/** A folder or file name from what the user typed. */
+export declare function safeName(text: string): string;
+export interface CharacterCard {
+    gender: string;
+    age: string;
+    skin: string;
+    hairStyle: string;
+    hairColor: string;
+    build: string;
+    outfit: string;
+    accessories: string;
+    style: string;
+    /** Anything else ("左眼下有颗小痣"). */
+    extra: string;
+    /** The sentence as the user edited it; empty: made from the fields. */
+    sentence: string;
+}
+/** Choices for each field of the card ("自己写" is always possible). Ages are adults only. */
+export declare const CARD_CHOICES: Record<Exclude<keyof CharacterCard, 'extra' | 'sentence'>, readonly string[]>;
+export declare const CARD_LABELS: Record<keyof CharacterCard, string>;
+export declare const DEFAULT_CARD: CharacterCard;
+/** "二十多岁的成年女性，自然肤色，深棕色长卷发，戴细框眼镜，穿家居服，身材匀称" — or the user's own sentence. */
+export declare function describe(card: CharacterCard): string;
+/** Green clothes would be keyed away with the green screen: then the background is grey. */
+export declare function screenColor(card: CharacterCard): {
+    name: string;
+    hex: string;
+};
+export type Pose = 'stand' | 'sit' | 'lie';
+export declare const POSE_WORDS: Record<Pose, string>;
+export interface ClipPlan {
+    /** File name without .mp4: `<pose>_<role>_<nn>`. */
+    file: string;
+    action: string;
+    /** Part of the minimum: idle and two talks. */
+    required?: boolean;
+    /** Left out of the task (the user unticked it). */
+    off?: boolean;
+}
+export interface ProjectScene {
+    id: string;
+    name: string;
+    /** What the place looks like ("温馨的卧室，木质床头柜和台灯，暖色灯光"). */
+    place: string;
+    pose: Pose;
+    hours?: string;
+    user?: 'active' | 'idle';
+    clips: ClipPlan[];
+}
+/** The tool the clips are made with. `manual` is any other tool, described in `custom`. */
+export type Generator = 'minimax' | 'comfyui' | 'jimeng' | 'kling' | 'hailuo' | 'wanx' | 'vidu' | 'manual';
+export interface GeneratorInfo {
+    name: string;
+    /** One line in the picker. */
+    label: string;
+    /** The settings every clip uses, written at the top of each 提示词.txt. */
+    settings: string;
+    /** How the clips get made, in the last card. */
+    how: string;
+}
+export declare const GENERATORS: Record<Exclude<Generator, 'manual'>, GeneratorInfo>;
+/** For `manual`: the tool's name, its settings, and words every clip's prompt starts with (a LoRA trigger word, a style). */
+export interface CustomGenerator {
+    name: string;
+    settings: string;
+    prefix: string;
+}
+export declare const MANUAL_LABEL = "\u624B\u5DE5\u586B\u5199\uFF08\u522B\u7684\u5DE5\u5177\uFF0C\u81EA\u5DF1\u5199\u540D\u5B57\u548C\u8BBE\u7F6E\uFF09";
+/** The project's tool, a custom one filled in from `custom`. */
+export declare function generatorInfo(project: Pick<LookProject, 'generator' | 'custom'>): GeneratorInfo;
+export interface LookProject {
+    format: typeof PROJECT_FORMAT;
+    id: string;
+    name: string;
+    card: CharacterCard;
+    desk: {
+        on: boolean;
+        clips: ClipPlan[];
+    };
+    scenes: ProjectScene[];
+    /** The scene when no rule matches (an id in `scenes`). */
+    default?: string;
+    generator: Generator;
+    /** Filled in when `generator` is `manual`. */
+    custom?: CustomGenerator;
+    createdAt: string;
+}
+/** The preset clips for a pose: the minimum ticked, the rest offered unticked. */
+export declare function presetClips(pose: Pose): ClipPlan[];
+/** A clip of the user's own: an action name from what they typed (`<pose>_<name>_01`), not clashing with the others. */
+export declare function customClip(pose: Pose, existing: readonly ClipPlan[], action: string): ClipPlan;
+export declare function newProject(id: string, name: string, now?: Date): LookProject;
+export declare function newScene(id: string, name: string, pose?: Pose): ProjectScene;
+/** Fixed rules every clip carries, for its kind and the generator. */
+export declare function rules(project: LookProject, kind: 'desk' | 'scene', scene?: ProjectScene): string;
+export declare const NEGATIVE = "\u6362\u8138, \u8EAB\u4EFD\u6F02\u79FB, \u53D1\u578B\u53D8\u5316, \u670D\u88C5\u53D8\u5316, \u5E74\u9F84\u53D8\u5316, \u591A\u4F59\u4EBA\u7269, \u591A\u4F59\u624B\u6307, \u624B\u90E8\u7578\u5F62, \u80A2\u4F53\u626D\u66F2, \u811A\u6B65\u79FB\u52A8, \u8D70\u51FA\u753B\u9762, \u77AC\u79FB, \u955C\u5934\u79FB\u52A8, \u53D8\u7126, \u5207\u955C, \u80CC\u666F\u53D8\u5316, \u5149\u7EBF\u95EA\u70C1, \u9634\u5F71\u51FA\u73B0, \u6587\u5B57, \u5B57\u5E55, \u6C34\u5370, logo, \u5938\u5F20\u8868\u60C5, \u5361\u901A\u5316, \u5851\u6599\u76AE\u80A4, \u6A21\u7CCA, \u4F4E\u6E05";
+/** The full prompt of one clip: rules, who she is, the action. */
+export declare function clipPrompt(project: LookProject, kind: 'desk' | 'scene', clip: ClipPlan, scene?: ProjectScene): string;
+/** The reference picture: her on a plain screen, full length. It is also the desk pet's anchor. */
+export declare function referencePrompt(project: LookProject): string;
+/** A scene's full-screen photo, made with the reference picture so she stays the same person. */
+export declare function scenePhotoPrompt(project: LookProject, scene: ProjectScene, screen?: {
+    width: number;
+    height: number;
+}): string;
+/** Every clip to make, with where it goes and its prompt. */
+export declare function plannedClips(project: LookProject): Array<{
+    part: string;
+    folder: string;
+    first: string;
+    clip: ClipPlan;
+    prompt: string;
+}>;
+/** 提示词.txt of one part (the desk pet, or a scene): every clip's prompt, ready to copy. */
+export declare function promptsFile(project: LookProject, part: 'desk' | ProjectScene): string;
+/** 生成清单.md: every clip with its first frame, where it goes and its prompt, for any tool. */
+export declare function clipList(project: LookProject, root: string): string;
+/** ComfyUI生成清单.json: the same list for a script that drives a ComfyUI workflow. */
+export declare function comfyuiList(project: LookProject, root: string): string;
+/** The task file for MiniMax Code: one uniform setting, at most 5 at a time, download as each finishes. */
+export declare function minimaxTask(project: LookProject, root: string): string;
+/** An age that is clearly grown up: 二十多岁, 三十岁左右, 25 岁, 成年 … */
+export declare function isAdult(age: string): boolean;
+/** Check a project read from disk or sent by the page. */
+export declare function validateProject(value: unknown): LookProject;
+/** The workshop's cards, in order. */
+export type WorkshopCard = 'look' | 'reference' | 'desk' | 'scene' | 'import';
+/**
+ * Example pictures and clips each card shows, by file name under
+ * `examples/workshop/` (in the plugin; a file of the same name in
+ * `<home>/examples/workshop/` wins). A missing one shows as a placeholder
+ * naming the file, until the finished showroom's material is put there.
+ */
+export declare const EXAMPLE_SLOTS: Record<WorkshopCard, ReadonlyArray<{
+    file: string;
+    label: string;
+}>>;
+export declare const EXAMPLE_FILES: ReadonlySet<string>;