dsh-plugin-local-utilities

English | 中文

DeepSeek Harness Cordis plugin for local utility features.

This repository is not a Codex plugin package and does not contain a local skill bundle. It intentionally has no .codex-plugin/plugin.json, no skills/ directory, and no bundled SKILL.md. Instead, it registers a DeepSeek Harness Cordis plugin that can import external GitHub or Markdown SKILL.md files into the Harness skill registry.

It currently provides:

• Windows completion notifications when a root agent becomes idle.
• External GitHub or Markdown skill imports through the Harness ctx.skills registry.

The plugin is loaded by DeepSeek Harness with a cordis.yml patch and does not modify Harness core code.

Requirements

• A DeepSeek Harness developer checkout.
• Node.js ^22.19.0 || >=24.0.0.
• pnpm.
• Windows for desktop completion notifications.
• Network access to api.github.com when loading GitHub-hosted skills.
• A Harness profile that includes the skill consumer, such as the standard Web profile with the built-in skill tool.

Install Dependencies

Install this plugin repository's dependencies before loading src/index.ts from Harness:

cd C:\path\to\dsh-plugin-local-utilities
pnpm.cmd install

Harness imports this plugin from a file:///.../src/index.ts URL. The plugin repository therefore needs its own node_modules/ so imports such as @deepseek-ai/dsh-skill resolve correctly.

Local Harness Usage

Create a local patch file from the example and edit the plugin path:

cd C:\path\to\dsh-plugin-local-utilities
copy cordis.example.yml cordis.local.yml

In cordis.local.yml, replace the placeholder name with the absolute file:/// URL for this repository's src/index.ts:

- insert:
    - id: local-utilities
      name: 'file:///C:/absolute/path/to/dsh-plugin-local-utilities/src/index.ts'
      config:
        externalSkills:
          - name: khazix-writer
            description: Write in a natural human style with less mechanical phrasing.
            url: https://github.com/KKKKhazix/khazix-skills/tree/main/khazix-writer
            whenToUse: Use when the user asks for natural, human-like writing.

This example uses a human-writing skill. Add more external skills to the externalSkills list as needed. Run Harness from the DeepSeek Harness checkout and pass your edited local patch file:

cd C:\path\to\deepseek-harness
pnpm.cmd dsh web --patch C:\path\to\dsh-plugin-local-utilities\cordis.local.yml

You can also run the same Harness command from this plugin repository. The dsh script delegates to a sibling deepseek-harness checkout, or to DSH_HARNESS_DIR when that environment variable is set:

cd C:\path\to\dsh-plugin-local-utilities
pnpm.cmd dsh web --patch C:\path\to\dsh-plugin-local-utilities\cordis.local.yml

If the default port is busy:

pnpm.cmd dsh web --patch C:\path\to\dsh-plugin-local-utilities\cordis.local.yml --port 3082

A successful startup prints:

[local-utilities] loaded

If Harness is already on your machine

If your local DeepSeek Harness checkout is already present, clone this repository next to it and use the default sibling lookup:

C:\Users\admin\Desktop\Development\Projects\Agent\deepseek-harness
C:\Users\admin\Desktop\Development\Projects\Agent\dsh-plugin-local-utilities

Then run:

cd C:\Users\admin\Desktop\Development\Projects\Agent\dsh-plugin-local-utilities
pnpm.cmd install
copy cordis.example.yml cordis.local.yml
pnpm.cmd dsh web --patch C:\Users\admin\Desktop\Development\Projects\Agent\dsh-plugin-local-utilities\cordis.local.yml

If the two repositories are not siblings, set DSH_HARNESS_DIR first:

$env:DSH_HARNESS_DIR="C:\Users\admin\Desktop\Development\Projects\Agent\deepseek-harness"
pnpm.cmd dsh web --patch C:\Users\admin\Desktop\Development\Projects\Agent\dsh-plugin-local-utilities\cordis.local.yml

In both cases, the plugin repository still needs its own pnpm.cmd install so the file:///.../src/index.ts import can resolve local package dependencies.

Calling an Imported Skill

This plugin only registers external skills with ctx.skills. The /skill-name gesture and the model-facing skill tool are provided by Harness's skill consumer, for example @deepseek-ai/dsh-tool-skill. They must be present in the Harness profile you start.

After the plugin is loaded and the Harness profile includes the skill consumer, the configured skill appears in the Harness skill registry.

You can invoke it explicitly in the Web UI:

/khazix-writer

Rewrite this paragraph in a more natural human style:
...

The model can also call the built-in skill tool with the exact skill name when the task matches the skill description.

Configuration

interface Config {
  enabled: boolean
  title: string
  message: string
  balloonMs: number
  rootAgentsOnly: boolean
  externalSkills?: ExternalSkillSource[]
}

interface ExternalSkillSource {
  name: string
  description: string
  url: string
  whenToUse?: string
}

externalSkills[].name must satisfy the Harness skill registry name rule: kebab-case, for example khazix-writer or human-writing. The plugin schema accepts a string, and the Harness registry rejects invalid skill names during catalog loading.

Supported external skill URLs:

• https://github.com/<owner>/<repo> reads SKILL.md from the repository root on the main branch.
• https://github.com/<owner>/<repo>/tree/<ref>/<skill-dir> reads <skill-dir>/SKILL.md from that ref.
• https://github.com/<owner>/<repo>/blob/<ref>/<path>/SKILL.md reads that exact SKILL.md file.
• https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>/SKILL.md reads Markdown text directly.
• Any direct non-GitHub URL returning Markdown text.

GitHub repository URLs are loaded through the GitHub Contents API to avoid depending on raw.githubusercontent.com DNS availability.

Branch or tag names containing / are not supported in GitHub tree or blob URLs because GitHub encodes refs and paths in the same URL path. Use a raw URL or a direct Markdown URL for those refs.

Development

pnpm.cmd install
pnpm.cmd test
pnpm.cmd run typecheck

This repository includes pnpm-workspace.yaml entries for the exact Harness preview packages currently locked in pnpm-lock.yaml, so normal pnpm.cmd test, pnpm.cmd run typecheck, and pnpm.cmd dsh ... commands do not fail only because those packages are recent preview releases. If Windows file access reports EPERM, rerun from a normal user PowerShell outside restricted sandboxes.

For local verification against a sibling DeepSeek Harness checkout, use your untracked cordis.local.yml or create another local patch file with an absolute file:/// plugin path.

Limitations

• External skills are imported at Harness startup from cordis.yml; there is no Web UI dynamic import command yet.
• Repository-root GitHub URLs always resolve main/SKILL.md.
• GitHub tree and blob URL parsing does not support refs containing /.
• GitHub skill loading requires api.github.com access.
• Windows notifications use powershell.exe and System.Windows.Forms, so they are Windows-only.