前言¶

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