# 七牛云上传 Skill - 安装指南

## 📦 快速安装

### 1. 复制 Skill 目录

```bash
# 从源服务器复制
scp -r user@source-server:~/.openclaw/workspace/skills/qiniu-uploader \
  ~/.openclaw/workspace/skills/
```

### 2. 配置七牛云凭证

```bash
mkdir -p ~/.openclaw/credentials/

cat > ~/.openclaw/credentials/qiniu-config.json << 'EOF'
{
  "buckets": {
    "default": {
      "accessKey": "YOUR_ACCESS_KEY_HERE",
      "secretKey": "YOUR_SECRET_KEY_HERE",
      "bucket": "your-bucket-name",
      "region": "z2",
      "domain": "https://your-cdn-domain.com"
    }
  }
}
EOF
```

### 3. 获取七牛云密钥

访问七牛云控制台获取密钥：
- 网址：https://portal.qiniu.com/user/key
- 创建存储桶：https://portal.qiniu.com/kodo/bucket

### 4. 重启 OpenClaw Gateway

```bash
openclaw gateway restart
```

### 5. 验证安装

在飞书或其他聊天平台发送：

```
/qiniu-config list
```

应该显示配置信息。

---

## 📋 文件结构

```
qiniu-uploader/
├── scripts/
│   ├── upload-to-qiniu.js      # 核心上传脚本
│   ├── debug-upload.js         # 调试工具
│   ├── check-bucket-override.js # 存储桶检查
│   └── update-bucket-setting.js # 设置更新
├── openclaw-processor.js       # OpenClaw 处理器
├── openclaw-handler.js         # HTTP 处理器
├── SKILL.md                    # Skill 说明文档
├── INSTALL.md                  # 本文件
└── README.md                   # 完整文档
```

---

## 🔧 配置说明

### qiniu-config.json

| 字段 | 说明 | 示例 |
|------|------|------|
| `accessKey` | 七牛云访问密钥 | `YO_Wi-aMubLmZJr_X5EFOI3WC2a9rfif1fBsS_pK` |
| `secretKey` | 七牛云密钥 | `NlcJ...rMX7` |
| `bucket` | 存储桶名称 | `daoqires` |
| `region` | 区域代码 | `z0`=华东，`z1`=华北，`z2`=华南 |
| `domain` | CDN 域名 | `https://daoqi.daoqi888.cn` |

### 区域代码

| 代码 | 区域 |
|------|------|
| `z0` | 华东（浙江） |
| `z1` | 华北（河北） |
| `z2` | 华南（广东） |
| `na0` | 北美 |
| `as0` | 东南亚 |

---

## 📤 使用方式

### 飞书/聊天平台

```
/upload /path/to/file.txt
/u /path/to/file.txt        # 快捷命令
/upload --original          # 使用原文件名
/qiniu-config list          # 查看配置
```

### 命令行

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

# 上传文件
node scripts/upload-to-qiniu.js upload \
  --file ./test.txt \
  --key /test/test.txt \
  --bucket default

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

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

---

## ✅ 功能特性

- ✅ 支持覆盖上传同名文件
- ✅ 支持指定上传路径
- ✅ 支持多存储桶配置
- ✅ 自动刷新 CDN 缓存
- ✅ 显示实际存储桶名称
- ✅ 临时文件自动清理
- ✅ 支持 `/upload` 和 `/u` 命令

---

## 🐛 故障排查

### 上传失败

1. 检查凭证配置：`/qiniu-config list`
2. 检查 AccessKey/SecretKey 是否正确
3. 检查存储桶名称和区域是否匹配

### 无法覆盖上传

确保上传凭证的 scope 参数包含 key（已修复）

### Emoji 显示问题

某些 emoji 在某些平台可能不显示，可以修改代码中的 emoji

---

## 📞 需要帮助？

查看完整文档：`README.md`

快速参考：`CHEATSHEET.md`

---

## 📝 版本信息

- **Skill 版本**: 1.1.0
- **兼容 OpenClaw**: 2026.3.2+
- **七牛云 API**: 表单上传 v2