dsh-prime-memory 0.22.2 → 0.24.1

package/dist/util/maturity.d.ts

@@ -1,13 +1,19 @@
 /**
  * 成熟度（maturity）合成——G3，单一事实源的纯函数。
  *
- * 把三个**已存在**的信号合成一个可解释的置信档，供面板显示（后续可作召回排序/矛盾旁注）：
+ * 把四个**已存在**的信号合成一个可解释的置信档，供面板显示与召回排序：
  * - `priority`（L1 真实列，0-100）：写入时的重要性先验；
  * - `usage.used`（recall-usage，进 topN 被注入才计）：被反复用到 = 越"确立"；
- * - `agingWeight`（读路径衰减系数 0.5~1，null=关）：新鲜度。
+ * - `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。
+ * 且顶层列不进快照哈希=隐形改写。各输入即时可得，纯函数零 IO。
  *
  * 权重/阈值集中为常量，便于回归与调参；缺 usage（未装配）按 0 强化处理（不虚构成熟度）。
  */
@@ -20,7 +26,18 @@ export interface MaturityInput {
     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。 */

package/dist/util/maturity.js

@@ -1,10 +1,27 @@
 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));
 }
@@ -13,7 +30,7 @@ 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 W_PRIORITY * p + W_USAGE * u + W_AGING * a;
+    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) {

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;

package/dist/util/md-name.js

@@ -0,0 +1,366 @@
+/**
+ * 文件身份名（N1）：把一条 L1 记忆的正文折成一个**人可读、可编辑、全库唯一**的短名，
+ * 直接当 `<root>/<type>/<name>.memory.md` 的文件名干。
+ *
+ * 为什么不用现成的键：
+ * - `id` 每轮新铸、从不复用（merge = 旧行软删 + 新记录追加），拿它当文件名等于每天换名；
+ * - `scene_name` 实测基数大于记录数，当不了唯一名；
+ * - `ext_key` 是**导入幂等键**（机器算的、只在来源内唯一），语义与"人给这条记忆起的名字"不同。
+ *
+ * 名字纪律**复用** `sanitizeFilename`（`store/scenes.ts`）而不是另写一套：
+ * 那里已经处理过非法字符、Windows 保留设备名（`CON`/`LPT1`…）、stem 超长截断。
+ * 自己拼一份正则迟早和它漂移，而漂移的后果是"库里存的名字写不出文件"。
+ *
+ * Phase 2 重写：旧 `deriveName` 取首行前 24 字，正本是完整叙述句时天然是残句
+ * （真机 1166 条里 96.7% 是句子残片）。现改为**分段流水线**：标题行优先 → 剥 markdown
+ * 前缀 → 剥叙述引子 → 结构边界截断 → 词元边界收尾 → 截断纪律，每一步都可单测。
+ */
+import { sanitizeFilename } from '../store/scenes.js';
+/**
+ * 入库闸门的长度上限（字符）。人/模型**有意给**的名字允许到这里。
+ *
+ * 历史：24 → 28 → **40**。放宽的理由不是“名字长点好看”，是**计数把 ASCII 与汉字同价**：
+ * 本项目记忆标题里 `dsh-agent-teams`、`Python-3.13`、`NeatDownloader` 这类标识符很常见，
+ * 一个词就吃掉 13–16 个额度，于是语义上只有一两个词的正当名在字符上“超长”
+ * （真机 13 条 fallback 里 3 条属此类）。28 的代价不是难看，是把已经拿到的语义丢掉重算。
+ * 仍钉在 40 而不是更松：投射路径要留在 Windows `MAX_PATH` 里，而且超过 40 的名
+ * 几乎必然是句子而不是标题。
+ */
+export const NAME_MAX = 40;
+/**
+ * 规则兜底名（{@link deriveName}）的截断上限，**故意比闸门紧**。
+ *
+ * 两者不能合为一个数（实测过：统一放 40 后，`buildTurnCompactSystemPrompt` 会拖出
+ * 「负责组装每一轮的系统提示」这种句子尾巴）：`deriveName` 吃的是**叙述句**，多给的额度
+ * 只会被句子吃掉；而闸门吃的是**人/模型写的标题**，那里长度是语义而不是噪声。
+ * 28 仍是兜底名不至于变成句子的上限。
+ */
+export const NAME_CLIP_MAX = 28;
+/** 目标区间下界（推荐名短于此偏空），仅作注释性常量，不作硬闸。 */
+export const NAME_TARGET_MIN = 6;
+/** 目标区间上界（推荐名长于此偏啰嗦），仅作注释性常量，不作硬闸。 */
+export const NAME_TARGET_MAX = 14;
+/**
+ * 叙述引子表：正文是"谁干了什么"的完整叙述句时，这些前缀只是话头，
+ * 占了名字名额却不含信息量（真机坏味「用户要求将-...」「团队已完成-...」即此）。
+ * 导出供 `validateTitle` 与 `deriveName` **共用同一份**，两处判据不许漂移。
+ */
+export const NARRATIVE_LEAD_INS = [
+    '用户要求', '用户规定', '用户需要', '用户确立', '用户',
+    '团队已', '团队将', '团队完', '团队',
+    '针对', '已生成', '生成了', '已为', '本次', '目前', '结论', '要点', '待推进',
+];
+/** 由长到短排序，保证「用户要求」优先于「用户」命中（前缀匹配不会被短项截胡）。 */
+const LEAD_IN_SORTED = [...NARRATIVE_LEAD_INS].sort((a, b) => b.length - a.length);
+/**
+ * 闸门用的引子表 = 剥引子表**去掉裸主语**（`用户` / `团队`）。
+ *
+ * 两张表本来就该是两个用途，之前共用一份是误杀源：
+ * - `deriveName` 吃的是**完整叙述句**，句首裸「用户」只是话头、不含信息量，该剥；
+ * - `validateTitle` 吃的是**人/模型给的名词短语**，「用户npm账号用户名」「团队profile配置」里的
+ *   「用户/团队」是正当的所属主语，当成叙述引子拒掉就是误杀（真机改名计划 13 条 fallback 里 10 条栽在这两个词）。
+ * 所以这不是把闸门调松，是把「剥话头」与「拒名字」分开——短语类引子（用户要求/团队已/针对/本次…）照旧拒。
+ */
+const GATE_LEAD_IN_SORTED = LEAD_IN_SORTED.filter((lead) => lead !== '用户' && lead !== '团队');
+/** 引子之后可能残留的单个话头连接词（「用户要求将…」的「将」），一并丢弃。 */
+const LEAD_IN_CONNECTOR = '(?:将|把|要|需|做了|做|规定|需要|的)?';
+/** 只吃引子后的空白与读点，不吃正文用字。 */
+const LEAD_IN_PUNCT = '[\\s，,、：:]*';
+/** 结构边界截断点：第一个命中的分隔标记处断开（'，' '、' 不在此列，只走长度收尾）。 */
+const STRUCTURAL_BOUNDARIES = [
+    /[：。；]/, // 全角句读
+    /[（(]/, // 括号：整块丢弃括号内容
+    /`/, // 反引号：内联代码前后都算边界
+    /[A-Za-z]:[\\/]/, // Windows 盘符路径
+    /session-[0-9a-f-]{8,}/i, // 会话 id
+    /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}/i, // uuid 片段
+];
+/**
+ * 正文 → 名字干（分段流水线）。
+ *
+ * 保持签名 `(content) => string` 与"洗不出可用文字返回空串"的承诺。步骤：
+ *  1. 标题行优先：正文有 `^#{1,3} ` 行用它，否则取首个非空行；
+ *  2. 剥 markdown 前缀；
+ *  3. 剥叙述引子（{@link NARRATIVE_LEAD_INS}）连同其后标点/残留话头；
+ *  4. 结构边界截断（第一个句读 / 括号 / 反引号 / 路径 / session / uuid 处断开，
+ *     括号内整块丢弃——除非主句因此被丢空）；
+ *  5. 词元边界收尾：CJK 逐字、ASCII 逐词，绝不切半单词；
+ *  6. 截断纪律：过 `sanitizeFilename`，剥尾随 `.` `-` 空格。
+ *
+ * @param content - 记忆正文。
+ * @returns 文件名安全的名字干；无可用文字时 `''`。
+ */
+export function deriveName(content) {
+    let s = pickTitleLine(content);
+    if (s.length === 0)
+        return '';
+    s = stripLeadIn(s);
+    s = structuralTruncate(s);
+    s = clipAtTokenBoundary(s, NAME_CLIP_MAX);
+    if (s.length === 0)
+        return '';
+    return applyTrailingDiscipline(s);
+}
+/**
+ * 步骤 1+2：选出标题行并剥掉 markdown 前缀。
+ * markdown 标题（`#`/`##`/`###` + 空格）优先；否则首个非空行去掉 `#>*-+` 与空白前缀。
+ */
+function pickTitleLine(content) {
+    const lines = (content ?? '').split('\n');
+    const heading = lines.find((l) => /^#{1,3} \S/.test(l.trim()));
+    if (heading)
+        return heading.trim().replace(/^#{1,3}\s+/, '').trim();
+    const line = lines.find((l) => l.trim().length > 0) ?? '';
+    return line.trim().replace(/^[#>\-*+\s]+/, '').trim();
+}
+/**
+ * 步骤 3：剥叙述引子。命中引子就把引子 + 其后标点 + 单个残留话头一起丢，
+ * 直到剩不下引子为止（只剥一次最外层，避免把正文首词也吃掉）。
+ */
+function stripLeadIn(raw) {
+    let s = raw.trim();
+    for (const lead of LEAD_IN_SORTED) {
+        const re = new RegExp(`^${escapeRe(lead)}${LEAD_IN_CONNECTOR}${LEAD_IN_PUNCT}`);
+        const m = re.exec(s);
+        if (m && m[0].length > lead.length - 1) {
+            s = s.slice(m[0].length).trim();
+            break;
+        }
+    }
+    return s;
+}
+/**
+ * 步骤 4：结构边界截断。取所有标记里**最靠前**的断点；若断点是括号，
+ * 括号内整块丢弃（保留括号前的主句），仅当主句被丢空时才跳过这个括号继续找下一断点。
+ */
+function structuralTruncate(raw) {
+    let s = raw.trim();
+    // 反复处理：命中括号且主句非空 → 截到括号前；命中其它标记 → 截到标记前。
+    for (let guard = 0; guard < 8; guard++) {
+        let cut = -1;
+        for (const re of STRUCTURAL_BOUNDARIES) {
+            const m = re.exec(s);
+            if (m && (cut === -1 || m.index < cut))
+                cut = m.index;
+        }
+        if (cut === -1)
+            return s;
+        const head = s.slice(0, cut).trim();
+        const marker = s[cut];
+        const isParen = marker === '(' || marker === '（';
+        if (head.length === 0 && isParen) {
+            // 主句被丢空：丢掉这个左括号，保留其后内容继续处理。
+            s = s.slice(cut + 1).trim();
+            continue;
+        }
+        return head;
+    }
+    return s;
+}
+/**
+ * 步骤 5：截到 maxLen，且绝不切半 ASCII 单词。
+ * 若刚好落在 ASCII 词元中间（末字符与被丢字符都是 `[A-Za-z0-9]`），回删整个残词。
+ * CJK 逐字，无需回退。
+ *
+ * 导出是因为**改名侧也要同一个收梢算法**：模型给的 title 只是超长（`too-long`）时，
+ * 按词元边界收一刀仍是好名字，直接回落 `deriveName` 等于把已经拿到的语义扔掉重算。
+ * 两处共用一份，截断形状才不会分头演化。
+ */
+export function clipAtTokenBoundary(raw, maxLen) {
+    if (raw.length <= maxLen)
+        return raw;
+    let clipped = raw.slice(0, maxLen);
+    const lastKept = clipped.slice(-1);
+    const firstDropped = raw[maxLen] ?? '';
+    if (/[A-Za-z0-9]/.test(lastKept) && /[A-Za-z0-9]/.test(firstDropped)) {
+        clipped = clipped.replace(/[A-Za-z0-9]+$/, '');
+    }
+    return clipped;
+}
+/**
+ * 步骤 6：截断纪律。过 `sanitizeFilename` 的字符白名单 → 剥它补的 `.md`
+ * → 剥尾随 `.` `-` `_` 空格（尾点是真机 12 条坏味的直接来源）。
+ */
+function applyTrailingDiscipline(raw) {
+    const safe = sanitizeFilename(raw).replace(/\.md$/i, '');
+    return safe.replace(/[.\-_\s]+$/, '');
+}
+/**
+ * 校验一个**人给的或模型给的**名字是否可用（形状，不含唯一性）。
+ *
+ * Phase 3 的 few-shot 判据会拿它当门禁，因此签名与 reason 取值必须稳定。
+ * 命中任一硬规则即拒；全部通过返回 `{ ok: true, name }`（name 为过字符白名单后的归一值）。
+ *
+ * @param raw - 候选名字。
+ * @returns `{ ok: true, name }` 或 `{ ok: false, reason }`。
+ */
+export function validateTitle(raw) {
+    const s = (raw ?? '').trim();
+    if (s.length === 0)
+        return { ok: false, reason: 'empty' };
+    if (/[\r\n]/.test(s))
+        return { ok: false, reason: 'has-newline' };
+    if (s.length < 4)
+        return { ok: false, reason: 'too-short' };
+    if (s.length > NAME_MAX)
+        return { ok: false, reason: 'too-long' };
+    if (/[。！？!?.]$/.test(s))
+        return { ok: false, reason: 'ends-with-punctuation' };
+    if (/[A-Za-z]:[\\/]/.test(s))
+        return { ok: false, reason: 'has-drive-path' };
+    if (s.includes('/'))
+        return { ok: false, reason: 'has-slash' };
+    if (/http/i.test(s))
+        return { ok: false, reason: 'has-url' };
+    // 只拒**真 id 形状**（session-44332549…）：宽判 `session-` 子串会把
+    // `dsh-session-steward` 这类正当词组名误拒（真机改名计划实测 4/20 的误杀源）。
+    if (/session-[0-9a-f]{6,}/i.test(s))
+        return { ok: false, reason: 'has-session-id' };
+    if (/[0-9a-fA-F]{32,36}/.test(s))
+        return { ok: false, reason: 'has-hex-id' };
+    // 数字尾巴**只在它不属于某个标识符名字**时才算残片：`记录-12345-号` 是截断产物（数字前是 CJK），
+    // 而 `ADR-0006`、`Han-1413141` 里数字前面是 ASCII 字母——那是名字本体（`[^ -~]` = 非可打印 ASCII）。
+    // 旧判据一律拒 `-\d{4}`，真机把 4 条 ADR 记录的正当 LLM 标题全打进 fallback（反而掉回 `ADR-0006` 这种半截名）。
+    if (/[^ -~]-\d{4}/.test(s))
+        return { ok: false, reason: 'has-id-fragment' };
+    if (startsNarrativeLeadIn(s))
+        return { ok: false, reason: 'starts-with-lead-in' };
+    if (isBareCodeIdentifier(s))
+        return { ok: false, reason: 'code-identifier' };
+    const safe = sanitizeFilename(s).replace(/\.md$/i, '');
+    if (safe.length === 0)
+        return { ok: false, reason: 'no-usable-char' };
+    return { ok: true, name: safe };
+}
+/** 是否以叙述引子开头（用 {@link GATE_LEAD_IN_SORTED}：剥引子与拒名字两张表用途不同，见其注释）。 */
+function startsNarrativeLeadIn(s) {
+    return GATE_LEAD_IN_SORTED.some((lead) => s.startsWith(lead));
+}
+/**
+ * 是否为"裸代码标识符"——纯 ASCII、无任何分隔符（空格/-/_）、且含词中大小写翻转
+ * （camelCase 边界），读起来像被原样抓来的函数/变量名，而非人给短标题。
+ * 真机坏味 `buildTurnCompactSystemPr`（ASCII 函数名硬切腰斩）即此类。
+ */
+function isBareCodeIdentifier(s) {
+    if (/[^\x00-\x7F]/.test(s))
+        return false; // 含非 ASCII（CJK 等）不算
+    if (/[\s\-_]/.test(s))
+        return false; // 有分隔符即为短语，放行
+    return /[a-z][A-Z]/.test(s); // 词中大写翻转 = 驼峰标识符
+}
+/**
+ * 剥一个**模型给的** title 的形状噪声：空白（含全角空格）→ `-`、连字折叠、首尾点/横线剔掉。
+ *
+ * 为什么需要它：不是语义不对，只是字符形状不对——直接拿原文过形状闸会把
+ * “尾部多一个点”这种一律打进 fallback（真机旧行为：16/20 条白归规则名）。
+ * 导出是为了**只有一个整形函数**：管线与临时改名脚本共用，两套迟早漂。
+ */
+export function reshapeTitle(raw) {
+    return raw.replace(/[\s\u3000]+/g, '-').replace(/-{2,}/g, '-').replace(/^[-.]+|[-.]+$/g, '');
+}
+/**
+ * 收下模型产出的 title：先整形再入闸，**只超长**时按词元边界再收一刀。
+ *
+ * 返回落名或 `undefined`（不合格）。刻意**不回落规则名**：那是调用方的决定，
+ * 因为两条路的可观测要求不同（管线要“没名字就交给起名器”，脚本要“记 fallback+reason”）。
+ * 闸仍是 {@link validateTitle} 那一个，不开第二套判据。
+ *
+ * @param raw - 模型给的原文（故意收 `unknown`：模型输出是不可信输入）。
+ * @returns 可用的落名，或 `undefined`。
+ */
+export function acceptTitle(raw) {
+    if (typeof raw !== 'string')
+        return undefined;
+    const shaped = reshapeTitle(raw.trim());
+    if (shaped.length === 0)
+        return undefined;
+    // 两轮：原形状→若仅因超长被拒则按词元边界收到 NAME_MAX 再试。其他拒因（句子、路径、
+    // 叙述引子开头）收短也不会变合格，重试只会把垃圾洗成“看起来干净”的垃圾。
+    for (const cand of [shaped, clipAtTokenBoundary(shaped, NAME_MAX)]) {
+        const g = validateTitle(cand);
+        if (g.ok)
+            return g.name;
+    }
+    return undefined;
+}
+/**
+ * 校验一个**人给的**名字是否可用（形状，不含唯一性）。
+ *
+ * 人从面板或 md 文件里改名字时，先过这道形状闸再谈唯一性：形状不合就拒，
+ * 比"收下然后写不出文件"好。返回归一后的名字（可能与入参不同：洗掉了非法字符）。
+ *
+ * @param raw - 用户给的名字。
+ * @returns `{ ok: true, name }` 或 `{ ok: false, reason }`。
+ */
+export function normalizeName(raw) {
+    const trimmed = (raw ?? '').trim();
+    if (trimmed.length === 0)
+        return { ok: false, reason: 'empty' };
+    if (trimmed.length > NAME_MAX * 2)
+        return { ok: false, reason: 'too-long' };
+    const safe = sanitizeFilename(trimmed).replace(/\.md$/i, '');
+    if (safe.length === 0)
+        return { ok: false, reason: 'no-usable-char' };
+    if (safe !== trimmed)
+        return { ok: false, reason: 'illegal-chars' };
+    return { ok: true, name: safe };
+}
+/** 名字没洗出可用字符时的回落干：`mem-<id 后 8 位>`。 */
+export function fallbackStem(id) {
+    return `mem-${(id ?? '').slice(-8)}`;
+}
+/**
+ * 给一个名字求**全库唯一**的落名：基底 → `基底-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 function allocUniqueName(base, id, isFree, reserved) {
+    const usable = (n) => n.length > 0 && !reserved.has(n) && isFree(n);
+    const fallback = fallbackStem(id);
+    // 基底没洗出名字时，回落名就是基底（先试裸名，再试 `-N`）。
+    const stem = base.length > 0 ? base : fallback;
+    if (usable(stem)) {
+        reserved.add(stem);
+        return stem;
+    }
+    // 后缀从 2 起（-1 留给裸名，读起来不像"第二个"）。
+    for (let n = 2; n <= 999; n++) {
+        const tail = `-${n}`;
+        const room = Math.max(1, NAME_MAX - tail.length);
+        const candidate = `${stem.slice(0, room)}${tail}`;
+        if (usable(candidate)) {
+            reserved.add(candidate);
+            return candidate;
+        }
+    }
+    // 理论上到不了这里（999 个尾巴不够用 = 同一个 28 字基底已经有 1000 条记录）；
+    // 真到了就用 id 尾巴加数字，至少能保证写得出文件。
+    for (let n = 1; n <= 999; n++) {
+        const candidate = n === 1 ? fallback : `${fallback}-${n}`;
+        if (usable(candidate)) {
+            reserved.add(candidate);
+            return candidate;
+        }
+    }
+    const last = `${fallback}-${Date.now().toString(36)}`;
+    reserved.add(last);
+    return last;
+}
+/** 正则元字符转义，供动态构造引子匹配。 */
+function escapeRe(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

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

@@ -0,0 +1,23 @@
+/**
+ * 记忆正文的 markdown 版式归一（P4.2「格式需要标准化」）。
+ *
+ * 只做**版式**，不做**语义**：不 bullet 化散文、不插 H1、不往正文里塞元数据（元数据一律在
+ * frontmatter）。三条理由：
+ * - 散文转列表会把"因为/所以/但是"这类连接关系拆散，且拆完不可逆；
+ * - 正文一旦带骨架，`parseMdFile` 的往返一致性（P2）就得反向剪枝，两套逻辑必然漂移；
+ * - 归一结果要进 `renderRecord`（导出）与回灌（入库）两头，任何有损改写都会被写进库。
+ *
+ * **幂等是硬要求**：`f(f(x)) === f(x)`。不幂等的话账本 `fileDigest` 每轮都变，反向同步
+ * 永远判"文件被改过"，写回环打不完——那正是 P2 用例钉死的那条性质。
+ *
+ * 刻意不用正则与转义写法：同仓产物里出现过 `\n` 被展开成真实换行、把正则字面量截断的事，
+ * 所以这里全部走字符码与字符串切片，形状只依赖文件真实结构。
+ */
+/**
+ * 归一一段记忆正文。
+ *
+ * @param text - 原始正文（可含 CRLF、BOM、任意尾随空白）。
+ * @returns 版式归一后的正文：**无**前导/尾随空行、段落间恰好一个空行、围栏内（含 delimiter）
+ *          逐字保留、无末尾换行（渲染器自己控制）。
+ */
+export declare function normalizeContentMd(text: string): string;