dsh-xiaozhi · drive DSH by voice with the Xiaozhi assistant

Connects the Xiaozhi (小智) voice assistant to DeepSeek Harness (DSH) Web: DSH acts as the MCP tool provider, exposing workspaces, sessions, models, settings and files as tools a voice assistant can call over JSON-RPC 2.0 on a WebSocket.

English · 中文文档 · Install & verify · Tool reference

Connect the Xiaozhi voice assistant to DSH Web: DSH is the MCP tool provider, exposing 35 DSH Web endpoints as 16 voice-friendly tools, with a DSH Web settings page. 把小智（Xiaozhi）语音助手接入 DSH Web：DSH 作为 MCP 工具提供方，把 35 个接口封装成 16 个语音友好工具，自带设置页。

The pre-implementation design proposals (architecture ADR, v2 review, settings UX walkthrough) are archived in docs/design/ with every divergence from the shipped code listed.

1. What it solves

DSH's capabilities live behind HTTP REST endpoints; Xiaozhi only speaks MCP. This plugin sits between them:

 you say a sentence
        │
        ▼
┌─────────────┐   MCP (JSON-RPC 2.0 / WebSocket)  ┌──────────────────────────┐
│  Xiaozhi     │ ◄──────────────────────────────► │ dsh-xiaozhi (Host half)   │
│ App / device │  initialize / tools/list / call   │ ├ MCP session + registry  │
└─────────────┘                                    │ ├ capability → REST map   │
                                                   │ └ LocalInvoker (in-proc)  │
                                                   └───────────┬──────────────┘
                                                               │ no network hop
                                                               ▼
                                                   ┌──────────────────────────┐
                                                   │ DSH Web REST routes (copy)│
                                                   └──────────────────────────┘

Three deliberate decisions:

1. DSH is always the MCP server / tool provider. In both transports it answers initialize, ping, tools/list and tools/call, and never initiates them.

2. Outbound by default (endpoint mode). DSH dials out to the Xiaozhi MCP access point, so it needs no public IP, port forwarding or reverse proxy.

3. In-process invocation, not loopback HTTP. Tool calls go straight to the bundled DSH REST routes through LocalInvoker, so there is no host/port/auth guessing and no dependency on an external service.

Related MCP server: dsh-trio

2. Quick start (3 steps)

Requirements: DSH Web running (dsh web, default http://127.0.0.1:3080), a Xiaozhi account, and its MCP access point page open.

1. Install from this directory:

   dsh plugin add https://github.com/toddpan/dsh-xiaozhi

   Or use "install from a local directory" under Settings → Plugins in DSH Web.

2. Add a device with the access point: DSH Web → Settings → Xiaozhi → Connection, press Add device, paste the WebSocket address from the Xiaozhi console (like wss://api.xiaozhi.me/mcp/?token=…), then press Save and reload. Add more rows to bind several Xiaozhi devices/agents at once — each connects and reports its state independently.

3. Check the status tab: the connection should read connected. The tab auto-refreshes every 3 seconds, so after "Reconnect now" (or a single device's reconnect) the badge flips without a manual refresh. Press Test connection to perform a real handshake.

   Then say to Xiaozhi: "ask DSH for my session list".

The access point URL carries a token. When the page reads the config back it shows token=***, and saving treats that sentinel as "unchanged" rather than writing it over the real secret. See §7.

3. Two transports

Both can run at once: mode picks the primary channel, and serverPort > 0 additionally listens on 0.0.0.0.

Multi-device binding: endpoint mode binds several Xiaozhi devices (several agents' MCP access points) at once. Each device owns one WebSocket connection with its own backoff and heartbeat; the settings page shows per-device state and offers per-device Reconnect and Test, and removing a device touches only that device. The list is stored under endpoints (§8); a legacy single-URL config (endpointUrl) still works — the page shows it as one device and migrates it to the list on the first save.

Reconnect in endpoint mode uses exponential backoff (reconnectMinMs → reconnectMaxMs, ±20% jitter) plus a heartbeatMs ping. The Status tab and the log show every attempt.

4. Tool exposure: grouped (default) or flat

Xiaozhi sanitises tool names to [A-Za-z0-9_\-CJK]. Every name this plugin exposes is a fixed point of that rule (e.g. dsh_session_history), so no platform-side renaming occurs.

Grouped is the default because a voice model picks the right tool far more reliably from 16 options than from 35; the settings page warns past 24 tools. Full mapping: docs/TOOLS.md.

Groups can be disabled per area (e.g. docs, files). allowWriteTools = false refuses create/update/delete/send operations with a speakable message while keeping read operations usable, even inside a grouped tool that mixes both.

5. Capability coverage

All 35 endpoints are reachable, and both tool modes cover 35/35:

Four of them are degraded under MCP semantics. Read the next section before relying on them.

6. MCP semantic degradations (please read)

tools/call is strictly request/response with no incremental channel, while several source endpoints stream. This plugin keeps as much semantics as possible and says so, instead of pretending:

Also:

• dsh_say(wait=false) hands a sentence to a session without waiting: it submits prompt-stream with a ~1.5 s budget and, on timeout, quietly reports "submitted" plus the session status.

• Every tool result is clipped to maxVoiceChars and delivered as a single text block so speech stays short.

7. Security model

Secret masking: reading the config masks apiKey, serverToken, the token= value inside the access point URL — including every device URL in endpoints — and every endpointHeaders / device-headers value (•••••• / ***) while keeping header names. Saving treats those sentinels as "unchanged" and restores the stored values, so a sentinel can never overwrite a real secret.

Global endpointHeaders can be added or overwritten from the page but not deleted (the write is a merge). Edit settings.json by hand to remove a global header; device-level headers are saved per row, so deleting the line in the device card and saving removes the key.

8. Configuration

Precedence, lowest first:

1. code defaults (DEFAULTS in src/config.ts)

2. the plugin row's config (the profile's cordis.patch.yml)

3. overrides saved by the settings page (<homeDir>/settings.json)

Why is homeDir not on the settings page? It decides where the override file lives, so honouring it from that file is circular — the page would show a new directory while overrides kept being written to the old one. homeDir therefore comes only from the plugin row config (or the DSH_XIAOZHI_HOME environment variable) and the page shows it read-only.

9. Settings page

DSH Web → Settings → Xiaozhi, five tabs:

• Status — connection badge, transport, masked access point, a state line per bound device, client count, reconnects, last error, warnings, public addresses, tool/capability counts, per-group state; with Test connection, Reconnect now and Refresh. The tab auto-refreshes every 3 seconds, so a reconnect updates the badge on its own.

• Connection — basics, the Xiaozhi MCP device list (add / rename / remove, per-device Reconnect and Test), tool-group switches, and a collapsed advanced form. Save and reload writes the override file and restarts the runtime; Restore defaults clears every override.

• Tools — the tools actually exposed, their read/write nature and capability counts.

• Capabilities — all 35 capabilities by area, with method and path.

• Logs — the plugin ring log (300 lines) with an optional 5-second auto refresh.

The page styles itself with DSH theme tokens (--dsw-alias-*) only, imports no dsh-client-ui-primitives, and therefore follows the host in light and dark without clashing.

10. Development

cd dsh-xiaozhi
bash scripts/build.sh                     # needs a DSH source checkout for tsc (auto-probed)
node --test --test-timeout=30000 "test/*.test.mjs"

127 test cases across:

src/dshapi/ is a verbatim copy of @dsh-external/dsh-web-service v0.1.11 (BSD-3-Clause); the only new file is src/dshapi/service.ts, which assembles it into one router, so an upstream update stays a clean three-way diff. See NOTICE.

11. Troubleshooting

12. License

BSD-3-Clause. Derived from @dsh-external/dsh-web-service v0.1.11 (Copyright © 2026 toddpan 潘祖继) under the same license. See LICENSE and NOTICE.