dsh-extension-ops

简体中文

dsh-extension-ops is an experimental project. It tests whether a compact,
on-demand Skill plus version-exact facts can make DSH extension work faster
and use fewer tokens than letting a model scan packages or guess from READMEs.

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.

Archived. The experiment asked whether a compact Skill plus version-exact
facts could beat scanning packages for speed and token cost. Comparable
A/B runs did not show those gains. No further work planned. npm stays
unpublished.

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

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

Optional, only if you want to run the experiment inside a local profile.

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 the experiment: same model and artifact, baseline versus treatment,
with recorded wall time and tokens. It does not prove an extension will boot
in DSH. Current comparable runs have not shown a speed or token win.

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

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

Codex is optional. When Codex credits are unavailable, the same auditor can
score a DeepSeek run through the Codex-compatible backend:

pnpm exec tsx tools/run-agent-eval.ts --execute \
  --scenario real-icon-theme-mixed-boundary \
  --model deepseek-chat \
  --subject-artifact /path/to/pinned/dsh-icon-theme-0.1.0.tgz \
  --project-snapshot sha256:<pinned-archive-sha256> \
  --reasoning medium \
  --codex ./tools/deepseek-eval-backend.mjs \
  --output /tmp/dsh-extension-ops-eval

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

License

MIT