@max-null/dsh-memory 0.5.0 → 0.6.0

package/dist/bm25.js

@@ -3,12 +3,55 @@
  * store — no model call — so recall is deterministic and a miss is explainable
  * as "no keyword match".
  */
-/** Split text into lowercase terms: English/number runs stay whole, each CJK ideograph its own term. */
+/**
+ * Split text into lowercase terms: English/number runs stay whole; each CJK
+ * ideograph its own term AND each adjacent pair its own bigram (0.5.2) —
+ * bigram raises Chinese multi-char hit precision, single chars keep
+ * single-character queries working.
+ */
 export function tokenize(text) {
-    return text.toLowerCase().match(/[a-z0-9]+|[\u3400-\u9fff]/g) ?? [];
+    const lower = text.toLowerCase();
+    const terms = [];
+    const runs = lower.match(/[a-z0-9]+|[\u3400-\u9fff]+/g) ?? [];
+    for (const run of runs) {
+        if (/^[a-z0-9]/.test(run)) {
+            terms.push(run);
+            continue;
+        }
+        for (let i = 0; i < run.length; i++)
+            terms.push(run[i]);
+        for (let i = 0; i < run.length - 1; i++)
+            terms.push(run.slice(i, i + 2));
+    }
+    return terms;
 }
 const K1 = 1.2;
 const B = 0.75;
+/** 命中 tags（keywords）的 term 频率权重（0.5.2：人工关键词比正文更可检索）。 */
+const TAG_BOOST = 2;
+/** 单文档 BM25 打分（tags 命中 ×TAG_BOOST；文档长度按同一加权核算）。 */
+function scoreDoc(queryTerms, body, tags, documentFrequency, n, averageLength) {
+    let score = 0;
+    const length = body.length + tags.length * TAG_BOOST;
+    for (const term of queryTerms) {
+        let bodyTf = 0;
+        for (const candidate of body)
+            if (candidate === term)
+                bodyTf++;
+        let tagTf = 0;
+        for (const candidate of tags)
+            if (candidate === term)
+                tagTf++;
+        if (bodyTf + tagTf === 0)
+            continue;
+        const frequency = documentFrequency.get(term) ?? 0;
+        const idf = Math.log(1 + (n - frequency + 0.5) / (frequency + 0.5));
+        const weightedTf = bodyTf + tagTf * TAG_BOOST;
+        const denominator = weightedTf + K1 * (1 - B + B * (length / (averageLength || 1)));
+        score += idf * (weightedTf * (K1 + 1)) / denominator;
+    }
+    return score;
+}
 /** Score one query against each document with BM25, in document order. */
 export function bm25Scores(query, docs) {
     const queryTerms = tokenize(query);
@@ -20,23 +63,59 @@ export function bm25Scores(query, docs) {
         }
     }
     const n = docs.length;
-    const totalLength = tokenized.reduce((sum, doc) => sum + doc.length, 0);
-    const averageLength = n === 0 ? 0 : totalLength / n;
-    return tokenized.map((doc) => {
-        let score = 0;
-        for (const term of queryTerms) {
-            let termFrequency = 0;
-            for (const candidate of doc) {
-                if (candidate === term)
-                    termFrequency++;
-            }
-            if (termFrequency === 0)
-                continue;
-            const frequency = documentFrequency.get(term) ?? 0;
-            const idf = Math.log(1 + (n - frequency + 0.5) / (frequency + 0.5));
-            const denominator = termFrequency + K1 * (1 - B + B * (doc.length / (averageLength || 1)));
-            score += idf * (termFrequency * (K1 + 1)) / denominator;
+    const averageLength = n === 0 ? 0 : tokenized.reduce((sum, doc) => sum + doc.length, 0) / n;
+    return tokenized.map(doc => scoreDoc(queryTerms, doc, [], documentFrequency, n, averageLength));
+}
+/**
+ * 字段加权 BM25（0.5.2）：body（记忆内容）与 tags（人工关键词）分离打分，
+ * tags 命中 ×TAG_BOOST；用于 memory_search，人工关键词比正文更可检索。
+ */
+export function bm25FieldScores(query, docs) {
+    const queryTerms = tokenize(query);
+    const bodies = docs.map(doc => tokenize(doc.body));
+    const tags = docs.map(doc => doc.tags === undefined || doc.tags === '' ? [] : tokenize(doc.tags));
+    const documentFrequency = new Map();
+    for (let i = 0; i < bodies.length; i++) {
+        for (const term of new Set([...bodies[i], ...tags[i]])) {
+            documentFrequency.set(term, (documentFrequency.get(term) ?? 0) + 1);
         }
-        return score;
-    });
+    }
+    const n = docs.length;
+    const averageLength = n === 0
+        ? 0
+        : bodies.reduce((sum, body, i) => sum + body.length + tags[i].length * TAG_BOOST, 0) / n;
+    return bodies.map((body, i) => scoreDoc(queryTerms, body, tags[i], documentFrequency, n, averageLength));
+}
+/**
+ * RRF（Reciprocal Rank Fusion，0.5.2 混合检索）：按各通道排名倒数融合。
+ * 只依赖排名不依赖分数，两个异构打分通道（BM25 / 余弦相似度）可直接合流。
+ * @param rankings - 每通道一个 id → 排名（0 = 第一）；同一 id 在多个通道的
+ *   分数累加。
+ * @param k - RRF 常数（惯例 60）。
+ * @returns id → 融合分数（按降序排序的数组）。
+ */
+export function rrfFuse(rankings, k = 60) {
+    const scores = new Map();
+    for (const ranking of rankings) {
+        ranking.forEach((id, rank) => {
+            scores.set(id, (scores.get(id) ?? 0) + 1 / (k + rank + 1));
+        });
+    }
+    return [...scores.entries()].sort((left, right) => right[1] - left[1]);
+}
+/** 余弦相似度（默认 similarity；向量维度不一致返回 0）。 */
+export function cosineSimilarity(left, right) {
+    if (left.length === 0 || left.length !== right.length)
+        return 0;
+    let dot = 0;
+    let leftNorm = 0;
+    let rightNorm = 0;
+    for (let i = 0; i < left.length; i++) {
+        dot += left[i] * right[i];
+        leftNorm += left[i] * left[i];
+        rightNorm += right[i] * right[i];
+    }
+    if (leftNorm === 0 || rightNorm === 0)
+        return 0;
+    return dot / (Math.sqrt(leftNorm) * Math.sqrt(rightNorm));
 }

package/dist/engine.d.ts

@@ -5,6 +5,7 @@
  * is always created `suggested` and becomes effective only through `setStatus`.
  */
 import { Service } from '@deepseek-ai/cordis';
+import { type PromptFile } from './prompt-files.ts';
 declare const memoryIdBrand: unique symbol;
 /** Opaque identity of one stored memory record. */
 export type MemoryId = string & {
@@ -18,6 +19,27 @@ export type MemoryNamespace = 'global' | 'project';
  * 审核通过。注入与否由独立维度 `injected` 控制（见 MemoryRecord）。
  */
 export type MemoryStatus = 'suggested' | 'approved';
+/**
+ * 记录类别（0.6.0 模板库）：'fact' = 常规记忆（缺省，旧数据即此）；
+ * 'prompt' = 提示词模板索引记录（文件是事实源，见 prompt-files.ts）。
+ */
+export type MemoryKind = 'fact' | 'prompt';
+/** prompt 索引记录的附加元数据（与 md 文件 frontmatter 对齐，工具/UI 直接取用）。 */
+export interface PromptMetaIndex {
+    seq?: number;
+    name: string;
+    dimension?: string;
+    difficulty?: string;
+    tags: string[];
+    /** 索引摘要（正文前 200 字）。 */
+    summary: string;
+    /** md 文件绝对路径（引擎内部使用；工具输出不暴露）。 */
+    path: string;
+    /** 索引时的文件 mtime（惰性刷新比对）。 */
+    mtime: number;
+    /** user=用户创建；agent=模型新增（UI 角标）。 */
+    source: 'user' | 'agent';
+}
 export interface MemoryRecord {
     id: MemoryId;
     namespace: MemoryNamespace;
@@ -28,6 +50,12 @@ export interface MemoryRecord {
     keywords: string[];
     createdAt: number;
     updatedAt: number;
+    /** 最近一次被 memory_search 命中的时间（0.5.3 冷热追踪）；无则未命中过。 */
+    lastUsedAt?: number;
+    /** 记录类别（缺省 'fact'）。 */
+    kind?: MemoryKind;
+    /** prompt 记录元数据（仅 kind==='prompt'）。 */
+    meta?: PromptMetaIndex;
 }
 export interface MemoryWrite {
     content: string;
@@ -38,6 +66,8 @@ export interface MemoryFilter {
     namespace?: MemoryNamespace;
     status?: MemoryStatus;
     injected?: boolean;
+    /** 记录类别过滤（0.6.0）；缺省不过滤（工具层显式传 kind='fact' 保持旧行为）。 */
+    kind?: MemoryKind;
 }
 export interface MemoryHit {
     record: MemoryRecord;
@@ -68,12 +98,38 @@ declare module '@deepseek-ai/cordis' {
         'memory/changed'(change: MemoryChange): void;
     }
 }
+/**
+ * 嵌入能力（0.5.2 混合检索）：缺省不配置 = 纯 BM25（行为不变）；
+ * 配置后 memory_search 以 BM25 与语义结果做 RRF 融合，向量持久化到
+ * 存储文件（vector 字段，外部可读），失败自动降级回纯 BM25。
+ */
+export interface MemoryEmbeddings {
+    /** 文本 → 向量（与输入等长，一维浮点数组）。 */
+    embed(texts: readonly string[], signal?: AbortSignal): Promise<readonly number[][]>;
+    /** 相似度函数（缺省余弦相似度）。 */
+    similarity?: (left: readonly number[], right: readonly number[]) => number;
+}
 /** Engine configuration: the two storage roots, defaulted to home and project. */
 export interface MemoryConfig {
     /** Root for `global` memories; defaults to `$DSH_HOME/storages`. */
     globalRoot?: string;
     /** Root for `project` memories; defaults to `<cwd>/.dsh/storages`. */
     projectRoot?: string;
+    /**
+     * 常驻注入预算（字符，0.5.2）：`memory:recall` 每轮注入的摘要总量上限，
+     * 超预算按「最近更新优先」省略（面板提示省略数）。null/0 = 不限制。
+     * 默认 DEFAULT_INJECTION_BUDGET（1500 字符，约 400-700 token）。
+     */
+    injectionBudget?: number | null;
+    /** 单条注入摘要截断上限（字符）；默认 DEFAULT_SUMMARY_CHARS（80）。 */
+    summaryChars?: number;
+    /** 混合语义检索（0.5.2）：缺省纯 BM25；配置后与 BM25 做 RRF 融合。 */
+    embeddings?: MemoryEmbeddings;
+    /** 语义侧参与融合的 topK（0.5.2）；默认 5。 */
+    semanticTopK?: number;
+    /** 全局提示词模板根目录（0.6.0）；默认 `$DSH_HOME/prompt-library`。
+     *  project 模板随工作区（`<workspace>/.dsh/prompt-library`，与记忆同构）。 */
+    promptGlobalRoot?: string;
 }
 /**
  * Cross-session plaintext memory over the storage hub, split by namespace:
@@ -115,6 +171,16 @@ export declare class MemoryEngine extends Service {
     remember(input: MemoryWrite, projectCwd?: string): Promise<MemoryRecord>;
     list(filter?: MemoryFilter, projectCwd?: string): Promise<MemoryRecord[]>;
     search(query: string, filter?: MemoryFilter, projectCwd?: string): Promise<MemoryHit[]>;
+    /**
+     * 语义排序（0.5.2）：查询向量 + 候选向量的余弦相似度，仅在有
+     * embeddings 配置时被调用。缺失向量（新增/更新过的记录）在此补生成
+     * 并持久化（vector 字段）；生成失败抛给调用方降级。
+     */
+    private semanticRanking;
+    /** 按已知 id 定位记录所在表（global 优先，其次当前工作区表）。 */
+    private tableOf;
+    /** 命中标记：把 lastUsedAt 写回（命中记录不存在时跳过；不 emit 事件——统计性字段）。 */
+    private markUsed;
     forget(id: MemoryId, projectCwd?: string): Promise<boolean>;
     setStatus(id: MemoryId, status: MemoryStatus, projectCwd?: string): Promise<MemoryRecord>;
     /**
@@ -132,13 +198,59 @@ export declare class MemoryEngine extends Service {
         keywords?: string[];
     }, projectCwd?: string): Promise<MemoryRecord>;
     /**
-     * 注入专用（0.3.4）：systemPrompt context 是同步回调、无会话 cwd 可及，
-     * 只返回 global 的 approved+injected（工作区记忆走检索/面板）。
+     * 预热某工作区的 project 表（异步打开并缓存）。system prompt 的
+     * `memory:recall` provider 是同步回调——只读已打开的表；预热让
+     * 会话创建/首次请求后本轮或下一轮即可注入工作区记忆。
      */
-    recallRecords(): MemoryRecord[];
+    ensureProjectOpen(projectCwd: string): Promise<void>;
+    /**
+     * 注入专用（0.3.4 + 0.5.1）：system prompt 的 `memory:recall` context
+     * provider 可经 AssembleContext.agent 拿到当前会话 header.cwd，因此
+     * 注入 = global 的 approved+injected + 当前会话工作区的 approved+injected。
+     * provider 是同步回调：只读已打开/缓存的表，未打开的工作区本轮为空
+     * （`ensureProjectOpen` 提供预热，工具/面板路径也会打开）。
+     */
+    recallRecords(projectCwd?: string): MemoryRecord[];
     private allRecords;
     private recordsOf;
     private tableFor;
     private requireTable;
+    /** 全局模板根（默认 `$DSH_HOME/prompt-library`，可配置覆盖）。 */
+    private promptGlobalDir;
+    /** project 模板根（随工作区 `<workspace>/.dsh/prompt-library`，与记忆同构）。 */
+    private promptProjectDir;
+    /** 稳定索引 id（按路径 hash；文件删除后随刷新清理）。 */
+    private promptIdOf;
+    /**
+     * 扫描模板目录并同步索引（mtime 惰性：未变条目零写；目录缺失 = 空库）。
+     * @returns 统计（扫描数/变更数/清理数 + 坏文件警告）。
+     */
+    refreshPromptIndex(projectCwd?: string): Promise<{
+        scan: number;
+        changed: number;
+        removed: number;
+        warnings: string[];
+    }>;
+    /**
+     * 取模板（id 或名称/路径片段定位），返回 md 全文（直读文件，忽略索引缓存）。
+     * @throws 未命中或文件解析失败（错误信息可读）。
+     */
+    promptGet(nameOrId: string, projectCwd?: string): Promise<PromptFile>;
+    /**
+     * 新增模板：写 md 文件（序号自动分配/文件名安全化/同名防覆盖）+ 刷新索引。
+     * 返回索引记录（模型新增 source='agent'，UI 角标提示）。
+     */
+    promptAdd(input: {
+        name: string;
+        dimension?: string;
+        difficulty?: string;
+        tags?: string[];
+        content: string;
+        fallback?: string;
+        source: 'user' | 'agent';
+        namespace?: MemoryNamespace;
+    }, projectCwd?: string): Promise<MemoryRecord>;
+    /** 删除模板：md 文件与索引一并删除；未命中返回 false。 */
+    promptRemove(idOrName: string, projectCwd?: string): Promise<boolean>;
 }
 export {};