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

package/src/auto-inject.js

@@ -15,7 +15,9 @@ import { cfgInsight, GlobalStore, defaultGlobalFile } from './insight-store.js'
 import { projectTags } from './project-profile.js'
 import { rankEntriesMergedScored } from './util/search.js'
 import { insightToEntry } from './recall.js'
-import { buildReadinessContext, hintQueryText, matchTrigger, relativeHits } from './readiness.js'
+import { buildReadinessContext, hintQueryText, idfCoverage, matchTrigger, normalizeTrigger, relativeHits } from './readiness.js'
+import { activityFromCalls } from './ops.js'
+import { appendInjectionAudit, auditRecordFrom, cfgAudit } from './audit.js'
 
 export const INJECT_MARK = '[Memory Inject]'
 
@@ -52,6 +54,25 @@ export function cfgEngine(config) {
     // 0（默认）= 内容没变就不再注入：注入消息会留在会话历史里（宿主不压缩历史），
     // 整块重发同一条 1200 字 procedure 只是重复占位。>0 用于历史可能被外部裁剪的场景。
     reinjectItemsAfter: typeof c.reinjectItemsAfter === 'number' && c.reinjectItemsAfter >= 0 ? c.reinjectItemsAfter : 0,
+    // ---- S2/S3/S4 新增（准入化改造） ----
+    // 旧 `scope` 的处理：'filter'（默认，保留旧语义——不静默改用户数据）或 'ignore'。
+    // 注意：实测里唯一带 scope 的条目，其值不在项目画像 tag 空间内，等于被判死刑；
+    // 自检会把它报出来，由作者决定改值还是改语义。
+    legacyScope: c.legacyScope === 'ignore' ? 'ignore' : 'filter',
+    // 条目通道的步间隔：两次"条目注入"之间至少隔这么多步（常驻任务卡不受限——它是状态快照，
+    // 内容变了就该更新）。这是"不频繁"的主要旋钮。
+    gateCooldownSteps: typeof c.gateCooldownSteps === 'number' && c.gateCooldownSteps >= 0 ? c.gateCooldownSteps : 2,
+    // 每会话条目注入的上限（条数 / 字符）：预算只能是上限，不是目标。
+    maxItemsPerSession: typeof c.maxItemsPerSession === 'number' && c.maxItemsPerSession >= 0 ? c.maxItemsPerSession : 12,
+    maxItemCharsPerSession: typeof c.maxItemCharsPerSession === 'number' && c.maxItemCharsPerSession >= 0 ? c.maxItemCharsPerSession : 4000,
+    // 提示通道的**绝对**下限（IDF 加权覆盖率）：相对阈值分不出"有信号"和"矮子里拔将军"。
+    // null = 关闭（回到只有相对阈值的老行为）。
+    hintMinCoverage: typeof c.hintMinCoverage === 'number' && c.hintMinCoverage >= 0 ? c.hintMinCoverage : 0.3,
+    // 提示通道还要求至少这么多个共同词：单个通用词（"插件"）也能拿到 coverage=1.00。
+    hintMinMatched: typeof c.hintMinMatched === 'number' && c.hintMinMatched >= 0 ? c.hintMinMatched : 2,
+    // 通道级沉默：查询里能在语料中找到对应的词占比低于这个值时，整条提示通道本轮不出声。
+    // 长句子里只有一两个词碰巧命中，coverage 会虚高到 1.00——这条门就是为它设的。
+    hintMinSupport: typeof c.hintMinSupport === 'number' && c.hintMinSupport >= 0 ? c.hintMinSupport : 0.15,
   }
 }
 
@@ -130,8 +151,9 @@ export function buildEntryContent(task, cfg, { withEdited = true } = {}) {
   return parts.join('\n')
 }
 
-/** 候选池：project + global + 绑定任务（同一 id 只取一次；归档/草稿不进注入）。 */
-function insightCandidates(store, globalStore, task) {
+/** 候选池：project + global + 绑定任务（同一 id 只取一次；归档/草稿不进注入）。
+ * 候选在进入匹配前统一走旧 trigger → 新 schema 的归一（幂等，纯内存，不落盘）。 */
+function insightCandidates(store, globalStore, task, opts) {
   const out = []
   const seen = new Set()
   const push = (it) => {
@@ -139,7 +161,7 @@ function insightCandidates(store, globalStore, task) {
     const key = it.id || `${it.kind}:${it.title}`
     if (seen.has(key)) return
     seen.add(key)
-    out.push(it)
+    out.push(normalizeTrigger(it, { legacyScope: opts?.legacyScope }))
   }
   for (const it of (store ? store.insightItems() : []) || []) push(it)
   for (const it of (globalStore ? globalStore.items() : []) || []) push(it)
@@ -181,34 +203,44 @@ export function buildInjection(opts) {
   const { query, task, globalStore, cfg } = opts
   const store = opts.store || null
   const tags = opts.projectTagsList || []
-  const ctx = buildReadinessContext(opts.readiness || { humanText: query || '' })
+  const ctx = buildReadinessContext({ ...(opts.readiness || { humanText: query || '' }), tags })
   const labels = []
   const reasons = []
   const dropped = []
   const parts = []
-  const budgetChars = (cfg.maxTokens || 400) * 3
+  // 预算只能是上限，不是目标：单轮额度（maxTokens）与会话级剩余额度取小者。
+  const quotaChars = typeof opts.maxChars === 'number' ? opts.maxChars : Infinity
+  const maxItems = typeof opts.maxItems === 'number' ? opts.maxItems : Infinity
+  const skipItems = opts.skipItems === true
+  const budgetChars = Math.max(0, Math.min((cfg.maxTokens || 400) * 3, quotaChars))
 
   const skipItem = typeof opts.skipItem === 'function' ? opts.skipItem : null
-  const cands = insightCandidates(store, globalStore, task).filter((it) => !(skipItem && skipItem(it)))
+  const cands = insightCandidates(store, globalStore, task, cfg).filter((it) => !(skipItem && skipItem(it)))
 
   // 通道 1：authored trigger —— 确定性、全文、优先级 1。procedure 先于其它 kind（步骤更完整）。
+  // 准入化（S2）：只有 `when`（op / 写目标 / 意图词）能触发，guard 只能收窄；
+  // **没有 `when` 的条目在这里永远不命中**（降级为可发现 + 按需拉取）。
   const triggered = []
   for (const it of cands) {
     const why = matchTrigger(it.trigger, ctx)
     if (!why) continue
-    const scope = it.trigger?.scope
-    if (Array.isArray(scope) && scope.length && tags.length && !scope.some((s) => tags.includes(s))) continue
     triggered.push({ it, why })
   }
   triggered.sort(
     (a, b) => (a.it.kind === 'procedure' ? 0 : 1) - (b.it.kind === 'procedure' ? 0 : 1)
       || String(a.it.id).localeCompare(String(b.it.id)),
   )
+  if (skipItems) {
+    // 会话级限流命中：条目通道本轮整体沉默，但把"本该注入什么"记进 dropped——不做静默降级。
+    for (const t of triggered) dropped.push({ id: t.it.id, channel: 'trigger', reason: opts.silenceReason || 'cooldown' })
+  }
 
-  // 通道 2：统计信号 —— 提示态、优先级 2，判据是层内相对阈值（尺度无关）。
-  // procedure 只走 trigger 通道：否则会被统计通道绕过 trigger.scope 的画像过滤。
+  // 通道 2：统计信号 —— 提示态、优先级 2。**双门槛**：层内相对阈值 + IDF 加权覆盖率（绝对下限）。
+  // 查询只用「人类消息的意图文字 + 本次写目标」：原始工具参数不再进查询，它们正是
+  // `dcterms→rm`、`*.pptx→论文笔记` 那类假阳性的来源。procedure 不进本通道（要过 trigger.scope）。
   const consumed = new Set(triggered.map((t) => t.it.id))
-  const hintCands = cands.filter((it) => !consumed.has(it.id) && it.kind !== 'procedure')
+  const hintCands = skipItems ? [] : cands.filter((it) => !consumed.has(it.id) && it.kind !== 'procedure')
+  const hintQuery = [ctx.intent || ctx.humanText || '', ...(ctx.targets || [])].filter(Boolean).join(' ')
   const hints = []
   if (hintCands.length) {
     if (typeof cfg.relevanceMin === 'number') {
@@ -218,17 +250,37 @@ export function buildInjection(opts) {
         if (score >= cfg.relevanceMin) hints.push({ it, score, why: `overlap:${score.toFixed(3)}` })
       }
       hints.sort((a, b) => b.score - a.score)
-    } else {
+    } else if (hintQueryText(hintQuery)) {
       const byId = new Map(hintCands.map((it) => [it.id, it]))
-      // 提示查询先剔除 1–2 字符的拉丁缩写（PR/CI/OS）：它们一个巧合命中就能当上该层最高分。
-      const scored = rankEntriesMergedScored(
-        hintCands.map(insightToEntry),
-        [hintQueryText(ctx.humanText), hintQueryText(ctx.actionText)].filter(Boolean),
-        hintCands.length,
-      )
+      const corpus = hintCands.map((it) => insightMatchText(it))
+      // 查询与被测覆盖率的文本用**同一个**过滤后的查询：否则缩写（wsl/npm）会在 BM25 里被剔除、
+      // 却仍在覆盖率里计分，"至少两个共同词"就被它们凑够了。
+      const q = hintQueryText(hintQuery)
+      const scored = rankEntriesMergedScored(hintCands.map(insightToEntry), [q], hintCands.length)
+      const coverage = new Map(hintCands.map((it, i) => [it.id, idfCoverage(q, corpus[i], corpus)]))
+      const qStats = coverage.get(hintCands[0].id) || { supported: 0, terms: 0 }
+      const supportRatio = qStats.terms > 0 ? qStats.supported / qStats.terms : 0
+      // 通道级沉默：查询里绝大多数词在语料里根本没有对应 → "覆盖率 1.00"只是假象。
+      const channelThin = typeof cfg.hintMinSupport === 'number' && supportRatio < cfg.hintMinSupport
       for (const r of relativeHits(scored, { ratioMin: cfg.signalMinRatio })) {
         const it = byId.get(r.entry.insightId)
-        if (it) hints.push({ it, score: r.score, why: `relative:${(r.score / (scored[0].score || 1)).toFixed(2)}` })
+        if (!it) continue
+        const ev = coverage.get(it.id) || { coverage: 0, matched: 0, supported: 0, terms: 0 }
+        if (channelThin) {
+          dropped.push({ id: it.id, channel: 'hint', reason: `support:${supportRatio.toFixed(2)}` })
+          continue
+        }
+        // 绝对门槛：覆盖率下限 + 共同词数下限（查询本身很短时下限按可用词数收敛）。
+        if (typeof cfg.hintMinCoverage === 'number' && ev.coverage < cfg.hintMinCoverage) {
+          dropped.push({ id: it.id, channel: 'hint', reason: `coverage:${ev.coverage.toFixed(2)}` })
+          continue
+        }
+        const needMatched = Math.min(typeof cfg.hintMinMatched === 'number' ? cfg.hintMinMatched : 2, ev.supported)
+        if (ev.matched < needMatched) {
+          dropped.push({ id: it.id, channel: 'hint', reason: `thin:${ev.matched}` })
+          continue
+        }
+        hints.push({ it, score: r.score, why: `relative:${(r.score / (scored[0].score || 1)).toFixed(2)} cov:${ev.coverage.toFixed(2)}/${ev.matched}` })
       }
     }
   }
@@ -239,35 +291,48 @@ export function buildInjection(opts) {
   const entry = echo ? buildEntryContent(task, cfg) : ''
   const entryStable = echo ? buildEntryContent(task, cfg, { withEdited: false }) : ''
   let used = entry.length
+  let itemCount = 0
 
   for (const { it, why } of triggered) {
+    if (skipItems) break
+    if (itemCount >= maxItems) {
+      dropped.push({ id: it.id, channel: 'trigger', reason: 'quota' })
+      continue
+    }
     const body = fitBody(insightBody(it), budgetChars - used, MIN_BODY_CHARS.trigger)
     if (body === null) {
       dropped.push({ id: it.id, channel: 'trigger', reason: 'budget' })
       continue
     }
     used += body.length + 1
+    itemCount++
     parts.push(body)
     labels.push(it.kind === 'procedure' ? 'procedure' : it.kind)
-    reasons.push({ id: it.id, channel: 'trigger', why, hash: insightItemHash(it) })
+    reasons.push({ id: it.id, channel: 'trigger', why, hash: insightItemHash(it), chars: body.length })
   }
   for (const { it, why } of hints) {
+    if (skipItems) break
+    if (itemCount >= maxItems) {
+      dropped.push({ id: it.id, channel: 'hint', reason: 'quota' })
+      continue
+    }
     const body = fitBody(insightBody(it), budgetChars - used, MIN_BODY_CHARS.hint)
     if (body === null) {
       dropped.push({ id: it.id, channel: 'hint', reason: 'budget' })
       continue
     }
     used += body.length + 1
+    itemCount++
     parts.push(body)
     labels.push('hint')
-    reasons.push({ id: it.id, channel: 'hint', why, hash: insightItemHash(it) })
+    reasons.push({ id: it.id, channel: 'hint', why, hash: insightItemHash(it), chars: body.length })
   }
 
   const total = [entry, ...parts].filter(Boolean)
-  if (!total.length) return { text: '', labels, reasons, dropped }
+  if (!total.length) return { text: '', entry, labels, reasons, dropped }
   const clamp = (t) => (t.length > budgetChars ? `${t.slice(0, budgetChars)}\n…(截断)` : t)
   const dedupeText = clamp([entryStable, ...parts].filter(Boolean).join('\n'))
-  return { text: clamp(total.join('\n')), labels, reasons, dropped, dedupeText }
+  return { text: clamp(total.join('\n')), entry, entryStable, labels, reasons, dropped, dedupeText, itemChars: used - entry.length }
 }
 
 /** 注册 agent/pre-step 监听，向每步请求的 enter 决策追加记忆消息（默认开）。
@@ -278,6 +343,8 @@ export function installAutoInject(ctx, config) {
   const auto = (config && config.autoContext) || {}
   if (auto.enabled === false) return
   const cfg = cfgEngine(config)
+  // 审计配置同 cfg：安装时解析一次（与 autoContext 其余开关一致）。
+  const audit = cfgAudit(config)
   // 每个会话一份“上次注入指纹”。用单个变量会让并发会话互相抑制注入。
   const lastFpBySession = new Map()
   const LAST_FP_MAX = 200
@@ -291,6 +358,9 @@ export function installAutoInject(ctx, config) {
   const INJECTED_ITEMS_MAX = 600
   // 会话步数：为 reinjectItemsAfter 提供时间轴（>0 时才用得上）。
   const stepBySession = new Map()
+  // 会话级条目额度（S3）：条数 / 字符 / 上次"条目注入"的步号。常驻任务卡不占这个额度——
+  // 它是状态快照，内容变了就该更新；被限流的是记忆条目的推送。
+  const budgetBySession = new Map()
   // 反应窗口：本会话最近观察到的 tool/call（参数里有 git commit / npm publish / 改动的路径）。
   // 宿主没有"工具执行前拦截"钩子，所以这是 pre-step 之外唯一能拿到的动作事实。
   const observedBySession = new Map()
@@ -318,6 +388,7 @@ export function installAutoInject(ctx, config) {
       observedBySession.clear()
       injectedBySession.clear()
       stepBySession.clear()
+      budgetBySession.clear()
     })
   }
   ctx.on('agent/pre-step', async (payload, next) => {
@@ -336,15 +407,21 @@ export function installAutoInject(ctx, config) {
       const sessionId = session && session.id
       if (!root || !sessionId) return decision
       const query = lastUserText(decision.messages)
-      const store = new ProjectMemoryStore(memoryRootFor(root, config.memoryDir)).load()
+      const memoryRoot = memoryRootFor(root, config.memoryDir)
+      const store = new ProjectMemoryStore(memoryRoot).load()
       const globalStore = new GlobalStore(cfgInsight(config).globalFile || defaultGlobalFile()).load()
       const boundTaskId = store.getBoundTaskId(sessionId) ? store.getBoundTaskId(sessionId) : null
       const task = boundTaskId ? store.getTask(boundTaskId) : null
       // 两个窗口合并进同一个就绪上下文：人类消息（先发）+ 已观察动作（反应）。
+      // 动作平面（S1）：把"最近做过什么"解析成 op / 写目标 / 主机——不再把原始参数当文本搜。
       const observed = observedBySession.get(sessionId) || []
+      const activity = activityFromCalls(observed)
       const readiness = buildReadinessContext({
         humanText: query || '',
         actionText: observed.map((c) => `${c.name} ${c.arguments}`).join('\n'),
+        ops: activity.ops,
+        targets: activity.targets,
+        hosts: activity.hosts,
       })
       // 条目级去重：本会话已注入过、且正文未变的条目不再参与排程（cfg.reinjectItemsAfter=0 时永久，
       // >0 时走冷却步数，用于历史可能被外部裁剪的场景）。正文变了（编辑过 insight）立刻允许重发。
@@ -364,7 +441,31 @@ export function installAutoInject(ctx, config) {
             const rec = seen.get(it.id)
             return Boolean(rec) && rec.hash === insightItemHash(it) && stepNo - rec.step < cooldown
           }
-      const built = buildInjection({ query: query || '', readiness, task, store, globalStore, projectTagsList: projectTags(root), cfg, skipItem })
+      // 会话级限流（S3）：冷却步数 / 条目条数 / 条目字符。三个任一触顶 → 条目通道整体沉默，
+      // 但本轮"本该注入什么"仍会进 dropped（不做静默降级）。
+      const budget = budgetBySession.get(sessionId) || { items: 0, chars: 0, lastStep: -Infinity }
+      budgetBySession.set(sessionId, budget)
+      while (budgetBySession.size > LAST_FP_MAX) budgetBySession.delete(budgetBySession.keys().next().value)
+      const cooling = Number.isFinite(budget.lastStep) && stepNo - budget.lastStep < cfg.gateCooldownSteps
+      const itemsLeft = Math.max(0, cfg.maxItemsPerSession - budget.items)
+      const charsLeft = Math.max(0, cfg.maxItemCharsPerSession - budget.chars)
+      const silenceReason = cooling ? 'cooldown'
+        : itemsLeft === 0 ? 'session-items'
+          : charsLeft === 0 ? 'session-chars' : null
+      const built = buildInjection({
+        query: query || '',
+        readiness,
+        task,
+        store,
+        globalStore,
+        projectTagsList: projectTags(root),
+        cfg,
+        skipItem,
+        skipItems: silenceReason !== null,
+        silenceReason: silenceReason || 'cooldown',
+        maxItems: itemsLeft,
+        maxChars: charsLeft,
+      })
       const fp = fingerprint(built.dedupeText ?? built.text)
       const shouldInject = Boolean(built.text) && fp !== lastFpBySession.get(sessionId)
       let injectMessage = null
@@ -378,6 +479,12 @@ export function installAutoInject(ctx, config) {
           if (r && r.id && r.hash) seen.set(r.id, { hash: r.hash, step: stepNo })
         }
         while (seen.size > INJECTED_ITEMS_MAX) seen.delete(seen.keys().next().value)
+        // 会话额度只被"条目"消耗；任务卡不算（否则任务一多就把记忆挤没了）。
+        if (built.reasons.length) {
+          budget.items += built.reasons.length
+          budget.chars += typeof built.itemChars === 'number' ? built.itemChars : 0
+          budget.lastStep = stepNo
+        }
         injectMessage = createUserMessage({
           content: [{ type: 'text', text: `\n\n${INJECT_MARK} auto-context\n${built.text}` }],
           // 这一块是「同一生产者后续快照会取代的当前状态」，不是一次性通知。
@@ -410,7 +517,21 @@ export function installAutoInject(ctx, config) {
           }
         }
       }
-      if (injectMessage) return { ...decision, messages: [...decision.messages, injectMessage] }
+      if (injectMessage) {
+        // S0 观测：只记真的进了上下文的那一次（dropped 单独出现不写，否则每步刷屏）。
+        appendInjectionAudit(memoryRoot, auditRecordFrom({
+          sessionId,
+          root,
+          step: stepNo,
+          text: built.text,
+          labels: built.labels,
+          reasons: built.reasons,
+          dropped: built.dropped,
+          budget: { items: budget.items, chars: budget.chars, lastStep: Number.isFinite(budget.lastStep) ? budget.lastStep : null },
+          silence: silenceReason,
+        }), audit)
+        return { ...decision, messages: [...decision.messages, injectMessage] }
+      }
     } catch (err) {
       console.error(`[dsh-project-memory] auto-inject skipped: ${err?.message || err}`)
     }

package/src/insight-store.js

@@ -98,11 +98,31 @@ 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') {
-    // 所有 kind 通用：keywords / symbols / actions / paths / scope（actions/paths 见 src/readiness.js）
+    // 所有 kind 通用。准入化 schema：when（唯一触发面）/ guard（只收窄）/ prevents（准入条件）；
+    // 旧字段 keywords / symbols / actions / paths / scope 继续接受（readiness 会内存内迁移）。
     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)
     }
+    const when = raw.trigger.when
+    if (when && typeof when === 'object') {
+      const w = {}
+      for (const f of ['ops', 'writes', 'intents']) {
+        if (Array.isArray(when[f]) && when[f].length) w[f] = when[f].map(String)
+      }
+      if (Object.keys(w).length) tr.when = w
+    }
+    const guard = raw.trigger.guard
+    if (guard && typeof guard === 'object') {
+      const g = {}
+      for (const f of ['paths', 'not_paths', 'hosts', 'tags']) {
+        if (Array.isArray(guard[f]) && guard[f].length) g[f] = guard[f].map(String)
+      }
+      if (Object.keys(g).length) tr.guard = g
+    }
+    if (typeof raw.trigger.prevents === 'string' && raw.trigger.prevents.trim()) {
+      tr.prevents = raw.trigger.prevents.trim()
+    }
     if (Object.keys(tr).length) ins.trigger = tr
   }
   return ins

package/src/ops.js

@@ -0,0 +1,210 @@
+// 动作平面（PLAN S1）：把"这一步在做什么"从工具调用解析成有限的 op + 写目标 + 主机环境。
+//
+// 为什么不能继续用文本匹配：语料（路径、命令、被读文件正文）里的字符串可以冒充动作。
+// 实测病征是 `keyword:rm` 命中 `dcterms`、`keyword:pptx` 命中一个文件扩展名。
+// op 与 target 是低维、可枚举、可审计的：不随文本长度变化，也不会被正文污染。
+//
+// 分工：ops.js 只负责"把调用读成什么动作"，不负责决定注入什么（那是 readiness/auto-inject）。
+// 刻意不 import readiness：readiness 要 import 本模块的 op 闭集，反向依赖会造成循环。
+
+/** 带扩展名的路径 token（与 readiness.extractPaths 同规则；这里就地实现以免循环依赖）。 */
+const PATH_TOKEN = /(?:[A-Za-z0-9_.@-]+\/)*[A-Za-z0-9_.@-]+\.[A-Za-z][A-Za-z0-9]{0,7}\b/g
+
+function extractPaths(text) {
+  const s = String(text || '')
+  if (!s) return []
+  return [...new Set([...s.matchAll(PATH_TOKEN)].map((m) => m[0]))]
+}
+
+/** op 闭集。新增一个 op 必须同时想清楚：它是动作，不是话题。 */
+export const OP_IDS = [
+  'file-write',
+  'file-delete',
+  'shell-run',
+  'git-commit',
+  'git-push',
+  'release',
+  'npm-publish',
+  'deploy',
+  'migrate',
+  'go-public',
+  'render-doc',
+  'index-doc',
+  'read-image',
+  'fetch-web',
+  'run-bench',
+  'query-memory',
+]
+
+/**
+ * 兜底 op：它们描述的是"发生了某类操作"，信息量低、假阳性高。
+ * 允许写进 `when.ops`，但自检会 warn——兜底 op 只该命中兜底级记忆。
+ */
+export const FALLBACK_OPS = new Set(['shell-run', 'file-write', 'query-memory'])
+
+/**
+ * 弱 op：日常动作。它本身不构成边界（每天都在提交），所以当条目**已经有更精确的 writes**
+ * 时，迁移会把弱 op 丢掉——留着它只会把"改这个文件时"扩大成"任何一次提交时"。
+ * 实测：`git-commit` 让一条"别删内部文档"的教训在发版场景里被注入。
+ */
+export const WEAK_OPS = new Set([...FALLBACK_OPS, 'git-commit', 'git-push'])
+
+/** 旧 action id → op。旧值里有一批从来没进过 ACTION_LEXICON 的死值，这里给它们一个归宿。 */
+export const LEGACY_ACTION_ALIAS = {
+  'git-add': 'git-commit',
+  'npm-pack': 'npm-publish',
+  'release': 'release',
+  'generate-pptx': 'render-doc',
+  'render': 'render-doc',
+  'read-image': 'read-image',
+  'web-fetch': 'fetch-web',
+  'benchmark': 'run-bench',
+  'cleanup': 'file-delete',
+  'delete': 'file-delete',
+  'recover': null, // 没有对应动作：恢复是意图，不是工具动作
+  'research': null,
+  'survey': null,
+  'interview-prep': null,
+  'write-resume': null,
+  'report-metrics': null,
+  'write-docs': null,
+}
+
+const WRITE_TOOLS = new Set(['write', 'edit', 'multi_edit', 'apply_patch', 'str_replace', 'create_file', 'notebook_edit'])
+const READ_IMAGE_TOOLS = new Set(['read_image'])
+const INDEX_TOOLS = new Set(['index_doc', 'index_repo', 'watch_repo'])
+const FETCH_TOOLS = new Set(['web_fetch', 'web_search'])
+const SHELL_TOOLS = new Set(['bash', 'shell', 'pwsh', 'powershell', 'run', 'exec', 'job_run'])
+const QUERY_TOOLS = new Set(['query_memory', 'recall'])
+
+/** bash 命令 → op。顺序有意义：先具体后兜底。 */
+const SHELL_OP_RULES = [
+  [/\bnpm\s+(publish|pack)\b/, 'npm-publish'],
+  [/\bnpm\s+version\b/, 'release'],
+  [/\bgit\s+tag\b/, 'release'],
+  [/\bgit\s+push\b/, 'git-push'],
+  [/\bgit\s+(commit|add)\b/, 'git-commit'],
+  [/\bgit\s+(checkout|restore|reset)\b/, 'file-write'],
+  // `\brm\b` 而不是 `rm\s+-[rf]`：后者被 `\b` 卡在 'rm -rf' 的 r 后面（f 还是词字符），永远匹配不上。
+  [/\b(rm|git\s+rm|unlink|rmdir|shred)\b/, 'file-delete'],
+  [/\b(kubectl|docker\s+push|systemctl\s+restart|pm2\s+(deploy|restart)|vercel|netlify\s+deploy)\b/, 'deploy'],
+  [/\b(migrate|alembic|prisma\s+migrate|db:migrate)\b/, 'migrate'],
+  // 注意：只认"渲染器"，不认 .pptx 扩展名——否则给 pptx 改个时间戳也会命中"做 PPT"
+  [/(pptxgenjs|soffice|libreoffice|render\.sh|marp|pandoc|slidev)/, 'render-doc'],
+  [/(bench\.mjs|\bbench(mark)?\b)/, 'run-bench'],
+  [/\b(curl|wget|web_fetch)\b/, 'fetch-web'],
+]
+
+/** 会改动文件系统的 shell 动作前缀：只有这些命令的路径才算"写目标"。 */
+const SHELL_WRITE_RE = /\b(rm|rmdir|unlink|shred|mv|cp|touch|tee|truncate|mkdir)\b|>>?\s*\S|\bsed\s+-i\b/
+
+const WSL_HINT_RE = /\/mnt\/[a-z]\//i
+
+function safeJson(text) {
+  if (typeof text !== 'string' || !text.trim()) return null
+  try {
+    const v = JSON.parse(text)
+    return v && typeof v === 'object' ? v : null
+  } catch {
+    return null
+  }
+}
+
+function argsFields(argsText) {
+  const obj = safeJson(argsText)
+  if (!obj) return {}
+  const pick = (...keys) => keys
+    .map((k) => obj[k])
+    .filter((v) => typeof v === 'string' && v)
+    .join(' ')
+  return {
+    command: pick('command', 'cmd', 'script', 'code'),
+    path: pick('file_path', 'path', 'file', 'target', 'notebook_path'),
+  }
+}
+
+/** bash 命令 → { ops, targets, hosts }。 */
+export function classifyShellCommand(command) {
+  const cmd = String(command || '')
+  const ops = []
+  if (cmd) {
+    for (const [re, op] of SHELL_OP_RULES) {
+      if (re.test(cmd) && !ops.includes(op)) ops.push(op)
+    }
+  }
+  if (!ops.length) ops.push('shell-run')
+  const targets = SHELL_WRITE_RE.test(cmd) ? extractPaths(cmd) : []
+  const hosts = WSL_HINT_RE.test(cmd) || /\b(powershell|pwsh|cmd)\.exe\b/i.test(cmd) ? ['wsl'] : []
+  return { ops, targets, hosts }
+}
+
+/**
+ * 一次工具调用 → { ops, targets, hosts }。
+ * @param {string} name 工具名
+ * @param {string} argsText 工具参数（JSON 字符串或裸文本）
+ */
+export function classifyToolCall(name, argsText) {
+  const tool = String(name || '').toLowerCase()
+  const { command, path } = argsFields(argsText)
+  if (SHELL_TOOLS.has(tool)) return classifyShellCommand(command || String(argsText || ''))
+  if (READ_IMAGE_TOOLS.has(tool)) return { ops: ['read-image'], targets: [], hosts: [] }
+  if (INDEX_TOOLS.has(tool)) return { ops: ['index-doc'], targets: [], hosts: [] }
+  if (FETCH_TOOLS.has(tool)) return { ops: ['fetch-web'], targets: [], hosts: [] }
+  if (QUERY_TOOLS.has(tool)) return { ops: ['query-memory'], targets: [], hosts: [] }
+  if (WRITE_TOOLS.has(tool)) {
+    const targets = path ? [path, ...extractPaths(path)] : []
+    const hosts = targets.some((t) => WSL_HINT_RE.test(t)) ? ['wsl'] : []
+    return { ops: ['file-write'], targets: [...new Set(targets)], hosts }
+  }
+  return { ops: [], targets: [], hosts: [] }
+}
+
+/**
+ * 把一组已观察到的工具调用合成这一个线程的动态面。
+ * @param {{name?: string, arguments?: string}[]} calls
+ */
+export function activityFromCalls(calls) {
+  const ops = new Set()
+  const targets = new Set()
+  const hosts = new Set()
+  for (const call of calls || []) {
+    const r = classifyToolCall(call?.name, call?.arguments)
+    for (const op of r.ops) ops.add(op)
+    for (const t of r.targets) targets.add(t)
+    for (const h of r.hosts) hosts.add(h)
+  }
+  return { ops: [...ops], targets: [...targets], hosts: [...hosts] }
+}
+
+/**
+ * 没拿到结构化调用时的兜底：直接对一段文本跑 shell 规则。
+ * 用于 `actionText` 形式的就绪上下文（测试与老宿主），以及人类消息里的动作词。
+ */
+export function activityFromText(text) {
+  const s = String(text || '')
+  if (!s) return { ops: [], targets: [], hosts: [] }
+  const lines = s.split('\n').filter(Boolean)
+  const ops = new Set()
+  const targets = new Set()
+  const hosts = new Set()
+  for (const line of lines) {
+    // 先按"工具调用"解析（`edit {"file_path":"..."}`）：结构化参数比正则猜命令可靠得多。
+    const call = /^\s*([A-Za-z_][\w-]*)\s+(\{[\s\S]*\})\s*$/.exec(line)
+    const r = call ? classifyToolCall(call[1], call[2]) : classifyShellCommand(line)
+    // 纯文本行里没有 shell 动作时不要退化成 shell-run（那是噪音源）
+    if (r.ops.length === 1 && r.ops[0] === 'shell-run' && !/\b\w+\s+-/.test(line)) continue
+    for (const op of r.ops) ops.add(op)
+    for (const t of r.targets) targets.add(t)
+    for (const h of r.hosts) hosts.add(h)
+  }
+  return { ops: [...ops], targets: [...targets], hosts: [...hosts] }
+}
+
+/** 旧 action id（含死值）→ op；无法映射返回 null。 */
+export function opForLegacyAction(action) {
+  const a = String(action || '')
+  if (!a) return null
+  if (OP_IDS.includes(a)) return a
+  if (a in LEGACY_ACTION_ALIAS) return LEGACY_ACTION_ALIAS[a]
+  return null
+}