@linxin666/dsh-pet 0.2.2 → 0.2.4

package/lib/types/voice-pack.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Voice-pack normalization and merge (pet-center M4, issue #677).
+ *
+ * A voice pack is the optional 'voice.json' inside a pet directory, or the
+ * global '$DSH_HOME/pets/.voice.json' override file — pure JSON content that
+ * layers pet copy over the built-in pools. Two halves:
+ *
+ *  - 'overrides': the chatter pools (status / tools / toolRemaining /
+ *    whispers) handed to the chatter engines through a VoicePoolsProvider;
+ *  - 'panel': the hover-panel chrome (button labels, stat formats, action
+ *    subset) served to the browser half through PetDefinition.panel.
+ *
+ * Discipline split matches the registry: STRUCTURE is fail-closed per file
+ * (a non-object root drops the whole pack with a warning), CONTENT is
+ * warn-and-drop per slot — one bad line never breaks a pet. The JSON Schema
+ * twin lives at contracts/voice-pack-v1.schema.json for documentation and
+ * external tooling; this hand-rolled normalizer is authoritative (the
+ * repository ships no schema-validator runtime).
+ *
+ * Placeholder policy (each pool kind whitelists its own tokens):
+ *  - status / whisper pools / panel labels: no placeholders allowed — a line
+ *    carrying any '{...}' token is dropped with a warning;
+ *  - tools: {tool} and {hint}; toolRemaining: {n}; panel stats:
+ *    {rank} / {n} / {points}.
+ *
+ * This file is imported directly by scripts/dsh-pet under node's strip-only
+ * TypeScript mode: keep it erasable-syntax-only.
+ * @module @linxin666/dsh-pet/voice-pack
+ */
+import { type VoicePackOverrides, type WhisperRule } from './chatter.ts';
+/** Schema version this module normalizes (optional field; missing = 1). */
+export declare const VOICE_PACK_V1: 1;
+/** Hover-panel action buttons a pack can show or hide (canonical order). */
+export declare const PANEL_ACTIONS: readonly ['feed', 'rename', 'hide'];
+export type PanelAction = (typeof PANEL_ACTIONS)[number];
+/** Panel label slots (unset slots keep the client's i18n dictionary copy). */
+export declare const PANEL_LABEL_KEYS: readonly ['feed', 'rename', 'hide', 'confirm'];
+export type PanelLabelKey = (typeof PANEL_LABEL_KEYS)[number];
+/** Panel stat slots ({rank}/{n}/{points} interpolate the live values). */
+export declare const PANEL_STAT_KEYS: readonly ['rank', 'treats', 'points'];
+export type PanelStatKey = (typeof PANEL_STAT_KEYS)[number];
+/** Hover-panel chrome overrides served to the browser half. */
+export interface PetPanelView {
+    /** Button / input labels; unset slots keep the i18n dictionary copy. */
+    labels?: Partial<Record<PanelLabelKey, string>>;
+    /** Stat line formats; unset slots keep the i18n dictionary copy. */
+    stats?: Partial<Record<PanelStatKey, string>>;
+    /** Actions to render in canonical order; absent = all three; [] = none. */
+    actions?: PanelAction[];
+}
+/** One normalized voice pack (a pet's voice.json or the global override). */
+export interface VoicePack {
+    /** Chatter pool overrides (draw-time merged with the built-in pools). */
+    overrides: VoicePackOverrides;
+    /** Hover-panel chrome, when the pack declares any. */
+    panel?: PetPanelView;
+}
+/** Hard caps shared by every pool slot (mirrors the remarks discipline). */
+export declare const VOICE_POOL_LINES_MAX = 64;
+export declare const VOICE_LINE_MAX = 160;
+export declare const VOICE_KEYWORDS_PER_RULE_MAX = 16;
+export declare const VOICE_KEYWORD_MAX = 40;
+export declare const VOICE_RULES_MAX = 32;
+export declare const VOICE_LABEL_MAX = 40;
+export declare const VOICE_STAT_MAX = 80;
+type PoolKind = 'status' | 'tools' | 'toolRemaining' | 'whisperGeneric' | 'whisperRule' | 'label' | 'stat';
+/**
+ * Normalize one pool slot. Accepts a single line or an array; non-string
+ * entries warn and drop, empty lines drop silently, lines over the length
+ * cap truncate, illegal placeholders drop the line, and pools over the line
+ * cap keep their first lines. An explicit empty pool normalizes to [] (the
+ * whisper channels read that as mute) while an absent slot normalizes to
+ * undefined (the slot keeps the built-in pool).
+ */
+export declare function normalizePool(raw: unknown, kind: PoolKind, onWarning?: (message: string) => void): string[] | undefined;
+/** Normalize the ordered keyword-rule list ([] disables the keyword channel). */
+export declare function normalizeWhisperRules(raw: unknown, onWarning?: (message: string) => void): WhisperRule[] | undefined;
+/** Normalize the panel block (labels / stats / actions; warn-and-drop). */
+export declare function normalizePanel(raw: unknown, onWarning?: (message: string) => void): PetPanelView | undefined;
+/** Voice-pack top-level fields ('$schema' mirrors the schema twin; drift-locked in tests). */
+export declare const VOICE_PACK_KEYS: Set<string>;
+/** Allowed whisper-section fields (drift-locked in tests). */
+export declare const WHISPER_KEYS: Set<string>;
+/**
+ * Normalize one raw voice.json document into a VoicePack, or undefined when
+ * the file cannot serve as a pack at all (non-object root — structure is
+ * fail-closed per file). Every slot issue is a warning, never a throw.
+ */
+export declare function normalizeVoicePack(raw: unknown, onWarning?: (message: string) => void): VoicePack | undefined;
+/**
+ * Merge voice-pack layers into one pack; later layers win per slot. The
+ * built-in pools are NOT a layer here — the chatter engines fall back to
+ * them per key at draw time. Merge order for a selected pet:
+ * mergeVoicePacks(registry.globalVoice, entry.voice).
+ */
+export declare function mergeVoicePacks(...layers: (VoicePack | undefined)[]): VoicePack | undefined;
+export {};
+//# sourceMappingURL=voice-pack.d.ts.map

package/lib/types/voice-pack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-pack.d.ts","sourceRoot":"","sources":["../../src/voice-pack.ts"],"names":[],"mappings":"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"}

package/lib/types/voice-pack.js

@@ -0,0 +1,384 @@
+/**
+ * Voice-pack normalization and merge (pet-center M4, issue #677).
+ *
+ * A voice pack is the optional 'voice.json' inside a pet directory, or the
+ * global '$DSH_HOME/pets/.voice.json' override file — pure JSON content that
+ * layers pet copy over the built-in pools. Two halves:
+ *
+ *  - 'overrides': the chatter pools (status / tools / toolRemaining /
+ *    whispers) handed to the chatter engines through a VoicePoolsProvider;
+ *  - 'panel': the hover-panel chrome (button labels, stat formats, action
+ *    subset) served to the browser half through PetDefinition.panel.
+ *
+ * Discipline split matches the registry: STRUCTURE is fail-closed per file
+ * (a non-object root drops the whole pack with a warning), CONTENT is
+ * warn-and-drop per slot — one bad line never breaks a pet. The JSON Schema
+ * twin lives at contracts/voice-pack-v1.schema.json for documentation and
+ * external tooling; this hand-rolled normalizer is authoritative (the
+ * repository ships no schema-validator runtime).
+ *
+ * Placeholder policy (each pool kind whitelists its own tokens):
+ *  - status / whisper pools / panel labels: no placeholders allowed — a line
+ *    carrying any '{...}' token is dropped with a warning;
+ *  - tools: {tool} and {hint}; toolRemaining: {n}; panel stats:
+ *    {rank} / {n} / {points}.
+ *
+ * This file is imported directly by scripts/dsh-pet under node's strip-only
+ * TypeScript mode: keep it erasable-syntax-only.
+ * @module @linxin666/dsh-pet/voice-pack
+ */
+import { STATUS_SCENES, TOOL_CATEGORIES, } from './chatter.js';
+/** Schema version this module normalizes (optional field; missing = 1). */
+export const VOICE_PACK_V1 = 1;
+/** Hover-panel action buttons a pack can show or hide (canonical order). */
+export const PANEL_ACTIONS = ['feed', 'rename', 'hide'];
+/** Panel label slots (unset slots keep the client's i18n dictionary copy). */
+export const PANEL_LABEL_KEYS = ['feed', 'rename', 'hide', 'confirm'];
+/** Panel stat slots ({rank}/{n}/{points} interpolate the live values). */
+export const PANEL_STAT_KEYS = ['rank', 'treats', 'points'];
+/** Hard caps shared by every pool slot (mirrors the remarks discipline). */
+export const VOICE_POOL_LINES_MAX = 64;
+export const VOICE_LINE_MAX = 160;
+export const VOICE_KEYWORDS_PER_RULE_MAX = 16;
+export const VOICE_KEYWORD_MAX = 40;
+export const VOICE_RULES_MAX = 32;
+export const VOICE_LABEL_MAX = 40;
+export const VOICE_STAT_MAX = 80;
+/** Any '{token}' placeholder (no nesting, no newlines). */
+const PLACEHOLDER_PATTERN = /{[^{}]*}/g;
+/** Allowed placeholder tokens per pool kind (absent kind = none allowed). */
+const PLACEHOLDER_WHITELIST = {
+    tools: ['{tool}', '{hint}'],
+    toolRemaining: ['{n}'],
+    stat: ['{rank}', '{n}', '{points}'],
+};
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Trim, length-cap and placeholder-check one copy line; undefined to drop. */
+function normalizeLine(raw, kind, onWarning) {
+    const trimmed = raw.trim();
+    if (trimmed === '')
+        return undefined;
+    let capped = trimmed.length > VOICE_LINE_MAX ? trimmed.slice(0, VOICE_LINE_MAX) : trimmed;
+    // The length cap may cut a placeholder token in half, leaving a dangling
+    // '{' that would render literally; drop the tail from the unmatched brace.
+    const dangling = capped.lastIndexOf('{');
+    if (dangling !== -1 && capped.indexOf('}', dangling) === -1) {
+        onWarning('line cut at an unterminated placeholder; tail dropped: ' + capped.slice(0, 40) + '...');
+        capped = capped.slice(0, dangling);
+    }
+    if (capped === '')
+        return undefined;
+    const allowed = PLACEHOLDER_WHITELIST[kind];
+    const tokens = capped.match(PLACEHOLDER_PATTERN) ?? [];
+    for (const token of tokens) {
+        if (allowed?.includes(token) === true)
+            continue;
+        const preview = capped.length > 40 ? capped.slice(0, 40) + '...' : capped;
+        onWarning('line dropped (unsupported placeholder ' + token + '): ' + preview);
+        return undefined;
+    }
+    return capped;
+}
+/**
+ * Normalize one pool slot. Accepts a single line or an array; non-string
+ * entries warn and drop, empty lines drop silently, lines over the length
+ * cap truncate, illegal placeholders drop the line, and pools over the line
+ * cap keep their first lines. An explicit empty pool normalizes to [] (the
+ * whisper channels read that as mute) while an absent slot normalizes to
+ * undefined (the slot keeps the built-in pool).
+ */
+export function normalizePool(raw, kind, onWarning = () => { }) {
+    if (raw === undefined)
+        return undefined;
+    const entries = typeof raw === 'string' ? [raw] : Array.isArray(raw) ? raw : undefined;
+    if (entries === undefined) {
+        onWarning('pool must be a string or an array of strings');
+        return undefined;
+    }
+    if (entries.length > VOICE_POOL_LINES_MAX) {
+        onWarning('pool has more than ' + VOICE_POOL_LINES_MAX + ' lines; extra lines are ignored');
+    }
+    const pool = [];
+    for (const entry of entries.slice(0, VOICE_POOL_LINES_MAX)) {
+        if (typeof entry !== 'string') {
+            onWarning('non-string pool entry dropped');
+            continue;
+        }
+        const line = normalizeLine(entry, kind, onWarning);
+        if (line !== undefined)
+            pool.push(line);
+    }
+    return pool;
+}
+/** Normalize the ordered keyword-rule list ([] disables the keyword channel). */
+export function normalizeWhisperRules(raw, onWarning = () => { }) {
+    if (raw === undefined)
+        return undefined;
+    if (!Array.isArray(raw)) {
+        onWarning('whispers.rules must be an array');
+        return undefined;
+    }
+    if (raw.length > VOICE_RULES_MAX) {
+        onWarning('whispers.rules has more than ' + VOICE_RULES_MAX + ' rules; extra rules are ignored');
+    }
+    const rules = [];
+    for (const item of raw.slice(0, VOICE_RULES_MAX)) {
+        if (!isRecord(item)) {
+            onWarning('whisper rule must be an object');
+            continue;
+        }
+        for (const key of Object.keys(item)) {
+            if (key !== 'keywords' && key !== 'pool')
+                onWarning('unknown whisper rule field ' + key + ' ignored');
+        }
+        const keywordsRaw = item.keywords;
+        const keywords = [];
+        if (Array.isArray(keywordsRaw)) {
+            for (const entry of keywordsRaw.slice(0, VOICE_KEYWORDS_PER_RULE_MAX)) {
+                if (typeof entry !== 'string') {
+                    onWarning('non-string keyword dropped');
+                    continue;
+                }
+                const trimmed = entry.trim().toLowerCase().slice(0, VOICE_KEYWORD_MAX);
+                if (trimmed !== '')
+                    keywords.push(trimmed);
+            }
+            if (keywordsRaw.length > VOICE_KEYWORDS_PER_RULE_MAX) {
+                onWarning('rule has more than ' + VOICE_KEYWORDS_PER_RULE_MAX + ' keywords; extra keywords are ignored');
+            }
+        }
+        const pool = normalizePool(item.pool, 'whisperRule', onWarning);
+        if (keywords.length === 0 || pool === undefined || pool.length === 0) {
+            onWarning('whisper rule dropped (needs keywords and a non-empty pool)');
+            continue;
+        }
+        rules.push({ keywords, pool });
+    }
+    return rules;
+}
+/** Normalize the panel block (labels / stats / actions; warn-and-drop). */
+export function normalizePanel(raw, onWarning = () => { }) {
+    if (!isRecord(raw)) {
+        onWarning('panel must be an object');
+        return undefined;
+    }
+    const panel = {};
+    const labelsRaw = raw.labels;
+    if (labelsRaw !== undefined) {
+        if (!isRecord(labelsRaw)) {
+            onWarning('panel.labels must be an object');
+        }
+        else {
+            const labels = {};
+            for (const key of PANEL_LABEL_KEYS) {
+                const value = labelsRaw[key];
+                if (value === undefined)
+                    continue;
+                if (typeof value !== 'string') {
+                    onWarning('panel.labels.' + key + ' must be a string');
+                    continue;
+                }
+                const line = normalizeLine(value, 'label', onWarning);
+                if (line !== undefined)
+                    labels[key] = line.slice(0, VOICE_LABEL_MAX);
+            }
+            if (Object.keys(labels).length > 0)
+                panel.labels = labels;
+        }
+    }
+    const statsRaw = raw.stats;
+    if (statsRaw !== undefined) {
+        if (!isRecord(statsRaw)) {
+            onWarning('panel.stats must be an object');
+        }
+        else {
+            const stats = {};
+            for (const key of PANEL_STAT_KEYS) {
+                const value = statsRaw[key];
+                if (value === undefined)
+                    continue;
+                if (typeof value !== 'string') {
+                    onWarning('panel.stats.' + key + ' must be a string');
+                    continue;
+                }
+                const line = normalizeLine(value, 'stat', onWarning);
+                if (line !== undefined)
+                    stats[key] = line.slice(0, VOICE_STAT_MAX);
+            }
+            if (Object.keys(stats).length > 0)
+                panel.stats = stats;
+        }
+    }
+    const actionsRaw = raw.actions;
+    if (actionsRaw !== undefined) {
+        if (!Array.isArray(actionsRaw)) {
+            onWarning('panel.actions must be an array');
+        }
+        else {
+            const seen = new Set();
+            for (const entry of actionsRaw) {
+                if (typeof entry !== 'string' || !PANEL_ACTIONS.includes(entry)) {
+                    onWarning('unknown panel action dropped: ' + String(entry));
+                    continue;
+                }
+                seen.add(entry);
+            }
+            // Canonical order, deduplicated; an explicit empty array hides all.
+            panel.actions = PANEL_ACTIONS.filter(action => seen.has(action));
+        }
+    }
+    if (panel.labels === undefined && panel.stats === undefined && panel.actions === undefined)
+        return undefined;
+    return panel;
+}
+/** Voice-pack top-level fields ('$schema' mirrors the schema twin; drift-locked in tests). */
+export const VOICE_PACK_KEYS = new Set(['$schema', 'voicePackVersion', 'status', 'tools', 'toolRemaining', 'whispers', 'panel']);
+/** Allowed whisper-section fields (drift-locked in tests). */
+export const WHISPER_KEYS = new Set(['generic', 'rules']);
+/**
+ * Normalize one raw voice.json document into a VoicePack, or undefined when
+ * the file cannot serve as a pack at all (non-object root — structure is
+ * fail-closed per file). Every slot issue is a warning, never a throw.
+ */
+export function normalizeVoicePack(raw, onWarning = () => { }) {
+    if (raw === undefined)
+        return undefined;
+    if (!isRecord(raw)) {
+        onWarning('voice.json must be a JSON object; the file is ignored');
+        return undefined;
+    }
+    for (const key of Object.keys(raw)) {
+        if (!VOICE_PACK_KEYS.has(key))
+            onWarning('unknown top-level field ' + key + ' ignored');
+    }
+    const version = raw.voicePackVersion;
+    if (version !== undefined && (typeof version !== 'number' || version !== VOICE_PACK_V1)) {
+        onWarning('voicePackVersion ' + String(version) + ' is not supported; reading as v1 best-effort');
+    }
+    const overrides = {};
+    const statusRaw = raw.status;
+    if (statusRaw !== undefined) {
+        if (!isRecord(statusRaw)) {
+            onWarning('status must be an object');
+        }
+        else {
+            for (const key of Object.keys(statusRaw)) {
+                if (!STATUS_SCENES.includes(key)) {
+                    onWarning('unknown status scene ' + key + ' ignored');
+                    continue;
+                }
+                const pool = normalizePool(statusRaw[key], 'status', onWarning);
+                if (pool !== undefined && pool.length > 0) {
+                    overrides.status = { ...overrides.status, [key]: pool };
+                }
+            }
+        }
+    }
+    const toolsRaw = raw.tools;
+    if (toolsRaw !== undefined) {
+        if (!isRecord(toolsRaw)) {
+            onWarning('tools must be an object');
+        }
+        else {
+            for (const key of Object.keys(toolsRaw)) {
+                if (!TOOL_CATEGORIES.includes(key)) {
+                    onWarning('unknown tool family ' + key + ' ignored');
+                    continue;
+                }
+                const pool = normalizePool(toolsRaw[key], 'tools', onWarning);
+                if (pool !== undefined && pool.length > 0) {
+                    overrides.tools = { ...overrides.tools, [key]: pool };
+                }
+            }
+        }
+    }
+    const remainingRaw = raw.toolRemaining;
+    if (remainingRaw !== undefined) {
+        const pool = normalizePool(remainingRaw, 'toolRemaining', onWarning);
+        if (pool !== undefined && pool.length > 0)
+            overrides.toolRemaining = pool;
+    }
+    const whispersRaw = raw.whispers;
+    if (whispersRaw !== undefined) {
+        if (!isRecord(whispersRaw)) {
+            onWarning('whispers must be an object');
+        }
+        else {
+            for (const key of Object.keys(whispersRaw)) {
+                if (!WHISPER_KEYS.has(key))
+                    onWarning('unknown whispers field ' + key + ' ignored');
+            }
+            const generic = normalizePool(whispersRaw.generic, 'whisperGeneric', onWarning);
+            const rules = normalizeWhisperRules(whispersRaw.rules, onWarning);
+            if (generic !== undefined || rules !== undefined) {
+                overrides.whispers = {
+                    ...(generic === undefined ? {} : { generic }),
+                    ...(rules === undefined ? {} : { rules }),
+                };
+            }
+        }
+    }
+    const panel = raw.panel === undefined ? undefined : normalizePanel(raw.panel, onWarning);
+    if (overrides.status === undefined && overrides.tools === undefined
+        && overrides.toolRemaining === undefined && overrides.whispers === undefined
+        && panel === undefined) {
+        return undefined;
+    }
+    return {
+        overrides,
+        ...(panel === undefined ? {} : { panel }),
+    };
+}
+/**
+ * Merge voice-pack layers into one pack; later layers win per slot. The
+ * built-in pools are NOT a layer here — the chatter engines fall back to
+ * them per key at draw time. Merge order for a selected pet:
+ * mergeVoicePacks(registry.globalVoice, entry.voice).
+ */
+export function mergeVoicePacks(...layers) {
+    const overrides = {};
+    const labels = {};
+    const stats = {};
+    let actions;
+    let panelSeen = false;
+    let any = false;
+    for (const layer of layers) {
+        if (layer === undefined)
+            continue;
+        any = true;
+        if (layer.overrides.status !== undefined) {
+            overrides.status = { ...overrides.status, ...layer.overrides.status };
+        }
+        if (layer.overrides.tools !== undefined) {
+            overrides.tools = { ...overrides.tools, ...layer.overrides.tools };
+        }
+        if (layer.overrides.toolRemaining !== undefined)
+            overrides.toolRemaining = layer.overrides.toolRemaining;
+        if (layer.overrides.whispers !== undefined) {
+            overrides.whispers = { ...overrides.whispers, ...layer.overrides.whispers };
+        }
+        if (layer.panel !== undefined) {
+            panelSeen = true;
+            if (layer.panel.labels !== undefined)
+                Object.assign(labels, layer.panel.labels);
+            if (layer.panel.stats !== undefined)
+                Object.assign(stats, layer.panel.stats);
+            if (layer.panel.actions !== undefined)
+                actions = layer.panel.actions;
+        }
+    }
+    if (!any)
+        return undefined;
+    const panel = {
+        ...(Object.keys(labels).length > 0 ? { labels } : {}),
+        ...(Object.keys(stats).length > 0 ? { stats } : {}),
+        ...(actions === undefined ? {} : { actions }),
+    };
+    const panelEmpty = panel.labels === undefined && panel.stats === undefined && panel.actions === undefined;
+    return {
+        overrides,
+        ...(panelSeen && !panelEmpty ? { panel } : {}),
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@linxin666/dsh-pet",
   "description": "Multi-pet companion plugin for the dsh web GUI: a registry-driven floating pet that reacts to model activity, with per-pet naming, petting/feeding interactions and an affinity score",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "type": "module",
   "engines": {
     "node": "^22.19.0 || >=24.0.0"
@@ -31,7 +31,8 @@
     "lib/**/*.d.ts.map",
     "src",
     "cordis.patch.yml",
-    "assets"
+    "assets",
+    "contracts"
   ],
   "license": "Apache-2.0",
   "dsh": {
@@ -58,24 +59,26 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-session": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-settings": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.8",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^22.20.0",
     "@types/react": "~18.3.1",
     "@types/react-dom": "~18.3.0",
     "jsdom": "29.1.1",
+    "pixi.js": "^8.19.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "tsdown": "^0.22.2",
     "typescript": "^6.0.3",
+    "untitled-pixi-live2d-engine": "1.3.5",
     "vite-tsconfig-paths": "^6.1.1",
     "vitest": "^4.1.8"
   },

package/src/chatter.test.ts

@@ -14,6 +14,7 @@ import {
   WHISPER_GENERIC_POOL,
   WHISPER_RULES,
   WhisperEngine,
+  type VoicePackOverrides,
 } from './chatter.ts'
 
 describe('StatusVoice', () => {
@@ -139,7 +140,7 @@ describe('WhisperEngine', () => {
   })
 
   it('earns an ambient whisper from output volume alone', () => {
-    const engine = new WhisperEngine(0, 10)
+    const engine = new WhisperEngine(undefined, 0, 10)
     expect(engine.feed('aaaaaaaa', 0)).toBeUndefined()
     expect(engine.feed('bbbb', 1)).toBe(WHISPER_GENERIC_POOL[0])
     // The counter resets after speaking: another budget must accumulate.
@@ -148,7 +149,93 @@ describe('WhisperEngine', () => {
   })
 
   it('ignores empty chunks', () => {
-    const engine = new WhisperEngine(0, 0)
+    const engine = new WhisperEngine(undefined, 0, 0)
     expect(engine.feed('', 0)).toBeUndefined()
   })
 })
+
+describe('voice-pack overrides (pet-center M4)', () => {
+  const PACK = (): VoicePackOverrides => ({
+    status: {
+      done: ['自定义完工', '第二句完工'],
+      thinking: [],
+    },
+    tools: {
+      shell: ['敲命令 {hint}', '再来一次 {tool}'],
+    },
+    toolRemaining: ['后台还有 {n} 个'],
+    whispers: {
+      generic: ['自定义碎碎念 A', '自定义碎碎念 B'],
+      rules: [{ keywords: ['测试通过'], pool: ['自定义全绿'] }],
+    },
+  })
+
+  it('replaces a scene pool and keeps untouched scenes on the built-in pools', () => {
+    const voice = new StatusVoice(PACK)
+    expect(voice.scene('done', 0)).toBe('自定义完工')
+    expect(voice.scene('done', 5000)).toBe('第二句完工')
+    expect(voice.scene('thinking', 0)).toBe(STATUS_POOLS.thinking[0])
+  })
+
+  it('falls back to the built-in pool when the override pool is empty', () => {
+    const voice = new StatusVoice(PACK)
+    // PACK.thinking is an empty array: a scene line always renders.
+    expect(voice.scene('thinking', 0)).toBe(STATUS_POOLS.thinking[0])
+  })
+
+  it('interpolates placeholders from an overridden tool pool', () => {
+    const voice = new StatusVoice(PACK)
+    expect(voice.tool('bash', 'bash', 'npm test', 0)).toBe('敲命令 npm test')
+    const rotated = voice.tool('bash', 'bash', 'npm test', 5000)
+    expect(rotated).toBe('再来一次 bash')
+  })
+
+  it('uses an overridden remaining-tools pool', () => {
+    const voice = new StatusVoice(PACK)
+    expect(voice.toolRemaining(4, 0)).toBe('后台还有 4 个')
+  })
+
+  it('interpolates every occurrence of a repeated placeholder', () => {
+    const pack: ReturnType<typeof PACK> = {
+      ...PACK(),
+      tools: { shell: ['{tool} 和 {tool} 一起跑 {hint} {hint}'] },
+      toolRemaining: ['{n} 路并进，共 {n} 路'],
+    }
+    const voice = new StatusVoice(() => pack)
+    expect(voice.tool('bash', 'bash', 'npm test', 0)).toBe('bash 和 bash 一起跑 npm test npm test')
+    expect(voice.toolRemaining(2, 5000)).toBe('2 路并进，共 2 路')
+  })
+
+  it('follows a provider swap on the next draw without rebuilding the engine', () => {
+    let pack: ReturnType<typeof PACK> = PACK()
+    const voice = new StatusVoice(() => pack)
+    expect(voice.scene('done', 0)).toBe('自定义完工')
+    pack = { ...PACK(), status: { done: ['换声了'] } }
+    expect(voice.scene('done', 5000)).toBe('换声了')
+  })
+
+  it('replaces the whisper rules as a whole', () => {
+    const engine = new WhisperEngine(PACK)
+    expect(engine.feed('这里有一个错误', 0)).toBeUndefined()
+    // The built-in error rule is gone; only the pack's rule fires.
+    expect(engine.feed('测试通过', 1000)).toBe('自定义全绿')
+  })
+
+  it('replaces the ambient generic pool', () => {
+    const engine = new WhisperEngine(PACK, 0, 3)
+    expect(engine.feed('aaaa', 0)).toBe('自定义碎碎念 A')
+    expect(engine.feed('bbbb', 1)).toBe('自定义碎碎念 B')
+  })
+
+  it('mutes ambient whispers when the generic pool is explicitly empty', () => {
+    const engine = new WhisperEngine(() => ({ whispers: { generic: [] } }), 0, 3)
+    expect(engine.feed('aaaa', 0)).toBeUndefined()
+    expect(engine.feed('bbbb', 1)).toBeUndefined()
+  })
+
+  it('disables keyword rules when the rules array is explicitly empty', () => {
+    const engine = new WhisperEngine(() => ({ whispers: { rules: [] } }), 0, 3)
+    // No keyword rule matches anymore; volume still earns a built-in ambient.
+    expect(engine.feed('测试通过', 0)).toBe(WHISPER_GENERIC_POOL[0])
+  })
+})