@iducky/media-agent 1.1.0

package/src/media_agent/platforms/xiaohongshu/xiaohongshu_publish.py

@@ -0,0 +1,925 @@
+#!/usr/bin/env python3
+"""
+小红书创作服务平台发布脚本 — 五阶段发布流水线。
+
+注意：浏览器自动化部分为 IMPLEMENTED_UNVERIFIED，实现依据为
+docs/xiaohongshu-creator-publishing-handoff.md 的实测流程，
+待 Level 2 在线实测后固化；CLI 底座（账本去重、素材校验、门禁、
+退出码）已经 Level 1 离线测试验证。
+
+Phases:
+  --dry-run          检查素材 SHA-256 去重，不执行实际操作（不开浏览器、不取锁、不写账本）
+  --prepare          上传素材、填写并读回标题、写账本后保持浏览器等待确认
+  --confirm-submit   确认提交（单次真实点击"发布"）
+  --status           查询发布状态
+  --close            关闭浏览器并释放锁
+
+Ledger: tasks/xiaohongshu_publish/publish-ledger.jsonl
+State machine: discovered → prepared → submitted → reviewing → published/rejected/indeterminate/failed
+SHA-256 dedup: submitted / reviewing / published 永久阻止重复提交。
+"""
+from media_agent.runtime.paths import runtime_home
+
+import argparse
+import hashlib
+import json
+import os
+import signal
+import sys
+import time
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+
+# ─── Paths ───────────────────────────────────────────────────────────────────
+BASE = runtime_home()
+LOCKS_DIR = BASE / 'locks'
+LEDGER_DIR = BASE / 'tasks' / 'xiaohongshu_publish'
+LEDGER_FILE = LEDGER_DIR / 'publish-ledger.jsonl'
+PUBLISH_URL = 'https://creator.xiaohongshu.com/publish/video-publish'
+NOTE_MANAGER_URL = 'https://creator.xiaohongshu.com/new/note-manager'
+SIGNAL_DIR = BASE / 'signals'
+
+
+def _profile_dir(profile_id):
+    return BASE / 'profiles' / profile_id
+
+
+def _browser_data(profile_id):
+    return str(_profile_dir(profile_id) / 'browser_data')
+
+
+def _lock_file(profile_id):
+    return LOCKS_DIR / f'{profile_id}.lock'
+
+
+def _confirm_file(profile_id):
+    return SIGNAL_DIR / f'{profile_id}.confirm'
+
+
+def _close_file(profile_id):
+    return SIGNAL_DIR / f'{profile_id}.close'
+
+
+# ─── Constants ───────────────────────────────────────────────────────────────
+DEDUP_STATES = {'submitted', 'reviewing', 'published'}
+SUPPORTED_VIDEO_FORMATS = {'.mp4', '.mov', '.avi', '.wmv', '.flv', '.mkv', '.webm', '.m4v', '.3gp'}
+TZ_SHANGHAI = timezone(timedelta(hours=8))
+NOTE_POLL_INTERVAL = 18  # 交接文档要求 15–20 秒间隔只读检查
+NOTE_POLL_TIMEOUT = 300  # 最长 5 分钟
+SUCCESS_PAGE_WAIT = 180  # 点击后等待同域跳转最长 180 秒
+
+
+# ─── Helpers ─────────────────────────────────────────────────────────────────
+
+def sha256_file(path):
+    """Compute SHA-256 digest of a file."""
+    h = hashlib.sha256()
+    with open(path, 'rb') as f:
+        while True:
+            chunk = f.read(65536)
+            if not chunk:
+                break
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def load_ledger():
+    """Load all ledger entries as a list of dicts."""
+    LEDGER_DIR.mkdir(parents=True, exist_ok=True)
+    if not LEDGER_FILE.exists():
+        return []
+    entries = []
+    for line in LEDGER_FILE.read_text().splitlines():
+        line = line.strip()
+        if line:
+            try:
+                entries.append(json.loads(line))
+            except json.JSONDecodeError:
+                pass
+    return entries
+
+
+def find_ledger_entry(sha256):
+    """Return the most recent ledger entry matching a SHA-256 (or None)."""
+    for entry in reversed(load_ledger()):
+        if entry.get('sha256') == sha256:
+            return entry
+    return None
+
+
+def check_duplicate(sha256):
+    """Return (is_blocked, existing_entry) — True if SHA-256 is in a terminal dedup state."""
+    entry = find_ledger_entry(sha256)
+    if entry and entry.get('state') in DEDUP_STATES:
+        return True, entry
+    return False, entry
+
+
+def append_ledger(entry):
+    """Append a JSON line to the ledger."""
+    LEDGER_DIR.mkdir(parents=True, exist_ok=True)
+    with open(LEDGER_FILE, 'a') as f:
+        f.write(json.dumps(entry, ensure_ascii=False) + '\n')
+
+
+def acquire_lock(profile_id, task_id):
+    """Acquire the profile lock. Returns (ok, existing_owner)."""
+    lf = _lock_file(profile_id)
+    LOCKS_DIR.mkdir(parents=True, exist_ok=True)
+    if lf.exists():
+        try:
+            old = json.loads(lf.read_text())
+            os.kill(old.get('pid', 0), 0)
+            return False, old
+        except (OSError, json.JSONDecodeError):
+            lf.unlink()
+    lf.write_text(json.dumps({
+        'task_id': task_id,
+        'pid': os.getpid(),
+        'time': datetime.now().isoformat(),
+        'phase': 'publish',
+    }, indent=2))
+    return True, None
+
+
+def release_lock(profile_id):
+    """Release the profile lock."""
+    lf = _lock_file(profile_id)
+    if lf.exists():
+        lf.unlink(missing_ok=True)
+
+
+def now_iso():
+    """Return current time in Asia/Shanghai ISO format."""
+    return datetime.now(TZ_SHANGHAI).isoformat()
+
+
+def log(msg):
+    """Print a structured log line to stdout."""
+    print(json.dumps({'ts': now_iso(), **msg}, ensure_ascii=False), flush=True)
+
+
+def die(code, msg):
+    """Print error and exit."""
+    log({'level': 'ERROR', 'exit_code': code, **msg})
+    sys.exit(code)
+
+
+def _kwargs(**kw):
+    """Helper to return a dict of kwargs — for readability."""
+    return kw
+
+
+def _validate_media(media_path):
+    """Validate media file existence and format. Returns resolved Path."""
+    path = Path(media_path).resolve()
+    if not path.exists():
+        die(1, _kwargs(error='FILE_NOT_FOUND', path=str(path)))
+    if not path.is_file():
+        die(1, _kwargs(error='NOT_A_FILE', path=str(path)))
+    ext = path.suffix.lower()
+    if ext not in SUPPORTED_VIDEO_FORMATS:
+        die(1, _kwargs(
+            error='UNSUPPORTED_FORMAT',
+            format=ext, supported=sorted(SUPPORTED_VIDEO_FORMATS),
+        ))
+    return path
+
+
+# ─── Browser ─────────────────────────────────────────────────────────────────
+
+def launch_browser(profile_id):
+    """Launch a CloakBrowser persistent context for the profile."""
+    from media_agent.runtime.browser import launch_persistent_context
+
+    pdir = _profile_dir(profile_id)
+    cfg = json.loads((pdir / 'config.json').read_text())
+    fp = cfg.get('fingerprint', {})
+
+    ctx = launch_persistent_context(
+        user_data_dir=_browser_data(profile_id),
+        headless=False,
+        stealth_args=True,
+        viewport=fp.get('viewport', {'width': 1440, 'height': 900}),
+        locale=fp.get('locale', 'zh-CN'),
+        timezone=fp.get('timezone', 'Asia/Shanghai'),
+        humanize=False,
+        geoip=False,
+    )
+    return ctx, cfg
+
+
+def _is_login_page(url):
+    """Detect login/passport redirect."""
+    low = url.lower()
+    return 'login' in low or 'passport' in low
+
+
+# ─── Phase: dry-run ──────────────────────────────────────────────────────────
+
+def phase_dry_run(profile_id, media_path):
+    """Check media file validity and SHA-256 dedup status.
+
+    纯离线检查：不开浏览器、不取锁、不写账本。
+    """
+    path = _validate_media(media_path)
+    file_size = path.stat().st_size
+    sha = sha256_file(str(path))
+    blocked, existing = check_duplicate(sha)
+
+    result = _kwargs(
+        phase='dry-run',
+        media_path=str(path),
+        file_size=file_size,
+        file_size_mb=round(file_size / 1024 / 1024, 2),
+        sha256=sha,
+        format=path.suffix.lower(),
+        duplicate_blocked=blocked,
+        profile_id=profile_id,
+    )
+
+    if blocked:
+        result['existing_state'] = existing.get('state')
+        result['existing_task_id'] = existing.get('task_id')
+        result['existing_timestamp'] = existing.get('timestamp')
+        log(result)
+        sys.exit(8)  # DUPLICATE_BLOCKED
+
+    log(result)
+    return sha, str(path)
+
+
+# ─── Prepare helpers ─────────────────────────────────────────────────────────
+
+def _wait_for_upload_complete(page, timeout=300):
+    """Wait for the video upload/processing to complete."""
+    start = time.time()
+    while time.time() - start < timeout:
+        status = page.evaluate('''() => {
+            const body = document.body.textContent || '';
+            const processing = body.includes('上传中') || body.includes('视频上传中') || body.includes('处理中');
+            // 完成证据：发布按钮出现/启用、视频预览或智能封面
+            let publishReady = false;
+            for (const el of document.querySelectorAll('button, div, span')) {
+                const text = (el.textContent || '').trim();
+                if (text === '发布' && el.offsetParent !== null) { publishReady = true; break; }
+            }
+            const preview = document.querySelector('video');
+            if (publishReady && !processing) { return 'done'; }
+            if (preview && !processing) { return 'done'; }
+            if (processing) { return 'processing'; }
+            return 'waiting';
+        }''')
+        if status == 'done':
+            return True
+        if status == 'processing':
+            log(_kwargs(step='upload_progress', status='processing', elapsed=round(time.time() - start)))
+        time.sleep(3)
+    return False
+
+
+def _dismiss_popups(page):
+    """位置权限选"一律不允许"；"要恢复页面吗"提示关闭而非恢复。"""
+    time.sleep(2)
+    dismissed = page.evaluate('''() => {
+        const actions = [];
+        const denyKeywords = ['一律不允许', '不允许', '禁止', '拒绝', "Don't Allow", 'Block', 'Deny'];
+        for (const kw of denyKeywords) {
+            for (const el of document.querySelectorAll('button, span, div, a')) {
+                const text = (el.textContent || '').trim();
+                if ((text === kw || text.includes(kw)) && el.offsetParent !== null) {
+                    el.click();
+                    actions.push('denied:' + kw);
+                    break;
+                }
+            }
+            if (actions.length) break;
+        }
+        // "要恢复页面吗？" → 点关闭图标，绝不点"恢复"
+        for (const el of document.querySelectorAll('[class*="close"], [aria-label="关闭"], [class*="Close"]')) {
+            const rect = el.getBoundingClientRect();
+            if (el.offsetParent !== null && rect.width > 0 && rect.width < 60) {
+                const nearby = (el.closest('div')?.textContent || '');
+                if (nearby.includes('恢复页面')) {
+                    el.click();
+                    actions.push('restore_prompt_closed');
+                    break;
+                }
+            }
+        }
+        return actions;
+    }''')
+    log(_kwargs(step='dismiss_popups', result=dismissed))
+    time.sleep(1)
+
+
+def _fill_title(page, title):
+    """Fill the note title input."""
+    r = page.evaluate('''(t) => {
+        const selectors = [
+            'input[placeholder*="填写标题"]',
+            'input[placeholder*="标题"]',
+            '#publishInput',
+            '[class*="title"] input',
+            '[class*="c-input_titleInput"] input',
+        ];
+        for (const sel of selectors) {
+            for (const inp of document.querySelectorAll(sel)) {
+                if (inp.offsetParent !== null) {
+                    const setter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value').set ||
+                                 Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, 'value').set;
+                    setter.call(inp, t);
+                    inp.dispatchEvent(new Event('input', { bubbles: true }));
+                    inp.dispatchEvent(new Event('change', { bubbles: true }));
+                    return 'title_set';
+                }
+            }
+        }
+        return 'no_title_input';
+    }''', title)
+    log(_kwargs(step='fill_title', result=r))
+    return r == 'title_set'
+
+
+def _readback_title(page):
+    """Read back the title value from the page."""
+    value = page.evaluate('''() => {
+        for (const inp of document.querySelectorAll('input, textarea')) {
+            if (inp.offsetParent !== null && inp.value && inp.value.trim()) {
+                const ph = inp.placeholder || '';
+                if (ph.includes('标题')) { return inp.value; }
+            }
+        }
+        for (const inp of document.querySelectorAll('input, textarea')) {
+            if (inp.offsetParent !== null && inp.value && inp.value.trim()) {
+                return inp.value;
+            }
+        }
+        return '';
+    }''')
+    log(_kwargs(step='title_readback', value=(value or '')[:60]))
+    return value or ''
+
+
+def _inspect_publish_button(page):
+    """发布按钮必须唯一、可见且启用。"""
+    info = page.evaluate('''() => {
+        const buttons = [];
+        for (const el of document.querySelectorAll('button, [role="button"]')) {
+            const text = (el.textContent || '').trim();
+            if (text === '发布' && el.offsetParent !== null) {
+                buttons.push({
+                    tag: el.tagName,
+                    disabled: el.disabled === true || el.getAttribute('aria-disabled') === 'true',
+                });
+            }
+        }
+        return {count: buttons.length, buttons: buttons};
+    }''')
+    log(_kwargs(step='publish_button_inspect', **info))
+    ready = info.get('count') == 1 and not any(b.get('disabled') for b in info.get('buttons', []))
+    return ready
+
+
+def _verify_note_in_manager(page, title):
+    """在"笔记管理 → 全部"按标题匹配目标卡片并读取状态。
+
+    返回 dict：{note_found, note_status, evidence}。
+    note_status ∈ reviewing / published / rejected / unknown。
+    """
+    info = page.evaluate('''(targetTitle) => {
+        const cards = document.querySelectorAll('[class*="note"], [class*="card"], li, tr');
+        for (const card of cards) {
+            const text = (card.textContent || '');
+            if (!text.includes(targetTitle)) { continue; }
+            const status = text.includes('未通过') ? 'rejected'
+                : text.includes('审核中') ? 'reviewing'
+                : text.includes('已发布') ? 'published'
+                : 'unknown';
+            return {
+                note_found: true,
+                note_status: status,
+                evidence: text.replace(/\\s+/g, ' ').trim().substring(0, 120),
+            };
+        }
+        return {note_found: false, note_status: 'unknown', evidence: ''};
+    }''', title)
+    return info
+
+
+# ─── Phase: prepare ──────────────────────────────────────────────────────────
+
+def phase_prepare(profile_id, media_path, title):
+    """Upload media, fill title, write ledger, keep browser awaiting confirm."""
+    path = _validate_media(media_path)
+    sha = sha256_file(str(path))
+
+    blocked, existing = check_duplicate(sha)
+    if blocked:
+        die(8, _kwargs(
+            phase='prepare', error='DUPLICATE_BLOCKED', sha256=sha,
+            existing_state=existing.get('state'),
+            existing_task_id=existing.get('task_id'),
+        ))
+
+    task_id = f'xhs_publish_{profile_id}_{datetime.now().strftime("%Y%m%d_%H%M%S")}'
+
+    ok, owner = acquire_lock(profile_id, task_id)
+    if not ok:
+        die(3, _kwargs(phase='prepare', error='PROFILE_LOCKED', owner=owner))
+
+    log(_kwargs(phase='prepare', step='launch_browser', task_id=task_id))
+
+    try:
+        ctx, cfg = launch_browser(profile_id)
+        page = ctx.pages[0] if ctx.pages else ctx.new_page()
+    except Exception as e:
+        release_lock(profile_id)
+        die(1, _kwargs(phase='prepare', error='BROWSER_LAUNCH_FAILED', detail=str(e)[:200]))
+
+    ledger_entry = None
+    try:
+        # ── 直接进入视频发布页（不点击"发布视频笔记"入口，避免触发原生文件选择器）──
+        log(_kwargs(step='navigate', url=PUBLISH_URL))
+        page.goto(PUBLISH_URL, wait_until='load', timeout=60000)
+        time.sleep(5)
+
+        current_url = page.url
+        if _is_login_page(current_url):
+            ctx.close()
+            release_lock(profile_id)
+            die(2, _kwargs(phase='prepare', error='LOGIN_REQUIRED', current_url=current_url[:120]))
+
+        log(_kwargs(step='landed', url=current_url[:120], title=page.title()))
+
+        # ── 上传：直接对 file input 设置路径，绕开原生文件选择器 ──
+        log(_kwargs(step='upload', path=str(path)))
+        try:
+            file_input = page.locator('input[type="file"]').first
+            file_input.set_input_files(str(path))
+            log(_kwargs(step='file_set', result='ok', native_chooser_bypassed=True))
+        except Exception as e:
+            log(_kwargs(step='file_set', result='locator_failed', error=str(e)[:100]))
+            page.evaluate('''() => {
+                const inputs = document.querySelectorAll('input[type="file"]');
+                for (const inp of inputs) {
+                    inp.style.display = 'block';
+                    inp.style.visibility = 'visible';
+                    inp.style.position = 'static';
+                }
+                return inputs.length;
+            }''')
+            try:
+                file_input = page.locator('input[type="file"]').first
+                file_input.set_input_files(str(path))
+                log(_kwargs(step='file_set', result='ok_retry', native_chooser_bypassed=True))
+            except Exception as e2:
+                ctx.close()
+                release_lock(profile_id)
+                die(1, _kwargs(phase='prepare', error='UPLOAD_FAILED', detail=str(e2)[:200]))
+
+        time.sleep(3)
+
+        # ── 处理位置权限等弹窗 ──
+        _dismiss_popups(page)
+
+        # ── 等待上传与平台处理完成 ──
+        if not _wait_for_upload_complete(page):
+            log(_kwargs(step='upload_wait', warning='timeout — proceeding anyway'))
+
+        # ── 填写标题并读回校验 ──
+        filled = _fill_title(page, title)
+        time.sleep(1)
+        readback = _readback_title(page)
+        title_ok = filled and readback.strip() == title.strip()
+        if not title_ok:
+            log(_kwargs(step='title_readback_mismatch', expected=title[:40], actual=readback[:40]))
+
+        # ── Write ledger entry ──
+        ledger_entry = _kwargs(
+            task_id=task_id,
+            sha256=sha,
+            path=str(path),
+            state='prepared',
+            timestamp=now_iso(),
+            profile_id=profile_id,
+            title=title,
+            title_readback=readback,
+            title_ok=title_ok,
+            file_size=path.stat().st_size,
+            click_count=0,
+            pid=os.getpid(),
+        )
+        append_ledger(ledger_entry)
+        log(_kwargs(phase='prepare', step='ledger_written', state='prepared', task_id=task_id))
+
+        # ── Wait for confirm or close signal ──
+        SIGNAL_DIR.mkdir(parents=True, exist_ok=True)
+        cf = _confirm_file(profile_id)
+        clf = _close_file(profile_id)
+        for f in [cf, clf]:
+            if f.exists():
+                f.unlink(missing_ok=True)
+
+        log(_kwargs(
+            phase='prepare', step='awaiting_confirm', task_id=task_id,
+            hint='Run xhs-publish-confirm to submit, or xhs-publish-close to abort',
+        ))
+
+        while True:
+            if cf.exists():
+                cf.unlink(missing_ok=True)
+                log(_kwargs(phase='prepare', step='confirm_received'))
+
+                # 门禁：按钮必须唯一、可见且启用，否则不点击继续等待
+                if not _inspect_publish_button(page):
+                    log(_kwargs(step='publish_button_not_ready', warning='waiting, no click performed'))
+                    continue
+
+                # 单次真实点击"发布"
+                clicked = page.evaluate('''() => {
+                    for (const el of document.querySelectorAll('button, [role="button"], div, span')) {
+                        const text = (el.textContent || '').trim();
+                        if (text === '发布' && el.offsetParent !== null) {
+                            el.dispatchEvent(new MouseEvent('mousedown', {bubbles: true, cancelable: true}));
+                            el.dispatchEvent(new MouseEvent('mouseup', {bubbles: true, cancelable: true}));
+                            el.dispatchEvent(new MouseEvent('click', {bubbles: true, cancelable: true}));
+                            return 'clicked:' + el.tagName + ':' + text;
+                        }
+                    }
+                    return 'not_found';
+                }''')
+                ledger_entry['click_count'] = 1
+                log(_kwargs(step='publish_click', result=clicked, click_count=1))
+                time.sleep(5)
+
+                # ── 等待发布成功页（最长 180 秒）──
+                success_seen = False
+                start_wait = time.time()
+                while time.time() - start_wait < SUCCESS_PAGE_WAIT:
+                    current_url = page.url
+                    page_text = page.evaluate('() => document.body.innerText.substring(0,500)')
+                    if '/publish/success' in current_url or '发布成功' in page_text:
+                        success_seen = True
+                        log(_kwargs(step='success_page', url=current_url[:120]))
+                        break
+                    if '失败' in page_text or '错误' in page_text:
+                        log(_kwargs(step='platform_error_hint', text=page_text[:200]))
+                    time.sleep(5)
+
+                if not success_seen:
+                    # 成功页证据不足 → indeterminate，保持浏览器，禁止重发
+                    ledger_entry['state'] = 'indeterminate'
+                    ledger_entry['indeterminate_at'] = now_iso()
+                    ledger_entry['indeterminate_reason'] = 'no_success_page_evidence'
+                    ledger_entry['result'] = 'PUBLISH_INDETERMINATE'
+                    append_ledger(ledger_entry)
+                    log(_kwargs(phase='prepare', step='indeterminate', task_id=task_id))
+                    continue  # Stay in loop waiting for close signal
+
+                # 成功页只证明平台接收提交 → SUBMITTED / VERIFYING_NOTE，不得直接判 PUBLISHED
+                ledger_entry['state'] = 'submitted'
+                ledger_entry['submitted_at'] = now_iso()
+                ledger_entry['success_page_seen'] = True
+                append_ledger(ledger_entry)
+                log(_kwargs(phase='prepare', step='VERIFYING_NOTE', task_id=task_id,
+                            note='success page only proves receipt, verifying in note manager'))
+
+                # 等约 10 秒让作品列表同步
+                time.sleep(10)
+
+                # ── VERIFYING_NOTE: 进入 note-manager → 全部 核验 ──
+                page.goto(NOTE_MANAGER_URL, wait_until='load', timeout=60000)
+                time.sleep(5)
+                page.evaluate('''() => {
+                    for (const el of document.querySelectorAll('div, span, a, li')) {
+                        const text = (el.textContent || '').trim();
+                        if (text === '全部' && el.offsetParent !== null) { el.click(); return 'clicked'; }
+                    }
+                    return 'not_found';
+                }''')
+                time.sleep(3)
+                log(_kwargs(step='note_manager_landed', url=page.url[:120], section='笔记管理/全部'))
+
+                verify = _verify_note_in_manager(page, title)
+                log(_kwargs(step='note_verify', **verify))
+
+                if not verify.get('note_found'):
+                    # 轮询最长 5 分钟（15–20 秒间隔只读检查）
+                    start_poll = time.time()
+                    while time.time() - start_poll < NOTE_POLL_TIMEOUT:
+                        time.sleep(NOTE_POLL_INTERVAL)
+                        page.reload(timeout=15000)
+                        time.sleep(3)
+                        page.evaluate('''() => {
+                            for (const el of document.querySelectorAll('div, span, a, li')) {
+                                const text = (el.textContent || '').trim();
+                                if (text === '全部' && el.offsetParent !== null) { el.click(); return 'clicked'; }
+                            }
+                            return 'not_found';
+                        }''')
+                        time.sleep(2)
+                        verify = _verify_note_in_manager(page, title)
+                        log(_kwargs(step='note_poll', **verify, elapsed=round(time.time() - start_poll)))
+                        if verify.get('note_found'):
+                            break
+
+                if verify.get('note_found'):
+                    note_status = verify.get('note_status')
+                    ledger_entry['note_found'] = True
+                    ledger_entry['section'] = '笔记管理/全部'
+                    ledger_entry['status_evidence'] = verify.get('evidence')
+                    if note_status in ('published', 'rejected', 'reviewing'):
+                        ledger_entry['state'] = note_status
+                        append_ledger(ledger_entry)
+                        log(_kwargs(phase='prepare', step='final_state', state=note_status, task_id=task_id))
+                    else:
+                        # 卡片已落地但状态标签无法识别 → submitted（已接收）
+                        append_ledger(ledger_entry)
+                        log(_kwargs(phase='prepare', step='final_state', state='submitted',
+                                    note='card_found_status_unknown', task_id=task_id))
+                else:
+                    # 5 分钟仍未找到 → PUBLISH_INDETERMINATE，保持浏览器，禁止重发
+                    ledger_entry['state'] = 'indeterminate'
+                    ledger_entry['indeterminate_at'] = now_iso()
+                    ledger_entry['indeterminate_reason'] = 'note_not_found_after_polling'
+                    ledger_entry['result'] = 'PUBLISH_INDETERMINATE'
+                    ledger_entry['note_found'] = False
+                    append_ledger(ledger_entry)
+                    log(_kwargs(phase='prepare', step='indeterminate', task_id=task_id,
+                                reason='note_not_found', no_resubmit=True))
+                    continue  # Keep browser for manual inspection
+                break
+
+            if clf.exists():
+                clf.unlink(missing_ok=True)
+                log(_kwargs(phase='prepare', step='close_received', task_id=task_id))
+                ledger_entry['state'] = 'indeterminate'
+                ledger_entry['closed_at'] = now_iso()
+                append_ledger(ledger_entry)
+                break
+
+            time.sleep(2)
+
+    except Exception as e:
+        log(_kwargs(phase='prepare', error=str(e)[:300]))
+        try:
+            append_ledger(_kwargs(
+                task_id=task_id, sha256=sha, path=str(path),
+                state='failed', timestamp=now_iso(),
+                error=str(e)[:200], profile_id=profile_id,
+            ))
+        except Exception:
+            pass
+    finally:
+        try:
+            ctx.close()
+        except Exception:
+            pass
+        release_lock(profile_id)
+        log(_kwargs(phase='prepare', step='browser_closed', task_id=task_id))
+
+
+# ─── Phase: confirm-submit ───────────────────────────────────────────────────
+
+def phase_confirm_submit(profile_id):
+    """Send confirm signal to a running prepare process, or launch browser and click submit once."""
+    SIGNAL_DIR.mkdir(parents=True, exist_ok=True)
+    lf = _lock_file(profile_id)
+    cf = _confirm_file(profile_id)
+
+    if lf.exists():
+        try:
+            lock_data = json.loads(lf.read_text())
+            pid = lock_data.get('pid')
+            if pid:
+                os.kill(pid, 0)
+                cf.write_text(json.dumps({
+                    'action': 'confirm',
+                    'timestamp': now_iso(),
+                }))
+                log(_kwargs(phase='confirm-submit', step='signal_sent', target_pid=pid))
+                time.sleep(10)
+                if not cf.exists():
+                    log(_kwargs(phase='confirm-submit', step='signal_consumed', status='ok'))
+                else:
+                    log(_kwargs(phase='confirm-submit', step='signal_pending', status='waiting'))
+                return
+        except (OSError, json.JSONDecodeError):
+            log(_kwargs(phase='confirm-submit', step='process_dead', action='launch_new'))
+
+    log(_kwargs(phase='confirm-submit', step='launch_browser'))
+
+    try:
+        ctx, cfg = launch_browser(profile_id)
+        page = ctx.pages[0] if ctx.pages else ctx.new_page()
+    except Exception as e:
+        die(1, _kwargs(phase='confirm-submit', error='BROWSER_LAUNCH_FAILED', detail=str(e)[:200]))
+
+    try:
+        page.goto(PUBLISH_URL, wait_until='load', timeout=60000)
+        time.sleep(5)
+
+        current_url = page.url
+        if _is_login_page(current_url):
+            ctx.close()
+            die(2, _kwargs(phase='confirm-submit', error='LOGIN_REQUIRED', current_url=current_url[:120]))
+
+        if not _inspect_publish_button(page):
+            log(_kwargs(step='no_publish_button',
+                        warning='Upload page may not have a prepared video. Run xhs-publish-prepare first.'))
+
+        clicked = page.evaluate('''() => {
+            for (const el of document.querySelectorAll('button, [role="button"], div, span')) {
+                const text = (el.textContent || '').trim();
+                if (text === '发布' && el.offsetParent !== null) {
+                    el.click();
+                    return 'clicked:' + text;
+                }
+            }
+            return 'not_found';
+        }''')
+        log(_kwargs(step='confirm_fallback_click', result=clicked, click_count=1 if clicked != 'not_found' else 0))
+        time.sleep(5)
+        log(_kwargs(step='post_submit', url=page.url[:120], title=page.title()))
+
+        entries = load_ledger()
+        if entries:
+            latest = entries[-1]
+            latest['state'] = 'submitted'
+            latest['submitted_at'] = now_iso()
+            append_ledger(latest)
+            log(_kwargs(step='ledger_updated', task_id=latest.get('task_id')))
+
+    except Exception as e:
+        log(_kwargs(phase='confirm-submit', error=str(e)[:300]))
+    finally:
+        try:
+            ctx.close()
+        except Exception:
+            pass
+        release_lock(profile_id)
+        log(_kwargs(phase='confirm-submit', step='browser_closed'))
+
+
+# ─── Phase: status ───────────────────────────────────────────────────────────
+
+def phase_status(profile_id, task_id=None):
+    """Query publish status from the ledger."""
+    entries = load_ledger()
+
+    if task_id:
+        matching = [e for e in entries if e.get('task_id') == task_id]
+    else:
+        matching = entries[-10:]
+
+    if not matching:
+        log(_kwargs(phase='status', entries=[], count=0))
+        return
+
+    states = {}
+    for e in matching:
+        s = e.get('state', 'unknown')
+        states[s] = states.get(s, 0) + 1
+
+    result = _kwargs(
+        phase='status',
+        total_entries=len(entries),
+        shown=len(matching),
+        state_summary=states,
+        entries=matching,
+    )
+
+    lf = _lock_file(profile_id)
+    if lf.exists():
+        try:
+            lock_data = json.loads(lf.read_text())
+            pid = lock_data.get('pid')
+            os.kill(pid, 0)
+            result['browser_running'] = True
+            result['browser_pid'] = pid
+        except (OSError, json.JSONDecodeError):
+            result['browser_running'] = False
+
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    sys.exit(0)
+
+
+# ─── Phase: close ────────────────────────────────────────────────────────────
+
+def phase_close(profile_id):
+    """Close the browser and release the lock."""
+    SIGNAL_DIR.mkdir(parents=True, exist_ok=True)
+    lf = _lock_file(profile_id)
+    clf = _close_file(profile_id)
+
+    result = _kwargs(phase='close', action='none')
+
+    if lf.exists():
+        try:
+            lock_data = json.loads(lf.read_text())
+            pid = lock_data.get('pid')
+            if pid:
+                try:
+                    os.kill(pid, 0)
+                    clf.write_text(json.dumps({
+                        'action': 'close',
+                        'timestamp': now_iso(),
+                    }))
+                    result['action'] = 'signal_sent'
+                    result['pid'] = pid
+                    log(result)
+
+                    for _ in range(15):
+                        time.sleep(2)
+                        if not lf.exists():
+                            result['lock_released'] = True
+                            break
+                        try:
+                            os.kill(pid, 0)
+                        except OSError:
+                            result['lock_released'] = True
+                            release_lock(profile_id)
+                            break
+
+                    if not result.get('lock_released'):
+                        try:
+                            os.kill(pid, signal.SIGTERM)
+                            time.sleep(2)
+                        except OSError:
+                            pass
+                        release_lock(profile_id)
+                        result['action'] = 'force_killed'
+                        result['lock_released'] = True
+
+                    log(result)
+                    return
+                except OSError:
+                    pass
+        except (json.JSONDecodeError, ValueError):
+            pass
+
+    release_lock(profile_id)
+    result['action'] = 'lock_released'
+    result['lock_released'] = True
+    log(result)
+
+
+# ─── CLI ─────────────────────────────────────────────────────────────────────
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='小红书创作服务平台发布 — 五阶段发布流水线（浏览器自动化部分 IMPLEMENTED_UNVERIFIED）',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog='''
+Examples:
+  python3 xiaohongshu_publish.py --dry-run --profile-id <id> --media-path /path/to/video.mp4
+  python3 xiaohongshu_publish.py --prepare --profile-id <id> --media-path /path/to/video.mp4 --title "标题"
+  python3 xiaohongshu_publish.py --confirm-submit --profile-id <id>
+  python3 xiaohongshu_publish.py --status --profile-id <id> [--task-id xhs_publish_xxx]
+  python3 xiaohongshu_publish.py --close --profile-id <id>
+        ''',
+    )
+
+    parser.add_argument('--dry-run', action='store_true', help='Check media without executing')
+    parser.add_argument('--prepare', action='store_true', help='Upload and fill title')
+    parser.add_argument('--confirm-submit', action='store_true', help='Confirm final submission')
+    parser.add_argument('--status', action='store_true', help='Query publish status')
+    parser.add_argument('--close', action='store_true', help='Close browser')
+    parser.add_argument('--media-path', help='Path to media file (required for --dry-run, --prepare)')
+    parser.add_argument('--title', default=None, help='Note title (required for --prepare, generated by Agent)')
+    parser.add_argument('--task-id', default=None, help='Task ID for status query')
+    parser.add_argument('--profile-id', required=True, help='Profile ID')
+    args = parser.parse_args()
+    profile_id = args.profile_id
+
+    if args.dry_run:
+        if not args.media_path:
+            die(1, _kwargs(error='MEDIA_PATH_REQUIRED', detail='--media-path required for --dry-run'))
+        phase_dry_run(profile_id, args.media_path)
+
+    elif args.prepare:
+        if not args.media_path:
+            die(1, _kwargs(error='MEDIA_PATH_REQUIRED', detail='--media-path required for --prepare'))
+        if not args.title or not args.title.strip():
+            die(1, _kwargs(error='TITLE_REQUIRED',
+                           detail='--title required for --prepare; title is generated by Agent from video content'))
+        phase_prepare(profile_id, args.media_path, args.title)
+
+    elif args.confirm_submit:
+        phase_confirm_submit(profile_id)
+
+    elif args.status:
+        phase_status(profile_id, args.task_id)
+
+    elif args.close:
+        phase_close(profile_id)
+
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()