dsh-branch-visualizer

Readme

# DSH Branch Visualizer

[![CI](https://github.com/111222cjyq/dsh-branch-visualizer/actions/workflows/ci.yml/badge.svg)](https://github.com/111222cjyq/dsh-branch-visualizer/actions/workflows/ci.yml)

一个面向 DeepSeek Harness 的持久化分支可视化插件。它把 Harness 原生会话与子代理关系展示为可拖拽树图，并在同一界面提供跳转、改名和归档操作。

> 当前状态：**Developer Preview**。本插件已按 2026-08-21 的 DeepSeek Harness `0.1.0-rc.8` / `master` 契约核对，但 Harness 本身仍处于实验阶段。适配策略与已知风险见 [DSH_COMPATIBILITY_STRATEGY.md](./DSH_COMPATIBILITY_STRATEGY.md) 和 [KNOWN_LIMITATIONS.md](./KNOWN_LIMITATIONS.md)。

## 功能

| 功能 | 说明 |
| --- | --- |
| 原生分支树 | 读取同一工作区的会话、父会话和子代理关系，自动生成树形布局 |
| 自由画布 | 支持拖动节点、框选、平移、缩放、自动布局和视图居中 |
| 紧凑显示 | 普通面板在有效缩放低于 `0.6` 时切换圆形节点；紧凑面板阈值为 `0.85` |
| 会话跳转 | 双击普通节点打开会话；子代理节点使用 Harness 的 `openSubagent` 地址跳转 |
| 运行状态 | 区分 `running`、`idle`、`cold`，并监听 Agent 生命周期事件 |
| 标题修改 | 支持活跃会话直接改名；冷会话通过持久化事件追加并处理序列冲突 |
| 单项/批量归档 | 归档前校验工作区归属，批量结果逐项返回；父节点归档时收集其子代理后代 |
| 归档显示模式 | 默认不加载归档节点；可切换完整视图。隐藏归档链时用双虚线连接最近可见祖先 |
| 性能保护 | 快照 TTL/LRU、同键请求合并、全局重建并发上限、子代理 TTL/LRU 和轮询退避 |
| 兼容诊断 | `/brvis/api/diagnostics` 返回去敏的适配器版本、能力状态和缺失能力 |

## 安装

前置条件：

- DeepSeek Harness 支持 bundle/plugin profile；
- Node.js `^22.19.0` 或 `>=24.0.0`；
- 使用 Harness CLI 管理插件，不要手工复制构建产物。

从 GitHub 安装到指定 profile：

```bash
dsh plugin --profile <profile> add github:111222cjyq/dsh-branch-visualizer
```

然后重启对应的 Harness 进程。Cordis 动态包是进程内实例，源码或 `lib` 更新不会自动替换已经运行的插件实例。

Git 依赖会通过 `prepare` 自动构建。如果 pnpm 报告构建脚本被阻止，请让 Harness CLI 把精确包名 `dsh-branch-visualizer` 加入宿主项目的 `pnpm.allowBuilds`，不要全局放开任意依赖脚本。

更新或移除时仍通过同一个 profile 操作，并在操作后重启 Harness。CLI 参数以当前 Harness 版本的 `dsh plugin --help` 为准。

## 使用

1. 打开任意会话。
2. 点击会话标题栏中的“◈ 分支图”。
3. 双击节点跳转；拖动节点调整布局；空格加左键平移画布。
4. 选择一个或多个节点后执行改名或归档。
5. 需要检查完整历史时开启“显示归档”。大工作区第一次加载完整历史可能明显慢于默认视图。

## 持久化与数据边界

这是标准 Harness bundle，不依赖临时注入器，也不把状态写入浏览器全局变量。安装关系由 `package.json` 的 `dsh.bundle.patch` 和根目录 `cordis.patch.yml` 声明；宿主和客户端由同一个包提供。

插件：

- 不包含遥测、广告、分析 SDK 或第三方网络请求；
- 只通过 Harness 同源 `/brvis/api` 访问本地宿主；
- 读取会话 ID、标题、父子关系、工作区归属、归档状态和 Agent 状态；
- 只有在用户明确点击时才改名或归档；
- 兼容诊断不返回路径、会话 ID、标题或用户内容；
- 源码和发布包通过隐私扫描，禁止提交本机用户目录、私钥和明显的硬编码令牌。

更完整的威胁模型见 [SECURITY.md](./SECURITY.md)。

## 面向 Harness 大改的适配结构

业务核心不直接绑定 Harness 的服务名和槽位名：

```text
DeepSeek Harness
      │
      ├─ Host adapter: src/platform/adapters/dsh-preview-2026-08/host.ts
      ├─ Client adapter: src/platform/adapters/dsh-preview-2026-08/client.ts
      │
      ├─ Stable contracts: src/shared/
      │
      ├─ Host core: src/host/
      └─ Client core: src/client/
```

如果 Harness 修改 service key、事件 payload、slot 名称或导航 API，应优先新增版本化 adapter，并在能力探测中明确降级；不要把版本判断散落到布局、缓存、HTTP 或 mutation 代码中。详细升级流程见 [DSH_COMPATIBILITY_STRATEGY.md](./DSH_COMPATIBILITY_STRATEGY.md)。

## 项目结构

```text
src/
  index.ts                         Host 装配与同源 API
  host/
    data.ts                        快照、缓存、授权、子代理和 Agent 状态
    mutations.ts                   改名与归档
    canonical-path.ts              工作区权威路径键
    http-guard.ts                  HTTP/CSRF 边界
  client/
    index.ts                       Client 装配、槽位和共享状态
    canvas.tsx                     React 生命周期与画布编排
    canvas-interactions.ts         手势、跳转、改名和归档动作
    canvas-elements.tsx            展示组件
    canvas-geometry.ts             命中、框选和几何计算
    layout.ts                      树布局与边计算
    api.ts                         同源 transport
    styles.ts                      样式
  platform/
    adapters/dsh-preview-2026-08/  Harness 版本适配层
    capabilities.ts                无副作用能力探测
    diagnostics.ts                 去敏诊断报告
  shared/                          稳定 wire/runtime 契约
tests/                             生产构建产物回归测试
scripts/                           跨平台构建与隐私检查
cordis.patch.yml                   Harness profile patch
```

后续扩展的模块边界与拆分顺序见 [PERSISTENT_ARCHITECTURE_SPLIT_GUIDE.md](./PERSISTENT_ARCHITECTURE_SPLIT_GUIDE.md)。

## 开发与验证

```bash
npm ci --ignore-scripts
npm run verify
```

`npm run verify` 会依次执行：

- TypeScript 类型检查；
- ESLint；
- Windows/Linux 通用的 Node 构建脚本；
- 生产产物回归测试；
- 隐私/密钥扫描；
- npm 发布内容预览。

CI 在 Node `22.19.0` 和 Node `24` 上执行同一套流程。测试直接导入 `lib`，构建缺失或产物不可加载时会失败，不使用静态副本兜底。

## 当前不成熟之处

最重要的限制如下：

- DeepSeek Harness 仍是实验版本，未来的 profile、Cordis、slot、session 或 subagent 契约可能发生破坏性变化；
- 当前只支持 `dsh.client.platform = web`，未验证 Electron/桌面专用 bridge；
- HTTP 边界用于阻止普通跨站浏览器请求，不是本机恶意进程隔离或多用户认证系统；
- 冷会话改名依赖 session event 结构，是适配中最容易受 Harness schema 变化影响的能力；
- 尚未提供“取消归档”，也没有在非常大的工作区完成长期基准；
- 画布已支持常用鼠标/指针操作，但键盘无障碍和触屏手势仍不完整；
- 自动化测试覆盖逻辑、构建和打包，真实 Harness UI 仍应在每个兼容版本上做一次人工冒烟。

完整清单、影响和规避办法见 [KNOWN_LIMITATIONS.md](./KNOWN_LIMITATIONS.md)。

## 许可证

[MIT](./LICENSE)