dsh-prime-memory 0.11.0

package/dist/types.d.ts

@@ -0,0 +1,139 @@
+/**
+ * 领域类型与词汇表(净室重写)。
+ *
+ * 覆盖:记忆族/档位、Hall 目录、L0/L1 记录形状、抽取产出与族判定三级兜底、
+ * L2 场景摘要与 L1 检索命中。字段名与取值是磁盘/管线两侧的既定契约,不可更名。
+ */
+/** 蒸馏 Prompt 家族:chat = 个人记忆(persona/episodic/instruction + 用户画像),work = 工作记忆(work_fact/work_task/work_method/work_artifact + Team Operating Doctrine)。 */
+export type MemoryFamily = 'chat' | 'work';
+/** 会话记忆档位:auto = 双族自动判定 | chat/work = 单族 | off = 本会话对记忆系统隐身。 */
+export type MemoryMode = 'auto' | 'chat' | 'work' | 'off';
+/** 蒸馏可用的档位(off 在捕获侧被拦截,永远到不了管线)。 */
+export type ExtractMode = 'auto' | 'chat' | 'work';
+/**
+ * Hall(粗分类属性通道,与 family/type 正交):给 L1 记忆加一个跨族的可检索标签。
+ * 主线 3 个默认启用;finance/journey 为实验性(默认不进 hall.enabled,显式加入才参与
+ * 自动打标)。细粒度归属由 prompt 语义判断,拿不准时省略 hall(不进 General 兜底,避免噪声)。
+ */
+export interface HallDef {
+    id: string;
+    label: string;
+    /** 实验性(默认不进 hall.enabled,需用户显式开启才参与自动打标/过滤)。 */
+    experimental?: boolean;
+}
+export declare const HALL_CATALOG: HallDef[];
+/** 默认启用的 Hall id(主线 3;实验性条目要用户写进 config hall.enabled 才生效)。 */
+export declare const HALL_DEFAULT_ENABLED: string[];
+export type HallId = (typeof HALL_CATALOG)[number]['id'];
+export declare function hallLabel(id: string): string;
+/** 记录族标签推断:work_* 前缀 → work,其余(含 auto 档兜底)→ chat。 */
+export declare function familyForType(type: string): MemoryFamily;
+/**
+ * 记忆的持续性(时间轴第三维,与 createdAt/updatedAt 正交):
+ * - 'p' point     时点事件(某事在某刻发生)——历史事实,永不被"取代"
+ * - 's' span      已结束的持续区间——validTo 是关键信息,不可被后来者改写
+ * - 'o' open      仍在持续——被矛盾事实取代时应闭合 validTo 并标 rw
+ * - 't' timeless  无时间性(规则/偏好/恒真事实)——不随时间失效
+ *
+ * 缺省(undefined)= 未判定:不参与取代/闭合判定,只当普通事实。
+ */
+export type Persistence = 'p' | 's' | 'o' | 't';
+export declare const PERSISTENCE_VALUES: readonly Persistence[];
+/** 持续性取值归一:只认 p/s/o/t,其余(缺省/非法)返回 undefined。 */
+export declare function normPersistence(raw: unknown): Persistence | undefined;
+/** 日志接口(适配 ctx.logger)。 */
+export interface MemoryLogger {
+    debug?(msg: string): void;
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+}
+/** L0 会话消息(管线内的运行时形态)。 */
+export interface ConversationMessage {
+    /** 唯一消息 ID(L1 prompt 的 source_message_ids 追踪用)。 */
+    id: string;
+    role: 'user' | 'assistant';
+    content: string;
+    /** epoch ms */
+    timestamp: number;
+}
+/** L0 JSONL 记录(一条消息一行,磁盘事实源形状)。 */
+export interface L0MessageRecord {
+    sessionId: string;
+    recordedAt: string;
+    id: string;
+    role: 'user' | 'assistant';
+    content: string;
+    timestamp: number;
+}
+/** L1 抽取产出(LLM 返回的记忆条目,尚未分配 record id)。 */
+export interface ExtractedMemory {
+    content: string;
+    type: string;
+    priority: number;
+    source_message_ids: string[];
+    metadata: Record<string, unknown>;
+    /** 所属情境名(L1 抽取的情境切分结果)。 */
+    scene_name: string;
+    /** auto 档抽取输出的显式族判定(chat|work;纯档 Prompt 无此字段)。
+     *  语境归族、形状不归族——避免"个人计划性事实被 work_* 形状吸走"的族错标。 */
+    family?: string;
+}
+/** 抽取输出 family 字段归一:只认 chat|work,其余(缺省/非法值)交由调用方回落。 */
+export declare function normExtractedFamily(raw: unknown): MemoryFamily | undefined;
+/** 记录族三级兜底链:会话档位强制(纯档)→ 抽取显式判定(auto)→ type 前缀推导(旧输出兜底)。 */
+export declare function resolveRecordFamily(forced: MemoryFamily | undefined, extracted: unknown, type: string): MemoryFamily;
+/** L1 持久化记录(磁盘与 DB 的权威形状;version/source_message_ids/metadata 由写入侧补默认)。 */
+export interface MemoryRecord {
+    id: string;
+    content: string;
+    type: string;
+    priority: number;
+    scene_name: string;
+    /** 合并/更新时保留的时间戳并集。 */
+    timestamps: number[];
+    createdAt: number;
+    updatedAt: number;
+    /** 每条 update/merge 合并 +1。 */
+    version?: number;
+    /** 来源消息 id(JSONL 事实源保留;检索库不存该列)。 */
+    source_message_ids?: string[];
+    /** 类型附加信息(episodic 的活动起止时间等)。 */
+    metadata?: Record<string, unknown>;
+    /** 来源会话(缺省 default;跨会话记忆共享)。 */
+    sessionId?: string;
+    /** 所属族(写入缺省由 familyForType(type) 回填;召回/浏览/去重候选按族过滤的唯一依据)。 */
+    family?: MemoryFamily;
+    /**
+     * 有效期起(epoch ms):该事实在**真实世界**开始成立的时间。
+     * 与 createdAt(入库时间)是两条不同的轴——"2026-03 在 A 项目"这条事实,
+     * createdAt 是它进库的时刻,validFrom 才是 2026-03。缺省 = 未知。
+     */
+    validFrom?: number;
+    /**
+     * 有效期止(epoch ms):该事实停止成立的时间。
+     * 为空(undefined)表示**仍在持续**(persistence='o')或**无时间性**(persistence='t'),
+     * 二者由 persistence 区分——这正是不能用"空值"当"已结束"的原因。
+     */
+    validTo?: number;
+    /** 持续性(见 Persistence);缺省 = 未判定。 */
+    persistence?: Persistence;
+}
+/** L2 场景块摘要(META 解析结果)。 */
+export interface SceneSummary {
+    path: string;
+    created: string;
+    updated: string;
+    summary: string;
+    heat: number;
+}
+/** L1 检索命中。 */
+export interface L1Hit {
+    id: string;
+    content: string;
+    type: string;
+    scene_name: string;
+    score: number;
+    priority?: number;
+    family?: MemoryFamily;
+}

package/dist/types.js

@@ -0,0 +1,38 @@
+/**
+ * 领域类型与词汇表(净室重写)。
+ *
+ * 覆盖:记忆族/档位、Hall 目录、L0/L1 记录形状、抽取产出与族判定三级兜底、
+ * L2 场景摘要与 L1 检索命中。字段名与取值是磁盘/管线两侧的既定契约,不可更名。
+ */
+export const HALL_CATALOG = [
+    { id: 'work', label: '工作' },
+    { id: 'relationships', label: '人际关系' },
+    { id: 'general', label: '通用' },
+    { id: 'finance', label: '财务', experimental: true },
+    { id: 'journey', label: '旅程', experimental: true },
+];
+/** 默认启用的 Hall id(主线 3;实验性条目要用户写进 config hall.enabled 才生效)。 */
+export const HALL_DEFAULT_ENABLED = ['work', 'relationships', 'general'];
+export function hallLabel(id) {
+    const h = HALL_CATALOG.find((x) => x.id === id);
+    return h ? h.label : id;
+}
+/** 记录族标签推断:work_* 前缀 → work,其余(含 auto 档兜底)→ chat。 */
+export function familyForType(type) {
+    return type.startsWith('work') ? 'work' : 'chat';
+}
+export const PERSISTENCE_VALUES = ['p', 's', 'o', 't'];
+/** 持续性取值归一:只认 p/s/o/t,其余(缺省/非法)返回 undefined。 */
+export function normPersistence(raw) {
+    return typeof raw === 'string' && PERSISTENCE_VALUES.includes(raw)
+        ? raw
+        : undefined;
+}
+/** 抽取输出 family 字段归一:只认 chat|work,其余(缺省/非法值)交由调用方回落。 */
+export function normExtractedFamily(raw) {
+    return raw === 'chat' || raw === 'work' ? raw : undefined;
+}
+/** 记录族三级兜底链:会话档位强制(纯档)→ 抽取显式判定(auto)→ type 前缀推导(旧输出兜底)。 */
+export function resolveRecordFamily(forced, extracted, type) {
+    return forced ?? normExtractedFamily(extracted) ?? familyForType(type);
+}

package/dist/util/context-occupancy.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 上下文占用账本:插件注入内容在当前会话上下文窗口中的启发式 token 存量。
+ *
+ * 本模块是全部占用数字的唯一算术来源(host 记账与 client 渲染共用,esbuild
+ * 将其内联进 client bundle),任何一侧不得另写算法。口径与官方
+ * @deepseek-ai/dsh-token-meter/estimate 的固定密度启发式同式:
+ *
+ *   - text 块 = ceil(chars / 4) + 4(块开销);
+ *   - 整条 user 消息(召回注入体的形态)再叠加 role overhead 4;
+ *   - 系统提示里的稳定区子片计入时不加任何 overhead——那 +8 是官方对整段
+ *     消息/整体系统提示的结构成本,切片重复计会与官方总数对不上;
+ *   - 字符数一律 JS `.length`(UTF-16 单元),与官方产出严格可比。
+ */
+/** 固定文本密度:每 4 字符记 1 token(官方 CHARS_PER_TOKEN 同值)。 */
+export declare const CHARS_PER_TOKEN = 4;
+/** 召回注入体(单 text 块 user message)的启发式 token 数。 */
+export declare function estimateInjectedMessageTokens(chars: number): number;
+/** 稳定区子片的启发式 token 数(不加结构开销,见模块头注释)。 */
+export declare function estimateStableSectionTokens(chars: number): number;
+/**
+ * 单会话占用账本(权威账本只在 host 侧;client 仅消费展示)。
+ * stockTokens = recallTokens + profileTokens 恒等式由三个迁移函数共同维护。
+ */
+export interface OccupancyLedger {
+    /** 当前估算仍在上下文窗口内的记忆存量(token)。 */
+    stockTokens: number;
+    /** 累计召回注入存留份额。 */
+    recallTokens: number;
+    /** 系统提示稳定区当前份额(OFF 使 text() 返回空时即时清零)。 */
+    profileTokens: number;
+    /** 最近一轮召回注入的增量(悬浮卡/面板"最近一次"语义)。 */
+    lastInjectTokens: number;
+    updatedAt: number;
+}
+export declare function emptyOccupancyLedger(now?: number): OccupancyLedger;
+/** 召回注入成功后的入账(失败跳过的轮次不调用——账目零扰动)。 */
+export declare function recordRecallInjection(l: OccupancyLedger, chars: number, now?: number): void;
+/**
+ * 稳定区份额随每次实际组进的文本同步(含切回非 OFF 的重新计入):
+ * 增量记账保证重复调用不双算,清零后重设即可净额回补。
+ */
+export declare function recordProfileShare(l: OccupancyLedger, chars: number, now?: number): void;
+/** OFF 边界:稳定区随下一次请求组装物理离场,账目同边界清零(宁低勿高)。 */
+export declare function clearProfileShare(l: OccupancyLedger, now?: number): void;
+/**
+ * compaction 复位:采用"清零重新累积"的低估近似——被压缩掉的注入以整数轮粒度
+ * 退出账本,幸存的摘要行不重复认领(已知限制,方向宁低勿高)。
+ */
+export declare function resetForCompaction(l: OccupancyLedger, now?: number): void;
+/**
+ * 官方上下文环周长:viewBox 14 内 r=5.5 圆(2π×5.5 ≈ 34.55751918948772),
+ * 与真机反推的官方 fill dasharray 分母逐字一致。
+ */
+export declare const CONTEXT_METER_CIRCUMFERENCE = 34.55751918948772;
+/**
+ * 光晕弧 stroke-dasharray:形状沿用官方 fill(len + 全周长 gap)。
+ * @param occupancyRatio 占窗口比 0..1(越界钳制)。
+ * @param minLen 最小可见弧长(14px 渲染下 <1 单位即亚像素不可见,真实占比常低至
+ *  0.6%≈0.2 单位——指示灯语义需要"存在即可见",精确数字归面板)。
+ */
+export declare function haloDashArray(occupancyRatio: number, circumference?: number, minLen?: number): string;
+/** 官方环触发按钮的结构签名(locale 无关定位依据)。 */
+export interface ContextMeterAnchorSignature {
+    ariaHasPopup?: string | null;
+    viewBox?: string | null;
+    circleRadii?: ReadonlyArray<number>;
+}
+export declare function isContextMeterAnchor(sig: ContextMeterAnchorSignature): boolean;

package/dist/util/context-occupancy.js

@@ -0,0 +1,92 @@
+/**
+ * 上下文占用账本:插件注入内容在当前会话上下文窗口中的启发式 token 存量。
+ *
+ * 本模块是全部占用数字的唯一算术来源(host 记账与 client 渲染共用,esbuild
+ * 将其内联进 client bundle),任何一侧不得另写算法。口径与官方
+ * @deepseek-ai/dsh-token-meter/estimate 的固定密度启发式同式:
+ *
+ *   - text 块 = ceil(chars / 4) + 4(块开销);
+ *   - 整条 user 消息(召回注入体的形态)再叠加 role overhead 4;
+ *   - 系统提示里的稳定区子片计入时不加任何 overhead——那 +8 是官方对整段
+ *     消息/整体系统提示的结构成本,切片重复计会与官方总数对不上;
+ *   - 字符数一律 JS `.length`(UTF-16 单元),与官方产出严格可比。
+ */
+/** 固定文本密度:每 4 字符记 1 token(官方 CHARS_PER_TOKEN 同值)。 */
+export const CHARS_PER_TOKEN = 4;
+const BLOCK_OVERHEAD = 4;
+const ROLE_OVERHEAD = 4;
+/** 召回注入体(单 text 块 user message)的启发式 token 数。 */
+export function estimateInjectedMessageTokens(chars) {
+    return Math.ceil(chars / CHARS_PER_TOKEN) + BLOCK_OVERHEAD + ROLE_OVERHEAD;
+}
+/** 稳定区子片的启发式 token 数(不加结构开销,见模块头注释)。 */
+export function estimateStableSectionTokens(chars) {
+    return Math.ceil(chars / CHARS_PER_TOKEN);
+}
+export function emptyOccupancyLedger(now = Date.now()) {
+    return { stockTokens: 0, recallTokens: 0, profileTokens: 0, lastInjectTokens: 0, updatedAt: now };
+}
+/** 召回注入成功后的入账(失败跳过的轮次不调用——账目零扰动)。 */
+export function recordRecallInjection(l, chars, now = Date.now()) {
+    const tokens = estimateInjectedMessageTokens(chars);
+    l.recallTokens += tokens;
+    l.stockTokens += tokens;
+    l.lastInjectTokens = tokens;
+    l.updatedAt = now;
+}
+/**
+ * 稳定区份额随每次实际组进的文本同步(含切回非 OFF 的重新计入):
+ * 增量记账保证重复调用不双算,清零后重设即可净额回补。
+ */
+export function recordProfileShare(l, chars, now = Date.now()) {
+    const tokens = estimateStableSectionTokens(chars);
+    l.stockTokens += tokens - l.profileTokens;
+    l.profileTokens = tokens;
+    l.updatedAt = now;
+}
+/** OFF 边界:稳定区随下一次请求组装物理离场,账目同边界清零(宁低勿高)。 */
+export function clearProfileShare(l, now = Date.now()) {
+    l.stockTokens -= l.profileTokens;
+    l.profileTokens = 0;
+    l.updatedAt = now;
+}
+/**
+ * compaction 复位:采用"清零重新累积"的低估近似——被压缩掉的注入以整数轮粒度
+ * 退出账本,幸存的摘要行不重复认领(已知限制,方向宁低勿高)。
+ */
+export function resetForCompaction(l, now = Date.now()) {
+    l.stockTokens = 0;
+    l.recallTokens = 0;
+    l.profileTokens = 0;
+    l.lastInjectTokens = 0;
+    l.updatedAt = now;
+}
+/* ── 渲染侧纯函数(client 寄生组件用;数字唯一来源在此) ── */
+/**
+ * 官方上下文环周长:viewBox 14 内 r=5.5 圆(2π×5.5 ≈ 34.55751918948772),
+ * 与真机反推的官方 fill dasharray 分母逐字一致。
+ */
+export const CONTEXT_METER_CIRCUMFERENCE = 34.55751918948772;
+/**
+ * 光晕弧 stroke-dasharray:形状沿用官方 fill(len + 全周长 gap)。
+ * @param occupancyRatio 占窗口比 0..1(越界钳制)。
+ * @param minLen 最小可见弧长(14px 渲染下 <1 单位即亚像素不可见,真实占比常低至
+ *  0.6%≈0.2 单位——指示灯语义需要"存在即可见",精确数字归面板)。
+ */
+export function haloDashArray(occupancyRatio, circumference = CONTEXT_METER_CIRCUMFERENCE, minLen = 0) {
+    const clamped = Number.isFinite(occupancyRatio) ? Math.min(1, Math.max(0, occupancyRatio)) : 0;
+    const len = Math.max(clamped * circumference, clamped > 0 ? minLen : 0);
+    return `${len} ${circumference}`;
+}
+/** 半径比对容差:吞掉渲染库对属性值的无害浮点噪声。 */
+const RADIUS_EPSILON = 1e-6;
+export function isContextMeterAnchor(sig) {
+    if (sig.ariaHasPopup !== 'dialog')
+        return false;
+    if (sig.viewBox !== '0 0 14 14')
+        return false;
+    const radii = sig.circleRadii;
+    if (!Array.isArray(radii) || radii.length !== 2)
+        return false;
+    return radii.every((r) => Math.abs(r - 5.5) < RADIUS_EPSILON);
+}

package/dist/util/filelog.d.ts

@@ -0,0 +1,6 @@
+import type { MemoryLogger } from '../types.js';
+/** 缓冲行数达到该值立即刷盘(未到定时器也不积压);同时是体积检查的抽样粒度。 */
+export declare const SIZE_CHECK_INTERVAL = 32;
+/** 错误对象转带堆栈的单行描述(诊断日志用,非 Error 直接字符串化)。 */
+export declare function errDetail(err: unknown): string;
+export declare function withFileLog(dataDir: string, logger: MemoryLogger): MemoryLogger;

package/dist/util/filelog.js

@@ -0,0 +1,108 @@
+/**
+ * 文件日志:dsh 宿主只把插件日志打到控制台(无持久化),这里镜像 warn/error/info
+ * 到数据目录 memory.log,供事后诊断蒸馏管线。
+ *
+ * 重写版把落盘改为异步缓冲:捕获/召回是每轮对话的热路径,逐条同步 append 在
+ * Windows+杀软环境可达毫秒级。行先进内存缓冲,定时/定量批量 appendFile(队列
+ * 串行保序);轮转与 Windows EBUSY 截断兜底语义保留。写入失败静默忽略——
+ * 诊断日志绝不能反过来拖垮管线。
+ */
+import { appendFileSync, existsSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { appendFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const MAX_LOG_BYTES = 2 * 1024 * 1024;
+/** 轮转 rename 连续失败多少次后放弃归档、直接截断重开(Windows 文件占用兜底)。 */
+const ROTATE_FAIL_LIMIT = 5;
+/** 缓冲行数达到该值立即刷盘(未到定时器也不积压);同时是体积检查的抽样粒度。 */
+export const SIZE_CHECK_INTERVAL = 32;
+/** 定时刷盘间隔(ms);unref,不阻止进程退出。 */
+const FLUSH_INTERVAL_MS = 500;
+/** 错误对象转带堆栈的单行描述(诊断日志用,非 Error 直接字符串化)。 */
+export function errDetail(err) {
+    if (err instanceof Error)
+        return `${err.message} @ ${err.stack?.split('\n')[1]?.trim() ?? err.name}`;
+    return String(err);
+}
+export function withFileLog(dataDir, logger) {
+    const logPath = join(dataDir, 'memory.log');
+    let buffer = [];
+    let rotateFailures = 0;
+    let writesSinceCheck = 0;
+    let flushing = Promise.resolve();
+    const line = (level, msg) => `${new Date().toISOString()} [${level}] ${msg}\n`;
+    const rotateIfNeeded = () => {
+        if (writesSinceCheck++ % SIZE_CHECK_INTERVAL !== 0 || !existsSync(logPath) || statSync(logPath).size <= MAX_LOG_BYTES) {
+            return;
+        }
+        try {
+            renameSync(logPath, `${logPath}.1`);
+            rotateFailures = 0;
+        }
+        catch {
+            // rename 可能因文件被占用失败(Windows EBUSY):连续失败达上限后截断重开,
+            // 保住"日志体积有上界"的底线(放弃 .1 归档,保当前日志可用)
+            if (++rotateFailures >= ROTATE_FAIL_LIMIT) {
+                writeFileSync(logPath, '');
+                rotateFailures = 0;
+            }
+        }
+    };
+    const drain = (lines) => {
+        flushing = flushing
+            .then(async () => {
+            if (lines.length === 0)
+                return;
+            rotateIfNeeded();
+            await appendFile(logPath, lines.join(''), 'utf-8');
+        })
+            .catch(() => {
+            /* ignore */
+        });
+    };
+    const flushNow = () => {
+        if (buffer.length === 0)
+            return;
+        const batch = buffer;
+        buffer = [];
+        drain(batch);
+    };
+    const timer = setInterval(flushNow, FLUSH_INTERVAL_MS);
+    timer.unref?.();
+    process.once('beforeExit', () => {
+        if (buffer.length > 0) {
+            const batch = buffer;
+            buffer = [];
+            try {
+                appendFileSync(logPath, batch.join(''), 'utf-8');
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    });
+    const write = (level, msg) => {
+        try {
+            buffer.push(line(level, msg));
+            if (buffer.length >= SIZE_CHECK_INTERVAL)
+                flushNow();
+        }
+        catch {
+            /* ignore */
+        }
+    };
+    return {
+        debug: (m) => logger.debug?.(m),
+        info: (m) => {
+            logger.info(m);
+            write('info', m);
+        },
+        warn: (m) => {
+            logger.warn(m);
+            write('warn', m);
+        },
+        error: (m) => {
+            logger.error(m);
+            write('error', m);
+        },
+    };
+}

package/dist/util/io.d.ts

@@ -0,0 +1,18 @@
+export declare function ensureDir(dir: string): Promise<void>;
+/**
+ * 原子写文本文件。tmp 写满后先 fsync 数据块再 rename——否则断电时文件系统可能
+ * 先持久化 rename 元数据、后持久化数据块(ext4 delayed allocation / NTFS 均可能),
+ * 目标文件变成空文件或半截。tmp 名带随机段防同毫秒碰撞;失败路径清理孤儿 tmp。
+ */
+export declare function atomicWriteText(file: string, content: string): Promise<void>;
+/** 原子写 JSON(两空格缩进,人工可查)。 */
+export declare function atomicWriteJson(file: string, value: unknown): Promise<void>;
+export declare function readJsonIfExists<T>(file: string): Promise<T | undefined>;
+export declare function readTextIfExists(file: string): Promise<string | undefined>;
+/** 追加 JSONL 行(存在则追加,否则创建);空数组零副作用。 */
+export declare function appendJsonl(file: string, lines: unknown[]): Promise<void>;
+/** 读取 JSONL 全部行(坏行跳过,不抛出)。 */
+export declare function readJsonl<T>(file: string): Promise<T[]>;
+export declare function nowIso(): string;
+/** 本地时区的 YYYY-MM-DD 键(L0/L1 按天分文件的文件名来源)。 */
+export declare function dayKey(ts: number): string;

package/dist/util/io.js

@@ -0,0 +1,97 @@
+/**
+ * 持久化工具:原子写(tmp + fsync + rename)与 JSON/JSONL 读写。
+ *
+ * JSONL 追加是热路径(每轮对话一次),走 OS 写回不加 fsync——逐条 fsync 的延迟
+ * 代价大于崩溃窗口丢尾部几行的损失;状态文件则必须原子写,防半截状态。
+ */
+import { randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+export async function ensureDir(dir) {
+    await fs.mkdir(dir, { recursive: true });
+}
+/**
+ * 原子写文本文件。tmp 写满后先 fsync 数据块再 rename——否则断电时文件系统可能
+ * 先持久化 rename 元数据、后持久化数据块(ext4 delayed allocation / NTFS 均可能),
+ * 目标文件变成空文件或半截。tmp 名带随机段防同毫秒碰撞;失败路径清理孤儿 tmp。
+ */
+export async function atomicWriteText(file, content) {
+    await ensureDir(path.dirname(file));
+    const tmp = `${file}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+    try {
+        await fs.writeFile(tmp, content, 'utf-8');
+        const fh = await fs.open(tmp, 'r+');
+        try {
+            await fh.sync();
+        }
+        finally {
+            await fh.close();
+        }
+        await fs.rename(tmp, file);
+    }
+    catch (err) {
+        await fs.unlink(tmp).catch(() => { });
+        throw err;
+    }
+}
+/** 原子写 JSON(两空格缩进,人工可查)。 */
+export async function atomicWriteJson(file, value) {
+    await atomicWriteText(file, JSON.stringify(value, null, 2));
+}
+export async function readJsonIfExists(file) {
+    try {
+        const raw = await fs.readFile(file, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function readTextIfExists(file) {
+    try {
+        return await fs.readFile(file, 'utf-8');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 追加 JSONL 行(存在则追加,否则创建);空数组零副作用。 */
+export async function appendJsonl(file, lines) {
+    if (lines.length === 0)
+        return;
+    await ensureDir(path.dirname(file));
+    const payload = lines.map((l) => JSON.stringify(l)).join('\n') + '\n';
+    await fs.appendFile(file, payload, 'utf-8');
+}
+/** 读取 JSONL 全部行(坏行跳过,不抛出)。 */
+export async function readJsonl(file) {
+    try {
+        const raw = await fs.readFile(file, 'utf-8');
+        const out = [];
+        for (const line of raw.split('\n')) {
+            const t = line.trim();
+            if (!t)
+                continue;
+            try {
+                out.push(JSON.parse(t));
+            }
+            catch {
+                // 跳过坏行
+            }
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+export function nowIso() {
+    return new Date().toISOString();
+}
+/** 本地时区的 YYYY-MM-DD 键(L0/L1 按天分文件的文件名来源)。 */
+export function dayKey(ts) {
+    const d = new Date(ts);
+    const mm = String(d.getMonth() + 1).padStart(2, '0');
+    const dd = String(d.getDate()).padStart(2, '0');
+    return `${d.getFullYear()}-${mm}-${dd}`;
+}

package/dist/util/recall-budget.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 召回预算与超时(ADR-0001 / 规格 A 节)。
+ *
+ * 预算:单条记忆截断上限 + 整轮总量上限——超限截断并以后缀引导模型用记忆工具
+ * 查全文(截断是引流而不是损失:工具路径返回完整记录);总量超限按融合排名丢尾部。
+ * 超时:召回是增强能力,超时跳过本轮注入、绝不阻塞对话(CONTEXT.md「召回超时」语义
+ * 在本模块以 raceRecallTimeout 落地)。
+ */
+/** 截断后缀:显式告诉模型全文在工具侧(引导主动深挖)。注入字符串,逐字为契约。 */
+export declare const RECALL_TRUNCATION_SUFFIX = "\u2026(\u5DF2\u622A\u65AD;\u53EF\u7528 memory_search \u6216 conversation_search \u67E5\u770B\u8BE6\u60C5)";
+export interface RecallBudgetLimits {
+    /** 单条记忆注入长度上限(字符);0 = 不限。 */
+    maxCharsPerMemory: number;
+    /** 整轮注入总量上限(字符);0 = 不限。超限时低分(排名靠后)尾部先丢。 */
+    maxTotalRecallChars: number;
+}
+/** 按 code point 计数截断(不劈开代理对),带引导后缀。 */
+export declare function truncateRecallLine(line: string, maxChars: number): string;
+/**
+ * 对召回行施加预算:先逐条截断,再按总量预算装填——装不下的尾部整条丢弃。
+ * 输入行应按相关性降序(低分先丢)。行间换行符计入总量预算。
+ */
+export declare function applyRecallBudget(lines: string[], limits: RecallBudgetLimits): string[];
+/**
+ * 召回总预算:超时返回 undefined(调用方跳过本轮注入),正常 resolve 返回原值。
+ * resolve 为空结果(空数组)与超时(undefined)语义不同,调用方据此区分日志。
+ */
+export declare function raceRecallTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T | undefined>;
+/** 召回路径嵌入调用的内层钳制(固定值):给 FTS 降级留出总预算内的时间。
+ *  远程作用于 HTTP fetch;本地作用于 worker 代理的等待(race 放弃、迟到回复丢弃)。 */
+export declare const RECALL_EMBED_CAP_MS = 3000;