openclaw-skill-qiniu/README.md

# 🍙 七牛云自动上传 v2 - 完整使用指南

## ✨ v2 新功能

1. ✅ **支持指定上传路径** - 可以上传到存储桶的子文件夹
2. ✅ **使用原文件名** - 可选保留原始文件名
3. ✅ **聊天命令配置** - 在飞书中直接修改七牛云配置
4. ✅ **多存储桶支持** - 动态添加和管理多个存储桶

---

## 📤 上传文件

### 方式一：指定路径上传

```
/upload /config/test/test.txt default
[附上文件]
```

文件将上传到：`default` 存储桶的 `/config/test/test.txt`

### 方式二：使用原文件名

```
/upload --original default
[附上文件]
```

文件将使用原始文件名上传到 `default` 存储桶。

### 方式三：简单上传（默认使用原文件名）

```
/upload
[附上文件]
```

等价于：`/upload --original default`

### 方式四：指定存储桶

```
/upload /docs/report.pdf production
[附上文件]
```

---

## ⚙️ 配置管理（聊天命令）

### 查看当前配置

```
/qiniu-config list
```

回复示例：
```
📋 当前配置：

存储桶配置：

  🪣 [default]
     accessKey: 7hO...xyz
     secretKey: xYz...abc
     bucket:    my-files
     region:    z0
     domain:    https://cdn.example.com

💡 使用 config set <key> <value> 修改配置
```

### 修改单个配置项

```
/qiniu-config set default.accessKey YOUR_NEW_ACCESS_KEY
```

```
/qiniu-config set default.secretKey YOUR_NEW_SECRET_KEY
```

```
/qiniu-config set default.bucket my-new-bucket
```

```
/qiniu-config set default.region z1
```

```
/qiniu-config set default.domain https://new-cdn.example.com
```

### 添加新的存储桶

```
/qiniu-config set-bucket production {"accessKey":"...","secretKey":"...","bucket":"prod-bucket","region":"z0","domain":"https://prod-cdn.com"}
```

### 重置配置

```
/qiniu-config reset
```

---

## 📋 配置项说明

| 配置项 | 说明 | 示例 |
|--------|------|------|
| `default.accessKey` | 七牛访问密钥 | `7hO...` |
| `default.secretKey` | 七牛密钥 | `xYz...` |
| `default.bucket` | 存储桶名称 | `my-files` |
| `default.region` | 区域代码 | `z0`(华东)、`z1`(华北)、`z2`(华南)、`na0`(北美)、`as0`(东南亚) |
| `default.domain` | CDN 域名 | `https://cdn.example.com` |

---

## 🎯 使用示例

### 示例 1：上传配置文件

```
/upload /config/app/config.json default
[附上 config.json 文件]
```

回复：
```
✅ 上传成功！

📦 文件：config/app/config.json
🔗 链接：https://cdn.example.com/config/app/config.json
💾 原文件：config.json
🪣 存储桶：default
```

### 示例 2：上传图片到指定目录

```
/upload /images/2026/03/photo.jpg default
[附上照片]
```

### 示例 3：使用原文件名上传

```
/upload --original
[附上 report-2026-Q1.pdf]
```

文件将以 `report-2026-Q1.pdf` 上传。

### 示例 4：修改 CDN 域名

```
/qiniu-config set default.domain https://new-cdn.example.com
```

### 示例 5：添加生产环境存储桶

```
/qiniu-config set-bucket production {"accessKey":"AK_prod","secretKey":"SK_prod","bucket":"prod-assets","region":"z0","domain":"https://prod-cdn.example.com"}
```

然后上传到生产环境：

```
/upload /assets/main.js production
[附上 main.js]
```

### 示例 6：查看帮助

```
/qiniu-help
```

---

## 🔧 命令行使用

### 上传文件

```bash
# 使用原文件名
node scripts/upload-to-qiniu.js upload --file ./report.pdf

# 指定路径
node scripts/upload-to-qiniu.js upload --file ./report.pdf --key /docs/report.pdf

# 指定存储桶
node scripts/upload-to-qiniu.js upload --file ./report.pdf --key /docs/report.pdf --bucket production
```

### 配置管理

```bash
# 初始化配置
node scripts/upload-to-qiniu.js config init

# 查看配置
node scripts/upload-to-qiniu.js config list

# 修改配置
node scripts/upload-to-qiniu.js config set default.accessKey YOUR_KEY

# 添加存储桶
node scripts/upload-to-qiniu.js config set-bucket production '{"accessKey":"...","secretKey":"...","bucket":"prod","region":"z0","domain":"https://..."}'

# 重置配置
node scripts/upload-to-qiniu.js config reset
```

---

## 🚀 启动监听器

```bash
cd ~/.openclaw/workspace/skills/qiniu-uploader

# 前台运行
./scripts/start-listener.sh

# 后台运行
nohup node scripts/feishu-listener.js > listener.log 2>&1 &

# 查看日志
tail -f listener.log

# 停止服务
pkill -f feishu-listener
```

---

## 📊 文件结构

```
qiniu-uploader/
├── scripts/
│   ├── upload-to-qiniu.js    # 核心上传脚本（支持配置管理）
│   ├── feishu-listener.js    # 飞书监听器（v2）
│   ├── start-listener.sh     # 启动脚本
│   └── verify-url.js         # URL 验证
├── .env.example              # 环境变量模板
└── docs/
    ├── README.md             # 本文档
    ├── QUICKSTART.md         # 快速开始
    └── FEISHU_SETUP.md       # 飞书配置
```

---

## 🔍 故障排查

### 上传失败

```bash
# 检查配置
/qiniu-config list

# 手动测试上传
node scripts/upload-to-qiniu.js upload --file ./test.txt --key /test.txt
```

### 配置命令无响应

检查监听器日志：

```bash
tail -f listener.log
```

### 权限错误

确保飞书应用有以下权限：
- `im:message`
- `im:file`
- `im:message:send_as_bot`

---

## 💡 最佳实践

1. **路径规范**：建议使用 `/` 开头的路径，如 `/config/app/config.json`
2. **存储桶命名**：使用有意义的名称，如 `default`、`production`、`backup`
3. **定期轮换密钥**：使用 `/qiniu-config set` 定期更新 AccessKey/SecretKey
4. **备份配置**：重要配置修改前，先 `/qiniu-config list` 查看当前配置

---

## 🆘 获取帮助

- 在飞书中发送：`/qiniu-help`
- 查看文档：`cat README.md`
- 快速开始：`cat QUICKSTART.md`

---

**祝你使用愉快！** 🍙