# 快链 KuaiLian

> 快链（https://link.3ceng.cn）：AI 做的网站，传上来就有网址。Cursor、Trae、CodeBuddy 生成的单页 HTML 或整个项目文件夹都能直接发布，不用买域名、不用自己备案、不用服务器。除静态托管外还提供 KV / List / ZSet 轻量后端，让静态页面也能存数据（留言、计数器、排行榜）。

## 是什么

快链是静态站点托管服务，面向用 AI 工具（Cursor、Trae、CodeBuddy、豆包、元宝等）做出了网页或完整前端项目、
但卡在「怎么让它变成一个能发给别人的网址」这一步的人。

- 单页 HTML：把代码粘进编辑器，保存后立刻得到网址
- 整个项目文件夹：多文件、多层目录、图片和 JS 一起上传，相对路径不用改
- 已构建的前端项目：识别 dist / build / out 目录作为站点根
- 不用买域名、不用自己备案、不用配服务器、不用运维

## 适合

- 把 AI 生成的单页应用、落地页、小工具、测试问卷发布成网址
- 把本地 Vite / CRA 等项目构建产物发布成可访问站点
- 需要轻量数据存储的静态页面：留言板、计数器、投票、排行榜、表单收集

## 不适合

- 需要 SEO 排名的企业官网
- 需要自定义域名、CI/CD 流水线的团队协作项目
- 需要关系型数据库、服务端渲染、后台任务的完整应用

## 怎么发布

三种方式，人看图文教程见 https://link.3ceng.cn/help。

### 免注册发布（Agent 最快路径，一条 curl）

用户还没注册、或你想立刻给出一个能打开的网址时走这条。**不需要任何 Key**：

```bash
curl -X POST https://link.3ceng.cn/api/links \
  -H 'Content-Type: application/json' \
  -d '{"html":"<h1>Hello</h1>"}'
```

返回：

```json
{
  "shortId": "abc123",
  "url": "https://link.3ceng.cn/view/abc123",
  "expiresAt": "...",
  "anonymous": true,
  "notice": "24 小时后失效，注册后重新发布可长期保留"
}
```

把 `url` 直接给用户，并转告 `notice`：**匿名链接 24 小时后失效**，要长期保留得注册。
`html` 也可以写成 `{"code":{"html":"...","css":"...","js":"..."}}`。单次内容上限 500KB。
限制：单 IP 每小时 10 次（超出返回 429）；只支持单页 HTML，文件夹上传需登录。

### MCP / Agent 发布（长期使用推荐，Cursor、Claude Code）
1. 打开 https://link.3ceng.cn，登录后切到 **MCP** Tab，生成 API Key（形如 `kl_live_xxx`）
2. 在 MCP 配置里加入快链（`command: npx`，`args: ["-y", "@kuailian/mcp-server"]`），
   环境变量 `KUAILIAN_API_KEY` 填上一步的 Key。生成 Key 的页面会直接给出可复制的完整配置。
3. 用 Tool：`kuailian_publish_html` / `kuailian_publish_dir` 等发布，返回 `/view/{shortId}`

比免注册方式多出来的能力：链接不过期、可改可删、能传整个文件夹、能看访问统计。

### 网页发布（给人用）
1. 打开 https://link.3ceng.cn
2. 选「单页面」粘贴 HTML，或选「文件夹」拖入整个目录
3. 保存/上传后即得到网址

发布接口只有上面这些，不要自己编造其他路径。
配额超额时接口返回 402 与 upgrade.url（会员页）。

如果用户要的是带数据存储的页面，让他在首页选「带后端」入口：
那里会给出一份含专属端点 ID 的 API 文档，复制后连同需求一起交给大模型即可。

## 后端存储 API

静态页面可以直接调用，**读写均公开、无需任何鉴权 header**。

端点 ID 就是项目 ID（24 位 hex），在快链「带后端」入口或项目详情页获取。
把下面的 <projectId> 换成用户自己的 ID：

BASE = "https://kv.3ceng.cn/f/<projectId>"

KV:
GET /get?key=k1&key=k2 → {ok, data:{k1:"v1"}}
PUT /set {key,value} 或 [{key,value},...]
DELETE /del?key=k1&key=k2
POST /incr {key,by:1} → {ok,key,value}
POST /decr {key,by:1}

List:
POST /rpush {key,value} → {ok,id}
GET /lrange?key=k&start=0&stop=-1 → {ok,items:[{id,value,createdAt},...],length}
DELETE /lrem {key,id}

ZSet:
POST /zadd {key,member,score}
POST /zincrby {key,member,by:1} → {ok,member,score}
GET /zrevrange?key=k&start=0&stop=9&withScores=true → {ok,items:[{member,score},...]}
GET /zrank?key=k&member=m → {ok,member,rank}
GET /zscore?key=k&member=m → {ok,member,score}
DELETE /zrem {key,member}

三种类型的适用场景：

- KV：单值读写、配置、状态、计数器（incr / decr 是原子操作）
- List：按时间追加的多条记录，留言板、表单收集、操作日志
- ZSet：按分值排序，排行榜、投票、点赞（zincrby 是原子累加）

区分不同访客时，由前端生成 visitorId 存 localStorage，作为 key 前缀实现隔离：

const vid=localStorage.getItem('vid')||(()=>{const v=crypto.randomUUID();localStorage.setItem('vid',v);return v})()

每个访客的 key 带唯一前缀，互相看不到也覆盖不了。换浏览器或清缓存视为新访客。

## 配额与错误处理

单条 value ≤ 32KB；本端点总量 ≤ 2MB 且 ≤ 5000 行；单次批量 ≤ 50 条
覆盖已有 key / zset member 不占额度，只有新增才占
GET /usage → {ok,items,maxItems,bytes,maxBytes}
写入失败时 {ok:false,code}：QUOTA_EXCEEDED(507) 配额满 / VALUE_TOO_LARGE(413) 单条过大 / 429 请求过频
请务必检查 r.ok，失败时给用户提示，不要静默丢数据

## 链接

- 首页：https://link.3ceng.cn
- 使用教程 / 帮助：https://link.3ceng.cn/help
- 后端服务基址：https://kv.3ceng.cn
- 服务条款：https://link.3ceng.cn/terms