@twinsearth/fang-dsh-plugin 0.0.0-stage → 3.3.4

package/src/lib/bridge-client.mjs

@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+// bridge-client — talk to a running PC host's `@ignotuss/dsh-desktop-bridge`.
+//
+// The bridge is transport only: 127.0.0.1 + bearer token from
+// `<DSH_HOME>/desktop-bridge.json`. The descriptor is re-read on every call because
+// the port and token are regenerated each time the PC host mounts the plugin.
+// This client never writes to the PC host and never logs the token.
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+export const BRIDGE_DESCRIPTOR_FILE = 'desktop-bridge.json'
+export const BRIDGE_DEFAULT_TIMEOUT_MS = 15000
+
+export const BRIDGE_CODE = Object.freeze({
+  UNAVAILABLE: 'bridge-unavailable',
+  INVALID: 'bridge-descriptor-invalid',
+  HTTP: 'bridge-http',
+  NETWORK: 'bridge-network',
+  TIMEOUT: 'bridge-timeout',
+  INVALID_INPUT: 'bridge-invalid-input',
+})
+
+const LOOPBACK = new Set(['127.0.0.1', '::1', 'localhost'])
+
+export function defaultDshHome() {
+  return String(process.env.DSH_HOME ?? '').trim() || path.join(String(process.env.USERPROFILE ?? '').trim() || '.', '.dsh')
+}
+
+export function descriptorPath(dshHome) {
+  return path.join(String(dshHome ?? '').trim() || defaultDshHome(), BRIDGE_DESCRIPTOR_FILE)
+}
+
+/**
+ * Read + validate the descriptor. Fail-closed: a malformed or non-loopback
+ * descriptor is an error, never a partial client.
+ * @returns {{ok:true, info:{version:number,address:string,port:number,token:string,pid?:number}, file:string} | {ok:false, code:string, error:string, file:string}}
+ */
+export function readBridgeDescriptor(options = {}) {
+  const file = options.file ?? descriptorPath(options.dshHome)
+  let raw
+  try {
+    raw = fs.readFileSync(file, 'utf8')
+  } catch (e) {
+    return { ok: false, code: BRIDGE_CODE.UNAVAILABLE, error: `desktop-bridge.json not readable (${e?.code ?? 'ENOENT'})`, file }
+  }
+  let info
+  try { info = JSON.parse(raw) } catch { return { ok: false, code: BRIDGE_CODE.INVALID, error: 'desktop-bridge.json is not JSON', file } }
+  if (!info || typeof info !== 'object') return { ok: false, code: BRIDGE_CODE.INVALID, error: 'descriptor is not an object', file }
+  if (info.version !== 1) return { ok: false, code: BRIDGE_CODE.INVALID, error: `unsupported descriptor version ${String(info.version)}`, file }
+  if (!LOOPBACK.has(String(info.address ?? ''))) return { ok: false, code: BRIDGE_CODE.INVALID, error: 'bridge address is not loopback', file }
+  const port = Number(info.port)
+  if (!Number.isInteger(port) || port < 1 || port > 65535) return { ok: false, code: BRIDGE_CODE.INVALID, error: 'invalid bridge port', file }
+  const token = typeof info.token === 'string' ? info.token.trim() : ''
+  if (!/^[0-9a-f]{32,}$/i.test(token)) return { ok: false, code: BRIDGE_CODE.INVALID, error: 'invalid bridge token', file }
+  return { ok: true, file, info: { version: 1, address: String(info.address), port, token, pid: info.pid, startedAt: info.startedAt } }
+}
+
+function cleanError(e) {
+  const code = e?.name === 'AbortError' ? BRIDGE_CODE.TIMEOUT : BRIDGE_CODE.NETWORK
+  return { ok: false, code, error: code === BRIDGE_CODE.TIMEOUT ? 'bridge request timed out' : 'bridge request failed' }
+}
+
+/**
+ * Create a client bound to a DSH home. Every method reloads the descriptor.
+ * @returns {{status:Function, listSessions:Function, events:Function, send:Function, create:Function}}
+ */
+export function createBridgeClient(options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch
+  const timeoutMs = Math.max(1000, Number(options.timeoutMs) || BRIDGE_DEFAULT_TIMEOUT_MS)
+
+  async function call(method, pathname, body) {
+    const desc = readBridgeDescriptor({ file: options.file, dshHome: options.dshHome })
+    if (!desc.ok) return desc
+    const url = `http://${desc.info.address}:${desc.info.port}${pathname}`
+    let res
+    try {
+      res = await fetchImpl(url, {
+        method,
+        headers: { authorization: `Bearer ${desc.info.token}`, accept: 'application/json', ...(body ? { 'content-type': 'application/json' } : {}) },
+        body: body ? JSON.stringify(body) : undefined,
+        signal: AbortSignal.timeout(timeoutMs),
+      })
+    } catch (e) {
+      return cleanError(e)
+    }
+    const text = await res.text().catch(() => '')
+    let data = null
+    try { data = text ? JSON.parse(text) : null } catch { data = null }
+    if (!res.ok) {
+      return { ok: false, code: BRIDGE_CODE.HTTP, status: res.status, error: String(data?.error ?? `HTTP ${res.status}`).slice(0, 300) }
+    }
+    return { ok: true, status: res.status, data, pid: desc.info.pid, startedAt: desc.info.startedAt }
+  }
+
+  return {
+    async status() {
+      const desc = readBridgeDescriptor({ file: options.file, dshHome: options.dshHome })
+      if (!desc.ok) return desc
+      return { ok: true, available: true, pid: desc.info.pid, startedAt: desc.info.startedAt, file: desc.file }
+    },
+    async listSessions() {
+      const out = await call('GET', '/v1/sessions')
+      if (!out.ok) return out
+      return { ok: true, items: Array.isArray(out.data?.items) ? out.data.items : [] }
+    },
+    async events(sessionId, opts = {}) {
+      const id = String(sessionId ?? '').trim()
+      if (!id) return { ok: false, code: BRIDGE_CODE.INVALID_INPUT, error: 'sessionId required' }
+      const limit = Math.min(100, Math.max(1, Number(opts.limit) || 30))
+      const out = await call('GET', `/v1/sessions/${encodeURIComponent(id)}/events?limit=${limit}`)
+      if (!out.ok) return out
+      return { ok: true, sessionId: id, events: Array.isArray(out.data?.events) ? out.data.events : [] }
+    },
+    async send(sessionId, text) {
+      const id = String(sessionId ?? '').trim()
+      const body = String(text ?? '')
+      if (!id) return { ok: false, code: BRIDGE_CODE.INVALID_INPUT, error: 'sessionId required' }
+      if (!body.trim() || Buffer.byteLength(body, 'utf8') > 4096) return { ok: false, code: BRIDGE_CODE.INVALID_INPUT, error: 'text must be 1-4096 bytes' }
+      const out = await call('POST', `/v1/sessions/${encodeURIComponent(id)}/messages`, { text: body })
+      if (!out.ok) return out
+      return { ok: true, accepted: out.data?.accepted === true, requestId: out.data?.requestId ?? null }
+    },
+    async create(input = {}) {
+      const cwd = String(input.cwd ?? '').trim()
+      if (!cwd) return { ok: false, code: BRIDGE_CODE.INVALID_INPUT, error: 'cwd required' }
+      const out = await call('POST', '/v1/sessions', { cwd, ...(input.title ? { title: String(input.title) } : {}) })
+      if (!out.ok) return out
+      return { ok: true, session: out.data }
+    },
+  }
+}

package/src/lib/broker-adapter.mjs

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// v3.0.9 read-only broker adapter: issues only read capabilities. Write is intentionally absent.
+const READ_ROOTS = new Set(['essence', 'sessions'])
+
+export function issueReadCapability(broker, identity, root) {
+  if (!READ_ROOTS.has(root)) throw new Error('read-root-not-allowed')
+  const role = identity?.role
+  if (!role) throw new Error('identity-missing')
+  return broker.issue({
+    role,
+    root,
+    op: 'read',
+    essenceId: String(identity.essenceId || ''),
+    forkId: String(identity.forkId || ''),
+  })
+}
+
+export function checkReadCapability(broker, token, scope) {
+  if (!READ_ROOTS.has(scope?.root)) return { ok: false, error: 'access-denied', reason: 'read-root-not-allowed' }
+  return broker.resolve({
+    token,
+    root: scope.root,
+    op: 'read',
+    essenceId: scope.essenceId || '',
+    ownerEssenceId: scope.ownerEssenceId || '',
+    forkId: scope.forkId || '',
+    ownerForkId: scope.ownerForkId || '',
+    path: scope.path || '',
+  })
+}
+
+function headerValue(headers, name) {
+  const key = Object.keys(headers || {}).find((k) => k.toLowerCase() === name)
+  return key ? headers[key] : ''
+}
+
+export function resolveIdentity({ headers = {}, url = '/' }, resolveToken) {
+  const auth = String(headerValue(headers, 'x-fang-auth') || '')
+  const bearer = /^Bearer\s+(.+)$/i.exec(String(headerValue(headers, 'authorization') || ''))?.[1] || ''
+  let query = ''
+  try { query = new URL(url, 'http://127.0.0.1').searchParams.get('token') || '' } catch { /* ignore */ }
+  const token = auth || bearer || query
+  if (!token) return { ok: false, status: 401, error: 'unauthorized' }
+  if (typeof resolveToken !== 'function') return { ok: false, status: 401, error: 'unauthorized' }
+  const identity = resolveToken(token)
+  if (!identity) return { ok: false, status: 401, error: 'unauthorized' }
+  if (identity.denied) return { ok: false, status: 403, error: 'access-denied', reason: String(identity.reason || 'denied') }
+  if (!identity.role) return { ok: false, status: 401, error: 'unauthorized' }
+  return {
+    ok: true,
+    token,
+    role: String(identity.role),
+    essenceId: String(identity.essenceId || ''),
+    forkId: String(identity.forkId || ''),
+  }
+}
+
+export function denialToHttp(result) {
+  if (result?.ok) return null
+  const status = result?.status === 403 ? 403 : 401
+  return {
+    status,
+    body: status === 403
+      ? { ok: false, error: 'access-denied', reason: String(result?.reason || 'denied') }
+      : { ok: false, error: 'unauthorized' },
+  }
+}

package/src/lib/broker.mjs

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import crypto from 'node:crypto'
+import { canAccess } from './roots.mjs'
+
+export class Broker {
+  constructor(secret) {
+    this.secret = secret || crypto.randomBytes(32)
+    this.audit = []
+  }
+
+  issue({ role, root, op, essenceId = '', forkId = '', ttlMs = 60_000 }) {
+    const payload = Buffer.from(JSON.stringify({ role, root, op, essenceId, forkId, exp: Date.now() + ttlMs })).toString('base64url')
+    const sig = crypto.createHmac('sha256', this.secret).update(payload).digest('base64url')
+    return `${payload}.${sig}`
+  }
+
+  verify(token) {
+    const [payload, sig] = String(token || '').split('.')
+    if (!payload || !sig) return null
+    const expected = crypto.createHmac('sha256', this.secret).update(payload).digest('base64url')
+    if (sig.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) return null
+    try {
+      const caps = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'))
+      if (!caps.exp || caps.exp < Date.now()) return null
+      return caps
+    } catch { return null }
+  }
+
+  resolve({ token, root, op, essenceId = '', ownerEssenceId = '', forkId = '', ownerForkId = '', path = '' }) {
+    const caps = this.verify(token)
+    const deny = (reason) => {
+      this.audit.push({ ok: false, reason, root, op, essenceId, forkId, at: Date.now() })
+      return { ok: false, error: 'access-denied', reason }
+    }
+    if (!caps) return deny('bad-capability')
+    if (caps.root !== root || caps.op !== op) return deny('capability-mismatch')
+    if (caps.role !== 'coordinator' && caps.essenceId && ownerEssenceId && caps.essenceId !== ownerEssenceId) return deny('wrong-essence')
+    if (caps.role === 'fork' && caps.forkId && ownerForkId && caps.forkId !== ownerForkId) return deny('wrong-fork')
+    const allowed = canAccess({ role: caps.role, root, op, essenceId: caps.essenceId || essenceId, ownerEssenceId, forkId: caps.forkId || forkId, ownerForkId, path })
+    if (!allowed) return deny('matrix')
+    this.audit.push({ ok: true, root, op, essenceId: caps.essenceId, forkId: caps.forkId, at: Date.now() })
+    return { ok: true, role: caps.role }
+  }
+}

package/src/lib/business-producers.mjs

@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+//
+// business-producers — 业务生产者 → 决策中心的命名适配层（P4 业务接入契约）。
+//
+// 这不是“外部系统已接”：HarnessMM/PluginUpdater/SuperAgent/PJM/Worker 的本体不在
+// 本仓。本模块给它们一个**明确、稳定、可测试**的调用面；只要在各自进程里调用对应
+// 方法（或等价 ingest payload），就会生成正确等级/kind/dedupeKey 的 ticket。
+import { nowMs } from '../kernel/index.mjs'
+
+/** 把外部系统的动作映射成 decision-center ingest/submit 的稳定 payload。 */
+export function createBusinessProducers({ submit, now = nowMs } = {}) {
+  if (typeof submit !== 'function') throw new TypeError('createBusinessProducers: submit required')
+  const send = (payload) => submit({ ...payload, at: now() })
+
+  return {
+    /** MirrorUpgrade 成功但需要重启宿主：红色，动作 confirm_restart。 */
+    mirrorUpgradeRestartRequired({ from = 'unknown', to = 'unknown', reason = '' } = {}) {
+      return send({
+        producer: 'MirrorUpgrade', kind: 'mirror-upgrade', level: 'red',
+        title: '镜像升级完成，需重启宿主',
+        context: `镜像已从 ${from} 切换到 ${to}${reason ? `（${reason}）` : ''}；重启后新镜像才会完全生效。`,
+        actions: [
+          { id: 'confirm_restart', label: '立即重启', type: 'primary' },
+          { id: 'later', label: '稍后', type: 'default' },
+        ],
+        dedupeKey: `mirror-upgrade:restart:${from}->${to}`,
+      })
+    },
+    /** MirrorUpgrade 失败/exception。 */
+    mirrorUpgradeFailed({ from = 'unknown', to = null, reason = 'unknown', level = 'yellow' } = {}) {
+      return send({
+        producer: 'MirrorUpgrade', kind: 'mirror-upgrade', level,
+        title: '母体镜像升级失败',
+        context: `镜像升级未成功：${reason}${from ? `（from ${from}${to ? ` -> ${to}` : ''}）` : ''}`,
+        actions: [{ id: 'retry', label: '重试升级', type: 'primary' }, { id: 'ignore', label: '忽略', type: 'default' }],
+        dedupeKey: `mirror-upgrade:failed:${reason}`.slice(0, 200),
+      })
+    },
+    /** EssenceManager 合并冲突：黄色，合并同一 essence 的冲突。 */
+    essenceConflict({ essenceId = 'unknown', conflicts = [], severity = 'warning' } = {}) {
+      return send({
+        producer: 'EssenceManager', kind: 'essence-conflict', level: severity === 'fatal' ? 'red' : 'yellow',
+        title: `元主合并冲突：${essenceId}`,
+        context: `essence=${essenceId}; conflicts=${Array.isArray(conflicts) ? conflicts.length : 0}`,
+        actions: [{ id: 'review', label: '查看冲突', type: 'primary' }, { id: 'ignore', label: '忽略', type: 'default' }],
+        dedupeKey: `essence-conflict:${essenceId}`,
+      })
+    },
+    /** HarnessMM 优化建议：蓝色（异步建议，不阻塞）。 */
+    harnessmmSuggestion({ id = null, summary = '', score = null } = {}) {
+      return send({
+        producer: 'HarnessMM', kind: 'harnessmm-suggestion', level: 'blue',
+        title: summary || 'HarnessMM 优化建议',
+        context: `suggestion=${id ?? 'n/a'}; score=${score ?? 'n/a'}`,
+        actions: [{ id: 'accept', label: '采纳', type: 'default' }, { id: 'ignore', label: '忽略', type: 'default' }],
+        dedupeKey: id ? `harnessmm:${id}` : undefined,
+      })
+    },
+    /** PluginUpdater 备份完成通知：绿色（FYI）。 */
+    pluginUpdaterBackup({ pluginId = 'unknown', backupId = null } = {}) {
+      return send({
+        producer: 'PluginUpdater', kind: 'plugin-updater-backup', level: 'green',
+        title: `插件更新前备份完成：${pluginId}`,
+        context: `plugin=${pluginId}; backup=${backupId ?? 'n/a'}`,
+        dedupeKey: backupId ? `plugin-updater:backup:${backupId}` : undefined,
+      })
+    },
+    /** SuperAgent 任务完成汇报：绿色。 */
+    superagentCompletion({ taskId = null, summary = '' } = {}) {
+      return send({
+        producer: 'SuperAgent', kind: 'superagent-completion', level: 'green',
+        title: summary || 'SuperAgent 任务完成',
+        context: `task=${taskId ?? 'n/a'}`,
+        dedupeKey: taskId ? `superagent:completed:${taskId}` : undefined,
+      })
+    },
+    /** PJM 超时：黄色 + 默认 5 分钟自动转灰。 */
+    pjmTimeout({ projectId = null, phase = 'unknown', timeoutMinutes = 5 } = {}) {
+      return send({
+        producer: 'PJM', kind: 'pjm-timeout', level: 'yellow', timeoutMinutes,
+        title: `PJM 超时：${projectId ?? 'unknown'}`,
+        context: `project=${projectId ?? 'n/a'}; phase=${phase}`,
+        actions: [{ id: 'retry', label: '重试', type: 'primary' }, { id: 'abandon', label: '放弃', type: 'default' }],
+        dedupeKey: projectId ? `pjm:timeout:${projectId}:${phase}` : undefined,
+      })
+    },
+    /** PJM 致命错误：黄色（需要人看，但不阻塞整个 Agent）。 */
+    pjmFatal({ projectId = null, error = 'unknown' } = {}) {
+      return send({
+        producer: 'PJM', kind: 'pjm-fatal', level: 'yellow',
+        title: `PJM 致命错误：${projectId ?? 'unknown'}`,
+        context: `project=${projectId ?? 'n/a'}; error=${String(error).slice(0, 500)}`,
+        actions: [{ id: 'retry', label: '重试', type: 'primary' }, { id: 'abandon', label: '放弃', type: 'default' }],
+        dedupeKey: projectId ? `pjm:fatal:${projectId}` : undefined,
+      })
+    },
+    /** Worker 跑偏：黄色（可在 payload 带偏离详情）。 */
+    workerDeviation({ workerId = null, taskId = null, detail = '' } = {}) {
+      return send({
+        producer: 'Worker', kind: 'worker-deviation', level: 'yellow',
+        title: `Worker 跑偏：${workerId ?? 'unknown'}`,
+        context: `worker=${workerId ?? 'n/a'}; task=${taskId ?? 'n/a'}; ${String(detail).slice(0, 500)}`,
+        actions: [{ id: 'review', label: '查看', type: 'primary' }, { id: 'ignore', label: '忽略', type: 'default' }],
+        dedupeKey: taskId ? `worker:deviation:${taskId}` : undefined,
+      })
+    },
+  }
+}

package/src/lib/command-cache.mjs

@@ -0,0 +1,209 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+// dsh-Fang v2.6.3 — 幂等命令缓存（in-flight 合并 + completed LRU 淘汰）。
+//
+// 契约：docs/COMMAND-CACHE.md、docs/PROTOCOL-V3.md §6.2。
+// 设计要点：
+//   * 两态：running（value 是同一个 promise）/ completed（value 是结果）；
+//   * 同一 commandId 并发提交 → 第二个调用等待同一个 promise，不重复执行副作用；
+//   * LRU：Map 插入顺序即使用顺序；run() 命中会 touch，纯 get() 不 touch；
+//   * 淘汰：只淘汰 completed，跳过 running；全是 running 时允许临时超限，
+//     等 in-flight 完成后自动收敛；
+//   * 失败契约：fn 返回的业务失败（CommandResult.status='rejected'）**缓存**；
+//     fn 抛错（传输层/编程错误，命令可能没执行）**不缓存并移除**，允许重试重新执行；
+//   * 缓存不实现超时：超时属于命令层（AbortController），缓存层只在得到最终结果后决策。
+export const COMMAND_CACHE_DEFAULT_CAPACITY = 500
+
+/**
+ * @typedef {{state:'running', promise:Promise<any>|null, startedAt:number}} RunningEntry
+ * @typedef {{state:'completed', result:any, completedAt:number}} CompletedEntry
+ * @typedef {RunningEntry|CompletedEntry} CacheEntry
+ */
+
+/**
+ * @typedef {object} CommandCacheOptions
+ * @property {number} [capacity=500] 容量上限（>=1）；超限时只淘汰 completed 项
+ * @property {(commandId:string, entry:CompletedEntry)=>void} [onEvict] 淘汰回调（异常被隔离）
+ * @property {()=>number} [now=Date.now] 时钟注入（测试用）
+ */
+
+export class CommandCache {
+  /** @param {CommandCacheOptions} [options] */
+  constructor({ capacity = COMMAND_CACHE_DEFAULT_CAPACITY, onEvict = null, now = Date.now } = {}) {
+    const cap = Math.floor(Number(capacity))
+    if (!Number.isFinite(cap) || cap < 1) {
+      throw new RangeError('command cache capacity must be an integer >= 1')
+    }
+    this.capacity = cap
+    this.onEvict = typeof onEvict === 'function' ? onEvict : null
+    this.now = typeof now === 'function' ? now : Date.now
+    /** @type {Map<string, CacheEntry>} */
+    this.entries = new Map()
+    this.counters = { executions: 0, hits: 0, dedupHits: 0, evictions: 0, droppedOnError: 0 }
+  }
+
+  /**
+   * 幂等执行：同一 commandId 至多执行一次。
+   * - completed 命中 → 返回缓存结果（并 touch）；
+   * - running 命中 → 返回同一个 promise（并 touch，不重复执行 fn）；
+   * - 未命中 → 执行 fn，完成后写 completed；fn 抛错则移除并抛出。
+   *
+   * 说明：fn 必须把「业务失败」转成结果对象返回；只有「命令没有执行到」的
+   * 传输层/编程错误才允许抛错（这样重试才会重新执行）。
+   *
+   * @param {string} commandId
+   * @param {() => Promise<any>} fn
+   * @returns {Promise<any>}
+   */
+  run(commandId, fn) {
+    const id = normalizeCommandId(commandId)
+    if (typeof fn !== 'function') throw new TypeError('command cache run() requires a function')
+
+    const existing = this.entries.get(id)
+    if (existing) {
+      this.counters.hits += 1
+      this.touch(id)
+      if (existing.state === 'completed') return Promise.resolve(existing.result)
+      this.counters.dedupHits += 1
+      return existing.promise
+    }
+
+    /** @type {RunningEntry} */
+    const entry = { state: 'running', promise: null, startedAt: this.now() }
+    const promise = Promise.resolve()
+      .then(() => {
+        this.counters.executions += 1
+        return fn()
+      })
+      .then(
+        (result) => {
+          // 只有「本次执行」仍然占着这个 commandId 时才落缓存（防御未来 running 失效语义变化）
+          const current = this.entries.get(id)
+          if (current === entry) {
+            this.entries.set(id, { state: 'completed', result, completedAt: this.now() })
+            this.evictIfNeeded()
+          }
+          return result
+        },
+        (error) => {
+          const current = this.entries.get(id)
+          if (current === entry) {
+            this.entries.delete(id)
+            this.counters.droppedOnError += 1
+          }
+          throw error
+        },
+      )
+
+    entry.promise = promise
+    this.entries.set(id, entry)
+    this.evictIfNeeded()
+    // 给 promise 挂一个空 handler：调用方忽略返回值时不会出现 unhandled rejection；
+    // 错误仍会通过上面返回的 promise 交给调用方。
+    promise.catch(() => {})
+    return promise
+  }
+
+  /** 纯查询：只返回 completed 的结果，不改变 LRU 顺序。 */
+  get(commandId) {
+    const entry = this.entries.get(String(commandId ?? ''))
+    return entry && entry.state === 'completed' ? entry.result : undefined
+  }
+
+  /** 是否已有缓存项（running 或 completed 都算）。 */
+  has(commandId) {
+    return this.entries.has(String(commandId ?? ''))
+  }
+
+  /** 手动失效：只对 completed 生效；running 不可失效（避免副作用重复）。 */
+  invalidate(commandId) {
+    const id = String(commandId ?? '')
+    const entry = this.entries.get(id)
+    if (!entry || entry.state !== 'completed') return false
+    this.entries.delete(id)
+    return true
+  }
+
+  /**
+   * 清空所有 completed 项，保留 running。
+   * running 的 promise 还在飞，完成后仍会落缓存（它确实已经执行过）。
+   * @returns {number} 被清掉的 completed 数量
+   */
+  clear() {
+    const completedIds = []
+    for (const [id, entry] of this.entries) {
+      if (entry.state === 'completed') completedIds.push(id)
+    }
+    for (const id of completedIds) this.entries.delete(id)
+    return completedIds.length
+  }
+
+  /** 当前项数（可能暂时超过 capacity：全是 running 时）。 */
+  size() {
+    return this.entries.size
+  }
+
+  /** 容量与状态统计（用于诊断/测试）。 */
+  stats() {
+    let running = 0
+    let completed = 0
+    for (const entry of this.entries.values()) {
+      if (entry.state === 'running') running += 1
+      else completed += 1
+    }
+    return {
+      total: this.entries.size,
+      running,
+      completed,
+      capacity: this.capacity,
+      overCapacity: Math.max(0, this.entries.size - this.capacity),
+      ...this.counters,
+    }
+  }
+
+  /** 把项移到 Map 末尾（最近使用）。 */
+  touch(commandId) {
+    const id = String(commandId ?? '')
+    const entry = this.entries.get(id)
+    if (!entry) return false
+    this.entries.delete(id)
+    this.entries.set(id, entry)
+    return true
+  }
+
+  /**
+   * 容量收敛：从 Map 头开始找最久未用的 completed 项淘汰。
+   * running 项不可淘汰；全是 running 时直接返回（允许临时超限）。
+   */
+  evictIfNeeded() {
+    while (this.entries.size > this.capacity) {
+      let victimId = null
+      for (const [id, entry] of this.entries) {
+        if (entry.state === 'completed') {
+          victimId = id
+          break
+        }
+      }
+      if (victimId === null) return
+      const victim = this.entries.get(victimId)
+      this.entries.delete(victimId)
+      this.counters.evictions += 1
+      if (this.onEvict) {
+        try {
+          this.onEvict(victimId, victim)
+        } catch {
+          /* 淘汰回调异常不得中断容量收敛 */
+        }
+      }
+    }
+  }
+}
+
+/** commandId 必须是非空字符串（Adapter 侧已用正则校验格式）。 */
+function normalizeCommandId(commandId) {
+  const id = String(commandId ?? '').trim()
+  if (!id) throw new TypeError('command cache requires a non-empty commandId')
+  return id
+}
+
+export const _internals = { normalizeCommandId }