@gobing-ai/knowledge-kit 0.1.10 → 0.1.12

package/plugins/kk/scripts/voice3-publish-window.ts

@@ -0,0 +1,202 @@
+#!/usr/bin/env bun
+/**
+ * voice3-publish-window — cron-safe launcher for the voice3 shadow publish window (task 0334).
+ *
+ * WHY a launcher (audit F08/F09/F10, docs/design/kk-daily-ai-voice3.md):
+ * - cron ends a command at the first UNESCAPED % and feeds the rest to stdin, so any inline
+ *   `$(date +%Y%m%d)` shell in a crontab entry silently truncates the command. Date math and
+ *   flag assembly live here, in plain TypeScript, behind zero percent signs.
+ * - the publish window must read the GENERATION bundle (`<works>/kk-daily-ai-voice2/<date>/
+ *   bundle.json` — voice3 prepares under the voice2 namespace until the operator's cutover
+ *   changes it), never the publish3 output directory that earlier entries pointed at.
+ * - the CN consent token list is validated against the pinned preset's WINDOW rows before any
+ *   spur process starts; the old baked `wechatmp-pub,xhs-pub,…` list (tokens that have no
+ *   cn-peak row) is refused up front.
+ *
+ * Contract: everything before `spur workflow run plugins/kk/workflows/kk-daily-publish3.yaml`
+ * is preparation and refusal; the only side effects are refusal messages and, on success, the
+ * single spur exec. `KK_SPUR_BIN` pins the spur binary (same convention as board/capture.ts and
+ * decision-hub.ts); `--dry-run` prints the forwarded vars and stops (rehearsal aid).
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const USAGE =
+    'usage: voice3-publish-window.ts --window <after-generate|cn-peak|overseas-rss> [--run-date <YYYY-MM-DD|YYYYMMDD>] ' +
+    '[--preset <slug>] [--live-channels a,b] [--work-dir <dir>] [--dummy] [--dry-run]';
+
+const WINDOWS = new Set(['after-generate', 'cn-peak', 'overseas-rss']);
+
+function failWith(code: number, message: string): never {
+    console.error(message);
+    process.exit(code);
+}
+
+function expandHome(raw: string): string {
+    return raw === '~' || raw.startsWith('~/') ? join(homedir(), raw.slice(1)) : raw;
+}
+
+/** KK_WORKS_DIR env > config works_dir > <cwd>/.works — the kk-workflow-stages precedence. */
+function resolveWorksDir(): string {
+    const fromEnv = process.env.KK_WORKS_DIR;
+    if (fromEnv) return expandHome(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 resolve(process.cwd(), '.works');
+}
+
+/** A real calendar day as `YYYY-MM-DD`, or undefined (mirrors publish-matrix normalizeRunDate). */
+function normalizeRunDate(raw: string): string | undefined {
+    const match = /^(\d{4})-?(\d{2})-?(\d{2})$/.exec(raw.trim());
+    if (match === null) return undefined;
+    const iso = `${match[1]}-${match[2]}-${match[3]}`;
+    const parsed = new Date(`${iso}T00:00:00Z`);
+    if (
+        Number.isNaN(parsed.getTime()) ||
+        parsed.getUTCFullYear() !== Number(match[1]) ||
+        parsed.getUTCMonth() + 1 !== Number(match[2]) ||
+        parsed.getUTCDate() !== Number(match[3])
+    ) {
+        return undefined;
+    }
+    return iso;
+}
+
+/** Today (offset 0) or yesterday (offset -1) in America/Los_Angeles — the episodes' own day. */
+function losAngelesDate(offsetDays: number): string {
+    const instant = new Date(Date.now() + offsetDays * 24 * 60 * 60 * 1000);
+    // en-CA renders YYYY-MM-DD; Intl does the zone math cron cannot do inline.
+    return new Intl.DateTimeFormat('en-CA', { timeZone: 'America/Los_Angeles' }).format(instant);
+}
+
+/** `--flag value`, or undefined. */
+function flagValue(args: string[], flag: string): string | undefined {
+    const index = args.indexOf(flag);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+
+function main(): void {
+    const args = process.argv.slice(2);
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log(USAGE);
+        process.exit(0);
+    }
+    const window = flagValue(args, '--window');
+    if (window === undefined || !WINDOWS.has(window))
+        failWith(1, `${USAGE}\nvoice3-publish-window: --window must be one of ${[...WINDOWS].join('|')}`);
+    const dummy = args.includes('--dummy');
+    const dryRun = args.includes('--dry-run');
+    const preset = flagValue(args, '--preset');
+    const liveChannelsRaw = flagValue(args, '--live-channels');
+    const workDirOverride = flagValue(args, '--work-dir');
+
+    // R1: run date = explicit flag, else window-derived LA day (overseas reads the episode that
+    // landed after the 07:00 tick, i.e. yesterday).
+    const runDateRaw = flagValue(args, '--run-date');
+    let runDate: string | undefined;
+    if (runDateRaw !== undefined && runDateRaw.trim() !== '') {
+        runDate = normalizeRunDate(runDateRaw);
+        if (runDate === undefined)
+            failWith(1, `voice3-publish-window: '${runDateRaw}' is not a valid calendar day (YYYY-MM-DD or YYYYMMDD)`);
+    } else {
+        runDate = losAngelesDate(window === 'overseas-rss' ? -1 : 0);
+    }
+    const digits = runDate.replaceAll('-', '');
+
+    if (dummy && liveChannelsRaw !== undefined) {
+        failWith(1, 'voice3-publish-window: --dummy and --live-channels are mutually exclusive');
+    }
+
+    // R3/F10: live tokens validate against the pinned preset's WINDOW rows before any spawn.
+    const liveChannels =
+        liveChannelsRaw !== undefined && liveChannelsRaw.trim() !== ''
+            ? liveChannelsRaw
+                  .split(',')
+                  .map((token) => token.trim())
+                  .filter((token) => token !== '')
+            : [];
+    if (liveChannels.length > 0 && preset === undefined) {
+        failWith(1, 'voice3-publish-window: --live-channels requires an explicit --preset to validate the window');
+    }
+    if (liveChannels.length > 0) {
+        const scriptDir = dirname(fileURLToPath(import.meta.url));
+        const presetPath = join(dirname(scriptDir), 'publish-presets', `${preset}.json`);
+        if (!existsSync(presetPath))
+            failWith(1, `voice3-publish-window: preset '${preset}' not found at ${presetPath}`);
+        const parsed = JSON.parse(readFileSync(presetPath, 'utf-8')) as {
+            targets?: Array<{ plugin: string; id?: string; mode?: string; window?: string }>;
+        };
+        const targets = parsed.targets ?? [];
+        const inWindow = targets.filter((target) => (target.window ?? 'after-generate') === window);
+        const refused = liveChannels.filter((token) => {
+            const row = inWindow.find((target) => target.plugin === token || target.id === token);
+            return row === undefined || (row.mode ?? 'draft') === 'off';
+        });
+        if (refused.length > 0) {
+            failWith(
+                1,
+                `voice3-publish-window: live token(s) ${refused.join(', ')} have no active row in window '${window}' of preset '${preset}'` +
+                    ` (send-confirm resumes are consent-scoped per window; see docs/design/kk-daily-ai-voice3.md)`,
+            );
+        }
+    }
+
+    // R1/F08: the bundle is the GENERATION artifact under the voice2 namespace, never a publish3
+    // output dir. Mismatched/missing bundles refuse before spur starts.
+    const genDir =
+        workDirOverride !== undefined && workDirOverride.trim() !== ''
+            ? resolve(workDirOverride)
+            : join(resolveWorksDir(), 'kk-daily-ai-voice2', digits);
+    const bundlePath = join(genDir, 'bundle.json');
+    if (!existsSync(bundlePath)) failWith(1, `voice3-publish-window: no generation bundle at ${bundlePath}`);
+    let bundleRunDate: string | undefined;
+    try {
+        const bundle = JSON.parse(readFileSync(bundlePath, 'utf-8')) as { runDate?: string };
+        bundleRunDate = typeof bundle.runDate === 'string' ? normalizeRunDate(bundle.runDate) : undefined;
+    } catch {
+        failWith(1, `voice3-publish-window: unreadable generation bundle at ${bundlePath}`);
+    }
+    if (bundleRunDate !== runDate) {
+        failWith(
+            1,
+            `voice3-publish-window: bundle at ${bundlePath} is dated ${bundleRunDate ?? 'unknown'}, not the requested ${runDate}`,
+        );
+    }
+
+    const vars: Record<string, string> = {
+        work_dir: genDir,
+        run_date: digits,
+        window,
+    };
+    if (preset !== undefined && preset.trim() !== '') vars.preset = preset;
+    if (liveChannels.length > 0) vars.live_channels = liveChannels.join(',');
+    if (dummy) vars.dummy = 'true';
+
+    if (dryRun) {
+        console.log(JSON.stringify(vars, null, 2));
+        process.exit(0);
+    }
+
+    const proc = spawnSync(
+        process.env.KK_SPUR_BIN || 'spur',
+        ['workflow', 'run', 'plugins/kk/workflows/kk-daily-publish3.yaml', '--vars', JSON.stringify(vars)],
+        {
+            stdio: 'inherit',
+        },
+    );
+    // node spawnSync surfaces the child's code as `status` (exitCode is the async-API field).
+    process.exit(proc.status ?? 1);
+}
+
+main();

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

@@ -3,6 +3,7 @@ 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.
+requires: [cli:kk, cli:spur, local-fs]
 ---
 
 # article-adapt

package/plugins/kk/skills/audio-authoring/SKILL.md

@@ -6,6 +6,7 @@ description: >-
   "outline options for audio", "author a VoiceScript", "revise the script".
   Runs briefing → outline → script with explicit operator gates; solo mode
   ships first, dialogue/interview/narration are named extension points.
+requires: [local-fs]
 ---
 
 # audio-authoring — spoken-audio authoring (create | briefing | outline | script)

package/plugins/kk/skills/content-judge/SKILL.md

@@ -2,6 +2,7 @@
 name: content-judge
 description: This skill should be used when an LLM evaluation gate is needed in a knowledge-kit pipeline — "judge this content", "evaluate against rubric", "quality gate before publish", "check technical accuracy", "review brand tone", "compliance check", or when a spur workflow step of type `agent.run` targets the content-judge skill to emit a PASS/FAIL/NEEDS_REVISION verdict. Centralizes evaluation rubrics, prompt templates, and structured verdict emission for generated Content.
 version: 0.1.0
+requires: [cli:kk, cli:spur, local-fs]
 ---
 
 # content-judge — LLM-as-judge evaluation skill

package/plugins/kk/skills/content-safety/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: content-safety
 description: This skill should be used when a knowledge-kit pipeline or operator needs a content-safety / platform-admission review before publishing — "check this before publishing", "小宇宙/公众号/网易云/苹果播客 审核风险", "desensitize personal info", "verify disclosure and sourcing before publish". Detects admission risk per distribution platform, proposes honest revisions or exclusion, and escalates what it cannot verify. Quality scoring is content-judge's job.
+requires: [local-fs]
 ---
 
 # content-safety — pre-publication content-safety review

package/plugins/kk/skills/explain-things/SKILL.md

@@ -7,6 +7,7 @@ description: >-
   "how does X work", "ELI5", "like I'm 5", or "show me". Normal explanations are
   concise inline views; the ELI5 register is opt-in. This is not for content authoring,
   research, judging, publishing, or package/code review workflows.
+requires: [local-fs]
 ---
 
 # explain-things

package/plugins/kk/skills/image-authoring/SKILL.md

@@ -7,6 +7,7 @@ description: >-
   "list the image formats and styles". Three operations — generate,
   extract-style, list-presets — over named format and style presets, with a
   confirmation gate before any paid generation.
+requires: [cli:kk, cli:spur, local-fs]
 ---
 
 # image-authoring — image generation agent surface (generate | extract-style | list-presets)

package/plugins/kk/skills/itc-generating/SKILL.md

@@ -7,6 +7,7 @@ description: >-
   writing method", "generate an IT technical draft on X", "create a technical
   article for WeChat/English platforms". Orchestrates topic (outline + draft),
   optional storm-research, and optional content-judge without enlarging those skills.
+requires: [cli:kk, local-fs]
 ---
 
 # itc-generating — IT technical draft generation (method + orchestration)

package/plugins/kk/skills/publish/SKILL.md

@@ -6,6 +6,7 @@ description: >-
   `kk executor run` / `kk fanout` for file-cli and script channels; sequences
   agent-default CMS channels as workflow `agent.run` steps. Does not own
   transport.
+requires: [cli:kk, local-fs]
 ---
 
 # publish — leftover channel operator surface

package/plugins/kk/skills/smart-seo/SKILL.md

@@ -6,6 +6,7 @@ description: >-
   this saved audit", "explain these SEO findings", or "check GEO readiness". Read-only results: no
   site mutation, no ranking and no citation promises.
 version: 0.1.0
+requires: [cli:kk, cli:spur, local-fs]
 ---
 
 # smart-seo — evidence-grounded SEO/GEO audits

package/plugins/kk/skills/storm-research/SKILL.md

@@ -8,6 +8,7 @@ description: >-
   (prepare → ingest → generate → render) over the 0056 works layout. Research is separate from
   authoring: topic owns init→outline→draft and this skill never merges into topic.
 version: 0.1.0
+requires: [cli:kk, local-fs]
 ---
 
 # storm-research — STORM daily research (topic sentence XOR markdown file → content.md)

package/plugins/kk/skills/taste-unslop/SKILL.md

@@ -5,6 +5,7 @@ description: >-
   voice and substance — "make this sound human", "remove the AI tells", "audit this
   copy for canned patterns", "restore my voice after AI editing". Not for code,
   translation-only work, or proofreading that must preserve style.
+requires: [local-fs]
 ---
 
 # taste-unslop

package/plugins/kk/skills/topic/SKILL.md

@@ -7,6 +7,7 @@ description: >-
   Runs the topic-core authoring loop (init → outline → draft) through four
   operations with explicit operator gates and safe resume. knowledge-kit's
   cohesive topic-authoring core, harvested from the WT 7-stage wrappers.
+requires: [cli:kk, cli:spur, local-fs]
 ---
 
 # topic — topic-core authoring (create | init | outline | draft)

package/plugins/kk/skills/web-automation/SKILL.md

@@ -9,6 +9,7 @@ description: >-
   web-automation skill. Owns method and evidence; transport stays in kk
   plugins; orchestration is a @gobing-ai/ts-dual-workflow-engine
   transition-flow (see docs/design/web-automation-engine.md).
+requires: [cli:spur, local-fs]
 ---
 
 # web-automation — discover, enhance, automate with a real browser

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

@@ -7,6 +7,7 @@ description: >-
   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.
+requires: [cli:kk, local-fs]
 ---
 
 # xhs-images — source-grounded XHS card series (plan → render → package → handoff)