dsh-prime-memory 0.18.2 → 0.18.5

package/dist/store/trace.js

@@ -0,0 +1,149 @@
+/**
+ * §F 结构化追踪(memorax-absorb Wave 4 / task_28)——recall/distill 事件流。
+ *
+ * 模块级单例(token-cost.ts 同款):trace() 埋点拿不到 store 实例(store 在
+ * index.ts 运行时才有 dataDir),initTraceStore 启动时注入;未初始化或
+ * trace.enabled=false 时 trace() 为零副作用 no-op。
+ *
+ * 存储:按天 JSONL(`dataDir/trace/trace-YYYY-MM-DD.jsonl`,appendJsonl 原语),
+ * 文件名即日期 → 保留期清理在切日时触发(删除超 retentionDays 的旧文件);
+ * 单文件 >5MB 停写 + 写入一行 trace_truncated marker(防无限增长);
+ * 写失败静默(filelog 同款纪律——追踪绝不影响主链路)。
+ *
+ * 隐私默认 metadata-only:recall 事件只带 queryChars+querySha,
+ * captureContent=true 才存 queryText(截断 200)——由埋点方决定字段,本模块不感知。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { appendJsonl, dayKey, readJsonl } from '../util/io.js';
+const TRACE_DIR = 'trace';
+const DEFAULT_MAX_FILE_BYTES = 5 * 1024 * 1024;
+export class TraceStore {
+    dataDir;
+    opts;
+    /** 已停写的日期(5MB 上限触发;当日内后续事件丢弃,次日自动恢复)。 */
+    truncatedDays = new Set();
+    lastPruneDay = '';
+    chain = Promise.resolve();
+    constructor(dataDir, opts) {
+        this.dataDir = dataDir;
+        this.opts = opts;
+    }
+    /** 追加事件(异步串行链,失败静默)。 */
+    append(event) {
+        const day = dayKey(event.ts);
+        if (this.truncatedDays.has(day))
+            return;
+        this.chain = this.chain
+            .then(() => this.writeOne(day, event))
+            .catch(() => {
+            /* 静默:追踪失败不影响主链路 */
+        });
+    }
+    /** 等待挂起的写入排空(dispose 序用)。 */
+    flush() {
+        return this.chain;
+    }
+    /**
+     * 尾部读取:从最近的日期文件倒序收集,按 kind 过滤,返回至多 `lines` 条
+     * (按写入顺序 = 时间升序)。坏行跳过(readJsonl 同款)。
+     */
+    async tail(lines, kind) {
+        const limit = Math.max(1, Math.min(500, Math.round(lines) || 100));
+        const files = this.recentFiles();
+        const collected = [];
+        for (let i = files.length - 1; i >= 0 && collected.length < limit; i--) {
+            const rows = await readJsonl(files[i]);
+            for (let j = rows.length - 1; j >= 0 && collected.length < limit; j--) {
+                const row = rows[j];
+                if (!row || typeof row !== 'object' || !row.kind)
+                    continue;
+                if (kind && row.kind !== kind)
+                    continue;
+                collected.push(row);
+            }
+        }
+        return collected.reverse();
+    }
+    dir() {
+        return path.join(this.dataDir, TRACE_DIR);
+    }
+    fileFor(day) {
+        return path.join(this.dir(), `trace-${day}.jsonl`);
+    }
+    recentFiles() {
+        try {
+            return fs
+                .readdirSync(this.dir())
+                .filter((f) => f.startsWith('trace-') && f.endsWith('.jsonl'))
+                .sort()
+                .map((f) => path.join(this.dir(), f));
+        }
+        catch {
+            return [];
+        }
+    }
+    async writeOne(day, event) {
+        if (day !== this.lastPruneDay) {
+            this.lastPruneDay = day;
+            this.pruneOldDays(day);
+        }
+        const file = this.fileFor(day);
+        try {
+            const stat = await fs.promises.stat(file);
+            if (stat.size > (this.opts.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES)) {
+                this.truncatedDays.add(day);
+                await appendJsonl(file, [
+                    { kind: 'trace_truncated', ts: event.ts, note: '单日文件超上限,当日停写(次日自动恢复)' },
+                ]);
+                return;
+            }
+        }
+        catch {
+            /* 文件不存在 = 首写,继续 */
+        }
+        await appendJsonl(file, [event]);
+    }
+    /** 删除超过保留期的旧日文件(retentionDays 0 = 永久)。 */
+    pruneOldDays(today) {
+        if (this.opts.retentionDays <= 0)
+            return;
+        let files;
+        try {
+            files = fs.readdirSync(this.dir());
+        }
+        catch {
+            return;
+        }
+        const todayMs = Date.parse(`${today}T00:00:00`);
+        for (const f of files) {
+            const m = /^trace-(\d{4}-\d{2}-\d{2})\.jsonl$/.exec(f);
+            if (!m)
+                continue;
+            const dayMs = Date.parse(`${m[1]}T00:00:00`);
+            if (!Number.isFinite(dayMs) || !Number.isFinite(todayMs))
+                continue;
+            if (todayMs - dayMs > this.opts.retentionDays * 86_400_000) {
+                fs.promises.rm(path.join(this.dir(), f), { force: true }).catch(() => { });
+            }
+        }
+    }
+}
+// ── 模块级单例(token-cost.ts 同款) ──
+let store = null;
+/** 插件启动时注入(index.ts 调用);enabled=false 或 0 天保留不影响初始化本身。 */
+export function initTraceStore(dataDir, opts) {
+    store = new TraceStore(dataDir, opts);
+}
+/** 测试/卸载:清空单例。 */
+export function resetTraceStore() {
+    store = null;
+}
+/** 埋点入口:未初始化 = no-op。fire-and-forget,永不抛。 */
+export function trace(event) {
+    store?.append(event);
+}
+/** RPC tail 数据源;未初始化返回 undefined(端点回空集)。 */
+export function getTraceStore() {
+    return store;
+}

package/dist/tools/index.d.ts

@@ -22,6 +22,7 @@ import type { PersonaStore } from '../store/persona.js';
 import type { SceneStore } from '../store/scenes.js';
 import type { SessionModeStore } from '../store/session-modes.js';
 import type { MemoryFamily, MemoryLogger } from '../types.js';
+import type { RoomRegistryStore } from '../store/rooms-registry.js';
 export declare function registerMemoryTools(ctx: Context, cfg: MemoryConfig, stores: {
     l0: L0Store;
     l1: L1Store;
@@ -31,4 +32,6 @@ export declare function registerMemoryTools(ctx: Context, cfg: MemoryConfig, sto
     graph?: GraphStore;
 }, logger: MemoryLogger, modes: SessionModeStore, live: LiveSettingsHandle, 
 /** 反刍控制器(可选:未装配时 ruminate 工具返回未启用提示)。 */
-ruminate?: RuminateController): void;
+ruminate?: RuminateController, 
+/** Room 注册表(分类管理 beta.4;缺省 = memory_room_admin 返回未装配提示)。 */
+roomRegistry?: RoomRegistryStore): void;

package/dist/tools/index.js

@@ -3,13 +3,37 @@ import { RECEIPTS_QUERY_LIMIT_MAX, dimensionOf, toReceiptView } from '../store/r
 import { listConflictPairs, renderConflictResolution, renderConflicts, resolveConflictPair } from '../conflict-service.js';
 import { WING_CATALOG, WING_FALLBACK, normPersistence, normScope, resolveRecordScope } from '../types.js';
 import { scopeFilterOf, workspaceIdOf } from '../workspace.js';
+import { annotateOrphanCandidates, confirmReview, mergeRoom, nextReview, pendingReviewCount, renameRoom, skipReview, } from '../room-review.js';
 import { GRAPH_STATUS_LABELS } from '../prompts/graph-projection.js';
+import { redactSecrets } from '../util/redact.js';
 const OFF_NOTICE = '本会话的记忆档位为"关闭":该会话对记忆系统完全隐身,不读取也不写入记忆。';
 const WRITE_ONLY_NOTICE = '本会话为只写模式:记忆照常沉淀,但不读取。';
 const GLOBAL_OFF_NOTICE = '记忆注入已全局停用:本会话不读取记忆(沉淀照常)。';
+/** §C 一次性告警标记:手动写入路径的脱敏失败只提示一次(不阻断写入)。 */
+let manualRedactWarnedOnce = false;
+/**
+ * §C 手动写入路径脱敏(memorax-absorb / task_18):memory_add / memory_import
+ * 与捕获路径走同一 8 类词表,两条 L1 写入边界语义一致。
+ * 红线:脱敏失败放行原文 + 一次性 warn(不阻断写入)。
+ */
+function applyManualRedaction(record, cfg, logger) {
+    if (cfg.capture?.redactSecrets === false)
+        return;
+    try {
+        record.content = redactSecrets(record.content).text;
+    }
+    catch (err) {
+        if (!manualRedactWarnedOnce) {
+            manualRedactWarnedOnce = true;
+            logger.warn(`[memory] 手动写入脱敏失败,放行原文(一次性提示): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
 export function registerMemoryTools(ctx, cfg, stores, logger, modes, live, 
 /** 反刍控制器(可选:未装配时 ruminate 工具返回未启用提示)。 */
-ruminate) {
+ruminate, 
+/** Room 注册表(分类管理 beta.4;缺省 = memory_room_admin 返回未装配提示)。 */
+roomRegistry) {
     if (!cfg.tools)
         return;
     /**
@@ -147,6 +171,145 @@ ruminate) {
             };
         },
     }));
+    // ── memory_room_admin: Room 粒度目录治理(分类管理 beta.4;beta.5 起 merge/rename/retire 已注册) ──
+    // list 免预算零风险;merge/rename/retire 走 dryRun 预览→实跑,执行前自动备份,完成入队场景重算。
+    ctx.tools.register(defineTool({
+        name: 'memory_room_admin',
+        description: 'Room 分类管理(目录粒度)。action="list" 列出注册表条目与自生长 Room 计数;' +
+            'action="register" 预注册一个 Room(高权限;两级制——大类上限 200,小类用「大类/小类」细分不占额度,如 dsh-plugin/merge;' +
+            'action="merge" 合并两个 Room(高权限;dryRun 默认 true 只返预览,实跑改写全部匹配记录的 tags 并入队场景重算,执行前自动备份);' +
+            'action="rename" 改名(= merge 1:1 + 注册表改名);action="retire" 退役一个注册 Room(高权限;存量记录不动)。' +
+            'merge/rename 与反刍并发会相互覆盖,请在反刍空闲时执行。',
+        parameters: {
+            action: { type: 'string', required: true, description: 'list | register(高权限) | merge(高权限) | rename(高权限) | retire(高权限)' },
+            slug: { type: 'string', description: 'register 的 Room slug(小写字母数字连字符)' },
+            label: { type: 'string', description: 'register 的人类可读名(可选,可中文)' },
+            description: { type: 'string', description: 'register 的归类说明(可选;喂给标注器帮助归类)' },
+            from: { type: 'string', description: 'merge/rename 的源 Room slug' },
+            to: { type: 'string', description: 'merge/rename 的目标 Room slug' },
+            dryRun: { type: 'string', description: 'merge/rename:默认 true 只返预览;"false" 才实际执行' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                properties: {
+                    notice: { type: 'string' },
+                    rooms: { type: 'string' },
+                    slug: { type: 'string' },
+                    created: { type: 'boolean' },
+                },
+                additionalProperties: false,
+            },
+            render: (_args, value) => [{ type: 'text', text: value.notice ?? JSON.stringify(value) }],
+        },
+        execute: async (args) => {
+            const action = String(args.action ?? '');
+            if (action === 'list') {
+                if (!roomRegistry)
+                    return { notice: 'Room 注册表未装配(需要插件重载以初始化)。' };
+                const registry = roomRegistry.list();
+                const counts = stores.l1.listRooms();
+                const countOf = (slug) => counts.find((r) => r.room === slug)?.count ?? 0;
+                const regLines = registry.map((e) => `- ${e.slug}${e.label ? `(${e.label})` : ''} [${e.source}/${e.status}] 现有 ${countOf(e.slug)} 条${e.description ? ` — ${e.description}` : ''}`);
+                const grownOnly = counts.filter((r) => !registry.some((e) => e.slug === r.room));
+                return {
+                    notice: `注册表 ${registry.length} 条(上限 200),自生长未注册 ${grownOnly.length} 个。\n` +
+                        (regLines.join('\n') || '(注册表为空——用 action=register 预注册)') +
+                        `\n自生长未注册:${grownOnly.map((r) => `${r.room}(${r.count})`).join(", ") || "无"}`,
+                    rooms: `${registry.length}+${grownOnly.length}`,
+                };
+            }
+            if (action === 'register') {
+                if (!roomRegistry)
+                    return { notice: 'Room 注册表未装配(需要插件重载以初始化)。' };
+                if (!live.get().memoryMutate)
+                    return { notice: MUTATE_OFF_NOTICE };
+                const slug = String(args.slug ?? '').trim();
+                try {
+                    const r = await roomRegistry.register({
+                        slug,
+                        label: typeof args.label === 'string' ? args.label : undefined,
+                        description: typeof args.description === 'string' ? args.description : undefined,
+                    });
+                    return {
+                        notice: r.created
+                            ? `已预注册 Room:${r.entry.slug}${r.entry.label ? `(${r.entry.label})` : ''}。候选标注器将优先把相关记忆挂到它上面。`
+                            : `Room 已存在:${r.entry.slug}(本次只补全了缺失的 label/description)。`,
+                        slug: r.entry.slug,
+                        created: r.created,
+                    };
+                }
+                catch (err) {
+                    return { notice: `注册失败: ${err instanceof Error ? err.message : String(err)}` };
+                }
+            }
+            if (action === 'update') {
+                if (!roomRegistry)
+                    return { notice: 'Room 注册表未装配(需要插件重载以初始化)。' };
+                if (!live.get().memoryMutate)
+                    return { notice: MUTATE_OFF_NOTICE };
+                const slug = String(args.slug ?? '').trim();
+                if (!slug)
+                    return { notice: 'update 需要 slug。' };
+                try {
+                    const ok = await roomRegistry.update(slug, {
+                        label: typeof args.label === 'string' ? args.label : undefined,
+                        description: typeof args.description === 'string' ? args.description : undefined,
+                    });
+                    return { notice: ok ? `已更新:${slug}(显示名/归类说明)。` : `无变化:${slug} 未找到或未提供非空字段。`, slug };
+                }
+                catch (err) {
+                    return { notice: `更新失败: ${err instanceof Error ? err.message : String(err)}` };
+                }
+            }
+            if (action === 'merge' || action === 'rename') {
+                if (!roomRegistry)
+                    return { notice: 'Room 注册表未装配(需要插件重载以初始化)。' };
+                if (!live.get().memoryMutate)
+                    return { notice: MUTATE_OFF_NOTICE };
+                const from = String(args.from ?? '').trim();
+                const to = String(args.to ?? '').trim();
+                if (!from || !to)
+                    return { notice: 'merge/rename 需要 from 与 to 两个 slug。' };
+                const dryRun = String(args.dryRun ?? 'true').toLowerCase() !== 'false';
+                try {
+                    const fn = action === 'merge' ? mergeRoom : renameRoom;
+                    const r = await fn({ l1: stores.l1, registry: roomRegistry, logger }, from, to, { dryRun });
+                    if (r.dryRun) {
+                        return {
+                            notice: `[dryRun 预览] ${from} → ${to}:影响 ${r.affected} 条${r.hasMore ? '(超过单次上限,需续跑)' : ''}。` +
+                                `样例:${r.preview.join(', ') || '无'}。确认无误后以 dryRun="false" 执行(执行前自动备份,重写含已退场行,完成后自动入队场景重算)。`,
+                            affected: r.affected,
+                        };
+                    }
+                    return {
+                        notice: `${action === 'merge' ? '合并' : '改名'}完成:${from} → ${to},重写 ${r.applied} 条` +
+                            `(备份:${r.backupFile ?? '无'})。`,
+                        applied: r.applied,
+                        id: to,
+                    };
+                }
+                catch (err) {
+                    return { notice: `${action} 失败: ${err instanceof Error ? err.message : String(err)}` };
+                }
+            }
+            if (action === 'retire') {
+                if (!roomRegistry)
+                    return { notice: 'Room 注册表未装配(需要插件重载以初始化)。' };
+                if (!live.get().memoryMutate)
+                    return { notice: MUTATE_OFF_NOTICE };
+                const slug = String(args.slug ?? '').trim();
+                try {
+                    const ok = await roomRegistry.setStatus(slug, 'retired');
+                    return { notice: ok ? `已退役 Room:${slug}(存量记录的 tags 不动,仅词表不再推荐)。` : `未找到注册条目:${slug}(自生长 Room 无需退役,会随 tags 自然消失)。`, slug };
+                }
+                catch (err) {
+                    return { notice: `退役失败: ${err instanceof Error ? err.message : String(err)}` };
+                }
+            }
+            return { notice: `非法 action:${action}(允许 list/register/merge/rename/retire)。` };
+        },
+    }));
     // ── conversation_search: L0 原始对话 ──
     ctx.tools.register(defineTool({
         name: 'conversation_search',
@@ -362,6 +525,7 @@ ruminate) {
                 return { notice: 'content 为空,未写入' };
             const scene = typeof args.scene === 'string' && args.scene.trim() ? args.scene.trim().slice(0, 120) : '__manual__';
             const record = buildRecord(args, scene, Date.now(), workspaceIdOf(exec));
+            applyManualRedaction(record, cfg, logger);
             await stores.l1.appendNew([record]);
             logger.info(`[memory] 高权限写入记忆(${record.type}${record.metadata?.hall ? '/' + String(record.metadata.hall) : ''},时间轴 ${record.persistence ?? '?'}):${record.content.slice(0, 120)}`);
             return { id: record.id };
@@ -455,7 +619,9 @@ ruminate) {
                     return;
                 }
                 seen.add(key);
-                records.push(buildRecord(item, scene, now, workspaceIdOf(exec)));
+                const record = buildRecord(item, scene, now, workspaceIdOf(exec));
+                applyManualRedaction(record, cfg, logger);
+                records.push(record);
             });
             if (records.length > 0)
                 await stores.l1.appendNew(records);
@@ -740,6 +906,87 @@ ruminate) {
         },
     }));
     // ── 反刍状态查询(查看当前反刍进度) ──
+    // ── memory_room_review:孤儿记忆的 Room 候选逐个复查(agent 长尾治理)──────
+    // next/annotate 只读或预算内标注(无需门);confirm/skip 改写 metadata,
+    // confirm 吃 live.memoryMutate 高权限门(与 memory_delete 同款)。
+    ctx.tools.register(defineTool({
+        name: 'memory_room_review',
+        description: '孤儿记忆(无 Room 绑定)的逐个复查:action="next" 取下一条待复查记录(带系统预标记的候选 Room 与现有词表,agent 依据记录内容判定);' +
+            'action="confirm" 按 id 把 1-3 个 Room slug 写入该记忆(高权限);action="skip" 跳过(不再进队列);' +
+            'action="annotate" 立即对一批孤儿做候选预标记(平时由反刍自动推进)。建议长会话空闲时逐个过,保持分类收敛——优先挂靠现有 Room。',
+        parameters: {
+            action: { type: 'string', required: true, description: 'next(取下一条)| confirm(确认写入)| skip(跳过)| annotate(批量预标记)' },
+            id: { type: 'string', description: 'confirm/skip 的目标记录 id(action=next 返回的 id)' },
+            rooms: { type: 'string', description: 'confirm 的 Room slug 列表(逗号分隔,1-3 个,小写字母数字连字符;可含词表外新 slug)' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                properties: {
+                    notice: { type: 'string' },
+                    id: { type: 'string' },
+                    content: { type: 'string' },
+                    candidates: { type: 'string' },
+                    roomCatalog: { type: 'string' },
+                    remaining: { type: 'number' },
+                    confirmedTags: { type: 'string' },
+                    annotated: { type: 'number' },
+                    deferred: { type: 'number' },
+                },
+                additionalProperties: false,
+            },
+            render: (_args, value) => [{ type: 'text', text: value.notice ?? JSON.stringify(value) }],
+        },
+        execute: async (args) => {
+            const action = String(args.action ?? '');
+            const io = { l1: stores.l1, logger };
+            if (action === 'next') {
+                const item = nextReview(io.l1);
+                if (!item)
+                    return { notice: '没有待复查的孤儿记忆(roomCandidates 队列为空)。可用 action=annotate 先做一轮候选预标记。' };
+                return {
+                    id: item.id,
+                    content: item.content,
+                    candidates: item.candidates.join(', '),
+                    roomCatalog: item.roomCatalog.map((r) => `${r.room}(${r.count})`).join(', '),
+                    remaining: item.remaining,
+                };
+            }
+            if (action === 'annotate') {
+                const r = await annotateOrphanCandidates(ctx, cfg, { ...io, registry: roomRegistry }, 40);
+                return {
+                    notice: `候选预标记完成:选中 ${r.selected} 条,产候选 ${r.candidates} 条,写 pending ${r.written} 条。用 action=next 逐个复查。`,
+                    annotated: r.candidates,
+                    deferred: r.selected - r.written,
+                };
+            }
+            if (action === 'confirm') {
+                if (!live.get().memoryMutate)
+                    return { notice: MUTATE_OFF_NOTICE };
+                const id = String(args.id ?? '').trim();
+                if (!id)
+                    return { notice: 'confirm 需要 id(action=next 返回的 id)。' };
+                const rooms = String(args.rooms ?? '')
+                    .split(/[,,、]/)
+                    .map((x) => x.trim())
+                    .filter(Boolean);
+                if (rooms.length === 0)
+                    return { notice: 'confirm 需要 rooms(逗号分隔的 1-3 个 Room slug)。' };
+                const r = confirmReview(io.l1, id, rooms);
+                if (!r)
+                    return { notice: `确认失败:id=${id} 不存在、已被确认过、或 rooms 全部非法(需 1-3 个合法 slug)。` };
+                return { notice: `已挂到 Room:${r.tags.join(', ')}(面板下一次刷新即可见)。`, confirmedTags: r.tags.join(', '), id };
+            }
+            if (action === 'skip') {
+                const id = String(args.id ?? '').trim();
+                if (!id)
+                    return { notice: 'skip 需要 id。' };
+                const ok = skipReview(io.l1, id);
+                return { notice: ok ? `已跳过 ${id}(不再进复查队列)。` : `跳过失败:id=${id} 不存在。`, id };
+            }
+            return { notice: `非法 action:${action}(允许 next/confirm/skip/annotate)。剩余待复查 ${pendingReviewCount(stores.l1)} 条。` };
+        },
+    }));
     ctx.tools.register(defineTool({
         name: 'memory_ruminate_status',
         description: '查询当前记忆反刍的状态与进度(是否运行中、当前阶段、已完成/总会话数等)。\n\n注意:在 DSH Web GUI 的对话中无法直接调用此工具,因为模型可调用工具列表不包含 ruminate_status。如需查询进度,请在记忆库面板的蒸馏面板查看。',

package/dist/types.d.ts

@@ -41,6 +41,10 @@ export interface RoomCount {
     room: string;
     /** 该 Room 下的记录数(与 `wingL1Counts()` 同口径:含 retired 行)。 */
     count: number;
+    /** 来源标示(rooms-get 端点层合并注册表后附带;'grown' = 自生长,可缺省)。 */
+    source?: 'pre-registered' | 'grown';
+    /** 人类可读名(注册表条目才有;面板 chip 可用 label 展示)。 */
+    label?: string;
 }
 /** 记录族标签推断:work_* 前缀 → work,其余(含 auto 档兜底)→ chat。 */
 export declare function familyForType(type: string): MemoryFamily;

package/dist/util/redact.d.ts

@@ -0,0 +1,27 @@
+/**
+ * §C 载荷脱敏(memorax-absorb Wave 2 / task_14)——捕获边界的密钥擦除。
+ *
+ * 用户在对话里贴入的密钥(PEM/Bearer/JWT/Cookie/厂商 API key/邮箱/长号/高熵 ID)
+ * 若原样进 L0/L1,会被逐轮召回注入上下文并在 UI 展示。本模块在捕获单点把它们
+ * 替换为类型化占位符 `[REDACTED:<KIND>]`——占位符保留类别语义,关键词检索仍可命中。
+ *
+ * 词表/正则/allowlist/span 合并算法以 memorax `payload-redaction.ts` 为基准逐条移植
+ * (全文快照见计划 evidence/payload-redaction-snapshot.ts;findings.md 有等价内联)。
+ *
+ * 契约(sanitize 同款,tests/redact.test.ts 钉住):
+ * - 纯函数,零 I/O 零时钟零随机;输入原样返回(未命中)= 引用不变无关紧要,字符串不可变;
+ * - **幂等**:已是 `[REDACTED:KIND]` 的值不会被二次匹配;
+ * - 安全值 allowlist 命中不脱(`example`/`change-me`/`$VAR`/`${{…}}` 等);
+ * - 本函数**永不抛错**的保证由调用方 try/catch 兜底(capture 接线层,§C 红线:失败放行原文)。
+ */
+export type RedactionKind = 'PRIVATE_KEY' | 'AUTH_TOKEN' | 'COOKIE' | 'API_KEY' | 'CREDENTIAL' | 'EMAIL' | 'LONG_NUMBER' | 'OPAQUE_ID';
+export interface RedactionResult {
+    text: string;
+    counts: Partial<Record<RedactionKind, number>>;
+    redacted: boolean;
+}
+/**
+ * 对文本执行 8 类脱敏。规则各自扫描 → 收集值级 span → 合并重叠 → 重拼插入占位符。
+ * 同一位置被多条规则命中时取更长/更高优先级的 span。
+ */
+export declare function redactSecrets(text: string): RedactionResult;