前言¶
在 DSH（DeepSeek Harness）里做运维或可观测性相关的智能体时，模型往往需要查指标、看告警、核对抓取目标，而不是只读静态文档。常见做法是自己在插件里拼 HTTP 请求、维护 endpoint 列表和错误格式，和 Prometheus 官方 API 也容易对不齐。
下面介绍社区插件 huckops/dsh-prometheus-plugin（维护者 HuckOps）：基于 Cordis 与 @deepseek-ai/dsh-tools，将 Prometheus HTTP API 注册为一批带 promql- 前缀的工具，供 LLM agent 直接调用。插件当前版本为 0.1.0（见仓库 package.json），许可证 MIT。
这是什么¶
一句话：面向 DSH 的 Prometheus / PromQL 工具包，用声明式工具定义覆盖 Prometheus 官方 HTTP API 的主要读路径与部分管理接口。
前提条件：有一台可通过 HTTP 访问的 Prometheus 实例。部分工具还要求 Prometheus 启动参数或版本满足 README 中的说明（见下文「适用场景与注意」）。
核心功能¶
资料中列出的能力如下。
工具规模与实现方式¶
- 共 30 个工具，对应 Prometheus HTTP API 的查询、元数据与序列、targets、规则与告警、状态、实验性 Search API、以及 admin TSDB 等端点。
- 共享 HTTP 客户端（
src/client.ts），统一错误格式；请求超时通过AbortController配置，默认 30 秒。 - 工具由
@deepseek-ai/dsh-tools以声明式方式注册，便于 agent 选用。
工具与 API 对应关系（前缀 promql-）¶
Query
| 工具 | Prometheus endpoint |
|---|---|
promql-query |
GET /api/v1/query |
promql-query-range |
GET /api/v1/query_range |
promql-format-query |
GET /api/v1/format_query |
promql-parse-query |
GET /api/v1/parse_query |
promql-query-exemplars |
GET /api/v1/query_exemplars |
Metadata & series
| 工具 | Prometheus endpoint |
|---|---|
promql-series |
GET /api/v1/series |
promql-labels |
GET /api/v1/labels |
promql-label-values |
GET /api/v1/label/{name}/values |
promql-metadata |
GET /api/v1/metadata |
Targets
| 工具 | Prometheus endpoint |
|---|---|
promql-targets |
GET /api/v1/targets |
promql-targets-metadata |
GET /api/v1/targets/metadata |
promql-scrape-pools |
GET /api/v1/scrape_pools |
Rules / alerts / alertmanagers
| 工具 | Prometheus endpoint |
|---|---|
promql-rules |
GET /api/v1/rules |
promql-alerts |
GET /api/v1/alerts |
promql-alertmanagers |
GET /api/v1/alertmanagers |
Status
| 工具 | Prometheus endpoint |
|---|---|
promql-status-config |
GET /api/v1/status/config |
promql-status-flags |
GET /api/v1/status/flags |
promql-status-runtimeinfo |
GET /api/v1/status/runtimeinfo |
promql-status-buildinfo |
GET /api/v1/status/buildinfo |
promql-status-tsdb |
GET /api/v1/status/tsdb（Prometheus 3.6.0+） |
promql-status-tsdb-blocks |
GET /api/v1/status/tsdb/blocks |
promql-status-walreplay |
GET /api/v1/status/walreplay |
promql-status-self-metrics |
GET /api/v1/status/self_metrics |
promql-features |
GET /api/v1/features |
Search（实验性，需 --enable-feature=search-api）
| 工具 | Prometheus endpoint |
|---|---|
promql-search-metric-names |
GET /api/v1/search/metric_names |
promql-search-label-names |
GET /api/v1/search/label_names |
promql-search-label-values |
GET /api/v1/search/label_values |
Admin（需 --web.enable-admin-api）
| 工具 | Prometheus endpoint |
|---|---|
promql-admin-snapshot |
POST /api/v1/admin/tsdb/snapshot |
promql-admin-delete-series |
POST /api/v1/admin/tsdb/delete_series |
promql-admin-clean-tombstones |
POST /api/v1/admin/tsdb/clean_tombstones |
README 还说明：部分端点仅在较新 Prometheus 上可用（如 format-query、parse-query、query-exemplars、status-tsdb（3.6.0+）、status-self-metrics、features 等）；对旧版本调用时，错误来自 Prometheus 自身的 HTTP 响应。
安装与启用¶
仓库 README 给出的安装方式是将 bundle 装入 DSH profile，无需手改 cordis.yml：bundle 通过 cordis.patch.yml 注册 promql-plugin 条目，包名为 @local/dsh-prometheus-plugin（由 package.json 的 dsh.bundle.patch 解析）。
1、取得插件目录（README 示例为 clone 仓库到本地路径）。
2、在 DSH（agent 或 Plugin Manager）中安装 bundle：
# 在 dsh 中执行（路径替换为你的本地目录）：
plugin_manager install_bundle /path/to/dsh-prometheus-plugin
README 中的完整示例还包含获取源码的一步；若你从其他渠道拿到同目录结构的 bundle，仍以 install_bundle 指向该目录为准。
3、按需修改 Prometheus 地址。patch 自带默认配置：
- insert:
- id: promql-plugin
name: '@local/dsh-prometheus-plugin'
config:
prometheusEndpoint: http://127.0.0.1:9090
编辑 patch，或覆盖该 entry 的 config，将 prometheusEndpoint 指向你的 Prometheus。省略时默认 http://127.0.0.1:9090。
从源码构建时，在插件目录执行：
npm install # postinstall 会运行 tsc，输出到 lib/
说明：@deepseek-ai/dsh-tools、@deepseek-ai/cordis、@deepseek-ai/schemastery 在 package.json 中声明为与 DSH 宿主运行时匹配的 peer dependencies，不会打进插件包内。
典型用法¶
安装并配置 prometheusEndpoint 后，智能体在对话中即可按名称调用上述工具，例如：
- 排障时用
promql-query/promql-query-range执行即时或区间 PromQL； - 探索指标与标签时用
promql-labels、promql-label-values、promql-series、promql-metadata； - 核对抓取与规则时用
promql-targets、promql-rules、promql-alerts； - 看实例状态时用
promql-status-buildinfo、promql-status-runtimeinfo等。
各工具参数与 Prometheus API 查询参数一致，具体字段以工具 schema（@deepseek-ai/dsh-tools 注册定义）及 Prometheus HTTP API 文档 为准；本文不重复罗列每个 query 参数。
若启用了 Search 或 Admin 相关 Prometheus 特性，可额外使用 promql-search-* 与 promql-admin-*；未开启时调用会由 Prometheus 返回 HTTP 错误。
适用场景与注意¶
适合谁
- 已在用 DSH 做 SRE / 可观测性助手，希望 agent 直接读 Prometheus 而不是重复封装 API 的团队或个人。
- 需要覆盖「查询 + 元数据 + targets + 告警规则 + 状态」完整面的场景；只偶尔查一两个指标时，也可只用子集工具。
Prometheus 侧要求
- Admin 类工具（
promql-admin-snapshot、promql-admin-delete-series、promql-admin-clean-tombstones）需要 Prometheus 启动参数--web.enable-admin-api。 - Search 类工具需要
--enable-feature=search-api。 - 版本相关端点见上文「核心功能」与 README Prerequisites。
安全与权限
- 插件以当前 dsh 进程权限 向
prometheusEndpoint发 HTTP 请求；Admin 工具可能修改或清理 TSDB 数据，启用前应确认 Prometheus 访问控制与网络隔离。 - 安装 bundle 前建议阅读仓库源码与
LICENSE（MIT），确认行为符合你的环境策略。社区目录 SkillHub 插件页 与 GitHub 仓库由社区维护，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-prometheus-plugin 把 Prometheus HTTP API 收成 30 个 promql- 工具，并透过 cordis.patch.yml 与 prometheusEndpoint 完成 DSH 侧接入。需要查指标、看告警或核对抓取目标时，可在 agent 里直接选用对应工具，而无需为每个 endpoint 单独写插件 HTTP 层。
- 目录页：https://www.skillhub.cn/plugins/HuckOps/dsh-prometheus-plugin
- GitHub：https://github.com/HuckOps/dsh-prometheus-plugin
