Preface¶

DeepSeek Harness (DSH) implements the concept of “everything is a plugin” thoroughly: session logs are reconstructable, service composition is clear, and Agent loops are sufficiently transparent. However, for many developers new to DSH, a practical issue is that the ecosystem is still in its early stages. Capabilities like internet search, cross-session memory, code navigation, sub-agents, and image analysis that users expect out-of-the-box might not yet be fully available in DSH’s native plugin library.

On the other hand, Pi’s extension ecosystem is already quite mature: hundreds of packages have been published on npm, many with real users. If you appreciate DSH’s architecture but don’t want to rewrite these capabilities from scratch, pi2dsh offers a pragmatic path: using a compatibility bridge layer, it maps Pi’s public extension ABI onto DSH’s native services, allowing Pi packages to be mounted as DSH plugins as-is—no forking, patching, or writing individual adapters for each package.

This article is compiled from public resources in the SkillHub Plugin Directory and the GitHub repository. SkillHub is a community-maintained DSH plugin index with no official affiliation to DeepSeek / High-Flyer; please review the source code and MIT license before installation.

What is This¶

pi2dsh is maintained by community developer weijiafu14 and categorized as a “workflow” tool on SkillHub. The GitHub repository currently has approximately 159 stars and 32 forks (as of 2026-08-25).

In one sentence, it serves as a compatibility layer engine between Pi and DSH. Pi plugins believe they are running on a full Pi Host; DSH loads them as ordinary plugins—only the pi2dsh “translator” layer in between is aware of both vocabulary sets.

Architecturally, it is divided into three layers with clear responsibility boundaries:

┌─ Pi Plugin (unchanged npm package)────────────────────────────┐
│  Sees full Pi Host: runtime imports, registerX, lifecycle events│
└──────────────────────────┬─────────────────────────────────────┘
                           │  Pi Public ABI
┌──────────────────────────▼─────────────────────────────────────┐
│  pi2dsh — Registry projection, event bridge, session/sub-agent │
│  bridge, credential mapping                                    │
└──────────────────────────┬─────────────────────────────────────┘
                           │  Ordinary DSH Plugin + llm adapter
┌──────────────────────────▼─────────────────────────────────────┐
│  DeepSeek Harness — Sees just another native plugin            │
└────────────────────────────────────────────────────────────────┘

Core Features and Highlights¶

1. Zero-Conversion Installation of Pi Plugins¶

After installing the pi2dsh engine, subsequent Pi plugins are installed the same way as any DSH plugin: explicitly dsh plugin add <package-name> and restart dsh to mount. There are no conversion steps, no generated artifacts, and no need for additional builds.

2. Coverage of Pi Public ABI’s Main Capability Surfaces¶

According to the repository documentation, for the public extension surface of Pi 0.84.1, the bridge layer maintains 111 upstream rule mappings, covering tools, commands, messages and sessions, models and credentials, user interactions, project environments, etc. Tools use the DSH tool registry, models use DSH’s llm configuration, and user Q&A uses DSH’s official Q&A channel—the bridge does not write a parallel implementation for existing capabilities.

3. Already End-to-End Verified Plugins¶

The repository maintains two levels of verification lists. Level 1 is the list of plugins that “real humans have run through in a real DSH loop,” which is more trustworthy. For example:

Additionally, black-box probing was conducted on the top 50 packages by monthly downloads in the Pi directory: as of the documented record, 47 out of 50 probes passed. It is important to emphasize that a probe pass only indicates “the bridge covers the ABI surface touched by that package,” not “your specific workflow will definitely be issue-free”—the repository has also used pi-btw as an example to explain such differences.

4. Includes CLI Tools¶

Beyond the engine, several auxiliary commands are provided:

npx pi2dsh inspect <pkg>@<version>   # Compatibility check before upgrading
npx pi2dsh matrix --json             # Export the full capability matrix
npx pi2dsh mcp-config                # Translate Pi's mcpServers configuration into DSH official MCP entries

Installation and Enabling¶

Environment Requirements: Node.js 22.19+, with DeepSeek Harness installed.

Profiles need to include a UI bundle. DSH’s built-in templates include web and headless; if using a custom profile like dsh-tui, ensure the corresponding UI plugin (e.g., @deepseek-harness-tui/dsh-tui) is listed in dsh.profile.bundles.

Basic Installation (web profile)¶

First install the engine, then install the Pi plugins you want:

dsh plugin --profile web add pi2dsh
dsh plugin --profile web add pi-mcp-adapter

Then restart dsh—plugins are mounted at startup.

If you prefer a global profile, the README also provides a simplified approach:

dsh plugin add pi2dsh          # Install the engine once
dsh plugin add <any-pi-plugin> # Then add as needed

Pinning Versions (Optional)¶

If the community directory supports installation from GitHub, a common approach is dsh plugin add github:owner/repo; the official pi2dsh README specifies using the npm package name pi2dsh. After a fresh release, if add installs an older version, you can explicitly pin the version:

dsh plugin add pi2dsh@<version>

Two Common Installation Tips¶

1. ERR_PNPM_IGNORED_BUILDS: pnpm defaults to intercepting dependency build scripts. Navigate to $DSH_HOME/profiles/<profile> and run pnpm approve-builds, or allow the prompted packages in pnpm-workspace.yaml’s allowBuilds, then re-run add.
2. Upgrade Strategy: To upgrade a single Pi plugin, use dsh plugin add <package-name>@latest without changing the engine; to upgrade the engine, use dsh plugin add pi2dsh@latest without changing the installed Pi plugins. When uninstalling, first remove the Pi package, then finally remove pi2dsh.

Typical Use Case: Advanced MCP in the Terminal¶

This walkthrough best illustrates the value of pi2dsh. dsh-TUI comes with a native /mcp (DSH’s official MCP client), while Pi’s pi-mcp-adapter provides a fullscreen server manager, lazy tool loading, proxy tools, JavaScript orchestration for multiple MCP calls, OAuth login, and other more complete capabilities. After installing the bridge, this package can run without modification.

1. Installation¶

dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui   # Skip if profile already exists
dsh plugin --profile dsh-tui add pi2dsh
dsh plugin --profile dsh-tui add pi-mcp-adapter

Restart dsh.

2. Configure MCP Servers¶

In dsh-TUI, run:

/pi-mcp setup

The setup process can incorporate MCP server definitions from existing host configurations into the adapter’s own mcp.json, requiring no bridge-specific configuration.

3. Usage¶

/pi-mcp

Opens the fullscreen interactive server manager. Models obtain mcp and mcpScript tools via the DSH tool registry; each Agent (including those created with /new) has its own connection instance.

Two commands coexist and do not replace each other:

/mcp       # Native DSH MCP client status
/pi-mcp    # Pi ecosystem MCP manager

Applicable Scenarios and Considerations¶

Who Is It For

• Developers who have used several extensions in the Pi ecosystem and, when migrating to DSH, don’t want to rewrite or maintain forks.
• Those needing to quickly fill gaps in DSH’s early ecosystem: internet search, memory, sub-agents, MCP orchestration, visual analysis, etc.
• Developers who want to leverage Pi’s large plugin catalog for real-world load testing of DSH’s plugin architecture.

Important Notes

1. Permissions and Security: Plugins run with the permissions of the current dsh process. Before installing any Pi package, read its source code, dependencies, and license; pi2dsh itself is MIT-licensed.
2. Capability Boundaries: The bridge layer explicitly does not fabricate success—capabilities that cannot be securely mapped are reported once in plain language, rather than silently returning false data. Plugin-drawn card-type UIs are currently registered as acceptable but not yet fully rendered.
3. Verification Granularity: Top 50 black-box probing and Level 1 end-to-end verification are not the same standard; before production use, it’s recommended to run a real workflow test on packages you care about, using npx pi2dsh inspect for pre-upgrade checks if necessary.
4. Ecosystem Positioning: Both SkillHub and pi2dsh are community contributions and do not represent official DeepSeek endorsement; DSH upstream is still iterating rapidly, and certain seams (e.g., outbound plugin extension of persistent event types) may still await official interface improvements.

Summary¶

pi2dsh solves not a single-point issue like “write another MCP client,” but the entire Pi → DSH plugin migration pathway: install the engine once, and then Pi extensions on npm can be gradually integrated using their original package names. For developers who value DSH’s architecture but are unwilling to abandon Pi’s ecosystem investments, this is currently the most fully documented and publicly verified compatibility route.

• Directory page: https://www.skillhub.cn/plugins/weijiafu14/pi2dsh
• GitHub: https://github.com/weijiafu14/pi2dsh
• DSH Official Repository: https://github.com/deepseek-ai/deepseek-harness