dsh-db-tool 0.1.2 → 0.1.4

package/README.md

@@ -46,6 +46,23 @@ GaussDB 官方驱动未发布 npm，需先构建 vendor：`npm run build:gaussdb
 - `run_script`：node:vm 独立 context、60s 超时、无 require/process/网络/文件系统，仅注入受限 `db.{query,execute}` 句柄
 - 已知边界：对话内确认为提示级强制 + 审计兜底；DSH 无硬中断通道前，恶意对话仍可能诱导用户确认，请配合最小权限数据库账号使用
 
+## Troubleshooting
+
+### npm 安装插件导入失败（punycode / resolve.paths）
+
+症状：DSH 启动后插件加载报 `failed to import`，伴随 `TypeError: Cannot read properties of null (reading 'Symbol(Symbol.iterator)')`，栈指向 `dsh-app-boot` 的 `routeScoped`。
+
+根因：上游 `@deepseek-ai/dsh-app-boot` 对 `createRequire(parent).resolve.paths(name)` 直接做 `for..of`，而 Node 对 core-module 同名包（`punycode` 等）返回 `null`，hoisted profile 下凡依赖树含此类 npm 包的插件都会炸。
+
+一键修复（幂等，应用前自动备份为 `index.js.bak-hotfix`；`--revert` 可还原）：
+
+```bash
+npm run patch:dsh        # Windows（PowerShell）
+npm run patch:dsh:sh     # macOS / Linux
+```
+
+脚本自动探测 DSH 安装根（`--dsh-root` 可显式指定）；补丁文件见 `patches/dsh-app-boot-route-scoped-hotfix.patch`，仅对 `0.1.7-rc.2` 声明兼容，其他版本会警告（`--force` 覆盖）。上游 issue：<https://github.com/mengqi1436/dsh-db-tool/issues>（占位，待上游仓库开放后替换）。
+
 ## 测试
 
 ```bash
@@ -62,7 +79,7 @@ npx stryker run # 变异测试（范围 lib/guard + lib/manager + lib/store，
 lib/        host 插件（store / adapters×8 / guard / manager / http / index）
 client/     侧边栏单文件产物（client.js，即源码）
 skills/     db-admin skill
-scripts/    GaussDB vendor 构建（sh / ps1）
+scripts/    GaussDB vendor 构建、DSH dsh-app-boot 热修复（patch:dsh）
 docs/       安装、HTTP 契约（api-contract.md）、skill 说明
 tests/      vitest（离线 mock + DBT_TEST_* 门控真机）
 vendor/     gaussdb-pg 构建产物（gitignore，不入库）

package/client/client.js

@@ -66,6 +66,7 @@ window.__ModuleLoader__.load({
 			modeRw: "读写",
 			// 浏览
 			noDatabases: "无可用数据库",
+			noSchemas: "无模式",
 			noTables: "无表",
 			loadFailed: "加载失败",
 			structure: "结构",
@@ -150,6 +151,7 @@ window.__ModuleLoader__.load({
 			modeRo: "read-only ro",
 			modeRw: "read-write rw",
 			noDatabases: "No databases available",
+			noSchemas: "No schemas",
 			noTables: "No tables",
 			loadFailed: "Failed to load",
 			structure: "Structure",
@@ -621,7 +623,7 @@ window.__ModuleLoader__.load({
 										{ className: "dbt-muted", style: { fontFamily: MONO_FONT, fontSize: 11, wordBreak: "break-all" } },
 										c.safeUrl || (c.host + ":" + (c.port || "")),
 									) : null,
-									testInfo[c.id] ? React.createElement("div", { className: "dbt-muted" }, testInfo[c.id]) : null,
+									testInfo[c.id] ? React.createElement("div", { style: { fontSize: 12, color: testInfo[c.id].startsWith("✓") ? "var(--dbt-success, #30d158)" : "var(--dbt-danger, #ff453a)" } }, testInfo[c.id]) : null,
 								),
 								// 右列：动作按钮（次要语义，danger 仅删除）
 								React.createElement(
@@ -708,7 +710,8 @@ window.__ModuleLoader__.load({
 			const [loading, setLoading] = React.useState({});
 			const [error, setError] = React.useState({}); // 树节点加载失败信息（就地显示，可点重试）
 			const [dbs, setDbs] = React.useState({}); // connId -> string[]
-			const [tablesMap, setTablesMap] = React.useState({}); // "<connId>/<db>" -> TableInfo[]
+			const [schemasMap, setSchemasMap] = React.useState({}); // "<connId>/<db>" -> string[]（PG/GaussDB 库内 schema 层）
+			const [tablesMap, setTablesMap] = React.useState({}); // "<connId>/<db|schema>" -> TableInfo[]
 			const [sel, setSel] = React.useState(null); // {connId, db, table: TableInfo}
 			const [schema, setSchema] = React.useState([]);
 			const [preview, setPreview] = React.useState(null); // QueryResult
@@ -718,7 +721,7 @@ window.__ModuleLoader__.load({
 
 			// 会话项目切换 / 连接列表变化时清空树缓存，避免陈旧授权下的旧数据
 			React.useEffect(() => {
-				setOpen({}); setLoading({}); setError({}); setDbs({}); setTablesMap({}); setSel(null); setSchema([]); setPreview(null);
+				setOpen({}); setLoading({}); setError({}); setDbs({}); setSchemasMap({}); setTablesMap({}); setSel(null); setSchema([]); setPreview(null);
 			}, [projectPath]);
 
 			function toggle(key, load) {
@@ -744,11 +747,23 @@ window.__ModuleLoader__.load({
 						setDbs((m) => Object.assign({}, m, { [c.id]: list || [] }));
 					}));
 			}
+			// PG/GaussDB 官方层级为 数据库 → 模式(schema) → 表：库节点下先列 schema 再列表
+			const HAS_SCHEMAS = { postgresql: true, gaussdb: true };
 			function toggleDb(c, d) {
 				if (!projectPath) return;
+				const useSchemas = !!HAS_SCHEMAS[c.kind];
+				const what = useSchemas ? "schemas" : "tables";
 				toggle("d:" + c.id + "/" + d, () =>
-					api("tables" + qs({ project: projectPath, connId: c.id, database: d })).then((list) => {
-						setTablesMap((m) => Object.assign({}, m, { [c.id + "/" + d]: list || [] }));
+					api(what + qs({ project: projectPath, connId: c.id, database: d })).then((list) => {
+						const setter = useSchemas ? setSchemasMap : setTablesMap;
+						setter((m) => Object.assign({}, m, { [c.id + "/" + d]: list || [] }));
+					}));
+			}
+			function toggleSchema(c, d, s) {
+				if (!projectPath) return;
+				toggle("s:" + c.id + "/" + d + "/" + s, () =>
+					api("tables" + qs({ project: projectPath, connId: c.id, database: s })).then((list) => {
+						setTablesMap((m) => Object.assign({}, m, { [c.id + "/" + s]: list || [] }));
 					}));
 			}
 			// 请求序号守卫：快速切换选中表/翻页时，丢弃晚到的旧响应，防止旧数据覆盖新选中项
@@ -795,19 +810,43 @@ window.__ModuleLoader__.load({
 				if (!list) continue;
 				if (list.length === 0) { treeRows.push(treerow(ck + ":e", 1, false, true, t("noDatabases"))); continue; }
 				for (const d of list) {
+					const useSchemas = !!HAS_SCHEMAS[c.kind];
 					const dk = "d:" + c.id + "/" + d;
 					const dOpen = !!open[dk];
 					treeRows.push(treerow(dk, 1, dOpen, false, d, () => toggleDb(c, d)));
 					if (!dOpen) continue;
-					const tkey = c.id + "/" + d;
-					const tlist = tablesMap[tkey];
 					if (loading[dk]) { treeRows.push(treerow(dk + ":l", 2, false, true, "…")); continue; }
 					if (error[dk]) { treeRows.push(treerow(dk + ":x", 2, false, true, t("loadFailed") + "：" + error[dk], () => retry(dk, () => toggleDb(c, d)))); continue; }
+					// PG/GaussDB：库 → 模式 → 表（三层，Navicat 官方层级）；schema 节点复用 open/loading/error 状态
+					if (useSchemas) {
+						const slist = schemasMap[c.id + "/" + d];
+						if (!slist) continue;
+						if (slist.length === 0) { treeRows.push(treerow(dk + ":e", 2, false, true, t("noSchemas"))); continue; }
+						for (const s of slist) {
+							const sk = "s:" + c.id + "/" + d + "/" + s;
+							const sOpen = !!open[sk];
+							treeRows.push(treerow(sk, 2, sOpen, false, s, () => toggleSchema(c, d, s)));
+							if (!sOpen) continue;
+							const tlist = tablesMap[c.id + "/" + s];
+							if (loading[sk]) { treeRows.push(treerow(sk + ":l", 3, false, true, "…")); continue; }
+							if (error[sk]) { treeRows.push(treerow(sk + ":x", 3, false, true, t("loadFailed") + "：" + error[sk], () => retry(sk, () => toggleSchema(c, d, s)))); continue; }
+							if (!tlist) continue;
+							if (tlist.length === 0) { treeRows.push(treerow(sk + ":e", 3, false, true, t("noTables"))); continue; }
+							for (const tb of tlist) {
+								const active = !!sel && sel.connId === c.id && sel.db === s && sel.table.name === tb.name;
+								treeRows.push(treerow("t:" + sk + "/" + tb.name, 3, false, true,
+									tb.name + (tb.type && tb.type !== "table" ? " · " + tb.type : ""),
+									() => setSel({ connId: c.id, db: s, table: tb }), active));
+							}
+						}
+						continue;
+					}
+					const tlist = tablesMap[c.id + "/" + d];
 					if (!tlist) continue;
 					if (tlist.length === 0) { treeRows.push(treerow(dk + ":e", 2, false, true, t("noTables"))); continue; }
 					for (const tb of tlist) {
 						const active = !!sel && sel.connId === c.id && sel.db === d && sel.table.name === tb.name;
-						treeRows.push(treerow("t:" + tkey + "/" + tb.name, 2, false, true,
+						treeRows.push(treerow("t:" + c.id + "/" + d + "/" + tb.name, 2, false, true,
 							tb.name + (tb.type && tb.type !== "table" ? " · " + tb.type : ""),
 							() => setSel({ connId: c.id, db: d, table: tb }), active));
 					}

package/dist/adapters/sql-shared/pg-like.js

@@ -116,6 +116,14 @@ export async function createPgLikeAdapter(kind, Driver, conn, opts) {
             const res = await pool.query('SELECT datname FROM pg_database WHERE datistemplate = false AND datallowconn = true ORDER BY datname');
             return res.rows.map((r) => String(r.datname));
         }),
+        // 库内 schema 清单（Navicat 官方层级：数据库 → 模式 → 表）。
+        // PG 连接固定单库，database 参数无法跨库，忽略；pg_* 前缀覆盖 pg_catalog/pg_toast/pg_temp 系。
+        listSchemas: () => humanize(`${kind} 列出模式`, async () => {
+            const res = await pool.query(`SELECT nspname FROM pg_catalog.pg_namespace
+           WHERE nspname NOT LIKE 'pg\\_%' AND nspname <> 'information_schema'
+           ORDER BY nspname`);
+            return res.rows.map((r) => String(r.nspname));
+        }),
         listTables: (database) => humanize(`${kind} 列出表`, async () => {
             const schema = database ? assertIdent(database, 'schema') : defaultSchema();
             const res = await pool.query(`SELECT table_name, table_type FROM information_schema.tables

package/dist/http/index.js

@@ -210,6 +210,9 @@ async function route(req, res, service, path, q, opts) {
     if (path === '/api/tables' && req.method === 'GET') {
         return sendOk(res, await service.tables(projectOf(q), required(q, 'connId'), q.get('database') ?? undefined));
     }
+    if (path === '/api/schemas' && req.method === 'GET') {
+        return sendOk(res, await service.schemas(projectOf(q), required(q, 'connId'), q.get('database') ?? undefined));
+    }
     if (path === '/api/schema' && req.method === 'GET') {
         return sendOk(res, await service.schema(projectOf(q), required(q, 'connId'), required(q, 'table'), q.get('database') ?? undefined));
     }

package/dist/manager.js

@@ -146,6 +146,21 @@ export class DbToolService {
             throw this.toDriverError(e);
         }
     }
+    /** 库内 schema 清单（仅 PG/GaussDB 等三层语义适配器实现；ro 即可）。 */
+    async schemas(projectPath, connId, database) {
+        const { key, adapter } = await this.authorize(projectPath, connId, false);
+        if (!adapter.listSchemas)
+            return [];
+        try {
+            const result = await adapter.listSchemas(database);
+            this.audit(key, connId, 'schemas', database ?? 'default', 'none', false, true);
+            return result;
+        }
+        catch (e) {
+            this.audit(key, connId, 'schemas', database ?? 'default', 'none', false, false, this.errText(e));
+            throw this.toDriverError(e);
+        }
+    }
     async schema(projectPath, connId, table, database) {
         const t = assertNonEmpty(table, 'table');
         const { key, adapter } = await this.authorize(projectPath, connId, false);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-db-tool",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "DSH community plugin: chat-operated multi-database admin tool with sidebar management, project-scoped grants, ro/rw modes and dangerous-operation confirmation",
   "type": "module",
   "license": "MIT",
@@ -28,7 +28,9 @@
     "typecheck": "tsc --noEmit",
     "build": "tsc -p tsconfig.build.json && node -e \"const fs=require('fs'); fs.mkdirSync('dist/script',{recursive:true}); fs.copyFileSync('lib/script/worker.cjs','dist/script/worker.cjs'); console.log('build OK')\"",
     "build:gaussdb": "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/build-gaussdb.ps1",
-    "build:gaussdb:sh": "bash scripts/build-gaussdb.sh"
+    "build:gaussdb:sh": "bash scripts/build-gaussdb.sh",
+    "patch:dsh": "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/apply-dsh-hotfix.ps1",
+    "patch:dsh:sh": "bash scripts/apply-dsh-hotfix.sh"
   },
   "dsh": {
     "bundle": {
@@ -72,6 +74,7 @@
     "client",
     "skills",
     "docs",
+    "patches",
     "scripts",
     "README.md"
   ]

package/patches/dsh-app-boot-route-scoped-hotfix.patch

@@ -0,0 +1,26 @@
+# DSH ResolutionRouter routeScoped hotfix (upstream bug: createRequire(parent).resolve.paths(name)
+# returns null for core-module names like "punycode", breaking hoisted profile installs).
+# Target-Version: 0.1.7-rc.2
+# Apply manually:  git apply -p1 -d <dsh-app-boot package root> <this file>
+# Or one command:  npm run patch:dsh    (scripts/apply-dsh-hotfix.ps1)
+# Generated from @deepseek-ai/dsh-app-boot@0.1.7-rc.2 npm tarball vs patched local copy.
+diff --git a/lib/index.js b/lib/index.js
+index 8f6041d..89a138e 100644
+--- a/lib/index.js
++++ b/lib/index.js
+@@ -1419,7 +1419,14 @@ var ResolutionRouter = class {
+ 		const target = resolution.entries.get(name);
+ 		const candidates = [];
+ 		const localSearchPaths = [];
+-		for (const searchPath of createRequire(parent).resolve.paths(name)) {
++		/* local hotfix: resolve.paths returns null for core-module names (e.g. "punycode"),
++		   which made the for..of throw TypeError and broke every hoisted profile install
++		   whose dependency tree requires such an npm package. Fall back to the standard
++		   node_modules search chain so the local candidate can still be found. */
++		const _hotReq = createRequire(parent);
++		const _hotPaths = _hotReq.resolve.paths(name)
++			?? _hotReq("node:module")._nodeModulePaths(_hotReq("node:path").dirname(parent));
++		for (const searchPath of _hotPaths) {
+ 			if (!searchPath.startsWith(layer.localPrefix)) break;
+ 			localSearchPaths.push(searchPath);
+ 			const candidate = localPackageCandidate(searchPath, name, flavor);

package/scripts/apply-dsh-hotfix.ps1

@@ -0,0 +1,34 @@
+# Apply or revert the DSH ResolutionRouter hotfix (dsh-app-boot routeScoped resolve.paths fix).
+# Thin wrapper: all logic lives in scripts/hotfix-core.mjs (cross-platform, testable).
+# Usage: powershell -NoProfile -ExecutionPolicy Bypass -File scripts/apply-dsh-hotfix.ps1
+#            [-DshRoot <dir>] [-PatchFile <file>] [-Force] [-Revert] [-DryRun]
+param(
+	[string]$DshRoot,
+	[string]$PatchFile,
+	[switch]$Force,
+	[switch]$Revert,
+	[switch]$DryRun
+)
+
+$ErrorActionPreference = 'Stop'
+$core = Join-Path $PSScriptRoot 'hotfix-core.mjs'
+if (-not (Test-Path $core)) {
+	Write-Error "hotfix-core.mjs not found next to this script ($PSScriptRoot)."
+	exit 1
+}
+
+$node = Get-Command node -ErrorAction SilentlyContinue
+if (-not $node) {
+	Write-Error 'node is required but was not found on PATH.'
+	exit 1
+}
+
+$argv = @($core)
+if ($DshRoot) { $argv += @('--dsh-root', $DshRoot) }
+if ($PatchFile) { $argv += @('--patch-file', $PatchFile) }
+if ($Force) { $argv += '--force' }
+if ($Revert) { $argv += '--revert' }
+if ($DryRun) { $argv += '--dry-run' }
+
+& $node.Source @argv
+exit $LASTEXITCODE

package/scripts/apply-dsh-hotfix.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Apply or revert the DSH ResolutionRouter hotfix (dsh-app-boot routeScoped resolve.paths fix).
+# Thin wrapper: all logic lives in scripts/hotfix-core.mjs (cross-platform, testable).
+# Usage: bash scripts/apply-dsh-hotfix.sh [--dsh-root <dir>] [--patch-file <file>] [--force] [--revert] [--dry-run]
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CORE="$SCRIPT_DIR/hotfix-core.mjs"
+
+if [[ ! -f "$CORE" ]]; then
+	echo "hotfix-core.mjs not found next to this script ($SCRIPT_DIR)." >&2
+	exit 1
+fi
+
+if ! command -v node >/dev/null 2>&1; then
+	echo "node is required but was not found on PATH." >&2
+	exit 1
+fi
+
+exec node "$CORE" "$@"

package/scripts/hotfix-core.d.mts

@@ -0,0 +1,26 @@
+/**
+ * 类型声明：scripts/hotfix-core.mjs（无 allowJs，为 tests/scripts/hotfix.spec.ts 提供 import 类型）。
+ */
+export declare const TARGET_VERSION: string;
+export declare const HOTFIX_MARKER: string;
+export declare const BOOT_INDEX_REL: string;
+export declare const BACKUP_SUFFIX: string;
+export declare const ORIGINAL_LINE: string;
+
+export declare function isApplied(content: string): boolean;
+export declare function applyToContent(content: string): {
+	ok: boolean;
+	reason?: string;
+	content: string;
+};
+export declare function revertContent(content: string): {
+	ok: boolean;
+	reason?: string;
+	content: string;
+};
+export declare function parsePatchTargetVersion(patchText: string): string | undefined;
+export declare function findBootIndex(root: string): string | undefined;
+export declare function resolveCandidateRoots(explicitRoot?: string): string[];
+export declare function resolveDshRoot(explicitRoot?: string): string | undefined;
+export declare function applyToIndexFile(indexFile: string, patchFile: string): string;
+export declare function run(argv?: string[]): number;

package/scripts/hotfix-core.mjs

@@ -0,0 +1,320 @@
+#!/usr/bin/env node
+/**
+ * DSH ResolutionRouter hotfix —— 核心逻辑（纯 Node、零依赖、可被测试 import）。
+ *
+ * 修复的 bug：@deepseek-ai/dsh-app-boot 的 routeScoped() 直接对
+ * `createRequire(parent).resolve.paths(name)` 做 for..of，而 Node 对 core-module
+ * 同名包（punycode 等）返回 null，导致 hoisted profile 下 npm 安装插件导入失败
+ * （TypeError: Cannot read properties of null）。
+ *
+ * 用法：node scripts/hotfix-core.mjs [--dsh-root <dir>] [--patch-file <file>]
+ *           [--force] [--revert] [--dry-run]
+ * 退出码：0 成功/已应用跳过；1 失败；2 版本不匹配且未给 --force。
+ */
+import { execFileSync, spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+/** 补丁文件里的目标版本声明行（patches/*.patch 注释头）。 */
+export const TARGET_VERSION = '0.1.7-rc.2';
+/** 判断目标文件是否已打补丁的标识串（hotfix 注释首行片段）。 */
+export const HOTFIX_MARKER = 'local hotfix: resolve.paths returns null';
+/** dsh-app-boot 内 lib/index.js 相对包根的路径。 */
+export const BOOT_INDEX_REL = path.join('lib', 'index.js');
+/** 应用前备份文件后缀。 */
+export const BACKUP_SUFFIX = '.bak-hotfix';
+
+/** 原始（未打补丁）单行 —— 必须与 dsh-app-boot@0.1.7-rc.2 lib/index.js 逐字节一致。 */
+export const ORIGINAL_LINE =
+	'\t\tfor (const searchPath of createRequire(parent).resolve.paths(name)) {';
+
+/** 热修复代码块 —— 与 patches/dsh-app-boot-route-scoped-hotfix.patch 的 + 行一致。 */
+const HOTFIX_BLOCK = [
+	'\t\t/* local hotfix: resolve.paths returns null for core-module names (e.g. "punycode"),',
+	'\t\t   which made the for..of throw TypeError and broke every hoisted profile install',
+	'\t\t   whose dependency tree requires such an npm package. Fall back to the standard',
+	'\t\t   node_modules search chain so the local candidate can still be found. */',
+	'\t\tconst _hotReq = createRequire(parent);',
+	'\t\tconst _hotPaths = _hotReq.resolve.paths(name)',
+	'\t\t\t?? _hotReq("node:module")._nodeModulePaths(_hotReq("node:path").dirname(parent));',
+	'\t\tfor (const searchPath of _hotPaths) {',
+].join('\n');
+
+/** 目标文件是否已包含热修复。 */
+export function isApplied(content) {
+	return content.includes(HOTFIX_MARKER);
+}
+
+/**
+ * 在文件内容上应用热修复（幂等：已应用时返回 already-applied）。
+ * @returns {{ ok: boolean, reason?: string, content: string }}
+ */
+export function applyToContent(content) {
+	if (isApplied(content)) return { ok: false, reason: 'already-applied', content };
+	if (!content.includes(ORIGINAL_LINE)) {
+		return { ok: false, reason: 'target-line-not-found', content };
+	}
+	return { ok: true, content: content.replace(ORIGINAL_LINE, HOTFIX_BLOCK) };
+}
+
+/**
+ * 还原热修复（优先用内建块反替换；调用方在磁盘层面应优先用 .bak-hotfix 备份）。
+ * @returns {{ ok: boolean, reason?: string, content: string }}
+ */
+export function revertContent(content) {
+	if (!isApplied(content)) return { ok: false, reason: 'not-applied', content };
+	if (!content.includes(HOTFIX_BLOCK)) {
+		return { ok: false, reason: 'hotfix-block-not-found', content };
+	}
+	return { ok: true, content: content.replace(HOTFIX_BLOCK, ORIGINAL_LINE) };
+}
+
+/** 从补丁文本解析注释头声明的目标版本（无则返回 undefined）。 */
+export function parsePatchTargetVersion(patchText) {
+	const m = /^\s*#\s*Target-Version:\s*(\S+)/m.exec(patchText);
+	return m?.[1];
+}
+
+/**
+ * 在候选 dsh 根下定位 dsh-app-boot/lib/index.js。
+ * 候选解释：root=DSH 安装根（@deepseek-ai/dsh 包目录）；也接受直接指向
+ * dsh-app-boot 包根或 node_modules/@deepseek-ai 层级。
+ * @returns {string | undefined} lib/index.js 绝对路径
+ */
+export function findBootIndex(root) {
+	const candidates = [
+		path.join(root, 'node_modules', '@deepseek-ai', 'dsh-app-boot', BOOT_INDEX_REL),
+		path.join(root, '@deepseek-ai', 'dsh-app-boot', BOOT_INDEX_REL),
+		path.join(root, BOOT_INDEX_REL),
+	];
+	for (const candidate of candidates) {
+		try {
+			if (!fs.statSync(candidate).isFile()) continue;
+			// 防误伤：确认包根 package.json 的 name 是 dsh-app-boot。
+			const pkg = JSON.parse(
+				fs.readFileSync(path.join(path.dirname(path.dirname(candidate)), 'package.json'), 'utf8'),
+			);
+			if (pkg.name === '@deepseek-ai/dsh-app-boot') return candidate;
+		} catch {
+			/* 候选不存在或不可读，试下一个 */
+		}
+	}
+	return undefined;
+}
+
+/**
+ * 自动探测 DSH 安装根候选列表（dsh 包目录）。
+ * 顺序：--dsh-root 参数 → DSH_HOME → which/where dsh 的 shim 反推 → 常见全局路径。
+ * 调用方应逐个用 findBootIndex 试探（DSH_HOME 存在但不含 dsh-app-boot 时继续回退）。
+ */
+export function resolveCandidateRoots(explicitRoot) {
+	const roots = [];
+	if (explicitRoot) {
+		if (fs.existsSync(explicitRoot)) roots.push(path.resolve(explicitRoot));
+		return roots;
+	}
+	const fromEnv = process.env.DSH_HOME;
+	if (fromEnv && fs.existsSync(fromEnv)) roots.push(path.resolve(fromEnv));
+
+	const shim = findDshOnPath();
+	if (shim) {
+		// <global>/dsh(.cmd) → <global>/node_modules/@deepseek-ai/dsh
+		const globalDir = path.dirname(path.dirname(shim));
+		const candidate = path.join(globalDir, 'node_modules', '@deepseek-ai', 'dsh');
+		if (fs.existsSync(candidate)) roots.push(candidate);
+	}
+
+	roots.push(...commonGlobalRoots());
+	return roots;
+}
+
+/** resolveCandidateRoots 的单值便捷形式（取第一个候选）。 */
+export function resolveDshRoot(explicitRoot) {
+	return resolveCandidateRoots(explicitRoot)[0];
+}
+
+function findDshOnPath() {
+	const isWin = process.platform === 'win32';
+	try {
+		const out = execFileSync(isWin ? 'where.exe' : 'which', ['dsh'], {
+			encoding: 'utf8',
+			stdio: ['ignore', 'pipe', 'ignore'],
+		});
+		const first = out.split(/\r?\n/).find((line) => line.trim() !== '');
+		return first ? first.trim() : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function commonGlobalRoots() {
+	const isWin = process.platform === 'win32';
+	const roots = [];
+	if (isWin) {
+		if (process.env.APPDATA) {
+			roots.push(path.join(process.env.APPDATA, 'npm', 'node_modules', '@deepseek-ai', 'dsh'));
+		}
+		// nvm-windows: <drive>:\Tool\nvm\v*\node_modules\@deepseek-ai\dsh 与 C:\nvm\v*\...
+		for (const base of ['E:\\Tool\\nvm', 'C:\\nvm', 'D:\\nvm']) {
+			try {
+				for (const entry of fs.readdirSync(base)) {
+					if (/^v/.test(entry)) {
+						roots.push(path.join(base, entry, 'node_modules', '@deepseek-ai', 'dsh'));
+					}
+				}
+			} catch {
+				/* base 不存在 */
+			}
+		}
+	} else {
+		for (const lib of ['/usr/local/lib', '/usr/lib', path.join(process.env.HOME ?? '', '.nvm')]) {
+			try {
+				if (lib.includes('.nvm')) {
+					const versions = path.join(lib, 'versions', 'node');
+					for (const v of fs.readdirSync(versions)) {
+						roots.push(
+							path.join(versions, v, 'lib', 'node_modules', '@deepseek-ai', 'dsh'),
+						);
+					}
+				} else {
+					roots.push(path.join(lib, 'node_modules', '@deepseek-ai', 'dsh'));
+				}
+			} catch {
+				/* 不可读 */
+			}
+		}
+	}
+	return roots;
+}
+
+/**
+ * 首选 git apply（若 git 可用且补丁可干净应用）；否则回退内建字符串替换。
+ * 两种路径结果一致（内建块与补丁 + 行逐字节相同，测试保证）。
+ */
+export function applyToIndexFile(indexFile, patchFile) {
+	if (isGitApplyable(indexFile, patchFile)) {
+		const bootRoot = path.dirname(path.dirname(indexFile));
+		execFileSync('git', ['apply', '-p1', '--directory', '.', patchFile], {
+			cwd: bootRoot,
+		});
+		return 'git-apply';
+	}
+	const content = fs.readFileSync(indexFile, 'utf8');
+	const result = applyToContent(content);
+	if (!result.ok) throw new Error(`apply failed: ${result.reason}`);
+	fs.writeFileSync(indexFile, result.content, 'utf8');
+	return 'builtin-replace';
+}
+
+function isGitApplyable(indexFile, patchFile) {
+	const bootRoot = path.dirname(path.dirname(indexFile));
+	try {
+		// --directory 只接受相对路径（git 拒绝绝对目标 "invalid path"），故以包根为 cwd。
+		execFileSync('git', ['apply', '--check', '-p1', '--directory', '.', patchFile], {
+			cwd: bootRoot,
+		});
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** 命令行主入口。@returns {number} 退出码 */
+export function run(argv = process.argv.slice(2)) {
+	let dshRoot;
+	let patchFile = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'patches', 'dsh-app-boot-route-scoped-hotfix.patch');
+	let force = false;
+	let revert = false;
+	let dryRun = false;
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg === '--dsh-root') dshRoot = argv[++i];
+		else if (arg === '--patch-file') patchFile = argv[++i];
+		else if (arg === '--force') force = true;
+		else if (arg === '--revert') revert = true;
+		else if (arg === '--dry-run') dryRun = true;
+		else if (arg === '--help' || arg === '-h') {
+			console.log('usage: node scripts/hotfix-core.mjs [--dsh-root <dir>] [--patch-file <file>] [--force] [--revert] [--dry-run]');
+			return 0;
+		}
+	}
+
+	let indexFile;
+	for (const root of resolveCandidateRoots(dshRoot)) {
+		indexFile = findBootIndex(root);
+		if (indexFile) {
+			console.log(`[dsh-hotfix] using DSH root: ${root}`);
+			break;
+		}
+	}
+	if (!indexFile) {
+		console.error('[dsh-hotfix] dsh-app-boot/lib/index.js not found in any candidate root; pass --dsh-root explicitly.');
+		return 1;
+	}
+
+	const pkgPath = path.join(path.dirname(path.dirname(indexFile)), 'package.json');
+	let actualVersion;
+	try {
+		actualVersion = JSON.parse(fs.readFileSync(pkgPath, 'utf8')).version;
+	} catch {
+		/* 读不到版本号时跳过比对 */
+	}
+	const patchText = fs.existsSync(patchFile) ? fs.readFileSync(patchFile, 'utf8') : '';
+	const declared = parsePatchTargetVersion(patchText) ?? TARGET_VERSION;
+	if (actualVersion && actualVersion !== declared && !force) {
+		console.warn(`[dsh-hotfix] version mismatch: installed ${actualVersion} != patch target ${declared}. Use --force to apply anyway.`);
+		return 2;
+	}
+
+	let content;
+	try {
+		content = fs.readFileSync(indexFile, 'utf8');
+	} catch (err) {
+		console.error(`[dsh-hotfix] cannot read ${indexFile}: ${err.message}`);
+		return 1;
+	}
+
+	if (revert) {
+		const backup = indexFile + BACKUP_SUFFIX;
+		if (fs.existsSync(backup)) {
+			if (dryRun) {
+				console.log(`[dsh-hotfix] dry-run: would restore ${backup} -> ${indexFile}`);
+				return 0;
+			}
+			fs.copyFileSync(backup, indexFile);
+			console.log(`[dsh-hotfix] reverted ${indexFile} from backup.`);
+			return 0;
+		}
+		const result = revertContent(content);
+		if (!result.ok) {
+			console.error(`[dsh-hotfix] revert failed: ${result.reason} (no backup at ${backup}).`);
+			return 1;
+		}
+		if (dryRun) {
+			console.log('[dsh-hotfix] dry-run: would revert via builtin replacement.');
+			return 0;
+		}
+		fs.writeFileSync(indexFile, result.content, 'utf8');
+		console.log(`[dsh-hotfix] reverted ${indexFile} via builtin replacement.`);
+		return 0;
+	}
+
+	if (isApplied(content)) {
+		console.log('[dsh-hotfix] already applied; nothing to do.');
+		return 0;
+	}
+	if (dryRun) {
+		console.log(`[dsh-hotfix] dry-run: would apply patch to ${indexFile}.`);
+		return 0;
+	}
+	const backup = indexFile + BACKUP_SUFFIX;
+	if (!fs.existsSync(backup)) fs.copyFileSync(indexFile, backup);
+	const method = applyToIndexFile(indexFile, patchFile);
+	console.log(`[dsh-hotfix] applied to ${indexFile} (via ${method}; backup at ${backup}).`);
+	return 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+	process.exitCode = run(process.argv.slice(2));
+}

package/skills/db-admin/SKILL.md

@@ -57,6 +57,7 @@ DatabaseManager({ action: "schema", conn_id: "c1", database: "shop", table: "use
 ```
 
 - 表列表返回 `TableInfo[]`：`{name, type?, comment?, database?}`（Redis 的 type 为 hash|list|set|zset|string|stream）。
+- PostgreSQL/GaussDB 为「数据库 → 模式(schema) → 表」三层语义：`database` 参数此时应传 **schema 名**（如 `public`）；不确定时先执行 `SELECT nspname FROM pg_catalog.pg_namespace WHERE nspname NOT LIKE 'pg\_%' AND nspname <> 'information_schema'` 列出可用 schema。
 - 列结构返回 `ColumnInfo[]`：`{name, dataType, nullable, key?, default?, comment?}`。
 
 ### 5. preview — 预览表数据