@morehao/dsh-plugin-kit 0.1.0 → 0.2.1

package/README.md

@@ -14,16 +14,34 @@ DeepSeek Harness（dsh）插件共用的工具包。当前提供三件事：
 npm install @morehao/dsh-plugin-kit
 ```
 
+## 能力边界：哪些复用宿主、哪些必须自建
+
+自更新这件事在宿主（`@deepseek-ai/dsh-plugin-manager`）里已有大半能力，本包的原则是**能复用就复用**：
+
+| 能力 | 来源 | 说明 |
+|---|---|---|
+| 安装 / 卸载 | **复用宿主** | apply 全程走 `pluginManager.installBundle` / `removeBundle`；`already-installed → remove → install` 就是宿主既定的更新流程，`applied/restart-required/overridden` 也直接来自宿主结果。 |
+| registry 列表（镜像 / 私源 / token） | **复用宿主** | `resolved` 由宿主跑 `pnpm config get registry` 解析，本包不自己读 `.npmrc`。 |
+| registry **排序 / 回退** | **复用宿主（注入）** | 优先用调用方注入的宿主原生 `registryPlan`（`@deepseek-ai/dsh-plugin-manager/registry`），与 `installBundle`/`inspect` 内部同一份源码、含私有源「只问它自己、不回退公有源」语义。本包不直接 import（保持零 `@deepseek-ai/*` 运行时依赖），由插件侧注入。未注入时用内置 `resolveRegistryPlan` 兜底（`resolved → registry → fallback` 宽松顺序，fail-open）。 |
+| 查最新版 | **必须自建** | 宿主 `inspect()` 对「已装包」直接返回 `already-installed`，不会去问 registry；插件查的正是「我自己这个已装包」，必然被拦截。故只能走 `pnpm view`（`runPnpmView`，复用 profile 的包管理器）或 registry `/latest`。 |
+| 安装形态判定 | **必须自建** | 宿主未暴露「本包以什么 spec 声明」；本包读 `<profile.dir>/package.json` 识别 `link:/file:/workspace:` 以拒绝把开发链接覆盖成 npm 版。 |
+
+一句话：**装/卸、registry 取数与排序都复用宿主（排序原生能力通过注入复用）；查版本、判形态因宿主 API 缺口而自建；不注入原生 `registryPlan` 时才回落到内置兜底顺序。**
+
 ## 一键更新（host）
 
 ```ts
 import { createPluginUpdater } from '@morehao/dsh-plugin-kit/update';
+// 宿主原生 registry 排序（与 installBundle/inspect 同一份），由插件侧注入、本包不直接依赖
+import { registryPlan as hostRegistryPlan } from '@deepseek-ai/dsh-plugin-manager/registry';
 
 const updater = createPluginUpdater({
   meta: { name: pkg.name, version: pkg.version, ...(pkg.repository ? { repository: repoUrl(pkg.repository) } : {}) },
   getPluginManager: () => ctx.get('pluginManager'),
   getProfile: () => ctx.get('profileContext'),
   getProfileName: () => ctx.get('profileContext')?.name,
+  // 可选但推荐：注入宿主原生 registryPlan，使「查版本的 registry 顺序」与宿主安装完全一致
+  registryPlan: hostRegistryPlan,
   // 可选：用 profile 的包管理器查版本（继承 .npmrc 的镜像 / 私源 / token）
   runPnpmView: async (spec) => {
     const profile = ctx.get('profileContext');
@@ -106,5 +124,5 @@ sendJson(response, 200, { ok: true });
 
 ```bash
 npm install
-npm run check   # typecheck + build + 24 条离线测试（假 fetch / 假 pluginManager，不联网、不真装）
+npm run check   # typecheck + build + 26 条离线测试（假 fetch / 假 pluginManager，不联网、不真装）
 ```

package/dist/index.d.ts

@@ -1,43 +1,15 @@
-export { D as DetectDeps, I as InstallKind, a as InstallKindResult, P as ProfileLike, c as classifyInstallSpec, d as detectInstallKind, n as normalizeProfile, r as readDeclaredSpec } from './profile-C-eyP5F6.js';
+export { D as DEFAULT_CACHE_TTL_MS, a as DEFAULT_TIMEOUT_MS, b as DetectDeps, H as HostRegistryPlan, I as InstallKind, c as InstallKindResult, O as OFFICIAL_REGISTRY, P as ProfileLike, R as RegistriesLike, d as classifyInstallSpec, e as detectInstallKind, f as encodePackageName, m as manualCommand, n as normalizeProfile, g as normalizeRegistry, r as readDeclaredSpec, h as registryPlan, i as resolveRegistryPlan } from './profile-RKpxKDlK.js';
 
-/**
- * semver 解析与比较（只做插件更新需要的部分）。
- *
- * 不引 semver 依赖：更新判定宁可不升级也不要误升，所以非法版本一律返回 undefined，
- * 由调用方按「不更新」处理。支持 `v1.2.3` / `1.2.3-beta.1` / `1.2.3+build`。
- */
+/** 保留旧接口形状：核心三段 + 预发布标识（字符串数组）。 */
 interface Semver {
     core: [number, number, number];
     prerelease: string[];
 }
+/** 解析成 `Semver`；非法（含空串 / `1.2` / `1.2.3.4` / 非版本串）返回 undefined。 */
 declare function parseSemver(value: unknown): Semver | undefined;
 /** `candidate` 是否严格新于 `current`；任一方不是合法 semver 都返回 false。 */
 declare function isNewerVersion(current: unknown, candidate: unknown): boolean;
 /** 比较两个版本：负数 / 0 / 正数；任一方非法返回 undefined。 */
 declare function compareVersions(left: unknown, right: unknown): number | undefined;
 
-/**
- * npm registry 约定：把包名拼成 `/latest` 端点，并按宿主给出的 registry 优先级发请求。
- *
- * 宿主 `pluginManager.registries()` 会把 profile 的镜像 / 私源 / token 计划交出来；
- * 拿不到就退回官方 registry。这里只做纯函数（不含网络），网络在 `latest.ts`。
- */
-declare const OFFICIAL_REGISTRY = "https://registry.npmjs.org/";
-declare const DEFAULT_TIMEOUT_MS = 8000;
-declare const DEFAULT_CACHE_TTL_MS: number;
-/** 宿主 registry 计划的形状（字段都当可选处理，宿主版本差异不该让我们崩）。 */
-interface RegistriesLike {
-    resolved?: unknown;
-    registry?: unknown;
-    fallbackRegistries?: unknown;
-}
-/** npm 包名转 registry 路径：`@scope/name` → `@scope%2Fname`（保留 @，斜杠编码）。 */
-declare function encodePackageName(name: string): string;
-/** registry 归一成 `https://host/` 形式；非法（非 http(s) / 解析失败）返回 null。 */
-declare function normalizeRegistry(value: unknown): string | null;
-/** 由宿主的 registries() 结果拼出要问的 registry 顺序：resolved → registry → fallback，去重。 */
-declare function registryPlan(registries: unknown): string[];
-/** 手动更新命令：`dsh plugin --profile <name> add <pkg>@latest`。 */
-declare function manualCommand(packageName: string, profileName?: string | null): string;
-
-export { DEFAULT_CACHE_TTL_MS, DEFAULT_TIMEOUT_MS, OFFICIAL_REGISTRY, type RegistriesLike, type Semver, compareVersions, encodePackageName, isNewerVersion, manualCommand, normalizeRegistry, parseSemver, registryPlan };
+export { type Semver, compareVersions, isNewerVersion, parseSemver };

package/dist/index.js

@@ -1,59 +1,29 @@
 // src/semver.ts
-var SEMVER = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+import semver from "semver";
 function parseSemver(value) {
   const text = String(value ?? "").trim();
-  const match = SEMVER.exec(text);
-  if (match === null) return void 0;
-  const major = Number(match[1]);
-  const minor = Number(match[2]);
-  const patch = Number(match[3]);
-  if (!Number.isSafeInteger(major) || !Number.isSafeInteger(minor) || !Number.isSafeInteger(patch)) return void 0;
-  return { core: [major, minor, patch], prerelease: match[4] === void 0 ? [] : match[4].split(".") };
-}
-function comparePrerelease(left, right) {
-  if (left.length === 0 || right.length === 0) {
-    return left.length === right.length ? 0 : left.length === 0 ? 1 : -1;
-  }
-  const length = Math.max(left.length, right.length);
-  for (let index = 0; index < length; index += 1) {
-    const a = left[index];
-    const b = right[index];
-    if (a === void 0 || b === void 0) return a === b ? 0 : a === void 0 ? -1 : 1;
-    if (a === b) continue;
-    const aNumeric = /^\d+$/.test(a);
-    const bNumeric = /^\d+$/.test(b);
-    if (aNumeric && bNumeric) {
-      const an = BigInt(a);
-      const bn = BigInt(b);
-      if (an !== bn) return an > bn ? 1 : -1;
-      continue;
-    }
-    if (aNumeric !== bNumeric) return aNumeric ? -1 : 1;
-    return a > b ? 1 : -1;
-  }
-  return 0;
+  if (text === "") return void 0;
+  const parsed = semver.parse(text);
+  if (parsed === null) return void 0;
+  return {
+    core: [parsed.major, parsed.minor, parsed.patch],
+    // semver 会把纯数字预发布段解析为 number，这里统一转回字符串以保持旧契约。
+    prerelease: parsed.prerelease.map((part) => String(part))
+  };
 }
 function isNewerVersion(current, candidate) {
   const a = parseSemver(current);
   const b = parseSemver(candidate);
   if (a === void 0 || b === void 0) return false;
-  for (let index = 0; index < 3; index += 1) {
-    const left = a.core[index] ?? 0;
-    const right = b.core[index] ?? 0;
-    if (right !== left) return right > left;
-  }
-  return comparePrerelease(b.prerelease, a.prerelease) > 0;
+  const left = String(current).trim();
+  const right = String(candidate).trim();
+  return semver.gt(right, left);
 }
 function compareVersions(left, right) {
   const a = parseSemver(left);
   const b = parseSemver(right);
   if (a === void 0 || b === void 0) return void 0;
-  for (let index = 0; index < 3; index += 1) {
-    const an = a.core[index] ?? 0;
-    const bn = b.core[index] ?? 0;
-    if (an !== bn) return an > bn ? 1 : -1;
-  }
-  return comparePrerelease(a.prerelease, b.prerelease);
+  return semver.compare(String(left).trim(), String(right).trim());
 }
 
 // src/registry.ts
@@ -96,6 +66,36 @@ function registryPlan(registries) {
   if (ordered.length === 0) ordered.push(OFFICIAL_REGISTRY);
   return ordered;
 }
+function planFromHost(hostPlan, registries) {
+  if (registries === null || typeof registries !== "object") return null;
+  const ordered = [];
+  const push = (value) => {
+    const normalized = normalizeRegistry(value);
+    if (normalized !== null && !ordered.includes(normalized)) ordered.push(normalized);
+  };
+  let result;
+  try {
+    result = hostPlan(void 0, registries);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(result)) return null;
+  for (const entry of result) {
+    if (entry === null) {
+      push(registries.resolved);
+      continue;
+    }
+    push(entry);
+  }
+  return ordered.length === 0 ? null : ordered;
+}
+function resolveRegistryPlan(registries, hostPlan) {
+  if (typeof hostPlan === "function") {
+    const fromHost = planFromHost(hostPlan, registries);
+    if (fromHost !== null) return fromHost;
+  }
+  return registryPlan(registries);
+}
 function manualCommand(packageName, profileName) {
   const spec = `${packageName}@latest`;
   return typeof profileName === "string" && profileName !== "" ? `dsh plugin --profile ${profileName} add ${spec}` : `dsh plugin add ${spec}`;
@@ -175,5 +175,6 @@ export {
   normalizeRegistry,
   parseSemver,
   readDeclaredSpec,
-  registryPlan
+  registryPlan,
+  resolveRegistryPlan
 };

package/dist/profile-RKpxKDlK.d.ts

@@ -0,0 +1,117 @@
+/**
+ * npm registry 约定：把包名拼成 `/latest` 端点，并按宿主给出的 registry 优先级发请求。
+ *
+ * **registry 列表与排序都优先复用宿主原生能力**（`@deepseek-ai/dsh-plugin-manager/registry` 的
+ * `registryPlan(requested, configured)`，与 `installBundle` / `inspect` 内部用的是同一份源码）。
+ * 但本包坚持**零 `@deepseek-ai/*` 运行时依赖**（见 package.json / update.ts），所以不直接 import，
+ * 而是让调用方把原生函数**注入**进来（见 `HostRegistryPlan` / `LatestDeps.registryPlan`）：
+ *
+ *   - 注入了 → 用宿主原生排序（含私有源「只问它自己、不回退公有源」的语义，与安装完全一致）；
+ *   - 没注入 / 调用抛错 / 结果不可用 → 退回本模块内置的 `registryPlan` 兜底（见下）。
+ *
+ * 为什么查最新版不复用 `pluginManager.inspect()`：`inspect(spec)` 在 registry 分支里先判
+ * 「该包是否已在 profile 依赖中」，命中即返回 `already-installed`，**根本不会去问 registry**。
+ * 而插件自更新要查的恰恰是「我自己这个已装包有没有新版」，必然命中该拦截。所以查 latest
+ * 只能另走 `pnpm view`（见 `latest.ts` 的 `runPnpmView`）或 registry `/latest`，`inspect` 不可替代。
+ */
+declare const OFFICIAL_REGISTRY = "https://registry.npmjs.org/";
+declare const DEFAULT_TIMEOUT_MS = 8000;
+declare const DEFAULT_CACHE_TTL_MS: number;
+/**
+ * 宿主 `pluginManager.registries()` 的返回形状（对齐 @deepseek-ai/dsh-plugin-manager）。
+ *
+ * 设计取舍：字段都按可选 + unknown 收。宿主版本差异或字段改名时，内置兜底 `registryPlan` 用
+ * `normalizeRegistry` 逐个校验，非法项直接跳过并最终退到官方源，**绝不因形状不符而抛错**
+ * （fail-open：宁可退化到官方源，也不让自更新检查因宿主形状变化而崩）。
+ */
+interface RegistriesLike {
+    /** pnpm 在 profile 内解析出的实际 registry（继承 .npmrc），非空时最优先。 */
+    resolved?: unknown;
+    /** 配置里显式的 registry（可能为 null，表示「pnpm 自身配置的源」）。 */
+    registry?: unknown;
+    /** 回退源；宿主默认含 npmmirror。 */
+    fallbackRegistries?: unknown;
+}
+/**
+ * 宿主原生 `registryPlan` 的注入形状，对齐 `@deepseek-ai/dsh-plugin-manager/registry`。
+ *
+ * 调用方（各插件）自己 `import { registryPlan } from '@deepseek-ai/dsh-plugin-manager/registry'`
+ * 后注入本包，即可让「查最新版的 registry 顺序」与宿主安装使用**完全一致**的排序与私有源语义。
+ *
+ * 入参/返回：
+ * - `requested`：首位要问的 registry；`undefined` 表示交给宿主按 configured 首项决定。
+ * - `configured`：`registries()` 的返回值（resolved / registry / fallbackRegistries）。
+ * - 返回：依次要问的 registry 数组，**元素可能为 `null`**（表示 pnpm 自身配置的源）；宿主实现
+ *   在入参非法时会**抛错**，所以本包调用处已包 try/catch 兜底。
+ */
+type HostRegistryPlan = (requested: string | undefined, configured: RegistriesLike) => Array<string | null>;
+/** npm 包名转 registry 路径：`@scope/name` → `@scope%2Fname`（保留 @，斜杠编码）。 */
+declare function encodePackageName(name: string): string;
+/** registry 归一成 `https://host/` 形式；非法（非 http(s) / 解析失败）返回 null。 */
+declare function normalizeRegistry(value: unknown): string | null;
+/**
+ * 内置兜底：把 `registries()` 的结果收敛成「查 latest 时要依次试的 registry 顺序」：
+ * `resolved → registry → fallback`，去重；全非法/缺失时退到官方 registry，**绝不抛**。
+ *
+ * 这是**注入不到宿主原生 `registryPlan` 时的简化兜底**，不是宿主安装计划的等价物：它不区分
+ * 公有/私有源。因此若 `resolved` 是私有源而其上查不到本包（镜像未同步），兜底会继续去问
+ * fallback / 官方源拿 latest；而宿主真正安装时可能只问私有源并失败。差异只影响「能否查到版本」，
+ * 不影响实际安装走哪条路。想与宿主机安装完全对齐，请注入原生 `registryPlan`（见 `HostRegistryPlan`）。
+ */
+declare function registryPlan(registries: unknown): string[];
+/**
+ * 解析「查 latest 时要依次试的 registry 顺序」：
+ * **优先用宿主原生 `registryPlan`**（注入且成功时，排序/私有源语义与宿主机安装完全一致），
+ * 否则退回内置 `registryPlan` 兜底（fail-open，保证查询永远有一条可走的路）。
+ *
+ * @param registries 宿主 `registries()` 的返回值（任意形状，内部按 unknown 校验）。
+ * @param hostPlan  可选的宿主原生 `registryPlan`（由调用方从 dsh-plugin-manager/registry 注入）。
+ */
+declare function resolveRegistryPlan(registries: unknown, hostPlan?: HostRegistryPlan): string[];
+/** 手动更新命令：`dsh plugin --profile <name> add <pkg>@latest`。 */
+declare function manualCommand(packageName: string, profileName?: string | null): string;
+
+/**
+ * profile 读取：判断本插件是以什么形态装进当前 profile。
+ *
+ * 一键更新最危险的场景是「开发用的本地链接」：profile 里写的是 `link:/path/to/repo`，
+ * 一旦用 registry 重装，本地的 link 会被换成 npm 版，开发流就被悄悄改掉了。所以
+ * 更新前先读 `<profile.dir>/package.json` 的依赖声明，link: / file: / workspace: 一律
+ * 关闭一键更新，只给手动命令。
+ */
+type InstallKind = 'registry' | 'link' | 'file' | 'workspace' | 'unknown';
+interface ProfileLike {
+    name?: string;
+    dir?: string;
+    home?: string;
+    packageManager?: {
+        command?: string;
+        args?: string[];
+    };
+}
+interface InstallKindResult {
+    kind: InstallKind;
+    /** profile package.json 里声明的原始 spec（读不到就是 undefined）。 */
+    spec?: string;
+    /** 说明来源，便于日志与界面提示。 */
+    source?: string;
+}
+/** 把宿主 `profileContext`（任意形状）收敛成只含我们关心的字段；拿不到返回 null。 */
+declare function normalizeProfile(value: unknown): ProfileLike | null;
+/** `dependencies` 里声明的 spec 决定安装形态；`npm:` 别名仍按 registry 处理。 */
+declare function classifyInstallSpec(spec: unknown): InstallKind;
+interface DetectDeps {
+    profile: ProfileLike | null;
+    packageName: string;
+    /** 测试注入；默认读真实文件。 */
+    readFile?: (path: string) => Promise<string>;
+    readJson?: (path: string) => Promise<unknown>;
+}
+/** 读 profile 的 package.json，返回本插件声明的 spec（找不到返回 undefined）。 */
+declare function readDeclaredSpec(deps: DetectDeps): Promise<{
+    spec?: string;
+    source?: string;
+}>;
+declare function detectInstallKind(deps: DetectDeps): Promise<InstallKindResult>;
+
+export { DEFAULT_CACHE_TTL_MS as D, type HostRegistryPlan as H, type InstallKind as I, OFFICIAL_REGISTRY as O, type ProfileLike as P, type RegistriesLike as R, DEFAULT_TIMEOUT_MS as a, type DetectDeps as b, type InstallKindResult as c, classifyInstallSpec as d, detectInstallKind as e, encodePackageName as f, normalizeRegistry as g, registryPlan as h, resolveRegistryPlan as i, manualCommand as m, normalizeProfile as n, readDeclaredSpec as r };

package/dist/update-client.d.ts

@@ -1,5 +1,5 @@
 import { UpdateView, ApplyResult } from './update.js';
-import './profile-C-eyP5F6.js';
+import './profile-RKpxKDlK.js';
 
 /**
  * 客户端侧 headless 控制器（不依赖 React、不 import node 内置模块）。

package/dist/update.d.ts

@@ -1,5 +1,25 @@
-import { I as InstallKind } from './profile-C-eyP5F6.js';
-export { P as ProfileLike } from './profile-C-eyP5F6.js';
+import { I as InstallKind, H as HostRegistryPlan } from './profile-RKpxKDlK.js';
+export { P as ProfileLike } from './profile-RKpxKDlK.js';
+
+/**
+ * 查 npm 上某个包的最新版本。
+ *
+ * 顺序（可配置）：
+ *   1. 调用方注入的 `runPnpmView`（让插件用自己 profile 的包管理器查，继承 .npmrc 的
+ *      镜像 / 私源 / token；宿主内裸 fetch 读不到这些配置）。**这是复用宿主包管理器**：
+ *      查询在 profile 目录、profile 的 packageManager 环境下执行，与宿主安装同源。
+ *   2. 宿主 `pluginManager.registries()` 给出的 registry 列表，依次问 `<base><pkg>/latest`；
+ *      排序**优先用调用方注入的宿主原生 `registryPlan`**（与安装完全一致），未注入则内置兜底
+ *      （见 `registry.ts` 的 `resolveRegistryPlan`）；
+ *   3. 都没有就用官方 registry。
+ *
+ * **为什么不用宿主的 `pluginManager.inspect()` 查最新版**：`inspect()` 在 registry 分支会先判
+ * 「该包是否已在 profile 依赖中」，命中即返回 `already-installed`，不会真正去问 registry。
+ * 插件自更新要查的正是「我自己这个已装包」，必然命中该拦截，所以此处只能走 `pnpm view` / `/latest`。
+ *
+ * 全部失败返回 null（不抛）：调用方用它标记 `checkFailed`，界面照常可用。注意「查不到」≠「宿主缺失」，
+ * 而是网络 / registry / 包管理器任一环节不可用时的运行时降级。
+ */
 
 type Logger = (event: string, detail?: Record<string, unknown>) => void;
 interface PluginMeta {
@@ -13,7 +33,11 @@ interface PluginMeta {
  *
  * 设计约束（三个 DSH 插件共用这份逻辑）：
  * - **零 `@deepseek-ai/*` 运行时依赖**：pluginManager / profileContext 都由调用方用
- *   `ctx.get(...)` 惰性取，拿不到就退化成「只检查 + 手动命令」。
+ *   `ctx.get(...)` 惰性取。本包定位就是 DSH 插件，宿主必然在；但 `installBundle` 是
+ *   可选/远程能力，取不到只是「当前部署未暴露该能力」，退化成「只检查 + 手动命令」。
+ * - **复用优先**：registry 顺序优先用调用方注入的宿主原生 `registryPlan`（与宿主安装完全一致，
+ *   含私有源语义），未注入则内置兜底（见 `registry.ts` 的 `resolveRegistryPlan`）；查最新版走
+ *   `pnpm view` / registry `/latest`（`inspect()` 对已装包返回 already-installed，不可替代）。
  * - **不自作主张升级**：只有 registry 明确给出合法且严格更新的版本才允许安装；
  *   `link:` / `file:` / `workspace:` 安装一律禁止一键更新（会把开发链接换成 npm 版）。
  * - **装不上要能回退**：宿主 `installBundle` 对已装包会返回 `already-installed`，按官方
@@ -63,6 +87,8 @@ interface UpdaterDeps {
     getProfileName?: () => string | null;
     fetchImpl?: typeof fetch;
     runPnpmView?: (spec: string) => Promise<string | null>;
+    /** 可选：注入宿主原生 `registryPlan`（dsh-plugin-manager/registry），让查版本的 registry 顺序与安装一致。 */
+    registryPlan?: HostRegistryPlan;
     readFile?: (path: string) => Promise<string>;
     logger?: Logger;
     now?: () => number;
@@ -84,4 +110,4 @@ interface Updater {
 }
 declare function createPluginUpdater(deps: UpdaterDeps): Updater;
 
-export { type ApplyResult, InstallKind, type Logger, type PluginManagerLike, type PluginMeta, PluginUpdateError, type UpdateErrorCode, type UpdateView, type Updater, type UpdaterDeps, createPluginUpdater };
+export { type ApplyResult, HostRegistryPlan, InstallKind, type Logger, type PluginManagerLike, type PluginMeta, PluginUpdateError, type UpdateErrorCode, type UpdateView, type Updater, type UpdaterDeps, createPluginUpdater };

package/dist/update.js

@@ -38,56 +38,61 @@ function registryPlan(registries) {
   if (ordered.length === 0) ordered.push(OFFICIAL_REGISTRY);
   return ordered;
 }
+function planFromHost(hostPlan, registries) {
+  if (registries === null || typeof registries !== "object") return null;
+  const ordered = [];
+  const push = (value) => {
+    const normalized = normalizeRegistry(value);
+    if (normalized !== null && !ordered.includes(normalized)) ordered.push(normalized);
+  };
+  let result;
+  try {
+    result = hostPlan(void 0, registries);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(result)) return null;
+  for (const entry of result) {
+    if (entry === null) {
+      push(registries.resolved);
+      continue;
+    }
+    push(entry);
+  }
+  return ordered.length === 0 ? null : ordered;
+}
+function resolveRegistryPlan(registries, hostPlan) {
+  if (typeof hostPlan === "function") {
+    const fromHost = planFromHost(hostPlan, registries);
+    if (fromHost !== null) return fromHost;
+  }
+  return registryPlan(registries);
+}
 function manualCommand(packageName, profileName) {
   const spec = `${packageName}@latest`;
   return typeof profileName === "string" && profileName !== "" ? `dsh plugin --profile ${profileName} add ${spec}` : `dsh plugin add ${spec}`;
 }
 
 // src/semver.ts
-var SEMVER = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+import semver from "semver";
 function parseSemver(value) {
   const text = String(value ?? "").trim();
-  const match = SEMVER.exec(text);
-  if (match === null) return void 0;
-  const major = Number(match[1]);
-  const minor = Number(match[2]);
-  const patch = Number(match[3]);
-  if (!Number.isSafeInteger(major) || !Number.isSafeInteger(minor) || !Number.isSafeInteger(patch)) return void 0;
-  return { core: [major, minor, patch], prerelease: match[4] === void 0 ? [] : match[4].split(".") };
-}
-function comparePrerelease(left, right) {
-  if (left.length === 0 || right.length === 0) {
-    return left.length === right.length ? 0 : left.length === 0 ? 1 : -1;
-  }
-  const length = Math.max(left.length, right.length);
-  for (let index = 0; index < length; index += 1) {
-    const a = left[index];
-    const b = right[index];
-    if (a === void 0 || b === void 0) return a === b ? 0 : a === void 0 ? -1 : 1;
-    if (a === b) continue;
-    const aNumeric = /^\d+$/.test(a);
-    const bNumeric = /^\d+$/.test(b);
-    if (aNumeric && bNumeric) {
-      const an = BigInt(a);
-      const bn = BigInt(b);
-      if (an !== bn) return an > bn ? 1 : -1;
-      continue;
-    }
-    if (aNumeric !== bNumeric) return aNumeric ? -1 : 1;
-    return a > b ? 1 : -1;
-  }
-  return 0;
+  if (text === "") return void 0;
+  const parsed = semver.parse(text);
+  if (parsed === null) return void 0;
+  return {
+    core: [parsed.major, parsed.minor, parsed.patch],
+    // semver 会把纯数字预发布段解析为 number，这里统一转回字符串以保持旧契约。
+    prerelease: parsed.prerelease.map((part) => String(part))
+  };
 }
 function isNewerVersion(current, candidate) {
   const a = parseSemver(current);
   const b = parseSemver(candidate);
   if (a === void 0 || b === void 0) return false;
-  for (let index = 0; index < 3; index += 1) {
-    const left = a.core[index] ?? 0;
-    const right = b.core[index] ?? 0;
-    if (right !== left) return right > left;
-  }
-  return comparePrerelease(b.prerelease, a.prerelease) > 0;
+  const left = String(current).trim();
+  const right = String(candidate).trim();
+  return semver.gt(right, left);
 }
 
 // src/latest.ts
@@ -131,7 +136,7 @@ function createLatestResolver(deps) {
     }
   }
   async function viaRegistries() {
-    const plan = registryPlan(await readRegistries());
+    const plan = resolveRegistryPlan(await readRegistries(), deps.registryPlan);
     for (const base of plan) {
       try {
         const response = await fetchImpl(`${base}${encodePackageName(deps.meta.name)}/latest`, {
@@ -273,6 +278,7 @@ function createPluginUpdater(deps) {
     ...deps.getPluginManager === void 0 ? {} : { getPluginManager: deps.getPluginManager },
     ...deps.fetchImpl === void 0 ? {} : { fetchImpl: deps.fetchImpl },
     ...deps.runPnpmView === void 0 ? {} : { runPnpmView: deps.runPnpmView },
+    ...deps.registryPlan === void 0 ? {} : { registryPlan: deps.registryPlan },
     ...deps.now === void 0 ? {} : { now: deps.now },
     ...deps.cacheTtlMs === void 0 ? {} : { cacheTtlMs: deps.cacheTtlMs },
     ...deps.timeoutMs === void 0 ? {} : { timeoutMs: deps.timeoutMs },
@@ -376,7 +382,7 @@ function createPluginUpdater(deps) {
     }
     const service = manager();
     if (service === null || typeof service.installBundle !== "function") {
-      throw new PluginUpdateError("NO_MANAGER", "\u5F53\u524D\u73AF\u5883\u4E0D\u652F\u6301\u4E00\u952E\u66F4\u65B0\uFF08\u7F3A\u5C11 pluginManager.installBundle\uFF09", {
+      throw new PluginUpdateError("NO_MANAGER", "\u5F53\u524D profile \u672A\u63D0\u4F9B\u4E00\u952E\u5B89\u88C5\u80FD\u529B\uFF08pluginManager.installBundle \u4E0D\u53EF\u7528\uFF09\uFF0C\u8BF7\u624B\u52A8\u66F4\u65B0", {
         manualCommand: view.manualCommand
       });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morehao/dsh-plugin-kit",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "DeepSeek Harness 插件共用工具包：插件自更新引擎（查 npm 最新版 + 经宿主 pluginManager 重装）、headless 客户端控制器与 HTTP 小工具。零 @deepseek-ai 运行时依赖，宿主能力全部注入。",
   "type": "module",
   "main": "dist/index.js",
@@ -49,6 +49,7 @@
   },
   "devDependencies": {
     "@types/node": "22.20.5",
+    "@types/semver": "^7.8.0",
     "tsup": "8.5.1",
     "typescript": "5.9.3"
   },
@@ -65,5 +66,8 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "semver": "^7.8.5"
   }
 }

package/dist/profile-C-eyP5F6.d.ts

@@ -1,44 +0,0 @@
-/**
- * profile 读取：判断本插件是以什么形态装进当前 profile。
- *
- * 一键更新最危险的场景是「开发用的本地链接」：profile 里写的是 `link:/path/to/repo`，
- * 一旦用 registry 重装，本地的 link 会被换成 npm 版，开发流就被悄悄改掉了。所以
- * 更新前先读 `<profile.dir>/package.json` 的依赖声明，link: / file: / workspace: 一律
- * 关闭一键更新，只给手动命令。
- */
-type InstallKind = 'registry' | 'link' | 'file' | 'workspace' | 'unknown';
-interface ProfileLike {
-    name?: string;
-    dir?: string;
-    home?: string;
-    packageManager?: {
-        command?: string;
-        args?: string[];
-    };
-}
-interface InstallKindResult {
-    kind: InstallKind;
-    /** profile package.json 里声明的原始 spec（读不到就是 undefined）。 */
-    spec?: string;
-    /** 说明来源，便于日志与界面提示。 */
-    source?: string;
-}
-/** 把宿主 `profileContext`（任意形状）收敛成只含我们关心的字段；拿不到返回 null。 */
-declare function normalizeProfile(value: unknown): ProfileLike | null;
-/** `dependencies` 里声明的 spec 决定安装形态；`npm:` 别名仍按 registry 处理。 */
-declare function classifyInstallSpec(spec: unknown): InstallKind;
-interface DetectDeps {
-    profile: ProfileLike | null;
-    packageName: string;
-    /** 测试注入；默认读真实文件。 */
-    readFile?: (path: string) => Promise<string>;
-    readJson?: (path: string) => Promise<unknown>;
-}
-/** 读 profile 的 package.json，返回本插件声明的 spec（找不到返回 undefined）。 */
-declare function readDeclaredSpec(deps: DetectDeps): Promise<{
-    spec?: string;
-    source?: string;
-}>;
-declare function detectInstallKind(deps: DetectDeps): Promise<InstallKindResult>;
-
-export { type DetectDeps as D, type InstallKind as I, type ProfileLike as P, type InstallKindResult as a, classifyInstallSpec as c, detectInstallKind as d, normalizeProfile as n, readDeclaredSpec as r };