@sovovs/bycli 2.1.24 → 2.1.26

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'], freshPage: true,
+        });
+        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,
     }));
   },
 });

package/clis/weixin/create-draft.js

@@ -1,8 +1,61 @@
+import * as nodeFs from 'node:fs';
+import * as nodePath from 'node:path';
 import { cli, Strategy } from '@sovovs/bycli/registry';
-import { CommandExecutionError } from '@sovovs/bycli/errors';
+import { ArgumentError, AuthRequiredError, CommandExecutionError } from '@sovovs/bycli/errors';
 
 const WEIXIN_DOMAIN = 'mp.weixin.qq.com';
 const WEIXIN_HOME = 'https://mp.weixin.qq.com/';
+const MAX_TITLE_LENGTH = 64;
+const MAX_AUTHOR_LENGTH = 8;
+const SUPPORTED_COVER_EXTENSIONS = new Set(['.jpg', '.jpeg', '.png', '.gif', '.webp']);
+
+function codePointLength(value) {
+    return [...value].length;
+}
+
+function requiredText(value, name) {
+    const text = String(value ?? '').trim();
+    if (!text) throw new ArgumentError(`${name} must not be empty`);
+    return text;
+}
+
+function validateCoverImage(value) {
+    if (value === undefined || value === null) return null;
+    const coverPath = nodePath.resolve(requiredText(value, 'cover-image'));
+    const extension = nodePath.extname(coverPath).toLowerCase();
+    if (!SUPPORTED_COVER_EXTENSIONS.has(extension)) {
+        throw new ArgumentError('cover-image must be a jpg, jpeg, png, gif, or webp file');
+    }
+    const info = nodeFs.statSync(coverPath, { throwIfNoEntry: false });
+    if (!info?.isFile() || info.size <= 0) {
+        throw new ArgumentError(`cover-image must be a readable non-empty file: ${coverPath}`);
+    }
+    try {
+        nodeFs.accessSync(coverPath, nodeFs.constants.R_OK);
+    } catch {
+        throw new ArgumentError(`cover-image must be readable: ${coverPath}`);
+    }
+    return coverPath;
+}
+
+function normalizeCreateDraftArgs(kwargs) {
+    const title = requiredText(kwargs.title, 'title');
+    requiredText(kwargs.content, 'content');
+    if (codePointLength(title) > MAX_TITLE_LENGTH) {
+        throw new ArgumentError(`title must be at most ${MAX_TITLE_LENGTH} characters`);
+    }
+    const author = kwargs.author == null ? null : requiredText(kwargs.author, 'author');
+    if (author && codePointLength(author) > MAX_AUTHOR_LENGTH) {
+        throw new ArgumentError(`author must be at most ${MAX_AUTHOR_LENGTH} characters`);
+    }
+    return {
+        title,
+        content: String(kwargs.content),
+        author,
+        summary: kwargs.summary == null ? null : String(kwargs.summary).trim(),
+        coverImage: validateCoverImage(kwargs['cover-image']),
+    };
+}
 
 async function getToken(page) {
     return page.evaluate(`(window.location.href.match(/token=(\\d+)/)||[])[1]`);
@@ -13,13 +66,19 @@ async function navigateToEditor(page) {
     await page.wait(3);
     const token = await getToken(page);
     if (!token) {
-        throw new CommandExecutionError('Could not extract session token. Please log in to mp.weixin.qq.com');
+        throw new AuthRequiredError(
+            WEIXIN_DOMAIN,
+            'Could not extract session token. Please log in to mp.weixin.qq.com',
+        );
     }
     await page.goto(`https://mp.weixin.qq.com/cgi-bin/appmsg?t=media/appmsg_edit_v2&action=edit&isNew=1&type=77&token=${token}&lang=zh_CN`);
     await page.wait(4);
     const hasTitle = await page.evaluate('!!document.querySelector("textarea#title")');
     if (!hasTitle) {
-        throw new CommandExecutionError('Article editor did not load. Session may have expired');
+        throw new AuthRequiredError(
+            WEIXIN_DOMAIN,
+            'Article editor did not load. Session may have expired',
+        );
     }
 }
 
@@ -27,15 +86,18 @@ async function fillField(page, selector, value) {
     return page.evaluate(`(() => {
         var el = document.querySelector('${selector}');
         if (!el) return { ok: false, reason: 'not found: ${selector}' };
+        var expected = ${JSON.stringify(value)};
         el.focus();
         var proto = el.tagName === 'TEXTAREA' ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
         var setter = Object.getOwnPropertyDescriptor(proto, 'value');
-        if (setter && setter.set) setter.set.call(el, ${JSON.stringify(value)});
-        else el.value = ${JSON.stringify(value)};
-        el.dispatchEvent(new InputEvent('input', { bubbles: true, data: ${JSON.stringify(value)} }));
+        if (setter && setter.set) setter.set.call(el, expected);
+        else el.value = expected;
+        el.dispatchEvent(new InputEvent('input', { bubbles: true, data: expected }));
         el.dispatchEvent(new Event('change', { bubbles: true }));
         el.blur();
-        return { ok: true };
+        return el.value === expected
+            ? { ok: true, value: el.value }
+            : { ok: false, reason: 'value mismatch', value: el.value };
     })()`);
 }
 
@@ -49,10 +111,21 @@ async function fillContent(page, text) {
         document.execCommand('selectAll', false, null);
         document.execCommand('insertText', false, ${JSON.stringify(text)});
         editor.dispatchEvent(new InputEvent('input', { bubbles: true }));
-        return { ok: true };
+        var normalize = value => String(value ?? '').replace(/\\r\\n?/g, '\\n').trim();
+        var expected = normalize(${JSON.stringify(text)});
+        var actual = normalize(editor.innerText ?? editor.textContent ?? '');
+        return actual === expected
+            ? { ok: true, value: actual }
+            : { ok: false, reason: 'value mismatch', value: actual };
     })()`);
 }
 
+function requirePageResult(result, label) {
+    if (!result?.ok) {
+        throw new CommandExecutionError(`Failed to fill ${label}: ${result?.reason ?? 'unverified page state'}`);
+    }
+}
+
 async function uploadContentImage(page, imagePath) {
     const fs = await import('node:fs');
     const path = await import('node:path');
@@ -76,15 +149,20 @@ async function uploadContentImage(page, imagePath) {
     await page.wait(1);
 
     await page.setFileInput([absPath], 'input[type="file"][name="file"]');
-    await page.wait(8);
 
-    const cdnCount = await page.evaluate(`(() => {
-        var editor = document.querySelector('#ueditor_0');
-        return editor ? editor.querySelectorAll('img[src*="mmbiz"]').length : 0;
-    })()`);
-    if (cdnCount === 0) {
-        throw new CommandExecutionError('Image did not upload to WeChat CDN');
+    for (let attempt = 0; attempt < 15; attempt++) {
+        await page.wait(1);
+        const cdnCount = await page.evaluate(`(() => {
+            var editors = document.querySelectorAll('#ueditor_0, div[contenteditable="true"]');
+            var count = 0;
+            editors.forEach(function(editor) {
+                count += editor.querySelectorAll('img[src*="mmbiz"], img[data-src*="mmbiz"]').length;
+            });
+            return count;
+        })()`);
+        if (cdnCount > 0) return;
     }
+    throw new CommandExecutionError('Image did not upload to WeChat CDN');
 }
 
 async function selectCoverFromContent(page) {
@@ -134,18 +212,23 @@ async function selectCoverFromContent(page) {
             if (btns[i].textContent.trim() === '确认' && btns[i].offsetHeight > 0 && !btns[i].disabled) { btns[i].click(); return; }
         }
     })()`);
-    await page.wait(2);
-    const hasCover = await page.evaluate(`(() => {
-        var area = document.querySelector('#js_cover_area');
-        if (!area) return false;
-        var found = false;
-        area.querySelectorAll('*').forEach(function(el) {
-            var bg = window.getComputedStyle(el).backgroundImage;
-            if (bg && bg.includes('mmbiz')) found = true;
-        });
-        return found;
-    })()`);
-    return hasCover;
+    for (let attempt = 0; attempt < 15; attempt++) {
+        await page.wait(1);
+        const hasCover = await page.evaluate(`(() => {
+            var areas = document.querySelectorAll('#js_cover_area, #js_cover_description_area, #appmsgItem');
+            var found = false;
+            areas.forEach(function(area) {
+                if (area.querySelector('img[src*="mmbiz"], img[data-src*="mmbiz"]')) found = true;
+                [area].concat(Array.from(area.querySelectorAll('*'))).forEach(function(el) {
+                    var bg = window.getComputedStyle(el).backgroundImage;
+                    if (bg && bg.includes('mmbiz')) found = true;
+                });
+            });
+            return found;
+        })()`);
+        if (hasCover) return true;
+    }
+    return false;
 }
 
 async function clickSaveDraft(page) {
@@ -167,7 +250,7 @@ async function clickSaveDraft(page) {
         })()`);
         if (saved) return true;
     }
-    return false;
+    throw new CommandExecutionError('Draft save could not be confirmed');
 }
 
 export const createDraftCommand = cli({
@@ -190,37 +273,39 @@ export const createDraftCommand = cli({
     columns: ['status', 'detail'],
 
     func: async (page, kwargs) => {
+        const args = normalizeCreateDraftArgs(kwargs);
         await navigateToEditor(page);
 
-        const titleResult = await fillField(page, 'textarea#title', kwargs.title);
-        if (!titleResult?.ok) throw new CommandExecutionError('Failed to fill title');
+        const titleResult = await fillField(page, 'textarea#title', args.title);
+        requirePageResult(titleResult, 'title');
 
-        if (kwargs.author) {
-            const authorResult = await fillField(page, 'input#author', kwargs.author);
-            if (!authorResult?.ok) throw new CommandExecutionError('Failed to fill author');
+        if (args.author) {
+            const authorResult = await fillField(page, 'input#author', args.author);
+            requirePageResult(authorResult, 'author');
         }
 
-        const contentResult = await fillContent(page, kwargs.content);
-        if (!contentResult?.ok) throw new CommandExecutionError('Failed to fill content');
+        const contentResult = await fillContent(page, args.content);
+        requirePageResult(contentResult, 'content');
 
-        if (kwargs['cover-image']) {
-            await uploadContentImage(page, kwargs['cover-image']);
+        if (args.coverImage) {
+            await uploadContentImage(page, args.coverImage);
             const coverSet = await selectCoverFromContent(page);
             if (!coverSet) {
-                // Non-fatal: draft can be saved without cover
+                throw new CommandExecutionError('Failed to set the requested cover image');
             }
         }
 
-        if (kwargs.summary) {
-            await fillField(page, 'textarea#js_description', kwargs.summary);
+        if (args.summary) {
+            const summaryResult = await fillField(page, 'textarea#js_description', args.summary);
+            requirePageResult(summaryResult, 'summary');
         }
 
         await page.wait(1);
-        const success = await clickSaveDraft(page);
+        await clickSaveDraft(page);
 
         return [{
-            status: success ? 'draft saved' : 'save attempted, check browser to confirm',
-            detail: `"${kwargs.title}"${kwargs.author ? ` by ${kwargs.author}` : ''}${kwargs['cover-image'] ? ' (with cover)' : ''}`,
+            status: 'draft saved',
+            detail: `"${args.title}"${args.author ? ` by ${args.author}` : ''}${args.coverImage ? ' (with cover)' : ''}`,
         }];
     },
 });

package/clis/weixin/download-publish-data.js

@@ -1,4 +1,7 @@
-import { ArgumentError } from '@sovovs/bycli/errors';
+import { constants } from 'node:fs';
+import { access, stat } from 'node:fs/promises';
+import { extname, resolve } from 'node:path';
+import { ArgumentError, CommandExecutionError } from '@sovovs/bycli/errors';
 import { cli, Strategy } from '@sovovs/bycli/registry';
 import { resolveBrowserCredentials } from './_wechat/auth-session.js';
 import { buildSecretSet, redactText } from './_wechat/redact.js';
@@ -10,6 +13,7 @@ import {
   matchPublishedRecord,
   positiveSafeInteger,
   validatePublishDate,
+  validatePublishedQuery,
 } from './_wechat/publish-records.js';
 
 const COLUMNS = [
@@ -23,6 +27,33 @@ function sanitizedError(error, secrets, fallback) {
     .replace(/https?:\/\/mp\.weixin\.qq\.com\/\S*/giu, '[REDACTED]');
 }
 
+async function validateArtifact(result, { label, expectedStatus, expectedExtension }) {
+  if (!result || result.status !== expectedStatus) {
+    throw new CommandExecutionError(`${label} returned an invalid status`);
+  }
+  if (typeof result.path !== 'string' || !result.path.trim()) {
+    throw new CommandExecutionError(`${label} returned no output path`);
+  }
+  if (!Number.isSafeInteger(result.size) || result.size <= 0) {
+    throw new CommandExecutionError(`${label} returned an invalid size`);
+  }
+  const path = resolve(result.path);
+  if (extname(path).toLowerCase() !== expectedExtension) {
+    throw new CommandExecutionError(`${label} returned an unexpected file type`);
+  }
+  let info;
+  try {
+    await access(path, constants.R_OK);
+    info = await stat(path);
+  } catch {
+    throw new CommandExecutionError(`${label} returned an unreadable file`);
+  }
+  if (!info.isFile() || info.size <= 0 || info.size !== result.size) {
+    throw new CommandExecutionError(`${label} returned an unreadable or mismatched file`);
+  }
+  return { ...result, path, size: info.size };
+}
+
 export const downloadPublishDataCommand = cli({
   site: 'weixin',
   name: 'download-publish-data',
@@ -43,6 +74,7 @@ export const downloadPublishDataCommand = cli({
   func: async (page, args) => {
     const query = String(args.query ?? '').trim();
     if (!query) throw new ArgumentError('query required');
+    const validatedQuery = validatePublishedQuery(query);
 
     const timeoutSeconds = positiveSafeInteger(args.timeout, 'timeout', 60);
     const maxPages = positiveSafeInteger(args['max-pages'], 'max-pages', 5);
@@ -56,7 +88,7 @@ export const downloadPublishDataCommand = cli({
       maxPages,
       timeout: timeoutSeconds,
     });
-    const record = matchPublishedRecord(rows, query, validatedDate);
+    const record = matchPublishedRecord(rows, validatedQuery, validatedDate);
     const detailUrl = buildDetailUrl(record, token);
     const outputDir = args.output ?? './weixin-publish-data';
     const commonOptions = {
@@ -71,15 +103,25 @@ export const downloadPublishDataCommand = cli({
     let markdownResult = null;
     const errors = [];
     try {
-      dataResult = await downloadPublishData(page, commonOptions);
+      const result = await downloadPublishData(page, commonOptions);
+      dataResult = await validateArtifact(result, {
+        label: 'Excel artifact',
+        expectedStatus: 'downloaded',
+        expectedExtension: '.xls',
+      });
     } catch (error) {
       errors.push(`Excel download failed: ${sanitizedError(error, secrets, 'Excel download failed')}`);
     }
     try {
-      markdownResult = await collectPublishAnalysis(page, {
+      const result = await collectPublishAnalysis(page, {
         ...commonOptions,
         publishedAt: record.publishedAt,
       });
+      markdownResult = await validateArtifact(result, {
+        label: 'Markdown artifact',
+        expectedStatus: 'saved',
+        expectedExtension: '.md',
+      });
     } catch (error) {
       errors.push(`Markdown analysis failed: ${sanitizedError(error, secrets, 'Markdown analysis failed')}`);
     }

package/clis/weixin/download.js

@@ -8,107 +8,21 @@
  */
 import { cli, Strategy } from '@sovovs/bycli/registry';
 import { downloadArticle } from '@sovovs/bycli/download/article-download';
-import { ArgumentError, AuthRequiredError, CommandExecutionError } from '@sovovs/bycli/errors';
+import { AuthRequiredError } from '@sovovs/bycli/errors';
 import { buildExtractWechatArticleContentJs } from './_wechat/article-content.js';
+import {
+    isTrustedSogouRedirectUrl,
+    isTrustedWechatArticleUrl,
+    normalizeWechatUrl,
+    resolveWechatArticleUrl,
+} from './_wechat/article-link.js';
 export { extractWechatArticleContent } from './_wechat/article-content.js';
-// ============================================================
-// URL Normalization
-// ============================================================
-/**
- * Normalize a pasted WeChat article URL.
- */
-export function normalizeWechatUrl(raw) {
-    let s = (raw || '').trim();
-    if (!s)
-        return s;
-    // Strip wrapping quotes / angle brackets
-    if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
-        s = s.slice(1, -1).trim();
-    }
-    if (s.startsWith('<') && s.endsWith('>')) {
-        s = s.slice(1, -1).trim();
-    }
-    // Remove backslash escapes before URL-significant characters
-    s = s.replace(/\\+([:/&?=#%])/g, '$1');
-    // Decode HTML entities
-    s = s.replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"');
-    // Allow bare hostnames
-    if (s.startsWith('mp.weixin.qq.com/') || s.startsWith('//mp.weixin.qq.com/')) {
-        s = 'https://' + s.replace(/^\/+/, '');
-    }
-    // Force https for mp.weixin.qq.com
-    try {
-        const parsed = new URL(s);
-        if (['http:', 'https:'].includes(parsed.protocol) && parsed.hostname.toLowerCase() === 'mp.weixin.qq.com') {
-            parsed.protocol = 'https:';
-            s = parsed.toString();
-        }
-    }
-    catch {
-        // Ignore parse errors
-    }
-    return s;
-}
-
-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 resolveWechatDownloadUrl(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');
-    }
-}
+export {
+    isTrustedSogouRedirectUrl,
+    isTrustedWechatArticleUrl,
+    normalizeWechatUrl,
+    resolveWechatArticleUrl as resolveWechatDownloadUrl,
+};
 /**
  * Format a WeChat article timestamp as a UTC+8 datetime string.
  * Accepts either Unix seconds or milliseconds.
@@ -245,7 +159,7 @@ cli({
     ],
     columns: ['title', 'author', 'publish_time', 'status', 'size', 'saved', 'source_url', 'resolved_url'],
     func: async (page, kwargs) => {
-        const { sourceUrl, resolvedUrl, alreadyNavigated } = await resolveWechatDownloadUrl(page, kwargs.url);
+        const { sourceUrl, resolvedUrl, alreadyNavigated } = await resolveWechatArticleUrl(page, kwargs.url);
         // Navigate and wait for content to load. Sogou resolution already lands on the article.
         if (!alreadyNavigated)
             await page.goto(resolvedUrl);

package/clis/weixin/save-articles.js

@@ -1,13 +1,21 @@
-import { ArgumentError, AuthRequiredError, CommandExecutionError } from '@sovovs/bycli/errors';
+import {
+  ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError,
+} from '@sovovs/bycli/errors';
 import { MAX_WECHAT_HTML_BYTES } from '@sovovs/bycli/download/wechat-article';
 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, isTrustedWechatArticleUrl, saveArticles,
 } from './_wechat/crawler-runtime.js';
 import { readAuthSource } from './_wechat/args.js';
 import { wechatArticleToMarkdown } from './_wechat/markdown.js';
+import { collectSogouAccountArticles } from './_wechat/sogou-fallback.js';
 
 const DOMAIN = 'mp.weixin.qq.com';
 const browserRequired = args => readAuthSource(args) === 'browser';
@@ -156,11 +164,11 @@ export const saveArticlesCommand = cli({
   description: 'Download WeChat official-account articles as Markdown files',
   strategy: Strategy.COOKIE, browser: browserRequired,
   args: [
-    { name: 'fakeid', positional: true, required: true, help: 'Official-account fakeid returned by weixin accounts' }, { name: 'name', help: 'Official-account name used in Markdown metadata' },
+    { name: 'fakeid', positional: true, required: true, help: 'Official-account fakeid returned by weixin accounts' }, { name: 'name', help: 'Official-account name; exact case-insensitive match required for browser Sogou fallback' },
     { name: 'output', default: './weixin-articles', help: 'Directory for saved Markdown files' }, { name: 'limit', type: 'int', help: 'Maximum number of articles to save' },
     { 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', 'status', 'stage', 'path', 'error', 'url'],
+  columns: ['title', 'status', 'stage', 'path', 'error', 'url', 'source', 'coverage'],
   func: async (page, args) => {
     const fakeid = String(args.fakeid ?? '').trim();
     if (!fakeid) throw new ArgumentError('fakeid is required');
@@ -169,20 +177,55 @@ export const saveArticlesCommand = cli({
       ? readEnvironmentCredentials(false) : await resolveBrowserCredentials(page);
     const articleHtmlDownloader = createArticleHtmlDownloader({ authSource, page });
     const fetchPage = createArticleIndexFetcher({ page, source: authSource, credentials });
-    const rows = await callCrawler(async () => {
-      const { articles } = await collectArticles({ fakeid, fetchPage, limit: args.limit, maxPages: args['max-pages'] });
-      return saveArticles({
+    let articles;
+    let resolutionFailures = [];
+    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 save-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 save-articles', primaryError);
+      try {
+        const fallback = await collectSogouAccountArticles({
+          page, accountName, limit: args.limit, maxPages: args['max-pages'],
+          resolutionPolicy: 'rows', freshPage: true,
+        });
+        articles = fallback.articles;
+        resolutionFailures = fallback.resolutionFailures;
+        source = fallback.source;
+        coverage = fallback.coverage;
+      } catch (fallbackError) {
+        throw combineArticleFallbackErrors({
+          operation: 'weixin save-articles', primaryError, fallbackError, credentials,
+        });
+      }
+    }
+
+    const savedRows = articles.length === 0 ? [] : await callCrawler(() => saveArticles({
         articles, accountName: String(args.name ?? '').trim(),
         outputDir: args.output ?? './weixin-articles', fetchArticleHtml: articleHtmlDownloader,
         buildMarkdown: (article, html) => wechatArticleToMarkdown({
           html, title: article.title, accountName: String(args.name ?? '').trim(), author: article.author,
           publishedAt: article.publishedAt, digest: article.digest, url: article.url,
         }), existingFilePolicy: 'suffix',
-      });
-    });
-    return rows.map(row => ({
+      }));
+    const orderedRows = source === 'sogou'
+      ? [
+        ...savedRows.map((row, index) => ({ ...row, order: articles[index]?.order ?? index })),
+        ...resolutionFailures,
+      ].sort((left, right) => left.order - right.order)
+      : savedRows;
+    return orderedRows.map(row => ({
       title: row.title, status: row.status, stage: row.stage || null, path: row.saved || null,
-      error: row.error || null, url: row.url,
+      error: row.error || null, url: row.url, source, coverage,
     }));
   },
 });