@gobing-ai/knowledge-kit 0.0.22 → 0.0.24

package/plugins/kk/skills/xhs-images/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: xhs-images
+description: >-
+  Use the xhs-images skill to turn source content into an ordered Xiaohongshu
+  card series — "make XHS cards from this article", "generate a card series",
+  "turn these notes into 小红书图文卡片". Plans N ordered cards (cover, content,
+  closing) grounded in the source, renders them through the image-gen executor
+  with the xhs-card/xhs-knowledge presets, packages a publishable Content, and
+  hands off to kk:publish channel xhs. Never publishes directly.
+---
+
+# xhs-images — source-grounded XHS card series (plan → render → package → handoff)
+
+Adapted from `baoyu-xhs-images` (MIT © Jim Liu) — layout, typography, and
+consistency guidance only. Not imported: backend selection, batch/parallel
+generation, `EXTEND.md` chain. Layout catalog:
+`references/card-layouts.md`. Presets: `xhs-card` (format) +
+`xhs-knowledge` (style). Rendering always goes through
+`kk executor run image-gen` — this skill holds no transport.
+
+## Inputs
+
+| Input | Required | Notes |
+| ----- | -------- | ----- |
+| source file (md/txt) | yes | read-only; never written or modified |
+| `--out <dir>` | yes | fresh dir = new plan; existing dir = resume |
+| `--count <n>` | no | 1–10; default: cover + one card per major point, capped at 10 |
+| `--style <name>` | no | default `xhs-knowledge` |
+| `--live` | no | passed through to kk:publish as the operator's live request |
+
+`--count` above `min(10, image.max_images)` is refused, naming
+`KK_IMAGE_MAX_IMAGES` / `image.max_images`.
+
+## Procedure
+
+1. **Plan** — read the source; produce ordered cards: card 01 `role: cover`,
+   then `content` cards in source order, then an optional `closing` card. Each
+   card records `index`, `role`, `sourcePoint` (verbatim heading or sentence),
+   `copy` (short Chinese on-card text), `layout` (from the reference catalog),
+   `subject` (visual scene). Write `<out>/cards.json` with
+   `{ source, cards: [{ index, role, sourcePoint, copy, layout, promptPath,
+   imagePath, status: 'pending' }] }`.
+2. **Envelopes** — for each card write `<out>/cards/NN.in.json`: the `image-gen`
+   envelope with `job: free`, `format: xhs-card`, `style`, `vars` (role,
+   layout, headline, points, subject, language 简体中文, index), `provider`,
+   `model`, `maxImages: 1`, `outputStem: card-NN`. For NN ≥ 02 add
+   `referenceImages: [<cover path>]` **only when** `kk:image-authoring`
+   `references/providers.md` marks the provider/model reference-capable.
+3. **Dry-run + one confirmation** — run each envelope with `KK_IMAGE_DRY_RUN=1`;
+   save the emitted `Content.body` as `<out>/cards/NN.prompt.txt` (the exact
+   composed prompt; it must equal `ImageArtifact.prompt` after render). Resolve
+   provider/model via `kk:image-authoring`'s preference chain (arguments >
+   env > `$KK_CONFIG` > defaults). Show **one** spend preview for the series
+   (provider, model, style, N, cover prompt, per-card copy list, plus the
+   consistency path: cover-reference chain when the provider is
+   reference-capable per `kk:image-authoring` `references/providers.md`, or an
+   explicit weaker-consistency disclosure when it is not) and follow the
+   `kk:image-authoring` Confirmation policy once before any paid render.
+4. **Render sequentially** — card 01, then 02..N, each via
+   `kk executor run image-gen --in cards/NN.in.json --out cards/NN.json`.
+   On the first failure: stop spending, mark the card `failed`, later cards
+   stay `pending`, report the retry.
+5. **Package** — write `<out>/content.json`: `title` (XHS title, ≤ 20 chars),
+   `body` (Chinese note + hashtags, ≤ 1000 chars), `format: 'text'`,
+   `metadata.images` = each card's `cards/NN.json` `metadata.images[0]` in
+   index order, `metadata.publishStatus: 'draft'`. Packaging refuses while any
+   card is not `rendered` or its prompt/image file is missing.
+6. **Handoff** — never spawn `xhs-pub` directly. Hand `content.json` to
+   `kk:publish` channel `xhs`; pass `--live` through as the operator's live
+   request.
+
+## Resume
+
+Re-running with the same `--out` reuses the existing `cards.json` and
+`cards/NN.in.json` (no replanning) and renders only cards without an existing
+image file — check existence via the artifact path recorded in the prior run's
+`cards/NN.json` (or a `cards/card-NN-*` glob), since the provider decides the
+extension. Replanning requires a new `--out`.
+
+## Checks and limits
+
+- N ≤ 10 and ≤ `image.max_images`; refusal names the cap env/key.
+- Source file is never written.
+- One spend confirmation per series; renders strictly sequential.
+- Card text stays minimal (headline ≤ 12 chars, 2–4 short points) — the model
+  renders text, so fewer words means fewer rendering defects.
+- Consistency: cover prompt fixes palette/typography wording; per-card prompts
+  reuse it verbatim and vary only layout/points/subject. When the provider is
+  reference-capable, cards ≥ 02 reference the rendered cover.

package/plugins/kk/skills/xhs-images/references/card-layouts.md

@@ -0,0 +1,35 @@
+# XHS card layouts — adapted from `baoyu-xhs-images`
+
+Source: `vendors/baoyu-skills/skills/baoyu-xhs-images/SKILL.md` (MIT © Jim Liu).
+Adapted: layout names, typography rules, consistency guidance. Not imported:
+backend selection, batch/parallel generation, `EXTEND.md` chain.
+
+## Layout catalog
+
+| Layout | Use when | On-card structure |
+| ------ | -------- | ----------------- |
+| `cover` | Card 01 | Big headline (≤ 12 chars), one-line hook, small series label |
+| `definition` | One concept to explain | Term + one-sentence definition + 2 short points |
+| `list` | 3–4 parallel items | Numbered short lines, uniform phrasing |
+| `comparison` | Two options | Two columns, 2–3 contrast points each |
+| `steps` | Ordered process | 3–4 numbered steps, verb-first |
+| `quote` | Key sentence from source | Large quote text + attribution line |
+| `summary` | Closing card | 3 takeaways + one CTA line |
+
+## Typography rules
+
+- Headline: extra-large bold; ≤ 12 Chinese characters.
+- Points: short lines, 2–4 per card, generous line spacing.
+- Keep total on-card text minimal — the model renders text, so fewer words
+  means fewer rendering defects.
+- Language default: 简体中文 (`xhs-card` format `language` var).
+
+## Consistency rules
+
+- Compose the cover prompt first; fix palette/typography wording there.
+- Per-card prompts reuse that wording verbatim; vary only
+  layout/points/subject (via the `xhs-card` template variables).
+- When the provider/model is reference-capable per `kk:image-authoring`
+  `references/providers.md`, cards ≥ 02 set `referenceImages: [<cover path>]`.
+- Renders are strictly sequential (card 01 → N) so the cover reference exists
+  before dependents render.

package/plugins/kk/workflows/kk-daily-ai-voice.yaml

@@ -5,7 +5,8 @@ kind: state-machine
 description: >-
   Daily AI news end-to-end pipeline (F61 destination): collect (fan-in --source: aihot + last30days
   + Horizon) → core facts → plan → content QC (filter, done-no-content terminal) → article + cover
-  + script + review + voice → publish (surfdash + podcast, full|partial|none routing) → locales
+  + script + review + voice → publish (surfdash + podcast, full|partial|none routing) → xhs draft
+  (independent, non-blocking target) → locales
 initialState: prepare
 terminalStates:
   - done
@@ -19,7 +20,7 @@ vars:
   limit: "10"
   language: "zh"
   voice_profile: "robin-news"
-  # 20260917: voice driver switch — voicebox (default, voice-gen) | ominivoice (omni-voice-gen).
+  # 20260917: voice driver switch — voicebox (default, voice-gen) | ominivoice (omni-voice-gen) | gemini (gemini-tts).
   # 20260920: default flipped to voicebox — operator A/B at matched speech rate (~5.2 chars/s)
   # judged voicebox clearly better (ominivoice carries ~1min dead air over 16min + ASR-garble class).
   vdriver: "voicebox"
@@ -31,11 +32,45 @@ vars:
   cursor: ""
   state_file: ""
   skip_review: "false"
-  transcode_mp3: "false"
+  # 0171 R1: podcast-pub publishes metadata.mp3Path, so "false" fell back to the WAV render — an
+  # enclosure Apple Podcasts rejects and no ID3 tag can ride.
+  transcode_mp3: "true"
+  # 0171 R3/R4: ID3 artist/album stamped onto the published MP3 (title comes from the article,
+  # date from run_date); an empty var omits that tag.
+  podcast_artist: "Robin Min"
+  podcast_album: "咸话咸说"
   cover_enabled: "true"
+  # F614: the daily cover pins provider+model in vars — each provider has its own look, so the
+  # pin is part of the style contract; it stays a var because the right value depends on which
+  # credentials the machine has (2026-09-24 run: minimax/image-01).
+  cover_provider: "minimax"
+  cover_model: "image-01"
+  # D6 0166: runtime-fallback opt-in for the cover render — "" (default) keeps strict fail-fast,
+  # "true" retries down AUTO_ORDER, anything else is a comma-separated provider list. The empty
+  # default keeps F614's pinned look the default; availability trades against it only on opt-in.
+  cover_fallback: ""
+  # E8: XHS image-card target. Cards are planned from the lead plan item (the same source the
+  # cover uses) and rendered through the pinned xhs-card/xhs-knowledge presets. `xhs_live` stays a
+  # separate launch-time switch (ADR-022), so an unattended run drafts and never posts live.
+  # Default OFF (2026-09-28): XHS warned the operator about automated login/publish activity.
+  # `xhs-pub` always launches a headed browser and drives the creator console, and an unattended
+  # daily job repeating that is precisely the pattern the platform flags — so the target is
+  # operator-opt-in until a reviewed automation policy exists. Do NOT flip this on for a scheduled
+  # run; publish XHS deliberately, by hand, and rarely.
+  xhs_enabled: "false"
+  xhs_cards: "4"
+  xhs_style: "xhs-knowledge"
+  # Same credential surface as the cover pin: the provider/model must be one this machine can
+  # actually reach, and each provider renders its own look.
+  xhs_provider: "minimax"
+  xhs_model: "image-01"
+  xhs_live: "false"
   plan_max_items: "20"
   plan_translate_enabled: "true"
   article_write_enabled: "true"
+  # F613 R3: script-write authors the per-item plan the zh builder consumes; "false" routes
+  # article/cover straight to script (template build, no plan file is written).
+  script_write_enabled: "true"
   plugins_path: ""
   # Projected by the publish state from 3-publish/<run_date>_17_publish_publish-status.txt;
   # guards test this var instead of cat-ing the file (state at decision time).
@@ -160,24 +195,60 @@ states:
             kk stage daily-article "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}"
 
   - id: cover
-    description: "Generate the article cover image via the kk:image-authoring skill (agent.run)"
+    description: "Render the daily cover from the lead plan item through the pinned daily-news presets (brief agent.run -> pinned stage render -> normalize, F614)"
     onEnter:
       - kind: agent.run
+        # A bad or failed brief must never halt the run: the stage falls back to the format's
+        # default subject (F614 R4) and keeps the same pinned format/style/provider/model.
+        onError: continue
         options:
           role: scribe
           agent: ${vars.agent}
+          # ADR-115 error tier: keep this prompt <= 1000 chars.
           input: |
-            Invoke the kk:image-authoring skill (generate operation).
-            Non-interactive step: run every image command with KK_NONINTERACTIVE=1 and KK_IMAGE_AUTO_CONFIRM=1 — never prompt (cover_enabled is the spend approval).
-            Command: --format cover --content ${vars.work_dir}/2-article/${vars.run_date}_06_article_article.md --out ${vars.work_dir}/2-cover
-            Template variables (title, subtitle, topics) come from the article as the skill owns; do not pass --style.
-            The plugin writes ${vars.work_dir}/2-cover/content.json plus ${vars.work_dir}/2-cover/content-cover-01.<ext> (ext follows the elected provider: minimax → .jpg, google/ark → .png). On failure report the error verbatim and stop — no procedural fallback.
-          expectFile: ${vars.work_dir}/2-cover/content-cover-01.jpg
+            Read ${vars.work_dir}/2-plan/${vars.run_date}_03_plan_plan.json — a JSON array of news docs; don't edit it.
+            Take item 1 only (its "title" and "metadata.brief") — the episode's lead story.
+            Write one concrete visual scene in English, ≤240 characters, that a viewer would connect to that story: objects, settings, symbols, metaphor.
+            No text, letters, numbers, logos, brand marks, flags, or recognizable real people. No style, color, lighting, or composition words — the preset owns those.
+            Output strictly valid JSON {"subject": "..."} to ${vars.work_dir}/2-cover/${vars.run_date}_07_cover-brief.json.
+          expectFile: ${vars.work_dir}/2-cover/${vars.run_date}_07_cover-brief.json
+          allowAppend: false
+      - kind: shell
+        options:
+          command: >-
+            kk stage daily-cover "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}" "${vars.cover_provider}" "${vars.cover_model}" "${vars.cover_fallback}"
       - kind: shell
         options:
           command: >-
             kk stage daily-cover-normalize "${vars.work_dir}" "${vars.run_date}"
 
+  - id: script-write
+    description: "Author the per-item script plan (intro/outro + lead/insight per doc id) from the show-notes plan source via agent.run; onError: continue — a failed plan falls back to templates (F613)"
+    onEnter:
+      - kind: shell
+        options:
+          # Spur has no workflow-dir var, so the prompt cannot name the shipped sidecar: this
+          # stage snapshots it into the work dir (idempotent; a missing sidecar is a broken
+          # install and fails loud). The snapshot also freezes the contract the plan was
+          # written against, per run, for audit.
+          command: >-
+            kk stage daily-script-style "${vars.work_dir}" "${vars.run_date}"
+      - kind: agent.run
+        # A rejected or failed plan must never halt the unattended daily run: the builder
+        # decides plan-vs-template from the file itself and falls back to templates.
+        onError: continue
+        options:
+          role: scribe
+          agent: ${vars.agent}
+          # ADR-115 error tier: keep this prompt <= 1000 chars.
+          input: |
+            Read ${vars.work_dir}/2-plan/${vars.run_date}_03_plan_plan.json — a JSON array of docs; use each doc's `id`; don't edit it. Also read the style contract ${vars.work_dir}/2-script/${vars.run_date}_08_script-write_style.md and obey its char caps and banned phrases.
+            For each doc write a `lead` (a spoken bridge into the title, not containing it) and an `insight` (why it matters, grounded only in that doc's facts).
+            Write an `intro` hooking today's actual themes and an `outro`; no greeting or sign-off — the builder adds both.
+            Output only the JSON object {"version":1,"intro":"…","outro":"…","items":[{"id":"…","lead":"…","insight":"…"}]} with one item per doc id to ${vars.work_dir}/2-script/${vars.run_date}_08_script-write_plan.json.
+          expectFile: ${vars.work_dir}/2-script/${vars.run_date}_08_script-write_plan.json
+          allowAppend: false
+
   - id: script
     description: "Compile the episode plan Doc[] into structured broadcast VoiceScript YAML Content"
     onEnter:
@@ -204,7 +275,7 @@ states:
             kk stage daily-wrap-docs "${vars.work_dir}" "${vars.run_date}" "${vars.voice_profile}"
 
   - id: generate
-    description: "Invoke voice driver plugin (vdriver var: ominivoice -> omni-voice-gen, voicebox -> voice-gen) to generate audio"
+    description: "Invoke voice driver plugin (vdriver var: ominivoice -> omni-voice-gen, voicebox -> voice-gen, gemini -> gemini-tts) to generate audio"
     onEnter:
       - kind: shell
         options:
@@ -228,12 +299,12 @@ states:
             kk stage daily-quality-report "${vars.work_dir}" "${vars.run_date}"
 
   - id: publish-prep
-    description: "Merge article Content with audio (podcast assembly facts ride the content options channel for podcast-pub's absorbed assembly; runDate kept for surfdash slug)"
+    description: "Merge article Content with the MP3 (rejects a non-.mp3 enclosure) and stamp its ID3 tags (podcast assembly facts ride the content options channel for podcast-pub's absorbed assembly; runDate kept for surfdash slug)"
     onEnter:
       - kind: shell
         options:
           command: >-
-            kk stage daily-publish-prep "${vars.work_dir}" "${vars.run_date}"
+            kk stage daily-publish-prep "${vars.work_dir}" "${vars.run_date}" "${vars.podcast_artist}" "${vars.podcast_album}"
 
   - id: publish-surfdash
     description: "Publish the merged Content to surfdash (single target); result lands in result.json — surfdash publishes first so show-notes can link the article (task 0118 seam reorder)"
@@ -259,6 +330,41 @@ states:
           command: >-
             kk stage daily-publish-podcast "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}"
 
+  - id: xhs-write
+    description: "Plan the XHS card series from the lead plan item via agent.run (title + note + N ordered cards), then render it through the pinned xhs-card/xhs-knowledge presets (E8); onError: continue — a failed plan or render skips the XHS target, never the run"
+    onEnter:
+      - kind: agent.run
+        # XHS is an independent, non-blocking target: a bad or failed plan must never halt the run.
+        # The render stage still fails loud; the publish state then skips naming the missing series.
+        onError: continue
+        options:
+          role: scribe
+          agent: ${vars.agent}
+          # ADR-115 error tier: keep this prompt <= 1000 chars.
+          input: |
+            Read ${vars.work_dir}/2-plan/${vars.run_date}_03_plan_plan.json — a JSON array of news docs; don't edit it.
+            Take item 1 only (its "title" and "metadata.brief") — the lead story.
+            Write a Xiaohongshu note: "title" (≤20 chars) and "body" (Chinese note ≤1000 chars, ending with 3-5 hashtags).
+            Write exactly ${vars.xhs_cards} cards: card 1 role "cover", the rest "content", except a final "closing". Each card carries "role", "copy" (Chinese on-card headline ≤12 chars), "points" (2-4 short Chinese bullets), "layout", "subject" (one concrete English visual scene), "sourcePoint" (the lead-story fact that card uses).
+            Ground every "copy", "points" and "sourcePoint" in that story alone — no invented facts. No text, letters, numbers, logos or real people in "subject".
+            Output strictly valid JSON {"title": "...", "body": "...", "cards": [...]} to ${vars.work_dir}/2-xhs/${vars.run_date}_18_xhs_plan.json.
+          expectFile: ${vars.work_dir}/2-xhs/${vars.run_date}_18_xhs_plan.json
+          allowAppend: false
+      - kind: shell
+        onError: continue
+        options:
+          command: >-
+            kk stage daily-xhs-render "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}" "${vars.xhs_cards}" "${vars.xhs_style}" "${vars.xhs_provider}" "${vars.xhs_model}"
+
+  - id: xhs-publish
+    description: "Publish the packaged card series to XHS — draft, or live only when xhs_live=true (ADR-022); independent and non-blocking: its outcome never enters publish_status. xhs-pub itself enforces a headless session preflight and a 24h publish/check cap (ADR-025), so a sessionless or capped run fails soft with a named reason and the run continues"
+    onEnter:
+      - kind: shell
+        onError: continue
+        options:
+          command: >-
+            kk stage daily-publish-xhs "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}" "${vars.xhs_live}"
+
   - id: publish
     description: "Classify the sequenced surfdash → podcast outcomes full|partial|none into publish-status.txt (exit 0 in all three — routing is transition-owned; task 0118: per-target classification over the merged result.json)"
     onEnter:
@@ -416,18 +522,43 @@ transitions:
       options:
         command: 'test "${vars.cover_enabled}" = "true" && test ! -f "${vars.work_dir}/2-cover/${vars.run_date}_07_cover_cover.png"'
 
+  # F613 R3: first match wins — the cover edge stays above script-write so the cover still
+  # generates before the plan is authored; script-write sits above the always `-> script` edges
+  # and skips itself when disabled, non-zh, or the plan/YAML already exists (resume cost).
+  - from: article
+    to: script-write
+    description: "script_write_enabled, zh, and neither today's plan nor VoiceScript exists -> author the script plan"
+    guard:
+      kind: shell
+      options:
+        command: 'test "${vars.script_write_enabled}" = "true" && test "${vars.language}" = "zh" && test ! -f "${vars.work_dir}/2-script/${vars.run_date}_08_script-write_plan.json" && test ! -f "${vars.work_dir}/2-script/${vars.run_date}_08_script_voicescript.yaml"'
+
   - from: article
     to: script
     description: "cover disabled or today's cover cached -> skip to script"
     guard:
       kind: always
 
+  - from: cover
+    to: script-write
+    description: "script_write_enabled, zh, and neither today's plan nor VoiceScript exists -> author the script plan"
+    guard:
+      kind: shell
+      options:
+        command: 'test "${vars.script_write_enabled}" = "true" && test "${vars.language}" = "zh" && test ! -f "${vars.work_dir}/2-script/${vars.run_date}_08_script-write_plan.json" && test ! -f "${vars.work_dir}/2-script/${vars.run_date}_08_script_voicescript.yaml"'
+
   - from: cover
     to: script
     description: "Cover generated -> build broadcast script"
     guard:
       kind: always
 
+  - from: script-write
+    to: script
+    description: "Script plan authored (ok or failed: onError continue) -> build the broadcast script"
+    guard:
+      kind: always
+
   - from: script
     to: wrap-docs
     description: "skip_review enabled -> bypass HITL review"
@@ -519,6 +650,26 @@ transitions:
     guard:
       kind: always
 
+  - from: publish-podcast
+    to: xhs-write
+    description: "xhs_enabled -> plan and render the XHS card series from the lead plan item; first-match-wins, so this sits above the classification edge (XHS is independent and never gates publish_status)"
+    guard:
+      kind: shell
+      options:
+        command: 'test "${vars.xhs_enabled}" = "true"'
+
+  - from: xhs-write
+    to: xhs-publish
+    description: "Card series planned and rendered (or failed: onError continue) -> publish the XHS draft"
+    guard:
+      kind: always
+
+  - from: xhs-publish
+    to: publish
+    description: "XHS dispatched (or skipped: onError continue) -> classify the surfdash/podcast outcomes; XHS contributes no target to the classification"
+    guard:
+      kind: always
+
   - from: publish-podcast
     to: publish
     description: "Podcast dispatched -> classify the per-target outcomes full|partial|none"