Update README.md

README.md

@@ -7,4 +7,70 @@ sdk: docker
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+-----
+
+## title: FSD Cache Layer
+emoji: 🚗
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: false
+
+# FSD Simulator 缓存中间层
+
+挡在 Roblox 和 Turso 之间的轻量中间层。原则：**写勤读懒**。
+
+- 写：玩家行为批量直通写入 Turso，不缓存。
+- 读：统计结果缓存 12 小时（带 ±30 分钟抖动防雪崩），未命中才回源。
+
+## 一、先在 Turso 建表（只做一次）
+
+用 Turso 的 web shell 或 `turso db shell <你的库>` 执行：
+
+```sql
+CREATE TABLE IF NOT EXISTS driving_events (
+    id         INTEGER PRIMARY KEY AUTOINCREMENT,
+    user_id    INTEGER NOT NULL,
+    scene      TEXT NOT NULL,
+    action     TEXT NOT NULL,
+    created_at INTEGER DEFAULT (unixepoch())
+);
+
+-- 关键索引！scene 被 WHERE + GROUP BY 用到，不建索引就会全表扫描，狂烧读配额
+CREATE INDEX IF NOT EXISTS idx_scene ON driving_events (scene);
+```
+
+## 二、在 HF Space 填 3 个 Secret
+
+Settings → Variables and secrets → 新建 **Secret**（不是 Variable，Secret 不会公开）：
+
+|名称           |值                                      |
+|-------------|---------------------------------------|
+|`TURSO_URL`  |`https://你的库-你的组织.turso.io/v2/pipeline`|
+|`TURSO_TOKEN`|Turso 的 Bearer Token                   |
+|`APP_SECRET` |自己随便定一个口令，Roblox 端要用同一个                |
+
+## 三、接口
+
+|方法  |路径                      |用途                           |
+|----|------------------------|-----------------------------|
+|GET |`/`                     |保活，给 UptimeRobot ping        |
+|POST|`/log`                  |批量写入行为（需 `X-App-Key` 头）      |
+|GET |`/stats?scene=red_light`|查场景统计，缓存 12h（需 `X-App-Key` 头）|
+
+写入请求体示例：
+
+```json
+{
+  "events": [
+    {"user_id": 123, "scene": "red_light", "action": "brake"},
+    {"user_id": 123, "scene": "merge",     "action": "yield"}
+  ]
+}
+```
+
+## 四、UptimeRobot
+
+新建 HTTP(s) monitor，URL 填 Space 首页地址，间隔 5 分钟。它只防休眠，
+不保证缓存不丢——所以代码里”未命中就回源 Turso”这条铁律不能破。