@yejiming/dsh-data-agent 0.0.6 → 0.0.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/README.en.md +142 -119
  2. package/README.md +138 -118
  3. package/cordis.patch.yml +8 -9
  4. package/lib/client.js +42423 -524
  5. package/lib/client.js.map +1 -1
  6. package/lib/command-LFgLb6el.js +875 -0
  7. package/lib/command.js +2 -0
  8. package/lib/connections-WmjuUrDj.js +1608 -0
  9. package/lib/defaults-DP4RyRh1.js +21 -0
  10. package/lib/index.js +265 -68
  11. package/lib/routes.js +94 -170
  12. package/lib/tool-Dka6RyEp.js +1128 -0
  13. package/lib/tool.js +1 -426
  14. package/lib/types/analysis.d.ts +1071 -0
  15. package/lib/types/client/AnalysisChart.d.ts +26 -0
  16. package/lib/types/client/AnalysisDashboard.d.ts +30 -0
  17. package/lib/types/client/DataAgentWorkbench.d.ts +2 -2
  18. package/lib/types/client/analysis-charts.d.ts +40 -0
  19. package/lib/types/client/analysis-view-model.d.ts +44 -0
  20. package/lib/types/client/index.d.ts +3 -4
  21. package/lib/types/client/locales.d.ts +66 -0
  22. package/lib/types/client/persistence.d.ts +6 -1
  23. package/lib/types/client-discovery.d.ts +45 -0
  24. package/lib/types/clients.d.ts +17 -10
  25. package/lib/types/command.d.ts +41 -0
  26. package/lib/types/connections.d.ts +115 -40
  27. package/lib/types/defaults.d.ts +2 -0
  28. package/lib/types/index.d.ts +109 -63
  29. package/lib/types/routes.d.ts +25 -91
  30. package/lib/types/sql.d.ts +1 -1
  31. package/lib/types/storage.d.ts +70 -0
  32. package/lib/types/structured-read.d.ts +50 -0
  33. package/lib/types/tool.d.ts +29 -20
  34. package/lib/types/tui-connection-form.d.ts +98 -0
  35. package/package.json +65 -4
  36. package/preset/data-agent/agent.cordis.yml +22 -25
  37. package/preset/data-agent/preset.yml +1 -1
  38. package/lib/defaults-Bac6QvNt.js +0 -911
  39. package/lib/query-CmhTFklw.js +0 -86
package/README.en.md CHANGED
@@ -1,196 +1,219 @@
1
- # Data Agent · Let AI Connect Your Database and Write SQL
1
+ # DSH Data Agent · Analyze Data Through Conversation
2
2
 
3
3
  [中文](README.md) | **English**
4
4
 
5
- ![Data Mode session](assets/session.png)
5
+ <p align="center">
6
+ <img src="assets/dsh-data-agent-banner.png" alt="dsh-data-agent hero banner" width="100%">
7
+ </p>
8
+ <p align="center">
9
+ <img src="https://img.shields.io/github/v/release/omdsh-dev/dsh-data-agent?style=flat-square" alt="Version">
10
+ &nbsp;
11
+ <a href="https://dshfind.com/en/plugins/omdsh-dev/dsh-data-agent?ref=badge"><img src="https://dshfind.com/api/badge/omdsh-dev/dsh-data-agent" alt="dshfind badge"></a>
12
+ &nbsp;
13
+ <img src="https://img.shields.io/github/stars/omdsh-dev/dsh-data-agent?style=flat-square" alt="Stars">
14
+ &nbsp;
15
+ <img src="https://img.shields.io/npm/v/@yejiming%2Fdsh-data-agent?style=flat-square&label=npm" alt="npm">
16
+ &nbsp;
17
+ <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License">
18
+ </p>
19
+ <p align="center">
20
+ <a href="https://dshfind.com/en/plugins/omdsh-dev/dsh-data-agent?ref=badge"><img src="https://dshfind.com/api/card/omdsh-dev/dsh-data-agent" alt="dshfind card" width="440"></a>
21
+ </p>
22
+ <p align="center">
23
+ <strong>Connect DeepSeek Harness to databases and turn conversations into data analysis and business insights</strong><br>
24
+ <em>Natural-language queries · Automatic SQL execution · Iterative analysis · Web UI · dsh-tui · Read-only protection</em>
25
+ </p>
6
26
 
7
- This plugin is a Data Agent built on DeepSeek Harness, letting DeepSeek focus on database operations.
27
+ <p align="center">
8
28
 
9
- Leveraging the agent-preset capability of DeepSeek Harness, it adds a Data Mode preset. The preset keeps only the three DSH built-in tools — read, edit, write — and adds custom sql-query / sql-write / sqlcmd database tools in place of the bash tool, free from irrelevant tools and prompts.
29
+ [Project Overview](#project-overview) · [Features](#features) · [Quick Install](#quick-install) · [Web UI](#using-data-agent-in-the-web-ui) · [dsh-tui](#using-data-agent-in-dsh-tui) · [Security](#security)
10
30
 
11
- With this preset, you can configure a database connection right in the conversation UI, grant the AI access to the database, and complete CRUD operations.
31
+ </p>
32
+
33
+ ## Project Overview
34
+
35
+ 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.
36
+
37
+ ![Data analysis charts](assets/charts.png)
12
38
 
13
39
  ## Features
14
40
 
15
- - **Database connection management**: per-session connections to MySQL / PostgreSQL / SQLite / Oracle / Hive / Impala (SQLite uses a file path, Oracle a service name/SID, Hive/Impala a default database). Connection state lives in server memory and survives layout switches; passwords stay in memory and travel to the client via environment variables or stdin connect prefixes — never written to disk on the server.
41
+ - **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.
42
+ - **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.
43
+ - **Web analysis reports (render-analysis)**: In the Web UI the agent can choose, within an ordinary tool call, to produce a single chart or a Dashboard-style report (metric/line/bar/pie/scatter/table views) with an inline preview and a “View analysis” Modal. Whether to chart is the agent's decision — schema exploration, single scalars, and queries without visual value are never forced into charts.
44
+ - **Works with both Web UI and dsh-tui**: For a visual workflow, we recommend [zhu1090093659/dsh-web-ui](https://github.com/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](https://github.com/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.
45
+ - **Connect common business databases**: Supports MySQL, PostgreSQL, SQLite, Oracle, Hive, and Impala across application databases, analytics systems, local data files, and data warehouses.
46
+ - **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.
47
+ - **Stay focused with Data Mode**: The session uses DSH's native `str_replace_editor` for files and keeps `sql-query`, `sql-write`, and `sql-cmd`; Web additionally provides `render-analysis`. Host or community tools such as `describe_image` and `ssh_*` do not leak into Data Mode.
48
+ - **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.
16
49
 
17
- ![Database connection](assets/connection.png)
50
+ 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.
18
51
 
19
- - **Database workbench** (embedded above the session's input bar): connection config card (collapses into a summary row after connecting, expandable for review); schema explorer (a "Tables" button opens a Modal — single-click a database to expand its scrollable table list, click a table to inspect its columns); SQL command box (write and run SQL on the non-agent channel, monospace output). The connection config is persisted to browser localStorage — switching pages or restarting restores the form and auto-reconnects. Once the conversation starts, the workbench becomes the left column and the chat records + input bar sit on the right.
20
- - **Database tools**: `sql-query` runs read-only SQL and returns structured `{ columns, rows, affectedRows, elapsedMs }`; `sql-write` runs one write/management SQL per call with explicit autocommit semantics; `sqlcmd` keeps the original raw terminal output. All three run through the database clients (mysql / psql / sqlite3 / sqlplus / beeline / impala-shell); no shell layer (argv arrays + SQL via stdin), timeouts terminate the process tree, output is bounded and truncated, and one call carries at most one SQL statement.
21
- - **Data Mode preset**: choose "Data Mode" when creating a session — the tool surface is `sql-query`/`sql-write`/`sqlcmd`/`read`/`write`/`edit`, and every other project tool (bash, grep, skill, todo, goal, web, subagent, …) is simply absent, i.e. disabled; non-Data-Mode sessions render no workbench at all.
52
+ ![Database workbench](assets/tables.png)
22
53
 
23
- ![Data Mode preset](assets/settings.png)
54
+ Choose “Data Mode when creating a session, and DSH will use the data-analysis workflow for everything that follows.
24
55
 
25
- - **Standard agent loop**: a data-mode session is an ordinary DSH session — standard turn/step, streaming, tool scheduling, and persistence, with zero host changes.
56
+ ![Data Mode preset](assets/settings.png)
26
57
 
27
58
  ## Quick Install
28
59
 
29
- Two install methods, neither requires a local build (the prebuilt output in
30
- `lib/` is committed, and no `prepare`/`prepack` scripts are declared).
60
+ The Web UI, DSH Desktop, and dsh-tui use separate DSH profiles. Install the plugin into every profile you actually use.
31
61
 
32
62
  ### Method 1: npm (recommended)
33
63
 
34
64
  ```sh
35
- # Install from npm (initializes the profile on first use)
36
65
  dsh plugin --profile web add @yejiming/dsh-data-agent
66
+ dsh plugin --profile desktop add @yejiming/dsh-data-agent
67
+ dsh plugin --profile dsh-tui add @yejiming/dsh-data-agent
37
68
  ```
38
69
 
39
- ### Method 2: GitHub source
70
+ ### Method 2: GitHub
40
71
 
41
72
  ```sh
42
- # Install from the GitHub source (lib/ is committed, no build at install time)
43
73
  dsh plugin --profile web add github:omdsh-dev/dsh-data-agent
74
+ dsh plugin --profile desktop add github:omdsh-dev/dsh-data-agent
75
+ dsh plugin --profile dsh-tui add github:omdsh-dev/dsh-data-agent
44
76
  ```
45
77
 
46
- Verify the install:
78
+ 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.
79
+
80
+ ## Using Data Agent in the Web UI
81
+
82
+ Start the Web UI:
47
83
 
48
84
  ```sh
49
- dsh --profile web --dump-config # the data-agent layer should appear
50
- ls $DSH_HOME/.agent-presets/data-agent/ # agent.cordis.yml + preset.yml (auto-installed)
85
+ dsh --profile web
51
86
  ```
52
87
 
53
- Start the Web GUI:
88
+ Then:
89
+
90
+ 1. Create a session and choose “Data Mode.”
91
+ 2. Click the database button in the top-right of the composer and enter your connection details in the workbench Modal.
92
+ 3. Once connected, ask an analysis question directly in the conversation.
93
+ 4. Follow up on the first result and ask DSH to narrow the scope, compare dimensions, or summarize the conclusions.
94
+
95
+ 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.
96
+
97
+ ### Web analysis reports
98
+
99
+ In the Web UI, Data Mode also provides the render-analysis tool: 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:
100
+
101
+ - 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;
102
+ - Simple questions produce a single main chart (inline preview in the result row); complex questions produce a compact summary plus a “View analysis” button;
103
+ - “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;
104
+ - 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;
105
+ - The tool is Web-only: the dsh-tui tool surface is unchanged and loads no chart or browser dependencies.
106
+
107
+ ## Using Data Agent in dsh-tui
108
+
109
+ Start the terminal interface:
54
110
 
55
111
  ```sh
56
- dsh --profile web
112
+ dsh --profile dsh-tui
57
113
  ```
58
114
 
59
- In the Web GUI: create a session choose the "Data Mode" preset the database workbench appears above the input bar → fill in the connection info (type/host/port/user/password/database; SQLite uses a file path) → after connecting, browse schemas (single-click a database to expand tables, click a table for its structure) or run SQL directly in the command box → once the conversation starts the workbench moves to the left; in Chat ask the AI to "list all tables and count rows" or "write a SQL query for orders in the last 30 days, save it to orders.sql and run it".
115
+ In a blank session, switch to Data Mode and connect a database:
60
116
 
61
- > Database client binaries: sqlite3 usually ships with macOS/Linux; mysql / psql / sqlplus / beeline / impala-shell must be provided by the deployment and can be overridden per type via the `clients` config (missing clients are named in the connect error).
117
+ ```text
118
+ /preset data-agent
119
+ /database connect
120
+ ```
62
121
 
63
- ## Architecture
122
+ 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.
123
+
124
+ After connecting, return to the chat input and ask a business question. Other useful database commands include:
64
125
 
65
126
  ```text
66
- Browser (apps/web) Host process (dsh --profile web)
67
- ┌─────────────────────────────┐ ┌──────────────────────────────────────┐
68
- Database workbench (input.dock) │ fetch │ @yejiming/dsh-data-agent (host row)│
69
- │ · connection config (6 types) │ ─────▶ │ · /plugins/data-agent/* routes │
70
- │ · schema explorer + SQL box │ │ · dataAgentConnections store │
71
- │ · hero stacked / active rail │ │ · preset self-install → $DSH_HOME/ │
72
- └─────────────────────────────┘ └──────────────┬───────────────────────┘
73
- │ same process
74
- data-agent session (full agent loop reuse) ▼
75
- ┌──────────────────────────────────────────────────────────────────────────┐
76
- │ agent.cordis.yml (preset layer, only 3 rows) │
77
- │ · persona → data-engineer system prompt │
78
- │ · dsh-tool-fs → read / write / edit (project built-ins) │
79
- │ · dsh-data-agent/tool → sql-query / sql-write / sqlcmd (tool half) │
80
- └──────────────────────────────────────────────────────────────────────────┘
127
+ /database status Show the current connection
128
+ /database test Test the current connection
129
+ /database disconnect Disconnect the current database
81
130
  ```
82
131
 
83
- One npm package, three loadable faces, two host rows:
132
+ 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.
133
+
134
+ ![Data analysis in dsh-tui](assets/tui.png)
135
+
136
+ ## How to Ask Better Analysis Questions
137
+
138
+ For more valuable results, include the business goal, time range, and dimensions you care about. For example:
84
139
 
85
- | Face | Entry | Loaded by |
86
- |---|---|---|
87
- | Server half (connection store / preset self-install) | `lib/index.js` (host row `data-agent`) | Host composition: provides `dataAgentConnections`, seeds connections, self-installs the preset; works headless too |
88
- | Server half (HTTP routes) | `lib/routes.js` (host row `data-agent-routes`, exports subpath `./routes`) | Host composition: registers routes via a nested inject only where a webserver exists (skipped automatically headless) |
89
- | Tool half | `lib/tool.js` (exports subpath `./tool`) | Only mounted by the data-agent preset (`tool-sqlcmd` row) |
90
- | Browser half | `lib/client.js` (`dsh.client` declaration) | Browser: the database workbench in the input dock (`conversation.input.dock`) |
140
+ ```text
141
+ Analyze revenue and gross-margin changes by region in Q2 2026.
142
+ Find the regions with unusual performance, drill down into categories and key customers,
143
+ and recommend three concrete business actions.
144
+ ```
91
145
 
92
- The tool half only consumes host services (`tools`, `subprocess`, `dataAgentConnections`) and provides none, so the preset guard needs no `isolate` realm.
146
+ You can also ask DSH to save the SQL or analysis so it can be reviewed and reused:
93
147
 
94
- ## Configuration
148
+ ```text
149
+ Complete a member repeat-purchase analysis, save the final SQL to
150
+ analysis/repurchase.sql, and summarize the main findings in a format suitable for a weekly report.
151
+ ```
95
152
 
96
- Every field has a loader default; there are no library-level defaults. Host row `data-agent`:
153
+ ## Before You Start
97
154
 
98
- | Key | Meaning |
99
- |---|---|
100
- | `presetId` | Preset directory name installed under `$DSH_HOME/.agent-presets/` (default `data-agent`) |
101
- | `installPreset` | Whether to self-install the preset on startup (default true; existing directories are skipped, keeping user edits) |
102
- | `connectTimeoutMs` | End-to-end deadline for one /connect connectivity check (default 10000 ms) |
103
- | `introspectMaxTables` | Cap on the table list returned by /connect and /status (default 500) |
104
- | `queryTimeoutMs` | Deadline for one database-tool query (default 30000 ms) |
105
- | `maxResultChars` | In-memory cap on captured database-tool output, per stream (default 20000 chars) |
106
- | `clients` | Per-type CLI client overrides: `{ command?, args? }` for keys `mysql` / `postgres` / `sqlite` / `oracle` / `hive` / `impala` (built-in defaults mysql/psql/sqlite3/sqlplus/beeline/impala-shell) |
107
- | `connections` | Config-seeded connections keyed by session id (`'*'` = wildcard default for any session without its own; headless/keyless runs and deployments pinning one database). **No password field** — passwords only enter memory via the /connect route |
155
+ DSH must be able to reach the target database from your machine, and the corresponding database client must be installed:
108
156
 
109
- The `tool-sqlcmd` row (inside the data-agent preset) additionally has `maxRows` (default 100, enforced: an unbounded SELECT gets a top-level LIMIT and structured parsing truncates as a second guard); `queryTimeoutMs` / `maxResultChars` / `clients` share the host row's names and defaults.
157
+ - SQLite is usually included with macOS or Linux.
158
+ - MySQL requires the `mysql` client.
159
+ - PostgreSQL requires the `psql` client.
160
+ - Oracle, Hive, and Impala require their respective command-line clients.
110
161
 
111
- The `data-agent-routes` row has its own config: `connectTimeoutMs` / `introspectMaxTables` / `maxResultChars` mirror the main row; plus `queryTimeoutMs` (for /query and metadata queries, default 30000) and `maxQueryChars` (single-SQL length cap for /query, default 65536).
162
+ 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.
163
+
164
+ 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:
112
165
 
113
166
  ```yaml
114
- # Example override in cordis.patch.yml or a profile layer
115
167
  - id: data-agent
116
- name: '@yejiming/dsh-data-agent'
117
168
  config:
118
169
  clients:
119
170
  mysql:
120
- command: /usr/local/bin/mysql-client
121
- # Wildcard default connection: sessions without an explicit /connect fall back
122
- # to this database (password-free scenario only)
123
- connections:
124
- '*':
125
- type: sqlite
126
- database: /tmp/analytics.db
171
+ searchPaths:
172
+ - /opt/company/mysql/bin
173
+ # command: /opt/company/mysql/bin/mysql
127
174
  ```
128
175
 
129
- ## Headless / One-shot Runs
130
-
131
- **Important**: `dsh run` (the headless bundle) does not mount the agent-presets roster and never mounts presets for sessions — preset mounting belongs to the web surface (the api-proxy mounts on session creation). Therefore **headless sessions cannot use the sql-query/sql-write/sqlcmd/read/write/edit tool surface**; the database tools are verified and used on the web surface. Headless database work is limited to the host base's own tools (e.g. calling clients via bash).
132
-
133
- (Note: inserting the roster row plus disabling the base tool rows cannot reproduce the preset tool surface headless — the agent ends up with an empty, zero-tool composition. For a headless smoke test, verify "seeded connections + host tools work" only.)
134
-
135
- The `data-agent-routes` row is skipped automatically in profiles without a webserver (nested inject), so nothing needs special handling.
176
+ 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`.
136
177
 
137
- ## HTTP API
178
+ We recommend creating a read-only database account so Data Agent can explore and analyze data without modifying production records.
138
179
 
139
- Prefix `/plugins/data-agent` (same-origin calls from the browser half):
180
+ 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`.
140
181
 
141
- | Method/Path | Meaning |
142
- |---|---|
143
- | `POST /connect` | body `{ sessionId, type, host?, port?, user?, database, password? }`; validate → connectivity check (list tables) → save only on success, returns `{ ok, tables }`, failure returns `{ ok: false, error }` without saving |
144
- | `POST /disconnect` | body `{ sessionId }`; drop the session's connection |
145
- | `GET /status?sessionId=` | `{ connected, summary? }`; summary is the password-stripped connection plus the table list |
146
- | `GET /schemas?sessionId=` | `{ ok, schemas: string[] }`; database list (sqlite returns `['main']`) |
147
- | `GET /tables?sessionId=&schema=` | `{ ok, tables: string[] }`; tables of one schema (sqlite ignores the schema param) |
148
- | `GET /describe?sessionId=&schema=&table=` | `{ ok, columns: [{ name, type, nullable? }] }`; table structure (sqlite ignores schema) |
149
- | `POST /query` | body `{ sessionId, sql }`; runs one SQL statement (the workbench command box, non-agent channel), returns `{ ok, result: { exitCode, stdout, stderr, truncated } }`; `sql` length capped by `maxQueryChars`; multiple statements are rejected; readonly rejects writes |
182
+ ## Security
150
183
 
151
- Schema/table identifiers allow only `[A-Za-z0-9_$]` (server-side whitelist and per-type quoting; injection-shaped input is rejected).
184
+ - Prefer a read-only database account and enable read-only mode in the connection form.
185
+ - 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.
186
+ - If authentication must be restored across processes, use a DSH credential reference instead of putting a plaintext password in command arguments.
187
+ - 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.
188
+ - Database connections are isolated by session, making it easier to keep different projects, customers, and analysis environments separate.
152
189
 
153
- ## Security Notes
154
-
155
- - **Passwords**: server-side, memory only; transport per type — mysql via `MYSQL_PWD`, postgres via `PGPASSWORD` environment variables; oracle via the sqlplus `connect user/pass@...` stdin prefix, hive via the beeline `!connect` stdin prefix (never argv); impala sends no password by default (LDAP/kerberos configured through `clients`). `/status` and the public connection-store reads strip passwords.
156
- - **Connection-config persistence**: the workbench saves the connection config (type/host/port/user/database) to browser localStorage (key `dsh-data-agent.connection.v1`) to restore the form and auto-reconnect once on page switches/restarts. **Passwords are not persisted by default**; they are stored only when "remember password" is explicitly checked (plain-text localStorage, opt-in). To clear: run `localStorage.removeItem('dsh-data-agent.connection.v1')` in the browser console.
157
- - **No shell layer**: `ctx.subprocess.spawn` uses argv arrays, SQL and connect prefixes travel via stdin — no shell concatenation injection surface; metadata route identifiers pass the whitelist.
158
- - **SQL execution authority**: with the approval policy set to `never`, `sql-write`/`sqlcmd` and `/query` execute DDL/DML directly — connections are session-isolated; assess the data-plane risk yourself. `readonly: true` rejects write statements; each database-tool call is an independent client process with autocommit, so transactions do not span calls.
159
- - **Timeouts & caps**: query timeouts, output truncation, table-list caps, and the /query SQL length are all config items — no hard-coded tunables.
160
-
161
- ## Uninstall & Rollback
190
+ ## Uninstall and Rollback
162
191
 
163
192
  ```sh
164
- dsh plugin --profile web remove @yejiming/dsh-data-agent # removes the dependency and its layer
165
- rm -rf $DSH_HOME/.agent-presets/data-agent # manually delete the self-installed preset
193
+ dsh plugin --profile web remove @yejiming/dsh-data-agent
194
+ dsh plugin --profile desktop remove @yejiming/dsh-data-agent
195
+ dsh plugin --profile dsh-tui remove @yejiming/dsh-data-agent
196
+ rm -rf $DSH_HOME/.agent-presets/data-agent
166
197
  ```
167
198
 
168
- Connections are in-memory; there is no persisted data to clean up.
169
-
170
- ## Development
199
+ 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.
171
200
 
172
- Build and test:
201
+ ## Local Development
173
202
 
174
203
  ```sh
175
- pnpm build # cleans and rebuilds lib/ (tsdown: lib/index.js, lib/routes.js, lib/tool.js, lib/invariant.js, lib/client.js) + tsc declarations
176
- pnpm test # vitest: connection store / CLI templates / sqlcmd execution (mocked subprocess)
204
+ pnpm install
205
+ pnpm build
206
+ pnpm test
177
207
  ```
178
208
 
179
- `lib/` is committed, so installing and debugging (including `dsh plugin add .`)
180
- never requires a build. To rebuild the artifacts, just run `pnpm install`: all
181
- `@deepseek-ai/*` dependencies are published on npm, so there is no need to copy
182
- or symlink `node_modules` from a local DSH checkout anymore.
183
- `pnpm-workspace.yaml` follows the dsh convention (`nodeLinker: hoisted`); pnpm
184
- 11's supply-chain policy blocks freshly published packages and dependency build
185
- scripts, so the repository pre-declares `minimumReleaseAgeExclude` (the rc.6
186
- family) and `allowBuilds: esbuild`.
209
+ The prebuilt `lib/` directory is committed to the repository, so npm and GitHub installations do not require a local build.
187
210
 
188
211
  ## License
189
212
 
190
213
  MIT
191
214
 
192
- ## Friends
215
+ ## Related Links
193
216
 
194
- - [dshfind.com](https://dshfind.com): Chinese learning & sharing community for DeepSeek Harness — read the papers, write plugins, see the whole ecosystem.
195
- - [dsh-web-ui](https://github.com/dsh-external/dsh-web-ui): Plugins & skins collection for the DeepSeek Harness (DSH) Web UI
196
- - [dsh-cc-tui](https://github.com/dsh-external/dsh-cc-tui): Claude Code style fullscreen interactive terminal plugin
217
+ - [dshfind.com](https://dshfind.com): A Chinese learning and sharing community for DeepSeek Harness
218
+ - [dsh-web-ui](https://github.com/dsh-external/dsh-web-ui): A collection of plugins and skins for the DeepSeek Harness Web UI
219
+ - [dsh-cc-tui](https://github.com/dsh-external/dsh-cc-tui): A Claude Code-style full-screen terminal interface