dsh-plugins — External Plugin Repository for DeepSeek Harness

English | 中文

This repository is a directory of external (out-of-tree) plugins developed for DeepSeek Harness. Each extracted plugin is developed and released from its own Git repository. Plugins not yet extracted remain under plugins/; after migration this repository will contain only the index.

Background: Why "External" Plugins

• The DeepSeek Harness @deepseek-ai/* workspace packages are not published to the npm registry, so external plugins use the link: protocol to point their dependencies to a local harness checkout.
• Projects not yet extracted from plugins/ assume by default that the Harness checkout is located at the sibling path ../deepseek-harness. Each extracted project documents its own development layout and installation flow.

Directory Structure

dsh-plugins/
├── plugins/
│   ├── greet-tool/        # Example plugin: configurable greet tool (starter template for new plugins)
│   ├── cost-balance/      # Real-time session cost and account balance display (composer dock)
│   ├── codex-enabler/     # One-click Codex subagent integration
│   └── tool-audit/        # Tool-call audit: duration/outcome/failure/timeout (composer dock)
└── README.md

Plugin Index

greet-tool — Example Tool Plugin

• Type: host-only · tool
• Functionality: Registers a greet tool with a greeting configurable through Config.
• Description: A minimal, complete plugin example and a starter template for developing new plugins.
• Installation: Insert an entry in the patch layer (see Quick Start); it is ready to use after pnpm install and type checking.
• Documentation: plugins/greet-tool/README.md

cost-balance — Session Cost and Balance

• Type: host/client half plugin (host + client)
• Functionality:
  • Session cost: Listens for the usage event from each LLM request, converts usage into a monetary amount using the configured unit prices, and maintains a real-time running total
  • Account balance: Periodically calls DeepSeek GET /user/balance and displays the result below the input box
• UI: conversation.composer.dock slot with an always-visible status line (cost ¥0.0012 · 12.3K in · 4.5K out · balance ¥438.76)
• Data channels: Session cost uses session projection (pure event folding on the host → useProjection), while the balance uses the /cost-balance/balance route (client polling).
• Tests: 7 cases over the projection fold (accumulation / same-step replacement / cost derivation / schema consistency) (tests/).
• Documentation: plugins/cost-balance/README.md

usage-heatmap — Daily Token Usage Heatmap

• Type: host/client half plugin (host + client)
• Functionality:
  • GitHub-style heatmap: Shows daily token usage for the past year on the "Usage" page in Settings. Lighter and brighter cells indicate higher usage (green gradient), and hovering shows usage grouped by model (v4-pro/v4-flash)
  • Summary cards: Total balance and total token usage across the entire period
• Data channels: The host listens for session/event, aggregates usage by day, and assigns models based on request/header. On startup, it backfills historical data from persisted session logs; the client polls /usage-heatmap/history.
• Persistence: $DSH_HOME/usage-heatmap/daily-usage.json (atomic writes).
• Tests: 11 cases over the daily-usage fold / attribution / replacement / persistence invariants (tests/).
• Standalone repository: MoriTang/dsh-usage-heatmap
• Install: Clone the standalone repository, then run pnpm dsh plugin --profile web add /absolute/path/to/dsh-usage-heatmap.

neubrutalism-theme — Neubrutalism Web UI Theme

• Type: bundle + browser client
• Functionality: Applies theme tokens and removable global styles across the Web GUI, including 2px control outlines, 3px container outlines, square corners, zero-blur hard shadows, flat accent surfaces, and button press feedback.
• Fonts: Embeds local WOFF2 files for Syne, Space Grotesk, Inter, and Space Mono, with no browser request to an external font service.
• Standalone repository: MoriTang/dsh-neubrutalism-theme
• Install: Clone the standalone repository, then run pnpm dsh plugin --profile web add /absolute/path/to/dsh-neubrutalism-theme.

codex-enabler — Codex Provider Integration with a Dedicated preset

• Type: bundle (installation script + configuration layer)

• Functionality: Installs the official Codex Provider, configures the Host entry, and creates a copy of the standard-codex agent preset that authorizes subagent_codex only for selected sessions. The official Provider package owns the matching @openai/codex version, so a second runtime is no longer installed.

• Installation:

  node plugins/codex-enabler/install.mjs web
  

• Usage: After restarting the profile, select standard-codex for new sessions. Existing sessions retain their preset and toolset.

• Documentation: plugins/codex-enabler/README.md

tool-audit — Tool-Call Audit (duration / outcome / failure / timeout)

• Type: dual-half plugin (host + client)
• Functionality:
  • Call ledger: Records every model tool call's wall duration and settle outcome (success / failure / aborted / timeout) with a slow-call flag, streamed live into the composer dock.
  • Failures / timeouts visible: red = failure, gray = aborted, amber = timeout/slow; hover for callId and the error code.
  • Optional blanket abort: with abortAfterMs, only tools without their own declared timeoutMs budget are aborted past it (off by default; does not duplicate the official per-tool timeoutMs policy).
• Data channel: the host times calls in tools/execute and commits the authoritative settle from tools/result into an in-memory ledger; the client polls /tool-audit/recent (session-scoped).
• Tests: 16 cases across the pure core and the host integration (tests/*.test.ts).
• Documentation: plugins/tool-audit/README.md

Quick Start

1. Install Dependencies

Each plugin is an independent pnpm project. Its @deepseek-ai/* dependencies use link: to point to the harness checkout:

cd plugins/greet-tool
pnpm install

2. Load a Plugin (Two Methods)

Method A: Hot Loading (Recommended; No Restart Required)

Add the plugin entry to the web profile's user patch layer (~/.dsh/profiles/web/cordis.patch.yml):

- insert:
    - id: greet-tool
      name: '/path/to/this/repo/plugins/greet-tool/src/index.ts'
      config:
        greeting: 'Hello'

While dsh web is running, this file is monitored by config-only HMR. Changes take effect as soon as the file is saved: the plugin is mounted immediately, with no service restart required. Changes to config values also take effect in real time; removing the entry unloads the plugin.

Method B: Load at Startup Using a --patch overlay

cd /path/to/deepseek-harness
pnpm dsh web --patch /path/to/this/repo/plugins/greet-tool/cordis.yml

Note: A --patch overlay is parsed only once at startup. Editing it while the application is running does not trigger hot reloading. For hot loading, use the cordis.patch.yml layer described in Method A.

3. Verify the Plugin

In the Web UI (http://127.0.0.1:3080), ask the model to invoke the greet tool, for example:

Use the greet tool to greet Ada.

The model should receive the tool result Hello, Ada!.

Developing a New Plugin

1. Copy plugins/greet-tool as the starter template.
2. Follow the official tutorials for the plugin module structure (name / inject / apply), the Schemastery Config schema, and ctx.tools registration:
   • Building a Tool Plugin
   • Plugin Configuration
   • Tool Development Reference
3. Run a type check:

cd plugins/<your-plugin>
pnpm exec tsc --noEmit

Known Limitations

• Changes to plugin source code are not hot-reloaded under web: The web profile disables module-level HMR (the hmr entry has disabled: true). After changing src/index.ts, you must restart dsh web. User patches in the profile or Harness home are hot-reloaded; changes to patches included with an installed bundle require a restart.
• Plugins cannot be enabled or disabled from the GUI: The Plugins settings page in the Web UI only renders configuration cards for registered plugins and provides no runtime enable/disable controls.
• There are two loading methods: For source plugins (greet-tool, cost-balance, and usage-heatmap), name in the patch layer must be an absolute path (a patch does not change the module resolution base directory), so it must be updated when moving to another machine; bundle plugins (codex-enabler) are mounted by package name, installed through dsh plugin add, and configured through overrides in cordis.patch.yml.