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
```

---

## 🚀 部署方式

### 方式一：OpenClaw 集成（推荐）

1. 复制 skill 到 OpenClaw：
```bash
cp -r qiniu-uploader ~/.openclaw/workspace/skills/
```

2. 配置七牛云凭证：
```bash
cp qiniu-config.example.json ~/.openclaw/credentials/qiniu-config.json
nano ~/.openclaw/credentials/qiniu-config.json
```

3. 重启 OpenClaw Gateway：
```bash
openclaw gateway restart
```

4. 在飞书中测试：
```
/qiniu-config list
```

### 方式二：独立监听器

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

# 配置环境变量
cp .env.example .env
nano .env  # 编辑飞书凭证

# 启动监听器
node scripts/feishu-listener.js

# 或使用 PM2 后台运行
pm2 start scripts/feishu-listener.js --name qiniu-uploader
```

**注意：** 独立监听器需要在飞书开放平台配置事件订阅地址。

---

## 📊 文件结构

```
qiniu-uploader/
├── scripts/
│   ├── upload-to-qiniu.js      # 核心上传脚本
│   ├── feishu-listener.js      # 飞书独立监听器
│   └── update-bucket-setting.js # 存储桶设置工具
├── openclaw-processor.js       # OpenClaw 处理器
├── openclaw-handler.js         # HTTP 处理器
├── deploy.sh                   # 部署脚本
├── .env.example                # 环境变量模板
├── qiniu-config.example.json   # 配置示例
└── README.md                   # 本文档
```

---

## 🔍 故障排查

### 上传失败

1. 检查配置：
```bash
/qiniu-config list
```

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

3. 检查实际存储桶名称：
```bash
# 回复中的"存储桶"应显示实际桶名（如 daoqires），而不是配置别名（如 default）
```

### 配置命令无响应

1. 检查 OpenClaw Gateway 状态：
```bash
openclaw gateway status
```

2. 查看日志：
```bash
tail -f /tmp/openclaw/openclaw-*.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`

---

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