aiconductor-cli 1.3.4 → 1.4.0

package/api_docs/xhs_user_notes_v3.md

@@ -0,0 +1,46 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/xhs_user_notes_v3`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+根据用户 ID 获取小红书用户笔记列表，支持自动翻页（cursor 机制），兼容图文与视频笔记，按页计费。费用以 api_services 表配置为准（service_code: `xhs_user_notes_v2`）。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| user_id | string | 是 | — | 小红书用户 ID |
+| max_pages | int | 否 | 1 | 最大翻页数 |
+| max_seconds | int | 否 | 50 | 最长运行时长（秒） |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| billing | object | 计费信息（service_fee / discount_applied / balance_before / balance_after / currency / pages_billed / total_service_fee / transaction_ids） |
+| data.notes | array[object] | 笔记列表（见下） |
+
+`data.notes[]` 字段：`noteId`(string)、`time`(int, 毫秒时间戳)、`title`(string)、`type`(string, normal/video)、`desc`(string)、`time_desc`(string)、`likes`(int)、`comments_count`(int)、`collected_count`(int)、`shared_count`(int)、`ip_location`(string)、`sticky`(bool)、`is_goods_note`(bool)、`has_music`(bool)、`user`(object{user_id, nickname, avatar})、`images`(array[{url, url_size_large, width, height}])。
+视频笔记额外包含 `video`(object)：`duration`(int)、`width`(int)、`height`(int)、`cover_url`(string)、`thumbnail_url`(string)、`streams`(array[{codec, quality, url, backup_urls, width, height, duration, fps, format, size}])。
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/xhs_user_notes_v3" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{"user_id": "5f8e9c1b0000000001001a2b", "max_pages": 3}'
+```
+
+## 注意事项
+1. 按页计费：每成功获取一页计费一次，余额不足、超时或上游无更多数据自动停止翻页。
+2. 采用后扣费模式：仅成功获取并解析后才扣费，失败不扣费。
+3. 翻页由内部维护 `cursor`（取每页最后一条笔记的 cursor），调用方无需关心。
+4. 返回数据同时兼容图文（normal）与视频（video）笔记，视频笔记带 streams 流信息。
+5. 上游单页请求超时 55s，最多重试 3 次。

package/bin/aiconductor-cli.js

@@ -7,7 +7,8 @@ const {
   listCommand: webpageListCommand,
   deleteCommand: webpageDeleteCommand,
 } = require("../src/commands/md_publish");
-const { searchCommand } = require("../src/commands/web_search");
+const { searchCommand } = require("../src/commands/web_search");
+const { briefingCommand } = require("../src/commands/content");
 const {
   videoInfoCommand,
   videoCommentsCommand,
@@ -17,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();
 
@@ -111,8 +112,8 @@ searchCmd
     searchCommand(query, "web", options);
   });
 
-searchCmd
-  .command("image")
+searchCmd
+  .command("image")
   .description("图片搜索")
   .argument("<query>", "搜索关键词（1~100字符）")
   .option("-k, --api-key <key>", "AIConductor API Key（也可通过 AICONDUCTOR_API_KEY 环境变量或 .env 文件提供）")
@@ -124,9 +125,25 @@ searchCmd
   .option("--image-shapes <shapes>", "图片形状，以 | 分隔：横长方形、竖长方形、方形")
   .option("--query-rewrite", "开启 Query 改写")
   .option("-f, --format <format>", "输出格式：json 或 text", "json")
-  .action((query, options) => {
-    searchCommand(query, "image", options);
-  });
+  .action((query, options) => {
+    searchCommand(query, "image", options);
+  });
+
+// content 子命令组
+const contentCmd = program
+  .command("content")
+  .description("内容选题与素材工具");
+
+contentCmd
+  .command("briefing")
+  .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")
+  .option("-f, --format <format>", "输出格式：json 或 text", "json")
+  .action((options) => {
+    briefingCommand(options);
+  });
 
 // 未知命令处理
 
@@ -205,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.4",
+  "version": "1.4.0",
   "description": "AIConductor CLI 工具箱",
   "keywords": [
     "aiconductor",

package/src/api.js

@@ -1,4 +1,5 @@
-const https = require("https");
+const http = require("http");
+const https = require("https");
 const fs = require("fs");
 const path = require("path");
 
@@ -8,6 +9,8 @@ const MD_TO_HTML_API_PATH = "/api/md_to_html";
 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";
@@ -75,14 +78,15 @@ function validateInt(value, name) {
  * @param {string} host
  * @param {string} path
  * @param {object} body
- * @returns {Promise<object>}
- */
-function httpPost(host, requestPath, body, headers = {}) {
+ * @param {typeof http|typeof https} [transport]
+ * @returns {Promise<object>}
+ */
+function httpPost(host, requestPath, body, headers = {}, transport = https) {
   return new Promise((resolve, reject) => {
     const data = JSON.stringify(body);
     const options = {
       hostname: host,
-      port: 443,
+      port: transport === http ? 80 : 443,
       path: requestPath,
       method: "POST",
       headers: {
@@ -92,7 +96,7 @@ function httpPost(host, requestPath, body, headers = {}) {
       },
     };
 
-    const req = https.request(options, (res) => {
+    const req = transport.request(options, (res) => {
       let chunks = [];
       res.on("data", (chunk) => chunks.push(chunk));
       res.on("end", () => {
@@ -343,6 +347,56 @@ async function webSearch(apiKey, params) {
 
   return result;
 }
+
+/**
+ * 聚合多个平台的热榜条目。
+ * @param {string} apiKey
+ * @param {{ sourceIds: string[]|string, limit?: number|string }} params
+ * @returns {Promise<object>}
+ */
+async function hotList(apiKey, params) {
+  const inputSources = Array.isArray(params.sourceIds)
+    ? params.sourceIds
+    : String(params.sourceIds || "").split(",");
+  const sourceIds = [...new Set(inputSources.map((source) => String(source).trim()).filter(Boolean))];
+  if (sourceIds.length === 0) {
+    throw Object.assign(new Error("sourceIds 至少需要提供一个来源"), { type: "validation_error" });
+  }
+  if (sourceIds.length > 52) {
+    throw Object.assign(new Error("sourceIds 最多支持 52 个来源"), { type: "validation_error" });
+  }
+
+  const limit = validatePositiveInt(params.limit === undefined ? 30 : params.limit, "limit", 30);
+  // The hot-list service is currently served over HTTP; see api_docs/hot_list_mixed.md.
+  const resp = await httpPost(API_HOST, HOT_LIST_API_PATH, {
+    source_ids: sourceIds,
+    latest: true,
+    limit,
+  }, {
+    Authorization: `Bearer ${apiKey}`,
+  }, http);
+  const result = stripBilling(resp);
+  if (result?.success === false) {
+    throw Object.assign(new Error(result.message || "热榜接口返回失败"), { type: "api_error" });
+  }
+  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 并发布
@@ -537,7 +591,9 @@ module.exports = {
   publishMdToHtml,
   getPublishedWebpages,
   deletePublishedWebpage,
-  webSearch,
+  webSearch,
+  hotList,
+  xhsHotList,
   douyinVideoInfo,
   douyinVideoComments,
   douyinUserVideos,

package/src/api.test.js

@@ -1,15 +1,24 @@
 const assert = require("node:assert/strict");
 const { EventEmitter } = require("node:events");
+const http = require("node:http");
 const https = require("node:https");
 const test = require("node:test");
 
-const { webSearch } = require("./api");
+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: {} }) {
-  const originalRequest = https.request;
+function captureRequest(callback, responseBody = { success: true, billing: {} }, transport = https) {
+  const originalRequest = transport.request;
   let captured;
-  https.request = (options, responseCallback) => {
+  transport.request = (options, responseCallback) => {
     const request = new EventEmitter();
     const chunks = [];
     request.write = (chunk) => chunks.push(Buffer.from(chunk));
@@ -24,8 +33,11 @@ function captureRequest(callback, responseBody = { success: true, billing: {} })
     return request;
   };
 
-  return callback().then(() => captured).finally(() => {
-    https.request = originalRequest;
+  return callback().then((result) => {
+    captured.result = result;
+    return captured;
+  }).finally(() => {
+    transport.request = originalRequest;
   });
 }
 
@@ -155,3 +167,202 @@ test("webSearch raises nested API failures", async () => {
     { type: "api_error", message: "image 搜索的 count 必须为 1~5" }
   );
 });
+
+test("hotList sends deduplicated sources with current defaults", async () => {
+  const request = await captureRequest(
+    () => hotList("test-key", { sourceIds: ["zhihu", "weibo", "zhihu", "aihot"] }),
+    undefined,
+    http
+  );
+
+  assert.equal(request.options.path, "/api/hot_list_mixed");
+  assert.equal(request.options.port, 80);
+  assert.equal(request.options.headers.Authorization, "Bearer test-key");
+  assert.deepEqual(request.body, {
+    source_ids: ["zhihu", "weibo", "aihot"],
+    latest: true,
+    limit: 30,
+  });
+  assert.deepEqual(parseSourceIds(), DEFAULT_HOT_LIST_SOURCES);
+  assert.deepEqual(parseSourceIds("zhihu, weibo,zhihu"), ["zhihu", "weibo"]);
+});
+
+test("hotList validates source IDs and limits", async () => {
+  await assert.rejects(hotList("test-key", { sourceIds: [] }), { type: "validation_error" });
+  await assert.rejects(
+    hotList("test-key", { sourceIds: Array.from({ length: 53 }, (_, index) => `source-${index}`) }),
+    { type: "validation_error" }
+  );
+  await assert.rejects(hotList("test-key", { sourceIds: ["zhihu"], limit: 0 }), { type: "validation_error" });
+  await assert.rejects(hotList("test-key", { sourceIds: ["zhihu"], limit: 31 }), { type: "validation_error" });
+});
+
+test("formatHotListText keeps successful sources and reports failures", () => {
+  const text = formatHotListText({
+    data: {
+      sources: [{
+        source_id: "zhihu",
+        status: "cache",
+        updated_time: 0,
+        items: [{ title: "AI 应用趋势", url: "https://example.com/topic", pub_date: "今天" }],
+      }],
+      failed_sources: [{ source_id: "weibo", message: "上游暂不可用" }],
+    },
+  });
+
+  assert.match(text, /【zhihu】缓存/);
+  assert.match(text, /AI 应用趋势/);
+  assert.match(text, /URL: https:\/\/example\.com\/topic/);
+  assert.match(text, /失败来源:/);
+  assert.match(text, /weibo: 上游暂不可用/);
+});
+
+test("hotList raises API failures", async () => {
+  await assert.rejects(
+    captureRequest(
+      () => hotList("test-key", { sourceIds: ["zhihu"] }),
+      { success: false, message: "没有可用热榜来源" },
+      http
+    ),
+    { 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

@@ -0,0 +1,184 @@
+const { hotList, xhsHotList } = require("../api");
+const { outputResult, outputError, resolveKeyOrExit, handleApiError } = require("../lib/cli-utils");
+
+const DEFAULT_HOT_LIST_SOURCES = ["zhihu", "weibo", "douyin", "aihot"];
+
+/**
+ * 解析并去重逗号分隔的平台来源 ID。
+ * @param {string|undefined} value
+ * @returns {string[]}
+ */
+function parseSourceIds(value) {
+  const rawSources = value === undefined ? DEFAULT_HOT_LIST_SOURCES : String(value).split(",");
+  const sourceIds = [...new Set(rawSources.map((source) => source.trim()).filter(Boolean))];
+  if (sourceIds.length === 0) {
+    throw Object.assign(new Error("--sources 至少需要提供一个来源 ID"), { type: "validation_error" });
+  }
+  if (sourceIds.length > 52) {
+    throw Object.assign(new Error("--sources 最多支持 52 个来源"), { type: "validation_error" });
+  }
+  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
+ * @returns {string}
+ */
+function formatHotListText(result = {}) {
+  const data = result.data || {};
+  const sources = data.sources || [];
+  const failedSources = data.failed_sources || [];
+  const lines = ["热点选题简报"];
+
+  if (!sources.length) {
+    lines.push("没有获取到可用热点来源。");
+  }
+
+  sources.forEach((source) => {
+    const status = source.status === "cache" ? "缓存" : source.status || "未知状态";
+    lines.push(`\n【${source.source_id}】${status}`);
+    if (source.updated_time) lines.push(`更新时间: ${formatTimestamp(source.updated_time)}`);
+    (source.items || []).forEach((item, index) => {
+      lines.push(`[${index + 1}] ${item.title || "未命名条目"}`);
+      if (item.url) lines.push(`  URL: ${item.url}`);
+      if (item.pub_date) lines.push(`  发布时间: ${item.pub_date}`);
+    });
+  });
+
+  if (failedSources.length) {
+    lines.push("\n失败来源:");
+    failedSources.forEach((source) => {
+      lines.push(`- ${source.source_id}: ${source.message || "未知错误"}`);
+    });
+  }
+
+  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();
+}
+
+/**
+ * content briefing 命令。
+ * @param {{ apiKey?: string, sources?: string, limit?: string, format?: "json"|"text" }} options
+ * @returns {Promise<void>}
+ */
+async function briefingCommand(options = {}) {
+  const format = options.format || "json";
+  const apiKey = resolveKeyOrExit(options.apiKey, format);
+
+  try {
+    const hotListParams = {
+      sourceIds: parseSourceIds(options.sources),
+      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) {
+    if (err.type === "validation_error") {
+      outputError(err, format);
+    } else {
+      handleApiError(err, format);
+    }
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  briefingCommand,
+  buildBriefingResult,
+  formatHotListText,
+  parseLimit,
+  parseSourceIds,
+  DEFAULT_HOT_LIST_SOURCES,
+};