@sovovs/bycli 2.1.47 → 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",
@@ -29044,6 +29141,62 @@
     "sourceFile": "weixin/create-draft.js",
     "navigateBefore": false
   },
+  {
+    "site": "weixin",
+    "name": "create-newspic",
+    "description": "通过微信公众号官方 API 创建贴图草稿（不会公开发布）",
+    "access": "write",
+    "example": "bycli weixin create-newspic --title \"相册标题\" --images \"./01.jpg,http://example.com/02.png\" --content \"说明文字\" --appid wx123 --appsecret secret",
+    "strategy": "local",
+    "browser": false,
+    "args": [
+      {
+        "name": "title",
+        "type": "str",
+        "required": true,
+        "help": "贴图标题（最长 32 字）"
+      },
+      {
+        "name": "images",
+        "type": "str",
+        "required": true,
+        "help": "1–20 张本地或 HTTP(S) 图片，使用逗号分隔"
+      },
+      {
+        "name": "content",
+        "type": "str",
+        "required": false,
+        "valueRequired": true,
+        "help": "可选的纯文本贴图说明"
+      },
+      {
+        "name": "appid",
+        "type": "str",
+        "required": true,
+        "help": "公众号 AppID"
+      },
+      {
+        "name": "appsecret",
+        "type": "str",
+        "required": true,
+        "help": "公众号 AppSecret；请勿提交到 shell 历史或日志"
+      },
+      {
+        "name": "allow-private-image-hosts",
+        "type": "boolean",
+        "default": false,
+        "required": false,
+        "help": "允许下载 localhost/内网 HTTP(S) 图片；云元数据地址始终禁止"
+      }
+    ],
+    "columns": [
+      "status",
+      "detail"
+    ],
+    "type": "js",
+    "modulePath": "weixin/create-newspic.js",
+    "sourceFile": "weixin/create-newspic.js"
+  },
   {
     "site": "weixin",
     "name": "download",
@@ -29210,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",
@@ -29303,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-draft.js

@@ -12,7 +12,7 @@ function apiError(context, payload) {
   return new CommandExecutionError(`${context} failed (${code}): ${message}`);
 }
 
-async function readJsonResponse(response, context) {
+export async function readJsonResponse(response, context) {
   let payload;
   try {
     payload = await response.json();
@@ -24,7 +24,7 @@ async function readJsonResponse(response, context) {
   return payload;
 }
 
-async function getAccessToken(appid, appsecret, fetchImpl) {
+export async function getAccessToken(appid, appsecret, fetchImpl) {
   const url = new URL(`${API_BASE}/token`);
   url.searchParams.set('grant_type', 'client_credential');
   url.searchParams.set('appid', appid);
@@ -43,7 +43,7 @@ function mimeType(filePath) {
   return 'image/jpeg';
 }
 
-async function uploadImage(filePath, token, fetchImpl) {
+export async function uploadImage(filePath, token, fetchImpl) {
   const data = await nodeFs.readFile(filePath);
   const form = new FormData();
   form.append('media', new Blob([data], { type: mimeType(filePath) }), nodePath.basename(filePath));

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/api-newspic.js

@@ -0,0 +1,180 @@
+import * as nodePath from 'node:path';
+import { access, stat } from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
+import { ArgumentError, CommandExecutionError } from '@sovovs/bycli/errors';
+import { downloadRemoteImage } from './remote-image.js';
+import { getAccessToken, readJsonResponse, uploadImage } from './api-draft.js';
+
+const API_BASE = 'https://api.weixin.qq.com/cgi-bin';
+const MIN_IMAGES = 1;
+const MAX_IMAGES = 20;
+const SUPPORTED_IMAGE_EXTENSIONS = new Set(['.jpg', '.jpeg', '.png', '.gif', '.webp']);
+
+function isRemoteImageSource(source) {
+  return /^https?:\/\//iu.test(String(source || ''));
+}
+
+function validateImageCount(images) {
+  if (!Array.isArray(images) || images.length < MIN_IMAGES || images.length > MAX_IMAGES) {
+    throw new ArgumentError('newspic requires 1–20 images');
+  }
+}
+
+async function resolveLocalImage(source, baseDir) {
+  const imagePath = nodePath.resolve(baseDir, source);
+  if (!SUPPORTED_IMAGE_EXTENSIONS.has(nodePath.extname(imagePath).toLowerCase())) {
+    throw new ArgumentError(`newspic image must be a jpg, jpeg, png, gif, or webp file: ${source}`);
+  }
+  try {
+    await access(imagePath, fsConstants.R_OK);
+    const info = await stat(imagePath);
+    if (!info.isFile() || info.size <= 0) throw new Error('not a non-empty file');
+  } catch {
+    throw new ArgumentError(`newspic image must be a readable non-empty file: ${imagePath}`);
+  }
+  return imagePath;
+}
+
+export async function stageNewspicImages(images, {
+  baseDir = process.cwd(),
+  allowPrivateHosts = false,
+  fetchImpl = globalThis.fetch,
+  lookupImpl,
+  downloadImpl = downloadRemoteImage,
+} = {}) {
+  validateImageCount(images);
+  const downloads = [];
+  const paths = [];
+  let cleaned = false;
+  const cleanup = async () => {
+    if (cleaned) return;
+    cleaned = true;
+    const results = await Promise.allSettled(downloads.map(download => download.cleanup()));
+    const failure = results.find(result => result.status === 'rejected');
+    if (failure) {
+      throw new CommandExecutionError(`Failed to clean up a temporary Weixin image: ${failure.reason?.message ?? failure.reason}`);
+    }
+  };
+  try {
+    for (const rawSource of images) {
+      const source = String(rawSource ?? '').trim();
+      if (!source) throw new ArgumentError('newspic image source must not be empty');
+      if (isRemoteImageSource(source)) {
+        const downloaded = await downloadImpl(source, {
+          allowPrivateHosts,
+          fetchImpl,
+          ...(lookupImpl ? { lookupImpl } : {}),
+        });
+        downloads.push(downloaded);
+        paths.push(downloaded.path);
+      } else {
+        paths.push(await resolveLocalImage(source, baseDir));
+      }
+    }
+    return { paths, cleanup };
+  } catch (error) {
+    try {
+      await cleanup();
+    } catch (cleanupError) {
+      throw new CommandExecutionError(`${error?.message ?? error}; ${cleanupError.message}`);
+    }
+    throw error;
+  }
+}
+
+async function deleteMaterial(mediaId, token, fetchImpl) {
+  const url = new URL(`${API_BASE}/material/del_material`);
+  url.searchParams.set('access_token', token);
+  const response = await fetchImpl(url.toString(), {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json; charset=utf-8' },
+    body: JSON.stringify({ media_id: mediaId }),
+  });
+  await readJsonResponse(response, '删除图片素材');
+}
+
+export async function createNewspicDraftViaApi({
+  appid,
+  appsecret,
+  title,
+  content = '',
+  images,
+  baseDir = process.cwd(),
+  fetchImpl = globalThis.fetch,
+  imageFetchImpl = globalThis.fetch,
+  lookupImpl,
+  downloadImpl = downloadRemoteImage,
+  allowPrivateImageHosts = false,
+} = {}) {
+  if (!String(appid ?? '').trim() || !String(appsecret ?? '').trim()) {
+    throw new CommandExecutionError('newspic API requires both appid and appsecret');
+  }
+  if (typeof fetchImpl !== 'function') throw new CommandExecutionError('newspic API requires fetch support');
+  validateImageCount(images);
+
+  const staged = await stageNewspicImages(images, {
+    baseDir,
+    allowPrivateHosts: allowPrivateImageHosts,
+    fetchImpl: imageFetchImpl,
+    downloadImpl,
+    ...(lookupImpl ? { lookupImpl } : {}),
+  });
+  let token;
+  const imageMediaIds = [];
+  let draftResult;
+  try {
+    token = await getAccessToken(String(appid).trim(), String(appsecret).trim(), fetchImpl);
+    for (const imagePath of staged.paths) {
+      const uploaded = await uploadImage(imagePath, token, fetchImpl);
+      imageMediaIds.push(uploaded.media_id);
+    }
+
+    const url = new URL(`${API_BASE}/draft/add`);
+    url.searchParams.set('access_token', token);
+    const body = {
+      articles: [{
+        article_type: 'newspic',
+        title: String(title ?? ''),
+        content: String(content ?? ''),
+        need_open_comment: 0,
+        only_fans_can_comment: 0,
+        image_info: {
+          image_list: imageMediaIds.map(imageMediaId => ({ image_media_id: imageMediaId })),
+        },
+      }],
+    };
+    const response = await fetchImpl(url.toString(), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json; charset=utf-8' },
+      body: JSON.stringify(body),
+    });
+    const payload = await readJsonResponse(response, '创建贴图草稿');
+    if (!payload.media_id) throw new CommandExecutionError('创建贴图草稿 failed: response did not contain media_id');
+    draftResult = { mediaId: payload.media_id, imageMediaIds };
+  } catch (error) {
+    const cleanupProblems = [];
+    if (token && imageMediaIds.length > 0) {
+      const results = await Promise.allSettled(imageMediaIds.map(mediaId => deleteMaterial(mediaId, token, fetchImpl)));
+      const failedMediaIds = imageMediaIds.filter((_mediaId, index) => results[index].status === 'rejected');
+      if (failedMediaIds.length > 0) {
+        cleanupProblems.push(`failed to delete permanent materials: ${failedMediaIds.join(', ')}`);
+      }
+    }
+    try {
+      await staged.cleanup();
+    } catch (cleanupError) {
+      cleanupProblems.push(cleanupError.message);
+    }
+    if (cleanupProblems.length > 0) {
+      throw new CommandExecutionError(`${error?.message ?? error}; cleanup incomplete: ${cleanupProblems.join('; ')}`);
+    }
+    throw error;
+  }
+
+  try {
+    await staged.cleanup();
+  } catch (cleanupError) {
+    return { ...draftResult, cleanupWarning: cleanupError.message };
+  }
+  return draftResult;
+}

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/create-newspic.js

@@ -0,0 +1,61 @@
+import { cli, Strategy } from '@sovovs/bycli/registry';
+import { ArgumentError } from '@sovovs/bycli/errors';
+import { createNewspicDraftViaApi } from './_wechat/api-newspic.js';
+
+const MAX_TITLE_LENGTH = 32;
+
+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 parseImages(value) {
+  const images = requiredText(value, 'images').split(',').map(item => item.trim());
+  if (images.some(image => !image)) throw new ArgumentError('images must not contain empty entries');
+  if (images.length < 1 || images.length > 20) throw new ArgumentError('newspic requires 1–20 images');
+  return images;
+}
+
+export const createNewspicCommand = cli({
+  site: 'weixin',
+  name: 'create-newspic',
+  access: 'write',
+  description: '通过微信公众号官方 API 创建贴图草稿（不会公开发布）',
+  example: 'bycli weixin create-newspic --title "相册标题" --images "./01.jpg,http://example.com/02.png" --content "说明文字" --appid wx123 --appsecret secret',
+  strategy: Strategy.LOCAL,
+  browser: false,
+  args: [
+    { name: 'title', required: true, help: '贴图标题（最长 32 字）' },
+    { name: 'images', required: true, help: '1–20 张本地或 HTTP(S) 图片，使用逗号分隔' },
+    { name: 'content', valueRequired: true, help: '可选的纯文本贴图说明' },
+    { name: 'appid', required: true, help: '公众号 AppID' },
+    { name: 'appsecret', required: true, help: '公众号 AppSecret；请勿提交到 shell 历史或日志' },
+    { name: 'allow-private-image-hosts', type: 'boolean', default: false, help: '允许下载 localhost/内网 HTTP(S) 图片；云元数据地址始终禁止' },
+  ],
+  columns: ['status', 'detail'],
+
+  func: async (kwargs) => {
+    const title = requiredText(kwargs.title, 'title');
+    if (codePointLength(title) > MAX_TITLE_LENGTH) {
+      throw new ArgumentError(`title must be at most ${MAX_TITLE_LENGTH} characters`);
+    }
+    const images = parseImages(kwargs.images);
+    const result = await createNewspicDraftViaApi({
+      appid: requiredText(kwargs.appid, 'appid'),
+      appsecret: requiredText(kwargs.appsecret, 'appsecret'),
+      title,
+      content: kwargs.content == null ? '' : String(kwargs.content),
+      images,
+      allowPrivateImageHosts: kwargs['allow-private-image-hosts'] === true,
+    });
+    return [{
+      status: 'newspic draft created',
+      detail: `"${title}" (media_id: ${result.mediaId}, images: ${images.length})${result.cleanupWarning ? `; warning: ${result.cleanupWarning}` : ''}`,
+    }];
+  },
+});

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.47",
+  "version": "2.1.49",
   "publishConfig": {
     "access": "public"
   },