# ClawDrive (clawdrive.qname.com) — Agent 接入指南 / Agent Integration Skill

图床服务 API，供 AI agent / 自动化系统集成：上传图片拿到可公开访问的 CDN URL。
Image hosting API for agents: upload an image, get a public URL back.

Base URL: `https://clawdrive.qname.com`
OpenAPI 规格: `https://clawdrive.qname.com/openapi.yaml`

---

## 1. 获取凭证 (Get Credentials)

两种方式，二选一：

### A. 用户后台创建（推荐，免付费）
用户登录 `https://clawdrive.qname.com/dashboard/keys` 创建密钥，把以下三个值交给 agent：
- `accessKey` (`ak_...`)
- `secretKey` (`sk_...`，备用)
- `signatureKey` (64 位 hex，**签名用，必须保密**)

### B. Agent 自助注册（BTC 付费，无需人工）
```bash
# 1) 注册，拿 BTC 收款地址
curl -X POST https://clawdrive.qname.com/api/agent/register \
  -H 'Content-Type: application/json' \
  -d '{"keyName": "my-agent"}'
# → { "data": { "btcAddress": "bc1...", "minPaymentSat": 10000, ... } }

# 2) 向该地址支付 >= 0.0001 BTC (10000 satoshi)

# 3) 轮询激活状态，支付确认后返回凭证
curl 'https://clawdrive.qname.com/api/agent/status?address=bc1...'
# → { "status": "active", "accessKey": "ak_...", "signatureKey": "...", "quotaLimit": "..." }
```
费率：每 0.0001 BTC ≈ 2000 MB 永久配额。

---

## 2. 认证：HMAC 签名 (Authentication)

每个请求带 3 个 header：

| Header | 说明 |
|---|---|
| `X-Access-Key` | accessKey |
| `X-Timestamp` | 当前毫秒时间戳（与服务器偏差须 < 5 分钟）|
| `X-Signature` | `HMAC-SHA256(signatureKey, "{METHOD}\n{path}\n{timestamp}")` 的 hex |

注意：
- `{METHOD}` 大写，如 `POST`
- `{path}` 仅路径，不含域名和 query，如 `/api/files/upload`
- 签名内容是三行用 `\n` 拼接：`POST\n/api/files/upload\n1727000000000`

### Node.js 签名示例
```js
const crypto = require('crypto')

function sign(method, path, signatureKey) {
  const timestamp = Date.now().toString()
  const signature = crypto
    .createHmac('sha256', signatureKey)
    .update(`${method}\n${path}\n${timestamp}`)
    .digest('hex')
  return { 'X-Access-Key': ACCESS_KEY, 'X-Timestamp': timestamp, 'X-Signature': signature }
}
```

### Python 签名示例
```python
import hmac, hashlib, time

def sign(method, path, access_key, signature_key):
    ts = str(int(time.time() * 1000))
    sig = hmac.new(signature_key.encode(), f"{method}\n{path}\n{ts}".encode(), hashlib.sha256).hexdigest()
    return {"X-Access-Key": access_key, "X-Timestamp": ts, "X-Signature": sig}
```

---

## 3. 核心接口 (Endpoints)

### 上传文件 — `POST /api/upload`
`multipart/form-data`，字段名 `file`。按 Content-Type 分流：
- `image/*`：自动转 WebP（最长边 5000px, q75）+ 400px 缩略图
- `audio/mpeg`(mp3) / `audio/mp4`(m4a) / `audio/ogg` / `video/mp4`：原样存储，不转码不压缩
- MD5 秒传去重对所有类型生效；单文件上限 10MB

```bash
TS=$(date +%s%3N)
SIG=$(printf "POST\n/api/upload\n$TS" | openssl dgst -sha256 -hmac "$SIGNATURE_KEY" | cut -d' ' -f2)
curl -X POST https://clawdrive.qname.com/api/upload \
  -H "X-Access-Key: $ACCESS_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -F "file=@photo.png"
```
响应：
```json
{ "success": true, "data": { "id": "...", "url": "https://img.qname.com/u/...webp", "thumbnail": "https://img.qname.com/t/...webp", "size": 12345, "width": 800, "height": 600 } }
```
`data.url` 即公开可访问的地址，可直接发给任何人 / 嵌入 markdown / 作 `<audio>` `<video>` 的 `src`。
音频/视频无缩略图，`thumbnail` 为 `null`。

伺服特性：返回正确的 Content-Type，支持 **Range 请求**（`Accept-Ranges: bytes`，206 Partial Content，`<audio>` 可拖动进度条），`Cache-Control: immutable`（内容 MD5 寻址），`Access-Control-Allow-Origin: *`（Web Audio API 可用）。

### 上传任意文件 — `POST /api/files/upload`
不做格式转换，原样存储。`multipart/form-data`，字段 `file`。

### 列出文件 — `GET /api/files?page=1&limit=50&keyword=xxx`
返回 `data[].cdnUrl / thumbUrl / fileSize / createdAt`。

### 删除文件 — `DELETE /api/files/{id}`

---

## 4. 错误码 (Errors)

| HTTP | 含义 |
|---|---|
| 400 | 参数错误（缺文件 / 文件过大）|
| 401 | 签名错误 / 时间戳超窗 / key 过期 |
| 403 | 配额不足（需 BTC 充值或联系管理员）|
| 429 | 请求过于频繁，按响应头 `Retry-After`（秒）精确退避重试 |

上传限流（按用户）：图片 60 次/分钟，音视频 300 次/分钟（分开计数）。429 响应带 `Retry-After` 头和 `retryAfter` 字段。

## 5. 集成要点 (Rules)

1. `signatureKey` 永不出现在网络请求中，只用于本地计算签名 — 不要写进日志。
2. 时间戳用毫秒；服务器允许 ±5 分钟偏差，注意校时。
3. 上传成功以 `success: true` 为准；MD5 命中秒传也返回已有 URL，属正常。
4. 返回的 URL 永久有效（除非文件被删除），带 1 年缓存头，可作长期引用。