dsh-lite-memory 0.18.1 → 0.18.19

package/learning.js

@@ -40,6 +40,11 @@ const NEGATIVE = /不要|不用|别用|别再|停用|取消这条|这条不要|
 const CORRECTION = /改成|改为|换成|重做|重来|再来|下次|不对|错了|不是这样|又没|怎么又|还是没|没按|不好|不行|不满意|不要|别/;
 const EXECUTION_MISS = /之前说过|已经说过|不是说好|怎么又|又没|还是没|没按|又忘|重复/;
 const UNCLEAR = /不太对|再想想|感觉不对|说不上|有点怪|不对劲/;
+/**
+ * 点名项目范围才算全项目授权；「以后都」不等于「所有项目」。
+ * 「所有口播」「一律」这种覆盖全部对象的说法也算，但只限当前项目层。
+ */
+const PROJECT_WIDE = /(这个项目|本项目|所有项目|全项目|整个项目|全库|每个项目|所有(?!项目)|一律)/;
 
 const has = (pattern, text) => pattern.test(text);
 
@@ -182,6 +187,8 @@ export function candidateFrom({ messages, anchor, sessionId, projectId, now } =
   if (!context.projectId) return null;
   /** 没有作品绑定时，规范纠正同样按项目候选收集；单次局部改动交给整理器判空，不再用电平词一刀切。 */
   if (cue.type !== 'spec_change') return null;
+  /** 作用域在收集时就固定：只有原句点名项目范围才给全项目，否则先待确认。 */
+  const applicability = PROJECT_WIDE.test(text) ? 'all_in_scope' : 'unresolved';
   return {
     projectId: context.projectId,
     sessionId: context.sessionId,
@@ -195,7 +202,7 @@ export function candidateFrom({ messages, anchor, sessionId, projectId, now } =
     text,
     sourceExcerpt,
     cue,
-    expectedTarget: { scope: 'project', projectId, applicability: 'unresolved' },
+    expectedTarget: { scope: 'project', projectId, applicability },
     episodeUpdatedAt: '',
     at,
   };
@@ -356,13 +363,36 @@ export function pendingChangeFrom(feedback = {}) {
   if (!currentText) return null;
   const first = (lines[0] || currentText).split(/[，。！？；]/)[0].trim();
   const topicKey = String(feedback.cue?.dimension || first || currentText).slice(0, 60);
+  /**
+   * 兜底不是授权：只在文本自己说到全项目时才按全项目收，否则保留它原本的适用范围
+   * （有任务种类就挂条件，没有就待确认），不能让一句「以后开头先给结论」变成全库规则。
+   */
+  const expected = feedback.expectedTarget && typeof feedback.expectedTarget === 'object' ? feedback.expectedTarget : null;
+  const taskKind = String(feedback.cue?.taskKind || expected?.taskKind || '').trim();
+  const expectedConditions = ['taskKind', 'seriesId', 'phase']
+    .filter((key) => String(expected?.[key] || '').trim())
+    .map((key) => ({ key, value: String(expected[key]).trim() }));
+  /**
+   * 兜底不重新推导作用域：候选收集时已经固定 expectedTarget 就照抄（只能沿用或收窄），
+   * 没有 expectedTarget 的旧调用才退回原句判断。
+   */
+  const applicability = expected
+    ? (expected.applicability === 'all_in_scope'
+      ? 'all_in_scope'
+      : expectedConditions.length ? 'conditional' : 'unresolved')
+    : /(所有|全都|一律|任何|默认|整个项目|这个项目|本项目)/.test(currentText)
+      ? 'all_in_scope'
+      : taskKind ? 'conditional' : 'unresolved';
+  const conditions = expected
+    ? (applicability === 'conditional' ? expectedConditions : [])
+    : applicability === 'conditional' ? [{ key: 'taskKind', value: taskKind }] : [];
   return {
     target: 'new',
     feedbackType: 'spec_change',
     topicKey,
     currentText,
-    applicability: 'all_in_scope',
-    conditions: [],
+    applicability,
+    conditions,
     evidence: ['u0'],
     persistence: 'project_candidate',
     /** 摘录从候选一路带到提交路径，模型返回空时也不丢来源。 */
@@ -504,7 +534,7 @@ export function buildCallInput({ projectId, episodeId, taskKind, seriesId, phase
   return { system, prompt, messages: [{ role: 'user', content: prompt }], refs, rules: inputRules, bytes: Buffer.byteLength(system) + Buffer.byteLength(prompt), sourceExcerpt, messageIds };
 }
 /** 严格解析：截断、工具调用、额外字段、超限都整批拒绝，不做第二次修复调用。 */
-export function parseOutput(text, { finish, refs, rules, ranges } = {}) {
+export function parseOutput(text, { finish, refs, rules, ranges, expectedTarget } = {}) {
   if (finish && finish.kind !== 'stop' && finish.kind !== 'completed') return { ok: false, reason: '整理没有正常结束' };
   const raw = String(text || '').trim();
   if (!raw) return { ok: false, reason: '整理没有返回内容' };
@@ -522,14 +552,14 @@ export function parseOutput(text, { finish, refs, rules, ranges } = {}) {
   if (data.changes.length > LIMITS.maxChanges) return { ok: false, reason: '一次改动太多' };
   const changes = [];
   for (const change of data.changes) {
-    const checked = validateChange(change, { refs, rules, ranges });
+    const checked = validateChange(change, { refs, rules, ranges, expectedTarget });
     if (!checked.ok) return checked;
     changes.push(checked.change);
   }
   return { ok: true, changes };
 }
 
-export function validateChange(change, { refs, rules, ranges } = {}) {
+export function validateChange(change, { refs, rules, ranges, expectedTarget } = {}) {
   if (!change || typeof change !== 'object' || Array.isArray(change)) return { ok: false, reason: '变化不是对象' };
   for (const key of Object.keys(change)) if (!ALLOWED_KEYS.has(key)) return { ok: false, reason: `变化里有未知字段：${key}` };
   const byRef = new Map((Array.isArray(rules) ? rules : []).map((row) => [row.ref, row]));
@@ -590,6 +620,35 @@ export function validateChange(change, { refs, rules, ranges } = {}) {
       if (!allowed) return { ok: false, reason: '条件值不在本项目的栏目或阶段里' };
     }
   }
+  /** 收集时固定的作用域只能沿用或收窄：整理器不能把待确认候选抬成全项目规则。 */
+  const expected = expectedTarget && typeof expectedTarget === 'object' ? expectedTarget : null;
+  const expectedConditions = ['taskKind', 'seriesId', 'phase']
+    .filter((key) => String(expected?.[key] || '').trim())
+    .map((key) => ({ key, value: String(expected[key]).trim() }));
+  const expectedApplicability = expected
+    ? (expected.applicability === 'all_in_scope'
+      ? 'all_in_scope'
+      : expectedConditions.length ? 'conditional' : 'unresolved')
+    : '';
+  if (expectedApplicability && applicability === 'all_in_scope' && expectedApplicability !== 'all_in_scope') {
+    return { ok: false, reason: '适用范围不能从待确认抬成全项目' };
+  }
+  if (expected && expected.scope === 'episode' && applicability === 'all_in_scope') {
+    return { ok: false, reason: '作品规则不能抬成全项目' };
+  }
+  const effectiveConditions = conditions !== undefined ? conditions : normalizeConditions(existing?.conditions);
+  if (applicability === 'all_in_scope' && effectiveConditions.length) {
+    return { ok: false, reason: '全项目规则不能带条件' };
+  }
+  if (applicability === 'conditional' && !conditions && !existing && !sampleOnly) {
+    return { ok: false, reason: '条件适用必须给出条件' };
+  }
+  if (conditions && expectedConditions.length) {
+    const has = new Set(conditions.map((row) => `${row.key}=${row.value}`));
+    if (expectedConditions.some((row) => !has.has(`${row.key}=${row.value}`))) {
+      return { ok: false, reason: '条件不能删掉收集时的任务范围' };
+    }
+  }
   const evidence = Array.isArray(change.evidence) ? change.evidence.map((value) => String(value)) : [];
   if (!evidence.length || evidence.length > LIMITS.evidence) return { ok: false, reason: '证据数量不对' };
   for (const ref of evidence) if (!refs?.feedback?.[ref]) return { ok: false, reason: '证据不在本次反馈里' };

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "dsh-lite-memory",
-  "version": "0.18.1",
-  "description": "On-demand memory for the DeepSeek Harness: nothing in the system prompt, one muted line only when something is saved, hit or suggested.",
+  "version": "0.18.19",
+  "description": "On-demand memory for the DeepSeek Harness: nothing resident, at most three small cards on a real hit, bodies read on demand.",
   "type": "module",
   "main": "index.js",
   "engines": {
     "dsh": ">=0.1.5"
   },
   "scripts": {
-    "test": "node test/store.test.mjs && node test/state.test.mjs && node test/view.test.mjs && node test/anchor.test.mjs && node test/recall.test.mjs && node test/evolution-read.test.mjs && node test/lexical.test.mjs && node test/control.test.mjs && node test/learning.test.mjs && node test/scenario.test.mjs && node test/crossing.test.mjs && node test/runtime-context.test.mjs && node test/client.test.mjs && node test/palace.test.mjs && node test/contract.test.mjs && node test/safety.test.mjs && node test/ha.test.mjs && node test/record.test.mjs",
+    "test": "node test/store.test.mjs && node test/state.test.mjs && node test/view.test.mjs && node test/anchor.test.mjs && node test/recall.test.mjs && node test/evolution-read.test.mjs && node test/lexical.test.mjs && node test/layer-read.test.mjs && node test/control.test.mjs && node test/learning.test.mjs && node test/scenario.test.mjs && node test/crossing.test.mjs && node test/runtime-context.test.mjs && node test/client.test.mjs && node test/palace.test.mjs && node test/contract.test.mjs && node test/safety.test.mjs && node test/ha.test.mjs && node test/record.test.mjs && node test/eval-seed.test.mjs",
     "bench": "node bench/bench.mjs",
     "bench:evolution": "node bench/evolution.mjs"
   },

package/state.js

@@ -106,12 +106,13 @@ export function evolutionOf(state) {
 export function controlOf(state) {
   const raw = state && state.control;
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
-    return { enabled: true, epoch: '', changedAt: '', compatible: true };
+    return { enabled: true, epoch: '', changedAt: '', recoveryPending: false, compatible: true };
   }
   return {
-    enabled: raw.enabled !== false,
+    enabled: raw.enabled !== false && raw.recoveryPending !== true,
     epoch: typeof raw.epoch === 'string' ? raw.epoch : '',
     changedAt: typeof raw.changedAt === 'string' ? raw.changedAt : '',
+    recoveryPending: raw.recoveryPending === true,
     compatible: true,
   };
 }
@@ -143,13 +144,39 @@ export function applyControl(draft, enabled) {
   return { changed: true, enabled: next, epoch: config.epoch };
 }
 
+/**
+ * 旧策略生成的实验规则没记下作用域指纹，无法证明它该在哪些任务里出现。
+ * 只把它们转成待复核：正文、来源、版本原样保留，不删除也不改写内容。
+ */
+function quarantineLegacyRules(draft, now) {
+  let touched = 0;
+  for (const entry of Array.isArray(draft.entries) ? draft.entries : []) {
+    if (!entry || entry.origin !== 'project_evolution') continue;
+    const maintenance = entry.maintenance || (entry.maintenance = {});
+    if (maintenance.reviewState === 'legacy_unreviewed') continue;
+    if (maintenance.learning && maintenance.learning.specDigest) continue;
+    maintenance.reviewState = 'legacy_unreviewed';
+    maintenance.legacyReview = { reason: 'scope_unverified', at: now };
+    const learning = maintenance.learning;
+    if (learning && (learning.state === 'trial' || learning.state === 'active')) {
+      learning.state = 'paused';
+      learning.blockedReason = 'needs_scope_review';
+      learning.pausedAt = now;
+      learning.pausedBy = 'legacy_scope';
+    }
+    touched += 1;
+  }
+  return touched;
+}
+
 /** 自进化开关只停运行层：规则、候选、试用、证据和额度都保留，恢复时接着用。 */
 export function applyEvolution(draft, enabled) {
   const now = new Date().toISOString();
   const current = evolutionOf(draft);
   if (!current.compatible) throw new StateError('invalid', '实验配置版本不认，先不要改动开关');
   const next = Boolean(enabled);
-  if (current.enabled === next) return { changed: false, enabled: next };
+  const quarantined = next ? quarantineLegacyRules(draft, now) : 0;
+  if (current.enabled === next) return { changed: quarantined > 0, enabled: next, quarantined };
   const config = {
     enabled: next,
     epoch: crypto.randomUUID(),
@@ -174,7 +201,7 @@ export function applyEvolution(draft, enabled) {
       }
     }
   }
-  return { changed: true, enabled: next, epoch: config.epoch };
+  return { changed: true, enabled: next, epoch: config.epoch, quarantined };
 }
 
 /** 容量与预算都归这里管：写入路径只报「要写什么」，能不能落地由 state 决定。 */
@@ -1142,6 +1169,20 @@ export function migrateLegacy(scope, options = {}) {
   });
 }
 
+/** 恢复出来的状态把总开关留在关闭态并记下原因，避免用一份旧快照静默恢复授权。 */
+function withRecoveryMarker(payload) {
+  const raw = payload && payload.control && typeof payload.control === 'object' && !Array.isArray(payload.control) ? payload.control : {};
+  return {
+    ...payload,
+    control: {
+      enabled: false,
+      epoch: typeof raw.epoch === 'string' ? raw.epoch : '',
+      changedAt: new Date().toISOString(),
+      recoveryPending: true,
+    },
+  };
+}
+
 /**
  * 读当前状态：只有「完全没有」才算新库；坏文件、未知版本、迁移痕迹都报错，
  * 绝不用空库覆盖。
@@ -1173,7 +1214,7 @@ export function load(scope, options = {}) {
     }
     if (recovered) {
       return {
-        state: recovered,
+        state: withRecoveryMarker(recovered),
         exists: true,
         recovered: true,
         recovery: {
@@ -1204,7 +1245,7 @@ export function load(scope, options = {}) {
     const prev = readEnvelope(prevFile(scope));
     if (prev) {
       // current 丢了但 prev 完好：恢复 prev，并标记需要重写 current。
-      return { state: prev, exists: false, recovered: true };
+      return { state: withRecoveryMarker(prev), exists: false, recovered: true };
     }
     return { state: emptyState(scope), exists: false, recovered: false };
   }

package/store.js

@@ -1011,6 +1011,24 @@ function applyDraft(scope, index, source, now, options = {}) {
   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(live, draft);
@@ -1045,6 +1063,13 @@ 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}，空值也要显式写`);
@@ -1553,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);
@@ -1575,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;
 }
 
@@ -1587,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 的残留扫描才收得干净。 */
@@ -1612,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);
@@ -1664,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;
@@ -1684,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);
@@ -1823,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 };
@@ -1835,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 || []) {
@@ -2114,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);
@@ -2288,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;
@@ -2300,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),
   };
@@ -2474,12 +2601,15 @@ function crossLayerSimilar(projectScope, targetScope, draft) {
 }
 
 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) };
 }
@@ -2531,8 +2661,21 @@ export function pendingConflictsOf(scope) {
  * 保存的唯一入口：先路由，再在两层里查重（完全相同 → 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 };
@@ -2554,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) {
@@ -2574,6 +2733,8 @@ export function saveEntry(projectScope, source) {
         return {
           needsResolution: true,
           crossLayer: true,
+          /** 相近那条在哪一层：跨层「用同一个标题再存一次」得落在它那层，否则会另建一条。 */
+          crossScope: near[0] && near[0].scope === 'global' ? 'global' : 'project',
           similarList: near,
           similar: near[0],
           draft,
@@ -2926,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 || '作品',