前言¶
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
