aiconductor-cli 1.2.1 → 1.2.2

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/package.json

@@ -1,17 +1,18 @@
 {
   "name": "aiconductor-cli",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "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"
   },

package/src/api.js

@@ -1,4 +1,4 @@
-const http = require("http");
+const https = require("https");
 const fs = require("fs");
 const path = require("path");
 
@@ -40,6 +40,31 @@ function resolveApiKey(optionKey) {
   return null;
 }
 
+/**
+ * 过滤响应中的计费信息
+ * @param {object} resp
+ * @returns {object}
+ */
+function stripBilling(resp) {
+  if (!resp || typeof resp !== "object") return resp;
+  const result = { ...resp };
+  delete result.billing;
+  return result;
+}
+
+/**
+ * 校验整数参数，非有效正整数时报错
+ * @param {*} value
+ * @param {string} name
+ */
+function validateInt(value, name) {
+  if (value === undefined || value === null) return;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 0) {
+    throw Object.assign(new Error(`${name} 须为非负整数，收到: ${value}`), { type: "validation_error" });
+  }
+}
+
 /**
  * HTTP POST 请求封装
  * @param {string} host
@@ -53,7 +78,7 @@ function httpPost(host, path, body, headers = {}) {
 
     const options = {
       hostname: host,
-      port: 80,
+      port: 443,
       path: path,
       method: "POST",
       headers: {
@@ -63,7 +88,7 @@ function httpPost(host, path, body, headers = {}) {
       },
     };
 
-    const req = http.request(options, (res) => {
+    const req = https.request(options, (res) => {
       let chunks = [];
       res.on("data", (chunk) => chunks.push(chunk));
       res.on("end", () => {
@@ -112,10 +137,7 @@ async function publishHtml(apiKey, htmlCode, title) {
   if (title) reqBody.title = title;
 
   const resp = await httpPost(API_HOST, API_PATH, reqBody);
-
-  // 过滤计费信息
-  const { billing, ...safe } = resp;
-  return safe;
+  return stripBilling(resp);
 }
 
 /**
@@ -125,6 +147,10 @@ async function publishHtml(apiKey, htmlCode, title) {
  * @returns {Promise<object>}
  */
 async function webSearch(apiKey, params) {
+  // 输入校验
+  validateInt(params.count, "count");
+  validateInt(params.authLevel, "authLevel");
+
   const reqBody = {
     query: params.query,
     search_type: params.searchType,
@@ -140,9 +166,7 @@ async function webSearch(apiKey, params) {
     Authorization: `Bearer ${apiKey}`,
   });
 
-  // 过滤计费信息
-  const { billing, ...safe } = resp;
-  return safe;
+  return stripBilling(resp);
 }
 
 /**
@@ -163,8 +187,7 @@ async function publishMdToHtml(apiKey, mdText, filename, addCopyButton = false)
 
   const resp = await httpPost(API_HOST, MD_TO_HTML_API_PATH, reqBody);
 
-  const { billing, ...safe } = resp;
-  return safe;
+  return stripBilling(resp);
 }
 
 /**
@@ -178,8 +201,7 @@ async function douyinVideoInfo(apiKey, shareUrl) {
     api_key: apiKey,
     share_url: shareUrl,
   });
-  const { billing, ...safe } = resp;
-  return safe;
+  return stripBilling(resp);
 }
 
 /**
@@ -193,8 +215,7 @@ async function douyinVideoComments(apiKey, videoUrl, maxCount) {
   const body = { api_key: apiKey, video_url: videoUrl };
   if (maxCount !== undefined && maxCount !== null) body.max_count = maxCount;
   const resp = await httpPost(API_HOST, DOUYIN_VIDEO_COMMENTS_PATH, body);
-  const { billing, ...safe } = resp;
-  return safe;
+  return stripBilling(resp);
 }
 
 /**
@@ -210,8 +231,7 @@ async function douyinUserVideos(apiKey, homePage, maxSeconds, maxPages) {
   if (maxSeconds !== undefined && maxSeconds !== null) body.max_seconds = maxSeconds;
   if (maxPages !== undefined && maxPages !== null) body.max_pages = maxPages;
   const resp = await httpPost(API_HOST, DOUYIN_USER_VIDEOS_PATH, body);
-  const { billing, ...safe } = resp;
-  return safe;
+  return stripBilling(resp);
 }
 
 /**
@@ -225,8 +245,7 @@ async function douyinUserDetail(apiKey, homePage) {
     api_key: apiKey,
     home_page: homePage,
   });
-  const { billing, ...safe } = resp;
-  return safe;
+  return stripBilling(resp);
 }
 
 /**
@@ -243,8 +262,7 @@ async function douyinUserSearch(apiKey, keyword, opts = {}) {
   if (opts.fansRange) body.douyin_user_fans = opts.fansRange;
   if (opts.userType) body.douyin_user_type = opts.userType;
   const resp = await httpPost(API_HOST, DOUYIN_USER_SEARCH_PATH, body);
-  const { billing, ...safe } = resp;
-  return safe;
+  return stripBilling(resp);
 }
 
 /**
@@ -265,8 +283,7 @@ async function douyinVideoSearch(apiKey, keyword, opts = {}) {
   const resp = await httpPost(API_HOST, DOUYIN_VIDEO_SEARCH_PATH, body, {
     Authorization: `Bearer ${apiKey}`,
   });
-  const { billing, ...safe } = resp;
-  return safe;
+  return stripBilling(resp);
 }
 
 /**
@@ -280,8 +297,7 @@ async function douyinLinkToText(apiKey, videoUrl) {
     api_key: apiKey,
     video_url: videoUrl,
   });
-  const { billing, ...safe } = resp;
-  return safe;
+  return stripBilling(resp);
 }
 
 module.exports = {