dsh-plugin-thinking-api
DeepSeek Harness plugin: configure any OpenAI-compatible API in one block and get thinking mode for free — while dodging the developer-role rejection that breaks such APIs.
What it solves
Three problems in one plugin:
- Configure any OpenAI-compatible API in one block — Tencent CodeBuddy, self-hosted vLLM, or any relay — no hand-writing
reasoningEfforts, thinkingFormat, or pi-ai provider internals.
- Thinking mode out of the box — set
thinking: true on a model and it gains reasoning levels automatically.
- Fixes the
content_filter / developer-role bug — this is the subtle one.
The bug this fixes
When a model declares reasoning, pi-ai rewrites the system prompt into the OpenAI developer role unless it recognizes the endpoint as a non-standard vendor. Third-party APIs that are not on pi-ai's built-in allowlist (Tencent CodeBuddy is a prime example) therefore receive a developer message, which many endpoints hard-reject with content_filter — while the exact same request using system succeeds.
The official dsh-llm-pi-ai adapter drops the compat.supportsDeveloperRole field when it builds models, so you cannot fix this from settings.yaml alone. This plugin builds the pi-ai models itself and injects compat.supportsDeveloperRole: false directly, forcing the system role.
How it stays maintainable
The plugin reuses the official PiAiAdapter class (exported by @deepseek-ai/dsh-llm-pi-ai): its streaming, chunk translation, credential resolution, idle-timeout watchdog, and image handling all keep evolving with DSH. This plugin only owns the small "model/provider assembly" layer where the correct compat is written in.
Install
Add to your profile's package.json dependencies and bundle list:
// ~/.dsh/profiles/<profile>/package.json
{
"dependencies": {
"dsh-plugin-thinking-api": "github:qjf44/dsh-plugin-thinking-api"
},
"dsh": {
"profile": {
"bundles": [
// ... your existing bundles ...
"dsh-plugin-thinking-api"
]
}
}
}
Then reinstall and restart the Harness. The plugin's cordis.patch.yml registers itself (insert: [{ id: thinking-api }]), so no manual cordis.patch.yml edit is needed.
Configure
Add a thinking-api section to ~/.dsh/settings.yaml:
thinking-api:
providers:
codebuddy: # route id (any unique name)
displayName: CodeBuddy # optional, shown in pickers
baseURL: https://copilot.tencent.com/v2
apiKeyEnv: CODEBUDDY_API_KEY # env-var reference; store via the Web Models page or export it
thinkingFormat: deepseek # optional, default deepseek
models:
deepseek-v4-pro:
name: DeepSeek V4 Pro
thinking: true # ← enables thinking mode
deepseek-v4-flash:
name: DeepSeek V4 Flash
thinking: false
deepseek-v4.1-flash:
name: DeepSeek V4.1 Flash
thinking: true
input: [text, image] # ← declares vision; makes read_image usable
Store the key (never paste raw keys into the config):
# either export it in the launching environment
export CODEBUDDY_API_KEY=ck_xxxxxxxx
# or write it through the Web UI → Models page (credentials service)
Restart, then pick your API's models from the model picker.
📄 Ready-to-copy configs (CodeBuddy / self-hosted vLLM / any OpenAI-compatible relay): see examples/settings.yaml.
One-click setup in the Web GUI
The plugin also registers a Settings → Thinking API panel with a single setup wizard. Open it to connect an API without touching YAML:
- Source — pick a template (CodeBuddy / DeepSeek / OpenRouter / …) or Custom.
- API key — paste it once. Templates ship sensible default models, so you can save immediately and start chatting.
- Models (optional) — click Fetch models to list the endpoint's models; the wizard pre-flags reasoning models by name (and you can adjust each one with a checkbox). Or add model ids manually.
Tencent CodeBuddy (copilot.tencent.com) has no OpenAI-compatible /models endpoint; Fetch models falls back to the template's default models instead of failing with 404. On other endpoints a 404 means you should enter model ids manually.
- Save — done. The provider appears in the model picker and uses the fixed adapter (
supportsDeveloperRole: false).
Existing providers can be edited (the Edit button reloads them into the wizard) or removed.
The client half ships as a browser bundle discovered through exports["./client"]; after changing plugin source, rebuild the Web artifacts so this URL picks up the new bundle.
Configuration reference
Provider (per providers.<id>)
| Field | Type | Required | Default | Meaning |
|---|
baseURL | string | ✅ | — | API endpoint base URL |
apiKeyEnv | string | — | — | Env-var name holding the API key |
displayName | string | — | route id | Name shown in pickers |
thinkingFormat | enum | — | deepseek | deepseek | openai | openrouter | together | zai | qwen | string-thinking |
models | dict | ✅ | — | Model id → model entry |
Model (per models.<id>)
| Field | Type | Required | Default | Meaning |
|---|
name | string | — | model id | Display name |
thinking | boolean | — | false | Enable reasoning levels |
thinkingEfforts | dict | — | auto | Custom level → wire-value mapping, e.g. { off: null, high: high, max: xhigh } |
contextWindow | number | — | 262144 | Context window size |
maxTokens | number | — | 32768 | Max output tokens |
input | array | — | ["text"] | Input modalities: ["text"] or ["text","image"]. Only a model declaring image is treated as a vision model by DSH (making read_image usable) |
When thinking: true and no thinkingEfforts is given, the plugin fills a verified DeepSeek-compatible level map (off / high / max, mapping to disabled / reasoning_effort: high / reasoning_effort: xhigh). Provide thinkingEfforts to add levels (low/medium) or override per API.
About input / image support: DSH's read_image refuses any route that does not declare image (model "..." does not declare image input), and this plugin registers every model as text-only by default. To let a model see images, declare input: [text, image] — e.g. Tencent CodeBuddy's deepseek-v4.1-flash, which is the official natively-multimodal V4.1 Flash. An empty array is synonymous with omitting the field and falls back to ["text"].
This is a declaration only: it does not guarantee the upstream endpoint accepts images. If the endpoint rejects them, you will see an error when an image is actually sent; conversely, if the endpoint supports images but you never declare them, images are blocked locally and never leave your machine.
Why not llm-pi-ai?
The built-in llm-pi-ai adapter already supports custom APIs. It just cannot express supportsDeveloperRole (its compat schema omits the field and its resolver drops it), so thinking-mode models on allowlist-less APIs hit the developer-role rejection. This plugin exists purely to inject that one missing bit, while reusing everything else.
Supported DSH
Built against DSH 0.1.0-rc.6 through 0.1.5-rc.1 (@deepseek-ai/dsh-llm-pi-ai), pi-ai ^0.82.1. The plugin defensively reuses PiAiAdapter's constructor shape; if a future DSH changes that internal contract, the plugin fails with a clear error rather than silently misbehaving — check the release notes before upgrading DSH.
DSH 0.1.5 compatibility. 0.1.5 moved several internal contracts; versions ≤ 0.1.2 break on it. v0.1.3–v0.1.5 fix them in turn (see the changelog for the full detail):
| Symptom on DSH 0.1.5 | Root cause | Fixed in |
|---|
Failed to load plugins at boot | dsh.client.inject still declared the removed @deepseek-ai/dsh-client-runtime | v0.1.3 |
Settings panel: Cannot read properties of undefined (reading 'settings') | connection no longer exposes .api; reads must go through ctx.remote.* | v0.1.4 |
Model picker: CodeBuddy 加载失败: Cannot read properties of undefined (reading 'get') | 0.1.5 pi-ai modelOf() reads profile.modelErrors, which the plugin's hand-built profile omitted | v0.1.5 |
After upgrading DSH, CodeBuddy / third-party APIs stop working? Run the compat check
The plugin depends on several internal contracts of pi-ai and DSH (provider auth shape, PiAiAdapter constructor, llm service registration methods). These are not covered by semver. So after every DSH (or pi-ai) upgrade, if models suddenly fail with Provider is not configured, content_filter, or MISSING_CREDENTIAL, run the compat check first:
# from the plugin repo (DSH workspace is auto-detected upward; pass --workspace when needed)
node scripts/check-compat.mjs --workspace ~/.workbuddy/binaries/node/workspace
It verifies, item by item: the plugin imports under the real dependencies, the PiAiAdapter constructor shape, the pi-ai provider auth shape, the llm service registration methods, and the settings/credentials helpers. All ✓ means you can keep using it; any ✗ means the plugin needs an update (each failure names the changed contract and where to fix it).
Incident log (2026-09-12, images silently failing)
A user reported that CodeBuddy's deepseek-v4.1-flash could not read images. The verdict was the plugin, not the model:
- Symptom.
read_image on any picture failed with model "<id>" does not declare image input; switch to an image-capable model to read images. Note this refusal happened before any network request was made.
- Root cause.
buildModel() hard-coded input: ['text'], and dsh-llm-pi-ai maps that verbatim onto inputModalities; dsh-tool-fs's read_image then refuses any route that does not declare image. So the image was dropped locally — the upstream being natively multimodal made no difference. The model-entry schema had no input field at all, so users could not work around it from settings.yaml.
- Fix. Added an optional
input field (defaulting to ['text'], so existing behavior is unchanged) and made buildModel read it; an empty array is synonymous with omitting it, matching upstream declaredInput semantics.
Lesson: "the model doesn't support it" and "the route never declared it" are different failures. When debugging vision, check the local capability declaration (inputModalities) before suspecting the endpoint — the former blocks images locally, the latter errors server-side, and the two are fixed in completely different places.
One more deployment trap worth remembering: a file: dependency in the profile is a copy, not a symlink. Editing the plugin repo without re-running pnpm install leaves the profile's stale copy untouched and the change silently inert.
Incident log (2026-09-11, DSH 0.1.1-rc.2 → 0.1.5-rc.1)
Three contracts moved at once, each surfacing only at a different layer — which is why a "server boots fine" check misses them:
- Client bundle preload (
Failed to load plugins). 0.1.5 dropped @deepseek-ai/dsh-client-runtime, but the plugin still declared it in dsh.client.inject, so the loader missed the module and the whole plugin graph failed. createSnapshotStore also moved to the built-in seed module @deepseek-ai/dsh-client-store. Fix: drop the runtime from inject; import the store from the seed module.
- Renderer data layer (
reading 'settings'). connection no longer carries .api; the settings/credentials/llm reads had to move to the cordis namespace services ctx.remote.settings / ctx.remote.credentials / ctx.remote.llm. Note the client bundle is served per request with a content-hash rev, so this half takes effect on a page reload — no host restart needed.
- Host profile shape (
reading 'get'). 0.1.5's pi-ai modelOf() unconditionally evaluates profile.modelErrors.get(model). The plugin builds its profiles by hand (it cannot reuse the official resolveProfiles, which has no userAgent/compat.supportsDeveloperRole hook), and that hand-built object predated the field — so modelCatalog enumeration threw for the whole provider group. listModels alone uses getModels() and stays safe, so the group listed fine and only failed once the selector resolved per-model details. Fix: emit modelErrors: new Map() plus the image-budget defaults the official profile also carries. This half is host code and does need a harness restart.
Lesson: after a DSH upgrade, verify at all three layers (boot, settings panel, model picker) — not just that the server starts.
Incident log (2026-08-18, DSH rc.6 → rc.7)
After the upgrade, codebuddy requests failed 100% with PI_AI_ERROR: Provider is not configured: codebuddy. Root cause: pi-ai 0.82.1 changed the provider auth contract:
- Before 0.82.1:
auth: { name, resolve } (top-level resolve).
- From 0.82.1:
resolveProviderAuth only recognizes auth.apiKey.resolve; a top-level resolve is treated as "no auth method" → getAuth returns nothing → the error above.
Fix: buildProvider now assembles auth as { apiKey: { name, resolve } }, matching the official dsh-llm-pi-ai routeAuth/harnessApiKeyAuth shape. The plugin also self-checks this contract at startup, so a version mismatch now fails loudly at boot instead of on your first message.
Second pitfall: editing a provider in the GUI wizard with the key field left blank wiped the existing apiKeyEnv, losing the credential reference after an upgrade/reconfigure (reported as MISSING_CREDENTIAL or auth failures). Fixed: in edit mode, a blank key means "keep unchanged" and the previous apiKeyEnv is preserved.
Contributing
Bugs and reports welcome — please open an issue via the bug report template (it asks for the DSH version, plugin version, and the compat-check output, which covers 90% of failures).
Before opening a PR, run the local checks:
npm run check # syntax (lib/index.mjs, lib/client.js, scripts/check-compat.mjs)
node scripts/check-compat.mjs --workspace ~/.workbuddy/binaries/node/workspace # contract check against your real DSH
CI runs npm run check plus an npm-package sanity job (tarball file list and version-bump) on every push/PR — see .github/workflows/check.yml.
License
MIT
