dsh-prime-memory 0.25.0 → 0.26.0

package/dist/stats.js

@@ -32,8 +32,9 @@ import { WING_CATALOG, WING_FALLBACK } from './types.js';
 import { isRoomSlug } from './metadata-validators.js';
 import { InProcMemoryBackend } from './store/memory-backend.js';
 import { isWingCorner } from './store/session-modes.js';
-import { startWingBackfill } from './wing-backfill.js';
+import { startWingBackfill, wingBackfillState } from './wing-backfill.js';
 import { startKeywordBackfill, keywordBackfillState } from './keyword-backfill.js';
+import { startRedistillBackfill, redistillBackfillState } from './redistill-backfill.js';
 import { errDetail } from './util/filelog.js';
 import { snapshotTokenCost } from './token-cost.js';
 import { computeMaturity } from './util/maturity.js';
@@ -42,13 +43,31 @@ import { relinkWorkspaces } from './pipeline/workspace-relink.js';
 import { reconcileLedger } from './store/memory-md-export.js';
 import { mdRunStatus, runProjection } from './store/memory-md-run.js';
 import { disableProjectionFile } from './store/memory-md-disable.js';
-import { MEMORY_TYPE_DIRS, UNSORTED_DIR, resolveMemoriesRoot, targetFor } from './store/memory-md.js';
+import { MEMORY_TYPE_DIRS, UNSORTED_DIR, resolveMemoriesRoot, targetFor, relPathFor } from './store/memory-md.js';
 import { ensureTypeSkeleton } from './store/memory-md-skeleton.js';
 import { sweepOrphanFiles } from './store/memory-md-orphan.js';
 import { collectProjectionFiles } from './store/memory-md-archive.js';
 import { syncFromFiles } from './pipeline/md-sync.js';
 const require = createRequire(import.meta.url);
 export const PLUGIN_VERSION = require('../package.json').version;
+/**
+ * 批扫模块的内部状态 → 契约进度体（keyword 与 redistill 同形状，故共用一个映射）。
+ *
+ * 写成显式字段而不是 `as`：两边 state 类型各自演化时，这里漏一个字段就是编译错，
+ * 而强转会造出一个能编译、但面板上永远显示旧值的进度。
+ */
+function backfillProgress(s) {
+    return {
+        chunk: s.chunk,
+        candidates: s.candidates,
+        processed: s.processed,
+        scanning: s.scanning,
+        batchesDone: s.batchesDone,
+        batchTotal: s.batchTotal,
+        concurrency: s.concurrency,
+        deferred: s.deferred,
+    };
+}
 /**
  * 端点全集运行时清单(与 tests/contract-keys.test.ts 的 ENDPOINTS 及
  * contract.ts 类型映射表三方对齐,漂移由键集 diff 测试暴露)。
@@ -72,10 +91,12 @@ export const MEMORY_ENDPOINTS = [
     'dsh-memory/room-admin',
     'dsh-memory/wing-backfill',
     'dsh-memory/keyword-backfill',
+    'dsh-memory/redistill-backfill',
     'dsh-memory/session-stats',
     'dsh-memory/settings-get',
     'dsh-memory/settings-set',
     'dsh-memory/list-records',
+    'dsh-memory/records-meta',
     'dsh-memory/records-delete',
     'dsh-memory/receipts',
     'dsh-memory/conflicts',
@@ -633,10 +654,11 @@ export async function handleEndpoint(endpoint, payload, deps) {
         case 'dsh-memory/mem-sync': {
             // P2 反向同步：文件 → 库。与导出的**风险不对称**——导出只写文件，本项会写库，
             // 所以多两道门：要先开投射（没导出过 = 账本为空 = 判不出“谁变了”），要高权限。
-            const syn = cfg.mdSync;
+            const ec = effectiveCfg(cfg, live);
+            const syn = ec.mdSync;
             if (syn?.enabled !== true)
-                throw new Error('md 反向同步未开启（cfg.mdSync.enabled）');
-            if (cfg.memExport?.enabled !== true)
+                throw new Error('md 反向同步未开启（概览页开关，或 config mdSync.enabled）');
+            if (ec.memExport?.enabled !== true)
                 throw new Error('md 反向同步需先开启 md 投射（cfg.memExport.enabled）');
             if (!live?.get().memoryMutate)
                 throw new Error('记忆写删未开放：请在记忆库面板开启「高权限模式」后才能回灌文件侧修改。');
@@ -794,7 +816,7 @@ export async function handleEndpoint(endpoint, payload, deps) {
         }
         // ── 轨3 外部记忆来源（Connect）：登记/列表/退役/只读扫描。整面默认关（cfg.memport.enabled）。
         case 'dsh-memory/memory-sources-list': {
-            const enabled = cfg.memport?.enabled === true;
+            const enabled = effectiveCfg(cfg, live).memport?.enabled === true;
             const v = {
                 sources: enabled && memorySources
                     ? memorySources.list().map((e) => ({
@@ -813,8 +835,8 @@ export async function handleEndpoint(endpoint, payload, deps) {
             return v;
         }
         case 'dsh-memory/memory-sources-add': {
-            if (cfg.memport?.enabled !== true)
-                throw new Error('外部记忆来源未启用（config memport.enabled）。');
+            if (effectiveCfg(cfg, live).memport?.enabled !== true)
+                throw new Error('外部记忆来源未启用（概览页开关，或 config memport.enabled）。');
             if (!memorySources)
                 throw new Error('外部来源注册表未装配（需要插件重载以初始化）。');
             if (!live?.get().memoryMutate)
@@ -834,8 +856,8 @@ export async function handleEndpoint(endpoint, payload, deps) {
             return v;
         }
         case 'dsh-memory/memory-sources-retire': {
-            if (cfg.memport?.enabled !== true)
-                throw new Error('外部记忆来源未启用（config memport.enabled）。');
+            if (effectiveCfg(cfg, live).memport?.enabled !== true)
+                throw new Error('外部记忆来源未启用（概览页开关，或 config memport.enabled）。');
             if (!memorySources)
                 throw new Error('外部来源注册表未装配（需要插件重载以初始化）。');
             if (!live?.get().memoryMutate)
@@ -853,8 +875,8 @@ export async function handleEndpoint(endpoint, payload, deps) {
             return v;
         }
         case 'dsh-memory/memport-scan': {
-            if (cfg.memport?.enabled !== true) {
-                const v = { enabled: false, sources: [], notice: '外部记忆扫描未启用（config memport.enabled）。' };
+            if (effectiveCfg(cfg, live).memport?.enabled !== true) {
+                const v = { enabled: false, sources: [], notice: '外部记忆扫描未启用（概览页开关，或 config memport.enabled）。' };
                 return v;
             }
             if (!memorySources) {
@@ -864,7 +886,7 @@ export async function handleEndpoint(endpoint, payload, deps) {
             const p = (payload ?? {});
             const all = memorySources.listEnabled();
             const targets = p.sourceId ? all.filter((e) => e.id === p.sourceId) : all;
-            const maxRecords = cfg.memport?.scanMaxRecords ?? 5000;
+            const maxRecords = effectiveCfg(cfg, live).memport?.scanMaxRecords ?? 5000;
             // 只读扫描：不写库（写走 memory_import）。逐个标扫描时间（失败不影响预览）。
             const sources = await scanSources({ sources: targets, l1: stores.l1, maxRecords });
             const nowIso = new Date().toISOString();
@@ -1134,6 +1156,10 @@ export async function handleEndpoint(endpoint, payload, deps) {
             return v;
         }
         case 'dsh-memory/wing-backfill': {
+            // probe=true 只读快照：不启动（UI 离开区域再回来时恢复在途任务用）。
+            if (payload?.probe === true) {
+                return { started: false, running: wingBackfillState().running };
+            }
             const r = startWingBackfill({
                 ctx: deps.ctx,
                 cfg: deps.cfg,
@@ -1143,17 +1169,47 @@ export async function handleEndpoint(endpoint, payload, deps) {
             return r;
         }
         case 'dsh-memory/keyword-backfill': {
-            // 门控关：不启动，如实报 enabled=false（面板据此提示“先开关键词回填开关”）。
-            if (!cfg.keyword?.enabled)
-                return { started: false, running: false, enabled: false, updated: 0, failed: 0 };
+            // 门控看生效配置（live.keywordEnabled 覆盖部署 cfg.keyword.enabled）；关时不启动。
+            const ec = effectiveCfg(cfg, live);
+            const st0 = keywordBackfillState();
+            // probe=true 只读快照：不启动（UI 离开区域再回来时恢复在途任务用）。
+            if (payload?.probe === true) {
+                return { started: false, running: st0.running, enabled: ec.keyword?.enabled === true, updated: st0.updated, failed: st0.failed, progress: backfillProgress(st0) };
+            }
+            if (!ec.keyword?.enabled)
+                return { started: false, running: false, enabled: false, updated: 0, failed: 0, progress: backfillProgress(st0) };
             const r = startKeywordBackfill({
                 ctx: deps.ctx,
-                cfg: deps.cfg,
+                cfg: ec,
                 backend: stores.backend ?? new InProcMemoryBackend(stores.l1),
                 logger: deps.logger,
+                // 运行时并发读取器：拖概览页滑块对**正在跑**的任务即时生效（弹性池每完成一条重读）。
+                concurrency: () => effectiveCfg(cfg, live).backfill?.concurrency,
             });
             const st = keywordBackfillState();
-            return { started: r.started, running: r.running, enabled: true, updated: st.updated, failed: st.failed };
+            return { started: r.started, running: r.running, enabled: true, updated: st.updated, failed: st.failed, progress: backfillProgress(st) };
+        }
+        case 'dsh-memory/redistill-backfill': {
+            // 门控看生效配置（live.redistillEnabled 覆盖部署 cfg.redistill.enabled）；关时不启动。
+            const ec = effectiveCfg(cfg, live);
+            const st0 = redistillBackfillState();
+            // probe=true 只读快照：不启动（UI 离开区域再回来时恢复在途任务用）。
+            if (payload?.probe === true) {
+                return { started: false, running: st0.running, enabled: ec.redistill?.enabled === true, updated: st0.updated, skipped: st0.skipped, failed: st0.failed, progress: backfillProgress(st0) };
+            }
+            if (!ec.redistill?.enabled)
+                return { started: false, running: false, enabled: false, updated: 0, skipped: 0, failed: 0, progress: backfillProgress(st0) };
+            // 改 content 需进程内重嵌 + 追加 JSONL + 投射点火，直取 stores.l1（不经 worker backend）。
+            const r = startRedistillBackfill({
+                ctx: deps.ctx,
+                cfg: ec,
+                l1: stores.l1,
+                logger: deps.logger,
+                // 运行时并发读取器：拖概览页滑块对**正在跑**的任务即时生效（弹性池每完成一条重读）。
+                concurrency: () => effectiveCfg(cfg, live).backfill?.concurrency,
+            });
+            const st = redistillBackfillState();
+            return { started: r.started, running: r.running, enabled: true, updated: st.updated, skipped: st.skipped, failed: st.failed, progress: backfillProgress(st) };
         }
         // ── 会话级统计(悬浮卡信息区;热路径端点,见 SessionInfoSource 的零 I/O 硬规则) ──
         case 'dsh-memory/session-stats': {
@@ -1264,7 +1320,12 @@ export async function handleEndpoint(endpoint, payload, deps) {
                     memoryMutate: false,
                     conflictFreeze: live?.get()?.conflictFreeze === true,
                     skillsEnabled: live?.get()?.skillsEnabled === true,
+                    keywordEnabled: live?.get()?.keywordEnabled === true,
+                    redistillEnabled: live?.get()?.redistillEnabled === true,
+                    mdSyncEnabled: live?.get()?.mdSyncEnabled === true,
+                    memportEnabled: live?.get()?.memportEnabled === true,
                     mdExportMaxRecords: live?.get()?.mdExportMaxRecords ?? 0,
+                    backfillConcurrency: live?.get()?.backfillConcurrency ?? 0,
                 }),
                 // 静态部署上限(cordis.patch.yml):运行时开关与它取 AND
                 ceilings: { capture: cfg.capture.enabled, distill: cfg.extract.enabled, recall: cfg.recall.enabled },
@@ -1303,7 +1364,7 @@ export async function handleEndpoint(endpoint, payload, deps) {
             const patch = (payload ?? {});
             const clean = {};
             // 布尔开关组:memoryMutate(高权限写删门)与主开关同列;conflictFreeze(§C 人工冲突裁决)
-            for (const key of ['enabled', 'capture', 'distill', 'recall', 'memoryMutate', 'conflictFreeze', 'skillsEnabled', 'toolRoom', 'toolGraph', 'toolRuminate', 'toolConflict', 'toolMutate']) {
+            for (const key of ['enabled', 'capture', 'distill', 'recall', 'memoryMutate', 'conflictFreeze', 'skillsEnabled', 'keywordEnabled', 'redistillEnabled', 'mdSyncEnabled', 'memportEnabled', 'toolRoom', 'toolGraph', 'toolRuminate', 'toolConflict', 'toolMutate']) {
                 if (typeof patch[key] === 'boolean')
                     clean[key] = patch[key];
             }
@@ -1312,6 +1373,11 @@ export async function handleEndpoint(endpoint, payload, deps) {
             if (typeof patch.mdExportMaxRecords === 'number' && Number.isFinite(patch.mdExportMaxRecords)) {
                 clean.mdExportMaxRecords = Math.min(10_000, Math.max(0, Math.floor(patch.mdExportMaxRecords)));
             }
+            // 回填并行度运行时覆盖（概览页滑块）：不收白名单 = “写成功但被静默丢”，
+            // 而用户会拿着“并行 1”的 UI 去判断串行跑的结果——比没有这个旋钮更坏。
+            if (typeof patch.backfillConcurrency === 'number' && Number.isFinite(patch.backfillConcurrency)) {
+                clean.backfillConcurrency = Math.min(8, Math.max(0, Math.floor(patch.backfillConcurrency)));
+            }
             // 运行时统一路由链：结构校验后整体写入（空数组 = 回到跟随部署配置）
             if (patch.distillChain !== undefined) {
                 const err = validateDistillChain(patch.distillChain);
@@ -1630,6 +1696,37 @@ export async function handleEndpoint(endpoint, payload, deps) {
                 })),
             };
         }
+        case 'dsh-memory/records-meta': {
+            const p = (payload ?? {});
+            if (!Array.isArray(p.ids) || p.ids.length === 0)
+                throw new Error('ids 必须是非空字符串数组');
+            const ids = p.ids.filter((x) => typeof x === 'string' && x.length > 0).slice(0, 50);
+            if (ids.length === 0)
+                throw new Error('ids 过滤后为空');
+            const records = stores.l1.getByIds(ids);
+            const items = records.map((r) => {
+                // 与写盘、槽位投影同一算法，不各自抄一份清洗规则。
+                const filePath = relPathFor(r);
+                return {
+                    id: r.id,
+                    name: r.name ?? null,
+                    type: r.type,
+                    priority: r.priority,
+                    content: r.content,
+                    maturity: computeMaturity({ priority: r.priority, usage: null, agingWeight: null, mark: null }),
+                    createdAt: r.createdAt ? new Date(r.createdAt).toISOString() : null,
+                    updatedAt: r.updatedAt ? new Date(r.updatedAt).toISOString() : null,
+                    scene: r.scene_name,
+                    scope: (r.scope === 'workspace' ? 'workspace' : 'global'),
+                    workspaceId: r.scope === 'workspace' ? (r.workspaceId ?? '') || null : null,
+                    ...(Array.isArray(r.metadata?.dsh_keywords) ? { keywords: r.metadata.dsh_keywords.filter((k) => typeof k === 'string' && k !== '') } : {}),
+                    ...(Array.isArray(r.metadata?.dsh_usage_scenario) ? { usageScenario: r.metadata.dsh_usage_scenario } : {}),
+                    filePath,
+                    retired: r.validTo !== undefined,
+                };
+            });
+            return { items };
+        }
         case 'dsh-memory/records-delete': {
             // 面板高权限删除指定记忆;写入删权限门(memoryMutate)防御。
             //

package/dist/store/l1.d.ts

@@ -122,6 +122,18 @@ export declare class L1Store {
      * 配套写回必须用 `patchMetadata()` —— 本方法拿不到 content,用 upsert 会把正文清空。
      */
     allLite(limit: number, offset: number): L1MetaLite[];
+    /**
+     * 游标分批取**活跃**记录的骨架判定输入（含 content）——redistill 扫描阶段专用。
+     *
+     * 与 `allLite` 的分工：本方法**只为读**（判骨架），写回仍走 `appendNew`（改正文）/
+     * `patchMetadata`（只打标）——不得拿本投影去 upsert，退场行已被 SQL 排除。
+     */
+    activeForSkeleton(limit: number, offset: number): Array<{
+        id: string;
+        type: string;
+        content: string;
+        metadata: Record<string, unknown>;
+    }>;
     /**
      * 只更新 metadata_json 的最小写回(不动 content 与其它列)。
      * 返回 false 表示 id 不存在或写入失败——调用方须记账,不许静默。

package/dist/store/l1.js

@@ -149,6 +149,15 @@ export class L1Store {
     allLite(limit, offset) {
         return this.db.getAllL1Lite(limit, offset);
     }
+    /**
+     * 游标分批取**活跃**记录的骨架判定输入（含 content）——redistill 扫描阶段专用。
+     *
+     * 与 `allLite` 的分工：本方法**只为读**（判骨架），写回仍走 `appendNew`（改正文）/
+     * `patchMetadata`（只打标）——不得拿本投影去 upsert，退场行已被 SQL 排除。
+     */
+    activeForSkeleton(limit, offset) {
+        return this.db.getActiveL1ForSkeleton(limit, offset);
+    }
     /**
      * 只更新 metadata_json 的最小写回(不动 content 与其它列)。
      * 返回 false 表示 id 不存在或写入失败——调用方须记账,不许静默。

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

@@ -105,6 +105,14 @@ export declare function recordDigest(r: Pick<MemoryRecord, 'content'>): string;
  * 免得后来人以为"回落名也能双向"。
  */
 export declare function fileStemFor(r: Pick<MemoryRecord, 'id' | 'name' | 'content'>): string;
+/**
+ * 一条记录的投射相对路径 `<dir>/<stem>.memory.md`（分隔符恒 `/`）。
+ *
+ * 单一事实源：`renderRecord` 写盘、`dsh-memory/records-meta` 端点、槽位投影的
+ * `refViews.filePath` 都走这里。各自抄一份清洗规则必然漂移——漂移之后「投影给的地址」
+ * 和「磁盘上的真文件」对不上，而这三处本来就是给人核对同一个事实用的。
+ */
+export declare function relPathFor(r: Pick<MemoryRecord, 'id' | 'name' | 'content' | 'type'>): string;
 /**
  * 渲染一条记录。
  *

package/dist/store/memory-md.js

@@ -184,6 +184,17 @@ export function fileStemFor(r) {
     // 借 sanitizeFilename 的字符/保留名纪律，再剥掉它补的 .md（我们后面统一补）。
     return sanitizeFilename(base).replace(/\.md$/i, '') || `mem-${r.id.slice(-8)}`;
 }
+/**
+ * 一条记录的投射相对路径 `<dir>/<stem>.memory.md`（分隔符恒 `/`）。
+ *
+ * 单一事实源：`renderRecord` 写盘、`dsh-memory/records-meta` 端点、槽位投影的
+ * `refViews.filePath` 都走这里。各自抄一份清洗规则必然漂移——漂移之后「投影给的地址」
+ * 和「磁盘上的真文件」对不上，而这三处本来就是给人核对同一个事实用的。
+ */
+export function relPathFor(r) {
+    const dir = MEMORY_TYPE_DIRS.has(r.type) ? r.type : UNSORTED_DIR;
+    return `${dir}/${fileStemFor(r)}.memory.md`;
+}
 /** 把值写成可解析回读的 frontmatter 标量/数组（JSON 编码，转义由它负责）。 */
 function fmLine(key, value) {
     return `${key}: ${JSON.stringify(value)}`;
@@ -195,9 +206,9 @@ function fmLine(key, value) {
  * @returns `relPath`（相对投射根，已归一分隔符）与 `text`（全文）。
  */
 export function renderRecord(r) {
-    const dir = MEMORY_TYPE_DIRS.has(r.type) ? r.type : UNSORTED_DIR;
+    const relPath = normalize(relPathFor(r)).replace(/\\/g, '/');
+    // frontmatter 的 `name` 必须与文件名干同一值，所以单独再取一次（同一纯函数，不会漂）。
     const stem = fileStemFor(r);
-    const relPath = normalize(`${dir}/${stem}.memory.md`).replace(/\\/g, '/');
     const scenario = Array.isArray(r.metadata?.dsh_usage_scenario)
         ? (r.metadata?.dsh_usage_scenario).filter((s) => typeof s === 'string')
         : [];

package/dist/store/sqlite.d.ts

@@ -229,6 +229,23 @@ export declare class MemoryDb {
      * 巡检期间即使有写回也不会有分页漂移;updated_time 会被写回改动。
      */
     getAllL1Lite(limit: number, offset: number): L1MetaLite[];
+    /**
+     * 游标分批取**活跃** L1 的骨架判定所需列（`id / type / content / metadata`）。
+     *
+     * 为什么单开一个方法而不是复用 `getAllL1Lite`：后者刻意不返 content（防写回把正文清空），
+     * 而 redistill 的**扫描阶段就要用 content 判骨架**——把筛子下推到扫描期，才能像反刍
+     * 重标定那样“只把真目标送 LLM”，而不是每批 hydrate 20 条候选后发现只有 4 条要整形。
+     *
+     * 退场判据走 `retiredL1Sql()`（全库唯一事实源）下推到 SQL：活跃集本就只占全库
+     * 两成（真机 289/1221），先筛掉退场行可把扫描代价降到五分之一。
+     * 分页同 `getAllL1Lite`：`ORDER BY record_id`（主键不变 ⇒ 无分页漂移）。
+     */
+    getActiveL1ForSkeleton(limit: number, offset: number): Array<{
+        id: string;
+        type: string;
+        content: string;
+        metadata: Record<string, unknown>;
+    }>;
     /**
      * **只**更新 metadata_json(顺带 updated_time),绝不碰 content 或其它列。
      *

package/dist/store/sqlite.js

@@ -1275,6 +1275,39 @@ export class MemoryDb {
             return [];
         }
     }
+    /**
+     * 游标分批取**活跃** L1 的骨架判定所需列（`id / type / content / metadata`）。
+     *
+     * 为什么单开一个方法而不是复用 `getAllL1Lite`：后者刻意不返 content（防写回把正文清空），
+     * 而 redistill 的**扫描阶段就要用 content 判骨架**——把筛子下推到扫描期，才能像反刍
+     * 重标定那样“只把真目标送 LLM”，而不是每批 hydrate 20 条候选后发现只有 4 条要整形。
+     *
+     * 退场判据走 `retiredL1Sql()`（全库唯一事实源）下推到 SQL：活跃集本就只占全库
+     * 两成（真机 289/1221），先筛掉退场行可把扫描代价降到五分之一。
+     * 分页同 `getAllL1Lite`：`ORDER BY record_id`（主键不变 ⇒ 无分页漂移）。
+     */
+    getActiveL1ForSkeleton(limit, offset) {
+        if (this.degraded)
+            return [];
+        if (limit <= 0)
+            return [];
+        try {
+            const rows = this.db
+                .prepare(`SELECT record_id, type, content, metadata_json FROM l1_records
+                  WHERE NOT (${retiredL1Sql()}) ORDER BY record_id LIMIT ? OFFSET ?`)
+                .all(limit, offset);
+            return rows.map((r) => ({
+                id: r.record_id,
+                type: r.type,
+                content: r.content ?? '',
+                metadata: parseMetadataJson(r.metadata_json),
+            }));
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} L1 骨架取数失败(返回空,本轮跳过): ${err instanceof Error ? err.message : String(err)}`);
+            return [];
+        }
+    }
     /**
      * **只**更新 metadata_json(顺带 updated_time),绝不碰 content 或其它列。
      *

package/dist/wing-backfill.d.ts

@@ -1,13 +1,16 @@
 /**
  * 存量未打标记录的一键回填(task_15):从 WingWheel"未打标 M"入口触发,
- * 对 metadata 无 wing 的 L1 记录按 8 角词表批量补打标签(复用 L1 抽取的打标路径:
+ * 对 metadata 无 wing 的 L1 记录按 8 角词表**逐条**补打标签(复用 L1 抽取的打标路径:
  * 同一候选词表与措辞,经既有蒸馏 LLM 路由)。
  *
  * 安全边界:
  * - **单飞**:同时最多一个回填任务,重复触发直接返回 running(不排队不叠加);
- * - **后台执行**:端点立即返回,逐块推进(每块 20 条),不阻塞 RPC/管线;
- * - **失败可退**:LLM 失败/输出不合法只跳过当前块,原记录零改动(标签只写成功的);
+ * - **后台执行**:端点立即返回,**逐条推进、跑完一条再发下一条**,不阻塞 RPC/管线;
+ * - **失败可退**:LLM 失败/输出不合法只跳过当前条,原记录零改动(标签只写成功的);
  * - **有界**:单次任务最多处理 MAX_RECORDS 条,防止一次跑飞;其余可再次触发。
+ *
+ * 形状约定(用户定):**按单元、串行、不合并**——一个请求只装一条记忆。旧形状把 20 条
+ * 合并进一个 prompt(一次截断/空输出就整批丢弃),逐条只把爆炸半径限制在 1 条。
  */
 import type { Context } from '@deepseek-ai/cordis';
 import { type MemoryLogger, type MemoryRecord } from './types.js';
@@ -32,16 +35,15 @@ export declare function startWingBackfill(deps: HallBackfillDeps): {
     started: boolean;
     running: boolean;
 };
-/** Wing 标注器(导出):一键回填与反刍重标定共用同一 LLM 路径与措辞。 */
-export declare function labelWingChunk(ctx: Context, cfg: MemoryConfig, logger: MemoryLogger, chunk: MemoryRecord[], candidates: string): Promise<Array<{
-    record: MemoryRecord;
-    wing: string;
-}>>;
 /**
- * 涌现标签标注器(导出):为一批记录提炼 slug 标签(tags)——Room 的前身。
- * 与 Wing 标注共用 LLM 路由(layer='l1-extract');失败返回空数组,调用方零改动。
+ * Wing 标注器(导出):一键回填与反刍重标定共用同一 LLM 路径与措辞。
+ *
+ * **一个请求只装一条**(旧名 `labelWingChunk`,多条一次,已废)。返回该条的 wing,
+ * 失败/字段缺失/值非法返回 null(记账归调用方,本函数不动全局状态)。
+ */
+export declare function labelWingOne(ctx: Context, cfg: MemoryConfig, logger: MemoryLogger, rec: MemoryRecord, candidates: string, callTimeoutMs?: number): Promise<string | null>;
+/**
+ * 涌现标签标注器(导出):为**一条**记录提炼 slug 标签(tags)——Room 的前身。
+ * 一个请求只装一条(旧名 `tagChunk`,多条一次,已废)。失败返回 null;合法但为空返回 []。
  */
-export declare function tagChunk(ctx: Context, cfg: MemoryConfig, logger: MemoryLogger, chunk: MemoryRecord[]): Promise<Array<{
-    record: MemoryRecord;
-    tags: string[];
-}>>;
+export declare function tagOne(ctx: Context, cfg: MemoryConfig, logger: MemoryLogger, rec: MemoryRecord, callTimeoutMs?: number): Promise<string[] | null>;