dsh-dbpulse

English | 中文

一个为 dsh 增加「数据库监控」agent 模式 + 专业监控面板的插件:「数据库监控模式」(dbpulse)agent preset、随包自带的 db-monitor 技能,以及挂载在 Web 客户端的实时监控面板(会话头部脉冲图标打开)。定位是引擎无关的数据库运行监控、性能诊断与故障排查:内置 MySQL、PostgreSQL、SQLite、SQL Server、MongoDB 和 Redis 六个引擎支持;采集全程宿主侧只读,凭据不越界。插件由两个官方 dsh 机制组成:

• cordis.patch.yml —— profile bundle patch,由 manifest 的 dsh.bundle.patch 字段声明。它插入两行:挂载监控服务的 host 平面插件,以及声明「数据库监控模式」的 @deepseek-ai/dsh-agent-preset。
• skills/db-monitor/ —— preset 挂载的技能,随包发布,挂载时从已安装的 dsh-dbpulse 包内解析。

自 harness 0.2 起,agent preset 是由 bundle patch 携带的声明,不再是目录:旧的 $DSH_HOME/.agent-presets/<id>/(preset.yml + agent.cordis.yml)已无任何代码读取,因此上面的 patch 是该模式的唯一事实来源。

监控面板通过浏览器访问宿主侧 dbpulse TypertRemote 服务:连接配置持久化在 $DSH_HOME/.dbpulse/(密码仅存宿主侧,不回传客户端),指标采集全部走宿主侧数据库驱动(mysql2/pg/mssql/node:sqlite/mongodb/redis)直连,不依赖本地客户端二进制文件;agent 侧则由随 preset 挂载的 dbpulse_* 工具(driver-based 只读工具)完成采集,零外部依赖。

引擎支持

| 引擎 | 健康快照 | 会话 | 锁等待 | 慢查询 | 复制 | EXPLAIN | 容量页 | 控制台 | | --- | :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: | | MySQL | ✅ | ✅ | ✅ | ✅ perf schema | ✅ replication | ✅ standard | ✅ information_schema | ✅ SQL | | PostgreSQL | ✅ | ✅ | ✅ | ⚠️ pg_stat_statements | ✅ pg_stat_replication | ✅ ANALYZE BUFFERS | ✅ pg_database_size | ✅ SQL | | SQL Server | ✅ | ✅ sys.dm_exec_* | ✅ blocking_session_id | ⚠️ dm_exec_query_stats | ✅ AG replicas | ✅ SHOWPLAN_ALL | ✅ master_files | ✅ SQL | | SQLite | ✅ PRAGMA | — (嵌入式) | — | — | — | ✅ QUERY PLAN | ✅ 文件大小 | ✅ SQL | | MongoDB | ✅ serverStatus | ✅ currentOp | — | ⚠️ Profiler 开启时 | ✅ replSetGetStatus | — | ✅ listDatabases+dbStats | — | | Redis | ✅ INFO | ✅ CLIENT LIST | — | ✅ SLOWLOG GET | ✅ INFO replication | — | ⚠️ DBSIZE 键数 | ⚠️ 只读命令白名单 |

安装

一条命令,官方 profile 插件安装:

dsh plugin --profile web add dsh-dbpulse

bundle 的 patch 插入两行,让模式与面板端到端可用:

• dbpulse —— bundle 主插件(包默认入口 lib/index.js),注册 dbpulse TypertRemote 服务供浏览器面板调用。
• preset-dbpulse —— @deepseek-ai/dsh-agent-preset 声明,把「数据库监控模式」发布到会话模式选择器;选择该模式的 agent 会挂载 dbpulse_* 驱动工具与 db-monitor 技能。

说明:

• 命令按 profile 生效:每个需要提供「数据库监控模式」的 profile 都要执行一次。preset 由已安装包的 patch 声明,而非复制进用户目录的文件,插件升级后下次启动即生效。
• 技能从已安装的 dsh-dbpulse 包(skills/)读取,升级随包发布技能变更;没有需要同步的目录,也没有可手改的落盘文件。
• 本插件有运行时依赖:peerDependencies 全部为 workspace:^ 的 harness 包(cordis、dsh-typert-protocol、dsh-subprocess、dsh-client-* 等),registry / file: / 本地 link: 安装时由 pnpm workspace 或 peer 解析提供;构建工具链(typescript、tsdown、vitest、react 类型)在 devDependencies。
• 想定制该模式,可把该行拷进自己的 profile patch 并按 id 覆盖 preset-dbpulse:覆盖会整块替换该行的 config,因此需完整重述 id、name、description、order 与 plugins。

监控面板

会话头部点击数据库脉冲图标打开监控面板。面板采用多页面布局:左侧导航按「概览 / 工具 / 监控 / 管理」分组,首页仪表盘聚焦整体状态,每个细化功能都有独立页面,并附带一个只读 SQL 控制台,可当作轻量数据库管理软件使用:

• 仪表盘(首页):整体状态条、健康检查、连接数/缓存命中/吞吐/慢查询四张水位卡片与趋势图、触发告警的阈值横幅、容量 TOP 概览。
• SQL 查询:只读 SQL 控制台(SELECT / SHOW / DESCRIBE / EXPLAIN / WITH),⌘/Ctrl+Enter 执行,结果表格化展示(行数封顶、超限截断提示),支持一键导出 CSV;写入类语句被宿主侧直接拒绝。
• 连接管理:新建/编辑/删除数据库连接配置(引擎、主机、端口、库、用户、密码),密码仅存宿主侧($DSH_HOME/.dbpulse/connections-v1.json),面板不回显;每个连接可一键探活,显示服务器版本与延迟。落盘的连接/阈值/历史文件(含密码)会以 0600 权限写入,请确保 $DSH_HOME/.dbpulse/ 目录本身仅当前用户可读。
• 关键指标:全部指标卡片按类别(连接/缓存/性能/锁/复制/其他)分页展示。
• 会话:按运行时长排序的活跃会话表(SQL 截断展示),支持 CSV 导出。
• 慢查询:慢查询 TOP(MySQL 走 performance_schema 摘要,PostgreSQL 走 pg_stat_statements,未启用时明确标注),点击行一键填入 EXPLAIN 并出执行计划。
• 锁等待:被阻塞/阻塞链、等待时长与语句。
• 复制状态:副本/通道的 IO 与回放状态、延迟秒数。
• 容量:各库/表空间大小与占比堆叠条,支持 CSV 导出。
• 告警阈值:每个连接独立的预警/高危阈值编辑(连接使用率、缓存命中率、复制延迟),保存后仪表盘立即重新着色。
• 自动刷新:关闭/10s/30s/60s 四档,手动刷新随时可用。

面板数据全部来自宿主侧只读采集,采集失败会逐项降级并在面板备注区说明,不会整屏报错。

使用

两种入口互补:会话模式选择器里的「数据库监控模式」是 agent 对话式诊断,会话头部的脉冲图标是可视化面板。对话式诊断示例:

• 「帮我体检一下这台 MySQL,看看有没有隐患」
• 「分析一下最近最慢的 20 条查询,给优化建议」
• 「PostgreSQL 连接数打满了,排查一下」
• 「看看有没有锁等待,谁在阻塞谁」

驱动库已声明为项目依赖;插件连接全走宿主侧驱动直连,无需 shell 调用本地客户端。凭据仅存在服务端,永不外泄。agent 侧通过预设挂载的 dbpulse_* 工具族(driver-based 只读工具)完成任务,无需目标库安装任何客户端。

模型体验

preset 贡献模型可见的文本与工具:persona(带只读优先与危险操作确认纪律的数据库运维专家身份)、目录中的 db-monitor 技能,以及技能采集所用的 dbpulse_* 驱动工具族(dsh-dbpulse/tools)。其余与标准模式一致(shell、filesystem、web、skills、goals、subagents、workflows);诊断能力来自技能的检查项工作流,通过上述驱动工具执行,而不是 shell 调用部署环境的数据库客户端。这些工具调用与提示段落与其他任何 preset 的贡献一样,可从会话日志重建。

KV Cache 影响

无直接影响;preset 各行的效果由其所属包负责。

已知限制与暂缓事项

• 无需本地客户端。 驱动库(mysql2/pg/mssql/node:sqlite/mongodb/redis)已声明依赖;插件采集全程走宿主侧驱动直连,不依赖部署环境安装数据库客户端。凭据仅存服务端,从不回传。
• 非 SQL 引擎能力受限: MongoDB 不支持 SQL 控制台和锁等待页;Redis 只支持受控的只读命令白名单(如 GET/SCAN/INFO/SLOWLOG),而非任意 SQL。但它们的会话与容量页面仍能展示有价值的运行时信息。
• 扩展依赖目标库启用。 如 pg_stat_statements 等扩展需目标库启用,技能会先探测可用性,未启用时给出启用方式而非跳过分析。
• bundle 按 profile 安装。 每个需要提供「数据库监控模式」的 profile 都要执行安装命令;preset 本身是全局的。
• 暂不包含定时采集与告警。 当前定位是会话内的按需监控与诊断;周期巡检、指标持久化与告警推送留待后续版本(可作为独立服务插件演进)。