索引注入桥接 VCPr0j3k7/dsh-index-tap-bridge

dsh-index-tap-bridge

License: MIT
Node.js

为 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：

1. 窗口加载的是外壳内置的 SPA（自定义 scheme dsh-app://app/，资源来自 dsh-web-frontend/dist）；
2. Host 启动完成后，仅通过 IPC 上报一次 collectIndexInjections() 的结果，由外壳按注入行的 kind 逐条应用；
3. tapIndex 注册的变换仅在 renderIndex() 内执行，而 renderIndex() 只会在 Host 自行渲染 index 时被触发 —— 桌面版不会走到该路径。

由此产生的现象是：插件加载过程无任何报错，插件列表中也显示为已启用，但其注入的 / 从未被加载。

@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 均已注册）：

1. 读取 webServer.indexTaps（tapIndex() 的实现即向该数组 push，参见官方实现）；
2. 将每个变换作用于一份最小骨架 HTML，提取其新增的标记；
3. 将新增标记翻译为结构化注入行，push 进注入表；
4. 按 kind 与载荷去重，避免重复推送。

整个过程对原插件透明：其变换仍保留在 indexTaps 中，浏览器与 dsh web 经由 renderIndex() 的路径行为不变。桥接逻辑仅在桌面外壳中启用，判据见启用条件。

翻译规则

| 原始标记 | 翻译结果 |
| | { kind: 'script-src', src: 'U' } |
| 内联代码 | { kind: 'script', text, placement } |
| … | { kind: 'style', text } |
| 、div、span、template、noscript、iframe、meta | { kind: 'html', placement, html } |

必须单独映射为 script / script-src，不能由 html 行承载：桌面前端对 html 行使用 insertAdjacentHTML()，以此方式插入的 不会被执行。

启用条件

判据为 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() 的方式实现。
- 一类标记不会被强行翻译为 html 行：insertAdjacentHTML 无法表达「替换已有节点」的语义，强行翻译会产出错误结果，因此此类标记会被明确报告为未翻译。
- 官方桌面版的插件库开关会重写 dsh.profile.bundles（内部调用 sanitizeProfile(...) 清理非官方 bundle）。若桥接突然失效，应首先检查 bundles 中该条目是否仍然存在。

许可

MIT