AGENTS.md

Out-of-tree DeepSeek Harness plugin (host + Web client bundle): form-level and file-level configuration management with an open registration SDK. Self-contained repository — every source, compiler, documentation, and project-reference path stays below this root; lib/ is committed and kept in sync with source.

Layout

src/index.ts            host entry: function plugin (name/inject/Config/apply, no default export)
src/config.ts           serializable schema + direct-call defaults (message only)
src/runtime.ts          Cordis activation + host-boundary wiring (ctx.dshSettingsPlus, fabric binding)
src/crawler.ts          read-only enumeration: listNamespaces (settings.describe, redacted) / listCompositionConfigs (registry rows)
src/service.ts          the dshSettingsPlus host service: reads delegate to the crawler, writes route through the settings seam with expectedRevision guards
src/fabric.ts           optional gateway exposed-namespaces widening (loaded from host context at binding time; three-posture)
src/sdk.ts              open registration SDK: registerUserSettings / defineSettingsSection / settingsNamespace brand + ./sdk export
src/file-browser.ts     closed writable manifest ($DSH_HOME root yml/yaml + profiles/<name>/cordis*.yml) + realpath boundary; never writes
src/file-store.ts       atomic reads/writes through the injected FsLike channel, byte caps, expected-version write guard
src/yaml-editor.ts      comment-preserving YAML round-trip
src/patch-validator.ts  semantic validation that rejects patch edits breaking the document
src/hmr-aware.ts        save strategy copy: the host owns reloading, this plugin never suggests a restart
src/invariant.ts        invariant companion (documented empty installer — see its reason comment)
src/client/             browser half, served as the single file lib/client.js
  index.ts              settings.section registrations: entry (order 30) + three-phase status row + per-entry sections, signature-diff reconcile
  catalog.ts            observable catalog store + injectable settingsPlusCatalog source seam
  component.tsx         entry / status-row / data-section components
  schema-form.tsx       generic schema form renderer (whitelisted controls, secret placeholder protocol, reset, conflict, restart notice)
  form-logic.ts         pure form logic: path ops, secret placeholder decisions, conflict classification
  locales.ts            zh/en dictionaries; zh is the key-set source of truth, en satisfies Record<keyof typeof zh, string>
tests/                  node-env host specs + jsdom client specs (client.spec.ts, schema-form.spec.tsx, form-logic.spec.ts, …)

Contracts with the harness (do not drift)

• The crawler and the SDK consume the host settings seam through minimal local contracts, never an import of the host package: crawler calls only ctx.settings.describe({ redactSecrets: true }), the SDK only ctx.settings.register(...). There is no second enumeration surface — the host settings service is the single arbiter of registered namespaces, and duplicates fail loud at register time.
• listCompositionConfigs reads live ctx.registry rows: only rows whose Config exposes toJSON (schemastery) and whose fibers carry a string row id are surfaced; secrets are stripped by the schema-walking redactValue.
• The dshSettingsPlus write boundary is narrow by design: updateComposition/removeComposition accept only ids that are registered settings namespaces. Plain cordis.yml rows are rejected loudly — file-surface or cordis.patch.yml is the answer.
• cordis.patch.yml carries three rows: dsh-settings-plus, dsh-settings-plus-invariant, and a disabled cordis-fabric stub. The Fabric binding is optional: no facade mounted → safe no-op; facade mounted but malformed → loud error. Never edit the patch or the binding without updating src/fabric.ts together.
• The file surface never touches anything outside the writable manifest: file-browser.ts enumerates, every write path goes through isWritableTarget + realpath boundary, and the file store adds byte caps and an expected-version guard. No file creation, deletion, or rename — ever.
• The client composes only through standing seams: ctx.slots.inject('settings.section', ...) with declaration-aware deferral, ctx.locale.register, and the settingsPlusCatalog source seam. Section registration uses signature diffing (${key}\u0000${label}): unchanged signatures are reused, anything else is disposed and rebuilt. The catalog production default is the honest local empty source until the host wire surface lands.
• The schema form's secret placeholder protocol is fixed: placeholders never travel, empty input keeps the stored value, only explicit input commits; per-field reset uses unset ops, never value-bearing writes. Revision conflicts surface a reload prompt (form.conflict).
• Locale keys: src/client/locales.ts is the key-set source of truth; any new copy the client renders must be added to both dictionaries (the en side is compile-checked against zh). Chinese is the product copy; code comments, JSDoc, and the English README are English.

Check ladder

pnpm run typecheck and pnpm test must be green before every commit, then pnpm run build (which also regenerates lib/), and finally pnpm run verify:self-contained (rejects dependency specs, out-of-repo paths, external/broken Markdown links, absolute workstation paths, and malformed skill metadata). pnpm run prepare regenerates consumer artifacts for Git/tarball installs. Keep lib/ committed and in sync: any source change that alters built output lands with its lib/ regeneration in the same commit.

Commit discipline

• Conventional commits (feat:/fix:/docs:/build:/chore:) with a body: what and why.
• One concern per commit; run the full check ladder before committing; never commit node_modules/, logs, or credentials.