5 个插件让 Claude Code 直连数据库:zweite-tools 上手实操

封面图:Claude Code 通过五个插件连向数据库和文档系统

「帮我查下生产库今天多少订单」——这话我以前不敢跟 AI 说。它拿不到数据库连接,只能帮我写条 SQL,我还得自己复制到客户端里跑一遍。

zweite 这个人做了个 Claude Code 插件市场 zweite/claude-pluginshttps://github.com/zweite/claude-plugins,把中间这层给补上了。装完之后,Claude Code 真能自己连库、跑查询,而且带一个「风险刹车」:高危语句先问你一句再动手。

zweite-tools 插件市场仓库首页

一句话重点:市场里有五个插件,四个是数据查询(zeppelin / starrocks / mysql / mongodb),共享同一套「执行前分级 + 元数据缓存 + 多环境凭证」设计;第五个 alidocs 负责把钉钉文档拉下来、推上去。下面挨个拆,每个都配一个我实际会用的场景。

先装上:一条命令进市场,一个目录管配置

安装分两步——先把市场加进来,再挑需要的插件装。这套走的是 Claude Code 官方的 /plugin 机制,不用手动 clone 仓库。


	bash

/plugin marketplace add zweite/claude-plugins/plugin install mysql@zweite-tools/plugin install alidocs@zweite-tools

配置我卡过一次。老版本每个工具各放各的(~/.mysql/config.json),新版统一挪到了 ~/.taku/ 下面,一个工具一个 JSON。最简单的单库配置长这样:


	json

{"host": "db-prod","port": 3306,"user": "you","password": "…","database": "mydb"}

想换目录用 TAKU_DIR 覆盖就行。旧路径也没废掉——作者保留了对 ~/.<tool>/config.json 的回退读取,所以你要是之前配过,升级完不用重弄。


	bash

export TAKU_DIR=~/work/taku-config   # 想把配置集中放别处时

这个设计我挺认的:配置收敛到一个目录,但不强制迁移,老用户零成本。

整个市场的结构也很规整。仓库根目录一个 marketplace.json 做市场清单,plugins/ 下面每个插件一个文件夹,里头是 plugin.json 清单、skills/<tool>/SKILL.md 技能说明、scripts/ 脚本外加一份 README。五个插件全是纯 Python,没有二进制、没有编译步骤,脚本就是可读的 .py 文件——想在装之前先看它到底会跑什么,直接翻 scripts/ 就行,这点对要连生产库的工具很重要。

作者还留了个校验命令,自己改了插件或者想确认市场清单没写错,跑一下就知道:


	bash

claude plugin validate .

这里得说清一件事:让 AI「说人话就能查库」,靠的不是魔法。每个插件的 skills/<tool>/SKILL.md 就是一份写给 Claude 的说明书——什么时候该调 mysql.py、参数怎么传、风险档怎么读,都写在里头。装一个插件,等于同时把脚本和这份说明书一起塞给 Claude Code,所以它才知道你说「查订单」时该去跑哪个脚本、按什么姿势跑。这也是插件市场这种形态比裸给你几个 .py 更省事的地方:脚本加技能说明打包在一起,装完即用,不用你再手把手教 AI 怎么调。

四个数据插件,一套共享设计

zeppelin、starrocks、mysql、mongodb 这四个,长得

第一层是执行前风险分级。 每条语句先过一遍分类器,分成四档:


风险档	覆盖的语句
safe	只读查询(SELECT)
low	低风险操作
medium	中等风险操作
high	DDL、不带 WHERE 的删改、覆盖写

high 档会先弹确认再执行。这套分级不是简单靠关键字匹配就完事——它还会做一层语义判断:识别到语句碰的是生产表、PII 或者财务字段,风险只往上抬,不往下降。也就是说,一条看着人畜无害的 UPDATE,只要落在敏感表上,就可能被抬到需要你确认的档位。这条「只升不降」的规则是我觉得最靠谱的地方,它默认往保守那头站。

想看某条语句到底判成几档,可以把它直接喂给 risk.py 单独试,不用真连库:


	bash

echo 'DROP TABLE foo' | python3 "$ROOT/scripts/risk.py" --magic '%sql'

这里的 $ROOT 是插件装完后的脚本目录,Claude Code 会告诉你具体路径。日常你几乎碰不到它——正常用法是直接跟 AI 说话,由它在后台调脚本;只有想手动验证某条语句、或者绕开 AI 跑固定查询时,才需要自己拼这种命令。

自动批准的阈值用环境变量控。默认是 safe,意思是只有只读查询能自己跑,其它都要人点头。这个默认值选得很克制——装完不配任何东西,AI 也只能查、不能改:


	bash

export MYSQL_AUTO_APPROVE_LEVEL=safe   # 生产库我只开到这一档

第二层是元数据缓存。 每个 profile 会缓存表结构加 10 行样本数据,默认 30 天 TTL。有了它,AI 不用每次都去 DESCRIBE 一遍表,写查询也知道字段长啥样。缓存自己管:


	bash

python3 "$ROOT/scripts/mysql.py" cache put --table mydb.orderspython3 "$ROOT/scripts/mysql.py" cache listpython3 "$ROOT/scripts/mysql.py" cache clear --all

30 天这个默认 TTL 是个平衡:表结构不会天天变,缓存久点省来回;真改了 schema,手动 cache clear 或者等它过期就重新拉。缓存放哪、存多久都能用环境变量调,MYSQL_CACHE_DIR 换目录,MYSQL_CACHE_TTL_DAYS 改新鲜度窗口。

第三层是命名 profile。 一份配置里放多套环境,prod、staging 随手切。这层解决的是「同一个库有测试和生产两套连接」的日常麻烦——不用改配置文件,查询时点名用哪个 profile 就行。凭证跟着 profile 走,缓存也按 profile 分开存,测试库的表结构不会污染生产库那份。

把这三层单独拎出来讲,是因为它们不是某个插件的私货,而是四个数据插件的公共底座。你在 mysql 上学会的「先看风险档、信任缓存、按 profile 切环境」,到 starrocks、mongodb、zeppelin 上原样适用,不用重学。作者把共性抽到一层,新插件只要接上这套约定就能复用同样的安全边界——这也是我判断这个市场不是随手攒几个脚本的关键:它有统一的设计意图,不是四个各写各的散件。

MySQL 和 StarRocks:一句话查生产库

先说最常用的 mysql。多环境配置就是在上面那份 JSON 外面套一层 profiles:


	json

{"default_profile": "prod","profiles": {"prod":    { "host": "db-prod",    "user": "you", "password": "…" },"staging": { "host": "db-staging", "user": "you", "password": "…", "ssl": true }  },"cache_ttl_days": 30}

除了连接三件套,配置项还挺全。每个键都有对应的环境变量,写进 JSON 或者用环境变量覆盖都行,CI 里注入敏感值就靠后者:


环境变量	配置键	默认	作用
`MYSQL_HOST`	`host`	必填	数据库地址
`MYSQL_PORT`	`port`	3306	端口
`MYSQL_USER` / `MYSQL_PASSWORD`	`user` / `password`	必填	账号密码
`MYSQL_DATABASE`	`database`	空	默认库
`MYSQL_SSL`	`ssl`	false	一开始就强制 TLS
`MYSQL_TIMEOUT_SECONDS`	`timeout_seconds`	30	socket 超时
`MYSQL_CACHE_TTL_DAYS`	`cache_ttl_days`	30	缓存新鲜度窗口
`MYSQL_AUTO_APPROVE_LEVEL`	仅环境变量	safe	自动批准阈值

注意最后一行的 MYSQL_AUTO_APPROVE_LEVEL 只认环境变量、不进 JSON——我理解这是故意的:自动批准阈值是台机器的安全策略,不该跟着配置文件一起被拷来拷去。你的笔记本可以宽松点,跳板机上就该锁死在 safe。

配好之后,日常就是跟 Claude Code 说人话,不用自己拼命令:

「查一下 prod 环境 mydb.orders 表今天下了多少单」

它背后会挑 prod profile、从缓存里读出 orders 的表结构、生成 SELECT、判成 safe 档直接跑,再把结果贴回聊天里。整个过程我不用碰 SQL,也不用记表名。想绕开 AI、手动验证连通性或者跑条固定查询,CLI 口子也留着:


	bash

python3 "$ROOT/scripts/mysql.py" test-connpython3 "$ROOT/scripts/mysql.py" --profile staging query --sql 'SELECT 1'

test-conn 我每换一台机器都先跑一遍,连不上先排查网络,别等 AI 生成完查询才发现连不通。

再举个会触发风险闸的例子,好看清这套刹车到底怎么拦。我让它「把 staging 库里 status 还是 pending 的测试订单清掉」——这是个 DELETE,真按我说的执行会落到一批记录上。它生成语句后判成 high 档,没有直接跑,而是把要执行的那条 SQL 原样贴给我、标上风险等级、停下来等我点头。我扫了眼 WHERE 条件确认没写飞才让它继续。这一趟里,AI 负责把大白话翻成 SQL,真正拍板的还是我——这正是我愿意把它接到 staging、但生产库死守 safe 的原因:让它干翻译的活,别让它干拍板的活。

starrocks 是同一套逻辑,差别在实现:它用纯 Python 实现了 MySQL 协议,不用装任何数据库驱动。mysql 插件也一样,连 caching_sha2 这种较新的认证方式都自己实现了,没有回落到需要 C 扩展的老库。对我这种懒得在每台机器上装一堆 mysqlclient 编译依赖的人,这点是真省事——一个 Python 环境走天下,离线机器也能跑。StarRocks 面向的是 OLAP 分析场景,让 AI 直接对着数仓问「上周哪个渠道转化最高」这类聚合问题,比自己在 BI 工具里拖拉快得多。

MongoDB:用 JSON 描述查询,不用背语法

mongodb 插件的思路跟 SQL 那几个不太一样——Mongo 没有 SQL,它让你用 JSON spec 描述查询,底层走 pymongSQL 那套硬套过来——drop、deleteMany、updateMany 这类破坏性操作会被单独认出来判档,而 find 这种只读的就放行。用 JSON spec 的好处是,查询意图结构化了,AI 生成起来不容易出语法错,你 review 的时候也一眼能看懂它要干嘛。一个 spec 说清集合和条件:


	json

{"collection": "orders","filter": { "status": "paid" },"limit": 20}

缓存这块它做得比 SQL 那几个更关键:按集合(per-collection)缓存 schema 和采样。Mongo 本身没有固定 schema,同一个集合里的文档字段可以千奇百怪,只有靠采样才能让 AI 知道文档大概长啥样、有哪些字段。所以第一次查一个陌生集合,它会先采一批样建立结构认知,之后再问就快了,也更准。


	bash

python3 "$ROOT/scripts/mongodb.py" --profile prod query --spec ./find-paid.json

插件 README 里把这套 JSON spec 用法和风险分类写得很清楚,想照着抄一个查询直接对着看就行:

mongodb 插件 README 的 JSON spec 使用示例

连接串这块它也odb+srv://…),托管在 Atlas 的库不用自己拆分片地址。我拿它翻过一个日志集合,字段嵌套三四层,平时用 Compass 一层层点开看眼睛疼,让 AI 按采样出来的结构直接捞我要的那几个字段、顺手做个计数,比手写聚合管道舒服太多。

Zeppelin:让 AI 在 notebook 里跑 Spark 作业

zeppelin 插件把面铺得最宽——它能在 Apache Zeppelin 上跑 SQL、Spark、PySpark,甚至 shell 命令,同样带风险控制那套刹车。数据团队如果已经把 Zeppelin 当交互式分析入口,这个插件等于让 AI 直接进到你的 notebook 环境里干活。


	bash

python3 "$ROOT/scripts/zeppelin.py" --profile prod run --sql 'SELECT count(*) FROM events'

一个我会用的场景:让 AI 对着数仓跑一段临时统计。比如「统计上周每天的活跃用户数,按天分组」,它生成一段 PySpark、判档、我确认后在 Zeppelin 里执行,结果回来再顺手问「哪天掉得最狠、大概掉了多少」。以前这套要自己开 notebook、写 Spark、等结果、再手动读数;现在对话里一气呵成,notebook 只是执行后端。


	bash

python3 "$ROOT/scripts/zeppelin.py" --profile prod run --pyspark 'df = spark.table("events"); df.groupBy("dt").count().show()'

因为它连 shell 都能跑,风险刹车在这儿尤其关键——这也是四个插件都先做 risk 分级再执行的原因,口子开得越大,越需要那道闸。Zeppelin 本身是段落式(paragraph)的交互 notebook,一个段落一个解释器,这个插件相当于让 AI 成为你 notebook 里的另一双手:它写 PySpark、你审风险、它跑、结果回来接着分析,人始终在环里。对已经把 Zeppelin 当日常分析入口的数据团队,这个衔接省掉了「AI 给代码 → 我复制进 notebook → 跑 → 再贴结果回去问」的来回。

Alidocs:把钉钉知识库搬回本地

alidocs 在本地 Markdown 目录和钉钉云端文档树之间双向同步

alidocs 是市场里唯一的异类,不碰数据库,:


	json

{"cookie": "cna=…; doc_atoken=…; XSRF-TOKEN=…","default_out_dir": "~/Downloads/alidocs","use_playwright": true}

依赖是分层按需装的,不用一上来全装:requests 必装,只下载文档有它就够;要往上传/同步得加 oss2(走阿里云 OSS);要把在线文档导出成本地文件还得装 playwright 再 playwright install chromium,靠无头浏览器渲染导出。space_id 不填它会自动探测,use_playwright 开关控制要不要走在线导出。这种「基础功能零重依赖、高级功能才拉重家伙」的分层,让只想下载的人不必背上一个 Chromium。

我自己最先用起来的就是它——团队的钉钉知识库我一直想整份扒下来做本地检索。它能拉单篇,也能顺着链接把一整个文件夹甚至整个知识库递归拉下来:


	bash

python3 "$ROOT/scripts/alidocs.py" fetch --url 'https://alidocs.dingtalk.com/i/nodes/<uuid>' --out ~/docs/team-kb

插件 README 把 fetch / push / sync 三种用法和 cookie 配置都列全了,照着抄就能跑:

alidocs 插件 README 的下载/同步用法示例

反过来把本地目录推回云端才是它的另一半价值,尤其适合「本地用 Markdown 写、写完同步回钉钉」的工作方式。推送默认让你先 --dry-run 看一眼要改哪些文件、建哪跑。同步还能选冲突策略和清理多余文件:

bash

python3 "$ROOT/scripts/alidocs.py" sync --src ./my-project \    --dest '<链接>' --on-conflict overwrite --prune --yes

--on-conflict 控制本地和云端都改过时听谁的,overwrite 就是本地覆盖云端;--prune 会把云端多出来、本地没有的文件删掉,让两边严格对齐。这两个开关配上,alidocs 才算真能当「同步」用,而不只是单向下载。--prune 这种会删远端文件的动作,配 --dry-run 先跑一遍看清要删啥,不亏。

cookie 会过期是它唯一的日常磕碰——失效了整份重新从浏览器登录态拷一次,把配置里的 cookie 字段换掉就行,已经下载到本地的文件不受影响。对我这种一个月才批量同步一两次的用法,重拷 cookie 的成本可以忽略。

我会怎么用,谁先别急装

这套东西适合谁,我心里有杆秤。如果你已经在用 Claude Code 做日常的数据排查、运维或者文档整理,它把「AI 只能给建议」变成了「AI 能直接动手查」,省掉了复制粘贴那一趟。 数据团队接 Zeppelin、后端接 MySQL、做知识库的接 alidocs,各取所需。

但有两种情况我建议先别急。一是别把它当 GUI 客户端的替代品——它是给对话式操作用的,你要肉眼翻一百张表的数据,Navicat 还是更趁手。二是千万别图省事把自动批准直接开到 high:

bash

export MYSQL_AUTO_APPROVE_LEVEL=high   # 别这么干,等于把刹车拆了

我生产库一律只开 safe。AI 再聪明,DELETE 不带 WHERE 这种事,我也不想给它自动执行的机会——那道风险闸留着,就是为了这一刻。

还有个安全细节值得先说清:这些凭证——数据库密码、钉钉的 cookie——都是明文躺在 ~/.taku/ 下的 JSON 里。这跟大多数 CLI 工具一个路数,但既然它连的是生产库和公司文档,我的习惯是给这个目录收紧权限(chmod 600),敏感环境干脆用环境变量注入、不落盘。alidocs 的 cookie 还会过期,失效了重新从浏览器拷一份就行。

装之前也建议翻一眼对应插件的 scripts/ 源码——都是纯 Python,几百行读得完,确认它连库之后到底会跑什么,比盲装一个能碰生产的工具踏实。

最后放一张速查表,方便按需回来查:

插件	连什么	一句话用途	额外依赖
mysql	MySQL	一句话查库,纯 Python 协议免驱动	无
starrocks	StarRocks	对数仓问聚合分析问题	无
mongodb	MongoDB / Atlas	JSON spec 查询 + 采样建 schema	pymongo
zeppelin	Apache Zeppelin	让 AI 在 notebook 里跑 SQL/Spark/PySpark	视环境
alidocs	钉钉/阿里文档	下载、推送、同步整个知识库	requests(+oss2/playwright)

想上手就从最贴你工作的那个插件开始装,一个就够,配置十分钟内能跑通:

bash

/plugin install mysql@zweite-tools

五个插件我建议按需收着,哪天要连哪个库了再回来装对应那个,别一次全铺开。

真要我排个装机顺序:先 mysql,把 MYSQL_AUTO_APPROVE_LEVEL 锁在 safe 就能安全试水,10 分钟跑通;手上有 MongoDB 就补 mongodb,让它对目标集合先采一轮样;数据团队才需要动 zeppelin 接 notebook;alidocs 完全独立,看你有没有钉钉知识库要搬。五个里我日常真正天天开的就两个——mysql 查库、alidocs 同步文档,剩下三个按项目需要临时装。

还有个省事的细节:四个数据插件共用 ~/.taku/ 一个配置目录,chmod 600 ~/.taku/*.json 一条命令就把几份凭证的权限一起收紧了,不用挨个文件改。前面吐槽过的「配置收敛到一处」,到收尾这一步反而成了安全上的便利。

把 Claude Code 从「帮你写 SQL」升级成「帮你查库」,中间就差这么一个装了风险刹车的插件——四档分级、safe 默认批准、~/.taku/ 一处管配置,这三件事记住就够上手。

值不值得装,说到底取决于你有没有「让 AI 直接动手查数据」的真实需求:有,它省掉你在 AI 和数据库客户端之间来回复制粘贴那一趟;没有,它就只是躺在 ~/.taku/ 里的几个 JSON,装了也闲置。

先收藏这篇,上面那张速查表留着——五个插件哪个连什么、缺哪个依赖、跑哪条命令,回来扫一眼就够,不用再翻一遍 README 或者插件源码。