aiconductor-cli 1.5.0 → 1.6.0

package/AGENTS.md

@@ -2,7 +2,7 @@
 
 ## 项目概述
 
-`aiconductor-cli` 是 AIConductor 平台 API 的命令行封装：Node.js >= 18、CommonJS、唯一运行时依赖 `commander`，发布到 npm 供 agent 与终端用户直接调用。七组命令覆盖网页发布、豆包搜索、热点简报、抖音数据、小红书数据、公众号数据；`.codex/skills/` 存放面向 agent 的工作流，指导如何调用这些命令，其中对外发布的技能（`xhs-note-publish`、`douyin-script-extract`）还要满足 WorkBuddy 上架字段，见 `references/workbuddy技能规范.md`。`README.md` 是对外命令契约，本文档是开发与维护契约。
+`aiconductor-cli` 是 AIConductor 平台 API 的命令行封装：Node.js >= 18、CommonJS、唯一运行时依赖 `commander`，发布到 npm 供 agent 与终端用户直接调用。七组命令覆盖网页发布、豆包搜索、热点简报、抖音数据、小红书数据、公众号数据；`.agents/skills/` 存放面向 agent 的工作流（pi 在项目受信任时会自动发现项目级 `.agents/skills/`），指导如何调用这些命令，其中对外发布的技能（`xhs-note-publish`、`douyin-script-extract`）还要满足 WorkBuddy 上架字段，见 `references/workbuddy技能规范.md`。`README.md` 是对外命令契约，本文档是开发与维护契约。
 
 ## 项目结构与模块组织
 
@@ -21,7 +21,7 @@ src/commands/
 src/api.test.js          全部自动化测试（api 映射 + 纯格式化/聚合函数）
 api_docs/<endpoint>.md   每个平台接口的请求/响应/计费契约（`aiconductor-platform` 对应文件的整文件副本）
 references/              平台侧规范（workbuddy技能规范.md），不参与 CLI 运行；已 gitignore + npmignore，只在本机
-.codex/skills/<name>/    SKILL.md（路由与执行）+ references/（按条件加载）+ 可选 scripts/
+.agents/skills/<name>/   SKILL.md（路由与执行）+ references/（按条件加载）+ 可选 scripts/；仓库里唯一入库的 .agents 子目录
 ```
 
 推导规则：命令组名与文件名**不一一对应**（`webpage` → `md_publish.js`，`search` → `web_search.js`），找实现先看 `bin/aiconductor-cli.js` 的注册处。命令文件只做四件事：解析选项、调用 `src/api.js`、格式化输出、`process.exit`；共享逻辑进 `src/lib/cli-utils.js`，HTTP 与鉴权细节不允许出现在命令文件里。
@@ -43,7 +43,7 @@ references/              平台侧规范（workbuddy技能规范.md），不参
 | 新增/修改接口契约 | platform 侧插件与 `api_docs`，再覆盖到 `aiconductor-cli/api_docs/` |
 | CLI 接入 | `src/api.js`（端点常量 + `httpPost` + `stripBilling`）→ `src/commands/<组>.js` → `bin/aiconductor-cli.js` 注册 |
 | 测试 | `src/api.test.js`，请求字段抄 `api_docs`，不抄实现 |
-| 对外文档与技能 | `README.md`、`.codex/skills/*/SKILL.md` |
+| 对外文档与技能 | `README.md`、`.agents/skills/*/SKILL.md` |
 
 ### 鉴权与计费的两侧分工
 
@@ -68,10 +68,10 @@ platform 侧还有、CLI 未接 10 个：`wx_rss_reader`、`flow_wx_history_arti
 | 命令 | 用途 |
 |---|---|
 | `npm install` | 安装唯一依赖 `commander`（有 lock） |
-| `npm test` | `node --test`，25 个用例，离线打桩，不需要 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`，不含 `.codex/` 与 `references/`（平台侧规范只在本机，已从 `.npmignore`/`.gitignore` 排掉） |
+| `npm pack --dry-run` | 确认发布内容：含 `src/**`（含测试）、`api_docs/`、`AGENTS.md`，不含 `.agents/` 与 `references/`（平台侧规范只在本机，已从 `.npmignore`/`.gitignore` 排掉） |
 
 无构建步骤、无 lint/formatter、无 CI。
 
@@ -83,7 +83,7 @@ platform 侧还有、CLI 未接 10 个：`wx_rss_reader`、`flow_wx_history_arti
 2. 需要新端点时先读 `api_docs/<endpoint>.md`，在 `src/api.js` 加端点常量与函数，复用 `httpPost` + `stripBilling`。
 3. 在 `bin/aiconductor-cli.js` 注册子命令与选项——这是**唯一注册点**。`-k, --api-key`、`-f, --format` 每个命令各自声明，没有全局注入；可重复选项用 `collect`。
 4. 跑 `node bin/aiconductor-cli.js <组> <子命令> --help` 核对命令面，跑 `npm test`。
-5. 同步受影响产物：`README.md`（synopsis、选项表、示例）、对应的 `.codex/skills/*/SKILL.md`（命令、选项、`data.data.*` 路径）、`src/api.test.js`（改了请求映射或格式化时）。
+5. 同步受影响产物：`README.md`（synopsis、选项表、示例）、对应的 `.agents/skills/*/SKILL.md`（命令、选项、`data.data.*` 路径）、`src/api.test.js`（改了请求映射或格式化时）。
 
 ### 新增平台接口
 
@@ -94,11 +94,13 @@ platform 侧还有、CLI 未接 10 个：`wx_rss_reader`、`flow_wx_history_arti
 
 ### 维护 skill
 
-- 目录名、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）。
+- 技能放 `.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，小红书选题→xhs-topic-radar，小红书单篇拆解→xhs-note-insight，小红书账号→xhs-account-analyze，公众号发文列表→wx-account-articles，单篇公众号数据→wx-article-data）。
 - `SKILL.md` 只放路由、决策、命令行、响应路径、安全规则；长选项表、安装与密钥恢复放 `references/`，并写明何时读。
 - 默认 JSON 输出，文档写稳定的 `data.data.*` 路径（`outputResult` 会额外包一层 `{success, data}`）。
 - 用户请求执行即等同授权：不要每次预检安装或密钥；安装说明只在需要时读一次，修复后重试原命令一次。
-- 安装说明被复制成 9 份 `references/aiconductor-skills-setup.md`（技能是独立安装单元，无法跨目录引用）；改它必须同步 9 份。改完跑 `md5sum .codex/skills/*/references/aiconductor-skills-setup.md | awk '{print $1}' | sort -u | wc -l`，结果必须是 **1**。
+- 安装说明被复制成 11 份 `references/aiconductor-skills-setup.md`（技能是独立安装单元，无法跨目录引用）；改它必须同步 11 份。改完跑 `md5sum .agents/skills/*/references/aiconductor-skills-setup.md | awk '{print $1}' | sort -u | wc -l`，结果必须是 **1**。
 
 ### 上架到 WorkBuddy
 
@@ -122,8 +124,13 @@ platform 侧还有、CLI 未接 10 个：`wx_rss_reader`、`flow_wx_history_arti
 - **小红书发布是两段式**：本地文件或 Base64 先经 `r2Upload` 换成临时公开 URL（`valid_days` 仅 1 或 7，默认 7；图片单张 ≤ 32MB，本地视频 ≤ 100MB），再调用计费接口生成 H5 页与二维码。Base64 参数支持 `@文件路径`。
 - **热点简报是部分成功语义**：热榜与小红书热榜并行请求，任一成功即返回 `success:true`，失败写入 `data.failed_sources` / `data.failed_services`；仅两个服务都失败才退出 1。不要简化成"全有或全无"。
 - **`wx` 组线上真实字段**（2026-11-04 实测调用）：`wx_article_data` 返回 `read` / `zan` / `looking`（在看）/ `share_num` / `collect_num` / `comment_count`；`wx_history_articles` 用 `--name` 定位时业务层只有 `mp_nickname` 与 `mp_ghid`——**`api_docs` 写的 `mp_wxid` / `head_img` 实际不返回**；文章项字段与文档一致（`post_time_str` / `read` / `zan` / `original` / `url` / `digest`）。改 formatter 按实测字段，不要按文档新增字段。
+- **`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。
 
 ## 禁区
@@ -147,7 +154,7 @@ platform 侧还有、CLI 未接 10 个：`wx_rss_reader`、`flow_wx_history_arti
 
 ## 最短验证闭环
 
-`npm test`（25 个用例，离线打桩，不需要 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/` 的接线没有自动化测试覆盖。
 
 ## 任务执行与报告约定
 
@@ -172,7 +179,7 @@ platform 侧还有、CLI 未接 10 个：`wx_rss_reader`、`flow_wx_history_arti
 
 - 格式 `<tag>: <描述>`，tag 取自既有历史：`feat:`、`fix:`、`refactor:`、`docs:`、`skills:`、`search:`、`content:`、`release:`；agent 提交在前面加 `[Agent]`（如 `[Agent] release(cli): 1.4.0 —— ...`），描述可用中文。
 - 发版提交只改 `package.json` + `package-lock.json` 的版本号；发版前先跑 `npm test`。
-- 新增或修改 skill 必须随 `.codex/skills/**` 一起进 Git（`.npmignore` 已排除 `.codex/`，所以技能在仓库里版本化、不进 npm 包）。
+- 新增或修改 skill 必须随 `.agents/skills/**` 一起进 Git（`.npmignore` 已排除 `.agents/`，所以技能在仓库里版本化、不进 npm 包）。
 - 历史只有单作者、无 PR 记录，可直接在 `master` 提交；若走 PR，描述写清命令面/API 影响与验证命令，保持 diff 聚焦。
 
 ## 安全与配置

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 内容的文本文件。
@@ -374,6 +438,8 @@ aiconductor-cli wx history "https://mp.weixin.qq.com/s?__biz=xxxx" -f text
 
 返回路径：`article-data` 的互动数据在 `data.data`（`read` / `zan` / `looking` / `share_num` / `collect_num` / `comment_count`，text 模式渲染成阅读/点赞/在看/分享/收藏/评论，未知字段原样输出）；`history` 的文章在 `data.data.data[]`（标题 `title`、时间 `post_time_str`、阅读 `read`、点赞 `zan`、链接 `url`）。
 
+`history` 另带 `data.data.code`（上游返回码）：`0` 才表示成功；非 0（如 `107` 名称/链接对不上、`20001` 平台侧上游故障）时 CLI 以退出码 1 报 `api_error`，不会用空列表冒充成功。
+
 ### 通用选项
 
 所有命令支持：
@@ -395,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/api_docs/xhs_user_info_v2.md

@@ -5,7 +5,11 @@
 - **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
 
 ## 功能说明
-根据用户ID获取小红书用户详情，包括基本信息、互动数据（关注/粉丝/获赞与收藏）、标签等。按次计费。
+根据用户ID获取小红书用户详情，包括基本信息、互动数据（关注/粉丝/获赞与收藏/获赞/收藏）、标签等。按次计费。
+
+> **数据源变更（2026-11-05）**：上游由 YDDM `/xhs/user_detail`（实测 8.2s）切换为 TikHub `GET /api/v1/xiaohongshu/app_v2/get_user_info`（实测 2.3s），**入参与出参形状完全不变**：
+> `user_info.basic_info{nickname, avatar, red_id, gender, ip_location, desc}` + `user_info.interactions[5]{type, name, count}`（关注/粉丝/获赞与收藏/获赞/收藏）+ `user_info.tags[string]`。
+> 两个口径差异需知悉：① `ip_location` 统一给**中文省份**（优先取资料地区省份，回落英文 IP 归属地，如 `福建`）；② `获赞与收藏` 取上游自带的合计值，缺失时用 `获赞 + 收藏` 兜底。
 
 ## 请求参数
 

package/api_docs/xhs_user_notes_v3.md

@@ -7,6 +7,8 @@
 ## 功能说明
 根据用户 ID 获取小红书用户笔记列表，支持自动翻页（cursor 机制），兼容图文与视频笔记，按页计费。费用以 api_services 表配置为准（service_code: `xhs_user_notes_v2`）。
 
+> **数据源变更（2026-11-05）**：上游由 YDDM `/xhs/user_post2`（持续返回 `code 5003 网络连接失败`，接口表现为 `success:true` + 空 `notes`）切换为 TikHub `GET /api/v1/xiaohongshu/app_v2/get_user_posted_notes`（实测 20 条/页、1.9s）。**入参与出参形状完全不变**，与 `xhs_user_notes_v2` 同一上游、同一输出结构（差别只在 `desc` 等字段的原始内容）。
+
 ## 请求参数
 
 | 参数名 | 类型 | 必填 | 默认值 | 说明 |

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.0",
+  "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";
@@ -176,6 +195,22 @@ function throwOnBusinessFailure(resp) {
   return resp;
 }
 
+/**
+ * wx_history_articles 把上游失败塞在 HTTP 200 + success:true 的 data.code 里
+ * （api_docs：data.code 为 0 才算成功，平台侧并不改写成 success:false）。
+ * 不认这个码，就会把「上游挂了」当成「这个号没有文章」。
+ * @param {object} resp
+ * @returns {object}
+ */
+function throwOnWxHistoryFailure(resp) {
+  const inner = resp && resp.data;
+  if (inner && typeof inner.code === "number" && inner.code !== 0) {
+    const detail = resp.message || inner.msg || "上游返回失败";
+    throw Object.assign(new Error(`${detail}（上游错误码 ${inner.code}）`), { type: "api_error" });
+  }
+  return resp;
+}
+
 function contentTypeForFilename(filename) {
   const types = {
     ".avif": "image/avif",
@@ -638,7 +673,7 @@ async function wxHistoryArticles(apiKey, params = {}) {
   const resp = await httpPost(API_HOST, WX_HISTORY_ARTICLES_PATH, body, {
     Authorization: `Bearer ${apiKey}`,
   });
-  return throwOnBusinessFailure(stripBilling(resp));
+  return throwOnWxHistoryFailure(throwOnBusinessFailure(stripBilling(resp)));
 }
 
 /**
@@ -661,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,
@@ -679,6 +916,12 @@ module.exports = {
   douyinLinkToText,
   r2Upload,
   xhsNotePublish,
+  xhsNoteInfo,
+  xhsNoteComments,
+  xhsNoteSearch,
+  xhsUserInfo,
+  xhsUserNotes,
+  resolveXhsShortLink,
   wxArticleData,
   wxHistoryArticles,
 };