omdsh-dev/dsh-data-agent

中文 | English

Project Overview · Features · Quick Install · Web UI · dsh-tui · Security

Project Overview

dsh-data-agent is a data analysis plugin for DeepSeek Harness (DSH). Connect a database and ask a business question; DSH inspects schemas, writes and runs SQL, continues the analysis from real results, and returns clear conclusions and business insights. The plugin supports both the Web UI and dsh-tui without modifying the DSH source code.

Features

• Analyze data through conversation: Describe your goal in natural language. DSH understands the question, breaks it into analysis steps, queries real data, and organizes the conclusions. You can keep asking follow-up questions to explore the same context in greater depth.
• Discover business insights automatically: Data Agent goes beyond returning query results. It helps compare trends, locate anomalies, identify valuable customers or products, and turn the data into explanations that support decisions.
• Cross-surface HTML reports (render-analysis): In an ordinary tool call, the agent can choose to produce a single chart or a Dashboard-style report (metric/line/bar/pie/scatter/table views). Every successful call saves an offline HTML file under analysis-reports/ in the current workspace. Web also shows an inline preview and a “View analysis” Modal; dsh-tui returns the file path. Whether to chart remains the agent's decision — schema exploration, single scalars, and queries without visual value are never forced into charts.
• Works with both Web UI and dsh-tui: For a visual workflow, we recommend zhu1090093659/dsh-web-ui, where you can connect databases, browse schemas, and inspect results in the browser. For a keyboard-first workflow, we recommend ccch1mneyyy/dsh-TUI, where you can use the same Data Mode, connect through /database, and move directly into conversational analysis. Both interfaces provide the core Data Agent experience.
• Connect common business databases: Supports MySQL, PostgreSQL, SQLite, Oracle, Hive, and Impala across application databases, analytics systems, local data files, and data warehouses.
• Let DSH complete the analysis loop: DSH inspects table structures, writes SQL, runs the query, and adjusts its approach based on errors or returned data instead of stopping at an unverified SQL draft.
• Stay focused with Data Mode: The session uses DSH's native str_replace_editor for files and keeps sql-query, sql-write, sql-cmd, and render-analysis; Web, Desktop, dsh-tui, and headless profiles use the same tool protocol. Host or community tools such as describe_image and ssh_* do not leak into Data Mode.
• Work safely with real data: Use read-only mode and a read-only database account when appropriate. TUI passwords are masked and are never restored as part of a form draft. You decide whether the session may modify data.

The Web UI also includes an on-demand database workbench. Click the database button in the top-right of the composer to configure the connection, browse schemas, inspect columns, or run SQL in one Modal. Before and after the conversation starts, it no longer occupies the area above the composer or a left sidebar.

Choose “Data Mode” when creating a session, and DSH will use the data-analysis workflow for everything that follows.

Quick Install

The commands below install the plugin into the Web profile.

Method 1: npm (recommended)

dsh plugin --profile web add @yejiming/dsh-data-agent

Method 2: GitHub

dsh plugin --profile web add github:omdsh-dev/dsh-data-agent

The plugin installs the Data Mode preset automatically and preloads its database tools and command when the profile starts. Selecting the preset no longer performs dynamic package-subpath imports. No local build is required.

Using Data Agent in the Web UI

Start the Web UI:

dsh --profile web

Then:

1. Create a session and choose “Data Mode.”
2. Click the database button in the top-right of the composer and enter your connection details in the workbench Modal.
3. Once connected, ask an analysis question directly in the conversation.
4. Follow up on the first result and ask DSH to narrow the scope, compare dimensions, or summarize the conclusions.

For example, ask: “Analyze order changes over the last 30 days, identify the regions and products with the largest revenue decline, and explain the main causes.” DSH will inspect the relevant tables, generate and run the queries, and complete the analysis from real results.

Analysis reports and HTML artifacts

Data Mode provides the render-analysis tool on every surface. The agent first explores and verifies facts with sql-query, then decides for itself whether a visualization helps. When it does, one tool call produces one versioned analysis report:

• A report holds 1-6 read-only datasets and 1-8 views (metric, line, bar, pie, scatter, table); multiple views may reuse one dataset, and aggregation or Top N is written in the SQL itself;
• Simple questions produce a single main chart (inline preview in the result row); complex questions produce a compact summary plus a “View analysis” button;
• “View analysis” opens a large Modal with every view of that report: a compact metric band, a full-width main chart, a two-column secondary grid, and a detail table — responsive across light/dark themes and narrow screens;
• Regardless of the active UI, the complete Dashboard is written atomically to analysis-reports/*.html under the session workspace and appears in DSH's Produced row where supported. The filename defaults to the report title or a semantic outputName basename, without a long UUID. Data, styles, and SVG rendering code are inline, so the file opens without a network connection;
• The complete report snapshot is persisted with the session log: refreshing or replaying history never re-queries the database and creates no extra browser storage;
• Web still renders its preview from the same report meta; the Node HTML generator loads neither ECharts nor Web client code.

Using Data Agent in dsh-tui

Install Data Agent into the dsh-tui profile. render-analysis does not require a particular dsh-TUI version or scene capability:

dsh plugin --profile dsh-tui add @yejiming/dsh-data-agent

Start the terminal interface:

dsh --profile dsh-tui

In a blank session, switch to Data Mode and connect a database:

/preset data-agent
/database connect

The connection form displays all relevant fields together. Use Tab or Shift+Tab to move between fields. Press Enter on database type or read-only mode to show every option, use the arrow keys to select one, and press Enter again to confirm.

After connecting, return to the chat input and ask a business question. Other useful database commands include:

/database status       Show the current connection
/database test         Test the current connection
/database disconnect   Disconnect the current database

After the agent generates a report, the tool card shows dataset, view, empty-data facts, and the absolute HTML path. TUI does not print a character Dashboard and does not register /analysis; open the HTML in a local browser to inspect all six view types and raw data. The file belongs to that tool call, and /resume does not re-query the database.

When you reopen the connection form in the same session, it restores the latest database type, host, port, user, database, and read-only mode. The password always remains masked and is never restored.

How to Ask Better Analysis Questions

For more valuable results, include the business goal, time range, and dimensions you care about. For example:

Analyze revenue and gross-margin changes by region in Q2 2026.
Find the regions with unusual performance, drill down into categories and key customers,
and recommend three concrete business actions.

You can also ask DSH to save the SQL or analysis so it can be reviewed and reused:

Complete a member repeat-purchase analysis, save the final SQL to
analysis/repurchase.sql, and summarize the main findings in a format suitable for a weekly report.

Before You Start

DSH must be able to reach the target database from your machine, and the corresponding database client must be installed:

• SQLite is usually included with macOS or Linux.
• MySQL requires the mysql client.
• PostgreSQL requires the psql client.
• Oracle, Hive, and Impala require their respective command-line clients.

The plugin tries the active profile process PATH first. If that fails, it also checks client HOME environment variables and common Windows, macOS, and Linux installation locations, including Homebrew, MacPorts, Linuxbrew, Snap, Nix, WinGet Links, Scoop, Chocolatey, and versioned Program Files directories. The supplemental PATH used for discovery is also passed to the actual client process, so DSH Desktop launched from Finder normally needs no manual path override for Homebrew clients.

If a client lives in a company toolchain or another custom directory, add search directories to the current profile's data-agent config. Use an absolute command path when you need to pin one exact version. The current profile PATH always wins, and searchPaths is checked before platform defaults:

- id: data-agent
  config:
    clients:
      mysql:
        searchPaths:
          - /opt/company/mysql/bin
        # command: /opt/company/mysql/bin/mysql

On Windows, a search path can be written as C:\Program Files\MySQL\MySQL Server 9.0\bin. The plugin does not download database clients, run a login shell, or scan the whole disk. A client in an unusual directory that is not on PATH still requires searchPaths or command.

We recommend creating a read-only database account so Data Agent can explore and analyze data without modifying production records.

If you see failed to mount or a missing @yejiming/dsh-data-agent package error, the plugin is usually missing from the current profile or an older preset is still installed. Run the matching command for the Web UI, DSH Desktop, or dsh-tui, then quit and restart DSH completely. An unmodified legacy preset is migrated automatically; for a hand-edited preset, remove the two configuration blocks that reference @yejiming/dsh-data-agent/tool and @yejiming/dsh-data-agent/command.

Security

• Prefer a read-only database account and enable read-only mode in the connection form.
• Temporary passwords entered in the Web UI or dsh-tui are used only for the current connection. The TUI displays only * and never restores the password when the form is reopened.
• If authentication must be restored across processes, use a DSH credential reference instead of putting a plaintext password in command arguments.
• When read-only mode is disabled, Data Agent can run update or administrative statements at your request. Before connecting to a production database, review the account permissions and backup policy.
• Database connections are isolated by session, making it easier to keep different projects, customers, and analysis environments separate.

Uninstall and Rollback

dsh plugin --profile web remove @yejiming/dsh-data-agent
dsh plugin --profile desktop remove @yejiming/dsh-data-agent
dsh plugin --profile dsh-tui remove @yejiming/dsh-data-agent
rm -rf $DSH_HOME/.agent-presets/data-agent

Uninstalling the plugin does not automatically delete saved non-secret connection information. If you need to remove it completely, back it up first and then delete the corresponding Data Agent storage records in DSH.

Local Development

pnpm install
pnpm build
pnpm test

The prebuilt lib/ directory is committed to the repository, so npm and GitHub installations do not require a local build.

License

MIT

Related Links

• dshfind.com: A Chinese learning and sharing community for DeepSeek Harness
• dsh-web-ui: A collection of plugins and skins for the DeepSeek Harness Web UI
• dsh-cc-tui: A Claude Code-style full-screen terminal interface