dsh-plugin-snapshot 0.0.0-stage → 0.1.0

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,45 @@
+# dsh-plugin-snapshot
+
+Pre-upgrade snapshots, one-step rollback and a static health check for DeepSeek Harness plugins.
+
+The built-in plugin_manager already installs, removes and toggles plugins. This plugin adds what it does not: a verifiable recovery point before you change anything, a way back when an upgrade goes wrong, and a clear view of which plugins collide.
+
+## Install
+
+    dsh plugin add dsh-plugin-snapshot
+
+Restart DSH (or let HMR pick it up), then the three tools are available.
+
+## Tools
+
+### plugin_snapshot
+
+Create, list and restore snapshots of the profile manifests (package.json, pnpm-lock.yaml, pnpm-workspace.yaml).
+
+Every snapshot carries a manifest with the profile fingerprint, creation time, and per-file 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.
+
+### plugin_updates
+
+Read-only version check. Compares the version resolved in pnpm-lock.yaml against the registry and reports updatable / major / uptodate / prerelease / failed / manual. Prereleases are never suggested, and GitHub sources are always flagged for manual review.
+
+### plugin_doctor
+
+Static diagnostic: declared vs installed vs enabled, author-declared DSH compatibility (an explicit incompatible is reported as incompatible, never as probably fine), duplicate cordis.patch.yml ids, missing packages and unparseable manifests. The returned priority is a rule-weighted score, not a crash probability.
+
+## Where data lives
+
+    ~/.dsh-plugin-snapshot/snapshots/<timestamp>/
+    ~/.dsh-plugin-snapshot/logs/
+
+Nothing else is written except the three profile manifests on restore. node_modules and the bundles list are never touched, and DSH is never started or stopped.
+
+## 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,86 @@
-# Temporary Holding Version
+# dsh-plugin-snapshot
+
+给 DeepSeek Harness 的插件做**升级前快照、一键回滚和静态体检**。
+
+DSH 官方的 plugin_manager 已经能装、卸、启停插件；本插件只补它没有的那一块：**改动之前先存一份能验身份的恢复点，出问题能退回来，装完之后能看清谁跟谁冲突**。
+
+## 为什么需要它
+
+插件升级失败时最难受的不是报错，而是"清单已经改了、依赖没装完、不知道回到了什么状态"。本插件在每次升级前把 profile 的三份清单（package.json / pnpm-lock.yaml / pnpm-workspace.yaml）存成一份带指纹与哈希的快照，任何时候都能退回去。
+
+## 安装
+
+    dsh plugin add dsh-plugin-snapshot
+
+装好后重启 DSH（或启用 HMR 时自动生效），三个工具随即可用。
+
+## 提供的工具
+
+### plugin_snapshot
+
+快照的创建、列表与恢复。
+
+- action = "create"：把当前 profile 的三份清单存成一份快照，返回快照名
+- action = "list"：列出全部快照（时间、依赖数、是否带 manifest）
+- action = "restore" + name：恢复到指定快照；恢复前会先自动给现状再存一份
+
+每份快照都带 manifest：profile 指纹、创建时间、每个文件的存在性与 sha256。恢复时会先校验指纹——**别的 profile 的快照会被拒绝**；文件摘要对不上只告警（你可能手工改过清单）。
+
+### plugin_updates
+
+只读的版本检测。
+
+- 以 pnpm-lock.yaml 里解析出来的版本为基准，去 registry 查候选版本
+- 输出每个插件的状态：updatable / major / uptodate / prerelease / failed / manual
+- 预发布版本不会被建议升级；主版本变更、GitHub 源一律标成需人工确认
+
+### plugin_doctor
+
+静态体检。
+
+- 已声明 vs 已安装 vs 已启用，三者分开列
+- 按插件作者声明判定 DSH 版本兼容性：**明确写 incompatible 的判成不兼容，绝不显示成"大概率可用"**
+- 重复的 cordis.patch.yml 行 id、缺失的包、无法解析的清单
+- 给出"检查优先级"（规则加权，不是崩溃概率）
+
+## 数据放在哪
+
+    ~/.dsh-plugin-snapshot/snapshots/<时间戳>/
+    ~/.dsh-plugin-snapshot/logs/
+
+只写这两个目录，以及恢复时写回 profile 的三份清单。不碰 node_modules，不改 bundles 清单，不启动或关闭 DSH。
+
+## 安全边界
+
+- plugin_updates 与 plugin_doctor 是**纯只读**：只读文件、只发 GET 请求
+- plugin_snapshot 的 create 只写自己的数据目录；restore 需要显式传 name，且只覆盖三份清单
+- 不实现安装/卸载/启停——那是官方 plugin_manager 的职责，避免两套实现互相打架
+
+## 配置
+
+可选，写进 profile 的插件配置：
+
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| profileDir | 自动定位 | 显式指定 profile 目录 |
+| registry | registry.npmjs.org | 检测用的源，也可用 DSH_REGISTRY |
+| dataDir | ~/.dsh-plugin-snapshot | 快照与日志目录 |
+| snapshotsKeep | 7 | 保留份数 |
+| concurrency | 8 | 检测并发 |
+
+profile 定位顺序：配置 > 环境变量 DSH_PROFILE_DIR > ~/.dsh/profiles/desktop > 扫描 profiles 目录取最近修改的。
+
+## 已知限制
+
+- 快照只覆盖三份清单，不含 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,53 @@
 {
   "name": "dsh-plugin-snapshot",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "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"
+    }
+  },
+  "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"
+  }
+}