# dbcat

**Repository Path**: AJiangS/dbcat

## Basic Information

- **Project Name**: dbcat
- **Description**: DBCat（Database Cat）是一款跨平台数据库管理工具，支持多种数据库的连接、查询、结构管理、数据编辑与 AI 辅助 SQL。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-11
- **Last Updated**: 2026-09-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DBCat

> 数据库管理桌面客户端 · Go + Wails v2 + Vue 3

## 版本说明

> ⚠️ **本项目是 DBX 的 Go 语言重写修改版**，非官方出品。
>
> 原版软件为 **DBX**，官方网站：<https://dbxio.com/cn>

DBCat（Database Cat）是一款跨平台数据库管理工具，支持多种数据库的连接、查询、结构管理、数据编辑与 AI 辅助 SQL。名字由 **DB**（数据库）+ **Cat**（猫）组成，图标是一只坐在数据库圆柱上的猫。

---

## 功能特性

- **多数据库支持**：MySQL、PostgreSQL、SQLite、Redis、MongoDB 五种驱动；兼容 MariaDB / TiDB / OceanBase / PolarDB / StarRocks / Doris（走 MySQL 驱动）、Kingbase / Vastbase / openGauss / Redshift（走 PostgreSQL 驱动）等；未实现的数据库类型在新建连接对话框中已禁用
- **SQL 编辑器**：CodeMirror 6 语法高亮、自动补全、格式化、查询历史、多标签页
- **AI Agent 集成（AI 控制）**：内置本地 HTTP API（127.0.0.1 + token 认证），供 **DeepSeek Harness / ZCode / Trae** 三类插件分别授权接入——每个 Agent 独立开关与独立令牌（停用即吊销）。用 AI 聊天即可读取连接、浏览 Schema、执行 SQL、增删改查；写操作强制确认。**即使 DBCat 未运行**，DSH 插件也能通过 `dbcat_direct_*` 直接连接 MySQL/PostgreSQL/SQLite/Redis/MongoDB
- **数据网格**：结果集查看、编辑、排序、筛选、导出（Excel / CSV）
- **结构管理**：表结构查看与编辑、索引、外键、DDL、Schema 对比
- **NoSQL 支持**：Redis 键浏览、Mongo 文档浏览与 shell
- **数据工具**：数据导入导出、表数据对比、数据传输、数据库搜索、字段血缘、ER 图
- **安全**：连接密码加密存储、本地 API token 认证

---

## 技术栈

| 层 | 技术 |
|---|---|
| 桌面框架 | Wails v2 (Go) |
| 后端 | Go 1.25，分层结构（`internal/app` 业务层 / `drivers` 驱动 / `models` 模型 / `storage` 存储） |
| 前端 | Vue 3 + TypeScript + Vite + Pinia |
| 编辑器 | CodeMirror 6 |
| UI | shadcn-vue（reka-ui）+ Tailwind CSS 4 |
| AI | DeepSeek Harness 插件（`dsh-plugin/`）通过本地 HTTP API 控制 |

---

## 项目结构

```
c:\Users\Administrator\Desktop\dbcat\
├── main.go                    # Wails 入口（窗口标题、绑定 App.Call）
├── internal\
│   ├── app\                   # 业务层：命令注册表（cmd_*.go）、本地 HTTP API（httpapi.go）
│   │   ├── httpapi.go         # AI Agent 集成：127.0.0.1 + token 的本地 HTTP API
│   │   ├── dshagents.go       # 多 Agent 授权模型：独立开关/令牌、镜像文件生命周期、旧格式迁移
│   │   ├── dshplugin.go       # Agent 插件的安装/卸载（检测 DSH profile 清单 + 调 dsh plugin）
│   │   ├── plugin_assets.go   # 内嵌插件源码 → npm 兼容 tgz（archive/tar + gzip，不调 pnpm）
│   │   ├── cmd_dsh.go         # 集成状态/开关/端口/令牌/插件安装的前端命令
│   │   ├── datagrid_save.go   # 数据网格保存：生成 INSERT/UPDATE/DELETE 与回滚语句
│   │   ├── export_sql.go      # 导出 SQL INSERT 语句
│   │   ├── cmd_datagrid_filter.go # 筛选条件 / COUNT 语句生成
│   │   ├── sqlsafety.go       # 只读判断 + 写操作风险分级（写操作确认门）
│   │   └── ...                # cmd_core / cmd_data / cmd_meta / cmd_diff / cmd_nosql ...
│   ├── drivers\               # MySQL / Postgres / SQLite / Redis / Mongo 驱动封装
│   │                          # （含 TxExecutor：单事务执行多条语句，M/S/P 三驱动实现）
│   ├── models\                # 数据模型
│   └── storage\               # 本地存储（SQLite 配置库）
├── frontend\                  # Vue 3 前端源码
├── dsh-plugin\                # DeepSeek Harness 插件（控制 DBCat 的 AI 工具）
│   ├── embed.go               # //go:embed all:plugin —— 把插件【源码】打进 exe（不嵌产物）
│   ├── plugin\                # 插件源码（dbcat-dsh-plugin，含 dsh.bundle.patch 声明）
│   │   └── cordis.patch.yml   # bundle patch（安装后由 DSH 自动应用）
│   ├── test\                  # 冒烟测试 + mock 契约测试 + 一键脚本（run-all-tests.mjs）
│   └── README.md
├── zcode-plugin\              # ZCode 插件（MCP server，零依赖 Node）
│   └── dbcat\                 # .zcode-plugin\plugin.json + mcp\server.mjs + skills/commands
├── trae-plugin\               # Trae 插件（mcp.json + rules）
├── .gitignore                 # 忽略构建产物/依赖/日志
├── go.mod / wails.json
└── dbcat.exe                  # 构建产物（根目录）
```

> 数据存储位置：`%APPDATA%\dbcat\dbcat.db`（SQLite，保存连接配置与应用设置）
> AI Agent 集成镜像文件（DBCat 自动写入、供插件读取地址与令牌）：
> `dsh.json`（始终写出，顶层即 DSH 视图）、`zcode.json` / `trae.json`（各自启用时写出，停用即删除）

---

## AI Agent 集成（AI 插件控制 DBCat）

内置 AI 已移除，AI 能力由**外部 Agent 插件**提供，同一套本地 API 供三种插件分别授权接入：

```
DeepSeek Harness / ZCode / Trae ──各自令牌──▶ DBCat 本地 HTTP API ──▶ 数据库
```

- **DBCat 侧**：启动时自动在 `127.0.0.1:<port>` 起本地 HTTP API（默认 28710，被占用自动后移），
  Bearer token 认证。接口覆盖连接列表/增删改、连接测试、schema 浏览、SQL 执行，以及 `GET /api/status` 诊断
  （诊断端点刻意只回传各 Agent 的 `token_set` 布尔值、不回传明文令牌：否则任何持有某个 Agent 令牌的插件，
  都能在被停用前窃取其它 Agent 的令牌从而绕过吊销）。
- **多 Agent 授权隔离**：`dsh` / `zcode` / `trae` 三个 Agent 各有独立开关与独立令牌——
  任一启用即启动服务、全部停用即停止服务；**令牌即授权**，停用某个 Agent 后它的令牌立即失效（不必改其他 Agent 的令牌）。
  首次启用某 Agent 时自动生成它的令牌；`dsh.json` 始终写出，`zcode.json` / `trae.json` 各自启用时写出、停用即删除。
- **写操作安全**：`INSERT/UPDATE/DELETE/DDL` 等写语句在 API 层强制 `confirm` 确认，
  未确认时返回 `confirmation_required`；危险语句（DROP/TRUNCATE/ALTER/CREATE 等）标记 `danger`。
- **插件不接触密码**：所有数据库操作都由 DBCat 执行。
- **集成开关**：工具栏插头图标 → “AI Agent 集成”对话框可查看服务状态、改端口（1024-65535，所有 Agent 共用）、
  逐个 Agent 启用/停用、显示/复制/重新生成各自令牌，并附插件安装指引与该 Agent 的配置文件路径。
  DSH 默认启用；全部停用后本地 API 停止，`dbcat_*` 工具失效（`dbcat_direct_*` 直接模式不受影响），DBCat 界面使用不受影响。
- **直接连接模式**：DBCat 未运行时，DSH 插件内置驱动（mysql2 / pg / node:sqlite / ioredis / mongodb）可直接连库，
  密码仅存于进程内存、写操作同样强制确认；见 [dsh-plugin/README.md](dsh-plugin/README.md)。
- **一键安装 / 更新 / 卸载插件**：DeepSeek Harness 卡片「停用」左边的按钮是**三态**的——
  未安装→「安装」；已安装但版本落后于可用源→「更新」；已安装且最新→「卸载」
  （卡片副标题会写「已安装 vX」或「已安装 vX · 可更新到 vY」）。执行中按钮转圈禁用，卸载前二次确认，
  完成后提示重启 DeepSeek Harness。检测依据是 `$DSH_HOME/profiles/<profile>/package.json`
  里的 `dependencies` 与 `dsh.profile.bundles`（`$DSH_HOME` 优先，否则 `~/.dsh`）。
  包来源：**exe 内嵌的插件源码**（`dsh-plugin/plugin`，由 `dsh-plugin/embed.go` 的
  `//go:embed all:plugin` 打进二进制）——点安装时由 DBCat 在代码里打成 npm 兼容归档
  （`archive/tar` + `gzip`，条目带 `package/` 前缀、权限 0644、时间戳固定），
  写进 `~/.dsh/plugin-archives/` 后交给 `dsh plugin --profile <p> add|remove`（DSH 自己会同步 bundle 列表）。
  因此**不依赖 pnpm 是否存在**、版本库里也不会多出二进制产物；embed 是编译期的，改了插件源码要重新编译 exe。
  ZCode / Trae 的插件没有可编程入口，需在各自客户端手动安装（卡片内有指引）。
- **手动安装（等价命令）**：`pnpm --dir dsh-plugin\plugin pack --pack-destination %TEMP%` 后
  `dsh plugin --profile web add "file:%TEMP%\dbcat-dsh-plugin-0.2.2.tgz"`；卸载 `dsh plugin --profile web remove dbcat-dsh-plugin`。
  见 [dsh-plugin/README.md](dsh-plugin/README.md) ·
  ZCode 见 [zcode-plugin/README.md](zcode-plugin/README.md) · Trae 见 [trae-plugin/README.md](trae-plugin/README.md)

---

## 构建与运行

### 1. 后端测试

```powershell
cd C:\Users\Administrator\Desktop\dbcat
go test ./... -count=1
```

默认全部离线可跑（不依赖外部环境）。另有两个**默认跳过**的真实环境集成测试：

```powershell
# 对真实 MySQL 跑一遍「生成保存语句 → 真事务提交 → 校验落库 → 失败整体回滚 → 回滚语句复原」
# 全程只操作 TEMPORARY 临时表（会话级、连接断开即消失），不碰库里任何真实数据
$env:DBCAT_TEST_MYSQL_HOST='...'; $env:DBCAT_TEST_MYSQL_PORT='3306'
$env:DBCAT_TEST_MYSQL_USER='...'; $env:DBCAT_TEST_MYSQL_PASSWORD='...'
$env:DBCAT_TEST_MYSQL_DATABASE='...'    # 建临时表也要求先选中一个库
go test ./internal/app/ -run MySQLSaveChainIntegration -v -count=1

# 只读检测本机 DSH 插件安装状态 + 验证 dsh CLI 命令通道（用 list，不改动安装）
$env:DBCAT_TEST_DSH_DETECT='1'
go test ./internal/app/ -run 'InspectAgentPluginOnRealMachine|RunDshPluginList' -v -count=1
```

### 1.5 插件测试

```powershell
# 一键运行全部插件测试（冒烟 + mock 契约，需 28710 端口空闲）
node dsh-plugin\test\run-all-tests.mjs
```

### 2. 前端构建

```powershell
cd C:\Users\Administrator\Desktop\dbcat\frontend
npm install
npm run build
```

### 3. 完整构建（前端 + exe）

```powershell
cd C:\Users\Administrator\Desktop\dbcat
$env:GOFLAGS="-buildvcs=false"
wails build -clean
Copy-Item build\bin\dbcat.exe . -Force   # 复制到根目录
```

> 本机 git 不可用时需 `GOFLAGS=-buildvcs=false` 跳过 VCS 版本戳。
> 插件源码（`dsh-plugin/plugin`）由 `//go:embed all:plugin` 打进 exe，**没有"重打内嵌包"这一步**：
> 改了插件源码重新 `wails build` 即可；安装时的 npm 归档由 DBCat 在代码里现打（不调用 pnpm）。
> `TestBuildPluginArchiveMatchesEmbeddedSource` 会校验「打出的归档 == 内嵌源码逐字节」，
> `TestBuildPluginArchiveStructure` 校验 npm 归档结构（`package/` 前缀、0644、含 `dsh.bundle.patch`、输出确定性）。

### 4. 开发模式（热重载）

```bash
cd C:\Users\Administrator\Desktop\dbcat
wails dev
```

---

## 图标资源

| 文件 | 尺寸 | 用途 |
|---|---|---|
| `build/dbcat-icon.svg` | 矢量源 | 主图标设计源（蓝底数据库猫） |
| `build/dbcat-icon-dark.svg` | 矢量源 | 深色主题版设计源 |
| `build/appicon.png` | 1024 | Wails 应用图标（嵌入 exe） |
| `frontend/public/logo.png` | 512 | 界面 Logo（浅色主题） |
| `frontend/public/logo-black.png` | 512 | 界面 Logo（深色主题） |
| `frontend/public/favicon.png` | 128 | 窗口 / 标签图标 |
| `build/windows/icon.ico` | 16–256 | Windows 多尺寸图标 |

重新生成图标资源：

```powershell
python "C:\Users\Administrator\Desktop\dbx\.go-gen-icons.py"   # Python 版（依赖 Pillow，推荐）
powershell -File "C:\Users\Administrator\Desktop\dbx\.go-gen-icons.ps1"   # 脚本版（依赖 ImageMagick）
```

---

## 常用脚本速查

| 脚本 | 作用 |
|---|---|
| `.go-sync-build.ps1` | 全量同步真源 → 工作目录 |
| `.go-sync-ai.ps1` | AI 相关文件增量同步 |
| `.go-ai-agent-test.ps1` | 运行 AI agent 测试 |
| `.go-rebuild.ps1` | 前端构建 + wails 打包 + 复制 exe |
| `.go-copy-exe.ps1` | 单独覆盖根目录 exe |
| `.go-gen-icons.py` | 重新生成图标资源（Pillow） |
| `.go-rename-dbcat.ps1` | DBX → DBCat 批量改名脚本（已执行） |

---

## 改名历史

- 本项目基于 **DBX**（原版官网：<https://dbxio.com/cn>）的 Go 语言修改版改造而来。
- 内部标识符同步更新：Go module（`dbcat`）、exe 文件名（`dbcat.exe`）、localStorage key（`dbcat-*`）、日志前缀（`[DBCat]`）、数据目录（`%APPDATA%\dbcat`）。
- 外部链接（官网 `dbxio.com`、发布仓库）保持不变。