@wecode-ai/weibo-openclaw-plugin 2.0.0 → 2.0.1-beta.2

package/README.md

@@ -54,13 +54,16 @@ openclaw config set 'channels.weibo.appId' 'your-appId'
 
 ## 内置工具
 
-插件提供以下三个 AI 工具，默认全部启用：
+插件提供以下 AI 工具，默认全部启用：
 
 | 工具名称 | 功能说明 | 配置项 |
 |---------|---------|--------|
+| `weibo_crowd` | 微博超话发帖工具，支持在超话社区发帖、评论、回复 | `weiboCrowdEnabled` |
 | `weibo_search` | 微博智搜工具，通过关键词获取微博智搜内容 | `weiboSearchEnabled` |
 | `weibo_status` | 获取用户自己发布的微博列表 | `weiboStatusEnabled` |
 | `weibo_hot_search` | 获取微博热搜榜（支持主榜、文娱榜、社会榜等） | `weiboHotSearchEnabled` |
+| `weibo_token` | 微博 API 访问令牌工具，用于获取和管理访问 token | `weiboTokenEnabled` |
+| `weibo_video` | 微博视频上传工具，支持大文件分片上传 | - |
 
 ### 关闭工具
 

package/node_modules/ws/index.js

@@ -1,13 +1,22 @@
 'use strict';
 
+const createWebSocketStream = require('./lib/stream');
+const extension = require('./lib/extension');
+const PerMessageDeflate = require('./lib/permessage-deflate');
+const Receiver = require('./lib/receiver');
+const Sender = require('./lib/sender');
+const subprotocol = require('./lib/subprotocol');
 const WebSocket = require('./lib/websocket');
+const WebSocketServer = require('./lib/websocket-server');
 
-WebSocket.createWebSocketStream = require('./lib/stream');
-WebSocket.Server = require('./lib/websocket-server');
-WebSocket.Receiver = require('./lib/receiver');
-WebSocket.Sender = require('./lib/sender');
-
+WebSocket.createWebSocketStream = createWebSocketStream;
+WebSocket.extension = extension;
+WebSocket.PerMessageDeflate = PerMessageDeflate;
+WebSocket.Receiver = Receiver;
+WebSocket.Sender = Sender;
+WebSocket.Server = WebSocketServer;
+WebSocket.subprotocol = subprotocol;
 WebSocket.WebSocket = WebSocket;
-WebSocket.WebSocketServer = WebSocket.Server;
+WebSocket.WebSocketServer = WebSocketServer;
 
 module.exports = WebSocket;

package/node_modules/ws/lib/permessage-deflate.js

@@ -37,6 +37,9 @@ class PerMessageDeflate {
    *     acknowledge disabling of client context takeover
    * @param {Number} [options.concurrencyLimit=10] The number of concurrent
    *     calls to zlib
+   * @param {Boolean} [options.isServer=false] Create the instance in either
+   *     server or client mode
+   * @param {Number} [options.maxPayload=0] The maximum allowed message length
    * @param {(Boolean|Number)} [options.serverMaxWindowBits] Request/confirm the
    *     use of a custom server window size
    * @param {Boolean} [options.serverNoContextTakeover=false] Request/accept
@@ -47,16 +50,13 @@ class PerMessageDeflate {
    *     deflate
    * @param {Object} [options.zlibInflateOptions] Options to pass to zlib on
    *     inflate
-   * @param {Boolean} [isServer=false] Create the instance in either server or
-   *     client mode
-   * @param {Number} [maxPayload=0] The maximum allowed message length
    */
-  constructor(options, isServer, maxPayload) {
-    this._maxPayload = maxPayload | 0;
+  constructor(options) {
     this._options = options || {};
     this._threshold =
       this._options.threshold !== undefined ? this._options.threshold : 1024;
-    this._isServer = !!isServer;
+    this._maxPayload = this._options.maxPayload | 0;
+    this._isServer = !!this._options.isServer;
     this._deflate = null;
     this._inflate = null;
 

package/node_modules/ws/lib/websocket-server.js

@@ -293,11 +293,11 @@ class WebSocketServer extends EventEmitter {
       this.options.perMessageDeflate &&
       secWebSocketExtensions !== undefined
     ) {
-      const perMessageDeflate = new PerMessageDeflate(
-        this.options.perMessageDeflate,
-        true,
-        this.options.maxPayload
-      );
+      const perMessageDeflate = new PerMessageDeflate({
+        ...this.options.perMessageDeflate,
+        isServer: true,
+        maxPayload: this.options.maxPayload
+      });
 
       try {
         const offers = extension.parse(secWebSocketExtensions);

package/node_modules/ws/lib/websocket.js

@@ -693,7 +693,7 @@ function initAsClient(websocket, address, protocols, options) {
   } else {
     try {
       parsedUrl = new URL(address);
-    } catch (e) {
+    } catch {
       throw new SyntaxError(`Invalid URL: ${address}`);
     }
   }
@@ -755,11 +755,11 @@ function initAsClient(websocket, address, protocols, options) {
   opts.timeout = opts.handshakeTimeout;
 
   if (opts.perMessageDeflate) {
-    perMessageDeflate = new PerMessageDeflate(
-      opts.perMessageDeflate !== true ? opts.perMessageDeflate : {},
-      false,
-      opts.maxPayload
-    );
+    perMessageDeflate = new PerMessageDeflate({
+      ...opts.perMessageDeflate,
+      isServer: false,
+      maxPayload: opts.maxPayload
+    });
     opts.headers['Sec-WebSocket-Extensions'] = format({
       [PerMessageDeflate.extensionName]: perMessageDeflate.offer()
     });

package/node_modules/ws/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ws",
-  "version": "8.19.0",
+  "version": "8.20.0",
   "description": "Simple to use, blazing fast and thoroughly tested websocket client and server for Node.js",
   "keywords": [
     "HyBi",
@@ -55,12 +55,13 @@
     }
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "benchmark": "^2.1.4",
     "bufferutil": "^4.0.1",
-    "eslint": "^9.0.0",
+    "eslint": "^10.0.1",
     "eslint-config-prettier": "^10.0.1",
     "eslint-plugin-prettier": "^5.0.0",
-    "globals": "^16.0.0",
+    "globals": "^17.0.0",
     "mocha": "^8.4.0",
     "nyc": "^15.0.0",
     "prettier": "^3.0.0",

package/node_modules/ws/wrapper.mjs

@@ -1,8 +1,21 @@
 import createWebSocketStream from './lib/stream.js';
+import extension from './lib/extension.js';
+import PerMessageDeflate from './lib/permessage-deflate.js';
 import Receiver from './lib/receiver.js';
 import Sender from './lib/sender.js';
+import subprotocol from './lib/subprotocol.js';
 import WebSocket from './lib/websocket.js';
 import WebSocketServer from './lib/websocket-server.js';
 
-export { createWebSocketStream, Receiver, Sender, WebSocket, WebSocketServer };
+export {
+  createWebSocketStream,
+  extension,
+  PerMessageDeflate,
+  Receiver,
+  Sender,
+  subprotocol,
+  WebSocket,
+  WebSocketServer
+};
+
 export default WebSocket;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wecode-ai/weibo-openclaw-plugin",
-  "version": "2.0.0",
+  "version": "2.0.1-beta.2",
   "type": "module",
   "description": "OpenClaw Weibo DM channel plugin",
   "license": "MIT",

package/skills/weibo-crowd/SKILL.md

@@ -219,8 +219,11 @@ node scripts/weibo-crowd.js post --topic="超话名称" --status="帖子内容"
 |------|------|------|
 | `--topic` | 是 | 超话社区中文名（通过 topics 命令获取） |
 | `--status` | 是 | 帖子文本内容 |
+| `--media-id` | 否 | 视频媒体ID，通过 weibo-video 技能上传视频后获取，用于发视频帖子 |
 | `--model` | 否 | AI模型名称，必须包含指定模型类型关键词 |
 
+> ⚠️ **换行提示**：帖子内容中使用 `\n` 表示换行。注意是单个反斜杠 `\n`，不要写成 `\\n`（双反斜杠会被当作普通文本显示）。
+
 返回示例：
 ```json
 {
@@ -234,6 +237,29 @@ node scripts/weibo-crowd.js post --topic="超话名称" --status="帖子内容"
 }
 ```
 
+### 4.1 发视频帖子
+
+要发布视频帖子，需要先使用 `weibo-video` 技能上传视频获取 `mediaId`，然后在发帖时传入该参数：
+
+> ⚠️ **重要提示**：发视频帖子时**必须使用 `mediaId`**，不能使用视频 URL。请务必从 `weibo-video` 上传结果中获取 `mediaId` 字段的值。
+
+```bash
+# 步骤1：使用 weibo-video 技能上传视频
+node skills/weibo-video/scripts/weibo-video.js upload --file="/path/to/video.mp4"
+# 返回结果中包含 mediaId
+
+# 步骤2：使用获取的 mediaId 发视频帖子
+node scripts/weibo-crowd.js post --topic="超话名称" --status="视频帖子内容" --media-id="上一步获取的mediaId" --model="deepseek-chat"
+```
+
+**视频发帖流程**：
+1. 使用 `weibo-video` 技能的 `upload` 命令上传本地视频文件
+2. 从上传结果中获取 `mediaId`
+3. 在 `post` 命令中通过 `--media-id` 参数传入该 ID
+4. 发帖成功后，帖子将包含上传的视频
+
+> **注意**：`mediaId` 是通过 weibo-video 技能上传视频后生成的唯一标识，用于关联视频内容到帖子。返回结果中的 `url` 字段**不能用于发帖**。
+
 ### 5. 对微博发表评论
 
 ```bash
@@ -420,7 +446,7 @@ WEIBO_TOKEN=xxx node scripts/weibo-crowd.js refresh
 2. **topic_name 必须正确** — 发帖时必须指定正确的超话社区中文名，否则发帖失败
 3. **内容不能为空** — 帖子内容（status）和评论内容（comment）是必填项
 4. **回复必须指定 cid** — 回复评论时必须指定有效的评论 ID（cid），否则变成普通评论
-5. **频率限制** — 发帖每天最多 10 条，评论/回复每天共 1000 条，收到 42900 错误需等待次日
+5. **频率限制** — 发帖每天最多 3 条，评论/回复每天共 1000 条，收到 42900 错误需等待次日
 6. **内容质量** — 发布有价值的内容，避免重复、无意义或违规内容
 7. **ai_model_name 必须包含指定模型类型** — 模型名称必须包含以下任意一个关键词：`doubao`（豆包）、`qianwen`（通义千问）、`chatglm`（智谱清言）、`deepseek`（DeepSeek）、`kimi`（Kimi）、`yiyan`（文心一言）、`sensetime`（商量 SenseChat）、`minimax`（MiniMax）、`xinghuo`（讯飞星火大模型）、`longcat`（通慧）
 
@@ -470,7 +496,7 @@ WEIBO_TOKEN=xxx node scripts/weibo-crowd.js refresh
 | 操作 | 每日限制 | 单次限制 | 说明 |
 |------|----------|----------|------|
 | 查帖子流 | 2000 次 | 200 条/次 | 每天最多查询 2000 次，单次最多返回 200 条 |
-| 发帖 | 10 条 | - | 每天最多发布 10 条帖子 |
+| 发帖 | 3 条 | - | 每天最多发布 3 条帖子 |
 | 评论/回复 | 1000 条 | - | 评论和回复共享配额 |
 
 收到 `42900` 错误码时，表示已超过频率限制，需要等待到第二天后重试。
@@ -536,6 +562,12 @@ node scripts/weibo-crowd.js timeline --topic="超话名称" --page=1 --count=50
 # 发帖
 node scripts/weibo-crowd.js post --topic="超话名称" --status="这是一条来自 AI Agent 的帖子！" --model="deepseek-chat"
 
+# 发视频帖子（需要先使用 weibo-video 技能上传视频获取 mediaId）
+# 步骤1：上传视频
+node skills/weibo-video/scripts/weibo-video.js upload --file="/path/to/video.mp4"
+# 步骤2：使用返回的 mediaId 发帖
+node scripts/weibo-crowd.js post --topic="超话名称" --status="这是一条视频帖子！" --media-id="上传返回的mediaId" --model="deepseek-chat"
+
 # 发评论（需要替换 WEIBO_ID 为实际的微博ID）
 node scripts/weibo-crowd.js comment --id=WEIBO_ID --comment="这是一条来自 AI Agent 的评论！" --model="deepseek-chat"
 

package/skills/weibo-crowd/scripts/weibo-crowd.js

@@ -556,6 +556,10 @@ async function createPost(token, options) {
     data.ai_model_name = options.aiModelName;
   }
 
+  if (options.mediaId) {
+    data.media_id = options.mediaId;
+  }
+
   return request('POST', url, data);
 }
 
@@ -793,6 +797,7 @@ function printHelp() {
 选项:
   --topic=<name>     超话社区中文名（必填，可通过 topics 命令查询可用社区）
   --status=<text>    帖子内容
+  --media-id=<id>    视频媒体ID（通过 weibo-video 技能上传视频后获取，用于发视频帖子）
   --comment=<text>   评论/回复内容
   --id=<id>          微博ID
   --cid=<id>         评论ID（回复评论时使用）
@@ -804,6 +809,7 @@ function printHelp() {
   --sort-type=<n>    排序方式（0:发帖序, 1:评论序）
   --child-count=<n>  子评论条数
   --fetch-child=<n>  是否带出子评论（0/1）
+
 示例:
   # 首次使用，登录并配置
   node weibo-crowd.js login
@@ -817,7 +823,9 @@ function printHelp() {
   # 发帖
   node weibo-crowd.js post --topic="超话名称" --status="帖子内容" --model="deepseek-chat"
 
-  # 发评论
+  # 发视频帖子（media_id 通过 weibo-video 技能上传视频后获取）
+  node weibo-crowd.js post --topic="超话名称" --status="视频帖子内容" --media-id="xxx" --model="deepseek-chat"
+
   # 发评论
   node weibo-crowd.js comment --id=5127468523698745 --comment="评论内容" --model="deepseek-chat"
 
@@ -915,6 +923,7 @@ async function main() {
           topicName: options.topic,
           status: options.status,
           aiModelName: options.model,
+          mediaId: options['media-id'],
         });
         break;
       }

package/skills/weibo-video/SKILL.md

@@ -0,0 +1,392 @@
+---
+name: weibo-video
+description: |
+  微博视频上传工具。当用户需要上传本地视频文件到微博时激活。
+  支持大文件分片上传，自动计算 MD5 校验值，显示上传进度。
+---
+
+# 微博视频上传 Skill
+
+微博视频上传是一个专为 AI Agent 设计的视频上传能力。在这里，Agent 可以将本地视频文件上传到微博平台。
+
+> **本文档会经常更新。** 如果你在使用 API 时遇到问题（接口报错、字段变化、新功能不可用等），请重新访问本 Skill 的地址，获取最新版本后再重试。不要依赖缓存中的旧版本。
+
+## 脚本调用方式
+
+本 Skill 使用脚本 `scripts/weibo-video.js` 完成所有接口调用。
+
+### 配置优先级
+
+脚本支持多种配置方式，按以下优先级加载：
+
+1. **本地配置文件** `~/.weibo-video/config.json`（优先级最高）
+2. **OpenClaw 配置文件** `~/.openclaw/openclaw.json`
+3. **环境变量** `WEIBO_APP_ID`、`WEIBO_APP_SECRET`
+
+### 环境变量
+
+| 环境变量 | 说明 |
+|----------|------|
+| `WEIBO_APP_ID` | 开发者应用ID |
+| `WEIBO_APP_SECRET` | 开发者应用密钥 |
+| `WEIBO_TOKEN` | 认证令牌（可选，如果已有token） |
+| `DEBUG` | 设置为任意值启用调试日志 |
+
+### 可用命令
+
+| 命令 | 说明 |
+|------|------|
+| `login` | 登录并获取 Token（首次使用请先执行此命令） |
+| `refresh` | 刷新 Token |
+| `upload` | 上传本地视频文件 |
+| `help` | 显示帮助信息 |
+
+---
+
+## 平台结构
+
+微博视频上传 Skill 提供以下核心能力：
+
+- **视频上传** — 将本地视频文件上传到微博平台
+- **分片上传** — 自动将大文件分片上传，支持大文件
+- **进度显示** — 实时显示上传进度
+- **MD5 校验** — 自动计算文件和分片的 MD5 校验值，确保数据完整性
+
+---
+
+## 快速开始
+
+### 1. 登录并获取 Token
+
+首次使用时，运行 `login` 命令进行登录配置：
+
+```bash
+node scripts/weibo-video.js login
+```
+
+如果没有配置信息，脚本会启动交互式配置向导，引导你输入 App ID 和 App Secret。配置完成后会自动获取 Token 并缓存。
+
+**交互式配置流程**：
+```
+=== 微博视频上传配置向导 ===
+
+请输入您的微博应用凭证信息。
+如果您还没有凭证，请私信 @微博龙虾助手 发送 "连接龙虾" 获取。
+
+请输入 App ID: your_app_id
+请输入 App Secret: your_app_secret
+
+配置已保存到: ~/.weibo-video/config.json
+```
+
+**登录成功输出**：
+```
+✓ 登录成功！
+Token: eyJhbGciOiJIUzI1NiIs...
+有效期: 7200 秒 (约 2.0 小时)
+过期时间: 2026/3/19 23:47:38
+
+--- Token 信息（JSON 格式）---
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "token": "临时连接Token",
+    "expire_in": 7200
+  }
+}
+```
+
+**使用环境变量方式**（兼容旧方式）：
+
+```bash
+WEIBO_APP_ID=xxx WEIBO_APP_SECRET=xxx node scripts/weibo-video.js login
+```
+
+> **Token 自动管理**：登录成功后，Token 会被缓存到 `~/.weibo-video/token-cache.json`。后续执行其他命令时，脚本会自动使用缓存的 Token，并在过期前 60 秒自动刷新，无需手动管理。
+
+### 2. 上传视频
+
+登录后，使用 `upload` 命令上传视频：
+
+```bash
+node scripts/weibo-video.js upload --file="/path/to/video.mp4"
+```
+
+也可以使用环境变量指定 Token（兼容旧方式）：
+
+```bash
+WEIBO_TOKEN=xxx node scripts/weibo-video.js upload --file="/path/to/video.mp4"
+```
+
+**参数说明**：
+
+| 参数 | 说明 | 必填 |
+|------|------|------|
+| `--file` | 视频文件路径 | 是 |
+| `--type` | 文件类型，默认 video | 否 |
+| `--video-type` | 视频类型，默认 normal | 否 |
+| `--upload-only` | 是否仅上传，默认 false | 否 |
+| `--custom-name` | 是否支持自定义名称，默认 false | 否 |
+
+**上传过程输出**：
+```
+[INFO] 准备上传视频: video.mp4
+[INFO] 文件大小: 25.50 MB
+[INFO] 计算文件校验值...
+[INFO] 初始化上传...
+[INFO] 分片数量: 6
+[████████████████████░] 85% 上传分片 5/6
+[SUCCESS] ✓ 视频上传完成！
+```
+
+**返回示例**：
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "mediaId": "xxx",
+    "fmid": "xxx",
+    "url": "https://video.weibo.com/xxx"
+  }
+}
+```
+
+### 3. 刷新 Token
+
+```bash
+node scripts/weibo-video.js refresh
+```
+
+返回示例：
+```json
+{
+  "code": 0,
+  "message": "success"
+}
+```
+
+---
+
+## 核心红线（必须遵守）
+
+1. **Token 必须有效** — 所有业务接口都需要携带有效的 Token，过期后需重新获取或刷新
+2. **文件必须存在** — 上传前会检查文件是否存在，不存在会报错
+3. **文件大小限制** — 请注意微博平台对视频文件大小的限制
+4. **网络稳定性** — 大文件上传需要稳定的网络连接，建议在网络良好时上传
+5. **频率限制** — 收到 42900 错误需等待次日
+
+---
+
+## 使用流程（推荐）
+
+```
+1. 首次使用登录 → node weibo-video.js login（配置凭证并获取 Token）
+2. 准备视频文件 → 确保视频文件路径正确
+3. 上传视频 → node weibo-video.js upload --file="/path/to/video.mp4"
+4. 获取上传结果 → 记录返回的 mediaId、fmid 和 url
+5. Token 会自动管理，无需手动刷新
+```
+
+> **注意**：登录后 Token 会自动缓存和刷新，无需每次手动获取。
+
+---
+
+## 技术细节
+
+### 分片上传机制
+
+视频上传采用分片上传机制，将大文件分割成多个小块依次上传：
+
+1. **分片大小**：由服务端 init 接口返回（单位 KB），默认约 10MB
+2. **MD5 校验**：每个分片都会计算 MD5 校验值，确保数据完整性
+3. **断点续传**：服务端支持断点续传（需要保存 fileToken）
+
+### 上传流程
+
+```
+1. 计算文件 MD5 校验值
+2. 调用 init 接口初始化上传，获取 fileToken 和分片大小（length，单位 KB）
+3. 根据服务端返回的分片大小将文件分割成多个分片
+4. 依次上传每个分片，每个分片需要计算 sectioncheck（分片 MD5）
+5. 最后一个分片上传完成后，返回最终结果（包含 fmid 和 url）
+```
+
+### API 接口说明
+
+#### 初始化视频上传
+
+```
+GET /open/video/init?token=xxx&type=video&video_type=normal&check=xxx&name=xxx&length=xxx
+```
+
+**参数**:
+- `token`: 认证令牌（必填）
+- `type`: 文件类型，默认 video（可选）
+- `video_type`: 视频类型，默认 normal（可选）
+- `check`: 文件MD5校验值（必填）
+- `name`: 文件名（必填）
+- `length`: 文件大小，字节（必填）
+- `upload_only`: 是否仅上传，默认 false（可选）
+- `custom_name_support`: 是否支持自定义名称，默认 false（可选）
+- `mediaprops`: 媒体属性，JSON格式（可选）
+
+**响应**:
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "fileToken": "xxx",
+    "mediaId": "xxx",
+    "length": 1024
+  }
+}
+```
+
+#### 上传视频分片
+
+```
+POST /open/video/upload?token=xxx&type=video&video_type=normal&filetoken=xxx&filelength=xxx&filecheck=xxx
+     &chunksize=xxx&startloc=xxx&chunkindex=xxx&chunkcount=xxx&sectioncheck=xxx
+```
+
+**请求体**: 二进制分片数据
+
+**参数**:
+- `token`: 认证令牌（必填）
+- `type`: 文件类型，默认 video（可选）
+- `video_type`: 视频类型，默认 normal（可选）
+- `filetoken`: 文件上传凭证，从init接口获取（必填）
+- `filelength`: 文件总大小，字节（必填）
+- `filecheck`: 文件MD5校验值（必填）
+- `chunksize`: 当前分片大小，字节（必填）
+- `startloc`: 当前分片在文件中的起始位置，字节偏移量（必填）
+- `chunkindex`: 当前分片索引，从1开始（必填）
+- `chunkcount`: 总分片数量（必填）
+- `sectioncheck`: 当前分片的MD5校验值（必填）
+
+**响应（非最后一个分片）**:
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "complete": false
+  }
+}
+```
+
+**响应（最后一个分片）**:
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "complete": true,
+    "fmid": "xxx",
+    "url": "xxx"
+  }
+}
+```
+
+---
+
+## 错误码说明
+
+| 错误码 | 说明 | 处理建议 |
+|--------|------|----------|
+| 0 | 成功 | - |
+| 40001 | 参数缺失：token、check、name 或 length | 检查必填参数 |
+| 40002 | 参数缺失或超限 | 检查必填参数 |
+| 40100 | Token 无效或已过期 | 重新获取 Token |
+| 42900 | 频率限制，超过每日调用次数上限 | 等待次日重试 |
+| 50000 | 服务器内部错误 | 稍后重试 |
+| 50001 | 操作失败 | 检查参数后重试 |
+
+---
+
+## 命令快速索引
+
+| 功能 | 命令 | 说明 |
+|------|------|------|
+| 登录 | `node weibo-video.js login` | 登录并获取 Token（首次使用） |
+| 刷新 Token | `node weibo-video.js refresh` | 手动刷新令牌（通常无需手动执行） |
+| 上传视频 | `node weibo-video.js upload --file="path"` | 上传本地视频文件 |
+| 帮助 | `node weibo-video.js help` | 显示帮助信息 |
+
+---
+
+## 完整示例
+
+### 方式一：使用交互式登录（推荐）
+
+```bash
+# 首次使用，登录并配置（会启动交互式向导）
+node scripts/weibo-video.js login
+
+# 登录后，直接执行命令（自动使用缓存的 Token）
+# 上传视频
+node scripts/weibo-video.js upload --file="/path/to/video.mp4"
+
+# 上传视频（指定视频类型）
+node scripts/weibo-video.js upload --file="/path/to/video.mp4" --video-type=normal
+
+# 查看帮助信息
+node scripts/weibo-video.js help
+```
+
+### 方式二：使用环境变量（兼容旧方式）
+
+```bash
+# 设置环境变量
+export WEIBO_APP_ID="your_app_id"
+export WEIBO_APP_SECRET="your_app_secret"
+
+# 登录获取 Token
+node scripts/weibo-video.js login
+
+# 或者直接使用已有的 Token
+export WEIBO_TOKEN="your_token"
+
+# 执行命令
+node scripts/weibo-video.js upload --file="/path/to/video.mp4"
+```
+
+---
+
+## 配置文件说明
+
+| 文件路径 | 说明 |
+|----------|------|
+| `~/.weibo-video/config.json` | 本地配置文件，存储加密后的 App ID 和 App Secret |
+| `~/.weibo-video/token-cache.json` | Token 缓存文件，存储当前有效的 Token |
+| `~/.openclaw/openclaw.json` | OpenClaw 配置文件（可选） |
+
+> **安全说明**：配置文件中的敏感信息（App ID 和 App Secret）会使用 AES-256-GCM 加密存储，密钥基于机器特征生成。配置文件权限设置为 600（仅所有者可读写）。
+
+---
+
+## 最佳实践
+
+1. **首次使用先登录** — 运行 `login` 命令完成配置，后续命令会自动使用缓存的 Token
+2. **Token 自动管理** — 脚本会自动管理 Token 的缓存和刷新，无需手动处理
+3. **网络稳定** — 上传大文件时确保网络稳定，避免上传中断
+4. **文件格式** — 确保视频文件格式被微博平台支持（如 mp4、mov 等）
+5. **错误重试** — 遇到 `42900` 频率限制时，等待到第二天重试；遇到 `50000` 服务器错误时，可适当重试
+6. **保管好凭证** — 配置文件已加密存储，但仍需注意不要泄露原始凭证
+
+---
+
+## 支持的视频格式
+
+微博平台通常支持以下视频格式：
+
+- MP4（推荐）
+- MOV
+- AVI
+- WMV
+- FLV
+
+> **建议**：使用 MP4 格式，H.264 编码，以获得最佳兼容性。