dsh-index-tap-bridge
为 DeepSeek Harness (DSH) 提供 tapIndex 注入通道的兼容层，使依赖该通道的第三方插件在官方
Harness 桌面版中同样生效。
本插件以独立 bundle 形式装入 DSH profile，无需修改目标插件的任何源码。
目录
问题背景
@deepseek-ai/dsh-host-webserver 提供两条向 index.html 注入内容的通道：
| 通道 | 主要使用者 | 官方桌面版 |
|---|
结构化注入行（webserver/index-inject 事件） | 官方插件（dsh-client-modules 等） | 生效 |
索引变换（tapIndex(html => html)） | 大量第三方插件 | 不生效 |
原因在于官方桌面版不渲染 Host 的 index.html：
- 窗口加载的是外壳内置的 SPA（自定义 scheme
dsh-app://app/，资源来自 dsh-web-frontend/dist）；
- Host 启动完成后，仅通过 IPC 上报一次
collectIndexInjections() 的结果，由外壳按注入行的
kind 逐条应用；
tapIndex 注册的变换仅在 renderIndex() 内执行，而 renderIndex() 只会在 Host 自行渲染
index 时被触发 —— 桌面版不会走到该路径。
由此产生的现象是：插件加载过程无任何报错，插件列表中也显示为已启用，但其注入的
<script> / <style> 从未被加载。
@deepseek-ai/dsh-host-webserver 源码中对 applyIndexTaps() 的注释原文：
"the escape hatch for markup no IndexInjection row expresses"
环境要求
| 项 | 要求 |
|---|
| Node.js | ^22.19.0 || >=24 |
| DeepSeek Harness | 已在官方桌面版 0.1.7-rc.2 上验证 |
安装
# 装入指定 profile（web 为 dsh 首次运行时自动创建的 profile）
dsh plugin --profile web add github:VCPr0j3k7/dsh-index-tap-bridge
官方 Harness 桌面版使用 desktop profile：
dsh plugin --profile desktop add github:VCPr0j3k7/dsh-index-tap-bridge
无需手动修改 dsh.profile.bundles。dsh plugin 在 pnpm 执行完毕后会运行一次
reconcilePlugins()，凡声明了 dsh.bundle.patch 的依赖会被自动追加进 bundle 层栈。
确认已登记：
dsh --profile web --dump-config # 输出中应包含 index-tap-bridge
安装完成后需重启目标 harness。桌面版在启动时加载插件，运行中的实例不会热更新。
卸载
dsh plugin --profile desktop rm dsh-index-tap-bridge
reconcilePlugins() 会在依赖被移除后同步清理 dsh.profile.bundles 中的对应条目；若发现残留，
手动删除该条目即可。卸载后同样需要重启 harness。
工作原理
在 webserver/index-inject 事件发射的时刻（此时所有插件均已加载、tap 均已注册）：
- 读取
webServer.indexTaps（tapIndex() 的实现即向该数组 push，参见官方实现）；
- 将每个变换作用于一份最小骨架 HTML，提取其新增的标记；
- 将新增标记翻译为结构化注入行，push 进注入表；
- 按
kind 与载荷去重，避免重复推送。
整个过程对原插件透明：其变换仍保留在 indexTaps 中，浏览器与 dsh web 经由 renderIndex()
的路径行为不变。桥接逻辑仅在桌面外壳中启用，判据见启用条件。
翻译规则
| 原始标记 | 翻译结果 |
|---|
<script src="U"> | { kind: 'script-src', src: 'U' } |
<script>内联代码</script> | { kind: 'script', text, placement } |
<style>…</style> | { kind: 'style', text } |
<link>、div、span、template、noscript、iframe、meta | { kind: 'html', placement, html } |
<script> 必须单独映射为 script / script-src，不能由 html 行承载：桌面前端对 html 行
使用 insertAdjacentHTML()，以此方式插入的 <script> 不会被执行。
启用条件
判据为 process.argv 的前两位中是否包含 dsh-desktop-host（官方外壳正是以该方式 spawn Host）。
这是目前唯一能可靠区分「Host 的 index 是否会被渲染」的信号 —— 若改用 Electron 或
--expose-internals 等特征判断，会将自包含外壳（自行加载 Host URL、走 renderIndex() 路径）
一并误判，导致重复注入。
排障时可强制覆盖：
| 环境变量 | 取值 | 作用 |
|---|
DSH_INDEX_TAP_BRIDGE | on | 强制启用 |
DSH_INDEX_TAP_BRIDGE | off | 强制关闭 |
测试
npm test
test/check.mjs 为纯逻辑自检（23 项），不依赖 DSH 运行时，覆盖各翻译分支、空载荷丢弃、
顺序保持、不可翻译标记的上报，以及桌面外壳判定。当前 23/23 通过。
端到端验证：安装并重启桌面版后，原本不显示挂件的插件应开始正常工作；若插件带有日志，
可观察到其注入的资源被请求。
已知限制
- 仅翻译可翻译的标记。 若
tapIndex 中执行的是修改已有标记（而非新增），则无法翻译。
此类标记会通过 console.warn 列出，不会被静默忽略。
- 官方若变更
indexTaps 字段名，桥接将静默失效（存在 Array.isArray 守卫，不抛错）。
届时需改为包装 tapIndex() 的方式实现。
<canvas> 一类标记不会被强行翻译为 html 行：insertAdjacentHTML 无法表达「替换已有
节点」的语义，强行翻译会产出错误结果，因此此类标记会被明确报告为未翻译。- 官方桌面版的插件库开关会重写
dsh.profile.bundles（内部调用 sanitizeProfile(...) 清理
非官方 bundle）。若桥接突然失效，应首先检查 bundles 中该条目是否仍然存在。
许可
MIT
