@aiwayds/dsh-topics-memory 0.13.1 → 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";
@@ -136,7 +137,7 @@ const SKILL_RESOURCE_BASE = {
 };
 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.1",
+  "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-config/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dsh-topics-memory-config
-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。"
+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 移除旧包。

package/src/commands.ts

@@ -12,6 +12,7 @@ import { join } from 'node:path'
 import { spawn } from 'node:child_process'
 import type { TopicsService } from './service.ts'
 import type { DistillResult } from './distill.ts'
+import type { ConsolidateResult } from './consolidate.ts'
 import { serializeTopicDoc, slugify, firstParagraph } from './okf.ts'
 import { buildGraph, renderGraphHtml } from './viz.ts'
 import { CONFIG_KEYS, displayKey, type ConfigKey, type TopicsConfigValue, parseConfigValue } from './config.ts'
@@ -37,11 +38,19 @@ import {
  */
 export type ManualDistill = (invocation: CommandInvocation) => Promise<DistillResult>
 
+/**
+ * Manual `/topics consolidate` trigger, wired by the host (index.ts owns the
+ * lane instance). Bypasses the cadence gate; the lane's own in-flight guard
+ * still applies.
+ */
+export type ManualConsolidate = (invocation: CommandInvocation) => Promise<ConsolidateResult>
+
 export const HELP = [
   'dsh-topics-memory — OKF topic 记忆（本地 bundle，git 可追溯，可选 GitHub 同步）',
   '  /topics onboard             交互式配置向导（ask-user 面板逐项问答；无 UI 环境逐条输入）',
   '  /topics status              bundle 健康：topic 数、观察积压、冲突、同步状态',
   '  /topics distill             手动触发一次蒸馏（观察池 → Topic，输出 marked/created/updated/gc 摘要）',
+  '  /topics consolidate         手动触发一次整理（合并重复/晋升 stable/废弃过时/刷新元数据，无视 cadence 立即跑）',
   '  /topics stats               注入统计：hit rate、top-N、near-miss 分布与调参建议',
   '  /topics list                列出全部 Topic',
   '  /topics show <slug>         查看一个 Topic 全文（含反向引用）',
@@ -55,17 +64,17 @@ export const HELP = [
   '凭据：$GITHUB_TOKEN 或已登录的 gh CLI；登录不在本插件职责内。',
 ].join('\n')
 
-export function buildTopicsCommand(service: TopicsService, mutate: MutateFn, resolveAsk: AskServiceResolver = () => undefined, resolveLlm: LlmDirectoryResolver = () => [], distillNow?: ManualDistill): CommandDefinition {
+export function buildTopicsCommand(service: TopicsService, mutate: MutateFn, resolveAsk: AskServiceResolver = () => undefined, resolveLlm: LlmDirectoryResolver = () => [], distillNow?: ManualDistill, consolidateNow?: ManualConsolidate): CommandDefinition {
   const onboard = createOnboardHandler(service, mutate, undefined, resolveAsk, resolveLlm)
   return {
     name: 'topics',
-    description: 'OKF topic 记忆：onboard | distill | status | stats | list | show | history | graph | sync | config | set',
-    input: { hint: '[onboard | distill | status | stats | list | show <slug> | history <slug> | graph | sync [pull|push] | config | set <key> <value>]' },
-    handler: (invocation) => handle(invocation, service, mutate, onboard, resolveAsk, resolveLlm, distillNow),
+    description: 'OKF topic 记忆：onboard | distill | consolidate | status | stats | list | show | history | graph | sync | config | set',
+    input: { hint: '[onboard | distill | consolidate | status | stats | list | show <slug> | history <slug> | graph | sync [pull|push] | config | set <key> <value>]' },
+    handler: (invocation) => handle(invocation, service, mutate, onboard, resolveAsk, resolveLlm, distillNow, consolidateNow),
   }
 }
 
-async function handle(invocation: CommandInvocation, service: TopicsService, mutate: MutateFn, onboard: (args: string[], invocation: CommandInvocation) => Promise<CommandResult>, resolveAsk: AskServiceResolver, resolveLlm: LlmDirectoryResolver, distillNow?: ManualDistill): Promise<CommandResult> {
+async function handle(invocation: CommandInvocation, service: TopicsService, mutate: MutateFn, onboard: (args: string[], invocation: CommandInvocation) => Promise<CommandResult>, resolveAsk: AskServiceResolver, resolveLlm: LlmDirectoryResolver, distillNow?: ManualDistill, consolidateNow?: ManualConsolidate): Promise<CommandResult> {
   const raw = invocation.rawInput.trim()
   const [action = '', ...rest] = raw.split(/\s+/)
   try {
@@ -78,6 +87,8 @@ async function handle(invocation: CommandInvocation, service: TopicsService, mut
         return ok(await renderStatus(service))
       case 'distill':
         return await doDistill(service, invocation, distillNow)
+      case 'consolidate':
+        return await doConsolidate(service, invocation, consolidateNow)
       case 'stats':
         return ok(await renderStats(service))
       case 'list':
@@ -125,6 +136,7 @@ async function renderStatus(service: TopicsService): Promise<string> {
     ['注入去重', cfg.injectDedup ? '开（同会话已注入的 Topic 不重注）' : '关'],
     ['慢道', cfg.qualityLane === 'off' ? '关' : cfg.qualityLane === 'always' ? `每轮（${cfg.distillProvider}/${cfg.distillModel}）` : `采样 1/3（${cfg.distillProvider}/${cfg.distillModel}）`],
     ['蒸馏', cfg.distillProvider !== '' && cfg.distillModel !== '' ? `${cfg.distillProvider}/${cfg.distillModel}，每 ${cfg.distillEveryTurns} 轮` : '未配置模型（/topics set distill-provider / distill-model）'],
+    ['整理', cadenceLabel(cfg.consolidateCadence) + (cfg.consolidateCadence === 'off' ? '' : `（复用蒸馏模型，/topics consolidate 立即跑）`)],
   ]
   // Last lane outcome (distill-state summary) — what "checkable via
   // /topics status" promises; absent until the first run of this bundle.
@@ -137,6 +149,20 @@ async function renderStatus(service: TopicsService): Promise<string> {
     const gc = typeof lastRun.gcDropped === 'number' && lastRun.gcDropped > 0 ? `，GC 回收 ${lastRun.gcDropped}` : ''
     rows.push(['最近蒸馏', `${outcome}${gc} @ ${cell(String(lastRun.at ?? '').slice(0, 19).replace('T', ' '))}`])
   }
+  const lastConsolidate = await service.store.readConsolidateState()
+  if (lastConsolidate !== undefined) {
+    const count = (v: unknown): number => (Array.isArray(v) ? v.length : 0)
+    const counts = [
+      `合并 ${count(lastConsolidate.merged)}`,
+      `晋升 ${count(lastConsolidate.promoted)}`,
+      `废弃 ${count(lastConsolidate.deprecated)}`,
+      `刷新 ${count(lastConsolidate.refreshed)}`,
+    ].join('/')
+    rows.push([
+      '最近整理',
+      `${counts} @ ${cell(String(lastConsolidate.at ?? '').slice(0, 19).replace('T', ' '))}${lastConsolidate.ok === false && lastConsolidate.detail ? `（${String(lastConsolidate.detail).slice(0, 80)}）` : ''}`,
+    ])
+  }
   if (service.sync !== undefined) {
     rows.push(['上次推送', cell(String(service.sync.lastPushAt ?? '从未'))])
     if (service.sync.lastError !== '') rows.push(['同步错误', cell(service.sync.lastError.split('\n').at(-1) ?? '')])
@@ -156,6 +182,59 @@ async function renderStatus(service: TopicsService): Promise<string> {
  * summary mirrors the distill state fields (ok / marked / created / updated /
  * gc dropped / reason) so what the user sees is what the state file records.
  */
+/** Human-readable cadence for status/consolidate output. */
+function cadenceLabel(value: string): string {
+  switch (value) {
+    case 'daily':
+      return '每天'
+    case '3d':
+      return '每 3 天'
+    case '7d':
+      return '每 7 天'
+    default:
+      return '关'
+  }
+}
+
+/**
+ * `/topics consolidate` — one manual run of the consolidation lane (LLM
+ * gardener over the existing pool). Bypasses the cadence gate; the lane's
+ * own in-flight guard dedups a concurrent automatic run. Output mirrors the
+ * lane's actions with per-op reasons so the user can eyeball (and git-revert)
+ * what the model decided.
+ */
+async function doConsolidate(service: TopicsService, invocation: CommandInvocation, consolidateNow: ManualConsolidate | undefined): Promise<CommandResult> {
+  if (consolidateNow === undefined) return fail('整理 lane 未接线（宿主未提供手动整理触发器）')
+  const cfg = service.cfg
+  if (cfg.distillProvider === '' || cfg.distillModel === '') {
+    return fail('整理复用蒸馏模型路由：请先 /topics set distill-provider 与 distill-model。')
+  }
+  const result = await consolidateNow(invocation)
+  if (!result.ok) {
+    const reasonNote =
+      result.reason === 'no-clusters'
+        ? '没有找到可能相近的 topic 候选簇（词面上没有疑似重复/相关对）'
+        : result.reason === 'no-model'
+          ? '蒸馏模型未配置（/topics set distill-provider / distill-model）'
+          : result.reason === 'in-flight'
+            ? '已有整理在跑，稍后再试'
+            : (result.reason ?? 'unknown')
+    return fail(`整理未执行：${reasonNote}${result.detail !== undefined ? `\n   ${result.detail}` : ''}`)
+  }
+  const lines: string[] = []
+  const actions = result.actions ?? []
+  const KIND_LABEL: Record<string, string> = { merge: '合并', promote: '晋升', deprecate: '废弃', refresh: '刷新' }
+  for (const a of actions) {
+    if (a.kind === 'merge' && a.merged !== undefined) {
+      lines.push(`- 合并 ${a.merged.map((m) => cell(m)).join('、')} → ${cell(a.slug)}${a.reason !== undefined ? `：${a.reason}` : ''}`)
+    } else {
+      lines.push(`- ${KIND_LABEL[a.kind] ?? a.kind} ${cell(a.slug)}${a.reason !== undefined ? `：${a.reason}` : ''}`)
+    }
+  }
+  const header = `✅ 整理完成：合并 ${result.merged.length} 组；晋升 ${result.promoted.length}；废弃 ${result.deprecated.length}；刷新 ${result.refreshed.length}${result.droppedOps ? `（丢弃 ${result.droppedOps} 个无效 op）` : ''}${result.detail !== undefined ? `\n   ${result.detail}` : ''}`
+  return ok(lines.length === 0 ? header : `${header}\n${lines.join('\n')}\n全部变更已逐条 git commit，可 /topics history <slug> 追溯、git revert 回滚。`)
+}
+
 async function doDistill(service: TopicsService, invocation: CommandInvocation, distillNow: ManualDistill | undefined): Promise<CommandResult> {
   if (distillNow === undefined) return fail('蒸馏 lane 未接线（宿主未提供手动蒸馏触发器）')
   const pending = await service.store.undistilledObservations(1)