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

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.5.4 (2026-09-12)
+
+### Changed (indexing: model-free by design; whole-chunk retrieval terms)
+
+- **Indexing never calls a model — by construction.** `buildDocEntries(relPath, filePath, opts)` no longer accepts an `llm` parameter, so index-time code cannot reach a model even by accident. `src/doc-pipeline.js`, `src/watch.js`, `src/lazy.js`, `index_doc` and `index_repo` no longer resolve or pass a route. A stub-model run over 289 files / 2141 entries records **0 calls**.
+- **Retrieval terms cover the whole chunk.** The old shape made the whole chunk's searchable body the ≤300-char `summary` (`util/search.js` `weightedFieldText`), so a 3000-char chunk had roughly 90% of its text invisible to `query_memory`. Each doc entry now also carries `terms` — a bounded (≤160), deterministic, stop-word-filtered literal term set covering the **entire chunk** (`src/doc-index.js`, built from the existing `tokenizeRaw`). `summary` stays short for the injection budget; `terms` is search-only.
+  - Measured on this repository's docs (179 chunks): reachable unique chunk terms go from **27.3% to 100%**; terms that appear only beyond character 300 go from **0% to 100%** entryHit@5, while already-answerable queries keep their ranking (MRR **0.958** with `terms` vs **0.955** without). Zero model calls.
+  - `linkEntries` now includes `terms` in its haystack for the same reason: a symbol mentioned late in a chunk links again.
+  - **Existing stores are back-filled automatically.** `index_repo`, `watch` and `lazy` treat a doc record whose entries lack `terms` as needing re-extraction even when the content hash is unchanged (`docEntriesNeedBackfill`), so the coverage fix reaches stores indexed before 0.5.4 without a manual `reindex: true`. It is a one-shot pass: once entries carry `terms`, the hash skip resumes.
+- **Rule-based keywords** (`extractKeywords`: title-weighted top terms) replace the previous placeholder 5–10 keywords, so `keywords` is deterministic and reproducible. Bilingual keyword expansion and self-reported blind spots are intentionally **not** produced at index time: the `blindSpots` field and its rendering are retained for compatibility, but new entries leave it empty.
+- **Recall-time opt-in LLM is routed explicitly and visibly.** `config.llmQueryExpansion` (default off) and `reflection.enabled` (default off) are the only remaining model calls, and both are recall-time and opt-in. They resolve `provider`/`model` through `src/llm-route.js` (config override → session `requestHeader().config` → agent options → last-seen `request/header` route). When no route is available or a call fails, search falls back explicitly and records a one-time `degraded` entry rather than failing silently.
+- **Tests:** `test/doc-index.test.mjs` (new) pins summary ≤300 / terms covering past char 300 / BM25 hitting a post-300 term / zero model calls at index time even with a routed `exec` / deterministic bounded `extractTerms` / the automatic back-fill. `test/llm-route.test.mjs` covers the recall-time routing contract. `test/run-test.mjs` asserts watch indexing makes **zero** model calls and that doc entries are structural.
+
+### Changed (injection semantics + signals)
+
+- **The injected block now declares `form: 'snapshot'`, not `'notice'`.** The autocontext block is current state that a later injection supersedes; `notice` means "a one-off account of something that just happened", so the old declaration was semantically wrong for both the transcript UI and the model. The channel is untouched (still appended through `agent/pre-step` as a plugin `user/message`). The host's `ContextFormed` is a discriminated union (`packages/llm/llm/src/message.ts:81-96`), so `snapshot` carries `sections: [{ name, text }]` and must **not** carry `notice`'s `summary`; the section is named `project-memory` and its `text` is exactly the assembled block.
+- **Per-file `reads` / `writes` counters are now collected.** `task.fileMeta[rel]` gained `reads` and `writes` alongside the retained `n` (which stays the read+write total for old tasks). This is **collect-only**: `hotSortFiles`, the resident "editing now" list and the dedupe fingerprint still read only `lastWriteAt` / `lastReadAt`, so no ordering or injection behaviour changes. It starts collecting the one signal a full-index memory plugin cannot observe — what the model actually read.
+- **`query_memory` memory rows carry a status placeholder.** Each doc/symbol row now prints `- status: <value>`, defaulting to `exact` for every entry (the vocabulary is `exact | needs-verify | re-verified | refreshed | demoted`). No state machine is implemented yet; this is a forward-compatible output contract so real values can land later without changing the rendering again.
+- **Tests:** suite 227 → **231** checks. `test/host-contract.test.mjs` now drives a real injection and pins the source shape (`form: 'snapshot'`, `sections[0].name`, no `summary`); `test/taskbridge.test.mjs` pins `reads`/`writes`/`n`; `test/run-test.mjs` pins the `status` placeholder on doc and symbol rows.
+
+### Files
+- src/doc-index.js (new), src/doc-pipeline.js, src/llm.js, src/llm-route.js (new), src/util/text.js, src/util/search.js, src/link.js, src/index.js, src/watch.js, src/lazy.js, src/reflection-pipeline.js, src/auto-inject.js, src/setup/taskbridge.js, src/tools/index-doc.js, src/tools/index-repo.js, src/tools/query-memory.js, src/tools/task-tools.js, src/commands/task-actions.js, test/doc-index.test.mjs (new), test/llm-route.test.mjs, test/host-contract.test.mjs, test/taskbridge.test.mjs, test/run-test.mjs, test/reflection-pipeline.test.mjs, package.json, CHANGELOG.md
+
 ## 0.5.3 (2026-09-10)
 
 ### Changed (DSH 0.1.5-rc.1 compatibility)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yolk_vat-y/dsh-project-memory",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "Persistent project memory for dsh agents: index docs (PDF/Markdown/text) and code symbols into a searchable per-workspace store, recall them with cited sources, and keep experience entries (problems -> solutions) searchable on demand.",
   "type": "module",
   "main": "src/index.js",
@@ -17,7 +17,7 @@
     "url": "https://github.com/00080000/dsh-project-memory.git"
   },
   "scripts": {
-    "test": "node test/run-test.mjs && node test/taskbridge.test.mjs && node test/insight-store.test.mjs && node test/reflection-pipeline.test.mjs && node test/auto-inject.test.mjs && node test/insight-actions.test.mjs && node test/host-contract.test.mjs",
+    "test": "node test/run-test.mjs && node test/taskbridge.test.mjs && node test/insight-store.test.mjs && node test/reflection-pipeline.test.mjs && node test/auto-inject.test.mjs && node test/insight-actions.test.mjs && node test/host-contract.test.mjs && node test/llm-route.test.mjs && node test/doc-index.test.mjs",
     "build:client": "tsdown"
   },
   "keywords": [

package/src/auto-inject.js

@@ -204,7 +204,15 @@ export function installAutoInject(ctx, config) {
         if (lastFpBySession.size > LAST_FP_MAX) lastFpBySession.delete(lastFpBySession.keys().next().value)
         const injectMessage = createUserMessage({
           content: [{ type: 'text', text: `\n\n${INJECT_MARK} auto-context\n${built.text}` }],
-          source: { kind: 'plugin', plugin: 'dsh-project-memory', form: 'notice', summary: `记忆注入 ${built.text.length} 字符` },
+          // 这一块是「同一生产者后续快照会取代的当前状态」，不是一次性通知。
+          // 宿主 ContextFormed 是判别联合：snapshot 必须带 sections（notice 才需要 summary）。
+          // 通道不变（仍走 agent/pre-step 追加 user 消息），只修语义。
+          source: {
+            kind: 'plugin',
+            plugin: 'dsh-project-memory',
+            form: 'snapshot',
+            sections: [{ name: 'project-memory', text: built.text }],
+          },
         })
         return { ...decision, messages: [...decision.messages, injectMessage] }
       }

package/src/commands/task-actions.js

@@ -7,6 +7,7 @@ import { ProjectMemoryStore } from '../store.js'
 import { projectRootFor, adoptStepsToSession, shouldAdoptToHost } from '../setup/taskbridge.js'
 import { renderTaskSnapshot, buildTaskPayload } from './tasks.js'
 import { fireReflect } from '../reflection-pipeline.js'
+import { resolveRoute } from '../llm-route.js'
 
 const VERBS = { switch: 'switch', archive: 'archive' }
 
@@ -138,7 +139,7 @@ export function taskCommandDefinition(config, ctx) {
           store.save()
           // 反思钩子：切走旧任务异步收割（默认关）
           if (prevBound && prevBound !== task.id) {
-            fireReflect(config, { llm: ctx?.llm }, root, prevBound, 'switch-away')
+            fireReflect(config, { llm: ctx?.llm }, root, prevBound, 'switch-away', resolveRoute(session ? { agent: { session } } : undefined, config))
           }
           // 反向接管：切换成功后把任务步骤推成宿主 todo/write（dsh 清单跟随）
           if (shouldAdoptToHost(config)) {
@@ -156,7 +157,7 @@ export function taskCommandDefinition(config, ctx) {
           task.updatedAt = new Date().toISOString()
           store.save()
           // 反思钩子：归档即收割（默认关）
-          fireReflect(config, { llm: ctx?.llm }, root, taskId, 'archive')
+          fireReflect(config, { llm: ctx?.llm }, root, taskId, 'archive', resolveRoute(session ? { agent: { session } } : undefined, config))
           const note = `已归档: ${describeTask(task)}（select_task 可恢复）`
           return withTaskSnapshot(config, cwd, sid, store, note)
         }

package/src/doc-index.js

@@ -0,0 +1,71 @@
+// 文档索引的结构化词项（纯规则、确定性；索引期不调用任何模型）。
+//
+// 动机：检索只吃 title/keywords/summary/sourcePath（util/search.js 的 weightedFieldText），
+// 而 summary 为了注入预算被压到 300 字符 —— 一个 3000 字符的 chunk 有九成内容检索不到。
+// 这里把「注入用的短摘要」和「检索用的词项」拆开：summary 仍然短，terms 覆盖整个 chunk。
+//
+// 纯规则、确定性、可重放：tokenizeRaw（拉丁词 + CJK bigram）→ 去停用词/纯数字 → 词频排序 → 截断。
+import { tokenizeRaw } from './util/search.js'
+
+export const MAX_TERMS = 160
+export const MAX_KEYWORDS = 8
+
+const STOPWORDS = new Set([
+  'the', 'and', 'for', 'are', 'but', 'not', 'you', 'all', 'any', 'can', 'had', 'her', 'was', 'one',
+  'our', 'out', 'day', 'get', 'has', 'him', 'his', 'how', 'its', 'new', 'now', 'old', 'see', 'two',
+  'way', 'who', 'boy', 'did', 'use', 'that', 'this', 'with', 'from', 'they', 'will', 'would', 'there',
+  'their', 'what', 'about', 'which', 'when', 'make', 'like', 'time', 'just', 'know', 'take', 'into',
+  'your', 'some', 'them', 'than', 'then', 'only', 'come', 'over', 'also', 'back', 'after', 'other',
+  'many', 'most', 'such', 'even', 'much', 'more', 'been', 'were', 'have', 'each', 'does', 'doing',
+  'should', 'could', 'these', 'those', 'being', 'where', 'while', 'because', 'before', 'between',
+  'under', 'again', 'further', 'once', 'here', 'both', 'few', 'same', 'too', 'very', 'own', 'off',
+  'per', 'via', 'etc', 'see', 'note', 'used', 'using', 'uses', 'may', 'must', 'shall',
+])
+
+/** 一个 token 是否值得作为检索词项。 */
+function isUseful(token) {
+  if (token.length < 2) return false
+  if (STOPWORDS.has(token)) return false
+  if (/^\d+$/.test(token)) return false
+  return true
+}
+
+/**
+ * 整个 chunk 的字面词项（唯一、按词频排序、有上限）。
+ * @returns {string[]} 词项数组（已去重）
+ */
+export function extractTerms(text, { max = MAX_TERMS } = {}) {
+  const counts = new Map()
+  for (const token of tokenizeRaw(text)) {
+    if (!isUseful(token)) continue
+    counts.set(token, (counts.get(token) || 0) + 1)
+  }
+  return [...counts.entries()]
+    .sort((a, b) => b[1] - a[1] || b[0].length - a[0].length || a[0].localeCompare(b[0]))
+    .slice(0, max)
+    .map(([token]) => token)
+}
+
+/**
+ * 结构化的检索词项串（用于 entry.terms，并入 BM25 的检索文本）。
+ */
+export function extractTermText(text, { max = MAX_TERMS } = {}) {
+  return extractTerms(text, { max }).join(' ')
+}
+
+/**
+ * 规则化关键词：标题重复一次以取得小幅加权（替代此前依赖 LLM 的 5–10 个关键词）。
+ */
+export function extractKeywords(title, text, { max = MAX_KEYWORDS } = {}) {
+  const source = title ? `${title} ${title} ${text}` : text
+  return extractTerms(source, { max })
+}
+
+/**
+ * 旧 store 的 doc 条目没有 `terms`：需要一次定向回填，否则内容哈希未变的文件会被跳过，
+ * 新的检索覆盖不会生效。只对 doc 条目判断，code 条目（符号表）不需要 terms。
+ */
+export function docEntriesNeedBackfill(entries) {
+  if (!Array.isArray(entries) || entries.length === 0) return true
+  return entries.some((e) => e && e.type === 'doc' && typeof e.terms !== 'string')
+}

package/src/doc-pipeline.js

@@ -2,9 +2,10 @@ import { createHash } from 'node:crypto'
 import path from 'node:path'
 import { stat } from 'node:fs/promises'
 import { looksLikeDump, readTextFile } from './util/fs.js'
+import { summarizeText } from './util/text.js'
 import { parsePdf } from './parsers/pdfjs-parser.js'
 import { chunkText } from './chunker.js'
-import { extractDocEntry } from './llm.js'
+import { extractKeywords, extractTermText } from './doc-index.js'
 
 export async function extractTextFromFile(filePath, { maxFileSizeMb = 50, maxPdfPages = 1000 } = {}) {
   const ext = path.extname(filePath).toLowerCase()
@@ -21,43 +22,37 @@ export async function extractTextFromFile(filePath, { maxFileSizeMb = 50, maxPdf
   return readTextFile(filePath, maxFileSizeMb ? maxFileSizeMb * 1024 * 1024 : Infinity)
 }
 
-const DOC_CONCURRENCY = 4
-
-export async function buildDocEntries(llm, a, b, c) {
-  // Backward compatible: old signature (llm, filePath, opts) or new (llm, relPath, filePath, opts)
-  const [relPath, filePath, opts] = c === undefined ? [a, a, b] : [a, b, c]
+/**
+ * 文档分片 → 记忆条目（索引期不调用任何模型：纯规则、确定性、可重放）。
+ *
+ * 注入用 summary 与检索用 terms 分离：
+ *   - summary：≤300 字符，进上下文，保持小预算；
+ *   - terms：整个 chunk 的字面词项，只进 BM25 检索文本，不进注入。
+ * 于是「chunk 只有前 300 字符可检索」的旧限制被移除，且没有任何 LLM 调用。
+ * 函数签名里刻意没有 llm —— 索引期零 LLM 由构造保证，而不是靠 catch。
+ */
+export async function buildDocEntries(relPath, filePath, opts = {}) {
   const text = await extractTextFromFile(filePath, opts)
   if (looksLikeDump(text)) return null
-  
+
   // Compute content hash for update detection
   const hash = createHash('sha256').update(text).digest('hex').slice(0, 16)
-  
+
   const chunks = chunkText(text, opts.chunkChars, opts.maxChunks)
-  const metas = new Array(chunks.length)
-  let cursor = 0
-  await Promise.all(
-    Array.from({ length: Math.min(DOC_CONCURRENCY, chunks.length) }, () =>
-      (async () => {
-        while (cursor < chunks.length) {
-          const i = cursor++
-          metas[i] = await extractDocEntry(llm, chunks[i], filePath)
-        }
-      })(),
-    ),
-  )
-  return metas.map((meta, i) => ({
+  return chunks.map((chunk, i) => ({
     id: `${relativeId(relPath)}#${i}`,
     sourcePath: relPath,
-    sourceLine: chunks[i].line,
+    sourceLine: chunk.line,
     type: 'doc',
-    title: meta.title,
-    summary: meta.summary,
-    blindSpots: meta.blindSpots || '',
-    keywords: meta.keywords,
+    title: chunk.title || relPath,
+    summary: summarizeText(chunk.text),
+    blindSpots: '',
+    keywords: extractKeywords(chunk.title, chunk.text),
+    terms: extractTermText(chunk.text),
     hash,
   }))
 }
 
 function relativeId(filePath) {
   return String(filePath).replace(/[\\/:\s]/g, '_')
-}
+}

package/src/index.js

@@ -13,6 +13,7 @@ import { setupTaskbridge } from './setup/taskbridge.js'
 import { listTasksTool, selectTaskTool, archiveTaskTool, showTaskPanelTool } from './tools/task-tools.js'
 import { lessonTool } from './tools/lesson-tools.js'
 import { installAutoInject } from './auto-inject.js'
+import { rememberRoute } from './llm-route.js'
 import { tasksCommandDefinition } from './commands/tasks.js'
 import { taskCommandDefinition } from './commands/task-actions.js'
 import { insightCommandDefinition } from './commands/insight-actions.js'
@@ -29,6 +30,14 @@ export const Config = Schema.object({
   maxPdfPages: Schema.number().default(1000),
   llmQueryExpansion: Schema.boolean().default(false),
   expansionCount: Schema.number().default(6),
+  // 辅助 LLM 调用的路由覆写 —— **索引期零 LLM**，这里的路由只服务于召回期可选项
+  // （llmQueryExpansion 查询扩展）与反思期（reflection.enabled）。
+  // 未设置时：工具调用取当前会话 header 的 provider/model；后台路径取最近一次会话路由（request/header）。
+  // 两者都拿不到时明确走回退并记录 degraded（不静默）。
+  llm: Schema.object({
+    provider: Schema.string(),
+    model: Schema.string(),
+  }).default({}),
   lazyIndexing: Schema.boolean().default(true),
   autoIndexOnFirstUse: Schema.boolean().default(false),
   watch: Schema.boolean().default(true),
@@ -51,7 +60,7 @@ export const Config = Schema.object({
     decayDays: Schema.number().default(90),
     globalFile: Schema.string(),
   }).default({}),
-  // PR 1b：反思管线（LLM 消费点，默认关）。产出只写 task 级草稿，见 PLAN §3
+  // 反思管线（召回期可选 LLM 消费点，默认关）。产出只写 task 级草稿。
   reflection: Schema.object({
     enabled: Schema.boolean().default(false),
     cooldownMs: Schema.number().default(1800000),
@@ -88,6 +97,10 @@ export function apply(ctx, config) {
 
   // TaskBridge：任务实体 + 宿主 todo 同步
   setupTaskbridge(ctx, config)
+  // 跟踪会话路由（request/header 事件），为无会话上下文的召回期可选 LLM（查询扩展 / 反思）兜底
+  ctx.on('session/event', (session, event) => {
+    if (event?.type === 'request/header') rememberRoute(session)
+  })
   ctx.tools.register(listTasksTool(config))
   ctx.tools.register(selectTaskTool(config, { llm: ctx.llm, ctx }))
   ctx.tools.register(archiveTaskTool(config, { llm: ctx.llm, ctx }))

package/src/lazy.js

@@ -3,6 +3,7 @@ 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 { ProjectMemoryStore } from './store.js'
@@ -98,7 +99,8 @@ export async function indexFile(ctx, config, filePath, watchManager = null) {
   } catch {
     return false
   }
-  if (existing && existing.sha256 === hash) return false
+  // 旧 store 的 doc 条目缺 terms → 一次性回填（即使哈希未变）
+  if (existing && existing.sha256 === hash && !(isSupportedDoc(ext) && docEntriesNeedBackfill(store.entries[rel]))) return false
 
   if (watchManager) {
     watchManager.addRoot(root)
@@ -115,7 +117,7 @@ export async function indexFile(ctx, config, filePath, watchManager = null) {
       return true
     })
   } else {
-    entries = await buildDocEntries(ctx.llm, rel, filePath, {
+    entries = await buildDocEntries(rel, filePath, {
       chunkChars: config.chunkChars,
       maxChunks: config.maxChunksPerFile,
       maxFileSizeMb: config.maxFileSizeMb,

package/src/link.js

@@ -28,7 +28,8 @@ export function linkEntries(store) {
   let links = 0
   for (const doc of docs) {
     const linked = new Set()
-    const haystack = `${doc.title || ''} ${doc.summary || ''} ${doc.keywords ? doc.keywords.join(' ') : ''}`.toLowerCase()
+    // 结构词项也参与链接：terms 覆盖整个 chunk，符号在后半段被提及时同样能链上（与检索同源）
+    const haystack = `${doc.title || ''} ${doc.summary || ''} ${doc.terms || ''} ${doc.keywords ? doc.keywords.join(' ') : ''}`.toLowerCase()
     for (const [, entry] of symbolByName) {
       const hit = entry.re ? entry.re.test(haystack) : haystack.includes(entry.lower)
       for (const s of entry.syms) {

package/src/llm-route.js

@@ -0,0 +1,95 @@
+// 辅助 LLM 调用的路由解析（仅召回期可选：查询扩展 / 反思）。
+//
+// 背景：宿主 LlmRuntime.stream 要求 provider/model 必填，缺失即抛 NO_ADAPTER。
+// 本模块负责：
+//   1) 从工具 exec / 会话 / 配置解析出 (provider, model)；
+//   2) 把「无法路由 / 调用失败」记成可见的 degraded 记录，而不是静默降级。
+//
+// 解析优先级（与宿主 compaction summarizer 同序，再补一条后台 hint）：
+//   config.llm 显式覆写 > exec 会话 requestHeader().config > exec agent options >
+//   最近一次 request/header 事件记下的路由（后台 watch/lazy 兜底）。
+//
+// 登记规则：路由只影响辅助调用走哪个模型，不改变检索/排序行为。
+
+/** 最近一次在会话里观察到的路由，供无 exec 的后台索引（watch/lazy）兜底。 */
+let routeHint = null
+
+/** 无法路由 / 调用失败留下的可见痕迹：code -> { code, reason, at, count }。 */
+const degraded = new Map()
+
+function normalize(provider, model, source) {
+  if (typeof provider !== 'string' || !provider) return null
+  if (typeof model !== 'string' || !model) return null
+  return { provider, model, source }
+}
+
+function routeFromSession(session) {
+  try {
+    const config = session?.requestHeader?.()?.config
+    return normalize(config?.provider, config?.model, 'session')
+  } catch {
+    return null
+  }
+}
+
+/** 记下会话当前路由，作为后台索引的兜底。由 request/header 事件驱动。 */
+export function rememberRoute(session) {
+  const route = routeFromSession(session)
+  if (route) routeHint = { provider: route.provider, model: route.model }
+}
+
+/** 显式配置的路由（config.llm.provider + config.llm.model 同时存在才算）。 */
+function routeFromConfig(config) {
+  return normalize(config?.llm?.provider, config?.llm?.model, 'config')
+}
+
+/**
+ * 解析一次辅助 LLM 调用的路由。
+ * @param exec - 工具执行上下文（可含 agent.session / agent.options），可为空。
+ * @param config - 插件配置（可含 llm 覆写）。
+ * @returns {{provider: string, model: string, source: string}|null}
+ */
+export function resolveRoute(exec, config) {
+  const configured = routeFromConfig(config)
+  if (configured) return configured
+
+  const fromExecSession = routeFromSession(exec?.agent?.session)
+  if (fromExecSession) return fromExecSession
+
+  const options = exec?.agent?.options
+  const fromOptions = normalize(options?.provider, options?.model, 'agent')
+  if (fromOptions) return fromOptions
+
+  if (routeHint) return { ...routeHint, source: 'session-hint' }
+  return null
+}
+
+/**
+ * 记录一次降级（允许降级，不允许静默）。同一 code 只打印一次，避免逐 chunk 刷屏；
+ * 计数与最近原因保留下来，供 memory_stats / 测试读取。
+ */
+export function noteDegraded(code, reason) {
+  const at = new Date().toISOString()
+  const prev = degraded.get(code)
+  if (prev) {
+    prev.count += 1
+    prev.at = at
+    prev.reason = reason
+    return prev
+  }
+  const record = { code, reason, at, count: 1 }
+  degraded.set(code, record)
+  console.warn(`[dsh-project-memory] degraded ${code}: ${reason}`)
+  return record
+}
+
+/** 当前累计的降级记录（快照，按 code 去重）。 */
+export function degradedList() {
+  return [...degraded.values()].map((d) => ({ ...d }))
+}
+
+/** 测试用：清空路由 hint 与降级记录。 */
+export function resetRouteState() {
+  routeHint = null
+  degraded.clear()
+}

package/src/llm.js

@@ -1,5 +1,7 @@
+// 辅助 LLM 调用（**仅召回期 / 反思期，按需可选**；索引期不调用任何模型）。
+// chatText 是唯一的宿主调用出口：provider/model 必填，缺失时显式抛错，由调用方决定回退并记 degraded。
 import { BlockAssembler, createUserMessage } from '@deepseek-ai/dsh-llm'
-import { tokenize } from './util/search.js'
+import { noteDegraded } from './llm-route.js'
 
 function systemMessage(text) {
   return { role: 'system', content: [{ type: 'text', text }] }
@@ -13,24 +15,19 @@ function textOf(message) {
     .join('\n')
 }
 
-const MAX_SUMMARY = 300
-
-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 + '…'
-}
-
-export async function chatText(llm, system, user, { timeoutMs = 120000 } = {}) {
+export async function chatText(llm, system, user, { timeoutMs = 120000, route } = {}) {
+  // provider/model 是宿主 GenerateOptions 的必填项，缺失时 LlmRuntime 抛 NO_ADAPTER。
+  // 这里显式失败（由调用方决定回退并记 degraded），不让异常悄悄消失。
+  if (!route?.provider || !route?.model) {
+    throw new Error('auxiliary LLM call requires an explicit provider/model route')
+  }
   const assembler = new BlockAssembler()
   const controller = new AbortController()
   const timer = setTimeout(() => controller.abort(), timeoutMs)
   try {
     for await (const chunk of llm.stream({
+      provider: route.provider,
+      model: route.model,
       messages: [systemMessage(system), createUserMessage({ content: [{ type: 'text', text: user }] })],
       signal: controller.signal,
     })) {
@@ -72,8 +69,13 @@ function parseJson(text, validate) {
   return null
 }
 
-export async function expandQuery(llm, query, count = 6) {
+/** 召回期可选的查询扩展（默认关；开启时才需要 provider/model 路由）。 */
+export async function expandQuery(llm, query, count = 6, { route } = {}) {
   if (!llm) return [query]
+  if (!route) {
+    noteDegraded('llm.expand.no-route', 'no provider/model route for query expansion; search uses the raw query')
+    return [query]
+  }
   const system =
     'You are a search-query expander for a codebase/document memory search engine. ' +
     'Given a user query, return a STRICT JSON array of alternative search queries that ' +
@@ -81,57 +83,14 @@ export async function expandQuery(llm, query, count = 6) {
     'code identifier guesses, and narrower/longer phrasings. Include the original query first. ' +
     'Output only the JSON array of strings, no fences, no commentary.'
   try {
-    const raw = await chatText(llm, system, `Query: "${query}"\n\nReturn the JSON array.`)
+    const raw = await chatText(llm, system, `Query: "${query}"\n\nReturn the JSON array.`, { route })
     const parsed = parseJsonArray(raw)
     if (Array.isArray(parsed) && parsed.length) {
       const variants = parsed.map(String).filter((s) => s.trim()).slice(0, count)
       if (variants.length) return variants
     }
-  } catch {
-    // fall through to the raw query
+  } catch (err) {
+    noteDegraded('llm.expand.failed', `query expansion LLM call failed: ${err?.message || err}`)
   }
   return [query]
 }
-
-export async function extractDocEntry(llm, chunk, sourcePath) {
-  const system =
-    'You are a project-documentation indexer. Given a chunk of a project document, ' +
-    'return a STRICT JSON object with exactly four fields: ' +
-    '"title" (short section title, string), ' +
-    '"summary" (3-5 sentence dense summary of what this section covers, ' +
-    'mentioning concrete names, decisions, constraints, and key technical details), ' +
-    '"blindSpots" (string describing what this summary does NOT cover, ' +
-    'e.g. "未覆盖：部署细节、性能基准、v0.2 前 API", empty string if none), ' +
-    '"keywords" (array of 5-10 searchable strings: ' +
-    'cover the document\'s own language AND English equivalents, ' +
-    'so a query in either language can match). ' +
-    'Do not include markdown fences, do not add commentary, output only the JSON object.'
-
-  const user =
-    `Document: ${sourcePath}\nSection: ${chunk.title || '(untitled)'}\n\n` +
-    `Content:\n${chunk.text.slice(0, 6000)}\n\nReturn the JSON object.`
-
-  const fallback = () => ({
-    title: chunk.title || sourcePath,
-    summary: summarizeText(chunk.text),
-    blindSpots: '',
-    keywords: tokenize(chunk.title).slice(0, 5),
-  })
-
-  if (!llm) return fallback()
-
-  try {
-    const raw = await chatText(llm, system, user)
-    const parsed = parseStructuredJson(raw)
-    if (!parsed || typeof parsed.summary !== 'string' || !parsed.summary.trim()) return fallback()
-    const kw = Array.isArray(parsed.keywords) ? parsed.keywords.map(String).filter((k) => k).slice(0, 8) : []
-    return {
-      title: typeof parsed.title === 'string' && parsed.title.trim() ? parsed.title.trim() : chunk.title || sourcePath,
-      summary: summarizeText(parsed.summary.trim()),
-      blindSpots: typeof parsed.blindSpots === 'string' ? parsed.blindSpots.trim() : '',
-      keywords: kw.length ? kw : tokenize(chunk.title).slice(0, 5),
-    }
-  } catch {
-    return fallback()
-  }
-}

package/src/reflection-pipeline.js

@@ -10,6 +10,7 @@ import { ProjectMemoryStore } from './store.js'
 import { memoryRootFor } from './util/fs.js'
 import { cfgInsight, saveInsight, GlobalStore, defaultGlobalFile } from './insight-store.js'
 import { chatText, parseStructuredJson } from './llm.js'
+import { noteDegraded } from './llm-route.js'
 
 export const REFLECT_SYSTEM =
   'You distill task work into durable lessons and decisions for project memory. ' +
@@ -57,7 +58,7 @@ function normalizeList(arr, max) {
  * 对某任务做一次反思（可归档任务照做——归档正是收割时机）。
  * 全程 try/catch：调用方 fire-and-forget 即可。
  */
-export async function reflectTaskAfter({ config, llm, root, taskId, reason = 'transition' }) {
+export async function reflectTaskAfter({ config, llm, root, taskId, reason = 'transition', route = null }) {
   const rc = (config && config.reflection) || {}
   const fallback = { ok: false, skipped: 'disabled' }
   if (!rc.enabled) return fallback
@@ -67,6 +68,11 @@ export async function reflectTaskAfter({ config, llm, root, taskId, reason = 'tr
     const task = store.getTask(taskId)
     const gate = isReflectDue(config, task)
     if (!gate.due) return { ok: false, skipped: gate.reason }
+    // 路由检查放在门控之后：未到期/内容未变时不应留下 no-route 降级噪声
+    if (!route) {
+      noteDegraded('llm.reflect.no-route', 'no provider/model route for reflection; skipping this reflection')
+      return { ok: false, skipped: 'no-route' }
+    }
 
     const snap = taskReflectionSnapshot(task)
     const user =
@@ -75,7 +81,7 @@ export async function reflectTaskAfter({ config, llm, root, taskId, reason = 'tr
       (snap.files ? `Files touched:\n${snap.files.slice(0, 1000)}\n` : '') +
       `Trigger: ${reason}\n\nReturn the JSON object.`
 
-    const raw = await chatText(llm, REFLECT_SYSTEM, user, { timeoutMs: 90000 })
+    const raw = await chatText(llm, REFLECT_SYSTEM, user, { timeoutMs: 90000, route })
     const parsed = parseStructuredJson(raw)
     if (!parsed) return { ok: false, skipped: 'unparsable' }
 
@@ -136,10 +142,10 @@ export async function reflectTaskAfter({ config, llm, root, taskId, reason = 'tr
 }
 
 /** 工具/命令层 fire-and-forget：默认关时立刻廉价返回，绝不让错误上抛。 */
-export function fireReflect(config, host, root, taskId, reason) {
+export function fireReflect(config, host, root, taskId, reason, route = null) {
   const rc = (config && config.reflection) || {}
   if (!rc.enabled) return Promise.resolve({ ok: false, skipped: 'disabled' })
-  return reflectTaskAfter({ config, llm: host?.llm, root, taskId, reason }).catch((err) => {
+  return reflectTaskAfter({ config, llm: host?.llm, root, taskId, reason, route }).catch((err) => {
     console.error(`[dsh-project-memory] fireReflect error: ${err?.message || err}`)
     return { ok: false, skipped: 'error' }
   })

package/src/setup/taskbridge.js

@@ -146,8 +146,14 @@ export function touchTaskFile(task, rel, kind, now) {
     }
   }
   const m = task.fileMeta[rel] || {}
-  m.n = (m.n || 0) + 1
-  if (kind === 'write') m.lastWriteAt = now
+  m.n = (m.n || 0) + 1 // 兼容旧字段：读+写总数（保留，避免老任务语义漂移）
+  // 读/写分计数（先只采集，不消费 —— 排序与注入仍只用 lastWriteAt/lastReadAt）
+  if (kind === 'write') {
+    m.writes = (m.writes || 0) + 1
+    m.lastWriteAt = now
+  } else if (kind === 'read') {
+    m.reads = (m.reads || 0) + 1
+  }
   m.lastReadAt = now
   task.fileMeta[rel] = m
   task.files = hotSortFiles(task.files, task.fileMeta)

package/src/store.js

@@ -158,7 +158,7 @@ export class ProjectMemoryStore {
   }
 
   // ---- v0.5 insights：project 级 insight 文档（任务级在 task.insights[]） ----
-  // 迁移语义（与初版方案的差异，见 PLAN §10 风险 / 收尾说明）：
+  // 迁移语义（旧版 store 的兼容策略）：
   // v0.4 experience.json 仍由 remember/forget/query_memory 服务，不删除；
   // 首次加载把旧笔记**复制导入** insights.json（kind: experience, source: migrate），
   // migratedAt 落盘保证跨进程/崩溃幂等。销毁式收敛放到 recall 统一 PR。

package/src/tools/index-doc.js

@@ -11,8 +11,8 @@ export function indexDocTool(ctx, config) {
     name: 'index_doc',
     description:
       'Index a project document (PDF, Markdown, txt) into persistent project memory: split into sections, ' +
-      'summarize each with the LLM, and store cited summaries (path + line) for later query_memory recall. ' +
-      'Re-indexing the same unchanged file is a no-op (content-hash skip).',
+      'store a short cited summary plus a full-chunk literal term index (no LLM at index time), for later ' +
+      'query_memory recall. Re-indexing the same unchanged file is a no-op (content-hash skip).',
     parameters: {
       file_path: {
         type: 'string',
@@ -42,7 +42,7 @@ export function indexDocTool(ctx, config) {
         return `Skipped (unchanged): ${rel}\nAlready indexed with ${(store.entries[rel] || []).length} entry/entries.`
       }
 
-      const entries = await buildDocEntries(ctx.llm, rel, filePath, {
+      const entries = await buildDocEntries(rel, filePath, {
         chunkChars: config.chunkChars,
         maxChunks: config.maxChunksPerFile,
         maxFileSizeMb: config.maxFileSizeMb,

package/src/tools/index-repo.js

@@ -3,6 +3,7 @@ import path from 'node:path'
 import { statSync } from 'node:fs'
 import { 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'
 import { linkEntries } from '../link.js'
 import { ProjectMemoryStore } from '../store.js'
@@ -40,7 +41,9 @@ export async function indexRepository(ctx, config, root, { reindex = false } = {
 
       // 单次读盘：同一 buffer 供哈希与正文使用（不再 sha256OfFile + readFileSync 读两遍）
       const { hash, buffer } = readFileForIndex(filePath)
-      if (!reindex && existing && existing.sha256 === hash) {
+      // 旧 store 的 doc 条目缺 terms → 即使哈希未变也重抽一次（一次性回填）
+      const needsBackfill = isSupportedDoc(ext) && docEntriesNeedBackfill(store.entries[rel])
+      if (!reindex && existing && existing.sha256 === hash && !needsBackfill) {
         skipped++
         continue
       }
@@ -57,7 +60,7 @@ export async function indexRepository(ctx, config, root, { reindex = false } = {
           skipped++
           continue
         }
-        entries = await buildDocEntries(ctx.llm, rel, filePath, {
+        entries = await buildDocEntries(rel, filePath, {
           chunkChars: config.chunkChars,
           maxChunks: config.maxChunksPerFile,
           maxFileSizeMb: config.maxFileSizeMb,
@@ -123,7 +126,8 @@ export function indexRepoTool(ctx, config) {
   return defineTool({
     name: 'index_repo',
     description:
-      'Index a whole project into persistent memory. Documents (PDF/Markdown/txt) are summarized by the LLM; ' +
+      'Index a whole project into persistent memory. Documents (PDF/Markdown/txt) get a short cited summary plus ' +
+      'a full-chunk literal term index (no LLM at index time); ' +
       'code files get a zero-token symbol table (function/class names with line numbers). Incremental: only changed ' +
       'files are re-extracted (content-hash), deleted files are removed from memory. Call once per project, then query_memory.',
     parameters: {

package/src/tools/query-memory.js

@@ -3,6 +3,7 @@ import path from 'node:path'
 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 { truncate } from '../util/text.js'
 
@@ -49,7 +50,7 @@ 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()) {
@@ -77,7 +78,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)

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/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

@@ -2,6 +2,7 @@ import { existsSync, statSync } from 'node:fs'
 import path from 'node:path'
 import { isSupportedCode, isSupportedDoc, 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'
@@ -105,14 +106,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,