跳到正文
CF / PROJECT 03

database-cli

给 Agent 用的安全数据库排查

CLI 优先的数据库技能，让 Agent 在护栏内排查真实数据。

状态
活跃开发中
开始于
2026
技术栈
Python · CLI · Codex Skill · Database
链接
01

Why

为什么

生产排查总会绕回数据库：这个字段在哪张表、哪一列变了、这笔订单在 QA 环境里到底长什么样。

Agent 很擅长这种来回查证。但直接给它一个通用数据库客户端并不划算。database-cli 给 Agent 的是一个收窄的、可审计的入口。

02

Problem

问题
  1. 01

    Agent 靠猜而不是读 schema，经常对着不存在的表写 SQL。

  2. 02

    通用 SQL 客户端什么语句都放行，包括写入和 DDL。

  3. 03

    连接信息散落在命令行和聊天记录里。

  4. 04

    每个环境配置方式都不一样，人和 Agent 没有共用的入口。

03

System

系统

CLI 就是产品本体，其余的都是它上面的薄层。

  1. L1Skill · SKILL.md

    使用规范：先确认环境、读取真实 schema、执行有界只读查询，只有得到明确允许才改数据。

  2. L2可选 MCP 适配层

    scripts/database-mcp 通过 stdio MCP 暴露同一套能力，每一次调用都委托给 CLI。

  3. L3CLI · scripts/db-query

    唯一的真实执行入口：校验 SQL、强制只读默认值和行数上限、检索元数据。

  4. L4sq 后端

    查询通过 sq 执行，环境配置写在本地的 connections.local.json，不进仓库。

04

Implementation

实现

  • Agent 能直接处理的安装状态

    --setup-status 返回包含 ready、问题列表和 next_actions 的 JSON，且不连接任何数据库，Agent 可以先自己修好配置。

  • 对象搜索

    按模式搜索 schema、表、列、索引和存储过程，支持 names、summary、full 三档详情，不用手写 information_schema SQL。

  • 带意图的连接

    环境可以配置显示名、项目、描述和别名，Agent 能按用户的意思选对连接。

  • 一步安装

    scripts/install 检查 sq、收集连接信息并写入本地配置，一条命令完成。

05

Decisions

决策
  1. D1

    只有一条执行路径

    MCP 适配层不允许有自己的查询逻辑。安全规则都在 CLI 层，任何客户端都绕不过去。

  2. D2

    写权限由配置声明，不由参数声明

    只有标记了 "writable": true 的环境才接受 --allow-write；临时连接还需要额外的 --writable。受保护的库无法改用临时连接来绕过配置。

  3. D3

    改之前先数

    已批准的 UPDATE、DELETE 会先 COUNT 实际影响行数，超过 max_write_rows（默认 1000）直接拒绝，WHERE 1=1 这种语句混不过去。

  4. D4

    有些 SQL 永远不放行

    DDL、权限、事务、存储过程、锁和导出，即使批准了写入也依然拦截。

  5. D5

    不做平台

    不做 Workbench、权限平台或多租户服务。它始终是一个人和 Agent 都能安装、能审计的技能。

06

Result

结果
执行入口
scripts/db-query
默认行为
只读 · 有界行数
客户端
Codex Skill · MCP

它是我自己 Agent 工作流里的数据库入口：查 schema、跨环境核对、产出修数 SQL，都走同一个带护栏的 CLI。

GitHub