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

package/src/lazy.js

@@ -1,11 +1,8 @@
 import path from 'node:path'
 import { tmpdir } from 'node:os'
 import { existsSync, readdirSync, statSync } from 'node:fs'
-import { isSupportedCode, isSupportedDoc, memoryRootFor, readFileForIndex, relativePath, storeKey } 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'
+import { memoryRootFor, relativePath, storeKey } from './util/fs.js'
+import { DROP, OVERSIZE, UNCHANGED, commitFileUpdates, fileKind, planFileIndex, toFileUpdate } from './index-pipeline.js'
 import { ProjectMemoryStore } from './store.js'
 import { onFileObserved } from './enhancer.js'
 
@@ -78,70 +75,42 @@ export function findProjectRoot(filePath, ceiling = path.resolve(tmpdir())) {
 }
 
 export async function indexFile(ctx, config, filePath, watchManager = null) {
-  const ext = path.extname(filePath).toLowerCase()
-  if (!isSupportedDoc(ext) && !isSupportedCode(ext)) return false
+  const kind = fileKind(path.extname(filePath).toLowerCase())
+  if (!kind) return false
   const root = findProjectRoot(filePath)
   if (!root) return false
 
   const memoryDir = memoryRootFor(root, config.memoryDir)
   const store = new ProjectMemoryStore(memoryDir).load()
   const rel = storeKey(relativePath(root, filePath))
-  const existing = store.fileRecord(rel)
-  let hash
+  const record = store.fileRecord(rel)
+
   let size
-  let buffer
-  let entries
+  let plan
   try {
-    if (isSupportedCode(ext) && config.maxFileSizeMb && statSync(filePath).size > config.maxFileSizeMb * 1024 * 1024) {
-      return false
-    }
-    ;({ hash, size, buffer } = readFileForIndex(filePath))
+    size = statSync(filePath).size
+    plan = await planFileIndex({ rel, filePath, kind, config, record, existingEntries: store.entries[rel], size })
   } catch {
     return false
   }
-  // 旧 store 的 doc 条目缺 terms → 一次性回填（即使哈希未变）
-  if (existing && existing.sha256 === hash && !(isSupportedDoc(ext) && docEntriesNeedBackfill(store.entries[rel]))) return false
+  if (plan.key === UNCHANGED || plan.key === OVERSIZE) return false
 
   if (watchManager) {
     watchManager.addRoot(root)
     store.addWatch(root)
   }
 
-  if (isSupportedCode(ext)) {
-    entries = scanSymbols(rel, filePath, buffer.toString('utf8'))
+  if (plan.key !== DROP && plan.type === 'code') {
     onFileObserved(store, rel, filePath, config, root)
-    return store.commit((s) => {
-      s.markFile(rel, { sha256: hash, size, type: 'code', indexedAt: new Date().toISOString() })
-      s.setEntries(rel, entries)
-      linkEntries(s)
-      return true
-    })
-  } else {
-    entries = await buildDocEntries(rel, filePath, {
-      chunkChars: config.chunkChars,
-      maxChunks: config.maxChunksPerFile,
-      maxFileSizeMb: config.maxFileSizeMb,
-      maxPdfPages: config.maxPdfPages,
-    })
-    if (entries === null) {
-      return store.commit((s) => {
-        s.removeFile(rel)
-        return false
-      })
-    }
-    return store.commit((s) => {
-      s.markFile(rel, { sha256: hash, size, type: 'doc', indexedAt: new Date().toISOString() })
-      s.setEntries(rel, entries)
-      linkEntries(s)
-      return true
-    })
   }
+  commitFileUpdates(store, { updates: [toFileUpdate(rel, plan, record)] })
+  return plan.key !== DROP
 }
 
 export function codeFirst(paths) {
   return [...paths].sort((a, b) => {
-    const aCode = isSupportedCode(path.extname(a).toLowerCase()) ? 0 : 1
-    const bCode = isSupportedCode(path.extname(b).toLowerCase()) ? 0 : 1
+    const aCode = fileKind(path.extname(a).toLowerCase()) === 'code' ? 0 : 1
+    const bCode = fileKind(path.extname(b).toLowerCase()) === 'code' ? 0 : 1
     return aCode - bCode
   })
 }

package/src/link.js

@@ -39,7 +39,16 @@ export function linkEntries(store) {
         if (linked.size > before) links++
       }
     }
-    doc.linkedSymbols = linked.size ? [...linked] : undefined
+    const before = Array.isArray(doc.linkedSymbols) ? doc.linkedSymbols.join('\u0000') : ''
+    const next = [...linked]
+    if (before === next.join('\u0000')) continue
+    doc.linkedSymbols = next.length ? next : undefined
+    // 链接是在**符号**落盘那一刻算出来的，此时 doc 的 shard 往往不是脏的；不标脏就只存在于内存，
+    // 下次进程启动重新加载后链接全部丢失（"文档先索引、符号后到"的正常顺序）。
+    if (typeof store.markFile === 'function' && typeof store.fileRecord === 'function' && doc.sourcePath) {
+      const record = store.fileRecord(doc.sourcePath)
+      if (record) store.markFile(doc.sourcePath, record)
+    }
   }
   return links
 }

package/src/parsers/pdfjs-parser.js

@@ -60,9 +60,8 @@ export async function parsePdf(filePath, { pages = null, maxPages = 1000, backen
   const data = new Uint8Array(await readFile(filePath))
   const { getDocument } = await loadPdfjs()
   const loadingTask = getDocument({ data, ...PDFJS_OPTIONS })
-  const doc = await loadingTask.promise
-
   try {
+    const doc = await loadingTask.promise
     const total = doc.numPages
     if (total > maxPages) {
       throw new Error(`PDF has ${total} pages, over the maxPages limit of ${maxPages}`)
@@ -112,9 +111,8 @@ export async function parsePdfInfo(filePath, maxPages = 1000) {
   const data = new Uint8Array(await readFile(filePath))
   const { getDocument } = await loadPdfjs()
   const loadingTask = getDocument({ data, ...PDFJS_OPTIONS })
-  const doc = await loadingTask.promise
-
   try {
+    const doc = await loadingTask.promise
     if (doc.numPages > maxPages) {
       throw new Error(`PDF has ${doc.numPages} pages, over the maxPages limit of ${maxPages}`)
     }

package/src/project-profile.js

@@ -17,11 +17,18 @@ function depsOf(manifest, fields) {
   const tags = new Set()
   for (const f of fields) {
     const deps = manifest && manifest[f]
-    if (deps && typeof deps === 'object') {
-      for (const name of Object.keys(deps)) {
-        tags.add(name.toLowerCase())
-        if (name.startsWith('@')) tags.add(name.split('/')[1].toLowerCase())
-      }
+    if (!deps || typeof deps !== 'object') continue
+    for (const name of Object.keys(deps)) {
+      if (typeof name !== 'string' || !name) continue
+      tags.add(name.toLowerCase())
+      if (!name.startsWith('@')) continue
+      // scoped 包名 `@scope/pkg`：要加的是 **scope**（`vue`），不是包名段（`compiler-sfc`）。
+      // 旧写法 `name.split('/')[1]` 让 `@vue/*` 项目永远拿不到 `vue` tag，
+      // trigger.scope:['vue'] / legacy scope 过滤会把最相关的那条 procedure 静默判死；
+      // 而 `@malformed`（没有 `/`）会在这里抛错，异常被 collectTags 整个吞掉 → 全项目 tags 清零。
+      const parts = name.slice(1).split('/')
+      if (parts[0]) tags.add(parts[0].toLowerCase())
+      if (parts[1]) tags.add(parts[1].toLowerCase())
     }
   }
   return tags

package/src/readiness.js

@@ -82,7 +82,16 @@ export function buildReadinessContext(input = {}) {
   const humanText = String(input.humanText ?? input.query ?? '')
   const actionText = String(input.actionText || '')
   const actions = new Set([...(input.actions || []), ...detectActions(humanText), ...detectActions(actionText)])
-  const paths = new Set([...(input.paths || []), ...extractPaths(actionText), ...extractPaths(humanText)])
+  // 人类消息里提到的路径 = **动手前的写意图**（"帮我改 src/x.js"）；动作文本里的路径不区分读写，
+  // 读一个文件不该算写目标（否则 `read README.md` 会命中 writes:['README.md']）。
+  // 两者对外仍合并成 `paths`（兼容既有语义），写通道单看 humanPaths。
+  // 调用方若已带 humanPaths（injectForStep 构建后再传给 buildInjection），以它为准，
+  // 否则退回 paths —— 避免把上一次算出来的并集（含读路径）再当写意图。
+  const humanPaths = new Set([
+    ...(Array.isArray(input.humanPaths) ? input.humanPaths : (input.paths || [])),
+    ...extractPaths(humanText),
+  ])
+  const paths = new Set([...humanPaths, ...extractPaths(actionText)])
   // 动作平面（S1）：结构化调用优先；没有结构化调用时对 actionText 跑一遍 shell 规则兜底。
   const fromText = activityFromText(actionText)
   const ops = new Set([...(input.ops || []), ...fromText.ops])
@@ -97,6 +106,7 @@ export function buildReadinessContext(input = {}) {
     actionText,
     actions: [...actions],
     paths: [...paths],
+    humanPaths: [...humanPaths],
     ops: [...ops],
     targets: [...targets],
     hosts: [...hosts],
@@ -209,6 +219,10 @@ export function intentText(text) {
     .replace(/“[^”\n]*”/g, ' ')
     .replace(/[A-Za-z]:\\[^\s"']*/g, ' ')
     .replace(/(?:[A-Za-z0-9_.@-]+\/)+[A-Za-z0-9_.@-]+/g, ' ')
+    // 带扩展名的**非 ASCII 文件名**（`石啸天-记忆方向调研.pptx` / `docs/面试演示-王金鹏.md`）：
+    // 只挡 ASCII 路径不够——中文文件名整块留下，"调研""面试"这类子串照样触发 when.intents，
+    // 正是引号剥离要防的那类假阳性。ASCII 裸名（如 de-TODO.md）保持原语义，不在这里动。
+    .replace(/\S*[^\x00-\x7F]\S*\.[A-Za-z][A-Za-z0-9]{0,7}\b/g, ' ')
     // 仓库里的裸文件名（README / CHANGELOG …）也是语料，不是意图
     .replace(/\b(?:README|CHANGELOG|LICENSE|AGENTS|CONTRIBUTING|Dockerfile|Makefile)\b/g, ' ')
     .replace(/\s+/g, ' ')
@@ -301,10 +315,14 @@ export function matchTrigger(trigger, ctx) {
   for (const op of when.ops || []) {
     if (op && (ctx?.ops || []).includes(String(op))) return `op:${op}`
   }
+  // 写目标 = 已观察到的结构化写调用 ∪ 人类消息里提到的路径（动手前的写意图）。
+  // DSH 没有工具执行前拦截钩子，动手前唯一能拿到的写意图就是人类消息里的路径；
+  // 但动作文本里的**读**路径不算（`read README.md` 不是"即将写 README.md"）。
+  const writeTargets = [...(ctx?.targets || []), ...(ctx?.humanPaths || [])]
   for (const w of when.writes || []) {
     // 扩展名/泛名 glob 在这里被硬性忽略：`*.pptx` 这类条件只能撒谎，不能收窄。
     if (!w || isDroppableGlob(w)) continue
-    if (matchAnyPath(w, ctx?.targets)) return `write:${w}`
+    if (matchAnyPath(w, writeTargets)) return `write:${w}`
   }
   const intent = ctx?.intent ?? ctx?.humanText ?? ''
   for (const it of when.intents || []) {
@@ -355,6 +373,9 @@ export function normalizeTrigger(it, opts = {}) {
   // （实测：那样会让 D 场景一次多出 6 条假阳性）。
   const intents = []
   for (const k of t.keywords || []) if (isIntentWord(k)) intents.push(String(k))
+  // 旧 `symbols` 也走文本平面：不归一就等于静默丢掉一个作者写下的触发面
+  // （README 承诺 keywords/symbols/actions/paths/scope 都会迁移）。与 keywords 同一把准入尺子。
+  for (const s of t.symbols || []) if (isIntentWord(s)) intents.push(String(s))
   const when = {}
   if (ops.size) when.ops = [...ops].sort()
   if (writes.length) when.writes = [...new Set(writes)]
@@ -463,6 +484,9 @@ export function relativeHits(scored, { ratioMin = 0.5 } = {}) {
   const list = (scored || []).filter((r) => r && Number.isFinite(r.score) && r.score > 0)
   if (!list.length) return []
   const top = list[0].score
-  const floor = top * (typeof ratioMin === 'number' && ratioMin > 0 ? ratioMin : 0.5)
+  // 显式的 0 表示"关掉相对门槛"（只剩 score>0）；未给/非法值才回退 0.5。
+  // 旧写法 `ratioMin > 0 ? ratioMin : 0.5` 把 0 当成"没配"，配置上无法关闭。
+  const ratio = typeof ratioMin === 'number' && Number.isFinite(ratioMin) ? ratioMin : 0.5
+  const floor = top * Math.max(0, Math.min(1, ratio))
   return list.filter((r) => r.score >= floor)
 }

package/src/recall.js

@@ -101,6 +101,21 @@ export function insightToEntry(ins) {
   }
 }
 
+/**
+ * 一条 insight 的**打分文本**（BM25 与 IDF 覆盖率必须用同一份）。
+ *
+ * 为什么要有这个函数：提示通道的"这条查询离语料有多远"（`idfCoverage` 的 df）曾经用
+ * `insightMatchText` 计算，而排序用 `insightToEntry`（含 fix/solution/reason/steps）。
+ * 于是"只在解药里有匹配"的查询词 df=0 → supportRatio=0 → **整条提示通道本轮沉默**，
+ * 而排序明明给了它高分。两份文本永远来自同一个 entry，才不会再漂移。
+ * @param {object} ins
+ * @returns {string}
+ */
+export function insightScoringText(ins) {
+  const e = insightToEntry(ins)
+  return [e.title, e.summary, e.terms, ...(e.keywords || [])].filter(Boolean).join('\n')
+}
+
 /**
  * 召回可见的 insight 集合：作用域可见性跟随会话绑定。
  *   - project / global：始终可见（归档除外）；
@@ -127,6 +142,9 @@ export function visibleInsights({ store = null, globalStore = null, boundTaskId
     const task = store.getTask(boundTaskId)
     for (const it of (task && task.insights) || []) {
       if (!it || it.archived) continue
+      // 任务级也要挡草稿：reflection 写的是 draft:true，未确认前不该被 query_memory 召回
+      // （project/global 一直有这道闸，任务级漏了）。
+      if (it.draft === true) continue
       out.push({ ...it, scope: it.scope || 'task' })
     }
   }
@@ -163,15 +181,17 @@ export function recallItems(opts = {}) {
   if (want.has('doc') || want.has('symbol')) {
     const pool = (entries || (store && typeof store.allEntries === 'function' ? store.allEntries() : []) || [])
       .filter((e) => e && (e.type === 'doc' || e.type === 'symbol') && want.has(e.type))
-    const scored = rankEntriesStreaming(pool, qs, idf, limit)
-    const byLayer = new Map([['doc', []], ['symbol', []]])
-    for (const { entry, score } of scored) {
-      const prior = entry.type === 'doc' ? normativePrior(entry) : LAYER_PRIORS.symbol
-      byLayer.get(entry.type).push({ item: entry, score, prior, weightedScore: score * prior })
-    }
+    // 每层各自 top-k（不变量 #2）：一次跨类型取 top-k 会让文档把符号挤出结果——
+    // 20 条命中文档 + 1 条命中符号、limit 8 时符号层直接消失。分类型各取一次再分桶。
     for (const layer of ['doc', 'symbol']) {
-      const hits = byLayer.get(layer)
-      if (!hits.length) continue
+      const layerPool = pool.filter((e) => e.type === layer)
+      if (!layerPool.length) continue
+      const scored = rankEntriesStreaming(layerPool, qs, idf, limit)
+      if (!scored.length) continue
+      const hits = scored.map(({ entry, score }) => {
+        const prior = layer === 'doc' ? normativePrior(entry) : LAYER_PRIORS.symbol
+        return { item: entry, score, prior, weightedScore: score * prior }
+      })
       hits.sort((a, b) => b.weightedScore - a.weightedScore)
       const top = hits[0].weightedScore || 1
       buckets.push({

package/src/setup/taskbridge.js

@@ -2,7 +2,7 @@
 // 事实依据：dsh session/event 签名 (session, event)；todo/write data.todos；
 // tool/call data.arguments 为 JSON 字符串；fs 工具名 read/write/edit/read_image，参数 file_path。
 import path from 'node:path'
-import { createHash } from 'node:crypto'
+import { createHash, randomUUID } from 'node:crypto'
 import { memoryRootFor } from '../util/fs.js'
 import { findProjectRoot } from '../lazy.js'
 import { ProjectMemoryStore } from '../store.js'
@@ -27,7 +27,9 @@ export function slugifyTitle(text) {
 
 export function genTaskId(projectRoot, title) {
   const slug = slugifyTitle(title) || 'task'
-  return `tsk_${hash8(projectRoot)}_${slug}_${Date.now()}`
+  // 毫秒不是唯一性保证：两个会话在同一毫秒建同名任务会拿到同一个 id，
+  // addTask 变成"同一 id 两次"，两个会话的绑定互相串台。补 6 位随机后缀。
+  return `tsk_${hash8(projectRoot)}_${slug}_${Date.now().toString(36)}_${randomUUID().slice(0, 6)}`
 }
 
 /** 项目根推导：findProjectRoot 期望文件路径，传目录会从父级起跳，故用目录内探针路径。 */
@@ -138,13 +140,7 @@ export function hotSortFiles(files, meta) {
 /** 触碰文件后更新元数据并重排 task.files（写 vs 读分别记时间/次数）。 */
 export function touchTaskFile(task, rel, kind, now) {
   task.fileMeta = task.fileMeta || {}
-  if (!task.files.includes(rel)) {
-    task.files.push(rel)
-    if (task.files.length > MAX_FILES_PER_TASK) {
-      const dropped = task.files.shift()
-      delete task.fileMeta[dropped]
-    }
-  }
+  if (!task.files.includes(rel)) task.files.push(rel)
   const m = task.fileMeta[rel] || {}
   m.n = (m.n || 0) + 1 // 兼容旧字段：读+写总数（保留，避免老任务语义漂移）
   // 读/写分计数（先只采集，不消费 —— 排序与注入仍只用 lastWriteAt/lastReadAt）
@@ -157,6 +153,12 @@ export function touchTaskFile(task, rel, kind, now) {
   m.lastReadAt = now
   task.fileMeta[rel] = m
   task.files = hotSortFiles(task.files, task.fileMeta)
+  // 超限丢最冷的：列表已按热度降序，末尾即最冷。旧代码在**重排前** shift()，
+  // 而那时 files 本身就是热序，shift 恰好把最热的那个文件（刚写的）丢掉、留下最冷的。
+  while (task.files.length > MAX_FILES_PER_TASK) {
+    const dropped = task.files.pop()
+    delete task.fileMeta[dropped]
+  }
 }
 
 /**

package/src/store.js

@@ -17,6 +17,14 @@ const SHARDS_DIR = 'shards'
 const storeCache = new Map()
 const STORE_CACHE_MAX = 32
 
+/** 已就"无法迁移的旧 store"告警过的目录：避免每次 load() 都刷一行。 */
+const migrationWarned = new Set()
+
+/** 纯对象判定（排除 null / 数组）：磁盘读入的 JSON 形状校验统一走它。 */
+function isRecord(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
 function loadJson(filePath, fallback) {
   let raw
   try {
@@ -82,7 +90,9 @@ export class ProjectMemoryStore {
   load() {
     const key = path.resolve(this.dir)
     const hot = storeCache.get(key)
-    if (hot && hot !== this) return hot
+    // 缓存命中即返回：`hot === this` 时再读一遍盘会静默丢弃本实例尚未 save() 的变更
+    // （_loadSharded/_loadInsights 会重新赋值 experience/tasks/insights…）。
+    if (hot) return hot
     this._migrateLegacyIfNeeded()
     this._loadSharded()
     this._loadInsights()
@@ -114,9 +124,34 @@ export class ProjectMemoryStore {
     }
     const legacyEntriesPath = path.join(this.dir, ENTRIES_FILE)
     if (!existsSafe(legacyEntriesPath)) return
-    const index = loadJson(path.join(this.dir, INDEX_FILE), {})
-    const files = index.files || {}
-    const entries = loadJson(legacyEntriesPath, {})
+    const legacyIndexPath = path.join(this.dir, INDEX_FILE)
+    // 先读两份旧文件：损坏的那份会在这里被 loadJson 备份为 .corrupt（保留现场）。
+    const index = loadJson(legacyIndexPath, null)
+    const entries = loadJson(legacyEntriesPath, null)
+    if (!isRecord(index) || !isRecord(entries)) {
+      const hasEntries = isRecord(entries) && Object.keys(entries).length > 0
+      if (!hasEntries) {
+        // entries 损坏（已备份）或本就是空的：没有可保护的数据，按空旧库收尾。
+        writeJsonAtomic(formatPath, { version: 2, layout: 'sharded' })
+        for (const stale of [legacyEntriesPath, legacyIndexPath]) {
+          try {
+            unlinkSync(stale)
+          } catch {
+            // already renamed away by corrupt backup, or gone; nothing to do
+          }
+        }
+        return
+      }
+      // index.json 是 entries.json → rel 的唯一映射。它缺失或损坏时继续迁移，会写出 0 个
+      // shard、打上 v2 标记、再把**完好的** entries.json 删掉——等于一次静默的数据清空。
+      // 保留现场，不写 format 标记，等 index.json 修好后再迁（每次进程只提示一次）。
+      if (!migrationWarned.has(this.dir)) {
+        migrationWarned.add(this.dir)
+        console.error(`[dsh-project-memory] legacy store at ${this.dir} has ${ENTRIES_FILE} but no readable ${INDEX_FILE}; migration skipped to protect it`)
+      }
+      return
+    }
+    const files = isRecord(index.files) ? index.files : {}
     const orphans = Object.keys(entries).filter((rel) => !(rel in files))
     if (orphans.length) {
       console.error(
@@ -147,9 +182,11 @@ export class ProjectMemoryStore {
     }
     for (const name of shardNames) {
       const shard = loadJson(path.join(this.dir, SHARDS_DIR, name), null)
-      if (!shard || typeof shard.relPath !== 'string' || !shard.record) continue
+      if (!shard || typeof shard.relPath !== 'string' || !isRecord(shard.record)) continue
       this.files[shard.relPath] = shard.record
-      this.entries[shard.relPath] = shard.entries || []
+      // 畸形 shard（entries 被写成对象/null）不能让 allEntries() 在 `for…of` 上抛错，
+      // 否则一个坏文件会拖垮整个进程的每一次读取。
+      this.entries[shard.relPath] = Array.isArray(shard.entries) ? shard.entries.filter(isRecord) : []
     }
     this.experience = loadJson(path.join(this.dir, EXPERIENCE_FILE), [])
     this.tasks = loadJson(path.join(this.dir, TASKS_FILE), [])
@@ -165,7 +202,10 @@ export class ProjectMemoryStore {
   // migratedAt 落盘保证跨进程/崩溃幂等。销毁式收敛放到 recall 统一 PR。
   _loadInsights() {
     const doc = loadJson(path.join(this.dir, INSIGHTS_FILE), null)
-    this.insights = doc && typeof doc === 'object' && Array.isArray(doc.items) ? doc : { version: 1, migratedAt: null, items: [] }
+    this.insights = isRecord(doc) && Array.isArray(doc.items)
+      // items 里混进 null/非对象（手改或旧版写入）会让迁移与召回逐个 `.title` 抛错——过滤掉。
+      ? { ...doc, items: doc.items.filter(isRecord) }
+      : { version: 1, migratedAt: null, items: [] }
     this._migrateExperienceToInsights()
     // PR3：v1 → v2 懒回填派生 trigger（纯确定性、幂等；不调用模型，不改写已有字段）
     if (backfillDerivedTriggers(this.insights)) this._dirtyInsights = true
@@ -551,15 +591,14 @@ export class ProjectMemoryStore {
     return result
   }
 
-  applyFileUpdate(relPath, { expectedHash, hash, entries, meta, deleted, type, size }) {
-    const cur = this.fileRecord(relPath)
-    if (!deleted && (cur?.sha256 ?? null) !== (expectedHash ?? null)) {
-      return { skipped: true }
-    }
-    if (deleted) {
-      this.removeFile(relPath)
-      return { ok: true }
-    }
+  /**
+   * 写入一条文件更新，以 expectedHash 做 CAS。
+   * @returns {boolean} true = 已写入；false = 文件自扫描后又被改动，本次拒绝
+   *   （调用方让该条目保持未落快照，下一轮重试）。
+   * 移除条目不经过这里：调用方在 commit 里直接 removeFile（见 index-pipeline.js）。
+   */
+  applyFileUpdate(relPath, { expectedHash, hash, entries, type, size }) {
+    if ((this.fileRecord(relPath)?.sha256 ?? null) !== (expectedHash ?? null)) return false
     this.markFile(relPath, {
       sha256: hash,
       size,
@@ -567,7 +606,7 @@ export class ProjectMemoryStore {
       indexedAt: new Date().toISOString(),
     })
     this.setEntries(relPath, entries)
-    return { ok: true }
+    return true
   }
 }
 

package/src/symbols.js

@@ -144,18 +144,57 @@ function extractTypeSignature(line) {
   return sig
 }
 
-function extractInterfaceOrType(line) {
-  // interface User { name: string; age: number }
-  const ifaceMatch = line.match(/^interface\s+(\w+)\s*(?:extends\s+[^{]+)?\s*\{([^}]*)\}/)
-  if (ifaceMatch) {
-    return `{ ${ifaceMatch[2].trim()} }`
+function braceDelta(s) {
+  let d = 0
+  for (const ch of s) {
+    if (ch === '{') d++
+    else if (ch === '}') d--
   }
-  // type UserMap = Map<string, User>
-  const typeMatch = line.match(/^type\s+(\w+)\s*=\s*([^;{]+)/)
-  if (typeMatch) {
-    return `= ${typeMatch[2].trim()}`
+  return d
+}
+
+/**
+ * 读取一条 interface / type 声明，支持 `export`（含 `declare`）与多行形态。
+ * 旧实现要求 `^interface`（不吃 export）且 `}` 必须在本行，于是
+ * `export interface X {…}`、任何多行 interface、`export type X = …` 在 L1 正则扫描器里
+ * 全都产出 0 个符号（TS 增强器可用时才被补回来；没有 typescript 的项目就彻底看不到）。
+ * @returns {{kind: 'interface'|'type', name: string, text: string, endIdx: number} | null}
+ */
+function readTypeDeclaration(rawLines, startIdx) {
+  const first = rawLines[startIdx].trim()
+  const m = first.match(/^(?:export\s+)?(?:declare\s+)?(interface|type)\s+([A-Za-z_$][\w$]*)/)
+  if (!m) return null
+  const kind = m[1]
+  const parts = [first]
+  let depth = braceDelta(first)
+  let endIdx = startIdx
+  const complete = () => (kind === 'interface'
+    ? depth <= 0 && parts[parts.length - 1].includes('}')
+    : depth <= 0 && /[;}]/.test(parts[parts.length - 1]))
+  for (let j = startIdx + 1; j < rawLines.length && j - startIdx <= 20 && !complete(); j++) {
+    const t = rawLines[j].trim()
+    if (!t) {
+      if (depth <= 0) break
+      parts.push(t)
+      endIdx = j
+      continue
+    }
+    // 归零后遇到下一条声明开头就收尾（TS 的 type 别名常不写分号）
+    if (depth <= 0 && j > startIdx && /^(?:export\s+)?(?:declare\s+)?(?:interface|type|function|class|const|let|var|import|enum)\b/.test(t)) break
+    parts.push(t)
+    depth += braceDelta(t)
+    endIdx = j
   }
-  return ''
+  return { kind, name: m[2], text: parts.join(' '), endIdx }
+}
+
+function formatTypeDeclaration({ kind, text }) {
+  if (kind === 'interface') {
+    const body = text.match(/\{([\s\S]*)\}/)
+    return body ? `{ ${body[1].replace(/\s+/g, ' ').trim()} }` : ''
+  }
+  const eq = text.match(/=\s*([\s\S]+?);?\s*$/)
+  return eq ? `= ${eq[1].replace(/\s+/g, ' ').trim()}` : ''
 }
 
 function extractOverloads(masked, startIdx) {
@@ -226,6 +265,7 @@ function scanJsLike(masked, relPath, rawLines) {
   const symbols = []
   let prevOpensBlock = false
   for (let i = 0; i < masked.length; i++) {
+    const declStart = i // 多行声明会推进 i，符号行号要记声明的**首行**
     const rawText = rawLines[i].trim()
     const maskedText = masked[i].trim()
     if (!rawText) continue
@@ -233,13 +273,12 @@ function scanJsLike(masked, relPath, rawLines) {
     let matched = null
     let joinedText = null
     
-    // Check for interface / type alias first (on raw line, not masked)
-    const ifaceSig = extractInterfaceOrType(rawText)
-    if (ifaceSig) {
-      const nameMatch = rawText.match(/^(?:export\s+)?(?:interface|type)\s+(\w+)/)
-      if (nameMatch) {
-        matched = { name: nameMatch[1], kind: 'interface', typeSig: ifaceSig }
-      }
+    // interface / type（支持 export 与多行；没有 TS 增强器时这是唯一来源）
+    const typeDecl = readTypeDeclaration(rawLines, i)
+    if (typeDecl) {
+      const sig = formatTypeDeclaration(typeDecl)
+      if (sig) matched = { name: typeDecl.name, kind: typeDecl.kind, typeSig: sig }
+      i = typeDecl.endIdx
     }
     
     if (!matched) {
@@ -294,7 +333,7 @@ function scanJsLike(masked, relPath, rawLines) {
         if (overloads.length > 1) matched.overloads = overloads
       }
       
-      symbols.push(buildSymbol(matched, relPath, rawLines[i], i + 1))
+      symbols.push(buildSymbol(matched, relPath, rawLines[declStart], declStart + 1))
     }
     
     prevOpensBlock = masked[i].trim().endsWith('{')
@@ -433,7 +472,7 @@ function buildSymbol(matched, relPath, rawLine, lineNo) {
 export function scanSymbols(a, b, c) {
   // Backward compatible: old signature (filePath, content) or new (relPath, filePath, content)
   const [relPath, filePath, content] = c === undefined ? [a, a, b] : [a, b, c]
-  const ext = relPath.slice(relPath.lastIndexOf('.'))
+  const ext = relPath.slice(relPath.lastIndexOf('.')).toLowerCase()
   const lines = content.split(/\r?\n/)
   if (JS_LIKE.has(ext)) return scanJsLike(maskTokens(lines, JS_MASKER), relPath, lines)
   if (PYTHON.has(ext)) return scanPython(maskTokens(lines, PY_MASKER), relPath, lines)

package/src/tools/forget.js

@@ -1,5 +1,5 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import { memoryRootFor, resolveIndexRoot } from '../util/fs.js'
+import { assertIndexRoot, memoryRootFor, resolveIndexRoot } from '../util/fs.js'
 import { ProjectMemoryStore } from '../store.js'
 
 export function forgetTool(config) {
@@ -24,6 +24,7 @@ export function forgetTool(config) {
     },
     async execute(args, exec) {
       const root = resolveIndexRoot(exec, args.root)
+      assertIndexRoot(root, args.root || root)
       const memoryDir = memoryRootFor(root, config.memoryDir)
       const store = new ProjectMemoryStore(memoryDir).load()
       return store.commit((s) => {

package/src/tools/index-doc.js

@@ -2,6 +2,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import path from 'node:path'
 import { assertReadableFile, memoryRootFor, sha256OfFile, storeKey } from '../util/fs.js'
 import { buildDocEntries } from '../doc-pipeline.js'
+import { docEntriesNeedBackfill } from '../doc-index.js'
 import { linkEntries } from '../link.js'
 import { ProjectMemoryStore } from '../store.js'
 import { findProjectRoot } from '../lazy.js'
@@ -38,7 +39,9 @@ export function indexDocTool(ctx, config) {
       const rel = storeKey(path.relative(root, filePath).split(path.sep).join('/'))
       const { hash, size } = await sha256OfFile(filePath)
       const existing = store.fileRecord(rel)
-      if (existing && existing.sha256 === hash) {
+      // 与 index_repo/watch/lazy 同一条判据：哈希未变但旧条目缺 terms 时仍要重抽一次（一次性回填）。
+      // 少了这一步，terms 回填就是"路径相关"的——只有走 index_repo 才生效。
+      if (existing && existing.sha256 === hash && !docEntriesNeedBackfill(store.entries[rel])) {
         return `Skipped (unchanged): ${rel}\nAlready indexed with ${(store.entries[rel] || []).length} entry/entries.`
       }