mysql-cli AGENTS.md

This file provides guidance to AI agents when working with code in this repository.

项目定位

Go 实现的 MySQL CLI，目标是替代 designcomputer/mysql_mcp_server：把原 MCP 的全部只读/写能力下沉为命令行子命令，让任何能跑 shell 的 AI agent（Claude Code / Cursor / Codex / Aider）无需 MCP runtime 即可查询 MySQL。设计前提是 agent 是首要调用方（默认 JSON 输出、稳定退出码），REPL 仅供人类调试，不是主路径。

常用命令

go build ./...                              # 编译
go vet ./...                                # 静态检查
go test ./...                               # 单元测试（默认，136 用例，全部用 sqlmock，无需 DB）
go test ./internal/query/ -run TestApplyLimit -v   # 跑单个测试
go test -cover ./...                        # 覆盖率（项目目标 ≥80%，历史区间 81%~92%）
go test -coverprofile=cover.out ./... && go tool cover -func=cover.out   # 覆盖率明细
./scripts/skill-format-check.sh skills/     # 校验 SKILL.md frontmatter
./scripts/skill-format-check/test.sh        # skill-format-check 自测（good/bad 用例）

集成测试需要真实 MySQL，用 testcontainers-go 起 mysql:8 容器，默认跳过：

RUN_INTEGRATION=1 go test -tags=integration ./internal/integration/ -v

internal/integration/integration_test.go 带 //go:build integration 构建标签，且 TestMain 在 RUN_INTEGRATION 未设置时直接 os.Exit(m.Run()) 跳过容器初始化。Docker 未运行时不要开此变量。

架构（分层与依赖方向）

包严格单向依赖，result 是无依赖底层，避免循环引用：

cmd/mysql-cli/main  ->  cli（cobra 装配 + 退出码映射 + config 子命令）
                          ↓
        config ─-> conn ─-> query ─-> result
          │        │       └─-> safety（无依赖，纯逻辑）
          │        └─-> schema ─-> result/safety
          └─ env/file 解析   repl（聚合 query+schema+format）
                              format ← result

• result - 共享 Result{Columns, Rows, RowsAffected, LastInsertID}，是 query/schema（生产者）与 format/cli（消费者）之间的中立契约。
• safety - 纯逻辑、零依赖、完全可单测。SQL 分类（read/dml/ddl/unknown）、只读闸门、标识符校验、多语句检测、破坏性操作识别。改动安全模型时只动这里。
• config - TOML 命名数据源 + MYSQL_* 环境变量兼容（零配置迁移自原 MCP）。解析优先级：CLI flag > env > file > default（见 Resolve）。密码支持 ${ENV} 占位符展开。
• conn - 由 config.Datasource 渲染 go-sql-driver DSN 并开连接池；SSH 隧道在 Open 前建立，DSN 指向本地转发端口。Pool.Close 先关隧道再关 *sql.DB（生命周期绑定，见下）。
• query - Execute（读，走 QueryContext）、ExecuteWrite（单条 DML/DDL，包在事务里提交）、ExecuteTxn（多条原子事务）。每条语句都过 safety 闸门 + 多语句检测。
• schema - 只读探索命令（schema/sample/tables/databases/read/explore/analyze），对应原 MCP 的 get_schema_info/get_table_sample/list_resources/read_resource。所有标识符在拼接 SQL 前经 safety.Validate* 校验。
• format - result.Result -> json/table/csv/tsv；JSON 严格信封 {success,data,error:{code,message}}。
• cli - cobra 子命令 + 全局 flag + mapError 把核心 error 翻译成退出码；含 config 子命令（init/list/global/project）。
• repl - readline 交互壳，仅人类调试用，复用 query/schema/format。