@yolk_vat-y/dsh-project-memory 0.5.5 → 0.5.7

package/src/chunker.js

@@ -20,17 +20,25 @@ export function chunkText(text, chunkChars = 3000, maxChunks = 40) {
 
   const chunks = []
   for (const section of sections) {
-    if (!section.lines.join('').trim()) continue
-    let block = section.lines.join('\n').trim()
-    let line = section.line
+    const rawBlock = section.lines.join('\n')
+    if (!rawBlock.trim()) continue
+    // `.trim()` 会吃掉段首的空白与换行——把它们算进行号，否则整段的引用行号会偏低。
+    const lead = rawBlock.match(/^\s*/)[0]
+    let line = section.line + (lead.match(/\n/g) || []).length
+    let block = rawBlock.trim()
     while (block.length > chunkChars) {
       let splitAt = block.lastIndexOf('\n\n', chunkChars)
       if (splitAt < chunkChars * 0.5) splitAt = block.lastIndexOf(' ', chunkChars)
       if (splitAt < chunkChars * 0.5) splitAt = chunkChars
-      const part = block.slice(0, splitAt).trim()
+      const rawPart = block.slice(0, splitAt)
+      const part = rawPart.trim()
       if (part) chunks.push({ title: section.title, text: part, line })
-      line += part.split('\n').length
-      block = block.slice(splitAt).trim()
+      // 行号按**原始**切片里的换行数推进，再加上被下一次 trim 吃掉的段首换行。
+      // 旧写法 `part.split('\n').length` 每次跨行切分都要多算一行，误差会累积。
+      const rest = block.slice(splitAt)
+      const nextLead = rest.match(/^\s*/)[0]
+      line += (rawPart.match(/\n/g) || []).length + (nextLead.match(/\n/g) || []).length
+      block = rest.trim()
       if (chunks.length >= maxChunks) break
     }
     if (block) {

package/src/commands/insight-actions.js

@@ -6,6 +6,7 @@ import { ProjectMemoryStore } from '../store.js'
 import { memoryRootFor } from '../util/fs.js'
 import { cfgInsight, GlobalStore, normalizeInsight, defaultGlobalFile, saveInsight, INSIGHT_KINDS } from '../insight-store.js'
 import { projectRootFor } from '../setup/taskbridge.js'
+import { fencedJson, invocationContext } from './invocation.js'
 
 function insSummary(ins, extra = {}) {
   const s = ins || {}
@@ -225,7 +226,9 @@ const KIND_CONTENT = {
   procedure: ['steps', 'trigger'],
   experience: ['problem', 'solution'],
 }
-const ALL_CONTENT = ['body', 'pattern', 'fix', 'problem', 'solution', 'choice', 'reason', 'steps', 'trigger']
+// 切 kind 时要清掉的内容字段。**不含 trigger**：任何 kind 都可以带 authored trigger，
+// 放进这里会在 lesson↔decision 之间切换时把自动注入能力一并删掉。
+const ALL_CONTENT = ['body', 'pattern', 'fix', 'problem', 'solution', 'choice', 'reason', 'steps']
 
 /** 编辑既有条目（title/kind/正文/trigger 等白名单字段）。任务级按 id 在任务池定位。 */
 export function editMemoryItem({ store, gs, scope, id, fields }) {
@@ -244,10 +247,18 @@ export function editMemoryItem({ store, gs, scope, id, fields }) {
       }
       if (key === 'trigger') {
         if (!v || typeof v !== 'object') continue
-        item.trigger = {
-          keywords: Array.isArray(v.keywords) ? v.keywords.map(String) : [],
-          ...(Array.isArray(v.scope) ? { scope: v.scope.map(String) } : {}),
-        }
+        // 合并而非重建：只改传进来的成员，when/guard/prevents 等 authored 触发面必须原样保留，
+        // 否则一次 /insight edit 就会把自动注入的 trigger 降级成 legacy keywords。
+        const next = { ...(item.trigger || {}) }
+        if (Array.isArray(v.keywords)) next.keywords = v.keywords.map(String)
+        if (Array.isArray(v.scope)) next.scope = v.scope.map(String)
+        if (Array.isArray(v.actions)) next.actions = v.actions.map(String)
+        if (Array.isArray(v.paths)) next.paths = v.paths.map(String)
+        if (Array.isArray(v.symbols)) next.symbols = v.symbols.map(String)
+        if (v.when && typeof v.when === 'object') next.when = v.when
+        if (v.guard && typeof v.guard === 'object') next.guard = v.guard
+        if (typeof v.prevents === 'string') next.prevents = v.prevents
+        item.trigger = next
         changed = true
         continue
       }
@@ -300,10 +311,6 @@ export function editMemoryItem({ store, gs, scope, id, fields }) {
   return { ok: true, text: '已更新记忆条目' }
 }
 
-function jsonText(payload, note) {
-  return `${note}\n\n\`\`\`json\n${JSON.stringify(payload)}\n\`\`\``
-}
-
 /** /insight <verb> <args…>：list [task|project|global] | confirm/promote/demote/archive/restore/delete <id> [taskId] */
 export function insightCommandDefinition(config, ctx) {
   return {
@@ -312,10 +319,7 @@ export function insightCommandDefinition(config, ctx) {
     input: { hint: 'list [scope] | <动作> <scope> <id> [taskId]' },
     handler: (invocation) => {
       try {
-        const agent = invocation?.agent
-        const sid = agent?.id || agent?.session?.id
-        const session = sid && agent?.ctx ? agent.ctx.sessions?.get(sid) : (agent?.session || null)
-        const cwd = session?.header?.cwd || agent?.session?.header?.cwd
+        const { cwd } = invocationContext(invocation)
         const lineRaw = (invocation?.rawInput || '').trim()
         const raw = lineRaw.split(/\s+/).filter(Boolean)
         const root = projectRootFor(cwd)
@@ -326,7 +330,7 @@ export function insightCommandDefinition(config, ctx) {
           const store = new ProjectMemoryStore(memoryRootFor(root, config.memoryDir)).load()
           const gs = new GlobalStore(cfgInsight(config).globalFile || defaultGlobalFile()).load()
           const payload = listInsights(store, gs, scope)
-          return { kind: 'success', text: jsonText(payload, `记忆 ${scope}：${payload.count} 条`) }
+          return { kind: 'success', text: fencedJson(`记忆 ${scope}：${payload.count} 条`, JSON.stringify(payload)) }
         }
         if (verb === 'save') {
           // /insight save <scope> <json>（新建/合并；project|global）

package/src/commands/invocation.js

@@ -0,0 +1,36 @@
+/**
+ * 命令处理器的公共接线：/tasks、/task、/insight 三个定义此前各自复制了
+ * 「解析 CommandInvocation → 会话与 cwd」和「拼 JSON 围栏载荷」两段代码。
+ * 集中在这里，语义只在一处维护。
+ */
+
+/**
+ * 从命令调用里解出会话上下文。
+ *
+ * `sid` 优先取 `agent.id`；`session` 优先走 `sessions` 服务（拿到的是宿主实时会话，
+ * 带 append 等能力），服务缺失或不可用时退回 `agent.session`。
+ * @param {object} invocation - 宿主 CommandInvocation（handler 的入参）。
+ * @returns {{agent: object|undefined, sid: string|undefined, session: object|null, cwd: string|undefined}}
+ */
+export function invocationContext(invocation) {
+  const agent = invocation?.agent
+  const sid = agent?.id || agent?.session?.id
+  const fromService = sid && agent?.ctx ? agent.ctx.sessions?.get(sid) : null
+  // sessions 服务缺失**或查不到**时都退回 agent.session（文档承诺的降级路径）。
+  // 旧写法只在 agent.ctx 不存在时退回：服务在、但 get 返回 undefined 时 session 直接是 undefined，
+  // /task switch|todos|unbind 于是静默跳过 session.append（宿主 todo 同步失效）。
+  const session = fromService || agent?.session || null
+  const cwd = session?.header?.cwd || agent?.session?.header?.cwd
+  return { agent, sid, session, cwd }
+}
+
+/**
+ * 统一的命令输出载荷：人类可读摘要 + ```json 块。
+ * 客户端命令节点按尾部 JSON 解析并渲染面板，因此三个命令共用同一格式。
+ * @param {string} note - 人类可读摘要（可多行）。
+ * @param {string} payload - 已序列化的 JSON 载荷。
+ * @returns {string}
+ */
+export function fencedJson(note, payload) {
+  return `${note}\n\n\`\`\`json\n${payload}\n\`\`\``
+}

package/src/commands/task-actions.js

@@ -8,8 +8,7 @@ import { projectRootFor, adoptStepsToSession, shouldAdoptToHost } from '../setup
 import { renderTaskSnapshot, buildTaskPayload } from './tasks.js'
 import { fireReflect } from '../reflection-pipeline.js'
 import { resolveRoute } from '../llm-route.js'
-
-const VERBS = { switch: 'switch', archive: 'archive' }
+import { fencedJson, invocationContext } from './invocation.js'
 
 function describeTask(t) {
   const done = (t.steps || []).filter((s) => s.status === 'completed').length
@@ -17,6 +16,23 @@ function describeTask(t) {
   return `「${t.title}」（步骤 ${done}/${total}）`
 }
 
+/**
+ * raw 去掉前 n 个空白分隔 token 后的**原始剩余文本**（保留内部空白与引号）。
+ * 旧写法 `raw.split(/\s+/).slice(n).join(' ')` 会把标题/JSON 里的连续空格压成一个，
+ * `/task rename <id> "a  b"` 于是改名成 "a b"。
+ */
+function restAfter(raw, n) {
+  let i = 0
+  let seen = 0
+  while (i < raw.length && seen < n) {
+    while (i < raw.length && /\s/.test(raw[i])) i++
+    if (i >= raw.length) break
+    while (i < raw.length && !/\s/.test(raw[i])) i++
+    seen++
+  }
+  return raw.slice(i).replace(/^\s+/, '')
+}
+
 function withTaskSnapshot(config, cwd, sid, store, note) {
   const tasks = store.getTasks()
   const active = tasks.filter((t) => !t.archived)
@@ -24,7 +40,7 @@ function withTaskSnapshot(config, cwd, sid, store, note) {
   const boundId = sid ? store.getBoundTaskId(sid) : null
   const human = `项目 ${projectRootFor(cwd)}\n${note}\n任务: ${active.length} 套${archived ? `（归档 ${archived}）` : ''}`
   const payload = buildTaskPayload(active, boundId, archived)
-  return { kind: 'success', text: `${human}\n\n\`\`\`json\n${payload}\n\`\`\`` }
+  return { kind: 'success', text: fencedJson(human, payload) }
 }
 
 export function taskCommandDefinition(config, ctx) {
@@ -34,10 +50,7 @@ export function taskCommandDefinition(config, ctx) {
     input: { hint: 'switch|archive <任务id> | unbind' },
     handler: (invocation) => {
       try {
-        const agent = invocation?.agent
-        const sid = agent?.id || agent?.session?.id
-        const session = sid && agent?.ctx ? agent.ctx.sessions?.get(sid) : (agent?.session || null)
-        const cwd = session?.header?.cwd || agent?.session?.header?.cwd
+        const { session, sid, cwd } = invocationContext(invocation)
         const raw = (invocation?.rawInput || '').trim()
         const [verb, taskId, ...rest] = raw.split(/\s+/)
 
@@ -70,7 +83,7 @@ export function taskCommandDefinition(config, ctx) {
         // /task rename <任务id> <json标题> —— 双击任务标题改名
         if (verb === 'rename') {
           if (!taskId) return { kind: 'error', text: '[task] rename 需要任务 id（由卡片双击调用）' }
-          const payload = raw.split(/\s+/).slice(2).join(' ').trim()
+          const payload = restAfter(raw, 2).trim()
           let title = payload
           try {
             const parsed = JSON.parse(payload)
@@ -92,7 +105,7 @@ export function taskCommandDefinition(config, ctx) {
         // /task todos <json> —— 卡片双击编辑步骤后，把整份新清单写回绑定任务并推宿主
         // （与模型 todo_write 同一套数据，只是发起方是用户面板）
         if (verb === 'todos') {
-          const rawJson = raw.split(/\s+/).slice(1).join(' ').trim()
+          const rawJson = restAfter(raw, 1).trim()
           let todos
           try {
             todos = JSON.parse(rawJson)
@@ -126,7 +139,7 @@ export function taskCommandDefinition(config, ctx) {
           return withTaskSnapshot(config, cwd, sid, store, note)
         }
 
-        if (verb === VERBS.switch) {
+        if (verb === 'switch') {
           const task = store.getTask(taskId)
           if (!task) return { kind: 'error', text: `[task] 找不到任务: ${taskId}（/tasks 查看）` }
           const prevBound = sid ? store.getBoundTaskId(sid) : null
@@ -149,7 +162,7 @@ export function taskCommandDefinition(config, ctx) {
           return withTaskSnapshot(config, cwd, sid, store, note)
         }
 
-        if (verb === VERBS.archive) {
+        if (verb === 'archive') {
           const task = store.getTask(taskId)
           if (!task) return { kind: 'error', text: `[task] 找不到任务: ${taskId}（/tasks 查看）` }
           if (task.archived) return { kind: 'error', text: `[task] 已归档: ${task.title}` }
@@ -169,31 +182,3 @@ export function taskCommandDefinition(config, ctx) {
     },
   }
 }
-
-// 保留语义别名：/task-switch、/task-archive（仅当前端/旧入口用）
-export function taskSwitchCommandDefinition(config) {
-  const base = taskCommandDefinition(config)
-  return {
-    ...base,
-    name: 'task-switch',
-    handler: (invocation) => {
-      const id = (invocation?.rawInput || '').trim().split(/\s+/)[0]
-      return base.handler({ ...invocation, rawInput: id ? `switch ${id}` : '' })
-    },
-  }
-}
-
-export function taskArchiveCommandDefinition(config) {
-  const base = taskCommandDefinition(config)
-  return {
-    ...base,
-    name: 'task-archive',
-    handler: (invocation) => {
-      const id = (invocation?.rawInput || '').trim().split(/\s+/)[0]
-      return base.handler({ ...invocation, rawInput: id ? `archive ${id}` : '' })
-    },
-  }
-}
-
-// renderTaskSnapshot 引用保留，供外部（测试/工具）使用
-export { renderTaskSnapshot }

package/src/commands/tasks.js

@@ -4,6 +4,7 @@
 import { memoryRootFor } from '../util/fs.js'
 import { ProjectMemoryStore } from '../store.js'
 import { projectRootFor } from '../setup/taskbridge.js'
+import { fencedJson, invocationContext } from './invocation.js'
 
 function timeAgo(iso) {
   const diff = Date.now() - new Date(iso).getTime()
@@ -15,12 +16,21 @@ function timeAgo(iso) {
   return `${Math.floor(h / 24)}天前`
 }
 
+/** 步骤在历史数据里可能是字符串，也可能是 {content|text, status}：统一取文本与状态。 */
+function stepContent(s) {
+  if (typeof s === 'string') return s
+  return s?.content ?? s?.text ?? ''
+}
+function stepStatus(s) {
+  return typeof s === 'string' ? 'pending' : (s?.status || 'pending')
+}
+
 export function buildTaskPayload(tasks, boundId, archived) {
   return JSON.stringify({
     tasks: tasks.map((t) => ({
       id: t.id,
       title: t.title,
-      steps: (t.steps || []).map((s) => ({ content: s.content || s.text, status: s.status })),
+      steps: (t.steps || []).map((s) => ({ content: stepContent(s), status: stepStatus(s) })),
       files: (t.files || []).map((f) => ({ path: f, line: undefined })),
       lastActiveAt: t.lastActiveAt,
       updatedAt: t.updatedAt,
@@ -47,18 +57,16 @@ export function renderTaskSnapshot(config, cwd, sid) {
 
   if (!active.length) {
     const payload = buildTaskPayload([], boundId, archived)
-    return {
-      kind: 'success',
-      text: `项目 ${root}\n任务记录: 0 套${archived ? `（归档 ${archived}）` : ''}。让模型开始干活并维护 todo 清单后会自动建档。\n\n\`\`\`json\n${payload}\n\`\`\``,
-    }
+    const note = `项目 ${root}\n任务记录: 0 套${archived ? `（归档 ${archived}）` : ''}。让模型开始干活并维护 todo 清单后会自动建档。`
+    return { kind: 'success', text: fencedJson(note, payload) }
   }
   const lines = [`项目 ${root}`, `任务: ${active.length} 套${archived ? `（归档 ${archived}）` : ''}`, '']
   for (const t of active) {
-    const done = (t.steps || []).filter((s) => s.status === 'completed').length
+    const done = (t.steps || []).filter((s) => stepStatus(s) === 'completed').length
     const total = (t.steps || []).length
     const progress = total ? `${done}/${total}` : '无步骤'
-    const inProgress = (t.steps || []).find((s) => s.status === 'in_progress')
-    const step = inProgress ? ` · 当前: ${inProgress.content}` : ''
+    const inProgress = (t.steps || []).find((s) => stepStatus(s) === 'in_progress')
+    const step = inProgress ? ` · 当前: ${stepContent(inProgress)}` : ''
     const marker = bound && bound.id === t.id ? '（本会话绑定）' : ''
     const files = (t.files || []).slice(0, 8)
     const fileLine = files.length ? `\n  文件: ${files.join(', ')}${t.files.length > 8 ? ' …' : ''}` : ''
@@ -67,7 +75,7 @@ export function renderTaskSnapshot(config, cwd, sid) {
   lines.push('', '续接/改名/归档：直接告诉模型（list_tasks / select_task / archive_task）。')
   const humanText = lines.join('\n')
   const payload = buildTaskPayload(active, boundId, archived)
-  return { kind: 'success', text: `${humanText}\n\n\`\`\`json\n${payload}\n\`\`\`` }
+  return { kind: 'success', text: fencedJson(humanText, payload) }
 }
 
 export function tasksCommandDefinition(config, ctx) {
@@ -76,10 +84,7 @@ export function tasksCommandDefinition(config, ctx) {
     description: '查看本项目的任务清单（几套任务、进度、涉及文件、当前绑定）',
     handler: (invocation) => {
       try {
-        const agent = invocation?.agent
-        const sid = agent?.id || agent?.session?.id
-        const session = sid && agent?.ctx ? agent.ctx.sessions?.get(sid) : (agent?.session || null)
-        const cwd = session?.header?.cwd || agent?.session?.header?.cwd
+        const { cwd, sid } = invocationContext(invocation)
         return renderTaskSnapshot(config, cwd, sid)
       } catch (err) {
         return { kind: 'error', text: `[tasks] ${err?.message || err}` }

package/src/enhancer.js

@@ -19,7 +19,14 @@ function acceptTsVersion(mod) {
 }
 
 export function initTypeScript(config) {
-  if (config?.enableTypeScript === false) return null
+  if (config?.enableTypeScript === false) {
+    // 显式关闭要把已解析的模块放掉：否则 enqueueEnhance 的 `if (!ts)` 仍会放行，
+    // 配置上关了、增强器照跑。
+    ts = null
+    tsPath = null
+    tsVersion = null
+    return null
+  }
   if (ts) return ts
 
   // 1. 配置指定路径
@@ -265,7 +272,9 @@ export function deepParseWithTS(filePath, content) {
         line: getLine(node)
       })
     } else if (ts.isTypeAliasDeclaration(node)) {
-      const typeStr = node.type ? getTypeStr(checker.getTypeAtLocation(node.type)) : 'any'
+      // checker.getTypeAtLocation(node.type) 对别名返回的是**别名自身**，于是
+      // `type X = { a: string }` 变成 `X= X -- f:1`。直接用类型节点的源码文本。
+      const typeStr = node.type ? node.type.getText().replace(/\s+/g, ' ').slice(0, 200) : 'any'
       symbols.push({
         name: node.name.getText(),
         kind: 'type',

package/src/index-pipeline.js

@@ -0,0 +1,119 @@
+// 索引一个文件的**唯一**实现。
+//
+// 这段逻辑以前在 index_repo（批量）、watch（轮询）、lazy（fs/observed 懒索引）里各抄一份，
+// 三份随后各自打补丁、已经漂移：index_repo 多一道冗余的 dump 预检、体积超限时删旧记录，
+// 而 watch/lazy 保留旧记录；terms 回填与单次读盘的写法也各不相同。
+// 现在「这个文件该不该读、读出来该写什么条目」只在这里定义一次；
+// 调用方只保留自己的编排（批量计数、watch 的 mtime 快照、lazy 的根解析与副作用）。
+import { statSync } from 'node:fs'
+import { isSupportedCode, isSupportedDoc, readFileForIndex } from './util/fs.js'
+import { buildDocEntries } from './doc-pipeline.js'
+import { docEntriesNeedBackfill } from './doc-index.js'
+import { scanSymbols } from './symbols.js'
+import { linkEntries } from './link.js'
+
+/** 不索引的后缀。 */
+export const UNSUPPORTED = 'unsupported'
+/** 代码文件超过 maxFileSizeMb：读盘成本不抵符号表收益。 */
+export const OVERSIZE = 'oversize'
+/** 内容哈希未变，且无需回填词项。 */
+export const UNCHANGED = 'unchanged'
+/** 文档不可索引（dump / 抽取返回 null）→ 从 store 移除。 */
+export const DROP = 'drop'
+/** 有内容要写入 store。 */
+export const WRITE = 'write'
+
+/** 后缀 → 'code' | 'doc' | null。 */
+export function fileKind(ext) {
+  if (isSupportedCode(ext)) return 'code'
+  if (isSupportedDoc(ext)) return 'doc'
+  return null
+}
+
+function exceedsSizeCap(kind, size, config) {
+  return kind === 'code' && !!config.maxFileSizeMb && size > config.maxFileSizeMb * 1024 * 1024
+}
+
+/**
+ * 读取 + 判重 + 抽条目。抛出的异常（读盘失败、PDF 解析失败……）由调用方按各自策略处理：
+ * index_repo 收进 failures 汇总，watch 去重打印并可重试，lazy 记一行日志。
+ *
+ * @returns {{key: string, hash?: string, size?: number, type?: string, entries?: object[]}}
+ *   key 为 UNSUPPORTED / OVERSIZE / UNCHANGED / DROP / WRITE 之一。
+ * @param {object} args
+ * @param {number} [args.size] 调用方已 statSync 时传入，避免重复 stat。
+ * @param {boolean} [args.force] index_repo 的 reindex：忽略哈希跳过。
+ */
+export async function planFileIndex({ rel, filePath, kind, config, record, existingEntries = [], size, force = false }) {
+  if (!kind) return { key: UNSUPPORTED }
+  const fileSize = typeof size === 'number' ? size : statSync(filePath).size
+  if (exceedsSizeCap(kind, fileSize, config)) return { key: OVERSIZE }
+
+  // 单次读盘：同一 buffer 供内容哈希与正文解码使用（未变更的文件不解码）。
+  const { hash, buffer } = readFileForIndex(filePath)
+  // 旧 store 的 doc 条目缺 terms → 即使哈希未变也重抽一次（一次性回填）。
+  const backfill = kind === 'doc' && docEntriesNeedBackfill(existingEntries)
+  if (!force && record && record.sha256 === hash && !backfill) return { key: UNCHANGED }
+
+  if (kind === 'code') {
+    return { key: WRITE, hash, size: fileSize, type: 'code', entries: scanSymbols(rel, filePath, buffer.toString('utf8')) }
+  }
+  // dump 判定在 buildDocEntries 内部（唯一真源）：不可索引的文档返回 null。
+  const entries = await buildDocEntries(rel, filePath, {
+    chunkChars: config.chunkChars,
+    maxChunks: config.maxChunksPerFile,
+    maxFileSizeMb: config.maxFileSizeMb,
+    maxPdfPages: config.maxPdfPages,
+  })
+  return entries === null ? { key: DROP } : { key: WRITE, hash, size: fileSize, type: 'doc', entries }
+}
+
+/**
+ * plan → 落盘用的更新记录。只接受 DROP / WRITE：UNCHANGED / OVERSIZE 由调用方自己跳过，
+ * 误传会直接抛错——静默写进一条 entries=undefined 的记录才是真正的坑。
+ * `expectedHash` 是 CAS 基准：扫描之后文件又被改动时，commit 会拒绝这次写入，
+ * 调用方据此回滚自己的快照（见 commitFileUpdates 的返回值）。
+ */
+export function toFileUpdate(rel, plan, record) {
+  if (plan.key === DROP) return { rel, drop: true }
+  if (plan.key !== WRITE) throw new Error(`toFileUpdate: unexpected plan key ${plan.key}`)
+  return {
+    rel,
+    expectedHash: record?.sha256 ?? null,
+    hash: plan.hash,
+    size: plan.size,
+    type: plan.type,
+    entries: plan.entries,
+  }
+}
+
+/**
+ * 一批更新一次性落盘：写入 / 移除 → 清掉本轮未见到的旧条目 → 重建链接。
+ * 单事务的好处是 store 只 save 一次，watch 每轮不会反复重写。
+ *
+ * @returns {{stale: string[], removed: number}} stale 是 CAS 失败（并发改动）的 rel，
+ *   调用方应让它们保持「未落快照」状态，下一轮重试。
+ */
+export function commitFileUpdates(store, { updates, unseen = null, link = true }) {
+  const stale = []
+  let removed = 0
+  store.commit((s) => {
+    for (const update of updates) {
+      if (update.drop) {
+        s.removeFile(update.rel)
+        continue
+      }
+      if (!s.applyFileUpdate(update.rel, update)) stale.push(update.rel)
+    }
+    if (unseen) {
+      for (const rel of Object.keys(s.files)) {
+        if (!unseen.has(rel)) {
+          s.removeFile(rel)
+          removed++
+        }
+      }
+    }
+    if (link) linkEntries(s)
+  })
+  return { stale, removed }
+}