@aiwayds/dsh-topics-memory 0.13.0 → 0.14.0

package/lib/index.js

@@ -30,6 +30,7 @@ import { buildTopicTools } from "./tools.js";
 import { buildTopicsCommand } from "./commands.js";
 import { Observer, textOf } from "./observer.js";
 import { Distiller, defaultModelCaller } from "./distill.js";
+import { Consolidator, dropExpiredDeprecated } from "./consolidate.js";
 import { SlowLane } from "./quality.js";
 import { CONFIG_KEYS, TopicsConfig } from "./config.js";
 import { isDelegated } from "./delegation.js";
@@ -126,17 +127,17 @@ export function migrateLegacySettings(settings, warn) {
 }
 // --- Bundled skill -----------------------------------------------------------
 /** Provider name under `ctx.skills`; doubles as the skill name. */
-const SKILL_PROVIDER_NAME = 'dsh-topics-memory';
+const SKILL_PROVIDER_NAME = 'dsh-topics-memory-config';
 /** Packaged skill body; `../skills/` resolves to the package root from both lib/ and src/. */
-const SKILL_BODY_URL = new URL('../skills/dsh-topics-memory/SKILL.md', import.meta.url);
+const SKILL_BODY_URL = new URL('../skills/dsh-topics-memory-config/SKILL.md', import.meta.url);
 /** Resource base served with the skill so its relative links resolve. */
 const SKILL_RESOURCE_BASE = {
     kind: 'directory',
-    path: fileURLToPath(new URL('../skills/dsh-topics-memory/', import.meta.url)),
+    path: fileURLToPath(new URL('../skills/dsh-topics-memory-config/', import.meta.url)),
 };
 const SKILL_INVOCATION = { modelInvocable: true, userInvocable: true };
 /** 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 = {
     name: SKILL_PROVIDER_NAME,
     description: SKILL_DESCRIPTION,
@@ -410,6 +411,10 @@ export function apply(ctx) {
     // 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
     // one. Observations are write-through on disk, so a run the process exits
@@ -586,6 +591,39 @@ export function apply(ctx) {
                         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));
+                }
+                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);
+                }
             });
         }
     }));
@@ -684,7 +722,22 @@ export function apply(ctx) {
             }
             return run.finally(() => releaseSessionLlm(sessionId));
         };
-        cmdCtx.effect(() => commands.register(buildTopicsCommand(service, mutate, 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) => {
+            try {
+                captureFromAgent(invocation.agent);
+            }
+            catch {
+                // contained — the candidate chain still walks whatever was captured
+            }
+            const sessionId = String(invocation.agent?.id ?? 'manual');
+            return consolidator.run(sessionId);
+        };
+        cmdCtx.effect(() => commands.register(buildTopicsCommand(service, mutate, resolveAsk, resolveLlm, manualDistill, manualConsolidate)), 'topics: /topics');
     });
 }
 /** Config defaults for harnesses that skip schemastery's default application. */
@@ -711,5 +764,8 @@ const DEFAULTS = {
     distillModel: '',
     distillBatchSize: 40,
     distillMaxModelCalls: 8,
+    consolidateCadence: 'daily',
+    deprecatedTtlDays: 15,
+    usageBoost: 0.15,
     pushDebounceSeconds: 45,
 };

package/lib/retrieval.d.ts

@@ -36,7 +36,22 @@ 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 declare const USAGE_BOOST_CAP = 0.2;
 export declare const DEFAULT_RETRIEVAL: RetrievalConfig;
 /** Trigger hits outrank every other lexical field (pi-llm-wiki: highest weight). */
 export declare const TRIGGER_WEIGHT = 5;
@@ -70,7 +85,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;
 }
 /** Score one topic against the query tokens. */

package/lib/retrieval.js

@@ -12,6 +12,9 @@
  * @module retrieval
  */
 import { dependsSlugs } from "./okf.js";
+/** 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 = {
     threshold: 0.3,
     topK: 4,
@@ -19,6 +22,7 @@ export const DEFAULT_RETRIEVAL = {
     graphDepth: 2,
     recencyWindowDays: 7,
     structuralGate: true,
+    usageBoost: 0.15,
 };
 /** Trigger hits outrank every other lexical field (pi-llm-wiki: highest weight). */
 export const TRIGGER_WEIGHT = 5;
@@ -115,6 +119,18 @@ export function scoreTopic(queryTokens, topic, cfg) {
         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/lib/service.d.ts

@@ -10,7 +10,7 @@ import { type RetrievableTopic, type SearchOutcome } from './retrieval.ts';
 import { type AssembleResult } from './digest.ts';
 import type { BundleStore, Observation, SaveResult } from './store.ts';
 import type { TopicsConfigValue } from './config.ts';
-import { type AggregateStats, type QueryBuildShape } from './ilog.ts';
+import { type AggregateStats, type QueryBuildShape, type UsageSignal } from './ilog.ts';
 import type { Sync } from './sync.ts';
 export interface RetrieveOutcome {
     outcome: SearchOutcome;
@@ -38,6 +38,7 @@ export declare class TopicsService {
     private cache;
     /** mtime-keyed parse of the observations log, grouped by session. */
     private echoCache;
+    private usageCache;
     readonly store: BundleStore;
     private readonly getConfig;
     readonly sync?: Sync;
@@ -58,6 +59,14 @@ export declare class TopicsService {
      * the injection hot path, mtime-cached like the roster.
      */
     echoSlugsSync(sessionId: string): Set<string>;
+    /**
+     * 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>;
     /**
      * Full retrieval round: search → assemble → log (ADR 0006/0007). The
      * injection record is written even for zero-hit rounds — the hit-rate

package/lib/service.js

@@ -11,12 +11,13 @@ import { join } from 'node:path';
 import * as okf from "./okf.js";
 import { searchTopics, scoreTopic, passesGate, tokenize } from "./retrieval.js";
 import { assembleInjection, assemblePointer, POINTER_PER_TOPIC, POINTER_TOTAL } from "./digest.js";
-import { aggregateStats, querySample } from "./ilog.js";
+import { aggregateStats, querySample, aggregateUsage, USAGE_WINDOW_DAYS } from "./ilog.js";
 import { fileHistory, fileAtRev } from "./git.js";
 export class TopicsService {
     cache = new Map();
     /** mtime-keyed parse of the observations log, grouped by session. */
     echoCache;
+    usageCache;
     store;
     getConfig;
     sync;
@@ -66,6 +67,12 @@ 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,
@@ -85,6 +92,7 @@ export class TopicsService {
     invalidate() {
         this.cache.clear();
         this.echoCache = undefined;
+        this.usageCache = undefined;
     }
     /**
      * Slugs distilled from THIS session's own turns — the echo set (2026-09
@@ -139,6 +147,64 @@ 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() {
+        const injFile = join(this.store.metaDir(), 'injections.jsonl');
+        const opensFile = join(this.store.metaDir(), 'opens.jsonl');
+        const statOf = (file) => {
+            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 = (file) => {
+            const out = [];
+            try {
+                for (const line of readFileSync(file, 'utf8').split('\n')) {
+                    if (line.trim() === '')
+                        continue;
+                    try {
+                        out.push(JSON.parse(line));
+                    }
+                    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
@@ -162,6 +228,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 = [];
@@ -264,6 +332,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;
@@ -325,6 +395,8 @@ export class TopicsService {
                     recencyWindowDays: cfg.recencyWindowDays,
                     conflicts,
                     structuralGate: true,
+                    usageBoost: cfg.usageBoost,
+                    usage: this.usageSignalsSync(),
                 });
                 shadow.push({
                     slug: item.slug,
@@ -488,6 +560,9 @@ 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,
@@ -579,6 +654,8 @@ export class TopicsService {
             // structural gate must not hide results.
             structuralGate: false,
             conflicts: await this.store.getConflicts(),
+            usageBoost: cfg.usageBoost,
+            usage: this.usageSignalsSync(),
         });
     }
     async history(slug, limit = 20) {

package/lib/store.d.ts

@@ -66,6 +66,10 @@ export declare class BundleStore {
     /** Last distill-lane run outcome (diagnostics for /topics status and e2e). */
     writeDistillState(state: unknown): Promise<void>;
     readDistillState(): Promise<Record<string, unknown> | undefined>;
+    private consolidateStatePath;
+    /** Last consolidation-lane run outcome (cadence stamp + /topics status). */
+    writeConsolidateState(state: unknown): Promise<void>;
+    readConsolidateState(): Promise<Record<string, unknown> | undefined>;
     /** Create the directory skeleton, git repo, initial index, and repair
      * wrapped depends entries left by older save paths (idempotent). */
     ensure(): Promise<void>;
@@ -102,6 +106,13 @@ export declare class BundleStore {
         actor?: string;
         created?: boolean;
     }): Promise<SaveResult>;
+    /**
+     * 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).
+     */
+    deleteTopic(slug: string, message: string): Promise<boolean>;
     private regenerateIndex;
     /**
      * Reverse-reference index: slug → who references it and how (`depends`

package/lib/store.js

@@ -8,7 +8,7 @@
  *
  * @module store
  */
-import { readdir, readFile, writeFile, rename, mkdir, appendFile, access, } from 'node:fs/promises';
+import { readdir, readFile, writeFile, rename, mkdir, appendFile, access, rm, } from 'node:fs/promises';
 import { readFileSync } from 'node:fs';
 import { constants as FsConstants } from 'node:fs';
 import { dirname, join } from 'node:path';
@@ -93,6 +93,22 @@ export class BundleStore {
             return undefined;
         }
     }
+    consolidateStatePath() {
+        return join(this.metaDir(), 'consolidate-state.json');
+    }
+    /** Last consolidation-lane run outcome (cadence stamp + /topics status). */
+    async writeConsolidateState(state) {
+        await mkdir(this.metaDir(), { recursive: true });
+        await atomicWrite(this.consolidateStatePath(), `${JSON.stringify(state, null, 2)}\n`);
+    }
+    async readConsolidateState() {
+        try {
+            return JSON.parse(await readFile(this.consolidateStatePath(), 'utf8'));
+        }
+        catch {
+            return undefined;
+        }
+    }
     /** Create the directory skeleton, git repo, initial index, and repair
      * wrapped depends entries left by older save paths (idempotent). */
     async ensure() {
@@ -262,6 +278,24 @@ export class BundleStore {
             return { slug, path: `topics/${slug}.md`, committed, created };
         });
     }
+    /**
+     * 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, message) {
+        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;
+        });
+    }
     async regenerateIndex() {
         const metas = await this.listTopics();
         const entries = metas.map((m) => ({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwayds/dsh-topics-memory",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "dsh-plugin: quality-first topic memory for dsh — a topic keeps the starting question, conclusion, impact and dependencies, not the process; local-first git-traced OKF bundle, budgeted LLM-free injection",
   "type": "module",
   "main": "lib/index.js",
@@ -39,7 +39,7 @@
     "build": "tsc -p tsconfig.json",
     "check": "tsc --noEmit -p tsconfig.json",
     "pretest": "tsc -p tsconfig.json",
-    "test": "node --test test/yaml.test.mjs test/okf.test.mjs test/retrieval.test.mjs test/digest.test.mjs test/ilog.test.mjs test/store.test.mjs test/paths.test.mjs test/git.test.mjs test/sync.test.mjs test/tools.test.mjs test/dedup.test.mjs test/commands.test.mjs test/onboard.test.mjs test/delegation.test.mjs test/observer.test.mjs test/distill.test.mjs test/viz.test.mjs test/corpus.test.mjs test/llm-scope.test.mjs test/settings-migration.test.mjs test/quality.test.mjs test/replay-gate.test.mjs test/depends-repair.test.mjs test/skill.test.mjs",
+    "test": "node --test test/yaml.test.mjs test/okf.test.mjs test/retrieval.test.mjs test/digest.test.mjs test/ilog.test.mjs test/store.test.mjs test/paths.test.mjs test/git.test.mjs test/sync.test.mjs test/tools.test.mjs test/dedup.test.mjs test/commands.test.mjs test/onboard.test.mjs test/delegation.test.mjs test/observer.test.mjs test/distill.test.mjs test/consolidate.test.mjs test/viz.test.mjs test/corpus.test.mjs test/llm-scope.test.mjs test/settings-migration.test.mjs test/quality.test.mjs test/replay-gate.test.mjs test/depends-repair.test.mjs test/skill.test.mjs",
     "smoke": "node scripts/smoke-boot.mjs"
   },
   "dependencies": {},

package/skills/{dsh-topics-memory → dsh-topics-memory-config}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: dsh-topics-memory
-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。"
+name: dsh-topics-memory-config
+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。"
 ---
 
 # dsh-topics-memory 使用指南（工作记忆 / 蒸馏 / 注入）
@@ -36,6 +36,9 @@ description: "dsh 记忆插件（@aiwayds/dsh-topics-memory）使用与配置指
 | `distillProvider` / `distillModel` | 空（蒸馏关闭） | 蒸馏模型路由，两者都非空才启用 |
 | `distillBatchSize` | `40` | 每次蒸馏模型调用携带的观察条数（输出上限失败自动减半，下限 5） |
 | `distillMaxModelCalls` | `8` | 单次蒸馏 run 的模型调用预算（预算耗尽即停，已成功批次保留标记） |
+| `consolidateCadence` | `daily` | 整理 lane 节拍：daily／3d／7d／off。会话启动时检查上次整理时间，到期即在后台跑 LLM 园丁（复用蒸馏模型路由）：合并重复、晋升 stable、废弃过时、刷新元数据；off 关闭 |
+| `deprecatedTtlDays` | `15` | deprecated 条目超过 N 天在会话启动时自动删除（本地规则不依赖模型，逐条 git commit 可回溯找回）；0 关闭清扫 |
+| `usageBoost` | `0.15` | 使用加成（ADR 0015）：近 30 天被注入命中/点开过的 Topic 检索加分（计入门槛分，帽 0.2，零词面相关不加，结构门不豁免）；`0` 关闭 |
 | `pushDebounceSeconds` | `45` | GitHub 模式去抖推送间隔 |
 
 - 全部键都可用 `/topics set <键> <值>` 运行时写回同段（即时校验：boolean 用 on|off、
@@ -67,6 +70,7 @@ GitHub 模式凭据走 `$GITHUB_TOKEN` 或已登录的 gh CLI（`gh auth status`
 | `/topics onboard` | 交互式配置向导（ask-user 面板，末步确认才写入） |
 | `/topics status` | bundle 健康：topic 数、观察积压、冲突、最近蒸馏、同步状态 |
 | `/topics distill` | 手动触发一次蒸馏 run（复用现有 lane 与 in-flight 守卫） |
+| `/topics consolidate` | 手动触发一次整理 run：LLM 园丁合并重复/晋升/废弃/刷新元数据，逐条 git commit 可回滚 |
 | `/topics stats` | 注入统计：hit rate、Top-N、near-miss 分布与调参建议 |
 | `/topics list` | 表格列出全部 Topic（带序号、最新优先、100 条封顶） |
 | `/topics show <slug>` | Topic 全文阅读页 + 反向引用（谁引用了我、怎么引用） |
@@ -83,9 +87,14 @@ GitHub 模式凭据走 `$GITHUB_TOKEN` 或已登录的 gh CLI（`gh auth status`
 2. **蒸馏没跑**：distill-provider 与 distill-model 必须**同时非空**（缺一即闲置）；长会话看
    distill-every-turns 节拍、会话结束看 distill-on-session-end；`/topics distill` 手动触发
    会给可读原因（no-model / in-flight / no-observations）。
-3. **GitHub 同步**：repo 须形如 owner/name；推送有 push-debounce-seconds 去抖；退出只做
+3. **整理 lane**：`consolidate-cadence`（daily/3d/7d，默认 daily，off 关闭）到期后在会话启动
+   时后台跑，复用蒸馏模型路由（未配蒸馏模型则闲置）；本地词面聚类只把「长得像」的 topic
+   送模型，四类动作（merge/promote/deprecate/refresh）都逐条 git commit，`/topics consolidate`
+   手动立即跑，`/topics status` 看最近整理，不满意 `git revert` 即回滚。被合并条目标
+   deprecated 且不再参与注入。
+4. **GitHub 同步**：repo 须形如 owner/name；推送有 push-debounce-seconds 去抖；退出只做
    本地 commit 不等网络，推迟的 push 由下次启动 pull 后补推；rebase 冲突的 topic 降权标记，
    `/topics status` 可查。
-4. **旧版 llmwiki 段自动迁移**：0.5.x 的 `llmwiki:` 设置段与 `~/.dsh/llmwiki` 数据目录在
+5. **旧版 llmwiki 段自动迁移**：0.5.x 的 `llmwiki:` 设置段与 `~/.dsh/llmwiki` 数据目录在
    首次启动时自动迁移到 `topics` / `~/.dsh/topics`，无需手工；旧插件还在运行时会警告跳过
    （防双载脑裂），先从 profile 移除旧包。