# Fresco API 参考

Fresco 私人 AI 网页托管服务的全部接口，供 AI Agent 与脚本集成使用。

- **Base URL**: `https://longmarch.cloud/e`
- 页面托管地址形式：`https://longmarch.cloud/e/{slug}`

---

### 注册与开始使用（新用户）

Fresco 对**所有互联网用户开放**：访问 `https://longmarch.cloud/e/register` 免费注册。

1. 用**邮箱 + 密码**注册，立即获得你的专属 **API Key**（⚠️ 请立即保存，页面关闭后无法再次查看完整 Key，切勿泄漏）
2. 把 API Key 交给 AI Agent（把下面提示词模板发给任意 Agent 即可）：

```
你是我的网页发布助手。请用以下凭据把我的内容发布到 Fresco 网页托管：
API Key（Bearer 认证）：<你的Key>
接口地址：https://longmarch.cloud/e/api/deploy
发布方法：POST 接口地址，请求头 Authorization: Bearer <你的Key> 与 Content-Type: application/json，
请求体 {"slug":"页面地址(英文)","title":"标题","html":"完整HTML内容"}（可选 description/image；slug 已存在需加 "overwrite": true）
页面地址：https://longmarch.cloud/e/<slug>。完成后把页面地址告诉我。
```

3. **后续所有管理在 Agent 中进行**：页面修改/暂停/删除/微调/限额，都由 Agent 通过 API 完成；你也可以用邮箱+密码登录管理台（`/e/setting`）手动管理自己的页面
4. 每个用户只能管理自己的页面（互相隔离）；管理员拥有全局管理权限

#
### ① 管理认证（邮箱 + 密码）

访问 `https://longmarch.cloud/e/setting` 登录管理台，获得会话 Cookie，管理**自己的**页面与密钥。

### ② Agent 认证（API Key）

Agent 部署用，无需登录密码。注册时获得 API Key，请求头携带：

```
Authorization: Bearer fr_xxxxxxxxxxxxxxxx
```

**隔离规则**：每个密钥只能管理自己上传的页面（owner 隔离），操作其他密钥的页面返回 `403`。

## 认证方式

两种认证，互不混用：

### ① 管理认证（Cookie 会话）

管理台 `/setting` 登录后获得会话 Cookie，用于完整管理操作（页面增删改、密钥管理、改密码）。

```
POST /api/login
Content-Type: application/json
{"password": "管理密码"}
```
成功返回 `{"ok": true}` 并 `Set-Cookie: fr_session=...`，后续请求携带该 Cookie。

### ② Agent 认证（API Key）

Agent 部署用，无需登录密码。在管理台「API Key」区块创建密钥，请求头携带：

```
Authorization: Bearer fr_xxxxxxxxxxxxxxxx
```

**隔离规则**：每个密钥只能管理自己上传的页面（owner 隔离），操作其他密钥的页面返回 `403`。

---

## Agent 部署接口（Bearer 认证）

### 上传 / 更新页面

```
POST /api/deploy
Authorization: Bearer fr_xxxx
Content-Type: application/json
```

请求体：

| 字段 | 类型 | 说明 |
|------|------|------|
| `slug` | string | 地址（1-64 位字母/数字/连字符/下划线/点号，保留字除外） |
| `title` | string | 标题（可选，缺省用 slug） |
| `html` | string | 完整 HTML 内容 |
| `overwrite` | bool | slug 已存在且归属本密钥时，传 `true` 覆盖更新（可选，默认 `false`） |
| `danmaku_enabled` | bool | 是否开启弹幕（可选，默认 true） |
| `description` | string | 页面描述（可选，≤200 字；微信等分享卡片的摘要） |
| `image` | string | 分享卡片封面图 URL（可选，https 图片；缺省用 Fresco 默认图） |

**slug 冲突规则**：地址已存在时默认返回 `409` 错误（写明原因）；只有传 `"overwrite": true` 且该地址归属本密钥时才覆盖更新。操作其他密钥的地址永远返回 `403`。

curl 示例：

```bash
curl -X POST https://longmarch.cloud/e/api/deploy \
  -H "Authorization: Bearer fr_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"slug":"my-page","title":"标题","html":"<h1>内容</h1>"}'
```

响应：

```json
{"ok": true, "page": {"id": "...", "slug": "my-page", "owner": "workbuddy"}, "action": "created"}
```
（`action` 为 `created` 或 `updated`）

错误响应（`err` 字段写明原因）：

```json
HTTP 409  {"ok": false, "err": "地址 my-page 已存在（本密钥托管）。如需覆盖更新，请在请求体加 \"overwrite\": true"}
HTTP 403  {"ok": false, "err": "地址 my-page 已被其他密钥（xxx）占用，无权覆盖"}
HTTP 400  {"ok": false, "err": "页面数超限：该密钥最多托管 5 个页面，当前已有 5 个"}
HTTP 400  {"ok": false, "err": "大小超限：该密钥托管总大小上限 100 MB，当前 98.12 MB，本次 1024.00 KB 将超出"}
```

### 列出本密钥的页面

```
GET /api/pages
Authorization: Bearer fr_xxxx
```

返回 `{"ok": true, "pages": [ ... ]}`（仅包含该密钥自己的页面）。

### 删除本密钥的页面

```
POST /api/deploy/delete
Authorization: Bearer fr_xxxx
Content-Type: application/json
{"slug": "my-page"}
```

---

## 管理接口（Cookie 认证）

以下接口需先 `POST /api/login` 获得 Cookie，均需管理权限。

| 方法 | 路径 | 说明 | 请求体 |
|------|------|------|--------|
| GET | `/api/pages` | 列出全部页面 | - |
| POST | `/api/pages` | 手动新建页面（owner=admin，地址冲突报错） | `{title, slug, html}` |
| POST | `/api/pages/delete` | 删除页面 | `{"id": "..."}` |
| POST | `/api/pages/toggle` | 暂停 / 恢复 | `{"id": "..."}` |
| POST | `/api/pages/rename` | 修改地址 | `{"id": "...", "slug": "新地址"}` |
| POST | `/api/pages/password` | 设置 / 清除页面访问密码 | `{"id": "...", "password": "访问密码"}`（留空则清除） |

### 密钥管理（Cookie）

| 方法 | 路径 | 说明 | 请求体 |
|------|------|------|--------|
| GET | `/api/keys` | 列出所有 API Key（含限额字段） | - |
| POST | `/api/keys` | 新建密钥（可带 `max_pages` / `max_size_mb`） | `{"name": "agent-1"}` |
| POST | `/api/keys/limits` | 设置密钥限额 | `{"key": "fr_...", "max_pages": 5, "max_size_mb": 100}` |
| POST | `/api/keys/rename` | 重命名密钥 | `{"key": "fr_...", "name": "新名称"}` |
| POST | `/api/keys/delete` | 删除密钥 | `{"key": "fr_..."}` |

### 密钥限额规则

每个 API Key 可单独设置两类上限（`0` 或不设置 = 无上限）：

- **页面数上限** `max_pages`：该密钥托管页面的最大数量；
- **总大小上限** `max_size_mb`（MB）：该密钥全部页面内容大小的总和上限。

Agent 通过 `/api/deploy` 新建页面时若将超过任一上限，返回 `400` 并在 `err` 中写明原因（含上限值与当前用量）；覆盖更新（`overwrite: true`）同样受总大小上限约束。限额可在管理台「API Key」列表的「限额」按钮中可视化设置。

### 修改管理密码（Cookie）

```
POST /api/password
{"old": "旧密码", "new": "新密码"}
```
修改后新密码会邮件通知给已配置的收件人。

---

### 分享卡片（og meta）

每个 HTML 托管页面自动注入微信/QQ 等社交平台识别的分享卡片 meta，粘贴链接即显示卡片。

| og 标签 | 取值规则 |
|------|------|
| `og:title` | 页面标题（deploy 的 `title` 字段） |
| `og:description` | deploy 的 `description` 字段；未设置时自动提取页面正文前 60 字 |
| `og:image` | deploy 的 `image` 字段（https 图片地址）；未设置时用 Fresco 默认图（"Fr" 字样品牌图） |
| `og:url` / `og:type` | 自动生成（页面地址 / website） |

规范：页面自带 `og:title` 时不重复注入（尊重页面自定义）；`og:image` 建议 ≥300×300 的 https 图片；微信对同一 URL 的抓取结果有缓存，修改 meta 后需等缓存过期或加 `?v=x` 参数验证。

### 人工微调（网页编辑器）

Agent 部署的页面可以交给「人」直接在浏览器里微调，无需重新生成整页。两种入口：

**① 单次微调地址（Agent 生成，交给用户）** — 建议 Agent 告知用户可以人工微调修改：

```
GET /api/editor/token?slug=my-page
Authorization: Bearer fr_xxxx
```

为**本密钥托管**的页面生成单次微调地址，响应：

```json
{"ok": true, "token": "...", "url": "https://longmarch.cloud/e/editor?t=...", "expires_hours": 24, "hint": "微调地址 24 小时内有效，保存一次后自动失效"}
```

- 地址 24 小时内有效，**保存一次后自动失效**
- 错误：`403` 页面不属于此密钥；`404` 页面不存在；`401` 密钥无效

**② 管理台编辑（Cookie）**：管理台页面列表每行「微调」按钮（`/editor?id=…`），可反复保存；每次保存自动留存**最近 5 个历史版本**（超出自动覆盖最早的），支持一键还原。

编辑器为 Monaco（VS Code 内核）：左编辑 HTML 源码、右实时预览，桌面/平板/手机宽度切换，Ctrl+S 保存。

## 页面访问密码（公开）

设置了访问密码的页面，访问时需先解锁：

```
POST /api/unlock
Content-Type: application/json
{"slug": "my-page", "password": "访问密码"}
```

验证通过后 `Set-Cookie: fr_access=...`（24 小时内免重复输入），随后即可访问该页面。

---

## 弹幕（浏览者互动）

每个 HTML 托管页面都自带弹幕系统：页面底部有发送栏（可拖动），浏览者可发送、开关弹幕。

### 获取某页面弹幕（公开）

```
GET /api/danmaku?slug=my-page
```

返回 `{"ok": true, "danmaku": [{"id":"...","text":"...","color":"#fff","ts":...}]}`（最近 200 条）。

### 发送弹幕（公开）

```
POST /api/danmaku
Content-Type: application/json
{"slug": "my-page", "text": "你好", "color": "#ffffff"}
```

- `text` 最长 100 字符；`color` 为 `#rrggbb` 格式（缺省 `#ffffff`）。
- 每页最多保留最近 500 条。

### 弹幕管理（Cookie）

| 方法 | 路径 | 说明 | 请求体 |
|------|------|------|--------|
| GET | `/api/danmaku/all` | 列出所有弹幕（平铺，按时间倒序） | - |
| POST | `/api/danmaku/delete` | 删除单条弹幕 | `{"id": "..."}` |
| POST | `/api/danmaku/clear` | 清空某页面全部弹幕 | `{"slug": "my-page"}` |

---

## 约束

- **slug 规则**：1-64 位，字母/数字/连字符/下划线/点号开头不能是保留字。保留字：`setting`、`api`、`login`、`logout`、`unlock`、`deploy`、`keys`、`stats`、`docs`、`docs.md`、`fresco`、`index.html`、`favicon.ico`、`robots.txt`（运营地址可在管理台「运营地址保留」中逐个释放）。
- **无全局大小限制**：上传的 HTML 无全局大小上限（单个密钥可设置限额，见上文）。
- **无访问限制**：不限制访问次数。
- **弹幕**：仅注入 HTML 页面，`.md` 文档不注入。