Preface¶

DeepSeek Harness (hereinafter referred to as DSH) treats models, tools, sessions, skills, and UI as replaceable plugins, with the official repository positioning itself as “everything is a plugin”. It is currently in developer preview, and its core API is subject to change. For newcomers, the more immediate gap often lies not in the kernel, but in ready-made capabilities: web search, cross-session memory, code navigation, sub-agents, and image understanding, which have not yet been fully rolled out in the native ecosystem.

Pi (https://pi.dev/) already has a mature extension ecosystem, with hundreds of publicly released packages. The problem is that the plugin ABIs of the two platforms are incompatible: Pi extensions are designed for its own Host surface, while DSH plugins are mounted on Cordis services. Wrapping each Pi package into a DSH adapter is both labor-intensive and difficult to sync with upstream.

pi2dsh takes a different approach: it implements a layer of Pi’s public extension ABI, allowing unmodified Pi packages to be mounted as regular DSH plugins. This article is compiled after cross-verifying information from the community plugin directory, GitHub repository READMEs (including Chinese versions), the 0.12.3 version notes on npm, and the official DeepSeek Harness repository. The community directory site has no official affiliation with DeepSeek / FunFound, and should not be treated as an official app store.

What is pi2dsh¶

pi2dsh is a development and runtime plugin maintained by weijiafu14, licensed under MIT, and primarily written in TypeScript. The current version on npm and package.json is 0.12.3 (released on 2026-08-16). As of the check on 2026-08-18, the GitHub repository weijiafu14/pi2dsh had 21 stars; the community directory page at the time showed 8 stars, so star counts should be referenced from the repository page.

Its positioning can be summed up in one sentence: a universal Pi Host ABI layer that allows unmodified Pi extensions to run as native DSH plugins. The repository itself makes it clear that this is a bridge, not an end goal. When better native plugins appear in the DSH ecosystem, they should be used instead.

The runtime requirements are explicitly stated in the README: Node.js 22.19+ and a working DeepSeek Harness instance.

Core Capabilities¶

pi2dsh does not write a separate patch for each Pi package. The model outlined in the README is: install the engine once, then use dsh plugin add to directly add the original Pi packages from npm. There is no conversion step, and no new bundle is generated.

Three Layers, No Cross-Boundary Responsibilities¶

The repository uses three layers to clarify responsibilities:
1. Pi plugins remain unmodified npm packages. They see a complete Pi host environment: three runtime imports, registerX, ctx.*, lifecycle events, and are unaware of DSH’s existence.
2. pi2dsh is the only translation layer that understands the vocabulary of both platforms: directory projection, event bridging, session and sub-agent bridging, credentials, and vendored Pi logic.
3. DeepSeek Harness only sees a regular plugin plus an LLM adapter, and is unaware of Pi’s existence.

There is another browser shell half: presentation surfaces such as side chat overlays, headers, widget docks, and working areas use their own routing from this package, and do not occupy DSH’s first-class citizen typed Remote contract.

Several implementation principles are clearly stated in the README: do not rebuild capabilities that DSH already has (tools go into the DSH tool registry, MCP is handed over to dsh-mcp-client, skills are handed over to dsh-skill-filesystem); user-side configuration retains the DSH format; there is no per-package special handling like if (packageName === …) in the core; unmapped capabilities will be explicitly stated instead of pretending to succeed.

Capability Coverage (Based on the Repository Table)¶

The capability matrix given in the README is generated from runtime rules, totaling 112 Pi-facing surfaces: 24 are semantically consistent, 83 have been mapped with documented differences, and 5 have been deliberately not provided. In addition, it uses vendored/headless shims to provide 202 import symbols for Pi’s three runtime packages (pi-coding-agent, pi-tui, pi-ai), avoiding version pinning conflicts when plugins load their required Pi versions.

The deliberately excluded parts include: runtime package installation, independent model runtime, provider payload/header/response interception, and project trust decisions — these still belong to the host. The repository itself admits a remaining gap: plugin self-drawn cards will currently register but not invoke, with content converted into native context injection lines without the plugin’s own styling.

Subscription login also works. DSH itself only provides static HTTP headers, and the bridge supplements Pi’s interactive OAuth flow. Pi providers that declare an oauth block will get the /login <name> command; the README notes that four official flows are built-in: OpenAI Codex, Anthropic, GitHub Copilot, and Kimi Code. Credentials are persisted according to Pi’s auth.json semantics, and then drive DSH’s native LLM paths via the standard dsh-credentials provider.

Which Features Are “Truly Usable” Today¶

The repository divides validation into two levels, which prove different things:

Level 1 is end-to-end testing with runnable examples included where possible. As of the current README content, the list is as follows:

Level 2 mounts the top 50 Pi packages by monthly downloads into a real DSH runtime, then probes the registration surface with black-box tests. As of 2026-08-14: 47 out of 50 probe calls succeeded, 1 had no detectable surface, and 2 need to be retested. The repository reminds users that this level only proves that “the bridge covers the surfaces used by this plugin”, not that the real workflow works. pi-btw is a counterexample — the probe showed working status long-term, but /btw failed in real sessions until version 0.11.0 fixed two ABI gaps.

Therefore, any packages outside the Level 1 list should be treated as experimental rather than confirmed usable.

There are three auxiliary commands outside the engine:

npx pi2dsh inspect <package-name>@<version>   # Compatibility report before upgrading
npx pi2dsh matrix --json           # Full capability matrix
npx pi2dsh mcp-config              # Convert Pi's mcpServers config → DSH official MCP entries

Installation and Activation¶

The installation command given on the community directory page can be run in the DeepSeek Harness terminal:

dsh plugin add github:weijiafu14/pi2dsh

For reproducible installations, the directory page recommends pinning the commit hash:

dsh plugin add github:weijiafu14/pi2dsh#<commit>

The standard installation method in the repository README uses the npm package name and specifies a profile with an interface layer. DSH only builds templates for web and headless by default; when creating a new profile with another name, there may be no interface layer, and it will hang without errors after startup — this is unrelated to pi2dsh, but easy to encounter during first-time installation.

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

After installation, restart dsh — the plugin mounts during startup.

Daily addition, removal, and upgrade commands (from the README):

dsh plugin add <package-name>                 # Then restart
dsh plugin remove <package-name>              # Uninstall the plugin first, then the engine
dsh plugin add <package-name>@latest          # Only upgrade a specific Pi plugin
dsh plugin add pi2dsh@latest          # Only upgrade the engine
npx pi2dsh inspect <package-name>@<version>      # Run a compatibility check before upgrading

Two installation-time warnings are worth knowing in advance:
1. If ERR_PNPM_IGNORED_BUILDS appears, it means pnpm blocked dependency build scripts by default. You need to run pnpm approve-builds in $DSH_HOME/profiles/web, or add the packages mentioned in the prompt to the allowBuilds field of the profile’s pnpm-workspace.yaml, then re-run the add command. The bridge will not bypass this step for you.
2. After a new release, add may sometimes install an older version, because pnpm’s minimumReleaseAge skips packages that were just published. Explicitly pin the version instead, for example dsh plugin add pi2dsh@0.12.3.

The directory page also notes the security boundary: plugins run with the permissions of the current dsh process, and may execute code during installation. You should check the source code repository and license before installing.

Typical Usage: Let Plaintext Models Understand Images¶

The repository uses @kassing/pi-vision as the best example to illustrate the value of this bridge. DeepSeek series models are plaintext-only, and DSH cannot send images directly to them. This plugin in the Pi ecosystem delegates images to a vision model of your choice, then injects the analysis results back into the conversation.

First ensure the engine is installed, then add the plugin:

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

Then configure a multimodal endpoint separately. This model is not the same as the main model you use for chatting. The README uses OpenRouter’s Qwen-VL as an example; OpenAI-compatible endpoints such as DashScope / self-hosted vLLM are also supported.

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

If you want this vision model to appear in DSH’s own model selector, add a regular DSH configuration entry in 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

The bridge itself does not hold model configurations, and does not require manually writing Pi-format files. Do not use GPT-5 / o-series models as the vision backend: these generations will reject non-default temperature parameters, and some vision plugins include this parameter.

You can directly pass an image path via the CLI:

dsh --profile web "$PWD/photo.png What color is this image? Answer with one word only."

You can also directly paste images in the web interface. DSH will normally refuse to upload images to plaintext models, so the engine will automatically register a companion route for each plaintext routing in the model directory, named <route>-vision, displayed in the selector as the “+ Vision Bridge” group. Select it, paste the image, and ask your question. No pixel data will go through the plaintext call path; you will see a context injection line from pi2dsh:@kassing/pi-vision with the analysis results.

To disable the companion routes, add the following to $DSH_HOME/profiles/web/cordis.patch.yml:

- id: pi2dsh
  config:
    visionCompanions: false

The full runnable version (including probe images) is in the repository’s examples/vision-bridge/. Another verified path is pi-btw: use /btw <question> in a conversation to open a side thread, keeping the main session clean, with an example in examples/side-conversation/.

Applicable Scenarios and Notes¶

This tool is suitable for the following groups: users already using DSH but temporarily lacking native plugins; developers with existing Pi packages who do not want to fork them; teams that need to quickly integrate capabilities like image understanding, side conversations, and cross-session memory, and plan to migrate to native DSH plugins once the ecosystem catches up.

Several important notes need to be clarified separately:
1. Do not mix up validation levels. The Level 1 list is the only part the repository says “trust this table”; the Level 2 top 50 probe results only prove that the mounting surfaces are covered. The repository explicitly states: packages outside the top 50 are not a separate category, and the bridge has no per-package code, so any ABI gaps encountered should be fixed at the bridge level.
2. Use web or headless for profile names. Custom profile names may result in an empty profile without an interface layer.
3. Plugins run with the permissions of the current dsh process. Check the source code and license before installing; for supply-chain-sensitive environments, pin the commit or version number. Pi plugins can also execute code and affect agent behavior.
4. Known gaps. Plugin self-drawn cards currently do not render with plugin-specific styling; unmapped capabilities will prompt an error or mark the entire package as unavailable.
5. The community directory is not an official store. The directory page referenced in this article is an independent site. The official DSH repository is at https://github.com/deepseek-ai/deepseek-harness, and the official page also notes that it is still in developer preview with breaking changes possible.

Summary¶

pi2dsh connects Pi’s public extension ABI to DSH’s native services, allowing unmodified Pi packages to be installed and run as DSH plugins. It solves the ecological timing gap, rather than replacing DSH’s own plugin system. The current version is 0.12.3, licensed under MIT, and maintained by weijiafu14.

Community Directory Page: https://deepseek-harness-plugin.com/zh-CN/plugins/pi2dsh/

GitHub Repository: https://github.com/weijiafu14/pi2dsh