aiconductor-cli 1.5.1 → 1.6.0

package/AGENTS.md

@@ -68,7 +68,7 @@ platform 侧还有、CLI 未接 10 个：`wx_rss_reader`、`flow_wx_history_arti
 | 命令 | 用途 |
 |---|---|
 | `npm install` | 安装唯一依赖 `commander`（有 lock） |
-| `npm test` | `node --test`，27 个用例，离线打桩，不需要 API Key |
+| `npm test` | `node --test`，40 个用例，离线打桩，不需要 API Key |
 | `node bin/aiconductor-cli.js --help` | 不安装也能本地运行，核对命令面 |
 | `node bin/aiconductor-cli.js <组> <子命令> --help` | 核对某个命令的参数与默认值；CLI 契约以它为准 |
 | `npm pack --dry-run` | 确认发布内容：含 `src/**`（含测试）、`api_docs/`、`AGENTS.md`，不含 `.agents/` 与 `references/`（平台侧规范只在本机，已从 `.npmignore`/`.gitignore` 排掉） |
@@ -96,7 +96,7 @@ platform 侧还有、CLI 未接 10 个：`wx_rss_reader`、`flow_wx_history_arti
 
 - 技能放 `.agents/skills/<name>/`（2026-11-04 从 `.codex/skills/` 迁来，内容逐字未变，`git mv` 效果）：pi 从 cwd 向上到仓库根发现项目级 `.agents/skills/`（`dist/core/package-manager.js` 的 `collectAncestorAgentsSkillDirs`），`.codex/skills/` 从来不是 pi 的发现路径。代价：项目里有 `.agents/skills/` 会触发**项目信任门禁**（`hasTrustRequiringProjectResources` 返回 true），未信任时这 11 个技能不加载。**这是故意的**（2026-11-04）：本仓技能是**上架产物**（WorkBuddy / 技能仓库的发布件），不是本机开发时要用的上下文，所以 `~/.pi/agent/trust.json` 已给 `D:/Development/aiconductor-cli` 显式写 `false`——pi 不弹信任提示、技能不进上下文；需要某条技能内容时直接 `read .agents/skills/<name>/SKILL.md`，**不要为了加载它去信任项目**。
 - `.gitignore` 用 `.agents/*` + `!.agents/skills/` 只放行技能，`.agents/ledger.md`、`.agents/plans/` 属本机脚手架不入库——**别把 `.agents/` 整目录 ignore**，那会让技能从版本控制里消失（`git status` 表现为 `.codex/` 全删、新目录全是 `??`）。
-- 目录名、frontmatter `name`、实际调用的命令必须一致；`description` 写能力 + 用户原话触发 + 与相邻 skill 的边界（简报→content-briefing，单点搜索→doubao-search，网页→webpage-publish，抖音数据→douyin-toolbox，抖音文案→douyin-script-extract，抖音选题→douyin-topic-radar，抖音评论→douyin-comment-insight，抖音账号→douyin-account-analyze，小红书→xhs-note-publish，公众号发文列表→wx-account-articles，单篇公众号数据→wx-article-data）。
+- 目录名、frontmatter `name`、实际调用的命令必须一致；`description` 写能力 + 用户原话触发 + 与相邻 skill 的边界（简报→content-briefing，单点搜索→doubao-search，网页→webpage-publish，抖音数据→douyin-toolbox，抖音文案→douyin-script-extract，抖音选题→douyin-topic-radar，抖音评论→douyin-comment-insight，抖音账号→douyin-account-analyze，小红书发布→xhs-note-publish，小红书选题→xhs-topic-radar，小红书单篇拆解→xhs-note-insight，小红书账号→xhs-account-analyze，公众号发文列表→wx-account-articles，单篇公众号数据→wx-article-data）。
 - `SKILL.md` 只放路由、决策、命令行、响应路径、安全规则；长选项表、安装与密钥恢复放 `references/`，并写明何时读。
 - 默认 JSON 输出，文档写稳定的 `data.data.*` 路径（`outputResult` 会额外包一层 `{success, data}`）。
 - 用户请求执行即等同授权：不要每次预检安装或密钥；安装说明只在需要时读一次，修复后重试原命令一次。
@@ -127,6 +127,10 @@ platform 侧还有、CLI 未接 10 个：`wx_rss_reader`、`flow_wx_history_arti
 - **`wx_history_articles` 的上游失败藏在 `data.code`**：平台侧仍回 `success:true`，只有 `data.code` 非 0 才是失败（实测 `107` = 名称/链接对不上，`20001` = 平台侧上游故障），`src/api.js` 的 `throwOnWxHistoryFailure` 把它转成 `api_error`（退出码 1）。别用「数组为空」推断「这个号没发文」。
 - **抖音字段单位不统一**：`video-search` 的 `video.duration` 是**毫秒**，`user-videos` 的 `duration` 是 `"MM:SS"` 字符串——同名不同单位，跨端点复用代码必翻车。
 - **抖音时间戳是北京时间编码**：`create_time` 按 UTC 渲染出来就是北京时间，**不要再 +8 小时**（2026-10-28 实测 `video-search`/`video-comments`/`user-videos` 三处：+8 会让半小时前发的视频落到 7 小时后）。`user-videos` 另带 `create_time_formatted`，同口径。
+- **小红书时间戳正好相反**：`note_info.time`（秒）与 `user_notes/country` 的 `time`（毫秒）都是**真 UTC epoch**，展示必须 **+8**（2026-11-05 实测：同一视频笔记 `note_info.time`+8h 等于 `search` 返回的 `notePublishTime` 字符串）。上游 `time_desc` 的 `MM-DD` 是 **UTC-8 口径**（10-29 04:50 UTC 的笔记显示 `10-28`），只能用 `time +8` 自算。
+- **小红书端点取名与上游是错位的**：`xhs_user_notes_v2` 走 TikHub（可用、20 条/页），`xhs_user_notes_v3` 原本走 YDDM 且长期返回 `code 5003`（已于 2026-11-05 迁到同一 TikHub 上游）。CLI 选定 `xhs_user_notes_v2`；换端点要同步改测试与 `api_docs`。
+- **小红书 `share_text` 不能透传中文口令**：平台侧是原样转发上游的，带「复制内容，然后进入【小红书】…」的分享文案直接空结果（实测）。所以 `resolveNoteId` 先本地抽 URL、再跟 302 展开 `xhslink.cn` 短链。
+- **小红书同名不同结构**：`interact_info.*_count`、`like_count`、`sub_comment_count` 都是**字符串**；评论的 `user` 用 `userid`/`images`/`original_name`，笔记的 `user` 用 `user_id`/`avatar`/`nickname`。`noteInfo.readNum` 与 `userInfo.fansNum` 实测**恒为 0**，不要当真实阅读量/粉丝数承诺。
 - **密钥解析**：`-k` > `AICONDUCTOR_API_KEY` > **当前工作目录**的 `.env`（不向上查找）；缺失时 `resolveKeyOrExit` 打印错误并退出 1。
 
 ## 禁区
@@ -150,7 +154,7 @@ platform 侧还有、CLI 未接 10 个：`wx_rss_reader`、`flow_wx_history_arti
 
 ## 最短验证闭环
 
-`npm test`（27 个用例，离线打桩，不需要 API Key）。改动涉及 `bin/`、`README.md`、skill 文字或新增命令时，再补一条人工核对：`node bin/aiconductor-cli.js <组> <子命令> --help`——`bin/` 的接线没有自动化测试覆盖。
+`npm test`（40 个用例，离线打桩，不需要 API Key）。改动涉及 `bin/`、`README.md`、skill 文字或新增命令时，再补一条人工核对：`node bin/aiconductor-cli.js <组> <子命令> --help`——`bin/` 的接线没有自动化测试覆盖。
 
 ## 任务执行与报告约定
 

package/README.md

@@ -315,6 +315,70 @@ aiconductor-cli xhs hot-list [选项]
 aiconductor-cli xhs hot-list -f text
 ```
 
+#### 笔记详情 `xhs note`
+
+```bash
+aiconductor-cli xhs note <ref> [选项]
+```
+
+`ref` 支持笔记链接、`xhslink.cn`/`xhslink.com` 短链、完整分享口令，或 24 位 `note_id`。
+
+```bash
+aiconductor-cli xhs note "https://www.xiaohongshu.com/discovery/item/6ae972260000000015020d84" -f text
+aiconductor-cli xhs note "标题 https://xhslink.cn/o/85lbqBJtO94 复制内容，然后进入【小红书】查看相关笔记。"
+```
+
+#### 笔记评论 `xhs comments`
+
+```bash
+aiconductor-cli xhs comments <ref> [选项]
+```
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `--max-pages <n>` | 最大翻页数，范围 1~5 | 1 |
+| `--max-seconds <n>` | 最长运行时间（秒），上限 170 | 50 |
+
+返回一级评论，并带上上游可见的楼内回复（`sub_comments`）。`data.data.comments[]` 里 `like_count`、`sub_comment_count` 是**字符串**，评论的 `user` 对象用 `userid`/`original_name`（与笔记的 `user_id`/`nickname` 不同）。
+
+#### 笔记搜索 `xhs search`
+
+```bash
+aiconductor-cli xhs search <keyword> [选项]
+```
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `--sort <sort>` | `general` / `time_descending` / `popularity_descending` / `comment_descending` / `collect_descending` | 不限 |
+| `--note-time <range>` | `day` / `week` / `halfyear` | 不限 |
+| `--note-type <type>` | `video` / `note` | 不限 |
+| `--max-pages <n>` | 最大翻页数，范围 1~5 | 1 |
+
+示例：
+```bash
+aiconductor-cli xhs search "AI编程" --note-time week --sort popularity_descending --max-pages 2 -f text
+```
+
+结果在 `data.data.items[].noteInfo` 与 `.userInfo`。注意 `noteInfo.readNum` 与 `userInfo.fansNum` 实测恒为 0，不要当真实阅读量/粉丝数用。
+
+#### 用户详情 `xhs user` / 用户笔记 `xhs user-notes`
+
+```bash
+aiconductor-cli xhs user <ref> [选项]
+aiconductor-cli xhs user-notes <ref> [选项]      # 支持 --max-pages，范围 1~5
+```
+
+`ref` 支持主页链接 `/user/profile/<id>` 或 24 位 `user_id`。
+
+```bash
+aiconductor-cli xhs user "https://www.xiaohongshu.com/user/profile/53cd3bbbb4c4d64f93463018" -f text
+aiconductor-cli xhs user-notes 53cd3bbbb4c4d64f93463018 --max-pages 2 -f text
+```
+
+用户详情在 `user_info`（`basic_info` + 5 项中文 `interactions` + `tags`）；用户笔记在 `data.data.notes[]`。
+
+> 时间口径：小红书所有 `time` 都是 **UTC 时间戳**（笔记详情为秒、用户笔记为毫秒），`-f text` 已自动换算成北京时间；**不要**再额外加 8 小时。上游的 `time_desc`（如 `10-28`）是 UTC-8 口径，文本模式不使用它。
+
 ### 小红书扫码发布
 
 生成图文或视频笔记的 H5 发布页与二维码。素材支持公网 URL、本地文件、Base64/data URL，以及包含 Base64 内容的文本文件。
@@ -397,6 +461,11 @@ aiconductor-cli wx history "https://mp.weixin.qq.com/s?__biz=xxxx" -f text
 | 抖音视频搜索 | 0.15 元/页 |
 | 抖音链接转文字 | 0.01 元/次 + 0.0003 元/秒 |
 | 小红书热榜 | 以平台服务配置为准 |
+| 小红书笔记详情 | 以平台服务配置为准（按次） |
+| 小红书笔记评论 | 以平台服务配置为准（按成功翻页数） |
+| 小红书笔记搜索 | 以平台服务配置为准（按成功翻页数） |
+| 小红书用户详情 | 以平台服务配置为准（按次） |
+| 小红书用户笔记列表 | 以平台服务配置为准（按成功翻页数） |
 | 小红书扫码发布 | 0.05 元/次 |
 | 公众号文章互动数据 | 以平台服务配置为准（按次） |
 | 公众号历史文章列表 | 以平台服务配置为准（按成功翻页数） |

package/bin/aiconductor-cli.js

@@ -18,7 +18,15 @@ const {
   videoSearchCommand,
   linkToTextCommand,
 } = require("../src/commands/douyin");
-const { hotListCommand: xhsHotListCommand, notePublishCommand } = require("../src/commands/xhs");
+const {
+  hotListCommand: xhsHotListCommand,
+  notePublishCommand,
+  noteCommand: xhsNoteCommand,
+  commentsCommand: xhsCommentsCommand,
+  searchCommand: xhsSearchCommand,
+  userCommand: xhsUserCommand,
+  userNotesCommand: xhsUserNotesCommand,
+} = require("../src/commands/xhs");
 const {
   articleDataCommand: wxArticleDataCommand,
   historyCommand: wxHistoryCommand,
@@ -257,6 +265,53 @@ xhsCmd
   .option("-f, --format <format>", "输出格式：json 或 text", "json")
   .action((type, options) => { notePublishCommand(type, options); });
 
+xhsCmd
+  .command("note")
+  .description("获取小红书笔记详情（按次计费）")
+  .argument("<ref>", "笔记链接、xhslink 短链、分享口令或 24 位 note_id")
+  .option("-k, --api-key <key>", "AIConductor API Key")
+  .option("-f, --format <format>", "输出格式：json 或 text", "json")
+  .action((ref, options) => { xhsNoteCommand(ref, options); });
+
+xhsCmd
+  .command("comments")
+  .description("获取小红书笔记评论，含可见的楼内回复（按成功翻页计费）")
+  .argument("<ref>", "笔记链接、xhslink 短链、分享口令或 24 位 note_id")
+  .option("-k, --api-key <key>", "AIConductor API Key")
+  .option("--max-pages <n>", "最大翻页数，范围 1~5（每页约 10 条）", "1")
+  .option("--max-seconds <n>", "最长运行时间（秒），最大 170", "50")
+  .option("-f, --format <format>", "输出格式：json 或 text", "json")
+  .action((ref, options) => { xhsCommentsCommand(ref, options); });
+
+xhsCmd
+  .command("search")
+  .description("按关键词搜索小红书笔记（按成功翻页计费，每页约 20 条）")
+  .argument("<keyword>", "搜索关键词")
+  .option("-k, --api-key <key>", "AIConductor API Key")
+  .option("--sort <sort>", "排序：general/time_descending/popularity_descending/comment_descending/collect_descending")
+  .option("--note-time <range>", "发布时间：day/week/halfyear（不传=不限）")
+  .option("--note-type <type>", "笔记类型：video/note（不传=不限）")
+  .option("--max-pages <n>", "最大翻页数，范围 1~5", "1")
+  .option("-f, --format <format>", "输出格式：json 或 text", "json")
+  .action((keyword, options) => { xhsSearchCommand(keyword, options); });
+
+xhsCmd
+  .command("user")
+  .description("获取小红书用户详情（按次计费）")
+  .argument("<ref>", "主页链接 /user/profile/ 或 24 位 user_id")
+  .option("-k, --api-key <key>", "AIConductor API Key")
+  .option("-f, --format <format>", "输出格式：json 或 text", "json")
+  .action((ref, options) => { xhsUserCommand(ref, options); });
+
+xhsCmd
+  .command("user-notes")
+  .description("获取小红书用户笔记列表（按成功翻页计费，每页约 20 条）")
+  .argument("<ref>", "主页链接 /user/profile/ 或 24 位 user_id")
+  .option("-k, --api-key <key>", "AIConductor API Key")
+  .option("--max-pages <n>", "最大翻页数，范围 1~5", "1")
+  .option("-f, --format <format>", "输出格式：json 或 text", "json")
+  .action((ref, options) => { xhsUserNotesCommand(ref, options); });
+
 // wx 子命令组（公众号数据）
 const wxCmd = program
   .command("wx")

package/package.json

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

package/src/api.js

@@ -19,6 +19,25 @@ const DOUYIN_USER_SEARCH_PATH = "/api/douyin_user_search";
 const DOUYIN_VIDEO_SEARCH_PATH = "/api/douyin_video_search";
 const DOUYIN_LINK_TO_TEXT_PATH = "/api/douyin_link_to_text_v2";
 const XHS_NOTE_PUBLISH_PATH = "/api/xhs_note_publish";
+const XHS_NOTE_INFO_PATH = "/api/xhs_note_info_v3";
+const XHS_NOTE_COMMENTS_PATH = "/api/xhs_note_comments_fast";
+const XHS_NOTE_SEARCH_PATH = "/api/xhs_note_search_v3";
+const XHS_USER_INFO_PATH = "/api/xhs_user_info_v2";
+// 刻意打 v2：v3 已于 2026-11-05 迁到同一上游且同输出，但 v2 是历史真实流量所在（api_docs 两篇一致）。
+const XHS_USER_NOTES_PATH = "/api/xhs_user_notes_v2";
+
+// 本地校验区间，命中就在发请求前拦截，不产生计费
+const XHS_MAX_PAGES_LIMIT = 5;
+const XHS_MAX_SECONDS_LIMIT = 170;
+const XHS_SEARCH_SORTS = [
+  "general",
+  "time_descending",
+  "popularity_descending",
+  "comment_descending",
+  "collect_descending",
+];
+const XHS_SEARCH_NOTE_TIMES = ["day", "week", "halfyear"];
+const XHS_SEARCH_NOTE_TYPES = ["video", "note"];
 const WX_ARTICLE_DATA_PATH = "/api/wx_article_data";
 const WX_HISTORY_ARTICLES_PATH = "/api/wx_history_articles";
 const R2_UPLOADER_PATH = "/api/r2_uploader";
@@ -677,6 +696,208 @@ async function xhsNotePublish(apiKey, params) {
   return stripBilling(resp);
 }
 
+/**
+ * 抛 api_error（上层按业务失败处理）
+ * @param {object} result
+ * @returns {object}
+ */
+function throwOnXhsFailure(result) {
+  if (result?.success === false) {
+    throw Object.assign(new Error(result.message || "小红书接口返回失败"), { type: "api_error" });
+  }
+  return result;
+}
+
+/**
+ * 校验 1~上限 的正整数（上限单独校验，避免与其他命令的 limit 语义混住）
+ * @param {*} value
+ * @param {string} name
+ * @param {number} max
+ * @returns {number|null}
+ */
+function validateXhsPositiveInt(value, name, max) {
+  if (value === undefined || value === null || value === "") return null;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1 || n > max) {
+    throw Object.assign(new Error(`${name} 须为 1~${max} 的整数，收到: ${value}`), {
+      type: "validation_error",
+    });
+  }
+  return n;
+}
+
+/**
+ * 获取小红书笔记详情。
+ * 注意：只传 note_id 即可（2026-11-05 实测，不需要 xsec_token）。
+ * @param {string} apiKey
+ * @param {string} noteId
+ * @returns {Promise<object>} `note_data` 在顶层，没有 data.data 嵌套
+ */
+async function xhsNoteInfo(apiKey, noteId) {
+  const resp = await httpPost(API_HOST, XHS_NOTE_INFO_PATH, { note_id: noteId }, {
+    Authorization: `Bearer ${apiKey}`,
+  }, http);
+  return throwOnXhsFailure(stripBilling(resp));
+}
+
+/**
+ * 获取小红书笔记一级评论（含可见的楼内回复 sub_comments）。
+ * @param {string} apiKey
+ * @param {{noteId?: string, shareText?: string, maxPages?: number, maxSeconds?: number}} params
+ * @returns {Promise<object>} `data.data.comments`，10 条/页
+ */
+async function xhsNoteComments(apiKey, params = {}) {
+  const body = {};
+  const maxPages = validateXhsPositiveInt(params.maxPages, "max_pages", XHS_MAX_PAGES_LIMIT);
+  const maxSeconds = validateXhsPositiveInt(params.maxSeconds, "max_seconds", XHS_MAX_SECONDS_LIMIT);
+  if (maxPages !== null) body.max_pages = maxPages;
+  if (maxSeconds !== null) body.max_seconds = maxSeconds;
+
+  if (params.noteId) {
+    body.note_id = params.noteId;
+  } else if (params.shareText) {
+    body.share_text = params.shareText;
+  } else {
+    throw Object.assign(new Error("note_id 与分享链接至少提供一个"), { type: "validation_error" });
+  }
+
+  const resp = await httpPost(API_HOST, XHS_NOTE_COMMENTS_PATH, body, {
+    Authorization: `Bearer ${apiKey}`,
+  }, http);
+  return throwOnXhsFailure(stripBilling(resp));
+}
+
+/**
+ * 按关键词搜索小红书笔记。
+ * @param {string} apiKey
+ * @param {{keyword: string, maxPages?: number, sort?: string, noteTime?: string, noteType?: string}} params
+ * @returns {Promise<object>} `data.data.items[]`，20 条/页
+ */
+async function xhsNoteSearch(apiKey, params = {}) {
+  const keyword = typeof params.keyword === "string" ? params.keyword.trim() : "";
+  if (!keyword) {
+    throw Object.assign(new Error("keyword 不能为空"), { type: "validation_error" });
+  }
+
+  const body = { keyword };
+  const maxPages = validateXhsPositiveInt(params.maxPages, "max_pages", XHS_MAX_PAGES_LIMIT);
+  if (maxPages !== null) body.max_pages = maxPages;
+
+  if (params.sort) {
+    if (!XHS_SEARCH_SORTS.includes(params.sort)) {
+      throw Object.assign(new Error(`sort 仅支持 ${XHS_SEARCH_SORTS.join("|")}，收到: ${params.sort}`), {
+        type: "validation_error",
+      });
+    }
+    body.sort = params.sort;
+  }
+  if (params.noteTime) {
+    if (!XHS_SEARCH_NOTE_TIMES.includes(params.noteTime)) {
+      throw Object.assign(new Error(`note_time 仅支持 ${XHS_SEARCH_NOTE_TIMES.join("|")}，收到: ${params.noteTime}`), {
+        type: "validation_error",
+      });
+    }
+    body.note_time = params.noteTime;
+  }
+  if (params.noteType) {
+    if (!XHS_SEARCH_NOTE_TYPES.includes(params.noteType)) {
+      throw Object.assign(new Error(`note_type 仅支持 ${XHS_SEARCH_NOTE_TYPES.join("|")}，收到: ${params.noteType}`), {
+        type: "validation_error",
+      });
+    }
+    body.note_type = params.noteType;
+  }
+
+  const resp = await httpPost(API_HOST, XHS_NOTE_SEARCH_PATH, body, {
+    Authorization: `Bearer ${apiKey}`,
+  }, http);
+  return throwOnXhsFailure(stripBilling(resp));
+}
+
+/**
+ * 获取小红书用户详情。
+ * @param {string} apiKey
+ * @param {string} userId
+ * @returns {Promise<object>} `user_info` 在顶层，interactions 为 5 项中文
+ */
+async function xhsUserInfo(apiKey, userId) {
+  const resp = await httpPost(API_HOST, XHS_USER_INFO_PATH, { user_id: userId }, {
+    Authorization: `Bearer ${apiKey}`,
+  }, http);
+  return throwOnXhsFailure(stripBilling(resp));
+}
+
+/**
+ * 获取小红书用户笔记列表。
+ * @param {string} apiKey
+ * @param {{userId: string, maxPages?: number}} params
+ * @returns {Promise<object>} `data.data.notes[]`，20 条/页
+ */
+async function xhsUserNotes(apiKey, params = {}) {
+  if (!params.userId) {
+    throw Object.assign(new Error("user_id 不能为空"), { type: "validation_error" });
+  }
+  const body = { user_id: params.userId };
+  const maxPages = validateXhsPositiveInt(params.maxPages, "max_pages", XHS_MAX_PAGES_LIMIT);
+  if (maxPages !== null) body.max_pages = maxPages;
+
+  const resp = await httpPost(API_HOST, XHS_USER_NOTES_PATH, body, {
+    Authorization: `Bearer ${apiKey}`,
+  }, http);
+  return throwOnXhsFailure(stripBilling(resp));
+}
+
+/**
+ * 展开小红书分享短链（xhslink.cn / xhslink.com）为真实长链。
+ * 短链必须跟随 302，否则拿不到 note_id。
+ * @param {string} shortUrl
+ * @returns {Promise<string>} 长链；不是跳转时原样返回
+ */
+function resolveXhsShortLink(shortUrl) {
+  return new Promise((resolve, reject) => {
+    let parsed;
+    try {
+      parsed = new URL(shortUrl);
+    } catch {
+      reject(Object.assign(new Error(`短链格式无效: ${shortUrl}`), { type: "validation_error" }));
+      return;
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+      reject(Object.assign(new Error(`短链仅支持 HTTP/HTTPS: ${shortUrl}`), { type: "validation_error" }));
+      return;
+    }
+
+    const transport = parsed.protocol === "https:" ? https : http;
+    const req = transport.request({
+      hostname: parsed.hostname,
+      port: parsed.port || (parsed.protocol === "https:" ? 443 : 80),
+      path: `${parsed.pathname}${parsed.search}`,
+      method: "GET",
+      headers: {
+        "User-Agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1",
+      },
+    }, (res) => {
+      const location = res.headers?.location;
+      if (res.statusCode >= 300 && res.statusCode < 400 && location) {
+        if (res.resume) res.resume();
+        resolve(location);
+        return;
+      }
+      if (res.resume) res.resume();
+      resolve(shortUrl);
+    });
+
+    req.setTimeout(15000, () => {
+      req.destroy();
+      reject(Object.assign(new Error(`短链解析超时: ${shortUrl}`), { type: "network_error" }));
+    });
+    req.on("error", (err) => {
+      reject(Object.assign(new Error(`短链解析失败: ${err.message}`), { type: "network_error" }));
+    });
+    req.end();
+  });
+}
+
 module.exports = {
   resolveApiKey,
   publishHtml,
@@ -695,6 +916,12 @@ module.exports = {
   douyinLinkToText,
   r2Upload,
   xhsNotePublish,
+  xhsNoteInfo,
+  xhsNoteComments,
+  xhsNoteSearch,
+  xhsUserInfo,
+  xhsUserNotes,
+  resolveXhsShortLink,
   wxArticleData,
   wxHistoryArticles,
 };

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,
@@ -513,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,
+};

package/src/lib/cli-utils.js

@@ -81,4 +81,92 @@ function safeParseInt(value, defaultValue) {
   return Number.isNaN(n) ? defaultValue : n;
 }
 
-module.exports = { outputResult, outputError, resolveKeyOrExit, handleApiError, safeParseInt };
+/**
+ * 从文本（分享口令/带链接的句子）中抽出第一个 http(s) 链接。
+ *
+ * 小红书用户复制的内容形如「标题 https://xhslink.cn/o/xxx 复制内容，然后进入【小红书】查看相关笔记。」
+ * 平台侧的 share_text 是**原样透传上游**的，带中文口令必失败（2026-11-05 实测），所以链接必须本地抽。
+ * @param {string} text
+ * @returns {string|null}
+ */
+function extractUrlFromText(text) {
+  if (typeof text !== "string") return null;
+  const match = text.match(/https?:\/\/[^\s\u4e00-\u9fa5，。、；：！？（）【】《》“”‘’]+/i);
+  if (!match) return null;
+  // 去掉 URL 尾部的英文标点（中文标点已在字符集里排除）
+  return match[0].replace(/[),.;:!?'"\]}>]+$/, "");
+}
+
+const XHS_ID_RE = /^[0-9a-f]{24}$/i;
+
+/**
+ * 从用户输入里识别小红书笔记 ID（裸 ID / 长链 / 带链接的分享文案）。
+ * 短链（xhslink.cn）需先由 resolveXhsShortLink 换成长链。
+ * @param {string} text
+ * @returns {string|null}
+ */
+function parseXhsNoteId(text) {
+  if (typeof text !== "string") return null;
+  const raw = text.trim();
+  if (XHS_ID_RE.test(raw)) return raw;
+  const url = extractUrlFromText(raw);
+  if (!url) return null;
+  const match = url.match(/(?:explore|discovery\/item|note)\/([0-9a-f]{24})/i);
+  return match ? match[1] : null;
+}
+
+/**
+ * 从用户输入里识别小红书用户 ID（裸 ID / 主页链接）。
+ * @param {string} text
+ * @returns {string|null}
+ */
+function parseXhsUserId(text) {
+  if (typeof text !== "string") return null;
+  const raw = text.trim();
+  if (XHS_ID_RE.test(raw)) return raw;
+  const url = extractUrlFromText(raw);
+  if (!url) return null;
+  const match = url.match(/user\/profile\/([0-9a-f]{24})/i);
+  return match ? match[1] : null;
+}
+
+/**
+ * 小红书时间戳格式化：上游给的是**真 UTC epoch**（详情秒、笔记列表毫秒），展示需 +8 小时。
+ * 与抖音相反（抖音是「北京时间编码」，不要再加 8）。
+ * @param {number|string} value epoch 秒或毫秒
+ * @returns {string} `YYYY-MM-DD HH:mm:ss`，无效值返回空串
+ */
+function formatXhsTime(value) {
+  const n = Number(value);
+  if (!n || Number.isNaN(n)) return "";
+  const ms = n > 1e12 ? n : n * 1000;
+  return new Date(ms + 8 * 3600 * 1000).toISOString().replace("T", " ").slice(0, 19);
+}
+
+/**
+ * 归一化为整数计数：上游同一平台里数字有 int、字符串、以及「1.2万」这类糊糊写法。
+ * @param {*} value
+ * @returns {number}
+ */
+function toCount(value) {
+  if (typeof value === "number") return Number.isFinite(value) ? value : 0;
+  if (value === null || value === undefined) return 0;
+  const text = String(value).replace(/[,\s]/g, "");
+  const match = text.match(/^(\d+(?:\.\d+)?)(万|w)?\+?$/i);
+  if (!match) return 0;
+  const base = Number(match[1]);
+  return Math.round(match[2] ? base * 10000 : base);
+}
+
+module.exports = {
+  outputResult,
+  outputError,
+  resolveKeyOrExit,
+  handleApiError,
+  safeParseInt,
+  extractUrlFromText,
+  parseXhsNoteId,
+  parseXhsUserId,
+  formatXhsTime,
+  toCount,
+};