aiconductor-cli 1.2.1 → 1.2.3

package/CLAUDE.md

@@ -0,0 +1,76 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+### 本地运行
+
+```bash
+node bin/aiconductor-cli.js --help                              # 查看所有命令
+node bin/aiconductor-cli.js <command> --help                    # 查看子命令选项
+node bin/aiconductor-cli.js search web "关键词" -n 3 -f text    # 真实调用示例
+```
+
+### 发布到 npm
+
+```bash
+npm version patch|minor|major    # 升版本号
+npm pkg fix                      # 修复 package.json 格式
+npm publish                      # 发布
+```
+
+发布前须对本轮新增/修改的每个命令逐条执行真实调用，确认 exit 0 且输出格式正确。
+
+## Architecture
+
+### 分层结构
+
+```
+bin/aiconductor-cli.js          ← 入口层：commander 注册子命令树，不含业务逻辑
+src/api.js                      ← API 层：HTTPS 请求封装 + API Key 解析
+src/lib/cli-utils.js            ← 共享工具：output/outputError/key/error 统一处理
+src/commands/<topic>.js         ← 命令层：参数组装、调用 API、格式化输出
+```
+
+**`bin/aiconductor-cli.js`** — 纯聚合入口，action 回调只做参数传递。
+
+**`src/api.js`** — 所有外部 API 调用的底层封装：
+- `resolveApiKey(optionKey)` — 三级优先级：`-k` 参数 > `AICONDUCTOR_API_KEY` 环境变量 > `.env` 文件
+- `httpPost()` — 通用 HTTPS POST（端口 443），统一处理 HTTP 错误和网络错误
+- 每个 API 端点对应一个独立函数，通过 `stripBilling()` 过滤计费信息
+- 新增 API 端点只改此文件
+
+**`src/lib/cli-utils.js`** — 所有 command 文件共享的工具模块：
+- `outputResult(data, format, textFormatter?)` — 统一成功输出（JSON: `{success: true, data}`）
+- `outputError(err, format)` — 统一错误输出（JSON: `{success: false, error}` 到 stderr）
+- `resolveKeyOrExit(optionKey, format)` — 解析 API Key，失败自动输出错误并 exit(1)
+- `handleApiError(err, format)` — 统一处理 http_error / network_error / 未知错误
+- `safeParseInt(value, defaultValue)` — 安全整数解析，防 NaN
+
+**`src/commands/<topic>.js`** — 命令编排层，每个文件对应一个子命令组：
+- 导入 `cli-utils` 的 4 个共享函数，消除重复代码
+- 业务逻辑函数接收 argument + options，组装参数 → 调 API → `outputResult`
+- 成功 `exit(0)`，失败 `exit(1)`
+
+### 输出格式约定
+
+所有命令支持 `-f json|text`：
+- **JSON（默认）**：成功 stdout `{ success: true, data: {...} }`，失败 stderr `{ success: false, error: "..." }`
+- **text**：人类可读格式，成功以 `✓` 开头
+
+### API Key 鉴权
+
+两种模式共存（由 API 端决定，不要自行统一）：
+- Body 模式：`api_key` 放入请求 body（多数端点）
+- Bearer 模式：`Authorization: Bearer <api_key>` HTTP 头（web_search、douyin_video_search）
+
+### 扩展新 API 的标准流程
+
+1. `src/api.js`：添加 API 端点常量和调用函数（~10 行）
+2. `src/commands/<新主题>.js`：新建文件，导入 `cli-utils`，写命令函数（~10 行/命令）
+3. `bin/aiconductor-cli.js`：引入模块并注册子命令组
+
+### Skills 依赖
+
+`.codebuddy/skills/` 下 3 个 skills（`aic-web-search`、`webpage-publish`、`douyin-toolbox`）依赖此 CLI。修改命令签名或输出格式会破坏它们。`.codebuddy/` 已被 `.npmignore` 排除。

package/README.md

@@ -1,108 +1,266 @@
-# AIConductor CLI
-
-AIConductor 平台命令行工具箱，提供 HTML 发布和网页/图片搜索功能。
-
-## 安装
-
-```bash
-npm install -g aiconductor-cli
-```
-
-**Node.js >= 16.0.0** 环境。
-
-## 配置 API Key
-
-前往 [https://dev.aiconductor.fun/register](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`。
-
-## 命令
-
-### 发布 HTML 网页
-
-```bash
-aiconductor-cli html publish <HTML代码或文件路径> -t <英文文件名>
-```
-
-| 选项 | 说明 |
-|------|------|
-| `-t, --title` | 英文文件名（必填，小写+连字符） |
-| `-k, --api-key` | API Key（可选，默认读取环境变量） |
-| `-f, --format` | 输出格式：`json`（默认）或 `text` |
-
-示例：
-```bash
-aiconductor-cli html publish index.html -t my-page
-aiconductor-cli html publish "<h1>Hello</h1>" -t hello-page -f text
-```
-
-### 网页搜索
-
-```bash
-aiconductor-cli search web <关键词> [选项]
-```
-
-| 选项 | 说明 | 默认值 |
-|------|------|--------|
-| `-n, --count` | 返回条数（最多50） | 5 |
-| `--time-range` | 时间范围：`OneDay`/`OneWeek`/`OneMonth`/`OneYear` | 无 |
-| `--no-summary` | 不返回内容摘要 | 默认返回 |
-| `--content-format` | 内容格式：`Text`/`Markdown` | Text |
-| `--auth-level` | 权威过滤：0=不过滤，1=优先权威来源 | 0 |
-| `--query-rewrite` | 开启 Query 改写 | 关闭 |
-
-示例：
-```bash
-aiconductor-cli search web "北京今日天气" -n 3 --auth-level 1
-```
-
-### 图片搜索
-
-```bash
-aiconductor-cli search image <关键词> [选项]
-```
-
-| 选项 | 说明 | 默认值 |
-|------|------|--------|
-| `-n, --count` | 返回条数（最多5） | 5 |
-| `--time-range` | 时间范围 | 无 |
-
-示例：
-```bash
-aiconductor-cli search image "长城风景" -n 3 -f text
-```
-
-### 通用选项
-
-所有命令支持：
-- `-k, --api-key <key>` — API Key（优先级：参数 > 环境变量 > .env 文件）
-- `-f, --format <json|text>` — 输出格式，默认 JSON
-
-## 计费
-
-- HTML 发布：0.01 元/次
-- 网页/图片搜索：0.03 元/次
-- 搜索失败不扣费，仅成功时计费
-
-## 开发
-
-```bash
-git clone https://github.com/huyi9531/aiconductor-cli.git
-cd aiconductor-cli
-npm install
-node bin/aiconductor-cli.js --help    # 本地运行
-```
-
-## License
-
-MIT
+# AIConductor CLI
+
+AIConductor 平台命令行工具箱，提供网页发布、搜索和抖音数据功能。
+
+## 安装
+
+```bash
+npm install -g aiconductor-cli
+```
+
+**Node.js >= 16.0.0** 环境。
+
+## 配置 API Key
+
+前往 [https://dev.aiconductor.fun/register](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`。
+
+## 命令
+
+### 发布 HTML 网页
+
+```bash
+aiconductor-cli html publish <HTML代码或文件路径> [选项]
+```
+
+| 选项 | 说明 |
+|------|------|
+| `-t, --title` | 文档标题，用作文件名基础 |
+| `-k, --api-key` | API Key（可选，默认读取环境变量） |
+| `-f, --format` | 输出格式：`json`（默认）或 `text` |
+
+示例：
+```bash
+aiconductor-cli html publish index.html -t my-page
+aiconductor-cli html publish "<h1>Hello</h1>" -t hello-page -f text
+```
+
+### 发布 Markdown/HTML 网页（推荐）
+
+`webpage publish` 是统一的网页发布命令，自动识别 Markdown 和 HTML 并发布为在线网页。
+
+```bash
+aiconductor-cli webpage publish <Markdown/HTML代码或文件路径> [选项]
+```
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `-t, --title` | 文件名（不含 .html 后缀） | 自动生成 |
+| `-k, --api-key` | API Key（可选） | 环境变量 |
+| `--type` | 强制指定类型：`md` 或 `html` | 自动识别 |
+| `--copy-button` | 为代码块添加复制按钮（仅 Markdown） | 关闭 |
+| `-f, --format` | 输出格式：`json` 或 `text` | json |
+
+示例：
+```bash
+# 发布 Markdown 文件
+aiconductor-cli webpage publish README.md -t docs
+
+# 发布 Markdown 并添加代码复制按钮
+aiconductor-cli webpage publish article.md -t article --copy-button
+
+# 发布 HTML 文件
+aiconductor-cli webpage publish index.html -t my-page
+
+# 直接传入内容字符串
+aiconductor-cli webpage publish "# Hello\n\nThis is **markdown**" -t hello
+```
+
+### 网页搜索
+
+```bash
+aiconductor-cli search web <关键词> [选项]
+```
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `-n, --count` | 返回条数（最多50） | 5 |
+| `--time-range` | 时间范围：预设 `OneDay`/`OneWeek`/`OneMonth`/`OneYear`，或自定义 `YYYY-MM-DD..YYYY-MM-DD` | 无 |
+| `--no-summary` | 不返回内容摘要 | 默认返回 |
+| `--content-format` | 内容格式：`Text` 或 `Markdown` | Text |
+| `--auth-level` | 权威过滤：0=不过滤，1=优先权威来源 | 0 |
+| `--query-rewrite` | 开启 Query 改写 | 关闭 |
+| `-f, --format` | 输出格式：`json` 或 `text` | json |
+
+示例：
+```bash
+aiconductor-cli search web "北京今日天气" -n 3 --auth-level 1
+aiconductor-cli search web "AI 最新进展" --time-range OneWeek --content-format Markdown
+aiconductor-cli search web "技术文章" --time-range 2025-01-01..2025-06-30 -n 10
+```
+
+### 图片搜索
+
+```bash
+aiconductor-cli search image <关键词> [选项]
+```
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `-n, --count` | 返回条数（最多5） | 5 |
+| `--time-range` | 时间范围：预设或自定义日期范围 | 无 |
+| `-f, --format` | 输出格式：`json` 或 `text` | json |
+
+示例：
+```bash
+aiconductor-cli search image "长城风景" -n 3 -f text
+```
+
+### 抖音数据工具箱
+
+```bash
+aiconductor-cli douyin <子命令> [参数] [选项]
+```
+
+#### 获取作品详情
+
+```bash
+aiconductor-cli douyin video-info <分享链接> [选项]
+```
+
+示例：
+```bash
+aiconductor-cli douyin video-info "https://v.douyin.com/xxxxx/"
+```
+
+#### 获取作品评论
+
+```bash
+aiconductor-cli douyin video-comments <视频URL> [选项]
+```
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `--max-count` | 获取评论数量 | 50 |
+| `-f, --format` | 输出格式 | json |
+
+示例：
+```bash
+aiconductor-cli douyin video-comments "https://www.douyin.com/video/xxxxx" --max-count 100
+```
+
+#### 获取用户视频列表
+
+```bash
+aiconductor-cli douyin user-videos <用户主页URL> [选项]
+```
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `--max-pages` | 最大页数 | 1 |
+| `--max-seconds` | 最长运行时间（秒），最大 180 | 50 |
+| `-f, --format` | 输出格式 | json |
+
+示例：
+```bash
+aiconductor-cli douyin user-videos "https://www.douyin.com/user/xxxxx" --max-pages 3
+```
+
+#### 获取用户详情
+
+```bash
+aiconductor-cli douyin user-detail <用户主页URL> [选项]
+```
+
+示例：
+```bash
+aiconductor-cli douyin user-detail "https://www.douyin.com/user/xxxxx"
+```
+
+#### 搜索用户
+
+```bash
+aiconductor-cli douyin user-search <关键词> [选项]
+```
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `--max-pages` | 最大页数，0=不限制 | 1 |
+| `--max-seconds` | 最长运行时间（秒），最大 180 | 50 |
+| `--fans-range` | 粉丝数筛选：`0_1k`/`1k_1w`/`1w_10w`/`10w_100w`/`100w_` | 无 |
+| `--user-type` | 用户类型：`common_user`/`enterprise_user`/`personal_user` | 无 |
+| `-f, --format` | 输出格式 | json |
+
+示例：
+```bash
+aiconductor-cli douyin user-search "美食博主" --fans-range 10w_100w --user-type personal_user
+```
+
+#### 搜索视频
+
+```bash
+aiconductor-cli douyin video-search <关键词> [选项]
+```
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `--max-pages` | 最大页数，0=不限制 | 1 |
+| `--max-seconds` | 最长运行时间（秒），最大 50 | 50 |
+| `--sort-type` | 排序：0=综合，1=最多点赞，2=最新发布 | 0 |
+| `--publish-time` | 发布时间：0=不限，1=一天，7=一周，180=半年 | 0 |
+| `--filter-duration` | 时长：0=不限，0-1=1分钟内，1-5=1-5分钟，5-10000=5分钟以上 | 0 |
+| `--content-type` | 内容类型：0=不限，1=视频，2=图片，3=文章 | 0 |
+| `-f, --format` | 输出格式 | json |
+
+示例：
+```bash
+aiconductor-cli douyin video-search "编程教程" --sort-type 2 --publish-time 7 --content-type 1
+```
+
+#### 视频链接转文字
+
+```bash
+aiconductor-cli douyin link-to-text <视频URL> [选项]
+```
+
+示例：
+```bash
+aiconductor-cli douyin link-to-text "https://www.douyin.com/video/xxxxx"
+```
+
+### 通用选项
+
+所有命令支持：
+- `-k, --api-key <key>` — API Key（优先级：参数 > 环境变量 > .env 文件）
+- `-f, --format <json|text>` — 输出格式，默认 JSON
+
+## 计费
+
+| 功能 | 价格 |
+|------|------|
+| HTML 发布 | 0.01 元/次 |
+| Markdown/HTML 网页发布 | 0.01 元/次 |
+| 网页/图片搜索 | 0.03 元/次 |
+| 抖音作品详情 | 0.01 元/次 |
+| 抖音作品评论 | 0.01 元/次 |
+| 抖音用户视频列表 | 0.03 元/页 |
+| 抖音用户详情 | 0.03 元/次 |
+| 抖音用户搜索 | 0.15 元/页 |
+| 抖音视频搜索 | 0.15 元/页 |
+| 抖音链接转文字 | 0.01 元/次 + 0.0003 元/秒 |
+
+> 搜索/调用失败不扣费，仅成功时计费。
+
+## 开发
+
+```bash
+git clone https://github.com/huyi9531/aiconductor-cli.git
+cd aiconductor-cli
+npm install
+node bin/aiconductor-cli.js --help    # 本地运行
+```
+
+## License
+
+MIT

package/bin/aiconductor-cli.js

@@ -13,6 +13,7 @@ const {
   videoSearchCommand,
   linkToTextCommand,
 } = require("../src/commands/douyin");
+const { notePublishCommand } = require("../src/commands/xhs");
 
 const program = new Command();
 
@@ -164,6 +165,25 @@ douyinCmd
   .option("-f, --format <format>", "输出格式：json 或 text", "json")
   .action((videoUrl, options) => { linkToTextCommand(videoUrl, options); });
 
+// xhs 子命令组
+const xhsCmd = program
+  .command("xhs")
+  .description("小红书数据工具箱");
+
+xhsCmd
+  .command("note-publish")
+  .description("生成小红书扫码发布页与二维码（图文0.05元/次，含OSS转存0.1元/次）")
+  .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")
+  .action((type, options) => { notePublishCommand(type, options); });
+
 // 未知命令处理
 program.on("command:*", () => {
   console.error(`未知命令: ${program.args.join(" ")}`);

package/package.json

@@ -1,17 +1,18 @@
 {
   "name": "aiconductor-cli",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "AIConductor CLI 工具箱",
   "keywords": [
     "aiconductor",
     "html",
     "publish",
     "deploy",
-    "cli"
+    "cli",
+    "douyin",
+    "search"
   ],
   "author": "",
   "license": "MIT",
-  "main": "src/index.js",
   "bin": {
     "aiconductor-cli": "bin/aiconductor-cli.js"
   },