dsh-prime-memory 0.22.1 → 0.24.0

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;

package/dist/tools/skills.js

@@ -0,0 +1,130 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+const MUTATE_OFF_NOTICE = '记忆写删未开放：请在记忆库面板开启「高权限模式」后，模型才能改动技能。';
+export function registerSkillTools(ctx, cfg, skills, logger, live) {
+    if (!(cfg.skills.enabled === true || live.get().skillsEnabled === true))
+        return; // 默认关：部署 cfg 或看板 live 任一开才注册
+    // memory_skill_list：列全部技能摘要（含 status/sessionCount，candidate 也列出供审阅）。
+    ctx.tools.register(defineTool({
+        name: 'memory_skill_list',
+        description: '列出已沉淀的技能(程序性记忆)摘要：id/标题/状态/档位/覆盖会话数。用于查看技能库现状与候选晋升情况。',
+        parameters: {},
+        output: {
+            schema: {
+                type: 'object',
+                properties: {
+                    skills: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                id: { type: 'string' },
+                                title: { type: 'string' },
+                                status: { type: 'string' },
+                                tier: { type: 'string' },
+                                pinned: { type: 'boolean' },
+                                sessionCount: { type: 'number' },
+                            },
+                            additionalProperties: false,
+                        },
+                    },
+                    notice: { type: 'string' },
+                },
+                additionalProperties: false,
+            },
+            render: (_a, v) => [{ type: 'text', text: v.notice ?? `共 ${v.skills?.length ?? 0} 个技能` }],
+        },
+        execute: async () => {
+            const list = skills.list().map((s) => ({
+                id: s.id,
+                title: s.title,
+                status: s.status,
+                tier: s.injectionTier,
+                pinned: s.pinned,
+                sessionCount: skills.sessionCount(s.id),
+            }));
+            return { skills: list, notice: `共 ${list.length} 个技能` };
+        },
+    }));
+    // memory_skill_read：取某技能完整正文 + 步骤。
+    ctx.tools.register(defineTool({
+        name: 'memory_skill_read',
+        description: '读取一条技能的完整正文与步骤清单（按 id）。用于展开注入里被截断/excerpt 档的技能细节。',
+        parameters: { id: { type: 'string', required: true, description: '技能 id（来自 memory_skill_list 或注入头）' } },
+        output: {
+            schema: {
+                type: 'object',
+                properties: {
+                    id: { type: 'string' },
+                    title: { type: 'string' },
+                    body: { type: 'string' },
+                    steps: { type: 'array', items: { type: 'string' } },
+                    notice: { type: 'string' },
+                },
+                additionalProperties: false,
+            },
+            render: (_a, v) => [
+                {
+                    type: 'text',
+                    text: v.notice ?? [`【${v.title}】`, v.body, ...(v.steps || []).map((s) => `  - ${s}`)].join('\n'),
+                },
+            ],
+        },
+        execute: async (args) => {
+            const id = String(args?.id ?? '').trim();
+            const s = skills.get(id);
+            if (!s)
+                return { id, title: '', body: '', steps: [], notice: `未找到技能 ${id}` };
+            return { id: s.id, title: s.title, body: s.body, steps: s.steps };
+        },
+    }));
+    // memory_skill_pin：pin/unpin（高权限门）。pinned 技能不受闲置归档影响。
+    ctx.tools.register(defineTool({
+        name: 'memory_skill_pin',
+        description: '固定/取消固定一条技能（按 id）。固定后不参与闲置自动归档。仅用户显式要求时用；需高权限模式。',
+        parameters: {
+            id: { type: 'string', required: true, description: '技能 id' },
+            pinned: { type: 'boolean', required: true, description: 'true=固定，false=取消固定' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                properties: { notice: { type: 'string' } },
+                additionalProperties: false,
+            },
+            render: (_a, v) => [{ type: 'text', text: v.notice ?? '' }],
+        },
+        execute: async (args) => {
+            if (!live.get().memoryMutate)
+                return { notice: MUTATE_OFF_NOTICE };
+            const id = String(args?.id ?? '').trim();
+            const changed = await skills.update(id, { pinned: args?.pinned === true });
+            return { notice: changed ? `已${args?.pinned === true ? '固定' : '取消固定'}技能 ${id}` : `未找到技能 ${id} 或无变化` };
+        },
+    }));
+    // memory_skill_archive：归档（高权限门）；走 sidecar 生命周期，不触碰 l1_records 退场。
+    ctx.tools.register(defineTool({
+        name: 'memory_skill_archive',
+        description: '归档一条技能（按 id，可给原因）。归档后不再注入，但记录保留可恢复。仅用户显式要求时用；需高权限模式。',
+        parameters: {
+            id: { type: 'string', required: true, description: '技能 id' },
+            reason: { type: 'string', description: '归档原因（可选，供审计）' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                properties: { notice: { type: 'string' } },
+                additionalProperties: false,
+            },
+            render: (_a, v) => [{ type: 'text', text: v.notice ?? '' }],
+        },
+        execute: async (args) => {
+            if (!live.get().memoryMutate)
+                return { notice: MUTATE_OFF_NOTICE };
+            const id = String(args?.id ?? '').trim();
+            const done = await skills.archive(id, String(args?.reason ?? 'manual').slice(0, 120) || 'manual');
+            if (done)
+                logger.info(`[memory] 技能归档 ${id}`);
+            return { notice: done ? `已归档技能 ${id}` : `未找到技能 ${id} 或已归档` };
+        },
+    }));
+}

package/dist/types.d.ts

@@ -1,9 +1,3 @@
-/**
- * 领域类型与词汇表(净室重写)。
- *
- * 覆盖:记忆族/档位、Hall 目录、L0/L1 记录形状、抽取产出与族判定三级兜底、
- * L2 场景摘要与 L1 检索命中。字段名与取值是磁盘/管线两侧的既定契约,不可更名。
- */
 /** 蒸馏 Prompt 家族:chat = 个人记忆(persona/episodic/instruction + 用户画像),work = 工作记忆(work_fact/work_task/work_method/work_artifact + Team Operating Doctrine)。 */
 export type MemoryFamily = 'chat' | 'work';
 /** 会话记忆档位:auto = 双族自动判定 | chat/work = 单族 | off = 本会话对记忆系统隐身。 */
@@ -46,7 +40,14 @@ export interface RoomCount {
     /** 人类可读名(注册表条目才有;面板 chip 可用 label 展示)。 */
     label?: string;
 }
-/** 记录族标签推断:work_* 前缀 → work,其余(含 auto 档兜底)→ chat。 */
+/**
+ * 记录族标签推断（pm-name-distill task_1.2）：查 `TYPE_FAMILY_MAP`（词表单一真源）。
+ *
+ * 旧实现是 `type.startsWith('work')` 前缀猜族——新词表里 `project_*`/`development_*`/
+ * `*_experience` 都是 work 族却不带 work 前缀，前缀判定会把它们静默归进 chat，
+ * 而 family 决定召回/浏览/去重的共享面。未知值仍回落旧前缀规则并 warn 一次（可观测，
+ * 不静默）。
+ */
 export declare function familyForType(type: string): MemoryFamily;
 /**
  * 记忆的持续性(时间轴第三维,与 createdAt/updatedAt 正交):
@@ -118,6 +119,13 @@ export interface ExtractedMemory {
     metadata: Record<string, unknown>;
     /** 所属情境名(L1 抽取的情境切分结果)。 */
     scene_name: string;
+    /**
+     * 名称蒸馏（Phase 3）：模型**当场**给的短标题（名词短语，回答“这条讲的是什么”），
+     * 与 `content`（完整叙述正文）分离。只在 `cfg.naming.enabled` 时被要求产出；
+     * 缺省或过不了 `validateTitle` 形状闸就**不写成名字**，仍由 `L1Store.assignMissingNames`
+     * 兜底——名字的唯一真源不因多一个来源就分两套判据。
+     */
+    title?: string;
     /** auto 档抽取输出的显式族判定(chat|work;纯档 Prompt 无此字段)。
      *  语境归族、形状不归族——避免"个人计划性事实被 work_* 形状吸走"的族错标。 */
     family?: string;
@@ -226,6 +234,21 @@ export interface MemoryRecord {
     repoKeyOwner?: string;
     /** 记录级 applicability(ADR-0015 T1.10):'' 未声明(不围栏)| 'this-repo' | 'cross-project';显式不从 family 推导。 */
     applicability?: string;
+    /**
+     * 外部导入幂等键(轨3-P0):`sha1(source_id \0 身份)`;非外部导入(内部蒸馏/add)= undefined/''。
+     * 非空值受 `l1_records` 上部分唯一索引约束——同一 (来源, 内容/稳定身份) 重复导入结构性不可能。
+     * 与 `scene_name`/`metadata.origin` 不同:这是**存储层强制去重键**,不是展示用的溯源标签。
+     */
+    extKey?: string;
+    /**
+     * 文件身份键（md 投射相，N1）：人可读、可编辑、全库唯一，直接当
+     * `<root>/<type>/<name>.memory.md` 的文件名。与 `extKey` 的分工：extKey 是
+     * **导入幂等键**（机器算的、来源内唯一），name 是**文件身份**（人写的、全库唯一）。
+     * 不用 id 当身份：id 每轮新铸、从不复用；不用 scene_name：它的基数大于记录数。
+     * undefined = 还没名字（存量记录），投射器则回落 `mem-<id8>`。
+     * 非空值受 `l1_records` 上的部分唯一索引约束；该列**不进**快照哈希投影。
+     */
+    name?: string;
 }
 /** L2 场景块摘要(META 解析结果)。 */
 export interface SceneSummary {

package/dist/types.js

@@ -4,6 +4,7 @@
  * 覆盖:记忆族/档位、Hall 目录、L0/L1 记录形状、抽取产出与族判定三级兜底、
  * L2 场景摘要与 L1 检索命中。字段名与取值是磁盘/管线两侧的既定契约,不可更名。
  */
+import { familyOf } from './memory-types.js';
 export const WING_CATALOG = [
     { id: 'work', label: '工作' },
     { id: 'relationships', label: '人际' },
@@ -27,9 +28,16 @@ export function wingLabel(id) {
     const h = WING_CATALOG.find((x) => x.id === id);
     return h ? h.label : id;
 }
-/** 记录族标签推断:work_* 前缀 → work,其余(含 auto 档兜底)→ chat。 */
+/**
+ * 记录族标签推断（pm-name-distill task_1.2）：查 `TYPE_FAMILY_MAP`（词表单一真源）。
+ *
+ * 旧实现是 `type.startsWith('work')` 前缀猜族——新词表里 `project_*`/`development_*`/
+ * `*_experience` 都是 work 族却不带 work 前缀，前缀判定会把它们静默归进 chat，
+ * 而 family 决定召回/浏览/去重的共享面。未知值仍回落旧前缀规则并 warn 一次（可观测，
+ * 不静默）。
+ */
 export function familyForType(type) {
-    return type.startsWith('work') ? 'work' : 'chat';
+    return familyOf(type);
 }
 export const PERSISTENCE_VALUES = ['p', 's', 'o', 't'];
 /** 持续性取值归一:只认 p/s/o/t,其余(缺省/非法)返回 undefined。 */

package/dist/util/maturity.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 成熟度（maturity）合成——G3，单一事实源的纯函数。
+ *
+ * 把四个**已存在**的信号合成一个可解释的置信档，供面板显示与召回排序：
+ * - `priority`（L1 真实列，0-100）：写入时的重要性先验；
+ * - `usage.used`（recall-usage，进 topN 被注入才计）：被反复用到 = 越"确立"；
+ * - `agingWeight`（读路径衰减系数 0.5~1，null=关）：新鲜度；
+ * - `mark`（人在召回卡上打的 -1..5，**只看最近一笔**）：显式的人工裁决。
+ *
+ * 人工标记是**加性**项（±W_MARK），不是权重再分配：未打分时贡献恒为 0，
+ * 与三输入时代的分值**逐字相等**（旧回归断言不会因新增一项而漂）。
+ * 档位设计（用户口径：0/1/2 拉低、4/5 抬高）：0/1/2 为负、3 中性、4/5 为正；
+ * `-1`（声明过时）**不在此计分**——它走退场，若再计一次罚就是同一件事罚两遍。
+ *
+ * 刻意**读时派生、不落库**（Agent B/C 结论）：落库会在每轮 recordAttempt 触发双写 + 值随时间陈旧，
+ * 且顶层列不进快照哈希=隐形改写。各输入即时可得，纯函数零 IO。
+ *
+ * 权重/阈值集中为常量，便于回归与调参；缺 usage（未装配）按 0 强化处理（不虚构成熟度）。
+ */
+export type Maturity = 'low' | 'mid' | 'high';
+export interface MaturityUsage {
+    used: number;
+}
+export interface MaturityInput {
+    priority: number;
+    usage?: MaturityUsage | null;
+    /** 读路径老化权重（0.5~1）；null = 衰减关闭 → 视为 1（不惩罚）。 */
+    agingWeight?: number | null;
+    /**
+     * 人给的最近一笔打分（-1..5）；未打分 = undefined/null → 贡献 0（逐字旧行为）。
+     * `-1` 也按 0 处理：那条记录已经退场，不该在成熟度上再罚一次。
+     */
+    mark?: number | null;
+}
+/**
+ * 打分 → 归一化人工信号（-1..1）。3 分与未打分同为中性。
+ * 正侧只分两档（4 半、5 满）；负侧分三档渐次加重（2 轻罚 -0.4、1 中罚 -0.7、0 重罚 -1）——
+ * “不相关”是个需要区分程度的否定，而“相关”不必分那么细。
+ */
+export declare function markSignal(mark: number | null | undefined): number;
+/** 合成分值（0~1），导出供测试与未来排序复用。 */
+export declare function maturityScore(i: MaturityInput): number;
+/** 三档成熟度：high ≥0.66、mid ≥0.40、否则 low。 */
+export declare function computeMaturity(i: MaturityInput): Maturity;

package/dist/util/maturity.js

@@ -0,0 +1,43 @@
+const W_PRIORITY = 0.45;
+const W_USAGE = 0.3;
+const W_AGING = 0.25;
+/** 人工标记的加性幅度（±0.3）：够让一档在强先验上被推翻，又不足以一票定生死。 */
+const W_MARK = 0.3;
+/** used 达到该数即满强化（再高不加分）。 */
+const USAGE_SATURATE = 5;
+const HIGH_THRESHOLD = 0.66;
+const MID_THRESHOLD = 0.4;
+/**
+ * 打分 → 归一化人工信号（-1..1）。3 分与未打分同为中性。
+ * 正侧只分两档（4 半、5 满）；负侧分三档渐次加重（2 轻罚 -0.4、1 中罚 -0.7、0 重罚 -1）——
+ * “不相关”是个需要区分程度的否定，而“相关”不必分那么细。
+ */
+export function markSignal(mark) {
+    switch (mark) {
+        case 5: return 1;
+        case 4: return 0.5;
+        case 2: return -0.4;
+        case 1: return -0.7;
+        case 0: return -1;
+        default: return 0; // 3 / -1 / 未打分 / 越界值
+    }
+}
+function clamp01(x) {
+    return Math.max(0, Math.min(1, x));
+}
+/** 合成分值（0~1），导出供测试与未来排序复用。 */
+export function maturityScore(i) {
+    const p = clamp01(i.priority / 100);
+    const u = i.usage ? clamp01(i.usage.used / USAGE_SATURATE) : 0;
+    const a = i.agingWeight == null ? 1 : clamp01(i.agingWeight);
+    return clamp01(W_PRIORITY * p + W_USAGE * u + W_AGING * a + W_MARK * markSignal(i.mark));
+}
+/** 三档成熟度：high ≥0.66、mid ≥0.40、否则 low。 */
+export function computeMaturity(i) {
+    const s = maturityScore(i);
+    if (s >= HIGH_THRESHOLD)
+        return 'high';
+    if (s >= MID_THRESHOLD)
+        return 'mid';
+    return 'low';
+}

package/dist/util/md-name.d.ts

@@ -0,0 +1,129 @@
+/**
+ * 入库闸门的长度上限（字符）。人/模型**有意给**的名字允许到这里。
+ *
+ * 历史：24 → 28 → **40**。放宽的理由不是“名字长点好看”，是**计数把 ASCII 与汉字同价**：
+ * 本项目记忆标题里 `dsh-agent-teams`、`Python-3.13`、`NeatDownloader` 这类标识符很常见，
+ * 一个词就吃掉 13–16 个额度，于是语义上只有一两个词的正当名在字符上“超长”
+ * （真机 13 条 fallback 里 3 条属此类）。28 的代价不是难看，是把已经拿到的语义丢掉重算。
+ * 仍钉在 40 而不是更松：投射路径要留在 Windows `MAX_PATH` 里，而且超过 40 的名
+ * 几乎必然是句子而不是标题。
+ */
+export declare const NAME_MAX = 40;
+/**
+ * 规则兜底名（{@link deriveName}）的截断上限，**故意比闸门紧**。
+ *
+ * 两者不能合为一个数（实测过：统一放 40 后，`buildTurnCompactSystemPrompt` 会拖出
+ * 「负责组装每一轮的系统提示」这种句子尾巴）：`deriveName` 吃的是**叙述句**，多给的额度
+ * 只会被句子吃掉；而闸门吃的是**人/模型写的标题**，那里长度是语义而不是噪声。
+ * 28 仍是兜底名不至于变成句子的上限。
+ */
+export declare const NAME_CLIP_MAX = 28;
+/** 目标区间下界（推荐名短于此偏空），仅作注释性常量，不作硬闸。 */
+export declare const NAME_TARGET_MIN = 6;
+/** 目标区间上界（推荐名长于此偏啰嗦），仅作注释性常量，不作硬闸。 */
+export declare const NAME_TARGET_MAX = 14;
+/**
+ * 叙述引子表：正文是"谁干了什么"的完整叙述句时，这些前缀只是话头，
+ * 占了名字名额却不含信息量（真机坏味「用户要求将-...」「团队已完成-...」即此）。
+ * 导出供 `validateTitle` 与 `deriveName` **共用同一份**，两处判据不许漂移。
+ */
+export declare const NARRATIVE_LEAD_INS: readonly string[];
+/**
+ * 正文 → 名字干（分段流水线）。
+ *
+ * 保持签名 `(content) => string` 与"洗不出可用文字返回空串"的承诺。步骤：
+ *  1. 标题行优先：正文有 `^#{1,3} ` 行用它，否则取首个非空行；
+ *  2. 剥 markdown 前缀；
+ *  3. 剥叙述引子（{@link NARRATIVE_LEAD_INS}）连同其后标点/残留话头；
+ *  4. 结构边界截断（第一个句读 / 括号 / 反引号 / 路径 / session / uuid 处断开，
+ *     括号内整块丢弃——除非主句因此被丢空）；
+ *  5. 词元边界收尾：CJK 逐字、ASCII 逐词，绝不切半单词；
+ *  6. 截断纪律：过 `sanitizeFilename`，剥尾随 `.` `-` 空格。
+ *
+ * @param content - 记忆正文。
+ * @returns 文件名安全的名字干；无可用文字时 `''`。
+ */
+export declare function deriveName(content: string): string;
+/**
+ * 步骤 5：截到 maxLen，且绝不切半 ASCII 单词。
+ * 若刚好落在 ASCII 词元中间（末字符与被丢字符都是 `[A-Za-z0-9]`），回删整个残词。
+ * CJK 逐字，无需回退。
+ *
+ * 导出是因为**改名侧也要同一个收梢算法**：模型给的 title 只是超长（`too-long`）时，
+ * 按词元边界收一刀仍是好名字，直接回落 `deriveName` 等于把已经拿到的语义扔掉重算。
+ * 两处共用一份，截断形状才不会分头演化。
+ */
+export declare function clipAtTokenBoundary(raw: string, maxLen: number): string;
+/**
+ * 校验一个**人给的或模型给的**名字是否可用（形状，不含唯一性）。
+ *
+ * Phase 3 的 few-shot 判据会拿它当门禁，因此签名与 reason 取值必须稳定。
+ * 命中任一硬规则即拒；全部通过返回 `{ ok: true, name }`（name 为过字符白名单后的归一值）。
+ *
+ * @param raw - 候选名字。
+ * @returns `{ ok: true, name }` 或 `{ ok: false, reason }`。
+ */
+export declare function validateTitle(raw: string): {
+    ok: true;
+    name: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * 剥一个**模型给的** title 的形状噪声：空白（含全角空格）→ `-`、连字折叠、首尾点/横线剔掉。
+ *
+ * 为什么需要它：不是语义不对，只是字符形状不对——直接拿原文过形状闸会把
+ * “尾部多一个点”这种一律打进 fallback（真机旧行为：16/20 条白归规则名）。
+ * 导出是为了**只有一个整形函数**：管线与临时改名脚本共用，两套迟早漂。
+ */
+export declare function reshapeTitle(raw: string): string;
+/**
+ * 收下模型产出的 title：先整形再入闸，**只超长**时按词元边界再收一刀。
+ *
+ * 返回落名或 `undefined`（不合格）。刻意**不回落规则名**：那是调用方的决定，
+ * 因为两条路的可观测要求不同（管线要“没名字就交给起名器”，脚本要“记 fallback+reason”）。
+ * 闸仍是 {@link validateTitle} 那一个，不开第二套判据。
+ *
+ * @param raw - 模型给的原文（故意收 `unknown`：模型输出是不可信输入）。
+ * @returns 可用的落名，或 `undefined`。
+ */
+export declare function acceptTitle(raw: unknown): string | undefined;
+/**
+ * 校验一个**人给的**名字是否可用（形状，不含唯一性）。
+ *
+ * 人从面板或 md 文件里改名字时，先过这道形状闸再谈唯一性：形状不合就拒，
+ * 比"收下然后写不出文件"好。返回归一后的名字（可能与入参不同：洗掉了非法字符）。
+ *
+ * @param raw - 用户给的名字。
+ * @returns `{ ok: true, name }` 或 `{ ok: false, reason }`。
+ */
+export declare function normalizeName(raw: string): {
+    ok: true;
+    name: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/** 名字没洗出可用字符时的回落干：`mem-<id 后 8 位>`。 */
+export declare function fallbackStem(id: string): string;
+/**
+ * 给一个名字求**全库唯一**的落名：基底 → `基底-2` → `基底-3` → … → 回落名。
+ *
+ * 为什么必须在这里消歧，而不是"谁先到谁写"：同一段话的多条记录必然洗出同一个名字。
+ * 真机实测 1166 条里 42 条挤进 17 个同名文件（最狠一个路径 6 条），后果是导出每轮都把
+ * 被覆盖的那几条重写一遍（面板上那个永远不归零的「已写 9」）、而反向同步会把一份内容
+ * 回灌给六条记录。
+ *
+ * 分配本身只取决于"基底 + 已占用集"，因此**调用方必须按 id 排序后再分配**：
+ * 同一个基底碰上同一次分配时，谁先谁拿到裸名——顺序不钉死的话，两次导出会给同一条
+ * 记录分到不同名字，文件在盘上跳来跳去。后缀要留位置：总长不超过 {@link NAME_MAX}，
+ * 宁可截基底也不让它超长。
+ *
+ * @param base - 基底名（通常是 `deriveName(content)`，可以为空）。
+ * @param id - 记录 id，基底不可用时落回 `mem-<id8>`。
+ * @param isFree - 库侧查询：这个名字没被**其它**记录占着。
+ * @param reserved - 本轮已分配出去的名字（调用方逐次加入，函数也会自己加）。
+ * @returns 可用的名字；实在找不到就把 `id` 的回落名加上数字尾巴交出去（仍进 reserved）。
+ */
+export declare function allocUniqueName(base: string, id: string, isFree: (name: string) => boolean, reserved: Set<string>): string;