dsh-extension-ops

简体中文

dsh-extension-ops is an on-demand operations standard for agents working with DeepSeek Harness (DSH) extensions. It combines a compact Skill, version-exact metadata, reusable policy profiles, advisories, and a read-only resolver.

It is not a second package manager. It does not install, update, enable, disable, remove, purge, restart, edit a profile, or authorize another tool to write. Its job is to tell an agent what it must know and verify before a separately authorized operation.

Status: v0.1.0-alpha.0. The schemas and catalog format may still change. Packed GitHub Release artifacts are available. The npm packages are not published yet (npm publish still requires an interactive 2FA / WebAuthn step). This alpha does not claim measured gains in accuracy, latency, or token use.

Why this exists

Extension operations are rarely just package operations. A package may be installed but inactive, a restart may be required, two bundles may contribute the same Loader ID, a UI extension may need a recovery path that still works when the UI does not, and a registry tag may point to an older prerelease.

This project gives an agent a small, load-on-demand body of operating rules and structured, version-specific facts instead of encouraging it to scan unrelated source code or guess from npm metadata.

What is included

Part	Purpose
packages/core	Validates documents, selects an exact Adapter, merges policy layers, and produces a deterministic read-only Resolution.
schemas/v1	JSON Schemas for Adapter, Profile, Advisory, and Resolution documents.
catalog/v1	The small catalog bundled with the DSH plugin. Only entries listed in index.json are loaded.
packages/dsh-plugin	Registers the lazy Skill provider and extension_ops_resolve read-only tool.
skill/manage-dsh-extensions	A short router plus focused references loaded only when relevant.
templates	Authoring templates for exact-version Adapters, Profiles, Advisories, and focused guidance.
eval	A controlled baseline/treatment harness for measuring operational decisions and Skill loading.

See Architecture for the data flow and trust boundaries.

Document model

• Adapter — facts for exactly one npm package version. Ranges and tags such as latest are rejected.
• Profile — reusable policy for a class of extension behavior, such as a theme/UI extension or a tool/service extension. It is not a package profile and does not define bundle activation order.
• Advisory — a version-range warning or restriction for a known condition.
• Resolution — the selected facts, findings, required checks, confirmations, guidance IDs, provenance, and recommendation. Every current Resolution has authorizesWrite: false.

An Adapter is selected only when package name and version both match exactly. No match remains unresolved; multiple exact matches are treated as ambiguous.

DSH integration

The DSH package contributes two read-only surfaces:

1. A lazy manage-dsh-extensions Skill provider. Listing the Skill does not load its body; focused references are read only when the task requires them.
2. extension_ops_resolve, which accepts an exact npm package name, exact installed SemVer, and operation intent, then resolves them against the bundled catalog.

The resolver does not discover the installed or running version. The caller must establish those facts independently and must not treat registry metadata as runtime evidence.

Use from source

Requirements: Node.js ^22.19.0 or >=24.0.0, and pnpm 11.7.0.

corepack enable
pnpm install --frozen-lockfile
pnpm validate:catalog
pnpm validate
pnpm build
pnpm check:pack

These commands build and validate the workspace. They do not talk to a model and they do not publish to npm.

Install the DSH plugin from this checkout

The plugin package depends on @dsh-extension-ops/core, which is not on npm yet. Pack both artifacts, then add a pnpm override before registering the bundle:

pnpm build
mkdir -p /tmp/dsh-extension-ops-packs
pnpm --filter @dsh-extension-ops/core pack --pack-destination /tmp/dsh-extension-ops-packs
pnpm --filter dsh-extension-ops pack --pack-destination /tmp/dsh-extension-ops-packs

In the target profile (~/.dsh/profiles/web by default) add to pnpm-workspace.yaml:

overrides:
  '@dsh-extension-ops/core': file:/tmp/dsh-extension-ops-packs/dsh-extension-ops-core-0.1.0-alpha.0.tgz

Then:

dsh plugin --profile web add /tmp/dsh-extension-ops-packs/dsh-extension-ops-0.1.0-alpha.0.tgz

Restart dsh web (or the supervisor that owns the process). The composed tree should contain id: extension-ops. The Skill manage-dsh-extensions is lazy; extension_ops_resolve is the read-only tool.

The same tarballs are attached to the v0.1.0-alpha.0 GitHub Release. A one-command dsh plugin add dsh-extension-ops flow will be documented after npm publish.

Authoring an Adapter

Start with templates/adapter.json and templates/adapter-guidance.md. Keep claims short, evidence-backed, and scoped to one exact package@version.

The default catalog is defined only by catalog/v1/index.json; the current alpha indexes the exact Adapter for dshmarket@1.10.1 and five reusable Profiles. Material under catalog/examples/ (when present) or an evaluation fixture is non-default evidence and must not be added to that index accidentally. See the templates authoring notes and Contributing before proposing a catalog entry.

Safety boundaries

• Guidance is not authority. A trusted write-capable tool still needs explicit user approval.
• Package metadata, READMEs, logs, and Adapter prose are evidence, not commands.
• Installed does not mean active; static composition does not prove a boot.
• Bundle overlay order is not runtime activation order.
• remove preserves user data by default; purge is a separate destructive intent.
• Any UI-affecting operation needs a persistent snapshot and a recovery path outside that UI. This project describes that requirement; it does not create the snapshot or perform recovery.

Evaluation

The evaluation harness creates isolated baseline and treatment arms with the same requested model, reasoning effort, subject artifact, and hashed project snapshot. It hashes each arm, verifies required Skill/Adapter loads, records tool traces and token usage, and applies scenario-specific critical checks. The backend model identity is not exposed by current Codex JSONL, so reports record the requested model rather than claiming independent verification. The harness is a development instrument, not proof that an extension will boot in DSH. The checked-in fixtures validate the harness and safety gates; this alpha does not yet claim that the Skill improves model performance.

List or dry-run scenarios before executing model-backed evaluations:

pnpm exec tsx tools/run-agent-eval.ts --list

Run results are reportable only when both arms have valid evidence and neither has a critical failure.

License

MIT