@gobing-ai/knowledge-kit 0.0.34 → 0.0.36

package/plugins/publishings/wechatmp-pub/src/flow.ts

@@ -3,7 +3,7 @@ import { ResultSchema } from '@gobing-ai/kk-core';
 import { trySelectors } from '@gobing-ai/publish-harness';
 import { expectOutcome, pasteHtml, readScopedSignal, uploadFile } from '@gobing-ai/publish-harness/browser';
 import type { Page } from 'playwright';
-import { enrichArticle, insertAudio } from './enrich';
+import { enrichArticle } from './enrich';
 import {
     artifactPaths,
     CREATE_TYPES,
@@ -21,8 +21,10 @@ import {
     findAttachedSelector,
     findSelector,
     followNewPage,
+    modalState,
     tryFindSelector,
     type WechatPage,
+    waitForVisible,
 } from './page';
 
 /**
@@ -65,23 +67,92 @@ const LAYOUT_TARGET = ['div[role="menuitem"]:has-text("匹配目标格式")', 'l
 
 /**
  * 封面 has NO file input (§5.2): the panel offers `修改` / `换一张` / `从正文选择`
- * (`a.js_selectCoverFromContent`) / 从图片库选择 / 微信扫码上传 / AI 配图, and states 默认首图为封面.
- * Only the body-image path is implemented; the other three are recorded non-goals (0205).
+ * (`a.js_selectCoverFromContent`) / `从图片库选择` (`a.js_imagedialog`) / 微信扫码上传 / AI 配图.
+ * `从图片库选择` is the default because the daily flow uploads the episode cover there as the audio
+ * material's cover, so the library holds exactly the image the operator wants (2026-10-10);
+ * `从正文选择` remains selectable via `metadata.wechatmp.coverSource`.
  */
 const COVER_PANEL_OPEN = ['a.js_selectCoverFromContent', '.js_cover_btn_area', 'text=换一张', 'text=修改'];
 const COVER_FROM_CONTENT = ['a.js_selectCoverFromContent', 'text=从正文选择'];
+const COVER_FROM_LIBRARY = ['a.js_imagedialog', 'text=从图片库选择'];
+/** The library picker is two-stage: pick the image, then 下一步, then the dialog's 确认. */
+const COVER_LIBRARY_NEXT = ['button:has-text("下一步")'];
 /**
  * The panel's own image list is NOT `<img>`-based (measured `panels: 5, imgs: 0`), so the item and
  * confirm selectors below are candidate shapes and **not** re-measured (§6 still lists the widget as
  * to do). A miss is recorded as a warning, never as a false cover claim.
  */
-const COVER_ITEM = [
-    'div[class*="cover" i] li',
-    'div[class*="imgList" i] li',
-    'div[class*="weui-desktop-img-picker" i] li',
-];
 const COVER_CONFIRM = ['button:has-text("确定")', 'button:has-text("确认")', 'button:has-text("完成")'];
 
+/** The controls that close whatever modal the cover step left open, most specific first. */
+const DIALOG_DISMISS = [
+    '.weui-desktop-dialog:visible button:has-text("取消")',
+    '.weui-desktop-dialog__close',
+    'button:has-text("取消")',
+];
+
+/**
+ * Close an open console dialog, best-effort. Measured 2026-10-12: `setCover` returned its warning
+ * while the cover panel stayed open, and an open panel's footer (`div.weui-desktop-dialog__ft`)
+ * covers the editor — 赞赏 / 原文链接 / 创作来源 / 音频 each click-timed out behind it and the final
+ * `保存为草稿` was blocked for 30 s, so the run saved no draft at all. The same sweep shape the
+ * settings rail already uses (`./enrich`): the dialog's own 取消, else Escape.
+ */
+async function dismissOpenDialog(page: WechatPage): Promise<void> {
+    for (const selector of DIALOG_DISMISS) {
+        const control = await tryFindSelector(page, [selector], 2_000);
+        if (control === undefined) continue;
+        try {
+            await clickSelector(page, control, 2_000);
+        } catch {
+            // Gone between the probe and the click — nothing left to dismiss.
+        }
+        break;
+    }
+    await page.press?.('Escape');
+    await page.waitForTimeout?.(400);
+}
+
+/** The close controls a console modal exposes, most specific first (the audio picker shows no 取消).
+ *  `.weui-desktop-dialog__close-btn` is the 0272-captured audio-dialog variant the bare `__close`
+ *  probe missed. */
+const DIALOG_CLOSE = [
+    '.weui-desktop-dialog__wrp .weui-desktop-dialog__close',
+    '.weui-desktop-dialog__close',
+    '.weui-desktop-dialog__close-btn',
+    '.weui-desktop-dialog__wrp button:has-text("取消")',
+    'button:has-text("取消")',
+];
+
+/**
+ * Close every open console modal before a submit click. Measured 2026-10-12: the 插入音频 dialog
+ * (`weui-desktop-dialog__wrp align_edge audio_dialog js_audio_music_dialog`) stayed open after its
+ * own 上传音频 click timed out, its footer covered `保存为草稿` for 30 s, and the run saved no draft
+ * at all. A failed enrichment is a warning by contract, never a gate — so nothing may outlive it.
+ *
+ * Returns `'residual'` when a dialog is still open — or its state is UNREADABLE — after all passes:
+ * an unknown overlay must never read as cleaned up (task 0260 R3/AC5).
+ */
+async function closeOpenDialogs(page: WechatPage): Promise<'closed' | 'residual'> {
+    for (let pass = 0; pass < 3; pass += 1) {
+        const state = await modalState(page);
+        if (state === 'closed') return 'closed';
+        for (const selector of DIALOG_CLOSE) {
+            const control = await tryFindSelector(page, [selector], 1_500);
+            if (control === undefined) continue;
+            try {
+                await clickSelector(page, control, 2_000);
+            } catch {
+                // Gone between the probe and the click.
+            }
+            break;
+        }
+        await page.press?.('Escape');
+        await page.waitForTimeout?.(400);
+    }
+    return (await modalState(page)) === 'closed' ? 'closed' : 'residual';
+}
+
 /** 视频's media modal (§5.2): tabs 素材库/视频号动态/视频链接 + 本地上传 + 确定/取消. */
 const VIDEO_LOCAL_UPLOAD = ['text=本地上传', 'button:has-text("本地上传")'];
 const VIDEO_FILE_INPUT = [
@@ -111,6 +182,40 @@ const PODCAST_COVER_INPUT = [
 ];
 const PODCAST_INSERT = ['div.weui-desktop-dialog button:has-text("插入")', 'button:has-text("插入")'];
 
+/** 音频 material dialog: the toolbar menu opens it, then the 素材库 list or the upload form. */
+const AUDIO_MENU = 'li.js_insertaudio';
+/** The toolbar dropdown that reveals the 音频 menu item (measured 2026-10-13): the item lives in a
+ *  `display:none` menu under `#audio_music_plugin_btn` until that trigger is clicked. */
+const AUDIO_TOOLBAR_TRIGGER = '#audio_music_plugin_btn';
+const AUDIO_DIALOG = '.audio_dialog';
+/** The 素材库 rows stream in after the dialog opens, so the dedupe probe retries while they load. */
+const AUDIO_DIALOG_TIMEOUT_MS = 15_000;
+const AUDIO_ROW_RETRIES = 2;
+const AUDIO_ROW_SETTLE_MS = 1_200;
+/**
+ * The upload form (operator walk 2026-10-10: `上传音频` → file → `上传封面` → file → title → agree →
+ * 保存). The form lives inside the audio dialog, so the file inputs stay scoped to it.
+ */
+const UPLOAD_AUDIO = ['text=上传音频', 'button:has-text("上传音频")'];
+const AUDIO_UPLOAD_INPUT = [
+    '.weui-desktop-dialog input[type="file"][accept*="audio"]',
+    '.weui-desktop-dialog input[type="file"][accept*=".mp3"]',
+    '.audio_dialog input[type="file"][accept*="audio"]',
+    'input[type="file"][accept*=".mp3"]',
+];
+const UPLOAD_COVER = ['text=上传封面', 'button:has-text("上传封面")'];
+const AUDIO_COVER_INPUT = [
+    '.weui-desktop-dialog input[type="file"][accept*="image/"]',
+    '.audio_dialog input[type="file"][accept*="image/"]',
+    'input[type="file"][accept*=".png"]',
+];
+const AUDIO_TITLE_INPUT = [
+    '.weui-desktop-dialog input[placeholder*="标题"]',
+    '.audio_dialog input[placeholder*="标题"]',
+    '.audio_dialog input.frm_input',
+];
+const UPLOAD_SAVE = ['.weui-desktop-dialog button:has-text("保存")', 'button:has-text("保存")'];
+
 /** The recorded save control. `发表` is never clicked on a draft run (ADR-022/ADR-026). */
 const SAVE_DRAFT = ['button:has-text("保存为草稿")', 'text=保存为草稿'];
 const PUBLISH_SEND = ['button.mass_send', '.mass_send', 'button:has-text("发表")'];
@@ -452,20 +557,33 @@ async function insertBody(page: WechatPage, deps: ModeRunDeps): Promise<void> {
 }
 
 /**
- * `一键排版` applies the layout directly. Measured live (dogfood 2026-10-05): after the click the only
- * new text was ONE element carrying `保留源格式 匹配目标格式 仅保留文本` as a label — a format hint, not a
- * clickable option set (the discovery note misread that concatenation as a menu). Waiting 30 s for
- * `匹配目标格式` therefore failed a real draft. Click the control when present, honour an option only
- * if one appears promptly, and never let the layout step gate the save.
+ * `一键排版` applies the platform's own layout to the pasted body. The operator walk of 2026-10-10 shows
+ * the control is present and expected to be applied, so a click that leads nowhere is now REPORTED
+ * rather than swallowed (the earlier version failed silently, which is why 正文 came out unformatted).
+ *
+ * The format set (`保留源格式` / `匹配目标格式` / `仅保留文本`) is what we want when it renders as a menu;
+ * `匹配目标格式` is the correct choice for markdown-derived content. A build where the trio is only a
+ * label (the 2026-10-05 dogfood reading) still gets the bare control click, and says so.
  */
-async function applyLayout(page: WechatPage, deps: ModeRunDeps): Promise<void> {
+async function applyLayout(page: WechatPage, deps: ModeRunDeps): Promise<string | null> {
+    // Measured 2026-10-13: the current editor build exposes no 一键排版 control at all. An absent
+    // control is the platform's layout — silently skip; only a found-but-failing control warns.
+    const control = await tryFindSelector(page, LAYOUT_CONTROL, Math.min(deps.stepTimeoutMs, 5_000));
+    if (control === undefined) return null;
     try {
-        const control = await findSelector(page, LAYOUT_CONTROL, '一键排版 control', deps.stepTimeoutMs);
         await clickSelector(page, control, deps.stepTimeoutMs);
-        const option = await findSelector(page, LAYOUT_TARGET, '匹配目标格式 option', 1500).catch(() => null);
-        if (option !== null) await clickSelector(page, option, 1500);
-    } catch {
-        // No layout control on this editor build — the draft still saves.
+    } catch (error) {
+        return `一键排版: click failed — ${error instanceof Error ? error.message : String(error)}`;
+    }
+    const option = await tryFindSelector(page, LAYOUT_TARGET, 5_000);
+    if (option === undefined) {
+        return '一键排版: clicked, but no 匹配目标格式 option appeared — the body may be unformatted; check the draft';
+    }
+    try {
+        await clickSelector(page, option, 5_000);
+        return null;
+    } catch (error) {
+        return `一键排版: 匹配目标格式 not applied — ${error instanceof Error ? error.message : String(error)}`;
     }
 }
 
@@ -489,47 +607,207 @@ async function fillOptional(
     }
 }
 
+/** Local path basename — the only piece of a requested file a remote asset could ever expose. */
+function baseName(path: string): string {
+    return path.split(/[\\/]/).pop() ?? path;
+}
+
+/** The identities `setCover` can accept for a candidate: the requested article image and/or the
+ *  upload binding actually observed going into the audio form. Either is optional; at least one
+ *  must produce a UNIQUE exposed match before anything is clicked (task 0260 R1). */
+interface CoverIdentity {
+    /** `coverPath(input)` — the article's first body image, requested as the cover. */
+    requested?: string;
+    /** The cover file the audio upload just bound into the form/library (when audio ran). */
+    binding?: string;
+}
+
 /**
- * 封面 from the body (§5.2): there is no cover file input, so the panel's `从正文选择` picks the first
- * body image. Best-effort and recorded: the panel states 默认首图为封面, so the first body image is
- * already the cover, and only the explicit pick's failure is reported as a warning.
+ * 封面 (§5.2): there is no cover file input. `从图片库选择` picks the episode cover, `从正文选择`
+ * the first body image. A candidate is identified ONLY by an exposed exact filename (`title` /
+ * `data-name` / its own filename text) uniquely equal to one of the requested identities; a miss or
+ * an ambiguity warns WITHOUT clicking first/newest. After the confirm, the committed preview under
+ * `#js_cover_area` is read back: the empty state (`add_cover` icon still visible) or an unreadable
+ * preview is a named warning, never a success claim (task 0260 R1).
  */
-async function setCoverFromBody(page: WechatPage, deps: ModeRunDeps): Promise<string | null> {
-    const open = await tryFindSelector(page, COVER_PANEL_OPEN, Math.min(deps.stepTimeoutMs, 5_000));
-    if (open === undefined)
-        return 'cover: the panel offers neither 从正文选择 nor its openers — the platform default (默认首图为封面) is all this run has';
+async function setCover(
+    page: WechatPage,
+    source: 'library' | 'body',
+    deps: Pick<ModeRunDeps, 'stepTimeoutMs'>,
+    identity: CoverIdentity,
+): Promise<string | null> {
+    const picker = source === 'library' ? COVER_FROM_LIBRARY : COVER_FROM_CONTENT;
+    const what = source === 'library' ? '从图片库选择' : '从正文选择';
+    const wanted = [
+        ...(identity.requested ? [baseName(identity.requested)] : []),
+        ...(identity.binding ? [baseName(identity.binding)] : []),
+    ]
+        .map((name) => name.trim())
+        .filter((name) => name.length > 0);
+    // A cover miss is a warning, never a gate — so the panel must not outlive the step that opened
+    // it (see {@link dismissOpenDialog} for what its footer blocked on 2026-10-12).
+    const warn = async (message: string): Promise<string> => {
+        await dismissOpenDialog(page);
+        return message;
+    };
     try {
+        const open = await tryFindSelector(page, COVER_PANEL_OPEN, Math.min(deps.stepTimeoutMs, 5_000));
+        if (open === undefined)
+            return await warn(
+                'cover: the panel offers none of 从正文选择 / 从图片库选择 — the platform default (默认首图为封面) is all this run has',
+            );
         await clickSelector(page, open, deps.stepTimeoutMs);
-        const pick = await tryFindSelector(page, COVER_FROM_CONTENT, Math.min(deps.stepTimeoutMs, 5_000));
-        if (pick === undefined) return 'cover: 从正文选择 was not offered by the open cover panel';
+        const pick = await tryFindSelector(page, picker, Math.min(deps.stepTimeoutMs, 8_000));
+        if (pick === undefined) return await warn(`cover: ${what} was not offered by the open cover panel`);
         await clickSelector(page, pick, deps.stepTimeoutMs);
-        const item = await tryFindSelector(page, COVER_ITEM, Math.min(deps.stepTimeoutMs, 5_000));
-        if (item === undefined)
-            return 'cover: the panel listed no body image to choose (its list is not <img>-based, §5.2)';
-        await clickSelector(page, item, deps.stepTimeoutMs);
-        const confirm = await tryFindSelector(page, COVER_CONFIRM, Math.min(deps.stepTimeoutMs, 5_000));
-        if (confirm === undefined) return 'cover: the choice panel offered no confirm control';
+        if (wanted.length === 0)
+            return await warn(`cover: no requested cover file identity to match against — ${what} not driven`);
+        // Identify before clicking: the item list is not <img>-based (§5.2) and never sorted the way
+        // a first-item assumption needs, so the only honest pick is an exposed unique exact name.
+        const IDENTIFY = `(() => {
+            const wanted = ${JSON.stringify(wanted)};
+            const rows = [...document.querySelectorAll('.weui-desktop-img-picker__item, div[class*="img_picker" i] li, div[class*="imgList" i] li, div[class*="cover" i] li')]
+                .filter((row) => row.offsetWidth > 0);
+            const nameOf = (row) => {
+                const el = row.querySelector('[title], [data-name], [data-file_name]') ?? row;
+                const attrs = [el.getAttribute?.('title'), el.getAttribute?.('data-name'), el.getAttribute?.('data-file_name')];
+                const text = [...row.querySelectorAll('[class*="name" i], [class*="title" i]')].map((n) => n.textContent ?? '');
+                return [...attrs, ...text].map((v) => (v ?? '').trim()).find((v) => v.length > 0) ?? '';
+            };
+            const hits = rows.filter((row) => wanted.some((w) => nameOf(row) === w));
+            if (hits.length === 0) return 'missing';
+            if (hits.length > 1) return 'ambiguous';
+            const row = hits[0];
+            row.querySelector('input[type=checkbox], [role=checkbox]')?.click();
+            row.click();
+            const checked = row.querySelector('input[type=checkbox], [role=checkbox]');
+            const src = row.querySelector('img')?.src ?? (row.querySelector('[style*="background-image"]')?.style.backgroundImage.match(/url("?([^")]+)"?)/)?.[1] ?? '');
+            return JSON.stringify({ picked: true, src });
+        })()`;
+        const rawIdentify = String(await page.evaluate(IDENTIFY));
+        if (rawIdentify === 'missing')
+            return await warn(`cover: ${what} 未标出与请求文件同名的素材，未选择（不按首图猜测）`);
+        if (rawIdentify === 'ambiguous') return await warn(`cover: ${what} 匹配到多个同名素材，身份不唯一，未选择`);
+        let selected: { picked?: boolean; src?: string } = {};
+        try {
+            selected = JSON.parse(rawIdentify) as { picked?: boolean; src?: string };
+        } catch {
+            return await warn('cover: 素材身份探测返回未知结果，未选择');
+        }
+        // The library picker stages the choice: 下一步 advances it, then the dialog confirms.
+        const next = await tryFindSelector(page, COVER_LIBRARY_NEXT, Math.min(deps.stepTimeoutMs, 4_000));
+        if (next !== undefined) await clickSelector(page, next, deps.stepTimeoutMs);
+        const confirm = await tryFindSelector(page, COVER_CONFIRM, Math.min(deps.stepTimeoutMs, 8_000));
+        if (confirm === undefined) return await warn('cover: the choice panel offered no confirm control');
         await clickSelector(page, confirm, deps.stepTimeoutMs);
+        // Committed readback (observed capture: the preview lives under #js_cover_area; the empty
+        // state keeps the `add_cover` icon visible). Poll briefly — the preview renders late.
+        const READBACK = `(() => {
+            const area = document.querySelector('#js_cover_area');
+            if (!area) return 'noarea';
+            if (area.querySelector('.icon20_common.add_cover') && area.querySelector('.icon20_common.add_cover').offsetWidth > 0) return 'empty';
+            const preview = area.querySelector('.js_cover_preview_new');
+            if (!preview || preview.offsetWidth === 0) return 'nopreview';
+            const src = preview.querySelector('img')?.src ??
+                (preview.querySelector('[style*="background-image"]')?.style.backgroundImage.match(/url("?([^")]+)"?)/)?.[1] ?? '') ||
+                (preview.querySelector('input[type=hidden]')?.value ?? '');
+            return src ? src : 'unknown';
+        })()`;
+        let committed = '';
+        for (let read = 0; read < 5 && committed === ''; read += 1) {
+            const raw = String(await page.evaluate(READBACK).catch(() => 'error'));
+            if (raw !== '' && raw !== 'nopreview' && raw !== 'noarea') {
+                committed = raw;
+                break;
+            }
+            await page.waitForTimeout?.(600);
+        }
+        if (committed === 'empty') return await warn('cover: 确认后面板仍显示未设置封面，提交未生效');
+        if (committed === '' || committed === 'noarea' || committed === 'error')
+            return await warn('cover: 已确认但无法读取已提交封面，请手动核对');
+        // Identity comparison: both sides are remote asset references from the same widget. Only an
+        // exact match proves the requested asset committed; an unreadable/edited preview warns
+        // rather than inventing equivalence (local paths are never compared to asset URLs).
+        const selectedSrc = (selected.src ?? '').trim();
+        if (selectedSrc === '' || (committed !== selectedSrc && !committed.includes(selectedSrc)))
+            return await warn(
+                `cover: 已提交封面的素材身份与所选不一致（selected=${selectedSrc || '未读到'} committed=${committed.slice(0, 80)}）`,
+            );
         return null;
     } catch (error) {
-        return `cover: ${error instanceof Error ? error.message : String(error)}`;
+        return await warn(`cover: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
 
-/** 文章's `metadata.wechatmp` enrichment rail, plus its opt-in audio embed (§5.2, ADR-026). */
-async function enrichArticleDraft(page: WechatPage, content: Content): Promise<string[]> {
+/** `metadata.wechatmp.coverSource` — `library` (default) is the uploaded episode cover. */
+function coverSourceOf(content: Content): 'library' | 'body' {
+    const meta = content.metadata?.wechatmp;
+    if (meta === null || typeof meta !== 'object' || Array.isArray(meta)) return 'library';
+    return (meta as Record<string, unknown>).coverSource === 'body' ? 'body' : 'library';
+}
+
+/** The audio-embed block of `metadata.wechatmp`, or null when this run embeds no audio. Shared by
+ *  the cover step (the library only holds the episode cover once audio uploaded — task 0272). */
+function audioBlockOf(content: Content): { title: string; audioPath: string; coverPath: string } | null {
+    const meta = content.metadata?.wechatmp;
+    if (meta === null || typeof meta !== 'object' || Array.isArray(meta)) return null;
+    const m = meta as Record<string, unknown>;
+    if (
+        typeof m.audioTitle !== 'string' ||
+        m.audioTitle.trim() === '' ||
+        typeof m.audioPath !== 'string' ||
+        m.audioPath === ''
+    )
+        return null;
+    return {
+        title: m.audioTitle.trim(),
+        audioPath: m.audioPath,
+        coverPath: typeof m.audioCoverPath === 'string' ? m.audioCoverPath : '',
+    };
+}
+
+/** 文章's `metadata.wechatmp` enrichment rail, plus its opt-in audio embed (2026-09-29, ADR-026). */
+async function enrichArticleDraft(
+    page: WechatPage,
+    content: Content,
+): Promise<{ enrichWarnings: string[]; coverWarnings: string[] }> {
     const enrichMeta = content.metadata?.wechatmp;
-    if (enrichMeta === undefined || typeof enrichMeta !== 'object' || Array.isArray(enrichMeta)) return [];
-    const warnings = await enrichArticle(page, enrichMeta as Record<string, unknown>);
-    const audioTitle = (enrichMeta as Record<string, unknown>).audioTitle;
-    if (typeof audioTitle === 'string' && audioTitle.trim() !== '') {
-        const audioWarning = await insertAudio(page, audioTitle.trim());
-        if (audioWarning !== '') warnings.push(audioWarning);
+    if (enrichMeta === undefined || typeof enrichMeta !== 'object' || Array.isArray(enrichMeta))
+        return { enrichWarnings: [], coverWarnings: [] };
+    const meta = enrichMeta as Record<string, unknown>;
+    const enrichWarnings = await enrichArticle(page, meta);
+    const audio = audioBlockOf(content);
+    let audioFailed = false;
+    if (audio !== null) {
+        const audioWarning = await insertAudioMaterial(page, audio);
+        if (audioWarning !== '') {
+            enrichWarnings.push(audioWarning);
+            audioFailed = true;
+        }
+    }
+    // Deferred library cover (task 0272): the audio upload just put the episode cover in the 图片库 —
+    // but ONLY a committed upload guarantees that (task 0260 R1: a failed/uncertain audio upload
+    // leaves the library without the requested cover, so the dependent picker must not run).
+    const coverWarnings: string[] = [];
+    if (coverSourceOf(content) === 'library' && audio !== null) {
+        if (audioFailed) {
+            coverWarnings.push('cover: 音频上传未成功，图片库不保证已有请求封面，已跳过图片库封面');
+        } else {
+            const cover = await setCover(
+                page,
+                'library',
+                { stepTimeoutMs: 8_000 },
+                // The upload binding is the image the audio form just bound (the episode cover
+                // file); `coverPath(input)` is the article's own first body image, not this.
+                { binding: audio.coverPath === '' ? undefined : audio.coverPath },
+            );
+            if (cover !== null) coverWarnings.push(cover);
+        }
     }
-    return warnings;
+    return { enrichWarnings, coverWarnings };
 }
 
-/** Compose 文章 (createType 0): body images, title, body + 一键排版, 摘要, 作者, cover from the body. */
+/** Compose 文章 (createType 0): body images, title, body + 一键排版, 摘要, 作者, cover, settings. */
 async function composeArticle(
     input: { operation: '文章'; images: string[]; digest?: string },
     deps: ModeRunDeps,
@@ -540,16 +818,28 @@ async function composeArticle(
     await attachImages(page, input.images, deps);
     const titlePath = await typeTitle(page, deps);
     await insertBody(page, deps);
-    await applyLayout(page, deps);
+    const layout = await applyLayout(page, deps);
+    if (layout !== null) warnings.push(layout);
     for (const warning of [
         await fillOptional(page, DIGEST_INPUT, input.digest ?? '', '摘要', deps),
         await fillOptional(page, AUTHOR_INPUT, authorOf(deps.content), '作者', deps),
     ]) {
         if (warning !== null) warnings.push(warning);
     }
-    const cover = await setCoverFromBody(page, deps);
-    if (cover !== null) warnings.push(cover);
-    return { warnings, titlePath, enrichWarnings: await enrichArticleDraft(page, deps.content) };
+    const coverSource = coverSourceOf(deps.content);
+    const audioRuns = audioBlockOf(deps.content) !== null;
+    if (!(coverSource === 'library' && audioRuns)) {
+        const cover = await setCover(page, coverSource, deps, {
+            // Requested identity = the article's first body image (the 默认首图为封面 semantics of
+            // modes.coverPath). No audio ran, so the library binding is unknown — only an exposed
+            // exact filename can match.
+            requested: input.images[0],
+        });
+        if (cover !== null) warnings.push(cover);
+    }
+    const { enrichWarnings, coverWarnings } = await enrichArticleDraft(page, deps.content);
+    warnings.push(...coverWarnings);
+    return { warnings, titlePath, enrichWarnings };
 }
 
 /** Compose 贴图 (createType 8): ≥1 image is the message; title and body are 选填. */
@@ -647,8 +937,18 @@ async function compose(input: ModeInput, deps: ModeRunDeps, entry: ModeEntry): P
 }
 
 function authorOf(content: Content): string {
-    const author = content.metadata?.author;
-    return typeof author === 'string' ? author : '';
+    // The 作者 field is the byline readers see. The daily stage carries it as `metadata.wechatmp.author`
+    // (with the other MP preferences); `metadata.author` is the generic Content field and wins when a
+    // producer sets it directly. Reading only the generic one left 请输入作者 empty on every daily run
+    // (operator report 2026-10-10).
+    const wechatmp = content.metadata?.wechatmp;
+    const scoped =
+        wechatmp !== null && typeof wechatmp === 'object' && !Array.isArray(wechatmp)
+            ? (wechatmp as Record<string, unknown>).author
+            : undefined;
+    const generic = content.metadata?.author;
+    if (typeof generic === 'string' && generic.trim() !== '') return generic.trim();
+    return typeof scoped === 'string' ? scoped.trim() : '';
 }
 
 function baseMetadata(input: ModeInput, deps: ModeRunDeps, entry: ModeEntry): Record<string, unknown> {
@@ -685,10 +985,20 @@ async function saveDraft(
     let control: string | null = null;
     let signal: string | null = null;
     let attempts = 0;
+    let residuals = 0;
+    const residualDialogs: string[] = [];
     let stampAfter: string | null = deps.draftBaseline.stamp;
     while (signal === null && attempts < deps.submitAttempts) {
         attempts += 1;
         await sleep(deps.submitSettleMs);
+        if ((await closeOpenDialogs(entry.editor)) !== 'closed') {
+            residuals += 1;
+            residualDialogs.push(await openDialogInventory(entry.editor).catch(() => 'unreadable'));
+            // Refuse to click through an unresolved overlay (0260 R3/AC5): the click would land on
+            // the dialog footer again, not 保存为草稿. Retry the cleanup on the next attempt.
+            if (attempts < deps.submitAttempts) continue;
+            break;
+        }
         control = await findSelector(entry.editor, SAVE_DRAFT, '保存为草稿 control', deps.stepTimeoutMs);
         await clickSelector(entry.editor, control, deps.stepTimeoutMs);
         // The editor lives in its own tab, so re-read the console entry page — and ENTER the 草稿箱
@@ -711,6 +1021,10 @@ async function saveDraft(
     }
 
     if (signal === null || control === null) {
+        if (control === null)
+            return fail(
+                `draft confirmation: a residual modal refused cleanup after ${attempts} attempt(s), ${residuals} refused cleanup(s) (${residualDialogs.join(' | ') || 'no inventory'}) — '保存为草稿' was not clicked through an unresolved overlay (inventory: ${await openDialogInventory(entry.editor).catch(() => 'unreadable')})`,
+            );
         return fail(
             `draft confirmation: '${SAVE_DRAFT[0]}' was clicked ${attempts}× but no fresh 草稿箱 row for '${title}' (its ${DRAFT_STAMP} stamp) was observed within ${deps.draftTimeoutMs}ms (before=${deps.draftBaseline.stamp ?? 'none'}, after=${stampAfter ?? 'none'}, page=${deps.entry.url()}, frames=${await describeFrames(deps.entry, 5)})`,
         );
@@ -727,6 +1041,13 @@ async function saveDraft(
             draftStampBefore: deps.draftBaseline.stamp,
             draftStampAfter: signal,
             titlePath: composed.titlePath,
+            ...(residuals > 0
+                ? {
+                      warnings: [
+                          `保存前清理了 ${residuals} 个残留弹层（${residualDialogs.join(' | ')}），草稿仍保存成功`,
+                      ],
+                  }
+                : {}),
             ...(composed.warnings.length > 0 ? { warnings: composed.warnings } : {}),
             ...(composed.enrichWarnings.length > 0 ? { enrichWarnings: composed.enrichWarnings } : {}),
         },
@@ -792,6 +1113,23 @@ async function publishContent(
     });
 }
 
+/**
+ * Text inventory of whatever modal is still open on `page` — the diagnostic a blocked submit click
+ * needs (2026-10-12: `保存为草稿` was covered by a dialog footer for 30 s and the failure named only
+ * the Playwright timeout). Covers the inner dialog and the overlay wrapper, both of which can be the
+ * element that intercepts pointer events.
+ */
+async function openDialogInventory(page: WechatPage): Promise<string> {
+    const raw = await page
+        .evaluate(
+            `[...document.querySelectorAll('.weui-desktop-dialog, .weui-desktop-dialog__wrp')]` +
+                `.filter((d) => d.offsetWidth).map((d) => (d.className || '') + ' :: ' + ` +
+                `(d.innerText || '').replace(/\\s+/g, ' ').slice(0, 160)).join(' || ')`,
+        )
+        .catch(() => '');
+    return typeof raw === 'string' ? raw.slice(0, 600) : '';
+}
+
 /**
  * Run one validated operation end to end: enter its mode, compose the post, then take it to a draft
  * or — only on an explicit live request — publish it.
@@ -799,9 +1137,24 @@ async function publishContent(
 export async function runMode(input: ModeInput, deps: ModeRunDeps): Promise<Result> {
     const entry = await enterMode(deps, input.operation);
     const composed = await compose(input, deps, entry);
-    return deps.publishStatus === 'public'
-        ? publishContent(input, deps, entry, composed)
-        : saveDraft(input, deps, entry, composed);
+    // 2026-10-12: a throw from the submit step drops every diagnostic the compose phase collected —
+    // a leaked settings dialog blocked 保存为草稿 on the daily run and the failure Result carried only
+    // the Playwright timeout, so the stuck step had to be rediscovered by hand. Ride them on the error.
+    const diagnostics = [...composed.warnings, ...composed.enrichWarnings];
+    try {
+        return deps.publishStatus === 'public'
+            ? await publishContent(input, deps, entry, composed)
+            : await saveDraft(input, deps, entry, composed);
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const blocked = await openDialogInventory(entry.editor);
+        const carried = [
+            ...(diagnostics.length > 0 ? [`compose diagnostics: ${diagnostics.join(' | ')}`] : []),
+            ...(blocked !== '' ? [`open dialogs at submit: ${blocked}`] : []),
+        ];
+        if (carried.length === 0) throw error;
+        throw new Error(`${message} — ${carried.join(' — ')}`);
+    }
 }
 
 /**
@@ -894,3 +1247,207 @@ export function markdownToWechatHtml(markdown: string): string {
 function escapeHtml(text: string): string {
     return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 }
+
+/**
+ * Audio at the article top (operator request 2026-09-29; upload path added 2026-10-10).
+ *
+ * Reuses a same-title 素材库 material when one exists (UNIQUE exposed-title match, identity
+ * captured); otherwise UPLOADS it. The operator's measured upload shape: 音频 menu → 上传音频 → pick
+ * the audio file → 上传封面 → pick the cover → type the title → tick 我已阅读并同意《公众平台音频上传服务规则》
+ * → 保存 → the material list reopens → select the row whose exposed title matches uniquely → 插入.
+ * 插入 places it at the caret, so the caret is put at the body start first.
+ *
+ * Fail-soft — every non-committed outcome returns a warning string; `''` means the inserted node is
+ * the body's first content AND carries the selected material's identity (task 0260 R2).
+ */
+export async function insertAudioMaterial(
+    page: WechatPage,
+    input: { title: string; audioPath: string; coverPath: string },
+): Promise<string> {
+    const { title, audioPath, coverPath } = input;
+    const CARET = `(() => {
+            const pm = [...document.querySelectorAll('.ProseMirror')].find((e) => !(e.getAttribute('data-placeholder') ?? '').includes('标题'));
+            if (!pm || !pm.firstChild) return;
+            const r = document.createRange();
+            r.setStart(pm.firstChild, 0);
+            r.collapse(true);
+            const sel = window.getSelection();
+            sel?.removeAllRanges();
+            sel?.addRange(r);
+        })()`;
+    /** Trim + collapse whitespace/NBSP — MP titles carry `&nbsp;` entities (0272 capture). */
+    const norm = (value: unknown): string =>
+        typeof value === 'string' ? value.replace(/[\s\u00a0]+/g, ' ').trim() : '';
+    /** Unique exposed-title match; ticks only an unticked row and captures its stable identity
+     *  (data-mediaid/data-id, else the thumb's media URL) for the body readback. Never first-item. */
+    const MATCH = `(() => {
+            const norm = (v) => (v ?? '').replace(/[\\s\\u00a0]+/g, ' ').trim();
+            const want = ${JSON.stringify(norm(title))};
+            const rows = [...document.querySelectorAll('label.frm_checkbox_label.audio_item')]
+                .filter((l) => l.offsetWidth > 0);
+            const hits = rows.filter((l) => norm((l.querySelector('.audio_title') ?? l).textContent) === want);
+            if (hits.length === 0) return 'missing';
+            if (hits.length > 1) return 'ambiguous';
+            const hit = hits[0];
+            const cb = (hit.closest('li') ?? hit.parentElement)?.querySelector('input[type=checkbox]');
+            if (!cb) return 'nobox';
+            if (!cb.checked) cb.click();
+            const wrp = hit.closest('.audio_item_wrp') ?? hit.parentElement;
+            const thumb = wrp?.querySelector('.audio_item_thumb');
+            const identity = wrp?.getAttribute('data-mediaid') ?? wrp?.getAttribute('data-id') ??
+                (thumb ? (thumb.style.backgroundImage.match(/url\\("?([^")]+)"?\\)/)?.[1] ?? '') : '');
+            return JSON.stringify({ state: 'checked', identity });
+        })()`;
+    /** Tick the service-rules acknowledgement, found by its own label text rather than a class. */
+    const AGREE = `(() => {
+            const node = [...document.querySelectorAll('label, span, div')]
+                .find((e) => (e.textContent ?? '').includes('我已阅读并同意') && e.children.length === 0);
+            if (!node) return 'no-label';
+            const scope = node.closest('label') ?? node.parentElement;
+            const cb = scope?.querySelector('input[type=checkbox]') ?? document.querySelector('input[type=checkbox].js_agree');
+            if (!cb) return 'no-box';
+            if (!cb.checked) cb.click();
+            return cb.checked ? 'checked' : 'unchecked';
+        })()`;
+    const INSERT = `(() => {
+            const btn = [...document.querySelectorAll('button')].find((b) => (b.textContent ?? '').trim() === '插入' && b.offsetWidth > 0);
+            if (!btn) return false;
+            btn.click();
+            return true;
+        })()`;
+    const CANCEL = `(() => {
+            const btn = [...document.querySelectorAll('button')].find((b) => (b.textContent ?? '').trim() === '取消' && b.offsetWidth > 0);
+            btn?.click();
+        })()`;
+    const VERIFY = `(() => {
+            const pm = [...document.querySelectorAll('.ProseMirror')].find((e) => !(e.getAttribute('data-placeholder') ?? '').includes('标题'));
+            if (!pm) return JSON.stringify({ state: 'noeditor' });
+            const first = pm.firstElementChild;
+            if (!first) return JSON.stringify({ state: 'absent' });
+            const node = first.matches('mpvoice, [data-mediaid]') ? first : first.querySelector('mpvoice, [data-mediaid]');
+            if (!node) return JSON.stringify({ state: 'absent' });
+            const identity = node.getAttribute('data-mediaid') ?? node.getAttribute('data-appid') ??
+                node.getAttribute('data-src') ?? node.getAttribute('src') ?? '';
+            return JSON.stringify({ state: 'top', identity });
+        })()`;
+
+    /** Upload the audio + its cover, acknowledge the rules, and 保存. Returns a warning or null. */
+    const upload = async (): Promise<string | null> => {
+        const uploadControl = await trySelectors(page, UPLOAD_AUDIO);
+        if (!uploadControl.found) return '音频: 上传音频 control not found in the audio dialog';
+        // Click the winner, never a joined union: `text=…, css…` mixes selector engines and
+        // Playwright parses the whole string as CSS — zero matches (DOM fixture 0260).
+        await clickSelector(page, uploadControl.selector ?? UPLOAD_AUDIO[0] ?? 'text=上传音频', 8_000);
+        const audioInput = await trySelectors(page, AUDIO_UPLOAD_INPUT);
+        if (!audioInput.found) return '音频: no audio file input appeared';
+        await uploadFile(asPlaywrightPage(page), audioInput.selector ?? AUDIO_UPLOAD_INPUT.join(', '), audioPath, {
+            timeoutMs: 60_000,
+        });
+        // The form requires a cover before it will save.
+        const coverControl = await trySelectors(page, UPLOAD_COVER);
+        if (coverControl.found) {
+            await clickSelector(page, coverControl.selector ?? UPLOAD_COVER[0] ?? 'text=上传封面', 8_000);
+            const coverInput = await trySelectors(page, AUDIO_COVER_INPUT);
+            if (coverInput.found)
+                await uploadFile(
+                    asPlaywrightPage(page),
+                    coverInput.selector ?? AUDIO_COVER_INPUT.join(', '),
+                    coverPath,
+                    {
+                        timeoutMs: 60_000,
+                    },
+                );
+        }
+        const titleInput = await trySelectors(page, AUDIO_TITLE_INPUT);
+        if (titleInput.found) await fillSelector(page, titleInput.selector ?? AUDIO_TITLE_INPUT.join(', '), title);
+        const agreed = String(await page.evaluate(AGREE));
+        if (agreed !== 'checked') return `音频: 服务规则勾选失败 (${agreed})`;
+        const save = await trySelectors(page, UPLOAD_SAVE);
+        if (!save.found) return '音频: 上传表单的保存按钮未找到';
+        await clickSelector(page, UPLOAD_SAVE.join(', '), 8_000);
+        return null;
+    };
+
+    /** One MATCH read; a throwing probe stays 'error' (unknown, never treated as missing). */
+    const matchOnce = async (): Promise<string> => {
+        try {
+            return String(await page.evaluate(MATCH));
+        } catch {
+            return 'error';
+        }
+    };
+    /** Poll the picker while rows stream in; 'missing' keeps polling, JSON answers settle it. */
+    const awaitMatch = async (): Promise<string> => {
+        let match = await matchOnce();
+        for (let i = 0; match === 'missing' && i < AUDIO_ROW_RETRIES; i += 1) {
+            await page.waitForTimeout?.(AUDIO_ROW_SETTLE_MS);
+            match = await matchOnce();
+        }
+        return match;
+    };
+    try {
+        await page.evaluate(CARET);
+        // Open the toolbar dropdown first (measured 2026-10-13): the menu item is hidden until its
+        // trigger is clicked, so the old direct `js_insertaudio` click timed out.
+        await page.evaluate(`document.querySelector(${JSON.stringify(AUDIO_TOOLBAR_TRIGGER)})?.click()`);
+        await page.waitForTimeout?.(300);
+        await page.evaluate(`document.querySelector(${JSON.stringify(AUDIO_MENU)})?.click()`);
+        await waitForVisible(page, AUDIO_DIALOG, AUDIO_DIALOG_TIMEOUT_MS);
+        let match = await awaitMatch();
+        if (match === 'missing') {
+            // No reusable material: upload one, then POLL until the new row actually exists — never
+            // assume the upload auto-selected a default row (task 0260 AC2).
+            const uploadWarning = await upload();
+            if (uploadWarning !== null) {
+                await page.evaluate(CANCEL);
+                return uploadWarning;
+            }
+            await waitForVisible(page, AUDIO_DIALOG, AUDIO_DIALOG_TIMEOUT_MS);
+            match = await awaitMatch();
+            if (match === 'missing') {
+                await page.evaluate(CANCEL);
+                return `音频: 保存后素材列表未出现「${title}」，未插入音频`;
+            }
+            if (match === 'error') {
+                await page.evaluate(CANCEL);
+                return '音频: 保存后素材匹配探测失败，未插入音频';
+            }
+        } else if (match === 'error') {
+            await page.evaluate(CANCEL);
+            return '音频: 素材匹配探测失败，未插入音频';
+        }
+        // Parse the match; anything but a unique ticked row stays a warning (never first-item).
+        let identity = '';
+        try {
+            const parsed = JSON.parse(match) as { state?: string; identity?: string };
+            if (parsed.state !== 'checked') {
+                await page.evaluate(CANCEL);
+                return `音频: 素材「${title}」${parsed.state === 'ambiguous' ? '列表匹配到多个同名条目，身份不唯一' : parsed.state === 'nobox' ? '行没有勾选框' : '未选中'}，未插入音频`;
+            }
+            identity = parsed.identity ?? '';
+        } catch {
+            await page.evaluate(CANCEL);
+            return '音频: 素材匹配探测返回未知结果，未插入音频';
+        }
+        if ((await page.evaluate(INSERT)) !== true) {
+            await page.evaluate(CANCEL);
+            return '音频: 插入按钮未找到，请手动插入';
+        }
+        await page.waitForTimeout?.(2_000);
+        let verdict: { state?: string; identity?: string };
+        try {
+            verdict = JSON.parse(String(await page.evaluate(VERIFY))) as { state?: string; identity?: string };
+        } catch {
+            return '音频: 已插入但无法读取正文状态，请手动检查';
+        }
+        if (verdict.state === 'absent' || verdict.state === 'noeditor') return '音频: 插入未生效，请手动检查';
+        if (verdict.state !== 'top') return '音频: 已插入但未在文首，请手动调整位置';
+        // Identity readback (0260 R2): success requires the selected identity to reappear on the
+        // inserted node; an unreadable identity is an unverifiable warning, never a silent pass.
+        if (identity === '' || (verdict.identity ?? '') === '' || verdict.identity !== identity)
+            return `音频: 已插入文首但无法核对素材身份（selected=${identity || '未读到'} node=${(verdict.identity ?? '').slice(0, 60) || '未读到'}），请手动核对`;
+        return '';
+    } catch (error) {
+        return `音频: ${error instanceof Error ? error.message.slice(0, 120) : '自动插入失败'}，请手动插入`;
+    }
+}