aiconductor-cli 1.3.3 → 1.3.5

package/api_docs/douyin_video_search.md

@@ -0,0 +1,60 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/douyin_video_search`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+根据关键词搜索抖音视频，支持排序、发布时间、时长、内容类型等筛选，并自动翻页。按页计费，费用以 api_services 表配置为准（服务码 `douyin_video_search`，每翻一页扣一次费，不足一页不扣）。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| keyword | string | 是 | - | 搜索关键词。 |
+| sort_type | string | 否 | `0` | 排序类型（透传 TikHub 接口，如 `0` 综合、`1` 最多点赞等）。 |
+| publish_time | string | 否 | `0` | 发布时间筛选（透传 TikHub 接口）。 |
+| filter_duration | string | 否 | `0` | 时长筛选（透传 TikHub 接口）。 |
+| content_type | string | 否 | `0` | 内容类型筛选（透传 TikHub 接口）。 |
+| max_pages | integer | 否 | `1` | 最大翻页页数，`0` 表示不限制页数（受 max_seconds 约束）。 |
+| max_seconds | integer | 否 | `50` | 最大运行秒数，内部上限 50 秒。 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功。 |
+| message | string | 响应消息。 |
+| data | object | 搜索结果。 |
+| data.video_list | array | 视频列表，每项含：aweme_id、desc、create_time、author{uid,short_id,nickname,sec_uid,unique_id,signature,follower_count,total_favorited,is_verified,verification_type,enterprise_verify_reason,custom_verify,region,avatar_url}、music{id,title,author,duration,play_url}、video{duration,ratio,width,height,play_url,download_suffix,cover_url,dynamic_cover_url,origin_cover_url}、statistics{aweme_id,comment_count,digg_count,download_count,play_count,share_count,forward_count,collect_count...}、share_url、video_tag。 |
+| data.cursor | integer | 下一页游标。 |
+| data.has_more | integer | 是否还有更多（0/1）。 |
+| billing | object | 计费信息。 |
+| billing.service_fee | float | 单页服务费率。 |
+| billing.total_fee | float | 实际总扣费（页数 × 单页费率）。 |
+| billing.discount_applied | boolean | 是否应用折扣。 |
+| billing.pages_charged | integer | 实际扣费页数。 |
+| billing.balance_before | float | 扣费前余额。 |
+| billing.balance_after | float | 扣费后余额。 |
+| billing.currency | string | 货币类型，固定为 `CNY`。 |
+| billing.transaction_ids | array | 各页扣费交易ID列表。 |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/douyin_video_search" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "keyword": "露营攻略",
+    "sort_type": "1",
+    "max_pages": 2
+  }'
+```
+
+## 注意事项
+1. 仅当某一页成功返回视频数据时才对该页扣费；第一页即失败则不扣费，直接返回失败。
+2. 受 `max_pages` 与 `max_seconds`（上限 50 秒）双重限制；超时或后续翻页失败会返回已成功获取的部分数据（success 仍为 true）。
+3. 上游（TikHub）密钥仅配置在服务端，调用方无需也不应传入。

package/api_docs/douyin_video_search_fast.md

@@ -0,0 +1,48 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/douyin_video_search_fast`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+通过 Coze 工作流对抖音关键词进行快速搜索，返回视频列表（每条视频附带格式化后的创建时间）。按次计费，费用以 api_services 表配置为准（服务码 `douyin_keywords_search_fast`）。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| keyword | string | 是 | - | 搜索关键词。 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功。 |
+| keyword | string | 回显的搜索关键词。 |
+| video_list | array | 视频列表，每项含上游返回的原始字段；其中 `create_time` 经转换为 `create_time_converted`（YYYY-MM-DD HH:MM）。 |
+| message | 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 | integer | 成功扣费后的交易ID；未扣费时为 `null`。 |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/douyin_video_search_fast" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "keyword": "美食教程"
+  }'
+```
+
+## 注意事项
+1. 采用后扣费模式：仅在搜索成功（上游 code=0 且 HTTP 200）后才扣费；密钥无效/余额不足/网络异常/响应解析失败均不扣费。
+2. 上游 Coze 工作流密钥仅配置在服务端，调用方无需也不应传入。
+3. 返回结构依赖上游工作流输出，具体视频字段以 `video_list` 中实际内容为准。

package/api_docs/fast_ocr.md

@@ -0,0 +1,51 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/fast_ocr`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+通过 Coze 工作流对图片进行 OCR 文字识别，返回拼接后的识别文本与原始结果。按次计费，费用以 api_services 表配置为准（服务码 `Fast_OCR`）。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| image_url | string | 是 | - | 待识别的图片 URL |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| ocr_text | string | 拼接后的完整识别文字 |
+| ocr_results | array | 原始 OCR 识别结果（按区块组织） |
+| ocr_results[].words | array | 区块内文字项列表 |
+| ocr_results[].words[].text | string | 单条识别文字 |
+| billing | object | 计费信息 |
+| billing.service_fee | float | 本次费用（单价） |
+| billing.discount_applied | boolean | 是否应用折扣（成功分支为 true） |
+| billing.balance_before | float | 扣费前余额 |
+| billing.balance_after | float | 扣费后余额 |
+| billing.currency | string | 货币单位，固定 `CNY` |
+| billing.transaction_id | int/null | 交易 ID |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/fast_ocr" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "image_url": "https://example.com/receipt.jpg"
+  }'
+```
+
+## 注意事项
+1. `image_url` 为必填，缺失返回 `success=false`。
+2. 单价由 `api_services` 表（服务码 `Fast_OCR`）读取，按次计费。
+3. 余额不足、Coze 调用失败、OCR 未识别到结果等情形均不扣费，返回 `success=false`。
+4. `ocr_results` 为 Coze 工作流返回的原始结构（含按区块/文字项组织），`ocr_text` 为所有文字项的拼接结果。

package/api_docs/flow_article2podcast_creat.md

@@ -0,0 +1,41 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/flow_article2podcast_creat`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+创建文章转播客工作流任务，支持文章 URL 或内容输入，返回执行 ID 用于后续查询。本插件不计费（无 billing）。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| article_content | string | 否 | "" | 文章内容（与 article_url 至少填一个） |
+| article_url | string | 否 | "" | 文章 URL（与 article_content 至少填一个） |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| execute_id | string | 执行 ID（用于查询接口） |
+| debug_url | string | 调试 URL |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/flow_article2podcast_creat" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{"article_url": "https://example.com/some-article", "article_content": ""}'
+```
+
+## 注意事项
+1. `article_content` 与 `article_url` 至少提供一个，否则返回失败（execute_id/debug_url 为空）。
+2. 该接口为异步任务创建入口，需配合 `flow_article2podcast_query` 接口，使用返回的 `execute_id` 轮询执行结果。
+3. 内部调用扣子（Coze）工作流 API，请求超时 30s（连接 10s）。
+4. 工作流创建失败、HTTP 非 200、未返回 execute_id 等情况均返回失败且不产生执行 ID。

package/api_docs/flow_article2podcast_query.md

@@ -0,0 +1,41 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/flow_article2podcast_query`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+查询文章转播客工作流任务执行结果，输入执行 ID，返回执行状态与输出内容。本插件不计费（无 billing）。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| execute_id | string | 是 | — | 执行 ID（由 flow_article2podcast_creat 创建时返回） |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功（execute_status 为 Success 时为 true） |
+| message | string | 响应消息（根据状态返回：成功/失败/执行中） |
+| execute_status | string | 执行状态：`Running` / `Success` / `Failed` |
+| output | string | 输出结果（已提取的 Output 内容，原始为 JSON 字符串） |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/flow_article2podcast_query" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{"execute_id": "7484132558797553704_xxxx"}'
+```
+
+## 注意事项
+1. `execute_id` 不能为空，否则直接返回失败。
+2. 该接口为异步轮询接口：任务可能处于 `Running` 状态，需调用方按间隔重试直至 `Success` 或 `Failed`。
+3. `output` 为上游 Output 字段内容；若 JSON 解析失败则原样返回字符串。
+4. 内部调用扣子（Coze）工作流历史接口，请求超时 30s（连接 10s）。
+5. 本插件不产生费用（不计费）。

package/api_docs/flow_wx_history_articles.md

@@ -0,0 +1,45 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/flow_wx_history_articles`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+通过扣子（Coze）工作流获取微信公众号历史文章数据，返回文章 Excel 与 ZIP 文件的下载链接。本接口**不接入本平台计费系统（不扣费）**，仅作为工作流调用桥接。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| account_name | string | 是 | - | 目标微信公众号名称 |
+| max_pages | int | 否 | `5` | 最大翻页数量 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，框架自动注入；本插件同时会将该 `api_key` 作为工作流参数转发给扣子工作流。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功（工作流执行结果） |
+| message | string | 处理结果消息 |
+| article_xlsx | string | 文章数据 Excel 文件 URL（失败为空字符串） |
+| article_zip | string | 文章数据 ZIP 文件 URL（失败为空字符串） |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/flow_wx_history_articles" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "account_name": "人民日报",
+    "max_pages": 5
+  }'
+```
+
+## 注意事项
+1. 本接口**不接入本平台计费系统，不扣费**。
+2. `api_key` 除用于本平台鉴权外，会被作为工作流参数 `api_key` 转发给扣子工作流（框架自动从请求头注入到 body），请确保提供的密钥同时被工作流侧接受。
+3. 调用依赖外部扣子工作流（Coze），整体请求超时时间为 120 秒；超时或网络错误返回 `success=false`。
+4. 响应中 `data` 字段由扣子工作流返回（JSON 字符串），解析后提取 `article_xlsx`、`article_zip`、`message`、`success`；工作流执行失败（`code!=0`）或数据解析失败时返回失败。
+5. 返回的为文件下载链接，调用方自行下载；链接有效期取决于扣子/存储侧配置。

package/api_docs/generate_image.md

@@ -0,0 +1,68 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/generate_image`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+调用火山引擎 Ark Seedream 文生图模型生成 AI 图片，支持 doubao-seedream-4.5/5.0、2K/4K 分辨率与多种宽高比。按实际生成张数计费，单价以 api_services 表配置为准（服务码 `Generate_Image`）。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| prompt | string | 是 | - | 图片生成提示词 |
+| model | string | 否 | `"doubao-seedream-5-0-260128"` | 模型名，仅支持 `doubao-seedream-5-0-260128` / `doubao-seedream-4-5-251128` |
+| resolution | string | 否 | `"2K"` | 分辨率，仅支持 `2K`/`4K` |
+| aspect_ratio | string | 否 | `"1:1"` | 宽高比，可选 `1:1`/`4:3`/`3:4`/`16:9`/`9:16`/`3:2`/`2:3`/`21:9` |
+| image | array | 否 | `None` | 参考图 URL 列表（1-14 张，用于图生图） |
+| watermark | boolean | 否 | `false` | 是否添加水印 |
+| response_format | string | 否 | `"url"` | 返回格式：`url` 或 `b64_json` |
+| sequential_image_generation | string | 否 | `"disabled"` | `disabled`=单图，`auto`=组图 |
+| max_images | integer | 否 | `15` | 组图模式最大图片数（1-15，仅 `auto` 时生效） |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| images | array | 生成的图片列表 |
+| images[].url | string | 图片 URL（已转存至 OSS temporary 目录） |
+| images[].b64_json | string | base64 图片数据（仅 `response_format=b64_json` 时返回） |
+| images[].size | string | 图片尺寸（若有） |
+| model | string | 实际使用的模型名 |
+| created | integer | 生成时间戳 |
+| usage | object | 用量信息（来自 Ark 响应） |
+| billing | object | 计费信息 |
+| billing.service_fee | float | 本次总费用（单价 × 生成张数） |
+| billing.discount_applied | boolean | 是否应用折扣（恒为 true） |
+| billing.balance_before | float | 扣费前余额 |
+| billing.balance_after | float | 扣费后余额 |
+| billing.currency | string | 货币单位，固定 `CNY` |
+| billing.transaction_id | int/null | 交易 ID |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/generate_image" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "prompt": "一只在樱花树下打盹的橘猫，宫崎骏风格",
+    "model": "doubao-seedream-5-0-260128",
+    "resolution": "2K",
+    "aspect_ratio": "16:9",
+    "watermark": false,
+    "response_format": "url"
+  }'
+```
+
+## 注意事项
+1. 模型、分辨率、宽高比需匹配，非法值直接返回 `success=false`（错误信息会列出支持的选项）。
+2. `image` 参考图数量不能超过 14 张；组图模式下 `max_images` 取值 1-15。
+3. 单价由 `api_services` 表（服务码 `Generate_Image`）读取，按生成张数计费；`discount_applied` 恒为 `true`。
+4. 若 `余额 < 单张费用` 则直接返回 `success=false` 且不扣费；若余额足以支付单张但不足以支付全部，则正常生成并按 `min(应扣费用, 余额)` 实际扣减（仍返回 `success=true`）。
+5. 生成的图片 URL 为 Ark 原链（24h 有效），插件已自动转存至 OSS `temporary/` 目录以长期可用。

package/api_docs/get_duration.md

@@ -0,0 +1,37 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/get_duration`
+- **方法**: `POST`
+- **Content-Type**: `application/json`
+- **鉴权**: 本接口无需鉴权（代码中未读取 api_key，无计费）
+
+## 功能说明
+获取视频文件的时长信息，无计费。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| file_url | string | 是 | - | 视频文件的 URL |
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息（成功/失败原因） |
+| data | object | 时长信息 |
+| data.duration | number | 视频时长（秒） |
+| data.* | any | 底层时长服务返回的其他字段 |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/get_duration" \
+  -H "Content-Type: application/json" \
+  -d '{"file_url": "https://example.com/video.mp4"}'
+```
+
+## 注意事项
+1. 本插件无任何鉴权与计费逻辑，调用 free。
+2. data 字段具体结构取决于底层时长获取服务，duration（秒）为可靠返回字段。
+3. 获取失败或发生异常时返回 success=false 且 data 为空对象。

package/api_docs/hot_list_mixed.md

@@ -0,0 +1,122 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/hot_list_mixed`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+聚合获取 NewsNow 支持的多平台热榜；每个成功返回数据的 `source_id` 按服务单价计费一次，失败来源不计费。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| source_ids | array&lt;string&gt; / string | 是 | - | 平台来源 ID 数组，或以逗号分隔的字符串；去重后至少提供 1 个、最多 52 个。仅支持下表中的不重复来源 ID。 |
+| latest | boolean | 否 | true | 是否请求上游尝试返回较新的数据。`true` 不保证绕过上游缓存。 |
+| limit | integer | 否 | 30 | 每个平台最多返回的热榜条数，范围 1-30。 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+**支持的平台 ID（52 个不重复来源）：**
+
+| 来源 ID | 平台 | 内容 |
+|--------|------|------|
+| `v2ex` | V2EX | 最新分享 |
+| `zhihu` | 知乎 | 热点 |
+| `weibo` | 微博 | 实时热搜 |
+| `zaobao` | 联合早报 | 最新新闻 |
+| `coolapk` | 酷安 | 今日最热 |
+| `mktnews` | MKTNews | 快讯 |
+| `mktnews-flash` | MKTNews | 快讯 |
+| `wallstreetcn` | 华尔街见闻 | 快讯 |
+| `wallstreetcn-quick` | 华尔街见闻 | 快讯 |
+| `wallstreetcn-news` | 华尔街见闻 | 最新新闻 |
+| `wallstreetcn-hot` | 华尔街见闻 | 最热 |
+| `douyin` | 抖音 | 热点 |
+| `hupu` | 虎扑 | 主干道热帖 |
+| `dongqiudi` | 懂球帝 | 头条 |
+| `aihot` | AIHOT | AI 新闻 |
+| `tieba` | 百度贴吧 | 热议 |
+| `toutiao` | 今日头条 | 热点 |
+| `ithome` | IT之家 | 最新新闻 |
+| `thepaper` | 澎湃新闻 | 热榜 |
+| `sputniknewscn` | 卫星通讯社 | 最新新闻 |
+| `cankaoxiaoxi` | 参考消息 | 最新新闻 |
+| `pcbeta-windows11` | 远景论坛 | Win11 |
+| `cls` | 财联社 | 电报 |
+| `cls-telegraph` | 财联社 | 电报 |
+| `cls-depth` | 财联社 | 深度 |
+| `cls-hot` | 财联社 | 热门 |
+| `xueqiu` | 雪球 | 热门股票 |
+| `gelonghui` | 格隆汇 | 事件 |
+| `fastbull` | 法布财经 | 快讯 |
+| `fastbull-express` | 法布财经 | 快讯 |
+| `fastbull-news` | 法布财经 | 头条 |
+| `solidot` | Solidot | 最新新闻 |
+| `hackernews` | Hacker News | 热门故事 |
+| `producthunt` | Product Hunt | 热门产品 |
+| `github` | GitHub | 今日趋势 |
+| `bilibili` | 哔哩哔哩 | 热搜 |
+| `bilibili-hot-search` | 哔哩哔哩 | 热搜 |
+| `kaopu` | 靠谱新闻 | 最新新闻 |
+| `jin10` | 金十数据 | 最新新闻 |
+| `baidu` | 百度 | 热搜 |
+| `nowcoder` | 牛客 | 热搜 |
+| `sspai` | 少数派 | 热点 |
+| `juejin` | 稀土掘金 | 热点 |
+| `ifeng` | 凤凰网 | 热点资讯 |
+| `chongbuluo-latest` | 虫部落 | 最新帖子 |
+| `chongbuluo-hot` | 虫部落 | 热门帖子 |
+| `douban` | 豆瓣 | 热门电影 |
+| `steam` | Steam | 在线人数 |
+| `tencent-hot` | 腾讯新闻 | 综合早报 |
+| `freebuf` | FreeBuf | 网络安全 |
+| `qqvideo-tv-hotsearch` | 腾讯视频 | 热搜榜 |
+| `iqiyi-hot-ranklist` | 爱奇艺 | 热播榜 |
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| data | object | 热榜查询结果 |
+| data.sources | array | 成功获取数据的平台列表，保持请求的来源顺序 |
+| data.sources[].source_id | string | 上游实际使用的平台来源 ID |
+| data.sources[].status | string | 上游数据状态，`success` 或 `cache` |
+| data.sources[].updated_time | integer | 上游更新时间，Unix 毫秒时间戳 |
+| data.sources[].items | array | 热榜条目列表 |
+| data.sources[].items[].id | string | 条目 ID |
+| data.sources[].items[].title | string | 标题 |
+| data.sources[].items[].url | string | 原文链接 |
+| data.sources[].items[].mobile_url | string | 移动端链接，可能为空 |
+| data.sources[].items[].pub_date | integer / string | 发布时间，格式取决于来源 |
+| data.sources[].items[].extra | object | 来源特有的补充信息，可能为空对象 |
+| data.failed_sources | array | 请求失败的平台列表；成功平台仍会正常返回 |
+| data.failed_sources[].source_id | string | 失败的平台来源 ID |
+| data.failed_sources[].message | 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；未扣费时为 null |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/hot_list_mixed" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "source_ids": ["zhihu", "weibo"],
+    "latest": true,
+    "limit": 10
+  }'
+```
+
+## 注意事项
+1. 余额校验按请求的去重后来源数量计算；实际仅对成功返回数据的来源扣费，每个成功来源扣一次服务单价。
+2. 当部分来源失败时，接口仍返回成功来源和 `failed_sources`；当全部来源失败时不扣费。
+3. 上游服务可能返回缓存数据或临时不可用，调用方应根据 `status` 和 `failed_sources` 做容错处理。

package/api_docs/html_publish.md

@@ -0,0 +1,50 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/html_publish`
+- **方法**: `POST`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+将 HTML 代码发布为网页并上传到阿里云 OSS 存储，自动添加时间戳和 UUID 后缀确保文件名唯一性，并自动为链接添加 `target="_blank"`。按次计费，费用以 api_services 表配置为准。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| html_code | string | 是 | - | HTML 格式文本内容（支持完整文档或 HTML 片段，系统会自动提取 `<!DOCTYPE html>` 到 `</html>` 部分） |
+| title | string | 否 | 随机 8 位十六进制串 | 文档标题，用作文件名基础（不含后缀） |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| online_url | string | 在线访问的网页 URL（失败时为 ""） |
+| 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 | 交易流水号（未扣费时为 null） |
+| billing.error | string | 错误信息（仅失败响应的 billing 中可能出现） |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/html_publish" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "html_code": "<!DOCTYPE html><html><head><title>页面</title></head><body><h1>你好</h1></body></html>",
+    "title": "我的页面"
+  }'
+```
+
+## 注意事项
+1. 采用后扣费模式：网页发布事务（finalize_webpage_publish）成功后才扣费；若发布事务失败，系统会尝试清理已上传的 OSS 文件且不扣费。
+2. API 密钥无效、账户禁用或余额不足时不扣费；OSS 上传或服务异常时不扣费。
+3. 系统会自动剥离 Markdown 代码块标记（```html ... ```）并提取纯 HTML 内容，且为所有 `<a href>` 链接追加 `target="_blank"`。

package/api_docs/html_publish_flexible.md

@@ -0,0 +1,65 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/html_publish_flexible`
+- **方法**: `POST`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+将 HTML 代码发布为网页并上传到阿里云 OSS 存储，支持通过 `html_code` 或 `html_url` 提供内容（二选一），支持自定义 `file_name`、`base_url` 和 `directory`。按次计费，费用以 api_services 表配置为准。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| file_name | string | 是 | - | 文件名（不含后缀，系统自动追加 .html） |
+| html_code | string | 条件必填 | null | HTML 文本（与 html_url 二选一，二者只能提供一个） |
+| html_url | string | 条件必填 | null | HTML 文件链接，仅支持 .html 文件（与 html_code 二选一） |
+| base_url | string | 否 | 默认配置 | 可选的自定义 OSS base_url（访问域名） |
+| directory | string | 否 | 默认配置 | 可选的自定义 OSS 存储目录 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| online_url | string | 在线访问的网页 URL（失败时为 ""） |
+| 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 | 交易流水号（未扣费时为 null） |
+| billing.error | string | 错误信息（仅失败响应的 billing 中可能出现） |
+
+## 请求示例
+
+```bash
+# 方式一：直接传 HTML 代码
+curl -X POST "http://plugin.aiconductor.fun/api/html_publish_flexible" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "file_name": "landing",
+    "html_code": "<!DOCTYPE html><html><body><h1>Hello</h1></body></html>",
+    "directory": "my_pages"
+  }'
+
+# 方式二：传 HTML 文件链接
+curl -X POST "http://plugin.aiconductor.fun/api/html_publish_flexible" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "file_name": "landing",
+    "html_url": "https://example.com/page.html"
+  }'
+```
+
+## 注意事项
+1. `html_code` 与 `html_url` 必须且只能提供其中一个：两者都未提供或同时提供时返回失败且不扣费。
+2. 当提供 `html_url` 时，链接必须以 `.html` 结尾（忽略查询串与锚点），否则返回失败且不扣费；下载失败时不扣费。
+3. 采用后扣费模式：OSS 上传成功并记录交易后才扣费；API 密钥无效、账户禁用或余额不足时不扣费。
+4. 系统会自动为所有 `<a href>` 链接追加 `target="_blank"`，并提取纯 HTML 内容。