@gobing-ai/knowledge-kit 0.0.13 → 0.0.15

package/plugins/kk/workflows/kk-itc.yaml

@@ -29,34 +29,17 @@ vars:
 
 states:
   - id: prepare
-    description: "mkdir work_dir, 2-outline, 3-draft; validate XOR topic/input_file; write brief.md"
+    description: "mkdir work_dir, 2-outline; validate XOR topic/input_file; 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}/2-outline" "${vars.work_dir}/3-draft";
-            echo 0 > "${vars.work_dir}/.revise-count";
-            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 [ -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;
+            kbin="$(command -v kk 2>/dev/null)";
+            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
+            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
+            bun "$st" prepare-itc "${vars.work_dir}" "${vars.topic}" "${vars.input_file}" "${vars.force}"
 
   - id: research
     description: "Conduct preliminary topic research via storm-research (agent.run)"
@@ -123,9 +106,9 @@ states:
           agent: ${vars.agent}
           input: |
             Invoke the kk:${vars.writer} skill.
-            Author the technical draft at ${vars.work_dir}/3-draft/draft-article.md based on approved outline ${vars.work_dir}/2-outline/outline-approved.md and brief ${vars.work_dir}/brief.md using playbook ${vars.playbook}.
+            Author the technical draft at ${vars.work_dir}/3-draft-draft-article.md based on approved outline ${vars.work_dir}/2-outline/outline-approved.md and brief ${vars.work_dir}/brief.md using playbook ${vars.playbook}.
             Revision feedback: ${vars.__hitlInput}
-          expectFile: ${vars.work_dir}/3-draft/draft-article.md
+          expectFile: ${vars.work_dir}/3-draft-draft-article.md
 
   - id: draft-review
     description: "Operator reviews and approves or requests revision on draft-article.md"
@@ -133,7 +116,7 @@ states:
     onEnter:
       - kind: hitl.confirm
         options:
-          prompt: "Review draft at ${vars.work_dir}/3-draft/draft-article.md. Approve?"
+          prompt: "Review draft at ${vars.work_dir}/3-draft-draft-article.md. Approve?"
           var: __hitlAnswer
 
   - id: draft-revise
@@ -147,7 +130,7 @@ states:
             echo $((n + 1)) > "${vars.work_dir}/.revise-count";
       - kind: hitl.input
         options:
-          prompt: "Provide specific revision feedback for ${vars.work_dir}/3-draft/draft-article.md:"
+          prompt: "Provide specific revision feedback for ${vars.work_dir}/3-draft-draft-article.md:"
           var: __hitlInput
 
   - id: judge
@@ -159,7 +142,7 @@ states:
           agent: ${vars.agent}
           input: |
             Invoke the kk:content-judge skill.
-            Evaluate the draft at ${vars.work_dir}/3-draft/draft-article.md against the ${vars.rubric} rubric.
+            Evaluate the draft at ${vars.work_dir}/3-draft-draft-article.md against the ${vars.rubric} rubric.
             Write the verdict JSON to ${vars.work_dir}/.itc-verdict.json per the skill's verdict contract.
             Print the verdict path as the last line of stdout.
           expectFile: ${vars.work_dir}/.itc-verdict.json

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

@@ -37,33 +37,16 @@ states:
     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;
-          echo 0 > "${vars.work_dir}/.revise-count";
+          # ADR-115: the XOR / voice_profile / overwrite / brief logic lives in the
+          # solo-podcast stage runner; this action only resolves the package root and
+          # delegates (one logical call).
+          command: >-
+            kbin="$(command -v kk 2>/dev/null)";
+            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
+            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
+            bun "$st" prepare-solo "${vars.work_dir}" "${vars.topic}" "${vars.input_file}" "${vars.voice_profile}" "${vars.force}"
 
   - id: understand
     description: "Analyze brief and generate podcast briefing (agent.run)"
@@ -75,10 +58,10 @@ states:
           input: |
             Invoke the kk:audio-authoring skill: operation `briefing`, mode `solo`.
             Read the source brief at ${vars.work_dir}/brief.md.
-            Write a concise podcast briefing at ${vars.work_dir}/1-briefing/briefing.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.
             Flags: --dir ${vars.work_dir} --duration ${vars.target_duration_min}
-          expectFile: ${vars.work_dir}/1-briefing/briefing.md
+          expectFile: ${vars.work_dir}/1-briefing-briefing.md
 
   - id: outline-write
     description: "Generate spoken podcast outline options (agent.run)"
@@ -89,7 +72,7 @@ states:
           agent: ${vars.agent}
           input: |
             Invoke the kk:audio-authoring skill: operation `outline`, mode `solo`.
-            Read the briefing at ${vars.work_dir}/1-briefing/briefing.md and brief at ${vars.work_dir}/brief.md.
+            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)
@@ -100,8 +83,8 @@ states:
           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; }
+          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"
@@ -121,15 +104,15 @@ states:
     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";
+          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)"
@@ -138,51 +121,32 @@ states:
         options:
           role: scribe
           agent: ${vars.agent}
+          # ADR-115 (R3): the VoiceScript field contract is the skill's own
+          # templates/voicescript.solo.yaml (task 0081) — not duplicated here. The prompt
+          # stays a bounded skill invocation: operation + inputs + output path + budget.
           input: |
             Invoke the kk:audio-authoring skill: operation `script`, mode `solo`.
-            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}
-            Duration retries: if ${vars.work_dir}/.duration-feedback exists, invoke with `--force` (authorized rewrite) and treat its contents as the revision feedback.
-            Flags: --dir ${vars.work_dir} --duration ${vars.target_duration_min} --language ${vars.language} --profile ${vars.voice_profile} --revise "${vars.__hitlInput}"
-          expectFile: ${vars.work_dir}/3-script/voicescript.yaml
+            Inputs: briefing ${vars.work_dir}/1-briefing-briefing.md; approved outline ${vars.work_dir}/2-outline/outline-approved.md; revision feedback ${vars.__hitlInput}.
+            Contract: the skill's templates/voicescript.solo.yaml — `language: "${vars.language}"`, `segments` of spoken text; no `default_profile`, no `title`, no invented fields.
+            Budget: ${vars.target_duration_min} min — zh/ja/ko ${vars.cjk_chars_per_min} chars/min, else ${vars.words_per_min} words/min; within ±20%, one speaker.
+            Write ONLY the YAML (no fences, no repo paths) to ${vars.work_dir}/3-script-voicescript.yaml.
+            Flags: --dir ${vars.work_dir} --duration ${vars.target_duration_min} --language ${vars.language} --profile ${vars.voice_profile} --revise "${vars.__hitlInput}"; add --force when ${vars.work_dir}/.duration-feedback exists (its contents are the revision feedback).
+          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 [ ! -f "$vs" ]; then
-            kbin="$(command -v kk 2>/dev/null || true)";
-            while [ -L "$kbin" ]; do
-              link="$(readlink "$kbin")";
-              case "$link" in /*) kbin="$link";; *) kbin="$(dirname "$kbin")/$link";; esac;
-            done;
-            pkg=""; [ -n "$kbin" ] && pkg="$(cd "$(dirname "$kbin")/.." 2>/dev/null && pwd || true)";
-            vs="";
-            if [ -n "$KK_WORKFLOWS_DIR" ] && [ -f "$KK_WORKFLOWS_DIR/validate-voicescript.ts" ]; then vs="$KK_WORKFLOWS_DIR/validate-voicescript.ts";
-            elif [ -n "$pkg" ] && [ -f "$pkg/plugins/kk/workflows/validate-voicescript.ts" ]; then vs="$pkg/plugins/kk/workflows/validate-voicescript.ts";
-            elif [ -f "$HOME/.config/kk/workflows/validate-voicescript.ts" ]; then vs="$HOME/.config/kk/workflows/validate-voicescript.ts"; fi;
-          fi;
-          if [ -z "$vs" ]; then
-            echo "validate_script not found (searched: \$KK_WORKFLOWS_DIR, kk package root via \`command -v kk\`, \$HOME/.config/kk/workflows) — install the kk package or place an override with /workflow-run kk-solo-podcast --force" >&2;
-            exit 1;
-          fi;
-          bun "$vs" --in "${vars.work_dir}/3-script/voicescript.yaml"
+          # ADR-115: package-root resolution + delegation to validate-voicescript.ts
+          # (override chain preserved inside the stage runner).
+          command: >-
+            kbin="$(command -v kk 2>/dev/null)";
+            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
+            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
+            bun "$st" validate "${vars.validate_script}" --in "${vars.work_dir}/3-script-voicescript.yaml"
 
   - id: script-review
     description: "Operator reviews and approves VoiceScript before live TTS generation"
@@ -190,7 +154,7 @@ states:
     onEnter:
       - kind: hitl.confirm
         options:
-          prompt: "Review VoiceScript at ${vars.work_dir}/3-script/voicescript.yaml. Approve for voice generation?"
+          prompt: "Review VoiceScript at ${vars.work_dir}/3-script-voicescript.yaml. Approve for voice generation?"
           var: __hitlAnswer
 
   - id: script-revise
@@ -199,13 +163,13 @@ states:
     onEnter:
       - kind: shell
         options:
-        command: >-
-          rm -f "${vars.work_dir}/.duration-feedback";
-          n=$(cat "${vars.work_dir}/.revise-count" 2>/dev/null || echo 0);
-          echo $((n + 1)) > "${vars.work_dir}/.revise-count";
+          command: >-
+            rm -f "${vars.work_dir}/.duration-feedback";
+            n=$(cat "${vars.work_dir}/.revise-count" 2>/dev/null || echo 0);
+            echo $((n + 1)) > "${vars.work_dir}/.revise-count";
       - kind: hitl.input
         options:
-          prompt: "Provide specific revision feedback for ${vars.work_dir}/3-script/voicescript.yaml:"
+          prompt: "Provide specific revision feedback for ${vars.work_dir}/3-script-voicescript.yaml:"
           var: __hitlInput
 
   - id: wrap-docs
@@ -213,65 +177,42 @@ states:
     onEnter:
       - kind: shell
         options:
-        command: >-
-          set -e;
-          ws="${vars.wrap_script}";
-          if [ ! -f "$ws" ]; then
-            kbin="$(command -v kk 2>/dev/null || true)";
-            while [ -L "$kbin" ]; do
-              link="$(readlink "$kbin")";
-              case "$link" in /*) kbin="$link";; *) kbin="$(dirname "$kbin")/$link";; esac;
-            done;
-            pkg=""; [ -n "$kbin" ] && pkg="$(cd "$(dirname "$kbin")/.." 2>/dev/null && pwd || true)";
-            ws="";
-            if [ -n "$KK_WORKFLOWS_DIR" ] && [ -f "$KK_WORKFLOWS_DIR/wrap-voicescript-doc.ts" ]; then ws="$KK_WORKFLOWS_DIR/wrap-voicescript-doc.ts";
-            elif [ -n "$pkg" ] && [ -f "$pkg/plugins/kk/workflows/wrap-voicescript-doc.ts" ]; then ws="$pkg/plugins/kk/workflows/wrap-voicescript-doc.ts";
-            elif [ -f "$HOME/.config/kk/workflows/wrap-voicescript-doc.ts" ]; then ws="$HOME/.config/kk/workflows/wrap-voicescript-doc.ts"; fi;
-          fi;
-          if [ -z "$ws" ]; then
-            echo "wrap_script not found (searched: \$KK_WORKFLOWS_DIR, kk package root via \`command -v kk\`, \$HOME/.config/kk/workflows) — install the kk package or place an override with /workflow-run kk-solo-podcast --force" >&2;
-            exit 1;
-          fi;
-          bun "$ws" "${vars.work_dir}/3-script/voicescript.yaml" "${vars.work_dir}/4-audio/docs.json" "${vars.voice_profile}"
+          # ADR-115: package-root resolution + delegation to wrap-voicescript-doc.ts
+          # (override chain preserved inside the stage runner).
+          command: >-
+            kbin="$(command -v kk 2>/dev/null)";
+            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
+            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
+            bun "$st" wrap "${vars.wrap_script}" --in "${vars.work_dir}/3-script-voicescript.yaml" --out "${vars.work_dir}/4-audio/docs.json" --profile "${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
+          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; miss writes .duration-feedback for the retry edge"
     onEnter:
       - kind: shell
         options:
-        command: >-
-          rm -f "${vars.work_dir}/4-audio/.duration-ok";
-          if [ ! -f "${vars.work_dir}/4-audio/content.json" ]; then
-            exit 0;
-          fi;
-          dur=$(jq -r '.metadata.duration // empty' "${vars.work_dir}/4-audio/content.json" 2>/dev/null);
-          if [ -z "$dur" ]; then
-            printf 'Regenerate: audio metadata.duration missing or not a number.\n' > "${vars.work_dir}/.duration-feedback";
-            n=$(cat "${vars.work_dir}/.revise-count" 2>/dev/null || echo 0);
-            echo $((n+1)) > "${vars.work_dir}/.revise-count";
-            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}');
-          if awk -v d="$dur" -v min="$min_s" -v max="$max_s" 'BEGIN { exit !(d >= min && d <= max) }'; then
-            touch "${vars.work_dir}/4-audio/.duration-ok";
-          else
-            printf 'Regenerate: last audio duration %ss outside 0.5x–2x of %ss; adjust segment lengths toward the target.\n' "$dur" "$target_s" > "${vars.work_dir}/.duration-feedback";
-            n=$(cat "${vars.work_dir}/.revise-count" 2>/dev/null || echo 0);
-            echo $((n+1)) > "${vars.work_dir}/.revise-count";
-          fi
+          # ADR-115: the band math, .duration-feedback, and .revise-count bump live in
+          # the solo-podcast stage runner; the transition guards below still branch on
+          # .duration-ok.
+          command: >-
+            kbin="$(command -v kk 2>/dev/null)";
+            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
+            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
+            bun "$st" duration "${vars.work_dir}" "${vars.target_duration_min}"
 
   - id: done
     description: "Terminal — Solo podcast VoiceScript and audio generated successfully"

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

@@ -52,49 +52,12 @@ states:
       - 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
+            kbin="$(command -v kk 2>/dev/null)";
+            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
+            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
+            bun "$st" prepare-storm "${vars.work_dir}" "${vars.topic}" "${vars.input_file}" "${vars.maxResults}" "${vars.fixture}"
 
   - id: ingest
     description: >-
@@ -139,25 +102,12 @@ states:
       - kind: shell
         options:
           command: >-
-            set -e;
-            rs="${vars.render_script}";
-            if [ ! -f "$rs" ]; then
-              kbin="$(command -v kk 2>/dev/null || true)";
-              while [ -L "$kbin" ]; do
-                link="$(readlink "$kbin")";
-                case "$link" in /*) kbin="$link";; *) kbin="$(dirname "$kbin")/$link";; esac;
-              done;
-              pkg=""; [ -n "$kbin" ] && pkg="$(cd "$(dirname "$kbin")/.." 2>/dev/null && pwd || true)";
-              rs="";
-              if [ -n "$pkg" ] && [ -f "$pkg/plugins/kk/scripts/render-md.ts" ]; then rs="$pkg/plugins/kk/scripts/render-md.ts";
-              elif [ -f "plugins/kk/scripts/render-md.ts" ]; then rs="plugins/kk/scripts/render-md.ts"; fi;
-            fi;
-            if [ -z "$rs" ]; then
-              echo "render_script not found (searched: var, kk package root via \`command -v kk\`, ./plugins/kk/scripts)" >&2;
-              exit 1;
-            fi;
-            bun "$rs" --in "${vars.work_dir}/content.json"
-            --out "${vars.work_dir}/content.md"
+            kbin="$(command -v kk 2>/dev/null)";
+            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
+            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
+            bun "$st" render-storm "${vars.render_script}" --in "${vars.work_dir}/content.json" --out "${vars.work_dir}/content.md"
 
   - id: done
     description: >-

package/plugins/publishings/emdash-pub/dist/index.js

@@ -21848,6 +21848,26 @@ var ResultSchema = exports_external.object({
   metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
 });
 var DocListSchema = exports_external.array(DocSchema);
+var omniVoiceGenContentSchema = ContentSchema.extend({
+  format: exports_external.literal("audio"),
+  metadata: exports_external.looseObject({
+    generator: exports_external.literal("kk:omni-voice-gen"),
+    audioPath: exports_external.string(),
+    duration: exports_external.number(),
+    segments: exports_external.array(exports_external.looseObject({
+      generationId: exports_external.string(),
+      profile: exports_external.string(),
+      speaker: exports_external.string().optional(),
+      emotion: exports_external.string().optional(),
+      duration: exports_external.number(),
+      verifyRetries: exports_external.number(),
+      transcription: exports_external.string().optional(),
+      loudnessDip: exports_external.boolean().optional()
+    })),
+    mp3Path: exports_external.string().optional(),
+    qc: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+  })
+});
 
 // ../../packages/kk-core/src/kinds.ts
 var PLUGIN_KINDS = ["ingestion", "generator", "publish"];

package/plugins/publishings/podcast-pub/dist/index.js

@@ -21849,6 +21849,26 @@ var ResultSchema = exports_external.object({
   metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
 });
 var DocListSchema = exports_external.array(DocSchema);
+var omniVoiceGenContentSchema = ContentSchema.extend({
+  format: exports_external.literal("audio"),
+  metadata: exports_external.looseObject({
+    generator: exports_external.literal("kk:omni-voice-gen"),
+    audioPath: exports_external.string(),
+    duration: exports_external.number(),
+    segments: exports_external.array(exports_external.looseObject({
+      generationId: exports_external.string(),
+      profile: exports_external.string(),
+      speaker: exports_external.string().optional(),
+      emotion: exports_external.string().optional(),
+      duration: exports_external.number(),
+      verifyRetries: exports_external.number(),
+      transcription: exports_external.string().optional(),
+      loudnessDip: exports_external.boolean().optional()
+    })),
+    mp3Path: exports_external.string().optional(),
+    qc: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+  })
+});
 
 // ../../packages/kk-core/src/kinds.ts
 var PLUGIN_KINDS = ["ingestion", "generator", "publish"];
@@ -21962,7 +21982,12 @@ function renderShowNotesMarkdown(docs, opts) {
     const s = t.toLowerCase().replace(/[^\w\s-]/g, "").trim().replace(/[\s_]+/g, "-");
     return s.length > 0 ? s : "post";
   };
-  const articleUrl = `${opts.articleBaseUrl ?? "https://surfing.salty.vip"}/zh/posts/${opts.runDate}-${slugify2(opts.title)}`;
+  const baseUrl = opts.articleBaseUrl ?? "https://surfing.salty.vip";
+  const segments = opts.articlePostPath?.split(/[\\/]/).filter((s) => s.length > 0) ?? [];
+  const postSlug = segments.length >= 2 ? segments[segments.length - 2] ?? "" : "";
+  const postLocale = segments.find((s) => ["zh", "en", "ja"].includes(s)) ?? "zh";
+  const articleUrl = postSlug.length > 0 ? `${baseUrl}/${postLocale}/posts/${postSlug}` : `${baseUrl}/zh/posts/${opts.runDate}-${slugify2(opts.title)}`;
+  const briefMode = opts.briefMode === true && postSlug.length > 0;
   const sourceLabel = (d) => {
     const m = d.metadata ?? {};
     if (typeof m.sourceName === "string" && m.sourceName.trim())
@@ -21973,11 +21998,31 @@ function renderShowNotesMarkdown(docs, opts) {
       return "\u6765\u6E90";
     }
   };
+  const itemBrief = (d) => {
+    const meta3 = d.metadata ?? {};
+    if (typeof meta3.brief === "string" && meta3.brief.trim().length > 0)
+      return meta3.brief.trim();
+    return (d.body ?? "").trim().split(/(?<=[\u3002\uFF01\uFF1F])\s*/).slice(0, 2).join("");
+  };
+  const itemTimestamp = (d) => {
+    const meta3 = d.metadata ?? {};
+    const raw = meta3.publishAt;
+    const t = typeof raw === "string" ? Date.parse(raw) : typeof raw === "number" ? raw : Number.NaN;
+    if (!Number.isFinite(t))
+      return "--:--";
+    const at = new Date(t);
+    return `${String(at.getHours()).padStart(2, "0")}:${String(at.getMinutes()).padStart(2, "0")}`;
+  };
   const lines = [`# ${opts.title}`, ""];
   docs.forEach((d, i) => {
     const body = (d.body ?? "").trim();
     const sentences = body.split(/(?<=[\u3002\uFF01\uFF1F])\s*/).slice(0, 2).join("");
-    lines.push(`## ${i + 1}. ${d.title ?? `\u6761\u76EE ${i + 1}`}`, "", sentences, "", `[\u6765\u6E90\uFF1A${sourceLabel(d)}](${d.sourceUri ?? ""})`, "");
+    lines.push(`## ${i + 1}. ${d.title ?? `\u6761\u76EE ${i + 1}`}`, "");
+    if (briefMode) {
+      lines.push(`${itemTimestamp(d)} \xB7 ${itemBrief(d)}`, "", `[\u6765\u6E90\uFF1A${sourceLabel(d)}](${d.sourceUri ?? ""}) \xB7 [\u6587\u7AE0](${articleUrl})`, "");
+    } else {
+      lines.push(sentences, "", `[\u6765\u6E90\uFF1A${sourceLabel(d)}](${d.sourceUri ?? ""})`, "");
+    }
   });
   lines.push(`\u8BE6\u60C5\u89C1\u672C\u671F\u5B8C\u6574\u6587\u7AE0\uFF1A[ ${opts.title} ](${articleUrl})`, "");
   return lines.join(`
@@ -22262,8 +22307,17 @@ function resolveShowNotesRenderOptions(options) {
     return { error: 'options.runDate (or PODCAST_PUB_RUN_DATE) is required for the "show-notes" operation' };
   }
   const articleBaseUrl = resolveOptionString(options.articleBaseUrl, "PODCAST_PUB_ARTICLE_BASE_URL");
+  const briefModeRaw = options.briefMode ?? process.env.PODCAST_PUB_BRIEF_MODE;
+  const briefMode = briefModeRaw === true || briefModeRaw === "true" || briefModeRaw === "1";
+  const articlePostPath = resolveOptionString(options.articlePostPath, "PODCAST_PUB_ARTICLE_POST_PATH");
   return {
-    renderOptions: { title, runDate, ...articleBaseUrl !== undefined ? { articleBaseUrl } : {} }
+    renderOptions: {
+      title,
+      runDate,
+      ...articleBaseUrl !== undefined ? { articleBaseUrl } : {},
+      ...briefMode ? { briefMode: true } : {},
+      ...articlePostPath !== undefined ? { articlePostPath } : {}
+    }
   };
 }
 function renderShowNotesFromOptions(options) {

package/plugins/publishings/podcast-pub/src/index.ts

@@ -28,6 +28,10 @@ interface PodcastPubOptions {
     title?: unknown;
     runDate?: unknown;
     articleBaseUrl?: unknown;
+    /** Brief/timeline render flag (task 0118). */
+    briefMode?: unknown;
+    /** Surfdash publish result `metadata.postPath` (briefMode URL source). */
+    articlePostPath?: unknown;
     /** Episode-assembly options for the `publish` op (absorb publish-prep's merge; additive). */
     audioFile?: unknown;
     coverPath?: unknown;
@@ -76,7 +80,10 @@ function resolveItemId(options: PodcastPubOptions): { itemId: string } | { error
 }
 
 /** Options the `show-notes` operation reads on the payload (a subset of {@link PodcastPubOptions}). */
-type ShowNotesOpOptions = Pick<PodcastPubOptions, 'docs' | 'title' | 'runDate' | 'articleBaseUrl'>;
+type ShowNotesOpOptions = Pick<
+    PodcastPubOptions,
+    'docs' | 'title' | 'runDate' | 'articleBaseUrl' | 'briefMode' | 'articlePostPath'
+>;
 
 /**
  * Option-then-env resolution for the show-notes render options: `kk executor run`
@@ -103,8 +110,17 @@ function resolveShowNotesRenderOptions(
         return { error: 'options.runDate (or PODCAST_PUB_RUN_DATE) is required for the "show-notes" operation' };
     }
     const articleBaseUrl = resolveOptionString(options.articleBaseUrl, 'PODCAST_PUB_ARTICLE_BASE_URL');
+    const briefModeRaw = options.briefMode ?? process.env.PODCAST_PUB_BRIEF_MODE;
+    const briefMode = briefModeRaw === true || briefModeRaw === 'true' || briefModeRaw === '1';
+    const articlePostPath = resolveOptionString(options.articlePostPath, 'PODCAST_PUB_ARTICLE_POST_PATH');
     return {
-        renderOptions: { title, runDate, ...(articleBaseUrl !== undefined ? { articleBaseUrl } : {}) },
+        renderOptions: {
+            title,
+            runDate,
+            ...(articleBaseUrl !== undefined ? { articleBaseUrl } : {}),
+            ...(briefMode ? { briefMode: true } : {}),
+            ...(articlePostPath !== undefined ? { articlePostPath } : {}),
+        },
     };
 }