@local/branch-map

Readme

# 分支图谱插件（branch-map）

会话分支图谱：树形管理 fork 会话 + 每分支注解文档 + 布局持久化。
**纯自研渲染（零第三方依赖、零 CDN、零构建步骤）**，静态双端包形态。

**一条命令完成安装 + 激活，不再需要手工改 patch 文件、不再需要 mklink junction。**

## 一、安装方法：

```powershell
# 方式 A：git 仓库
dsh plugin --profile web add github:<你的用户名>/branch-map-plugin
```

## 二、卸载 / 禁用

```powershell
dsh plugin --profile web remove @local/branch-map   # 从 bundles 与依赖里移除
```

## 三、架构

| 端 | 文件 | 职责 |
| --- | --- | --- |
| Host | `lib/index.js` | 工作区森林聚合（`sessionQuery`）、注解/布局文件读写（`fs`，`.branchmap/*.yaml`）、分支重命名（`sessionTitle`）；经 `webServer` 前缀路由暴露 JSON-RPC：`POST /branchmap/rpc`（method: tree / revision / annotations.read / annotations.save / annotations.remove / session.rename / layout.read / layout.save / diag） |
| Client | `lib/client.js` | `dsh.client` 静态 bundle（`window.__ModuleLoader__.load` 工厂格式）注册 `conversation.view` 槽位条目；卡片树 + 连线 + 分叉点 + 拖拽/平移/缩放 + 状态过滤 + 编辑对话框 + 自动定位 |
| Patch 层 | `cordis.patch.yml` | bundle 自带激活行（单行 insert 同时挂 host 行与 client 半区，client-modules 按 `dsh.client` 声明扫描进浏览器图谱） |

- 树结构不落盘：`sessionQuery.listSessions()` 按会话 cwd 实时聚合（多根森林）。
- 数据文件：每个工作区一份 `.branchmap/annotations.yaml`（乐观锁 revision）与
  `.branchmap/layout.yaml`（节点位置，拖拽自动保存）；另有 `.branchmap/diag.log`。

## 四、使用

1. 打开任意会话 → 顶部标签"**分支图谱**"。
2. 卡片 = 一个工作区会话；连线边上的圆点 = 分叉点（`#fork序号`）。
3. 拖拽卡片调整布局（自动保存）；空白处拖拽平移；工具栏"重置布局 / 适应窗口 / 刷新"。
4. "编辑"打开对话框：分支名称（同步到侧边栏/标题）、主要说明、状态、标签。
5. 状态下拉过滤卡片；"跳转"在新会话打开该分支。

![效果示意图](./img/img.png "效果示意图")