dsh-memoir 0.4.3

package/lib/tools.js

@@ -0,0 +1,292 @@
+/**
+ * Agent tools for dsh-memoir: memoir_record (persist one work / lesson /
+ * action / note entry) and memoir_read (read project / global memory). Both
+ * tools resolve the caller's workspace from the executing agent's session cwd
+ * and delegate all persistence to the structured MemoirStore.
+ *
+ * v0.3.1: section headers no longer duplicate "##"; project/global reads are
+ * bounded by internal hard caps; descriptions and renders are trimmed.
+ * v0.4.0: memoir_read gains limit (default 8, max 30) and detail
+ * (compact default / full) so reads are cheap by default.
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { SECTIONS, SECTION_KEYS, formatTime, projectTitle } from './store.js';
+/** One text content block (the only render shape these tools emit). */
+export function text(value) {
+    return [{ type: 'text', text: value }];
+}
+/** Resolve the caller session's workspace cwd (absolute), or undefined. */
+export function resolveWorkspace(exec) {
+    const cwd = exec?.agent?.session?.header?.cwd;
+    return typeof cwd === 'string' && cwd !== '' ? cwd : undefined;
+}
+/** Internal hard caps: bound read output regardless of stored volume. */
+export const READ_GLOBAL_MAX_ENTRIES_PER_PROJECT = 50;
+export const READ_OUTPUT_MAX_CHARS = 16000;
+/** Full-detail entry line (time + label + title + content). */
+export function renderEntryFull(entry) {
+    const label = SECTIONS[entry.section]?.label ?? entry.section;
+    const when = formatTime(entry.time);
+    const head = entry.title !== undefined ? entry.title + ' — ' : '';
+    return '- [' + when + '] [' + label + '] ' + head + entry.content;
+}
+/** Compact one-line entry (id + title + collapsed single-line content). */
+export function renderEntryCompact(entry, maxContent = 200) {
+    const head = entry.title !== undefined && entry.title !== '' ? entry.title + ' — ' : '';
+    const oneLine = entry.content.replace(/\s+/g, ' ').trim();
+    const body = oneLine.length > maxContent ? oneLine.slice(0, maxContent) + '…' : oneLine;
+    return '- [' + entry.id + '] ' + head + body;
+}
+/** Append a truncation note when the limit clipped the output. */
+function clippedNote(total, shown) {
+    return '（共 ' + total + ' 条匹配，仅显示 ' + shown + ' 条，可用 limit 参数调整）';
+}
+/**
+ * Incremental output budget (v0.4.2): blocks are appended in RANK order and
+ * the budget stops accepting once the char cap is reached. This preserves
+ * the highest-ranked head of the result set — the old tail slice kept the
+ * bottom of the list and dropped exactly the entries the ranking put first.
+ */
+class OutputBudget {
+    parts = [];
+    used = 0;
+    overflow = false;
+    max;
+    constructor(max) {
+        this.max = max;
+    }
+    /** Add one block; returns false once the budget is exhausted. */
+    add(text) {
+        if (text === '')
+            return true;
+        if (this.overflow)
+            return false;
+        const cost = this.used === 0 ? text.length : text.length + 2; // two-char newline separator
+        if (this.used + cost > this.max) {
+            this.overflow = true;
+            return false;
+        }
+        this.parts.push(text);
+        this.used += cost;
+        return true;
+    }
+    get text() {
+        return this.parts.join('\n\n');
+    }
+    get clipped() {
+        return this.overflow;
+    }
+}
+/** Append grouped entries ('## section' headers + bullets) into the budget. */
+function appendGrouped(budget, entries, renderEntry) {
+    let shown = 0;
+    let lastSection = '';
+    for (const entry of entries) {
+        if (entry.section !== lastSection) {
+            lastSection = entry.section;
+            if (!budget.add('## ' + (SECTIONS[entry.section]?.label ?? entry.section)))
+                break;
+        }
+        if (!budget.add(renderEntry(entry)))
+            break;
+        shown++;
+    }
+    return shown;
+}
+/** The record tool: persist one memory entry. */
+export function memoirRecordTool(store) {
+    return defineTool({
+        name: 'memoir_record',
+        description: '把一条记忆写入项目持久记忆，供未来会话继承。阶段任务收尾时归纳「做了什么(work)/经验教训(lessons)/下一步行动(actions)」分条记录。' +
+            'Triggers: 记录经验教训、沉淀记忆、归纳工作、更新行动指南、总结踩坑。',
+        parameters: {
+            section: {
+                type: 'string',
+                required: true,
+                enum: [...SECTION_KEYS],
+                description: '记忆分类：work 工作记录 / lessons 经验教训 / actions 行动指南 / note 备注。',
+            },
+            title: {
+                type: 'string',
+                description: '可选，一句话标题（如「修复 pet 悬停闪退」）。',
+            },
+            content: {
+                type: 'string',
+                required: true,
+                description: '记忆正文：具体做了什么、结论、教训或下一步怎么做。建议精炼、可执行。',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    section: { type: 'string', required: true },
+                    id: { type: 'string', required: true },
+                    title: { type: 'string' },
+                    projectFile: { type: 'string', required: true },
+                    globalIndex: { type: 'string', required: true },
+                    recordedAt: { type: 'string', required: true },
+                },
+            },
+            // Minimal text: the structured fields stay available for debugging, but
+            // the agent-facing render is one line (paths/timestamps add no value).
+            render: (_args, value) => text('已记录 [' + value.section + '] ' + (value.title !== undefined && value.title !== '' ? value.title + ' ' : '') + '(id: ' + value.id + ')'),
+        },
+        async execute(args, exec) {
+            const cwd = resolveWorkspace(exec);
+            if (cwd === undefined) {
+                throw new Error('无法确定会话工作区（缺少 agent cwd）；请在项目会话内调用 memoir_record');
+            }
+            const sessionId = exec?.agent?.id ? String(exec.agent.id) : undefined;
+            const entry = store.record(cwd, args, sessionId);
+            return {
+                section: entry.section,
+                id: entry.id,
+                ...(entry.title !== undefined ? { title: entry.title } : {}),
+                // record() already regenerated the project file — never write twice.
+                projectFile: store.projectFilePath(cwd),
+                globalIndex: store.path,
+                recordedAt: formatTime(entry.time),
+            };
+        },
+    });
+}
+/** The read tool: project / global / all memory with optional filters. */
+export function memoirReadTool(store, options, retrieval) {
+    const defaultLimit = options?.defaultLimit ?? 8;
+    const maxLimit = options?.maxLimit ?? 30;
+    return defineTool({
+        name: 'memoir_read',
+        description: '读取项目持久记忆与经验教训（默认返回最近 ' + defaultLimit + ' 条 compact 摘要）。开始新会话或接手旧项目时先调用。' +
+            'Triggers: 读取记忆、回顾项目历史、查询经验教训、接手项目、查看行动指南。',
+        parameters: {
+            scope: {
+                type: 'string',
+                enum: ['project', 'global', 'all'],
+                description: '读取范围：project 仅本项目（默认）/ global 全局跨项目 / all 全部。',
+            },
+            section: {
+                type: 'string',
+                enum: [...SECTION_KEYS],
+                description: '可选，只返回某一分类。',
+            },
+            query: {
+                type: 'string',
+                description: '可选，本地相关性检索标题与正文：支持中文短语、英文关键词、代码标识符与路径，并按相关性排序。',
+            },
+            limit: {
+                type: 'number',
+                description: '可选，最多返回条数（默认 ' + defaultLimit + '，最大 ' + maxLimit + '）。',
+            },
+            detail: {
+                type: 'string',
+                enum: ['compact', 'full'],
+                description: '输出形态：compact 单行摘要（默认）/ full 完整正文。',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    text: { type: 'string', required: true },
+                },
+            },
+            render: (_args, value) => text(value.text),
+        },
+        async execute(args, exec) {
+            const scope = args.scope ?? 'project';
+            const cwd = resolveWorkspace(exec);
+            const detail = args.detail ?? 'compact';
+            const rawLimit = typeof args.limit === 'number' && Number.isFinite(args.limit) ? Math.floor(args.limit) : defaultLimit;
+            const limit = Math.min(maxLimit, Math.max(1, rawLimit));
+            const renderEntry = detail === 'full' ? renderEntryFull : renderEntryCompact;
+            const query = typeof args.query === 'string' ? args.query.toLowerCase() : '';
+            const matches = (s) => (query === '' ? true : String(s).toLowerCase().includes(query));
+            const filterEntry = (e) => (args.section === undefined || e.section === args.section) && matches((e.title ?? '') + ' ' + e.content);
+            // v0.4.2: output is assembled through a rank-order budget — the top of
+            // the ranked list always survives truncation.
+            const budget = new OutputBudget(READ_OUTPUT_MAX_CHARS);
+            if (scope === 'project' || scope === 'all') {
+                if (cwd === undefined) {
+                    budget.add('（无法确定会话工作区，跳过项目记忆）');
+                }
+                else {
+                    // v0.4.1: query → ranked recall (BM25 + boosts), no query → newest first.
+                    const ranked = query !== '' && retrieval !== undefined
+                        ? retrieval.cachedSearch(query, { section: args.section, cwd, limit, detail })
+                        : [];
+                    if (ranked.length > 0) {
+                        const entries = ranked.slice(0, limit).map((r) => r.entry);
+                        appendGrouped(budget, entries, renderEntry);
+                        if (ranked.length > entries.length)
+                            budget.add(clippedNote(ranked.length, entries.length));
+                    }
+                    else {
+                        const matched = store.entries(cwd).filter(filterEntry);
+                        if (matched.length === 0) {
+                            budget.add('本项目（' + cwd + '）暂无' + (query !== '' || args.section !== undefined ? '匹配的' : '') + '持久记忆。可用 memoir_record 沉淀。');
+                        }
+                        else {
+                            const entries = matched.slice(-limit);
+                            appendGrouped(budget, entries, renderEntry);
+                            if (matched.length > entries.length)
+                                budget.add(clippedNote(matched.length, entries.length));
+                        }
+                    }
+                }
+            }
+            if (scope === 'global' || scope === 'all') {
+                const ranked = query !== '' && retrieval !== undefined
+                    ? retrieval.cachedSearch(query, { section: args.section, limit, detail })
+                    : [];
+                if (ranked.length > 0) {
+                    // v0.4.2: the limit is a true global Top-K — slice first, then
+                    // group by project for rendering (never per-project × limit).
+                    const top = ranked.slice(0, limit);
+                    const grouped = new Map();
+                    for (const result of top) {
+                        const bucket = grouped.get(result.projectPath) ?? [];
+                        bucket.push(result.entry);
+                        grouped.set(result.projectPath, bucket);
+                    }
+                    for (const [path, entries] of grouped) {
+                        if (!budget.add(['### ' + projectTitle(path), 'path: ' + path].join('\n')))
+                            break;
+                        for (const entry of entries) {
+                            if (!budget.add(renderEntry(entry)))
+                                break;
+                        }
+                    }
+                    if (ranked.length > top.length)
+                        budget.add(clippedNote(ranked.length, top.length));
+                }
+                else {
+                    const projects = store.listProjects();
+                    for (const project of projects) {
+                        const matched = store.entries(project.path).filter(filterEntry);
+                        if (matched.length === 0)
+                            continue;
+                        const entries = matched.slice(-Math.min(limit, READ_GLOBAL_MAX_ENTRIES_PER_PROJECT));
+                        if (!budget.add(['### ' + (project.title || projectTitle(project.path)), 'path: ' + project.path + '  updated: ' + formatTime(project.updatedAt)].join('\n')))
+                            break;
+                        for (const entry of entries) {
+                            if (!budget.add(renderEntry(entry)))
+                                break;
+                        }
+                        if (matched.length > entries.length)
+                            budget.add(clippedNote(matched.length, entries.length));
+                    }
+                    if (budget.text === '')
+                        budget.add('（全局索引中没有匹配的内容）');
+                }
+            }
+            const text = budget.text;
+            if (budget.clipped) {
+                return { text: text + '\n\n（输出超过 ' + READ_OUTPUT_MAX_CHARS + ' 字符上限，已保留相关性最高/最新的部分）' };
+            }
+            return { text };
+        },
+    });
+}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "dsh-memoir",
+  "description": "Cache-aware local project memory for DeepSeek Harness (DSH): agents distill session work, lessons and next actions into a local JSON store (~/.dsh/dsh-memoir.json, source of truth) with a per-project PROJECT_MEMORY.md projection; bounded hot-memory (ranked, session-frozen) is auto-injected into the system prompt while long-tail history is served by ranked BM25 retrieval (memoir_read, no embeddings / no external services); a web-GUI 'Memory' panel offers ranked search, hot-memory inspection and retrieval diagnostics over /api/dsh-memoir routes. TypeScript, mounted via the dsh.bundle.patch manifest, no dsh source changes.",
+  "version": "0.4.3",
+  "type": "module",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime"
+      ],
+      "platform": "web"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-runtime": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-host-webserver": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-system-prompt": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.6",
+    "@types/node": "^22.20.1",
+    "@types/react": "~18.3.31",
+    "@types/react-dom": "^18.3.7",
+    "esbuild": "^0.28.2",
+    "typescript": "~5.8.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node build.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test \"test/*.test.ts\"",
+    "bench": "npm run build && node bench/bench.mjs"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  },
+  "files": [
+    "lib/*.js",
+    "lib/*.js.map",
+    "lib/*.d.ts",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "license": "Apache-2.0",
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "dsh-plugin",
+    "memory",
+    "lessons",
+    "session",
+    "agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Qinling-Melon-Farmers/dsh-memoir.git"
+  }
+}