dsh-plugin-snapshot 0.0.0-stage → 0.1.1

package/LICENSE

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

@@ -0,0 +1,86 @@
+# dsh-plugin-snapshot
+
+**Pre-upgrade snapshots, one-step rollback and a static health check for DeepSeek Harness plugins.**
+
+One plugin, three tools.
+
+- npm: https://www.npmjs.com/package/dsh-plugin-snapshot
+- repo: https://github.com/Uesccda/dsh-plugin-snapshot
+- compatible with DSH 0.2.0+ (tested on 0.2.2-rc.1)
+
+---
+
+## What problem it solves
+
+| The trouble you hit | What this does |
+| --- | --- |
+| A plugin upgrade fails halfway: manifests changed, dependencies not installed, unknown state | Takes a snapshot with fingerprint and hashes before upgrading, so you can always go back |
+| Dozens of plugins installed, no idea which collide or whose compatibility claim is stale | One scan reports installed / enabled / missing / incompatible / untested, plus a review priority |
+| No idea which plugins have newer versions, and afraid of auto-upgrading to a beta | Lists updatable items and marks prereleases separately instead of mixing them in |
+
+It deliberately does **not** install, remove or toggle plugins: that is what the built-in plugin_manager is for. Two implementations fighting over the same profile is the most common source of breakage in this ecosystem.
+
+---
+
+## The three tools
+
+| Tool | Does | Writes |
+| --- | --- | --- |
+| plugin_snapshot | create / list / restore snapshots of the profile manifests | only its own data dir, plus the three manifests on restore |
+| plugin_doctor | static diagnostic: install state, author-declared compatibility, duplicate patch ids, missing packages | read-only |
+| plugin_updates | compares the version resolved in pnpm-lock.yaml against the registry | read-only |
+
+---
+
+## Usage
+
+Just talk to the model:
+
+- "Take a snapshot before upgrading my plugins"
+- "Check my installed plugins for problems"
+- "Which plugins have updates available?"
+- "That upgrade failed, roll back to before it"
+
+---
+
+## Install
+
+    dsh plugin add dsh-plugin-snapshot
+
+Restart DSH afterwards. Remove with:
+
+    dsh plugin remove dsh-plugin-snapshot
+
+---
+
+## What a snapshot contains
+
+The three profile manifests (package.json, pnpm-lock.yaml, pnpm-workspace.yaml) plus a manifest.json recording the profile fingerprint, creation time, per-file existence and sha256.
+
+Restoring verifies the fingerprint first, so a snapshot from another profile is rejected. A hash mismatch only warns, because you may have edited the manifest by hand.
+
+Snapshots do **not** include node_modules. Dependencies must be reinstalled after a restore.
+
+---
+
+## Where data lives
+
+    ~/.dsh-plugin-snapshot/snapshots/<timestamp>/
+    ~/.dsh-plugin-snapshot/logs/
+
+Nothing else is written except the three profile manifests on restore.
+
+---
+
+## Limitations
+
+- Snapshots cover the three manifests only, not node_modules
+- Diagnostics are static evidence, not runtime verification
+- No scheduler: the plugin only exists while DSH runs
+
+---
+
+## License
+
+MIT
+

package/README.md

@@ -1,3 +1,120 @@
-# Temporary Holding Version
+# dsh-plugin-snapshot
+
+**给 DeepSeek Harness 的插件做升级前快照、一键回滚和静态体检。**
+
+一个插件，三个工具。
+
+- npm: https://www.npmjs.com/package/dsh-plugin-snapshot
+- 仓库: https://github.com/Uesccda/dsh-plugin-snapshot
+- 兼容: DSH 0.2.0 及以上（已在 0.2.2-rc.1 实测）
+
+---
+
+## 它解决什么问题
+
+| 你会遇到的麻烦 | 这个插件怎么处理 |
+| --- | --- |
+| 升级插件失败，清单已经改了、依赖没装完，不知道回到了什么状态 | 升级前先存一份带指纹和哈希的快照，任何时候都能退回去 |
+| 装了几十个插件，不知道谁跟谁冲突、谁的兼容声明已经过期 | 一次扫描给出：已装/已启用/缺失/不兼容/未验证，以及检查优先级 |
+| 不知道哪些插件有新版本，又怕自动升到测试版 | 列出可更新项，预发布版本单独标注、不混进"可升级"里 |
+
+它**不负责**安装、卸载、启停插件——那是 DSH 自带的 plugin_manager 的事。两套实现打架是插件市场里最常见的坑，这里直接避开。
+
+---
+
+## 三个工具
+
+| 工具 | 做什么 | 会不会写文件 |
+| --- | --- | --- |
+| plugin_snapshot | 创建快照 / 列出快照 / 恢复到某个快照 | 只写自己的数据目录，恢复时覆盖 profile 的三份清单 |
+| plugin_doctor | 静态体检：安装状态、作者声明的兼容性、patch id 冲突、缺失的包 | 纯只读 |
+| plugin_updates | 以 lockfile 解析出的版本为基准，查 registry 有没有新版本 | 纯只读 |
+
+---
+
+## 怎么用（对话示例）
+
+你不用记命令，直接跟模型说：
+
+- **"升级插件前先给我打个快照"** → 调用 plugin_snapshot 的 create，返回快照名
+- **"看看我这些插件有没有问题"** → 调用 plugin_doctor，给出 48 个插件的体检结果
+- **"哪些插件可以升级"** → 调用 plugin_updates，列出可更新项
+- **"刚才那次升级失败了，退回到升级前"** → 调用 plugin_snapshot 的 restore
+
+---
+
+## 安装
+
+    dsh plugin add dsh-plugin-snapshot
+
+装完重启 DSH（启用 HMR 时自动生效），三个工具随即可用。
+
+卸载：
+
+    dsh plugin remove dsh-plugin-snapshot
+
+---
+
+## 兼容性
+
+本插件声明支持 DSH 0.2.0 及以上，并在 0.2.2-rc.1 实测通过：
+
+    0.2.2-rc.1  compatible
+    0.2.1       compatible
+    0.2.0+      compatible
+
+如果你在别的 DSH 版本上使用，plugin_doctor 会如实显示为「未验证」而不是假装兼容。
+
+---
+
+## 快照里存了什么
+
+profile 目录下的三份清单：
+
+    package.json
+    pnpm-lock.yaml
+    pnpm-workspace.yaml
+
+每份快照额外带一个 manifest.json，记录：profile 指纹、创建时间、每个文件是否存在、每个文件的 sha256。
+
+恢复时会先比对 profile 指纹——**别的 profile 的快照会被拒绝**，避免把 A 环境的清单写进 B。文件摘要对不上只告警，因为你可能手工改过清单。
+
+⚠️ 快照**不包含 node_modules**。恢复之后需要让包管理器重新安装依赖。
+
+---
+
+## 数据放在哪
+
+    ~/.dsh-plugin-snapshot/snapshots/<时间戳>/
+    ~/.dsh-plugin-snapshot/logs/
+
+只写这两个目录，以及恢复时写回 profile 的三份清单。不碰 node_modules、不改 bundles 清单、不启动或关闭 DSH。
+
+---
+
+## 安全边界
+
+- plugin_doctor 与 plugin_updates 是**纯只读**：只读文件、只发 GET 请求
+- plugin_snapshot 的 create 只写自己的数据目录；restore 必须显式传 name
+- 不调用 pnpm、不修改依赖树、不结束任何进程
+
+---
+
+## 已知限制
+
+- 快照只覆盖三份清单，不含 node_modules
+- 诊断基于静态扫描与作者声明，不代表运行时验证
+- 没有定时任务：插件只在 DSH 运行时存在
+
+---
+
+## 开发
+
+    npm test      # 5 项自测，用 stub 顶替 @deepseek-ai/dsh-tools
+
+---
+
+## 许可
+
+MIT
 
-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.

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# dsh bundle patch: inserts this plugin into a profile's layer stack.
+- insert:
+    - id: dsh-plugin-snapshot
+      name: 'dsh-plugin-snapshot'
+

package/lib/doctor.js

@@ -0,0 +1,177 @@
+/**
+ * 诊断：静态扫描已安装插件，给出兼容性、互斥与检查优先级。
+ * 只读，不修改任何文件；结论都标注为「静态线索」，不是运行时验证。
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { readProfile, readLockVersions } from './profile.js';
+import { parseSemver, cmpSemver, shortVer } from './util.js';
+
+const MAX_JSON = 4 * 1024 * 1024;
+
+/** 兼容性判定：否定声明优先于肯定声明（incompatible 绝不能被读成兼容） */
+export function judgeCompatibility(pkg, dshVersion) {
+  const cur = parseSemver(dshVersion);
+  const dshField = (pkg && pkg.dsh) || {};
+  const rel = (dshField.compatibility && dshField.compatibility.dshReleases) || null;
+  const out = { state: 'unknown', label: '未声明', detail: '', declared: [], current: dshVersion };
+
+  if (rel && typeof rel === 'object') {
+    const keys = Object.keys(rel);
+    out.declared = keys.map((k) => k + ' -> ' + rel[k]);
+    let denyKey = null;
+    let allowExact = null;
+    let allowOpen = false;
+    for (const k of keys) {
+      const raw = String(k).trim();
+      const isOpen = raw.slice(-1) === '+';
+      const ver = isOpen ? raw.slice(0, -1) : raw;
+      const val = String(rel[k] === undefined ? '' : rel[k]).toLowerCase().trim();
+      const isDeny = /^(in|not|no|un|non|unsupported)/.test(val);
+      const isPartial = val.indexOf('partial') === 0;
+      const isAllow = /compat|^full$|^yes$|^true$|^supported$|^ok$/.test(val);
+      if (!isDeny && !isPartial && !isAllow) continue;
+      if (!cur) continue;
+      const covers = isOpen ? (!!parseSemver(ver) && cmpSemver(dshVersion, ver) >= 0) : (cmpSemver(dshVersion, ver) === 0);
+      if (!covers) continue;
+      if (isDeny || isPartial) denyKey = raw + ' = ' + rel[k];
+      else if (isOpen) allowOpen = true;
+      else allowExact = ver;
+    }
+    if (denyKey) {
+      out.state = 'incompatible';
+      out.label = '明确不兼容';
+      out.detail = '作者显式声明 ' + denyKey + '，当前 DSH ' + dshVersion + ' 不在支持范围';
+      return out;
+    }
+    if (allowExact) { out.state = 'compatible'; out.label = '已验证兼容'; out.detail = '显式声明 ' + allowExact + ' 兼容'; return out; }
+    if (allowOpen) { out.state = 'compatible'; out.label = '区间兼容'; out.detail = '当前版本落在声明的开放区间内'; return out; }
+    out.state = 'untested';
+    out.label = '未验证';
+    out.detail = '声明范围不含 ' + (dshVersion || '未知版本') + '；风险未知，建议先在测试环境验证';
+    return out;
+  }
+  if (pkg && pkg.engines && pkg.engines.dsh) {
+    out.state = 'engines-only';
+    out.label = '仅 engines 约束';
+    out.detail = 'engines.dsh = ' + pkg.engines.dsh + '（作者未声明 compatibility）';
+    return out;
+  }
+  out.detail = '插件未声明任何 DSH 版本兼容信息';
+  return out;
+}
+
+function patchIds(text) {
+  const ids = [];
+  let inInsert = false;
+  for (const raw of String(text).split(/\r?\n/)) {
+    const line = raw.replace(/\s+$/, '');
+    if (/^\s*-?\s*insert:\s*$/.test(line)) { inInsert = true; continue; }
+    if (!inInsert) continue;
+    if (/^\s*$/.test(line) || /^\s*#/.test(line)) continue;
+    const m = /^\s*-?\s*id:\s*([^\s#]+)\s*$/.exec(line);
+    if (m) { ids.push(m[1]); continue; }
+    if (/^\s*-?\s*[a-zA-Z_]+:/.test(line) && !/^\s{4,}/.test(line)) inInsert = false;
+  }
+  return Array.from(new Set(ids));
+}
+
+function hasNative(dir) {
+  const walk = (d, depth) => {
+    if (depth > 2) return false;
+    let items = [];
+    try { items = readdirSync(d, { withFileTypes: true }); } catch (e) { return false; }
+    for (const e of items) {
+      if (e.isFile() && e.name.endsWith('.node')) return true;
+      if (e.isDirectory() && /^(build|prebuilds|native)$/.test(e.name) && walk(join(d, e.name), depth + 1)) return true;
+    }
+    return false;
+  };
+  return walk(dir, 0);
+}
+
+export function scanPlugins(profileDir, dshVersion) {
+  const prof = readProfile(profileDir);
+  const lock = readLockVersions(profileDir);
+  const nm = join(profileDir, 'node_modules');
+  const items = [];
+  for (const name of Object.keys(prof.deps)) {
+    const dir = join(nm, ...name.split('/'));
+    const enabled = prof.bundles.indexOf(name) >= 0;
+    const pkgFile = join(dir, 'package.json');
+    if (!existsSync(pkgFile)) {
+      items.push({ name, enabled, installed: false, error: '已声明但未安装（node_modules 缺失）', declared: String(prof.deps[name]) });
+      continue;
+    }
+    let pkg = {};
+    let error = '';
+    try {
+      if (statSync(pkgFile).size > MAX_JSON) error = 'package.json 过大，已跳过解析';
+      else pkg = JSON.parse(readFileSync(pkgFile, 'utf8'));
+    } catch (e) { error = 'package.json 无法解析'; }
+    const patchFile = join(dir, 'cordis.patch.yml');
+    let ids = [];
+    let hasPatch = false;
+    if (existsSync(patchFile)) {
+      hasPatch = true;
+      try { ids = patchIds(readFileSync(patchFile, 'utf8')); } catch (e) { /* 忽略 */ }
+    }
+    const rawInject = (pkg.dsh && pkg.dsh.client && pkg.dsh.client.inject);
+    items.push({
+      name,
+      enabled,
+      installed: true,
+      version: pkg.version || '?',
+      declared: String(prof.deps[name]),
+      resolved: lock[name] || '',
+      hasPatch,
+      patchIds: ids,
+      hasNative: hasNative(dir),
+      clientInject: Array.isArray(rawInject) ? rawInject.filter((x) => typeof x === 'string') : [],
+      compatibility: judgeCompatibility(pkg, dshVersion),
+      error: error || undefined
+    });
+  }
+  return { items, profile: prof.name };
+}
+
+export function detectConflicts(items) {
+  const conflicts = [];
+  const byPatch = new Map();
+  for (const it of items) {
+    for (const id of it.patchIds || []) {
+      if (!byPatch.has(id)) byPatch.set(id, []);
+      byPatch.get(id).push(it.name);
+    }
+  }
+  for (const [id, owners] of byPatch) {
+    if (owners.length > 1) conflicts.push({ severity: 'critical', kind: 'patch-id', message: 'patch 行标识 ' + id + ' 被 ' + owners.length + ' 个插件占用', plugins: owners });
+  }
+  for (const it of items) {
+    const c = it.compatibility || {};
+    if (c.state === 'incompatible') conflicts.push({ severity: 'critical', kind: 'compat', message: it.name + '：' + c.detail, plugins: [it.name] });
+    else if (c.state === 'untested') conflicts.push({ severity: 'high', kind: 'compat', message: it.name + '：' + c.detail, plugins: [it.name] });
+    if (it.installed === false) conflicts.push({ severity: 'high', kind: 'missing', message: it.name + '：' + it.error, plugins: [it.name] });
+    if (it.error) conflicts.push({ severity: 'medium', kind: 'manifest', message: it.name + '：' + it.error, plugins: [it.name] });
+  }
+  const rank = { critical: 0, high: 1, medium: 2, low: 3 };
+  conflicts.sort((a, b) => (rank[a.severity] - rank[b.severity]) || (a.kind < b.kind ? -1 : 1));
+  return conflicts;
+}
+
+/** 检查优先级（规则加权，不是崩溃概率） */
+export function priorityOf(item, conflicts) {
+  let score = 0;
+  const factors = [];
+  const mine = conflicts.filter((c) => c.plugins.indexOf(item.name) >= 0);
+  for (const c of mine) {
+    if (c.severity === 'critical') { score += 45; factors.push('严重：' + c.kind); }
+    else if (c.severity === 'high') { score += 25; factors.push('高：' + c.kind); }
+    else { score += 12; factors.push('中：' + c.kind); }
+  }
+  if (item.hasNative) { score += 8; factors.push('含原生模块'); }
+  score = Math.max(0, Math.min(100, score));
+  const level = score >= 60 ? '高' : score >= 30 ? '中' : score >= 10 ? '低' : '未发现已知风险';
+  return { score, level, factors };
+}
+

package/lib/index.js

@@ -0,0 +1,303 @@
+/**
+ * dsh-plugin-snapshot — 插件快照、回滚与诊断。
+ *
+ * 设计边界（刻意保持窄）：
+ *  - 只做三件事：检测可更新项、快照/回滚 profile 清单、静态诊断；
+ *  - 不安装、不卸载、不启停插件——那是官方 plugin_manager 的职责，不重复实现；
+ *  - 所有写操作只发生在自己的数据目录与 profile 的三份清单文件上。
+ */
+/*
+ * defineTool 由宿主提供。这里做成「优先官方、缺失时降级」：
+ * 一旦解析不到就整插件加载失败，代价远大于少一层参数校验。
+ * 降级后工具仍按同一契约注册（name/description/parameters/output/execute），
+ * 只是不再享受官方 schema 校验；正常情况下走的一定是官方实现。
+ */
+let defineTool;
+try {
+  ({ defineTool } = await import('@deepseek-ai/dsh-tools'));
+} catch (e) {
+  defineTool = null;
+}
+if (typeof defineTool !== 'function') {
+  defineTool = (options) => options;
+}
+import { resolveProfileDir, readProfile } from './profile.js';
+import { createSnapshot, listSnapshots, restoreSnapshot } from './snapshot.js';
+import { checkUpdates } from './updates.js';
+import { scanPlugins, detectConflicts, priorityOf } from './doctor.js';
+import { Logger, dataDir } from './util.js';
+
+export const name = 'dsh-plugin-snapshot';
+
+export const inject = ['tools'];
+
+const TOOL = {
+  updates: 'plugin_updates',
+  snapshot: 'plugin_snapshot',
+  doctor: 'plugin_doctor'
+};
+
+function makeCtx(config) {
+  const cfg = config || {};
+  return {
+    profileDir: cfg.profileDir || '',
+    registry: cfg.registry || '',
+    dataDir: cfg.dataDir || dataDir(),
+    snapshotsKeep: cfg.snapshotsKeep || 7,
+    concurrency: cfg.concurrency || 8,
+    logger: new Logger()
+  };
+}
+
+function needProfile(cfg) {
+  const dir = resolveProfileDir(cfg);
+  if (!dir) {
+    throw new Error('没能定位 DSH profile 目录。可在插件配置里指定 profileDir，或设置 DSH_PROFILE_DIR 环境变量。');
+  }
+  return dir;
+}
+
+function renderLines(title, lines) {
+  return [{ type: 'text', text: title + '\n' + lines.join('\n') }];
+}
+
+export function apply(ctx, config) {
+  const cfg = makeCtx(config);
+
+  ctx.inject(['tools'], (sctx) => {
+    sctx.tools.register(defineTool({
+      name: TOOL.updates,
+      description: 'List DeepSeek Harness profile plugins that have a newer npm version. Read-only: compares the version resolved in pnpm-lock.yaml with the registry, and never installs anything. Returns per-plugin state (updatable / major / uptodate / prerelease / failed) plus a summary.',
+      parameters: {
+        registry: { type: 'string', description: 'npm registry to query. Defaults to the plugin config, DSH_REGISTRY, or registry.npmjs.org.' },
+        onlyUpdatable: { type: 'boolean', description: 'When true, return only items that have a newer version.' }
+      },
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            profile: { type: 'string' },
+            registry: { type: 'string' },
+            summary: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                total: { type: 'number' },
+                updatable: { type: 'number' },
+                major: { type: 'number' },
+                uptodate: { type: 'number' },
+                failed: { type: 'number' },
+                skipped: { type: 'number' }
+              }
+            },
+            items: {
+              type: 'array',
+              items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                  name: { type: 'string' },
+                  declared: { type: 'string' },
+                  resolved: { type: 'string' },
+                  candidate: { type: 'string' },
+                  state: { type: 'string' },
+                  reason: { type: 'string' }
+                }
+              }
+            }
+          }
+        },
+        render(args, value) {
+          const s = value.summary || {};
+          const rows = (value.items || []).map((x) => '- ' + x.name + '  ' + (x.resolved || x.declared || '?') + ' -> ' + (x.candidate || '-') + '  [' + x.state + ']' + (x.reason ? ' ' + x.reason : ''));
+          return renderLines('Plugin updates (profile: ' + value.profile + ', registry: ' + value.registry + ')', [
+            'total ' + s.total + ' | updatable ' + s.updatable + ' | major ' + s.major + ' | uptodate ' + s.uptodate + ' | failed ' + s.failed,
+            ...(rows.length ? rows : ['- nothing to show'])
+          ]);
+        }
+      },
+      async execute(args) {
+        const a = args || {};
+        if (a.registry) cfg.registry = String(a.registry);
+        const dir = needProfile(cfg);
+        cfg.logger.info('check updates in ' + dir);
+        const r = await checkUpdates(dir, cfg);
+        const items = a.onlyUpdatable ? r.items.filter((x) => x.state === 'updatable') : r.items;
+        return { profile: r.profile, registry: r.registry, summary: r.summary, items: items.map((x) => ({
+          name: x.name, declared: x.declared, resolved: x.resolved || '', candidate: x.candidate || '', state: x.state, reason: x.reason || ''
+        })) };
+      }
+    }));
+
+    sctx.tools.register(defineTool({
+      name: TOOL.snapshot,
+      description: 'Create, list or restore a snapshot of the current DSH profile manifests (package.json, pnpm-lock.yaml, pnpm-workspace.yaml). Snapshots live in the plugin data directory, carry an identity fingerprint and per-file hashes, and are the recovery point to use before upgrading plugins. Actions: create / list / restore.',
+      parameters: {
+        action: { type: 'string', enum: ['create', 'list', 'restore'], description: 'create a snapshot, list existing ones, or restore a named one.' },
+        name: { type: 'string', description: 'Snapshot name for action=restore, as returned by action=list.' }
+      },
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            action: { type: 'string' },
+            created: { type: 'string' },
+            restored: { type: 'array', items: { type: 'string' } },
+            warnings: { type: 'array', items: { type: 'string' } },
+            snapshots: {
+              type: 'array',
+              items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                  name: { type: 'string' },
+                  createdAt: { type: 'string' },
+                  deps: { type: 'number' },
+                  hasManifest: { type: 'boolean' }
+                }
+              }
+            }
+          }
+        },
+        render(args, value) {
+          if (value.action === 'list') {
+            const rows = (value.snapshots || []).map((s) => '- ' + s.name + '  ' + s.createdAt + '  deps ' + s.deps + (s.hasManifest ? '' : '  (无 manifest)'));
+            return renderLines('Snapshots', rows.length ? rows : ['- 还没有快照']);
+          }
+          if (value.action === 'restore') {
+            return renderLines('Restored from ' + value.created, [
+              'files: ' + (value.restored || []).join(', '),
+              ...(value.warnings || []).map((w) => 'warning: ' + w)
+            ]);
+          }
+          return renderLines('Snapshot created: ' + value.created, ['先记下这个名字，回滚时用它。']);
+        }
+      },
+      async execute(args) {
+        const a = args || {};
+        const dir = needProfile(cfg);
+        const action = String(a.action || 'list');
+        if (action === 'list') {
+          const list = listSnapshots(cfg).map((s) => ({
+            name: s.name,
+            createdAt: new Date(s.mtime).toISOString(),
+            deps: s.deps,
+            hasManifest: !!s.hasManifest
+          }));
+          return { action: 'list', snapshots: list };
+        }
+        if (action === 'create') {
+          const s = createSnapshot(dir, cfg);
+          cfg.logger.info('snapshot created: ' + s.name);
+          return { action: 'create', created: s.name };
+        }
+        if (action === 'restore') {
+          const nm = String(a.name || '').trim();
+          if (!nm) throw new Error('action=restore 需要提供 name（先执行 action=list 查看）');
+          const r = restoreSnapshot(dir, cfg, nm);
+          cfg.logger.warn('snapshot restored: ' + nm);
+          return { action: 'restore', created: r.from, restored: r.restored, warnings: r.warnings };
+        }
+        throw new Error('未知 action: ' + action + '（可用 create / list / restore）');
+      }
+    }));
+
+    sctx.tools.register(defineTool({
+      name: TOOL.doctor,
+      description: 'Static diagnostic of installed DeepSeek Harness plugins: declared vs installed vs enabled state, DSH version compatibility as declared by the author (explicit incompatible is reported as incompatible, never as compatible), duplicate cordis.patch.yml ids, native modules and unparseable manifests. Read-only; findings are static evidence, not runtime verification.',
+      parameters: {
+        dshVersion: { type: 'string', description: 'DSH version to judge compatibility against. Defaults to DSH_VERSION env or unknown.' },
+        limit: { type: 'number', description: 'Max conflicts to return (default 30).' }
+      },
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            profile: { type: 'string' },
+            dshVersion: { type: 'string' },
+            summary: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                installed: { type: 'number' },
+                enabled: { type: 'number' },
+                missing: { type: 'number' },
+                incompatible: { type: 'number' },
+                untested: { type: 'number' },
+                native: { type: 'number' }
+              }
+            },
+            conflicts: {
+              type: 'array',
+              items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                  severity: { type: 'string' },
+                  kind: { type: 'string' },
+                  message: { type: 'string' }
+                }
+              }
+            },
+            topPriority: {
+              type: 'array',
+              items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                  name: { type: 'string' },
+                  score: { type: 'number' },
+                  level: { type: 'string' }
+                }
+              }
+            }
+          }
+        },
+        render(args, value) {
+          const s = value.summary || {};
+          const head = 'installed ' + s.installed + ' | enabled ' + s.enabled + ' | missing ' + s.missing + ' | incompatible ' + s.incompatible + ' | untested ' + s.untested + ' | native ' + s.native;
+          const rows = (value.conflicts || []).map((c) => '- [' + c.severity + '] ' + c.kind + ': ' + c.message);
+          return renderLines('Plugin diagnostic (profile: ' + value.profile + ', DSH ' + value.dshVersion + ')', [head, ...(rows.length ? rows : ['- 未发现已知冲突'])]);
+        }
+      },
+      async execute(args) {
+        const a = args || {};
+        const dir = needProfile(cfg);
+        const dshVersion = String(a.dshVersion || process.env.DSH_VERSION || 'unknown');
+        const scan = scanPlugins(dir, dshVersion);
+        const conflicts = detectConflicts(scan.items);
+        const prior = scan.items
+          .map((it) => ({ name: it.name, ...priorityOf(it, conflicts) }))
+          .sort((x, y) => y.score - x.score)
+          .slice(0, 5)
+          .map((x) => ({ name: x.name, score: x.score, level: x.level }));
+        const limit = Math.max(1, Math.min(Number(a.limit) || 30, 200));
+        const summary = {
+          installed: scan.items.filter((x) => x.installed !== false).length,
+          enabled: scan.items.filter((x) => x.enabled).length,
+          missing: scan.items.filter((x) => x.installed === false).length,
+          incompatible: scan.items.filter((x) => (x.compatibility || {}).state === 'incompatible').length,
+          untested: scan.items.filter((x) => (x.compatibility || {}).state === 'untested').length,
+          native: scan.items.filter((x) => x.hasNative).length
+        };
+        return {
+          profile: scan.profile,
+          dshVersion,
+          summary,
+          conflicts: conflicts.slice(0, limit).map((c) => ({ severity: c.severity, kind: c.kind, message: c.message })),
+          topPriority: prior
+        };
+      }
+    }));
+
+    ctx.logger?.info?.('[dsh-plugin-snapshot] tools registered on ' + needProfileSafe(cfg));
+  });
+
+  function needProfileSafe(c) {
+    try { return resolveProfileDir(c) || '(未定位)'; } catch (e) { return '(未定位)'; }
+  }
+}
+

package/lib/profile.js

@@ -0,0 +1,95 @@
+/**
+ * profile 定位与解析。
+ * 插件运行在 DSH 进程内，profile 目录按「显式配置 > 环境变量 > 标准路径 > 扫描」的顺序确定，
+ * 任一步失败都不会抛异常，只返回 null 让上层给出可读错误。
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const PROFILE_FILES = ['package.json', 'pnpm-lock.yaml', 'pnpm-workspace.yaml'];
+
+export function profilesRoot() {
+  return join(homedir(), '.dsh', 'profiles');
+}
+
+/** 定位一个可用的 profile 目录 */
+export function resolveProfileDir(cfg) {
+  const cands = [];
+  if (cfg && typeof cfg.profileDir === 'string' && cfg.profileDir) cands.push(cfg.profileDir);
+  for (const k of ['DSH_PROFILE_DIR', 'DSH_PROFILE_PATH', 'DSH_PROFILE']) {
+    if (process.env[k]) cands.push(String(process.env[k]));
+  }
+  cands.push(join(profilesRoot(), 'desktop'));
+  try {
+    const base = profilesRoot();
+    const dirs = readdirSync(base, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => ({ dir: join(base, e.name), mtime: statSync(join(base, e.name)).mtimeMs }))
+      .sort((a, b) => b.mtime - a.mtime);
+    for (const d of dirs) cands.push(d.dir);
+  } catch (e) { /* 没有 profiles 目录 */ }
+  for (const c of cands) {
+    if (c && existsSync(join(c, 'package.json'))) return c;
+  }
+  return null;
+}
+
+/** 读 profile 清单与启用状态 */
+export function readProfile(dir) {
+  const p = join(dir, 'package.json');
+  if (!existsSync(p)) throw new Error('找不到 profile 清单: ' + p);
+  let manifest = null;
+  try { manifest = JSON.parse(readFileSync(p, 'utf8')); }
+  catch (e) { throw new Error('profile 清单无法解析: ' + p); }
+  const deps = (manifest && manifest.dependencies) || {};
+  const bundles = (manifest && manifest.dsh && manifest.dsh.profile && manifest.dsh.profile.bundles) || [];
+  return { path: p, manifest, deps, bundles, name: manifest.name || '' };
+}
+
+/** 从 pnpm-lock.yaml 的 importers 段读直接依赖的解析版本 */
+export function parseLockVersions(lockText) {
+  const out = {};
+  const lines = String(lockText || '').split(/\r?\n/);
+  let inImporters = false;
+  let inDeps = false;
+  let depIndent = -1;
+  let curName = null;
+  for (const raw of lines) {
+    if (/^importers:\s*$/.test(raw)) { inImporters = true; continue; }
+    if (inImporters && /^[a-zA-Z]/.test(raw)) { inImporters = false; continue; }
+    if (!inImporters) continue;
+    if (/^\s+dependencies:\s*$/.test(raw)) { inDeps = true; depIndent = raw.indexOf('dependencies:'); curName = null; continue; }
+    if (inDeps && /^\s+(devDependencies|optionalDependencies):\s*$/.test(raw)) { inDeps = false; continue; }
+    if (!inDeps) continue;
+    const indent = raw.length - raw.trimStart().length;
+    const t = raw.trim();
+    if (!t) continue;
+    if (indent === depIndent + 2 && /^[^:]+:\s*$/.test(t)) {
+      curName = t.slice(0, -1).trim().replace(/^['"]|['"]$/g, '');
+      continue;
+    }
+    if (curName && indent === depIndent + 4) {
+      const m = /^version:\s*(.+)$/.exec(t);
+      if (m) { out[curName] = m[1].trim().replace(/^['"]|['"]$/g, ''); curName = null; }
+    }
+  }
+  return out;
+}
+
+export function readLockVersions(dir) {
+  const p = join(dir, 'pnpm-lock.yaml');
+  if (!existsSync(p)) return {};
+  try { return parseLockVersions(readFileSync(p, 'utf8')); } catch (e) { return {}; }
+}
+
+/** 依赖的分类：registry / github / local */
+export function specKind(spec) {
+  const s = String(spec || '');
+  if (/^(github:|git\+https?:|https?:\/\/(codeload\.)?github\.com)/i.test(s)) return 'github';
+  if (/^(file:|link:|\.\/|\.\.\/)/.test(s)) return 'local';
+  return 'registry';
+}
+
+export { PROFILE_FILES };
+

package/lib/snapshot.js

@@ -0,0 +1,149 @@
+/**
+ * 快照：把 profile 的三份清单备份到插件自己的数据目录，支持列表与恢复。
+ * 设计要点（与外部工具版一致，都是踩过坑之后的结论）：
+ *  - 一份都没备份到就抛错，不返回空快照；
+ *  - 每份写 manifest（profile 指纹、创建时间、每文件摘要）；
+ *  - 清理时保护正在使用的快照，按创建时间排序；
+ *  - 恢复前校验 profile 身份，摘要不符只告警。
+ */
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { atomicWrite, sha256, tsStr, isValidSnapName, dataDir, readJson } from './util.js';
+
+const FILES = ['package.json', 'pnpm-lock.yaml', 'pnpm-workspace.yaml'];
+const MANIFEST = 'manifest.json';
+
+export function snapRoot(cfg) {
+  const base = (cfg && cfg.dataDir) ? cfg.dataDir : dataDir();
+  return join(base, 'snapshots');
+}
+
+function profileId(dir) {
+  return sha256(Buffer.from(String(dir))).slice(0, 16);
+}
+
+function uniqueDir(base) {
+  const stamp = tsStr();
+  let dir = join(base, stamp);
+  let i = 2;
+  while (existsSync(dir)) { dir = join(base, stamp + '-' + i); i++; }
+  return dir;
+}
+
+export function createSnapshot(profileDir, cfg) {
+  const base = snapRoot(cfg);
+  mkdirSync(base, { recursive: true });
+  const dir = uniqueDir(base);
+  mkdirSync(dir, { recursive: true });
+  const saved = [];
+  for (const f of FILES) {
+    const src = join(profileDir, f);
+    if (!existsSync(src)) continue;
+    copyFileSync(src, join(dir, f));
+    saved.push(f);
+  }
+  if (!saved.length) {
+    try { rmSync(dir, { recursive: true, force: true }); } catch (e) { /* 忽略 */ }
+    throw new Error('无法创建快照：profile 目录里没有任何清单文件（' + profileDir + '）');
+  }
+  const files = {};
+  for (const f of FILES) {
+    const p = join(profileDir, f);
+    if (!existsSync(p)) { files[f] = { exists: false }; continue; }
+    try { files[f] = { exists: true, size: statSync(p).size, sha256: sha256(readFileSync(p)) }; }
+    catch (e) { files[f] = { exists: false }; }
+  }
+  try {
+    atomicWrite(join(dir, MANIFEST), JSON.stringify({
+      profileId: profileId(profileDir),
+      profileDir,
+      createdAt: Date.now(),
+      created: tsStr(),
+      tool: 'dsh-plugin-snapshot',
+      files
+    }, null, 2));
+  } catch (e) { /* manifest 失败不影响恢复，只是少了身份校验 */ }
+  prune(cfg, [basename(dir)]);
+  return { name: basename(dir), dir, files: saved };
+}
+
+export function prune(cfg, protect) {
+  const base = snapRoot(cfg);
+  const keep = Math.max(1, Number((cfg && cfg.snapshotsKeep) || 7));
+  const prot = new Set((protect || []).map((x) => basename(String(x))));
+  let items = [];
+  try { items = readdirSync(base); } catch (e) { return; }
+  const timed = [];
+  for (const n of items) {
+    if (!isValidSnapName(n)) continue;
+    let ms = 0;
+    try { ms = statSync(join(base, n)).mtimeMs; } catch (e) { ms = 0; }
+    timed.push({ n, ms });
+  }
+  timed.sort((a, b) => a.ms - b.ms);
+  const snaps = timed.map((x) => x.n);
+  const queue = snaps.filter((n) => !prot.has(n));
+  let over = snaps.length - keep;
+  while (over > 0 && queue.length) {
+    const victim = queue.shift();
+    try { rmSync(join(base, victim), { recursive: true, force: true }); over--; } catch (e) { /* 忽略 */ }
+  }
+}
+
+export function listSnapshots(cfg) {
+  const base = snapRoot(cfg);
+  let items = [];
+  try { items = readdirSync(base); } catch (e) { return []; }
+  const out = [];
+  for (const name of items) {
+    if (!isValidSnapName(name)) continue;
+    const dir = join(base, name);
+    const man = readJson(join(dir, MANIFEST));
+    let mtime = 0;
+    try { mtime = statSync(dir).mtimeMs; } catch (e) { /* 忽略 */ }
+    if (man && man.createdAt) mtime = man.createdAt;
+    let deps = 0;
+    try { deps = Object.keys(JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).dependencies || {}).length; }
+    catch (e) { /* 忽略 */ }
+    out.push({ name, dir, mtime, deps, hasManifest: !!man, files: FILES.filter((f) => existsSync(join(dir, f))) });
+  }
+  out.sort((a, b) => b.mtime - a.mtime);
+  return out;
+}
+
+function resolveSnap(cfg, name) {
+  const base = basename(String(name || ''));
+  if (!isValidSnapName(base)) throw new Error('非法的快照名: ' + (base || '(空)'));
+  return join(snapRoot(cfg), base);
+}
+
+export function restoreSnapshot(profileDir, cfg, name) {
+  const dir = resolveSnap(cfg, name);
+  if (!existsSync(dir)) throw new Error('快照不存在: ' + dir);
+  const present = FILES.filter((f) => existsSync(join(dir, f)));
+  if (!present.length) throw new Error('快照目录内没有可恢复的文件: ' + dir);
+
+  const man = readJson(join(dir, MANIFEST));
+  if (man && man.profileId && man.profileId !== profileId(profileDir)) {
+    throw new Error('快照属于另一个 profile（' + String(man.profileDir || '?') + '），已拒绝恢复');
+  }
+  const warnings = [];
+  if (man && man.files) {
+    for (const f of present) {
+      const meta = man.files[f];
+      if (!meta || !meta.exists || !meta.sha256) continue;
+      try {
+        if (sha256(readFileSync(join(dir, f))) !== meta.sha256) warnings.push('快照文件与创建时摘要不一致: ' + f);
+      } catch (e) { /* 忽略 */ }
+    }
+  }
+
+  createSnapshot(profileDir, cfg);
+  const restored = [];
+  for (const f of present) {
+    copyFileSync(join(dir, f), join(profileDir, f));
+    restored.push(f);
+  }
+  return { restored, warnings, from: basename(dir) };
+}
+

package/lib/updates.js

@@ -0,0 +1,92 @@
+/**
+ * 版本检测：以 lockfile 的解析版本为准，去 registry 查候选版本。
+ * 只读操作，不写 profile、不安装任何东西。
+ */
+import { readProfile, readLockVersions, specKind } from './profile.js';
+import { parseSpec, parseSemver, cmpSemver, shortVer, isValidPkgName, Logger } from './util.js';
+
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+
+function registryOf(cfg) {
+  const r = String((cfg && cfg.registry) || process.env.DSH_REGISTRY || '').trim();
+  return (r || DEFAULT_REGISTRY).replace(/[/]+$/, '');
+}
+
+async function fetchLatest(name, cfg) {
+  if (!isValidPkgName(name)) return { ok: false, reason: '非法包名' };
+  const base = registryOf(cfg);
+  if (!/^https?:[/][/]/.test(base)) return { ok: false, reason: '非法的 registry 地址' };
+  try {
+    const res = await fetch(base + '/' + name + '/latest', {
+      signal: AbortSignal.timeout(Math.max(5000, Number((cfg && cfg.timeoutMs) || 20000))),
+      headers: { accept: 'application/json' }
+    });
+    if (res.status === 404) return { ok: false, reason: 'HTTP 404（包不存在）' };
+    if (!res.ok) return { ok: false, reason: 'HTTP ' + res.status };
+    const j = await res.json();
+    if (!j || !j.version) return { ok: false, reason: '响应缺少 version' };
+    return { ok: true, latest: j.version, engines: j.engines || null, dsh: j.dsh || null };
+  } catch (e) {
+    return { ok: false, reason: String((e && e.message) || e) };
+  }
+}
+
+async function mapLimit(items, limit, worker) {
+  const out = new Array(items.length);
+  let cursor = 0;
+  const runners = new Array(Math.max(1, Math.min(limit || 1, items.length))).fill(0).map(async () => {
+    while (true) {
+      const i = cursor++;
+      if (i >= items.length) return;
+      out[i] = await worker(items[i], i);
+    }
+  });
+  await Promise.all(runners);
+  return out;
+}
+
+export async function checkUpdates(profileDir, cfg) {
+  const prof = readProfile(profileDir);
+  const lock = readLockVersions(profileDir);
+  const names = Object.keys(prof.deps);
+  const targets = [];
+  const skipped = [];
+  for (const name of names) {
+    if (!isValidPkgName(name)) { skipped.push({ name, reason: '非法包名' }); continue; }
+    const kind = specKind(prof.deps[name]);
+    if (kind === 'local') { skipped.push({ name, reason: '本地依赖，不参与升级' }); continue; }
+    targets.push({ name, kind, declared: String(prof.deps[name]), resolved: lock[name] || '' });
+  }
+
+  const results = await mapLimit(targets, Math.max(1, Math.min(Number((cfg && cfg.concurrency) || 8), 16)), async (t) => {
+    if (t.kind === 'github') {
+      return { ...t, state: 'manual', reason: 'GitHub 源需人工确认，本工具不自动判定' };
+    }
+    const r = await fetchLatest(t.name, cfg);
+    if (!r.ok) return { ...t, state: 'failed', reason: r.reason };
+    const cur = parseSpec(t.resolved || t.declared);
+    const lat = parseSemver(r.latest);
+    if (!cur || !lat) return { ...t, state: 'unknown', reason: '版本号无法解析', candidate: r.latest };
+    if (lat.pre) return { ...t, state: 'prerelease', reason: '候选是预发布版本', candidate: r.latest };
+    if (cur.major !== lat.major) return { ...t, state: 'major', reason: '主版本变更，需人工确认', candidate: r.latest };
+    const c = cmpSemver(cur.base, r.latest);
+    return {
+      ...t,
+      candidate: r.latest,
+      state: (c !== null && c < 0) ? 'updatable' : 'uptodate',
+      reason: (c !== null && c < 0) ? '' : '',
+      shortResolved: shortVer(t.resolved || t.declared)
+    };
+  });
+
+  const summary = {
+    total: results.length,
+    updatable: results.filter((x) => x.state === 'updatable').length,
+    major: results.filter((x) => x.state === 'major').length,
+    uptodate: results.filter((x) => x.state === 'uptodate').length,
+    failed: results.filter((x) => x.state === 'failed').length,
+    skipped: skipped.length
+  };
+  return { items: results, skipped, summary, profile: prof.name, registry: registryOf(cfg) };
+}
+

package/lib/util.js

@@ -0,0 +1,131 @@
+/**
+ * 通用工具：原子写、摘要、语义化版本、路径与日志。
+ * 本文件不依赖 Electron / DSH 内部包，可在纯 Node 下被单测直接覆盖。
+ */
+import { appendFileSync, existsSync, mkdirSync, openSync, closeSync, fsyncSync, renameSync, unlinkSync, writeFileSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+
+/** 原子写：tmp -> fsync -> rename，中途失败不会留下半个文件 */
+export function atomicWrite(file, text) {
+  const tmp = file + '.tmp-' + Date.now() + '-' + Math.random().toString(36).slice(2, 8);
+  let fd = null;
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    fd = openSync(tmp, 'w');
+    writeFileSync(fd, text, 'utf8');
+    try { fsyncSync(fd); } catch (e) { /* 部分文件系统不支持 */ }
+    closeSync(fd);
+    fd = null;
+    renameSync(tmp, file);
+    return true;
+  } catch (e) {
+    if (fd !== null) { try { closeSync(fd); } catch (err) { /* 忽略 */ } }
+    try { if (existsSync(tmp)) unlinkSync(tmp); } catch (err) { /* 忽略 */ }
+    throw e;
+  }
+}
+
+export function sha256(buf) {
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+export function todayStr(d) {
+  const x = d || new Date();
+  return x.getFullYear() + '-' + pad(x.getMonth() + 1) + '-' + pad(x.getDate());
+}
+
+export function tsStr(d) {
+  const x = d || new Date();
+  return String(x.getFullYear()) + pad(x.getMonth() + 1) + pad(x.getDate()) + '-' + pad(x.getHours()) + pad(x.getMinutes()) + pad(x.getSeconds());
+}
+
+export function pad(n) { return String(n).padStart(2, '0'); }
+
+/** 合法的 npm 包名：可带 @scope/，只允许字母数字与 . _ - */
+export function isValidPkgName(n) {
+  if (typeof n !== 'string') return false;
+  const s = n.trim();
+  if (!s || s.length > 214) return false;
+  if (s.startsWith('.') || s.startsWith('-')) return false;
+  if (s.indexOf('..') >= 0 || s.indexOf(String.fromCharCode(92)) >= 0 || s.indexOf('/') === s.length - 1) return false;
+  if (/[\s\u0000]/.test(s)) return false;
+  return /^(@[a-zA-Z0-9][a-zA-Z0-9._-]*\/)?[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(s);
+}
+
+export function isValidSnapName(n) {
+  return typeof n === 'string' && /^[0-9]{8}-[0-9]{6}(-[0-9]+)?$/.test(n);
+}
+
+/** 解析 spec 里的语义化版本（支持 ^ ~ >= 前缀、v 前缀、prerelease、build、四段） */
+export function parseSpec(spec) {
+  if (typeof spec !== 'string') return null;
+  const m = /^([\^~>=<*\s]*?)v?(\d+)\.(\d+)\.(\d+)(?:\.\d+)?(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(spec.trim());
+  if (!m) return null;
+  return { prefix: m[1] || '', major: +m[2], minor: +m[3], patch: +m[4], pre: m[5] || null, base: m[2] + '.' + m[3] + '.' + m[4] + (m[5] ? '-' + m[5] : '') };
+}
+
+export function parseSemver(v) {
+  const s = parseSpec(v);
+  return s ? { major: s.major, minor: s.minor, patch: s.patch, pre: s.pre, raw: s.base } : null;
+}
+
+export function cmpSemver(a, b) {
+  const A = parseSemver(a), B = parseSemver(b);
+  if (!A || !B) return null;
+  for (const k of ['major', 'minor', 'patch']) {
+    if (A[k] !== B[k]) return A[k] < B[k] ? -1 : 1;
+  }
+  if (A.pre === null && B.pre === null) return 0;
+  if (A.pre === null) return 1;
+  if (B.pre === null) return -1;
+  const pa = A.pre.split('.'), pb = B.pre.split('.');
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const x = pa[i], y = pb[i];
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    const xn = /^\d+$/.test(x), yn = /^\d+$/.test(y);
+    if (xn && yn) { if (+x !== +y) return +x < +y ? -1 : 1; }
+    else if (xn) return -1;
+    else if (yn) return 1;
+    else if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+export function shortVer(spec) {
+  return String(spec == null ? '' : spec).replace(/^[\^~>=<\s]+/, '');
+}
+
+/** 数据目录：只写用户目录下的独立子目录，不碰 profile */
+export function dataDir() {
+  return join(homedir(), '.dsh-plugin-snapshot');
+}
+
+/** 极简日志器：写本插件自己的目录，失败不抛 */
+export class Logger {
+  constructor(dir) {
+    this.dir = dir || join(dataDir(), 'logs');
+    this.file = join(this.dir, 'snapshot-' + todayStr() + '.log');
+    this.lines = [];
+  }
+  write(level, msg) {
+    const line = '[' + new Date().toISOString() + '] [' + level + '] ' + msg;
+    this.lines.push(line);
+    if (this.lines.length > 200) this.lines.shift();
+    try {
+      mkdirSync(this.dir, { recursive: true });
+      appendFileSync(this.file, line + '\n', 'utf8');
+    } catch (e) { /* 只影响日志，不影响功能 */ }
+  }
+  info(m) { this.write('info', m); }
+  warn(m) { this.write('warn', m); }
+  error(m) { this.write('error', m); }
+  tail(n) { return this.lines.slice(-(n || 20)); }
+}
+
+export function readJson(file) {
+  try { return JSON.parse(readFileSync(file, 'utf8')); } catch (e) { return null; }
+}
+

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "dsh-plugin-snapshot",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Pre-update snapshots, one-step rollback and conflict diagnostics for DeepSeek Harness profile plugins.",
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "snapshot",
+    "rollback",
+    "plugin-manager",
+    "diagnostics"
+  ],
+  "author": "YG",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Uesccda/dsh-plugin-snapshot.git"
+  },
+  "homepage": "https://github.com/Uesccda/dsh-plugin-snapshot#readme",
+  "bugs": {
+    "url": "https://github.com/Uesccda/dsh-plugin-snapshot/issues"
+  },
+  "main": "lib/index.js",
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "README.en.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "compatibility": {
+      "dshReleases": {
+        "0.2.2-rc.1": "compatible",
+        "0.2.1": "compatible",
+        "0.2.0+": "compatible"
+      }
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-tools": ">=0.1.7-rc.1 <0.4.0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/plugin.test.mjs",
+    "smoke": "node test/smoke.mjs"
+  }
+}