Skip to content

Latest commit

 

History

History
60 lines (48 loc) · 4.04 KB

client-bundle.md

File metadata and controls

60 lines (48 loc) · 4.04 KB

客户端接入与产物格式(详细)

客户端加载须知(两个 inject 不是一回事)

这份 package.json 里有两个 inject,它们在不同的层、要填不同的东西 —— 混淆过一次, 症状是 web 客户端启动时报 import failed / did not activate:

位置 填什么 当前值
package.json → dsh.client.inject 客户端模块的包名 @deepseek-ai/dsh-client-ui-settings、@deepseek-ai/dsh-client-ui-slots、@deepseek-ai/dsh-client-ui-renderer
src/client.ts → export const inject cordis 服务名 ['slots', 'configForms']
  • 前者是「先把这些客户端模块加载起来」的清单,只接受能解析到的包名(参照实现里 20 个插件的值 全是 @deepseek-ai/dsh-client-* / @deepseek-ai/dsh-api-*;写裸服务名如 "slots" 会解析失败)。
  • 后者是 cordis 的依赖声明:slots 是槽注册表,configForms 是本分区绑宿主原生表单用的服务 (所有在参照实现里带设置分区的插件都声明了它)。
  • 关于 immediately:DSH 官方模板里有这个字段(templates/decoration/package.json), 但本机已安装的 20 个 dsh.client 插件都没用它。本仓库不再使用它。 这里必须说清楚:它既不是病根、也不是禁令 —— 当初删掉它是因为它同时不符合本地惯例, 而真正导致 import failed 的是产物格式(见下一节)。

客户端产物必须是 lazy-CJS factory(否则 web 端直接起不来)

lib/client.js 不是 ESM 模块,lib/index.js 才是。 两个半边是两种不同格式,别一起改:

  • 宿主半边 lib/index.js:普通 ESM,宿主用 import() 加载它。

  • 浏览器半边 lib/client.js:只注册一个惰性 factory,由 web 客户端求值:

    window.__ModuleLoader__.load({
      id: "dsh-image-forge",              // 必须 = 包名
      factory: (require) => {
        var module = { exports: {} };
        var exports = module.exports;
        …
        return module.exports;            // 只发布 apply 与 inject
      }
    });

    执行 bundle 只注册 factory;所有模块体副作用(含 CSS 注入)都在 factory 闭包里,等到物化时才跑。 本插件在 apply() 里调用 injectClientStyles()(src/client-styles.ts):往 document.head 插一根 id="dsh-image-forge-client-styles" 的 <style>,幂等。样式跟设置页/工具卡片的 dsh-image-forge-* 类名绑定,布局用容器查询(container-type: inline-size)按设置栏自身宽度切换标签/控件双栏或堆叠—— 宽 Host 窗口里的窄设置栏也会堆叠,视口 @media 看不见这种情况。 React 来自 shell 预置的冻结模块表(PLATFORM_MODULES),因此走 factory 的 require("react"), 既不打包进来、也不写进 dsh.client.external(它已在基线表里)。而且必须单文件、零相对 require —— loader 只物化这一个 bundle,不能同步解析同级的 client*.js。

    这条由 tsdown.client.config.ts 负责(CJS 输出 + banner 开 factory + footer 关 factory), 由 pnpm build 跑两趟:tsdown && tsdown -c tsdown.client.config.ts(第二条不能开 clean, 否则会删掉同一目录里的 lib/index.js)。

    ⚠️ 为什么这件事必须写成断言:顶层 import 的 ESM bundle 什么都不注册,客户端只会报 import failed —— 而本仓库的 Node 测试从不求值浏览器 bundle,所以这个错误能在 100+ 个 全绿用例下存活到第一次真机加载。test/settings.test.mjs 现在钉住:产物含 window.__ModuleLoader__.load、id: "dsh-image-forge"、require("react")、return module.exports, 恰好只发布 apply / inject,且不含任何顶层 import/export 语句、不含相对 require、 不含打包进来的 React。