介绍
# AIFS - AI File System
AIFS.space 是一个用于云文件存储的简单 HTTP REST API。使用它可以在会话之间持久化文件，在代理之间共享数据，或将用户内容存储在云端。
## 人类
用户应在 https://AIFS.Space 上注册并获取 API 密钥以提供给代理。
## 身份验证
需要在请求头中包含 API 密钥。请检查环境变量 (`AIFS_API_KEY`) 或用户配置中的密钥。
```bash Authorization: Bearer aifs_xxxxx ```
**密钥类型：** `admin` (完全权限), `read-write` (读写), `read-only` (只读), `write-only` (只写)
## 基础 URL
``` https://aifs.space ```
## 端点
### 列出文件
```bash curl -H "Authorization: Bearer $AIFS_API_KEY" https://aifs.space/api/files ```
返回：`{"files": [{"path": "notes/todo.txt", "size": 1024, "modifiedAt": "..."}]}`
### 读取文件
```bash # Full file curl -H "Authorization: Bearer $AIFS_API_KEY" "https://aifs.space/api/read?path=notes/todo.txt"
# Line range (1-indexed) curl -H "Authorization: Bearer $AIFS_API_KEY" "https://aifs.space/api/read?path=notes/todo.txt&start_line=5&end_line=10" ```
返回：`{"path": "...", "content": "...", "total_lines": 42, "returned_lines": 10}`
### 写入文件
自动创建目录（最大深度：20）。
```bash curl -X POST -H "Authorization: Bearer $AIFS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"path":"notes/new.txt","content":"Hello world"}' \ https://aifs.space/api/write ```
返回：`{"success": true, "path": "...", "size": 11, "lines": 1}`
### 修补文件（行替换）
更新特定行而无需重写整个文件。
```bash curl -X PATCH -H "Authorization: Bearer $AIFS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"path":"notes/todo.txt","start_line":5,"end_line":10,"content":"replacement"}' \ https://aifs.space/api/patch ```
返回：`{"success": true, "lines_before": 42, "lines_after": 38}`
### 删除文件
```bash curl -X DELETE -H "Authorization: Bearer $AIFS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"path":"notes/old.txt"}' \ https://aifs.space/api/delete ```
### 摘要（预览）
获取文件的前 500 个字符。
```bash curl -H "Authorization: Bearer $AIFS_API_KEY" "https://aifs.space/api/summary?path=notes/long.txt" ```
## 速率限制
每个密钥每分钟 60 次请求。请检查响应头：
- `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`
## 错误代码
| 代码 | 含义 | | -------------- | -------------------------- | | AUTH_REQUIRED | 未提供身份验证 | | AUTH_FAILED | 密钥无效 | | FORBIDDEN | 密钥类型缺少权限 | | RATE_LIMITED | 请求过多 | | NOT_FOUND | 文件不存在 | | INVALID_PATH | 路径遍历或路径无效 | | DEPTH_EXCEEDED | 目录深度超过 20 |
## 常见用法
### 持久化会话笔记
```bash # Save curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \ -d "{\"path\":\"sessions/$(date +%Y-%m-%d).md\",\"content\":\"# Session Notes\\n...\"}" \ https://aifs.space/api/write
# Retrieve curl -H "Authorization: Bearer $KEY" "https://aifs.space/api/read?path=sessions/2024-01-15.md" ```
### 按项目组织
``` projects/ ├── alpha/ │ ├── README.md │ └── notes.md └── beta/ └── spec.md ```
### 追加到日志（读取 + 写入）
```bash # Read existing EXISTING=$(curl -s -H "Authorization: Bearer $KEY" "https://aifs.space/api/read?path=log.txt" | jq -r .content)
# Append and write back curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \ -d "{\"path\":\"log.txt\",\"content\":\"$EXISTING\\n$(date): New entry\"}" \ https://aifs.space/api/write ```