dsh-prime-memory 0.22.1 → 0.22.2

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 元信息(**仅三列**):后台巡检专用。
      *

package/dist/tools/index.d.ts

@@ -1,16 +1,3 @@
-/**
- * 模型可调用工具:memory_search(L1)、conversation_search(L0)、memory_read_scene(L2/L3)、
- * 高权限 memory_add / memory_delete。
- *
- * 会话档位联动:execute 的 exec.agent 即发起调用的 agent(agent.id === sessionId),
- * memory_search 按会话档位过滤族(auto 不过滤,纯档只查本族);off 档下读类工具统一
- * 返回提示(本会话已对记忆系统隐身)。conversation_search 检索范围保持全库。
- * 只写会话(注入覆盖=关)同款拒读,notice 区分文案——写入走捕获钩子不经工具,
- * 拒读不影响"只写"语义。
- *
- * 写删工具受 live.memoryMutate 高权限门控(默认 false):显式记忆指令语义——
- * 用户说"记得 X" → memory_add;说"忘了/删除该记忆" → memory_delete。
- */
 import type { Context } from '@deepseek-ai/cordis';
 import type { MemoryConfig } from '../config.js';
 import type { LiveSettingsHandle } from '../settings.js';

package/dist/tools/index.js

@@ -1,3 +1,17 @@
+/**
+ * 模型可调用工具:memory_search(L1)、conversation_search(L0)、memory_read_scene(L2/L3)、
+ * 高权限 memory_add / memory_delete。
+ *
+ * 会话档位联动:execute 的 exec.agent 即发起调用的 agent(agent.id === sessionId),
+ * memory_search 按会话档位过滤族(auto 不过滤,纯档只查本族);off 档下读类工具统一
+ * 返回提示(本会话已对记忆系统隐身)。conversation_search 检索范围保持全库。
+ * 只写会话(注入覆盖=关)同款拒读,notice 区分文案——写入走捕获钩子不经工具,
+ * 拒读不影响"只写"语义。
+ *
+ * 写删工具受 live.memoryMutate 高权限门控(默认 false):显式记忆指令语义——
+ * 用户说"记得 X" → memory_add;说"忘了/删除该记忆" → memory_delete。
+ */
+import { createHash } from 'node:crypto';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { RECEIPTS_QUERY_LIMIT_MAX, dimensionOf, toReceiptView } from '../store/receipts.js';
 import { listConflictPairs, renderConflictResolution, renderConflicts, resolveConflictPair } from '../conflict-service.js';
@@ -491,7 +505,14 @@ roomRegistry) {
      * 时间轴同时写顶层字段(时间增强列)与 metadata(列迁移前的兼容层,
      * 也是面板与图谱时间锚的读取点);`cf`/`rw` 落在 metadata.conflict/rewritten。
      */
-    function buildRecord(item, sceneName, now, workspaceId) {
+    /** 外部导入幂等键:sha1(source_id \0 稳定身份)。身份取 dedupe_key,缺省用内容规范化。 */
+    const computeExtKey = (sourceId, item, content) => {
+        const identity = typeof item.dedupe_key === 'string' && item.dedupe_key.trim()
+            ? item.dedupe_key.trim()
+            : content.replace(/\s+/g, ' ').toLowerCase();
+        return createHash('sha1').update(`${sourceId}\u0000${identity}`, 'utf8').digest('hex');
+    };
+    function buildRecord(item, sceneName, now, workspaceId, sourceId) {
         const content = String(item.content ?? '').trim();
         const type = ADD_TYPES.includes(String(item.type ?? '')) ? String(item.type) : 'episodic';
         const family = type.startsWith('work') ? 'work' : 'chat';
@@ -536,6 +557,7 @@ roomRegistry) {
             ...(validFrom !== undefined ? { validFrom } : {}),
             ...(validTo !== undefined ? { validTo } : {}),
             ...(persistence !== undefined ? { persistence } : {}),
+            ...(sourceId && sourceId.trim() ? { extKey: computeExtKey(sourceId.trim(), item, content) } : {}),
         };
     }
     /** 时间轴/溯源字段的可选入参(两个写工具共用同一形状)。 */
@@ -618,6 +640,10 @@ roomRegistry) {
                         },
                         ...writeFields,
                         priority: { type: 'number', description: '优先级 0-100(缺省 80)' },
+                        dedupe_key: {
+                            type: 'string',
+                            description: '可选稳定身份(外部包内该条的稳定 id);与顶层 source_id 组合算幂等键,缺省用内容规范化哈希',
+                        },
                     },
                 },
             },
@@ -625,12 +651,17 @@ roomRegistry) {
                 type: 'string',
                 description: `归属场景名(缺省 ${DEFAULT_IMPORT_SCENE};建议用"${DEFAULT_IMPORT_SCENE}/<来源>")`,
             },
+            source_id: {
+                type: 'string',
+                description: '来源标识(如 "workbuddy"/"claude-code"/外部包名);非空时启用幂等——同一来源重复导入相同 dedupe_key/内容会被跳过并计入 deduped',
+            },
         },
         output: {
             schema: {
                 type: 'object',
                 properties: {
                     written: { type: 'number' },
+                    deduped: { type: 'number' },
                     ids: { type: 'array', items: { type: 'string' } },
                     skipped: {
                         type: 'array',
@@ -653,15 +684,16 @@ roomRegistry) {
         },
         execute: async (args, exec) => {
             if (!live.get().memoryMutate) {
-                return { written: 0, ids: [], skipped: [], notice: MUTATE_OFF_NOTICE };
+                return { written: 0, deduped: 0, ids: [], skipped: [], notice: MUTATE_OFF_NOTICE };
             }
             const raw = Array.isArray(args.records) ? args.records : [];
             if (raw.length === 0) {
-                return { written: 0, ids: [], skipped: [], notice: 'records 为空,未写入' };
+                return { written: 0, deduped: 0, ids: [], skipped: [], notice: 'records 为空,未写入' };
             }
             if (raw.length > MAX_IMPORT) {
                 return {
                     written: 0,
+                    deduped: 0,
                     ids: [],
                     skipped: [],
                     notice: `单次上限 ${MAX_IMPORT} 条(收到 ${raw.length} 条),请拆批导入`,
@@ -670,10 +702,13 @@ roomRegistry) {
             const scene = typeof args.scene === 'string' && args.scene.trim()
                 ? args.scene.trim().slice(0, 120)
                 : DEFAULT_IMPORT_SCENE;
+            const sourceId = typeof args.source_id === 'string' ? args.source_id.trim() : '';
             const now = Date.now();
             const seen = new Set();
+            const seenExt = new Set();
             const records = [];
             const skipped = [];
+            let deduped = 0;
             raw.forEach((item, index) => {
                 const content = String(item?.content ?? '').trim();
                 if (!content) {
@@ -686,14 +721,30 @@ roomRegistry) {
                     return;
                 }
                 seen.add(key);
-                const record = buildRecord(item, scene, now, workspaceIdOf(exec));
+                // 幂等(轨3-P0):带 source_id 时按 ext_key 拦截重复——先查库内、再查本批，
+                // 命中即计入 deduped 并跳过(不写 JSONL、不写检索库)。无 source_id 保持既有逐字行为。
+                if (sourceId) {
+                    const extKey = computeExtKey(sourceId, item, content);
+                    if (seenExt.has(extKey)) {
+                        deduped++;
+                        skipped.push({ index, reason: '与本批前面的记录外部键重复(幂等跳过)' });
+                        return;
+                    }
+                    if (stores.l1.findIdByExtKey(extKey)) {
+                        deduped++;
+                        skipped.push({ index, reason: '库内已存在同外部键记录(幂等跳过)' });
+                        return;
+                    }
+                    seenExt.add(extKey);
+                }
+                const record = buildRecord(item, scene, now, workspaceIdOf(exec), sourceId);
                 applyManualRedaction(record, cfg, logger);
                 records.push(record);
             });
             if (records.length > 0)
                 await stores.l1.appendNew(records);
-            logger.info(`[memory] 批量导入 ${records.length} 条(跳过 ${skipped.length} 条,场景 ${scene})`);
-            return { written: records.length, ids: records.map((r) => r.id), skipped };
+            logger.info(`[memory] 批量导入 ${records.length} 条(幂等跳过 ${deduped} 条,场景 ${scene}${sourceId ? `,来源 ${sourceId}` : ''})`);
+            return { written: records.length, deduped, ids: records.map((r) => r.id), skipped };
         },
     })));
     // memory_delete:显式"忘了 X"——按语义检索命中后删除(高权限门控)。
@@ -1222,7 +1273,7 @@ roomRegistry) {
             if (family === null) {
                 return { enabled: false, total: 0, items: [], notice: blockNoticeOf(exec) };
             }
-            return listConflictPairs({ l1: stores.l1, conflictFreezeEnabled: live.get().conflictFreeze === true }, { limit: typeof args.limit === 'number' ? args.limit : undefined });
+            return listConflictPairs({ l1: stores.l1, conflictFreezeEnabled: live.get().conflictFreeze === true, decayHalfLifeDays: cfg.recall?.decayHalfLifeDays }, { limit: typeof args.limit === 'number' ? args.limit : undefined });
         },
     })));
     // ── memory_conflicts_rejected: §C 丢弃留痕的读出口 ──

package/dist/tools/skills.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 技能工具面（轨2）。**整块仅在 cfg.skills.enabled 时注册**——默认关时零表面积
+ * （对齐 benchControl"生产部署零表面积"先例，避免注册了却被门控的空壳工具污染模型工具列表）。
+ *
+ * 读工具 list/read；写工具 pin/archive 过 live.memoryMutate 高权限门（与 memory_add 同门）。
+ * 技能不是 memory `type`，这些工具只操作 SkillStore sidecar，不触碰 l1_records / ADD_TYPES / prompt 词表。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { MemoryConfig } from '../config.js';
+import type { LiveSettingsHandle } from '../settings.js';
+import type { SkillStore } from '../store/skill-store.js';
+import type { MemoryLogger } from '../types.js';
+export declare function registerSkillTools(ctx: Context, cfg: MemoryConfig, skills: SkillStore, logger: MemoryLogger, live: LiveSettingsHandle): void;