@kaiwangleo/dsh-xiwen

dsh plugin --profile web add @kaiwangleo/dsh-xiwen

dsh-xiwen

dsh-xiwen connects DeepSeek Harness to Xiwen (析问), a Chinese business analytics agent backed by a curated semantic layer.

The plugin registers one model-facing tool, xiwen_query. It sends a business question to a separately deployed Xiwen service, consumes the JSON-over-SSE response, and returns bounded structured data to Harness.

Version 0.1.0 is published on npm as @kaiwangleo/dsh-xiwen.

Verified Xiwen result

This end-to-end result was captured with the real Xiwen service, MySQL, Qdrant, Elasticsearch, and Embedding containers. A deterministic local OpenAI-compatible mock supplied the LLM responses; no external model service was used for this verification.

Architecture and responsibilities

DeepSeek Harness
    | xiwen_query
    v
@kaiwangleo/dsh-xiwen
    | POST /api/query + Bearer token + SSE
    v
Xiwen FastAPI / LangGraph service
    |-- MySQL metadata and read-only warehouse access
    |-- Qdrant field and metric recall
    |-- Elasticsearch enumerated-value recall
    |-- Embedding service
    `-- OpenAI-compatible LLM service

The plugin is only the Harness adapter. It does not install, start, configure, or monitor the Python service, MySQL, Qdrant, Elasticsearch, the Embedding service, an LLM, or the Xiwen web workbench.

What xiwen_query does

The tool accepts one required argument:

{
  "query": "统计 2025 年各地区的销售总额"
}

Use it for structured business questions that depend on curated tables, columns, metrics, aliases, enumerated values, filters, or time dimensions. It is not a general web-search or arbitrary database administration tool.

A successful call returns this canonical JSON shape:

{
  "sql": "SELECT ...",
  "rows": [],
  "rowCount": 0,
  "truncated": false,
  "message": null
}

The adapter understands Xiwen's progress, result, error, and chat SSE events. It forwards Harness cancellation to the HTTP stream, applies its own timeout, and bounds results by both row count and serialized row characters.

Requirements

• Node.js ^22.19.0 or >=24.0.0.
• A compatible DeepSeek Harness installation. The supported tool-runtime range is declared in [package.json](package.json).
• A separately running Xiwen backend and all of its dependencies.
• A configured semantic layer and a completed knowledge build before the first analytical query.

The current Xiwen warehouse implementation supports MySQL only.

Start the Xiwen backend

From the Xiwen repository, create local configuration files and replace every CHANGE_ME value:

cd data-agent
cp .env.example .env
cp conf/app_config.example.yaml conf/app_config.yaml

Keep the metadata and warehouse credentials in conf/app_config.yaml consistent with .env. In particular, db_dw should use the dedicated read-only warehouse account rather than root or the metadata account.

Place a compatible BAAI/bge-large-zh-v1.5 model under data-agent/docker/embedding/models/bge-large-zh-v1.5, then start the infrastructure containers:

docker compose up -d

This Compose file starts MySQL, Qdrant, Elasticsearch, and the Embedding service. Start the Python API separately:

uv sync
uv run python main.py

The default API address is http://127.0.0.1:8000. Check dependency readiness before connecting Harness:

curl http://127.0.0.1:8000/api/health

The response should report "status": "ok". A degraded response identifies unavailable dependencies without exposing credentials or connection details.

Before the first query, use the Xiwen workbench to select warehouse tables, maintain table/column/metric metadata, and complete a knowledge build. See the [repository setup guide](../../README.md) and [technical architecture](../../data-agent/docs/技术架构.md).

Install into a Harness profile

Local checkout

From the Xiwen repository root, install dependencies and build the ESM entry point:

npm --prefix plugins/dsh-xiwen ci
npm --prefix plugins/dsh-xiwen run build
dsh plugin --profile xiwen add ./plugins/dsh-xiwen

Local tarball

To install the exact packaged artifact without using the registry:

cd plugins/dsh-xiwen
npm ci
npm pack
dsh plugin --profile xiwen add ./kaiwangleo-dsh-xiwen-0.1.0.tgz

npm registry

Install the published release directly from npm:

dsh plugin --profile xiwen add @kaiwangleo/dsh-xiwen@0.1.0

Verify that Harness loaded the bundle layer:

dsh --profile xiwen --dump-config

The output should contain an xiwen row whose package name is @kaiwangleo/dsh-xiwen. Start Harness with the same profile:

dsh --profile xiwen

Then ask the model to use xiwen_query, for example:

Use xiwen_query to answer: 统计 2025 年各地区的销售总额

Configuration

The bundled patch defaults to the loopback Xiwen service. To override it, add an xiwen row to the profile's cordis.patch.yml:

- id: xiwen
  config:
    baseUrl: 'http://127.0.0.1:8000'
    apiToken: 'REPLACE_WITH_THE_BACKEND_API_AUTH_TOKEN'
    timeoutMs: 120000
    maxRows: 200
    maxResultChars: 50000
    includeProgressSummary: false

Do not commit a real apiToken. Omit it when the local backend has no token configured.

Setting · Default · Meaning

baseUrl · http://127.0.0.1:8000 · Xiwen service root. Only HTTP and HTTPS URLs without embedded credentials, query strings, or fragments are accepted.

apiToken

…(truncated)