dsh-glob-rules

dsh-glob-rules

English | 中文

Glob-activated rule prompts for DeepSeek Harness (DSH) — a Claude Code rules.md / # Path:-style mechanism. Each rule declares glob patterns; when the agent reads or edits a matching file, the rule activates and its content (any prompt or markdown document) is injected into the conversation as a superseding <rules> snapshot.

A TypeScript re-creation of dsh-rules with the same behavior, written against the current plugin development guide and the installed framework surface (cordis 4.x, dsh-* rc packages). The one breaking API change versus the original: session history is now read through session.snapshotEvents() — the old session.events array no longer exists — and the package ships TypeScript compiled with tsc like today's plugins.

Works in every DSH deployment: desktop / web / tui / headless / custom profiles — nothing about this plugin is desktop-specific.

Contents

• Features
• How it works
• Installation
• Rule format
• Configuration
• Discoverability
• Development
• License

Features

• Glob activation — rules activate per file the agent touches: **, *, ?, {a,b}, [abc], and ! negation (picomatch).
• Claude Code compatible — plain rule files (.dsh/rules/*.md) and # Path: sections inside CLAUDE.md / AGENTS.md.
• Visible & durable — active rules are injected as a user message the UI shows and the session log persists; each snapshot supersedes earlier ones, so the model always sees the current set.
• Session-format-v4 source contract — every snapshot declares a producer-owned message source ({ kind: 'dsh-glob-rules', form: 'instructions' }). The retired shared { kind: 'plugin', plugin: … } wrapper that DSH 0.1.7+ (session format v4) refuses — it aborts the whole turn with "format v4 message requires a producer-owned source kind" — is never emitted, while snapshots an older runtime logged are still recognized when seeding on resume.
• Budget-bounded — byte-budget rendering (32 KB default): low-priority rules are dropped first, then the last rule is truncated; content is escaped so it can never break out of the framing tags.
• Resume-friendly — on session resume the last snapshot and its matched files are restored from the log (session.snapshotEvents()), preventing duplicate injection.
• Per-session tracking — every agent/session tracks its own touched files (subagents included); global rules (no path:) are always active.

How it works

workspace
  .dsh/rules/*.md    ← rule definitions (frontmatter declares globs)
  ~/.dsh/rules/*.md  ← user-level rules (optional)
  AGENTS.md/CLAUDE.md ← optional: # Path: sections (Claude Code compatible)

agent reads/edits a file (fs/observed) → record per-session touched path
  ↓ every step (agent/pre-step)
match touched paths against globs → collect active rules → render a <rules> snapshot into the conversation

• Injection point: an agent/pre-step waterfall listener appends a <rules>-framed user message carrying this plugin's own source kind; a new message is only appended when the snapshot text changes.
• Discovery & caching: rule sources are re-probed per step with version caching (fs.stat().version, or mtimeMs:size on the Node fallback) — edits to rule files take effect on the next step.
• Reads: prefer the harness fs service (containment-aware); fall back to Node's filesystem when no fs service is mounted.

Installation

Published as a DSH bundle (declares dsh.bundle.patch), so dsh plugin installs and activates it in one step:

# Adjust the profile name: desktop / web / tui / headless
dsh plugin --profile desktop add dsh-glob-rules

The reconcile pass appends dsh-glob-rules to the profile's dsh.profile.bundles layer list automatically — no manual cordis.patch.yml edits are needed. Restart DSH (restart the desktop app; restart the web/headless process) and the plugin loads with the next Cordis composition.

Installing from a local checkout or a git host (development): the package ships a prepare script that builds lib/ from src/ with tsc, so dsh plugin --profile desktop add . (or add github:you/dsh-glob-rules) works too. pnpm ≥10 asks you to allow the git dependency's prepare script first — copy the exact package key pnpm prints into the profile's pnpm-workspace.yaml under allowBuilds, then re-run the add.

Per-profile configuration (optional): the plugin loads with its code defaults; to customize, override the entry's config in <profile>/cordis.patch.yml:

- id: dsh-glob-rules
  name: dsh-glob-rules
  config:
    includeClaudeSections: true
    projectRootMarkers: [".git", ".dsh"]

Remove: dsh plugin --profile desktop remove dsh-glob-rules, then restart.

Rule format

Source A: rule files (.dsh/rules/*.md and ~/.dsh/rules/*.md)

---
path:
  - "src/**/*.ts"
  - "!src/**/*.test.ts"
---
Rule body (markdown, injected verbatim when active — any prompt content works)

Source B: # Path: sections (requires includeClaudeSections: true)

Parses # Path: <globs…> headings out of AGENTS.md / CLAUDE.md (including .local.md variants and ~/.dsh/AGENTS.md):

# Project notes (content before the first heading is handled by the built-in agent-instructions baseline, not by this plugin)

# Path: src/**/*.ts, scripts/**
This section activates only when a file under src/**/*.ts or scripts/ is touched

• Each # Path: heading starts a rule that runs until the next heading (or end of file).
• Globs may be comma- or space-separated.
• Content before the first # Path: heading is intentionally not injected by this plugin — DSH's built-in agent-instructions already injects the full AGENTS.md/CLAUDE.md baseline.

Precedence & deduplication

Project rules (rank 100) > user rules (rank 200) > # Path: sections (rank 300). Same-name rules keep the highest-priority entry; rendering order is (rank, name) — deterministic across steps.

Configuration

Discoverability

This plugin is discoverable through the GitHub dsh-plugin topic — the channel recommended by the DeepSeek Harness README ("Community and support": Add the dsh-plugin topic to your plugin repository for discoverability). Community plugin lists and marketplaces (e.g. awesome-dsh-plugin, dsh-plugin-marketplace) scan that topic to pick up new plugins; the tag can be viewed/edited in the repository's About section.

Development

pnpm install
pnpm run check   # typecheck + build (tsc)
pnpm test        # node --test: parsing / glob matching / precedence / budget / determinism / fs fallback

Layout:

• src/index.ts — plugin entry (name / Config / apply): fs/observed touch tracking, agent/pre-step injection, agent/disposed cleanup, resume seeding from session.snapshotEvents().
• src/rules.ts — pure logic: frontmatter and # Path: parsing, glob compilation/matching, precedence merging, budget rendering.
• src/fs.ts — versioned discovery/reads: harness fs service first, Node fallback.
• test/rules.test.mjs, test/apply.test.mjs — unit + apply-level tests (run against the compiled lib/).
• examples/.dsh/rules/ — sample rules (copy into your project to get started).
• fixtures/demo-project/ — a ready-made project for trying the plugin out.

License

MIT — includes attribution to the original dsh-rules this project ports.