@nsyan/db 1.3.0 → 1.3.2

package/README.md

@@ -15,7 +15,7 @@
 
 - **10 种数据库 · 6 家族**：PostgreSQL · MySQL · Oracle · 达梦 · Redis · Elasticsearch · MongoDB · Neo4j · Hive · Spark
 - **AI 工具**：查询 / 表结构 / 连接清单 / 扫描建连，读多写少场景的 token 友好输出
-- **扫描建连**：AI 驱动——工具返回项目文件树，会话 AI 自行定位并阅读配置文件（任意语言/格式），提取候选后弹框确认建连；防幻觉校验（url 必须能被方言解析）
+- **扫描建连**：AI 驱动——工具返回项目文件树，会话 AI 自行定位并阅读配置文件（任意语言/格式），提取候选后弹框确认建连；防幻觉校验（url 必须能被方言解析）+ 来源可信度评级（远端证据 / 环境标识 / 跨环境冲突）提示“能连通 ≠ 属于当前环境”
 - **安全模型**：只读模式、写确认 + 执行理由、连接级强制只读、家族白名单、管理命令恒拒
 - **审计**（可选）：写操作按天落盘，含理由与完整 SQL
 - **零构建**：TypeScript 由 pi/tsx 直接加载，core/dialects 零 pi 运行时依赖
@@ -74,6 +74,7 @@ pi install ./packages/db     # 本仓库开发者
 | 家族白名单 | Redis/ES/Mongo 只读白名单；`DROP`、管理 DDL、服务端 JS、`CALL dbms.*` 恒拒 |
 | 审计日志 | 默认关；`/db config` 开启后写操作按天落盘（完整 SQL，0600） |
 | 凭据 | 配置文件 `0600`；扫描场景密码经确认框补录（v1.3 起随 AI 阅读进会话，用户知情接受） |
+| 扫描越界 | `path` 相对会话工作目录（`ctx.cwd`）解析，按**真实路径（realpath）**判定：`..` 上跳、绝对路径、仓库内指向子树外的软链（如 `dbconf -> /etc`）一律拒绝；`ctx.cwd` 缺失时 fail-closed，绝不回落到宿主进程目录 |
 
 ## ⚙️ 设置
 

package/docs/USAGE.md

@@ -60,13 +60,19 @@
 
 **流程**：
 
-1. AI 调用 `scan_project_configs` 获取项目文件树（path 强制限定当前工作目录子树内，越界拒绝）
-2. AI 从树中挑出可能含连接配置的文件，用自带读文件工具阅读，提取候选（类型/host/端口/库名/账号/密码/连接串）
+1. AI 调用 `scan_project_configs` 获取项目文件树（path 相对**会话工作目录**（`ctx.cwd`）解析，越界拒绝；判定按**真实路径**（realpath）：仓库内指向子树外的软链（如 `dbconf -> /etc`）同样拒绝，扫描不会成为越界的第二个入口）
+2. AI 先定位**当前生效的环境**（Spring：application.yml/bootstrap.yml + pom.xml 的 profile，Maven `@xxx@` 占位符真值在 `<profile><properties>` 里），再挑出可能含连接配置的文件阅读提取；配置指向配置中心（nacos/apollo）时以**远端为准**（仓库里签入的副本常已过期）
 3. AI 调用 `db_scan_save` 提交候选——工具逐个弹确认框：确认 → 补录缺字段 → **测试连接通过才写盘**；同名连接三选一（覆盖/改名/跳过）
 4. 被拒绝的候选（url 与类型矛盾等）AI 会按返回原因修正后重提
 
+> ⚠️ **“能连通”≠“属于当前环境”**：同一仓库常并存 dev/test/devops/prod/dm 多套配置，连错的库（尤其是废弃库名、其他环境的地址）一样能测通。请核对确认框里的**来源**字段是否对应生效 profile。
+
 **防幻觉校验**（确定性规则，AI 不可绕过）：dialectId 必须在支持列表内；带 `url` 的候选必须能被对应方言 `parseUrl` 解析（解析成功后以 URL 为准）；host 必填、port 范围 1~65535。
 
+**来源可信度**（确定性规则，展示用、不拒绝）：插件按候选的 `source` 评级并在确认框/结果里展示理由——🟢 source 含**远端检索证据**（远端 URL / `dataId=` / 显式「远端」）/ 🟡 本地文件带环境标识，或**仅自述配置中心产品名**（仓库里签入的副本也会命中产品名，而签入副本会漂移，所以不升级为可信）/ 🔴 无环境标识、或本批次跨多个环境。`testConnection` 只证明库存在、凭据有效，**不证明它属于当前环境**，这一评级就是你在写盘前拦住「连错环境」的那一眼。
+
+> 边界说明：评级输入是**模型自述的 source 文本**，不是独立取证（写什么就信什么）；它提高的是「误连环境」的被发现概率，不是安全保证。
+
 **结果状态**：✅ 可直接建 / ✏️ 待补字段（确认框中补录）/ ⏭️ 同名已存在。
 
 ### 配置中心场景（Nacos / Apollo / Spring Cloud Config）
@@ -83,7 +89,7 @@
    ```
 3. 从返回的 YAML 原文提取连接候选 → `db_scan_save` 提交（校验/确认/测试连接照常）
 
-本地 profile 文件（如 `application-dev.yml`）与配置中心共有的项目，两边都会被提取，重复的连接靠同名查重（⏭️ exists 状态）与确认框兜底。
+本地 profile 文件（如 `application-dev.yml`）与配置中心共有的项目：**以远端为准**（仓库里签入的副本常已过期），两边若都提取出候选，重复连接靠同名查重（⏭️ exists 状态）与确认框兜底，但冲突值不取本地。
 
 **隐私行为变化**（v1.3.0，用户知情接受）：配置文件原文（含密码）会随 AI 阅读进入会话上下文；v1.2 及以前"密码只在终端补录、不进模型上下文"的承诺不再适用于扫描场景（查询/连接管理不受影响）。
 

package/index.ts

@@ -5,7 +5,9 @@ import { registry } from "./src/dialects/index.js";
 import { decide, effectiveReadonly, writeRequiresReason } from "./src/core/policy.js";
 import { appendAuditLog } from "./src/core/audit.js";
 import { collectTree } from "./src/core/scan/tree.js";
+import { MAX_DEPTH } from "./src/core/scan/walker.js";
 import { validateCandidates } from "./src/core/scan/validate.js";
+import { TRUST_GLYPH, TRUST_LABEL } from "./src/core/scan/trust.js";
 import type { Candidate, ConnConfig, DbTypeId } from "./src/core/types.js";
 import {
   loadConfigs, saveConfigs, loadPluginConfig, savePluginConfig, getConfigSummary,
@@ -50,13 +52,21 @@ function buildDisplayList(configs: ConnConfig[]): { list: string[]; map: Map<str
 // ── 构建「可用数据库」提示（注入系统提示，让 AI 知道有哪些连接） ────
 // 效率项（Spec §6）：每连接只注一行 `名称[家族] + 一行语义`，细节压进系统提示
 
-// 各家族一行语义（KV/搜索/大数据行由后续任务的 dialect.label 接管，此处三库先行）
+// 各家族一行语义：让 AI 一眼知道该类型的 sql 参数填什么（覆盖全部十种类型）
 function familyHint(c: ConnConfig): string {
   switch (c.type) {
     case "postgresql":
     case "mysql":
     case "oracle":
+    case "dm":
       return "关系型，sql 参数填 SQL";
+    case "redis":
+      return "Redis 键值库，sql 参数填单条 Redis 命令（如 GET key / SCAN 0 MATCH user:* COUNT 100；KEYS 已禁用，扫描请用 SCAN）";
+    case "elasticsearch":
+      return "Elasticsearch 搜索库，sql 参数填 DSL JSON（如 {\"query\":{\"match_all\":{}}}；仅支持读端点 _search/_count/_mget）";
+    case "hive":
+    case "spark":
+      return "大数据 SQL 引擎，sql 参数填 SQL（如 SELECT * FROM 库.表 LIMIT 10）";
     case "mongodb":
       return "MongoDB 文档库，sql 参数填 JSON 命令信封（如 {\"find\":\"users\",\"filter\":{}}；读命令 find/count/distinct/aggregate）";
     case "neo4j":
@@ -70,7 +80,7 @@ function familyHint(c: ConnConfig): string {
 const SCAN_TRIGGER_HINT = [
   "[项目扫描建连]",
   "当用户说“连一下这个项目的数据库”“帮我把这项目的库配上”“/db scan”等时，走两步 AI 扫描流程：",
-  "第 1 步：调用 scan_project_configs 获取项目文件树（path 必须在当前工作目录子树内，越界拒绝）；",
+  "第 1 步：调用 scan_project_configs 获取项目文件树（path 相对会话工作目录 ctx.cwd 解析，按真实路径判定越界，越界拒绝）；",
   "第 2 步：从树中自行判断哪些文件可能包含数据库连接配置（任意语言：Spring/Py/Go/TS/Rust 的 yml/toml/env/ini/json 等都算），用自带读文件工具阅读它们，",
   "  从中提取连接候选（类型/host/端口/库名/账号/密码），用户说“只要 pg”这类话时只提取对应类型；",
   "第 3 步：调用 db_scan_save 提交候选——工具会弹确认框，用户逐个确认并补录密码后才写盘，绝不静默建连。",
@@ -126,7 +136,16 @@ const SCAN_GLYPH: Record<Candidate["status"], string> = {
 function candidateLine(c: Candidate): string {
   const p = c.partial;
   const miss = c.missing.length ? `，缺: ${c.missing.join("/")}` : "";
-  return `${SCAN_GLYPH[c.status]} [${c.status}] ${p.name} (${c.dialectId}) ${p.host ?? ""}:${p.port ?? ""}${p.database ? "/" + p.database : ""}${miss} <- ${c.source}`;
+  const trust = `${TRUST_GLYPH[c.trust.level]}${TRUST_LABEL[c.trust.level]}(环境: ${c.trust.env ?? "未知"})`;
+  return `${SCAN_GLYPH[c.status]} [${c.status}] ${p.name} (${c.dialectId}) ${p.host ?? ""}:${p.port ?? ""}${p.database ? "/" + p.database : ""}${miss} ${trust} <- ${c.source}`;
+}
+
+/** 会话工作目录（信任锚）——扫描与审计都用它，不用 `process.cwd()`。
+ *  `process.cwd()` 是宿主进程的 OS cwd，pi-web 下是 pi-web 包目录、TUI 下是启动目录，
+ *  都与会话 cwd 不同源（见 walker.resolveRoot 注释）。缺失时返回 null，由调用方 fail-closed。 */
+function sessionCwdOf(ctx: any): string | null {
+  const cwd = ctx?.cwd;
+  return typeof cwd === "string" && cwd ? cwd : null;
 }
 
 // ── 导出扩展 ──────────────────────────────────────
@@ -140,9 +159,12 @@ export default function (pi: ExtensionAPI) {
   const confirmAndSaveCandidate = async (ctx: any, cand: Candidate): Promise<"saved" | "skipped" | "failed"> => {
     const p = cand.partial;
     let name = p.name!;
+    // 来源可信度必须出现在确认框里：testConnection 通过之后，唯一能拦住「连错环境」的就是用户这一眼
+    const trustBlock = `\n${TRUST_GLYPH[cand.trust.level]} ${TRUST_LABEL[cand.trust.level]}（环境: ${cand.trust.env ?? "未知"}）\n`
+      + cand.trust.reasons.map((r) => `  · ${r}`).join("\n");
     const ok = await ctx.ui.confirm(
       "AI 扫描建连",
-      `添加 ${name} (${cand.dialectId})？\n${p.host ?? ""}:${p.port ?? ""}${p.database ? "/" + p.database : ""}\n来源: ${cand.source}`,
+      `添加 ${name} (${cand.dialectId})？\n${p.host ?? ""}:${p.port ?? ""}${p.database ? "/" + p.database : ""}\n来源: ${cand.source}${trustBlock}`,
     );
     if (!ok) return "skipped";
 
@@ -530,15 +552,15 @@ export default function (pi: ExtensionAPI) {
           if (result.rows.length > 10) {
             lines.push(`... 还有 ${result.rows.length - 10} 行`);
           }
-          if (result.rows.length > 50) {
+          if (result.rows.length > 50 || result.truncated) {
             try {
               const exp = writeQueryExport(result.columns ?? [], result.rows, `db-menu-${config.name.replace(/[^\w.-]/g, "_")}`);
-              lines.push(`完整结果已导出: ${exp.csvPath} | ${exp.jsonPath}`);
+              lines.push(`已导出取回的结果 (${result.rows.length} 行): ${exp.csvPath} | ${exp.jsonPath}`);
             } catch { /* 导出失败不影响主结果 */ }
           }
         }
         if (result.truncated) {
-          lines.push("（结果已达 maxRows 上限截断）");
+          lines.push("（结果已达 maxRows 上限截断，服务端仍有更多数据未取回）");
         }
         ctx.ui.notify(lines.join("\n"), "info");
       } else {
@@ -655,7 +677,7 @@ export default function (pi: ExtensionAPI) {
         const val = await ctx.ui.select(`选择 ${field.label}`, field.options);
         if (!val) continue;
         if (field.valueMap) {
-          (newCfg as any)[field.key] = field.valueMap[val];
+          (newCfg as any)[field.key] = (field.valueMap as Record<string, unknown>)[val];
         } else {
           (newCfg as any)[field.key] = val === "是";
         }
@@ -699,7 +721,11 @@ export default function (pi: ExtensionAPI) {
     };
   });
 
-  // ── 注册 3 个工具（给 LLM 调用） ──────────────────
+  // ── 注册 6 个工具（给 LLM 调用） ──────────────────
+  // 注：pi 的 AgentToolResult.details 为必填字段（registerTool 的 TDetails 默认 unknown）。
+  // 本插件工具没有结构化详情，故在返回对象里统一显式写 details: undefined——与"完全不提供该字段"
+  // 在运行时等价：宿主读取走可选链（result.details?.x）、合并判定用 `!== undefined`，
+  // 且 JSON 序列化会跳过 undefined 值。
 
   // 解析工具 database 参数：缺省走默认连接（Spec §11.1）；无默认则报错指引
   function resolveTargetDb(name: string | undefined): { config?: ConnConfig; error?: string } {
@@ -735,7 +761,7 @@ export default function (pi: ExtensionAPI) {
 
       const target = resolveTargetDb(params.database);
       if (target.error || !target.config) {
-        return {
+        return { details: undefined,
           content: [{ type: "text" as const, text: target.error ?? "未找到数据库配置" }],
         };
       }
@@ -748,7 +774,7 @@ export default function (pi: ExtensionAPI) {
       // verdict = dialect.isAllowed(sql, readonly) → decide → deny/confirm/run
       const dialect = registry.get(config.type);
       if (!dialect) {
-        return {
+        return { details: undefined,
           content: [{ type: "text" as const, text: `数据库类型 "${config.type}" 暂不支持。` }],
         };
       }
@@ -758,19 +784,19 @@ export default function (pi: ExtensionAPI) {
         const note = !cfg.ai_readonly && config.forceReadonly === true
           ? `（连接 ${config.name} 已设置强制只读）`
           : "";
-        return {
+        return { details: undefined,
           content: [{ type: "text" as const, text: (verdict.reason ?? "该操作不被允许。如需修改，请执行 /db config 更改配置。") + note }],
         };
       }
       // 写操作强制附执行理由（v1.1 UX 共识 Q1/Q3：与确认策略解耦；缺 reason 拒绝并引导 AI 补充）
       if (writeRequiresReason(verdict, params.reason)) {
-        return {
+        return { details: undefined,
           content: [{ type: "text" as const, text: "写操作必须附执行理由：请在 reason 参数中说明动机与影响范围（如\"将status=2的历史订单归档，预计影响1.2万行\"），补充后重试。" }],
         };
       }
       if (action === "confirm") {
         if (!ctx?.hasUI) {
-          return {
+          return { details: undefined,
             content: [{ type: "text" as const, text: "当前环境无法弹出确认对话框，已取消 SQL 执行。请在有界面的环境中操作。" }],
           };
         }
@@ -779,7 +805,7 @@ export default function (pi: ExtensionAPI) {
           `理由: ${params.reason}\n\n${verdict.summary ?? ""}\n\n数据库: ${config.name}\n\nSQL:\n${params.sql}`,
         );
         if (!ok) {
-          return {
+          return { details: undefined,
             content: [{ type: "text" as const, text: "用户取消了 SQL 执行。" }],
           };
         }
@@ -793,7 +819,7 @@ export default function (pi: ExtensionAPI) {
       );
 
       if (!result.success) {
-        return {
+        return { details: undefined,
           content: [{ type: "text" as const, text: `查询失败: ${result.error}` }],
         };
       }
@@ -803,7 +829,7 @@ export default function (pi: ExtensionAPI) {
       if (verdict.isWrite && cfg.audit_enabled) {
         appendAuditLog({
           time: new Date().toISOString(),
-          project: process.cwd(),
+          project: sessionCwdOf(ctx) ?? "(会话目录未知)",
           connection: config.name,
           type: config.type,
           summary: verdict.summary ?? "",
@@ -823,15 +849,17 @@ export default function (pi: ExtensionAPI) {
         const rows = result.rows.slice(0, 50).map((r) => r.join(" | "));
         text += [header, separator, ...rows].join("\n");
         if (result.rows.length > 50) {
-          // P0 导出：长结果落盘 /tmp（CSV+JSON），只回路径不贴全量
-          text += `\n... 还有 ${result.rows.length - 50} 行`;
+          text += `\n... 还有 ${result.rows.length - 50} 行（本次共取回 ${result.rows.length} 行）`;
+        }
+        // 取回行数超展示上限，或被 maxRows 截断时落盘 /tmp（CSV+JSON），只回路径不贴全量
+        if (result.rows.length > 50 || result.truncated) {
           try {
             const exp = writeQueryExport(result.columns ?? [], result.rows, `db-query-${config.name.replace(/[^\w.-]/g, "_")}`);
-            text += `\n完整结果已导出: ${exp.csvPath} | ${exp.jsonPath}`;
+            text += `\n已导出取回的结果 (${result.rows.length} 行): ${exp.csvPath} | ${exp.jsonPath}`;
           } catch { /* 导出失败不影响主结果 */ }
         }
         if (result.truncated) {
-          text += `\n（结果已达 maxRows 上限截断）`;
+          text += `\n（结果已达 maxRows 上限截断，服务端仍有更多数据未取回）`;
         }
       } else {
         text += "无数据返回。";
@@ -841,7 +869,7 @@ export default function (pi: ExtensionAPI) {
         text += `\n执行理由: ${params.reason}`;
       }
 
-      return { content: [{ type: "text" as const, text }] };
+      return { details: undefined, content: [{ type: "text" as const, text }] };
     },
   });
 
@@ -858,7 +886,7 @@ export default function (pi: ExtensionAPI) {
     async execute(_toolCallId: string, params: { database?: string; pattern?: string }, _signal: any) {
       const target = resolveTargetDb(params.database);
       if (target.error || !target.config) {
-        return {
+        return { details: undefined,
           content: [{ type: "text" as const, text: target.error ?? "未找到数据库配置" }],
         };
       }
@@ -866,14 +894,14 @@ export default function (pi: ExtensionAPI) {
 
       const dialect = registry.get(config.type);
       if (!dialect) {
-        return {
+        return { details: undefined,
           content: [{ type: "text" as const, text: `数据库类型 "${config.type}" 暂不支持。` }],
         };
       }
       const result = await dialect.listTables(toRuntimeConfig(config, dialect.defaultPort), params.pattern);
 
       if (!result.success || !result.tables) {
-        return {
+        return { details: undefined,
           content: [{ type: "text" as const, text: `获取表列表失败: ${result.error}` }],
         };
       }
@@ -885,7 +913,7 @@ export default function (pi: ExtensionAPI) {
         return `${schema}${t.name} (${t.type})${desc}`;
       });
 
-      return {
+      return { details: undefined,
         content: [{ type: "text" as const, text: `数据库 "${config.name}"${params.pattern ? `（pattern: ${params.pattern}）` : ""} 共 ${result.count} 张表:\n${lines.join("\n")}` }],
       };
     },
@@ -904,7 +932,7 @@ export default function (pi: ExtensionAPI) {
     async execute(_toolCallId: string, params: { database?: string; table: string }, _signal: any) {
       const target = resolveTargetDb(params.database);
       if (target.error || !target.config) {
-        return {
+        return { details: undefined,
           content: [{ type: "text" as const, text: target.error ?? "未找到数据库配置" }],
         };
       }
@@ -912,14 +940,14 @@ export default function (pi: ExtensionAPI) {
 
       const dialect = registry.get(config.type);
       if (!dialect) {
-        return {
+        return { details: undefined,
           content: [{ type: "text" as const, text: `数据库类型 "${config.type}" 暂不支持。` }],
         };
       }
       const result = await dialect.describeTable(toRuntimeConfig(config, dialect.defaultPort), params.table);
 
       if (!result.success || !result.columns) {
-        return {
+        return { details: undefined,
           content: [{ type: "text" as const, text: `获取表结构失败: ${result.error}` }],
         };
       }
@@ -935,7 +963,7 @@ export default function (pi: ExtensionAPI) {
         );
       }
 
-      return {
+      return { details: undefined,
         content: [{ type: "text" as const, text: lines.join("\n") }],
       };
     },
@@ -945,30 +973,44 @@ export default function (pi: ExtensionAPI) {
   pi.registerTool({
     name: "scan_project_configs",
     label: "扫描项目数据库配置",
-    description: "获取项目文件树，供 AI 自行定位并阅读数据库连接配置文件（任意语言：Spring/Py/Go/TS/Rust 的 yml/toml/env/ini/json 等均覆盖）。本身不做提取；提取结果用 db_scan_save 提交。",
-    promptSnippet: "当用户说「连一下这个项目的数据库」「帮我把这项目的库配上」「/db scan 配置pg」等时调用第 1 步。返回项目文件树后：自己判断哪些文件可能含数据库连接配置（用户指了类型就只找该类型），用自带读文件工具阅读，提取连接候选（类型/host/端口/库名/账号/密码），然后调用 db_scan_save 提交。path 必须在当前工作目录子树内。",
+    description: "获取项目文件树，供 AI 自行定位并阅读数据库连接配置文件（任意语言：Spring/Py/Go/TS/Rust 的 yml/toml/env/ini/json 等均覆盖）。本身不做提取；提取结果用 db_scan_save 提交。path 相对会话工作目录（ctx.cwd）解析，按真实路径（realpath）强制限定在该子树内。",
+    promptSnippet: "当用户说「连一下这个项目的数据库」「帮我把这项目的库配上」「/db scan 配置pg」等时调用第 1 步。返回项目文件树后：自己判断哪些文件可能含数据库连接配置（用户指了类型就只找该类型），用自带读文件工具阅读，提取连接候选（类型/host/端口/库名/账号/密码），然后调用 db_scan_save 提交。path 相对会话工作目录解析，必须在会话工作目录子树内。",
+    promptGuidelines: [
+      "扫描建连（scan_project_configs → db_scan_save）先定位「当前生效的环境」再取配置：Spring 项目读 application.yml/bootstrap.yml 与 pom.xml 的 profiles（Maven 的 @xxx@ 占位符真值在 pom.xml 的 <profile><properties> 里）；同仓库常并存 dev/test/devops/prod/dm 多套配置，读错 profile 会拿到废弃库。",
+      "配置指向配置中心（nacos/apollo/spring-cloud-config）时以远端为准：仓库里签入的 *_配置副本.yaml 常已过期，远端与本地冲突时用远端值；每个候选的 source 写清「生效 profile + 来源文件/dataId」。",
+      "能连通只证明库存在且凭据有效，不等于它属于当前环境：来源可疑（非生效 profile、环境无法确定）的候选不要提交，先向用户确认。插件按确定性规则给每个候选评级并随工具返回（🟢 source 含远端证据 URL/dataId、🟡 本地文件带环境标识或仅自述配置中心、🔴 无环境标识或本批跨环境冲突），汇报结果时必须如实转述评级与理由，不得把 🟡/🔴 说成已核实；从远端拉的候选请在 source 里写明 dataId 或 URL。",
+    ],
     parameters: Type.Object({
-      path: Type.Optional(Type.String({ description: "扫描根目录，缺省为当前工作目录；强制限定在当前工作目录子树内，越界拒绝" })),
+      path: Type.Optional(Type.String({ description: "扫描根目录，缺省为会话工作目录；强制限定在会话工作目录子树内（按真实路径判定，指向子树外的软链同样被拒，越界拒绝）" })),
     }),
-    async execute(_toolCallId: string, params: { path?: string }, _signal: any) {
+    async execute(_toolCallId: string, params: { path?: string }, _signal: any, _onUpdate?: any, ctx?: any) {
+      // 锚点取会话 cwd（ctx.cwd）。缺失时 **fail-closed**：用 process.cwd() 兜底等于把红线
+      // 钉在宿主目录上（pi-web 下就是 pi-web 包目录），正是本版修掉的错锚点
+      const anchor = sessionCwdOf(ctx);
+      if (!anchor) {
+        return { details: undefined,
+          content: [{ type: "text" as const, text: "扫描失败: 无法获取会话工作目录（ctx.cwd 缺失）——拒绝在未知锚点下扫描。" }],
+        };
+      }
       try {
-        const tree = collectTree(params.path ?? ".");
+        const tree = collectTree(params.path ?? ".", anchor);
         const text = [
           `项目根目录: ${tree.root}（文件总数 ${tree.total}${tree.truncated ? "，已截断展示前 " + tree.lines.length + " 条" : ""}）`,
+          ...(tree.depthCapped ? [`⚠️ 文件树可能不完整：有目录未展开（超过 ${MAX_DEPTH} 层或目录数上限）——可把更深的子目录作为 path 再扫一次`] : []),
           "",
           "文件树（相对路径，浅层优先）：",
           ...tree.lines,
           "",
           "下一步（必须执行）：",
-          "1. 从文件树中判断哪些文件可能包含数据库连接配置——任意语言/格式都算：Spring application*.yml、Python settings/config.py、Go config.yaml、Node .env、Rust .env+config.toml、docker-compose、K8s manifest 等；",
-          "2. 用你的读文件工具阅读这些文件；若发现 bootstrap.yml/application.yml 指向配置中心（nacos/apollo/spring-cloud-config），用配置中心地址与凭据拉取远端配置后再提取——例如 Nacos：先用 POST {server}/nacos/v1/auth/login（form: username/password）拿 accessToken，再 GET {server}/nacos/v1/cs/configs?dataId=<服务名>.yaml&group=<group>&tenant=<namespace-id>&accessToken=<token>，返回的 YAML 原文同样提取候选；",
-          "3. 从本地/远端配置中提取连接候选：dialectId（postgresql/mysql/oracle/dm/redis/elasticsearch/mongodb/neo4j/hive/spark）、host、port、database、username、password、url（如有完整连接串）、source（来源文件或 dataId）；用户指定了类型（如「配置pg」）就只提取该类型；",
+          "1. 先定位「当前生效的环境」，再看文件：Spring 项目看 application.yml/bootstrap.yml 与 pom.xml 的 profiles（Maven 的 @xxx@ 占位符真值在 pom.xml 的 <profile><properties> 里），确定生效 profile（如 devops）与生效配置文件（如 application-devops.yml）——同仓库常并存 dev/test/devops/prod/dm 多套配置，读错 profile 会拿到废弃库；再判断哪些文件可能包含数据库连接配置——任意语言/格式都算：Spring application*.yml、Python settings/config.py、Go config.yaml、Node .env、Rust .env+config.toml、docker-compose、K8s manifest 等；",
+          "2. 用你的读文件工具阅读生效 profile 的文件；若 bootstrap.yml/application.yml 指向配置中心（nacos/apollo/spring-cloud-config），必须以远端配置为准（仓库里签入的副本常已过期）——例如 Nacos：先用 POST {server}/nacos/v1/auth/login（form: username/password）拿 accessToken，再 GET {server}/nacos/v1/cs/configs?dataId=<服务名>.yaml&group=<group>&tenant=<namespace-id>&accessToken=<token>；远端与本地冲突时以远端为准；",
+          "3. 从生效配置中提取连接候选：dialectId（postgresql/mysql/oracle/dm/redis/elasticsearch/mongodb/neo4j/hive/spark）、host、port、database、username、password、url（如有完整连接串）、source（写清「生效 profile + 来源文件/dataId」，如 pom.xml#devops → application-devops.yml）；用户指定了类型（如「配置pg」）就只提取该类型；来源可疑（非生效 profile、环境无法确定）的候选不要提交，先向用户确认；",
           "4. 调用 db_scan_save 提交候选数组。带 url 的候选必须能被对应方言解析，编造的 url 会被拒绝；",
           "5. 工具会弹确认框让用户逐个确认并补录密码，把工具返回的保存结果汇报给用户。",
         ].join("\n");
-        return { content: [{ type: "text" as const, text }] };
+        return { details: undefined, content: [{ type: "text" as const, text }] };
       } catch (err) {
-        return {
+        return { details: undefined,
           content: [{ type: "text" as const, text: `扫描失败: ${err instanceof Error ? err.message : String(err)}` }],
         };
       }
@@ -991,12 +1033,12 @@ export default function (pi: ExtensionAPI) {
         password: Type.Optional(Type.String({ description: "密码（缺失时确认框会引导用户补录）" })),
         url: Type.Optional(Type.String({ description: "完整连接串（可选，提供时必须能被方言解析，否则整条拒绝）" })),
         name: Type.Optional(Type.String({ description: "连接名称（缺省自动生成）" })),
-        source: Type.Optional(Type.String({ description: "来源描述，如配置文件相对路径" })),
+        source: Type.Optional(Type.String({ description: "来源描述。本地文件写「生效 profile + 来源文件」，如 pom.xml#devops → application-devops.yml；从配置中心拉的必须写远端证据（远端 URL 或 dataId=），否则只能评为 🟡。插件按此评级并在确认框展示，缺失/无环境标识评为 🔴" })),
       }), { description: "连接候选数组" }),
     }),
     async execute(_toolCallId: string, params: { candidates: unknown[] }, _signal: any, _onUpdate?: any, ctx?: any) {
       if (!ctx?.ui) {
-        return { content: [{ type: "text" as const, text: "db_scan_save 需要交互式会话（ctx.ui 不可用）。请引导用户在终端执行 /db add 手动添加。" }] };
+        return { details: undefined, content: [{ type: "text" as const, text: "db_scan_save 需要交互式会话（ctx.ui 不可用）。请引导用户在终端执行 /db add 手动添加。" }] };
       }
       const { candidates, rejected } = validateCandidates(params.candidates, new Set(loadConfigs().map((c) => c.name)));
       const lines: string[] = [];
@@ -1006,20 +1048,23 @@ export default function (pi: ExtensionAPI) {
       if (candidates.length === 0) {
         lines.push(rejected.length > 0 ? "没有可保存的候选。" : "未收到有效候选（candidates 需为数组，每项含 dialectId+host）。",
           "提示：从配置文件原文提取后重试；确认方言取值在支持列表内。");
-        return { content: [{ type: "text" as const, text: lines.join("\n") }] };
+        return { details: undefined, content: [{ type: "text" as const, text: lines.join("\n") }] };
       }
       lines.push(`收到 ${candidates.length} 个连接候选，逐个确认：`, ...candidates.map(candidateLine), "");
       const results: string[] = [];
       for (const cand of candidates) {
         try {
           const r = await confirmAndSaveCandidate(ctx, cand);
-          results.push(`${SCAN_GLYPH[cand.status]} ${cand.partial.name} (${cand.dialectId}): ${r === "saved" ? "已保存" : r === "skipped" ? "用户跳过" : "连接失败未保存"}`);
+          const trustLine = `${TRUST_GLYPH[cand.trust.level]}${TRUST_LABEL[cand.trust.level]}（环境: ${cand.trust.env ?? "未知"}）`;
+          // 理由一并回传：promptGuidelines 要求模型如实转述评级与理由，模型看不到就无从转述
+          const why = cand.trust.reasons.length ? `\n      ${cand.trust.reasons.join("；")}` : "";
+          results.push(`${SCAN_GLYPH[cand.status]} ${cand.partial.name} (${cand.dialectId}): ${r === "saved" ? "已保存" : r === "skipped" ? "用户跳过" : "连接失败未保存"} ${trustLine}${why}`);
         } catch (err) {
           results.push(`❌ ${cand.partial.name} (${cand.dialectId}): 异常 ${err instanceof Error ? err.message : String(err)}`);
         }
       }
       lines.push("", "保存结果：", ...results.map((r) => "  - " + r));
-      return { content: [{ type: "text" as const, text: lines.join("\n") }] };
+      return { details: undefined, content: [{ type: "text" as const, text: lines.join("\n") }] };
     },
   });
 
@@ -1033,7 +1078,7 @@ export default function (pi: ExtensionAPI) {
     async execute() {
       const configs = loadConfigs();
       if (configs.length === 0) {
-        return {
+        return { details: undefined,
           content: [{ type: "text" as const, text: "尚无数据库连接。请引导用户在终端执行 /db add 或 /db scan 建连。" }],
         };
       }
@@ -1046,7 +1091,7 @@ export default function (pi: ExtensionAPI) {
         const url = registry.get(c.type)?.displayUrl(c) ?? "";
         return `- ${c.name} [${shortTypeLabel(c.type)}]${marks ? " " + marks : ""} - ${fullTypeLabel(c.type)}${c.database ? " · 库: " + c.database : ""} · ${url} · ${test}${used ? " · " + used : ""}${c.description ? " · " + c.description : ""}`;
       });
-      return {
+      return { details: undefined,
         content: [{ type: "text" as const, text: `共 ${configs.length} 个连接：\n${lines.join("\n")}\n\n标注 [prod·强制只读] 的连接永远只读（即使全局允许写操作）。` }],
       };
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nsyan/db",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "AI 数据库接入扩展 for pi —— 达梦(DM)/PostgreSQL/MySQL/Oracle/Redis/Elasticsearch/MongoDB/Neo4j/Hive/Spark 十种数据库，六大家族方言，提供查询/表结构/扫描建连/连接清单 LLM 工具 | Database access extension for the pi coding agent: query, schema browsing, connection scanning and audit tools for PostgreSQL, MySQL, Oracle, DM (Dameng 达梦), Redis, Elasticsearch, MongoDB, Neo4j, Hive and Spark",
   "keywords": [
     "pi-extension",
@@ -60,14 +60,17 @@
     "mysql2": "^3.23.1",
     "neo4j-driver": "^5.28.3",
     "oracledb": "^7.0.1",
-    "neo4j-driver": "^5.28.3",
     "pg": "^8.22.0"
   },
   "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.85.1",
+    "@types/node": "^22.20.2",
     "@types/pg": "^8.20.0",
-    "tsx": "^4.23.13"
+    "tsx": "^4.23.13",
+    "typescript": "^7.0.2"
   },
   "scripts": {
-    "test": "tsx --test \"test/**/*.test.ts\""
+    "test": "tsx --test \"test/**/*.test.ts\"",
+    "typecheck": "tsc -p tsconfig.typecheck.json"
   }
 }

package/src/config.ts

@@ -274,11 +274,26 @@ export function toRuntimeConfig(c: ConnConfig, defaultPort: number): ConnConfig
   };
 }
 
-// 供 UI 层展示类型短标签（原 index.ts 内 5 处重复映射的收敛点之一）
+// 供 UI 层展示类型标签（原 index.ts 内 5 处重复映射的收敛点之一）
+// 单一数据源：短标签与全称同表维护。键类型用 Record<DbTypeId, ...> 而非 Record<string, ...>，
+// 新增方言而漏补标签时会在类型检查阶段报错，不再静默 fallback 成原始 id。
+const TYPE_LABELS: Record<DbTypeId, { short: string; full: string }> = {
+  postgresql: { short: "PG", full: "PostgreSQL" },
+  mysql: { short: "MySQL", full: "MySQL" },
+  oracle: { short: "Oracle", full: "Oracle" },
+  dm: { short: "DM", full: "达梦" },
+  redis: { short: "Redis", full: "Redis" },
+  elasticsearch: { short: "ES", full: "Elasticsearch" },
+  mongodb: { short: "MongoDB", full: "MongoDB" },
+  neo4j: { short: "Neo4j", full: "Neo4j" },
+  hive: { short: "Hive", full: "Hive" },
+  spark: { short: "Spark", full: "Spark" },
+};
+
 export function shortTypeLabel(type: DbTypeId): string {
-  return ({ postgresql: "PG", mysql: "MySQL", oracle: "Oracle", mongodb: "MongoDB", neo4j: "Neo4j" } as Record<string, string>)[type] ?? type;
+  return TYPE_LABELS[type]?.short ?? type;
 }
 
 export function fullTypeLabel(type: DbTypeId): string {
-  return ({ postgresql: "PostgreSQL", mysql: "MySQL", oracle: "Oracle", mongodb: "MongoDB", neo4j: "Neo4j" } as Record<string, string>)[type] ?? type;
+  return TYPE_LABELS[type]?.full ?? type;
 }

package/src/core/audit.ts

@@ -12,7 +12,7 @@ export const AUDIT_DIR = join(homedir(), ".pi", "agent", "db-audit");
 export interface AuditEntry {
   /** ISO 时间 */
   time: string;
-  /** 执行时的项目路径（process.cwd()），跨项目区分用 */
+  /** 执行时的项目路径（会话 cwd = ctx.cwd），跨项目区分用 */
   project: string;
   /** 连接名 */
   connection: string;

package/src/core/scan/tree.ts

@@ -10,15 +10,18 @@ export interface TreeResult {
   root: string;            // 绝对路径
   total: number;           // 收集到的文件总数
   truncated: boolean;      // 是否超出 MAX_TREE_LINES 被截断
+  depthCapped: boolean;    // 是否有目录未展开（超 MAX_DEPTH 或目录预算；如实上报，避免静默漏扫）
   lines: string[];         // 相对路径清单（已排序：浅层优先）
 }
 
 const MAX_TREE_LINES = 3000;
 
-/** 收集项目文件树（相对路径排序清单）；越界由 resolveRoot 拒绝 */
-export function collectTree(rootInput: string): TreeResult {
-  const root = resolveRoot(rootInput);
-  const files = walk(root);
+/** 收集项目文件树（相对路径排序清单）；越界由 resolveRoot 拒绝。
+ * anchor 传会话工作目录（`ctx.cwd`），勿传 `process.cwd()`，原因见 walker.resolveRoot。
+ * 输出确定：walk 对目录项排序，本函数再按「浅层优先 + 字典序」排序，同一项目每次结果一致 */
+export function collectTree(rootInput: string, anchor: string): TreeResult {
+  const root = resolveRoot(rootInput, anchor);
+  const { files, depthCapped } = walk(root);
   const rels = files
     .map((f) => f.slice(root.length + 1).split("\\").join("/"))
     .sort((a, b) => {
@@ -29,6 +32,7 @@ export function collectTree(rootInput: string): TreeResult {
     root,
     total: rels.length,
     truncated: rels.length > MAX_TREE_LINES,
+    depthCapped,
     lines: rels.slice(0, MAX_TREE_LINES),
   };
 }

package/src/core/scan/trust.ts

@@ -0,0 +1,86 @@
+// scan/trust.ts —— 候选「来源可信度」评估（确定性规则，纯函数，可单测）
+// 动机：db_scan_save 唯一的客观闸门是 testConnection，而「能连通」只证明库存在、凭据有效，
+//   不证明它属于当前环境。同仓库常并存 dev/test/devops/prod/dm 多套配置，签入的配置中心
+//   副本又会随时间漂移，模型很容易提取到废弃库名或别的环境地址——而且照样能测通。
+//   本模块不判断配置对不对（无确定解），只把「来源能证明什么」分级、在确认框里显式展示，
+//   把环境判断交回用户，而不是让它静默通过。
+//
+// 边界（必须明说）：评级输入是**模型自述的 `source` 文本**，不是独立取证——写什么就信什么。
+//   它抬高的是「误连环境」的被发现概率（用户在确认框多看一眼），不构成安全保证；
+//   真正的闸门只有 testConnection 与用户确认。
+//   因此 🟢 要求 source 里有**远端检索证据**（URL / dataId / 显式「远端」）；仅出现产品名
+//   （nacos/apollo/…）不升级——仓库里签入的同名副本会命中，而那恰恰是会漂移的东西。
+
+export type TrustLevel = "high" | "medium" | "low";
+
+export interface SourceTrust {
+  level: TrustLevel;
+  /** 从 source 识别出的环境标识（local/dev/test/devops/prod…），识别不出为 null */
+  env: string | null;
+  /** 展示给用户的中文理由：只陈述来源能证明什么，不含结论 */
+  reasons: string[];
+}
+
+/** 远端检索证据：只有真的去远端拉过才会写进 source 的标记（URL / Nacos OpenAPI / dataId= / 显式「远端」） */
+const REMOTE_EVIDENCE = /https?:\/\/|dataid\s*=|cs\/configs|(?:远端|远程|remote)/i;
+
+/** 配置中心产品名：仓库里签入的副本文件名同样命中，不能单独证明「取自远端」 */
+const CONFIG_CENTER_NAME = /\bnacos\b|\bapollo\b|\bconsul\b|config[-_ ]?center|config[-_ ]?server|spring-cloud-config/i;
+
+/** 环境标识白名单：按分隔符整段比对，避免 "dev" 命中 "devops" */
+const ENV_TOKENS = new Set([
+  "local", "devops", "dev", "sit", "test", "uat", "stage", "staging", "pre", "gray", "prod", "release", "dm",
+]);
+
+const PROD_TOKENS = new Set(["prod", "release"]);
+
+/** 从 source 文本取环境段（按 . _ - / \ # 空格 = 切分后整段匹配；切 `=` 使 `group=devops` 也能识别） */
+export function envOf(source: string): string | null {
+  for (const tok of source.toLowerCase().split(/[._\-/\\#\s=]+/)) {
+    if (ENV_TOKENS.has(tok)) return tok;
+  }
+  return null;
+}
+
+/**
+ * 批量评估来源可信度（跨候选的环境冲突必须看整批，故入口是数组）。
+ * @param sources 与候选一一对应的 source 文本（空串表示未提供）
+ */
+export function assessSourceTrust(sources: readonly string[]): SourceTrust[] {
+  const envs = sources.map(envOf);
+  const distinct = [...new Set(envs.filter((e): e is string => e !== null))];
+
+  return sources.map((source, i) => {
+    const reasons: string[] = [];
+    const env = envs[i];
+    let level: TrustLevel;
+
+    if (REMOTE_EVIDENCE.test(source)) {
+      level = "high";
+      reasons.push("来源含远端检索证据（URL / dataId / 显式「远端」）：远端配置是运行时真值");
+    } else if (CONFIG_CENTER_NAME.test(source)) {
+      level = "medium";
+      reasons.push("来源自述为配置中心但未写远端证据（URL / dataId）：请确认它取自远端接口，而不是仓库里签入的副本——签入的副本常已过期");
+    } else if (env === null) {
+      level = "low";
+      reasons.push("来源无环境标识：同仓库常并存多套环境配置，且签入的配置中心副本可能已过期，无法判断它是否属于当前环境");
+    } else {
+      level = "medium";
+      reasons.push(`来源为本地文件、环境标识「${env}」：请确认它就是当前生效 profile（Maven 的 @xxx@ 占位符真值在 pom.xml 的 <profile><properties> 里）`);
+    }
+
+    // 一批里出现多个环境，说明至少有一部分候选不属于当前环境，必须让用户定夺
+    if (distinct.length > 1 && env !== null) {
+      level = "low";
+      reasons.unshift(`本批次候选来自多个环境（${distinct.join("、")}）：请确认当前生效的是哪一个，只取生效环境的库`);
+    }
+
+    if (env !== null && PROD_TOKENS.has(env)) {
+      reasons.push("疑似生产环境：保存后建议用 /db 编辑该连接、把环境标签设为 prod（会启用强制只读）");
+    }
+    return { level, env, reasons };
+  });
+}
+
+export const TRUST_GLYPH: Record<TrustLevel, string> = { high: "🟢", medium: "🟡", low: "🔴" };
+export const TRUST_LABEL: Record<TrustLevel, string> = { high: "来源可信", medium: "来源待核", low: "来源存疑" };

package/src/core/scan/validate.ts

@@ -6,7 +6,8 @@
 
 import { basename } from "node:path";
 import { registry } from "../../dialects/index.js";
-import type { Candidate, CandidateInput, CandidateStatus, DbTypeId } from "../types.js";
+import { assessSourceTrust } from "./trust.js";
+import type { Candidate, CandidateInput, CandidateStatus, ConnConfig, DbTypeId } from "../types.js";
 
 /** 各类型建连必需字段（空串同样视为缺失）——家族语义，非正则，保留 */
 const REQUIRED: Record<DbTypeId, string[]> = {
@@ -37,6 +38,13 @@ export function validateCandidates(raw: unknown, existingNames: Set<string>): Va
   const candidates: Candidate[] = [];
   const rejected: string[] = [];
   const seenNames = new Set(existingNames);
+  // 来源可信度：跨候选的环境冲突要看整批，故先批量评估，再按原始下标挂到候选上
+  const trusts = assessSourceTrust(
+    list.map((item) =>
+      item && typeof item === "object" && nonEmpty((item as Record<string, unknown>).source)
+        ? String((item as Record<string, unknown>).source)
+        : ""),
+  );
 
   for (const [i, item] of list.entries()) {
     if (item === null || typeof item !== "object") {
@@ -54,7 +62,9 @@ export function validateCandidates(raw: unknown, existingNames: Set<string>): Va
 
     // ② 带 url 时：方言 parseUrl 必须能解析（防幻觉——claim 与 url 矛盾整条拒）
     //    解析成功时以解析结果为准（host/port/database/username/password 由 URL 补全）
-    let bag: Partial<CandidateInput> = {
+    // 归一化后 port/dbIndex 恒为 number（下行 parseInt 收敛）。此处用 Partial<ConnConfig> 而非
+    // Partial<CandidateInput>——后者的 port 是 number|string，会让下方端口范围校验退化为字符串比较。
+    let bag: Partial<ConnConfig> = {
       host: typeof c.host === "string" ? c.host.trim() : undefined,
       port: typeof c.port === "number" ? c.port : parseInt(String(c.port ?? ""), 10) || undefined,
       username: nonEmpty(c.username) ? String(c.username) : undefined,
@@ -90,7 +100,7 @@ export function validateCandidates(raw: unknown, existingNames: Set<string>): Va
     }
 
     // ④ 缺字段判定
-    const missing = (REQUIRED[dialect.id] ?? []).filter((f) => !nonEmpty(bag[f as keyof CandidateInput]));
+    const missing = (REQUIRED[dialect.id] ?? []).filter((f) => !nonEmpty(bag[f as keyof ConnConfig]));
 
     // ⑤ 命名：显式 name > 默认；同名（含与本批前序候选撞名）→ exists 状态
     let name = nonEmpty(c.name) ? String(c.name).trim()
@@ -104,7 +114,8 @@ export function validateCandidates(raw: unknown, existingNames: Set<string>): Va
       dialectId: dialect.id,
       partial: { name, ...bag } as Partial<import("../types.js").ConnConfig>,
       missing,
-      source: nonEmpty(c.source) ? String(c.source) : "AI 提取",
+      source: nonEmpty(c.source) ? String(c.source) : "AI 提取（未提供来源）",
+      trust: trusts[i],
       warnings: Array.isArray(c.warnings) ? c.warnings.map(String).slice(0, 3) : undefined,
     });
   }

package/src/core/scan/walker.ts

@@ -1,14 +1,23 @@
 // scan/walker.ts —— 目录漫步：默认忽略常见无关目录；resolveRoot 越界拒绝（Spec §8.5 红线）
-import { readdirSync, statSync, type Dirent } from "node:fs";
-import { extname, isAbsolute, join, relative, resolve } from "node:path";
+import { readdirSync, realpathSync, statSync, type Dirent } from "node:fs";
+import { basename, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 
+// 忽略的目录：只列**确定无关**的（依赖/构建产物/版本控制元数据/工具缓存）。
+// 注意 docs 不在此列：本模块不对「目录名是否与配置有关」做猜测（见 tree.ts 设计注释），
+// 配置样例/真实配置放 docs 下的项目是存在的，漏扫比多扫代价大。
 const IGNORED_DIRS = new Set([
-  "node_modules", ".git", "target", "dist", "venv", "logs", "docs",
-  "build", "coverage", "__pycache__", ".idea", ".vscode",
+  "node_modules", ".git", ".svn", ".hg", "target", "dist", "venv", ".venv", "logs",
+  "build", "coverage", "__pycache__", ".idea", ".vscode", ".next", ".nuxt", ".cache",
+  ".gradle", ".tox", ".pytest_cache", ".mypy_cache", ".turbo", ".parcel-cache", ".sass-cache",
 ]);
 
 const MAX_FILES = 2000;
-const MAX_DEPTH = 8;
+/** 目录访问预算：软链别名会重复走到同一个真实目录（见 walk 的断环说明），
+ *  需要一个上界防止病态目录图把扫描拖死；超限经 depthCapped 上报，不静默。 */
+const MAX_DIRS = 20000;
+/** 深度上限：Java 多模块可达 `m/src/main/java/com/x/.../service/mapper/impl`（实测 14 层）、
+ *  monorepo 嵌套更深；超限会通过 depthCapped 如实上报。导出供工具提示引用，避免硬编码层数漂移。 */
+export const MAX_DEPTH = 16;
 
 /** 扫描目标配置文件：不受普通文件配额挤占（大型 Java 工程源码文件可轻易冲爆 MAX_FILES） */
 const CONFIG_EXTS = new Set([".yml", ".yaml", ".properties"]);
@@ -17,47 +26,117 @@ function isConfigFile(name: string): boolean {
   return base === ".env" || base.startsWith(".env.") || CONFIG_EXTS.has(extname(base));
 }
 
+/** target 是否在 base 子树内（纯路径判定，用于拦住软链逃逸） */
+function within(base: string, target: string): boolean {
+  const rel = relative(base, target);
+  return rel === "" || (rel !== ".." && !rel.startsWith(".." + sep) && !isAbsolute(rel));
+}
+
 /**
- * 把输入路径解析为绝对路径；越界（cwd 子树之外、`..` 上跳、cwd 本身除外）
- * 直接抛 "scan path out of scope"——与「密码不进上下文」同级别的红线。
+ * 把输入路径解析为绝对路径；越界（anchor 子树之外、`..` 上跳）直接抛
+ * "scan path out of scope"——与「密码不进上下文」同级别的红线。
+ *
+ * anchor 必须由调用方显式传入「会话工作目录」（pi 的 `ctx.cwd`），不能取 `process.cwd()`：
+ * 扩展与 pi 主进程同进程，`process.cwd()` 是**宿主进程的 OS cwd**。pi-web 下宿主 cwd 是
+ * pi-web 包目录、TUI 下是 pi 的启动目录，都与会话 cwd 不同源（会话 cwd 存在 session header
+ * 里，`/resume` 后可与启动目录不同）。锚错对象的后果是双向的：
+ *   - fail-closed：项目路径全被拒（pi-web 下的必然结果）；
+ *   - fail-open：宿主 cwd 子树反而被放行——红线保护了不相干的目录树。
+ * 因此锚点只能来自 `ctx.cwd`，绝不能由模型传入的 input 反推。
+ *
+ * 判定分两道：
+ *   ① 字面路径必须在 anchor 子树内（拦 `..` 上跳与绝对路径）；
+ *   ② **真实路径**（realpath）也必须在 anchor 的真实路径子树内——字面合法 ≠ 真实位置合法：
+ *      仓库里一个 `dbconf -> /etc` 的软链会让 abs 字面在子树内、真实位置在外（仅比对
+ *      「root 的 realpath 与其子项」会让软链扫描根自我授权）。两端都取 realpath 再比对，
+ *      因此「项目本身位于软链路径下」（如 macOS `/tmp → /private/tmp`）不会被误伤。
  */
-export function resolveRoot(input: string): string {
-  const cwd = process.cwd();
+export function resolveRoot(input: string, anchor: string): string {
+  const cwd = resolve(anchor);
   const abs = isAbsolute(input) ? resolve(input) : resolve(cwd, input);
   const rel = relative(cwd, abs);
-  if (rel.startsWith("..") || isAbsolute(rel)) {
-    throw new Error(`scan path out of scope: ${input}`);
+  // 注意：不能写 rel.startsWith("..")——cwd 内合法的 `..foo/` 也会命中前缀，属假阳性误杀
+  if (rel === ".." || rel.startsWith(".." + sep) || isAbsolute(rel)) {
+    throw new Error(`scan path out of scope: ${input}（允许根目录: ${cwd}）`);
+  }
+  let anchorReal: string;
+  try { anchorReal = realpathSync(cwd); } catch { throw new Error(`scan anchor does not exist: ${cwd}`); }
+  let absReal: string;
+  try { absReal = realpathSync(abs); } catch { throw new Error(`scan path does not exist: ${input}`); }
+  if (!within(anchorReal, absReal)) {
+    throw new Error(`scan path out of scope: ${input}（真实路径 ${absReal} 不在允许根目录 ${anchorReal} 子树内）`);
   }
   return abs;
 }
 
-/** 递归收集文本候选文件（忽略无关目录与隐藏目录，上限 MAX_FILES）；配置类文件单独收集不被挤占 */
-export function walk(root: string): string[] {
+export interface WalkResult {
+  files: string[];
+  /** 是否有目录未展开（超 MAX_DEPTH 深度上限或 MAX_DIRS 目录预算），静默截断会让模型误判「项目里没有更深的配置」 */
+  depthCapped: boolean;
+}
+
+/** 递归收集文本候选文件（上限 MAX_FILES）；配置类文件单独收集不被挤占。
+ * 与 v1.3.1 的行为差异：
+ *   ① 不再跳过 `.` 开头的目录（`.config/db.yml` 这类配置此前永远扫不到），改为靠 IGNORED_DIRS 排噪；
+ *   ② 软链不再静默忽略：目标 realpath 在 root 子树内则按真实类型访问（拦越界逃逸）；
+ *   ③ 深度超限不再静默：通过 depthCapped 如实上报；
+ *   ④ 输出确定：目录项排序 + 只用祖先链断环（不做全局 realpath 去重），
+ *      真目录与软链别名两条路径都保留，不随文件系统的 readdir 顺序变化。*/
+export function walk(root: string): WalkResult {
   const out: string[] = [];
   const configs: string[] = [];
-  const visit = (dir: string, depth: number): void => {
-    // 不因 out 满而提前返回：必须走完整棵树，否则后遍历到的目录里的配置文件永远收不到
-    if (depth > MAX_DEPTH) return;
+  let rootReal = resolve(root);
+  try { rootReal = realpathSync(root); } catch { /* root 不存在时由 readdir 兜底 */ }
+  let depthCapped = false;
+  let dirsVisited = 0;
+
+  const push = (path: string, isConfig: boolean): void => {
+    if (isConfig) {
+      if (configs.length < MAX_FILES) configs.push(path);
+    } else if (out.length < MAX_FILES) {
+      out.push(path);
+    }
+  };
+
+  /**
+   * ancestors 只装「当前遍历路径上」的目录 realpath，用于断环，**不做全局去重**：
+   * 全局去重会让真目录与软链别名按 readdir 顺序互相吞掉（谁先遍历到谁赢），
+   * 同一项目因此在 APFS/ext4 上产出不同的文件树——别名路径照样要走，只是不能成环。
+   */
+  const visit = (dir: string, depth: number, ancestors: ReadonlySet<string>): void => {
+    if (depth > MAX_DEPTH || dirsVisited >= MAX_DIRS) { depthCapped = true; return; }
+    let real: string;
+    try { real = realpathSync(dir); } catch { return; }
+    if (ancestors.has(real)) return;   // 软链环（a/self -> a）：断环即可
+    dirsVisited++;
+    const next = new Set(ancestors);
+    next.add(real);
     let entries: Dirent[];
     try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    // readdir 顺序随文件系统而变（APFS 插入序 / ext4 哈希序），排序后文件树才是确定的
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
     for (const e of entries) {
       if (IGNORED_DIRS.has(e.name)) continue;
-      if (e.isDirectory() && e.name.startsWith(".")) continue;
       const p = join(dir, e.name);
-      if (e.isDirectory()) visit(p, depth + 1);
-      else if (e.isFile()) {
-        try {
-          if (statSync(p).isFile()) {
-            if (isConfigFile(e.name)) {
-              if (configs.length < MAX_FILES) configs.push(p);
-            } else if (out.length < MAX_FILES) {
-              out.push(p);
-            }
-          }
-        } catch { /* ignore */ }
-      }
+      if (e.isDirectory()) { visit(p, depth + 1, next); continue; }
+      if (e.isFile()) { push(p, isConfigFile(e.name)); continue; }
+      // 软链：readdir 的 Dirent 对软链 isDirectory/isFile 均为 false，需按 realpath 判定。
+      // 指向 root 子树之外的一律忽略——扫描目录树不能成为越界的第二个入口。
+      if (!e.isSymbolicLink()) continue;
+      let target: string;
+      try { target = realpathSync(p); } catch { continue; }
+      if (!within(rootReal, target)) continue;
+      let targetIsDir = false, targetIsFile = false;
+      try {
+        const st = statSync(target);
+        targetIsDir = st.isDirectory();
+        targetIsFile = st.isFile();
+      } catch { continue; }
+      if (targetIsDir) visit(p, depth + 1, next);
+      // 软链文件名可能不带配置后缀（.env 被链接成 env.local）：名字与目标名任一像配置就按配置收
+      else if (targetIsFile) push(p, isConfigFile(e.name) || isConfigFile(basename(target)));
     }
   };
-  visit(root, 0);
-  return [...configs, ...out];
+  visit(root, 0, new Set<string>());
+  return { files: [...configs, ...out], depthCapped };
 }

package/src/core/types.ts

@@ -1,4 +1,5 @@
 // core/types.ts
+import type { SourceTrust } from "./scan/trust.js";
 export type DbTypeId = "postgresql" | "mysql" | "oracle" | "dm"
   | "redis" | "elasticsearch" | "mongodb" | "hive" | "spark" | "neo4j";
 export type DbFamily = "relational" | "kv" | "search" | "document" | "bigdata" | "graph";
@@ -58,6 +59,8 @@ export interface Candidate {
   partial: Partial<ConnConfig>;     // 归一化后的字段（含默认 name）
   missing: string[];                // 待补字段名（incomplete 时）
   source: string;                   // 来源描述
+  /** 来源可信度（插件按确定性规则从模型自述的 source 评估，供展示，不影响 status；不是独立取证） */
+  trust: SourceTrust;
   warnings?: string[];
 }
 

package/src/dialects/dm.ts

@@ -80,10 +80,12 @@ class DmDialect extends RelationalDialect {
   protected async doExecute(client: unknown, stmt: string, opts: ExecOpts): Promise<{ columns: string[]; rows: unknown[][]; rowCount: number }> {
     const dmConn = client as dmdb.Connection;
     const maxRows = opts.maxRows;
+    // 上游 dmdb 的 ExecuteOptions 未声明 maxRows/fetchArraySize（运行时可接受或被忽略）；
+    // 结果另有下方 .slice(0, maxRows) 兜底，故此处仅放宽类型断言，不改运行时行为。
     const res = await dmConn.execute(stmt, [], {
       maxRows,
       fetchArraySize: maxRows,
-    });
+    } as dmdb.ExecuteOptions);
     if (res.metaData && res.metaData.length > 0) {
       const columns = res.metaData.map((m: any) => m.name);
       const rows = (res.rows ?? []).slice(0, maxRows).map((r: any) => [...r]);
@@ -95,7 +97,8 @@ class DmDialect extends RelationalDialect {
   async versionQuery(conn: DbConnection): Promise<string> {
     const dmConn = conn.client as dmdb.Connection;
     const res = await dmConn.execute("SELECT * FROM V$VERSION");
-    return (res.rows ?? [])[0]?.[0] as string ?? "unknown";
+    const rows = (res.rows as unknown[][] | undefined) ?? [];
+    return (rows[0]?.[0] as string | undefined) ?? "unknown";
   }
 
   async listTables(config: ConnConfig, pattern?: string): Promise<ListTablesResult> {

package/src/dialects/elasticsearch.ts

@@ -144,7 +144,7 @@ class ElasticsearchDialect extends SearchDialect {
     }
   }
 
-  protected async doSearch(client: unknown, config: ConnConfig, sql: string, kind: DslKind, opts: ExecOpts): Promise<{ columns: string[]; rows: unknown[][]; rowCount: number }> {
+  protected async doSearch(client: unknown, config: ConnConfig, sql: string, kind: DslKind, opts: ExecOpts): Promise<{ columns: string[]; rows: unknown[][]; rowCount: number; truncated?: boolean }> {
     const es = client as ClientV8;
     const index = config.database;
     if (!index) throw new Error("ES 连接缺少默认 index（database 字段）");
@@ -160,14 +160,20 @@ class ElasticsearchDialect extends SearchDialect {
       if (kind.endpoint === "_count") {
         const res = await es.count({ index });
         const count = (unwrap(res) as unknown as { count?: number }).count ?? 0;
-        return { columns: ["count"], rows: [[count]], rowCount: count };
+        // rowCount 为“取回行数”（1 行 = 计数值本身），实际计数在单元格里，避免“返回 88 行”却只给一行的误读
+        return { columns: ["count"], rows: [[count]], rowCount: 1 };
       }
       if (kind.endpoint === "_mget") {
-        const res = await es.mget({ index, body: { docs: [] } });
+        // 注：_mget 需兼容 v7 客户端的 body 形态（本文件为 v7/v8/v9 三客户端分发），
+        // 而 v8/v9 的类型已把请求体改为顶层 docs，故按运行时通用形态传参并放宽参数类型。
+        const res = await es.mget({ index, body: { docs: [] } } as unknown as Parameters<ClientV8["mget"]>[0]);
         return docsToRows(unwrap(res));
       }
-      // _search：DSL 整体即 body
-      const res = await es.search({ index, body, size: opts.maxRows });
+      // _search：DSL 整体即 body；body 显式带数字 size 时不再注入顶层 size
+      // （尊重调用方分页与 size:0 纯聚合意图，否则顶层 size 会覆盖 body.size 使聚合退化为普通搜索）
+      const searchParams: Record<string, unknown> = { index, body };
+      if (typeof (body as { size?: unknown } | undefined)?.size !== "number") searchParams.size = opts.maxRows;
+      const res = await es.search(searchParams as Parameters<ClientV8["search"]>[0]);
       return hitsToRows(unwrap(res));
     }
     throw new Error(`ES 写端点 ${kind.endpoint} 需走非只读确认流程执行，本方言 executeOn 仅执行读查询`);
@@ -233,12 +239,48 @@ class ElasticsearchDialect extends SearchDialect {
 }
 
 // ── 结果转换 ──────────────────────────────
-function hitsToRows(res: unknown): { columns: string[]; rows: unknown[][]; rowCount: number } {
-  const body = res as { hits?: { total?: number | { value?: number }; hits?: Array<{ _id?: string; _source?: unknown }> } };
+interface EsHitsBody {
+  hits?: { total?: number | { value?: number }; hits?: Array<{ _id?: string; _source?: unknown }> };
+  aggregations?: Record<string, unknown>;
+}
+
+/** 搜索响应 → 行；纯聚合查询（无命中 + aggregations）展开为聚合行，命中存在时保持文档视图 */
+export function hitsToRows(res: unknown): { columns: string[]; rows: unknown[][]; rowCount: number; truncated?: boolean } {
+  const body = res as EsHitsBody;
   const hits = body.hits?.hits ?? [];
   const total = typeof body.hits?.total === "number" ? body.hits.total : (body.hits?.total?.value ?? hits.length);
+  if (hits.length === 0 && body.aggregations !== undefined
+    && body.aggregations !== null && typeof body.aggregations === "object") {
+    return aggsToRows(body.aggregations);
+  }
   const rows = hits.map((h) => [h._id, typeof h._source === "object" ? JSON.stringify(h._source) : h._source]);
-  return { columns: ["_id", "_source"], rows, rowCount: typeof total === "number" ? total : hits.length };
+  const rowCount = typeof total === "number" ? total : hits.length;
+  // total 为服务端统计（可能是 gte 下限），大于取回行数即已截断（供工具层提示与导出）
+  return { columns: ["_id", "_source"], rows, rowCount, truncated: rowCount > rows.length };
+}
+
+/** 聚合结果 → 行：列 [aggregation, key, doc_count, value]；metric 取值，桶内子聚合折叠为 value 列 JSON */
+export function aggsToRows(aggs: Record<string, unknown>): { columns: string[]; rows: unknown[][]; rowCount: number } {
+  const rows: unknown[][] = [];
+  for (const [name, agg] of Object.entries(aggs)) {
+    if (agg === null || typeof agg !== "object") { rows.push([name, null, null, agg ?? null]); continue; }
+    const buckets = (agg as { buckets?: unknown }).buckets;
+    if (Array.isArray(buckets)) {
+      for (const b of buckets) {
+        if (b === null || typeof b !== "object") { rows.push([name, b, null, null]); continue; }
+        const bucket = b as Record<string, unknown>;
+        const key = bucket.key_as_string ?? bucket.key ?? null;
+        const docCount = typeof bucket.doc_count === "number" ? bucket.doc_count : null;
+        const extra = Object.entries(bucket).filter(([k]) => k !== "key" && k !== "key_as_string" && k !== "doc_count");
+        rows.push([name, key, docCount, extra.length > 0 ? JSON.stringify(Object.fromEntries(extra)) : null]);
+      }
+      continue;
+    }
+    const metric = agg as { value?: unknown; value_as_string?: unknown };
+    if ("value" in metric) { rows.push([name, null, null, metric.value_as_string ?? metric.value ?? null]); continue; }
+    rows.push([name, null, null, JSON.stringify(agg)]);
+  }
+  return { columns: ["aggregation", "key", "doc_count", "value"], rows, rowCount: rows.length };
 }
 
 function docsToRows(res: unknown): { columns: string[]; rows: unknown[][]; rowCount: number } {

package/src/dialects/hive.ts

@@ -61,7 +61,9 @@ class HiveDialect extends BigDataDialect {
   }
 
   protected async doConnect(config: ConnConfig, timeoutMs: number): Promise<DbConnection> {
-    const client = new hive.HiveClient(TCLIService, TCLIService_types);
+    // 上游 hive-driver 的 TCLIServiceTypes 声明不完整（缺 25 个请求类型），与其运行时实际
+    // 使用的 thrift 定义不一致；仅放宽类型断言，运行时对象未做任何改动。
+    const client = new hive.HiveClient(TCLIService, TCLIService_types as any);
     await client.connect(
       { host: config.host ?? "localhost", port: config.port ?? DEFAULT_PORT },
       new hive.connections.TcpConnection(),

package/src/dialects/mysql.ts

@@ -109,9 +109,11 @@ class MysqlDialect extends RelationalDialect {
     try {
       const tables = await this.withConnection(config, async (conn) => {
         const mysqlConn = conn.client as mysql.Connection;
+        // config.database 为可选（ConnConfig），而 mysql2 的 ExecuteValues 不接受 undefined 元素；
+        // 此处仅放宽类型断言，运行时参数与既有行为完全一致。
         const [rows] = await mysqlConn.execute(
           "SELECT TABLE_NAME, TABLE_TYPE, TABLE_COMMENT FROM information_schema.TABLES WHERE TABLE_SCHEMA = ? ORDER BY TABLE_NAME",
-          [config.database],
+          [config.database] as any[],
         );
         const all = (rows as any[]).map((r: any) => ({
           schema: "",
@@ -149,7 +151,7 @@ class MysqlDialect extends RelationalDialect {
         try {
           const [commentRows] = await mysqlConn.execute(
             "SELECT COLUMN_NAME, COLUMN_COMMENT FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?",
-            [config.database, table],
+            [config.database, table] as any[],
           );
           const commentMap = new Map((commentRows as any[]).map((r: any) => [r.COLUMN_NAME, r.COLUMN_COMMENT]));
           for (const col of cols) {

package/src/dialects/neo4j.ts

@@ -270,7 +270,7 @@ class Neo4jDialect extends GraphDialect {
             const f = r._fields ?? [];
             const types = f[3] as string[] | null;
             if (!Array.isArray(types) || !types.includes(graphName)) continue;
-            indexLines.push(`${f[0]}(${f[1]}, ${f[5] ?? "online"}) ON ${isRel ? "rel" : "node"}(${types.join(":")}).(${(f[4] ?? []).join(",")})`);
+            indexLines.push(`${f[0]}(${f[1]}, ${f[5] ?? "online"}) ON ${isRel ? "rel" : "node"}(${types.join(":")}).(${((f[4] ?? []) as string[]).join(",")})`);
           }
         } catch { /* SHOW 失败降级 */ }
         try {
@@ -281,7 +281,7 @@ class Neo4jDialect extends GraphDialect {
             const types = f[3] as string[] | null;
             if (!Array.isArray(types) || !types.includes(graphName)) continue;
             for (const p of (f[4] ?? []) as string[]) if (String(f[1]).toUpperCase().includes("UNIQUE")) uniqueProps.add(p);
-            indexLines.push(`${f[0]}(${f[1]}) ON ${types.join(":")}.(${(f[4] ?? []).join(",")})`);
+            indexLines.push(`${f[0]}(${f[1]}) ON ${types.join(":")}.(${((f[4] ?? []) as string[]).join(",")})`);
           }
         } catch { /* 降级 */ }
 

package/src/dialects/oracle.ts

@@ -1,7 +1,7 @@
 // src/dialects/oracle.ts
 import oracledb from "oracledb";
 import type { ConnConfig, DbConnection, ExecOpts, ParsedTarget,
-  ListTablesResult, DescribeTableResult, ColumnInfo, TestConnectionResult } from "../core/types.js";
+  ListTablesResult, DescribeTableResult, TableInfo, ColumnInfo, TestConnectionResult } from "../core/types.js";
 import { RelationalDialect } from "./relational-dialect.js";
 import { register, filterTables, type Fingerprints } from "./dialect.js";
 
@@ -107,7 +107,9 @@ class OracleDialect extends RelationalDialect {
            WHERE T.OWNER NOT IN ('SYS', 'SYSTEM', 'DBSNMP', 'XDB')
            ORDER BY T.OWNER, T.TABLE_NAME`,
         );
-        const all = (res.rows ?? []).map((r: any) => ({
+        // 显式标注 TableInfo[]：oracledb 无类型声明，res.rows 退化为 any，若不标注则
+        // filterTables 的泛型会回退到约束 { name; schema? }，丢失 type/description 两个字段。
+        const all: TableInfo[] = (res.rows ?? []).map((r: any) => ({
           schema: r[1],
           name: r[0],
           type: "TABLE",

package/src/dialects/redis.ts

@@ -93,9 +93,13 @@ class RedisDialect extends KvDialect {
         let sampled = 0;
         let cursor = "0";
         // LIKE（%/_）→ SCAN 通配（*/?），全局替换（String.replace 单次替换是 bug）
-        const matchArgs = pattern ? ["MATCH", pattern.split("").map((ch) => ch === "%" ? "*" : ch === "_" ? "?" : ch).join("")] : [];
+        const scanPattern = pattern ? pattern.split("").map((ch) => ch === "%" ? "*" : ch === "_" ? "?" : ch).join("") : null;
         do {
-          const [next, keys] = await redis.scan(cursor, "COUNT", 100, ...matchArgs);
+          // ioredis 的 scan 重载要求 MATCH/COUNT 固定次序，不能靠 spread 拼参；
+          // Redis 的 SCAN 命令本身不区分参数顺序，故两个分支与原来的命令语义完全一致。
+          const [next, keys] = scanPattern
+            ? await redis.scan(cursor, "MATCH", scanPattern, "COUNT", 100)
+            : await redis.scan(cursor, "COUNT", 100);
           cursor = next;
           for (const key of keys) {
             if (sampled >= 200) break;
@@ -166,7 +170,8 @@ class RedisDialect extends KvDialect {
           } else if (type === "set") {
             preview = JSON.stringify(await redis.smembers(key)).slice(0, 200);
           } else if (type === "zset") {
-            preview = JSON.stringify(await redis.zrange(key, 0, 9, "WITHSCORES")).slice(0, 200);
+            // ioredis 6 的 zrange 重载把 stop 声明为 string|Buffer（漏了 number）；索引 "9" 与数字 9 等价。
+            preview = JSON.stringify(await redis.zrange(key, 0, "9", "WITHSCORES")).slice(0, 200);
           }
         } catch { /* ignore */ }
         return [

package/src/dialects/relational-dialect.ts

@@ -56,7 +56,10 @@ export abstract class RelationalDialect implements Dialect {
       await this.withConnection(config, async (conn) => {
         for (const s of stmts) last = await this.doExecute(conn.client, s, opts);
       }, opts.timeoutSec * 1000);
-      return { success: true, ...last, duration: `${Date.now() - start}ms` };
+      // 结果集被 maxRows 截断时标注（各行返回 rowCount=服务端完整行数、rows 已按 maxRows 截取）；
+      // 仅对结果集（有列）判定，写操作 rows 为空而 rowCount=影响行数，不得误标
+      const truncated = last.columns.length > 0 && last.rowCount > last.rows.length;
+      return { success: true, ...last, truncated, duration: `${Date.now() - start}ms` };
     } catch (err: unknown) {
       return { success: false, error: err instanceof Error ? err.message : String(err), duration: `${Date.now() - start}ms` };
     }

package/src/dialects/spark.ts

@@ -58,7 +58,8 @@ class SparkDialect extends BigDataDialect {
   }
 
   protected async doConnect(config: ConnConfig, timeoutMs: number): Promise<DbConnection> {
-    const client = new hive.HiveClient(TCLIService, TCLIService_types);
+    // 同 hive.ts：上游 hive-driver 的 TCLIServiceTypes 声明不完整，仅放宽类型断言，不动运行时。
+    const client = new hive.HiveClient(TCLIService, TCLIService_types as any);
     await client.connect(
       { host: config.host ?? "localhost", port: config.port ?? DEFAULT_PORT },
       new hive.connections.TcpConnection(),