@web-auto/webauto 0.1.17 → 0.1.19

package/modules/camo-backend/src/internal/BrowserSession.ts

@@ -42,6 +42,36 @@ interface RecordingState {
   lastError: string | null;
 }
 
+type NavigationWaitUntil = 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
+
+function resolveInputActionTimeoutMs(): number {
+  const raw = Number(process.env.CAMO_INPUT_ACTION_TIMEOUT_MS ?? process.env.CAMO_API_TIMEOUT_MS ?? 30000);
+  return Math.max(1000, Number.isFinite(raw) ? raw : 30000);
+}
+
+function resolveNavigationWaitUntil(): NavigationWaitUntil {
+  const raw = String(process.env.CAMO_NAV_WAIT_UNTIL ?? 'commit').trim().toLowerCase();
+  if (raw === 'load') return 'load';
+  if (raw === 'domcontentloaded' || raw === 'dom') return 'domcontentloaded';
+  if (raw === 'networkidle') return 'networkidle';
+  return 'commit';
+}
+
+function resolveInputActionMaxAttempts(): number {
+  const raw = Number(process.env.CAMO_INPUT_ACTION_MAX_ATTEMPTS ?? 2);
+  return Math.max(1, Math.min(3, Number.isFinite(raw) ? Math.floor(raw) : 2));
+}
+
+function resolveInputRecoveryDelayMs(): number {
+  const raw = Number(process.env.CAMO_INPUT_RECOVERY_DELAY_MS ?? 120);
+  return Math.max(0, Number.isFinite(raw) ? Math.floor(raw) : 120);
+}
+
+function resolveInputRecoveryBringToFrontTimeoutMs(): number {
+  const raw = Number(process.env.CAMO_INPUT_RECOVERY_BRING_TO_FRONT_TIMEOUT_MS ?? 800);
+  return Math.max(100, Number.isFinite(raw) ? Math.floor(raw) : 800);
+}
+
 export class BrowserSession {
   private browser?: Browser;
   private context?: BrowserContext;
@@ -56,6 +86,8 @@ export class BrowserSession {
   private bridgedPages = new WeakSet<Page>();
   private recorderBridgePages = new WeakSet<Page>();
   private lastViewport: { width: number; height: number } | null = null;
+  private followWindowViewport = false;
+  private inputActionTail: Promise<void> = Promise.resolve();
   private fingerprint: any = null;
   private recordingStream: fs.WriteStream | null = null;
   private recording: RecordingState = {
@@ -129,15 +161,26 @@ export class BrowserSession {
       userAgent: fingerprint.userAgent?.substring(0, 50) + '...',
     });
 
-    const viewport = this.options.viewport || { width: 3840, height: 2046 };
+    const fallbackViewport = { width: 1440, height: 1100 };
+    const explicitViewport = this.options.viewport
+      && Number(this.options.viewport.width) > 0
+      && Number(this.options.viewport.height) > 0
+      ? {
+        width: Math.floor(Number(this.options.viewport.width)),
+        height: Math.floor(Number(this.options.viewport.height)),
+      }
+      : null;
+    const viewport = explicitViewport || fingerprint?.viewport || fallbackViewport;
+    const headless = !!this.options.headless;
+    this.followWindowViewport = !headless;
     const deviceScaleFactor = this.resolveDeviceScaleFactor();
 
     // 使用 EngineManager 启动上下文（Chromium 已移除，仅支持 Camoufox）
     this.context = await launchEngineContext({
       engine,
-      headless: !!this.options.headless,
+      headless,
       profileDir: this.profileDir,
-      viewport: fingerprint?.viewport || viewport,
+      viewport,
       userAgent: fingerprint?.userAgent,
       locale: 'zh-CN',
       timezoneId: fingerprint?.timezoneId || 'Asia/Shanghai',
@@ -148,7 +191,9 @@ export class BrowserSession {
 
     // NOTE: deviceScaleFactor override was Chromium-only (CDP). Chromium removed.
 
-    this.lastViewport = { width: viewport.width, height: viewport.height };
+    this.lastViewport = this.followWindowViewport
+      ? null
+      : { width: viewport.width, height: viewport.height };
     this.browser = this.context.browser();
     this.browser.on('disconnected', () => this.notifyExit());
     this.context.on('close', () => this.notifyExit());
@@ -158,6 +203,9 @@ export class BrowserSession {
 
     this.setupPageHooks(this.page);
     this.context.on('page', (p) => this.setupPageHooks(p));
+    if (this.followWindowViewport) {
+      await this.refreshViewportFromWindow(this.page).catch(() => {});
+    }
 
     if (initialUrl) {
       await this.goto(initialUrl);
@@ -863,6 +911,10 @@ export class BrowserSession {
   }
 
   private async ensurePageViewport(page: Page): Promise<void> {
+    if (this.followWindowViewport) {
+      await this.refreshViewportFromWindow(page).catch(() => {});
+      return;
+    }
     if (!this.lastViewport) return;
     const current = page.viewportSize();
     if (current && current.width === this.lastViewport.width && current.height === this.lastViewport.height) {
@@ -876,6 +928,31 @@ export class BrowserSession {
     await this.syncDeviceScaleFactor(page, { ...this.lastViewport });
   }
 
+  private async readWindowInnerSize(page: Page): Promise<{ width: number; height: number } | null> {
+    try {
+      const metrics = await page.evaluate(() => ({
+        width: Math.floor(Number(window.innerWidth || 0)),
+        height: Math.floor(Number(window.innerHeight || 0)),
+      }));
+      const width = Number(metrics?.width);
+      const height = Number(metrics?.height);
+      if (!Number.isFinite(width) || !Number.isFinite(height)) return null;
+      if (width < 300 || height < 200) return null;
+      return { width, height };
+    } catch {
+      return null;
+    }
+  }
+
+  private async refreshViewportFromWindow(page: Page): Promise<void> {
+    const inner = await this.readWindowInnerSize(page);
+    if (!inner) return;
+    this.lastViewport = {
+      width: Math.max(800, Math.floor(inner.width)),
+      height: Math.max(700, Math.floor(inner.height)),
+    };
+  }
+
   private ensureContext(): BrowserContext {
     if (!this.context) {
       throw new Error('browser context not ready');
@@ -887,6 +964,11 @@ export class BrowserSession {
     const ctx = this.ensureContext();
     const existing = this.getActivePage();
     if (existing) {
+      try {
+        await this.ensurePageViewport(existing);
+      } catch {
+        /* ignore */
+      }
       return existing;
     }
     this.page = await ctx.newPage();
@@ -913,9 +995,10 @@ export class BrowserSession {
 
   async goBack(): Promise<{ ok: boolean; url: string }> {
     const page = await this.ensurePrimaryPage();
+    const waitUntil = resolveNavigationWaitUntil();
     try {
       const res = await page
-        .goBack({ waitUntil: 'domcontentloaded' })
+        .goBack({ waitUntil })
         .catch((): null => null);
       await ensurePageRuntime(page, true).catch(() => {});
       this.lastKnownUrl = page.url();
@@ -1001,7 +1084,7 @@ export class BrowserSession {
       /* ignore */
     }
     if (url) {
-      await page.goto(url, { waitUntil: 'domcontentloaded' });
+      await page.goto(url, { waitUntil: resolveNavigationWaitUntil() });
       await ensurePageRuntime(page);
       this.lastKnownUrl = url;
     }
@@ -1149,7 +1232,7 @@ export class BrowserSession {
 
   async goto(url: string): Promise<void> {
     const page = await this.ensurePrimaryPage();
-    await page.goto(url, { waitUntil: 'domcontentloaded' });
+    await page.goto(url, { waitUntil: resolveNavigationWaitUntil() });
     await ensurePageRuntime(page);
     this.lastKnownUrl = url;
   }
@@ -1159,19 +1242,8 @@ export class BrowserSession {
     return page.screenshot({ fullPage });
   }
 
-  async click(selector: string): Promise<void> {
-    const page = await this.ensurePrimaryPage();
-    await page.click(selector, { timeout: 20000 });
-  }
-
-  async fill(selector: string, text: string): Promise<void> {
-    const page = await this.ensurePrimaryPage();
-    await page.fill(selector, text, { timeout: 20000 });
-  }
-
   private async ensureInputReady(page: Page): Promise<void> {
     if (this.options.headless) return;
-    if (os.platform() !== 'win32') return;
     let needsFocus = false;
     try {
       const state = await page.evaluate(() => ({
@@ -1193,30 +1265,112 @@ export class BrowserSession {
     }
   }
 
+  private async withInputActionTimeout<T>(label: string, run: () => Promise<T>): Promise<T> {
+    const timeoutMs = resolveInputActionTimeoutMs();
+    let timer: NodeJS.Timeout | null = null;
+    try {
+      return await Promise.race<T>([
+        run(),
+        new Promise<T>((_resolve, reject) => {
+          timer = setTimeout(() => {
+            reject(new Error(`${label} timed out after ${timeoutMs}ms`));
+          }, timeoutMs);
+        }),
+      ]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+
+  private async recoverInputPipeline(page: Page): Promise<Page> {
+    const bringToFrontTimeoutMs = resolveInputRecoveryBringToFrontTimeoutMs();
+    let bringToFrontTimer: NodeJS.Timeout | null = null;
+    try {
+      await Promise.race<void>([
+        page.bringToFront(),
+        new Promise<void>((_resolve, reject) => {
+          bringToFrontTimer = setTimeout(() => {
+            reject(new Error(`input recovery bringToFront timed out after ${bringToFrontTimeoutMs}ms`));
+          }, bringToFrontTimeoutMs);
+        }),
+      ]);
+    } catch {
+      // Best-effort recovery only.
+    } finally {
+      if (bringToFrontTimer) clearTimeout(bringToFrontTimer);
+    }
+    const delayMs = resolveInputRecoveryDelayMs();
+    if (delayMs > 0) {
+      try {
+        await page.waitForTimeout(delayMs);
+      } catch {
+        // Best-effort recovery only.
+      }
+    }
+    return page;
+  }
+
+  private async runInputAction<T>(page: Page, label: string, run: (activePage: Page) => Promise<T>): Promise<T> {
+    const maxAttempts = resolveInputActionMaxAttempts();
+    let lastError: unknown = null;
+    let activePage = page;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+      try {
+        return await this.withInputActionTimeout(`${label} (attempt ${attempt}/${maxAttempts})`, () => run(activePage));
+      } catch (error) {
+        lastError = error;
+        if (attempt >= maxAttempts) break;
+        activePage = await this.recoverInputPipeline(activePage);
+      }
+    }
+    if (lastError instanceof Error) throw lastError;
+    throw new Error(`${label} failed`);
+  }
+
+  private async withInputActionLock<T>(run: () => Promise<T>): Promise<T> {
+    const previous = this.inputActionTail;
+    let release: (() => void) | null = null;
+    this.inputActionTail = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    await previous.catch(() => {});
+    try {
+      return await run();
+    } finally {
+      if (release) release();
+    }
+  }
+
   /**
    * 基于屏幕坐标的系统级鼠标点击（Playwright 原生）
    * @param opts 屏幕坐标及点击选项
    */
   async mouseClick(opts: { x: number; y: number; button?: 'left' | 'right' | 'middle'; clicks?: number; delay?: number }): Promise<void> {
     const page = await this.ensurePrimaryPage();
-    await this.ensureInputReady(page);
-    const { x, y, button = 'left', clicks = 1, delay = 50 } = opts;
-
-    // 移动鼠标到目标位置（模拟轨迹）
-    await page.mouse.move(x, y, { steps: 3 });
-
-    // 执行点击（支持多次、间隔随机抖动）
-    for (let i = 0; i < clicks; i++) {
-      if (i > 0) {
-        // 多次点击间隔 100-200ms
-        await new Promise(r => setTimeout(r, 100 + Math.random() * 100));
+    await this.withInputActionLock(async () => {
+      await this.runInputAction(page, 'input:ready', (activePage) => this.ensureInputReady(activePage));
+      const { x, y, button = 'left', clicks = 1, delay = 50 } = opts;
+
+      // Avoid page.mouse.click() composite hangs by using explicit down/up sequence.
+      for (let i = 0; i < clicks; i++) {
+        if (i > 0) {
+          // 多次点击间隔 100-200ms
+          await new Promise(r => setTimeout(r, 100 + Math.random() * 100));
+        }
+        await this.runInputAction(page, 'mouse:move(pre-click)', (activePage) => activePage.mouse.move(x, y, { steps: 1 }));
+        await this.runInputAction(page, 'mouse:down', (activePage) => activePage.mouse.down({
+          button,
+          clickCount: 1,
+        }));
+        if (delay > 0) {
+          await page.waitForTimeout(delay);
+        }
+        await this.runInputAction(page, 'mouse:up', (activePage) => activePage.mouse.up({
+          button,
+          clickCount: 1,
+        }));
       }
-      await page.mouse.click(x, y, {
-        button,
-        clickCount: 1,
-        delay // 按键间隔
-      });
-    }
+    });
   }
 
   /**
@@ -1225,10 +1379,11 @@ export class BrowserSession {
    */
   async mouseMove(opts: { x: number; y: number; steps?: number }): Promise<void> {
     const page = await this.ensurePrimaryPage();
-    await this.ensureInputReady(page);
-    const { x, y, steps = 3 } = opts;
-
-    await page.mouse.move(x, y, { steps });
+    await this.withInputActionLock(async () => {
+      await this.runInputAction(page, 'input:ready', (activePage) => this.ensureInputReady(activePage));
+      const { x, y, steps = 3 } = opts;
+      await this.runInputAction(page, 'mouse:move', (activePage) => activePage.mouse.move(x, y, { steps }));
+    });
   }
 
   /**
@@ -1236,23 +1391,27 @@ export class BrowserSession {
    */
   async keyboardType(opts: { text: string; delay?: number; submit?: boolean }): Promise<void> {
     const page = await this.ensurePrimaryPage();
-    await this.ensureInputReady(page);
-    const { text, delay = 80, submit } = opts;
+    await this.withInputActionLock(async () => {
+      await this.runInputAction(page, 'input:ready', (activePage) => this.ensureInputReady(activePage));
+      const { text, delay = 80, submit } = opts;
 
-    if (text && text.length > 0) {
-      await page.keyboard.type(text, { delay });
-    }
+      if (text && text.length > 0) {
+        await this.runInputAction(page, 'keyboard:type', (activePage) => activePage.keyboard.type(text, { delay }));
+      }
 
-    if (submit) {
-      await page.keyboard.press('Enter');
-    }
+      if (submit) {
+        await this.runInputAction(page, 'keyboard:press', (activePage) => activePage.keyboard.press('Enter'));
+      }
+    });
   }
 
   async keyboardPress(opts: { key: string; delay?: number }): Promise<void> {
     const page = await this.ensurePrimaryPage();
-    await this.ensureInputReady(page);
-    const { key, delay } = opts;
-    await page.keyboard.press(key, typeof delay === 'number' ? { delay } : undefined);
+    await this.withInputActionLock(async () => {
+      await this.runInputAction(page, 'input:ready', (activePage) => this.ensureInputReady(activePage));
+      const { key, delay } = opts;
+      await this.runInputAction(page, 'keyboard:press', (activePage) => activePage.keyboard.press(key, typeof delay === 'number' ? { delay } : undefined));
+    });
   }
 
   /**
@@ -1261,9 +1420,11 @@ export class BrowserSession {
    */
   async mouseWheel(opts: { deltaY: number; deltaX?: number }): Promise<void> {
     const page = await this.ensurePrimaryPage();
-    await this.ensureInputReady(page);
-    const { deltaX = 0, deltaY } = opts;
-    await page.mouse.wheel(Number(deltaX) || 0, Number(deltaY) || 0);
+    await this.withInputActionLock(async () => {
+      await this.runInputAction(page, 'input:ready', (activePage) => this.ensureInputReady(activePage));
+      const { deltaX = 0, deltaY } = opts;
+      await this.runInputAction(page, 'mouse:wheel', (activePage) => activePage.mouse.wheel(Number(deltaX) || 0, Number(deltaY) || 0));
+    });
   }
 
   private async syncWindowBounds(
@@ -1384,6 +1545,16 @@ export class BrowserSession {
     if (!width || !height) {
       throw new Error('invalid_viewport_size');
     }
+    if (this.followWindowViewport && !this.options.headless) {
+      await page.evaluate(({ w, h }) => {
+        try { window.resizeTo(w, h); } catch {}
+      }, { w: width, h: height });
+      await page.waitForTimeout(150);
+      await this.refreshViewportFromWindow(page).catch(() => {});
+      const next = this.lastViewport || { width, height };
+      await this.maybeCenterWindow(page, next).catch(() => {});
+      return next;
+    }
     await page.setViewportSize({ width, height });
     await this.syncWindowBounds(page, { width, height });
     await this.syncDeviceScaleFactor(page, { width, height });

package/modules/camo-backend/src/internal/engine-manager.ts

@@ -176,17 +176,13 @@ export async function launchEngineContext(opts: EngineLaunchOptions): Promise<Br
     const workW = Number(dm?.workWidth || physicalW || 4096);
     const workH = Number(dm?.workHeight || physicalH || 2190);
     
-    // Use provided viewport as MAXIMUM (e.g., from fingerprint or explicit opt), default to full work area
-    const maxViewportW = Number(opts.viewport?.width || workW);
-    const maxViewportH = Number(opts.viewport?.height || workH);
-    
-    // Target: fill work area, but don't exceed explicit viewport caps if provided
-    const targetW = maxViewportW > 0 ? Math.min(maxViewportW, workW) : workW;
-    const targetH = maxViewportH > 0 ? Math.min(maxViewportH, workH) : workH;
-
-    // Use targetW/targetH as viewport (even in headless) to match headful size
-    const viewportW = Math.max(1440, Math.floor(Number(targetW) || 4096));
-    const viewportH = Math.max(900, Math.floor(Number(targetH) || 2190));
+    // Base viewport target:
+    // - prefer explicit/fingerprint viewport if provided
+    // - otherwise use a deterministic default for stable first-run UX
+    const requestedW = Number(opts.viewport?.width || process.env.WEBAUTO_VIEWPORT_WIDTH || 1440);
+    const requestedH = Number(opts.viewport?.height || process.env.WEBAUTO_VIEWPORT_HEIGHT || 1100);
+    const viewportW = Math.max(900, Math.floor(Number(requestedW) || 1440));
+    const viewportH = Math.max(700, Math.floor(Number(requestedH) || 1100));
 
     const envHeadlessW = Number(process.env.WEBAUTO_HEADLESS_WIDTH || 0);
     const envHeadlessH = Number(process.env.WEBAUTO_HEADLESS_HEIGHT || 0);
@@ -198,9 +194,12 @@ export async function launchEngineContext(opts: EngineLaunchOptions): Promise<Br
     
     const headless = Boolean(opts.headless);
 
-    // Final window size: maximize to fill work area (leave small margin for chrome/window decorations)
-    const winW = headless ? headlessW : Math.max(1440, Math.floor(workW * 0.95));
-    const winH = headless ? headlessH : Math.max(900, Math.floor(workH - 80));
+    // Final headful window size:
+    // align window with viewport by default and keep it inside available work area.
+    const maxHeadfulW = workW > 0 ? Math.max(900, workW - 40) : 1920;
+    const maxHeadfulH = workH > 0 ? Math.max(700, workH - 80) : 1200;
+    const winW = headless ? headlessW : Math.min(viewportW, maxHeadfulW);
+    const winH = headless ? headlessH : Math.min(viewportH, maxHeadfulH);
     
     // Ensure integer types for Camoufox
     const screenW = Math.floor(physicalW) | 0;
@@ -247,7 +246,7 @@ export async function launchEngineContext(opts: EngineLaunchOptions): Promise<Br
       headless,
       os: targetOS,
       window: [intWinW, intWinH],
-      viewport: { width: headless ? headlessW : viewportW, height: headless ? headlessH : viewportH },
+      viewport: headless ? { width: headlessW, height: headlessH } : null,
       firefox_user_prefs,
       config,
       data_dir: opts.profileDir,

package/modules/camo-backend/src/internal/ws-server.ts

@@ -40,6 +40,19 @@ function appendLog(target: string, event: string, payload: Record<string, any> =
 const appendDomPickerLog = (event: string, payload: Record<string, any> = {}) => appendLog(domPickerLogPath, event, payload);
 const appendHighlightLog = (event: string, payload: Record<string, any> = {}) => appendLog(highlightLogPath, event, payload);
 
+function legacySelectorActionDisabled(source: string, action: 'click' | 'type') {
+  return {
+    success: false,
+    code: 'LEGACY_ACTION_DISABLED',
+    error: `[${source}] legacy selector action "${action}" is disabled; use mouse:* and keyboard:* protocol actions instead`,
+    data: {
+      source,
+      action,
+      replacements: ['mouse:move', 'mouse:click', 'mouse:wheel', 'keyboard:press', 'keyboard:type'],
+    },
+  };
+}
+
 export class BrowserWsServer {
   private wss?: WebSocketServer;
   private matcher = new ContainerMatcher();
@@ -687,10 +700,10 @@ export class BrowserWsServer {
     const op = parameters.operation_type;
     if (!op) throw new Error('operation_type required');
    if (op === 'click') {
-     return this.handleNodeExecute(sessionId, { command_type: 'node_execute', node_type: 'click', parameters: parameters.target || parameters });
+     return legacySelectorActionDisabled('user_action.operation', 'click');
    }
    if (op === 'type') {
-     return this.handleNodeExecute(sessionId, { command_type: 'node_execute', node_type: 'type', parameters: parameters.target || parameters });
+     return legacySelectorActionDisabled('user_action.operation', 'type');
    }
    if (op === 'scroll') {
      const session = this.options.sessionManager.getSession(sessionId);
@@ -1000,23 +1013,10 @@ export class BrowserWsServer {
         };
       }
       case 'click': {
-        const selector = parameters.selector;
-        if (!selector) throw new Error('Click node requires selector');
-        await session.click(selector);
-        return {
-          success: true,
-          data: { action: 'clicked', selector },
-        };
+        return legacySelectorActionDisabled('node_execute', 'click');
       }
       case 'type': {
-        const selector = parameters.selector;
-        if (!selector) throw new Error('Type node requires selector');
-        const text = parameters.text ?? parameters.value ?? '';
-        await session.fill(selector, String(text));
-        return {
-          success: true,
-          data: { action: 'typed', selector, text },
-        };
+        return legacySelectorActionDisabled('node_execute', 'type');
       }
       case 'screenshot': {
         const filename = parameters.filename || `screenshot_${Date.now()}.png`;

package/modules/camo-runtime/src/autoscript/action-providers/xhs/common.mjs

@@ -1,4 +1,5 @@
 import { callAPI } from '../../../utils/browser-service.mjs';
+import { assertNoForbiddenJsAction } from '../../../utils/js-policy.mjs';
 
 export function withOperationHighlight(script, color = '#ff7a00') {
   return `(() => {
@@ -37,8 +38,17 @@ export function withOperationHighlight(script, color = '#ff7a00') {
   })()`;
 }
 
-export async function runEvaluateScript({ profileId, script, highlight = true }) {
-  const wrappedScript = highlight ? withOperationHighlight(script) : script;
+export async function runEvaluateScript({
+  profileId,
+  script,
+  highlight = true,
+  allowUnsafeJs = false,
+}) {
+  const sourceScript = String(script || '');
+  if (!allowUnsafeJs) {
+    assertNoForbiddenJsAction(sourceScript, 'xhs provider evaluate');
+  }
+  const wrappedScript = highlight && allowUnsafeJs ? withOperationHighlight(sourceScript) : sourceScript;
   return callAPI('evaluate', { profileId, script: wrappedScript });
 }
 

package/modules/camo-runtime/src/autoscript/action-providers/xhs/persistence.mjs

@@ -39,6 +39,7 @@ export function resolveXhsOutputContext({
     noteId: note,
     keywordDir,
     noteDir,
+    linksPath: path.join(keywordDir, 'links.collected.jsonl'),
     commentsPath: path.join(noteDir, 'comments.jsonl'),
     likeStatePath: path.join(keywordDir, '.like-state.jsonl'),
     likeEvidenceDir: path.join(keywordDir, 'like-evidence', note),
@@ -93,6 +94,38 @@ function commentDedupKey(row) {
   return `${String(row?.userId || '')}:${String(row?.content || '')}`;
 }
 
+function readXsecToken(url) {
+  const href = String(url || '').trim();
+  if (!href) return '';
+  try {
+    const parsed = new URL(href);
+    return String(parsed.searchParams.get('xsec_token') || '').trim();
+  } catch {
+    return '';
+  }
+}
+
+function normalizeLinkRow(row) {
+  const noteId = String(row?.noteId || '').trim();
+  const noteUrl = String(row?.noteUrl || row?.url || '').trim();
+  const listUrl = String(row?.listUrl || '').trim();
+  const xsecToken = String(row?.xsecToken || readXsecToken(noteUrl)).trim();
+  return {
+    noteId,
+    noteUrl,
+    listUrl,
+    xsecToken,
+    ts: new Date().toISOString(),
+  };
+}
+
+function linkDedupKey(row) {
+  const noteId = String(row?.noteId || '').trim();
+  if (noteId) return `note:${noteId}`;
+  const noteUrl = String(row?.noteUrl || '').trim();
+  return noteUrl ? `url:${noteUrl}` : '';
+}
+
 export async function mergeCommentsJsonl({ filePath, noteId, comments = [] }) {
   const existing = await readJsonlRows(filePath);
   const seen = new Set(
@@ -122,6 +155,30 @@ export async function mergeCommentsJsonl({ filePath, noteId, comments = [] }) {
   };
 }
 
+export async function mergeLinksJsonl({ filePath, links = [] }) {
+  const existing = await readJsonlRows(filePath);
+  const seen = new Set(existing.map((row) => linkDedupKey(row)).filter(Boolean));
+
+  const added = [];
+  for (const row of links) {
+    const normalized = normalizeLinkRow(row);
+    if (!normalized.noteUrl || !normalized.xsecToken) continue;
+    const key = linkDedupKey(normalized);
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    added.push(normalized);
+  }
+
+  await appendJsonlRows(filePath, added);
+  return {
+    filePath,
+    added: added.length,
+    existing: existing.length,
+    total: existing.length + added.length,
+    rowsAdded: added,
+  };
+}
+
 export function makeLikeSignature({ noteId, userId = '', userName = '', text = '' }) {
   const normalizedText = String(text || '').replace(/\s+/g, ' ').trim().slice(0, 200);
   return [