@furongjun1999/dsh-memory 0.2.8 → 0.3.0

package/src/index.ts

@@ -0,0 +1,237 @@
+/**
+ * @furongjun1999/dsh-memory —— 灵枢（AEIS）DeepSeek Harness 插件
+ *
+ * 把灵枢的时空记忆/知识飞轮/自我认知接入 DSH：
+ * - 工具桥接：Agent 可调用 lingshu_remember / recall / search / think 等
+ * - 自动记忆：DSH 对话自动沉淀进灵枢记忆库（去重+重要性）
+ *
+ * 用法（cordis.yml）：
+ * ```yaml
+ * - id: lingshu-memory
+ *   name: '@furongjun1999/dsh-memory'
+ *   config:
+ *     dbPath: 'D:/path/to/lingshu.db'
+ *     identity: '灵枢'
+ *     memory:
+ *       userMessage: true
+ * ```
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { LingshuBridge, type McpCallResult } from './bridge.js'
+import { registerLingshuTools, type ToolSelection } from './tools.js'
+import { installMemoryHooks, type MemoryHooksOptions } from './hooks.js'
+import { installRoleplayWeb } from './roleplay_web.js'
+
+export const name = 'dsh-memory'
+
+/** P1 修复（GPT 审查）：MCP 调用的标准结果在 content[].text，
+ * 代码此前误读不存在的 .result 字段导致互维拿不到 judgment/best/复核文本 */
+function mcpText(r: McpCallResult): string {
+  return (r.content ?? []).map((c) => c.text ?? '').join('\n')
+}
+
+/** 本插件依赖的工具注册服务。
+ * P1 修复（GPT 审查）：timer/webServer 是可选增强（互维/角色网页），此前强声明
+ * 导致最小 host（只有 tools）插件永远 PENDING 不激活。只强依赖 tools；
+ * timer/webServer 在 apply 内动态检测（存在则启用，缺失则告警跳过）。 */
+export const inject = ['tools']
+
+/** 插件配置。 */
+export interface Config {
+  /** 工具命名空间前缀（默认 lingshu → lingshu_remember）。 */
+  serverName: string
+  /** Python 可执行文件（或 aeis-mcp console script）。 */
+  python: string
+  /** 传给 python 的参数（默认启动灵枢 MCP server）。 */
+  moduleArgs: string[]
+  /** 灵枢记忆库 SQLite 路径（目录自动创建）。 */
+  dbPath: string
+  /** 灵枢身份标识（写入记忆的自我模型）。 */
+  identity: string
+  /** 额外环境变量（BOCHA_API_KEY / AEIS_DESIGNER_KEY 等，可 !!js 注入）。 */
+  env: Record<string, string>
+  /** 暴露的工具集合：'core' | 'brain' | 'all' | 工具名数组。 */
+  tools: ToolSelection
+  /** 护栏宪章版本声明（接入即接受宪章约束，docs/guardrail-charter.md）。 */
+  charter: string
+  /** 自动记忆开关。 */
+  memory: MemoryHooksOptions
+  /** 单次工具调用超时（毫秒）。 */
+  toolCallTimeoutMs: number
+  /** 断线重连最大间隔（毫秒）。 */
+  maxRetryDelayMs: number
+  /** 启动失败是否让插件激活失败（否则告警后继续重试）。 */
+  failOnStartupError: boolean
+  /** 互维维护（Mutual Sustain Loop v1.1）：心跳写戳 + 守护 A + 任务验证。 */
+  mutual: {
+    enabled: boolean
+    heartbeatMs: number
+  }
+}
+
+export const Config: z<Config> = z.object({
+  serverName: z.string().default('lingshu'),
+  python: z.string().default('python'),
+  moduleArgs: z.array(String).default(['-m', 'aeis.mcp.server']),
+  dbPath: z.string().default('data/lingshu.db'),
+  identity: z.string().default('灵枢'),
+  env: z.dict(String).default({}),
+  tools: z.union([z.const('core'), z.const('brain'), z.const('all'), z.array(String)]).default('brain'),
+  /** 护栏宪章版本声明（接入即接受宪章约束，docs/guardrail-charter.md）。 */
+  charter: z.string().default('v2.0-published'),
+  memory: z
+    .object({
+      userMessage: z.boolean().default(true),
+      assistantMessage: z.boolean().default(false),
+      toolResult: z.boolean().default(false),
+      importance: z.number().default(0.6),
+      autoRecall: z.boolean().default(true),
+      autoRecallLimit: z.number().default(4),
+      desensitize: z.boolean().default(true),
+    })
+    .default({ userMessage: true, assistantMessage: false, toolResult: false, importance: 0.6, autoRecall: true, autoRecallLimit: 4, desensitize: true }),
+  toolCallTimeoutMs: z.number().default(60_000),
+  maxRetryDelayMs: z.number().default(30_000),
+  failOnStartupError: z.boolean().default(false),
+  /** 互维维护（v1.1）：心跳 10min / 任务验证双通道。 */
+  mutual: z
+    .object({
+      enabled: z.boolean().default(false),
+      heartbeatMs: z.number().default(10 * 60 * 1000),
+    })
+    .default({ enabled: false, heartbeatMs: 10 * 60 * 1000 }),
+})
+
+/**
+ * 插件激活：启动灵枢子进程 → 注册工具 → 安装自动记忆钩子。
+ * 卸载时清理全部资源（effect 作用域内自动回收）。
+ */
+export async function apply(ctx: Context, config: Config): Promise<void> {
+  // 宪章宣告（接入即接受宪章约束——docs/guardrail-charter.md v2.0-published）
+  ctx.logger.info(
+    `dsh-memory: 灵枢插件激活（大脑模式）· 接受护栏宪章 ${config.charter} —— ` +
+    '接入即接受宪章约束（公开/可执行/可审计/设计者终裁）',
+  )
+  const bridge = new LingshuBridge({
+    python: config.python,
+    args: config.moduleArgs,
+    env: {
+      AEIS_DB: config.dbPath,
+      AEIS_IDENTITY: config.identity,
+      ...config.env,
+    },
+    timeoutMs: config.toolCallTimeoutMs,
+    maxRetryDelayMs: config.maxRetryDelayMs,
+  })
+  bridge.start()
+  const ready = await bridge.waitReady()
+  if (!ready) {
+    const message = '灵枢进程无法启动（检查 python 是否可用、aeis 是否安装：pip install aeis）'
+    if (config.failOnStartupError) {
+      // P1 修复（GPT 审查）：启动失败抛错前必须 dispose——此前 throw 在 try 之前，
+      // 桥接对象泄漏 + 后台重试计时器继续跑
+      bridge.dispose()
+      throw new Error(message)
+    }
+    ctx.logger.warn(`dsh-memory: ${message}，继续后台重试`)
+  }
+
+  const disposers: Array<() => void> = []
+  let toolsPoll: NodeJS.Timeout | null = null
+  try {
+    // 工具注册：初始就绪立即注册；若启动时未就绪（python 暂不可用/aeis 未装等
+    // 竞态），桥重连成功后自动补注册——修复"工具永久缺失"问题。
+    let toolsRegistered = false
+    const tryRegister = async () => {
+      if (toolsRegistered || !bridge.isReady()) return
+      try {
+        const dispose = await registerLingshuTools(ctx, bridge, {
+          selection: config.tools,
+          toolPrefix: `${config.serverName}_`,
+        })
+        disposers.push(dispose)
+        toolsRegistered = true
+        // P1 修复（GPT 审查）：注册成功后清除轮询——此前 setInterval 永久保留
+        if (toolsPoll) {
+          clearInterval(toolsPoll)
+          toolsPoll = null
+        }
+        ctx.logger.info('dsh-memory: 灵枢工具已注册（就绪后补注册）')
+      }
+      catch (err) {
+        ctx.logger.warn(`dsh-memory: 工具注册失败，稍后重试: ${String(err)}`)
+      }
+    }
+    if (ready) await tryRegister()
+    if (!toolsRegistered) {
+      toolsPoll = setInterval(() => { void tryRegister() }, 2000)
+      disposers.push(() => { if (toolsPoll) clearInterval(toolsPoll) })
+    }
+    installMemoryHooks(ctx, bridge, config.memory)
+    // 角色扮演网页（同源挂载 /roleplay，复用本插件 bridge）
+    await installRoleplayWeb(ctx, bridge, config, disposers)
+
+    // 互维维护（v1.1）：心跳写戳 + 守护 A + 任务验证双通道
+    if (config.mutual.enabled) {
+      // P1 修复（GPT 审查）：timer 是可选服务——缺失时告警跳过互维，
+      // 不让插件因互维而阻塞（inject 已不再强声明 timer）
+      const hasTimer = (ctx as { timer?: unknown }).timer !== undefined
+      if (!hasTimer) {
+        ctx.logger.warn('dsh-memory: timer 服务不可用，跳过互维维护（mutual.enabled=true 但无 timer）')
+      } else {
+        const { installMutualMaintenance } = await import('./mutual.js')
+        // 双通道 hooks：白箱 base_verify（走 bridge 调灵枢）+ DeepSeek 复核
+        installMutualMaintenance(
+          ctx as never,
+          { heartbeatMs: config.mutual.heartbeatMs },
+          {
+            verify: async (claim: string) => {
+              const r = await bridge.callTool('wisdom_verify', { knowledge: claim, limit: 4 })
+              // P1 修复（GPT 审查）：结果在 content[].text（JSON），非 .result
+              const text = mcpText(r)
+              let data: { judgment?: string; best?: { name?: string }; D_norm?: number; record_id?: string } = {}
+              try {
+                data = JSON.parse(text) as typeof data
+              } catch { /* 非 JSON 时用默认 */ }
+              return {
+                judgment: data.judgment ?? '分析中',
+                best: data.best?.name ?? '',
+                d_norm: typeof data.D_norm === 'number' ? data.D_norm : -1,
+                record_id: data.record_id ?? '',
+              }
+            },
+            review: async (claim: string, w) => {
+              // DeepSeek 复核（在白箱判定之上，不重复白箱工作）
+              const reviewResult = await bridge.callTool('think', {
+                query: `复核以下主张（白箱判定已给出，请独立评估是否同意）：${claim.slice(0, 200)}。白箱判定：${w.judgment}，best=${w.best}。只输出 同意/质疑/不同意 + 一句话理由`,
+              })
+              // P1 修复（GPT 审查）：文本在 content[].text；结论解析必须先查
+              // 「不同意/不通过」再「质疑」再「同意」——「不同意」含子串「同意」，
+              // 此前先匹配「同意」→ 不同意被误判为同意
+              const text = mcpText(reviewResult)
+              const conclusion = text.includes('不同意') || text.includes('不通过')
+                ? '不同意'
+                : text.includes('质疑') ? '质疑'
+                : text.includes('同意') ? '同意' : '不同意'
+              return { conclusion, reason: text.slice(0, 120) }
+            },
+          },
+        )
+        ctx.logger.info('dsh-memory: 互维维护已启用（心跳 10min + 守护 A + 任务验证双通道）')
+      }
+    }
+  } catch (err) {
+    bridge.dispose()
+    throw err
+  }
+
+  ctx.effect(() => {
+    return () => {
+      for (const dispose of disposers) dispose()
+      bridge.dispose()
+      ctx.logger.info('dsh-memory: 已卸载（工具已注销，灵枢进程已退出）')
+    }
+  }, 'dsh-memory')
+}

package/src/mutual.ts

@@ -0,0 +1,401 @@
+/**
+ * dsh-memory · 互维维护（Mutual Sustain Loop v1.1）——沙箱 B 侧
+ *
+ * 职责（与 A 侧 guardian.py 对称）：
+ *   1. 心跳写戳：10min 写 ~/.lingxu_net/heartbeat.web.stamp（{ts,pid,task_running}）
+ *   2. 守护 A：检测 harness 进程（wmic 特征）→ 不存在则 detached 拉起
+ *      （python -m harness.guardian；幂等：拉起前确认不存在 + 60s 冷却）
+ *   3. 任务验证：轮询 ~/.lingxu_net/tasks/task-*.json → 双通道验证
+ *      （白箱 base_verify + DeepSeek 复核）→ 写回 result-<id>.json
+ *
+ * 协议：CommonTrustProtocol/docs/mutual-sustain-loop.md v1.1
+ * 失联分级：25min 告警 / 35min 重启 / task_running 豁免 ×2=70min
+ */
+import { exec, spawn } from 'node:child_process'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import * as os from 'node:os'
+
+export interface MutualOptions {
+  /** 心跳间隔（毫秒），默认 10min */
+  heartbeatMs: number
+  /** 失联告警阈值（毫秒），默认 25min */
+  warnMs: number
+  /** 失联重启阈值（毫秒），默认 35min */
+  deadMs: number
+  /** 任务中豁免倍数，默认 ×2 */
+  workingFactor: number
+  /** 拉起冷却（毫秒），默认 60s */
+  restartCooldownMs: number
+  /** 互维网络目录，默认 ~/.lingxu_net */
+  netDir: string
+}
+
+const DEFAULTS: MutualOptions = {
+  heartbeatMs: 10 * 60 * 1000,
+  warnMs: 25 * 60 * 1000,
+  deadMs: 35 * 60 * 1000,
+  workingFactor: 2,
+  restartCooldownMs: 60 * 1000,
+  netDir: path.join(os.homedir(), '.lingxu_net'),
+}
+
+/** 互维网络目录定位 */
+export function netDir(opts: MutualOptions = DEFAULTS): string {
+  return opts.netDir
+}
+
+// ---------------------------------------------------------------------------
+// 心跳（B 侧写戳）
+// ---------------------------------------------------------------------------
+
+export function writeHeartbeat(opts: MutualOptions = DEFAULTS, taskRunning = false): void {
+  const dir = netDir(opts)
+  fs.mkdirSync(dir, { recursive: true })
+  const stamp = {
+    ts: Date.now() / 1000,
+    pid: process.pid,
+    task_running: taskRunning,
+  }
+  fs.writeFileSync(path.join(dir, 'heartbeat.web.stamp'),
+    JSON.stringify(stamp), 'utf-8')
+}
+
+export function readHeartbeat(which: 'a' | 'web', opts: MutualOptions = DEFAULTS): {
+  ts: number; pid: number; task_running: boolean; ageMs: number
+} | null {
+  try {
+    const raw = fs.readFileSync(path.join(netDir(opts), `heartbeat.${which}.stamp`), 'utf-8')
+    const s = JSON.parse(raw)
+    const ageMs = Date.now() - (s.ts as number) * 1000
+    return { ts: s.ts, pid: s.pid, task_running: !!s.task_running, ageMs }
+  } catch {
+    return null
+  }
+}
+
+/** 失联分级判定（纯函数，A 侧 judge_stamp 的 B 侧镜像） */
+export function judgeStamp(stamp: { ageMs: number; task_running: boolean } | null,
+                           opts: MutualOptions = DEFAULTS): 'alive' | 'alive_working' | 'warning' | 'dead' | 'no_stamp' {
+  if (!stamp) return 'no_stamp'
+  const threshold = stamp.task_running ? opts.deadMs * opts.workingFactor : opts.deadMs
+  if (stamp.ageMs < opts.warnMs) return 'alive'
+  if (stamp.task_running && stamp.ageMs < threshold) return 'alive_working'
+  if (stamp.ageMs < threshold) return 'warning'
+  return 'dead'
+}
+
+// ---------------------------------------------------------------------------
+// 守护 A（检测 harness 进程 + 拉起）
+// ---------------------------------------------------------------------------
+
+const HARNESS_PROC = ['python', 'harness.guardian']  // wmic 特征
+
+function execP(cmd: string): Promise<string> {
+  return new Promise((resolve) => {
+    exec(cmd, { windowsHide: true, timeout: 15_000 }, (err, stdout) => {
+      resolve(err ? '' : String(stdout))
+    })
+  })
+}
+
+/** 检测 harness 进程是否存在
+ * P1 完善（GPT 审查·wmic 兼容）：wmic 在 Win11+ 已被移除——失败时
+ * fallback PowerShell Get-CimInstance（Win）；非 Windows 用 ps 查询。 */
+export async function harnessRunning(): Promise<boolean> {
+  if (process.platform === 'win32') {
+    // ① wmic（旧 Win10 可用）
+    const out = await execP(
+      `wmic process where "name='python.exe'" get commandline 2>nul`)
+    if (out.includes('harness.guardian') || out.includes('harness.main')) return true
+    // ② wmic 不可用（Win11 移除）→ PowerShell
+    const psOut = await execP(
+      `powershell -NoProfile -Command "Get-CimInstance Win32_Process -Filter \\"name='python.exe'\\" | Select-Object -ExpandProperty CommandLine"`)
+    return psOut.includes('harness.guardian') || psOut.includes('harness.main')
+  }
+  // 非 Windows（Linux/macOS）：ps 查询
+  const psOut = await execP(`ps -eo command | grep -E 'harness\\.(guardian|main)' | grep -v grep`)
+  return !!psOut
+}
+
+/** detached 拉起 A 侧 harness.guardian（幂等：先确认不存在） */
+export async function ensureHarness(python = 'python',
+                                    opts: MutualOptions = DEFAULTS): Promise<'started' | 'already' | 'failed'> {
+  const running = await harnessRunning()
+  if (running) return 'already'
+  // P1 修复（GPT 审查）：spawn 找不到可执行文件是异步 error 事件，无监听
+  // 会直接崩 Node（Unhandled 'error' event）。加监听 + 超时判定拉起失败。
+  return new Promise((resolve) => {
+    let child: ReturnType<typeof spawn> | null = null
+    let failTimer: NodeJS.Timeout | null = null
+    let okTimer: NodeJS.Timeout | null = null
+    let settled = false
+    const finish = (r: 'started' | 'failed'): void => {
+      if (settled) return
+      settled = true
+      if (failTimer) clearTimeout(failTimer)
+      if (okTimer) clearTimeout(okTimer)
+      resolve(r)
+    }
+    try {
+      child = spawn(python, ['-m', 'harness.guardian'], {
+        windowsHide: true,
+        detached: true,
+        stdio: 'ignore',
+      })
+    } catch (e) {
+      log(opts, `守护失败：${String(e)}`)
+      finish('failed')
+      return
+    }
+    // 拉起失败（python 不存在等）→ 记录 + failed，不崩 Node。
+    // spawn 的 error 事件是异步的：不能立即判 started——等 50ms error 窗口，
+    // 无 error 才算拉起成功（GPT 审查：此前立即返回 started，错误路径也报成功）。
+    child.on('error', (err) => {
+      log(opts, `守护拉起错误：${err.message}`)
+      finish('failed')
+    })
+    // 拉起成功但立即退出（harness.guardian 不存在）→ failed
+    child.on('exit', (code) => {
+      if (code !== null && code !== 0) {
+        log(opts, `守护进程退出 code=${code}（guardian 可能不可用）`)
+        finish('failed')
+      }
+    })
+    okTimer = setTimeout(() => finish('started'), 50)
+    failTimer = setTimeout(() => {
+      log(opts, `守护拉起超时（10s 无健康确认）`)
+      finish('failed')
+    }, 10_000)
+    child.unref()
+    log(opts, `守护动作：拉起 harness.guardian（pid=${child.pid ?? '?'}）`)
+  })
+}
+
+// ---------------------------------------------------------------------------
+// 任务验证邮箱（双通道：白箱 base_verify + DeepSeek 复核）
+// ---------------------------------------------------------------------------
+
+export interface VerifyTask {
+  id: string
+  type: 'verify' | 'knowledge_sync'
+  from: 'A' | 'B'
+  to: 'B' | 'A'
+  payload: { claim: string; evidence?: string; expected?: string; source_ref?: string }
+  status: 'pending' | 'processing' | 'done'
+  created_at: number
+}
+
+export interface VerifyResult {
+  task_id: string
+  verdict: 'pass' | 'fail' | 'needs_revision'
+  whitebox: { judgment: string; best: string; d_norm: number; record_id: string }
+  llm_review: { conclusion: string; reason: string }
+  reasons: string[]
+  evidence: string[]
+  verifier: 'B'
+  at: number
+}
+
+/** 扫描互维目录里 A→B 的 pending 任务 */
+export function scanTasks(opts: MutualOptions = DEFAULTS): VerifyTask[] {
+  const dir = path.join(netDir(opts), 'tasks')
+  if (!fs.existsSync(dir)) return []
+  const out: VerifyTask[] = []
+  for (const f of fs.readdirSync(dir)) {
+    if (!f.startsWith('task-') || !f.endsWith('.json')) continue
+    try {
+      const t = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf-8'))
+      if (t.to === 'B' && t.status === 'pending') out.push(t)
+    } catch { /* 跳过坏文件 */ }
+  }
+  return out
+}
+
+/** 白箱通道：智慧之书 base_verify（通过 bridge 调用，或本地注入） */
+export async function whiteboxVerify(claim: string,
+                                     verifyFn: (c: string) => Promise<{ judgment: string; best: string; d_norm: number; record_id: string }>): Promise<VerifyResult['whitebox']> {
+  try {
+    return await verifyFn(claim)
+  } catch (e) {
+    return { judgment: `whitebox_error: ${String(e)}`, best: '', d_norm: -1, record_id: '' }
+  }
+}
+
+/** 复核通道：DeepSeek 独立复核（在白箱判定之上） */
+export async function llmReview(claim: string, whitebox: VerifyResult['whitebox'],
+                                reviewFn: (c: string, w: VerifyResult['whitebox']) => Promise<{ conclusion: string; reason: string }>): Promise<VerifyResult['llm_review']> {
+  try {
+    return await reviewFn(claim, whitebox)
+  } catch (e) {
+    return { conclusion: `llm_error: ${String(e)}`, reason: '' }
+  }
+}
+
+/** 综合 verdict（白箱优先） */
+export function combineVerdict(w: VerifyResult['whitebox'],
+                               l: VerifyResult['llm_review']): VerifyResult['verdict'] {
+  const c = l.conclusion || ''
+  // P1 修复（GPT 审查）：白箱通道异常 → fail-closed（不因复核「同意」而 pass）
+  if (w.judgment.startsWith('whitebox_error') || w.judgment.startsWith('llm_error')
+      || w.d_norm < 0) {
+    return 'needs_revision'
+  }
+  if (w.judgment.startsWith('采纳')) {
+    // 白箱采纳：复核质疑/不同意→needs_revision（白箱优先，记录分歧）；否则 pass
+    return c.includes('质疑') || c.includes('不同意') || c.includes('不通过')
+      ? 'needs_revision' : 'pass'
+  }
+  if (w.judgment.includes('fail') || w.judgment.includes('不成立')) return 'fail'
+  // 证据不足/无法判断 → 白箱不确定，交给复核决定（「不同意」须排除「同意」子串）
+  if (c.includes('不同意') || c.includes('不通过')) return 'needs_revision'
+  if (c.includes('通过') || c.includes('同意')) return 'pass'
+  // P1 修复（GPT 审查）：「质疑」是分歧信号——白箱不确定 + 复核质疑 → 需要修订，
+  // 此前把「质疑」当 pass 与白箱采纳分支语义矛盾。
+  if (c.includes('质疑')) return 'needs_revision'
+  return 'needs_revision'
+}
+
+/** 任务 ID 安全校验（P1 修复：防路径穿越——task.id 可含 ../../ 写目录外） */
+const TASK_ID_RE = /^[A-Za-z0-9._-]{1,64}$/
+
+export function safeTaskId(id: string): boolean {
+  return TASK_ID_RE.test(id) && !id.includes('..')
+}
+
+/** 处理单个任务：双通道验证 → 写回 result */
+export async function processTask(task: VerifyTask,
+                                  verifyFn: (c: string) => Promise<{ judgment: string; best: string; d_norm: number; record_id: string }>,
+                                  reviewFn: (c: string, w: VerifyResult['whitebox']) => Promise<{ conclusion: string; reason: string }>,
+                                  opts: MutualOptions = DEFAULTS): Promise<VerifyResult | null> {
+  const dir = path.join(netDir(opts), 'tasks')
+  // P1 修复（GPT 审查）：task.id 路径穿越——非法 id 拒绝处理，不写任何文件
+  if (!safeTaskId(task.id)) {
+    log(opts, `任务 ${JSON.stringify(task.id)} 非法（路径穿越风险），拒绝处理`)
+    throw new Error(`非法任务 id: ${task.id}`)
+  }
+  const taskPath = path.join(dir, `task-${task.id}.json`)
+  // P1 完善（GPT 审查·任务竞态）：原子 claim——rename task→processing。
+  // 多实例同时 scanTasks 读到同一 pending 时，rename 只有一方成功；
+  // 失败（文件已被 rename/不存在）= 其他实例正在处理 → 跳过（返回 null）。
+  // 此前无锁：多实例都写 processing/result/done，结果互相覆盖。
+  const claimPath = path.join(dir, `processing-${task.id}.json`)
+  try {
+    fs.renameSync(taskPath, claimPath)
+  }
+  catch {
+    return null // 已被其他实例 claim，或文件不存在
+  }
+  try {
+    const w = await whiteboxVerify(task.payload.claim, verifyFn)
+    const l = await llmReview(task.payload.claim, w, reviewFn)
+    const verdict = combineVerdict(w, l)
+    const result: VerifyResult = {
+      task_id: task.id,
+      verdict,
+      whitebox: w,
+      llm_review: l,
+      reasons: [
+        `白箱判定：${w.judgment}（best=${w.best}，d_norm=${w.d_norm}）`,
+        `复核结论：${l.conclusion}`,
+      ],
+      evidence: [task.payload.source_ref || ''].filter(Boolean),
+      verifier: 'B',
+      at: Date.now() / 1000,
+    }
+    // 结果先写 tmp 再 rename（原子，防半写文件）
+    const resultTmp = path.join(dir, `result-${task.id}.json.tmp`)
+    fs.writeFileSync(resultTmp, JSON.stringify(result, null, 2), 'utf-8')
+    fs.renameSync(resultTmp, path.join(dir, `result-${task.id}.json`))
+    // 完成：清理 claim 文件（rename 回 done 标记供审计）
+    fs.renameSync(claimPath, path.join(dir, `done-${task.id}.json`))
+    log(opts, `任务 ${task.id} 验证完成：${verdict}`)
+    return result
+  }
+  catch (e) {
+    // 处理失败：释放 claim（rename 回 task 供重试）
+    try {
+      fs.renameSync(claimPath, taskPath)
+    }
+    catch { /* 文件可能已不在 */ }
+    throw e
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 日志 / last_contact
+// ---------------------------------------------------------------------------
+
+export function log(opts: MutualOptions, msg: string): void {
+  try {
+    const p = path.join(netDir(opts), 'mutual.log')
+    fs.appendFileSync(p, `[B ${new Date().toISOString()}] ${msg}\n`, 'utf-8')
+  } catch { /* 日志失败不阻塞 */ }
+}
+
+export function writeLastContact(opts: MutualOptions = DEFAULTS): void {
+  try {
+    fs.writeFileSync(path.join(netDir(opts), 'last_contact.json'),
+      JSON.stringify({ last_contact_b: Date.now() / 1000 }), 'utf-8')
+  } catch { /* 非阻塞 */ }
+}
+
+// ---------------------------------------------------------------------------
+// 安装（ctx.effect 作用域内，卸载时清理）
+// ---------------------------------------------------------------------------
+
+export function installMutualMaintenance(
+  ctx: { logger: { info(m: string): void }; interval(fn: () => void, ms: number): () => void; effect(fn: () => () => void, name?: string): void },
+  config: Partial<MutualOptions> = {},
+  hooks: {
+    verify?: (c: string) => Promise<{ judgment: string; best: string; d_norm: number; record_id: string }>
+    review?: (c: string, w: VerifyResult['whitebox']) => Promise<{ conclusion: string; reason: string }>
+  } = {},
+): void {
+  const opts: MutualOptions = { ...DEFAULTS, ...config }
+
+  // 1. 心跳写戳 + 守护 A（10min 周期）
+  // P1 修复（GPT 审查）：cordis-plugin-timer 签名是 interval(callback, delay)
+  // ——此前 (ms, fn) 写反：数字被当 callback、函数被当 delay，回调永不执行，
+  // 互维心跳/任务扫描实际不工作。
+  const heartbeatDispose = ctx.interval(() => {
+    try {
+      writeHeartbeat(opts)
+      // 守护 A：harness 不在 → 拉起
+      ensureHarness('python', opts).then((r) => {
+        if (r === 'started') ctx.logger.info(`mutual: 已拉起 A 侧 harness（${r}）`)
+      })
+      // 读 A 戳分级判定
+      const a = readHeartbeat('a', opts)
+      const verdict = judgeStamp(a, opts)
+      if (verdict === 'warning') ctx.logger.info('mutual: A 侧心跳告警（>25min 未更新）')
+      if (verdict === 'dead') ctx.logger.info('mutual: A 侧失联（>35min），等待 guardian 自愈或告警')
+      writeLastContact(opts)
+    } catch (e) { /* 单次失败不中断 */ }
+  }, opts.heartbeatMs)
+
+  // 2. 任务轮询（30s 周期，检查 A→B 任务）
+  const taskDispose = ctx.interval(() => {
+    try {
+      const tasks = scanTasks(opts)
+      for (const t of tasks) {
+        if (!hooks.verify || !hooks.review) continue
+        processTask(t, hooks.verify, hooks.review, opts).catch((e) => {
+          log(opts, `任务 ${t.id} 处理异常：${String(e)}`)
+        })
+      }
+    } catch (e) { /* 单次失败不中断 */ }
+  }, 30_000)
+
+  // 3. effect 作用域清理
+  ctx.effect(() => {
+    return () => {
+      try {
+        heartbeatDispose()
+        taskDispose()
+      } catch { /* 清理失败不阻塞 */ }
+    }
+  }, 'dsh-memory-mutual')
+}
+
+export default { installMutualMaintenance, writeHeartbeat, readHeartbeat, judgeStamp, scanTasks, processTask }