aiconductor-cli 1.3.4 → 1.3.5

package/api_docs/video_to_text_v2.md

@@ -0,0 +1,49 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/video_to_text_v2`
+- **方法**: `POST`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+将视频文件 URL 转换为文字。长视频（>5 分钟的非 MP3 文件）直接使用阿里云 STT 转写，短视频和 MP3 使用 Coze STT 转写，包含 API 密钥验证与按秒计费（基础费率 × 实际转写时长，四舍五入至少 1 秒），具体费率以 api_services 表配置为准。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| file_url | string | 是 | - | 待转写的视频文件 URL |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息（成功/失败原因） |
+| text | string | 转写文本结果 |
+| billing | object | 计费信息 |
+| billing.service_fee | number | 本次服务费用 |
+| billing.discount_applied | boolean | 是否应用折扣/计费 |
+| billing.balance_before | number | 扣费前余额 |
+| billing.balance_after | number | 扣费后余额 |
+| billing.currency | string | 货币单位（CNY） |
+| billing.transaction_id | string | 交易流水号（失败为 null） |
+| billing.base_fee | number | 基础费率（成功及余额不足分支返回） |
+| billing.duration_seconds | number | 计费时长（秒，四舍五入，成功及余额不足分支返回） |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/video_to_text_v2" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{"file_url": "https://example.com/video.mp4"}'
+```
+
+## 注意事项
+1. 视频时长超过 20 分钟将被拒绝转写并返回失败，不计费。
+2. 余额 ≤ 0 将直接返回失败且不计费（额外校验）。
+3. 路由策略：>5 分钟且非 mp3 用阿里云 STT；其余（≤5 分钟视频或 mp3）用 Coze STT。
+4. 采用后扣费模式：转写失败、未获取到文本、密钥无效等异常均不扣费（service_fee 为 0）。
+5. 费用 = 基础费率 × 实际转写时长（四舍五入，至少 1 秒）；余额不足时返回失败且预置计费信息（transaction_id 为 null）。

package/api_docs/volcengine_face_pretty.md

@@ -0,0 +1,55 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/volcengine_face_pretty`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+调用火山引擎智能变美（FacePretty）接口进行人脸美颜。本插件在平台侧不执行计费（handler 未调用计费模块），仅消耗调用方提供的火山引擎 AccessKey 配额。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| access_key_id | string | 是 | - | 火山引擎 AccessKeyId |
+| secret_access_key | string | 是 | - | 火山引擎 SecretAccessKey |
+| image_url | string | 是 | - | 待处理图片 URL |
+| region | string | 否 | `"cn-north-1"` | 火山引擎服务区域 |
+| do_risk | boolean | 否 | `false` | 是否需要内容安全审核 |
+| multi_face | string | 否 | `"0"` | 多人脸策略：`"1"` 处理所有人脸，其他值仅处理最大人脸 |
+| beauty_level | float | 否 | `1.0` | 美颜程度，范围 0.0-1.0，值越大越明显 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| image_url | string | 处理后图片 URL（已转存至 OSS 临时目录），失败时为空字符串 |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/volcengine_face_pretty" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "access_key_id": "你的火山引擎AK",
+    "secret_access_key": "你的火山引擎SK",
+    "image_url": "https://example.com/portrait.jpg",
+    "beauty_level": 0.8,
+    "multi_face": "0",
+    "do_risk": false,
+    "region": "cn-north-1"
+  }'
+```
+
+## 注意事项
+1. 需调用方自备有效的火山引擎 AccessKey，平台侧不校验、不托管该密钥。
+2. `image_url` 为必填，缺失直接返回 `success=false`。
+3. `beauty_level` 取值 0.0-1.0；`multi_face="1"` 时处理图中所有人脸。
+4. 火山引擎接口失败时会自动重试最多 10 次；全部失败返回 `success=false`。
+5. 处理后的图片由插件转存至阿里云 OSS 临时目录并返回 URL，原响应为 base64 时也会上传。
+6. 平台侧不扣费，仅消耗火山引擎侧配额。

package/api_docs/volcengine_faceswap.md

@@ -0,0 +1,55 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/volcengine_faceswap`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+调用火山引擎 CVProcess（face_swap3_6）接口进行人脸融合（换脸）。本插件在平台侧不执行计费（handler 未调用计费模块），仅消耗调用方自行提供的火山引擎 AccessKey 配额。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| access_key_id | string | 是 | - | 火山引擎 AccessKeyId |
+| secret_access_key | string | 是 | - | 火山引擎 SecretAccessKey |
+| source_image | string | 是 | - | 源图 URL（被替换的人脸图） |
+| template_image | string | 是 | - | 模板图 URL（目标人脸图） |
+| face_type | string | 否 | `"area"` | 换脸类型：`l2r`/`t2b`/`area`，非法值自动回退为 `area` |
+| source_similarity | float | 否 | `1.0` | 源脸相似度，范围 0-1；无法转为 float 时回退 1.0 |
+| ref_img_url | string | 否 | `None` | 参考图 URL（可选，用于增强） |
+| region | string | 否 | `"cn-north-1"` | 火山引擎服务区域 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| image_url | string | 融合后的图片 URL，失败时为空字符串 |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/volcengine_faceswap" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "access_key_id": "你的火山引擎AK",
+    "secret_access_key": "你的火山引擎SK",
+    "source_image": "https://example.com/face.jpg",
+    "template_image": "https://example.com/template.jpg",
+    "face_type": "area",
+    "source_similarity": 1.0,
+    "region": "cn-north-1"
+  }'
+```
+
+## 注意事项
+1. 需调用方自备有效的火山引擎 AccessKey，平台侧不校验、不托管该密钥。
+2. `face_type` 仅接受 `l2r`/`t2b`/`area`，其余值自动回退为 `area`。
+3. `source_similarity` 传入非法值时回退为 `1.0`，不会报错。
+4. 火山引擎接口失败时会自动重试，最多重试 10 次；全部失败返回 `success=false`。
+5. 平台侧不扣费，仅消耗火山引擎侧的调用配额。

package/api_docs/website_screenshot.md

@@ -0,0 +1,49 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/website_screenshot`
+- **方法**: `POST`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+对指定网站进行截图并返回截图 URL，支持自定义截图宽度与加载延迟，包含 API 密钥验证与按次计费，费用以 api_services 表配置为准。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| url | string | 是 | - | 要截图的网站 URL（须以 http:// 或 https:// 开头） |
+| delay_seconds | int | 否 | 1 | 页面加载后的延迟秒数 |
+| width | int | 否 | 1920 | 截图宽度（像素） |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| screenshot_url | string | 生成的截图文件 URL |
+| file_name | string | 截图文件名 |
+| billing | object | 计费信息 |
+| billing.service_fee | number | 本次服务费用 |
+| billing.discount_applied | boolean | 是否应用折扣/计费 |
+| billing.balance_before | number | 扣费前余额 |
+| billing.balance_after | number | 扣费后余额 |
+| billing.currency | string | 货币单位（CNY） |
+| billing.transaction_id | string | 交易流水号（失败为 null） |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/website_screenshot" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://example.com", "delay_seconds": 2, "width": 1920}'
+```
+
+## 注意事项
+1. 采用后扣费模式：截图生成失败、URL 格式无效、请求异常均不扣费（service_fee 为 0）。
+2. url 必须以 http:// 或 https:// 开头，否则返回格式错误且不扣费。
+3. 截图服务请求超时 180 秒，超时视为服务异常且不扣费。
+4. 按次计费：截图成功即扣费。

package/api_docs/wx_access_token.md

@@ -0,0 +1,44 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/wx_access_token`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+获取微信公众号接口调用凭据（Access Token）。仅做 API 密钥有效性校验，**不扣费**，Token 有效期为 7200 秒（由微信返回，需调用方自行缓存）。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| appid | string | 是 | - | 微信公众号的 AppID |
+| secret | string | 是 | - | 微信公众号的 AppSecret |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| access_token | string | 获取到的接口调用凭据（失败为空字符串） |
+| expires_in | int | 凭证有效时间，单位：秒（成功时微信返回，一般为 7200；失败为 0） |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/wx_access_token" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "appid": "wx1234567890abcdef",
+    "secret": "your_app_secret"
+  }'
+```
+
+## 注意事项
+1. 本接口**不扣费**，仅验证 API 密钥；密钥无效或账户被禁用时返回 `success=false`。
+2. `appid` / `secret` 为公众号后台凭证，请妥善保管，避免泄露。
+3. 微信返回的 `access_token` 全局唯一且有效期 7200 秒，建议调用方缓存复用，避免频繁调用触发频率限制。
+4. 调用微信接口的网络超时时间为 30 秒，超时返回失败提示。

package/api_docs/wx_article_analysis_data_push.md

@@ -0,0 +1,43 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/wx_article_analysis_data_push`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+微信文章分析数据推送服务（纯扣费/触发接口）。为**计费插件**：每次调用直接扣费一次，费用以 `api_services` 表（`service_code=wx_article_analysis_data_push`）配置为准。
+
+## 请求参数
+
+> 本接口无额外业务参数，仅需 API 密钥鉴权。
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功（扣费是否成功） |
+| message | 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/None | 交易流水 ID（成功时为整数；失败或未扣费时为 `null`） |
+| billing.error | string | 失败分支额外携带的错误说明（仅失败时存在） |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/wx_article_analysis_data_push" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+## 注意事项
+1. 本接口为**纯扣费/触发接口**，每次成功调用即扣费一次，用于触发后续的微信文章分析数据推送流程。
+2. **不扣费场景**：API 密钥无效、账户被禁用、余额不足、服务异常——此时 `transaction_id=null`，余额不变（异常分支 `service_fee=0`）。
+3. 调用方应据 `success` 判断扣费结果；失败分支的 `billing` 中会包含 `error` 字段说明原因。

package/api_docs/wx_article_data.md

@@ -0,0 +1,48 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/wx_article_data`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+获取指定微信文章的互动数据（阅读、点赞、在看、分享、收藏、评论等）。为**计费插件**：按次计费，费用以 `api_services` 表（`service_code=wx_article_data`）配置为准。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| url | string | 是 | - | 微信文章链接 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | 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_ids | array | 交易流水 ID 列表（成功时为 `[transaction_id]`，未扣费时为空列表 `[]`） |
+| data | object | 文章互动数据（结构取决于第三方数据源，通常含阅读数、点赞数、在看数、分享数、收藏数、评论数等字段；失败时为 `{}`） |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/wx_article_data" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "url": "https://mp.weixin.qq.com/s?__biz=xxxx&mid=xxxx&idx=1&sn=xxxx"
+  }'
+```
+
+## 注意事项
+1. 本接口**计费**，仅在成功获取文章数据后扣费一次；`billing.transaction_ids` 为列表。
+2. **不扣费场景**：缺少 `url`、API 密钥无效、账户被禁用、余额不足、第三方 API 返回错误（`code!=0`）、服务异常——上述情况 `transaction_ids` 为空列表且余额不变。
+3. 上游数据服务最多重试 10 次，单次调用整体超时 60 秒。
+4. `data` 字段结构由第三方数据源决定，调用方应做容错处理；异常分支下 `data` 含 `error_details`。

package/api_docs/wx_article_style_rewrite.md

@@ -0,0 +1,45 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/users/wx_article_style_rewrite`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+异步调用扣子工作流，将微信公众号文章按指定风格改写，返回 task_url 供轮询结果。本插件仅校验密钥、不计费（无 billing）。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| coze_token | string | 是 | — | 用户的 Coze API Token |
+| article_url | string | 是 | — | 微信公众号文章链接 |
+| article_style | string | 是 | — | 文章风格，如：招商小话匣 |
+| model | string | 否 | "minimax/minimax-m2.7" | 使用的模型 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功（任务已提交） |
+| message | string | 响应消息（成功时为「任务已提交，请打开result_url查看结果」） |
+| task_id | string | 工作流任务 ID |
+| result_url | string | 结果查看 URL |
+| debug_url | string | 调试 URL |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/users/wx_article_style_rewrite" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{"coze_token": "pat_xxxxxxxx", "article_url": "https://mp.weixin.qq.com/s/abcdef", "article_style": "招商小话匣"}'
+```
+
+## 注意事项
+1. 本插件仅校验 api_key 有效性，不扣费（无 billing 字段）。
+2. `coze_token`、`article_url`、`article_style` 均为必填，缺失任一将返回失败。
+3. 为异步任务：提交后通过响应中的 `result_url` 查看改写结果，需自行轮询。
+4. 工作流内部使用固定的飞书多维表格参数与 workflow_id，调用方无需关心。
+5. 校验失败、密钥无效或账户禁用时返回空 task_id/result_url/debug_url。

package/api_docs/wx_draft_add.md

@@ -0,0 +1,56 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/wx_draft_add`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+新增微信公众号图文草稿：先上传封面图获取 `thumb_media_id`，再调用微信 `draft/add` 接口创建草稿。仅做 API 密钥校验，**不扣费**。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| access_token | string | 是 | - | 微信公众号接口调用凭证（通过 wx_access_token 获取） |
+| title | string | 是 | - | 文章标题 |
+| content | string | 是 | - | 文章内容（HTML 格式） |
+| image_url | string | 是 | - | 封面图片 URL（需可公网访问，用于上传获取 thumb_media_id） |
+| author | string | 否 | 空 | 作者（微信限制不超过 16 字符，超出将截断） |
+| content_source_url | string | 否 | 空 | 原文链接 |
+| digest | string | 否 | 空 | 摘要 |
+| need_open_comment | int | 否 | `0` | 是否打开评论，`0` 否 / `1` 是 |
+| only_fans_can_comment | int | 否 | `0` | 是否仅粉丝可评论，`0` 否 / `1` 是 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| media_id | string | 创建成功的草稿 media_id（失败为空字符串，可传入 wx_draft_publish 发布） |
+| error_code | int | 错误码，成功为 `0`，失败为微信返回的 `errcode` |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/wx_draft_add" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "access_token": "your_wechat_access_token",
+    "title": "我的第一篇文章",
+    "content": "<p>这里是正文内容，支持 <b>加粗</b> 等 HTML 标签。</p>",
+    "image_url": "https://example.com/cover.jpg",
+    "author": "张三",
+    "digest": "文章摘要"
+  }'
+```
+
+## 注意事项
+1. 本接口**不扣费**，仅验证 API 密钥。
+2. `image_url` 必须可公网访问，接口会先下载并上传至微信素材库获取 `thumb_media_id`；上传失败则返回 `media_id` 为空。
+3. `author` 字段超过 16 字符（或 8 个汉字）会被截断，以符合微信限制。
+4. 返回的 `media_id` 需配合 `wx_draft_publish` 接口完成发布。
+5. 微信端对 `content` 中图片有域名白名单等校验，建议正文图片先经 `wx_image_upload` 转为微信图片 URL。

package/api_docs/wx_draft_publish.md

@@ -0,0 +1,47 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/wx_draft_publish`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+将已创建的图文草稿提交发布（微信 `freepublish/submit` 接口）。仅做 API 密钥校验，**不扣费**。注意：接口调用成功仅表示发布任务提交成功，实际发布结果由微信事件推送通知。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| access_token | string | 是 | - | 微信公众号接口调用凭证（通过 wx_access_token 获取） |
+| media_id | string | 是 | - | 要发布的草稿 media_id（通过 wx_draft_add 获取） |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功（任务是否提交成功） |
+| message | string | 响应消息 |
+| publish_id | string | 发布任务 ID（成功时返回） |
+| msg_data_id | string | 消息的数据 ID |
+| errcode | int | 微信返回的错误码，`0` 表示成功 |
+| errmsg | string | 错误信息 |
+| code | int | HTTP 状态码，成功为 `200`（密钥/参数错误为 400/401，超时 504，其他异常 500） |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/wx_draft_publish" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "access_token": "your_wechat_access_token",
+    "media_id": "your_draft_media_id"
+  }'
+```
+
+## 注意事项
+1. 本接口**不扣费**，仅验证 API 密钥。
+2. 需先通过 `wx_draft_add` 获取草稿 `media_id`，再调用本接口提交发布。
+3. 微信端为**异步发布**：本接口返回成功仅代表任务已提交，最终发布结果通过微信事件回调通知，需另行监听。
+4. `access_token`、`media_id` 缺失时分别返回 `code=400`；密钥无效返回 `code=401`；调用微信超时返回 `code=504`。

package/api_docs/wx_history_articles.md

@@ -0,0 +1,70 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/wx_history_articles`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+获取微信公众号历史文章列表，支持自动翻页与按页计费。为**计费插件**：按成功翻页次数计费（每翻一页扣费一次），费用以 `api_services` 表（`service_code=get_wx_history_article`）配置为准（源码注释提示：链接短链 0.08/次、长链 0.06/次、按名称 0.08 元/次，实际以表配置为准）。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| url | string | 否* | - | 微信文章链接（用于定位公众号）。与 `name` 至少提供一个 |
+| name | string | 否* | - | 公众号名称或微信 ID（调用参数名 `name`） |
+| max_pages | int | 否 | `1` | 最大翻页数量 |
+| max_seconds | int | 否 | `50` | 最长运行时长（秒），超时即停止翻页 |
+
+> **说明**：`url` 与 `name` 二者至少提供一个，否则返回失败。
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | 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.pages_billed | int | 实际成功计费（翻页）页数 |
+| billing.total_service_fee | float | 累计扣费总额 |
+| billing.transaction_ids | array | 交易流水 ID 列表（每页一条） |
+| data | object | 历史文章结果数据，含以下字段 |
+| data.code | int | 最后一页的 API 返回码（`0` 为正常） |
+| data.msg | string | `success` / `error` |
+| data.data | array | 文章列表，每项为文章对象（含标题、链接、发布时间等字段，结构取决于数据源） |
+| data.total_num | int | 该公众号历史文章总数（仅第一页返回） |
+| data.total_page | int | 总页数（仅第一页返回） |
+| data.publish_count | int | 发布次数（仅第一页返回） |
+| data.masssend_count | int | 群发次数（仅第一页返回） |
+| data.now_page | int | 实际已翻页数 |
+| data.now_page_articles_num | int | 已获取文章总数 |
+| data.mp_nickname | string | 公众号昵称（使用 `name` 参数时返回） |
+| data.mp_wxid | string | 公众号 wxid（使用 `name` 参数时返回） |
+| data.mp_ghid | string | 公众号 ghid（使用 `name` 参数时返回） |
+| data.head_img | string | 公众号头像（使用 `name` 参数时返回） |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/wx_history_articles" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "人民日报",
+    "max_pages": 3,
+    "max_seconds": 50
+  }'
+```
+
+## 注意事项
+1. 本接口**按页计费**，每成功翻一页扣费一次；已扣费的页不退还。
+2. **停止翻页条件**：余额不足、API 返回错误、无更多页、达到 `max_pages` 或超过 `max_seconds` 任一满足即停止；`billing.pages_billed` / `total_service_fee` 反映实际扣费。
+3. **不扣费场景**：缺少 `url` 与 `name`、API 密钥无效、账户被禁用——此时 `pages_billed=0`、`total_service_fee=0`、余额不变。
+4. `data.data[]` 为文章对象列表，字段结构由第三方数据源决定，需做容错解析。
+5. 每页请求最多重试 10 次；建议合理设置 `max_seconds` 以避免单次调用过长触发平台 180 秒超时。

package/api_docs/wx_image_upload.md

@@ -0,0 +1,46 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/wx_image_upload`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+从指定 URL 下载图片并上传到微信公众号素材库，返回微信图片 URL。仅做 API 密钥校验，**不扣费**。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| access_token | string | 是 | - | 微信公众号接口调用凭证（通过 wx_access_token 获取） |
+| image_url | string | 是 | - | 待上传的图片公网 URL 地址 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| url | string | 上传成功后微信返回的图片 URL（失败为空字符串） |
+| errcode | int | 错误码，`0` 表示成功，非 0 或 `-1` 表示失败 |
+| errmsg | string | 错误描述信息 |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/wx_image_upload" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "access_token": "your_wechat_access_token",
+    "image_url": "https://example.com/cover.jpg"
+  }'
+```
+
+## 注意事项
+1. 本接口**不扣费**，仅验证 API 密钥。
+2. 仅支持 `jpg` / `jpeg` / `png` 格式，且文件大小需在 **1MB 以内**，超出限制将返回失败。
+3. `image_url` 须为可公网访问的图片地址；接口会校验响应 `Content-Type` 是否为图片类型。
+4. `access_token` 为必填，缺失时返回 `errcode=-1` 的失败响应。
+5. 上传使用的微信接口为 `cgi-bin/media/uploadimg`，返回的是微信图片外链 URL。