aiconductor-cli 1.3.5 → 1.4.0

package/README.md

@@ -1,6 +1,6 @@
 # AIConductor CLI
 
-AIConductor 平台命令行工具箱，提供网页发布、搜索、抖音数据和小红书扫码发布功能。
+AIConductor 平台命令行工具箱，提供内容选题简报、网页发布、搜索、抖音数据和小红书工具。
 
 ## 安装
 
@@ -159,7 +159,7 @@ aiconductor-cli search image "长城风景" -n 3 --image-width-min 1200 --image-
 
 ### 热点选题简报
 
-聚合多个平台的热点条目，为内容选题提供带来源链接的原料。默认查询知乎、微博、抖音和 AIHOT，每个来源返回 30 条。
+聚合多个平台热点与小红书实时热榜，为内容选题提供带来源链接的原料。默认查询知乎、微博、抖音和 AIHOT，每个来源返回 30 条，并额外请求一次小红书热榜。
 
 ```bash
 aiconductor-cli content briefing [选项]
@@ -181,7 +181,14 @@ aiconductor-cli content briefing -f text
 aiconductor-cli content briefing --sources aihot,hackernews,producthunt,juejin --limit 15 -f text
 ```
 
-默认 JSON 输出会保留成功来源、缓存状态和失败来源，便于后续选题处理。部分来源失败时仍返回其他成功来源；仅成功返回数据的来源会计费。
+默认 JSON 输出保留以下字段，便于后续选题处理：
+
+- `data.data.sources`：成功的综合热榜来源，兼容旧版本。
+- `data.data.failed_sources`：综合热榜中失败的平台来源。
+- `data.data.xhs_hot_list`：小红书热榜结果，包含日期与话题条目；小红书热榜接口失败时为 `null`。
+- `data.data.failed_services`：综合热榜或小红书热榜接口级失败信息。
+
+任一服务成功时命令仍会返回可用数据；只有两个服务都失败时才退出失败。成功来源和成功的小红书热榜调用均按平台现有规则计费。
 
 ### 抖音数据工具箱
 
@@ -295,6 +302,19 @@ aiconductor-cli douyin link-to-text <视频URL> [选项]
 aiconductor-cli douyin link-to-text "https://www.douyin.com/video/xxxxx"
 ```
 
+### 小红书数据工具
+
+获取小红书实时热榜：
+
+```bash
+aiconductor-cli xhs hot-list [选项]
+```
+
+示例：
+```bash
+aiconductor-cli xhs hot-list -f text
+```
+
 ### 小红书扫码发布
 
 生成图文或视频笔记的 H5 发布页与二维码。素材支持公网 URL、本地文件、Base64/data URL，以及包含 Base64 内容的文本文件。
@@ -353,6 +373,7 @@ aiconductor-cli xhs note-publish video \
 | 抖音用户搜索 | 0.15 元/页 |
 | 抖音视频搜索 | 0.15 元/页 |
 | 抖音链接转文字 | 0.01 元/次 + 0.0003 元/秒 |
+| 小红书热榜 | 以平台服务配置为准 |
 | 小红书扫码发布 | 0.05 元/次 |
 
 > 搜索/调用失败不扣费，仅成功时计费。

package/bin/aiconductor-cli.js

@@ -18,7 +18,7 @@ const {
   videoSearchCommand,
   linkToTextCommand,
 } = require("../src/commands/douyin");
-const { notePublishCommand } = require("../src/commands/xhs");
+const { hotListCommand: xhsHotListCommand, notePublishCommand } = require("../src/commands/xhs");
 
 const program = new Command();
 
@@ -136,7 +136,7 @@ const contentCmd = program
 
 contentCmd
   .command("briefing")
-  .description("聚合多平台热点，生成选题原料")
+  .description("聚合多平台热点与小红书热榜，生成选题原料")
   .option("-k, --api-key <key>", "AIConductor API Key（也可通过 AICONDUCTOR_API_KEY 环境变量或 .env 文件提供）")
   .option("--sources <ids>", "来源 ID，逗号分隔；默认 zhihu,weibo,douyin,aihot")
   .option("--limit <n>", "每个来源返回条数，范围 1 到 30", "30")
@@ -222,11 +222,18 @@ douyinCmd
   .action((videoUrl, options) => { linkToTextCommand(videoUrl, options); });
 
 // xhs 子命令组
-const xhsCmd = program
-  .command("xhs")
-  .description("小红书数据工具箱");
-
-xhsCmd
+const xhsCmd = program
+  .command("xhs")
+  .description("小红书数据工具箱");
+
+xhsCmd
+  .command("hot-list")
+  .description("获取小红书实时热榜")
+  .option("-k, --api-key <key>", "AIConductor API Key")
+  .option("-f, --format <format>", "输出格式：json 或 text", "json")
+  .action((options) => { xhsHotListCommand(options); });
+
+xhsCmd
   .command("note-publish")
   .description("生成小红书扫码发布页与二维码（0.05元/次）")
   .argument("<type>", "笔记类型：normal（图文）或 video（视频）")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiconductor-cli",
-  "version": "1.3.5",
+  "version": "1.4.0",
   "description": "AIConductor CLI 工具箱",
   "keywords": [
     "aiconductor",

package/src/api.js

@@ -10,6 +10,7 @@ const PUBLISHED_WEBPAGES_API_PATH = "/api/published_webpages";
 const DELETE_PUBLISHED_WEBPAGE_API_PATH = "/api/delete_published_webpage";
 const SEARCH_API_PATH = "/api/doubao_search";
 const HOT_LIST_API_PATH = "/api/hot_list_mixed";
+const XHS_HOT_LIST_API_PATH = "/api/xhs_hot_list";
 const DOUYIN_VIDEO_INFO_PATH = "/api/douyin_video_info";
 const DOUYIN_VIDEO_COMMENTS_PATH = "/api/douyin_video_comments";
 const DOUYIN_USER_VIDEOS_PATH = "/api/douyin_user_videos";
@@ -380,6 +381,22 @@ async function hotList(apiKey, params) {
   }
   return result;
 }
+
+/**
+ * 获取小红书实时热榜。
+ * @param {string} apiKey
+ * @returns {Promise<object>}
+ */
+async function xhsHotList(apiKey) {
+  const resp = await httpPost(API_HOST, XHS_HOT_LIST_API_PATH, {}, {
+    Authorization: `Bearer ${apiKey}`,
+  }, http);
+  const result = stripBilling(resp);
+  if (result?.success === false) {
+    throw Object.assign(new Error(result.message || "小红书热榜接口返回失败"), { type: "api_error" });
+  }
+  return result;
+}
 
 /**
  * Markdown 转 HTML 并发布
@@ -576,6 +593,7 @@ module.exports = {
   deletePublishedWebpage,
   webSearch,
   hotList,
+  xhsHotList,
   douyinVideoInfo,
   douyinVideoComments,
   douyinUserVideos,

package/src/api.test.js

@@ -4,9 +4,16 @@ const http = require("node:http");
 const https = require("node:https");
 const test = require("node:test");
 
-const { hotList, webSearch } = require("./api");
-const { formatHotListText, parseSourceIds, DEFAULT_HOT_LIST_SOURCES } = require("./commands/content");
+const { hotList, webSearch, xhsHotList } = require("./api");
+const {
+  buildBriefingResult,
+  formatHotListText,
+  parseLimit,
+  parseSourceIds,
+  DEFAULT_HOT_LIST_SOURCES,
+} = require("./commands/content");
 const { formatSearchText } = require("./commands/web_search");
+const { hotListTextFormatter, notePublishTextFormatter } = require("./commands/xhs");
 
 function captureRequest(callback, responseBody = { success: true, billing: {} }, transport = https) {
   const originalRequest = transport.request;
@@ -26,7 +33,10 @@ function captureRequest(callback, responseBody = { success: true, billing: {} },
     return request;
   };
 
-  return callback().then(() => captured).finally(() => {
+  return callback().then((result) => {
+    captured.result = result;
+    return captured;
+  }).finally(() => {
     transport.request = originalRequest;
   });
 }
@@ -217,3 +227,142 @@ test("hotList raises API failures", async () => {
     { type: "api_error", message: "没有可用热榜来源" }
   );
 });
+
+test("xhsHotList calls the XHS hot-list endpoint over HTTP", async () => {
+  const responseBody = {
+    success: true,
+    data: {
+      date: "2026-07-29",
+      items: [{ rank: 1, title: "夏日穿搭", hot: "123万", trend: "up", url: "https://example.com/xhs" }],
+    },
+    billing: { service_fee: 0.01 },
+  };
+  const request = await captureRequest(() => xhsHotList("test-key"), responseBody, http);
+
+  assert.equal(request.options.path, "/api/xhs_hot_list");
+  assert.equal(request.options.port, 80);
+  assert.equal(request.options.headers.Authorization, "Bearer test-key");
+  assert.deepEqual(request.body, {});
+  assert.equal(request.result.billing, undefined);
+});
+
+test("xhsHotList raises API failures", async () => {
+  await assert.rejects(
+    captureRequest(
+      () => xhsHotList("test-key"),
+      { success: false, message: "小红书热榜暂不可用" },
+      http
+    ),
+    { type: "api_error", message: "小红书热榜暂不可用" }
+  );
+});
+
+test("buildBriefingResult preserves hot-list fields and adds XHS data", () => {
+  const result = buildBriefingResult(
+    {
+      status: "fulfilled",
+      value: {
+        success: true,
+        data: {
+          sources: [{ source_id: "zhihu", items: [{ title: "AI 应用趋势" }] }],
+          failed_sources: [{ source_id: "weibo", message: "上游暂不可用" }],
+        },
+      },
+    },
+    {
+      status: "fulfilled",
+      value: {
+        success: true,
+        data: { date: "2026-07-29", items: [{ rank: 1, title: "AI 工具" }] },
+      },
+    }
+  );
+
+  assert.equal(result.success, true);
+  assert.equal(result.data.sources[0].source_id, "zhihu");
+  assert.equal(result.data.failed_sources[0].source_id, "weibo");
+  assert.equal(result.data.xhs_hot_list.items[0].title, "AI 工具");
+  assert.deepEqual(result.data.failed_services, []);
+});
+
+test("buildBriefingResult keeps either service when the other one fails", () => {
+  const hotListOnly = buildBriefingResult(
+    { status: "fulfilled", value: { success: true, data: { sources: [], failed_sources: [] } } },
+    { status: "rejected", reason: Object.assign(new Error("小红书超时"), { type: "network_error" }) }
+  );
+  assert.equal(hotListOnly.data.xhs_hot_list, null);
+  assert.deepEqual(hotListOnly.data.failed_services, [{ service: "xhs_hot_list", message: "小红书超时" }]);
+
+  const xhsOnly = buildBriefingResult(
+    { status: "rejected", reason: Object.assign(new Error("热榜超时"), { type: "network_error" }) },
+    { status: "fulfilled", value: { success: true, data: { date: "2026-07-29", items: [] } } }
+  );
+  assert.deepEqual(xhsOnly.data.sources, []);
+  assert.equal(xhsOnly.data.xhs_hot_list.date, "2026-07-29");
+  assert.deepEqual(xhsOnly.data.failed_services, [{ service: "hot_list", message: "热榜超时" }]);
+});
+
+test("buildBriefingResult fails only when both services fail", () => {
+  assert.throws(
+    () => buildBriefingResult(
+      { status: "rejected", reason: new Error("热榜超时") },
+      { status: "rejected", reason: new Error("小红书超时") }
+    ),
+    { type: "api_error", message: /均获取失败/ }
+  );
+});
+
+test("hot-list formatters render XHS trends and service failures", () => {
+  const briefingText = formatHotListText({
+    data: {
+      sources: [],
+      xhs_hot_list: {
+        date: "2026-07-29",
+        items: [{ rank: 1, title: "夏日穿搭", hot: "123万", trend: "up", url: "https://example.com/xhs" }],
+      },
+      failed_services: [{ service: "hot_list", message: "上游暂不可用" }],
+    },
+  });
+  assert.match(briefingText, /【小红书热榜】2026-07-29/);
+  assert.match(briefingText, /\[1\] 夏日穿搭 up/);
+  assert.match(briefingText, /服务失败:/);
+
+  const xhsText = hotListTextFormatter({
+    data: { date: "2026-07-29", items: [{ rank: 2, title: "露营", hot_value: 88, trend: "new" }] },
+  });
+  assert.match(xhsText, /小红书热榜/);
+  assert.match(xhsText, /\[2\] 露营 new/);
+  assert.match(xhsText, /热度: 88/);
+});
+
+test("note-publish formatter surfaces the shareable qrcode image URL", () => {
+  const text = notePublishTextFormatter({
+    message: "发布页生成成功",
+    data: {
+      id: "note-1",
+      url: "https://oss.aiconductor.fun/temporary_7/xhs_note_publish/note-1/index.html",
+      qrcode: "data:image/png;base64,AAAA",
+      qrcode_url: "https://oss.aiconductor.fun/temporary_7/xhs_note_publish/note-1/qrcode.png",
+    },
+  });
+  assert.match(text, /H5 地址:/);
+  assert.match(text, /二维码图: https:\/\/oss\.aiconductor\.fun\/temporary_7\/xhs_note_publish\/note-1\/qrcode\.png/);
+});
+
+test("note-publish formatter tolerates responses without qrcode_url", () => {
+  // 旧版后端只返回 base64 二维码，formatter 不能因此报错
+  const text = notePublishTextFormatter({
+    data: { id: "note-2", url: "https://example.com/index.html" },
+  });
+  assert.match(text, /H5 地址:/);
+  assert.doesNotMatch(text, /二维码图/);
+});
+
+test("parseLimit accepts the documented range", () => {
+  assert.equal(parseLimit(), 30);
+  assert.equal(parseLimit("1"), 1);
+  assert.equal(parseLimit(30), 30);
+  assert.throws(() => parseLimit("0"), { type: "validation_error" });
+  assert.throws(() => parseLimit("31"), { type: "validation_error" });
+  assert.throws(() => parseLimit("invalid"), { type: "validation_error" });
+});

package/src/commands/content.js

@@ -1,4 +1,4 @@
-const { hotList } = require("../api");
+const { hotList, xhsHotList } = require("../api");
 const { outputResult, outputError, resolveKeyOrExit, handleApiError } = require("../lib/cli-utils");
 
 const DEFAULT_HOT_LIST_SOURCES = ["zhihu", "weibo", "douyin", "aihot"];
@@ -20,11 +20,71 @@ function parseSourceIds(value) {
   return sourceIds;
 }
 
+/**
+ * 解析每个热榜来源的返回条数。
+ * @param {string|number|undefined} value
+ * @returns {number}
+ */
+function parseLimit(value) {
+  const limit = Number(value === undefined ? 30 : value);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 30) {
+    throw Object.assign(new Error(`--limit 须为 1 到 30 的整数，收到: ${value}`), {
+      type: "validation_error",
+    });
+  }
+  return limit;
+}
+
 function formatTimestamp(value) {
   if (typeof value !== "number" || !Number.isFinite(value)) return value || "";
   return new Date(value).toISOString();
 }
 
+function errorMessage(reason) {
+  if (reason?.body?.message) return reason.body.message;
+  return reason?.message || String(reason || "未知错误");
+}
+
+/**
+ * 将热榜和小红书热榜的并行结果组合为兼容既有字段的简报响应。
+ * @param {PromiseSettledResult<object>} hotListResult
+ * @param {PromiseSettledResult<object>} xhsHotListResult
+ * @returns {object}
+ */
+function buildBriefingResult(hotListResult, xhsHotListResult) {
+  const hotListSucceeded = hotListResult.status === "fulfilled";
+  const xhsHotListSucceeded = xhsHotListResult.status === "fulfilled";
+
+  if (!hotListSucceeded && !xhsHotListSucceeded) {
+    throw Object.assign(
+      new Error(`热点与小红书热榜均获取失败: ${errorMessage(hotListResult.reason)}; ${errorMessage(xhsHotListResult.reason)}`),
+      { type: "api_error" }
+    );
+  }
+
+  const failedServices = [];
+  if (!hotListSucceeded) {
+    failedServices.push({ service: "hot_list", message: errorMessage(hotListResult.reason) });
+  }
+  if (!xhsHotListSucceeded) {
+    failedServices.push({ service: "xhs_hot_list", message: errorMessage(xhsHotListResult.reason) });
+  }
+
+  const hotListData = hotListSucceeded
+    ? hotListResult.value.data || {}
+    : { sources: [], failed_sources: [] };
+  const xhsHotListData = xhsHotListSucceeded ? xhsHotListResult.value.data || {} : null;
+  return {
+    success: true,
+    message: failedServices.length ? "热点简报已生成，部分服务不可用" : "热点简报已生成",
+    data: {
+      ...hotListData,
+      xhs_hot_list: xhsHotListData,
+      failed_services: failedServices,
+    },
+  };
+}
+
 /**
  * text 模式的热点简报格式化。
  * @param {object} result
@@ -58,6 +118,28 @@ function formatHotListText(result = {}) {
     });
   }
 
+  const xhsHotList = data.xhs_hot_list;
+  if (xhsHotList) {
+    lines.push(`\n【小红书热榜】${xhsHotList.date || ""}`.trimEnd());
+    (xhsHotList.items || []).forEach((item) => {
+      const rank = item.rank === undefined ? "-" : item.rank;
+      const trend = item.trend ? ` ${item.trend}` : "";
+      lines.push(`[${rank}] ${item.title || "未命名话题"}${trend}`);
+      if (item.hot || item.hot_value !== undefined) {
+        lines.push(`  热度: ${item.hot || item.hot_value}`);
+      }
+      if (item.url) lines.push(`  URL: ${item.url}`);
+    });
+  }
+
+  const failedServices = data.failed_services || [];
+  if (failedServices.length) {
+    lines.push("\n服务失败:");
+    failedServices.forEach((service) => {
+      lines.push(`- ${service.service || "未知服务"}: ${service.message || "未知错误"}`);
+    });
+  }
+
   return lines.join("\n").trimEnd();
 }
 
@@ -71,10 +153,15 @@ async function briefingCommand(options = {}) {
   const apiKey = resolveKeyOrExit(options.apiKey, format);
 
   try {
-    const result = await hotList(apiKey, {
+    const hotListParams = {
       sourceIds: parseSourceIds(options.sources),
-      limit: options.limit === undefined ? 30 : options.limit,
-    });
+      limit: parseLimit(options.limit),
+    };
+    const [hotListResult, xhsHotListResult] = await Promise.allSettled([
+      hotList(apiKey, hotListParams),
+      xhsHotList(apiKey),
+    ]);
+    const result = buildBriefingResult(hotListResult, xhsHotListResult);
     outputResult(result, format, formatHotListText);
     process.exit(0);
   } catch (err) {
@@ -87,4 +174,11 @@ async function briefingCommand(options = {}) {
   }
 }
 
-module.exports = { briefingCommand, formatHotListText, parseSourceIds, DEFAULT_HOT_LIST_SOURCES };
+module.exports = {
+  briefingCommand,
+  buildBriefingResult,
+  formatHotListText,
+  parseLimit,
+  parseSourceIds,
+  DEFAULT_HOT_LIST_SOURCES,
+};

package/src/commands/xhs.js

@@ -1,225 +1,268 @@
-const fs = require("fs");
-const path = require("path");
-const { r2Upload, xhsNotePublish } = require("../api");
-const { outputResult, resolveKeyOrExit, handleApiError } = require("../lib/cli-utils");
-
-const MAX_IMAGE_SIZE = 32 * 1024 * 1024;
-const MAX_UPLOAD_SIZE = 100 * 1024 * 1024;
-
-function validationError(message) {
-  return Object.assign(new Error(message), { type: "validation_error" });
-}
-
-function resolveBase64Input(value, label) {
-  if (!value.startsWith("@")) return value;
-  const filePath = path.resolve(value.slice(1));
-  let content;
-  try {
-    content = fs.readFileSync(filePath, "utf-8").trim();
-  } catch (err) {
-    throw validationError(`${label} Base64 文件读取失败 ${filePath}: ${err.message}`);
-  }
-  if (!content) throw validationError(`${label} Base64 文件内容为空: ${filePath}`);
-  return content;
-}
-
-function validateLocalFile(filePath, label, maxSize) {
-  const absolutePath = path.resolve(filePath);
-  let stat;
-  try {
-    stat = fs.statSync(absolutePath);
-  } catch (err) {
-    throw validationError(`${label}文件读取失败 ${absolutePath}: ${err.message}`);
-  }
-  if (!stat.isFile()) throw validationError(`${label}路径不是文件: ${absolutePath}`);
-  if (stat.size > maxSize) {
-    throw validationError(`${label}文件超过 ${maxSize / 1024 / 1024}MB: ${absolutePath}`);
-  }
-}
-
-function validateUrl(value, label) {
-  let parsed;
-  try {
-    parsed = new URL(value);
-  } catch (_) {
-    throw validationError(`${label}不是有效 URL: ${value}`);
-  }
-  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-    throw validationError(`${label}仅支持 HTTP/HTTPS URL: ${value}`);
-  }
-}
-
-function validateBase64Size(value, label, maxSize) {
-  const dataUrlPrefix = value.match(/^data:[^,]*,/i)?.[0];
-  const payload = (dataUrlPrefix ? value.slice(dataUrlPrefix.length) : value).replace(/\s/g, "");
-  const padding = payload.endsWith("==") ? 2 : payload.endsWith("=") ? 1 : 0;
-  const size = Math.max(0, Math.floor(payload.length * 3 / 4) - padding);
-  if (size > maxSize) {
-    throw validationError(`${label} Base64 内容超过 ${maxSize / 1024 / 1024}MB`);
-  }
-}
-
-async function uploadMedia(apiKey, params, label) {
-  try {
-    const result = await r2Upload(apiKey, params);
-    return result.file_url;
-  } catch (err) {
-    const detail = err.type === "http_error"
-      ? `HTTP ${err.statusCode}: ${err.body?.message || JSON.stringify(err.body)}`
-      : err.message || err;
-    const wrapped = new Error(`${label}上传失败: ${detail}`);
-    wrapped.type = err.type === "validation_error" || err.type === "network_error"
-      ? err.type
-      : "api_error";
-    wrapped.statusCode = err.statusCode;
-    wrapped.body = err.body;
-    throw wrapped;
-  }
-}
-
-/**
- * text 格式输出：用 ✓ 开头展示关键信息
- */
-function textFormatter(resp) {
-  const d = resp.data || {};
-  const lines = [];
-  lines.push("✓ 小红书笔记发布页已生成");
-  lines.push(`  ID:       ${d.id}`);
-  lines.push(`  H5 地址:  ${d.url}`);
-  if (resp.message) lines.push(`  消息:     ${resp.message}`);
-  if (d.qrcode) lines.push(`  二维码:   ${d.qrcode.substring(0, 50)}...`);
-  if (d.media) {
-    if (d.media.images) lines.push(`  图片:     ${d.media.images.length} 张`);
-    if (d.media.video) lines.push(`  视频:     ${d.media.video}`);
-    if (d.media.cover) lines.push(`  封面:     ${d.media.cover}`);
-  }
-  return lines.join("\n");
-}
-
-async function notePublishCommand(type, options = {}) {
-  const format = options.format || "json";
-  const apiKey = resolveKeyOrExit(options.apiKey, format);
-
-  try {
-    if (type !== "normal" && type !== "video") {
-      throw validationError(`笔记类型仅支持 normal 或 video，收到: ${type}`);
-    }
-
-    const imageUrls = options.images
-      ? options.images.split(",").map((value) => value.trim()).filter(Boolean)
-      : [];
-    const imageFiles = options.imageFile || [];
-    const imageBase64 = (options.imageBase64 || []).map((value, index) =>
-      resolveBase64Input(value, `第 ${imageUrls.length + imageFiles.length + index + 1} 张图片`)
-    );
-    const videoBase64 = options.videoBase64
-      ? resolveBase64Input(options.videoBase64, "视频")
-      : undefined;
-    const coverBase64 = options.coverBase64
-      ? resolveBase64Input(options.coverBase64, "视频封面")
-      : undefined;
-    const imageCount = imageUrls.length + imageFiles.length + imageBase64.length;
-    const videoSources = [options.video, options.videoFile, videoBase64].filter(Boolean);
-    const coverSources = [options.cover, options.coverFile, coverBase64].filter(Boolean);
-    const validDays = Number(options.uploadValidDays || 7);
-
-    if (validDays !== 1 && validDays !== 7) {
-      throw validationError(`--upload-valid-days 仅支持 1 或 7，收到: ${options.uploadValidDays}`);
-    }
-    if (type === "normal") {
-      if (videoSources.length > 0 || coverSources.length > 0) {
-        throw validationError("normal 类型不能使用视频或封面参数");
-      }
-      if (imageCount === 0) {
-        throw validationError("normal 类型至少需要一张图片，请使用 --images、--image-file 或 --image-base64");
-      }
-      if (imageCount > 18) {
-        throw validationError(`图片最多 18 张，当前共 ${imageCount} 张`);
-      }
-      imageUrls.forEach((url, index) => validateUrl(url, `第 ${index + 1} 张图片`));
-      imageFiles.forEach((filePath, index) => validateLocalFile(
-        filePath,
-        `第 ${imageUrls.length + index + 1} 张图片`,
-        MAX_IMAGE_SIZE
-      ));
-      imageBase64.forEach((value, index) => validateBase64Size(
-        value,
-        `第 ${imageUrls.length + imageFiles.length + index + 1} 张图片`,
-        MAX_IMAGE_SIZE
-      ));
-    } else {
-      if (imageCount > 0) {
-        throw validationError("video 类型不能使用图片参数");
-      }
-      if (videoSources.length !== 1) {
-        throw validationError("video 类型必须且只能使用 --video、--video-file、--video-base64 之一");
-      }
-      if (coverSources.length > 1) {
-        throw validationError("视频封面只能使用 --cover、--cover-file、--cover-base64 之一");
-      }
-      if (options.video) validateUrl(options.video, "视频");
-      if (options.videoFile) validateLocalFile(options.videoFile, "视频", MAX_UPLOAD_SIZE);
-      if (videoBase64) validateBase64Size(videoBase64, "视频", MAX_UPLOAD_SIZE);
-      if (options.cover) validateUrl(options.cover, "视频封面");
-      if (options.coverFile) validateLocalFile(options.coverFile, "视频封面", MAX_IMAGE_SIZE);
-      if (coverBase64) validateBase64Size(coverBase64, "视频封面", MAX_IMAGE_SIZE);
-    }
-
-    let images;
-    let video;
-    let cover;
-    if (type === "normal") {
-      const uploadedImages = await Promise.all([
-        ...imageFiles.map((filePath, index) => uploadMedia(
-          apiKey,
-          { filePath, validDays },
-          `第 ${imageUrls.length + index + 1} 张图片`
-        )),
-        ...imageBase64.map((fileBase64, index) => uploadMedia(
-          apiKey,
-          { fileBase64, defaultContentType: "image/jpeg", validDays },
-          `第 ${imageUrls.length + imageFiles.length + index + 1} 张图片`
-        )),
-      ]);
-      images = [...imageUrls, ...uploadedImages];
-    } else {
-      video = options.video;
-      if (options.videoFile) {
-        video = await uploadMedia(apiKey, { filePath: options.videoFile, validDays }, "视频");
-      } else if (videoBase64) {
-        video = await uploadMedia(
-          apiKey,
-          { fileBase64: videoBase64, defaultContentType: "video/mp4", validDays },
-          "视频"
-        );
-      }
-
-      cover = options.cover;
-      if (options.coverFile) {
-        cover = await uploadMedia(apiKey, { filePath: options.coverFile, validDays }, "视频封面");
-      } else if (coverBase64) {
-        cover = await uploadMedia(
-          apiKey,
-          { fileBase64: coverBase64, defaultContentType: "image/jpeg", validDays },
-          "视频封面"
-        );
-      }
-    }
-
-    const result = await xhsNotePublish(apiKey, {
-      type,
-      title: options.title,
-      content: options.content,
-      images,
-      video,
-      cover,
-    });
-    outputResult(result, format, textFormatter);
-    process.exit(0);
-  } catch (err) {
-    handleApiError(err, format);
-    process.exit(1);
-  }
-}
-
-module.exports = { notePublishCommand };
+const fs = require("fs");
+const path = require("path");
+const { r2Upload, xhsHotList, xhsNotePublish } = require("../api");
+const { outputResult, resolveKeyOrExit, handleApiError } = require("../lib/cli-utils");
+
+const MAX_IMAGE_SIZE = 32 * 1024 * 1024;
+const MAX_UPLOAD_SIZE = 100 * 1024 * 1024;
+
+function validationError(message) {
+  return Object.assign(new Error(message), { type: "validation_error" });
+}
+
+function resolveBase64Input(value, label) {
+  if (!value.startsWith("@")) return value;
+  const filePath = path.resolve(value.slice(1));
+  let content;
+  try {
+    content = fs.readFileSync(filePath, "utf-8").trim();
+  } catch (err) {
+    throw validationError(`${label} Base64 文件读取失败 ${filePath}: ${err.message}`);
+  }
+  if (!content) throw validationError(`${label} Base64 文件内容为空: ${filePath}`);
+  return content;
+}
+
+function validateLocalFile(filePath, label, maxSize) {
+  const absolutePath = path.resolve(filePath);
+  let stat;
+  try {
+    stat = fs.statSync(absolutePath);
+  } catch (err) {
+    throw validationError(`${label}文件读取失败 ${absolutePath}: ${err.message}`);
+  }
+  if (!stat.isFile()) throw validationError(`${label}路径不是文件: ${absolutePath}`);
+  if (stat.size > maxSize) {
+    throw validationError(`${label}文件超过 ${maxSize / 1024 / 1024}MB: ${absolutePath}`);
+  }
+}
+
+function validateUrl(value, label) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch (_) {
+    throw validationError(`${label}不是有效 URL: ${value}`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw validationError(`${label}仅支持 HTTP/HTTPS URL: ${value}`);
+  }
+}
+
+function validateBase64Size(value, label, maxSize) {
+  const dataUrlPrefix = value.match(/^data:[^,]*,/i)?.[0];
+  const payload = (dataUrlPrefix ? value.slice(dataUrlPrefix.length) : value).replace(/\s/g, "");
+  const padding = payload.endsWith("==") ? 2 : payload.endsWith("=") ? 1 : 0;
+  const size = Math.max(0, Math.floor(payload.length * 3 / 4) - padding);
+  if (size > maxSize) {
+    throw validationError(`${label} Base64 内容超过 ${maxSize / 1024 / 1024}MB`);
+  }
+}
+
+async function uploadMedia(apiKey, params, label) {
+  try {
+    const result = await r2Upload(apiKey, params);
+    return result.file_url;
+  } catch (err) {
+    const detail = err.type === "http_error"
+      ? `HTTP ${err.statusCode}: ${err.body?.message || JSON.stringify(err.body)}`
+      : err.message || err;
+    const wrapped = new Error(`${label}上传失败: ${detail}`);
+    wrapped.type = err.type === "validation_error" || err.type === "network_error"
+      ? err.type
+      : "api_error";
+    wrapped.statusCode = err.statusCode;
+    wrapped.body = err.body;
+    throw wrapped;
+  }
+}
+
+/**
+ * text 格式输出：用 ✓ 开头展示关键信息
+ * @param {object} resp
+ * @returns {string}
+ */
+function notePublishTextFormatter(resp) {
+  const d = resp.data || {};
+  const lines = [];
+  lines.push("✓ 小红书笔记发布页已生成");
+  lines.push(`  ID:       ${d.id}`);
+  lines.push(`  H5 地址:  ${d.url}`);
+  if (resp.message) lines.push(`  消息:     ${resp.message}`);
+  if (d.qrcode_url) lines.push(`  二维码图: ${d.qrcode_url}`);
+  if (d.qrcode) lines.push(`  二维码:   ${d.qrcode.substring(0, 50)}...`);
+  if (d.media) {
+    if (d.media.images) lines.push(`  图片:     ${d.media.images.length} 张`);
+    if (d.media.video) lines.push(`  视频:     ${d.media.video}`);
+    if (d.media.cover) lines.push(`  封面:     ${d.media.cover}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * text 格式输出：展示小红书实时热榜。
+ * @param {object} resp
+ * @returns {string}
+ */
+function hotListTextFormatter(resp = {}) {
+  const data = resp.data || {};
+  const lines = ["小红书热榜"];
+  if (data.date) lines.push(`日期: ${data.date}`);
+
+  (data.items || []).forEach((item) => {
+    const rank = item.rank === undefined ? "-" : item.rank;
+    const trend = item.trend ? ` ${item.trend}` : "";
+    lines.push(`\n[${rank}] ${item.title || "未命名话题"}${trend}`);
+    if (item.hot || item.hot_value !== undefined) lines.push(`  热度: ${item.hot || item.hot_value}`);
+    if (item.url) lines.push(`  URL: ${item.url}`);
+  });
+
+  return lines.join("\n");
+}
+
+/**
+ * 获取小红书实时热榜。
+ * @param {{ apiKey?: string, format?: "json"|"text" }} options
+ * @returns {Promise<void>}
+ */
+async function hotListCommand(options = {}) {
+  const format = options.format || "json";
+  const apiKey = resolveKeyOrExit(options.apiKey, format);
+
+  try {
+    const result = await xhsHotList(apiKey);
+    outputResult(result, format, hotListTextFormatter);
+    process.exit(0);
+  } catch (err) {
+    handleApiError(err, format);
+    process.exit(1);
+  }
+}
+
+async function notePublishCommand(type, options = {}) {
+  const format = options.format || "json";
+  const apiKey = resolveKeyOrExit(options.apiKey, format);
+
+  try {
+    if (type !== "normal" && type !== "video") {
+      throw validationError(`笔记类型仅支持 normal 或 video，收到: ${type}`);
+    }
+
+    const imageUrls = options.images
+      ? options.images.split(",").map((value) => value.trim()).filter(Boolean)
+      : [];
+    const imageFiles = options.imageFile || [];
+    const imageBase64 = (options.imageBase64 || []).map((value, index) =>
+      resolveBase64Input(value, `第 ${imageUrls.length + imageFiles.length + index + 1} 张图片`)
+    );
+    const videoBase64 = options.videoBase64
+      ? resolveBase64Input(options.videoBase64, "视频")
+      : undefined;
+    const coverBase64 = options.coverBase64
+      ? resolveBase64Input(options.coverBase64, "视频封面")
+      : undefined;
+    const imageCount = imageUrls.length + imageFiles.length + imageBase64.length;
+    const videoSources = [options.video, options.videoFile, videoBase64].filter(Boolean);
+    const coverSources = [options.cover, options.coverFile, coverBase64].filter(Boolean);
+    const validDays = Number(options.uploadValidDays || 7);
+
+    if (validDays !== 1 && validDays !== 7) {
+      throw validationError(`--upload-valid-days 仅支持 1 或 7，收到: ${options.uploadValidDays}`);
+    }
+    if (type === "normal") {
+      if (videoSources.length > 0 || coverSources.length > 0) {
+        throw validationError("normal 类型不能使用视频或封面参数");
+      }
+      if (imageCount === 0) {
+        throw validationError("normal 类型至少需要一张图片，请使用 --images、--image-file 或 --image-base64");
+      }
+      if (imageCount > 18) {
+        throw validationError(`图片最多 18 张，当前共 ${imageCount} 张`);
+      }
+      imageUrls.forEach((url, index) => validateUrl(url, `第 ${index + 1} 张图片`));
+      imageFiles.forEach((filePath, index) => validateLocalFile(
+        filePath,
+        `第 ${imageUrls.length + index + 1} 张图片`,
+        MAX_IMAGE_SIZE
+      ));
+      imageBase64.forEach((value, index) => validateBase64Size(
+        value,
+        `第 ${imageUrls.length + imageFiles.length + index + 1} 张图片`,
+        MAX_IMAGE_SIZE
+      ));
+    } else {
+      if (imageCount > 0) {
+        throw validationError("video 类型不能使用图片参数");
+      }
+      if (videoSources.length !== 1) {
+        throw validationError("video 类型必须且只能使用 --video、--video-file、--video-base64 之一");
+      }
+      if (coverSources.length > 1) {
+        throw validationError("视频封面只能使用 --cover、--cover-file、--cover-base64 之一");
+      }
+      if (options.video) validateUrl(options.video, "视频");
+      if (options.videoFile) validateLocalFile(options.videoFile, "视频", MAX_UPLOAD_SIZE);
+      if (videoBase64) validateBase64Size(videoBase64, "视频", MAX_UPLOAD_SIZE);
+      if (options.cover) validateUrl(options.cover, "视频封面");
+      if (options.coverFile) validateLocalFile(options.coverFile, "视频封面", MAX_IMAGE_SIZE);
+      if (coverBase64) validateBase64Size(coverBase64, "视频封面", MAX_IMAGE_SIZE);
+    }
+
+    let images;
+    let video;
+    let cover;
+    if (type === "normal") {
+      const uploadedImages = await Promise.all([
+        ...imageFiles.map((filePath, index) => uploadMedia(
+          apiKey,
+          { filePath, validDays },
+          `第 ${imageUrls.length + index + 1} 张图片`
+        )),
+        ...imageBase64.map((fileBase64, index) => uploadMedia(
+          apiKey,
+          { fileBase64, defaultContentType: "image/jpeg", validDays },
+          `第 ${imageUrls.length + imageFiles.length + index + 1} 张图片`
+        )),
+      ]);
+      images = [...imageUrls, ...uploadedImages];
+    } else {
+      video = options.video;
+      if (options.videoFile) {
+        video = await uploadMedia(apiKey, { filePath: options.videoFile, validDays }, "视频");
+      } else if (videoBase64) {
+        video = await uploadMedia(
+          apiKey,
+          { fileBase64: videoBase64, defaultContentType: "video/mp4", validDays },
+          "视频"
+        );
+      }
+
+      cover = options.cover;
+      if (options.coverFile) {
+        cover = await uploadMedia(apiKey, { filePath: options.coverFile, validDays }, "视频封面");
+      } else if (coverBase64) {
+        cover = await uploadMedia(
+          apiKey,
+          { fileBase64: coverBase64, defaultContentType: "image/jpeg", validDays },
+          "视频封面"
+        );
+      }
+    }
+
+    const result = await xhsNotePublish(apiKey, {
+      type,
+      title: options.title,
+      content: options.content,
+      images,
+      video,
+      cover,
+    });
+    outputResult(result, format, notePublishTextFormatter);
+    process.exit(0);
+  } catch (err) {
+    handleApiError(err, format);
+    process.exit(1);
+  }
+}
+
+module.exports = { hotListCommand, hotListTextFormatter, notePublishCommand, notePublishTextFormatter };