@max-null/dsh-memory 0.5.0 → 0.6.0

package/dist/index.js

@@ -9,9 +9,10 @@ import { MemoryEngine } from "./engine.js";
 import { MemoryGateway } from "./remote.js";
 import { mountMemoryApi } from "./routes.js";
 import { SELF_DESCRIPTION } from "./self.js";
+import { DEFAULT_INJECTION_BUDGET, DEFAULT_SUMMARY_CHARS, renderInjection } from "./injection.js";
 export { MemoryEngine } from "./engine.js";
 export { MemoryId } from "./engine.js";
-export { bm25Scores, tokenize } from "./bm25.js";
+export { bm25FieldScores, bm25Scores, cosineSimilarity, rrfFuse, tokenize } from "./bm25.js";
 export const name = 'dsh-memory';
 export const inject = ['storage', 'systemPrompt', 'tools', 'webServer', 'webRuntime'];
 const RECORD_SCHEMA = {
@@ -26,6 +27,7 @@ const RECORD_SCHEMA = {
         keywords: { type: 'array', required: true, items: { type: 'string' } },
         createdAt: { type: 'number', required: true },
         updatedAt: { type: 'number', required: true },
+        lastUsedAt: { type: 'number' },
     },
 };
 const HIT_SCHEMA = {
@@ -36,6 +38,21 @@ const HIT_SCHEMA = {
         score: { type: 'number', required: true },
     },
 };
+/** 模板记录（0.6.0）：不暴露本地文件路径（meta.path 引擎内部使用）。 */
+const PROMPT_RECORD_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        id: { type: 'string', required: true },
+        name: { type: 'string', required: true },
+        dimension: { type: 'string' },
+        difficulty: { type: 'string' },
+        tags: { type: 'array', items: { type: 'string' } },
+        summary: { type: 'string', required: true },
+        source: { type: 'string', enum: ['user', 'agent'], required: true },
+        namespace: { type: 'string', enum: ['global', 'project'], required: true },
+    },
+};
 function recordValue(record) {
     return {
         id: String(record.id),
@@ -46,11 +63,25 @@ function recordValue(record) {
         keywords: record.keywords,
         createdAt: record.createdAt,
         updatedAt: record.updatedAt,
+        ...record.lastUsedAt === undefined ? {} : { lastUsedAt: record.lastUsedAt },
     };
 }
 function hitValue(hit) {
     return { record: recordValue(hit.record), score: hit.score };
 }
+function promptValue(record) {
+    const meta = record.meta;
+    return {
+        id: String(record.id),
+        name: meta?.name ?? '',
+        ...meta?.dimension === undefined ? {} : { dimension: meta.dimension },
+        ...meta?.difficulty === undefined ? {} : { difficulty: meta.difficulty },
+        tags: meta?.tags ?? [],
+        summary: meta?.summary ?? record.content.slice(0, 200),
+        source: meta?.source ?? 'user',
+        namespace: record.namespace,
+    };
+}
 // 0.3.0：审核语义双语（host 侧 GUIDANCE 无法跟随 DSH locale 动态切换，
 // 采用中英双语都写、模型自取——设计文档「风险与注意」）。
 const GUIDANCE = 'Use memory tools for cross-session preferences, habits, and project conventions. '
@@ -63,16 +94,29 @@ const GUIDANCE = 'Use memory tools for cross-session preferences, habits, and pr
     + 'When earlier context may be relevant, call memory_search to recall it — reviewable memories '
     + '(`suggested`) are searchable too. 相关历史上下文可用 memory_search 检索——待审核的记忆也可检索。'
     + 'Every memory is plaintext and inspectable with memory_list; memory_forget removes one. '
-    + '所有记忆均为明文，可用 memory_list 查看；memory_forget 删除一条。';
-// 0.3.4：注入只注入 global 的 approved+injected（systemPrompt context 是
-// 同步回调、无会话 cwd 可及）；工作区（project）记忆按会话 cwd 路由，靠
-// memory_search / 面板访问。
-function recallText(memory) {
-    const auto = memory.recallRecords();
-    if (auto.length === 0)
+    + '所有记忆均为明文，可用 memory_list 查看；memory_forget 删除一条。'
+    + 'Approved + injected memories of the CURRENT session workspace are every-turn injected too. '
+    + '已审核 + 常驻注入开关打开的工作区记忆也会每轮注入（按当前会话工作区路由）。';
+// 0.5.1：`memory:recall` provider 可经 AssembleContext.agent 拿到当前会话
+// 的 header.cwd——注入 = global + 当前会话工作区的 approved+injected
+// （0.3.4 起工作区记忆就按会话 cwd 路由；provider 是同步回调，只读已
+// 打开/缓存的表，未打开时本轮工作区部分为空，由 ensureProjectOpen 预热）。
+// 0.5.2：注入经摘要化 + 预算截断（renderInjection，纯函数）防上下文膨胀。
+function recallText(memory, projectCwd, budget, summaryChars) {
+    const rendered = renderInjection(memory.recallRecords(projectCwd), budget, summaryChars);
+    if (rendered.lines.length === 0)
         return '';
-    const lines = auto.map(record => `- [memory:${String(record.id)}] ${record.content}`);
-    return `Remembered preferences and conventions — apply these:\n${lines.join('\n')}`;
+    return `Remembered preferences and conventions — apply these:\n${rendered.lines.join('\n')}`;
+}
+/** 从组装上下文取当前 agent 会话的工作区 cwd（AssembleContext.agent 由 dsh-agent 声明合并提供）。 */
+function assemblyProjectCwd(assembly) {
+    return assembly
+        ?.agent?.session?.header?.cwd;
+}
+/** 会话 header 的 cwd（session/created 事件载荷），预热 work 区表用。 */
+function sessionProjectCwd(session) {
+    const cwd = session?.meta?.cwd;
+    return typeof cwd === 'string' && cwd !== '' ? cwd : undefined;
 }
 /** 从工具执行上下文取调用会话的工作区 cwd（0.3.4 工作区路由）。 */
 function execProjectCwd(exec) {
@@ -108,7 +152,24 @@ export async function apply(ctx, config) {
     ctx.systemPrompt.context({
         name: 'memory:recall',
         order: 50,
-        text: () => recallText(memory),
+        text: (assembly) => {
+            const cwd = assemblyProjectCwd(assembly);
+            if (cwd !== undefined)
+                void memory.ensureProjectOpen(cwd).catch(() => { });
+            const budget = config?.injectionBudget ?? DEFAULT_INJECTION_BUDGET;
+            const summaryChars = config?.summaryChars ?? DEFAULT_SUMMARY_CHARS;
+            return recallText(memory, cwd, budget, summaryChars);
+        },
+    });
+    // 会话创建即预热对应工作区的 project 表（0.5.1）：让首轮模型请求就
+    // 能注入工作区常驻记忆（provider 同步只读已打开的表）。
+    // session/created 事件由 dsh-session 提供（可选依赖：无 session 服务
+    // 的环境不派发事件，预热由 provider 路径兜底）。
+    const emitter = ctx;
+    emitter.on?.('session/created', (session) => {
+        const cwd = sessionProjectCwd(session);
+        if (cwd !== undefined)
+            void memory.ensureProjectOpen(cwd).catch(() => { });
     });
     ctx.tools.register(defineTool({
         name: 'memory_save',
@@ -154,11 +215,12 @@ export async function apply(ctx, config) {
     }));
     ctx.tools.register(defineTool({
         name: 'memory_search',
-        description: 'Recall stored memories by keyword. Deterministic literal matching — a miss means no stored term matched the query. 按关键词检索记忆（含待审核条目）。',
+        description: 'Recall stored memories by keyword. Deterministic literal matching — a miss means no stored term matched the query. 按关键词检索记忆（中文 2-gram + 关键词加权；配置嵌入时含语义融合；含待审核条目）。',
         parameters: {
             query: { type: 'string', required: true, description: 'Keyword query. 关键词查询.' },
             namespace: { type: 'string', enum: ['global', 'project'], description: 'Restrict to one namespace. 限定单个命名空间.' },
             status: { type: 'string', enum: ['suggested', 'approved'], description: 'Restrict to one review status. 限定审核状态.' },
+            kind: { type: 'string', enum: ['fact', 'prompt'], description: 'Restrict by record kind — fact (memories, default) or prompt (templates; use prompt_search instead). 按记录类别过滤：fact=记忆（默认）/ prompt=模板（模板请用 prompt_search）.' },
         },
         output: {
             schema: { type: 'array', items: HIT_SCHEMA },
@@ -168,10 +230,141 @@ export async function apply(ctx, config) {
             return memory.search(args.query, {
                 ...args.namespace === undefined ? {} : { namespace: args.namespace },
                 ...args.status === undefined ? {} : { status: args.status },
+                ...args.kind === undefined ? {} : { kind: args.kind },
             }, execProjectCwd(exec)).then(hits => hits.map(hitValue));
         },
         presentCall: args => present('Search memory', 'read', args.query),
     }));
+    ctx.tools.register(defineTool({
+        name: 'prompt_search',
+        description: 'Search prompt templates by keyword plus dimension/difficulty/tag filters. Returns matching summaries; call prompt_get for the full text. 按关键词+维度/难度/标签检索提示词模板，返回匹配摘要；取全文用 prompt_get。',
+        parameters: {
+            query: { type: 'string', required: true, description: 'Keyword query (name/tag/body). 关键词查询（名称/标签/正文）.' },
+            dimension: { type: 'string', description: 'Filter by dimension (前端/后端/…). 按维度过滤.' },
+            difficulty: { type: 'string', description: 'Filter by difficulty (L1-L5/LX). 按难度过滤.' },
+            tags: { type: 'array', items: { type: 'string' }, description: 'Filter by any of these tags. 按任一标签过滤.' },
+            namespace: { type: 'string', enum: ['global', 'project'], description: 'Restrict to one namespace. 限定单个命名空间.' },
+        },
+        output: {
+            schema: { type: 'array', items: PROMPT_RECORD_SCHEMA },
+            render: (_args, value) => renderJson(value),
+        },
+        execute(args, exec) {
+            return memory.refreshPromptIndex(execProjectCwd(exec)).then(async () => {
+                const all = await memory.list({ kind: 'prompt', ...args.namespace === undefined ? {} : { namespace: args.namespace } }, execProjectCwd(exec));
+                const filtered = all.filter(record => {
+                    const meta = record.meta;
+                    if (meta === undefined)
+                        return true;
+                    if (args.dimension !== undefined && args.dimension !== '' && meta.dimension !== args.dimension)
+                        return false;
+                    if (args.difficulty !== undefined && args.difficulty !== '' && meta.difficulty !== args.difficulty)
+                        return false;
+                    if (args.tags !== undefined && args.tags.length > 0 && !args.tags.some(tag => meta.tags.includes(tag)))
+                        return false;
+                    return true;
+                });
+                const quoted = JSON.stringify(args.query ?? '');
+                const hits = await memory.search(quoted, { kind: 'prompt', ...args.namespace === undefined ? {} : { namespace: args.namespace } }, execProjectCwd(exec));
+                const hitIds = new Set(hits.map(hit => String(hit.record.id)));
+                // 过滤器命中列表按检索分排序在前，未命中关键词的过滤命中排后（按名称）
+                const byQuery = filtered.filter(record => hitIds.has(String(record.id)));
+                const rest = filtered
+                    .filter(record => !hitIds.has(String(record.id)))
+                    .sort((a, b) => (a.meta?.name ?? '').localeCompare(b.meta?.name ?? ''));
+                return [...byQuery, ...rest].map(promptValue);
+            });
+        },
+        presentCall: args => present('Search prompt library', 'read', args.query),
+    }));
+    ctx.tools.register(defineTool({
+        name: 'prompt_get',
+        description: 'Fetch a prompt template full text by id or name (name matches the file stem without the seq prefix). 按 id 或名称取模板全文（名称 = 文件名去序号部分）。',
+        parameters: {
+            nameOrId: { type: 'string', required: true, description: 'Template id or name. 模板 id 或名称.' },
+        },
+        output: {
+            schema: { type: 'object', additionalProperties: false, properties: {
+                    name: { type: 'string', required: true },
+                    dimension: { type: 'string' },
+                    difficulty: { type: 'string' },
+                    tags: { type: 'array', items: { type: 'string' } },
+                    body: { type: 'string', required: true },
+                    fallback: { type: 'string' },
+                } },
+            render: (_args, value) => renderJson(value),
+        },
+        execute(args, exec) {
+            return memory.promptGet(args.nameOrId, execProjectCwd(exec)).then(file => ({
+                name: file.meta.name,
+                ...file.meta.dimension === undefined ? {} : { dimension: file.meta.dimension },
+                ...file.meta.difficulty === undefined ? {} : { difficulty: file.meta.difficulty },
+                tags: file.meta.tags,
+                body: file.body,
+                ...file.fallback === null ? {} : { fallback: file.fallback },
+            }));
+        },
+        presentCall: args => present('Get prompt template', 'read', args.nameOrId),
+    }));
+    ctx.tools.register(defineTool({
+        name: 'prompt_list',
+        description: 'List every prompt template index (no full text), optionally filtered by dimension/difficulty/tag. 列出全部模板索引（不含全文），可按维度/难度/标签过滤。',
+        parameters: {
+            dimension: { type: 'string', description: '按维度过滤.' },
+            difficulty: { type: 'string', description: '按难度过滤.' },
+            tags: { type: 'array', items: { type: 'string' }, description: '按任一标签过滤.' },
+            namespace: { type: 'string', enum: ['global', 'project'], description: '限定单个命名空间.' },
+        },
+        output: {
+            schema: { type: 'array', items: PROMPT_RECORD_SCHEMA },
+            render: (_args, value) => renderJson(value),
+        },
+        execute(args, exec) {
+            return memory.refreshPromptIndex(execProjectCwd(exec)).then(() => memory.list({ kind: 'prompt', ...args.namespace === undefined ? {} : { namespace: args.namespace } }, execProjectCwd(exec))).then(records => records.filter(record => {
+                const meta = record.meta;
+                if (meta === undefined)
+                    return false;
+                if (args.dimension !== undefined && args.dimension !== '' && meta.dimension !== args.dimension)
+                    return false;
+                if (args.difficulty !== undefined && args.difficulty !== '' && meta.difficulty !== args.difficulty)
+                    return false;
+                if (args.tags !== undefined && args.tags.length > 0 && !args.tags.some(tag => meta.tags.includes(tag)))
+                    return false;
+                return true;
+            }).sort((a, b) => (a.meta?.seq ?? 0) - (b.meta?.seq ?? 0)).map(promptValue));
+        },
+        presentCall: () => present('List prompt templates', 'read'),
+    }));
+    ctx.tools.register(defineTool({
+        name: 'prompt_add',
+        description: 'Add one prompt template to the library (writes a metadata-marked md file; source=agent is surfaced in the UI). 新增一条提示词模板（写元数据 md 文件；source=agent 在 UI 角标提示）。',
+        parameters: {
+            name: { type: 'string', required: true, description: 'Template name (also the file stem). 模板名称（也是文件名）.' },
+            content: { type: 'string', required: true, description: 'The prompt body. 提示词正文.' },
+            dimension: { type: 'string', description: '维度（前端/后端/…）.' },
+            difficulty: { type: 'string', description: '难度（L1-L5/LX）.' },
+            tags: { type: 'array', items: { type: 'string' }, description: '检索用标签.' },
+            fallback: { type: 'string', description: '可选备用提示词.' },
+            namespace: { type: 'string', enum: ['global', 'project'], description: '默认 global.' },
+        },
+        output: {
+            schema: PROMPT_RECORD_SCHEMA,
+            render: (_args, value) => renderJson(value),
+        },
+        execute(args, exec) {
+            return memory.promptAdd({
+                name: args.name,
+                content: args.content,
+                ...args.dimension === undefined ? {} : { dimension: args.dimension },
+                ...args.difficulty === undefined ? {} : { difficulty: args.difficulty },
+                ...args.tags === undefined ? {} : { tags: args.tags },
+                ...args.fallback === undefined ? {} : { fallback: args.fallback },
+                ...args.namespace === undefined ? {} : { namespace: args.namespace },
+                source: 'agent',
+            }, execProjectCwd(exec)).then(promptValue);
+        },
+        presentCall: args => present('Add prompt template', 'other', args.name),
+    }));
     ctx.tools.register(defineTool({
         name: 'memory_forget',
         description: 'Delete one stored memory by id. The human owner may remove any memory.',

package/dist/injection.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 注入渲染（0.5.2）：`memory:recall` 与面板「注入预览」共用的确定性
+ * 渲染——摘要化 + 预算截断。纯函数、无模型调用：注入行 = 每条记忆的
+ * 单行摘要（内容过长取首行截断），超出预算（字符数）时按「最近更新
+ * 优先」贪心保留，省略计数返回给 UI 提示。
+ */
+import type { MemoryRecord } from './engine.ts';
+/** 摘要截断上限（字符）：中英混合场景下 ~40-60 token。 */
+export declare const DEFAULT_SUMMARY_CHARS = 80;
+/** 注入预算（字符）：0.5.2 起默认开启，防常驻注入随记忆增长膨胀上下文。 */
+export declare const DEFAULT_INJECTION_BUDGET = 1500;
+/**
+ * 确定性摘要：取首行，超过 maxChars 截断加省略号。
+ * 空内容/空首行回退为去掉换行后的前 maxChars（保证 any 内容有摘要）。
+ */
+export declare function deriveSummary(content: string, maxChars: number): string;
+/** 一条注入行的渲染文本（与面板预览完全一致）。 */
+export declare function injectionLine(record: MemoryRecord, summaryChars: number): string;
+export interface InjectionRender {
+    /** 实际注入行（已按预算截断、按更新时间降序）。 */
+    lines: string[];
+    /** 生效的预算（字符；null = 无限制）。 */
+    budget: number | null;
+    /** 因预算被省略的候选条数（0 = 全部注入）。 */
+    omitted: number;
+    /** 实际注入的字符数（摘要 + 标记开销之和）。 */
+    chars: number;
+}
+/**
+ * 由候选记录渲染注入行：按使用序降序（lastUsedAt 优先、缺省回退
+ * updatedAt——最近使用/更新的记忆最先），逐条累加开销直到预算用尽；
+ * 预算为 null 或非正数时全量注入（不过滤）。
+ */
+export declare function renderInjection(records: readonly MemoryRecord[], budget: number | null, summaryChars: number): InjectionRender;

package/dist/injection.js

@@ -0,0 +1,52 @@
+/**
+ * 注入渲染（0.5.2）：`memory:recall` 与面板「注入预览」共用的确定性
+ * 渲染——摘要化 + 预算截断。纯函数、无模型调用：注入行 = 每条记忆的
+ * 单行摘要（内容过长取首行截断），超出预算（字符数）时按「最近更新
+ * 优先」贪心保留，省略计数返回给 UI 提示。
+ */
+/** 摘要截断上限（字符）：中英混合场景下 ~40-60 token。 */
+export const DEFAULT_SUMMARY_CHARS = 80;
+/** 注入预算（字符）：0.5.2 起默认开启，防常驻注入随记忆增长膨胀上下文。 */
+export const DEFAULT_INJECTION_BUDGET = 1500;
+/** 单条注入行的固定标记开销（不含摘要本体）。 */
+const LINE_OVERHEAD = 27;
+/**
+ * 确定性摘要：取首行，超过 maxChars 截断加省略号。
+ * 空内容/空首行回退为去掉换行后的前 maxChars（保证 any 内容有摘要）。
+ */
+export function deriveSummary(content, maxChars) {
+    const firstLine = content.split('\n')[0].trim();
+    if (firstLine !== '') {
+        return firstLine.length <= maxChars ? firstLine : `${firstLine.slice(0, maxChars)}…`;
+    }
+    const collapsed = content.replace(/\s+/g, ' ').trim();
+    if (collapsed === '')
+        return content;
+    return collapsed.length <= maxChars ? collapsed : `${collapsed.slice(0, maxChars)}…`;
+}
+/** 一条注入行的渲染文本（与面板预览完全一致）。 */
+export function injectionLine(record, summaryChars) {
+    return `- [memory:${String(record.id).slice(0, 8)}:${record.namespace}] ${deriveSummary(record.content, summaryChars)}`;
+}
+/**
+ * 由候选记录渲染注入行：按使用序降序（lastUsedAt 优先、缺省回退
+ * updatedAt——最近使用/更新的记忆最先），逐条累加开销直到预算用尽；
+ * 预算为 null 或非正数时全量注入（不过滤）。
+ */
+export function renderInjection(records, budget, summaryChars) {
+    const ordered = [...records].sort((left, right) => (right.lastUsedAt ?? right.updatedAt) - (left.lastUsedAt ?? left.updatedAt));
+    const lines = [];
+    let chars = 0;
+    let omitted = 0;
+    for (const record of ordered) {
+        const text = injectionLine(record, summaryChars);
+        const cost = text.length + LINE_OVERHEAD;
+        if (budget !== null && budget > 0 && chars + cost > budget) {
+            omitted++;
+            continue;
+        }
+        lines.push(text);
+        chars += cost;
+    }
+    return { lines, budget: budget ?? null, omitted, chars };
+}

package/dist/prompt-files.d.ts

@@ -0,0 +1,77 @@
+/**
+ * prompt-files.ts — 提示词模板 md 文件解析与目录扫描（纯 Node，零依赖可测）。
+ *
+ * 文件是模板的唯一事实源（设计文档 §2）：用户可直接放入/编辑/删除 md，
+ * 索引层按 mtime 惰性刷新。格式：
+ *
+ * ```md
+ * ---
+ * seq: 36
+ * name: "样例"          # 必填；缺 name 的文件跳过（坏文件不崩不索引）
+ * dimension: "前端"
+ * difficulty: "L3"
+ * tags: ["Three.js"]
+ * source: user          # user | agent（模型新增打 agent 角标）
+ * createdAt: 2026-08-26
+ * ---
+ * (主提示词全文)
+ * ---
+ * (备用提示词，可选)
+ * ```
+ * 解析失败/缺 name 的文件记 warnings，不影响整体扫描。
+ */
+export interface PromptMeta {
+    seq?: number;
+    name: string;
+    dimension?: string;
+    difficulty?: string;
+    tags: string[];
+    source: 'user' | 'agent';
+    createdAt?: number;
+}
+export interface PromptFile {
+    path: string;
+    mtime: number;
+    meta: PromptMeta;
+    /** 主提示词全文。 */
+    body: string;
+    /** 备用提示词（可选；md 中以独立 `---` 行与正文分隔）。 */
+    fallback: string | null;
+    /** 索引摘要（正文前 200 字，替换换行）。 */
+    summary: string;
+}
+/**
+ * 解析一份 md（frontmatter + 正文 + 可选备用段）。纯文本解析，不碰文件系统；
+ * mtime 由调用方传入（scan 从 stat 取；纯解析测试传 0）。
+ * @returns ok:true 带结构化结果；ok:false 带人读错误（跳过不索引）。
+ */
+export declare function parsePromptFile(path: string, text: string, mtime?: number): {
+    ok: true;
+    file: PromptFile;
+} | {
+    ok: false;
+    error: string;
+};
+/** 扫描一个目录的全部 *.md（目录不存在 = 空）。坏文件收集 warnings。 */
+export declare function scanPromptDir(dir: string): {
+    files: PromptFile[];
+    warnings: string[];
+};
+/** 文件名安全化（Windows 保留字符替换；保留中文与常用符号）。 */
+export declare function sanitizeFileName(name: string): string;
+/** 下一个可用序号（现有文件 `\d+_` 前缀 + 1；目录空 = 1）。 */
+export declare function nextSeq(dir: string): number;
+export interface PromptWriteInput {
+    name: string;
+    dimension?: string;
+    difficulty?: string;
+    tags?: string[];
+    content: string;
+    fallback?: string;
+    source: 'user' | 'agent';
+}
+/**
+ * 写一份模板 md（目录不存在自动创建；序号自动分配；同名防追加后缀）。
+ * @returns 写入路径。
+ */
+export declare function writePromptFile(dir: string, input: PromptWriteInput): string;

package/dist/prompt-files.js

@@ -0,0 +1,188 @@
+/**
+ * prompt-files.ts — 提示词模板 md 文件解析与目录扫描（纯 Node，零依赖可测）。
+ *
+ * 文件是模板的唯一事实源（设计文档 §2）：用户可直接放入/编辑/删除 md，
+ * 索引层按 mtime 惰性刷新。格式：
+ *
+ * ```md
+ * ---
+ * seq: 36
+ * name: "样例"          # 必填；缺 name 的文件跳过（坏文件不崩不索引）
+ * dimension: "前端"
+ * difficulty: "L3"
+ * tags: ["Three.js"]
+ * source: user          # user | agent（模型新增打 agent 角标）
+ * createdAt: 2026-08-26
+ * ---
+ * (主提示词全文)
+ * ---
+ * (备用提示词，可选)
+ * ```
+ * 解析失败/缺 name 的文件记 warnings，不影响整体扫描。
+ */
+import { readdirSync, readFileSync, statSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+const SUMMARY_CHARS = 200;
+/** 解析简单 frontmatter 值：字符串（含引号）/数字/布尔/数组。 */
+function parseFrontmatterValue(raw) {
+    const value = raw.trim();
+    if (value.startsWith('[') && value.endsWith(']')) {
+        return value
+            .slice(1, -1).split(',')
+            .map(part => part.trim().replace(/^["']|["']$/g, ''))
+            .filter(part => part !== '');
+    }
+    if (value.startsWith('"') && value.endsWith('"'))
+        return value.slice(1, -1);
+    if (value.startsWith("'") && value.endsWith("'"))
+        return value.slice(1, -1);
+    if (/^\d+$/.test(value))
+        return Number(value);
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    return value;
+}
+/**
+ * 解析一份 md（frontmatter + 正文 + 可选备用段）。纯文本解析，不碰文件系统；
+ * mtime 由调用方传入（scan 从 stat 取；纯解析测试传 0）。
+ * @returns ok:true 带结构化结果；ok:false 带人读错误（跳过不索引）。
+ */
+export function parsePromptFile(path, text, mtime = 0) {
+    const lines = text.split(/\r?\n/);
+    if (lines[0]?.trim() !== '---') {
+        return { ok: false, error: 'missing frontmatter fence (first line must be ---)' };
+    }
+    let fence = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i].trim() === '---') {
+            fence = i;
+            break;
+        }
+    }
+    if (fence === -1)
+        return { ok: false, error: 'unclosed frontmatter fence' };
+    const meta = {};
+    for (const line of lines.slice(1, fence)) {
+        const m = /^([A-Za-z][A-Za-z0-9]*)\s*:\s*(.*)$/.exec(line);
+        if (m === null || m[2] === undefined)
+            continue;
+        meta[m[1]] = parseFrontmatterValue(m[2]);
+    }
+    const name = typeof meta.name === 'string' ? meta.name : '';
+    if (name === '')
+        return { ok: false, error: 'missing required frontmatter field "name"' };
+    const source = meta.source === 'agent' ? 'agent' : 'user';
+    // 正文：frontmatter 后到第一个独立 `---` 行为止（剩余为备用提示词）
+    const bodyLines = [];
+    const fallbackLines = [];
+    let inFallback = false;
+    for (const line of lines.slice(fence + 1)) {
+        if (!inFallback && line.trim() === '---') {
+            inFallback = true;
+            continue;
+        }
+        ;
+        (inFallback ? fallbackLines : bodyLines).push(line);
+    }
+    const body = bodyLines.join('\n').trim();
+    if (body === '')
+        return { ok: false, error: 'empty prompt body' };
+    // 备用段首行常为「备用提示词2」之类的标题行，跳过（约定：正文与备用用 --- 分隔）
+    const fallbackRaw = fallbackLines.join('\n').trim();
+    const fallback = fallbackRaw === '' ? null : fallbackRaw.replace(/^\s*(备用提示词\d*|fallback\d*)\s*\n?/i, '');
+    const file = {
+        path,
+        mtime,
+        meta: {
+            seq: typeof meta.seq === 'number' ? meta.seq : undefined,
+            name,
+            dimension: typeof meta.dimension === 'string' ? meta.dimension : undefined,
+            difficulty: typeof meta.difficulty === 'string' ? meta.difficulty : undefined,
+            tags: Array.isArray(meta.tags) ? meta.tags.filter((tag) => typeof tag === 'string') : [],
+            source,
+            createdAt: typeof meta.createdAt === 'number' ? meta.createdAt : undefined,
+        },
+        body,
+        fallback,
+        summary: body.replace(/\s+/g, ' ').trim().slice(0, SUMMARY_CHARS),
+    };
+    return { ok: true, file };
+}
+/** 扫描一个目录的全部 *.md（目录不存在 = 空）。坏文件收集 warnings。 */
+export function scanPromptDir(dir) {
+    const files = [];
+    const warnings = [];
+    let entries = [];
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return { files, warnings }; // 目录不存在：空库
+    }
+    for (const entry of entries) {
+        if (!entry.toLowerCase().endsWith('.md'))
+            continue;
+        const path = join(dir, entry);
+        let text;
+        try {
+            text = readFileSync(path, 'utf8');
+        }
+        catch (error) {
+            warnings.push(`${path}: read failed (${error instanceof Error ? error.message : String(error)})`);
+            continue;
+        }
+        const parsed = parsePromptFile(path, text, statSync(path).mtimeMs);
+        if (!parsed.ok) {
+            warnings.push(`${path}: ${parsed.error}`);
+            continue;
+        }
+        files.push(parsed.file);
+    }
+    return { files, warnings };
+}
+/** 文件名安全化（Windows 保留字符替换；保留中文与常用符号）。 */
+export function sanitizeFileName(name) {
+    const safe = name.replace(/[<>:"/\\|?*\u0000-\u001F]/g, '_').trim();
+    return (safe === '' ? 'untitled' : safe).slice(0, 80);
+}
+/** 下一个可用序号（现有文件 `\d+_` 前缀 + 1；目录空 = 1）。 */
+export function nextSeq(dir) {
+    let max = 0;
+    try {
+        for (const entry of readdirSync(dir)) {
+            const m = /^(\d+)_/.exec(entry);
+            if (m !== null)
+                max = Math.max(max, Number(m[1]));
+        }
+    }
+    catch { /* 目录不存在：从 1 开始 */ }
+    return max + 1;
+}
+/**
+ * 写一份模板 md（目录不存在自动创建；序号自动分配；同名防追加后缀）。
+ * @returns 写入路径。
+ */
+export function writePromptFile(dir, input) {
+    mkdirSync(dir, { recursive: true });
+    const seq = nextSeq(dir);
+    const base = sanitizeFileName(input.name);
+    let path = join(dir, `${seq}_${base}.md`);
+    let attempt = 0;
+    while (existsSync(path)) {
+        attempt += 1;
+        path = join(dir, `${seq}_${base}_${attempt}.md`);
+    }
+    const lines = ['---', `seq: ${seq}`, `name: ${JSON.stringify(input.name)}`, `source: ${input.source}`];
+    if (input.dimension !== undefined && input.dimension !== '')
+        lines.push(`dimension: ${JSON.stringify(input.dimension)}`);
+    if (input.difficulty !== undefined && input.difficulty !== '')
+        lines.push(`difficulty: ${JSON.stringify(input.difficulty)}`);
+    if (input.tags !== undefined && input.tags.length > 0)
+        lines.push(`tags: [${input.tags.map(tag => JSON.stringify(tag)).join(', ')}]`);
+    lines.push(`createdAt: ${new Date().toISOString().slice(0, 10)}`, '---');
+    const text = `${lines.join('\n')}\n\n${input.content.trim()}\n${input.fallback === undefined || input.fallback === '' ? '' : `\n---\n\n${input.fallback.trim()}\n`}`;
+    writeFileSync(path, text, 'utf8');
+    return path;
+}

package/dist/remote.d.ts

@@ -29,12 +29,16 @@ export declare class MemoryGateway extends TypertRemoteService {
     /** Force-reload storage files (external edits; JsonStorageBackend has no watch). */
     reload(cwd?: string): Promise<MemoryRecord[]>;
     /**
-     * 注入预览（0.3.5）：开发者查看当前注入到 system prompt 的记忆内容
-     * ——self 自述 + 实际注入的 global approved+injected 记忆。
+     * 注入预览（0.3.5 + 0.5.2）：开发者查看当前注入到 system prompt 的记忆
+     * 内容——self 自述 + 当前会话工作区（cwd）的 approved+injected 记忆，
+     * 经摘要化 + 预算截断（与 memory:recall 同源渲染）。
      */
-    injectionPreview(): {
+    injectionPreview(cwd?: string, budget?: number | null, summaryChars?: number): Promise<{
         self: string;
-        injected: MemoryRecord[];
-    };
+        lines: string[];
+        budget: number | null;
+        omitted: number;
+        chars: number;
+    }>;
 }
 export default MemoryGateway;