@gobing-ai/knowledge-kit 0.0.17 → 0.0.18

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

@@ -500,6 +500,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);
@@ -752,6 +762,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 +778,10 @@ function dailyArticle(args: string[]): void {
                 ...pluginsArgs(pluginsPath),
             ],
             {
-                env: { ARTICLE_DATE: runDate },
+                env: {
+                    ARTICLE_DATE: runDate,
+                    ...(isFile(proseBody) ? { ARTICLE_BODY_FILE: proseBody } : {}),
+                },
             },
         );
         const body = readJson(articleContent)?.body;
@@ -792,7 +809,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 +835,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 +884,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 +911,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 +1039,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 +1047,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 +1107,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 +1120,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 +1151,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 +1231,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 +1344,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 +1354,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 +1377,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 +1542,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 +1563,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);

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

@@ -0,0 +1,80 @@
+---
+name: publish
+description: >-
+  Thin operator surface for leftover publish channels — "publish this draft to
+  Medium", "fan out to Qiita and Medium", "prepare a Juejin draft". Shells
+  `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.
+---
+
+# publish — leftover channel operator surface
+
+## Purpose
+
+Drive harvested `kind: publish` plugins after a draft exists. **The plugin owns
+transport and Result.** This skill selects the channel, confirms draft vs live,
+and shells `kk` — it does not call an LLM from inside a plugin process and does
+not add a `kk publish` noun.
+
+## Channels
+
+| Channel | Plugin | Transport | How this skill invokes it |
+| --- | --- | --- | --- |
+| medium | `medium-pub` | `file-cli` (token API) | `kk executor run medium-pub --in <content.json> --out <result.json>` |
+| wechatmp | `wechatmp-pub` | `file-cli` (`draft/add`) | `kk executor run wechatmp-pub` (default operation `draft`) |
+| x post | `x-pub` | `file-cli` (`POST /2/tweets`) | `kk executor run x-pub` (`options.operation` omitted / `post`) |
+| x article | `x-pub` | `browser` / `agent` | workflow `agent.run` — not `kk fanout` |
+| 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` |
+
+Already-harvested file-cli channels (`qiita-pub`, `zenn-pub`, `surfdash-pub`,
+`emdash-pub`, `podcast-pub`) compose the same way.
+
+## Do not
+
+- Embed Playwright selectors or reimplement a transport here.
+- Spawn an LLM from `kk fanout` (ADR-007 R4). Agent-default channels are
+  sequential workflow `agent.run` steps — see
+  `plugins/kk/workflows/leftover-publish-fanout-example.yaml`.
+- Add a first-layer `kk publish` command.
+- Put secrets in `--in` JSON or `plugin.json`. Env only.
+
+## Confirmation
+
+Default Result is **draft / unpublished**. Live publish (`public`, WeChat
+`freepublish/submit`, CMS submit) requires an explicit operator confirmation
+in this skill before the plugin is invoked with a live status. Under
+`KK_NONINTERACTIVE=1`, proceed only when the `--in` payload already carries
+the confirmed live status; otherwise fail naming the switch.
+
+## Invocation
+
+```
+<channel> [--in <content.json>] [--out <result.json>] [--live]
+          [--fanout <channel>,<channel>]
+```
+
+1. Resolve `--in` Content (required).
+2. If `--fanout` lists two or more **file-cli or script** channels: run
+   `kk fanout --in <content.json> --targets <list> --out <aggregate.json>`.
+   Each target contributes one `targets[]` Result entry.
+3. If the channel's default driver is `agent`: do **not** call `kk fanout`.
+   Tell the operator (or the workflow) to run the page against
+   `~/.config/kk/browser-profiles/<channel>` then `kk executor run <plugin>`
+   so the plugin writes Result. The example workflow sequences that as
+   `agent.run`.
+4. Otherwise: `kk executor run <plugin> --in … --out …`.
+5. Report `--out` `ok`, `target`, `id`/`url`, and `error` verbatim on failure.
+
+## Env (plugin-owned; never echoed)
+
+| Plugin | Required |
+| --- | --- |
+| medium-pub | `MEDIUM_INTEGRATION_TOKEN` |
+| wechatmp-pub | `WECHAT_APP_ID`, `WECHAT_APP_SECRET` |
+| x-pub `post` | `X_API_KEY`, `X_API_SECRET`, `X_ACCESS_TOKEN`, `X_ACCESS_TOKEN_SECRET` |
+
+Missing env → plugin exit 1, `Result.ok false`, error names the variable.