@aiwayds/dsh-topics-memory 0.13.1 → 0.15.0

package/src/index.ts

@@ -45,6 +45,7 @@ import { buildTopicTools } from './tools.ts'
 import { buildTopicsCommand } from './commands.ts'
 import { Observer, textOf, type UserMessageLike } from './observer.ts'
 import { Distiller, defaultModelCaller, type DistillResult, type LlmCandidateShape } from './distill.ts'
+import { Consolidator, dropExpiredDeprecated, type ConsolidateResult } from './consolidate.ts'
 import { SlowLane } from './quality.ts'
 import type { SlowDelivery } from './service.ts'
 import { CONFIG_KEYS, TopicsConfig, type TopicsConfigValue } from './config.ts'
@@ -193,7 +194,7 @@ const SKILL_RESOURCE_BASE = {
 const SKILL_INVOCATION = { modelInvocable: true, userInvocable: true } as const
 
 /** Routing description; must stay identical to the SKILL.md frontmatter (asserted in tests). */
-const SKILL_DESCRIPTION = 'dsh 记忆插件（@aiwayds/dsh-topics-memory）使用与配置指南。凡涉及 dsh 记忆/话题库/GitHub 同步/蒸馏，或要配置 topics 段时先读本指南：settings.yaml 顶层 `topics:` 段全部键（repo/autoInject/topK/注入预算/蒸馏/观察/图游走等）、/topics 命令族（onboard/status/distill/stats/list/show/history/graph/sync/config/set）、首次配置 ask_user_question 向导（local-only 或绑 GitHub 仓、蒸馏模型路由、注入档位、自动观察）、注入形态 pointer/digest、legacy llmwiki 段自动迁移。触发词：topics、记忆、topic、蒸馏、distill、autoInject、记忆库、llmwiki、include-subagents。'
+const SKILL_DESCRIPTION = 'dsh 记忆插件（@aiwayds/dsh-topics-memory）使用与配置指南。凡涉及 dsh 记忆/话题库/GitHub 同步/蒸馏/整理，或要配置 topics 段时先读本指南：settings.yaml 顶层 `topics:` 段全部键（repo/autoInject/topK/注入预算/蒸馏/整理/观察/图游走等）、/topics 命令族（onboard/status/distill/consolidate/stats/list/show/history/graph/sync/config/set）、首次配置 ask_user_question 向导（local-only 或绑 GitHub 仓、蒸馏模型路由、注入档位、自动观察）、注入形态 pointer/digest、legacy llmwiki 段自动迁移。触发词：topics、记忆、topic、蒸馏、distill、整理、consolidate、合并重复、deprecatedTtl、usageBoost、使用加成、autoInject、记忆库、llmwiki、include-subagents。'
 
 const SKILL_CANDIDATE: SkillCandidate = {
   name: SKILL_PROVIDER_NAME,
@@ -471,6 +472,10 @@ export function apply(ctx: Context): void {
   // The settle hook re-runs the release check because a disposal that landed
   // mid-pipeline deferred to THIS pipeline and never fires again.
   const slowLane = new SlowLane(service, caller, releaseSessionLlm)
+  // Consolidation lane (整理): same caller/route as distill, global single
+  // flight inside. Reads the pool and merges/promotes/deprecates/refreshes;
+  // cadence-gated at session start, manual via /topics consolidate.
+  const consolidator = new Consolidator(service, caller)
 
   // ---- Observer (M2) ----
   // Trigger runs are fire-and-forget everywhere now — including the exit
@@ -642,6 +647,38 @@ export function apply(ctx: Context): void {
               if (run !== undefined) void run.catch(() => undefined)
             })
             .catch(() => undefined)
+          // Consolidation cadence check — after the pull (freshest pool),
+          // fully fire-and-forget: cadence/single-flight gates live inside
+          // maybeRun, and a no-model boot just skips (no stamp advanced).
+          // Failures are NOT silent at the host log: the 2026-09-09 real-host
+          // test showed a dead distill route would otherwise hide here with
+          // zero observable trace (the state file only advances on success).
+          try {
+            captureFromAgent(agents()?.get(session.id) as unknown)
+          } catch {
+            // contained — the run below fails with a readable no-model detail
+          }
+          void consolidator
+            .maybeRun({ sessionId: String(session.id) })
+            .then((r) => {
+              if (r !== undefined && !r.ok && r.reason !== 'no-clusters') {
+                warn(`dsh-topics-memory 整理 lane 未执行：${r.reason ?? 'unknown'}${r.detail !== undefined ? `（${r.detail}）` : ''}`)
+              }
+            })
+            .catch(() => undefined)
+          // Deprecated-TTL sweep — pure local rule, no model, runs even when
+          // the distill route is unconfigured. Drops are logged: deletion is
+          // the one housekeeping action the user should always see happened.
+          const ttl = cfgNow().deprecatedTtlDays
+          if (ttl > 0) {
+            void dropExpiredDeprecated(service, ttl)
+              .then((dropped) => {
+                if (dropped.length > 0) {
+                  warn(`dsh-topics-memory：按 ${ttl} 天 TTL 删除了 ${dropped.length} 条 deprecated topic（${dropped.map((s) => `topics/${s}`).join('、')}）；git 历史可找回`)
+                }
+              })
+              .catch(() => undefined)
+          }
         })
     }
   }) as never)
@@ -742,7 +779,21 @@ export function apply(ctx: Context): void {
       }
       return run.finally(() => releaseSessionLlm(sessionId))
     }
-    cmdCtx.effect(() => commands.register(buildTopicsCommand(service, mutate as never, resolveAsk, resolveLlm, manualDistill)), 'topics: /topics')
+    // Manual /topics consolidate trigger: same lane as the cadence path, same
+    // trigger-time llm capture and in-flight guard (the command runs inside a
+    // live session, so its agent's scoped instance is the freshest adapter
+    // holder). Unlike the cadence path there is no releaseSessionLlm hook —
+    // the consolidator holds no per-session capture of its own.
+    const manualConsolidate = async (invocation: unknown): Promise<ConsolidateResult> => {
+      try {
+        captureFromAgent((invocation as { agent?: unknown }).agent)
+      } catch {
+        // contained — the candidate chain still walks whatever was captured
+      }
+      const sessionId = String((invocation as { agent?: { id?: unknown } }).agent?.id ?? 'manual')
+      return consolidator.run(sessionId)
+    }
+    cmdCtx.effect(() => commands.register(buildTopicsCommand(service, mutate as never, resolveAsk, resolveLlm, manualDistill, manualConsolidate)), 'topics: /topics')
   })
 }
 
@@ -770,5 +821,8 @@ const DEFAULTS: TopicsConfigValue = {
   distillModel: '',
   distillBatchSize: 40,
   distillMaxModelCalls: 8,
+  consolidateCadence: 'daily',
+  deprecatedTtlDays: 15,
+  usageBoost: 0.15,
   pushDebounceSeconds: 45,
 }

package/src/observer.ts

@@ -111,9 +111,12 @@ export class Observer {
         state.assistantText = ''
         return
       }
-      case 'assistant/chunk': {
-        const chunk = (data as { chunk?: { type?: string; text?: string } }).chunk
-        if (chunk?.type === 'text-delta' && typeof chunk.text === 'string') state.assistantText += chunk.text
+      case 'assistant/message': {
+        // dsh 0.1.5-rc.1: streaming `assistant/chunk` events are gone — the
+        // settlement carries the committed message. Accumulate each round's
+        // text; turn/end reads the whole turn's transcript. Failed attempts
+        // (`assistant/attempt`) never reached the user, so they are skipped.
+        state.assistantText += textOf(data as UserMessageLike)
         return
       }
       case 'turn/end': {

package/src/retrieval.ts

@@ -40,8 +40,21 @@ export interface RetrievalConfig {
    * self-cross. Off for the explicit topic_search tool (the model asked).
    */
   structuralGate: boolean
+  /**
+   * UsageBoost (ADR 0015): behavioral bonus for topics used within the
+   * rolling window. Gate-scoped but double-locked — capped below the
+   * threshold and never granted to a zero-lexical candidate; the structural
+   * gate still requires lexical evidence. 0 = off.
+   */
+  usageBoost: number
+  /** Usage signals per slug (hits/opens in the window); absent map = no boost. */
+  usage?: ReadonlyMap<string, { hits: number; opens: number }>
 }
 
+/** Hard cap for the usage bonus — below threshold 0.3 so usage can never
+ *  carry a candidate across the gate on its own (ADR 0015). */
+export const USAGE_BOOST_CAP = 0.2
+
 export const DEFAULT_RETRIEVAL: RetrievalConfig = {
   threshold: 0.3,
   topK: 4,
@@ -49,6 +62,7 @@ export const DEFAULT_RETRIEVAL: RetrievalConfig = {
   graphDepth: 2,
   recencyWindowDays: 7,
   structuralGate: true,
+  usageBoost: 0.15,
 }
 
 /** Trigger hits outrank every other lexical field (pi-llm-wiki: highest weight). */
@@ -115,7 +129,8 @@ export interface ScoredTopic {
   strong: boolean
   /** Distinct query terms found in description ∪ conclusion — pass condition B is ≥2. */
   bodyHits: number
-  /** Score with the recency tiebreaker removed — the only score the gate looks at. */
+  /** Score with the recency tiebreaker removed — the score the numeric gate
+   *  looks at (lexical + tags + usageBoost; recency excluded, ADR 0015). */
   gateScore: number
 }
 
@@ -179,6 +194,18 @@ export function scoreTopic(
     score += boost
     reasons.push(`tag-boost:+${boost.toFixed(2)}`)
   }
+  // UsageBoost (ADR 0015) — gate-scoped behavioral bonus, unlike recency it
+  // IS part of gateScore. Double-locked: capped below the threshold, and a
+  // zero-lexical candidate (score === 0 here) never qualifies. Presence of a
+  // signal is the trigger, not its magnitude — votes never scale the bonus.
+  if (cfg.usageBoost > 0 && score > 0 && cfg.usage !== undefined) {
+    const u = cfg.usage.get(topic.slug)
+    if (u !== undefined && (u.hits > 0 || u.opens > 0)) {
+      const boost = Math.min(cfg.usageBoost, USAGE_BOOST_CAP)
+      score += boost
+      reasons.push(`usage:+${boost.toFixed(2)}`)
+    }
+  }
   // Recency is a RANKING tiebreaker only (v4): it pads `score` but is kept
   // out of `gateScore`, so it can never carry a candidate across the numeric
   // threshold. Conflict demotion applies to the pre-tiebreaker score.

package/src/service.ts

@@ -14,7 +14,7 @@ import { searchTopics, scoreTopic, passesGate, tokenize, type RetrievableTopic,
 import { assembleInjection, assemblePointer, POINTER_PER_TOPIC, POINTER_TOTAL, type AssembleResult, type DigestInput, type SlowPointerInput } from './digest.ts'
 import type { BundleStore, Observation, SaveResult } from './store.ts'
 import type { TopicsConfigValue } from './config.ts'
-import { aggregateStats, querySample, type AggregateStats, type InjectionRecord, type QueryBuildShape, type ShadowVerdict, type SlowItem } from './ilog.ts'
+import { aggregateStats, querySample, aggregateUsage, USAGE_WINDOW_DAYS, type AggregateStats, type InjectionRecord, type QueryBuildShape, type ShadowVerdict, type SlowItem, type UsageSignal } from './ilog.ts'
 import { fileHistory, fileAtRev } from './git.ts'
 import type { Sync } from './sync.ts'
 
@@ -50,6 +50,13 @@ export class TopicsService {
   private cache = new Map<string, CacheEntry>()
   /** mtime-keyed parse of the observations log, grouped by session. */
   private echoCache: { mtimeMs: number; size: number; bySession: Map<string, Set<string>> } | undefined
+  private usageCache: {
+    injMs: number
+    injSize: number
+    opensMs: number
+    opensSize: number
+    signals: Map<string, UsageSignal>
+  } | undefined
   readonly store: BundleStore
   private readonly getConfig: () => TopicsConfigValue
   readonly sync?: Sync
@@ -99,6 +106,11 @@ export class TopicsService {
       }
       if (entry === undefined) continue
       const doc = entry.doc
+      // Deprecated topics are retired knowledge (consolidation merges and
+      // manual deprecations) — they must not rank, inject, or feed the
+      // depends-graph walk, or a merged-away entry would keep competing
+      // with its survivor for the injection budget.
+      if (doc.fm.status === 'deprecated') continue
       out.push({
         slug: entry.slug,
         title: doc.fm.title,
@@ -119,6 +131,7 @@ export class TopicsService {
   invalidate(): void {
     this.cache.clear()
     this.echoCache = undefined
+    this.usageCache = undefined
   }
 
   /**
@@ -169,6 +182,68 @@ export class TopicsService {
     return bySession.bySession.get(sessionId) ?? new Set()
   }
 
+  /**
+   * Usage signals (ADR 0015): mtime-cached aggregate over the injection log
+   * and the opens log, rolling USAGE_WINDOW_DAYS. Synchronous like
+   * echoSlugsSync — the retrieval hot path is sync — and cheap when warm:
+   * a fresh cache costs two stat() calls. Unreadable logs fail open to an
+   * empty map (no boost), never an error.
+   */
+  usageSignalsSync(): Map<string, UsageSignal> {
+    const injFile = join(this.store.metaDir(), 'injections.jsonl')
+    const opensFile = join(this.store.metaDir(), 'opens.jsonl')
+    const statOf = (file: string): { mtimeMs: number; size: number } => {
+      try {
+        const st = statSync(file)
+        return { mtimeMs: st.mtimeMs, size: st.size }
+      } catch {
+        return { mtimeMs: 0, size: 0 }
+      }
+    }
+    const injSt = statOf(injFile)
+    const opensSt = statOf(opensFile)
+    const cached = this.usageCache
+    if (
+      cached !== undefined &&
+      cached.injMs === injSt.mtimeMs &&
+      cached.injSize === injSt.size &&
+      cached.opensMs === opensSt.mtimeMs &&
+      cached.opensSize === opensSt.size
+    ) {
+      return cached.signals
+    }
+    const parseLines = <T>(file: string): T[] => {
+      const out: T[] = []
+      try {
+        for (const line of readFileSync(file, 'utf8').split('\n')) {
+          if (line.trim() === '') continue
+          try {
+            out.push(JSON.parse(line) as T)
+          } catch {
+            continue // torn tail line
+          }
+        }
+      } catch {
+        // unreadable log: contribute nothing
+      }
+      return out
+    }
+    const signals = aggregateUsage(
+      parseLines(injFile),
+      parseLines(opensFile),
+      USAGE_WINDOW_DAYS,
+      Date.now(),
+    )
+    this.usageCache = {
+      injMs: injSt.mtimeMs,
+      injSize: injSt.size,
+      opensMs: opensSt.mtimeMs,
+      opensSize: opensSt.size,
+      signals,
+    }
+    return signals
+  }
+
   /**
    * Full retrieval round: search → assemble → log (ADR 0006/0007). The
    * injection record is written even for zero-hit rounds — the hit-rate
@@ -192,6 +267,8 @@ export class TopicsService {
       graphDepth: cfg.graphDepth,
       recencyWindowDays: cfg.recencyWindowDays,
       conflicts,
+      usageBoost: cfg.usageBoost,
+      usage: this.usageSignalsSync(),
     })
     const bySlug = new Map(roster.map((r) => [r.slug, r]))
     const entries: DigestInput[] = []
@@ -289,6 +366,8 @@ export class TopicsService {
       graphDepth: cfg.graphDepth,
       recencyWindowDays: cfg.recencyWindowDays,
       conflicts,
+      usageBoost: cfg.usageBoost,
+      usage: this.usageSignalsSync(),
     })
     const exclude = dedup?.exclude
     const echo = dedup?.echo
@@ -346,6 +425,8 @@ export class TopicsService {
           recencyWindowDays: cfg.recencyWindowDays,
           conflicts,
           structuralGate: true,
+          usageBoost: cfg.usageBoost,
+          usage: this.usageSignalsSync(),
         })
         shadow.push({
           slug: item.slug,
@@ -515,6 +596,8 @@ export class TopicsService {
       }
       if (entry === undefined) continue
       const doc = entry.doc
+      // Same retirement rule as roster(): deprecated knowledge never injects.
+      if (doc.fm.status === 'deprecated') continue
       out.push({
         slug: entry.slug,
         title: doc.fm.title,
@@ -621,6 +704,8 @@ export class TopicsService {
       // structural gate must not hide results.
       structuralGate: false,
       conflicts: await this.store.getConflicts(),
+      usageBoost: cfg.usageBoost,
+      usage: this.usageSignalsSync(),
     })
   }
 

package/src/store.ts

@@ -17,6 +17,7 @@ import {
   mkdir,
   appendFile,
   access,
+  rm,
 } from 'node:fs/promises'
 import { readFileSync } from 'node:fs'
 import { constants as FsConstants } from 'node:fs'
@@ -161,6 +162,24 @@ export class BundleStore {
     }
   }
 
+  private consolidateStatePath(): string {
+    return join(this.metaDir(), 'consolidate-state.json')
+  }
+
+  /** Last consolidation-lane run outcome (cadence stamp + /topics status). */
+  async writeConsolidateState(state: unknown): Promise<void> {
+    await mkdir(this.metaDir(), { recursive: true })
+    await atomicWrite(this.consolidateStatePath(), `${JSON.stringify(state, null, 2)}\n`)
+  }
+
+  async readConsolidateState(): Promise<Record<string, unknown> | undefined> {
+    try {
+      return JSON.parse(await readFile(this.consolidateStatePath(), 'utf8')) as Record<string, unknown>
+    } catch {
+      return undefined
+    }
+  }
+
   /** Create the directory skeleton, git repo, initial index, and repair
    * wrapped depends entries left by older save paths (idempotent). */
   async ensure(): Promise<void> {
@@ -326,8 +345,25 @@ export class BundleStore {
     })
   }
 
-  private async regenerateIndex(): Promise<void> {
-    const metas = await this.listTopics()
+  /**
+   * Remove a topic file and regenerate the index — one commit, so the rm is
+   * as traceable and revertible as every other bundle write. Callers own the
+   * policy (TTL housekeeping, future manual ops); the store only supplies the
+   * safe write path. Returns false when the slug doesn't exist (idempotent).
+   */
+  async deleteTopic(slug: string, message: string): Promise<boolean> {
+    return this.enqueue(async () => {
+      const clean = okf.slugify(slug)
+      const file = this.topicPath(clean)
+      if (!(await existsSync(file))) return false
+      await rm(file)
+      await this.regenerateIndex()
+      await this.commit([`topics/${clean}.md`, 'index.md'], message)
+      return true
+    })
+  }
+
+  private async regenerateIndex(): Promise<void> {    const metas = await this.listTopics()
     const entries: okf.IndexEntry[] = metas.map((m) => ({
       slug: m.slug,
       title: m.title,