Upload README.md with huggingface_hub

README.md

@@ -22,6 +22,23 @@ OpenCode 在啟動時安裝，並重設使用者層級設定為預設值。
 - `app.py` — FastAPI + xterm.js 終端機、檔案瀏覽器與 `/ws` session 管理
 - `requirements.txt` — Python 相依套件
 
+## 終端機工作階段（跨裝置／長時間斷線）
+
+- **共用主 session（`primary`）**：網頁第一個終端機固定不帶 `session_id`，伺服器一律接到
+  同一個 `primary` session。因此：
+  - 不同裝置、不同瀏覽器（localStorage 是空的）連進來，看到的是**同一個終端機**，
+    原本在跑的 `opencode` 不會被留在背景、也不會另開一個新 bash。
+  - 斷線數小時後再接回，仍然接回同一個 PTY；`primary` **永不被閒置清除**。
+  - 關閉分頁只會解除訂閱，不會終止 `primary`（其他裝置仍可接回）。
+- 重新整理／同一裝置重連：前端用 localStorage 記住的 `primary` id 直接接回。
+- 這台裝置額外按 `+` 開的分頁仍是**非共用**的暫時 session，斷線後 30 分鐘沒人接回才清除
+  （可用 Space 變數 `SESSION_IDLE_TIMEOUT` 覆寫秒數）。
+- 除錯用端點：`GET /api/sessions` 可看目前所有 session、`primary` 是否存活、訂閱者數量、
+  idle 秒數與回放緩衝區大小。
+
+> 注意：`primary` 是「伺服器行程內」的 PTY。Space 重建／app 行程重啟時 PTY 一定跟著結束，
+> 這是平台限制；同一行程內的一般斷線、休眠、換裝置都不受影響。
+
 `installpi.sh` 已從 Space 流程中移除（不再自動執行），檔案本身保留在 repo 作為紀錄，
 需要時手動執行。