前言¶

DeepSeek Harness（DSH）把「一切皆插件」貫徹得很徹底：會話日誌可重建、服務組合清晰、Agent 循環也足夠透明。但對很多剛接觸 DSH 的開發者來說，一個現實問題是——生態還處在早期。大家開箱就想要的聯網搜索、跨會話記憶、代碼導航、子代理、看圖分析等能力，在 DSH 原生插件庫裏未必已經齊備。

另一邊，Pi 的擴展生態已經相當成熟：npm 上發佈了數百個包，不少都有真實用戶。如果你既認可 DSH 的架構，又不想從零重寫這些能力，pi2dsh 提供了一條務實的路徑：用一層兼容橋，把 Pi 的公開擴展 ABI 映射到 DSH 原生服務之上，讓 Pi 包以發佈原樣掛載爲 DSH 插件——不 fork、不打補丁、不爲每個包單獨寫適配器。

本文基於 SkillHub 插件目錄 與 GitHub 倉庫 的公開資料整理。SkillHub 是社區維護的 DSH 插件索引，與 DeepSeek / 幻方無官方從屬關係；安裝前請自行審閱源碼與 MIT 許可證。

這是什麼¶

pi2dsh 由社區開發者 weijiafu14 維護，在 SkillHub 上歸類爲「工作流」，GitHub 倉庫當前約 159 stars、32 forks（截至 2026-08-25 檢索）。

一句話定位：它是 Pi 與 DSH 之間的兼容層引擎。Pi 插件以爲自己運行在完整的 Pi Host 上；DSH 則把它當作普通插件加載——中間只有 pi2dsh 這一層「翻譯器」知道兩套詞彙表的存在。

架構上分三層，職責邊界清晰：

┌─ Pi 插件（未改動的 npm 包）────────────────────────────┐
│  看到完整的 Pi Host：運行時導入、registerX、生命週期事件   │
└──────────────────────────┬───────────────────────────────┘
                           │  Pi 公開 ABI
┌──────────────────────────▼───────────────────────────────┐
│  pi2dsh — 註冊表投影、事件橋、會話/子代理橋、憑證映射      │
└──────────────────────────┬───────────────────────────────┘
                           │  普通 DSH 插件 + llm adapter
┌──────────────────────────▼───────────────────────────────┐
│  DeepSeek Harness — 只看到又一個原生插件                   │
└──────────────────────────────────────────────────────────┘

核心功能與亮點¶

1. 零轉換安裝 Pi 插件¶

裝好 pi2dsh 引擎之後，後續 Pi 插件的安裝方式與裝任何 DSH 插件相同：顯式 dsh plugin add <包名>，重啓 dsh 即可掛載。沒有轉換步驟、沒有生成產物、也不需要額外構建。

2. 覆蓋 Pi 公開 ABI 的主要能力面¶

根據倉庫文檔，針對 Pi 0.84.1 的公開擴展面，橋接層維護了 111 條上游規則映射，涵蓋工具、命令、消息與會話、模型與憑證、用戶交互、項目環境等。工具走 DSH 工具註冊表，模型走 DSH 的 llm 配置，用戶問答走 DSH 官方問答通道——橋不會爲已有能力再寫一套平行實現。

3. 已有端到端驗證的插件¶

倉庫維護了兩級驗證清單。其中 Level 1 是「真人在真實 DSH 循環裏跑通過」的列表，更值得信任，例如：

此外，對 Pi 目錄月下載量 Top 50 的包做過黑盒探測：截至文檔記錄，50 箇中 47 個探測通過。需要強調的是：探測通過只說明「橋接覆蓋了該包觸及的 ABI 面」，不等於「你的具體工作流一定無坑」——倉庫也以 pi-btw 爲例說明過這類差異。

4. 附帶 CLI 工具¶

引擎之外還提供若干輔助命令：

npx pi2dsh inspect <pkg>@<version>   # 升級前做兼容性體檢
npx pi2dsh matrix --json             # 導出完整能力矩陣
npx pi2dsh mcp-config                # 將 Pi 的 mcpServers 配置翻譯爲 DSH 官方 MCP 條目

安裝與啓用¶

環境要求：Node.js 22.19+，已安裝 DeepSeek Harness。

profile 需要帶界面 bundle。DSH 內置模板有 web 與 headless；若用 dsh-tui 等自定義 profile，需先確保對應界面插件（如 @deepseek-harness-tui/dsh-tui）已寫入 dsh.profile.bundles。

基礎安裝（web profile）¶

先裝引擎，再裝你想要的 Pi 插件：

dsh plugin --profile web add pi2dsh
dsh plugin --profile web add pi-mcp-adapter

然後重啓 dsh——插件在啓動時掛載。

若你更習慣全局 profile，README 也給出簡化寫法：

dsh plugin add pi2dsh          # 裝一次引擎
dsh plugin add <任意-pi-插件>   # 之後按需追加

固定版本（可選）¶

社區目錄若支持從 GitHub 安裝，常見寫法爲 dsh plugin add github:owner/repo；pi2dsh 官方 README 以 npm 包名 pi2dsh 爲準。剛發版後若 add 裝到舊版本，可顯式釘版本：

dsh plugin add pi2dsh@<版本號>

兩條常見安裝提示¶

1. ERR_PNPM_IGNORED_BUILDS：pnpm 默認攔截依賴構建腳本。到 $DSH_HOME/profiles/<profile> 執行 pnpm approve-builds，或在 pnpm-workspace.yaml 的 allowBuilds 中放行提示的包，然後重跑 add。
2. 升級策略：升級單個 Pi 插件用 dsh plugin add <包名>@latest，引擎不動；升級引擎用 dsh plugin add pi2dsh@latest，已裝 Pi 插件不動。卸插件時先卸 Pi 包，最後再卸 pi2dsh。

典型用法：終端裏的進階 MCP¶

這個 walkthrough 最能體現 pi2dsh 的價值。dsh-TUI 自帶原生 /mcp（DSH 官方 MCP 客戶端），而 Pi 生態的 pi-mcp-adapter 提供全屏服務器管理器、工具懶加載、代理工具、JavaScript 編排多次 MCP 調用、OAuth 登錄等更完整的能力。裝上橋之後，該包無需修改即可運行。

1. 安裝¶

dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui   # profile 已存在可跳過
dsh plugin --profile dsh-tui add pi2dsh
dsh plugin --profile dsh-tui add pi-mcp-adapter

重啓 dsh。

2. 配置 MCP 服務器¶

在 dsh-TUI 中執行：

/pi-mcp setup

setup 流程可把已有宿主配置裏的 MCP 服務器定義收編進 adapter 自己的 mcp.json，無需橋專屬配置。

3. 使用¶

/pi-mcp

打開全屏交互式服務器管理器。模型經 DSH 工具註冊表獲得 mcp 與 mcpScript 工具；每個 Agent（含 /new 新建的）都有獨立連接實例。

兩條命令並存、互不替代：

/mcp       # 原生 DSH MCP 客戶端狀態
/pi-mcp    # Pi 生態 MCP 管理器

適用場景與注意事項¶

適合誰

• 已經在 Pi 生態裏用過若干擴展，遷移到 DSH 時不想重寫或維護 fork。
• 需要快速補齊 DSH 早期生態缺口：聯網搜索、記憶、子代理、MCP 編排、視覺分析等。
• 想借 Pi 的大規模插件目錄，對 DSH 插件架構做真實負載驗證的開發者。

需要注意

1. 權限與安全：插件以當前 dsh 進程的權限運行。安裝任何 Pi 包前，請閱讀其源碼、依賴與許可證；pi2dsh 本身爲 MIT 許可。
2. 能力邊界：橋接層明確不僞造成功——無法安全映射的能力會一次性、用白話報告，而不是靜默返回假數據。插件自繪卡片類 UI 目前註冊可接受但尚未完整渲染。
3. 驗證粒度：Top 50 黑盒探測與 Level 1 端到端驗證不是同一標準；上生產前建議對你關心的包單獨跑一遍真實工作流，必要時用 npx pi2dsh inspect 做升級前體檢。
4. 生態定位：SkillHub 與 pi2dsh 均屬社區貢獻，不代表 DeepSeek 官方背書；DSH 上游仍在快速迭代，個別 seam（如出站插件擴展持久事件類型）可能仍需等待官方接口完善。

小結¶

pi2dsh 解決的不是「再寫一個 MCP 客戶端」這種單點問題，而是整條 Pi → DSH 插件遷移通道：一次安裝引擎，之後 npm 上的 Pi 擴展可以按原包名逐步接入。對看重 DSH 架構、又不願放棄 Pi 生態沉澱的開發者來說，這是目前資料最完整、驗證最公開的一條兼容路線。

• 目錄頁：https://www.skillhub.cn/plugins/weijiafu14/pi2dsh
• GitHub：https://github.com/weijiafu14/pi2dsh
• DSH 官方倉庫：https://github.com/deepseek-ai/deepseek-harness