sillyspec 3.28.7 → 3.28.9

package/src/knowledge-classify.js

@@ -0,0 +1,363 @@
+/**
+ * knowledge-classify.js — knowledge classify 子命令核心（2026-09-14-knowledge-loop-close task-02）
+ *
+ * 职责：把 knowledge/uncategorized.md 中的条目迁移归类到目标知识文件，四步动作：
+ *   ①解析条目 → ②追加目标知识文件（`## <标题>` + 原文，先追加后删除保内容可 revert）
+ *   → ③INDEX.md 对应分类段补路由行（keywords 显式传或标题分词兜底，anchor=条目标题
+ *   机械生成，先例 knowledge/INDEX.md `#平台审核占位`）→ ④从 uncategorized.md 删除该段。
+ *
+ * 条目寻址三通道（X-001 双格式 + --title 兜底，按优先级）：
+ *   1. 标题行前缀 `## <qlId> | <标题>`（knowledge.js validate 契约格式）
+ *   2. 正文尾注 `（<qlId>）`（中文括号，quick.js 收尾指引格式；半角括号容忍）
+ *   3. titleFallback 模糊匹配条目标题（无 ql 标注历史条目兜底）
+ *
+ * 幂等：目标文件已含同标题条目 → 跳过追加（skippedReason='duplicate-title'）只做迁移
+ * 收尾（INDEX 路由 + 删除原条目）；INDEX 已含同 file#anchor 路由 → 不重复加行。
+ * --dry-run 只渲染将要发生的变更（返回 plan），不落盘（含审计零写盘）。
+ *
+ * 审计：归类动作经 task-01 的 appendKnowledgeHit（KnowledgeHitsAPI）落一行 type:classify
+ * 进 .runtime/knowledge-hits.jsonl；runtimeDir 缺省 = knowledgeDir/../.runtime。
+ *
+ * CRLF/LF 双容忍：读侧 \r\n 归一解析，写侧按各文件检测到的既有 EOL 回写/追加
+ * （uncategorized.md 可能 CRLF，主仓知识文件为 LF）。
+ */
+
+import { appendFileSync, existsSync, readFileSync } from 'fs'
+import { basename, dirname, join } from 'path'
+import { writeAtomicSync } from './fs-atomic.js'
+import { appendKnowledgeHit } from './knowledge-hits.js'
+
+// ── 常量与内部工具 ──
+
+// 目标文件（INDEX 相对 POSIX 路径）→ INDEX.md 分类段标题。
+// decisions/ 目录按前缀判定为 Decisions；四类之外的目标文件无处落路由行 → unknown_category。
+const CATEGORY_SECTIONS = {
+  'known-issues.md': 'Known Issues',
+  'patterns.md': 'Patterns',
+  'conventions.md': 'Conventions',
+}
+
+// 标题行 qlId 标注形态：`## ql-20260604-001-7a4c | <标题>` 的首 token
+const QL_TOKEN_RE = /^(?:ql|quick)-[a-z0-9][a-z0-9-]*$/i
+
+function escapeRegExp(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+function detectEol(content) {
+  return content.includes('\r\n') ? '\r\n' : '\n'
+}
+
+/**
+ * 目标文件路径归一：反斜杠转 POSIX、剥 './' 与冗余 'knowledge/' 前缀（--file 容错）。
+ * 'knowledge\known-issues.md' / './known-issues.md' → 'known-issues.md'
+ */
+function normalizeTargetFile(targetFile) {
+  let f = String(targetFile || '').trim().replace(/\\/g, '/')
+  if (!f) return ''
+  f = f.replace(/^\.\//, '')
+  if (f.startsWith('knowledge/')) f = f.slice('knowledge/'.length)
+  return f
+}
+
+/** 目标文件 → INDEX.md 分类段标题（known-issues/patterns/conventions/decisions 四类，其余 null） */
+function categoryForTarget(file) {
+  if (/^decisions\//.test(file)) return 'Decisions'
+  return CATEGORY_SECTIONS[basename(file)] || null
+}
+
+/**
+ * 标题分词兜底（--keywords 未显式传时的 keywords 来源，X-005）：
+ * 按空白 + Unicode 标点/符号切段（'|' 与 '→' 均 \p{S}/\p{P}，不会泄进关键词），
+ * 滤 <2 字符噪音 token，去重封顶 6 个；中文长短语保持整段
+ * （keywordMatchesContext 对非 ASCII 关键词用子串匹配，短语可命中）。
+ */
+function tokenizeTitle(title) {
+  return [...new Set(
+    String(title || '')
+      .split(/[\s\p{P}\p{S}]+/u)
+      .map(t => t.trim())
+      .filter(t => t.length >= 2)
+  )].slice(0, 6)
+}
+
+/** keywords 解析：显式传优先（滤空与含 '→'/换行的废值）；缺省/为空 → 标题分词兜底；仍空 → 标题本身 */
+function resolveKeywords(keywords, title) {
+  const explicit = (Array.isArray(keywords) ? keywords : [keywords])
+    .map(k => String(k || '').trim())
+    .filter(k => k && !k.includes('→') && !k.includes('\n'))
+  if (explicit.length > 0) return explicit
+  const tokens = tokenizeTitle(title)
+  return tokens.length > 0 ? tokens : [String(title || 'uncategorized')]
+}
+
+// ── uncategorized.md 条目解析（双格式寻址底座） ──
+
+/**
+ * 解析 uncategorized.md（\r\n 已归一的正文）为条目列表。
+ * 条目边界：`^#{2,3}\s+\S` 标题行——与 knowledge.js validate 的计数正则
+ * `/^#{2,3}\s+\S/gm` 同口径（h3 形态一并兼容）；h1 行终止当前条目但自身不是条目；
+ * h4 归入正文。start/end 为行号区间 [start, end)，end 止于下一标题边界行。
+ * @returns {{ start: number, end: number, headingText: string, qlIdPrefix: string|null,
+ *             title: string, body: string, text: string }[]}
+ */
+function parseUncategorizedEntries(normalizedContent) {
+  const lines = normalizedContent.split('\n')
+  const boundaryRe = /^#{1,3}\s+\S/
+  const entryHeadingRe = /^#{2,3}\s+\S/
+  const entries = []
+  let cur = null
+  for (let i = 0; i < lines.length; i++) {
+    if (!boundaryRe.test(lines[i])) continue
+    if (cur) { cur.end = i; entries.push(cur); cur = null }
+    if (entryHeadingRe.test(lines[i])) {
+      cur = { start: i, end: lines.length, headingText: lines[i].replace(/^#{2,3}\s+/, '').trim() }
+    }
+  }
+  if (cur) entries.push(cur)
+
+  for (const e of entries) {
+    // 标题行 qlId 前缀剥离：`## ql-xxx | <标题>` → title=`<标题>`；非 ql 形态首 token 不剥
+    const m = e.headingText.match(/^(\S+)\s*\|\s*(.*)$/)
+    if (m && QL_TOKEN_RE.test(m[1])) {
+      e.qlIdPrefix = m[1]
+      e.title = m[2].trim() || e.headingText
+    } else {
+      e.qlIdPrefix = null
+      e.title = e.headingText
+    }
+    e.body = lines.slice(e.start + 1, e.end).join('\n').trim()
+    e.text = e.headingText + '\n' + e.body
+  }
+  return entries
+}
+
+/** 三通道寻址：qlId 标题行前缀 → qlId 正文尾注（中文/半角括号）→ titleFallback 模糊（首个命中） */
+function locateEntry(entries, qlId, titleFallback) {
+  if (qlId) {
+    const headingRe = new RegExp(`^${escapeRegExp(qlId)}\\s*\\|`)
+    const byHeading = entries.find(e => headingRe.test(e.headingText))
+    if (byHeading) return { entry: byHeading, channel: 'ql-heading' }
+    const full = `（${qlId}）`
+    const half = `(${qlId})`
+    const bySuffix = entries.find(e => e.text.includes(full) || e.text.includes(half))
+    if (bySuffix) return { entry: bySuffix, channel: 'ql-suffix' }
+  }
+  if (titleFallback) {
+    const needle = String(titleFallback).toLowerCase()
+    const byTitle = entries.find(e =>
+      e.title.toLowerCase().includes(needle) || e.headingText.toLowerCase().includes(needle))
+    if (byTitle) return { entry: byTitle, channel: 'title-fallback' }
+  }
+  return { entry: null, channel: null }
+}
+
+/**
+ * INDEX.md 分类段内（或文件末尾新段）插入路由行，返回新的归一正文（'\n' 行尾）。
+ * 只增不改既有行；插入点 = 分类段内最后一个非空行之后（段缺失时 EOF 追加 `## <段>` + 行）。
+ */
+function insertRouteLine(indexNorm, category, routeLine) {
+  const lines = indexNorm.split('\n')
+  const sectionRe = new RegExp(`^##\\s+${escapeRegExp(category)}\\s*$`, 'i')
+  let sectStart = -1
+  for (let i = 0; i < lines.length; i++) {
+    if (sectionRe.test(lines[i])) { sectStart = i; break }
+  }
+  if (sectStart < 0) {
+    return indexNorm.replace(/\n+$/, '') + `\n\n## ${category}\n${routeLine}\n`
+  }
+  let lastContent = sectStart
+  for (let i = sectStart + 1; i < lines.length; i++) {
+    if (/^##\s+\S/.test(lines[i])) break
+    if (lines[i].trim() !== '') lastContent = i
+  }
+  lines.splice(lastContent + 1, 0, routeLine)
+  return lines.join('\n')
+}
+
+// ── 核心 ──
+
+/**
+ * 归类单个 uncategorized 条目到目标知识文件（四步迁移）。
+ *
+ * @param {object} params
+ * @param {string} params.knowledgeDir - knowledge 目录路径
+ * @param {string} [params.qlId] - quicklog 条目 ID（标题行前缀 ∪ 正文尾注双格式寻址）
+ * @param {string} params.targetFile - 目标知识文件（INDEX 相对，如 'known-issues.md'）
+ * @param {string} [params.sectionTitle] - 覆盖落盘条目标题（--section；anchor 随实际标题）
+ * @param {string[]} [params.keywords] - INDEX 路由行关键词（缺省按条目标题分词兜底）
+ * @param {string} [params.titleFallback] - 无 ql 标注历史条目的模糊匹配兜底（--title）
+ * @param {boolean} [params.dryRun] - 只渲染将要发生的变更，不落盘
+ * @param {string} [params.runtimeDir] - 审计目录（缺省 knowledgeDir/../.runtime）
+ * @returns {{ ok: boolean, moved: boolean, appendedTo: string|null, indexUpdated: boolean,
+ *             anchor: string, skippedReason?: string, error?: object,
+ *             dryRun?: boolean, title?: string, channel?: string, keywords?: string[], plan?: object }}
+ *   moved：真实迁移发生（条目已从 uncategorized 删除；dry-run 恒 false）；
+ *   skippedReason='duplicate-title'：目标已含同标题条目，跳过追加只做迁移收尾。
+ */
+export function classifyUncategorizedEntry({ knowledgeDir, qlId, targetFile, sectionTitle, keywords, titleFallback, dryRun, runtimeDir } = {}) {
+  const fail = (code, extra = {}) => ({
+    ok: false, moved: false, appendedTo: null, indexUpdated: false, anchor: '',
+    error: { code, ...extra },
+  })
+
+  // ① 前置校验
+  const file = normalizeTargetFile(targetFile)
+  if (!knowledgeDir || !existsSync(knowledgeDir)) return fail('knowledge_dir_missing', { path: knowledgeDir || null })
+  if (!file) return fail('target_file_required')
+  if (!qlId && !titleFallback) return fail('address_required', { message: 'qlId 与 titleFallback 至少传一个' })
+
+  const uncatPath = join(knowledgeDir, 'uncategorized.md')
+  if (!existsSync(uncatPath)) return fail('uncategorized_missing', { path: 'knowledge/uncategorized.md' })
+  const uncatRaw = readFileSync(uncatPath, 'utf8')
+  const uncatEol = detectEol(uncatRaw)
+  const uncatNorm = uncatRaw.replace(/\r\n/g, '\n')
+  const entries = parseUncategorizedEntries(uncatNorm)
+
+  const { entry, channel } = locateEntry(entries, qlId, titleFallback)
+  if (!entry) return fail('entry_not_found', { qlId: qlId || null, titleFallback: titleFallback || null })
+
+  const entryTitle = entry.title || entry.headingText
+  const finalTitle = String(sectionTitle || '').trim() || entryTitle
+  const anchor = finalTitle // anchor=条目标题机械生成（X-005 / R-03）
+
+  // ② 追加目标知识文件（幂等：同标题条目已存在 → 跳过追加只做迁移收尾）
+  const targetPath = join(knowledgeDir, file)
+  if (!existsSync(targetPath)) return fail('target_file_missing', { targetFile: file, path: targetPath })
+  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) {
+    // 追加块：空行 + `## <标题>` + 空行 + 原文 + 收尾换行（按目标文件既有 EOL）
+    const body = entry.body ? entry.body.replace(/\n/g, targetEol) : ''
+    appendBlock = ['', `## ${finalTitle}`, '', ...(body ? [body] : []), ''].join(targetEol)
+    if (targetRaw && !targetRaw.endsWith('\n')) appendBlock = targetEol + appendBlock
+  } else {
+    skippedReason = 'duplicate-title'
+  }
+
+  // ③ INDEX.md 对应分类段补路由行（不改既有行；同 file#anchor 已路由则不重复加）
+  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)
+
+  // --dry-run：只渲染将要发生的变更，不落盘（三个知识文件与 hits 审计均零写盘）
+  if (dryRun) {
+    return {
+      ok: true, dryRun: true, moved: false, appendedTo: file, indexUpdated: false,
+      anchor, title: finalTitle, channel, keywords: kws,
+      skippedReason: skippedReason || undefined,
+      plan: {
+        appendToTarget: !duplicate,
+        targetSectionHeading: `## ${finalTitle}`,
+        indexRouteLine: routeExists ? null : routeLine,
+        removeFromUncategorized: true,
+      },
+    }
+  }
+
+  // 落盘顺序（约束：先追加后删除，条目不丢内容、可手工搬运 revert）：
+  // 目标文件追加（append-only，既有字节不动）→ INDEX 原子写 → uncategorized 删除段原子写
+  if (appendBlock !== null) appendFileSync(targetPath, appendBlock, 'utf8')
+  if (newIndexNorm !== null) writeAtomicSync(indexPath, newIndexNorm.split('\n').join(indexEol))
+  const uncatLines = uncatNorm.split('\n')
+  uncatLines.splice(entry.start, entry.end - entry.start)
+  writeAtomicSync(uncatPath, uncatLines.join(uncatEol))
+
+  // 归类审计（task-01 KnowledgeHitsAPI；幂等重入同样留痕，skippedReason 随行记录）
+  const rt = runtimeDir || join(dirname(knowledgeDir), '.runtime')
+  appendKnowledgeHit(rt, {
+    type: 'classify',
+    qlId: qlId || entry.qlIdPrefix || undefined,
+    targetFile: file,
+    title: finalTitle,
+    channel,
+    skippedReason: skippedReason || undefined,
+  })
+
+  return {
+    ok: true, moved: true, appendedTo: file,
+    indexUpdated: newIndexNorm !== null,
+    anchor, title: finalTitle, channel, keywords: kws,
+    skippedReason: skippedReason || undefined,
+  }
+}
+
+// ── CLI 入口（形态对齐 src/stages/knowledge.js 的 cmdSearch：JSON 输出 + args.indexOf 解析） ──
+
+function output(ok, data, error) {
+  const result = { ok, ...data }
+  if (error) result.error = error
+  console.log(JSON.stringify(result, null, 2))
+}
+
+/**
+ * `sillyspec knowledge classify` 子命令入口（stages/knowledge.js 二级路由动态 import 转发）。
+ *
+ * 用法：classify (--ql <id> | --title <模糊>) --file <目标文件>
+ *               [--section <标题>] [--keywords kw1,kw2] [--dry-run]
+ * @param {string} dir - 项目根目录
+ * @param {string[]} args - 二级路由切掉 'classify' 后的参数
+ * @param {object} [opts] - { specDir, runtimeDir }
+ */
+export async function cmdKnowledgeClassify(dir, args, opts = {}) {
+  const base = opts.specDir || join(dir, '.sillyspec')
+  const knowledgeDir = join(base, 'knowledge')
+
+  const pick = (name) => {
+    const i = args.indexOf(name)
+    return i >= 0 && args[i + 1] ? args[i + 1] : ''
+  }
+  const qlId = pick('--ql')
+  const targetFile = pick('--file')
+  const sectionTitle = pick('--section')
+  const keywordsRaw = pick('--keywords')
+  const titleFallback = pick('--title')
+  const dryRun = args.includes('--dry-run')
+
+  if (!qlId && !titleFallback) {
+    output(false, {}, '--ql or --title is required')
+    return
+  }
+  if (!targetFile) {
+    output(false, {}, '--file is required')
+    return
+  }
+  const keywords = keywordsRaw
+    ? keywordsRaw.split(/[,，]/).map(s => s.trim()).filter(Boolean)
+    : undefined
+
+  const result = classifyUncategorizedEntry({
+    knowledgeDir,
+    qlId,
+    targetFile,
+    sectionTitle,
+    keywords,
+    titleFallback,
+    dryRun,
+    runtimeDir: opts.runtimeDir || join(base, '.runtime'),
+  })
+
+  if (result.ok) {
+    output(true, result)
+  } else {
+    output(false, {
+      moved: result.moved,
+      appendedTo: result.appendedTo,
+      indexUpdated: result.indexUpdated,
+      anchor: result.anchor,
+    }, result.error)
+  }
+}

package/src/knowledge-hits.js

@@ -0,0 +1,74 @@
+/**
+ * knowledge-hits.js — 知识闭环遥测事件流（.runtime/knowledge-hits.jsonl）
+ *
+ * 2026-09-14-knowledge-loop-close task-01 交付的共享底座（KnowledgeHitsAPI）：
+ * - 写：appendKnowledgeHit —— 每次恰好一行 JSON + '\n'（Node fs 不做换行翻译，Windows 下同为 LF）
+ * - 读：readKnowledgeHits —— 逐行 JSON.parse，坏行/残行跳过不抛（R-04：并发 append 交错容忍）
+ * - 记录类型：inject（机械注入命中，task-04 写入）/ classify（归类审计，task-02 写入）；
+ *   聚合侧 stats（task-05）统一经 readKnowledgeHits 读取
+ *
+ * 数据模型按 design.md：{"type":"inject"|"classify","change":…,"query":…,"matchedFiles":[…],"at":"ISO-8601"}
+ * classify 记录可携带 qlId/targetFile（字段原样序列化，不裁剪）。
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'fs'
+import { join } from 'path'
+
+const HITS_FILENAME = 'knowledge-hits.jsonl'
+
+function hitsFilePath(runtimeDir) {
+  return join(runtimeDir, HITS_FILENAME)
+}
+
+/**
+ * 追加一条遥测记录（目录/文件缺失自动创建）。
+ *
+ * @param {string} runtimeDir - .runtime 目录
+ * @param {object} hit - 记录对象，常用字段 { type:'inject'|'classify', change, query, matchedFiles, at }
+ *   （at 缺省时补当前 ISO 时间；其余字段原样序列化，classify 的 qlId/targetFile 等照写）
+ * @returns {object} 实际落盘的记录对象
+ */
+export function appendKnowledgeHit(runtimeDir, hit) {
+  const record = { ...hit }
+  if (record.at === undefined || record.at === null) {
+    record.at = new Date().toISOString()
+  }
+  mkdirSync(runtimeDir, { recursive: true })
+  appendFileSync(hitsFilePath(runtimeDir), JSON.stringify(record) + '\n', 'utf8')
+  return record
+}
+
+/**
+ * 读取遥测记录（坏行/残行容忍，解析失败不抛）。
+ *
+ * @param {string} runtimeDir - .runtime 目录
+ * @param {object} [opts] - { sinceDays }：仅保留 at 在近 N 天内的记录
+ *   （过滤启用时 at 缺失/不可解析的记录一并跳过——无法证明在窗口内）
+ * @returns {object[]} 解析成功的记录数组（文件缺失/为空 → []）
+ */
+export function readKnowledgeHits(runtimeDir, opts = {}) {
+  const file = hitsFilePath(runtimeDir)
+  if (!existsSync(file)) return []
+
+  const records = []
+  for (const line of readFileSync(file, 'utf8').split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed) continue
+    let record
+    try {
+      record = JSON.parse(trimmed)
+    } catch {
+      continue // 坏行/残行：跳过不抛（R-04）
+    }
+    if (!record || typeof record !== 'object' || Array.isArray(record)) continue
+    records.push(record)
+  }
+
+  const sinceDays = opts ? Number(opts.sinceDays) : NaN
+  if (!Number.isFinite(sinceDays) || sinceDays < 0) return records
+  const cutoff = Date.now() - sinceDays * 24 * 60 * 60 * 1000
+  return records.filter((record) => {
+    const at = Date.parse(record.at)
+    return Number.isFinite(at) && at >= cutoff
+  })
+}

package/src/knowledge-stats.js

@@ -0,0 +1,180 @@
+/**
+ * knowledge-stats.js — knowledge stats 子命令核心（2026-09-14-knowledge-loop-close task-05，FR-05 / D-002@v1）
+ *
+ * 职责：聚合 .runtime/knowledge-hits.jsonl 遥测事件流（task-01 KnowledgeHitsAPI 写入：
+ * task-04 注入点写 type:inject、task-02 classify 写 type:classify），输出近 N 天命中矩阵
+ * （文件 × 次数 × 最近命中时间）与从未命中清单（对照 INDEX.md 全集标注疑似死重）。
+ * 纯只读：不写 hits/INDEX/知识文件任何输入；死重清单只报告，不自动删除/合并（非目标）。
+ *
+ * 计数口径：
+ * - inject 记录：matchedFiles 每个条目（`file#anchor` 形态，prompt.js 注入侧逐条落盘）计 1 次
+ *   命中，归属剥 # 后的 file；classify 记录：targetFile 计 1 次（归类审计同样视作一次消费命中）；
+ * - lastHitAt = 引用该文件的记录 at 最大值（ISO 原样保留；sinceDays 窗口启时时幸存记录
+ *   必有可解析 at——readKnowledgeHits 契约滤掉 at 缺失/坏值，'' 兜底仅防御性）；
+ * - totalInjects / totalClassifies = 窗口内两类记录条数（按记录计，与 matrix 按条目计独立）；
+ * - 未知 type 不进矩阵不进计数（前向兼容：新事件类型不炸聚合）。
+ *
+ * neverHit：parseKnowledgeIndex（src/knowledge-match.js 同款解析）得 INDEX.md 唯一 file 全集
+ * （保持 INDEX 行序）减去 matrix 中出现过的 file。不在 INDEX 但被命中过的 file 照进 matrix
+ * （informative），不影响 neverHit。INDEX 缺失 → neverHit=[]（无对照面）。
+ *
+ * 空数据：hits.jsonl 缺失/无有效记录 → 空矩阵 + totals 0 + neverHit=INDEX 全集；CLI 人类可读
+ * 模式此时输出「暂无遥测数据」提示（--json 输出 hasTelemetry:false 供机读区分「无遥测」与
+ * 「窗口内无命中」两种空矩阵——后者死重对照无意义，人类可读模式同样略过 neverHit 段）。
+ */
+
+import { existsSync } from 'fs'
+import { join } from 'path'
+import { readKnowledgeHits } from './knowledge-hits.js'
+import { parseKnowledgeIndex } from './knowledge-match.js'
+
+// ── 聚合核心 ──
+
+/** `file#anchor` 引用 → file 部分（反斜杠归一 POSIX、剥首个 # 后段；空引用 → ''） */
+function fileOfRef(ref) {
+  const s = String(ref || '').trim().replace(/\\/g, '/')
+  if (!s) return ''
+  const hash = s.indexOf('#')
+  return (hash >= 0 ? s.slice(0, hash) : s).trim()
+}
+
+/**
+ * 聚合命中矩阵与死重对照。
+ *
+ * @param {string} knowledgeDir - knowledge 目录（INDEX.md 全集来源）
+ * @param {string} runtimeDir - .runtime 目录（knowledge-hits.jsonl 落点）
+ * @param {object} [opts] - { sinceDays = 30 }：仅统计近 N 天记录（at 过滤沿 readKnowledgeHits 契约，
+ *   坏行/残行读取侧已跳过）
+ * @returns {{ matrix: { file: string, hits: number, lastHitAt: string }[],
+ *             neverHit: string[], totalInjects: number, totalClassifies: number }}
+ *   matrix 按 hits 降序（同数按 file 字典序稳定 tie-break）；neverHit 保持 INDEX 行序。
+ */
+export function buildHitMatrix(knowledgeDir, runtimeDir, { sinceDays = 30 } = {}) {
+  const records = readKnowledgeHits(runtimeDir, { sinceDays })
+
+  const byFile = new Map()
+  const touch = (file, at) => {
+    if (!file) return
+    const row = byFile.get(file) || { file, hits: 0, lastHitAt: '', lastTs: -Infinity }
+    row.hits += 1
+    const ts = Date.parse(at)
+    if (Number.isFinite(ts) && ts >= row.lastTs) {
+      row.lastTs = ts
+      row.lastHitAt = String(at)
+    }
+    byFile.set(file, row)
+  }
+
+  let totalInjects = 0
+  let totalClassifies = 0
+  for (const record of records) {
+    if (record.type === 'inject') {
+      totalInjects += 1
+      const refs = Array.isArray(record.matchedFiles) ? record.matchedFiles : []
+      for (const ref of refs) touch(fileOfRef(ref), record.at)
+    } else if (record.type === 'classify') {
+      totalClassifies += 1
+      touch(fileOfRef(record.targetFile), record.at)
+    }
+  }
+
+  const matrix = [...byFile.values()]
+    .map(({ lastTs, ...row }) => row) // 内部时间比较键不下发
+    .sort((a, b) => b.hits - a.hits || (a.file < b.file ? -1 : a.file > b.file ? 1 : 0))
+
+  const hitFiles = new Set(matrix.map((row) => row.file))
+  const seen = new Set()
+  const neverHit = []
+  for (const entry of parseKnowledgeIndex(knowledgeDir)) {
+    const file = fileOfRef(entry.file)
+    if (!file || seen.has(file) || hitFiles.has(file)) continue
+    seen.add(file)
+    neverHit.push(file)
+  }
+
+  return { matrix, neverHit, totalInjects, totalClassifies }
+}
+
+// ── CLI 入口（形态对齐 src/stages/knowledge.js cmdSearch / src/knowledge-classify.js cmdKnowledgeClassify）──
+
+function outputJson(ok, data, error) {
+  const result = { ok, ...data }
+  if (error) result.error = error
+  console.log(JSON.stringify(result, null, 2))
+}
+
+/**
+ * `sillyspec knowledge stats` 子命令入口（stages/knowledge.js 二级路由动态 import 转发）。
+ *
+ * 用法：stats [--since-days N] [--json]
+ * 默认人类可读输出（命中矩阵表 + 从未命中清单 + 遥测计数）；--json 输出结构化结果
+ * （{ ok, sinceDays, hasTelemetry, matrix, neverHit, totalInjects, totalClassifies }）。
+ * 纯只读。
+ *
+ * @param {string} dir - 项目根目录
+ * @param {string[]} args - 二级路由切掉 'stats' 后的参数
+ * @param {object} [opts] - { specDir, runtimeDir }
+ */
+export async function cmdKnowledgeStats(dir, args, opts = {}) {
+  const base = opts.specDir || join(dir, '.sillyspec')
+  const knowledgeDir = join(base, 'knowledge')
+  const runtimeDir = opts.runtimeDir || join(base, '.runtime')
+
+  const pick = (name) => {
+    const i = args.indexOf(name)
+    return i >= 0 && args[i + 1] !== undefined ? args[i + 1] : ''
+  }
+  let sinceDays = 30
+  const sinceRaw = pick('--since-days')
+  if (sinceRaw !== '') {
+    const n = Number.parseInt(sinceRaw, 10)
+    if (!Number.isFinite(n) || n < 0) {
+      outputJson(false, {}, '--since-days must be a non-negative integer')
+      return
+    }
+    sinceDays = n
+  }
+  const asJson = args.includes('--json')
+
+  // 遥测在场判定用全量读取（不加窗口）：文件缺失/只有坏行 → 无遥测
+  const hasTelemetry = readKnowledgeHits(runtimeDir).length > 0
+  const result = buildHitMatrix(knowledgeDir, runtimeDir, { sinceDays })
+
+  if (asJson) {
+    outputJson(true, { sinceDays, hasTelemetry, ...result })
+    return
+  }
+
+  const lines = []
+  lines.push(`📚 knowledge stats（近 ${sinceDays} 天，数据源 .runtime/knowledge-hits.jsonl）`)
+  lines.push('')
+
+  if (!hasTelemetry) {
+    lines.push('暂无遥测数据（hits.jsonl 缺失或无有效记录）——机械注入（execute/quick prompt）与 knowledge classify 产生命中后此处可查')
+    lines.push('')
+  } else if (result.matrix.length === 0) {
+    lines.push(`近 ${sinceDays} 天无命中记录（可用 --since-days 扩大窗口；窗口内死重对照无意义，已略过）`)
+    lines.push('')
+  } else {
+    const fileCol = Math.max(2, ...result.matrix.map((row) => row.file.length))
+    lines.push('命中矩阵（按次数降序）：')
+    lines.push(`  ${'文件'.padEnd(fileCol)}  命中  最近命中`)
+    for (const row of result.matrix) {
+      const last = row.lastHitAt ? row.lastHitAt.slice(0, 10) : '—'
+      lines.push(`  ${row.file.padEnd(fileCol)}  ${String(row.hits).padStart(4)}  ${last}`)
+    }
+    lines.push('')
+    if (!existsSync(join(knowledgeDir, 'INDEX.md'))) {
+      lines.push('（knowledge/INDEX.md 缺失——从未命中清单无从对照）')
+    } else if (result.neverHit.length > 0) {
+      lines.push('从未命中（对照 INDEX 全集，疑似死重——仅报告，不自动删除/合并）：')
+      for (const file of result.neverHit) lines.push(`  - ${file}`)
+    } else {
+      lines.push('INDEX 路由的全部文件在窗口内均有过命中（无死重）')
+    }
+    lines.push('')
+  }
+
+  lines.push(`遥测计数（窗口内）：注入 ${result.totalInjects} 次 | 归类 ${result.totalClassifies} 次`)
+  console.log(lines.join('\n'))
+}

package/src/local-detect.js

@@ -15,26 +15,41 @@ import { join } from 'path'
 
 /**
  * 从 Makefile 文本提取 test 目标的命令（轻量正则，与 verify-postcheck 同风格）。
- * 支持两种常见写法：
- *   - 同行命令：`test: pytest`            → 'pytest'
- *   - tab 续行：`test:\n\tpytest\n`        → 'pytest'（命令在下一 tab 开头行）
+ * 支持的写法（按 make 语义）：
+ *   - tab/空格 缩行配方：`test:\n\tpytest\n`   → 'pytest'
+ *   - `;` 同行配方：`test: ; pytest`            → 'pytest'
+ *   - 行内其他非空内容是 prerequisite（`test: unit integration`），不是命令——配方照常
+ *     向下找缩行；无配方回退 'make test'（make 会先跑依赖目标，语义正确）
  * 边界：
- *   - 纯空目标（`test:` 无同行命令、无 tab 续行）→ 回退 'make test'
- *   - 命令行内 `#` 注释截断；取第一个非空命令行
+ *   - 配方行以「下一个非缩进非空行」为界——空目标后跳进后续目标的配方是旧版缺陷
+ *     （ql-20260911-029 复现：`test:\nbuild:\n\tnpm run build` 旧正则返回 'npm run build'）
+ *   - `test := x` 变量赋值不匹配 test 目标；命令行内 `#` 注释截断
  * @param {string} makefileText
  * @returns {string}
  */
-function parseMakefileTestCommand(makefileText) {
+export function parseMakefileTestCommand(makefileText) {
   if (!makefileText) return 'make test'
-  // 定位 `test:` 行；捕获 `:` 后同行内容（同行命令或空）
-  const head = makefileText.match(/^test:\s*([^\n#]*?)\s*(?:#.*)?$/m)
-  if (!head) return 'make test'
-  const inline = (head[1] || '').trim()
-  if (inline) return inline
-  // 同行为空 → 找该行之后第一个 tab 续行命令（`\tcmd` 或 `    cmd`）
-  const after = makefileText.slice(head.index + head[0].length)
-  const cont = after.match(/^[ \t]+([^\n#]+?)\s*(?:#.*)?$/m)
-  if (cont && cont[1]) return cont[1].trim()
+  const lines = String(makefileText).split(/\r?\n/)
+  // (?!=) 排除 `test :=` 变量赋值形态
+  const testIdx = lines.findIndex(l => /^test:(?!=)/.test(l))
+  if (testIdx === -1) return 'make test'
+  const inline = lines[testIdx].slice(lines[testIdx].indexOf('test:') + 'test:'.length).trim()
+  const semicolonRecipe = inline.match(/^;\s*(.+)$/)
+  if (semicolonRecipe) {
+    const cmd = semicolonRecipe[1].replace(/\s+#.*$/, '').trim()
+    if (cmd) return cmd
+  }
+  // 向下扫配方：第一条缩进行即 test 的配方（tab 或空格缩进）；遇非缩进非空行（下一
+  // 目标/变量/指令）即边界——空行与列 0 注释不构成边界
+  for (let i = testIdx + 1; i < lines.length; i++) {
+    const line = lines[i]
+    if (line.trim() === '' || line.startsWith('#')) continue
+    if (/^[ \t]+\S/.test(line)) {
+      const cmd = line.replace(/^[ \t]+/, '').replace(/\s+#.*$/, '').trim()
+      return cmd || 'make test'
+    }
+    return 'make test'
+  }
   return 'make test'
 }