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

package/src/tools/lesson-tools.js

@@ -11,7 +11,7 @@ function sessionIdOf(exec) {
 }
 
 export function lessonTool(config) {
-  const kindDesc = `insight 语义：lesson(曾踩坑/纠偏, pattern→fix) | decision(权衡选型, choice→reason) | procedure(多步指南, steps+可选 trigger) | experience(problem→solution，v0.4 兼容)。默认 lesson。`
+  const kindDesc = `insight 语义：lesson(曾踩坑/纠偏, pattern→fix) | decision(权衡选型, choice→reason) | procedure(多步指南, steps) | experience(problem→solution，v0.4 兼容)。默认 lesson。所有 kind 都可带 trigger：命中即在动手前确定性注入。`
   const scopeDesc =
     '作用域：task(任务私有，随任务归档，不进共享注入) | project(项目资产) | global(个人能力库，跨项目，建议配 trigger 关键词以便将来技能命中)。' +
     '解析顺序：显式 scope > task_id > 当前绑定任务 > project。'
@@ -37,9 +37,14 @@ export function lessonTool(config) {
         properties: {
           keywords: { type: 'array', items: { type: 'string' } },
           symbols: { type: 'array', items: { type: 'string' } },
+          actions: { type: 'array', items: { type: 'string' } },
+          paths: { type: 'array', items: { type: 'string' } },
           scope: { type: 'array', items: { type: 'string' } },
         },
-        description: 'kind=procedure: "作为 Skill" 的触发关键词（keywords/symbols + scope tags）',
+        description:
+          'authored trigger（所有 kind 通用）：命中即在**动手前**确定性注入本条。' +
+          'keywords/symbols 匹配人类消息与工具参数；actions 用归一 id（git-commit / npm-publish / go-public / deploy / delete / migrate …）；' +
+          'paths 用 glob（README* / CHANGELOG* / .gitignore）；scope 按项目画像 tags 过滤。留空则只可能作为统计提示注入。',
       },
       task_id: { type: 'string', description: '目标任务 id（scope 缺省时优先于绑定任务）' },
       files: { type: 'array', items: { type: 'string' }, description: '关联文件（项目相对路径）' },

package/src/tools/query-memory.js

@@ -3,9 +3,10 @@ import path from 'node:path'
 import { memoryRootFor, resolveIndexRoot } from '../util/fs.js'
 import { ProjectMemoryStore, storeOverview } from '../store.js'
 import { expandQuery } from '../llm.js'
-import { rankEntriesMergedScored, rankExperienceScored, rankEntriesStreaming } from '../util/search.js'
+import { resolveRoute } from '../llm-route.js'
+import { GlobalStore, cfgInsight, defaultGlobalFile } from '../insight-store.js'
+import { recallItems } from '../recall.js'
 import { truncate } from '../util/text.js'
-
 function toAbs(root, rel) {
   return path.isAbsolute(rel) ? rel : path.join(root, rel)
 }
@@ -14,9 +15,10 @@ export function queryMemoryTool(ctx, config) {
   return defineTool({
     name: 'query_memory',
     description:
-      'Search persistent project memory: doc summaries and code symbol tables (indexed via index_doc/index_repo) ' +
-      'plus experience notes (problem -> solution, saved via remember). Every hit returns its source path and line so ' +
-      'you can verify by reading the real file. Docs are cross-linked to the code symbols they mention. ' +
+      'Search persistent project memory: doc summaries and code symbol tables (indexed via index_doc/index_repo), ' +
+      'experience notes (problem -> solution, saved via remember) and insights (lessons / decisions / procedures, ' +
+      'saved via save_lesson). Every hit returns its source path and line, or its insight id, so you can verify. ' +
+      'Docs are cross-linked to the code symbols they mention. ' +
       'Use BEFORE grepping when you need orientation, a spec constraint, or a past decision.',
     parameters: {
       query: {
@@ -30,8 +32,8 @@ export function queryMemoryTool(ctx, config) {
       },
       type: {
         type: 'string',
-        enum: ['all', 'doc', 'symbol', 'experience', 'task'],
-        description: 'Which memory layer to search. Default "all". "task" searches task records (title/steps/files).',
+        enum: ['all', 'doc', 'symbol', 'experience', 'insight', 'task'],
+        description: 'Which memory layer to search. Default "all". "insight" searches lessons / decisions / procedures; "task" searches task records.',
       },
       limit: {
         type: 'number',
@@ -49,25 +51,47 @@ export function queryMemoryTool(ctx, config) {
       const limit = Math.max(1, Math.min(Number(args.limit) || 8, 20))
 
       const queries = config.llmQueryExpansion
-        ? await expandQuery(ctx.llm, args.query, config.expansionCount)
+        ? await expandQuery(ctx.llm, args.query, config.expansionCount, { route: resolveRoute(exec, config) })
         : [args.query]
       const symbolById = new Map()
       for (const e of store.allEntries()) {
         if (e.type === 'symbol') symbolById.set(e.id, e)
       }
 
-      const idf = store.getIdfCache()
+      // 会话绑定决定 task 级 insight 的可见性；global 级始终可见。
+      const sessionId = exec?.agent?.session?.id
+      const boundTaskId = sessionId && typeof store.getBoundTaskId === 'function' ? store.getBoundTaskId(sessionId) : null
+      const globalStore = new GlobalStore(cfgInsight(config).globalFile || defaultGlobalFile()).load()
+      const wantMemory = type === 'all' || type === 'doc' || type === 'symbol'
+      const wantInsight = type === 'all' || type === 'insight'
+      // 一次 recall 覆盖全部层：doc/symbol/experience/insight 共用同一个检索核心（src/recall.js）。
+      const recalled = recallItems({
+        store,
+        globalStore,
+        queries,
+        boundTaskId,
+        limit,
+        layers: [
+          ...(wantMemory ? (type === 'symbol' ? ['symbol'] : type === 'doc' ? ['doc'] : ['doc', 'symbol']) : []),
+          ...(wantInsight ? ['insight'] : []),
+          ...(type === 'all' || type === 'experience' ? ['experience'] : []),
+        ],
+      })
 
       const lines = []
-      if (type === 'all' || type === 'doc' || type === 'symbol') {
-        const pool = type === 'all' ? store.allEntries() : store.allEntries().filter((e) => e.type === type)
-        const scored = rankEntriesStreaming(pool, queries, idf, limit)
-        if (scored.length) {
-          const top = scored[0].score || 1
+      if (wantMemory) {
+        // doc/symbol 同源同尺度：合并后按加权分排序（规范段提权已计入 weightedScore）
+        const memHits = recalled.layers
+          .filter((l) => l.layer === 'doc' || l.layer === 'symbol')
+          .flatMap((l) => l.hits)
+          .sort((a, b) => b.weightedScore - a.weightedScore)
+          .slice(0, limit)
+        if (memHits.length) {
+          const top = memHits[0].weightedScore || 1
           lines.push(`## Memory (${type === 'all' ? 'docs + symbols' : type})`)
-          for (const { entry: e, score } of scored) {
+          for (const { item: e, weightedScore } of memHits) {
             const absSource = e.sourceLine ? `${toAbs(root, e.sourcePath)}:${e.sourceLine}` : toAbs(root, e.sourcePath)
-            const rel = Math.round((score / top) * 100)
+            const rel = Math.round((weightedScore / top) * 100)
             let summaryLine = `- ${e.summary}`
             if (e.type === 'doc' && e.blindSpots) {
               const queryTokens = queries.flatMap(q => q.split(/[\s\-_]+/)).map(t => t.toLowerCase()).filter(Boolean)
@@ -77,7 +101,9 @@ export function queryMemoryTool(ctx, config) {
                 summaryLine += `\n- ⚠️ 摘要未覆盖：${e.blindSpots.replace(/^\s*\/\/\s*未覆盖[:：]\s*/, '')}。建议读原文 ${absSource}`
               }
             }
-            lines.push(`### ${e.title} (score: ${rel})\n- source: ${absSource}\n${summaryLine}`)
+            // 条目状态占位（可证伪状态机落地前恒为 exact）。
+            // 先立字段，后续状态机到位时只改值、不改输出契约。
+            lines.push(`### ${e.title} (score: ${rel})\n- source: ${absSource}\n- status: ${e.status || 'exact'}\n${summaryLine}`)
             if (e.type === 'doc' && Array.isArray(e.linkedSymbols) && e.linkedSymbols.length) {
               const refs = e.linkedSymbols.slice(0, 5).map((id) => {
                 const s = symbolById.get(id)
@@ -88,15 +114,28 @@ export function queryMemoryTool(ctx, config) {
           }
         }
       }
+      if (wantInsight) {
+        const bucket = recalled.layers.find((l) => l.layer === 'insight')
+        if (bucket && bucket.hits.length) {
+          lines.push('## Insights (lessons / decisions / procedures)')
+          for (const { item: e, rel } of bucket.hits) {
+            const scope = e.scope ? `, scope: ${e.scope}` : ''
+            const files = e.files && e.files.length ? `\n- files: ${e.files.map((f) => toAbs(root, f)).join(', ')}` : ''
+            const conf = typeof e.confidence === 'number' ? `\n- confidence: ${e.confidence}` : ''
+            lines.push(
+              `### ${e.title} (score: ${Math.round(rel * 100)}, kind: ${e.kind}${scope}, id: ${e.insightId})\n- ${e.summary}${files}${conf}`,
+            )
+          }
+        }
+      }
       if (type === 'all' || type === 'experience') {
-        const scoredExp = rankExperienceScored(store.experience, queries, limit)
-        if (scoredExp.length) {
-          const expTop = scoredExp[0].score || 1
+        const expBucket = recalled.layers.find((l) => l.layer === 'experience')
+        if (expBucket && expBucket.hits.length) {
           lines.push(`## Experience (past problems -> solutions)`)
-          for (const { item: e, score } of scoredExp) {
+          for (const { item: e, rel } of expBucket.hits) {
             const source = e.sourceFile ? ` (source: ${toAbs(root, e.sourceFile)})` : ''
             lines.push(
-              `### Problem: ${e.problem} (score: ${Math.round((score / expTop) * 100)}, id: ${e.id})\n- solution: ${e.solution}${source}\n- updated: ${e.updatedAt}`,
+              `### Problem: ${e.problem} (score: ${Math.round(rel * 100)}, id: ${e.id})\n- solution: ${e.solution}${source}\n- updated: ${e.updatedAt}`,
             )
           }
         }
@@ -132,9 +171,11 @@ export function queryMemoryTool(ctx, config) {
         const hint =
           type === 'experience'
             ? 'Note a fix with remember so it can be recalled next time.'
-            : type === 'all'
-              ? 'Index it first with index_repo / index_doc, or note a fix with remember.'
-              : 'Index it first with index_repo / index_doc.'
+            : type === 'insight'
+              ? 'Save a lesson / decision / procedure with save_lesson so it can be recalled next time.'
+              : type === 'all'
+                ? 'Index it first with index_repo / index_doc, or note a fix with remember or save_lesson.'
+                : 'Index it first with index_repo / index_doc.'
         const tail =
           overview.files === 0
             ? '. The store has never been indexed.'

package/src/tools/task-tools.js

@@ -4,6 +4,7 @@ import { ProjectMemoryStore } from '../store.js'
 import { truncate } from '../util/text.js'
 import { genTaskId, hash8, adoptStepsToSession, shouldAdoptToHost } from '../setup/taskbridge.js'
 import { fireReflect } from '../reflection-pipeline.js'
+import { resolveRoute } from '../llm-route.js'
 import { createHash } from 'node:crypto'
 
 function sessionIdOf(exec) {
@@ -137,7 +138,7 @@ export function selectTaskTool(config, host) {
 
       // 反思钩子：切走旧任务时异步收割（默认关，零成本；失败只记日志）
       if (prevBound && prevBound !== task.id) {
-        fireReflect(config, host, root, prevBound, 'switch-away')
+        fireReflect(config, host, root, prevBound, 'switch-away', resolveRoute(exec, config))
       }
 
       const card = {
@@ -191,7 +192,7 @@ export function archiveTaskTool(config, host) {
       task.updatedAt = new Date().toISOString()
       store.save()
       // 反思钩子：归档即收割最终教训（默认关）
-      fireReflect(config, host, root, args.taskId, 'archive')
+      fireReflect(config, host, root, args.taskId, 'archive', resolveRoute(exec, config))
       return truncate(JSON.stringify({ success: true, archived: true, hint: '已归档，select_task 可恢复' }), config.maxOutputChars)
     },
   })

package/src/tools/watch-repo.js

@@ -1,6 +1,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import path from 'node:path'
-import { memoryRootFor, resolveIndexRoot } from '../util/fs.js'
+import { existsSync } from 'node:fs'
+import { isUnwatchableRoot, memoryRootFor, resolveIndexRoot } from '../util/fs.js'
 import { ProjectMemoryStore } from '../store.js'
 
 export function watchRepoTool(watchManager, config) {
@@ -27,6 +28,14 @@ export function watchRepoTool(watchManager, config) {
     },
     async execute(args, exec) {
       const root = path.resolve(args.root)
+      // 不存在的根不写进 watchlist：watch 每轮会 commit → save → mkdirSync，把它重新造出来
+      if (args.watch !== false && !existsSync(root)) {
+        return `Not watching: ${root} does not exist.`
+      }
+      // 文件系统根 / 共享临时目录不整体监听（子目录允许）：会把无关程序和测试夹具的临时文件全扫进来
+      if (args.watch !== false && isUnwatchableRoot(root)) {
+        return `Refusing to watch ${root}: it is the filesystem root or the shared temp directory. Pass a project subdirectory instead.`
+      }
       const memoryDir = memoryRootFor(root, config.memoryDir)
       const sessionRoot = resolveIndexRoot(exec)
       const sessionMemoryDir = memoryRootFor(sessionRoot, config.memoryDir)

package/src/util/fs.js

@@ -1,6 +1,7 @@
 import { accessSync, constants, readdirSync, readFileSync, statSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { createHash } from 'node:crypto'
+import os from 'node:os'
 import path from 'node:path'
 
 export function assertReadableFile(filePath, maxFileSizeMb) {
@@ -23,6 +24,33 @@ export function assertReadableFile(filePath, maxFileSizeMb) {
   return filePath
 }
 
+/** Windows-style absolute path (`D:\dir`, `C:/dir`) — not absolute on POSIX. */
+const WINDOWS_ABSOLUTE_PATH = /^[A-Za-z]:[\\/]/
+
+/**
+ * 校验索引根目录：必须存在且是目录。
+ *
+ * 之前 `index_repo` / `autoIndexOnFirstUse` 只做 `path.resolve()`：在 Linux/macOS 上传入
+ * Windows 风格路径（如 `D:\project\foo`）会被解析成相对路径 `<cwd>/D:\project\foo`，
+ * 随后 store 的 `mkdirSync` 把这个字面量目录（连同其 `.dsh-project-memory`）真的建出来。
+ * 这里在写盘前拒绝不存在的根；`requested` 只用于在报错里点明“这看起来是 Windows 路径”。
+ */
+export function assertIndexRoot(root, requested = root) {
+  let stats
+  try {
+    stats = statSync(root)
+  } catch {
+    const hint = process.platform !== 'win32' && WINDOWS_ABSOLUTE_PATH.test(String(requested))
+      ? ` The argument looks like a Windows path, which is not absolute on ${process.platform}.`
+      : ''
+    throw new Error(`Index root does not exist: ${root}.${hint}`)
+  }
+  if (!stats.isDirectory()) {
+    throw new Error(`Index root is not a directory: ${root}`)
+  }
+  return root
+}
+
 export function sha256OfBuffer(buf) {
   return createHash('sha256').update(buf).digest('hex')
 }
@@ -117,6 +145,19 @@ export function memoryRootFor(indexRoot, memoryDir) {
   return path.join(indexRoot, memoryDir)
 }
 
+/**
+ * 不该整体当「项目根」监听的目录：文件系统根，以及共享的 OS 临时目录。
+ * 监听后者会把无关程序（以及插件自己的测试夹具）的临时文件全扫进来，而且只要读过
+ * `/tmp` 下任意一个文件，findProjectRoot 的兜底就会把根解析成 `/tmp` 并自我固化。
+ * 根的**子目录**不受影响——项目放在临时目录的子目录里照常可监听。
+ */
+export function isUnwatchableRoot(root) {
+  if (typeof root !== 'string' || !root) return true
+  const abs = path.resolve(root)
+  if (abs === path.parse(abs).root) return true
+  return abs === path.resolve(os.tmpdir())
+}
+
 export function resolveIndexRoot(exec, explicitRoot) {
   if (explicitRoot && explicitRoot.trim()) return path.resolve(explicitRoot)
   const sessionCwd = exec?.agent?.session?.header?.cwd

package/src/util/search.js

@@ -131,6 +131,8 @@ export function weightedFieldText(entry) {
   for (let i = 0; i < 5; i++) parts.push(entry.title || '')
   parts.push((entry.keywords || []).join(' '))
   parts.push(entry.summary || '')
+  // 结构词项：覆盖整个 chunk 的字面词项，把「只有前 300 字符可检索」补回来（索引期零 LLM）
+  parts.push(entry.terms || '')
   parts.push(entry.sourcePath || '')
   return parts.join(' ')
 }

package/src/util/text.js

@@ -2,4 +2,17 @@ export function truncate(text, maxChars) {
   if (typeof text !== 'string') return String(text)
   if (text.length <= maxChars) return text
   return text.slice(0, maxChars) + `\n\n...[truncated at ${maxChars} chars]`
+}
+
+export const MAX_SUMMARY = 300
+
+/** 注入用短摘要：压平空白，按句子边界截断到 max 字符。纯函数，无 LLM。 */
+export function summarizeText(text, max = MAX_SUMMARY) {
+  const flat = String(text || '').replace(/\s+/g, ' ').trim()
+  if (!flat) return ''
+  if (flat.length <= max) return flat
+  const clip = max - 1
+  const clipped = flat.slice(0, clip)
+  const lastBreak = Math.max(clipped.lastIndexOf('。'), clipped.lastIndexOf('.'), clipped.lastIndexOf(';'))
+  return lastBreak > clip * 0.4 ? clipped.slice(0, lastBreak + 1) : clipped + '…'
 }

package/src/watch.js

@@ -1,7 +1,8 @@
 import { existsSync, statSync } from 'node:fs'
 import path from 'node:path'
-import { isSupportedCode, isSupportedDoc, memoryRootFor, readFileForIndex, relativePath, storeKey, walkDir } from './util/fs.js'
+import { isSupportedCode, isSupportedDoc, isUnwatchableRoot, memoryRootFor, readFileForIndex, relativePath, storeKey, walkDir } 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 { ProjectMemoryStore } from './store.js'
@@ -21,17 +22,34 @@ export class WatchManager {
     // 用 load() 的返回值：storeCache 命中时 load() 返回的是缓存实例，忽略返回值会拿到空 store
     const store = new ProjectMemoryStore(memoryRootFor(cwd, this.config.memoryDir)).load()
     if (existsSync(store.dir)) {
-      for (const root of store.watchlist) {
-        if (typeof root === 'string' && root) this.addRoot(root)
+      let dropped = 0
+      for (const root of [...store.watchlist]) {
+        if (typeof root !== 'string' || !root) continue
+        // 自愈剔除两类条目：已不存在的根（每轮白跑，还会把目录重新 mkdir 出来），
+        // 以及不该整体监听的文件系统根 / 共享临时目录（会把别人和测试的临时文件全扫进来）。
+        if (!existsSync(root) || isUnwatchableRoot(root)) {
+          store.removeWatch(root)
+          dropped++
+          continue
+        }
+        this.addRoot(root)
       }
+      if (dropped) store.save()
     }
   }
 
   addRoot(root) {
+    // 根目录不存在就拒绝：否则每轮 poll 都会 commit → save → mkdirSync，
+    // 把一条历史遗留、已被删除的 watchlist 条目重新「创建」出来。
+    if (!existsSync(root)) return false
+    // 文件系统根 / 共享临时目录不整体监听（子目录允许）。
+    if (isUnwatchableRoot(root)) return false
     if (!this.roots.has(root)) {
       this.roots.set(root, {
         store: new ProjectMemoryStore(memoryRootFor(root, this.config.memoryDir)).load(),
         snapshot: {},
+        // rel → 上次已上报的错误信息。坏文件每轮都会重试，逐轮打印会刷屏。
+        failures: new Map(),
       })
       return true
     }
@@ -105,14 +123,16 @@ export class WatchManager {
       // 单次读盘：同一 buffer 供哈希与正文使用
       const { hash, buffer } = readFileForIndex(filePath)
       const existing = state.store.fileRecord(rel)
-      if (existing && existing.sha256 === hash) continue
+      // 旧 store 的 doc 条目缺 terms → 一次性回填（即使哈希未变）
+      const needsBackfill = isSupportedDoc(ext) && docEntriesNeedBackfill(state.store.entries[rel])
+      if (existing && existing.sha256 === hash && !needsBackfill) continue
 
       try {
         let entries
         if (isSupportedCode(ext)) {
           entries = scanSymbols(rel, filePath, buffer.toString('utf8'))
         } else {
-          entries = await buildDocEntries(this.ctx.llm, rel, filePath, {
+          entries = await buildDocEntries(rel, filePath, {
             chunkChars: this.config.chunkChars,
             maxChunks: this.config.maxChunksPerFile,
             maxFileSizeMb: this.config.maxFileSizeMb,
@@ -122,15 +142,22 @@ export class WatchManager {
             // Dump file - update snapshot so we don't re-hash next poll, but don't index
             fileUpdates.push({ rel, expectedHash: state.store.fileRecord(rel)?.sha256, deleted: true, _sig: sig })
             changed++
+            state.failures?.delete(rel)
             continue
           }
         }
         fileUpdates.push({ rel, expectedHash: state.store.fileRecord(rel)?.sha256, hash, size: stats.size, entries, type: isSupportedCode(ext) ? 'code' : 'doc', _sig: sig })
         changed++
+        state.failures?.delete(rel)
       } catch (err) {
         // Index failed - rollback snapshot so next poll retries
         delete state.snapshot[rel]
-        console.error(`[dsh-project-memory] re-index failed for ${rel}: ${err.message}`)
+        // 同一个文件的同一个错误只上报一次：坏文件每轮都会重试，逐轮 console.error 会刷屏
+        if (!state.failures) state.failures = new Map()
+        if (state.failures.get(rel) !== err.message) {
+          state.failures.set(rel, err.message)
+          console.error(`[dsh-project-memory] re-index failed for ${rel}: ${err.message}`)
+        }
         continue
       }
     }