@gobing-ai/knowledge-kit 0.0.22 → 0.0.24

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

@@ -32,8 +32,9 @@
  * 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. 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.
+ * workflow reaches the same script through `kk stage` (apps/cli/src/stage.ts), which resolves a
+ * recognized checkout entry to this checked-in copy (never a stale `apps/cli/plugins/` stage) and an
+ * installed entry to its own package-shipped copy.
  *
  * 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 —
@@ -60,11 +61,39 @@ const SCRIPTS_DIR = import.meta.dir;
 const VALIDATE_SIDECAR = 'validate-voicescript.ts';
 const WRAP_SIDECAR = 'wrap-voicescript-doc.ts';
 const RENDER_SIDECAR = 'render-md.ts';
+// F613: the zh style contract the script-write prompt reads (snapshot stage) and dailynews-gen
+// consumes (DAILYNEWS_STYLE_FILE); no workflow var carries an override, so the chain is
+// $KK_WORKFLOWS_DIR -> package copy -> $HOME.
+const STYLE_SIDECAR = 'daily-voice-style.zh.md';
 const REVISE_COUNT = '.revise-count';
 // Post-translation title-dedup threshold (task 0138 R3). ponytail: the 2026-09-16 Gemini 3.8 Live
 // pair measures 0.417 zh title-only Jaccard, the nearest distinct pair 0.1 (4x margin). Character
 // bigrams need same-language input — pre-translate dedup over the mixed-language blend cannot work.
 const DEDUP_TITLE_THRESHOLD = 0.4;
+// F614: the daily cover renders through the shipped daily-news presets; the brief's subject is
+// the only per-run var. The format/style pins and the subject cap are part of the style
+// contract — changing the look means editing the preset files, not this stage.
+const COVER_FORMAT = 'daily-news-cover';
+const COVER_STYLE = 'daily-news';
+const COVER_SUBJECT_CAP = 240;
+// E8: the XHS card series. Format and style are pinned exactly like the cover's; only the copy is
+// model-authored. `XHS_MAX_CARDS` mirrors the format preset's own series guidance.
+const XHS_FORMAT = 'xhs-card';
+const XHS_MAX_CARDS = 10;
+const XHS_TITLE_CAP = 20;
+const XHS_BODY_CAP = 1000;
+const XHS_ROLES: readonly string[] = ['cover', 'content', 'closing'];
+
+/** One planned card, normalized: `index` zero-padded for the preset's artifact name. */
+interface XhsCard {
+    index: string;
+    role: string;
+    copy: string;
+    points: string[];
+    layout: string;
+    subject: string;
+    sourcePoint: string;
+}
 
 function fail(message: string): never {
     console.error(message);
@@ -414,6 +443,7 @@ const DAILY_DIRS = [
     '2-plan',
     '2-article',
     '2-cover',
+    '2-xhs',
     '2-script',
     '3-audio',
     '3-publish',
@@ -478,6 +508,12 @@ function pluginsArgs(pluginsPath: string): string[] {
 }
 
 /** `kk <args>` with the caller's env overrides; `soft` mirrors the shell's `|| true`. */
+// spur --async exports SPUR_EXPECTED_DEFINITION_DIGEST (its own worker's identity binding) into
+// every descendant env; a nested `spur workflow run` — postsurfing's publishing workflow under
+// surfdash-pub — resolves a DIFFERENT digest and refuses to start. Strip both launcher vars at
+// the nested-spur boundary (SPUR_WORKFLOW_RUN_ACTIVE is the older sibling guard, task 0133-era).
+const NESTED_SPUR_UNSET = ['SPUR_WORKFLOW_RUN_ACTIVE', 'SPUR_EXPECTED_DEFINITION_DIGEST'] as const;
+
 function kk(
     args: string[],
     options: { env?: Record<string, string>; unset?: readonly string[]; soft?: boolean } = {},
@@ -861,6 +897,76 @@ function dailyArticle(args: string[]): void {
     });
 }
 
+/**
+ * F614 R2/R4: validate the agent-written cover brief in the order R4 names — the first failing
+ * check is the fallback reason; `reason: null` carries the trimmed subject.
+ */
+function coverBrief(briefPath: string): { reason: string | null; subject: string } {
+    if (!isFile(briefPath)) return { reason: 'missing-brief', subject: '' };
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(readFileSync(briefPath, 'utf-8'));
+    } catch {
+        return { reason: 'invalid-json', subject: '' };
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { reason: 'invalid-json', subject: '' };
+    }
+    const subject = (parsed as Record<string, unknown>).subject;
+    if (typeof subject !== 'string') return { reason: 'no-subject', subject: '' };
+    const trimmed = subject.trim();
+    if (trimmed === '' || trimmed.length > COVER_SUBJECT_CAP) return { reason: 'subject-cap', subject: '' };
+    return { reason: null, subject: trimmed };
+}
+
+/**
+ * F614 R3: build the image-gen envelope from the day's cover brief and render it. The subject is
+ * the only model-authored input (the workflow's brief agent.run wrote it); format, style,
+ * provider and model are pinned by this stage so no caller can drift the look. A missing or
+ * invalid brief degrades to the format's default subject (R4) — a plugin failure still fails
+ * the stage, matching the pre-F614 cover behavior.
+ */
+function dailyCover(args: string[]): void {
+    const [workDir = '', runDate = '', pluginsPath = '', provider = '', model = '', fallback = ''] = args;
+    const briefPath = join(workDir, '2-cover', `${runDate}_07_cover-brief.json`);
+    const envPath = join(workDir, '2-cover', `${runDate}_07_cover_image-gen-in.json`);
+    const contentOut = join(workDir, '2-cover', 'content.json');
+    timed(workDir, 'cover', () => {
+        const brief = coverBrief(briefPath);
+        const vars: Record<string, string> = {};
+        if (brief.reason !== null) {
+            console.error(`cover brief: fallback (${brief.reason})`);
+        } else {
+            vars.subject = brief.subject;
+        }
+        const imageGen: Record<string, unknown> = {
+            job: 'cover',
+            format: COVER_FORMAT,
+            style: COVER_STYLE,
+            vars,
+            maxImages: 1,
+        };
+        if (provider !== '') imageGen.provider = provider;
+        if (model !== '') imageGen.model = model;
+        // D6 0166 R7: runtime-fallback opt-in. '' (the shipped var default) keeps strict fail-fast —
+        // F614's pinned look stays the default; 'true' = retry down AUTO_ORDER; anything else is a
+        // comma-split, trimmed candidate list. Unknown names are rejected by image-gen, not here.
+        if (fallback !== '') {
+            imageGen.fallback =
+                fallback === 'true'
+                    ? true
+                    : fallback
+                          .split(',')
+                          .map((s) => s.trim())
+                          .filter(Boolean);
+        }
+        sted('write', envPath, () =>
+            writeJsonText(envPath, [{ id: 'daily-cover', title: runDate, body: '', metadata: { imageGen } }]),
+        );
+        kk(['executor', 'run', 'image-gen', '--in', envPath, '--out', contentOut, ...pluginsArgs(pluginsPath)]);
+    });
+}
+
 function dailyCoverNormalize(args: string[]): void {
     const [workDir = '', runDate = ''] = args;
     // The pre-0133 shell had no timing trap, so this stage is not `timed`; it still fails through
@@ -878,15 +984,26 @@ function dailyCoverNormalize(args: string[]): void {
 }
 
 function coverNormalizeBody(workDir: string, runDate: string): void {
-    const png = join(workDir, '2-cover', 'content-cover-01.png');
-    const jpg = join(workDir, '2-cover', 'content-cover-01.jpg');
+    // F614 R5: the artifact name follows the format preset (`<stem>-<format>-NN.<ext>`,
+    // paths.ts), so normalize reads the path the plugin itself recorded in the manifest instead
+    // of a hard-coded name. The legacy content-cover-01.{png,jpg} paths stay as stale cleanup.
+    const legacyPng = join(workDir, '2-cover', 'content-cover-01.png');
+    const legacyJpg = join(workDir, '2-cover', 'content-cover-01.jpg');
     // Must match the name dailyPublishPrep and the article->cover workflow guard read:
     // `${runDate}_07_cover_cover.png` (a plain `cover-${runDate}.png` left options.coverPath
     // undefined and silently dropped the cover from both podcast and surfdash — 2026-09-16 run).
     const out = join(workDir, '2-cover', `${runDate}_07_cover_cover.png`);
-    const source = isFile(png) ? png : isFile(jpg) ? jpg : '';
-    if (source === '') failWith(1, 'cover normalize: no content-cover-01.{png,jpg} artifact');
-    if (source === jpg) {
+    const images = metadataOf(readJson(join(workDir, '2-cover', 'content.json'))).images;
+    const first = Array.isArray(images) ? images[0] : undefined;
+    const recorded =
+        first !== null && typeof first === 'object' && typeof (first as Record<string, unknown>).path === 'string'
+            ? ((first as Record<string, unknown>).path as string)
+            : '';
+    if (recorded === '' || !isFile(recorded)) {
+        failWith(1, 'cover normalize: no image artifact in 2-cover/content.json');
+    }
+    const source = recorded;
+    if (source.endsWith('.jpg') || source.endsWith('.jpeg')) {
         const sips = spawnSync('sips', ['-s', 'format', 'png', source, '--out', out], { stdio: 'ignore' });
         // Bun reports a missing binary as `status: undefined` (older versions: `null`) plus an
         // `error` object — the pre-0133 shell's `command -v sips` failed the same way.
@@ -899,16 +1016,236 @@ function coverNormalizeBody(workDir: string, runDate: string): void {
     } else {
         sted('mv', source, () => renameSync(source, out));
     }
-    for (const stale of [jpg, png]) {
+    for (const stale of new Set([legacyJpg, legacyPng, source])) {
         try {
             unlinkSync(stale);
         } catch {
-            // `rm -f` is silent when the file is already gone.
+            // `rm -f` is silent when the file is already gone (a renamed source lands here too).
         }
     }
     console.log(`cover normalized: ${runDate}_07_cover_cover.png`);
 }
 
+/** `metadata.images[0]` — the artifact the image-gen plugin recorded for one render. */
+function firstArtifact(content: Record<string, unknown> | null): Record<string, unknown> | null {
+    const images = metadataOf(content).images;
+    const first = Array.isArray(images) ? images[0] : undefined;
+    return first !== null && typeof first === 'object' ? (first as Record<string, unknown>) : null;
+}
+
+/**
+ * E8: validate the agent-written XHS card plan. The plan is the only model-authored input —
+ * format, style, provider and model are pinned by `dailyXhsRender`, matching F614's cover. Every
+ * check fails loud naming the field, so an unusable plan skips the XHS target visibly instead of
+ * publishing a partial card series (the owning state carries `onError: continue`).
+ */
+function xhsPlan(planPath: string, count: number): { title: string; body: string; cards: XhsCard[] } {
+    const parsed = requireJson(planPath, 'xhs plan');
+    const title = typeof parsed.title === 'string' ? parsed.title.trim() : '';
+    if (title === '' || title.length > XHS_TITLE_CAP) {
+        failWith(1, `xhs plan: title must be 1..${XHS_TITLE_CAP} chars, got ${title.length}`);
+    }
+    const body = typeof parsed.body === 'string' ? parsed.body.trim() : '';
+    if (body === '' || body.length > XHS_BODY_CAP) {
+        failWith(1, `xhs plan: body must be 1..${XHS_BODY_CAP} chars, got ${body.length}`);
+    }
+    const raw = parsed.cards;
+    if (!Array.isArray(raw) || raw.length !== count) {
+        failWith(1, `xhs plan: expected ${count} cards (xhs_cards), got ${Array.isArray(raw) ? raw.length : 0}`);
+    }
+    const cards = raw.map((entry, position): XhsCard => {
+        const card = (entry !== null && typeof entry === 'object' ? entry : {}) as Record<string, unknown>;
+        const label = `xhs plan: card ${position + 1}`;
+        const text = (key: string): string => {
+            const value = card[key];
+            if (typeof value !== 'string' || value.trim() === '') failWith(1, `${label} needs a non-empty '${key}'`);
+            return value.trim();
+        };
+        const role = text('role');
+        if (!XHS_ROLES.includes(role)) {
+            failWith(1, `${label} role must be one of ${XHS_ROLES.join('|')}, got '${role}'`);
+        }
+        if (position === 0 && role !== 'cover') failWith(1, `${label} must be role 'cover' (the series opens on it)`);
+        const points = card.points;
+        if (!Array.isArray(points) || points.length < 1 || points.length > 4) {
+            failWith(1, `${label} needs 1..4 'points', got ${Array.isArray(points) ? points.length : 0}`);
+        }
+        const bullets = points.map((point) => {
+            if (typeof point !== 'string' || point.trim() === '') failWith(1, `${label} has an empty point`);
+            return point.trim();
+        });
+        return {
+            index: `${position + 1}`.padStart(2, '0'),
+            role,
+            copy: text('copy'),
+            points: bullets,
+            layout: text('layout'),
+            subject: text('subject'),
+            sourcePoint: text('sourcePoint'),
+        };
+    });
+    return { title, body, cards };
+}
+
+/**
+ * E8: build one `image-gen` envelope per planned card, render them sequentially, and package the
+ * ordered card manifest + `Content` that `xhs-pub` consumes. Format, style, provider and model
+ * are pinned here (never model-authored), so the series cannot drift from its preset. Resume-safe:
+ * a card whose recorded artifact is still on disk is not re-rendered — and not re-billed.
+ */
+function dailyXhsRender(args: string[]): void {
+    const [workDir = '', runDate = '', pluginsPath = '', countArg = '', style = '', provider = '', model = ''] = args;
+    const count = Number.parseInt(countArg, 10);
+    const planPath = join(workDir, '2-xhs', `${runDate}_18_xhs_plan.json`);
+    const cardsDir = join(workDir, '2-xhs', 'cards');
+    const manifestPath = join(workDir, '2-xhs', 'cards.json');
+    const contentPath = join(workDir, '2-xhs', 'content.json');
+    timed(workDir, 'xhs-render', () => {
+        if (!Number.isInteger(count) || count < 1 || count > XHS_MAX_CARDS) {
+            failWith(1, `xhs render: xhs_cards must be 1..${XHS_MAX_CARDS}, got '${countArg}'`);
+        }
+        const plan = xhsPlan(planPath, count);
+        sted('mkdir', cardsDir, () => mkdirSync(cardsDir, { recursive: true }));
+        const images: Record<string, unknown>[] = [];
+        const cards: Record<string, unknown>[] = [];
+        for (const card of plan.cards) {
+            const out = join(cardsDir, `card-${card.index}.json`);
+            const promptPath = join(cardsDir, `card-${card.index}.prompt.txt`);
+            let artifact = firstArtifact(readJson(out));
+            if (artifact === null || !isFile(typeof artifact.path === 'string' ? artifact.path : '')) {
+                const envPath = join(cardsDir, `card-${card.index}.in.json`);
+                const imageGen: Record<string, unknown> = {
+                    job: 'free',
+                    format: XHS_FORMAT,
+                    style,
+                    vars: {
+                        role: card.role,
+                        layout: card.layout,
+                        headline: card.copy,
+                        points: card.points.join('\n'),
+                        subject: card.subject,
+                        language: '简体中文',
+                        index: card.index,
+                    },
+                    maxImages: 1,
+                };
+                if (provider !== '') imageGen.provider = provider;
+                if (model !== '') imageGen.model = model;
+                sted('write', envPath, () =>
+                    writeJsonText(envPath, [
+                        { id: `xhs-card-${card.index}`, title: runDate, body: '', metadata: { imageGen } },
+                    ]),
+                );
+                // Sequential on purpose: one provider call per card, and the first failure stops
+                // the spend — later cards stay unrendered for a resume run to pick up.
+                kk(['executor', 'run', 'image-gen', '--in', envPath, '--out', out, ...pluginsArgs(pluginsPath)]);
+                artifact = firstArtifact(requireJson(out, 'xhs render'));
+            }
+            if (artifact === null) failWith(1, `xhs render: card ${card.index} recorded no image artifact (${out})`);
+            const recorded = artifact.path;
+            if (typeof recorded !== 'string' || !isFile(recorded)) {
+                failWith(1, `xhs render: card ${card.index} image artifact is not on disk: '${String(recorded)}'`);
+            }
+            // `image-gen` writes the artifact beside `--out`; the publisher requires absolute paths.
+            const imagePath = resolve(recorded);
+            sted('write', promptPath, () =>
+                writeRaw(promptPath, typeof artifact.prompt === 'string' ? artifact.prompt : ''),
+            );
+            images.push({ ...artifact, path: imagePath });
+            cards.push({
+                index: card.index,
+                role: card.role,
+                sourcePoint: card.sourcePoint,
+                copy: card.copy,
+                layout: card.layout,
+                promptPath,
+                imagePath,
+                status: 'rendered',
+            });
+        }
+        sted('write', manifestPath, () => writeJsonText(manifestPath, { source: planPath, cards }));
+        sted('write', contentPath, () =>
+            writeJsonText(contentPath, {
+                title: plan.title,
+                body: plan.body,
+                format: 'text',
+                metadata: { images, publishStatus: 'draft' },
+            }),
+        );
+        console.log(`xhs render: ${cards.length} cards packaged in card order (${contentPath})`);
+    });
+}
+
+/** A single-target xhs Result, not the fan-out aggregate: `ok` plus `metadata.publishStatus`. */
+function xhsStatus(path: string): string {
+    const parsed = readJson(path);
+    if (parsed?.ok !== true) return '';
+    const status = metadataOf(parsed).publishStatus;
+    return status === 'public' || status === 'draft' ? status : '';
+}
+
+/**
+ * E8: publish the packaged card series through `xhs-pub`'s script driver. Draft by default; live
+ * only on an explicit launch-time `xhs_live=true` (ADR-022 — an unattended run never posts live on
+ * its own). Non-blocking by operator decision: a missing/expired XHS session or a changed console
+ * logs a loud failure and leaves the run alive, and the outcome never enters `publish_status`
+ * (surfdash + podcast remain the episode's publication contract).
+ */
+function dailyPublishXhs(args: string[]): void {
+    const [workDir = '', runDate = '', pluginsPath = '', live = 'false'] = args;
+    const content = join(workDir, '2-xhs', 'content.json');
+    const input = join(workDir, '3-publish', `${runDate}_19_publish-xhs_content.json`);
+    const result = join(workDir, '3-publish', `${runDate}_19_publish-xhs_result.json`);
+    const want = live === 'true' ? 'public' : 'draft';
+    timed(workDir, 'publish-xhs', () => {
+        // Cache on the *requested* status: a cached draft must not silently satisfy a later
+        // xhs_live=true re-run (that would report a live post that never happened).
+        if (xhsStatus(result) === want) {
+            console.log(`publish-xhs cached: ${want} already recorded in ${result}`);
+            return;
+        }
+        if (!isFile(content)) {
+            console.log(`publish-xhs: no card series at ${content} (render packaged none) — skip`);
+            return;
+        }
+        const packaged = requireJson(content, 'publish-xhs');
+        sted('write', input, () =>
+            writeJsonText(input, { ...packaged, metadata: { ...metadataOf(packaged), publishStatus: want } }),
+        );
+        // `soft` keeps the XHS target non-blocking: the plugin still writes its own failed Result
+        // and prints the failing step (login gate, upload, body, submit control), which is what the
+        // operator needs to re-run — never a silent skip.
+        const status = kk(['executor', 'run', 'xhs-pub', '--in', input, '--out', result, ...pluginsArgs(pluginsPath)], {
+            soft: true,
+        });
+        console.log(
+            status === 0
+                ? `publish-xhs: ${want} dispatched; outcome recorded in ${result}`
+                : `WARNING: publish-xhs — xhs-pub exited ${status}; XHS target skipped (run continues, see ${result})`,
+        );
+    });
+}
+
+/**
+ * F613 R1: snapshot the shipped style contract into the run's work dir. Spur workflows have no
+ * workflow-dir var, so the script-write prompt reads this copy — and the snapshot freezes the
+ * exact contract the run's plan was written against. Idempotent (an existing snapshot is kept);
+ * a missing sidecar is a broken install, so `requireSidecar` fails loud.
+ */
+function dailyScriptStyle(args: string[]): void {
+    const [workDir = '', runDate = ''] = args;
+    const snapshot = join(workDir, '2-script', `${runDate}_08_script-write_style.md`);
+    if (isFile(snapshot)) {
+        console.log(`script style cached: ${snapshot}`);
+        return;
+    }
+    const sidecar = requireSidecar('', STYLE_SIDECAR, 'daily-voice-style');
+    const scriptDir = join(workDir, '2-script');
+    sted('mkdir', scriptDir, () => mkdirSync(scriptDir, { recursive: true }));
+    sted('cp', snapshot, () => copyFileSync(sidecar, snapshot));
+    console.log(`script style snapshot: ${snapshot}`);
+}
+
 function dailyScript(args: string[]): void {
     const [workDir = '', runDate = '', pluginsPath = '', language = '', title = '', voiceProfile = ''] = args;
     const yamlOut = join(workDir, '2-script', `${runDate}_08_script_voicescript.yaml`);
@@ -920,7 +1257,16 @@ function dailyScript(args: string[]): void {
             return;
         }
         kk(['executor', 'run', 'dailynews-gen', '--in', planIn, '--out', contentOut, ...pluginsArgs(pluginsPath)], {
-            env: { DAILYNEWS_LANGUAGE: language, DAILYNEWS_TITLE: title, VOICEBOX_DEFAULT_PROFILE: voiceProfile },
+            env: {
+                DAILYNEWS_LANGUAGE: language,
+                DAILYNEWS_TITLE: title,
+                VOICEBOX_DEFAULT_PROFILE: voiceProfile,
+                // F613 R4: always passed as absolute paths — spawnPluginEntry runs plugins with
+                // cwd = the plugin package dir, so a relative workDir would silently miss the
+                // plan; a plan file absent at build time reports missing-plan (template fallback).
+                DAILYNEWS_SCRIPT_PLAN: resolve(join(workDir, '2-script', `${runDate}_08_script-write_plan.json`)),
+                DAILYNEWS_STYLE_FILE: resolve(resolveSidecar('', STYLE_SIDECAR)),
+            },
         });
         const body = readJson(contentOut)?.body;
         if (typeof body !== 'string') failWith(1, `script: ${contentOut} has no string body`);
@@ -965,7 +1311,11 @@ function dailyGenerate(args: string[]): void {
     const [workDir = '', runDate = '', pluginsPath = '', transcodeMp3 = '', vdriver = ''] = args;
     // 20260917 review: the workflow picks a voice driver by short name; both drivers' envs are
     // passed unconditionally so switching `vdriver` needs no shell changes. Unknown -> fail loud.
-    const VOICE_DRIVERS: Record<string, string> = { ominivoice: 'omni-voice-gen', voicebox: 'voice-gen' };
+    const VOICE_DRIVERS: Record<string, string> = {
+        ominivoice: 'omni-voice-gen',
+        voicebox: 'voice-gen',
+        gemini: 'gemini-tts',
+    };
     const voiceGenerator = VOICE_DRIVERS[vdriver];
     if (!voiceGenerator) {
         failWith(
@@ -1008,15 +1358,22 @@ function dailyIntro(args: string[]): void {
             console.log(`intro-music cached: ${contentPath}`);
             return;
         }
-        const rawFile = meta.mp3Path ?? meta.audioPath;
-        if (typeof rawFile !== 'string' || rawFile === '') {
+        // Merge from the raw lossless render; mp3Path is the derived publish artifact.
+        // Preferring mp3Path here made `<stem>.mp3` the concat input while the output
+        // suffix rewrite (`.wav` -> `.intro.wav`) no longer matched, so ffmpeg saw one
+        // path as both input #1 and output and aborted with "same as Input #1".
+        const candidates = [meta.audioPath, meta.mp3Path].filter(
+            (candidate): candidate is string => typeof candidate === 'string' && candidate !== '',
+        );
+        const rawFile = candidates.find((candidate) => existsSync(resolve(candidate))) ?? candidates[0];
+        if (rawFile === undefined) {
             failWith(1, 'intro-music: voice content carries no mp3Path/audioPath');
         }
         const introPath = resolve(introSrc);
         if (!existsSync(introPath)) failWith(1, `intro-music: intro file not found: ${introPath}`);
         const mainPath = resolve(rawFile);
         if (!existsSync(mainPath)) failWith(1, `intro-music: generated audio not found: ${mainPath}`);
-        const mergedPath = mainPath.replace(/\.wav$/, '.intro.wav');
+        const mergedPath = `${mainPath.replace(/\.(wav|mp3)$/i, '')}.intro.wav`;
         const probe = (file: string, entries: string): string =>
             spawnSync('ffprobe', [
                 '-v',
@@ -1110,8 +1467,50 @@ function dailyQualityReport(args: string[]): void {
     });
 }
 
+/**
+ * 0171 R3: Apple Podcasts reads the enclosure's ID3 tags, so the published MP3 carries
+ * title/artist/album/date. `-c copy` moves the audio frames without a re-encode, and the temp
+ * file + rename keeps a failed ffmpeg from truncating the episode in place. An empty value
+ * omits that tag rather than failing. The caller runs this after intro-music, whose mp3
+ * re-transcode would otherwise strip tags stamped earlier.
+ */
+function stampId3Tags(audioFile: string, title: string, runDate: string, artist: string, album: string): void {
+    const tmpFile = `${audioFile}.id3.tmp.mp3`;
+    const metadata: string[] = [];
+    const addTag = (name: string, value: string): void => {
+        if (value.trim() !== '') metadata.push('-metadata', `${name}=${value}`);
+    };
+    addTag('title', title);
+    addTag('artist', artist);
+    addTag('album', album);
+    // run_date is a digits-only stamp (`20260924`); ID3 wants `YYYY-MM-DD`.
+    const isoDate = /^\d{8}$/.test(runDate)
+        ? `${runDate.slice(0, 4)}-${runDate.slice(4, 6)}-${runDate.slice(6, 8)}`
+        : runDate;
+    addTag('date', isoDate);
+    const stamp = spawnSync('ffmpeg', [
+        '-y',
+        '-hide_banner',
+        '-loglevel',
+        'error',
+        '-i',
+        audioFile,
+        '-c',
+        'copy',
+        '-id3v2_version',
+        '3',
+        ...metadata,
+        tmpFile,
+    ]);
+    if (stamp.status !== 0 || !existsSync(tmpFile)) {
+        if (existsSync(tmpFile)) unlinkSync(tmpFile); // never leave a partial file beside the episode
+        failWith(1, `publish-prep: ffmpeg ID3 stamp failed: ${stamp.stderr?.toString().trim()}`);
+    }
+    sted('rename', audioFile, () => renameSync(tmpFile, audioFile));
+}
+
 function dailyPublishPrep(args: string[]): void {
-    const [workDir = '', runDate = ''] = args;
+    const [workDir = '', runDate = '', artist = '', album = ''] = args;
     const articlePath = join(workDir, '2-article', `${runDate}_06_article_content.json`);
     const audioPath = join(workDir, '3-audio', `${runDate}_11_generate_content.json`);
     const prepPath = join(workDir, '3-publish', `${runDate}_13_publish-prep_content.json`);
@@ -1124,6 +1523,12 @@ function dailyPublishPrep(args: string[]): void {
             failWith(1, 'publish-prep: voice content carries no mp3Path/audioPath');
         }
         const audioFile = resolve(rawFile);
+        // 0171 R2: publish-prep publishes metadata.mp3Path ?? audioPath, so a WAV here means
+        // transcode_mp3 was turned off — the run would ship an enclosure Apple Podcasts rejects.
+        if (!audioFile.endsWith('.mp3')) {
+            failWith(1, `publish-prep: resolved audio is not an MP3 (transcode_mp3 must be "true"): ${audioFile}`);
+        }
+        stampId3Tags(audioFile, typeof article.title === 'string' ? article.title : '', runDate, artist, album);
         const resolvedCover = resolve(coverPath);
         const hasCover = existsSync(resolvedCover);
         // podcast-pub's documented contract reads metadata.coverImage (map.ts); options.coverPath
@@ -1168,7 +1573,7 @@ function dailyPublishSurfdash(args: string[]): void {
                 ...pluginsArgs(pluginsPath),
             ],
             {
-                unset: ['SPUR_WORKFLOW_RUN_ACTIVE'],
+                unset: NESTED_SPUR_UNSET,
                 soft: true,
             },
         );
@@ -1487,6 +1892,8 @@ function dailyRunReport(args: string[]): void {
                 // 20260917 funnel: the blended fan-in input, rendered as the 语料构成
                 // source/category composition (absent -> omitted).
                 NEWS_REPORT_BLENDED_FILE: join(absWorkDir, '1-ingest', `${runDate}_02_collect_blended.json`),
+                // F613 R5: the script stage's Content, read best-effort (absent -> 脚本来源 omitted).
+                NEWS_REPORT_SCRIPT_FILE: join(absWorkDir, '2-script', `${runDate}_08_script_content.json`),
                 NEWS_REPORT_DATE: runDate,
             },
         });
@@ -1576,7 +1983,9 @@ function dailyTranslateSync(args: string[]): void {
         sted('write', sync, () =>
             writeJqText(sync, { body: '', options: { operation: 'sync', postPath: zhPostPath } }),
         );
-        kk(['executor', 'run', 'surfdash-pub', '--in', sync, '--out', syncResult, ...pluginsArgs(pluginsPath)]);
+        kk(['executor', 'run', 'surfdash-pub', '--in', sync, '--out', syncResult, ...pluginsArgs(pluginsPath)], {
+            unset: NESTED_SPUR_UNSET,
+        });
     });
 }
 
@@ -1650,9 +2059,18 @@ if (import.meta.main)
         case 'daily-article':
             dailyArticle(rest);
             break;
+        case 'daily-cover':
+            dailyCover(rest);
+            break;
         case 'daily-cover-normalize':
             dailyCoverNormalize(rest);
             break;
+        case 'daily-xhs-render':
+            dailyXhsRender(rest);
+            break;
+        case 'daily-script-style':
+            dailyScriptStyle(rest);
+            break;
         case 'daily-script':
             dailyScript(rest);
             break;
@@ -1680,6 +2098,9 @@ if (import.meta.main)
         case 'daily-publish-podcast':
             dailyPublishPodcast(rest);
             break;
+        case 'daily-publish-xhs':
+            dailyPublishXhs(rest);
+            break;
         case 'daily-publish-classify':
             dailyPublishClassify(rest);
             break;

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

@@ -28,11 +28,34 @@ not add a `kk publish` noun.
 | juejin | `juejin-pub` | `browser` / `agent` | workflow `agent.run` |
 | infoq | `infoq-pub` | `browser` / `agent` | workflow `agent.run` |
 | substack | `substack-pub` | `browser` / `agent` | workflow `agent.run` |
-| xhs | `xhs-pub` | `browser` / `agent` | workflow `agent.run` |
+| xhs | `xhs-pub` | `browser` / `script` | `kk executor run xhs-pub --in <content.json> --out <result.json>` — its default `script` driver uploads the ordered card images with Playwright `setInputFiles`; the `agent` driver fails loud for this channel (ADR-024) |
 
 Already-harvested file-cli channels (`qiita-pub`, `zenn-pub`, `surfdash-pub`,
 `emdash-pub`, `podcast-pub`) compose the same way.
 
+## XHS profile setup (0177)
+
+`xhs-pub` reuses the signed-in session at `~/.config/kk/browser-profiles/xhs`; kk stores no
+credentials. Before the first script-driver run (and after any session expiry), do a one-time
+headed login, then verify reuse read-only:
+
+```bash
+bun plugins/publishings/xhs-pub/src/profile-check.ts login   # headed; sign in once in the window
+bun plugins/publishings/xhs-pub/src/profile-check.ts check   # headless; exit 0 = session verified
+```
+
+`check` never signs in — with no saved profile it refuses (exit 1) instead of reporting success.
+Overrides: `--profile <dir>`, `--timeout <ms>`; env fallback `XHS_PROFILE_DIR` / `KK_BROWSER_PROFILE_DIR`.
+
+**ADR-025 (2026-09-28, after an XHS warning about automated activity).** Publish now runs this same
+check as a **preflight** before opening anything headed — so a missing or expired session is a fast
+refusal (`ok: false`) rather than a headed window sitting on the login gate for 120 s — and both
+console visits are capped at **one headed publish cycle + one session check per 24 h**
+(`~/.config/kk/xhs-automation.json`, override `KK_XHS_AUTOMATION_STATE`; a manual `check` draws on
+the same `check` budget). A capped or sessionless publish fails with `ok: false` and a named reason.
+`login` is never automated and never capped. Do not schedule XHS publishing: publish deliberately,
+by hand, at most once a day, and prefer a draft.
+
 ## Do not
 
 - Embed Playwright selectors or reimplement a transport here.