@lotuseslunarland/dsh-lotuses-memory 0.0.0-stage → 0.1.3

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# Lotuses'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.
+跨会话长期记忆插件，给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）用。
+
+对话型 agent 通常"每个群/每个线程一个 session"，换个地方就忘了之前认识谁。
+这个插件把"认识的人、待过的群、发生过的事"存成普通 Markdown 档案，**每轮请求自动注入**，
+并提供两个工具让模型自己读写。
+
+## 特性
+
+- **档案是普通文件**：`<memoryDir>/people/<QQ>.md`、`<memoryDir>/groups/<群号>.md`，随时能手工编辑
+- **自动注入**：走 `systemPrompt.context`，不污染用户消息正文；按「当前发言人 + 当前群」挑档案
+- **工具**：`memory_note`（记一条）、`memory_recall`（翻全文）
+- **自动压缩**：档案超过 4000 字符时把旧记录折叠成一行计数，保留最近 40 条
+- **通道无关**：聊天对象从会话 ID 解析（`<prefix>-<kind>-<id>`），发言人以消息前缀里的 `(QQ)` 识别；
+  解析不到时只注入群档案（或退回上一轮记住的发言人）
+
+## 安装
+
+```bash
+# 从 npm
+dsh plugin --profile web add @lotuseslunarland/dsh-lotuses-memory
+
+# 或从本地目录 / tgz
+cd ~/.dsh/profiles/web
+pnpm add file:/path/to/Lotuses_Memory
+```
+
+然后在 profile 的 `cordis.patch.yml` 里**用 insert 块**启用（新插件不能用顶层 `- id:`）：
+
+```yaml
+- insert:
+    - id: lotuses-memory
+      name: '@lotuseslunarland/dsh-lotuses-memory'
+      config:
+        memoryDir: '/path/to/Memory'
+        sessionsDir: '/root/.dsh/sessions'   # 可选，默认 <DSH_HOME>/sessions
+        maxPersonChars: 900
+        maxGroupChars: 600
+```
+
+## 配置
+
+| 键 | 默认 | 说明 |
+| --- | --- | --- |
+| `memoryDir` | `<cwd>/Memory` | 记忆库目录 |
+| `sessionsDir` | `<DSH_HOME>/sessions` | 会话文件根目录（用于识别发言人） |
+| `maxPersonChars` | `900` | 单个人物档案注入上限 |
+| `maxGroupChars` | `600` | 单个群档案注入上限 |
+| `injectOrder` | `2500` | 注入在系统提示中的排序位置 |
+
+## 档案格式
+
+> 下面的人名、QQ、群号全是虚构示例，只为说明结构。
+
+```markdown
+# 示例昵称（100000001）
+
+## 名字
+- **账号昵称**：`示例昵称`
+- **各群群名片**：1000000001 → 小示
+
+## 基本信息
+- **身份**：管理员
+
+## 称呼与代词
+
+- 我叫「示例昵称」；性别未确认时用「对方」
+
+## 记录
+- 2026-01-01 00:00｜喜欢在深夜写代码
+```
+
+写入是**追加式**的，不会覆盖手写内容；文件头（名字/基本信息等）由人维护，`## 记录` 段由工具追加。
+
+## 设计取舍
+
+- **为什么读会话文件而不是订阅事件**：这样插件不依赖任何聊天通道插件，也不碰宿主内部状态。
+  代价是"同一轮里消息可能还没落盘"，因此保留了「上次成功发言人」兜底。
+- **为什么不用向量检索**：长期记忆的核心需求是"认识人和群"，结构化档案足够；向量检索成本高且难以人工校正。
+- **为什么档案是文件**：可审计、可备份、可手改。黑盒记忆出了问题没法查。
+
+## License
+
+MIT

package/lib/core.js

@@ -0,0 +1,308 @@
+/**
+ * Lotuses'Memory 核心逻辑（纯 Node，不依赖 dsh 运行时，可独立单测）。
+ *
+ * 负责：记忆档案读写/截断/压缩、会话 ID 解析、从会话文件里找最近发言人。
+ * 插件壳（index.js）只负责把这里的东西接到 systemPrompt 与工具注册上。
+ * @module dsh-lotuses-memory/core
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+
+
+/** 档案读取缓存：路径 → { mtimeMs, text }。 */
+const cache = new Map();
+
+/** 会话文件解析缓存：路径 → { mtimeMs, speaker }。 */
+const speakerCache = new Map();
+/**
+ * 每个会话「上次成功解析出来的发言人」。
+ *
+ * 为什么需要它：插件在组装请求时读会话文件，而那条 user/message 往往还没落盘
+ * （同一轮里先投递、后组装），当场解析会得到 undefined。此时退回上一轮记住的人 ——
+ * 比直接丢掉个人档案好，只有全新会话的第一轮才会真的没有。
+ */
+const lastKnownSpeaker = new Map();
+
+/**
+ * 解析记忆库根目录。
+ * @param config - 插件配置。
+ * @returns 绝对或相对路径。
+ */
+export function memoryRoot(config) {
+    const dir = typeof config.memoryDir === 'string' ? config.memoryDir.trim() : '';
+    if (dir !== '')
+        return dir.replace(/[\\/]+$/, '');
+    return path.resolve('Memory');
+}
+
+/**
+ * 解析会话根目录。
+ * @param config - 插件配置。
+ * @returns 目录路径。
+ */
+function sessionsRoot(config) {
+    const dir = typeof config.sessionsDir === 'string' ? config.sessionsDir.trim() : '';
+    if (dir !== '')
+        return dir.replace(/[\\/]+$/, '');
+    const home = process.env.DSH_HOME ?? path.join(process.env.HOME ?? process.env.USERPROFILE ?? '', '.dsh');
+    return path.join(home, 'sessions');
+}
+
+/**
+ * 读一份档案（按 mtime 缓存）。
+ * @param root - 记忆库根目录。
+ * @param folder - people / groups。
+ * @param key - QQ 号或群号。
+ * @returns 文本或 null。
+ */
+export function readDoc(root, folder, key) {
+    if (typeof key !== 'string' || key === '')
+        return null;
+    const full = path.join(root, folder, key + '.md');
+    try {
+        const mtime = fs.statSync(full).mtimeMs;
+        const hit = cache.get(full);
+        if (hit !== undefined && hit.mtimeMs === mtime)
+            return hit.text;
+        const text = fs.readFileSync(full, 'utf8');
+        cache.set(full, { mtimeMs: mtime, text });
+        return text;
+    }
+    catch {
+        return null;
+    }
+}
+
+/**
+ * 截断到指定长度（按行切）。
+ * @param text - 原文。
+ * @param max - 上限。
+ * @returns 截断后的文本。
+ */
+function trim(text, max) {
+    if (text.length <= max)
+        return text;
+    let cut = text.slice(0, max);
+    const nl = cut.lastIndexOf('\n');
+    if (nl > max * 0.6)
+        cut = cut.slice(0, nl);
+    return cut + '\n…（档案还有更多，需要细节可调 memory_recall）';
+}
+
+/**
+ * 从会话 ID 解析聊天对象。
+ *
+ * 约定（QQ 通道的会话命名）：`onebot-group-<群号>[-后缀]` / `onebot-private-<QQ>[-后缀]`。
+ * 其他通道解析不出来时返回 null，此时只注入"全局记忆"（不注入个人档案）。
+ * @param sessionId - 会话 id。
+ * @returns `{ kind, target }` 或 null。
+ */
+export function chatOfSession(sessionId) {
+    if (typeof sessionId !== 'string')
+        return null;
+    const m = /^onebot-(group|private)-(\d{5,12})/.exec(sessionId);
+    if (m === null)
+        return null;
+    return { kind: m[1], target: m[2] };
+}
+
+/**
+ * 解压 zstd 多帧并返回 JSONL 事件数组。
+ * @param file - 会话文件路径。
+ * @returns 事件数组（解析失败的跳过）。
+ */
+function readSessionEvents(file) {
+    const buf = fs.readFileSync(file);
+    const magic = Buffer.from([0x28, 0xb5, 0x2f, 0xfd]);
+    const offsets = [];
+    let i = 0;
+    while ((i = buf.indexOf(magic, i)) !== -1) {
+        offsets.push(i);
+        i += 4;
+    }
+    offsets.push(buf.length);
+    const chunks = [];
+    for (let k = 0; k < offsets.length - 1; k++) {
+        try {
+            chunks.push(zlib.zstdDecompressSync(buf.subarray(offsets[k], offsets[k + 1])).toString('utf8'));
+        }
+        catch { /* 跳过坏帧 */ }
+    }
+    const events = [];
+    for (const line of chunks.join('').split('\n')) {
+        if (line === '')
+            continue;
+        try {
+            events.push(JSON.parse(line));
+        }
+        catch { /* 跳过坏行 */ }
+    }
+    return events;
+}
+
+/**
+ * 找出某个会话最近一条用户消息的发送者 QQ。
+ *
+ * 为什么读文件而不是订阅事件：这样插件不依赖任何通道插件，也不碰宿主内部状态。
+ * 从消息正文的 `[hh:mm 昵称(QQ)]` 前缀解析；解析不到就返回 undefined（只注入群档案）。
+ * @param config - 插件配置。
+ * @param sessionId - 会话 id。
+ * @returns QQ 号或 undefined。
+ */
+export function lastSpeaker(config, sessionId) {
+    if (typeof sessionId !== 'string' || sessionId === '')
+        return undefined;
+    const root = sessionsRoot(config);
+    let dir = null;
+    try {
+        for (const workspace of fs.readdirSync(root)) {
+            const candidate = path.join(root, workspace, sessionId);
+            if (fs.existsSync(candidate)) {
+                dir = candidate;
+                break;
+            }
+        }
+    }
+    catch {
+        return lastKnownSpeaker.get(sessionId);
+    }
+    if (dir === null)
+        return lastKnownSpeaker.get(sessionId);
+    const file = path.join(dir, 'session.v4.jsonl.zstd');
+    try {
+        const mtime = fs.statSync(file).mtimeMs;
+        const hit = speakerCache.get(file);
+        if (hit !== undefined && hit.mtimeMs === mtime) {
+            if (hit.speaker !== undefined)
+                lastKnownSpeaker.set(sessionId, hit.speaker);
+            return hit.speaker ?? lastKnownSpeaker.get(sessionId);
+        }
+        const events = readSessionEvents(file);
+        let found;
+        for (let k = events.length - 1; k >= 0; k--) {
+            const e = events[k];
+            if (e?.type !== 'user/message')
+                continue;
+            const text = (e.data?.content ?? []).map((b) => (typeof b.text === 'string' ? b.text : '')).join('');
+            // `[hh:mm 昵称(QQ)]` 或 `[hh:mm 昵称(QQ，账号昵称:xx)]`
+            const m = /\[\d{1,2}:\d{2}\s[^\]]*?\((\d{5,12})[)\]]/.exec(text);
+            if (m !== null) {
+                found = m[1];
+                break;
+            }
+        }
+        speakerCache.set(file, { mtimeMs: mtime, speaker: found });
+        if (found !== undefined) {
+            lastKnownSpeaker.set(sessionId, found);
+            return found;
+        }
+        // 这一轮的 user/message 可能还没落盘 → 退回上一轮记住的人
+        return lastKnownSpeaker.get(sessionId);
+    }
+    catch {
+        return lastKnownSpeaker.get(sessionId);
+    }
+}
+
+/**
+ * 组装注入文本。
+ * @param root - 记忆库根目录。
+ * @param opts - `{ personId, groupId }`。
+ * @param config - 插件配置（取上限）。
+ * @returns 注入文本（空串表示没有可注入的内容）。
+ */
+export function buildHint(root, opts, config) {
+    const parts = [];
+    if (typeof opts.personId === 'string' && opts.personId !== '') {
+        const person = readDoc(root, 'people', opts.personId);
+        if (person !== null && person.trim() !== '')
+            parts.push('[记忆·这个人]\n' + trim(person, Number(config.maxPersonChars ?? 900)));
+        else
+            parts.push('[记忆] QQ ' + opts.personId + ' 是第一次见的新面孔，可以自然认识一下。');
+    }
+    if (typeof opts.groupId === 'string' && opts.groupId !== '') {
+        const group = readDoc(root, 'groups', opts.groupId);
+        if (group !== null && group.trim() !== '')
+            parts.push('[记忆·这个群]\n' + trim(group, Number(config.maxGroupChars ?? 600)));
+    }
+    if (parts.length === 0)
+        return '';
+    return parts.join('\n') + '\n（以上是可信的长期记忆，自然运用即可；不要把这些档案原文念给别人听）\n';
+}
+
+/**
+ * 追加一条事实到档案（不存在就建）。
+ * @param root - 记忆库根目录。
+ * @param kind - person / group。
+ * @param key - QQ 号或群号。
+ * @param text - 要记的内容。
+ * @returns 写入的文件路径。
+ */
+export function noteFact(root, kind, key, text) {
+    const folder = kind === 'group' ? 'groups' : 'people';
+    fs.mkdirSync(path.join(root, folder), { recursive: true });
+    const full = path.join(root, folder, key + '.md');
+    const now = new Date();
+    const pad = (n) => String(n).padStart(2, '0');
+    const stamp = now.getFullYear() + '-' + pad(now.getMonth() + 1) + '-' + pad(now.getDate())
+        + ' ' + pad(now.getHours()) + ':' + pad(now.getMinutes());
+    const line = '- ' + stamp + '｜' + String(text).trim().replace(/\n+/g, ' ');
+    if (!fs.existsSync(full))
+        fs.writeFileSync(full, (kind === 'group' ? '# 群 ' : '# QQ ') + key + '\n\n## 记录\n\n', 'utf8');
+    fs.appendFileSync(full, line + '\n', 'utf8');
+    cache.delete(full);
+    try {
+        compactIfNeeded(root, kind, key);
+    }
+    catch { /* 压缩失败不影响写入 */ }
+    return full;
+}
+
+/** 档案超过该长度就折叠旧记录。 */
+export const COMPACT_THRESHOLD = 4000;
+/** 折叠后保留的最近记录条数。 */
+export const COMPACT_KEEP = 40;
+
+/**
+ * 档案自动压缩：保留头部与最近 N 条记录，更早的折叠成一行计数。
+ * @param root - 记忆库根目录。
+ * @param kind - person / group。
+ * @param key - QQ 号或群号。
+ * @returns 是否发生折叠。
+ */
+export function compactIfNeeded(root, kind, key) {
+    const folder = kind === 'group' ? 'groups' : 'people';
+    const full = path.join(root, folder, key + '.md');
+    if (!fs.existsSync(full))
+        return false;
+    const text = fs.readFileSync(full, 'utf8');
+    if (text.length <= COMPACT_THRESHOLD)
+        return false;
+    const at = text.indexOf('## 记录');
+    if (at < 0)
+        return false;
+    const head = text.slice(0, at) + '## 记录\n\n';
+    const lines = text.slice(at).split('\n');
+    const recordIdx = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].startsWith('- ') && !lines[i].startsWith('- （更早的'))
+            recordIdx.push(i);
+    }
+    if (recordIdx.length <= COMPACT_KEEP)
+        return false;
+    let prevFolded = 0;
+    for (const l of lines) {
+        const m = /^- （更早的 (\d+) 条记录已折叠/.exec(l);
+        if (m !== null) {
+            prevFolded = Number(m[1]) || 0;
+            break;
+        }
+    }
+    const folded = recordIdx.length - COMPACT_KEEP;
+    const keepFrom = recordIdx[recordIdx.length - COMPACT_KEEP];
+    const rest = lines.slice(keepFrom).filter((l) => !/^- （更早的 \d+ 条记录已折叠/.test(l));
+    fs.writeFileSync(full, head + '- （更早的 ' + (folded + prevFolded) + ' 条记录已折叠；如需细节可翻会话历史）\n' + rest.join('\n'), 'utf8');
+    cache.delete(full);
+    return true;
+}

package/lib/index.js

@@ -0,0 +1,145 @@
+/**
+ * Lotuses'Memory（dsh-lotuses-memory）— 跨会话长期记忆（独立插件）
+ *
+ * 只做三件事，逻辑都在 core.js 里：
+ *  1. 用 systemPrompt.context 每轮注入「这个人 / 这个群」的档案摘要
+ *  2. 注册 memory_note（写事实）与 memory_recall（翻全文）
+ *  3. 写档案时自动压缩（core.noteFact 内部完成）
+ *
+ * 与聊天通道完全解耦：从会话 ID 解析聊天对象、从会话文件解析发言人，
+ * 不依赖任何通道插件，也不改用户消息正文。
+ * @module dsh-lotuses-memory
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { z } from 'zod';
+import {
+    buildHint,
+    chatOfSession,
+    lastSpeaker,
+    memoryRoot,
+    noteFact,
+    readDoc,
+} from './core.js';
+
+export { compactIfNeeded, chatOfSession, lastSpeaker, buildHint, noteFact } from './core.js';
+export { COMPACT_KEEP, COMPACT_THRESHOLD } from './core.js';
+
+/** Cordis 插件名。 */
+export const name = 'lotuses-memory';
+
+/** 依赖的服务：系统提示组装 + 工具注册。 */
+export const inject = ['systemPrompt', 'tools'];
+
+/** 配置 schema（cordis 会对它调用 .validate，必须用 zod/schemastery 这类 schema 对象，不能是普通 JSON）。 */
+export const Config = z.object({
+    memoryDir: z.string().default('').describe('记忆库目录；留空则用 <工作目录>/Memory'),
+    sessionsDir: z.string().default('').describe('会话文件根目录；留空则用 <DSH_HOME>/sessions'),
+    maxPersonChars: z.number().default(900).describe('单个人物档案注入上限（字符）'),
+    maxGroupChars: z.number().default(600).describe('单个群档案注入上限（字符）'),
+    injectOrder: z.number().default(2500).describe('注入在系统提示里的排序位置'),
+});
+/**
+ * 插件入口。
+ * @param ctx - cordis 插件上下文。
+ * @param rawConfig - 插件配置。
+ */
+export function apply(ctx, rawConfig) {
+    const config = { ...rawConfig };
+    const root = memoryRoot(config);
+    console.log('[lotuses-memory] 已加载：记忆库 ' + root);
+
+    // ① 每轮请求自动注入
+    ctx.effect(() => ctx.systemPrompt.context({
+        name: 'memory:hint',
+        order: Number(config.injectOrder ?? 2500),
+        interpolate: false,
+        text: (context) => {
+            try {
+                const sessionId = context?.agent?.session?.id;
+                const chat = chatOfSession(sessionId);
+                const speaker = lastSpeaker(config, sessionId);
+                const hint = buildHint(root, {
+                    personId: speaker,
+                    groupId: chat?.kind === 'group' ? chat.target : undefined,
+                }, config);
+                console.log('[lotuses-memory] 注入 session=' + String(sessionId)
+                    + ' chat=' + JSON.stringify(chat)
+                    + ' speaker=' + String(speaker)
+                    + ' 长度=' + hint.length
+                    + ' contextKeys=' + Object.keys(context ?? {}).join(','));
+                return hint;
+            }
+            catch (error) {
+                console.log('[lotuses-memory] 注入失败: ' + String(error && error.message));
+                return '';
+            }
+        },
+    }), 'dsh-memory.inject');
+
+    // ② 工具：写记忆
+    ctx.effect(() => ctx.tools.register(defineTool({
+        name: 'memory_note',
+        description: '把值得长期记住的事实写进记忆库（跨会话共享）。'
+            + '\n适合记：这个人是谁 / 喜欢什么 / 说过什么承诺、这个群是干什么的 / 有哪些常驻成员、自己的重要经历。'
+            + '\n不要记：一次性闲聊、临时状态，以及密码 / 密钥 / 住址这类敏感信息。'
+            + '\n一句一条，写清「谁 / 什么事」，不要抄大段原话。',
+        parameters: {
+            kind: { type: 'string', description: 'person=记人，group=记群' },
+            key: { type: 'string', description: 'QQ 号（记人）或群号（记群）；省略则按当前会话推断' },
+            text: { type: 'string', description: '要记的事实（一句话）' },
+        },
+        output: {
+            schema: { type: 'json' },
+            render: (_args, value) => [{
+                type: 'text',
+                text: value !== null && typeof value === 'object' && value.ok === true
+                    ? '(记下了：' + value.kind + ' ' + value.key + ')'
+                    : '(没记成)',
+            }],
+        },
+        isConcurrencySafe: () => true,
+        execute: async (args, exec) => {
+            const kind = args.kind === 'group' ? 'group' : 'person';
+            const text = String(args.text ?? '').trim();
+            let key = String(args.key ?? '').trim().replace(/\D/g, '');
+            if (key === '') {
+                const sessionId = exec?.agent?.session?.id;
+                const chat = chatOfSession(sessionId);
+                if (kind === 'group')
+                    key = chat?.kind === 'group' ? chat.target : '';
+                else
+                    key = lastSpeaker(config, sessionId) ?? '';
+            }
+            if (key === '' || text === '')
+                throw new Error('memory_note: 缺少 key 或 text');
+            noteFact(root, kind, key, text);
+            return { ok: true, kind, key };
+        },
+    })), 'dsh-memory.note');
+
+    // ③ 工具：翻细节
+    ctx.effect(() => ctx.tools.register(defineTool({
+        name: 'memory_recall',
+        description: '读一份记忆档案的全文（人物或群）。需要了解某人/某群的完整记录时用。',
+        parameters: {
+            kind: { type: 'string', description: 'person=人，group=群' },
+            key: { type: 'string', description: 'QQ 号或群号' },
+        },
+        output: {
+            schema: { type: 'json' },
+            render: (_args, value) => [{
+                type: 'text',
+                text: typeof value?.text === 'string' && value.text !== '' ? value.text : '(没有找到这份档案)',
+            }],
+        },
+        isConcurrencySafe: () => true,
+        execute: async (args, exec) => {
+            const kind = args.kind === 'group' ? 'group' : 'person';
+            const key = String(args.key ?? '').trim().replace(/\D/g, '');
+            if (key === '')
+                throw new Error('memory_recall: 缺少 key');
+            const text = readDoc(root, kind === 'group' ? 'groups' : 'people', key);
+            return { text: text ?? '' };
+        },
+    })), 'dsh-memory.recall');
+}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@lotuseslunarland/dsh-lotuses-memory",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.3",
+  "description": "Lotuses'Memory — 跨会话长期记忆：按聊天对象自动把人物/群档案注入 systemPrompt，并提供 memory_note / memory_recall 工具",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/core.js",
+    "README.md"
+  ],
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "memory",
+    "long-term-memory"
+  ],
+  "author": "lotuseslunarland",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.5",
+    "@deepseek-ai/dsh-system-prompt": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.1-rc.2"
+  }
+}