dsh-plugin-graph

DeepSeek Harness（DSH）Web 设置页插件：以力导向图（Koishi / Obsidian 风格）可视化客户端插件之间的关系。

Tip: 这是一个dsh自己写的项目，还在快速完善中 如有好的想法，欢迎提出Issue~

功能

• 力导向图画布：节点自动物理布局，节点按度数缩放。
• 两类节点：
  • 插件节点（蓝色圆点）—— 来自启动清单 window.__DSH_BOOT__ 与插槽注册表；
  • 插槽节点（琥珀色菱形）—— 来自实时插槽注册表 ctx.slots.snapshot()。
• 三类彩色边：
  • 蓝色 inject —— 插件对其它包的依赖；
  • 绿色 declares —— 插槽声明者；
  • 琥珀色 registers —— 注册到插槽的插件。
• 交互：拖拽节点（重新加热布局）、拖拽空白平移、滚轮缩放、悬停高亮相邻节点并弹出信息框（显示依赖/被依赖、声明者/注册者）。
• 放大查看：画布右上角展开按钮，打开全屏模态框，支持 Esc / 遮罩 / × 关闭。
• 只读快照：不订阅任何事件，挂载与手动刷新时重建图。

快速上手

1. 前置条件

• 已安装 DeepSeek Harness，并至少启动过一次 Web 界面（会生成 ~/.dsh/profiles/web）。

2. 安装插件

二选一：

方式 A：从 npm registry 安装（推荐一般用户使用）

dsh plugin --profile web add dsh-plugin-graph

方式 B：从本地源码目录安装（开发 / 未发布时）

dsh plugin --profile web add /path/to/dsh-plugin-graph

dsh plugin add 会把包装进 profile 的 package.json 依赖并链接到 ~/.dsh/profiles/web/node_modules。请不要用裸 npm i dsh-plugin-graph 安装——那只会装进当前目录的 node_modules，dsh 并不知道它。

本包自带 dsh.bundle 声明（cordis.patch.yml 配置层），dsh plugin add 后会自动追加到 profile 的 dsh.profile.bundles 层叠，启动时由包自带的 patch 挂载 ui-plugin-graph 行——无需手动编辑 cordis.patch.yml。

升级提示：如果在旧版本（无 dsh.bundle）时手动往 cordis.patch.yml 加过 insert: - id: ui-plugin-graph，请删除该条目，避免与 bundle 自带的挂载重复。

3. 重启并打开

1. 重启 dsh Web 进程（配置变更和 loader 条目都需要重启才生效）。
2. 打开设置页（侧边栏底部「设置」）→ 找到 「插件关系图谱」 入口（位于 Agent 预设之后）。
3. 点击进入，即看到力导向图。

4. 使用画布

操作	效果
拖拽节点	钉住该节点，重新加热布局
拖拽空白处	平移画布
滚轮	缩放
悬停节点	高亮相邻节点，弹出信息框（依赖/被依赖、声明者/注册者）
点击右上角 ⤢	打开全屏模态框（Esc / 遮罩 / × 关闭）
点击 ↻	手动刷新（重新读取启动清单与插槽注册表）

5. 卸载

dsh plugin --profile web remove dsh-plugin-graph

dsh 会同时移除依赖与 dsh.profile.bundles 里的层条目；如果旧版本手动加过 cordis.patch.yml 的 insert，也一并删除，最后重启 dsh。

6. 常见问题

• 设置页没有「插件关系图谱」入口：确认 dsh plugin add 后 profile 的 package.json 中 dsh.profile.bundles 包含 dsh-plugin-graph（cat ~/.dsh/profiles/web/package.json）；确认重启过 dsh；确认 node_modules 里链接存在（ls ~/.dsh/profiles/web/node_modules/dsh-plugin-graph）。
• 安装时报 declares no dsh.bundle 警告：说明安装的版本过旧（< 0.2.0，尚无 bundle 声明），升级后重新 dsh plugin add 即可自动成为 profile 层。
• 安装时 pnpm 报 peer 依赖缺失（missing peer @deepseek-ai/cordis / react ...）：这是预期提示。profile 模板固定 autoInstallPeers: false + hoisted linker，缺失 peer 会回退到安装级 profiles/node_modules，运行时由宿主提供，功能不受影响（harness 内部 client 插件同样声明这些 peer）。若升级 dsh 后版本不匹配，同步升级本包。
• 图谱里看不到宿主插件：本图只覆盖客户端插件（__DSH_BOOT__ 内的 dsh.client 行）；宿主平面行（webserver、storage 等）仅在被插槽声明/注册时出现。见「已知限制」。

构建与测试

pnpm install
pnpm build      # tsc 声明 + tsdown 打包（lib/client.js 为浏览器 bundle）
pnpm test       # vitest 单元测试（--pool=threads）

构建产物约定：exports["./client"] 指向 lib/client.js，宿主经 /plugins/<id>/client.js 提供；dsh.client 声明是浏览器名册准入。

设计说明

• 数据流：build() 同步读取 window.__DSH_BOOT__ 与 ctx.slots.snapshot()，由 buildPluginGraph 组装成模型，再由 buildVisualGraph 转为图节点/边（纯函数、可单测）。
• 力模拟：ForceGraph.tsx 内置斥力 + 弹簧 + 向心力 + 阻尼 + alpha 衰减，requestAnimationFrame 驱动，收敛后自动停止；拖拽节点时将其钉住（不参与积分），邻居仍对其受力。
• 主题：全部使用 DSH 设计 token（--dsw-static-* / --dsw-alias-*），自动适配亮/暗主题。

已知限制

• 快照视图：不订阅 slots/changed，HMR 注册变化需手动刷新（画布右上角 ↻）。
• 仅客户端插件：宿主平面行（webserver、storage 等）不在 __DSH_BOOT__ 中，仅当被插槽声明/注册时才会出现。
• 内嵌图与模态框图为两个独立模拟实例（各自演算布局，互不共享拖拽位置）。

License

MIT