@yejiming/dsh-data-agent 0.0.6 → 0.0.10

package/README.md

@@ -1,191 +1,211 @@
-# 数据Agent（Data Agent）· 让 AI 帮你连数据库、写 SQL
+# DSH Data Agent · 用对话分析数据
 
-[English](README.en.md) | **中文**
+**中文** | [English](README.en.md)
 
-![数据模式会话](assets/session.png)
+<p align="center">
+  <img src="assets/dsh-data-agent-banner.png" alt="dsh-data-agent HERO图" width="100%">
+</p>
+<p align="center">
+  <img src="https://img.shields.io/github/v/release/omdsh-dev/dsh-data-agent?style=flat-square" alt="Version">
+  &nbsp;
+  <a href="https://dshfind.com/zh/plugins/omdsh-dev/dsh-data-agent?ref=badge"><img src="https://dshfind.com/api/badge/omdsh-dev/dsh-data-agent?lang=zh" alt="dshfind 小标"></a>
+  &nbsp;
+  <img src="https://img.shields.io/github/stars/omdsh-dev/dsh-data-agent?style=flat-square" alt="Stars">
+  &nbsp;
+  <img src="https://img.shields.io/npm/v/@yejiming%2Fdsh-data-agent?style=flat-square&label=npm" alt="npm">
+  &nbsp;
+  <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License">
+</p>
+<p align="center">
+  <a href="https://dshfind.com/zh/plugins/omdsh-dev/dsh-data-agent?ref=badge"><img src="https://dshfind.com/api/card/omdsh-dev/dsh-data-agent?lang=zh" alt="dshfind 展示卡" width="440"></a>
+</p>
+<p align="center">
+  <strong>让DeepSeek Harness连接数据库，用对话完成数据分析与商业洞察</strong><br>
+  <em>自然语言查询 · 自动执行SQL · 连续分析 · Web UI · dsh-tui · 只读保护</em>
+</p>
 
-用AI写过SQL的同学都有这种体验，AI现在写代码能力已经很强了，但SQL逻辑老写不对。**原因是AI并没有与数据库操作形成Agent Loop**，它只能根据静态指令生成SQL，却无法感知执行结果、无法根据报错或返回数据动态调优。
+<p align="center">
 
-这个插件就是来填这个坑的。它复用DeepSeek Harness强大的Agent主循环能力，让AI连上数据库并获得实时反馈，同时删掉所有跟数据无关的上下文和工具，让AI专注于SQL生成和业务数据分析。
+[项目简介](#项目简介) · [主要功能](#主要功能) · [快速安装](#快速安装) · [Web UI](#在web-ui中使用) · [dsh-tui](#在dsh-tui中使用) · [安全说明](#安全说明)
 
-我利用DeepSeek Harness的Agent预设功能，定义了专用的数据模式预设。仅保留read、edit、write三个DSH自带的 tools，并自定义 sql-query / sql-write / sqlcmd 三个数据库 tools 替代 bash tool。
+</p>
 
-懂行的朋友一眼就能看出，这是借鉴了Pi Agent的设计，只使用最基本的工具。
+## 项目简介
 
-用起来也很简单：在对话界面配好数据库连接，授权AI访问权限，然后就可以向AI提问，让AI帮你查询、更新、分析。
+dsh-data-agent是DeepSeek Harness（DSH）的数据分析插件。连接数据库后，直接提出业务问题，DSH会自动查看库表、编写并执行SQL、根据真实结果继续分析，最终给出清晰的数据结论和商业洞察。插件同时支持Web UI与dsh-tui，无需修改DSH源码。
+
+![数据分析图表](assets/charts.png)
 
 ## 主要功能
 
-- **数据库连接管理**：按会话连接 MySQL / PostgreSQL / SQLite / Oracle / Hive / Impala（SQLite 走文件路径，Oracle 填服务名/SID，Hive/Impala 填默认库），连接状态驻留服务端内存，布局切换不丢；密码仅内存、经环境变量或 stdin 连接前缀传给客户端，绝不落盘。
+- **通过对话完成数据分析**：直接用自然语言描述目标，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，可用于业务系统、分析库、本地数据文件及数仓场景。
+- **DSH自动完成分析闭环**：DSH会根据当前问题查看表结构、编写SQL、执行查询，并结合报错或返回结果继续调整，而不是只生成一段未经验证的SQL。
+- **专注数据任务的数据模式**：会话使用DSH原生`str_replace_editor`处理文件，并保留`sql-query`、`sql-write`、`sql-cmd`；Web额外提供`render-analysis`。`describe_image`、`ssh_*`等宿主或社区插件工具不会进入数据模式。
+- **安全地使用真实数据**：支持只读模式和数据库只读账号；TUI密码会被隐藏，且不会作为表单草稿恢复。是否允许修改数据由你决定。
+
+Web UI还提供按需数据库工作台：点击输入框右上角的数据库按钮，即可在同一个Modal中配置连接、浏览库表、查看字段结构或临时运行SQL。开始对话前后都不占用输入框上方或左侧的对话空间。
 
-  ![数据库连接](assets/connection.png)
-- **数据库工作台**（内嵌于会话输入框上方）：连接配置卡（连接成功后折叠为摘要行，可展开查看）；库表浏览（点击「库表」按钮弹出 Modal：单击库展开表列表（可滚动），点击表查看结构）；SQL 命令框（编辑并运行 SQL，非 agent 通道，结果等宽展示）。连接配置持久化到浏览器 localStorage，切换页面/重启自动回填并重连。开始对话后工作台自动变为左侧栏，对话记录与输入框在右侧。
+![数据库工作台](assets/tables.png)
 
-  ![数据库工作台](assets/tables.png)
-- **数据库 tools**：`sql-query` 执行只读 SQL 并返回结构化 `{ columns, rows, affectedRows, elapsedMs }`；`sql-write` 执行写/管理 SQL（单条自动提交，写语义明确）；`sqlcmd` 保留原始终端输出。三者均在数据库客户端（mysql / psql / sqlite3 / sqlplus / beeline / impala-shell）执行；无 shell 层（argv 数组化 + SQL 走 stdin），超时自动终止进程树，输出有界截断，单次调用只允许一条 SQL。
-- **数据模式 预设**：新建会话可选「数据模式」——工具面为 `sql-query`/`sql-write`/`sqlcmd`/`read`/`write`/`edit`，项目其他工具（bash、grep、skill、todo、goal、web、subagent 等）全部缺席即禁用；非数据模式会话不渲染工作台，零影响。
+创建会话时选择“数据模式”，DSH就会以数据分析工作流处理后续问题。
 
-  ![数据模式 预设](assets/settings.png)
-- **标准 agent loop**：data-agent 会话就是普通 DSH 会话，走标准 turn/step、流式输出、工具调度与持久化，零宿主改动。
+![数据模式预设](assets/settings.png)
 
 ## 快速安装
 
-支持两种安装方式，均**无需本地构建**（构建产物 `lib/` 已提交进仓库，且不设
-`prepare`/`prepack` 脚本）。
+Web UI、DSH Desktop和dsh-tui使用独立的DSH profile。请把插件安装到实际使用的profile；同时使用多个界面时，分别执行对应命令。
 
-### 方式一：npm 安装（推荐）
+### 方式一：npm安装（推荐）
 
 ```sh
-# 从 npm 安装（首次使用会初始化该 profile）
 dsh plugin --profile web add @yejiming/dsh-data-agent
+dsh plugin --profile desktop add @yejiming/dsh-data-agent
+dsh plugin --profile dsh-tui add @yejiming/dsh-data-agent
 ```
 
-### 方式二：GitHub 源码安装
+### 方式二：从GitHub安装
 
 ```sh
-# 从 GitHub 源码安装（仓库已提交构建产物 lib/，安装时无需构建）
 dsh plugin --profile web add github:omdsh-dev/dsh-data-agent
+dsh plugin --profile desktop add github:omdsh-dev/dsh-data-agent
+dsh plugin --profile dsh-tui add github:omdsh-dev/dsh-data-agent
 ```
 
-安装后验证：
+插件会自动安装“数据模式”预设，并在profile启动时预加载该预设的数据库工具与命令；选择预设时不再动态导入插件子路径，无需本地构建。
+
+## 在Web UI中使用
+
+启动Web UI：
 
 ```sh
-dsh --profile web --dump-config   # 输出中应出现 data-agent 层
-ls $DSH_HOME/.agent-presets/data-agent/   # 应有 agent.cordis.yml + preset.yml（由插件自动安装）
+dsh --profile web
 ```
 
-启动 Web GUI：
+然后按下面的步骤操作：
+
+1. 新建会话并选择“数据模式”。
+2. 点击输入框右上角的数据库按钮，在工作台Modal中填写连接信息。
+3. 连接成功后，直接在对话框中提出分析问题。
+4. 根据第一轮结果继续追问，让DSH缩小范围、比较维度或总结结论。
+
+例如，输入“分析最近30天订单变化，找出销售额下降最明显的地区和商品，并解释主要原因”，DSH会自行查看相关表、生成并执行查询，再根据真实结果完成分析。
+
+### Web 分析报告
+
+在 Web UI 中，数据模式还提供 render-analysis 工具：Agent 会先用 sql-query 探查并核对事实，再自行判断可视化是否有帮助。判断需要画图时，一次工具调用会生成一份版本化分析报告：
+
+- 报告包含 1-6 个只读数据集与 1-8 个视图（metric、line、bar、pie、scatter、table），同一数据集可被多个视图复用，聚合与 Top N 都写在 SQL 中；
+- 简单问题生成单个主图（结果行内联预览），复杂问题生成紧凑摘要 + 「查看分析」按钮；
+- 「查看分析」在大型 Modal 中展示本次报告的全部视图：紧凑指标带、全宽主图、双列辅助图与明细表，浅色/深色主题与窄屏单列自适应；
+- 完整报告快照随会话日志持久化：刷新或历史回放不重新查询数据库，也不产生新的浏览器存储；
+- 仅 Web 提供该工具；dsh-tui 的工具面保持不变，也不会加载图表或浏览器依赖。
+
+## 在dsh-tui中使用
+
+启动终端界面：
 
 ```sh
-dsh --profile web
+dsh --profile dsh-tui
 ```
 
-在 Web GUI 中：新建会话 → 选择「数据模式」预设 → 输入框上方出现数据库工作台 → 填写连接信息（类型/主机/端口/用户/密码/库名；SQLite 填文件路径）→ 连接成功后浏览库表（单击库展开表、点击表看结构），或在 SQL 命令框直接运行 SQL → 开始对话后工作台移到左侧，在 Chat 让 AI「列出所有表并统计行数」或「写一条 SQL 查出近 30 天订单，保存到 orders.sql 并执行」。
+在空白会话中切换到数据模式，然后连接数据库：
+
+```text
+/preset data-agent
+/database connect
+```
 
-> 数据库客户端二进制要求：sqlite3 一般系统自带（macOS/Linux）；mysql / psql / sqlplus / beeline / impala-shell 需部署方安装，且可在插件配置 `clients` 中覆盖命令名或绝对路径（缺失时连接报错会点名缺失的命令）。
+连接表单会一次展示所有相关字段。使用Tab或Shift+Tab切换输入项；数据库类型和只读模式按Enter展开选项，使用方向键选择并再次按Enter确认。
 
-## 架构
+连接成功后，回到聊天输入框直接提出业务问题即可。常用的数据库命令还有：
 
 ```text
-浏览器 (apps/web)                         宿主进程 (dsh --profile web)
-┌─────────────────────────────┐          ┌──────────────────────────────────────┐
-│ 数据库工作台 (input.dock)    │  fetch   │ @yejiming/dsh-data-agent (宿主行)   │
-│  · 连接配置 (6 类型)         │ ───────▶ │  · /plugins/data-agent/* 路由          │
-│  · 库表浏览 + SQL 命令框     │          │  · 连接存储服务 dataAgentConnections   │
-│  · hero 堆叠 / active 左栏   │          │  · 预设自安装 → $DSH_HOME/.agent-presets│
-└─────────────────────────────┘          └──────────────┬───────────────────────┘
-                                                       │ 同一进程
-        data-agent 会话 (agent loop 全复用)              ▼
-┌──────────────────────────────────────────────────────────────────────────┐
-│ agent.cordis.yml (预设层，仅 3 行)                                        │
-│  · persona             → 数据工程师系统提示词                             │
-│  · dsh-tool-fs         → read / write / edit（项目自带）                  │
-│  · dsh-data-agent/tool → sql-query / sql-write / sqlcmd（本包工具半体）  │
-└──────────────────────────────────────────────────────────────────────────┘
+/database status       查看当前连接
+/database test         测试当前连接
+/database disconnect   断开当前连接
 ```
 
-一个 npm 包三个装载面、宿主两条行：
+同一会话再次打开连接表单时，会恢复最近填写的数据库类型、地址、端口、用户、数据库和只读模式。密码始终隐藏且不会恢复。
+
+![dsh-tui数据分析](assets/tui.png)
+
+## 推荐的提问方式
+
+为了获得更有价值的分析，可以在问题中补充业务目标、时间范围和关注维度。例如：
 
-| 面 | 入口 | 装载位置 |
-|---|---|---|
-| 服务端半体（连接存储/预设自安装） | `lib/index.js`（宿主行 `data-agent`） | 宿主组合：提供 `dataAgentConnections` 服务、预置连接、自安装预设；headless 也可用 |
-| 服务端半体（HTTP 路由） | `lib/routes.js`（宿主行 `data-agent-routes`，exports 子路径 `./routes`） | 宿主组合：仅在 webserver 存在时经嵌套 inject 注册路由（headless 无 webserver 时自动跳过） |
-| 工具半体 | `lib/tool.js`（exports 子路径 `./tool`） | 仅 data-agent 预设装载（`tool-sqlcmd` 行） |
-| 浏览器半体 | `lib/client.js`（package.json `dsh.client` 声明） | 浏览器：输入条带内嵌数据库工作台（`conversation.input.dock`） |
+```text
+分析2026年第二季度各地区的销售额和毛利率变化，找出表现异常的地区，
+继续拆解到品类和核心客户，并给出三条可执行的业务建议。
+```
 
-工具半体只消费宿主服务（`tools`、`subprocess`、`dataAgentConnections`），不提供服务，因此预设守卫无需 `isolate` realm。
+你也可以让DSH保存分析过程或SQL，方便复查和复用：
 
-## 配置
+```text
+完成会员复购分析，把最终SQL保存到analysis/repurchase.sql，
+并用一段适合周报的文字总结主要发现。
+```
 
-所有字段都有 loader 默认值；无库级默认值。宿主行 `data-agent`：
+## 使用前准备
 
-| 键 | 说明 |
-|---|---|
-| `presetId` | 自安装的预设目录名（默认 `data-agent`） |
-| `installPreset` | 是否在启动时自安装预设（默认 true；已存在则跳过，保留用户编辑） |
-| `connectTimeoutMs` | /connect 连通性检查的端到端超时（默认 10000 毫秒） |
-| `introspectMaxTables` | 表清单上限（默认 500） |
-| `queryTimeoutMs` | 数据库 tools 单次查询超时（默认 30000 毫秒） |
-| `maxResultChars` | 数据库 tools 捕获输出上限（stdout/stderr 各自，默认 20000 字符） |
-| `readonly` | 只读护栏（默认 false）：true 时数据库 tools 与 `/query` 仅放行读语句（SELECT/SHOW/DESCRIBE/EXPLAIN/PRAGMA 等），写语句直接拒绝 |
-| `clients` | 各数据库类型 CLI 客户端覆盖：`{ command?, args? }`，键为 `mysql` / `postgres` / `sqlite` / `oracle` / `hive` / `impala`（内置默认 mysql/psql/sqlite3/sqlplus/beeline/impala-shell） |
-| `connections` | 配置预置连接，键为 sessionId（`'*'` = 通配符默认，任何无自有连接的会话回落它；headless/keyless 运行与部署固定默认库场景）。**不含 password 字段**——密码只允许经 /connect 路由进入内存；可选 `readonly` 字段按连接锁定只读 |
+DSH运行查询时需要本机能够访问目标数据库，并安装相应的数据库客户端：
 
-工具行 `tool-sqlcmd`（data-agent 预设内）另有 `maxRows`（默认 100，强制生效：SELECT 未写 LIMIT 时自动追加，结构化结果解析时二次截断）与 `readonly`，`queryTimeoutMs` / `maxResultChars` / `clients` 与宿主行同名可配。
+- SQLite通常已随macOS或Linux提供。
+- MySQL需要`mysql`客户端。
+- PostgreSQL需要`psql`客户端。
+- Oracle、Hive和Impala需要各自的命令行客户端。
 
-路由行 `data-agent-routes` 独立配置：`connectTimeoutMs` / `introspectMaxTables` / `maxResultChars` / `readonly` 与主行同名同默认；另有 `queryTimeoutMs`（/query 与元数据查询超时，默认 30000）与 `maxQueryChars`（/query 单条 SQL 长度上限，默认 65536）。
+插件会先使用当前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`在系统常见目录之前：
 
 ```yaml
-# cordis.patch.yml 或 profile 层覆盖示例
 - id: data-agent
-  name: '@yejiming/dsh-data-agent'
   config:
     clients:
       mysql:
-        command: /usr/local/bin/mysql-client
-    # 通配符默认连接：任何未显式 /connect 的会话回落到该库（仅限无密码场景）
-    connections:
-      '*':
-        type: sqlite
-        database: /tmp/analytics.db
+        searchPaths:
+          - /opt/company/mysql/bin
+        # command: /opt/company/mysql/bin/mysql
 ```
 
-## Headless / 一次性运行
-
-**重要**：`dsh run`（headless bundle）不装载 agent-presets roster，也不会为会话挂载预设——预设机制属于 web 面（apiproxy 在会话创建时 mount）。因此 **headless 会话无法使用 sql-query/sql-write/sqlcmd/read/write/edit 工具面**，数据库 tools 的验证与使用都在 web 面完成；headless 中如需数据库能力，只能靠宿主 base 自带工具（如 bash 直接调用客户端）。
-
-（注：插入 roster 行 + 禁用 base 工具行的 patch 组合无法在 headless 中复现预设工具面——agent 会得到一个零工具的空组合，模型无工具可调。如需 headless 冒烟，仅验证「连接配置预置 + 宿主工具可用」即可。）
-
-`data-agent-routes` 行在无 webserver 的 profile 中经嵌套 inject 自动跳过，无需处理。
+Windows路径可以写成`C:\Program Files\MySQL\MySQL Server 9.0\bin`。插件不会下载数据库客户端、执行登录shell或扫描整块磁盘；位于非常规目录且未进入PATH时，仍需使用`searchPaths`或`command`。
 
-## HTTP 接口
+建议先准备一个只读数据库账号，让数据Agent在不修改业务数据的前提下完成探索和分析。
 
-前缀 `/plugins/data-agent`（浏览器半体同源调用）：
-
-| 方法/路径 | 说明 |
-|---|---|
-| `POST /connect` | body `{ sessionId, type, host?, port?, user?, database, password?, readonly? }`；校验 → 连通性验证（列出所有表）→ 成功才保存连接，返回 `{ ok, tables }`，失败返回 `{ ok: false, error }` 且不保存 |
-| `POST /disconnect` | body `{ sessionId }`；清除该会话连接 |
-| `GET /status?sessionId=` | `{ connected, summary? }`；summary 为脱敏连接概要（无密码，含 `readonly` 当连接显式设定时）+ 表清单 |
-| `GET /schemas?sessionId=` | `{ ok, schemas: string[] }`；库/数据库列表（sqlite 为 `['main']`） |
-| `GET /tables?sessionId=&schema=` | `{ ok, tables: string[] }`；某库的表列表（sqlite 忽略 schema 参数） |
-| `GET /describe?sessionId=&schema=&table=` | `{ ok, columns: [{ name, type, nullable? }] }`；表结构（sqlite 忽略 schema） |
-| `POST /query` | body `{ sessionId, sql }`；运行一条 SQL（工作台命令框，非 agent 通道），返回 `{ ok, result: { exitCode, stdout, stderr, truncated } }`；`sql` 长度上限 `maxQueryChars`；单次只允许一条语句；readonly 开启时拒绝写语句 |
-
-schema/table 标识符仅允许 `[A-Za-z0-9_$]`（服务端白名单校验并转义引用，拒绝注入形字符）。
+如果出现`failed to mount`或提示找不到`@yejiming/dsh-data-agent`，通常是当前profile还没有安装插件，或仍在使用旧版预设。请为Web UI、DSH Desktop或dsh-tui执行对应的安装命令，然后完全退出并重新启动DSH。未修改过的旧版预设会自动迁移；手工编辑过的预设需要删除其中指向`@yejiming/dsh-data-agent/tool`和`@yejiming/dsh-data-agent/command`的两行配置块。
 
 ## 安全说明
 
-- **密码**：服务端仅存内存，传递通道按类型：mysql 经 `MYSQL_PWD`、postgres 经 `PGPASSWORD` 环境变量；oracle 经 sqlplus `connect user/pass@...` stdin 前缀、hive 经 beeline `!connect` stdin 前缀（均不进 argv）；impala 默认不传密码（LDAP/kerberos 由部署侧 `clients` 覆盖）。`/status` 与连接存储的公开读取面均剥离密码。
-- **连接配置持久化**：工作台把连接配置（type/host/port/user/database）保存到浏览器 localStorage（键 `dsh-data-agent.connection.v1`），用于切换页面/重启后回填表单并自动重连一次。**密码默认不落盘**：仅当用户勾选「记住密码」时才持久化密码（明文 localStorage，本机单用户场景的显式 opt-in）。若需清除：浏览器控制台执行 `localStorage.removeItem('dsh-data-agent.connection.v1')`。
-- **无 shell 层**：`ctx.subprocess.spawn` 参数数组化，SQL 与连接前缀经 stdin 传入，不存在 shell 拼接注入面；元数据路由的 schema/table 标识符经收紧白名单 `[A-Za-z0-9_$]` 校验并按类型转义引用（反引号/双引号），拒绝 `#`、`--`、`;`、`'` 等注入形字符。
-- **SQL 执行权**：审批策略为 never 时，`sql-write`/`sqlcmd` 与 `/query` 的 DDL/DML 会直接执行——连接按 session 隔离，请自行评估数据面风险。可设 `readonly: true`（宿主/工具/路由三行同名，或 `/connect` 传 `readonly: true` 按连接锁定）强制只放行读语句（SELECT/SHOW/DESCRIBE/EXPLAIN/PRAGMA 等），作为误操作防护；对更强对手防护，仍建议配合数据库侧只读账号。每次数据库工具调用为独立客户端进程并自动提交，不支持跨调用事务。
-- **超时与上限**：查询超时、输出截断、表清单上限、读查询最大行数（`maxRows`）、/query 单条 SQL 长度均为配置项，无硬编码 tunables。
+- 推荐使用数据库只读账号，并在连接表单中开启只读模式。
+- Web UI和dsh-tui中的临时密码只用于当前连接；TUI只显示`*`，重新打开表单时不会恢复密码。
+- 需要跨进程恢复认证时，可以使用DSH credential reference，避免在命令参数中输入明文密码。
+- 未开启只读模式时，数据Agent可以按你的要求执行更新或管理语句。连接生产数据库前，请先确认账号权限和数据备份策略。
+- 不同会话的数据库连接相互隔离，便于分别处理不同项目、客户或分析环境。
 
 ## 卸载与回滚
 
 ```sh
-dsh plugin --profile web remove @yejiming/dsh-data-agent   # 移除依赖与对应层
-rm -rf $DSH_HOME/.agent-presets/data-agent                      # 手动删除自安装的预设
+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存储记录。
 
 ## 本地开发
 
-构建与测试：
-
 ```sh
-pnpm build   # 清空并重建 lib/（tsdown：lib/index.js、lib/routes.js、lib/tool.js、lib/invariant.js、lib/client.js）+ tsc 声明
-pnpm test    # vitest：连接存储 / CLI 模板 / sqlcmd 执行（mock subprocess）
+pnpm install
+pnpm build
+pnpm test
 ```
 
-`lib/` 已提交进仓库，安装与调试（含 `dsh plugin add .`）都不需要先构建。重新
-构建产物时直接 `pnpm install` 即可：`@deepseek-ai/*` 等依赖均已发布到 npm，
-无需再从本地 DSH checkout 复制/链接 node_modules。`pnpm-workspace.yaml` 采用
-dsh 同款约定（`nodeLinker: hoisted`）；pnpm 11 的供应链策略会拦截「发布不久」
-的包与依赖构建脚本，仓库已预置 `minimumReleaseAgeExclude`（rc.6 全家桶）与
-`allowBuilds: esbuild`。
+`lib/`已提交到仓库，因此通过npm或GitHub安装时无需自行构建。
 
 ## 许可
 
@@ -193,6 +213,6 @@ MIT
 
 ## 友情链接
 
-- [dshfind.com](https://dshfind.com)：DeepSeek Harness 的中文学习与分享社区。读懂论文，写出插件，看见整个生态。
-- [dsh-web-ui](https://github.com/dsh-external/dsh-web-ui)：DeepSeek Harness（DSH）Web UI 的插件与皮肤集合
-- [dsh-cc-tui](https://github.com/dsh-external/dsh-cc-tui)：Claude Code 风格全屏交互终端插件
+- [dshfind.com](https://dshfind.com)：DeepSeek Harness中文学习与分享社区
+- [dsh-web-ui](https://github.com/dsh-external/dsh-web-ui)：DeepSeek Harness Web UI插件与皮肤集合
+- [dsh-cc-tui](https://github.com/dsh-external/dsh-cc-tui)：Claude Code风格的全屏终端界面

package/cordis.patch.yml

@@ -1,14 +1,13 @@
 # The dsh-data-agent bundle patch: activates the plugin as a profile layer.
 #
-# Two host rows: `data-agent` provides the connection store, seeds config
-# connections, and self-installs the agent preset (works in every profile,
-# headless included); `data-agent-routes` mounts the HTTP routes and only
-# activates where the webserver exists (web profiles). The browser half
-# (lib/client.js) ships in the same package and loads under the data-agent id
-# through the `dsh.client` declaration in package.json; the tool half
-# (lib/tool.js) is mounted only by the `data-agent` agent preset as the
-# `@yejiming/dsh-data-agent/tool` row, so no further rows belong here
-# (duplicate ids fail the load).
+# Two host rows: `data-agent` provides the connection store, installs the
+# selectable agent preset, and statically preloads that preset's scoped tools
+# and command through the profile bundle path; `data-agent-routes` mounts the
+# HTTP routes and only activates where the webserver exists (web profiles).
+# The browser half (lib/client.js) ships in the same package and loads under
+# the data-agent id through the `dsh.client` declaration in package.json.
+# The preset composition deliberately contains no dynamic imports of this
+# package, which keeps DSH Desktop away from its unpacked-ASAR resolver bug.
 - insert:
     - id: data-agent
       name: '@yejiming/dsh-data-agent'