@gobing-ai/knowledge-kit 0.0.19 → 0.0.22

package/plugins/kk/scripts/kk-workflow-stages.ts

@@ -12,13 +12,21 @@
  *   wrap          [<override>] --in <voicescript.yaml> --out <docs.json> [--profile <name>]
  *   duration      <work_dir> <target_duration_min>
  *   render-storm  [<override>] --in <content.json> --out <content.md>
+ *   itc-outline-pick <work_dir>          (0149, body in the sibling itc-stages.ts)
+ *   itc-report       <work_dir> [max_revisions]  (0149, body in the sibling itc-stages.ts)
+ *   itc-materialize  <work_dir> <publish_live>   (0150, sibling)
+ *   itc-publish-plan <work_dir> <targets> <source_locale> <publish_live>  (0150, sibling)
+ *   itc-publish-fanout <work_dir> [--retry]   (0151, sibling)
+ *   itc-publish-next  <work_dir>              (0151, sibling)
  *
  * `validate` / `wrap` / `render-storm` resolve the shipped sibling sidecars and delegate to them;
  * nothing about those sidecars changed. The `prepare-*` verbs and `duration` keep the logic that
  * used to live inline in `plugins/kk/workflows/*.yaml`, message-for-message.
  *
- * Node/Bun builtins only — no @gobing-ai/* and no relative imports (the file is resolved from the
- * installed package or from a checkout).
+ * Node/Bun builtins only — no @gobing-ai/* and no cross-directory relative imports (the file is
+ * resolved from the installed package or from a checkout). The itc-* stages delegate to their
+ * same-directory sibling `itc-stages.ts`, imported lazily so a runner copy without the sibling
+ * still loads and fails loud with the remediation path.
  *
  * The YAML prelude resolves this file as `$pkg/plugins/kk/scripts/kk-workflow-stages.ts` where `pkg`
  * comes from `realpath "$(command -v kk)"` (the installed package root), and falls back to the
@@ -46,7 +54,7 @@ import {
     writeFileSync,
 } from 'node:fs';
 import { homedir } from 'node:os';
-import { basename, dirname, join, resolve } from 'node:path';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 
 const SCRIPTS_DIR = import.meta.dir;
 const VALIDATE_SIDECAR = 'validate-voicescript.ts';
@@ -63,6 +71,21 @@ function fail(message: string): never {
     process.exit(1);
 }
 
+/**
+ * Load the itc-* helper sibling lazily: this runner is resolved (and copied alone, e.g. by
+ * apps/cli/tests/kk-workflow-stages.test.ts) from installs where the sibling may be absent, so
+ * the itc-* stages fail loud with a remediation path instead of breaking every stage at load.
+ */
+async function loadItcStages(): Promise<typeof import('./itc-stages.ts')> {
+    try {
+        return await import('./itc-stages.ts');
+    } catch {
+        return fail(
+            'itc-stages.ts not found next to kk-workflow-stages.ts — install or refresh the kk package (bun link in a checkout)',
+        );
+    }
+}
+
 /** coreutils-style reason for the errno codes the staged file operations can hit. */
 const ERRNO_REASONS: Record<string, string> = {
     EACCES: 'Permission denied',
@@ -904,7 +927,14 @@ function dailyScript(args: string[]): void {
         sted('write', yamlOut, () => writeRaw(yamlOut, body));
         // R3 (task 0139): fresh writes are validated here; the script cache path is covered by
         // wrap-docs, which runs on every path that reaches audio.
-        assertScriptContent(yamlOut);
+        try {
+            assertScriptContent(yamlOut);
+        } catch (err) {
+            // A rejected fresh write would otherwise poison the isFile(yamlOut) cache: every
+            // resume skips regeneration and re-fails at wrap-docs. Drop it so retry regenerates.
+            unlinkSync(yamlOut);
+            throw err;
+        }
     });
 }
 
@@ -1306,6 +1336,17 @@ function dailyPatchSurfdash(args: string[]): void {
         const postPath = (sd.metadata as Record<string, unknown> | undefined)?.postPath;
         if (typeof postPath !== 'string' || postPath === '')
             failWith(1, 'patch-surfdash: surfdash result carries no postPath');
+        // Refuse before anything is written: surfdash's deploy.yml publishes from main, so a commit
+        // on any other branch is invisible to production. Placed here (after the input checks) so a
+        // refusal leaves the working tree untouched.
+        const head = spawnSync('git', ['-C', surfdashRoot, 'rev-parse', '--abbrev-ref', 'HEAD'])
+            .stdout?.toString()
+            .trim();
+        if (head !== 'main')
+            failWith(1, `patch-surfdash: refusing to commit on '${head}' — surfdash deploys from main`);
+        // Paths this run actually wrote, relative to surfdashRoot. `git add`/`commit` take these as a
+        // pathspec so the operator's unrelated staged work is never swept into the commit.
+        const written: string[] = [];
         const slugDir = dirname(postPath);
         const showNotesUrl = typeof pod.url === 'string' ? pod.url : '';
         const coverUrl = ((pod.metadata as Record<string, unknown> | undefined)?.imageUrl as string | undefined) ?? '';
@@ -1318,9 +1359,12 @@ function dailyPatchSurfdash(args: string[]): void {
         };
         let changed = 0;
         for (const [locale, dir] of [
+            // zh posts live under articles/zh/<slug>; en/ja under articles/<locale>/<slug> —
+            // two dirnames up, not one (20260919: `articles/zh/en/...` never existed, so en/ja
+            // were silently skipped by the not-published branch).
             ['zh', slugDir],
-            ['en', join(dirname(slugDir), 'en', basename(slugDir))],
-            ['ja', join(dirname(slugDir), 'ja', basename(slugDir))],
+            ['en', join(dirname(dirname(slugDir)), 'en', basename(slugDir))],
+            ['ja', join(dirname(dirname(slugDir)), 'ja', basename(slugDir))],
         ] as const) {
             const indexMd = join(dir, 'index.md');
             if (!existsSync(indexMd)) {
@@ -1330,17 +1374,38 @@ function dailyPatchSurfdash(args: string[]): void {
             let md = readFileSync(indexMd, 'utf-8');
             const fmEnd = md.indexOf('---', 3); // frontmatter is `---\n ... \n---\n`
             if (fmEnd < 0) failWith(1, `patch-surfdash: no frontmatter in ${indexMd}`);
-            if (!/^image:/m.test(md.slice(0, fmEnd))) {
-                let image = coverUrl;
-                if (image === '' && existsSync(localCover)) {
-                    // Fallback for pre-#6 runs: copy the local cover instead of a hosted URL.
+            // Upsert a single-line `key: 'value'`; the regex consumes folded-scalar continuation
+            // lines (`og_image: >-\n  https://...`) so multi-line publish output is replaced whole.
+            const upsertKey = (src: string, key: string, value: string): string => {
+                // YAML single-quoted scalars escape `'` as `''`; the replacement is a function so
+                // `$&`/`$1`/`$$` in the value are never expanded. Scope the match to the frontmatter
+                // (recomputed per call, since each upsert shifts offsets) so a body line starting with
+                // `image:` is not rewritten.
+                const end = src.indexOf('\n---', 3);
+                const fm = src.slice(0, end);
+                const body = src.slice(end);
+                const line = `${key}: '${value.replaceAll("'", "''")}'`;
+                const re = new RegExp(`^${key}:.*(?:\\n[ \\t]+.*)*`, 'm');
+                const next = re.test(fm)
+                    ? fm.replace(re, () => line)
+                    : fm.replace(/^publishDate: .*$/m, (m0) => `${m0}\n${line}`);
+                return next + body;
+            };
+            if (coverUrl !== '') {
+                // 20260919 prod feedback: the podcast-hosted cover URL wins even when surfdash-pub
+                // already wrote `image:` — its resolved og_image points at /content-posts/<slug>/
+                // assets/cover.png, which the deployed worker does not serve (404).
+                md = upsertKey(md, 'image', coverUrl);
+                md = upsertKey(md, 'og_image', coverUrl);
+            } else if (!/^image:/m.test(md.slice(0, fmEnd))) {
+                // Fallback for runs without a podcast cover: copy the local cover instead.
+                if (existsSync(localCover)) {
                     const assets = join(dir, 'assets');
                     mkdirSync(assets, { recursive: true });
                     copyFileSync(localCover, join(assets, 'cover.png'));
-                    image = './assets/cover.png';
-                }
-                if (image !== '') {
-                    md = md.replace(/^publishDate: .*$/m, (m0) => `${m0}\nimage: '${image}'\nog_image: '${image}'`);
+                    written.push(relative(surfdashRoot, join(assets, 'cover.png')));
+                    md = upsertKey(md, 'image', './assets/cover.png');
+                    md = upsertKey(md, 'og_image', './assets/cover.png');
                 }
             }
             if (showNotesUrl !== '' && !md.includes(showNotesUrl)) {
@@ -1348,6 +1413,7 @@ function dailyPatchSurfdash(args: string[]): void {
             }
             if (md !== readFileSync(indexMd, 'utf-8')) {
                 sted('write', indexMd, () => writeFileSync(indexMd, md));
+                written.push(relative(surfdashRoot, indexMd));
                 changed++;
             }
         }
@@ -1359,9 +1425,15 @@ function dailyPatchSurfdash(args: string[]): void {
             const r = spawnSync('git', ['-C', surfdashRoot, ...a]);
             if (r.status !== 0) failWith(1, `patch-surfdash: git ${a[0]} failed: ${r.stderr?.toString().trim()}`);
         };
-        git('add', 'content/posts/articles');
-        git('commit', '-m', `feat: cover + podcast cross-link for ${basename(slugDir)} (kk daily patch)`);
-        if (process.env.SURFDASH_AUTO_PUSH !== '0') git('push');
+        git('add', '--', ...written);
+        git(
+            'commit',
+            '-m',
+            `feat: cover + podcast cross-link for ${basename(slugDir)} (kk daily patch)`,
+            '--',
+            ...written,
+        );
+        if (process.env.SURFDASH_AUTO_PUSH !== '0') git('push', 'origin', 'main');
         console.log(
             `patch-surfdash: patched ${changed} post(s), committed${process.env.SURFDASH_AUTO_PUSH !== '0' ? ' + pushed' : ' (push skipped: SURFDASH_AUTO_PUSH=0)'}`,
         );
@@ -1626,8 +1698,43 @@ if (import.meta.main)
         case 'daily-translate-sync':
             dailyTranslateSync(rest);
             break;
+        case 'itc-outline-pick': {
+            const { itcOutlinePick } = await loadItcStages();
+            itcOutlinePick(rest);
+            break;
+        }
+        case 'itc-report': {
+            const { itcReport } = await loadItcStages();
+            itcReport(rest);
+            break;
+        }
+        case 'itc-materialize': {
+            const { itcMaterialize } = await loadItcStages();
+            itcMaterialize(rest);
+            break;
+        }
+        case 'itc-publish-plan': {
+            const { itcPublishPlan } = await loadItcStages();
+            itcPublishPlan(rest);
+            break;
+        }
+        case 'itc-publish-fanout': {
+            const { itcPublishFanout } = await loadItcStages();
+            itcPublishFanout(rest);
+            break;
+        }
+        case 'itc-publish-next': {
+            const { itcPublishNext } = await loadItcStages();
+            itcPublishNext(rest);
+            break;
+        }
+        case 'itc-adapt-verify': {
+            const { itcAdaptVerify } = await loadItcStages();
+            itcAdaptVerify(rest);
+            break;
+        }
         default:
             fail(
-                `unknown stage: ${stage ?? '(none)'} (expected prepare-itc|prepare-solo|prepare-storm|validate|wrap|duration|render-storm|daily-*)`,
+                `unknown stage: ${stage ?? '(none)'} (expected prepare-itc|prepare-solo|prepare-storm|validate|wrap|duration|render-storm|itc-*|daily-*)`,
             );
     }

package/plugins/kk/scripts/render-md.ts

@@ -101,6 +101,12 @@ function renderReferences(references: ContentInput['references']): string {
     return `\n\n## References\n\n${lines.join('\n')}`;
 }
 
+/** Escape `\\`, `[`, `]` so link text cannot terminate the `[title]` form early (0155 R4). */
+const escapeLinkText = (s: string): string => s.replace(/[\\[\]]/g, '\\$&');
+/** Percent-encode characters that would break the inline link destination `(url)` (0155 R4). */
+const escapeLinkUrl = (s: string): string =>
+    s.replace(/[ ()<>]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase().padStart(2, '0')}`);
+
 function renderReferenceLabel(ref: Ref): string {
     const { url, title, cite } = ref;
     const titleT = title?.trim() ?? '';
@@ -108,7 +114,7 @@ function renderReferenceLabel(ref: Ref): string {
     const citeT = cite?.trim() ?? '';
     let label: string;
     if (titleT !== '' && urlT !== '') {
-        label = `[${titleT}](${urlT})`;
+        label = `[${escapeLinkText(titleT)}](${escapeLinkUrl(urlT)})`;
     } else if (titleT !== '') {
         label = titleT;
     } else if (urlT !== '') {

package/plugins/kk/skills/article-adapt/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: article-adapt
+# Description rules: front-load the leading identity phrase; one trigger per genuine
+# branch (collapse synonym triggers into one); never restate the body's identity line.
+description: This skill should be used when a kk-itc publish plan contains variants with adapt=true and per-variant Content files must be written — "adapt the article", "translate for the target profile", "write content.zh-article.json", or when a spur workflow agent.run step invokes kk:article-adapt. Translates title and body to the variant locale, applies the plan limits, and preserves code blocks, URLs and references; it holds no platform table.
+---
+
+# article-adapt
+
+
+This skill adapts one published article into one Content file per `publish-plan.json` variant with
+`adapt: true`. It is deliberately **thin**: the plan (built from `TARGET_PROFILES` in
+`plugins/kk/scripts/itc-stages.ts`) carries the per-variant locale, format and limits — this skill
+holds **no platform table** and never decides which variants exist.
+
+## Inputs
+
+- `<work_dir>/4-publish/publish-plan.json` — `{live, sourceLocale, variants, fanout, browser}` where
+  each `variants[<locale>-<format>]` entry is
+  `{file, adapt, limits?, switches}`.
+- `<work_dir>/4-publish/content.json` — the source article (the `sourceLocale` materialized draft).
+
+## Output
+
+For every `variants[*]` entry with `adapt: true`, write
+`<work_dir>/4-publish/<entry.file>` (e.g. `content.zh-article.json`) as a Content JSON object:
+
+```json
+{
+  "title": "<translated title>",
+  "format": "<variant format suffix, e.g. article | wechat-article | short-note | short-post>",
+  "body": "<translated body>",
+  "metadata": { "coverImage": "...", "tags": [], "description": "..." },
+  "references": [{ "url": "...", "title": "...", "cite": "id" }]
+}
+```
+
+## Procedure
+
+1. Read the plan. Collect the variants whose `adapt` is `true`. If there are none, report that and
+   stop — do not write any file.
+2. For each such variant, read `content.json` and produce the variant file:
+   - **Translate** `title` and `body` into the variant locale (the locale is the part of the variant
+     key before the first `-`). Keep every code block, URL and inline link verbatim — never
+     translate code, identifiers, commands or URLs.
+   - **Carry over** `references[]`, `metadata.coverImage`, `metadata.tags`, `metadata.keywords` and
+     `metadata.description` unchanged.
+   - **Apply the limits** from the entry's `limits` (e.g. a max character count): trim the body
+     within the limit without dropping code blocks or breaking markdown; state in one closing line
+     that the full article is available at the source URL when content had to be cut.
+   - **Set `format`** to the variant key's format suffix (the part after the first `-`).
+3. Write the file with `metadata` present (at minimum `{}`). A valid Content object always has a
+   non-empty `title` and `body`.
+4. Report each written path as the last line of stdout.
+
+## Invariants
+
+- **Never set draft or live switch keys.** Do not write `metadata.published`,
+  `metadata.publishStatus` or `metadata.operation`: `itc-publish-fanout` stamps the plan's
+  `switches` into each variant's metadata at send time (V3 — the switch is deterministic code, not
+  model output).
+- **No platform knowledge.** If the plan names a variant, adapt it; if a limit is missing, adapt
+  without a limit. Never hard-code target names, locales or limits in this skill.
+- **Faithful translation.** Do not add, remove or reorder sections relative to the source body; the
+  approved outline's structure is preserved.
+
+## Gotchas
+
+1. **Read the plan, not the target list** — the plan, not `publish_targets`, is the adaptation
+   contract.
+2. **A missing source `content.json` is a blocking error** — the materialize state always writes it
+   before publish-plan; if it is absent, fail loudly instead of inventing content.
+3. **One file per adapt variant, exact path** — write `<entry.file>` under `4-publish/`; a
+   follow-up `kk stage itc-adapt-verify` step fails the workflow when a variant file is missing or
+   lacks `title`/`body`.
+
+## Platform Notes
+
+### Claude Code
+
+Invoked from a spur workflow `agent.run` step; the prompt supplies the work_dir path.
+
+### Codex / OpenClaw / OpenCode / Antigravity
+
+Run file reads/writes via the available file tools; arguments arrive in the step prompt.

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

@@ -19,8 +19,10 @@ vars:
   limit: "10"
   language: "zh"
   voice_profile: "robin-news"
-  # 20260917: voice driver switch — ominivoice (default, omni-voice-gen) | voicebox (voice-gen).
-  vdriver: "ominivoice"
+  # 20260917: voice driver switch — voicebox (default, voice-gen) | ominivoice (omni-voice-gen).
+  # 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"
   # 20260917 review #7: 8s intro sting prepended to every daily output; empty = skip.
   intro_music: ".works/kk-daily-ai-voice/AI每日资讯_8秒播客片头.mp3"
   # 20260917 review #4/#6: surfdash checkout the patch stage commits to.
@@ -463,8 +465,14 @@ transitions:
       kind: always
 
   - from: generate
+    to: intro-music
+    description: "Audio generated -> prepend intro sting"
+    guard:
+      kind: always
+
+  - from: intro-music
     to: quality-control
-    description: "Audio generated -> run quality control validation"
+    description: "Intro merged -> run quality control validation"
     guard:
       kind: always
 
@@ -518,10 +526,12 @@ transitions:
       kind: always
 
   - from: publish
-    to: patch-surfdash
-    description: "Publish classified -> patch surfdash posts with cover + podcast cross-link"
+    to: translate
+    description: "Publish classified -> full publish continues to en/ja translation; guard is full-only (partial exits via publish-partial); patch-surfdash runs after translate so all three locales get cover + podcast cross-link patching"
     guard:
-      kind: always
+      kind: shell
+      options:
+        command: 'test "${vars.publish_status}" = "full"'
 
   - from: patch-surfdash
     to: run-report
@@ -551,24 +561,24 @@ transitions:
     guard:
       kind: always
 
-  - from: run-report
-    to: translate
-    description: "Run report assembled after full publish -> scaffold + translate en/ja locales + sync"
+  - from: translate
+    to: patch-surfdash
+    description: "zh post + en/ja locales scaffolded, translated, and synced -> patch all published posts with cover + podcast cross-link"
     guard:
-      kind: shell
-      options:
-        command: 'test "${vars.publish_status}" = "full"'
+      kind: always
 
   - from: run-report
     to: done
-    description: "Run report assembled after partial publish -> done; retry failed targets later via kk executor fan-out --retry-from"
+    description: "Run report assembled after non-full publish (partial) -> done; retry failed targets later via kk executor fan-out --retry-from"
     guard:
       kind: shell
       options:
         command: 'test "${vars.publish_status}" = "partial"'
 
-  - from: translate
+  - from: run-report
     to: done
-    description: "zh post + en/ja locales scaffolded, translated, and synced into the surfdash CMS -> episode complete"
+    description: "Run report assembled after full publish -> episode complete (en/ja already translated and patched)"
     guard:
-      kind: always
+      kind: shell
+      options:
+        command: 'test "${vars.publish_status}" = "full"'