memory-eternal 0.10.6 → 0.10.7

package/hooks/capture.mjs

@@ -1,77 +1,77 @@
-#!/usr/bin/env node
-// 记忆核心 · 通用「会话结束自动沉淀」hook（claude-code / codex / cursor 共用）。
-//
-// 用法：node capture.mjs <agent>     agent ∈ claude-code | codex | cursor
-// stdin（平台 hook 注入）：
-//   { session_id, transcript_path, hook_event_name, cwd, last_assistant_message, prompt, ... }
-//
-// 行为：读 transcript（JSONL/JSON 兼容）或显式文本字段 → 调 runStandaloneCapture 蒸馏入库。
-// 设计约束：
-//   - 静默失败（hook 崩溃不能影响宿主 agent）
-//   - 幂等（去重/追加在 runStandaloneCapture 内处理）
-//   - 署名 source = agent 名，便于智能体筛选；vault 由 MEMORY_VAULT_DIR 或 ~/.dsh/memory-vault 决定（与全库统一）
-//
-// Windows 友好：纯 node，无外部依赖（同 claude-session.js）。
-
-import { promises as fs } from 'node:fs'
-
-const agent = process.argv[2] || 'agent'
-
-const readStdin = () => new Promise((resolve) => {
-  let buf = ''
-  process.stdin.setEncoding('utf8')
-  process.stdin.on('data', (c) => { buf += c })
-  process.stdin.on('end', () => resolve(buf))
-  setTimeout(() => resolve(buf), 2000)
-})
-
-/** 从 message 对象里抽可读文本（兼容 claude 的 {role,content} 与 codex/cursor 的 {text|content}）。 */
-function textOf(msg) {
-  if (!msg) return ''
-  if (typeof msg === 'string') return msg
-  const c = msg.content
-  if (typeof c === 'string') return c
-  if (Array.isArray(c)) return c.filter((x) => x && x.type === 'text').map((x) => x.text).join('\n')
-  return msg.text || msg.message || ''
-}
-
-/** 读 transcript 文件并抽取最近对话文本。优先 JSONL 行解析，退回整体文本。 */
-async function extractTranscript(transcriptPath) {
-  let text
-  try { text = await fs.readFile(transcriptPath, 'utf8') } catch { return '' }
-  if (!text.trim()) return ''
-  text = text.replace(/^\uFEFF/, '') // 去掉可能存在的 UTF-8 BOM
-  const lines = text.split('\n').filter(Boolean)
-  const parts = []
-  let structured = 0
-  for (const line of lines.slice(-400)) {
-    let rec
-    try { rec = JSON.parse(line); structured++ } catch { continue }
-    const t = textOf(rec?.message)
-    if (t && t.trim().length > 4) {
-      const role = rec?.message?.role || rec?.role || 'msg'
-      parts.push(`${role}: ${t.trim()}`)
-    }
-  }
-  if (structured >= 1 && parts.length) return parts.slice(-30).join('\n\n')
-  // 非结构化：取尾部可读文本（去掉控制字符）
-  return text.replace(/\r/g, '').replace(/\u0000/g, '').slice(-6000)
-}
-
-async function main() {
-  let meta = {}
-  try { meta = JSON.parse((await readStdin()) || '{}') } catch { /* 静默 */ }
-
-  let conversation = ''
-  if (meta.transcript_path) { try { conversation = await extractTranscript(meta.transcript_path) } catch { /* 静默 */ } }
-  if (!conversation || conversation.trim().length < 120) {
-    conversation = meta.last_assistant_message || meta.prompt || meta.context || ''
-  }
-  if (!conversation || conversation.trim().length < 120) return
-
-  const { runStandaloneCapture, defaultVaultDir } = await import('../lib/capture-run.js')
-  const src = agent // 署名 = agent 名（可筛选）；若想保留会话粒度可用 `${agent}:${session_id}`
-  await runStandaloneCapture(defaultVaultDir(), conversation, { source: src })
-}
-
-main().catch(() => { /* hook 静默失败 */ })
+#!/usr/bin/env node
+// 记忆核心 · 通用「会话结束自动沉淀」hook（claude-code / codex / cursor 共用）。
+//
+// 用法：node capture.mjs <agent>     agent ∈ claude-code | codex | cursor
+// stdin（平台 hook 注入）：
+//   { session_id, transcript_path, hook_event_name, cwd, last_assistant_message, prompt, ... }
+//
+// 行为：读 transcript（JSONL/JSON 兼容）或显式文本字段 → 调 runStandaloneCapture 蒸馏入库。
+// 设计约束：
+//   - 静默失败（hook 崩溃不能影响宿主 agent）
+//   - 幂等（去重/追加在 runStandaloneCapture 内处理）
+//   - 署名 source = agent 名，便于智能体筛选；vault 由 MEMORY_VAULT_DIR 或 ~/.dsh/memory-vault 决定（与全库统一）
+//
+// Windows 友好：纯 node，无外部依赖（同 claude-session.js）。
+
+import { promises as fs } from 'node:fs'
+
+const agent = process.argv[2] || 'agent'
+
+const readStdin = () => new Promise((resolve) => {
+  let buf = ''
+  process.stdin.setEncoding('utf8')
+  process.stdin.on('data', (c) => { buf += c })
+  process.stdin.on('end', () => resolve(buf))
+  setTimeout(() => resolve(buf), 2000)
+})
+
+/** 从 message 对象里抽可读文本（兼容 claude 的 {role,content} 与 codex/cursor 的 {text|content}）。 */
+function textOf(msg) {
+  if (!msg) return ''
+  if (typeof msg === 'string') return msg
+  const c = msg.content
+  if (typeof c === 'string') return c
+  if (Array.isArray(c)) return c.filter((x) => x && x.type === 'text').map((x) => x.text).join('\n')
+  return msg.text || msg.message || ''
+}
+
+/** 读 transcript 文件并抽取最近对话文本。优先 JSONL 行解析，退回整体文本。 */
+async function extractTranscript(transcriptPath) {
+  let text
+  try { text = await fs.readFile(transcriptPath, 'utf8') } catch { return '' }
+  if (!text.trim()) return ''
+  text = text.replace(/^\uFEFF/, '') // 去掉可能存在的 UTF-8 BOM
+  const lines = text.split('\n').filter(Boolean)
+  const parts = []
+  let structured = 0
+  for (const line of lines.slice(-400)) {
+    let rec
+    try { rec = JSON.parse(line); structured++ } catch { continue }
+    const t = textOf(rec?.message)
+    if (t && t.trim().length > 4) {
+      const role = rec?.message?.role || rec?.role || 'msg'
+      parts.push(`${role}: ${t.trim()}`)
+    }
+  }
+  if (structured >= 1 && parts.length) return parts.slice(-30).join('\n\n')
+  // 非结构化：取尾部可读文本（去掉控制字符）
+  return text.replace(/\r/g, '').replace(/\u0000/g, '').slice(-6000)
+}
+
+async function main() {
+  let meta = {}
+  try { meta = JSON.parse((await readStdin()) || '{}') } catch { /* 静默 */ }
+
+  let conversation = ''
+  if (meta.transcript_path) { try { conversation = await extractTranscript(meta.transcript_path) } catch { /* 静默 */ } }
+  if (!conversation || conversation.trim().length < 120) {
+    conversation = meta.last_assistant_message || meta.prompt || meta.context || ''
+  }
+  if (!conversation || conversation.trim().length < 120) return
+
+  const { runStandaloneCapture, defaultVaultDir } = await import('../lib/capture-run.js')
+  const src = agent // 署名 = agent 名（可筛选）；若想保留会话粒度可用 `${agent}:${session_id}`
+  await runStandaloneCapture(defaultVaultDir(), conversation, { source: src })
+}
+
+main().catch(() => { /* hook 静默失败 */ })

package/hooks/claude-session.js

@@ -1,56 +1,56 @@
-#!/usr/bin/env node
-// 记忆核心 · Claude Code SessionEnd/PreCompact hook（Windows 友好，纯 node）。
-//
-// Claude Code 在会话结束/压缩前触发，stdin 传入 JSON：
-//   { session_id, transcript_path, hook_event_name, cwd, ... }
-// 本脚本解析 transcript JSONL，提取最近若干轮 user/assistant 文本，蒸馏入库。
-// 由 lib/setup.js 自动注册到 ~/.claude/settings.json 的 hooks.SessionEnd。
-//
-// 特性：静默失败（hook 崩溃不能影响 Claude Code）；幂等（重复跑同一段只追加）。
-
-import { promises as fs } from 'node:fs'
-import path from 'node:path'
-
-async function main() {
-  let input = {}
-  try {
-    const raw = await new Promise((resolve) => {
-      let buf = ''
-      process.stdin.setEncoding('utf8')
-      process.stdin.on('data', (c) => { buf += c })
-      process.stdin.on('end', () => resolve(buf))
-      setTimeout(() => resolve(buf), 2000)
-    })
-    input = JSON.parse(raw || '{}')
-  } catch { /* 静默 */ }
-
-  const transcriptPath = input.transcript_path
-  if (!transcriptPath) return
-  let lines
-  try { lines = (await fs.readFile(transcriptPath, 'utf8')).split('\n').filter(Boolean) } catch { return }
-
-  // 提取尾部对话文本（user 与 assistant 的 message.content 文本部分）
-  const texts = []
-  for (const line of lines.slice(-400)) {
-    let rec
-    try { rec = JSON.parse(line) } catch { continue }
-    const msg = rec?.message
-    if (!msg || !msg.role) continue
-    const content = msg.content
-    let text = ''
-    if (typeof content === 'string') text = content
-    else if (Array.isArray(content)) {
-      text = content.filter((c) => c?.type === 'text').map((c) => c.text).join('\n')
-    }
-    if (text && text.trim().length > 4) texts.push(`${msg.role}: ${text.trim()}`)
-  }
-  const conversation = texts.slice(-30).join('\n\n')
-  if (conversation.trim().length < 120) return
-
-  const { runStandaloneCapture, defaultVaultDir } = await import('../lib/capture-run.js')
-  await runStandaloneCapture(defaultVaultDir(), conversation, {
-    source: `claude-code:${input.session_id || path.basename(transcriptPath)}`,
-  })
-}
-
-main().catch(() => { /* hook 静默失败 */ })
+#!/usr/bin/env node
+// 记忆核心 · Claude Code SessionEnd/PreCompact hook（Windows 友好，纯 node）。
+//
+// Claude Code 在会话结束/压缩前触发，stdin 传入 JSON：
+//   { session_id, transcript_path, hook_event_name, cwd, ... }
+// 本脚本解析 transcript JSONL，提取最近若干轮 user/assistant 文本，蒸馏入库。
+// 由 lib/setup.js 自动注册到 ~/.claude/settings.json 的 hooks.SessionEnd。
+//
+// 特性：静默失败（hook 崩溃不能影响 Claude Code）；幂等（重复跑同一段只追加）。
+
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+
+async function main() {
+  let input = {}
+  try {
+    const raw = await new Promise((resolve) => {
+      let buf = ''
+      process.stdin.setEncoding('utf8')
+      process.stdin.on('data', (c) => { buf += c })
+      process.stdin.on('end', () => resolve(buf))
+      setTimeout(() => resolve(buf), 2000)
+    })
+    input = JSON.parse(raw || '{}')
+  } catch { /* 静默 */ }
+
+  const transcriptPath = input.transcript_path
+  if (!transcriptPath) return
+  let lines
+  try { lines = (await fs.readFile(transcriptPath, 'utf8')).split('\n').filter(Boolean) } catch { return }
+
+  // 提取尾部对话文本（user 与 assistant 的 message.content 文本部分）
+  const texts = []
+  for (const line of lines.slice(-400)) {
+    let rec
+    try { rec = JSON.parse(line) } catch { continue }
+    const msg = rec?.message
+    if (!msg || !msg.role) continue
+    const content = msg.content
+    let text = ''
+    if (typeof content === 'string') text = content
+    else if (Array.isArray(content)) {
+      text = content.filter((c) => c?.type === 'text').map((c) => c.text).join('\n')
+    }
+    if (text && text.trim().length > 4) texts.push(`${msg.role}: ${text.trim()}`)
+  }
+  const conversation = texts.slice(-30).join('\n\n')
+  if (conversation.trim().length < 120) return
+
+  const { runStandaloneCapture, defaultVaultDir } = await import('../lib/capture-run.js')
+  await runStandaloneCapture(defaultVaultDir(), conversation, {
+    source: `claude-code:${input.session_id || path.basename(transcriptPath)}`,
+  })
+}
+
+main().catch(() => { /* hook 静默失败 */ })

package/hooks/hooks.claude.json

@@ -1,12 +1,23 @@
-{
-  "SessionEnd": [
-    {
-      "hooks": [
-        {
-          "type": "command",
-          "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/capture.mjs\" claude-code"
-        }
-      ]
-    }
-  ]
-}
+{
+  "SessionEnd": [
+    {
+      "hooks": [
+        {
+          "type": "command",
+          "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/capture.mjs\" claude-code"
+        }
+      ]
+    }
+  ],
+  "PreToolUse": [
+    {
+      "matcher": "Read|Bash|Grep|Glob",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/secret-guard.mjs\""
+        }
+      ]
+    }
+  ]
+}

package/hooks/hooks.codex.json

@@ -1,15 +1,15 @@
-{
-  "hooks": {
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/capture.mjs\" codex",
-            "statusMessage": "memory-eternal: saving session"
-          }
-        ]
-      }
-    ]
-  }
-}
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/capture.mjs\" codex",
+            "statusMessage": "memory-eternal: saving session"
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/hooks.cursor.json

@@ -1,11 +1,11 @@
-{
-  "version": 1,
-  "hooks": {
-    "stop": [
-      { "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/capture.mjs\" cursor" }
-    ],
-    "sessionEnd": [
-      { "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/capture.mjs\" cursor" }
-    ]
-  }
-}
+{
+  "version": 1,
+  "hooks": {
+    "stop": [
+      { "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/capture.mjs\" cursor" }
+    ],
+    "sessionEnd": [
+      { "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/capture.mjs\" cursor" }
+    ]
+  }
+}

package/hooks/secret-guard.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// 记忆核心 · 凭据读取守卫（Claude Code PreToolUse hook，纯 node、静默失败）
+//
+// 为什么需要它：一旦 agent 知道「本机有密钥」，它很可能直接 `cat ~/.dsh/.credentials.yaml`
+// 或 Read 那个文件 —— 值就进了它的上下文（再经 provider / 日志 / 蒸馏扩散出去）。
+// 「知道去哪取」与「不许直接读」必须成对存在，否则索引反而放大了泄漏面。
+//
+// 生效条件（**默认不打扰任何人**）：本机存在密钥加载器
+//   ~/.config/memory-eternal/secrets.py
+// 没有它（其它用户 / 其它机器）这个 hook 直接放行，什么也不做。
+//
+// 命中判定：工具参数里出现下列文件（Read 的 file_path / Bash 的命令行 / Grep 的 pattern 等）
+//   .credentials.y(a)ml、~/.dsh/.env、gitee-token
+// 命中即以 PreToolUse permissionDecision=deny 拒绝，并指路到 secrets.py --names / --run。
+//
+// 由 hooks/hooks.claude.json 注册（PreToolUse）。也可以手工测试：
+//   echo '{"tool_name":"Read","tool_input":{"file_path":"/x/.credentials.yaml"}}' | node hooks/secret-guard.mjs
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const LOADER = path.join(os.homedir(), '.config', 'memory-eternal', 'secrets.py')
+const SENSITIVE = [
+  /\.credentials\.ya?ml/i,
+  /[\\/]\.dsh[\\/]\.env(?:$|[\s"'])/i,
+  /[\\/]\.env(?:$|["'\s])/i,          // 通用 .env（含值）——只在本机装了加载器时才拦
+  /gitee-token/i,
+]
+const REASON = [
+  '这道读取被「记忆核心」的凭据守卫拦下了：该文件里是密钥**明文**，读进上下文就等于泄漏',
+  '（值经 provider / 日志 / 自动蒸馏会扩散到多处，且删除也无法收回）。',
+  '',
+  '正确做法：',
+  '  1) 先列名字（不输出值）：python ~/.config/memory-eternal/secrets.py --names',
+  '  2) 再带值执行命令（值只进子进程环境变量）：python ~/.config/memory-eternal/secrets.py --require <KEY> --run -- <命令>',
+  '  3) 需要「有哪些键、放在哪、干什么用」的说明：memory_recall("密钥 目录")',
+  '',
+  '确实需要人工查看时，请在终端里自己打开该文件 —— 不要经由 Agent 的工具读取。',
+].join('\n')
+
+async function readStdin() {
+  try {
+    return await new Promise((resolve) => {
+      let buf = ''
+      process.stdin.setEncoding('utf8')
+      process.stdin.on('data', (c) => { buf += c })
+      process.stdin.on('end', () => resolve(buf))
+      setTimeout(() => resolve(buf), 1500) // hook 不能挂住宿主
+    })
+  } catch { return '' }
+}
+
+function targetsCredential(input) {
+  if (!input || typeof input !== 'object') return false
+  const fields = ['file_path', 'path', 'notebook_path', 'command', 'pattern', 'glob', 'query', 'url', 'content']
+  const haystack = fields
+    .map((f) => (typeof input[f] === 'string' ? input[f] : ''))
+    .filter(Boolean)
+    .join('\n')
+  if (!haystack) return false
+  return SENSITIVE.some((re) => re.test(haystack))
+}
+
+async function main() {
+  if (!fs.existsSync(LOADER)) return // 没装加载器 → 不打扰
+  const raw = await readStdin()
+  let payload = null
+  try { payload = JSON.parse(raw || '{}') } catch { return }
+  const tool = String(payload?.tool_name || '')
+  if (!tool) return
+  if (!targetsCredential(payload.tool_input)) return
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: REASON,
+    },
+  }))
+}
+
+main().catch(() => { /* hook 静默失败：绝不因为守卫崩了而挡住正常工具 */ })

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 {
@@ -812,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()
@@ -843,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' },
@@ -1022,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 : [],
@@ -1088,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）' })
@@ -1204,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）。