openma-ai/dsh-agents-plugins

dsh Agents Plugins Bridge

通过一个桥接包，在 DeepSeek Harness 中安装 Agent Plugins、Codex 插件、Claude Code 插件和 Pi 包。

Bridge 是一个普通的 DeepSeek Harness
bundle：一个安装入口，许多小型 Cordis 插件。它会检测外部包格式，将显式选择的包复制到
profile 本地存储中，并将每个受支持的能力物化为各自独立的可逆 DSH 行。它不会模拟另一个
agent 运行时，也不会把所有内容都隐藏在一个通用插件背后。

快速开始

需要 Node.js 22.19 或更高版本。先安装 DSH，然后将同一个 Bridge 包添加到每个应使用外部
插件的 profile：

npm install -g @deepseek-ai/dsh

Web management UI + shared Host capabilities
dsh plugin --profile web add @openma/dsh-agents-plugins-bridge@latest
dsh web

Terminal UI + the same shared Host capabilities
dsh plugin --profile tui add @openma/dsh-agents-plugins-bridge@latest
dsh --profile tui

DSH profile 是彼此独立的组合，因此安装到 web 不会静默修改 tui，反之亦然。用户只需
安装根 Bridge 包。它通过自身的依赖图携带 Web 界面、格式适配器和 MCP Apps 支持。

Web

打开 Settings → Plugins → Agent plugins 以扫描本地 Codex、Claude Code 和 Pi 状态；
注册或导入 marketplace；搜索目录；安装插件；检查每个插件的能力行和诊断信息；以及管理
Pi 包更新检查。

DSH Web 中的 Agent Plugins 管理

Web 面板是 Host 运行时之上的管理界面。关闭面板不会停止已安装的 hooks、commands、
skills、MCP servers 或 Pi extensions。

TUI

TUI 不需要第二套 Bridge 实现。/plugin-bridge、导入的斜杠命令和用户可调用的 skills
都通过 ACP 从同一个 Host 组合投射出来，并出现在 TUI 正常的可搜索命令菜单中。Hooks、
monitors、MCP connections、agents、LSP rows 和 Pi extension
生命周期保留在 Host 上，无需浏览器即可继续工作。

该截图来自
DeepSeek Harness TUI，其
命令菜单是 Bridge 命令和导入技能接入的界面。

MCP Apps 是有意为之的例外：共享的 MCP 连接、工具、
资源、提示词和后端钩子在 TUI 中均可工作，但不受信任的 App HTML
仅由 Web 沙箱渲染。终端不执行浏览器 UI。

无头所有者

诸如 pi-telegram 之类的 Pi 扩展即使在没有打开任何 UI 时，
也可能需要一个活动 Session。请使用
Martty owner
来管理该进程生命周期。Bridge 仍然负责导入、物化、钩子、
工具、命令和扩展运行时；Martty 是通用的 ACP rpc 客户端，
它保持 Session 存活，并且只调用显式公布的启动
和关闭命令。它不会自动批准权限或应答
扩展表单。

| 能力 | Web | TUI |
|---|:---:|:---:|
| 发现、导入、安装、启用、禁用、卸载 | 面板 + 命令 | 命令 |
| 技能、斜杠命令、提示词模板 | 是 | 是 |
| Codex 和 Claude Code 钩子 | 是 | 是 |
| MCP 工具、资源、提示词和服务器生命周期 | 是 | 是 |
| Claude 代理、输出样式、监控器和 LSP | 是 | 是 |
| Pi 扩展、工具、命令、技能和生命周期 | 是 | 是 |
| 外部浏览器主题 | 是 | 否 |
| MCP Apps HTML/AppBridge 渲染器 | 是 | 否 |

使用 Bridge

检查活动的 Bridge 和只读发现结果：

/plugin-bridge
/plugin-bridge marketplace list
/plugin-bridge discover
/plugin-bridge marketplace discover

添加本地市场目录或 GitHub 仓库，然后安装一个
目录条目：

/plugin-bridge marketplace add /absolute/path/to/marketplace
/plugin-bridge marketplace add https://github.com/company/agent-plugins
/plugin-bridge marketplace add company/agent-plugins@main
/plugin-bridge install deployment-tools@company-tools

导入另一个代理已在本地注册的状态：

/plugin-bridge discover
/plugin-bridge import codex-local-cache:personal/deployment-tools/1.2.3
/plugin-bridge marketplace discover
/plugin-bridge marketplace import claude-code-registered-marketplaces:company-tools

发现是只读的。导入首先将选定的包或目录
复制到配置文件本地的 Bridge 存储中；外部代理目录绝不会被就地执行
或修改。安装和导入随后共享相同的格式检测、
组件适配器、Loader 事务、回滚和持久状态。

disable 移除活动行但保留已复制的包，enable 恢复
符合条件的已存储计划，并且 uninstall 会将包副本移入配置文件本地的
回收站。

架构

该布局遵循 DSH 的标准插件形态：

root bundle patch
├─ kernel + one provider/locator/adapter per capability dialect
├─ runtime + /plugin-bridge command
├─ package-owned Web gateway/client wrappers
└─ package-owned MCP Apps Host/Web wrappers
└─ resolve dependency from Bridge's graph → Loader import → ctx.plugin

installed foreign package
└─ normalized components
├─ skill row
├─ MCP connection row(s)
├─ hook row(s)
├─ command / agent / monitor row(s)
└─ Pi extension row(s)

在 pnpm 下，包自有的包装器条目非常重要：配置文件只解析
@openma/dsh-agents-plugins-bridge/*；每个包装器从 Bridge 包自身的依赖图中解析其运行时，
通过 DSH 的 Loader 导入它，
并将其挂载为子 Cordis 插件。传递依赖提升从来都不是
运行时契约的一部分。支持 Web 的包装器行还会暴露自己的
/package.json 以及一个精确 ID 的浏览器 bundle，因此 DSH 官方的
dsh.client 扫描器会从同一行构建 Browser 树，而不需要
在配置文件中再引入第二个 UI 包。

生命周期内核暴露六个可逆注册表：

MarketplaceProvider   discovers marketplace catalogs and resolves package sources
PackageFormatProvider recognizes and normalizes an extracted plugin package
ComponentAdapter      maps normalized components onto explicit dsh Cordis rows
InstalledPluginLocator observes one agent's local plugin registry/cache
MarketplaceRegistrationLocator observes one agent's registered catalogs
ActivationPolicy      inspects and gates rows that require explicit user trust

每一次成功安装都会编译为显式行。每项能力都可以
独立地加载、失败、重新加载、禁用和卸载。一个 MCP 清单会再次展开，
使每个已配置的服务器都拥有自己的
@deepseek-ai/dsh-mcp-client 行。

MCP 工具、资源、提示词和 Apps 复用同一个 MCP SDK 连接。
Bridge 通过两个
独立的包自有包装器，包含来自
@openma/dsh-mcp-apps 的 Host 和 Web 两半。一个 Codex 注册的 App 是外部宿主
例外：它的中继拥有一个 Codex app-server 进程，因为 Codex 仍然拥有
该连接和 OAuth 生命周期。

Hook 行对 DSH 官方的 Codex 和
Claude Code hook 插件使用相同的依赖包装器模式。包装器行拥有嵌套的插件 fiber，因此 Web
和 TUI 共享同一个 Host 生命周期，而不需要配置文件单独安装或
提升这些运行时包。

可移植包核心

Agent Plugins 1.0 是可移植核心。当前 provider 识别规范根清单：

{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "minimal-plugin"
}
它只在固定位置发现标准组件：

- skills/ 用于 Agent Skills
- mcp.json 用于 MCP 服务器

桥接器首先验证 skills/ 是一个目录，且 mcp.json 是一个常规文件。错误的条目类型只会禁用该组件，并产生一条安装诊断信息。有效的 skills/ 目录会成为一行隔离的 @deepseek-ai/dsh-skill-filesystem；该 dsh 提供程序会发现直接的 /SKILL.md 包，并对格式错误的条目发出警告并跳过，而不会丢弃有效的同级条目。因此，每个技能的解析警告属于 dsh 技能提供程序，而不是桥接器安装结果。

Schema 选择是本地进行的，并以规范的 $schema 标识符为键。插件加载从不下载 schema。提供程序强制执行 Agent Plugins 名称约束和封闭的 author 对象。未知的顶层字段和非对象的 extensions 字段仍作为可见诊断信息，而不会成为可移植语义。

可移植的 mcp.json 使用自己的适配器行，与 Codex 和 Claude MCP 兼容性分开。每个有效的服务器都会成为一行 Loader。该适配器支持 stdio 和 streamable-http，验证它们的封闭变体，仅在 args、env 和 cwd 中应用标准的 ${PLUGIN_ROOT} 和 ${PLUGIN_DATA} 替换，并注入一个持久的、按安装区分的 PLUGIN_DATA 目录。无效的单个服务器以及 dsh 不支持的旧版 sse 传输会被跳过并产生诊断信息，同时独立的技能和服务器会继续加载。

Codex .codex-plugin/plugin.json 和 Claude Code .claude-plugin/plugin.json 布局是兼容性提供程序；它们不会重新定义可移植核心。

兼容性

| 来源 | 目录 | 包 | 物化组件 |
|---|---|---|---|
| Agent Plugins 1.0 | 市场方言未标准化 | plugin.json | skills/、mcp.json |
| Codex | .agents/plugins/marketplace.json | .codex-plugin/plugin.json | 技能、MCP 服务器、已注册 Apps、Codex hooks |
| Claude Code | .claude-plugin/marketplace.json | .claude-plugin/plugin.json | 技能、MCP 服务器、hooks、命令、代理、输出样式、监视器、主题、LSP 服务器 |
| Pi | 无市场注册表 | 带 pi 的 package.json，或约定目录 | 扩展、技能、提示模板、主题 |

Codex 市场解析遵循官方 OpenAI 打包参考：本地源可以是 ./ 字符串或 { "source": "local", "path": "./..." }；HTTPS url 和 git-subdir 条目遵循 ref 或 sha。Git 子目录在克隆后从根目录包含的路径复制。文档中记录的 npm 源会被拒绝，并给出明确的不支持诊断，因为安全地复现 Codex 的无生命周期脚本安装尚未实现。
支持 Claude 市场本地目录以及官方 github、HTTPS url 和 git-subdir 源形态。Git 子目录必须保持在根目录内，并且保留 ref 或 sha 固定。文档中记录的 npm 源仍然是明确的不支持错误；未知的源形态绝不会被猜测或静默降级。GitHub 市场 URL 和 owner/repo@ref 简写会在不使用 shell 的情况下克隆。

本地发现边界

Codex 插件发现仅从 ~/.codex/config.toml 读取 [plugins."plugin@marketplace"] 注册项，然后在 ~/.codex/plugins/cache/// 下解析匹配的带版本副本。结果保留配置的启用/禁用状态，并标记为 plugin-cache，因为 Codex 在那里不暴露单独的已安装路径 JSON 注册表。宽泛的 ~/.codex/.tmp/plugins 目录同步被有意忽略，绝不会作为已安装状态呈现。

Claude Code 插件发现读取其显式的 ~/.claude/plugins/installed_plugins.json 注册表，并将结果标记为 installed-registry。它不会从市场检出或缓存内容推断安装。

Pi 包发现读取 ~/.pi/agent/settings.json 和当前项目的 .pi/settings.json 中显式的 packages 数组。它解析 Pi 管理的 npm 和 git 安装根目录，以及相对于所属设置文件的本地路径。Pi 没有市场注册表：npm、git 和本地路径是包源，而公共包库是发现元数据，而不是目录注册。仅凭 pi-package 关键字绝不会声称一个普通 Node 包。

Pi 包清单可以声明扩展、技能、提示模板和主题，或使用匹配的约定目录。专用的 Pi 技能提供程序在将每个定义注册到 ctx.skills 之前，保留精确的文件、目录、递归 SKILL.md 发现、扁平 Markdown 技能、glob 表达式和 ! 排除项。提示资源保留相同的路径表达式边界，并成为带命名空间的 DSH 斜杠命令。主题 JSON 解析 Pi 变量和 xterm-256 颜色，映射 DSH 暴露的角色，并通过独立的主题客户端行注册浏览器主题。Pi 扩展通过代理作用域的兼容宿主加载，该宿主将其命令、工具、UI 问题和生命周期回调映射到 DSH。

已注册的市场发现是另一个提供程序层。Codex 仅从 ~/.codex/config.toml 读取 [marketplaces.] 条目；Claude Code 仅读取 ~/.claude/plugins/known_marketplaces.json。Claude 的 installLocation 和 Codex 本地源在注册前会被复制。受支持的 GitHub Codex Git 注册项通过现有的安全市场管理器重新获取。格式错误、缺失、重复或不支持的条目会成为按提供程序划分的诊断信息，并且不会抑制有效的同级条目。
不支持的旧版组件会保留在安装结果中，而不是静默消失。Claude 代理会变为带命名空间的 DSH 子代理工具；只有显式映射的 Claude 工具名称才会进入其允许列表，而不支持的模型覆盖仍作为诊断信息保留。普通输出样式会按代理注册 /output-style-- 命令，而 force-for-plugin 样式则遵循 Claude 的自动替换或 keep-coding-instructions 行为。监视器仅使用已验证的 always 和 on-skill-invoke: 生命周期接缝，并通过 DSH 的子进程服务运行。缺少必需字段和未知变体会产生诊断信息且不生成行——不存在 basename、默认描述、事件或模型回退。未来的 OpenCode 方言仍需要匹配的 DSH 接缝或运行时兼容层。由捆绑的 MCP 服务器返回的 MCP Apps 通过共享的 dsh MCP 连接工作。

Codex Apps 适配器可识别 .app.json 注册连接标识符，而不会将不透明 ID 视为可执行的 MCP 配置。同名的捆绑 MCP 服务器会直接解析该 App。否则，每个声明的连接会编译为两个独立的行：一个标准的 @deepseek-ai/dsh-mcp-client 行，用于启动 codex-host-relay，以及一个 DSH 工具审批策略行。中继使用 codex app-server --stdio，验证 app/installed 表明该连接已启用且可调用，打开一个临时线程，按连接器 ID 过滤 codex_apps 目录，并代理该 App 的工具、资源、资源模板、工具 _meta、结果 _meta 和结构化内容。它从不读取或复制 Codex 的 OAuth 数据库或令牌。Codex app-server 目前不会通过其直接的 MCP 状态/调用接口暴露托管 App 的提示，因此中继不会宣传任何虚构的提示；普通的捆绑 MCP 服务器仍保留其原生提示生命周期。

只读分类来自托管工具的注解。声明的只读调用会直接通过；写入操作会通过 DSH 的正常审批接缝请求批准，而检查目录中不存在的新工具会被视为写入。外部主机要求仍然附加，以便 Web 可以解释必须安装、连接并登录 Codex。持久安装会有意恢复其确切存储的行计划，因此由较旧桥接构建导入的插件必须卸载并重新导入，才能获得新添加的适配器行。

命令

自有命令命名空间是 /plugin-bridge：

/plugin-bridge marketplace add
/plugin-bridge marketplace discover
/plugin-bridge marketplace import
/plugin-bridge marketplace list
/plugin-bridge install @
/plugin-bridge discover
/plugin-bridge import
/plugin-bridge enable
/plugin-bridge disable
/plugin-bridge uninstall
发现始终是只读的，首次导入始终是显式的。导入的主机快照在运行时启动时协调一次，之后默认每五分钟协调一次；将 autoUpdateIntervalMs 设置为另一个正数间隔，或设置为 0 以禁用轮询。Codex 协调在其版本化缓存中遵循 SemVer 优先级。Claude Code 遵循 installed_plugins.json 中确切的活动条目，包括上游回滚。Pi 本地路径包保持仅显式导入。内容摘要也能在没有新版本字符串的情况下检测到变更。替换包会先被复制并验证，然后在现有 Bridge 拥有的根目录中交换其行；任何获取、验证、激活或持久化失败都会恢复先前的包和活动行。

Pi npm 和 Git 包还使用 Pi 的公共原生包管理器 API。Web 面板默认设置为仅通知，在到期时于启动时检查，之后每六小时检查一次，并且仅列出已导入此 Bridge 配置文件的 Pi 包的更新。用户可以选择自动更新或关闭检查，将单个包排除在自动更新之外，立即检查，以及更新一个包或所有可用包。手动操作忽略自动更新排除项。固定版本、npm 和 Git 行为、用户/项目范围以及包安装布局仍由 Pi 拥有；Bridge 不实现第二个 npm 或 Git 更新器。原生包源保留在主机上，Web 客户端仅接收不透明 ID。将 piUpdateCheckIntervalMs 设置为另一个正数间隔，或设置为 0 以禁用后台检查；手动检查仍然可用。

导入的 Claude 输出样式在常规 DSH 命令注册表中公开其生成的选择命令。Hook 行不会添加第二个摘要批准门：导入并启用插件会直接激活原生 DSH Codex 或 Claude Code hook 桥接。

安全与生命周期

- 包路径和符号链接目标不能逃逸出复制的插件根目录。
- 外部插件和 marketplace 目录永远不会被修改；显式导入会先复制。
- Marketplace 相对源拒绝绝对路径和路径遍历。
- Git 通过参数数组调用，绝不通过 shell 调用。
- 可移植 MCP 子进程接收固定的、由 Bridge 拥有的 PLUGIN_ROOT 和 PLUGIN_DATA；可移植方言不执行任意 ${ENV} 展开。
- Codex 注册的 App 凭据保留在 Codex 内部；中继使用公共 app-server 协议，并且仅持久化插件已声明的不透明连接标识符。
- 标记为非只读的 Codex App 工具，以及该中继命名空间中未知的未来工具，在分发前需要 DSH 批准。
- 加载器激活和状态持久化在失败时一起回滚。
- 外部可执行模块在发现期间永远不会运行。显式导入加启用是执行同意边界；Pi 扩展以及 Codex 和 Claude Code hooks 不会添加重复的摘要批准步骤。
- 注册、行激活、禁用和处置都是可逆的。
- 已卸载的包副本会移动到配置文件本地的回收站，而不是被递归删除。

相关项目

| 项目 | 用途 |
|---|---|
| DeepSeek Harness | 万物皆插件的 Host、Loader、Web 界面和能力服务 |
| DeepSeek Harness TUI | 终端原生的 ACP 客户端；从共享的 Host 组合中接收 Bridge 命令和技能 |
| DeepSeek Harness ACP | 向 Zed 等 ACP 客户端暴露相同的 Host 命令、技能、工具和会话 |
| dsh-mcp-apps | 独立的 MCP Apps Host 和沙箱化 Web 渲染器；已由此 Bridge 包含 |
| Agent Plugins | 可移植的插件清单、技能和 MCP 包标准 |
| Pi packages | Pi 包画廊和扩展生态系统 |

当目标是使用 Codex、Claude Code、Pi 或可移植的 Agent Plugins 时，请安装 Bridge。仅当某个配置文件需要 MCP Apps 渲染而不需要外部插件兼容层时，才直接安装 @openma/dsh-mcp-apps。

开发

npm install
npm test
npm run typecheck
npm run build

Git 安装会运行 prepare 以生成 lib/。pnpm 10 可能要求用户显式允许该构建脚本；注册表发布版本和打包的 tarball 会附带已构建的输出。