dsh-foxy-memory 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kun-Fox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# dsh-foxy-memory
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`dsh-foxy-memory` 是 [`dsh-foxy`](../dsh-foxy) 的可选记忆子插件。它把 Foxy 会话写成本地 JSONL，并在下一轮把最近记忆注入 Foxy 的 persona。
+
+它不依赖 ChatLuna/LivingMemory；这样任何人都可以只装 `dsh-foxy` + `dsh-foxy-memory` 就得到能记住对话的 Foxy。
+
+## 记录格式
+
+默认文件：
+
+```text
+%USERPROFILE%\.dsh\foxy\memory\entries.jsonl
+```
+
+每条记录：
+
+```json
+{
+  "id": "uuid",
+  "presetId": "foxy3",
+  "sessionId": "session-id",
+  "platform": "dsh",
+  "sourceLabel": "DSH",
+  "speaker": "kunfox",
+  "role": "user",
+  "type": "conversation",
+  "status": "active",
+  "content": "今天在 DSH 做了……",
+  "keywords": [],
+  "summary": "",
+  "importance": 0.5,
+  "createdAt": 1790000000000,
+  "updatedAt": 1790000000000
+}
+```
+
+注入时会格式化成：
+
+```text
+- [2026-11-06 20:00] [DSH] kunfox: 今天在 DSH 做了……
+- [2026-11-06 20:00] [DSH] Foxy: 记住啦。
+```
+
+`platform` 统一小写（`dsh`），显示时用 `sourceLabel`（如 `DSH`）；`presetId` 允许 Foxy 主预设和 Character 预设分开存档。
+
+## 配置
+
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| `dataDir` | `$DSH_HOME/foxy/memory` | 数据目录 |
+| `entriesFile` | `entries.jsonl` | 文件名 |
+| `maxEntries` | `5000` | 超过后丢弃最旧记录 |
+| `maxContentChars` | `4000` | 单条内容截断 |
+| `maxContextEntries` | `20` | 最多注入条数 |
+| `maxContextChars` | `6000` | 注入内容总字符上限 |
+| `userLabel` | `kunfox` | 用户显示名 |
+| `assistantLabel` | `Foxy` | 助手显示名 |
+| `provider` | `livingmemory`（配置 bridgeUrl 时）/ `local` | 记忆写到哪个 provider |
+| `bridgeUrl` | 空 | Koishi 桥地址，如 `http://127.0.0.1:5140/foxy-memory` |
+| `bridgeToken` | 空 | 与桥的 `token` 一致；公网部署必须设置 |
+| `bridgePresetId` | `foxy3（Character）` | 写入 LivingMemory 的 preset |
+| `bridgeTimeoutMs` | `15000` | 桥请求超时 |
+| `batchSize` | `8` | 累积多少条消息后调用 `/ingest` |
+| `flushIntervalMs` | `30000` | 未满一批时的定时冲刷间隔 |
+| `extractModel` | `deepseek/deepseek-flash` | 桥提取记忆使用的模型 |
+
+DSH 侧不再逐条写记忆：`record` 只把消息放进 pending，满 `batchSize` 或到 `flushIntervalMs` 时调用桥的 `/ingest`，由模型提炼成中文第一人称记忆。`stats()` 会显示 `pending`。
+
+Foxy 面板的「记忆桥设置」可以修改这些值，保存到 `$DSH_HOME/foxy/settings.json`；插件启动时读取，保存后尝试热重载。`/api/dsh-foxy/settings` 在 DSH host 内提供。
+
+## 服务
+
+加载后提供：
+
+```js
+ctx.foxyMemory.record({ role, text, presetId, sessionId, platform, speaker })
+ctx.foxyMemory.context({ presetId, limit })
+ctx.foxyMemory.list({ presetId, status, limit })
+ctx.foxyMemory.search(query, { presetId })
+ctx.foxyMemory.archive(id)
+ctx.foxyMemory.stats()
+```
+
+同时通过 `ctx.foxy.registerMemoryProvider('local', ...)` 和（配置了桥时）`registerMemoryProvider('livingmemory', ...)` 注册到 Foxy 的 provider 注册表。
+
+## 与 LivingMemory 的关系
+
+本地 JSONL 是默认实现，不是 `chatluna-livingmemory` 的替代品，也不直接写它的 `koishi.db`/PGlite 索引。
+
+如果要把 DSH 记忆写回 QQ 侧的 `foxy3（Character）` 池，安装并配置 [`koishi-plugin-foxy-memory-bridge`](../koishi-plugin-foxy-memory-bridge)：
+
+```yaml
+# DSH 侧 dsh-foxy-memory 配置
+provider: livingmemory
+bridgeUrl: http://127.0.0.1:5140/foxy-memory
+bridgeToken: 与桥一致的随机串
+bridgePresetId: foxy3（Character）
+```
+
+DSH 侧只向桥发送 `record`/`context` 请求；桥内调用：
+
+```js
+ctx.chatluna_living_memory.createMemory(scope, input, speakerKeys)
+```
+
+不要直接 INSERT SQLite，否则会绕过 speaker key、profile 和向量索引。桥不可用时会自动回退本地 JSONL，不会丢消息。
+
+## 安装
+
+```powershell
+dsh plugin --profile desktop add "file:D:\path\to\dsh-foxy-memory"
+```
+
+需要同时安装 `dsh-foxy`；重启 DSH 后，Foxy 会话会使用当前 provider。默认是本地 JSONL；配置 `bridgeUrl` 后默认切到 LivingMemory 桥（也可显式 `provider: local` 保持本地）。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-foxy-memory
+      name: dsh-foxy-memory

package/lib/index.js

@@ -0,0 +1,395 @@
+import { randomUUID } from 'node:crypto'
+import { appendFile, mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+export const name = 'dsh-foxy-memory'
+export const inject = ['foxy']
+
+function resolveDataDir(config) {
+  if (typeof config.dataDir === 'string' && config.dataDir.trim()) return config.dataDir.trim()
+  const home = process.env.DSH_HOME || join(homedir(), '.dsh')
+  return join(home, 'foxy', 'memory')
+}
+
+function clip(text, max) {
+  const value = String(text || '').trim()
+  return value.length > max ? `${value.slice(0, max)}…` : value
+}
+
+function roleSpeaker(entry, config) {
+  const speaker = String(entry.speaker || '').trim()
+  if (speaker && speaker !== 'user' && speaker !== 'assistant') return speaker
+  if (entry.role === 'assistant') return config.assistantLabel || 'Foxy'
+  return config.userLabel || 'kunfox'
+}
+
+function normalizePlatform(value) {
+  const platform = String(value || 'dsh').trim().toLowerCase()
+  return platform || 'dsh'
+}
+
+function formatEntry(entry, config) {
+  const date = new Date(entry.createdAt).toISOString().slice(0, 16).replace('T', ' ')
+  const platform = entry.sourceLabel || (entry.platform === 'dsh' ? 'DSH' : entry.platform) || 'DSH'
+  return `- [${date}] [${platform} 平台] ${roleSpeaker(entry, config)}: ${entry.content}`
+}
+
+export function apply(ctx, config = {}) {
+  try {
+    const settingsFile = join(process.env.DSH_HOME || join(homedir(), '.dsh'), 'foxy', 'settings.json')
+    const saved = JSON.parse(readFileSync(settingsFile, 'utf8'))
+    for (const key of ['provider', 'bridgeUrl', 'bridgeToken', 'bridgePresetId', 'batchSize', 'flushIntervalMs', 'extractModel']) {
+      if (saved[key] !== undefined) config[key] = saved[key]
+    }
+  } catch {}
+  config = {
+    ...config,
+    userLabel: config.userLabel || 'kunfox',
+    assistantLabel: config.assistantLabel || 'Foxy',
+  }
+  const dataDir = resolveDataDir(config)
+  const entriesFile = join(dataDir, config.entriesFile || 'entries.jsonl')
+  const maxEntries = Math.max(1, Number(config.maxEntries) || 5000)
+  const maxContentChars = Math.max(200, Number(config.maxContentChars) || 4000)
+  const maxContextEntries = Math.max(1, Number(config.maxContextEntries) || 20)
+  const maxContextChars = Math.max(500, Number(config.maxContextChars) || 6000)
+
+  const entries = new Map()
+  let ready = null
+
+  async function rewrite() {
+    const temp = `${entriesFile}.tmp`
+    const body = [...entries.values()].map((entry) => JSON.stringify(entry)).join('\n')
+    await writeFile(temp, body ? `${body}\n` : '', 'utf8')
+    await rename(temp, entriesFile)
+  }
+
+  function normalize(entry) {
+    if (!entry || !entry.id || !entry.content) return null
+    entry.type ||= 'conversation'
+    entry.status ||= 'active'
+    entry.platform = normalizePlatform(entry.platform)
+    entry.sourceLabel ||= entry.platform === 'dsh' ? 'DSH' : entry.platform
+    entry.keywords = Array.isArray(entry.keywords) ? entry.keywords : []
+    entry.summary ||= ''
+    entry.importance = Number(entry.importance) || 0.5
+    entry.createdAt = Number(entry.createdAt) || Date.now()
+    entry.updatedAt = Number(entry.updatedAt) || entry.createdAt
+    if (!entry.speaker) entry.speaker = entry.role === 'assistant' ? config.assistantLabel || 'Foxy' : config.userLabel || 'kunfox'
+    return entry
+  }
+
+  async function init() {
+    await mkdir(dataDir, { recursive: true })
+    try {
+      const text = await readFile(entriesFile, 'utf8')
+      for (const line of text.split(/\r?\n/)) {
+        if (!line.trim()) continue
+        try {
+          const entry = normalize(JSON.parse(line))
+          if (entry) entries.set(entry.id, entry)
+        } catch {
+          // Skip a damaged line rather than losing the whole archive.
+        }
+      }
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error
+    }
+  }
+
+  ready = init().catch((error) => {
+    ctx.logger?.warn?.(`[dsh-foxy-memory] failed to load ${entriesFile}: ${error instanceof Error ? error.message : String(error)}`)
+  })
+
+  async function record(input = {}) {
+    await ready
+    const role = input.role === 'assistant' ? 'assistant' : input.role === 'user' ? 'user' : ''
+    if (!role) throw new TypeError('memory role must be user or assistant')
+    const content = clip(input.text, maxContentChars)
+    if (!content) return null
+
+    const presetId = String(input.presetId || 'foxy3')
+    const sessionId = String(input.sessionId || '')
+    const platform = normalizePlatform(input.platform || input.sourceLabel)
+    const sourceLabel = input.sourceLabel || (platform === 'dsh' ? 'DSH' : platform)
+    const speaker = String(
+      input.speaker || (role === 'assistant' ? config.assistantLabel || 'Foxy' : config.userLabel || 'kunfox'),
+    )
+    const last = [...entries.values()].at(-1)
+    if (
+      last &&
+      last.role === role &&
+      last.presetId === presetId &&
+      last.sessionId === sessionId &&
+      last.platform === platform &&
+      last.content === content &&
+      Math.abs(Number(input.at || Date.now()) - last.createdAt) < 1000
+    ) {
+      return last
+    }
+
+    const now = Number(input.at) || Date.now()
+    const entry = normalize({
+      id: randomUUID(),
+      presetId,
+      sessionId,
+      platform,
+      sourceLabel,
+      speaker,
+      role,
+      type: 'conversation',
+      status: 'active',
+      content,
+      keywords: Array.isArray(input.keywords) ? input.keywords : [],
+      summary: '',
+      importance: role === 'assistant' ? 0.4 : 0.5,
+      createdAt: now,
+      updatedAt: now,
+    })
+    entries.set(entry.id, entry)
+    await appendFile(entriesFile, `${JSON.stringify(entry)}\n`, 'utf8')
+
+    let trimmed = false
+    while (entries.size > maxEntries) {
+      const oldest = entries.keys().next().value
+      if (oldest === undefined) break
+      entries.delete(oldest)
+      trimmed = true
+    }
+    if (trimmed) await rewrite()
+    return entry
+  }
+
+  async function context(input = {}) {
+    await ready
+    const presetId = String(input.presetId || 'foxy3')
+    const limit = Math.min(maxContextEntries, Math.max(1, Number(input.limit) || maxContextEntries))
+    const picked = [...entries.values()]
+      .filter((entry) => entry.presetId === presetId && entry.status === 'active')
+      .slice(-limit)
+    if (!picked.length) return ''
+
+    const lines = []
+    let size = 0
+    for (const entry of picked.reverse()) {
+      const line = formatEntry(entry, config)
+      if (size + line.length > maxContextChars) break
+      lines.push(line)
+      size += line.length + 1
+    }
+    return lines.reverse().join('\n')
+  }
+
+  async function list(input = {}) {
+    await ready
+    const presetId = input.presetId === undefined ? undefined : String(input.presetId)
+    const status = input.status === undefined ? 'active' : String(input.status)
+    const limit = Math.min(500, Math.max(1, Number(input.limit) || 50))
+    return [...entries.values()]
+      .filter((entry) => (presetId === undefined || entry.presetId === presetId) && (status === '*' || entry.status === status))
+      .slice(-limit)
+  }
+
+  async function search(query, input = {}) {
+    await ready
+    const needle = String(query || '').trim().toLowerCase()
+    if (!needle) return []
+    const presetId = input.presetId === undefined ? undefined : String(input.presetId)
+    const limit = Math.min(200, Math.max(1, Number(input.limit) || 20))
+    return [...entries.values()]
+      .filter((entry) => entry.status === 'active')
+      .filter((entry) => presetId === undefined || entry.presetId === presetId)
+      .filter((entry) =>
+        `${entry.content}\n${entry.keywords.join(' ')}\n${entry.platform}\n${entry.speaker}`.toLowerCase().includes(needle),
+      )
+      .slice(-limit)
+      .reverse()
+  }
+
+  async function archive(id) {
+    await ready
+    const entry = entries.get(String(id))
+    if (!entry) return null
+    entry.status = 'archived'
+    entry.updatedAt = Date.now()
+    await rewrite()
+    return entry
+  }
+
+  function stats() {
+    const byPreset = {}
+    const byPlatform = {}
+    for (const entry of entries.values()) {
+      byPreset[entry.presetId] ??= { active: 0, archived: 0 }
+      byPreset[entry.presetId][entry.status === 'archived' ? 'archived' : 'active'] += 1
+      byPlatform[entry.platform] ??= { active: 0, archived: 0 }
+      byPlatform[entry.platform][entry.status === 'archived' ? 'archived' : 'active'] += 1
+    }
+    return { dataDir, entriesFile, total: entries.size, byPreset, byPlatform }
+  }
+
+  const provider = Object.freeze({
+    name: 'local',
+    version: 1,
+    record,
+    context,
+    list,
+    search,
+    archive,
+    stats,
+  })
+
+  const bridgeUrl = String(config.bridgeUrl || '').trim().replace(/\/+$/, '')
+  const bridgeToken = String(config.bridgeToken || '').trim()
+  const bridgePresetId = String(config.bridgePresetId || config.presetId || 'foxy3（Character）')
+  const bridgeTimeoutMs = Math.max(1000, Number(config.bridgeTimeoutMs) || 15000)
+
+  const batchSize = Math.max(1, Number(config.batchSize) || 8)
+  const flushIntervalMs = Math.max(1000, Number(config.flushIntervalMs) || 30000)
+  const pendingBySession = new Map()
+  let flushTimer
+
+  function pendingFor(sessionId) {
+    const key = String(sessionId || 'default')
+    if (!pendingBySession.has(key)) pendingBySession.set(key, [])
+    return pendingBySession.get(key)
+  }
+
+  async function flushSession(sessionId) {
+    const key = String(sessionId || 'default')
+    const messages = pendingBySession.get(key)
+    if (!messages?.length) return { created: 0 }
+    try {
+      const first = messages[0] || {}
+      const result = await bridgePost('/ingest', {
+        presetId: bridgePresetId,
+        sessionId: key,
+        scene: first.scene || 'dsh',
+        platform: first.platform || 'dsh',
+        channelType: first.channelType || 'private',
+        channelId: first.channelId || key,
+        eventType: first.eventType || 'conversation',
+        sourceLabel: first.sourceLabel || 'DSH',
+        messages,
+      })
+      pendingBySession.delete(key)
+      ctx.logger?.info?.(`[dsh-foxy-memory] flushed ${messages.length} messages -> ${result.created || 0} memories`)
+      return result
+    } catch (error) {
+      ctx.logger?.warn?.(`[dsh-foxy-memory] ingest failed; keeping ${messages.length} pending: ${error instanceof Error ? error.message : String(error)}`)
+      if (messages.length > 200) messages.splice(0, messages.length - 200)
+      return { created: 0, pending: messages.length }
+    }
+  }
+
+  async function flushAll() {
+    for (const key of [...pendingBySession.keys()]) await flushSession(key)
+  }
+
+  async function bridgePost(path, body = {}) {
+    if (!bridgeUrl) throw new Error('foxy-memory bridgeUrl is not configured')
+    const url = new URL(`${bridgeUrl}${path}`)
+    for (const [key, value] of Object.entries(body)) {
+      if (value === undefined || value === null) continue
+      if (typeof value === 'object') continue
+      if (String(value).trim()) url.searchParams.set(key, String(value))
+    }
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        ...(bridgeToken ? { authorization: `Bearer ${bridgeToken}` } : {}),
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(bridgeTimeoutMs),
+    })
+    const data = await response.json().catch(() => ({}))
+    if (!response.ok || data?.ok === false) {
+      throw new Error(data?.error || `bridge HTTP ${response.status}`)
+    }
+    return data
+  }
+
+  const bridgeProvider = bridgeUrl
+    ? Object.freeze({
+        name: 'livingmemory',
+        version: 1,
+        async record(input = {}) {
+          const sessionId = String(input.sessionId || 'default')
+          const messages = pendingFor(sessionId)
+          messages.push({
+            role: input.role,
+            text: input.text,
+            at: input.at || Date.now(),
+            scene: input.scene || 'dsh',
+            platform: input.platform || 'dsh',
+            sourceLabel: input.sourceLabel || 'DSH',
+            eventType: input.eventType || 'conversation',
+            channelType: input.channelType || 'private',
+            channelId: input.channelId || sessionId,
+            title: input.title || '',
+            url: input.url || '',
+          })
+          if (messages.length >= batchSize) await flushSession(sessionId)
+          return {
+            id: `pending:${sessionId}`,
+            presetId: bridgePresetId,
+            platform: input.platform || 'dsh',
+            sourceLabel: input.sourceLabel || 'DSH',
+            role: input.role,
+            content: input.text,
+            createdAt: Number(new Date(input.at)) || Date.now(),
+            pending: messages.length,
+          }
+        },
+        async context(input = {}) {
+          try {
+            const result = await bridgePost('/context', {
+              presetId: bridgePresetId,
+              sessionId: input.sessionId,
+              query: input.query || 'DSH',
+              limit: input.limit,
+            })
+            if (result.text) return result.text
+          } catch (error) {
+            ctx.logger?.warn?.(`[dsh-foxy-memory] bridge context failed, falling back to local: ${error instanceof Error ? error.message : String(error)}`)
+          }
+          return context(input)
+        },
+        list,
+        search,
+        archive,
+        stats() {
+          const pending = [...pendingBySession.values()].reduce((sum, list) => sum + list.length, 0)
+          return { ...stats(), provider: 'livingmemory', bridgeUrl, bridgePresetId, pending }
+        },
+      })
+    : null
+
+  const requested = String(config.provider || (bridgeProvider ? 'livingmemory' : 'local'))
+  const active = requested === 'livingmemory' && bridgeProvider ? bridgeProvider : provider
+
+  const disposeLocal = ctx.foxy.registerMemoryProvider('local', async () => provider)
+  const disposeBridge = bridgeProvider
+    ? ctx.foxy.registerMemoryProvider('livingmemory', async () => bridgeProvider)
+    : null
+  flushTimer = setInterval(() => { void flushAll() }, flushIntervalMs)
+  flushTimer.unref?.()
+
+  if (typeof ctx.provide === 'function') ctx.provide('foxyMemory', active)
+  ctx.logger?.info?.(`[dsh-foxy-memory] ready; provider=${active.name}; file=${entriesFile}${bridgeUrl ? `; bridge=${bridgeUrl}` : ''}`)
+
+  return {
+    provider: active,
+    dispose: () => {
+      clearInterval(flushTimer)
+      void flushAll()
+      disposeLocal()
+      disposeBridge?.()
+    },
+    reload: async () => { entries.clear(); await init() },
+  }
+}
+

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "dsh-foxy-memory",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Memory subplugin for dsh-foxy: local JSONL archive plus optional ChatLuna LivingMemory bridge, recall and search.",
+  "type": "module",
+  "main": "lib/index.js",
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "author": "Kun-Fox",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Kun-Fox/dsh-foxy-memory.git"
+  },
+  "homepage": "https://github.com/Kun-Fox/dsh-foxy-memory#readme",
+  "bugs": {
+    "url": "https://github.com/Kun-Fox/dsh-foxy-memory/issues"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "foxy",
+    "memory",
+    "livingmemory"
+  ],
+  "license": "MIT"
+}
+
+
+
+
+
+
+
+