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-web-mcp

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 /Users/tsbj/feyanggit/DHS-test/dsh-xiaozhi

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

2. Paste the access point: DSH Web → Settings → Xiaozhi → Connection, put the WebSocket address from the Xiaozhi console (like wss://api.xiaozhi.me/mcp/?token=…) into "Xiaozhi MCP access point", then press Save and reload.

3. Check the status tab: the connection should read connected with a client count. 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.

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, and every endpointHeaders value (•••••• / ***) while keeping header names. Saving treats those sentinels as "unchanged" and drops them, so a sentinel can never overwrite a real secret.

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 header.

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, client count, reconnects, last error, warnings, public addresses, tool/capability counts, per-group state; with Test connection, Reconnect now and Refresh.

• Connection — basics, 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"

114 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.