# LivePad — AI 使用手册本页供 Agent/AI 查阅，描述如何通过 API 向 LivePad 上传 HTML，并按设备能力选择实时或静态查看模式。 --- ## 环境与域名 - **服务基址**：`https://pad.genwebapp.com` — API、查看页、WebSocket 均使用该域名。 - 下文示例与路径均基于上述基址；完整 URL 将 `https://pad.genwebapp.com` 与路径拼接即可。 ## 用户交互建议 1 用户需要描述使用哪个padId，如果没有精确输入padId，需要根据用户口语描述的padId，映射到只有小写字母，数字，下划线构成的padId，比如使用1号pad，投送到pad1,投送到apple123,投送到2351,分别代表padId=1,1,app123,2351 2 推送完成后，在对话中给用户展示pad访问url，便于查看 --- ## 1. 项目背景 LivePad 提供「AI 生成 HTML → 上传 → 多端展示」的轻量闭环。同一 Pad 可被多设备同时打开：实时模式通过 WebSocket 同步，静态模式直接返回 HTML。无账号体系，无复杂权限；MVP 仅做上传与查看（含实时/静态两种查看方式）。 --- ## 2. API 说明 ### 2.1 上传 HTML 上传入口为 **`/push`**，支持 **GET** 与 **POST** 两种方式；**推荐大内容或程序化调用使用 POST**，避免 URL 长度截断与编码问题。 #### 方式一：GET（适合「打开链接即投送」、短内容） - **路径**：`GET /push?padId={padId}&content={URL 编码的 HTML 字符串}` - **说明**：浏览器打开该 URL 或任意能发起 GET 的工具即可上传。`content` 需做 URL 编码（如 `encodeURIComponent(html)`）。内容较长时易遇 URL 截断或编码错误，建议改用 POST。 - **参数**：`padId`（必填）、`content`（必填，URL 编码后的 HTML）。 **示例**： ``` https://pad.genwebapp.com/push?padId=my-pad-1&content=%3Chtml%3E%3Cbody%3EHello%3C%2Fbody%3E%3C%2Fhtml%3E ``` #### 方式二：POST（推荐：大内容、AI/脚本上传） - **路径**：`POST /push`（可选 query：`?padId={padId}`） - **说明**：content 放在请求体中，无 URL 长度与编码问题。 - **两种 body 格式**： 1. **JSON**（推荐）：`Content-Type: application/json`，body：`{ "padId": "{padId}", "content": "..." }`。`padId` 可放在 query 或 body，二选一或同时提供（query 优先）。 2. **原始 HTML**：`Content-Type: text/html` 或 `text/plain`，body 为 HTML 原文；此时 **padId 必须在 query**：`POST /push?padId={padId}`。 **示例（JSON）**： ```bash curl -X POST https://pad.genwebapp.com/push \ -H "Content-Type: application/json" \ -d '{"padId":"my-pad-1","content":"Hello"}' ``` **示例（原始 HTML + query padId）**： ```bash curl -X POST "https://pad.genwebapp.com/push?padId=my-pad-1" \ -H "Content-Type: text/html; charset=utf-8" \ -d "Hello" ``` - **成功响应**：`200`，`{ "ok": true, "padId", "updatedAt", "expiresAt" }` - **错误**：400（缺少/非法 padId、缺少 content、非法 JSON 等）、413（content 超过 10MB） ### 2.2 获取当前 HTML - **路径**：`GET /api/pads/{padId}` - **成功响应**：`200`，`{ "exists": true|false, "html?", "updatedAt?", "expiresAt?" }` - `exists === false` 表示该 Pad 尚无内容或已过期。 ### 2.3 WebSocket 订阅 - **路径**：`/ws/{padId}`（GET，Upgrade: websocket） - 服务端推送 JSON：`{ "type": "html"|"info"|"error", "html?", "updatedAt?", "expiresAt?", ... }` - 上传新 HTML 时会推送 `type: "html"`，客户端应使用 `html` 更新展示。 --- ## 3. padId 建议上传时由调用方指定 padId（必填）。若希望「服务端生成」风格，可由调用方自行生成 UUID 再填入。允许短 padId（如六位）便于电视等场景。 --- ## 4. HTML 规范单文件 HTML，UTF-8，体积 ≤10MB。内容为 AI 生成，展示端会有安全提示。 --- ## 5. 常见错误与排查 | 现象 | 可能原因 | 处理 | |------|----------|------| | 400 MISSING_PAD_ID / MISSING_CONTENT | /push 缺少 padId 或 content | GET 须带 padId 和 content（content 为 URL 编码）；POST 须在 query/body 中提供 padId 并在 body 中提供 content | | 413 | /push 的 content >10MB | 压缩或拆分 HTML | | 400 INVALID_PAD_ID | padId 含 `/` 或为空 | 使用合法字符串，不含 `/` | | 打开 /p/{padId} 无内容 | Pad 未上传或已过期 | 先通过 GET 或 POST /push 上传，或 Pad 已过期需重新上传 | --- ## 6. 查看页与实时更新打开 `/p/{padId}` 即可查看。页面会 `GET /api/pads/{padId}` 取当前 HTML 并建立 `/ws/{padId}` 接收后续更新；上传（GET 或 POST /push）后所有已打开该 Pad 的客户端会立即刷新。 **查看页 URL**：`https://pad.genwebapp.com/p/{padId}` ## 7. 静态查看模式（无 WebSocket）当设备不支持 WebSocket，或不需要实时刷新时，使用静态模式： - 路径：`/t/{padId}`（兼容 `/-t/{padId}`） - 行为：服务端直接返回该 Pad 的 HTML（`text/html`），不加载实时外层框架、不建立 WebSocket - 适用：电视浏览器、嵌入式 WebView、只需一次性渲染的场景