@furongjun1999/dsh-memory 0.2.9 → 0.3.1

package/src/index.ts

@@ -0,0 +1,268 @@
+/**
+ * @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 { appendFileSync, mkdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { homedir } from 'node:os'
+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'
+
+/**
+ * 调试探针：记录 apply 失败到独立文件（绕过 DSH 日志系统）。
+ * 路径从用户家目录动态解析（issue #5，与 bridge.ts 同因同修）。
+ */
+const APPLY_ERROR_LOG = join(homedir(), '.dsh', 'logs', 'dsh-memory-apply-error.log')
+let applyLogDirReady = false
+function probeApplyError(err: unknown): void {
+  try {
+    if (!applyLogDirReady) {
+      mkdirSync(dirname(APPLY_ERROR_LOG), { recursive: true })
+      applyLogDirReady = true
+    }
+    appendFileSync(APPLY_ERROR_LOG, `[${new Date().toISOString()}] apply failed: ${String(err)}\n${(err as Error).stack ?? ''}\n`)
+  } catch { /* 探针失败忽略 */ }
+}
+
+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)
+
+    // 白箱 LLM 服务商（v0.4 新能力）：把灵枢注册为 DSH 的 provider，
+    // Web/QQ/飞书等所有会话可选「白箱灵枢」模型——白箱直答（零 LLM），
+    // 输入/输出/缓存命中 token 计数对齐 dsh-llm 协议。动态检测 llm 服务。
+    {
+      const { installWhiteboxLlm } = await import('./llm_adapter.js')
+      disposers.push(installWhiteboxLlm(ctx, bridge))
+    }
+
+    // 互维维护（v1.1）：心跳写戳 + 守护 A + 任务验证双通道
+    if (config.mutual.enabled) {
+      // P1 修复（GPT 审查）：timer 是可选服务——缺失时告警跳过互维，
+      // 不让插件因互维而阻塞（inject 已不再强声明 timer）。
+      // 注意：不能直接读 ctx.timer——Cordis 未声明 inject 的属性访问会抛
+      // "cannot get property without inject"（getter 严格）；ctx.get() 安全。
+      const hasTimer = ctx.get('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) {
+    // 探针：记录 apply 失败的具体错误（定位插件加载失败根因）
+    probeApplyError(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/llm_adapter.ts

@@ -0,0 +1,305 @@
+/**
+ * llm_adapter.ts —— 白箱 LLM 服务商（WhiteboxLlmAdapter）
+ *
+ * 设计哲学：白箱本身就是 LLM 模型（对外完全对齐 dsh-llm 协议），内部白箱化。
+ *  - provider: 'lingshu-whitebox'（设置页「模型」可见，可被 agent 默认选用）
+ *  - stream(): 调灵枢 wisdom_chat（白箱 CCG 条件路由/组合生成/自校验）
+ *  - token 计数：输入/输出/缓存命中（白箱直答 = 全部 cacheRead，零推理成本）
+ *  - 降级：白箱无把握（route=llm / 桥未就绪）→ 可选 fallback（后续接 deepseek）
+ *
+ * 结构仿官方 @deepseek-ai/dsh-llm-deepseek adapter。
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { LingshuBridge } from './bridge.js'
+
+// ---- dsh-llm 类型（运行时仅用结构；类型从包引入保持协议对齐）----
+// 不 import 运行时符号，仅引用类型，避免强依赖 dsh-llm 未装时报错。
+export interface LlmStreamChunk {
+  type: 'block-start' | 'text-delta' | 'reasoning-delta' | 'tool-call-delta' | 'block-end' | 'usage' | 'finish'
+  index?: number
+  blockType?: string
+  text?: string
+  id?: string
+  name?: string
+  argumentsDelta?: string
+  block?: { type: string; text?: string; [k: string]: unknown }
+  usage?: { inputTokens: number; outputTokens: number; cacheReadTokens?: number; cacheWriteTokens?: number }
+  reason?: string
+  replayState?: unknown
+}
+
+export interface LlmGenerateOptions {
+  provider: string
+  model: string
+  reasoningEffort?: string
+  messages: Array<{ role: string; content?: Array<{ type?: string; text?: string; arguments?: string; [k: string]: unknown }> }>
+  system?: string
+  tools?: Array<{ name: string; description: string; parameters: Record<string, unknown> }>
+  temperature?: number
+  maxTokens?: number
+  stop?: string[]
+  signal?: AbortSignal
+  sessionId?: string
+  purpose?: 'compaction' | 'session-title'
+}
+
+// ---- token 估算（确定性启发式：CJK 0.6/字符，其余 /4）----
+export function estimateTokens(text: string | undefined | null): number {
+  if (!text) return 0
+  let cjk = 0
+  let other = 0
+  for (const ch of text) {
+    const code = ch.codePointAt(0)!
+    if ((code >= 0x4e00 && code <= 0x9fff) || (code >= 0x3040 && code <= 0x30ff)) cjk++
+    else other++
+  }
+  return Math.ceil(cjk * 0.6 + other / 4)
+}
+
+/** 从 GenerateOptions 汇总输入 token（system + messages 全部文本）。 */
+export function countInputTokens(options: LlmGenerateOptions): number {
+  let total = 0
+  if (options.system) total += estimateTokens(options.system)
+  for (const msg of options.messages ?? []) {
+    for (const block of msg.content ?? []) {
+      if (typeof block?.text === 'string') total += estimateTokens(block.text)
+      if (typeof block?.arguments === 'string') total += estimateTokens(block.arguments)
+    }
+  }
+  return total
+}
+
+/** 把 DSH 会话消息折叠成白箱可读的对话文本。 */
+export function serializeMessages(options: LlmGenerateOptions): string {
+  const parts: string[] = []
+  if (options.system) parts.push(`[系统] ${options.system}`)
+  for (const msg of options.messages ?? []) {
+    const text = (msg.content ?? [])
+      .filter((b) => b?.type === 'text' && typeof b.text === 'string')
+      .map((b) => b.text as string)
+      .join('')
+    if (!text) continue
+    const role = msg.role === 'assistant' ? '灵枢' : msg.role === 'user' ? '用户' : msg.role
+    parts.push(`[${role}] ${text}`)
+  }
+  return parts.join('\n')
+}
+
+/** 把一段完整文本包装成协议流（确定性整段生成 → 单次流）。 */
+export async function* wrapTextStream(
+  text: string,
+  inputTokens: number,
+  outputTokens: number,
+  cacheReadTokens: number,
+): AsyncIterable<LlmStreamChunk> {
+  yield { type: 'block-start', index: 0, blockType: 'text' }
+  yield { type: 'text-delta', index: 0, text }
+  yield { type: 'block-end', index: 0, block: { type: 'text', text } }
+  yield {
+    type: 'usage',
+    usage: {
+      inputTokens,
+      outputTokens,
+      ...(cacheReadTokens > 0 ? { cacheReadTokens } : {}),
+    },
+  }
+  yield { type: 'finish', reason: 'stop' }
+}
+
+/**
+ * 白箱知识卡片格式检测：REVERSE_DAILY 直答是知识库内部格式——
+ * 「X是什么…，是『A』vs『B』的矛盾——X（是…（…（…）…）…真相：①…」
+ * 特征（任一强信号命中即判定）：
+ * ① 卡片开头句式：内容含「，是『X』vs『Y』的矛盾——」（矛盾标记+破折号）
+ * ② 「真相：」结构化标记（卡片分段标题）+ 括号密集（>8）
+ * ③ 长文本（>300）+ 高括号密度（>20）+ 无自然语言标点分隔（顿号密集）
+ */
+export function isCardFormat(text: string): boolean {
+  if (!text) return false
+
+  // ① 强信号：矛盾标记句式（「，是『A』vs『B』的矛盾——」）——卡片开头的
+  //    标志性结构，不受长度门槛限制（短卡片也判定）
+  if (/，是『[^』]{1,12}』vs『[^』]{1,12}』的矛盾[——\-]/.test(text)) return true
+
+  // 短文本（<150）无矛盾标记 → 正常文本
+  if (text.length < 150) return false
+
+  // ② 「真相：」+ 括号密集（卡片的分段结构）
+  if (text.includes('真相：')) {
+    const parens = (text.match(/（/g) ?? []).length
+    if (parens >= 8) return true
+  }
+
+  // ③ 超长 + 极高括号密度（卡片展开体）
+  const parens2 = (text.match(/（/g) ?? []).length
+  if (text.length > 300 && parens2 > 20) return true
+
+  return false
+}
+
+/** 白箱 adapter 依赖注入。 */
+export interface WhiteboxAdapterDeps {
+  /** 灵枢桥（MCP stdio）——白箱引擎通道。 */
+  bridge?: LingshuBridge
+  /**
+   * 降级 LLM：白箱未命中（route=llm / 桥未就绪）时转发。由 installWhiteboxLlm
+   * 注入 DSH 的 llm 服务（走 fallbackProvider 路由），实现「白箱优先 + LLM 降级」。
+   */
+  fallback?: { stream(o: LlmGenerateOptions): AsyncIterable<LlmStreamChunk> }
+}
+
+/** 白箱 LLM adapter —— 注册为 DSH 的 provider。 */
+export class WhiteboxLlmAdapter {
+  private readonly bridge?: LingshuBridge
+  private readonly fallback?: WhiteboxAdapterDeps['fallback']
+
+  constructor(deps: WhiteboxAdapterDeps = {}) {
+    this.bridge = deps.bridge
+    this.fallback = deps.fallback
+  }
+
+  providerInfo(provider: string): { id: string; name: string } {
+    return { id: provider, name: '白箱灵枢 (lingshu-whitebox)' }
+  }
+
+  providerRetryPolicy(): undefined {
+    return undefined
+  }
+
+  async listModels(): Promise<Array<{ provider: string; id: string; name: string }>> {
+    return [
+      { provider: 'lingshu-whitebox', id: 'whitebox-v1', name: '白箱引擎 v1 (CCG 条件路由)' },
+      { provider: 'lingshu-whitebox', id: 'whitebox-wisdom', name: '白箱智慧之书' },
+    ]
+  }
+
+  async resolveModel(provider: string, model: string): Promise<{ provider: string; id: string; name: string }> {
+    return { provider, id: model, name: model }
+  }
+
+  /**
+   * 核心：一次模型调用。白箱优先，无把握降级。
+   * @param options 完全装配的请求（必须 honor options.signal）
+   */
+  async *stream(options: LlmGenerateOptions): AsyncIterable<LlmStreamChunk> {
+    const inputTokens = countInputTokens(options)
+    const conversation = serializeMessages(options)
+    // 取最后一条用户文本作为白箱输入（完整对话太长时截尾）
+    const lastUserText = [...(options.messages ?? [])]
+      .reverse()
+      .flatMap((m) => m.content ?? [])
+      .filter((b) => b?.type === 'text')
+      .map((b) => b.text as string)
+      .join('')
+      .slice(-2000)
+
+    // ---- 白箱主路径：调灵枢 wisdom_chat ----
+    let whitebox: { text: string; route: string } | null = null
+    if (this.bridge?.isReady?.()) {
+      try {
+        const r = await this.bridge.callTool('wisdom_chat', {
+          message: lastUserText || conversation.slice(-4000),
+          session_id: (options.sessionId as string) ?? 'default',
+        }, options.signal)
+        const raw = (r?.content ?? []).map((c) => (c as { text?: string }).text ?? '').join('\n')
+        // 白箱返回结构：{"reply": "...", "route": "self|llm", "hits": [...], "honest": bool}
+        let text = raw
+        let route = 'self'
+        try {
+          const parsed = JSON.parse(raw) as { route?: string; reply?: unknown }
+          if (parsed.route) route = parsed.route
+          if (typeof parsed.reply === 'string') text = parsed.reply
+          else if (parsed.reply !== undefined) text = JSON.stringify(parsed.reply)
+        }
+        catch { /* 非 JSON = 纯文本回复 */ }
+        // 质量门槛（v0.4.1）：REVERSE_DAILY 卡片直答是知识库内部格式——
+        // 「X是什么…是『A』vs『B』的矛盾——X（是…（…）」重复+括号嵌套，
+        // 直接当 LLM 输出喂给用户=「重复回答」。检测到卡片特征 → 视为
+        // 未命中，走降级 LLM（白箱不输出内部格式垃圾）。
+        if (route !== 'llm' && text && text.trim() && !isCardFormat(text)) {
+          whitebox = { text: text.trim(), route }
+        }
+        else if (text && isCardFormat(text)) {
+          console.warn('[whitebox-llm] 白箱返回知识卡片格式，降级 LLM（内部格式不直出）')
+        }
+      }
+      catch (err) {
+        // 白箱异常不阻塞——记日志后走降级
+        console.warn('[whitebox-llm] 白箱调用失败，降级:', String(err))
+      }
+    }
+
+    if (whitebox) {
+      const outputTokens = estimateTokens(whitebox.text)
+      // 白箱直答 = 全缓存命中（条件路由固化命中，零推理成本）
+      yield* wrapTextStream(whitebox.text, inputTokens, outputTokens, inputTokens)
+      return
+    }
+
+    // ---- 降级路径：白箱无把握 / 桥未就绪 ----
+    if (this.fallback) {
+      console.warn('[whitebox-llm] 白箱未命中，转降级 LLM')
+      yield* this.fallback.stream(options)
+      return
+    }
+    // 无降级可用：诚实声明（盲区 28：未来承诺不可检验——不假装回答）
+    const honest = '（白箱引擎未命中且降级 LLM 未配置——按白箱纪律，我诚实声明不知道，不编造答案。）'
+    yield* wrapTextStream(honest, inputTokens, estimateTokens(honest), 0)
+  }
+}
+
+/** provider 路由名（设置页「模型」下拉可见）。 */
+export const WHITEBOX_PROVIDER = 'lingshu-whitebox'
+
+/**
+ * 注册白箱 provider 到 DSH llm 服务（动态检测，不强依赖 llm 服务——
+ * 最小 host 无 llm 时跳过，插件其余功能不受影响）。
+ * @returns 注销函数；未注册返回 noop。
+ */
+export function installWhiteboxLlm(ctx: Context, bridge: LingshuBridge | undefined): () => void {
+  // 动态检测 llm 服务（P1 模式：timer/webServer 同理）。
+  // 注意：不能直接读 ctx.llm——Cordis 未声明 inject 的属性访问会抛
+  // "cannot get property without inject"；ctx.get('llm') 安全返回 undefined。
+  const llm = ctx.get('llm') as
+    | {
+      registerAdapter?: (p: string[], a: unknown) => { replace?: (p: string[]) => void }
+      registerConfigurableProviders?: (e: unknown[]) => void
+      stream?: (o: Record<string, unknown>) => AsyncIterable<LlmStreamChunk>
+      listProviders?: () => Array<{ id: string }>
+    }
+    | undefined
+  if (!llm?.registerAdapter) {
+    ctx.logger?.info?.('dsh-memory: llm 服务不可用，跳过白箱 provider 注册（最小 host）')
+    return () => {}
+  }
+
+  // 降级 LLM：白箱未命中时转发给 fallbackProvider 路由（默认 deepseek-official，
+  // 可在 settings.yaml 的 llm-whitebox.fallbackProvider 覆盖）。通过 llm.stream
+  // 重路由——保持 DSH 的全链路（重试/瀑布流/用量计量）。
+  const fallbackProvider = 'deepseek-official'
+  const fallback: WhiteboxAdapterDeps['fallback'] | undefined = llm.stream
+    ? {
+      stream(options) {
+        return llm.stream!({ ...options, provider: fallbackProvider })
+      },
+    }
+    : undefined
+
+  const adapter = new WhiteboxLlmAdapter({ bridge, fallback })
+  try {
+    llm.registerConfigurableProviders?.([{
+      provider: WHITEBOX_PROVIDER,
+      displayName: '白箱灵枢 (Whitebox)',
+      settingsNs: 'llm-whitebox',
+      settingsPath: [],
+    }])
+    const registration = llm.registerAdapter([WHITEBOX_PROVIDER], adapter)
+    ctx.logger?.info?.('dsh-memory: 白箱 LLM provider 已注册: %s（降级→%s）', WHITEBOX_PROVIDER, fallbackProvider)
+    return () => { try { registration?.replace?.([]) } catch { /* 忽略注销异常 */ } }
+  }
+  catch (err) {
+    ctx.logger?.warn?.('dsh-memory: 白箱 provider 注册失败: %s', String(err))
+    return () => {}
+  }
+}