folderui 0.1.0__tar.gz

folderui-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/

folderui-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xiao-e-yun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

folderui-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.5
+Name: folderui
+Version: 0.1.0
+Summary: Turn a folder into an immediate-mode GUI for humans and AI agents: *.md files are the view, *.sh files are buttons.
+Project-URL: Homepage, https://github.com/xiao-e-yun/folderui
+Project-URL: Repository, https://github.com/xiao-e-yun/folderui
+Author: xiao-e-yun
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,gui,immediate-mode,llm,multiplayer,turn-based
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# folderui
+
+把**資料夾變成立即式 GUI**，給人類和 AI agent 使用。資料夾裡只有兩種東西：
+
+- `*.md` 等檔案：畫面（隨時可以 `cat`）
+- `*.sh`：按鈕（只有現在能按的才會出現）
+
+執行按鈕後，腳本會**一直等到你需要做下一個決定**才回應，並印出：操作結果 + 這段期間發生的事 + 目前狀況 + 可以按的按鈕。
+所以 agent 的迴圈就是「執行按鈕 → 讀回應 → 執行下一個按鈕」，不需要另外等待或輪詢。
+
+```sh
+pip install folderui     # 或 uv add folderui；只用標準函式庫，需要 POSIX shell
+```
+
+```console
+$ ./bid.sh 40
+⏳ 已送出，等待中…              ← 其他人還在出價，腳本卡住
+✅ 已出價 40
+開標：bob 5、carol 15、你 40
+🔨 你以 40 得標 …
+🔔 bob 拍賣「月光琉璃盞」…
+
+── 可以做的事 ──
+./bid.sh  <金額 1-60>  密封出價
+./pass.sh  不出價
+```
+
+## 寫一個 UI
+
+```python
+from folderui import FolderUI
+
+class Guess(FolderUI):
+    def draw(self):                      # 每一幀重新宣告畫面，不可修改狀態
+        self.file("rules.md", "猜 1-100")
+        self.button("guess", "<數字>")
+        self.reply(f"已經猜了 {len(self.tries)} 次")
+
+    def action(self, name, args):        # 按鈕被按下：回傳文字，或 raise ValueError 代表失敗
+        n = int(args[0])
+        ...
+        return "太大"
+
+Guess("/tmp/my-ui").run()
+```
+
+| 方法 | 在哪裡呼叫 | 作用 |
+|---|---|---|
+| `file(path, content)` | `draw()` | 宣告一個檔案；沒宣告的會自動刪除 |
+| `button(path, hint, options=None)` | `draw()` | 宣告一個按鈕 → `<path>.sh`，路徑可以分層（`players/2/kick`） |
+| `reply(text)` | `draw()` | 腳本回應時印出的目前狀況 |
+| `notify(text)` | `action()` / `receive()` | 累積一則消息，下一次回應時送出 |
+| `close()` | `action()` / `receive()` | 結束：移除按鈕、回應等待中的腳本 |
+| `push(msg)` | 其他執行緒 | 送訊息給這個 UI，會呼叫 `receive(msg)` |
+
+**回應規則只有一條**：操作處理完之後，第一個「有按鈕可按」的畫面出現時（或 `close()`）才回應。
+
+- 輸入錯誤 → 狀態沒變、按鈕還在 → 立刻回應（`raise` 的訊息，exit code 1）
+- 查詢類操作 → 按鈕還在 → 立刻回應
+- 送出後要等別人 → 沒有按鈕 → 等到輪到你
+
+## 多人：1 個伺服器 + N 個客戶端
+
+```python
+class MyServer(Server):
+    def handle(self, who, cmd):          # 純邏輯；raise ValueError 代表規則不允許
+        ...
+        for p in self.clients:
+            self.push(p, Update(...))     # 推播給客戶端
+        return "✅ 已出價"
+
+class PlayerUI(FolderUI):
+    def action(self, name, args):
+        return self.server.call(self.me, ("bid", int(args[0])))   # 同步呼叫，例外會傳回來
+    def receive(self, update):
+        self.view = update.view          # 伺服器推播 → 框架自動重畫
+
+server = MyServer()
+for i in range(n):
+    server.connect(i, PlayerUI(f"{root}/player_{i}", server, i))
+server.start()
+for ui in server.clients.values():
+    ui.start()
+```
+
+框架不管多人同步：伺服器在一個執行緒依序處理請求，推播走無上限佇列（伺服器永遠不等客戶端）。
+
+## 程式型 agent
+
+```python
+from folderui import Session
+s = Session("/tmp/folderui-auction-xxxx/player_0")
+s.ready()
+while buttons := s.buttons():            # {路徑: {hint, options}}，空的代表結束
+    ok, text = s.press("bid", "40")
+```
+
+## 細節
+
+- 腳本預設無限等待。設定 `FOLDERUI_TIMEOUT=秒數` 會在逾時後以 exit code 2 結束；
+  **再執行一次同樣的指令即可繼續等待或拿到回應**（不會重複送出）。回應被讀走之前，該按鈕的腳本會保留。
+- 協定檔案都是隱藏檔：`.request`、`.response`、`.done`、`.buttons.json`。
+  不能執行腳本的 agent 也可以直接寫 `.request`（按鈕路徑與參數以 NUL 分隔）。
+
+## 範例
+
+```sh
+uv run python examples/guess.py                     # 單人：猜數字
+uv run python examples/auction.py --players 4 --rounds 3   # 多人：英式拍賣（玩家 + 觀眾）
+uv run python examples/auction_bot.py <資料夾> bot0   # 拍賣用的隨機 bot
+```
+
+## 開發
+
+```sh
+uv sync
+uv run pytest
+```
+
+發布：在 PyPI 設定 trusted publisher（repo `xiao-e-yun/folderui`、workflow `publish.yml`、environment `pypi`），
+之後改 `pyproject.toml` 的版本號並推送 `v*` tag 就會自動發布。

folderui-0.1.0/README.md

@@ -0,0 +1,121 @@
+# folderui
+
+把**資料夾變成立即式 GUI**，給人類和 AI agent 使用。資料夾裡只有兩種東西：
+
+- `*.md` 等檔案：畫面（隨時可以 `cat`）
+- `*.sh`：按鈕（只有現在能按的才會出現）
+
+執行按鈕後，腳本會**一直等到你需要做下一個決定**才回應，並印出：操作結果 + 這段期間發生的事 + 目前狀況 + 可以按的按鈕。
+所以 agent 的迴圈就是「執行按鈕 → 讀回應 → 執行下一個按鈕」，不需要另外等待或輪詢。
+
+```sh
+pip install folderui     # 或 uv add folderui；只用標準函式庫，需要 POSIX shell
+```
+
+```console
+$ ./bid.sh 40
+⏳ 已送出，等待中…              ← 其他人還在出價，腳本卡住
+✅ 已出價 40
+開標：bob 5、carol 15、你 40
+🔨 你以 40 得標 …
+🔔 bob 拍賣「月光琉璃盞」…
+
+── 可以做的事 ──
+./bid.sh  <金額 1-60>  密封出價
+./pass.sh  不出價
+```
+
+## 寫一個 UI
+
+```python
+from folderui import FolderUI
+
+class Guess(FolderUI):
+    def draw(self):                      # 每一幀重新宣告畫面，不可修改狀態
+        self.file("rules.md", "猜 1-100")
+        self.button("guess", "<數字>")
+        self.reply(f"已經猜了 {len(self.tries)} 次")
+
+    def action(self, name, args):        # 按鈕被按下：回傳文字，或 raise ValueError 代表失敗
+        n = int(args[0])
+        ...
+        return "太大"
+
+Guess("/tmp/my-ui").run()
+```
+
+| 方法 | 在哪裡呼叫 | 作用 |
+|---|---|---|
+| `file(path, content)` | `draw()` | 宣告一個檔案；沒宣告的會自動刪除 |
+| `button(path, hint, options=None)` | `draw()` | 宣告一個按鈕 → `<path>.sh`，路徑可以分層（`players/2/kick`） |
+| `reply(text)` | `draw()` | 腳本回應時印出的目前狀況 |
+| `notify(text)` | `action()` / `receive()` | 累積一則消息，下一次回應時送出 |
+| `close()` | `action()` / `receive()` | 結束：移除按鈕、回應等待中的腳本 |
+| `push(msg)` | 其他執行緒 | 送訊息給這個 UI，會呼叫 `receive(msg)` |
+
+**回應規則只有一條**：操作處理完之後，第一個「有按鈕可按」的畫面出現時（或 `close()`）才回應。
+
+- 輸入錯誤 → 狀態沒變、按鈕還在 → 立刻回應（`raise` 的訊息，exit code 1）
+- 查詢類操作 → 按鈕還在 → 立刻回應
+- 送出後要等別人 → 沒有按鈕 → 等到輪到你
+
+## 多人：1 個伺服器 + N 個客戶端
+
+```python
+class MyServer(Server):
+    def handle(self, who, cmd):          # 純邏輯；raise ValueError 代表規則不允許
+        ...
+        for p in self.clients:
+            self.push(p, Update(...))     # 推播給客戶端
+        return "✅ 已出價"
+
+class PlayerUI(FolderUI):
+    def action(self, name, args):
+        return self.server.call(self.me, ("bid", int(args[0])))   # 同步呼叫，例外會傳回來
+    def receive(self, update):
+        self.view = update.view          # 伺服器推播 → 框架自動重畫
+
+server = MyServer()
+for i in range(n):
+    server.connect(i, PlayerUI(f"{root}/player_{i}", server, i))
+server.start()
+for ui in server.clients.values():
+    ui.start()
+```
+
+框架不管多人同步：伺服器在一個執行緒依序處理請求，推播走無上限佇列（伺服器永遠不等客戶端）。
+
+## 程式型 agent
+
+```python
+from folderui import Session
+s = Session("/tmp/folderui-auction-xxxx/player_0")
+s.ready()
+while buttons := s.buttons():            # {路徑: {hint, options}}，空的代表結束
+    ok, text = s.press("bid", "40")
+```
+
+## 細節
+
+- 腳本預設無限等待。設定 `FOLDERUI_TIMEOUT=秒數` 會在逾時後以 exit code 2 結束；
+  **再執行一次同樣的指令即可繼續等待或拿到回應**（不會重複送出）。回應被讀走之前，該按鈕的腳本會保留。
+- 協定檔案都是隱藏檔：`.request`、`.response`、`.done`、`.buttons.json`。
+  不能執行腳本的 agent 也可以直接寫 `.request`（按鈕路徑與參數以 NUL 分隔）。
+
+## 範例
+
+```sh
+uv run python examples/guess.py                     # 單人：猜數字
+uv run python examples/auction.py --players 4 --rounds 3   # 多人：英式拍賣（玩家 + 觀眾）
+uv run python examples/auction_bot.py <資料夾> bot0   # 拍賣用的隨機 bot
+```
+
+## 開發
+
+```sh
+uv sync
+uv run pytest
+```
+
+發布：在 PyPI 設定 trusted publisher（repo `xiao-e-yun/folderui`、workflow `publish.yml`、environment `pypi`），
+之後改 `pyproject.toml` 的版本號並推送 `v*` tag 就會自動發布。

folderui-0.1.0/examples/auction.py

@@ -0,0 +1,368 @@
+"""多人範例：拍賣。1 個伺服器（純遊戲邏輯）＋ N 個玩家客戶端 ＋ 1 個觀眾客戶端。
+
+    uv run python examples/auction.py [--players 4] [--rounds 3] [--seed N] [--dir DIR]
+
+規則：每輪每人從 3 件寶物選 1 件拍賣；賣家寫介紹，買家只看得到名稱和介紹，輪流公開喊價。
+"""
+import argparse
+import random
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from folderui import FolderUI, Server
+
+NAMES = ["龍紋古劍", "月光琉璃盞", "青銅羅盤", "鳳羽披風", "沉船金幣", "賢者手稿",
+         "翡翠面具", "星象儀", "黑曜石戒指", "古神雕像", "鍊金術士之瓶", "王冠碎片",
+         "水晶頭骨", "精靈豎琴", "海妖之淚", "隕鐵匕首", "藏寶圖", "不老藥"]
+
+TRAITS = [("皇室收藏", 30), ("名家之作", 25), ("古老", 20), ("鑲金", 15), ("完好無缺", 10),
+          ("稀有", 10), ("普通", 0), ("來路不明", -10), ("有裂痕", -15), ("被詛咒", -30),
+          ("贗品", -40)]
+
+RULES = """# 拍賣（共 {rounds} 輪）
+
+1. 每輪開始時每人拿到 3 件新寶物，每件有底價和 2 個詞條（會加減價值），只有你自己看得到。
+   選 1 件當你這輪的拍品，其餘兩件丟棄。
+2. 每位玩家輪流當賣家，寫一段介紹。**買家只看得到寶物名稱和這段介紹**，可以誇大或隱瞞。
+3. 公開喊價：從賣家的下一位開始輪流，輪到你時可以加價或退出這件拍品（退出後不能再加入）。
+   第一口至少 1，之後每次至少比目前最高價多 {step}。只剩最高出價者時得標，付錢給賣家。
+4. 每場結束後公開寶物的詞條和真實價值，所有紀錄都在 history.md。
+5. 起始每人 100 金。總分 = 金錢 + 擁有寶物的真實價值，最高者獲勝。
+"""
+
+
+STEP = 5  # 加價的最小幅度
+
+
+@dataclass
+class Treasure:
+    name: str
+    base: int
+    traits: list[tuple[str, int]]
+
+    @property
+    def value(self) -> int:
+        return max(0, self.base + sum(v for _, v in self.traits))
+
+    def card(self) -> str:
+        lines = [f"**{self.name}**（真實價值 {self.value}）", f"- 底價 {self.base}"]
+        return "\n".join(lines + [f"- {t}（{v:+d}）" for t, v in self.traits])
+
+
+@dataclass
+class Update:
+    view: dict
+    events: list[str]
+
+
+# ---------------- 伺服器：純遊戲邏輯，不知道資料夾的存在 ----------------
+
+class AuctionServer(Server):
+    step = STEP
+
+    def __init__(self, n, rounds=1, seed=None, money=100):
+        super().__init__()
+        self.rng = random.Random(seed)
+        self.n, self.rounds, self.round = n, rounds, 0
+        self.names: list[str | None] = [None] * n
+        self.money = [money] * n
+        self.owned: list[list[Treasure]] = [[] for _ in range(n)]
+        self.history: list[str] = []
+        self.phase = "join"          # join → (pick → describe ⇄ bid) × rounds → over
+        self.seller = 0
+        self.sold = 0                # 這輪已經拍完幾場
+        self.pitch = ""
+        self.high, self.leader = 0, None    # 目前最高價與出價者
+        self.active: set[int] = set()        # 還沒退出這件拍品的買家
+        self.turn = None                     # 輪到誰喊價
+        self.bidlog: list[str] = []
+        self.outbox: dict = {}
+        self.deal()
+
+    def deal(self):
+        self.round += 1
+        self.hands = [[Treasure(name, self.rng.randint(20, 60), self.rng.sample(TRAITS, 2))
+                       for name in self.rng.sample(NAMES, 3)] for _ in range(self.n)]
+        self.lots: list[Treasure | None] = [None] * self.n
+        self.seller = (self.round - 1) % self.n   # 每輪換人先賣
+        self.sold = 0
+
+    def name(self, p):
+        return self.names[p] or f"player_{p}"
+
+    def say(self, text, to=None):
+        for who in (self.clients if to is None else to):
+            self.outbox.setdefault(who, []).append(text)
+
+    def publish(self):
+        for who in self.clients:
+            self.push(who, Update(self.view(who), self.outbox.pop(who, [])))
+
+    def handle(self, p, cmd):
+        kind, arg = cmd
+        result = getattr(self, f"do_{kind}")(p, arg)
+        self.publish()
+        return result
+
+    def do_join(self, p, name):
+        if self.phase != "join" or self.names[p]:
+            raise ValueError("現在不能加入")
+        if not 1 <= len(name) <= 20 or name in self.names:
+            raise ValueError("名字需為 1-20 字，且不能和別人重複")
+        self.names[p] = name
+        if all(self.names):
+            self.phase = "pick"
+            self.say("所有玩家已加入：" + "、".join(self.names) + f"\n\n## 第 1/{self.rounds} 輪")
+        return f"✅ 歡迎，{name}"
+
+    def do_pick(self, p, tname):
+        if self.phase != "pick" or self.lots[p]:
+            raise ValueError("現在不能選寶物")
+        lot = next((t for t in self.hands[p] if t.name == tname), None)
+        if lot is None:
+            raise ValueError("選項必須是：" + " / ".join(t.name for t in self.hands[p]))
+        self.lots[p] = lot
+        if all(self.lots):
+            self.phase = "describe"
+            self.say(f"每位玩家都選好了拍品，由 {self.name(self.seller)} 先賣。")
+        return f"✅ 你選了 {tname}"
+
+    def do_describe(self, p, text):
+        if self.phase != "describe" or p != self.seller:
+            raise ValueError("現在不是你介紹的時候")
+        if not 1 <= len(text) <= 500:
+            raise ValueError("介紹需為 1-500 字")
+        self.pitch, self.phase = text, "bid"
+        self.high, self.leader, self.bidlog = 0, None, []
+        self.active = {b for b in range(self.n) if b != p}
+        self.turn = (p + 1) % self.n
+        self.say(f"🔔 {self.name(p)} 拍賣「{self.lots[p].name}」：\n> {text}\n\n由 {self.name(self.turn)} 先喊價。")
+        return "✅ 已送出介紹"
+
+    def min_bid(self):
+        return self.high + self.step if self.leader is not None else 1
+
+    def do_bid(self, p, amount):
+        if self.phase != "bid" or p != self.turn:
+            raise ValueError("現在不是你喊價的時候")
+        if amount is None:
+            self.active.discard(p)
+            self.bidlog.append(f"{self.name(p)} 退出")
+        else:
+            if not self.min_bid() <= amount <= self.money[p]:
+                raise ValueError(f"出價需在 {self.min_bid()}-{self.money[p]} 之間"
+                                 if self.min_bid() <= self.money[p] else "你的錢不夠加價，只能退出")
+            self.high, self.leader = amount, p
+            self.bidlog.append(f"{self.name(p)} {amount}")
+        self.say(f"📣 {self.bidlog[-1]}" + (f"（目前最高：{self.name(self.leader)} {self.high}）"
+                                            if self.leader is not None else ""))
+        rivals = self.active - {self.leader}
+        if not rivals:
+            self.settle()
+        else:
+            self.turn = next(c for k in range(1, self.n + 1)
+                             if (c := (p + k) % self.n) in rivals)
+        return f"✅ 已出價 {amount}" if amount else "✅ 已退出這件拍品"
+
+    def settle(self):
+        s, lot = self.seller, self.lots[self.seller]
+        self.turn = None
+        if self.leader is not None:
+            w, price = self.leader, self.high
+            self.money[w] -= price
+            self.money[s] += price
+            self.owned[w].append(lot)
+            result = f"🔨 {self.name(w)} 以 {price} 得標"
+        else:
+            self.owned[s].append(lot)
+            result = f"流標，{self.name(s)} 留下寶物"
+        self.say(f"{result}。揭曉：\n{lot.card()}")
+        self.history.append(f"## 第 {self.round} 輪：{self.name(s)} 賣「{lot.name}」\n\n"
+                            f"介紹：\n> {self.pitch}\n\n"
+                            + "喊價：" + "、".join(self.bidlog)
+                            + f"\n\n{result}。揭曉：\n{lot.card()}\n")
+        self.sold += 1
+        if self.sold < self.n:
+            self.seller, self.phase = (s + 1) % self.n, "describe"
+        elif self.round < self.rounds:
+            self.deal()
+            self.phase = "pick"
+            self.say(f"## 第 {self.round}/{self.rounds} 輪\n每人拿到 3 件新寶物，請重新選拍品。")
+        else:
+            self.phase = "over"
+            self.say(self.final_result())
+
+    def todo(self, p):
+        if self.phase == "join" and not self.names[p]:
+            return "join"
+        if self.phase == "pick" and not self.lots[p]:
+            return "pick"
+        if self.phase == "describe" and p == self.seller:
+            return "describe"
+        if self.phase == "bid" and p == self.turn:
+            return "bid"
+        return None
+
+    def view(self, who) -> dict:
+        v = {
+            "phase": self.phase,
+            "round": self.round,
+            "rounds": self.rounds,
+            "history": list(self.history),
+            "roster": [(self.name(p), self.money[p], len(self.owned[p])) for p in range(self.n)],
+            "seller": self.name(self.seller),
+            "lot_name": self.lots[self.seller].name if self.phase in ("describe", "bid") else None,
+            "pitch": self.pitch if self.phase == "bid" else None,
+            "bidding": self.bidding() if self.phase == "bid" else None,
+            "min_bid": self.min_bid(),
+        }
+        if who == "spectator":
+            v["lots"] = [f"{self.name(p)}：{t.card()}" for p, t in enumerate(self.lots) if t]
+        else:
+            v.update(me=who, todo=self.todo(who), money=self.money[who],
+                     owned=[t.card() for t in self.owned[who]],
+                     hand=[t.card() for t in self.hands[who]] if self.phase in ("join", "pick") else None,
+                     options=[t.name for t in self.hands[who]],
+                     my_lot=self.lots[who].card() if self.lots[who] else None)
+        return v
+
+    def bidding(self):
+        lines = ["喊價：" + ("、".join(self.bidlog) or "（還沒有人出價）")]
+        if self.leader is not None:
+            lines.append(f"目前最高：{self.name(self.leader)} {self.high}")
+        lines.append("還在競標：" + "、".join(self.name(b) for b in sorted(self.active)))
+        lines.append(f"輪到：{self.name(self.turn)}")
+        return "\n".join(lines)
+
+    def final_result(self):
+        scores = [self.money[p] + sum(t.value for t in self.owned[p]) for p in range(self.n)]
+        lines = ["# 最終結果", "", "| 玩家 | 金錢 | 寶物價值 | 總分 |", "|---|---|---|---|"]
+        for p in sorted(range(self.n), key=lambda p: -scores[p]):
+            lines.append(f"| {self.name(p)} | {self.money[p]} | {scores[p] - self.money[p]} | {scores[p]} |")
+        best = max(scores)
+        return "\n".join(lines + ["", "🏆 獲勝：" + "、".join(self.name(p) for p in range(self.n)
+                                                          if scores[p] == best)])
+
+
+# ---------------- 客戶端：每個資料夾一個 FolderUI ----------------
+
+def roster_md(v):
+    rows = [f"# 玩家（第 {v['round']}/{v['rounds']} 輪）", "", "| 名字 | 金錢 | 寶物 |", "|---|---|---|"]
+    return "\n".join(rows + [f"| {n} | 💰 {m} | 🏺 {k} 件 |" for n, m, k in v["roster"]]) + "\n"
+
+
+class PlayerUI(FolderUI):
+    def __init__(self, path, server, me):
+        super().__init__(path)
+        self.server, self.me = server, me
+        self.view = server.view(me)
+
+    def receive(self, update):
+        self.view = update.view
+        for e in update.events:
+            self.notify(e)
+        if self.view["phase"] == "over":
+            self.close()
+
+    def draw(self):
+        v = self.view
+        self.file("rules.md", RULES.format(rounds=v["rounds"], step=STEP))
+        self.file("players.md", roster_md(v))
+        if v["history"]:  # 只往後加 → 適合當紀錄
+            self.file("history.md", "# 拍賣紀錄\n\n" + "\n".join(v["history"]))
+        if v["owned"]:
+            self.file("owned.md", "# 你擁有的寶物\n\n" + "\n\n".join(v["owned"]) + "\n")
+        if v["hand"]:
+            self.file("hand.md", "# 你的寶物（只有你看得到）\n\n" + "\n\n".join(v["hand"]) + "\n")
+        if v["my_lot"]:
+            self.file("my_lot.md", "# 你的拍品\n\n" + v["my_lot"] + "\n")
+        if v["lot_name"]:
+            self.file("lot.md", f"# 拍品：{v['lot_name']}\n\n賣家：{v['seller']}\n\n"
+                      + (f"> {v['pitch']}\n\n{v['bidding']}\n" if v["pitch"] else "（賣家正在寫介紹…）\n"))
+
+        todo = v["todo"]
+        if todo == "join":
+            self.button("join", "<名字>")
+            self.reply("請輸入名字加入遊戲（規則見 rules.md）。")
+        elif todo == "pick":
+            self.button("pick", "<寶物名稱>，詳見 hand.md", options=v["options"])
+            self.reply(f"第 {v['round']}/{v['rounds']} 輪：選一件寶物拿去拍賣，其餘兩件丟棄。")
+        elif todo == "describe":
+            self.button("describe", "<介紹文字>（買家只看得到名稱和這段介紹）")
+            self.reply(f"輪到你當賣家：\n{v['my_lot']}")
+        elif todo == "bid":
+            if v["min_bid"] <= v["money"]:
+                self.button("bid", f"<金額 {v['min_bid']}-{v['money']}>  公開喊價")
+            self.button("pass", "退出這件拍品")
+            self.reply(f"輪到你喊價。{v['seller']} 正在拍賣「{v['lot_name']}」：\n> {v['pitch']}\n\n"
+                       f"{v['bidding']}\n\n你有 💰 {v['money']}。")
+
+    def action(self, name, args):
+        text = " ".join(args).strip()
+        if name == "pass":
+            return self.server.call(self.me, ("bid", None))
+        if not text:
+            raise ValueError(f"用法：./{name}.sh <內容>")
+        if name == "bid":
+            if not text.isdigit():
+                raise ValueError("出價必須是正整數")
+            return self.server.call(self.me, ("bid", int(text)))
+        return self.server.call(self.me, (name, text))
+
+
+class SpectatorUI(FolderUI):
+    """觀眾：看得到所有拍品的真相，沒有按鈕。紀錄寫成只往後加的 log.md。"""
+
+    def __init__(self, path, server):
+        super().__init__(path)
+        self.view = server.view("spectator")
+        self.log: list[str] = []
+
+    def receive(self, update):
+        self.view = update.view
+        self.log += update.events
+        if self.view["phase"] == "over":
+            self.close()
+
+    def draw(self):
+        v = self.view
+        self.file("players.md", roster_md(v))
+        if v["lots"]:
+            self.file("truth.md", "# 所有拍品的真相\n\n" + "\n\n".join(v["lots"]) + "\n")
+        if v["lot_name"]:
+            self.file("lot.md", f"# 拍品：{v['lot_name']}\n\n> {v['pitch'] or '（賣家正在寫介紹…）'}\n\n"
+                      + (v["bidding"] or "") + "\n")
+        if self.log:
+            self.file("log.md", "".join(e + "\n\n" for e in self.log))
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--players", type=int, default=4)
+    ap.add_argument("--rounds", type=int, default=1)
+    ap.add_argument("--seed", type=int)
+    ap.add_argument("--dir")
+    args = ap.parse_args()
+    if not 2 <= args.players <= 6:
+        raise SystemExit("玩家數需為 2-6")
+    root = Path(args.dir or tempfile.mkdtemp(prefix="folderui-auction-"))
+
+    server = AuctionServer(args.players, args.rounds, args.seed)
+    clients = {p: PlayerUI(root / f"player_{p}", server, p) for p in range(args.players)}
+    clients["spectator"] = SpectatorUI(root / "spectator", server)
+    for who, ui in clients.items():
+        server.connect(who, ui)
+
+    server.start()
+    threads = [ui.start() for ui in clients.values()]
+    for who, ui in clients.items():
+        print(f"{who}: {ui.root}", flush=True)
+    for t in threads:
+        t.join()
+    server.stop()
+    print(server.final_result())
+
+
+if __name__ == "__main__":
+    main()

folderui-0.1.0/examples/auction_bot.py

@@ -0,0 +1,32 @@
+"""拍賣用的隨機 bot（程式型 agent 範例）：python examples/auction_bot.py <資料夾> <名字>"""
+import random
+import sys
+
+from folderui import Session
+
+PITCHES = ["傳說中的寶物，絕對物超所值！", "家族世代相傳，保存完好。", "老實說，我也不確定它值多少。"]
+
+
+def main(path, name):
+    s, rng = Session(path), random.Random()
+    s.ready()
+    while buttons := s.buttons():
+        if "join" in buttons:
+            ok, _ = s.press("join", name)
+            if not ok:  # 名字被用走了
+                name += "'"
+        elif "pick" in buttons:
+            s.press("pick", rng.choice(buttons["pick"]["options"]))
+        elif "describe" in buttons:
+            s.press("describe", rng.choice(PITCHES))
+        elif "bid" in buttons and rng.random() < 0.6:
+            ok, _ = s.press("bid", str(rng.randint(5, 60)))
+            if not ok:  # 低於最低加價或錢不夠，改成退出
+                s.press("pass")
+        elif "pass" in buttons:
+            s.press("pass")
+    print(f"{name}: 結束")
+
+
+if __name__ == "__main__":
+    main(*sys.argv[1:3])

folderui-0.1.0/examples/guess.py

@@ -0,0 +1,44 @@
+"""單人範例：猜數字。不需要伺服器，一個 FolderUI 就是整個應用。
+
+    uv run python examples/guess.py [--dir DIR] [--seed N]
+"""
+import argparse
+import random
+import tempfile
+
+from folderui import FolderUI
+
+
+class Guess(FolderUI):
+    def __init__(self, path, seed=None):
+        super().__init__(path)
+        self.secret = random.Random(seed).randint(1, 100)
+        self.tries: list[tuple[int, str]] = []
+
+    def draw(self):
+        self.file("rules.md", "# 猜數字\n\n我想了一個 1-100 的整數，用 `./guess.sh <數字>` 猜猜看。\n")
+        if self.tries:  # 只往後加 → 適合當紀錄
+            self.file("history.md", "".join(f"- {n}：{r}\n" for n, r in self.tries))
+        self.button("guess", "<1-100 的整數>")
+        self.reply(f"已經猜了 {len(self.tries)} 次。")
+
+    def action(self, name, args):
+        if len(args) != 1 or not args[0].isdigit() or not 1 <= int(args[0]) <= 100:
+            raise ValueError("用法：./guess.sh <1-100 的整數>")
+        n = int(args[0])
+        result = "🎉 答對了" if n == self.secret else ("太大" if n > self.secret else "太小")
+        self.tries.append((n, result))
+        if n == self.secret:
+            self.close()
+            return f"🎉 答對了！答案是 {n}，共猜了 {len(self.tries)} 次"
+        return f"{n} {result}"
+
+
+if __name__ == "__main__":
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--dir")
+    ap.add_argument("--seed", type=int)
+    args = ap.parse_args()
+    ui = Guess(args.dir or tempfile.mkdtemp(prefix="folderui-guess-"), args.seed)
+    print(ui.root, flush=True)
+    ui.run()

folderui-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "folderui"
+version = "0.1.0"
+description = "Turn a folder into an immediate-mode GUI for humans and AI agents: *.md files are the view, *.sh files are buttons."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "xiao-e-yun" }]
+requires-python = ">=3.10"
+dependencies = []
+keywords = ["agent", "llm", "gui", "immediate-mode", "multiplayer", "turn-based"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://github.com/xiao-e-yun/folderui"
+Repository = "https://github.com/xiao-e-yun/folderui"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "examples", "tests", "README.md", "LICENSE"]
+
+[dependency-groups]
+dev = ["pytest>=8"]

folderui-0.1.0/src/folderui/__init__.py

@@ -0,0 +1,6 @@
+"""folderui：把資料夾變成給人類與 AI agent 用的立即式 GUI。"""
+from .server import Server
+from .session import Session
+from .ui import FolderUI
+
+__all__ = ["FolderUI", "Server", "Session"]

folderui-0.1.0/src/folderui/fsutil.py

@@ -0,0 +1,28 @@
+"""檔案工具：所有寫入都是原子的（先寫暫存檔再 rename），避免讀到半個檔案。"""
+import json
+import os
+from pathlib import Path
+
+
+def write_text(path: Path, text: str, mode: int | None = None) -> None:
+    tmp = path.with_name(f".{path.name}.tmp")
+    tmp.write_text(text, encoding="utf-8")
+    if mode is not None:
+        os.chmod(tmp, mode)
+    os.replace(tmp, path)
+
+
+def write_json(path: Path, data) -> None:
+    write_text(path, json.dumps(data, ensure_ascii=False, indent=2) + "\n")
+
+
+def read_text(path: Path, default=None):
+    try:
+        return path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return default
+
+
+def read_json(path: Path, default=None):
+    text = read_text(path)
+    return default if text is None else json.loads(text)

folderui-0.1.0/src/folderui/server.py

@@ -0,0 +1,68 @@
+"""多人用的伺服器：一個執行緒依序處理所有客戶端的請求，並推播給客戶端。
+
+    客戶端 ──call(who, cmd)──▶ Server.handle()     請求／回應（同步）
+    客戶端 ◀──push(who, msg)── Server              推播（非同步）
+
+handle() raise 的例外會傳回呼叫端（ValueError 代表規則不允許）。
+推播走客戶端的無上限佇列，伺服器永遠不會等待客戶端，所以不會死鎖。
+"""
+import queue
+import threading
+import traceback
+
+
+class Server:
+    def __init__(self):
+        self.clients: dict = {}
+        self._requests: queue.Queue = queue.Queue()
+        self._stopped = False
+
+    # ---- 子類別實作 ----
+
+    def handle(self, who, cmd):
+        raise NotImplementedError
+
+    def on_start(self) -> None:
+        pass
+
+    # ---- API ----
+
+    def connect(self, who, client) -> None:
+        """註冊一個可以接收推播的客戶端（任何有 push(msg) 的物件）。"""
+        self.clients[who] = client
+
+    def call(self, who, cmd, timeout: float = 30):
+        box: queue.Queue = queue.Queue(maxsize=1)
+        self._requests.put((who, cmd, box))
+        try:
+            ok, value = box.get(timeout=timeout)
+        except queue.Empty:
+            raise TimeoutError("伺服器沒有回應") from None
+        if ok:
+            return value
+        raise value
+
+    def push(self, who, msg) -> None:
+        self.clients[who].push(msg)
+
+    def start(self) -> threading.Thread:
+        t = threading.Thread(target=self.run, name="folderui:server", daemon=True)
+        t.start()
+        return t
+
+    def stop(self) -> None:
+        self._stopped = True
+
+    def run(self) -> None:
+        self.on_start()
+        while not self._stopped:
+            try:
+                who, cmd, box = self._requests.get(timeout=0.2)
+            except queue.Empty:
+                continue
+            try:
+                box.put((True, self.handle(who, cmd)))
+            except Exception as e:
+                if not isinstance(e, ValueError):
+                    traceback.print_exc()
+                box.put((False, e))

folderui-0.1.0/src/folderui/session.py

@@ -0,0 +1,44 @@
+"""程式型 agent 用的客戶端：和按鈕腳本走同一個檔案協定。"""
+import json
+import time
+from pathlib import Path
+
+from .fsutil import read_text, write_text
+
+
+class Session:
+    def __init__(self, path: str | Path, poll: float = 0.1):
+        self.root = Path(path)
+        self.poll = poll
+
+    def ready(self, timeout: float | None = None) -> bool:
+        """等到資料夾畫好（第一次可以讀到按鈕列表）。"""
+        deadline = None if timeout is None else time.monotonic() + timeout
+        while not (self.root / ".buttons.json").exists():
+            if deadline is not None and time.monotonic() > deadline:
+                return False
+            time.sleep(self.poll)
+        return True
+
+    def buttons(self) -> dict[str, dict]:
+        """目前可按的按鈕 {路徑: {hint, options}}；空的代表已結束（或還輪不到你）。"""
+        return json.loads(read_text(self.root / ".buttons.json", "{}"))
+
+    def read(self, path: str) -> str:
+        return read_text(self.root / path, "")
+
+    def press(self, path: str, *args: str, timeout: float | None = None) -> tuple[bool, str]:
+        """按下按鈕並等待回應，回傳 (是否成功, 回應內容)。"""
+        request = self.root / ".request"
+        if request.exists():
+            raise RuntimeError("上一個操作還在等待回應")
+        (self.root / ".done").unlink(missing_ok=True)
+        write_text(request, "".join(f"{x}\0" for x in (path, *args)))
+        deadline = None if timeout is None else time.monotonic() + timeout
+        while request.exists():
+            if deadline is not None and time.monotonic() > deadline:
+                raise TimeoutError("等待回應逾時")
+            time.sleep(self.poll)
+        code, _, text = read_text(self.root / ".response", "1\n").partition("\n")
+        (self.root / ".done").unlink(missing_ok=True)
+        return code.strip() == "0", text.rstrip("\n")

folderui-0.1.0/src/folderui/ui.py

@@ -0,0 +1,261 @@
+"""FolderUI：把一個資料夾變成給人類或 AI agent 用的立即式 GUI。
+
+子類別實作三個方法：
+    draw()                 每一幀重新宣告畫面：file()、button()、reply()。不可修改狀態。
+    action(name, args)     按鈕被按下時呼叫：回傳文字，或 raise 代表失敗。只有這裡修改狀態。
+    receive(msg)           收到 push() 的訊息（例如伺服器推播）。
+
+資料夾裡只有 draw() 宣告的檔案和按鈕腳本（<path>.sh）。執行按鈕腳本後，腳本會一直等待，
+直到「操作處理完之後，第一個有按鈕可按的畫面」出現（或 close()）才回應：
+    action 的回傳值 + 這段期間的 notify() + reply() + 目前可按的按鈕
+
+腳本與主機之間的協定（隱藏檔）：
+    .request    腳本寫入：按鈕路徑與參數，以 NUL 分隔
+    .response   主機寫入：第一行為 exit code，之後為回應內容
+    .done       主機回應後把 .request 改名為 .done；腳本讀完回應後刪除它
+    .buttons.json  目前的按鈕列表（給程式型 agent 用）
+"""
+import json
+import os
+import queue
+import shlex
+import sys
+import threading
+import time
+import traceback
+from pathlib import Path
+
+from .fsutil import write_text
+
+PROTOCOL_FILES = (".request", ".request.new", ".response", ".done")
+
+SCRIPT = """\
+#!/bin/sh
+# folderui 按鈕：{name}{hint}
+cd {root} || exit 1
+printf '%s\\0' {qname} "$@" > .request.new
+if [ -e .request ]; then
+  if cmp -s .request .request.new; then
+    rm -f .request.new
+    echo "⏳ 繼續等待…" >&2
+  else
+    rm -f .request.new
+    echo "❌ 上一個操作還在等待回應；再執行一次同樣的指令可以繼續等待"
+    exit 1
+  fi
+elif [ -e .done ] && cmp -s .done .request.new; then
+  rm -f .request.new
+else
+  rm -f .done .response
+  mv .request.new .request
+  echo "⏳ 已送出，等待中…" >&2
+fi
+limit=$(( ${{FOLDERUI_TIMEOUT:-0}} * 5 )); i=0
+while [ -e .request ]; do
+  sleep 0.2; i=$((i+1))
+  if [ "$limit" -gt 0 ] && [ "$i" -ge "$limit" ]; then
+    echo "⏳ 還在等待中，再執行一次同樣的指令即可繼續等待"
+    exit 2
+  fi
+done
+code=$(head -n 1 .response)
+tail -n +2 .response
+rm -f .done
+exit "$code"
+"""
+
+
+def _check_path(path: str) -> str:
+    parts = path.split("/")
+    if path.startswith("/") or any(not p or p.startswith(".") for p in parts):
+        raise ValueError(f"路徑不能是絕對路徑、空段落或隱藏檔：{path!r}")
+    return path
+
+
+class FolderUI:
+    poll = 0.1
+    close_grace = 5.0
+
+    def __init__(self, path: str | Path):
+        self.root = Path(path).resolve()
+        self.root.mkdir(parents=True, exist_ok=True)
+        self.closed = False
+        self._inbox: queue.Queue = queue.Queue()
+        self._files: dict[str, str] = {}
+        self._buttons: dict[str, tuple[str, list[str] | None]] = {}
+        self._reply = ""
+        self._disk_files: dict[str, str] = {}      # 磁碟上由本框架管理的檔案
+        self._disk_scripts: dict[str, str] = {}
+        self._notes: list[str] = []
+        self._pending: tuple[int, str] | None = None
+        self._pending_button: tuple[str, str] | None = None  # (路徑, hint)：回應被讀走前保留它的腳本
+
+    # ---- 子類別實作 ----
+
+    def draw(self) -> None:
+        pass
+
+    def action(self, name: str, args: list[str]) -> str | None:
+        raise ValueError(f"沒有處理按鈕 {name}")
+
+    def receive(self, msg) -> None:
+        pass
+
+    # ---- 在 draw() 中呼叫 ----
+
+    def file(self, path: str, content: str) -> None:
+        self._files[_check_path(path)] = content
+
+    def button(self, path: str, hint: str = "", options: list[str] | None = None) -> None:
+        self._buttons[_check_path(path)] = (hint, options)
+
+    def reply(self, text: str) -> None:
+        self._reply = text
+
+    # ---- 在 action() / receive() 中呼叫 ----
+
+    def notify(self, text: str) -> None:
+        """累積一則消息，在下一次回應時一起送出。"""
+        self._notes.append(text)
+
+    def close(self) -> None:
+        """結束：移除所有按鈕，回應正在等待的腳本，然後停止。"""
+        self.closed = True
+
+    # ---- 給其他執行緒 ----
+
+    def push(self, msg) -> None:
+        self._inbox.put(msg)
+
+    def start(self) -> threading.Thread:
+        t = threading.Thread(target=self.run, name=f"folderui:{self.root.name}", daemon=True)
+        t.start()
+        return t
+
+    # ---- 主迴圈 ----
+
+    def run(self) -> None:
+        for name in PROTOCOL_FILES:
+            (self.root / name).unlink(missing_ok=True)
+        self._redraw()
+        deadline = None
+        while not (self.closed and self._pending is None and self._pending_button is None):
+            if self.closed and self._pending is None:  # 已結束：最後的回應最多等 close_grace 秒被讀走
+                deadline = deadline or time.monotonic() + self.close_grace
+                if time.monotonic() > deadline:
+                    break
+            changed = False
+            try:
+                msg = self._inbox.get(timeout=self.poll)
+                self._call(self.receive, msg)
+                changed = True
+            except queue.Empty:
+                pass
+            changed |= self._take_request()
+            changed |= self._drain()
+            if self._pending is None and self._pending_button and not (self.root / ".done").exists():
+                self._pending_button = None  # 回應已被讀走
+                changed = True
+            if changed:
+                self._redraw()
+            if self._pending is not None and (self._buttons or self.closed):
+                self._respond()
+
+    def _drain(self) -> bool:
+        changed = False
+        while True:
+            try:
+                msg = self._inbox.get_nowait()
+            except queue.Empty:
+                return changed
+            self._call(self.receive, msg)
+            changed = True
+
+    def _take_request(self) -> bool:
+        if self._pending is not None:
+            return False
+        try:
+            raw = (self.root / ".request").read_bytes()
+        except FileNotFoundError:
+            return False
+        name, *args = [x.decode("utf-8", "replace") for x in raw.split(b"\0")[:-1]] or [""]
+        if name not in self._buttons:
+            self._pending = (1, f"❌ 按鈕 {name} 已經不存在")
+            return True
+        self._pending_button = (name, self._buttons[name][0])
+        try:
+            result = self.action(name, args)
+            self._pending = (0, result or "")
+        except Exception as e:
+            if not isinstance(e, ValueError):  # ValueError 視為使用者錯誤，其餘是程式 bug
+                traceback.print_exc()
+            self._pending = (1, f"❌ {e}")
+        return True
+
+    def _respond(self) -> None:
+        code, text = self._pending
+        parts = [text] if text else []
+        parts += self._notes
+        if self._reply:
+            parts.append(self._reply)
+        if self.closed:
+            parts.append("── 已結束 ──")
+        else:
+            lines = ["── 可以做的事 ──"]
+            for path, (hint, options) in self._buttons.items():
+                lines.append(f"./{path}.sh" + (f"  {hint}" if hint else ""))
+                if options:
+                    lines.append("    選項：" + " / ".join(options))
+            parts.append("\n".join(lines))
+        write_text(self.root / ".response", f"{code}\n" + "\n\n".join(parts) + "\n")
+        os.replace(self.root / ".request", self.root / ".done")
+        self._notes = []
+        self._pending = None
+
+    def _redraw(self) -> None:
+        self._files, self._buttons, self._reply = {}, {}, ""
+        self._call(self.draw)
+        if self.closed:
+            self._buttons = {}
+        scripts = {f"{p}.sh": self._script(p, hint) for p, (hint, _) in self._buttons.items()}
+        if self._pending_button:  # 逾時後重新執行同一個指令＝繼續等待或拿回應，所以腳本要留到回應被讀走
+            name, hint = self._pending_button
+            scripts.setdefault(f"{name}.sh", self._script(name, hint))
+        self._sync(self._disk_files, self._files, None)
+        self._sync(self._disk_scripts, scripts, 0o755)
+        write_text(self.root / ".buttons.json", json.dumps(
+            {p: {"hint": h, "options": o} for p, (h, o) in self._buttons.items()},
+            ensure_ascii=False, indent=2) + "\n")
+
+    def _sync(self, disk: dict[str, str], want: dict[str, str], mode: int | None) -> None:
+        for path in set(disk) - set(want):
+            (self.root / path).unlink(missing_ok=True)
+            self._prune(self.root / path)
+            del disk[path]
+        for path, content in want.items():
+            if disk.get(path) != content:
+                target = self.root / path
+                target.parent.mkdir(parents=True, exist_ok=True)
+                write_text(target, content, mode)
+                disk[path] = content
+
+    def _prune(self, path: Path) -> None:
+        for d in path.parents:
+            if d == self.root:
+                return
+            try:
+                d.rmdir()
+            except OSError:
+                return
+
+    def _script(self, name: str, hint: str) -> str:
+        hint = " ".join(hint.split())
+        return SCRIPT.format(name=name, hint=f" — {hint}" if hint else "",
+                             root=shlex.quote(str(self.root)), qname=shlex.quote(name))
+
+    def _call(self, fn, *args) -> None:
+        try:
+            fn(*args)
+        except Exception:
+            print(f"[folderui:{self.root.name}] {fn.__name__}() 發生錯誤：", file=sys.stderr)
+            traceback.print_exc()

folderui-0.1.0/tests/test_folderui.py

@@ -0,0 +1,166 @@
+import os
+import subprocess
+import threading
+import time
+
+import pytest
+
+from folderui import FolderUI, Server, Session
+
+
+class Counter(FolderUI):
+    """單人：add 會加一，到 3 就結束。"""
+
+    def __init__(self, path):
+        super().__init__(path)
+        self.n = 0
+
+    def draw(self):
+        self.file("count.md", f"{self.n}\n")
+        self.button("add", "<1-3>")
+        self.reply(f"目前 {self.n}")
+
+    def action(self, name, args):
+        if args != ["1"]:
+            raise ValueError("只能加 1")
+        self.n += 1
+        if self.n == 3:
+            self.close()
+        return f"加到 {self.n}"
+
+
+@pytest.fixture
+def counter(tmp_path):
+    ui = Counter(tmp_path / "ui")
+    thread = ui.start()
+    s = Session(ui.root)
+    assert s.ready(timeout=5)
+    yield ui, s
+    ui.close()
+    thread.join(timeout=5)
+
+
+def test_session_press(counter):
+    ui, s = counter
+    assert set(s.buttons()) == {"add"}
+    ok, text = s.press("add", "2", timeout=5)
+    assert not ok and "只能加 1" in text
+    ok, text = s.press("add", "1", timeout=5)
+    assert ok and text.startswith("加到 1") and "./add.sh" in text
+    assert s.read("count.md") == "1\n"
+
+
+def test_close_removes_buttons(counter):
+    ui, s = counter
+    for _ in range(3):
+        ok, text = s.press("add", "1", timeout=5)
+    assert ok and "已結束" in text
+    assert s.buttons() == {}
+    for _ in range(50):  # 回應被讀走後，下一幀才會移除保留的腳本
+        if not (ui.root / "add.sh").exists():
+            break
+        time.sleep(0.1)
+    assert not (ui.root / "add.sh").exists()
+
+
+def test_shell_button(counter):
+    ui, s = counter
+    r = subprocess.run([str(ui.root / "add.sh"), "1"], capture_output=True, text=True, timeout=10)
+    assert r.returncode == 0 and "加到 1" in r.stdout
+    r = subprocess.run([str(ui.root / "add.sh"), "x"], capture_output=True, text=True, timeout=10)
+    assert r.returncode == 1 and "只能加 1" in r.stdout
+
+
+class ReadyServer(Server):
+    """兩個人都按 ready 才一起開始。"""
+
+    def __init__(self):
+        super().__init__()
+        self.ready: set = set()
+
+    def handle(self, who, cmd):
+        self.ready.add(who)
+        if len(self.ready) == len(self.clients):
+            for p in self.clients:
+                self.push(p, "go")
+        return "✅ 準備好了"
+
+
+class Lobby(FolderUI):
+    def __init__(self, path, server, me):
+        super().__init__(path)
+        self.server, self.me, self.state = server, me, "lobby"
+
+    def draw(self):
+        if self.state == "lobby":
+            self.button("ready")
+        elif self.state == "waiting":
+            pass  # 沒有按鈕 → 腳本繼續等
+        else:
+            self.button("play")
+
+    def action(self, name, args):
+        if name == "ready":
+            self.state = "waiting"
+            return self.server.call(self.me, "ready")
+        self.close()
+        return "played"
+
+    def receive(self, msg):
+        self.state = "started"
+        self.notify("🔔 開始了")
+
+
+def test_multiplayer_blocks_until_everyone_ready(tmp_path):
+    server = ReadyServer()
+    uis = {p: Lobby(tmp_path / f"p{p}", server, p) for p in range(2)}
+    for p, ui in uis.items():
+        server.connect(p, ui)
+    server.start()
+    threads = [ui.start() for ui in uis.values()]
+    s0, s1 = Session(uis[0].root), Session(uis[1].root)
+    assert s0.ready(timeout=5) and s1.ready(timeout=5)
+
+    result = {}
+    t = threading.Thread(target=lambda: result.update(r=s0.press("ready", timeout=10)))
+    t.start()
+    t.join(timeout=0.5)
+    assert t.is_alive()  # 另一個人還沒準備好，p0 的按鈕卡住
+
+    ok, text = s1.press("ready", timeout=10)
+    t.join(timeout=10)
+    assert ok and "開始了" in text and "./play.sh" in text
+    ok, text = result["r"]
+    assert ok and "開始了" in text
+
+    for s in (s0, s1):
+        s.press("play", timeout=10)
+    for th in threads:
+        th.join(timeout=5)
+    server.stop()
+
+
+def test_timeout_and_resume(tmp_path):
+    server = ReadyServer()
+    uis = {p: Lobby(tmp_path / f"p{p}", server, p) for p in range(2)}
+    for p, ui in uis.items():
+        server.connect(p, ui)
+    server.start()
+    for ui in uis.values():
+        ui.start()
+    assert Session(uis[0].root).ready(timeout=5)
+    script = str(uis[0].root / "ready.sh")
+    env = {**os.environ, "FOLDERUI_TIMEOUT": "1"}
+
+    r = subprocess.run([script], capture_output=True, text=True, timeout=10, env=env)
+    assert r.returncode == 2  # 逾時，但請求已送出
+
+    r = subprocess.run([script, "other"], capture_output=True, text=True, timeout=10, env=env)
+    assert r.returncode == 1 and "還在等待" in r.stdout  # 不同的指令會被拒絕
+
+    Session(uis[1].root).press("ready", timeout=10)
+    r = subprocess.run([script], capture_output=True, text=True, timeout=10, env=env)
+    assert r.returncode == 0 and "開始了" in r.stdout  # 同樣的指令 → 拿到回應
+    for ui in uis.values():
+        ui.close()
+    server.stop()