這是一個關於為 Pi 編程 Agent 打造 Telegram 遠端控制的技術案例。核心創新在於利用 Pi SDK 的開放設計，透過 Telegram 實現無縫的雙向工作階段切換，保留完整上下文。

專案背景與動機

作者長期使用 Pi 編程工具，認為它是目前最符合人工智慧原生設計的編程框架——僅提供四個核心工具（讀、寫、編輯、bash），其餘功能由 Agent 自行構建。相較之下，Claude Code 因共享使用限額導致預算浪費，而 Pi 在上下文窗口控制上更靈活。Telegram 成為遠端介面的選擇，是因為已用於 OpenClaw 操作 Agent，且 Telegram Bot API 提供動態按鈕和斜線命令，無需開發專屬應用程式。

TelePi 核心功能

TelePi 是一個完整的 Telegram Bot，封裝 Pi 的 AgentSession SDK，並非簡單代理。它支援：

• /new — 在任何已知工作區建立新工作階段（多專案時顯示選擇器）
• /sessions — 瀏覽所有工作區的所有工作階段，按專案分組，可點擊切換
• /model — 透過內嵌鍵盤即時切換 AI 模型
• /handback — 將工作階段交回 CLI（macOS 自動複製到剪貼簿）
• /abort — 取消當前操作
• 完整的 tool 執行、串流回應和速率限制重試功能

雙向工作階段切換的無損設計

工作階段切換的關鍵在於 Pi 將工作階段儲存為 JSONL 檔案（位於 ~/.pi/agent/sessions/），該檔案是唯一資訊來源。無論 CLI 或 Telegram 哪一側開啟工作階段，都會從 JSONL 項目重建完整訊息歷史記錄，因此切換本身是無損的。流程為：

• CLI → Telegram：在 Pi CLI 輸入 /handoff，擴充功能終止任何執行中的 TelePi 實例，以當前工作階段啟動 TelePi 並關閉 CLI。開啟 Telegram 後可繼續工作，包含所有上下文。
• Telegram → CLI：在 Telegram 輸入 /handback，TelePi 釋放工作階段並發送確切的 pi --session <path> 指令（macOS 複製到剪貼簿）。貼到終端機即可恢復，包含 Telegram 上發生的所有事情。

這不是同步機制，而是單一真實來源設計——JSONL 檔案就是上下文。

跨工作區感知能力

TelePi 可發現所有專案工作區的工作階段。Pi 將工作階段儲存在以工作區路徑為鑰匙的目錄中，TelePi 透過 SessionManager.listAll() 發現所有工作階段。這意味著使用者可在 Telegram 中無縫切換不同專案（如 TelePi 除錯工作階段、OpenClaw 操作任務、網站更新），每次切換都會將編程工具重新限定到正確的專案目錄，確保 bash、讀、寫、編輯操作在正確的工作區進行。

技術實現

TelePi 採用 TypeScript，使用 Grammy 處理 Telegram 端、Pi 的 AgentSession SDK 處理 Agent 端。串流回應採用防抖編輯模式：當 Agent 發出文字差異時，TelePi 累積並每 1.5 秒編輯一次 Telegram 訊息，避免觸發 Telegram 速率限制同時保持回應感。超過 Telegram 4096 字元限制的長回應會自動分割成多條訊息。工具執行內嵌顯示，支援根據詳細程度設定顯示完整輸出、摘要、僅錯誤或不顯示。

設計哲學

作者選擇 Telegram 而非專屬應用程式，因為 Telegram 已在使用中，不需開發分發、推播通知、身份驗證和 UI 渲染。這與 Pi 的極簡設計哲學相符——Pi 是最小化框架，TelePi 亦是橋接層而非產品。工作階段檔案才是真正的產品，其他一切只是讀寫該檔案的方式。

TelePi 之所以可行，根本原因在於 Pi 的 SDK 設計完全開放——AgentSession API、SessionManager、ModelRegistry 都是公開文檔化介面，第三方程式碼可自由組合。這在編程 Agent 領域極其罕見。多數編程 Agent 是封閉迴圈，TelePi 展示了相反的可能性：提供原始工具讓使用者打造符合個人工作流程的介面。