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

package/src/insight-store.js

@@ -98,10 +98,12 @@ export function normalizeInsight(raw, extra = {}) {
     if (Array.isArray(raw[f]) && raw[f].length) ins[f] = [...new Set(raw[f].map((x) => String(x)))]
   }
   if (raw.trigger && typeof raw.trigger === 'object') {
-    const tr = { keywords: Array.isArray(raw.trigger.keywords) ? raw.trigger.keywords.map(String) : [] }
-    if (Array.isArray(raw.trigger.symbols)) tr.symbols = raw.trigger.symbols.map(String)
-    if (Array.isArray(raw.trigger.scope)) tr.scope = raw.trigger.scope.map(String)
-    if (tr.keywords.length) ins.trigger = tr
+    // 所有 kind 通用：keywords / symbols / actions / paths / scope（actions/paths 见 src/readiness.js）
+    const tr = {}
+    for (const f of ['keywords', 'symbols', 'actions', 'paths', 'scope']) {
+      if (Array.isArray(raw.trigger[f]) && raw.trigger[f].length) tr[f] = raw.trigger[f].map(String)
+    }
+    if (Object.keys(tr).length) ins.trigger = tr
   }
   return ins
 }

package/src/parsers/pdfjs-parser.js

@@ -25,6 +25,9 @@ const PDFJS_OPTIONS = {
   isEvalSupported: false,
   useWorkerFetch: false,
   useWorker: false,
+  // 0 = ERRORS。损坏/线性化缺失的 PDF 会让 pdf.js 打 "Warning: Indexing all PDF objects"
+  // 之类的告警——那是它自己的恢复路径，对使用者没有可操作性，静音。
+  verbosity: 0,
 }
 
 function buildMarkdown(pages) {

package/src/readiness.js

@@ -0,0 +1,224 @@
+/**
+ * 就绪引擎（push 侧）。
+ *
+ * recall 回答"记忆里有什么和这件事有关"；readiness 回答"动手之前必须知道什么"。
+ * 交付契约（设计核心）：
+ *   - **authored trigger = 确定性注入**：作者写下的 keywords / symbols / actions / paths 命中即在
+ *     动手前全文注入，优先级 1。可审计（返回 `why`），不参与任何相似度打分。
+ *   - **统计信号 = 提示态**：没有 trigger 的条目只能作为截断提示进入，优先级 2，且判据是
+ *     **层内相对阈值**（相对最高分），不是长度敏感的魔法常量。
+ *
+ * 两个窗口（忠于宿主契约：DSH 没有"工具执行前拦截"钩子，唯一能加上下文的缝是 agent/pre-step）：
+ *   - 先发窗口：人类消息里的意图词（"提交/发布/公开"）→ 动作 id 在模型规划动作之前就命中；
+ *   - 反应窗口：已观察到的 tool/call 参数（`git commit`、`npm publish`、改动的路径）走同一个匹配器。
+ *
+ * 纯函数、零依赖、不调用模型。
+ * @module dsh-project-memory/readiness
+ */
+
+/**
+ * 动作词典：动作 id → 匹配模式。命令形态与人类意图词都归一成同一套 id，
+ * 于是"你顺便提交一下"与 `git commit -m x` 对 trigger 是同一件事。
+ */
+export const ACTION_LEXICON = [
+  ['git-add', [/git\s+add\b/i]],
+  ['git-commit', [/git\s+commit\b/i, /提交/]],
+  ['git-push', [/git\s+push\b/i, /推送/]],
+  ['npm-publish', [/npm\s+publish\b/i, /发包/, /发布\s*到\s*npm/i]],
+  ['release', [/git\s+tag\b/i, /\brelease\b/i, /发版/, /发布版本/]],
+  ['go-public', [/公开/, /开源/, /对外/, /上线/]],
+  ['delete', [/rm\s+-rf\b/, /git\s+rm\b/, /删除/, /清理/]],
+  ['migrate', [/migrate\b/i, /迁移/]],
+  ['deploy', [/\bdeploy\b/i, /部署/]],
+]
+
+/** 带扩展名的路径 token（README.md、src/util/fs.js …）。 */
+const PATH_TOKEN = /(?:[A-Za-z0-9_.@-]+\/)*[A-Za-z0-9_.@-]+\.[A-Za-z][A-Za-z0-9]{0,7}\b/g
+/** 点开头的裸文件名（.gitignore、.npmrc …）。 */
+const DOTFILE_TOKEN = /(?:^|[\s"'`(])(\.[A-Za-z0-9_-]{2,})/g
+
+/**
+ * 文本 → 动作 id 列表（确定性、去重、词典序稳定）。
+ * @param {string} text - 人类消息或工具调用参数。
+ * @returns {string[]} 动作 id。
+ */
+export function detectActions(text) {
+  const s = String(text || '')
+  if (!s) return []
+  const out = []
+  for (const [id, patterns] of ACTION_LEXICON) {
+    if (patterns.some((re) => re.test(s))) out.push(id)
+  }
+  return out
+}
+
+/**
+ * 文本 → 路径 token（用于 trigger.paths 的 glob 匹配）。
+ * @param {string} text - 工具调用参数或人类消息。
+ * @returns {string[]} 去重后的路径 token。
+ */
+export function extractPaths(text) {
+  const s = String(text || '')
+  if (!s) return []
+  const out = new Set()
+  for (const m of s.matchAll(PATH_TOKEN)) out.add(m[0])
+  for (const m of s.matchAll(DOTFILE_TOKEN)) out.add(m[1])
+  return [...out]
+}
+
+/**
+ * 组装就绪上下文：人类意图 + 已观察动作。三处来源都做动作/路径归一，调用方只需给文本。
+ * @param {object} input
+ * @param {string} [input.humanText] - 本轮人类消息（先发窗口）。
+ * @param {string} [input.actionText] - 已观察到的 tool/call 参数（反应窗口）。
+ * @param {string[]} [input.actions] - 调用方已归一化的动作 id（可选，会被并集）。
+ * @param {string[]} [input.paths] - 调用方已归一化的路径（可选，会被并集）。
+ * @returns {{ humanText: string, actionText: string, actions: string[], paths: string[] }}
+ */
+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)])
+  return { humanText, actionText, actions: [...actions], paths: [...paths] }
+}
+
+/**
+ * 派生 trigger 的意图词表（有界、确定性）。派生信号**只进提示通道**：它能提升召回，
+ * 但永不强制注入——"自动学出来的东西"不该污染上下文。
+ */
+export const ACTION_WORDS = [
+  '提交', '公开', '泄漏', '发布', '发包', '发版', '上线', '部署', '迁移', '删除', '清理', '回滚',
+  '推送', '打包', '构建', '依赖', '密钥', '权限', '并发', '超时', '内存', '性能', '安全', '面试',
+]
+
+/** 无扩展名但明确是文件名的裸词（README / CHANGELOG / …），当关键词用。 */
+const BARE_FILE_NAMES = /\b(?:README|CHANGELOG|LICENSE|AGENTS|CONTRIBUTING|Dockerfile|Makefile)\b/g
+
+const DERIVED_MAX_KEYWORDS = 6
+const DERIVED_MAX_ACTIONS = 4
+const DERIVED_MAX_PATHS = 6
+
+/**
+ * 从一条 insight 的正文确定性派生触发信号（零模型、可重放）。
+ * 结果只写进 `triggerDerived`，供提示通道（检索文本）使用；是否强制注入只由 authored `trigger` 决定。
+ * @param {object} ins - 归一化后的 insight 条目。
+ * @returns {{ keywords: string[], actions: string[], paths: string[] }}
+ */
+export function deriveTrigger(ins) {
+  const text = [
+    ins?.title,
+    ins?.pattern,
+    ins?.fix,
+    ins?.choice,
+    ins?.reason,
+    ins?.problem,
+    ins?.solution,
+    ins?.topic,
+    ins?.body,
+    ...(Array.isArray(ins?.steps) ? ins.steps : []),
+  ].filter(Boolean).join('\n')
+  const bare = text.match(BARE_FILE_NAMES) || []
+  const keywords = [...new Set([...ACTION_WORDS.filter((w) => text.includes(w)), ...bare])].slice(0, DERIVED_MAX_KEYWORDS)
+  const actions = detectActions(text).slice(0, DERIVED_MAX_ACTIONS)
+  const paths = extractPaths(text).slice(0, DERIVED_MAX_PATHS)
+  return { keywords, actions, paths }
+}
+
+/**
+ * insights 文档的懒回填：给缺少 `triggerDerived` 的条目补上派生信号（增量、幂等）。
+ * 只改内存；是否落盘由调用方的 commit 决定。
+ * @param {{ items?: object[] }} doc - insights 文档。
+ * @returns {boolean} 是否发生了变更（用于置 dirty）。
+ */
+export function backfillDerivedTriggers(doc) {
+  if (!doc || !Array.isArray(doc.items)) return false
+  let changed = false
+  for (const it of doc.items) {
+    if (!it || it.triggerDerived) continue
+    const derived = deriveTrigger(it)
+    if (!derived.keywords.length && !derived.actions.length && !derived.paths.length) continue
+    it.triggerDerived = derived
+    changed = true
+  }
+  return changed
+}
+
+/**
+ * 提示通道的查询文本：剔除 1–2 个字符的拉丁 token。
+ *
+ * 为什么：`PR` / `CI` / `OS` 这类缩写太短、歧义太大，一个巧合命中就能当上该层最高分，
+ * 于是以 `relative:1.00` 混进上下文（实测：人类消息里的 "PR" 把一条 task-tools 越权 lesson
+ * 顶到了提示位）。内容词（≥3 字符的拉丁标识符、CJK 词）不受影响；
+ * authored trigger 通道完全不走这里，确定性匹配保持字面语义。
+ * @param {string} text - 人类消息或工具参数。
+ * @returns {string} 过滤后的查询文本。
+ */
+export function hintQueryText(text) {
+  return String(text || '')
+    .split(/\s+/)
+    // 路径形态的 token 原样保留（src/util/fs.js 里的 fs / js 是有效证据），
+    // 只对独立词做缩写剔除。
+    .map((w) => (/[/.]/.test(w) ? w : w.replace(/\b[A-Za-z0-9_]{1,2}\b/g, ' ')))
+    .join(' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+/** glob（只支持 `*`）→ 正则。 */
+function globToRegExp(pattern) {
+  const escaped = String(pattern).replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')
+  return new RegExp(`^${escaped}$`, 'i')
+}
+
+/**
+ * trigger 命中判定（确定性，无打分）。
+ * @param {object|null} trigger - `{ keywords?, symbols?, actions?, paths?, scope? }`。
+ * @param {object} ctx - {@link buildReadinessContext} 的结果。
+ * @returns {string|null} 命中原因（`keyword:…` / `symbol:…` / `action:…` / `path:…`），未命中为 null。
+ */
+export function matchTrigger(trigger, ctx) {
+  if (!trigger) return null
+  const haystack = `${ctx?.humanText || ''}\n${ctx?.actionText || ''}`
+  const lower = haystack.toLowerCase()
+  for (const kw of trigger.keywords || []) {
+    const k = String(kw || '')
+    if (k && lower.includes(k.toLowerCase())) return `keyword:${k}`
+  }
+  for (const sym of trigger.symbols || []) {
+    const s = String(sym || '')
+    if (s && haystack.includes(s)) return `symbol:${s}`
+  }
+  const actions = new Set(ctx?.actions || [])
+  for (const a of trigger.actions || []) {
+    const id = String(a || '')
+    if (id && actions.has(id)) return `action:${id}`
+  }
+  for (const p of trigger.paths || []) {
+    const pattern = String(p || '')
+    if (!pattern) continue
+    const re = globToRegExp(pattern)
+    const hit = (ctx?.paths || []).some((cand) => {
+      const c = String(cand || '')
+      if (!c) return false
+      return re.test(c) || re.test(c.split(/[\\/]/).pop() || '')
+    })
+    if (hit) return `path:${pattern}`
+  }
+  return null
+}
+
+/**
+ * 层内相对阈值：命中分至少达到该层最高分的 `ratioMin`。尺度无关（BM25 分数无上界），
+ * 取代"整条消息 vs 整条 insight 的集合重叠 ÷ 较大集合"这种长度敏感判据。
+ * @param {{ id?: string, score: number }[]} scored - 已按分数降序的候选。
+ * @param {{ ratioMin?: number }} [opts] - 相对阈值，默认 0.5。
+ * @returns {object[]} 通过阈值的候选（零分恒被剔除）。
+ */
+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)
+  return list.filter((r) => r.score >= floor)
+}

package/src/recall.js

@@ -0,0 +1,217 @@
+/**
+ * 统一召回核心（pull 侧）。
+ *
+ * 设计口径：「一个记忆，两种交付契约」——recall 回答"记忆里有什么和这件事有关"，
+ * readiness 回答"动手之前必须知道什么"（PR2）。本模块只做前者，且是 pull/push 共用
+ * 的检索核心，避免第二次为 insight 层另写一个更弱的匹配器。
+ *
+ * 三条不变量：
+ *   1. 每层一个适配器：把该层条目映射到同一个检索条目契约
+ *      （{ title, keywords, summary, terms, sourcePath }，见 util/search.js:weightedFieldText）。
+ *   2. 每层各自 top-k 后再合并：20k doc 条目不能把十几条 insight 挤出结果。
+ *   3. 跨层不给"伪可比"的单一分数：桶内先按层内 top 归一为 rel，再乘层先验；
+ *      该分数只用于提示级排序，pull 的展示始终按层分节。
+ *
+ * 规范段提权：标题命中"必须遵守 / 禁止 / rules / must"等词集的 doc chunk 在召回中提权。
+ * 确定性、零模型、零依赖——不违反「零依赖、零后台、零 LLM 索引期」。
+ *
+ * @module dsh-project-memory/recall
+ */
+import { rankEntriesMergedScored, rankEntriesStreaming, rankExperienceScored } from './util/search.js'
+
+/** 各层先验：insight 是"踩过的坑"，略高于普通文档；经验层已由 experience 文件服务，略低。 */
+export const LAYER_PRIORS = Object.freeze({
+  insight: 1.15,
+  doc: 1,
+  symbol: 1,
+  experience: 0.9,
+})
+
+/** 规范段词集（多语言、确定性）：标题命中即视为"规约/清单"段。 */
+export const NORMATIVE_HEADING =
+  /(必须|禁止|不得|不要|铁律|规约|规范|规则|约定|清单|检查表|checklist|rules?|requirements?|must|must not|do not|don't|never)/i
+
+/** 规范段提权倍数。取 1.5 与 CJK 短语加成同量级：足以翻转词频差，不足以压过强命中。 */
+export const NORMATIVE_PRIOR = 1.5
+
+/**
+ * 规范段先验：doc 条目标题命中规范词集时提权，其余条目恒为 1。
+ * @param {{ title?: string }} entry - 任意检索条目（通常是 doc chunk）。
+ * @returns {number} 1 或 {@link NORMATIVE_PRIOR}。
+ */
+export function normativePrior(entry) {
+  return NORMATIVE_HEADING.test(String(entry?.title || '')) ? NORMATIVE_PRIOR : 1
+}
+
+/**
+ * 一条 insight 的正文文本（用于展示、注入与检索兜底）。
+ * 顺序即优先级：fix > choice > solution > pattern/problem > body > steps。
+ * @param {object} ins - 归一化后的 insight 条目。
+ * @returns {string} 单行正文。
+ */
+export function insightBodyText(ins) {
+  const parts = []
+  if (ins?.fix) parts.push(ins.fix)
+  else if (ins?.choice) parts.push(ins.choice)
+  else if (ins?.solution) parts.push(ins.solution)
+  else if (ins?.pattern) parts.push(ins.pattern)
+  else if (ins?.problem) parts.push(ins.problem)
+  else if (ins?.body) parts.push(ins.body)
+  if (ins?.reason) parts.push(`理由：${ins.reason}`)
+  if (Array.isArray(ins?.steps) && ins.steps.length) {
+    parts.push(ins.steps.map((s, i) => `${i + 1}. ${s}`).join(' '))
+  }
+  return parts.filter(Boolean).join(' ')
+}
+
+/**
+ * insight → 统一检索条目契约的适配器。
+ * 复用 doc 条目的字段语义，于是 title×5 字段加权、CJK 短语加成、IDF 打分全部现成可用。
+ * @param {object} ins - 归一化后的 insight 条目。
+ * @returns {object} 检索条目（额外字段仅供渲染，不参与打分）。
+ */
+export function insightToEntry(ins) {
+  const derived = ins?.triggerDerived || {}
+  const keywords = [
+    ins?.kind,
+    ins?.scope,
+    ...(Array.isArray(ins?.files) ? ins.files : []),
+    ...(Array.isArray(ins?.symbols) ? ins.symbols : []),
+    ...(Array.isArray(ins?.tags) ? ins.tags : []),
+    // 派生信号（PR3）：只提升召回，不参与强制注入
+    ...(Array.isArray(derived.keywords) ? derived.keywords : []),
+    ...(Array.isArray(derived.actions) ? derived.actions : []),
+  ].filter(Boolean)
+  return {
+    id: `insight:${ins?.id}`,
+    insightId: ins?.id,
+    type: 'insight',
+    kind: ins?.kind,
+    scope: ins?.scope,
+    confidence: ins?.confidence,
+    files: Array.isArray(ins?.files) ? ins.files : [],
+    symbols: Array.isArray(ins?.symbols) ? ins.symbols : [],
+    title: String(ins?.title || '(untitled)'),
+    summary: insightBodyText(ins).slice(0, 300),
+    // 检索用词项：pattern/problem/reason 是"症状"侧词汇，fix 已在 summary 里（title×5 之外单算 1 份）。
+    terms: [ins?.pattern, ins?.problem, ins?.reason, ...(Array.isArray(derived.paths) ? derived.paths : [])].filter(Boolean).join(' '),
+    keywords,
+    sourcePath: Array.isArray(ins?.files) && ins.files.length ? ins.files[0] : '',
+    status: 'exact',
+  }
+}
+
+/**
+ * 召回可见的 insight 集合：作用域可见性跟随会话绑定。
+ *   - project / global：始终可见（归档除外）；
+ *   - task：只在该会话绑定了对应任务时可见（任务私有，不泄露给别的会话）；
+ *   - 迁移影子（kind=experience 且 source=migrate）不在此列：它们由 experience 层服务，
+ *     否则同一内容会在 `## Insights` 与 `## Experience` 里各出现一次。
+ * @param {{ store?: object, globalStore?: object, boundTaskId?: string|null }} opts
+ * @returns {object[]} 可检索的 insight 条目。
+ */
+export function visibleInsights({ store = null, globalStore = null, boundTaskId = null } = {}) {
+  const out = []
+  for (const it of (store && typeof store.insightItems === 'function' ? store.insightItems() : []) || []) {
+    if (!it || it.archived) continue
+    if (it.scope === 'task') continue
+    if (it.draft === true) continue
+    if (it.kind === 'experience' && it.source === 'migrate') continue // v0.4 影子，交给 experience 层
+    out.push(it)
+  }
+  for (const it of (globalStore && typeof globalStore.items === 'function' ? globalStore.items() : []) || []) {
+    if (!it || it.archived || it.draft === true) continue
+    out.push(it)
+  }
+  if (boundTaskId && store && typeof store.getTask === 'function') {
+    const task = store.getTask(boundTaskId)
+    for (const it of (task && task.insights) || []) {
+      if (!it || it.archived) continue
+      out.push({ ...it, scope: it.scope || 'task' })
+    }
+  }
+  return out
+}
+
+/**
+ * 按层召回：每层各自 top-k，桶内保留原始分与层内相对分。
+ * @param {object} opts
+ * @param {object} [opts.store] - ProjectMemoryStore；提供 doc/symbol/experience 池与 IDF 缓存。
+ * @param {object} [opts.globalStore] - GlobalStore；提供 global 级 insight。
+ * @param {object[]} [opts.entries] - 直接给定检索池（测试/自定义场景），优先于 store。
+ * @param {string[]|string} [opts.queries] - 一条或多条查询（LLM 扩展变体也走这里）。
+ * @param {string[]} [opts.layers] - 要召回的层；默认四层。
+ * @param {number} [opts.limit] - 每层上限。
+ * @param {string|null} [opts.boundTaskId] - 当前会话绑定的任务（决定 task 级可见性）。
+ * @returns {{ layers: object[], flat: object[] }} layers 为分桶结果，flat 为归一化+先验后的跨层提示序。
+ */
+export function recallItems(opts = {}) {
+  const {
+    store = null,
+    globalStore = null,
+    entries = null,
+    queries = [],
+    layers = ['doc', 'symbol', 'experience', 'insight'],
+    limit = 8,
+    boundTaskId = null,
+  } = opts
+  const qs = (Array.isArray(queries) ? queries : [queries]).map((q) => String(q ?? '')).filter(Boolean)
+  const want = new Set(layers)
+  const idf = store && typeof store.getIdfCache === 'function' ? store.getIdfCache() : {}
+  const buckets = []
+
+  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 })
+    }
+    for (const layer of ['doc', 'symbol']) {
+      const hits = byLayer.get(layer)
+      if (!hits.length) continue
+      hits.sort((a, b) => b.weightedScore - a.weightedScore)
+      const top = hits[0].weightedScore || 1
+      buckets.push({
+        layer,
+        prior: LAYER_PRIORS[layer],
+        hits: hits.map((h) => ({ ...h, rel: h.weightedScore / top })),
+      })
+    }
+  }
+
+  if (want.has('experience')) {
+    const scored = rankExperienceScored((store && store.experience) || [], qs, limit)
+    if (scored.length) {
+      const top = scored[0].score || 1
+      buckets.push({
+        layer: 'experience',
+        prior: LAYER_PRIORS.experience,
+        hits: scored.map(({ item, score }) => ({ item, score, prior: LAYER_PRIORS.experience, weightedScore: score, rel: score / top })),
+      })
+    }
+  }
+
+  if (want.has('insight')) {
+    const pool = entries !== null
+      ? entries.filter((e) => e && e.type === 'insight')
+      : visibleInsights({ store, globalStore, boundTaskId }).map(insightToEntry)
+    const scored = rankEntriesMergedScored(pool, qs, limit)
+    if (scored.length) {
+      const top = scored[0].score || 1
+      buckets.push({
+        layer: 'insight',
+        prior: LAYER_PRIORS.insight,
+        hits: scored.map(({ entry, score }) => ({ item: entry, score, prior: LAYER_PRIORS.insight, weightedScore: score, rel: score / top })),
+      })
+    }
+  }
+
+  const flat = buckets
+    .flatMap((b) => b.hits.map((h) => ({ ...h, layer: b.layer, layerPrior: b.prior, hint: h.rel * b.prior })))
+    .sort((a, b) => b.hint - a.hint)
+    .slice(0, limit)
+  return { layers: buckets, flat }
+}

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。'
@@ -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: '关联文件（项目相对路径）' },