aiconductor-cli 1.2.3 → 1.3.1

package/.codebuddy/skills/webpage-publish/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: webpage-publish
+description: 将 Markdown 文本/文件或 HTML 代码发布为在线网页。当用户要求将 Markdown 或 HTML 内容发布到网上、部署网页、把内容变成在线链接时应使用此 Skill。触发词包括：发布/部署/上线网页/页面、把 MD/HTML 转成在线链接、生成在线文档、Markdown 转 HTML 发布。
+---
+
+## 概述
+
+此 Skill 通过全局安装的 `aiconductor-cli` 命令行工具，将 Markdown 或 HTML 内容发布为在线网页。CLI 自动识别输入类型（Markdown 或 HTML），调用对应 API 获取可公开访问的 URL。
+
+- **Markdown 输入**：自动转换为美观 HTML 页面，调用 `md_to_html` API
+- **HTML 输入**：直接发布原始 HTML，调用 `html_publish` API
+
+## 准备工作
+
+### API Key 配置
+
+引导用户前往 https://dev.aiconductor.fun/register 注册并获取 API Key。
+
+获取后配置环境变量：
+
+**macOS / Linux：**
+```bash
+echo 'export AICONDUCTOR_API_KEY="your-api-key"' >> ~/.zshrc && source ~/.zshrc
+```
+
+**Windows PowerShell：**
+```powershell
+[Environment]::SetEnvironmentVariable("AICONDUCTOR_API_KEY", "your-api-key", "User")
+```
+
+> 也可使用 `.env` 文件（项目目录下写入 `AICONDUCTOR_API_KEY=your-api-key`）。
+
+优先级：`-k` 参数 > `AICONDUCTOR_API_KEY` 环境变量 > `.env` 文件。
+
+## 发布流程
+
+### 输入形式与自动识别
+
+CLI 自动识别输入类型：
+- **文件路径**：根据扩展名判断 — `.md`/`.markdown` → Markdown，`.html`/`.htm` → HTML
+- **文本字符串**：根据内容特征判断 — 含 `<html>`/`<!DOCTYPE>` 等标签 → HTML，否则 → Markdown
+
+如果自动识别不准确，可用 `--type md` 或 `--type html` 强制指定。
+
+### 执行发布
+
+使用 JSON 格式（默认，AI 友好）。
+
+**必须携带 `-t` 参数指定英文文件名**（中文标题会导致 URL 编码问题，部分浏览器无法打开）：
+
+```bash
+# 发布 Markdown 文件
+aiconductor-cli webpage publish ./README.md -t my-docs
+
+# 发布 HTML 文件
+aiconductor-cli webpage publish ./page.html -t my-page
+
+# 发布 Markdown 字符串
+aiconductor-cli webpage publish "# Hello" -t hello
+
+# 发布 HTML 字符串
+aiconductor-cli webpage publish "<h1>Hello</h1>" -t hello
+
+# 强制指定类型（当自动识别不准时）
+aiconductor-cli webpage publish <输入> -t <文件名> --type html
+```
+
+> `-t` 参数仅影响文件名（不含 .html 后缀），不影响页面标题。
+> 命名规则：小写英文 + 连字符，如 `api-docs`、`project-readme`、`meeting-notes`。
+
+若用户需要人类可读输出：
+
+```bash
+aiconductor-cli webpage publish <输入> -t <文件名> -f text
+```
+
+若 Markdown 内容需要代码复制按钮：
+
+```bash
+aiconductor-cli webpage publish <输入> -t <文件名> --copy-button
+```
+
+### 解析输出
+
+JSON 格式输出示例：
+```json
+{
+  "success": true,
+  "data": {
+    "success": true,
+    "message": "HTML网页发布成功",
+    "online_url": "https://oss.aiconductor.fun/online/xxx.html"
+  }
+}
+```
+
+从中提取 `data.online_url` 作为最终可访问链接返回给用户。
+
+### 错误处理
+
+- 缺少 API Key → 提示用户前往 https://dev.aiconductor.fun/register 注册获取
+- CLI 未安装 / command not found → 执行 `npm install -g aiconductor-cli@latest`，安装后重试原命令
+- API 返回错误 → 展示错误信息给用户
+
+### 可选项
+
+- `-t, --title <title>`：指定文件名（不含 .html 后缀）
+- `--type <type>`：强制指定类型：`md` 或 `html`（默认自动识别）
+- `--copy-button`：添加代码复制按钮（仅 Markdown 类型生效，默认不添加）
+- `-f, --format <format>`：输出格式（`json` 或 `text`），默认 `json`
+
+## 注意事项
+
+1. **文件名必须用英文**：`-t` 参数只能传入英文（小写+连字符），禁止中文、空格、特殊字符
+2. 发布前确保内容完整有效
+3. Markdown 类型默认不添加代码块复制按钮，使用 `--copy-button` 可开启；HTML 类型无此选项
+4. API 按次计费（0.01 元/次），计费信息不会暴露给终端用户
+5. 默认使用 JSON 输出格式，便于 AI Agent 解析
+6. 与 `html publish` 命令的区别：`html publish` 是专门发布 HTML 的子命令，`webpage publish` 是统一入口，自动识别 Markdown/HTML

package/.codebuddy/skills/webpage-publish/references/aiconductor-skills-setup.md

@@ -0,0 +1,50 @@
+# 技能安装与配置
+
+仅当用户明确要求首次安装、初始化或配置此技能时读取本文档。正常搜索流程默认环境已经可用，不要每次使用前执行初始化。
+
+## 安装或升级 CLI
+
+使用 npm 全局安装最新版：
+
+```bash
+npm install -g aiconductor-cli@latest
+```
+
+安装后确认命令可用：
+
+```bash
+aiconductor-cli --help
+```
+
+## 配置 API Key
+
+引导用户前往 https://dev.aiconductor.fun/register 注册并获取 API Key。
+
+macOS / Linux：
+
+```bash
+echo 'export AICONDUCTOR_API_KEY="your-api-key"' >> ~/.zshrc && source ~/.zshrc
+```
+
+Windows PowerShell：
+
+```powershell
+[Environment]::SetEnvironmentVariable("AICONDUCTOR_API_KEY", "your-api-key", "User")
+```
+
+也可在当前项目目录创建 `.env` 文件：
+
+```env
+AICONDUCTOR_API_KEY=your-api-key
+```
+
+优先级：`-k` 参数 > `AICONDUCTOR_API_KEY` 环境变量 > `.env` 文件。
+
+## 故障恢复
+
+- `command not found` / `aiconductor-cli` 无法识别：执行安装或升级命令后重试原命令
+- 缺少 API Key：按上方方式配置密钥后开启新的终端会话，或在当前命令中临时使用 `-k <api-key>`
+- API Key 无效或认证失败：请用户确认密钥是否正确、是否仍可用，再重试原命令
+- 版本不兼容或参数不被识别：升级到最新版后重试原命令
+
+修复后只重试原命令一次；如果仍失败，向用户展示原始错误信息和已尝试的修复步骤。

package/.codebuddy/skills/xhs-note-publish/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: xhs-note-publish
+description: 小红书扫码发布 — 生成小红书图文/视频笔记的扫码发布页与二维码。当用户想要发布小红书笔记、生成小红书发布页、创建小红书扫码发布链接、把图片/视频做成可发布的笔记页面时应使用此 Skill。触发词包括：小红书发布、小红书笔记、小红书扫码、xhs发布、xhs note、red note publish、发小红书、生成小红书发布页、小红书图文发布、小红书视频发布。
+---
+
+## 概述
+
+此 Skill 通过全局安装的 `aiconductor-cli` 命令行工具，调用小红书笔记发布 API，生成 H5 扫码发布页与二维码。用户扫码后可在手机浏览器中点击"发布到小红书"按钮，自动唤起小红书 App 进行发布。
+
+适用环境默认已配置好 CLI 和 API Key。当遇到安装或配置问题时，读取 [references/aiconductor-skills-setup.md](references/aiconductor-skills-setup.md)。仅当用户明确要求初始化或配置 Skill 时才主动读取该文件。
+
+## 准备工作
+
+发布前需确认用户已准备好：
+
+- **图文笔记**：标题（可选）、正文（可选）、至少 1 张图片（最多 18 张）
+- **视频笔记**：标题（可选）、正文（可选）、1 个视频，可选封面图
+
+图片、视频和封面均支持公网 HTTP(S) URL、本地文件路径、Base64/data URL。保存 Base64 内容的文本文件使用 `@文件路径` 传入。
+
+本地文件由 CLI 自动转成 data URL，与 Base64 素材一起通过 JSON 接口免费上传到临时 R2，再将公开 URL 传给小红书发布接口。默认链接有效期为 7 天，可用 `--upload-valid-days 1` 改为 1 天。
+
+## 发布流程
+
+### 1. 确认笔记类型
+
+根据用户意图确认笔记类型：
+- `normal` — 图文笔记（需要图片列表）
+- `video` — 视频笔记（需要视频素材，可选封面图）
+
+### 2. 收集素材信息
+
+从用户输入中提取以下信息，缺失的必填项要主动询问：
+
+| 信息 | 说明 | 是否必填 |
+|------|------|----------|
+| 笔记类型 | `normal` 或 `video` | 是 |
+| 图片素材 | URL、本地文件、Base64，可混用 | normal 必填，合计最多 18 张 |
+| 视频素材 | URL、本地文件、Base64 三选一 | video 必填 |
+| 标题 | 笔记标题，中文计 1 字/英文数字计 0.5 字，最多 20 字 | 否 |
+| 正文 | 笔记正文，最多 1000 字符 | 否 |
+| 封面图 | URL、本地文件、Base64 三选一（仅 video 类型） | 否 |
+| 临时链接有效期 | 本地/Base64 素材上传后的有效期，1 或 7 天 | 否，默认 7 天 |
+
+### 3. 执行发布
+
+使用 JSON 格式（默认，AI 友好）。
+
+**图文笔记：**
+
+```bash
+aiconductor-cli xhs note-publish normal \
+  --title "笔记标题" \
+  --content "笔记正文内容" \
+  --images "https://example.com/photo1.jpg,https://example.com/photo2.jpg"
+```
+
+**图文笔记（URL 与本地文件混用）：**
+
+```bash
+aiconductor-cli xhs note-publish normal \
+  --title "笔记标题" \
+  --images "https://example.com/photo1.jpg" \
+  --image-file "./photo2.jpg" \
+  --image-file "./photo3.png"
+```
+
+`--image-file` 和 `--image-base64` 均可重复使用。混用时顺序固定为 URL、本地文件、Base64，各组内部保持传入顺序。
+
+**图文笔记（Base64）：**
+
+```bash
+# 短 Base64 或 data URL 可直接传入
+aiconductor-cli xhs note-publish normal \
+  --image-base64 "data:image/png;base64,iVBORw0KGgo..."
+
+# 较大 Base64 建议写入文本文件，使用 @路径避免命令行长度限制
+aiconductor-cli xhs note-publish normal \
+  --image-base64 "@./photo-base64.txt"
+```
+
+**视频笔记（本地文件）：**
+
+```bash
+aiconductor-cli xhs note-publish video \
+  --title "视频标题" \
+  --content "视频正文内容" \
+  --video-file "./video.mp4" \
+  --cover-file "./cover.jpg"
+```
+
+若用户需要人类可读输出：
+
+```bash
+aiconductor-cli xhs note-publish <normal|video> ... -f text
+```
+
+### 4. 解析输出
+
+JSON 格式输出示例：
+
+```json
+{
+  "success": true,
+  "data": {
+    "success": true,
+    "message": "发布页生成成功",
+    "data": {
+      "id": "3502cf75-...-b8620053c7bf",
+      "url": "https://oss.aiconductor.fun/temporary_7/xhs_note_publish/.../index.html",
+      "qrcode": "data:image/png;base64,iVBORw0KGgo...",
+      "media": {
+        "images": ["https://example.com/photo1.jpg"],
+        "video": null,
+        "cover": null
+      }
+    }
+  }
+}
+```
+
+从中提取以下信息返回给用户：
+
+- **`data.data.url`** — H5 发布页在线地址，点击可直接打开（桌面端展示手机模拟框 + 右侧扫码面板，移动端直接打开发布引导页）
+- **`data.data.qrcode`** — 二维码 base64 图片（`data:image/png;base64,...`），手机扫码即可打开发布页
+- **`data.data.id`** — 笔记唯一标识 UUID
+- **`data.data.media`** — 最终使用的素材列表（images / video / cover）
+
+**返回给用户时，优先展示 H5 链接和二维码。** 二维码 base64 可以直接嵌入 HTML img 标签在聊天中预览。
+
+### 错误处理
+
+- 缺少 API Key / CLI 未安装 / command not found → 读取 [references/aiconductor-skills-setup.md](references/aiconductor-skills-setup.md) 并按其步骤处理
+- CLI 参数或 API 返回错误 → 展示错误信息给用户，常见原因包括：
+  - 本地文件不存在、不是普通文件或超过限制
+  - 视频/封面同时提供了多个来源
+  - Base64 文本文件为空或不可读
+  - 图片/视频 URL 不可公网访问或内网 localhost 地址
+  - 图片超过 32MB；URL 视频超过 200MB；本地/Base64 视频超过 100MB
+  - 图片数量超过 18 张
+  - 标题超过 20 字或正文超过 1000 字符
+- 参数校验失败或素材下载失败不扣费，仅页面生成成功时才扣费
+
+## 全部选项
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `-t, --title <标题>` | 笔记标题，最多 20 字符 | 空 |
+| `--content <正文>` | 笔记正文，最多 1000 字符 | 空 |
+| `--images <urls>` | 图片 URL 列表，逗号分隔（normal 类型），最多 18 张 | 无 |
+| `--image-file <path>` | 本地图片路径，可重复使用（normal 类型） | 无 |
+| `--image-base64 <data>` | 图片 Base64、data URL 或 `@文本文件`，可重复使用 | 无 |
+| `--video <url>` | 视频 URL（video 类型） | 无 |
+| `--video-file <path>` | 本地视频路径，与其他视频来源三选一 | 无 |
+| `--video-base64 <data>` | 视频 Base64、data URL 或 `@文本文件` | 无 |
+| `--cover <url>` | 视频封面图 URL（video 类型） | 无 |
+| `--cover-file <path>` | 本地视频封面路径 | 无 |
+| `--cover-base64 <data>` | 视频封面 Base64、data URL 或 `@文本文件` | 无 |
+| `--upload-valid-days <days>` | 本地/Base64 素材临时链接有效期：1 或 7 天 | `7` |
+| `-k, --api-key <key>` | AIConductor API Key | 环境变量或 .env |
+| `-f, --format <format>` | 输出格式：`json` 或 `text` | `json` |
+
+## 注意事项
+
+1. 采用后扣费模式：仅页面生成成功时才扣费，参数校验失败或素材下载失败不扣费
+2. 发布页生成 0.05 元/次，本地/Base64 素材预上传免费
+4. 临时上传链接有效期为 1 或 7 天，过期自动清理；应在有效期内完成发布
+5. 素材 URL 必须为公网可访问的 HTTP(S) 地址，内网 IP 和 localhost 将被拒绝
+6. URL 视频上限 200MB；本地/Base64 视频受上传接口限制为 100MB；图片上限 32MB
+7. 生成的 H5 页面支持移动端扫码后在浏览器中点击"发布到小红书"按钮自动唤起 App
+8. 默认使用 JSON 输出格式，便于 AI Agent 解析
+9. 图片顺序按 URL、本地文件、Base64 分组，各组内部保持输入顺序；第一张图片作为笔记封面

package/.codebuddy/skills/xhs-note-publish/references/aiconductor-skills-setup.md

@@ -0,0 +1,50 @@
+# 技能安装与配置
+
+仅当用户明确要求首次安装、初始化或配置此技能时读取本文档。正常操作流程默认环境已经可用，不要每次使用前执行初始化。
+
+## 安装或升级 CLI
+
+使用 npm 全局安装最新版：
+
+```bash
+npm install -g aiconductor-cli@latest
+```
+
+安装后确认命令可用：
+
+```bash
+aiconductor-cli --help
+```
+
+## 配置 API Key
+
+引导用户前往 https://dev.aiconductor.fun/register 注册并获取 API Key。
+
+macOS / Linux：
+
+```bash
+echo 'export AICONDUCTOR_API_KEY="your-api-key"' >> ~/.zshrc && source ~/.zshrc
+```
+
+Windows PowerShell：
+
+```powershell
+[Environment]::SetEnvironmentVariable("AICONDUCTOR_API_KEY", "your-api-key", "User")
+```
+
+也可在当前项目目录创建 `.env` 文件：
+
+```env
+AICONDUCTOR_API_KEY=your-api-key
+```
+
+优先级：`-k` 参数 > `AICONDUCTOR_API_KEY` 环境变量 > `.env` 文件。
+
+## 故障恢复
+
+- `command not found` / `aiconductor-cli` 无法识别：执行安装或升级命令后重试原命令
+- 缺少 API Key：按上方方式配置密钥后开启新的终端会话，或在当前命令中临时使用 `-k <api-key>`
+- API Key 无效或认证失败：请用户确认密钥是否正确、是否仍可用，再重试原命令
+- 版本不兼容或参数不被识别：升级到最新版后重试原命令
+
+修复后只重试原命令一次；如果仍失败，向用户展示原始错误信息和已尝试的修复步骤。

package/README.md

@@ -1,6 +1,6 @@
 # AIConductor CLI
 
-AIConductor 平台命令行工具箱，提供网页发布、搜索和抖音数据功能。
+AIConductor 平台命令行工具箱，提供网页发布、搜索、抖音数据和小红书扫码发布功能。
 
 ## 安装
 
@@ -8,7 +8,7 @@ AIConductor 平台命令行工具箱，提供网页发布、搜索和抖音数
 npm install -g aiconductor-cli
 ```
 
-**Node.js >= 16.0.0** 环境。
+**Node.js >= 18.0.0** 环境。
 
 ## 配置 API Key
 
@@ -229,6 +229,44 @@ aiconductor-cli douyin link-to-text <视频URL> [选项]
 aiconductor-cli douyin link-to-text "https://www.douyin.com/video/xxxxx"
 ```
 
+### 小红书扫码发布
+
+生成图文或视频笔记的 H5 发布页与二维码。素材支持公网 URL、本地文件、Base64/data URL，以及包含 Base64 内容的文本文件。
+
+```bash
+# 图文：URL 与本地图片混用
+aiconductor-cli xhs note-publish normal \
+  --title "笔记标题" \
+  --images "https://example.com/photo1.jpg" \
+  --image-file "./photo2.jpg" \
+  --image-file "./photo3.png"
+
+# 图文：较大 Base64 写入文本文件后使用 @路径
+aiconductor-cli xhs note-publish normal \
+  --image-base64 "@./photo-base64.txt"
+
+# 视频：本地视频与本地封面
+aiconductor-cli xhs note-publish video \
+  --title "视频标题" \
+  --video-file "./video.mp4" \
+  --cover-file "./cover.jpg"
+```
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `--images <urls>` | 图片 URL 列表，逗号分隔 | 无 |
+| `--image-file <path>` | 本地图片路径，可重复使用 | 无 |
+| `--image-base64 <data>` | 图片 Base64、data URL 或 `@文本文件`，可重复使用 | 无 |
+| `--video <url>` | 视频 URL | 无 |
+| `--video-file <path>` | 本地视频路径 | 无 |
+| `--video-base64 <data>` | 视频 Base64、data URL 或 `@文本文件` | 无 |
+| `--cover <url>` | 视频封面 URL | 无 |
+| `--cover-file <path>` | 本地视频封面路径 | 无 |
+| `--cover-base64 <data>` | 封面 Base64、data URL 或 `@文本文件` | 无 |
+| `--upload-valid-days <days>` | 本地/Base64 素材临时链接有效期：1 或 7 天 | 7 |
+
+本地文件会在 CLI 内转换成 data URL，与 Base64 素材统一通过 JSON 接口免费上传为临时公开 URL，不使用 multipart。图片合计最多 18 张、单张最多 32MB；本地/Base64 视频受上传接口限制为 100MB，URL 视频上限为 200MB。
+
 ### 通用选项
 
 所有命令支持：
@@ -249,6 +287,7 @@ aiconductor-cli douyin link-to-text "https://www.douyin.com/video/xxxxx"
 | 抖音用户搜索 | 0.15 元/页 |
 | 抖音视频搜索 | 0.15 元/页 |
 | 抖音链接转文字 | 0.01 元/次 + 0.0003 元/秒 |
+| 小红书扫码发布 | 0.05 元/次 |
 
 > 搜索/调用失败不扣费，仅成功时计费。
 

package/bin/aiconductor-cli.js

@@ -13,9 +13,13 @@ const {
   videoSearchCommand,
   linkToTextCommand,
 } = require("../src/commands/douyin");
-const { notePublishCommand } = require("../src/commands/xhs");
-
-const program = new Command();
+const { notePublishCommand } = require("../src/commands/xhs");
+
+const program = new Command();
+
+function collect(value, previous) {
+  return previous ? previous.concat([value]) : [value];
+}
 
 program
   .name("aiconductor-cli")
@@ -172,16 +176,22 @@ const xhsCmd = program
 
 xhsCmd
   .command("note-publish")
-  .description("生成小红书扫码发布页与二维码（图文0.05元/次，含OSS转存0.1元/次）")
+  .description("生成小红书扫码发布页与二维码（0.05元/次）")
   .argument("<type>", "笔记类型：normal（图文）或 video（视频）")
   .option("-k, --api-key <key>", "AIConductor API Key")
-  .option("-t, --title <title>", "笔记标题（最多20字符）")
-  .option("--content <text>", "笔记正文（最多1000字符）")
-  .option("--images <urls>", "图片公网URL列表，逗号分隔（normal类型必填，最多18张）")
-  .option("--video <url>", "视频公网URL（video类型必填）")
-  .option("--cover <url>", "视频封面图公网URL（仅video类型有效）")
-  .option("--transfer-to-oss", "是否将素材转存到云端（更稳定，7天有效）")
-  .option("-f, --format <format>", "输出格式：json 或 text", "json")
+  .option("-t, --title <title>", "笔记标题（最多20字符）")
+  .option("--content <text>", "笔记正文（最多1000字符）")
+  .option("--images <urls>", "图片公网URL列表，逗号分隔（normal类型，最多18张）")
+  .option("--image-file <path>", "本地图片路径，可重复使用（normal类型，最多18张）", collect)
+  .option("--image-base64 <data>", "图片Base64/data URL/@文本文件，可重复使用", collect)
+  .option("--video <url>", "视频公网URL（与--video-file、--video-base64三选一）")
+  .option("--video-file <path>", "本地视频路径（与--video、--video-base64三选一）")
+  .option("--video-base64 <data>", "视频Base64/data URL/@文本文件（与其他视频来源三选一）")
+  .option("--cover <url>", "视频封面图公网URL（与其他封面来源三选一）")
+  .option("--cover-file <path>", "本地视频封面路径（仅video类型有效）")
+  .option("--cover-base64 <data>", "视频封面Base64/data URL/@文本文件（仅video类型）")
+  .option("--upload-valid-days <days>", "本地/Base64素材临时链接有效期：1或7天", "7")
+  .option("-f, --format <format>", "输出格式：json 或 text", "json")
   .action((type, options) => { notePublishCommand(type, options); });
 
 // 未知命令处理

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiconductor-cli",
-  "version": "1.2.3",
+  "version": "1.3.1",
   "description": "AIConductor CLI 工具箱",
   "keywords": [
     "aiconductor",
@@ -9,6 +9,8 @@
     "deploy",
     "cli",
     "douyin",
+    "xiaohongshu",
+    "xhs",
     "search"
   ],
   "author": "",
@@ -17,7 +19,7 @@
     "aiconductor-cli": "bin/aiconductor-cli.js"
   },
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=18.0.0"
   },
   "scripts": {},
   "dependencies": {