# 策展 · X (Twitter) 🔥

> 作者：3ene (@BBleimschein) · 平台：X (Twitter) · 日期：2026-03-21

> 原始來源：https://x.com/BBleimschein/status/2034959936346521860

## 中文摘要

這是一個關於為 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 展示了相反的可能性：提供原始工具讓使用者打造符合個人工作流程的介面。

## 標籤

Agent, 開源專案, 教學資源, Bash, Pi, Telegram