前言¶

DeepSeek Harness（DSH）把 Agent Loop、工具、Session、權限等運行時能力做成可插拔的 bundle，但日常開發往往仍需要一個在終端裏就能完成對話、審批和會話管理的界面。Web 或 headless profile 能跑通流程，卻不一定適合長時間盯着 Transcript、切換 Session、或一邊改代碼一邊跟 Agent 交互。

dsh-pi-tui 是 XMoon 維護的第三方客戶端插件，基於 vendored fork 的 Pi TUI，作爲獨立 bundle 裝進 profile，專門承擔終端交互層。模型、工具、Session 持久化、Skills、Plan、Goal、Subagent 等能力仍由 DSH 提供；TUI 負責流式展示、按鍵、Slash Command 和狀態行。下面介紹它的定位、核心能力與安裝用法。

這是什麼¶

@xmoon76/dsh-pi-tui（社區目錄名 xmoon/dsh-pi-tui）是 MIT 許可的 npm 包，當前版本 0.3.4。README 將其定位爲「基於 Pi TUI 的 DeepSeek Harness 終端前端」——安裝包內已包含運行所需的 Pi TUI fork，用戶無需單獨安裝內部 TUI package。

插件分類爲「客戶端」。GitHub 倉庫 XMoon/dsh-pi-tui 約 11 stars。它與 DeepSeek / 幻方無官方從屬關係；社區目錄 SkillHub 是獨立的插件收錄站點，DSH 生態遵循「一切皆插件」的思路，目錄站並不等同於官方應用商店。

對話、Focus 與工具展示¶

TUI 側覆蓋日常對話所需的可視化與交互：

1. 流式 Markdown 輸出，Thinking 可摺疊（Alt+T），Tool Call 以卡片展示運行狀態。
2. Tool / System 詳情默認摺疊，Ctrl+O 展開；全屏 Focus 下 Ctrl+O 改爲整體切換最近幾個 Thought root。
3. Transcript 全文搜索（Ctrl+F），長會話歷史可摺疊。
4. 狀態區顯示 Context、Token、模型與運行狀態；支持 Approval、ask_user_question、Plan Review、Todo / Goal 展示。

Focus Mode 用 /focus 進入：運行中的 Thinking、Tool Call 和中間回覆會聚合爲一個即時更新的 Thought 區塊。需要看過程時可展開；關閉 Focus 後恢復普通 Transcript。Focus 只改變界面投影，不修改 Session 裏保存的事件。

Session 與輸入歷史¶

插件對接 DSH 持久化 Session，支持新建與恢復、切換、重命名、Fork、Rewind、Session lineage、Transcript 導出。常用 Slash Command：

/sessions
/fork
/rewind

空閒且編輯器爲空時，連按兩次 Esc 也可打開 Rewind。Rewind 會從選中的歷史 User Turn 創建新的 Child Session，並把對應 Prompt 放回編輯器；原 Session 不會被修改。

輸入歷史用 Ctrl+R 搜索，範圍可選 Current session、Current directory、All directories。結果含 Prompt、工作目錄、時間和 Session 信息；選中後只恢復到編輯器，不會立即發送。↑ / ↓ 仍用於瀏覽最近輸入。

Subagent、Shell 與文件引用¶

/tasks 打開當前 Session 的任務瀏覽器。Subagent 按完整 lineage 樹形展示（含嵌套 descendant），並區分 continuable、one-shot、running / inactive、嵌套 descendant、後臺 Job。已結束的 one-shot Subagent 仍可查看持久化 Transcript。對當前 Session 的直接 continuable Child，可進入交互式 Viewer 並繼續發消息；更深層 nested Subagent 默認只讀。

Shell 有兩種編輯器模式（! / !! 是模式切換，不是普通文本前綴）：

! git status

執行本地命令，輸出進入當前 Session。

!! git status

僅在本地執行，輸出不進入模型上下文。

輸入 @ 可搜索並補全工作區文件，例如 @src/index.ts 或 @"path with spaces/file.ts"；可解析的相對路徑在提交時會轉爲明確文件路徑。Ctrl+V 可粘貼剪貼板圖片，通過 DSH Attachment 保存到 Session。

設置、Footer 與快捷鍵¶

模型與運行設置沿用 DSH 服務，常用入口包括 /model、/settings、/login、/permission、/plan、/goal、/compact、/footer、/statusline。其他插件註冊到 ctx.commands 的 Slash Command 會被自動發現。/settings 裏可切換 Icon style（Emoji / Symbols / Minimal）。

Footer 是可組合的狀態表面。/settings 的 Status line 或設置文檔中的 footer 鍵可選 default（舊名 full）、compact、custom；command 模式只能通過 USER 層設置文檔啓用。/footer 提供交互式配置器；footerLayout 支持左右區域、分隔符和多種內置條目 id。footer: command 時，狀態快照以 JSON 寫入用戶命令 stdin，stdout 經淨化後渲染；僅 USER 層配置的命令會執行，倉庫/項目層提供的 footerCommand 不會執行。

常用按鍵摘要（完整表見 TUI 內 /help）：

快捷鍵可在 dsh-pi-tui 設置命名空間裏按語義 action（app.*）覆蓋，改完後執行 /keybindings reload 即生效。環境變量 DSH_PI_TUI_SAFE_KEYBINDINGS=1 可忽略全部用戶覆蓋。

Extension API¶

除作爲終端前端使用外，包還提供版本化 Extension API，供其他 Cordis / DSH 插件擴展界面。公開入口包括：

可擴展 Header / Footer、Input Widget、Slash Command、Theme、Message / Tool Renderer、Overlay 等。插件只需依賴公開入口，不必 import 內部 TuiApp 實現。Stable API 還支持通過 chrome.footer.item 槽位貢獻可配置的 Footer 條目。

安裝與啓用¶

環境要求：

• 已安裝 DeepSeek Harness
• Node.js ^22.19.0 || >=24

項目當前跟隨 DeepSeek Harness 0.1.1-rc.x 版本線開發。推薦使用單獨的 pi-tui profile 安裝並啓動：

dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui
dsh --profile pi-tui

恢復已有 Session：

dsh --profile pi-tui --session <session-id>

更新、列出、卸載：

dsh plugin --profile pi-tui -- update @xmoon76/dsh-pi-tui
dsh plugin --profile pi-tui -- list
dsh plugin --profile pi-tui -- remove @xmoon76/dsh-pi-tui

經過上面的步驟，TUI 可與同一套運行時數據下的其他 Surface 並存，例如 dsh --profile web、dsh --profile headless、dsh --profile pi-tui。

適用場景與注意¶

適合需要在終端長時間使用 DSH、且希望流式 Transcript、Session 管理、Subagent 瀏覽和 Shell 集成都留在同一界面的開發者。若你主要用 Web UI 或腳本化 headless，不必強制換 TUI；但若要在 pi-tui profile 裏獲得完整交互，這個 bundle 是 README 推薦的終端前端方案。

安裝前請注意：插件以當前 dsh 進程權限運行，Shell 模式（!）會把命令輸出提交到 Session；footer: command 僅在 USER 層設置下執行用戶配置的腳本。安裝前應閱讀源碼與 MIT 許可證，確認符合你的安全與合規要求。SkillHub 目錄頁與 GitHub 倉庫是同一插件的兩個入口，安裝命令以 README 中的 dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui 爲準，不要憑倉庫名自行拼接 github:owner/repo 形式。

dsh-pi-tui 把 Pi TUI 的終端體驗接到 DSH 運行時上：交互在 TUI，能力在 Harness。需要進一步瞭解架構、Extension API 或性能基線，可查閱倉庫 docs/ 目錄與 Extension API 文檔。

• 社區目錄：https://www.skillhub.cn/plugins/XMoon/dsh-pi-tui
• GitHub：https://github.com/XMoon/dsh-pi-tui