openclaw-skill-qiniu/SKILL.md

---
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` - 快速参考卡片