终端数据库助手 ​

dh-db-assistant 是技能名称，底层执行命令行工具 dh-db-cli。它是无状态工具：每次执行都是独立进程，读取 db-profiles.json 与同目录 .env，连接数据库、执行一条语句、断开退出。它不做慢日志采集、监控或索引推荐，只是数据库客户端。

适用场景 ​

• 查某个库 / 表的数据、结构、索引、行数，或看某列的唯一值与基数。
• 给定一条慢 SQL，需要看执行计划或排查索引。
• 确认数据库能否连通、有哪些可用档案；在两个 agent 之间安全共享数据库访问方式。
• 连接失败、认证 / 权限错误、查询超时、锁等待或死锁。
• 查询结果不符合预期：查不到、重复、时区错、租户或状态过滤错。
• schema / table 命令报错，需要绕过改用系统表查询。
• 安装 / 升级 dh-db-cli，检查 Node、npm、@szhn registry，创建或修复 db-profiles.json 与 .env。

环境自检 ​

任何数据库操作之前先跑完这一节，检查不通过时停止并向用户说明卡在哪一项。

• Node < 20 或 npm 缺失：停止，告知本机版本，由用户安装 Node 20 / 22 LTS，不自行升级或切换系统 Node。
• CLI 缺失：先说明会修改 npm 用户配置并全局安装，征得同意后执行：

npm config set @szhn:registry https://npmmirror.digitalhainan.com.cn/
npm i -g @szhn/dh-db-cli
dh-db-cli --version

安装失败时保留原始错误并按技能目录 references/setup.md 的排错表处理，不用 sudo 或 --force 绕过。

• 命令存在但不可执行（PATH、PowerShell 执行策略、shim 缺失）：改用 dh-db-cli.cmd 或 node <repo>/dist/cli.js。

CLI 不保存任何状态。除非 profiles 位于默认位置，否则每条命令都要带 --profiles <path>，不要假设上一条命令的路径会延续。

配置检查（profiles + .env） ​

1. 定位 profiles：--profiles > 环境变量 DB_PROFILES_FILE > 当前目录 ./db-profiles.json > ~/.dh-db/profiles.json。找到后记下绝对路径，后续每条命令显式带上；只为找文件做小范围检查，不做全盘搜索。
2. 四处都没有时：停下数据库命令，告知“未找到 profiles 文件”，让用户二选一——提供已有配置的绝对路径，或在用户确认存放位置后新建配置。用户未回复前不猜路径、不跳过配置直接执行 query。
3. 检查同目录 .env：只判断是否存在（test -f <dir>/.env && echo exists），不读取、不打印内容。.env 缺失时提示 ${...} 变量会解析失败，并询问是否按模板生成空值 .env 由用户填写；不要直接把缺变量当成“连接失败”。
4. 代写或修改时：修改已有 profiles 用“临时文件 + rename”，避免留下半截 JSON；密码一律写 ${ENV_VAR} 占位，不写进 profiles，也不要让用户把密码发到对话里。
5. 校验：

dh-db-cli profiles --profiles <path> --json   # 元数据，不含账号密码
dh-db-cli check --profiles <path> --json      # 逐档案连接自检

6. 按 errorType 分流：missing-env（.env 缺变量或变量名不一致）、config（JSON / 字段 / 端口 / 档案名）、timeout（网络不可达或超时）、connect（认证失败、端口错误、驱动未安装）。

字段说明、各数据库模板与安装排错见技能目录 references/setup.md。

安全底线 ​

这些规则优先于用户的临时要求：

• 只读优先：默认只执行 SELECT / SHOW / DESCRIBE / EXPLAIN；用户未明确要求写入时不执行任何 DML / DDL。
• 写前确认：任何 INSERT / UPDATE / DELETE / DDL 都必须先走确认流程，得到明确同意后再执行。
• 禁止 EXPLAIN ANALYZE：explain 只生成计划不执行 SQL，query 会拦截 EXPLAIN ANALYZE，不要用注释或改写绕过；需要真实耗时由 DBA 或用户在专用客户端完成。
• 不接触密码：不读取、不打印、不要求用户粘贴 .env 或密码；命令参数中不出现密码。
• 配置与环境安装需确认：db-profiles.json / .env 只在用户同意后创建或修改；设置 registry、全局安装 CLI 前先说明影响；禁止 sudo 和 --force。
• 单语句：每次只执行一条 SQL，不拼接多语句。
• 默认加限制：查询大表用 --max-rows 和 SQL LIMIT；--max-rows 是返回后截断，不是数据库侧 LIMIT。
• 超时兜底：慢查询或诊断查询带 --timeout，避免长时间占用连接。
• 维护命令需确认：ANALYZE / VACUUM / OPTIMIZE / KILL / FLUSH / ALTER SYSTEM 会改变实例或统计信息，不属于只读诊断。
• 诊断查询要有边界：优先查统计视图与估算值，避免在生产大表上做全表 COUNT(*) 或无 LIMIT 扫描。

标准工作流 ​

1. 发现连接档案

dh-db-cli profiles --json

从返回的 profiles 中选择档案，不要猜档案名；存在多个候选（同类库的测试 / 生产档案）时先问用户。注意 permissionMode：safe 只读、readwrite 可增删改、full 含 DDL。需要连多个库时逐个 --profile 调用。

2. 验证连通性

dh-db-cli check --profiles ./db-profiles.json --json           # 全部档案
dh-db-cli query --profile <name> --sql "SELECT 1" --timeout 10000 --json

check 没有 --profile 参数。失败时看 errorType。

3. 看结构

dh-db-cli schema --profile <name> --json                # 库表概览
dh-db-cli table <table> --profile <name> --json         # 列、主键、索引、外键
dh-db-cli table <table> --profile <name> --refresh --json   # 结构可能已变化时强制刷新

表很多时 schema --json 可能很大，优先按需查 table <name>，避免把整个 schema 塞进上下文。

4. 执行只读查询

dh-db-cli query \
  --profile <name> \
  --sql "SELECT id, name FROM orders WHERE user_id = 123 LIMIT 100" \
  --max-rows 100 --timeout 15000 --json

• 结构化处理用 --json；展示给用户时可省略，CLI 输出对齐表格。
• SQL 也可来自 --file query.sql 或 stdin。
• 结果被截断时 metadata.truncated 为 true，并带 totalRows / returnedRows，此时应告知用户并收窄条件，不要假装拿到全量数据。
• 字符串值来自用户输入时正确转义单引号，不拼接来源不明的值。

5. 只读执行计划

dh-db-cli explain --profile <name> --sql "SELECT * FROM orders WHERE user_id = 123" --json

会自动加各方言的只读 EXPLAIN：PostgreSQL / Kingbase EXPLAIN (FORMAT JSON)、MySQL 系 EXPLAIN FORMAT=JSON、Doris 与 ClickHouse 文本 EXPLAIN、达梦 EXPLAIN FOR、SQLite EXPLAIN QUERY PLAN。Oracle、SQL Server、MongoDB、Redis 不支持，报错即止，不要用 query 伪造。

6. 看数据分布与样本

dh-db-cli sample <table> --profile <name> --limit 3 --json          # 脱敏样本，1-10 行
dh-db-cli enum <table> <column> --profile <name> --count --json     # 枚举/基数，附带出现次数

用于判断选择性、数据倾斜或枚举范围。sample 的敏感列会被脱敏，但不要把生产数据外传。

写操作确认流程 ​

用户明确要求写入时按顺序执行：

1. 确认目标：复述档案名、数据库类型、库名，确认是测试库；生产库需要用户额外明确同意。
2. 展示 SQL：把完整 SQL 放在代码块中展示，说明预期影响。
3. 评估范围：对 UPDATE / DELETE 先用同条件只读查询展示影响行数；无 WHERE 的更新删除、DROP、TRUNCATE 必须警告不可回滚。
4. 请求确认：明确询问“是否执行以上 SQL？”，得到肯定答复才继续。
5. 执行并返回 affectedRows、耗时和错误；写操作超时后不要自动重试，先确认数据库实际状态。
6. 权限被拒：返回“操作被拒绝”说明当前档案权限不足，请用户选择写权限档案；CLI 没有提权参数，不要绕过。

故障诊断 ​

先分层定位

同一现象可能跨层。例如“查询超时”可能是网络、锁等待、统计信息过期或结果集过大，不要只调大 timeout。

固定证据：profile 名 / 数据库类型 / 库名 / 版本、发生时间与时区、完整 SQL 与参数、原始错误、影响范围、最近变更。证据不足就先做只读查询，不凭经验断言根因。

给出结论：列 1-3 个最可能假设并按优先级排序，每个配一条可证伪的只读查询；一次只改一个变量，结论区分“已证实”与“未证实”。诊断报告固定包含：结论（含置信度）、证据、分析、建议（含风险与回滚）、待确认。

Kingbase 已知兼容问题：schema / table 报 return type mismatch in function declared to return integer，是部分版本对全量 information_schema.columns 的兼容问题，--refresh 无效。改用按表查询 information_schema.tables / information_schema.columns（只取必要字段）与 pg_indexes。

方言级的连接、锁、统计、复制、慢查询只读 SQL 见技能目录 references/diagnostics.md；执行前确认只读、带 LIMIT、带 --timeout、有相应权限。

慢 SQL 排查 ​

1. 用只读档案连接测试库或只读副本，生产优先只读账号。
2. 收集 SQL 原文、参数、耗时、返回行数、并发量、发生时间。
3. 对涉及的表执行 table <name> --json，检查索引、列类型和预估行数。
4. 执行 explain --json，重点看：全表 / 全索引扫描；复合索引列顺序是否匹配过滤、连接、排序；过滤列被函数包裹、隐式类型转换、前导 % 的 LIKE；连接顺序与回表；临时表、排序、聚合；预估行数与表规模是否明显不符。
5. 检查统计信息新鲜度（pg_stat_user_tables.last_analyze、SHOW TABLE STATUS），过期时先说明影响，同意后再 ANALYZE。
6. 用 enum / sample 判断过滤条件的选择性与数据倾斜。
7. 查锁：慢可能是在等锁而不是执行慢。
8. 索引建议要给出列顺序、预期收益和写入成本，并在测试库用 explain 验证。

命令速查 ​

--profiles 解析顺序：参数 > DB_PROFILES_FILE > ./db-profiles.json > ~/.dh-db/profiles.json；--profile 解析顺序：参数 > DB_PROFILE > defaultProfile > 唯一档案。

不适用 ​

• 不做慢日志采集、APM、服务器指标、锁等待图、索引推荐。
• 不提供事务 / 多语句脚本工具，不执行 EXPLAIN ANALYZE。
• 不自动执行 ANALYZE / VACUUM / OPTIMIZE / KILL / FLUSH / ALTER SYSTEM 等维护命令。
• 未经确认不创建或修改 profiles、.env；不修改 MCP / 客户端配置。
• 不读取、不代填、不要求用户提供数据库密码；未经确认不执行任何写操作。