Introduction

In the DSH (DeepSeek Harness) ecosystem, building Kubernetes-oriented AIOps capabilities often requires integrating multiple independent toolchains. Existing approaches often fragment alert handling and incident diagnosis workflows. The dsh-aiops plugin aims to solve this problem by integrating alert ingestion, incident diagnosis, routing policies, and observability capabilities into a unified DSH workflow plugin.

Plugin Positioning

dsh-aiops is a Kubernetes-oriented AIOps plugin maintained by jarvan1. It provides Alertmanager-driven, read-only incident diagnosis and integrates structured incident reports, workspace-scoped historical auditing, and a dedicated AIOps portal.

Core Features

The plugin mainly includes the following capabilities:

  • Alertmanager-driven diagnosis: Drives incident diagnosis workflows based on Alertmanager events.
  • Authenticated entry: Provides authenticated Webhook endpoints for receiving alerts.
  • Session routing: Supports fingerprint-to-session routing, including persistent queues and resource budget management.
  • Query window: Provides alert-time query windows to assist diagnosis.
  • Skill pack: Packages the aiops-diag skill.
  • Dynamic data sources: Supports dynamic selection of Alertmanager, Prometheus, and Kubernetes observability capabilities.
  • Operator feedback: Supports append-only operator feedback mechanisms.
  • Audit and reports: Provides structured incident reports and workspace-scoped historical/routing auditing.

Installation and Enablement

Before installation, make sure the environment meets the dependency requirements.

Environment Dependencies

  • DSH version: @deepseek-ai/dsh@0.1.2-rc.1
  • Node.js version: ^22.19.0 or >=24.0.0
  • pnpm version: >=10

Installation Commands

In an environment where a DSH Web profile is configured, run the following command to install the plugin:

dsh plugin --profile web add github:jarvan1/dsh-aiops

If DSH is not configured globally, use npx to directly invoke the matching CLI version:

npx -y @deepseek-ai/dsh@0.1.2-rc.1 plugin --profile web add github:jarvan1/dsh-aiops

pnpm Version Compatibility

If you use pnpm 10 or later, the prepare script for Git dependencies may be blocked. When installation fails, the allowBuilds key is printed. Copy this exact key into the pnpm-workspace.yaml file in the DSH Web profile (usually located at ~/.dsh/profiles/web/pnpm-workspace.yaml):

allowBuilds:
  'dsh-aiops@https://codeload.github.com/jarvan1/dsh-aiops/tar.gz/<resolved-commit-sha>': true

Restart DSH after installation is complete.

Configuration and Usage

After installing the plugin, configure the relevant environment variables to connect to observability data sources.

Basic Configuration

The following environment variables provide optional defaults and can be persisted or overridden in DSH’s AIOps data source settings:

  • PROMETHEUS_URL
  • ALERTMANAGER_URL
  • KUBECONFIG
  • KUBERNETES_CONTEXT

Workflow Configuration

Configuring the automated workflow requires the following credentials:

  • AIOPS_WORKSPACE: Defines the workspace scope.
  • AIOPS_ALERTMANAGER_WEBHOOK_SECRET: The secret for the Alertmanager Webhook.

Webhook Listening

The Webhook listens on the local address 127.0.0.1:3081/alertmanager by default. If Alertmanager cannot access this local address, override the listening address by using the environment variable AIOPS_WEBHOOK_PUBLIC_URL.

AIOps Portal

In the DSH Web interface, open the dedicated portal through the persistent AIOps action at the bottom of the sidebar. This portal reads only AIOPS_WORKSPACE and does not expand the query scope based on the currently selected chat session. The Prometheus/Alertmanager URLs and kubeconfig path/context are persistently stored in DSH user settings.

Development and Debugging

Local Development

For local development, set the DSH_HOME environment variable and install the plugin using a link install:

DSH_HOME=/path/to/profile-home pnpm dsh plugin --profile web add link:/path/to/dsh-aiops/packages/aiops

Building and Testing

Run the following commands from the project root to perform type checking and tests:

pnpm install --offline
pnpm run typecheck
pnpm test

The command to build the plugin package is:

pnpm run pack:bundle

Notes

  1. Permission Requirements: The Kubernetes integration uses a read-only kubeconfig. It does not require the kubectl command-line tool, but basic read-only RBAC capabilities must be available.
  2. pnpm Configuration: When using pnpm 10+, ensure the allowBuilds entry in pnpm-workspace.yaml is configured correctly; otherwise, installation will fail.
  3. DSH Version: You must use @deepseek-ai/dsh@0.1.2-rc.1; otherwise, the plugin may not work correctly.
  4. Portal Scope: The portal always reads AIOPS_WORKSPACE and does not change scope when switching sessions.