@qilin-agent/dsh-compat 0.0.0-stage → 3.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,34 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/util/dsh-compat/README.md
+/:
+  en: 31f4d375f2c45aef
+  zh: 9beef4241a4e4953
+/qilin-dsh-compat:
+  en: da01746b6aa01ff3
+  zh: d4f949eaed1392ea
+/qilin-dsh-compat/summary:
+  en: 38552b541bcab51a
+  zh: b18b352279f6adda
+/qilin-dsh-compat/table-of-contents:
+  en: 76368b6b1da79c80
+  zh: b4a2a0e132e8ddf8
+/qilin-dsh-compat/use-this-package:
+  en: d0ad8090a9dbf715
+  zh: 90dcbcf230062cab
+/qilin-dsh-compat/understand-the-implementation:
+  en: e9f1d745306596fd
+  zh: c547396e19b6eaa8
+/qilin-dsh-compat/model-experience:
+  en: 0c1978665c0886b0
+  zh: d0159681b5568bdb
+/qilin-dsh-compat/model-experience/kv-cache-effect:
+  en: 5df5e153f56aec41
+  zh: 7f70d29d8d80cb58
+/qilin-dsh-compat/known-limitations-and-deferred-work:
+  en: ff21fa030cc8c41b
+  zh: b4246c9cff73db62
+/qilin-dsh-compat/known-limitations-and-deferred-work/dev-note:
+  en: 6500ff89363ef9e9
+  zh: 2699e3038d5414cf

package/README.md

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+---
+description: "Runtime compatibility helpers that let QiLin load DSH-era plugin manifests and module names."
+kind: "package-library"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/dsh-compat
+
+English | [中文](README.zh.md)
+
+## Summary
+
+This package keeps the DSH plugin ecosystem usable in QiLin. It selects a bundle or client declaration from either the native `qilin` manifest key or the DSH-era `dsh` key, and canonicalizes renamed DSH module specifiers onto QiLin module-table entries.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Profile loading, the plugin manager's install gate and bundle inventory, and the client test runtime's roster use `bundlePatchOf` for `qilin.bundle.patch` and `dsh.bundle.patch`. The client module graph and browser loader use `clientDeclarationOf` and `dshCompatModuleId` so prebuilt DSH factories can keep their original `require()` names.
+
+The exact platform aliases are exported as `DSH_PLATFORM_MODULE_ALIASES`. Unknown third-party names pass through unchanged; the compatibility layer does not replace service implementations or provide Electron-only APIs.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+The manifest reader gives a QiLin declaration precedence when both keys exist. The module resolver applies explicit aliases first, then maps `@deepseek-ai/dsh-<name>` to `@qilin-agent/<name>`; `client-runtime` maps to QiLin’s `client-modules` package. The browser shell seeds static platform aliases, while dynamic graph edges and factory requests are canonicalized at their owning loaders.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as this utility only maps DSH-era manifest keys and module names; it changes no prompt, tool schema, session event, or token budget.
+
+#### KV Cache effect
+
+None; it adds nothing to a request and subscribes to no cached prefix.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Engine-specific DSH plugins still need per-plugin validation** — plugins that depend on engine-specific services, resource URL schemes, or Electron bridges are out of scope. This package handles manifest and module identity compatibility only; it does not emulate API drift between DSH and QiLin.
+
+<a id="dev-note"></a>
+### Dev Note
+
+The alias table mirrors the DSH-to-QiLin package renames used by the vendored coding-sidebar channel. Add a mapping only when a real DSH package or bundle requires it, and cover both graph ordering and browser `require()` behavior.

package/README.zh.md

@@ -0,0 +1,58 @@
+---
+description: "让 QiLin 加载 DSH 时代插件 manifest 与模块名称的运行时兼容工具。"
+kind: "package-library"
+---
+
+# @qilin-agent/dsh-compat
+
+[English](README.md) | 中文
+
+## 概述
+
+本包保持 DSH 插件生态在 QiLin 中可用。它会从原生的 `qilin` manifest 键或 DSH 时代的 `dsh` 键读取 bundle/client 声明，并把已重命名的 DSH 模块说明符归一化到 QiLin 的模块表条目。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [模型体验](#model-experience)
+- [已知限制与延后工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+Profile 加载、插件管理器的安装门与 bundle 清单、以及客户端测试运行时的 roster 通过 `bundlePatchOf` 同时读取 `qilin.bundle.patch` 与 `dsh.bundle.patch`。客户端模块图和浏览器加载器通过 `clientDeclarationOf` 与 `dshCompatModuleId` 处理预构建 DSH 工厂，使其可以保留原有的 `require()` 名称。
+
+精确的平台别名由 `DSH_PLATFORM_MODULE_ALIASES` 导出。未知的第三方名称保持不变；兼容层不会替换服务实现，也不会提供 Electron 专属 API。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 实现说明
+
+当两个键同时存在时，manifest 读取器优先使用 QiLin 声明。模块解析先应用精确别名，再把 `@deepseek-ai/dsh-<name>` 映射到 `@qilin-agent/<name>`；其中 `client-runtime` 映射到 QiLin 的 `client-modules`。浏览器 shell 提供静态平台别名，动态图边与工厂请求在各自的加载器中归一化。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无，因为本工具只映射 DSH 时代的 manifest 键与模块名称；它不改变任何 prompt、工具 schema、Session 事件或 token 预算。
+
+#### KV Cache 影响
+
+无；它不为请求增加任何内容，也不订阅任何缓存前缀。
+
+## 已知限制与延后工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **依赖引擎细节的 DSH 插件仍需逐个验证** —— 依赖引擎专属服务、资源 URL scheme 或 Electron bridge 的插件不在范围内。本包只处理 manifest 与模块身份兼容，不模拟 DSH 与 QiLin 之间已经漂移的 API。
+
+<a id="dev-note"></a>
+### 开发备注
+
+别名表与 vendored coding-sidebar channel 使用的 DSH 到 QiLin 包名重写保持一致。只有在真实 DSH 包或 bundle 需要时增加映射，并同时覆盖图排序与浏览器 `require()` 行为。

package/lib/index.js

@@ -0,0 +1,108 @@
+//#region lib/types/aliases.js
+/**
+* DSH-era module-name aliases.
+*
+* QiLin renamed every harness package (`@deepseek-ai/cordis` → `@qilin-agent/kylin`,
+* `@deepseek-ai/dsh-client-ui-slots` → `@qilin-agent/client-ui-slots`, …), but the
+* DSH plugin ecosystem ships prebuilt bundles whose factories `require()` the
+* old names. The static platform aliases keep those `require` calls resolvable
+* against QiLin's module table, and {@link dshCompatModuleId} canonicalizes the
+* package-name edges (boot-graph `inject`/`external` lists) onto the renamed
+* rows. The mapping mirrors the mechanical rewrite table of the vendored
+* channel sync (`dsh-coding-sidebar` `scripts/sync-to-qilin.mjs` IMPORT_MAP) —
+* keep the two tables consistent by hand: this package is the runtime source.
+* @module @qilin-agent/dsh-compat/aliases
+*/
+/**
+* Exact aliases for the DSH-era platform (static) module names, including the
+* bare `cordis` spelling some bundles require. Keys are DSH-era specifiers;
+* values are QiLin platform module names (each also a static seed-table key).
+*/
+const DSH_PLATFORM_MODULE_ALIASES = {
+	"cordis": "@qilin-agent/kylin",
+	"@deepseek-ai/cordis": "@qilin-agent/kylin",
+	"@deepseek-ai/schemastery": "@qilin-agent/schemastery",
+	"@deepseek-ai/dsh-client-store": "@qilin-agent/client-store",
+	"@deepseek-ai/dsh-client-ui-slots": "@qilin-agent/client-ui-slots",
+	"@deepseek-ai/dsh-client-ui-primitives": "@qilin-agent/client-ui-primitives",
+	"@deepseek-ai/dsh-client-ui-dockkit": "@qilin-agent/client-ui-dockkit"
+};
+/** The scoped prefix every renamed DSH engine package shares. */
+const DSH_PACKAGE_PREFIX = "@deepseek-ai/dsh-";
+/** The QiLin scope the prefix rule maps package heads onto. */
+const QILIN_SCOPE = "@qilin-agent/";
+/**
+* Package heads whose QiLin name is not the mechanical `dsh-` strip: the
+* DSH client module system (`dsh-client-runtime`) is QiLin's
+* `@qilin-agent/client-modules`.
+*/
+const DSH_PACKAGE_RENAMES = { "client-runtime": "client-modules" };
+/**
+* Canonicalize one module specifier for QiLin's module graph: an exact
+* platform alias wins; a scoped `@deepseek-ai/dsh-<pkg>[/subpath]` name maps
+* onto `@qilin-agent/<pkg>[/subpath]` with the rename table applied to the package
+* head; every other specifier (including unrenamed `@deepseek-ai/*` names such
+* as `@qilin-agent/schemastery`, which QiLin keeps verbatim) passes through
+* unchanged.
+* @param specifier - the specifier a manifest edge or a bundle `require` named.
+* @returns the QiLin-canonical specifier for graph and seed-table lookups.
+*/
+function dshCompatModuleId(specifier) {
+	const exact = DSH_PLATFORM_MODULE_ALIASES[specifier];
+	if (exact !== void 0) return exact;
+	if (!specifier.startsWith(DSH_PACKAGE_PREFIX)) return specifier;
+	const [head = "", ...subpath] = specifier.slice(17).split("/");
+	return QILIN_SCOPE + [DSH_PACKAGE_RENAMES[head] ?? head, ...subpath].join("/");
+}
+//#endregion
+//#region lib/types/manifest.js
+/**
+* Manifest-key fallback readers for DSH-era plugin packages.
+*
+* A DSH plugin's `package.json` declares its Harness metadata under the `dsh`
+* key (`dsh.bundle.patch`, `dsh.client`); a QiLin-native package declares the
+* same shape under `qilin`. These readers pick the declaration a package
+* actually carries so the profile launcher and the client module system mount
+* either channel's packages unchanged. Each reader validates only its own
+* pick (string presence for the patch path); the owning consumer keeps its
+* full structural validation and error reporting.
+* @module @qilin-agent/dsh-compat/manifest
+*/
+/**
+* The relative patch-file path a bundle package declares, from `qilin.bundle.patch`
+* when the package carries the native key and from `dsh.bundle.patch` otherwise.
+* A present-but-non-string declaration falls through to the other channel and
+* finally to `undefined`, so the caller's fail-loud path reports it.
+* @param manifest - the parsed `package.json` value of the bundle package.
+* @returns the declared patch path, or `undefined` when neither key declares one.
+*/
+function bundlePatchOf(manifest) {
+	const channels = manifest;
+	if (typeof channels !== "object" || channels === null) return void 0;
+	const qilin = channels.qilin?.bundle?.patch;
+	if (typeof qilin === "string") return qilin;
+	const dsh = channels.dsh?.bundle?.patch;
+	if (typeof dsh === "string") return dsh;
+}
+/**
+* Pick a package's client declaration: `qilin.client` when present (the
+* native key wins for a package that carries both), else `dsh.client`.
+* @param manifest - the parsed `package.json` value of the package.
+* @returns the picked declaration, or `undefined` when neither key declares one.
+*/
+function clientDeclarationOf(manifest) {
+	const channels = manifest;
+	if (typeof channels !== "object" || channels === null) return void 0;
+	const qilin = channels.qilin?.client;
+	if (qilin !== void 0) return {
+		key: "qilin.client",
+		value: qilin
+	};
+	const dsh = channels.dsh?.client;
+	if (dsh !== void 0) return {
+		key: "dsh.client",
+		value: dsh
+	};
+}
+//#endregion
+export { DSH_PLATFORM_MODULE_ALIASES, bundlePatchOf, clientDeclarationOf, dshCompatModuleId };

package/lib/types/aliases.d.ts

@@ -0,0 +1,32 @@
+/**
+ * DSH-era module-name aliases.
+ *
+ * QiLin renamed every harness package (`@deepseek-ai/cordis` → `@qilin-agent/kylin`,
+ * `@deepseek-ai/dsh-client-ui-slots` → `@qilin-agent/client-ui-slots`, …), but the
+ * DSH plugin ecosystem ships prebuilt bundles whose factories `require()` the
+ * old names. The static platform aliases keep those `require` calls resolvable
+ * against QiLin's module table, and {@link dshCompatModuleId} canonicalizes the
+ * package-name edges (boot-graph `inject`/`external` lists) onto the renamed
+ * rows. The mapping mirrors the mechanical rewrite table of the vendored
+ * channel sync (`dsh-coding-sidebar` `scripts/sync-to-qilin.mjs` IMPORT_MAP) —
+ * keep the two tables consistent by hand: this package is the runtime source.
+ * @module @qilin-agent/dsh-compat/aliases
+ */
+/**
+ * Exact aliases for the DSH-era platform (static) module names, including the
+ * bare `cordis` spelling some bundles require. Keys are DSH-era specifiers;
+ * values are QiLin platform module names (each also a static seed-table key).
+ */
+export declare const DSH_PLATFORM_MODULE_ALIASES: Readonly<Record<string, string>>;
+/**
+ * Canonicalize one module specifier for QiLin's module graph: an exact
+ * platform alias wins; a scoped `@deepseek-ai/dsh-<pkg>[/subpath]` name maps
+ * onto `@qilin-agent/<pkg>[/subpath]` with the rename table applied to the package
+ * head; every other specifier (including unrenamed `@deepseek-ai/*` names such
+ * as `@qilin-agent/schemastery`, which QiLin keeps verbatim) passes through
+ * unchanged.
+ * @param specifier - the specifier a manifest edge or a bundle `require` named.
+ * @returns the QiLin-canonical specifier for graph and seed-table lookups.
+ */
+export declare function dshCompatModuleId(specifier: string): string;
+//# sourceMappingURL=aliases.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * DSH plugin ecosystem compatibility for QiLin: module-name aliases and
+ * manifest-key fallback readers. See {@link ./aliases.ts} and
+ * {@link ./manifest.ts}.
+ * @module @qilin-agent/dsh-compat
+ */
+export { DSH_PLATFORM_MODULE_ALIASES, dshCompatModuleId, } from './aliases.ts';
+export { bundlePatchOf, clientDeclarationOf, type ClientDeclaration, type ClientDeclarationKey, } from './manifest.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/manifest.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Manifest-key fallback readers for DSH-era plugin packages.
+ *
+ * A DSH plugin's `package.json` declares its Harness metadata under the `dsh`
+ * key (`dsh.bundle.patch`, `dsh.client`); a QiLin-native package declares the
+ * same shape under `qilin`. These readers pick the declaration a package
+ * actually carries so the profile launcher and the client module system mount
+ * either channel's packages unchanged. Each reader validates only its own
+ * pick (string presence for the patch path); the owning consumer keeps its
+ * full structural validation and error reporting.
+ * @module @qilin-agent/dsh-compat/manifest
+ */
+/**
+ * The relative patch-file path a bundle package declares, from `qilin.bundle.patch`
+ * when the package carries the native key and from `dsh.bundle.patch` otherwise.
+ * A present-but-non-string declaration falls through to the other channel and
+ * finally to `undefined`, so the caller's fail-loud path reports it.
+ * @param manifest - the parsed `package.json` value of the bundle package.
+ * @returns the declared patch path, or `undefined` when neither key declares one.
+ */
+export declare function bundlePatchOf(manifest: unknown): string | undefined;
+/** Which manifest key supplied a client declaration. */
+export type ClientDeclarationKey = 'qilin.client' | 'dsh.client';
+/** One picked client declaration: the key that supplied it and its raw value. */
+export interface ClientDeclaration {
+    /** The manifest key the declaration was read from; consumers use it in diagnostics. */
+    readonly key: ClientDeclarationKey;
+    /** The raw declaration value; the consumer's structural validation applies unchanged. */
+    readonly value: unknown;
+}
+/**
+ * Pick a package's client declaration: `qilin.client` when present (the
+ * native key wins for a package that carries both), else `dsh.client`.
+ * @param manifest - the parsed `package.json` value of the package.
+ * @returns the picked declaration, or `undefined` when neither key declares one.
+ */
+export declare function clientDeclarationOf(manifest: unknown): ClientDeclaration | undefined;
+//# sourceMappingURL=manifest.d.ts.map

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@qilin-agent/dsh-compat",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "DSH-era plugin ecosystem compatibility: module-name aliases and manifest-key fallback readers",
+  "version": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/util/dsh-compat"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  }
 }