During the development and debugging of DeepSeek Harness (DSH), understanding Cordis state (such as plugin loading status, tool visibility, credential configuration, and more) usually requires running Shell commands or manually reading configuration files. Traditional Skills often play the role of a “symptom checklist,” telling the agent which commands to run and how to parse the output. The dsh-tool-diagnose plugin changes this pattern. As a Cordis plugin, it runs introspection inside the process and directly exposes a model-facing diagnose tool.

Preface

The plugin is designed to solve the problem of developers needing to inspect DSH runtime state in real time and with precision. Instead of relying on external scripts or Skills, it provides an extensible inspection mechanism through the ctx.diagnostics registry. This allows the agent to invoke the diagnostic tool directly in a conversation and obtain real-time data about plugin state, tool availability, credential resolution, approval policies, token pressure, and the subagent tree.

Installation and Enablement

Installation requires specifying an existing Profile. DSH provides two default Profiles, web and headless, corresponding to Web UI and command-line one-off task scenarios, respectively.

  1. Web UI environment:
    dsh plugin --profile web add dsh-tool-diagnose
  1. Headless terminal environment:
    dsh plugin --profile headless add dsh-tool-diagnose

If your environment uses a custom Profile (i.e., the $DSH_HOME/profiles/<name>/ directory), replace the argument after --profile with your Profile name.

Core Features

The core of the plugin is the ctx.diagnostics service. It contains a set of checks. Some checks depend on specific services (such as ctx.credentials, ctx.approval, and so on). If a dependent service is not mounted, the plugin automatically skips the corresponding checks without causing the overall plugin loading to fail.

The supported checks include:

  • plugin-fiber-state: Reads ctx.loader.entries() and reports the enabled/disabled status of plugin entries and their Fiber phase (pending/loading/active/failed/unloading).
  • tool-visibility: Calls ctx.tools.get(name) to confirm whether a tool is registered or visible in the global scope.
  • credential-resolution: Resolves credential references (such as DEEPSEEK_API_KEY) through ctx.credentials.describe(). It returns only configuration/source/writability status and does not leak the actual secret.
  • approval-policy: Reports the deployed default approval policy (“ask”/”never”), or a session-specific override policy.
  • token-pressure: Compares totalTokens (request/response pressure) with surfaceTokens (fixed heuristic total) to help troubleshoot why compression did not run.
  • subagent-tree: Flattens the session’s subagent tree and reports the count, maximum depth, and unresolvable descendants.

Typical Usage

When invoking the diagnose tool in a conversation, you can provide an optional target parameter to filter the scope of checks. The exact meaning of target depends on the individual check:

  • plugin-fiber-state: A substring of the plugin module name.
  • tool-visibility: The tool name.
  • credential-resolution: The credential reference name.
  • subagent-tree: The session ID.

Example: Checking why the bash_run tool is not displayed

The agent can make the following call:

Invoke the diagnose tool with target "bash_run" to check tool visibility.

The system returns the relevant check results, helping identify whether the issue is tool registration, plugin loading failure, or scope restriction.

Extension Mechanism

The design of dsh-tool-diagnose allows other plugins to depend on and extend its inspection capabilities. A check is essentially a factory function closed over ctx. Third-party plugins can depend on the diagnostics service through ctx.inject within their own apply function and register new checks.

Third-Plugin Extension Example:

import type { Context } from '@deepseek-ai/cordis'

export const name = 'my-extra-diagnostics'

export function apply(ctx: Context) {
  ctx.inject(['diagnostics'], (ctx) => {
    ctx.diagnostics.registerCheck({
      id: 'my-check',
      description: '检查特定业务逻辑的状态',
      run(target) {
        // 在此处读取闭包捕获的 ctx
        // 不要将 ctx 作为 run() 的参数传入
        return []
      },
    })
  })
}

Difference Between Plugins and Skills

This is a Cordis plugin, not a Skill. It runs inside the DSH process and directly accesses service state in memory. In contrast, a Skill is a portable, build-free script, typically used to tell the agent to run external commands. The two can be used together: a Skill can instruct the agent to first invoke the diagnose tool and then make judgments based on the tabular data returned by the tool.

Resource Links

  • GitHub Repository: https://github.com/xu-kai-quan/dsh-tool-diagnose
  • NPM Package: dsh-tool-diagnose
  • Community Directory: https://www.skillhub.cn/plugins/xu-kai-quan/dsh-tool-diagnose