111222cjyq/dsh-branch-visualizer

DSH 分支可视化器

CI

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

当前状态：Developer Preview。本插件已按 2026-08-21 的 DeepSeek Harness 0.1.0-rc.8 / master 契约核对，但 Harness 本身仍处于实验阶段。适配策略与已知风险见 DSH_COMPATIBILITY_STRATEGY.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：

dsh plugin --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。

面向 Harness 大改的适配结构

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

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。

项目结构

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。

开发与验证

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。

许可证

MIT