@agentrhq/webcmd 0.1.1 → 0.2.0

package/clis/xiaohongshu/publish.js

@@ -1,1423 +0,0 @@
-/**
- * Xiaohongshu 图文笔记 publisher — creator center UI automation.
- *
- * Flow:
- *   1. Navigate to creator publish page
- *   2. Upload images via CDP DOM.setFileInputFiles (with base64 fallback)
- *   3. Fill title and body text
- *   4. Add topic hashtags
- *   5. Publish (or save as draft)
- *
- * Requires: logged into creator.xiaohongshu.com in Chrome.
- *
- * Usage:
- *   webcmd xiaohongshu publish --title "标题" "正文内容" \
- *     --images /path/a.jpg,/path/b.jpg \
- *     --topics 生活,旅行
- */
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import { CommandExecutionError, ArgumentError } from '@agentrhq/webcmd/errors';
-import { cli, Strategy } from '@agentrhq/webcmd/registry';
-const PUBLISH_URL = 'https://creator.xiaohongshu.com/publish/publish?from=menu_left&target=image';
-const MAX_IMAGES = 9;
-const MAX_TITLE_LEN = 20;
-const UPLOAD_SETTLE_MS = 3000;
-const CARD_TEXT_DELIM = '|||';
-const DEFAULT_CARD_STYLE = '基础';
-// Example styles for help text only — the real options are read live from the
-// (virtualized, content-dependent) 预览图片 strip at runtime, so this list is NOT
-// used to validate input; an unavailable requested style fails before submit.
-// 文字配图 --card-style catalog: each style name → the content it suits.
-// Styles are read live from the page at runtime (see selectCardStyle); this list
-// only powers --help, and an unmatched requested style is a typed failure.
-const CARD_STYLE_GUIDE = [
-    ['基础', '默认兜底，万能'],
-    ['边框', '金句/要点卡'],
-    ['备忘', '提醒/随手记'],
-    ['清新', '日常/清单贴士'],
-    ['涂写', '随笔/碎碎念'],
-    ['便签', '笔记/提醒'],
-    ['光影', '情绪/文艺'],
-    ['涂鸦', '趣味/童话'],
-    ['简约', '干货/观点'],
-    ['手写', '日记/情感'],
-    ['插图', '生活方式/轻松话题'],
-    ['美漫', '活力/趣味/故事感'],
-    ['弥散', '弥散光氛围'],
-    ['柔和', '柔和/温柔金句'],
-    ['印刷', '印刷海报/排版'],
-    ['科技', '科技/产品'],
-    ['贺卡', '节日祝福'],
-    ['札记', '艺术/水彩氛围'],
-    ['书摘', '书摘/引用'],
-    ['手帐', '手帐拼贴'],
-    ['几何', '醒目/有力主张'],
-];
-const CARD_STYLES = CARD_STYLE_GUIDE.map(([name]) => name);
-const TEXT_IMAGE_ENTRY_LABEL = '文字配图';
-const ADD_CARD_LABEL = '再写一张';
-const GENERATE_LABEL = '生成图片';
-const PREVIEW_NEXT_LABEL = '下一步';
-/** tiptap/ProseMirror card editor inside the 写文字 swiper. */
-const CARD_EDITOR_SELECTOR = '.tiptap.ProseMirror';
-/**
- * XHS creator center wraps the publish/save button in an `<xhs-publish-btn>`
- * web component backed by a CLOSED shadow root. Host-level `.click()` does
- * not dispatch into the internal handler. Invoke these instance methods on
- * the host element to trigger publish / save-draft directly (#1606).
- */
-const PUBLISH_METHOD_NAMES = ['_onPublish', 'onPublish', '_onSubmit', '_handlePublish'];
-const DRAFT_METHOD_NAMES = ['_onSave', '_onSaveDraft', '_onDraft'];
-/** Selectors for the title field, ordered by priority across current UI variants. */
-const TITLE_SELECTORS = [
-    // Some creator-center variants expose the title as contenteditable,
-    // others use a normal <input> with the same placeholder. Visible
-    // user-facing variants always carry a Chinese placeholder; class-based
-    // variants also match a pair of 4 px wide hidden scaffolding inputs
-    // (same `class*="title"`, empty placeholder, no v-model commit on save)
-    // so placeholder-based selectors take precedence to avoid filling those.
-    '[contenteditable="true"][placeholder*="标题"]',
-    '[contenteditable="true"][placeholder*="赞"]',
-    'input[placeholder*="标题"]',
-    'input[placeholder*="title" i]',
-    '[contenteditable="true"][class*="title"]',
-    'input[maxlength="20"]',
-    'input[class*="title"]',
-    '.title-input input',
-    '.note-title input',
-    'input[maxlength]',
-];
-/** Selectors for the note body / content editor, ordered by priority. */
-const BODY_SELECTORS = [
-    '[contenteditable="true"][class*="content"]',
-    '[contenteditable="true"][class*="editor"]',
-    '[contenteditable="true"][placeholder*="描述"]',
-    '[contenteditable="true"][placeholder*="正文"]',
-    '[contenteditable="true"][placeholder*="内容"]',
-    '.note-content [contenteditable="true"]',
-    '.editor-content [contenteditable="true"]',
-    // Broad fallback — last resort; filter out any title contenteditable
-    '[contenteditable="true"]:not([placeholder*="标题"]):not([placeholder*="赞"]):not([placeholder*="title" i])',
-];
-const SUPPORTED_EXTENSIONS = {
-    '.jpg': 'image/jpeg',
-    '.jpeg': 'image/jpeg',
-    '.png': 'image/png',
-    '.gif': 'image/gif',
-    '.webp': 'image/webp',
-};
-function unwrapBrowserResult(value) {
-    if (
-        value
-        && typeof value === 'object'
-        && typeof value.session === 'string'
-        && Object.prototype.hasOwnProperty.call(value, 'data')
-    ) {
-        return value.data;
-    }
-    return value;
-}
-/**
- * Validate image paths: check existence and extension.
- * Returns resolved absolute paths.
- */
-function validateImagePaths(filePaths) {
-    return filePaths.map((filePath) => {
-        const absPath = path.resolve(filePath);
-        if (!fs.existsSync(absPath))
-            throw new ArgumentError(`Image file not found: ${absPath}`);
-        const ext = path.extname(absPath).toLowerCase();
-        if (!SUPPORTED_EXTENSIONS[ext]) {
-            throw new ArgumentError(`Unsupported image format "${ext}". Supported: jpg, png, gif, webp`);
-        }
-        return absPath;
-    });
-}
-/** CSS selector for image-accepting file inputs. */
-const IMAGE_INPUT_SELECTOR = 'input[type="file"][accept*="image"],'
-    + 'input[type="file"][accept*=".jpg"],'
-    + 'input[type="file"][accept*=".jpeg"],'
-    + 'input[type="file"][accept*=".png"],'
-    + 'input[type="file"][accept*=".gif"],'
-    + 'input[type="file"][accept*=".webp"]';
-/**
- * Upload images via CDP DOM.setFileInputFiles — Chrome reads files directly
- * from the local filesystem, avoiding base64 payload size limits.
- *
- * Falls back to the legacy base64 DataTransfer approach if the extension
- * does not support set-file-input (e.g. older extension version).
- */
-async function uploadImages(page, absPaths) {
-    // ── Primary: CDP DOM.setFileInputFiles ──────────────────────────────
-    if (page.setFileInput) {
-        try {
-            // Find image-accepting file input on the page
-            const selector = await page.evaluate(`
-        (() => {
-          const sels = ${JSON.stringify(IMAGE_INPUT_SELECTOR)};
-          const el = document.querySelector(sels);
-          return el ? sels : null;
-        })()
-      `);
-            if (!selector) {
-                return { ok: false, count: 0, error: 'No file input found on page' };
-            }
-            await page.setFileInput(absPaths, selector);
-            return { ok: true, count: absPaths.length };
-        }
-        catch (err) {
-            // If set-file-input action is not supported by extension, fall through to legacy
-            const msg = err instanceof Error ? err.message : String(err);
-            if (msg.includes('Unknown action') || msg.includes('not supported') || msg.includes('Not allowed')) {
-                // Extension too old — fall through to legacy base64 method
-            }
-            else {
-                return { ok: false, count: 0, error: msg };
-            }
-        }
-    }
-    // ── Fallback: legacy base64 DataTransfer injection ─────────────────
-    const images = absPaths.map((absPath) => {
-        const base64 = fs.readFileSync(absPath).toString('base64');
-        const ext = path.extname(absPath).toLowerCase();
-        return { name: path.basename(absPath), mimeType: SUPPORTED_EXTENSIONS[ext], base64 };
-    });
-    // Warn if total payload is large — this may fail with older extensions
-    const totalBytes = images.reduce((sum, img) => sum + img.base64.length, 0);
-    if (totalBytes > 500_000) {
-        console.warn(`[warn] Total image payload is ${(totalBytes / 1024 / 1024).toFixed(1)}MB (base64). ` +
-            'This may fail with the browser bridge. Update the extension to v1.6+ for CDP-based upload, ' +
-            'or compress images before publishing.');
-    }
-    const payload = JSON.stringify(images);
-    return page.evaluate(`
-    (async () => {
-      const images = ${payload};
-
-      const inputs = Array.from(document.querySelectorAll('input[type="file"]'));
-      const input = inputs.find(el => {
-        const accept = el.getAttribute('accept') || '';
-        return (
-          accept.includes('image') ||
-          accept.includes('.jpg') ||
-          accept.includes('.jpeg') ||
-          accept.includes('.png') ||
-          accept.includes('.gif') ||
-          accept.includes('.webp')
-        );
-      });
-
-      if (!input) return { ok: false, count: 0, error: 'No image file input found on page' };
-
-      const dt = new DataTransfer();
-      for (const img of images) {
-        try {
-          const binary = atob(img.base64);
-          const bytes = new Uint8Array(binary.length);
-          for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
-          const blob = new Blob([bytes], { type: img.mimeType });
-          dt.items.add(new File([blob], img.name, { type: img.mimeType }));
-        } catch (e) {
-          return { ok: false, count: 0, error: 'Failed to create File: ' + e.message };
-        }
-      }
-
-      Object.defineProperty(input, 'files', { value: dt.files, writable: false });
-      input.dispatchEvent(new Event('change', { bubbles: true }));
-      input.dispatchEvent(new Event('input', { bubbles: true }));
-
-      return { ok: true, count: dt.files.length };
-    })()
-  `);
-}
-/**
- * Wait until all upload progress indicators have disappeared (up to maxWaitMs).
- */
-async function waitForUploads(page, maxWaitMs = 30_000) {
-    const pollMs = 2_000;
-    const maxAttempts = Math.ceil(maxWaitMs / pollMs);
-    for (let i = 0; i < maxAttempts; i++) {
-        const uploading = await page.evaluate(`
-      () => !!document.querySelector(
-        '[class*="upload"][class*="progress"], [class*="uploading"], [class*="loading"][class*="image"]'
-      )
-    `);
-        if (!uploading)
-            return;
-        await page.wait({ time: pollMs / 1_000 });
-    }
-}
-/**
- * Fill a visible text input or contenteditable with the given text.
- * Tries multiple selectors in priority order.
- * Returns { ok, sel }.
- */
-async function fillField(page, selectors, text, fieldName) {
-    const located = await page.evaluate(`
-    (function(selectors) {
-      const __webcmd_xhs_fill_phase = "locate";
-      for (const sel of selectors) {
-        const candidates = document.querySelectorAll(sel);
-        for (const el of candidates) {
-          if (!el || el.offsetParent === null) continue;
-          const kind = el.isContentEditable
-            ? 'contenteditable'
-            : (el.tagName === 'TEXTAREA' ? 'textarea' : 'input');
-          return { ok: true, sel, kind };
-        }
-      }
-      return { ok: false };
-    })(${JSON.stringify(selectors)})
-  `);
-    if (!located.ok) {
-        await page.screenshot({ path: `/tmp/xhs_publish_${fieldName}_debug.png` });
-        throw new Error(`Could not find ${fieldName} input. Debug screenshot: /tmp/xhs_publish_${fieldName}_debug.png`);
-    }
-    const applyInPage = () => page.evaluate(`
-      ((selector, expectedText) => {
-        const __webcmd_xhs_fill_phase = "apply";
-        const normalize = (value) => (value || '').replace(/\\s+/g, ' ').trim();
-        const fireBeforeInput = (el, value) => {
-          try {
-            el.dispatchEvent(new InputEvent('beforeinput', {
-              bubbles: true,
-              data: value,
-              inputType: 'insertText',
-            }));
-          } catch {
-            el.dispatchEvent(new Event('beforeinput', { bubbles: true }));
-          }
-        };
-        const fireInput = (el, value) => {
-          try {
-            el.dispatchEvent(new InputEvent('input', {
-              bubbles: true,
-              data: value,
-              inputType: 'insertText',
-            }));
-          } catch {
-            el.dispatchEvent(new Event('input', { bubbles: true }));
-          }
-        };
-        const el = Array.from(document.querySelectorAll(selector)).find(node => node && node.offsetParent !== null);
-        if (!el) return { ok: false, actual: '' };
-        el.focus();
-        fireBeforeInput(el, expectedText);
-        if (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA') {
-          const proto = el.tagName === 'TEXTAREA'
-            ? HTMLTextAreaElement.prototype
-            : HTMLInputElement.prototype;
-          const nativeSetter = Object.getOwnPropertyDescriptor(proto, 'value')?.set;
-          if (nativeSetter) nativeSetter.call(el, expectedText);
-          else el.value = expectedText;
-          fireInput(el, expectedText);
-          el.dispatchEvent(new Event('change', { bubbles: true }));
-          el.blur();
-          return { ok: el.value === expectedText, actual: el.value || '' };
-        }
-        el.textContent = '';
-        const selection = window.getSelection();
-        const range = document.createRange();
-        range.selectNodeContents(el);
-        range.collapse(false);
-        selection?.removeAllRanges();
-        selection?.addRange(range);
-        const inserted = document.execCommand('insertText', false, expectedText);
-        if (!inserted) el.textContent = expectedText;
-        fireInput(el, expectedText);
-        el.dispatchEvent(new Event('change', { bubbles: true }));
-        el.blur();
-        const actual = normalize(el.innerText || el.textContent || '');
-        return { ok: actual === normalize(expectedText), actual };
-      })(${JSON.stringify(located.sel)}, ${JSON.stringify(text)})
-    `);
-    let result;
-    if (located.kind === 'contenteditable' && page.insertText) {
-        const prepared = await page.evaluate(`
-      ((selector, nextText) => {
-        const __webcmd_xhs_fill_phase = "prepare";
-        const fireBeforeInput = (el, value) => {
-          try {
-            el.dispatchEvent(new InputEvent('beforeinput', {
-              bubbles: true,
-              data: value,
-              inputType: 'insertText',
-            }));
-          } catch {
-            el.dispatchEvent(new Event('beforeinput', { bubbles: true }));
-          }
-        };
-        const el = Array.from(document.querySelectorAll(selector)).find(node => node && node.offsetParent !== null);
-        if (!el) return { ok: false };
-        el.focus();
-        el.textContent = '';
-        const selection = window.getSelection();
-        const range = document.createRange();
-        range.selectNodeContents(el);
-        range.collapse(false);
-        selection?.removeAllRanges();
-        selection?.addRange(range);
-        fireBeforeInput(el, nextText);
-        return { ok: true };
-      })(${JSON.stringify(located.sel)}, ${JSON.stringify(text)})
-    `);
-        if (!prepared?.ok) {
-            await page.screenshot({ path: `/tmp/xhs_publish_${fieldName}_debug.png` });
-            throw new Error(`Could not prepare ${fieldName} input. Debug screenshot: /tmp/xhs_publish_${fieldName}_debug.png`);
-        }
-        try {
-            await page.insertText(text);
-            result = await page.evaluate(`
-      ((selector, expectedText) => {
-        const __webcmd_xhs_fill_phase = "verify";
-        const normalize = (value) => (value || '').replace(/\\s+/g, ' ').trim();
-        const fireInput = (el, value) => {
-          try {
-            el.dispatchEvent(new InputEvent('input', {
-              bubbles: true,
-              data: value,
-              inputType: 'insertText',
-            }));
-          } catch {
-            el.dispatchEvent(new Event('input', { bubbles: true }));
-          }
-        };
-        const el = Array.from(document.querySelectorAll(selector)).find(node => node && node.offsetParent !== null);
-        if (!el) return { ok: false, actual: '' };
-        fireInput(el, expectedText);
-        el.dispatchEvent(new Event('change', { bubbles: true }));
-        el.blur();
-        const actual = normalize(el.innerText || el.textContent || '');
-        return { ok: actual === normalize(expectedText), actual };
-      })(${JSON.stringify(located.sel)}, ${JSON.stringify(text)})
-    `);
-        }
-        catch {
-            result = await applyInPage();
-        }
-    }
-    else {
-        result = await applyInPage();
-    }
-    if (!result?.ok) {
-        await page.screenshot({ path: `/tmp/xhs_publish_${fieldName}_debug.png` });
-        const actual = typeof result?.actual === 'string' ? result.actual : '';
-        throw new Error(`Failed to set ${fieldName}. Expected "${text}", got "${actual}". Debug screenshot: /tmp/xhs_publish_${fieldName}_debug.png`);
-    }
-}
-/**
- * Add topic hashtags by driving the editor's native inline "#" flow.
- *
- * Modern XHS creator-center editors turn a "#keyword" typed into the note body
- * into a linked topic entity only after the author picks an item from the
- * suggestion dropdown that appears while typing. There is no standalone
- * "添加话题" search input anymore, so we type directly into the body editor.
- *
- * For each topic we:
- *   1. focus the body contenteditable and move the caret to the end,
- *   2. type " #<topic>" using native CDP insertion (falls back to execCommand)
- *      so XHS fires its inline suggestion dropdown,
- *   3. wait for the dropdown, then click the suggestion whose text best matches
- *      the topic (falling back to the first suggestion, then to Enter),
- *   4. confirm a topic chip/link was produced before moving on.
- *
- * A requested topic is a write-side postcondition: if XHS does not create a
- * real topic entity, fail before publishing instead of silently emitting a note
- * with bare "#text".
- */
-async function focusBodyEnd(page, bodySelectors) {
-    return unwrapBrowserResult(await page.evaluate(`
-    (selectors => {
-      const el = selectors
-        .map(sel => Array.from(document.querySelectorAll(sel)))
-        .flat()
-        .find(node => node && node.offsetParent !== null && node.isContentEditable);
-      if (!el) return false;
-      el.focus();
-      const selection = window.getSelection();
-      const range = document.createRange();
-      range.selectNodeContents(el);
-      range.collapse(false);
-      selection?.removeAllRanges();
-      selection?.addRange(range);
-      return true;
-    })(${JSON.stringify(bodySelectors)})
-  `));
-}
-function topicSuggestionScript(topic, { click = false } = {}) {
-    // Returns the best matching suggestion's screen coordinates (center) so the
-    // caller can issue a real click.
-    return `
-    (topicName => {
-      const norm = (value) => (value || '').replace(/^#/, '').replace(/\\s+/g, '').trim();
-      const want = norm(topicName);
-      const SUGGESTION_SELECTORS = [
-        '[class*="topic-item"]',
-        '[class*="hashtag-item"]',
-        '[class*="suggest-item"]',
-        '[class*="suggestion"] li',
-        '[class*="mention"] li',
-        '[class*="dropdown"] li',
-        '[id*="topic"] li',
-        '[class*="topic"] li',
-      ];
-      const seen = new Set();
-      const items = [];
-      for (const sel of SUGGESTION_SELECTORS) {
-        for (const node of document.querySelectorAll(sel)) {
-          if (!node || seen.has(node)) continue;
-          if (node.offsetParent === null) continue;
-          const rect = node.getBoundingClientRect();
-          if (rect.width <= 0 || rect.height <= 0) continue;
-          seen.add(node);
-          items.push(node);
-        }
-      }
-      if (!items.length) return { ok: false, count: 0 };
-      let target = items.find(node => norm(node.innerText || node.textContent) === want);
-      if (!target) target = items.find(node => norm(node.innerText || node.textContent).includes(want));
-      if (!target) target = items[0];
-      const rect = target.getBoundingClientRect();
-      ${click ? "try { target.click(); } catch (e) { return { ok: false, count: items.length, message: String(e) }; }" : ''}
-      return {
-        ok: true,
-        count: items.length,
-        x: Math.round(rect.left + rect.width / 2),
-        y: Math.round(rect.top + rect.height / 2),
-        text: (target.innerText || target.textContent || '').trim().slice(0, 40),
-      };
-    })(${JSON.stringify(topic)})
-  `;
-}
-function topicEntityCountScript(topic, bodySelectors) {
-    return `
-    ((topicName, selectors) => {
-      const norm = (value) => (value || '').replace(/^#/, '').replace(/\\s+/g, '').trim();
-      const want = norm(topicName);
-      const editor = selectors
-        .map(sel => Array.from(document.querySelectorAll(sel)))
-        .flat()
-        .find(node => node && node.offsetParent !== null && node.isContentEditable);
-      if (!editor || !want) return 0;
-      const hasTopicSignal = (node) => {
-        const tag = (node.tagName || '').toLowerCase();
-        const role = (node.getAttribute && node.getAttribute('role')) || '';
-        const cls = String(node.className || '');
-        const id = String(node.id || '');
-        const href = (node.getAttribute && node.getAttribute('href')) || '';
-        const dataKeys = node.dataset ? Object.keys(node.dataset).join(' ') : '';
-        const haystack = [tag, role, cls, id, href, dataKeys].join(' ');
-        return tag === 'a'
-          || /link/i.test(role)
-          || /topic|hashtag|hash-tag|tag|mention|keyword/i.test(haystack)
-          || node.isContentEditable === false;
-      };
-      let count = 0;
-      for (const node of Array.from(editor.querySelectorAll('*'))) {
-        if (!node || node.offsetParent === null) continue;
-        if (!hasTopicSignal(node)) continue;
-        const text = norm(node.innerText || node.textContent || '');
-        if (text === want || text === '#' + want) count += 1;
-      }
-      return count;
-    })(${JSON.stringify(topic)}, ${JSON.stringify(bodySelectors)})
-  `;
-}
-function topicMarkerCountScript(topic, bodySelectors) {
-    return `
-    ((topicName, selectors) => {
-      const __webcmd_xhs_topic_marker_count = true;
-      const marker = '#' + topicName + '[话题]';
-      const editor = selectors
-        .map(sel => Array.from(document.querySelectorAll(sel)))
-        .flat()
-        .find(node => node && node.offsetParent !== null && node.isContentEditable);
-      if (!editor || !marker) return 0;
-      const text = editor.innerText || editor.textContent || '';
-      let count = 0;
-      let index = text.indexOf(marker);
-      while (index !== -1) {
-        count += 1;
-        index = text.indexOf(marker, index + marker.length);
-      }
-      return count;
-    })(${JSON.stringify(topic)}, ${JSON.stringify(bodySelectors)})
-  `;
-}
-async function typeTopicQuery(page, topic) {
-    // Type "#<topic>" so XHS recognizes it as a topic query and pops the inline
-    // suggestion dropdown. The caller separates topics with Enter beforehand so
-    // each query starts on its own line and matches cleanly.
-    const query = `#${topic}`;
-    if (typeof page.insertText === 'function') {
-        try {
-            await page.insertText(query);
-            return true;
-        }
-        catch {
-            // fall through to execCommand path
-        }
-    }
-    return unwrapBrowserResult(await page.evaluate(`
-    (text => {
-      const ok = document.execCommand('insertText', false, text);
-      const active = document.activeElement;
-      if (active) active.dispatchEvent(new Event('input', { bubbles: true }));
-      return ok;
-    })(${JSON.stringify(query)})
-  `));
-}
-async function addTopics(page, bodySelectors, topics) {
-    const added = [];
-    for (const topic of topics) {
-        const focused = await focusBodyEnd(page, bodySelectors);
-        if (!focused) {
-            throw new CommandExecutionError(`Could not attach topic "${topic}": body editor not found`);
-        }
-        const beforeMarkerCount = Number(unwrapBrowserResult(await page.evaluate(topicMarkerCountScript(topic, bodySelectors)))) || 0;
-        // Separate this topic from the preceding text so the dropdown is clean.
-        if (typeof page.pressKey === 'function') {
-            try {
-                await page.pressKey('Enter');
-            }
-            catch { /* non-fatal */ }
-        }
-        // Type the inline "#<topic>" query so XHS pops the inline suggestion
-        // dropdown. We must use `page.insertText` (CDP) rather than the legacy
-        // `execCommand` path, otherwise XHS's editor doesn't fire its keyup
-        // listener and no dropdown appears.
-        if (typeof page.insertText !== 'function') {
-            throw new CommandExecutionError(`Could not attach topic "${topic}": page.insertText is unavailable`);
-        }
-        try {
-            await page.insertText(`#${topic}`);
-        }
-        catch {
-            throw new CommandExecutionError(`Could not attach topic "${topic}": failed to type inline topic query`);
-        }
-        await page.wait({ time: 1.2 }); // Let the suggestion dropdown render.
-        // The suggestion dropdown lives inside the editor's closed shadow root,
-        // so light-DOM queries cannot enumerate its items. XHS auto-highlights
-        // the first matching suggestion as soon as the query is typed, so
-        // pressing Enter accepts it directly. `page.nativeClick` would also
-        // work but is not always wired up in the browser-bridge wrapper.
-        if (typeof page.pressKey !== 'function') {
-            throw new CommandExecutionError(`Could not attach topic "${topic}": page.pressKey is unavailable`);
-        }
-        try {
-            await page.pressKey('Enter');
-        }
-        catch (err) {
-            throw new CommandExecutionError(`Could not attach topic "${topic}": failed to accept suggestion (${err && err.message || err})`);
-        }
-        await page.wait({ time: 0.8 });
-        // Verify the topic chip actually rendered. The chip itself lives in a
-        // closed shadow root so we cannot count `<a>` elements, but XHS exposes
-        // a stable "#<topic>[话题]" marker in the body editor's innerText once
-        // the suggestion is accepted. Require the scoped marker count to
-        // increase so an existing marker elsewhere cannot satisfy the write
-        // postcondition.
-        const afterMarkerCount = Number(unwrapBrowserResult(await page.evaluate(topicMarkerCountScript(topic, bodySelectors)))) || 0;
-        if (afterMarkerCount <= beforeMarkerCount) {
-            throw new CommandExecutionError(`Could not attach topic "${topic}": no real topic entity appeared after selection`);
-        }
-        added.push(topic);
-        await page.wait({ time: 0.4 });
-    }
-    return added;
-}
-async function selectImageTextTab(page) {
-    const result = await page.evaluate(`
-    () => {
-      const isVisible = (el) => {
-        if (!el || el.offsetParent === null) return false;
-        const rect = el.getBoundingClientRect();
-        return rect.width > 0 && rect.height > 0;
-      };
-
-      const normalize = (value) => (value || '').replace(/\\s+/g, ' ').trim();
-      const selector = 'button, [role="tab"], [role="button"], a, label, div, span, li';
-      const nodes = Array.from(document.querySelectorAll(selector));
-      const targets = ['上传图文', '图文', '图片'];
-
-      for (const target of targets) {
-        for (const node of nodes) {
-          if (!isVisible(node)) continue;
-          const text = normalize(node.innerText || node.textContent || '');
-          if (!text || text.includes('视频')) continue;
-          if (text === target) {
-            const clickable = node.closest('button, [role="tab"], [role="button"], a, label') || node;
-            clickable.click();
-            return { ok: true, target, text };
-          }
-        }
-      }
-
-      for (const target of targets) {
-        for (const node of nodes) {
-          if (!isVisible(node)) continue;
-          const text = normalize(node.innerText || node.textContent || '');
-          if (!text || text.includes('视频')) continue;
-          if (text.startsWith(target) || text.includes(target)) {
-            const clickable = node.closest('button, [role="tab"], [role="button"], a, label') || node;
-            clickable.click();
-            return { ok: true, target, text };
-          }
-        }
-      }
-
-      const visibleTexts = [];
-      for (const node of nodes) {
-        if (!isVisible(node)) continue;
-        const text = normalize(node.innerText || node.textContent || '');
-        if (!text || text.length > 20) continue;
-        visibleTexts.push(text);
-        if (visibleTexts.length >= 20) break;
-      }
-      return { ok: false, visibleTexts };
-    }
-  `);
-    if (result?.ok) {
-        await page.wait({ time: 1 });
-    }
-    return result;
-}
-/**
- * Click the first visible element whose trimmed text equals `label`.
- * Marker constant `__webcmd_xhs_click_label` lets the test mock branch on it.
- */
-async function clickByText(page, label, maxWaitMs = 7_000) {
-    const pollMs = 500;
-    const maxAttempts = Math.max(1, Math.ceil(maxWaitMs / pollMs));
-    let result = { ok: false };
-    // Retry until the control appears: 生成图片 → 下一步 advances through async
-    // render/generation steps, so the target may not exist on the first probe.
-    for (let attempt = 0; attempt < maxAttempts; attempt++) {
-        result = unwrapBrowserResult(await page.evaluate(`
-    ((cfg) => {
-      const __webcmd_xhs_click_label = { wantLabel: ${JSON.stringify(label)} };
-      const wantLabel = ${JSON.stringify(label)};
-      const isVisible = (el) => {
-        if (!el || el.offsetParent === null) return false;
-        const r = el.getBoundingClientRect();
-        return r.width > 0 && r.height > 0;
-      };
-      const norm = (v) => (v || '').replace(/\\s+/g, ' ').trim();
-      const clickable = (el) => el.closest('button, [role="button"], a, label') || el;
-      const enabled = (el) =>
-        !(el.getAttribute && el.getAttribute('aria-disabled') === 'true')
-        && !el.disabled
-        && !(el.className && String(el.className).split(/\\s+/).includes('disabled'));
-      // Exact-text matches, innermost first. The real click handler usually lives on
-      // an inner control (.edit-text-button 生成图片, .add-text-item-button-text 再写一张);
-      // an outer wrapper that merely *contains* the label is a no-op, so prefer the
-      // deepest matching node and let the event bubble up to the handler.
-      const nodes = Array.from(document.querySelectorAll('button, [role="button"], div, span, a, label, li'));
-      const exact = nodes.filter((n) => isVisible(n) && norm(n.innerText || n.textContent) === wantLabel);
-      const innermost = exact.filter((n) => !exact.some((o) => o !== n && n.contains(o)));
-      const contains = nodes.filter((n) => {
-        if (!isVisible(n)) return false;
-        const t = norm(n.innerText || n.textContent);
-        return t && t.length <= wantLabel.length + 4 && t.includes(wantLabel);
-      });
-      for (const node of [...(innermost.length ? innermost : exact), ...contains]) {
-        const c = clickable(node);
-        if (!enabled(c)) continue;
-        c.click();
-        return { ok: true, text: norm(node.innerText || node.textContent) || wantLabel };
-      }
-      return { ok: false };
-    })()
-  `));
-        if (result?.ok)
-            return result;
-        await page.wait({ time: pollMs / 1_000 });
-    }
-    return result;
-}
-/**
- * Focus the currently-active 写文字 card editor (tiptap/ProseMirror) and move the
- * caret to the end so insertText appends into it.
- */
-async function focusActiveCard(page) {
-    const result = await page.evaluate(`
-    (() => {
-      const __webcmd_xhs_focus_card = true;
-      const sel = ${JSON.stringify(CARD_EDITOR_SELECTOR)};
-      const editors = Array.from(document.querySelectorAll(sel)).filter((el) => el.offsetParent !== null);
-      // Prefer the editor inside the active swiper slide if present.
-      const active = editors.find((el) => el.closest('.swiper-slide-active')) || editors[editors.length - 1];
-      if (!active) return { ok: false };
-      active.focus();
-      const selection = window.getSelection();
-      const range = document.createRange();
-      range.selectNodeContents(active);
-      range.collapse(false);
-      selection?.removeAllRanges();
-      selection?.addRange(range);
-      return { ok: true };
-    })()
-  `);
-    return unwrapBrowserResult(result);
-}
-/** Confirm the active card editor holds non-empty text (guards against empty cards). */
-async function activeCardText(page) {
-    const result = await page.evaluate(`
-    (() => {
-      const __webcmd_xhs_card_text = true;
-      const sel = ${JSON.stringify(CARD_EDITOR_SELECTOR)};
-      const editors = Array.from(document.querySelectorAll(sel)).filter((el) => el.offsetParent !== null);
-      const active = editors.find((el) => el.closest('.swiper-slide-active')) || editors[editors.length - 1];
-      const text = active ? (active.innerText || active.textContent || '').trim() : '';
-      return { ok: !!text, text };
-    })()
-  `);
-    return unwrapBrowserResult(result);
-}
-/**
- * Count visible card editors and report whether the active one is still empty.
- * Used to wait out the swiper render lag after clicking 再写一张.
- */
-async function cardEditorState(page) {
-    const result = await page.evaluate(`
-    (() => {
-      const __webcmd_xhs_card_count = true;
-      const sel = ${JSON.stringify(CARD_EDITOR_SELECTOR)};
-      const editors = Array.from(document.querySelectorAll(sel)).filter((el) => el.offsetParent !== null);
-      const active = editors.find((el) => el.closest('.swiper-slide-active')) || editors[editors.length - 1];
-      const activeText = active ? (active.innerText || active.textContent || '').trim() : '';
-      return { ok: true, count: editors.length, activeEmpty: !activeText };
-    })()
-  `);
-    return unwrapBrowserResult(result);
-}
-/** Poll until at least one card editor has rendered (after entering 文字配图). */
-async function waitForFirstCard(page, maxWaitMs = 8_000) {
-    const pollMs = 300;
-    const maxAttempts = Math.ceil(maxWaitMs / pollMs);
-    for (let i = 0; i < maxAttempts; i++) {
-        const state = await cardEditorState(page);
-        if (state?.count >= 1)
-            return true;
-        await page.wait({ time: pollMs / 1_000 });
-    }
-    return false;
-}
-/**
- * After clicking 再写一张, the new card editor renders asynchronously and only
- * then becomes the active swiper slide. Wait for the fresh empty card to be
- * active before typing — otherwise the text lands in the previous card and the
- * cards get merged.
- */
-async function waitForNewCard(page, expectedCount, maxWaitMs = 6_000) {
-    const pollMs = 300;
-    const maxAttempts = Math.ceil(maxWaitMs / pollMs);
-    for (let i = 0; i < maxAttempts; i++) {
-        const state = await cardEditorState(page);
-        if (state?.count >= expectedCount && state?.activeEmpty)
-            return true;
-        await page.wait({ time: pollMs / 1_000 });
-    }
-    return false;
-}
-/**
- * Click 再写一张 and wait for the new card to render. Retries the click because
- * 再写一张 only adds a card once the current card's text has registered in the
- * editor model — a click fired too early no-ops. Re-clicking is safe: once the
- * fresh empty card is active, 再写一张 no-ops, so this never over-adds.
- */
-async function addCard(page, expectedCount, maxAttempts = 4) {
-    for (let attempt = 0; attempt < maxAttempts; attempt++) {
-        const clicked = await clickByText(page, ADD_CARD_LABEL);
-        if (!clicked?.ok)
-            return false;
-        if (await waitForNewCard(page, expectedCount, 2_500))
-            return true;
-    }
-    return false;
-}
-/** True once the 预览图片 step has rendered (its 下一步 button is present). */
-async function previewStepReady(page) {
-    const result = await page.evaluate(`
-    (() => {
-      const __webcmd_xhs_preview_ready = true;
-      const ready = Array.from(document.querySelectorAll('button'))
-        .some((b) => b.offsetParent !== null && (b.innerText || '').replace(/\\s+/g, '') === '下一步');
-      return { ok: ready };
-    })()
-  `);
-    return unwrapBrowserResult(result);
-}
-/**
- * Click 生成图片 and wait for the 预览图片 step. Retries the click because 生成图片
- * no-ops until the card text has registered in the editor model (same timing quirk as
- * 再写一张). Re-clicking is safe: once the preview step is showing, 生成图片 is gone.
- */
-async function clickGenerate(page, maxAttempts = 6) {
-    const pollMs = 400;
-    const polls = Math.ceil(3_000 / pollMs);
-    for (let attempt = 0; attempt < maxAttempts; attempt++) {
-        const clicked = await clickByText(page, GENERATE_LABEL);
-        if (!clicked?.ok && attempt === 0)
-            return false; // 生成图片 not on the page at all
-        for (let i = 0; i < polls; i++) {
-            if ((await previewStepReady(page))?.ok)
-                return true;
-            await page.wait({ time: pollMs / 1_000 });
-        }
-    }
-    return false;
-}
-/**
- * Type one card's text into the active card editor, then verify it stuck.
- *
- * tiptap/ProseMirror swallows a "\n" embedded in a single insertText call, so a
- * multi-line card would collapse onto one line. Split the text on "\n" and press
- * Enter between segments to produce real line breaks (same Enter mechanism
- * addTopics relies on). An empty segment (consecutive "\n") yields a blank line.
- *
- * Single-quoted shell args (the most natural way to pass `--card-text`) deliver a
- * literal backslash + "n", not a real LF, so we normalize those to real newlines
- * first — both `$'a\nb'` and `'a\nb'` then break lines identically.
- */
-async function fillCard(page, text, index) {
-    text = String(text).replace(/\\n/g, '\n');
-    const focused = await focusActiveCard(page);
-    if (!focused?.ok)
-        throw new CommandExecutionError(`文字配图: could not focus card editor #${index + 1}`);
-    if (typeof page.insertText === 'function') {
-        const lines = text.split('\n');
-        for (let i = 0; i < lines.length; i++) {
-            if (i > 0 && typeof page.pressKey === 'function')
-                await page.pressKey('Enter');
-            if (lines[i])
-                await page.insertText(lines[i]);
-        }
-    }
-    else {
-        await page.evaluate(`(t => document.execCommand('insertText', false, t))(${JSON.stringify(text)})`);
-    }
-    await page.wait({ time: 0.4 });
-    const state = await activeCardText(page);
-    if (!state?.ok)
-        throw new CommandExecutionError(`文字配图: card editor #${index + 1} is empty after typing`);
-}
-/**
- * On the 预览图片 step, optionally pick a style. The style picker is a
- * scrollable strip whose options are loaded lazily, so we scroll it to the end
- * to surface every option, then read the real on-page labels (no hard-coded
- * whitelist — XHS adds/removes styles over time). The strip is located by
- * anchoring on a known seed label (e.g. 基础) rather than a volatile class name.
- *
- * If the caller requested a style, it is a write-side postcondition: either
- * that style is available and clicked, or publishing fails before submit.
- */
-async function selectCardStyle(page, styleName) {
-    if (!styleName || styleName === DEFAULT_CARD_STYLE)
-        return DEFAULT_CARD_STYLE; // default 基础 is preselected — nothing to do.
-    // The style strip (".cover-list-container") is VIRTUALIZED: only the items
-    // near the viewport are in the DOM, so a single read sees ~10 of ~20 options
-    // and an option scrolled out of view cannot be clicked. Step-scroll the strip
-    // (".cover-list-container-wrapper"), accumulating every label seen; stop as
-    // soon as the requested style appears and scroll it into view so the
-    // subsequent click lands. XHS also shows a content-dependent subset, so the
-    // real options vary per note — hence no static whitelist.
-    const available = unwrapBrowserResult(await page.evaluate(`
-    (async () => {
-      const __webcmd_xhs_card_styles = true;
-      const want = ${JSON.stringify(styleName)};
-      const norm = (el) => ((el && (el.innerText || el.textContent)) || '').trim();
-      const names = () => Array.from(document.querySelectorAll('.cover-list-container .cover-name'));
-      const seen = [];
-      const readAll = () => { for (const el of names()) { const t = norm(el); if (t && !seen.includes(t)) seen.push(t); } };
-      const target = () => names().find((el) => norm(el) === want);
-      const reveal = (el) => { el.scrollIntoView({ block: 'center' }); };
-      readAll();
-      let hit = target();
-      if (hit) { reveal(hit); return { ok: true, styles: seen, found: true }; }
-      const scroller = document.querySelector('.cover-list-container-wrapper')
-        || document.querySelector('.cover-list-container');
-      if (scroller) {
-        const ch = scroller.clientHeight || 200;
-        const sh = scroller.scrollHeight;
-        for (let y = 0; y <= sh + ch; y += Math.max(60, Math.floor(ch / 2))) {
-          scroller.scrollTop = y;
-          await new Promise((r) => setTimeout(r, 180));
-          readAll();
-          hit = target();
-          if (hit) { reveal(hit); await new Promise((r) => setTimeout(r, 150)); return { ok: true, styles: seen, found: true }; }
-        }
-        scroller.scrollTop = 0;
-      }
-      return { ok: seen.length > 0, styles: seen, found: false };
-    })()
-  `));
-    if (!available?.found) {
-        throw new CommandExecutionError(`文字配图: requested style "${styleName}" is not available for this content `
-            + `(options: ${(available?.styles || []).join(' / ') || 'none'}). `
-            + `Choose an available style or omit --card-style to use ${DEFAULT_CARD_STYLE}.`);
-    }
-    const clicked = await clickByText(page, styleName);
-    if (!clicked?.ok) {
-        throw new CommandExecutionError(`文字配图: could not click requested style "${styleName}".`);
-    }
-    await page.wait({ time: 0.6 });
-    return styleName;
-}
-/**
- * Count visible media in the current editor/composer. Text-image generation must
- * produce real image cards before we fill title/body or submit; otherwise a
- * no-op 生成图片 / 下一步 sequence can publish the wrong draft surface.
- */
-async function currentComposerMediaCount(page) {
-    const result = await page.evaluate(`
-    (() => {
-      const __webcmd_xhs_composer_media_count = true;
-      const visibleBox = (el) => {
-        if (!el || el.offsetParent === null) return false;
-        const r = el.getBoundingClientRect();
-        return r.width > 0 && r.height > 0;
-      };
-      const visibleMedia = (el) => {
-        if (!visibleBox(el)) return false;
-        const r = el.getBoundingClientRect();
-        return r.width >= 48 && r.height >= 48;
-      };
-      const titleSelectors = ${JSON.stringify(TITLE_SELECTORS)};
-      const titleEl = titleSelectors
-        .map((sel) => Array.from(document.querySelectorAll(sel)))
-        .flat()
-        .find((el) => visibleBox(el));
-      const root = titleEl?.closest('form, [class*="publish"], [class*="editor"], [class*="note"]') || document.body;
-      const seen = new Set();
-      let count = 0;
-      for (const el of Array.from(root.querySelectorAll('img, video, canvas, [style*="background-image"]'))) {
-        if (!visibleMedia(el)) continue;
-        const rect = el.getBoundingClientRect();
-        const src = el.currentSrc || el.src || el.getAttribute('src') || el.style?.backgroundImage || '';
-        const key = src || String(Math.round(rect.left)) + ':' + String(Math.round(rect.top));
-        if (seen.has(key)) continue;
-        seen.add(key);
-        count += 1;
-      }
-      return { ok: true, count };
-    })()
-  `);
-    return unwrapBrowserResult(result);
-}
-async function assertComposerMediaCount(page, expectedCount, label) {
-    const state = await currentComposerMediaCount(page);
-    if (!state || typeof state.count !== 'number') {
-        throw new CommandExecutionError(`${label}: could not verify current composer media count`);
-    }
-    if (state.count < expectedCount) {
-        await page.screenshot({ path: '/tmp/xhs_publish_media_debug.png' });
-        throw new CommandExecutionError(`${label}: expected at least ${expectedCount} visible media item(s), got ${state.count}. ` +
-            'Debug screenshot: /tmp/xhs_publish_media_debug.png');
-    }
-}
-/**
- * Drive the full 文字配图 sub-flow: entry → type cards → 生成图片 → pick style → 下一步.
- * Leaves the page on the standard editor (caller then runs waitForEditForm).
- */
-async function runTextImageFlow(page, cards, cardStyle) {
-    const entry = await clickByText(page, TEXT_IMAGE_ENTRY_LABEL);
-    if (!entry?.ok) {
-        await page.screenshot({ path: '/tmp/xhs_publish_textimage_debug.png' });
-        throw new CommandExecutionError(`文字配图: could not click "${TEXT_IMAGE_ENTRY_LABEL}" entry. ` +
-            'Debug: /tmp/xhs_publish_textimage_debug.png');
-    }
-    if (!(await waitForFirstCard(page))) {
-        await page.screenshot({ path: '/tmp/xhs_publish_textimage_debug.png' });
-        throw new CommandExecutionError(`文字配图: 写文字 card editor did not appear after clicking "${TEXT_IMAGE_ENTRY_LABEL}". ` +
-            'Debug: /tmp/xhs_publish_textimage_debug.png');
-    }
-    for (let i = 0; i < cards.length; i++) {
-        if (i > 0) {
-            const added = await addCard(page, i + 1);
-            if (!added) {
-                await page.screenshot({ path: '/tmp/xhs_publish_addcard_debug.png' });
-                throw new CommandExecutionError(`文字配图: new card editor #${i + 1} did not render after "${ADD_CARD_LABEL}". ` +
-                    'Debug: /tmp/xhs_publish_addcard_debug.png');
-            }
-        }
-        await fillCard(page, cards[i], i);
-    }
-    const generated = await clickGenerate(page);
-    if (!generated) {
-        await page.screenshot({ path: '/tmp/xhs_publish_generate_debug.png' });
-        throw new CommandExecutionError(`文字配图: "${GENERATE_LABEL}" did not advance to the 预览图片 step. ` +
-            'Debug: /tmp/xhs_publish_generate_debug.png');
-    }
-    const appliedStyle = await selectCardStyle(page, cardStyle);
-    const next = await clickByText(page, PREVIEW_NEXT_LABEL);
-    if (!next?.ok) {
-        await page.screenshot({ path: '/tmp/xhs_publish_next_debug.png' });
-        throw new CommandExecutionError(`文字配图: could not click "${PREVIEW_NEXT_LABEL}". ` +
-            'Debug: /tmp/xhs_publish_next_debug.png');
-    }
-    await page.wait({ time: 2 }); // editor render
-    return appliedStyle;
-}
-async function inspectPublishSurfaceState(page) {
-    return page.evaluate(`
-    () => {
-      const text = (document.body?.innerText || '').replace(/\s+/g, ' ').trim();
-      const hasTitleInput = !!Array.from(document.querySelectorAll('input, textarea')).find((el) => {
-        if (!el || el.offsetParent === null) return false;
-        const placeholder = (el.getAttribute('placeholder') || '').trim();
-        const cls = el.className ? String(el.className) : '';
-        const maxLength = Number(el.getAttribute('maxlength') || 0);
-        return (
-          placeholder.includes('标题') ||
-          /title/i.test(placeholder) ||
-          /title/i.test(cls) ||
-          maxLength === 20
-        );
-      });
-      const hasImageInput = !!Array.from(document.querySelectorAll('input[type="file"]')).find((el) => {
-        const accept = el.getAttribute('accept') || '';
-        return (
-          accept.includes('image') ||
-          accept.includes('.jpg') ||
-          accept.includes('.jpeg') ||
-          accept.includes('.png') ||
-          accept.includes('.gif') ||
-          accept.includes('.webp')
-        );
-      });
-      const hasVideoSurface = text.includes('拖拽视频到此处点击上传') || text.includes('上传视频');
-      const state = hasTitleInput ? 'editor_ready' : hasImageInput || !hasVideoSurface ? 'image_surface' : 'video_surface';
-      return { state, hasTitleInput, hasImageInput, hasVideoSurface };
-    }
-  `);
-}
-async function waitForPublishSurfaceState(page, maxWaitMs = 5_000) {
-    const pollMs = 500;
-    const maxAttempts = Math.max(1, Math.ceil(maxWaitMs / pollMs));
-    let surface = await inspectPublishSurfaceState(page);
-    for (let i = 0; i < maxAttempts; i++) {
-        if (surface.state !== 'video_surface') {
-            return surface;
-        }
-        if (i < maxAttempts - 1) {
-            await page.wait({ time: pollMs / 1_000 });
-            surface = await inspectPublishSurfaceState(page);
-        }
-    }
-    return surface;
-}
-/**
- * Poll until the title/content editing form appears on the page.
- * The new creator center UI only renders the editor after images are uploaded.
- */
-async function waitForEditForm(page, maxWaitMs = 10_000) {
-    const pollMs = 1_000;
-    const maxAttempts = Math.ceil(maxWaitMs / pollMs);
-    for (let i = 0; i < maxAttempts; i++) {
-        const found = await page.evaluate(`
-      (() => {
-        const sels = ${JSON.stringify(TITLE_SELECTORS)};
-        for (const sel of sels) {
-          const el = document.querySelector(sel);
-          if (el && el.offsetParent !== null) return true;
-        }
-        return false;
-      })()`);
-        if (found)
-            return true;
-        if (i < maxAttempts - 1)
-            await page.wait({ time: pollMs / 1_000 });
-    }
-    return false;
-}
-cli({
-    site: 'xiaohongshu',
-    name: 'publish',
-    access: 'write',
-    description: '小红书发布图文笔记 (creator center UI automation)',
-    domain: 'creator.xiaohongshu.com',
-    strategy: Strategy.COOKIE,
-    browser: true,
-    navigateBefore: false,
-    args: [
-        { name: 'content', required: true, positional: true, help: '笔记正文' },
-        { name: 'title', required: true, help: '笔记标题 (最多20字)' },
-        { name: 'images', required: false, help: '图片路径，逗号分隔，最多9张 (jpg/png/gif/webp)' },
-        { name: 'card-text', required: false, help: `文字配图卡片文字，多张卡片用 ${CARD_TEXT_DELIM} 分隔，卡内换行用 \\n` },
-        { name: 'card-style', required: false, help: `文字配图卡片样式，运行时按页面实际选项匹配；找不到会失败。省略时使用${DEFAULT_CARD_STYLE}。可选: ${CARD_STYLE_GUIDE.map(([n, s]) => `${n}(${s})`).join(' ')}` },
-        { name: 'topics', required: false, help: '话题标签，逗号分隔，不含 # 号' },
-        { name: 'draft', type: 'bool', default: false, help: '保存为草稿，不直接发布' },
-    ],
-    columns: ['status', 'detail'],
-    func: async (page, kwargs) => {
-        if (!page)
-            throw new Error('Browser page required');
-        const title = String(kwargs.title ?? '').trim();
-        const content = String(kwargs.content ?? '').trim();
-        const imagePaths = kwargs.images
-            ? String(kwargs.images).split(',').map((s) => s.trim()).filter(Boolean)
-            : [];
-        const topics = kwargs.topics
-            ? String(kwargs.topics).split(',').map((s) => s.trim()).filter(Boolean)
-            : [];
-        const isDraft = Boolean(kwargs.draft);
-        const cardText = kwargs['card-text'] ? String(kwargs['card-text']) : '';
-        const cards = cardText
-            ? cardText.split(CARD_TEXT_DELIM).map((s) => s.trim()).filter(Boolean)
-            : [];
-        const cardStyle = kwargs['card-style'] ? String(kwargs['card-style']).trim() : '';
-        const isTextImage = cards.length > 0;
-        // ── Validate inputs ────────────────────────────────────────────────────────
-        if (!title)
-            throw new ArgumentError('--title is required');
-        if (title.length > MAX_TITLE_LEN)
-            throw new ArgumentError(`Title is ${title.length} chars — must be ≤ ${MAX_TITLE_LEN}`);
-        if (!content)
-            throw new ArgumentError('Positional argument <content> is required');
-        if (!isTextImage && imagePaths.length === 0)
-            throw new ArgumentError('Provide --card-text (text-image mode) or --images (upload mode); neither was given.');
-        if (imagePaths.length > MAX_IMAGES)
-            throw new ArgumentError(`Too many images: ${imagePaths.length} (max ${MAX_IMAGES})`);
-        // The editor-page image input (text-image append) rejects gif.
-        if (isTextImage && imagePaths.some((p) => path.extname(p).toLowerCase() === '.gif'))
-            throw new ArgumentError('文字配图模式追加的图片不支持 .gif（编辑器图片入口只接受 jpg/jpeg/png/webp）');
-        // Validate image paths before navigating (fast-fail on bad paths / unsupported formats)
-        const absImagePaths = validateImagePaths(imagePaths);
-        // ── Step 1: Navigate to publish page ──────────────────────────────────────
-        await page.goto(PUBLISH_URL);
-        await page.wait({ time: 3 });
-        // Verify we landed on the creator site (not redirected to login)
-        const pageUrl = await page.evaluate('() => location.href');
-        if (!pageUrl.includes('creator.xiaohongshu.com')) {
-            throw new Error('Redirected away from creator center — session may have expired. ' +
-                'Re-capture browser login via: webcmd xiaohongshu creator-profile');
-        }
-        // ── Step 2: Select 图文 (image+text) note type if tabs are present ─────────
-        const tabResult = await selectImageTextTab(page);
-        const surface = await waitForPublishSurfaceState(page, tabResult?.ok ? 5_000 : 2_000);
-        if (surface.state === 'video_surface') {
-            await page.screenshot({ path: '/tmp/xhs_publish_tab_debug.png' });
-            const detail = tabResult?.ok
-                ? `clicked "${tabResult.text}"`
-                : `visible candidates: ${(tabResult?.visibleTexts || []).join(' | ') || 'none'}`;
-            throw new Error('Still on the video publish page after trying to select 图文. ' +
-                `Details: ${detail}. Debug screenshot: /tmp/xhs_publish_tab_debug.png`);
-        }
-        // ── Step 3: Acquire images — text-image generation and/or upload ──────────
-        let appliedCardStyle = cardStyle;
-        if (isTextImage) {
-            // Drive 文字配图: type cards → 生成图片 → pick style → 下一步 → standard editor.
-            appliedCardStyle = await runTextImageFlow(page, cards, cardStyle);
-        }
-        else {
-            const upload = await uploadImages(page, absImagePaths);
-            if (!upload.ok) {
-                await page.screenshot({ path: '/tmp/xhs_publish_upload_debug.png' });
-                throw new CommandExecutionError(`Image injection failed: ${upload.error ?? 'unknown'}. ` +
-                    'Debug screenshot: /tmp/xhs_publish_upload_debug.png');
-            }
-            await page.wait({ time: UPLOAD_SETTLE_MS / 1_000 });
-            await waitForUploads(page);
-        }
-        // ── Step 3b: Wait for editor form to render ───────────────────────────────
-        const formReady = await waitForEditForm(page);
-        if (!formReady) {
-            await page.screenshot({ path: '/tmp/xhs_publish_form_debug.png' });
-            throw new CommandExecutionError('Editing form did not appear after image acquisition. The page layout may have changed. ' +
-                'Debug screenshot: /tmp/xhs_publish_form_debug.png');
-        }
-        if (isTextImage) {
-            await assertComposerMediaCount(page, cards.length, '文字配图 generated images');
-        }
-        // ── Step 3c: In text-image mode, optionally append uploaded images ────────
-        if (isTextImage && absImagePaths.length > 0) {
-            const upload = await uploadImages(page, absImagePaths);
-            if (!upload.ok) {
-                await page.screenshot({ path: '/tmp/xhs_publish_append_debug.png' });
-                throw new CommandExecutionError(`Appending images failed: ${upload.error ?? 'unknown'}. ` +
-                    'Debug screenshot: /tmp/xhs_publish_append_debug.png');
-            }
-            await page.wait({ time: UPLOAD_SETTLE_MS / 1_000 });
-            await waitForUploads(page);
-            await assertComposerMediaCount(page, cards.length + absImagePaths.length, '文字配图 appended images');
-        }
-        // ── Step 4: Fill title ─────────────────────────────────────────────────────
-        await fillField(page, TITLE_SELECTORS, title, 'title');
-        await page.wait({ time: 0.5 });
-        // ── Step 5: Fill content / body ────────────────────────────────────────────
-        await fillField(page, BODY_SELECTORS, content, 'content');
-        await page.wait({ time: 0.5 });
-        // ── Step 6: Add topic hashtags ─────────────────────────────────────────────
-        // XHS converts a "#keyword" typed into the body editor into a real topic
-        // entity only when the user picks an item from the inline suggestion
-        // dropdown that pops up while typing. The previous implementation looked
-        // for a standalone "添加话题" button + dedicated search <input>, which the
-        // current creator-center editor no longer exposes — it left bare "#"
-        // characters in the body with no linked topics. We now drive the native
-        // inline flow: focus the body editor, type "#keyword" (firing the
-        // dropdown), then select the matching suggestion.
-        let addedTopics = [];
-        if (topics.length) {
-            addedTopics = await addTopics(page, BODY_SELECTORS, topics);
-        }
-        // ── Step 7: Publish or save draft ─────────────────────────────────────────
-        const actionLabels = isDraft ? ['暂存离开', '存草稿'] : ['发布', '发布笔记'];
-        const invokeResult = await page.evaluate(`
-      (cfg => {
-        const { isDraftMode, publishNames, draftNames, labels } = cfg;
-        const isVisible = (el) => {
-          if (!el || el.offsetParent === null) return false;
-          const rect = el.getBoundingClientRect();
-          return rect.width > 0 && rect.height > 0;
-        };
-        // Path 1: web component method invoke on <xhs-publish-btn>.
-        const hosts = Array.from(document.querySelectorAll('xhs-publish-btn')).filter(isVisible);
-        const wanted = isDraftMode ? draftNames : publishNames;
-        // Try every host + every candidate; do NOT bail on the first throw
-        // (multiple hosts can exist, and a later name may succeed).
-        let lastMethodError = null;
-        for (const host of hosts) {
-          for (const name of wanted) {
-            if (typeof host[name] !== 'function') continue;
-            try {
-              host[name]();
-              return { ok: true, via: 'method', name };
-            } catch (err) {
-              lastMethodError = String(err && err.message || err);
-            }
-          }
-        }
-        // Path 2: legacy <button>/[role=button] text-match click fallback.
-        const buttons = document.querySelectorAll('button, [role="button"]');
-        for (const btn of buttons) {
-          const text = (btn.innerText || btn.textContent || '').trim();
-          if (
-            labels.some(l => text === l || text.includes(l)) &&
-            isVisible(btn) &&
-            !btn.disabled
-          ) {
-            btn.click();
-            return { ok: true, via: 'click', text };
-          }
-        }
-        return { ok: false, via: 'none', hosts: hosts.length, lastMethodError };
-      })(${JSON.stringify({
-            isDraftMode: isDraft,
-            publishNames: PUBLISH_METHOD_NAMES,
-            draftNames: DRAFT_METHOD_NAMES,
-            labels: actionLabels,
-        })})
-    `);
-        if (!invokeResult?.ok) {
-            // ── Draft fallback: try leave-and-save flow ──────────────────────────
-            if (isDraft) {
-                const leaveTriggered = await page.evaluate(`
-              (() => {
-                const labels = ['返回', '关闭', '取消', '离开'];
-                const buttons = document.querySelectorAll('button, [role="button"], div, span');
-                for (const btn of buttons) {
-                  const text = (btn.innerText || btn.textContent || '').trim();
-                  if (labels.some(l => text === l || text.includes(l)) && btn.offsetParent !== null) {
-                    btn.click();
-                    return true;
-                  }
-                }
-                return false;
-              })()
-            `);
-                if (leaveTriggered) {
-                    await page.wait({ time: 1 });
-                    const saveLabels = ['暂存离开', '存草稿', '保存草稿'];
-                    const saved = await page.evaluate(`
-                (labels => {
-                  const buttons = document.querySelectorAll('button, [role="button"]');
-                  for (const btn of buttons) {
-                    const text = (btn.innerText || btn.textContent || '').trim();
-                    if (
-                      labels.some(l => text === l || text.includes(l)) &&
-                      btn.offsetParent !== null &&
-                      !btn.disabled
-                    ) {
-                      btn.click();
-                      return true;
-                    }
-                  }
-                  return false;
-                })(${JSON.stringify(saveLabels)})
-              `);
-                    if (saved) {
-                        invokeResult.ok = true;
-                        invokeResult.via = 'leave-save-fallback';
-                    }
-                }
-                // Check if auto-saved
-                if (!invokeResult?.ok) {
-                    await page.wait({ time: 2 });
-                    const autoSaved = await page.evaluate(`
-                () => {
-                  const markers = ['草稿箱(', '保存于', '编辑于'];
-                  for (const el of document.querySelectorAll('*')) {
-                    const text = (el.innerText || el.textContent || '').trim();
-                    if (text && markers.some(marker => text.includes(marker))) return true;
-                  }
-                  return false;
-                }
-              `);
-                    if (autoSaved) {
-                        invokeResult.ok = true;
-                        invokeResult.via = 'auto-save';
-                    }
-                }
-            }
-        }
-        if (!invokeResult?.ok) {
-            await page.screenshot({ path: '/tmp/xhs_publish_submit_debug.png' });
-            const viaClause = invokeResult?.via ? ` (via=${invokeResult.via})` : '';
-            const errorClause = invokeResult?.error ? `, error=${invokeResult.error}` : '';
-            const lastMethodClause = invokeResult?.lastMethodError ? `, lastMethodError=${invokeResult.lastMethodError}` : '';
-            throw new Error(`Could not trigger "${actionLabels[0]}" action${viaClause}${errorClause}${lastMethodClause}. ` +
-                'Debug screenshot: /tmp/xhs_publish_submit_debug.png');
-        }
-        // ── Step 8: Verify success ─────────────────────────────────────────────────
-        await page.wait({ time: 4 });
-        const finalUrl = await page.evaluate('() => location.href');
-        const successMarkers = isDraft
-            ? ['草稿已保存', '暂存成功', '保存成功', '保存于', '图文笔记(']
-            : ['发布成功', '上传成功'];
-        const successMsg = await page.evaluate(`
-      (markers => {
-        for (const el of document.querySelectorAll('*')) {
-          if (el.tagName === 'STYLE' || el.tagName === 'SCRIPT') continue;
-          const text = (el.innerText || '').trim();
-          if (text.length > 200) continue;
-          if (el.children.length === 0 && markers.some(marker => text.includes(marker))) return text;
-        }
-        return '';
-      })(${JSON.stringify(successMarkers)})
-    `);
-        const navigatedAway = !finalUrl.includes('/publish/publish');
-        const isSuccess = successMsg.length > 0 || navigatedAway;
-        const verb = isDraft ? '暂存成功' : '发布成功';
-        if (!isSuccess) {
-            throw new CommandExecutionError(`${verb} could not be verified: no success marker or post-submit navigation was observed. ` +
-                (finalUrl ? `Current URL: ${finalUrl}` : 'Current URL was empty.'));
-        }
-        return [
-            {
-                status: `✅ ${verb}`,
-                detail: [
-                    `"${title}"`,
-                    isTextImage
-                        ? `${cards.length}张文字配图${absImagePaths.length ? ` + ${absImagePaths.length}张图片` : ''}${appliedCardStyle && appliedCardStyle !== DEFAULT_CARD_STYLE ? ` (${appliedCardStyle})` : ''}`
-                        : `${absImagePaths.length}张图片`,
-                    addedTopics.length ? `话题: ${addedTopics.join(' ')}` : '',
-                    successMsg || finalUrl || '',
-                ]
-                    .filter(Boolean)
-                    .join(' · '),
-            },
-        ];
-    },
-});