# 下载中心文件管理 API 使用说明

本文档说明如何通过 API 远程编辑下载目录中的文件。

---

## API 端点

基础地址: `https://www.wubug.cc`

### 1. 获取可编辑文件列表

```bash
GET /api/downloads/editable
```

**响应示例：**
```json
{
  "success": true,
  "files": [
    {
      "name": "OpenClaw安装指南.txt",
      "size": 11255,
      "mtime": "2026-03-20T02:54:00.000Z",
      "editable": true
    }
  ]
}
```

### 2. 读取文件内容

```bash
GET /api/downloads/file/{文件名}
```

**响应示例：**
```json
{
  "success": true,
  "filename": "OpenClaw安装指南.txt",
  "content": "# OpenClaw 安装指南...",
  "mtime": "2026-03-20T02:54:00.000Z"
}
```

### 3. 更新文件内容

```bash
PUT /api/downloads/file/{文件名}
Content-Type: application/json

Body:
{
  "content": "更新后的文件内容..."
}
```

**响应示例：**
```json
{
  "success": true,
  "message": "文件已保存",
  "filename": "OpenClaw安装指南.txt",
  "mtime": "2026-03-20T03:00:00.000Z"
}
```

---

## 允许编辑的文件类型

- `.txt` - 文本文件
- `.md` - Markdown 文档
- `.json` - JSON 配置
- `.yml` / `.yaml` - YAML 配置
- `.html` - HTML 文件

---

## 使用示例（curl）

### 读取文件

```bash
curl "https://www.wubug.cc/api/downloads/file/OpenClaw安装指南.txt"
```

### 更新文件

```bash
curl -X PUT "https://www.wubug.cc/api/downloads/file/OpenClaw安装指南.txt" \
  -H "Content-Type: application/json" \
  -d '{"content": "# 新的内容..."}'
```

---

## 使用示例（Python）

```python
import requests

API_BASE = "https://www.wubug.cc"

# 读取文件
def read_file(filename):
    resp = requests.get(f"{API_BASE}/api/downloads/file/{filename}")
    return resp.json()

# 更新文件
def update_file(filename, content):
    resp = requests.put(
        f"{API_BASE}/api/downloads/file/{filename}",
        headers={"Content-Type": "application/json"},
        json={"content": content}
    )
    return resp.json()

# 使用
result = read_file("OpenClaw安装指南.txt")
print(result["content"])

update_file("OpenClaw安装指南.txt", "# 更新后的内容")
```

---

## 安全特性

1. **自动备份** - 每次修改自动创建备份文件（保留最近 5 个）
2. **文件类型限制** - 只允许编辑文本类文件
3. **路径安全** - 防止目录遍历攻击

---

## 注意事项

1. 修改文件前建议先读取当前内容
2. 文件编码统一为 UTF-8
3. 大文件（>1MB）建议分段处理
4. 备份文件格式: `原文件名.bak.时间戳`

---

> 最后更新: 2026-03-20
> 问题反馈: 联系服务器管理员