@gobing-ai/knowledge-kit 0.0.17 → 0.0.19

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

@@ -23,11 +23,13 @@
  * 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 +45,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;
@@ -500,6 +503,16 @@ function metadataOf(value: Record<string, unknown> | null): Record<string, unkno
     return metadata !== null && typeof metadata === 'object' ? (metadata as Record<string, unknown>) : {};
 }
 
+/**
+ * Required stage input: a missing or unparsable file fails the stage naming the path, so a
+ * run-date/path mismatch surfaces as its real cause instead of a downstream "field missing" error.
+ */
+function requireJson(path: string, label: string): Record<string, unknown> {
+    const parsed = readJson(path);
+    if (parsed === null) failWith(1, `${label}: required input not found or unparsable: ${path}`);
+    return parsed;
+}
+
 /** `jq -e '.targets[]? | select(.target == t and .ok == true and .status == "published")'`. */
 function targetPublished(path: string, target: string): boolean {
     const parsed = readJson(path);
@@ -524,15 +537,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),
@@ -562,6 +589,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`);
@@ -752,6 +808,10 @@ function dailyArticle(args: string[]): void {
             console.log(`article cached: ${articleMd}`);
             return;
         }
+        // Agent-written prose body (workflow `article-write` state) replaces the mechanical
+        // per-item render when present — the 3-format split: surfdash gets an article,
+        // not a news list (2026-09-16 feedback).
+        const proseBody = join(workDir, '2-article', `${runDate}_06_article-write_body.md`);
         kk(
             [
                 'executor',
@@ -764,7 +824,12 @@ function dailyArticle(args: string[]): void {
                 ...pluginsArgs(pluginsPath),
             ],
             {
-                env: { ARTICLE_DATE: runDate },
+                env: {
+                    ARTICLE_DATE: runDate,
+                    // 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) } : {}),
+                },
             },
         );
         const body = readJson(articleContent)?.body;
@@ -792,7 +857,10 @@ 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');
-    const out = join(workDir, '2-cover', `cover-${runDate}.png`);
+    // 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) {
@@ -815,7 +883,7 @@ function coverNormalizeBody(workDir: string, runDate: string): void {
             // `rm -f` is silent when the file is already gone.
         }
     }
-    console.log(`cover normalized: cover-${runDate}.png`);
+    console.log(`cover normalized: ${runDate}_07_cover_cover.png`);
 }
 
 function dailyScript(args: string[]): void {
@@ -864,7 +932,17 @@ function dailyWrapDocs(args: string[]): void {
 }
 
 function dailyGenerate(args: string[]): void {
-    const [workDir = '', runDate = '', pluginsPath = '', transcodeMp3 = '', voiceGenerator = ''] = args;
+    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 voiceGenerator = VOICE_DRIVERS[vdriver];
+    if (!voiceGenerator) {
+        failWith(
+            1,
+            `generate: unknown vdriver '${vdriver}' (expected one of: ${Object.keys(VOICE_DRIVERS).join(', ')})`,
+        );
+    }
     const docs = join(workDir, '3-audio', `${runDate}_10_wrap-docs_docs.json`);
     const content = join(workDir, '3-audio', `${runDate}_11_generate_content.json`);
     timed(workDir, 'generate', () => {
@@ -881,6 +959,111 @@ function dailyGenerate(args: string[]): void {
     });
 }
 
+/**
+ * 20260917 review #7: prepend the show's 8s intro sting to the generated audio.
+ * `intro_music` empty -> skip. Writes `<stem>.intro.wav` (original render kept), points
+ * `audioPath` at the merged file, extends `duration`, marks `introMerged` (idempotent).
+ */
+function dailyIntro(args: string[]): void {
+    const [workDir = '', runDate = '', introSrc = ''] = args;
+    if (!introSrc || introSrc.trim() === '') {
+        console.log('intro-music: intro_music var empty — skip');
+        return;
+    }
+    const contentPath = join(workDir, '3-audio', `${runDate}_11_generate_content.json`);
+    timed(workDir, 'intro-music', () => {
+        const content = requireJson(contentPath, 'intro-music');
+        const meta = metadataOf(content);
+        if (meta.introMerged === true) {
+            console.log(`intro-music cached: ${contentPath}`);
+            return;
+        }
+        const rawFile = meta.mp3Path ?? meta.audioPath;
+        if (typeof rawFile !== 'string' || rawFile === '') {
+            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 probe = (file: string, entries: string): string =>
+            spawnSync('ffprobe', [
+                '-v',
+                'error',
+                '-select_streams',
+                'a:0',
+                '-show_entries',
+                entries,
+                '-of',
+                'csv=p=0',
+                file,
+            ])
+                .stdout?.toString()
+                .trim() ?? '';
+        const mainDur = Number.parseFloat(probe(mainPath, 'format=duration'));
+        const introDur = Number.parseFloat(probe(introPath, 'format=duration'));
+        if (!Number.isFinite(mainDur) || !Number.isFinite(introDur)) {
+            failWith(1, `intro-music: ffprobe could not read durations (main=${mainDur} intro=${introDur})`);
+        }
+        const rate = probe(mainPath, 'stream=sample_rate') || '24000'; // match the generated audio's rate; mono s16 both sides
+        const norm = (label: string): string =>
+            `[${label}:a]aresample=${rate},aformat=sample_fmts=s16:channel_layouts=mono[${label}]`;
+        const fc = `${norm('0')};${norm('1')};[0][1]concat=n=2:v=0:a=1[out]`;
+        const conv = spawnSync('ffmpeg', [
+            '-y',
+            '-hide_banner',
+            '-loglevel',
+            'error',
+            '-i',
+            introPath,
+            '-i',
+            mainPath,
+            '-filter_complex',
+            fc,
+            '-map',
+            '[out]',
+            '-c:a',
+            'pcm_s16le',
+            mergedPath,
+        ]);
+        if (conv.status !== 0 || !existsSync(mergedPath)) {
+            failWith(1, `intro-music: ffmpeg concat failed: ${conv.stderr?.toString().trim()}`);
+        }
+        if (meta.mp3Path && typeof meta.mp3Path === 'string') {
+            // transcode_mp3=true: keep the mp3 path honest by re-transcoding the merged wav.
+            const mp3 = spawnSync('ffmpeg', [
+                '-y',
+                '-hide_banner',
+                '-loglevel',
+                'error',
+                '-i',
+                mergedPath,
+                '-codec:a',
+                'libmp3lame',
+                '-qscale:a',
+                '2',
+                resolve(meta.mp3Path),
+            ]);
+            if (mp3.status !== 0) failWith(1, `intro-music: mp3 re-transcode failed: ${mp3.stderr?.toString().trim()}`);
+        }
+        const mergedDur = Number.parseFloat(probe(mergedPath, 'format=duration')) || mainDur + introDur;
+        const updated = {
+            ...content,
+            metadata: {
+                ...meta,
+                audioPath: mergedPath,
+                duration: mergedDur,
+                introMerged: true,
+            },
+        };
+        sted('write', contentPath, () => writeJsonText(contentPath, updated));
+        console.log(
+            `intro-music: merged ${introDur.toFixed(1)}s intro -> ${mergedPath} (${mergedDur.toFixed(1)}s total)`,
+        );
+    });
+}
+
 function dailyQualityReport(args: string[]): void {
     const [workDir = '', runDate = ''] = args;
     const content = join(workDir, '3-audio', `${runDate}_11_generate_content.json`);
@@ -904,7 +1087,7 @@ function dailyPublishPrep(args: string[]): void {
     const prepPath = join(workDir, '3-publish', `${runDate}_13_publish-prep_content.json`);
     const coverPath = join(workDir, '2-cover', `${runDate}_07_cover_cover.png`);
     timed(workDir, 'publish-prep', () => {
-        const article = readJson(articlePath) ?? {};
+        const article = requireJson(articlePath, 'publish-prep');
         const audioMeta = metadataOf(readJson(audioPath));
         const rawFile = audioMeta.mp3Path ?? audioMeta.audioPath;
         if (typeof rawFile !== 'string' || rawFile === '') {
@@ -912,13 +1095,21 @@ function dailyPublishPrep(args: string[]): void {
         }
         const audioFile = resolve(rawFile);
         const resolvedCover = resolve(coverPath);
+        const hasCover = existsSync(resolvedCover);
+        // podcast-pub's documented contract reads metadata.coverImage (map.ts); options.coverPath
+        // alone was silently dropped by the mapper — episodes published without a cover.
         const merged = {
             ...article,
-            metadata: { ...metadataOf(article), audioFile, runDate },
+            metadata: {
+                ...metadataOf(article),
+                audioFile,
+                runDate,
+                ...(hasCover ? { coverImage: resolvedCover } : {}),
+            },
             options: {
                 audioFile,
                 durationSec: audioMeta.duration,
-                coverPath: existsSync(resolvedCover) ? resolvedCover : undefined,
+                coverPath: hasCover ? resolvedCover : undefined,
             },
         };
         sted('write', prepPath, () => writeJsonText(prepPath, merged));
@@ -964,6 +1155,9 @@ function dailyShowNotes(args: string[]): void {
     const result = join(workDir, '3-publish', `${runDate}_14_publish-surfdash_result.json`);
     const out = join(workDir, '3-publish', `${runDate}_15_show-notes_show-notes.md`);
     const plan = join(workDir, '2-plan', `${runDate}_03_plan_plan.json`);
+    // Generated-episode content carries `metadata.segments[]` — the source of real
+    // audio offsets for the show-notes timeline (jump-to-item timestamps).
+    const audioContent = join(workDir, '3-audio', `${runDate}_11_generate_content.json`);
     timed(workDir, 'show-notes', () => {
         const effective = readJson(article)?.title;
         const titleArg = title !== '' ? title : typeof effective === 'string' ? effective : '';
@@ -974,6 +1168,7 @@ function dailyShowNotes(args: string[]): void {
                 PODCAST_PUB_RUN_DATE: runDate,
                 PODCAST_PUB_BRIEF_MODE: 'true',
                 PODCAST_PUB_ARTICLE_POST_PATH: postPath,
+                ...(isFile(audioContent) ? { PODCAST_PUB_AUDIO_CONTENT: audioContent } : {}),
             },
         });
     });
@@ -1004,7 +1199,7 @@ function dailyPublishPodcast(args: string[]): void {
             return;
         }
         try {
-            const content = readJson(prep) ?? {};
+            const content = requireJson(prep, 'publish-podcast');
             const showNotes = readFileSync(notes, 'utf-8');
             const merged = { ...content, metadata: { ...metadataOf(content), showNotes } };
             sted('write', prep, () => writeJsonText(prep, merged));
@@ -1084,6 +1279,95 @@ function dailyPublishPartial(args: string[]): void {
     });
 }
 
+/**
+ * 20260917 review #4/#6: after both publishes land, patch the surfdash disk posts —
+ * reuse the podcast-hosted cover URL in frontmatter (image/og_image; no re-upload; fallback:
+ * copy the local cover into assets/) and append a podcast cross-link at the end of zh/en/ja.
+ * Idempotent per post; commits + pushes the surfdash checkout (SURFDASH_AUTO_PUSH=0 keeps commit-only).
+ */
+function dailyPatchSurfdash(args: string[]): void {
+    const [workDir = '', runDate = '', surfdashRoot = ''] = args;
+    if (!surfdashRoot || !existsSync(surfdashRoot)) {
+        console.log(`patch-surfdash: surfdash root '${surfdashRoot}' not found — skip`);
+        return;
+    }
+    timed(workDir, 'patch-surfdash', () => {
+        const sdResult = join(workDir, '3-publish', `${runDate}_14_publish-surfdash_result.json`);
+        const podcastResult = join(workDir, '3-publish', `${runDate}_16_publish-podcast_result.json`);
+        if (!isFile(sdResult) || !isFile(podcastResult)) {
+            failWith(1, 'patch-surfdash: missing surfdash/podcast publish results — run the publish states first');
+        }
+        const targetOf = (path: string): Record<string, unknown> => {
+            const parsed = readJson(path) as { targets?: Array<Record<string, unknown>> };
+            return parsed.targets?.[0] ?? {};
+        };
+        const sd = targetOf(sdResult);
+        const pod = targetOf(podcastResult);
+        const postPath = (sd.metadata as Record<string, unknown> | undefined)?.postPath;
+        if (typeof postPath !== 'string' || postPath === '')
+            failWith(1, 'patch-surfdash: surfdash result carries no postPath');
+        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) ?? '';
+        const localCover = join(workDir, '2-cover', `${runDate}_07_cover_cover.png`);
+        const dateIso = `${runDate.slice(0, 4)}-${runDate.slice(4, 6)}-${runDate.slice(6, 8)}`;
+        const crossLink: Record<string, string> = {
+            zh: `🎧 本期已同步制作为播客节目，[点击收听《每日 AI 资讯 · ${dateIso}》](${showNotesUrl})。`,
+            en: `🎧 This episode is also available as a podcast: [listen to the Daily AI Briefing · ${dateIso}](${showNotesUrl}).`,
+            ja: `🎧 本エピソードはポッドキャストでも配信中：[Daily AI Briefing · ${dateIso} を聴く](${showNotesUrl})。`,
+        };
+        let changed = 0;
+        for (const [locale, dir] of [
+            ['zh', slugDir],
+            ['en', join(dirname(slugDir), 'en', basename(slugDir))],
+            ['ja', join(dirname(slugDir), 'ja', basename(slugDir))],
+        ] as const) {
+            const indexMd = join(dir, 'index.md');
+            if (!existsSync(indexMd)) {
+                console.log(`patch-surfdash: ${locale} post not published (${indexMd}) — skip`);
+                continue;
+            }
+            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.
+                    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}'`);
+                }
+            }
+            if (showNotesUrl !== '' && !md.includes(showNotesUrl)) {
+                md = `${md.replace(/\s*$/, '')}\n\n${crossLink[locale]}\n`;
+            }
+            if (md !== readFileSync(indexMd, 'utf-8')) {
+                sted('write', indexMd, () => writeFileSync(indexMd, md));
+                changed++;
+            }
+        }
+        if (changed === 0) {
+            console.log('patch-surfdash: nothing to change');
+            return;
+        }
+        const git = (...a: 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');
+        console.log(
+            `patch-surfdash: patched ${changed} post(s), committed${process.env.SURFDASH_AUTO_PUSH !== '0' ? ' + pushed' : ' (push skipped: SURFDASH_AUTO_PUSH=0)'}`,
+        );
+    });
+}
+
 function dailyRunReport(args: string[]): void {
     const [
         workDir = '',
@@ -1108,6 +1392,9 @@ function dailyRunReport(args: string[]): void {
             return;
         }
         sted('write', cands, () => writeJqText(cands, metadataOf(readJson(candidates)).docs ?? []));
+        // Plugin env paths must be absolute: spawnPluginEntry runs plugins with cwd = the
+        // plugin package dir, so a relative workDir silently misses every best-effort read.
+        const absWorkDir = resolve(workDir);
         kk(['executor', 'run', 'news-report-gen', '--in', cands, '--out', reportJson, ...pluginsArgs(pluginsPath)], {
             env: {
                 QC_MIN_QUALITY: minQuality,
@@ -1115,13 +1402,19 @@ function dailyRunReport(args: string[]): void {
                 QC_MIN_URGENCY: minUrgency,
                 QC_MIN_IMPACT: minImpact,
                 NEWS_REPORT_REJECTED_FILE: join(
-                    workDir,
+                    absWorkDir,
                     '2-plan',
                     `${runDate}_04_quality-control-content_candidates.rejected.json`,
                 ),
-                NEWS_REPORT_TIMING_FILE: join(workDir, 'step-timing.json'),
+                NEWS_REPORT_TIMING_FILE: join(absWorkDir, 'step-timing.json'),
                 // 0139 R5b: the generate stage's QC audit, read best-effort (absent -> section omitted).
-                NEWS_REPORT_QC_FILE: join(workDir, '3-audio', `${runDate}_11_generate_content.json`),
+                NEWS_REPORT_QC_FILE: join(absWorkDir, '3-audio', `${runDate}_11_generate_content.json`),
+                // 20260917 funnel: the plan stage's full selection trail (every fetched title +
+                // scores + disposition), rendered as the 选稿漏斗 section (absent -> omitted).
+                NEWS_REPORT_PLAN_AUDIT_FILE: join(absWorkDir, '2-plan', `${runDate}_03_plan_plan.json.audit.json`),
+                // 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`),
                 NEWS_REPORT_DATE: runDate,
             },
         });
@@ -1132,68 +1425,78 @@ function dailyRunReport(args: string[]): void {
     });
 }
 
-function dailyTranslateEn(args: string[]): void {
+/**
+ * Collapsed translate scaffolding (2026-09-16 feedback): surfdash-pub owns the
+ * deterministic mechanics — `scaffold-locale` for both target locales — while the
+ * workflow `translate` state's agent step owns the LLM translation of the drafts.
+ * Writes one marker file per locale (zh post path + en/ja draft paths); empty
+ * marker = locale absent (callers skip). Reuses an existing on-disk draft as the
+ * cache across run retries — re-scaffolding would erase the agent's translation.
+ */
+function dailyTranslateLocalize(args: string[]): void {
     const [workDir = '', runDate = '', pluginsPath = ''] = args;
     const result = join(workDir, '3-publish', `${runDate}_17_publish_result.json`);
-    const zhFile = join(workDir, '3-publish', `${runDate}_20_translate-en_zh-post-path.txt`);
-    const enFile = join(workDir, '3-publish', `${runDate}_20_translate-en_en-post-path.txt`);
-    const scaffold = join(workDir, '3-publish', `${runDate}_20_translate-en_scaffold-en.json`);
-    const scaffoldResult = join(workDir, '3-publish', `${runDate}_20_translate-en_scaffold-en-result.json`);
-    timed(workDir, 'translate-en', () => {
+    const zhFile = join(workDir, '3-publish', `${runDate}_20_translate-localize_zh-post-path.txt`);
+    timed(workDir, 'translate-localize', () => {
         const postPath = firstPostPath(readJson(result), 'surfdash-pub');
         const zh = postPath.endsWith('index.md') ? postPath : '';
         sted('write', zhFile, () => writeRaw(zhFile, zh));
-        const en = zh.replace('/zh/', '/en/');
-        sted('write', enFile, () => writeRaw(enFile, en));
-        if (zh === '') {
-            console.log('no zh post path — skip translate-en');
-            return;
-        }
-        if (isFile(en)) {
-            console.log(`en draft cached: ${en}`);
-            return;
-        }
-        sted('write', scaffold, () =>
-            writeJqText(scaffold, { body: '', options: { operation: 'scaffold-locale', postPath: zh, target: 'en' } }),
-        );
-        kk(['executor', 'run', 'surfdash-pub', '--in', scaffold, '--out', scaffoldResult, ...pluginsArgs(pluginsPath)]);
-        const draftPath = metadataOf(readJson(scaffoldResult)).draftPath;
-        sted('write', enFile, () => writeRaw(enFile, typeof draftPath === 'string' ? draftPath : ''));
-    });
-}
-
-function dailyTranslateJa(args: string[]): void {
-    const [workDir = '', runDate = '', pluginsPath = ''] = args;
-    const zhFile = join(workDir, '3-publish', `${runDate}_20_translate-en_zh-post-path.txt`);
-    const jaFile = join(workDir, '3-publish', `${runDate}_22_translate-ja_ja-post-path.txt`);
-    const scaffold = join(workDir, '3-publish', `${runDate}_22_translate-ja_scaffold-ja.json`);
-    const scaffoldResult = join(workDir, '3-publish', `${runDate}_22_translate-ja_scaffold-ja-result.json`);
-    timed(workDir, 'translate-ja', () => {
-        const zh = isFile(zhFile) ? readFileSync(zhFile, 'utf-8') : '';
-        const ja = zh.replace('/zh/', '/ja/');
-        sted('write', jaFile, () => writeRaw(jaFile, ja));
         if (zh === '') {
-            console.log('no zh post path — skip translate-ja');
+            for (const target of ['en', 'ja'] as const) {
+                sted(
+                    'write',
+                    join(workDir, '3-publish', `${runDate}_20_translate-localize_${target}-post-path.txt`),
+                    () =>
+                        writeRaw(
+                            join(workDir, '3-publish', `${runDate}_20_translate-localize_${target}-post-path.txt`),
+                            '',
+                        ),
+                );
+            }
+            console.log('no zh post path — skip localize');
             return;
         }
-        if (isFile(ja)) {
-            console.log(`ja draft cached: ${ja}`);
-            return;
+        for (const target of ['en', 'ja'] as const) {
+            const markerFile = join(workDir, '3-publish', `${runDate}_20_translate-localize_${target}-post-path.txt`);
+            const existing = zh.replace('/zh/', `/${target}/`);
+            if (isFile(existing)) {
+                sted('write', markerFile, () => writeRaw(markerFile, existing));
+                console.log(`${target} draft cached: ${existing}`);
+                continue;
+            }
+            const scaffold = join(workDir, '3-publish', `${runDate}_20_translate-localize_scaffold-${target}.json`);
+            const scaffoldResult = join(
+                workDir,
+                '3-publish',
+                `${runDate}_20_translate-localize_scaffold-${target}-result.json`,
+            );
+            sted('write', scaffold, () =>
+                writeJqText(scaffold, { body: '', options: { operation: 'scaffold-locale', postPath: zh, target } }),
+            );
+            kk([
+                'executor',
+                'run',
+                'surfdash-pub',
+                '--in',
+                scaffold,
+                '--out',
+                scaffoldResult,
+                ...pluginsArgs(pluginsPath),
+            ]);
+            const draftPath = metadataOf(readJson(scaffoldResult)).draftPath;
+            sted('write', markerFile, () => writeRaw(markerFile, typeof draftPath === 'string' ? draftPath : ''));
         }
-        sted('write', scaffold, () =>
-            writeJqText(scaffold, { body: '', options: { operation: 'scaffold-locale', postPath: zh, target: 'ja' } }),
-        );
-        kk(['executor', 'run', 'surfdash-pub', '--in', scaffold, '--out', scaffoldResult, ...pluginsArgs(pluginsPath)]);
-        const draftPath = metadataOf(readJson(scaffoldResult)).draftPath;
-        sted('write', jaFile, () => writeRaw(jaFile, typeof draftPath === 'string' ? draftPath : ''));
     });
 }
 
 function dailyTranslateSync(args: string[]): void {
-    const [workDir = '', runDate = '', pluginsPath = '', zhPostPath = ''] = args;
+    const [workDir = '', runDate = '', pluginsPath = '', zhPathFile = ''] = args;
     const sync = join(workDir, '3-publish', `${runDate}_24_translate-sync_sync.json`);
     const syncResult = join(workDir, '3-publish', `${runDate}_24_translate-sync_sync-result.json`);
     timed(workDir, 'translate-sync', () => {
+        // Reads the marker file itself — the collapsed `translate` state has no
+        // cross-state var to hand the path through.
+        const zhPostPath = isFile(zhPathFile) ? readFileSync(zhPathFile, 'utf-8') : '';
         if (zhPostPath === '') {
             console.log('no zh post path — skip translate-sync');
             return;
@@ -1287,6 +1590,9 @@ if (import.meta.main)
         case 'daily-generate':
             dailyGenerate(rest);
             break;
+        case 'daily-intro':
+            dailyIntro(rest);
+            break;
         case 'daily-quality-report':
             dailyQualityReport(rest);
             break;
@@ -1305,17 +1611,17 @@ if (import.meta.main)
         case 'daily-publish-classify':
             dailyPublishClassify(rest);
             break;
+        case 'daily-patch-surfdash':
+            dailyPatchSurfdash(rest);
+            break;
         case 'daily-publish-partial':
             dailyPublishPartial(rest);
             break;
         case 'daily-run-report':
             dailyRunReport(rest);
             break;
-        case 'daily-translate-en':
-            dailyTranslateEn(rest);
-            break;
-        case 'daily-translate-ja':
-            dailyTranslateJa(rest);
+        case 'daily-translate-localize':
+            dailyTranslateLocalize(rest);
             break;
         case 'daily-translate-sync':
             dailyTranslateSync(rest);