aiconductor-cli 1.3.4 → 1.4.0

package/api_docs/wx_md_to_html.md

@@ -0,0 +1,48 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/wx_md_to_html`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+将 Markdown 文本转换为微信公众号兼容的 HTML（遵循 V2.0 样式规范：基于 Section、Flex 列表、内联样式）。仅做 API 密钥校验，**不扣费**。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| md_text | string | 是 | - | 待转换的 Markdown 文本内容 |
+| primary_color | string | 否 | `#07c160` | 主题色（标题、列表标记、链接、加粗等用色，微信绿） |
+| text_color | string | 否 | `#333333` | 正文文字颜色 |
+| secondary_color | string | 否 | `#888888` | 次要文本颜色 |
+| font_size | int | 否 | `16` | 正文字号（px） |
+| line_height | float | 否 | `1.75` | 行高 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息（成功示例：「转换成功」；空内容示例：「转换成功（空内容）」） |
+| html | string | 转换后的微信公众号 HTML 字符串（失败为空字符串） |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/wx_md_to_html" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "md_text": "# 标题\n\n这是一段正文，支持 **加粗**、[链接](https://example.com) 与列表：\n\n- 项目一\n- 项目二",
+    "primary_color": "#07c160",
+    "text_color": "#333333"
+  }'
+```
+
+## 注意事项
+1. 本接口**不扣费**，仅验证 API 密钥。
+2. 当 `md_text` 为空时仍返回 `success=true` 且 `html` 为空字符串（视为空内容转换成功）。
+3. 转换支持标题、段落、有序/无序列表（转为 Flex Section）、引用、代码块、内联代码、图片、表格、加粗、链接等常见 Markdown 元素。
+4. 输出为带内联样式的 HTML 片段，可直接粘贴至公众号编辑器。

package/api_docs/wx_rss_reader.md

@@ -0,0 +1,59 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/wx_rss_reader`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+批量读取微信公众号的 RSS 订阅文章（支持多公众号并发）。为**计费插件**：按公众号数量计费（单价 × 公众号个数），费用以 `api_services` 表（`service_code=wechat_rss_reader`）配置为准。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| wx_names | string | 是 | - | 公众号名称，多个用英文逗号隔开，如 `公众号A,公众号B` |
+| recent_days | int | 否 | `3` | 获取最近几天内的文章 |
+| max_items | int | 否 | `5` | 每个公众号最多返回几篇 |
+| use_json_mode | bool | 否 | `false` | 是否启用 JSON 文件模式：为 `true` 时结果打包上传 OSS 并返回 `data_url`，`data` 为 null |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功（整体任务是否提交完成） |
+| message | string | 响应消息，如「批量处理完成: 成功 X 个，失败 Y 个」 |
+| billing | object | 计费信息，含以下子字段 |
+| billing.service_code | string | 服务代码 `wechat_rss_reader` |
+| billing.unit_fee | float | 单个公众号的单价 |
+| billing.total_fee | float | 总费用 = 单价 × 公众号数量 |
+| billing.count | int | 本次请求的公众号数量 |
+| billing.transaction_id | int | 交易流水 ID |
+| data_url | string | JSON 模式下的 OSS 结果文件链接（`use_json_mode=false` 时为 null） |
+| data | array | 非 JSON 模式下的解析结果列表（`use_json_mode=true` 时为 null），每个元素含以下字段 |
+| data[].wx_name | string | 公众号名称 |
+| data[].success | boolean | 该公众号是否解析成功 |
+| data[].message | string | 该公众号的解析说明 |
+| data[].data | object | 该公众号的 RSS 解析结果（结构取决于 RSS 解析服务返回） |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/wx_rss_reader" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "wx_names": "人民日报,央视新闻",
+    "recent_days": 3,
+    "max_items": 5,
+    "use_json_mode": false
+  }'
+```
+
+## 注意事项
+1. 本接口**计费**，按公众号数量（×单价）一次性扣费；余额不足时不扣费并返回失败。
+2. API 密钥无效或账户被禁用时不扣费。
+3. 公众号需已在后台 `wechat_rss_feeds` 表中配置对应 RSS 链接，未配置或查询不到则返回该公众号 `success=false`。
+4. 多公众号并发上限为 5；单公众号 RSS 解析调用最多重试 3 次，单次请求整体超时 60 秒。
+5. `use_json_mode=true` 时结果以 JSON 文件形式上传至 OSS（`temporary_90` 目录）并返回 `data_url`，便于批量数据落地。

package/api_docs/xhs_hot_list.md

@@ -0,0 +1,48 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/xhs_hot_list`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+获取小红书实时热榜（热门话题/关键词榜单），返回名次、标题、链接、热度值及趋势。按次计费，费用以 api_services 表配置为准（service_code: `xhs_hot_list`）。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| 无业务参数 | — | — | — | 仅需有效的 api_key 鉴权，无需其他业务参数 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| billing | object | 计费信息（service_fee / discount_applied / balance_before / balance_after / currency / transaction_id） |
+| data.date | string | 热榜日期 |
+| data.items | array[object] | 热榜条目列表（见下） |
+
+`data.items[]` 字段：`rank`(int)、`title`(string)、`url`(string)、`item_id`(string)、`hot`(string)、`hot_value`(int)、`trend`(string)。
+
+## 请求示例
+
+```bash
+curl -X GET "http://plugin.aiconductor.fun/api/xhs_hot_list" \
+  -H "Authorization: Bearer your_api_key"
+```
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/xhs_hot_list" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+## 注意事项
+1. 接口无业务参数，仅需有效的 api_key；余额不足、密钥无效或账户禁用均不扣费。
+2. 上游返回业务错误或热榜为空时返回失败且不扣费。
+3. 采用后扣费模式：仅成功取到热榜数据后才扣费，网络/上游异常不扣费。
+4. 上游单页请求超时 55s。

package/api_docs/xhs_note_comments_fast.md

@@ -0,0 +1,54 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/xhs_note_comments_fast`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+根据笔记 ID 或分享链接获取小红书笔记的一级评论数据，支持自动翻页与时间控制，按页计费。费用以 api_services 表配置为准（service_code: `xhs_get_note_comment_fast`）。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| note_id | string | 否 | None | 笔记 ID（`share_text` 为空时必填） |
+| xsec_token | string | 否 | None | URL 或列表中的 xsec_token 值（`share_text` 为空时必填） |
+| share_text | string | 否 | None | web 端 URL 链接（`note_id` 为空时必填） |
+| max_pages | int | 否 | 1 | 最大翻页数 |
+| max_seconds | int | 否 | 50 | 最长运行时长（秒） |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+> `note_id`+`xsec_token` 与 `share_text` 两组参数至少提供一组。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| billing | object | 计费信息（service_fee / discount_applied / balance_before / balance_after / currency / pages_billed / total_service_fee / transaction_ids） |
+| data.code | int | 上游返回码 |
+| data.user_id | string | 笔记所属用户 ID |
+| data.comments | array[object] | 评论列表（已过滤 liked/show_tags/status/at_users 字段，含 sub_comments 子评论） |
+| data.cursor | string | 下一页翻页游标 |
+| data.has_more | boolean | 是否还有更多数据 |
+| data.time | int | 处理完成时间戳（毫秒） |
+| data.xsec_token | string | 笔记 xsec_token |
+| data.total_pages | int | 实际抓取页数 |
+| data.total_comments | int | 评论总数 |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/xhs_note_comments_fast" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{"note_id": "65dxxxx", "xsec_token": "xxx_token", "max_pages": 2}'
+```
+
+## 注意事项
+1. 按页计费：每成功抓取一页计费一次，余额不足、超时或上游无更多数据自动停止翻页。
+2. 采用后扣费模式：仅成功获取并解析后才扣费，失败不扣费。
+3. `note_id`+`xsec_token` 或 `share_text` 至少一组；上游 `code != 0` 时停止翻页。
+4. 评论数据已剔除内部字段（liked/show_tags/status/at_users），便于前端使用。
+5. 上游单页请求超时 55s。

package/api_docs/xhs_note_info_v2.md

@@ -0,0 +1,45 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/xhs_note_info_v2`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+小红书笔记信息提取插件 V2，支持从分享文本或直接链接中提取笔记标题、内容、图片和视频信息，集成 API 密钥验证与计费。按次计费，费用以 api_services 表配置为准（service_code: `get_xhs_note_info_v2`）。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| url | string | 是 | — | 网页地址或包含链接的分享文本 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| title | string | 笔记标题（已去除「 - 小红书」后缀） |
+| content | string | 笔记内容（meta description） |
+| image_urls | array[string] | 图片链接列表（og:image） |
+| video_url | string | 视频链接（og:video） |
+| video_duration | string | 视频时长（og:videotime） |
+| billing | object | 计费信息（service_fee / discount_applied / balance_before / balance_after / currency / transaction_id） |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/xhs_note_info_v2" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://www.xiaohongshu.com/explore/65dxxxx?xsec_token=xxx&xsec_source=pc_pgy"}'
+```
+
+## 注意事项
+1. 采用后扣费模式：仅在页面成功访问并提取到信息后才扣费；密钥无效、账户禁用、页面不可访问、解析异常等均不扣费。
+2. 输入支持直接链接，也支持粘贴分享文本，插件会自动从文本中提取链接（`remove_params=False` 保留参数）。
+3. 若链接为 `xhslink.com` 短链，会自动解析为原始长链接（超时 10s），解析失败则继续用原链接尝试。
+4. 标题自动去除末尾「 - 小红书」后缀；内容取自页面 `meta[name=description]`。
+5. 上游页面请求超时 55s，超時或网络异常时返回失败且不扣费。

package/api_docs/xhs_note_info_v3.md

@@ -0,0 +1,69 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/xhs_note_info_v3`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+根据笔记ID获取小红书笔记详情，包括标题、描述、用户信息、图片列表、互动数据、标签等。按次计费。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| note_id | string | 是 | | 笔记ID，从小红书链接 `/explore/` 后提取，如 `6915bf1300000000070380e4` |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| note_data | object | 笔记详情数据 |
+| note_data.note_id | string | 笔记ID |
+| note_data.type | string | 笔记类型（normal/video等） |
+| note_data.title | string | 笔记标题 |
+| note_data.desc | string | 笔记描述 |
+| note_data.time | integer | 发布时间（毫秒时间戳） |
+| note_data.video | string | 视频信息（图文笔记为空） |
+| note_data.user | object | 用户信息 |
+| note_data.user.user_id | string | 用户ID |
+| note_data.user.nickname | string | 用户昵称 |
+| note_data.user.avatar | string | 用户头像URL |
+| note_data.image_list | array | 图片列表 |
+| note_data.image_list[].url | string | 图片URL |
+| note_data.image_list[].width | integer | 图片宽度 |
+| note_data.image_list[].height | integer | 图片高度 |
+| note_data.image_list[].live_photo | boolean | 是否为Live Photo |
+| note_data.interact_info | object | 互动数据 |
+| note_data.interact_info.liked_count | string | 点赞数 |
+| note_data.interact_info.collected_count | string | 收藏数 |
+| note_data.interact_info.comment_count | string | 评论数 |
+| note_data.interact_info.share_count | string | 分享数 |
+| note_data.tag_list | array | 标签列表 |
+| note_data.tag_list[].id | string | 标签ID |
+| note_data.tag_list[].name | string | 标签名称 |
+| note_data.tag_list[].type | string | 标签类型 |
+| billing | object | 计费信息 |
+| billing.service_fee | float | 服务费 |
+| billing.discount_applied | boolean | 是否应用折扣 |
+| billing.balance_before | float | 扣费前余额 |
+| billing.balance_after | float | 扣费后余额 |
+| billing.currency | string | 货币类型（CNY） |
+| billing.transaction_id | string | 交易ID |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/xhs_note_info_v3" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{"note_id": "6915bf1300000000070380e4"}'
+```
+
+## 注意事项
+1. note_id 从小红书链接中提取，链接格式为 `https://www.xiaohongshu.com/explore/{note_id}`
+2. 笔记可能因被隐藏、删除或设置访问权限而无法获取，此时返回失败信息且不扣费
+3. 采用后扣费模式，仅笔记详情获取成功时才扣费

package/api_docs/xhs_note_publish.md

@@ -0,0 +1,54 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/xhs_note_publish`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+生成小红书扫码发布 H5 页面与二维码，支持图文/视频两种笔记类型，可选转存素材到 OSS。按次计费，费用以 api_services 表配置为准（service_code: `xhs_note_publish`（普通）/ `xhs_note_publish_pro`（含 OSS 转存））。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| type | string | 是 | — | 笔记类型：`normal`（图文）或 `video`（视频） |
+| title | string | 否 | "" | 标题，最多 20 字符（中文=1，英文/数字=0.5） |
+| content | string | 否 | "" | 正文，最多 1000 字符 |
+| images | array[string] | 否 | [] | 图片 URL 列表（`normal` 类型必填，最多 18 张，需公网 http(s)） |
+| video | string | 否 | "" | 视频 URL（`video` 类型必填，需公网 http(s)） |
+| cover | string | 否 | "" | 封面图 URL（`video` 类型可选，需公网 http(s)） |
+| transfer_to_oss | bool | 否 | false | 是否将素材转存到 OSS（视频上限 200MB，图片上限 32MB） |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| data.id | string | 笔记 ID |
+| data.url | string | 发布页 URL（上传至 OSS） |
+| data.qrcode | string | 发布页二维码（base64 data URL） |
+| data.transfer_to_oss | boolean | 是否转存了素材到 OSS |
+| data.media | object | 最终使用的素材（见下） |
+| data.media.images | array[string] | 图片地址（转存后为 OSS 地址） |
+| data.media.video | string | 视频地址（转存后为 OSS 地址） |
+| data.media.cover | string | 封面地址（转存后为 OSS 地址） |
+| billing | object | 计费信息（service_fee / discount_applied / balance_before / balance_after / currency / transaction_id） |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/xhs_note_publish" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{"type": "normal", "title": "周末探店", "content": "分享一家很棒的咖啡馆", "images": ["https://example.com/cover.jpg"]}'
+```
+
+## 注意事项
+1. 参数校验失败（`type` 非法、标题/正文超长、图文缺 images、视频缺 video、URL 非公网等）不扣费，返回 `billing` 余额均为 0。
+2. 图片/视频/封面 URL 必须是公网可访问的 http(s) 地址，并有 SSRF 防护（禁止内网、localhost 及非公网 IP）。
+3. 视频上限 200MB、图片上限 32MB，下载时最多 4 次重定向。
+4. 实际发布需在移动端小红书 APP 内完成；PC 端仅用于预览与扫码，调用方拿到 `url`/`qrcode` 后引导用户在手机打开。
+5. 采用后扣费模式：H5 页面生成并上传成功后才扣费，异常不扣费。

package/api_docs/xhs_note_search_v2.md

@@ -0,0 +1,73 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/xhs_note_search_v2`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+根据关键词搜索小红书笔记，支持自动翻页，使用 max_pages 和 max_seconds 控制翻页范围。按页计费，每页计费一次。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| keyword | string | 是 | | 搜索关键词 |
+| max_pages | integer | 否 | 1 | 最大翻页数 |
+| max_seconds | integer | 否 | 50 | 最长运行时长（秒），超时自动停止 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| data | object | 搜索结果数据 |
+| data.has_more | boolean | 是否还有更多数据 |
+| data.items | array | 笔记列表 |
+| data.items[].noteInfo | object | 笔记信息 |
+| data.items[].noteInfo.noteId | string | 笔记ID |
+| data.items[].noteInfo.title | string | 笔记标题 |
+| data.items[].noteInfo.noteType | integer | 笔记类型（1=图文，2=视频） |
+| data.items[].noteInfo.notePublishTime | string | 发布时间 |
+| data.items[].noteInfo.noteLink | string | 笔记链接 |
+| data.items[].noteInfo.likeNum | integer | 点赞数 |
+| data.items[].noteInfo.favNum | integer | 收藏数 |
+| data.items[].noteInfo.cmtNum | integer | 评论数 |
+| data.items[].noteInfo.readNum | integer | 浏览数 |
+| data.items[].noteInfo.videoUrl | string | 视频URL（图文笔记为空） |
+| data.items[].noteInfo.videoDuration | integer | 视频时长（秒） |
+| data.items[].noteInfo.noteImages | array | 图片列表 |
+| data.items[].noteInfo.noteImages[].imageUrl | string | 图片URL |
+| data.items[].noteInfo.noteImages[].imageWidth | integer | 图片宽度 |
+| data.items[].noteInfo.noteImages[].imageHeight | integer | 图片高度 |
+| data.items[].userInfo | object | 用户信息 |
+| data.items[].userInfo.nickName | string | 用户昵称 |
+| data.items[].userInfo.avatar | string | 用户头像URL |
+| data.items[].userInfo.userId | string | 用户ID |
+| data.items[].userInfo.fansNum | integer | 粉丝数 |
+| billing | object | 计费信息 |
+| billing.service_fee | float | 单页服务费 |
+| billing.discount_applied | boolean | 是否应用折扣 |
+| billing.balance_before | float | 扣费前余额 |
+| billing.balance_after | float | 扣费后余额 |
+| billing.currency | string | 货币类型（CNY） |
+| billing.pages_billed | integer | 实际计费页数 |
+| billing.total_service_fee | float | 总服务费 |
+| billing.transaction_ids | array | 交易ID列表 |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/xhs_note_search_v2" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{"keyword": "人民日报", "max_pages": 2, "max_seconds": 60}'
+```
+
+## 注意事项
+1. 按页计费，每成功获取一页数据扣费一次
+2. max_pages 控制最大翻页数，max_seconds 控制最长运行时间，两者任一达到限制即停止
+3. 余额不足时自动停止翻页，已获取的数据正常返回
+4. 采用后扣费模式，仅成功获取数据的页面才计费

package/api_docs/xhs_note_search_v3.md

@@ -0,0 +1,54 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/xhs_note_search_v3`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+小红书笔记搜索插件 V3，基于 TikHub API，支持关键词搜索与自动翻页（search_id 机制），按页计费。费用以 api_services 表配置为准（service_code: `xhs_note_search_v3`）。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| keyword | string | 是 | — | 搜索关键词 |
+| max_pages | int | 否 | 1 | 最大翻页数 |
+| max_seconds | int | 否 | 50 | 最长运行时长（秒） |
+| page | int | 否 | 1 | 起始页码 |
+| sort | string | 否 | "" | 排序方式：`general` / `time_descending` / `popularity_descending` / `comment_descending` / `collect_descending`（空=general） |
+| note_type | string | 否 | "" | 笔记类型：`video` / `note` / 空（不限） |
+| note_time | string | 否 | "" | 发布时间：`day` / `week` / `halfyear` / 空（不限） |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| billing | object | 计费信息（service_fee / discount_applied / balance_before / balance_after / currency / pages_billed / total_service_fee / transaction_ids） |
+| data.has_more | boolean | 是否还有更多数据 |
+| data.items | array[object] | 笔记列表 |
+| data.items[].noteInfo | object | 笔记信息（见下） |
+| data.items[].userInfo | object | 用户信息（见下） |
+
+`data.items[].noteInfo` 字段：`noteId`(string)、`title`(string)、`noteType`(string)、`notePublishTime`(string)、`noteLink`(string)、`likeNum`(int)、`favNum`(int)、`cmtNum`(int)、`readNum`(int)、`videoUrl`(string)、`videoDuration`(int)、`desc`(string)、`noteImages`(array[{imageUrl, imageWidth, imageHeight}])。
+
+`data.items[].userInfo` 字段：`nickName`(string)、`avatar`(string)、`userId`(string)、`fansNum`(int)。
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/xhs_note_search_v3" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{"keyword": "美食探店", "max_pages": 2, "note_type": "video", "sort": "popularity_descending"}'
+```
+
+## 注意事项
+1. 按页计费：每成功抓取一页计费一次，余额不足、超时或上游无更多数据会自动停止翻页。
+2. 采用后扣费模式：仅当某页成功获取并解析后才扣费，失败不扣费。
+3. 翻页由内部维护 `search_id` / `search_session_id`，调用方无需关心。
+4. 上游单页请求超时 55s，单次搜索最多重试 3 次。
+5. 上游返回业务错误或无数据时停止翻页，已抓取数据仍正常返回。

package/api_docs/xhs_user_info_v2.md

@@ -0,0 +1,57 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/xhs_user_info_v2`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+根据用户ID获取小红书用户详情，包括基本信息、互动数据（关注/粉丝/获赞与收藏）、标签等。按次计费。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| user_id | string | 是 | | 小红书用户ID，从用户主页链接 `/user/profile/` 后提取 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| user_info | object | 用户详情数据 |
+| user_info.basic_info | object | 基本信息 |
+| user_info.basic_info.nickname | string | 用户昵称 |
+| user_info.basic_info.avatar | string | 用户头像URL |
+| user_info.basic_info.red_id | string | 小红书号 |
+| user_info.basic_info.gender | integer | 性别（0=未知，1=男，2=女） |
+| user_info.basic_info.ip_location | string | IP归属地 |
+| user_info.basic_info.desc | string | 个人简介 |
+| user_info.interactions | array | 互动数据列表 |
+| user_info.interactions[].type | string | 互动类型（follows/fans/interaction） |
+| user_info.interactions[].name | string | 互动名称（关注/粉丝/获赞与收藏） |
+| user_info.interactions[].count | integer | 互动数量 |
+| user_info.tags | array | 标签列表 |
+| billing | object | 计费信息 |
+| billing.service_fee | float | 服务费 |
+| billing.discount_applied | boolean | 是否应用折扣 |
+| billing.balance_before | float | 扣费前余额 |
+| billing.balance_after | float | 扣费后余额 |
+| billing.currency | string | 货币类型（CNY） |
+| billing.transaction_id | string | 交易ID |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/xhs_user_info_v2" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{"user_id": "6229d4850000000021021d46"}'
+```
+
+## 注意事项
+1. user_id 从小红书用户主页链接中提取，格式为 `https://www.xiaohongshu.com/user/profile/{user_id}`
+2. 采用后扣费模式，仅用户详情获取成功时才扣费
+3. 用户可能设置隐私权限导致部分数据不可见，此时正常返回可见数据

package/api_docs/xhs_user_notes_v2.md

@@ -0,0 +1,56 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/xhs_user_notes_v2`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+根据用户ID获取小红书用户笔记列表，支持自动翻页，使用 max_pages 和 max_seconds 控制翻页范围。按页计费，每页计费一次。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| user_id | string | 是 | | 小红书用户ID，从用户主页链接 `/user/profile/` 后提取 |
+| max_pages | integer | 否 | 1 | 最大翻页数 |
+| max_seconds | integer | 否 | 50 | 最长运行时长（秒），超时自动停止 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| data | object | 笔记列表数据 |
+| data.notes | array | 笔记列表 |
+| data.notes[].noteId | string | 笔记ID |
+| data.notes[].title | string | 笔记标题 |
+| data.notes[].type | string | 笔记类型（video/normal） |
+| data.notes[].time | integer | 发布时间（毫秒时间戳） |
+| billing | object | 计费信息 |
+| billing.service_fee | float | 单页服务费 |
+| billing.discount_applied | boolean | 是否应用折扣 |
+| billing.balance_before | float | 扣费前余额 |
+| billing.balance_after | float | 扣费后余额 |
+| billing.currency | string | 货币类型（CNY） |
+| billing.pages_billed | integer | 实际计费页数 |
+| billing.total_service_fee | float | 总服务费 |
+| billing.transaction_ids | array | 交易ID列表 |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/xhs_user_notes_v2" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{"user_id": "5e7e31a20000000001004b48", "max_pages": 3, "max_seconds": 120}'
+```
+
+## 注意事项
+1. 按页计费，每成功获取一页数据扣费一次
+2. max_pages 控制最大翻页数，max_seconds 控制最长运行时间，两者任一达到限制即停止
+3. 余额不足时自动停止翻页，已获取的数据正常返回
+4. 采用后扣费模式，仅成功获取数据的页面才计费
+5. user_id 从小红书用户主页链接中提取，格式为 `https://www.xiaohongshu.com/user/profile/{user_id}`