dsh-memory-eternal 0.1.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,87 @@
+# 架构说明（Architecture）
+
+记忆核心（dsh-memory-eternal）是一个独立 DSH 插件，采用「host 半边负责数据与逻辑、client 半边负责图形化界面」的双进程结构，与 [dsh-ui-three-body](https://github.com/EternalNight996/dsh-ui-three-body) 同一套插件装载机制。
+
+```
+┌───────────────────────── DSH Web (browser) ─────────────────────────┐
+│  src/client/index.tsx → lib/client.js (esbuild 打包)                │
+│  · 设置 → 记忆 页面（slots settings.section 挂载）                   │
+│  · 统计 / 检索 / 知识卡网格 / 知识图谱（fetch /memory-eternal/api/*）    │
+└───────────────┬─────────────────────────────────────▲───────────────┘
+                │ fetch（同源 webServer 路由）          │ JSON
+┌───────────────▼─────────────────────────────────────┴───────────────┐
+│  index.js（host 半边，DSH Node 进程）                               │
+│  · settings 命名空间 memory-eternal                                    │
+│  · agent/turn-stopping 钩子 → 自动沉淀管线                          │
+│  · systemPrompt 召回段 + memory_recall 工具                         │
+│  · webServer /memory-eternal/api/* JSON 路由                           │
+│  ├── lib/vault.js     Markdown Vault 存储层（纯 Node，可单测）      │
+│  └── lib/capture.js   自动沉淀管线（LLM 压缩 + 语义去重）            │
+└───────────────────────────┬─────────────────────────────────────────┘
+                            ▼
+              ~/.dsh/memory-vault/（本地 Markdown 知识库）
+```
+
+## 数据流
+
+### 自动沉淀（写入路径）
+
+1. `agent/turn-stopping`（serial 事件）触发：同步抓取 `agent.session.events` 增量快照（按 seq 过滤，`sliceNewEvents`），不阻塞收尾。
+2. 后台队列执行 `runCapture`：
+   - `extractLastTurn` 提取 user/assistant 文本（工具结果不进入）；
+   - 短于 `captureMinChars` 直接跳过；日配额 `maxCardsPerDay` 防烧 token；
+   - `resolveRoute` 取当前 provider 旗舰模型（与驯兽师一致）；
+   - `pickNeighbors` 按关键词重叠选出最相关已有卡（≤8 张，控制 token）；
+   - `summarizeTurn` 把对话 + 已有卡索引交给模型，输出严格 JSON：
+     - `{"save":false}` → 丢弃；
+     - `{"append_to","update"}` → 追加更新记录到已有卡（语义去重，免疫 LLM 改写）；
+     - `{"save":true,title,kind,tags,body}` → 写新卡。
+3. `writeCard` 写入前再做**词法去重**（Jaccard 字符 bigram，阈值 0.62，移植 boujoy）：命中则拒绝新建、改为 `appendUpdate` 追加「更新记录」段。
+
+### 自动召回（读取路径）
+
+- `systemPrompt.section`：注入「你拥有记忆核心 + 规则」段（可配置关闭）；
+- `memory_recall` 工具：CJK 感知检索（整词 + 中文字符 bigram），返回命中卡摘要。
+
+### 图形化知识库（client 路径）
+
+- `settings.section` id=`memory-eternal`：统计概览、搜索框（280ms 防抖）、kind 筛选、知识卡网格、SVG 知识图谱；
+- 数据源：host `webServer.register({kind:'prefix', path:'/memory-eternal/api'})`，端点：
+  - `GET /overview` — 统计（总数/分 kind/近 7 天/标签数/vault 路径）
+  - `GET /cards?kind=&q=&limit=` — 卡片列表
+  - `GET /card?path=` — 卡片全文（阅读弹层）
+  - `GET /search?q=` — 检索命中
+  - `GET /graph` — 图谱节点与边（wikilink + 共享标签）
+
+## 关键设计决策
+
+| 决策 | 理由 |
+| --- | --- |
+| Vault = 普通 Markdown | 用户拥有数据；可手动编辑、可 git、可被 Obsidian 等工具读取；不锁进私有数据库 |
+| 模型决定「建/并/弃」 | 对齐 boujoy「模型判定价值与压缩」哲学；语义去重比纯词法更抗 LLM 改写 |
+| 词法去重兜底 | 低成本防重复卡堆积；阈值与 boujoy 一致（0.62） |
+| 增量 seq 捕获 | 多轮会话不重复处理历史；避免把整段历史重复喂给模型 |
+| 后台队列 + 日配额 | 不阻塞 turn 收尾；防止大扫荡烧光 token |
+| 同源 fetch API | 不引入 typert/Remote 复杂度；client 只需 `fetch('/memory-eternal/api/…')` |
+
+## 目录结构
+
+```
+dsh-memory-eternal/
+├── index.js             # host 半边
+├── lib/
+│   ├── vault.js         # Vault 存储层（parseCard/safeSlug/textSimilarity/dedupCheck/queryTerms/listCards/search/graph/overview/writeCard/appendUpdate/ensureVault/readCard）
+│   └── capture.js       # 沉淀管线（summarizeTurn/parseCaptureJson/extractLastTurn/sliceNewEvents/pickNeighbors/captureCard/captureUpdate/makeDedupChecker）
+├── src/client/index.tsx # client 半边（设置页 UI）
+├── build.mjs            # esbuild → lib/client.js
+├── cordis.patch.yml     # bundle 补丁层
+├── tests/               # node:test 单测（vault 12 + capture 12 + api 5 = 29）
+├── README.md / PUBLISH.md / LICENSE
+└── assets/              # README 截图（memory-preview.png）
+```
+
+## 依赖
+
+- 运行时（host）：`@deepseek-ai/schemastery`（配置 schema）、`@deepseek-ai/dsh-tools`（工具）、`@deepseek-ai/dsh-llm`（流式模型调用）——均为 peerDependency，由 DSH 提供。
+- 构建（dev）：esbuild。
+- client：仅 React（DSH `__ModuleLoader__` 注入），零第三方 UI 依赖。

package/index.js

@@ -0,0 +1,283 @@
+// 记忆核心（host 侧）：自动沉淀 + 自动召回 + 知识库 JSON API。
+//
+// 职责：
+// 1. 注册 `memory-eternal` 设置命名空间（enabled / autoCapture / autoRecall /
+//    vaultDir / dedupThreshold / captureMinChars / captureCooldownMs）。
+// 2. 监听 `agent/turn-stopping`：每轮对话结束自动把「值得长期复用的内容」
+//    压缩成知识卡写入本地 Markdown Vault（去重守卫：相似卡拒绝新建、改为
+//    追加更新记录）。零人工干预。
+// 3. 注入 systemPrompt 分段：告知 Agent 它有一块记忆核心、可随时
+//    memory_recall 召回历史上下文；并注册 `memory_recall` 工具。
+// 4. 注册 `/memory-eternal/api/*` JSON 路由：供客户端设置页渲染统计 / 卡片 /
+//    知识图谱 / 检索。
+//
+// 存储全部落在本地 Markdown Vault（默认 $DSH_HOME/memory-vault），不依赖
+// 外部数据库；卡是普通 .md 文件，可手动编辑、可 git 管理。
+
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import z from '@deepseek-ai/schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { ensureVault, listCards, readCard, search, graph, overview } from './lib/vault.js'
+import { summarizeTurn, extractLastTurn, sliceNewEvents, resolveRoute, captureCard, captureUpdate, pickNeighbors } from './lib/capture.js'
+
+export const name = 'memory-eternal'
+export const inject = ['systemPrompt', 'settings']
+
+export const Config = z.object({
+  enabled: z.boolean().default(true),
+  autoCapture: z.boolean().default(true),
+  autoRecall: z.boolean().default(true),
+  vaultDir: z.string().default(''),
+  dedupThreshold: z.number().min(0).max(1).default(0.62),
+  captureMinChars: z.number().default(200),
+  captureCooldownMs: z.number().default(5 * 60 * 1000),
+  maxCardsPerDay: z.number().default(60),
+})
+
+const API_PREFIX = '/memory-eternal/api'
+
+export function apply(ctx, config) {
+  const settings = ctx.settings.register('memory-eternal', Config, { base: config ?? {} })
+
+  const vaultDir = () => {
+    const cfg = settings.get() ?? {}
+    if (cfg.vaultDir && cfg.vaultDir.trim()) return path.resolve(cfg.vaultDir.trim())
+    const home = process.env.DSH_HOME || path.join(os.homedir(), '.dsh')
+    return path.join(home, 'memory-vault')
+  }
+
+  // -- 1. 自动沉淀 ---------------------------------------------------------
+  // agent/turn-stopping 是 serial 事件：不在监听器里 await LLM（会拖慢收尾），
+  // 同步抓取增量事件快照后，把真正的捕获调度到后台队列执行。
+  const pending = new Map() // sessionId -> merged events array
+  let captureQueue = Promise.resolve()
+
+  const scheduleCapture = (agent, events, lastSeq) => {
+    const cfg = settings.get() ?? {}
+    if (!cfg.enabled || !cfg.autoCapture) return
+    const sessionId = agent?.session?.id ?? agent?.id ?? 'unknown'
+    const newEvents = sliceNewEvents(events, lastSeq)
+    if (newEvents.length === 0) return
+    const existing = pending.get(sessionId)
+    if (existing) {
+      // 连续轮次合并：把新事件接到待处理队列尾，一次 LLM 调用处理。
+      pending.set(sessionId, [...existing, ...newEvents])
+      return
+    }
+    pending.set(sessionId, newEvents)
+    captureQueue = captureQueue.then(() => runCapture(agent, pending.get(sessionId) ?? newEvents))
+  }
+
+  const runCapture = async (agent, events) => {
+    try {
+      const cfg = settings.get() ?? {}
+      if (!cfg.enabled || !cfg.autoCapture) return
+      const llm = ctx.get('llm')
+      if (!llm) return
+      const text = extractLastTurn(events)
+      if (text.length < (cfg.captureMinChars ?? 200)) return
+      // 日配额：防止一次大扫荡烧光 token。
+      if (!(await underDailyQuota(cfg.maxCardsPerDay))) return
+      const route = await resolveRoute(llm)
+      if (!route) return
+      // 语义去重近邻：把已有卡片索引喂给模型，让模型决定新建 vs 追加。
+      const draft = { title: '', body: text.slice(0, 400) }
+      const neighbors = await pickNeighbors(vaultDir(), draft, 8)
+      const result = await summarizeTurn(llm, route, text, { signal: AbortSignal.timeout(45000), existing: neighbors })
+      if (!result || result.save !== true) return
+      if (result.append_to) {
+        // 模型判定属于已有卡 → 追加更新记录，不新建（boujoy 语义）。
+        await captureUpdate(vaultDir(), result.append_to, result.update, { threshold: cfg.dedupThreshold })
+        return
+      }
+      const card = {
+        kind: result.kind,
+        title: result.title,
+        tags: result.tags,
+        body: result.body,
+        source: agent?.session?.id ? `session:${agent.session.id}` : '',
+      }
+      const out = await captureCard(vaultDir(), card, { threshold: cfg.dedupThreshold })
+      if (!out.ok && out.duplicate) {
+        // 词法兜底：高度相似 → 追加更新记录而不是再建一张重复卡。
+        await captureUpdate(vaultDir(), out.duplicate.path, `${result.title}：${result.body.slice(0, 400)}`, {
+          threshold: cfg.dedupThreshold,
+        })
+      }
+    } catch (error) {
+      console.error('[memory-eternal] capture failed:', error)
+    } finally {
+      const sessionId = agent?.session?.id ?? agent?.id ?? 'unknown'
+      pending.delete(sessionId)
+    }
+  }
+
+  const lastDayStamps = []
+  const underDailyQuota = async (max) => {
+    const now = Date.now()
+    const dayStart = now - 86400000
+    while (lastDayStamps.length && lastDayStamps[0] < dayStart) lastDayStamps.shift()
+    if (lastDayStamps.length >= (max ?? 60)) return false
+    lastDayStamps.push(now)
+    return true
+  }
+
+  const lastSeqs = new Map() // sessionId -> last processed seq
+  ctx.on('agent/turn-stopping', ({ agent }) => {
+    const events = agent?.session?.events
+    if (!Array.isArray(events)) return
+    const sessionId = agent?.session?.id ?? agent?.id ?? 'unknown'
+    const lastSeq = lastSeqs.get(sessionId) ?? 0
+    scheduleCapture(agent, events, lastSeq)
+    lastSeqs.set(sessionId, events.length ? events[events.length - 1].seq : lastSeq)
+  })
+
+  // -- 2. 自动召回：systemPrompt 分段 + memory_recall 工具 -----------------
+  ctx.effect(() => {
+    let disposeSection = null
+    const refresh = (cfg) => {
+      if (disposeSection) {
+        const dispose = disposeSection
+        disposeSection = null
+        dispose()
+      }
+      if (!cfg || cfg.enabled === false || cfg.autoRecall !== true) return
+      const text = [
+        '你拥有一个本地「记忆核心」（Markdown 知识库，位于 ' + vaultDir() + '）。',
+        '规则：',
+        '1. 每轮对话结束后，值得长期复用的内容会被自动沉淀成知识卡，你无需询问用户、也无需手动保存。',
+        '2. 当任务需要项目背景、历史决策、之前讨论过的方案或领域知识时，先调用 memory_recall 检索相关卡片，再作答。',
+        '3. 若检索结果为空，就诚实说明当前记忆库没有相关内容，不要编造。',
+        '4. 知识卡是普通 Markdown 文件，你可以用文件工具直接读写它。',
+      ].join('\n')
+      disposeSection = ctx.systemPrompt.section({
+        name: 'memory-eternal: auto-recall',
+        order: 600,
+        text,
+      })
+    }
+    refresh(settings.get())
+    const unwatch = settings.watch(refresh)
+    return () => {
+      if (typeof unwatch === 'function') unwatch()
+      if (disposeSection) disposeSection()
+    }
+  }, 'memory-eternal: recall section')
+
+  const tools = ctx.get('tools')
+  if (tools !== undefined) {
+    tools.register(defineTool({
+      name: 'memory_recall',
+      description:
+        '从本地记忆核心（Markdown 知识库）检索相关知识卡。需要项目背景、历史决策、之前讨论过的方案、' +
+        '或领域知识时调用；返回最相关的卡片摘要。用 query 描述要找的内容，支持中文整词与字符片段检索。',
+      parameters: {
+        query: { type: 'string', required: true, description: '检索关键词或自然语言描述，如「数据库选型」「用户偏好」' },
+        limit: { type: 'number', description: '返回卡片数上限，默认 5' },
+      },
+      output: {
+        schema: { type: 'string' },
+        render(_a, v) { return [{ type: 'text', text: v }] },
+      },
+      timeoutMs: 20000,
+      async execute(args) {
+        const cfg = settings.get() ?? {}
+        if (!cfg.enabled) return '（记忆核心已禁用）'
+        const query = String(args.query || '').trim()
+        if (!query) return '（未提供检索词）'
+        const limit = Math.min(Math.max(Number(args.limit) || 5, 1), 20)
+        const hits = await search(vaultDir(), query, { limit })
+        if (hits.length === 0) return `记忆库中没有与「${query}」相关的内容。`
+        const lines = hits.map((h, i) => {
+          const tags = h.tags.length ? ` [${h.tags.join(', ')}]` : ''
+          return `### ${i + 1}. ${h.title}${tags}\n路径：${h.path}\n${h.summary || ''}`
+        })
+        return `从记忆核心检索到 ${hits.length} 条相关卡片：\n\n${lines.join('\n\n')}`
+      },
+    }))
+  }
+
+  // -- 3. 知识库 JSON API（客户端设置页数据源） ----------------------------
+  const webServer = ctx.get('webServer')
+  if (webServer !== undefined) {
+    webServer.register({
+      kind: 'prefix',
+      path: API_PREFIX,
+      handler: async (req, res) => {
+        try {
+          await handleApi(req, res, vaultDir())
+        } catch (error) {
+          json(res, 500, { ok: false, error: String(error?.message || error) })
+        }
+      },
+    })
+  }
+
+  // 首次激活时确保 vault 目录存在。
+  ctx.effect(() => {
+    const root = vaultDir()
+    ensureVault(root).catch((error) => console.error('[memory-eternal] ensureVault failed:', error))
+  }, 'memory-eternal: ensure vault')
+}
+
+// -- API -------------------------------------------------------------------
+
+async function handleApi(req, res, vaultRoot) {
+  const url = new URL(req.url, 'http://localhost')
+  const route = url.pathname.slice(API_PREFIX.length).replace(/\/+$/, '') || '/overview'
+  const query = url.searchParams
+
+  switch (route) {
+    case '/overview': {
+      await ensureVault(vaultRoot)
+      json(res, 200, { ok: true, vaultDir: vaultRoot, ...(await overview(vaultRoot)) })
+      return
+    }
+    case '/cards': {
+      const kind = query.get('kind') || ''
+      const q = query.get('q') || ''
+      const limit = Math.min(Number(query.get('limit')) || 200, 500)
+      let cards = await listCards(vaultRoot)
+      if (kind) cards = cards.filter((c) => c.kind === kind)
+      if (q.trim()) {
+        const hits = await search(vaultRoot, q, { limit: 200 })
+        const hitPaths = new Set(hits.map((h) => h.path))
+        cards = cards.filter((c) => hitPaths.has(c.path))
+      }
+      json(res, 200, { ok: true, cards: cards.slice(0, limit) })
+      return
+    }
+    case '/card': {
+      const rel = query.get('path') || ''
+      if (!rel) return json(res, 400, { ok: false, error: '缺少 path' })
+      const text = await readCard(vaultRoot, rel)
+      json(res, 200, { ok: true, path: rel, text })
+      return
+    }
+    case '/search': {
+      const q = query.get('q') || ''
+      if (!q.trim()) return json(res, 200, { ok: true, hits: [] })
+      json(res, 200, { ok: true, hits: await search(vaultRoot, q, { limit: 30 }) })
+      return
+    }
+    case '/graph': {
+      await ensureVault(vaultRoot)
+      json(res, 200, { ok: true, ...(await graph(vaultRoot)) })
+      return
+    }
+    default:
+      json(res, 404, { ok: false, error: '未知接口' })
+  }
+}
+
+function json(res, status, body) {
+  const payload = JSON.stringify(body)
+  res.writeHead(status, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Content-Length': Buffer.byteLength(payload),
+    'Cache-Control': 'no-store',
+  })
+  res.end(payload)
+}

package/lib/capture.js

@@ -0,0 +1,221 @@
+// 记忆核心 · 自动沉淀管线
+//
+// 移植 boujoy-harness 的「知识捕获」理念：模型负责判定价值（score）与压缩
+// （卡片正文），本模块只负责安全（写哪、多短拒绝、去重守卫）。
+//
+// 与 boujoy 的区别：不需要用户点「沉淀」——会话每轮结束后由 index.js 监听
+// agent/turn-stopping 自动触发 summarizeTurn → writeCard/appendUpdate。
+//
+// 去重：两级。第一级是词法（Jaccard bigram，阈值 0.62，捕获纯重复）；第二级
+// 是语义——把「现有卡片索引」（标题+摘要，最多近邻 8 张）喂给模型，让模型
+// 判断新知识是「新建卡片」还是「追加到已有卡片」（append_to），这正是
+// boujoy 的「追加更新记录，不要堆重复卡」语义，且对 LLM 改写免疫。
+
+import { writeCard, appendUpdate, textSimilarity, dedupCheck, listCards, queryTerms } from './vault.js'
+
+/** 默认去重阈值（与 boujoy 一致）。 */
+export const DEDUP_THRESHOLD = 0.62
+
+/** 参与语义去重的近邻卡片数上限（控制 token）。 */
+export const DEDUP_NEIGHBORS = 8
+
+/**
+ * 用当前模型把一段对话压缩成知识卡（或判定不值得保存 / 应追加到已有卡）。
+ * @param llm - dsh 的 llm 服务（ctx.get('llm')）
+ * @param route - { provider, model } 解析结果
+ * @param conversation - 本轮对话文本（用户+助手）
+ * @param opts - { maxTokens, signal, existing }：existing 为 [{path,title,summary}]
+ * @returns Promise<null | { save:boolean } | { save:true, title, kind, tags, body } | { append_to, update }>
+ */
+export async function summarizeTurn(llm, route, conversation, opts = {}) {
+  const text = String(conversation || '').trim()
+  if (text.length < 120) return null // 太短，没有沉淀价值
+
+  const existing = Array.isArray(opts.existing) ? opts.existing.slice(0, DEDUP_NEIGHBORS) : []
+  const existingBlock = existing.length
+    ? '\n\n## 记忆库已有卡片索引（若新知识属于其中某张，必须用 append_to 追加而不是新建）\n' +
+      existing.map((e, i) => `${i + 1}. [${e.path}] ${e.title}${e.summary ? `：${e.summary.slice(0, 120)}` : ''}`).join('\n')
+    : ''
+
+  const system = [
+    '你是本地知识库的「记忆沉淀引擎」。你的唯一任务：判断一段对话中是否有值得长期复用的知识，若有则压缩成一张知识卡。',
+    '判断标准（全部满足才保存）：',
+    '1. 内容对未来有复用价值（技术方案、项目背景、设计决策、领域知识、偏好约定等）；',
+    '2. 不是纯闲聊、寒暄或一次性指令；',
+    '3. 与已有知识不重复（见下）。',
+    '输出严格 JSON（不要 markdown 代码块、不要多余文字）：',
+    '{"save": false} 表示不值得保存；',
+    '否则输出：',
+    '{"save": true, "title": "简短标题", "kind": "knowledge|project|content|prompt|business", "tags": ["标签"], "body": "300-800字的压缩正文，markdown，含要点列表，首行是# 标题"}',
+    'kind 含义：project=项目背景/进度；knowledge=通用知识/技术方案/设计决策；content=内容素材/资料；prompt=提示词/工作流；business=业务/商业。',
+    '正文要求：去掉对话口水，只留可复用的结论、参数、步骤、原因。语言与对话一致。',
+    '已有卡片规则：若新知识与某张已有卡片是同一主题（同一技术、同一项目、同一决策），不要新建——输出',
+    '{"append_to": "已有卡片的 path 字段原样", "update": "追加/修正的短文本（一段话）"}',
+    '只有当已有卡片索引为空或不相关时，才新建卡片。',
+  ].join('\n')
+
+  const { BlockAssembler, createUserMessage } = await importLlmHelpers()
+  const assembler = new BlockAssembler()
+  const messages = [createUserMessage({
+    content: [{ type: 'text', text: text + existingBlock }],
+    source: { kind: 'plugin', plugin: 'memory-eternal' },
+  })]
+
+  const options = {
+    provider: route.provider,
+    model: route.model,
+    messages,
+    system,
+    maxTokens: opts.maxTokens ?? 900,
+    reasoningEffort: 'off',
+    purpose: 'memory-capture',
+    signal: opts.signal ?? AbortSignal.timeout(45000),
+  }
+  for await (const chunk of llm.stream(options)) assembler.push(chunk)
+  const out = assembler.blocks().filter((b) => b.type === 'text').map((b) => b.text).join('').trim()
+  return parseCaptureJson(out)
+}
+
+/**
+ * 语义去重近邻：按关键词重叠为候选卡排序，返回最相似的若干张。
+ * 关键词 = 新卡标题/正文的 CJK 整词 + bigram 与已有卡标题/摘要的命中数。
+ */
+export async function pickNeighbors(root, card, limit = DEDUP_NEIGHBORS) {
+  const haystack = `${card.title}\n${card.body}`.toLowerCase()
+  const wanted = queryTerms(haystack)
+  const cards = await listCards(root)
+  const scored = []
+  for (const existing of cards) {
+    let score = 0
+    const target = `${existing.title}\n${existing.summary}`.toLowerCase()
+    for (const term of wanted) if (target.includes(term.toLowerCase())) score += 1
+    if (score > 0) scored.push({ ...existing, score })
+  }
+  scored.sort((a, b) => b.score - a.score)
+  return scored.slice(0, limit)
+}
+
+/**
+ * 去重守卫：目标目录里已有高度相似卡片时返回它，否则返回 null。
+ * @returns Promise<null | { path, score }>
+ */
+export function makeDedupChecker(dir) {
+  return (text, threshold = DEDUP_THRESHOLD) => dedupCheck(dir, text, threshold)
+}
+
+/** 写卡（带目录级去重守卫），命中返回 duplicate 而非写卡。 */
+export async function captureCard(root, card, opts = {}) {
+  const threshold = opts.threshold ?? DEDUP_THRESHOLD
+  return writeCard(root, card, { threshold, dedup: true })
+}
+
+/** 追加更新记录（去重命中时）。 */
+export async function captureUpdate(root, rel, text, opts = {}) {
+  return appendUpdate(root, rel, text, { threshold: opts.threshold ?? DEDUP_THRESHOLD })
+}
+
+// -- helpers ---------------------------------------------------------------
+
+async function importLlmHelpers() {
+  // 延迟加载，避免在无 llm 服务时拉高启动成本；dsh-llm 是 peerDependency。
+  const { BlockAssembler, createUserMessage } = await import('@deepseek-ai/dsh-llm')
+  return { BlockAssembler, createUserMessage }
+}
+
+export function parseCaptureJson(text) {
+  if (!text) return null
+  // 去掉可能的 ```json 围栏
+  const cleaned = text.replace(/^```(?:json)?\s*/i, '').replace(/```\s*$/, '').trim()
+  let parsed
+  try {
+    parsed = JSON.parse(cleaned)
+  } catch {
+    // 容错：截取第一个 { 到最后一个 }
+    const start = cleaned.indexOf('{')
+    const end = cleaned.lastIndexOf('}')
+    if (start < 0 || end <= start) return null
+    try {
+      parsed = JSON.parse(cleaned.slice(start, end + 1))
+    } catch {
+      return null
+    }
+  }
+  if (!parsed || parsed.save === false) return { save: false }
+  // 追加已有卡片：append_to 命中的优先级最高
+  if (parsed.append_to) {
+    const target = String(parsed.append_to).trim()
+    const update = String(parsed.update || '').trim()
+    if (target && update.length >= 10) return { append_to: target, update }
+    return null
+  }
+  const title = String(parsed.title || '').trim().slice(0, 80)
+  const body = String(parsed.body || '').trim()
+  if (!title || body.length < 20) return null
+  const kind = ['project', 'knowledge', 'content', 'prompt', 'business'].includes(parsed.kind) ? parsed.kind : 'knowledge'
+  const tags = Array.isArray(parsed.tags)
+    ? parsed.tags.map((t) => String(t).trim().slice(0, 30)).filter(Boolean).slice(0, 8)
+    : []
+  return { save: true, title, kind, tags, body }
+}
+
+/** 从会话事件里提取「增量片段」的可读对话文本（用户 + 助手）。 */
+export function extractLastTurn(events, _turn) {
+  const lines = []
+  const pushMessage = (event) => {
+    const data = event.data || event
+    const message = data.message || data
+    const role = message.role
+    const content = message.content
+    if (Array.isArray(content)) {
+      for (const block of content) {
+        if (block.type === 'text' && block.text) lines.push(`${role === 'user' ? '用户' : '助手'}：${block.text}`)
+      }
+    } else if (typeof content === 'string' && content) {
+      lines.push(`${role === 'user' ? '用户' : '助手'}：${content}`)
+    }
+  }
+  for (const event of events) {
+    const type = event.type
+    const data = event.data || event
+    if (type === 'user/message' || (type === 'message' && data.role === 'user')) {
+      pushMessage(data)
+    } else if (type === 'assistant/message' || type === 'assistant/chunk') {
+      if (type === 'assistant/message') pushMessage(data)
+      else if (data.chunk?.content) {
+        const content = data.chunk.content
+        if (typeof content === 'string') lines.push(`助手：${content}`)
+        else if (Array.isArray(content)) {
+          for (const block of content) {
+            if (block.type === 'text' && block.text) lines.push(`助手：${block.text}`)
+          }
+        }
+      }
+    }
+  }
+  return lines.join('\n').trim()
+}
+
+/** 取增量事件：seq 大于 lastSeq 的 user/assistant 消息事件。 */
+export function sliceNewEvents(events, lastSeq) {
+  const out = []
+  for (const event of events) {
+    const seq = event.seq
+    if (seq !== undefined && lastSeq !== undefined && seq <= lastSeq) continue
+    const type = event.type
+    if (type === 'user/message' || type === 'assistant/message') out.push(event)
+  }
+  return out
+}
+
+/** 解析当前模型路由：取第一个 provider 的旗舰模型（与驯兽师一致）。 */
+export async function resolveRoute(llm) {
+  try {
+    const providers = llm.listProviders()
+    if (!providers || providers.length === 0) return null
+    const models = await llm.listModels(providers[0].id)
+    if (!models || models.length === 0) return null
+    return { provider: providers[0].id, model: models[0].id }
+  } catch {
+    return null
+  }
+}

package/lib/client.js

@@ -0,0 +1,47 @@
+window.__ModuleLoader__.load({
+  id: "dsh-memory-eternal",
+  factory: (require) => {
+    var module = { exports: {} };
+    var exports = module.exports;
+var R=Object.create;var S=Object.defineProperty;var O=Object.getOwnPropertyDescriptor;var A=Object.getOwnPropertyNames;var L=Object.getPrototypeOf,B=Object.prototype.hasOwnProperty;var T=(e,r)=>{for(var l in r)S(e,l,{get:r[l],enumerable:!0})},I=(e,r,l,n)=>{if(r&&typeof r=="object"||typeof r=="function")for(let d of A(r))!B.call(e,d)&&d!==l&&S(e,d,{get:()=>r[d],enumerable:!(n=O(r,d))||n.enumerable});return e};var H=(e,r,l)=>(l=e!=null?R(L(e)):{},I(r||!e||!e.__esModule?S(l,"default",{value:e,enumerable:!0}):l,e)),G=e=>I(S({},"__esModule",{value:!0}),e);var re={};T(re,{apply:()=>F,inject:()=>q});module.exports=G(re);var t=H(require("react"),1),w="memory-eternal",E="/memory-eternal/api",q=["settingsScope","slots","locale","connection","remote"],U={nav:"\u8BB0\u5FC6",loading:"\u52A0\u8F7D\u4E2D\u2026",refresh:"\u5237\u65B0",overview:"\u8BB0\u5FC6\u5E93\u6982\u89C8",total:"\u77E5\u8BC6\u5361",recent:"\u8FD1 7 \u5929\u65B0\u589E",tags:"\u6807\u7B7E",searchPlaceholder:"\u641C\u7D22\u8BB0\u5FC6\uFF08\u652F\u6301\u4E2D\u6587\u7247\u6BB5\uFF09\u2026",search:"\u641C\u7D22",all:"\u5168\u90E8",kindProject:"\u9879\u76EE",kindKnowledge:"\u77E5\u8BC6",kindContent:"\u5185\u5BB9",kindPrompt:"\u63D0\u793A\u8BCD",kindBusiness:"\u4E1A\u52A1",graph:"\u77E5\u8BC6\u56FE\u8C31",graphHint:"\u8282\u70B9=\u77E5\u8BC6\u5361\uFF1B\u8FDE\u7EBF=[[\u94FE\u63A5]] \u6216\u5171\u4EAB\u6807\u7B7E\u3002\u70B9\u51FB\u8282\u70B9\u9605\u8BFB\u5361\u7247\u3002",empty:"\u8BB0\u5FC6\u5E93\u8FD8\u662F\u7A7A\u7684\u3002\u591A\u804A\u51E0\u8F6E\u540E\uFF0C\u503C\u5F97\u4FDD\u5B58\u7684\u5185\u5BB9\u4F1A\u81EA\u52A8\u6C89\u6DC0\u6210\u77E5\u8BC6\u5361\u3002",open:"\u9605\u8BFB",updated:"\u66F4\u65B0\u4E8E",created:"\u521B\u5EFA\u4E8E",source:"\u6765\u6E90",close:"\u5173\u95ED",vaultDir:"\u8BB0\u5FC6\u5E93\u76EE\u5F55",capture:"\u81EA\u52A8\u6C89\u6DC0",recall:"\u81EA\u52A8\u53EC\u56DE",enabled:"\u5DF2\u542F\u7528",disabled:"\u5DF2\u7981\u7528",error:"\u52A0\u8F7D\u5931\u8D25",back:"\u8FD4\u56DE\u5217\u8868",cardCount:"\u5F20\u5361",nodes:"\u8282\u70B9",edges:"\u8FDE\u7EBF"},_={nav:"Memory",loading:"Loading\u2026",refresh:"Refresh",overview:"Memory Overview",total:"Cards",recent:"Added (7d)",tags:"Tags",searchPlaceholder:"Search memory\u2026",search:"Search",all:"All",kindProject:"Projects",kindKnowledge:"Knowledge",kindContent:"Content",kindPrompt:"Prompts",kindBusiness:"Business",graph:"Knowledge Graph",graphHint:"Nodes = cards; edges = [[links]] or shared tags. Click a node to read.",empty:"Memory is empty. After a few conversations, valuable content is auto-captured.",open:"Read",updated:"Updated",created:"Created",source:"Source",close:"Close",vaultDir:"Vault directory",capture:"Auto capture",recall:"Auto recall",enabled:"on",disabled:"off",error:"Load failed",back:"Back to list",cardCount:"cards",nodes:"nodes",edges:"edges"},V=["all","project","knowledge","content","prompt","business"],x={project:"#3b82f6",knowledge:"#22c55e",content:"#f43f5e",prompt:"#06b6d4",business:"#eab308",other:"#8b5cf6"},Z=`
+.memory-eternal-root { font-family: inherit; color: var(--dsh-color-text, #1f2937); }
+.memory-eternal-root .mc-card { background: var(--dsh-color-surface, #ffffff); border: 1px solid var(--dsh-color-border, #e5e7eb); border-radius: 12px; padding: 14px 16px; }
+.memory-eternal-stats { display: grid; grid-template-columns: repeat(auto-fit, minmax(110px, 1fr)); gap: 10px; margin-bottom: 14px; }
+.memory-eternal-stat { text-align: center; }
+.memory-eternal-stat b { display: block; font-size: 22px; line-height: 1.2; }
+.memory-eternal-stat span { font-size: 12px; opacity: 0.65; }
+.memory-eternal-toolbar { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; margin-bottom: 12px; }
+.memory-eternal-toolbar input[type=text] { flex: 1; min-width: 180px; padding: 7px 10px; border-radius: 8px; border: 1px solid var(--dsh-color-border, #d1d5db); background: var(--dsh-color-input, #f9fafb); color: inherit; font-size: 13px; }
+.memory-eternal-chips { display: flex; gap: 6px; flex-wrap: wrap; margin-bottom: 12px; }
+.memory-eternal-chip { border: 1px solid var(--dsh-color-border, #d1d5db); background: transparent; color: inherit; border-radius: 999px; padding: 4px 12px; font-size: 12px; cursor: pointer; opacity: 0.7; }
+.memory-eternal-chip.active { opacity: 1; font-weight: 600; border-color: currentColor; }
+.memory-eternal-btn { border: 1px solid var(--dsh-color-border, #d1d5db); background: transparent; color: inherit; border-radius: 8px; padding: 6px 12px; font-size: 12px; cursor: pointer; }
+.memory-eternal-btn:hover { opacity: 0.85; }
+.memory-eternal-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(230px, 1fr)); gap: 10px; }
+.memory-eternal-card { cursor: pointer; transition: border-color 0.15s; display: flex; flex-direction: column; gap: 6px; min-height: 110px; }
+.memory-eternal-card:hover { border-color: var(--dsh-color-accent, #6366f1); }
+.memory-eternal-card h4 { margin: 0; font-size: 14px; line-height: 1.35; }
+.memory-eternal-card p { margin: 0; font-size: 12px; opacity: 0.7; line-height: 1.5; display: -webkit-box; -webkit-line-clamp: 3; -webkit-box-orient: vertical; overflow: hidden; }
+.memory-eternal-card footer { margin-top: auto; display: flex; justify-content: space-between; align-items: center; font-size: 11px; opacity: 0.55; }
+.memory-eternal-tags { display: flex; gap: 4px; flex-wrap: wrap; }
+.memory-eternal-tag { font-size: 10px; padding: 1px 7px; border-radius: 999px; background: var(--dsh-color-border, #e5e7eb); opacity: 0.85; }
+.memory-eternal-kind { width: 8px; height: 8px; border-radius: 50%; display: inline-block; margin-right: 6px; }
+.memory-eternal-empty { text-align: center; padding: 40px 10px; opacity: 0.6; font-size: 13px; }
+.memory-eternal-overlay { position: fixed; inset: 0; background: rgba(0,0,0,0.45); z-index: 999; display: flex; align-items: center; justify-content: center; padding: 24px; }
+.memory-eternal-dialog { background: var(--dsh-color-surface, #fff); color: var(--dsh-color-text, #111); border-radius: 14px; max-width: 720px; width: 100%; max-height: 84vh; display: flex; flex-direction: column; box-shadow: 0 24px 60px rgba(0,0,0,0.3); }
+.memory-eternal-dialog-head { display: flex; justify-content: space-between; align-items: center; padding: 12px 18px; border-bottom: 1px solid var(--dsh-color-border, #e5e7eb); }
+.memory-eternal-dialog-head h3 { margin: 0; font-size: 15px; }
+.memory-eternal-dialog-body { padding: 14px 18px; overflow: auto; font-size: 13px; line-height: 1.7; white-space: pre-wrap; word-break: break-word; }
+.memory-eternal-graph-wrap { width: 100%; height: 420px; position: relative; }
+.memory-eternal-graph-wrap svg { width: 100%; height: 100%; }
+.memory-eternal-graph-line { stroke: var(--dsh-color-border, #d1d5db); stroke-width: 1; opacity: 0.6; }
+.memory-eternal-graph-node { cursor: pointer; }
+.memory-eternal-graph-node:hover circle { stroke: var(--dsh-color-accent, #6366f1); stroke-width: 2; }
+.memory-eternal-graph-label { font-size: 11px; fill: var(--dsh-color-text, #333); pointer-events: none; }
+.memory-eternal-graph-legend { display: flex; gap: 10px; flex-wrap: wrap; padding: 8px 2px 0; font-size: 11px; opacity: 0.8; }
+.memory-eternal-flag { font-size: 11px; padding: 2px 8px; border-radius: 999px; border: 1px solid var(--dsh-color-border, #d1d5db); margin-left: 6px; }
+`;function F(e){e.effect(()=>e.locale.register(w,{zh:U,en:_}),"memory-eternal: locale");let r=e.locale.bind(w);e.effect(()=>e.slots.inject("settings.section",()=>e.slots.register({name:"settings.section",id:w,order:25,label:()=>r("nav"),locale:w,inject:()=>({})},()=>t.default.createElement(J,{t:r,scope:e.settingsScope.bind({namespace:w})}))),"memory-eternal: settings section")}function J({t:e}){let[r,l]=(0,t.useState)(null),[n,d]=(0,t.useState)([]),[h,f]=(0,t.useState)(!0),[y,i]=(0,t.useState)(""),[u,z]=(0,t.useState)("all"),[p,N]=(0,t.useState)(""),[b,C]=(0,t.useState)(null),[o,c]=(0,t.useState)(!1),s=(0,t.useRef)(null),k=(0,t.useCallback)(async(a=u,g=p)=>{try{f(!0),i("");let m=new URLSearchParams;a&&a!=="all"&&m.set("kind",a),g.trim()&&m.set("q",g.trim());let M=await(await fetch(`${E}/cards?${m.toString()}`)).json();M.ok&&d(M.cards||[])}catch(m){i(String(m&&m.message?m.message:m))}finally{f(!1)}},[u,p]),v=(0,t.useCallback)(async()=>{try{let[a,g]=await Promise.all([fetch(`${E}/overview`).then(m=>m.json()),fetch(`${E}/cards`).then(m=>m.json())]);a.ok&&l(a),g.ok&&d(g.cards||[])}catch(a){i(String(a&&a.message?a.message:a))}finally{f(!1)}},[]);(0,t.useEffect)(()=>(v(),()=>{s.current&&clearTimeout(s.current)}),[v]);let D=a=>{N(a),s.current&&clearTimeout(s.current),s.current=setTimeout(()=>k(u,a),280)},$=a=>{z(a),k(a,p)},K=async a=>{try{let m=await(await fetch(`${E}/card?path=${encodeURIComponent(a.path)}`)).json();m.ok&&C({path:a.path,title:a.title,text:m.text})}catch(g){i(String(g&&g.message?g.message:g))}},ae=a=>e(P(a));return t.default.createElement("div",{className:"memory-eternal-root mc-card"},t.default.createElement("style",{key:"mc-css"},Z),t.default.createElement("div",{className:"memory-eternal-stats"},j(e("total"),r?r.total:"\u2014"),j(e("recent"),r?r.recent:"\u2014"),j(e("tags"),r?r.tags:"\u2014"),j(e("cardCount"),r?r.byKind?.knowledge??0:"\u2014")),t.default.createElement("div",{className:"memory-eternal-toolbar"},t.default.createElement("input",{type:"text",placeholder:e("searchPlaceholder"),value:p,onChange:a=>D(a.target.value)}),t.default.createElement("button",{className:"memory-eternal-btn",onClick:()=>v()},e("refresh")),t.default.createElement("button",{className:"memory-eternal-btn",onClick:()=>c(!0)},e("graph"))),t.default.createElement("div",{className:"memory-eternal-chips"},V.map(a=>t.default.createElement("button",{key:a,className:`memory-eternal-chip${u===a?" active":""}`,onClick:()=>$(a)},e(a==="all"?"all":P(a))))),y&&t.default.createElement("div",{className:"memory-eternal-empty"},`${e("error")}\uFF1A${y}`),h&&!n.length?t.default.createElement("div",{className:"memory-eternal-empty"},e("loading")):n.length===0?t.default.createElement("div",{className:"memory-eternal-empty"},e("empty")):t.default.createElement("div",{className:"memory-eternal-grid"},n.map(a=>Q(a,e,K))),b&&t.default.createElement(W,{t:e,card:b,onClose:()=>C(null)}),o&&t.default.createElement(X,{t:e,onClose:()=>c(!1),onOpen:K}))}var j=(e,r)=>t.default.createElement("div",{className:"memory-eternal-stat mc-card"},t.default.createElement("b",null,r),t.default.createElement("span",null,e)),Q=(e,r,l)=>t.default.createElement("article",{key:e.path,className:"memory-eternal-card mc-card",onClick:()=>l(e)},t.default.createElement("h4",null,t.default.createElement("span",{className:"memory-eternal-kind",style:{background:x[e.kind]||x.other}}),e.title),t.default.createElement("p",null,e.summary||""),e.tags.length>0&&t.default.createElement("div",{className:"memory-eternal-tags"},e.tags.slice(0,4).map(n=>t.default.createElement("span",{key:n,className:"memory-eternal-tag"},n))),t.default.createElement("footer",null,t.default.createElement("span",null,r(P(e.kind))),t.default.createElement("span",null,te(e.updated))));function W({t:e,card:r,onClose:l}){return t.default.createElement("div",{className:"memory-eternal-overlay",onClick:l},t.default.createElement("div",{className:"memory-eternal-dialog",onClick:n=>n.stopPropagation()},t.default.createElement("div",{className:"memory-eternal-dialog-head"},t.default.createElement("h3",null,r.title),t.default.createElement("button",{className:"memory-eternal-btn",onClick:l},e("close"))),t.default.createElement("div",{className:"memory-eternal-dialog-body"},r.text)))}function X({t:e,onClose:r,onOpen:l}){let[n,d]=(0,t.useState)(null),[h,f]=(0,t.useState)("");return(0,t.useEffect)(()=>{let y=!0;return fetch(`${E}/graph`).then(i=>i.json()).then(i=>{y&&d(i.ok?i:null)}).catch(i=>{y&&f(String(i&&i.message?i.message:i))}),()=>{y=!1}},[]),t.default.createElement("div",{className:"memory-eternal-overlay",onClick:r},t.default.createElement("div",{className:"memory-eternal-dialog",onClick:y=>y.stopPropagation()},t.default.createElement("div",{className:"memory-eternal-dialog-head"},t.default.createElement("h3",null,`${e("graph")}\uFF08${n?n.nodes.length:0} ${e("nodes")} \xB7 ${n?Y(n.edges):0} ${e("edges")}\uFF09`),t.default.createElement("button",{className:"memory-eternal-btn",onClick:r},e("close"))),t.default.createElement("div",{className:"memory-eternal-dialog-body"},h&&t.default.createElement("div",{className:"memory-eternal-empty"},`${e("error")}\uFF1A${h}`),!n&&!h&&t.default.createElement("div",{className:"memory-eternal-empty"},e("loading")),n&&n.nodes.length===0&&t.default.createElement("div",{className:"memory-eternal-empty"},e("empty")),n&&n.nodes.length>0&&t.default.createElement(ee,{nodes:n.nodes,edges:n.edges,onOpen:l,t:e}))))}function Y(e){let r=new Set;for(let l of e||[])r.add([l.source,l.target].sort().join("|"));return r.size}function ee({nodes:e,edges:r,onOpen:l,t:n}){let i=Math.min(660,380)/2-46,u={};e.forEach((o,c)=>{(u[o.kind]=u[o.kind]||[]).push(c)});let z=Object.keys(u),p=new Array(e.length),N=-Math.PI/2;for(let o of z){let c=u[o],s=c.length/e.length*Math.PI*2,k=N;c.forEach((v,D)=>{let $=c.length===1?k+s/2:k+s*(D+.5)/c.length;p[v]={x:330+i*Math.cos($),y:190+i*Math.sin($)}}),N+=s}let b=new Set,C=(r||[]).filter(o=>{let c=[o.source,o.target].sort().join("|");return b.has(c)?!1:(b.add(c),!0)});return t.default.createElement("div",null,t.default.createElement("div",{className:"memory-eternal-graph-wrap"},t.default.createElement("svg",{viewBox:"0 0 660 380",role:"img"},C.map((o,c)=>t.default.createElement("line",{key:`e${c}`,className:"memory-eternal-graph-line",x1:p[e.findIndex(s=>s.id===o.source)]?.x,y1:p[e.findIndex(s=>s.id===o.source)]?.y,x2:p[e.findIndex(s=>s.id===o.target)]?.x,y2:p[e.findIndex(s=>s.id===o.target)]?.y})),e.map((o,c)=>{let s=p[c];return s?t.default.createElement("g",{key:o.id,className:"memory-eternal-graph-node",transform:`translate(${s.x} ${s.y})`,onClick:()=>l({path:o.id,title:o.title})},t.default.createElement("circle",{r:o.kind==="project"?9:7,fill:x[o.kind]||x.other}),t.default.createElement("text",{className:"memory-eternal-graph-label",x:12,y:3},String(o.title||"").slice(0,14))):null}))),t.default.createElement("div",{className:"memory-eternal-graph-legend"},Object.keys(x).map(o=>t.default.createElement("span",{key:o},t.default.createElement("span",{className:"memory-eternal-kind",style:{background:x[o]}}),n(P(o)))),t.default.createElement("span",{style:{opacity:.6,marginLeft:6}},n("graphHint"))))}var P=e=>({project:"kindProject",knowledge:"kindKnowledge",content:"kindContent",prompt:"kindPrompt",business:"kindBusiness",other:"kindKnowledge"})[e]||"kindKnowledge";function te(e){if(!e)return"";let r=new Date(e);if(Number.isNaN(r.getTime()))return"";let l=new Date,n=r.toDateString()===l.toDateString(),d=f=>String(f).padStart(2,"0"),h=`${d(r.getHours())}:${d(r.getMinutes())}`;return n?h:`${r.getMonth()+1}-${r.getDate()} ${h}`}
+
+    return module.exports;
+  },
+});