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

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,110 @@
-# 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
+```
+
+## 一键更新（host）
+
+```ts
+import { createPluginUpdater } from '@morehao/dsh-plugin-kit/update';
+
+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,
+  // 可选：用 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 + 24 条离线测试（假 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,43 @@
+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';
+
+/**
+ * semver 解析与比较（只做插件更新需要的部分）。
+ *
+ * 不引 semver 依赖：更新判定宁可不升级也不要误升，所以非法版本一律返回 undefined，
+ * 由调用方按「不更新」处理。支持 `v1.2.3` / `1.2.3-beta.1` / `1.2.3+build`。
+ */
+interface Semver {
+    core: [number, number, number];
+    prerelease: string[];
+}
+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 };

package/dist/index.js

@@ -0,0 +1,179 @@
+// src/semver.ts
+var SEMVER = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+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;
+}
+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;
+}
+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);
+}
+
+// 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 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
+};

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

@@ -0,0 +1,44 @@
+/**
+ * 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 };

package/dist/update-client.d.ts

@@ -0,0 +1,57 @@
+import { UpdateView, ApplyResult } from './update.js';
+import './profile-C-eyP5F6.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,87 @@
+import { I as InstallKind } from './profile-C-eyP5F6.js';
+export { P as ProfileLike } from './profile-C-eyP5F6.js';
+
+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(...)` 惰性取，拿不到就退化成「只检查 + 手动命令」。
+ * - **不自作主张升级**：只有 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>;
+    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, InstallKind, type Logger, type PluginManagerLike, type PluginMeta, PluginUpdateError, type UpdateErrorCode, type UpdateView, type Updater, type UpdaterDeps, createPluginUpdater };

package/dist/update.js

@@ -0,0 +1,459 @@
+// 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 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.-]+)?$/;
+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;
+}
+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;
+}
+
+// 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 = registryPlan(await readRegistries());
+    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.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\u73AF\u5883\u4E0D\u652F\u6301\u4E00\u952E\u66F4\u65B0\uFF08\u7F3A\u5C11 pluginManager.installBundle\uFF09", {
+        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,69 @@
 {
   "name": "@morehao/dsh-plugin-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "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",
+    "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/"
+  }
+}