@gobing-ai/knowledge-kit 0.0.14 → 0.0.16

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
     },
     "plugins": [
         {
-            "version": "0.0.14",
+            "version": "0.0.16",
             "name": "kk",
             "source": "./plugins/kk",
             "description": "knowledge-kit — a set of toolkit for knowledge management"

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/knowledge-kit",
-    "version": "0.0.14",
+    "version": "0.0.16",
     "description": "An ingest → create → publish content pipeline CLI (Bun).",
     "repository": {
         "type": "git",

package/plugins/generations/omni-voice-gen/README.md

@@ -2,14 +2,17 @@
 
 OmniVoice-backed voice generator plugin for [knowledge-kit](../../../README.md).
 Drop-in replacement for `voice-gen` — same `kk executor run` contract (`--in Doc[] --out Content`),
-same audio metadata shape, same QC pipeline. Swap the backend in `kk-daily-ai-voice` with:
+same audio metadata shape, same QC pipeline. `kk-daily-ai-voice` selects it by default via the
+`voice_generator` var; fall back to the Voicebox backend with:
 
 ```bash
 spur workflow run plugins/kk/workflows/kk-daily-ai-voice.yaml \
-  --vars '{"voice_generator":"omni-voice-gen"}'   # other vars per your kk config
+  --vars '{"voice_generator":"voice-gen"}'   # other vars per your kk config
 ```
 
-The default `voice_generator` is `voice-gen` (production behavior unchanged; swap is operator opt-in).
+> **Voice identity:** the shipped `robin-news` profile is an instruct placeholder. For a real
+> operator voice, record a 3–10 s clip into a private registry (`OMNIVOICE_PROFILE_REGISTRY`)
+> and it supersedes the committed entry.
 
 ## Setup
 
@@ -23,6 +26,9 @@ make sync          # runs `uv sync` — creates .venv, installs omnivoice from P
 > (~2–4 GB depending on device). The Whisper ASR model used for transcription-fidelity QC loads
 > lazily on the first QC transcription (`OMNIVOICE_ASR_MODEL` overrides it). Subsequent runs
 > use the HF cache. `OMNIVOICE_MODEL` overrides the model id or points to a local checkout.
+> If the cached-model revalidation hang blocks a run (observed on flaky networks), set
+> `HF_HUB_OFFLINE=1` once the model is cached — the plugin only needs the hub for the
+> first pull.
 > GPU (`cuda`) is auto-selected when available; MPS (Apple Silicon) and CPU are fallbacks.
 > Set `OMNIVOICE_DEVICE` to override (e.g. `cpu` for CI).
 

package/plugins/generations/omni-voice-gen/profiles.json

@@ -1,4 +1,8 @@
 {
+    "robin-news": {
+        "ref_audio": "voices/robin-news.wav",
+        "ref_text": "本届赛事由北京市人民政府、中央广播电视总台、世界机器人合作组织、亚太机器人世界杯国际理事会联合主办。来自六大洲 16 个国家的 666 支队伍、2056 台机器人参赛，队伍数量较首届增长 138%，机器人"
+    },
     "sample-clone": {
         "ref_audio": "voices/sample-ref.wav",
         "ref_text": "Replace with the transcript of your reference clip."
@@ -7,6 +11,6 @@
         "prompt": "voices/sample-prompt.pt"
     },
     "sample-narrator": {
-        "instruct": "Speak in a calm, measured narrator voice."
+        "instruct": "male, middle-aged, low pitch"
     }
 }

package/plugins/generations/omni-voice-gen/src/omni_voice_gen/backend.py

@@ -19,6 +19,15 @@ from .profiles import ProfileEntry
 
 DEFAULT_MODEL = "k2-fsa/OmniVoice"
 SAMPLE_RATE = 24000  # OmniVoice output rate; ASR transcribe is fixed at 24000 (task R4)
+_ASR_CHUNK_SECONDS = 28.0  # ponytail: Whisper errors on >30s inputs; fixed chunks, silence-aware split if boundary words hurt fidelity
+
+
+def _chunk_for_asr(audio: np.ndarray) -> list[np.ndarray]:
+    """Split a waveform into <=30s slices the upstream Whisper pipe accepts."""
+    chunk = int(_ASR_CHUNK_SECONDS * SAMPLE_RATE)
+    if len(audio) <= chunk:
+        return [audio]
+    return [audio[i : i + chunk] for i in range(0, len(audio), chunk)]
 
 
 class SegmentSpec(TypedDict):
@@ -147,4 +156,6 @@ class OmnivoiceBackend:
         if not self._asr_loaded:
             self._model.load_asr_model(model_name=self._asr_model)
             self._asr_loaded = True
-        return str(self._model.transcribe((_wav_to_float(wav), SAMPLE_RATE)))
+        audio = _wav_to_float(wav)
+        parts = [str(self._model.transcribe((part, SAMPLE_RATE))) for part in _chunk_for_asr(audio)]
+        return " ".join(part for part in parts if part)

package/plugins/generations/omni-voice-gen/src/omni_voice_gen/pipeline.py

@@ -39,7 +39,6 @@ from .voicescript import (
     WarnSink,
     merge_voice_scripts,
     parse_doc_to_voicescript,
-    resolve_instruct,
     validate_voice_script,
 )
 
@@ -51,6 +50,10 @@ def _log(msg: str) -> None:
     print(f"omni-voice-gen: {msg}", file=sys.stderr)
 
 
+# Emotions already warned about this run (one line per distinct value, not per segment).
+_ignored_emotions: set[str] = set()
+
+
 def _delete(*paths: str) -> None:
     for path in paths:
         Path(path).unlink(missing_ok=True)
@@ -188,11 +191,24 @@ def _render(
         speaker = (script.speakers or {}).get(segment.speaker) if segment.speaker else None
         profile = resolve_profile_target(segment, speaker, script, env_default, docs)
         emotion = _first(segment.emotion, getattr(speaker, "emotion", None), script.default_emotion)
+        # OmniVoice instruct accepts a fixed vocabulary (accent/age/pitch) with no emotion items,
+        # so voicegen-era free-text emotion is unrepresentable: drop it loudly and let the
+        # resolved profile's instruct carry the voice. An explicit segment/speaker instruct is
+        # operator-authored whitelist text and passes through untouched.
+        segment_instruct = _first(segment.instruct, getattr(speaker, "instruct", None))
+        if segment_instruct is None and emotion is not None:
+            key = emotion.strip().lower()
+            if key not in _ignored_emotions:
+                _ignored_emotions.add(key)
+                _log(
+                    f"ignoring emotion {emotion!r}: OmniVoice instruct vocabulary has no emotion items — "
+                    "voice comes from the resolved profile"
+                )
         spec: SegmentSpec = {
             "text": segment.text,
             "language": _first(segment.language, getattr(speaker, "language", None), script.language, "en"),
             "profile": resolve_profile(profile, registry),
-            "instruct": resolve_instruct(_first(segment.instruct, getattr(speaker, "instruct", None)), emotion),
+            "instruct": segment_instruct,
             "seed": None if segment.seed is None else int(segment.seed),
             "speed": None,
         }

package/plugins/generations/omni-voice-gen/src/omni_voice_gen/profiles.py

@@ -83,6 +83,14 @@ def load_registry(path: Path | None = None) -> ProfileRegistry:
             f"profile registry at {path} must be a JSON object mapping profile names to entries"
         )
     entries = {name: _parse_entry(name, spec) for name, spec in data.items()}
+    # Resolve relative asset paths against the registry's directory so backend passes
+    # absolute paths to the engine regardless of process CWD.
+    base = path.resolve().parent
+    for entry in entries.values():
+        if entry.ref_audio and not Path(entry.ref_audio).is_absolute():
+            entry.ref_audio = str((base / entry.ref_audio).resolve())
+        if entry.prompt and not Path(entry.prompt).is_absolute():
+            entry.prompt = str((base / entry.prompt).resolve())
     lowered = [key.lower() for key in entries]
     if len(set(lowered)) != len(lowered):
         dupes = sorted({key for key in entries if lowered.count(key.lower()) > 1})

package/plugins/generations/omni-voice-gen/src/omni_voice_gen/voicescript.py

@@ -338,15 +338,3 @@ def validate_voice_script(script: VoiceScript, sink: WarnSink) -> None:
             raise ValueError("seed must be a non-negative integer")
 
         _collect_ignored(segment, f"segments[{idx}]", sink)
-
-
-def resolve_instruct(instruct: str | None = None, emotion: str | None = None) -> str | None:
-    if instruct and emotion:
-        if emotion.lower() in instruct.lower():
-            return instruct
-        return f"{instruct}. Emotion: {emotion}"
-    if instruct:
-        return instruct
-    if emotion:
-        return f"Speak in a {emotion} tone."
-    return None

package/plugins/kk/commands/workflow-run.md

@@ -2,8 +2,8 @@
 name: workflow-run
 description: >-
   Run STORM daily research, IT content authoring, or solo-podcast end to end.
-  Resolves the workflow YAML from the user override, KK_WORKFLOWS_SOURCE, the
-  installed kk package root, or a repo checkout — runs in place from any cwd;
+  Resolves the workflow YAML from the user override, KK_WORKFLOWS_SOURCE, bun/npm
+  global installs, the kk package root, or a repo checkout — runs in place from any cwd;
   creates the config with defaults if missing; computes the workspace; shells
   spur workflow run against the resolved YAML.
 argument-hint: "[name] <topic|--in file> [--dir <path>] [--playbook generic|english|wechat] [--research] [--judge] [--outline <a|b|c>] [--writer itc-generating|topic] [--duration <min>] [--language <code>] [--script-approved] [--fixture] [--force]"
@@ -13,8 +13,9 @@ Thin runner around the **storm-research**, **itc-generating** / **topic**, and *
 capabilities. Read `plugins/kk/skills/storm-research/SKILL.md` or
 `plugins/kk/skills/itc-generating/SKILL.md` for craft; solo-podcast craft lives in the
 `audio-authoring` skill. This command owns the run procedure: config create,
-workflow YAML resolution (user override → `$KK_WORKFLOWS_SOURCE` → **installed package
-root** → repo checkout, runs in place from any cwd), workspace computation, and the
+workflow YAML resolution (user override → `$KK_WORKFLOWS_SOURCE` → **bun/npm global
+install** → **installed package root** → repo checkout, runs in place from any cwd), workspace
+computation, and the
 `spur workflow run` of the resolved YAML. Design-time SSOT remains
 `plugins/kk/workflows/` in the package/repo. No new `kk` CLI noun (ADR-011) — everything here
 is shell + the workflow.
@@ -30,12 +31,13 @@ Parse per the frozen rule:
   `kk-storm-research` (default), `kk-itc`, `kk-solo-podcast`. Any other name after successful copy → exit 1 listing
   `kk-storm-research`, `kk-itc`, `kk-solo-podcast`.
 - `--in <file>` → file mode. `--force` → overwrite an existing dest YAML / existing `brief.md`.
-- Profile `kk-storm-research`: `--fixture` → force `fixture: "true"`.
-- Profile `kk-itc`: `--dir <path>` (default `./<kebab>`), `--playbook generic|english|wechat` (default `generic`),
+- Profile `kk-storm-research`: `--dir <path>` (default `$works_dir/kk-storm-research/<topic-id>`),
+  `--fixture` → force `fixture: "true"`.
+- Profile `kk-itc`: `--dir <path>` (default `$works_dir/kk-itc/<kebab>`), `--playbook generic|english|wechat` (default `generic`),
   `--research` (`true`|`false`, default `false`), `--judge` (`true`|`false`, default `false`),
   `--outline <a|b|c>` (default empty), `--writer itc-generating|topic` (default `itc-generating`).
   `--fixture` passed with `kk-itc` or `kk-solo-podcast` → exit 1 (`fixture is storm-only`).
-- Profile `kk-solo-podcast`: `--dir <path>` (default `$works_dir/<kebab>`), `--outline <a|b|c>`
+- Profile `kk-solo-podcast`: `--dir <path>` (default `$works_dir/kk-solo-podcast/<date>`), `--outline <a|b|c>`
   (default empty), `--duration <min>` (default `8`), `--language <code>` (default `en`),
   `--script-approved` (sets `script_approved=true`; default off). `--fixture` is storm-only.
 - **XOR:** exactly one of `<topic>` / `--in <file>`. Both set or both empty → exit 1, stderr
@@ -90,6 +92,19 @@ while [ -L "$kbin" ]; do
   case "$link" in /*) kbin="$link";; *) kbin="$(dirname "$kbin")/$link";; esac
 done
 pkg=""; [ -n "$kbin" ] && pkg="$(cd "$(dirname "$kbin")/.." 2>/dev/null && pwd || true)"
+# Global-install roots — the common no-config case (package installed with `bun install -g`
+# or `npm i -g` and no `workflows_dir` written yet). Each probe is guarded, so a missing
+# package manager never breaks the chain.
+bun_global_workflows=""
+if command -v bun >/dev/null 2>&1; then
+  bg="$(dirname "$(bun pm bin -g 2>/dev/null)")/install/global/node_modules/@gobing-ai/knowledge-kit/plugins/kk/workflows"
+  [ -d "$bg" ] && bun_global_workflows="$bg"
+fi
+npm_global_workflows=""
+if command -v npm >/dev/null 2>&1; then
+  ng="$(dirname "$(npm root -g 2>/dev/null)")/node_modules/@gobing-ai/knowledge-kit/plugins/kk/workflows"
+  [ -d "$ng" ] && npm_global_workflows="$ng"
+fi
 ```
 
 Resolution order — first hit wins:
@@ -97,26 +112,31 @@ Resolution order — first hit wins:
 1. **User override** `$workflows_dir/$NAME.yaml` (default `~/.config/kk/workflows/`) —
    when it exists it always wins, and nothing is copied.
 2. `$KK_WORKFLOWS_SOURCE/$NAME.yaml`
-3. `$pkg/plugins/kk/workflows/$NAME.yaml` — the installed package copy
-4. `plugins/kk/workflows/$NAME.yaml` — repo checkout (development)
+3. **bun global install** — `$(dirname $(bun pm bin -g))/install/global/node_modules/@gobing-ai/knowledge-kit/plugins/kk/workflows/$NAME.yaml`
+4. **npm global install** — `$(dirname $(npm root -g))/node_modules/@gobing-ai/knowledge-kit/plugins/kk/workflows/$NAME.yaml`
+5. `$pkg/plugins/kk/workflows/$NAME.yaml` — the installed package copy (resolved from the `kk` binary)
+6. `plugins/kk/workflows/$NAME.yaml` — repo checkout (development)
+
+A corrupt `config.yaml` already exited 1 in step 2; none of these probes runs before that check,
+so no fallback masks a config error.
 
 ```bash
 dest=""
 if [ -f "$workflows_dir/$NAME.yaml" ]; then
   dest="$workflows_dir/$NAME.yaml"
 else
-  for d in "$KK_WORKFLOWS_SOURCE" ${pkg:+"$pkg/plugins/kk/workflows"} "plugins/kk/workflows"; do
+  for d in "$KK_WORKFLOWS_SOURCE" "$bun_global_workflows" "$npm_global_workflows" ${pkg:+"$pkg/plugins/kk/workflows"} "plugins/kk/workflows"; do
     [ -n "$d" ] && [ -f "$d/$NAME.yaml" ] && { dest="$d/$NAME.yaml"; break; }
   done
-  [ -z "$dest" ] && { echo "no source workflow for $NAME (searched $workflows_dir, KK_WORKFLOWS_SOURCE, kk package root, plugins/kk/workflows)" >&2; exit 1; }
+  [ -z "$dest" ] && { echo "no source workflow for $NAME (searched $workflows_dir, KK_WORKFLOWS_SOURCE, bun/npm global installs, kk package root, plugins/kk/workflows)" >&2; exit 1; }
 fi
 # --force: refresh the user override from the best available source, then run the override.
 if [ "$FORCE" = true ]; then
   src=""
-  for d in "$KK_WORKFLOWS_SOURCE" ${pkg:+"$pkg/plugins/kk/workflows"} "plugins/kk/workflows"; do
+  for d in "$KK_WORKFLOWS_SOURCE" "$bun_global_workflows" "$npm_global_workflows" ${pkg:+"$pkg/plugins/kk/workflows"} "plugins/kk/workflows"; do
     [ -n "$d" ] && [ -f "$d/$NAME.yaml" ] && { src="$d/$NAME.yaml"; break; }
   done
-  [ -z "$src" ] && { echo "no source workflow for $NAME to force-install (searched KK_WORKFLOWS_SOURCE, kk package root, plugins/kk/workflows)" >&2; exit 1; }
+  [ -z "$src" ] && { echo "no source workflow for $NAME to force-install (searched KK_WORKFLOWS_SOURCE, bun/npm global installs, kk package root, plugins/kk/workflows)" >&2; exit 1; }
   install -d "$workflows_dir" && cp "$src" "$workflows_dir/$NAME.yaml"
   dest="$workflows_dir/$NAME.yaml"
 fi
@@ -126,9 +146,11 @@ fi
   `--force` to place a fresh copy there) — that override wins on every later run.
 - No auto-copy, no drift warnings: the package copy is versioned with the CLI and
   never goes stale; overrides are explicit.
-- Sidecars (`validate-voicescript.ts`, `wrap-voicescript-doc.ts`) are **not copied** —
-  the workflow's own fallback chain resolves them via `$KK_WORKFLOWS_DIR`, the package
-  root, then `$HOME/.config/kk/workflows`.
+- Sidecars (`plugins/kk/scripts/kk-workflow-stages.ts`, plus the
+  `validate-voicescript.ts` / `wrap-voicescript-doc.ts` it delegates to) are **not copied** —
+  the workflow resolves the stage runner from the package root, and the runner resolves each
+  sidecar via the explicit var, `$KK_WORKFLOWS_DIR`, the package copy, then
+  `$HOME/.config/kk/workflows`.
 
 ## 4. Compute workspace
 
@@ -143,7 +165,7 @@ slug=$(printf '%s' "$normalized" | tr -cs 'a-z0-9' '-' | sed 's/^-*//; s/-*$//'
 [ -z "$slug" ] && slug="topic"
 hash=$(printf '%s' "$normalized" | shasum -a 256 | cut -c1-8)
 topic_id="${slug}-${hash}"
-work_dir="$works_dir/$topic_id"
+work_dir="${DIR:-$works_dir/kk-storm-research/$topic_id}"
 ```
 
 - `raw` derives empty (no H1 and empty basename) → exit 1 with the derived value.
@@ -157,15 +179,24 @@ mkdir -p "$work_dir"
 
 `raw` = `TOPIC` or file-mode first ATX H1 else basename without extension.
 `kebab` = lower-case, `[^a-z0-9]+` → `-`, trimmed dashes (no length cap, no sha256 hash).
-`work_dir="${DIR:-./$kebab}"`. Empty derived `kebab` → exit 1.
+`work_dir="${DIR:-$works_dir/kk-itc/$kebab}"`. Empty derived `kebab` → exit 1. An explicit
+`--dir` still wins, and the default never writes into the caller's cwd.
 
-### Profile `kk-solo-podcast` / `kk-daily-ai-voice`
+### Profile `kk-solo-podcast`
 
 `date` = today's date in `YYYY-MM-DD` (`$(date +%Y-%m-%d)`).
 `raw` = `TOPIC` or file-mode first ATX H1 else basename without extension.
 `kebab` = lower-case, `[^a-z0-9]+` → `-`, trimmed dashes (no length cap, no sha256 hash).
 `work_dir="${DIR:-$works_dir/kk-solo-podcast/$date}"`.
 
+### Profile `kk-daily-ai-voice`
+
+Same `date` / `raw` / `kebab` derivation as `kk-solo-podcast`.
+`work_dir="${DIR:-$works_dir/kk-daily-ai-voice/$date}"`.
+
+Every profile's default puts its workspace in **its own** `$works_dir/<workflow-name>/` namespace;
+an explicit `--dir` overrides all four defaults.
+
 ## 5. Run the workflow
 
 All values are strings.
@@ -216,9 +247,10 @@ spur workflow run "$dest" --vars \
   and `$work_dir/content.json` (machine contract). Skim `content.md` citations against `docs.json`
   ids before presenting.
 - **`kk-itc`**: print resolved `work_dir`, then `$work_dir/brief.md`, `$work_dir/2-outline/outline-approved.md`,
-  and `$work_dir/3-draft/draft-article.md`. If `judge=true`, also print the verdict path.
-- **`kk-solo-podcast`**: print resolved `work_dir`, then `$work_dir/3-script/voicescript.yaml`,
-  `$work_dir/4-audio/content.json`, and `$work_dir/4-audio/content.wav`.
+  and `$work_dir/3-draft-draft-article.md`. If `judge=true`, also print the verdict path.
+- **`kk-solo-podcast`**: print resolved `work_dir`, then `$work_dir/1-briefing-briefing.md`,
+  `$work_dir/3-script-voicescript.yaml`, `$work_dir/4-audio/content.json`, and
+  `$work_dir/4-audio/content.wav`.
 
 If the run ended `failed`, show the failing state (`spur workflow trace <run-id> --json`) and the
 fail-loud recovery line.

package/plugins/kk/config.example.yaml

@@ -1,3 +1,8 @@
+# kk operator config. `works_dir` is the run-workspace root — each workflow run defaults
+# to <works_dir>/<workflow-name>/<run-id> unless --dir is given (existing `.works/`-era
+# trees are not migrated). `workflows_dir` is the user-override root for workflow YAMLs;
+# when a workflow is not found there, /workflow-run falls back to KK_WORKFLOWS_SOURCE,
+# bun/npm global installs, the kk package root, then the repo checkout.
 works_dir: "~/.config/kk/works"
 workflows_dir: "~/.config/kk/workflows"
 defaults:

package/plugins/kk/plugin.json

@@ -1,5 +1,5 @@
 {
     "name": "kk",
-    "version": "0.0.14",
+    "version": "0.0.16",
     "description": "knowledge-kit Claude Code plugin: skills, commands, subagents, hooks, and rules"
 }