@sovovs/bycli 2.1.48 → 2.1.49

package/cli-manifest.json

@@ -28798,6 +28798,103 @@
     "sourceFile": "weixin/accounts.js",
     "navigateBefore": true
   },
+  {
+    "site": "weixin",
+    "name": "article-fetch",
+    "description": "Fetch one published Weixin article with optional browser fallback",
+    "access": "read",
+    "domain": "mp.weixin.qq.com",
+    "strategy": "cookie",
+    "browser": "conditional",
+    "args": [
+      {
+        "name": "article-id",
+        "type": "str",
+        "required": false,
+        "help": "Official article_id for API retrieval"
+      },
+      {
+        "name": "url",
+        "type": "str",
+        "required": false,
+        "help": "Trusted public article URL required for browser mode or fallback"
+      },
+      {
+        "name": "source",
+        "type": "str",
+        "default": "auto",
+        "required": false,
+        "help": "Article source and fallback policy",
+        "choices": [
+          "auto",
+          "api",
+          "browser"
+        ]
+      },
+      {
+        "name": "content",
+        "type": "str",
+        "default": "file",
+        "required": false,
+        "help": "Official API HTML handling",
+        "choices": [
+          "none",
+          "inline",
+          "file"
+        ]
+      },
+      {
+        "name": "output",
+        "type": "str",
+        "default": "./weixin-published",
+        "required": false,
+        "help": "Artifact output directory"
+      },
+      {
+        "name": "download-images",
+        "type": "boolean",
+        "default": true,
+        "required": false,
+        "help": "Download images in browser mode"
+      },
+      {
+        "name": "appid",
+        "type": "str",
+        "required": false,
+        "help": "WeChat Official Account AppID; falls back to WECHAT_APPID"
+      },
+      {
+        "name": "appsecret",
+        "type": "str",
+        "required": false,
+        "help": "WeChat AppSecret; prefer WECHAT_APPSECRET to avoid shell history"
+      },
+      {
+        "name": "access-token",
+        "type": "str",
+        "required": false,
+        "help": "Existing API token; falls back to WECHAT_ACCESS_TOKEN"
+      }
+    ],
+    "columns": [
+      "article_id",
+      "title",
+      "author",
+      "digest",
+      "published_at",
+      "url",
+      "content_html",
+      "artifact_paths_json",
+      "thumb_media_id",
+      "image_info_json",
+      "source",
+      "fallback_reason"
+    ],
+    "type": "js",
+    "modulePath": "weixin/article-fetch.js",
+    "sourceFile": "weixin/article-fetch.js",
+    "navigateBefore": "https://mp.weixin.qq.com"
+  },
   {
     "site": "weixin",
     "name": "articles",
@@ -29266,6 +29363,157 @@
     "sourceFile": "weixin/drafts.js",
     "navigateBefore": false
   },
+  {
+    "site": "weixin",
+    "name": "freepublish-get",
+    "description": "Get one published Weixin article through the official freepublish API",
+    "access": "read",
+    "domain": "api.weixin.qq.com",
+    "strategy": "local",
+    "browser": false,
+    "args": [
+      {
+        "name": "articleId",
+        "type": "str",
+        "required": true,
+        "positional": true,
+        "help": "Published article_id returned by freepublish-list"
+      },
+      {
+        "name": "content",
+        "type": "str",
+        "default": "inline",
+        "required": false,
+        "help": "HTML handling: omit, return inline, or save files",
+        "choices": [
+          "none",
+          "inline",
+          "file"
+        ]
+      },
+      {
+        "name": "output",
+        "type": "str",
+        "default": "./weixin-published",
+        "required": false,
+        "help": "Artifact directory when --content file is used"
+      },
+      {
+        "name": "appid",
+        "type": "str",
+        "required": false,
+        "help": "WeChat Official Account AppID; falls back to WECHAT_APPID"
+      },
+      {
+        "name": "appsecret",
+        "type": "str",
+        "required": false,
+        "help": "WeChat AppSecret; prefer WECHAT_APPSECRET to avoid shell history"
+      },
+      {
+        "name": "access-token",
+        "type": "str",
+        "required": false,
+        "help": "Existing API token; falls back to WECHAT_ACCESS_TOKEN"
+      }
+    ],
+    "columns": [
+      "article_id",
+      "article_index",
+      "article_type",
+      "title",
+      "author",
+      "digest",
+      "published_url",
+      "thumb_media_id",
+      "updated_at",
+      "content_html",
+      "artifact_paths_json",
+      "image_info_json"
+    ],
+    "type": "js",
+    "modulePath": "weixin/freepublish-get.js",
+    "sourceFile": "weixin/freepublish-get.js"
+  },
+  {
+    "site": "weixin",
+    "name": "freepublish-list",
+    "description": "List published Weixin articles through the official freepublish API",
+    "access": "read",
+    "domain": "api.weixin.qq.com",
+    "strategy": "local",
+    "browser": false,
+    "args": [
+      {
+        "name": "offset",
+        "type": "int",
+        "default": 0,
+        "required": false,
+        "help": "Zero-based published-material offset"
+      },
+      {
+        "name": "count",
+        "type": "int",
+        "default": 20,
+        "required": false,
+        "help": "Number of published materials to return (1–20)"
+      },
+      {
+        "name": "content",
+        "type": "str",
+        "default": "none",
+        "required": false,
+        "help": "HTML handling: omit, return inline, or save files",
+        "choices": [
+          "none",
+          "inline",
+          "file"
+        ]
+      },
+      {
+        "name": "output",
+        "type": "str",
+        "default": "./weixin-published",
+        "required": false,
+        "help": "Artifact directory when --content file is used"
+      },
+      {
+        "name": "appid",
+        "type": "str",
+        "required": false,
+        "help": "WeChat Official Account AppID; falls back to WECHAT_APPID"
+      },
+      {
+        "name": "appsecret",
+        "type": "str",
+        "required": false,
+        "help": "WeChat AppSecret; prefer WECHAT_APPSECRET to avoid shell history"
+      },
+      {
+        "name": "access-token",
+        "type": "str",
+        "required": false,
+        "help": "Existing API token; falls back to WECHAT_ACCESS_TOKEN"
+      }
+    ],
+    "columns": [
+      "article_id",
+      "article_index",
+      "article_type",
+      "title",
+      "author",
+      "digest",
+      "published_url",
+      "thumb_media_id",
+      "updated_at",
+      "content_html",
+      "artifact_paths_json",
+      "image_info_json"
+    ],
+    "type": "js",
+    "modulePath": "weixin/freepublish-list.js",
+    "sourceFile": "weixin/freepublish-list.js"
+  },
   {
     "site": "weixin",
     "name": "home-overview",
@@ -29359,6 +29607,105 @@
     "sourceFile": "weixin/published.js",
     "navigateBefore": false
   },
+  {
+    "site": "weixin",
+    "name": "published-articles",
+    "description": "List published Weixin articles with optional official-API-to-browser fallback",
+    "access": "read",
+    "domain": "mp.weixin.qq.com",
+    "strategy": "cookie",
+    "browser": "conditional",
+    "args": [
+      {
+        "name": "source",
+        "type": "str",
+        "default": "auto",
+        "required": false,
+        "help": "Article source and fallback policy",
+        "choices": [
+          "auto",
+          "api",
+          "browser"
+        ]
+      },
+      {
+        "name": "limit",
+        "type": "int",
+        "default": 20,
+        "required": false,
+        "help": "Maximum articles to return"
+      },
+      {
+        "name": "max-pages",
+        "type": "int",
+        "default": 5,
+        "required": false,
+        "help": "Maximum browser pages to scan"
+      },
+      {
+        "name": "timeout",
+        "type": "int",
+        "default": 30,
+        "required": false,
+        "help": "Browser request timeout in seconds"
+      },
+      {
+        "name": "content",
+        "type": "str",
+        "default": "none",
+        "required": false,
+        "help": "Official API HTML handling",
+        "choices": [
+          "none",
+          "inline",
+          "file"
+        ]
+      },
+      {
+        "name": "output",
+        "type": "str",
+        "default": "./weixin-published",
+        "required": false,
+        "help": "Official API artifact directory"
+      },
+      {
+        "name": "appid",
+        "type": "str",
+        "required": false,
+        "help": "WeChat Official Account AppID; falls back to WECHAT_APPID"
+      },
+      {
+        "name": "appsecret",
+        "type": "str",
+        "required": false,
+        "help": "WeChat AppSecret; prefer WECHAT_APPSECRET to avoid shell history"
+      },
+      {
+        "name": "access-token",
+        "type": "str",
+        "required": false,
+        "help": "Existing API token; falls back to WECHAT_ACCESS_TOKEN"
+      }
+    ],
+    "columns": [
+      "article_id",
+      "title",
+      "author",
+      "digest",
+      "published_at",
+      "url",
+      "content_html",
+      "artifact_paths_json",
+      "thumb_media_id",
+      "image_info_json",
+      "source",
+      "fallback_reason"
+    ],
+    "type": "js",
+    "modulePath": "weixin/published-articles.js",
+    "sourceFile": "weixin/published-articles.js",
+    "navigateBefore": "https://mp.weixin.qq.com"
+  },
   {
     "site": "weixin",
     "name": "save-articles",

package/clis/weixin/_wechat/api-freepublish.js

@@ -0,0 +1,170 @@
+import { ArgumentError, CommandExecutionError } from '@sovovs/bycli/errors';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { getAccessToken } from './api-draft.js';
+
+const API_BASE = 'https://api.weixin.qq.com/cgi-bin/freepublish';
+
+export class WechatOfficialApiError extends CommandExecutionError {
+  constructor(context, errcode, errmsg) {
+    super(`${context} failed (${String(errcode)}): ${String(errmsg || 'unknown error')}`);
+    this.wechatErrcode = errcode;
+  }
+}
+
+function text(value) {
+  const normalized = String(value ?? '').trim();
+  return normalized || null;
+}
+
+export function readOfficialApiCredentials(args = {}, env = process.env) {
+  const accessToken = text(args['access-token']) ?? text(env.WECHAT_ACCESS_TOKEN);
+  if (accessToken) return { accessToken, appid: null, appsecret: null, configured: true };
+  const explicitAppid = text(args.appid);
+  const explicitSecret = text(args.appsecret);
+  const usesExplicitPair = Boolean(explicitAppid || explicitSecret);
+  const appid = usesExplicitPair ? explicitAppid : text(env.WECHAT_APPID);
+  const appsecret = usesExplicitPair ? explicitSecret : text(env.WECHAT_APPSECRET);
+  if (Boolean(appid) !== Boolean(appsecret)) {
+    throw new ArgumentError('appid and appsecret must be provided together');
+  }
+  return {
+    accessToken: null, appid, appsecret, configured: Boolean(appid && appsecret),
+  };
+}
+
+export async function resolveOfficialApiAccessToken(credentials, fetchImpl = globalThis.fetch) {
+  if (credentials?.accessToken) return credentials.accessToken;
+  if (!credentials?.appid || !credentials?.appsecret) {
+    throw new ArgumentError('Official Weixin API requires WECHAT_ACCESS_TOKEN or an AppID/AppSecret pair');
+  }
+  try {
+    return await getAccessToken(credentials.appid, credentials.appsecret, fetchImpl);
+  } catch (error) {
+    const secret = String(credentials.appsecret);
+    let message = error instanceof Error ? error.message : String(error);
+    for (const value of [secret, encodeURIComponent(secret)]) message = message.replaceAll(value, '[REDACTED]');
+    message = message.replace(/([?&]secret=)[^&\s]*/giu, '$1[REDACTED]');
+    throw new CommandExecutionError(message);
+  }
+}
+
+async function postJson(path, accessToken, body, fetchImpl) {
+  if (typeof fetchImpl !== 'function') throw new CommandExecutionError('Official Weixin API requires fetch support');
+  const url = new URL(`${API_BASE}/${path}`);
+  url.searchParams.set('access_token', accessToken);
+  let response;
+  try {
+    response = await fetchImpl(url.toString(), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json; charset=utf-8' },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(30_000),
+    });
+  } catch {
+    throw new CommandExecutionError(`Weixin freepublish ${path} request failed`);
+  }
+  let payload;
+  try { payload = await response.json(); } catch { throw new CommandExecutionError(`Weixin freepublish ${path} returned invalid JSON`); }
+  if (!response.ok) throw new CommandExecutionError(`Weixin freepublish ${path} returned HTTP ${response.status}`);
+  if (payload?.errcode != null && payload.errcode !== 0) {
+    throw new WechatOfficialApiError(`Weixin freepublish ${path}`, payload.errcode, payload.errmsg);
+  }
+  return payload;
+}
+
+export function batchGetFreepublish({ accessToken, offset, count, noContent, fetchImpl = globalThis.fetch }) {
+  return postJson('batchget', accessToken, { offset, count, no_content: noContent }, fetchImpl);
+}
+
+export function getFreepublishArticle({ accessToken, articleId, fetchImpl = globalThis.fetch }) {
+  return postJson('getarticle', accessToken, { article_id: articleId }, fetchImpl);
+}
+
+function record(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new CommandExecutionError(`Weixin freepublish returned invalid ${label}`);
+  }
+  return value;
+}
+
+function unixIso(value) {
+  if (value == null) return null;
+  if (!Number.isSafeInteger(value) || value < 0) throw new CommandExecutionError('Weixin freepublish returned invalid update_time');
+  return new Date(value * 1000).toISOString();
+}
+
+function flattenArticle(container, articleId, updateTime) {
+  const content = container.content && typeof container.content === 'object' ? container.content : container;
+  const items = content.news_item;
+  if (!Array.isArray(items)) throw new CommandExecutionError('Weixin freepublish returned invalid news_item');
+  return items.map((raw, articleIndex) => {
+    const item = record(raw, `news_item[${articleIndex}]`);
+    const articleType = text(item.article_type) ?? (item.image_info ? 'newspic' : 'news');
+    return {
+      article_id: articleId,
+      article_index: articleIndex,
+      article_type: articleType,
+      title: text(item.title),
+      author: text(item.author),
+      digest: text(item.digest),
+      published_url: text(item.url),
+      thumb_media_id: text(item.thumb_media_id),
+      updated_at: unixIso(updateTime),
+      content_html: item.content == null ? null : String(item.content),
+      artifact_paths_json: null,
+      image_info_json: item.image_info == null ? null : JSON.stringify(item.image_info),
+    };
+  });
+}
+
+export function normalizeFreepublishPayload(payload) {
+  const response = record(payload, 'response');
+  if (Array.isArray(response.item)) {
+    return response.item.flatMap((raw, index) => {
+      const item = record(raw, `item[${index}]`);
+      const articleId = text(item.article_id);
+      if (!articleId) throw new CommandExecutionError('Weixin freepublish returned an item without article_id');
+      return flattenArticle(item, articleId, item.update_time);
+    });
+  }
+  const articleId = text(response.article_id);
+  if (!articleId) throw new CommandExecutionError('Weixin freepublish returned an article without article_id');
+  return flattenArticle(response, articleId, response.update_time);
+}
+
+function safeStem(row) {
+  const base = String(row.title || row.article_id || 'article')
+    .normalize('NFKC').replace(/[\\/:*?"<>|\u0000-\u001f]/gu, '-').replace(/\.{2,}/gu, '-').trim();
+  return (base || 'article').slice(0, 80);
+}
+
+async function writeUnique(directory, stem, extension, content) {
+  for (let suffix = 0; suffix < 10_000; suffix += 1) {
+    const name = `${stem}${suffix === 0 ? '' : `-${suffix}`}.${extension}`;
+    const path = join(directory, name);
+    try {
+      await writeFile(path, content, { encoding: 'utf8', flag: 'wx' });
+      return path;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+    }
+  }
+  throw new CommandExecutionError('Could not allocate a unique freepublish artifact name');
+}
+
+export async function materializeFreepublishRows(rows, { contentMode = 'inline', output = './weixin-published' } = {}) {
+  if (!['none', 'inline', 'file'].includes(contentMode)) throw new ArgumentError('content must be none, inline, or file');
+  if (contentMode === 'none') return rows.map(row => ({ ...row, content_html: null, artifact_paths_json: null }));
+  if (contentMode === 'inline') return rows.map(row => ({ ...row, artifact_paths_json: null }));
+  const directory = resolve(output);
+  await mkdir(directory, { recursive: true });
+  const materialized = [];
+  for (const row of rows) {
+    const stem = `${safeStem(row)}-${row.article_index + 1}`;
+    const html = await writeUnique(directory, stem, 'html', row.content_html ?? '');
+    const metadata = await writeUnique(directory, stem, 'json', `${JSON.stringify(row, null, 2)}\n`);
+    materialized.push({ ...row, content_html: null, artifact_paths_json: JSON.stringify({ html, metadata }) });
+  }
+  return materialized;
+}

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

@@ -0,0 +1,17 @@
+import { ArgumentError } from '@sovovs/bycli/errors';
+import { isTrustedWechatArticleUrl } from './article-link.js';
+import { WechatOfficialApiError } from './api-freepublish.js';
+
+const FALLBACK_CODES = new Set([48001, 50001]);
+
+export function isFreepublishFallbackEligible(error) {
+  return error instanceof WechatOfficialApiError && FALLBACK_CODES.has(error.wechatErrcode);
+}
+
+export function requireBrowserFallbackUrl(value) {
+  const url = String(value ?? '').trim();
+  if (!url || !isTrustedWechatArticleUrl(url)) {
+    throw new ArgumentError('Browser article fallback requires a trusted mp.weixin.qq.com article URL');
+  }
+  return url;
+}

package/clis/weixin/article-fetch.js

@@ -0,0 +1,66 @@
+import { ArgumentError } from '@sovovs/bycli/errors';
+import { cli, getRegistry, Strategy } from '@sovovs/bycli/registry';
+import { readOfficialApiCredentials } from './_wechat/api-freepublish.js';
+import { isFreepublishFallbackEligible, requireBrowserFallbackUrl } from './_wechat/freepublish-fallback.js';
+import { freepublishGetCommand, } from './freepublish-get.js';
+import { OFFICIAL_API_ARGS } from './freepublish-list.js';
+import { FACADE_COLUMNS, projectOfficialRows, sourceValue } from './published-articles.js';
+
+export async function loadBrowserDownloadCommand() {
+  const existing = getRegistry().get('weixin/download');
+  if (typeof existing?.func === 'function') return existing;
+  const module = await import('./download.js');
+  const registered = getRegistry().get('weixin/download');
+  return typeof registered?.func === 'function' ? registered : module.weixinDownloadCommand;
+}
+
+async function browserArticle(page, args, fallbackReason) {
+  const url = requireBrowserFallbackUrl(args.url);
+  const download = await loadBrowserDownloadCommand();
+  if (!download) throw new ArgumentError('weixin download command is unavailable for browser fallback');
+  const rows = await download.func(page, { url, output: args.output, 'download-images': args['download-images'] ?? true });
+  return rows.map(row => ({
+    article_id: null, title: row.title, author: row.author ?? null, digest: null,
+    published_at: row.publish_time ?? null, url: row.resolved_url ?? url, content_html: null,
+    artifact_paths_json: JSON.stringify({ markdown: row.saved }), thumb_media_id: null,
+    image_info_json: null, source: 'browser', fallback_reason: fallbackReason,
+  }));
+}
+
+export const articleFetchCommand = cli({
+  site: 'weixin', name: 'article-fetch', access: 'read', domain: 'mp.weixin.qq.com',
+  description: 'Fetch one published Weixin article with optional browser fallback',
+  strategy: Strategy.COOKIE,
+  browser: args => sourceValue(args.source) !== 'api',
+  args: [
+    { name: 'article-id', help: 'Official article_id for API retrieval' },
+    { name: 'url', help: 'Trusted public article URL required for browser mode or fallback' },
+    { name: 'source', default: 'auto', choices: ['auto', 'api', 'browser'], help: 'Article source and fallback policy' },
+    { name: 'content', default: 'file', choices: ['none', 'inline', 'file'], help: 'Official API HTML handling' },
+    { name: 'output', default: './weixin-published', help: 'Artifact output directory' },
+    { name: 'download-images', type: 'boolean', default: true, help: 'Download images in browser mode' },
+    ...OFFICIAL_API_ARGS,
+  ],
+  columns: FACADE_COLUMNS,
+  func: async (page, args) => {
+    const source = sourceValue(args.source);
+    if (source === 'browser') return browserArticle(page, args, null);
+    const articleId = String(args['article-id'] ?? '').trim();
+    if (!articleId) {
+      if (source === 'auto') return browserArticle(page, args, 'article-id-not-provided');
+      throw new ArgumentError('article-id is required in API mode');
+    }
+    const credentials = readOfficialApiCredentials(args);
+    if (source === 'auto' && !credentials.configured) return browserArticle(page, args, 'api-not-configured');
+    try {
+      return projectOfficialRows(await freepublishGetCommand.func({
+        ...args, articleId, content: args.content ?? 'file',
+      }));
+    } catch (error) {
+      if (source === 'auto' && isFreepublishFallbackEligible(error)) {
+        return browserArticle(page, args, 'api-not-authorized');
+      }
+      throw error;
+    }
+  },
+});

package/clis/weixin/download.js

@@ -149,7 +149,7 @@ export function buildDetectWechatAccessIssueJs() {
 // ============================================================
 // CLI Registration
 // ============================================================
-cli({
+export const weixinDownloadCommand = cli({
     site: 'weixin',
     name: 'download',
     access: 'read',

package/clis/weixin/freepublish-get.js

@@ -0,0 +1,30 @@
+import { ArgumentError } from '@sovovs/bycli/errors';
+import { cli, Strategy } from '@sovovs/bycli/registry';
+import {
+  getFreepublishArticle, materializeFreepublishRows, normalizeFreepublishPayload,
+  readOfficialApiCredentials, resolveOfficialApiAccessToken,
+} from './_wechat/api-freepublish.js';
+import { contentMode, FREEPUBLISH_COLUMNS, OFFICIAL_API_ARGS } from './freepublish-list.js';
+
+export const freepublishGetCommand = cli({
+  site: 'weixin', name: 'freepublish-get', access: 'read', domain: 'api.weixin.qq.com',
+  description: 'Get one published Weixin article through the official freepublish API',
+  strategy: Strategy.LOCAL, browser: false,
+  args: [
+    { name: 'articleId', positional: true, required: true, help: 'Published article_id returned by freepublish-list' },
+    { name: 'content', default: 'inline', choices: ['none', 'inline', 'file'], help: 'HTML handling: omit, return inline, or save files' },
+    { name: 'output', default: './weixin-published', help: 'Artifact directory when --content file is used' },
+    ...OFFICIAL_API_ARGS,
+  ],
+  columns: FREEPUBLISH_COLUMNS,
+  func: async args => {
+    const articleId = String(args.articleId ?? '').trim();
+    if (!articleId) throw new ArgumentError('articleId is required');
+    const mode = contentMode(args.content, 'inline');
+    const credentials = readOfficialApiCredentials(args);
+    const accessToken = await resolveOfficialApiAccessToken(credentials);
+    const payload = await getFreepublishArticle({ accessToken, articleId });
+    const rows = normalizeFreepublishPayload({ ...payload, article_id: payload.article_id ?? articleId });
+    return materializeFreepublishRows(rows, { contentMode: mode, output: args.output });
+  },
+});

package/clis/weixin/freepublish-list.js

@@ -0,0 +1,53 @@
+import { ArgumentError, EmptyResultError } from '@sovovs/bycli/errors';
+import { cli, Strategy } from '@sovovs/bycli/registry';
+import {
+  batchGetFreepublish, materializeFreepublishRows, normalizeFreepublishPayload,
+  readOfficialApiCredentials, resolveOfficialApiAccessToken,
+} from './_wechat/api-freepublish.js';
+
+export const FREEPUBLISH_COLUMNS = [
+  'article_id', 'article_index', 'article_type', 'title', 'author', 'digest',
+  'published_url', 'thumb_media_id', 'updated_at', 'content_html',
+  'artifact_paths_json', 'image_info_json',
+];
+
+export const OFFICIAL_API_ARGS = [
+  { name: 'appid', help: 'WeChat Official Account AppID; falls back to WECHAT_APPID' },
+  { name: 'appsecret', help: 'WeChat AppSecret; prefer WECHAT_APPSECRET to avoid shell history' },
+  { name: 'access-token', help: 'Existing API token; falls back to WECHAT_ACCESS_TOKEN' },
+];
+
+function contentMode(value, fallback) {
+  const mode = String(value ?? fallback);
+  if (!['none', 'inline', 'file'].includes(mode)) throw new ArgumentError('content must be none, inline, or file');
+  return mode;
+}
+
+export const freepublishListCommand = cli({
+  site: 'weixin', name: 'freepublish-list', access: 'read', domain: 'api.weixin.qq.com',
+  description: 'List published Weixin articles through the official freepublish API',
+  strategy: Strategy.LOCAL, browser: false,
+  args: [
+    { name: 'offset', type: 'int', default: 0, help: 'Zero-based published-material offset' },
+    { name: 'count', type: 'int', default: 20, help: 'Number of published materials to return (1–20)' },
+    { name: 'content', default: 'none', choices: ['none', 'inline', 'file'], help: 'HTML handling: omit, return inline, or save files' },
+    { name: 'output', default: './weixin-published', help: 'Artifact directory when --content file is used' },
+    ...OFFICIAL_API_ARGS,
+  ],
+  columns: FREEPUBLISH_COLUMNS,
+  func: async args => {
+    const offset = args.offset ?? 0;
+    const count = args.count ?? 20;
+    if (!Number.isSafeInteger(offset) || offset < 0) throw new ArgumentError('offset must be a non-negative safe integer');
+    if (!Number.isSafeInteger(count) || count < 1 || count > 20) throw new ArgumentError('count must be an integer from 1 to 20');
+    const mode = contentMode(args.content, 'none');
+    const credentials = readOfficialApiCredentials(args);
+    const accessToken = await resolveOfficialApiAccessToken(credentials);
+    const payload = await batchGetFreepublish({ accessToken, offset, count, noContent: mode === 'none' ? 1 : 0 });
+    const rows = normalizeFreepublishPayload(payload);
+    if (rows.length === 0) throw new EmptyResultError('weixin freepublish-list', 'No published articles were returned by the official API.');
+    return materializeFreepublishRows(rows, { contentMode: mode, output: args.output });
+  },
+});
+
+export { contentMode };

package/clis/weixin/published-articles.js

@@ -0,0 +1,77 @@
+import { ArgumentError, EmptyResultError } from '@sovovs/bycli/errors';
+import { cli, Strategy } from '@sovovs/bycli/registry';
+import { readOfficialApiCredentials } from './_wechat/api-freepublish.js';
+import { resolveBrowserCredentials } from './_wechat/auth-session.js';
+import { isFreepublishFallbackEligible } from './_wechat/freepublish-fallback.js';
+import { collectPublishedRecords } from './_wechat/publish-records.js';
+import { freepublishListCommand, OFFICIAL_API_ARGS } from './freepublish-list.js';
+
+export const FACADE_COLUMNS = [
+  'article_id', 'title', 'author', 'digest', 'published_at', 'url', 'content_html',
+  'artifact_paths_json', 'thumb_media_id', 'image_info_json', 'source', 'fallback_reason',
+];
+
+function sourceValue(value) {
+  const source = String(value ?? 'auto');
+  if (!['auto', 'api', 'browser'].includes(source)) throw new ArgumentError('source must be auto, api, or browser');
+  return source;
+}
+
+export function projectOfficialRows(rows, fallbackReason = null) {
+  return rows.map(row => ({
+    article_id: row.article_id, title: row.title, author: row.author, digest: row.digest,
+    published_at: row.updated_at, url: row.published_url, content_html: row.content_html,
+    artifact_paths_json: row.artifact_paths_json, thumb_media_id: row.thumb_media_id,
+    image_info_json: row.image_info_json, source: 'official-api', fallback_reason: fallbackReason,
+  }));
+}
+
+async function browserRows(page, args, fallbackReason) {
+  const { token } = await resolveBrowserCredentials(page);
+  const rows = await collectPublishedRecords(page, {
+    token, limit: args.limit ?? 20, maxPages: args['max-pages'] ?? 5, timeout: args.timeout ?? 30,
+  });
+  return rows.map(row => ({
+    article_id: null, title: row.title, author: null, digest: null,
+    published_at: row.publishedAt, url: row.url, content_html: null,
+    artifact_paths_json: null, thumb_media_id: null, image_info_json: null,
+    source: 'browser', fallback_reason: fallbackReason,
+  }));
+}
+
+export const publishedArticlesCommand = cli({
+  site: 'weixin', name: 'published-articles', access: 'read', domain: 'mp.weixin.qq.com',
+  description: 'List published Weixin articles with optional official-API-to-browser fallback',
+  strategy: Strategy.COOKIE,
+  browser: args => sourceValue(args.source) !== 'api',
+  args: [
+    { name: 'source', default: 'auto', choices: ['auto', 'api', 'browser'], help: 'Article source and fallback policy' },
+    { name: 'limit', type: 'int', default: 20, help: 'Maximum articles to return' },
+    { name: 'max-pages', type: 'int', default: 5, help: 'Maximum browser pages to scan' },
+    { name: 'timeout', type: 'int', default: 30, help: 'Browser request timeout in seconds' },
+    { name: 'content', default: 'none', choices: ['none', 'inline', 'file'], help: 'Official API HTML handling' },
+    { name: 'output', default: './weixin-published', help: 'Official API artifact directory' },
+    ...OFFICIAL_API_ARGS,
+  ],
+  columns: FACADE_COLUMNS,
+  func: async (page, args) => {
+    const source = sourceValue(args.source);
+    if (source === 'browser') return browserRows(page, args, null);
+    const credentials = readOfficialApiCredentials(args);
+    if (source === 'auto' && !credentials.configured) return browserRows(page, args, 'api-not-configured');
+    try {
+      const rows = await freepublishListCommand.func({
+        ...args, offset: 0, count: Math.min(args.limit ?? 20, 20), content: args.content ?? 'none',
+      });
+      return projectOfficialRows(rows);
+    } catch (error) {
+      if (source === 'auto' && isFreepublishFallbackEligible(error)) {
+        return browserRows(page, args, 'api-not-authorized');
+      }
+      if (error instanceof EmptyResultError) throw error;
+      throw error;
+    }
+  },
+});
+
+export { sourceValue };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sovovs/bycli",
-  "version": "2.1.48",
+  "version": "2.1.49",
   "publishConfig": {
     "access": "public"
   },