Introduction

In DeepSeek Harness (DSH) development, managing the knowledge-base health, context injection, and navigation logic of agent runs often requires writing a lot of repetitive hook logic. Directly capturing raw hooks in individual plugins can easily lead to dependency confusion and difficult state management.

@catheadowl/dsh-extras is a DSH plugin suite designed to provide a composable base framework by encapsulating common DSH hooks, along with Markdown tools and routing capabilities to address documentation maintenance and context management issues.

What Is This

This is a collection of DSH plugins maintained by CatheadOwl, installed at once using the dsh plugin add command. It encapsulates two common hooks into service interfaces (ctx.gates and ctx.enrichment) instead of having each plugin directly capture low-level hooks, thereby providing structured quality gating, context enrichment, Markdown file renaming, and knowledge-base routing.

Core Features

The suite contains four independently toggleable modules:

  • Quality Gating Framework (gates): Runs automatically at the end of a turn. Developers register gate logic through the ctx.gates interface. Module ID is gates.
  • Context Enrichment Framework (enrichment): Runs during the agent/pre-step phase. It is a provider registry that converts path mentions into budget-limited relevant context. Module ID is enrichment.
  • Markdown Tools (markdown): Provides the md_rename tool (moves a Markdown file and rewrites all internal links) and the doc-link gate, with a built-in link transaction library. Module ID is markdown.
  • Knowledge Routing Tools (routes): Provides the any_nav tool (creates a routing view over a Markdown knowledge base) and breadcrumb-related providers. Module ID is routes.

Installation and Activation

Installation requires the dsh CLI. All runtime dependencies are provided by the DSH host.

dsh plugin add @catheadowl/dsh-extras

After installation, all modules appear as a composition row. You can control modules independently by disabling specific rows without affecting other modules.

Configuration and Usage

Disabling a Module

Disable a specific module through the configuration layer:

- id: gates
  disabled: true

Configuring Enrichment Timeouts

The enrichment module supports timeout configuration parameters:

- id: enrichment
  config:
    providerTimeoutMs: 2000
    totalTimeoutMs: 5000
    renderBudgetChars: 4000

Gates Safety Valve Configuration

The gates module includes a safety valve option, maxConsecutiveBlocks (default value is 3). When the consecutive block count is exhausted, the gate degrades to pass-through. This serves only as a safety valve, not a correctness guarantee.

Development and Testing

If you need to perform secondary development or verify the code, you can use the following commands:

# 从仓库根目录运行
pnpm run build                  # 构建四个模块库及客户端包
pnpm run test:gates             # 运行门控模块的单元测试
pnpm run verify:package-face    # 验证导出接口

Notes

  1. Runtime environment: The plugin depends on the DSH CLI, and all runtime dependencies are provided by the host.
  2. State isolation: Modules do not share state with one another. They can be disabled independently without affecting each other.
  3. Web configuration limitation: The Web configuration page currently supports only the gates and enrichment modules.
  4. Documentation language: The project root README is bilingual (English + Chinese). Module documentation and in-depth documentation are Chinese-first.
  5. Version management: Adding or removing modules is implemented through package version upgrades and dsh plugin update.