@gobing-ai/knowledge-kit 0.0.18 → 0.0.21

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

@@ -12,22 +12,32 @@
  *   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
  * cwd-relative `plugins/kk/scripts/kk-workflow-stages.ts` when that copy is absent — the checkout
- * tier kk-storm-research's render has always relied on, preserved on purpose.
+ * tier kk-storm-research's render has always relied on, preserved on purpose. The daily-voice
+ * workflow reaches the same script through `kk stage` (apps/cli/src/stage.ts), which applies the
+ * same two resolution tiers in TypeScript.
  *
- * SYNC: plugins/kk/workflows/{kk-solo-podcast,kk-itc,kk-storm-research,kk-daily-ai-voice}.yaml shell
- * this script. Keep message substrings stable — apps/cli/tests/kk-workflow-stages.test.ts and the
- * four workflow static tests match them.
+ * SYNC: plugins/kk/workflows/{kk-solo-podcast,kk-itc,kk-storm-research}.yaml shell this script
+ * (kk-daily-ai-voice goes through `kk stage`). Keep message substrings stable —
+ * apps/cli/tests/kk-workflow-stages.test.ts and the four workflow static tests match them.
  */
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
@@ -43,6 +53,7 @@ import {
     unlinkSync,
     writeFileSync,
 } from 'node:fs';
+import { homedir } from 'node:os';
 import { basename, dirname, join, resolve } from 'node:path';
 
 const SCRIPTS_DIR = import.meta.dir;
@@ -60,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',
@@ -534,15 +560,29 @@ function dailyPrepare(args: string[]): void {
         last30daysEnabled = '',
         topic = '',
         horizonHours = '',
+        runDateArg = '',
     ] = args;
-    const workDir = resolve(workDirArg);
-    timed(workDirArg, 'prepare', () => {
-        if (!workDirArg) failWith(1, 'missing required variable: work_dir');
+    // Empty work_dir composes the real workspace from the operator's works_dir
+    // (workflow-run.md §2 precedence: KK_WORKS_DIR > config works_dir > ~/.config/kk/works):
+    //   $works_dir/kk-daily-ai-voice/<stamp>
+    // The stamp is digits-only (dashes stripped from the caller's run_date, else today) so a
+    // resumed/retried run whose persisted run_date var already carries the digits-only
+    // run-date.txt value re-derives the same directory.
+    const dirDate = runDateArg ? runDateArg.replaceAll('-', '') : formatRunDate();
+    const workDir = resolve(workDirArg || join(resolveWorksDir(), 'kk-daily-ai-voice', dirDate));
+    timed(workDir, 'prepare', () => {
         for (const dir of DAILY_DIRS)
             sted('mkdir', join(workDir, dir), () => mkdirSync(join(workDir, dir), { recursive: true }));
         sted('write', join(workDir, 'run-date.txt'), () =>
-            writeFileSync(join(workDir, 'run-date.txt'), `${formatRunDate()}\n`),
+            writeFileSync(join(workDir, 'run-date.txt'), `${dirDate}\n`),
         );
+        // Anchor for the workflow: shell actions cannot set vars, so the YAML reads the
+        // effective work_dir back into vars.work_dir from this cwd-relative file.
+        const anchorDir = join('.spur', 'runs', 'kk-daily-ai-voice');
+        sted('write', join(anchorDir, 'work-dir.txt'), () => {
+            mkdirSync(anchorDir, { recursive: true });
+            writeFileSync(join(anchorDir, 'work-dir.txt'), `${workDir}\n`);
+        });
         sted('write', join(workDir, '1-ingest/source.json'), () =>
             writeJsonText(join(workDir, '1-ingest/source.json'), {
                 limit: Number(limit),
@@ -572,6 +612,35 @@ function formatRunDate(): string {
     return `${now.getFullYear()}${month}${day}`;
 }
 
+/** Expand the `~/` and `$HOME/` prefixes the config examples use. */
+function expandHome(p: string): string {
+    if (p.startsWith('~/')) return join(homedir(), p.slice(2));
+    if (p.startsWith('$HOME/')) return join(homedir(), p.slice('$HOME/'.length));
+    return p;
+}
+
+/**
+ * works_dir for composed daily workspaces — workflow-run.md §2 precedence:
+ * KK_WORKS_DIR env > config works_dir > compiled default ~/.config/kk/works.
+ * Unreadable/unparseable config falls through to the default (pluginEnvFromConfig
+ * tolerates the same), never fails the run.
+ */
+function resolveWorksDir(): string {
+    const fromEnv = process.env.KK_WORKS_DIR;
+    if (fromEnv) return fromEnv;
+    const configPath = process.env.KK_CONFIG || join(homedir(), '.config/kk/config.yaml');
+    if (existsSync(configPath)) {
+        try {
+            const parsed = Bun.YAML.parse(readFileSync(configPath, 'utf-8')) as Record<string, unknown> | null;
+            const worksDir = parsed !== null && typeof parsed === 'object' ? parsed.works_dir : undefined;
+            if (typeof worksDir === 'string' && worksDir !== '') return expandHome(worksDir);
+        } catch {
+            // fall through to the compiled default
+        }
+    }
+    return join(homedir(), '.config/kk/works');
+}
+
 function dailyCollectFacts(args: string[]): void {
     const [workDir = '', runDate = '', pluginsPath = ''] = args;
     const content = join(workDir, '2-facts', `${runDate}_02_collect_content.json`);
@@ -780,7 +849,9 @@ function dailyArticle(args: string[]): void {
             {
                 env: {
                     ARTICLE_DATE: runDate,
-                    ...(isFile(proseBody) ? { ARTICLE_BODY_FILE: proseBody } : {}),
+                    // Plugin entries run with cwd = plugin dir (invoke.ts), so relative
+                    // paths in env must be resolved or the plugin sees ENOENT.
+                    ...(isFile(proseBody) ? { ARTICLE_BODY_FILE: resolve(proseBody) } : {}),
                 },
             },
         );
@@ -856,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;
+        }
     });
 }
 
@@ -1270,9 +1348,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)) {
@@ -1282,17 +1363,28 @@ 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 => {
+                const line = `${key}: '${value}'`;
+                const re = new RegExp(`^${key}:.*(?:\\n[ \\t]+.*)*`, 'm');
+                if (re.test(src)) return src.replace(re, line);
+                return src.replace(/^publishDate: .*$/m, (m0) => `${m0}\n${line}`);
+            };
+            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}'`);
+                    md = upsertKey(md, 'image', './assets/cover.png');
+                    md = upsertKey(md, 'og_image', './assets/cover.png');
                 }
             }
             if (showNotesUrl !== '' && !md.includes(showNotesUrl)) {
@@ -1578,8 +1670,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/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.