pi2dsh

English | 中文

让 Pi 生态的插件原样跑在 DeepSeek Harness 上。

dsh plugin add pi2dsh          # 装一次
dsh plugin add <任意 Pi 插件>   # 之后想装谁装谁，直接用 npm 原包

为什么有这个项目

DeepSeek Harness（DSH）的 理念值得押注——可重建的持久会话日志、干净的服务组合、一条真能讲清楚的 agent 循环。它现在缺的是插件生态：还处在早期，而大家开箱就想要的那些能力——联网搜索、 记忆、代码导航、子代理、看图——大多还没人为它写。

Pi 的生态已经成熟：几百个已发布的包，很多都有真实用户。

pi2dsh 是一层兼容层，把 Pi 的公开扩展 ABI 实现在 DSH 的原生服务之上，让 Pi 包 以发布的原样跑在 DSH 上——不 fork、不打补丁、不为每个包写适配器。你像装任何 DSH 插件一样装一个 Pi 插件，它就能用。

这是桥，不是终点。你在这里用到的每一项能力，DSH 自己的生态早晚都会有原生实现； 哪天某个能力出现了更原生、更好的插件，你就应该换过去——那正说明这座桥起到了作用。

安装

一次引擎，之后想装谁装谁：

dsh plugin --profile <你的 profile> add pi2dsh
dsh plugin --profile <你的 profile> add @kassing/pi-vision

然后重启 dsh——插件在启动时挂载。

就这一种方式。没有转换步骤，没有生成产物，不用构建。引擎会读出你 profile 里的 Pi 包（每一个都是你显式装的），用同一个桥实例挂载它们：一个模型目录、一个登录、 一个凭证存储、一个升级单元。

日常操作：

要做的事	命令
装插件	dsh plugin add <包名>（然后重启 dsh）
卸插件	dsh plugin remove <包名>——先卸插件，再卸引擎
升级插件	dsh plugin add <包名>@latest，引擎不动
升级引擎	dsh plugin add pi2dsh@latest，插件不动
升级前先体检	npx pi2dsh inspect <包名>@<版本>

两条安装期提示值得提前知道：

• ERR_PNPM_IGNORED_BUILDS：pnpm 默认拦截依赖的构建脚本。在 $DSH_HOME/profiles/<你的 profile> 里跑 pnpm approve-builds，或者把提示 里的包在该 profile 的 pnpm-workspace.yaml 的 allowBuilds 下设成 true， 然后重跑 add。（这是你的决定权，桥不会绕过它。）
• 刚发版后 add 装到了旧版本：pnpm 的 minimumReleaseAge 会跳过刚发布不久 的版本。显式钉版本即可：dsh plugin add pi2dsh@<版本>。

需要 Node.js 22.19+ 和 DeepSeek Harness。

走一遍：让纯文本模型能看图

这个例子最能说明这座桥值什么。DeepSeek 系列是纯文本模型，DSH 没法把图片发给它。 Pi 生态里正好有插件干这件事：把图片交给你指定的视觉模型，再把分析结果注入回对话。

1. 装插件

dsh plugin --profile <你的 profile> add @kassing/pi-vision

2. 给它配一个多模态模型

这一步是关键——插件需要它自己的视觉模型，这个模型和你聊天用的那个不是同一个。 任何 OpenAI 兼容的视觉端点都行（OpenRouter、DashScope/Qwen-VL、自建 vLLM……）。

插件从环境变量读自己的配置——这是 Pi 插件生态的主流做法，对你来说就是一个纯粹的 DSH 侧动作：

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

这两处都是普通的 DSH 配置。桥自己不持有任何模型配置，也没有任何需要你手写的 Pi 格式文件。

视觉后端别选 GPT-5/o 系列：那一代模型会拒绝非默认的 temperature，而有些视觉 插件会带这个参数。

3. 问一张图

CLI 里直接提路径：

dsh --profile <你的 profile> "$PWD/photo.png 这张图是什么颜色？只答一个词。"

Web 里直接粘图——哪怕你的主模型是纯文本的。DSH 正常情况下会拒绝给纯文本模型 上传图片，所以引擎会给模型目录里每一个纯文本路由自动注册一个贴图伴生路由， 名字是 <路由>-vision。在模型选择器里选它（显示为 “+ Vision Bridge” 分组）， 粘图，提问。

你会看到：你消息里的图片块变成引导文本，一行 pi2dsh:@kassing/pi-vision 的 上下文注入带着分析结果，然后你的纯文本模型照常回答图片内容。像素从没进过纯文本 那条线。

伴生路由是全自动的。想关掉、或者只给某些路由开，在引擎的插件配置里设 visionCompanions（$DSH_HOME/profiles/<你的 profile>/cordis.patch.yml）：

- id: pi2dsh
  config:
    visionCompanions: false

完整可跑版本（含纯色探针图）：examples/vision-bridge。

现在到底哪些真能用

分两级，这两件事不是一回事。

第一级——端到端实测过，配可跑示例

有人真坐下来，在真实 DSH loop 上用了这个插件的真功能，亲眼看到它工作。 要信就信这张表。

插件	验证了什么	在哪验的	示例
@kassing/pi-vision	图片委托给视觉模型；贴图伴生路由；分析结果注入纯文本模型的这一轮	CLI + Web	vision-bridge
pi-btw	/btw <问题> 跑成 DSH 子代理界面里的真子会话；/btw-inject；/btw --save；主会话保持干净	CLI + Web	side-conversation
pi-vision-tool	工具注册，且带一个 DSH 需要转换的 JSON Schema 形状（anyOf → oneOf）	CLI + Web	—
pi-approval-guardian	每次工具调用先由第二个模型审批；放行与拒绝两条路都看到了	CLI（裸环境）	—
pi-hermes-memory	跨会话记忆：一个进程写入，另一个全新进程读回	CLI	—

后三个的示例还没写。按本项目自己的规矩，补示例前必须重新端到端验证一遍，所以 这张表如实标出今天谁有示例。

第二级——能挂载，且注册面能被探针调起来

Pi 目录里月下载量前 50 的包，每个都在真实 DSH 运行时里挂载，然后用黑盒探针 调用。状态截至 2026-08-14；逐包的机器可读证据在 community/。

50 个里 47 个探针调用成功 · 1 个没有可探测面 · 2 个待复跑。

这一级不能说明的事：不能说明这个插件的真功能按你的用法能跑通。探针是拿合成 参数去调一个注册面，用户跑的是一整条工作流。pi-btw 就是最好的反例——它在这张 表里挂着"working"挂了好几周，而真实会话里 /btw <问题> 是直接失败的：这个功能 需要补两个 ABI 缺口（Pi 公开可写的 AgentState.messages，以及给桥接命令声明输入 描述符），而任何探针都不会碰到它们。两个缺口都在 0.11.0 修好了，而且都是通用修 复——同样用法的插件一起解锁。

所以下面这张表请读成"桥覆盖了这个插件用到的面"，而不是"这个插件已知可用"。 你要是试了哪个，不管成没成，反馈回来都有用。

能力	插件
MCP	pi-mcp-adapter · pi-mcp-extension
联网搜索与抓取	pi-web-access · pi-deepseek-search · pi-web-search · @ollama/pi-web-search · @juicesharp/rpiv-web-tools
代码导航与编辑	pi-lens（ast-grep）· @narumitw/pi-lsp · pi-readseek · @ff-labs/pi-fff · pi-landstrip · pi-hashline-edit-pro¹
子代理与后台任务	@tintinweb/pi-subagents · @gotgenes/pi-subagents · pi-background-tasks² · @mjasnikovs/pi-task
记忆	pi-hermes-memory · pi-goosedump
计划与目标	@narumitw/pi-goal · pi-goal-list-loop-audit · @narumitw/pi-plan-mode · @juicesharp/rpiv-todo
问你 / 审批	@juicesharp/rpiv-ask-user-question · pi-ask-user · @gotgenes/pi-permission-system · @juicesharp/rpiv-advisor
侧边对话	pi-btw · @narumitw/pi-btw
模型与 provider	pi-provider-litellm · pi-llama-cpp · pi-prompt-template-model · @vigolium/piolium
图像	@kassing/pi-vision（见上文）· @amaster.ai/pi-image-gen
外部集成	@llblab/pi-telegram · pi-cursor-sdk² · @howaboua/pi-codex-conversion · pi-agent-browser-native² · pi-harness-runtime
提示词与工作流	pi-simplify · pi-fabric² · mitsupi · pi-cc-extensions · pi-rtk-optimizer · pi-interview¹
终端装饰	pi-powerline-footer · @narumitw/pi-statusline · pi-zentui
语音	@juicesharp/rpiv-voice
用量统计	@alexanderfortin/pi-deepseek-usage³

¹ 能挂载，调用验证待复跑（装置侧的失败，不是包或桥的问题）。 ² 业务逻辑真跑到底了，然后拒绝了合成的探针参数——属于正常工作、参数校验正确。 ³ 纯事件钩子包：四个订阅全都挂上了，但每个处理器都要求有活的 DeepSeek 计费会话 （它拉账单用量并渲染 footer），黑盒探针没有可安全断言的调用面。

前 50 之外的包不是另一类情况——桥里没有任何逐包代码。哪个包撞上 ABI 缺口，补上 那个缺口，撞同一处的包一起解锁。

第一级是靠一个一个啃第二级长出来的。完整的验证阶梯、以及每一级分别能证明什么、 不能证明什么：support matrix。

技术架构

三层，谁也不跨谁：

┌─ Pi 插件 ───────────────────────────────────────────────────┐
│ 原样的 npm 包。它看到的是一个完整的 Pi 宿主：三个 Pi 运行时  │
│ 导入、registerX、ctx.*、33 个生命周期事件。它永远不知道      │
│ DSH 的存在。                                                │
└──────────────────────────┬──────────────────────────────────┘
                           │  Pi 的公开 ABI
┌──────────────────────────▼──────────────────────────────────┐
│ pi2dsh——翻译官，也是唯一同时懂两边词汇的地方。目录投影、    │
│ 事件桥、会话与子代理桥、凭证、vendored 的 Pi 逻辑。          │
└──────────────────────────┬──────────────────────────────────┘
                           │  一个普通 DSH 插件 + llm adapter
┌──────────────────────────▼──────────────────────────────────┐
│ DeepSeek Harness。它只看到一个普通插件，永远不知道 Pi 的存在。│
└─────────────────────────────────────────────────────────────┘

保证它靠谱的几条标准：

• DSH 已经有的东西，绝不再造一遍。 工具进 DSH 的工具注册表，模型进 DSH 的 llm 配置，MCP 交给 dsh-mcp-client，skills 交给 dsh-skill-filesystem， 提问交给 DSH 的 user questions。桥做的是配置翻译，不是另起一套运行时。
• 你面前永远没有 Pi。 你要配的、要读的、要敲的，全是 DSH 形状：DSH 设置、 DSH 命令、DSH 凭证。Pi 的词汇只活在插件自己的视野和桥的内部实现里。
• 零逐包特判。 核心里没有任何 if (packageName === …)。修一个 ABI 缺口， 撞上它的包一起解锁。
• 绝不伪装成功。 映射不了的能力会如实告诉你——同一个插件同一项能力只提示 一次，讲人话。如果某个插件在启动期就需要这样一项能力，它会被整包标成不可用并 给出卸载建议，而不是半死不活地跑着。
• 验证过才算数。 每项能力都有公开 API 契约测试，并且必须在真实 DSH loop 上 端到端跑通——CLI 和 Web 双端——才会发布。

Pi 的开放能力在 DSH 上怎么落

Pi 包能碰到的每一个面，以及它落到 DSH 的什么位置。下面这些表是从桥在运行时真正 查的那份规则生成的，所以不会和代码脱节。

能力域	Pi 面数	状态
工具	12	3 语义一致 · 9 已映射并写明差异
命令、flag、编辑器输入	13	13 已映射并写明差异
消息、上下文、agent 循环	20	7 语义一致 · 13 已映射并写明差异
会话与侧边对话	24	4 语义一致 · 20 已映射并写明差异
模型、provider、凭证	15	12 已映射并写明差异 · 3 不提供
向用户提问与渲染	24	4 语义一致 · 20 已映射并写明差异
项目环境与资源	4	1 语义一致 · 1 已映射 · 2 不提供
合计	112	19 语义一致 · 88 已映射并写明差异 · 5 不提供

另外还有 Pi 三个运行时包（pi-coding-agent、pi-tui、pi-ai）的 202 个 导入符号，由 vendored 或 headless shim 提供——所以插件自己钉的 Pi 版本永远不会 被加载。

从能力索引开始看。机器可读版：pi2dsh matrix --json。

用订阅登录也能用：DSH 本身只提供静态 HTTP header，桥补上了 Pi 生态的交互式 OAuth 层。任何声明了 oauth 块的 Pi provider 包都会得到一条可用的 /login <provider>，跑的是这个包自己的协议代码——Pi 官方的四条流程（OpenAI Codex、Anthropic、GitHub Copilot、Kimi Code）内置。凭证按 Pi 的 auth.json 语义持久化，并通过标准的 dsh-credentials provider 按请求解析，所以你的订阅能 驱动 DSH 原生 llm 路径上的真实调用。细节见模型。

哪些是刻意不提供的，以及为什么：运行时装包和独立模型运行时属于宿主及其安全 门；provider 的 payload/header/response 拦截应该写成 DSH llm adapter；项目信任 是宿主的决定。见模型与 项目环境。

我们自己欠的那一块：插件自绘卡片。Pi 插件可以自带渲染器，目前这类注册我们接 下来但不调用，所以这种笔记会显示成原生的上下文注入行——内容你和模型都拿得到， 只是没有插件自己的样式。DSH 是提供这套机制的，我们的客户端半边还没做。

示例

每一项验证过的能力都配一个完整可跑的 example。example 里的每条命令都在真实 DSH loop 上实际跑过才会进来。

示例	你能得到什么
vision-bridge	纯文本模型回答图片问题——CLI 与 Web 双端，附探针图
side-conversation	/btw <问题> 在 DSH 原生子代理界面里开一条侧边线程，主会话保持干净
custom-gateways	按 DSH 官方方式接任何 OpenAI 兼容网关，每个 Pi 插件都能看到它

其它工具

除了引擎，CLI 还有几个辅助命令：

npx pi2dsh inspect <包名>@<版本>   # 升级前的兼容性报告
npx pi2dsh matrix --json           # 完整能力矩阵
npx pi2dsh mcp-config              # Pi 的 mcpServers 配置 → DSH 官方 MCP 条目

开发与验证

pnpm verify                 # 类型检查 + 契约测试 + 打包检查
pnpm audit:community        # 前 50 静态筛查
pnpm test:community         # 深度运行时 + 官方插件管理器 + e2e
DEEPSEEK_API_KEY=… pnpm test:live    # 真实模型验收（key 只从环境读）

逐项能力的验收证据：docs/acceptance.md。 工作标准：CLAUDE.md 与 docs/STANDARDS.md。

许可

MIT。vendored 的 Pi 源码保留其上游 MIT 许可 （src/compat/vendor/PI-LICENSE）；生成的 bundle 保留拷贝过来的上游许可与声明 文件。