dsh-plugin-tool-management 0.19.0 → 0.20.0

package/lib/trash-retention.js

@@ -0,0 +1,256 @@
+// 回收站保留期（0.19.1）—— 超过保留期的回收站条目由清扫**自动永久删除**。
+//
+// 为什么要有它：回收站此前只有「进来」没有「出去」—— 除了用户一条条点「永久删除」，
+// 没有任何自动清空的开关。删掉一个场景、一批技能、一堆记忆之后，条目会一直躺在磁盘上。
+// History（归档会话）页早就有这套（`hub/history-retention.json` + `sweepHistory`），
+// 这里**刻意同形**：同一个 `{retentionDays, updatedAt}` 侧车形状、同一条到期判据、同一个
+// 「改设置即重置倒计时」语义。两处口径一旦分家，用户在两个页面看到的就是两套话术。
+//
+// 覆盖六类：hub 五类（`trash/<域>-trash/<id>/manifest.json`，含记忆 —— 它的落点自
+// 2026-10-10 起也在这里，读写仍走 memories 域自己的实现）+ 技能（`trash/skills-trash/`，
+// 元数据文件叫 `metadata.json`，是 core 层自己写的那套）。
+//
+// 三条口径（改这个文件前先读）：
+//   ① `retentionDays <= 0` = **永久保留**，清扫是纯 no-op。这是默认值，也是本文件存在的
+//      前提：`skills/manager-state.ts` 里有一条更早的产品裁定 ——「回收站没有自动清理：
+//      超龄条目通过 warnings 提示用户到 Skills 管理页处理，**避免静默删除用户可能还想
+//      恢复的内容**」。那条裁定针对的是「没有开关的自动删除」，所以这里默认关闭、
+//      只有用户显式打开才删。默认值改了就等于推翻那条裁定，别顺手改。
+//   ② 到期基线 = `max(deletedAt, updatedAt)`，`updatedAt` 是**最近一次改保留期的时刻**。
+//      于是「把保留期从 30 天改成 7 天」不会当场删掉一批 8 天前的条目 —— 倒计时从改设置
+//      那一刻按新天数重算。与 History 页同一条（那边原话：「改保留期即重置倒计时」）。
+//   ③ `deletedAt` 缺失 / 解析失败**不清扫**。判据宁可漏删也不能误删：条目元数据被手改过、
+//      或来自更早的版本时，我们并不知道它躺了多久 —— 按「刚删的」处理，让它等下一轮。
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { recordAudit } from './audit-log.js';
+import { hubPath, listTrashEntries, purgeTrashEntry, } from './hub.js';
+import { listTrash as listSkillTrash, permanentlyDeleteTrash } from './skills/skill-trash.js';
+/** 一天的毫秒数（保留期按「天」配置，比较按毫秒）。与 sessions/history.ts 同一个常量。 */
+export const MS_PER_DAY = 24 * 60 * 60 * 1000;
+/** 保留期侧车文件名（放 hub 根，与 `history-retention.json` 并排）。 */
+export const TRASH_RETENTION_FILE = 'trash-retention.json';
+/** 走 hub 通用回收站的四类（技能与记忆各自另有实现，不在这里）。 */
+export const HUB_TRASH_KINDS = ['subagents', 'scenes', 'prompts', 'quick-prompts'];
+/** 永久删除时记流水用的 op 名 —— **复用各域已有的 `*-trash-delete`**，不另造一套。
+ *  这样兼容页「最近改动」里自动清理与手工删除长得一样，`compat.audit.op.trashDelete`
+ *  那条既有翻译也直接适用（否则会在流水里露出一串没人认识的 op 名）。 */
+const AUDIT_OP_BY_KIND = {
+    prompts: 'agentsmd-trash-delete',
+    'quick-prompts': 'quickprompt-trash-delete',
+    subagents: 'subagent-trash-delete',
+    scenes: 'scene-trash-delete',
+};
+const AUDIT_OP_SKILLS = 'skill-trash-delete';
+const AUDIT_OP_MEMORIES = 'rules-trash-remove';
+/** 侧车绝对路径。 */
+export function trashRetentionPath() {
+    return hubPath(TRASH_RETENTION_FILE);
+}
+/**
+ * 解析侧车内容（纯函数，坏输入不抛）。
+ *
+ * 与 `readHistoryRetention` 同判据：`retentionDays` 只认**有限且非负**的数，其余一律 0
+ * （= 永久保留）。宁可退化成「什么都不删」，也不能因为一份被手改坏的 JSON 变成
+ * 「拿一个负数当保留期」—— 那会让 `now - 负数 * 一天` 落到未来，把全部条目判成到期。
+ */
+export function parseTrashRetention(raw) {
+    const obj = raw && typeof raw === 'object' ? raw : null;
+    const days = Number((obj && obj.retentionDays) ?? 0);
+    const updatedAt = Number((obj && obj.updatedAt) ?? 0);
+    return {
+        retentionDays: Number.isFinite(days) && days >= 0 ? days : 0,
+        updatedAt: Number.isFinite(updatedAt) && updatedAt > 0 ? updatedAt : 0,
+    };
+}
+/** 读侧车。文件不存在 / 读坏 / JSON 坏 → `{0, 0}`（= 永久保留）。 */
+export async function readTrashRetention() {
+    try {
+        return parseTrashRetention(JSON.parse(await readFile(trashRetentionPath(), 'utf8')));
+    }
+    catch {
+        return { retentionDays: 0, updatedAt: 0 };
+    }
+}
+/** 写侧车。`updatedAt` = 本次修改时刻（到期基线随之重置，见文件头第 ② 条）。 */
+export async function writeTrashRetention(retentionDays) {
+    const abs = trashRetentionPath();
+    await mkdir(dirname(abs), { recursive: true });
+    await writeFile(abs, JSON.stringify({ retentionDays, updatedAt: Date.now() }), 'utf8');
+}
+/**
+ * 算出到期应永久删除的条目 id（纯函数，便于测试）。
+ *
+ * 参数顺序、返回形状与 `sessions/history.ts` 的 `expiredArchivedIds` 逐字对应 ——
+ * 两处保留期必须是同一套判据，改一边就要改另一边。
+ *
+ * @param entries 至少要有 `id` 与 `deletedAt`（ISO 字符串）
+ * @param retentionDays `<= 0` = 永久保留，返回空集
+ * @param now 当前时刻（毫秒）
+ * @param updatedAt 最近一次改保留期的时刻（毫秒）；`0` = 从没改过，退回到 deletedAt 语义
+ */
+export function expiredTrashIds(entries, retentionDays, now, updatedAt = 0) {
+    if (!(retentionDays > 0))
+        return [];
+    const cutoff = now - retentionDays * MS_PER_DAY;
+    const out = [];
+    for (const entry of entries) {
+        const deleted = Date.parse(String(entry.deletedAt ?? ''));
+        // 缺失 / 解析失败 → 不知道躺了多久 → 不清扫（文件头第 ③ 条）。
+        if (!Number.isFinite(deleted))
+            continue;
+        const baseline = updatedAt > 0 ? Math.max(deleted, updatedAt) : deleted;
+        if (baseline <= cutoff)
+            out.push(entry.id);
+    }
+    return out;
+}
+/**
+ * 收集六类回收站条目（best-effort：某一类读不出来只跳过那一类，不拖垮整轮清扫）。
+ *
+ * 为什么每类各自 try/catch：清扫是启动期的后台动作，一个坏掉的 manifest 不该让另外五类
+ * 永远清不掉 —— 那正是「保留期看起来没生效」这类难查故障的温床。
+ */
+export async function collectTrashCandidates(memories) {
+    const out = [];
+    for (const kind of HUB_TRASH_KINDS) {
+        let entries = [];
+        try {
+            entries = await listTrashEntries(kind);
+        }
+        catch {
+            entries = [];
+        }
+        for (const entry of entries) {
+            out.push({
+                key: `${kind}/${entry.id}`,
+                domain: kind,
+                name: entry.name,
+                deletedAt: String(entry.deletedAt ?? ''),
+                purge: () => purgeTrashEntry(kind, entry.id),
+            });
+        }
+    }
+    try {
+        for (const item of await listSkillTrash()) {
+            out.push({
+                key: `skills/${item.id}`,
+                domain: 'skills',
+                name: item.name,
+                // `deletedAt` 在技能元数据里是可选的：更早的版本可能没写 → 空串 → 不清扫（第 ③ 条）。
+                deletedAt: String(item.deletedAt ?? ''),
+                purge: () => permanentlyDeleteTrash(item.id, undefined),
+            });
+        }
+    }
+    catch { /* 技能回收站读不出来 → 本轮跳过 */ }
+    try {
+        for (const item of await memories.list()) {
+            out.push({
+                key: `memories/${item.id}`,
+                domain: 'memories',
+                name: item.name,
+                deletedAt: String(item.deletedAt ?? ''),
+                purge: () => memories.purge(item.id),
+            });
+        }
+    }
+    catch { /* 记忆回收站读不出来 → 本轮跳过 */ }
+    return out;
+}
+/** 删除成功与否：`{ok:false}` 与抛错都算失败（与 `recordOpAudit` 同口径）。 */
+async function purgeSucceeded(run) {
+    try {
+        const res = await run();
+        if (res && typeof res === 'object' && res.ok === false)
+            return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 扫一轮：按当前保留期把到期条目永久删除。
+ *
+ * **刻意不经 op 表**（与 `sweepHistory` 同一条）：这是引擎自己的后台动作，不是「谁发起的
+ * 一次改动」。走 op 表会同时套上令牌门禁与场景冻结 —— 于是「锁着一个场景」就等于
+ * 「保留期静默失效」，而用户根本看不出原因。手工删除仍走各域的 `*-trash-delete`（那几条
+ * 是冻结的），两条路的差别只在**发起方**：用户点的是写操作，清扫不是。
+ *
+ * 流水照记（`source: 'engine'`）：自动删掉的东西必须留痕，否则用户只会看到条目"自己消失了"。
+ */
+export async function sweepTrash(memories, now = Date.now()) {
+    const { retentionDays, updatedAt } = await readTrashRetention();
+    if (!(retentionDays > 0))
+        return { swept: [], failed: 0, retentionDays };
+    const candidates = await collectTrashCandidates(memories);
+    const expired = new Set(expiredTrashIds(candidates.map((c) => ({ id: c.key, deletedAt: c.deletedAt })), retentionDays, now, updatedAt));
+    const swept = [];
+    let failed = 0;
+    for (const candidate of candidates) {
+        if (!expired.has(candidate.key))
+            continue;
+        if (await purgeSucceeded(candidate.purge)) {
+            swept.push(`${candidate.domain}/${candidate.name || candidate.key}`);
+            recordAudit({
+                ts: now,
+                op: candidate.domain === 'skills' ? AUDIT_OP_SKILLS
+                    : candidate.domain === 'memories' ? AUDIT_OP_MEMORIES
+                        : (AUDIT_OP_BY_KIND[candidate.domain] || 'trash-sweep'),
+                target: candidate.name || candidate.key,
+                source: 'engine',
+            });
+        }
+        else {
+            failed += 1;
+        }
+    }
+    return { swept, failed, retentionDays };
+}
+/**
+ * 回收站保留期域：读 / 写侧车 + 清扫，并在**启动时扫一次、之后按 `sweepIntervalMs` 周期复跑**。
+ *
+ * 与 `createHistoryDomain` 同形（那边是归档会话的保留期）：默认 6 小时一次，`sweepIntervalMs`
+ * 由插件配置覆盖。间隔读同一个配置键，是为了让"清扫频率"只有一个说法 —— 两个域各读各的键，
+ * 用户调了其中一个却只影响一半，是查不出来的那种不一致。
+ *
+ * 清扫**不阻断启动**：`void sweep()` 失败只 warn。回收站清理是附属能力，任何时候都不该
+ * 让插件起不来（与 audit-log.ts 第 ② 条同一条纪律）。
+ */
+export function createTrashRetentionDomain(deps) {
+    const { ctx, config, memories } = deps;
+    const configured = Number(config?.sweepIntervalMs || 0);
+    const sweepIntervalMs = configured > 0 ? configured : 6 * 60 * 60 * 1000;
+    async function sweep() {
+        try {
+            return await sweepTrash(memories);
+        }
+        catch (e) {
+            ctx.logger?.warn?.(`trash retention sweep failed: ${String(e?.message ?? e)}`);
+            return { swept: [], failed: 0, retentionDays: 0 };
+        }
+    }
+    // 启动时扫一次：上次退出到现在可能已经过了好几个保留期。
+    try {
+        void sweep();
+    }
+    catch { /* 非致命 */ }
+    try {
+        ctx.effect(() => {
+            // interval 缺失时退化为不挂钟（fake-ctx 测试里正是如此，不阻塞测试）。
+            const timer = ctx;
+            const fn = typeof timer.interval === 'function' ? timer.interval
+                : (typeof timer.setInterval === 'function' ? timer.setInterval : undefined);
+            if (!fn)
+                return () => { };
+            return fn(() => { void sweep(); }, sweepIntervalMs);
+        }, 'dsh-plugin-tool-management: trash retention sweep');
+    }
+    catch { /* timer 缺失时静默 */ }
+    return {
+        read: readTrashRetention,
+        write: writeTrashRetention,
+        sweep,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-tool-management",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "DSH plugin: one settings panel for MCP servers, skills, scenes, memories, subagent personas and AGENTS.md presets — a scene switches the whole environment, and the model can drive it from chat too.",
   "repository": {
     "type": "git",

package/lib/mcp/inspect-probe.js

@@ -1,199 +0,0 @@
-// MCP 配置体检的探测部分：命令在不在 PATH 上、http 端点通不通、把一行配置汇成检查清单，
-// 以及 `mcpm-inspect` 这个 op 本身。
-//
-// 正文从 mcp/manager.ts 的 createMcpManager 闭包里整段搬来，一字未改（只去不掉缩进 —— 它本来
-// 就在两层上；改的是两个闭包作用域的名字走 deps，moved-verify 按这两类容差机检）。
-//
-// 为什么先剥这一段：它是这 2211 行里少见的**纯消费方** —— 只读 normalizeRow 与 mcpmList 的
-// 结果，不碰工厂实例上那几个缓存（disabledToolsCache / restrictTimer / epoch /
-// agentRestrictions 那一簇被 ops 段与 dispose 共同改写，剥它要动的是调用点而不是这段）。
-// 体检自己的承诺是「点了什么都不变」，所以它复用列表结果而不回写任何缓存。
-import { maskUrlQuery } from './secret-guard.js';
-import { parseRows } from './patch-yaml.js';
-import { execFile } from 'node:child_process';
-export function createInspectProbe(deps) {
-    const INSPECT_PATH_TIMEOUT_MS = 3000;
-    /** 命令是否在 PATH 上：`unknown`（查不了）与 `missing`（确认没有）必须分开 —— 前者不是问题。 */
-    async function probeCommandOnPath(command) {
-        if (!command)
-            return 'unknown';
-        const finder = process.platform === 'win32' ? 'where' : 'which';
-        return await new Promise((resolve) => {
-            execFile(finder, [command], { timeout: INSPECT_PATH_TIMEOUT_MS, windowsHide: true }, (error, stdout) => {
-                if (!error) {
-                    resolve(String(stdout || '').trim() ? 'ok' : 'missing');
-                    return;
-                }
-                // ENOENT = 连 where/which 自己都没跑到；killed = 超时。两种都是「无法确认」，
-                // 剩下的（退出码非 0）才是「PATH 上没有这条命令」。
-                const code = error.code;
-                if (code === 'ENOENT' || error.killed === true)
-                    resolve('unknown');
-                else
-                    resolve('missing');
-            });
-        });
-    }
-    /** streamable-http 连通性探测的超时：再长，「全部检查」就会被一台挂掉的服务拖住。 */
-    const INSPECT_PROBE_TIMEOUT_MS = 5000;
-    /** 探测失败的原因短语（进词典模板的 {reason}）：认得出常见错误码就说人话，认不出给原文截断。 */
-    function describeProbeFailure(e) {
-        const err = e;
-        if (err && (err.name === 'TimeoutError' || err.name === 'AbortError')) {
-            return '探测超时（' + Math.round(INSPECT_PROBE_TIMEOUT_MS / 1000) + ' 秒无响应）';
-        }
-        const code = err && err.cause && err.cause.code;
-        if (code === 'ENOTFOUND' || code === 'EAI_AGAIN')
-            return '域名解析失败（' + code + '）';
-        if (code === 'ECONNREFUSED')
-            return '连接被拒绝（' + code + '）';
-        if (code === 'ETIMEDOUT')
-            return '连接超时（' + code + '）';
-        if (code === 'ECONNRESET')
-            return '连接被重置（' + code + '）';
-        if (typeof code === 'string' && /CERT|SSL|TLS/.test(code))
-            return 'TLS 证书校验失败（' + code + '）';
-        const text = String((err && err.cause && err.cause.message) || (err && err.message) || e || '');
-        return text.length > 80 ? text.slice(0, 77) + '…' : text;
-    }
-    /**
-     * streamable-http 的连通性探测：对配置地址 GET 一次，**任何** HTTP 响应（含 404/405）
-     * 都算「可达」—— 探测只回答"这个地址现在连不连得上"，不校验它是不是 MCP 服务。
-     * 不读响应体：streamable-http 对 GET 常回一条 SSE 长连接，拿到状态行就取消。
-     */
-    async function probeHttpEndpoint(url, headers) {
-        const extra = {};
-        if (headers && typeof headers === 'object' && !Array.isArray(headers)) {
-            for (const [k, v] of Object.entries(headers)) {
-                if (typeof v === 'string' && v)
-                    extra[k] = v;
-            }
-        }
-        try {
-            const res = await fetch(url, { method: 'GET', headers: extra, redirect: 'follow', signal: AbortSignal.timeout(INSPECT_PROBE_TIMEOUT_MS) });
-            try {
-                await res.body?.cancel();
-            }
-            catch { /* 取消失败不影响「可达」结论 */ }
-            return { reachable: true };
-        }
-        catch (e) {
-            return { reachable: false, reason: describeProbeFailure(e) };
-        }
-    }
-    /** 一行配置 → 检查项。`level: 'warn'` 才点黄；`info` 是「查不了 / 不算问题」那类说明。 */
-    async function inspectChecks(row, duplicateIds) {
-        const checks = [];
-        const declared = String(row.transport || '');
-        const url = String(row.url || '');
-        const command = String(row.command || '');
-        // transport 缺失/不认识时按字段形状推：历史上手工改过补丁文件的行会绕过 normalize，
-        // 直接判「没有 transport」会把一条其实能用的配置说成坏的。
-        const transport = declared === 'stdio' || (!declared && command && !url) ? 'stdio'
-            : declared === 'streamable-http' || (!declared && url) ? 'streamable-http'
-                : declared;
-        if (!declared && transport)
-            checks.push({ id: 'transportMissing', level: 'info' });
-        /** 值必须是字符串映射：非对象整片算坏，对象里逐个挑出非字符串的键。 */
-        const badKv = (map) => {
-            if (map == null)
-                return [];
-            if (typeof map !== 'object' || Array.isArray(map))
-                return ['*'];
-            return Object.keys(map).filter((k) => typeof map[k] !== 'string');
-        };
-        if (transport === 'stdio') {
-            if (!command)
-                checks.push({ id: 'noCommand', level: 'warn' });
-            else {
-                // 唯一一次外部调用。npx / uvx 这类 shim 找不到时界面给的下半句是「shim 属正常可忽略」，
-                // 不让用户以为命令坏了。
-                //
-                // `params.command` 原样回给客户端：这与 `mcpm-list`（同样是**免令牌**的只读 op）一致
-                // —— 列表视图里的 `command` 一直是明文，命令名本身不是凭据（真正装凭据的 `args`
-                // 两边都不回）。若哪天要收紧，两处必须一起收，否则只是把同一份值换个 op 暴露。
-                const found = await probeCommandOnPath(command);
-                if (found === 'missing')
-                    checks.push({ id: 'cmdMissing', level: 'warn', params: { command } });
-                else if (found === 'unknown')
-                    checks.push({ id: 'cmdUnknown', level: 'info', params: { command } });
-            }
-            if (row.args != null && !Array.isArray(row.args))
-                checks.push({ id: 'argsNotArray', level: 'warn' });
-            const badEnv = badKv(row.env);
-            if (badEnv.length)
-                checks.push({ id: 'kvNotString', level: 'warn', params: { where: 'env', keys: badEnv.join('、') } });
-        }
-        else if (transport === 'streamable-http') {
-            if (!url)
-                checks.push({ id: 'noUrl', level: 'warn' });
-            // URL 一律**打码后**回给客户端（`maskUrlQuery`，与列表视图同一口径）。本 op 在登记表里
-            // 是 `readonly: true` 的免令牌 op，原先这里回的是补丁文件里的 URL 原文 —— 于是一个
-            // 无需令牌的请求就能拿到 `?api_key=…` 的明文，绕过了 `mcpm-reveal` 那道
-            // 「令牌是明文凭据最后一道防线」的设计（审查 P0-5）。路径与主机保留，定位不受影响。
-            else if (!/^https?:\/\//.test(url))
-                checks.push({ id: 'badUrl', level: 'warn', params: { url: maskUrlQuery(url) } });
-            else {
-                // 格式对了再做一次真实探测（0.16.5）：此前的体检止步于格式校验，一条编造的
-                // 地址也能拿绿点 —— 绿点承诺的「没发现问题」其实只覆盖了一半（2026-09-29 实测）。
-                const probe = await probeHttpEndpoint(url, row.headers);
-                if (!probe.reachable)
-                    checks.push({ id: 'httpUnreachable', level: 'warn', params: { url: maskUrlQuery(url), reason: probe.reason } });
-            }
-            const badHeaders = badKv(row.headers);
-            if (badHeaders.length)
-                checks.push({ id: 'kvNotString', level: 'warn', params: { where: 'headers', keys: badHeaders.join('、') } });
-        }
-        else if (!command && !url) {
-            checks.push({ id: 'noEndpoint', level: 'warn' });
-        }
-        else {
-            checks.push({ id: 'badTransport', level: 'warn', params: { transport } });
-        }
-        if (duplicateIds > 1)
-            checks.push({ id: 'nameDup', level: 'warn', params: { name: String(row.serverName || ''), count: duplicateIds } });
-        return checks;
-    }
-    async function mcpmInspect(args) {
-        const p = await deps.ensurePaths();
-        const rows = [];
-        const errors = [];
-        for (const level of ['project', 'global']) {
-            const abs = level === 'project' ? p.projectPatch : p.globalPatch;
-            let content = '';
-            try {
-                content = await deps.readPatch(abs);
-            }
-            catch (e) {
-                errors.push(level + ': ' + deps.message(e));
-                continue;
-            }
-            const { rows: fileRows } = parseRows(content);
-            for (const r of fileRows)
-                rows.push(deps.normalizeRow(r, level, abs));
-        }
-        // 重名判据：同一个 serverName 挂在**不同 id** 下。同 id 跨层是正常遮蔽（界面已有「重复 id」标签），
-        // 而按名字注册的 `mcp__<serverName>__*` 会撞车 —— 那才是配置问题。
-        const idsByName = {};
-        for (const r of rows) {
-            const n = String(r.serverName || '');
-            if (!idsByName[n])
-                idsByName[n] = new Set();
-            idsByName[n].add(String(r.id));
-        }
-        const onlyId = args && String(args.id || '') ? String(args.id) : '';
-        const onlyLevel = args && String(args.level || '') ? String(args.level) : '';
-        // 逐行检查并行跑：体检含 streamable-http 的端点探测（每次至多 5 秒超时），串行会让
-        // 「全部检查」在多台同时连不上时按行数翻倍地慢。Promise.all 保序，与旧实现一致。
-        const targets = rows.filter((r) => (!onlyId || String(r.id) === onlyId) && (!onlyLevel || String(r.level) === onlyLevel));
-        const results = await Promise.all(targets.map(async (r) => ({
-            id: r.id,
-            serverName: r.serverName,
-            level: r.level,
-            transport: r.transport || null,
-            checks: await inspectChecks(r, (idsByName[String(r.serverName || '')] || new Set()).size),
-        })));
-        return { ok: true, results, errors };
-    }
-    return { probeCommandOnPath, describeProbeFailure, probeHttpEndpoint, inspectChecks, mcpmInspect };
-}