dsh-dbhub-live 2.0.0 → 3.1.2

package/AGENTS.md

@@ -0,0 +1,97 @@
+# AGENTS.md — dsh-dbhub-live 开发与调试说明
+
+> 本文件面向在本仓库上继续开发/调试本插件的 AI 与人。业务需求见 [doc/REQUIREMENTS.md](doc/REQUIREMENTS.md)，用户安装使用见 [README.md](README.md)。
+
+## 一句话定位
+
+DSH host 插件（Node/E SM）+ Web client 插件（浏览器半）：把 dbhub（Bytebase 的数据库 MCP 服务器）接入 DSH，提供按工作区的常驻连接工具、临时连接工具，外加设置在「设置 → 插件」里的实时状态卡片与启用/禁用开关。
+
+## 目录结构
+
+```
+lib/
+  index.mjs    入口：name/inject/apply、状态命名空间(schemastery)接线、懒加载编排、配置变更应用
+  config.mjs   路径/持久化(store,runtime)/DSN 解析/工作区发现/store v2（environments）助手/小工具
+  state.mjs    运行时状态机：enabled/phase/toolCount/lastError/mode + 订阅发布
+  options.mjs  可配置参数：updateIntervalDays/idleMinutes（设置UI > 环境默认；dbhubPackage 仅内部环境knob）
+  runtime.mjs  dbhub 可执行文件发现、按需自动安装、定期自动更新、孤儿进程清理
+  mcp.mjs      MCP JSON-RPC 客户端 + 常驻多源 dbhub 服务生命周期 + collectSources(工作区×环境) + 摘要缓存
+  adhoc.mjs    临时连接（每次调用一条一次性 dbhub 进程）
+  collect.mjs  授权扫描项目配置文件并提取 DSN 候选（含 askUser 桥接）
+  tools.mjs    host 自有工具定义与注册（dbhub_configure 支持 env 参数）
+  client.js    Web 半（手写 lazy-CJS bundle）：折叠分区卡片（状态/配置/工作区连接）
+test/          node:test 单元测试（纯逻辑 + client bundle 格式契约）
+doc/           需求文档
+cordis.patch.yml   bundle patch：`name: dsh-dbhub-live` 挂载本包
+```
+
+## 关键架构事实
+
+- **模块依赖只进不出**：`config ← state ← runtime ← mcp ← tools ← index`，`adhoc ← mcp`，`collect ← tools`；禁止反向 or 循环 import（HMR/装载顺序依赖它）。
+- **状态命名空间**：Host 注册 `dsh-dbhub-live` 命名空间（`ctx.inject(['settings'], …)` + schema）；Web 端 Plugins 选项卡按命名空间分发 `settings.plugin.item` 卡片。命名空间值 = 状态 `{enabled, phase, toolCount, lastError, mode}` + 配置 `{updateIntervalDays, idleMinutes}` + `{serverUp}` + `{workspaces(JSON 掩码摘要)}` + `{configOp}`（主机消费后自动清空）。**注入回调是独立作用域：内部需要的服务（如 `subprocess`）必须用 `ctx.get('subprocess')` 就地获取，绝不能引用 `apply()` 的局部变量——否则 ReferenceError 会静默杀死整条发布/配置链路（卡片只剩静态值、工作区连接不刷新）**。回调整体套 `wrap()` 防护，异常必须打日志。
+- **可配置参数**：`options.mjs` 只此一处持有部署开关（`dbhubPackage` 仅环境变量/内部，不进设置）；watch 把卡片写入的字段经 `options.applyPatch` 应用到运行时。**优先级：用户设置 > 进程环境变量 > 内置默认**。不要绕过 `applyPatch` 直接改 `options` 内部值。
+- **工作区连接管理（configOp 通道）**：store v2 = `{ [wsPath]: { environments: { [env]: {dsn, source, updatedAt} } } }`（v1 单 dsn 条目自动迁移进 `environments.default`）。卡片只读**掩码**摘要（`collectSources` → `latestSummaries`，密码永不出 Host）；增/改/删通过命名空间 `configOp` 单向命令下发，`index.mjs` 用 `setWorkspaceEnv`/`removeWorkspaceEnv` 落盘后重扫摘要并发布（configOp 随发布清空，天然防环）。自动发现（mise/.env）只提供未覆盖的 `default`，不持久化。
+- **工具声明数量恒定（上下文预算红线）**：**绝不为每个工作区 × 环境注册独有工具**（否则 2N 个工具声明每轮进模型上下文）。常驻查询只有 `dbhub_execute_sql(source, …)` / `dbhub_search_objects(source, …)` 两个声明，调用时 `resolveSource` 按 source 值（`标题_hash[_环境]`，来自 `dbhub_list_sources`）解析到真实连接并调用 `dbhub_<base>_<sourceId>`。曾实现过的 per-source 注册（syncToolsNow/兜底/升级）已移除，勿回恢复。核心工具全集固定：configure / list_sources / execute_sql / search_objects / query / query_objects。
+- **schema 弹性依赖**：优先用真实 `@deepseek-ai/schemastery` schema（`await import`）；解析失败时降级为 `lib/index.mjs` 内建的最小 callable schema（`schema(v)` 合默认值 + `toJSON()`），保证**链路安装（`dsh plugin add <本地目录>`，Node ESM 按源码真实路径解析裸导入）下插件照样启动、卡片照常工作**。tarball/npm 安装（真实目录在 profile node_modules 下）走真实 schemastery 路径。不要把这个 import 改回静态顶层 import——会重新引入链路安装时启动失败。
+- **懒加载**：`apply()` 只注册核心工具 + 后台异步初始化（`startLazyInit`）；任何工具调用先 `ensureRunning`（共享 `server.starting`，并发调用自动排队等待）；启动失败进入 `phase:'error'` 并记录 `lastError`，下次调用自动重试。**无工作区数据源时恒不拉起 dbhub 进程**（空 `[[sources]]` toml 对 dbhub 是致命的；空指纹若被当成“已同步”会在二次调用时绕过 toml 直接 spawn——`ensureRunning` 的 `sources.length === 0` 早退必须在指纹判断之外）。
+- **启用/禁用**：`state.setEnabled` 持久化到 `credentials.json`（权威值）；禁用时立即 `terminateServer()` 释放进程，所有工具 execute 首行返回「插件已禁用」；重新启用触发懒加载初始化。
+- **密码脱敏**：`maskDsn` 是唯一出口——工具描述、结果前缀、扫描候选一律走它。
+
+## 存储与容错（初始化即处理）
+
+- **实例隔离**：所有持久化都在 `$DSH_HOME/storages/dsh-dbhub-live/`（`credentials.json` 凭据+enabled、`runtime.json`、`dbhub.toml`、`dbhub-runtime/` 自动安装前缀）。隔离粒度 = `DSH_HOME`（同一 home 的多个 profile 共享，与 dsh 自身 workspace.json 约定一致）；dbhub 进程、状态机、工具注册天然按进程隔离。**进程环境变量不参与连接解析**。
+- **升级/手改遗留兼容**：`loadStore`/`loadRuntime` 先用纯函数 `normalizeStore`/`normalizeRuntime` 清洗：丢弃非布尔 `enabled`、非对象/空 dsn 条目、非法 `dbhubExe`/`dbhubInstallAt`；`dsn` 统一 trim；v1 单 dsn 条目自动迁移为 `environments.default`；**未知字段保留**（向前兼容）。清洗结果与原文不同时**一次性回写迁移**，之后每次启动都是规范化文件。
+- **空值安全**：解析器对缺失/空值全部有兜底（`resolveWorkspaceEnvs` 判空、`maskDsn` 对不可解析 DSN 正则兜底、状态 schema 默认值、settings 镜像的 `enabled` 只认布尔），清洗后不存在半吊子条目。
+- **运行目录被删 / 写入被拦截**：每次 JSON/toml 写入前自动 `mkdirSync` 重建目录；写入失败**不抛致命**，`warnOnce` 一次性告警并继续内存态运行（凭据持久化失效但工具可用）；`dbhub.toml` 写入失败按**初始化错误**记录（状态卡片 🔴 + `lastError`）并下次调用自动重试；npm 自动安装前同样重建目录。注意：以上全是 best-effort，被拦截时重启会丢「仅内存态」的修改，属预期。
+
+## 调试方法（不影响正在运行的 Harness）
+
+DSH 启动是 fail-loud：任一插件激活失败整树拒绝启动、GUI 打不开。因此**永远不要在配置/源码上直接动主实例**，按下面阶梯来：
+
+1. **静态校验（30 秒，零风险）** — `npm run check`（node --check 全部 lib）→ `npm test`（node:test 单测）。单测会自己建临时 `DSH_HOME`，不会碰真实 store。
+2. **会话内跑通逻辑（不重启）** — 用动态插件工具连（`cordis_define`/`cordis_run`/`cordis_stop`/`cordis_undefine`）：把要验证的纯逻辑（如 configure 流程、状态机）以无 import 的 Host 代码贴进动态包，在会话里跑，`cordis_stop` 即清场。动态包只活在进程内存 + 当前会话，改动/出错都不影响主进程。
+   - 注意：动态 Host 代码不能用 `import`，所以带 `@deepseek-ai/schemastery` / `dsh-settings` import 的 `lib/index.mjs` 不能整文件贴进动态包；只对纯逻辑做动态验证。
+3. **冷启动验证（隔离实例）** — 用独立 `DSH_HOME` 起测试实例：
+   ```powershell
+   $env:DSH_HOME = "D:\path\.dsh-test"        # 放工作区内即可免越权
+   dsh web --port 3081 --no-open              # 首次自动初始化 web 模板
+   dsh plugin --profile web add D:/path/to/dsh-dbhub-live
+   dsh web --port 3081 --no-open
+   # 验证：日志出现 [dsh-dbhub-live] 初始化/服务已加载；GET /plugins/dsh-dbhub-live/client.js 返回 bundle
+   ```
+4. **在位热更新（有失败保护，谨慎）** — 主实例的 `cordis.patch.yml` 支持 HMR，读取/解析失败时保留最后一个可用树，GUI 不会挂。但 HMR 不监听插件源码，只适合挂载/卸载验证，代码迭代请用 1/2/3。
+5. **安全网** — `$DSH_SNAPSHOT=replay` 可从 `cordis.snapshot.yml` 启动回放点；改动主 profile 前先备份 `cordis.patch.yml`。
+
+## 修改 client 半（lib/client.js）
+
+`lib/client.js` 是**手写 lazy-CJS bundle**，DSH client 模块系统按 `dsh.client` 声明 + `exports["./client"]` 直接服务它，**没有构建步骤**。遵守以下契约（改完跑 `node test/client-format.test.mjs` 守护）：
+
+- 必须以 `window.__ModuleLoader__.load({ id: "dsh-dbhub-live", factory: (require) => { … } })` 注册；
+- `id` 必须等于 Loader entry 名（`dsh-dbhub-live`，见 cordis.patch.yml 的 `name`），不是行 id；
+- factory 只允许 `require("react")` 等 baseline 模块；不 import 其他插件的值（bundle-purity）；
+- 导出 `name/inject/apply`，结尾 `return module.exports`；
+- 组件不得接触 `ctx`，数据/回调一律通过注册时的 `inject: () => face` 传入 props；用内联样式，不依赖 CSS 文件。
+- 若本包脱离仓库（发布 npm），`dsh.client` 与 `exports["./client"]` 必须保留，否则 client-modules 扫描会启动报错。
+
+## 质量门
+
+```bash
+npm run check   # 全部 lib 语法
+npm test        # 单元测试（node:test；沙箱内请逐个文件跑：node test/x.test.mjs）
+```
+
+发布前：按「调试方法」第 3 步在隔离实例完整冷启动一遍，确认 Host 无报错、`/plugins/dsh-dbhub-live/client.js` 可访问。
+
+## 版本号策略（内部调试 ≠ 发布）
+
+- **每次内部调试迭代都升小版本**（如 `3.1.1-dev.1`、`3.1.1-dev.2`、`3.1.1-dev.3`…），`pnpm pack` 产物随之换名；
+- 原因：pnpm 对 `dsh plugin add <同名同版本 tarball>` 会判「Already up to date」跳过、**不换包**；升版本号才能保证调试包真正部署（曾因同版本 tgz 导致连换两轮都没生效）。
+- `dsh plugin add` 后务必用 `dsh plugin ls` 或核对 `node_modules/<pkg>/package.json` 的版本号确认已替换。
+- **发布时**再升级发布版本（如调试到 `3.1.1-dev.N` 后，正式版打 `3.1.2`），tag/npm 一律用正式版本号。
+
+## 约定
+
+- 产品文案中文、代码注释英文；密码脱敏不可绕过；扫描必须经 `askUser` 授权。
+- `state.*` 之外不要直接改 `store`/`runtime` 之外的持久化。
+- 增加行为时同步更新本文件、README（用户侧）与 doc/REQUIREMENTS.md（业务侧）。
+- README 双语同步：`README.md`（中文）为唯一真源，`README.en.md` 由 AI 从最新中文派生——改动任一侧必须同次更新另一侧，章节结构一一对应。

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 mr-mihu
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 mr-mihu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,162 @@
+# dsh-dbhub-live
+
+[简体中文](README.md) | English
+
+> Let [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/DeepSeek-Harness) operate databases directly and safely: persistent multi-source connections + per-workspace tools + ad-hoc dynamic connections + lazy loading and a browser status card.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![DSH](https://img.shields.io/badge/DSH-plugin-blue.svg)](#installation)
+[![DBHub](https://img.shields.io/badge/Built_on-DBHub-22a05a)](https://github.com/bytebase/dbhub)
+[![npm version](https://img.shields.io/npm/v/dsh-dbhub-live)](https://www.npmjs.com/package/dsh-dbhub-live)
+[![Listed on dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/plugins/mr-mihu/dsh-dbhub-live)
+
+`dsh-dbhub-live` is a DSH plugin built on [DBHub](https://dbhub.ai) (a database MCP server) that lets the model query databases directly: reuse persistent connections on configured workspaces, or make one-off connections to any database for ad-hoc investigation.
+
+## ✨ Features
+
+- **Persistent multi-source service** — a single background dbhub service connects to multiple sources; connections are reused and queries are faster.
+- **Per-workspace tools** — `dbhub_execute_sql_<workspace>` / `dbhub_search_objects_<workspace>`; the tool name is the workspace, multiple workspaces never mix up, and connections are clearly labeled (passwords masked).
+- **Ad-hoc dynamic connections** — `dbhub_query` / `dbhub_query_objects` connect to any database independently on each call and can query several databases in parallel, handy for cross-environment diagnosis.
+- **Lazy-load startup** — plugin startup does not block the GUI and tools are available immediately; environment initialization is deferred to the first call (queries during initialization automatically wait until ready).
+- **Enable / disable switch** — turning it off makes every dbhub tool return a friendly "plugin disabled" message immediately, without a restart; turning it back on takes effect right away.
+- **Browser status card** — the Settings → Plugins → dsh-dbhub-live panel shows in real time: a status badge (🟢 running / 🟡 initializing / 🔴 error), registered tool count, operating mode, and the most recent error (in red), plus the enable/disable switch.
+- **Out of the box** — if `dbhub` is not installed, the plugin installs it automatically on first use and keeps it updated afterwards; no manual steps needed.
+- **Multiple configuration methods** — explicit DSN / fill-in fields / authorized scanning of project config files; credentials stay in your local user directory and passwords are masked end to end.
+
+## Supported Data Sources
+
+MySQL · PostgreSQL · MariaDB · SQLite · SQL Server
+
+## Requirements
+
+- DeepSeek Harness's `dsh` CLI (`dsh web` runs the GUI)
+- Node.js ≥ 18 with `npm` recommended — `dbhub` is auto-installed on first use
+
+## Installation
+
+```bash
+# Option 1: use a locally installed dsh
+dsh plugin --profile web add dsh-dbhub-live
+
+# Option 2: invoke dsh via npx (no global dsh installation required)
+npx @deepseek-ai/dsh plugin --profile web add dsh-dbhub-live
+```
+
+After installing, **restart `dsh web`** for it to take effect (you can then see the status card at Settings → Plugins → dsh-dbhub-live).
+
+## Quick Start
+
+The tools below are invoked automatically by DSH's AI — you don't run them by hand; just state your request in natural language (e.g., "look up the users table") and the AI configures and queries on demand:
+
+```text
+# 1) If the current workspace has no connection yet, the AI configures one first (three methods below under "Configuration Methods")
+dbhub_configure
+
+# 2) Run a query on a persistent connection of a configured workspace
+dbhub_execute_sql_myapp  SELECT * FROM users LIMIT 10;
+
+# 3) Make a one-off connection to any database
+dbhub_query  dsn=mysql://user:pass@127.0.0.1:3306/mydb  sql="SHOW TABLES;"
+```
+
+## Tools
+
+| Tool | Description |
+| --- | --- |
+| `dbhub_configure(workspace?, env?, dsn?)` | Configure/persist a database connection for a workspace (environment name optional, default `default`). |
+| `dbhub_list_sources()` | List all registered connection sources (workspace × environment, masked connection strings, origin, and the corresponding **source** value); **masked strings are for identification only and cannot be used for direct connections**. |
+| `dbhub_execute_sql(source, sql)` | Execute SQL on a source's persistent connection; `source` comes from `dbhub_list_sources` (the default environment has no suffix; named environments look like `…_test`). |
+| `dbhub_search_objects(source, object_type, ...)` | Search database objects (tables/views/columns/indexes, etc.) on a given source. |
+| `dbhub_query(dsn, sql)` | Connect to any database temporarily and execute SQL (multiple statements separated by `;`); **a masked `****` password is detected and the call is rejected**, steering you to the persistent tools. |
+| `dbhub_query_objects(dsn, ...)` | Connect to any database temporarily and search database objects; masked passwords are also rejected. |
+
+> Persistent tools have a **constant declaration count** (it does not grow with the number of workspaces/environments): every workspace × environment is selected through the `source` parameter of `dbhub_execute_sql` / `dbhub_search_objects` — semantically equivalent to one tool per workspace × environment, but **without using extra context space**.
+
+> Note: `search_objects` is only available for SQLite; for MySQL / PostgreSQL etc. use `dbhub_query` directly (e.g., `SHOW TABLES`).
+
+### Configuration Methods
+
+1. **Explicit DSN** — pass a full connection string, e.g. `mysql://user:pass@host:3306/db`.
+2. **Fill in fields** — fill type / host / port / user / password / database name in order.
+3. **Authorized scan** — after authorization, scan project config files (`.env`, `application*.yml`, `docker-compose`, `jdbc.properties`, etc.) and list candidates (passwords masked) for you to confirm.
+
+If a workspace already has `mise env` or `.env` (`DSN` / `DB_*`), the plugin discovers it automatically — no manual configuration needed.
+
+## Status Card
+
+Settings → Plugins → dsh-dbhub-live: the plugin syncs its running state and configuration to the Web settings panel in real time (only visible on the `dsh web` side). The card uses the **single-row collapsible** style (consistent with the other plugin settings cards):
+
+**Collapsed (default)**: one row shows the status badge (🟢 running / 🟡 initializing / 🔴 error / ⚪ disabled), environment count, and the **enable/disable switch** — you can check the status and toggle without expanding.
+
+**Expanded** shows three blocks —
+
+**Status** (supporting info; the tool declaration count is fixed and no longer the focus):
+
+- Resident process: running / pending start (on demand) — shows "pending start" after idle reclamation.
+- Operating mode: lazy loading (initializes on first call).
+- Tool declarations: `6 (fixed)`; environments: `N · M saved`.
+- Most recent error (shown in red on error).
+
+**Configuration** (edit, then click "Save Configuration" to apply immediately and persist):
+
+| Parameter | Description | Default |
+| --- | --- | --- |
+| Auto-update interval (days) | How often dbhub is auto-updated; `0` disables | `7` |
+| Idle reclamation (minutes) | Idle reclamation time of the resident dbhub process | `10` |
+
+Precedence: **user settings > process environment variables (default seeds) > built-in defaults**. The auto-installed package is not in the UI (controlled separately by the `DSH_DBHUB_PACKAGE` environment variable, default `@bytebase/dbhub`).
+
+**Workspace connections**:
+
+- Lists every workspace × environment connection: workspace name, environment name, **source value** (what the model passes to `dbhub_execute_sql`, shown in monospace), **masked** connection string, and origin badge (`saved` / `auto`).
+  - `saved`: you configured it (`dbhub_configure` or added in the card).
+  - `auto`: not saved, discovered from `mise env` / `.env` — not persisted and follows the source files; if auto-discovery is wrong, use "Edit" to override it with a manual configuration.
+- Each row can be **edited** (override the connection string; an auto item becomes saved) or **deleted** (saved items only).
+- **Multiple environments per workspace**: fill "workspace (path or title, empty = default current workspace) + environment name + connection string" in the form and click "Add Connection". The default environment's source has no suffix; named environments look like `<workspace>_<environment>`.
+
+## dbhub Environment Variables
+
+| Environment variable | Description | Default |
+| --- | --- | --- |
+| `DSH_DBHUB_PACKAGE` | npm package name used for auto-install (environment variable only, not exposed in the UI) | `@bytebase/dbhub` |
+| `DSH_DBHUB_UPDATE_DAYS` | Seed for the auto-update interval in days; `0` disables (overridden once saved in the settings card) | `7` |
+
+## 🔄 Automatic Installation & Updates
+
+- **Auto-install on first use** — when `dbhub` is missing locally, the plugin installs it on the first query; afterwards it also works offline.
+- **Kept up to date automatically** — silently updates to the latest version in the background (interval under "Status Card → configurable parameters"); on failure the existing version is kept.
+- **Never touches your configuration** — a `dbhub` you installed yourself via PATH / mise is left untouched.
+
+> The default update interval can also be seeded by an environment variable, see "Status Card → Configuration"; once saved in the settings card, the saved value wins.
+
+## Data Location
+
+All configuration and credentials live outside the module directory (unaffected by pnpm packaging); deleting the directory clears everything:
+
+```
+~/.dsh/storages/dsh-dbhub-live/
+```
+
+Instances are isolated by `DSH_HOME`; multiple profiles of the same instance share it (same convention as dsh's own `workspace.json`). Workspace connections are stored per "workspace × environment" (`environments.default` is the default environment); legacy v1 single-connection entries migrate automatically at startup. The plugin cleans up and migrates legacy config left by upgrades or manual edits in one pass; it does not crash if the runtime directory is deleted or writes are blocked by the system — it recreates the directory, warns once and keeps running in memory when a write fails, and treats a `dbhub.toml` write failure as an initialization error with automatic retry.
+
+## Uninstall
+
+```bash
+dsh plugin --profile web remove dsh-dbhub-live
+```
+
+## Troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| "Cannot locate dbhub" on first use | Make sure npm is present and online; offline, install `dbhub` manually and add it to PATH. |
+| Status card shows 🔴 error | Check "Most recent error" in the status card and the `dsh web` logs; a crashed process is auto-restarted on the next call. |
+| Tools say "plugin disabled" | Open Settings → Plugins → dsh-dbhub-live and click "Enable". |
+| Status card not visible | Confirm the plugin is installed and restart `dsh web`; the card only shows in the Web settings panel (`dsh web`) — on terminal environments without the panel, tool usage is unaffected. |
+| No config files found by the scan | `node_modules` / `.git` / `target` / `dist` etc. are skipped by default; use "Enter DSN" or "Fill in fields" instead. |
+| Need a custom dbhub version | Set the `DSH_DBHUB_PACKAGE` environment variable (e.g. `@bytebase/dbhub@1.2.1`) and restart; or delete `~/.dsh/storages/dsh-dbhub-live` and let it reinstall automatically. |
+| Don't want automatic dbhub updates | Set "Auto-update interval (days)" to `0` in the status card and save; or set `DSH_DBHUB_UPDATE_DAYS=0`. |
+
+## License
+
+[MIT](./LICENSE)

package/README.md

@@ -1,110 +1,162 @@
-# dsh-dbhub-live
-
-> 让 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/DeepSeek-Harness) 直接、安全地操作数据库：常驻多源连接 + 按工作区工具 + 临时动态连接。
-
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![DSH](https://img.shields.io/badge/DSH-plugin-blue.svg)](#安装)
-[![DBHub](https://img.shields.io/badge/Built_on-DBHub-22a05a)](https://github.com/bytebase/dbhub)
-
-`dsh-dbhub-live` 是一个 DSH 插件，基于 [DBHub](https://dbhub.ai)（数据库 MCP 服务器）让模型直接查询数据库：既能在已配置的工作区上复用常驻连接，也能临时连任意库做一次性排查。
-
-## ✨ 特性
-
-- **常驻多源服务** — 后台一个 dbhub 服务同时接入多个数据源，连接复用、查询更快。
-- **按工作区工具** — `dbhub_execute_sql_<工作区>` / `dbhub_search_objects_<工作区>`，工具名即工作区，多工作区不混淆，连接标注（密码打码）清晰可见。
-- **临时动态连接** — `dbhub_query` / `dbhub_query_objects` 每次独立连任意库，可并行查多个不同库，便于跨环境排查。
-- **开箱即用** — 未安装 `dbhub` 时首次使用自动安装，之后自动保持更新，无需手动处理。
-- **多种配置方式** — 显式 DSN / 填写分项 / 授权扫描项目配置文件，凭据仅存本机用户目录，密码全程脱敏。
-
-## 支持的数据源
-
-MySQL · PostgreSQL · MariaDB · SQLite · SQL Server
-
-## 环境要求
-
-- DeepSeek Harness 的 `dsh` CLI（`dsh web` 负责 GUI 运行）
-- 推荐本机有 Node.js ≥ 18（含 `npm`）——首次使用会自动安装 `dbhub`
-
-## 安装
-
-```bash
-# 方式一：使用本机已安装的 dsh
-dsh plugin --profile web add github:mr-mihu/dsh-dbhub-live
-
-# 方式二：通过 npx 调用 dsh（无需本机全局安装 dsh）
-npx @deepseek-ai/dsh plugin --profile web add github:mr-mihu/dsh-dbhub-live
-```
-
-安装后**重启 `dsh web`** 生效。
-
-## 快速开始
-
-```text
-# 1) 为当前工作区配置数据库连接（三种方式任选其一）
-dbhub_configure
-
-# 2) 在已配置工作区的常驻连接上执行查询
-dbhub_execute_sql_myapp  SELECT * FROM users LIMIT 10;
-
-# 3) 临时连任意库做一次性排查
-dbhub_query  dsn=mysql://root:pass@192.168.77.6:3306/tx_sd_jinengshu  sql="SHOW TABLES;"
-```
-
-## 工具
-
-| 工具 | 说明 |
-| --- | --- |
-| `dbhub_configure(workspace?, dsn?)` | 为工作区配置/持久化数据库连接。 |
-| `dbhub_execute_sql_<工作区>` | 在指定工作区的常驻连接上执行 SQL。 |
-| `dbhub_search_objects_<工作区>` | 在指定工作区搜索数据库对象（表/视图/列/索引等）。 |
-| `dbhub_query(dsn, sql)` | 临时连接任意库执行 SQL（多语句用 `;` 分隔）。 |
-| `dbhub_query_objects(dsn, ...)` | 临时连接任意库搜索数据库对象。 |
-
-> 注：`search_objects` 仅对 SQLite 开放；MySQL / PostgreSQL 等请用 `dbhub_query` 直接查（如 `SHOW TABLES`）。
-
-### 配置方式
-
-1. **显式 DSN** — 传入完整连接串，如 `mysql://user:pass@host:3306/db`。
-2. **填写分项** — 按类型 / 主机 / 端口 / 账号 / 密码 / 库名依次填写。
-3. **授权扫描** — 授权后扫描项目配置文件（`.env`、`application*.yml`、`docker-compose`、`jdbc.properties` 等），列出候选（密码打码）供你确认。
-
-工作区若已有 `mise env` 或 `.env`（`DSN` / `DB_*`），插件会自动发现，无需手动配置。
-
-## 🔄 dbhub 自动安装与更新
-
-- **首次使用自动安装**：本机没有 `dbhub` 时，插件会在第一次查询时自动安装，之后离线也可用。
-- **自动保持更新**：每 7 天在后台静默更新到最新版，失败则沿用现有版本。
-- **不碰你的配置**：通过 PATH / mise 自行安装的 `dbhub` 不会被插件改动。
-
-| 环境变量 | 说明 | 默认 |
-| --- | --- | --- |
-| `DSH_DBHUB_PACKAGE` | 自动安装使用的 npm 包名 | `@bytebase/dbhub` |
-| `DSH_DBHUB_UPDATE_DAYS` | 自动更新间隔天数，`0` 关闭 | `7` |
-
-## 数据位置
-
-所有配置与凭据存放在模块目录之外（不受 pnpm 打包影响），删除该目录即可完整清空：
-
-```
-~/.dsh/storages/dsh-dbhub-live/
-```
-
-## 卸载
-
-```bash
-dsh plugin --profile web remove dsh-dbhub-live
-```
-
-## 故障排查
-
-| 现象 | 处理 |
-| --- | --- |
-| 首次使用报「无法获取 dbhub」 | 确认本机有 npm 且能联网；离线可手动安装 `dbhub` 并加入 PATH。 |
-| 工具显示「dbhub 服务不可用」 | 查看 `dsh web` 日志；进程异常退出时插件会在下次调用自动重启。 |
-| 扫描不到配置文件 | 默认跳过 `node_modules` / `.git` / `target` / `dist` 等目录，可改用「输入 DSN」或「填写分项」。 |
-| 需要自定义 dbhub 版本 | 删除 `~/.dsh/storages/dsh-dbhub-live` 后设置 `DSH_DBHUB_PACKAGE` 指定包/版本。 |
-| 不希望自动更新 dbhub | 设置环境变量 `DSH_DBHUB_UPDATE_DAYS=0`。 |
-
-## 许可证
-
-[MIT](./LICENSE)
+# dsh-dbhub-live
+
+**简体中文** · [English](README.en.md)
+
+> 让 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/DeepSeek-Harness) 直接、安全地操作数据库：常驻多源连接 + 按工作区工具 + 临时动态连接 + 懒加载与浏览器状态卡片。
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![DSH](https://img.shields.io/badge/DSH-plugin-blue.svg)](#安装)
+[![DBHub](https://img.shields.io/badge/Built_on-DBHub-22a05a)](https://github.com/bytebase/dbhub)
+[![npm version](https://img.shields.io/npm/v/dsh-dbhub-live)](https://www.npmjs.com/package/dsh-dbhub-live)
+[![Listed on dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/zh/plugins/mr-mihu/dsh-dbhub-live)
+
+`dsh-dbhub-live` 是一个 DSH 插件，基于 [DBHub](https://dbhub.ai)（数据库 MCP 服务器）让模型直接查询数据库：既能在已配置的工作区上复用常驻连接，也能临时连任意库做一次性排查。
+
+## ✨ 特性
+
+- **常驻多源服务** — 后台一个 dbhub 服务同时接入多个数据源，连接复用、查询更快。
+- **按工作区工具** — `dbhub_execute_sql_<工作区>` / `dbhub_search_objects_<工作区>`，工具名即工作区，多工作区不混淆，连接标注（密码打码）清晰可见。
+- **临时动态连接** — `dbhub_query` / `dbhub_query_objects` 每次独立连任意库，可并行查多个不同库，便于跨环境排查。
+- **懒加载启动** — 插件启动不阻塞 GUI，工具立即可用；环境初始化推迟到首次调用（初始化期间查询自动等待就绪）。
+- **启用 / 禁用开关** — 关闭后所有 dbhub 工具立即返回「插件已禁用」友好提示，无需重启；再次开启立即可用。
+- **浏览器状态卡片** — 设置 → 插件 → dsh-dbhub-live 面板实时展示：运行状态徽章（🟢 运行中 / 🟡 初始化中 / 🔴 异常）、已注册工具数、工作模式、最近错误（红色），并提供启用/禁用开关。
+- **开箱即用** — 未安装 `dbhub` 时首次使用自动安装，之后自动保持更新，无需手动处理。
+- **多种配置方式** — 显式 DSN / 填写分项 / 授权扫描项目配置文件，凭据仅存本机用户目录，密码全程脱敏。
+
+## 支持的数据源
+
+MySQL · PostgreSQL · MariaDB · SQLite · SQL Server
+
+## 环境要求
+
+- DeepSeek Harness 的 `dsh` CLI（`dsh web` 负责 GUI 运行）
+- 推荐本机有 Node.js ≥ 18（含 `npm`）——首次使用会自动安装 `dbhub`
+
+## 安装
+
+```bash
+# 方式一：使用本机已安装的 dsh
+dsh plugin --profile web add dsh-dbhub-live
+
+# 方式二：通过 npx 调用 dsh（无需本机全局安装 dsh）
+npx @deepseek-ai/dsh plugin --profile web add dsh-dbhub-live
+```
+
+安装后**重启 `dsh web`** 生效（重启后到 设置 → 插件 → dsh-dbhub-live 可看到状态卡片）。
+
+## 快速开始
+
+以下工具由 DSH 的 AI 自动调用，你不用手动执行——直接用自然语言提出需求即可（如「查一下 users 表」），AI 会按需完成配置与查询：
+
+```text
+# 1) 若当前工作区还没有连接，AI 先为其配置数据库连接（三种方式见下方「配置方式」）
+dbhub_configure
+
+# 2) 在已配置工作区的常驻连接上执行查询
+dbhub_execute_sql_myapp  SELECT * FROM users LIMIT 10;
+
+# 3) 临时连任意库做一次性排查
+dbhub_query  dsn=mysql://user:pass@127.0.0.1:3306/mydb  sql="SHOW TABLES;"
+```
+
+## 工具
+
+| 工具 | 说明 |
+| --- | --- |
+| `dbhub_configure(workspace?, env?, dsn?)` | 为工作区配置/持久化数据库连接（可指定环境名，默认 `default`）。 |
+| `dbhub_list_sources()` | 列出当前已注册的全部连接源（工作区 × 环境、打码连接串、来源与对应 **source 值**）；**打码连接串仅供识别，不可用于直连**。 |
+| `dbhub_execute_sql(source, sql)` | 在指定数据源的常驻连接上执行 SQL；`source` 见 `dbhub_list_sources`（默认环境不带后缀，命名环境如 `…_test`）。 |
+| `dbhub_search_objects(source, object_type, ...)` | 在指定数据源搜索数据库对象（表/视图/列/索引等）。 |
+| `dbhub_query(dsn, sql)` | 临时连接任意库执行 SQL（多语句用 `;` 分隔）；**检测到 `****` 脱敏密码会直接拒绝**并引导使用常驻工具。 |
+| `dbhub_query_objects(dsn, ...)` | 临时连接任意库搜索数据库对象；同样拒绝脱敏密码。 |
+
+> 常驻工具**声明数量恒定**（不随工作区/环境数量增长）：全部工作区 × 环境通过 `dbhub_execute_sql` / `dbhub_search_objects` 的 `source` 参数选择，语义等价于每个工作区×环境一个工具，但**不占据多余上下文空间**。
+
+> 注：`search_objects` 仅对 SQLite 开放；MySQL / PostgreSQL 等请用 `dbhub_query` 直接查（如 `SHOW TABLES`）。
+
+### 配置方式
+
+1. **显式 DSN** — 传入完整连接串，如 `mysql://user:pass@host:3306/db`。
+2. **填写分项** — 按类型 / 主机 / 端口 / 账号 / 密码 / 库名依次填写。
+3. **授权扫描** — 授权后扫描项目配置文件（`.env`、`application*.yml`、`docker-compose`、`jdbc.properties` 等），列出候选（密码打码）供你确认。
+
+工作区若已有 `mise env` 或 `.env`（`DSN` / `DB_*`），插件会自动发现，无需手动配置。
+
+## 状态卡片
+
+设置 → 插件 → dsh-dbhub-live：插件会把运行状态与配置实时同步到 Web 设置面板（仅 `dsh web` 端可见）。卡片为**整行折叠**样式（与其它插件设置卡一致）：
+
+**折叠态（默认）**：一行显示 运行状态徽章（🟢 运行中 / 🟡 初始化中 / 🔴 异常 / ⚪ 已禁用）、环境数量、**启用/禁用开关**——不展开也能看状态、切开关。
+
+**展开后**分三块——
+
+**状态**（辅助信息，工具声明数固定已非重点）：
+
+- 常驻进程：运行中 / 待启动（按需）——空闲回收后显示「待启动」。
+- 工作模式：懒加载（首次调用时初始化）。
+- 工具声明：`6 个（固定）`；环境：`N 个 · 已保存 M`。
+- 最近错误（异常时红色展示）。
+
+**配置**（编辑后点「保存配置」即时生效并持久化）：
+
+| 参数 | 说明 | 默认 |
+| --- | --- | --- |
+| 自动更新间隔(天) | 自动更新 dbhub 的间隔天数，`0` 关闭 | `7` |
+| 空闲回收(分钟) | 常驻 dbhub 进程空闲回收时长 | `10` |
+
+优先级：**用户设置 > 进程环境变量（默认值种子）> 内置默认**。自动安装包不在 UI 中（`DSH_DBHUB_PACKAGE` 环境变量单独控制，默认 `@bytebase/dbhub`）。
+
+**工作区连接**：
+
+- 列出每个工作区 × 环境的连接：工作区名、环境名、**source 值**（模型调用 `dbhub_execute_sql` 时填这个，等宽字体显示）、**打码**连接串、来源徽章（`已保存` / `自动`）。
+  - `已保存`：你配置过（`dbhub_configure` 或卡片添加）。
+  - `自动`：未保存，来自 `mise env` / `.env` 自动发现——不持久化，随源文件变化；自动发现不对时可直接「修改」为手动配置覆盖。
+- 每行可「修改」（覆盖连接串，自动项会转成已保存项）或「删除」（仅已保存项）。
+- **同一工作区可添加多个环境**：表单填「工作区（路径或标题，留空=默认当前工作区）+ 环境名 + 连接串」点「添加连接」。默认环境 source 不带后缀，命名环境如 `<工作区>_<环境>`。
+
+## dbhub 环境变量
+
+| 环境变量 | 说明 | 默认 |
+| --- | --- | --- |
+| `DSH_DBHUB_PACKAGE` | 自动安装使用的 npm 包名（仅环境变量，不在 UI 暴露） | `@bytebase/dbhub` |
+| `DSH_DBHUB_UPDATE_DAYS` | 自动更新间隔天数种子，`0` 关闭（被设置卡片保存过的值覆盖） | `7` |
+
+## 🔄 dbhub 自动安装与更新
+
+- **首次使用自动安装**：本机没有 `dbhub` 时，插件会在第一次查询时自动安装，之后离线也可用。
+- **自动保持更新**：后台静默更新到最新版（间隔见「状态卡片 → 可配置参数」），失败则沿用现有版本。
+- **不碰你的配置**：通过 PATH / mise 自行安装的 `dbhub` 不会被插件改动。
+
+> 更新间隔默认值也可用环境变量播种，见「状态卡片 → 配置」；一旦在设置卡片保存过，即以设置值为准。
+
+## 数据位置
+
+所有配置与凭据存放在模块目录之外（不受 pnpm 打包影响），删除该目录即可完整清空：
+
+```
+~/.dsh/storages/dsh-dbhub-live/
+```
+
+按 `DSH_HOME` 实例隔离，同一实例的多个 profile 共享（与 dsh 自身 `workspace.json` 同一约定）。工作区连接按「工作区 × 环境」存储（`environments.default` 为默认环境）；v1 旧格式单连接条目启动时自动迁移。插件对升级/手改遗留的旧格式配置自动清洗并一次性迁移；运行目录被误删或写入被系统拦截时不会崩溃——自动重建目录、写入失败仅告警并继续内存态运行，`dbhub.toml` 写入失败则显示为初始化错误并自动重试。
+
+## 卸载
+
+```bash
+dsh plugin --profile web remove dsh-dbhub-live
+```
+
+## 故障排查
+
+| 现象 | 处理 |
+| --- | --- |
+| 首次使用报「无法获取 dbhub」 | 确认本机有 npm 且能联网；离线可手动安装 `dbhub` 并加入 PATH。 |
+| 状态卡片显示 🔴 异常 | 查看状态卡片中的「最近错误」与 `dsh web` 日志；进程异常退出时插件会在下次调用自动重启。 |
+| 工具显示「插件已禁用」 | 打开 设置 → 插件 → dsh-dbhub-live 卡片，点击「启用」。 |
+| 看不到状态卡片 | 确认插件已安装并重启 `dsh web`；状态卡片只在 Web 设置面板（`dsh web`）显示，在无设置面板的终端环境下不影响工具使用。 |
+| 扫描不到配置文件 | 默认跳过 `node_modules` / `.git` / `target` / `dist` 等目录，可改用「输入 DSN」或「填写分项」。 |
+| 需要自定义 dbhub 版本 | 设置环境变量 `DSH_DBHUB_PACKAGE`（如 `@bytebase/dbhub@1.2.1`）后重启；或删除 `~/.dsh/storages/dsh-dbhub-live` 重新自动安装。 |
+| 不希望自动更新 dbhub | 状态卡片「自动更新间隔(天)」填 `0` 并保存；或设置环境变量 `DSH_DBHUB_UPDATE_DAYS=0`。 |
+
+## 许可证
+
+[MIT](./LICENSE)

package/cordis.patch.yml

@@ -1,8 +1,8 @@
-# dsh-dbhub-live bundle patch — declares the plugin row this package mounts.
-# `dsh plugin --profile web add dsh-dbhub-live` installs this package into the
-# profile; reconcilePlugins sees `dsh.bundle.patch` and appends the package to
-# `dsh.profile.bundles`, then this patch layer inserts the row. The bare name
-# resolves the package's main (lib/index.mjs) from the profile's node_modules.
-- insert:
-    - id: dbhub-live
-      name: 'dsh-dbhub-live'
+# dsh-dbhub-live bundle patch — declares the plugin row this package mounts.
+# `dsh plugin --profile web add dsh-dbhub-live` installs this package into the
+# profile; reconcilePlugins sees `dsh.bundle.patch` and appends the package to
+# `dsh.profile.bundles`, then this patch layer inserts the row. The bare name
+# resolves the package's main (lib/index.mjs) from the profile's node_modules.
+- insert:
+    - id: dbhub-live
+      name: 'dsh-dbhub-live'