@aiwayds/dsh-topics-memory 0.12.0 → 0.13.0

package/README.md

@@ -103,15 +103,18 @@ First-time setup belongs to `/topics onboard`; day-to-day tuning is `/topics set
 | `repo` | empty (local-only) | GitHub sync repo `owner/name`; suggested `dsh-topics-data`; empty = back to local-only |
 | `autoInject` | `true` | Per-turn injection master switch |
 | `injectDedup` | `true` | Session-level injection dedup: topics already injected in this session are not re-injected (registry cleared at session end; budget-dropped topics stay injectable; deduped topK slots are NOT backfilled) — ADR 0012 |
+| `suppressEcho` | `true` | Distill-echo suppression: topics distilled from the CURRENT session's own turns are not injected back into it (provenance rides the observations log `sessionId → distilledInto`) |
 | `topK` | `4` | Max topics injected per turn |
 | `perTopicBudget` | `300` | Per-topic digest token budget |
 | `totalBudget` | `1500` | Total injection budget per turn |
 | `matchThreshold` | `0.3` | Hit threshold; tune from `/topics stats` near-miss evidence |
-| `tagBoost` | `0.15` | Additive boost per tag hit |
+| `tagBoost` | `0.15` | Additive boost per tag hit (total cap across hits equals this value) |
+| `injectMode` | `pointer` | Injection shape: pointer (light pointers, ≤80 tok each, `topic_open` pulls the full text; total budget capped at 600) / digest (full digest rendering, per-topic 300 / total 1500) |
+| `qualityLane` | `sampled` | Slow quality lane: `off` / `sampled` (1/3 of turns) / `always`; produced at `turn/end`, consumed by the next injection (consume-once), never for subagent sessions |
 | `graphDepth` | `2` | `depends` graph walk depth (0 disables) |
 | `recencyWindowDays` | `7` | Recency bonus window (+0.2) |
 | `autoObserve` | `true` | Capture atomic observations every turn |
-| `includeSubagents` | `true` | Whether injection and observation also engage subagent sessions (ADR 0011); `off` skips them entirely |
+| `includeSubagents` | `false` | Whether injection and observation also engage subagent sessions (ADR 0011; off by default since 0.7.0); `off` skips them entirely |
 | `observationMaxChars` | `2000` | Per-side per-turn observation truncation |
 | `distillProvider` / `distillModel` | empty (distill off) | Distill lane model route; both must be set to enable. With a UI, `/topics set distill-provider` / `distill-model` without a value opens a picker panel (provider list → that provider's model catalog); a mixed `provider model` / `provider/model` value for `distill-model` splits into both keys |
 | `distillEveryTurns` | `5` | Distill every N turns of a long session |
@@ -132,7 +135,7 @@ This project's shape is directly inspired and supported by:
 
 ## Known boundaries
 
-- **Subagents engage memory by default — one switch to opt out**: by default (`include-subagents` on), injection and observation apply to subagent sessions too. `/topics set include-subagents off` skips delegated sessions entirely — no injection, no observation, no distill triggers; the topic tools stay on the global layer, so an explicit `topic_save` from a child still lands. Out-of-process subagents (claude-code/codex providers) never load this plugin anyway.
+- **Subagents are out of memory by default — one switch to opt in**: by default (`include-subagents` off since 0.7.0) delegated sessions are skipped entirely — no injection, no observation, no distill triggers; `/topics set include-subagents on` applies injection and observation to them too. The topic tools stay on the global layer, so an explicit `topic_save` from a child still lands. Out-of-process subagents (claude-code/codex providers) never load this plugin anyway.
 - **Exit is local-only (0.10.0)**: the plugin's disposer makes one local git commit of the meta sidecars (observations / injections / distill state) and never waits on the network — no pull, no push, no model call, so host exit no longer pays a git round-trip or a bounded distill wait (the old 90s cap is gone; only a 10s guard against a pathological git stall remains). The exit distill trigger is fired fire-and-forget and is skipped entirely while a session-end run is still in flight (the same pool head would otherwise be fed to the model twice). Nothing is lost by skipping: observations are write-through on disk, the deferred push is replayed by the next boot's pull, and the skipped distill is replayed there too (boot-replay). `meta/distill-state.json` records each lane's outcome, checkable via `/topics status`.
 - **Observation GC (three strikes)**: an observation the model actually evaluated (parseable answer, however useless) but no op consumed accrues one failed attempt; the third failed attempt physically deletes it — explicitly authorized cleanup of raw data the lane demonstrably cannot process. Runs that never evaluated the batch never count: infrastructure failures (network errors, unconfigured distill route → readable `no-model` short-circuit) and unparseable output (`invalid-output`) are exempt, and a batch still mid-shrink on output-limit retries is only counted once a verdict is reached (success, floor stop, stall, or an explicit skip). Deletions are committed immediately (data destruction stays git-traceable); pure attempt counters follow the usual flush cadence.
 - **Config read timing**: `/topics set` and `settings.yaml` edits take effect most reliably from the next session start.

package/README.zh.md

@@ -103,15 +103,18 @@ dsh plugin --profile <name> remove @aiwayds/dsh-topics-memory
 | `repo` | 空（local-only） | GitHub 同步仓 `owner/name`；建议 `dsh-topics-data`；置空回 local-only |
 | `autoInject` | `true` | 每轮注入总开关 |
 | `injectDedup` | `true` | 会话级注入去重：本会话已实际注入过的 Topic 不重注（会话结束清空注册表；被预算丢弃的仍可注入；被去重占用的 topK 名额不回填）——见 ADR 0012 |
+| `suppressEcho` | `true` | 蒸馏回声抑制：本会话蒸馏出的 Topic 不回注同会话（provenance 记入 observations 日志的 `sessionId → distilledInto`） |
 | `topK` | `4` | 每轮最多注入的 Topic 数 |
 | `perTopicBudget` | `300` | 单 Topic 摘要 token 预算 |
 | `totalBudget` | `1500` | 每轮注入总预算 |
 | `matchThreshold` | `0.3` | 命中阈值；按 `/topics stats` 的 near-miss 证据调 |
-| `tagBoost` | `0.15` | tag 命中加成 |
+| `tagBoost` | `0.15` | tag 命中加成（多次命中的总上限也为此值） |
+| `injectMode` | `pointer` | 注入形态：pointer（轻指针，单条 ≤80 tok，`topic_open` 拉全文；总预算上界锁 600）／digest（完整摘要渲染，per-topic 300 / 总 1500） |
+| `qualityLane` | `sampled` | 慢道质量 lane：`off`／`sampled`（1/3 轮触发）／`always`；`turn/end` 产出、下一轮注入消费（消费即清），子代理会话写死不跑 |
 | `graphDepth` | `2` | `depends` 图双向游走深度（0 关闭） |
 | `recencyWindowDays` | `7` | 近因加分窗口（+0.2） |
 | `autoObserve` | `true` | 每轮自动抓原子观察 |
-| `includeSubagents` | `true` | 注入与观察是否作用于子代理会话（ADR 0011）；`off` = 子代理整体跳过 |
+| `includeSubagents` | `false` | 注入与观察是否作用于子代理会话（ADR 0011；0.7.0 起默认 off）；`off` = 子代理整体跳过 |
 | `observationMaxChars` | `2000` | 每侧每轮观察截断长度 |
 | `distillProvider` / `distillModel` | 空（蒸馏关闭） | 蒸馏 lane 模型路由，两者都设置才启用。有 UI 时 `/topics set distill-provider` / `distill-model` 不带值会弹选择面板（provider 列表 → 该 provider 的模型目录）；带值时 `distill-model` 支持 `provider model` 或 `provider/model` 混写自动拆成两个键 |
 | `distillEveryTurns` | `5` | 长 session 每 N 轮触发一次蒸馏 |
@@ -132,7 +135,7 @@ dsh plugin --profile <name> remove @aiwayds/dsh-topics-memory
 
 ## 已知边界
 
-- **子代理默认参与记忆，可整体关掉**：默认（`include-subagents` 开）注入与观察同样作用于子代理会话。`/topics set include-subagents off` 后，delegation depth > 0 的子代理会话被整体跳过——不注入、不观察、不触发蒸馏；topic 工具始终在全局层（子代理显式 `topic_save` 不受开关影响）。跨进程子代理（claude-code/codex 等 provider）本就不加载本插件。
+- **子代理默认不参与记忆，可整体打开**：默认（`include-subagents` off，0.7.0 起）delegation depth > 0 的子代理会话被整体跳过——不注入、不观察、不触发蒸馏；`/topics set include-subagents on` 后注入与观察同样作用于子代理会话。topic 工具始终在全局层（子代理显式 `topic_save` 不受开关影响）。跨进程子代理（claude-code/codex 等 provider）本就不加载本插件。
 - **退出路径本地化（0.10.0）**：插件 disposer 只做一步本地 git commit（meta 侧车文件：observations / injections / distill state），不再等待任何网络——没有 pull、没有 push、没有模型调用，宿主退出不再支付 git 双程与有界蒸馏等待（旧的 90s 上限移除，仅保留 10s 兜底以防病理性 git 卡死）。退出蒸馏触发改为 fire-and-forget；已有 session-end run 在跑时整体跳过（否则同一全局队头批次会被双份喂给模型）。跳过不丢活：observations 本就 write-through 落盘，推迟的 push 由下次启动的 pull 补推，被跳过的蒸馏同样由下次启动回放（boot-replay）。`meta/distill-state.json` 记录每次 lane 的结局，`/topics status` 可查。
 - **观察 GC（三振删除）**：被模型实际评估（返回了可解析应答，无论内容有无价值）却未被任何 op 消费的观察记一次 failed attempt，连续 3 次即物理删除（用户已明确授权删除 lane 确实无法处理的原始观察）。模型从未评估过的批次永不计数：基础设施失败（网络错误、蒸馏路由未配置 → 可读 `no-model` 短路）与输出不可解析（`invalid-output`）豁免；输出上限减半重试中的批次只有到达裁决（成功 / 触底 / stalled / 明确跳过）才计一次。删除立即 commit（数据销毁 git 可追溯），纯计数沿用 flush 节奏。
 - **配置读取时机**：`/topics set` 与 settings.yaml 修改在下次会话启动后生效最稳。

package/lib/index.d.ts

@@ -1,20 +1,3 @@
-/**
- * dsh-topics-memory — OKF topic memory for DeepSeek Harness.
- *
- * Wiring (per ADR 0001–0008):
- *  - `topics` settings namespace (user-tunable via /topics set)
- *  - static systemPrompt section teaching the topic tools (never volatile
- *    content — the provider cache prefix stays byte-stable)
- *  - same-turn injection: retrieval runs synchronously at inbox-claim time
- *    (`agent/inbox/spliced` live event, which dispatches BEFORE prompt
- *    assembly — the only seam early enough, per the dsh-llmwiki upstream's
- *    validated recipe) and a systemPrompt.context() provider serves the assembled
- *    digest for this turn
- *  - model tools: topic_save / topic_search / topic_observe / topic_history
- *  - `/topics` command via the shared dsh-commands registry (optional peer)
- *  - observer (M2): turn capture + distill triggers over session events
- *  - sync (ADR 0003): pull on session start, debounced write-through push
- */
 import type { Context } from '@deepseek-ai/cordis';
 export declare const name = "dsh-topics-memory";
 /**
@@ -31,7 +14,8 @@ export declare const EXIT_COMMIT_TIMEOUT_MS = 10000;
  * naturally instead of being kept alive purely by the bound.
  */
 export declare function settleBounded(p: Promise<unknown> | undefined, ms: number): Promise<void>;
-/** Services consumed at apply time; llm joins via guarded ctx.inject. */
+/** Services consumed at apply time; llm joins via guarded ctx.inject, and the
+ *  skills registry serves the bundled usage/config guide. */
 export declare const inject: string[];
 /**
  * Settings-provider surface the legacy-namespace migration needs. Structurally
@@ -69,5 +53,16 @@ interface SettingsNsLike {
  * fire-and-forgets it.
  */
 export declare function migrateLegacySettings(settings: SettingsNsLike, warn?: (message: string) => void): Promise<void> | undefined;
+/**
+ * Strip a leading YAML frontmatter block (`---` / body / `---`) from a skill
+ * markdown file. `SkillDefinition.content` must be the instruction body after
+ * metadata removal — the same shape the filesystem provider serves — so the
+ * bundled SKILL.md, which keeps its frontmatter for the GitHub/manual install
+ * paths, has the block removed when served through {@link skillProvider.get}.
+ * Tolerant by design: input that does not open with a `---` line, or whose
+ * frontmatter block is never closed, is returned unchanged. Mirrors the
+ * delimiter semantics of the upstream skill-filesystem provider.
+ */
+export declare function stripFrontmatter(raw: string): string;
 export declare function apply(ctx: Context): void;
 export {};

package/lib/index.js

@@ -1,3 +1,27 @@
+/**
+ * dsh-topics-memory — OKF topic memory for DeepSeek Harness.
+ *
+ * Wiring (per ADR 0001–0008):
+ *  - `topics` settings namespace (user-tunable via /topics set)
+ *  - static systemPrompt section teaching the topic tools (never volatile
+ *    content — the provider cache prefix stays byte-stable)
+ *  - same-turn injection: retrieval runs synchronously at inbox-claim time
+ *    (`agent/inbox/spliced` live event, which dispatches BEFORE prompt
+ *    assembly — the only seam early enough, per the dsh-llmwiki upstream's
+ *    validated recipe) and a systemPrompt.context() provider serves the assembled
+ *    digest for this turn
+ *  - model tools: topic_save / topic_search / topic_observe / topic_history
+ *  - `/topics` command via the shared dsh-commands registry (optional peer)
+ *  - bundled usage/config skill served through ctx.skills.registerProvider
+ *  - observer (M2): turn capture + distill triggers over session events
+ *  - sync (ADR 0003): pull on session start, debounced write-through push
+ */
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+/** Mirrors dsh-skill's bundled-skill rank (a non-load-bearing ordering hint;
+ *  the constant is hardcoded there too). Local copy — see the type-import
+ *  note above for why dsh-skill is not loaded at runtime here. */
+const BUNDLED_SKILL_RANK = 600;
 import * as paths from "./paths.js";
 import { BundleStore } from "./store.js";
 import { TopicsService } from "./service.js";
@@ -34,8 +58,9 @@ export function settleBounded(p, ms) {
     const settled = p.then(() => undefined, () => undefined);
     return Promise.race([settled, cap]).finally(() => clearTimeout(timer));
 }
-/** Services consumed at apply time; llm joins via guarded ctx.inject. */
-export const inject = ['systemPrompt', 'tools', 'settings', 'agents', 'llm'];
+/** Services consumed at apply time; llm joins via guarded ctx.inject, and the
+ *  skills registry serves the bundled usage/config guide. */
+export const inject = ['systemPrompt', 'tools', 'settings', 'agents', 'llm', 'skills'];
 // dsh-settings 0.1.2-alpha.3 removed the runtime settingsNamespace() helper:
 // register() now brand-checks the namespace at the type level
 // (SettingsNamespaceInput) and validates the same lowercase-hyphenated
@@ -99,7 +124,76 @@ export function migrateLegacySettings(settings, warn) {
         return undefined;
     }
 }
+// --- Bundled skill -----------------------------------------------------------
+/** Provider name under `ctx.skills`; doubles as the skill name. */
+const SKILL_PROVIDER_NAME = 'dsh-topics-memory';
+/** 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);
+/** 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)),
+};
+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_CANDIDATE = {
+    name: SKILL_PROVIDER_NAME,
+    description: SKILL_DESCRIPTION,
+    invocation: SKILL_INVOCATION,
+    provider: SKILL_PROVIDER_NAME,
+    source: 'bundled',
+    resourceBase: SKILL_RESOURCE_BASE,
+    rank: BUNDLED_SKILL_RANK,
+    locator: SKILL_BODY_URL,
+};
+const skillProvider = {
+    name: SKILL_PROVIDER_NAME,
+    list: () => Promise.resolve([SKILL_CANDIDATE]),
+    async get(_candidate) {
+        return {
+            name: SKILL_CANDIDATE.name,
+            description: SKILL_CANDIDATE.description,
+            invocation: SKILL_CANDIDATE.invocation,
+            provider: SKILL_CANDIDATE.provider,
+            source: SKILL_CANDIDATE.source,
+            resourceBase: SKILL_RESOURCE_BASE,
+            content: stripFrontmatter(await readFile(SKILL_BODY_URL, 'utf8')),
+        };
+    },
+};
+/**
+ * Strip a leading YAML frontmatter block (`---` / body / `---`) from a skill
+ * markdown file. `SkillDefinition.content` must be the instruction body after
+ * metadata removal — the same shape the filesystem provider serves — so the
+ * bundled SKILL.md, which keeps its frontmatter for the GitHub/manual install
+ * paths, has the block removed when served through {@link skillProvider.get}.
+ * Tolerant by design: input that does not open with a `---` line, or whose
+ * frontmatter block is never closed, is returned unchanged. Mirrors the
+ * delimiter semantics of the upstream skill-filesystem provider.
+ */
+export function stripFrontmatter(raw) {
+    const firstLineEnd = raw.indexOf('\n');
+    if (firstLineEnd < 0 || raw.slice(0, firstLineEnd).replace(/\r$/, '') !== '---')
+        return raw;
+    let lineStart = firstLineEnd + 1;
+    while (lineStart <= raw.length) {
+        const nextNewline = raw.indexOf('\n', lineStart);
+        const lineEnd = nextNewline < 0 ? raw.length : nextNewline;
+        if (raw.slice(lineStart, lineEnd).replace(/\r$/, '') === '---') {
+            return raw.slice(nextNewline < 0 ? raw.length : nextNewline + 1).trim();
+        }
+        if (nextNewline < 0)
+            return raw;
+        lineStart = nextNewline + 1;
+    }
+    return raw;
+}
 export function apply(ctx) {
+    // `inject = ['skills']` guarantees the service exists on every real host;
+    // register unconditionally so a missing service fails loud instead of
+    // silently dropping the bundled skill.
+    ctx.skills.registerProvider(() => skillProvider);
     // dsh-settings is part of every real host closure but is a runtime-optional
     // peer so bare test harnesses can still load this module.
     const settingsNs = ctx.settings;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwayds/dsh-topics-memory",
-  "version": "0.12.0",
+  "version": "0.13.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",
@@ -32,13 +32,14 @@
   "files": [
     "lib",
     "cordis.patch.yml",
-    "src"
+    "src",
+    "skills"
   ],
   "scripts": {
     "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": "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",
     "smoke": "node scripts/smoke-boot.mjs"
   },
   "dependencies": {},
@@ -47,6 +48,7 @@
     "@deepseek-ai/dsh-tools": ">=0.1.2-rc.1",
     "@deepseek-ai/dsh-llm": ">=0.1.2-rc.1",
     "@deepseek-ai/dsh-settings": ">=0.1.2-rc.1",
+    "@deepseek-ai/dsh-skill": ">=0.1.2-rc.1",
     "@deepseek-ai/dsh-commands": ">=0.1.2-rc.1",
     "@deepseek-ai/dsh-util-values": ">=0.1.2-rc.1",
     "@deepseek-ai/schemastery": "^3.18.2"
@@ -64,6 +66,9 @@
     "@deepseek-ai/dsh-settings": {
       "optional": true
     },
+    "@deepseek-ai/dsh-skill": {
+      "optional": true
+    },
     "@deepseek-ai/dsh-commands": {
       "optional": true
     },
@@ -86,6 +91,7 @@
     "@deepseek-ai/dsh-scope": "0.1.2-rc.1",
     "@deepseek-ai/dsh-session": "0.1.2-rc.1",
     "@deepseek-ai/dsh-settings": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-skill": "0.1.2-rc.1",
     "@deepseek-ai/dsh-system-prompt": "0.1.2-rc.1",
     "@deepseek-ai/dsh-timeout": "0.1.2-rc.1",
     "@deepseek-ai/dsh-tools": "0.1.2-rc.1",

package/skills/dsh-topics-memory/SKILL.md

@@ -0,0 +1,91 @@
+---
+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。"
+---
+
+# dsh-topics-memory 使用指南（工作记忆 / 蒸馏 / 注入）
+
+> dsh 插件：把会话中的「问题/结论/影响/依赖」蒸馏成结构化 topic，按相关度每轮回注上下文，
+> 可选同步 GitHub 私有仓跨机共享。记忆是编辑出来的不是攒出来的——一个 topic 只记四件事
+> （起始问题、结论、影响、依赖），过程属于 session，结束就随它去。
+
+## 配置入口（settings.yaml 顶层 `topics:` 段）
+
+在 `~/.dsh/settings.yaml` 写顶层 `topics:` 段（只写非默认值即可）：
+
+| 键 | 默认 | 作用 |
+|---|---|---|
+| `repo` | 空（local-only） | GitHub 同步仓 `owner/name`；空 = local-only（数据在 `~/.dsh/topics`，`$DSH_TOPICS_HOME` 可覆盖）；建议仓库名 `dsh-topics-data`（与插件源码仓区分） |
+| `autoInject` | `true` | 每轮注入总开关 |
+| `injectDedup` | `true` | 会话级注入去重：本会话已实际注入过的 topic 不重注 |
+| `suppressEcho` | `true` | 蒸馏回声抑制：本会话蒸馏出的 topic 不回注同会话 |
+| `topK` | `4` | 每轮最多注入条数 |
+| `perTopicBudget` | `300` | 单 topic 摘要 token 预算（digest 形态用；pointer 形态单条 ≤80 tok） |
+| `totalBudget` | `1500` | 每轮注入总预算（digest 形态用；pointer 形态上界锁 600，旋钮可下调） |
+| `matchThreshold` | `0.3` | 命中阈值；按 `/topics stats` 的 near-miss 证据调 |
+| `tagBoost` | `0.15` | tag 命中加成（多次命中的总上限也为此值） |
+| `injectMode` | `pointer` | 注入形态：pointer（轻指针，单条 ≤80 tok，`topic_open` 拉全文）／digest（完整摘要 300/1500） |
+| `qualityLane` | `sampled` | 慢道质量 lane：off／sampled（1/3 轮）／always |
+| `graphDepth` | `2` | `depends` 图双向游走深度（0 关闭） |
+| `recencyWindowDays` | `7` | 近因加分窗口（+0.2） |
+| `autoObserve` | `true` | 每轮自动抓原子观察（`topic_observe` 之外的后台捕获） |
+| `includeSubagents` | `false` | 注入与观察是否作用于子代理会话；off 时子代理整体跳过（慢道写死不跑） |
+| `observationMaxChars` | `2000` | 每侧每轮观察截断长度 |
+| `distillEveryTurns` | `5` | 长 session 每 N 轮触发一次蒸馏 |
+| `distillOnSessionEnd` | `true` | session 结束时蒸馏一次 |
+| `distillProvider` / `distillModel` | 空（蒸馏关闭） | 蒸馏模型路由，两者都非空才启用 |
+| `distillBatchSize` | `40` | 每次蒸馏模型调用携带的观察条数（输出上限失败自动减半，下限 5） |
+| `distillMaxModelCalls` | `8` | 单次蒸馏 run 的模型调用预算（预算耗尽即停，已成功批次保留标记） |
+| `pushDebounceSeconds` | `45` | GitHub 模式去抖推送间隔 |
+
+- 全部键都可用 `/topics set <键> <值>` 运行时写回同段（即时校验：boolean 用 on|off、
+  inject-mode 限 pointer|digest、quality-lane 限 off|sampled|always、repo 须形如 owner/name；
+  distill-model 支持 `provider model` 或 `provider/model` 混写，自动拆成两个键）。
+  `/topics config` 看当前生效值；配置修改在下次会话启动后生效最稳。
+
+## 交互式配置向导（ask_user_question）
+
+用户说「帮我配置记忆 / 配置 topics」时优先引导跑 `/topics onboard`——dsh 原生 ask-user
+面板逐题收集（每题展示当前值，末步确认面板列出全部写入项，确认才写入；无 ask UI 的环境
+自动退化为逐条输入向导）：
+
+1. **存储模式**：local-only（推荐，零配置零凭据，数据只在 `~/.dsh/topics`）／
+   GitHub 同步（`owner/name` 私有仓，写穿 + 去抖推送，跨机共享；默认建议
+   `<gh登录名>/dsh-topics-data`）。
+2. **蒸馏模型**：跳过（先不启用，观察只积累，随时可开）／指定 provider → 该 provider 目录下的
+   model（两键都非空才启用；选完经路由预校验，provider 无活路由阻断重选）。
+3. **注入档位**：保守（topK 2 · 800 tok）／标准（topK 4 · 1.5k tok，默认）／放量（topK 6 · 2.5k tok）。
+4. **自动观察**：保持开（推荐，随手聊就被记录）／关闭（只手动 topic_save / topic_observe）。
+
+GitHub 模式凭据走 `$GITHUB_TOKEN` 或已登录的 gh CLI（`gh auth status` 检查；登录本身
+不在插件职责内，缺凭据先解决这一步）。
+
+## 命令速查
+
+| 命令 | 作用 |
+|------|------|
+| `/topics onboard` | 交互式配置向导（ask-user 面板，末步确认才写入） |
+| `/topics status` | bundle 健康：topic 数、观察积压、冲突、最近蒸馏、同步状态 |
+| `/topics distill` | 手动触发一次蒸馏 run（复用现有 lane 与 in-flight 守卫） |
+| `/topics stats` | 注入统计：hit rate、Top-N、near-miss 分布与调参建议 |
+| `/topics list` | 表格列出全部 Topic（带序号、最新优先、100 条封顶） |
+| `/topics show <slug>` | Topic 全文阅读页 + 反向引用（谁引用了我、怎么引用） |
+| `/topics history <slug>` | 结论变更史（git log 工具化，表格化输出） |
+| `/topics graph` | 生成关系图网页并自动在浏览器打开 |
+| `/topics sync [pull\|push]` | GitHub 模式手动同步（默认自动） |
+| `/topics config` | 当前生效配置（表格化输出） |
+| `/topics set <键> <值>` | 运行时写回配置（校验见上）；distill-provider / distill-model 不带值弹选择面板 |
+
+## 排障
+
+1. **注入太多/太吵**：下调 top-K、抬高 match-threshold 或压 total-budget；先看
+   `/topics stats` 的 near-miss 分布再动手，调参看证据不拍脑袋。
+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 去抖；退出只做
+   本地 commit 不等网络，推迟的 push 由下次启动 pull 后补推；rebase 冲突的 topic 降权标记，
+   `/topics status` 可查。
+4. **旧版 llmwiki 段自动迁移**：0.5.x 的 `llmwiki:` 设置段与 `~/.dsh/llmwiki` 数据目录在
+   首次启动时自动迁移到 `topics` / `~/.dsh/topics`，无需手工；旧插件还在运行时会警告跳过
+   （防双载脑裂），先从 profile 移除旧包。

package/src/index.ts

@@ -12,10 +12,25 @@
  *    digest for this turn
  *  - model tools: topic_save / topic_search / topic_observe / topic_history
  *  - `/topics` command via the shared dsh-commands registry (optional peer)
+ *  - bundled usage/config skill served through ctx.skills.registerProvider
  *  - observer (M2): turn capture + distill triggers over session events
  *  - sync (ADR 0003): pull on session start, debounced write-through push
  */
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
 import type { Context } from '@deepseek-ai/cordis'
+// Types only (erased at emit). The runtime import is deliberately avoided:
+// the registry-published dsh-skill lib imports host-closure siblings
+// (@deepseek-ai/dsh-scope, dsh-llm — peers of it, but absent from a plugin
+// repo's own dependency graph), which dies under pnpm's isolated layout.
+// The host injects the real service at runtime; these types only shape the
+// provider object this plugin hands it.
+import type { SkillCandidate, SkillDefinition, SkillProvider } from '@deepseek-ai/dsh-skill'
+
+/** Mirrors dsh-skill's bundled-skill rank (a non-load-bearing ordering hint;
+ *  the constant is hardcoded there too). Local copy — see the type-import
+ *  note above for why dsh-skill is not loaded at runtime here. */
+const BUNDLED_SKILL_RANK = 600
 // Type-only side-effect import: loads dsh-settings' `declare module
 // '@deepseek-ai/cordis'` augmentation, which is what puts `ctx.settings` on
 // the Context type. There is no runtime import — the host provides the
@@ -66,8 +81,9 @@ export function settleBounded(p: Promise<unknown> | undefined, ms: number): Prom
   return Promise.race([settled, cap]).finally(() => clearTimeout(timer))
 }
 
-/** Services consumed at apply time; llm joins via guarded ctx.inject. */
-export const inject = ['systemPrompt', 'tools', 'settings', 'agents', 'llm']
+/** Services consumed at apply time; llm joins via guarded ctx.inject, and the
+ *  skills registry serves the bundled usage/config guide. */
+export const inject = ['systemPrompt', 'tools', 'settings', 'agents', 'llm', 'skills']
 
 // dsh-settings 0.1.2-alpha.3 removed the runtime settingsNamespace() helper:
 // register() now brand-checks the namespace at the type level
@@ -160,7 +176,83 @@ export function migrateLegacySettings(settings: SettingsNsLike, warn?: (message:
   }
 }
 
+// --- Bundled skill -----------------------------------------------------------
+
+/** Provider name under `ctx.skills`; doubles as the skill name. */
+const SKILL_PROVIDER_NAME = 'dsh-topics-memory'
+
+/** 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)
+
+/** 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)),
+} as const
+
+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_CANDIDATE: SkillCandidate = {
+  name: SKILL_PROVIDER_NAME,
+  description: SKILL_DESCRIPTION,
+  invocation: SKILL_INVOCATION,
+  provider: SKILL_PROVIDER_NAME,
+  source: 'bundled',
+  resourceBase: SKILL_RESOURCE_BASE,
+  rank: BUNDLED_SKILL_RANK,
+  locator: SKILL_BODY_URL,
+}
+
+const skillProvider: SkillProvider = {
+  name: SKILL_PROVIDER_NAME,
+  list: () => Promise.resolve([SKILL_CANDIDATE]),
+  async get(_candidate): Promise<SkillDefinition> {
+    return {
+      name: SKILL_CANDIDATE.name,
+      description: SKILL_CANDIDATE.description,
+      invocation: SKILL_CANDIDATE.invocation,
+      provider: SKILL_CANDIDATE.provider,
+      source: SKILL_CANDIDATE.source,
+      resourceBase: SKILL_RESOURCE_BASE,
+      content: stripFrontmatter(await readFile(SKILL_BODY_URL, 'utf8')),
+    }
+  },
+}
+
+/**
+ * Strip a leading YAML frontmatter block (`---` / body / `---`) from a skill
+ * markdown file. `SkillDefinition.content` must be the instruction body after
+ * metadata removal — the same shape the filesystem provider serves — so the
+ * bundled SKILL.md, which keeps its frontmatter for the GitHub/manual install
+ * paths, has the block removed when served through {@link skillProvider.get}.
+ * Tolerant by design: input that does not open with a `---` line, or whose
+ * frontmatter block is never closed, is returned unchanged. Mirrors the
+ * delimiter semantics of the upstream skill-filesystem provider.
+ */
+export function stripFrontmatter(raw: string): string {
+  const firstLineEnd = raw.indexOf('\n')
+  if (firstLineEnd < 0 || raw.slice(0, firstLineEnd).replace(/\r$/, '') !== '---') return raw
+  let lineStart = firstLineEnd + 1
+  while (lineStart <= raw.length) {
+    const nextNewline = raw.indexOf('\n', lineStart)
+    const lineEnd = nextNewline < 0 ? raw.length : nextNewline
+    if (raw.slice(lineStart, lineEnd).replace(/\r$/, '') === '---') {
+      return raw.slice(nextNewline < 0 ? raw.length : nextNewline + 1).trim()
+    }
+    if (nextNewline < 0) return raw
+    lineStart = nextNewline + 1
+  }
+  return raw
+}
+
 export function apply(ctx: Context): void {
+  // `inject = ['skills']` guarantees the service exists on every real host;
+  // register unconditionally so a missing service fails loud instead of
+  // silently dropping the bundled skill.
+  ctx.skills.registerProvider(() => skillProvider)
   // dsh-settings is part of every real host closure but is a runtime-optional
   // peer so bare test harnesses can still load this module.
   const settingsNs = (ctx as unknown as { settings?: { register(n: unknown, s: unknown): { get(): unknown } } }).settings