@web-auto/webauto 0.1.4 → 0.1.7

package/apps/webauto/entry/xhs-unified.mjs

@@ -11,6 +11,8 @@ import { AutoscriptRunner } from '../../../modules/camo-runtime/src/autoscript/r
 import { syncXhsAccountsByProfiles } from './lib/account-detect.mjs';
 import { markProfileInvalid } from './lib/account-store.mjs';
 import { listProfilesForPool } from './lib/profilepool.mjs';
+import { runCamo } from './lib/camo-cli.mjs';
+import { publishBusEvent } from './lib/bus-publish.mjs';
 
 function nowIso() {
   return new Date().toISOString();
@@ -65,15 +67,125 @@ function sanitizeForPath(name, fallback = 'unknown') {
   return cleaned || fallback;
 }
 
+const XHS_HOME_URL = 'https://www.xiaohongshu.com';
+
+async function ensureProfileSession(profileId) {
+  const id = String(profileId || '').trim();
+  if (!id) return false;
+  const ret = runCamo(['start', id, '--url', XHS_HOME_URL], {
+    rootDir: process.cwd(),
+    timeoutMs: 60000,
+  });
+  if (ret?.ok) {
+    runCamo(['goto', id, XHS_HOME_URL], { rootDir: process.cwd(), timeoutMs: 60000 });
+  }
+  return Boolean(ret?.ok);
+}
+
+function buildStopScreenshotPath(profileId, reason, outputDir) {
+  const safeProfile = sanitizeForPath(profileId, 'profile');
+  const safeReason = sanitizeForPath(reason || 'stop', 'stop');
+  const file = `stop-${safeProfile}-${safeReason}.png`;
+  return path.join(outputDir, file);
+}
+
+async function captureStopScreenshot({ profileId, reason, outputDir }) {
+  const outDir = String(outputDir || '').trim();
+  if (!outDir) return null;
+  try {
+    await fsp.mkdir(outDir, { recursive: true });
+  } catch {}
+  const outputPath = buildStopScreenshotPath(profileId, reason, outDir);
+  const tryCapture = () => runCamo(['screenshot', profileId, '--output', outputPath], {
+    rootDir: process.cwd(),
+    timeoutMs: 60000,
+  });
+  let ret = tryCapture();
+  if (!ret?.ok) {
+    await ensureProfileSession(profileId);
+    ret = tryCapture();
+  }
+  if (ret?.ok) return outputPath;
+  return null;
+}
+
+function sanitizeKeywordDirParts({ env, keyword }) {
+  return {
+    safeEnv: sanitizeForPath(env, 'prod'),
+    safeKeyword: sanitizeForPath(keyword, 'unknown'),
+  };
+}
+
 function resolveDownloadRoot(customRoot = '') {
   const fromArg = String(customRoot || '').trim();
   if (fromArg) return path.resolve(fromArg);
   const fromEnv = String(process.env.WEBAUTO_DOWNLOAD_ROOT || process.env.WEBAUTO_DOWNLOAD_DIR || '').trim();
   if (fromEnv) return path.resolve(fromEnv);
+  if (process.platform === 'win32') {
+    try {
+      if (fs.existsSync('D:\\')) return 'D:\\webauto';
+    } catch {
+      // ignore
+    }
+    const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+    return path.join(home, '.webauto');
+  }
   const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
   return path.join(home, '.webauto', 'download');
 }
 
+const NON_NOTE_DIR_NAMES = new Set([
+  'merged',
+  'profiles',
+  'like-evidence',
+  'virtual-like',
+  'smart-reply',
+  'comment-match',
+  'discover-fallback',
+]);
+
+async function collectKeywordDirs(baseOutputRoot, env, keyword) {
+  const { safeEnv, safeKeyword } = sanitizeKeywordDirParts({ env, keyword });
+  const dirs = [
+    path.join(baseOutputRoot, 'xiaohongshu', safeEnv, safeKeyword),
+  ];
+  const shardsRoot = path.join(baseOutputRoot, 'shards');
+  try {
+    const entries = await fsp.readdir(shardsRoot, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      dirs.push(path.join(shardsRoot, entry.name, 'xiaohongshu', safeEnv, safeKeyword));
+    }
+  } catch {
+    // ignore
+  }
+  return Array.from(new Set(dirs));
+}
+
+async function collectCompletedNoteIds(baseOutputRoot, env, keyword) {
+  const keywordDirs = await collectKeywordDirs(baseOutputRoot, env, keyword);
+  const completed = new Set();
+  for (const keywordDir of keywordDirs) {
+    let entries = [];
+    try {
+      entries = await fsp.readdir(keywordDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const noteId = String(entry.name || '').trim();
+      if (!noteId || noteId.startsWith('.') || noteId.startsWith('_')) continue;
+      if (NON_NOTE_DIR_NAMES.has(noteId)) continue;
+      completed.add(noteId);
+    }
+  }
+  return {
+    count: completed.size,
+    noteIds: Array.from(completed),
+  };
+}
+
 async function ensureDir(dirPath) {
   await fsp.mkdir(dirPath, { recursive: true });
 }
@@ -88,23 +200,123 @@ async function appendJsonl(filePath, payload) {
   await fsp.appendFile(filePath, `${JSON.stringify(payload)}\n`, 'utf8');
 }
 
+function resolveUnifiedApiBaseUrl() {
+  const raw = String(
+    process.env.WEBAUTO_UNIFIED_API
+    || process.env.WEBAUTO_UNIFIED_URL
+    || 'http://127.0.0.1:7701',
+  ).trim();
+  return raw.replace(/\/+$/, '');
+}
+
+async function postUnifiedTaskRequest(baseUrl, pathname, payload) {
+  try {
+    const response = await fetch(`${baseUrl}${pathname}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload || {}),
+      signal: AbortSignal.timeout(2000),
+    });
+    if (!response.ok) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function createTaskReporter(seed = {}) {
+  const baseUrl = resolveUnifiedApiBaseUrl();
+  const staticSeed = {
+    profileId: String(seed.profileId || 'unknown').trim() || 'unknown',
+    keyword: String(seed.keyword || '').trim(),
+    phase: 'unified',
+  };
+  const createdRunIds = new Set();
+
+  const ensureCreated = async (runId, extra = {}) => {
+    const rid = String(runId || '').trim();
+    if (!rid) return false;
+    if (createdRunIds.has(rid)) return true;
+    const ok = await postUnifiedTaskRequest(baseUrl, '/api/v1/tasks', {
+      runId: rid,
+      ...staticSeed,
+      ...extra,
+    });
+    if (ok) createdRunIds.add(rid);
+    return ok;
+  };
+
+  const update = async (runId, patch = {}) => {
+    const rid = String(runId || '').trim();
+    if (!rid) return false;
+    await ensureCreated(rid, patch);
+    return postUnifiedTaskRequest(baseUrl, `/api/v1/tasks/${encodeURIComponent(rid)}/update`, {
+      ...staticSeed,
+      ...patch,
+    });
+  };
+
+  const pushEvent = async (runId, type, data = {}) => {
+    const rid = String(runId || '').trim();
+    if (!rid) return false;
+    await ensureCreated(rid, data);
+    return postUnifiedTaskRequest(baseUrl, `/api/v1/tasks/${encodeURIComponent(rid)}/events`, {
+      type: String(type || 'event').trim() || 'event',
+      data,
+    });
+  };
+
+  const setError = async (runId, message, code = 'TASK_ERROR', recoverable = false) => {
+    const rid = String(runId || '').trim();
+    if (!rid) return false;
+    return update(rid, {
+      error: {
+        message: String(message || 'task_error'),
+        code: String(code || 'TASK_ERROR'),
+        timestamp: Date.now(),
+        recoverable: recoverable === true,
+      },
+    });
+  };
+
+  return {
+    ensureCreated,
+    update,
+    pushEvent,
+    setError,
+  };
+}
+
 function buildTemplateOptions(argv, profileId, overrides = {}) {
   const keyword = String(argv.keyword || argv.k || '').trim();
-  const env = String(argv.env || 'debug').trim() || 'debug';
+  const env = String(argv.env || 'prod').trim() || 'prod';
   const inputMode = String(argv['input-mode'] || 'protocol').trim() || 'protocol';
   const headless = parseBool(argv.headless, false);
   const ocrCommand = String(argv['ocr-command'] || '').trim();
   const maxNotes = parseIntFlag(argv['max-notes'] ?? argv.target, 30, 1);
+  const maxComments = parseNonNegativeInt(argv['max-comments'], 0);
   const throttle = parseIntFlag(argv.throttle, 500, 100);
   const tabCount = parseIntFlag(argv['tab-count'], 4, 1);
   const noteIntervalMs = parseIntFlag(argv['note-interval'], 900, 200);
-  const maxLikesPerRound = parseIntFlag(argv['max-likes'], 2, 1);
+  const maxLikesPerRound = parseNonNegativeInt(argv['max-likes'], 0);
   const matchMode = String(argv['match-mode'] || 'any').trim() || 'any';
   const matchMinHits = parseIntFlag(argv['match-min-hits'], 1, 1);
   const matchKeywords = String(argv['match-keywords'] || keyword).trim();
   const likeKeywords = String(argv['like-keywords'] || '').trim();
   const replyText = String(argv['reply-text'] || '感谢分享，已关注').trim() || '感谢分享，已关注';
   const outputRoot = String(argv['output-root'] || '').trim();
+  const resume = parseBool(argv.resume, false);
+  const incrementalMax = parseBool(argv['incremental-max'], true);
+  const sharedHarvestPath = String(overrides.sharedHarvestPath ?? argv['shared-harvest-path'] ?? '').trim();
+  const searchSerialKey = String(overrides.searchSerialKey ?? argv['search-serial-key'] ?? '').trim();
+  const seedCollectCount = parseNonNegativeInt(
+    overrides.seedCollectCount ?? argv['seed-collect-count'],
+    0,
+  );
+  const seedCollectMaxRounds = parseNonNegativeInt(
+    overrides.seedCollectMaxRounds ?? argv['seed-collect-rounds'],
+    0,
+  );
 
   const dryRun = parseBool(argv['dry-run'], false);
   const disableDryRun = parseBool(argv['no-dry-run'], false);
@@ -122,7 +334,10 @@ function buildTemplateOptions(argv, profileId, overrides = {}) {
     tabCount,
     noteIntervalMs,
     maxNotes,
+    maxComments,
     maxLikesPerRound,
+    resume,
+    incrementalMax,
     matchMode,
     matchMinHits,
     matchKeywords,
@@ -135,11 +350,15 @@ function buildTemplateOptions(argv, profileId, overrides = {}) {
     doReply: parseBool(argv['do-reply'], false) && !effectiveDryRun,
     doOcr: parseBool(argv['do-ocr'], false),
     persistComments: parseBool(argv['persist-comments'], !effectiveDryRun),
+    sharedHarvestPath,
+    searchSerialKey,
+    seedCollectCount,
+    seedCollectMaxRounds,
   };
   return { ...base, ...overrides };
 }
 
-function buildShardPlan({ profiles, totalNotes, defaultMaxNotes }) {
+function buildEvenShardPlan({ profiles, totalNotes, defaultMaxNotes }) {
   const uniqueProfiles = Array.from(new Set(profiles.map((item) => String(item || '').trim()).filter(Boolean)));
   if (uniqueProfiles.length === 0) return [];
 
@@ -156,6 +375,27 @@ function buildShardPlan({ profiles, totalNotes, defaultMaxNotes }) {
   return plan.filter((item) => item.assignedNotes > 0);
 }
 
+function buildDynamicWavePlan({ profiles, remainingNotes }) {
+  const uniqueProfiles = Array.from(new Set(profiles.map((item) => String(item || '').trim()).filter(Boolean)));
+  if (uniqueProfiles.length === 0) return [];
+  const remaining = Math.max(0, Number(remainingNotes) || 0);
+  if (remaining <= 0) return [];
+
+  if (remaining < uniqueProfiles.length) {
+    return uniqueProfiles.slice(0, remaining).map((profileId) => ({
+      profileId,
+      assignedNotes: 1,
+    }));
+  }
+
+  const waveTotal = remaining - (remaining % uniqueProfiles.length);
+  return buildEvenShardPlan({
+    profiles: uniqueProfiles,
+    totalNotes: waveTotal > 0 ? waveTotal : remaining,
+    defaultMaxNotes: 1,
+  });
+}
+
 function createProfileStats(spec) {
   return {
     assignedNotes: spec.assignedNotes,
@@ -211,10 +451,15 @@ function updateProfileStatsFromEvent(stats, payload) {
   if (event !== 'autoscript:operation_done') return;
 
   const operationId = String(payload.operationId || '').trim();
-  const result = payload.result && typeof payload.result === 'object' ? payload.result : {};
+  const rawResult = payload.result && typeof payload.result === 'object' ? payload.result : {};
+  const result = rawResult.result && typeof rawResult.result === 'object'
+    ? rawResult.result
+    : rawResult;
 
   if (operationId === 'open_first_detail' || operationId === 'open_next_detail') {
-    stats.openedNotes = Math.max(stats.openedNotes, toNumber(result.visited, stats.openedNotes));
+    if (result.opened === true) {
+      stats.openedNotes += 1;
+    }
     return;
   }
 
@@ -256,11 +501,31 @@ function isObject(value) {
 
 async function runProfile(spec, argv, baseOverrides = {}) {
   const profileId = spec.profileId;
+  const busEnabled = parseBool(argv['bus-events'], false) || process.env.WEBAUTO_BUS_EVENTS === '1';
+  const busPublishable = new Set([
+    'xhs.unified.start',
+    'xhs.unified.stop',
+    'xhs.unified.stop_screenshot',
+    'xhs.unified.profile_failed',
+    'autoscript:operation_done',
+    'autoscript:operation_error',
+    'autoscript:operation_terminal',
+    'autoscript:operation_recovery_failed',
+  ]);
+  let currentRunId = null;
   const overrides = {
     ...baseOverrides,
     maxNotes: spec.assignedNotes,
     outputRoot: spec.outputRoot,
   };
+  if (spec.sharedHarvestPath) overrides.sharedHarvestPath = spec.sharedHarvestPath;
+  if (spec.searchSerialKey) overrides.searchSerialKey = spec.searchSerialKey;
+  if (spec.seedCollectCount !== undefined && spec.seedCollectCount !== null) {
+    overrides.seedCollectCount = parseNonNegativeInt(spec.seedCollectCount, 0);
+  }
+  if (spec.seedCollectMaxRounds !== undefined && spec.seedCollectMaxRounds !== null) {
+    overrides.seedCollectMaxRounds = parseNonNegativeInt(spec.seedCollectMaxRounds, 0);
+  }
   const options = buildTemplateOptions(argv, profileId, overrides);
   const script = buildXhsUnifiedAutoscript(options);
   const normalized = normalizeAutoscript(script, `xhs-unified:${profileId}`);
@@ -269,6 +534,31 @@ async function runProfile(spec, argv, baseOverrides = {}) {
 
   await ensureDir(path.dirname(spec.logPath));
   const stats = createProfileStats(spec);
+  const reporter = createTaskReporter({
+    profileId,
+    keyword: options.keyword,
+  });
+  let activeRunId = '';
+  const pushTaskSnapshot = (status = 'running') => {
+    if (!activeRunId) return;
+    void reporter.update(activeRunId, {
+      status,
+      phase: 'unified',
+      progress: {
+        total: Math.max(0, Number(spec.assignedNotes) || 0),
+        processed: Math.max(0, Number(stats.openedNotes) || 0),
+        failed: Math.max(0, Number(stats.operationErrors) || 0),
+      },
+      stats: {
+        notesProcessed: Math.max(0, Number(stats.openedNotes) || 0),
+        commentsCollected: Math.max(0, Number(stats.commentsCollected) || 0),
+        likesPerformed: Math.max(0, Number(stats.likesNewCount) || 0),
+        repliesGenerated: 0,
+        imagesDownloaded: 0,
+        ocrProcessed: 0,
+      },
+    });
+  };
 
   const logEvent = (payload) => {
     const eventPayload = isObject(payload) ? payload : { event: 'autoscript:raw', payload };
@@ -277,9 +567,38 @@ async function runProfile(spec, argv, baseOverrides = {}) {
       profileId,
       ...eventPayload,
     };
+    if (!merged.runId && currentRunId) merged.runId = currentRunId;
     fs.appendFileSync(spec.logPath, `${JSON.stringify(merged)}\n`, 'utf8');
     console.log(JSON.stringify(merged));
     updateProfileStatsFromEvent(stats, merged);
+    if (busEnabled && busPublishable.has(String(merged.event || '').trim())) {
+      void publishBusEvent(merged);
+    }
+    const eventName = String(merged.event || '').trim();
+    const mergedRunId = String(merged.runId || '').trim();
+    if (mergedRunId) activeRunId = mergedRunId;
+    const shouldReportEvent = (
+      eventName === 'xhs.unified.start'
+      || eventName === 'xhs.unified.stop'
+      || eventName === 'autoscript:start'
+      || eventName === 'autoscript:stop'
+      || eventName === 'autoscript:impact'
+      || eventName === 'autoscript:operation_start'
+      || eventName === 'autoscript:operation_done'
+      || eventName === 'autoscript:operation_error'
+      || eventName === 'autoscript:operation_recovery_failed'
+    );
+    if (activeRunId && shouldReportEvent) {
+      void reporter.pushEvent(activeRunId, eventName, merged);
+    }
+    if (
+      eventName === 'autoscript:operation_done'
+      || eventName === 'autoscript:operation_error'
+      || eventName === 'autoscript:operation_recovery_failed'
+      || eventName === 'autoscript:impact'
+    ) {
+      pushTaskSnapshot('running');
+    }
     if (
       merged.event === 'autoscript:event'
       && merged.subscriptionId === 'login_guard'
@@ -293,8 +612,45 @@ async function runProfile(spec, argv, baseOverrides = {}) {
     }
   };
 
+  const runner = new AutoscriptRunner(normalized, {
+    profileId,
+    log: logEvent,
+  });
+
+  const running = await runner.start();
+  currentRunId = running?.runId || currentRunId;
+  activeRunId = String(running?.runId || '').trim();
+  if (activeRunId) {
+    await reporter.ensureCreated(activeRunId, {
+      status: 'starting',
+      phase: 'unified',
+      progress: {
+        total: Math.max(0, Number(spec.assignedNotes) || 0),
+        processed: 0,
+        failed: 0,
+      },
+    });
+    await reporter.update(activeRunId, {
+      status: 'running',
+      phase: 'unified',
+      progress: {
+        total: Math.max(0, Number(spec.assignedNotes) || 0),
+        processed: 0,
+        failed: 0,
+      },
+      stats: {
+        notesProcessed: 0,
+        commentsCollected: 0,
+        likesPerformed: 0,
+        repliesGenerated: 0,
+        imagesDownloaded: 0,
+        ocrProcessed: 0,
+      },
+    });
+  }
   logEvent({
     event: 'xhs.unified.start',
+    runId: running?.runId || null,
     keyword: options.keyword,
     env: options.env,
     maxNotes: options.maxNotes,
@@ -302,13 +658,6 @@ async function runProfile(spec, argv, baseOverrides = {}) {
     outputRoot: options.outputRoot,
     parallelRunLabel: spec.runLabel,
   });
-
-  const runner = new AutoscriptRunner(normalized, {
-    profileId,
-    log: logEvent,
-  });
-
-  const running = await runner.start();
   const done = await running.done;
 
   const stopPayload = {
@@ -321,7 +670,47 @@ async function runProfile(spec, argv, baseOverrides = {}) {
   };
   logEvent(stopPayload);
 
+  const stopScreenshotPath = await captureStopScreenshot({
+    profileId,
+    reason: stopPayload.reason || 'stop',
+    outputDir: path.dirname(spec.logPath),
+  });
+  if (stopScreenshotPath) {
+    logEvent({
+      event: 'xhs.unified.stop_screenshot',
+      profileId,
+      runId: stopPayload.runId,
+      reason: stopPayload.reason || null,
+      path: stopScreenshotPath,
+    });
+  }
+
   stats.stopReason = stopPayload.reason;
+  const finalRunId = String(stopPayload.runId || activeRunId || '').trim();
+  if (finalRunId) {
+    activeRunId = finalRunId;
+    const failed = stopPayload.reason === 'script_failure';
+    await reporter.update(finalRunId, {
+      status: failed ? 'failed' : 'completed',
+      phase: 'unified',
+      progress: {
+        total: Math.max(0, Number(spec.assignedNotes) || 0),
+        processed: Math.max(0, Number(stats.openedNotes) || 0),
+        failed: Math.max(0, Number(stats.operationErrors) || 0),
+      },
+      stats: {
+        notesProcessed: Math.max(0, Number(stats.openedNotes) || 0),
+        commentsCollected: Math.max(0, Number(stats.commentsCollected) || 0),
+        likesPerformed: Math.max(0, Number(stats.likesNewCount) || 0),
+        repliesGenerated: 0,
+        imagesDownloaded: 0,
+        ocrProcessed: 0,
+      },
+    });
+    if (failed) {
+      await reporter.setError(finalRunId, `autoscript stopped: ${stopPayload.reason || 'script_failure'}`, 'SCRIPT_FAILURE', false);
+    }
+  }
 
   const profileResult = {
     ok: stopPayload.reason !== 'script_failure',
@@ -331,6 +720,7 @@ async function runProfile(spec, argv, baseOverrides = {}) {
     assignedNotes: spec.assignedNotes,
     outputRoot: options.outputRoot,
     logPath: spec.logPath,
+    stopScreenshotPath: stopScreenshotPath || null,
     stats,
   };
 
@@ -527,93 +917,49 @@ export async function runUnified(argv, overrides = {}) {
   const keyword = String(argv.keyword || argv.k || '').trim();
   if (!keyword) throw new Error('missing --keyword');
 
-  const env = String(argv.env || 'debug').trim() || 'debug';
+  const env = String(argv.env || 'prod').trim() || 'prod';
+  const busEnabled = parseBool(argv['bus-events'], false) || process.env.WEBAUTO_BUS_EVENTS === '1';
   const profiles = parseProfiles(argv);
   if (profiles.length === 0) throw new Error('missing --profile or --profiles or --profilepool');
-
-  const accountStates = await syncXhsAccountsByProfiles(profiles);
-  const executableProfiles = accountStates
-    .filter((item) => item?.valid === true && Boolean(String(item?.accountId || '').trim()))
-    .map((item) => item.profileId);
-  const invalidProfiles = accountStates.filter((item) => !item || item.valid !== true);
-  if (executableProfiles.length === 0) {
-    throw new Error(`no valid business accounts: ${invalidProfiles.map((item) => `${item.profileId}:${item.reason || 'invalid'}`).join(', ')}`);
-  }
-
+  await Promise.all(profiles.map((profileId) => ensureProfileSession(profileId)));
   const defaultMaxNotes = parseIntFlag(argv['max-notes'] ?? argv.target, 30, 1);
   const totalNotes = parseNonNegativeInt(argv['total-notes'] ?? argv['total-target'], 0);
-  const plan = buildShardPlan({ profiles: executableProfiles, totalNotes, defaultMaxNotes });
-  if (plan.length === 0) throw new Error('empty shard plan');
-
+  const hasTotalTarget = totalNotes > 0;
+  const maxWaves = parseIntFlag(argv['max-waves'], 40, 1);
   const parallelRequested = parseBool(argv.parallel, false);
-  const parallel = parallelRequested && plan.length > 1;
-  const concurrency = parallel
-    ? Math.min(plan.length, parseIntFlag(argv.concurrency, plan.length, 1))
-    : 1;
+  const configuredConcurrency = parseIntFlag(argv.concurrency, profiles.length || 1, 1);
+  const planOnly = parseBool(argv['plan-only'], false);
+  const seedCollectCountFlag = parseNonNegativeInt(argv['seed-collect-count'], 0);
+  const seedCollectRoundsFlag = parseNonNegativeInt(argv['seed-collect-rounds'], 6);
 
   const runLabel = formatRunLabel();
   const baseOutputRoot = resolveDownloadRoot(argv['output-root']);
+  const outputRootArg = String(argv['output-root'] || '').trim();
+  const useShardRoots = profiles.length > 1;
+  const sharedHarvestPath = profiles.length > 1
+    ? path.join(baseOutputRoot, 'xiaohongshu', sanitizeForPath(env, 'prod'), sanitizeForPath(keyword, 'unknown'), 'merged', `run-${runLabel}`, 'coord', 'harvest-note-claims.json')
+    : '';
+  const searchSerialKey = `${sanitizeForPath(env, 'prod')}:${sanitizeForPath(keyword, 'unknown')}:${runLabel}`;
   const mergedDir = path.join(
     baseOutputRoot,
     'xiaohongshu',
-    sanitizeForPath(env, 'debug'),
+    sanitizeForPath(env, 'prod'),
     sanitizeForPath(keyword, 'unknown'),
     'merged',
     `run-${runLabel}`,
   );
   const planPath = path.join(mergedDir, 'plan.json');
-
-  const useShardRoots = plan.length > 1;
-  const specs = plan.map((item) => {
-    const shardId = sanitizeForPath(item.profileId, 'profile');
-    const shardOutputRoot = useShardRoots
-      ? path.join(baseOutputRoot, 'shards', shardId)
-      : String(argv['output-root'] || '').trim();
-    return {
-      ...item,
-      runLabel,
-      outputRoot: shardOutputRoot,
-      logPath: path.join(mergedDir, 'profiles', `${shardId}.events.jsonl`),
-      summaryPath: path.join(mergedDir, 'profiles', `${shardId}.summary.json`),
-    };
-  });
-
-  const planPayload = {
-    event: 'xhs.unified.plan',
-    planPath,
-    keyword,
-    env,
-    totalNotes: totalNotes > 0 ? totalNotes : null,
-    defaultMaxNotes,
-    parallel,
-    concurrency,
-    accountStates,
-    skippedProfiles: invalidProfiles.map((item) => ({
-      profileId: item?.profileId || null,
-      status: item?.status || 'invalid',
-      reason: item?.reason || 'invalid',
-      valid: item?.valid === true,
-      accountId: item?.accountId || null,
-    })),
-    specs: specs.map((item) => ({
-      profileId: item.profileId,
-      assignedNotes: item.assignedNotes,
-      outputRoot: item.outputRoot,
-      logPath: item.logPath,
-    })),
-  };
-  console.log(JSON.stringify(planPayload));
-
-  await writeJson(planPath, planPayload);
-
-  if (parseBool(argv['plan-only'], false)) {
-    return {
-      ok: true,
-      planOnly: true,
-      planPath,
-      specs,
-    };
-  }
+  const completedAtStart = hasTotalTarget
+    ? await collectCompletedNoteIds(baseOutputRoot, env, keyword)
+    : { count: 0, noteIds: [] };
+  let remainingNotes = hasTotalTarget
+    ? Math.max(0, totalNotes - completedAtStart.count)
+    : defaultMaxNotes;
+
+  const skippedProfileMap = new Map();
+  const wavePlans = [];
+  const allResults = [];
+  let finalAccountStates = [];
 
   const execute = async (spec) => {
     try {
@@ -667,9 +1013,159 @@ export async function runUnified(argv, overrides = {}) {
     }
   };
 
-  const results = parallel
-    ? await runWithConcurrency(specs, concurrency, execute)
-    : await runWithConcurrency(specs, 1, execute);
+  for (let wave = 1; wave <= maxWaves; wave += 1) {
+    if (hasTotalTarget && remainingNotes <= 0) break;
+    if (!hasTotalTarget && wave > 1) break;
+
+    let executableProfiles = [];
+    if (planOnly) {
+      executableProfiles = profiles.slice();
+      finalAccountStates = executableProfiles.map((profileId) => ({
+        profileId,
+        status: 'plan_only_unverified',
+        reason: 'plan_only_skip_account_sync',
+        valid: null,
+        accountId: null,
+      }));
+    } else {
+      const accountStates = await syncXhsAccountsByProfiles(profiles);
+      finalAccountStates = accountStates;
+      executableProfiles = accountStates
+        .filter((item) => item?.valid === true && Boolean(String(item?.accountId || '').trim()))
+        .map((item) => item.profileId);
+      const invalidProfiles = accountStates.filter((item) => !item || item.valid !== true);
+      for (const item of invalidProfiles) {
+        const profileId = String(item?.profileId || '').trim();
+        if (!profileId) continue;
+        skippedProfileMap.set(profileId, {
+          profileId,
+          status: item?.status || 'invalid',
+          reason: item?.reason || 'invalid',
+          valid: item?.valid === true,
+          accountId: item?.accountId || null,
+        });
+      }
+
+      if (executableProfiles.length === 0) {
+        if (wave === 1) {
+          throw new Error(`no valid business accounts: ${invalidProfiles.map((item) => `${item.profileId}:${item.reason || 'invalid'}`).join(', ')}`);
+        }
+        break;
+      }
+    }
+
+    const plan = hasTotalTarget
+      ? buildDynamicWavePlan({ profiles: executableProfiles, remainingNotes })
+      : buildEvenShardPlan({ profiles: executableProfiles, totalNotes: 0, defaultMaxNotes });
+    if (plan.length === 0) break;
+
+    const parallel = parallelRequested && plan.length > 1;
+    const concurrency = parallel
+      ? Math.min(plan.length, configuredConcurrency)
+      : 1;
+    const waveTag = `wave-${String(wave).padStart(3, '0')}`;
+    const specs = plan.map((item, index) => {
+      const shardId = sanitizeForPath(item.profileId, 'profile');
+      const shardOutputRoot = useShardRoots
+        ? path.join(baseOutputRoot, 'shards', shardId)
+        : outputRootArg;
+      const defaultSeedCollectCount = Math.max(1, Math.min(
+        Number(item.assignedNotes || 1),
+        Math.max(1, plan.length * 2),
+      ));
+      const seedCollectCount = index === 0
+        ? (seedCollectCountFlag > 0 ? seedCollectCountFlag : defaultSeedCollectCount)
+        : 0;
+      return {
+        ...item,
+        runLabel,
+        waveTag,
+        outputRoot: shardOutputRoot,
+        logPath: path.join(mergedDir, 'profiles', `${waveTag}.${shardId}.events.jsonl`),
+        summaryPath: path.join(mergedDir, 'profiles', `${waveTag}.${shardId}.summary.json`),
+        sharedHarvestPath,
+        searchSerialKey,
+        seedCollectCount,
+        seedCollectMaxRounds: index === 0 ? seedCollectRoundsFlag : 0,
+      };
+    });
+
+    wavePlans.push({
+      wave,
+      waveTag,
+      remainingBefore: remainingNotes,
+      parallel,
+      concurrency,
+      specs: specs.map((item) => ({
+        profileId: item.profileId,
+        assignedNotes: item.assignedNotes,
+        outputRoot: item.outputRoot,
+        logPath: item.logPath,
+        sharedHarvestPath: item.sharedHarvestPath || null,
+        seedCollectCount: item.seedCollectCount || 0,
+        seedCollectMaxRounds: item.seedCollectMaxRounds || 0,
+      })),
+    });
+
+    if (planOnly) break;
+
+    const waveResults = parallel
+      ? await runWithConcurrency(specs, concurrency, execute)
+      : await runWithConcurrency(specs, 1, execute);
+    allResults.push(...waveResults);
+
+    if (hasTotalTarget) {
+      const openedInWave = waveResults.reduce((sum, item) => sum + toNumber(item?.stats?.openedNotes, 0), 0);
+      remainingNotes = Math.max(0, remainingNotes - openedInWave);
+      const waveRecord = wavePlans[wavePlans.length - 1];
+      waveRecord.openedInWave = openedInWave;
+      waveRecord.remainingAfter = remainingNotes;
+      if (openedInWave <= 0) {
+        console.error(JSON.stringify({
+          event: 'xhs.unified.wave_stalled',
+          wave,
+          remainingNotes,
+        }));
+        break;
+      }
+    }
+  }
+
+  const skippedProfiles = Array.from(skippedProfileMap.values());
+
+  const planPayload = {
+    event: 'xhs.unified.plan',
+    planPath,
+    keyword,
+    env,
+    totalNotes: totalNotes > 0 ? totalNotes : null,
+    defaultMaxNotes,
+    maxWaves,
+    runLabel,
+    hasTotalTarget,
+    completedAtStart: completedAtStart.count,
+    remainingAtPlan: remainingNotes,
+    accountStates: finalAccountStates,
+    skippedProfiles,
+    waves: wavePlans,
+  };
+  console.log(JSON.stringify(planPayload));
+
+  await writeJson(planPath, planPayload);
+
+  if (planOnly) {
+    return {
+      ok: true,
+      planOnly: true,
+      planPath,
+      waves: wavePlans,
+    };
+  }
+
+  const results = allResults;
+  if (results.length === 0) {
+    throw new Error(`no executable waves generated, see ${planPath}`);
+  }
 
   const merged = await mergeProfileOutputs({
     results,
@@ -677,26 +1173,55 @@ export async function runUnified(argv, overrides = {}) {
     keyword,
     env,
     totalNotes,
-    parallel,
-    concurrency,
-    skippedProfiles: invalidProfiles.map((item) => ({
-      profileId: item?.profileId || null,
-      status: item?.status || 'invalid',
-      reason: item?.reason || 'invalid',
-      accountId: item?.accountId || null,
-    })),
+    parallel: parallelRequested,
+    concurrency: configuredConcurrency,
+    skippedProfiles,
   });
 
-  console.log(JSON.stringify({
+  const mergedSummary = {
+    ...merged.mergedSummary,
+    progress: {
+      completedAtStart: completedAtStart.count,
+      completedDuringRun: toNumber(merged.mergedSummary?.totals?.openedNotes, 0),
+      targetTotal: hasTotalTarget ? totalNotes : null,
+      remainingAfterRun: hasTotalTarget ? Math.max(0, remainingNotes) : null,
+      reachedTarget: hasTotalTarget ? remainingNotes <= 0 : null,
+    },
+    waves: wavePlans,
+  };
+  await writeJson(merged.summaryPath, mergedSummary);
+
+  const mergedEvent = {
     event: 'xhs.unified.merged',
     summaryPath: merged.summaryPath,
+    waves: wavePlans.length,
     profilesTotal: results.length,
     profilesSucceeded: results.filter((item) => item.ok).length,
     profilesFailed: results.filter((item) => !item.ok).length,
-  }));
+    remainingNotes: hasTotalTarget ? remainingNotes : null,
+  };
+  console.log(JSON.stringify(mergedEvent));
+  if (busEnabled) {
+    void publishBusEvent(mergedEvent);
+  }
 
-  if (results.some((item) => !item.ok)) {
-    throw new Error(`unified finished with failures, see ${merged.summaryPath}`);
+  const failedResults = results.filter((item) => !item.ok);
+  if (hasTotalTarget && remainingNotes > 0) {
+    throw new Error(`target not reached, remaining=${remainingNotes}, see ${merged.summaryPath}`);
+  }
+  if (failedResults.length > 0) {
+    if (hasTotalTarget && remainingNotes <= 0) {
+      console.warn(JSON.stringify({
+        event: 'xhs.unified.partial_failures_tolerated',
+        summaryPath: merged.summaryPath,
+        failedProfiles: failedResults.map((item) => ({
+          profileId: item.profileId,
+          reason: item.reason || null,
+        })),
+      }));
+    } else {
+      throw new Error(`unified finished with failures, see ${merged.summaryPath}`);
+    }
   }
 
   return {
@@ -717,10 +1242,18 @@ async function main() {
       '  --max-notes <n>              单账号目标（未启用 total-notes 时）',
       '  --total-notes <n>            总目标数（自动分片到账号）',
       '  --total-target <n>           total-notes 别名',
+      '  --max-waves <n>              动态分片最大波次（默认40）',
       '  --parallel                   启用并行执行',
+      '  --bus-events <bool>          启用 UI 事件总线推送（默认 false）',
       '  --concurrency <n>            并行度（默认=账号数）',
+      '  --resume <bool>              断点续传（默认 false）',
+      '  --incremental-max <bool>     max-notes 作为增量配额（默认 true）',
       '  --plan-only                  只生成分片计划，不执行',
       '  --output-root <path>         输出根目录（并行时自动分 profile shard）',
+      '  --seed-collect-count <n>     首账号预采样去重ID数量（默认按分片自动）',
+      '  --seed-collect-rounds <n>    首账号预采样滚动轮数（默认6）',
+      '  --search-serial-key <key>    搜索阶段串行锁key（默认自动生成）',
+      '  --shared-harvest-path <path> 共享harvest去重列表路径（默认自动生成）',
     ].join('\n'));
     return;
   }