sillyspec 3.34.1 → 3.34.2

package/src/knowledge-classify.js

@@ -22,7 +22,7 @@
  * （uncategorized.md 可能 CRLF，主仓知识文件为 LF）。
  */
 
-import { appendFileSync, existsSync, readFileSync } from 'fs'
+import { appendFileSync, existsSync, readFileSync, readdirSync, rmSync } from 'fs'
 import { basename, dirname, join } from 'path'
 import { writeAtomicSync } from './fs-atomic.js'
 import { appendKnowledgeHit } from './knowledge-hits.js'
@@ -30,11 +30,16 @@ import { appendKnowledgeHit } from './knowledge-hits.js'
 // ── 常量与内部工具 ──
 
 // 目标文件（INDEX 相对 POSIX 路径）→ INDEX.md 分类段标题。
-// decisions/ 目录按前缀判定为 Decisions；四类之外的目标文件无处落路由行 → unknown_category。
+// decisions/ 目录按前缀判定为 Decisions；五类之外的目标文件无处落路由行 → unknown_category。
+// gotchas 双目标（2026-11-07-knowledge-k-shape-minimal）：工具/测试坑知识此前被迫落
+// known-issues 语义错位（2026-11-06 六条合入已现此妥协）——INDEX 无对应段时由
+// insertRouteLine 既有 EOF 追加语义兜底，不假设段名在场。
 const CATEGORY_SECTIONS = {
   'known-issues.md': 'Known Issues',
   'patterns.md': 'Patterns',
   'conventions.md': 'Conventions',
+  'sillyspec-gotchas.md': 'SillySpec Gotchas',
+  'testing-gotchas.md': 'Testing Gotchas',
 }
 
 // 标题行 qlId 标注形态：`## ql-20260604-001-7a4c | <标题>` 的首 token
@@ -295,7 +300,177 @@ export function classifyUncategorizedEntry({ knowledgeDir, qlId, targetFile, sec
   }
 }
 
-// ── CLI 入口（形态对齐 src/stages/knowledge.js 的 cmdSearch：JSON 输出 + args.indexOf 解析） ──
+// ── proposed 收口通道（2026-11-07-knowledge-accept-channel）─────────────────────
+
+/**
+ * 待审知识生效目标（--file 可省时的 category 自动路由白名单，INDEX 相对 basename）。
+ * 与 CATEGORY_SECTIONS 同源——decisions/ 不收 proposed（决策走蒸馏管道，不走人工合入）。
+ */
+const ACCEPT_TARGETS = new Set(['known-issues', 'patterns', 'conventions', 'sillyspec-gotchas', 'testing-gotchas'])
+
+/**
+ * K 形态结构完整度启发式（2026-11-07-knowledge-k-shape-minimal FR-02）：有效知识最小
+ * 结构 = 「问题」段 + 解法类段（解法/规则/模式/约定任一）。标题措辞启发式检测——
+ * advisory 不阻断（历史形态多元，硬门留完整 K 契约变更裁决）。
+ */
+function structuralWarningsFor(body) {
+  const warnings = []
+  // 行首锚定已足（\b 在纯中文后失效——中文非 \w，词边界断言恒 false）
+  if (!/^#{1,3}\s*问题/m.test(body)) warnings.push('缺「问题」段标题（现象/根因宜以「## 问题」开头）')
+  if (!/^#{1,3}\s*(解法|规则|模式|约定)/m.test(body)) warnings.push('缺解法类段标题（「## 解法/规则/模式/约定」任一——可执行结论是有效知识的最小结构）')
+  return warnings
+}
+
+/**
+ * 合并单个 proposed/ 待审条目到正式知识文件（proposed 收口通道 FR-01~04）。
+ *
+ * 复用 classifyUncategorizedEntry 的全部迁移原语（追加块/duplicate 判定/INDEX 路由行/
+ * keywords 解析/EOL 检测），差异仅在源侧：读 proposed/<slug>.md（frontmatter category +
+ * `#` 标题 + 正文，剥 cmdPropose 生成的尾注块）→ 删除整个源文件（区别于 classify 删
+ * uncategorized 段）。落盘顺序对齐 classify：先追加后 INDEX 后删源（中断最坏态可幂等收敛）。
+ *
+ * 复活防线（2026-11-07-sync-proposed-no-revive）：accept 删本地源文件后，下次 spec-sync
+ * 按「服务器有本地无 → delete」自然下发删除，平台待审区同步清位——无复活面。
+ */
+function acceptProposedEntry({ knowledgeDir, id, targetFile, keywords, sectionTitle, dryRun, runtimeDir } = {}) {
+  const fail = (code, extra = {}) => ({
+    ok: false, moved: false, appendedTo: null, indexUpdated: false, anchor: '',
+    error: { code, ...extra },
+  })
+
+  // ① id 归一：proposed/<slug> 或裸 slug → 目录内文件名（拒绝路径穿越形态）
+  let slug = String(id || '').trim().replace(/\\/g, '/')
+  if (slug.startsWith('proposed/')) slug = slug.slice('proposed/'.length)
+  if (!knowledgeDir || !existsSync(knowledgeDir)) return fail('knowledge_dir_missing', { path: knowledgeDir || null })
+  if (!slug || slug.includes('/') || slug.includes('..') || slug === '.') return fail('proposed_invalid_id', { id })
+  const srcPath = join(knowledgeDir, 'proposed', `${slug}.md`)
+  if (!existsSync(srcPath)) return fail('proposed_not_found', { id })
+
+  // ② 解析 proposed 文件：frontmatter(category/proposed_at) + `#` 标题 + 正文（剥尾注块）
+  const norm = readFileSync(srcPath, 'utf8').replace(/\r\n/g, '\n')
+  const fm = {}
+  const fmBlock = norm.match(/^---\n([\s\S]*?)\n---\n/)
+  if (fmBlock) {
+    for (const line of fmBlock[1].split('\n')) {
+      const m = line.match(/^([A-Za-z_][\w-]*)\s*:\s*(.*)$/)
+      if (m) fm[m[1].toLowerCase()] = m[2].trim()
+    }
+  }
+  const titleMatch = norm.match(/^#\s+(.+)$/m)
+  if (!titleMatch) return fail('proposed_invalid', { id, reason: '缺少 # 标题行' })
+  const entryTitle = titleMatch[1].trim()
+  let body = norm.slice(norm.indexOf(titleMatch[0]) + titleMatch[0].length)
+  // 剥 cmdPropose 生成的尾注分隔块（'---\n> This is a proposed knowledge entry...'）
+  body = body.replace(/\n+---\s*\n>\s*This is a proposed knowledge entry[\s\S]*$/, '').trim()
+
+  const finalTitle = String(sectionTitle || '').trim() || entryTitle
+  const anchor = finalTitle
+  // K 形态结构完整度 advisory（2026-11-07-knowledge-k-shape-minimal FR-02）：缺段列警告
+  // 不阻断——dry-run 与正式路径同携（见两处返回的 structuralWarnings 键）。
+  const structuralWarnings = structuralWarningsFor(body)
+
+  // ③ 目标文件：--file 显式优先 > frontmatter category 自动路由（FR-02）
+  let file = normalizeTargetFile(targetFile || '')
+  if (!file) {
+    const cat = String(fm.category || '').trim().replace(/\.md$/, '')
+    if (ACCEPT_TARGETS.has(cat)) file = `${cat}.md`
+    else return fail('target_file_required', {
+      category: fm.category || null,
+      message: 'category 无效或缺失，须显式 --file（known-issues/patterns/conventions/sillyspec-gotchas/testing-gotchas 五目标）',
+    })
+  }
+  const targetPath = join(knowledgeDir, file)
+  if (!existsSync(targetPath)) return fail('target_file_missing', { targetFile: file, path: targetPath })
+
+  // ④ 追加块 + duplicate 幂等（口径逐字对齐 classifyUncategorizedEntry ②段）
+  const targetRaw = readFileSync(targetPath, 'utf8')
+  const targetEol = detectEol(targetRaw)
+  const dupRe = new RegExp(`^##\\s+${escapeRegExp(finalTitle)}\\s*$`, 'm')
+  const duplicate = dupRe.test(targetRaw.replace(/\r\n/g, '\n'))
+  let appendBlock = null
+  let skippedReason
+  if (!duplicate) {
+    const b = body ? body.replace(/\n/g, targetEol) : ''
+    appendBlock = ['', `## ${finalTitle}`, '', ...(b ? [b] : []), ''].join(targetEol)
+    if (targetRaw && !targetRaw.endsWith('\n')) appendBlock = targetEol + appendBlock
+  } else {
+    skippedReason = 'duplicate-title'
+  }
+
+  // ⑤ INDEX 路由行（口径对齐 classifyUncategorizedEntry ③段）
+  const category = categoryForTarget(file)
+  if (!category) return fail('unknown_category', { targetFile: file })
+  const indexPath = join(knowledgeDir, 'INDEX.md')
+  if (!existsSync(indexPath)) return fail('index_missing', { path: 'knowledge/INDEX.md' })
+  const indexRaw = readFileSync(indexPath, 'utf8')
+  const indexEol = detectEol(indexRaw)
+  const indexNorm = indexRaw.replace(/\r\n/g, '\n')
+  const kws = resolveKeywords(keywords, finalTitle)
+  const display = `${file}#${anchor}`
+  const routeLine = `- ${kws.join('|')} → [${display}](${display})`
+  const routeExists = indexNorm.split('\n').some((l) => l.includes(`](${display})`))
+  const newIndexNorm = routeExists ? null : insertRouteLine(indexNorm, category, routeLine)
+
+  if (dryRun) {
+    return {
+      ok: true, dryRun: true, moved: false, appendedTo: file, indexUpdated: false,
+      anchor, title: finalTitle, keywords: kws, skippedReason: skippedReason || undefined,
+      ...(structuralWarnings.length > 0 ? { structuralWarnings } : {}),
+      plan: {
+        appendToTarget: !duplicate,
+        targetSectionHeading: `## ${finalTitle}`,
+        indexRouteLine: routeExists ? null : routeLine,
+        removeFromProposed: `knowledge/proposed/${slug}.md`,
+      },
+    }
+  }
+
+  // 落盘顺序（对齐 classify 约束：先追加后删除，条目不丢内容、可手工搬运 revert）
+  if (appendBlock !== null) appendFileSync(targetPath, appendBlock, 'utf8')
+  if (newIndexNorm !== null) writeAtomicSync(indexPath, newIndexNorm.split('\n').join(indexEol))
+  rmSync(srcPath, { force: true })
+
+  const rt = runtimeDir || join(dirname(knowledgeDir), '.runtime')
+  appendKnowledgeHit(rt, {
+    type: 'accept',
+    targetFile: file,
+    title: finalTitle,
+    skippedReason: skippedReason || undefined,
+  })
+
+  return {
+    ok: true, moved: true, appendedTo: file,
+    indexUpdated: newIndexNorm !== null,
+    anchor, title: finalTitle, keywords: kws,
+    skippedReason: skippedReason || undefined,
+    ...(structuralWarnings.length > 0 ? { structuralWarnings } : {}),
+  }
+}
+
+/** 列出 proposed/ 待审清单（inbox 消费段 FR-05）：slug + 标题 + 积压天数。空目录返回 []。 */
+export function listProposedPending(knowledgeDir) {
+  const propDir = join(knowledgeDir, 'proposed')
+  if (!existsSync(propDir)) return []
+  const now = Date.now()
+  return readdirSync(propDir)
+    .filter((f) => f.endsWith('.md'))
+    .map((f) => {
+      const slug = f.replace(/\.md$/, '')
+      let title = slug
+      let ageDays = null
+      try {
+        const norm = readFileSync(join(propDir, f), 'utf8').replace(/\r\n/g, '\n')
+        title = norm.match(/^#\s+(.+)$/m)?.[1]?.trim() || slug
+        const at = norm.match(/^proposed_at:\s*(.+)$/m)?.[1]?.trim()
+        const ts = at ? Date.parse(at) : NaN
+        if (Number.isFinite(ts)) ageDays = Math.max(0, Math.floor((now - ts) / 86400000))
+      } catch { /* 单文件解析失败按 slug 兜底展示 */ }
+      return { slug, title, ageDays }
+    })
+    .sort((a, b) => (b.ageDays ?? 0) - (a.ageDays ?? 0))
+}
+
+
 
 function output(ok, data, error) {
   const result = { ok, ...data }
@@ -413,12 +588,24 @@ export async function cmdKnowledgeInbox(dir, args, opts = {}) {
     qlId: e.qlIdPrefix || null,
     summary: String(e.body || '').replace(/\s+/g, ' ').slice(0, 80),
   }))
+  // proposed 待审清单（2026-11-07-knowledge-accept-channel FR-05）：json 面恒挂键；文本面
+  // 非空渲染——渲染件在空收件箱早退**之前**（评审 P1 修复：早退吞清单致默认人读路径
+  // 违反 FR-05）。
+  const proposed = listProposedPending(knowledgeDir)
+  const renderProposed = () => {
+    if (proposed.length === 0) return
+    console.log(`📬 待审提议（proposed/ ${proposed.length} 条）——确认后 knowledge accept --id proposed/<slug> 合并生效：`)
+    proposed.forEach((p, i) => {
+      console.log(`  ${i + 1}. 《${p.title}》${p.ageDays !== null ? `（积压 ${p.ageDays} 天）` : ''}`)
+    })
+  }
   if (wantJson) {
-    output(true, { inbox: { count: entries.length, baseline, over, items } })
+    output(true, { inbox: { count: entries.length, baseline, over, items, proposed } })
     return
   }
   if (entries.length === 0) {
     console.log('📚 知识收件箱：空——uncategorized 无待审条目')
+    renderProposed()
     return
   }
   console.log(`📚 知识收件箱：待审 ${entries.length} 条${baseline !== null ? `（基线 ${baseline}${over ? '，已超 ⚠️' : ''}）` : ''}`)
@@ -427,4 +614,43 @@ export async function cmdKnowledgeInbox(dir, args, opts = {}) {
     if (it.summary) console.log(`     ${it.summary}`)
   })
   console.log('   归类：sillyspec knowledge classify --title "…" --file conventions|patterns|known-issues.md')
+  renderProposed()
+}
+
+/**
+ * `sillyspec knowledge accept` 子命令入口（2026-11-07-knowledge-accept-channel）：
+ * 合并单个 proposed/ 待审条目到正式知识文件（用户确认后由 agent/人执行）。
+ * 参数解析形态对齐 cmdSearch（args.indexOf + flag-as-value 防护）。
+ */
+export async function cmdKnowledgeAccept(dir, args, opts = {}) {
+  const base = opts.specDir || join(dir, '.sillyspec')
+  const knowledgeDir = join(base, 'knowledge')
+  const grab = (flag) => {
+    const i = args.indexOf(flag)
+    const v = i >= 0 ? args[i + 1] : ''
+    return v && !v.startsWith('--') ? v : ''
+  }
+  const id = grab('--id')
+  const targetFile = grab('--file')
+  const sectionTitle = grab('--section')
+  const kwRaw = grab('--keywords')
+  const dryRun = args.includes('--dry-run')
+  if (!id) {
+    output(false, {}, '--id is required（proposed/<slug>）')
+    return
+  }
+  const r = acceptProposedEntry({
+    knowledgeDir,
+    id,
+    targetFile: targetFile || undefined,
+    keywords: kwRaw ? kwRaw.split(',').map((s) => s.trim()).filter(Boolean) : undefined,
+    sectionTitle: sectionTitle || undefined,
+    dryRun,
+  })
+  if (r.ok) {
+    const { error: _e, ...data } = r
+    output(true, data)
+  } else {
+    output(false, {}, r.error)
+  }
 }

package/src/knowledge-digest.js

@@ -17,6 +17,7 @@
 import { existsSync, readFileSync, readdirSync } from 'fs'
 import { join } from 'path'
 import { readFrBindings, resolveTestFileRel, testAnchorFile } from './test-bindings.js'
+import { listProposedPending } from './knowledge-classify.js'
 
 /** 伪域判定：auto- 前缀（scaffold 时代机器蒸馏域）或 unmapped 池 */
 const isPseudoDomain = (domain) => /^auto[-_]/.test(domain) || domain === 'unmapped'
@@ -161,6 +162,24 @@ export function collectKnowledgeDigest({ specBase, projectRoot }) {
       inboxTitles.slice(0, 5).join('；') + (inboxTitles.length > 5 ? ' 等' : ''),
       'sillyspec knowledge inbox 看清单 → knowledge classify --ql <id> --file <known-issues.md|patterns.md|conventions.md> [--dry-run] 逐条归类')
   }
+  // ③ proposed 待审积压（2026-11-07-knowledge-accept-channel FR-05）：此前 proposed 积压
+  // 零信号（本仓 6 条 46 天无人知）——与收件箱同款双档（info 可见 / 超阈 warn），阈值 6 取
+  // 本仓当前积压实证量级。
+  let proposedPending = []
+  const propDir = join(knowledgeRoot, 'proposed')
+  if (existsSync(propDir)) {
+    proposedPending = listProposedPending(knowledgeRoot)
+    totals.proposed = proposedPending.length
+  }
+  if (totals.proposed >= 6) {
+    mk('proposed', 'warn', `待审知识积压（proposed ${totals.proposed} 条 ≥ 6）`, totals.proposed,
+      proposedPending.slice(0, 5).map((p) => p.title).join('；') + (proposedPending.length > 5 ? ' 等' : ''),
+      'sillyspec knowledge inbox 看清单 → 确认后 knowledge accept --id proposed/<slug> 合并生效')
+  } else if (totals.proposed > 0) {
+    mk('proposed', 'info', `待审知识 ${totals.proposed} 条（proposed）`, totals.proposed,
+      proposedPending.slice(0, 5).map((p) => p.title).join('；') + (proposedPending.length > 5 ? ' 等' : ''),
+      '确认后 knowledge accept --id proposed/<slug> 合并生效')
+  }
   if (totals.pseudo > 0) {
     mk('pseudo-domain', 'warn', `伪域在库（auto-*/unmapped 共 ${totals.pseudo} 条）`, totals.pseudo,
       [...pseudoByDomain.entries()].map(([d, n]) => `${d} ${n}`).join('、'),

package/src/knowledge-match.js

@@ -286,6 +286,21 @@ export function keywordMatchesContext(keyword, contextLower) {
   return new RegExp(`(^|[^a-z0-9_])${escapeRegex(kw)}([^a-z0-9_]|$)`).test(contextLower)
 }
 
+/** 检索结果 → 命中通道单源判定（routing/vector/fallback/scope，2026-11-05-knowledge-search-
+ *  observability FR-04）：注入遥测 channel 字段与 search 面通道行同口径。放本叶子模块（而非
+ *  knowledge-vector.js）——stages/execute.js 静态导入本函数，若从 knowledge-vector 导入会形成
+ *  stages/index→execute→knowledge-vector→…→stages/index 的 TDZ 环（execute.js 头注释 2026-09-14
+ *  实证同型坑）。json 判别键与各层构造方一致（fallbackByQueryShingles/buildResultFromPlatform/
+ *  buildScopeRecallResult 的 json 标记）。 */
+export function resultChannel(result) {
+  const json = result && result.json
+  if (!json) return 'routing'
+  if (json.fallback) return 'fallback'
+  if (json.vector) return 'vector'
+  if (json.scope) return 'scope'
+  return 'routing'
+}
+
 /** 查询词片抽取：CJK 连续段 bigram ＋ ≥4 字符 ASCII 词（小写；短词与标点数字不参与；
  *  纯 ASCII 查询不产词片——中文知识库，英文查询维持既有零命中行为）。
  *  snake/kebab 复合词保留整词并额外产出 ≥4 字符拆分片段（FR-02：查询 worktree_apply 时
@@ -430,6 +445,93 @@ export function fallbackByQueryShingles(indexDir, taskContext) {
   }
 }
 
+/**
+ * 正文词片兜底（2026-11-06-knowledge-body-recall FR-01）：普通知识文件 `##` 段落语料的
+ * 查询词片召回——四层检索既有语料均不含普通文件正文（根因见该变更 design），本通道补位。
+ *
+ * - 语料：INDEX 引用的普通知识文件（排除 decisions/fr 路由行——各有专用通道；排除停车场
+ *   文件），按 `## ` 切段，段落=锚点级命中单元。
+ * - 词片：复用 queryShingles（无新分词逻辑；纯 ASCII 查询零词片=零产出，既有语义边界）。
+ * - 窗判定（D-002 段落覆盖数口径，非 decisions 通道的绝对次数窗）：词片**覆盖的段落数**
+ *   n_segs ∈ [2, max(2, ceil(8% × 该文件段落总数))] 才算「跨段复现且非泛在」——绝对次数
+ *   窗在正文语料会误杀稀有词（实测 5% 次数窗上限恒 2，正文出现 3-5 次的稀有词被误判泛在，
+ *   依据 .sillyspec/.runtime/logs/bigram-stats.log：泛在词「目录」段覆盖 19.3%、「会话」
+ *   11.9% vs 稀有词「重开」1.8%、「问题」3.7%，8% 取分界带）。
+ * - 已修复段落过滤（FR-04）：段落含 `- 状态：已修复/已解决/已退役` 状态行时跳过（口径对齐
+ *   isResolvedRoute 的正文状态行判据）。
+ * - 无可命中段落返回 null（保持调用方零命中语义，对齐 fallbackByQueryShingles 契约）。
+ */
+export function fallbackByBodyShingles(indexDir, taskContext) {
+  const shingles = queryShingles(taskContext)
+  if (shingles.length === 0) return null
+  const entries = parseKnowledgeIndex(indexDir)
+  if (entries.length === 0) return null
+
+  const byFile = new Map()
+  for (const e of entries) {
+    const file = String(e.file || '').replace(/\\/g, '/')
+    // 专用通道文件（decisions/fr 路由行）与停车场不入正文语料
+    if (/^decisions\//.test(file) || /^fr\//.test(file) || isParkingFile(file)) continue
+    if (!byFile.has(file)) byFile.set(file, [])
+    byFile.get(file).push(e)
+  }
+
+  const hits = []
+  for (const [file] of byFile) {
+    let content
+    try {
+      content = readFileSync(join(indexDir, file), 'utf8').replace(/\r\n?/g, '\n')
+    } catch { continue /* 文件不可读跳过（fail-soft，对齐 isResolvedRoute 读取容错） */ }
+    // `## ` 切段；段头之后的正文参与词片判定
+    const blocks = content.split(/^## /m).slice(1)
+    if (blocks.length === 0) continue
+    const segs = blocks.map((b) => {
+      const lines = b.split('\n')
+      return { heading: lines[0].trim(), text: b.toLowerCase() }
+    })
+    // 已修复段落过滤（FR-04）
+    const active = segs.filter((s) => !/^\s*-\s*状态[：:]\s*(已修复|已解决|已退役)/m.test(s.text))
+    const ceil = Math.max(2, Math.ceil(active.length * 0.08))
+    // 词片 → 覆盖段落数（段落覆盖口径）；窗内词片按段落聚合
+    const segHitCount = new Map()
+    const inWindow = new Set()
+    for (const sh of shingles) {
+      let n = 0
+      for (const s of active) if (s.text.includes(sh)) n++
+      if (n >= 2 && n <= ceil) {
+        inWindow.add(sh)
+        for (const s of active) if (s.text.includes(sh)) segHitCount.set(s, (segHitCount.get(s) || 0) + 1)
+      }
+    }
+    if (inWindow.size === 0) continue
+    const entry = byFile.get(file)[0]
+    for (const s of active) {
+      const score = segHitCount.get(s) || 0
+      if (score === 0) continue
+      hits.push({
+        file,
+        anchor: s.heading,
+        keywords: [...inWindow].filter((sh) => s.text.includes(sh)),
+        display: `${s.heading}（正文词片命中）`,
+        category: entry.category || '',
+        score,
+      })
+    }
+  }
+  if (hits.length === 0) return null
+  hits.sort((a, b) => b.score - a.score)
+  const top = hits.slice(0, 10)
+  return {
+    matched: true,
+    entries: top,
+    report: `Status: body fallback matched (${top.length} segments in ${byFile.size} files)`,
+    json: {
+      matched: true, entry_count: top.length, fallback: true, bodyFallback: true,
+      entries: top.map((e) => ({ file: e.file, anchor: e.anchor, keywords: e.keywords, category: e.category })),
+    },
+  }
+}
+
 /**
  * 用任务上下文匹配知识条目
  * @param {string} indexDir - knowledge 目录路径

package/src/knowledge-vector.js

@@ -38,9 +38,21 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { runtimeStatePath } from './runtime-paths.js'
 import { join, dirname } from 'path'
 import { readPlatformConfig } from './sync.js'
-import { matchByRouting, fallbackByQueryShingles, parseDecisionEntries, isParkingFile } from './knowledge-match.js'
+import { matchByRouting, fallbackByQueryShingles, fallbackByBodyShingles, parseDecisionEntries, isParkingFile, resultChannel } from './knowledge-match.js'
+
+export { resultChannel }
+
+/** 向量召回 HTTP 预算（ms）。缺省 5000 覆盖平台 embedding worker 冷启 1~3s + 查询嵌入
+ *  （2026-11-04-knowledge-vector-async-refresh 平台侧修复的配套议题——旧缺省 3000 在
+ *  worker 闲置自灭后的首查必超时白降级一次）；env SILLYSPEC_KNOWLEDGE_VECTOR_TIMEOUT_MS
+ *  正整数覆盖，非法值回落缺省（2026-11-05-knowledge-search-observability FR-01）。 */
+const VECTOR_TIMEOUT_MS_DEFAULT = 5000
+
+export function resolveVectorTimeoutMs(env = process.env) {
+  const raw = Number(env.SILLYSPEC_KNOWLEDGE_VECTOR_TIMEOUT_MS)
+  return Number.isFinite(raw) && Number.isInteger(raw) && raw > 0 ? raw : VECTOR_TIMEOUT_MS_DEFAULT
+}
 
-const VECTOR_TIMEOUT_MS = 3000
 const ENDPOINT_PATH = '/api/spec/knowledge/vector-search'
 /** 能力缓存重试窗：unavailable 记录 1h 内不再探测（平台部署后最迟 1h 自动启用）。 */
 const CAPABILITY_RETRY_MS = 60 * 60 * 1000
@@ -142,7 +154,7 @@ const vectorDeadEndpoints = new Set()
  * 平台向量召回（纯 HTTP 层）。未连接/失败/形态不符 → null（调用方降级）。
  * @returns {Promise<{results: Array<{spec_path: string, anchor: string, score: number}>}|null>}
  */
-export async function platformVectorRecall({ cwd, query, limit = 10, timeoutMs = VECTOR_TIMEOUT_MS }) {
+export async function platformVectorRecall({ cwd, query, limit = 10, timeoutMs = resolveVectorTimeoutMs() }) {
   const cfg = readPlatformConfig(cwd)
   if (!cfg || !cfg.url || !cfg.token) return null
   const base = String(cfg.url).replace(/\/+$/, '')
@@ -215,9 +227,23 @@ export function buildResultFromPlatform(indexDir, pvResults) {
       file,
       anchor: rs[0].anchor,
       display: `${file}（平台向量召回）`,
+      // search 面真实分透出（FR-03）：该文件命中的最高余弦分——buildSearchMatches
+      // 对 vector 通道用它替代 keywords∩query 计数（原先恒 0 是错值不只是缺值）
+      vectorScore: Math.max(...rs.map((r) => (typeof r.score === 'number' ? r.score : 1))),
     })
   }
   if (decisionHits.length === 0) return null
+  // 跨文件同键去重（FR-02，2026-11-05-knowledge-search-observability）：epoch 迁移/蒸馏
+  // fanout 遗留同 (id, change) 条目在多个域文件存副本（实测 798 条中 104 重复槽位，top10
+  // 曾被 5 条副本挤占）——键含 change||''（无 change 的同号跨变更是诚实形态不误并），保分高
+  const byKey = new Map()
+  for (const h of decisionHits) {
+    const key = `${h.id}\u0000${h.change || ''}`
+    const cur = byKey.get(key)
+    if (!cur || h.score > cur.score) byKey.set(key, h)
+  }
+  decisionHits.length = 0
+  decisionHits.push(...byKey.values())
   decisionHits.sort((a, b) =>
     (b.score - a.score) ||
     (((b.status === 'rejected' || b.deathPath) ? 1 : 0) - ((a.status === 'rejected' || a.deathPath) ? 1 : 0))
@@ -254,6 +280,31 @@ async function fuseBaseWithScope(base, indexDir, scopeFiles) {
   } catch { return base }
 }
 
+/**
+ * 路由命中结果的正文词片并联融合（2026-11-06-knowledge-body-recall FR-02）：弱命中不短路
+ * 的根因修复——路由命中（哪怕泛词 tag 撞词的弱命中）此前直接 return，正文写了相关词的普通
+ * 知识文件段落永久不可见。body 兜底命中按 `file#anchor` 键去重后**追加**顶层 entries 尾部
+ * （路由命中原序不动；`json.entries` 不同步——全仓零消费点，仅在 json 面挂 bodyFallback 判
+ * 定键）；本路径零网络（「路由命中零网络」契约保持）。fail-soft：body 兜底异常原样返回 base。
+ */
+function fuseRoutingWithBodyFallback(base, indexDir, taskContext) {
+  try {
+    const body = fallbackByBodyShingles(indexDir, taskContext)
+    if (!body) return base
+    const seen = new Set(base.entries.map((e) => `${String(e.file || '').replace(/\\/g, '/')}#${e.anchor || ''}`))
+    const additions = body.entries.filter((e) => {
+      const key = `${String(e.file || '').replace(/\\/g, '/')}#${e.anchor || ''}`
+      if (seen.has(key)) return false
+      seen.add(key)
+      return true
+    })
+    if (additions.length === 0) return base
+    base.entries = [...base.entries, ...additions]
+    base.json = { ...(base.json || {}), bodyFallback: true }
+    return base
+  } catch { return base }
+}
+
 /**
  * 异步三层检索入口（四消费方使用：flow 注入段／complete 门／prompt {DECISION_HITS}／
  * knowledge search CLI）：路由 → 平台向量（已连接且开关开）→ scope 遍历 → 本地词片 → 空。
@@ -269,7 +320,9 @@ export async function matchKnowledgeHybrid(indexDir, taskContext, opts = {}) {
     // 融合（2026-11-02-knowledge-fusion）：路由命中后仍跑 scope——热文件触达的 rejected/手工条目
     // 原先被 early-return 永久遮住。只追加 scopeDecisionHits/scopeEntries（不重排路由结果）；
     // scope 构建失败原样返回路由结果；仍不跑平台向量（路由命中零网络）。
-    return fuseBaseWithScope(r, indexDir, scopeFiles)
+    // 正文词片并联（2026-11-06-knowledge-body-recall FR-02）：同一 early-return 也遮正文——
+    // body 兜底先行并联（零网络），scope 融合照旧。
+    return fuseBaseWithScope(fuseRoutingWithBodyFallback(r, indexDir, taskContext), indexDir, scopeFiles)
   }
   const cwd = opts.cwd || dirname(dirname(String(indexDir)))
   if (vectorEnabled(cwd)) {
@@ -289,5 +342,6 @@ export async function matchKnowledgeHybrid(indexDir, taskContext, opts = {}) {
     } catch { /* 图构建 fail-soft——降级词片层 */ }
   }
   const fb = fallbackByQueryShingles(indexDir, taskContext)
-  return fb || r
+  // 零命中链末端补跑（FR-01）：decisions 词片回退优先，无果时普通文件正文兜底接管
+  return fb || fallbackByBodyShingles(indexDir, taskContext) || r
 }

package/src/route-hindsight.js

@@ -15,8 +15,10 @@
  *   - 标记文件 route-hindsight.json：per-repo 单条，每次标记整文件覆盖——提示语义即
  *     「上个轻量变更」。
  *
- * 指标四元组（口径）：
- *   designRewriteRatio / tasksRewriteRatio：终稿 vs 首版快照的行级改写比——复用
+ * 指标口径（判定三元组 + 观测一路）：
+ *   designRewriteRatio（判定 >0.5）/ tasksRewriteRatio（仅观测，判定已退役
+ *     2026-11-08-hindsight-tasks-ratio-retire——种子=v3 成功标准转写，横幅明文要求改写，
+ *     正常与不清不可分离）：终稿 vs 首版快照的行级改写比——复用
  *     flow-draft.computeEditRatio 同款 LCS 口径（改写行/首版行数，纯增行不计入；CRLF/LF
  *     归一后比对）。diff 面先做结构归一：剔 frontmatter 块、HTML 注释标记行（<!--）、空行
  *     ——惰性脚手架行（机器稿里约占半数）会把真实换血稀释到阈值以下（实测整写机器段仅得
@@ -39,11 +41,15 @@ import { writeAtomicSync } from './fs-atomic.js'
 import { computeEditRatio } from './flow-draft.js'
 import { runtimeStatePath } from './runtime-paths.js'
 
-/** 超阈判定常量（可调；口径：比例两路为严格大于——恰等于阈值不算超，保守防误标 R-01；
- * 计数两路为大于等于——2 维/2 次即系统性信号）。 */
+/** 超阈判定常量（可调；口径：比例路为严格大于——恰等于阈值不算超，保守防误标 R-01；
+ * 计数两路为大于等于——2 维/2 次即系统性信号）。
+ * tasksRewriteRatio 判定退役（2026-11-08-hindsight-tasks-ratio-retire）：种子自
+ * 2026-10-07-thin-tasks-v3 起为成功标准逐条转写（验收句≠实现步骤，文体必然不同），
+ * 且 flow start 横幅明文要求「机器种子按真实实现路径改写、增删改随意」——正常改写与
+ * 需求不清的改写不可区分（0.875/0.8 两连误标实证），阈值无分离度。计算面保留为观测
+ * （computeHindsightMetrics 照算照返回），未来有证据可重定口径后再恢复判定。 */
 export const HINDSIGHT_THRESHOLDS = {
   designRewriteRatio: 0.5, // design 机器稿改写比 > 0.5（50% 首版行被改写）
-  tasksRewriteRatio: 0.6,  // tasks 机器预填稿改写率 > 0.6
   blindDims: 2,            // 评审盲维命中（dimensionNotes='finding'）≥ 2 维
   testFailures: 2,         // 收口实测失败记录 ≥ 2 次
 }
@@ -229,9 +235,8 @@ export function markHindsight({ cwd, specBase, change, metrics }) {
   if (num(m.designRewriteRatio) > HINDSIGHT_THRESHOLDS.designRewriteRatio) {
     reasons.push(`design 机器稿改写比 ${num(m.designRewriteRatio)} > ${HINDSIGHT_THRESHOLDS.designRewriteRatio}`)
   }
-  if (num(m.tasksRewriteRatio) > HINDSIGHT_THRESHOLDS.tasksRewriteRatio) {
-    reasons.push(`tasks 机器预填稿改写率 ${num(m.tasksRewriteRatio)} > ${HINDSIGHT_THRESHOLDS.tasksRewriteRatio}`)
-  }
+  // tasksRewriteRatio 判定退役（2026-11-08-hindsight-tasks-ratio-retire）——metrics 字段
+  // 仍随标记文件落盘（观测面，向后兼容读取），不再参与判定与 reasons。
   if (num(m.blindDims) >= HINDSIGHT_THRESHOLDS.blindDims) {
     reasons.push(`评审盲维命中 ${num(m.blindDims)} 维 ≥ ${HINDSIGHT_THRESHOLDS.blindDims}`)
   }