@aiwayds/dsh-topics-memory 0.11.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/commands.js

@@ -86,18 +86,17 @@ function fail(text) {
 async function renderStatus(service) {
     const s = await service.store.status();
     const cfg = service.cfg;
-    const lines = [
-        `dsh-topics-memory @ ${s.root}`,
-        `  模式：${service.githubMode ? `github（${cfg.repo}）` : 'local-only'}`,
-        `  Topics：${s.topicCount}（draft ${s.byStatus.draft} / stable ${s.byStatus.stable} / deprecated ${s.byStatus.deprecated}）`,
-        `  观察积压：${s.observationsPending} 未蒸馏 / ${s.observationsTotal} 总量`,
-        `  冲突：${s.conflicts.length === 0 ? '无' : s.conflicts.join('、')}`,
-        `  损坏文件：${s.broken.length === 0 ? '无' : s.broken.join('、')}`,
-        `  git：${s.git ? `是（HEAD ${s.head?.slice(0, 10) ?? '??'}）` : '否'}`,
-        `  注入：${cfg.autoInject ? `${cfg.injectMode === 'digest' ? 'digest' : 'pointer'} 模式（topK ${cfg.topK}，预算 ${cfg.injectMode === 'digest' ? cfg.totalBudget : Math.min(cfg.totalBudget, 600)} tok，阈值 ${cfg.matchThreshold}）` : '关'}`,
-        `  去重：${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）'}`,
+    const rows = [
+        ['模式', service.githubMode ? `github（${cell(cfg.repo)}）` : 'local-only'],
+        ['Topics', `${s.topicCount}（draft ${s.byStatus.draft} / stable ${s.byStatus.stable} / deprecated ${s.byStatus.deprecated}）`],
+        ['观察积压', `${s.observationsPending} 未蒸馏 / ${s.observationsTotal} 总量`],
+        ['冲突', s.conflicts.length === 0 ? '无' : s.conflicts.map((c) => cell(c)).join('、')],
+        ['损坏文件', s.broken.length === 0 ? '无' : s.broken.map((b) => cell(b)).join('、')],
+        ['git', s.git ? `是（HEAD ${s.head?.slice(0, 10) ?? '??'}）` : '否'],
+        ['注入', cfg.autoInject ? `${cfg.injectMode === 'digest' ? 'digest' : 'pointer'} 模式（topK ${cfg.topK}，预算 ${cfg.injectMode === 'digest' ? cfg.totalBudget : Math.min(cfg.totalBudget, 600)} tok，阈值 ${cfg.matchThreshold}）` : '关'],
+        ['注入去重', 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）'],
     ];
     // Last lane outcome (distill-state summary) — what "checkable via
     // /topics status" promises; absent until the first run of this bundle.
@@ -107,14 +106,20 @@ async function renderStatus(service) {
             ? `标记 ${String(lastRun.marked ?? 0)} 条观察`
             : `失败（${String(lastRun.reason ?? 'unknown')}）`;
         const gc = typeof lastRun.gcDropped === 'number' && lastRun.gcDropped > 0 ? `，GC 回收 ${lastRun.gcDropped}` : '';
-        lines.push(`  最近蒸馏：${outcome}${gc} @ ${String(lastRun.at ?? '').slice(0, 19).replace('T', ' ')}`);
+        rows.push(['最近蒸馏', `${outcome}${gc} @ ${cell(String(lastRun.at ?? '').slice(0, 19).replace('T', ' '))}`]);
     }
     if (service.sync !== undefined) {
-        lines.push(`  上次推送：${service.sync.lastPushAt ?? '从未'}`);
+        rows.push(['上次推送', cell(String(service.sync.lastPushAt ?? '从未'))]);
         if (service.sync.lastError !== '')
-            lines.push(`  同步错误：${service.sync.lastError.split('\n').at(-1)}`);
+            rows.push(['同步错误', cell(service.sync.lastError.split('\n').at(-1) ?? '')]);
     }
-    return lines.join('\n');
+    return [
+        `dsh-topics-memory @ ${s.root}`,
+        '',
+        '| 字段 | 值 |',
+        '| --- | --- |',
+        ...rows.map(([k, v]) => `| ${k} | ${v} |`),
+    ].join('\n');
 }
 /**
  * `/topics distill` — one manual distill run over the current observation pool.
@@ -151,9 +156,13 @@ async function renderStats(service) {
         return '还没有注入记录 —— 用起来之后这里会有 hit rate / top-N / near-miss 分布。';
     const lines = [
         `注入统计（最近 ${records.length} 轮）：`,
-        `  hit rate：${(stats.hitRate * 100).toFixed(1)}%（${stats.injectedRounds}/${stats.rounds} 轮注入）`,
-        `  零命中轮：${stats.zeroHitRounds}；平均命中 ${stats.avgHitsPerRound} 条/轮`,
-        `  平均预算占用：${stats.avgBudgetUtilization} tok`,
+        '',
+        '| 指标 | 值 |',
+        '| --- | --- |',
+        `| hit rate | ${(stats.hitRate * 100).toFixed(1)}%（${stats.injectedRounds}/${stats.rounds} 轮注入） |`,
+        `| 零命中轮 | ${stats.zeroHitRounds} |`,
+        `| 平均命中 | ${stats.avgHitsPerRound} 条/轮 |`,
+        `| 平均预算占用 | ${stats.avgBudgetUtilization} tok |`,
     ];
     // v4 lane split — how much of the injection traffic each lane carries.
     const slowRounds = records.filter((r) => r.lane === 'slow' || r.lane === 'mixed').length;
@@ -166,7 +175,7 @@ async function renderStats(service) {
                 .sort((a, b) => a - b);
             medianLag = `，赶上中位时延 ${(lags[Math.floor(lags.length / 2)] / 1000).toFixed(1)}s`;
         }
-        lines.push(`  慢道参与轮：${slowRounds}（快 ${(records.length - slowRounds)} / 慢或混合 ${slowRounds}${medianLag}）`);
+        lines.push(`| 慢道参与轮 | ${slowRounds}（快 ${records.length - slowRounds} / 慢或混合 ${slowRounds}${medianLag}） |`);
     }
     // Pointer open rate (v4 §4.3): topic_open calls vs pointer entries injected.
     // Echoed hits ride the retrieval but never became pointers — excluded here.
@@ -176,24 +185,24 @@ async function renderStats(service) {
             r.hits.filter((h) => !(r.deduped ?? []).includes(h.slug) && !(r.echoed ?? []).includes(h.slug)).length +
             (r.slow?.length ?? 0), 0);
         const rate = entries === 0 ? 0 : Math.min(1, opens.length / entries);
-        lines.push(`  指针打开率：${(rate * 100).toFixed(1)}%（${opens.length} 次 topic_open / ${entries} 条注入指针）`);
+        lines.push(`| 指针打开率 | ${(rate * 100).toFixed(1)}%（${opens.length} 次 topic_open / ${entries} 条注入指针） |`);
     }
     const echoedCount = records.reduce((acc, r) => acc + (r.echoed?.length ?? 0), 0);
     if (echoedCount > 0) {
-        lines.push(`  回声抑制：${echoedCount} 次（本会话蒸馏出的 topic 不回注）`);
+        lines.push(`| 回声抑制 | ${echoedCount} 次（本会话蒸馏出的 topic 不回注） |`);
     }
     if (stats.topTopics.length > 0) {
-        lines.push('  Top-N 被注入 Topic：');
+        lines.push('', 'Top-N 被注入 Topic：', '', '| Slug | 注入次数 |', '| --- | --- |');
         for (const t of stats.topTopics.slice(0, 5))
-            lines.push(`    ${t.slug} ×${t.count}`);
+            lines.push(`| \`${cell(t.slug)}\` | ${t.count} |`);
     }
     if (stats.nearMissHistogram.length > 0) {
-        lines.push('  Near-miss 分布（低于阈值或被结构门挡下）：');
+        lines.push('', 'Near-miss 分布（低于阈值或被结构门挡下）：', '', '| 分数段 | 次数 |', '| --- | --- |');
         for (const b of stats.nearMissHistogram)
-            lines.push(`    ${b.bucket}: ${b.count}`);
+            lines.push(`| ${cell(b.bucket)} | ${b.count} |`);
         const hint = tuningHint(stats, service.cfg.matchThreshold);
         if (hint !== undefined)
-            lines.push(`  💡 ${hint}`);
+            lines.push('', `💡 ${hint}`);
     }
     return lines.join('\n');
 }
@@ -207,20 +216,31 @@ export function tuningHint(stats, threshold) {
     }
     return undefined;
 }
+/** /topics list caps the table at this many newest topics. */
+const LIST_LIMIT = 100;
 async function renderList(service) {
     const metas = await service.store.listTopics();
     if (metas.length === 0)
         return 'Bundle 里还没有 Topic —— 在会话里让我记点什么，或 /topics set 配置好蒸馏。';
-    metas.sort((a, b) => a.slug.localeCompare(b.slug));
+    // Newest first, capped: with a large bundle the table is for scanning
+    // recent work, not an exhaustive roster — /topics show <slug> reaches any
+    // topic the cap hides. (store.ts re-stamps generated.at on every topic
+    // write, so it IS the updated-at time; the slug tiebreak keeps same-stamp
+    // rows stable.)
+    metas.sort((a, b) => b.generatedAt.localeCompare(a.generatedAt) || a.slug.localeCompare(b.slug));
+    const shown = metas.slice(0, LIST_LIMIT);
     const lines = [
-        `共 ${metas.length} 个 Topic：`,
+        `共 ${metas.length} 个 Topic（按最近更新排序）：`,
         '',
-        '| Slug | 标题 | 状态 | 标签 | 更新 |',
-        '| --- | --- | --- | --- | --- |',
+        '| # | Slug | 标题 | 状态 | 标签 | 更新 |',
+        '| --- | --- | --- | --- | --- | --- |',
     ];
-    for (const m of metas) {
+    shown.forEach((m, i) => {
         const tags = m.tags.length > 0 ? m.tags.map((t) => `#${cell(t)}`).join(' ') : '—';
-        lines.push(`| \`${cell(m.slug)}\` | ${cell(m.title)} | ${m.status} | ${tags} | ${cell(m.generatedAt.slice(0, 10))} |`);
+        lines.push(`| ${i + 1} | \`${cell(m.slug)}\` | ${cell(m.title)} | ${m.status} | ${tags} | ${cell(m.generatedAt.slice(0, 10))} |`);
+    });
+    if (metas.length > shown.length) {
+        lines.push('', `… 其余 ${metas.length - shown.length} 个更早的 Topic 未显示（/topics show <slug> 直达）。`);
     }
     return lines.join('\n');
 }
@@ -254,11 +274,15 @@ async function renderHistory(service, slug) {
     const { entries } = await service.history(slug, 30);
     if (entries.length === 0)
         return fail(`Topic “${slug}” 没有历史（不存在或 bundle 不是 git 仓库）`);
-    const lines = [`${slug} 的变更史（${entries.length} 条）：`];
+    const lines = [
+        `${slug} 的变更史（${entries.length} 条）：`,
+        '',
+        '| Hash | 时间 | 变更 | 当时的结论 |',
+        '| --- | --- | --- | --- |',
+    ];
     for (const e of entries) {
-        lines.push(`  ${e.hash} ${e.date.slice(0, 19).replace('T', ' ')} ${e.message}`);
-        if (e.conclusion !== undefined && e.conclusion !== '')
-            lines.push(`      └ 结论当时：${e.conclusion}`);
+        const conclusion = e.conclusion !== undefined && e.conclusion !== '' ? cell(e.conclusion) : '—';
+        lines.push(`| \`${cell(e.hash)}\` | ${cell(e.date.slice(0, 19).replace('T', ' '))} | ${cell(e.message)} | ${conclusion} |`);
     }
     return ok(lines.join('\n'));
 }
@@ -316,9 +340,14 @@ async function doSync(service, direction) {
     return fail('用法：/topics sync [pull|push]');
 }
 function renderConfig(cfg) {
-    const lines = ['当前配置：'];
+    const lines = [
+        '当前配置：',
+        '',
+        '| 配置项 | 值 |',
+        '| --- | --- |',
+    ];
     for (const key of CONFIG_KEYS) {
-        lines.push(`  ${displayKey(key)} = ${String(cfg[key])}`);
+        lines.push(`| ${displayKey(key)} | ${cell(String(cfg[key]))} |`);
     }
     return lines.join('\n');
 }

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.11.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/commands.ts

@@ -114,18 +114,17 @@ function fail(text: string): CommandResult {
 async function renderStatus(service: TopicsService): Promise<string> {
   const s = await service.store.status()
   const cfg = service.cfg
-  const lines = [
-    `dsh-topics-memory @ ${s.root}`,
-    `  模式：${service.githubMode ? `github（${cfg.repo}）` : 'local-only'}`,
-    `  Topics：${s.topicCount}（draft ${s.byStatus.draft} / stable ${s.byStatus.stable} / deprecated ${s.byStatus.deprecated}）`,
-    `  观察积压：${s.observationsPending} 未蒸馏 / ${s.observationsTotal} 总量`,
-    `  冲突：${s.conflicts.length === 0 ? '无' : s.conflicts.join('、')}`,
-    `  损坏文件：${s.broken.length === 0 ? '无' : s.broken.join('、')}`,
-    `  git：${s.git ? `是（HEAD ${s.head?.slice(0, 10) ?? '??'}）` : '否'}`,
-    `  注入：${cfg.autoInject ? `${cfg.injectMode === 'digest' ? 'digest' : 'pointer'} 模式（topK ${cfg.topK}，预算 ${cfg.injectMode === 'digest' ? cfg.totalBudget : Math.min(cfg.totalBudget, 600)} tok，阈值 ${cfg.matchThreshold}）` : '关'}`,
-    `  去重：${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）'}`,
+  const rows: [string, string][] = [
+    ['模式', service.githubMode ? `github（${cell(cfg.repo)}）` : 'local-only'],
+    ['Topics', `${s.topicCount}（draft ${s.byStatus.draft} / stable ${s.byStatus.stable} / deprecated ${s.byStatus.deprecated}）`],
+    ['观察积压', `${s.observationsPending} 未蒸馏 / ${s.observationsTotal} 总量`],
+    ['冲突', s.conflicts.length === 0 ? '无' : s.conflicts.map((c) => cell(c)).join('、')],
+    ['损坏文件', s.broken.length === 0 ? '无' : s.broken.map((b) => cell(b)).join('、')],
+    ['git', s.git ? `是（HEAD ${s.head?.slice(0, 10) ?? '??'}）` : '否'],
+    ['注入', cfg.autoInject ? `${cfg.injectMode === 'digest' ? 'digest' : 'pointer'} 模式（topK ${cfg.topK}，预算 ${cfg.injectMode === 'digest' ? cfg.totalBudget : Math.min(cfg.totalBudget, 600)} tok，阈值 ${cfg.matchThreshold}）` : '关'],
+    ['注入去重', 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）'],
   ]
   // Last lane outcome (distill-state summary) — what "checkable via
   // /topics status" promises; absent until the first run of this bundle.
@@ -136,13 +135,19 @@ async function renderStatus(service: TopicsService): Promise<string> {
         ? `标记 ${String(lastRun.marked ?? 0)} 条观察`
         : `失败（${String(lastRun.reason ?? 'unknown')}）`
     const gc = typeof lastRun.gcDropped === 'number' && lastRun.gcDropped > 0 ? `，GC 回收 ${lastRun.gcDropped}` : ''
-    lines.push(`  最近蒸馏：${outcome}${gc} @ ${String(lastRun.at ?? '').slice(0, 19).replace('T', ' ')}`)
+    rows.push(['最近蒸馏', `${outcome}${gc} @ ${cell(String(lastRun.at ?? '').slice(0, 19).replace('T', ' '))}`])
   }
   if (service.sync !== undefined) {
-    lines.push(`  上次推送：${service.sync.lastPushAt ?? '从未'}`)
-    if (service.sync.lastError !== '') lines.push(`  同步错误：${service.sync.lastError.split('\n').at(-1)}`)
+    rows.push(['上次推送', cell(String(service.sync.lastPushAt ?? '从未'))])
+    if (service.sync.lastError !== '') rows.push(['同步错误', cell(service.sync.lastError.split('\n').at(-1) ?? '')])
   }
-  return lines.join('\n')
+  return [
+    `dsh-topics-memory @ ${s.root}`,
+    '',
+    '| 字段 | 值 |',
+    '| --- | --- |',
+    ...rows.map(([k, v]) => `| ${k} | ${v} |`),
+  ].join('\n')
 }
 
 /**
@@ -178,9 +183,13 @@ async function renderStats(service: TopicsService): Promise<string> {
   if (records.length === 0) return '还没有注入记录 —— 用起来之后这里会有 hit rate / top-N / near-miss 分布。'
   const lines = [
     `注入统计（最近 ${records.length} 轮）：`,
-    `  hit rate：${(stats.hitRate * 100).toFixed(1)}%（${stats.injectedRounds}/${stats.rounds} 轮注入）`,
-    `  零命中轮：${stats.zeroHitRounds}；平均命中 ${stats.avgHitsPerRound} 条/轮`,
-    `  平均预算占用：${stats.avgBudgetUtilization} tok`,
+    '',
+    '| 指标 | 值 |',
+    '| --- | --- |',
+    `| hit rate | ${(stats.hitRate * 100).toFixed(1)}%（${stats.injectedRounds}/${stats.rounds} 轮注入） |`,
+    `| 零命中轮 | ${stats.zeroHitRounds} |`,
+    `| 平均命中 | ${stats.avgHitsPerRound} 条/轮 |`,
+    `| 平均预算占用 | ${stats.avgBudgetUtilization} tok |`,
   ]
   // v4 lane split — how much of the injection traffic each lane carries.
   const slowRounds = records.filter((r) => r.lane === 'slow' || r.lane === 'mixed').length
@@ -193,7 +202,7 @@ async function renderStats(service: TopicsService): Promise<string> {
         .sort((a, b) => a - b)
       medianLag = `，赶上中位时延 ${(lags[Math.floor(lags.length / 2)] / 1000).toFixed(1)}s`
     }
-    lines.push(`  慢道参与轮：${slowRounds}（快 ${(records.length - slowRounds)} / 慢或混合 ${slowRounds}${medianLag}）`)
+    lines.push(`| 慢道参与轮 | ${slowRounds}（快 ${records.length - slowRounds} / 慢或混合 ${slowRounds}${medianLag}） |`)
   }
   // Pointer open rate (v4 §4.3): topic_open calls vs pointer entries injected.
   // Echoed hits ride the retrieval but never became pointers — excluded here.
@@ -207,21 +216,21 @@ async function renderStats(service: TopicsService): Promise<string> {
       0,
     )
     const rate = entries === 0 ? 0 : Math.min(1, opens.length / entries)
-    lines.push(`  指针打开率：${(rate * 100).toFixed(1)}%（${opens.length} 次 topic_open / ${entries} 条注入指针）`)
+    lines.push(`| 指针打开率 | ${(rate * 100).toFixed(1)}%（${opens.length} 次 topic_open / ${entries} 条注入指针） |`)
   }
   const echoedCount = records.reduce((acc, r) => acc + (r.echoed?.length ?? 0), 0)
   if (echoedCount > 0) {
-    lines.push(`  回声抑制：${echoedCount} 次（本会话蒸馏出的 topic 不回注）`)
+    lines.push(`| 回声抑制 | ${echoedCount} 次（本会话蒸馏出的 topic 不回注） |`)
   }
   if (stats.topTopics.length > 0) {
-    lines.push('  Top-N 被注入 Topic：')
-    for (const t of stats.topTopics.slice(0, 5)) lines.push(`    ${t.slug} ×${t.count}`)
+    lines.push('', 'Top-N 被注入 Topic：', '', '| Slug | 注入次数 |', '| --- | --- |')
+    for (const t of stats.topTopics.slice(0, 5)) lines.push(`| \`${cell(t.slug)}\` | ${t.count} |`)
   }
   if (stats.nearMissHistogram.length > 0) {
-    lines.push('  Near-miss 分布（低于阈值或被结构门挡下）：')
-    for (const b of stats.nearMissHistogram) lines.push(`    ${b.bucket}: ${b.count}`)
+    lines.push('', 'Near-miss 分布（低于阈值或被结构门挡下）：', '', '| 分数段 | 次数 |', '| --- | --- |')
+    for (const b of stats.nearMissHistogram) lines.push(`| ${cell(b.bucket)} | ${b.count} |`)
     const hint = tuningHint(stats, service.cfg.matchThreshold)
-    if (hint !== undefined) lines.push(`  💡 ${hint}`)
+    if (hint !== undefined) lines.push('', `💡 ${hint}`)
   }
   return lines.join('\n')
 }
@@ -237,19 +246,31 @@ export function tuningHint(stats: ReturnType<typeof aggregateStats>, threshold:
   return undefined
 }
 
+/** /topics list caps the table at this many newest topics. */
+const LIST_LIMIT = 100
+
 async function renderList(service: TopicsService): Promise<string> {
   const metas = await service.store.listTopics()
   if (metas.length === 0) return 'Bundle 里还没有 Topic —— 在会话里让我记点什么，或 /topics set 配置好蒸馏。'
-  metas.sort((a, b) => a.slug.localeCompare(b.slug))
+  // Newest first, capped: with a large bundle the table is for scanning
+  // recent work, not an exhaustive roster — /topics show <slug> reaches any
+  // topic the cap hides. (store.ts re-stamps generated.at on every topic
+  // write, so it IS the updated-at time; the slug tiebreak keeps same-stamp
+  // rows stable.)
+  metas.sort((a, b) => b.generatedAt.localeCompare(a.generatedAt) || a.slug.localeCompare(b.slug))
+  const shown = metas.slice(0, LIST_LIMIT)
   const lines = [
-    `共 ${metas.length} 个 Topic：`,
+    `共 ${metas.length} 个 Topic（按最近更新排序）：`,
     '',
-    '| Slug | 标题 | 状态 | 标签 | 更新 |',
-    '| --- | --- | --- | --- | --- |',
+    '| # | Slug | 标题 | 状态 | 标签 | 更新 |',
+    '| --- | --- | --- | --- | --- | --- |',
   ]
-  for (const m of metas) {
+  shown.forEach((m, i) => {
     const tags = m.tags.length > 0 ? m.tags.map((t) => `#${cell(t)}`).join(' ') : '—'
-    lines.push(`| \`${cell(m.slug)}\` | ${cell(m.title)} | ${m.status} | ${tags} | ${cell(m.generatedAt.slice(0, 10))} |`)
+    lines.push(`| ${i + 1} | \`${cell(m.slug)}\` | ${cell(m.title)} | ${m.status} | ${tags} | ${cell(m.generatedAt.slice(0, 10))} |`)
+  })
+  if (metas.length > shown.length) {
+    lines.push('', `… 其余 ${metas.length - shown.length} 个更早的 Topic 未显示（/topics show <slug> 直达）。`)
   }
   return lines.join('\n')
 }
@@ -281,10 +302,15 @@ async function renderHistory(service: TopicsService, slug: string | undefined):
   if (slug === undefined || slug === '') return fail('用法：/topics history <slug>')
   const { entries } = await service.history(slug, 30)
   if (entries.length === 0) return fail(`Topic “${slug}” 没有历史（不存在或 bundle 不是 git 仓库）`)
-  const lines = [`${slug} 的变更史（${entries.length} 条）：`]
+  const lines = [
+    `${slug} 的变更史（${entries.length} 条）：`,
+    '',
+    '| Hash | 时间 | 变更 | 当时的结论 |',
+    '| --- | --- | --- | --- |',
+  ]
   for (const e of entries) {
-    lines.push(`  ${e.hash} ${e.date.slice(0, 19).replace('T', ' ')} ${e.message}`)
-    if (e.conclusion !== undefined && e.conclusion !== '') lines.push(`      └ 结论当时：${e.conclusion}`)
+    const conclusion = e.conclusion !== undefined && e.conclusion !== '' ? cell(e.conclusion) : '—'
+    lines.push(`| \`${cell(e.hash)}\` | ${cell(e.date.slice(0, 19).replace('T', ' '))} | ${cell(e.message)} | ${conclusion} |`)
   }
   return ok(lines.join('\n'))
 }
@@ -341,9 +367,14 @@ async function doSync(service: TopicsService, direction: string | undefined): Pr
 }
 
 function renderConfig(cfg: TopicsConfigValue): string {
-  const lines = ['当前配置：']
+  const lines = [
+    '当前配置：',
+    '',
+    '| 配置项 | 值 |',
+    '| --- | --- |',
+  ]
   for (const key of CONFIG_KEYS) {
-    lines.push(`  ${displayKey(key)} = ${String(cfg[key])}`)
+    lines.push(`| ${displayKey(key)} | ${cell(String(cfg[key]))} |`)
   }
   return lines.join('\n')
 }

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