DSH Branch Visualizer

一个面向 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 <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