initial: 七牛云上传 OpenClaw Skill

功能特性: - 支持 /upload, /u 命令上传文件到七牛云 - 支持 /qiniu-config 配置管理 - 支持飞书卡片交互 - 支持指定上传路径和存储桶 - 自动刷新 CDN 缓存 - 支持文件覆盖上传包含组件: - OpenClaw 处理器 (openclaw-processor.js) - 独立监听器 (scripts/feishu-listener.js) - 核心上传脚本 (scripts/upload-to-qiniu.js) - 部署脚本 (deploy.sh) - 完整文档部署方式: 1. 复制 skill 到 ~/.openclaw/workspace/skills/ 2. 配置 ~/.openclaw/credentials/qiniu-config.json 3. 重启 OpenClaw Gateway
2026-03-07 16:02:18 +08:00
commit 1aeae9cc51
36 changed files with 6826 additions and 0 deletions
--- a/SKILL.md
+++ b/SKILL.md
@@ -0,0 +1,261 @@
+---
+name: qiniu-uploader
+description: 七牛云文件上传和管理。支持命令触发和飞书卡片交互两种方式。
+---
+
+# 七牛云上传 Skill
+
+## 使用方式
+
+本 Skill 支持两种使用方式：
+
+### 方式 1：命令触发（简单）
+
+| 命令 | 说明 | 示例 |
+|------|------|------|
+| `/upload` | 上传文件到七牛云 | `/upload /config/file.txt` |
+| `/u` | 上传快捷命令（别名） | `/u file.txt` |
+| `/qiniu-config` | 管理七牛云配置 | `/qiniu-config list` |
+| `/qc` | 配置管理快捷命令（别名） | `/qc list` |
+| `/qiniu-help` | 查看帮助 | `/qiniu-help` |
+| `/qh` | 帮助快捷命令（别名） | `/qh` |
+
+### 方式 2：飞书卡片交互（推荐）
+
+通过飞书消息卡片按钮操作，体验更佳。需要配置卡片交互服务器。
+
+**卡片功能：**
+- 📎 选择文件上传
+- 📋 查看配置
+- ❓ 帮助
+
+## 命令格式
+
+### 上传文件
+
+```
+/upload [目标路径] [存储桶名]
+/upload --original [存储桶名]
+```
+
+**参数说明：**
+- `目标路径`：可选，指定上传到七牛云的路径（如 `/config/test/file.txt`）
+- `存储桶名`：可选，默认使用 `default` 存储桶
+- `--original`：使用原始文件名
+
+**示例：**
+```
+/upload                          # 使用原文件名上传到 default
+/upload --original               # 同上
+/upload /config/test.txt         # 上传到指定路径
+/upload /docs/r.pdf production   # 指定路径和存储桶
+```
+
+**文件覆盖行为：**
+- ✅ 上传同名文件会**自动覆盖**旧文件
+- ✅ 支持指定路径覆盖（如 `/config/test.txt`）
+- ✅ 覆盖后 CDN 会自动刷新（可能有几秒延迟）
+
+### 配置管理
+
+```
+/qiniu-config list                        # 查看当前配置
+/qiniu-config set <键> <值>               # 修改单个配置项
+/qiniu-config set-bucket <名> <JSON>      # 添加/修改存储桶
+/qiniu-config reset                       # 重置配置
+```
+
+**配置项说明：**
+- `default.accessKey` - 七牛访问密钥
+- `default.secretKey` - 七牛密钥
+- `default.bucket` - 存储桶名称
+- `default.region` - 区域代码（z0/z1/z2/na0/as0）
+- `default.domain` - CDN 域名
+
+**示例：**
+```
+/qiniu-config list
+/qiniu-config set default.accessKey YOUR_KEY
+/qiniu-config set default.domain https://cdn.example.com
+/qiniu-config set-bucket production {"accessKey":"...","secretKey":"...","bucket":"prod","region":"z0","domain":"https://prod-cdn.com"}
+```
+
+## 配置文件
+
+位置：`~/.openclaw/credentials/qiniu-config.json`
+
+```json
+{
+  "buckets": {
+    "default": {
+      "accessKey": "YOUR_ACCESS_KEY",
+      "secretKey": "YOUR_SECRET_KEY",
+      "bucket": "your-bucket-name",
+      "region": "z0",
+      "domain": "https://your-cdn-domain.com"
+    },
+    "production": {
+      "accessKey": "...",
+      "secretKey": "...",
+      "bucket": "prod-bucket",
+      "region": "z0",
+      "domain": "https://prod-cdn.com"
+    }
+  }
+}
+```
+
+## 执行脚本
+
+核心脚本：`~/.openclaw/workspace/skills/qiniu-uploader/scripts/upload-to-qiniu.js`
+
+### 调用方式
+
+```bash
+# 上传文件
+node scripts/upload-to-qiniu.js upload --file <文件路径> --key <目标路径> --bucket <存储桶名>
+
+# 配置管理
+node scripts/upload-to-qiniu.js config list
+node scripts/upload-to-qiniu.js config set <键> <值>
+node scripts/upload-to-qiniu.js config set-bucket <名> <JSON>
+```
+
+## 回复格式
+
+### 上传成功
+
+```
+✅ 上传成功！
+
+📦 文件：config/test.txt
+🔗 链接：https://cdn.example.com/config/test.txt
+💾 原文件：test.txt
+🪣 存储桶：default
+```
+
+### 上传失败
+
+```
+❌ 上传失败：文件不存在
+```
+
+### 配置列表
+
+```
+📋 当前配置：
+
+存储桶配置：
+
+  🪣 [default]
+     accessKey: YO_W...S_pK
+     secretKey: NlcJ...rMX7
+     bucket:    daoqires
+     region:    z0
+     domain:    https://daoqi.daoqi888.cn
+
+💡 使用 config set <key> <value> 修改配置
+```
+
+## 处理流程
+
+1. **识别命令**：检测消息是否以 `/upload`、`/qiniu-config` 或 `/qiniu-help` 开头
+2. **解析参数**：提取目标路径、存储桶名等参数
+3. **下载文件**：从飞书/钉钉下载附件到临时目录
+4. **执行上传**：调用 `upload-to-qiniu.js` 脚本上传到七牛云
+5. **刷新 CDN**：自动刷新 CDN 缓存
+6. **回复结果**：在聊天中回复上传结果
+7. **清理临时文件**：删除临时下载的文件
+
+## 依赖
+
+- Node.js v14+
+- 七牛云账号和存储桶
+- 飞书/钉钉机器人配置
+
+## 注意事项
+
+1. **文件需要先下载**：从聊天平台下载附件到临时目录
+2. **上传后清理**：完成后删除临时文件
+3. **配置安全**：AccessKey/SecretKey 妥善保管
+4. **路径规范**：建议使用 `/` 开头的路径（如 `/config/file.txt`）
+5. **区域代码**：确保 region 与存储桶实际区域一致
+6. **文件覆盖**：上传同名文件会自动覆盖（`insertOnly: 0`）
+
+## 区域代码
+
+| 代码 | 区域 |
+|------|------|
+| `z0` | 华东（浙江） |
+| `z1` | 华北（河北） |
+| `z2` | 华南（广东） |
+| `na0` | 北美 |
+| `as0` | 东南亚 |
+
+## 故障排查
+
+### 上传失败
+
+1. 检查配置文件是否存在：`~/.openclaw/credentials/qiniu-config.json`
+2. 检查 AccessKey/SecretKey 是否正确
+3. 检查存储桶名称是否匹配
+4. 检查区域代码是否正确
+
+### **同名文件无法覆盖** ⚠️
+
+**原因：** 七牛云存储桶启用了"防覆盖"设置
+
+**解决方法 1：通过七牛云控制台**
+1. 登录七牛云控制台：https://portal.qiniu.com/
+2. 进入"对象存储" → 选择你的存储桶
+3. 点击"设置" → "空间设置"
+4. 找到"防覆盖"选项，**关闭**它
+5. 保存设置后重试上传
+
+**解决方法 2：通过命令行**
+```bash
+# 1. 检查当前设置
+node scripts/check-bucket-override.js default
+
+# 2. 关闭防覆盖
+node scripts/update-bucket-setting.js mybucket noOverwrite 0
+
+# 3. 重启 Gateway
+openclaw gateway restart
+```
+
+**解决方法 3：修改上传脚本（临时）**
+在上传时使用不同的文件名（如添加时间戳）：
+```bash
+/upload /config/file_$(date +%Y%m%d_%H%M%S).txt
+```
+
+### 配置命令无响应
+
+1. 检查脚本权限：`chmod +x scripts/upload-to-qiniu.js`
+2. 手动测试：`node scripts/upload-to-qiniu.js config list`
+3. 查看日志输出
+
+### 文件下载失败
+
+1. 检查飞书/钉钉 App ID 和 App Secret 配置
+2. 检查机器人权限（im:message, im:file）
+3. 检查网络连接
+
+### 诊断工具
+
+```bash
+# 检查存储桶覆盖设置
+node scripts/check-bucket-override.js [bucket-name]
+
+# 更新存储桶设置
+node scripts/update-bucket-setting.js <bucket> <setting> <value>
+```
+
+## 相关文件
+
+- `scripts/upload-to-qiniu.js` - 核心上传脚本
+- `scripts/feishu-listener.js` - 飞书独立监听器（可选）
+- `~/.openclaw/credentials/qiniu-config.json` - 七牛云配置
+- `README.md` - 完整使用文档
+- `CHEATSHEET.md` - 快速参考卡片