@sovovs/bycli 2.1.34 → 2.1.36

package/cli-manifest.json

@@ -28292,49 +28292,87 @@
   {
     "site": "weixin",
     "name": "create-draft",
-    "description": "创建微信公众号图文草稿",
+    "description": "创建微信公众号草稿（支持浏览器富文本或官方 API）",
     "access": "write",
+    "example": "bycli weixin create-draft --title \"文章标题\" --content-file article.html --content-format html --cover-image cover.jpg",
     "domain": "mp.weixin.qq.com",
     "strategy": "cookie",
-    "browser": true,
+    "browser": "conditional",
     "args": [
       {
         "name": "title",
         "type": "str",
         "required": true,
-        "help": "文章标题 (最长64字)"
+        "help": "文章标题（最长 64 字）"
       },
       {
         "name": "content",
         "type": "str",
-        "required": true,
+        "required": false,
         "positional": true,
-        "help": "文章正文"
+        "help": "正文文本；也可用 --content-file 读取 HTML 文件"
+      },
+      {
+        "name": "content-file",
+        "type": "str",
+        "required": false,
+        "help": "正文文件路径；HTML 模式支持本地图片"
+      },
+      {
+        "name": "content-format",
+        "type": "str",
+        "default": "text",
+        "required": false,
+        "help": "正文格式：text=纯文本，html=富文本，html-text=保留段落但忽略样式",
+        "choices": [
+          "text",
+          "html",
+          "html-text"
+        ]
       },
       {
         "name": "author",
         "type": "str",
         "required": false,
-        "help": "作者名 (最长8字)"
+        "help": "作者名（最长 8 字）"
       },
       {
         "name": "cover-image",
         "type": "str",
         "required": false,
-        "help": "封面图片路径 (会先上传到正文再设为封面)"
+        "help": "封面图路径；API 模式必填，浏览器模式会上传后设为封面"
       },
       {
         "name": "summary",
         "type": "str",
         "required": false,
-        "help": "文章摘要"
+        "help": "文章摘要；API 模式对应 digest"
+      },
+      {
+        "name": "appid",
+        "type": "str",
+        "required": false,
+        "help": "公众号 AppID；与 --appsecret 同传时走官方 API，不打开浏览器"
+      },
+      {
+        "name": "appsecret",
+        "type": "str",
+        "required": false,
+        "help": "公众号 AppSecret；请勿提交到 shell 历史或日志"
+      },
+      {
+        "name": "dry-run",
+        "type": "boolean",
+        "default": false,
+        "required": false,
+        "help": "浏览器模式：填充并验证正文后停止，不会保存草稿"
       },
       {
         "name": "timeout",
         "type": "int",
         "default": 180,
         "required": false,
-        "help": "Max seconds for the overall command (default: 180)"
+        "help": "命令总超时时间（秒，默认 180）"
       }
     ],
     "columns": [

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

@@ -0,0 +1,114 @@
+import * as nodeFs from 'node:fs/promises';
+import * as nodePath from 'node:path';
+import { CommandExecutionError } from '@sovovs/bycli/errors';
+import { prepareHtmlContent } from './draft-content.js';
+
+const API_BASE = 'https://api.weixin.qq.com/cgi-bin';
+
+function apiError(context, payload) {
+  const code = payload?.errcode == null ? 'unknown' : payload.errcode;
+  const message = payload?.errmsg || 'unknown error';
+  return new CommandExecutionError(`${context} failed (${code}): ${message}`);
+}
+
+async function readJsonResponse(response, context) {
+  let payload;
+  try {
+    payload = await response.json();
+  } catch (error) {
+    throw new CommandExecutionError(`${context} returned invalid JSON: ${error?.message ?? error}`);
+  }
+  if (!response.ok) throw new CommandExecutionError(`${context} returned HTTP ${response.status}`);
+  if (payload?.errcode != null && payload.errcode !== 0) throw apiError(context, payload);
+  return payload;
+}
+
+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);
+  url.searchParams.set('secret', appsecret);
+  const response = await fetchImpl(url.toString(), { method: 'GET' });
+  const payload = await readJsonResponse(response, '获取 access_token');
+  if (!payload.access_token) throw new CommandExecutionError('获取 access_token failed: response did not contain access_token');
+  return payload.access_token;
+}
+
+function mimeType(filePath) {
+  const extension = nodePath.extname(filePath).toLowerCase();
+  if (extension === '.png') return 'image/png';
+  if (extension === '.gif') return 'image/gif';
+  if (extension === '.webp') return 'image/webp';
+  return 'image/jpeg';
+}
+
+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));
+  const url = new URL(`${API_BASE}/material/add_material`);
+  url.searchParams.set('access_token', token);
+  url.searchParams.set('type', 'image');
+  const response = await fetchImpl(url.toString(), { method: 'POST', body: form });
+  const payload = await readJsonResponse(response, '上传图片');
+  if (!payload.media_id) throw new CommandExecutionError('上传图片 failed: response did not contain media_id');
+  return payload;
+}
+
+function removeCoverImage(html) {
+  return String(html ?? '').replace(/<img\b[^>]*(?:alt|title)=["'][^"']*封面[^"']*["'][^>]*>\s*/giu, '');
+}
+
+export async function createDraftViaApi({
+  appid,
+  appsecret,
+  title,
+  author = '',
+  digest = '',
+  coverImage,
+  html,
+  baseDir = process.cwd(),
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  if (!String(appid ?? '').trim() || !String(appsecret ?? '').trim()) {
+    throw new CommandExecutionError('API mode requires both appid and appsecret');
+  }
+  if (typeof fetchImpl !== 'function') throw new CommandExecutionError('API mode requires fetch support');
+  if (!coverImage) throw new CommandExecutionError('API mode requires cover-image');
+
+  const token = await getAccessToken(String(appid).trim(), String(appsecret).trim(), fetchImpl);
+  const cover = await uploadImage(nodePath.resolve(coverImage), token, fetchImpl);
+  const prepared = await prepareHtmlContent(removeCoverImage(html), {
+    baseDir,
+    resolveImage: async imagePath => {
+      const uploaded = await uploadImage(imagePath, token, fetchImpl);
+      return uploaded.url || uploaded.media_id;
+    },
+  });
+
+  const url = new URL(`${API_BASE}/draft/add`);
+  url.searchParams.set('access_token', token);
+  const body = {
+    articles: [{
+      title: String(title ?? ''),
+      author: String(author ?? ''),
+      digest: String(digest || title || ''),
+      content: prepared.html,
+      content_source_url: '',
+      thumb_media_id: cover.media_id,
+      show_cover_pic: 1,
+      need_open_comment: 0,
+      only_fans_can_comment: 0,
+    }],
+  };
+  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');
+  return { mediaId: payload.media_id };
+}
+
+export { removeCoverImage };

package/clis/weixin/_wechat/draft-content.js

@@ -0,0 +1,208 @@
+import * as nodeFs from 'node:fs';
+import * as nodePath from 'node:path';
+import { ArgumentError, CommandExecutionError } from '@sovovs/bycli/errors';
+import { parseWechatHtmlFragment, serializeWechatHtml } from '@sovovs/bycli/download/article-download';
+
+const DROP_TAGS = new Set(['base', 'embed', 'form', 'iframe', 'link', 'meta', 'object', 'script', 'style', 'template']);
+const ALLOWED_TAGS = new Set([
+  'a', 'b', 'blockquote', 'br', 'code', 'div', 'em', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+  'i', 'img', 'li', 'ol', 'p', 'pre', 'section', 'span', 'strong', 'table', 'tbody', 'td',
+  'tfoot', 'th', 'thead', 'tr', 'u', 'ul',
+]);
+const IMPORTANT_STYLE_PROPERTIES = new Set([
+  'background', 'background-color', 'border', 'border-radius', 'color', 'display',
+  'font-size', 'line-height', 'margin', 'margin-bottom', 'padding', 'text-align', 'text-indent',
+  'vertical-align',
+]);
+
+export function htmlToPlainText(html) {
+  return String(html ?? '')
+    .replace(/<(?:br)\b[^>]*>/giu, '\n')
+    .replace(/<\/(?:p|div|section|h[1-6]|li|tr|blockquote|table)>/giu, '\n')
+    .replace(/<[^>]*>/gu, '')
+    .replace(/&nbsp;/giu, ' ')
+    .replace(/&amp;/giu, '&')
+    .replace(/&lt;/giu, '<')
+    .replace(/&gt;/giu, '>')
+    .replace(/[\t \f\v]+/gu, ' ')
+    .replace(/ *\n */gu, '\n')
+    .replace(/\n{3,}/gu, '\n\n')
+    .trim();
+}
+
+function attributes(node) {
+  return Array.isArray(node.attrs) ? node.attrs : [];
+}
+
+function setAttribute(node, name, value) {
+  const attr = attributes(node).find(item => item.name === name);
+  if (attr) attr.value = value;
+  else node.attrs.push({ name, value });
+}
+
+function removeAttribute(node, name) {
+  node.attrs = attributes(node).filter(attr => attr.name !== name);
+}
+
+function normalizeStyle(value) {
+  return String(value ?? '')
+    .replace(/box-shadow\s*:[^;]+;?/giu, '')
+    .replace(/text-shadow\s*:[^;]+;?/giu, '')
+    .replace(/background\s*:\s*linear-gradient\([^;]+\);?/giu, '')
+    .replace(/background\s*:\s*([#a-z0-9(),.%\s-]+);/giu, 'background-color: $1;')
+    .split(';')
+    .map(declaration => declaration.trim())
+    .filter(Boolean)
+    .map(declaration => {
+      const separator = declaration.indexOf(':');
+      if (separator < 0) return '';
+      const property = declaration.slice(0, separator).trim().toLowerCase();
+      let valuePart = declaration.slice(separator + 1).trim();
+      if (property === 'text-indent') valuePart = '0';
+      if (IMPORTANT_STYLE_PROPERTIES.has(property) && !/!important$/iu.test(valuePart)) {
+        valuePart += ' !important';
+      }
+      return `${property}: ${valuePart}`;
+    })
+    .filter(Boolean)
+    .join('; ');
+}
+
+function convertBackgroundSection(node) {
+  const tag = String(node.tagName ?? node.nodeName ?? '').toLowerCase();
+  if (tag !== 'section' && tag !== 'div') return;
+  const styleAttr = attributes(node).find(attr => attr.name === 'style');
+  const style = String(styleAttr?.value ?? '');
+  if (!style || !/background(?:-color)?\s*:/iu.test(style) || /font-family\s*:/iu.test(style)) return;
+
+  const children = node.childNodes ?? [];
+  const td = {
+    nodeName: 'td', tagName: 'td', namespaceURI: 'http://www.w3.org/1999/xhtml',
+    attrs: [{ name: 'style', value: normalizeStyle(style) }], childNodes: children,
+  };
+  const tr = {
+    nodeName: 'tr', tagName: 'tr', namespaceURI: 'http://www.w3.org/1999/xhtml',
+    attrs: [], childNodes: [td],
+  };
+  node.nodeName = 'table';
+  node.tagName = 'table';
+  node.attrs = [{
+    name: 'style',
+    value: 'width: 100% !important; border-collapse: separate !important; border-spacing: 0 !important; border-radius: 10px !important; overflow: hidden !important',
+  }];
+  node.childNodes = [tr];
+}
+
+function safeUrl(value, { image = false } = {}) {
+  const raw = String(value ?? '').trim();
+  if (!raw || raw.startsWith('javascript:') || raw.startsWith('data:')) return null;
+  if (image && raw.startsWith('blob:')) return null;
+  if (!image && !/^(?:https?:|mailto:)/iu.test(raw)) return null;
+  return raw;
+}
+
+function sanitizeAttributes(node) {
+  for (const attr of [...attributes(node)]) {
+    const name = attr.name.toLowerCase();
+    if (name.startsWith('on') || name === 'id' || name === 'class' || name === 'srcset') {
+      removeAttribute(node, attr.name);
+      continue;
+    }
+    if (name === 'style') {
+      const style = normalizeStyle(String(attr.value ?? '')
+        .replace(/url\s*\([^)]*\)/giu, '')
+        .replace(/expression\s*\([^)]*\)/giu, '')
+        .replace(/-moz-binding\s*:[^;]+;?/giu, ''));
+      if (style) setAttribute(node, 'style', style);
+      else removeAttribute(node, attr.name);
+      continue;
+    }
+    if (name === 'href') {
+      const url = safeUrl(attr.value);
+      if (url) setAttribute(node, 'href', url);
+      else removeAttribute(node, attr.name);
+      continue;
+    }
+    if (name === 'src' && node.tagName === 'img') continue;
+    if (name !== 'alt' && name !== 'title' && name !== 'target' && name !== 'rel') {
+      removeAttribute(node, attr.name);
+    }
+  }
+}
+
+async function sanitizeNode(node, options) {
+  if (!node || typeof node !== 'object') return;
+  if (node.nodeName === '#text') return;
+  if (node.nodeName === '#comment') {
+    node.nodeName = '#text';
+    node.value = '';
+    delete node.data;
+    return;
+  }
+
+  const tag = String(node.tagName ?? node.nodeName ?? '').toLowerCase();
+  if (DROP_TAGS.has(tag)) {
+    node.childNodes = [];
+    node.tagName = 'div';
+    node.nodeName = 'div';
+    node.attrs = [];
+  } else if (!ALLOWED_TAGS.has(tag)) {
+    node.tagName = 'span';
+    node.nodeName = 'span';
+    sanitizeAttributes(node);
+  } else {
+    sanitizeAttributes(node);
+  }
+
+  convertBackgroundSection(node);
+
+  if (tag === 'img') {
+    const source = attributes(node).find(attr => attr.name === 'src')?.value;
+    const url = safeUrl(source, { image: true });
+    if (!url) throw new CommandExecutionError('HTML contains an unsupported image source');
+    const isRemote = /^https?:\/\//iu.test(url);
+    const resolved = isRemote ? url : await options.resolveImage(url);
+    if (!resolved) throw new CommandExecutionError(`Could not upload HTML image: ${url}`);
+    setAttribute(node, 'src', resolved);
+  }
+
+  for (const child of node.childNodes ?? []) await sanitizeNode(child, options);
+}
+
+export function loadDraftContent({ content, contentFile, contentFormat = 'text' }) {
+  const format = String(contentFormat ?? 'text').toLowerCase();
+  if (!['html', 'html-text', 'text'].includes(format)) throw new ArgumentError('content-format must be html, html-text, or text');
+  if (contentFile) {
+    const filePath = nodePath.resolve(String(contentFile));
+    let fileContent;
+    try {
+      fileContent = nodeFs.readFileSync(filePath, 'utf8');
+    } catch {
+      throw new ArgumentError(`content-file must be a readable file: ${filePath}`);
+    }
+    if (!fileContent.trim()) throw new ArgumentError('content-file must not be empty');
+    return {
+      format: format === 'html-text' ? 'text' : format,
+      content: format === 'html-text' ? htmlToPlainText(fileContent) : fileContent,
+      filePath,
+    };
+  }
+  const value = String(content ?? '');
+  if (!value.trim()) throw new ArgumentError('content or content-file must not be empty');
+  return {
+    format: format === 'html-text' ? 'text' : format,
+    content: format === 'html-text' ? htmlToPlainText(value) : value,
+    filePath: null,
+  };
+}
+
+export async function prepareHtmlContent(html, { baseDir = process.cwd(), resolveImage } = {}) {
+  if (typeof resolveImage !== 'function') throw new ArgumentError('resolveImage is required for HTML content');
+  const fragment = parseWechatHtmlFragment(String(html ?? ''));
+  const imageResolver = async source => {
+    const absolute = /^https?:\/\//iu.test(source) ? source : nodePath.resolve(baseDir, source);
+    return resolveImage(absolute);
+  };
+  await Promise.all((fragment.childNodes ?? []).map(node => sanitizeNode(node, { resolveImage: imageResolver })));
+  return { html: serializeWechatHtml(fragment) };
+}

package/clis/weixin/_wechat/html-clipboard.js

@@ -0,0 +1,141 @@
+import { CommandExecutionError } from '@sovovs/bycli/errors';
+
+const RICH_NODE_PATTERN = /<(?:p|h[1-6]|strong|em|a|ul|ol|table|img|div|section|span)\b/i;
+
+function plainTextFromHtml(html) {
+  return String(html ?? '')
+    .replace(/<br\s*\/?>/giu, '\n')
+    .replace(/<[^>]*>/gu, ' ')
+    .replace(/&nbsp;/giu, ' ')
+    .replace(/&amp;/giu, '&')
+    .replace(/&lt;/giu, '<')
+    .replace(/&gt;/giu, '>')
+    .replace(/\s+/gu, ' ')
+    .trim();
+}
+
+function clipboardWriteScript(html, text) {
+  return `(() => {
+    const html = ${JSON.stringify(html)};
+    const text = ${JSON.stringify(text)};
+    if (!navigator.clipboard || typeof navigator.clipboard.write !== 'function' || typeof ClipboardItem !== 'function') {
+      return { ok: false, reason: 'Clipboard API is unavailable' };
+    }
+    const item = new ClipboardItem({
+      'text/html': new Blob([html], { type: 'text/html' }),
+      'text/plain': new Blob([text], { type: 'text/plain' }),
+    });
+    return navigator.clipboard.write([item])
+      .then(() => ({ ok: true }))
+      .catch(error => ({ ok: false, reason: error && error.message ? error.message : String(error) }));
+  })()`;
+}
+
+function editorReadScript() {
+  return `(() => {
+    const ueditor = document.querySelector('#ueditor_0');
+    const iframeBody = ueditor?.tagName === 'IFRAME' ? ueditor.contentDocument?.body : null;
+    const scopedEditors = [...document.querySelectorAll('#js_ueditor [contenteditable="true"], #js_editor [contenteditable="true"]')];
+    const visibleEditors = scopedEditors.filter(node => node.offsetParent !== null);
+    const editor = iframeBody || (ueditor?.matches?.('[contenteditable="true"]') ? ueditor : null)
+      || visibleEditors[visibleEditors.length - 1];
+    if (!editor) return { ok: false, reason: 'contenteditable editor not found' };
+    const warning = [...document.querySelectorAll('.weui-desktop-dialog__wrp, .weui-desktop-dialog')]
+      .some(dialog => {
+        const wrap = dialog.closest('.weui-desktop-dialog__wrp') || dialog;
+        return window.getComputedStyle(wrap).display !== 'none'
+          && wrap.offsetHeight > 0
+          && (dialog.innerText || '').includes('\u5b89\u5168\u9690\u60a3');
+      });
+    return { ok: true, warning, html: editor.innerHTML || '', text: editor.innerText || editor.textContent || '' };
+  })()`;
+}
+
+export async function pasteHtmlThroughClipboard(page, html, {
+  origin = 'https://mp.weixin.qq.com',
+  platform = process.platform,
+} = {}) {
+  if (typeof page?.cdp !== 'function') {
+    throw new CommandExecutionError('Rich HTML paste requires Browser Bridge CDP support');
+  }
+  if (typeof page?.evaluate !== 'function' || typeof page?.nativeKeyPress !== 'function' || typeof page?.nativeClick !== 'function') {
+    throw new CommandExecutionError('Rich HTML paste requires page evaluation and native key support');
+  }
+
+  const source = String(html ?? '');
+  if (!source.trim()) throw new CommandExecutionError('Rich HTML content must not be empty');
+
+  if (typeof page.focusWindow === 'function') {
+    try { await page.focusWindow(); } catch { /* the native paste will report focus failures */ }
+  }
+
+  try {
+    await page.cdp('Browser.grantPermissions', {
+      origin,
+      permissions: ['clipboardReadWrite', 'clipboardSanitizedWrite'],
+    });
+  } catch (error) {
+    const message = String(error?.message ?? error);
+    if (!message.includes('CDP method not permitted: Browser.grantPermissions')) {
+      throw new CommandExecutionError(`Could not grant clipboard permission: ${message}`);
+    }
+  }
+
+  const editorLocation = await page.evaluate(`(() => {
+    const ueditor = document.querySelector('#ueditor_0');
+    const iframeBody = ueditor?.tagName === 'IFRAME' ? ueditor.contentDocument?.body : null;
+    const scopedEditors = [...document.querySelectorAll('#js_ueditor [contenteditable="true"], #js_editor [contenteditable="true"]')];
+    const visibleEditors = scopedEditors.filter(node => node.offsetParent !== null);
+    const editor = iframeBody || (ueditor?.matches?.('[contenteditable="true"]') ? ueditor : null)
+      || visibleEditors[visibleEditors.length - 1];
+    if (!editor) return { ok: false, reason: 'contenteditable editor not found' };
+    const rect = (ueditor?.tagName === 'IFRAME' ? ueditor : editor).getBoundingClientRect();
+    return {
+      ok: rect.width > 0 && rect.height > 0,
+      rect: { x: rect.left, y: rect.top, width: rect.width, height: rect.height },
+    };
+  })()`);
+  if (!editorLocation?.ok) throw new CommandExecutionError(`Could not locate rich-text editor: ${editorLocation?.reason ?? 'unknown error'}`);
+
+  if (typeof page.focusWindow === 'function') {
+    try { await page.focusWindow(); } catch { /* the clipboard write reports the actionable error */ }
+  }
+  const x = Math.round(editorLocation.rect.x + editorLocation.rect.width / 2);
+  const y = Math.round(editorLocation.rect.y + editorLocation.rect.height / 2);
+  await page.nativeClick(x, y);
+
+  const written = await page.evaluate(clipboardWriteScript(source, plainTextFromHtml(source)));
+  if (!written?.ok) throw new CommandExecutionError(`Could not write HTML to clipboard: ${written?.reason ?? 'unknown error'}`);
+
+  const shortcut = platform === 'darwin' ? ['Meta'] : ['Ctrl'];
+  try {
+    await page.nativeKeyPress('v', shortcut);
+  } catch {
+    const modifiers = platform === 'darwin' ? 4 : 2;
+    await page.cdp('Input.dispatchKeyEvent', {
+      type: 'keyDown', key: 'v', code: 'KeyV', modifiers,
+      windowsVirtualKeyCode: 86, nativeVirtualKeyCode: 86,
+    });
+    await page.cdp('Input.dispatchKeyEvent', {
+      type: 'keyUp', key: 'v', code: 'KeyV', modifiers,
+      windowsVirtualKeyCode: 86, nativeVirtualKeyCode: 86,
+    });
+  }
+  if (typeof page.wait === 'function') await page.wait(1);
+
+  const result = await page.evaluate(editorReadScript());
+  if (result?.warning) {
+    throw new CommandExecutionError('WeChat displayed its editor-integrity warning after rich HTML paste; the draft was not saved');
+  }
+  if (!result?.ok || !String(result.text ?? '').trim() || !RICH_NODE_PATTERN.test(String(result.html ?? ''))) {
+    const actualHtml = String(result?.html ?? '');
+    const actualText = String(result?.text ?? '');
+    const tags = [...actualHtml.matchAll(/<([a-z0-9]+)/giu)].map(match => match[1].toLowerCase());
+    throw new CommandExecutionError(
+      `rich HTML content was not retained by the editor (htmlLength=${actualHtml.length}, textLength=${actualText.length}, tags=${tags.join(',') || 'none'})`,
+    );
+  }
+  return { html: result.html, text: result.text };
+}
+
+export { plainTextFromHtml };

package/clis/weixin/create-draft.js

@@ -2,6 +2,9 @@ import * as nodeFs from 'node:fs';
 import * as nodePath from 'node:path';
 import { cli, Strategy } from '@sovovs/bycli/registry';
 import { ArgumentError, AuthRequiredError, CommandExecutionError } from '@sovovs/bycli/errors';
+import { loadDraftContent, prepareHtmlContent } from './_wechat/draft-content.js';
+import { pasteHtmlThroughClipboard } from './_wechat/html-clipboard.js';
+import { createDraftViaApi } from './_wechat/api-draft.js';
 
 const WEIXIN_DOMAIN = 'mp.weixin.qq.com';
 const WEIXIN_HOME = 'https://mp.weixin.qq.com/';
@@ -38,9 +41,22 @@ function validateCoverImage(value) {
     return coverPath;
 }
 
+function readApiCredentials(kwargs) {
+    const appid = kwargs.appid == null ? '' : String(kwargs.appid).trim();
+    const appsecret = kwargs.appsecret == null ? '' : String(kwargs.appsecret).trim();
+    if (Boolean(appid) !== Boolean(appsecret)) {
+        throw new ArgumentError('appid and appsecret must be provided together');
+    }
+    return { appid: appid || null, appsecret: appsecret || null };
+}
+
+function requiresBrowser(kwargs) {
+    const { appid, appsecret } = readApiCredentials(kwargs);
+    return !(appid && appsecret);
+}
+
 function normalizeCreateDraftArgs(kwargs) {
     const title = requiredText(kwargs.title, 'title');
-    requiredText(kwargs.content, 'content');
     if (codePointLength(title) > MAX_TITLE_LENGTH) {
         throw new ArgumentError(`title must be at most ${MAX_TITLE_LENGTH} characters`);
     }
@@ -48,12 +64,21 @@ function normalizeCreateDraftArgs(kwargs) {
     if (author && codePointLength(author) > MAX_AUTHOR_LENGTH) {
         throw new ArgumentError(`author must be at most ${MAX_AUTHOR_LENGTH} characters`);
     }
+    const draftContent = loadDraftContent({
+        content: kwargs.content,
+        contentFile: kwargs['content-file'],
+        contentFormat: kwargs['content-format'],
+    });
+    const { appid, appsecret } = readApiCredentials(kwargs);
     return {
         title,
-        content: String(kwargs.content),
+        ...draftContent,
         author,
         summary: kwargs.summary == null ? null : String(kwargs.summary).trim(),
         coverImage: validateCoverImage(kwargs['cover-image']),
+        dryRun: kwargs['dry-run'] === true,
+        appid,
+        appsecret,
     };
 }
 
@@ -225,19 +250,31 @@ async function uploadContentImage(page, imagePath) {
 
     for (let attempt = 0; attempt < 15; attempt++) {
         await page.wait(1);
-        const cdnCount = await page.evaluate(`(() => {
+        const uploaded = await page.evaluate(`(() => {
             var editors = document.querySelectorAll('#ueditor_0, div[contenteditable="true"]');
-            var count = 0;
+            var sources = [];
             editors.forEach(function(editor) {
-                count += editor.querySelectorAll('img[src*="mmbiz"], img[data-src*="mmbiz"]').length;
+                editor.querySelectorAll('img[src*="mmbiz"], img[data-src*="mmbiz"]').forEach(function(image) {
+                    var src = image.getAttribute('src') || image.getAttribute('data-src') || '';
+                    if (src && !sources.includes(src)) sources.push(src);
+                });
             });
-            return count;
+            return sources;
         })()`);
-        if (cdnCount > 0) return;
+        if (Array.isArray(uploaded) && uploaded.length > 0) return uploaded[uploaded.length - 1];
+        if (typeof uploaded === 'string' && uploaded) return uploaded;
+        if (typeof uploaded === 'number' && uploaded > 0) return true;
     }
     throw new CommandExecutionError('Image did not upload to WeChat CDN');
 }
 
+async function removeTemporaryInsertedImage(page) {
+    if (typeof page.nativeKeyPress !== 'function') return;
+    await page.nativeKeyPress('Backspace', []);
+    await page.nativeKeyPress('Backspace', []);
+    if (typeof page.wait === 'function') await page.wait(1);
+}
+
 async function selectCoverFromContent(page) {
     await page.evaluate('document.querySelector("#js_cover_description_area")?.scrollIntoView()');
     await page.wait(1);
@@ -330,23 +367,46 @@ export const createDraftCommand = cli({
     site: 'weixin',
     name: 'create-draft',
     access: 'write',
-    description: '创建微信公众号图文草稿',
+    description: '创建微信公众号草稿（支持浏览器富文本或官方 API）',
+    example: 'bycli weixin create-draft --title "文章标题" --content-file article.html --content-format html --cover-image cover.jpg',
     domain: WEIXIN_DOMAIN,
     strategy: Strategy.COOKIE,
-    browser: true,
+    browser: requiresBrowser,
     navigateBefore: false,
     args: [
-        { name: 'title', required: true, help: '文章标题 (最长64字)' },
-        { name: 'content', required: true, positional: true, help: '文章正文' },
-        { name: 'author', help: '作者名 (最长8字)' },
-        { name: 'cover-image', help: '封面图片路径 (会先上传到正文再设为封面)' },
-        { name: 'summary', help: '文章摘要' },
-        { name: 'timeout', type: 'int', required: false, default: 180, help: 'Max seconds for the overall command (default: 180)' },
+        { name: 'title', required: true, help: '文章标题（最长 64 字）' },
+        { name: 'content', required: false, positional: true, help: '正文文本；也可用 --content-file 读取 HTML 文件' },
+        { name: 'content-file', help: '正文文件路径；HTML 模式支持本地图片' },
+        { name: 'content-format', choices: ['text', 'html', 'html-text'], default: 'text', help: '正文格式：text=纯文本，html=富文本，html-text=保留段落但忽略样式' },
+        { name: 'author', help: '作者名（最长 8 字）' },
+        { name: 'cover-image', help: '封面图路径；API 模式必填，浏览器模式会上传后设为封面' },
+        { name: 'summary', help: '文章摘要；API 模式对应 digest' },
+        { name: 'appid', help: '公众号 AppID；与 --appsecret 同传时走官方 API，不打开浏览器' },
+        { name: 'appsecret', help: '公众号 AppSecret；请勿提交到 shell 历史或日志' },
+        { name: 'dry-run', type: 'boolean', default: false, help: '浏览器模式：填充并验证正文后停止，不会保存草稿' },
+        { name: 'timeout', type: 'int', required: false, default: 180, help: '命令总超时时间（秒，默认 180）' },
     ],
     columns: ['status', 'detail'],
 
     func: async (page, kwargs) => {
         const args = normalizeCreateDraftArgs(kwargs);
+        if (args.appid && args.appsecret) {
+            const baseDir = args.filePath ? nodePath.dirname(args.filePath) : process.cwd();
+            const result = await createDraftViaApi({
+                appid: args.appid,
+                appsecret: args.appsecret,
+                title: args.title,
+                author: args.author ?? '',
+                digest: args.summary ?? '',
+                coverImage: args.coverImage,
+                html: args.content,
+                baseDir,
+            });
+            return [{
+                status: 'draft created',
+                detail: `"${args.title}" (media_id: ${result.mediaId})`,
+            }];
+        }
         await navigateToEditor(page);
 
 
@@ -360,8 +420,29 @@ export const createDraftCommand = cli({
 
         await page.wait(10);
 
-        const contentResult = await fillContent(page, args.content);
-        requirePageResult(contentResult, 'content');
+        let content = args.content;
+        if (args.format === 'html') {
+            const baseDir = args.filePath ? nodePath.dirname(args.filePath) : process.cwd();
+            const prepared = await prepareHtmlContent(content, {
+                baseDir,
+                resolveImage: async imagePath => {
+                    const uploaded = await uploadContentImage(page, imagePath);
+                    await removeTemporaryInsertedImage(page);
+                    return uploaded;
+                },
+            });
+            await pasteHtmlThroughClipboard(page, prepared.html, { origin: `https://${WEIXIN_DOMAIN}` });
+        } else {
+            const contentResult = await fillContent(page, content);
+            requirePageResult(contentResult, 'content');
+        }
+
+        if (args.dryRun) {
+            return [{
+                status: 'draft ready',
+                detail: `"${args.title}" (dry-run)`,
+            }];
+        }
 
         if (args.coverImage) {
             await uploadContentImage(page, args.coverImage);

package/dist/src/download/article-download.d.ts

@@ -7,6 +7,7 @@
  */
 import TurndownService from 'turndown';
 export { extractWechatArticleHtml } from './wechat-article.js';
+export { parseFragment as parseWechatHtmlFragment, serialize as serializeWechatHtml } from 'parse5';
 export interface ArticleData {
     title: string;
     author?: string;

package/dist/src/download/article-download.js

@@ -13,6 +13,7 @@ import { gfm } from 'turndown-plugin-gfm';
 import { httpDownload, sanitizeFilename } from './index.js';
 import { formatBytes } from './progress.js';
 export { extractWechatArticleHtml } from './wechat-article.js';
+export { parseFragment as parseWechatHtmlFragment, serialize as serializeWechatHtml } from 'parse5';
 const IMAGE_CONCURRENCY = 5;
 const DEFAULT_LABELS = {
     author: '作者',

package/package.json

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

package/scripts/typed-error-lint-baseline.json

@@ -95,14 +95,6 @@
     "text": "const count = Math.min(kwargs.limit || 20, 50);",
     "occurrence": 0
   },
-  {
-    "rule": "silent-clamp",
-    "command": "bilibili/comments",
-    "file": "clis/bilibili/comments.js",
-    "line": 21,
-    "text": "const limit = Math.min(Number(kwargs.limit) || 20, 50);",
-    "occurrence": 0
-  },
   {
     "rule": "silent-clamp",
     "command": "bilibili/favorite",
@@ -271,6 +263,14 @@
     "text": "return Math.max(1, Math.min(parsed, MAX_LIMIT));",
     "occurrence": 0
   },
+  {
+    "rule": "silent-clamp",
+    "command": "github/search",
+    "file": "clis/github/search.js",
+    "line": 238,
+    "text": "url.searchParams.set('per_page', String(Math.min(perPage, MAX_LIMIT)));",
+    "occurrence": 0
+  },
   {
     "rule": "silent-clamp",
     "command": "google/news",
@@ -419,7 +419,7 @@
     "rule": "silent-clamp",
     "command": "linkedin/timeline",
     "file": "clis/linkedin/timeline.js",
-    "line": 473,
+    "line": 479,
     "text": "const limit = Math.max(1, Math.min(kwargs.limit ?? 20, 100));",
     "occurrence": 0
   },
@@ -635,7 +635,7 @@
     "rule": "silent-clamp",
     "command": "twitter/following",
     "file": "clis/twitter/following.js",
-    "line": 227,
+    "line": 228,
     "text": "const fetchCount = Math.min(50, limit - allUsers.length + 10);",
     "occurrence": 0
   },
@@ -643,7 +643,7 @@
     "rule": "silent-clamp",
     "command": "twitter/likes",
     "file": "clis/twitter/likes.js",
-    "line": 207,
+    "line": 208,
     "text": "const fetchCount = Math.min(100, limit - allTweets.length + 10);",
     "occurrence": 0
   },
@@ -651,7 +651,7 @@
     "rule": "silent-clamp",
     "command": "twitter/list-tweets",
     "file": "clis/twitter/list-tweets.js",
-    "line": 176,
+    "line": 178,
     "text": "const fetchCount = Math.min(100, limit - allTweets.length + 10);",
     "occurrence": 0
   },
@@ -659,7 +659,7 @@
     "rule": "silent-clamp",
     "command": "twitter/timeline",
     "file": "clis/twitter/timeline.js",
-    "line": 183,
+    "line": 185,
     "text": "const fetchCount = Math.min(40, limit - allTweets.length + 5); // over-fetch slightly for promoted filtering",
     "occurrence": 0
   },
@@ -819,7 +819,7 @@
     "rule": "silent-clamp",
     "command": "zhihu/collection",
     "file": "clis/zhihu/collection.js",
-    "line": 154,
+    "line": 142,
     "text": "const currentFetchLimit = Math.min(pageLimit, requestedLimit - collected.length);",
     "occurrence": 0
   },
@@ -827,7 +827,7 @@
     "rule": "silent-clamp",
     "command": "zhihu/collection",
     "file": "clis/zhihu/collection.js",
-    "line": 143,
+    "line": 131,
     "text": "const pageLimit = Math.min(requestedLimit, 20); // 知乎 API 限制每页最大 20",
     "occurrence": 0
   },
@@ -1003,7 +1003,7 @@
     "rule": "silent-sentinel",
     "command": "twitter/search",
     "file": "clis/twitter/search.js",
-    "line": 217,
+    "line": 218,
     "text": "author: tweetUser?.core?.screen_name || tweetUser?.legacy?.screen_name || 'unknown',",
     "occurrence": 0
   },

package/scripts/recorder.sh

@@ -1,186 +0,0 @@
-#!/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