dsh-prime-memory 0.21.0 → 0.22.2

package/dist/memport/format.js

@@ -0,0 +1,305 @@
+/**
+ * MMF v1.1 记忆包解析 / 序列化（轨3 宿主侧纯 TS 实现，零 IO）。
+ *
+ * 与 `skills/memport/scripts/memport.py` 是**同一格式的两份实现**：Python 侧供无 DSH
+ * 环境下导出用，本模块供 DSH 宿主侧导入 pre-check / 预筛用。二者必须产出一致的
+ * 结构校验结论与哈希——`tests/memport-ts-consistency.test.ts` 用 `templates/example.mem`
+ * 头部声明的 sha256(`af1247329ce5`) 做**跨实现金标准**钉死这一点。
+ *
+ * 刻意零 IO：解析入参是字符串（调用方自己读文件/请求体），便于单测且不碰文件系统。
+ * 逐字段语义见 `references/format.md`；四轴时间(created/updated/vf/vt)、持续性 st
+ * 的判定不可互相顶替（见 SKILL §四）。
+ */
+import { createHash } from 'node:crypto';
+/** MMF v1.1 默认列序（缺 `#cols=` 时按此解析；v1 包缺 vf/vt/st 列按 -/-/? 补齐）。 */
+export const DEFAULT_COLS = ['type', 'created', 'updated', 'vf', 'vt', 'st', 'cf', 'rw', 'tags', 'content'];
+/** 类型码 → 运行时 type（与 memport.py TYPE_CODES 一字不差）。 */
+export const TYPE_CODES = {
+    pe: 'persona',
+    ep: 'episodic',
+    in: 'instruction',
+    wf: 'work_fact',
+    wt: 'work_task',
+    wm: 'work_method',
+    wa: 'work_artifact',
+};
+const TYPE_FULL = Object.fromEntries(Object.entries(TYPE_CODES).map(([k, v]) => [v, k]));
+/** 持续性取值域：p 时点 / s 已结束区间 / o 仍在持续 / t 无时间性 / ? 未判定。 */
+export const PERSISTENCE = ['p', 's', 'o', 't', '?'];
+/** 支持的包版本（其余报错）。 */
+const KNOWN_VERSIONS = new Set(['1', 'v1', '1.1', 'v1.1']);
+/** NFKC + 空白折叠 + 去首尾（用于哈希与相似度，不改原文）。 */
+export function normText(s) {
+    return s.normalize('NFKC').replace(/\s+/g, ' ').trim();
+}
+/**
+ * 内容哈希：sha256(normText + 小写)[:16]。
+ * 注意：Python 用 casefold（激进大小写折叠），JS 用 toLowerCase；
+ * 对 CJK/ASCII 记忆正文等价，仅极端 Unicode 有别——实际记忆集不含此类，
+ * 跨实现金标准走包级 sha256（不逐条折叠），不受影响。
+ */
+export function contentHash(s) {
+    return createHash('sha256').update(normText(s).toLowerCase(), 'utf8').digest('hex').slice(0, 16);
+}
+/** 记录稳定 id：`mp_` + sha256(src|chash)[:16]。 */
+export function recordId(src, chash) {
+    return 'mp_' + createHash('sha256').update(`${src}|${chash}`, 'utf8').digest('hex').slice(0, 16);
+}
+/** 解码内容列：反斜杠+反斜杠 → 单反斜杠；反斜杠+n → 换行（其余反斜杠原样）。 */
+export function unescapeContent(s) {
+    let out = '';
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (c === '\\' && i + 1 < s.length) {
+            const nxt = s[i + 1];
+            if (nxt === '\\') {
+                out += '\\';
+                i++;
+                continue;
+            }
+            if (nxt === 'n') {
+                out += '\n';
+                i++;
+                continue;
+            }
+        }
+        out += c;
+    }
+    return out;
+}
+/**
+ * 编码内容列：反斜杠 → 双反斜杠、CRLF → LF、LF → 反斜杠+n。
+ * 用 charCode 常量而非控制字符字面量，避免跨工具写盘时 CR/LF 被吞进正则/字符串字面量。
+ */
+export function escapeContent(s) {
+    const CR = String.fromCharCode(13);
+    const LF = String.fromCharCode(10);
+    const BSL = String.fromCharCode(92);
+    return s.split(BSL).join(BSL + BSL).split(CR + LF).join(LF).split(LF).join(BSL + 'n');
+}
+/** `k:v;k:v` → 对象（缺冒号的段忽略）。 */
+export function parseTags(raw) {
+    const out = {};
+    for (const part of (raw || '').split(';')) {
+        const p = part.trim();
+        if (!p || !p.includes(':'))
+            continue;
+        const idx = p.indexOf(':');
+        out[p.slice(0, idx).trim()] = p.slice(idx + 1).trim();
+    }
+    return out;
+}
+/** 时间串 → { ms|null, precision }（镜像 Python parse_time；naive 视为本地）。 */
+export function parseTime(raw) {
+    const s = (raw || '').trim();
+    if (s === '' || s === '-' || s === '?' || s === 'null')
+        return { ms: null, precision: 'unknown' };
+    const patterns = [
+        [/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?$/, 'exact'],
+        [/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?:Z|[+-]\d{2}:?\d{2})?$/, 'minute'],
+        [/^\d{4}-\d{2}-\d{2}[ ]\d{2}:\d{2}:\d{2}$/, 'exact'],
+        [/^\d{4}-\d{2}-\d{2}[ ]\d{2}:\d{2}$/, 'minute'],
+        [/^\d{4}-\d{2}-\d{2}$/, 'day'],
+    ];
+    for (const [re, prec] of patterns) {
+        if (re.test(s)) {
+            const iso = s.includes('T') ? s : s.replace(' ', 'T');
+            const t = Date.parse(iso);
+            if (Number.isFinite(t))
+                return { ms: t, precision: prec };
+        }
+    }
+    return { ms: null, precision: 'unknown' };
+}
+/** 按 Python str.split(sep, maxsplit) 语义切列：前 maxsplit 个分隔符切，剩余归最后一列。 */
+function splitMax(line, maxSplit) {
+    const out = [];
+    let start = 0;
+    for (let i = 0; i < maxSplit; i++) {
+        const idx = line.indexOf('|', start);
+        if (idx === -1)
+            break;
+        out.push(line.slice(start, idx));
+        start = idx + 1;
+    }
+    out.push(line.slice(start));
+    return out;
+}
+/**
+ * 解析整包文本 → Bundle（含结构校验）。镜像 memport.py parse_bundle。
+ * 入参是字符串（调用方读文件时自带编码处理）；此处容错剥离 BOM。
+ */
+export function parseBundle(text) {
+    const b = {
+        header: {},
+        cols: [],
+        records: [],
+        errors: [],
+        warnings: [],
+        declaredCount: null,
+        declaredSha: null,
+        bodyLines: [],
+    };
+    const clean = text.replace(/^/, '');
+    const rawLines = clean.split(/\r?\n/);
+    const body = [];
+    let seqLine = 0;
+    for (const line of rawLines) {
+        seqLine++;
+        if (line.startsWith('#')) {
+            const head = line.slice(1).trim();
+            if (head.startsWith('memport')) {
+                const rest = head.slice('memport'.length).trim();
+                b.header.version = rest.split(';')[0].trim() || '1';
+                continue;
+            }
+            for (const part of head.split(';')) {
+                const p = part.trim();
+                if (!p || !p.includes('='))
+                    continue;
+                const idx = p.indexOf('=');
+                const k = p.slice(0, idx).trim();
+                const v = p.slice(idx + 1).trim();
+                if (k === 'cols')
+                    b.cols = v.split('|').map((c) => c.trim());
+                else if (k === 'count') {
+                    const n = Number(v);
+                    if (Number.isInteger(n))
+                        b.declaredCount = n;
+                    else
+                        b.errors.push(`L${seqLine}: count 不是整数:${v}`);
+                }
+                else if (k === 'sha256')
+                    b.declaredSha = v;
+                else
+                    b.header[k] = v;
+            }
+            continue;
+        }
+        if (line.trim() === '')
+            continue;
+        body.push(line);
+    }
+    b.bodyLines = body;
+    if (b.cols.length === 0) {
+        b.cols = [...DEFAULT_COLS];
+        b.warnings.push('包未声明 #cols=，按 MMF 默认列序解析');
+    }
+    if (!b.cols.includes('content')) {
+        b.errors.push('列声明缺少 content 列');
+        return b;
+    }
+    const missingCols = ['vf', 'vt', 'st'].filter((c) => !b.cols.includes(c));
+    if (missingCols.length) {
+        b.warnings.push(`包缺 ${missingCols.join('/')} 列（MMF v1 包）；有效期与持续性将按 -/-/? 落库，无法参与时间定位，建议导出侧升级到 v1.1`);
+    }
+    const ci = {};
+    b.cols.forEach((name, i) => (ci[name] = i));
+    const contentIdx = ci.content;
+    if (contentIdx !== b.cols.length - 1 && b.errors.length === 0) {
+        b.warnings.push('content 不是最后一列；含 | 的内容可能被误切');
+    }
+    const col = (parts, name, def = '') => {
+        const i = ci[name];
+        return i === undefined ? def : (parts[i] ?? '').trim();
+    };
+    body.forEach((line, i) => {
+        const seq = i + 1;
+        const parts = splitMax(line, b.cols.length - 1);
+        if (parts.length !== b.cols.length) {
+            b.errors.push(`记录 ${seq}: 列数 ${parts.length} != 声明 ${b.cols.length}`);
+            return;
+        }
+        const content = unescapeContent(parts[contentIdx] ?? '').trim();
+        const typeRaw = col(parts, 'type');
+        const rec = {
+            seq,
+            type: typeRaw,
+            typeFull: TYPE_CODES[typeRaw] ?? typeRaw,
+            created: col(parts, 'created'),
+            updated: col(parts, 'updated'),
+            vf: col(parts, 'vf', '-'),
+            vt: col(parts, 'vt', '-'),
+            st: col(parts, 'st', '?'),
+            cf: col(parts, 'cf'),
+            rw: col(parts, 'rw'),
+            tags: 'tags' in ci ? parseTags(col(parts, 'tags')) : {},
+            content,
+            hash: contentHash(content),
+            createdMs: null,
+            createdPrec: 'unknown',
+            updatedMs: null,
+            updatedPrec: 'unknown',
+            vfMs: null,
+            vfPrec: 'unknown',
+            vtMs: null,
+            vtPrec: 'unknown',
+        };
+        const c = parseTime(rec.created);
+        rec.createdMs = c.ms;
+        rec.createdPrec = c.precision;
+        const u = parseTime(rec.updated);
+        rec.updatedMs = u.ms;
+        rec.updatedPrec = u.precision;
+        const vf = parseTime(rec.vf);
+        rec.vfMs = vf.ms;
+        rec.vfPrec = vf.precision;
+        const vt = parseTime(rec.vt);
+        rec.vtMs = vt.ms;
+        rec.vtPrec = vt.precision;
+        b.records.push(rec);
+    });
+    // ── 结构校验 ──
+    const ver = b.header.version;
+    if (ver !== undefined && !KNOWN_VERSIONS.has(ver)) {
+        b.errors.push(`未知包版本：${ver}（本工具支持 1 / 1.1）`);
+    }
+    if (b.declaredCount !== null && b.declaredCount !== body.length) {
+        b.errors.push(`条数不符：声明 ${b.declaredCount}，实际记录行 ${body.length}`);
+    }
+    if (b.declaredSha) {
+        const digest = createHash('sha256').update(body.join('\n'), 'utf8').digest('hex');
+        if (!digest.startsWith(b.declaredSha.slice(0, 12))) {
+            b.errors.push(`校验和不符：声明 ${b.declaredSha.slice(0, 12)}，实算 ${digest.slice(0, 12)}`);
+        }
+    }
+    const seen = {};
+    for (const rec of b.records) {
+        const p = `记录 ${rec.seq}`;
+        if (!(rec.type in TYPE_CODES) && !(rec.type in TYPE_FULL)) {
+            if (rec.type === '' || rec.type === '?')
+                b.warnings.push(`${p}: 类型缺失，导入时将回落 episodic`);
+            else
+                b.warnings.push(`${p}: 非标准类型码 ${rec.type}，将按原样透传`);
+        }
+        for (const [fld, val] of [
+            ['cf', rec.cf],
+            ['rw', rec.rw],
+        ]) {
+            if (val !== '0' && val !== '1' && val !== '?')
+                b.errors.push(`${p}: ${fld} 取值非法 ${val}（仅 0/1/?）`);
+        }
+        if (!PERSISTENCE.includes(rec.st)) {
+            b.errors.push(`${p}: st 取值非法 ${rec.st}（仅 p/s/o/t/?）`);
+        }
+        if (rec.vfMs && rec.vtMs && rec.vtMs < rec.vfMs) {
+            b.warnings.push(`${p}: vt 早于 vf，已按 vf 处理`);
+            rec.vtMs = rec.vfMs;
+        }
+        if (rec.content.length < 4)
+            b.errors.push(`${p}: content 过短，疑似空记录`);
+        if (rec.content.length > 600)
+            b.warnings.push(`${p}: content 超长（${rec.content.length} 字符），违反节省规则（≤100 字）`);
+        if (rec.createdMs && rec.updatedMs && rec.updatedMs < rec.createdMs) {
+            b.warnings.push(`${p}: updated 早于 created，已按 created 视为 updated`);
+            rec.updatedMs = rec.createdMs;
+        }
+        if (rec.hash in seen)
+            b.errors.push(`${p}: 与本包第 ${seen[rec.hash]} 条内容重复（应先在包内去重）`);
+        else
+            seen[rec.hash] = rec.seq;
+    }
+    if (b.records.length === 0)
+        b.errors.push('包内没有任何记录');
+    return b;
+}

package/dist/memport/prefilter.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 外部导入预筛（轨3 宿主侧纯 TS）：把 memport.py 的确定性相似度判据下沉到宿主。
+ *
+ * 0 LLM / 0 token / 0 网络——纯本地 CPU。判据与阈值经真实语料标定，与
+ * `skills/memport/scripts/memport.py` 一字对齐（金标准测试见
+ * `tests/memport-ts-consistency.test.ts`）：score = max(3-gram Jaccard, 2-gram Dice)，
+ * 真改写对 0.49~0.51 / 主题相关但不同 0.16~0.28，故
+ *   score ≥ 0.62 → 同一事实的改写（near-dup）
+ *   score ≥ 0.30 → 主题相关，交上层判定互补还是矛盾（conflict-candidate）
+ * 宁可多判（代价低），不可漏判（漏判 = 冲突静默入库）。
+ *
+ * 刻意**不接嵌入做去重**：一旦引语义模型，就从"0-token 纯 CPU"变成"装运行时 + 逐条
+ * 嵌入"的持续开销（对齐计划轨3 性能红线）。
+ */
+import { type MemRecord } from './format.js';
+/** 相似度阈值（与 memport.py DEFAULT_* 一致）。 */
+export declare const DEFAULT_DUP_T = 0.62;
+export declare const DEFAULT_REL_T = 0.3;
+/** n-gram 集合（按码点滑窗，unicode 安全；len≤n 时整体作单 gram）。镜像 gram_set。 */
+export declare function gramSet(s: string, n?: number): Set<string>;
+export declare function jaccard(a: Set<string>, b: Set<string>): number;
+/** Dice 系数：对长度差异比 Jaccard 宽容，中文改写场景召回更好。 */
+export declare function dice(a: Set<string>, b: Set<string>): number;
+/** 一对（已预计算 gram）的相似度：max(3g Jaccard, 2g Dice)，round 4。镜像 score_pair。 */
+export declare function scorePair(g3: Set<string>, g2: Set<string>, h3: Set<string>, h2: Set<string>): number;
+/** 已有记忆的最小形状（来自 snapshot：content + hash + id）。 */
+export interface ExistingLike {
+    id: string;
+    content: string;
+    hash: string;
+}
+export type Verdict = 'new' | 'dup' | 'near-dup' | 'conflict-candidate';
+export interface MatchedRef {
+    id: string;
+    score: number;
+    hash: string;
+    content: string;
+}
+export interface PlanRow {
+    seq: number;
+    id: string;
+    hash: string;
+    typeFull: string;
+    content: string;
+    verdict: Verdict;
+    matched: MatchedRef[];
+    reason: string;
+}
+export interface PlanResult {
+    rows: PlanRow[];
+    counts: Record<Verdict, number>;
+}
+/**
+ * 四桶预筛：对每条待导入记录，先按内容哈希查 dup，再对基线取 top-3 相似按阈值分档；
+ * 基线未命中时兜底比对本包内前序条目（导出侧应已合并，这里拦包内近重复）。
+ * 镜像 cmd_plan 的分类段（不含 temporal_diff——那属上层裁决增强，非本层职责）。
+ */
+export declare function plan(records: MemRecord[], existing: ExistingLike[], opts?: {
+    dupThreshold?: number;
+    relThreshold?: number;
+    srcTag?: string;
+}): PlanResult;

package/dist/memport/prefilter.js

@@ -0,0 +1,132 @@
+/**
+ * 外部导入预筛（轨3 宿主侧纯 TS）：把 memport.py 的确定性相似度判据下沉到宿主。
+ *
+ * 0 LLM / 0 token / 0 网络——纯本地 CPU。判据与阈值经真实语料标定，与
+ * `skills/memport/scripts/memport.py` 一字对齐（金标准测试见
+ * `tests/memport-ts-consistency.test.ts`）：score = max(3-gram Jaccard, 2-gram Dice)，
+ * 真改写对 0.49~0.51 / 主题相关但不同 0.16~0.28，故
+ *   score ≥ 0.62 → 同一事实的改写（near-dup）
+ *   score ≥ 0.30 → 主题相关，交上层判定互补还是矛盾（conflict-candidate）
+ * 宁可多判（代价低），不可漏判（漏判 = 冲突静默入库）。
+ *
+ * 刻意**不接嵌入做去重**：一旦引语义模型，就从"0-token 纯 CPU"变成"装运行时 + 逐条
+ * 嵌入"的持续开销（对齐计划轨3 性能红线）。
+ */
+import { normText, recordId } from './format.js';
+/** 相似度阈值（与 memport.py DEFAULT_* 一致）。 */
+export const DEFAULT_DUP_T = 0.62;
+export const DEFAULT_REL_T = 0.30;
+/** n-gram 集合（按码点滑窗，unicode 安全；len≤n 时整体作单 gram）。镜像 gram_set。 */
+export function gramSet(s, n = 3) {
+    const t = Array.from(normText(s).toLowerCase());
+    if (t.length <= n)
+        return t.length ? [t.join('')].reduce((acc, x) => acc.add(x), new Set()) : new Set();
+    const out = new Set();
+    for (let i = 0; i + n <= t.length; i++)
+        out.add(t.slice(i, i + n).join(''));
+    return out;
+}
+export function jaccard(a, b) {
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let inter = 0;
+    for (const x of a)
+        if (b.has(x))
+            inter++;
+    const union = a.size + b.size - inter;
+    return union === 0 ? 0 : inter / union;
+}
+/** Dice 系数：对长度差异比 Jaccard 宽容，中文改写场景召回更好。 */
+export function dice(a, b) {
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let inter = 0;
+    for (const x of a)
+        if (b.has(x))
+            inter++;
+    return (2 * inter) / (a.size + b.size);
+}
+/** 一对（已预计算 gram）的相似度：max(3g Jaccard, 2g Dice)，round 4。镜像 score_pair。 */
+export function scorePair(g3, g2, h3, h2) {
+    return Math.round(Math.max(jaccard(g3, h3), dice(g2, h2)) * 1e4) / 1e4;
+}
+/**
+ * 四桶预筛：对每条待导入记录，先按内容哈希查 dup，再对基线取 top-3 相似按阈值分档；
+ * 基线未命中时兜底比对本包内前序条目（导出侧应已合并，这里拦包内近重复）。
+ * 镜像 cmd_plan 的分类段（不含 temporal_diff——那属上层裁决增强，非本层职责）。
+ */
+export function plan(records, existing, opts = {}) {
+    const dupT = opts.dupThreshold ?? DEFAULT_DUP_T;
+    const relT = opts.relThreshold ?? DEFAULT_REL_T;
+    const srcTag = opts.srcTag ?? '';
+    const byHash = new Map();
+    for (const r of existing)
+        if (!byHash.has(r.hash))
+            byHash.set(r.hash, r);
+    const exGrams = existing.map((r) => ({ r, g3: gramSet(r.content, 3), g2: gramSet(r.content, 2) }));
+    const rows = [];
+    const counts = { new: 0, dup: 0, 'near-dup': 0, 'conflict-candidate': 0 };
+    const bundleGrams = [];
+    for (const rec of records) {
+        const rid = recordId(srcTag, rec.hash);
+        const hit = byHash.get(rec.hash);
+        let verdict = 'new';
+        let matched = [];
+        let reason = '基线中无相关内容';
+        if (hit) {
+            verdict = 'dup';
+            matched = [{ id: hit.id, score: 1, hash: hit.hash, content: hit.content }];
+            reason = `内容哈希与现存 ${hit.id} 完全一致`;
+        }
+        else {
+            const c3 = gramSet(rec.content, 3);
+            const c2 = gramSet(rec.content, 2);
+            const scored = exGrams
+                .map(({ r, g3, g2 }) => ({ id: r.id, score: scorePair(c3, c2, g3, g2), hash: r.hash, content: r.content }))
+                .sort((a, b) => b.score - a.score)
+                .slice(0, 3);
+            const best = scored[0];
+            if (best && best.score >= dupT) {
+                verdict = 'near-dup';
+                matched = scored.filter((s) => s.score >= relT);
+                reason = `与现存 ${best.id} 相似度 ${best.score.toFixed(2)}，疑似同一事实的另一种表述`;
+            }
+            else if (best && best.score >= relT) {
+                verdict = 'conflict-candidate';
+                matched = scored.filter((s) => s.score >= relT);
+                reason = `与现存 ${best.id} 主题相关（相似度 ${best.score.toFixed(2)}），需判定互补还是矛盾`;
+            }
+            // 包内近重复兜底
+            if (verdict === 'new' && bundleGrams.length) {
+                let ibest = null;
+                let iscore = 0;
+                for (const prev of bundleGrams) {
+                    const sc = scorePair(c3, c2, prev.g3, prev.g2);
+                    if (sc > iscore) {
+                        iscore = sc;
+                        ibest = prev.rec;
+                    }
+                }
+                if (ibest && iscore >= relT) {
+                    const near = iscore >= dupT;
+                    verdict = near ? 'near-dup' : 'conflict-candidate';
+                    matched = [{ id: `bundle#${ibest.seq}`, score: iscore, hash: ibest.hash, content: ibest.content }];
+                    reason = `与本包第 ${ibest.seq} 条相似度 ${iscore.toFixed(2)}` + (near ? '（包内近重复，导出侧应先合并）' : '（包内相关条目，需判定）');
+                }
+            }
+            bundleGrams.push({ rec, g3: gramSet(rec.content, 3), g2: gramSet(rec.content, 2) });
+        }
+        counts[verdict]++;
+        rows.push({
+            seq: rec.seq,
+            id: rid,
+            hash: rec.hash,
+            typeFull: rec.typeFull,
+            content: rec.content,
+            verdict,
+            matched,
+            reason,
+        });
+    }
+    return { rows, counts };
+}

package/dist/memport/scan.d.ts

@@ -0,0 +1,13 @@
+import type { MemorySourceEntry } from '../store/memory-sources.js';
+import type { MemoryRecord as L1Record } from '../types.js';
+import type { MemportScanSourceResult } from '../contract.js';
+/** l1 的最小读取面（解耦具体 store，便于测试注入）。 */
+export interface L1Reader {
+    all(): L1Record[];
+}
+/** 扫描一批来源（只读）。返回每个来源的四桶预览（含失败原因）。 */
+export declare function scanSources(opts: {
+    sources: MemorySourceEntry[];
+    l1: L1Reader;
+    maxRecords: number;
+}): Promise<MemportScanSourceResult[]>;

package/dist/memport/scan.js

@@ -0,0 +1,100 @@
+/**
+ * 外部来源只读扫描（轨3 Connect，3.4）。
+ *
+ * **只读预览，绝不写库**：遍历已登记来源 → 找 `.mem` 包 → `parseBundle` → `prefilter.plan`
+ * 与现存基线比对 → 产出四桶计数 + 新记录样本。真正的落库由上层（agent 调 `memory_import`，
+ * 携 source_id 走 P0 的 ext_key 幂等 + 脱敏）完成——扫描本身不碰写入面，
+ * 因此不重复 memory_import 的 `__manual__`/supersede/redact 门禁（那些在写侧强制）。
+ *
+ * 卫生边界：
+ * - 单源/单包读失败**只记 error 不抛**，不阻断其余来源（对齐 sidecar 降级铁律）；
+ * - `.mem` 才是 interchange 载体；非 .mem 路径记一条提示，引导先跑 `memport 导出`；
+ * - 记录数受 `maxRecords` 上限（防极端大包在 RPC 事件循环里阻塞）；
+ * - 预览正文**截断**，且不外传整文件内容——完整脱敏留给写侧 memory_import。
+ */
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { isAbsolute, join } from 'node:path';
+import { contentHash, parseBundle } from './format.js';
+import { plan } from './prefilter.js';
+const MEM_EXT = '.mem';
+const MAX_FILES_PER_SOURCE = 50;
+const SAMPLE_CAP = 8;
+const SAMPLE_CHARS = 90;
+async function collectMemFiles(root) {
+    const st = await stat(root);
+    if (st.isFile())
+        return root.toLowerCase().endsWith(MEM_EXT) ? [root] : [];
+    if (!st.isDirectory())
+        return [];
+    const names = await readdir(root);
+    return names.filter((n) => n.toLowerCase().endsWith(MEM_EXT)).slice(0, MAX_FILES_PER_SOURCE).map((n) => join(root, n));
+}
+/** 扫描一批来源（只读）。返回每个来源的四桶预览（含失败原因）。 */
+export async function scanSources(opts) {
+    const { sources, l1, maxRecords } = opts;
+    // 现存基线（id + content + 规范化哈希）——供 plan 做 dup/near-dup 比对。
+    const existing = l1.all().map((r) => ({ id: r.id, content: r.content, hash: contentHash(r.content ?? '') }));
+    const out = [];
+    for (const src of sources) {
+        const result = {
+            sourceId: src.id,
+            label: src.label,
+            files: 0,
+            total: 0,
+            errors: [],
+            counts: { dup: 0, 'near-dup': 0, 'conflict-candidate': 0, new: 0 },
+            sampleNew: [],
+        };
+        out.push(result);
+        if (!isAbsolute(src.path)) {
+            result.errors.push(`来源 path 非绝对路径，已跳过：${src.path}`);
+            continue;
+        }
+        let files;
+        try {
+            files = await collectMemFiles(src.path);
+        }
+        catch (err) {
+            result.errors.push(`读取失败：${src.path}（${err instanceof Error ? err.message : String(err)}）`);
+            continue;
+        }
+        if (files.length === 0) {
+            result.errors.push(`${src.path} 下未发现 .mem 包（先用「memport 导出」在该工具侧生成，或把 .mem 落到此路径）`);
+            continue;
+        }
+        const acc = [];
+        for (const f of files) {
+            if (acc.length >= maxRecords)
+                break;
+            let text;
+            try {
+                text = await readFile(f, 'utf8');
+            }
+            catch (err) {
+                result.errors.push(`${f}: 读取失败（${err instanceof Error ? err.message : String(err)}）`);
+                continue;
+            }
+            const b = parseBundle(text);
+            if (b.errors.length) {
+                result.errors.push(`${f}: 校验失败——${b.errors[0]}${b.errors.length > 1 ? `（共 ${b.errors.length} 项）` : ''}`);
+                continue;
+            }
+            result.files++;
+            for (const rec of b.records) {
+                if (acc.length >= maxRecords)
+                    break;
+                acc.push(rec);
+            }
+        }
+        result.total = acc.length;
+        if (acc.length === 0)
+            continue;
+        const { rows, counts } = plan(acc, existing, { srcTag: src.id });
+        result.counts = counts;
+        result.sampleNew = rows
+            .filter((r) => r.verdict === 'new')
+            .slice(0, SAMPLE_CAP)
+            .map((r) => ({ type: r.typeFull, content: r.content.length > SAMPLE_CHARS ? r.content.slice(0, SAMPLE_CHARS) + '…' : r.content }));
+    }
+    return out;
+}

package/dist/metadata-validators.d.ts

@@ -1,3 +1,4 @@
+import { type CognitiveHall } from './cognitive-hall.js';
 /**
  * Wing 严格校验:只认 8 域 + general 兜底。
  *
@@ -23,3 +24,24 @@ export declare function isTag(v: unknown): boolean;
  */
 export declare function normTags(v: unknown, max?: number): string[];
 export { isCognitiveHall, COGNITIVE_HALLS, type CognitiveHall } from './cognitive-hall.js';
+/**
+ * usageScenario 归一 + 去重 + 上限。**所有写回点必须过这里**。
+ *
+ * 与 normTags 的区别：usageScenario 是自然语言短语（如“修改 profile 配置时”），
+ * 不是 slug，所以不做字符集校验，只做 trim/去重/长度钳制/上限。
+ * 非数组或空→ `[]`（缺字段中性，不抛——防单条抽取失败波及整切片重试）。
+ */
+export declare function normUsageScenario(v: unknown, max?: number): string[];
+/**
+ * 读 **Wing（生活域）**。⚠️ 磁盘键是 `metadata.hall`——历史别名，存的其实是 **wing 值**。
+ * 只认词表内的合法 wing（8 角 + general），否则 undefined。
+ *
+ * 用它取代裸读 `metadata.hall`：从入口上把“wing 轴”与“认知 hall 轴”分开，
+ * 防止把认知 hall 值（facts/events/…）误当 wing 读——两轴不串。
+ */
+export declare function readWing(metadata: Record<string, unknown> | undefined | null): string | undefined;
+/**
+ * 读 **认知 hall（大类）**。磁盘键 `metadata.cogHall`，与 wing 的磁盘键 `hall` 正交。
+ * 只认五个枚举值，否则 undefined（wing 值不当认知 hall 读）。
+ */
+export declare function readCognitiveHall(metadata: Record<string, unknown> | undefined | null): CognitiveHall | undefined;