pi2dsh

一句话定位

把 Pi 生态的几百个插件原样跑在 DeepSeek Harness 上，不 fork、不打补丁、不为每个插件写适配器；同一个桥实例统一管理模型目录、登录入口、凭证存储和升级路径。

核心能力

• 让 npm 上原样发布的 Pi 插件以普通 DSH 依赖方式安装并启动工作
• 把每个 profile 直接依赖中识别为 Pi 包的插件自动挂载，单进程共享一个模型目录和凭证
• 把 Pi 提供的工具、命令、会话、子代理、UI surface、模型 provider、OAuth 流程映射到 DSH 的同名公开 seam
• 自动为纯文本模型路由注册贴图伴生路由，让 DeepSeek 这类纯文本模型也能在 Web 上看图
• 配套提供 CLI：兼容性体检（inspect）、能力矩阵（matrix）、Pi MCP 配置翻译成 DSH 官方 MCP 客户端条目（mcp-config）
• 同时扮演 DSH 架构的实战压力测试：每个能力都按"Pi 调用 → 翻译 → 公开 seam → DSH 权威 → 用户可见"五层证据链分级

技术实现

• 语言: TypeScript（ESM，"type": "module"）
• 关键依赖: @deepseek-ai/cordis（运行时挂在 cordis 上的插件）、@deepseek-ai/dsh-* 一组 rc.8 的 peerDependencies（llm/tools/session/credentials/user-questions/commands 等）、jiti（动态加载 Pi 扩展 TS 源码）、pacote（按需解析 npm 注册表）、tinyglobby（读 Pi 包的资源清单）
• 架构模式: 一个 cordis 插件（apply + inject: ['tools', 'systemPrompt', 'commands', 'skills']）。在 agent/created、system-prompt/assemble、tools/pre-execute 三个 DSH 公开事件/waterfall 上挂网关，确保 Pi 运行时在每个根 Agent 的第一个 turn 前就绪；HOST 层资源（provider route、/login、凭证、伴生路由）由引擎独占挂载一次，避免每个 Agent 实例重复注册
• 入口文件: src/index.ts（cordis 引擎表面）；CLI 入口在 src/cli.ts，包内 pi2dsh 二进制指向 ./dist/cli.mjs

适用场景

你正在用 DeepSeek Harness，又想立刻拿到 Pi 生态里那些成熟插件的能力——联网搜索、视觉、代码导航、子代理、OAuth 订阅登录等；不想为这件事 fork 插件或维护适配层。本插件也是 DSH 架构的可执行回归测试，每次升级 DSH 后跑一遍能力矩阵和真实插件验证就能发现新出现的架构缺口。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:weijiafu14/pi2dsh

配置项

引擎自身不持有任何模型配置或凭证。Pi 插件的模型/密钥走 Pi 生态惯用的环境变量或 auth.json；DSH 模型路由走 DSH 的 settings.yaml。

常见问题

Q: 安装时遇到 ERR_PNPM_IGNORED_BUILDS 怎么办？

A: pnpm 默认拦截依赖的构建脚本。在 profile 目录下跑 pnpm approve-builds，或在 profile 的 pnpm-workspace.yaml 的 allowBuilds 下把需要的包设为 true，然后重新 add。这是用户的安全决定，桥不会绕过。

Q: 发版后立刻 add 却装到了旧版本怎么办？

A: pnpm 11 的 minimumReleaseAge 默认跳过刚发布不久的版本。用 dsh plugin add pi2dsh@<版本> 显式钉版本即可。

Q: 引擎和 Pi 插件是分开装的吗？

A: 是。dsh plugin add pi2dsh 装引擎（这一层只在 package.json 声明 dsh.bundle，被 profile 识别为引擎层）；之后每个 Pi 插件用 dsh plugin add <pkg> 当作普通依赖装。重启 dsh，引擎读 profile 的直接依赖，自动挂载所有识别为 Pi 包的依赖。

Q: 默认的纯文本模型也能看图吗？

A: 能。引擎会为每个纯文本路由自动注册 <路由>-vision 伴生路由——在选择器里显示为 "+ Vision Bridge" 分组。贴图后由挂载的视觉 Pi 插件分析，分析结果以注入上下文的形式回到本轮；像素始终不会进入纯文本那条线。注意 GPT-5/o 系列不要用作视觉后端，它们会拒绝部分插件发的非默认 temperature 参数。

Q: ChatGPT / Claude / Copilot / Kimi 的订阅账号能直接用吗？

A: 能。引擎内建 Pi 官方四个 OAuth 流程。装完引擎后 dsh plugin 的 /login <provider> 就能登录，凭证以 Pi 的 auth.json 语义持久化，通过标准 dsh-credentials 解析，调用走 DSH 原生 LLM 路径——一笔订阅走 DSH 模型选择器。

Q: Pi 的 MCP 服务怎么迁过来？

A: 用 CLI：npx pi2dsh mcp-config 读取 Pi 的六层标准 mcpServers 配置（含 disabled 标记），输出可直接放进 cordis.patch.yml 的 DSH 官方 MCP 客户端条目。不需要执行 Pi 的 MCP 适配器代码。

Q: 升级引擎会影响已装的 Pi 插件吗？

A: 不会。引擎与每个插件是独立的升级单元：dsh plugin add pi2dsh@latest 只升引擎，dsh plugin add <pkg>@latest 只升那个插件。升级前想体检某个 Pi 包的兼容性，可以跑 npx pi2dsh inspect <pkg>@<version>，会给出 full/partial/unsupported 三类清单。

上手难度

进阶 — 引擎本身零配置装好即可，但要让某个 Pi 插件工作到底，仍然需要读懂该插件自己的环境变量或 OAuth 流程，以及 DSH 的 settings.yaml、cordis.patch.yml。普通用户按 README 走示例可以直接跑通；想做能力评估或写自定义 patch 的用户需要熟悉 DSH 的工具/会话/模型三大子系统。

已知问题与限制

• 插件自绘卡片当前不被渲染：Pi 插件可以在自己的 view 里画组件样式；引擎接受这些注册但不调用，对应的笔记按 DSH 原生上下文注入行出现——内容能看见，样式丢。客户端半边已就位（侧边面板、header、widget dock、working chrome 四个 slot 都已经画），只剩 card renderer 没接。
• 4 个已确认的 DSH 架构缺口（非 pi2dsh 缺陷，而是 DSH 自身的限制）：DSH-ARCH-001（仓外插件无法注册可安全前向读取的自定义持久事件）；DSH-ARCH-003（已有 adapter 缺 wire 请求/响应 middleware）；DSH-ARCH-004（压缩执行前没有决策 waterfall）；DSH-ARCH-005（项目资源加载前没有 trust policy）。插件遇到这些只能降级或走 sidecar，不会假装成功
• runtime.ts 体积约 3900 行：源码顶部留有 TODO（2026-08-20 用户拍板，待拆），跨包挂载/SharedHostState/模型目录投影//login 与凭证恢复/伴生路由/命令工具事件桥六个层次都在同一个文件里；拆解方案按三层架构走，动手前需对齐
• 运行期包安装和独立模型运行时被刻意屏蔽：Pi 的 DefaultPackageManager 和 ModelRuntime 导入就标记、构造直接抛 PiCapabilityError——这些是 DSH 宿主的安全门，pi2dsh 不会复制第二套
• 纯文本模型的视觉能力要依赖挂载的视觉 Pi 插件：引擎的伴生路由只负责"接收图片并交给挂载的视觉插件"，本身不带视觉能力

English | 中文

Run the Pi ecosystem's plugins on DeepSeek Harness, unmodified.

dsh plugin add pi2dsh          # once
dsh plugin add <any-pi-plugin> # then any Pi plugin, straight from npm

Why this exists

DeepSeek Harness is built on ideas worth betting on — a durable, reconstructable session log, a clean service composition, an agent loop you can actually reason about. What it does not have yet is a large plugin ecosystem: it is early, and the plugins people want on day one — web search, memory, code navigation, subagents, vision — are mostly not written for it yet.

Pi has that ecosystem already, and it is mature: hundreds of published packages, many with real users.

pi2dsh is one compatibility layer that implements Pi's public extension ABI on top of DSH's native services, so a Pi package runs on DSH as published — no fork, no patch, no per-package adapter. You install a Pi plugin the same way you install anything else in DSH, and it works.

At the same time, pi2dsh is an ongoing, full-surface, real-world test of DSH's architecture. Instead of patching individual plugins, it asks whether the models, tools, sessions, interaction, resources and client capabilities that Pi plugins rely on can preserve their logic and lifecycle using only DSH's public services and extension seams. If they can, that is strong evidence that DSH's architectural goals for building agents and an agent-plugin ecosystem have been achieved, at least along this dimension. Wherever the bridge must bypass, degrade or cannot express a capability, it pinpoints an architectural gap that remains.

Install

One engine, then whatever plugins you want:

dsh plugin --profile web add pi2dsh
dsh plugin --profile web add @kassing/pi-vision

Then restart dsh — plugins mount at startup.

Use web or headless as the profile name. DSH ships a template for exactly those two, and each includes a surface (the web app / the one-shot driver). dsh plugin --profile <any-other-name> creates a profile with no surface at all, and that profile starts up and then hangs with no diagnostic — nothing to do with pi2dsh, but easy to hit on your first install. If you want a differently named profile, add the surface bundle to its dsh.profile.bundles yourself.

That is the whole model. There is no conversion step, no generated bundle, no build. The engine discovers the Pi packages in your profile (every one is something you explicitly added) and mounts them through a single bridge instance: one model directory, one login, one credential store, one upgrade unit.

Day-to-day:

Two installer messages worth knowing:

• ERR_PNPM_IGNORED_BUILDS — pnpm blocks dependency build scripts by default. Run pnpm approve-builds inside $DSH_HOME/profiles/web, or set the listed packages to true under allowBuilds in that profile's pnpm-workspace.yaml. Then re-run the add. (This is your call to make, so the bridge does not work around it.)
• An add silently installs an older version right after a release — pnpm's minimumReleaseAge skips versions published very recently. Pin it: dsh plugin add pi2dsh@<version>.

Requires Node.js 22.19+ and DeepSeek Harness.

Walkthrough: give a text-only model eyes

The clearest example of what the bridge buys you. DeepSeek models are text-only, so DSH cannot send them an image. The Pi ecosystem has a plugin for exactly this — it hands the image to a vision model you choose and injects the analysis back into the conversation.

1. Install the plugin

dsh plugin --profile web add @kassing/pi-vision

2. Point it at a multimodal model

This is the step to get right — the plugin needs its own vision model, and it is a different model from the one you chat with. Any OpenAI-compatible vision endpoint works (OpenRouter, DashScope/Qwen-VL, a self-hosted vLLM, …).

The plugin reads its configuration from environment variables — the standard way Pi plugins are configured, and a plain DSH-side action for you:

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

That is enough to work. If you would also like that vision model to appear in DSH's own model picker (so you can chat with it directly), add it as a normal DSH route as well — the llm-pi-ai: section of $DSH_HOME/settings.yaml:

llm-pi-ai:
  providers:
    openrouter:
      baseUrl: https://openrouter.ai/api/v1
      apiKeyEnv: OPENROUTER_API_KEY
      models:
        - id: qwen/qwen2.5-vl-72b-instruct

Both are ordinary DSH configuration. The bridge owns no model configuration of its own, and there is no Pi-format file for you to write.

Avoid GPT-5/o-family models as the vision backend: that generation rejects the non-default temperature some vision plugins send.

3. Ask about an image

In the CLI, mention a path:

dsh --profile web "What color fills $PWD/photo.png ? One word."

In the web app, just paste the image — even though your main model is text-only. DSH normally refuses image attachments for a text-only model, so the engine registers an image-admission companion route for every text-only route in your directory, named <route>-vision. Pick it in the model picker (it shows up as a "+ Vision Bridge" group), paste, and ask.

What you will see: your image becomes guide text, a pi2dsh:@kassing/pi-vision context-injection row carries the analysis, and your text-only model answers about the picture. Pixels never reach the text-only wire.

Companions are automatic. To turn them off, or narrow them to specific routes, set visionCompanions in the engine's plugin config ($DSH_HOME/profiles/web/cordis.patch.yml):

- id: pi2dsh
  config:
    visionCompanions: false

Full runnable version, with probe images: examples/vision-bridge.

What actually works today

Two levels, and they are not the same claim.

Level 1 — verified end to end, with a runnable example

Someone sat down, used the plugin's real feature on a real DSH loop, and saw it work. This is the list to trust.

Examples for the last three are still to be written; per this project's own rule they get re-verified from scratch before an example lands, so the table says plainly which have one today.

Level 2 — mounts and its surface answers a probe

The Pi catalog's top 50 packages by monthly downloads, each mounted in a real DSH runtime and then called through a black-box probe. Status as of 2026-08-14; per-package machine-readable evidence in community/.

47 of 50 exercised successfully · 1 with no probeable surface · 2 pending a re-run.

What this level does not tell you: that the plugin's actual feature works the way you would use it. A probe calls a registered surface with synthetic arguments; a user runs a workflow. pi-btw is the cautionary example — it graded "working" here for weeks while /btw <question> failed on a real session, because the feature needed two ABI gaps closed (Pi's settable AgentState.messages, and an input descriptor on bridged commands) that no probe exercised. Both are fixed in 0.11.0, and both were general fixes that unlock every plugin doing the same thing.

So read the table below as "the bridge covers what this plugin touches", not as "this plugin is known-good". When you try one, a report either way is useful.

¹ Mounts; the exercise run is pending a re-run (a harness-side failure, not a package or bridge gap). ² Ran its own business logic end to end and rejected the synthetic probe arguments — working, correctly validating. ³ A pure event-hook package: all subscriptions attach, but every handler is gated on a live DeepSeek billing session, so a black-box probe has nothing safely callable to assert.

Packages outside the top 50 are not a separate case — the bridge has no per-package code. If one hits an ABI gap, fixing that gap unlocks every package that shares it.

Level 1 grows by working through Level 2 one plugin at a time. The full verification ladder, with what each rung does and does not prove: support matrix.

How it works

Three layers, and nothing crosses them:

┌─ Pi plugin ─────────────────────────────────────────────────┐
│ unmodified npm package. It sees a complete Pi host: the     │
│ three Pi runtime imports, registerX, ctx.*, 33 lifecycle    │
│ events. It never learns DSH exists.                         │
└──────────────────────────┬──────────────────────────────────┘
                           │  Pi's public ABI
┌──────────────────────────▼──────────────────────────────────┐
│ pi2dsh — the translator, and the only place that knows both │
│ vocabularies. Registry projection, event bridge, session &  │
│ subagent bridge, credentials, vendored Pi logic.            │
└──────────────────────────┬──────────────────────────────────┘
                           │  ordinary DSH plugin + llm adapter
┌──────────────────────────▼──────────────────────────────────┐
│ DeepSeek Harness. Sees a normal plugin. Never learns Pi     │
│ exists.                                                     │
└─────────────────────────────────────────────────────────────┘

DSH is two halves, and so is the bridge. The column above is the server; the browser shell has its own plugin surface, and a Pi capability that is a SHAPE rather than a behaviour lands there:

┌──────────── DSH server (cordis) ────────────┐  ┌──────── DSH browser shell ────────┐
│ services · waterfalls · durable events      │  │ dsh.client + exports "./client"   │
│                                             │  │ slot registry (ui-slots)          │
│ pi2dsh engine                               │  │   shell.overlay  ← panel, pills   │
│   tools · commands · models · sessions      │  │   session.header.utilities ← hdr  │
│   subagent bridge ─────────────┐            │  │   input.dock ← widgets            │
│   browser-state registry       │            │  │   composer.dock ← working/footer  │
│     GET /pi2dsh/browser-state ─┼── own route┼──┼─▶ all four seats, one poller      │
└────────────────────────────────┴────────────┘  └───────────────────────────────────┘

The browser half's data rides this package's own route, not DSH's typed Remote system: that one is a first-party, code-generated contract, and an out-of-tree plugin talking to its own UI should carry its own channel. One payload per session serves every seat — the side-conversation panel, plus the Pi presentation surfaces (status, widget, header, footer, title and the working/thinking chrome), which are drawn in the host's own slot seats rather than re-implemented. Two host rules make the browser half load at all — the package must export ./package.json (the host resolves the manifest by subpath), and the ./client bundle is a closure-factory artifact, not plain ESM.

The rules that keep it honest:

• Never a second implementation of something DSH already has. Tools go to DSH's tool registry, models to DSH's llm configuration, MCP to dsh-mcp-client, skills to dsh-skill-filesystem, questions to DSH's user questions. The bridge translates configuration; it does not build a parallel runtime.
• You never see Pi. Everything you configure, read, or type is DSH-shaped: DSH settings, DSH commands, DSH credentials. Pi vocabulary exists only inside the plugin's view and the bridge's own internals.
• No per-package special cases. The core contains no if (packageName === …). One ABI gap fixed unlocks every package that hits it.
• Never fake success. A capability with no safe mapping is reported — once, per plugin, in plain language — instead of silently returning something invented. If a plugin needs one during startup, it is marked unusable with a removal hint rather than half-working.
• Verified, not asserted. Every capability has a public-API contract test, and ships only after running end to end on a real DSH loop — CLI and web.

What this is teaching us about DSH

pi2dsh is also an executable stress test of DSH's plugin architecture. Pi gives that test a useful workload: a large, already-used public plugin ABI rather than a set of examples invented to fit the host.

The result so far is specific, not a thumbs-up/thumbs-down verdict:

• DSH's public seams successfully carry whole capabilities: tools, commands, model adapters, user questions, native child sessions and browser slots.
• The pressure points appear when an out-of-repo plugin needs to extend an existing capability from the inside: add a durable session-event type, intercept the real provider request/response, control compaction before it happens, or participate in trust before project resources load.
• A working pi2dsh sidecar or alternate adapter is useful product behaviour, but it is not counted as proof that the native DSH seam is complete.

For example, a pi-btw answer is a real DSH child session — visible, resumable and continuable by the host. Pi custom entries are different: they still need a pi2dsh sidecar because an out-of-repo plugin cannot safely add a new event type to DSH's durable log. Likewise, a transport-owning Pi provider can register a native DSH route. Since DSH rc.8, a catalog-only provider also has a faithful official path: pi2dsh translates its endpoint, modalities, reasoning levels and the protocol-specific compat fields DSH offers into an llm-pi-ai profile, and DSH owns the request.

The project follows one Pi → DSH architecture mapping standard. It is a reasoning method, not another runtime layer: concrete Pi interface → Pi capability contract → DSH carrying mechanism → public seam → real plugin run → five-grade result. The evolving branches live in the handwritten architecture model, real runs in per-plugin validation records, and the three result classes in architecture conclusions. Architecture classifications are deliberately not generated from a JSON ledger. The previously observed 111 Pi rule rows and 45 DSH subsystems are versioned snapshots, not fixed totals or proof of completeness. Four DSH gap IDs remain active; a fifth historical finding (DSH-ARCH-002) was fixed upstream in rc.8. These are confirmed findings, not a claim of complete coverage. Current upstream reports include #2708 — durable events for out-of-repo plugins and #3076 — provider compat fields dropped by llm-pi-ai, now resolved by the rc.8 profile schema.

Pi capabilities on DSH

Every surface a Pi package can touch, and what it maps onto. These tables are generated from the rules the bridge consults at runtime, so they cannot drift from the code.

For pinned Pi 0.84.1, the generated catalog has 111 upstream-shaped rule rows. The bridge also keeps one documented compatibility extension, unregisterTool; it appears on the tools detail page but is deliberately outside that total. Nested objects such as the session manager can expose several methods behind one row; the architecture audit states this boundary explicitly.

Plus 203 imported symbols from Pi's three runtime packages (pi-coding-agent, pi-tui, pi-ai), served from vendored or headless shims — so a plugin's own Pi version pins never load. They are listed in Imported Pi runtime symbols.

Each area page states the Pi capability contract, the theoretical DSH mechanism and public seam, and the current implementation for every surface. Adding a surface without a capability assignment or theoretical mapping fails the docs check.

Start at the capability index. Machine-readable: pi2dsh matrix --json.

Signing in with a subscription works too: DSH ships static HTTP headers only, and the bridge adds the Pi ecosystem's interactive OAuth layer. Any Pi provider package that declares an oauth block gets a working /login <provider>, driven by the package's own protocol code — Pi's four official flows (OpenAI Codex, Anthropic, GitHub Copilot, Kimi Code) ship built in and are available immediately after installing the engine, even before the first community Pi package. Credentials persist with Pi's auth.json semantics and resolve per request through a standard dsh-credentials provider, so your subscription drives real calls on DSH's native llm path. Details in models.

What is deliberately not available, and why: runtime package installation and standalone model runtimes stay with the host and its security gates; provider payload/header/response interception belongs in a DSH llm adapter; project trust is a host decision. See models and environment.

The one gap we own: plugin-drawn cards. Pi plugins can ship their own renderers; today those registrations are accepted but not invoked, so such a note appears as a native context-injection row — the content reaches you and the model, without the plugin's styling. The client half exists and takes four seats (side-conversation panel, header, widget dock, working chrome) — the card renderers are what it does not draw yet.

Examples

Every verified capability ships as a complete, runnable example. Every command in one has actually been executed against a real DSH loop before landing.

Other tools

Beyond the engine, the CLI has a few helpers:

npx pi2dsh inspect <pkg>@<version>   # compatibility report before an upgrade
npx pi2dsh matrix --json             # the full capability matrix
npx pi2dsh mcp-config                # Pi mcpServers config → official DSH MCP entries

Development

pnpm verify                 # typecheck + contract tests + packaging
pnpm audit:community        # static screening over the top-50 corpus
pnpm test:community         # deep runtime + official plugin-manager + e2e
DEEPSEEK_API_KEY=… pnpm test:live    # real-model acceptance (key from env only)
CODEX_AUTH_FILE=… pnpm test:codex-image # real OAuth generation + reference edit + Web pixels

Acceptance evidence per capability: docs/acceptance.md. Working standards: CLAUDE.md and docs/STANDARDS.md.

License

MIT. Vendored Pi sources retain their upstream MIT license (src/compat/vendor/PI-LICENSE); generated bundles retain copied upstream license and notice files.