dsh-obsidian-memo 0.16.3

package/lib/host/images.js

@@ -0,0 +1,116 @@
+/** 本地图片读取；持有附件路径缓存和限时负缓存。 */
+import { assertPathWithin, failure, isInside } from '../files.js'
+import { formatBytes } from '../shared.js'
+import { debugLog, now } from './environment.js'
+import { readFile, readdir, realpath, stat } from 'node:fs/promises'
+import { dirname, extname, join, relative, resolve, sep } from 'node:path'
+
+function createImageReader({ assertNotePath, requireNotes }) {
+  const DEFAULT_IMAGE_MAX_BYTES = 8 * 1024 * 1024
+
+  const IMAGE_PATH_CACHE_LIMIT = 500
+
+  const IMAGE_MISS_TTL_MS = 60 * 1000
+
+  function imageMaxBytes(value) {
+    const requested = Number(value)
+    if (!Number.isFinite(requested) || requested <= 0) return null
+    return Math.floor(requested)
+  }
+
+  const imagePaths = new Map()
+
+  const imageMisses = new Map()
+
+  function rememberImagePath(key, actual) {
+    if (imagePaths.size >= IMAGE_PATH_CACHE_LIMIT) {
+      const oldest = imagePaths.keys().next().value
+      if (oldest !== undefined) imagePaths.delete(oldest)
+    }
+    imagePaths.set(key, actual)
+  }
+
+  function rememberImageMiss(key) {
+    if (imageMisses.size >= IMAGE_PATH_CACHE_LIMIT) {
+      const oldest = imageMisses.keys().next().value
+      if (oldest !== undefined) imageMisses.delete(oldest)
+    }
+    imageMisses.set(key, now() + IMAGE_MISS_TTL_MS)
+  }
+
+  async function endpointReadImage(payload) {
+    const startedAt = performance.now()
+    const notePath = await assertNotePath(payload?.path)
+    const wiki = payload?.wiki === true
+    let source = typeof payload?.source === 'string' ? payload.source.trim() : ''
+    try { source = decodeURIComponent(source) } catch { throw failure('bad-request', '图片路径编码无效') }
+    if (!source || source.startsWith('//') || /^[a-z][a-z\d+.-]*:/i.test(source)) throw failure('bad-request', '本地图片路径无效')
+    const paths = requireNotes()
+    const imagePath = resolve(dirname(notePath), source)
+    if (!isInside(paths.vault, imagePath)) throw failure('bad-request', '图片不在 Obsidian 仓库内')
+
+    // 附件名解析（尤其 wiki 裸文件名）要遍历全库；命中与落空都缓存，避免反复 walk。
+    // 命中缓存用 realpath 复核，文件被移动/删除就失效重算。
+    const cacheKey = `${notePath}\u0000${source}\u0000${wiki ? '1' : '0'}`
+    const cached = imagePaths.get(cacheKey)
+    let actual = cached === undefined ? null : await realpath(cached).catch(() => null)
+    if (cached !== undefined && actual === null) imagePaths.delete(cacheKey)
+    if (actual === null) {
+      // 负缓存：60s 内同一附件名不再全库查找（wiki 裸附件名找到不存在的图时最贵）。
+      const missExpires = imageMisses.get(cacheKey)
+      if (missExpires !== undefined) {
+        if (missExpires > now()) {
+          debugLog(`readImage · not-found · negative-cache · ${(performance.now() - startedAt).toFixed(1)}ms`)
+          throw failure('not-found', '找不到本地图片')
+        }
+        imageMisses.delete(cacheKey)
+      }
+    }
+    if (actual === null) {
+      try { actual = await realpath(imagePath) } catch {
+        try { actual = await realpath(resolve(paths.vault, source)) } catch { /* 继续查找 Obsidian 附件 */ }
+      }
+    }
+    if (actual === null && wiki) {
+      debugLog('readImage · walk vault attachments')
+      const matches = []
+      let visited = 0
+      async function walk(dir) {
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+          if (++visited > 20000) throw failure('bad-request', '附件查找范围过大，请使用仓库相对路径')
+          if (entry.name.startsWith('.') || entry.isSymbolicLink() || entry.name === 'node_modules') continue
+          const candidate = join(dir, entry.name)
+          if (entry.isDirectory()) await walk(candidate)
+          else if (entry.isFile() && (relative(paths.vault, candidate).split(sep).join('/') === source || (source.indexOf('/') < 0 && entry.name === source))) matches.push(candidate)
+        }
+      }
+      await walk(paths.vault)
+      if (matches.length > 1) throw failure('bad-request', '有多个同名附件，请使用仓库相对路径')
+      if (matches.length === 1) actual = await realpath(matches[0]).catch(() => null)
+    }
+    if (actual === null) {
+      if (wiki) rememberImageMiss(cacheKey)
+      debugLog(`readImage · not-found · ${(performance.now() - startedAt).toFixed(1)}ms`)
+      throw failure('not-found', '找不到本地图片')
+    }
+    await assertPathWithin(await realpath(paths.vault), actual)
+    const mime = ({ '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp', '.svg': 'image/svg+xml', '.avif': 'image/avif' })[extname(actual).toLowerCase()]
+    if (!mime) throw failure('bad-request', '不支持这种图片格式')
+    const info = await stat(actual)
+    if (!info.isFile()) throw failure('bad-request', '本地图片不是文件')
+    // 默认上限 8 MB；卡片缩略图显式传 maxBytes 时按传入值判定。超过统一报 too-large。
+    const maxBytes = imageMaxBytes(payload?.maxBytes) ?? DEFAULT_IMAGE_MAX_BYTES
+    if (info.size > maxBytes) throw failure('too-large', `本地图片超过读取上限（${formatBytes(maxBytes)}）`)
+    const data = await readFile(actual)
+    imageMisses.delete(cacheKey)
+    rememberImagePath(cacheKey, actual)
+    debugLog(`readImage ${(performance.now() - startedAt).toFixed(1)}ms · ${data.length} bytes · ${cached !== undefined ? 'path-cache' : 'resolve'}`)
+    return { dataUrl: `data:${mime};base64,${data.toString('base64')}` }
+  }
+
+  function clearImagePaths() { imagePaths.clear(); imageMisses.clear() }
+
+  return { endpointReadImage, clearImagePaths }
+}
+
+export { createImageReader }

package/lib/host/mutations.js

@@ -0,0 +1,123 @@
+/** 归档、删除、撤回与系统回收站操作；保留独占移动和整组回滚。 */
+import { assertPathWithin, failure, isInside, moveFileExclusive, readNoteFile } from '../files.js'
+import { openExternalUrl } from '../obsidian.js'
+import { makeId } from '../settings.js'
+import { LIMITS } from '../shared.js'
+import { DELETE_UNDO_MS, moveVaultTrashToSystem, noteAttachments, restoreTrashedNote, trashNote, vaultTrashInfo } from '../trash.js'
+import { now } from './environment.js'
+import { ensureDir, fileExists } from './note-content.js'
+import { lstat, realpath } from 'node:fs/promises'
+import { basename, dirname, join } from 'node:path'
+
+function createMutationEndpoints({
+  assertNotePath, clearImagePaths, deleteUndos, invalidateAndScan, invalidateScan, jobs, purgeExpiredState,
+  requireNotes, resolved, undos, withNoteWrite,
+}) {
+  async function endpointArchive(payload) {
+    const paths = requireNotes()
+    const filePath = await assertNotePath(payload?.path)
+    const targetId = typeof payload?.targetId === 'string' ? payload.targetId : ''
+    const target = paths.archive.find((item) => item.id === targetId)
+    if (!target) throw failure('bad-request', '还没有配置这个归档目录')
+    if (!isInside(paths.vault, target.path)) throw failure('bad-request', '归档目录不在仓库内')
+    if (target.path === paths.notes || isInside(target.path, paths.notes)) throw failure('bad-request', '归档目录不能是便签目录或其父目录')
+    const archiveReal = await assertPathWithin(paths.vault, target.path, { allowMissing: true })
+    const notesReal = await assertPathWithin(paths.vault, paths.notes)
+    if (isInside(archiveReal, notesReal)) throw failure('bad-request', '归档目录不能是便签目录或其父目录')
+    await readNoteFile(filePath)
+    await ensureDir(target.path)
+    await assertPathWithin(paths.vault, target.path)
+    const sourceName = basename(filePath)
+    let candidate = join(target.path, sourceName)
+    if (await fileExists(candidate)) {
+      const stem = sourceName.replace(/\.md$/i, '')
+      let index = 2
+      for (; index < 100; index += 1) {
+        candidate = join(target.path, `${stem} (${index}).md`)
+        if (!(await fileExists(candidate))) break
+      }
+      if (index >= 100) throw failure('exists', '目标目录里同名文件太多')
+    }
+    await assertPathWithin(paths.vault, candidate, { allowMissing: true })
+    await moveFileExclusive(filePath, candidate)
+    await invalidateAndScan(filePath)
+    const undoToken = makeId('undo')
+    purgeExpiredState()
+    undos.set(undoToken, { from: filePath, to: candidate, expires: now() + LIMITS.undoTtlMs })
+    return { undoToken, to: candidate, targetId }
+  }
+
+  async function endpointUndoArchive(payload) {
+    const token = typeof payload?.undoToken === 'string' ? payload.undoToken : ''
+    const entry = undos.get(token)
+    if (!entry || entry.expires < now()) {
+      undos.delete(token)
+      throw failure('not-found', '撤销窗口已过期')
+    }
+    const paths = requireNotes()
+    await assertPathWithin(paths.vault, entry.to)
+    await assertPathWithin(paths.vault, paths.notes)
+    await assertPathWithin(paths.notes, entry.from, { allowMissing: true })
+    if (await fileExists(entry.from)) throw failure('exists', '原位置已有同名文件，无法恢复')
+    await ensureDir(dirname(entry.from))
+    await moveFileExclusive(entry.to, entry.from)
+    undos.delete(token)
+    await invalidateAndScan(entry.from)
+    return { restoredTo: entry.from }
+  }
+
+  async function endpointDeleteNote(payload) {
+    const paths = requireNotes()
+    const filePath = await assertNotePath(payload?.path)
+    if ((await lstat(filePath)).isSymbolicLink()) throw failure('bad-request', '请在原文件位置删除便签，不能删除符号链接')
+    if ([...jobs.values()].some((job) => job.path === filePath && job.status === 'running')) throw failure('busy', '请等这张便签的 AI 任务完成后再删除')
+    const original = await readNoteFile(filePath)
+    const vault = await realpath(paths.vault), notePath = await realpath(filePath)
+    const attachments = await noteAttachments(vault, notePath, original)
+    const entry = await trashNote(vault, notePath, attachments.images)
+    purgeExpiredState()
+    const undoToken = makeId('delete')
+    const expiresAt = now() + DELETE_UNDO_MS
+    deleteUndos.set(undoToken, { ...entry, expires: expiresAt })
+    clearImagePaths()
+    invalidateScan(filePath)
+    return { undoToken, expiresAt, imageCount: attachments.images.length, sharedImageCount: attachments.shared }
+  }
+
+  async function endpointUndoDelete(payload) {
+    const token = typeof payload?.undoToken === 'string' ? payload.undoToken : ''
+    const entry = deleteUndos.get(token)
+    if (!entry || entry.expires <= now()) {
+      deleteUndos.delete(token)
+      throw failure('not-found', '撤回窗口已过期，可在仓库 .trash 文件夹中找回文件')
+    }
+    if (!resolved().vault || await realpath(resolved().vault) !== entry.vault) throw failure('conflict', '仓库设置已更改，请在原仓库 .trash 文件夹中恢复文件')
+    await withNoteWrite(entry.entries[0].from, () => restoreTrashedNote(entry))
+    deleteUndos.delete(token)
+    invalidateScan(entry.entries[0].from)
+    clearImagePaths()
+    return { restoredTo: entry.entries[0].from }
+  }
+
+  async function endpointTrash(payload) {
+    const vault = resolved().vault
+    if (!vault) throw failure('not-configured', '请先选择仓库')
+    const info = await vaultTrashInfo(vault)
+    if (payload?.action === 'reveal') {
+      if (!info.exists) throw failure('not-found', '仓库回收站为空')
+      const opened = await openExternalUrl(info.path)
+      if (!opened.ok) throw failure('open-failed', opened.message)
+    } else if (payload?.action === 'empty') {
+      if (payload.confirm !== true) throw failure('bad-request', '请先确认移至系统垃圾桶')
+      if ([...deleteUndos.values()].some((item) => item.expires > now())) throw failure('busy', '请等待 5 秒撤回窗口结束后再清理')
+      const result = await moveVaultTrashToSystem(vault)
+      deleteUndos.clear()
+      return result
+    } else if (payload?.action !== 'info') throw failure('bad-request', '未知回收站操作')
+    return info
+  }
+
+  return { endpointArchive, endpointUndoArchive, endpointDeleteNote, endpointUndoDelete, endpointTrash }
+}
+
+export { createMutationEndpoints }

package/lib/host/note-content.js

@@ -0,0 +1,44 @@
+/** 读取完整便签和模型原文，以及共享文件/目录辅助函数。 */
+import { contentRevision, failure, readNoteFile } from '../files.js'
+import { commentKindsFrom, getBody, parseNote } from '../notes.js'
+import { LIMITS } from '../shared.js'
+import { mkdir, stat } from 'node:fs/promises'
+import { basename, extname } from 'node:path'
+
+async function fileExists(filePath) {
+  try {
+    await stat(filePath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function ensureDir(dirPath) {
+  const info = await stat(dirPath).catch(() => null)
+  if (info !== null && !info.isDirectory()) throw failure('fs-failed', `不是文件夹：${dirPath}`)
+  if (info === null) await mkdir(dirPath, { recursive: true })
+}
+
+async function readFullNote(filePath) {
+  const text = await readNoteFile(filePath)
+  // 为让 commentKinds 覆盖「全部评论」解析到 scanComments；对外 comments 仍只给 fullComments 条。
+  const parsed = parseNote(text, { maxComments: LIMITS.scanComments, maxBlocks: LIMITS.blocks })
+  return {
+    path: filePath,
+    title: basename(filePath, '.md'),
+    body: getBody(text),
+    contentRevision: contentRevision(text),
+    blocks: parsed.blocks,
+    comments: parsed.comments.slice(0, LIMITS.fullComments),
+    commentCount: parsed.comments.length,
+    commentKinds: commentKindsFrom(parsed.comments),
+    projects: parsed.projects,
+  }
+}
+
+async function readModelSource(filePath) {
+  return { title: basename(filePath, extname(filePath)), body: getBody(await readNoteFile(filePath)) }
+}
+
+export { fileExists, ensureDir, readFullNote, readModelSource }

package/lib/host/notes.js

@@ -0,0 +1,148 @@
+/** 便签读取、新建、版本化编辑、改名、任务切换和 Obsidian 打开。 */
+import { createCapturedNote } from '../capture.js'
+import { sanitizeNoteFileName } from '../filename.js'
+import { assertPathWithin, atomicWrite, contentRevision, failure, isInside, moveFileExclusive, readNoteFile } from '../files.js'
+import { getBody, parseNote, splitFrontmatter, summarizeImages } from '../notes.js'
+import { openNoteInObsidian } from '../obsidian.js'
+import { LIMITS, colorForTag, darkColorForTag } from '../shared.js'
+import { debugLog, now } from './environment.js'
+import { fileExists, readFullNote } from './note-content.js'
+import { realpath, rename, stat } from 'node:fs/promises'
+import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path'
+
+function createNoteEndpoints({ assertNotePath, getSettings, invalidateAndScan, requireNotes, resolved, scanOnce, scanner }) {
+  async function endpointNote(payload) {
+    const filePath = await assertNotePath(payload?.path)
+    await scanOnce()
+    let note = await scanner.readFull(filePath)
+    if (note === null) {
+      await scanOnce()
+      note = await scanner.readFull(filePath)
+    }
+    if (note === null) {
+      const full = await readFullNote(filePath)
+      return {
+        ...full,
+        relPath: relative(resolved().vault, filePath).split(sep).join('/'),
+        name: basename(filePath, '.md'),
+        excerpt: '',
+        tag: null,
+        color: colorForTag(null),
+        darkColor: darkColorForTag(null),
+        comments: full.comments.slice(0, LIMITS.fullComments),
+        commentCount: full.commentCount,
+        ...summarizeImages(full.blocks),
+        commentKinds: full.commentKinds,
+        mtime: now(),
+        size: 0,
+        pending: null,
+      }
+    }
+    return note
+  }
+
+  async function endpointSaveNote(payload) {
+    const filePath = await assertNotePath(payload?.path)
+    if (typeof payload?.body !== 'string') throw failure('bad-request', '缺少正文')
+    const originalName = basename(filePath, extname(filePath))
+    const requestedName = payload?.name ?? originalName
+    let name = originalName
+    if (requestedName !== originalName) {
+      const nameCheck = sanitizeNoteFileName(requestedName)
+      if (nameCheck.error === 'too-long') throw failure('bad-request', `文件名不能超过 ${LIMITS.noteNameBytes} 字节`)
+      if (nameCheck.error === 'reserved') throw failure('bad-request', '文件名不能使用系统保留名')
+      if (nameCheck.error === 'empty') throw failure('bad-request', '文件名不能为空')
+      name = nameCheck.name
+    }
+    const target = name === originalName ? filePath : join(dirname(filePath), `${name}.md`)
+    let caseOnlyRename = false
+    await assertPathWithin(requireNotes().vault, target, { allowMissing: true })
+    if (target !== filePath && await fileExists(target)) {
+      // 仅大小写不同的改名：macOS/Windows 的大小写不敏感文件系统上 fileExists 会命中自己，
+      // 两边 realpath 相同就说明是同一个文件，允许改名，不误报 exists。
+      const [sourceReal, targetReal] = await Promise.all([
+        realpath(filePath).catch(() => null),
+        realpath(target).catch(() => null),
+      ])
+      if (sourceReal === null || targetReal === null || sourceReal !== targetReal) {
+        throw failure('exists', `同名便签已存在：${name}`)
+      }
+      caseOnlyRename = true
+    }
+    const original = await readNoteFile(filePath)
+    if (typeof payload.expectedRevision !== 'string' || payload.expectedRevision !== contentRevision(original)) {
+      throw failure('conflict', '便签已被修改或缺少编辑版本；请先复制保留草稿，再取消编辑并重新打开')
+    }
+    const { frontmatter, bom } = splitFrontmatter(original)
+    const bare = payload.body.replace(/\r\n?/g, '\n').replace(/^\n+/u, '').replace(/\s+$/u, '')
+    const bodyText = bare === '' ? '' : `${bare}\n`
+    const composed = frontmatter === null
+      ? bodyText
+      : bodyText === '' ? `${frontmatter}\n` : `${frontmatter}\n\n${bodyText}`
+    const content = `${bom ? '\uFEFF' : ''}${composed}`
+    if (Buffer.byteLength(content, 'utf8') > LIMITS.maxFileBytes) throw failure('bad-request', '便签文件过大')
+    await atomicWrite(filePath, content)
+    if (target !== filePath) {
+      try {
+        if (caseOnlyRename) await rename(filePath, target)
+        else await moveFileExclusive(filePath, target)
+      } catch (error) {
+        if (error.code === 'EEXIST') throw failure('exists', `同名便签已存在：${name}；正文已保存在原文件中`)
+        throw error
+      }
+    }
+    await invalidateAndScan(filePath)
+    const note = scanner.summary(target)
+    if (note === null) throw failure('fs-failed', '保存后读不到便签')
+    return { note }
+  }
+
+  async function endpointCreateNote(payload) {
+    const path = await createCapturedNote(requireNotes(), payload)
+    await invalidateAndScan(path).catch((error) => debugLog('新建后刷新失败：', error.message))
+    // 目录可在创建后被切换；提交已落盘时依然返回成功，避免重试产生歧义。
+    return { note: scanner.summary(path), path }
+  }
+
+  async function endpointToggleTask(payload) {
+    const filePath = await assertNotePath(payload?.path)
+    const sourceLine = Number(payload?.sourceLine)
+    if (!Number.isInteger(sourceLine) || sourceLine < 0 || typeof payload?.checked !== 'boolean') throw failure('bad-request', '任务项参数无效')
+    const original = await readNoteFile(filePath)
+    const split = splitFrontmatter(original)
+    if (getBody(original) !== payload?.expectedBody) throw failure('conflict', '便签已被修改，请刷新后再勾选')
+    if (!parseNote(original).blocks.some((block) => block.kind === 'li' && block.sourceLine === sourceLine)) throw failure('bad-request', '只能修改阅读模式中的任务项')
+    const lines = split.body.split('\n')
+    if (sourceLine >= lines.length) throw failure('bad-request', '任务项已变化，请刷新后重试')
+    const line = lines[sourceLine]
+    const match = line.match(/^(\s*(?:[-*+]|\d+[.)])\s+\[)([ xX])(\]\s+.*)$/)
+    if (!match) throw failure('bad-request', '这行已不是任务项，请刷新后重试')
+    // 只替换对应行的任务标记，保留 BOM、frontmatter、空行与原换行格式。
+    const raw = original.split(/(\r\n|\r|\n)/)
+    const lineIndex = (Math.ceil(raw.length / 2) - lines.length + sourceLine) * 2
+    raw[lineIndex] = raw[lineIndex].replace(/(\[)[ xX](\])/, `$1${payload.checked ? 'x' : ' '}$2`)
+    await atomicWrite(filePath, raw.join(''))
+    await invalidateAndScan(filePath)
+    return { note: scanner.summary(filePath) }
+  }
+
+  async function endpointOpenInObsidian(payload) {
+    const raw = payload?.path
+    if (typeof raw !== 'string' || raw.trim() === '') throw failure('bad-request', '缺少便签路径')
+    const target = resolve(raw)
+    const vault = getSettings().vaultPath ? resolve(getSettings().vaultPath) : ''
+    if (vault === '' || !isInside(vault, target)) throw failure('bad-request', '便签必须在仓库内')
+    await assertPathWithin(vault, target)
+    const info = await stat(target).catch(() => null)
+    if (info === null || !info.isFile()) throw failure('not-found', '便签不存在')
+    const opened = await openNoteInObsidian(target)
+    if (opened?.ok !== true) {
+      throw failure('open-failed', opened?.message ? `打开 Obsidian 失败：${opened.message}` : '打开 Obsidian 失败')
+    }
+    return { url: opened.url }
+  }
+
+  return { endpointNote, endpointSaveNote, endpointCreateNote, endpointToggleTask, endpointOpenInObsidian }
+}
+
+export { createNoteEndpoints }

package/lib/host/rpc.js

@@ -0,0 +1,82 @@
+/** 已认证 HTTP RPC 传输：认证、路径、请求预算与信封；不执行业务。 */
+import { CHANNEL, LIMITS } from '../shared.js'
+
+function registerRpcRoute(ctx, dispatch) {
+  ctx.effect(() => {
+    const webServer = ctx.get('webServer')
+    const connection = ctx.get('connection')
+    if (webServer === undefined) return () => {}
+    const route = {
+      kind: 'prefix',
+      path: CHANNEL,
+      handler: async (req, res) => {
+        const rejection = connection?.requestRejection?.({ headers: req.headers })
+        if (rejection !== undefined) {
+          res.writeHead(rejection)
+          res.end(rejection === 401 ? 'unauthorized' : 'forbidden')
+          return
+        }
+        if (req.method !== 'POST') {
+          res.writeHead(405)
+          res.end('method not allowed')
+          return
+        }
+        let pathname
+        try { pathname = new URL(req.url ?? CHANNEL, 'http://127.0.0.1').pathname } catch {
+          respond(res, 'invalid', { ok: false, error: { code: 'bad-request', message: '请求路径无效', details: {} } })
+          return
+        }
+        const pathEndpoint = pathname.startsWith(`${CHANNEL}/`) ? pathname.slice(CHANNEL.length + 1) : ''
+        let raw = ''
+        try {
+          const limit = pathEndpoint === 'createNote' ? LIMITS.captureRequestBytes
+            : ['saveNote', 'toggleTask'].includes(pathEndpoint) ? LIMITS.noteRequestBytes : LIMITS.maxFileBytes
+          let bytes = 0
+          const chunks = []
+          for await (const chunk of req) {
+            bytes += Buffer.byteLength(chunk)
+            if (bytes > limit) throw new Error('body too large')
+            chunks.push(Buffer.from(chunk))
+          }
+          raw = Buffer.concat(chunks).toString('utf8')
+        } catch (error) {
+          res.writeHead(400)
+          res.end('unreadable body')
+          return
+        }
+        let message
+        try {
+          message = JSON.parse(raw)
+        } catch {
+          respond(res, 'invalid', { ok: false, error: { code: 'bad-request', message: 'body is not JSON', details: {} } })
+          return
+        }
+        const rpcId = typeof message?.rpcId === 'string' ? message.rpcId : 'invalid'
+        const endpoint = typeof message?.method === 'string' ? message.method : ''
+        if (endpoint === '' || endpoint !== pathEndpoint) {
+          respond(res, rpcId, {
+            ok: false,
+            error: { code: 'bad-request', message: `method ${JSON.stringify(endpoint)} 与路径 ${JSON.stringify(pathname)} 不匹配`, details: {} },
+          })
+          return
+        }
+        let result
+        try {
+          result = await dispatch(endpoint, message.payload ?? {})
+        } catch (error) {
+          result = { ok: false, error: { code: 'fs-failed', message: error?.message ?? String(error), details: {} } }
+        }
+        respond(res, rpcId, result)
+      },
+    }
+    return webServer.register(route)
+  }, 'sticky-notes: rpc route')
+}
+
+function respond(res, rpcId, result) {
+  const body = { type: 'server-response', rpcId, result }
+  res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' })
+  res.end(JSON.stringify(body))
+}
+
+export { registerRpcRoute }

package/lib/host/scanning.js

@@ -0,0 +1,67 @@
+/** 按实例维护扫描单飞、串行队列和失效代次。 */
+import { NotesScanner } from '../scan.js'
+import { debugLog } from './environment.js'
+
+function createScanCoordinator({ getSettings }) {
+  const scanner = new NotesScanner()
+
+  let scanEpoch = 0
+
+  let scanRecord = null
+
+  let scanQueue = Promise.resolve()
+
+  function invalidateScan(filePath) {
+    scanEpoch += 1
+    scanner.invalidate(filePath)
+  }
+
+  function resetScan() {
+    scanEpoch += 1
+    scanner.reset()
+    return scanEpoch
+  }
+
+  function queueScan() {
+    const run = scanQueue.then(() => scanner.scan(getSettings()))
+    scanQueue = run.catch(() => {})
+    return run
+  }
+
+  function scanOnce(requireEpoch = 0) {
+    const current = scanRecord
+    // 进行中的扫描会在结束时自检 epoch 并重试，可以安全复用；
+    // 已结束的扫描只有代次足够新时才复用，避免把写前结果返回给写操作。
+    if (current !== null && (current.epoch >= requireEpoch || !current.settled)) {
+      debugLog('scan reuse · in-flight')
+      return current.promise
+    }
+    const record = { epoch: scanEpoch, settled: false, promise: null }
+    record.promise = (async () => {
+      for (;;) {
+        const epoch = scanEpoch
+        const startedAt = performance.now()
+        const result = await queueScan()
+        const elapsed = (performance.now() - startedAt).toFixed(1)
+        debugLog(`scan ${elapsed}ms · ${result.notes.length} notes${epoch === scanEpoch ? '' : ' · epoch changed, retry'}`)
+        if (epoch === scanEpoch) {
+          record.settled = true
+          return result
+        }
+      }
+    })().finally(() => {
+      if (scanRecord === record) scanRecord = null
+    })
+    scanRecord = record
+    return record.promise
+  }
+
+  async function invalidateAndScan(filePath) {
+    invalidateScan(filePath)
+    return scanOnce(scanEpoch)
+  }
+
+  return { invalidateScan, resetScan, scanOnce, invalidateAndScan, scanner }
+}
+
+export { createScanCoordinator }

package/lib/host/session.js

@@ -0,0 +1,67 @@
+/** 按实例持有任务与撤回 token，清理过期状态并提供任务快照。 */
+import { makeId } from '../settings.js'
+import { LIMITS } from '../shared.js'
+import { debugLog, now } from './environment.js'
+
+function createSessionState() {
+  const jobs = new Map()
+
+  const undos = new Map()
+
+  const deleteUndos = new Map()
+
+  function purgeExpiredState() {
+    const time = now(), cutoff = time - LIMITS.jobsTtlMs
+    for (const [id, job] of jobs) {
+      if (job.status !== 'running' && (job.finishedAt ?? 0) < cutoff) jobs.delete(id)
+    }
+    for (const tokens of [undos, deleteUndos]) {
+      for (const [token, entry] of tokens) if (entry.expires <= time) tokens.delete(token)
+    }
+  }
+
+  function liveJobs() {
+    purgeExpiredState()
+    return [...jobs.values()].map((job) => ({ ...job }))
+  }
+
+  function runningJob(kind, filePath, emojiId) {
+    for (const job of jobs.values()) {
+      if (job.status !== 'running' || job.kind !== kind || job.path !== filePath) continue
+      if (kind === 'comment' && job.emojiId !== emojiId) continue
+      return job
+    }
+    return undefined
+  }
+
+  function startJob(kind, filePath, extra = {}) {
+    const job = { id: makeId('job'), kind, path: filePath, status: 'running', startedAt: now(), ...extra }
+    jobs.set(job.id, job)
+    return job
+  }
+
+  function finishJob(job, error) {
+    job.finishedAt = now()
+    if (error) {
+      job.status = 'error'
+      job.error = error?.message ?? String(error)
+      // 0.13：带错误码，Client 据此给出「去调 AI 预算」这类可操作提示（例如 llm-token-budget）。
+      const code = error?.code
+      if (typeof code === 'string' && code !== '') job.errorCode = code
+      debugLog(`${job.kind} 失败${job.errorCode ? `(${job.errorCode})` : ''}：${job.error}`)
+    } else {
+      job.status = 'done'
+    }
+  }
+
+  function jobsFingerprint() {
+    return [...jobs.values()]
+      .map((job) => `${job.id}:${job.status}:${job.error ?? ''}:${job.errorCode ?? ''}:${job.truncated === true ? 'cut' : ''}`)
+      .sort()
+      .join('|')
+  }
+
+  return { purgeExpiredState, liveJobs, runningJob, startJob, finishJob, jobsFingerprint, jobs, undos, deleteUndos }
+}
+
+export { createSessionState }