dsh-m 0.2.14 → 0.4.0

package/lib/core/toggle.js

@@ -0,0 +1,220 @@
+/**
+ * 开关写路径编排（0.4.0，plan Task 5；ADR-0001 委派降级）。
+ *
+ * 判定顺序（Rev2.1 定稿）：
+ * ① 保护门最先（纯名单检查，无需枚举已装清单——空 profile 下 CLI 冒烟也得 protected）；
+ * ② 不在已装清单 → not-installed；
+ * ③ 粒度路由：单 insert 行插件 → 行覆盖；多行/不可解析 → Bundle 选择；
+ * ④ 委派优先：`getService()` 探测官方 pluginManager（运行时探测，不判版本号），
+ *    官方 readOnlyReason 映射：'management-required'→protected、'unaddressable'→unaddressable；
+ *    applied 以复读为准（官方富结果 application 字段鸭子读兜底）；
+ * ⑤ 降级：行级 = 锁内保注释 YAML 编辑 + `setLivePluginDisabled(pkg, !enabled)` 活体
+ *    （注意 live-plugin.ts 第二参是 disabled，方向取反）；bundle 级 = 锁内 bundles 数组
+ *    编辑，恒 restart-required。
+ *
+ * 锁：与官方同款 `withFileLock(<profile>/package.json)`（dsh-atomic-write，锁文件
+ * `package.json.lock`、wx 独占）——防与官方 UI 并发编辑 cordis.patch.yml 丢更新。
+ * 开关不经 Profile 变更事务（grilling Q1）：单文件轻量编辑、幂等可逆。
+ */
+import { readFile as fsReadFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
+import { listInstalledPlugins } from './installed.js';
+import { isSingleRowPlugin, planRowOverride } from './patch-yaml.js';
+import { PROTECTED_MODULES } from './enablement.js';
+import { setLivePluginDisabled, loaderHost } from './live-plugin.js';
+import { webProfileDir } from './env.js';
+export class ToggleError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/** 官方 change() 富结果的鸭子读（不建类型依赖）。 */
+function applicationOf(result) {
+    if (result && typeof result === 'object') {
+        const record = result;
+        return {
+            application: typeof record.application === 'string' ? record.application : undefined,
+            warnings: Array.isArray(record.warnings) ? record.warnings.map((w) => String(w)) : [],
+        };
+    }
+    return { warnings: [] };
+}
+async function readPatchText(io, path) {
+    try {
+        return await io.readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return '[]\n';
+        throw error;
+    }
+}
+export async function togglePlugin(pkg, enabled, deps = {}) {
+    const key = String(pkg || '').trim();
+    // ① 保护门最先：纯名单检查（空 profile 也先于 not-installed 命中）
+    if (key === 'dsh-m' || PROTECTED_MODULES.includes(key)) {
+        throw new ToggleError('protected', `受保护插件不可开关: ${key}（dsh-m 自身或官方宿主命脉）`);
+    }
+    const io = deps.io ?? { readFile: fsReadFile };
+    const profileDir = deps.profileDir ?? webProfileDir();
+    // ② 在装判定
+    const installed = await listInstalledPlugins(profileDir);
+    const item = installed.items.find((it) => it.pkg === key);
+    if (item === undefined)
+        throw new ToggleError('not-installed', `web profile 未安装该插件: ${key}`);
+    const granularity = item.patchRows && isSingleRowPlugin(item.patchRows) ? 'row' : 'bundle';
+    const service = deps.getService?.();
+    if (service !== undefined) {
+        // 委派一律走 Bundle 选择（官方插件页主开关同层，两层 UI 状态一致；
+        // 行覆盖残留由启用路径的清理扫描兜底）。行覆盖仅是降级路径的实现细节。
+        return toggleViaService(service, item, enabled);
+    }
+    // 降级：Bundle 退选态的「启用」必须走 bundles 编辑（行覆盖救不回未合成的树）
+    let inBundles = false;
+    try {
+        const manifest = JSON.parse(await io.readFile(join(profileDir, 'package.json'), 'utf8'));
+        const bundles = manifest?.dsh?.profile?.bundles;
+        inBundles = Array.isArray(bundles) && bundles.includes(item.pkg);
+    }
+    catch {
+        /* 读不到按不在 bundles 处理 */
+    }
+    const route = enabled && !inBundles ? 'bundle' : granularity;
+    return toggleFallback(item, enabled, route, { profileDir, io, loaderHost: deps.loaderHost ?? loaderHost() });
+}
+// ---------- 委派路径 ----------
+async function toggleViaService(service, item, enabled) {
+    const warnings = [];
+    // 启用前清理本插件的历史行覆盖（dsh-m 单开关模型：行覆盖是它自己写下的，
+    // 不清则 bundle 重选后旧行仍 disabled，官方页第二层会出现一开一关）
+    if (enabled) {
+        const cleared = await clearRowOverrides(service, item.pkg, warnings);
+        if (cleared > 0)
+            warnings.push(`已清理 ${cleared} 条历史行覆盖`);
+    }
+    const raw = await service.setBundleEnabled(item.pkg, enabled);
+    const rich = applicationOf(raw);
+    warnings.push(...rich.warnings);
+    if (enabled) {
+        // selectBundle 后才可见的行覆盖（bundle 退选期 loader 无条目）再扫一遍
+        await clearRowOverrides(service, item.pkg, warnings);
+    }
+    // applied 复读：bundle on → 该模块行应存在且启用；bundle off → 行消失或全禁用
+    const after = (await service.listPlugins()).filter((r) => r.moduleName === item.pkg);
+    const running = after.some((r) => r.enabled);
+    let applied;
+    if (rich.application === 'restart-required')
+        applied = 'restart-required';
+    else
+        applied = running === enabled ? 'live' : 'restart-required';
+    if (rich.application === 'overridden')
+        warnings.push('被更高补丁层覆盖，落盘状态与请求不符——重启后以下层为准');
+    return { pkg: item.pkg, enabled, applied, via: 'delegate', warnings };
+}
+/** 清理本插件可见的 disabled 行覆盖（跳过官方 readOnly 行）；返回清理条数。 */
+async function clearRowOverrides(service, pkg, warnings) {
+    const rows = (await service.listPlugins()).filter((r) => r.moduleName === pkg && !r.readOnlyReason && r.enabled === false);
+    let cleared = 0;
+    for (const row of rows) {
+        const rich = applicationOf(await service.setPluginEnabled(row.entryId, true));
+        warnings.push(...rich.warnings);
+        cleared += 1;
+    }
+    return cleared;
+}
+async function toggleFallback(item, enabled, granularity, ctx) {
+    if (granularity === 'row') {
+        return toggleRowFallback(item, enabled, ctx);
+    }
+    return toggleBundleFallback(item, enabled, ctx);
+}
+/** 行覆盖降级：锁内保注释 YAML 编辑 + loader 活体翻转。 */
+async function toggleRowFallback(item, enabled, ctx) {
+    const loaderEntry = findLoaderEntryByName(ctx.loaderHost, item.pkg);
+    const insert = item.patchRows?.readable ? item.patchRows.inserts[0] : undefined;
+    const id = loaderEntry?.id ?? insert?.id;
+    const name = loaderEntry?.options?.name ?? insert?.name;
+    if (id === undefined || id === '') {
+        throw new ToggleError('unknown-plugin', `无法定位该插件的合成条目 id（loader 与补丁行均无）: ${item.pkg}`);
+    }
+    const patchPath = join(ctx.profileDir, 'cordis.patch.yml');
+    let liveFound = false;
+    await withFileLock(join(ctx.profileDir, 'package.json'), async () => {
+        const text = await readPatchText(ctx.io, patchPath);
+        const plan = planRowOverride(text, id, name, enabled);
+        if (plan.changed) {
+            await writeFileAtomic(patchPath, plan.text, { mode: 0o600 });
+        }
+    });
+    liveFound = await setLivePluginDisabled(item.pkg, !enabled, ctx.loaderHost);
+    return {
+        pkg: item.pkg,
+        enabled,
+        applied: liveFound ? 'live' : 'restart-required',
+        via: 'fallback',
+        warnings: [],
+    };
+}
+function findLoaderEntryByName(host, pkg) {
+    const entries = host?.loader?.entries;
+    if (typeof entries !== 'function')
+        return null;
+    for (const entry of entries.call(host.loader)) {
+        if (entry && entry.options?.name === pkg)
+            return entry;
+    }
+    return null;
+}
+/** Bundle 选择降级：锁内 bundles 数组编辑（恒 restart-required）。 */
+async function toggleBundleFallback(item, enabled, ctx) {
+    const manifestPath = join(ctx.profileDir, 'package.json');
+    await withFileLock(join(ctx.profileDir, 'package.json'), async () => {
+        if (enabled) {
+            // 启用即清本包历史行覆盖（与委派路径同语义）
+            const patchPath = join(ctx.profileDir, 'cordis.patch.yml');
+            let patchText = '[]\n';
+            try {
+                patchText = await ctx.io.readFile(patchPath, 'utf8');
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            let patchMutated = false;
+            for (const insert of item.patchRows?.inserts ?? []) {
+                const plan = planRowOverride(patchText, insert.id, insert.name, true);
+                if (plan.changed) {
+                    patchText = plan.text;
+                    patchMutated = true;
+                }
+            }
+            if (patchMutated)
+                await writeFileAtomic(patchPath, patchText, { mode: 0o600 });
+        }
+        let raw;
+        try {
+            raw = await ctx.io.readFile(manifestPath, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                raw = '{}';
+            else
+                throw error;
+        }
+        const doc = JSON.parse(raw);
+        if (typeof doc.dsh !== 'object' || doc.dsh === null)
+            doc.dsh = {};
+        if (typeof doc.dsh.profile !== 'object' || doc.dsh.profile === null)
+            doc.dsh.profile = {};
+        const previous = Array.isArray(doc.dsh.profile.bundles) ? doc.dsh.profile.bundles : [];
+        const bundles = enabled
+            ? previous.includes(item.pkg) ? previous : [...previous, item.pkg]
+            : previous.filter((name) => name !== item.pkg);
+        doc.dsh.profile.bundles = bundles;
+        await writeFileAtomic(manifestPath, `${JSON.stringify(doc, null, 2)}\n`, { mode: 0o600 });
+    });
+    return { pkg: item.pkg, enabled, applied: 'restart-required', via: 'fallback', warnings: [] };
+}

package/lib/core/versions.js

@@ -18,43 +18,56 @@ function githubRateLimitMessage(err) {
     }
     return null;
 }
+/** registry base 归一（去尾斜杠；空/缺省 → 官方 npmjs）。 */
+function registryBase(registry) {
+    const base = typeof registry === 'string' && registry.trim() !== '' ? registry.trim() : 'https://registry.npmjs.org';
+    return base.replace(/\/+$/, '');
+}
 /** 精确 semver：接受 prerelease/build metadata，拒绝 v 前缀、range、tag 与脏尾缀。 */
 const EXACT_VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
 export function isExactVersion(version) {
     return EXACT_VERSION_RE.test(version);
 }
 /** 读取该精确版本的 dist metadata（不使用 /latest endpoint）；integrity 缺失由调用方拒绝安装。 */
-export async function npmVersion(pkg, version, timeoutMs = 20_000, signal) {
+export async function npmVersion(pkg, version, timeoutMs = 20_000, signal, registry) {
     if (!/^@?[A-Za-z0-9-._~]+(\/[A-Za-z0-9-._~]+)?$/.test(pkg))
         throw new Error(`无效 npm 包名: ${pkg}`);
     if (!isExactVersion(version))
         throw new Error(`不是精确版本（拒绝 range/tag/前缀）: ${version}`);
-    const data = await fetchJsonLimited(`https://registry.npmjs.org/${encodeURIComponent(pkg)}/${version}`, { timeoutMs, signal });
+    const data = await fetchJsonLimited(`${registryBase(registry)}/${encodeURIComponent(pkg)}/${version}`, { timeoutMs, signal });
     const resolved = typeof data.version === 'string' ? data.version : '';
     if (!resolved)
         throw new Error(`npm 未返回版本: ${pkg}@${version}`);
+    const peers = {};
+    if (data.peerDependencies !== null && typeof data.peerDependencies === 'object') {
+        for (const [name, range] of Object.entries(data.peerDependencies)) {
+            if (typeof range === 'string')
+                peers[name] = range;
+        }
+    }
     return {
         version: resolved,
         integrity: typeof data.dist?.integrity === 'string' ? data.dist.integrity : undefined,
         tarball: typeof data.dist?.tarball === 'string' ? data.dist.tarball : undefined,
+        peers,
     };
 }
 /**
  * 拉取完整 packument（NO_MATCHING_VERSION 退避重试前的预热/校验原语）。
  * 返回该包已知的全部版本号；解析不出 versions 时返回空列表（不抛）。
  */
-export async function npmPackument(pkg, timeoutMs = 20_000, signal) {
+export async function npmPackument(pkg, timeoutMs = 20_000, signal, registry) {
     if (!/^@?[A-Za-z0-9-._~]+(\/[A-Za-z0-9-._~]+)?$/.test(pkg))
         throw new Error(`无效 npm 包名: ${pkg}`);
     const data = await fetchJsonLimited(`https://registry.npmjs.org/${encodeURIComponent(pkg)}`, { timeoutMs, signal, maxBytes: 8 * 1024 * 1024 });
     const versions = data?.versions !== null && typeof data?.versions === 'object' ? Object.keys(data.versions) : [];
     return { versions };
 }
-export async function npmLatest(pkg, timeoutMs = 20_000, signal) {
+export async function npmLatest(pkg, timeoutMs = 20_000, signal, registry) {
     // 允许 scoped 包名：@scope/name（isSafePkgName 同款字符集）
     if (!/^@?[A-Za-z0-9-._~]+(\/[A-Za-z0-9-._~]+)?$/.test(pkg))
         throw new Error(`无效 npm 包名: ${pkg}`);
-    const data = await fetchJsonLimited(`https://registry.npmjs.org/${encodeURIComponent(pkg)}/latest`, { timeoutMs, signal });
+    const data = await fetchJsonLimited(`${registryBase(registry)}/${encodeURIComponent(pkg)}/latest`, { timeoutMs, signal });
     const version = typeof data.version === 'string' ? data.version : '';
     if (!version)
         throw new Error(`npm 未返回版本: ${pkg}`);

package/lib/host.js

@@ -3,44 +3,121 @@ import Schema from '@deepseek-ai/schemastery';
 import { createApiDispatcher } from './core/host-api.js';
 import { bindLoaderHost } from './core/live-plugin.js';
 import { createRegistryController } from './core/registry-controller.js';
+import { wireRegistrySettings, unwrapConfig, unwrapProbeConfig, detectSettingsKind, ownEntryId } from './core/settings-compat.js';
 import { registerTools } from './tools.js';
 import { appExitFromContext, scheduleRestart } from './core/restart.js';
+import { RegistryProbe } from './core/registry-probe.js';
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
 export const name = 'dshm';
 // dshm_* 七个工具（src/tools.ts）
 export const inject = ['tools'];
+/**
+ * 0.1.7+ 的 DSH schemastery 才有 `.volatile()`（标记字段进自动生成设置页 + loader 原地提交）；
+ * 旧版（≤0.1.5，schemastery 3.18.2）缺方法时保持普通字段——旧 settings API 的 scope 自带 live 语义。
+ * `volatile()` 幂等性：重复包裹会 throw，这里每字段只调一次。
+ */
+function live(field) {
+    const volatile = field.volatile;
+    return typeof volatile === 'function' ? volatile.call(field) : field;
+}
 export const Config = Schema.object({
-    registryUrl: Schema.string().description('registry 地址：空值使用默认官方清单；支持 HTTPS URL、loopback HTTP URL 或本机绝对路径/file://（整体覆盖默认清单，live 生效）'),
-    timeoutMs: Schema.number().default(20000).description('上游请求超时（毫秒）'),
-    cacheTtlMin: Schema.number().default(60).description('registry 缓存时长（分钟）'),
+    registryUrl: live(Schema.string().description('registry 地址：空值使用默认官方清单；支持 HTTPS URL、loopback HTTP URL 或本机绝对路径/file://（整体覆盖默认清单，live 生效）')),
+    timeoutMs: live(Schema.number().default(20000).description('上游请求超时（毫秒）')),
+    cacheTtlMin: live(Schema.number().default(60).description('registry 缓存时长（分钟）')),
+    probeEnabled: live(Schema.boolean().default(true).description('元数据源竞速探测：npmjs 与 npmmirror ping 并发，首个 2xx 胜出；只影响 dsh-m 元数据读取源与市场页展示，不影响安装链路')),
+    probeTimeoutMs: live(Schema.number().default(1500).description('竞速探测单侧超时（毫秒）')),
+    probeCacheTtlMin: live(Schema.number().default(5).description('竞速探测结果缓存时长（分钟）')),
 });
 export function apply(ctx, config) {
     // 卸载前的 live-disable 依赖 loader（skillhub 同款）
     bindLoaderHost(ctx);
     // registry controller：active config / configured / pending / rejected 分离 + generation fence；
-    // tools 与 Host API 共用同一 active config object（apply 原地更新字段，live 生效）
-    const controller = createRegistryController(config);
-    // DSH 0.1.2-rc.1 and 0.1.5-rc.1 both expose appExit through dsh-cmdline;
+    // tools 与 Host API 共用同一 active config object（apply 原地更新字段，live 生效）。
+    // unwrapConfig：0.1.7 上 volatile 字段是 cosmokit Volatile 引用，先解包成 plain 值再进 controller。
+    const controller = createRegistryController(unwrapConfig(config));
+    // DSH 0.1.2-rc.1 / 0.1.5-rc.1 / 0.1.7-rc.1 / 0.1.7-rc.2 都经 dsh-cmdline 暴露 appExit；
     // using it avoids guessing the service unit from release-specific cgroups.
     const appExit = appExitFromContext(ctx);
     const restart = (port = null) => scheduleRestart(port, { appExit });
+    // 元数据源竞速探测（Task 7/14）：timeoutMs 取启动时配置（实例持有缓存，改参数重启生效）；
+    // probeEnabled 每次调用实时读取（设置页关掉立即生效）。
+    const probe = new RegistryProbe({
+        timeoutMs: unwrapProbeConfig(config).probeTimeoutMs ?? 1500,
+        cacheTtlMs: (unwrapProbeConfig(config).probeCacheTtlMin ?? 5) * 60_000,
+    });
+    const probeLike = {
+        fastest: () => {
+            if (unwrapProbeConfig(config).probeEnabled === false)
+                return Promise.resolve(null);
+            return probe.fastest();
+        },
+    };
+    // 开关委派的官方服务探测（ADR-0001）：运行时按服务存在性探测，不判 DSH 版本号
+    const getService = () => ctx.get?.('pluginManager');
     registerTools(ctx, controller.config, { restart });
-    // 设置页（GUI 设置卡片的宿主命名空间）：applies 'live'，scope 提供 get/update/watch
+    // 设置页接线（双代兼容，详见 core/settings-compat.ts）：
+    // - ≤0.1.5：settings.register('dshm', …) scope（get/update/watch）；
+    // - 0.1.7-rc.1 / rc.2：Config `.volatile()` 字段自动生成设置页（autoGenerate 默认开，无需 configure），
+    //   读 = loader 解析的 Config 引用，写 = settings.update(ns, patch)，通知 = loader/volatile-update；
+    // - 其他形态：降级 cordis 配置文件通路。任何失败只 warn，不拖垮 webServer / tools。
+    // probe 配置写入口（Task 18 Rev）：forms 形态走 settings.update（落盘 + 活体）；
+    // legacy/其余形态就地改 config（probeLike 每次调用现读，活体生效但不保证持久化）。
+    let probeWriter = null;
     ctx.inject(['settings'], (c) => {
         const settings = c.settings;
-        const scope = settings.register('dshm', Config, { base: config, applies: 'live' });
-        const store = {
-            get: () => scope.get(),
-            update: (patch) => scope.update(patch),
-            watch: (callback) => scope.watch(callback),
-        };
-        controller.attachStore(store);
+        if (detectSettingsKind(settings) === 'forms') {
+            const ns = ownEntryId(ctx, pkg.name);
+            if (ns !== undefined) {
+                const forms = settings;
+                probeWriter = async (patch) => { await forms.update(ns, patch); };
+            }
+        }
+        if (probeWriter === null) {
+            probeWriter = async (patch) => {
+                const target = config;
+                for (const [k, v] of Object.entries(patch))
+                    target[k] = v;
+            };
+        }
+        try {
+            const outcome = wireRegistrySettings({
+                ctx,
+                settings,
+                schema: Config,
+                parsedConfig: config,
+                packageName: pkg.name,
+                logger: ctx.logger,
+                attachStore: (store) => controller.attachStore(store),
+            });
+            if (outcome === 'legacy' || outcome === 'forms') {
+                ctx.logger?.debug?.('dsh-m: settings store attached (%s)', outcome);
+            }
+        }
+        catch (err) {
+            ctx.logger?.warn?.('dsh-m: settings 集成失败，registry 地址走 cordis 配置文件');
+            ctx.logger?.warn?.(err);
+        }
     });
     // 本地 API：单路由 + method 分发（防护与状态映射在 core/host-api.ts）
     ctx.inject(['webServer'], (c) => {
         const server = c.webServer;
-        const handleApi = createApiDispatcher({ controller, pkg, deps: { scheduleRestart: restart } });
+        const handleApi = createApiDispatcher({
+            controller,
+            pkg,
+            deps: {
+                scheduleRestart: restart,
+                probe: probeLike,
+                probeSnapshot: () => probe.cachedSnapshot(),
+                getService,
+                probeConfigGet: () => unwrapProbeConfig(config),
+                probeConfigSet: async (patch) => {
+                    if (!probeWriter)
+                        throw new Error('设置服务缺席，probe 配置仅可经 cordis 配置文件修改');
+                    await probeWriter(patch);
+                },
+            },
+        });
         server.register({
             kind: 'exact',
             path: '/dshm',

package/lib/tools.js

@@ -2,6 +2,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools';
 import { installTimeoutMs } from './core/env.js';
 import { installFromRegistry, listInstalledWithMeta, listMarket, uninstallPlugin, upgradePlugin, } from './core/market.js';
 import { appExitFromContext, scheduleRestart } from './core/restart.js';
+import { togglePlugin as coreTogglePlugin } from './core/toggle.js';
 export const CATEGORY_LABELS = {
     market: '市场',
     tools: '工具',
@@ -25,6 +26,9 @@ export function registerTools(ctx, cfg, deps = {}) {
         upgradePlugin: deps.upgradePlugin ?? upgradePlugin,
     };
     const restart = deps.restart ?? ((port = null) => scheduleRestart(port, { appExit: appExitFromContext(ctx) }));
+    const toggle = deps.togglePlugin ?? coreTogglePlugin;
+    // 开关委派服务探测（ADR-0001）：运行时按存在性，不判版本号
+    const getService = () => ctx.get?.('pluginManager');
     ctx.tools.register(defineTool({
         name: 'dshm_search',
         description: 'Search your personal DSH plugin marketplace (dsh-m) and show clickable plugin cards. ALWAYS call this instead of web_search or bash when the user wants to find/recommend/browse their curated DSH plugins (插件). Call EXACTLY ONCE per user message; extract a real keyword (主题, 搜索) rather than pasting the whole sentence. Omit query to browse all listings. After cards appear, reply with AT MOST one short sentence. Do not print install commands.',
@@ -130,10 +134,11 @@ export function registerTools(ctx, cfg, deps = {}) {
     }));
     ctx.tools.register(defineTool({
         name: 'dshm_install',
-        description: 'Install a plugin from the dsh-m registry into the current web profile after the user names one (装 dsh-skins / 安装 web-search). Pass the id from dshm_search results. npm 源锁定最新精确版本，github 源锁定 commit SHA。Do not print CLI commands. After success, tell the user it needs a restart of dsh web, and offer dshm_restart.',
+        description: 'Install a plugin from the dsh-m registry into the current web profile after the user names one (装 dsh-skins / 安装 web-search). Pass the id from dshm_search results. npm 源锁定最新精确版本，github 源锁定 commit SHA。安装前做 peer 兼容预检（只检 @deepseek-ai/dsh(-*)；github 源不预检）：不兼容时返回结构化结果，向用户说明风险，用户确认后带 force: true 重试（force 等价 forceIncompatible）。Do not print CLI commands. After success, tell the user it needs a restart of dsh web, and offer dshm_restart.',
         parameters: {
             id: { type: 'string', required: true, description: '收录 id from dshm_search, e.g. dsh-skins' },
             version: { type: 'string', description: 'Optional exact semver (npm 源). Default latest.' },
+            force: { type: 'boolean', description: '用户已确认兼容风险后重试时置 true（跳过 peer 预检拦截）。' },
         },
         output: {
             schema: { type: 'object', additionalProperties: true },
@@ -152,7 +157,40 @@ export function registerTools(ctx, cfg, deps = {}) {
             if (!id)
                 throw new Error('缺少收录 id');
             const version = typeof args.version === 'string' && args.version.trim() ? args.version.trim() : undefined;
-            return cloneJson(await m.installFromRegistry(id, cfg, { version, namespace: 'host' }));
+            const force = args.force === true;
+            return cloneJson(await m.installFromRegistry(id, cfg, { version, forceIncompatible: force, namespace: 'host' }));
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'dshm_toggle',
+        description: 'Toggle a DSH plugin on/off (切换运行状态). Pass pkg from dshm_list and enabled (true=启用 / false=停用). 可逆操作：默认先与用户确认；用户同一句消息已明确表达（如「把 skins 关掉」）可直接执行。结果 applied=live 时告知已即时生效；restart-required 时提示需重启并提供 dshm_restart。受保护插件（dsh-m 自身与官方宿主命脉）会被拒绝。',
+        parameters: {
+            pkg: { type: 'string', required: true, description: '包名 from dshm_list, e.g. dsh-better-sidebar' },
+            enabled: { type: 'boolean', required: true, description: 'true = 启用，false = 停用' },
+        },
+        output: {
+            schema: { type: 'object', additionalProperties: true },
+            render: (_args, value) => [{ type: 'text', text: renderToggle(value) }],
+            presentationMeta: (_args, value) => ({ kind: 'dshm-toggle', ...value }),
+        },
+        presentCall: (args) => ({
+            card: 'generic',
+            title: `${args.enabled === true ? '启用' : '停用'} · ${String(args.pkg || '')}`,
+            content: [],
+        }),
+        presentResult: (_args, { isError, meta }) => ({
+            card: 'generic',
+            title: isError ? '开关操作失败' : `已${meta?.enabled === true ? '启用' : '停用'} · ${meta?.pkg || ''}`,
+            content: [],
+        }),
+        timeoutMs: 30_000,
+        async execute(args) {
+            const target = String(args.pkg || '').trim();
+            if (!target)
+                throw new Error('缺少 pkg');
+            if (typeof args.enabled !== 'boolean')
+                throw new Error('缺少 enabled（boolean）');
+            return cloneJson(await toggle(target, args.enabled, { getService: getService }));
         },
     }));
     ctx.tools.register(defineTool({
@@ -272,11 +310,29 @@ export function registerTools(ctx, cfg, deps = {}) {
                 `Plugin categories: ${Object.entries(CATEGORY_LABELS).map(([k, v]) => `${k}=${v}`).join(', ')}.`,
                 'Install only after the user names a card: dshm_install with its id. Then one short sentence mentioning the restart requirement; offer dshm_restart.',
                 'For installed plugins, call dshm_list / dshm_outdated. Upgrade only after the user confirms which one: dshm_upgrade. Uninstall only after confirmation: dshm_uninstall.',
+                'dshm_toggle switches a plugin on/off: confirm first unless the user already said it in the same message (把 skins 关掉 → execute directly); report live vs restart-required accordingly. ',
                 'dshm_restart only after the user agrees to restart; afterwards tell them to refresh once the page recovers.',
             ].join(' '),
         });
     });
 }
+/** 开关结果渲染（Task 15）。 */
+function renderToggle(out) {
+    const word = out.enabled ? '已启用' : '已停用';
+    if (out.applied === 'live') {
+        return `✅ ${out.pkg} ${word}（即时生效）。${out.warnings.join('；')}`;
+    }
+    return `✅ ${out.pkg} ${word}（需重启生效——询问是否 dshm_restart）。${out.warnings.join('；')}`;
+}
+/** 构建放行文案（ADR-0002）：列包名；兜底全量放行如实标注。 */
+function buildsNote(out) {
+    if (out.fallbackAllBuilds)
+        return '注意：该插件执行了构建脚本（名单不可读，已全量兜底放行）。';
+    const names = out.buildApprovals ?? [];
+    if (names.length === 0)
+        return '';
+    return `注意：该插件执行了构建脚本，已精确放行：${names.join('、')}。`;
+}
 function renderSearch(out) {
     if (!out.items?.length)
         return '收录清单中没有匹配的插件。对用户只说一句：没找到，可以换个词再搜。不要写长文。';
@@ -307,11 +363,19 @@ function renderList(out) {
     ].join('\n');
 }
 function renderInstall(out) {
-    const extra = out.usedAllowAllBuilds ? '注意：该插件执行了构建脚本（已按策略放行）。' : '';
+    const extra = buildsNote(out);
+    const compatNote = out.compat
+        ? '注意：该版本与当前 DSH 运行时 peer 不兼容，已按用户确认强制安装。'
+        : out.compatSkipped === 'github-source'
+            ? '注意：github 源未做兼容预检。'
+            : '';
+    const bundleNote = out.bundleWarning === 'no-patch-layer'
+        ? '注意：该包无补丁层（cordis.patch.yml 缺失且未进 bundles），已装入为纯依赖不会生效；如非预期可卸载（dshm_uninstall）或到收录仓库反馈。'
+        : '';
     const heals = out.healActions?.length
         ? `安装过程含 ${out.healActions.length} 步自愈（${out.healActions.map((h) => h.code).join('、')}）。`
         : '';
-    return `✅ ${out.pkg} 已安装（${out.spec}）。${extra}${heals}需要重启 DSH Web 生效——告知用户并询问是否 dshm_restart。不要打印安装命令。`;
+    return `✅ ${out.pkg} 已安装（${out.spec}）。${extra}${compatNote}${bundleNote}${heals}需要重启 DSH Web 生效——告知用户并询问是否 dshm_restart。不要打印安装命令。`;
 }
 function renderUninstall(out) {
     const parts = [`✅ ${out.pkg} 已卸载。`];
@@ -338,7 +402,7 @@ function renderOutdated(out) {
 function renderUpgrade(out) {
     const from = out.fromVersion ? `v${out.fromVersion} → ` : '';
     const to = out.version ? `v${out.version}` : out.sha ? out.sha.slice(0, 7) : '最新';
-    const extra = out.usedAllowAllBuilds ? '注意：该插件执行了构建脚本。' : '';
+    const extra = buildsNote(out);
     return `✅ ${out.pkg} 已升级（${from}${to}）。${extra}需要重启生效——询问是否 dshm_restart。`;
 }
 function clamp(n, min, max) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-m",
-  "version": "0.2.14",
+  "version": "0.4.0",
   "description": "可自定义收录清单的 DSH 插件市场：收录、安装、卸载、升级一站完成，附 agent 工具与 dshm CLI。",
   "license": "MIT",
   "type": "module",
@@ -74,9 +74,15 @@
     "@types/node": "^24.0.0",
     "@types/react": "^18.3.0",
     "@types/react-dom": "^18.3.0",
+    "@types/semver": "7.8.0",
     "esbuild": "^0.25.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "typescript": "^5.6.0"
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-atomic-write": "0.1.7-rc.2",
+    "semver": "7.8.5",
+    "yaml": "2.9.1"
   }
 }