dsh-prime-memory 0.21.0 → 0.22.2

package/dist/store/session-recalled.js

@@ -0,0 +1,163 @@
+/**
+ * 会话"活召回集"存储（G-live）：sessionKey → 本会话已注入、尚未被压缩覆盖的 L1 记录 id。
+ *
+ * 语义（对齐"当前会话召回后对 session 有影响的条目"，且**旧会话重开也有效**）：
+ * - 每次召回**实际注入**（recall.ts 注入成功点）按 **sessionKey**（=agent.session?.id ?? agent.id，
+ *   与 pill 的 sessionId、投影 header.id 同源）记入；
+ * - 上下文压缩/清空（agent/created source=compact|clear）按 sessionKey **reset**；
+ * - **写穿持久化到 `session-recalled.json`**（独立 sidecar，与 recall-dedupe 同款：串行原子写 +
+ *   未知版本/损坏只读降级、失败绝不抛进召回热路径）→ 重启/旧会话重开时 `init()` 载回，卡不空。
+ *
+ * 供只读端点 `dsh-memory/session-recalled` 消费（client 浮层 SessionRecalledArea 展示）。
+ * 不经 memorySlots 投影：那条路会把召回渲染成常驻槽位注册表，与召回的非常驻语义错位。
+ */
+import * as path from 'node:path';
+import { errDetail } from '../util/filelog.js';
+import { ensureDir, readJsonStrict, rmwJson } from '../util/io.js';
+import { SESSION_RECALLED_FILE_VERSION } from './file-versions.js';
+import { RECALL_DEDUPE_IDS_CAP, RECALL_DEDUPE_SESSION_CAP } from './recall-dedupe.js';
+/** 条目过期清理（90 天，与 recall-dedupe 同量级）。 */
+const PRUNE_MS = 90 * 24 * 3600_000;
+export class SessionRecalledStore {
+    logger;
+    file;
+    entries = new Map();
+    degraded;
+    degradedLogged = false;
+    lastPersisted;
+    writeChain;
+    /** 脏检序号：每次真实变更 +1，投影 apply 据此 O(1) 判断是否重建。 */
+    rev = 0;
+    constructor(dataDir, logger) {
+        this.logger = logger;
+        this.file = path.join(dataDir, 'session-recalled.json');
+        this.writeChain = this.init();
+    }
+    revision() {
+        return this.rev;
+    }
+    async init() {
+        const r = await readJsonStrict(this.file, { expectedVersion: SESSION_RECALLED_FILE_VERSION });
+        let data;
+        if (r.ok) {
+            data = r.value;
+        }
+        else if (r.reason === 'missing') {
+            return;
+        }
+        else {
+            const lenient = await readJsonStrict(this.file);
+            if (!lenient.ok) {
+                this.degraded = lenient.reason;
+                this.logger?.warn(`[memory] 活召回集文件${lenient.reason === 'corrupt' ? '损坏' : '不可读'}(${this.file})：按空起步且不回写`);
+                return;
+            }
+            data = lenient.value;
+            this.degraded = `未知版本(${lenient.version ?? '无 version 字段'})`;
+            this.logger?.warn(`[memory] 活召回集文件版本未知(${lenient.version ?? '无'})：按当前形状读取并只读降级(不回写)`);
+        }
+        this.lastPersisted = JSON.stringify(data);
+        if (!data?.sessions || typeof data.sessions !== 'object')
+            return;
+        const now = Date.now();
+        for (const [sid, entry] of Object.entries(data.sessions)) {
+            if (!Array.isArray(entry?.recordIds))
+                continue;
+            if (now - (entry.updatedAt ?? 0) > PRUNE_MS)
+                continue;
+            this.entries.set(sid, { ids: new Set(entry.recordIds), updatedAt: entry.updatedAt ?? now });
+        }
+    }
+    /** 记入本 sessionKey 本轮实际注入的记录 id（写穿；插入序淘汰最旧）。 */
+    add(sessionKey, recordIds) {
+        if (!sessionKey || recordIds.length === 0)
+            return;
+        let entry = this.entries.get(sessionKey);
+        if (!entry) {
+            entry = { ids: new Set(), updatedAt: 0 };
+            this.entries.set(sessionKey, entry);
+        }
+        for (const id of recordIds) {
+            entry.ids.add(id);
+            while (entry.ids.size > RECALL_DEDUPE_IDS_CAP) {
+                const oldest = entry.ids.values().next().value;
+                if (oldest === undefined)
+                    break;
+                entry.ids.delete(oldest);
+            }
+        }
+        entry.updatedAt = Date.now();
+        this.rev++;
+        this.writeChain = this.writeChain.then(() => this.persist());
+    }
+    list(sessionKey) {
+        const entry = this.entries.get(sessionKey);
+        return entry ? [...entry.ids] : [];
+    }
+    /** 压缩/清空：注入内容已离开上下文，清该会话活召回集（写穿）。 */
+    reset(sessionKey) {
+        if (!this.entries.has(sessionKey))
+            return;
+        this.entries.delete(sessionKey);
+        this.rev++;
+        this.writeChain = this.writeChain.then(() => this.persist());
+    }
+    size() {
+        return this.entries.size;
+    }
+    /** 等待在途持久化写完成（测试/停机）。 */
+    flush() {
+        return this.writeChain;
+    }
+    async persist() {
+        if (this.degraded !== undefined) {
+            if (!this.degradedLogged) {
+                this.degradedLogged = true;
+                this.logger?.warn(`[memory] 活召回集处于只读降级(${this.degraded})，已停止回写`);
+            }
+            return;
+        }
+        try {
+            await ensureDir(path.dirname(this.file));
+            await rmwJson(this.file, async (cur) => {
+                const diskRaw = cur.ok ? JSON.stringify(cur.value) : undefined;
+                if (this.lastPersisted !== undefined && diskRaw !== undefined && diskRaw !== this.lastPersisted) {
+                    throw new Error('活召回集文件已被其它进程更新，本次写入取消以避免覆盖');
+                }
+                const next = this.serialize();
+                this.lastPersisted = JSON.stringify(next);
+                return { next, result: undefined };
+            }, { logger: this.logger, purpose: 'session-recalled-rmw' });
+        }
+        catch (err) {
+            this.logger?.warn(`[memory] 活召回集持久化失败(降级内存态): ${errDetail(err)}`);
+        }
+    }
+    serialize() {
+        const now = Date.now();
+        for (const [sid, e] of this.entries) {
+            if (now - e.updatedAt > PRUNE_MS && e.updatedAt > 0)
+                this.entries.delete(sid);
+        }
+        while (this.entries.size > RECALL_DEDUPE_SESSION_CAP) {
+            let oldestKey;
+            let oldestAt = Infinity;
+            for (const [k, e] of this.entries) {
+                if (e.updatedAt < oldestAt) {
+                    oldestAt = e.updatedAt;
+                    oldestKey = k;
+                }
+            }
+            if (oldestKey === undefined)
+                break;
+            this.entries.delete(oldestKey);
+        }
+        const sessions = {};
+        for (const [sid, e] of this.entries) {
+            if (e.ids.size === 0)
+                continue;
+            sessions[sid] = { recordIds: [...e.ids], updatedAt: e.updatedAt };
+        }
+        return { version: SESSION_RECALLED_FILE_VERSION, sessions };
+    }
+}

package/dist/store/skill-store.d.ts

@@ -0,0 +1,99 @@
+import type { MemoryFamily, MemoryLogger } from '../types.js';
+export declare const SKILL_STORE_FILE_VERSION: 1;
+export type SkillStatus = 'candidate' | 'active' | 'archived';
+export type InjectionTier = 'full' | 'excerpt' | 'hint';
+export interface SkillTrigger {
+    /** 归属 wing/hall（粗分类）；缺省 = 不参与按域过滤。 */
+    hall?: string;
+    sceneName?: string;
+    keywords: string[];
+    workspaceId?: string;
+}
+export interface Skill {
+    id: string;
+    title: string;
+    /** 人可编辑正文；进 preserve 白名单，重建不覆盖。 */
+    body: string;
+    /** 机器聚合的 checklist 步骤；重建投影可覆盖。 */
+    steps: string[];
+    trigger: SkillTrigger;
+    injectionTier: InjectionTier;
+    status: SkillStatus;
+    pinned: boolean;
+    confidence: number;
+    family: MemoryFamily;
+    scope: 'global' | 'workspace';
+    /** 支撑该技能的证据记录 id（指向 l1_records.record_id，仅作溯源，不强约束外键）。 */
+    evidenceRecordIds: string[];
+    createdAt: string;
+    updatedAt: string;
+    lastUsedAt: string;
+    archivedReason?: string;
+}
+export interface SkillEvidence {
+    skillId: string;
+    runId: string;
+    recordId: string;
+    sessionId: string;
+    at: string;
+    kind: string;
+}
+export interface NewSkillInput {
+    id?: string;
+    title: string;
+    body?: string;
+    steps?: string[];
+    trigger?: Partial<SkillTrigger>;
+    injectionTier?: InjectionTier;
+    status?: SkillStatus;
+    family?: MemoryFamily;
+    scope?: 'global' | 'workspace';
+    evidenceRecordIds?: string[];
+}
+export declare class SkillStore {
+    private readonly logger?;
+    private readonly file;
+    private skills;
+    private evidence;
+    private rev;
+    private loaded;
+    private degraded;
+    private degradedLogged;
+    private writeChain;
+    private seq;
+    constructor(dataDir: string, logger?: MemoryLogger | undefined);
+    init(): Promise<void>;
+    private ensureLoaded;
+    list(): Skill[];
+    /** active 技能（注入候选）。 */
+    listActive(): Skill[];
+    get(id: string): Skill | undefined;
+    private newId;
+    /** 新建技能（幂等：显式传 id 且已存在 → 走 updateBody 语义由调用方决定，这里仅拒绝重复 id）。 */
+    create(input: NewSkillInput): Promise<Skill>;
+    /** 编辑人可读正文（body/title/steps/injectionTier/pinned）；只动提供的字段。 */
+    update(id: string, patch: Partial<Pick<Skill, 'title' | 'body' | 'steps' | 'injectionTier' | 'pinned'>>): Promise<boolean>;
+    /** 追加一条证据（只追加）；返回该技能当前的 distinct-session 数。 */
+    appendEvidence(ev: SkillEvidence): Promise<number>;
+    /** 某技能的 distinct session 计数（晋升判据的唯一来源，与 LLM 判断解耦）。 */
+    sessionCount(skillId: string): number;
+    /**
+     * 晋升：candidate→active，仅当功能开且该技能 distinct-session ≥ minSessions。
+     * 返回是否发生晋升。不批量、不依赖 LLM（可解释性结构保证，同 conflictFreeze"不自动裁决"哲学）。
+     */
+    tryPromote(skillId: string, minSessions: number, opts: {
+        allowPromote: boolean;
+    }): Promise<boolean>;
+    /** 记一次使用（刷新 lastUsedAt，供闲置归档与"只用才强化"）。 */
+    touchUsed(skillId: string, at: string): Promise<boolean>;
+    /** 归档（active/candidate→archived）；记录原因。走本表独立生命周期，不触碰 l1_records 退场。 */
+    archive(skillId: string, reason: string): Promise<boolean>;
+    /**
+     * 闲置归档：active 且未 pinned 且（now - lastUsedAt）> idleDays 的技能自动归档。
+     * 机械比较、0 LLM、不引入 timer（对齐 slots.expireDue 范式）。返回归档条数。
+     */
+    archiveDue(now: number, idleDays: number): Promise<number>;
+    private patchOne;
+    /** 写穿持久化（串行链；失败降级内存态并告警一次，绝不抛出阻塞调用方）。 */
+    private persist;
+}

package/dist/store/skill-store.js

@@ -0,0 +1,330 @@
+/**
+ * 技能结晶存储（轨2，程序性记忆）。**默认关**（config.skills.enabled）。
+ *
+ * 设计裁定（对齐计划轨2 + 三视角审计）：
+ * - 技能**不是 memory `type`**，而是 L1 之上的**可重建派生投影**——因此完全不碰
+ *   `ADD_TYPES` 白名单与蒸馏 prompt 词表，从根上规避 S1(白名单静默降级)/S2(词表产不出)/
+ *   S3(family 前缀误归族) 三处静默腐化；证据来源 = 现有 `work_method` L1 记录。
+ * - 落 **JSON sidecar**（仿 memory-sources/rooms-registry），不塞进 2691 行的 `sqlite.ts`：
+ *   技能条目量小、distinct-session 计数内存聚合即可；缺失=合法空表、损坏=只读降级不阻塞。
+ * - **`body`（人编辑）与 `steps`（机器聚合）分列**：机器侧可被重建投影覆盖，
+ *   人编辑侧永久保留（对齐 rebuild-preserve 的"非派生内容不可被重建抹掉"不变量）。
+ * - **只计数不晋升**（本轮）：`skill_evidence` 记录 distinct session，晋升需
+ *   `count(distinct session) >= minSessions` 且功能开；新装库无历史即空转，符合预期。
+ * - 归档 `archiveDue` 基于 `lastUsedAt` 闲置天数（机械比较，0 LLM、不引入 timer）。
+ */
+import * as path from 'node:path';
+import { readJsonStrict, atomicWriteText, ensureDir } from '../util/io.js';
+export const SKILL_STORE_FILE_VERSION = 1;
+const SKILLS_CAP = 500;
+const EVIDENCE_CAP = 20_000;
+const TITLE_MAX = 120;
+const BODY_MAX = 8000;
+const STEP_MAX = 40;
+const KEYWORDS_MAX = 16;
+const TIER_SET = new Set(['full', 'excerpt', 'hint']);
+const STATUS_SET = new Set(['candidate', 'active', 'archived']);
+function str(v, def = '') {
+    return typeof v === 'string' ? v : def;
+}
+function normTier(v) {
+    return TIER_SET.has(v) ? v : 'excerpt';
+}
+function normStatus(v) {
+    return STATUS_SET.has(v) ? v : 'candidate';
+}
+/** 规整一条技能（读取侧 fail-soft：非法值归一到合法域，绝不因单条脏数据拖垮整表）。 */
+function coerceSkill(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    const id = str(r.id);
+    const title = str(r.title).slice(0, TITLE_MAX);
+    if (!id || !title)
+        return null;
+    return {
+        id,
+        title,
+        body: str(r.body).slice(0, BODY_MAX),
+        steps: Array.isArray(r.steps) ? r.steps.filter((s) => typeof s === 'string').slice(0, STEP_MAX) : [],
+        trigger: {
+            hall: typeof r.trigger?.hall === 'string' ? str(r.trigger.hall) : undefined,
+            sceneName: typeof r.trigger?.sceneName === 'string' ? str(r.trigger.sceneName) : undefined,
+            keywords: Array.isArray(r.trigger?.keywords)
+                ? r.trigger.keywords.filter((k) => typeof k === 'string' && k !== '').slice(0, KEYWORDS_MAX)
+                : [],
+            workspaceId: typeof r.trigger?.workspaceId === 'string' ? str(r.trigger.workspaceId) : undefined,
+        },
+        injectionTier: normTier(r.injectionTier),
+        status: normStatus(r.status),
+        pinned: r.pinned === true,
+        confidence: typeof r.confidence === 'number' && Number.isFinite(r.confidence) ? Math.max(0, Math.min(1, r.confidence)) : 0,
+        family: r.family === 'work' ? 'work' : 'chat',
+        scope: r.scope === 'workspace' ? 'workspace' : 'global',
+        evidenceRecordIds: Array.isArray(r.evidenceRecordIds) ? r.evidenceRecordIds.filter((x) => typeof x === 'string').slice(0, 200) : [],
+        createdAt: str(r.createdAt),
+        updatedAt: str(r.updatedAt),
+        lastUsedAt: str(r.lastUsedAt),
+        archivedReason: typeof r.archivedReason === 'string' ? r.archivedReason : undefined,
+    };
+}
+export class SkillStore {
+    logger;
+    file;
+    skills = [];
+    evidence = [];
+    rev = 0;
+    loaded = false;
+    degraded;
+    degradedLogged = false;
+    writeChain = Promise.resolve();
+    seq = 0;
+    constructor(dataDir, logger) {
+        this.logger = logger;
+        this.file = path.join(dataDir, 'skills.json');
+    }
+    async init() {
+        await ensureDir(path.dirname(this.file));
+        const read = await readJsonStrict(this.file);
+        if (!read.ok) {
+            if (read.reason !== 'missing') {
+                this.degraded = `${read.reason}${'detail' in read && read.detail ? `: ${read.detail}` : ''}`;
+                this.logger?.warn(`[memory] 技能存储只读降级（内存态照常，停止回写）: ${this.degraded}`);
+            }
+            this.loaded = true;
+            return;
+        }
+        if (read.value.version !== SKILL_STORE_FILE_VERSION) {
+            this.logger?.warn(`[memory] 技能存储版本 ${String(read.value.version)} 未知，按当前形状读取`);
+        }
+        if (Array.isArray(read.value.skills)) {
+            for (const raw of read.value.skills) {
+                const s = coerceSkill(raw);
+                if (s)
+                    this.skills.push(s);
+            }
+        }
+        if (Array.isArray(read.value.evidence)) {
+            for (const e of read.value.evidence) {
+                if (e && typeof e.skillId === 'string' && typeof e.sessionId === 'string')
+                    this.evidence.push(e);
+            }
+        }
+        this.rev = typeof read.value.rev === 'number' ? read.value.rev : 0;
+        // 序号续接：避免重启后铸出重复 skill id。
+        this.seq = this.skills.length;
+        this.loaded = true;
+    }
+    ensureLoaded() {
+        if (!this.loaded)
+            throw new Error('技能存储未初始化（先 await init()）');
+    }
+    list() {
+        this.ensureLoaded();
+        return this.skills.map((s) => ({ ...s, steps: [...s.steps], trigger: { ...s.trigger, keywords: [...s.trigger.keywords] }, evidenceRecordIds: [...s.evidenceRecordIds] }));
+    }
+    /** active 技能（注入候选）。 */
+    listActive() {
+        return this.list().filter((s) => s.status === 'active');
+    }
+    get(id) {
+        this.ensureLoaded();
+        const s = this.skills.find((x) => x.id === id);
+        return s ? { ...s, steps: [...s.steps], trigger: { ...s.trigger, keywords: [...s.trigger.keywords] }, evidenceRecordIds: [...s.evidenceRecordIds] } : undefined;
+    }
+    newId() {
+        this.seq++;
+        return 'sk-' + Date.now().toString(36) + '-' + this.seq.toString(36);
+    }
+    /** 新建技能（幂等：显式传 id 且已存在 → 走 updateBody 语义由调用方决定，这里仅拒绝重复 id）。 */
+    async create(input) {
+        this.ensureLoaded();
+        if (this.skills.length >= SKILLS_CAP)
+            throw new Error(`技能数已达上限（${SKILLS_CAP}），请归档部分`);
+        const id = (input.id ?? '').trim() || this.newId();
+        if (this.skills.some((s) => s.id === id))
+            throw new Error(`技能 id 已存在: ${id}`);
+        const title = String(input.title ?? '').trim().slice(0, TITLE_MAX);
+        if (!title)
+            throw new Error('技能 title 不能为空');
+        const now = new Date().toISOString();
+        const skill = {
+            id,
+            title,
+            body: String(input.body ?? '').slice(0, BODY_MAX),
+            steps: (input.steps ?? []).filter((x) => typeof x === 'string').slice(0, STEP_MAX),
+            trigger: {
+                hall: input.trigger?.hall?.trim() || undefined,
+                sceneName: input.trigger?.sceneName?.trim() || undefined,
+                keywords: (input.trigger?.keywords ?? []).filter((k) => k).slice(0, KEYWORDS_MAX),
+                workspaceId: input.trigger?.workspaceId || undefined,
+            },
+            injectionTier: normTier(input.injectionTier),
+            status: normStatus(input.status),
+            pinned: false,
+            confidence: 0,
+            family: input.family === 'chat' ? 'chat' : 'work',
+            scope: input.scope === 'workspace' ? 'workspace' : 'global',
+            evidenceRecordIds: (input.evidenceRecordIds ?? []).slice(0, 200),
+            createdAt: now,
+            updatedAt: now,
+            lastUsedAt: '',
+        };
+        this.skills.push(skill);
+        this.rev++;
+        await this.persist();
+        return { ...skill };
+    }
+    /** 编辑人可读正文（body/title/steps/injectionTier/pinned）；只动提供的字段。 */
+    async update(id, patch) {
+        this.ensureLoaded();
+        const s = this.skills.find((x) => x.id === id);
+        if (!s)
+            return false;
+        let changed = false;
+        if (typeof patch.title === 'string' && patch.title.trim()) {
+            s.title = patch.title.trim().slice(0, TITLE_MAX);
+            changed = true;
+        }
+        if (typeof patch.body === 'string') {
+            s.body = patch.body.slice(0, BODY_MAX);
+            changed = true;
+        }
+        if (Array.isArray(patch.steps)) {
+            s.steps = patch.steps.filter((x) => typeof x === 'string').slice(0, STEP_MAX);
+            changed = true;
+        }
+        if (patch.injectionTier !== undefined && TIER_SET.has(patch.injectionTier)) {
+            s.injectionTier = patch.injectionTier;
+            changed = true;
+        }
+        if (patch.pinned !== undefined && patch.pinned !== s.pinned) {
+            s.pinned = patch.pinned;
+            changed = true;
+        }
+        if (!changed)
+            return false;
+        s.updatedAt = new Date().toISOString();
+        this.rev++;
+        await this.persist();
+        return true;
+    }
+    /** 追加一条证据（只追加）；返回该技能当前的 distinct-session 数。 */
+    async appendEvidence(ev) {
+        this.ensureLoaded();
+        if (!this.skills.some((s) => s.id === ev.skillId))
+            return 0;
+        this.evidence.push(ev);
+        if (this.evidence.length > EVIDENCE_CAP)
+            this.evidence.splice(0, this.evidence.length - EVIDENCE_CAP);
+        this.rev++;
+        await this.persist();
+        return this.sessionCount(ev.skillId);
+    }
+    /** 某技能的 distinct session 计数（晋升判据的唯一来源，与 LLM 判断解耦）。 */
+    sessionCount(skillId) {
+        this.ensureLoaded();
+        const s = new Set();
+        for (const e of this.evidence)
+            if (e.skillId === skillId && e.sessionId)
+                s.add(e.sessionId);
+        return s.size;
+    }
+    /**
+     * 晋升：candidate→active，仅当功能开且该技能 distinct-session ≥ minSessions。
+     * 返回是否发生晋升。不批量、不依赖 LLM（可解释性结构保证，同 conflictFreeze"不自动裁决"哲学）。
+     */
+    async tryPromote(skillId, minSessions, opts) {
+        this.ensureLoaded();
+        if (!opts.allowPromote)
+            return false;
+        const s = this.skills.find((x) => x.id === skillId);
+        if (!s || s.status !== 'candidate')
+            return false;
+        if (this.sessionCount(skillId) < minSessions)
+            return false;
+        s.status = 'active';
+        s.updatedAt = new Date().toISOString();
+        this.rev++;
+        await this.persist();
+        return true;
+    }
+    /** 记一次使用（刷新 lastUsedAt，供闲置归档与"只用才强化"）。 */
+    async touchUsed(skillId, at) {
+        return this.patchOne(skillId, (s) => {
+            s.lastUsedAt = at;
+        });
+    }
+    /** 归档（active/candidate→archived）；记录原因。走本表独立生命周期，不触碰 l1_records 退场。 */
+    async archive(skillId, reason) {
+        this.ensureLoaded();
+        const s = this.skills.find((x) => x.id === skillId);
+        if (!s || s.status === 'archived')
+            return false;
+        s.status = 'archived';
+        s.archivedReason = reason;
+        s.updatedAt = new Date().toISOString();
+        this.rev++;
+        await this.persist();
+        return true;
+    }
+    /**
+     * 闲置归档：active 且未 pinned 且（now - lastUsedAt）> idleDays 的技能自动归档。
+     * 机械比较、0 LLM、不引入 timer（对齐 slots.expireDue 范式）。返回归档条数。
+     */
+    async archiveDue(now, idleDays) {
+        this.ensureLoaded();
+        if (idleDays <= 0)
+            return 0;
+        const cutoff = now - idleDays * 86_400_000;
+        let n = 0;
+        for (const s of this.skills) {
+            if (s.status !== 'active' || s.pinned)
+                continue;
+            const last = s.lastUsedAt ? Date.parse(s.lastUsedAt) : Date.parse(s.updatedAt || s.createdAt);
+            if (Number.isFinite(last) && last < cutoff) {
+                s.status = 'archived';
+                s.archivedReason = `idle>${idleDays}d`;
+                s.updatedAt = new Date(now).toISOString();
+                n++;
+            }
+        }
+        if (n) {
+            this.rev++;
+            await this.persist();
+        }
+        return n;
+    }
+    async patchOne(id, mut) {
+        this.ensureLoaded();
+        const s = this.skills.find((x) => x.id === id);
+        if (!s)
+            return false;
+        mut(s);
+        s.updatedAt = new Date().toISOString();
+        this.rev++;
+        await this.persist();
+        return true;
+    }
+    /** 写穿持久化（串行链；失败降级内存态并告警一次，绝不抛出阻塞调用方）。 */
+    async persist() {
+        if (this.degraded)
+            return;
+        this.writeChain = this.writeChain.then(async () => {
+            const data = { version: SKILL_STORE_FILE_VERSION, rev: this.rev + 1, skills: this.skills, evidence: this.evidence };
+            try {
+                await ensureDir(path.dirname(this.file));
+                await atomicWriteText(this.file, JSON.stringify(data, null, 2));
+                this.rev = data.rev;
+            }
+            catch (err) {
+                this.degraded = err instanceof Error ? err.message : String(err);
+                if (!this.degradedLogged) {
+                    this.degradedLogged = true;
+                    this.logger?.warn(`[memory] 技能存储写入失败，只读降级: ${this.degraded}`);
+                }
+            }
+        });
+        await this.writeChain;
+    }
+}

package/dist/store/sqlite.d.ts

@@ -198,6 +198,11 @@ export declare class MemoryDb {
      */
     clearL1(): boolean;
     countL1(): number;
+    /**
+     * 按外部导入幂等键查已存在记录 id(轨3-P0 幂等 pre-check)。
+     * 空键/降级一律返回 undefined;未迁移旧库(无 ext_key 列)由 catch 兜底 undefined(fail-open)。
+     */
+    findRecordIdByExtKey(extKey: string): string | undefined;
     /**
      * 游标分批取 L1 元信息(**仅三列**):后台巡检专用。
      *

package/dist/store/sqlite.js

@@ -318,6 +318,14 @@ export class MemoryDb {
             this.db.exec("ALTER TABLE l1_records ADD COLUMN applicability TEXT NOT NULL DEFAULT ''");
             this.logger?.info(`${TAG} l1_records 补 repo 归属列(DEFAULT 即标注,存量零回填)`);
         }
+        // ── 外部导入幂等键(轨3-P0):ext_key='' 即内部记录(不参与去重),DEFAULT '' 存量零搬运。
+        // 部分唯一索引只约束非空值——多条内部记录 ext_key 同为 '' 互不冲突;仅当外部导入的
+        // 同一 (来源, 稳定身份) 重复导入才被结构性拒绝(写侧 pre-check + 索引双保险)。
+        if (!this.hasColumn('l1_records', 'ext_key')) {
+            this.db.exec("ALTER TABLE l1_records ADD COLUMN ext_key TEXT NOT NULL DEFAULT ''");
+            this.logger?.info(`${TAG} l1_records 补 ext_key 列(外部导入幂等键)`);
+        }
+        this.db.exec("CREATE UNIQUE INDEX IF NOT EXISTS l1_records_ext_key_uidx ON l1_records(ext_key) WHERE ext_key <> ''");
         // L2 场景重聚类作业队列(治理 W3 T3.10;ruminate 空闲档消费,每轮至多 1 作业)。
         // source 区分触发来源('demote'|'repo-change'),便于诊断与重入队语义区分。
         this.db.exec(`
@@ -434,8 +442,8 @@ export class MemoryDb {
         record_id, content, type, priority, scene_name, session_id, version,
         timestamp_str, timestamp_start, timestamp_end, created_time, updated_time, metadata_json, family,
         valid_from, valid_to, persistence, scope, workspace_id,
-        repo_key_name, repo_key_owner, applicability
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        repo_key_name, repo_key_owner, applicability, ext_key
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       ON CONFLICT(record_id) DO UPDATE SET
         content=excluded.content,
         type=excluded.type,
@@ -455,7 +463,8 @@ export class MemoryDb {
         workspace_id=excluded.workspace_id,
         repo_key_name=excluded.repo_key_name,
         repo_key_owner=excluded.repo_key_owner,
-        applicability=excluded.applicability
+        applicability=excluded.applicability,
+        ext_key=excluded.ext_key
     `);
         this.stmtGetL1 = this.db.prepare(`
       SELECT record_id, content, type, priority, scene_name, version, timestamp_str,
@@ -907,7 +916,7 @@ export class MemoryDb {
         // 旧版导入都会经这里写回记录,若照常重建 FTS/向量行,一条带退场标记的记录
         // 会**悄悄回到检索结果里**(而检索侧刻意不看 valid_to,正是为了零漂移)。
         const retiredNow = record.validTo !== undefined || readSupersedeMarker(record.metadata) !== undefined;
-        this.stmtUpsertL1.run(record.id, record.content, type, priority, sceneName, record.sessionId ?? 'default', record.version ?? 0, ts.str, ts.start, ts.end, toIso(record.createdAt), toIso(record.updatedAt), JSON.stringify(record.metadata ?? {}), family, toIso(record.validFrom), toIso(record.validTo), normPersistence(record.persistence) ?? '', scope, workspaceId, record.repoKeyName ?? '', record.repoKeyOwner ?? '', normApplicability(record.applicability));
+        this.stmtUpsertL1.run(record.id, record.content, type, priority, sceneName, record.sessionId ?? 'default', record.version ?? 0, ts.str, ts.start, ts.end, toIso(record.createdAt), toIso(record.updatedAt), JSON.stringify(record.metadata ?? {}), family, toIso(record.validFrom), toIso(record.validTo), normPersistence(record.persistence) ?? '', scope, workspaceId, record.repoKeyName ?? '', record.repoKeyOwner ?? '', normApplicability(record.applicability), record.extKey ?? '');
         // vec0 不支持 ON CONFLICT → 先删后插;零向量跳过(cosine 未定义)。
         // 已退场则**只删不插**(见上方 retiredNow 的说明)。
         if (this.stmtDeleteL1Vec && this.stmtInsertL1Vec) {
@@ -1134,6 +1143,23 @@ export class MemoryDb {
             return 0;
         }
     }
+    /**
+     * 按外部导入幂等键查已存在记录 id(轨3-P0 幂等 pre-check)。
+     * 空键/降级一律返回 undefined;未迁移旧库(无 ext_key 列)由 catch 兜底 undefined(fail-open)。
+     */
+    findRecordIdByExtKey(extKey) {
+        if (this.degraded || !extKey)
+            return undefined;
+        try {
+            const row = this.db
+                .prepare("SELECT record_id FROM l1_records WHERE ext_key = ? AND ext_key <> '' LIMIT 1")
+                .get(extKey);
+            return row?.record_id;
+        }
+        catch {
+            return undefined;
+        }
+    }
     /**
      * 游标分批取 L1 元信息(**仅三列**):后台巡检专用。
      *