aiconductor-cli 1.5.0 → 1.6.0

package/src/api.test.js

@@ -4,7 +4,23 @@ const http = require("node:http");
 const https = require("node:https");
 const test = require("node:test");
 
-const { hotList, webSearch, xhsHotList } = require("./api");const {
+const { hotList, webSearch, xhsHotList } = require("./api");
+const {
+  xhsNoteInfo,
+  xhsNoteComments,
+  xhsNoteSearch,
+  xhsUserInfo,
+  xhsUserNotes,
+  resolveXhsShortLink,
+} = require("./api");
+const {
+  extractUrlFromText,
+  parseXhsNoteId,
+  parseXhsUserId,
+  formatXhsTime,
+  toCount,
+} = require("./lib/cli-utils");
+const {
   buildBriefingResult,
   formatHotListText,
   parseLimit,
@@ -433,6 +449,40 @@ test("wx endpoints turn HTTP 200 business failures into api_error", async () =>
   );
 });
 
+test("wx history treats an upstream code inside a successful response as a failure", async () => {
+  // 2026-11-05 线上实测：平台仍回 success:true，把上游失败塞进 data.code（api_docs：code 0 为成功），
+  // 文章数组为空。若照 success 判断，会把「上游挂了」报成「这个号最近没发文」。
+  const upstreamFailure = {
+    success: true,
+    message: "未能获取到任何数据。请检查参数或账户余额。",
+    billing: { pages_billed: 0, transaction_ids: [] },
+    data: { code: 20001, msg: "error", data: [], now_page: 0, now_page_articles_num: 0 },
+  };
+
+  await assert.rejects(
+    () => captureRequest(() => wxHistoryArticles("test-key", { name: "人民日报" }), upstreamFailure),
+    (err) =>
+      err.type === "api_error" &&
+      err.message.includes("未能获取到任何数据") &&
+      err.message.includes("20001")
+  );
+});
+
+test("wx history still resolves an empty page when the upstream code is 0", async () => {
+  const emptyButOk = {
+    success: true,
+    message: "微信公众号历史文章获取完成。成功获取 1 页数据，共 0 篇文章。",
+    data: { code: 0, msg: "success", data: [], now_page: 1 },
+  };
+
+  const request = await captureRequest(
+    () => wxHistoryArticles("test-key", { name: "不存在的号" }),
+    emptyButOk
+  );
+  assert.deepEqual(request.result.data.data, []);
+  assert.equal(request.result.success, true);
+});
+
 test("wx history formatter lists documented article fields", () => {
   const text = formatHistoryText({
     data: {
@@ -479,3 +529,249 @@ test("wx article-data formatter labels the fields the live endpoint returns", ()
   const emptyText = formatArticleDataText({ data: {} });
   assert.match(emptyText, /上游未返回字段/);
 });
+
+// ---------------------------------------------------------------------------
+// 小红书（xhs）数据命令组
+// 依据：api_docs/xhs_*.md 的请求字段 + 2026-11-05 线上真实响应
+// ---------------------------------------------------------------------------
+
+test("xhsNoteInfo posts note_id to the v3 note detail endpoint over http", async () => {
+  const request = await captureRequest(
+    () => xhsNoteInfo("test-key", "6ae972260000000015020d84"),
+    { success: true, message: "笔记详情获取成功", note_data: { note_id: "6ae972260000000015020d84" }, billing: { service_fee: 0.15 } },
+    http
+  );
+
+  assert.equal(request.options.hostname, "plugin.aiconductor.fun");
+  assert.equal(request.options.path, "/api/xhs_note_info_v3");
+  assert.equal(request.options.port, 80);
+  assert.equal(request.options.method, "POST");
+  assert.equal(request.options.headers.Authorization, "Bearer test-key");
+  assert.deepEqual(request.body, { note_id: "6ae972260000000015020d84" });
+  // billing 不进任何输出
+  assert.equal(request.result.billing, undefined);
+  assert.equal(request.result.note_data.note_id, "6ae972260000000015020d84");
+});
+
+test("xhsNoteComments sends pagination fields and accepts share_text", async () => {
+  const request = await captureRequest(
+    () => xhsNoteComments("test-key", { noteId: "6ae972260000000015020d84", maxPages: 2, maxSeconds: 40 }),
+    { success: true, data: { comments: [], total_comments: 0 } },
+    http
+  );
+
+  assert.equal(request.options.path, "/api/xhs_note_comments_fast");
+  assert.equal(request.options.port, 80);
+  assert.deepEqual(request.body, {
+    note_id: "6ae972260000000015020d84",
+    max_pages: 2,
+    max_seconds: 40,
+  });
+});
+
+test("xhsNoteComments prefers share_text only when note id is absent", async () => {
+  const withShare = await captureRequest(
+    () => xhsNoteComments("test-key", { shareText: "https://xhslink.cn/o/85lbqBJtO94" }),
+    { success: true, data: { comments: [] } },
+    http
+  );
+  assert.deepEqual(withShare.body, { share_text: "https://xhslink.cn/o/85lbqBJtO94" });
+
+  // 两个都没给：本地拒绝，不发请求
+  await assert.rejects(() => xhsNoteComments("test-key", {}), { type: "validation_error" });
+  // 越界：max_pages 只允许 1~5，max_seconds 不超过平台 170s 上限
+  await assert.rejects(
+    () => xhsNoteComments("test-key", { noteId: "6ae972260000000015020d84", maxPages: 6 }),
+    { type: "validation_error" }
+  );
+  await assert.rejects(
+    () => xhsNoteComments("test-key", { noteId: "6ae972260000000015020d84", maxSeconds: 171 }),
+    { type: "validation_error" }
+  );
+});
+
+test("xhsNoteSearch maps keyword filters to the v3 search endpoint", async () => {
+  const request = await captureRequest(
+    () => xhsNoteSearch("test-key", {
+      keyword: "AI编程",
+      maxPages: 3,
+      sort: "popularity_descending",
+      noteTime: "week",
+      noteType: "video",
+    }),
+    { success: true, data: { items: [], has_more: false } },
+    http
+  );
+
+  assert.equal(request.options.path, "/api/xhs_note_search_v3");
+  assert.equal(request.options.port, 80);
+  assert.equal(request.options.headers.Authorization, "Bearer test-key");
+  assert.deepEqual(request.body, {
+    keyword: "AI编程",
+    max_pages: 3,
+    sort: "popularity_descending",
+    note_time: "week",
+    note_type: "video",
+  });
+});
+
+test("xhsNoteSearch rejects unknown enum values and empty keywords", async () => {
+  await assert.rejects(() => xhsNoteSearch("test-key", { keyword: "  " }), { type: "validation_error" });
+  await assert.rejects(
+    () => xhsNoteSearch("test-key", { keyword: "AI", sort: "likes" }),
+    { type: "validation_error" }
+  );
+  await assert.rejects(
+    () => xhsNoteSearch("test-key", { keyword: "AI", noteTime: "year" }),
+    { type: "validation_error" }
+  );
+  await assert.rejects(
+    () => xhsNoteSearch("test-key", { keyword: "AI", noteType: "image" }),
+    { type: "validation_error" }
+  );
+});
+
+test("xhsUserInfo maps user_id and xhsUserNotes maps pagination", async () => {
+  const userRequest = await captureRequest(
+    () => xhsUserInfo("test-key", "53cd3bbbb4c4d64f93463018"),
+    { success: true, user_info: { basic_info: {} } },
+    http
+  );
+  assert.equal(userRequest.options.path, "/api/xhs_user_info_v2");
+  assert.equal(userRequest.options.port, 80);
+  assert.deepEqual(userRequest.body, { user_id: "53cd3bbbb4c4d64f93463018" });
+
+  const notesRequest = await captureRequest(
+    () => xhsUserNotes("test-key", { userId: "53cd3bbbb4c4d64f93463018", maxPages: 2 }),
+    { success: true, data: { notes: [] } },
+    http
+  );
+  // 刻意打 v2 端点：v2/v3 现在同上游同输出，v2 是历史真实流量所在
+  assert.equal(notesRequest.options.path, "/api/xhs_user_notes_v2");
+  assert.equal(notesRequest.options.port, 80);
+  assert.deepEqual(notesRequest.body, { user_id: "53cd3bbbb4c4d64f93463018", max_pages: 2 });
+});
+
+test("xhs endpoints turn business failures into api_error", async () => {
+  await assert.rejects(
+    () => captureRequest(
+      () => xhsNoteInfo("test-key", "6ae972260000000015020d84"),
+      { success: false, message: "笔记ID无效或笔记不可访问" },
+      http
+    ),
+    { type: "api_error", message: "笔记ID无效或笔记不可访问" }
+  );
+});
+
+test("parseXhsNoteId and parseXhsUserId accept ids, long links and share copy", () => {
+  const id = "6ae972260000000015020d84";
+  assert.equal(parseXhsNoteId(id), id);
+  assert.equal(
+    parseXhsNoteId(`字节早就不是下狗了 https://www.xiaohongshu.com/discovery/item/${id}?xsec_token=abc 复制内容`),
+    id
+  );
+  assert.equal(parseXhsNoteId(`https://www.xiaohongshu.com/explore/${id}?xsec_source=pc_share`), id);
+  // 小红书号/主页/空串都不该被当成 note id
+  assert.equal(parseXhsNoteId("hainingshushu"), null);
+  assert.equal(parseXhsNoteId(""), null);
+  assert.equal(parseXhsNoteId(undefined), null);
+
+  const userId = "53cd3bbbb4c4d64f93463018";
+  assert.equal(parseXhsUserId(userId), userId);
+  assert.equal(parseXhsUserId(`https://www.xiaohongshu.com/user/profile/${userId}?xsec_token=x`), userId);
+  assert.equal(parseXhsUserId("https://www.xiaohongshu.com/explore/6ae972260000000015020d84"), null);
+});
+
+test("extractUrlFromText pulls the first url out of share copy", () => {
+  assert.equal(
+    extractUrlFromText("字节早就不是下狗了，不想承认也不行 https://xhslink.cn/o/85lbqBJtO94 复制内容，然后进入【小红书】查看相关笔记。"),
+    "https://xhslink.cn/o/85lbqBJtO94"
+  );
+  // 中文全角标点紧贴链接时不能带进 url
+  assert.equal(extractUrlFromText("看这个https://xhslink.cn/o/abc），很准"), "https://xhslink.cn/o/abc");
+  assert.equal(extractUrlFromText("没有链接"), null);
+});
+
+test("formatXhsTime renders UTC epoch as Beijing time", () => {
+  // 独立来源：同一视频笔记 note_info.time = 1793578330，+8h 等于 search 返回的 notePublishTime "2026-11-02 08:12:10"
+  assert.equal(formatXhsTime(1793578330), "2026-11-02 08:12:10");
+  // 毫秒（用户笔记列表）同口径
+  assert.equal(formatXhsTime(1793690772000), "2026-11-03 15:26:12");
+  assert.equal(formatXhsTime(0), "");
+  assert.equal(formatXhsTime(null), "");
+});
+
+test("toCount normalises string counts coming from the xhs upstream", () => {
+  assert.equal(toCount("54"), 54);
+  assert.equal(toCount("1,234"), 1234);
+  assert.equal(toCount(7), 7);
+  assert.equal(toCount("1.2万"), 12000);
+  assert.equal(toCount("1万+"), 10000);
+  assert.equal(toCount(undefined), 0);
+  assert.equal(toCount("abc"), 0);
+});
+
+test("resolveXhsShortLink follows the 302 to the real note url", async () => {
+  const finalUrl = "https://www.xiaohongshu.com/discovery/item/6ae972260000000015020d84?type=normal&xsec_token=abc";
+  const originalRequest = https.request;
+  https.request = (options, responseCallback) => {
+    const request = new EventEmitter();
+    request.setTimeout = () => {};
+    request.end = () => {
+      const response = new EventEmitter();
+      response.statusCode = 302;
+      response.headers = { location: finalUrl };
+      response.resume = () => {};
+      responseCallback(response);
+    };
+    request.destroy = () => {};
+    return request;
+  };
+
+  try {
+    const url = await resolveXhsShortLink("https://xhslink.cn/o/85lbqBJtO94");
+    assert.equal(url, finalUrl);
+  } finally {
+    https.request = originalRequest;
+  }
+});
+
+test("xhs text formatters: 评论按赞排序并展开楼内回复，搜索按赞排序", () => {
+  const { commentsTextFormatter, searchTextFormatter, noteTextFormatter } = require("./commands/xhs");
+
+  const commentsText = commentsTextFormatter({
+    data: {
+      has_more: true,
+      total_pages: 1,
+      comments: [
+        { content: "低赞", like_count: "1", sub_comment_count: "0", user: { original_name: "甲" } },
+        {
+          content: "高赞",
+          like_count: "43",
+          sub_comment_count: "1",
+          user: { original_name: "乙" },
+          sub_comments: [{ content: "楼内回复", user: { original_name: "丙" } }],
+        },
+      ],
+    },
+  });
+  assert.match(commentsText, /共取到 2 条评论/);
+  assert.ok(commentsText.indexOf("高赞") < commentsText.indexOf("低赞"), "评论应按点赞降序");
+  assert.match(commentsText, /↳ 丙: 楼内回复/);
+  assert.match(commentsText, /还有更多评论/);
+
+  const searchText = searchTextFormatter({
+    data: {
+      has_more: false,
+      items: [
+        { noteInfo: { title: "低", likeNum: 5, favNum: 1, cmtNum: 0, noteType: "normal" }, userInfo: { nickName: "A" } },
+        { noteInfo: { title: "高", likeNum: 900, favNum: 10, cmtNum: 3, noteType: "video" }, userInfo: { nickName: "B" } },
+      ],
+    },
+  });
+  assert.ok(searchText.indexOf("高") < searchText.indexOf("低"), "搜索结果应按点赞降序");
+
+  // 时间口径：上游是 UTC epoch，展示必须 +8（独立来源：+8h 等于上游 notePublishTime）
+  const noteText = noteTextFormatter({ note_data: { title: "T", type: "normal", time: 1793578330 } });
+  assert.match(noteText, /2026-11-02 08:12:10/);
+});

package/src/commands/xhs.js

@@ -1,7 +1,29 @@
 const fs = require("fs");
 const path = require("path");
-const { r2Upload, xhsHotList, xhsNotePublish } = require("../api");
-const { outputResult, resolveKeyOrExit, handleApiError } = require("../lib/cli-utils");
+const {
+  r2Upload,
+  xhsHotList,
+  xhsNotePublish,
+  xhsNoteInfo,
+  xhsNoteComments,
+  xhsNoteSearch,
+  xhsUserInfo,
+  xhsUserNotes,
+  resolveXhsShortLink,
+} = require("../api");
+const {
+  outputResult,
+  resolveKeyOrExit,
+  handleApiError,
+  extractUrlFromText,
+  parseXhsNoteId,
+  parseXhsUserId,
+  formatXhsTime,
+  toCount,
+  safeParseInt,
+} = require("../lib/cli-utils");
+
+const XHS_SHORT_LINK_HOSTS = ["xhslink.cn", "xhslink.com"];
 
 const MAX_IMAGE_SIZE = 32 * 1024 * 1024;
 const MAX_UPLOAD_SIZE = 100 * 1024 * 1024;
@@ -41,7 +63,7 @@ function validateUrl(value, label) {
   let parsed;
   try {
     parsed = new URL(value);
-  } catch (_) {
+  } catch {
     throw validationError(`${label}不是有效 URL: ${value}`);
   }
   if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
@@ -265,4 +287,323 @@ async function notePublishCommand(type, options = {}) {
   }
 }
 
-module.exports = { hotListCommand, hotListTextFormatter, notePublishCommand, notePublishTextFormatter };
+// ---------------------------------------------------------------------------
+// 小红书数据命令（note / comments / search / user / user-notes）
+// 口径依据：api_docs/xhs_*.md + 2026-11-05 线上实测
+// ---------------------------------------------------------------------------
+
+/**
+ * 把用户输入（笔记链接 / xhslink 短链 / 分享口令 / 裸 note_id）解析成 note_id。
+ * 短链必须本地展开成 302 后的长链，否则拿不到 id。
+ * @param {string} input
+ * @returns {Promise<string>}
+ */
+async function resolveNoteId(input) {
+  const direct = parseXhsNoteId(input);
+  if (direct) return direct;
+
+  const url = extractUrlFromText(typeof input === "string" ? input : "");
+  if (url) {
+    let hostname = "";
+    try {
+      hostname = new URL(url).hostname.toLowerCase();
+    } catch {
+      hostname = "";
+    }
+    if (XHS_SHORT_LINK_HOSTS.includes(hostname)) {
+      const longUrl = await resolveXhsShortLink(url);
+      const id = parseXhsNoteId(longUrl);
+      if (id) return id;
+    }
+  }
+
+  throw validationError("无法从输入里识别小红书笔记（支持笔记链接、xhslink 短链、分享口令或 24 位 note_id）");
+}
+
+/**
+ * 把用户输入（主页链接 / 裸 user_id）解析成 user_id。
+ * @param {string} input
+ * @returns {string}
+ */
+function resolveUserId(input) {
+  const id = parseXhsUserId(input);
+  if (id) return id;
+  throw validationError("无法从输入里识别小红书用户（支持主页链接 /user/profile/ 或 24 位 user_id）");
+}
+
+/**
+ * text 格式化：单篇笔记详情。
+ * @param {object} resp
+ * @returns {string}
+ */
+function noteTextFormatter(resp = {}) {
+  const note = resp.note_data || {};
+  const user = note.user || {};
+  const interact = note.interact_info || {};
+  const lines = [];
+
+  lines.push(`✓ ${note.title || "（无标题）"}`);
+  if (user.nickname) lines.push(`  作者:     ${user.nickname}`);
+  lines.push(`  类型:     ${note.type === "video" ? "视频笔记" : "图文笔记"}`);
+  const publishedAt = formatXhsTime(note.time);
+  if (publishedAt) lines.push(`  发布:     ${publishedAt}`);
+  lines.push(
+    `  互动:     赞 ${toCount(interact.liked_count)} / 藏 ${toCount(interact.collected_count)}` +
+      ` / 评 ${toCount(interact.comment_count)} / 分享 ${toCount(interact.share_count)}`
+  );
+  const tags = (note.tag_list || []).map((tag) => tag.name).filter(Boolean);
+  if (tags.length) lines.push(`  话题:     ${tags.join("、")}`);
+  if (note.image_list && note.image_list.length) {
+    lines.push(`  图片:     ${note.image_list.length} 张`);
+  }
+  if (note.type === "video" && note.video && note.video.duration) {
+    lines.push(`  视频时长: ${Math.round(note.video.duration)}s`);
+  }
+  if (note.desc) {
+    lines.push("");
+    lines.push(note.desc);
+  }
+  if (note.note_id) lines.push("", `笔记 ID: ${note.note_id}`);
+  return lines.join("\n");
+}
+
+/**
+ * text 格式化：笔记评论（按点赞降序）。
+ * @param {object} resp
+ * @returns {string}
+ */
+function commentsTextFormatter(resp = {}) {
+  const data = resp.data || {};
+  const comments = [...(data.comments || [])].sort((a, b) => toCount(b.like_count) - toCount(a.like_count));
+  const lines = [`✓ 共取到 ${comments.length} 条评论`];
+  // total_comments 是本次各页累计的总数，不是笔记真实评论总数（那要 note 接口的 comment_count）
+  if (data.has_more) lines.push(`  提示: 还有更多评论，可加 --max-pages（当前 ${toCount(data.total_pages) || 1} 页）`);
+  comments.forEach((item, index) => {
+    const nick = (item.user && (item.user.original_name || item.user.nickname)) || "匿名";
+    const ip = item.ip_location ? ` · ${item.ip_location}` : "";
+    lines.push("", `[${index + 1}] ${nick}${ip} · 赞 ${toCount(item.like_count)}`);
+    lines.push(`    ${(item.content || "").replace(/\n+/g, " ")}`);
+    const replies = Array.isArray(item.sub_comments) ? item.sub_comments : [];
+    replies.forEach((reply) => {
+      const replyUser = reply.user || {};
+      const replyNick = replyUser.original_name || replyUser.nickname || "匿名";
+      lines.push(`    ↳ ${replyNick}: ${(reply.content || "").replace(/\n+/g, " ")}`);
+    });
+    if (!replies.length && toCount(item.sub_comment_count) > 0) {
+      lines.push(`    ↳ 另有 ${toCount(item.sub_comment_count)} 条回复未展开`);
+    }
+  });
+  return lines.join("\n");
+}
+
+/**
+ * text 格式化：笔记搜索结果（按点赞降序）。
+ * @param {object} resp
+ * @returns {string}
+ */
+function searchTextFormatter(resp = {}) {
+  const data = resp.data || {};
+  const items = data.items || [];
+  const rows = items
+    .map((item) => ({ note: item.noteInfo || {}, user: item.userInfo || {} }))
+    .sort((a, b) => toCount(b.note.likeNum) - toCount(a.note.likeNum));
+
+  const lines = [`✓ 共取到 ${rows.length} 条笔记`];
+  if (data.has_more) lines.push("  提示: 还有更多结果，可加 --max-pages");
+  rows.forEach((row, index) => {
+    const note = row.note;
+    const author = row.user.nickName || "未知作者";
+    lines.push("", `[${index + 1}] ${note.title || "（无标题）"}`);
+    lines.push(
+      `    ${note.noteType === "video" ? "视频" : "图文"} · 赞 ${toCount(note.likeNum)}` +
+        ` / 藏 ${toCount(note.favNum)} / 评 ${toCount(note.cmtNum)} · ${author}`
+    );
+    if (note.notePublishTime) lines.push(`    发布: ${note.notePublishTime}`);
+    if (note.noteLink) lines.push(`    ${note.noteLink}`);
+  });
+  return lines.join("\n");
+}
+
+/**
+ * text 格式化：用户详情。
+ * @param {object} resp
+ * @returns {string}
+ */
+function userInfoTextFormatter(resp = {}) {
+  const info = resp.user_info || {};
+  const basic = info.basic_info || {};
+  const lines = [`✓ ${basic.nickname || "（无昵称）"}`];
+  if (basic.red_id) lines.push(`  小红书号: ${basic.red_id}`);
+  if (basic.ip_location) lines.push(`  地区:     ${basic.ip_location}`);
+  const interactions = info.interactions || [];
+  if (interactions.length) {
+    lines.push(`  互动:     ${interactions.map((item) => `${item.name} ${toCount(item.count)}`).join(" / ")}`);
+  }
+  const tags = info.tags || [];
+  if (tags.length) lines.push(`  标签:     ${tags.join("、")}`);
+  if (basic.desc) lines.push("", basic.desc);
+  return lines.join("\n");
+}
+
+/**
+ * text 格式化：用户笔记列表。
+ * @param {object} resp
+ * @returns {string}
+ */
+function userNotesTextFormatter(resp = {}) {
+  const notes = (resp.data && resp.data.notes) || [];
+  const lines = [`✓ 共取到 ${notes.length} 条笔记`];
+  let totalLikes = 0;
+  notes.forEach((note, index) => {
+    totalLikes += toCount(note.likes);
+    const flags = [];
+    if (note.sticky) flags.push("置顶");
+    if (note.is_goods_note) flags.push("带货");
+    const flagText = flags.length ? ` [${flags.join("/")}]` : "";
+    const published = formatXhsTime(note.time).slice(0, 10);
+    lines.push(
+      "",
+      `[${index + 1}] ${note.title || "（无标题）"}${flagText}`,
+      `    ${note.type === "video" ? "视频" : "图文"} · 赞 ${toCount(note.likes)} / 藏 ${toCount(note.collected_count)}` +
+        ` / 评 ${toCount(note.comments_count)}${published ? ` · ${published}` : ""}`
+    );
+  });
+  if (notes.length) lines.push("", `点赞合计: ${totalLikes}`);
+  return lines.join("\n");
+}
+
+/**
+ * xhs note：获取单篇笔记详情。
+ * @param {string} input 笔记链接 / 短链 / 分享口令 / note_id
+ * @param {{apiKey?: string, format?: "json"|"text"}} options
+ * @returns {Promise<void>}
+ */
+async function noteCommand(input, options = {}) {
+  const format = options.format || "json";
+  const apiKey = resolveKeyOrExit(options.apiKey, format);
+
+  try {
+    const noteId = await resolveNoteId(input);
+    const result = await xhsNoteInfo(apiKey, noteId);
+    outputResult(result, format, noteTextFormatter);
+    process.exit(0);
+  } catch (err) {
+    handleApiError(err, format);
+    process.exit(1);
+  }
+}
+
+/**
+ * xhs comments：获取笔记一级评论（含可见的楼内回复）。
+ * @param {string} input 笔记链接 / 短链 / 分享口令 / note_id
+ * @param {{apiKey?: string, format?: string, maxPages?: string, maxSeconds?: string}} options
+ * @returns {Promise<void>}
+ */
+async function commentsCommand(input, options = {}) {
+  const format = options.format || "json";
+  const apiKey = resolveKeyOrExit(options.apiKey, format);
+
+  try {
+    const noteId = await resolveNoteId(input);
+    const result = await xhsNoteComments(apiKey, {
+      noteId,
+      maxPages: options.maxPages === undefined ? 1 : safeParseInt(options.maxPages, 1),
+      maxSeconds: options.maxSeconds === undefined ? undefined : safeParseInt(options.maxSeconds, 50),
+    });
+    outputResult(result, format, commentsTextFormatter);
+    process.exit(0);
+  } catch (err) {
+    handleApiError(err, format);
+    process.exit(1);
+  }
+}
+
+/**
+ * xhs search：按关键词搜索笔记。
+ * @param {string} keyword
+ * @param {{apiKey?: string, format?: string, sort?: string, noteTime?: string, noteType?: string, maxPages?: string}} options
+ * @returns {Promise<void>}
+ */
+async function searchCommand(keyword, options = {}) {
+  const format = options.format || "json";
+  const apiKey = resolveKeyOrExit(options.apiKey, format);
+
+  try {
+    const result = await xhsNoteSearch(apiKey, {
+      keyword,
+      maxPages: options.maxPages === undefined ? 1 : safeParseInt(options.maxPages, 1),
+      sort: options.sort,
+      noteTime: options.noteTime,
+      noteType: options.noteType,
+    });
+    outputResult(result, format, searchTextFormatter);
+    process.exit(0);
+  } catch (err) {
+    handleApiError(err, format);
+    process.exit(1);
+  }
+}
+
+/**
+ * xhs user：获取用户详情。
+ * @param {string} input 主页链接 / user_id
+ * @param {{apiKey?: string, format?: "json"|"text"}} options
+ * @returns {Promise<void>}
+ */
+async function userCommand(input, options = {}) {
+  const format = options.format || "json";
+  const apiKey = resolveKeyOrExit(options.apiKey, format);
+
+  try {
+    const userId = resolveUserId(input);
+    const result = await xhsUserInfo(apiKey, userId);
+    outputResult(result, format, userInfoTextFormatter);
+    process.exit(0);
+  } catch (err) {
+    handleApiError(err, format);
+    process.exit(1);
+  }
+}
+
+/**
+ * xhs user-notes：获取用户笔记列表。
+ * @param {string} input 主页链接 / user_id
+ * @param {{apiKey?: string, format?: string, maxPages?: string}} options
+ * @returns {Promise<void>}
+ */
+async function userNotesCommand(input, options = {}) {
+  const format = options.format || "json";
+  const apiKey = resolveKeyOrExit(options.apiKey, format);
+
+  try {
+    const userId = resolveUserId(input);
+    const result = await xhsUserNotes(apiKey, {
+      userId,
+      maxPages: options.maxPages === undefined ? 1 : safeParseInt(options.maxPages, 1),
+    });
+    outputResult(result, format, userNotesTextFormatter);
+    process.exit(0);
+  } catch (err) {
+    handleApiError(err, format);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  hotListCommand,
+  hotListTextFormatter,
+  notePublishCommand,
+  notePublishTextFormatter,
+  noteCommand,
+  commentsCommand,
+  searchCommand,
+  userCommand,
+  userNotesCommand,
+  noteTextFormatter,
+  commentsTextFormatter,
+  searchTextFormatter,
+  userInfoTextFormatter,
+  userNotesTextFormatter,
+  resolveNoteId,
+  resolveUserId,
+};