openclaw-skill-qiniu/UPGRADE.md

# 🍙 七牛云自动上传 v2 - 更新说明

## 🎉 新增功能

### 1. 支持指定上传路径

现在可以在飞书聊天中指定文件上传到存储桶的具体路径：

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

文件将上传到七牛云：`bucket/config/test/test.txt`

### 2. 使用原文件名上传

支持保留原始文件名：

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

或直接：

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

### 3. 聊天命令动态配置

无需编辑配置文件，在飞书中直接修改七牛云配置：

```
/qiniu-config list
/qiniu-config set default.accessKey YOUR_KEY
/qiniu-config set default.domain https://cdn.example.com
```

### 4. 多存储桶管理

动态添加和管理多个存储桶：

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

---

## 📋 完整指令列表

### 上传指令

| 指令 | 说明 |
|------|------|
| `/upload` | 使用原文件名上传到 default 存储桶 |
| `/upload --original [bucket]` | 使用原文件名，可指定存储桶 |
| `/upload 路径 [bucket]` | 上传到指定路径 |

### 配置指令

| 指令 | 说明 |
|------|------|
| `/qiniu-config list` | 查看当前配置 |
| `/qiniu-config set <键> <值>` | 修改配置项 |
| `/qiniu-config set-bucket <名> <JSON>` | 添加/修改存储桶 |
| `/qiniu-config reset` | 重置配置 |
| `/qiniu-help` | 查看帮助 |

---

## 🔑 可配置项

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

# 修改 AccessKey
/qiniu-config set default.accessKey YOUR_ACCESS_KEY

# 修改 SecretKey
/qiniu-config set default.secretKey YOUR_SECRET_KEY

# 修改存储桶名称
/qiniu-config set default.bucket my-bucket

# 修改区域
/qiniu-config set default.region z0

# 修改 CDN 域名
/qiniu-config set default.domain https://cdn.example.com
```

---

## 🎯 使用示例

### 场景 1：上传配置文件到指定目录

```
/upload /config/app/config.json
[附上 config.json]
```

回复：
```
✅ 上传成功！
📦 文件：config/app/config.json
🔗 链接：https://cdn.example.com/config/app/config.json
```

### 场景 2：批量上传不同环境的配置

```
# 上传到开发环境
/upload /config/dev.json dev
[文件]

# 上传到生产环境
/upload /config/prod.json production
[文件]
```

### 场景 3：动态修改配置

```
# 查看当前配置
/qiniu-config list

# 修改 CDN 域名
/qiniu-config set default.domain https://new-cdn.com

# 添加新的存储桶
/qiniu-config set-bucket backup '{"accessKey":"...","secretKey":"...","bucket":"backup","region":"z1","domain":"https://backup-cdn.com"}'
```

---

## 📁 更新的文件

```
scripts/
├── upload-to-qiniu.js    # ⭐ 重写，支持配置管理和路径
└── feishu-listener.js    # ⭐ 重写，支持聊天命令

docs/
├── README.md             # ⭐ 更新使用指南
├── CHEATSHEET.md         # ✨ 新增快速参考
└── UPGRADE.md            # ✨ 本文档（更新说明）
```

---

## 🚀 升级步骤

如果你已经安装了 v1 版本：

### 1. 备份现有配置

```bash
cp ~/.openclaw/credentials/qiniu-config.json \
   ~/.openclaw/credentials/qiniu-config.json.bak
```

### 2. 更新脚本

脚本已自动更新，无需手动操作。

### 3. 重启监听器

```bash
# 停止旧版本
pkill -f feishu-listener

# 启动新版本
cd ~/.openclaw/workspace/skills/qiniu-uploader
./scripts/start-listener.sh
```

### 4. 测试新功能

```
# 在飞书中测试
/qiniu-config list
/upload /test/v2-upgrade.txt
[附上文件]
```

---

## 🔄 兼容性说明

### ✅ 向后兼容

- 旧的上传指令仍然有效
- 现有配置文件格式兼容
- 无需重新配置

### ⚠️ 行为变化

1. **默认使用原文件名**：`/upload` 不再要求指定文件名
2. **路径支持**：现在支持 `/` 开头的完整路径
3. **配置管理**：新增聊天命令配置功能

---

## 💡 最佳实践

### 1. 路径规范

```
✅ 推荐：/config/app/config.json
✅ 推荐：/images/2026/03/photo.jpg
❌ 避免：config/app/config.json (缺少前导 /)
```

### 2. 存储桶命名

```
default    - 默认存储桶
production - 生产环境
staging    - 测试环境
backup     - 备份存储
```

### 3. 安全建议

- 定期轮换 AccessKey/SecretKey
- 使用 `/qiniu-config set` 命令修改，避免明文传输
- 不要在不安全的渠道分享配置命令

---

## 🆘 故障排查

### 问题：配置命令无响应

```bash
# 检查监听器状态
ps aux | grep feishu-listener

# 查看日志
tail -f listener.log
```

### 问题：上传路径不正确

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

### 问题：配置丢失

```bash
# 重置配置
/qiniu-config reset

# 或手动初始化
node scripts/upload-to-qiniu.js config init
```

---

## 📞 获取帮助

- 飞书中：`/qiniu-help`
- 快速参考：`cat CHEATSHEET.md`
- 完整文档：`cat README.md`
- 更新说明：`cat UPGRADE.md`（本文档）

---

**升级完成！享受更强大的功能！** 🍙