remorses/tuistory

解決的問題

Tuistory 允許 AI 代理與長期執行的終端程序（例如開發伺服器、REPL 和互動式 CLI）互動，而不會阻塞其執行。它解決了代理在啟動伺服器時掛起，或必須依賴盲目的 sleep 命令來猜測程序是否準備就緒的問題。

工作原理

Tuistory 將終端命令包裝在由中繼守護程序管理的命名背景會話中。這種架構允許人類與 AI 代理連接到同一會話。人類可以以互動方式附加到終端（類似於 tmux），而代理則使用 CLI 或程式化 API 來讀取日誌、等待特定文字模式（正規表示式）、拍攝螢幕快照，並向程序發送鍵盤輸入。

適用對象

• AI 代理開發者：需要執行與監控開發伺服器或使用互動式終端工具的編碼代理開發者
• TUI 開發者：需要自動化或測試的終端使用者介面開發者
• 自動化工程師：希望以程式化方式控制 TTY 程式的使用者

主要特色

• 反應式等待：以 wait 和 wait-idle 命令取代盲目的 sleep，能即時回應終端輸出。
• 共享狀態：人類與代理可共享同一終端會話，允許人類在代理啟動的程序上介入並互動。
• 程式化控制：提供 TypeScript 套件，功能類似「終端版 Playwright」，可精確控制 PTY。
• 視覺化檢視：支援將目前終端螢幕擷取為文字快照或 PNG 圖像。
• CWD 與環境繼承：將呼叫 shell 的完整環境與 PATH 傳遞給子程序。
• 冪等執行：透過重新連接至現有會話而非失敗，避免「埠口已被使用」錯誤。