@gobing-ai/knowledge-kit 0.0.33 → 0.0.34

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

@@ -104,6 +104,7 @@ import {
     writeJqText,
     writeJsonText,
     writeRaw,
+    XHS_BODY_CAP,
     XHS_FORMAT,
     XHS_MAX_CARDS,
     xhsPlan,
@@ -197,12 +198,31 @@ export function dailyArticle(args: string[]): void {
     timed(workDir, 'article', () => {
         let planUsable = true;
         const raw = isFile(planIn) ? readFileSync(planIn, 'utf-8') : '';
+        // The plan file is canonically the plan `Doc[]` — `dailyPlan` writes the generator's
+        // `metadata.docs` — and every downstream stage reads it as one. `plan-translate`'s executor
+        // has been observed writing the generator's Content ENVELOPE back instead: valid JSON of the
+        // wrong shape, which the article generator then refuses with `expected array, received
+        // object`. Unwrap that envelope rather than discard the translation; anything else unusable
+        // still falls back to the untranslated candidates.
+        let planShape: unknown;
         try {
-            JSON.parse(raw);
+            planShape = JSON.parse(raw);
         } catch (error) {
             console.error(
                 `article: plan.json invalid JSON — replacing with untranslated plan (downstream states read this file): ${(error as Error).message}`,
             );
+        }
+        if (planShape !== undefined && !Array.isArray(planShape)) {
+            const enveloped = metadataOf(planShape as Record<string, unknown>).docs;
+            if (Array.isArray(enveloped) && enveloped.length > 0) {
+                console.error(
+                    `article: plan.json carries the Content envelope, not the Doc[] — unwrapping metadata.docs (${enveloped.length} doc(s))`,
+                );
+                sted('write', planIn, () => writeJsonText(planIn, enveloped));
+                planShape = enveloped;
+            }
+        }
+        if (!Array.isArray(planShape)) {
             const docs = metadataOf(readJson(candidates)).docs;
             if (!Array.isArray(docs) || docs.length === 0) {
                 console.error('article: candidates.json metadata.docs missing');
@@ -386,8 +406,51 @@ export function dailyEpisodeDuration(args: string[]): void {
     console.log(`episode-duration ok: ${shown} min within ${minMinutes}–${maxMinutes} min`);
 }
 
+/** Ceiling for the pre-spend estimate when the caller passes no `episode_max_minutes`. */
+const DEFAULT_EPISODE_MAX_MINUTES = 20;
+
+/** `kk executor run` argv shared by the quota probe, the voice1 one-shot, and each section. */
+function voiceExecutorArgs(generator: string, input: string, output: string, pluginsPath: string): string[] {
+    return ['executor', 'run', generator, '--in', input, '--out', output, ...pluginsArgs(pluginsPath)];
+}
+
+/**
+ * One tiny gemini-tts render before any episode speech. A non-zero exit (quota, key, network)
+ * means this run should use voicebox. Probe files are removed either way.
+ * Returns false when the caller should fall back.
+ */
+function geminiQuotaProbeOk(workDir: string, pluginsPath: string, transcodeMp3: string, probeDocs: unknown): boolean {
+    const probeDir = join(workDir, '30-audio');
+    const probeIn = join(probeDir, '.gemini-probe-in.json');
+    const probeOut = join(probeDir, '.gemini-probe-out.json');
+    writeJsonText(probeIn, probeDocs);
+    const probe = spawnSync('kk', voiceExecutorArgs('gemini-tts', probeIn, probeOut, pluginsPath), {
+        encoding: 'utf8',
+        timeout: 120_000,
+        env: { ...process.env, VOICE_GEN_MP3: transcodeMp3 },
+    });
+    for (const stale of [probeIn, probeOut, probeOut.replace(/\.json$/, '.wav'), probeOut.replace(/\.json$/, '.mp3')]) {
+        rmSync(stale, { force: true });
+    }
+    if (probe.status !== 0) {
+        const reason = (probe.stderr ?? '').trim().split('\n').slice(-1)[0] || `exit ${probe.status}`;
+        console.log(`generate: gemini quota probe failed (${reason}) — falling back to voicebox for this run`);
+        return false;
+    }
+    console.log('generate: gemini quota probe ok');
+    return true;
+}
+
 export function dailyGenerate(args: string[]): void {
-    const [workDir = '', runDate = '', pluginsPath = '', transcodeMp3 = '', vdriver = ''] = args;
+    const [
+        workDir = '',
+        runDate = '',
+        pluginsPath = '',
+        transcodeMp3 = '',
+        vdriver = '',
+        sectionConcurrency = '',
+        episodeMaxMinutes = '',
+    ] = 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> = {
@@ -402,54 +465,351 @@ export function dailyGenerate(args: string[]): void {
             `generate: unknown vdriver '${vdriver}' (expected one of: ${Object.keys(VOICE_DRIVERS).join(', ')})`,
         );
     }
+    // Strict `Number`, not `parseFloat`: a typo'd var ('2O') must refuse, not cap the episode at 2 min.
+    const maxMinutes = episodeMaxMinutes === '' ? DEFAULT_EPISODE_MAX_MINUTES : Number(episodeMaxMinutes);
+    if (!Number.isFinite(maxMinutes) || maxMinutes <= 0) {
+        failWith(1, `generate: invalid episode_max_minutes: ${episodeMaxMinutes}`);
+    }
     const docs = join(workDir, '30-audio', `${runDate}_10_wrap-docs_docs.json`);
     const content = join(workDir, '30-audio', `${runDate}_11_generate_content.json`);
+
+    if (!sectionConcurrency) {
+        timed(workDir, 'generate', () => {
+            if (isFile(content) && metadataOf(readJson(content)).qc !== undefined) {
+                const qc = metadataOf(readJson(content)).qc as Record<string, unknown> | undefined;
+                if (qc?.passed === true) {
+                    console.log(`audio cached: ${content} (QC passed)`);
+                    return;
+                }
+            }
+            // Gemini quota probe (20261006): the 06:00 cron hit gemini-3.8-flash-tts 429 with a
+            // multi-hour retry-after after the shared key's window drained overnight. One tiny
+            // render (~1 request) before the real episode; ANY probe failure (quota, key, network)
+            // flips this run to the local voicebox driver instead of dying mid-episode — voicebox
+            // needs no key. Operator decision 20261006: keep the gemini default + auto-fallback.
+            if (vdriver === 'gemini') {
+                const docsList = readJson(docs) as Array<Record<string, unknown>>;
+                if (
+                    docsList.length > 0 &&
+                    !geminiQuotaProbeOk(workDir, pluginsPath, transcodeMp3, [{ ...docsList[0], body: 'Hello.' }])
+                ) {
+                    voiceGenerator = VOICE_DRIVERS.voicebox;
+                }
+            }
+            kk(voiceExecutorArgs(voiceGenerator, docs, content, pluginsPath), {
+                env: { VOICE_GEN_MP3: transcodeMp3 },
+            });
+        });
+        return;
+    }
+
+    if (sectionConcurrency !== '1') {
+        failWith(1, `generate: section_concurrency '${sectionConcurrency}' not supported (must be 1)`);
+    }
+
     timed(workDir, 'generate', () => {
-        if (isFile(content) && metadataOf(readJson(content)).qc !== undefined) {
-            const qc = metadataOf(readJson(content)).qc as Record<string, unknown> | undefined;
-            if (qc?.passed === true) {
-                console.log(`audio cached: ${content} (QC passed)`);
-                return;
+        const scriptPath = join(workDir, '24-script', `${runDate}_08_script_voicescript.yaml`);
+        if (!existsSync(scriptPath)) {
+            failWith(1, `generate: voicescript not found: ${scriptPath}`);
+        }
+        const scriptRaw = readFileSync(scriptPath, 'utf8');
+        const script = Bun.YAML.parse(scriptRaw) as Record<string, unknown>;
+        const segments = (script.segments ?? []) as Array<Record<string, unknown>>;
+        if (!Array.isArray(segments) || segments.length < 2) {
+            failWith(1, 'generate: invalid voicescript (expected at least opening and closing segments)');
+        }
+
+        // Grouping: first is opening, last is closing, middle segments split after gap_ms: 1200
+        const middleSegments = segments.slice(1, -1);
+        const itemSections: Array<Array<Record<string, unknown>>> = [];
+        let currentItem: Array<Record<string, unknown>> = [];
+        for (const seg of middleSegments) {
+            currentItem.push(seg);
+            if (seg.gap_ms === 1200) {
+                itemSections.push(currentItem);
+                currentItem = [];
             }
         }
-        // Gemini quota probe (20261006): the 06:00 cron hit gemini-3.8-flash-tts 429 with a
-        // multi-hour retry-after after the shared key's window drained overnight. One tiny
-        // render (~1 request) before the real episode; ANY probe failure (quota, key, network)
-        // flips this run to the local voicebox driver instead of dying mid-episode — voicebox
-        // needs no key. Operator decision 20261006: keep the gemini default + auto-fallback.
-        if (vdriver === 'gemini') {
-            const probeDir = join(workDir, '30-audio');
-            const probeIn = join(probeDir, '.gemini-probe-in.json');
-            const probeOut = join(probeDir, '.gemini-probe-out.json');
-            const docsList = readJson(docs) as Array<Record<string, unknown>>;
-            if (docsList.length > 0) {
-                writeJsonText(probeIn, [{ ...docsList[0], body: 'Hello.' }]);
-                const probe = spawnSync(
-                    'kk',
-                    ['executor', 'run', 'gemini-tts', '--in', probeIn, '--out', probeOut, ...pluginsArgs(pluginsPath)],
-                    { encoding: 'utf8', timeout: 120_000, env: { ...process.env, VOICE_GEN_MP3: transcodeMp3 } },
-                );
-                for (const stale of [
-                    probeIn,
-                    probeOut,
-                    probeOut.replace(/\.json$/, '.wav'),
-                    probeOut.replace(/\.json$/, '.mp3'),
-                ])
-                    rmSync(stale, { force: true });
-                if (probe.status !== 0) {
-                    const reason = (probe.stderr ?? '').trim().split('\n').slice(-1)[0] || `exit ${probe.status}`;
-                    console.log(
-                        `generate: gemini quota probe failed (${reason}) — falling back to voicebox for this run`,
+        if (currentItem.length > 0) {
+            itemSections.push(currentItem);
+        }
+
+        const planPath = join(workDir, '24-script', `${runDate}_08_script-write_plan.json`);
+        if (existsSync(planPath)) {
+            try {
+                const plan = readJson(planPath) as { items?: unknown[] };
+                if (Array.isArray(plan.items) && plan.items.length !== itemSections.length) {
+                    failWith(
+                        1,
+                        `generate: plan item count (${plan.items.length}) does not match script item sections (${itemSections.length})`,
                     );
-                    voiceGenerator = VOICE_DRIVERS.voicebox;
-                } else {
-                    console.log('generate: gemini quota probe ok');
                 }
+            } catch (e: unknown) {
+                if (e instanceof StageFailure) throw e;
             }
         }
-        kk(['executor', 'run', voiceGenerator, '--in', docs, '--out', content, ...pluginsArgs(pluginsPath)], {
-            env: { VOICE_GEN_MP3: transcodeMp3 },
+
+        interface SectionDef {
+            index: number;
+            role: string;
+            stem: string;
+            name: string;
+            segments: Array<Record<string, unknown>>;
+            characters: number;
+            gap_ms: number;
+            text: string;
+        }
+
+        const sectionDefs: SectionDef[] = [];
+        // 00-opening
+        const openSegs = [segments[0]];
+        const openText = openSegs.map((s) => String(s.text ?? '')).join('');
+        sectionDefs.push({
+            index: 0,
+            role: 'opening',
+            stem: '00-opening',
+            name: '00-opening',
+            segments: openSegs,
+            characters: [...openText].length,
+            gap_ms:
+                typeof openSegs[openSegs.length - 1].gap_ms === 'number'
+                    ? (openSegs[openSegs.length - 1].gap_ms as number)
+                    : 1200,
+            text: openText,
+        });
+
+        // 01-item ...
+        itemSections.forEach((segs, idx) => {
+            const itemIdx = idx + 1;
+            const pad = String(itemIdx).padStart(2, '0');
+            const stem = `${pad}-item`;
+            const itemText = segs.map((s) => String(s.text ?? '')).join('');
+            const lastSeg = segs[segs.length - 1];
+            sectionDefs.push({
+                index: itemIdx,
+                role: 'item',
+                stem,
+                name: stem,
+                segments: segs,
+                characters: [...itemText].length,
+                gap_ms: typeof lastSeg?.gap_ms === 'number' ? (lastSeg.gap_ms as number) : 1200,
+                text: itemText,
+            });
         });
+
+        // closing
+        const closeIdx = sectionDefs.length;
+        const closePad = String(closeIdx).padStart(2, '0');
+        const closeSegs = [segments[segments.length - 1]];
+        const closeText = closeSegs.map((s) => String(s.text ?? '')).join('');
+        sectionDefs.push({
+            index: closeIdx,
+            role: 'closing',
+            stem: `${closePad}-closing`,
+            name: `${closePad}-closing`,
+            segments: closeSegs,
+            characters: [...closeText].length,
+            gap_ms:
+                typeof closeSegs[closeSegs.length - 1].gap_ms === 'number'
+                    ? (closeSegs[closeSegs.length - 1].gap_ms as number)
+                    : 300,
+            text: closeText,
+        });
+
+        // Character-rate estimate: section characters / driver rate + 8 s sting > the workflow's
+        // ceiling (`episode_max_minutes`, arg 8; default 20 for a bare five/six-argument call).
+        // The rates are MEASURED from shipped renders, not the style contract's prose. gemini-tts:
+        // 20261004 5466 chars / 1026 s = 5.33, 20261007 5970 / 1096 = 5.45, and the 0237 live dry run
+        // 4645 / 789.9 s of section speech = 5.88 — a 5.3–5.9 range, so 5.4 deliberately errs low (a
+        // slightly early refusal is cheaper than a rendered episode the duration gate then rejects).
+        // voice-gen: 20261006 6376 / 1135 = 5.62. A 20-minute ceiling is therefore ~6400 characters.
+        // The style sidecar's 3.3 / 6.3 figures are stale and mutually inconsistent with its own
+        // 4300–5800 字 budget (which is 13–29 min at 3.3); using them refused a script that really
+        // renders in 17 min. Recalibrate from a fresh pair of `metadata.duration` readings when a
+        // driver changes model or speed.
+        const charRate = voiceGenerator === 'gemini-tts' ? 5.4 : 5.6;
+        const totalChars = sectionDefs.reduce((acc, s) => acc + s.characters, 0);
+        const estimatedSeconds = 8 + totalChars / charRate;
+        if (estimatedSeconds > maxMinutes * 60) {
+            const longest3 = [...sectionDefs].sort((a, b) => b.characters - a.characters).slice(0, 3);
+            failWith(
+                1,
+                `generate: character-rate estimate ${Math.round(estimatedSeconds / 60)} min exceeds ${maxMinutes} min limit (longest sections: ${longest3.map((s) => s.name).join(', ')})`,
+            );
+        }
+
+        const voiceProfile =
+            (typeof script.default_profile_id === 'string' && script.default_profile_id) ||
+            (typeof script.default_profile === 'string' && script.default_profile) ||
+            process.env.VOICEBOX_DEFAULT_PROFILE ||
+            'robin-news';
+
+        const secDir = join(workDir, '30-audio', 'sections', runDate);
+        mkdirSync(secDir, { recursive: true });
+
+        const joinedWavPath = join(workDir, '30-audio', `${runDate}_11_generate_content.wav`);
+        const joinedContentPath = join(workDir, '30-audio', `${runDate}_11_generate_content.json`);
+
+        interface SectionPlan {
+            def: SectionDef;
+            hash: string;
+            wavPath: string;
+            jsonPath: string;
+            needsSynthesis: boolean;
+        }
+
+        const computePlans = (driver: string): SectionPlan[] => {
+            return sectionDefs.map((def) => {
+                const hash = createHash('sha256').update(`${def.text}\0${voiceProfile}\0${driver}`).digest('hex');
+                const wavPath = join(secDir, `${def.stem}.wav`);
+                const jsonPath = join(secDir, `${def.stem}.json`);
+                let cached = false;
+                if (existsSync(wavPath) && existsSync(jsonPath)) {
+                    try {
+                        const sidecar = readJson(jsonPath) as Record<string, unknown>;
+                        const sidecarMeta = metadataOf(sidecar) as Record<string, unknown>;
+                        if (sidecar.hash === hash || sidecarMeta.hash === hash) {
+                            cached = true;
+                        }
+                    } catch {}
+                }
+                return {
+                    def,
+                    hash,
+                    wavPath,
+                    jsonPath,
+                    needsSynthesis: !cached,
+                };
+            });
+        };
+
+        let plans = computePlans(voiceGenerator);
+        const anySynthesisNeeded = plans.some((p) => p.needsSynthesis);
+
+        if (!anySynthesisNeeded && existsSync(joinedWavPath) && existsSync(joinedContentPath)) {
+            console.log('generate: all sections cached, joined speech reused');
+            return;
+        }
+
+        // Same quota probe as the one-shot path, before any section request. A fallback changes
+        // the cache key, so plans are recomputed and no Gemini file is played as voicebox speech.
+        if (
+            anySynthesisNeeded &&
+            vdriver === 'gemini' &&
+            !geminiQuotaProbeOk(workDir, pluginsPath, transcodeMp3, [
+                {
+                    id: 'probe',
+                    title: 'Probe',
+                    body: Bun.YAML.stringify({
+                        title: 'Probe',
+                        segments: [{ text: 'Hello.' }],
+                    }),
+                    sourceUri: 'file://probe',
+                    mediaType: 'application/yaml',
+                    metadata: { voiceProfile },
+                },
+            ])
+        ) {
+            voiceGenerator = VOICE_DRIVERS.voicebox;
+            plans = computePlans(voiceGenerator);
+        }
+
+        // Synthesize sections sequentially (concurrency 1)
+        for (const plan of plans) {
+            if (!plan.needsSynthesis) {
+                console.log(`generate: section cached: ${plan.def.stem}`);
+                continue;
+            }
+            console.log(`generate: synthesizing section: ${plan.def.stem}`);
+            const secScript = { ...script, segments: plan.def.segments };
+            const secDocIn = join(secDir, `.${plan.def.stem}_in.json`);
+            const doc = {
+                id: createHash('sha256').update(`section-${plan.def.stem}`).digest('hex').slice(0, 16),
+                title: `Daily AI News VoiceScript - ${plan.def.stem}`,
+                sourceUri: `file://${resolve(scriptPath)}#${plan.def.stem}`,
+                body: Bun.YAML.stringify(secScript),
+                mediaType: 'application/yaml',
+                metadata: { voiceProfile },
+            };
+            writeJsonText(secDocIn, [doc]);
+            try {
+                const status = kk(voiceExecutorArgs(voiceGenerator, secDocIn, plan.jsonPath, pluginsPath), {
+                    env: { VOICE_GEN_MP3: transcodeMp3 },
+                    soft: true,
+                });
+                if (status !== 0) {
+                    failWith(status, `generate: section synthesis failed for ${plan.def.stem}`);
+                }
+            } finally {
+                rmSync(secDocIn, { force: true });
+            }
+            try {
+                const sidecar = readJson(plan.jsonPath) as Record<string, unknown>;
+                sidecar.hash = plan.hash;
+                if (sidecar.metadata && typeof sidecar.metadata === 'object') {
+                    (sidecar.metadata as Record<string, unknown>).hash = plan.hash;
+                }
+                writeJsonText(plan.jsonPath, sidecar);
+            } catch {}
+        }
+
+        // Join sections with ffmpeg
+        const probeHelper = (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 sampleRate = probeHelper(plans[0].wavPath, 'stream=sample_rate') || '24000';
+        const ffmpegArgs = ['-y', '-hide_banner', '-loglevel', 'error'];
+        const filterParts: string[] = [];
+        const concatInputs: string[] = [];
+
+        plans.forEach((plan, i) => {
+            ffmpegArgs.push('-i', plan.wavPath);
+            filterParts.push(`[${i}:a]aresample=${sampleRate},aformat=sample_fmts=s16:channel_layouts=mono[a${i}]`);
+            concatInputs.push(`[a${i}]`);
+            if (i < plans.length - 1) {
+                const gapMs = plan.def.gap_ms;
+                const gapS = gapMs > 0 ? (gapMs / 1000).toFixed(4) : '0';
+                filterParts.push(`anullsrc=r=${sampleRate}:cl=mono,atrim=duration=${gapS}[sil${i}]`);
+                concatInputs.push(`[sil${i}]`);
+            }
+        });
+
+        const filterComplex = `${filterParts.join(';')};${concatInputs.join('')}concat=n=${concatInputs.length}:v=0:a=1[out]`;
+        ffmpegArgs.push('-filter_complex', filterComplex, '-map', '[out]', '-c:a', 'pcm_s16le', joinedWavPath);
+
+        const conv = spawnSync('ffmpeg', ffmpegArgs);
+        if (conv.status !== 0 || !existsSync(joinedWavPath)) {
+            failWith(1, `generate: ffmpeg join failed: ${conv.stderr?.toString().trim()}`);
+        }
+
+        const joinedDuration = Number.parseFloat(probeHelper(joinedWavPath, 'format=duration'));
+
+        let contentObj: Record<string, unknown> = {};
+        if (existsSync(joinedContentPath)) {
+            try {
+                contentObj = readJson(joinedContentPath) as Record<string, unknown>;
+            } catch {}
+        }
+        const meta = (contentObj.metadata ?? {}) as Record<string, unknown>;
+        delete meta.introMerged;
+        meta.audioPath = joinedWavPath;
+        meta.duration = joinedDuration;
+        contentObj.audioPath = joinedWavPath;
+        contentObj.mediaType = 'audio/wav';
+        contentObj.metadata = meta;
+        writeJsonText(joinedContentPath, contentObj);
     });
 }
 
@@ -791,7 +1151,7 @@ export function dailyPublishWechat(args: string[]): void {
             original: true,
             aiGenerated: true,
             author: '冰原奔狼',
-            collection: collectionArg || 'AI 乱炖',
+            collection: collectionArg || '每日AI乱炖',
             ...(isFile(cover) ? { coverPath: cover } : {}),
             // Audio block at the article top (operator request 2026-09-29): the daily MP3 goes to
             // the 素材库 under the article title; the plugin reuses an existing same-title material.
@@ -842,10 +1202,15 @@ export function dailyPublishWechat(args: string[]): void {
  * 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).
+ *
+ * 0236: the optional trailing `<podcast>` arg (`'true'` from voice2 only) attaches the episode's
+ * 发播客 note to the same visit as `metadata.followUps` — one console visit, two notes, one cap entry
+ * (ADR-025 amendment 2026-10-09).
  */
 export function dailyPublishXhs(args: string[]): void {
-    const [workDir = '', runDate = '', pluginsPath = '', live = 'false'] = args;
+    const [workDir = '', runDate = '', pluginsPath = '', live = 'false', podcast = ''] = args;
     const content = join(workDir, '25-xhs', 'content.json');
+    const prep = join(workDir, '31-publish', `${runDate}_13_publish-prep_content.json`);
     const input = join(workDir, '31-publish', `${runDate}_19_publish-xhs_content.json`);
     const result = join(workDir, '31-publish', `${runDate}_19_publish-xhs_result.json`);
     const want = live === 'true' ? 'public' : 'draft';
@@ -854,6 +1219,17 @@ export function dailyPublishXhs(args: string[]): void {
         // xhs_live=true re-run (that would report a live post that never happened).
         if (resultPublishStatus(result) === want) {
             console.log(`publish-xhs cached: ${want} already recorded in ${result}`);
+            // 0236: the cache keys on the visit's primary note, so a 发播客 follow-up that failed in
+            // that visit is named here instead of hidden. It is not retried: a re-visit would post
+            // a second 图文 draft (the console has no idempotency key).
+            const followUps = metadataOf(readJson(result)).followUps;
+            for (const entry of Array.isArray(followUps) ? followUps : []) {
+                const step = (entry ?? {}) as Record<string, unknown>;
+                if (step.ok === true) continue;
+                console.log(
+                    `publish-xhs cached: follow-up ${String(metadataOf(step).operation ?? '?')} did not complete: ${String(step.error ?? 'no error recorded')}`,
+                );
+            }
             return;
         }
         if (!isFile(content)) {
@@ -861,8 +1237,16 @@ export function dailyPublishXhs(args: string[]): void {
             return;
         }
         const packaged = requireJson(content, 'publish-xhs');
+        const followUp = podcast === 'true' ? xhsPodcastNote(prep, want) : undefined;
         sted('write', input, () =>
-            writeJsonText(input, { ...packaged, metadata: { ...metadataOf(packaged), publishStatus: want } }),
+            writeJsonText(input, {
+                ...packaged,
+                metadata: {
+                    ...metadataOf(packaged),
+                    publishStatus: want,
+                    ...(followUp === undefined ? {} : { followUps: [followUp] }),
+                },
+            }),
         );
         // `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
@@ -878,6 +1262,34 @@ export function dailyPublishXhs(args: string[]): void {
     });
 }
 
+/**
+ * 0236 R1: the 发播客 Content for the same episode — the run's publish-prep Content (the final mp3
+ * with the intro, `23-cover`'s PNG, title and body) plus `metadata.operation` and the run's own
+ * `publishStatus`. No artifact is produced here: both files already exist.
+ *
+ * `metadata.audio` repeats the prep's `metadata.audioFile` under the key the xhs channel's 发播客 mode
+ * reads (`xhs-pub/src/modes.ts`); `metadata.coverImage` is already the shared spelling. A run with no
+ * publish-prep output names the missing episode drafts and carries the 图文 note alone — the 发播客
+ * note is never invented.
+ */
+function xhsPodcastNote(prepPath: string, publishStatus: 'draft' | 'public'): Record<string, unknown> | undefined {
+    const prep = readJson(prepPath);
+    if (prep === null) {
+        console.log(`publish-xhs: no publish-prep Content at ${prepPath} — the 发播客 note is skipped`);
+        return undefined;
+    }
+    const metadata = metadataOf(prep);
+    return {
+        ...prep,
+        metadata: {
+            ...metadata,
+            operation: '发播客',
+            audio: metadata.audioFile,
+            publishStatus,
+        },
+    };
+}
+
 /**
  * WeChat MP: drive the console via `wechatmp-pub`'s browser transport and save the article to the
  * draft box (草稿箱). Draft by default; the 发表 flow runs only on an explicit launch-time
@@ -1290,9 +1702,8 @@ export function dailyShowNotes(args: string[]): void {
                 PODCAST_PUB_RUN_DATE: runDate,
                 PODCAST_PUB_BRIEF_MODE: 'true',
                 PODCAST_PUB_ARTICLE_POST_PATH: postPath,
-                // Task 0189 R1 / Apple §1.11: AI-voice disclosure in the episode metadata, not only
-                // in the audio sign-off and the article footer.
-                PODCAST_PUB_FOOTER_NOTE: '本期文字由 AI 辅助整理，音频为 AI 合成配音。',
+                // 2026-10-08: the column settings carry the AI-production note. Do not append the
+                // stock closer to show notes (or the article, or the spoken sign-off).
                 ...(isFile(audioContent) ? { PODCAST_PUB_AUDIO_CONTENT: audioContent } : {}),
             },
         });
@@ -1310,7 +1721,10 @@ export function dailyShowNotes(args: string[]): void {
  */
 export function dailyTranslateLocalize(args: string[]): void {
     const [workDir = '', runDate = '', pluginsPath = ''] = args;
-    const result = join(workDir, '31-publish', `${runDate}_17_publish_result.json`);
+    // Same seam as show-notes (task 0137): `_17_publish_result.json` is written later by
+    // publish-classify, which depends on translate-sync. Reading it here always saw no zh
+    // path, so en/ja were never scaffolded (2026-10-08 dogfood).
+    const result = join(workDir, '31-publish', `${runDate}_14_publish-surfdash_result.json`);
     const zhFile = join(workDir, '31-publish', `${runDate}_20_translate-localize_zh-post-path.txt`);
     timed(workDir, 'translate-localize', () => {
         const postPath = firstPostPath(readJson(result), 'surfdash-pub');
@@ -1408,12 +1822,63 @@ export function dailyWrapDocs(args: string[]): void {
     });
 }
 
+/** 0235 R4: `note_scope`'s one opt-in value. Anything else — absent included — is today's path. */
+const XHS_NOTE_SCOPE_EPISODE = 'episode';
+
+/**
+ * 0235 R2: `①` — the circled digits ①…⑳ are contiguous from here, and the episode note attaches
+ * `XHS_MAX_CARDS` cards plus at most one cover, so no bare number can ever be needed.
+ */
+const CIRCLED_DIGIT_ONE = 0x2460;
+
+/** The attach-order marker of line `position` (0-based). */
+const markerFor = (position: number): string => String.fromCodePoint(CIRCLED_DIGIT_ONE + position);
+
+/**
+ * 0235 R2: split the agent's note body into its lead paragraph and its trailing hashtag run. The
+ * prompt asks for 3-5 hashtags at the end, so the run is read off the end of the body; a body
+ * without hashtags is entirely lead.
+ */
+function splitNoteBody(body: string): { lead: string; hashtags: string } {
+    const trimmed = body.trim();
+    const match = /(?:^|\s)(#\S+(?:\s+#\S+)*)\s*$/.exec(trimmed);
+    if (match === null) return { lead: trimmed, hashtags: '' };
+    return { lead: trimmed.slice(0, match.index).trimEnd(), hashtags: match[1] ?? '' };
+}
+
+/**
+ * 0235 R2: the episode note body — the agent's lead paragraph, then one numbered line per attached
+ * image in attach order, then the plan's hashtags. `cap` is the console's own note limit
+ * (`XHS_NOTE_BODY_MAX`): only the lead is trimmed to fit, so an image never loses its line. A body
+ * that overflows even without a lead fails loud rather than shipping a note the editor would cut.
+ */
+function episodeNoteBody(body: string, lines: string[], cap: number): string {
+    const { lead, hashtags } = splitNoteBody(body);
+    const tail = [lines.join('\n'), hashtags].filter((part) => part !== '').join('\n\n');
+    // `\n\n` joins the lead to the tail; a lead trimmed away drops the separator with it.
+    const budget = cap - tail.length - (lead === '' ? 0 : 2);
+    const head = budget >= lead.length ? lead : lead.slice(0, Math.max(budget, 0)).trimEnd();
+    const note = head === '' ? tail : `${head}\n\n${tail}`;
+    if (note.length > cap) {
+        failWith(
+            1,
+            `xhs render: episode note body is ${note.length} chars for ${lines.length} image lines — the cap is ${cap} and a line is never dropped`,
+        );
+    }
+    return note;
+}
+
 /**
  * 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. Card copy
  * is typeset by image-gen's composer; the provider prompt stays text-free (0181). Resume-safe:
  * a card whose recorded artifact is still on disk is not re-rendered — and not re-billed.
+ *
+ * `note_scope` (`episode`, 0235) opts into the episode note for voice2: the packaged set then also
+ * attaches the episode cover last, and the body is rebuilt as the lead paragraph plus one numbered
+ * line per attached image. Absent or any other value: the lead-item series and the agent's body are
+ * packaged verbatim (voice1's contract).
  */
 export function dailyXhsRender(args: string[]): void {
     const [
@@ -1425,9 +1890,12 @@ export function dailyXhsRender(args: string[]): void {
         provider = '',
         model = '',
         fallback = '',
+        noteScope = '',
     ] = args;
     const count = Number.parseInt(countArg, 10);
+    const episode = noteScope === XHS_NOTE_SCOPE_EPISODE;
     const planPath = join(workDir, '25-xhs', `${runDate}_18_xhs_plan.json`);
+    const coverPath = join(workDir, '23-cover', `${runDate}_07_cover_cover.png`);
     const cardsDir = join(workDir, '25-xhs', 'cards');
     const manifestPath = join(workDir, '25-xhs', 'cards.json');
     const contentPath = join(workDir, '25-xhs', 'content.json');
@@ -1439,6 +1907,13 @@ export function dailyXhsRender(args: string[]): void {
         sted('mkdir', cardsDir, () => mkdirSync(cardsDir, { recursive: true }));
         const images: Record<string, unknown>[] = [];
         const cards: Record<string, unknown>[] = [];
+        // 0235 R2: the numbered lines are a pure function of the plan and the cover, in attach order
+        // (cards in plan order, the cover last), so the note — and its cap — is settled before the
+        // first card is billed: an over-cap tail fails here with nothing rendered.
+        const withCover = episode && isFile(coverPath);
+        const lines = plan.cards.map((card, i) => `${markerFor(i)} ${card.copy}：${card.points[0] ?? ''}`);
+        if (withCover) lines.push(`${markerFor(lines.length)} 每日AI乱炖 ${runDate} 本期封面`);
+        const body = episode ? episodeNoteBody(plan.body, lines, XHS_BODY_CAP) : plan.body;
         for (const card of plan.cards) {
             const out = join(cardsDir, `card-${card.index}.json`);
             const promptPath = join(cardsDir, `card-${card.index}.prompt.txt`);
@@ -1514,19 +1989,34 @@ export function dailyXhsRender(args: string[]): void {
                 promptPath,
                 imagePath,
                 illustrationPath,
+                ...(card.itemId === undefined ? {} : { itemId: card.itemId }),
                 status: 'rendered',
             });
         }
+        // 0235 R1: the episode cover closes the set — it is ultrawide, and image 1 (card 01) is what
+        // sets the note's grid ratio. It is `daily-cover`'s own artifact (no new image kind), and
+        // the set is ≤ XHS_MAX_CARDS + 1 = 11, inside `xhs-pub`'s XHS_IMAGE_MAX (18).
+        if (withCover) {
+            images.push({ path: resolve(coverPath) });
+        } else if (episode) {
+            console.log(
+                `xhs render: no episode cover at ${coverPath} — the note carries the ${cards.length} cards only`,
+            );
+        }
         sted('write', manifestPath, () => writeJsonText(manifestPath, { source: planPath, cards }));
         sted('write', contentPath, () =>
             writeJsonText(contentPath, {
                 title: plan.title,
-                body: plan.body,
+                body,
                 format: 'text',
                 metadata: { images, publishStatus: 'draft' },
             }),
         );
-        console.log(`xhs render: ${cards.length} cards packaged in card order (${contentPath})`);
+        console.log(
+            episode
+                ? `xhs render: ${images.length} images packaged in image order (${contentPath})`
+                : `xhs render: ${cards.length} cards packaged in card order (${contentPath})`,
+        );
     });
 }