Skip to content

README_CN.md

Latest commit

 

History

History
236 lines (173 loc) · 7.78 KB

README_CN.md

File metadata and controls

236 lines (173 loc) · 7.78 KB

sql-agent-cli

Build Go Version License

Agent-First SQL 网关。

让 AI Agent 安全、省 token 地访问数据库，不泄露敏感信息。

English | 中文

什么是 Agent-First？

传统数据库工具为人类设计。sql-agent-cli 为运行在上下文窗口中的 AI Agent 设计。

Agent 查询数据库时，通常面临三个问题：

  1. Token 爆炸 — 一条 SELECT * 可能把上万行数据塞进 Agent 上下文，浪费大量 token。
  2. 密码泄露 — Agent 直接处理连接串时，密码会进入模型日志、命令历史和聊天记录。
  3. 误删误改 — DELETE 或 UPDATE 中的一个手误就能在生产环境造成灾难。

sql-agent-cli 通过在 Agent 和数据库之间建立代理层解决这三个问题。Agent 永远看不到凭证，查询结果自动压缩分页，危险操作必须人工确认。

核心设计

Token 智能优化

每个查询结果都针对 Agent 上下文窗口自动优化：

  • SQL 层分页 — LIMIT 在数据库层注入，非内存截断。数据库只返回 Agent 能处理的数据量
  • 智能截断 — 长文本和二进制字段自动摘要，不直接展示原始内容
  • 确定性分页 — 默认每页 50 行，带 has_more 元数据；Agent 自行判断是否值得消耗更多 token
  • 列数组格式 — {"columns": [...], "rows": [...]} 替代重复的对象键，宽表场景节省约 30% token
  • 探索模式 — --explore 返回结构化摘要，包含列名、样本行，以及对简单表查询的低成本行数估算，而不是原始分页结果。适合首次接触陌生表

安全代理模式

Agent 永远接触不到数据库凭证：

  • 凭证助手 — 通过外部 JSON helper 解析密码，密码绝不进入 Agent 上下文
  • 加密存储 — 命名连接使用 AES-256-GCM 加密；未提供主密钥时自动生成
  • 明确确认 — DELETE、DROP、TRUNCATE、ALTER 和无条件 UPDATE 无 --confirm 直接拦截
  • 单语句限制 — 每次只执行一条 SQL，防止复杂注入

零依赖部署

拷贝 skill 包到 Agent 目录即可运行：

# OpenCode / Claude Code
cp -R dist/sql-agent ~/.config/opencode/skills/

# 或 Cursor、Copilot CLI 等
# 嵌入的二进制会自动匹配当前平台

无需 Docker、无需数据库驱动、无需任何运行时配置。

快速开始

给 Agent 用户使用

# 1. 构建 skill（一条命令）
bash scripts/build-skill.sh

# 2. 拷贝到 Agent 的 skills 目录
cp -R dist/sql-agent ~/.config/opencode/skills/

# 3. Agent 自动学会使用 sql-agent-cli

给开发者使用

# 克隆并构建
git clone https://github.com/davidfantasy/sql-agent-cli.git
cd sql-agent-cli
bash scripts/build.sh

# 先列出已有连接，避免重复创建
./bin/sql-agent connection list

# 在你自己的终端里连接数据库（本地输入密码，校验成功后才保存）
./bin/sql-agent connection add analytics --wizard

# 或让 Agent 通过密码环境变量自动连接
export DB_PASSWORD='your-password'
./bin/sql-agent connection add analytics --driver postgres \
  --host db.example.com --port 5432 --database app \
  --username analyst --password-env DB_PASSWORD

# 或使用凭证助手（推荐）
./bin/sql-agent connection add prod --driver mysql \
  --credential-helper "vault-helper --profile prod"

# 创建只读连接（拒绝所有写入/DDL）
./bin/sql-agent connection add analytics --driver postgres \
  --host db.example.com --database app \
  --username analyst --password-env DB_PASSWORD --read-only

# 删除连接
./bin/sql-agent connection remove analytics

connection add 会先真实校验数据库连接，成功后才保存。非交互模式必须提供 --password-env 或 --credential-helper。如果你写了 --password-env DB_PASSWORD，但本地没有设置 DB_PASSWORD，CLI 会直接提示类似 export DB_PASSWORD=your-password，方便 Agent 明确告诉用户去终端补充，而不是把密码发进聊天。

探索与查询

# 先查结构
./bin/sql-agent schema list analytics
./bin/sql-agent schema describe analytics users

# 探索模式：摘要替代原始行（首次接触陌生表时节省 token）
./bin/sql-agent query analytics "SELECT * FROM users" --explore

# 自动分页查询（LIMIT 在数据库层注入）
./bin/sql-agent query analytics \
  "SELECT id, email, created_at FROM users ORDER BY id" --page 1

# 需要精确计数时显式调用 count
./bin/sql-agent count analytics users
./bin/sql-agent count analytics "SELECT * FROM users WHERE active = true"

# 危险操作被拦截
./bin/sql-agent query prod "DELETE FROM sessions WHERE created_at < NOW() - INTERVAL '30 days'"
# 错误: destructive_query_requires_confirmation

# 只有人工明确批准后才可以执行
./bin/sql-agent query prod "DELETE FROM sessions WHERE created_at < NOW() - INTERVAL '30 days'" --confirm

输出格式

{
  "ok": true,
  "data": {
    "columns": ["id", "email", "created_at"],
    "rows": [
      [1, "alice@example.com", "2024-01-15T09:30:00Z"],
      [2, "bob@example.com", "2024-02-20T14:45:00Z"]
    ],
    "page": 1,
    "page_size": 50,
    "returned_rows": 2,
    "has_more": false,
    "next_page": null,
    "truncated": false,
    "truncated_cells": 0
  },
  "warning": null,
  "error": null,
  "duration_ms": 14
}

架构

┌─────────────┐     ┌──────────────────┐     ┌──────────────┐
│  AI Agent   │────▶│  sql-agent-cli   │────▶│   Database   │
│  (Context)  │     │  (Proxy + Gate)  │     │ (MySQL/PSQL) │
└─────────────┘     └──────────────────┘     └──────────────┘
                           │
                    ┌──────┴──────┐
                    ▼             ▼
            ┌──────────┐  ┌────────────┐
            │  Safety  │  │  Credential│
            │   Gate   │  │   Helper   │
            └──────────┘  └────────────┘

Agent 与受控接口交互，而非直接接触原始数据库。CLI 负责：

  • 连接加密和解析
  • SQL 安全分析
  • 结果压缩和分页
  • 通过 helper 隔离密钥

路线图

状态 特性
✅ MySQL 支持
✅ PostgreSQL 支持
✅ 凭证助手协议
✅ 加密连接存储
✅ 危险写操作确认
✅ 自动 token 优化
✅ SQL 层分页注入
✅ 探索模式 (--explore)
📋 Microsoft SQL Server
📋 Oracle Database

安全模型

威胁 防护措施
Token 耗尽 智能截断 + 分页 + 列数组格式
凭证泄露 Agent 永远看不到密码；外部 helper 解析
误写数据 危险 SQL 无 --confirm 直接拦截
本地存储泄露 AES-256-GCM 加密；自动生成主密钥
注入攻击 单语句限制；禁止多查询执行

开发

# 格式化代码
bash scripts/format.sh

# 构建二进制
bash scripts/build.sh

# 运行测试（单元 + Docker 集成）
bash scripts/test.sh

# 构建带嵌入二进制的 skill
bash scripts/build-skill.sh

# 构建全平台发布包
bash scripts/package.sh

详见 AGENTS.md 了解架构细节和贡献指南。

许可证

MIT