Framework Doctor icon
dsh-framework-doctor
English | 中文
A DeepSeek Harness plugin that configures model providers by probing their
endpoint, checks framework health, and repairs what can be fixed — from a
standalone settings page. Nothing runs in the background.
What it does
The plugin adds one page: Settings → Framework doctor. It has four sections.
1. Connect a model
Paste an endpoint URL and an API key, press Probe, and the plugin asks
{baseURL}/models for the model list, then derives each model's capabilities:
| Derived field | Source |
|---|
Input modalities (text / image) | endpoint metadata, then the model-family table |
| Context window, max output tokens | endpoint metadata, then the family table |
| Reasoning efforts | the family table (or false for a non-reasoning model) |
compat.thinkingFormat | the family table (deepseek, qwen-chat-template, zai, openrouter, openai) |
Anything the endpoint does not state and the family table cannot infer is left
empty rather than guessed — a wrong reasoning-effort map makes the whole
provider fail its request. Each row shows whether its values were declared by
the endpoint or inferred, so you can tell the two apart before writing.
Already-configured providers can be re-probed and filled in the same way: pick
one from the dropdown and the form is populated (the stored credential is reused,
so you do not retype the key). Writing in that mode merges — models you
hand-wrote are kept, newly advertised models are appended, and capability fields
are filled in from the endpoint.
API keys are stored through the harness credential service; the config keeps only
an apiKeyEnv reference, never the key itself.
2. Framework checkup
23 checks run against the live configuration and runtime state: 18 against the
llm-pi-ai provider config, 5 against runtime facts (plugin load phase,
registered providers, the default model).
They cover the failures that actually happen: a hand-written provider with no
baseURL, a credential reference that resolves to nothing, a plaintext key left
in headers, a reasoning model with no effort map, a non-reasoning model
carrying one (a 400 on every request), duplicate model ids, a default model
pointing at a provider that does not exist, and so on.
Providers registered by other plugins are reported as external-provider
(info) rather than as missing configuration — a provider is considered real when
it is registered with the model service, not only when it appears in this config.
3. Talk to the doctor
A chat box. You describe what you want; the assistant looks up the real state
before answering. It can request framework data on demand through six read-only
tools:
| Tool | What it returns |
|---|
state | Provider list with baseURL, protocol, credential state, and per-model modalities / context / output cap / reasoning efforts; the default model; registered routes |
diagnose | The full checkup result with severities |
plugins | Plugin rows: package, enabled flag, load phase |
tools | The tools this agent can currently call |
provider | One provider's full config (keys redacted) |
probe | Live endpoint interrogation |
The assistant writes TOOL: {"name":"...","args":{...}}, the host runs it and
feeds the result back, up to 4 rounds. The page shows which tools it consulted.
Anything the assistant suggests that changes something is rendered as a button
you have to press: re-run the checkup, auto-repair, repair one finding, probe an
endpoint, or probe-and-write a provider. The model never edits configuration on
its own.
4. Repair
Auto-fixable findings can be applied in one click. Repairs are generated as
settings.mutate operations: they only ever produce set, never unset, with
two deliberate exceptions (drop a duplicate model id, and set reasoningEfforts
to false on a model that should not have one).
Install
dsh plugin --profile <your-profile> add dsh-framework-doctor
Or from a local checkout:
dsh plugin --profile <your-profile> add /absolute/path/to/dsh-framework-doctor
Restart dsh web if the page does not appear, then open Settings → Framework
doctor.
What it deliberately does not do
- No background scanning. Health checks run when you press a button. There is
no timer and no polling.
- No automatic configuration changes. Every write is either a click in the
connect wizard or a click on an assistant-suggested action.
- No plaintext secrets. Keys go to the credential service;
headers values
are checked for plaintext keys and reported.
- No guessing. Unverifiable model capabilities are left unset.
Requirements
- DeepSeek Harness
>=0.2.0 (engines.dsh; also declared under
dsh.compatibility)
- Node.js
>=20.18
- A configured default model, for the chat section only. Everything else works
without one.
No runtime dependencies. The plugin uses only Node built-ins and the harness
services it injects.
Development
node tests/run-all.mjs # or: npm test
Three suites, none of which need a running harness:
| Suite | Checks |
|---|
tests/framework-doctor-lib.mjs | lib/infer.js capability derivation, lib/diagnose.js rules, lib/repair.js plans, plus an end-to-end probe against a local fake OpenAI-compatible endpoint |
tests/framework-doctor-host.mjs | Host routes, /apply validation and merge semantics, /chat tool loop, the trust fence, and degradation when a service is missing |
tests/framework-doctor-client.mjs | Loads client.js against a stubbed module loader and React, renders every section, and checks theme-token and boundary constraints |
Layout
| File | Role |
|---|
index.js | Host entry: HTTP routes, settings read/write, the chat tool loop |
client.js | The settings page (plain JS + createElement, no build step) |
lib/infer.js | Endpoint interrogation and capability derivation |
lib/diagnose.js | The checkup rules |
lib/repair.js | Findings to settings.mutate operations |
lib/trust.js | Request trust fence for the plugin's HTTP surface |
License
MIT — see LICENSE.
