@modusensus/dsh-mneme 0.8.0 → 0.8.1

package/lib/version-check.js

@@ -0,0 +1,122 @@
+// 版本自检（issue #174 后续，2026-09-15 拍板）：独立插件不把「用户在用哪个
+// 版本」托付给插件市场——市场收录有 ~26h 年龄闸门 + 30min 缓存，且安装时
+// 精确指定过版本的 profile 会被 pnpm 钉子挡住（update 尊重既有 semver 范围，
+// 永不跨 minor/major，#174 的报障者正是这样用着 0.7.32 的行为模型来报 bug）。
+//
+// 本模块只做三件事：
+//   1. 向 npm registry 查 @modusensus/dsh-mneme 的 latest dist-tag（带 TTL
+//      缓存 + 超时 + 全失败静默——离线/被墙/registry 异常都返回 null，调用方
+//      据 null 渲染「未知」，前端不打扰）；
+//   2. 与运行版本做纯函数比对（classify）；
+//   3. 对外暴露 registry URL 白名单校验（validateRegistryUrl）——发请求前
+//      强制 https + 精确 host，构造上排除本机与内网地址。
+import { readFileSync } from "node:fs";
+
+// 运行版本：src/ 与 lib/ 都在插件根下一层，相对 import.meta.url 解析一致；
+// 读取失败（打包/受限环境）降级 "unknown"，横幅随之静默。
+const PACKAGE_VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+})();
+
+// registry 查询地址是模块常量而非用户输入；validateRegistryUrl 仍作为发请求
+// 前的强制闸（构造上即排除非 https 与非白名单 host，双保险且可单测）。
+const REGISTRY_URL = "https://registry.npmjs.org/@modusensus%2Fdsh-mneme/latest";
+const REGISTRY_HOST = "registry.npmjs.org";
+// 市场收录本身有 ~1 天年龄闸门，1h 的 registry 缓存远低于该粒度，足够新鲜。
+const CACHE_TTL_MS = 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 5000;
+
+// 精确 host 白名单：协议必须 https，且 host 逐字等于 registry.npmjs.org。
+// 这一条即构造性排除本机回环、私有网段与保留地址——不做任何
+// 「看起来像公网」的宽松判断，将来换源必须显式改这里的常量。
+export function validateRegistryUrl(candidate) {
+  let url;
+  try {
+    url = new URL(candidate);
+  } catch {
+    return false;
+  }
+  return url.protocol === "https:" && url.hostname === REGISTRY_HOST;
+}
+
+/** 解析 `x.y.z` / `x.y.z-后缀` 为可比较结构；解析失败返回 null。 */
+function parseVersion(text) {
+  if (typeof text !== "string") return null;
+  const match = text.trim().match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    // 有 prerelease 后缀的同号版本视为更旧（0.9.0-rc.1 < 0.9.0）。
+    prerelease: match[4] !== undefined
+  };
+}
+
+/**
+ * 三元组语义化比较：a<b → -1，a>b → 1，无法比较 → null（调用方归入 unknown）。
+ * 仅比较数字部分；数字相等时，带 prerelease 的一方更旧（0.9.0-rc.1 < 0.9.0），
+ * 两侧都带则视为同版——横幅只关心「是否落后于 latest」，不追求完整 semver 序。
+ */
+export function compareVersions(a, b) {
+  const va = parseVersion(a);
+  const vb = parseVersion(b);
+  if (!va || !vb) return null;
+  for (const key of ["major", "minor", "patch"]) {
+    if (va[key] !== vb[key]) return va[key] < vb[key] ? -1 : 1;
+  }
+  if (va.prerelease !== vb.prerelease) return va.prerelease ? -1 : 1;
+  return 0;
+}
+
+/**
+ * 运行版本 vs registry latest 的展示归类。latest 为 null（查询失败/离线）
+ * 或任一侧解析失败时归 unknown——前端对 unknown 完全静默。
+ */
+export function classify(version, latest) {
+  const cmp = compareVersions(version, latest);
+  if (cmp === null) return "unknown";
+  if (cmp < 0) return "outdated";
+  if (cmp > 0) return "ahead";
+  return "up-to-date";
+}
+
+// 模块级缓存：面板可能多处/多次拉取，TTL 内一律复用，不重复打 registry。
+// at 用 -Infinity 作「从未拉取」哨兵：任何时钟下 now-at 都是正无穷，首轮
+// 必然真实请求（测试的假时钟从 0 起也不会被误判成新鲜缓存）。
+let cache = { at: -Infinity, latest: null };
+
+/**
+ * 查询 registry latest。TTL 内直接命中缓存；任何失败（网络/超时/非 2xx/
+ * 响应形状不对/URL 校验不过）都静默返回 null——版本提示是锦上添花，绝不
+ * 让它成为新的故障面。失败不写缓存：TTL 起点保持旧值，下次调用立刻重试。
+ */
+export async function fetchLatestVersion({ fetchImpl = typeof fetch === "function" ? fetch : () => Promise.reject(new Error("no fetch")), now = Date.now } = {}) {
+  if (now() - cache.at < CACHE_TTL_MS) return cache.latest;
+  if (!validateRegistryUrl(REGISTRY_URL)) return null;
+  let manifest;
+  try {
+    const response = await fetchImpl(REGISTRY_URL, {
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      headers: { accept: "application/json" }
+    });
+    if (!response.ok) return null;
+    manifest = await response.json();
+  } catch {
+    return null;
+  }
+  const latest = typeof manifest?.version === "string" && manifest.version ? manifest.version : null;
+  cache = { at: now(), latest };
+  return latest;
+}
+
+/** 仅供测试：清空模块级缓存与时间戳。 */
+export function resetCacheForTest() {
+  cache = { at: -Infinity, latest: null };
+}
+
+export { PACKAGE_VERSION, REGISTRY_URL, CACHE_TTL_MS };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@modusensus/dsh-mneme",
   "description": "Cross-session memory plugin for DeepSeek Harness with autoDream consolidation: SQLite store, Markdown mirrors, 7 model tools, automatic injection, session summarization, user profile/rules, custom slash commands, vector (semantic) search, and a Web GUI panel",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/api.js

@@ -1,5 +1,4 @@
 import { URL } from "node:url";
-import { readFileSync } from "node:fs";
 import { timingSafeEqual, randomBytes } from "node:crypto";
 import { FEATURE_FLAG_SPEC } from "./settings.js";
 import { TYPE_FILE, renderMirrorText, parseHumanEdits } from "./mirror.js";
@@ -8,6 +7,7 @@ import { computeHeat } from "./heat.js";
 import { describeStreamFailure, resolveRoute } from "./dream.js";
 import { describeLocalRuntime, publicRuntimeStatus } from "./runtime/loader.js";
 import { hostModulesDir, provisionRuntime } from "./runtime/provision.js";
+import { classify, fetchLatestVersion, PACKAGE_VERSION } from "./version-check.js";
 
 // headers：少数端点（/export 附件下载）需要追加 Content-Disposition 等响应头。
 function sendJson(res, status, payload, headers = {}) {
@@ -24,16 +24,8 @@ function sendAttachment(res, status, contentType, filename, body) {
   res.end(body);
 }
 
-// 导出 JSON 的 version 字段：读插件根的 package.json（src/ 与 lib/ 都在根下
-// 一层，相对 import.meta.url 解析一致）。读取失败（打包/受限环境）降级为
-// "unknown"，导出本身仍然可用。
-const PACKAGE_VERSION = (() => {
-  try {
-    return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version ?? "unknown";
-  } catch {
-    return "unknown";
-  }
-})();
+// 版本号统一从 version-check.js 取（同一份读 package.json 逻辑，读取失败
+// 同样降级 "unknown"）——/info 与 /version-check 两个路由共用，不再各写一份。
 
 // Defaults for the standalone external API — keep in step with the schema
 // defaults in config.js (externalApiPort / externalApiHost).
@@ -175,6 +167,29 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     }
   });
 
+  // 版本自检（#174 后续）：运行版本 vs npm registry latest。只读，宿主围栏
+  // 统一鉴权（与 dream-status 同款，面板 apiFetch 直接可用）。registry 查询
+  // 全失败时 latest=null、status=unknown——前端对 unknown 完全静默，版本提示
+  // 是锦上添花，绝不因它新增故障面。
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/version-check",
+    handler(req, res) {
+      if (req.method !== "GET") {
+        sendJson(res, 404, { error: "not-found" });
+        return;
+      }
+      fetchLatestVersion()
+        .then((latest) => sendJson(res, 200, {
+          version: PACKAGE_VERSION,
+          latest,
+          status: classify(PACKAGE_VERSION, latest),
+          checkedAt: new Date().toISOString()
+        }))
+        .catch(() => sendJson(res, 200, { version: PACKAGE_VERSION, latest: null, status: "unknown" }));
+    }
+  });
+
   register({
     kind: "exact",
     path: "/api/dsh-mneme/list",
@@ -480,6 +495,19 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
             }
             patch.tags = body.tags;
           }
+          // v0.8.1 底座（issue #170）：显式 scope 修正。null=放宽到全局，
+          // 字符串=收窄/改标；归一化（"global"/"*"/空白→NULL + explicit 章 +
+          // 审计行）在 service.updateMemory 内做，路由只做形状校验。
+          if (body.agent_scope !== undefined && body.agent_scope !== null && typeof body.agent_scope !== "string") {
+            sendJson(res, 400, { error: "invalid-agent-scope" });
+            return;
+          }
+          if (body.workspace_scope !== undefined && body.workspace_scope !== null && typeof body.workspace_scope !== "string") {
+            sendJson(res, 400, { error: "invalid-workspace-scope" });
+            return;
+          }
+          if (body.agent_scope !== undefined) patch.agent_scope = body.agent_scope;
+          if (body.workspace_scope !== undefined) patch.workspace_scope = body.workspace_scope;
           if (body.archived !== undefined && typeof body.archived !== "boolean") {
             sendJson(res, 400, { error: "invalid-archived" });
             return;
@@ -501,7 +529,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
               ...history
             ].slice(0, 20);
           }
-          if (Object.keys(patch).length) service.update(id, patch);
+          if (Object.keys(patch).length) service.update(id, patch, { actor: "panel" });
           if (body.archived !== undefined) service.setArchived(id, body.archived);
           sendJson(res, 200, { memory: service.getById(id) });
         });

package/src/dream/sleep.js

@@ -4,6 +4,8 @@ import { STR, langOf } from "../lang.js";
 //   1. conflict resolution — high-similarity same-type pairs are either parked
 //      for review (freeze mode) or adjudicated by the LLM (winner kept / loser
 //      archived), reusing the dream conflict machinery. Strictness-graded.
+//      v0.8.1 (issue #170): cross-scope pairs are ALWAYS parked for human
+//      ownership review with a dedicated reason — never auto-adjudicated.
 //   2. archival demotion — memories unreferenced past sleepArchiveDays shrink
 //      to a one-line summary with the full body moved to _full_content; past
 //      sleepCompressDays they are archived outright.
@@ -18,6 +20,7 @@ import { STR, langOf } from "../lang.js";
 import { randomUUID, createHash } from "node:crypto";
 import { validateDecisions, applyDecisions, ACTIONS } from "./decisions.js";
 import { findPotentialConflicts, cosineSimilarity } from "./clustering.js";
+import { scopeKeyOf } from "../scope.js";
 import { buildReceipt, describeStreamFailure, resolveDreamEffort, withEffortFallback, maintainIndexAfterDream } from "../dream.js";
 import { computeHeat } from "../heat.js";
 
@@ -169,29 +172,57 @@ async function phaseConflicts(ctx, service, config, logger, runId, semantic = nu
     selected.push(p);
   }
 
-  // Freeze mode: park pairs for manual review, no LLM required.
+  // v0.8.1（issue #170 第 2 步）：跨 scope 相似对分流。同一内容落在两个归属下
+  // （任一维标注键不等即算，NULL=未标注=全局也参与比较——「全局副本 + 专属副本
+  // 并存」正是收窄/提升裁决的典型候选）不能自动裁决：归档败者可能销毁该内容在
+  // 某个归属下的唯一副本，LLM 也无从替用户决定归属。一律停车到冲突待确认队列
+  // （专属 reason），同 scope 对维持既有路径（freeze 停车 / LLM 裁决）。
+  const isCrossScopePair = (p) =>
+    scopeKeyOf(p.a.agent_scope) !== scopeKeyOf(p.b.agent_scope)
+    || scopeKeyOf(p.a.workspace_scope) !== scopeKeyOf(p.b.workspace_scope);
+  const crossPairs = selected.filter(isCrossScopePair);
+  const samePairs = selected.filter((p) => !isCrossScopePair(p));
+  const parkPair = (p, reason) => {
+    try {
+      // 返回 undefined = 该对已被人工裁决且两侧内容未变（复核项 4）——不算停车。
+      return service.saveConflictPending({ run_id: runId, memory_a: p.a.id, memory_b: p.b.id, reason }) != null;
+    } catch (error) {
+      logger?.warn?.(`dsh-mneme sleep: failed to park conflict ${p.a.id}/${p.b.id}: ${String(error)}`);
+      return false;
+    }
+  };
+  const scopeReason = (p) => STR.scopeCandidateReason[language](p.similarity.toFixed(2));
+  const simReason = (p) => STR.similarityReason[language](p.similarity.toFixed(2));
+
+  // Freeze mode: park pairs for manual review, no LLM required. Cross-scope
+  // pairs carry the dedicated scope-candidate reason so the queue reads them
+  // as ownership decisions rather than plain duplicates.
   if (config.conflictFreezeEnabled === true) {
     let frozen = 0;
     for (const p of selected) {
-      try {
-        service.saveConflictPending({ run_id: runId, memory_a: p.a.id, memory_b: p.b.id, reason: STR.similarityReason[language](p.similarity.toFixed(2)) });
-        frozen++;
-      } catch (error) {
-        logger?.warn?.(`dsh-mneme sleep: failed to freeze conflict ${p.a.id}/${p.b.id}: ${String(error)}`);
-      }
+      if (parkPair(p, isCrossScopePair(p) ? scopeReason(p) : simReason(p))) frozen++;
     }
-    return { status: frozen > 0 ? "ok" : "noop", frozen, pairs: selected.length };
+    return { status: frozen > 0 ? "ok" : "noop", frozen, scopeCandidates: crossPairs.length, pairs: selected.length };
   }
 
-  // LLM adjudication.
+  // 非 freeze：跨 scope 对先停车（绝不进 LLM 裁决），同 scope 对照常走 LLM。
+  let scopeParked = 0;
+  for (const p of crossPairs) {
+    if (parkPair(p, scopeReason(p))) scopeParked++;
+  }
+  if (samePairs.length === 0) {
+    return { status: scopeParked > 0 ? "ok" : "noop", frozen: 0, scopeCandidates: scopeParked, pairs: selected.length };
+  }
+
+  // LLM adjudication（仅同 scope 对）。
   const route = resolveSleepRoute(ctx, config, logger);
-  if (!route) return { status: "skipped", reason: "no llm route" };
+  if (!route) return { status: "skipped", reason: "no llm route", scopeCandidates: scopeParked, pairs: selected.length };
   const snapshot = new Map();
-  for (const p of selected) {
+  for (const p of samePairs) {
     snapshot.set(p.a.id, p.a);
     snapshot.set(p.b.id, p.b);
   }
-  const listText = selected.map((p) =>
+  const listText = samePairs.map((p) =>
     STR.candidateConflicts[language](p)
   ).join("\n\n");
   const sleepEffort = await resolveDreamEffort(ctx, route, config.sleepReasoningEffort, logger);

package/src/dream.js

@@ -1,5 +1,6 @@
 import { validateDecisions, applyDecisions } from "./dream/decisions.js";
 import { clusterMemories, findPotentialConflicts, cosineSimilarity } from "./dream/clustering.js";
+import { scopeKeyOf } from "./scope.js";
 import { createHash, randomUUID } from "node:crypto";
 import { STR, langOf } from "./lang.js";
 export { validateDecisions, applyDecisions, withEffortFallback, describeStreamFailure, resolveDreamEffort, resolveRoute };
@@ -989,7 +990,21 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
     // bounds the review queue; overflow is skipped with a warning.
     let frozenCount = 0;
     const frozenIds = [];
-    const applyList = freezeEnabled ? decisions.filter((d) => d.action !== "conflict") : decisions;
+    // v0.8.1（issue #170 复核项 3）：跨 scope 的 conflict 决策两种模式都一律
+    // 停车人工裁决、绝不自动归档——否则普通 dream 的 LLM 能归档别的 scope 的
+    // 唯一副本，sleep 路径（scope-candidate-queue）的保护在这里缺位。同 scope
+    // 的 conflict 决策照旧：freeze 停车 / 非 freeze 自动裁决。
+    const isCrossScopeDecision = (d) => {
+      const a = snapshot.get(d.winner);
+      const b = snapshot.get(d.loser);
+      return !!a && !!b && (
+        scopeKeyOf(a.agent_scope) !== scopeKeyOf(b.agent_scope)
+        || scopeKeyOf(a.workspace_scope) !== scopeKeyOf(b.workspace_scope)
+      );
+    };
+    const applyList = freezeEnabled
+      ? decisions.filter((d) => d.action !== "conflict")
+      : decisions.filter((d) => d.action !== "conflict" || !isCrossScopeDecision(d));
     if (freezeEnabled) {
       const conflictsToFreeze = decisions.filter((d) => d.action === "conflict");
       if (conflictsToFreeze.length > 0) {
@@ -1003,7 +1018,10 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
           }
           for (const d of toFreeze) {
             try {
-              service.saveConflictPending({ run_id: runId, memory_a: d.winner, memory_b: d.loser, reason: d.reason });
+              // 返回 undefined = 该对已被人工裁决且两侧内容未变（issue #170 复核
+              // 项 4：内容变了才重新入队）——不算停车、不进 frozenIds。
+              const parked = service.saveConflictPending({ run_id: runId, memory_a: d.winner, memory_b: d.loser, reason: d.reason });
+              if (parked == null) continue;
               frozenCount++;
               frozenIds.push(d.winner, d.loser);
             } catch (error) {
@@ -1014,6 +1032,29 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
           logger?.warn?.(`dsh-mneme dream: conflict freeze lookup failed: ${String(error)}`);
         }
       }
+    } else {
+      // 非 freeze：跨 scope conflict 停车（绝不进 applyDecisions）。带专属
+      // reason + 模型给出的裁决理由，队列里读起来是「归属裁决」而非重复项。
+      const crossScope = decisions.filter((d) => d.action === "conflict" && isCrossScopeDecision(d));
+      for (const d of crossScope) {
+        try {
+          const parked = service.saveConflictPending({
+            run_id: runId,
+            memory_a: d.winner,
+            memory_b: d.loser,
+            reason: STR.scopeConflictParkReason[language](d.reason)
+          });
+          if (parked != null) {
+            frozenCount++;
+            frozenIds.push(d.winner, d.loser);
+          }
+        } catch (error) {
+          logger?.warn?.(`dsh-mneme dream: failed to park cross-scope conflict ${d.winner}/${d.loser}: ${String(error)}`);
+        }
+      }
+      if (crossScope.length > 0) {
+        logger?.info?.(`[dsh-mneme] dream: parked ${crossScope.length} cross-scope conflict(s) for human ownership review`);
+      }
     }
 
     // CAS-guarded, per-decision-transactional apply against the run snapshot:

package/src/lang.js

@@ -103,6 +103,17 @@ export const STR = {
 
   // --- dream/sleep.js：冲突候选列表 --------------------------------------------
   similarityReason: { zh: (s) => `相似度 ${s}`, en: (s) => `similarity ${s}` },
+  // v0.8.1（issue #170 第 2 步）：跨 scope 相似对停车到冲突队列的专属 reason。
+  scopeCandidateReason: {
+    zh: (s) => `跨作用域相似 ${s}（疑似同一内容落在两个归属下，请裁决归属/去重）`,
+    en: (s) => `cross-scope similar ${s} (same content under two scopes — review ownership)`
+  },
+  // v0.8.1（issue #170 复核项 3）：普通 dream 的 LLM 输出跨 scope conflict 时
+  // 停车用（相似度未知，带模型给的裁决理由）。
+  scopeConflictParkReason: {
+    zh: (r) => `跨作用域冲突（归属不同，不自动裁决）${r ? `：${r}` : ""}`,
+    en: (r) => `cross-scope conflict (different ownership — not auto-adjudicated)${r ? `: ${r}` : ""}`
+  },
   candidateConflicts: {
     zh: (p) => `候选冲突：\nid=${p.a.id} | type=${p.a.type} | title=${p.a.title}\n${p.a.content}\n---\nid=${p.b.id} | type=${p.b.type} | title=${p.b.title}\n${p.b.content}\n（相似度 ${p.similarity.toFixed(2)}）`,
     en: (p) => `Candidate conflicts:\nid=${p.a.id} | type=${p.a.type} | title=${p.a.title}\n${p.a.content}\n---\nid=${p.b.id} | type=${p.b.type} | title=${p.b.title}\n${p.b.content}\n(similarity ${p.similarity.toFixed(2)})`

package/src/scope.js

@@ -8,8 +8,11 @@
 // 硬约束：解析失败绝不阻塞写入——任何一步取不到就落 NULL（读侧 NULL = 未标注
 // = 全局可见），任何异常都被吞掉（registry 故障 warn 一次后降级）。
 //
-// scopeEnabled 关闭时 resolveWriteScope 返回 null，调用方一个字段都不该标注，
-// 写入与去重行为和 A1 之前逐字节一致。
+// v0.8.1（issue #170 复核项 2）：scopeEnabled 的闸门从解析器挪到「写标注」处
+// （memory_save 的 auto 分支）。解析器恒返回会话身份（真取不到才是 null）——
+// 读取侧（strictVisibility / memory_get / inject）与显式声明都依赖它：flag 关
+// 只关「自动标注」，不能连读取身份一起关，否则 strictScope 硬墙被静默拆掉
+// （fail-open）。
 
 /**
  * @param {object} deps
@@ -31,8 +34,6 @@ export function createScopeResolver({ ctx, config, logger } = {}) {
   };
 
   return function resolveWriteScope(exec) {
-    if (config?.scopeEnabled !== true) return null;
-
     let session = null;
     try {
       session = exec?.agent?.session ?? null;
@@ -81,3 +82,37 @@ export function createScopeResolver({ ctx, config, logger } = {}) {
     return { agent_scope: agentScope, workspace_scope: workspaceScope };
   };
 }
+
+/**
+ * v0.8.1 底座（issue #170）：显式 scope 参数（memory_save / memory_update /
+ * 面板编辑）的归一化。约定：
+ *   - 省略（undefined，由调用方判断）= 该维不声明，回落载体自动标注；
+ *   - "global"（大小写不敏感）/ "*" / 空白 = 显式声明全局 → 存储 NULL
+ *     （行上的 agent_scope_source='explicit' 承担「显式全局」与「从未标注」
+ *     的区分，NULL 本身继续表示全局可见）；
+ *   - 其余非空 trim 字符串 = 收窄到该标签。
+ * 脏输入（非字符串）落 NULL（等同声明全局）——与 resolveWriteScope 的「解析
+ * 绝不阻塞写入」同一哲学：显式声明是用户意图，形状不对时宁可放宽不报错。
+ *
+ * @param {unknown} raw 工具/HTTP 参数原值
+ * @returns {string|null} 归一化后的标签值（null=显式全局）
+ */
+export function normalizeExplicitScope(raw) {
+  if (typeof raw !== "string") return null;
+  const s = raw.trim();
+  if (!s || s === "*" || s.toLowerCase() === "global") return null;
+  return s;
+}
+
+/**
+ * scope 标注的比较键（去重键/检索加权/跨 scope 配对共用口径）：非空 trim 字符串
+ * 原样返回，其余（NULL/undefined/空串/非字符串）统一为 null（「未标注」）。
+ * v0.8.1（issue #170 第 2 步）从 service.js 上提为共享定义——sleep 的跨 scope
+ * 候选配对必须与去重键用同一把钥匙，NULL 与已标注才不会错配。
+ *
+ * @param {unknown} v scope 标注原值
+ * @returns {string|null} 比较键（null=未标注）
+ */
+export function scopeKeyOf(v) {
+  return typeof v === "string" && v.trim() ? v.trim() : null;
+}