dsh-lite-memory 0.17.0 → 0.18.19

package/store.js

@@ -103,6 +103,10 @@ function toFlat(entry) {
     reviewState: maintenance.reviewState || 'active',
     created: entry.createdAt || '',
     updated: entry.updatedAt || '',
+    validFrom: typeof entry.validFrom === 'string' && entry.validFrom ? entry.validFrom : (entry.createdAt || ''),
+    validUntil: typeof entry.validUntil === 'string' ? entry.validUntil : '',
+    supersededBy: typeof entry.supersededBy === 'string' ? entry.supersededBy : '',
+    supersedeReason: typeof entry.supersedeReason === 'string' ? entry.supersedeReason : '',
     lastUsed: maintenance.lastUsed || entry.updatedAt || entry.createdAt || '',
     revision: Number(entry.revision) || 1,
     status: entry.status === 'archived' ? 'archived' : 'active',
@@ -130,6 +134,10 @@ function fromFlat(record, status) {
     ownerProjectId: record.ownerProjectId || '',
     createdAt: record.created || at,
     updatedAt: at,
+    validFrom: typeof record.validFrom === 'string' && record.validFrom ? record.validFrom : (record.created || at),
+    validUntil: typeof record.validUntil === 'string' ? record.validUntil : '',
+    supersededBy: typeof record.supersededBy === 'string' ? record.supersededBy : '',
+    supersedeReason: typeof record.supersedeReason === 'string' ? record.supersedeReason : '',
     current: {
       title: record.title || '',
       summary: record.summary || '',
@@ -203,6 +211,7 @@ export function loadIndex(scope, options = {}) {
     receipts: JSON.parse(JSON.stringify(loaded.state.receipts || [])),
     lastSuggestedAt: loaded.state.lastSuggestedAt || '',
     suppressions: JSON.parse(JSON.stringify(loaded.state.suppressions || [])),
+    conflicts: JSON.parse(JSON.stringify(loaded.state.conflicts || [])),
     __evolution: state.evolutionOf(loaded.state),
     __tasks: anchor.normalizeTasks(state.evolutionOf(loaded.state).tasks),
     __control: state.controlOf(loaded.state),
@@ -228,6 +237,7 @@ function applyFlat(scope, draft, index) {
   draft.candidates = Array.isArray(index.suggestions) ? JSON.parse(JSON.stringify(index.suggestions)) : [];
   draft.receipts = Array.isArray(index.receipts) ? JSON.parse(JSON.stringify(index.receipts)) : [];
   draft.suppressions = Array.isArray(index.suppressions) ? JSON.parse(JSON.stringify(index.suppressions)) : [];
+  draft.conflicts = Array.isArray(index.conflicts) ? JSON.parse(JSON.stringify(index.conflicts)) : [];
   draft.lastSuggestedAt = typeof index.lastSuggestedAt === 'string' ? index.lastSuggestedAt : draft.lastSuggestedAt || '';
   draft.scopeKey = draft.scopeKey || index.scope;
 }
@@ -240,9 +250,10 @@ export function saveIndex(scope, index) {
   const meta = index.__meta || { exists: false };
   const expected = meta.exists ? { generation: meta.generation, epoch: meta.epoch } : null;
   const result = state.transact(scope, { expected, expectCreate: !meta.exists }, (draft) => {
-    const before = JSON.stringify([draft.entries, draft.candidates, draft.receipts, draft.suppressions, draft.lastSuggestedAt]);
+    const stamp = () => JSON.stringify([draft.entries, draft.candidates, draft.receipts, draft.suppressions, draft.conflicts, draft.lastSuggestedAt]);
+    const before = stamp();
     applyFlat(scope, draft, index);
-    const after = JSON.stringify([draft.entries, draft.candidates, draft.receipts, draft.suppressions, draft.lastSuggestedAt]);
+    const after = stamp();
     return { changed: before !== after };
   });
   const published = result.state;
@@ -321,6 +332,7 @@ export function normalizeDraft(source, options = {}) {
   const has = (key) => Object.prototype.hasOwnProperty.call(draft, key) && draft[key] !== undefined;
   const id = typeof draft.id === 'string' && /^mem_[a-z0-9]+$/.test(draft.id) ? draft.id : '';
   if (has('id') && !id) throw new Error('id 格式不对');
+  if (has('supersedes') && !/^mem_[a-z0-9]+$/.test(String(draft.supersedes ?? ''))) throw new Error('supersedes 要给被取代的 id');
   const when = has('when') ? textField(draft.when, LIMITS.whenChars, '前置条件') : '';
   const title = textField(cleanTitle(draft.title), LIMITS.titleChars, '标题');
   /** 带 id 是更新：省略的字段保持原值，标题也一样。 */
@@ -370,7 +382,7 @@ export function normalizeDraft(source, options = {}) {
   const topicKey = has('topicKey') ? textField(draft.topicKey, LIMITS.tagChars, '主题') : undefined;
   /** 凭据扫描必须覆盖完整原文：截短后的摘要看不出凭据，原文里有也不行。 */
   const secret = detectSecret([title, summary, rawSummary, when, body, tags.join(' '), topicKey || ''].join('\n'));
-  if (secret) throw new Error(`疑似凭据（${secret}），只记位置，不记值`);
+  if (secret) throw new state.StateError('unsafe', `疑似凭据（${secret}），只记位置，不记值：正文里写「去哪取、怎么取」，不抄值`);
   return {
     id,
     title,
@@ -392,6 +404,8 @@ export function normalizeDraft(source, options = {}) {
     links,
     applicability,
     topicKey,
+    /** 显式取代：新记录写好后再给旧记录打 supersededBy/validUntil。 */
+    supersedes: has('supersedes') ? textField(draft.supersedes, 60, '取代目标') : '',
     has: {
       title: has('title') && Boolean(title),
       summary: has('summary'),
@@ -405,6 +419,7 @@ export function normalizeDraft(source, options = {}) {
       links: links !== undefined,
       applicability: applicability !== undefined,
       topicKey: topicKey !== undefined,
+      supersedes: has('supersedes'),
     },
   };
 }
@@ -695,9 +710,9 @@ const STOP_GRAMS = new Set([
   '的话', '这里', '那里', '一个', '一些', '这样', '那样', '看看', '帮我看', '继续',
 ]);
 
-const asciiWordsOf = (text) => normalizeText(text, 400).toLowerCase().match(/[a-z][a-z0-9_-]{1,}/g) || [];
-
-const wordIn = (pool, word) => new RegExp(`(^|[^a-z0-9])${word.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}($|[^a-z0-9])`).test(pool);
+/** 英文整词规则只有一份，放在 view：自动召回和手动搜索必须同一个判断。 */
+const asciiWordsOf = view.asciiWordsOf;
+const wordIn = view.wordIn;
 
 /** 查询按空格/标点切成段：多段按关键词处理，整句仍按相关度处理。 */
 function queryRuns(query) {
@@ -812,7 +827,16 @@ export function similarEntries(entries, title, summary, limit = 2) {
     const titleScore = Math.max(0, ...names.map((name) => similarity(name, title)));
     const summaryScore = similarity(item.summary, summary);
     const score = Math.max(titleScore, summaryScore);
-    if (score >= MERGE.near) rows.push({ id: item.id, title: item.title, summary: item.summary, when: item.when || '', score });
+    if (score >= MERGE.near) rows.push({
+      id: item.id,
+      title: item.title,
+      summary: item.summary,
+      when: item.when || '',
+      /** 候选要能自己解释「为什么像」：标题相近，还是同一主题槽位。 */
+      updated: item.updated || item.created || '',
+      reason: titleScore >= MERGE.near ? 'similar_title' : 'similar_summary',
+      score,
+    });
   }
   rows.sort((a, b) => b.score - a.score);
   return rows.slice(0, limit);
@@ -946,36 +970,92 @@ function mergedFields(draft, record, oldBody, index, writeMode = 'patch', foreig
   return next;
 }
 
+/** 已被取代或过了有效期：默认检索看不见，明确要 history 时仍可查到并读正文。 */
+function staleRecord(record, now = Date.now()) {
+  if (record.supersededBy) return true;
+  const until = Date.parse(record.validUntil || '');
+  return Number.isFinite(until) && until <= now;
+}
+
+/** 给旧记录打上取代链：正文快照交回调用方，放进新记录的 versions 链头。 */
+function stampSupersede(scope, target, nextId, now) {
+  if (target.supersededBy) {
+    throw new state.StateError('conflict', `这条记忆已经被 ${target.supersededBy} 取代，不能再取代一次`);
+  }
+  if (target.id === nextId) throw new Error('不能取代自己');
+  const versions = snapshot(target, readBody(scope, target.id));
+  target.validUntil = now;
+  target.supersededBy = nextId;
+  target.supersedeReason = 'user_replaced';
+  return versions;
+}
+
 /**
  * 一次写入的纯业务部分：校验、身份、字节预算、版本。不改盘（正文写入由调用方在同一把锁里做）。
  */
 function applyDraft(scope, index, source, now, options = {}) {
   const draft = normalizeDraft(source);
+  scanUnsafe(draft);
   const foreign = options.foreignEntries || [];
   const distinct = source && source.resolution === 'distinct';
+  /** 取代/过期记录不参与合并判断：新内容不该再合进一条已经不是现行的记录。 */
+  const live = index.entries.filter((item) => !staleRecord(item));
+  const supersedeTarget = (selfId) => {
+    if (!draft.supersedes) return null;
+    const target = index.entries.find((item) => item.id === draft.supersedes);
+    if (!target) throw new Error(`要取代的记忆不在这一层：${draft.supersedes}`);
+    if (target.id === selfId) throw new Error('不能取代自己');
+    return target;
+  };
   let record = draft.id ? index.entries.find((item) => item.id === draft.id) : null;
   if (draft.id && !record) throw new Error('没有这条记忆，改用新增');
   let mergedFrom = null;
   let similarList = [];
+  /**
+   * 同名就是同一条：标题是唯一句柄，重复存同一个标题必须是更新，不能悄悄另建一条
+   * （否则按标题读、按标题忘都会撞上两条）。前置条件明确不同的同名才允许是另一条。
+   */
+  if (!record && !distinct) {
+    const wantedConditions = view.conditionsKey(draft.conditions || []);
+    /** 只改摘要/正文时没重写适用条件，别因此把有条件的那条挤成另一条。 */
+    const statedConditions = Boolean(draft.has.when || draft.has.conditions || draft.has.applicability);
+    const named = live.find((item) => [item.title, ...(item.aliases || [])]
+      .some((name) => String(name || '').trim().toLowerCase() === String(draft.title || '').trim().toLowerCase())
+      && (!statedConditions || view.conditionsKey(item.conditions || []) === wantedConditions)
+      /** 同名但两边都明确写了不同的 when，是用户表达的另一种情况，算另一条。 */
+      && !(draft.has.when && String(item.when || '') && String(item.when || '') !== String(draft.when || '')));
+    if (named) {
+      record = named;
+      mergedFrom = named.title === draft.title ? null : named.title;
+    }
+  }
   if (!record) {
     /** distinct 是用户明确说的「这是另一条」：同名也另起一条，不被规范化后的精确同名吞掉。 */
-    const hit = distinct ? null : resolveTarget(index.entries, draft);
+    const hit = distinct ? null : resolveTarget(live, draft);
     if (hit) {
       record = hit.target;
       mergedFrom = hit.target.title === draft.title ? null : hit.target.title;
     } else if (draft.has.topicKey && draft.topicKey && !distinct) {
       /** 同一槽位只留一条现行规范：同层同 topicKey + 同条件必须确认是更新还是另一条。 */
-      const slot = index.entries.find((item) => (item.topicKey || '') === draft.topicKey
+      const slot = live.find((item) => (item.topicKey || '') === draft.topicKey
         && view.conditionsKey(item.conditions) === view.conditionsKey(draft.conditions));
       if (slot) {
-        const row = { id: slot.id, title: slot.title, summary: slot.summary || '', revision: slot.revision || 1 };
+        const row = {
+          id: slot.id,
+          title: slot.title,
+          summary: slot.summary || '',
+          when: slot.when || '',
+          updated: slot.updated || slot.created || '',
+          reason: 'same_topic',
+          revision: slot.revision || 1,
+        };
         return { needsResolution: true, sameTopic: true, similarList: [row], similar: row, draft, record: null, merged: false, previousBody: null, archived: [] };
       }
-      similarList = similarEntries(index.entries, draft.title, draft.summary, 2);
+      similarList = similarEntries(live, draft.title, draft.summary, 2);
     } else {
-      similarList = similarEntries(index.entries, draft.title, draft.summary, 2);
+      similarList = similarEntries(live, draft.title, draft.summary, 2);
       /** 同名不同前置条件是用户明确表达的另一条，不走确认；只有换个说法的相近标题才拦。 */
-      const sameName = index.entries.some((item) => [item.title, ...(item.aliases || [])]
+      const sameName = live.some((item) => [item.title, ...(item.aliases || [])]
         .some((name) => String(name || '').toLowerCase() === draft.title.toLowerCase()));
       if (similarList.length > 0 && !distinct && !sameName) {
         return { needsResolution: true, similarList, similar: similarList[0], draft, record: null, merged: false, previousBody: null, archived: [] };
@@ -983,12 +1063,20 @@ function applyDraft(scope, index, source, now, options = {}) {
     }
   }
   const writeMode = source && source.writeMode === 'replace_current' ? 'replace_current' : 'patch';
+  /** 改名不能撞上另一条现行记忆：标题是唯一句柄，撞了以后按标题读会分不清。 */
+  if (record && draft.has.title && cleanTitle(draft.title) !== record.title) {
+    const wanted = cleanTitle(draft.title).toLowerCase();
+    const clash = live.find((item) => item.id !== record.id
+      && [item.title, ...(item.aliases || [])].some((name) => String(name || '').trim().toLowerCase() === wanted));
+    if (clash) throw new Error(`已经有同名记忆「${clash.title}」，先改那一条的标题`);
+  }
   if (record && writeMode === 'replace_current') {
     for (const key of ['title', 'summary', 'when', 'body', 'kind', 'tags']) {
       if (!draft.has[key]) throw new Error(`整份替换要给出 ${key}，空值也要显式写`);
     }
   }
   if (record) {
+    const target = supersedeTarget(record.id);
     const oldBody = readBody(scope, record.id);
     const next = mergedFields(draft, record, oldBody, index, writeMode, foreign);
     /** 正文原样保存：摘要再长也不往正文里补尾巴；完整原句进维护区。 */
@@ -1009,7 +1097,7 @@ function applyDraft(scope, index, source, now, options = {}) {
       && next.applicability === (record.applicability || 'all_in_scope')
       && next.body === oldBody
       && summaryFull === (typeof record.summaryFull === 'string' ? record.summaryFull : '');
-    if (noop) {
+    if (noop && !target) {
       return { record, merged: true, mergedFrom: null, similar: null, similarList, draft, noop: true, previousBody: oldBody, archived: [] };
     }
     const versions = snapshot(record, oldBody);
@@ -1036,10 +1124,18 @@ function applyDraft(scope, index, source, now, options = {}) {
     const archived = assertFits(scope, index, nextRecord);
     writeBody(scope, record.id, next.body);
     Object.assign(record, nextRecord);
-    return { record, merged: true, mergedFrom, similar: null, similarList, draft, noop: false, previousBody: oldBody, archived };
+    /** 更新让这条重新成为现行版本：旧的取代链标记要摘掉。 */
+    delete record.supersededBy;
+    record.validUntil = '';
+    if (target) {
+      const chain = stampSupersede(scope, target, record.id, now);
+      record.versions = [...chain, ...(record.versions || [])].slice(0, 2);
+    }
+    return { record, merged: true, mergedFrom, similar: null, similarList, draft, noop: Boolean(noop), previousBody: oldBody, archived };
   }
   if (writeMode === 'replace_current') throw new Error('整份替换要先指明是哪条，不能用来新增');
   /** 新建也只用调用方给的正文：超长摘要的完整原句进维护区，不混进正文。 */
+  const target = supersedeTarget('');
   const createdBody = draft.body;
   draft.fullTextInBody = false;
   draft.fullTextSaved = Boolean(draft.summaryFull);
@@ -1062,6 +1158,10 @@ function applyDraft(scope, index, source, now, options = {}) {
     aliases: [],
     created: now,
     updated: now,
+    validFrom: now,
+    validUntil: '',
+    supersededBy: '',
+    supersedeReason: '',
     lastUsed: now,
     revision: 1,
     status: 'active',
@@ -1079,9 +1179,42 @@ function applyDraft(scope, index, source, now, options = {}) {
   const archived = assertFits(scope, index, created);
   writeBody(scope, created.id, created.body);
   index.entries.push(created);
+  if (target) created.versions = stampSupersede(scope, target, created.id, now);
   return { record: created, merged: false, mergedFrom: null, similar: similarList[0] || null, similarList, draft, noop: false, previousBody: null, archived };
 }
 
+/**
+ * 写入前兜底扫描：记忆会被 memory_read 原样喂回模型，所以只拦形状明确的三类——
+ * 提示注入指令、凭据原文、不可见 Unicode；提到「凭据 / 指令」的正文不算。
+ */
+const UNSAFE_TEXT = [
+  { code: 'injection', why: '像提示注入的指令', fix: '把「指令」改成对规则的描述', test: /ignore\s+(?:all\s+)?(?:previous|prior|above)\s+(?:instructions?|rules?|prompts?)/i },
+  { code: 'injection', why: '像提示注入的指令', fix: '把「指令」改成对规则的描述', test: /忽略(?:上面|以上|此前|之前)?(?:的)?(?:所有)?(?:指令|指示|要求|规则)/ },
+  { code: 'injection', why: '像提示注入的指令', fix: '把「指令」改成对规则的描述', test: /<\/?(?:system|instructions?|prompt|tool_call)[^>]*>/i },
+  { code: 'injection', why: '像提示注入的指令', fix: '把「指令」改成对规则的描述', test: /(?:^|\n)\s*(?:system|assistant)\s*[:：]/i },
+];
+const INVISIBLE = /[\u200B-\u200F\u202A-\u202E\u2060-\u2064\u2066-\u2069\uFEFF]|[\u{E0000}-\u{E007F}]/u;
+const SCAN_FIELD_NAMES = { title: '标题', summary: '摘要', when: '适用场景', body: '正文', tags: '标签', triggers: '触发词', conditions: '条件', selection: '适用范围' };
+
+function scanUnsafe(draft) {
+  const fields = [
+    ['title', draft.title], ['summary', draft.summary], ['when', draft.when], ['body', draft.body],
+    ['tags', (draft.tags || []).join('\n')], ['triggers', (draft.triggers || []).join('\n')],
+    ['conditions', JSON.stringify(draft.conditions || [])], ['selection', JSON.stringify(draft.selection || null)],
+  ];
+  for (const [field, raw] of fields) {
+    const text = typeof raw === 'string' ? raw : '';
+    if (!text) continue;
+    const name = SCAN_FIELD_NAMES[field] || field;
+    if (INVISIBLE.test(text)) {
+      throw new state.StateError('unsafe', `${name}里有看不见的字符（零宽或方向控制）；它们会跟着记忆原样回到模型，删掉再存`);
+    }
+    for (const rule of UNSAFE_TEXT) {
+      if (rule.test.test(text)) throw new state.StateError('unsafe', `${name}${rule.why}；${rule.fix}`);
+    }
+  }
+}
+
 /**
  * 单条与记录序列化两档预算：新增与更新走同一套。
  * 整层条数/正文预算由 state.transact 在发布前裁决（腾最久没读的那条，不拒绝新记忆），
@@ -1359,6 +1492,8 @@ export function search(scope, query, limit = 4, options = {}) {
       const collect = (pool, archived) => {
         for (const item of pool) {
           if (!readableRecord(item, options, index)) continue;
+          /** 被取代/过期待记录默认不出现；history:true 才列出，供模型看演化。 */
+          if (options.history !== true && staleRecord(item, options.now || Date.now())) continue;
           /** 已暂停、已过期或待确认的学习规则不进入检索结果，除非明确要病史。 */
           if (options.allowExperimental === true && options.history !== true
             && isExperimentalRecord(item) && !view.experimentalUsable(item, options.now)) continue;
@@ -1443,8 +1578,10 @@ export function peek(scope, query, limit = 3, options = {}) {
 }
 
 export function readEntry(scope, id, options = {}) {
-  const found = withLocks([scope, globalScope()], () => {
-    for (const source of [scope, globalScope()]) {
+  /** 显式指定层时只读那一层；默认仍只读当前项目和全局。 */
+  const sources = Array.isArray(options.layers) && options.layers.length ? options.layers : runtimeLayers(scope);
+  const found = withLocks(sources, () => {
+    for (const source of sources) {
       const index = loadIndex(source);
       const record = index.entries.find((item) => item.id === id);
       const archived = record ? null : index.archived.find((item) => item.id === id);
@@ -1465,8 +1602,9 @@ export function readEntry(scope, id, options = {}) {
     return null;
   });
   if (!found) return null;
-  /** 读过才算用过；归档的不回写（看病史不等于「在用」）。 */
-  if (!found.archived) touchUsed(found.source, [id]);
+  /** 读过才算用过；归档、被取代、过期或条件不匹配的读取都不算「在用」。 */
+  const countsAsUsage = typeof options.usage !== 'function' || options.usage(found.record) !== false;
+  if (!found.archived && countsAsUsage) touchUsed(found.source, [id]);
   return found.record;
 }
 
@@ -1477,11 +1615,14 @@ export function readEntry(scope, id, options = {}) {
 export function forget(scope, id, options = {}) {
   const mode = options.mode;
   if (mode !== 'archive' && mode !== 'purge') return { id, mode: 'needs_resolution' };
-  return withLocks([scope, globalScope()], () => {
+  /** 显式指定的层就是唯一范围；不然才按运行时「当前项目 + 全局」找。 */
+  const sources = Array.isArray(options.layers) && options.layers.length ? options.layers : null;
+  const scopeList = sources || [scope, globalScope()];
+  return withLocks(scopeList, () => {
     /** 屏障优先：上次彻底删除没做完时，先按原层 + 原 operationId 收尾，再决定这条在哪。 */
     let replayed = null;
     if (mode === 'purge') {
-      for (const source of [scope, globalScope()]) {
+      for (const source of scopeList) {
         const pending = state.purgeIntent(source);
         if (!pending) continue;
         /** 冷存里有待删条目的正文副本：先隔离，state.purge 的残留扫描才收得干净。 */
@@ -1502,7 +1643,7 @@ export function forget(scope, id, options = {}) {
       }
       if (replayed) return replayed;
     }
-    for (const source of [scope, globalScope()]) {
+    for (const source of scopeList) {
       const index = loadIndex(source);
       const active = index.entries.find((item) => item.id === id);
       const archived = active ? null : index.archived.find((item) => item.id === id);
@@ -1554,8 +1695,8 @@ export function forget(scope, id, options = {}) {
 
 /** 直接读邻居：只给当前投影，不缓存目标正文；目标不在了就标 invalid，不拿旧版本顶上。 */
 export function readLinks(scope, id, options = {}) {
-  return withLocks([scope, globalScope()], () => {
-    for (const source of [scope, globalScope()]) {
+  return withLocks(runtimeLayers(scope), () => {
+    for (const source of runtimeLayers(scope)) {
       const index = loadIndex(source);
       const record = index.entries.find((item) => item.id === id);
       if (!record) continue;
@@ -1574,7 +1715,7 @@ export function readLinks(scope, id, options = {}) {
 
 /** 关联目标按当前投影现场解引用：先项目层再全局层，归档和删除都算不存在。 */
 function findCurrent(id, scope, options = {}) {
-  for (const source of [scope, globalScope()]) {
+  for (const source of runtimeLayers(scope)) {
     let index;
     try {
       index = loadIndex(source);
@@ -1594,6 +1735,8 @@ function findCurrent(id, scope, options = {}) {
       summary: record.summary || '',
       scope: source.key === 'global' ? 'global' : 'project',
       revision: record.revision || 1,
+      validUntil: record.validUntil || '',
+      supersededBy: record.supersededBy || '',
       status: 'ok',
     };
   }
@@ -1711,9 +1854,51 @@ export function findAnywhere(id) {
   return null;
 }
 
+/** 运行时只允许当前项目和全局层：别的项目仅供人类管理面只读枚举。 */
+export function runtimeLayers(scope) {
+  const out = [];
+  const seen = new Set();
+  const push = (item) => {
+    if (!item || !item.dir || seen.has(item.dir)) return;
+    seen.add(item.dir);
+    out.push(item);
+  };
+  push(scope);
+  push(globalScope());
+  return out;
+}
+
 /** 按 id 在项目层与全局层里找位置，不靠文案猜作用域；管理动作也要看得见已归档的条目。 */
+/**
+ * 标题是唯一对外的句柄：当前项目找不到，就去全局和别的项目层找。
+ * 只用于读路径（读正文、查关联、解析标题）；写入仍然只动自己那层。
+ */
+export function layersFor(scope) {
+  const out = [];
+  const seen = new Set();
+  const push = (item) => {
+    if (!item || !item.dir || seen.has(item.dir)) return;
+    seen.add(item.dir);
+    out.push(item);
+  };
+  push(scope);
+  push(globalScope());
+  try {
+    for (const row of state.knownProjectScopes()) push({ key: row.key, dir: row.dir, cwd: row.cwd });
+  } catch { /* 层列表读不出来就只查当前层和全局，不影响读取 */ }
+  return out;
+}
+
 export function locate(scope, id, options = {}) {
-  for (const source of [scope, globalScope()]) {
+  /**
+   * 默认只看当前层和全局：面板/HTTP 用 id 探正文时跨层就是越权。
+   * 工具侧按标题读，明确传 crossLayer 才跨层（标题是用户给的句柄）；
+   * 显式指定某一层时只给那一层，绝不拿项目层去命中全局条目。
+   */
+  const sources = Array.isArray(options.layers) && options.layers.length
+    ? options.layers
+    : options.crossLayer ? layersFor(scope) : runtimeLayers(scope);
+  for (const source of sources) {
     const index = loadIndex(source, options);
     const active = index.entries.find((item) => item.id === id);
     if (active) return { scope: source, record: active, archived: false };
@@ -1723,6 +1908,35 @@ export function locate(scope, id, options = {}) {
   return null;
 }
 
+/**
+ * 标题是界面和模型唯一的句柄：在给定范围里按标题（含别名）找那一条。
+ * 同层可能同名但适用条件不同，所以带了版次就先按版次收敛，再退回第一条。
+ */
+export function locateByTitle(scope, title, options = {}) {
+  const wanted = normalizeText(title, 120).toLowerCase();
+  if (!wanted) return null;
+  const sources = options.crossLayer ? layersFor(scope) : runtimeLayers(scope);
+  const want = Number.isInteger(options.revision) ? options.revision : null;
+  for (const source of sources) {
+    const index = loadIndex(source, options);
+    const pick = (list) => {
+      const rows = list.filter((item) => [item.title, ...(Array.isArray(item.aliases) ? item.aliases : [])]
+        .some((name) => normalizeText(name, 120).toLowerCase() === wanted));
+      if (rows.length === 0) return null;
+      if (want !== null) {
+        const exact = rows.find((item) => (Number(item.revision) || 1) === want);
+        if (exact) return exact;
+      }
+      return rows[0];
+    };
+    const active = pick(index.entries);
+    if (active) return { scope: source, record: active, archived: false };
+    const archived = pick(index.archived);
+    if (archived) return { scope: source, record: archived, archived: true };
+  }
+  return null;
+}
+
 function forgottenFingerprints(index) {
   const out = new Set();
   for (const row of index.suppressions || []) {
@@ -2002,7 +2216,7 @@ export function renderIndex(entries, budget = 400) {
     const stateTag = item.state === 'archived' ? ' · 已归档' : item.state === 'needs_context' ? ' · 适用范围待确认' : item.state === 'not_applicable' ? ' · 当前条件不适用' : '';
     const originTag = item.origin === 'project_evolution' ? ' · 实验' : '';
     const tag = item.scope === 'global' ? '[global]' : item.scopeName ? `[${item.scopeName}]` : '';
-    const head = `${tag ? `${tag} ` : ''}${item.id} ${item.title}${item.when ? `（${item.when}）` : ''}${originTag}${stateTag}`;
+    const head = `${tag ? `${tag} ` : ''}「${item.title}」${item.when ? `（${item.when}）` : ''}${originTag}${stateTag}`;
     const line = stale ? `- ${head}` : `- ${head}｜${item.summary}`;
     if (used + line.length > budget) break;
     lines.push(line);
@@ -2176,6 +2390,30 @@ export function readCitationBody(sessionId, id) {
   const data = readSessionFile(sessionId);
   const row = ((data && data.items) || []).find((item) => item && item.id === id);
   if (!row) return null;
+  return readCitationRow(sessionId, row);
+}
+
+/** 按标题读引用正文：界面手里只有标题，id 留在引用文件里。 */
+export function readCitationBodyByTitle(sessionId, title, options = {}) {
+  const wanted = normalizeText(title, 120).toLowerCase();
+  if (!wanted) return null;
+  const data = readSessionFile(sessionId);
+  const want = Number.isInteger(options.revision) ? options.revision : null;
+  const scopeWanted = options.scope === 'global' || options.scope === 'project' ? options.scope : '';
+  /** 引用行只存身份，标题要从当前索引解析出来再比；行上没有 title 字段。 */
+  const matches = ((data && data.items) || [])
+    .map((row) => ({ row, found: resolveCitation(row) }))
+    .filter((item) => item.found
+      && (!scopeWanted || (item.found.scope.key === 'global' ? 'global' : 'project') === scopeWanted)
+      && normalizeText(item.found.row.title || '', 120).toLowerCase() === wanted);
+  if (matches.length === 0) return null;
+  const chosen = (want !== null
+    && matches.find((item) => (Number(item.found.entry.revision) || 1) === want)) || matches[0];
+  return readCitationRow(sessionId, chosen.row);
+}
+
+function readCitationRow(sessionId, row) {
+  const id = row.id;
   const found = resolveCitation(row);
   if (!found) return null;
   let body;
@@ -2188,6 +2426,7 @@ export function readCitationBody(sessionId, id) {
   }
   return {
     ...found.row,
+    status: found.entry.status || 'active',
     scopeLabel: found.scope.key === 'global' ? '全局' : path.basename(found.scope.cwd || '') || found.scope.key,
     body: body.slice(0, LIMITS.entryBytes),
   };
@@ -2353,28 +2592,90 @@ function crossLayerSimilar(projectScope, targetScope, draft) {
     id: item.id,
     title: item.title,
     summary: item.summary || '',
+    when: item.when || '',
+    updated: item.updated || '',
+    reason: item.reason || 'similar_title',
     revision: item.revision || 1,
     scope: other.key === 'global' ? 'global' : 'project',
   }));
 }
 
 function bindSameTopic(projectScope, ref) {
-  if (!ref || typeof ref !== 'object' || typeof ref.id !== 'string') return { error: 'sameTopicAs 要写成 {scope, id, revision}' };
+  if (!ref || typeof ref !== 'object') return { error: 'sameTopicAs 要写成 {scope, title}' };
   const source = ref.scope === 'global' ? globalScope() : projectScope;
-  const record = loadIndex(source).entries.find((item) => item.id === ref.id);
-  if (!record) return { error: `sameTopicAs 指向的记忆不存在：${ref.id}` };
-  if (Number(ref.revision) !== Number(record.revision || 1)) {
-    return { error: `sameTopicAs 的目标已经改过：${ref.id}` };
+  /** 句柄统一用标题：id 是底层实现，模型手里不该出现；老调用传 id 仍认。 */
+  const byTitle = typeof ref.title === 'string' ? normalizeText(ref.title, 120).toLowerCase() : '';
+  const record = loadIndex(source).entries.find((item) => (typeof ref.id === 'string' && item.id === ref.id)
+    || (byTitle && [item.title, ...(item.aliases || [])].some((name) => normalizeText(name, 120).toLowerCase() === byTitle)));
+  if (!record) return { error: `sameTopicAs 指向的记忆不存在：${ref.title || ref.id || ''}` };
+  if (ref.revision !== undefined && Number(ref.revision) !== Number(record.revision || 1)) {
+    return { error: `sameTopicAs 的目标已经改过：「${record.title}」` };
   }
   return { topicKey: view.topicSlot(record) };
 }
 
+
+/** 冲突队列：只记待办，不预写记忆；最多 20 条。 */
+const CONFLICT_LIMIT = 20;
+
+function queueConflictLocked(scope, draft, candidates) {
+  const index = loadIndex(scope);
+  const title = normalizeText(draft && draft.title, 120);
+  if (!title) return Array.isArray(index.conflicts) ? index.conflicts.length : 0;
+  const scopeKey = scope.key === 'global' ? 'global' : 'project';
+  const now = new Date().toISOString();
+  const rows = Array.isArray(index.conflicts) ? index.conflicts : [];
+  const view = candidates.slice(0, 2).map((item) => ({
+    id: item.id, title: item.title || '', when: item.when || '', reason: item.reason || 'similar_title',
+  }));
+  const hit = rows.find((row) => row.title === title && row.scope === scopeKey);
+  if (hit) {
+    hit.candidates = view;
+    hit.updatedAt = now;
+  } else {
+    rows.push({ id: `cf_${crypto.randomUUID().replace(/-/g, '').slice(0, 12)}`, title, scope: scopeKey, candidates: view, createdAt: now, updatedAt: now });
+  }
+  index.conflicts = rows.slice(-CONFLICT_LIMIT);
+  saveIndex(scope, index);
+  return index.conflicts.length;
+}
+
+function clearConflictLocked(scope, title) {
+  const index = loadIndex(scope);
+  const rows = Array.isArray(index.conflicts) ? index.conflicts : [];
+  const norm = normalizeText(title, 120);
+  const next = rows.filter((row) => !(row.title === norm && row.scope === (scope.key === 'global' ? 'global' : 'project')));
+  if (next.length === rows.length) return rows.length;
+  index.conflicts = next;
+  saveIndex(scope, index);
+  return next.length;
+}
+
+/** 当前层还有几条没处理的冲突。 */
+export function pendingConflictsOf(scope) {
+  const rows = loadIndex(scope).conflicts;
+  return Array.isArray(rows) ? rows.length : 0;
+}
+
 /**
  * 保存的唯一入口：先路由，再在两层里查重（完全相同 → existing_ref；只是相近 → 只给候选），
  * 最后才写。写之前判不出来的范围返回 needsScope，不替用户选。
  */
+function saveTargetOf(projectScope, source) {
+  /** 更新已有条目：先按 id 认出它到底在哪一层，只锁那一层。 */
+  const id = source && typeof source.id === 'string' ? source.id.trim() : '';
+  if (id) {
+    const found = locateInLayers(projectScope, id);
+    if (found) return found.scope;
+  }
+  /** 新增条目：归属由路由定，写全局就不该占住项目锁，反之亦然。 */
+  const routed = routeScope(source, { project: projectScope });
+  return routed.chosenScope === 'global' ? globalScope() : projectScope;
+}
+
 export function saveEntry(projectScope, source) {
-  return withLocks([projectScope, globalScope()], () => {
+  /** 只锁真正要写的那一层：别的项目写它自己的条目时，不会因为共享全局锁互相等待。 */
+  return withLocks([saveTargetOf(projectScope, source)], () => {
     const control = loadIndex(projectScope).__control || state.controlOf(null);
     if (!control.enabled) {
       return { needsScope: true, chosenScope: '', reasonCode: 'memory_disabled', requiredConditions: [], needsResolution: false, similarList: [], draft: null };
@@ -2396,7 +2697,23 @@ export function saveEntry(projectScope, source) {
     if (next.id) {
       const found = locateInLayers(projectScope, next.id);
       if (!found) throw new Error('没有这条记忆，改用新增');
+      /** 写了 scope 就只改那一层：同名条目在别层时不能悄悄改到别处。 */
+      const explicitScope = String(source.scope || '').trim();
+      if (explicitScope === 'global' && found.scope.key !== 'global') {
+        throw new Error('这条记忆在项目层；scope="global" 只改全局同名条目');
+      }
+      if (explicitScope === 'project' && found.scope.key === 'global') {
+        throw new Error('这条记忆在全局层；只有明确说「所有项目都这样」才改它');
+      }
       targetScope = found.scope;
+      /** 面板拿旧版本改正文：中间被别处改过就拒绝，不覆盖别人的修改。 */
+      if (source.expectedRevision !== undefined) {
+        const current = loadIndex(targetScope).entries.find((item) => item.id === next.id && item.status !== 'archived');
+        if (!current) throw new Error('没有这条记忆，改用新增');
+        if (!Number.isInteger(Number(source.expectedRevision)) || Number(current.revision) !== Number(source.expectedRevision)) {
+          throw new state.StateError('conflict', '这条记忆已经被更新过，刷新后再改');
+        }
+      }
     }
     /** 更新已有项目条目也必须落在确认过的根目录里。 */
     if (targetScope.key !== 'global' && targetScope.confirmed === false) {
@@ -2412,19 +2729,29 @@ export function saveEntry(projectScope, source) {
       }
       const near = crossLayerSimilar(projectScope, targetScope, draft);
       if (near.length) {
+        const pendingConflicts = queueConflictLocked(targetScope, draft, near);
         return {
           needsResolution: true,
           crossLayer: true,
+          /** 相近那条在哪一层：跨层「用同一个标题再存一次」得落在它那层，否则会另建一条。 */
+          crossScope: near[0] && near[0].scope === 'global' ? 'global' : 'project',
           similarList: near,
           similar: near[0],
           draft,
           needsScope: false,
+          pendingConflicts,
           chosenScope: targetScope.key === 'global' ? 'global' : 'project',
         };
       }
     }
     const foreign = targetScope.key === 'global' ? [] : loadIndex(globalScope()).entries;
     const result = upsertLocked(targetScope, next, { foreignEntries: foreign });
+    if (!result.needsResolution) clearConflictLocked(targetScope, draft ? draft.title : next.title);
+    if (result.needsResolution) {
+      const rows = Array.isArray(result.similarList) ? result.similarList : [];
+      const pendingConflicts = queueConflictLocked(targetScope, result.draft || draft, rows);
+      return { ...result, chosenScope: targetScope.key === 'global' ? 'global' : 'project', needsScope: false, reasonCode: routed.reasonCode, pendingConflicts };
+    }
     return { ...result, chosenScope: targetScope.key === 'global' ? 'global' : 'project', needsScope: false, reasonCode: routed.reasonCode };
   });
 }
@@ -2760,6 +3087,7 @@ function learningRuleView(record) {
     conditions: Array.isArray(record.conditions) ? record.conditions : [],
     topicKey: record.topicKey || '',
     origin: record.origin,
+    reviewState: record.reviewState === 'legacy_unreviewed' ? 'legacy_unreviewed' : 'active',
     state: record.learning?.state || 'pending',
     samples: (Array.isArray(record.learning?.samples) ? record.learning.samples : []).slice(-4).map((row) => ({
       dimension: row.dimension || '作品',