dsh-prime-memory 0.22.1 → 0.22.2

package/dist/store/file-versions.js

@@ -21,6 +21,8 @@ export const SESSION_MODES_FILE_VERSION = 1;
 export const OCCUPANCY_FILE_VERSION = 1;
 /** `recall-dedupe.json`。 */
 export const RECALL_DEDUPE_FILE_VERSION = 1;
+/** `session-recalled.json`（G-live 活召回集，持久化以令旧会话重开可读）。 */
+export const SESSION_RECALLED_FILE_VERSION = 1;
 /** `pending.json`。 */
 export const PENDING_FILE_VERSION = 1;
 /** `reconcile-state.json`。 */

package/dist/store/l1.d.ts

@@ -142,6 +142,8 @@ export declare class L1Store {
     };
     /** 按 id 精确取记录(去重决策的版本号查询用,避免全表扫描)。 */
     getByIds(ids: string[]): MemoryRecord[];
+    /** 外部导入幂等 pre-check(轨3-P0):ext_key 命中已存在记录则返回其 id,否则 undefined。 */
+    findIdByExtKey(extKey: string): string | undefined;
     /**
      * §B 决策凭证落盘(L1Store 的薄缝)。
      * 刻意放在 store 上:`runExtraction` 已经持有 L1Store,凭证写入因此无需新增

package/dist/store/l1.js

@@ -229,6 +229,10 @@ export class L1Store {
     getByIds(ids) {
         return this.db.getL1ByIds(ids);
     }
+    /** 外部导入幂等 pre-check(轨3-P0):ext_key 命中已存在记录则返回其 id,否则 undefined。 */
+    findIdByExtKey(extKey) {
+        return this.db.findRecordIdByExtKey(extKey);
+    }
     /**
      * §B 决策凭证落盘(L1Store 的薄缝)。
      * 刻意放在 store 上:`runExtraction` 已经持有 L1Store,凭证写入因此无需新增

package/dist/store/memory-sources.d.ts

@@ -0,0 +1,59 @@
+import type { MemoryLogger } from '../types.js';
+/** sidecar 版本常量（file-versions 同款集中纪律）。 */
+export declare const MEMORY_SOURCES_FILE_VERSION: 1;
+/** 已知外部 agent 来源类别（与 memport foreign-agent.md 对齐）；'file' = 任意路径。 */
+export declare const SOURCE_KINDS: readonly ["trae", "qoder", "codex", "claude", "workbuddy", "golutra", "cursor", "file"];
+export type SourceKind = (typeof SOURCE_KINDS)[number];
+export interface MemorySourceEntry {
+    /** 稳定 id（小写字母数字连字符）；扫描/导入按此归类、支持按来源撤销。 */
+    id: string;
+    kind: SourceKind;
+    /** 路径指针（绝对路径/目录），正文永不复制进来。 */
+    path: string;
+    label?: string;
+    /** 最近一次扫描时间（ISO）；未扫为空。 */
+    lastScanAt: string;
+    /** 最近一次导入时间（ISO）；未导入为空。 */
+    lastImportAt: string;
+    /** 用户临时停用（保留条目但不参与自动扫描；≠ 删除）。 */
+    disabled: boolean;
+    status: 'active' | 'retired';
+    createdAt: string;
+    updatedAt: string;
+}
+export type MemorySourceInput = Pick<MemorySourceEntry, 'id' | 'kind' | 'path'> & Partial<Pick<MemorySourceEntry, 'label'>>;
+export declare class MemorySourceStore {
+    private readonly logger?;
+    private readonly file;
+    private entries;
+    private rev;
+    private loaded;
+    private degraded;
+    private degradedLogged;
+    private writeChain;
+    constructor(dataDir: string, logger?: MemoryLogger | undefined);
+    /** 载入（启动 await 一次）。缺失 = 合法空表；损坏 = 只读降级（回退"无来源"）。 */
+    init(): Promise<void>;
+    private ensureLoaded;
+    /** 全量条目（含 retired；副本返回，活引用纪律）。 */
+    list(): MemorySourceEntry[];
+    /** active 且未停用的来源（扫描/导入遍历用）。 */
+    listEnabled(): MemorySourceEntry[];
+    byId(id: string): MemorySourceEntry | undefined;
+    /** 登记来源（幂等：同 id 已存在则原地补全 kind/path/label，不新建）。上限防刷。 */
+    register(input: MemorySourceInput): Promise<{
+        entry: MemorySourceEntry;
+        created: boolean;
+    }>;
+    /** 记一次扫描时间。 */
+    markScanned(id: string, at: string): Promise<boolean>;
+    /** 记一次导入时间。 */
+    markImported(id: string, at: string): Promise<boolean>;
+    /** 启用/停用（停用保留条目、只是不参与自动扫描）。 */
+    setDisabled(id: string, disabled: boolean): Promise<boolean>;
+    /** 退役/恢复（status 迁移）。 */
+    setStatus(id: string, status: 'active' | 'retired'): Promise<boolean>;
+    private patch;
+    /** 写穿持久化（串行链；失败降级内存态并告警一次，绝不抛出阻塞调用方）。 */
+    private persist;
+}

package/dist/store/memory-sources.js

@@ -0,0 +1,214 @@
+/**
+ * 外部记忆来源注册表（轨3 Connect 路径的一等实体）。
+ *
+ * 动机：此前"其他 agent → 记忆库"的取内容路径只装配到 `memory_import` 这最后一寸，
+ * 前面十一寸（发现来源、记录来源、按来源管理）全外包给 skill 文本 + 用户手填路径。
+ * 本注册表把"来源"升为可持久、可枚举、可按来源撤销的一等实体。
+ *
+ * **路径指针不复制**（Connect 语义，援引 `slots.refs` 先例）：每条只存 `path` + 摘要，
+ * 正文**永不落进插件目录**——既是"移动房子家具先消毒"的卫生边界，也让带 ext_key 的
+ * 外部记忆"来源仍在、可重放"（可重建性显式化）。
+ *
+ * 存储：rooms-registry 同款 sidecar（`memory-sources.json`），全量载入内存 + 写穿原子持久化，
+ * `rev` 乐观计数。文件缺失 = 合法空表；损坏/不可读 → 告警 + 只读降级（内存态照常、停止回写），
+ * **绝不阻塞扫描/导入/面板**（降级即回退"无注册来源"，非破坏性）。上限防刷。
+ */
+import * as path from 'node:path';
+import { readJsonStrict, atomicWriteText, ensureDir } from '../util/io.js';
+/** sidecar 版本常量（file-versions 同款集中纪律）。 */
+export const MEMORY_SOURCES_FILE_VERSION = 1;
+/** 已知外部 agent 来源类别（与 memport foreign-agent.md 对齐）；'file' = 任意路径。 */
+export const SOURCE_KINDS = ['trae', 'qoder', 'codex', 'claude', 'workbuddy', 'golutra', 'cursor', 'file'];
+/** 来源上限（防刷；一个工作区通常 <20 个外部工具记忆落点）。 */
+const SOURCES_CAP = 100;
+const PATH_MAX = 500;
+const LABEL_MAX = 80;
+function isSourceId(s) {
+    return /^[a-z0-9][a-z0-9-]{0,63}$/.test(s);
+}
+function normKind(k) {
+    return SOURCE_KINDS.includes(String(k)) ? k : 'file';
+}
+export class MemorySourceStore {
+    logger;
+    file;
+    entries = [];
+    rev = 0;
+    loaded = false;
+    degraded;
+    degradedLogged = false;
+    writeChain = Promise.resolve();
+    constructor(dataDir, logger) {
+        this.logger = logger;
+        this.file = path.join(dataDir, 'memory-sources.json');
+    }
+    /** 载入（启动 await 一次）。缺失 = 合法空表；损坏 = 只读降级（回退"无来源"）。 */
+    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 !== MEMORY_SOURCES_FILE_VERSION) {
+            this.logger?.warn(`[memory] 外部来源注册表版本 ${String(read.value.version)} 未知，按当前形状读取`);
+        }
+        const sources = Array.isArray(read.value.sources) ? read.value.sources : [];
+        for (const s of sources) {
+            if (!s || typeof s.id !== 'string' || !isSourceId(s.id))
+                continue; // 非法 id 丢弃
+            if (typeof s.path !== 'string' || !s.path)
+                continue; // 无路径指针的来源无意义，丢弃
+            this.entries.push({
+                id: s.id,
+                kind: normKind(s.kind),
+                path: s.path.slice(0, PATH_MAX),
+                label: typeof s.label === 'string' ? s.label : undefined,
+                lastScanAt: typeof s.lastScanAt === 'string' ? s.lastScanAt : '',
+                lastImportAt: typeof s.lastImportAt === 'string' ? s.lastImportAt : '',
+                disabled: s.disabled === true,
+                status: s.status === 'retired' ? 'retired' : 'active',
+                createdAt: typeof s.createdAt === 'string' ? s.createdAt : '',
+                updatedAt: typeof s.updatedAt === 'string' ? s.updatedAt : '',
+            });
+        }
+        this.rev = typeof read.value.rev === 'number' ? read.value.rev : 0;
+        this.loaded = true;
+    }
+    ensureLoaded() {
+        if (!this.loaded)
+            throw new Error('外部来源注册表未初始化（先 await init()）');
+    }
+    /** 全量条目（含 retired；副本返回，活引用纪律）。 */
+    list() {
+        this.ensureLoaded();
+        return this.entries.map((e) => ({ ...e }));
+    }
+    /** active 且未停用的来源（扫描/导入遍历用）。 */
+    listEnabled() {
+        return this.list().filter((e) => e.status === 'active' && !e.disabled);
+    }
+    byId(id) {
+        this.ensureLoaded();
+        const found = this.entries.find((e) => e.id === id);
+        return found ? { ...found } : undefined;
+    }
+    /** 登记来源（幂等：同 id 已存在则原地补全 kind/path/label，不新建）。上限防刷。 */
+    async register(input) {
+        this.ensureLoaded();
+        const id = String(input.id ?? '').trim().toLowerCase();
+        if (!isSourceId(id))
+            throw new Error(`非法来源 id: ${String(input.id)}（小写字母数字连字符，≤64）`);
+        const p = String(input.path ?? '').trim();
+        if (!p)
+            throw new Error('来源 path 不能为空（路径指针不复制，但必须指向真实落点）');
+        if (p.length > PATH_MAX)
+            throw new Error(`来源 path 过长（>${PATH_MAX}）`);
+        const found = this.entries.find((e) => e.id === id);
+        if (found) {
+            let changed = false;
+            const kind = normKind(input.kind);
+            if (found.kind !== kind) {
+                found.kind = kind;
+                changed = true;
+            }
+            if (found.path !== p) {
+                found.path = p;
+                changed = true;
+            }
+            if (typeof input.label === 'string' && input.label.trim() && found.label !== input.label.trim().slice(0, LABEL_MAX)) {
+                found.label = input.label.trim().slice(0, LABEL_MAX);
+                changed = true;
+            }
+            if (found.status === 'retired') {
+                found.status = 'active';
+                changed = true;
+            }
+            if (changed) {
+                found.updatedAt = new Date().toISOString();
+                this.rev++;
+                await this.persist();
+            }
+            return { entry: { ...found }, created: false };
+        }
+        if (this.entries.length >= SOURCES_CAP)
+            throw new Error(`外部来源已达上限（${SOURCES_CAP}），请先退役部分来源`);
+        const now = new Date().toISOString();
+        const entry = {
+            id,
+            kind: normKind(input.kind),
+            path: p.slice(0, PATH_MAX),
+            label: typeof input.label === 'string' && input.label.trim() ? input.label.trim().slice(0, LABEL_MAX) : undefined,
+            lastScanAt: '',
+            lastImportAt: '',
+            disabled: false,
+            status: 'active',
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.entries.push(entry);
+        this.rev++;
+        await this.persist();
+        return { entry: { ...entry }, created: true };
+    }
+    /** 记一次扫描时间。 */
+    async markScanned(id, at) {
+        return this.patch(id, (e) => {
+            e.lastScanAt = at;
+        });
+    }
+    /** 记一次导入时间。 */
+    async markImported(id, at) {
+        return this.patch(id, (e) => {
+            e.lastImportAt = at;
+        });
+    }
+    /** 启用/停用（停用保留条目、只是不参与自动扫描）。 */
+    async setDisabled(id, disabled) {
+        return this.patch(id, (e) => {
+            e.disabled = disabled;
+        });
+    }
+    /** 退役/恢复（status 迁移）。 */
+    async setStatus(id, status) {
+        return this.patch(id, (e) => {
+            e.status = status;
+        });
+    }
+    async patch(id, mut) {
+        this.ensureLoaded();
+        const found = this.entries.find((e) => e.id === id);
+        if (!found)
+            return false;
+        mut(found);
+        found.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: MEMORY_SOURCES_FILE_VERSION, rev: this.rev + 1, sources: this.entries };
+            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/session-recalled.d.ts

@@ -0,0 +1,25 @@
+import type { MemoryLogger } from '../types.js';
+export declare class SessionRecalledStore {
+    private readonly logger?;
+    private readonly file;
+    private readonly entries;
+    private degraded;
+    private degradedLogged;
+    private lastPersisted;
+    private writeChain;
+    /** 脏检序号：每次真实变更 +1，投影 apply 据此 O(1) 判断是否重建。 */
+    private rev;
+    constructor(dataDir: string, logger?: MemoryLogger | undefined);
+    revision(): number;
+    private init;
+    /** 记入本 sessionKey 本轮实际注入的记录 id（写穿；插入序淘汰最旧）。 */
+    add(sessionKey: string, recordIds: readonly string[]): void;
+    list(sessionKey: string): string[];
+    /** 压缩/清空：注入内容已离开上下文，清该会话活召回集（写穿）。 */
+    reset(sessionKey: string): void;
+    size(): number;
+    /** 等待在途持久化写完成（测试/停机）。 */
+    flush(): Promise<void>;
+    private persist;
+    private serialize;
+}

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;
+}