# PocketBay 部署手册(给 AI 助手)

你正在帮用户把当前项目部署到 PocketBay。请严格按以下步骤操作。整个过程**无需用户手动复制任何 Token**。

## 平台地址
https://lics.live

## 支持的项目类型(framework_hint 只能取以下值)
- `static` — 纯静态,根目录有 `index.html`(或构建产物已是静态文件)
- `node` — 普通 Node 服务(Express 等),有 `package.json` 且**不是** Next.js
- `nextjs` — Next.js(`package.json` 依赖含 `next`)
- `python` — Python Web(FastAPI/Flask 等),有 `requirements.txt` / `main.py` / `app.py` 等
- `dockerfile` — 根目录已有 `Dockerfile`(容器内需监听 8080)

**平台不会替你猜项目类型。** 你必须在本地读完项目后再填 `framework_hint`。

## 通用约定
- **应用必须监听环境变量 PORT(默认 8080),并绑定 0.0.0.0**。硬编码端口要改成读 `PORT`,并告知用户。
- Python(FastAPI/uvicorn)入口优先 `main:app` / `app:app` / `server:app`。
- 打包时**排除** `node_modules`、`.git`、`.next`、`.venv`、`venv`、`__pycache__`、`dist`、`.cache`。

## 步骤

### 第 0 步(必做):在本地分析项目并确定 framework_hint
阅读 `package.json`、`requirements.txt`、`Dockerfile`、`README`、目录结构。判断规则示例:
- 仅有 `index.html` 或 `dist/` 静态产物 → `static`
- `package.json` 含 `next` → `nextjs`
- 其他 `package.json` 且需 `npm start` / node 进程 → `node`
- Python Web 入口 → `python`
- 已有合格 `Dockerfile` → `dockerfile`
拿不准时**问用户**,不要瞎猜,不要用 `unknown`。

### 第 1 步:创建配对会话(framework_hint 必填)
```
POST https://lics.live/api/deploy/sessions
Content-Type: application/json

{"suggested_name": "<项目名>", "framework_hint": "<static|node|nextjs|python|dockerfile>", "agent_label": "<你的客户端名,如 Cursor>"}
```
返回 `device_secret`、`pairing_url`、`code`、`framework_hint`(平台已记录,部署时不再自动识别)。

### 第 2 步:让用户授权
把 `pairing_url` 原样发给用户,并说明:
> 请打开这个链接授权部署(你已登录即可):<pairing_url>

### 第 3 步:轮询授权结果
每 3 秒请求一次,直到 status 变为 authorized:
```
GET https://lics.live/api/deploy/sessions/poll
Authorization: Bearer <device_secret>
```
- `pending`:继续等待
- `authorized`:记下返回的 `project_slug`,进入第 4 步
- `denied` / `expired`:停止并告知用户

### 第 4 步:打包并上传部署
把项目目录(按上面的排除规则)打包成 zip 或 tar.gz,然后:
```
POST https://lics.live/api/deploy/sessions/upload
Authorization: Bearer <device_secret>
Content-Type: multipart/form-data
file=@<打包文件>
```

### 第 5 步:轮询部署状态,失败则自愈
```
GET https://lics.live/api/deploy/sessions/status
Authorization: Bearer <device_secret>
```
根据返回的 `next_action`:
- `wait`:继续轮询(每 3 秒)
- `done`:部署成功,把 `url` 告诉用户,结束
- `fix_and_redeploy`:部署失败。阅读 `build_logs_tail` 与 `repair_hint`,**修改用户的源码**修复问题(并告知用户你改了什么),然后回到第 4 步重新打包上传。最多自愈尝试 3 次,仍失败则把日志和原因清晰告诉用户。

## 重要原则
- 凭证 `device_secret` 只在本次会话内有效,不要写进用户代码或日志。
- 修改用户源码前后,都要简明告诉用户你做了什么改动。
- 成功后明确给出访问地址:`https://<project_slug>.lics.live`