@morehao/dsh-plugin-kit 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 morehao
+
+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.md

@@ -1,3 +1,128 @@
-# Temporary Holding Version
+# @morehao/dsh-plugin-kit
 
-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.
+DeepSeek Harness（dsh）插件共用的工具包。当前提供三件事：
+
+- **插件自更新引擎**（`./update`）：查 npm 最新版 → 判断能不能一键更新 → 经宿主 `pluginManager` 重装自己。
+- **headless 客户端控制器**（`./update/client`）：检查/更新的状态机与单飞，UI 由各插件自己渲染。
+- **HTTP 小工具**（`./http`）：自定义头鉴权、`no-store` JSON、有上限的 JSON body。
+
+设计约束：**零 `@deepseek-ai/*` 运行时依赖**，宿主能力（`pluginManager` / `profileContext`）全部由调用方注入；进程相关的策略（比如用哪个包管理器查版本）也由插件自己决定，本包不替你 spawn。
+
+## 安装
+
+```bash
+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');
+    const result = await execCapture(profile.packageManager?.command ?? 'pnpm', [...(profile.packageManager?.args ?? []), 'view', spec, 'version', '--json'], {
+      cwd: profile.dir,
+      env: sanitizedEnv(process.env),
+      timeoutMs: 8_000,
+    });
+    if (result.code !== 0) return null;
+    const value = JSON.parse(result.stdout.trim() || 'null');
+    return typeof (Array.isArray(value) ? value.at(-1) : value) === 'string' ? (Array.isArray(value) ? value.at(-1) : value) : null;
+  },
+  logger: (event, detail) => log(event, detail),
+});
+
+const view = await updater.check({ fresh: true });
+// { packageName, currentVersion, latestVersion, updateAvailable, checkFailed,
+//   canApply, installKind, installSpec?, manualCommand, applying, checkedAt }
+
+const result = await updater.apply(); // 需要先 check()；只接受刚查到的版本
+// { application: 'applied' | 'restart-required' | 'overridden', restartRequired, updatedVersion, installKind, steps }
+```
+
+`apply()` 的行为与边界：
+
+- 只安装 **registry 上刚查到的 latest**，不接受调用方随手给的 spec（防注入）。
+- `link:` / `file:` / `workspace:` 安装一律拒绝（`LINKED_INSTALL`），只给 `manualCommand`——避免把开发链接换成 npm 版。
+- `installBundle` 返回 `already-installed` 时走 `removeBundle → installBundle`；remove 之后装失败会尝试装回原版本，仍失败报 `ROLLBACK_FAILED`。
+- 单飞：同一实例同时只允许一次 `apply()`。
+- 没有 `pluginManager.installBundle` 时报 `NO_MANAGER`，界面应展示 `manualCommand`。
+
+错误码（`PluginUpdateError.code`）：`NO_MANAGER` `LINKED_INSTALL` `NOT_CHECKED` `NO_UPDATE` `INVALID_VERSION` `APPLY_IN_PROGRESS` `INSTALL_FAILED` `REMOVE_FAILED` `ROLLBACK_FAILED` `UNSUPPORTED_RESULT`。
+
+固定事件名（便于更新把插件自己卸载后对账）：
+
+| 事件 | 时机 |
+|---|---|
+| `plugin.update.latest` / `plugin.update.latest.failed` | 查到（或查不到）最新版 |
+| `plugin.update.check` | 一次检查完成 |
+| `plugin.update.apply.start` | 开始安装 |
+| `plugin.update.apply` | 安装成功（带 `application` / `restartRequired`） |
+| `plugin.update.apply.failed` | 安装失败（带 `code` / `steps`） |
+
+## 客户端控制器（headless）
+
+```ts
+import { createUpdateController } from '@morehao/dsh-plugin-kit/update/client';
+
+const controller = createUpdateController({
+  request: {
+    check: ({ fresh }) => api.getUpdate(fresh),   // 返回 UpdateClientView
+    apply: () => api.applyUpdate(),               // 返回 { application, restartRequired? }
+  },
+});
+controller.subscribe((state) => render(state));
+await controller.check();
+await controller.apply();
+```
+
+状态：`idle → checking → available | current | failed`；`available → applying → applied | restart-required | failed`。
+控制器不做 i18n、不引 React：错误码（`CHECK_FAILED` / `NO_UPDATE` / `NO_APPLY` 或宿主抛的 code）交给插件翻译。
+
+## HTTP 小工具
+
+```ts
+import { hasHeader, readJsonBody, sendJson } from '@morehao/dsh-plugin-kit/http';
+
+if (!hasHeader(request, 'x-my-plugin')) return sendJson(response, 403, { ok: false, code: 'FORBIDDEN' });
+const body = await readJsonBody(request, { maxBytes: 512 * 1024 });
+sendJson(response, 200, { ok: true });
+```
+
+## 版本与兼容
+
+- Node `^22.20.0 || >=24.0.0`，纯 ESM。
+- `./update` 与 `./http` 走 host 侧；`./update/client` 只含状态机，不 import node 内置模块（客户端产物只允许 react）。
+- 宿主服务形状按结构化类型处理（`PluginManagerLike` / `ProfileLike`），宿主版本变化不会把插件一起拖下去。
+
+## 开发
+
+```bash
+npm install
+npm run check   # typecheck + build + 26 条离线测试（假 fetch / 假 pluginManager，不联网、不真装）
+```

package/dist/http.d.ts

@@ -0,0 +1,28 @@
+/**
+ * HTTP 小工具：三个 web 插件共用的「自定义头鉴权 + no-store JSON + 有上限的 JSON body」。
+ *
+ * 只依赖结构化形状（不 import node:http 类型），宿主的 request/response 直接可用；
+ * 鉴权头名称由调用方给，避免把某一个插件的约定强加给其他插件。
+ */
+interface RequestLike {
+    headers?: Record<string, string | string[] | undefined>;
+}
+interface ResponseLike {
+    writeHead(status: number, headers: Record<string, string | number>): unknown;
+    end(body?: string): unknown;
+}
+type HttpErrorCode = 'PAYLOAD_TOO_LARGE' | 'INVALID_JSON';
+declare class HttpError extends Error {
+    readonly code: HttpErrorCode;
+    constructor(code: HttpErrorCode, message: string);
+}
+/** 请求头精确等于 `value`（默认 `1`）才算通过：跨源请求要先过预检，顺带挡 CSRF。 */
+declare function hasHeader(request: RequestLike, header: string, value?: string): boolean;
+declare function sendJson(response: ResponseLike, status: number, payload: unknown): void;
+interface ReadJsonOptions {
+    maxBytes?: number;
+}
+/** 读一个 JSON 对象 body；超过上限抛 PAYLOAD_TOO_LARGE，非对象/非法 JSON 抛 INVALID_JSON。 */
+declare function readJsonBody(request: AsyncIterable<Uint8Array | string>, options?: ReadJsonOptions): Promise<Record<string, unknown>>;
+
+export { HttpError, type HttpErrorCode, type ReadJsonOptions, type RequestLike, type ResponseLike, hasHeader, readJsonBody, sendJson };

package/dist/http.js

@@ -0,0 +1,51 @@
+// src/http.ts
+var HttpError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "HttpError";
+    this.code = code;
+  }
+};
+function hasHeader(request, header, value = "1") {
+  return request.headers?.[header.toLowerCase()] === value;
+}
+function sendJson(response, status, payload) {
+  const body = JSON.stringify(payload);
+  response.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "no-store",
+    "content-length": Buffer.byteLength(body)
+  });
+  response.end(body);
+}
+async function readJsonBody(request, options = {}) {
+  const maxBytes = options.maxBytes ?? 512 * 1024;
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of request) {
+    const buffer = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : Buffer.from(chunk);
+    size += buffer.length;
+    if (size > maxBytes) throw new HttpError("PAYLOAD_TOO_LARGE", "\u8BF7\u6C42\u4F53\u8FC7\u5927");
+    chunks.push(buffer);
+  }
+  if (chunks.length === 0) return {};
+  const text = Buffer.concat(chunks).toString("utf8").trim();
+  if (text === "") return {};
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    throw new HttpError("INVALID_JSON", `\u8BF7\u6C42\u4F53\u4E0D\u662F JSON \u5BF9\u8C61\uFF1A${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new HttpError("INVALID_JSON", "\u8BF7\u6C42\u4F53\u4E0D\u662F JSON \u5BF9\u8C61");
+  }
+  return value;
+}
+export {
+  HttpError,
+  hasHeader,
+  readJsonBody,
+  sendJson
+};

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+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';
+
+/** 保留旧接口形状：核心三段 + 预发布标识（字符串数组）。 */
+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;
+
+export { type Semver, compareVersions, isNewerVersion, parseSemver };

package/dist/index.js

@@ -0,0 +1,180 @@
+// src/semver.ts
+import semver from "semver";
+function parseSemver(value) {
+  const text = String(value ?? "").trim();
+  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;
+  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;
+  return semver.compare(String(left).trim(), String(right).trim());
+}
+
+// src/registry.ts
+var OFFICIAL_REGISTRY = "https://registry.npmjs.org/";
+var DEFAULT_TIMEOUT_MS = 8e3;
+var DEFAULT_CACHE_TTL_MS = 5 * 60 * 1e3;
+function encodePackageName(name) {
+  const text = name.trim();
+  if (text.startsWith("@")) {
+    const slash = text.indexOf("/");
+    if (slash < 0) return `@${encodeURIComponent(text.slice(1))}`;
+    return `@${encodeURIComponent(text.slice(1, slash))}%2F${encodeURIComponent(text.slice(slash + 1))}`;
+  }
+  return encodeURIComponent(text);
+}
+function normalizeRegistry(value) {
+  if (typeof value !== "string" || value.trim() === "") return null;
+  const text = value.trim().replace(/\/+$/, "");
+  try {
+    const url = new URL(`${text}/`);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    return url.href;
+  } catch {
+    return null;
+  }
+}
+function registryPlan(registries) {
+  const ordered = [];
+  const push = (value) => {
+    const normalized = normalizeRegistry(value);
+    if (normalized !== null && !ordered.includes(normalized)) ordered.push(normalized);
+  };
+  if (registries !== null && typeof registries === "object") {
+    const plan = registries;
+    push(plan.resolved);
+    push(plan.registry);
+    const fallback = plan.fallbackRegistries;
+    if (Array.isArray(fallback)) for (const item of fallback) push(item);
+  }
+  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/profile.ts
+function normalizeProfile(value) {
+  if (value === null || typeof value !== "object") return null;
+  const raw = value;
+  const profile = {};
+  if (typeof raw.name === "string" && raw.name !== "") profile.name = raw.name;
+  if (typeof raw.dir === "string" && raw.dir !== "") profile.dir = raw.dir;
+  if (typeof raw.home === "string" && raw.home !== "") profile.home = raw.home;
+  if (raw.packageManager !== null && typeof raw.packageManager === "object") {
+    const pm = raw.packageManager;
+    const command = typeof pm.command === "string" && pm.command !== "" ? pm.command : void 0;
+    const args = Array.isArray(pm.args) ? pm.args.filter((item) => typeof item === "string") : void 0;
+    if (command !== void 0 || args !== void 0) {
+      profile.packageManager = { ...command === void 0 ? {} : { command }, ...args === void 0 ? {} : { args } };
+    }
+  }
+  return profile;
+}
+function classifyInstallSpec(spec) {
+  if (typeof spec !== "string") return "unknown";
+  const text = spec.trim();
+  if (text === "") return "unknown";
+  if (text.startsWith("link:")) return "link";
+  if (text.startsWith("file:")) return "file";
+  if (text.startsWith("workspace:")) return "workspace";
+  return "registry";
+}
+async function defaultReadFile(path) {
+  const { readFile } = await import("fs/promises");
+  return readFile(path, "utf8");
+}
+async function readDeclaredSpec(deps) {
+  const { profile, packageName } = deps;
+  if (profile === null || typeof profile.dir !== "string" || profile.dir === "") return {};
+  const path = `${profile.dir.replace(/\/+$/, "")}/package.json`;
+  const readFile = deps.readFile ?? defaultReadFile;
+  const readJson = deps.readJson ?? (async (target) => JSON.parse(await readFile(target)));
+  let parsed;
+  try {
+    parsed = await readJson(path);
+  } catch {
+    return { source: "profile-package-json-unreadable" };
+  }
+  if (parsed === null || typeof parsed !== "object") return { source: "profile-package-json-invalid" };
+  const pkg = parsed;
+  for (const field of ["dependencies", "devDependencies", "optionalDependencies"]) {
+    const block = pkg[field];
+    if (block === null || typeof block !== "object") continue;
+    const spec = block[packageName];
+    if (typeof spec === "string") return { spec, source: `${path}#${field}` };
+  }
+  return { source: `${path}#no-entry` };
+}
+async function detectInstallKind(deps) {
+  const declared = await readDeclaredSpec(deps);
+  const result = { kind: classifyInstallSpec(declared.spec) };
+  if (declared.spec !== void 0) result.spec = declared.spec;
+  if (declared.source !== void 0) result.source = declared.source;
+  return result;
+}
+export {
+  DEFAULT_CACHE_TTL_MS,
+  DEFAULT_TIMEOUT_MS,
+  OFFICIAL_REGISTRY,
+  classifyInstallSpec,
+  compareVersions,
+  detectInstallKind,
+  encodePackageName,
+  isNewerVersion,
+  manualCommand,
+  normalizeProfile,
+  normalizeRegistry,
+  parseSemver,
+  readDeclaredSpec,
+  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

@@ -0,0 +1,57 @@
+import { UpdateView, ApplyResult } from './update.js';
+import './profile-RKpxKDlK.js';
+
+/**
+ * 客户端侧 headless 控制器（不依赖 React、不 import node 内置模块）。
+ *
+ * 各插件的 UI 长得不一样，共享「状态机 + 单飞 + 错误收敛」就够了：
+ * 插件用自己的 React / h() 订阅 `subscribe()`，按 `status` 渲染按钮与进度，
+ * 文案与样式留在各插件里（错误码由插件翻译，不在这里塞 i18n）。
+ *
+ * 状态：idle → checking → available | current | failed
+ *       available → applying → applied | restart-required | failed
+ */
+
+type UpdateClientStatus = 'idle' | 'checking' | 'available' | 'current' | 'failed' | 'applying' | 'applied' | 'restart-required';
+/** 只保留界面要用的字段，便于测试与跨版本兼容。 */
+type UpdateClientView = Pick<UpdateView, 'packageName' | 'currentVersion' | 'latestVersion' | 'updateAvailable' | 'checkFailed' | 'canApply' | 'installKind' | 'manualCommand'> & {
+    applying?: boolean;
+    installSpec?: string;
+};
+interface UpdateClientError {
+    code?: string;
+    message: string;
+}
+interface UpdateClientState {
+    status: UpdateClientStatus;
+    view: UpdateClientView | null;
+    error: UpdateClientError | null;
+    /** 最近一次检查完成时间（ISO）；没检查过就是 undefined。 */
+    checkedAt?: string;
+}
+interface UpdateRequest {
+    check(options: {
+        fresh?: boolean;
+        signal?: AbortSignal;
+    }): Promise<UpdateClientView>;
+    apply(): Promise<Pick<ApplyResult, 'application' | 'updatedVersion'> & {
+        restartRequired?: boolean;
+    }>;
+}
+interface UpdateControllerOptions {
+    request: UpdateRequest;
+    onChange?: (state: UpdateClientState) => void;
+    now?: () => number;
+}
+interface UpdateController {
+    getState(): UpdateClientState;
+    subscribe(listener: (state: UpdateClientState) => void): () => void;
+    check(options?: {
+        fresh?: boolean;
+    }): Promise<void>;
+    apply(): Promise<void>;
+    reset(): void;
+}
+declare function createUpdateController(options: UpdateControllerOptions): UpdateController;
+
+export { type UpdateClientError, type UpdateClientState, type UpdateClientStatus, type UpdateClientView, type UpdateController, type UpdateControllerOptions, type UpdateRequest, createUpdateController };

package/dist/update-client.js

@@ -0,0 +1,86 @@
+// src/update-client.ts
+var IDLE = { status: "idle", view: null, error: null };
+function errorOf(error) {
+  if (error !== null && typeof error === "object") {
+    const value = error;
+    const message = typeof value.message === "string" && value.message !== "" ? value.message : "\u64CD\u4F5C\u5931\u8D25";
+    return typeof value.code === "string" ? { code: value.code, message } : { message };
+  }
+  return { message: String(error ?? "\u64CD\u4F5C\u5931\u8D25") };
+}
+function createUpdateController(options) {
+  const now = options.now ?? Date.now;
+  let state = { ...IDLE };
+  const listeners = /* @__PURE__ */ new Set();
+  let inFlight = null;
+  function emit(next) {
+    state = next;
+    options.onChange?.(state);
+    for (const listener of listeners) listener(state);
+  }
+  async function check(checkOptions = {}) {
+    if (inFlight !== null) return;
+    inFlight = "check";
+    emit({ ...state, status: "checking", error: null });
+    try {
+      const view = await options.request.check(checkOptions);
+      const checkedAt = new Date(now()).toISOString();
+      if (view.checkFailed) {
+        emit({
+          status: "failed",
+          view,
+          error: { code: "CHECK_FAILED", message: "\u68C0\u67E5\u66F4\u65B0\u5931\u8D25\uFF1A\u62FF\u4E0D\u5230 registry \u4E0A\u7684\u6700\u65B0\u7248\u672C" },
+          checkedAt
+        });
+      } else {
+        emit({ status: view.updateAvailable ? "available" : "current", view, error: null, checkedAt });
+      }
+    } catch (error) {
+      emit({ ...state, status: "failed", error: errorOf(error) });
+    } finally {
+      inFlight = null;
+    }
+  }
+  async function apply() {
+    if (inFlight !== null) return;
+    const view = state.view;
+    if (view === null || !view.updateAvailable) {
+      emit({ ...state, status: "failed", error: { code: "NO_UPDATE", message: "\u6CA1\u6709\u53EF\u66F4\u65B0\u7684\u7248\u672C\uFF0C\u8BF7\u5148\u68C0\u67E5\u66F4\u65B0" } });
+      return;
+    }
+    if (!view.canApply) {
+      emit({
+        ...state,
+        status: "failed",
+        error: { code: "NO_APPLY", message: `\u5F53\u524D\u73AF\u5883\u4E0D\u652F\u6301\u4E00\u952E\u66F4\u65B0\uFF0C\u8BF7\u6267\u884C\uFF1A${view.manualCommand}` }
+      });
+      return;
+    }
+    inFlight = "apply";
+    emit({ ...state, status: "applying", error: null });
+    try {
+      const result = await options.request.apply();
+      const restartRequired = result.restartRequired ?? result.application !== "applied";
+      emit({ ...state, status: restartRequired ? "restart-required" : "applied", error: null });
+    } catch (error) {
+      emit({ ...state, status: "failed", error: errorOf(error) });
+    } finally {
+      inFlight = null;
+    }
+  }
+  return {
+    getState: () => state,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    check,
+    apply,
+    reset: () => emit({ ...IDLE })
+  };
+}
+export {
+  createUpdateController
+};

package/dist/update.d.ts

@@ -0,0 +1,113 @@
+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 {
+    name: string;
+    version: string;
+    repository?: string;
+}
+
+/**
+ * 插件自更新的 host 引擎：查最新版 → 判定能否一键更新 → 经宿主 `pluginManager` 重装。
+ *
+ * 设计约束（三个 DSH 插件共用这份逻辑）：
+ * - **零 `@deepseek-ai/*` 运行时依赖**：pluginManager / profileContext 都由调用方用
+ *   `ctx.get(...)` 惰性取。本包定位就是 DSH 插件，宿主必然在；但 `installBundle` 是
+ *   可选/远程能力，取不到只是「当前部署未暴露该能力」，退化成「只检查 + 手动命令」。
+ * - **复用优先**：registry 顺序优先用调用方注入的宿主原生 `registryPlan`（与宿主安装完全一致，
+ *   含私有源语义），未注入则内置兜底（见 `registry.ts` 的 `resolveRegistryPlan`）；查最新版走
+ *   `pnpm view` / registry `/latest`（`inspect()` 对已装包返回 already-installed，不可替代）。
+ * - **不自作主张升级**：只有 registry 明确给出合法且严格更新的版本才允许安装；
+ *   `link:` / `file:` / `workspace:` 安装一律禁止一键更新（会把开发链接换成 npm 版）。
+ * - **装不上要能回退**：宿主 `installBundle` 对已装包会返回 `already-installed`，按官方
+ *   更新路径先 remove 再 install；remove 之后 install 失败则尝试装回原版本。
+ * - **不重写宿主进程策略**：需要 `pnpm view` 时由调用方注入 `runPnpmView`（进程/环境
+ *   白名单是各插件自己的事），本包只做 registry 兜底。
+ * - 更新会把运行中的插件自己卸载，界面会一起消失：全过程落固定事件名，便于事后对账。
+ */
+
+type UpdateErrorCode = 'NO_MANAGER' | 'LINKED_INSTALL' | 'NOT_CHECKED' | 'NO_UPDATE' | 'INVALID_VERSION' | 'APPLY_IN_PROGRESS' | 'INSTALL_FAILED' | 'REMOVE_FAILED' | 'ROLLBACK_FAILED' | 'UNSUPPORTED_RESULT';
+declare class PluginUpdateError extends Error {
+    readonly code: UpdateErrorCode;
+    readonly detail: Record<string, unknown>;
+    constructor(code: UpdateErrorCode, message: string, detail?: Record<string, unknown>);
+}
+interface UpdateView {
+    packageName: string;
+    currentVersion: string;
+    latestVersion: string | null;
+    updateAvailable: boolean;
+    /** 查询失败（网络 / registry 都不可用），不等于「已是最新」。 */
+    checkFailed: boolean;
+    canApply: boolean;
+    installKind: InstallKind;
+    installSpec?: string;
+    manualCommand: string;
+    applying: boolean;
+    checkedAt?: string;
+}
+interface ApplyResult {
+    application: 'applied' | 'restart-required' | 'overridden';
+    restartRequired: boolean;
+    updatedVersion: string;
+    installKind: InstallKind;
+    /** 实际走过的步骤，给界面/日志做进度展示。 */
+    steps: string[];
+}
+interface PluginManagerLike {
+    installBundle?: (spec: string) => Promise<unknown>;
+    removeBundle?: (name: string) => Promise<unknown>;
+    registries?: () => unknown;
+}
+interface UpdaterDeps {
+    meta: PluginMeta;
+    getPluginManager?: () => unknown;
+    getProfile?: () => unknown;
+    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;
+    cacheTtlMs?: number;
+    timeoutMs?: number;
+}
+interface Updater {
+    check(options?: {
+        fresh?: boolean;
+    }): Promise<UpdateView>;
+    view(): UpdateView | null;
+    latestVersion(options?: {
+        fresh?: boolean;
+    }): Promise<string | null>;
+    apply(options?: {
+        version?: string;
+    }): Promise<ApplyResult>;
+    isApplying(): boolean;
+}
+declare function createPluginUpdater(deps: UpdaterDeps): Updater;
+
+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

@@ -0,0 +1,465 @@
+// src/registry.ts
+var OFFICIAL_REGISTRY = "https://registry.npmjs.org/";
+var DEFAULT_TIMEOUT_MS = 8e3;
+var DEFAULT_CACHE_TTL_MS = 5 * 60 * 1e3;
+function encodePackageName(name) {
+  const text = name.trim();
+  if (text.startsWith("@")) {
+    const slash = text.indexOf("/");
+    if (slash < 0) return `@${encodeURIComponent(text.slice(1))}`;
+    return `@${encodeURIComponent(text.slice(1, slash))}%2F${encodeURIComponent(text.slice(slash + 1))}`;
+  }
+  return encodeURIComponent(text);
+}
+function normalizeRegistry(value) {
+  if (typeof value !== "string" || value.trim() === "") return null;
+  const text = value.trim().replace(/\/+$/, "");
+  try {
+    const url = new URL(`${text}/`);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    return url.href;
+  } catch {
+    return null;
+  }
+}
+function registryPlan(registries) {
+  const ordered = [];
+  const push = (value) => {
+    const normalized = normalizeRegistry(value);
+    if (normalized !== null && !ordered.includes(normalized)) ordered.push(normalized);
+  };
+  if (registries !== null && typeof registries === "object") {
+    const plan = registries;
+    push(plan.resolved);
+    push(plan.registry);
+    const fallback = plan.fallbackRegistries;
+    if (Array.isArray(fallback)) for (const item of fallback) push(item);
+  }
+  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
+import semver from "semver";
+function parseSemver(value) {
+  const text = String(value ?? "").trim();
+  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;
+  const left = String(current).trim();
+  const right = String(candidate).trim();
+  return semver.gt(right, left);
+}
+
+// src/latest.ts
+function createLatestResolver(deps) {
+  const timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const cacheTtlMs = deps.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+  const now = deps.now ?? Date.now;
+  const logger = deps.logger ?? (() => {
+  });
+  const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+  let cache = null;
+  function manager() {
+    try {
+      const value = deps.getPluginManager?.();
+      return value !== null && typeof value === "object" ? value : null;
+    } catch {
+      return null;
+    }
+  }
+  async function readRegistries() {
+    const service = manager();
+    if (service === null || typeof service.registries !== "function") return null;
+    try {
+      return await service.registries();
+    } catch {
+      return null;
+    }
+  }
+  function remember(version, source) {
+    cache = { version, expiresAt: now() + cacheTtlMs, source };
+    return version;
+  }
+  async function viaPnpm() {
+    if (typeof deps.runPnpmView !== "function") return null;
+    try {
+      const value = await deps.runPnpmView(`${deps.meta.name}@latest`);
+      const version = typeof value === "string" ? value.trim() : "";
+      return parseSemver(version) === void 0 ? null : version;
+    } catch {
+      return null;
+    }
+  }
+  async function viaRegistries() {
+    const plan = resolveRegistryPlan(await readRegistries(), deps.registryPlan);
+    for (const base of plan) {
+      try {
+        const response = await fetchImpl(`${base}${encodePackageName(deps.meta.name)}/latest`, {
+          headers: { accept: "application/json" },
+          redirect: "error",
+          signal: AbortSignal.timeout(timeoutMs)
+        });
+        if (!response.ok) continue;
+        const value = await response.json();
+        const version = typeof value.version === "string" ? value.version.trim() : "";
+        if (parseSemver(version) !== void 0) return { version, source: base };
+      } catch {
+      }
+    }
+    return null;
+  }
+  async function latest(options = {}) {
+    if (deps.meta.name.trim() === "") return null;
+    if (options.fresh === true) cache = null;
+    if (cache !== null && now() < cache.expiresAt) return cache.version;
+    const pnpm = await viaPnpm();
+    if (pnpm !== null) {
+      logger("plugin.update.latest", { source: "pnpm", version: pnpm });
+      return remember(pnpm, "pnpm");
+    }
+    const registry = await viaRegistries();
+    if (registry !== null) {
+      logger("plugin.update.latest", { source: registry.source, version: registry.version });
+      return remember(registry.version, registry.source);
+    }
+    logger("plugin.update.latest.failed", { package: deps.meta.name });
+    return null;
+  }
+  return { latest, peek: () => cache === null ? null : { ...cache } };
+}
+
+// src/profile.ts
+function normalizeProfile(value) {
+  if (value === null || typeof value !== "object") return null;
+  const raw = value;
+  const profile = {};
+  if (typeof raw.name === "string" && raw.name !== "") profile.name = raw.name;
+  if (typeof raw.dir === "string" && raw.dir !== "") profile.dir = raw.dir;
+  if (typeof raw.home === "string" && raw.home !== "") profile.home = raw.home;
+  if (raw.packageManager !== null && typeof raw.packageManager === "object") {
+    const pm = raw.packageManager;
+    const command = typeof pm.command === "string" && pm.command !== "" ? pm.command : void 0;
+    const args = Array.isArray(pm.args) ? pm.args.filter((item) => typeof item === "string") : void 0;
+    if (command !== void 0 || args !== void 0) {
+      profile.packageManager = { ...command === void 0 ? {} : { command }, ...args === void 0 ? {} : { args } };
+    }
+  }
+  return profile;
+}
+function classifyInstallSpec(spec) {
+  if (typeof spec !== "string") return "unknown";
+  const text = spec.trim();
+  if (text === "") return "unknown";
+  if (text.startsWith("link:")) return "link";
+  if (text.startsWith("file:")) return "file";
+  if (text.startsWith("workspace:")) return "workspace";
+  return "registry";
+}
+async function defaultReadFile(path) {
+  const { readFile } = await import("fs/promises");
+  return readFile(path, "utf8");
+}
+async function readDeclaredSpec(deps) {
+  const { profile, packageName } = deps;
+  if (profile === null || typeof profile.dir !== "string" || profile.dir === "") return {};
+  const path = `${profile.dir.replace(/\/+$/, "")}/package.json`;
+  const readFile = deps.readFile ?? defaultReadFile;
+  const readJson = deps.readJson ?? (async (target) => JSON.parse(await readFile(target)));
+  let parsed;
+  try {
+    parsed = await readJson(path);
+  } catch {
+    return { source: "profile-package-json-unreadable" };
+  }
+  if (parsed === null || typeof parsed !== "object") return { source: "profile-package-json-invalid" };
+  const pkg = parsed;
+  for (const field of ["dependencies", "devDependencies", "optionalDependencies"]) {
+    const block = pkg[field];
+    if (block === null || typeof block !== "object") continue;
+    const spec = block[packageName];
+    if (typeof spec === "string") return { spec, source: `${path}#${field}` };
+  }
+  return { source: `${path}#no-entry` };
+}
+async function detectInstallKind(deps) {
+  const declared = await readDeclaredSpec(deps);
+  const result = { kind: classifyInstallSpec(declared.spec) };
+  if (declared.spec !== void 0) result.spec = declared.spec;
+  if (declared.source !== void 0) result.source = declared.source;
+  return result;
+}
+
+// src/update.ts
+var PluginUpdateError = class extends Error {
+  code;
+  detail;
+  constructor(code, message, detail = {}) {
+    super(message);
+    this.name = "PluginUpdateError";
+    this.code = code;
+    this.detail = detail;
+  }
+};
+function unwrapResult(result) {
+  if (result === null || typeof result !== "object") return {};
+  const value = result;
+  if (typeof value.ok === "boolean" && !("application" in value) && ("value" in value || "error" in value)) {
+    return value.ok ? unwrapResult(value.value) : { error: asError(value.error) };
+  }
+  const unwrapped = {};
+  if ("application" in value) unwrapped.application = value.application;
+  if ("error" in value && value.error !== void 0 && value.error !== null) unwrapped.error = asError(value.error);
+  return unwrapped;
+}
+function asError(value) {
+  if (value !== null && typeof value === "object") return value;
+  return { message: String(value ?? "") };
+}
+function failureMessage(error) {
+  if (error === void 0) return "";
+  for (const key of ["diagnostic", "message", "code"]) {
+    const value = error[key];
+    if (typeof value === "string" && value.trim() !== "") return value.trim();
+  }
+  return "";
+}
+var APPLICATIONS = /* @__PURE__ */ new Set(["applied", "restart-required", "overridden"]);
+function createPluginUpdater(deps) {
+  const logger = deps.logger ?? (() => {
+  });
+  const now = deps.now ?? Date.now;
+  const resolver = createLatestResolver({
+    meta: deps.meta,
+    ...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 },
+    logger
+  });
+  let lastView = null;
+  let applying = false;
+  function manager() {
+    try {
+      const value = deps.getPluginManager?.();
+      return value !== null && typeof value === "object" ? value : null;
+    } catch {
+      return null;
+    }
+  }
+  function profile() {
+    try {
+      return normalizeProfile(deps.getProfile?.());
+    } catch {
+      return null;
+    }
+  }
+  function profileName() {
+    try {
+      const fromDep = deps.getProfileName?.();
+      if (typeof fromDep === "string" && fromDep !== "") return fromDep;
+      return profile()?.name ?? null;
+    } catch {
+      return null;
+    }
+  }
+  function canApplyWith(kind) {
+    const service = manager();
+    if (service === null || typeof service.installBundle !== "function") return false;
+    return kind === "registry" || kind === "unknown";
+  }
+  async function check(options = {}) {
+    const install = await detectInstallKind({
+      profile: profile(),
+      packageName: deps.meta.name,
+      ...deps.readFile === void 0 ? {} : { readFile: deps.readFile }
+    });
+    const latest = await resolver.latest(options.fresh === true ? { fresh: true } : {});
+    const view = {
+      packageName: deps.meta.name,
+      currentVersion: deps.meta.version,
+      latestVersion: latest,
+      updateAvailable: latest !== null && isNewerVersion(deps.meta.version, latest),
+      checkFailed: latest === null,
+      canApply: canApplyWith(install.kind),
+      installKind: install.kind,
+      ...install.spec === void 0 ? {} : { installSpec: install.spec },
+      manualCommand: manualCommand(deps.meta.name, profileName()),
+      applying,
+      checkedAt: new Date(now()).toISOString()
+    };
+    lastView = view;
+    logger("plugin.update.check", {
+      current: view.currentVersion,
+      latest: view.latestVersion,
+      updateAvailable: view.updateAvailable,
+      checkFailed: view.checkFailed,
+      canApply: view.canApply,
+      installKind: view.installKind
+    });
+    return view;
+  }
+  async function apply(options = {}) {
+    if (applying) throw new PluginUpdateError("APPLY_IN_PROGRESS", "\u5DF2\u6709\u4E00\u6B21\u66F4\u65B0\u5728\u8FDB\u884C\u4E2D");
+    const view = lastView;
+    if (view === null) {
+      throw new PluginUpdateError("NOT_CHECKED", "\u8FD8\u6CA1\u6709\u68C0\u67E5\u8FC7\u66F4\u65B0\uFF0C\u8BF7\u5148\u68C0\u67E5\u518D\u66F4\u65B0");
+    }
+    if (view.checkFailed || view.latestVersion === null) {
+      throw new PluginUpdateError("NOT_CHECKED", "\u8FD8\u6CA1\u6709\u62FF\u5230\u53EF\u7528\u7684\u6700\u65B0\u7248\u672C\uFF0C\u8BF7\u5148\u68C0\u67E5\u66F4\u65B0", { checkFailed: view.checkFailed });
+    }
+    const target = view.latestVersion;
+    if (options.version !== void 0 && options.version !== target) {
+      throw new PluginUpdateError("INVALID_VERSION", `\u53EA\u80FD\u66F4\u65B0\u5230\u521A\u67E5\u5230\u7684 ${target}\uFF0C\u4E0D\u63A5\u53D7 ${options.version}`, {
+        requested: options.version,
+        target
+      });
+    }
+    if (!view.updateAvailable || !isNewerVersion(deps.meta.version, target)) {
+      throw new PluginUpdateError("NO_UPDATE", `\u5F53\u524D v${deps.meta.version} \u5DF2\u662F\u6700\u65B0\uFF08registry: ${target}\uFF09`);
+    }
+    if (parseSemver(target) === void 0) {
+      throw new PluginUpdateError("INVALID_VERSION", `registry \u8FD4\u56DE\u7684\u7248\u672C\u4E0D\u662F\u5408\u6CD5 semver\uFF1A${target}`);
+    }
+    const install = await detectInstallKind({
+      profile: profile(),
+      packageName: deps.meta.name,
+      ...deps.readFile === void 0 ? {} : { readFile: deps.readFile }
+    });
+    if (install.kind === "link" || install.kind === "file" || install.kind === "workspace") {
+      throw new PluginUpdateError(
+        "LINKED_INSTALL",
+        `\u5F53\u524D\u662F\u672C\u5730 ${install.kind} \u5B89\u88C5\uFF08${install.spec ?? "\u672A\u77E5 spec"}\uFF09\uFF0C\u4E0D\u80FD\u7528 registry \u7248\u672C\u8986\u76D6\uFF1B\u8BF7\u624B\u52A8\u6267\u884C ${view.manualCommand}`,
+        { installKind: install.kind, spec: install.spec }
+      );
+    }
+    const service = manager();
+    if (service === null || typeof service.installBundle !== "function") {
+      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
+      });
+    }
+    const installBundle = service.installBundle.bind(service);
+    const removeBundle = typeof service.removeBundle === "function" ? service.removeBundle.bind(service) : null;
+    const spec = `${deps.meta.name}@${target}`;
+    const steps = [];
+    applying = true;
+    lastView = { ...view, applying: true };
+    logger("plugin.update.apply.start", { from: deps.meta.version, target, installKind: install.kind });
+    try {
+      steps.push(`install ${spec}`);
+      let installed = unwrapResult(await installBundle(spec));
+      let removed = false;
+      if (installed.error?.code === "already-installed" && removeBundle !== null) {
+        steps.push(`remove ${deps.meta.name}`);
+        const removal = unwrapResult(await removeBundle(deps.meta.name));
+        if (removal.error !== void 0 || removal.application === "failed") {
+          throw new PluginUpdateError("REMOVE_FAILED", `\u79FB\u9664\u65E7\u7248\u672C\u5931\u8D25\uFF1A${failureMessage(removal.error)}`, { steps });
+        }
+        removed = true;
+        steps.push(`install ${spec}`);
+        installed = unwrapResult(await installBundle(spec));
+      }
+      if (installed.error !== void 0) {
+        const message = failureMessage(installed.error) || "\u5B89\u88C5\u65B0\u7248\u672C\u5931\u8D25";
+        if (removed) {
+          steps.push(`rollback ${deps.meta.name}@${deps.meta.version}`);
+          let rollback;
+          try {
+            rollback = unwrapResult(await installBundle(`${deps.meta.name}@${deps.meta.version}`));
+          } catch (error) {
+            throw new PluginUpdateError("ROLLBACK_FAILED", `\u66F4\u65B0\u5931\u8D25\u4E14\u56DE\u6EDA\u5931\u8D25\uFF1A${message}`, {
+              steps,
+              cause: error instanceof Error ? error.message : String(error)
+            });
+          }
+          if (rollback.error !== void 0) {
+            throw new PluginUpdateError("ROLLBACK_FAILED", `\u66F4\u65B0\u5931\u8D25\u4E14\u56DE\u6EDA\u5931\u8D25\uFF1A${message}`, {
+              steps,
+              rollback: failureMessage(rollback.error)
+            });
+          }
+        }
+        throw new PluginUpdateError("INSTALL_FAILED", `\u5B89\u88C5 v${target} \u5931\u8D25\uFF1A${message}`, { steps });
+      }
+      const application = typeof installed.application === "string" ? installed.application : "unknown";
+      if (!APPLICATIONS.has(application)) {
+        throw new PluginUpdateError("UNSUPPORTED_RESULT", `\u66F4\u65B0\u672A\u751F\u6548\uFF08application=${application}\uFF09`, { steps });
+      }
+      const result = {
+        application,
+        restartRequired: application !== "applied",
+        updatedVersion: target,
+        installKind: install.kind,
+        steps
+      };
+      logger("plugin.update.apply", { ...result });
+      return result;
+    } catch (error) {
+      const normalized = error instanceof PluginUpdateError ? error : new PluginUpdateError("INSTALL_FAILED", error instanceof Error ? error.message : String(error), { steps });
+      logger("plugin.update.apply.failed", { code: normalized.code, message: normalized.message, steps });
+      throw normalized;
+    } finally {
+      applying = false;
+      if (lastView !== null) lastView = { ...lastView, applying: false };
+    }
+  }
+  return {
+    check,
+    view: () => lastView,
+    latestVersion: (options = {}) => resolver.latest(options),
+    apply,
+    isApplying: () => applying
+  };
+}
+export {
+  PluginUpdateError,
+  createPluginUpdater
+};

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@morehao/dsh-plugin-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "DeepSeek Harness 插件共用工具包：插件自更新引擎（查 npm 最新版 + 经宿主 pluginManager 重装）、headless 客户端控制器与 HTTP 小工具。零 @deepseek-ai 运行时依赖，宿主能力全部注入。",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./update": {
+      "types": "./dist/update.d.ts",
+      "default": "./dist/update.js"
+    },
+    "./update/client": {
+      "types": "./dist/update-client.d.ts",
+      "default": "./dist/update-client.js"
+    },
+    "./http": {
+      "types": "./dist/http.d.ts",
+      "default": "./dist/http.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "engines": {
+    "node": "^22.20.0 || >=24.0.0"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "plugin-update",
+    "self-update"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test \"test/*.test.mjs\"",
+    "pretest": "npm run build",
+    "check": "npm run typecheck && npm run build && npm test --ignore-scripts"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.5",
+    "@types/semver": "^7.8.0",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3"
+  },
+  "license": "MIT",
+  "author": "morehao <morehao@qq.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/morehao/dsh-plugin-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/morehao/dsh-plugin-kit/issues"
+  },
+  "homepage": "https://github.com/morehao/dsh-plugin-kit",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "semver": "^7.8.5"
+  }
+}