@sovovs/bycli 2.1.24 → 2.1.25

package/cli-manifest.json

@@ -27869,7 +27869,7 @@
         "name": "name",
         "type": "str",
         "required": false,
-        "help": "Optional official-account name for display context"
+        "help": "Official-account name; exact case-insensitive match required for browser Sogou fallback"
       },
       {
         "name": "limit",
@@ -27900,7 +27900,9 @@
       "author",
       "digest",
       "publishedAt",
-      "url"
+      "url",
+      "source",
+      "coverage"
     ],
     "type": "js",
     "modulePath": "weixin/articles.js",
@@ -28264,7 +28266,7 @@
         "name": "name",
         "type": "str",
         "required": false,
-        "help": "Official-account name used in Markdown metadata"
+        "help": "Official-account name; exact case-insensitive match required for browser Sogou fallback"
       },
       {
         "name": "output",
@@ -28303,7 +28305,9 @@
       "stage",
       "path",
       "error",
-      "url"
+      "url",
+      "source",
+      "coverage"
     ],
     "type": "js",
     "modulePath": "weixin/save-articles.js",

package/clis/weixin/_wechat/article-fallback-policy.js

@@ -0,0 +1,46 @@
+import {
+  AuthRequiredError, CommandExecutionError, EmptyResultError,
+} from '@sovovs/bycli/errors';
+import { buildSecretSet, redactText } from './redact.js';
+
+function safePhase(error, secrets) {
+  const message = error instanceof Error ? error.message : String(error);
+  const hint = error && typeof error === 'object' && typeof error.hint === 'string'
+    ? error.hint : '';
+  const summary = hint ? `${message} (${hint})` : message;
+  return {
+    code: error && typeof error === 'object' && typeof error.code === 'string'
+      ? error.code : 'UNKNOWN',
+    summary: redactText(summary, secrets),
+  };
+}
+
+export function isEligibleArticleFallbackError(error) {
+  return error instanceof CommandExecutionError || error instanceof EmptyResultError;
+}
+
+export function withMissingFallbackName(operation, error) {
+  const hint = `${error.hint ? `${error.hint} ` : ''}Sogou fallback requires the exact official-account name in --name.`;
+  if (error instanceof EmptyResultError) return new EmptyResultError(operation, hint);
+  return new CommandExecutionError(error.message, hint);
+}
+
+export function combineArticleFallbackErrors({
+  operation,
+  primaryError,
+  fallbackError,
+  credentials,
+}) {
+  if (fallbackError instanceof AuthRequiredError) return fallbackError;
+  const secrets = buildSecretSet(credentials);
+  const primary = safePhase(primaryError, secrets);
+  const fallback = safePhase(fallbackError, secrets);
+  const hint = `Primary (${primary.code}): ${primary.summary}; fallback (${fallback.code}): ${fallback.summary}`;
+  if (primaryError instanceof EmptyResultError && fallbackError instanceof EmptyResultError) {
+    return new EmptyResultError(operation, hint);
+  }
+  return new CommandExecutionError(
+    'Weixin article index and Sogou fallback both failed',
+    hint,
+  );
+}

package/clis/weixin/_wechat/article-index.js

@@ -105,6 +105,14 @@ function buildReferer(token) {
   return `https://${DOMAIN}/cgi-bin/appmsg?${params}`;
 }
 
+function isWechatVerificationResponse(message, hint) {
+  const text = `${message}\n${hint ?? ''}`;
+  return /mp\/wappoc_appmsgcaptcha/i.test(text)
+    || /secitptpage\/verify\.html/i.test(text)
+    || /id=["']js_verify["']/i.test(text)
+    || (/环境异常/.test(text) && /(完成验证后即可继续访问|去验证)/.test(text));
+}
+
 function transportError(error, credentials) {
   const secrets = buildSecretSet(credentials);
   const message = error instanceof Error ? error.message : String(error);
@@ -114,6 +122,12 @@ function transportError(error, credentials) {
   const redactedHint = hint ? redactText(hint, secrets) : undefined;
   if (error instanceof AuthRequiredError && error.domain === DOMAIN
     && redactedMessage === message && redactedHint === hint) return error;
+  if (isWechatVerificationResponse(redactedMessage, redactedHint)) {
+    return new AuthRequiredError(
+      DOMAIN,
+      'WeChat article index requires environment verification. Complete it in the open browser tab and run the command again.',
+    );
+  }
   return new CommandExecutionError(
     `WeChat appmsgpublish request failed: ${redactedMessage}`,
     redactedHint,

package/clis/weixin/_wechat/article-link.js

@@ -0,0 +1,88 @@
+import { ArgumentError, AuthRequiredError, CommandExecutionError } from '@sovovs/bycli/errors';
+
+export function normalizeWechatUrl(raw) {
+  let value = String(raw ?? '').trim();
+  if (!value) return value;
+  if ((value.startsWith('"') && value.endsWith('"'))
+      || (value.startsWith("'") && value.endsWith("'"))) {
+    value = value.slice(1, -1).trim();
+  }
+  if (value.startsWith('<') && value.endsWith('>')) {
+    value = value.slice(1, -1).trim();
+  }
+  value = value.replace(/\\+([:/&?=#%])/g, '$1');
+  value = value.replace(/&amp;/g, '&').replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>').replace(/&quot;/g, '"');
+  if (value.startsWith('mp.weixin.qq.com/') || value.startsWith('//mp.weixin.qq.com/')) {
+    value = `https://${value.replace(/^\/+/, '')}`;
+  }
+  try {
+    const parsed = new URL(value);
+    if (['http:', 'https:'].includes(parsed.protocol)
+        && parsed.hostname.toLowerCase() === 'mp.weixin.qq.com') {
+      parsed.protocol = 'https:';
+      value = parsed.toString();
+    }
+  } catch {
+    // Trust validation below reports malformed URLs.
+  }
+  return value;
+}
+
+function isStrictHttpsUrl(raw, hostname, pathname) {
+  try {
+    const url = new URL(raw);
+    return url.protocol === 'https:' && url.hostname === hostname
+      && url.port === '' && url.username === '' && url.password === ''
+      && pathname(url.pathname);
+  } catch {
+    return false;
+  }
+}
+
+export function isTrustedWechatArticleUrl(raw) {
+  return isStrictHttpsUrl(raw, 'mp.weixin.qq.com', path => path === '/s' || path.startsWith('/s/'));
+}
+
+export function isTrustedSogouRedirectUrl(raw) {
+  return isStrictHttpsUrl(raw, 'weixin.sogou.com', path => path === '/link');
+}
+
+export async function resolveWechatArticleUrl(page, rawUrl) {
+  const sourceUrl = normalizeWechatUrl(rawUrl);
+  if (isTrustedWechatArticleUrl(sourceUrl)) {
+    return { sourceUrl, resolvedUrl: sourceUrl, alreadyNavigated: false };
+  }
+  if (!isTrustedSogouRedirectUrl(sourceUrl)) {
+    throw new ArgumentError(
+      'A trusted WeChat article or Sogou Weixin result URL is required.',
+      'Pass an https://mp.weixin.qq.com/s/... or https://weixin.sogou.com/link?... URL.',
+    );
+  }
+  try {
+    await page.goto(sourceUrl);
+    await page.wait(2);
+    const result = await page.evaluate(`(() => ({
+      finalUrl: window.location.href,
+      pageText: document.body ? document.body.innerText : '',
+      html: document.documentElement ? document.documentElement.innerHTML : '',
+    }))()`);
+    const text = `${result?.pageText || ''} ${result?.html || ''}`;
+    if (/验证码|安全验证|异常访问|访问过于频繁|请输入验证码/.test(text)) {
+      throw new AuthRequiredError(
+        'weixin.sogou.com',
+        'Sogou Weixin requires verification. Complete it in the open browser tab and run the command again.',
+      );
+    }
+    if (!isTrustedWechatArticleUrl(result?.finalUrl)) {
+      throw new CommandExecutionError(
+        'Sogou Weixin did not resolve to a trusted WeChat article URL',
+        'Open the search result in a browser and confirm it redirects to mp.weixin.qq.com/s/... before retrying.',
+      );
+    }
+    return { sourceUrl, resolvedUrl: new URL(result.finalUrl).href, alreadyNavigated: true };
+  } catch (error) {
+    if (error instanceof AuthRequiredError || error instanceof CommandExecutionError) throw error;
+    throw new CommandExecutionError('Failed to resolve the Sogou Weixin result URL');
+  }
+}

package/clis/weixin/_wechat/publish-records.js

@@ -69,6 +69,7 @@ function routePart(value) {
 
 function decodePublishInfo(value) {
   const decoded = parseJson(value, 'publish_info');
+  if (Array.isArray(decoded.appmsg_info)) return decoded;
   if (!Object.prototype.hasOwnProperty.call(decoded, 'publish_info')) return decoded;
   const nested = decoded.publish_info;
   if (typeof nested === 'string') return parseJson(nested, 'nested publish_info');
@@ -86,7 +87,7 @@ function parseEntry(info, article) {
   if (msgid === null || itemIdx === null) {
     throw commandError('returned an article without a detail route');
   }
-  const publishedAt = dateInShanghai(info?.sent_info?.time);
+  const publishedAt = dateInShanghai(info?.sent_info?.time ?? info?.publish_info?.create_time);
   return {
     title,
     publishedAt,
@@ -249,6 +250,18 @@ function normalizeArticleUrl(value) {
   return url.href;
 }
 
+export function validatePublishedQuery(value) {
+  const text = normalizeTitle(value);
+  if (!text) throw new ArgumentError('query must not be empty');
+  const parsed = parseAbsoluteUrl(text);
+  if (!parsed) return text;
+  const trustedPath = parsed.pathname === '/s' || parsed.pathname.startsWith('/s/');
+  if (!normalizeArticleUrl(text) || !trustedPath) {
+    throw new ArgumentError('query URL must be a trusted WeChat article URL');
+  }
+  return text;
+}
+
 function ambiguityError(matches) {
   const choices = matches.slice(0, 5)
     .map(record => `${record.publishedAt ?? record.publishDate} ${record.title} ${record.url}`)
@@ -280,8 +293,6 @@ export function matchPublishedRecord(records, query, date) {
   } else {
     const exact = uniqueMatch(candidates.filter(record => normalizeTitle(record.title) === text));
     if (exact) return exact;
-    const substring = uniqueMatch(candidates.filter(record => normalizeTitle(record.title).includes(text)));
-    if (substring) return substring;
   }
 
   throw new EmptyResultError(

package/clis/weixin/_wechat/sogou-fallback.js

@@ -0,0 +1,223 @@
+import {
+  ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError,
+} from '@sovovs/bycli/errors';
+import { resolveWechatArticleUrl } from './article-link.js';
+import { redactText } from './redact.js';
+import {
+  DEFAULT_SOGOU_MAX_PAGES,
+  normalizePositiveInteger,
+  searchSogouArticlePage,
+} from './sogou-search.js';
+
+const CST_OFFSET_MS = 8 * 60 * 60 * 1000;
+
+export function isExactAccountName(actual, expected) {
+  const normalizedActual = String(actual ?? '').trim().toLowerCase();
+  const normalizedExpected = String(expected ?? '').trim().toLowerCase();
+  return normalizedExpected.length > 0 && normalizedActual === normalizedExpected;
+}
+
+function normalizedUrl(raw) {
+  try {
+    return new URL(raw).href;
+  } catch {
+    return String(raw ?? '').trim();
+  }
+}
+
+function comparableTimestamp(raw) {
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value <= 0) return null;
+  return value >= 1_000_000_000_000 ? Math.floor(value / 1000) : value;
+}
+
+function validCstEpochSeconds(year, month, day, hour, minute, second) {
+  const epochMs = Date.UTC(year, month - 1, day, hour, minute, second) - CST_OFFSET_MS;
+  const check = new Date(epochMs + CST_OFFSET_MS);
+  if (check.getUTCFullYear() !== year || check.getUTCMonth() !== month - 1
+      || check.getUTCDate() !== day || check.getUTCHours() !== hour
+      || check.getUTCMinutes() !== minute || check.getUTCSeconds() !== second) return null;
+  return Math.floor(epochMs / 1000);
+}
+
+export function normalizeSogouPublishTimestamp({
+  publishTimestamp,
+  publishTime,
+  scanStartedAt,
+}) {
+  const raw = comparableTimestamp(publishTimestamp);
+  if (raw !== null) return Math.floor(raw);
+  const startMs = Number(scanStartedAt);
+  if (!Number.isFinite(startMs)) return null;
+  const text = String(publishTime ?? '').trim();
+
+  const relative = text.match(/^(\d+)(分钟|小时|天)前$/);
+  if (relative) {
+    const amount = Number(relative[1]);
+    const secondsPerUnit = { 分钟: 60, 小时: 3600, 天: 86400 }[relative[2]];
+    if (!Number.isSafeInteger(amount)) return null;
+    const timestamp = Math.floor(startMs / 1000) - amount * secondsPerUnit;
+    return Number.isSafeInteger(timestamp) && timestamp > 0 ? timestamp : null;
+  }
+
+  const dayWord = text.match(/^(昨天|前天)(?:\s+(\d{1,2}):(\d{2})(?::(\d{2}))?)?$/);
+  if (dayWord) {
+    const cstNow = new Date(startMs + CST_OFFSET_MS);
+    const dayOffset = dayWord[1] === '昨天' ? 1 : 2;
+    const clock = dayWord[2] === undefined
+      ? [cstNow.getUTCHours(), cstNow.getUTCMinutes(), cstNow.getUTCSeconds()]
+      : [Number(dayWord[2]), Number(dayWord[3]), Number(dayWord[4] ?? 0)];
+    const prior = new Date(Date.UTC(
+      cstNow.getUTCFullYear(), cstNow.getUTCMonth(), cstNow.getUTCDate() - dayOffset,
+    ));
+    return validCstEpochSeconds(
+      prior.getUTCFullYear(), prior.getUTCMonth() + 1, prior.getUTCDate(), ...clock,
+    );
+  }
+
+  const absolute = text.match(
+    /^(\d{4})(?:-(\d{1,2})-(\d{1,2})|\/(\d{1,2})\/(\d{1,2})|年(\d{1,2})月(\d{1,2})日)(?:\s+(\d{1,2}):(\d{2})(?::(\d{2}))?)?$/,
+  );
+  if (!absolute) return null;
+  const month = Number(absolute[2] ?? absolute[4] ?? absolute[6]);
+  const day = Number(absolute[3] ?? absolute[5] ?? absolute[7]);
+  return validCstEpochSeconds(
+    Number(absolute[1]), month, day,
+    Number(absolute[8] ?? 0), Number(absolute[9] ?? 0), Number(absolute[10] ?? 0),
+  );
+}
+
+function safeResolutionError(error) {
+  const message = error instanceof Error ? error.message : 'Sogou article link resolution failed';
+  return redactText(message, []) || 'Sogou article link resolution failed';
+}
+
+export async function collectSogouAccountArticles({
+  page,
+  accountName,
+  limit,
+  maxPages,
+  searchPage = searchSogouArticlePage,
+  resolveUrl = resolveWechatArticleUrl,
+  resolutionPolicy = 'atomic',
+  scanStartedAt = Date.now(),
+}) {
+  const normalizedName = String(accountName ?? '').trim();
+  if (!normalizedName) {
+    throw new ArgumentError(
+      'weixin Sogou fallback requires --name',
+      'Pass the exact official-account name with --name.',
+    );
+  }
+  if (!['atomic', 'rows'].includes(resolutionPolicy)) {
+    throw new ArgumentError('Invalid Sogou fallback resolution policy');
+  }
+  const pageLimit = normalizePositiveInteger(
+    maxPages,
+    'max-pages',
+    DEFAULT_SOGOU_MAX_PAGES,
+  );
+  const articleLimit = limit === undefined || limit === null
+    ? null : normalizePositiveInteger(limit, 'limit');
+  const seenFingerprints = new Set();
+  const seenSogouUrls = new Set();
+  const candidates = [];
+  let pagesScanned = 0;
+  let coverage = 'max-pages-reached';
+  let firstSeen = 0;
+
+  for (let pageNo = 1; pageNo <= pageLimit; pageNo += 1) {
+    const result = await searchPage(page, { query: normalizedName, pageNo });
+    pagesScanned += 1;
+    if (result.state === 'empty') {
+      coverage = 'search-exhausted';
+      break;
+    }
+    if (seenFingerprints.has(result.fingerprint)) {
+      throw new CommandExecutionError(
+        'Sogou Weixin repeated a result page while scanning account articles',
+        `Page ${pageNo} repeated an earlier page; refusing to return a partial article index.`,
+      );
+    }
+    seenFingerprints.add(result.fingerprint);
+    for (const item of result.rows) {
+      if (!isExactAccountName(item.account, normalizedName)) continue;
+      const sourceKey = normalizedUrl(item.url);
+      if (seenSogouUrls.has(sourceKey)) continue;
+      seenSogouUrls.add(sourceKey);
+      candidates.push({
+        ...item,
+        firstSeen,
+        sourceKey,
+        normalizedTimestamp: normalizeSogouPublishTimestamp({
+          publishTimestamp: item.publishTimestamp,
+          publishTime: item.publishTime,
+          scanStartedAt,
+        }),
+      });
+      firstSeen += 1;
+    }
+  }
+
+  if (candidates.length === 0) {
+    const coverageHint = coverage === 'max-pages-reached'
+      ? `Scanned ${pagesScanned} pages and reached the page cap; later pages may still contain a match.`
+      : `Sogou search exhausted after ${pagesScanned} pages.`;
+    throw new EmptyResultError(
+      'weixin Sogou account fallback',
+      `No Sogou articles matched the exact official-account name "${normalizedName}"; similarly named accounts were excluded. ${coverageHint}`,
+    );
+  }
+
+  candidates.sort((left, right) => {
+    const leftTime = left.normalizedTimestamp;
+    const rightTime = right.normalizedTimestamp;
+    if (leftTime !== null && rightTime !== null && leftTime !== rightTime) return rightTime - leftTime;
+    if (leftTime !== null && rightTime === null) return -1;
+    if (leftTime === null && rightTime !== null) return 1;
+    return left.firstSeen - right.firstSeen;
+  });
+
+  const seenResolvedUrls = new Set();
+  const articles = [];
+  const resolutionFailures = [];
+  let terminalCount = 0;
+  for (const candidate of candidates) {
+    if (articleLimit !== null && terminalCount >= articleLimit) break;
+    try {
+      const resolved = await resolveUrl(page, candidate.url);
+      const resolvedKey = normalizedUrl(resolved.resolvedUrl);
+      if (seenResolvedUrls.has(resolvedKey)) continue;
+      seenResolvedUrls.add(resolvedKey);
+      articles.push({
+        title: candidate.title,
+        author: null,
+        digest: candidate.summary || null,
+        publishedAt: candidate.publishTime || null,
+        url: resolved.resolvedUrl,
+        sourceUrl: resolved.sourceUrl,
+        order: terminalCount,
+      });
+      terminalCount += 1;
+    } catch (error) {
+      if (error instanceof AuthRequiredError || resolutionPolicy === 'atomic') throw error;
+      resolutionFailures.push({
+        title: candidate.title,
+        status: 'failed',
+        stage: 'resolve',
+        error: safeResolutionError(error),
+        url: candidate.url,
+        order: terminalCount,
+      });
+      terminalCount += 1;
+    }
+  }
+
+  return {
+    source: 'sogou',
+    coverage,
+    pagesScanned,
+    articles,
+    resolutionFailures,
+  };
+}

package/clis/weixin/_wechat/sogou-search.js

@@ -0,0 +1,143 @@
+import {
+  ArgumentError, AuthRequiredError, CommandExecutionError,
+} from '@sovovs/bycli/errors';
+
+const SOGOU_WEIXIN_DOMAIN = 'weixin.sogou.com';
+export const DEFAULT_SOGOU_MAX_PAGES = 50;
+
+export function normalizePositiveInteger(value, name, defaultValue, maxValue) {
+  if (value === undefined || value === null) return defaultValue;
+  const text = String(value).trim();
+  if (!/^\d+$/.test(text)) {
+    throw new ArgumentError(
+      `weixin sougousearch --${name} must be a positive integer`,
+      `Pass --${name} as a whole number${maxValue ? ` from 1 to ${maxValue}` : ' greater than 0'}.`,
+    );
+  }
+  const parsed = Number(text);
+  if (!Number.isSafeInteger(parsed) || parsed < 1 || (maxValue && parsed > maxValue)) {
+    throw new ArgumentError(
+      `weixin sougousearch --${name} is out of range`,
+      `Pass --${name} as a whole number${maxValue ? ` from 1 to ${maxValue}` : ' greater than 0'}.`,
+    );
+  }
+  return parsed;
+}
+
+export function buildSogouSearchUrl(query, pageNo) {
+  const searchUrl = new URL('https://weixin.sogou.com/weixin');
+  searchUrl.searchParams.set('query', query);
+  searchUrl.searchParams.set('type', '2');
+  searchUrl.searchParams.set('page', String(pageNo));
+  searchUrl.searchParams.set('ie', 'utf8');
+  return searchUrl.toString();
+}
+
+export function buildExtractSogouSearchResultsEvaluate() {
+  return String.raw`(() => {
+    const clean = (value) => {
+      return (value || '')
+        .replace(/\s+/g, ' ')
+        .replace(/<!--red_beg-->|<!--red_end-->/g, '')
+        .replace(/document\.write\(timeConvert\(['"]\d+['"]\)\)/g, '')
+        .trim();
+    };
+
+    const absolutize = (href) => {
+      if (!href) return '';
+      try {
+        return new URL(href, window.location.origin).toString();
+      } catch {
+        return href;
+      }
+    };
+
+    const bodyText = clean(document.body && document.body.innerText);
+    const blocked = /验证码|安全验证|异常访问|访问过于频繁|请输入验证码/.test(bodyText);
+    const empty = /没有找到相关的微信文章|未找到相关|暂无相关|没有找到/.test(bodyText)
+      || Boolean(document.querySelector('.no-result, .no_result, .s-noresult'));
+    const cards = Array.from(document.querySelectorAll('.news-list li'));
+    const extracted = cards.map((item) => {
+      const linkEl = item.querySelector('h3 a[href]');
+      const summaryEl = item.querySelector('p.txt-info');
+      const accountEl = item.querySelector('.s-p .all-time-y2');
+      const timeEl = item.querySelector('.s-p .s2');
+      const rawTimeHtml = timeEl && timeEl.innerHTML || '';
+      const timestampMatch = rawTimeHtml.match(/timeConvert\(['"](\d{10,13})['"]\)/);
+      return {
+        title: clean(linkEl && linkEl.textContent),
+        account: clean(accountEl && accountEl.textContent),
+        url: absolutize(linkEl && linkEl.getAttribute('href')),
+        summary: clean(summaryEl && summaryEl.textContent),
+        publishTime: clean(timeEl && timeEl.textContent),
+        publishTimestamp: timestampMatch ? Number(timestampMatch[1]) : null,
+      };
+    });
+    const rows = extracted.filter((row) => row.title && row.url);
+
+    return {
+      blocked,
+      empty,
+      invalidCount: extracted.length - rows.length,
+      rows,
+    };
+  })()`;
+}
+
+function fingerprintRows(rows) {
+  return rows.map(row => `${row.title}\u0000${row.url}`).join('\u0001');
+}
+
+export async function searchSogouArticlePage(page, { query, pageNo }) {
+  const normalizedQuery = String(query ?? '').trim();
+  if (!normalizedQuery) {
+    throw new ArgumentError(
+      'A search query is required.',
+      'Pass a non-empty keyword to search Weixin articles via Sogou.',
+    );
+  }
+  const normalizedPage = normalizePositiveInteger(pageNo, 'page', 1);
+  const searchUrl = buildSogouSearchUrl(normalizedQuery, normalizedPage);
+  let payload;
+  try {
+    await page.goto(searchUrl);
+    await page.wait(2);
+    payload = await page.evaluate(buildExtractSogouSearchResultsEvaluate());
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new CommandExecutionError('weixin sougousearch failed while loading Sogou results', detail);
+  }
+  if (!payload || typeof payload !== 'object' || !Array.isArray(payload.rows)) {
+    throw new CommandExecutionError(
+      'weixin sougousearch returned an unreadable browser payload',
+      'Sogou Weixin may have changed its result page structure.',
+    );
+  }
+  if (payload.blocked) {
+    throw new AuthRequiredError(
+      SOGOU_WEIXIN_DOMAIN,
+      'Sogou Weixin requires verification. Complete it in the open browser tab and run the command again.',
+    );
+  }
+  if (payload.invalidCount > 0) {
+    throw new CommandExecutionError(
+      'Sogou Weixin returned article cards without required title or URL',
+      'The result page structure may have changed; refusing to return a partial result set.',
+    );
+  }
+  if (payload.rows.length === 0 && payload.empty) {
+    return { state: 'empty', page: normalizedPage, fingerprint: '', rows: [] };
+  }
+  if (payload.rows.length === 0) {
+    throw new CommandExecutionError(
+      'weixin sougousearch did not expose article result cards',
+      'Sogou Weixin may have changed its selectors or returned a transient shell page.',
+    );
+  }
+  return {
+    state: 'results',
+    page: normalizedPage,
+    fingerprint: fingerprintRows(payload.rows),
+    rows: payload.rows,
+  };
+}

package/clis/weixin/articles.js

@@ -1,9 +1,15 @@
 import { ArgumentError, EmptyResultError } from '@sovovs/bycli/errors';
 import { cli, Strategy } from '@sovovs/bycli/registry';
 import { readEnvironmentCredentials, resolveBrowserCredentials } from './_wechat/auth-session.js';
+import {
+  combineArticleFallbackErrors,
+  isEligibleArticleFallbackError,
+  withMissingFallbackName,
+} from './_wechat/article-fallback-policy.js';
 import { createArticleIndexFetcher } from './_wechat/article-index.js';
 import { callCrawler, collectArticles } from './_wechat/crawler-runtime.js';
 import { readAuthSource } from './_wechat/args.js';
+import { collectSogouAccountArticles } from './_wechat/sogou-fallback.js';
 
 const DOMAIN = 'mp.weixin.qq.com';
 const browserRequired = args => readAuthSource(args) === 'browser';
@@ -14,10 +20,10 @@ export const articlesCommand = cli({
   strategy: Strategy.COOKIE, browser: browserRequired,
   args: [
     { name: 'fakeid', positional: true, required: true, help: 'Official-account fakeid returned by weixin accounts' },
-    { name: 'name', help: 'Optional official-account name for display context' }, { name: 'limit', type: 'int', help: 'Maximum number of articles to return' }, { name: 'max-pages', type: 'int', help: 'Maximum number of history pages to scan' },
+    { name: 'name', help: 'Official-account name; exact case-insensitive match required for browser Sogou fallback' }, { name: 'limit', type: 'int', help: 'Maximum number of articles to return' }, { name: 'max-pages', type: 'int', help: 'Maximum number of history pages to scan' },
     { name: 'auth-source', default: 'browser', choices: ['browser', 'env'], help: 'Credential source: browser session or environment variables' },
   ],
-  columns: ['title', 'author', 'digest', 'publishedAt', 'url'],
+  columns: ['title', 'author', 'digest', 'publishedAt', 'url', 'source', 'coverage'],
   func: async (page, args) => {
     const fakeid = String(args.fakeid ?? '').trim();
     if (!fakeid) throw new ArgumentError('fakeid is required');
@@ -25,13 +31,37 @@ export const articlesCommand = cli({
     const credentials = authSource === 'env'
       ? readEnvironmentCredentials(false) : await resolveBrowserCredentials(page);
     const fetchPage = createArticleIndexFetcher({ page, source: authSource, credentials });
-    const { articles } = await callCrawler(() => collectArticles({
-      fakeid, fetchPage, limit: args.limit, maxPages: args['max-pages'],
-    }));
-    if (articles.length === 0) throw new EmptyResultError('weixin articles', `No published articles were found for ${fakeid}.`);
+    let articles;
+    let source = 'wechat';
+    let coverage = null;
+    try {
+      const result = await callCrawler(() => collectArticles({
+        fakeid, fetchPage, limit: args.limit, maxPages: args['max-pages'],
+      }));
+      articles = result.articles;
+      if (articles.length === 0) {
+        throw new EmptyResultError('weixin articles', `No published articles were found for ${fakeid}.`);
+      }
+    } catch (primaryError) {
+      if (authSource !== 'browser' || !isEligibleArticleFallbackError(primaryError)) throw primaryError;
+      const accountName = String(args.name ?? '').trim();
+      if (!accountName) throw withMissingFallbackName('weixin articles', primaryError);
+      try {
+        const fallback = await collectSogouAccountArticles({
+          page, accountName, limit: args.limit, maxPages: args['max-pages'],
+        });
+        articles = fallback.articles;
+        source = fallback.source;
+        coverage = fallback.coverage;
+      } catch (fallbackError) {
+        throw combineArticleFallbackErrors({
+          operation: 'weixin articles', primaryError, fallbackError, credentials,
+        });
+      }
+    }
     return articles.map(article => ({
       title: article.title, author: article.author || null, digest: article.digest || null,
-      publishedAt: article.publishedAt || null, url: article.url,
+      publishedAt: article.publishedAt || null, url: article.url, source, coverage,
     }));
   },
 });