@gobing-ai/knowledge-kit 0.0.6 → 0.0.8

package/plugins/kk/workflows/kk-solo-podcast.yaml

@@ -0,0 +1,374 @@
+---
+"$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
+name: kk-solo-podcast
+kind: state-machine
+description: >-
+  Solo podcast authoring pipeline using VoiceScript authoring, Spur HITL gates, and voice-gen audio generation
+initialState: prepare
+terminalStates:
+  - done
+  - failed
+failureStates:
+  - failed
+
+vars:
+  topic: ""
+  input_file: ""
+  work_dir: ""
+  force: "false"
+  outline: ""
+  script_approved: ""
+  target_duration_min: "8"
+  words_per_min: "150"
+  cjk_chars_per_min: "220"
+  voice_profile: ""
+  language: "en"
+  plugins_path: ""
+  validate_script: ""
+  agent: ""
+  __runId: "solo"
+  __hitlAnswer: ""
+  __hitlInput: ""
+
+states:
+  - id: prepare
+    description: "mkdir work_dir and stage subdirectories; validate XOR topic/input_file and voice_profile; write brief.md"
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            set -e;
+            if [ -z "${vars.work_dir}" ]; then
+              echo "missing work_dir" >&2; exit 1;
+            fi;
+            mkdir -p "${vars.work_dir}" "${vars.work_dir}/1-briefing" "${vars.work_dir}/2-outline" "${vars.work_dir}/3-script" "${vars.work_dir}/4-audio";
+            if [ -n "${vars.topic}" ] && [ -n "${vars.input_file}" ]; then
+              echo "XOR violation: both topic and input_file set" >&2; exit 1;
+            fi;
+            if [ -z "${vars.topic}" ] && [ -z "${vars.input_file}" ]; then
+              echo "XOR violation: neither topic nor input_file set" >&2; exit 1;
+            fi;
+            if [ -z "${vars.voice_profile}" ] && [ -z "$VOICEBOX_DEFAULT_PROFILE" ]; then
+              echo "missing voice_profile (set vars.voice_profile or VOICEBOX_DEFAULT_PROFILE)" >&2; exit 1;
+            fi;
+            if [ -f "${vars.work_dir}/brief.md" ] && [ "${vars.force}" != "true" ]; then
+              echo "initialization target already exists at ${vars.work_dir}/brief.md; pass force=true to replace" >&2; exit 1;
+            fi;
+            if [ -n "${vars.topic}" ]; then
+              printf '%s\n' "${vars.topic}" > "${vars.work_dir}/brief.md";
+            else
+              if [ ! -f "${vars.input_file}" ]; then
+                echo "input file not found: ${vars.input_file}" >&2; exit 1;
+              fi;
+              cp "${vars.input_file}" "${vars.work_dir}/brief.md";
+            fi;
+
+  - id: understand
+    description: "Analyze brief and generate podcast briefing (agent.run)"
+    onEnter:
+      - kind: agent.run
+        options:
+          role: scribe
+          agent: ${vars.agent}
+          input: |
+            Read the source brief at ${vars.work_dir}/brief.md.
+            Write a concise podcast briefing at ${vars.work_dir}/1-briefing/briefing.md.
+            Identify core thesis, key listener takeaways, audience profile, target spoken duration (${vars.target_duration_min} minutes), tone, and what material from the brief to emphasize or cut.
+          expectFile: ${vars.work_dir}/1-briefing/briefing.md
+
+  - id: outline-write
+    description: "Generate spoken podcast outline options (agent.run)"
+    onEnter:
+      - kind: agent.run
+        options:
+          role: scribe
+          agent: ${vars.agent}
+          input: |
+            Read the briefing at ${vars.work_dir}/1-briefing/briefing.md and brief at ${vars.work_dir}/brief.md.
+            Generate spoken podcast outline options in ${vars.work_dir}/2-outline/:
+            - outline-option-a.md (e.g. narrative / storytelling arc)
+            - outline-option-b.md (e.g. analytical / explainer breakdown)
+            - optional outline-option-c.md
+            Target total episode spoken duration is ${vars.target_duration_min} minutes.
+            Do not wait for operator selection; write the option files.
+          expectFile: ${vars.work_dir}/2-outline/outline-option-a.md
+      - kind: shell
+        options:
+          command: >-
+            test -f "${vars.work_dir}/2-outline/outline-option-b.md" || { echo "missing required outline-option-b.md" >&2; exit 1; }
+
+  - id: outline-select
+    description: "Operator selects preferred outline option"
+    pause: true
+    onEnter:
+      - kind: hitl.select
+        options:
+          prompt: "Select an approved outline option from ${vars.work_dir}/2-outline/ (outline-option-a.md, outline-option-b.md, or outline-option-c.md):"
+          options:
+            - a
+            - b
+            - c
+          var: __hitlAnswer
+
+  - id: outline-commit
+    description: "Copy selected outline to outline-approved.md"
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            sel="${vars.outline}";
+            if [ -z "$sel" ]; then sel="${vars.__hitlAnswer}"; fi;
+            if [ -z "$sel" ]; then sel="a"; fi;
+            src="${vars.work_dir}/2-outline/outline-option-$sel.md";
+            if [ ! -f "$src" ]; then
+              echo "selected outline file not found: $src" >&2; exit 1;
+            fi;
+            cp "$src" "${vars.work_dir}/2-outline/outline-approved.md";
+
+  - id: script-write
+    description: "Author complete VoiceScript YAML from approved outline (agent.run)"
+    onEnter:
+      - kind: agent.run
+        options:
+          role: scribe
+          agent: ${vars.agent}
+          input: |
+            Read the approved outline at ${vars.work_dir}/2-outline/outline-approved.md and briefing at ${vars.work_dir}/1-briefing/briefing.md.
+            Target duration is ${vars.target_duration_min} minutes.
+            Spoken budget: if language (${vars.language}) is zh, ja, or ko, target characters = ${vars.target_duration_min} * ${vars.cjk_chars_per_min}; otherwise target words = ${vars.target_duration_min} * ${vars.words_per_min}. Land inside ±20%, spoken prose, one speaker.
+            Author the complete solo-podcast VoiceScript YAML at ${vars.work_dir}/3-script/voicescript.yaml.
+            Emit ONLY valid YAML (no markdown fences, no repo/docs paths). Contract:
+            title: string
+            language: "${vars.language}"
+            default_profile: "${vars.voice_profile}"
+            default_engine: qwen|qwen_custom_voice|luxtts|chatterbox|chatterbox_turbo|tada|kokoro  # optional
+            segments:
+              - text: "spoken sentence"   # required, 1..50000 characters
+                gap_ms: 400               # optional, >= 0, silence before next clip
+                instruct: "warm"          # optional, <= 500 characters
+            Do not invent fields. Revision feedback: ${vars.__hitlInput}
+          expectFile: ${vars.work_dir}/3-script/voicescript.yaml
+
+  - id: script-validate
+    description: "Validate authored VoiceScript YAML structure and constraints"
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            set -e;
+            vs="${vars.validate_script}";
+            if [ -z "$vs" ]; then
+              if [ -n "$KK_WORKFLOWS_DIR" ]; then vs="$KK_WORKFLOWS_DIR/validate-voicescript.ts";
+              else vs="$HOME/.config/kk/workflows/validate-voicescript.ts"; fi;
+            fi;
+            if [ ! -f "$vs" ]; then
+              echo "validate_script not found: $vs (install with /workflow-run kk-solo-podcast into $HOME/.config/kk/workflows)" >&2;
+              exit 1;
+            fi;
+            bun "$vs" --in "${vars.work_dir}/3-script/voicescript.yaml"
+
+  - id: script-review
+    description: "Operator reviews and approves VoiceScript before live TTS generation"
+    pause: true
+    onEnter:
+      - kind: hitl.confirm
+        options:
+          prompt: "Review VoiceScript at ${vars.work_dir}/3-script/voicescript.yaml. Approve for voice generation?"
+          var: __hitlAnswer
+
+  - id: script-revise
+    description: "Collect revision feedback from operator (bounded by 3 rounds)"
+    pause: true
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            mkdir -p .spur/run;
+            run_id="${vars.__runId}";
+            if [ -z "$run_id" ]; then run_id="solo"; fi;
+            count_file=".spur/run/$run_id-solo-revise-count";
+            curr=$(cat "$count_file" 2>/dev/null || echo 0);
+            echo $((curr + 1)) > "$count_file";
+      - kind: hitl.input
+        options:
+          prompt: "Provide specific revision feedback for ${vars.work_dir}/3-script/voicescript.yaml:"
+          var: __hitlInput
+
+  - id: wrap-docs
+    description: "Wrap VoiceScript into Doc[] JSON for voice-gen generator plugin"
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            bun -e '
+            import { readFileSync, writeFileSync } from "node:fs";
+            import { createHash } from "node:crypto";
+            import { resolve } from "node:path";
+            const scriptPath = resolve(process.argv[1]);
+            const outPath = resolve(process.argv[2]);
+            const voiceProfile = process.argv[3] || process.env.VOICEBOX_DEFAULT_PROFILE || "";
+            const body = readFileSync(scriptPath, "utf-8");
+            const sourceUri = "file://" + scriptPath;
+            const id = createHash("sha256").update(sourceUri).digest("hex").slice(0, 16);
+            const doc = {
+              id,
+              title: "Podcast VoiceScript",
+              sourceUri,
+              body,
+              mediaType: "application/yaml",
+              metadata: voiceProfile ? { voiceProfile } : {},
+            };
+            writeFileSync(outPath, JSON.stringify([doc], null, 2));
+            ' "${vars.work_dir}/3-script/voicescript.yaml" "${vars.work_dir}/4-audio/docs.json" "${vars.voice_profile}"
+
+  - id: generate
+    description: "Invoke voice-gen generator plugin to generate audio"
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            set -e;
+            extra="";
+            if [ -n "${vars.plugins_path}" ]; then extra="--plugins-path ${vars.plugins_path}"; fi;
+            kk executor run voice-gen --in "${vars.work_dir}/4-audio/docs.json" --out "${vars.work_dir}/4-audio/content.json" $extra
+
+  - id: duration-check
+    description: "Validate generated audio duration against target budget"
+
+  - id: done
+    description: "Terminal — Solo podcast VoiceScript and audio generated successfully"
+  - id: failed
+    description: "Terminal — Solo podcast workflow failed or rejected"
+
+transitions:
+  - from: prepare
+    to: understand
+    description: "Prepare completed -> begin briefing analysis"
+    guard:
+      kind: always
+
+  - from: understand
+    to: outline-write
+    description: "Briefing completed -> generate outline options"
+    guard:
+      kind: always
+
+  - from: outline-write
+    to: outline-select
+    description: "Outline not pre-selected -> pause for operator selection"
+    guard:
+      kind: shell
+      options:
+        command: 'test -z "${vars.outline}"'
+
+  - from: outline-write
+    to: outline-commit
+    description: "Outline pre-selected -> skip interactive selection"
+    guard:
+      kind: shell
+      options:
+        command: 'test -n "${vars.outline}"'
+
+  - from: outline-select
+    to: outline-commit
+    description: "Outline selected -> commit approved outline"
+    guard:
+      kind: always
+
+  - from: outline-commit
+    to: script-write
+    description: "Approved outline committed -> write VoiceScript"
+    guard:
+      kind: always
+
+  - from: script-write
+    to: script-validate
+    description: "VoiceScript written -> validate structure and caps"
+    guard:
+      kind: always
+
+  - from: script-validate
+    to: wrap-docs
+    description: "script_approved pre-set -> skip script review (CI/dry-run)"
+    guard:
+      kind: shell
+      options:
+        command: 'test "${vars.script_approved}" = "true"'
+  - from: script-validate
+    to: script-review
+    description: "VoiceScript validation passed -> pause for operator review"
+    guard:
+      kind: always
+
+  - from: script-review
+    to: wrap-docs
+    description: "VoiceScript approved -> wrap into Doc[] for generation"
+    guard:
+      kind: shell
+      options:
+        command: '{ test -z "${vars.__hitlAnswer}" || test "${vars.__hitlAnswer}" = "yes"; }'
+
+  - from: script-review
+    to: script-revise
+    description: "VoiceScript rejected with revision budget remaining -> collect feedback"
+    guard:
+      kind: shell
+      options:
+        command: 'test "${vars.__hitlAnswer}" = "no" && { run_id="${vars.__runId}"; if [ -z "$run_id" ]; then run_id="solo"; fi; test "$(cat .spur/run/$run_id-solo-revise-count 2>/dev/null || echo 0)" -lt 3; }'
+
+  - from: script-review
+    to: failed
+    description: "VoiceScript rejected with revision budget exhausted -> fail"
+    guard:
+      kind: shell
+      options:
+        command: 'test "${vars.__hitlAnswer}" = "no" && { run_id="${vars.__runId}"; if [ -z "$run_id" ]; then run_id="solo"; fi; test "$(cat .spur/run/$run_id-solo-revise-count 2>/dev/null || echo 0)" -ge 3; }'
+
+  - from: script-revise
+    to: script-write
+    description: "Feedback collected -> rewrite VoiceScript"
+    guard:
+      kind: always
+
+  - from: wrap-docs
+    to: generate
+    description: "Doc[] wrapped -> invoke voice-gen"
+    guard:
+      kind: always
+
+  - from: generate
+    to: duration-check
+    description: "Voice generation finished -> verify duration"
+    guard:
+      kind: always
+
+  - from: duration-check
+    to: done
+    description: "Audio duration within [0.5x, 2.0x] band or missing content.json in dry-run -> complete"
+    guard:
+      kind: shell
+      options:
+        command: >-
+          test ! -f "${vars.work_dir}/4-audio/content.json" || {
+            dur=$(jq -r '.metadata.duration // empty' "${vars.work_dir}/4-audio/content.json" 2>/dev/null);
+            test -n "$dur" && target_s=$((${vars.target_duration_min} * 60)) && min_s=$(awk -v t="$target_s" 'BEGIN {print t * 0.5}') && max_s=$(awk -v t="$target_s" 'BEGIN {print t * 2.0}') && awk -v d="$dur" -v min="$min_s" -v max="$max_s" 'BEGIN { if (d >= min && d <= max) exit 0; else exit 1 }';
+          }
+
+  - from: duration-check
+    to: failed
+    description: "Audio duration missing or outside [0.5x, 2.0x] target range -> fail"
+    guard:
+      kind: shell
+      options:
+        command: >-
+          test -f "${vars.work_dir}/4-audio/content.json" && {
+            dur=$(jq -r '.metadata.duration // empty' "${vars.work_dir}/4-audio/content.json" 2>/dev/null);
+            if [ -z "$dur" ]; then
+              echo "duration-check failed: metadata.duration missing or not a number" >&2;
+              exit 0;
+            fi;
+            target_s=$((${vars.target_duration_min} * 60));
+            min_s=$(awk -v t="$target_s" 'BEGIN {print t * 0.5}');
+            max_s=$(awk -v t="$target_s" 'BEGIN {print t * 2.0}');
+            awk -v d="$dur" -v min="$min_s" -v max="$max_s" -v ts="$target_s" 'BEGIN { if (d < min || d > max) { printf "duration-check failed: duration %ss outside 0.5x–2x of %ss\n", d, ts > "/dev/stderr"; exit 0 } else exit 1 }';
+          }

package/plugins/kk/workflows/kk-storm-research.yaml

@@ -0,0 +1,184 @@
+---
+# STORM topic-research daily workflow (C4):
+#   prepare -> ingest -> generate -> render -> done|failed.
+#
+# State-machine extension of the C3 dry-run prototype. Adds the 0056 XOR
+# prepare + works layout, the generate local-doc merge, and the 0058 render
+# sidecar state. No publish, no judge — by design (C4 scope).
+#
+# 0056 contract (docs/tasks/0056 ... Solution blocks 1-8): `work_dir` is the
+# RESOLVED topic dir (`$works_root/<topic-id>`), computed by the invoker
+# (0060/operator) and passed as `--vars`. prepare only `mkdir` + materializes
+# files into `${vars.work_dir}`; it never hashes the topic-id in YAML. XOR:
+# exactly one of `topic`/`input_file` must be non-empty.
+#
+# 0058 contract (docs/tasks/0058 ... Solution): render shells
+#   bun plugins/kk/scripts/render-md.ts --in <work_dir>/content.json \
+#     --out <work_dir>/content.md
+#
+# Success edges use `guard: { kind: always }` (repo convention — see the C3
+# file and task-pipeline.yaml): a real-run action failure short-circuits at
+# the state under the default onError=fail policy; `always` lets `--dry-run`
+# walk to `done` (actions don't execute in dry-run, so `action-ok` would
+# always deny and fall to `failed`).
+"$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
+name: kk-storm-research
+kind: state-machine
+description: >-
+  STORM daily topic research — XOR prepare into 0056 works layout, chain
+  ingest + generate, render content.md sidecar
+initialState: prepare
+terminalStates:
+  - done
+  - failed
+vars:
+  topic: "" # sentence-mode query; ignored when input_file set (XOR)
+  input_file: "" # file-mode markdown path when non-empty (XOR)
+  maxResults: "8" # written into topic.json as int (0054 maxResults)
+  fixture: "false" # "true" selects the stub; CI/dry-run must pass "true"
+  work_dir: "./work" # RESOLVED topic dir ($works_root/<topic-id>)
+  plugins_path: "./plugins" # --plugins-path for kk executor run
+  ingestion_plugin: "web-search"
+  generator_plugin: "content-gen"
+  render_script: "plugins/kk/scripts/render-md.ts" # 0058 shipped runner
+
+states:
+  - id: prepare
+    description: >-
+      mkdir work_dir; XOR guard; sentence mode writes topic.json; file mode
+      copies input.md, writes local-doc.json and topic.json with a derived
+      query
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            set -e;
+            mkdir -p "${vars.work_dir}";
+            if [ -n "${vars.topic}" ] && [ -n "${vars.input_file}" ]; then
+            echo "XOR violation: both topic and input_file set" >&2; exit 1;
+            fi;
+            if [ -z "${vars.topic}" ] && [ -z "${vars.input_file}" ]; then
+            echo "XOR violation: neither topic nor input_file set" >&2;
+            exit 1;
+            fi;
+            if [ -n "${vars.topic}" ]; then
+            jq -n --arg topic "${vars.topic}" --arg maxResults
+            "${vars.maxResults}" --arg fixture "${vars.fixture}"
+            '{topic: $topic, maxResults: ($maxResults | tonumber),
+            fixture: ($fixture == "true")}' > "${vars.work_dir}/topic.json";
+            exit 0;
+            fi;
+            if [ -f "${vars.input_file}" ]; then
+            cp "${vars.input_file}" "${vars.work_dir}/input.md";
+            ABS=$(cd "$(dirname "${vars.input_file}")" && pwd)/$(basename
+            "${vars.input_file}");
+            QUERY=$(grep -m1 '^# ' "${vars.input_file}" | sed 's/^# *//'
+            || true);
+            if [ -z "$QUERY" ]; then
+            QUERY=$(basename "${vars.input_file}" | sed 's/\.[^.]*$//');
+            fi;
+            if [ -z "$QUERY" ]; then
+            echo "no query derivable (no H1 and empty basename)" >&2;
+            exit 1;
+            fi;
+            ID=$(printf 'file://%s' "$ABS" | shasum -a 256 | cut -c1-16);
+            jq -n --arg id "$ID" --arg body "$(cat "${vars.input_file}")"
+            --arg title "$QUERY" --arg sourceUri "file://$ABS" --arg query
+            "$QUERY" '{id: $id, body: $body, title: $title, sourceUri:
+            $sourceUri, mediaType: "text/markdown",
+            metadata: {query: $query, rank: -1, position: 0}}'
+            > "${vars.work_dir}/local-doc.json";
+            jq -n --arg topic "$QUERY" --arg maxResults
+            "${vars.maxResults}" --arg fixture "${vars.fixture}"
+            '{topic: $topic, maxResults: ($maxResults | tonumber),
+            fixture: ($fixture == "true")}' > "${vars.work_dir}/topic.json";
+            else
+            echo "input_file not readable: ${vars.input_file}" >&2; exit 1;
+            fi
+
+  - id: ingest
+    description: >-
+      Run web-search ingestion plugin to produce document list (docs.json)
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            kk executor run "${vars.ingestion_plugin}" --in
+            "${vars.work_dir}/topic.json" --out "${vars.work_dir}/docs.json"
+            --plugins-path "${vars.plugins_path}"
+
+  - id: generate
+    description: >-
+      Prepend local-doc (when present) onto docs.json, then run content
+      generator to produce content.json
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            if [ -f "${vars.work_dir}/local-doc.json" ]; then
+            jq -s '[.[0]] + .[1]' "${vars.work_dir}/local-doc.json"
+            "${vars.work_dir}/docs.json" > "${vars.work_dir}/docs.json.tmp"
+            && mv "${vars.work_dir}/docs.json.tmp" "${vars.work_dir}/docs.json";
+            fi
+      - kind: shell
+        options:
+          command: >-
+            kk executor run "${vars.generator_plugin}" --in
+            "${vars.work_dir}/docs.json" --out "${vars.work_dir}/content.json"
+            --plugins-path "${vars.plugins_path}"
+
+  - id: render
+    description: >-
+      Render content.json to the markdown sidecar content.md via the 0058
+      shipped script
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            bun "${vars.render_script}" --in "${vars.work_dir}/content.json"
+            --out "${vars.work_dir}/content.md"
+
+  - id: done
+    description: >-
+      Terminal — topic materialized, ingested, generated, and rendered to
+      content.md. No publish/judge by design (C4).
+  - id: failed
+    description: Terminal — one of the steps failed
+
+transitions:
+  - from: prepare
+    to: ingest
+    description: Works materialized — proceed to web-search ingestion
+    guard:
+      kind: always
+  - from: prepare
+    to: failed
+    description: >-
+      prepare failed (XOR violation / unreadable input) — terminate workflow
+
+  - from: ingest
+    to: generate
+    description: Ingestion succeeded — proceed to content generation
+    guard:
+      kind: always
+  - from: ingest
+    to: failed
+    description: Ingestion failed — terminate workflow
+
+  - from: generate
+    to: render
+    description: Content generated — render the markdown sidecar
+    guard:
+      kind: always
+  - from: generate
+    to: failed
+    description: Generation failed — terminate workflow
+
+  - from: render
+    to: done
+    description: content.md rendered — workflow complete
+    guard:
+      kind: always
+  - from: render
+    to: failed
+    description: Render failed — terminate workflow