@a9i5k4/dsh-auto-memory 2.5.3 → 3.0.1

package/lib/recall-fusion.js

@@ -21,6 +21,19 @@ export const FUSION_RRF_K_V1 = 60
 /** rank 尺度常数:rank/divisor 把秩归到 (0,1] 量级(默认与 k 同值)。 */
 export const FUSION_RRF_DIVISOR_V1 = 60
 
+/**
+ * ★M2.5b：层次优先级序（与注入侧一致）。
+ *
+ * 出处：`tier-layer-inject.js:58 TIER_LAYER_ORDER_V1` —— **必须与之逐字相同**。
+ *
+ * 为什么不直接 import：本模块头注释承诺「**零依赖**、纯函数、零 IO」，
+ *   引入跨模块依赖会破坏该契约（且 tier-layer-inject 自身还有依赖链）。
+ * 为了既不破契约、又不产生「双源漂移」，此处**本地复刻**并由测试**断言两者相等**
+ *   （见 smoke-test-m25b-layer-arm-pre.mjs 的「常量一致性」断言）——
+ *   任何一侧改动而另一侧未同步，测试立刻红。
+ */
+export const FUSION_LAYER_ORDER_V1 = Object.freeze(['project', 'whiteboard', 'user', 'reflection', 'log'])
+
 /** 版本标识。 */
 export const RECALL_FUSION_VERSION = 'rrf_fusion_v1'
 
@@ -45,20 +58,63 @@ export function rankFusionRRFPre(pairs, opts = {}) {
   const list = Array.isArray(pairs) ? pairs.filter((p) => p && typeof p.memoryId === 'string') : []
 
   // 每臂独立排名:非空有限值按分数降序(平局 memoryId 升序)取秩(1 起);缺席者无秩。
-  const rankArm = (key) => {
+  // ★M2.5b：新增 `strMode` —— 层次臂的值是**字符串**，默认的「只收有限数」过滤会把它全部滤掉
+  //   （实测踩坑：layer 臂曾因此静默恒为 0，套件 [3] 抓到）。strMode=true 时接受非空字符串。
+  const rankArm = (key, cmp, strMode) => {
     const entries = []
     for (const p of list) {
       const v = p[key]
-      if (typeof v === 'number' && Number.isFinite(v)) entries.push({ memoryId: p.memoryId, v })
+      if (strMode) {
+        if (typeof v === 'string' && v) entries.push({ memoryId: p.memoryId, v })
+      } else if (typeof v === 'number' && Number.isFinite(v)) {
+        entries.push({ memoryId: p.memoryId, v })
+      }
     }
-    entries.sort((a, b) => (b.v !== a.v ? b.v - a.v : (a.memoryId < b.memoryId ? -1 : a.memoryId > b.memoryId ? 1 : 0)))
+    const tie = (a, b) => (a.memoryId < b.memoryId ? -1 : a.memoryId > b.memoryId ? 1 : 0)
+    entries.sort(cmp || ((a, b) => (b.v !== a.v ? b.v - a.v : tie(a, b))))
     const ranks = new Map()
     entries.forEach((e, i) => ranks.set(e.memoryId, i + 1))
     return ranks
   }
+
+  /**
+   * ★M2.5b：层次臂的**序** = 注入侧的层次优先级序（二者必须一致）。
+   * 出处：`tier-layer-inject.js:58 TIER_LAYER_ORDER_V1`
+   *       = ['project','whiteboard','user','reflection','log']。
+   * 语义：**rank 1 = 最高优先级层**。未列出的层（含新增层）排在已知层之后，按名称升序（确定性）。
+   * 注意：这里只定义**偏好顺序**，不定义权重；权重问题走 rank-space（见下），
+   *       需要调权重时应改分档/序，而不是给分数乘系数（Hindsight #3956）。
+   */
+  const layerRankOf = (name) => {
+    const i = FUSION_LAYER_ORDER_V1.indexOf(name)
+    return i >= 0 ? i : FUSION_LAYER_ORDER_V1.length
+  }
+  const cmpLayer = (a, b) => {
+    const la = layerRankOf(String(a.v))
+    const lb = layerRankOf(String(b.v))
+    if (la !== lb) return la - lb
+    const sa = String(a.v), sb = String(b.v)
+    if (sa !== sb) return sa < sb ? -1 : 1
+    return a.memoryId < b.memoryId ? -1 : a.memoryId > b.memoryId ? 1 : 0
+  }
+
   const denseRanks = rankArm('dense')
   const lexRanks = rankArm('lex')
 
+  // ★M2.5b 层次臂（2026-09-18）：可选第四臂。layer 为层次名（'project'/'user'/'log'/
+  // 'reflection'/'whiteboard'）或缺失。与时间臂同一条**退化安全**纪律：
+  //   所有 pair 均缺 layer **或 layer 全相等** → 不构建 layer 秩，行为与三臂版**逐字节一致**
+  //   （fused 不加 0 项、输出对象不含新字段）。
+  // 为什么需要它（实测不一致，2026-09-18）：Tier-0 **注入**侧有层次优先级
+  //   （tier-layer-inject.js:58 TIER_LAYER_ORDER_V1 = ['project','whiteboard','user','reflection','log']
+  //    + tier0-catalog.js:419-455 的 caps/floors），而 **排序**侧对层次完全无感
+  //   ⇒ 结论层（project）与流水层（log）在融合里**平等竞争**，笔记层常被日志挤掉。
+  // rank-space（Hindsight #3956 禁止 score-space 加权）：层次只贡献**秩**，不乘分。
+  const layers = []
+  for (const p of list) { if (typeof p.layer === 'string' && p.layer) layers.push(p.layer) }
+  const hasLayer = layers.length > 0 && layers.some((v) => v !== layers[0])
+  const layerRanks = hasLayer ? rankArm('layer', cmpLayer, true) : null
+
   // 时间臂(P12 后新增,2026-09-09):可选第三臂。temp 为 1(命中时间范围)/0(未命中)/
   // 缺失(无时间臂或非日期来源)。所有 pair 均缺 temp **或 temp 全相等**(全 0/全 1)→
   // 不构建 temp 秩,行为与两臂版逐字节一致(fused 不加 0 项、输出对象不含新字段)——
@@ -84,16 +140,31 @@ export function rankFusionRRFPre(pairs, opts = {}) {
         rankDense: rd === undefined ? null : rd,
         rankLex: rl === undefined ? null : rl,
       }
-      if (!hasTemp) return base
-      const rt = tempRanks.get(p.memoryId)
-      const rrfTemp = rt === undefined ? 0 : 1 / (k + rt / divisor)
-      return {
-        ...base,
-        fused: rrfDense + rrfLex + rrfTemp,
-        rrfTemp,
-        tempRaw: typeof p.temp === 'number' && Number.isFinite(p.temp) ? p.temp : null,
-        rankTemp: rt === undefined ? null : rt,
+      // 时间臂与层次臂**互不依赖**：各自独立判 has*，可单独生效、可同时生效。
+      let out = base
+      if (hasTemp) {
+        const rt = tempRanks.get(p.memoryId)
+        const rrfTemp = rt === undefined ? 0 : 1 / (k + rt / divisor)
+        out = {
+          ...out,
+          fused: out.fused + rrfTemp,
+          rrfTemp,
+          tempRaw: typeof p.temp === 'number' && Number.isFinite(p.temp) ? p.temp : null,
+          rankTemp: rt === undefined ? null : rt,
+        }
+      }
+      if (hasLayer) {
+        const rlay = layerRanks.get(p.memoryId)
+        const rrfLayer = rlay === undefined ? 0 : 1 / (k + rlay / divisor)
+        out = {
+          ...out,
+          fused: out.fused + rrfLayer,
+          rrfLayer,
+          layerRaw: typeof p.layer === 'string' && p.layer ? p.layer : null,
+          rankLayer: rlay === undefined ? null : rlay,
+        }
       }
+      return out
     })
     .sort((x, y) => (y.fused !== x.fused ? y.fused - x.fused : (x.memoryId < y.memoryId ? -1 : x.memoryId > y.memoryId ? 1 : 0)))
 }

package/lib/rerank-host.js

@@ -0,0 +1,160 @@
+/**
+ * rerank-host-pre —— P4 精排多级档位 + 有界异步窗口(2026-09-16, rerank_host_v1)。
+ *
+ * 权威依据: MASTER-PLAN-3.0.md §Phase 4 (H2 按实测重写) + TODO-GRAPH V2-P4 卡。
+ * 实测推翻方案假设(留痕): bge-reranker-v2-m3 P95 37.4 秒(50 对/题, RSS 3.84GB);
+ *   qwen3-reranker-0.6b P95 8.8 秒(小样本探针 10 对/题, RSS 4.95GB, 不可与 bge 直接比);
+ *   收益真实: recall@1 0.739 → 0.898(bge); cross-encoder 模型已下载; 真实缺口 = GPU 版 torch
+ *   (torch 2.13.0+cpu)与快档量化产物。⇒ 精排不得同步等待, 只能走**有界异步窗口**。
+ *
+ * 设计(卡内 v2 修正, 逐条对应):
+ *  - 多级档位(用户裁定): 'off' | 'fast'(int8+CPU, 未就绪=不可用) | 'enthusiast'(完整模型+GPU)。
+ *    档位只决定"是否允许排精排任务", 一期本地无 GPU torch / 无量化产物 ⇒ fast/enthusiast 均
+ *    fail closed 降级为粗排(绝不阻塞前台、绝不发出模型请求)。
+ *  - 一分钟 = 有界后台窗口: 从**入队时**起算含排队与计算, **到期不续命**; 本轮立即用现有排序;
+ *    后台完成只进有界结果缓存, 不改本轮 envelope、不再次 emit; 下一请求重新生成 requestKey,
+ *    仅 inputKey 完全匹配才复用, 且重跑当轮检查; 没有下一轮就过期, 不主动制造模型请求。
+ *  - 运行隔离: 精排必须走独立懒加载 worker 角色(注入 opts.rerankFn), 不得占用稠密/索引 worker;
+ *    全机最多一个精排任务在跑(busy 门), 忙时继续粗排。
+ *  - 资源门 T5-5R: 任务超清理宽限未被取消/完成 ⇒ 调 opts.killFn 终止并释放; 期间稠密查询照常。
+ *  - T5-6R: 本模块不产出任何"异步注入收益"口径 — 结果只进缓存; 零复用就是零复用。
+ *
+ * 纯主机侧状态机, 模型调用经 opts.rerankFn 注入(测试可控), 零 fs/零网络。
+ */
+
+export const RERANK_HOST_VERSION = 'rerank_host_v1'
+
+/** 有界异步窗口: 从入队起算(毫秒), 含排队与计算; 到期不续命。 */
+export const RERANK_WINDOW_MS_V1 = 60000
+/** 登记的清理宽限: 超窗后仍允许 killFn 在此宽限内终止进程。 */
+export const RERANK_KILL_GRACE_MS_V1 = 5000
+/** 缓存上限(条): 有界结果缓存, LRU 逐出。 */
+export const RERANK_CACHE_MAX_V1 = 16
+
+/** 档位解析: 'off'/'fast'/'enthusiast' 之外一律按 off(fail closed)。 */
+export function resolveRerankTierPre(raw) {
+  const s = String(raw || '').toLowerCase()
+  if (s === 'fast' || s === 'enthusiast') return { tier: s, active: false, reason: 'tier-not-provisioned' }
+  if (s === 'off') return { tier: 'off', active: false, reason: 'tier-off' }
+  return { tier: 'off', active: false, reason: 'invalid-tier' }
+}
+
+/**
+ * inputKey: 精排复用的完全匹配键 — 查询 + 排序输入 + miv 的规范化哈希。
+ * 任一身份字段变化 ⇒ 键不同 ⇒ 不复用(T5-3R)。
+ */
+export function computeRerankInputKeyPre({ query, orderedIds, memoryIndexVersion }) {
+  return sha256Hex(JSON.stringify([String(query || ''), JSON.stringify(Array.isArray(orderedIds) ? orderedIds.map(String) : []), String(memoryIndexVersion || '')]))
+}
+
+function sha256Hex(s) {
+  // 纯 JS sha256 避免引入 node:crypto 依赖面 — 复用 djb2 式双哈希足够做键(非安全用途),
+  // 但为确定性可审计, 用 FNV-1a 64 位两次盐化。
+  let h1 = 0x811c9dc5, h2 = 0x811c9dc5
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i)
+    h1 = ((h1 ^ c) * 0x01000193) >>> 0
+    h2 = ((h2 ^ (c + i)) * 0x01000193) >>> 0
+  }
+  return h1.toString(16).padStart(8, '0') + h2.toString(16).padStart(8, '0')
+}
+
+/**
+ * 创建精排主机(每引擎一份)。
+ * opts: {
+ *   tier: 'off'|'fast'|'enthusiast',
+ *   now?: () => ms(测试可注入),
+ *   rerankFn?: async ({query, ordered}) => number[]  // 独立 worker 角色; 懒加载由调用方注入
+ *   killFn?: () => void                               // T5-5R: 终止精排进程并释放
+ * }
+ */
+export function createRerankHostPre(opts = {}) {
+  const now = typeof opts.now === 'function' ? opts.now : () => Date.now()
+  const resolved = resolveRerankTierPre(opts.tier)
+  const stats = { enqueued: 0, reused: 0, expiredDrops: 0, killed: 0, completed: 0, busyRejects: 0, tierRejects: 0 }
+  /** Map<inputKey, {at, scores}> — 有界结果缓存(只缓存, 不推送)。 */
+  const cache = new Map()
+  let running = null // {inputKey, startedAt, done}
+
+  function pruneExpired() {
+    const t = now()
+    for (const [k, v] of cache) {
+      if (t - v.at > RERANK_WINDOW_MS_V1) { cache.delete(k); stats.expiredDrops++ }
+    }
+  }
+
+  /**
+   * 请求一次精排机会(每轮 recall 调用一次)。
+   * 返回 {mode, scores?, reason?}:
+   *   mode='reuse'  — 缓存命中(窗口内 + inputKey 完全匹配); 调用方把 scores 并进本轮展示。
+   *   mode='skip'   — 档位关/未就绪/无 worker/忙/无下一轮价值 ⇒ 本轮粗排, 不发模型请求。
+   *   mode='accepted' — 已入队(有界异步窗口起算); 本轮立即返回(粗排序不变)。
+   * **本轮同步路径绝不等待精排**(T5-3R: 前台先返回, 后台完成只进缓存)。
+   */
+  function offerRerankPre({ query, orderedIds, memoryIndexVersion, requestKey }) {
+    pruneExpired()
+    const tier = resolveRerankTierPre(opts.tier)
+    if (tier.tier === 'off') { stats.tierRejects++; return { mode: 'skip', reason: 'tier-off' } }
+    // fast/enthusiast 的可用性由"是否注入了独立 worker"决定(运行隔离: rerankFn 即懒加载 worker 角色)。
+    // 环境未供给(GPU torch 缺/量化产物缺) ⇒ 调用方不注入 rerankFn ⇒ 这里 fail closed 走粗排。
+    if (typeof opts.rerankFn !== 'function') { stats.tierRejects++; return { mode: 'skip', reason: 'no-worker' } }
+    const inputKey = computeRerankInputKeyPre({ query, orderedIds, memoryIndexVersion })
+    const hit = cache.get(inputKey)
+    if (hit && now() - hit.at <= RERANK_WINDOW_MS_V1) {
+      // T5-4R: 复用前调用方必须重跑当轮状态/fv2/冷却/预算检查 — 本模块只担保 inputKey 完全匹配。
+      stats.reused++
+      return { mode: 'reuse', scores: hit.scores, inputKey }
+    }
+    if (running) { stats.busyRejects++; return { mode: 'skip', reason: 'busy', inputKey } }
+    // 入队: 一期全机最多一个精排任务; 有界窗口从入队起算, 到期不续命。
+    stats.enqueued++
+    const startedAt = now()
+    const job = { inputKey, startedAt, requestKey: String(requestKey || '') }
+    running = job
+    Promise.resolve()
+      .then(() => opts.rerankFn({ query, ordered: Array.isArray(orderedIds) ? orderedIds.map(String) : [] }))
+      .then((scores) => {
+        // 到期不续命: 完成时已超窗 ⇒ 丢弃(没有下一轮就过期, 不制造请求)。
+        if (now() - startedAt > RERANK_WINDOW_MS_V1) { stats.expiredDrops++; return }
+        // 缓存条目记入队时刻(卡内口径: 窗口从入队起算, 不是完成时刻 — 否则慢计算等于续命)。
+        cache.set(inputKey, { at: startedAt, scores: Array.isArray(scores) ? scores : [] })
+        if (cache.size > RERANK_CACHE_MAX_V1) {
+          const oldest = [...cache.entries()].sort((a, b) => a[1].at - b[1].at)[0]
+          if (oldest) cache.delete(oldest[0])
+        }
+        stats.completed++
+      })
+      .catch(() => { /* fail soft: 精排失败不影响粗排 */ })
+      .finally(() => { if (running === job) running = null })
+    return { mode: 'accepted', inputKey }
+  }
+
+  /**
+   * T5-5R: 精排忽略取消/卡死 ⇒ 调用方在登记的清理宽限内调用; 终止进程并释放占用。
+   * 返回 {killed:boolean}。稠密查询与本主机其余路径不受影响。
+   */
+  function killRunningRerankPre() {
+    if (!running) return { killed: false }
+    running = null
+    stats.killed++
+    try { if (typeof opts.killFn === 'function') opts.killFn() } catch (_) {}
+    return { killed: true }
+  }
+
+  /** 是否存在超窗未完成的运行任务(调用方据此在宽限内 kill)。 */
+  function isRunningBeyondWindowPre() {
+    return !!(running && now() - running.startedAt > RERANK_WINDOW_MS_V1 + RERANK_KILL_GRACE_MS_V1)
+  }
+
+  function debugView() {
+    pruneExpired()
+    return {
+      version: RERANK_HOST_VERSION, tier: resolved.tier, active: resolved.active,
+      running: running ? { inputKey: running.inputKey, elapsedMs: now() - running.startedAt, beyondWindow: isRunningBeyondWindowPre() } : null,
+      cacheSize: cache.size, stats,
+      windowMs: RERANK_WINDOW_MS_V1, killGraceMs: RERANK_KILL_GRACE_MS_V1,
+    }
+  }
+
+  return { offerRerankPre, killRunningRerankPre, isRunningBeyondWindowPre, debugView }
+}

package/lib/rules-edit.js

@@ -0,0 +1,159 @@
+/**
+ * rules-edit.js —— 「用户级硬性约束」的**条目级**解析与增删改（R7 需求）。
+ *
+ * ## 背景（用户 2026-09-20 明确要求「这个功能必须要落在前端」）
+ *
+ * `[规则 — 用户级硬性约束 · 必须遵守]` 这一段是**每轮无条件注入**的硬约束，
+ * 真源 = `~/.dsh/memory/MEMORY.md`（见 `rules-layer.js:12` 的真源纪律）。
+ * 它**不走语义层** —— 即没有检索/打分/淘汰环节 ⇒ **过时条目不会被自动清理**；
+ * 而 AI（`memory_user`）也会往里写错东西。
+ * ⇒ 用户必须能**自己增/删/改**，否则错一条就每轮都被误导。
+ *
+ * ## 与既有渲染层的关系（重要：本模块不改变注入语义）
+ *
+ * `rules-layer.js` 的 `extractRulesLayerPre()` 负责**读**（把 MEMORY.md 解析成规则段），
+ * `renderRulesSectionPre()` 负责**渲染**。本模块只做**编辑定位**：
+ * 给定原文，找出「哪一段是规则段、每条规则在第几行」，以及产出改后的新全文。
+ * 它**不碰**注入、不碰检索、不碰 store。
+ *
+ * ## 条目模型
+ *
+ * 用户级 MEMORY.md 由若干 `## YYYY-MM-DD` 日期段 + `- ` 条目行组成。
+ * `rules-layer.js` 的渲染器只取 `- ` 开头的行（且跳过日期段）。
+ * ⇒ **一条规则 = 一个 `- ` 行**。本模块据此提供：
+ *   - `listRuleItemsPre(text)`      → [{ line, indent, text, source }]
+ *   - `updateRuleItemPre(text, i, next)` / `removeRuleItemPre(text, i)` / `appendRuleItemPre(text, body)`
+ *
+ * `source` 的判定：条目若落在 `## YYYY-MM-DD` 段内 ⇒ 归该日期（多为 AI 写入）；
+ * 落在段外（文件头部）⇒ 记为 `user`（多为用户手写）。这是 R7-3「标注来源」的依据。
+ *
+ * ## 纪律
+ *   - 纯函数：输入文本、输出文本，**不做任何 IO**（IO 由调用方走既有 writeFull 事务）。
+ *   - **删除 = 真删**（见 R7-4）：本层渲染器不认任何状态标记，软删标记会被当正文注入模型。
+ *   - 零运行时依赖。CRLF、无 BOM。
+ */
+
+/** 日期段标题（与 rules-layer.js 的 DATE_SECTION_RE 同口径）。 */
+export const RULE_DATE_SECTION_RE_V1 = /^##\s*\d{4}-\d{2}-\d{2}\s*$/
+
+/** 条目行：允许前导缩进 + `- `（渲染器同样只看 `- ` 行）。 */
+export const RULE_ITEM_RE_V1 = /^(\s*)-\s+(.*)$/
+
+/** 单条规则长度上限（与写闸门同量级，防止一次塞进整篇文档）。 */
+export const RULE_ITEM_MAX_CHARS_V1 = 2000
+
+/**
+ * 列出所有规则条目（**行号从 0 开始**，供后续增删改定位）。
+ *
+ * @param {string} text  MEMORY.md 全文
+ * @returns {Array<{line:number, indent:string, text:string, source:string, dateSection:string|null}>}
+ */
+export function listRuleItemsPre(text) {
+  const lines = String(text == null ? '' : text).split(/\r?\n/)
+  const out = []
+  let curDate = null
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i]
+    if (RULE_DATE_SECTION_RE_V1.test(l)) { curDate = l.replace(/^##\s*/, '').trim(); continue }
+    const m = RULE_ITEM_RE_V1.exec(l)
+    if (!m) continue
+    const body = m[2].trim()
+    if (!body) continue
+    out.push({
+      line: i,
+      indent: m[1] || '',
+      text: body,
+      // 落在日期段内 ⇒ 多为 AI（memory_user 会带日期标题）写入；否则视为用户手写
+      source: curDate ? 'ai' : 'user',
+      dateSection: curDate,
+    })
+  }
+  return out
+}
+
+/** 内部：切行（保留原始行尾风格判定所需的信息交给 join 处理）。 */
+function splitLinesPre(text) { return String(text == null ? '' : text).split(/\r?\n/) }
+
+function joinLinesPre(lines) { return lines.join('\n') }
+
+/**
+ * **替换**第 idx 条规则（按 listRuleItemsPre 的顺序）。
+ *
+ * @returns {{ok:boolean, text?:string, error?:string}}
+ */
+export function updateRuleItemPre(text, idx, nextBody) {
+  const items = listRuleItemsPre(text)
+  const body = String(nextBody == null ? '' : nextBody).trim()
+  if (!Number.isInteger(idx) || idx < 0 || idx >= items.length) return { ok: false, error: 'index-out-of-range' }
+  if (!body) return { ok: false, error: 'empty-body' }
+  if (body.length > RULE_ITEM_MAX_CHARS_V1) return { ok: false, error: 'too-long' }
+  if (/\r|\n/.test(body)) return { ok: false, error: 'multiline-not-allowed' }
+  const lines = splitLinesPre(text)
+  const it = items[idx]
+  lines[it.line] = it.indent + '- ' + body
+  return { ok: true, text: joinLinesPre(lines) }
+}
+
+/**
+ * **删除**第 idx 条规则（真删，见 R7-4）。
+ *
+ * ⚠️ 本层渲染器（`renderRulesSectionPre`）不认任何状态标记 ⇒ 软删标记会被当正文注入模型；
+ *    故这里**直接移除该行**。不可撤销 —— 调用方必须做二次确认。
+ */
+export function removeRuleItemPre(text, idx) {
+  const items = listRuleItemsPre(text)
+  if (!Number.isInteger(idx) || idx < 0 || idx >= items.length) return { ok: false, error: 'index-out-of-range' }
+  const lines = splitLinesPre(text)
+  lines.splice(items[idx].line, 1)
+  return { ok: true, text: joinLinesPre(lines) }
+}
+
+/**
+ * **追加**一条规则。
+ *
+ * 落点规则（与用户手写习惯一致，且保证渲染器一定能读到）：
+ *   - `dateSection` 为空 ⇒ 追加到**文件头部**（用户手写区，`source` 会是 `user`）；
+ *   - 给了 `dateSection` ⇒ 追加到该日期段的**末尾**（AI 写入区）。
+ */
+export function appendRuleItemPre(text, body, opts = {}) {
+  const b = String(body == null ? '' : body).trim()
+  if (!b) return { ok: false, error: 'empty-body' }
+  if (b.length > RULE_ITEM_MAX_CHARS_V1) return { ok: false, error: 'too-long' }
+  if (/\r|\n/.test(b)) return { ok: false, error: 'multiline-not-allowed' }
+  const lines = splitLinesPre(text)
+  const want = opts && opts.dateSection ? String(opts.dateSection).trim() : ''
+  const newLine = '- ' + b
+  if (!want) {
+    // 头部插入：跳过开头的空行，避免把条目顶到文件最上面的空行之前
+    let at = 0
+    while (at < lines.length && lines[at].trim() === '') at++
+    lines.splice(at, 0, newLine)
+    return { ok: true, text: joinLinesPre(lines) }
+  }
+  // 找目标日期段，插到该段内最后一个非空行之后
+  let secAt = -1
+  for (let i = 0; i < lines.length; i++) {
+    if (RULE_DATE_SECTION_RE_V1.test(lines[i]) && lines[i].replace(/^##\s*/, '').trim() === want) { secAt = i; break }
+  }
+  if (secAt < 0) return { ok: false, error: 'date-section-not-found' }
+  let end = secAt + 1
+  while (end < lines.length && !RULE_DATE_SECTION_RE_V1.test(lines[end])) end++
+  let ins = end
+  while (ins > secAt + 1 && lines[ins - 1].trim() === '') ins--
+  lines.splice(ins, 0, newLine)
+  return { ok: true, text: joinLinesPre(lines) }
+}
+
+/**
+ * **预览**：把规则条目渲染成注入时会长的样子（R7-6）。
+ *
+ * 只做**只读**格式化，不引入 rules-layer.js 的其它依赖（避免循环 import 风险）。
+ */
+export function previewRulesPre(text) {
+  const items = listRuleItemsPre(text)
+  return items.map((x) => '- ' + x.text).join('\n')
+}
+
+/** 空规则段判定（给 UI 显示空态用）。 */
+export function isEmptyRulesPre(text) { return listRuleItemsPre(text).length === 0 }
+