dsh-plugin-mindmap

Readme

# dsh-plugin-mindmap

**MindMap** — a [DeepSeek Harness](https://github.com/deepseek-ai/DeepSeek-Harness) plugin that distills a conversation into persistent **storylines** and renders them as an interactive map.

[中文文档](./README.zh-CN.md) | English

![MindMap screenshot](mindmap.png)

## Highlights

1. **Auto-organizes conversation logic and identifies key forks in thinking.** Every storyline is one independent topic; rule-first, LLM-fallback classification runs incrementally — each new message is decided once (append / fork / new), never re-clustered in bulk.
2. **Click a node to revisit any past Q&A — efficiently distilled.** Each node opens a detail card with the question, one-line summaries of tool calls, and the answer. Long storylines fold into multiple rows at semantic breakpoints, with bold labels marking the turns.
3. **Auto-distilled, persisted development memory.** The classification is stored in `DEV_LOG.json` at the workspace root. Restart the project or switch agents — the map reloads instantly with 0 LLM calls and keeps its memory.

## Features

- **Storyline map tab** (`MindMap` in the session view): one row per topic, bezier gradient ribbons, six node shapes (question / decision / feature / bugfix / refactor / research).
- **Status badges** under every title: `进行中` (ongoing, green) / `有阻塞` (blocked, amber) / `已完成` (done, blue) / `讨论结束` (discussion ended, gray), followed by a one-line description.
- **Instant open**: `DEV_LOG.json` exists and its format version matches → no rebuild, 0 LLM; new messages sync in the background and refresh automatically.
- **Background progress**: full rebuilds show a progress bar; incremental syncs show a small hint.

## Install

Prerequisite: DeepSeek Harness installed (`dsh` command available), a web profile in use, and **pnpm** on `PATH` (`dsh plugin` forwards to pnpm; install it with `npm install -g pnpm` if missing).

```sh
dsh plugin --profile web add github:ImCabbage/dsh-plugin-mindmap
```

1. The command installs the package into the profile with pnpm and adds it to the profile's bundle list automatically (the package declares `dsh.bundle`). The host and browser bundles are prebuilt and shipped in this repo — no build step and no build-script allowlist are needed. The install writes into `$DSH_HOME/profiles/<name>`, so that directory must be writable.
2. **Restart the web process**: stop the running `dsh web` and start it again. Refreshing the browser page is **not** enough — the composition is fixed at boot.
3. Verify the row is mounted:

   ```sh
   dsh --profile web --dump-config | grep mindmap
   ```

   You should see `- id: mindmap` next to `name: dsh-plugin-mindmap`.
4. Open any session — a **MindMap** tab appears in the view tab bar.

> The plugin creates `DEV_LOG.json` in the workspace root of every project you use it with — that file is the distilled memory itself. Add it to the project's `.gitignore` if you don't want to commit it.

### Troubleshooting

- `dsh: pnpm not found on PATH` — install pnpm first: `npm install -g pnpm`.
- Permission / `EROFS` / read-only errors — the install writes into `$DSH_HOME/profiles/<name>`; run it from an environment where that directory is writable.
- An `allowBuilds` hint printed by `dsh` after a pnpm failure — this plugin has no build script (prebuilt `lib/` ships in the repo), so that hint does not apply and can be ignored; check the real pnpm error above it.
- The first open keeps showing "梳理新消息 / syncing" for a long time — the first full distillation needs working model credentials (LLM calls). The tab shows a warning line when LLM calls fail; check your model credentials and network.

### Local development

```sh
dsh plugin --profile mindmap-test add .
```

(A separate test profile keeps your daily `web` profile untouched.)

## Usage

1. Chat normally; MindMap classifies in the background (progress is shown inside the tab).
2. Open the **MindMap** tab:
   - each colored ribbon is one independent topic, nodes ordered left-to-right by time;
   - click a node: focus its storyline and open the detail card (question / tool-call summaries / answer);
   - click empty space: clear focus;
   - the small line under each title is its current status (badge + description).
3. The first open (or a `DEV_LOG` format upgrade) runs one full distillation with a progress bar; after that every open is instant.

## How it works

- **Host half** (`src/host`): the `MindMapGateway` service (Typert remotes `mindmap/graph` and `mindmap/progress`) reads the session log, classifies incrementally (rules + LLM), reads/writes `DEV_LOG.json`, and runs background sync tasks with progress.
- **Client half** (`src/client`): registers the `MindMap` tab in the `conversation.view` slot; fetches the graph through `ctx.remote`, renders instantly from `DEV_LOG`, and polls background progress for auto-refresh.
- **RPC**: Typert protocol, with manifests hand-written in `src/host/typert.host.js` (host side) and `src/host/typert.remote-client.js` (client mount side), strict zod codecs.

## Develop

```sh
npm install
npm run build        # esbuild: lib/index.js (host) + lib/client.js (browser bundle)
```

Rebuild after changes, then restart the test profile's `dsh web`. Note: the built `lib/` is committed to this repo — git installs use it directly — so commit it together with the source changes.

## License

[MIT](./LICENSE)