memory-eternal 0.10.5 → 0.10.7

package/index.js

@@ -76,6 +76,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 +106,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),
   // 自动审核配置
@@ -361,7 +374,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 +390,18 @@ 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 || {}))
+    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,6 +410,7 @@ export function apply(ctx, config) {
         } catch { /* 日志失败无妨 */ }
       },
     })
+    return { ...out, ignored }
   }
   const drainPending = async () => {
     try {
@@ -448,6 +475,24 @@ export function apply(ctx, config) {
     return roots
   }
   // 把完整配置写入共享文件，使独立 web / MCP hook 捕获与 DSH 设置同步（不同步修复）。
+  //
+  // 2026-10-07：这里原来是 `catch { /* 静默 */ }` —— 正是本项目一直在消灭的静默吞错。它写不进去
+  // 的后果很隐蔽：独立页 / hooks / MCP 读的都是这个文件，于是表现为「配置改了但他们看不到」
+  // （实测到过一次：共享文件的 mtime 停在激活前，而宿主里的值已经变了）。现在失败一律可见。
+  let lastSyncError = ''
+  const reportSyncFailure = (reason) => {
+    const why = String(reason || '')
+    if (!why || why === lastSyncError) return   // 同一原因只报一次，避免 5 秒轮询刷屏
+    lastSyncError = why
+    // 必须延迟一拍：本函数可能在 apply() 的**同步**阶段被调用，而 logCapture 定义在更后面
+    // （const 的 TDZ 会直接抛 ReferenceError）。setImmediate 之后整个 apply() 已执行完毕。
+    const emit = () => {
+      try { console.error('[memory-eternal] 共享配置文件同步失败（独立页 / hooks / MCP 读到的是旧值）：' + why) } catch { /* 无妨 */ }
+      try { logCapture('system', 'warn', '共享配置文件同步失败（独立页 / hooks / MCP 会读到旧值）：' + why) } catch { /* 无妨 */ }
+    }
+    if (typeof setImmediate === 'function') setImmediate(emit)
+    else setTimeout(emit, 0)
+  }
   const syncConfigFile = async () => {
     try {
       const cfg = settings.get() ?? {}
@@ -456,7 +501,10 @@ export function apply(ctx, config) {
       // 原子写（tmp + rename，见 lib/config-sync.js 里 writeFileAtomicSync 的说明）：
       // 这个文件是跨进程共享的读源，非原子写会让独立 web / MCP 读到半截内容并静默回落成默认值。
       writeFileAtomicSync(configFilePath(process.env), JSON.stringify(cfg, null, 2))
-    } catch { /* 静默 */ }
+      lastSyncError = ''
+    } catch (error) {
+      reportSyncFailure(error && error.message ? error.message : error)
+    }
   }
   syncConfigFile()
   // agent/turn-stopping 是 serial 事件：不在监听器里 await LLM（会拖慢收尾），
@@ -791,6 +839,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()
@@ -822,7 +875,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' },
@@ -1001,10 +1056,10 @@ export function apply(ctx, config) {
               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 : [],
@@ -1067,7 +1122,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）' })
@@ -1183,22 +1238,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,18 +213,78 @@ 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': {
         // 「反馈异常」用：返回一段可直接贴进 issue 的**已脱敏**诊断文本。
         // 宿主与独立 web 共用这个实现；home 目录、各类 key/token 全都会被替换掉。
@@ -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 || '',
@@ -518,13 +630,18 @@ 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 未运行时下次启动生效）'
+                : knownGuard
+                  ? '这个宿主不允许插件从回调上下文写配置（与配置内容无关）：请到「DSH 设置 → 记忆」里改同一项。本次改动已在独立端重新排队，宿主升级/重启后仍会自动应用。'
+                  : '已写入待应用：DSH 端会自动同步（DSH 未运行时下次启动生效）'
           return json(res, 200, {
             ok: true, applied: Object.keys(clean), pending: appliedDirect ? [] : Object.keys(clean), retried: false, at: out.at,
             pendingOutcome: outcome,