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

package/src/store.js

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from 'node:crypto'
 import { mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { rankEntries, rankExperience, tokenize, tokenizeRaw, extractCjkPhrases, makeSearchText } from './util/search.js'
+import { backfillDerivedTriggers } from './readiness.js'
 
 const FORMAT_FILE = 'format.json'
 const INDEX_FILE = 'index.json'
@@ -166,6 +167,8 @@ export class ProjectMemoryStore {
     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._migrateExperienceToInsights()
+    // PR3：v1 → v2 懒回填派生 trigger（纯确定性、幂等；不调用模型，不改写已有字段）
+    if (backfillDerivedTriggers(this.insights)) this._dirtyInsights = true
   }
 
   _migrateExperienceToInsights() {
@@ -244,8 +247,22 @@ export class ProjectMemoryStore {
   }
 
   save() {
-    mkdirSync(this.dir, { recursive: true })
+    // 没有脏数据就不落盘。watch 每轮对每个根都无条件 commit → save；照旧执行的话，
+    // 末尾的 `_version++` + `_idfCache = null` 会打在跨实例共享的 store 上，
+    // 等于每 15 秒清空一次 IDF 缓存，废掉查询侧的 IDF 复用（v0.3.4 的 20x）。
+    const dirty =
+      this._dirtyShards.size > 0 ||
+      this._removedShards.size > 0 ||
+      this._dirtyExperience ||
+      this._dirtyInsights ||
+      this._dirtyTasks ||
+      this._dirtyBinding ||
+      this._dirtyWatch ||
+      !this._formatWritten
+    if (dirty) mkdirSync(this.dir, { recursive: true })
+    // 崩溃遗留的 *.tmp 无论有没有脏数据都顺手清掉（两次 readdir，自带 try/catch）
     this.cleanStaleTmp()
+    if (!dirty) return
     if (!this._formatWritten) {
       writeJsonAtomic(path.join(this.dir, FORMAT_FILE), { version: 2, layout: 'sharded' })
       this._formatWritten = true
@@ -272,6 +289,8 @@ export class ProjectMemoryStore {
       this._dirtyExperience = false
     }
     if (this._dirtyInsights) {
+      // PR3：落盘即把格式标记推到 v2（v1 → v2 是纯增量：只多一个可选的 triggerDerived）
+      if (this.insights && this.insights.version !== 2) this.insights.version = 2
       writeJsonAtomic(path.join(this.dir, INSIGHTS_FILE), this.insights)
       this._dirtyInsights = false
     }

package/src/tools/index-repo.js

@@ -1,7 +1,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import path from 'node:path'
 import { statSync } from 'node:fs'
-import { isSupportedCode, isSupportedDoc, looksLikeDump, memoryRootFor, readFileForIndex, relativePath, storeKey, walkDir } from '../util/fs.js'
+import { assertIndexRoot, isSupportedCode, isSupportedDoc, looksLikeDump, 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'
@@ -10,6 +10,9 @@ import { ProjectMemoryStore } from '../store.js'
 import { onFileIndexed, isTypeScriptFile } from '../enhancer.js'
 
 export async function indexRepository(ctx, config, root, { reindex = false } = {}) {
+  // 先校验根目录：缺了它，下面 `new ProjectMemoryStore(...).load()` 的 save() 会把
+  // 不存在的 root 连同 .dsh-project-memory 一起 mkdirSync 出来。
+  assertIndexRoot(root)
   const memoryDir = memoryRootFor(root, config.memoryDir)
   const store = new ProjectMemoryStore(memoryDir).load()
 
@@ -147,6 +150,9 @@ export function indexRepoTool(ctx, config) {
     },
     async execute(args) {
       const root = path.resolve(args.root)
+      // 透传原始入参：Windows 风格路径在 POSIX 上会被 resolve 成 <cwd>/D:\...，
+      // 报错时要点明这是路径风格问题，而不是“目录被删了”。
+      assertIndexRoot(root, args.root)
       return indexRepository(ctx, config, root, { reindex: Boolean(args.reindex) })
     },
   })

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。'
@@ -35,11 +35,38 @@ export function lessonTool(config) {
         type: 'object',
         additionalProperties: false,
         properties: {
-          keywords: { type: 'array', items: { type: 'string' } },
+          when: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              ops: { type: 'array', items: { type: 'string' }, description: '归一动作 id：file-write / file-delete / shell-run / git-commit / git-push / release / npm-publish / deploy / migrate / render-doc / index-doc / read-image / fetch-web / run-bench / query-memory。' },
+              writes: { type: 'array', items: { type: 'string' }, description: '本次要【写】的项目相对路径（禁扩展名/泛名 glob）。' },
+              intents: { type: 'array', items: { type: 'string' }, description: '人类消息里剥离引用后的意图词（CJK ≥2 字、拉丁 ≥5 字符且不含 _ . /）。' },
+            },
+            description: '唯一触发面：三者取或。',
+          },
+          guard: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              paths: { type: 'array', items: { type: 'string' }, description: '收窄：写目标必须命中其中之一（自己不能触发）。' },
+              not_paths: { type: 'array', items: { type: 'string' } },
+              hosts: { type: 'array', items: { type: 'string' }, description: '例如 wsl（命令里出现 /mnt/* 或 powershell.exe）。' },
+              tags: { type: 'array', items: { type: 'string' }, description: '项目画像 tag 交集（画像未知时不过滤）。' },
+            },
+            description: '收窄条件：全部满足才注入。',
+          },
+          prevents: { type: 'string', description: '准入条件：不知道这条，这一步会做错什么。写不出来 → 不该进自动注入。' },
+          keywords: { type: 'array', items: { type: 'string' }, description: '【旧字段】降级为 intents 与被动召回排序。' },
           symbols: { type: 'array', items: { type: 'string' } },
-          scope: { type: 'array', items: { type: 'string' } },
+          actions: { type: 'array', items: { type: 'string' }, description: '【旧字段】映射为 when.ops；死值丢弃并计入自检。' },
+          paths: { type: 'array', items: { type: 'string' }, description: '【旧字段】具体文件映射为 when.writes；扩展名/泛名 glob 丢弃。' },
+          scope: { type: 'array', items: { type: 'string' }, description: '【旧字段】默认忽略（值不在项目画像 tag 空间里）。' },
         },
-        description: 'kind=procedure: "作为 Skill" 的触发关键词（keywords/symbols + scope tags）',
+        description:
+          'authored trigger：命中即在**动手前**确定性注入。' +
+          'when = 唯一触发面（ops / writes / intents 取或）；guard 只能收窄；prevents 是准入条件。' +
+          '没有 when 的条目不会自动推送，只出现在记忆目录里供按需拉取。',
       },
       task_id: { type: 'string', description: '目标任务 id（scope 缺省时优先于绑定任务）' },
       files: { type: 'array', items: { type: 'string' }, description: '关联文件（项目相对路径）' },

package/src/tools/query-memory.js

@@ -4,9 +4,9 @@ import { memoryRootFor, resolveIndexRoot } from '../util/fs.js'
 import { ProjectMemoryStore, storeOverview } from '../store.js'
 import { expandQuery } from '../llm.js'
 import { resolveRoute } from '../llm-route.js'
-import { rankEntriesMergedScored, rankExperienceScored, rankEntriesStreaming } from '../util/search.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)
 }
@@ -15,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: {
@@ -31,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',
@@ -57,18 +58,40 @@ export function queryMemoryTool(ctx, config) {
         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)
@@ -91,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}`,
             )
           }
         }
@@ -135,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/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/watch.js

@@ -1,6 +1,6 @@
 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'
@@ -22,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
     }
@@ -125,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
       }
     }