@gobing-ai/knowledge-kit 0.0.9 → 0.0.11

package/plugins/generations/voice-gen/src/qc.ts

@@ -0,0 +1,157 @@
+import type { VoiceboxClient } from './voicebox-client';
+import type { VoiceScript, VoiceSegment } from './voicescript';
+
+export interface SegmentQualityAudit {
+    segmentIndex: number;
+    text: string;
+    duration: number;
+    expectedDurationRange: [number, number];
+    speechRateCharsPerSec: number;
+    transcription?: string;
+    repetitionDetected: boolean;
+    durationAnomaly: boolean;
+    issues: string[];
+    passed: boolean;
+}
+
+export interface VoiceQualityReport {
+    passed: boolean;
+    totalDuration: number;
+    overallScore: number; // 0 to 100
+    segmentAudits: SegmentQualityAudit[];
+    criticalIssues: string[];
+}
+
+/**
+ * Detects stuttering, repetitive loops, or mode collapse in text.
+ * E.g., "酒酒酒酒酒", "这种这种这种这种", "我会帮您收拾到最新的节目我会帮您收拾到最新的节目"
+ */
+export function detectRepetitions(text: string): boolean {
+    const trimmed = text.trim();
+    if (trimmed.length < 4) {
+        return false;
+    }
+
+    // 1. Single character repeated 3+ times (e.g. "酒酒酒" or "诶诶诶")
+    if (/(.)\1{2,}/u.test(trimmed)) {
+        return true;
+    }
+
+    // 2. 2-to-3 character word repeated 3+ times (e.g. "这种这种这种")
+    if (/(.{2,3}?)\1{2,}/u.test(trimmed)) {
+        return true;
+    }
+
+    // 3. 4-to-30 character phrase repeated 2+ times consecutively
+    if (/(.{4,30}?)\1{1,}/u.test(trimmed)) {
+        return true;
+    }
+
+    return false;
+}
+
+/**
+ * Compute expected speech duration range given text and language.
+ */
+export function computeExpectedDurationRange(text: string, language = 'zh'): [number, number] {
+    const cleanText = text.replace(/\[[^\]]+\]/g, '').trim(); // ignore [laugh] tags
+    const isZh = language.toLowerCase().startsWith('zh');
+
+    if (isZh) {
+        const charCount = cleanText.replace(/\s+/g, '').length;
+        const minSec = Math.max(1.0, charCount / 7.0);
+        const maxSec = Math.max(2.5, charCount / 2.2 + 2.5);
+        return [Number(minSec.toFixed(2)), Number(maxSec.toFixed(2))];
+    }
+
+    const wordCount = cleanText.split(/\s+/).filter(Boolean).length;
+    const minSec = Math.max(1.0, wordCount / 5.0);
+    const maxSec = Math.max(2.5, wordCount / 1.5 + 2.5);
+    return [Number(minSec.toFixed(2)), Number(maxSec.toFixed(2))];
+}
+
+/**
+ * Audit the quality of synthesized voice segments.
+ */
+export async function auditVoiceSegments(
+    script: VoiceScript,
+    segmentWavs: Uint8Array[],
+    segmentMetadata: Array<{ generationId: string; profile: string; duration: number }>,
+    client?: VoiceboxClient,
+): Promise<VoiceQualityReport> {
+    const audits: SegmentQualityAudit[] = [];
+    const criticalIssues: string[] = [];
+    let totalDuration = 0;
+
+    for (let i = 0; i < script.segments.length; i++) {
+        const segment = script.segments[i] as VoiceSegment;
+        const meta = segmentMetadata[i];
+        const wavBytes = segmentWavs[i];
+        const duration = meta?.duration ?? 0;
+        totalDuration += duration;
+
+        const lang = segment.language ?? script.language ?? 'zh';
+        const [minExpected, maxExpected] = computeExpectedDurationRange(segment.text, lang);
+        const cleanLen = segment.text.replace(/\s+/g, '').length;
+        const speechRate = duration > 0 ? cleanLen / duration : 0;
+
+        const issues: string[] = [];
+        let durationAnomaly = false;
+
+        // Check duration anomaly: duration exceeds 1.5x max expected or rate < 1.8 chars/sec on >= 8 chars
+        if (cleanLen >= 8 && (duration > maxExpected * 1.5 || speechRate < 1.8)) {
+            durationAnomaly = true;
+            issues.push(
+                `Duration anomaly: ${duration.toFixed(2)}s is unusually long for ${cleanLen} chars (expected ${minExpected}-${maxExpected}s, rate ${speechRate.toFixed(1)} chars/s)`,
+            );
+        }
+
+        let transcriptionText: string | undefined;
+        let repetitionDetected = false;
+
+        if (client && wavBytes && typeof client.transcribe === 'function') {
+            try {
+                const trans = await client.transcribe(wavBytes, lang);
+                transcriptionText = trans.text;
+                if (detectRepetitions(transcriptionText)) {
+                    repetitionDetected = true;
+                    issues.push(
+                        `Repetition hallucination detected in audio transcription: "${transcriptionText.slice(0, 80)}..."`,
+                    );
+                }
+            } catch {
+                // Transcription service unavailable or optional
+            }
+        }
+
+        const passed = !durationAnomaly && !repetitionDetected;
+        if (!passed) {
+            criticalIssues.push(`Segment ${i + 1} (${meta?.profile || 'Unknown'}): ${issues.join('; ')}`);
+        }
+
+        audits.push({
+            segmentIndex: i,
+            text: segment.text,
+            duration,
+            expectedDurationRange: [minExpected, maxExpected],
+            speechRateCharsPerSec: Number(speechRate.toFixed(2)),
+            transcription: transcriptionText,
+            repetitionDetected,
+            durationAnomaly,
+            issues,
+            passed,
+        });
+    }
+
+    const passedCount = audits.filter((a) => a.passed).length;
+    const overallScore = audits.length > 0 ? Math.round((passedCount / audits.length) * 100) : 100;
+    const allPassed = criticalIssues.length === 0;
+
+    return {
+        passed: allPassed,
+        totalDuration: Number(totalDuration.toFixed(2)),
+        overallScore,
+        segmentAudits: audits,
+        criticalIssues,
+    };
+}

package/plugins/generations/voice-gen/src/voicebox-client.ts

@@ -1,3 +1,9 @@
+export interface EffectConfig {
+    type: string;
+    enabled?: boolean;
+    params?: Record<string, number>;
+}
+
 export interface VoiceboxGenerateBody {
     profile_id: string;
     text: string;
@@ -6,8 +12,10 @@ export interface VoiceboxGenerateBody {
     instruct?: string;
     max_chunk_chars: number;
     crossfade_ms: number;
-    personality: false;
-    normalize: true;
+    personality?: boolean;
+    normalize?: boolean;
+    seed?: number | null;
+    effects_chain?: EffectConfig[] | null;
 }
 
 export interface VoiceboxProfile {
@@ -36,6 +44,7 @@ export interface VoiceboxClient {
         pollMs?: number,
     ): Promise<{ status: 'completed' | 'failed'; duration?: number; error?: string }>;
     downloadAudio(id: string): Promise<Uint8Array>;
+    transcribe(audio: Uint8Array, language?: string): Promise<{ text: string; duration?: number }>;
 }
 
 export interface VoiceboxClientOptions {
@@ -219,5 +228,34 @@ export function createVoiceboxClient(options: VoiceboxClientOptions = {}): Voice
                 throw new Error(`Voicebox /audio/${id} failed to read audio stream at ${url}: ${reason}`);
             }
         },
+
+        async transcribe(audio: Uint8Array, language = 'zh'): Promise<{ text: string; duration?: number }> {
+            const formData = new FormData();
+            const blob = new Blob([audio], { type: 'audio/wav' });
+            formData.append('file', blob, 'audio.wav');
+            formData.append('language', language);
+
+            let res: Response;
+            try {
+                res = await customFetch(`${url}/transcribe`, {
+                    method: 'POST',
+                    body: formData,
+                });
+            } catch (err: unknown) {
+                const reason = err instanceof Error ? err.message : String(err);
+                throw new Error(`Voicebox /transcribe request failed at ${url}: ${reason}`);
+            }
+
+            if (!res.ok) {
+                throw new Error(`Voicebox /transcribe failed at ${url}: HTTP ${res.status} ${res.statusText}`);
+            }
+
+            try {
+                return (await res.json()) as { text: string; duration?: number };
+            } catch (err: unknown) {
+                const reason = err instanceof Error ? err.message : String(err);
+                throw new Error(`Voicebox /transcribe returned invalid JSON at ${url}: ${reason}`);
+            }
+        },
     };
 }

package/plugins/generations/voice-gen/src/voicescript.ts

@@ -1,4 +1,5 @@
 import type { Doc } from '@gobing-ai/kk-core';
+import type { EffectConfig } from './voicebox-client';
 
 export const VOICEBOX_TEXT_MAX = 50_000;
 export const VOICEBOX_INSTRUCT_MAX = 500;
@@ -45,6 +46,43 @@ export const VOICEBOX_LANGUAGES = [
     'tr',
 ] as const;
 
+export const BUILTIN_EFFECT_PRESETS: Record<string, EffectConfig[]> = {
+    robotic: [
+        {
+            type: 'chorus',
+            enabled: true,
+            params: { rate_hz: 0.2, depth: 1.0, feedback: 0.35, centre_delay_ms: 7.0, mix: 0.5 },
+        },
+    ],
+    radio: [
+        { type: 'highpass', enabled: true, params: { cutoff_frequency_hz: 300.0 } },
+        { type: 'lowpass', enabled: true, params: { cutoff_frequency_hz: 3500.0 } },
+        {
+            type: 'compressor',
+            enabled: true,
+            params: { threshold_db: -15.0, ratio: 6.0, attack_ms: 5.0, release_ms: 50.0 },
+        },
+        { type: 'gain', enabled: true, params: { gain_db: 6.0 } },
+    ],
+    'echo chamber': [
+        {
+            type: 'reverb',
+            enabled: true,
+            params: { room_size: 0.85, damping: 0.3, wet_level: 0.45, dry_level: 0.55, width: 1.0 },
+        },
+        { type: 'delay', enabled: true, params: { delay_seconds: 0.25, feedback: 0.3, mix: 0.2 } },
+    ],
+    'deep voice': [
+        { type: 'pitch_shift', enabled: true, params: { semitones: -3.0 } },
+        { type: 'lowpass', enabled: true, params: { cutoff_frequency_hz: 6000.0 } },
+        {
+            type: 'compressor',
+            enabled: true,
+            params: { threshold_db: -18.0, ratio: 3.0, attack_ms: 10.0, release_ms: 150.0 },
+        },
+    ],
+};
+
 const ENGINE_SET = new Set<string>(VOICEBOX_ENGINES);
 const LANGUAGE_SET = new Set<string>(VOICEBOX_LANGUAGES);
 
@@ -60,23 +98,67 @@ function assertLanguage(value: string | undefined, label: string): void {
     }
 }
 
+export function resolveEffectsChain(customChain?: EffectConfig[], presetName?: string): EffectConfig[] | undefined {
+    if (customChain && customChain.length > 0) {
+        return customChain;
+    }
+    if (presetName) {
+        const normalized = presetName.trim().toLowerCase();
+        const preset = BUILTIN_EFFECT_PRESETS[normalized];
+        if (preset) {
+            return preset;
+        }
+    }
+    return undefined;
+}
+
+export function resolveInstruct(instruct?: string, emotion?: string): string | undefined {
+    if (instruct && emotion) {
+        const lower = instruct.toLowerCase();
+        if (lower.includes(emotion.toLowerCase())) {
+            return instruct;
+        }
+        return `${instruct}. Emotion: ${emotion}`;
+    }
+    if (instruct) {
+        return instruct;
+    }
+    if (emotion) {
+        return `Speak in a ${emotion} tone.`;
+    }
+    return undefined;
+}
+
 export interface VoiceSpeaker {
-    profile: string;
+    profile?: string;
+    profile_id?: string;
+    name?: string;
+    role?: string;
     engine?: string;
     language?: string;
+    emotion?: string;
     instruct?: string;
+    effects_chain?: EffectConfig[];
+    effect_preset?: string;
+    personality?: boolean;
 }
 
 export interface VoiceSegment {
     speaker?: string;
     profile?: string;
+    profile_id?: string;
     text: string;
+    emotion?: string;
     instruct?: string;
     engine?: string;
     language?: string;
     gap_ms?: number;
     max_chunk_chars?: number;
     crossfade_ms?: number;
+    personality?: boolean;
+    seed?: number;
+    effects_chain?: EffectConfig[];
+    effect_preset?: string;
 }
 
 export interface VoiceScript {
@@ -84,13 +166,26 @@ export interface VoiceScript {
     language?: string;
     default_engine?: string;
     default_profile?: string;
+    default_profile_id?: string;
+    default_emotion?: string;
+    default_effects_chain?: EffectConfig[];
+    default_effect_preset?: string;
     max_chunk_chars?: number;
     crossfade_ms?: number;
     speakers?: Record<string, VoiceSpeaker>;
     segments: VoiceSegment[];
 }
 
-const VOICESCRIPT_KEYS = new Set(['segments', 'speakers', 'default_profile', 'default_engine']);
+const VOICESCRIPT_KEYS = new Set([
+    'segments',
+    'speakers',
+    'default_profile',
+    'default_profile_id',
+    'default_engine',
+    'default_emotion',
+    'default_effects_chain',
+    'default_effect_preset',
+]);
 
 /**
  * Parse a Doc into a VoiceScript structure.
@@ -107,7 +202,11 @@ export function parseDocToVoiceScript(doc: Doc, envDefaultProfile?: string): Voi
         try {
             parsed = JSON.parse(trimmed);
         } catch {
-            throw new Error('Invalid VoiceScript JSON structure: failed to parse JSON object');
+            try {
+                parsed = Bun.YAML.parse(trimmed);
+            } catch {
+                throw new Error('Invalid VoiceScript JSON structure: failed to parse JSON object');
+            }
         }
         if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
             throw new Error('Invalid VoiceScript JSON structure: root must be a JSON object');
@@ -115,13 +214,17 @@ export function parseDocToVoiceScript(doc: Doc, envDefaultProfile?: string): Voi
         return parsed as VoiceScript;
     }
 
-    if (trimmed.startsWith('[')) {
-        return {
-            segments: [{ text: trimmed }],
-            default_profile:
-                envDefaultProfile ??
-                (typeof doc.metadata?.voiceProfile === 'string' ? doc.metadata.voiceProfile : undefined),
-        };
+    if (trimmed.startsWith('[') && !trimmed.startsWith('[-')) {
+        // Plain text starting with paralinguistic tag e.g. [laugh] or [sigh]
+        const hasYamlStructure = trimmed.includes('segments:') || trimmed.includes('speakers:');
+        if (!hasYamlStructure) {
+            return {
+                segments: [{ text: trimmed }],
+                default_profile:
+                    envDefaultProfile ??
+                    (typeof doc.metadata?.voiceProfile === 'string' ? doc.metadata.voiceProfile : undefined),
+            };
+        }
     }
 
     try {
@@ -161,7 +264,11 @@ export function mergeVoiceScripts(scripts: VoiceScript[], docs: Doc[], envDefaul
 
     let title: string | undefined;
     let defaultProfile: string | undefined = envDefaultProfile;
+    let defaultProfileId: string | undefined;
     let defaultEngine: string | undefined;
+    let defaultEmotion: string | undefined;
+    let defaultEffectsChain: EffectConfig[] | undefined;
+    let defaultEffectPreset: string | undefined;
     let language: string | undefined;
     let maxChunkChars: number | undefined;
     let crossfadeMs: number | undefined;
@@ -179,12 +286,24 @@ export function mergeVoiceScripts(scripts: VoiceScript[], docs: Doc[], envDefaul
         if (script.default_profile && defaultProfile === envDefaultProfile) {
             defaultProfile = script.default_profile;
         }
+        if (script.default_profile_id && !defaultProfileId) {
+            defaultProfileId = script.default_profile_id;
+        }
         if (!defaultProfile && typeof doc?.metadata?.voiceProfile === 'string') {
             defaultProfile = doc.metadata.voiceProfile;
         }
         if (!defaultEngine && script.default_engine) {
             defaultEngine = script.default_engine;
         }
+        if (!defaultEmotion && script.default_emotion) {
+            defaultEmotion = script.default_emotion;
+        }
+        if (!defaultEffectsChain && script.default_effects_chain) {
+            defaultEffectsChain = script.default_effects_chain;
+        }
+        if (!defaultEffectPreset && script.default_effect_preset) {
+            defaultEffectPreset = script.default_effect_preset;
+        }
         if (!language && script.language) {
             language = script.language;
         }
@@ -220,9 +339,21 @@ export function mergeVoiceScripts(scripts: VoiceScript[], docs: Doc[], envDefaul
     if (defaultProfile) {
         result.default_profile = defaultProfile;
     }
+    if (defaultProfileId) {
+        result.default_profile_id = defaultProfileId;
+    }
     if (defaultEngine) {
         result.default_engine = defaultEngine;
     }
+    if (defaultEmotion) {
+        result.default_emotion = defaultEmotion;
+    }
+    if (defaultEffectsChain) {
+        result.default_effects_chain = defaultEffectsChain;
+    }
+    if (defaultEffectPreset) {
+        result.default_effect_preset = defaultEffectPreset;
+    }
     if (language) {
         result.language = language;
     }
@@ -282,8 +413,8 @@ export function validateVoiceScript(script: VoiceScript): void {
             if (!speaker || typeof speaker !== 'object') {
                 throw new Error(`Speaker "${name}" definition must be an object`);
             }
-            if (!speaker.profile || typeof speaker.profile !== 'string') {
-                throw new Error(`Speaker "${name}" must have a profile specified`);
+            if (!speaker.profile && !speaker.profile_id) {
+                throw new Error(`Speaker "${name}" must have a profile or profile_id specified`);
             }
             if (
                 speaker.instruct &&
@@ -359,6 +490,12 @@ export function validateVoiceScript(script: VoiceScript): void {
             }
         }
 
+        if (segment.seed !== undefined) {
+            if (typeof segment.seed !== 'number' || !Number.isInteger(segment.seed) || segment.seed < 0) {
+                throw new Error('seed must be a non-negative integer');
+            }
+        }
+
         assertEngine(segment.engine, `Segment at index ${idx}`);
         assertLanguage(segment.language, `Segment at index ${idx}`);
     }

package/plugins/kk/README.md

@@ -4,7 +4,7 @@ This directory is the **only** home for knowledge-kit agent capabilities (ADR-00
 It is a Claude Code / Superskill plugin, **not** a kk-core product plugin.
 
 | Path | Holds |
-|------|--------|
+| ------ | -------- |
 | `skills/` | Fat skills (`SKILL.md`) |
 | `commands/` | Thin slash-command wrappers |
 | `agents/` | Thin subagent wrappers (currently empty — see below) |
@@ -24,5 +24,5 @@ Install: `superskill install kk`.
 
 Capability files **omit a leading `kk-`**. `superskill install` prefixes the plugin name, so
 `skills/content-judge` installs as `kk:content-judge` (not `kk:kk-content-judge`). Same for `topic`,
-`storm-research`, `itc-generating`, and `/workflow-run`. Product workflow YAML (`kk-storm-research.yaml`)
+`storm-research`, `itc-generating`, `explain-things` (via `/tell-me`), and `/workflow-run`. Product workflow YAML (`kk-storm-research.yaml`)
 keeps its existing name — that is a workflow stem, not an installable agent capability.

package/plugins/kk/commands/tell-me.md

@@ -0,0 +1,16 @@
+---
+name: tell-me
+description: Explain the supplied or current topic with the smallest useful view; use ELI5 only when requested.
+argument-hint: "[topic] [--eli5]"
+allowed-tools: ["Skill"]
+---
+
+# tell-me
+
+Thin wrapper for the `explain-things` skill — all explanation and view-selection logic lives in
+the skill. Forward `$ARGUMENTS` unchanged, including empty arguments (the skill owns
+conversation-topic fallback).
+
+```text
+Skill(skill="kk:explain-things", args="$ARGUMENTS")
+```