@sovovs/bycli 2.1.11 → 2.1.12

package/clis/weixin/_wechat/crawler-runtime.js

@@ -0,0 +1,34 @@
+import crawler from '@sovovs/wechat-article-crawler';
+import { ArgumentError, AuthRequiredError, CommandExecutionError } from '@sovovs/bycli/errors';
+
+const {
+  CrawlerError,
+  collectArticles,
+  createWechatApi,
+  isTrustedWechatArticleUrl,
+  saveArticles,
+} = crawler;
+
+export {
+  CrawlerError,
+  collectArticles,
+  createWechatApi,
+  isTrustedWechatArticleUrl,
+  saveArticles,
+};
+
+export async function callCrawler(operation) {
+  try {
+    return await operation();
+  } catch (error) {
+    if (!(error instanceof CrawlerError)) throw error;
+
+    if (error.code === 'INVALID_ARGUMENT') {
+      throw new ArgumentError(error.message);
+    }
+    if (error.code === 'AUTH_REQUIRED') {
+      throw new AuthRequiredError('mp.weixin.qq.com', error.message);
+    }
+    throw new CommandExecutionError(error.message);
+  }
+}

package/clis/weixin/articles.js

@@ -1,8 +1,7 @@
 import { ArgumentError, EmptyResultError } from '@sovovs/bycli/errors';
 import { cli, Strategy } from '@sovovs/bycli/registry';
 import { readEnvironmentCredentials, resolveBrowserCredentials } from './_wechat/auth-session.js';
-import { collectArticles } from './_wechat/article-service.js';
-import { createWechatApi } from './_wechat/wechat-api.js';
+import { callCrawler, collectArticles, createWechatApi } from './_wechat/crawler-runtime.js';
 import { readAuthSource } from './_wechat/args.js';
 
 const DOMAIN = 'mp.weixin.qq.com';
@@ -24,8 +23,10 @@ export const articlesCommand = cli({
     const authSource = readAuthSource(args);
     const credentials = authSource === 'env'
       ? readEnvironmentCredentials(false) : await resolveBrowserCredentials(page);
-    const { fetchPage } = createWechatApi(credentials);
-    const { articles } = await collectArticles({ fakeid, fetchPage, limit: args.limit, maxPages: args['max-pages'] });
+    const { articles } = await callCrawler(async () => {
+      const { fetchPage } = createWechatApi(credentials);
+      return 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}.`);
     return articles.map(article => ({
       title: article.title, author: article.author || null, digest: article.digest || null,

package/clis/weixin/save-articles.js

@@ -2,10 +2,11 @@ import { ArgumentError, AuthRequiredError, CommandExecutionError } from '@sovovs
 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 { collectArticles, isTrustedWechatArticleUrl } from './_wechat/article-service.js';
-import { saveArticles } from './_wechat/save-service.js';
-import { createWechatApi } from './_wechat/wechat-api.js';
+import {
+  callCrawler, collectArticles, createWechatApi, isTrustedWechatArticleUrl, saveArticles,
+} from './_wechat/crawler-runtime.js';
 import { readAuthSource } from './_wechat/args.js';
+import { wechatArticleToMarkdown } from './_wechat/markdown.js';
 
 const DOMAIN = 'mp.weixin.qq.com';
 const browserRequired = args => readAuthSource(args) === 'browser';
@@ -165,12 +166,18 @@ export const saveArticlesCommand = cli({
     const authSource = readAuthSource(args);
     const credentials = authSource === 'env'
       ? readEnvironmentCredentials(false) : await resolveBrowserCredentials(page);
-    const { fetchPage } = createWechatApi(credentials);
-    const { articles } = await collectArticles({ fakeid, fetchPage, limit: args.limit, maxPages: args['max-pages'] });
     const articleHtmlDownloader = createArticleHtmlDownloader({ authSource, page });
-    const rows = await saveArticles({
-      articles, accountName: String(args.name ?? '').trim(),
-      outputDir: args.output ?? './weixin-articles', fetchArticleHtml: articleHtmlDownloader,
+    const rows = await callCrawler(async () => {
+      const { fetchPage } = createWechatApi(credentials);
+      const { articles } = await collectArticles({ fakeid, fetchPage, limit: args.limit, maxPages: args['max-pages'] });
+      return 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 => ({
       title: row.title, status: row.status, stage: row.stage || null, path: row.saved || null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sovovs/bycli",
-  "version": "2.1.11",
+  "version": "2.1.12",
   "publishConfig": {
     "access": "public"
   },
@@ -90,6 +90,7 @@
   "dependencies": {
     "@mozilla/readability": "^0.6.0",
     "@sovovs/bycli-recorder-core": "^0.1.0",
+    "@sovovs/wechat-article-crawler": "^1.1.0",
     "cli-table3": "^0.6.5",
     "commander": "^14.0.3",
     "js-yaml": "^4.1.0",

package/scripts/check-package-install.mjs

@@ -3,6 +3,7 @@ import { execFileSync } from 'node:child_process';
 import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
+import { createRequire } from 'node:module';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
@@ -58,8 +59,24 @@ try {
     project, 'node_modules/@sovovs/bycli/package.json',
   ), 'utf8'));
   assert.equal(mainManifest.dependencies?.['@sovovs/bycli-recorder-core'], '^0.1.0');
+  assert.equal(mainManifest.dependencies?.['@sovovs/wechat-article-crawler'], '^1.1.0');
 
   const coreDirectory = join(project, 'node_modules/@sovovs/bycli-recorder-core');
+  const crawlerDirectoryInstalled = join(project, 'node_modules/@sovovs/wechat-article-crawler');
+  const crawlerManifest = JSON.parse(readFileSync(
+    join(crawlerDirectoryInstalled, 'package.json'), 'utf8',
+  ));
+  assert.equal(crawlerManifest.version, '1.1.2');
+  const projectRequire = createRequire(join(project, 'package.json'));
+  const crawlerEntry = projectRequire.resolve('@sovovs/wechat-article-crawler');
+  const crawlerModule = await import(pathToFileURL(crawlerEntry).href);
+  const crawlerApi = crawlerModule.default ?? crawlerModule;
+  for (const name of [
+    'CrawlerError', 'createWechatApi', 'collectArticles',
+    'isTrustedWechatArticleUrl', 'saveArticles',
+  ]) {
+    assert.ok(crawlerApi[name], `crawler root API missing ${name}`);
+  }
   const recorderEntry = join(
     project, 'node_modules/@sovovs/bycli/dist/src/browser/analyze.js',
   );

package/scripts/recorder.sh

@@ -0,0 +1,186 @@
+#!/usr/bin/env bash
+# 录制三端管理脚本
+#   daemon : 浏览器底座(19825),由 bycli 管理;扩展连这口
+#   be     : Recorder Local Service(19826),同源托管真实工作台 UI(dashboard/dist)
+#   web    : Umi dev server(8000),mock 模式,仅前端开发用(无真实录制)
+#
+# 用法:
+#   scripts/recorder.sh start   [daemon|be|all]       # 默认=真实录制环境(daemon+be,自动停 mock)
+#   scripts/recorder.sh start   --mock                # 仅此参数才起 mock 前端(web :8000,假数据)
+#   scripts/recorder.sh stop    [daemon|be|web|all]
+#   scripts/recorder.sh restart [daemon|be|vnc|all]   # restart all=daemon+be(不含 mock);改了 .env/dist 后用;vnc=删旧容器换新镜像
+#   scripts/recorder.sh status                        # 看三端
+#   scripts/recorder.sh build   [core|be|ui|ext|all] # 重建 dist(改源码后;all 含扩展,需手动重载)
+#
+# 真实录制(带 LLM)启动:scripts/recorder.sh start   → 打开 http://127.0.0.1:19826/workbench
+#
+# embedded_iframe 录制模式(P2,公开站页内嵌入;**本机默认开**):起 be 默认带 flag——
+#   EMBEDDED=0 scripts/recorder.sh start              # 显式关闭页内嵌入模式
+#   IFRAME_FRAME_SRC=https://juejin.cn scripts/recorder.sh restart be   # 只放该 origin(hardened)
+#   inline env 经 `env VAR=…` 注入,优先级高于 --env-file(.env 不覆盖已存在的 process env)。
+#
+# vnc 录制模式(容器内 Chromium+扩展+daemon,noVNC 投画面;**本机默认开**,需 podman + 镜像):
+#   scripts/recorder.sh build vnc                     # 构建容器镜像 bycli-verify:latest(需先 build ext + npm run build)
+#   scripts/recorder.sh restart vnc                   # 重启镜像:删旧容器(bycli-vnc),be 下次 bind 用新镜像重建(改镜像后用)
+#   VNC=0 scripts/recorder.sh restart be              # 显式关闭 vnc 模式
+#   选 VNC 模式后 be 自动 podman run 起容器、前端 iframe 投 noVNC 画面;录的数据走容器网关→be→合成链。
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+RUN="$ROOT/.recorder-run"; mkdir -p "$RUN"
+DAEMON_PORT=19825; BE_PORT=19826; WEB_PORT=8000
+
+port_pid() { lsof -ti "tcp:$1" -sTCP:LISTEN 2>/dev/null | head -1; }
+alive()    { [ -n "${1:-}" ] && kill -0 "$1" 2>/dev/null; }
+
+# ───────────────────────── daemon(交给 bycli 管) ─────────────────────────
+need_bycli() { command -v bycli >/dev/null || { echo "✗ bycli 不在 PATH(在仓库根 npm link)"; return 1; }; }
+daemon_start()   { need_bycli || return 1; bycli daemon start   2>&1 | tail -1; }
+daemon_stop()    { need_bycli && { bycli daemon stop 2>&1 | tail -1; } || true; }
+daemon_restart() { need_bycli || return 1; bycli daemon restart 2>&1 | tail -1; }
+daemon_status()  { local p; p="$(port_pid $DAEMON_PORT)"; [ -n "$p" ] && echo "● daemon  RUNNING  :$DAEMON_PORT  pid=$p" || echo "○ daemon  stopped  :$DAEMON_PORT"; }
+
+# ───────────────────────── vnc(podman 容器,be 自动编排) ────────────────
+# 容器名与 vncOrchestrator.ts 保持一致(BYCLI_VNC_CONTAINER 覆盖,默认 bycli-vnc)。
+VNC_CONTAINER="${BYCLI_VNC_CONTAINER:-bycli-vnc}"
+VNC_IMAGE="${BYCLI_VNC_IMAGE:-bycli-verify:latest}"
+need_podman() { command -v podman >/dev/null || { echo "✗ podman 不在 PATH(VNC 模式需 podman)"; return 1; }; }
+# 重启镜像:删旧容器,be 下次 bind 时用当前镜像重建(build vnc 换镜像后调用)。
+vnc_restart() {
+  need_podman || return 1
+  [ -n "$(podman images -q "$VNC_IMAGE" 2>/dev/null)" ] || { echo "✗ 镜像 $VNC_IMAGE 不存在 → scripts/recorder.sh build vnc"; return 1; }
+  if [ -n "$(podman ps -aq -f "name=^${VNC_CONTAINER}$" 2>/dev/null)" ]; then
+    podman rm -f "$VNC_CONTAINER" >/dev/null 2>&1 && echo "✓ 已删旧容器 $VNC_CONTAINER(be 下次 bind 用新镜像 $VNC_IMAGE 重建)"
+  else
+    echo "○ 容器 $VNC_CONTAINER 未运行(be 下次 bind 会用新镜像 $VNC_IMAGE 新建)"
+  fi
+}
+vnc_stop() {
+  need_podman || return 1
+  if [ -n "$(podman ps -aq -f "name=^${VNC_CONTAINER}$" 2>/dev/null)" ]; then
+    podman rm -f "$VNC_CONTAINER" >/dev/null 2>&1 && echo "✓ vnc 容器 $VNC_CONTAINER 已删"
+  else echo "○ vnc 容器未运行"; fi
+}
+vnc_status() {
+  command -v podman >/dev/null || { echo "○ vnc     (podman 未装)"; return; }
+  local st; st="$(podman inspect "$VNC_CONTAINER" --format '{{.State.Status}}' 2>/dev/null)"
+  [ -n "$st" ] && echo "● vnc     $st  container=$VNC_CONTAINER  image=$VNC_IMAGE" || echo "○ vnc     no container  ($VNC_CONTAINER)"
+}
+
+# ───────────────────────── be(node 进程,PID 文件) ──────────────────────
+be_start() {
+  [ -f "$ROOT/dashboard-be/dist/server.js" ] || { echo "✗ be 未构建 → scripts/recorder.sh build be"; return 1; }
+  [ -f "$ROOT/dashboard-be/.env" ]           || { echo "✗ 缺 dashboard-be/.env → cp dashboard-be/.env.example dashboard-be/.env 并填值"; return 1; }
+  [ -d "$ROOT/dashboard/dist" ]              || echo "⚠ dashboard/dist 不存在,be 将 API-only(无 UI)→ scripts/recorder.sh build ui"
+  if [ -n "$(port_pid $BE_PORT)" ]; then echo "● be 已在 :$BE_PORT(先 stop/restart)"; return 0; fi
+  # embedded_iframe 模式(P2):EMBEDDED=1 → 注入 flag 开 frame-src + 前端模式选项。
+  # 经 `env VAR=…` 内联注入,优先级高于 --env-file(.env 不覆盖已存在的 process env)。
+  # 三种录制模式默认全开(本机录制工作台);显式 EMBEDDED=0 / VNC=0 可单独关。
+  # 注:只在本机 be 启动注入,不动 recorder-core 的 fail-closed 发布默认(全局 CSP 安全底线不变)。
+  local envv=()
+  if [ "${EMBEDDED:-1}" = 1 ]; then
+    envv+=(FEATURE_EMBEDDED_IFRAME_RECORDING=1)
+    [ -n "${IFRAME_FRAME_SRC:-}" ] && envv+=("RECORDER_IFRAME_FRAME_SRC=$IFRAME_FRAME_SRC")
+    echo "  ⚙ embedded_iframe 模式 ON${IFRAME_FRAME_SRC:+(frame-src=$IFRAME_FRAME_SRC)}"
+  fi
+  if [ "${VNC:-1}" = 1 ]; then
+    envv+=(FEATURE_VNC_RECORDING=1)
+    echo "  ⚙ vnc 容器模式 ON(be 自动 podman run bycli-verify:latest;需先 build vnc)"
+  fi
+  ( cd "$ROOT" && nohup env ${envv[@]+"${envv[@]}"} node --env-file=dashboard-be/.env dashboard-be/dist/server.js >"$RUN/be.log" 2>&1 & echo $! >"$RUN/be.pid" )
+  sleep 1; be_status; echo "  日志: $RUN/be.log"
+}
+be_stop() {
+  # 端口权威:pid 文件 + 实际占 19826 的进程都杀(防重复实例残留)
+  local stopped=0 pf; pf="$(cat "$RUN/be.pid" 2>/dev/null)"
+  for pid in "$pf" "$(port_pid $BE_PORT)"; do
+    if alive "$pid"; then kill "$pid" 2>/dev/null; echo "✓ be 已停(pid=$pid)"; stopped=1; fi
+  done
+  [ "$stopped" = 0 ] && echo "○ be 未运行"
+  rm -f "$RUN/be.pid"
+}
+be_restart() { be_stop; sleep 1; be_start; }
+be_status()  { local p; p="$(port_pid $BE_PORT)"; [ -n "$p" ] && echo "● be      RUNNING  http://127.0.0.1:$BE_PORT/workbench  pid=$p" || echo "○ be      stopped  :$BE_PORT"; }
+
+# ───────────────────────── web(Umi dev,mock) ───────────────────────────
+web_start() {
+  if [ -n "$(port_pid $WEB_PORT)" ]; then echo "● web 已在 :$WEB_PORT"; return 0; fi
+  ( cd "$ROOT/dashboard" && nohup npm run dev >"$RUN/web.log" 2>&1 & echo $! >"$RUN/web.pid" )
+  echo "✓ web 启动中(mock,http://127.0.0.1:$WEB_PORT)  日志: $RUN/web.log"
+}
+web_stop() {
+  local pid; pid="$(cat "$RUN/web.pid" 2>/dev/null)"; [ -z "$pid" ] && pid="$(port_pid $WEB_PORT)"
+  if alive "$pid"; then pkill -P "$pid" 2>/dev/null; kill "$pid" 2>/dev/null; echo "✓ web 已停"; else echo "○ web 未运行"; fi
+  rm -f "$RUN/web.pid"
+}
+web_restart() { web_stop; sleep 1; web_start; }
+web_status()  { local p; p="$(port_pid $WEB_PORT)"; [ -n "$p" ] && echo "● web     RUNNING  http://127.0.0.1:$WEB_PORT (mock)  pid=$p" || echo "○ web     stopped  :$WEB_PORT (mock dev)"; }
+
+# ───────────────────────── build ────────────────────────────────────────
+do_build() {
+  case "${1:-all}" in
+    core) npm --prefix "$ROOT/packages/recorder-core" run build ;;
+    be)   npm --prefix "$ROOT/dashboard-be" run build ;;
+    ui)   ( cd "$ROOT/dashboard" && npm run build ) ;;
+    ext)  ( cd "$ROOT/extension" && npm run build ) ;;
+    vnc)  # VNC 录制模式容器镜像(Chromium+扩展+daemon+x11vnc+websockify+网关);be 起容器时复用 bycli-verify:latest。
+          command -v podman >/dev/null || { echo "✗ podman 不在 PATH(VNC 模式需 podman)"; return 1; }
+          [ -f "$ROOT/extension/dist/background.js" ] || { echo "✗ 扩展未构建 → scripts/recorder.sh build ext"; return 1; }
+          [ -f "$ROOT/dist/src/daemon.js" ]            || { echo "✗ dist 未构建 → npm run build"; return 1; }
+          echo "▶ 构建 VNC 容器镜像 bycli-verify:latest(首次装 chromium 较慢)…"
+          ( cd "$ROOT" && podman build -f podman-verify/Dockerfile -t bycli-verify:latest . ) ;;
+    all)  npm --prefix "$ROOT/packages/recorder-core" run build \
+            && npm --prefix "$ROOT/dashboard-be" run build \
+            && ( cd "$ROOT/dashboard" && npm run build ) \
+            && ( cd "$ROOT/extension" && npm run build ) \
+            && echo "↻ 扩展已重建 → chrome://extensions 重载 byCLI(确认版本号刷新)" ;;
+    *) echo "build: core|be|ui|ext|vnc|all"; return 1 ;;
+  esac
+}
+
+# ───────────────────────── dispatch ─────────────────────────────────────
+action="${1:-}"; shift || true
+case "$action" in
+  start)
+    # mock 仅在显式 --mock 时启动;其余参数视作服务名
+    mock=0; svcs=()
+    for a in "$@"; do if [ "$a" = "--mock" ]; then mock=1; else svcs+=("$a"); fi; done
+    if [ "$mock" = 1 ]; then
+      echo "▶ 启动【mock 前端】(web :$WEB_PORT,假数据,无真实录制)"
+      web_start
+    elif [ ${#svcs[@]} -eq 0 ]; then
+      # 默认 = 真实录制环境:停掉 mock web(防 :8000 误测)→ 起 daemon + be
+      echo "▶ 启动【真实录制环境】(daemon + be);mock web 若在跑将被停掉以免混淆"
+      [ -n "$(port_pid $WEB_PORT)" ] && web_stop
+      daemon_start; be_start
+      echo; echo "✅ 真实录制 → http://127.0.0.1:$BE_PORT/workbench(mock 需 start --mock)"
+    else
+      [ "${svcs[0]}" = "all" ] && svcs=(daemon be)
+      for t in "${svcs[@]}"; do
+        case "$t" in
+          daemon|be) "${t}_start" ;;
+          web) echo "✗ web 是 mock,请用:scripts/recorder.sh start --mock" ;;
+          *) echo "未知服务: $t(daemon|be|all,mock 用 --mock)" ;;
+        esac
+      done
+    fi ;;
+  stop|restart)
+    # all 语义:restart 只起真实环境(daemon+be,不复活 mock,与 start 默认一致);
+    #          stop 则全停(含 mock web,teardown)。mock 启停一律显式 web/--mock。
+    if [ $# -eq 0 ]; then targets=(daemon be)
+    elif [ "${1:-}" = all ]; then
+      [ "$action" = stop ] && targets=(daemon be web) || targets=(daemon be)
+    else targets=("$@"); fi
+    [ "$action" = stop ] && targets=($(printf '%s\n' "${targets[@]}" | tail -r 2>/dev/null || printf '%s\n' "${targets[@]}"))
+    for t in "${targets[@]}"; do
+      case "$t" in daemon|be|web|vnc) "${t}_${action}" ;; *) echo "未知服务: $t(daemon|be|web|vnc|all)";; esac
+    done ;;
+  status)
+    daemon_status; be_status; web_status; vnc_status ;;
+  build)
+    do_build "${1:-all}" ;;
+  ""|-h|--help|help)
+    awk 'NR>1 && /^#/{sub(/^# ?/,"");print;next} NR>1{exit}' "${BASH_SOURCE[0]}" ;;
+  *)
+    echo "未知命令: $action(start|stop|restart|status|build)"; exit 1 ;;
+esac

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

@@ -1,124 +0,0 @@
-import { ArgumentError, CommandExecutionError } from '@sovovs/bycli/errors';
-
-export const MAX_PAGES = 100;
-export const MAX_PAGE_SIZE = 10;
-export const MAX_ARTICLES = 1000;
-
-export function isTrustedWechatArticleUrl(value) {
-  try {
-    const url = new URL(value);
-    return url.protocol === 'https:'
-      && url.hostname === 'mp.weixin.qq.com'
-      && url.port === ''
-      && url.username === ''
-      && url.password === ''
-      && (url.pathname === '/s' || url.pathname.startsWith('/s/'));
-  } catch {
-    return false;
-  }
-}
-
-/** @param {any} article */
-export function isUsableArticle(article) {
-  return Boolean(article)
-    && article.isDeleted !== true
-    && typeof article.url === 'string'
-    && isTrustedWechatArticleUrl(article.url)
-    && !article.url.includes('tempkey=');
-}
-
-function canonicalUrl(value) {
-  try {
-    const url = new URL(value);
-    url.hash = '';
-    return url.href;
-  } catch {
-    return value;
-  }
-}
-
-function publicArticle(article) {
-  return {
-    title: typeof article.title === 'string' ? article.title : '',
-    url: article.url,
-    publishedAt: typeof article.publishedAt === 'string' ? article.publishedAt : null,
-    digest: typeof article.digest === 'string' ? article.digest : '',
-    author: typeof article.author === 'string' ? article.author : '',
-  };
-}
-
-/**
- * @param {{fakeid:string,fetchPage:(input:{fakeid:string,begin:number,count:number})=>Promise<any>,limit?:number,maxPages?:number,pageSize?:number}} options
- */
-export async function collectArticles({ fakeid, fetchPage, limit, maxPages, pageSize = 10 }) {
-  for (const [name, value, maximum] of [
-    ['pageSize', pageSize, MAX_PAGE_SIZE],
-    ['limit', limit, MAX_ARTICLES],
-    ['maxPages', maxPages, MAX_PAGES],
-  ]) {
-    if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0)) {
-      throw new ArgumentError(`${name} must be a positive safe integer`);
-    }
-    if (value !== undefined && value > maximum) {
-      throw new ArgumentError(`${name} must not exceed ${maximum}`);
-    }
-  }
-  const pageLimit = maxPages ?? MAX_PAGES;
-  const articleLimit = limit ?? MAX_ARTICLES;
-  const articles = [];
-  const seen = new Set();
-  let totalFromApi = 0;
-  let scanned = 0;
-  let invalid = 0;
-  let duplicates = 0;
-  let pages = 0;
-  let begin = 0;
-
-  while (true) {
-    const page = await fetchPage({ fakeid, begin, count: pageSize });
-    pages += 1;
-    const pageTotal = page?.total === undefined ? 0 : page.total;
-    if (!Number.isSafeInteger(pageTotal) || pageTotal < 0) {
-      throw new CommandExecutionError('WeChat article history returned invalid total metadata');
-    }
-    if (pages === 1) totalFromApi = pageTotal;
-    const rawArticles = Array.isArray(page?.articles) ? page.articles : [];
-    const publishItemCount = page?.publishItemCount === undefined ? 0 : page.publishItemCount;
-    if (!Number.isSafeInteger(publishItemCount) || publishItemCount < 0) {
-      throw new CommandExecutionError('WeChat article history returned invalid publish-item metadata');
-    }
-
-    for (const article of rawArticles) {
-      scanned += 1;
-      if (!isUsableArticle(article)) {
-        invalid += 1;
-        continue;
-      }
-      const canonical = canonicalUrl(article.url);
-      if (seen.has(canonical)) {
-        duplicates += 1;
-        continue;
-      }
-      seen.add(canonical);
-      articles.push(publicArticle(article));
-      if (articles.length >= articleLimit) break;
-    }
-
-    const reachedLimit = articles.length >= articleLimit;
-    const reachedMaxPages = pages >= pageLimit;
-    const reachedEnd = publishItemCount === 0
-      || publishItemCount < pageSize
-      || (totalFromApi > 0 && begin + publishItemCount >= totalFromApi);
-    if (reachedLimit || reachedMaxPages || reachedEnd) break;
-    const nextBegin = begin + pageSize;
-    if (!Number.isSafeInteger(nextBegin) || nextBegin <= begin) {
-      throw new CommandExecutionError('WeChat article pagination could not advance safely');
-    }
-    begin = nextBegin;
-  }
-
-  return {
-    articles,
-    summary: { totalFromApi, scanned, valid: articles.length, invalid, duplicates, pages },
-  };
-}

package/clis/weixin/_wechat/save-service.js

@@ -1,176 +0,0 @@
-import * as defaultFs from 'node:fs';
-import path from 'node:path';
-import { ArgumentError, AuthRequiredError, CommandExecutionError } from '@sovovs/bycli/errors';
-import { cleanMarkdownFilename, wechatArticleToMarkdown } from './markdown.js';
-
-export const MAX_FILENAME_ATTEMPTS = 100;
-
-function commandError(action, error) {
-  return new CommandExecutionError(`Failed to ${action}: ${error instanceof Error ? error.message : String(error)}`);
-}
-
-function assertInside(root, target) {
-  const relative = path.relative(root, target);
-  if (relative === '' || relative.startsWith(`..${path.sep}`) || relative === '..' || path.isAbsolute(relative)) {
-    throw new CommandExecutionError('Refusing to save an article outside the output directory');
-  }
-}
-
-function sameIdentity(left, right) {
-  return left.dev === right.dev && left.ino === right.ino;
-}
-
-function assertResolvedPathComponents(root, fsImpl) {
-  const parsed = path.parse(root);
-  let current = parsed.root;
-  for (const part of root.slice(parsed.root.length).split(path.sep).filter(Boolean)) {
-    current = path.join(current, part);
-    const stat = fsImpl.lstatSync(current);
-    if (stat.isSymbolicLink?.()) throw new CommandExecutionError('Refusing to save through a symbolic link');
-  }
-}
-
-function assertRootIdentity(root, rootFd, rootIdentity, fsImpl) {
-  assertResolvedPathComponents(root, fsImpl);
-  const pathStat = fsImpl.lstatSync(root);
-  const fdStat = fsImpl.fstatSync(rootFd);
-  if (!pathStat.isDirectory?.() || !fdStat.isDirectory?.()
-      || !sameIdentity(pathStat, rootIdentity) || !sameIdentity(fdStat, rootIdentity)) {
-    throw new CommandExecutionError('Output directory identity changed during save');
-  }
-}
-
-function cleanupOpenedTarget(target, openedStat, fsImpl) {
-  try {
-    const current = fsImpl.lstatSync(target);
-    if (sameIdentity(current, openedStat) && !current.isSymbolicLink?.()) fsImpl.unlinkSync(target);
-  } catch {
-    // Fail closed; cleanup is best effort after identity mismatch.
-  }
-}
-
-function writeExclusive(root, rootFd, rootIdentity, target, markdown, fsImpl) {
-  const noFollow = defaultFs.constants.O_NOFOLLOW;
-  if (typeof noFollow !== 'number') {
-    throw new CommandExecutionError('Secure article saving is unavailable: O_NOFOLLOW is unsupported');
-  }
-  // The opened root fd plus its dev/ino is the authorization capability.
-  // Path checks detect namespace replacement, but cannot and need not prevent
-  // a same-privilege process from renaming that already-authorized inode.
-  assertRootIdentity(root, rootFd, rootIdentity, fsImpl);
-  let fd;
-  let openedStat;
-  try {
-    fd = fsImpl.openSync(target,
-      defaultFs.constants.O_CREAT | defaultFs.constants.O_EXCL | defaultFs.constants.O_WRONLY | noFollow,
-      0o600);
-    // Once open succeeds, this fd remains bound to that inode; later renames
-    // or symlink swaps cannot redirect its writes into a replacement root.
-    openedStat = fsImpl.fstatSync(fd);
-    if (!openedStat.isFile?.() || openedStat.isSymbolicLink?.()) {
-      throw new CommandExecutionError('Refusing to write a non-regular article target');
-    }
-    assertRootIdentity(root, rootFd, rootIdentity, fsImpl);
-    const body = Buffer.from(markdown, 'utf8');
-    let offset = 0;
-    while (offset < body.length) {
-      const written = fsImpl.writeSync(fd, body, offset, body.length - offset);
-      if (!Number.isInteger(written) || written <= 0) throw new CommandExecutionError('Failed to write article bytes');
-      offset += written;
-    }
-    fsImpl.fsyncSync?.(fd);
-    assertRootIdentity(root, rootFd, rootIdentity, fsImpl);
-  } catch (error) {
-    if (openedStat) cleanupOpenedTarget(target, openedStat, fsImpl);
-    throw error;
-  } finally {
-    if (fd !== undefined) fsImpl.closeSync(fd);
-  }
-}
-
-export async function saveArticles({ articles, accountName, outputDir, fetchArticleHtml, buildMarkdown = wechatArticleToMarkdown, fsImpl = defaultFs }) {
-  if (!Array.isArray(articles) || articles.length > 1000) {
-    throw new ArgumentError('articles must be an array of at most 1000 items');
-  }
-  const requestedRoot = path.resolve(outputDir);
-  try { fsImpl.mkdirSync(requestedRoot, { recursive: true }); } catch (error) { throw commandError('create output directory', error); }
-  let root;
-  try { root = fsImpl.realpathSync(requestedRoot); } catch (error) { throw commandError('resolve output directory', error); }
-  let rootFd;
-  let rootIdentity;
-  try {
-    assertResolvedPathComponents(root, fsImpl);
-    rootIdentity = fsImpl.lstatSync(root);
-    if (!rootIdentity.isDirectory?.() || rootIdentity.isSymbolicLink?.()) throw new Error('not a directory');
-    rootFd = fsImpl.openSync(root, defaultFs.constants.O_RDONLY);
-    const openedRoot = fsImpl.fstatSync(rootFd);
-    if (!openedRoot.isDirectory?.() || !sameIdentity(openedRoot, rootIdentity)) {
-      throw new CommandExecutionError('Output directory identity changed during secure open');
-    }
-    assertRootIdentity(root, rootFd, rootIdentity, fsImpl);
-  } catch (error) {
-    if (rootFd !== undefined) fsImpl.closeSync(rootFd);
-    if (error instanceof CommandExecutionError) throw error;
-    throw commandError('secure output directory', error);
-  }
-  const reserved = new Set();
-  const rows = [];
-
-  try {
-    for (const article of articles) {
-      let articleHtml;
-      try {
-        articleHtml = await fetchArticleHtml(article);
-      } catch (error) {
-        if (error instanceof AuthRequiredError) throw error;
-        rows.push({ title: article.title || '', url: article.url || '', status: 'failed', stage: 'download', saved: '', error: 'article download failed' });
-        continue;
-      }
-      let markdown;
-      try {
-        markdown = buildMarkdown({ html: articleHtml, title: article.title, accountName,
-          author: article.author, publishedAt: article.publishedAt, digest: article.digest, url: article.url });
-      } catch {
-        rows.push({ title: article.title || '', url: article.url || '', status: 'failed', stage: 'download', saved: '', error: 'invalid article content' });
-        continue;
-      }
-
-      let suffix = 1;
-      let target;
-      while (suffix <= MAX_FILENAME_ATTEMPTS) {
-        const suffixText = suffix === 1 ? '' : `-${suffix}`;
-        const name = `${cleanMarkdownFilename(article.title, 100, suffixText)}${suffixText}`;
-        target = path.resolve(root, `${name}.md`);
-        assertInside(root, target);
-        if (reserved.has(target)) { suffix += 1; continue; }
-        try {
-          const stat = fsImpl.lstatSync(target);
-          if (stat.isSymbolicLink?.()) throw new CommandExecutionError('Refusing to overwrite a symbolic link');
-          suffix += 1;
-          continue;
-        } catch (error) {
-          if (error instanceof CommandExecutionError) throw error;
-          if (error?.code !== 'ENOENT') throw commandError('inspect article target', error);
-        }
-        try {
-          writeExclusive(root, rootFd, rootIdentity, target, markdown, fsImpl);
-          reserved.add(target);
-          break;
-        } catch (error) {
-          if (error?.code === 'EEXIST') {
-            suffix += 1;
-            continue;
-          }
-          throw commandError('write article Markdown', error);
-        }
-      }
-      if (suffix > MAX_FILENAME_ATTEMPTS) {
-        throw new CommandExecutionError(`Failed to reserve an article filename after ${MAX_FILENAME_ATTEMPTS} attempts`);
-      }
-      rows.push({ title: article.title || '', url: article.url || '', status: 'saved', stage: null, saved: target, error: '' });
-    }
-  } finally {
-    fsImpl.closeSync(rootFd);
-  }
-  return rows;
-}

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

@@ -1,133 +0,0 @@
-import { AuthRequiredError, CommandExecutionError } from '@sovovs/bycli/errors';
-import { buildSecretSet, redactText } from './redact.js';
-
-const DOMAIN = 'mp.weixin.qq.com';
-const ENDPOINT = `https://${DOMAIN}/cgi-bin/appmsgpublish`;
-
-function normalizedMessage(value) {
-  return String(value ?? '').trim().toLowerCase().replace(/\s+/g, ' ');
-}
-
-function commandError(message) {
-  return new CommandExecutionError(redactText(message, []));
-}
-
-function parseNestedJson(value, label) {
-  if (typeof value !== 'string') return value;
-  try {
-    return JSON.parse(value);
-  } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
-    throw commandError(`WeChat ${label} is malformed: ${detail}`);
-  }
-}
-
-/** @param {unknown} data */
-export function parsePublishData(data) {
-  if (!data || typeof data !== 'object') {
-    throw new CommandExecutionError('WeChat article history returned an unreadable response');
-  }
-  const response = /** @type {Record<string, any>} */ (data);
-  const ret = response.base_resp?.ret;
-  const message = response.base_resp?.err_msg ?? response.base_resp?.err_msg_en ?? '';
-  if (ret === 200013 && normalizedMessage(message) === 'invalid credential') {
-    throw new AuthRequiredError(DOMAIN, 'WeChat article-history credentials have expired');
-  }
-  if (ret !== undefined && ret !== 0) {
-    throw new CommandExecutionError(`WeChat article history failed (ret=${String(ret)})`);
-  }
-  if (response.publish_page === undefined || response.publish_page === null || response.publish_page === '') {
-    return { total: 0, publishItemCount: 0, articles: [] };
-  }
-  const page = parseNestedJson(response.publish_page, 'publish_page');
-  if (!page || typeof page !== 'object' || !Array.isArray(page.publish_list)) {
-    throw new CommandExecutionError('WeChat article history returned an invalid publish page');
-  }
-  const total = page.total_count === undefined ? 0 : page.total_count;
-  if (!Number.isSafeInteger(total) || total < 0) {
-    throw new CommandExecutionError('WeChat article history returned invalid total metadata');
-  }
-  const articles = [];
-  for (const item of page.publish_list) {
-    const info = parseNestedJson(item?.publish_info ?? {}, 'publish_info');
-    if (!info || typeof info !== 'object' || !Array.isArray(info.appmsg_info)) {
-      throw new CommandExecutionError('WeChat article history returned invalid publish information');
-    }
-    const timestamp = info.sent_info?.time ?? info.publish_info?.create_time ?? 0;
-    let publishedAt = null;
-    if (timestamp !== 0) {
-      if (typeof timestamp !== 'number' || !Number.isFinite(timestamp) || timestamp <= 0) {
-        throw new CommandExecutionError('WeChat article history returned an invalid publish timestamp');
-      }
-      const date = new Date(timestamp * 1000);
-      if (!Number.isFinite(date.getTime())) {
-        throw new CommandExecutionError('WeChat article history returned an invalid publish timestamp');
-      }
-      publishedAt = date.toISOString();
-    }
-    for (const messageItem of info.appmsg_info) {
-      const article = messageItem && typeof messageItem === 'object' ? messageItem : {};
-      articles.push({
-        title: typeof article.title === 'string' ? article.title : '',
-        url: typeof article.content_url === 'string' ? article.content_url : '',
-        isDeleted: article.is_deleted === true,
-        timestamp,
-        publishedAt,
-        digest: typeof article.digest === 'string' ? article.digest : '',
-        author: typeof article.author === 'string' ? article.author : '',
-      });
-    }
-  }
-  return {
-    total,
-    publishItemCount: page.publish_list.length,
-    articles,
-  };
-}
-
-export function requestHeaders(cookie, token) {
-  return {
-    Accept: 'application/json, text/javascript, */*; q=0.01',
-    Cookie: cookie,
-    Origin: `https://${DOMAIN}`,
-    Referer: `https://${DOMAIN}/cgi-bin/appmsg?t=media/appmsg_edit_v2&action=edit&isNew=1&type=10&token=${encodeURIComponent(token)}&lang=zh_CN`,
-    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/143 Safari/537.36',
-    'X-Requested-With': 'XMLHttpRequest',
-  };
-}
-
-/**
- * @param {{token:string,cookie:string,timeoutMs?:number,fetchImpl?:typeof fetch}} options
- */
-export function createWechatApi({ token, cookie, timeoutMs = 30_000, fetchImpl = fetch }) {
-  const headers = requestHeaders(cookie, token);
-  const secrets = buildSecretSet({ token, cookie });
-
-  return {
-    async fetchPage({ fakeid, begin = 0, count = 10 }) {
-      const query = new URLSearchParams({
-        sub: 'list', begin: String(begin), count: String(count), fakeid, token,
-        lang: 'zh_CN', f: 'json', ajax: '1',
-      });
-      try {
-        const response = await fetchImpl(`${ENDPOINT}?${query}`, {
-          headers,
-          signal: AbortSignal.timeout(timeoutMs),
-        });
-        if (!response.ok) {
-          throw new CommandExecutionError(`WeChat article history request failed: HTTP ${response.status} ${response.statusText ?? ''}`.trim());
-        }
-        return parsePublishData(await response.json());
-      } catch (error) {
-        if (error instanceof AuthRequiredError && error.domain === DOMAIN) throw error;
-        const message = error instanceof Error ? error.message : String(error);
-        const hint = error && typeof error === 'object' && 'hint' in error && typeof error.hint === 'string'
-          ? error.hint : undefined;
-        throw new CommandExecutionError(
-          `WeChat article history request failed: ${redactText(message, secrets)}`,
-          hint ? redactText(hint, secrets) : undefined,
-        );
-      }
-    },
-  };
-}