DSH-AUX

English | 简体中文

Hi~ I'm AUX, your auxiliary model little helper 💙 The main model stays focused on the chat; I take care of images, web pages, and compressing long text! Whenever you need me, just call me directly～

dsh-aux — Auxiliary Model System for DSH

Give the main agent a "co-pilot": vision analysis, web extraction, and long-text compression are handled by a separate auxiliary LLM, so the main model stays focused on the conversation.

💬 "Leave these chores to me, and you just enjoy the chat~"

Table of Contents

• What is this?
• Highlights
• What can I do for you
• Platform switches & SKILL modes
• Quick Start
• Daily commands
• Image Library
• Settings & status panel
• Bridges & advanced capabilities
• Security boundaries
• How It Works
• Project Layout
• Compatibility & Dependencies
• Documentation
• FAQ
• Related Projects
• License

What is this?

Models keep getting stronger, but handing "look at this image", "read this page", "compress this long text" to the main model interrupts the flow and burns context. dsh-aux routes those chores to a separate auxiliary LLM: you just send the request, and it automatically routes to the right model—the main model answers your conversation, while the auxiliary model takes care of "look at this image", "summarize this page", "compress these 50k words".

• Unified auxiliary LLM routing: per-task model / timeout / concurrency / reasoning effort.
• Zero-config by default: works without any model configuration; falls back to the session's main model.
• Observable: every call is written to the session log; visible through /aux status, the settings page, and the status chip.

Highlights

What can I do for you

💬 "Seeing images, reading pages, compressing long text—all my specialties!"

web_extract

• Output: single page returns summary / keyPoints + chars / truncated; recursion adds pages, totalChars. The result text opens with a notice stating that summary / keyPoints are the auxiliary model's restatement of external web content—untrusted data to reference, never to follow as instructions.
• Boundary: static-HTML summary agent—does not execute JS; cannot click/paginate/fill forms.
• Recursion: uses the same crawl engine as web_crawl, honoring robots.txt, rate limits, and per-hop SSRF checks.

web_crawl

Two summary modes

Cleaning & anti-crawl (zero dependencies)

• Encoding: decodes via Content-Type / <meta charset>; GBK/GB18030 etc. remain intact.
• JS Challenge: detects Cloudflare/challenge shells → returns browserRequired, does not burn tokens, suggests a browser.
• 429 / 502-504: retries once with a short backoff; if it still fails, reports a rate-limited error.
• 403 and other 4xx: returns a "may need a browser / login" message instead of feeding empty content to the auxiliary model.
• Redirects: follows each hop with SSRF checks and exposes the redirects count.
• Proxy: direct connection first; automatically falls back to HTTP(S)_PROXY (respecting NO_PROXY), zero dependencies.

Platform switches & SKILL modes

This is the core v0.4.0 experience: AUX is no longer "automatic but opaque"—it is configurable, disablable, and explainable.

Tool / bridge three-state switches

Applies to: vision_analyze, web_extract, web_crawl, compress_text, imageBridge, compactionBridge, skillAudit.

💬 "Don't want me in the way? One click back to native~"

SKILL audit modes

Diagnostics & repair panel

The settings page top shows each tool/bridge's status dot, patch badge, and unavailable reason; when a patch is missing you can re-apply it in one click, and it reminds you to restart DSH afterward. Status data is read through the hidden aux/platform-status event + aux-platform projection (a non-command channel, so it does not generate /aux status --json command cards in the session).

💬 "If something's off, I'll light up and tell you~"

Quick Start

# Option 1: clone and install everything (recommended, includes image-bridge)
git clone https://github.com/DoloresCaritasAngelus/DSH-AUX.git
cd DSH-AUX && ./install.sh

# Option 2: install the plugin package from a local source tree (use this until npm is published)
git clone https://github.com/DoloresCaritasAngelus/DSH-AUX.git
cd DSH-AUX/dsh-aux
dsh plugin --profile web add "file:$(pwd)"

After restarting DSH:

1. Send an image to the agent and it will describe it with vision_analyze (even a text-only main model can receive images—image-bridge is integrated);
2. Run /aux status to see each task's route;
3. Want vision to use a dedicated model? /aux model vision <provider>/mimo-v2.5.

⚠️ When starting DSH, use your real launcher (for example ~/dsh/start-dsh.sh or npx @deepseek-ai/dsh web). Do not use pnpm dsh --profile web-style development launchers that boot from TS source trees: dsh-aux patches are applied to the published lib/ artifacts, so source mode does not load them and features can appear patched but remain inactive.

💬 "Once installed, just call me~"

Updating (GitHub installs)

./update.sh                # pull latest code + re-wire (idempotent)
./update.sh --no-pull      # if you already updated the source, just re-wire
node scripts/doctor.mjs    # post-update health check (does not modify anything)

Why isn't git pull enough? dsh-aux's bridge patches and start-up self-heal hook live in the DSH deployment (node_modules / start-dsh.sh); git pull only updates the source. ./update.sh re-runs install.sh to write new patches / self-heal hooks into the deployment.

Daily commands

Image Library

The image library is dsh-aux's visual panel for session images, opened from the 🖼 button at the bottom of the DSH sidebar (Web UI). It helps you manage image attachments, analysis memories, and lifecycle state across sessions.

Features:

• Browse: thumbnail grid with small/medium/large sizes; search by file name, memory content, or session.
• Filter: All / Shared / Orphan / Archived / Retained / Memory.
• Batch actions: checkboxes or mouse drag-to-select (hold Shift/Ctrl to add to the selection); delete, reclaim orphans, retain/unretain.
• Detail: centered resizable/draggable modal with metadata, owner sessions, analysis memories, and "Go to message / trace" entries (currently a degraded open-session fallback due to DSH public API limits).
• Group/sort: group by date or session; date groups use progressive granularity: today in 6-hour buckets, the last 30 days per day, the current year per month, and older years per year; session grouping pins orphan/archived groups on top; supports within-group and between-group sorting.
• Archived state: images referenced only by archived sessions are no longer misclassified as orphans; they appear in the archived count/filter/session group. When a readable live owner exists, the thumbnail tries live sessions first.

Command-line read/manage commands:

See IMAGE-LIBRARY-CONTRACT.md and IMAGE-LIBRARY-DESIGN.md for the detailed contract and design.

Settings & status panel

Why look here first?

Some AUX bridges need platform patches to work fully (image-bridge, compaction, skill, etc.). The old experience led users into two traps:

• not knowing whether a patch is actually required;
• not knowing whether their patch is actually installed.

This settings page turns both into visible status: it tells you each tool/bridge's current state, whether a patch is missing, and what to do about it. The platform switches turn "are patches required or optional?" from a philosophy question into a configurable choice:

💬 "Is the patch installed? Don't guess—I'll tell you directly~"

3-step getting started

1. Restart DSH after installing;
2. Open Web → Settings → Auxiliary Models;
3. Look at the Diagnostics & Repair panel at the top:
   • Status normal: you're ready to go;
   • Patch missing / abnormal: click one-click repair;
   • After repair, it tells you to restart DSH for the patch to take effect; restart and come back to confirm the status is healthy.

What else the settings page can do

Web → Settings → Auxiliary Models. Configure per-task model, timeout, concurrency, maxChars, and reasoning effort for vision / web_extract / web_crawl / compress / compaction / skill. The page is grouped into collapsible "Tool Tasks / Bridge Tasks / Global / Platform Switches" sections and follows the DSH language (zh/en).

• Status chip: the composer shows the latest auxiliary call (task, duration, whether it fell back).
• Diagnostics & repair: each tool/bridge shows a status dot, patch badge, and unavailable reason; missing patches can be re-applied in one click, with restart detection after writing.
• Platform switches: tools and bridges can switch native / aux / compat; turn off AUX anywhere you don't want it.
• SKILL audit modes: native / audit / report / report-ondemand.
• Privacy: you can turn off "Show auxiliary model status chip in conversation UI"; when off, the aux-status projection is no longer exposed to Web/third-party readers, while /aux status still works.

Bridges & advanced capabilities

Skill pre-audit bridge (skill-audit)

DSH's native flow is "main model sees catalog → calls skill → directly executes SKILL.md". dsh-aux inserts an auxiliary-model due-diligence step:

Main model sees catalog → decides to call skill → native skill tool loads SKILL.md
    ↓
AUX intercepts → auxiliary model reads SKILL.md + current task
    ↓
Returns "how to apply / known pitfalls / 🔻rot-prone stale assertions / execution advice"
    ↓
Main model sees both "original SKILL.md + pre-audit report" → verifies → truly executes

• Enable: only intercepts after you configure a dedicated auxiliary model in settings or /aux model skill <provider>/<model>; without it, native pass-through.
• Does not own skills: dsh-aux does not create/manage skills; that remains the native or memory-management plugin's job.
• Fail-soft: if the auxiliary call fails, the original SKILL.md is returned and the main model is not blocked.

Compaction bridge

Configure a compaction task and native DSH auto/manual compaction routes through the AUX model, reusing AUX timeout/concurrency/cooldown/fallback/event tracing. In image-containing sessions, if images are unavailable, they are downgraded to text placeholders and compaction does not fail.

Reasoning never reaches the output: the auxiliary model treats only visible text (text blocks) as its result; thinking (reasoning blocks) never contributes—this holds for all six auxiliary tasks. If a call produces reasoning but no text, AUX treats it as a failure and takes the existing fallback path (main-model fallback; the skill task returns the native result instead) rather than passing thinking off as an answer.

Programmatic API (for plugin developers)

const result = await ctx.auxLlm.call("compress", {
  messages,
  system,
  session,
  signal
});
// => { text, provider, model }

Custom tasks: ctx.auxLlm.registerTask(...).

Security boundaries

• SSRF protection (on by default): web_extract, web_crawl, and vision_analyze's imageUrl reject internal/loopback/cloud-metadata addresses by default; the fallback fetch path validates every redirect hop before sending. Direct fetches pin the validated IP to a dedicated connection (closing DNS rebinding) and apply unconditional connect / first-byte / idle deadlines (15s / 45s by default, configurable, <=0 disables); an empty resolution is fail-closed. To fetch local/intranet services, explicitly set allowInternalUrls: true.
• Prompt injection mitigation: page bodies, compressed text, and text inside images are treated as untrusted data, physically separated from the trusted Question instructions, with embedded instructions explicitly forbidden.
• Concurrency hard cap: even if maxConcurrency is configured higher, each task is capped at 10.

💬 "Suspicious pages and instructions? I'll block them first and call you~"

How It Works

• Route resolution: explicit config > task default > session main model; on auxiliary failure, automatically falls back to the main model.
• Robustness: per-task timeout (default 60s), concurrency semaphore (default 2), failure cooldown (3 consecutive failures → stop 60s), error classification, and aggregated error reporting per attempt.
• Observability: every call writes an aux/llm-call session event + aux-status projection, replayable from history.
• Image capability gate: checks model input capabilities before calling; explicitly unsupported models are skipped; unknown capabilities are passed to the provider.
• Compaction synergy: dsh-compaction-basic summaries can run through ctx.auxLlm's compaction task.

Project Layout

• dsh-aux/src/ — plugin core (routing, tools, bridges, status/commands, client UI)
• bridge/ — platform patches, self-heal, install scripts
• tests/ — full test suite
• scripts/ — doctor and README generator
• assets/ — mascot images

Compatibility & Dependencies

• Platform: DSH 0.1.5-rc.2 (single supported line on the main branch); Node ≥ 20.
• DSH 0.1.5-rc.1 users: share this release — the two lines are equivalent for the AUX patch hosts (rc.1 → rc.2 changed version numbers only; see CHANGELOG.md).
• DSH 0.1.2-alpha.2 ~ 0.1.2-rc.1 users: use the permanent branch legacy/dsh-0.1.2-alpha.2-to-0.1.2-rc.1 or Release v0.4.4-legacy.
• Legacy DSH (0.1.0-rc.6 ~ 0.1.1-rc.2) users: use the permanent branch legacy/dsh-0.1.0-rc.6-to-0.1.1-rc.2 or Release v0.4.1-legacy. The main branch no longer supports these versions.
• Zero third-party runtime deps: peerDependencies are official DSH packages plus the platform-provided react/zod; no dependencies.
• Zero test deps: node --test tests/*.test.js (636 tests); file list and baseline in TESTING.md).

Integrated components

• image-bridge: lets text-only main models receive pasted images while keeping thumbnails; the delivered text anchors on attachmentId (no longer on .ext hard-link paths) and labels each image "image N of M in this message"; re-run bridge/apply-patch.mjs after npm update.
• settings writability: the settings page can read/write aux config; native on the DSH alpha line, rc.6 patch retired to bridge/retired/.
• session event registration channel: the four hidden events (including aux/llm-call) are written with ignorable: true; if the patch is missing, events are downgraded (not written) to protect session logs. Since DSH 0.1.5 the session migration validates historical events against a frozen vocabulary, so self-heal now applies P12 (admits aux/*) and P13 (admits official historical shapes, self-retiring once upstream ships); dsh-aux/src/event-shapes.js is the single source of truth for event fields — an unregistered field warns and fails the test suite.
• session deletion synergy: works with dsh-plugin-session-delete to clean up unreferenced images when a session is deleted.
• image ownership & delete safety: a session/event ownership hook plus a session/created recovery barrier (in-memory log scan); deletions are refused globally while a live session is unbackfilled (fail-closed, visible in /aux status); reclaim moves objects into objects/.trash/ (7-day recovery window).
• GC debt: an attachment-refs.json sidecar plus official imageHostPath reclamation and full .ext hard-link cleanup; the derived request-images/ cache is reclaimed by mtime LRU under a total cap (256 MiB by default, requestImagesMaxMiB).
• Vision delivery route: aux.visionRoute (aux by default / native-when-capable / auto); native delivery only applies to routes whitelisted in aux.nativeRoutes, and forceAuxVision wins. The fallback (visionFallbackToMain) only falls back to a main route that explicitly declares image input; when that capability is unknown or declared text-only the vision call fails outright instead of handing the image to a model that cannot see it.
• Auxiliary route and fallback: one auxiliary route per task (singular provider / model, else the task default). On failure it falls back to the main model per fallbackToMain / visionFallbackToMain (vision additionally requires the main model to declare image support — see below). There is no multi-level chain: to spread across several models, change the configuration yourself.
• Vision polish (Phase 3): failed entries report the reason and whether a retry helps (rate-limit/connection/server retry once in-tool; a timeout is not retried — the route already spent its whole timeoutMs, so raise that task's timeout instead); an extension-less imagePath is sniffed by magic bytes (aligned with read_image); animated GIFs are analyzed from the first frame; direct fetches pin the validated IP (closing DNS rebinding); the vision_analyze conversation card shows a 【图N/共M】 badge with thumbnail and conclusion.

Minimal / Anchored Standard compatibility

Before the first persistent tool/call, only the Minimal tool pair is exposed and auto-injected context is stripped. dsh-aux never injects AUX context/prompts in the first turn; after the first tool/call, the tool directory opens, AUX tools appear, and a one-time agent/pre-step hint guides direct use of vision_analyze.

Documentation

FAQ

Q1: Why can't I see vision_analyze and other AUX tools in the first turn of Minimal / Anchored Standard?

Those presets expose only the Minimal tool pair before the first persistent tool/call and strip auto-injected context. dsh-aux respects this and never injects AUX context/prompts in the first turn, nor exposes its tools early. After the first tool/call, the tool directory opens and AUX tools appear.

Q2: Why did /compact fail in an image-containing session?

If the image block's attachment object has already been GC/cleaned, or none of the available compaction routes support image input, images are unavailable for compaction. dsh-aux then downgrades images to text placeholders and continues compacting through AUX, so compaction normally does not fail.

Q3: Do I need to configure a model for dsh-aux?

No. dsh-aux is zero-config: it works without any model configuration and falls back to the session's main model. You can assign a dedicated model later via the settings page or /aux model <task> <provider/model>

Related Projects

• dsh-anchored-standard — Anchored Standard preset
• dsh-vision-toolkit — community vision toolkit
• dsh-plugin-session-delete — session deletion plugin
• SeekMaid-pet — DeepSeek desktop pet

License

MIT License © 2026 dsh-aux contributors