What pi2dsh is, and what you can learn here

[weijiafu14]

One bridge, two ecosystems

DSH is a young ecosystem with a strong design; Pi is an older one with mature
plugins. pi2dsh is a Pi Host ABI compatibility layer that lets Pi packages run
on DSH unmodified:

dsh plugin add pi2dsh          # the engine, installed once
dsh plugin add <pi-package>    # the original npm package, straight from the registry

No conversion step, no generated bundle, no second install path — that is a
standard in this repo, not a convenience. For a Pi author it means your package
reaches DSH users without a port and without your maintenance. For a DSH user it
means mature capabilities are available today, and the bridge gets out of the way
the moment a more native DSH plugin exists.

To users, everything looks like DSH. To plugins, everything looks like Pi. The
middle layer is the only translator.

A field study of agent-loop architecture

Pi and DSH are both attempts to re-abstract what an AI product is underneath the
chat window. Building a bridge between them forces us to answer, in running code
rather than in prose, the questions that decide how such a framework behaves:

• Where does an extension's lifetime begin and end — per process, per session,
  per agent? (Ours is per root agent, and the reasoning, including the route we
  tried and killed, is written down.)
• Who owns the system prompt, and how late can it still be changed?
• What shape do tool arguments have, and who translates between two hosts'
  vocabularies for the same built-in tool?
• How are sessions persisted, branched, compacted — and what does a "rollback"
  actually mean on disk?
• What vocabulary does an approval speak, and what happens to a permission model
  that has one fewer verb than the plugin expects?
• How does a model catalog become a route, and where do per-route capabilities
  (context window, modalities) actually come from?
• Where is the client/server line in a web surface, and what belongs in the
  browser half of a plugin?

Every answer in this repository comes from running both systems, not from reading
type definitions. Several of them started as a confident wrong answer that a real
run disproved.

Why the notes here are worth reading

The repository's working standards are strict on purpose:

• End to end on stock npm releases, a fresh home, and a real model. Mounting is
  not completion; a green unit test is not completion.
• No mocks in end-to-end tests. A fake endpoint proves the fake endpoint can
  talk.
• Assertions must be falsifiable and are read from the session log — never from
  page text or from the model's wording. Several "passing" tests here turned out
  to be passing while the feature was dead; those accidents are documented.
• Anything unverified is labeled unverified. "Loads and a probe reached it" and
  "a person used it end to end" are two different claims, and we never merge them.

Every rule was written after a specific failure, and the failures are kept:
docs/STANDARDS.md.

Where to start reading

If you want	Read
The Pi capability → DSH seam map, by architecture branch	docs/architecture-mapping-matrix.md
How a mapping is judged (native / translated / bypass / degraded)	docs/architecture-mapping-standard.md
What each Pi surface actually does on DSH today	docs/capabilities/
Real plugins, feature by feature, with evidence	docs/plugin-validation-matrix.md
Runnable examples, each with its own regression script	examples/

How to take part

• Q&A — how something works under the hood, or why a plugin behaves the way
  it does on DSH.
• Ideas — which Pi package should be bridged and verified next, and what a
  DSH-side seam would need for it.
• Show and tell — your surface, terminal, or plugin combination.

Bugs and reproducible failures still belong in Issues.

---

中文

一套桥，打通两边生态。 DSH 理念好但生态尚早，Pi 有大量成熟插件。pi2dsh 是
Pi Host ABI 兼容层：装一次引擎，之后直接 dsh plugin add 安装 Pi 的 npm 原包，
零转换、零生成产物。对 Pi 作者，插件的适用范围直接扩到 DSH，不需要你移植和维护；
对 DSH 用户，成熟能力今天就能用。对用户，一切是 DSH；对插件，一切是 Pi；中间层是
唯一的翻译官。

同时也是一份对两种 agent loop 框架的深入探索。 Pi 和 DSH 都在重新定义 AI
产品底层该怎么抽象。做这座桥必须用可运行的代码回答一批根本问题：扩展的生命周期
挂在哪一层、系统提示词由谁装配又能改到多晚、同一个内建工具在两边的参数词汇谁来翻译、
会话如何持久化与分支、审批语汇少一个动词会怎样、模型目录如何变成路由、Web 形态下
客户端与服务端的界线在哪。这里的每个结论都来自在两套真实系统上跑出来的结果，
不是读类型定义得来的——其中好几条，最初的自信答案被真机跑翻了。

仓库的工作标准是这些笔记可信的原因：真包真模型真端到端、端到端禁止 mock、断言必须
可证伪且读会话日志而非页面文字、没实测过的一律标注未实测。每条标准背后都有一次真实
事故，事故都留在 docs/STANDARDS.md 里。任何人来这个项目，都能顺着这些文档看到
AI 产品技术架构在底层到底是怎么工作的。