memory-eternal 0.10.6 → 0.10.8

package/index.js

@@ -19,6 +19,7 @@ import path from 'node:path'
 import os from 'node:os'
 import { spawn } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
+import { randomBytes } from 'node:crypto'
 const __filename = fileURLToPath(import.meta.url)
 const PACKAGE_ROOT = path.resolve(path.dirname(__filename))
 // 插件版本号（供「记忆配置」页面展示）
@@ -76,6 +77,13 @@ export const Config = z.object({
   recallLimit: z.number().min(1).max(20).default(5),
   recallSummaryLen: z.number().min(40).max(400).default(130),
   recallIncludeBody: z.boolean().default(false),
+  // 凭证取用提示（默认空 = 不注入）：写进来的一整句会被追加到每个会话的 systemPrompt 段，
+  // 用来让 agent「需要 API key / token 时先想到去查记忆里的目录卡」。
+  // 为什么做成配置而不是写死：默认值必须对**所有**用户安全 —— 插件本身不假定任何本机
+  // 密钥布局（也不该在公开包里硬编码某台机器的路径）；有需要的用户填一句自己的约定即可。
+  // 参考句式：需要 API key/token 时先查记忆目录卡（memory_recall「密钥 目录」），
+  //          再按卡片给的本机命令取用；禁止直接读凭据文件、禁止把值打印或写进卡片/代码。
+  secretHint: z.string().default(''),
   // 多 Vault / 多 Profile：命名分库，当前激活一个
   vaultProfiles: z.array(z.object({ name: z.string(), path: z.string() })).default([]),
   activeVault: z.string().default(''),
@@ -99,6 +107,12 @@ export const Config = z.object({
   // **v0.6.0 起默认 true**——DSH 进程内 setInterval 在 DSH 退出后失效；
   // 常驻 web 场景需要独立 watchdog；代价是 ~47 MB 额外常驻内存。
   watchdogAutoSpawn: z.boolean().default(true),
+  // 版本漂移自愈（默认开）：常驻 web（7999）比 DSH 活得久 —— 升级 npm 包只换磁盘文件，
+  // 端口上那个进程仍跑着启动时加载的旧代码，而「同端口已有活着的 watchdog 就让位」的策略
+  // 让重启 DSH 永远换不掉它（issue #19/#23）。开启后，激活时若发现**端口上真正服务的版本
+  // ≠ 本机磁盘版本**，就用新代码重启常驻实例（delegate → restart），而不是继续委派给旧实例。
+  // 关掉只是不自动做，面板上的「重启常驻实例」按钮与 dsh-memory restart 始终可用。
+  autoRestartOnDrift: z.boolean().default(true),
   // 回收站保留天数：软删卡超过此天数自动永久删除（默认 30）
   recycleRetentionDays: z.number().min(1).max(3650).default(30),
   // 自动审核配置
@@ -350,6 +364,19 @@ export function apply(ctx, config) {
   // 否则 5 秒一轮的轮询会把日志刷爆）。
   let lastDrainError = ''
   let lastDrainErrorAt = 0
+  // 被本宿主 schema 过滤掉的键（升级期新独立页 + 旧宿主），随 drain 结果回报给独立端
+  let lastDrainIgnored = []
+  // ---- 方案 A：把「应用 pending」搬进宿主允许的上下文（2026-10-08 实测）---------------------------------
+  // 同一个 settings.update：从插件**回调**里调必然被 activation 守卫拒（HMR transactions cannot be
+  // nested，一个字节都不提交）；从插件**HTTP 请求处理器**里调则真的提交（实测 revision 4→6）。
+  // 所以宿主把「自己的监听端口 + 一次性令牌」写进心跳，独立端保存后就地叫醒宿主：
+  // POST /memory-eternal/api/drain-pending（见下面的路由 + lib/config-sync.js 的 triggerHostDrain）。
+  const hostDrainToken = randomBytes(16).toString('hex')
+  let hostDrainPort = 0
+  const beatHostMarker = () => {
+    // 心跳失败不影响主流程：字段缺省时独立端会回落到「等宿主自己 drain」（旧行为）
+    try { writeHostMarker(process.env, { version: versionRef, port: hostDrainPort, token: hostDrainToken }) } catch { /* 心跳失败无妨 */ }
+  }
   const reportDrainError = (error) => {
     const dropped = !!(error && error.dropped)
     const msg = String((error && error.message) || error || '未知错误')
@@ -361,7 +388,10 @@ export function apply(ctx, config) {
       ? '独立 Web 端的配置改动连续失败已放弃（文件保留以便排查）：' + msg
       : '独立 Web 端的配置改动应用失败，将重试：' + msg
     try { console.error('[memory-eternal] ' + why) } catch { /* 日志失败无妨 */ }
-    try { logCapture('system', dropped ? 'fail' : 'warn', why) } catch { /* 日志失败无妨 */ }
+    // 用专用动作而不是 'fail'：logCapture 里 `action==='fail'` 会把**自动沉淀健康状态**翻红，
+    // 于是「配置同步失败」会被念成「自动沉淀异常」（本会话实测：宿主重启前一直挂着这条假警报）。
+    // 配置同步是另一个子系统：照样写进日志/诊断信息，但不冒充沉淀管线坏了。
+    try { logCapture('system', dropped ? 'config-fail' : 'config-warn', why) } catch { /* 日志失败无妨 */ }
   }
   // issue #21：dsh-tui 一类宿主的能力守卫会在 settings.update **内部**的 describe() 上抛
   // 「root.events.emit is unavailable from a plugin activation」（守卫只区分「第三方插件 vs
@@ -374,8 +404,19 @@ export function apply(ctx, config) {
   // AsyncLocalStorage.run(token) 包住每次插件回调，并 patch 了 Fiber._execute，定时器 /
   // fs.watch 的每一次回调都带着 activation token（见 ccch1mneyyy/dsh-TUI#1348 的定位）。
   const applyPendingPatch = async (patch) => {
-    const { applyPatchVerified } = await import('./lib/config-sync.js')
-    return applyPatchVerified(patch, {
+    const { applyPatchVerified, filterKnownKeys } = await import('./lib/config-sync.js')
+    // 只把**本宿主 schema 里存在的键**交给 settings.update。独立 Web 端（新版）提交的是整张表单，
+    // 升级期它可能带上旧宿主还不认识的键（本会话实测：新独立页提交含 secretHint 的整包 → 旧宿主
+    // 按白名单丢掉 secretHint → 回读校验必然对不上 → 连续失败 5 次标 dropped，用户还会看到
+    // 「HMR transactions cannot be nested」这种与配置内容无关的报错）。过滤后：旧宿主只应用它认识的
+    // 那部分，不认识的记一行日志等宿主升级后再生效。
+    const { known: filtered, ignored } = filterKnownKeys(patch, Object.keys(Config.dict || {}))
+    lastDrainIgnored = ignored
+    if (ignored.length) {
+      try { console.error('[memory-eternal] 待应用配置里有本宿主不认识的键（宿主升级后生效）：' + ignored.join(',')) } catch { /* 日志失败无妨 */ }
+    }
+    if (!Object.keys(filtered).length) return { applied: true, repaired: false, ignored }
+    const out = await applyPatchVerified(filtered, {
       apply: (p) => settings.update(p, undefined),
       read: () => settings.get() ?? {},
       onRepaired: (error) => {
@@ -384,8 +425,15 @@ export function apply(ctx, config) {
         } catch { /* 日志失败无妨 */ }
       },
     })
+    return { ...out, ignored }
   }
+  /**
+   * 应用一次 pending，并把结果**返回**给调用方（不再只是写日志）。
+   * 返回结构同时服务两条路：5 秒轮询 / fs.watch（忽略返回值）与 drain 路由（要如实回报给独立端）。
+   * @returns {Promise<{applied:string[], ignored:string[], error:string, dropped:boolean}>}
+   */
   const drainPending = async () => {
+    lastDrainIgnored = []
     try {
       const { drainPendingConfig } = await import('./lib/config-sync.js')
       const applied = await drainPendingConfig(process.env, applyPendingPatch)
@@ -394,10 +442,13 @@ export function apply(ctx, config) {
         syncConfigFile()
         syncAudit()
         try { console.error('[memory-eternal] 已应用独立 Web 端的配置改动: ' + Object.keys(applied).join(',')) } catch { /* 日志失败无妨 */ }
+        return { applied: Object.keys(applied), ignored: lastDrainIgnored, error: '', dropped: false }
       }
+      return { applied: [], ignored: lastDrainIgnored, error: '', dropped: false }
     } catch (error) {
       // 失败时保留文件由 config-sync.js 负责；这里只保证「失败可见」
       reportDrainError(error)
+      return { applied: [], ignored: lastDrainIgnored, error: String((error && error.message) || error), dropped: Boolean(error && error.dropped) }
     }
   }
   drainPending()
@@ -422,7 +473,7 @@ export function apply(ctx, config) {
   // 直接写共享配置（绕过会与宿主的 volatile 配置分叉）。心跳必须定期刷新：进程被硬杀时
   // 没有机会删文件，独立端靠「新鲜度 + pid 存活」两个条件判定，所以宁可多刷几次。
   ctx.effect(() => {
-    const beat = () => { try { writeHostMarker(process.env, { version: versionRef }) } catch { /* 心跳失败不影响主流程 */ } }
+    const beat = () => beatHostMarker()
     beat()
     // unref：心跳只是「我在跑」的旁证，不该成为阻止进程退出的最后一根钉子
     // （测试里以假 ctx 跑 apply() 时会因此挂住不退，实测过一次）。
@@ -812,6 +863,11 @@ export function apply(ctx, config) {
         ...((cfg.auditMode ?? 'all') === 'none' ? [] : [
           '6. **审核红线（强制）**：写卡一律停在 pending，由用户在「审核中心」审批。**禁止**调用 /memory-eternal/api/audit/approve 或 /audit/reject 代替用户审批，也不得用任何等价方式绕过审核；用户说「记录一下 / 增加记忆」不等于允许免审入库。需要立刻可用时，写卡后明确告知用户「已进审核中心，待批准」。',
         ]),
+        // 凭证取用提示（用户自己填的整句，见 Config.secretHint）：只在填了非空值时注入。
+        // 为什么走 systemPrompt 而不是「往卡里写值」：密钥的**值**入库会被每次召回带进模型
+        // 上下文（card.summary = 正文前 200 字，召回默认取前 130 字），而 agent 真正需要的
+        // 只是「去哪取、怎么取」——这句负责**触发**，目录卡负责细节，值留在本机凭据库。
+        ...((cfg.secretHint || '').trim() ? [String(cfg.secretHint).trim()] : []),
       ].join('\n')
       // 异常提示：沉淀管线坏了，靠这一句把消息送到用户面前（不依赖用户去翻页面）。
       const h = health.snapshot()
@@ -843,7 +899,9 @@ export function apply(ctx, config) {
       name: 'memory_recall',
       description:
         '从本地记忆核心（Markdown 知识库）检索相关知识卡。需要项目背景、历史决策、之前讨论过的方案、' +
-        '或领域知识时调用；返回最相关的卡片摘要。用 query 描述要找的内容，支持中文整词与字符片段检索。',
+        '或领域知识时调用；返回最相关的卡片摘要。用 query 描述要找的内容，支持中文整词与字符片段检索。' +
+        '需要 API key / token / 令牌等**凭证**时也先查这里（查「密钥 目录」）：记忆里存的是目录' +
+        '（名字、存放位置、取用命令），**值不在记忆库里**，请按卡片给的本机命令取用，不要直接读凭据文件。',
       parameters: {
         query: { type: 'string', required: true, description: '检索关键词或自然语言描述，如「数据库选型」「用户偏好」' },
         limit: { type: 'number', description: '返回卡片数上限，默认 5' },
@@ -956,6 +1014,10 @@ export function apply(ctx, config) {
   // 没有该服务的 profile（如 TUI）里子 fiber 保持 pending，主插件照常激活。
   // （DSH 自身的 dsh-client-modules 也是这么写的：ctx.inject(['webServer'], …)）
   const registerApiRoutes = (webServer) => {
+    // webServer 是晚到服务：它一就绪就把「监听端口」记下来并立刻刷新心跳 —— 独立端靠这个端口
+    // 把 drain 请求发回来（port=0 时独立端自动回落到旧的「等宿主自己 drain」行为）。
+    hostDrainPort = Number(webServer.port) || 0
+    beatHostMarker()
     const handleApi = createApi({
       vaultDir, vaultRoots, getSettings: settings.get,
       // 自动沉淀运行轨迹 + 健康状态：供「用量/今日」页排查「为什么没写卡」，异常时页面顶部亮红。
@@ -1016,16 +1078,33 @@ export function apply(ctx, config) {
             }
             return
           }
+          if (pathname === API_PREFIX + '/drain-pending') {
+            // 独立端保存后叫醒宿主（#方案 A）：**HTTP 请求上下文**是宿主允许写配置的地方 ——
+            // 实测同一个 settings.update 从回调里调必被 activation 守卫拒、从请求里调则真提交。
+            // 两道闸门写在 lib/config-sync.js（有单测）：只接受本机来源 + 心跳里的一次性令牌。
+            const { drainRequestError } = await import('./lib/config-sync.js')
+            const deny = drainRequestError(
+              { method: req.method, headers: req.headers, remoteAddress: req.socket && req.socket.remoteAddress },
+              hostDrainToken,
+            )
+            if (deny) return json(res, deny === '需 POST' ? 405 : 403, { ok: false, error: deny })
+            // 端口可能刚刚才就绪（webServer 是晚到服务）：顺手把心跳里的端口刷新到最新
+            if (Number(webServer.port) !== hostDrainPort) { hostDrainPort = Number(webServer.port) || 0; beatHostMarker() }
+            const drained = await drainPending()
+            if (drained.applied.length) hub.broadcast('config', { at: Date.now(), source: 'drain-request', applied: drained.applied })
+            // 失败也回 200：调用方要读到具体原因，而不是一个没有 body 的 500
+            return json(res, 200, { ok: !drained.error, ...drained })
+          }
           if (pathname === API_PREFIX + '/config') {
             const method = req.method || 'GET'
             if (method === 'GET') {
               const cfg = settings.get() ?? {}
               // 只暴露可安全展示/回填的字段
               const safe = {
-                autoCapture: cfg.autoCapture, autoRecall: cfg.autoRecall, recallLimit: cfg.recallLimit, recallSummaryLen: cfg.recallSummaryLen, recallIncludeBody: cfg.recallIncludeBody,
+                autoCapture: cfg.autoCapture, autoRecall: cfg.autoRecall, recallLimit: cfg.recallLimit, recallSummaryLen: cfg.recallSummaryLen, recallIncludeBody: cfg.recallIncludeBody, secretHint: cfg.secretHint || '',
                 captureMinChars: cfg.captureMinChars, captureCooldownMs: cfg.captureCooldownMs, dedupThreshold: cfg.dedupThreshold, maxCardsPerDay: cfg.maxCardsPerDay,
                 distillEnabled: cfg.distillEnabled, dedupByLLM: cfg.dedupByLLM, captureMaxTokens: cfg.captureMaxTokens, recallMinScore: cfg.recallMinScore,
-                autoWeb: cfg.autoWeb, autoWebMode: cfg.autoWebMode, webPort: cfg.webPort, webCheckIntervalMs: cfg.webCheckIntervalMs, webMaxRestart: cfg.webMaxRestart, watchdogAutoSpawn: cfg.watchdogAutoSpawn, autoMcpSetup: cfg.autoMcpSetup,
+                autoWeb: cfg.autoWeb, autoWebMode: cfg.autoWebMode, webPort: cfg.webPort, webCheckIntervalMs: cfg.webCheckIntervalMs, webMaxRestart: cfg.webMaxRestart, watchdogAutoSpawn: cfg.watchdogAutoSpawn, autoRestartOnDrift: cfg.autoRestartOnDrift, autoMcpSetup: cfg.autoMcpSetup,
                 auditMode: cfg.auditMode ?? 'all', auditExemptAgents: cfg.auditExemptAgents || [], auditExemptKinds: cfg.auditExemptKinds || [], recycleRetentionDays: cfg.recycleRetentionDays ?? 30,
                 // 多库（#10）：配置页可直接编辑
                 vaultProfiles: Array.isArray(cfg.vaultProfiles) ? cfg.vaultProfiles : [],
@@ -1088,7 +1167,7 @@ export function apply(ctx, config) {
                     retried: !!(writeResult && writeResult.retried),
                     note: pending.length
                       ? '已写入；宿主尚未回流这些值（面板已本地生效，重启 DSH 后以配置文件为准）'
-                      : '已保存。autoWebMode/watchdogAutoSpawn 等需重启 DSH 生效；若已有常驻 watchdog，关闭/改参不会自动停掉它，需 dsh-memory stop / restart（#19）',
+                      : '已保存。autoWebMode/watchdogAutoSpawn/webPort 等需重启 DSH 生效；若已有常驻 watchdog，关闭/改参不会自动停掉它，需 dsh-memory stop / restart（#19）。版本漂移（升级后端口上仍是旧代码）由 autoRestartOnDrift 在下次激活时自动重启常驻实例，也可在「插件信息」点「重启常驻实例」立刻处理',
                   })
                 } catch (e) {
                   if (e && e.code === 'SETTINGS_CONFLICT') return json(res, 409, { ok: false, error: '配置已被外部修改，请刷新后重试（revision conflict）' })
@@ -1204,22 +1283,59 @@ export function apply(ctx, config) {
     const wdPort = Number(cfg0.webPort) || 7999
     if (cfg0.watchdogAutoSpawn === true && cfg0.autoWeb !== false) {
       import('./lib/watchdog.js')
-        .then((m) => {
-          // 同端口已有**活着的** watchdog 时不再 spawn（issue #19）：旧实现每次都 spawn 一个、
-          // 每次都打印 "spawned"，而新进程会在锁上让位退出 —— 日志与实际状态完全相反，
-          // 排查时必然误判。这里如实打印 delegated，并提示版本漂移与替换命令。
-          const lock = m.readWatchdogLock(process.env)
-          const existing = lock.watchdogs.find((w) => Number(w.port) === wdPort && m.isPidAlive(w.pid))
-          if (existing) {
-            const cur = m.currentPkgVersion()
-            const stale = !!(existing.pkgVersion && cur && existing.pkgVersion !== cur)
-            const why = stale
-              ? `watchdog delegated to existing pid=${existing.pid} port=${wdPort}（常驻实例是旧版 v${existing.pkgVersion}，当前 v${cur}；如需换新版请执行 dsh-memory restart --port ${wdPort}）`
-              : `watchdog delegated to existing pid=${existing.pid} port=${wdPort}（同端口已有常驻实例，本次不再 spawn）`
+        .then(async (m) => {
+          // 先体检再决策（issue #19/#23）：同端口已有**活着的** watchdog 时不再 spawn ——
+          // 旧实现每次都 spawn 一个、每次都打印 "spawned"，而新进程会在锁上让位退出，
+          // 日志与实际状态完全相反。但「有实例在跑」不等于「跑的是新代码」：常驻 web 比
+          // DSH 活得久，升级只换磁盘文件，所以这里问的是**端口上真正服务的版本**，
+          // 漂移就用新代码重启它（autoRestartOnDrift），而不是继续委派给旧代码。
+          const info = await m.inspectResident({ port: wdPort })
+          const cur = m.currentPkgVersion()
+          const decision = m.decideResidentAction({
+            served: info.served,
+            expect: cur,
+            watchdogAlive: info.watchdogAlive,
+            occupantIsOurs: info.occupantIsOurs,
+            autoRestart: cfg0.autoRestartOnDrift !== false,
+            residentStartedAt: info.residentStartedAt,
+          })
+          const servedLabel = info.served || '（旧版不自报版本）'
+
+          if (decision.action === 'delegate') {
+            const who = info.watchdog ? `pid=${info.watchdog.pid}` : '外部实例'
+            const why = `watchdog delegated to ${who} port=${wdPort}（端口上服务 v${servedLabel}，本机 v${cur || '?'}${decision.reason === 'debounced' ? '；刚替换过，防抖窗口内不重复重启' : ''}）`
             console.error(`[memory-eternal] ${why}`)
-            logCapture('system', stale ? 'warn' : 'boot', why)
+            logCapture('system', 'boot', why)
             return
           }
+
+          if (decision.action === 'restart') {
+            // 「更新运行中的程序」的唯一安全形态 = 用新代码重启那个常驻进程（不是热替换内存里的模块）
+            const why = `版本漂移：端口 ${wdPort} 上服务 v${servedLabel} ≠ 本机 v${cur}（${decision.reason}）→ 用新代码重启常驻实例`
+            console.error(`[memory-eternal] ${why}`)
+            logCapture('system', 'warn', why)
+            const out = await m.restartResident({
+              port: wdPort,
+              vaultRoot: vaultDir(),
+              interval: Number(cfg0.webCheckIntervalMs) || 5000,
+              maxRestart: Number(cfg0.webMaxRestart) || 10,
+            })
+            const done = out.ok
+              ? `常驻实例已重启：端口 ${wdPort} 正在服务 v${out.served}（等待 ${Math.round(out.waitedMs / 1000)}s）`
+              : `常驻实例重启未确认生效（${out.stage}）：${out.error || '未知原因'} —— 可再试「设置 → 记忆 → 插件信息 → 重启常驻实例」，或执行 dsh-memory restart --port ${wdPort}`
+            console.error(`[memory-eternal] ${done}`)
+            logCapture('system', out.ok ? 'boot' : 'fail', done)
+            return
+          }
+
+          if (decision.action === 'warn') {
+            const why = `常驻实例版本漂移（端口上服务 v${servedLabel} ≠ 本机 v${cur}），但 autoRestartOnDrift 已关闭 → 不自动重启；可点面板「重启常驻实例」或执行 dsh-memory restart --port ${wdPort}`
+            console.error(`[memory-eternal] ${why}`)
+            logCapture('system', 'warn', why)
+            return
+          }
+
+          // 端口上没有我们的服务（也没人占着）→ 照常拉起一个常驻 watchdog
           const port = wdPort
           // 用 nodeBinary() 而非 process.execPath：Electron 宿主下后者是 Electron
           // 主程序，spawn 出来不会执行 watchdog.js（见 lib/node-bin.js）。

package/lib/api.js

@@ -20,6 +20,7 @@ import { buildDiagnostics } from './feedback.js'
 import { getSetupStatus, runSetup, mcpAgentAction } from './setup.js'
 import { backupDb } from './db.js'
 import { createHub } from './sse.js'
+import { probeServedVersion, restartResident, currentPkgVersion } from './watchdog.js'
 
 // 独立 web 的 SSE 中心：配置/数据变更即时推给已打开的页面（无需手动刷新）
 const hub = createHub()
@@ -31,6 +32,48 @@ export const API_PREFIX = '/memory-eternal/api'
 // npm 最新版本缓存（避免每次点「检查更新」都打 registry）
 const versionCache = { at: 0, latest: '' }
 
+// 「重启常驻实例」的并发闸门：连点两次不能起两个替换助手（后一个会让位退出，但白折腾一次）
+let residentRestarting = false
+
+/** 解析 `x.y.z[-pre]`；解析不出来返回 null。 */
+export function parseVersion(v) {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(String(v || '').trim())
+  if (!m) return null
+  return { nums: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] || '' }
+}
+
+/**
+ * 比较两个版本号（a>b → 1）。
+ *
+ * 为什么需要：`latest !== onDisk` 这种判断在**本地跑着未发布版本**时会给出误导性结论
+ * （磁盘 v0.10.7、npm 还是 v0.10.6 → 面板提示「有新版本」并让你装回旧的）。
+ * 预发布标识按 semver 口径比（点分标识、数字段按数值比）—— `rc.2 < rc.10` 不是字符串比较。
+ */
+export function compareVersions(a, b) {
+  const A = parseVersion(a)
+  const B = parseVersion(b)
+  if (!A || !B) return 0
+  for (let i = 0; i < 3; i++) if (A.nums[i] !== B.nums[i]) return A.nums[i] < B.nums[i] ? -1 : 1
+  if (A.pre === B.pre) return 0
+  if (!A.pre) return 1   // 正式版 > 预发布版
+  if (!B.pre) return -1
+  const as = A.pre.split('.')
+  const bs = B.pre.split('.')
+  for (let i = 0; i < Math.max(as.length, bs.length); i++) {
+    const x = as[i]
+    const y = bs[i]
+    if (x === undefined) return -1   // 前缀相同、标识更少的那个更小
+    if (y === undefined) return 1
+    if (x === y) continue
+    const nx = /^\d+$/.test(x)
+    const ny = /^\d+$/.test(y)
+    if (nx && ny) return Number(x) < Number(y) ? -1 : 1
+    if (nx !== ny) return nx ? -1 : 1 // 数字标识 < 字母标识
+    return x < y ? -1 : 1
+  }
+  return 0
+}
+
 export function createApi(deps = {}) {
   const vaultDir = deps.vaultDir ?? (() => '')
   const vaultRoots = deps.vaultRoots ?? (() => [{ name: '', root: vaultDir() }])
@@ -40,6 +83,14 @@ export function createApi(deps = {}) {
   // 自动沉淀运行轨迹（最新在前）+ 健康状态（异常时 UI 顶部亮红）。
   const getCaptureLog = deps.getCaptureLog ?? (() => null)
   const getCaptureHealth = deps.getCaptureHealth ?? (() => null)
+  // 「重启常驻实例」的实现（宿主与独立 web 共用 lib/watchdog.js 的那一份；注入仅为单测）
+  const doRestartResident = deps.restartResident ?? restartResident
+  const probeResidentVersion = deps.probeServedVersion ?? probeServedVersion
+  const pkgVersion = deps.currentPkgVersion ?? currentPkgVersion
+  // 本进程自己监听的端口（独立 web 传入；宿主为 0 = 不知道）。用来把「要重启/要看的是哪个
+  // 常驻实例」钉死在**本页所连的那个实例**上，而不是配置里的理想端口（web 退让到 port+1 时
+  // 两者不同，探错端口会给出错误结论）。
+  const selfPort = () => (typeof deps.selfPort === 'function' ? Number(deps.selfPort()) || 0 : Number(deps.selfPort) || 0)
 
   return async function handleApi(req, res) {
     const vaultRoot = vaultDir()
@@ -137,9 +188,9 @@ export function createApi(deps = {}) {
         return
       }
       case '/version-check': {
-        // 版本跟踪：运行中（宿主启动时加载） vs 磁盘安装 vs npm 最新。
-        // 典型场景：磁盘已更新，但 DSH 进程仍加载旧版 → UI 显示旧版本号、新接口 404。
-        const loaded = (getDshInfo() || {}).version || ''
+        // 版本跟踪：运行中（服务本页的进程） vs 磁盘安装 vs npm 最新。
+        // 典型场景：磁盘已更新，但端口上的常驻进程仍加载旧版 → UI 显示旧版本号、新接口 404。
+        const loaded = (getDshInfo() || {}).version || process.env.MEMORY_ETERNAL_VERSION || ''
         let onDisk = ''
         try {
           const pj = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
@@ -162,16 +213,76 @@ export function createApi(deps = {}) {
             latest = versionCache.latest
           }
         } catch (e) { checkError = String((e && e.message) || e).slice(0, 120) }
+        // 常驻实例（端口上那个进程）自报的版本：宿主面板靠它区分「是本页这个进程旧」还是
+        // 「常驻 web 旧」——两者要做的操作不同（重启 DSH vs 重启常驻实例）。独立 web 页里
+        // 探到的就是它自己。
+        const cfgVc = getSettings() ?? {}
+        const residentPort = selfPort() || Number(cfgVc.webPort) || Number(process.env.MEMORY_WEB_PORT) || 7999
+        let residentServed = ''
+        try { residentServed = String((await probeResidentVersion(residentPort)) || '') } catch { residentServed = '' }
         json(res, 200, {
           ok: true,
           loaded,
           onDisk,
           latest,
           checkError,
+          resident: { port: residentPort, served: residentServed },
           stale: !!(loaded && onDisk && loaded !== onDisk),
-          updateAvailable: !!(latest && onDisk && latest !== onDisk),
+          // 只在 **npm 上确实更新** 时提示升级：本地跑着未发布版本（磁盘 0.10.7 / npm 0.10.6）时
+          // 旧的 `latest !== onDisk` 会反过来劝用户装回旧版。
+          updateAvailable: !!(latest && onDisk && compareVersions(latest, onDisk) > 0),
           updateCommand: 'dsh plugin --profile <你的 profile> add memory-eternal@latest',
+          // 「重启常驻实例」的能力与命令（面板据此给一键按钮 / 手动指引）
+          canRestartResident: true,
+          restartCommand: `dsh-memory restart --port ${residentPort}`,
+        })
+        return
+      }
+      case '/restart-self': {
+        // 「运行中还是旧版本」的一键修复：用新代码重启**常驻实例**（端口上那个进程）。
+        // 三条硬约束：
+        //   ① 本进程很可能就是要被替换的旧 web → 先回响应，再调度替换（助手负责收旧实例）；
+        //   ② 常驻实例已经是最新版就别白折腾（宿主面板点这个按钮时最常见）——如实回 alreadyCurrent；
+        //   ③ 同一时刻只允许一个替换在跑。
+        if (req.method && req.method !== 'POST') return json(res, 405, { ok: false, error: 'method not allowed' })
+        const cfgR = getSettings() ?? {}
+        const port = Number(query.get('port')) || selfPort() || Number(cfgR.webPort) || Number(process.env.MEMORY_WEB_PORT) || 7999
+        const expect = pkgVersion()
+        const served = await probeResidentVersion(port).catch(() => '')
+        if (served && expect && String(served) === String(expect)) {
+          return json(res, 200, {
+            ok: true, alreadyCurrent: true, port, served: String(served), expect,
+            note: `常驻实例（端口 ${port}）已经在服务 v${served}，无需重启。若「运行中」仍显示旧版本号，说明那一行来自另一个进程（例如 DSH 宿主），需重启桌面版 / DSH。`,
+          })
+        }
+        if (residentRestarting) {
+          return json(res, 200, { ok: true, alreadyRunning: true, port, expect, note: `端口 ${port} 的替换已在进行中，请稍候刷新页面。` })
+        }
+        residentRestarting = true
+        json(res, 200, {
+          ok: true, scheduled: true, port, served: String(served || ''), expect,
+          note: `已调度重启常驻实例（端口 ${port} → v${expect || '?'}）：约 3-8 秒后新进程接管，请稍等再刷新页面（Ctrl+F5）。`,
         })
+        setTimeout(() => {
+          Promise.resolve()
+            .then(() => doRestartResident({
+              port, vaultRoot, interval: Number(cfgR.webCheckIntervalMs) || 5000, maxRestart: Number(cfgR.webMaxRestart) || 10,
+            }))
+            .then(async (out) => {
+              // 本进程若正是被替换的旧 web，这里根本不会执行 —— 助手会把结论写进 capture 日志
+              try {
+                const { appendCaptureLog } = await import('./capture-log.js')
+                await appendCaptureLog({
+                  time: Date.now(), sessionId: 'system', action: out && out.ok ? 'boot' : 'fail',
+                  reason: out && out.ok
+                    ? `面板一键重启常驻实例成功：端口 ${port} 正在服务 v${out.served}`
+                    : `面板一键重启常驻实例未确认生效：${(out && out.error) || '未知原因'}`,
+                }, process.env)
+              } catch { /* 日志失败不影响替换 */ }
+            })
+            .catch(() => {})
+            .finally(() => { residentRestarting = false })
+        }, 300)
         return
       }
       case '/diagnostics': {
@@ -426,11 +537,12 @@ export function createApi(deps = {}) {
             webCheckIntervalMs: Number(cfg.webCheckIntervalMs) || 5000,
             webMaxRestart: Number(cfg.webMaxRestart) || 10,
             watchdogAutoSpawn: cfg.watchdogAutoSpawn ?? env.MEMORY_WATCHDOG === '1',
+            autoRestartOnDrift: cfg.autoRestartOnDrift ?? true,
             autoMcpSetup: cfg.autoMcpSetup ?? false,
           })
         } catch (e) {
           // 配置读取异常时降级返回默认值，避免面板整块红屏
-          json(res, 200, { ok: true, budgetChars: 80000, recallLimit: 5, embedding: '', autoWeb: true, autoWebMode: 'init', webPort: 7999, webCheckIntervalMs: 5000, webMaxRestart: 10, watchdogAutoSpawn: true, autoMcpSetup: false })
+          json(res, 200, { ok: true, budgetChars: 80000, recallLimit: 5, embedding: '', autoWeb: true, autoWebMode: 'init', webPort: 7999, webCheckIntervalMs: 5000, webMaxRestart: 10, watchdogAutoSpawn: true, autoRestartOnDrift: true, autoMcpSetup: false })
         }
         return
       }
@@ -444,10 +556,10 @@ export function createApi(deps = {}) {
         const cfg = getSettings() ?? {}
         const env = typeof process !== 'undefined' ? process.env : {}
         const safe = {
-          autoCapture: cfg.autoCapture ?? true, autoRecall: cfg.autoRecall ?? true, recallLimit: cfg.recallLimit ?? 5, recallSummaryLen: cfg.recallSummaryLen ?? 130, recallIncludeBody: cfg.recallIncludeBody ?? false,
+          autoCapture: cfg.autoCapture ?? true, autoRecall: cfg.autoRecall ?? true, recallLimit: cfg.recallLimit ?? 5, recallSummaryLen: cfg.recallSummaryLen ?? 130, recallIncludeBody: cfg.recallIncludeBody ?? false, secretHint: cfg.secretHint || '',
           captureMinChars: cfg.captureMinChars ?? 200, captureCooldownMs: cfg.captureCooldownMs ?? 300000, dedupThreshold: cfg.dedupThreshold ?? 0.62, maxCardsPerDay: cfg.maxCardsPerDay ?? 60,
           distillEnabled: cfg.distillEnabled ?? true, dedupByLLM: cfg.dedupByLLM ?? true, captureMaxTokens: cfg.captureMaxTokens ?? DEFAULT_CAPTURE_MAX_TOKENS, recallMinScore: cfg.recallMinScore ?? 2,
-          autoWeb: cfg.autoWeb ?? env.MEMORY_AUTO_WEB !== '0', autoWebMode: cfg.autoWebMode || 'init', webPort: Number(cfg.webPort) || Number(env.MEMORY_WEB_PORT) || 7999, webCheckIntervalMs: Number(cfg.webCheckIntervalMs) || 5000, webMaxRestart: Number(cfg.webMaxRestart) || 10, watchdogAutoSpawn: cfg.watchdogAutoSpawn ?? env.MEMORY_WATCHDOG === '1', autoMcpSetup: cfg.autoMcpSetup ?? false,
+          autoWeb: cfg.autoWeb ?? env.MEMORY_AUTO_WEB !== '0', autoWebMode: cfg.autoWebMode || 'init', webPort: Number(cfg.webPort) || Number(env.MEMORY_WEB_PORT) || 7999, webCheckIntervalMs: Number(cfg.webCheckIntervalMs) || 5000, webMaxRestart: Number(cfg.webMaxRestart) || 10, watchdogAutoSpawn: cfg.watchdogAutoSpawn ?? env.MEMORY_WATCHDOG === '1', autoRestartOnDrift: cfg.autoRestartOnDrift ?? true, autoMcpSetup: cfg.autoMcpSetup ?? false,
           auditMode: cfg.auditMode ?? 'all', auditExemptAgents: cfg.auditExemptAgents ?? [], auditExemptKinds: cfg.auditExemptKinds ?? [], recycleRetentionDays: cfg.recycleRetentionDays ?? 30,
           vaultProfiles: Array.isArray(cfg.vaultProfiles) ? cfg.vaultProfiles : [], activeVault: cfg.activeVault || '',
           enabled: cfg.enabled !== false, vaultDir: cfg.vaultDir || '', captureProvider: cfg.captureProvider || '',
@@ -488,16 +600,29 @@ export function createApi(deps = {}) {
           }
           if (bad.length) return json(res, 400, { ok: false, error: '字段值不合法：' + bad.join('、'), fields: bad })
           if (!Object.keys(clean).length) return json(res, 400, { ok: false, error: '没有可写入的字段' })
-          const { writePendingConfig, readPendingConfig, waitPendingOutcome, clearPendingConfig, applySharedConfigDirect, describeApplyFailure } = await import('./config-sync.js')
+          const { writePendingConfig, readPendingConfig, waitPendingOutcome, clearPendingConfig, applySharedConfigDirect, describeApplyFailure, triggerHostDrain } = await import('./config-sync.js')
+          const { hostAlive, readHostMarker } = await import('./host-heartbeat.js')
           // #16 建议 4：上一份改动是否已被判定失败？是的话这次不能再报「一切正常」——
           // 否则用户第 N 次点击保存，看到的仍是成功，而问题一直在（其实是 settings.update 在报错）。
           const before = readPendingConfig(process.env)
           const out = writePendingConfig(process.env, clean)
           hub.broadcast('config', { at: out.at, source: 'standalone', applied: Object.keys(clean) })
-          // issue #21 建议 3：别急着报「一切正常」。宿主在跑时对 pending 文件有 fs.watch
-          // （毫秒级），稍等一下回读，就能分清「真的应用了」还是「只是排上队了」——
-          // 以前无论哪种都回 ok:true + 一句泛泛的 note，用户只会在几秒后从日志里发现失败。
-          let outcome = await waitPendingOutcome(process.env, { timeoutMs: 800 })
+          // 方案 A（首选）：宿主活着、且心跳里带了端口 + 令牌时，**直接请宿主在 HTTP 请求上下文里
+          // 应用**。为什么不继续等宿主自己 drain：宿主那条 drain 挂在回调上下文（setInterval /
+          // fs.watch），在带 activation 守卫的宿主上必然被拒（实测与 patch 内容无关）—— 等不来结果。
+          // 叫醒失败（旧宿主没这条路由 / 端口对不上 / 超时）不是错误：退回 issue #21 的等待路径。
+          let outcome = 'queued'
+          let hostDrainError = ''
+          const aliveHost = hostAlive(process.env) ? readHostMarker(process.env) : null
+          if (aliveHost && aliveHost.port && aliveHost.token) {
+            const call = await triggerHostDrain({ port: aliveHost.port, token: aliveHost.token, timeoutMs: 2500 })
+            if (call.ok) outcome = 'applied'
+            else if (call.status === 404 || call.status === 405 || call.status === 0) hostDrainError = call.error || ''
+            else { outcome = 'failed'; hostDrainError = call.error || '' }
+          }
+          // 回落（issue #21 建议 3）：别急着报「一切正常」。宿主对 pending 文件有 fs.watch（毫秒级），
+          // 稍等一下回读，就能分清「真的应用了」还是「只是排上队了」。
+          if (outcome === 'queued') outcome = await waitPendingOutcome(process.env, { timeoutMs: 800 })
           // issue #21 的宿主无关路径：**本机没有活着的 DSH 宿主**时（Codex / Claude Code /
           // 只跑 dsh-memory serve 的用户），没有任何进程会来 drain pending 文件 —— 那句
           // 「DSH 未运行时下次启动生效」在那类环境下永远不会兑现。这时直接原子写共享配置
@@ -505,7 +630,6 @@ export function createApi(deps = {}) {
           // 宿主活着时绝不走这条：共享文件是宿主的派生镜像，绕过它直写会被下一次 syncConfigFile 盖掉。
           let appliedDirect = false
           if (outcome === 'queued') {
-            const { hostAlive } = await import('./host-heartbeat.js')
             if (!hostAlive(process.env)) {
               try {
                 applySharedConfigDirect(process.env, clean)
@@ -518,17 +642,24 @@ export function createApi(deps = {}) {
           const stale = before && (before.dropped || before.lastError)
           const advice = describeApplyFailure(before && before.lastError)
           const hostGuard = advice.kind === 'host-guard'
+          // 上一份已经被这个宿主的守卫判死（dropped + host-guard）→ 这次也不能再空头承诺
+          // 「DSH 端会自动同步」：直说去哪儿改，否则用户会一直看到一个永远不会生效的「已排队」。
+          const knownGuard = Boolean(before && before.dropped && hostGuard)
           const note = outcome === 'applied'
-            ? '宿主已应用该改动。'
+            ? '宿主已在请求上下文里应用该改动（点保存即生效）。'
             : outcome === 'applied-direct'
               ? '本机没有 DSH 宿主在运行，已直接写入共享配置（hooks / MCP / 独立页立即生效）。'
               : outcome === 'failed'
-                ? '改动已写入，但宿主侧应用失败：' + (hostGuard ? advice.hint : '详见「反馈异常」里的诊断信息。')
-                : '已写入待应用：DSH 端会自动同步（DSH 未运行时下次启动生效）'
+                ? '改动已写入，但宿主侧应用失败：' + (hostDrainError || (hostGuard ? advice.hint : '详见「反馈异常」里的诊断信息。'))
+                : knownGuard
+                  ? '这个宿主不允许插件从回调上下文写配置（与配置内容无关）：请到「DSH 设置 → 记忆」里改同一项。本次改动已在独立端重新排队，宿主升级/重启后仍会自动应用。'
+                  : '已写入待应用：DSH 端会自动同步（DSH 未运行时下次启动生效）'
           return json(res, 200, {
-            ok: true, applied: Object.keys(clean), pending: appliedDirect ? [] : Object.keys(clean), retried: false, at: out.at,
+            ok: true, applied: Object.keys(clean), pending: (appliedDirect || outcome === 'applied') ? [] : Object.keys(clean), retried: false, at: out.at,
             pendingOutcome: outcome,
             appliedDirect,
+            // 方案 A 的现场：宿主叫醒失败的原因（旧宿主没路由 / 令牌不匹配 / 应用报错）如实回给界面
+            hostDrainError: hostDrainError || undefined,
             hostGuard: hostGuard || undefined,
             hint: hostGuard ? advice.hint : undefined,
             warning: stale