前言¶
用 DeepSeek Harness（DSH）写智能体或调模型时，推理往往跑在 DGX Spark 集群上，模型服务、decode/prefill 速率和各节点 GPU 状态通常要另开 Spark Scope 仪表盘才能对照。下面介绍社区插件 dsh-spark-scope：把 Spark Scope 迷你窗口里的 Glance 视图嵌进 DSH 左侧边栏底部，在 dsh web 或 Desktop 里工作时不必频繁切页，也能持续看到节点与模型服务概况。
这是什么¶
dsh-spark-scope（GitHub：juliankang4/dsh-spark-scope）由维护者 juliankang4 发布，在 DSH 插件目录中归类为客户端插件。它依赖独立项目 Spark Scope 提供的数据，在 DSH 侧栏展示与 Spark Scope 迷你窗口一致的监控摘要：decode、prefill、各 DGX Spark 节点状态等。插件当前版本 0.0.4，许可证 MIT；与 DSH 的适配在 README 中注明曾用 dsh 0.2.0-rc.2 / 0.2.1-rc.2 测试。
核心功能¶
侧栏监控卡片¶
卡片位于侧栏底部（在 dsh-cost-meter 等页脚项之上），主要内容包括：
- 顶部：模型名、响应中的节点数、decode 与 prefill 速率及五分钟 sparkline。
- 中部：运行中与排队请求、KV cache 占用、近五分钟 TTFT / TPOT p95、前缀缓存命中率。
- 底部：每个节点的 GPU 温度、功耗、负载与显存；节点超过四个时，行布局为两列。
模型名旁圆点：Spark Scope 报告集群健康时为绿色，其他状态为橙色；Spark Scope 无响应或数据超过 20 秒未更新时为红色。无读数时显示 —。右上角按钮可将卡片折叠为单行（模型名 + decode 速率），浏览器会记住折叠状态；侧栏整体收起时卡片隐藏。
与推理后端差异¶
卡片只展示推理引擎实际上报、且与 Spark Scope 相同标签的指标。例如 oMLX 自服务启动起的平均 decode/prefill 不带 sparkline；llama.cpp 用平均 decode 时间代替 TPOT、用 context 占用代替 KV cache；读取 oMLX 需要 API key 时，卡片会提示。多模型服务并存时，行为类似 Spark Scope 的 “All at once”：速率与请求会汇总，并列出各服务及其 decode 与状态；(servers 1/2) 表示仅部分服务上报该速率。离散 GPU 显存标为 VRAM；Mac 节点无 GPU 温度/功耗，汇总功耗会注明覆盖节点数，如 (5/6 nodes)。
数据如何进入 DSH¶
插件在 dsh web 服务器上增加路由 /plugins/dsh-spark-scope/state。页面可见时，卡片约每 2 秒请求该路由；dsh 再以 5 秒超时向 <你配置的地址>/api/state 拉取数据。插件只读，不会修改 Spark Scope 或节点。该路由与 dsh 自有 API 使用相同的登录与 Host 校验，仅已登录的 dsh 页面可读；超过 2 MB 的 Spark Scope 响应会被 dsh 忽略。详见 dsh SAFETY.md。
主题与语言跟随 dsh（含中文；韩文可配合 dsh-locale-ko），缩放可与 dsh-ui-scale 一致。
安装与启用¶
除安装插件外，还需要已运行的 Spark Scope 服务，安装方法见 spark-scope#installation。
Web 侧使用官方命令（勿自行拼接 github:owner/repo）：
dsh plugin --profile web add dsh-spark-scope
Desktop：打开 Plugins → Add plugin，输入 dsh-spark-scope 并安装。
配置 Spark Scope 地址¶
在 DSH Settings 的 Spark Scope 标签页填写仪表盘地址后按 Enter。支持局域网地址（如 http://spark-scope.local:8787）或 tailnet 地址（如 https://spark-scope.example.ts.net）；省略 scheme 时会自动补 http://。清空字段可隐藏卡片。
若当前打开的 dsh 页面无法保存设置，输入框会禁用并说明原因；dsh 0.2.0 仅允许在运行 dsh 的那台机器上保存该设置。
数据由 dsh 进程请求，而非浏览器直连，因此地址必须能从运行 dsh 的计算机访问。Spark Scope 默认只响应 localhost、IP 或自身主机名；若使用反向代理等其他主机名，需在 Spark Scope 服务端配置 SPARK_SCOPE_ALLOWED_HOSTS。
也可在 profile 的 cordis.patch.yml 中写入：
- id: spark-scope
name: dsh-spark-scope
config:
url: http://spark-scope.local:8787
配置字段如下（以 README 为准）：
| 字段 | 默认 | 说明 |
|---|---|---|
url |
空 | Spark Scope 地址（http 或 https）；留空则隐藏卡片 |
适用场景与注意¶
适合：已在 DGX Spark 上跑 vLLM、SGLang、oMLX、llama.cpp 等，并用 Spark Scope 做集群与模型服务监控；希望在使用 DSH 写提示、跑智能体时，侧栏持续显示 decode/prefill 与节点健康，减少切到独立仪表盘。
注意：
- 插件随 当前 dsh 进程拉取内网或 tailnet 地址，安装前宜阅读仓库源码与 MIT 许可证，并按 dsh 安全文档部署。
- 浏览器里打开的 dsh 若与运行 dsh 的机器不是同一台，Settings 能否保存
url受 dsh 版本与策略限制，需按界面提示操作。 - 社区插件目录 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系；DSH 生态强调「一切皆插件」，本插件为客户端扩展，不改变 DSH 核心行为。
