RFC: dsh-external-stent — repository purpose, architecture, and decision record

English | 中文

• Status: living document (each section records the decision and its history)
• Scope: this standalone Stent extension workspace
• Upstream anchors: deepseek-harness snapshots 7b9644f2 (0812) / 9f9e2782a4 (0813), fork tip 65bcaf9902 (feat-stent)

This document explains why this repository is shaped the way it is. Every non-obvious arrangement below was reached through a concrete failure recorded in the commit history; the sections follow the repository's evolution rather than its file layout.

---

1. Purpose: an external Stent extension, not a fork

deepseek-harness is a private monorepo. The Stent/Mixin extension layer lives there as three implementation packages, but a consumer cannot install them from the registry. This repository externalizes those three packages and publishes the @oh-my-dsh/stent-pack carrier so consumers can install the complete bundle through the official plugin channel:

dsh plugin --profile <p> add @oh-my-dsh/stent-pack

Boundary (hard rule): the workspace contains exactly three complete implementation packages — stent (pure transformation service), stent-api (pure compat facade), and stent-dsh (DSH-facing facades, invariant, profile bootstrap). The root @oh-my-dsh/stent-pack is a separately publishable carrier, not a fourth implementation package. Anything else — including the official @deepseek-ai/dsh-tool-cordis toolset — remains an upstream dependency and is not republished here.

2. Host integration: launcher-provided wiring

The three packages install hooks and mount facades through the compiled launcher. src/stent-dsh.ts compiles to lib/stent-dsh.js, while src/stent-dsh-preload.ts compiles to lib/stent-dsh-preload.js; the launcher injects that compiled preload before the official CLI loads. No host patch checkout is required. The preload also records a process-local stent-dsh launch capability, so Stent-dependent plugins stay unavailable under plain dsh even if low-level hooks were installed by another path. The same capability gate is enforced by getStent(ctx): a plugin that omitted inject: ['stent'] cannot mount the registry through the accessor under plain dsh and fails loudly instead.

Everything the official channels already cover is deliberately excluded: installing the trio (dsh plugin add), bundle roster rows and dependencies, catalog generation, invariant/gate exemptions for trio-in-workspace, and all documentation (README*, docs/, .agents/). What remains is what no channel can provide: launcher bootstrap (apps/cli/src/profile-boot.ts calls installStentBootstrap before any target import and checkStentRequiredPatches after boot), the clientBundle source-transform build seam (packages/client/tsdown.client.ts), catalog entries compiled into the official tool-cordis package, their tests, and the pnpm-policy seams.

2.1 The disabled opt-in rows

The web-app bundle layer inserts stent / stent-dsh rows as disabled opt-ins: the pure stent package is a library with no plugin apply, so an enabled row fails every boot ("invalid plugin"). A profile opts in by enabling the rows; the bundle layer applies on every boot, so pre-existing profiles are covered without edits.

2.2 The TSX dead end (recorded and reverted)

…