dsh-dbhub-live 4.0.0 → 4.1.0

package/AGENTS.md

@@ -4,7 +4,7 @@
 
 ## 一句话定位
 
-DSH host 插件（Node ESM）+ Web client 插件（浏览器半）：把 dbhub（Bytebase 的数据库 MCP 服务器）接入 DSH。**零知识凭据管理 + 一次性进程执行**——DSN/密码只存在于宿主侧，模型只见 source 句柄与元数据（类型/主机/端口/库）；每次工具调用 spawn 一条独立 `dbhub --dsn` 进程跑完即杀，无常驻服务。附设置在「设置 → 插件」里的实时状态卡片与启用/禁用开关。
+DSH host 插件（Node ESM）+ Web client 插件（浏览器半）：把 dbhub（Bytebase 的数据库 MCP 服务器）接入 DSH。**零知识凭据管理 + 一次性进程执行**——DSN/密码只存在于宿主侧，模型只见 source 句柄与元数据（类型/主机/端口/库）；每次工具调用 spawn 一条独立 `dbhub --dsn` 进程跑完即杀，无常驻服务。附配置页（设置 → DBHub 数据库工具 / 侧边栏快捷入口（可关）/ 插件页该行的「配置」）：实时状态 + 连接管理（启用禁用、增删改查、环境改名、连接测试）。
 
 ## 目录结构
 
@@ -18,8 +18,8 @@ lib/
   mcp.mjs      MCP JSON-RPC 客户端 + 工具注册表 + 工作区×环境来源发现（collectSources/resolveSource）+ 摘要缓存
   adhoc.mjs    唯一执行引擎：每次调用一条一次性 dbhub 进程（零知识标签 + stderr 清洗）
   collect.mjs  授权扫描项目配置文件并提取 DSN 候选（含 askUser 桥接）
-  tools.mjs    host 自有工具定义与注册：恒定 4 个（configure/list_sources/execute_sql/search_objects）
-  client.js    Web 半（手写 lazy-CJS bundle）：折叠分区卡片（状态/配置/工作区连接）
+  tools.mjs    host 自有工具定义与注册：恒定 4 个（configure/list_sources/execute_sql/search_objects）；configure 探连优先（见零知识契约 5）
+  client.js    Web 半（手写 lazy-CJS bundle）：配置页 = `settings.section` 一级设置页 + 可选侧边栏面板（`showSidebarEntry` 开关）+ `plugins.row.config`（summary/page 两视图）
 test/          node:test 单元测试（纯逻辑 + client bundle 格式契约 + 零知识泄漏门）
 doc/           需求文档
 cordis.patch.yml   bundle patch：`name: dsh-dbhub-live` 挂载本包
@@ -32,13 +32,15 @@ cordis.patch.yml   bundle patch：`name: dsh-dbhub-live` 挂载本包
 - **零知识模型契约（红线）**：
   1. 工具**参数**：`source`/`sql`/`object_type` 等 + configure 的非密预填（type/host/port/database/user）。**任何工具都不得声明 `dsn` 参数**（模型传 DSN 会把密码带进上下文）；configure 收到 `args.dsn` 直接拒绝（`result.noDsnViaModel`）。`dbhub_query`/`dbhub_query_objects` 已删除，勿恢复。
   2. 工具**输出**：结果/列表/标签一律 `connLabel(dsn)`（`type://host:port/db`）或 i18n 模板，密码与用户名永不出现；`dbhub` 返回的文本（含 stderr）进模型前必须过 `scrubSecrets(text, dsn)`。
-  3. **密码只在界面输入**：configure 的密码/完整 DSN 一律经 `askUser`（用户敲键盘，不经模型上下文）；设置卡片 add/edit 的 DSN 走 `configOp` 通道（浏览器→Host），同样不进模型上下文。
-  4. 鉴权/连接失败闭环：`likelyAuthOrConnError` 命中时在错误文本后附 `result.authHint`（引导 `dbhub_configure` 或设置卡片修改，密码由用户输入）。
-  5. **零密码泄漏门**：`test/zero-knowledge.test.mjs` 断言 summarizeRows 无 dsn 字段、无工具声明 `dsn` 参数、描述/i18n 文案不含真实形态 DSN；`util.test` 断言 scrubSecrets/connLabel 行为。改模型可见文案时这些测试必须保持绿。
-- **状态命名空间**：Host 注册 `dsh-dbhub-live` 命名空间（`ctx.inject(['settings'], …)` + schema）；Web 端 Plugins 选项卡按命名空间分发 `settings.plugin.item` 卡片。命名空间值 = 状态 `{enabled, phase(running|disabled), toolCount(恒定4), lastError, mode('oneshot')}` + 配置 `{updateIntervalDays}` + `{workspaces(JSON 元数据摘要：title/path/env/conn(主机端口库)/source/persisted/srcId)}` + `{configOp}`（主机消费后自动清空）+ `{testResult}`（连接测试的一次性回执，仅内存态、不落任何持久化）。**注入回调是独立作用域：内部需要的服务（如 `subprocess`）必须用 `ctx.get('subprocess')` 就地获取，绝不能引用 `apply()` 的局部变量——否则 ReferenceError 会静默杀死整条发布/配置链路（卡片只剩静态值、工作区连接不刷新）**。回调整体套 `wrap()` 防护，异常必须打日志。
-- **可配置参数**：`options.mjs` 只此一处持有部署开关：`updateIntervalDays`（设置 UI > 环境变量种子 > 内置默认；`dbhubPackage` 仅环境变量/内部，不进设置）。**已删除 `idleMinutes`**（无常驻进程可回收）。不要绕过 `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`，不持久化。**连接测试（`{op:'test', workspace, env, nonce}`）**：`handleTestOp` 用摘要背后的真实 DSN 调 `adhoc.probeConnection`（一次性 dbhub + `SELECT 1`，Host 侧 30s 超时兜底），结果经 `testResult` 镜像字段回推 `{nonce, ok, message}`；测试失败只是行内一次性提示，不得写入 store/lastError/phase。卡片只认自己派发过的 nonce，展示 ~10s 自动消退，刷新即失，天然不保留状态。
-- **工具声明数量恒定（上下文预算红线）**：恒定 4 个（configure / list_sources / execute_sql / search_objects），**绝不为每个工作区 × 环境注册独有工具**；`dbhub_execute_sql(source,…)` / `dbhub_search_objects(source,…)` 调用时 `resolveSource` 按 source 值（`标题_hash[_环境]`）解析到真实连接。曾实现过的 per-source 注册与 `dbhub_query` 临时连接工具已移除，勿回恢复。
+  3. **密码只在界面输入**：configure 的密码/完整 DSN 一律经 `askUser`（用户敲键盘，不经模型上下文）；配置页 add/edit 的 DSN 走 `configOp` 通道（浏览器→Host），同样不进模型上下文。
+  4. **鉴权/连接失败闭环**：`likelyAuthOrConnError` 命中时在错误文本后附 `result.authHint`（引导 `dbhub_configure` 或配置页修改，密码由用户输入）。
+  5. **configure 探连优先（交互红线）**：`dbhub_configure` 收到非敏感预填（type/host/database 齐备、非 sqlite）时先宿主侧试连候选 DSN（空密码）：可连通 → 直接持久化返回，**零弹窗**；试连提示需凭据 → 只弹「账号（未知时）+ 密码」最小输入框（`result.ask-*`），其余信息自动沿用；信息不完整或非鉴权失败 → 才弹完整选项（DSN/分项/扫描）。已配置行先探真实 DSN（含已存密码），通过即 `existing-ok` 零输入返回；**模型参数改变了端点（type/host/port/database 任一不同，`argsChangedEndpoint`）时视为新目标，对预填候选重跑试连循环**。凭据弹窗带诊断明细（`detail` = 试连失败原因）与逃生口（`result.askCredMore` → 回到完整选项，避免凭据弹窗死循环；凭据保存后再探失败附 `result.authHint`）。模式菜单里**不再有「仅填写密码」选项**——最小凭据框已取代它；「仍用现有连接」是字面沿用（不补填缺失字段，`result.useExisting*` 文案已澄清）；分项表单会把已知值带入（`result.askHost/askPort/askUserField/askDatabase`，未触碰字段保留预填值）。**试连诊断明确指向“空账号被拒”（`emptyUserDenied`，如 `Access denied for user ''@…`）时，账号为必填**：最小凭据框不提供「留空（使用空账号）」选项，用户仍提交空账号则拒绝保存（`result.askAccountRequired*`），避免把同一个必失败的 DSN 再存回去。决策逻辑收敛在 `config.mjs` 的 `decideConfigureStep`/`argsChangedEndpoint`/`emptyUserDenied`（纯函数，`util.test` 覆盖）。
+  6. **零密码泄漏门**：`test/zero-knowledge.test.mjs` 断言 summarizeRows 无 dsn 字段、无工具声明 `dsn` 参数、描述/i18n 文案不含真实形态 DSN；`util.test` 断言 scrubSecrets/connLabel/buildDsnFromParts/decideConfigureStep 行为。改模型可见文案时这些测试必须保持绿。
+- **状态命名空间**：Host 注册 `dsh-dbhub-live` 命名空间（`ctx.inject(['settings'], …)` + schema）；Web 端有三个入口指向同一个页面：**`settings.section`（id `dbhub`，主入口，settings 面板是核心 shell）**、**可选侧边栏面板**（`sidebar.panellist` + `main`，受 `showSidebarEntry` 控制）、**`plugins.row.config`**（键 `<包名>#<行 id>` = `dsh-dbhub-live#dbhub-live`，owner props 为 `view: 'summary' | 'page'`，该 slot 只在官方插件页的浏览器半区活跃时存在）。**dsh 0.1.6 已删除旧的 `settings.plugin.item` 槽位**：注册到不存在的 slot 会被静默忽略（不报错、界面什么都不显示）——升级 dsh 后「配置页消失」就是这个原因，不要再改回去。命名空间值 = 状态 `{enabled, phase(running|disabled), toolCount(恒定4), lastError, mode('oneshot')}` + 配置 `{updateIntervalDays, showSidebarEntry}` + `{workspaces(JSON 元数据摘要：title/path/env/conn(主机端口库)/source/persisted/srcId)}` + `{configOp}`（主机消费后自动清空）+ `{testResult}`（连接测试的一次性回执，仅内存态、不落任何持久化）。**注入回调是独立作用域：内部需要的服务（如 `subprocess`）必须用 `ctx.get('subprocess')` 就地获取，绝不能引用 `apply()` 的局部变量——否则 ReferenceError 会静默杀死整条发布/配置链路（配置页只剩静态值、工作区连接不刷新）**。回调整体套 `wrap()` 防护，异常必须打日志。
+- **可配置参数**：`options.mjs` 只此一处持有部署开关：`updateIntervalDays`（设置 UI > 环境变量种子 > 内置默认；`dbhubPackage` 仅环境变量/内部，不进设置）、`showSidebarEntry`（布尔，默认 `true`，设置页开关即时生效）。**已删除 `idleMinutes`**（无常驻进程可回收）。不要绕过 `applyPatch` 直接改 `options` 内部值。
+- **工作区连接管理（configOp 通道）**：store v2 = `{ [wsPath]: { environments: { [env]: {dsn, source, updatedAt} } } }`（v1 单 dsn 条目自动迁移进 `environments.default`）。环境名一律过 `normalizeEnvName`（trim、去控制字符、限长、空值收敛为 `default`），因此**中文环境名是一等公民**。配置页只读**元数据**摘要（`collectSources` → `latestSummaries`，密码/用户名永不出 Host）；增/改/删/改名通过命名空间 `configOp` 单向命令下发，`index.mjs` 用 `setWorkspaceEnv`/`removeWorkspaceEnv`/`renameWorkspaceEnv` 落盘后重扫摘要并发布（configOp 随发布清空，天然防环）。`add`/`set` 可带 `renameFrom` 做「改名 + 改连接」的**单条原子命令**（`configOp` 是单字段，拆两次写会互相覆盖）；纯改名走 `{op:'rename', workspace, env, newEnv}`。自动发现（mise/.env）只提供未覆盖的 `default`，不持久化。**连接测试（`{op:'test', workspace, env, nonce}`）**：`handleTestOp` 用摘要背后的真实 DSN 调 `adhoc.probeConnection`（一次性 dbhub + `SELECT 1`，Host 侧 30s 超时兜底），结果经 `testResult` 镜像字段回推 `{nonce, ok, message}`；测试失败只是行内一次性提示，不得写入 store/lastError/phase。配置页只认自己派发过的 nonce，展示 ~10s 自动消退，刷新即失，天然不保留状态。
+- **工具声明数量恒定（上下文预算红线）**：恒定 4 个（configure / list_sources / execute_sql / search_objects），**绝不为每个工作区 × 环境注册独有工具**；`dbhub_execute_sql(source,…)` / `dbhub_search_objects(source,…)` 调用时 `resolveSource` 按 source 值解析到真实连接。曾实现过的 per-source 注册与 `dbhub_query` 临时连接工具已移除，勿回恢复。
+- **工作区语义（模型契约，勿退化）**：**每条 source 只属于一个工作区**，跨工作区的「看起来一样」的连接是不同目标。`sourceIdOf(row)` 是 source 值的**唯一**构造点（`<标题slug>_<工作区路径哈希>[_<环境slug>]`），列表输出、解析器、各工具回执必须都调它，否则模型会拿到解析不回去的句柄。`envSlug`：`default` 保持裸值、纯 ASCII 名保持原 slug（`test`→`test`，既有 source 值不变）、含非 ASCII 的名（`线上`）取 `env-<shortHash>`——**旧实现对每个纯中文名都返回同一个 slug**，`线上` 与 `测试` 曾共用 source 值并被静默查错库；这是回归红线。`resolveSource(ctx, sub, ref, {preferredWsPath})` 精确优先，其次按**当前会话工作区**（`currentWorkspace(ctx, exec)`：会话 cwd 精确匹配 → 最长包含路径）筛选，仍有多条则返回 `{ambiguous:[…]}`，由 `result.ambiguousSource` 让模型用完整 source 值澄清——**绝不按列表顺序猜**。`dbhub_configure` 的工作区解析也**不再回退到 `workspaces[0]`**（那是「把连接配到别人工作区」的隐患）：显式 workspace 必须匹配，否则 `result.unknownWorkspace` 列出可用工作区；未给 workspace 时用当前工作区，解析不出来则 `result.needWorkspace`。跨工作区复用连接一律走 `copyFrom`（宿主侧复制 DSN，零知识不破）而不是直接用别人的 source。`dbhub_list_sources` 按工作区分组并标出【当前工作区】（`result.wsCurrentHead`/`wsOtherHead`/`wsGroup`）。
 - **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()` 只注册核心工具 + 后台 bookkeeping（`startBackgroundBoot`：置 phase running、刷新工具数、非阻塞检查 dbhub 自动更新）；真正的 dbhub 解析（persisted → mise → PATH → 自动安装）发生在**每次调用**（`resolveDbhubExe` 有 runtime.json 缓存，首次或缺二进制时才安装）。**无工作区数据源时一切照常**——工具正常注册，list_sources 返回空、execute 返回 noSource，不会拉起任何进程。
 - **启用/禁用**：`state.setEnabled` 持久化到 `credentials.json`（权威值）；禁用时所有工具 execute 首行返回「插件已禁用」（无进程可停，无需清理）；重新启用即恢复。
@@ -56,13 +58,15 @@ DSH 启动是 fail-loud：任一插件激活失败整树拒绝启动、GUI 打
 
 1. **静态校验（30 秒，零风险）** — `npm run check`（node --check 全部 lib）→ 逐个跑单测（沙箱下 `node --test` 的 runner 子进程会被 EPERM 挡，按本文件惯例**逐个文件**跑：`node test/x.test.mjs`）。单测会自己建临时 `DSH_HOME`，不会碰真实 store。
 2. **会话内跑通逻辑（不重启）** — 用动态插件工具连（`cordis_define`/`cordis_run`/`cordis_stop`/`cordis_undefine`）：把要验证的纯逻辑（如 configure 流程、scrubSecrets）以无 import 的 Host 代码贴进动态包，在会话里跑，`cordis_stop` 即清场。动态包只活在进程内存 + 当前会话，改动/出错都不影响主进程。动态 Host 代码不能用 `import`，带 `@deepseek-ai/schemastery` import 的 `lib/index.mjs` 不能整文件贴进动态包；只对纯逻辑做动态验证。
-3. **冷启动验证（隔离实例）** — 用独立 `DSH_HOME` 起测试实例：
+3. **冷启动验证（隔离实例）** — 用独立 `DSH_HOME` 起测试实例。本机备有独立测试 home：`deepseek-harness/mise.toml` 已把 `DSH_HOME` 指向 `D:/my/app/dsh/plugin/.dsh-a`，所以在该目录下用 `mise r dsh …` 启动的实例**与主进程（`%USERPROFILE%\.dsh`，3080）完全隔离**：
    ```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
+   cd D:\my\app\dsh\plugin\deepseek-harness          # mise.toml 在此，DSH_HOME 已指向 .dsh-a
+   mise r dsh web --port 3082 --no-open               # 首次自动初始化 web 模板
+   mise r dsh plugin --profile web add D:/path/to/<pkg>.tgz   # 用 pnpm pack 产物；同版本会被跳过，必须先升版本号
+   mise r dsh plugin --profile web ls                 # 核对 node_modules/<pkg>/package.json 版本确已替换
+   mise r dsh web --port 3082 --no-open
+   # 验证：日志出现 [dsh-dbhub-live] 加载 + 「设置页入口已注册: settings.section id=dbhub」「插件页配置入口已注册: plugins.row.config …」；
+   #      GET /plugins/dsh-dbhub-live/client.js 返回 bundle；http://127.0.0.1:3082 侧边栏出现「DBHub 数据库工具」、设置里出现同名一级页面
    ```
 4. **在位热更新（有失败保护，谨慎）** — 主实例的 `cordis.patch.yml` 支持 HMR，读取/解析失败时保留最后一个可用树，GUI 不会挂。但 HMR 不监听插件源码，只适合挂载/卸载验证，代码迭代请用 1/2/3。
 5. **安全网** — `$DSH_SNAPSHOT=replay` 可从 `cordis.snapshot.yml` 启动回放点；改动主 profile 前先备份 `cordis.patch.yml`。
@@ -75,8 +79,9 @@ DSH 启动是 fail-loud：任一插件激活失败整树拒绝启动、GUI 打
 - `id` 必须等于 Loader entry 名（`dsh-dbhub-live`，见 cordis.patch.yml 的 `name`），不是行 id；
 - factory 只允许 `require("react")` 等 baseline 模块；不 import 其他插件的值（bundle-purity）；
 - 导出 `name/inject/apply`，结尾 `return module.exports`；
+- 注册的 slot 必须是 `plugins.row.config`（key = `dsh-dbhub-live#dbhub-live`；见「状态命名空间」条），组件同时服务 `props.view === 'summary'`（一行摘要）与 `'page'`（完整表单，页面自己画标题/图标/面包屑）；**另外必须注册 `settings.section`（id `dbhub`，order 40）作为主入口**——设置面板是核心 shell，任何部署都在，用户也在那里找连接管理；`plugins.row.config` 只在官方插件页的浏览器半区活跃时存在，不能作为唯一入口。侧边栏快捷入口（`sidebar.panellist` id `dbhub` + `main` key `dbhub`，组件 `PanelIcon`/`ConfigPanel`）**由 `showSidebarEntry` 选项控制**：`syncSidebar()` 在 `host.subscribe` 上按镜像值即时 register/dispose，关闭它不得影响设置页与插件页入口（避免自锁）；
 - 组件不得接触 `ctx`，数据/回调一律通过注册时的 `inject: () => face` 传入 props；用内联样式，不依赖 CSS 文件；
-- 卡片渲染的 `workspaces` 行现在只显示 `w.conn`（元数据标签），**不得显示/回显 DSN**。
+- 配置页渲染的 `workspaces` 行只显示 `w.conn`（元数据标签），**不得显示/回显 DSN**；改名走 `configOp({op:'rename'})`，改名+改连接走**一条** `{op:'add', renameFrom}`（`configOp` 是单字段，连续两次写会互相覆盖）。
 - 若本包脱离仓库（发布 npm），`dsh.client` 与 `exports["./client"]` 必须保留，否则 client-modules 扫描会启动报错。
 
 ## 质量门
@@ -86,6 +91,7 @@ npm run check   # 全部 lib 语法
 # 单测：沙箱内逐个文件跑（node --test 的 runner 子进程在沙箱下 EPERM）
 node test/util.test.mjs && node test/state.test.mjs && node test/options.test.mjs \
   && node test/init.test.mjs && node test/i18n.test.mjs \
+  && node test/resolve-source.test.mjs && node test/resolve-workspace.test.mjs \
   && node test/client-format.test.mjs && node test/zero-knowledge.test.mjs
 ```
 
@@ -99,12 +105,17 @@ git grep -inE '10\.253\.|192\.168\.77|tx_zdsf|tx_sd_jineng|db_zdsf|hbtx|1hn7yaw|
 
 发布前：按「调试方法」第 3 步在隔离实例完整冷启动一遍，确认 Host 无报错、`/plugins/dsh-dbhub-live/client.js` 可访问。
 
-## 版本号策略（内部调试 ≠ 发布）
+## 版本号策略（测试版本 → 发布版本）
 
-- **每次内部调试迭代都升小版本**（如 `4.0.0-dev.1`、`4.0.0-dev.2`、`4.0.0-dev.3`…），`pnpm pack` 产物随之换名；
+- **基线 = 代码库当前版本**（`package.json` 版本，即最近一次发布）。测试/调试迭代一律在基线上挂 `-dev.<序号>`，序号从 1 递增、不复用（如 `4.0.1-dev.1`、`4.0.1-dev.2`…），`pnpm pack` 产物随之换名；
 - 原因：pnpm 对 `dsh plugin add <同名同版本 tarball>` 会判「Already up to date」跳过、**不换包**；升版本号才能保证调试包真正部署。
 - `dsh plugin add` 后务必用 `dsh plugin ls` 或核对 `node_modules/<pkg>/package.json` 的版本号确认已替换。
-- **发布时**再升级发布版本（如调试到 `4.0.0-dev.N` 后，正式版打 `4.0.0`），tag/npm 一律用正式版本号。
+- **测试完成要发版时，在基线上按「跨度和力度」决定升级幅度**（不以 dev 序号原号发布）：
+  - 小 bug 修复 / 小功能改动 → 升**补丁号**：`4.0.0` → `4.0.1`（例：测试到 `4.0.0-dev.8` 仅小修 → 发布 `4.0.1`）；
+  - 大功能新增 / 影响面较广的功能改动 → 升**次版本号**：`4.0.0` → `4.1.0`；
+  - 破坏性升级 / 阶段性架构变更 / 跨度过大 → 升**主版本号**：`4.0.0` → `5.0.0`（tag/npm 一律打正式版本号）。
+  - 跨档并存时按最高档计（含破坏性改动 → 主版本）；归属拿不准时**先向用户确认再发版**，禁止未确认跨度直接升主版本。
+- **发布版本成为新基线**，下一轮测试从 `新基线-dev.1` 重新起序（如 `5.0.0-dev.1`…）。
 
 ## 约定
 

package/README.en.md

@@ -2,7 +2,7 @@
 
 [简体中文](README.md) | English
 
-> Let [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/DeepSeek-Harness) operate databases directly and safely: **zero-knowledge credentials** (passwords never reach the model) + **one-shot process execution** (no resident server — naturally concurrent and multi-instance safe) + workspace × environment connection management + a browser status card.
+> Let [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/DeepSeek-Harness) operate databases directly and safely: **zero-knowledge credentials** (passwords never reach the model) + **one-shot process execution** (no resident server — naturally concurrent and multi-instance safe) + workspace × environment connection management + a browser Configure Page.
 
 [![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)
@@ -18,9 +18,9 @@
 - **One-shot process execution** — no resident dbhub service: each call spawns an independent process and recycles it when done. A hung/failed query only affects its own call; parallel tasks and multiple DSH instances running at once never interfere (no shared ports, no cross-kills).
 - **Constant 4 tool declarations** — `dbhub_configure` / `dbhub_list_sources` / `dbhub_execute_sql` / `dbhub_search_objects`; more environments never inflate the model context.
 - **Workspace × environment connection management** — one workspace can hold multiple environments (default / prod / dev / test…) distinguished by their `source` value.
-- **Auth-failure loop** — when credentials or connection details are wrong, the tool gives clear guidance; the model steers you to update the password in the UI (it never asks you for it), or you edit it directly in the settings card.
+- **Auth-failure loop** — when credentials or connection details are wrong, the tool gives clear guidance; the model steers you to update the password in the UI (it never asks you for it), or you edit it directly in the settings card. **Auto-probe during configuration**: non-sensitive connection facts are tested host-side first — if they connect they take effect with zero input (password-less databases never prompt), and if only the password is missing the dialog asks just for "account (when unknown) + password" instead of re-asking for the whole input method. When the probe explicitly blames an EMPTY account (e.g. `Access denied for user ''`), the account is required — the "leave empty (use empty account)" choice is not offered, so the same doomed DSN is never saved again.
 - **Enable / disable switch** — turning it off makes every dbhub tool return a friendly "plugin disabled" message immediately; no restart needed.
-- **Browser status card** — Settings → Plugins → dsh-dbhub-live shows live: status badge, mode (one-shot), registered tool count, environment count, recent error, plus the enable/disable switch, connection CRUD and connection tests.
+- **Browser configure page** — three entries to the same page: **Settings → DBHub Database Tools** (a first-level settings page, recommended), the **sidebar entry DBHub Database Tools** (a shortcut you can switch off on the settings page), and the plugin row's Configure control on the Plugins page. Shows live: status badge, mode (one-shot), registered tool count, environment count, recent error, plus the enable/disable switch, connection CRUD, **environment rename** and connection tests.
 - **Out of the box** — if `dbhub` is missing, the plugin installs it on first use and keeps it updated at your configured interval.
 
 ## Supported Data Sources
@@ -42,10 +42,10 @@ dsh plugin --profile web add dsh-dbhub-live
 npx @deepseek-ai/dsh plugin --profile web add dsh-dbhub-live
 
 # Update to a specific version (pin the currently published version so pnpm doesn't skip with "Already up to date")
-dsh plugin --profile web update dsh-dbhub-live@4.0.0
+dsh plugin --profile web update dsh-dbhub-live@4.1.0
 ```
 
-After installing, **restart `dsh web`** for it to take effect (you can then see the status card at Settings → Plugins → dsh-dbhub-live).
+After installing, **restart `dsh web`** for it to take effect (you can then see the configure page at **Settings → DBHub Database Tools**).
 
 ## Quick Start
 
@@ -66,9 +66,9 @@ dbhub_list_sources
 
 | Tool | Description |
 | --- | --- |
-| `dbhub_configure(workspace?, env?, type?, host?, port?, database?, user?)` | Configure/persist a workspace connection. **Does NOT accept a dsn argument** — the password/DSN is always entered in the UI (never through the model); type/host/port/database/user may be passed as non-sensitive prefills. |
-| `dbhub_list_sources()` | List every connection source (workspace × environment): metadata only (type/host/port/database) + origin badge + the corresponding **source** value. |
-| `dbhub_execute_sql(source, sql)` | Execute SQL on a source; `source` comes from `dbhub_list_sources` (the default environment has no suffix; named environments look like `…_test`). Each call is an independent one-shot connection; multiple statements separated by `;`. |
+| `dbhub_configure(workspace?, env?, renameFrom?, copyFrom?, type?, host?, port?, database?, user?)` | Configure/persist a workspace connection. **Does NOT accept a dsn argument** — the password/DSN is always entered in the UI (never through the model); type/host/port/database/user may be passed as non-sensitive prefills. **With enough prefills the plugin auto-probes first**: connectable → saved directly and the source value returned; password required → a minimal "account (when unknown) + password" dialog; incomplete info or another failure → the full method choice appears. **Rename**: `env=new name` + `renameFrom=old name` (the connection and its credentials stay as they are; works for `default` → `prod` or a Chinese/English swap; an existing target is confirmed with the user first). **Cross-workspace copy**: `copyFrom=<another workspace's source value>` + `env=<environment to create here>`; the Host copies the connection, so the password never passes through the model. |
+| `dbhub_list_sources()` | List every connection source, **grouped by workspace** and marking the **[CURRENT WORKSPACE]**: metadata only (type/host/port/database) + origin badge + the corresponding **source** value. |
+| `dbhub_execute_sql(source, sql)` | Execute SQL on a source; `source` comes from `dbhub_list_sources`. **Every source belongs to exactly one workspace** — prefer the current workspace's; to reuse another workspace's connection, first copy it here with `dbhub_configure`'s `copyFrom` instead of querying that workspace's source directly. Each call is an independent one-shot connection; multiple statements separated by `;`. |
 | `dbhub_search_objects(source, object_type, ...)` | Search database objects (tables/views/columns/indexes, etc.) on a given source. |
 
 > **Security**: the model can never obtain a password through this plugin — results and lists only show metadata like `mysql://host:3306/db`; dbhub's error text is scrubbed before it is returned. On a failing query, follow the hint and update the password in the UI.
@@ -77,44 +77,44 @@ dbhub_list_sources
 
 ### Configuration Methods
 
+0. **Auto-probe (preferred by default)** — once you state connection facts in chat (e.g. "mysql 10.0.0.1:3307/mydb"), the plugin tests them first: connectable → saved immediately (password-less databases need zero input); password required → the dialog asks only for "account (when unknown) + password" with the failure reason and a "use another way" escape when the connection details themselves are wrong; when the probe blames an EMPTY account (e.g. `Access denied for user ''`), the account is required (no "leave empty" choice); incomplete info or another failure → the three methods below appear. If you name a different database/host/port than the saved connection, the plugin re-runs the probe against the new target.
 1. **Explicit DSN** — enter a full connection string in the UI, e.g. `mysql://user:pass@host:3306/db`.
-2. **Fill in fields** — fill type / host / port / user / password / database name in the UI.
+2. **Fill in fields** — fill type / host / port / user / password / database name in the UI; fields already known from the conversation are pre-filled — you only fill in the gaps.
 3. **Authorized scan** — after authorization, scan project config files (`.env`, `application*.yml`, `docker-compose`, `jdbc.properties`, etc.) and list candidates (host/port/database only — passwords are read host-side and never shown) 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
+## Configure Page
 
-Settings → Plugins → dsh-dbhub-live: the plugin syncs its 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):
+Three entries, one page and one state:
 
-> All card copy (name, status, config fields, buttons, connection rows) follows the dsh UI language (Chinese / English — Settings → General → Language); model-facing errors, feedback and the host logs follow it as well.
+1. **Settings → DBHub Database Tools** (recommended): the first-level settings page the plugin registers; present in every deployment.
+2. **Sidebar entry DBHub Database Tools**: a shortcut, on by default; turn off "Show the sidebar entry" on the settings page to drop it (applies immediately, no restart or reload).
+3. **Plugins → dsh-dbhub-live → Configure**: the configure control the official Plugins page gives each plugin row since dsh 0.1.6 (that page is provided by the official plugin manager; use the first two entries when it is absent).
 
-**Collapsed (default)**: one row shows the status badge (🟢 running / ⚪ disabled), environment count, and the **enable/disable switch**.
+> Hiding the sidebar entry never removes access: the settings page and the plugin row's Configure control stay available.
 
-**Expanded** shows three blocks —
+All page copy (name, status, config fields, buttons, connection rows) follows the dsh UI language (Chinese / English — Settings → General → Language); model-facing errors, feedback and the host logs follow it as well.
 
-**Status**:
-
-- Mode: one-shot connection (an independent process per call).
-- Tool declarations: `4 (fixed)`; environments: `N · M saved`.
-- Most recent error (shown in red on error).
+**Status**: status badge (🟢 running / ⚪ disabled), the **enable/disable switch**, mode (one-shot connection), tool declarations (`4 (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` |
+| Show the sidebar entry | Whether the DBHub Database Tools shortcut appears in the sidebar; applies immediately | on |
 
 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), **connection metadata** (🔒 `mysql://host:3306/db` — no username, no password; passwords never appear on the card), origin badge (`saved` / `auto`) and origin detail (`saved · user` / `saved · scan` / `auto · mise env` / `auto · .env`).
-  - `saved`: you configured it (`dbhub_configure` or added in the card).
+- Lists every workspace × environment connection: workspace name, environment name, **source value** (what the model passes to `dbhub_execute_sql`, shown in monospace), **connection metadata** (🔒 `mysql://host:3306/db` — no username, no password; passwords never appear on the page), origin badge (`saved` / `auto`) and origin detail (`saved · user` / `saved · scan` / `saved · copied` / `auto · mise env` / `auto · .env`).
+  - `saved`: you configured it (`dbhub_configure` or added in the page).
   - `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 **tested** (connectivity probe, see below), **edited** (override the connection string; an auto item becomes saved) or **deleted** (saved items only).
+- Each row can be **tested** (connectivity probe, see below), **edited** (change the connection string **and/or the environment name**; a rename keeps the connection and its credentials untouched — enter only a name to rename) or **deleted** (saved items only).
 - **Connection test**: clicking "Test" makes the Host probe the row's real DSN through a throwaway connection (a one-off dbhub process running `SELECT 1`) and shows success/failure inline. The report is one-shot feedback: never persisted, fades after ~10 s; a failure never marks, restricts or alters the connection, other environments or queries (slow/unreachable databases wait at most ~30 s).
-- **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>`.
+- **Multiple environments per workspace**: fill "workspace (path or title, empty = default current workspace) + environment name + connection string" in the form and click "Add Connection". Environment names **may be Chinese** (e.g. `线上` / `测试`): the name is shown verbatim while the environment segment of the source value becomes `env-<short hash>`, so two Chinese names can never collide (purely ASCII names such as `test` / `dev` keep their existing source values).
 
 ## dbhub Environment Variables
 
@@ -126,10 +126,10 @@ Precedence: **user settings > process environment variables (default seeds) > bu
 ## 🔄 Automatic Installation & Updates
 
 - **Auto-install on first use** — when `dbhub` is missing locally, the plugin installs it on the first execution; 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.
+- **Kept up to date automatically** — silently updates to the latest version in the background (interval under "Configure Page → 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.
+> The default update interval can also be seeded by an environment variable, see "Configure Page → Configuration"; once saved in the settings card, the saved value wins.
 
 ## Data Location
 
@@ -152,13 +152,13 @@ dsh plugin --profile web remove dsh-dbhub-live
 | Symptom | Fix |
 | --- | --- |
 | "Cannot locate dbhub" on first use | Make sure npm is present and online; offline, install `dbhub` manually and add it to PATH. |
-| A query to one environment fails with connection refused / auth error | Environments use independent one-shot connections: an unreachable environment only fails that call — other environments and calls keep working. The error carries guidance — for wrong credentials/details, ask the AI to run `dbhub_configure` and enter the password in the UI, or edit it directly in Settings → Plugins → Workspace connections. |
-| 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. |
+| A query to one environment fails with connection refused / auth error | Environments use independent one-shot connections: an unreachable environment only fails that call — other environments and calls keep working. The error carries guidance — for wrong credentials/details, ask the AI to run `dbhub_configure` and enter the password in the UI, or edit it directly in Plugins → dsh-dbhub-live → Configure. |
+| Tools say "plugin disabled" | Open Plugins → dsh-dbhub-live → Configure and click "Enable". |
+| Configure Page 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`. |
-| Can't update the password in chat (the model asks you for it) | That is by design — the model must not handle passwords. Ask the AI to run `dbhub_configure` and fill in the password in the UI prompt, or edit it yourself in Settings → Plugins → Workspace connections. |
+| Don't want automatic dbhub updates | Set "Auto-update interval (days)" to `0` in the Configure Page and save; or set `DSH_DBHUB_UPDATE_DAYS=0`. |
+| Can't update the password in chat (the model asks you for it) | That is by design — the model must not handle passwords. Ask the AI to run `dbhub_configure` and fill in the password in the UI prompt, or edit it yourself in Plugins → dsh-dbhub-live → Configure. |
 
 ## License
 

package/README.md

@@ -2,7 +2,7 @@
 
 **简体中文** · [English](README.en.md)
 
-> 让 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/DeepSeek-Harness) 直接、安全地操作数据库：**凭据零知识**（密码永不经模型）+ **一次性进程执行**（无常驻服务、天然并发与多实例安全）+ 按工作区×环境的连接管理 + 浏览器状态卡片。
+> 让 [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)](#安装)
@@ -18,9 +18,9 @@
 - **一次性进程执行** — 没有常驻 dbhub 服务：每次调用 spawn 一条独立进程执行完即回收。单条查询挂掉只影响它自己；多任务并行、多个 DSH 实例同时跑互不干扰（无共享端口、无互杀）。
 - **工具声明恒定 4 个** — `dbhub_configure` / `dbhub_list_sources` / `dbhub_execute_sql` / `dbhub_search_objects`，环境再多也不膨胀模型上下文。
 - **按工作区 × 环境管理连接** — 一个工作区可配多个环境（default / prod / dev / test…），通过 `source` 值区分，互不混淆。
-- **鉴权失败闭环** — 凭据或连接信息不对时，工具给出明确指引；模型引导你在界面更新密码（不会向模型索要密码），或你直接在设置卡片修改。
+- **鉴权失败闭环** — 凭据或连接信息不对时，工具给出明确指引；模型引导你在界面更新密码（不会向模型索要密码），或你直接在设置卡片修改。**配置时自动试连**：说的是非敏感连接信息会先在宿主侧实测——可连通就直接生效（免密码库零输入），只差密码时弹窗只问「账号（未知时）+ 密码」，不再让你重选输入方式；若试连明确报“空账号被拒”，账号为必填（不再提供「留空（使用空账号）」选项），避免把同一个必失败的配置再存回去。
 - **启用 / 禁用开关** — 关闭后所有 dbhub 工具立即返回「插件已禁用」友好提示，无需重启。
-- **浏览器状态卡片** — 设置 → 插件 → dsh-dbhub-live 实时展示：状态徽章、工作模式（一次性连接）、已注册工具数、环境数、最近错误，并提供启用/禁用开关、连接增删改查与连接测试。
+- **浏览器配置页** — 三个入口同一个页面：**设置 → DBHub 数据库工具**（一级设置页，推荐）、**左侧栏「DBHub 数据库工具」快捷入口**（可在设置页用开关关闭）、插件页 dsh-dbhub-live 那行的「配置」。实时展示：状态徽章、工作模式（一次性连接）、已注册工具数、环境数、最近错误，并提供启用/禁用开关、连接增删改查、**环境改名**与连接测试。
 - **开箱即用** — 未安装 `dbhub` 时首次执行自动安装，之后按设置间隔自动更新。
 
 ## 支持的数据源
@@ -42,10 +42,10 @@ dsh plugin --profile web add dsh-dbhub-live
 npx @deepseek-ai/dsh plugin --profile web add dsh-dbhub-live
 
 # 更新到指定版本（推荐写明当前发布的版本号，避免 pnpm 判「Already up to date」跳过）
-dsh plugin --profile web update dsh-dbhub-live@4.0.0
+dsh plugin --profile web update dsh-dbhub-live@4.1.0
 ```
 
-安装后**重启 `dsh web`** 生效（重启后到 设置 → 插件 → dsh-dbhub-live 可看到状态卡片）。
+安装后**重启 `dsh web`** 生效（重启后到 **设置 → DBHub 数据库工具** 可看到配置页）。
 
 ## 快速开始
 
@@ -66,9 +66,9 @@ dbhub_list_sources
 
 | 工具 | 说明 |
 | --- | --- |
-| `dbhub_configure(workspace?, env?, type?, host?, port?, database?, user?)` | 为工作区配置/持久化数据库连接。**不接受 dsn 参数**——密码/连接串一律在界面输入（不经过模型）；type/host/port/database/user 可作为非敏感预填。 |
-| `dbhub_list_sources()` | 列出全部连接源（工作区 × 环境）：仅元数据（类型/主机/端口/库）+ 来源徽章 + 对应 **source 值**。 |
-| `dbhub_execute_sql(source, sql)` | 在指定数据源上执行 SQL；`source` 见 `dbhub_list_sources`（默认环境不带后缀，命名环境如 `…_test`）。每次调用为独立一次性连接，多语句用 `;` 分隔。 |
+| `dbhub_configure(workspace?, env?, renameFrom?, copyFrom?, type?, host?, port?, database?, user?)` | 为工作区配置/持久化数据库连接。**不接受 dsn 参数**——密码/连接串一律在界面输入（不经过模型）；type/host/port/database/user 可作为非敏感预填。**预填够用时插件会先自动试连**：可连通 → 直接保存并返回 source 值；提示要密码 → 弹出最小「账号（未知时）+ 密码」输入框；信息不全或其它失败 → 才弹出完整方式选择。**改名**：`env=新名` + `renameFrom=旧名`（连接与凭据原样保留，可用于 `default` → `prod` 或中英文互改；目标已存在时先请用户确认）。**跨工作区复制**：`copyFrom=其他工作区的 source 值` + `env=本工作区环境名`，插件在宿主侧复制连接，密码不经模型。 |
+| `dbhub_list_sources()` | 列出全部连接源，**按工作区分组**并标出【当前工作区】：仅元数据（类型/主机/端口/库）+ 来源徽章 + 对应 **source 值**。 |
+| `dbhub_execute_sql(source, sql)` | 在指定数据源上执行 SQL；`source` 见 `dbhub_list_sources`。**每个 source 只属于一个工作区**，优先用当前工作区的；要复用其他工作区的连接，先用 `dbhub_configure` 的 `copyFrom` 复制到当前工作区，不要直接拿别的工作区的 source 查询。每次调用为独立一次性连接，多语句用 `;` 分隔。 |
 | `dbhub_search_objects(source, object_type, ...)` | 在指定数据源搜索数据库对象（表/视图/列/索引等）。 |
 
 > **安全**：模型无法通过本插件拿到任何密码——结果与列表只标注 `mysql://host:3306/db` 这类元数据；dbhub 的报错文本在返回前也会被清洗。查询失败时按提示到界面更新密码即可。
@@ -77,44 +77,44 @@ dbhub_list_sources
 
 ### 配置方式
 
+0. **自动试连（默认优先）** — 你在对话里说出连接信息（如「mysql 10.0.0.1:3307/mydb」）后，插件先用这些非敏感信息实测：能连上就直接保存（数据库不需要密码时全程零输入）；提示需要密码 → 弹窗只问「账号（未知时）+ 密码」，其余信息自动沿用，并附失败原因与该连接信息不对时的「改用其他方式」入口；若试连明确报“空账号被拒”（如 `Access denied for user ''`），账号为必填（不提供「留空」选项）；信息不完整或其它原因失败，才进入下面三种方式。若你说的是另一个库/主机/端口（与已存连接不同），插件会按新信息重新试连判断。
 1. **显式 DSN** — 在界面输入完整连接串，如 `mysql://user:pass@host:3306/db`。
-2. **填写分项** — 在界面按类型 / 主机 / 端口 / 账号 / 密码 / 库名依次填写。
+2. **填写分项** — 在界面按类型 / 主机 / 端口 / 账号 / 密码 / 库名依次填写；已从对话中得知的字段会自动带入，只补缺项即可。
 3. **授权扫描** — 授权后扫描项目配置文件（`.env`、`application*.yml`、`docker-compose`、`jdbc.properties` 等），列出候选（只显示主机/端口/库，密码不显示，由插件直接读取）供你确认。
 
 工作区若已有 `mise env` 或 `.env`（`DSN` / `DB_*`），插件会自动发现，无需手动配置。
 
-## 状态卡片
+## 配置页
 
-设置 → 插件 → dsh-dbhub-live：插件会把状态与配置实时同步到 Web 设置面板（仅 `dsh web` 端可见）。卡片为**整行折叠**样式（与其它插件设置卡一致）：
+三个入口，同一个页面、同一份状态：
 
-> 卡片全部文案（名称、状态、配置项、按钮、连接行）跟随 dsh 界面语言（中 / 英，设置 → 通用 → 语言）切换；模型的报错/反馈与宿主日志同样跟随。
+1. **设置 → DBHub 数据库工具**（推荐）：插件在设置面板注册的一级页面，任何部署都有。
+2. **左侧栏「DBHub 数据库工具」**：快捷入口，默认开启；不想占用左侧栏时，在设置页把「在侧边栏显示入口」关掉即可（即时生效，无需重启/刷新）。
+3. **插件 → dsh-dbhub-live → 配置**：dsh 0.1.6 起官方「插件」页给每个插件行提供的配置控件（该页由官方插件管理器提供，缺失时用前两个入口）。
 
-**折叠态（默认）**：一行显示 状态徽章（🟢 运行中 / ⚪ 已禁用）、环境数量、**启用/禁用开关**。
+> 关闭侧边栏入口**不会**让你失去配置页：设置页与插件页那行的「配置」始终可用。
 
-**展开后**分三块——
+配置页全部文案（名称、状态、配置项、按钮、连接行）跟随 dsh 界面语言（中 / 英，设置 → 通用 → 语言）切换；模型的报错/反馈与宿主日志同样跟随。
 
-**状态**：
-
-- 工作模式：一次性连接（每次调用独立进程）。
-- 工具声明：`4 个（固定）`；环境：`N 个 · 已保存 M`。
-- 最近错误（异常时红色展示）。
+**状态**：状态徽章（🟢 运行中 / ⚪ 已禁用）、**启用/禁用开关**、工作模式（一次性连接）、工具声明（`4 个（固定）`）、环境数（`N 个 · 已保存 M`）、最近错误（异常时红色展示）。
 
 **配置**（编辑后点「保存配置」即时生效并持久化）：
 
 | 参数 | 说明 | 默认 |
 | --- | --- | --- |
 | 自动更新间隔(天) | 自动更新 dbhub 的间隔天数，`0` 关闭 | `7` |
+| 在侧边栏显示入口 | 是否在左侧栏显示「DBHub 数据库工具」快捷入口；改动即时生效 | 开 |
 
 优先级：**用户设置 > 进程环境变量（默认值种子）> 内置默认**。自动安装包不在 UI 中（`DSH_DBHUB_PACKAGE` 环境变量单独控制，默认 `@bytebase/dbhub`）。
 
 **工作区连接**：
 
-- 列出每个工作区 × 环境的连接：工作区名、环境名、**source 值**（模型调用 `dbhub_execute_sql` 时填这个，等宽字体显示）、**连接元数据**（🔒 `mysql://host:3306/db`——不含账号密码，密码永不出现在卡片上）、来源徽章（`已保存` / `自动`）与来源明细（`已保存·用户` / `已保存·扫描` / `自动·mise env` / `自动·.env`）。
-  - `已保存`：你配置过（`dbhub_configure` 或卡片添加）。
+- 列出每个工作区 × 环境的连接：工作区名、环境名、**source 值**（模型调用 `dbhub_execute_sql` 时填这个，等宽字体显示）、**连接元数据**（🔒 `mysql://host:3306/db`——不含账号密码，密码永不出现在页面上）、来源徽章（`已保存` / `自动`）与来源明细（`已保存·用户` / `已保存·扫描` / `已保存·复制` / `自动·mise env` / `自动·.env`）。
+  - `已保存`：你配置过（`dbhub_configure` 或配置页添加）。
   - `自动`：未保存，来自 `mise env` / `.env` 自动发现——不持久化，随源文件变化；自动发现不对时可直接「修改」为手动配置覆盖。
-- 每行可「测试」（连接探活，见下）、「修改」（覆盖连接串，自动项会转成已保存项）或「删除」（仅已保存项）。
+- 每行可「测试」（连接探活，见下）、「修改」（改连接串 **或改环境名**；改名连接与凭据原样保留，只填名字不填连接串即为纯改名）或「删除」（仅已保存项）。
 - **连接测试**：点「测试」后 Host 用该环境的真实 DSN 走一次性临时连接（独立 dbhub 进程执行 `SELECT 1`）实测可达性，成功 / 失败即时在行内提示。结果是一次性反馈：不持久化、约 10 秒后自动消失；失败不会标记、限制或改动这条连接，不影响其他环境与查询（慢库 / 不通库最长等待约 30 秒）。
-- **同一工作区可添加多个环境**：表单填「工作区（路径或标题，留空=默认当前工作区）+ 环境名 + 连接串」点「添加连接」。默认环境 source 不带后缀，命名环境如 `<工作区>_<环境>`。
+- **同一工作区可添加多个环境**：表单填「工作区（路径或标题，留空=默认当前工作区）+ 环境名 + 连接串」点「添加连接」。环境名**支持中文**（如 `线上` / `测试`）：显示用原名，source 值中的环境段用 `env-<短哈希>` 保证**不同中文名不会撞车**（纯 ASCII 名如 `test` / `dev` 的 source 值保持不变）。
 
 ## dbhub 环境变量
 
@@ -126,10 +126,10 @@ dbhub_list_sources
 ## 🔄 dbhub 自动安装与更新
 
 - **首次使用自动安装**：本机没有 `dbhub` 时，插件会在第一次执行时自动安装，之后离线也可用。
-- **自动保持更新**：后台静默更新到最新版（间隔见「状态卡片 → 可配置参数」），失败则沿用现有版本。
+- **自动保持更新**：后台静默更新到最新版（间隔见「配置页 → 可配置参数」），失败则沿用现有版本。
 - **不碰你的配置**：通过 PATH / mise 自行安装的 `dbhub` 不会被插件改动。
 
-> 更新间隔默认值也可用环境变量播种，见「状态卡片 → 配置」；一旦在设置卡片保存过，即以设置值为准。
+> 更新间隔默认值也可用环境变量播种，见「配置页 → 配置」；一旦在设置卡片保存过，即以设置值为准。
 
 ## 数据位置
 
@@ -152,13 +152,13 @@ dsh plugin --profile web remove dsh-dbhub-live
 | 现象 | 处理 |
 | --- | --- |
 | 首次使用报「无法获取 dbhub」 | 确认本机有 npm 且能联网；离线可手动安装 `dbhub` 并加入 PATH。 |
-| 某个环境的查询报连接被拒 / 认证失败 | 该环境为独立一次性连接：不可达只让该次调用报错，其他环境与调用不受影响。错误末尾会附指引——凭据或连接信息有误时，可让 AI 调用 `dbhub_configure` 引导你在界面更新，或直接在 设置 → 插件 → 工作区连接 中修改。 |
-| 工具显示「插件已禁用」 | 打开 设置 → 插件 → dsh-dbhub-live 卡片，点击「启用」。 |
-| 看不到状态卡片 | 确认插件已安装并重启 `dsh web`；状态卡片只在 Web 设置面板（`dsh web`）显示，在无设置面板的终端环境下不影响工具使用。 |
+| 某个环境的查询报连接被拒 / 认证失败 | 该环境为独立一次性连接：不可达只让该次调用报错，其他环境与调用不受影响。错误末尾会附指引——凭据或连接信息有误时，可让 AI 调用 `dbhub_configure` 引导你在界面更新，或直接在 插件 → dsh-dbhub-live → 配置 中修改。 |
+| 工具显示「插件已禁用」 | 打开 插件 → 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`。 |
-| 密码无法在对话中更新（模型问你要密码） | 这是设计如此：模型不应接触密码。让 AI 调用 `dbhub_configure`，在界面弹出的输入框中填密码即可；或自行到 设置 → 插件 → 工作区连接 修改。 |
+| 不希望自动更新 dbhub | 配置页「自动更新间隔(天)」填 `0` 并保存；或设置环境变量 `DSH_DBHUB_UPDATE_DAYS=0`。 |
+| 密码无法在对话中更新（模型问你要密码） | 这是设计如此：模型不应接触密码。让 AI 调用 `dbhub_configure`，在界面弹出的输入框中填密码即可；或自行到 插件 → dsh-dbhub-live → 配置 修改。 |
 
 ## 许可证
 

package/doc/REQUIREMENTS.md

@@ -1,7 +1,8 @@
 # dsh-dbhub-live 需求事实记录
 
 > 本文只记录「产品必须满足什么」的**需求事实**（概念层面），不含实现细节；开发实现说明见 `AGENTS.md`，用户安装使用见 `README.md`。
-> 版本基线：4.0（正式版；架构性变更：零知识凭据 + 一次性进程执行，不再有常驻服务）。
+> 版本基线：4.1（正式版；4.0 的零知识凭据 + 一次性进程执行架构之上，新增工作区隔离与来源解析、环境改名、设置入口与侧边栏开关）。
+> 当前迭代：无（4.1 已发布；下一轮在此基线上挂 `-dev.N` 迭代）。
 
 ## 一、产品定位
 
@@ -40,7 +41,7 @@
 
 ## 六、设置与状态界面
 
-- R21. 浏览器设置面板提供状态卡片：展示启用状态、工作模式、工具声明数、环境数、最近错误，并支持启用/禁用开关。
+- R21. 浏览器端提供配置页：展示启用状态、工作模式、工具声明数、环境数、最近错误，并支持启用/禁用开关、连接的增删改查、环境改名与连接测试。在 dsh 0.1.6 及以后，该配置页承载于官方「插件」页的插件行上（`plugins.row.config`），不再是设置面板里的独立卡片。
 - R22. 面板文案与模型侧反馈跟随 DSH 界面语言（中/英）。
 
 ## 七、存储与实例隔离
@@ -49,11 +50,37 @@
 - R24. 配置持久化失败不应导致崩溃，可降级继续运行。
 - R25. 升级或手工修改遗留的旧格式配置应被自动清洗/迁移，未知字段予以保留。
 
-## 八、连接配置交互原则
+## 八、连接配置交互原则（零打扰优先）
 
-- R26. 对**已配置且校验可用的连接**，配置工具必须首先自动校验；校验通过时直接给出「已配置可连通」的确认与使用指引，**不得要求用户重新输入任何信息**。
-- R27. 仅在环境**未配置**或**校验失败**时才向用户提问；提问不得索要重复信息——完整连接串已含密码时，不得再次索取密码。
-- R28. 校验失败时应提供「使用现有连接（不重新输入、不修改配置）」的确认选项。
-- R29. 「仅填密码」的简化路径只在其余连接信息（类型/主机/库名/账号）已具备时提供；否则须引导完整连接串或分项填写，避免产生不可用的半截配置。
-- R30. 连接保存或采纳后，系统应立即在宿主侧自检连通性，并把结果（可连通 / 失败原因）一并返回，避免用户通过后续尝试才得知失败。
-- R31. 连接信息输入界面只提供一个取消入口（由界面自身提供），不得出现重复取消项。
+> 本节由 4.0.x 交互优化迭代（探连优先 + 凭据最小询问）沉淀，覆盖用户侧三轮反馈：①可用直接可用、缺什么问什么；②已存连接凭据缺失时应诊断并只补缺失项；③连接信息本身不对或重新描述了目标时应能脱身并按新信息重走判断。
+
+- R26. 对**已配置且校验可用的连接**，配置过程必须自动校验；通过时直接确认「已配置可连通」并提供使用指引，**不要求用户重新输入任何信息**。
+- R27. 仅当环境未配置、校验失败或自动试连未成功时才向用户提问；**提问不得索要已知或重复信息**——完整连接串已含密码时，不得再次索取密码。
+- R28. 未配置环境下，若已从对话中得知足够的连接事实（类型/主机/库名；SQLite 除外），应**先自动试连**、按结果分流，而不是直接提问：
+  - 试连成功 → 按已有信息完成配置并返回可用来源标识，**全程零输入**（免密码连接、信息即用即存）；
+  - 试连提示缺凭据 → **只询问缺失项**（账号未知时连账号一起问），其余信息自动沿用，补完即生效；
+  - 信息不完整或试连因其它原因失败 → 才提供完整录入方式（输入连接串 / 分项填写 / 授权扫描）。
+- R29. 凭据询问必须**说明为什么需要**（试连失败原因），并允许用户表明「连接信息本身不对」从而改走完整录入，避免用户被困在反复补凭据的循环中。**若试连诊断明确指向“空账号被拒”（如 `Access denied for user ''@…`），账号为必填**：凭据询问不得提供「留空（使用空账号）」选择，用户仍提交空账号时应拒绝保存并说明原因，避免把同一个必失败的 DSN 再存回去。
+- R30. 用户重新描述的目标（库/主机/端口等）与已存连接不同时，必须**按新描述重新执行判断流程**，不得沿用旧连接的结果。
+- R31. 「使用现有连接」是**字面沿用**：不修改、不补填任何缺失字段（如账号/密码）；其文案必须让用户明确这一点，不得暗示会修复缺失项。
+- R32. 录入表单与凭据询问都应**预先带入已从对话中得知的字段**，用户只需补充缺失项，避免重复录入。
+- R33. 连接保存或被采纳后，应**立即自检连通性**并把结果（可连通 / 失败原因）随回执一并返回，避免用户通过后续尝试才得知失败。
+- R34. 连接信息输入界面只提供一个取消入口（由界面自身提供），不得出现重复取消项。
+
+## 九、工作区隔离与来源解析
+
+> 本节由 4.1 迭代沉淀：多工作区各自配置了相似（甚至同名）连接时，模型必须能分辨「这是哪个工作区的哪个环境」，不允许把不同工作区的连接当成同一个使用。
+
+- R35. 每条连接只属于一个工作区；不同工作区的连接是彼此独立的目标，即使连接信息看起来相同也不得视为同一条（不共享、不互相覆盖、不互相替代）。
+- R36. 模型侧应优先使用**当前会话工作区**的连接；连接清单必须按工作区分组并显式标出当前工作区。
+- R37. 当模型给出的来源标识可能命中多个工作区（同名工作区、同名环境或仅给标题）时，系统必须返回候选清单要求明确指定，**不得按列表顺序或长度猜测**。
+- R38. 需要复用其他工作区已配置的连接时，必须先取得用户确认，再由插件在宿主侧把连接**复制**到当前工作区（新建一条属于当前工作区的连接）；凭据与连接串不得因此进入模型上下文，也不得直接用其他工作区的来源标识执行查询。
+- R39. 环境名支持非 ASCII（如中文「线上」「测试」）：显示与存储保留原名，而用于来源标识的环境段必须**唯一且稳定**——不同中文环境名不得解析到同一个来源；纯 ASCII 名的既有来源标识保持不变。
+- R40. 环境可改名（模型可调、界面可改）：改名只更换名字，连接与凭据原样保留、无需重新输入；目标名已存在时必须先经用户确认（该操作会覆盖目标环境的连接）。
+- R41. 配置目标必须明确：显式给出的工作区不存在时应报错并列出可用工作区，不得静默改用其他工作区；未给出工作区时以当前会话工作区为准，无法确定时应要求明确指定。
+
+## 十、配置页与桌面端承载（dsh 版本适配）
+
+- R42. 配置页必须可通过**设置**进入：插件在设置面板注册一级页面（设置 → DBHub 数据库工具），该承载位属核心界面、任何部署都存在，用户也在此寻找连接管理；同时在官方「插件」页按当前 dsh 版本提供的单插件配置槽位（0.1.6 起为 `<包名>#<行 id>` 的配置页）再挂一份。三处进入的是同一个页面与同一份状态。
+- R43. 插件另提供**侧边栏快捷入口**，且该入口的显示与否由设置页上的开关（`在侧边栏显示入口`，默认开）控制，改动即时生效、无需重启或刷新。
+- R44. 官方槽位变化或缺失（如 dsh 升级移除旧槽位）不得导致配置页不可达；关闭侧边栏入口**不得**造成自锁——设置页与插件页入口必须始终可用。