@aiwayds/dsh-topics-memory 0.6.0

package/README.md

@@ -0,0 +1,112 @@
+# dsh-topics-memory
+
+English | [中文](README.zh.md)
+
+A dsh plugin: maintains "working topic memory" as an [OKF (Open Knowledge Format v0.2)](https://github.com/GoogleCloudPlatform/open-knowledge-format) knowledge bundle, persisted in a local git repository (optionally synced to a private GitHub repo), with conclusions traceable through git history, sessions automatically observed and distilled into knowledge, and relevant topics injected to the model before every turn.
+
+> **Requires dsh >= 0.1.2-alpha.4** (adapted to the dsh 0.1.2-alpha.4 settings namespace and LLM seam; the rc line is no longer supported).
+
+## The problem it solves
+
+Long sessions forget. Cross-session, even more so. This plugin maintains **structured topic memory**: each Topic records a matter's **name, dependencies, open questions, current conclusion, impact, and recommendations**. When a conclusion changes, edit the file and commit — `git log` directly answers "when, by whom, and why did this conclusion change".
+
+## Core features
+
+- **Strict OKF v0.2 compliance**: each Topic is a `markdown + YAML frontmatter` concept document (`type: Topic`) that the whole OKF ecosystem (Obsidian, OKF validators) can consume directly; ships with the provenance (`sources`), trust (`generated`/`verified`), and lifecycle (`status`/`stale_after`) field families.
+- **Git-traceable**: one conclusion change = one commit (write-through); the `topic_history` tool and `/topics history` make change history first-class.
+- **Local-first**: local-only mode by default (`~/.dsh/topics/`), zero config, zero credentials; setting `repo` enables GitHub sync (single repo, single bundle, single `main`, write-through + debounced push; rebase conflicts are demoted and flagged for a human — no automatic smart-merge).
+- **LLM-free hot-path injection**: per-turn lexical matching (CJK bigrams + words + weighted tags + `depends` graph walk), millisecond-scale; zero matches = zero injection; per-topic digest ≤300 tokens, top-K ≤4, total budget ≤1.5k tokens — all configurable.
+- **Observable, tunable injection**: every turn writes an Injection Log (hits, scores, near-misses, budget usage); `/topics stats` reports hit rate, top-N, near-miss distribution, and tuning suggestions — tune from evidence, not vibes.
+- **Knowledge as a graph**: `depends` (machine-readable directed edges) plus body `[[wikilinks]]` and markdown links (human-written edges) form one graph; retrieval walks it in both directions (per-level decay, configurable depth) so a single hit pulls in a knowledge subgraph; every write rebuilds the `meta/backlinks.json` reverse index, and `/topics show` lists "who references me, and how" — check the blast radius before changing a conclusion.
+- **Two-stage observer (M2)**: the main model jots atomic observations with `topic_observe`; a background distill lane (session end + every N turns, model configurable) distills them into formal Topics in batches; when the model itself deems something worth keeping, it `topic_save`s directly.
+
+## Quick start
+
+1. Install (command below), restart dsh;
+2. Run `/topics onboard` — native dsh ask-user panels walk you through the five decisions: mode / repo / distill model / injection tier / auto-observe — nothing is written until the final confirm;
+3. Work as usual: relevant conclusions are injected every turn; say "remember…" to have the model `topic_save`; `/topics status` for health, `/topics stats` for injection stats.
+
+## Tools & commands
+
+| Model tools | Purpose |
+|---|---|
+| `topic_save` | Distill/revise a Topic (name / dependencies / open questions / conclusion / impact / recommendations) |
+| `topic_observe` | Jot an atomic observation (decision/finding/constraint/question), pending distill |
+| `topic_search` | LLM-free keyword search over memory |
+| `topic_history` | A topic's conclusion change history (git log as a tool) |
+
+| Command | Purpose |
+|---|---|
+| `/topics onboard` | Interactive setup wizard on dsh-native ask-user panels (mode / repo / distill model / injection tier / auto-observe); typed fallback where no ask-user UI exists |
+| `/topics status` | Bundle health: topic count, observation backlog, conflicts, last distill outcome, sync status |
+| `/topics distill` | Manually trigger one distill run over the current observation pool (same lane, same in-flight guard; summary mirrors the distill-state fields) |
+| `/topics stats` | Injection stats: hit rate, top-N, near-miss distribution, tuning advice |
+| `/topics list` / `show` / `history` | Browse topics, backlinks, and change history |
+| `/topics graph` | Generate a relationship-graph web page (force-directed, draggable/zoomable, hover for conclusions) and open it in the browser |
+| `/topics sync [pull\|push]` | GitHub mode: manual pull/push (automatic by default) |
+| `/topics config` / `set <key> <value>` | View and edit config (thresholds, budgets, distill model, …) |
+
+## Install
+
+```bash
+dsh plugin --profile <your profile> add @aiwayds/dsh-topics-memory
+```
+
+First thing after installing: run `/topics onboard`. The bundle lives at `~/.dsh/topics/` by default (`$DSH_TOPICS_HOME` overrides). GitHub sync: `/topics set repo <owner/name>` (suggested repo name `dsh-topics-data`, to keep it distinct from the plugin's own source repo); credentials come from `$GITHUB_TOKEN` or a logged-in gh CLI (login is not this plugin's job).
+
+### Upgrading from 0.5.x (rename)
+
+0.6.0 renames the plugin: `@aiwayds/dsh-llmwiki-memory` → `@aiwayds/dsh-topics-memory`, the `/wiki` command family → `/topics`, and the settings namespace `llmwiki` → `topics`. Install the new package (and remove the old one from your profile) — on first start the plugin migrates everything automatically: the data directory `~/.dsh/llmwiki` is renamed to `~/.dsh/topics`, and user-tuned values in the old `llmwiki` settings namespace are copied into `topics`. No manual steps; if a migration step fails the plugin falls back to the old locations and keeps working.
+
+## Configuration
+
+First-time setup belongs to `/topics onboard`; day-to-day tuning is `/topics set <key> <value>` (writes the `topics` namespace in `settings.yaml`, effective from the next session). All keys and defaults:
+
+| Key | Default | Meaning |
+|---|---|---|
+| `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 |
+| `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 |
+| `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 |
+| `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 |
+| `distillOnSessionEnd` | `true` | Distill once when a session ends |
+| `distillBatchSize` | `40` | Observations per distill model call. On an output-limit (`max-tokens`) failure the batch halves automatically (floor 5) and retries — a failing batch can no longer livelock the backlog; the shrink persists until reload or a config change. Note: `/topics set distillBatchSize` back to the same value does not reset the shrink — set a different value or reload the plugin |
+| `distillMaxModelCalls` | `8` | Max model calls per distill run, including the one corrective retry for ops echoing no valid `observed_ids` (the run stalls when the budget can't fit it). Batches already distilled keep their marks when the budget stops the run (partial progress), recorded as `partial: …` in the distill state |
+| `pushDebounceSeconds` | `45` | GitHub-mode debounced push interval |
+
+## Acknowledgements
+
+This project's shape is directly inspired and supported by:
+
+- **[zosmaai/pi-llm-wiki](https://github.com/zosmaai/pi-llm-wiki)** — a native OKF v0.2 knowledge extension for pi and this project's direct inspiration; its two-stage observation (cheap atomic observations + background distill), cache-safe injection (volatile content never enters the system prompt), and layered vault & ownership model are all absorbed here.
+- **[GoogleCloudPlatform/open-knowledge-format](https://github.com/GoogleCloudPlatform/open-knowledge-format)** — the Open Knowledge Format (OKF) v0.2 spec this bundle format strictly follows.
+- **[Karpathy's LLM Wiki pattern](https://gist.github.com/karpathy/442a5bf55591489e981c11519de94f)** — the starting point of the whole "an LLM maintains a personal knowledge base" methodology.
+- **[fan56/pi-topic-memory](https://github.com/fan56/pi-topic-memory)** — the same author's predecessor: a working topic ledger with silent injection for pi; its LLM-free hot-path matching and injection-timing experience is this project's direct technical ancestor.
+- **[chancelu/dsh-llmwiki](https://github.com/chancelu/dsh-llmwiki)** — a fellow dsh-ecosystem precedent; this project's same-turn injection seam (`agent/inbox/spliced` + `systemPrompt.context()`) follows the mechanism it validated on real dsh.
+
+## 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.
+- **Session-end distill in headless one-shot sessions**: the plugin's disposer now waits (bounded, up to 90s) for the exit-triggered distill to land before unload completes, so a headless process no longer loses that race by default; a hanging model call gives up at the cap and exit proceeds without that run. Within that 90s window the exit run may complete only part of its call budget — the remaining backlog waits for the next trigger. The exit trigger is skipped entirely while a session-end run is still in flight (the same pool head would otherwise be fed to the model twice). Manual `/topics distill` runs inside a live session bypass the race entirely; `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.
+- **Picking a distill model**: `/topics onboard` splits the distill decision into two dependent questions (provider first, then that provider's model catalog), pre-validated with `resolveModelInfo` — a provider with no live route blocks and re-asks, an off-catalog model (a non-NO_ADAPTER failure: outside the advisory catalog, possibly still usable) warns but is allowed; hosts without an ask UI or a usable model route fall back to typed input. The same validation backs the `/topics set` picker panels.
+
+## Design docs
+
+- [CONTEXT.md](CONTEXT.md) — domain glossary
+- [docs/adr/](docs/adr/) — 0001–0013: OKF compliance, remote shape, sync strategy, two-stage observer, bundle layout, injection defaults, observability & tunables, dual-mode persistence, onboarding wizard, subagent isolation, the include-subagents switch, injection dedup default-on, the rename & migration
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,112 @@
+# dsh-topics-memory
+
+[English](README.md) | 中文
+
+一个 dsh 插件：把「工作 topic 记忆」维护成 [OKF 标准（Open Knowledge Format v0.2）](https://github.com/GoogleCloudPlatform/open-knowledge-format)的知识 bundle，持久化在本地 git 仓库（可选同步到 GitHub 私有仓库），利用 git 历史提供结论可追溯性，自动观察会话沉淀知识，并在每轮对话前向模型注入相关 Topic。
+
+> **Requires dsh >= 0.1.2-alpha.4**（适配 dsh 0.1.2-alpha.4 的 settings 命名空间与 LLM seam；不再兼容 rc 线宿主）。
+
+## 它解决什么问题
+
+长会话会失忆，跨会话更会。本插件维护一份**结构化的 topic 记忆**：每个 Topic 记录一件事的**名字、依赖、未决问题、目前结论、影响、建议**。结论变了就改文件、打 commit——`git log` 直接回答「这个结论什么时候、被谁、为什么改的」。
+
+## 核心特性
+
+- **OKF v0.2 严格合规**：每个 Topic 是 `markdown + YAML frontmatter` 的 concept 文档（`type: Topic`），可被 Obsidian、OKF 校验器等整个生态直接消费；自带 provenance（`sources`）、trust（`generated`/`verified`）、lifecycle（`status`/`stale_after`）三族字段。
+- **git 可追溯**：一次结论变更 = 一个 commit（写穿）；`topic_history` 工具和 `/topics history` 把变更史工具化。
+- **local-first**：默认 local-only 模式（`~/.dsh/topics/`），零配置零凭据；配置 `repo` 后启用 GitHub 同步（单库单 Bundle 单 main，写穿 + 去抖推送，rebase 冲突标记降权等人解，不做自动智能合并）。
+- **免 LLM 热路径注入**：每轮输入做词法匹配（CJK bigram + 词 + tag 加权 + `depends` 图游走），毫秒级；无命中零注入；per-topic 摘要 ≤300 token、top-K ≤4、总预算 ≤1.5k token，全部可配。
+- **注入可观测可调参**：每轮落 Injection Log（命中、得分、near-miss、预算占用），`/topics stats` 给出 hit rate、top-N、near-miss 分布和阈值调参建议——调参看证据，不拍脑袋。
+- **知识连接成图**：`depends`（机器可读的有向依赖边）+ 正文 `[[wikilink]]` 与 markdown 链接（人写边）共同构成图；检索命中后沿图双向游走（每层衰减一半、深度可配），一次命中带入一个知识子图；每次写入自动重建 `meta/backlinks.json` 反向引用索引，`/topics show` 直接列出「谁引用了我、怎么引用的」——改一条结论前先看牵连面。
+- **两段式观察（M2）**：主模型用 `topic_observe` 随手记原子观察，后台蒸馏 lane（session end + 每 N 轮，模型可配）把观察批量蒸馏成正式 Topic；主模型认为值得记时直接 `topic_save`。
+
+## 工具与命令
+
+| 模型工具 | 用途 |
+|---|---|
+| `topic_save` | 沉淀/修订一个 Topic（名字/依赖/未决问题/结论/影响/建议） |
+| `topic_observe` | 随手记一条原子观察（decision/finding/constraint/question），等蒸馏 |
+| `topic_search` | 免 LLM 关键词检索记忆 |
+| `topic_history` | 某 Topic 的结论变更史（git log 工具化） |
+
+| 命令 | 用途 |
+|---|---|
+| `/topics onboard` | 交互式配置向导：唤起 dsh 原生 ask-user 面板逐项问答（模式 / 仓库 / 蒸馏 / 注入档位 / 自动观察），末步确认才写入；无 ask-user UI 的环境自动退化为逐条输入 |
+| `/topics status` | bundle 健康：topic 数、观察积压、冲突、最近蒸馏结果、同步状态 |
+| `/topics distill` | 手动触发一次蒸馏 run（复用现有 lane 与 in-flight 守卫；输出摘要与 distill-state 字段一一对应） |
+| `/topics stats` | 注入统计：hit rate、top-N、near-miss 分布与调参建议 |
+| `/topics list` / `show` / `history` | 浏览 Topic、反向引用与变更史 |
+| `/topics graph` | 生成关系图网页（力导向、可拖拽缩放、悬停看结论）并自动在浏览器打开 |
+| `/topics sync [pull\|push]` | GitHub 模式手动同步 |
+| `/topics config` / `set <key> <value>` | 查看与修改配置（阈值、预算、蒸馏模型等） |
+
+## 安装
+
+```bash
+dsh plugin --profile <你的profile> add @aiwayds/dsh-topics-memory
+```
+
+Bundle 默认在 `~/.dsh/topics/`（`$DSH_TOPICS_HOME` 可覆盖）。装好后的第一件事：跑 `/topics onboard`——直接弹出 dsh 原生 ask-user 交互面板逐项问答（TUI 面板 / 浏览器会话 / 飞书卡自动适配，feishu 侧装了 dsh-ask-router 还能双端竞答）。GitHub 同步：`/topics set repo <owner/name>`（建议仓库名 `dsh-topics-data`，与插件源码仓区分开），凭据走 `$GITHUB_TOKEN` 或已登录的 gh CLI（登录不是本插件职责）。
+
+### 从 0.5.x 升级（更名）
+
+0.6.0 起插件更名：`@aiwayds/dsh-llmwiki-memory` → `@aiwayds/dsh-topics-memory`，命令族 `/wiki` → `/topics`，settings namespace `llmwiki` → `topics`。安装新包（并把旧包从 profile 移除）即可——首次启动时插件自动完成迁移：数据目录 `~/.dsh/llmwiki` 改名为 `~/.dsh/topics`，旧 `llmwiki` namespace 里用户调过的配置值一次性拷入 `topics`。无需手动操作；迁移某步失败时插件回落旧路径继续工作。
+
+## 快速上手
+
+1. 安装（上方命令），重启 dsh；
+2. 跑 `/topics onboard`，在 ask-user 面板里走完 模式 / 仓库 / 蒸馏模型 / 注入档位 / 自动观察 五个决定——末步确认才写入；
+3. 正常干活：相关结论每轮自动注入；说「记住…」让模型 `topic_save`；`/topics status` 看健康，`/topics stats` 看注入命中。
+
+## 配置
+
+首次配置交给 `/topics onboard`；日常微调用 `/topics set <key> <value>`（写 `settings.yaml` 的 `topics` namespace，下次会话启动生效）。全部键与默认值：
+
+| 键 | 默认 | 说明 |
+|---|---|---|
+| `repo` | 空（local-only） | GitHub 同步仓 `owner/name`；建议 `dsh-topics-data`；置空回 local-only |
+| `autoInject` | `true` | 每轮注入总开关 |
+| `injectDedup` | `true` | 会话级注入去重：本会话已实际注入过的 Topic 不重注（会话结束清空注册表；被预算丢弃的仍可注入；被去重占用的 topK 名额不回填）——见 ADR 0012 |
+| `topK` | `4` | 每轮最多注入的 Topic 数 |
+| `perTopicBudget` | `300` | 单 Topic 摘要 token 预算 |
+| `totalBudget` | `1500` | 每轮注入总预算 |
+| `matchThreshold` | `0.3` | 命中阈值；按 `/topics stats` 的 near-miss 证据调 |
+| `tagBoost` | `0.15` | tag 命中加成 |
+| `graphDepth` | `2` | `depends` 图双向游走深度（0 关闭） |
+| `recencyWindowDays` | `7` | 近因加分窗口（+0.2） |
+| `autoObserve` | `true` | 每轮自动抓原子观察 |
+| `includeSubagents` | `true` | 注入与观察是否作用于子代理会话（ADR 0011）；`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 轮触发一次蒸馏 |
+| `distillOnSessionEnd` | `true` | session 结束时蒸馏一次 |
+| `distillBatchSize` | `40` | 每次蒸馏模型调用携带的观察条数。遇输出上限（`max-tokens`）失败自动减半重试（下限 5），失败批次不再活锁积压；缩小状态跨 run 保持，直到插件重载或配置变更。注意：`/topics set distillBatchSize` 重设为同值不触发复位，需设为不同值或重载插件 |
+| `distillMaxModelCalls` | `8` | 单次蒸馏 run 的模型调用预算，含 ops 未回显有效 `observed_ids` 时的纠错重试（至多一次，预算放不下即零消费停机）。预算耗尽即停，已成功的批次照常 markDistilled（部分前进优于零前进），distill state 记 `partial: …` |
+| `pushDebounceSeconds` | `45` | GitHub 模式去抖推送间隔 |
+
+## Acknowledgements
+
+本项目的形态直接受以下项目的启发与支撑：
+
+- **[zosmaai/pi-llm-wiki](https://github.com/zosmaai/pi-llm-wiki)** — pi 上的原生 OKF v0.2 知识库扩展，本项目的直接灵感来源。其两段式观察（便宜的原子观察 + 后台蒸馏）、缓存安全注入（易变内容不进 system prompt）、分层 vault 与 ownership 模型都被本设计吸收。
+- **[GoogleCloudPlatform/open-knowledge-format](https://github.com/GoogleCloudPlatform/open-knowledge-format)** — Open Knowledge Format (OKF) v0.2 规范，本项目 Bundle 格式严格遵循的标准。
+- **[Karpathy 的 LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)** — 整个 LLM 维护个人知识库方法论 的起点。
+- **[fan56/pi-topic-memory](https://github.com/fan56/pi-topic-memory)** — 同作者的前作：pi 上的工作 topic 台账与静默注入扩展，其热路径免 LLM 匹配与注入时序经验是本项目的直接技术前身。
+- **[chancelu/dsh-llmwiki](https://github.com/chancelu/dsh-llmwiki)** — dsh 生态的同类先例，本项目的同轮注入 seam（`agent/inbox/spliced` + `systemPrompt.context()`）沿用了它在真实 dsh 上验证过的机制。
+
+## 已知边界
+
+- **子代理默认参与记忆，可整体关掉**：默认（`include-subagents` 开）注入与观察同样作用于子代理会话。`/topics set include-subagents off` 后，delegation depth > 0 的子代理会话被整体跳过——不注入、不观察、不触发蒸馏；topic 工具始终在全局层（子代理显式 `topic_save` 不受开关影响）。跨进程子代理（claude-code/codex 等 provider）本就不加载本插件。
+- **headless 单发会话里的 session-end 蒸馏**：插件 disposer 现在会等待退出触发的末次蒸馏落盘（有界等待，上限 90s；挂死的模型调用在超时后放弃、退出照常进行），headless 进程默认不再输掉这场竞速。90s 窗口内退出 run 可能只完成部分调用预算，剩余积压留待下次触发。已有 session-end run 在跑时退出触发整体跳过（否则同一全局队头批次会被双份喂给模型）。会话内 `/topics distill` 手动触发则完全绕开竞速；`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 修改在下次会话启动后生效最稳。
+- **蒸馏选模型**：`/topics onboard` 的蒸馏一步拆成两问（先 provider 后 model，模型列表取自该 provider 的目录），选完经 `resolveModelInfo` 预校验——provider 无活路由会阻断重选，模型目录校验非 NO_ADAPTER 失败（目录外，可能仍可用）则警告但放行；无 ask UI 或无可用模型路由的环境自动退回文本输入。`/topics set` 的选择面板走同一套校验。
+
+## 设计文档
+
+- [CONTEXT.md](CONTEXT.md) — 领域术语表
+- [docs/adr/](docs/adr/) — 0001–0013：OKF 合规、Remote 形态、同步策略、两段式 Observer、Bundle 布局、注入默认值、可观测与调参、双模式持久化、配置向导、子代理隔离、include-subagents 开关、注入去重默认开、更名与迁移
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# dsh-topics-memory bundle patch: mounts the plugin into the profile's
+# assembly tree under the stable plugin id `dsh-topics-memory`. It registers
+# the `topics` settings namespace, the topic tools, the /topics slash command,
+# and the session-event observer (injection + two-stage observation).
+
+- insert:
+    - id: dsh-topics-memory
+      name: '@aiwayds/dsh-topics-memory'

package/lib/commands.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `/topics` slash command family — status | stats | list | show | history |
+ * sync | config | set. Registered through the shared dsh-commands registry
+ * as an optional peer (vault pattern): hosts without it still load the plugin.
+ *
+ * @module commands
+ */
+import type { CommandDefinition, CommandInvocation } from '@deepseek-ai/dsh-commands';
+import type { TopicsService } from './service.ts';
+import type { DistillResult } from './distill.ts';
+import { aggregateStats } from './ilog.ts';
+import { type AskServiceResolver, type LlmDirectoryResolver, type MutateFn } from './onboard.ts';
+/**
+ * Manual `/topics distill` trigger, wired by the host (index.ts owns the lane
+ * instance). Returns the lane's own result shape; rejections surface through
+ * the command's normal error path.
+ */
+export type ManualDistill = (invocation: CommandInvocation) => Promise<DistillResult>;
+export declare const HELP: string;
+export declare function buildTopicsCommand(service: TopicsService, mutate: MutateFn, resolveAsk?: AskServiceResolver, resolveLlm?: LlmDirectoryResolver, distillNow?: ManualDistill): CommandDefinition;
+export declare function tuningHint(stats: ReturnType<typeof aggregateStats>, threshold: number): string | undefined;

package/lib/commands.js

@@ -0,0 +1,368 @@
+/**
+ * `/topics` slash command family — status | stats | list | show | history |
+ * sync | config | set. Registered through the shared dsh-commands registry
+ * as an optional peer (vault pattern): hosts without it still load the plugin.
+ *
+ * @module commands
+ */
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { serializeTopicDoc, slugify, firstParagraph } from "./okf.js";
+import { buildGraph, renderGraphHtml } from "./viz.js";
+import { CONFIG_KEYS, displayKey, parseConfigValue } from "./config.js";
+import { aggregateStats } from "./ilog.js";
+import { askDistillSingle, createOnboardHandler, llmDirectoryNotice, makePanel, parseDistillInput, pickLlmDirectory, } from "./onboard.js";
+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 stats               注入统计：hit rate、top-N、near-miss 分布与调参建议',
+    '  /topics list                列出全部 Topic',
+    '  /topics show <slug>         查看一个 Topic 全文（含反向引用）',
+    '  /topics history <slug>      一个 Topic 的结论变更史（git log）',
+    '  /topics graph               生成关系图网页并在浏览器打开',
+    '  /topics sync [pull|push]    GitHub 模式：手动拉取/推送（默认模式自动）',
+    '  /topics config              查看当前配置',
+    '  /topics set <key> <value>   修改配置；key: ' + CONFIG_KEYS.join(' | '),
+    '  （distill-provider / distill-model 不带 value 且有 ask UI + 可用模型路由时弹选择面板；distill-model 支持 "provider model" 混写自动拆分）',
+    '',
+    '凭据：$GITHUB_TOKEN 或已登录的 gh CLI；登录不在本插件职责内。',
+].join('\n');
+export function buildTopicsCommand(service, mutate, resolveAsk = () => undefined, resolveLlm = () => [], distillNow) {
+    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),
+    };
+}
+async function handle(invocation, service, mutate, onboard, resolveAsk, resolveLlm, distillNow) {
+    const raw = invocation.rawInput.trim();
+    const [action = '', ...rest] = raw.split(/\s+/);
+    try {
+        switch (action) {
+            case '':
+                return ok(HELP);
+            case 'onboard':
+                return await onboard(rest, invocation);
+            case 'status':
+                return ok(await renderStatus(service));
+            case 'distill':
+                return await doDistill(service, invocation, distillNow);
+            case 'stats':
+                return ok(await renderStats(service));
+            case 'list':
+                return ok(await renderList(service));
+            case 'show':
+                return await renderShow(service, rest[0]);
+            case 'history':
+                return await renderHistory(service, rest[0]);
+            case 'graph':
+                return await doGraph(service);
+            case 'sync':
+                return await doSync(service, rest[0]);
+            case 'config':
+                return ok(renderConfig(service.cfg));
+            case 'set':
+                return await doSet(service, rest, mutate, resolveAsk, resolveLlm, invocation);
+            default:
+                return fail(`未知子动作 “${action}”。\n\n${HELP}`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return fail(`topics ${action} 失败：${message}`);
+    }
+}
+function ok(text) {
+    return { kind: 'success', text };
+}
+function fail(text) {
+    return { kind: 'error', 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 ? `开（topK ${cfg.topK}，预算 ${cfg.totalBudget} tok，阈值 ${cfg.matchThreshold}）` : '关'}`,
+        `  去重：${cfg.injectDedup ? '开（同会话已注入的 Topic 不重注）' : '关'}`,
+        `  蒸馏：${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.
+    const lastRun = await service.store.readDistillState();
+    if (lastRun !== undefined) {
+        const outcome = lastRun.ok === true
+            ? `标记 ${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', ' ')}`);
+    }
+    if (service.sync !== undefined) {
+        lines.push(`  上次推送：${service.sync.lastPushAt ?? '从未'}`);
+        if (service.sync.lastError !== '')
+            lines.push(`  同步错误：${service.sync.lastError.split('\n').at(-1)}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * `/topics distill` — one manual distill run over the current observation pool.
+ * The empty-pool case answers immediately without touching the lane; the
+ * summary mirrors the distill state fields (ok / marked / created / updated /
+ * gc dropped / reason) so what the user sees is what the state file records.
+ */
+async function doDistill(service, invocation, distillNow) {
+    if (distillNow === undefined)
+        return fail('蒸馏 lane 未接线（宿主未提供手动蒸馏触发器）');
+    const pending = await service.store.undistilledObservations(1);
+    if (pending.length === 0)
+        return ok('观察池为空（no-observations）：没有未蒸馏的观察，无需触发。');
+    const result = await distillNow(invocation);
+    if (!result.ok) {
+        const reasonNote = result.reason === 'no-observations'
+            ? '观察池为空（no-observations）'
+            : 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 parts = [`标记 ${result.marked} 条观察`, `新建 ${result.created.length} 个 Topic`, `更新 ${result.updated.length} 个 Topic`];
+    if (result.gcDropped !== undefined && result.gcDropped > 0)
+        parts.push(`GC 回收 ${result.gcDropped} 条不可处理观察`);
+    return ok(`✅ 蒸馏完成：${parts.join('；')}${result.detail !== undefined ? `\n   ${result.detail}` : ''}`);
+}
+async function renderStats(service) {
+    const records = await service.store.readInjectionRecords();
+    const stats = aggregateStats(records);
+    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`,
+    ];
+    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}`);
+    }
+    if (stats.nearMissHistogram.length > 0) {
+        lines.push('  Near-miss 分布（低于阈值被挡）：');
+        for (const b of stats.nearMissHistogram)
+            lines.push(`    ${b.bucket}: ${b.count}`);
+        const hint = tuningHint(stats, service.cfg.matchThreshold);
+        if (hint !== undefined)
+            lines.push(`  💡 ${hint}`);
+    }
+    return lines.join('\n');
+}
+export function tuningHint(stats, threshold) {
+    // A dense band just below the threshold with zero overflow above it means
+    // the threshold, not the corpus, is the bottleneck.
+    const justBelow = stats.nearMissHistogram.filter((b) => Number(b.bucket.split('–')[0]) >= threshold - 0.15 && Number(b.bucket.split('–')[0]) < threshold);
+    const justBelowCount = justBelow.reduce((acc, b) => acc + b.count, 0);
+    if (stats.rounds >= 20 && justBelowCount >= stats.rounds * 0.3 && stats.hitRate < 0.5) {
+        return `near-miss 集中在阈值 ${threshold} 下方（${justBelowCount} 次），可尝试 /topics set match-threshold ${(Math.max(0.05, threshold - 0.1)).toFixed(2)}`;
+    }
+    return undefined;
+}
+async function renderList(service) {
+    const metas = await service.store.listTopics();
+    if (metas.length === 0)
+        return 'Bundle 里还没有 Topic —— 在会话里让我记点什么，或 /topics set 配置好蒸馏。';
+    const lines = [`共 ${metas.length} 个 Topic：`];
+    for (const m of metas.sort((a, b) => a.slug.localeCompare(b.slug))) {
+        lines.push(`  ${m.slug}  [${m.status}] ${m.title}${m.tags.length > 0 ? `  #${m.tags.join(' #')}` : ''}`);
+    }
+    return lines.join('\n');
+}
+async function renderShow(service, slug) {
+    if (slug === undefined || slug === '')
+        return fail('用法：/topics show <slug>');
+    const doc = await service.store.readTopic(slug);
+    if (doc === undefined)
+        return fail(`Topic “${slug}” 不存在（/topics list 查看）`);
+    const text = serializeTopicDoc(doc);
+    const backlinks = await service.store.readBacklinks();
+    const refs = backlinks[slugify(slug)] ?? [];
+    if (refs.length === 0)
+        return ok(text);
+    const VIA_LABEL = { depends: '依赖', link: '链接' };
+    const lines = [
+        text,
+        '---',
+        `反向引用（${refs.length} 条）——改动本条结论时这些 Topic 可能需要跟进：`,
+        ...refs.map((r) => `- ${r.slug}（${VIA_LABEL[r.via]}）`),
+    ];
+    return ok(lines.join('\n'));
+}
+async function renderHistory(service, slug) {
+    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} 条）：`];
+    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}`);
+    }
+    return ok(lines.join('\n'));
+}
+/**
+ * /topics graph — render the bundle's relationship graph into a self-contained
+ * HTML page and open it in the default browser. Set DSH_TOPICS_NO_OPEN=1 to
+ * skip the browser launch (tests, headless use).
+ */
+async function doGraph(service) {
+    const roster = await service.roster();
+    if (roster.length === 0)
+        return fail('Bundle 里还没有 Topic，无从画起（先记点什么）');
+    const graph = buildGraph(roster);
+    const conclusions = {};
+    for (const topic of roster) {
+        conclusions[topic.slug] = firstParagraph(topic.conclusion);
+    }
+    const html = renderGraphHtml(graph, { conclusions });
+    const file = join(service.store.root, 'meta', 'graph.html');
+    await writeFile(file, html, 'utf8');
+    const opened = openInBrowser(file);
+    const summary = `✅ 关系图已生成：${file}（${graph.nodes.length} 节点 / ${graph.edges.length} 边）` +
+        (opened ? '——已在浏览器打开' : '（浏览器未自动打开，手动用浏览器打开该文件即可）');
+    return ok(summary);
+}
+function openInBrowser(file) {
+    if (process.env.DSH_TOPICS_NO_OPEN === '1')
+        return false;
+    try {
+        const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+        const args = process.platform === 'win32' ? ['/c', 'start', '', file] : [file];
+        const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
+        child.unref?.();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function doSync(service, direction) {
+    if (!service.githubMode)
+        return fail('当前是 local-only 模式（/topics set repo <owner/name> 启用 GitHub 同步）');
+    if (service.sync === undefined)
+        return fail('同步层未就绪');
+    if (direction === undefined || direction === 'push') {
+        await service.sync.commitMeta();
+        const r = await service.sync.flush();
+        return r.ok ? ok(`✅ ${r.message}`) : fail(r.message);
+    }
+    if (direction === 'pull') {
+        const r = await service.sync.pull();
+        service.invalidate();
+        return r.ok ? ok(`✅ ${r.message}`) : fail(r.message);
+    }
+    return fail('用法：/topics sync [pull|push]');
+}
+function renderConfig(cfg) {
+    const lines = ['当前配置：'];
+    for (const key of CONFIG_KEYS) {
+        lines.push(`  ${displayKey(key)} = ${String(cfg[key])}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * One ask-user panel for `/topics set distill-provider|distill-model` without a
+ * value. Picks are pre-validated like the onboard wizard (live-route check
+ * for providers; resolveModelInfo for models — NO_ADAPTER blocks, off-catalog
+ * warns but allows). Cancellation and blank answers write nothing;
+ * ASK_CANCELLED / ASK_ABORTED surface as a clean no-write success.
+ */
+async function setDistillInteractive(service, key, ask, llm, mutate, invocation) {
+    const fail = (text) => ({ kind: 'error', text });
+    if (key === 'distillModel' && service.cfg.distillProvider === '') {
+        return fail('请先配置 distill-provider 再选模型：/topics set distill-provider（有 UI 时会弹 provider 选择面板）');
+    }
+    const invocationLike = invocation;
+    const panel = makePanel(ask, invocationLike.agent, invocationLike.signal);
+    const askKey = key === 'distillProvider' ? 'distill-provider' : 'distill-model';
+    try {
+        const picked = await askDistillSingle(llm, panel, askKey, service.cfg);
+        if (picked === undefined)
+            return ok('未选择，配置保持原样。');
+        await mutate([{ op: 'set', path: [key], value: picked.value }]);
+        return ok(`✅ topics.${displayKey(key)} = ${picked.value}${picked.warning === undefined ? '' : `\n⚠️ ${picked.warning}`}`);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ASK_CANCELLED' || code === 'ASK_ABORTED')
+            return ok('已取消，未写入任何改动。');
+        if (code === 'ASK_MISSING_AGENT')
+            return fail('当前 surface 的 ask-user 需要会话上下文。请改用 /topics set 带值输入。');
+        throw error;
+    }
+}
+async function doSet(service, tokens, mutate, resolveAsk = () => undefined, resolveLlm = () => [], invocation) {
+    const [rawKey = '', ...valueParts] = tokens;
+    const rawValue = valueParts.join(' ').trim();
+    const normalized = rawKey.toLowerCase().replace(/[-_]/g, '');
+    const key = CONFIG_KEYS.find((k) => k.toLowerCase() === normalized);
+    if (key === undefined) {
+        return fail(`未知配置项 “${rawKey}”。可选：${CONFIG_KEYS.map(displayKey).join('、')}`);
+    }
+    // No value → a single-question picker for the two distill route keys when a
+    // live UI AND a usable llm directory exist. Every other shape errors out:
+    // falling through to the typed path would silently CLEAR the key.
+    if ((key === 'distillProvider' || key === 'distillModel') && rawValue === '') {
+        const ask = resolveAsk();
+        const pick = pickLlmDirectory(resolveLlm());
+        if (ask !== undefined && typeof ask.ask === 'function' && pick.kind === 'ok') {
+            return setDistillInteractive(service, key, ask, pick.llm, mutate, invocation);
+        }
+        const reason = llmDirectoryNotice(pick) ?? '当前 surface 没有 ask-user 面板';
+        return fail(`${displayKey(key)} 需要一个值（如 /topics set distill-model zai-coding-cn glm-4.7-air），未写入任何改动。选择面板不可用：${reason}`);
+    }
+    // Mixed "provider model" / "provider/model" values for distill-model split
+    // into BOTH keys — the historical root of `distillModel: "prov model"` dirt.
+    // Splitting overwrites distill-provider; when that key already held a
+    // different provider, say so.
+    if (key === 'distillModel' && rawValue !== '' && /[\s/]/.test(rawValue)) {
+        const parsed = parseDistillInput(rawValue);
+        if ('error' in parsed)
+            return fail(parsed.error);
+        const previousProvider = service.cfg.distillProvider;
+        await mutate([
+            { op: 'set', path: ['distillProvider'], value: parsed.provider },
+            { op: 'set', path: ['distillModel'], value: parsed.model },
+        ]);
+        const overwrote = previousProvider !== '' && previousProvider !== parsed.provider;
+        return ok([
+            `✅ topics.distill-provider = ${parsed.provider}`,
+            `✅ topics.distill-model = ${parsed.model}`,
+            '（混写值已拆分写入 distill-provider 与 distill-model 两个键）',
+            ...(overwrote ? [`⚠️ 已覆盖原 distill-provider «${previousProvider}»`] : []),
+        ].join('\n'));
+    }
+    if (key === 'distillProvider' && rawValue !== '' && /[\s/]/.test(rawValue)) {
+        return fail('distill-provider 只接受单段 provider id（不含空格或斜杠）。混合值请用 /topics set distill-model "provider model" 一次写入两个键。');
+    }
+    const parsed = parseConfigValue(key, rawValue);
+    if (typeof parsed === 'object' && parsed !== null && 'error' in parsed)
+        return fail(parsed.error);
+    await mutate([{ op: 'set', path: [key], value: parsed }]);
+    if (key === 'repo' || key === 'autoInject')
+        service.invalidate();
+    return ok(`✅ topics.${displayKey(key)} = ${String(parsed)}`);
+}