@yejiming/dsh-data-agent 0.0.11 → 0.0.13

package/README.en.md

@@ -26,7 +26,7 @@
 
 <p align="center">
 
-[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)
+[Project Overview](#project-overview) · [Ecosystem Status](#ecosystem-specification-status) · [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)
 
 </p>
 
@@ -36,18 +36,39 @@ dsh-data-agent is a data analysis plugin for DeepSeek Harness (DSH). Connect a d
 
 ![Data analysis charts](assets/charts.webp)
 
+## Ecosystem Specification Status
+
+This package includes an experimental declaration for the [DSH Ecosystem Specification](https://github.com/T-Auto/dsh-ecosystem-spec) Community v0.15. It does not replace or double-register the existing Cordis behavior. The native bundle, preset, commands, tools, routes, Web UI, TUI form, and connection storage remain the sole functional implementation.
+
+| Item | Current status |
+| --- | --- |
+| Specification and stage | Community v0.15, Draft / Experimental |
+| Pinned baseline | `dsh-ecosystem-spec@ec80a4be5d92bbb971655afd0f097bb5586a1a28`; `dsh-std@614dfa1ac168db79fcf4577cf0ebb34e2e3b944b` |
+| Manifest | `dsh-plugin.json`, `manifestVersion: 0.15`, package identity `@yejiming/dsh-data-agent@0.0.13` |
+| Admission decision | The repository's eligible fixture is `compatible`; this is not an admission result from a real dsh-TUI Host |
+| Evidence level | `Parsed`; fixture negotiation is recorded only as `fixture-only` and does not become `Negotiated` evidence |
+| Exercised environment | Offline parser/projector/definition validation; disposable local mount/unmount with `@dsh-std/adapter-dsh@0.1.0-rc3` |
+| Artifact | The release identity is package name and version; a tarball SHA-256 is written only to an external sidecar after a real `npm pack`, never into the source manifest |
+| Unverified | Real Host Descriptor, real Web/Desktop/dsh-tui, real TTY, database, remote, attach/detach, multiple Presentation, `Observed`, and `Attested` evidence |
+
+Active restrictions include intentionally leaving `UserInteraction` undeclared because the pinned Community manifest cannot carry the requirement spec required by its dsh-std definition. Model tools, the agent preset, Cordis service, HTTP routes, Web slots, persistence domain, and local TTY remain native DSH behavior. During `@dsh-std/adapter-dsh` discovery, the ecosystem facet publishes only a degraded snapshot and no second Command, Tool, or UI handler.
+
+The plugin remains **trusted in-process** and is not sandboxed. Manifest permissions are Host admission contracts; they do not provide OS, process, or realm isolation. These results are not official DSH certification, security approval, a vulnerability-free guarantee, or a universal Host compatibility claim.
+
 ## 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.
-- **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.
-- **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.
-- **Connect common business databases**: Supports MySQL, PostgreSQL, SQLite, Oracle, Hive, and Impala across application databases, analytics systems, local data files, and data warehouses.
+- **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.
+- **Shares the core path across 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 share the database service and tool protocol; validate the exact version and deployment separately.
+- **Connect common business databases**: Supports MySQL, PostgreSQL, SQLite, Oracle, Hive, Impala, ClickHouse, Apache Doris, and SQL Server 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`, and `sql-cmd`; Web additionally provides `render-analysis`. Host or community tools such as `describe_image` and `ssh_*` do not leak into Data Mode.
+- **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.
+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. MySQL browsing verifies each schema with the current account and hides only schemas that explicitly deny database access; authorized system and application schemas remain visible. Before and after the conversation starts, it no longer occupies the area above the composer or a left sidebar.
+
+The SQL tab renders read-query results as a structured table with a sticky header, 100-row pages, and local horizontal scrolling for wide datasets. The complete loaded result can be exported as Excel (`.xlsx`), UTF-8 CSV, or copied to the clipboard, with a hard limit of 50,000 rows per query. Write/administrative commands and errors remain text messages instead of being misparsed as tables.
 
 ![Database workbench](assets/tables.webp)
 
@@ -90,18 +111,25 @@ Then:
 
 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.
 
-### Web analysis reports
+### Analysis reports and HTML artifacts
 
-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:
+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;
-- The tool is Web-only: the dsh-tui tool surface is unchanged and loads no chart or browser dependencies.
+- 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:
+
+```sh
+dsh plugin --profile dsh-tui add @yejiming/dsh-data-agent
+```
+
 Start the terminal interface:
 
 ```sh
@@ -115,7 +143,7 @@ In a blank session, switch to Data Mode and connect a database:
 /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.
+The connection form displays all relevant fields together. Use Tab or Shift+Tab to move between fields. Press Enter on database type, ClickHouse HTTPS, or read-only mode to show every option, use the arrow keys to select one, and press Enter again to confirm. For a network database, enter either a temporary password or a DSH credential reference, never both.
 
 After connecting, return to the chat input and ask a business question. Other useful database commands include:
 
@@ -125,7 +153,9 @@ After connecting, return to the chat input and ask a business question. Other us
 /database disconnect   Disconnect the current 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.
+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 form in the same session, it first restores that session's latest database type, host, port, user, database, ClickHouse HTTPS, and read-only mode, and restores the credential-reference name from its connected profile. A new session with no configuration uses the most recently connected non-secret profile as editable defaults, but remains disconnected until you confirm the connection. A temporary password always remains masked and is never restored.
 
 ## How to Ask Better Analysis Questions
 
@@ -152,10 +182,17 @@ DSH must be able to reach the target database from your machine, and the corresp
 - MySQL requires the `mysql` client.
 - PostgreSQL requires the `psql` client.
 - Oracle, Hive, and Impala require their respective command-line clients.
+- Apache Doris uses the MySQL protocol on port 9030 by default and requires a `mysql` client with `utf8mb4` support. The first release browses databases and tables in the current/internal catalog only.
+- SQL Server uses port 1433 by default and requires Microsoft ODBC `sqlcmd` 18.x. The first release supports SQL Login only—not integrated/Windows/Entra authentication, DSNs, or named instances.
+- ClickHouse does not require `clickhouse-client`. The plugin uses the bundled official `@clickhouse/client` 1.23.x HTTP adapter: HTTP defaults to 8123; selecting HTTPS defaults to 8443 and retains normal certificate verification. Validate the actual ClickHouse Server/Cloud combination with deployment smoke tests rather than inferring universal Cloud/TLS compatibility.
 
 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:
+MySQL and Doris invocations include `--default-character-set=utf8mb4` by default, preventing Windows code pages from corrupting Chinese database, table, column, or query-result text before it reaches DSH. You do not need to repeat this argument in the profile.
+
+SQL Server reads use T-SQL `TOP` or an existing `OFFSET ... FETCH` clause and never append `LIMIT`. To prevent `sqlcmd` scripting from crossing the SQL boundary, `GO`, `!!`, colon commands, and `$(...)` substitutions are rejected before the client starts. The plugin does not add `-C` or another trust-server-certificate option by default.
+
+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, or use `args` for other CLI arguments. The current profile PATH always wins, and `searchPaths` is checked before platform defaults:
 
 ```yaml
 - id: data-agent
@@ -165,6 +202,14 @@ If a client lives in a company toolchain or another custom directory, add search
         searchPaths:
           - /opt/company/mysql/bin
         # command: /opt/company/mysql/bin/mysql
+        # args:
+        #   - --protocol=tcp
+      # Doris can override the shared mysql client location:
+      # doris:
+      #   searchPaths: [/opt/company/mysql/bin]
+      # SQL Server can override the Microsoft ODBC sqlcmd location:
+      # sqlserver:
+      #   searchPaths: [/opt/mssql-tools18/bin]
 ```
 
 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`.
@@ -177,9 +222,11 @@ If you see `failed to mount` or a missing `@yejiming/dsh-data-agent` package err
 
 - 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.
+- If authentication must be restored across processes, enter a DSH credential reference in the TUI form or pass it with `--password-ref`. The form restores the reference name, but never reads, displays, or persists its resolved password.
+- MySQL/Doris and SQL Server passwords enter only `MYSQL_PWD` and `SQLCMDPASSWORD`, respectively. A ClickHouse password enters only the official HTTP client's authentication field—not the URL, argv, or persisted configuration.
 - 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.
+- The plugin and ecosystem adapter run inside the DSH process; neither is an OS, process, or realm sandbox. Ecosystem permissions support admission negotiation and do not replace database-account controls, network isolation, or runtime security policy.
 
 ## Uninstall and Rollback
 
@@ -187,10 +234,15 @@ If you see `failed to mount` or a missing `@yejiming/dsh-data-agent` package err
 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.
+A normal uninstall removes the plugin from the selected profile and disposes runtime effects. It does not automatically delete the installed Data Mode preset or saved non-secret connection information. To remove the preset explicitly, first verify that `DSH_HOME` points to the intended profile data directory, then run:
+
+```sh
+rm -rf "$DSH_HOME/.agent-presets/data-agent"
+```
+
+Purging connection storage is a separate destructive operation. Back it up first, then use the target DSH profile's storage-management path to remove the `data_agent_connections@1` records. Removing the ecosystem manifest or rolling back the adapter layer requires no data migration; any previously published ecosystem claim must be explicitly expired or revoked.
 
 ## Local Development
 
@@ -198,10 +250,13 @@ Uninstalling the plugin does not automatically delete saved non-secret connectio
 pnpm install
 pnpm build
 pnpm test
+pnpm conformance
 ```
 
 The prebuilt `lib/` directory is committed to the repository, so npm and GitHub installations do not require a local build.
 
+Upgrading the specification baseline requires an explicit update to both revisions and pinned digests in `conformance/dsh-ecosystem/baseline.json`, offline conformance against the matching local checkouts, review of inventory/restriction drift, and a complete build and test run. Generate release evidence with `pnpm conformance:artifact --output-dir <outside-worktree-directory>` so a real `npm pack` tarball produces an external sidecar. Documentation and claims must stay within the weakest verified evidence level in that sidecar.
+
 ## License
 
 MIT

package/README.md

@@ -26,7 +26,7 @@
 
 <p align="center">
 
-[项目简介](#项目简介) · [主要功能](#主要功能) · [快速安装](#快速安装) · [Web UI](#在web-ui中使用) · [dsh-tui](#在dsh-tui中使用) · [安全说明](#安全说明)
+[项目简介](#项目简介) · [生态规范状态](#生态规范状态) · [主要功能](#主要功能) · [快速安装](#快速安装) · [Web UI](#在web-ui中使用) · [dsh-tui](#在dsh-tui中使用) · [安全说明](#安全说明)
 
 </p>
 
@@ -36,18 +36,39 @@ dsh-data-agent是DeepSeek Harness（DSH）的数据分析插件。连接数据
 
 ![数据分析图表](assets/charts.webp)
 
+## 生态规范状态
+
+本包附带一层实验性的 [DSH Ecosystem Specification](https://github.com/T-Auto/dsh-ecosystem-spec) Community v0.15 声明。它不会替代或重复注册现有 Cordis 功能；原生 bundle、preset、命令、工具、路由、Web UI、TUI 表单和连接存储仍是唯一功能实现。
+
+| 项目 | 当前状态 |
+| --- | --- |
+| 规范与阶段 | Community v0.15，Draft / Experimental |
+| 固定基线 | `dsh-ecosystem-spec@ec80a4be5d92bbb971655afd0f097bb5586a1a28`；`dsh-std@614dfa1ac168db79fcf4577cf0ebb34e2e3b944b` |
+| Manifest | `dsh-plugin.json`，`manifestVersion: 0.15`，包身份 `@yejiming/dsh-data-agent@0.0.13` |
+| 准入结果 | 仓库内 eligible fixture 为 `compatible`；这不是实际 dsh-TUI Host 的准入结论 |
+| 证据等级 | `Parsed`；fixture negotiation 只记录为 `fixture-only`，不提升为 `Negotiated` |
+| 已执行环境 | 离线 parser/projector/definition 校验；`@dsh-std/adapter-dsh@0.1.0-rc3` 一次性本地 fixture 挂载/卸载 |
+| Artifact | 发布物身份为包名和版本；tarball SHA-256 只在真实 `npm pack` 后写入工作树外 sidecar，不嵌入 source manifest |
+| 未验证 | 真实 Host Descriptor、真实 Web/Desktop/dsh-tui、真实 TTY、数据库、remote、attach/detach、多 Presentation、`Observed`、`Attested` |
+
+主要限制包括：`UserInteraction` 因固定 Community manifest 无法携带 dsh-std definition 所需 requirement spec 而暂不声明；模型工具、agent preset、Cordis service、HTTP routes、Web slots、持久化域和本地 TTY 仍由原生 DSH 路径拥有。安装 `@dsh-std/adapter-dsh` 进行发现时，生态 facet 只发布降级快照，不发布第二个 Command、Tool 或 UI handler。
+
+该插件仍是 **trusted in-process**、非沙箱代码。Manifest permission 是 Host 的准入契约，不提供 OS、进程或 realm 隔离。上述结果不代表 DSH 官方认证、安全批准、无漏洞保证或对所有 Host 的普遍兼容承诺。
+
 ## 主要功能
 
 - **通过对话完成数据分析**：直接用自然语言描述目标，DSH会理解问题、拆解分析步骤、查询真实数据并整理结论。你可以继续追问，分析会沿着当前上下文逐步深入。
 - **自动寻找商业洞察**：不仅返回查询结果，还能帮助比较趋势、定位异常、识别高价值客户或商品，并把数据转化为便于业务决策的说明。
-- **Web 分析报告（render-analysis）**：Web 界面中 Agent 可在普通工具调用里自主生成单图或 Dashboard 式综合分析报告（metric/line/bar/pie/scatter/table 视图），结果行提供内联预览与「查看分析」Modal；是否画图由 Agent 按问题判断，schema 探查、单标量等查询不会被强制生成图表。
-- **完整兼容Web UI与dsh-tui**：喜欢可视化操作时，可以在Web界面连接数据库、浏览库表和查看结果，推荐使用[zhu1090093659/dsh-web-ui](https://github.com/zhu1090093659/dsh-web-ui)；习惯键盘工作流时，可以在终端中使用同一“数据模式”，通过`/database`完成连接，然后直接开始对话分析，推荐使用[ccch1mneyyy/dsh-TUI](https://github.com/ccch1mneyyy/dsh-TUI)。两种界面都能使用数据Agent的核心能力。
-- **连接常见业务数据库**：支持MySQL、PostgreSQL、SQLite、Oracle、Hive和Impala，可用于业务系统、分析库、本地数据文件及数仓场景。
+- **跨界面HTML分析报告（render-analysis）**：Agent可在普通工具调用里自主生成单图或Dashboard式综合分析报告（metric/line/bar/pie/scatter/table视图）。每次成功调用都会在当前工作目录的`analysis-reports/`中保存一份离线可打开的HTML；Web同时提供内联预览与“查看分析”Modal，dsh-tui直接返回文件路径。是否画图由Agent按问题判断，schema探查、单标量等查询不会被强制生成图表。
+- **共享Web UI与dsh-tui核心路径**：喜欢可视化操作时，可以在Web界面连接数据库、浏览库表和查看结果，推荐使用[zhu1090093659/dsh-web-ui](https://github.com/zhu1090093659/dsh-web-ui)；习惯键盘工作流时，可以在终端中使用同一“数据模式”，通过`/database`完成连接，然后直接开始对话分析，推荐使用[ccch1mneyyy/dsh-TUI](https://github.com/ccch1mneyyy/dsh-TUI)。两种界面共享数据Agent的数据库服务和工具协议；具体版本与部署仍应分别验证。
+- **连接常见业务数据库**：支持MySQL、PostgreSQL、SQLite、Oracle、Hive、Impala、ClickHouse、Apache Doris和SQL Server，可用于业务系统、分析库、本地数据文件及数仓场景。
 - **DSH自动完成分析闭环**：DSH会根据当前问题查看表结构、编写SQL、执行查询，并结合报错或返回结果继续调整，而不是只生成一段未经验证的SQL。
-- **专注数据任务的数据模式**：会话使用DSH原生`str_replace_editor`处理文件，并保留`sql-query`、`sql-write`、`sql-cmd`；Web额外提供`render-analysis`。`describe_image`、`ssh_*`等宿主或社区插件工具不会进入数据模式。
+- **专注数据任务的数据模式**：会话使用DSH原生`str_replace_editor`处理文件，并保留`sql-query`、`sql-write`、`sql-cmd`与`render-analysis`；Web、Desktop、dsh-tui和headless profile使用同一工具协议。`describe_image`、`ssh_*`等宿主或社区插件工具不会进入数据模式。
 - **安全地使用真实数据**：支持只读模式和数据库只读账号；TUI密码会被隐藏，且不会作为表单草稿恢复。是否允许修改数据由你决定。
 
-Web UI还提供按需数据库工作台：点击输入框右上角的数据库按钮，即可在同一个Modal中配置连接、浏览库表、查看字段结构或临时运行SQL。开始对话前后都不占用输入框上方或左侧的对话空间。
+Web UI还提供按需数据库工作台：点击输入框右上角的数据库按钮，即可在同一个Modal中配置连接、浏览库表、查看字段结构或临时运行SQL。MySQL库表浏览会用当前账号逐库验证访问权限，只隐藏明确返回无权访问的库；有权限的系统库与业务库都会正常显示。开始对话前后都不占用输入框上方或左侧的对话空间。
+
+SQL命令页会把读查询结果显示为带固定表头的结构化表格，并按100行分页，宽表可在结果区内横向滚动。当前结果可导出为Excel（`.xlsx`）、UTF-8 CSV或复制到剪贴板；三种导出都包含已加载的完整结果，单次最多50,000行。写入/管理命令及错误仍显示为文本消息，不会被误解析成表格。
 
 ![数据库工作台](assets/tables.webp)
 
@@ -90,18 +111,25 @@ dsh --profile web
 
 例如，输入“分析最近30天订单变化，找出销售额下降最明显的地区和商品，并解释主要原因”，DSH会自行查看相关表、生成并执行查询，再根据真实结果完成分析。
 
-### Web 分析报告
+### 分析报告与HTML文件
 
-在 Web UI 中，数据模式还提供 render-analysis 工具：Agent 会先用 sql-query 探查并核对事实，再自行判断可视化是否有帮助。判断需要画图时，一次工具调用会生成一份版本化分析报告：
+数据模式提供render-analysis工具：Agent会先用sql-query探查并核对事实，再自行判断可视化是否有帮助。判断需要画图时，一次工具调用会生成一份版本化分析报告：
 
 - 报告包含 1-6 个只读数据集与 1-8 个视图（metric、line、bar、pie、scatter、table），同一数据集可被多个视图复用，聚合与 Top N 都写在 SQL 中；
 - 简单问题生成单个主图（结果行内联预览），复杂问题生成紧凑摘要 + 「查看分析」按钮；
 - 「查看分析」在大型 Modal 中展示本次报告的全部视图：紧凑指标带、全宽主图、双列辅助图与明细表，浅色/深色主题与窄屏单列自适应；
+- 无论当前使用哪种UI，完整Dashboard都会原子保存到会话工作目录的`analysis-reports/*.html`，并在支持的DSH界面进入“产物”栏；文件名默认使用报告标题，也可用语义化`outputName`指定basename，不追加长UUID；文件内联数据、样式和SVG渲染代码，断网时也能直接打开；
 - 完整报告快照随会话日志持久化：刷新或历史回放不重新查询数据库，也不产生新的浏览器存储；
-- 仅 Web 提供该工具；dsh-tui 的工具面保持不变，也不会加载图表或浏览器依赖。
+- Web仍从同一份报告meta渲染预览；Node侧HTML生成器不加载ECharts或Web client代码。
 
 ## 在dsh-tui中使用
 
+把Data Agent安装到dsh-tui profile即可；`render-analysis`不要求特定dsh-TUI版本或scene能力：
+
+```sh
+dsh plugin --profile dsh-tui add @yejiming/dsh-data-agent
+```
+
 启动终端界面：
 
 ```sh
@@ -115,7 +143,7 @@ dsh --profile dsh-tui
 /database connect
 ```
 
-连接表单会一次展示所有相关字段。使用Tab或Shift+Tab切换输入项；数据库类型和只读模式按Enter展开选项，使用方向键选择并再次按Enter确认。
+连接表单会一次展示所有相关字段。使用Tab或Shift+Tab切换输入项；数据库类型、ClickHouse HTTPS和只读模式按Enter展开选项，使用方向键选择并再次按Enter确认。网络数据库可以二选一填写临时密码或DSH凭据引用，不能同时填写。
 
 连接成功后，回到聊天输入框直接提出业务问题即可。常用的数据库命令还有：
 
@@ -125,7 +153,9 @@ dsh --profile dsh-tui
 /database disconnect   断开当前连接
 ```
 
-同一会话再次打开连接表单时，会恢复最近填写的数据库类型、地址、端口、用户、数据库和只读模式。密码始终隐藏且不会恢复。
+Agent生成分析报告后，工具卡会显示数据集、视图、空数据摘要与HTML绝对路径。TUI不会输出字符Dashboard，也没有`/analysis`命令；直接在本机浏览器中打开该HTML即可查看六类视图和原始数据。文件来自本次工具调用，`/resume`不会重新查询数据库。
+
+同一会话再次打开连接表单时，会优先恢复该会话最近填写的数据库类型、地址、端口、用户、数据库、ClickHouse HTTPS和只读模式，并从已连接profile恢复凭据引用。新会话没有自己的配置时，会用最近一次成功连接的非敏感profile作为表单默认值，但仍是未连接状态，必须确认连接后才能查询。临时密码始终隐藏且不会恢复。
 
 ## 推荐的提问方式
 
@@ -151,10 +181,17 @@ DSH运行查询时需要本机能够访问目标数据库，并安装相应的
 - MySQL需要`mysql`客户端。
 - PostgreSQL需要`psql`客户端。
 - Oracle、Hive和Impala需要各自的命令行客户端。
+- Apache Doris通过MySQL协议连接，默认端口9030，需要支持`utf8mb4`的`mysql`客户端；首版只浏览当前/internal catalog中的数据库和表。
+- SQL Server默认端口1433，需要Microsoft ODBC `sqlcmd` 18.x；首版只支持SQL Login，不支持集成/Windows/Entra认证、DSN或命名实例。
+- ClickHouse不需要`clickhouse-client`。插件使用随包安装的官方`@clickhouse/client` 1.23.x HTTP适配器：HTTP默认8123；勾选HTTPS后默认8443并正常验证服务器证书。实际ClickHouse Server/Cloud组合仍应通过部署侧冒烟验证，不能据此推断所有Cloud/TLS配置都兼容。
 
 插件会先使用当前profile进程的PATH；找不到时，会继续检查客户端HOME环境变量以及Windows、macOS、Linux的常见安装位置，包括Homebrew、MacPorts、Linuxbrew、Snap、Nix、WinGet Links、Scoop、Chocolatey和Program Files下的版本目录。自动发现使用的补充PATH也会传给实际客户端进程，因此从Finder启动的DSH Desktop通常无需再为Homebrew客户端手工配置路径。
 
-如果客户端安装在公司工具链或其他自定义目录，可在当前profile的`data-agent`配置中补充搜索目录；需要锁定具体版本时则直接填写绝对命令路径。当前profile的PATH始终优先，`searchPaths`在系统常见目录之前：
+插件调用MySQL或Doris客户端时会内置`--default-character-set=utf8mb4`，确保Windows代码页不会使库名、表名、字段名或查询结果中的中文在进入DSH前乱码，无需在profile中重复配置该参数。
+
+SQL Server查询使用T-SQL `TOP`或已有的`OFFSET ... FETCH`限行，绝不会追加`LIMIT`。为避免`sqlcmd`自身脚本能力绕过SQL边界，输入中的`GO`、`!!`、冒号命令和`$(...)`变量替换会在启动客户端前被拒绝。插件不会默认添加`-C`或其他“信任服务器证书”选项。
+
+如果客户端安装在公司工具链或其他自定义目录，可在当前profile的`data-agent`配置中补充搜索目录；需要锁定具体版本时则直接填写绝对命令路径，也可通过`args`添加其他CLI参数。当前profile的PATH始终优先，`searchPaths`在系统常见目录之前：
 
 ```yaml
 - id: data-agent
@@ -164,6 +201,14 @@ DSH运行查询时需要本机能够访问目标数据库，并安装相应的
         searchPaths:
           - /opt/company/mysql/bin
         # command: /opt/company/mysql/bin/mysql
+        # args:
+        #   - --protocol=tcp
+      # Doris也可覆盖mysql客户端位置：
+      # doris:
+      #   searchPaths: [/opt/company/mysql/bin]
+      # SQL Server可覆盖Microsoft ODBC sqlcmd位置：
+      # sqlserver:
+      #   searchPaths: [/opt/mssql-tools18/bin]
 ```
 
 Windows路径可以写成`C:\Program Files\MySQL\MySQL Server 9.0\bin`。插件不会下载数据库客户端、执行登录shell或扫描整块磁盘；位于非常规目录且未进入PATH时，仍需使用`searchPaths`或`command`。
@@ -176,9 +221,11 @@ Windows路径可以写成`C:\Program Files\MySQL\MySQL Server 9.0\bin`。插件
 
 - 推荐使用数据库只读账号，并在连接表单中开启只读模式。
 - Web UI和dsh-tui中的临时密码只用于当前连接；TUI只显示`*`，重新打开表单时不会恢复密码。
-- 需要跨进程恢复认证时，可以使用DSH credential reference，避免在命令参数中输入明文密码。
+- 需要跨进程恢复认证时，可以在TUI表单填写DSH credential reference，或通过`--password-ref`传入；表单会恢复引用名，但不会读取、显示或持久化解析后的密码。
+- MySQL/Doris和SQL Server密码分别只传入`MYSQL_PWD`和`SQLCMDPASSWORD`；ClickHouse密码只进入官方HTTP客户端的认证字段，不进入URL、argv或持久化配置。
 - 未开启只读模式时，数据Agent可以按你的要求执行更新或管理语句。连接生产数据库前，请先确认账号权限和数据备份策略。
 - 不同会话的数据库连接相互隔离，便于分别处理不同项目、客户或分析环境。
+- 插件及其生态适配器都运行在DSH进程内，不是OS、进程或realm沙箱；生态permission只能用于准入协商，不能替代数据库账号权限、网络隔离或运行环境安全策略。
 
 ## 卸载与回滚
 
@@ -186,10 +233,15 @@ Windows路径可以写成`C:\Program Files\MySQL\MySQL Server 9.0\bin`。插件
 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
 ```
 
-卸载插件不会主动删除已经保存的非敏感连接信息。若需要彻底清理，请先备份，再删除DSH中对应的数据Agent存储记录。
+普通卸载只移除当前profile中的插件并释放运行时 effect，不会主动删除已安装的“数据模式”preset或已经保存的非敏感连接信息。若要显式清理preset，请在确认`DSH_HOME`指向目标profile数据目录后单独执行：
+
+```sh
+rm -rf "$DSH_HOME/.agent-presets/data-agent"
+```
+
+连接存储的彻底清理是另一个破坏性 purge 操作：请先备份，并通过目标DSH profile的存储管理方式删除`data_agent_connections@1`记录。移除生态manifest或回滚适配层不需要迁移现有数据；任何先前发布的生态claim都应明确标记为过期或撤销。
 
 ## 本地开发
 
@@ -197,10 +249,13 @@ rm -rf $DSH_HOME/.agent-presets/data-agent
 pnpm install
 pnpm build
 pnpm test
+pnpm conformance
 ```
 
 `lib/`已提交到仓库，因此通过npm或GitHub安装时无需自行构建。
 
+升级规范基线必须显式更新`conformance/dsh-ecosystem/baseline.json`中的两个revision和固定digest，使用对应的本地checkout离线运行conformance，复核inventory/restriction漂移，并重新执行完整构建与测试。发布证据应运行`pnpm conformance:artifact --output-dir <工作树外目录>`，从真实`npm pack` tarball生成外部sidecar；文档和claim不得超过其中最弱的已验证证据等级。
+
 ## 许可
 
 MIT

package/conformance/dsh-ecosystem/baseline.json

@@ -0,0 +1,59 @@
+{
+  "baselineVersion": "1",
+  "specification": {
+    "repository": "https://github.com/T-Auto/dsh-ecosystem-spec",
+    "revision": "ec80a4be5d92bbb971655afd0f097bb5586a1a28",
+    "specVersion": "community-v0.15",
+    "profileVersion": "tui-admission/0.15",
+    "manifestVersion": "0.15",
+    "suiteVersion": "dsh-data-agent-ecosystem/1"
+  },
+  "dshStd": {
+    "repository": "https://github.com/Yan-Zero/dsh-std",
+    "revision": "614dfa1ac168db79fcf4577cf0ebb34e2e3b944b",
+    "packages": {
+      "@dsh-std/sdk": {
+        "version": "0.1.0-rc1",
+        "integrity": "sha512-qWGGoJ5TZC8uckbpnFcg6mhXV3/YohPOoxCWVkoZPG/vRmmRUfAdG0l5Ci/XPljekHR9dko2747fhk81l6CBaw=="
+      },
+      "@dsh-std/manifest": {
+        "version": "0.1.0-rc1",
+        "integrity": "sha512-u4iaXOg8N03tPZYgwPwtrzvy7zODdjriQYolS6SyfYFCo5ojZCsACCPK0NZxQgHTVnQVZr8XMBHt/+GvQ++xmg=="
+      },
+      "@dsh-std/adapter-dsh": {
+        "version": "0.1.0-rc3",
+        "integrity": "sha512-FF7h4yXx7hdA5kPegfbTBtpYaQsshzVtMHRXLLKPkgbxqWb8jC9JXVGPsg76TGwIssHydAdZg2Yw3iIWdTHVcQ=="
+      },
+      "@dsh-std/command": {
+        "version": "0.1.0-rc2",
+        "integrity": "sha512-4kvnTxalYz+osXOh6EuPiJU7wCSV8CrXFeHCwfxaPqse0sWcQVQufXmxIhYdPq02KZzlppuwB9ZJmxhFF5eaKw=="
+      },
+      "@dsh-std/storage": {
+        "version": "0.1.0-rc1",
+        "integrity": "sha512-WXIb3v6Gc+6OIsVJS8Bg1PsjRTV5gsWautQRzAAbHh+E2l+ceIVlAH9Ujrvc7n5fQB1emXRHJmylsh2Mjt7PAw=="
+      },
+      "@dsh-std/presentation": {
+        "version": "0.1.0-rc1",
+        "integrity": "sha512-5yqXp+QJa/uSQm2IrfriqYGvf6EvmUCluWIRkH6hTJNNhYMcTUb3aFhLJCA8SlCt96912zy4LHinUbiYZqfH8A=="
+      }
+    }
+  },
+  "sourceDigests": {
+    "manifestSchema": "sha256:78392a63585c202ca1fbd262aa17145a320ee99ba72f0a257f99daa752603b33",
+    "tuiRegistry": "sha256:c3090dd129aadb06f87b56ad148dfbcec2ce4eed2404dda5eed9cf1dbae51f54",
+    "permissionRegistry": "sha256:1e2cfeaa860936f1608cb8a8bffdf6343de6f513645eb98f6765d72157d5a1a7",
+    "requirements": "sha256:88afac254990f7278382b6d352d6a9b8c49df9172ca3f2eceea5a5c604c572e6",
+    "hostDescriptorSchema": "sha256:4b76c43de2d7f8d0b8e171dd96a7a5c9c7732775e0f552e7345074bf95f5755e",
+    "claimSchema": "sha256:447940843bd9324a8864a9cb0018a9a6bc1fd1834865d15419f1e6f85631834f",
+    "effectLedgerSchema": "sha256:bfa0ea159daa1ab801053a946eb4c8f902cb96f83851502f7c3ae314d1ee75aa"
+  },
+  "acceptedFacetApiVersions": ["v1alpha1"],
+  "acceptedContracts": [
+    "commands.dsh/v1alpha1#Command",
+    "storage.dsh/v1alpha1#LocalStorage",
+    "presentation.dsh/v1alpha1#UserInteraction"
+  ],
+  "acceptedPermissions": {
+    "commands.invoke": "allow"
+  }
+}

package/conformance/dsh-ecosystem/dependencies.json

@@ -0,0 +1,41 @@
+{
+  "dependencyInventoryVersion": "1",
+  "runtime": {
+    "packaged": [
+      "@clickhouse/client",
+      "@dsh-std/sdk",
+      "echarts",
+      "fflate",
+      "schemastery",
+      "zod"
+    ],
+    "peerFamilies": [
+      "@deepseek-ai/cordis",
+      "@deepseek-ai/dsh-*",
+      "react"
+    ],
+    "externalExecutables": {
+      "mysql": "mysql",
+      "postgres": "psql",
+      "sqlite": "sqlite3",
+      "oracle": "sqlplus",
+      "hive": "beeline",
+      "impala": "impala-shell",
+      "doris": "mysql",
+      "sqlserver": "sqlcmd"
+    },
+    "httpClients": {
+      "clickhouse": "@clickhouse/client"
+    }
+  },
+  "build": {
+    "commands": ["tsdown", "tsc -p tsconfig.build.json", "tsc -p tsconfig.client.json"],
+    "generated": ["lib/**"],
+    "patches": ["cordis.patch.yml"],
+    "nativeBuildPolicy": {
+      "@deepseek-ai/dsh-subprocess-local": false,
+      "esbuild": true,
+      "node-pty": false
+    }
+  }
+}

package/conformance/dsh-ecosystem/fixtures/host-degraded.fixture.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "urn:dsh-tui:host-descriptor:0.15",
+  "hostId": "fixture.data-agent.degraded",
+  "hostVersion": "0.15-fixture",
+  "facetApiVersions": ["v1alpha1"],
+  "contracts": [
+    { "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "definition": { "source": "dsh-std", "package": "@dsh-std/command" }, "permissions": ["commands.invoke"] }
+  ],
+  "runtime": { "location": "local", "generationId": "fixture-degraded-1", "headless": true, "remoteAttach": false },
+  "trustLevel": "trusted-in-process",
+  "platform": { "os": "fixture", "arch": "fixture", "node": ">=22.19" }
+}

package/conformance/dsh-ecosystem/fixtures/host-eligible.fixture.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "urn:dsh-tui:host-descriptor:0.15",
+  "hostId": "fixture.data-agent.eligible",
+  "hostVersion": "0.15-fixture",
+  "facetApiVersions": ["v1alpha1"],
+  "contracts": [
+    { "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "definition": { "source": "dsh-std", "package": "@dsh-std/command" }, "permissions": ["commands.invoke"] },
+    { "apiVersion": "storage.dsh/v1alpha1", "kind": "LocalStorage", "definition": { "source": "dsh-std", "package": "@dsh-std/storage" }, "permissions": ["storage.local.read", "storage.local.write"] }
+  ],
+  "runtime": { "location": "local", "generationId": "fixture-eligible-1", "headless": false, "remoteAttach": false },
+  "trustLevel": "trusted-in-process",
+  "platform": { "os": "fixture", "arch": "fixture", "node": ">=22.19" }
+}

package/conformance/dsh-ecosystem/fixtures/host-rejected.fixture.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "urn:dsh-tui:host-descriptor:0.15",
+  "hostId": "fixture.data-agent.rejected",
+  "hostVersion": "0.15-fixture",
+  "facetApiVersions": ["v1alpha1"],
+  "contracts": [
+    { "apiVersion": "storage.dsh/v1alpha1", "kind": "LocalStorage", "definition": { "source": "dsh-std", "package": "@dsh-std/storage" }, "permissions": ["storage.local.read", "storage.local.write"] }
+  ],
+  "runtime": { "location": "local", "generationId": "fixture-rejected-1", "headless": true, "remoteAttach": false },
+  "trustLevel": "trusted-in-process",
+  "platform": { "os": "fixture", "arch": "fixture", "node": ">=22.19" }
+}

package/conformance/dsh-ecosystem/fixtures/profiles/native-only/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "dsh-data-agent-native-only-fixture",
+  "private": true,
+  "fixture": true,
+  "dependencies": {
+    "@yejiming/dsh-data-agent": "file:../../../../.."
+  }
+}

package/conformance/dsh-ecosystem/fixtures/profiles/native-plus-adapter/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "dsh-data-agent-native-plus-adapter-fixture",
+  "private": true,
+  "fixture": true,
+  "dependencies": {
+    "@dsh-std/adapter-dsh": "0.1.0-rc3",
+    "@yejiming/dsh-data-agent": "file:../../../../.."
+  }
+}

package/conformance/dsh-ecosystem/inventory.json

@@ -0,0 +1,77 @@
+{
+  "inventoryVersion": "1",
+  "packageName": "@yejiming/dsh-data-agent",
+  "nativeRuntime": {
+    "bundleRows": [
+      "@yejiming/dsh-data-agent",
+      "@yejiming/dsh-data-agent/routes"
+    ],
+    "presetRows": [
+      "@deepseek-ai/dsh-persona",
+      "@deepseek-ai/dsh-tool-str-replace-editor"
+    ],
+    "commands": ["database"],
+    "tools": [
+      "render-analysis",
+      "sql-cmd",
+      "sql-query",
+      "sql-write",
+      "str_replace_editor"
+    ],
+    "services": ["dataAgentConnections"],
+    "routes": [
+      "GET describe",
+      "GET schemas",
+      "GET status",
+      "GET tables",
+      "POST connect",
+      "POST disconnect",
+      "POST query"
+    ],
+    "webSlots": [
+      "conversation.input.right",
+      "tool.call.toolview"
+    ],
+    "storageDomains": ["data_agent_connections@1"],
+    "surfaces": ["desktop", "headless", "tui", "web"],
+    "databaseTypes": [
+      "clickhouse",
+      "doris",
+      "hive",
+      "impala",
+      "mysql",
+      "oracle",
+      "postgres",
+      "sqlite",
+      "sqlserver"
+    ],
+    "publicExports": [
+      ".",
+      "./client",
+      "./command",
+      "./cordis.patch.yml",
+      "./invariant",
+      "./package.json",
+      "./routes",
+      "./src/*",
+      "./tool"
+    ],
+    "packageFiles": [
+      "cordis.patch.yml",
+      "lib/**",
+      "preset/**"
+    ]
+  },
+  "abilities": [
+    { "id": "command:database", "disposition": "declared", "manifestReference": "io.github.omdsh-dev.dsh-data-agent.database" },
+    { "id": "tools:model", "disposition": "upstream-gap", "restrictionId": "tool-extension-not-in-tui-profile" },
+    { "id": "preset:data-agent", "disposition": "upstream-gap", "restrictionId": "agent-preset-not-in-tui-profile" },
+    { "id": "service:dataAgentConnections", "disposition": "upstream-gap", "restrictionId": "cordis-service-not-in-tui-profile" },
+    { "id": "routes:data-agent", "disposition": "restriction", "restrictionId": "http-routes-native-only" },
+    { "id": "ui:web-slots", "disposition": "restriction", "restrictionId": "web-slots-native-only" },
+    { "id": "storage:data_agent_connections", "disposition": "restriction", "restrictionId": "storage-domain-native-only" },
+    { "id": "credentials:resolve", "disposition": "restriction", "restrictionId": "credential-resolution-native-only" },
+    { "id": "subprocess:database-clients", "disposition": "restriction", "restrictionId": "database-execution-native-only" },
+    { "id": "presentation:local-tty", "disposition": "restriction", "restrictionId": "legacy-local-tty" }
+  ]
+}