# 🍙 七牛云自动上传 v2 - 配置总览

## 📁 文件结构

```
qiniu-uploader/
├── CHEATSHEET.md           # ⚡ 快速参考卡片
├── README.md               # 📖 完整使用指南
├── UPGRADE.md              # 🔄 更新说明
├── FEISHU_SETUP.md         # 📘 飞书开放平台配置
├── QUICKSTART.md           # 🏃 5 分钟快速开始
├── SKILL.md                # 技能元数据
├── INDEX.md                # 本文件（总览）
├── .env.example            # 环境变量模板
└── scripts/
    ├── upload-to-qiniu.js  # ☁️ 上传脚本（支持配置管理）
    ├── feishu-listener.js  # 👂 飞书监听器（v2）
    ├── start-listener.sh   # 🚀 启动脚本
    └── verify-url.js       # ✅ URL 验证
```

## ✨ v2 新功能

1. **指定上传路径** - `/upload /config/test/file.txt`
2. **使用原文件名** - `/upload --original`
3. **聊天命令配置** - `/qiniu-config set key value`
4. **多存储桶管理** - `/qiniu-config set-bucket name json`

## 🚀 快速开始

### 1. 配置七牛云

```bash
# 配置文件已存在，可直接使用
# 或在飞书中修改配置
/qiniu-config list
```

### 2. 启动监听器

```bash
cd ~/.openclaw/workspace/skills/qiniu-uploader
./scripts/start-listener.sh
```

### 3. 测试上传

在飞书中发送：

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

## 📋 指令速查

### 上传指令

```
/upload                      # 使用原文件名
/upload --original           # 同上
/upload /path/to/file.txt    # 指定路径
/upload /path/to/file bucket # 指定路径和存储桶
```

### 配置指令

```
/qiniu-config list                        # 查看配置
/qiniu-config set default.accessKey XXX   # 修改配置
/qiniu-config set-bucket prod '{...}'     # 添加存储桶
/qiniu-config reset                       # 重置配置
/qiniu-help                               # 查看帮助
```

## 🔑 配置项

| 配置项 | 说明 | 示例 |
|--------|------|------|
| `default.accessKey` | 访问密钥 | `7hO...` |
| `default.secretKey` | 密钥 | `xYz...` |
| `default.bucket` | 存储桶名 | `my-files` |
| `default.region` | 区域 | `z0`(华东) |
| `default.domain` | CDN 域名 | `https://cdn.com` |

## 🎯 使用场景

### 上传配置文件

```
/upload /config/app/config.json
[文件]
```

### 上传图片

```
/upload /images/2026/photo.jpg
[文件]
```

### 修改配置

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

### 添加存储桶

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

## 📊 配置检查

```bash
# 查看配置文件
cat ~/.openclaw/credentials/qiniu-config.json

# 在飞书中查看
/qiniu-config list

# 检查监听器
ps aux | grep feishu-listener

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

## 🔗 文档导航

- **快速参考** → `CHEATSHEET.md`
- **完整指南** → `README.md`
- **快速开始** → `QUICKSTART.md`
- **飞书配置** → `FEISHU_SETUP.md`
- **更新说明** → `UPGRADE.md`

## 💡 提示

1. **路径规范**：建议使用 `/` 开头，如 `/config/file.txt`
2. **原文件名**：不指定路径时自动使用原文件名
3. **配置安全**：使用聊天命令修改，避免明文传输
4. **多环境**：使用不同存储桶区分环境（dev/staging/prod）

## 🆘 获取帮助

- 飞书中：`/qiniu-help`
- 查看文档：`cat CHEATSHEET.md`
- 故障排查：查看 `README.md` 故障排查章节

---

**配置完成！开始使用吧！** 🍙