@heixui/dsh-session-suite 0.0.0-stage → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-session-suite contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,382 @@
-# Temporary Holding Version
+# dsh-session-suite
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**By [heixiua](https://github.com/heixiua)** · [github.com/heixiua/dsh-session-suite](https://github.com/heixiua/dsh-session-suite) · MIT
+· npm: [`@heixui/dsh-session-suite`](https://www.npmjs.com/package/@heixui/dsh-session-suite)
+
+Session checkpoints for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH): rewind a
+conversation *together with the workspace files and the session memory it produced*, delete sessions for good,
+share a conversation as an image or a self-contained page — and keep a **long-term memory** that survives across
+sessions and workspaces.
+
+It is a DSH bundle (Host + Web Client) built against the desktop profile, and it deliberately targets the
+interaction pattern of Trae's session actions.
+
+| Capability | Where it lives |
+|---|---|
+| Rewind to a message (conversation + files + memory) | ↺ button on every final assistant message, inline confirm bar above the composer |
+| Delete one turn (conversation + memory only) | 🗑 button beside ↺ |
+| Delete a chosen run of turns | Session menu → **Delete part of the conversation**, with a turn picker |
+| Delete a session permanently | Session menu → **Delete session** (confirmation dialog) |
+| Share a chosen range | Session menu → **Share**: pick turns, then Image / Web page / Markdown / JSON / copy text |
+| Snapshot management | Session menu → **Session snapshots**, and Settings → **Session snapshots** |
+| Long-term memory (global + per-workspace) | Settings → **Long-term memory**; `【记住：…】`; the `memory` tool |
+| Use WorkBuddy / Trae credits as models | **not this bundle** — see [Using WorkBuddy and Trae credits](docs/credits.md) |
+
+### Long-term memory
+
+Two isolated stores (`global` and per-`workspace`), a four-factor importance score
+(frequency · recency · affect · uniqueness), dynamic decay with a cold archive, similarity clustering with
+summary compression, and rule abstraction from repeated tags.
+
+The part that matters most: **nothing is stored implicitly without your consent.** After each turn a cheap model
+call proposes durable facts, they queue in the settings page, and only *Keep* writes them. Explicit
+`【记住：…】` / `【新增全局记忆：…】` instructions skip the queue and write immediately.
+
+Full detail — scoring formula, thresholds, lifecycle, commands, storage layout — in
+[docs/long-term-memory.md](docs/long-term-memory.md).
+
+
+### What each destructive action touches
+
+| Action | Conversation | Memory | Workspace files |
+|---|---|---|---|
+| Rewind (↺) | cut at the message | trimmed to that point | **restored** to that turn's snapshot |
+| Delete a turn (🗑) | the prompt, the reply, and the steps between them | trimmed to that point | untouched |
+| Delete part of the conversation | cut at the first selected turn (its prompt included) | trimmed to that point | untouched |
+| Delete session | removed from disk | removed | untouched (the folder stays) |
+
+Only a rewind puts files back; every other delete leaves the working tree exactly as it is. A session log is
+append-only, so "cut" always means "keep the prefix and retire the original" — the turns after a removed range go
+with it.
+
+### Sharing
+
+The share dialog lists every turn with its prompt and a preview of the answer. Everything is selected by default;
+untick what should stay out. Then choose an output:
+
+* **Image** — a PNG of the selected turns, drawn on a canvas (no other library involved);
+* **Web page** — one self-contained HTML file with inline CSS, light/dark aware, printable to PDF;
+* **Markdown** / **JSON** — for pasting into an issue or feeding another tool;
+* **Copy text** — the plain transcript on the clipboard.
+
+Both rich formats render the model's Markdown instead of echoing it: headings, bold/italic, inline code, fenced
+code blocks, ordered and bulleted lists, block quotes, pipe tables, and links. The Host parses the log once into
+blocks with inline runs (`lib/markdown.js`), the HTML renderer emits markup from those blocks, and the browser draws
+the very same blocks on a canvas — so the page and the image never disagree.
+
+Screenshots travel with the export. Attachments live outside the session log, so the Host resolves them
+(`attachments.imageHostPath`) and inlines them as data URLs under a bounded budget, which keeps the page a single
+portable file. In the image they are drawn at full card width (height-capped, aspect preserved); in the HTML page
+each screenshot is a button that opens a built-in viewer at native resolution — the page carries a small inline
+script and no external request.
+
+A raster image cannot contain clickable images: if opening a screenshot at full size matters, share the HTML file
+rather than the PNG. Nothing in the export depends on a network request either way.
+
+### What an export contains
+
+A session log is mostly plumbing: runtime context, the skill catalog, time samples, subagent relays, tool calls,
+and the narration a model writes between tools. None of that is the conversation:
+
+* only `source.kind === "user"` messages count as prompts — everything else in a user-role event is dropped;
+* **Final answers only** (the default) keeps your prompt plus the closing reply of each turn;
+* untick it to export every assistant step, including the narration around tool calls;
+* tool results never appear in the rich exports, and Markdown/JSON follow the same curation.
+
+Consecutive assistant steps of one turn merge into a single card, and steps with no prose are dropped rather than
+exported as empty `Assistant` labels.
+
+A public share link would need a server holding the conversation; the web page file is the portable equivalent, so
+that is what this bundle produces instead of minting URLs that would only work on this machine.
+
+## Install
+
+From npm:
+
+```bash
+dsh plugin --profile desktop install @heixui/dsh-session-suite
+```
+
+> The published package is scoped because the unscoped name `dsh-session-suite`
+> belongs to a different project on npm (`chc-1986/dsh-session-suite`), not to
+> this one. The scope is only the npm package identity — the plugin id, the
+> storage directory, and the bundle name remain `dsh-session-suite`, so data from
+> earlier builds is still found.
+
+From a checkout:
+
+```bash
+# from a checkout of this repository
+dsh plugin --profile desktop install .   # or: pnpm add -D . inside the profile
+```
+
+Or let the running Harness install it (this is what `plugin_manager` does):
+
+```js
+// tool call
+plugin_manager({ action: 'install_bundle', target: 'D:/path/to/dsh-session-suite' })
+```
+
+Install once, then reload the page. The bundle registers a single Host row (`session-suite`) whose patch lives in
+`cordis.patch.yml`; the Client half is discovered from `package.json` → `dsh.client`.
+
+## How a rewind works
+
+DSH's session log is append-only and is the only source of truth, so a rewind cannot delete events. The suite
+implements it as an atomic three-part operation:
+
+1. **Protect** — capture a temporary *undo* snapshot of the workspace and the memory ledger (10-minute TTL).
+2. **Conversation** — `sessionController.fork({ sessionId, atSeq })` copies the exact event prefix into a new
+   session (inclusive boundary, same `cwd`, same agent preset).
+3. **Files** — restore the checkpoint recorded for that turn: changed files are rewritten, files the session
+   created afterwards are removed, and files that existed before the session are never touched.
+4. **Memory** — trim memory entries observed after the target sequence.
+5. **Retire** — archive the source session (hidden from the sidebar, log kept) so nothing is destroyed.
+
+`Undo` reverses all of it: files, memory, the archived session, and the forked child.
+
+## Snapshots on disk
+
+```
+%DSH_HOME%/storages/dsh-session-suite/
+  sessions/<sessionId>/index.json        # checkpoint records
+  sessions/<sessionId>/manifests/*.json  # path -> {hash, size, mtime}
+  sessions/<sessionId>/blobs/<ab>/<hash> # gzip-compressed file contents, content-addressed
+  memory/<sessionId>.json                # per-session memory ledger
+  memory/_global.json                    # cross-session long-term memory
+  undo/<id>.json                         # rollback undo bundles
+```
+
+* **Incremental** — a manifest stores only tracked paths and hashes; identical content is stored once, and
+  unchanged files are skipped using the previous manifest's `(size, mtime)` fingerprint.
+* **Budget** — the newest 10 automatic checkpoints per session are kept; locked checkpoints never expire;
+  temporary undo bundles live outside the budget and are swept after 10 minutes.
+* **Ignore list** — `node_modules`, `.git`, caches, build output, logs, lockfiles, and binary files are never
+  recorded; `config.ignore` adds your own patterns.
+* **Limits** — files above 2 MiB and trees above 4000 files are skipped rather than slowing a turn down.
+
+## Configuration
+
+```yaml
+- insert:
+    - id: session-suite
+      name: dsh-session-suite
+      config:
+        keep: 10               # automatic checkpoints kept per session
+        autoCheckpoint: true   # capture one at the start of every turn
+        maxFileBytes: 2097152
+        maxFiles: 4000
+        sweepIntervalMs: 300000
+        ignore: []             # extra ignore patterns
+```
+
+## Layout
+
+```
+index.js            Host half: route registration, per-turn checkpoints, sweep timer
+client.js           Client half: menu rows, message actions, banner, dialog, settings page
+lib/api.js          Authenticated Fetch route (POST api/session-suite)
+lib/service.js      Session operations: rollback, undo, delete, share, delete-message
+lib/checkpoints.js  Content-addressed incremental snapshot store
+lib/memory.js       Session memory ledger with rollback trimming
+lib/share.js        Session log → Markdown / text / JSON projection
+locale/{en,zh}.json Plugin Manager display metadata and strings
+tools/              Self-tests and the pre-clean helper (not part of the bundle)
+docs/               Requirements and API notes
+```
+
+## Tests
+
+The self-tests exercise the engine and the orchestration against throwaway directories; they never touch the
+real DSH home.
+
+```bash
+node tools/selftest.mjs                       # snapshots, ignore rules, restore, pruning
+node tools/selftest-rollback.mjs              # rollback, undo, delete-message, share, permanent delete
+node tools/selftest-memory.mjs                # scoring, decay, clustering, rules
+node tools/selftest-memory-scope.mjs          # model fallback chain, workspace isolation
+node tools/selftest-workspace-registry.mjs    # workspace registry, automatic maintenance
+node tools/selftest-compaction-boundaries.mjs # cut points survive a compaction
+node tools/selftest-resolve-cwd.mjs           # an agent can find its own workspace
+node tools/selftest-maintenance.mjs           # idle libraries skip, rules never duplicate
+node tools/selftest-cluster-idempotence.mjs   # repeated passes never multiply rules or summaries
+node tools/selftest-inherit.mjs               # a forked session keeps its snapshots
+node tools/selftest-retrieval.mjs             # BM25, coverage and RRF primitives
+node tools/selftest-wordlist.mjs              # longest-match CJK segmentation
+node tools/selftest-factkeys.mjs              # fact-key canonicalisation and supersession
+node tools/selftest-factkey-integration.mjs   # fact keys through remember and recall
+node tools/selftest-injection.mjs             # how many memories get injected, and why not
+node tools/selftest-explicit-writes.mjs       # a pipeline message is never obeyed as a user instruction
+node tools/selftest-list-sessions.mjs         # a rewound session is still listed; subagents stay hidden
+node tools/selftest-delete-cascade.mjs        # cascade delete order, and refuse-before-touching
+node tools/check-locale.mjs                   # every t() key exists in both dictionaries
+```
+
+Every one of these has been mutation-checked: a deliberate break of the
+behaviour it names makes it fail. That is the only claim worth making about a
+test — one that passes on broken code is documentation, not a guard.
+
+`tools/ablate-word-route.mjs` answers a narrower question: does the third
+retrieval route earn its place? It runs each probe twice against the *same*
+store, once with the route and once without, so a shifted memory library cannot
+confound the comparison:
+
+```bash
+node tools/ablate-word-route.mjs
+```
+
+The result is that the word route raises MRR on both the held-out and final sets
+(0.491 → 0.561 and 0.612 → 0.683) while leaving recall@5 unchanged — better
+ordering, no lost hits.
+
+Retrieval quality is measured, not asserted. Three probes report the standard
+metrics (recall@k, MRR, nDCG@k) instead of a pass/fail on the top hit:
+
+```bash
+node tools/probe-recall.mjs           # the six queries the rerank was tuned on
+node tools/probe-recall-heldout.mjs   # seven unseen, everyday-worded queries
+node tools/probe-recall-final.mjs     # ten queries written before the hybrid change
+```
+
+The three sets exist because one set cannot tell honest progress from
+overfitting. `probe-recall.mjs` holds the queries the coverage rerank was tuned
+against, so it proves only that the code fits its own training set;
+`probe-recall-heldout.mjs` was written afterwards to expose that rerank's blind
+spots, and `probe-recall-final.mjs` was written *before* the hybrid change and
+never used to design it. All three rose when the hybrid landed, which is the
+evidence that matters:
+
+| query set | MRR before | MRR after | recall@5 before | recall@5 after |
+|---|---|---|---|---|
+| tuned (6) | 0.833 | **0.917** | — | — |
+| held-out (7) | 0.339 | **0.600** | 0.714 | **0.857** |
+| final (10) | 0.466 | **0.733** | 0.800 | **1.000** |
+
+Ranking runs three lexical routes with different blind spots and fuses them by
+rank, following the hybrid-retrieval design in chapter 3 of 《深入理解 AI Agent》:
+
+| route | vocabulary | scored by | blind spot it covers |
+|---|---|---|---|
+| precise | character bigrams + ASCII words | BM25 | — |
+| loose | single characters + ASCII words | IDF-weighted coverage | partial word overlap |
+| word | words from a general Chinese dictionary | BM25 | over-matching across word boundaries |
+
+The third route exists because character bigrams cannot tell 「车」 inside
+「车站」 from 「车」 standing alone, so they match across word boundaries; a word
+list fixes exactly that. It is weaker on anything outside the list — personal
+names, code identifiers, new coinages — which is why it joins the fusion rather
+than replacing a route. A third opinion only helps when it is wrong in different
+places, and `tools/ablate-word-route.mjs` is what checks that it is.
+
+The book fuses a dense route with a sparse one; recall runs offline and must stay
+offline, so every route here is lexical.
+
+That limit is worth stating plainly: no route crosses languages, so a query that
+shares no character with a memory — 「checkpoint」 against 「快照」 — still scores
+zero. The hybrid recovers ranking order among memories that are already
+reachable; it cannot invent a match where no character is shared.
+
+## What actually gets injected
+
+`recallLimit` is a ceiling, not a quota. Filling it on every turn is how a weak
+question drags six unrelated memories into the prompt and then asserts they are
+relevant. The injected count steps down with the evidence — the full budget for a
+strong match, fewer for a weaker one, and one entry when the question barely
+matches anything. A question that matches nothing injects nothing.
+
+A small resident layer runs alongside: the two most important memories ride along
+regardless of the question. Without it, an ordinary follow-up like 「继续」 shares
+no vocabulary with anything, a strict relevance filter would inject nothing at
+all, and the feature would look broken rather than selective. Set
+`residentLimit: 0` to turn it off.
+
+Every candidate that is *not* injected is reported with the rule that dropped it
+(`no-match` or `capacity`). A memory system that silently decides not to recall
+something is indistinguishable from one that has forgotten it; naming the reason
+is the difference between a black box and a debuggable feature.
+
+The memory settings page has a **"What would this question recall?"** box that
+shows this live: type a question, see which memories it pulls in, how many the
+evidence justifies, and why each of the rest was left out. The dry run is
+read-only (`touch: false`), so trying queries cannot re-rank your own library.
+
+## Fact keys: the same fact, restated
+
+Lexical similarity cannot see a value change. 「拼团还没开」 and 「拼团开了」 are
+the same fact before and after, but they look unrelated; 「身高一米七」 and
+「长胖到 55 公斤」 look alike but are different facts. Neither comparison can be
+made from the text.
+
+So an entry may carry a `subject.aspect` key — `她.身高`, `约定.见面地点`. Entries
+sharing a key are the same fact, and only the newest is recalled; the older ones
+are marked superseded, stay on disk, and are never deleted. Restating a superseded
+fact revives that record rather than forking a second one.
+
+Two rules keep it safe. A key that is too broad is **refused** rather than
+trusted — a single-segment key like `身高` names a category, not a fact, so the
+entry simply opts out of supersession. And a key must never contain the value:
+`她.身高170` changes whenever the height does, so the two records never meet. An
+absent key is harmless; a wrong key can retire a good memory.
+
+## If your memory library was affected
+
+Between 2026-11-04 and the fix in this version, a self-triggering bug made the
+plugin obey its own instruction text: it scanned every message with
+`role === 'user'` without checking `source.kind`, harness pipeline messages carry
+that role, and this plugin's injected memory block ends with the literal example
+`【记住：…】`. The plugin captured that placeholder and stored it as a memory, 154
+times.
+
+Three guards now prevent it, each with a regression test: only user-authored
+messages are obeyed, placeholder-only captures are refused, and identical text
+reinforces instead of appending. Real memories were never overwritten — the write
+path never rewrites text — so they are recoverable from any pre-poisoning
+snapshot, including the atomic write's leftover `.tmp` file:
+
+```bash
+node tools/repair-memory-store.mjs           # dry run: reports the plan
+node tools/repair-memory-store.mjs --apply   # backs up first, then repairs
+```
+
+The repair backs the current store up under `memory/backups/` before writing
+anything, and it never deletes real content.
+
+`docs/pitfalls.md` collects every trap hit while building this bundle, each written
+as symptom → root cause → fix. Read it before changing the snapshot, compaction,
+memory, or export paths.
+
+## Limits
+
+* Rewinding does not rewrite the durable log; it forks at the target message and archives the old session. That
+  is the only shape the append-only log supports, and it is what makes undo possible at all.
+* **Edit-and-resend appends, it does not replace.** The edited question is sent as a new turn in the same
+  session; the original question and its reply stay in the history above. This is a property of the append-only
+  log, not a shortcut: a plugin cannot erase events that were already written. Products like Doubao or ChatGPT can
+  replace a message in place because they own a mutable message table. If you need the old exchange to actually
+  disappear, use rewind (which forks) instead — it has that behaviour, at the cost of a new session.
+* **Tags are normalised, not taken verbatim.** Spellings of the same domain fold together (`DSH` → `dsh`,
+  `踩坑` → `错误教训`), and words that name this plugin's own UI (`快照`, `删除`) are dropped rather than stored,
+  because a tag nobody can filter by is worse than no tag. New domains are still accepted.
+* Snapshots cover files, not external side effects: database state, running processes, and network calls are out
+  of scope.
+* Cross-session memory is this bundle's ledger (`memory/`), not a Host feature; it is exposed through the settings
+  page and participates in rollback because the bundle owns it.
+* The HTTP route is protected by DSH Connection (Host/Origin checks plus the browser session), so it is reachable
+  only from the authenticated Web GUI.
+* Retrieval is lexical. Neither route crosses languages, so a query sharing no character with a memory
+  (`checkpoint` against `快照`) scores zero; the hybrid improves ordering among reachable memories, it cannot
+  invent a match.
+
+## Author
+
+Built by **heixiua** — <https://github.com/heixiua/dsh-session-suite>.
+
+Every source file, the git history, and the published npm tarball carry this
+identity. If you found this plugin through a fork or a repackaged bundle, the
+upstream repository above is the original.
+
+## License
+
+MIT. The bundle ships one third-party data file — a Chinese word list derived
+from [jieba](https://github.com/fxsjy/jieba) (MIT) — whose provenance, changes,
+and full licence text are recorded in [THIRD-PARTY.md](THIRD-PARTY.md).

package/README.zh.md

@@ -0,0 +1,178 @@
+# dsh-session-suite（会话套件）
+
+为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）提供会话检查点能力：把对话
+**连同工作区文件和会话记忆一起**回滚到任意一条消息，永久删除会话，把会话导出成图片或单文件网页，
+并且维护一套**跨会话、跨工作区的长期记忆**。
+
+这是一个 DSH 插件包（Host + Web Client），对标 Trae 的会话操作体验，已在 desktop profile 上验证加载。
+
+| 能力 | 位置 |
+|---|---|
+| 回滚到某条消息（对话 + 文件 + 记忆） | 每条最终助手消息的 ↺ 按钮，输入框上方的行内确认条 |
+| 删除某一轮（只动对话与记忆） | ↺ 旁边的 🗑 按钮 |
+| 删除选中的一段对话 | 会话 `…` 菜单 → **删除对话片段**（可选轮次） |
+| 永久删除会话 | 会话 `…` 菜单 → **删除任务**（二次确认弹窗） |
+| 分享选中的片段 | 会话 `…` 菜单 → **分享会话**：勾选轮次后生成图片 / 网页 / Markdown / JSON / 复制文本 |
+| 快照管理 | 会话 `…` 菜单 → **会话快照**，以及 设置 → **会话快照** |
+| 长期记忆（全局 + 工作区双库） | 设置 → **长期记忆**；`【记住：…】`；`memory` 工具 |
+| 用 WorkBuddy / Trae 积分跑模型 | **不在本包内** —— 见 [用 WorkBuddy 和 Trae 的积分](docs/credits.zh.md) |
+
+### 长期记忆
+
+两个隔离的库（`global` 与按工作区划分的 `workspace`）、四因子重要性评分（频率 · 新近度 · 情感强度 · 独特性）、
+动态衰减加冷归档、相似聚类并压缩成摘要、以及从重复标签里提炼规则型记忆。
+
+最关键的一点：**隐式记忆不会偷偷入库**。每轮结束后由一次轻量模型调用提出候选，进入设置页的待确认队列，
+只有你点「保留」才真正写入；而 `【记住：…】` / `【新增全局记忆：…】` 这类显式指令会跳过队列直接写入。
+
+评分公式、阈值、生命周期、指令、存储结构都在 [docs/long-term-memory.md](docs/long-term-memory.md)。
+
+
+### 各操作分别动到什么
+
+| 操作 | 对话 | 会话记忆 | 工作区文件 |
+|---|---|---|---|
+| 回滚（↺） | 截断到该消息 | 裁剪到该处 | **恢复到该轮快照** |
+| 删除一轮（🗑） | 提问 + 回答 + 中间的步骤一起移除 | 裁剪到该处 | 不动 |
+| 删除对话片段 | 从选中的第一轮（含它的提问）截断 | 裁剪到该处 | 不动 |
+| 删除任务 | 从磁盘移除 | 移除 | 不动（文件夹保留） |
+
+只有回滚会把文件写回去，其它删除都不碰工作区。会话日志是只追加的，所以「截断」只能是「保留前缀 + 原来的会话退休」——选中范围之后的内容会一起消失。
+
+### 分享
+
+分享弹窗会列出每一轮对话（你的提问 + 回答预览），默认全选，取消勾选即可排除。然后选输出形式：
+
+* **图片**：把选中轮次画成一张 PNG（用 canvas 直接画，不依赖任何第三方库）；
+* **网页文件**：单文件 HTML，内联样式、跟随明暗主题、可直接打印成 PDF；
+* **Markdown** / **JSON**：贴进 issue 或喂给别的工具；
+* **复制文本**：纯文本进剪贴板。
+
+两种富格式都会真正**渲染 Markdown**，而不是原样吐出：标题、粗体/斜体、行内代码、代码块、有序/无序列表、引用、管道表格、链接。Host 侧把日志解析成带内联样式的 block（`lib/markdown.js`），HTML 渲染器和 canvas 渲染器吃的是同一份结构，所以网页和图片不会出现两种排版。
+
+截图会跟着一起导出：附件不在会话日志里，Host 通过 `attachments.imageHostPath` 取到原文件，按预算内联成 data URL，网页因此仍是单文件。图片里截图按整卡宽度绘制（限高、保持比例）；网页里每张截图是一个按钮，点开用内置查看器按原始分辨率看——页面只带一小段内联脚本，不发任何外部请求。
+
+另外要说清楚：**位图（PNG/JPG）里的图片不可能点开**。需要「点开看原图」就分享网页文件，而不是导出的 PNG。
+
+### 导出到底包含什么
+
+会话日志里大部分不是对话：运行环境、技能目录、时间采样、子代理回执、工具调用，以及模型在工具之间写的过渡性说明。这些都不该进导出：
+
+* 只有 `source.kind === "user"` 的消息才算「你说了什么」，user 角色下的其它事件全部丢弃；
+* 默认勾选 **只导出最终回答**：每轮保留你的提问 + 最后那条答复；
+* 取消勾选则导出每个助手片段，包括工具调用之间的过程说明；
+* 富格式里永远不出现工具输出，Markdown / JSON 也走同一套取舍。
+
+同一轮里的多个助手片段会合并成一张卡片，只有工具调用、没有正文的步骤直接丢弃，不会导出成一堆空标签。
+
+真正的「在线链接」需要一台服务器托管内容；这个包用可离线打开的网页文件来替代，而不是生成一个只有本机能打开的链接。
+
+## 安装
+
+从 npm 安装：
+
+```bash
+dsh plugin --profile desktop install @heixui/dsh-session-suite
+```
+
+> 发布用的是带作用域的包名，因为不带作用域的 `dsh-session-suite` 在 npm 上属于另一个项目
+> （`chc-1986/dsh-session-suite`），不是这个。作用域只是 npm 上的包身份——插件 id、存储目录、
+> bundle 名仍然是 `dsh-session-suite`，所以旧版本留下的数据照样能找到。
+
+从本仓库检出目录安装：
+
+```bash
+# 从本仓库检出目录安装
+dsh plugin --profile desktop install .
+```
+
+或者让运行中的 Harness 安装（`plugin_manager` 就是这样做的）：
+
+```js
+plugin_manager({ action: 'install_bundle', target: 'D:/path/to/dsh-session-suite' })
+```
+
+安装后刷新页面即可。整个套件只有一个 Host 行（`session-suite`），配置写在 `cordis.patch.yml`；Client 部分由
+`package.json` 的 `dsh.client` 字段自动发现。
+
+## 回滚是怎么实现的
+
+DSH 的会话日志是**只追加**的，而且是唯一事实来源，所以回滚不能删除事件。套件把它做成一次原子的三段式操作：
+
+1. **保护**：先给工作区和记忆账本拍一个临时 *undo* 快照（10 分钟有效）。
+2. **对话**：`sessionController.fork({ sessionId, atSeq })` 把事件前缀完整分叉成新会话（边界包含该消息、
+   沿用同一个 `cwd` 与 agent preset）。
+3. **文件**：恢复该轮开始时记录的快照——改过的文件写回、轮次里新建的文件删除、会话开始前就存在的文件不动。
+4. **记忆**：裁掉晚于目标序列的记忆条目。
+5. **退休**：把原会话归档（侧边栏隐藏，日志保留），整个过程不销毁任何数据。
+
+「撤销回滚」会把这五项全部还原：文件、记忆、被归档的会话，以及分叉出来的子会话。
+
+## 快照在磁盘上
+
+```
+%DSH_HOME%/storages/dsh-session-suite/
+  sessions/<sessionId>/index.json        # 检查点索引
+  sessions/<sessionId>/manifests/*.json  # 路径 -> {hash, size, mtime}
+  sessions/<sessionId>/blobs/<ab>/<hash> # gzip 压缩的文件内容，按内容寻址
+  memory/<sessionId>.json                # 会话记忆账本
+  memory/_global.json                    # 跨会话长期记忆
+  undo/<id>.json                         # 回滚撤销包
+```
+
+* **增量**：manifest 只记录路径与哈希，相同内容只存一份；未变化的文件靠上一份 manifest 的
+  `(size, mtime)` 指纹直接跳过，不再读取。
+* **配额**：每个会话保留最近 10 个自动检查点；锁定的一律保留；临时撤销包不占配额，10 分钟后清理。
+* **忽略清单**：`node_modules`、`.git`、缓存、构建产物、日志、锁文件、二进制文件都不记录；`config.ignore`
+  可追加自定义规则。
+* **上限**：单文件超过 2 MiB、单次超过 4000 个文件会跳过，避免拖慢对话。
+
+## 配置
+
+```yaml
+- insert:
+    - id: session-suite
+      name: dsh-session-suite
+      config:
+        keep: 10               # 每个会话保留的自动检查点数量
+        autoCheckpoint: true   # 每轮开始时自动拍快照
+        maxFileBytes: 2097152
+        maxFiles: 4000
+        sweepIntervalMs: 300000
+        ignore: []             # 追加的忽略规则
+```
+
+## 目录结构
+
+```
+index.js            Host 半部：注册路由、按轮拍快照、清理定时器
+client.js           Client 半部：菜单行、消息操作、确认条、弹窗、设置页
+lib/api.js          受保护的 Fetch 路由（POST api/session-suite）
+lib/service.js      会话操作：rollback / undo / delete / share / deleteMessage
+lib/checkpoints.js  内容寻址的增量快照存储
+lib/memory.js       会话记忆账本（支持按序列裁剪）
+lib/share.js        会话日志 → Markdown / 文本 / JSON
+locale/{en,zh}.json 插件管理器的展示信息与文案
+tools/              自测脚本与预清理脚本（不随插件打包）
+docs/               需求与 API 笔记
+```
+
+## 测试
+
+两个自测脚本都在临时目录里跑，不会碰真实的 DSH 数据。
+
+```bash
+node tools/selftest.mjs          # 快照 / 忽略规则 / 恢复 / 淘汰 / 记忆
+node tools/selftest-rollback.mjs # 回滚 / 撤销 / 删除消息 / 分享 / 永久删除
+```
+
+## 已知边界
+
+* 回滚不改写日志，而是「分叉到目标消息 + 归档原会话」。这是只追加日志支持的唯一形态，也正是撤销能够成立的原因。
+* 快照覆盖的是文件，不覆盖外部副作用：数据库状态、运行中的进程、网络调用都不在其中。
+* 跨会话记忆是本套件自己的账本（`memory/`），不是 DSH 内核能力；因为由套件拥有，所以能一起回滚。
+* HTTP 路由受 DSH Connection 保护（Host/Origin 校验 + 浏览器会话），只有已鉴权的 Web GUI 能访问。
+
+## 许可证
+
+MIT。

package/THIRD-PARTY.md

@@ -0,0 +1,64 @@
+# Third-party material
+
+`dsh-session-suite` itself is MIT licensed (see [LICENSE](LICENSE)). It bundles
+one third-party data file, listed here with its licence and provenance.
+
+## `lib/data/jieba-dict.txt`
+
+A Chinese word list used for word-boundary segmentation on the retrieval path. It
+is derived from **jieba**'s `extra_dict/dict.txt.small`.
+
+- Upstream: <https://github.com/fxsjy/jieba> (`extra_dict/dict.txt.small`)
+- Licence: MIT — Copyright (c) 2013 Sun Junyi
+- What was changed: the frequency and part-of-speech columns were dropped, so the
+  file holds one word per line; duplicate entries were removed. No words were
+  added, removed, or edited.
+- Size: 109,750 entries, ~920 KB
+- Regenerate with: `node tools/fetch-jieba-dict.mjs` (add `--force` to refetch)
+
+The file is a lookup table loaded once per process. It is never sent to a model
+and adds nothing to prompt size or per-turn token cost.
+
+### jieba's MIT licence
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2013 Sun Junyi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+```
+
+## Design influences, not code
+
+Two third-party DSH plugins were read while designing the long-term memory
+features. **No code was copied from either**, and neither is a dependency.
+
+- [`dsh-fish-memory`](https://github.com/Yuuyuko-uu/dsh-fish-memory) — its licence
+  is a custom, non-OSI "Yuuyuko-uu 插件许可 1.0" that permits use and
+  modification but requires attribution on redistribution, so it is source for
+  ideas only. The resident-memory-layer idea (durable facts get their own small
+  quota instead of competing with question-matched entries) and the practice of
+  telling the user *why* a memory was not recalled both come from reading it.
+  The word-list segmentation approach it demonstrated is what motivated adopting
+  jieba's MIT word list here.
+- [`dsh-context`](https://github.com/bowenliang123/dsh-context) — Apache-2.0.
+  Read to confirm the two plugins do not collide on any slot, tool, or route.
+
+Coinage of the word list, the retrieval fusion, and every line of this bundle
+are original to this project.