前言¶
DeepSeek Harness（下文簡稱 DSH）把模型、工具、會話、技能、UI 都做成可替換的插件，官方倉庫的定位就是「一切皆插件」。它目前仍是開發者預覽版，核心 API 還會變。對剛上手的人來說，更直接的缺口往往不是內核，而是現成能力：聯網搜索、跨會話記憶、代碼導航、子代理、看圖，原生生態裏還沒有完全鋪開。
Pi（https://pi.dev/）那邊已經有一套成熟的擴展生態，公開發布的包數量以百計。問題是兩邊的插件 ABI 並不相同：Pi 擴展面向自己的 Host 表面，DSH 插件則掛在 Cordis 服務上。把每個 Pi 包裝成一份 DSH 適配器，既費事，也難跟上游同步。
pi2dsh 做的是另一件事：實現一層 Pi 的公開擴展 ABI，把未修改的 Pi 包當作普通 DSH 插件來掛載。本文依據社區插件目錄頁、GitHub 倉庫 README（含中文版）、npm 上的 0.12.3 版本說明，以及 DeepSeek 官方 Harness 倉庫交叉覈實後整理。社區目錄站點與 DeepSeek / 幻方沒有官方從屬關係，不要把它當成官方應用商店。
這是什麼¶
pi2dsh 是一款開發與運行時插件，由 weijiafu14 維護，許可證爲 MIT，主要語言是 TypeScript。npm 與 package.json 上的當前版本是 0.12.3（2026-08-16 發佈）。GitHub 倉庫 weijiafu14/pi2dsh 在 2026-08-18 查閱時顯示 21 stars；社區目錄頁當時仍顯示 8，星標以倉庫頁面爲準。
它的定位可以壓成一句話：一層通用的 Pi Host ABI，讓 未修改 的 Pi 擴展以原生 DSH 插件的方式運行。倉庫自己也寫得很明確——這是橋，不是終點。哪天 DSH 生態裏出現了更好的原生插件，就應該換過去。
運行要求在 README 裏寫死了：需要 Node.js 22.19+ 和已經能跑起來的 DeepSeek Harness。
核心能力¶
pi2dsh 不是給每個 Pi 包寫一份補丁。README 裏的模型是：先裝一次引擎，之後用 dsh plugin add 直接加 npm 上的 Pi 原包。沒有轉換步驟，也沒有生成一份新的 bundle。
三層、互不越界¶
倉庫用三層來說明職責：
- Pi 插件仍是原樣的 npm 包。它看到的是完整的 Pi 宿主：三個運行時導入、
registerX、ctx.*、生命週期事件，並不知道 DSH 的存在。 - pi2dsh 是唯一同時懂兩邊詞彙的翻譯層：目錄投影、事件橋、會話與子代理橋、憑證，以及 vendored 的 Pi 邏輯。
- DeepSeek Harness 只看到一個普通插件加 llm adapter，並不知道 Pi 的存在。
瀏覽器殼另有半邊：側邊對話浮層、header、widget dock、working 區等呈現面走本包自己的路由，不佔用 DSH 一等公民的 typed Remote 契約。
幾條實現原則在 README 裏寫得很硬：DSH 已經有的能力不再造一遍（工具進 DSH 工具註冊表，MCP 交給 dsh-mcp-client，skills 交給 dsh-skill-filesystem）；用戶側配置保持 DSH 形狀；核心沒有 if (packageName === …) 這種逐包特判；映射不了的能力會明說，而不是假裝成功。
能力面覆蓋（以倉庫表格爲準）¶
README 給出的能力矩陣是從運行時規則生成的，合計 112 個 Pi 面：24 個語義一致，83 個已映射並寫明差異，5 個刻意不提供。另外還用 vendored / headless shim 提供 Pi 三個運行時包（pi-coding-agent、pi-tui、pi-ai）的 202 個導入符號，避免插件自己釘的 Pi 版本被加載。
刻意不提供的部分包括：運行時裝包、獨立模型運行時、provider 的 payload/header/response 攔截，以及項目信任決策——這些仍歸宿主。倉庫自己承認還欠一塊：插件自繪卡片目前會接下注冊但不調用，內容會變成原生上下文注入行，沒有插件自己的樣式。
訂閱登錄也能走通。DSH 本身只提供靜態 HTTP header，橋補上了 Pi 的交互式 OAuth。聲明瞭 oauth 塊的 Pi provider 會得到 /login <name>；README 寫明內置了 OpenAI Codex、Anthropic、GitHub Copilot、Kimi Code 四條官方流程。憑證按 Pi 的 auth.json 語義持久化，再通過標準 dsh-credentials provider 驅動 DSH 原生 llm 路徑。
今天哪些算「真能用」¶
倉庫把驗證分成兩級，這兩級證明的事情不一樣。
第一級是端到端實測，並且儘量配可跑示例。截至 README 當前內容，名單如下：
| 插件 | 驗證了什麼 | 示例 |
|---|---|---|
@kassing/pi-vision |
圖片委託給視覺模型，分析結果注入純文本模型這一輪 | examples/vision-bridge/ |
pi-btw |
/btw 在 DSH 子代理界面裏開真子會話 |
examples/side-conversation/ |
pi-powerline-footer |
終端狀態條畫進 DSH 的 widget dock | examples/presentation-surfaces/ |
pi-vision-tool |
工具註冊，JSON Schema 的 anyOf 轉成 DSH 的 oneOf |
示例待補 |
pi-approval-guardian |
工具調用先由第二個模型審批 | 示例待補 |
pi-hermes-memory |
跨會話記憶：一個進程寫入，另一個全新進程讀回 | 示例待補 |
第二級是把 Pi 目錄月下載量前 50 的包掛進真實 DSH 運行時，再用黑盒探針去調註冊面。狀態截至 2026-08-14：50 個裏 47 個探針調用成功，1 個沒有可探測面，2 個待復跑。倉庫自己提醒：這一級只能說明「橋覆蓋了這個插件用到的面」，不能說明真實工作流已經跑通。pi-btw 就是反例——探針長期顯示 working，真實會話裏 /btw 卻失敗，直到 0.11.0 補上兩個 ABI 缺口。
所以後面如果要裝第一級以外的包，應先當作試驗，而不是當作已知可用。
引擎之外還有三個輔助命令：
npx pi2dsh inspect <包名>@<版本> # 升級前的兼容性報告
npx pi2dsh matrix --json # 完整能力矩陣
npx pi2dsh mcp-config # Pi 的 mcpServers 配置 → DSH 官方 MCP 條目
安裝與啓用¶
社區目錄頁給出的安裝命令如下，在 DeepSeek Harness 終端裏運行即可：
dsh plugin add github:weijiafu14/pi2dsh
如需可復現安裝，目錄頁建議固定 commit 哈希：
dsh plugin add github:weijiafu14/pi2dsh#<commit>
倉庫 README 的日常寫法是走 npm 包名，並指定帶界面層的 profile。DSH 只爲 web 和 headless 內置了模板；用別的名字新建 profile 時，可能沒有任何界面層，起來之後會掛住且不報錯——這跟 pi2dsh 無關，但第一次安裝很容易撞上。
dsh plugin --profile web add pi2dsh
dsh plugin --profile web add @kassing/pi-vision
裝完需要 重啓 dsh，插件在啓動時掛載。
日常增刪和升級（來自 README）：
dsh plugin add <包名> # 然後重啓
dsh plugin remove <包名> # 先卸插件，再卸引擎
dsh plugin add <包名>@latest # 只升級某個 Pi 插件
dsh plugin add pi2dsh@latest # 只升級引擎
npx pi2dsh inspect <包名>@<版本> # 升級前先體檢
兩條安裝期提示值得提前知道：
- 若出現
ERR_PNPM_IGNORED_BUILDS，說明 pnpm 默認攔截了依賴的構建腳本。需要在$DSH_HOME/profiles/web裏執行pnpm approve-builds，或把提示中的包寫進該 profile 的pnpm-workspace.yaml的allowBuilds，再重跑 add。橋不會替你繞過這一步。 - 剛發版後
add有時會裝到舊版本，原因是 pnpm 的minimumReleaseAge會跳過剛發佈不久的包。顯式釘版本即可，例如dsh plugin add pi2dsh@0.12.3。
目錄頁也寫了安全邊界：插件以當前 dsh 進程的權限運行，安裝時可能執行代碼。安裝前應檢查源代碼倉庫和許可證。
典型用法：給純文本模型看圖¶
倉庫把 @kassing/pi-vision 當作最能說明這座橋值什麼的例子。DeepSeek 系列是純文本模型，DSH 不能把圖片直接發給它。Pi 生態裏的這個插件會把圖片交給你指定的視覺模型，再把分析注入回對話。
先確保已經裝了引擎，再裝這個插件：
dsh plugin --profile web add @kassing/pi-vision
然後給它單獨配一個多模態端點。這個模型和你聊天用的主模型不是同一個。README 舉例使用 OpenRouter 上的 Qwen-VL；DashScope / 自建 vLLM 這類 OpenAI 兼容端點也可以。
export VISION_BRIDGE_BASE_URL=https://openrouter.ai/api/v1
export VISION_BRIDGE_MODEL=qwen/qwen2.5-vl-72b-instruct
export VISION_BRIDGE_API_KEY=$OPENROUTER_API_KEY
如果還想讓這個視覺模型出現在 DSH 自己的模型選擇器裏，再按普通 DSH 路由配一份，寫在 $DSH_HOME/settings.yaml 的 llm-pi-ai: 段：
llm-pi-ai:
providers:
openrouter:
baseUrl: https://openrouter.ai/api/v1
apiKeyEnv: OPENROUTER_API_KEY
models:
- id: qwen/qwen2.5-vl-72b-instruct
橋自己不持有模型配置，也不需要手寫 Pi 格式文件。視覺後端不要選 GPT-5 / o 系列：那一代模型會拒絕非默認的 temperature，而有些視覺插件會帶這個參數。
CLI 裏可以直接提圖片路徑：
dsh --profile web "$PWD/photo.png 這張圖是什麼顏色？只答一個詞。"
Web 界面裏可以直接粘圖。DSH 正常情況下會拒絕給純文本模型上傳圖片，所以引擎會給模型目錄裏每一個純文本路由自動註冊一條伴生路由，名字是 <路由>-vision，在選擇器裏顯示爲 “+ Vision Bridge” 分組。選它、粘圖、提問。像素不會進入純文本那條調用線；你會看到一行 pi2dsh:@kassing/pi-vision 的上下文注入帶着分析結果。
若要關掉伴生路由，在 $DSH_HOME/profiles/web/cordis.patch.yml 裏寫：
- id: pi2dsh
config:
visionCompanions: false
完整可跑版本（含探針圖）在倉庫的 examples/vision-bridge/。另一條已驗證路徑是 pi-btw：在對話裏用 /btw <問題> 開一條側邊線程，主會話保持乾淨，示例在 examples/side-conversation/。
適用場景與注意事項¶
比較適合這幾類人：已經在用 DSH，但暫時缺原生插件；手上有現成的 Pi 包，不想 fork 一份；需要先把看圖、側邊對話、跨會話記憶這類能力接進來，等 DSH 原生生態跟上再遷走。
使用時有幾件事需要單獨說清楚：
- 驗證分級不要混讀。 第一級名單纔是倉庫自己說「要信就信這張表」的部分；第二級的 top 50 探針只能說明掛載面被覆蓋。倉庫明確寫了：前 50 之外不是另一類情況，橋裏沒有任何逐包代碼，撞上 ABI 缺口時修的是缺口本身。
- profile 名字用
web或headless。 自定義名字容易得到一個沒有界面層的空 profile。 - 插件以當前 dsh 進程權限運行。 安裝前檢查源碼和許可證；供應鏈敏感的環境應固定 commit 或版本號。Pi 插件同樣可以執行代碼並影響智能體行爲。
- 已知缺口。 插件自繪卡片目前沒有按插件樣式渲染；映射不到的能力會提示或整包標成不可用。
- 社區目錄不是官方商店。 本文用到的目錄頁是獨立站點。DSH 本體以 https://github.com/deepseek-ai/deepseek-harness 爲準，官方頁面也寫明仍處於開發者預覽、存在破壞性變更。
小結¶
pi2dsh 把 Pi 的公開擴展 ABI 接到 DSH 的原生服務上，讓未修改的 Pi 包可以按 DSH 插件的方式安裝和運行。它解決的是生態時差，而不是替代 DSH 自己的插件體系。當前版本是 0.12.3，MIT 許可，維護者是 weijiafu14。
目錄頁：https://deepseek-harness-plugin.com/zh-CN/plugins/pi2dsh/
GitHub：https://github.com/weijiafu14/pi2dsh
