openclaw-skill-qiniu/INTEGRATION.md

# 🍙 七牛云 Skill - OpenClaw 集成指南

## 概述

这是一个 OpenClaw Skill，用于在飞书/钉钉等聊天平台中处理七牛云文件上传和配置管理。

**特点：**
- ✅ 无需修改飞书开放平台配置
- ✅ 与 OpenClaw 无缝集成
- ✅ 保持现有机器人对话功能
- ✅ 支持文件上传、配置管理、多存储桶

---

## 文件结构

```
~/.openclaw/workspace/skills/qiniu-uploader/
├── SKILL.md                      # Skill 元数据和说明
├── package.json                  # Skill 配置
├── openclaw-processor.js         # OpenClaw 消息处理器 ⭐
├── README.md                     # 使用文档
├── scripts/
│   ├── upload-to-qiniu.js        # 七牛云上传脚本
│   └── feishu-listener.js        # 独立监听器（可选）
└── ...
```

---

## 集成方式

### 方式一：OpenClaw 自动加载（推荐）

OpenClaw 会自动扫描 `~/.openclaw/workspace/skills/` 目录下的 Skill。

**步骤：**

1. **确保 Skill 目录存在**
   ```bash
   ls ~/.openclaw/workspace/skills/qiniu-uploader/
   ```

2. **重启 OpenClaw Gateway**
   ```bash
   openclaw gateway restart
   ```

3. **测试**
   在飞书中发送：
   ```
   /qiniu-config list
   ```

---

### 方式二：手动注册

在 OpenClaw 配置中手动注册 Skill：

**编辑：** `~/.openclaw/openclaw.json`

添加 Skill 配置：

```json
{
  "skills": {
    "qiniu-uploader": {
      "enabled": true,
      "path": "~/.openclaw/workspace/skills/qiniu-uploader",
      "triggers": ["/upload", "/qiniu-config", "/qiniu-help"],
      "handler": "openclaw-processor.js"
    }
  }
}
```

然后重启 OpenClaw：

```bash
openclaw gateway restart
```

---

### 方式三：使用独立监听器（备选）

如果不想集成到 OpenClaw，可以使用独立监听器：

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

# 修改飞书请求地址到 3000 端口
# http://47.83.185.237:3000

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

---

## 使用方式

### 上传文件

```
/upload [目标路径] [存储桶名]
/upload --original [存储桶名]
[附上文件]
```

**示例：**
```
/upload /config/test.txt
[附上文件]

/upload --original
[附上文件]

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

### 配置管理

```
/qiniu-config list                        # 查看配置
/qiniu-config set <键> <值>               # 修改配置
/qiniu-config set-bucket <名> <JSON>      # 添加存储桶
/qiniu-config reset                       # 重置配置
```

**示例：**
```
/qiniu-config list
/qiniu-config set default.accessKey YOUR_KEY
/qiniu-config set default.domain https://cdn.example.com
/qiniu-config set-bucket production '{"accessKey":"...","secretKey":"...","bucket":"prod","region":"z0","domain":"https://prod-cdn.com"}'
```

### 查看帮助

```
/qiniu-help
```

---

## 配置说明

### 七牛云配置

位置：`~/.openclaw/credentials/qiniu-config.json`

```json
{
  "buckets": {
    "default": {
      "accessKey": "YO_Wi-aMubLmZJr_X5EFOI3WC2a9rfif1fBsS_pK",
      "secretKey": "NlcJJKlZjK6CF2irT3SIw5e4pMPeL4S3IHFRrMX7",
      "bucket": "daoqires",
      "region": "z0",
      "domain": "https://daoqi.daoqi888.cn"
    }
  }
}
```

### 飞书配置

位置：`~/.openclaw/workspace/skills/qiniu-uploader/openclaw-processor.js`

```javascript
feishu: {
  appId: 'cli_a92ce47b02381bcc',
  appSecret: 'WpCWhqOPKv3F5Lhn11DqubrssJnAodot'
}
```

或使用环境变量：

```bash
export FEISHU_APP_ID=cli_a92ce47b02381bcc
export FEISHU_APP_SECRET=WpCWhqOPKv3F5Lhn11DqubrssJnAodot
```

---

## 测试

### 测试配置命令

```bash
cd ~/.openclaw/workspace/skills/qiniu-uploader
node openclaw-processor.js --message '{"content":{"text":"/qiniu-config list"}}'
```

应该输出：
```json
{
  "handled": true,
  "reply": "📋 当前配置：..."
}
```

### 测试上传（需要实际文件）

```bash
echo "test" > /tmp/test.txt
node openclaw-processor.js --message '{"content":{"text":"/upload /test.txt"},"chat_id":"test"}'
```

### 在飞书中测试

1. 确保 OpenClaw Gateway 运行中
2. 在飞书中发送：`/qiniu-config list`
3. 应该收到配置信息回复

---

## 工作流程

```
飞书消息
   ↓
OpenClaw Gateway (17733 端口)
   ↓
识别七牛云命令 (/upload, /qiniu-config)
   ↓
调用 openclaw-processor.js
   ↓
处理命令
├─ 下载文件（如果有附件）
├─ 调用 upload-to-qiniu.js
├─ 上传到七牛云
├─ 刷新 CDN
└─ 返回结果
   ↓
OpenClaw 回复消息
```

---

## 优势

### 与独立监听器对比

| 特性 | OpenClaw Skill | 独立监听器 |
|------|---------------|-----------|
| 飞书配置修改 | ❌ 不需要 | ✅ 需要 |
| 架构统一性 | ✅ 统一 | ❌ 分散 |
| 消息上下文 | ✅ 完整 | ❌ 部分 |
| 维护成本 | ✅ 低 | ⭐ 中 |
| 实现复杂度 | ⭐ 中 | ✅ 低 |
| 可靠性 | ✅ 高 | ⭐ 中 |

---

## 故障排查

### Skill 未触发

1. 检查 OpenClaw 是否加载了 Skill：
   ```bash
   openclaw status
   ```

2. 检查 Skill 目录是否存在：
   ```bash
   ls ~/.openclaw/workspace/skills/qiniu-uploader/
   ```

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

### 上传失败

1. 检查七牛云配置：
   ```bash
   cat ~/.openclaw/credentials/qiniu-config.json
   ```

2. 手动测试上传脚本：
   ```bash
   node scripts/upload-to-qiniu.js config list
   ```

3. 查看 OpenClaw 日志：
   ```bash
   openclaw logs --tail 100
   ```

### 文件下载失败

1. 检查飞书 App ID/Secret：
   ```bash
   echo $FEISHU_APP_ID
   echo $FEISHU_APP_SECRET
   ```

2. 检查机器人权限（im:message, im:file）

---

## 总结

✅ **已完成：**
- OpenClaw Skill 处理器
- 七牛云上传脚本
- 配置管理功能
- 测试通过

✅ **优势：**
- 无需修改飞书配置
- 与 OpenClaw 无缝集成
- 保持现有机器人功能

🎯 **下一步：**
1. 重启 OpenClaw Gateway
2. 在飞书中测试 `/qiniu-config list`
3. 测试文件上传功能

---

**集成完成！** 🍙