@jjh32456/dsh-longlive 1.6.8 → 1.8.0

package/src/adapters/engram/index.js

@@ -0,0 +1,235 @@
+/**
+ * engram 适配器（M2-E 解耦样板）
+ *
+ * 核心代码只通过 src/adapters/registry.js 使用本模块；本目录是唯一允许出现
+ * 第三方插件（engram）包名/工具名/动作名/注入标记字面量的地方。
+ *
+ * 统一接口：{ id, probe, call, health, mode }
+ * - probe():  探测宿主是否提供 engram 能力（按宿主传入的工具清单/显式 mode），返回 { ok, mode, evidence }
+ * - call():   经宿主 invoke 转发一次 engram 工具调用；adapter 缺席时返回降级结果，不抛错
+ * - health(): { id, mode, ok, degraded, detail }，供 doctor/lint/registry 汇总
+ * - mode:     'active' | 'degraded' | 'absent'
+ */
+import { readFileSync } from 'node:fs'
+
+export const ID = 'engram'
+export const PACKAGE_NAME = '@kenz1117/dsh-engram'
+export const ACTION_PREFIX = 'engram.'
+export const TOOL_PREFIX = 'engram_'
+export const PROFILE_EDIT_ACTION = 'engram.profile.edit'
+export const FORGET_ACTION = 'engram.forget'
+export const SAVE_ACTION = 'engram.save'
+export const FACTS_REPLACE_ACTION = 'engram.facts.replace'
+export const CLASSIFY_PLUGIN_LABEL = 'plugin:dsh-engram'
+export const EVIDENCE_PREFIX = 'engram:'
+export const LEGACY_TOOL_NAMES = Object.freeze(['memory_save'])
+export const INTERCEPTED_WRITE_TOOLS = Object.freeze([
+  'engram_save',
+  'engram_update',
+  'engram_facts',
+  'engram_forget',
+  'engram_profile_edit',
+])
+export const ACTION_NAMES = Object.freeze([
+  'engram.search',
+  'engram.save',
+  'engram.facts.replace',
+  'engram.forget',
+  'engram.profile.edit',
+])
+export const LEGACY_WRITE_TOOL_NAMES = Object.freeze(['memory_save'])
+export const WRITE_TOOL_NAMES = Object.freeze(['memory_save', 'engram_save', 'engram_update', 'engram_facts', 'engram_forget', 'engram_profile_edit'])
+export const ACTION_GROUPS = Object.freeze({
+  approval: ['engram.forget'],
+  write: ['engram.save', 'engram.facts.replace'],
+  profileEdit: ['engram.profile.edit'],
+})
+export const DEGRADE_TARGETS = Object.freeze({
+  'engram.search': 'live',
+  'engram.save': 'topics',
+  'engram.facts.replace': 'topics',
+  'engram.forget': 'topics',
+  'engram.profile.edit': 'topics',
+})
+export const SESSION_MARKER_PATTERNS = Object.freeze([
+  /<engram_profile\b/i,
+  /<engram_memory_context\b/i,
+])
+
+const DATA_FILES = Object.freeze({
+  'routing-rules': { url: new URL('./data/routing-rules.json', import.meta.url), sourcePath: 'src/adapters/engram/data/routing-rules.json' },
+  aliases: { url: new URL('./data/aliases.json', import.meta.url), sourcePath: 'src/adapters/engram/data/aliases.json' },
+  policy: { url: new URL('./data/policy.json', import.meta.url), sourcePath: 'src/adapters/engram/data/policy.json' },
+})
+const dataCache = new Map()
+
+/**
+ * 读取 adapter 数据文件；缺失/坏 JSON 一律 fail-safe：返回 ok:false + 错误记录，
+ * 由调用方（registry/核心 loader）降级继续跑，不抛错。
+ */
+export function loadData(kind) {
+  if (dataCache.has(kind)) return dataCache.get(kind)
+  const entry = DATA_FILES[kind]
+  let result
+  if (!entry) {
+    result = { ok: false, kind, data: null, text: '', sourcePath: '', error: { code: 'E_ADAPTER_DATA_UNKNOWN', message: `未知 adapter 数据：${String(kind)}` } }
+  } else {
+    try {
+      const text = readFileSync(entry.url, 'utf8')
+      result = { ok: true, kind, data: JSON.parse(text), text, sourcePath: entry.sourcePath, error: null }
+    } catch (cause) {
+      result = {
+        ok: false,
+        kind,
+        data: null,
+        text: '',
+        sourcePath: entry.sourcePath,
+        error: {
+          code: cause && cause.code === 'ENOENT' ? 'E_ADAPTER_DATA_MISSING' : 'E_ADAPTER_DATA_INVALID',
+          message: `${kind} 数据不可用：${cause && cause.message ? cause.message : String(cause)}`,
+        },
+      }
+    }
+  }
+  dataCache.set(kind, result)
+  return result
+}
+
+export function resetDataCacheForTests() {
+  dataCache.clear()
+}
+
+export function isEngramToolName(name) {
+  if (typeof name !== 'string') return false
+  const trimmed = name.trim()
+  if (!trimmed) return false
+  return trimmed.startsWith(TOOL_PREFIX) || LEGACY_TOOL_NAMES.includes(trimmed)
+}
+
+export function isEngramActionName(name) {
+  if (typeof name !== 'string') return false
+  const trimmed = name.trim()
+  return trimmed.startsWith(ACTION_PREFIX) || trimmed.startsWith(TOOL_PREFIX)
+}
+
+function normalizeMode(value) {
+  return value === 'active' || value === 'degraded' || value === 'absent' ? value : null
+}
+
+/**
+ * @param {object} [options]
+ * @param {() => string[]} [options.tools] 宿主可用工具名列表（探测依据，不 import 第三方）
+ * @param {string} [options.mode] 显式覆盖 mode（测试/配置用）
+ * @param {(tool: string, args: object) => any} [options.invoke] 宿主工具调用通道
+ * @param {() => any} [options.afterProbe]
+ */
+export function createEngramAdapter(options = {}) {
+  const toolsProvider = typeof options.tools === 'function' ? options.tools : () => (Array.isArray(options.tools) ? options.tools : [])
+  const invoke = typeof options.invoke === 'function' ? options.invoke : null
+  const forcedMode = normalizeMode(options.mode)
+  let last = null
+
+  function probe() {
+    if (forcedMode) {
+      last = { ok: forcedMode !== 'absent', mode: forcedMode, evidence: ['explicit-mode'], at: null }
+      return last
+    }
+    let tools = []
+    try {
+      const value = toolsProvider()
+      tools = Array.isArray(value) ? value : []
+    } catch {
+      tools = []
+    }
+    const hits = tools.filter(isEngramToolName)
+    const mode = hits.length > 0 ? 'active' : 'absent'
+    last = { ok: mode === 'active', mode, evidence: hits.slice(0, 8), at: null }
+    return last
+  }
+
+  function health() {
+    const state = last || probe()
+    return {
+      id: ID,
+      mode: state.mode,
+      ok: state.mode !== 'absent',
+      degraded: state.mode === 'degraded' || state.mode === 'absent',
+      detail: state.mode === 'absent' ? '未探测到 engram 工具，降级为文件记忆（topics/journal）' : state.mode === 'degraded' ? 'engram 部分能力不可用' : 'engram 可用',
+      evidence: state.evidence.slice(),
+    }
+  }
+
+  /** 动作级降级计划：插件缺席时给出降级目标与 degraded 标记，不抛错。 */
+  function plan(actionName) {
+    if (!isEngramActionName(actionName)) {
+      return { ok: false, degraded: false, code: 'E_ADAPTER_ACTION', action: actionName }
+    }
+    const state = last || probe()
+    if (state.mode === 'active') {
+      return { ok: true, degraded: false, mode: state.mode, target: ID, action: actionName }
+    }
+    return {
+      ok: false,
+      degraded: true,
+      mode: state.mode,
+      target: DEGRADE_TARGETS[actionName] || 'topics',
+      action: 'topics.write',
+      fallback: 'file-memory',
+      message: '外部记忆插件不可用：该动作降级到文件记忆（topics/journal），不阻塞',
+    }
+  }
+
+  function call(request = {}) {
+    const tool = typeof request.tool === 'string' ? request.tool : ''
+    if (!isEngramToolName(tool)) {
+      return { ok: false, degraded: false, code: 'E_ADAPTER_TOOL', message: `不是 engram 工具：${tool}` }
+    }
+    const state = last || probe()
+    if (state.mode === 'absent') {
+      return {
+        ok: false,
+        degraded: true,
+        mode: 'absent',
+        code: 'E_ADAPTER_ABSENT',
+        tool,
+        fallbackTarget: 'topics',
+        message: 'engram 不可用：降级到文件记忆（topics/journal），不阻塞',
+      }
+    }
+    if (typeof invoke !== 'function') {
+      return { ok: false, degraded: true, mode: state.mode, code: 'E_ADAPTER_NO_INVOKE', tool, message: '宿主未提供工具调用通道' }
+    }
+    try {
+      return { ok: true, degraded: state.mode !== 'active', mode: state.mode, tool, result: invoke(tool, request.args || {}) }
+    } catch (cause) {
+      return { ok: false, degraded: true, mode: state.mode, code: 'E_ADAPTER_CALL', tool, message: String(cause && cause.message ? cause.message : cause) }
+    }
+  }
+
+  return {
+    id: ID,
+    packageName: PACKAGE_NAME,
+    get mode() {
+      return (last || probe()).mode
+    },
+    probe,
+    call,
+    plan,
+    health,
+    loadData,
+    constants: Object.freeze({
+      ACTION_PREFIX,
+      TOOL_PREFIX,
+      LEGACY_TOOL_NAMES,
+      LEGACY_WRITE_TOOL_NAMES,
+      WRITE_TOOL_NAMES,
+      INTERCEPTED_WRITE_TOOLS,
+      ACTION_NAMES,
+      ACTION_GROUPS,
+      DEGRADE_TARGETS,
+      CLASSIFY_PLUGIN_LABEL,
+      EVIDENCE_PREFIX,
+      SESSION_MARKER_PATTERNS,
+    }),
+  }
+}

package/src/adapters/registry.js

@@ -0,0 +1,315 @@
+/**
+ * 第三方插件适配器注册表（M2-E 解耦的唯一核心入口）
+ *
+ * 设计：核心代码不 import 任何第三方包、不出现第三方包名/工具名/动作名字面量；
+ * 所有第三方接触面（包名、工具名、动作名、规则/别名/策略片段、注入标记）都由
+ * adapter 提供，核心经本 registry 取用。适配器缺席/数据损坏时一律 fail-safe：
+ * 核心照常运行 + 显式 degraded 记录，不抛错、不阻塞。
+ *
+ * 统一接口（每个 adapter 必须提供）：
+ *   { id, probe, call, health, mode }
+ * 可选：loadData(kind) → { ok, data, error }
+ *
+ * 新增第三方插件 = 在 adapters/<id>/ 实现接口 + 在 createDefaultRegistry() 里注册，
+ * 并先登记到 scripts/lint-plugin-independence.mjs。
+ */
+import { createEngramAdapter } from './engram/index.js'
+
+export const ADAPTER_REGISTRY_VERSION = 1
+
+function safeCall(fn, fallback) {
+  try {
+    return typeof fn === 'function' ? fn() : fallback
+  } catch (cause) {
+    return fallback
+  }
+}
+
+/**
+ * 创建一个独立 registry（测试用；生产用默认 registry）。
+ * @param {Array<object>} adapters
+ */
+export function createAdapterRegistry(adapters = []) {
+  const entries = new Map()
+  const problems = []
+
+  const registry = {
+    register(adapter) {
+      if (!adapter || typeof adapter.id !== 'string' || !adapter.id.trim()) {
+        problems.push({ code: 'E_ADAPTER_INVALID', message: 'adapter 缺 id，忽略' })
+        return false
+      }
+      if (entries.has(adapter.id)) {
+        problems.push({ code: 'E_ADAPTER_DUPLICATE', message: `adapter id 重复：${adapter.id}` })
+        return false
+      }
+      entries.set(adapter.id, adapter)
+      return true
+    },
+    get(id) {
+      return entries.get(id) || null
+    },
+    list() {
+      return [...entries.values()]
+    },
+    ids() {
+      return [...entries.keys()]
+    },
+    /** 探测全部 adapter，返回 { modes, degraded, problems }；单个 adapter 抛错不影响整体。 */
+    probeAll(options = {}) {
+      const modes = {}
+      const adapterProblems = []
+      for (const adapter of entries.values()) {
+        const result = safeCall(() => adapter.probe(options), { ok: false, mode: 'absent', evidence: [], error: { code: 'E_ADAPTER_PROBE' } })
+        modes[adapter.id] = result && result.mode ? result.mode : 'absent'
+        if (result && result.error) adapterProblems.push({ adapter: adapter.id, ...result.error })
+      }
+      return {
+        modes,
+        degraded: Object.values(modes).some((mode) => mode !== 'active'),
+        problems: [...adapterProblems],
+      }
+    },
+    /** 汇总 health；供 doctor/lint 输出。 */
+    healthAll(options = {}) {
+      const rows = []
+      for (const adapter of entries.values()) {
+        const health = safeCall(() => adapter.health(options), { id: adapter.id, mode: 'absent', degraded: true, detail: 'health() 异常' })
+        rows.push({ id: adapter.id, mode: health.mode || 'absent', ok: health.ok === true, degraded: health.degraded !== false, detail: health.detail || '' })
+      }
+      return { ok: rows.every((row) => row.ok), rows, problems: [...problems] }
+    },
+    /** 经适配器转发一次调用；adapter 缺席时返回降级结果。 */
+    call(id, request) {
+      const adapter = entries.get(id)
+      if (!adapter) {
+        return { ok: false, degraded: true, mode: 'absent', code: 'E_ADAPTER_UNKNOWN', message: `未注册的 adapter：${String(id)}` }
+      }
+      return safeCall(() => adapter.call(request), { ok: false, degraded: true, mode: 'absent', code: 'E_ADAPTER_CALL', message: 'adapter.call 异常' })
+    },
+    /** 合并各 adapter 的某类数据；失败仅记录 + degraded，不抛错。 */
+    loadData(kind) {
+      const items = []
+      const errors = []
+      const sources = []
+      for (const adapter of entries.values()) {
+        if (typeof adapter.loadData !== 'function') continue
+        const result = safeCall(() => adapter.loadData(kind), { ok: false, error: { code: 'E_ADAPTER_DATA', message: `adapter ${adapter.id} loadData 异常` } })
+        if (!result || !result.ok) {
+          errors.push({ adapter: adapter.id, kind, code: (result && result.error && result.error.code) || 'E_ADAPTER_DATA', message: (result && result.error && result.error.message) || 'adapter 数据不可用' })
+          continue
+        }
+        items.push({ adapter: adapter.id, data: result.data, text: result.text || '', sourcePath: result.sourcePath || '' })
+        sources.push(adapter.id)
+      }
+      return { ok: errors.length === 0, items, sources, errors, degraded: errors.length > 0 }
+    },
+    problems,
+  }
+
+  for (const adapter of adapters) registry.register(adapter)
+  return registry
+}
+
+/** 生产默认 registry：engram 是当前唯一样例；其它第三方插件只登记、不建 adapter。 */
+export function createDefaultRegistry() {
+  return createAdapterRegistry([createEngramAdapter()])
+}
+
+export const defaultRegistry = createDefaultRegistry()
+
+// ── 核心取用面（全部是中性命名，不含第三方字面量） ──────────────────────
+
+export function adapterHealth() {
+  return defaultRegistry.healthAll()
+}
+
+export function adapterModes() {
+  return defaultRegistry.probeAll().modes
+}
+
+export function adapterEntries() {
+  return defaultRegistry.list().map((adapter) => ({ id: adapter.id, mode: safeCall(() => adapter.mode, 'absent') }))
+}
+
+export function adapterCall(id, request) {
+  return defaultRegistry.call(id, request)
+}
+
+/** 合并 adapter 提供的路由规则（保留 adapter 侧 _order 以复原原表顺序）。 */
+export function loadAdapterRoutingRules() {
+  const loaded = defaultRegistry.loadData('routing-rules')
+  const rules = []
+  const targets = []
+  const errors = []
+  for (const item of loaded.items) {
+    const data = item.data || {}
+    if (Array.isArray(data.rules)) rules.push(...data.rules)
+    if (Array.isArray(data.targets)) targets.push(...data.targets)
+  }
+  errors.push(...loaded.errors)
+  return { ok: errors.length === 0, rules, targets, items: loaded.items, errors, degraded: errors.length > 0 }
+}
+
+/** 合并 adapter 提供的动作别名。 */
+export function loadAdapterAliases() {
+  const loaded = defaultRegistry.loadData('aliases')
+  const actions = []
+  const errors = [...loaded.errors]
+  for (const item of loaded.items) {
+    const data = item.data || {}
+    if (Array.isArray(data.actions)) actions.push(...data.actions)
+  }
+  return { ok: errors.length === 0, actions, errors, degraded: errors.length > 0 }
+}
+
+/** 把 adapter 的策略片段（forbiddenActions / allowPrefixes）并入一份已校验的 profile。 */
+export function applyAdapterPolicy(policy) {
+  const loaded = defaultRegistry.loadData('policy')
+  if (!loaded.ok || typeof policy !== 'object' || policy === null) {
+    return { policy, degraded: !loaded.ok, errors: loaded.errors }
+  }
+  const next = JSON.parse(JSON.stringify(policy))
+  const forbidden = new Set(next.rest && Array.isArray(next.rest.forbiddenActions) ? next.rest.forbiddenActions : [])
+  const allowed = new Set(next.writeScope && Array.isArray(next.writeScope.allowPrefixes) ? next.writeScope.allowPrefixes : [])
+  for (const item of loaded.items) {
+    const data = item.data || {}
+    for (const action of Array.isArray(data.forbiddenActions) ? data.forbiddenActions : []) forbidden.add(action)
+    for (const prefix of Array.isArray(data.allowPrefixes) ? data.allowPrefixes : []) allowed.add(prefix)
+  }
+  if (next.rest) next.rest.forbiddenActions = [...forbidden]
+  if (next.writeScope) next.writeScope.allowPrefixes = [...allowed]
+  return { policy: next, degraded: false, errors: [] }
+}
+
+export function optionalPeerNames() {
+  return defaultRegistry.list().map((adapter) => adapter.packageName).filter((name) => typeof name === 'string' && name.trim())
+}
+
+export function interceptedToolNames() {
+  const names = []
+  for (const adapter of defaultRegistry.list()) {
+    const constants = adapter.constants || {}
+    for (const name of constants.INTERCEPTED_WRITE_TOOLS || []) names.push(name)
+    for (const name of constants.LEGACY_TOOL_NAMES || []) names.push(name)
+  }
+  return [...new Set(names)]
+}
+
+export function classificationPluginLabels() {
+  return defaultRegistry.list().map((adapter) => adapter.constants && adapter.constants.CLASSIFY_PLUGIN_LABEL).filter(Boolean)
+}
+
+export function injectedMarkerPatterns() {
+  const patterns = []
+  for (const adapter of defaultRegistry.list()) {
+    for (const pattern of (adapter.constants && adapter.constants.SESSION_MARKER_PATTERNS) || []) patterns.push(pattern)
+  }
+  return patterns
+}
+
+export function pluginEvidencePrefixes() {
+  return defaultRegistry.list().map((adapter) => adapter.constants && adapter.constants.EVIDENCE_PREFIX).filter((prefix) => typeof prefix === 'string' && prefix)
+}
+
+// ── 语义判定（核心不关心是哪家插件） ────────────────────────────────
+
+function externalActions() {
+  return defaultRegistry.list().flatMap((adapter) => (adapter.constants && adapter.constants.ACTION_NAMES) || [])
+}
+
+export function isExternalMemoryAction(action) {
+  if (typeof action !== 'string') return false
+  const trimmed = action.trim()
+  if (!trimmed) return false
+  return externalActions().some((name) => trimmed === name) || defaultRegistry.list().some((adapter) => {
+    const prefix = adapter.constants && adapter.constants.ACTION_PREFIX
+    return typeof prefix === 'string' && prefix && trimmed.startsWith(prefix)
+  })
+}
+
+export function isExternalMemoryTarget(target) {
+  if (typeof target !== 'string') return false
+  const trimmed = target.trim()
+  return defaultRegistry.list().some((adapter) => trimmed === adapter.id)
+}
+
+export function isExternalMemoryTool(toolName) {
+  if (typeof toolName !== 'string') return false
+  const trimmed = toolName.trim()
+  return defaultRegistry.list().some((adapter) => {
+    const constants = adapter.constants || {}
+    if ((constants.LEGACY_TOOL_NAMES || []).includes(trimmed)) return true
+    const prefix = constants.TOOL_PREFIX
+    return typeof prefix === 'string' && prefix && trimmed.startsWith(prefix)
+  })
+}
+
+export function isExternalMemoryKind(kind) {
+  if (typeof kind !== 'string') return false
+  return defaultRegistry.list().some((adapter) => kind.includes(adapter.id))
+}
+
+/** 按语义分组取第三方动作名（approval/write/profileEdit 等，由 adapter 声明）。 */
+export function externalActionGroups(group) {
+  const out = []
+  for (const adapter of defaultRegistry.list()) {
+    const groups = adapter.constants && adapter.constants.ACTION_GROUPS
+    if (groups && Array.isArray(groups[group])) out.push(...groups[group])
+  }
+  return [...new Set(out)]
+}
+
+export function planExternalAction(action) {
+  for (const adapter of defaultRegistry.list()) {
+    if (typeof adapter.plan !== 'function') continue
+    const result = safeCall(() => adapter.plan(action), { ok: false, degraded: true, code: 'E_ADAPTER_PLAN' })
+    if (result && result.code !== 'E_ADAPTER_ACTION') return { ...result, adapter: adapter.id }
+  }
+  return { ok: false, degraded: false, code: 'E_ADAPTER_UNKNOWN_ACTION', action }
+}
+
+export function externalProfileEditAction() {
+  return externalActionGroups('profileEdit')[0] || null
+}
+
+export function externalLegacyToolNames() {
+  const out = []
+  for (const adapter of defaultRegistry.list()) {
+    const constants = adapter.constants || {}
+    out.push(...(constants.LEGACY_TOOL_NAMES || []))
+  }
+  return [...new Set(out)]
+}
+
+export function externalWriteToolNames() {
+  const out = []
+  for (const adapter of defaultRegistry.list()) {
+    const constants = adapter.constants || {}
+    out.push(...(constants.WRITE_TOOL_NAMES || []))
+  }
+  return [...new Set(out)]
+}
+
+export function externalLegacyWriteToolNames() {
+  const out = []
+  for (const adapter of defaultRegistry.list()) {
+    const constants = adapter.constants || {}
+    out.push(...(constants.LEGACY_WRITE_TOOL_NAMES || []))
+  }
+  return [...new Set(out)]
+}
+
+export function isExternalMemoryProfileEdit(action) {
+  return defaultRegistry.list().some((adapter) => {
+    const constants = adapter.constants || {}
+    return (constants.ACTION_NAMES || []).includes(action) && action.endsWith('.profile.edit')
+  })
+}
+
+export function isExternalMemoryDeleteAction(action) {
+  return defaultRegistry.list().some((adapter) => {
+    const constants = adapter.constants || {}
+    return (constants.ACTION_NAMES || []).includes(action) && action.endsWith('.forget')
+  })
+}