@dsh-plugin/dsh-loader 1.0.0

package/README.md

@@ -0,0 +1,226 @@
+# dshloader
+
+[English](#english) | [中文](README.zh-CN.md)
+
+---
+
+## English
+
+A runtime compatibility shim for **dsh** (DeepSeek Harness) cordis bundle
+plugins. dshloader decouples third-party plugins from dsh's internal service
+names, module paths, package names, and RPC details through a version-aware
+**adapter registry**, so that when dsh upgrades and breaks internal APIs, you
+only upgrade dshloader — plugins keep working unchanged.
+
+### Why
+
+dsh is moving fast and its internal surface changes between releases:
+
+- `httpServer` was renamed to `webServer` — old plugins that inject
+  `httpServer` hang forever.
+- Deep source imports like
+  `@deepseek-ai/dsh-client-runtime/src/client/sessions/context-provenance.ts`
+  break when dsh ships no `src/`.
+- Client UI packages like `@deepseek-ai/dsh-client-ui-primitives` could be
+  renamed in future dsh versions, breaking every plugin that imports them
+  directly.
+- The official `dsh-host-apiproxy` hardcodes a settings namespace whitelist,
+  so third-party settings cards never appear in the Web UI.
+
+dshloader absorbs these (and future) breaks behind a **stable API**:
+`ctx.dshLoader` on the host, `window.__dshLoader__` in the browser, and
+`@dsh-plugin/dsh-loader/*` stable subpaths for package imports.
+
+### Quick start
+
+#### 1. Install dshloader into a profile
+
+```sh
+dsh plugin --profile <name> add /path/to/dshloader
+# or
+DSH_HOME=~/.dsh npx dshloader setup <name>
+```
+
+#### 2. Plugin `package.json` — only depend on dshloader
+
+```json
+{
+  "dependencies": {
+    "@dsh-plugin/dsh-loader": "link:..."
+  }
+}
+```
+
+> **Plugins must NOT declare any `@deepseek-ai/*` dependency.** All dsh
+> packages are accessed through dshloader's stable subpaths.
+
+#### 3. Host side — use `ctx.dshLoader`
+
+```js
+export const inject = ['dshLoader'];
+
+export async function apply(ctx) {
+  // Settings: register a namespace
+  const scope = ctx.dshLoader.settings.register('my-plugin', schema);
+
+  // Web: register routes and WebSocket upgrades
+  ctx.dshLoader.web.get('/api/my-plugin/status', (req, res) => res.json({ ok: true }));
+  ctx.dshLoader.web.registerUpgrade({ path: '/ws/my-plugin', handler: fn });
+
+  // Services: read cordis services
+  const sessions = ctx.dshLoader.services.get('sessions');
+}
+```
+
+#### 4. Import dsh packages via stable subpaths
+
+```js
+// Host packages
+const { defineTool } = require('@dsh-plugin/dsh-loader/tools');
+
+// Client UI packages (in client bundle source)
+import { IconCloseFill14 } from '@dsh-plugin/dsh-loader/ui-primitives';
+```
+
+**Stable subpath → real dsh package mapping (dsh 1.x):**
+
+| Stable subpath | Real dsh package |
+|---|---|
+| `@dsh-plugin/dsh-loader/tools` | `@deepseek-ai/dsh-tools` |
+| `@dsh-plugin/dsh-loader/llm` | `@deepseek-ai/dsh-llm` |
+| `@dsh-plugin/dsh-loader/agent` | `@deepseek-ai/dsh-agent` |
+| `@dsh-plugin/dsh-loader/settings` | `@deepseek-ai/dsh-settings` |
+| `@dsh-plugin/dsh-loader/ui-primitives` | `@deepseek-ai/dsh-client-ui-primitives` |
+| `@dsh-plugin/dsh-loader/ui-slots` | `@deepseek-ai/dsh-client-ui-slots` |
+| `@dsh-plugin/dsh-loader/ui-settings` | `@deepseek-ai/dsh-client-ui-settings/client` |
+| `@dsh-plugin/dsh-loader/web-react` | `@deepseek-ai/dsh-client-web-react` |
+| `@dsh-plugin/dsh-loader/schema-form` | `@deepseek-ai/dsh-client-schema-form` |
+| `@dsh-plugin/dsh-loader/runtime` | `@deepseek-ai/dsh-client-runtime/client` |
+
+When dsh renames a package, only the dshloader adapter changes — plugin
+source and bundle stay the same.
+
+#### 5. Client side — use `window.__dshLoader__`
+
+```js
+// Read cordis client services
+const conv = window.__dshLoader__.services.get('conversation');
+
+// Register a package alias at runtime (fallback)
+window.__dshLoader__.registerPackageAlias('@old/pkg', '@new/pkg');
+```
+
+#### 6. Build config — mark stable subpaths as external
+
+```ts
+const CLIENT_EXTERNALS = [
+  'react', 'react/jsx-runtime', 'react-dom', 'react-dom/client', 'cordis',
+  '@dsh-plugin/dsh-loader/ui-primitives',
+  '@dsh-plugin/dsh-loader/ui-slots',
+  '@dsh-plugin/dsh-loader/ui-settings',
+  '@dsh-plugin/dsh-loader/web-react',
+  '@dsh-plugin/dsh-loader/schema-form',
+  '@dsh-plugin/dsh-loader/runtime',
+]
+```
+
+### How it works
+
+```
+plugin ──▶ ctx.dshLoader.{settings,web,services} ──▶ dshloader adapter
+                                                         │
+                                                         ▼
+                                               real dsh (current version)
+
+plugin bundle ──▶ require('@dsh-plugin/dsh-loader/ui-primitives')
+                         │
+                         ▼ (__ModuleLoader__ wrapper maps stable name)
+                   require('@deepseek-ai/dsh-client-ui-primitives')
+                         │
+                         ▼
+                   dsh module table
+```
+
+1. **Version detection** reads `node_modules/@deepseek-ai/dsh/package.json`
+   (or `DSHLOADER_DSH_VERSION` for tests/override).
+2. **AdapterRegistry** selects the best adapter for the detected version
+   (exact → range → nearest-low fallback → clear error).
+3. The selected **adapter** registers service aliases, installs package-name
+   mapping hooks (host: `Module._resolveFilename`; client:
+   `__ModuleLoader__.load` wrapper), and (only when opted in) the settings
+   whitelist bypass bridge. All registrations use `ctx.reflect.provide` /
+   `ctx.effect`, so cordis auto-recycles them on fiber unload.
+
+> **Load order does not matter.** cordis is reactive dependency injection:
+> plugins declaring `inject: [...]` stay `PENDING` until the alias is
+> provided, regardless of where dshloader sits in `cordis.patch.yml`.
+
+### Settings whitelist bypass (`exposeAllNamespaces`)
+
+By default dshloader **does not** bypass the official settings namespace
+whitelist. Opt in explicitly:
+
+- env: `DSHLOADER_EXPOSE_ALL_SETTINGS=1`
+- profile `package.json`: `dsh.dshloader.exposeAllNamespaces: true`
+
+> **Security trade-off**: enabling this removes the official default-deny
+> boundary for browser settings access. Only enable it in profiles where you
+> trust every installed plugin.
+
+### CLI
+
+```
+dshloader setup <profile>        Inject dshloader into a profile (dep + patch).
+dshloader dump-config <profile>  Run `dsh --profile <name> --dump-config`.
+dshloader info [profile]         Print loader version, detected dsh version,
+                                 selected adapter.
+```
+
+### Rollback / disable
+
+- Disable per launch: `DSHLOADER_DISABLE=1 dsh web`
+- Remove: `dsh plugin --profile <name> rm @dsh-plugin/dsh-loader`
+
+### Project layout
+
+```
+src/
+  index.js            host bundle entry (name / inject / apply)
+  client.js           client bundle entry (immediately tier)
+  api.js              DshLoaderHostAPI construction
+  registry.js         AdapterRegistry + version detection
+  version.js          loader version + log prefix
+  stable/             stable subpath re-exports (ui-primitives, tools, ...)
+  services/
+    settings.js       settings stable API
+    web.js            web stable API
+    services.js       services stable API (get / alias)
+  adapters/
+    dsh-1-x.js        dsh 1.x adapter
+    index.js          adapter registration
+  setup.mjs           profile injection + dump-config + info
+bin/dshloader.mjs     CLI entry
+docs/
+  api.md              full API reference (Chinese)
+  design.md           design document (Chinese)
+tests/                L1 (unit) / module (L2) / integration (L3)
+examples/
+  sample-plugin/      minimal example plugin
+  dsh-aux-state/      example using ctx.dshLoader only
+```
+
+### Develop
+
+```sh
+pnpm install
+npm test            # all tests
+npm run test:l1     # unit
+npm run test:l2     # module
+npm run test:l3     # integration
+```
+
+Node.js >= 18, `node --test`, no extra test framework.
+
+### License
+
+BSD-3-Clause

package/README.zh-CN.md

@@ -0,0 +1,202 @@
+# dshloader
+
+[English](README.md) | [中文](#中文)
+
+---
+
+## 中文
+
+**dsh**（DeepSeek Harness）cordis bundle 插件的运行时兼容层。dshloader 通过版本感知的**适配器注册表**，把第三方插件与 dsh 的内部服务名、模块路径、包名、RPC 细节解耦——dsh 升级改了内部 API 时，只需升级 dshloader，插件不用改。
+
+### 为什么需要
+
+dsh 迭代很快，内部 API 在版本间会变：
+
+- `httpServer` 被重命名为 `webServer`——旧插件注入 `httpServer` 会永远挂起。
+- 深层源码导入如
+  `@deepseek-ai/dsh-client-runtime/src/client/sessions/context-provenance.ts`
+  在 dsh 不再发布 `src/` 时直接报错。
+- 客户端 UI 包如 `@deepseek-ai/dsh-client-ui-primitives` 在未来 dsh 版本中可能改名，直接 import 的插件全部会坏。
+- 官方 `dsh-host-apiproxy` 硬编码了 settings namespace 白名单，第三方设置卡片无法出现在 Web UI 中。
+
+dshloader 把这些（以及未来的）破坏性变更吸收到**稳定 API** 后面：host 侧的 `ctx.dshLoader`、浏览器侧的 `window.__dshLoader__`、以及包导入的 `@dsh-plugin/dsh-loader/*` 稳定 subpath。
+
+### 快速上手
+
+#### 1. 安装 dshloader 到 profile
+
+```sh
+dsh plugin --profile <name> add /path/to/dshloader
+# 或
+DSH_HOME=~/.dsh npx dshloader setup <name>
+```
+
+#### 2. 插件 `package.json`——只依赖 dshloader
+
+```json
+{
+  "dependencies": {
+    "@dsh-plugin/dsh-loader": "link:..."
+  }
+}
+```
+
+> **插件不允许声明任何 `@deepseek-ai/*` 依赖。** 所有 dsh 包都通过 dshloader 的稳定 subpath 访问。
+
+#### 3. Host 侧——用 `ctx.dshLoader`
+
+```js
+export const inject = ['dshLoader'];
+
+export async function apply(ctx) {
+  // Settings：注册 namespace
+  const scope = ctx.dshLoader.settings.register('my-plugin', schema);
+
+  // Web：注册路由和 WebSocket upgrade
+  ctx.dshLoader.web.get('/api/my-plugin/status', (req, res) => res.json({ ok: true }));
+  ctx.dshLoader.web.registerUpgrade({ path: '/ws/my-plugin', handler: fn });
+
+  // Services：读取 cordis 服务
+  const sessions = ctx.dshLoader.services.get('sessions');
+}
+```
+
+#### 4. 通过稳定 subpath 导入 dsh 包
+
+```js
+// Host 包
+const { defineTool } = require('@dsh-plugin/dsh-loader/tools');
+
+// Client UI 包（在 client bundle 源码中）
+import { IconCloseFill14 } from '@dsh-plugin/dsh-loader/ui-primitives';
+```
+
+**稳定 subpath → dsh 真实包名映射（dsh 1.x）：**
+
+| 稳定 subpath | dsh 真实包名 |
+|---|---|
+| `@dsh-plugin/dsh-loader/tools` | `@deepseek-ai/dsh-tools` |
+| `@dsh-plugin/dsh-loader/llm` | `@deepseek-ai/dsh-llm` |
+| `@dsh-plugin/dsh-loader/agent` | `@deepseek-ai/dsh-agent` |
+| `@dsh-plugin/dsh-loader/settings` | `@deepseek-ai/dsh-settings` |
+| `@dsh-plugin/dsh-loader/ui-primitives` | `@deepseek-ai/dsh-client-ui-primitives` |
+| `@dsh-plugin/dsh-loader/ui-slots` | `@deepseek-ai/dsh-client-ui-slots` |
+| `@dsh-plugin/dsh-loader/ui-settings` | `@deepseek-ai/dsh-client-ui-settings/client` |
+| `@dsh-plugin/dsh-loader/web-react` | `@deepseek-ai/dsh-client-web-react` |
+| `@dsh-plugin/dsh-loader/schema-form` | `@deepseek-ai/dsh-client-schema-form` |
+| `@dsh-plugin/dsh-loader/runtime` | `@deepseek-ai/dsh-client-runtime/client` |
+
+dsh 改包名时，只需改 dshloader 适配器——插件源码和 bundle 不用动。
+
+#### 5. Client 侧——用 `window.__dshLoader__`
+
+```js
+// 读取 cordis client 服务
+const conv = window.__dshLoader__.services.get('conversation');
+
+// 运行时注册包名别名（兜底用）
+window.__dshLoader__.registerPackageAlias('@old/pkg', '@new/pkg');
+```
+
+#### 6. 构建配置——把稳定 subpath 加入 external
+
+```ts
+const CLIENT_EXTERNALS = [
+  'react', 'react/jsx-runtime', 'react-dom', 'react-dom/client', 'cordis',
+  '@dsh-plugin/dsh-loader/ui-primitives',
+  '@dsh-plugin/dsh-loader/ui-slots',
+  '@dsh-plugin/dsh-loader/ui-settings',
+  '@dsh-plugin/dsh-loader/web-react',
+  '@dsh-plugin/dsh-loader/schema-form',
+  '@dsh-plugin/dsh-loader/runtime',
+]
+```
+
+### 工作原理
+
+```
+plugin ──▶ ctx.dshLoader.{settings,web,services} ──▶ dshloader 适配器
+                                                        │
+                                                        ▼
+                                              真实 dsh（当前版本）
+
+plugin bundle ──▶ require('@dsh-plugin/dsh-loader/ui-primitives')
+                        │
+                        ▼（__ModuleLoader__ wrapper 映射稳定名）
+                  require('@deepseek-ai/dsh-client-ui-primitives')
+                        │
+                        ▼
+                  dsh 模块表
+```
+
+1. **版本探测** 读取 `node_modules/@deepseek-ai/dsh/package.json`（或 `DSHLOADER_DSH_VERSION`）。
+2. **适配器注册表** 选择最适合当前版本的适配器（精确 → 范围 → 最近低版本回退 → 报错）。
+3. 选中的**适配器** 注册服务别名、安装包名映射钩子（host: `Module._resolveFilename`；client: `__ModuleLoader__.load` wrapper）、以及（仅在开启时）settings 白名单绕过桥接。所有注册通过 `ctx.reflect.provide` / `ctx.effect`，cordis 在 fiber 卸载时自动回收。
+
+> **加载顺序无关。** cordis 是响应式依赖注入：声明了 `inject: [...]` 的插件会停在 `PENDING` 状态，直到依赖的服务出现，与 dshloader 在 `cordis.patch.yml` 中的位置无关。
+
+### Settings 白名单绕过（`exposeAllNamespaces`）
+
+默认**不绕过**官方 settings namespace 白名单。需要时显式开启：
+
+- 环境变量：`DSHLOADER_EXPOSE_ALL_SETTINGS=1`
+- profile `package.json`：`dsh.dshloader.exposeAllNamespaces: true`
+
+> **安全权衡**：开启后会移除官方对浏览器 settings 访问的默认拒绝边界。仅在信任所有已安装插件的 profile 中开启。
+
+### CLI
+
+```
+dshloader setup <profile>        注入 dshloader 到 profile（依赖 + patch）。
+dshloader dump-config <profile>  运行 `dsh --profile <name> --dump-config`。
+dshloader info [profile]         打印 loader 版本、探测到的 dsh 版本、选中的适配器。
+```
+
+### 回滚 / 禁用
+
+- 单次启动禁用：`DSHLOADER_DISABLE=1 dsh web`
+- 移除：`dsh plugin --profile <name> rm @dsh-plugin/dsh-loader`
+
+### 项目结构
+
+```
+src/
+  index.js            host bundle 入口（name / inject / apply）
+  client.js           client bundle 入口（immediately tier）
+  api.js              DshLoaderHostAPI 构造
+  registry.js         适配器注册表 + 版本探测
+  version.js          loader 版本 + 日志前缀
+  stable/             稳定 subpath re-export（ui-primitives、tools 等）
+  services/
+    settings.js       settings 稳定 API
+    web.js            web 稳定 API
+    services.js       services 稳定 API（get / alias）
+  adapters/
+    dsh-1-x.js        dsh 1.x 适配器
+    index.js          适配器注册
+  setup.mjs           profile 注入 + dump-config + info
+bin/dshloader.mjs     CLI 入口
+docs/
+  api.md              完整 API 参考
+  design.md           设计文档
+tests/                L1（单元）/ module（L2）/ integration（L3）
+examples/
+  sample-plugin/      最小示例插件
+  dsh-aux-state/      仅用 ctx.dshLoader 的示例
+```
+
+### 开发
+
+```sh
+pnpm install
+npm test            # 全部测试
+npm run test:l1     # 单元测试
+npm run test:l2     # 模块测试
+npm run test:l3     # 集成测试
+```
+
+Node.js >= 18，`node --test`，无额外测试框架。
+
+### 许可证
+
+BSD-3-Clause

package/bin/dshloader.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+// dshloader CLI entry (M6). Subcommands: setup, dump-config, info.
+import { setupProfile, dumpConfig, info } from '../src/setup.mjs';
+
+const [cmd, ...rest] = process.argv.slice(2);
+
+function usage() {
+  console.log(`dshloader <command> [args]
+
+Commands:
+  setup <profile>        Inject dshloader into a profile (dependency + patch).
+  dump-config <profile>  Run \`dsh --profile <name> --dump-config\` to validate.
+  info [profile]         Print dshloader version, detected dsh version, adapter.`);
+}
+
+try {
+  switch (cmd) {
+    case 'setup': {
+      const profile = rest[0];
+      if (!profile) throw new Error('setup requires a profile name');
+      setupProfile(profile);
+      break;
+    }
+    case 'dump-config': {
+      const profile = rest[0];
+      if (!profile) throw new Error('dump-config requires a profile name');
+      const { ok, output } = dumpConfig(profile);
+      process.stdout.write(output);
+      process.exit(ok ? 0 : 1);
+    }
+    case 'info': {
+      info(rest[0]);
+      break;
+    }
+    default:
+      usage();
+      process.exit(cmd ? 1 : 0);
+  }
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
+}

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# dsh bundle patch: mounts dshloader into a profile's cordis layer stack.
+# Position in the `insert` list does NOT affect whether service aliases /
+# module redirects take effect — cordis is reactive dependency injection,
+# so downstream plugins declaring `inject: [...]` stay PENDING until the
+# alias is provided, regardless of file order. See docs/design.md §1.2/§6.2.
+- insert:
+    - id: dsh-loader
+      name: '@dsh-plugin/dsh-loader'

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@dsh-plugin/dsh-loader",
+  "version": "1.0.0",
+  "description": "Runtime compatibility shim for dsh (DeepSeek Harness) cordis bundle plugins: decouples third-party plugins from real dsh internal service names, module paths, and RPC details via a version-aware adapter registry.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./lib/client.js",
+    "./registry": "./src/registry.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json",
+    "./ui-primitives": "./src/stable/ui-primitives.js",
+    "./ui-settings": "./src/stable/ui-settings.js",
+    "./ui-slots": "./src/stable/ui-slots.js",
+    "./web-react": "./src/stable/web-react.js",
+    "./schema-form": "./src/stable/schema-form.js",
+    "./runtime": "./src/stable/runtime.js",
+    "./tools": "./src/stable/tools.js",
+    "./llm": "./src/stable/llm.js",
+    "./agent": "./src/stable/agent.js",
+    "./settings": "./src/stable/settings.js"
+  },
+  "bin": {
+    "dshloader": "./bin/dshloader.mjs"
+  },
+  "files": [
+    "src",
+    "bin",
+    "lib/client.js",
+    "lib/client.js.map",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "scripts": {
+    "build:client": "tsdown --config tsdown.client.config.mjs",
+    "test": "node --test \"tests/**/*.test.mjs\"",
+    "test:l1": "node --test \"tests/*.test.mjs\"",
+    "test:l2": "node --test \"tests/module/*.test.mjs\"",
+    "test:l3": "node --test \"tests/integration/*.test.mjs\"",
+    "setup": "node bin/dshloader.mjs setup"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "semver": "^7.8.5"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true
+    }
+  },
+  "license": "BSD-3-Clause"
+}