# dsh-plugin-mindmap

**MindMap** —— 一个 [DeepSeek Harness](https://github.com/deepseek-ai/DeepSeek-Harness) 插件：把对话蒸馏成持久化的 **storyline**，渲染成可交互的地图。

[English](./README.md) | 中文

![MindMap 效果图](mindmap.png)

## 核心亮点

1. **自动整理对话逻辑，识别关键的思维分叉点。** 每条 storyline 是一个独立主题；规则优先、LLM 兜底的分类是增量式的——每条新消息只判定一次（续写 / 分叉 / 新主题），从不全量重聚类。
2. **点击节点即可回顾过往问答，信息已被高效蒸馏。** 节点详情卡片展示问题、工具调用的一句话总结、以及回复；长主题会在语义转折点折成多行，转折点用加粗标签标注。
3. **自动蒸馏并保存开发信息：重启项目、更换 agent 不丢失记忆。** 分类结果持久化在工作区根目录的 `DEV_LOG.json`。重启项目或换 agent 后，地图 0 LLM 秒开，记忆完整保留。

## 功能

- **Storyline 地图 tab**（会话视图新增 `MindMap`）：一行一个主题，贝塞尔渐变丝带，六类节点形状（提问 / 拍板 / 新功能 / 修复 / 重构 / 调研）。
- **状态徽章**：每条主题标题下显示彩色状态胶囊——`进行中`（绿）/ `有阻塞`（琥珀）/ `已完成`（蓝）/ `讨论结束`（灰），后接一句话描述。
- **秒开**：`DEV_LOG.json` 存在且格式版本不变就不重建、0 LLM；新消息后台增量同步完成后自动刷新。
- **后台进度**：全量重建显示进度条，增量同步显示小提示。

## 安装

前置条件：已安装 DeepSeek Harness（`dsh` 命令可用）、有正在使用的 web profile，且 **pnpm 在 PATH 上**（`dsh plugin` 会转发给 pnpm；没有的话先 `npm install -g pnpm`）。

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

1. 命令会在 profile 目录里用 pnpm 安装本包，并自动把它加进 profile 的 bundle 列表（本包声明了 `dsh.bundle`）。宿主端与浏览器端产物已**预构建并随仓库分发**——无需任何构建步骤，也不需要 build-script 白名单。安装会写入 `$DSH_HOME/profiles/<name>`，该目录必须可写。
2. **重启 web 进程**：停掉正在运行的 `dsh web` 再重新启动。**仅刷新浏览器页面是不够的**——组合在启动时固化。
3. 验证挂载成功：

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

   应看到 `- id: mindmap` 对应 `name: dsh-plugin-mindmap`。
4. 打开任意会话，视图 tab 栏出现 **MindMap** 即安装成功。

> 插件会在每个使用过它的项目根目录生成 `DEV_LOG.json`——这个文件就是蒸馏记忆本身。不想提交它的话，请把它加进项目的 `.gitignore`。

### 常见问题

- `dsh: pnpm not found on PATH` —— 先装 pnpm：`npm install -g pnpm`。
- 权限 / `EROFS` / 只读错误 —— 安装要写 `$DSH_HOME/profiles/<name>`，请在可写该目录的环境执行。
- `dsh` 在 pnpm 失败后提示 `allowBuilds` —— 本插件**没有构建脚本**（预构建 `lib/` 随仓库分发），该提示不适用本插件，可直接忽略，看它上面真正的 pnpm 报错。
- 首次打开一直停在"梳理新消息/同步" —— 首次全量蒸馏需要**可用的模型凭据**（LLM 调用）。LLM 调用失败时 tab 内会显示一条警告；请检查模型凭据与网络。

### 本地开发安装

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

（用独立测试 profile，不影响日常使用的 web profile。）

## 使用

1. 正常交流即可，MindMap 在后台增量分类（进度显示在 tab 内）。
2. 打开 **MindMap** tab：
   - 每条彩色丝带是一个独立主题，节点按时间从左到右排列；
   - 点击节点：聚焦该主题并打开详情卡片（问题 / 工具调用总结 / 回复）；
   - 点击空白：取消聚焦；
   - 标题下方的小字是当前状态（徽章 + 描述）。
3. 首次打开（或 `DEV_LOG` 格式升级）会做一次全量蒸馏并显示进度条；之后每次打开都是秒开。

## 原理

- **Host 半**（`src/host`）：`MindMapGateway` 服务（Typert remote：`mindmap/graph`、`mindmap/progress`）负责读会话日志、规则 + LLM 增量分类、读写 `DEV_LOG.json`、后台同步任务与进度。
- **Client 半**（`src/client`）：在 `conversation.view` 槽位注册 `MindMap` tab；通过 `ctx.remote` 取图渲染，秒开旧图 + 轮询后台进度自动刷新。
- **RPC**：Typert 协议，清单手写于 `src/host/typert.host.js`（host 侧）与 `src/host/typert.remote-client.js`（client 挂载侧），严格 zod codec。

## 开发

```sh
npm install
npm run build        # esbuild：lib/index.js（host）+ lib/client.js（浏览器 bundle）
```

改动后重新构建，重启测试 profile 的 `dsh web` 即可生效。注意：构建产物 `lib/` 随仓库提交（git 安装直接用它们），源码改动后请连同 `lib/` 一起提交。

## License

[MIT](./LICENSE)