quarry

Quarry

为 AI 时代打造的数据库工作台——一个内核，多种形态（CLI / GUI / MCP / Agent 技能）。

中文文档 → · 网站 →

你熟悉的每款数据库工具——DBeaver、TablePlus、pgAdmin——都假定键盘前坐着的是人类。但越来越多时候，运行查询的是 AI Agent，而 Agent 需要不同的保障：

• 机器可解析的结果，而不是供人阅读的屏幕
• 共享查询安全策略，并针对不同入口明确授权
• 确定性的错误约定（稳定的退出码），而不是需要抓取的堆栈跟踪
• 以文件形式配置，而不是点击操作——以便进行版本控制、比较差异并与 Agent 共享

Quarry 颠覆了传统设计：它首先是一个遵循 Agent 安全约定的查询内核，而面向人的界面（CLI、GUI）则是基于同一内核构建的轻量外壳。无论查询来自浏览器中的用户、CI 中的脚本，还是运行技能的 Claude，都会使用共享查询策略。CLI 会格式化并呈现行数据；GUI、MCP 和 Python API 则会公开结构化的 QueryResult。准确的边界请参见接口与支持约定。

理念

1. 一个核心，多种形态。 连接管理、查询执行、模式自省和安全防护都位于可导入的内核（quarry.core）中。CLI（qy）、GUI、MCP 服务和 Agent 技能都是轻量外壳。修复一次错误，所有形态都会受益。

2. 默认只读；权限提升需明确且分级。 CLI 写入操作需要 --write；生产环境还需要确认或 --yes。MCP 需要服务端和每次调用的授权，生产环境还需要 confirm_prod。GUI 查询为只读；Python 调用方须先获得授权，才能传入 allow_write=True。没有外层 LIMIT 的读取查询默认最多返回 500 行；使用 --max-rows 0 可明确禁用此限制。PostgreSQL/MySQL 查询执行也会使用数据库只读事务，除非已授权写入；SQLite 会以只读模式打开现有文件。

3. 机器可信赖的约定。 GUI/MCP/Python 查询会返回 {columns, rows, rowCount, truncated, elapsedMs, engine, sql, downloadBytes, sizeIsEstimated}。CLI JSON 仍为行数组；诊断信息和截断提示会输出到 stderr。退出码是稳定的 API：0 表示成功，2 表示连接错误，3 表示 SQL 错误，8 表示安全拦截。CLI 参数语法错误也使用 2；其他命令有各自的退出码（例如 ping 失败时返回 1）。GUI/MCP/Python 会报告结构化错误。

4. 工作区即代码。 工作区就是一个目录：connections.toml + queries/**/*.sql（带有 -- @meta 头部的命名查询）。可通过你自己的代码库共享查询文件和不含凭据的模板；实际连接凭据则保留在本地。

5. 依赖几乎为零。 基础软件包和 GUI 使用 Python 3.11+ 标准库，包括用于 SQLite 的 sqlite3。PostgreSQL 使用系统 psql，Redis 需要 redis-cli 6+，SSH 使用系统 ssh，MySQL 使用可选的 quarry-db[mysql] 依赖。无需 Electron 或云服务；可选的 qy up 保持进程会在后台运行。

安装

pipx install quarry-db        # or: pip install quarry-db
qy --help

SQLite 使用 Python 内置的 sqlite3，无需服务器、Docker 容器或 sqlite3 CLI。PostgreSQL 使用系统 psql 二进制文件；MySQL 需要 pip install "quarry-db[mysql]"。

快速入门

mkdir my-workspace && cd my-workspace
cat > connections.toml <<'EOF'
[shop]
url    = "postgresql://user:pass@localhost:5432/shop"
engine = "postgres"
env    = "dev"
EOF

qy connections                       # list connections
qy exec shop --sql "select * from customers"
qy schema shop customers             # table structure (\d+)
qy gui                               # browser data grid

SQLite 文件

将连接指向运行 qy 的机器上的现有 SQLite 文件：

[notes_local]
engine = "sqlite"
url = "sqlite:///data/notes-local.db"
db = "notes"
env = "local"

[notes_prod]
engine = "sqlite"
url = "sqlite:////srv/notes/notes.db"
db = "notes"
env = "prod"
production = true

sqlite:///data/notes-local.db 相对于包含该连接的工作区解析；sqlite:////srv/notes/notes.db 是绝对路径。显式设置 engine = "sqlite" 时，也接受普通文件路径。文件不存在时会报错，授权写入也不例外：Quarry 不会因为连接路径拼写错误而创建空数据库。

qy connections test notes --env local
qy exec notes --env local --sql "SELECT * FROM notes ORDER BY id"
qy schema notes notes --env local
qy gui

CLI、GUI、MCP 和 Python API 共享表/视图浏览、架构检查、参数、查询限制和导出功能。GUI 支持分页和 SQLite 的 EXPLAIN QUERY PLAN。查询默认只读；写入使用与其他 SQL 引擎相同的显式授权，GUI 始终保持只读。

local、dev 和 prod 是标签；使用不同文件可实现数据隔离。指向同一文件的两个环境访问的是相同数据。要启用生产环境保护并默认使用 Manual 模式，请显式设置 production = true。SQLite 不使用 qy local up、Docker 或 SSH 隧道；远程文件、:memory: 数据库、SQLite URI 选项和附加数据库不在首版实现的支持范围内。如果你的应用在生产环境中使用 PostgreSQL，本地也应使用 PostgreSQL，以保持 SQL 和数据类型一致。

工作区

工作区目录是连接 + 查询的来源：

my-workspace/
├── connections.toml      # [key] url / engine / env / group / notes
└── queries/<db>/*.sql    # named queries (with -- @meta headers)

解析顺序：--workspace PATH → ~/.config/quarry/config.toml → 当前目录。

关于无损数字/字符串表示、各入口的写入支持、稳定接口和经过测试的环境边界，请参阅 COMPATIBILITY.md。

CLI 参考

命令	用途
qy connections [list|add|set|remove|test]	管理连接
qy ping <db>|--all [--timeout N] [--format text|json]	可达性探测（ok/fail + 延迟；若有任一失败则退出码为 1）
qy exec <db> --sql "..." [--format json|ndjson|csv|table] [--timeout N]	执行临时 SQL
qy speedtest <db> [--env dev] [--bytes N] [--runs N]	对当前 PostgreSQL/MySQL 隧道路径进行基准测试
qy schema <db> <table>	查看实时表结构
qy run <name> [k=v ...]	运行已保存的命名查询
qy save <name> --db X --sql "..."	保存命名查询
qy list / describe / validate / fingerprint / audit	管理命名查询
qy workspace list/add/remove	管理聚合工作区
qy up/down/status [--format text|json]	工作区隧道保活程序
qy local up/down/status/sync [--engine postgres|redis|neptune|all]	本地开发服务（见下文）
qy gui	启动本地 GUI
qy mcp [--write]	通过 stdio 提供 MCP 接口（供 AI Agent 使用）

MCP（面向 Agent 的原生接口）

qy mcp 通过 stdio 使用模型上下文协议，无需 SDK 依赖，纯标准库实现。Agent 可使用九个工具（list_connections、list_tables、describe_table、exec_sql、list_saved_queries、run_saved_query、describe_saved_query、save_query、ping_connection），并遵循完全相同的内核安全机制：除非服务以 --write 启动，且调用传入 write: true，否则只读；此外，prod 环境还要求传入 confirm_prod: true。

describe_saved_query 会返回 SQL 和元数据，但不会运行查询。save_query 会写入查询文件，但不会进行验证或执行；它接受 name、db、sql、可选的 desc、tags、参数定义（name、type、required、default）以及 overwrite（默认值为 false）。存在多个工作区时，请使用 list_connections.workspaces 中的路径指定 workspace；数据库必须属于该工作区，其环境集不得跨工作区，且查询名称必须唯一。无需 --write 即可保存文件；该选项只控制数据库写入。ping_connection 会探测指定的 db 和可选的 env，并返回 ok、elapsed_ms 和经过清理的失败类别。其 timeout 默认为 10 秒（范围为 1–30 秒）；连接设置和探测执行有各自独立的时限，因此它不是总墙钟时间期限。

# Claude Code
claude mcp add quarry -- qy mcp --workspace ~/my-workspace

{ "mcpServers": { "quarry": { "command": "qy", "args": ["mcp", "--workspace", "/path/to/workspace"] } } }

已在 MCP Registry 上以 io.github.yiminspace/quarry 发布。 原个人命名空间下的条目仍需管理员协助迁移或弃用；请使用上方的组织条目。直接配置 qy mcp 的方式不变。

安全机制（AI 原生优势）

• CLI 默认只读：写入和 DDL 操作会被拦截，退出代码为 8；使用 --write 允许写入
• 自动限制行数：没有外层 LIMIT 的读取查询默认返回 500 行；使用 --max-rows N 提高上限，使用 --max-rows 0 禁用限制（工具/锁定查询不会被改写；Redis 会在收到结果后限制行数）
• CLI prod 保护：所有环境默认只读 → dev 需要 --write → prod 需要 --write，并且需要交互式确认（自动化场景使用 --yes）
• 查询退出代码：0 成功（可选返回行），1 用法错误，2 连接错误或 CLI 参数语法错误，3 执行错误，8 安全拦截；其他命令使用各自文档中说明的代码

超时

查询执行和连接建立（包括 SSH 隧道设置）分别设有时限，因此无法连接的主机不会耗尽整个查询时间预算：

• 连接超时：15 秒，固定值；仅限制隧道/拨号连接。
• 执行超时：CLI/GUI 默认为 300 秒，MCP 默认为 120 秒（Agent 应更快完成）。

有效执行超时按以下优先级确定：

1. --timeout N（CLI，用于 qy exec/qy run）
2. QUARRY_TIMEOUT 环境变量
3. connections.toml 中该连接的 timeout 字段（通过 qy connections add/set --timeout N 设置）
4. 上述默认值

[shop_prod]
url     = "postgresql://…prod…/shop"
timeout = 600   # this connection alone gets 10 minutes

在 PostgreSQL 上，qy 还会在运行查询前设置服务器端 statement_timeout（约为执行超时的 90%）；在 MySQL/MariaDB 上，它会尽力设置等效的会话变量（服务器支持哪一个就使用 MAX_EXECUTION_TIME 或 max_statement_time）。PostgreSQL 会在服务器端强制执行语句超时。MySQL 支持属于尽力而为，且其 MAX_EXECUTION_TIME 仅适用于 SELECT；客户端超时并不能证明写入已取消。超时错误会告知如何延长超时时间（--timeout、QUARRY_TIMEOUT 或连接的 timeout 设置）。--timeout 和 timeout 字段必须为正数秒。

作为库使用（GUI 和 Agent 所用）

from quarry import configure_workspace, get_connection, run_query

configure_workspace("~/my-workspace")
res = run_query(get_connection("shop"), "select * from customers")
print(res.to_dict())   # {columns, rows, rowCount, truncated, elapsedMs, engine, sql}

SSH 隧道

对于只能通过堡垒机访问的数据库，添加 ssh_* 字段，qy 会自动建立隧道（使用系统 ssh，无需额外依赖）：

[internal_db]
url      = "postgresql://user:[email protected]:5432/appdb"
engine   = "postgres"
ssh_host = "bastion.example.com"
ssh_user = "ubuntu"
ssh_key  = "~/.ssh/id_ed25519"

Neptune 现在也采用相同的隧道路由：如果 Neptune 连接设置了 ssh_host（以及可选的 ssh_user/ssh_key/ssh_port），它会像 Postgres/MySQL/Redis 一样加入隧道池并保持连接。

工作区保持连接（qy up/down/status）

如果你反复查询相同的 SSH 连接（CLI + GUI + MCP），可以启动一次工作区守护程序，并在多个进程间复用已建立的转发：

qy up                    # enable keep-alive; default reconnect on unless explicitly disabled
qy status                # text status: keeper + per-connection tunnel state
qy status --format json  # per-tunnel state (up/reconnecting/down/blocked)
qy down                  # stop keeper

keep_alive=true + reconnect=true 会按工作区保存在 ~/.config/quarry/config.toml 中。启用重新连接后，断开的隧道会通过指数退避重新建立，并在 qy status 和 GUI 标题栏徽标中显示为 reconnecting。如果启用了保持连接，但守护程序未运行，冷启动的 qy exec/qy run 仍可正常工作（沿用旧行为），并会向 stderr 打印一行提示，建议运行 qy up。

如果明确禁用了重新连接，守护程序会进行首次尝试，但不会重试失败或断开的隧道。缺少密钥、身份验证失败和 SSH 配置无效会显示为 blocked；修复相关连接或 SSH 文件后，即可再次尝试。qy status 描述的是隧道传输状态，而非数据库身份验证或查询健康状况；GUI 中的“keeper up”徽标表示后台进程正在运行。请使用只读查询测试完整链路。

注册表会在共享转发前验证进程身份。不可信任仅包含 PID 的旧版守护程序记录；升级前，请停止旧版本的守护程序。代理设置发生变化时，正在执行的查询会继续使用现有转发。由守护程序管理的已退役转发会一直保持运行，直到守护程序关闭，因为外部客户端可能仍在使用它们。

如需验证 PostgreSQL 服务器身份，请在数据库 URL 中添加 sslmode=verify-full 和受信任的 sslrootcert。Quarry 会保留数据库主机名以进行证书验证，并向 libpq 提供 hostaddr=127.0.0.1 以及转发端口。仅有 SSH 隧道并不能验证数据库服务器。

代理（用于受限速的隧道）

如果 SSH 隧道吞吐量受到限制（例如跨境堡垒机——握手连接正常，但数据传输缓慢），可通过本机的 HTTP(S) 代理进行路由：

qy proxy              # show the discovered proxy + each workspace's toggle state
qy proxy on           # enable for the current workspace
qy proxy off          # disable it again
qy exec mydb --no-proxy --sql "..."   # skip the proxy for one call, even if enabled

代理会自动发现——优先使用 macOS 系统代理设置（scutil --proxy），否则使用 ALL_PROXY/HTTPS_PROXY——并按工作区保存在 config.toml 中（绝不会保存在 connections.toml 中）。它只影响设置了 ssh_host 的连接（通过 ProxyCommand 建立隧道）以及 Neptune 的直接 HTTPS 请求；直接（非隧道）数据库连接不受影响。如果为未设置 ssh_host 的连接启用了代理，qy connections add/set 会发出警告。如果已启用代理，但其端口上没有任何进程监听，qy 会改为直接连接，而不是报错；系统代理例外列表覆盖的目标（环回地址、私有 CIDR 范围）绝不会通过代理访问。

确认代理确实生效

由于上述回退到直连的行为会按设计静默执行（查询仍须运行），因此值得了解如何检查某次调用是否确实经过代理：

• qy 输出：如果某个工作区启用了代理，但某次调用仍然直连，qy exec/qy run 会向 stderr 输出一行原因——未发现代理、已发现代理但其端口上没有进程监听，或目标位于代理的例外列表中。--no-proxy 会抑制此输出（你要求直连，因此无需报告）。
• qy proxy：除了显示已发现的代理和每个工作区的开关，它还会列出所有池化 SSH 隧道——SSH 目标、本地端口、是否确实经由代理路由（以及代理地址），以及底层 ssh 进程是否仍在运行。添加 --format json 可输出包含相同字段的 tunnels 数组，便于编写脚本。
• GUI：侧边栏中的环境标记会在该连接的隧道经由代理路由时显示小徽章；工作区管理器会显示每个工作区的代理开关以及当前发现的代理地址。两者都由服务端基于 qy 使用的同一套逻辑计算，而非在浏览器中猜测。

Redis

engine = "redis"（使用系统的 redis-cli）。查询为 Redis 命令：

qy exec cache --sql "SCAN 0 COUNT 100"
qy exec cache --sql "HGETALL user:42"

此处同样适用只读限制：GET/SCAN/TYPE/TTL/HGETALL 可执行；没有 --write 时会阻止 SET/DEL/FLUSHALL。在 GUI 中，Redis 键可点击，并会根据 TYPE 显示对应类型的值。

分组与环境集

连接可以按项目文件夹（group）和环境集（相同的 db、不同的 env，共享架构）进行组织：

[shop_dev]
url = "postgresql://user:[email protected]:5432/shop"
group = "shop"
db = "shop"
env = "dev"
[shop_prod]
url = "postgresql://user:[email protected]:5432/shop"
group = "shop"
db = "shop"
env = "prod"
production = true

• db 相同的连接会合并到一个环境集——同一条已保存的查询可在任意环境中运行：qy run recent_orders --env prod
• qy connections add/set 接受 --db 和 --group；当新键（例如 shop_prod --env prod）与现有环境集匹配时，Quarry 会自动继承其身份
• 如果某个环境成员未设置 group，但所有分组的同级成员设置一致，CLI/GUI/MCP 会将逻辑数据库保留在该分组中，而不是在 OTHER 下创建重复项
• 未指定的环境默认为 dev（最安全的选项）
• GUI 会显示环境切换器；生产环境样式由 production = true 控制

多个工作区

qy 会聚合 ~/.config/quarry/config.toml 中列出的所有工作区——通过一个 GUI/CLI 管理所有项目：

qy workspace add ~/projects/acme/db-workspace
qy workspace add ~/projects/side-project/db
qy connections    # both projects, grouped
qy gui            # sidebar shows both groups side by side

--workspace a:b（以 os.pathsep 分隔）可用作临时覆盖；第一个目录是写入操作的主目录。

Agent 技能与已保存的查询

可移植技能位于 skills/quarry。将该目录安装到 Agent 的技能目录中，并配合基于此版本构建的 qy CLI 使用。该技能不包含个人连接或查询。默认使用英文版 SKILL.md；对应的简体中文版为 SKILL.zh-CN.md。若要将中文设为安装后的入口，请将该版本复制到安装目录中的 SKILL.md。安装一个版本即可，不要安装两个重复技能；修改技能行为时，请同步维护两个版本。

qy --skill-dir /path/to/installed/quarry list
qy --skill-dir /path/to/installed/quarry --workspace ~/db/acme save customer-count \
  --db customers --sql 'SELECT count(*) FROM customers'

save 负责文件格式，并将文件写入 <workspace>/queries/<db>/<name>.sql。运行命令前，--skill-dir 会创建一个符号链接 <skill>/queries/<workspace-name>，指向该查询目录。凭据仍保留在链接之外。每次调用时都传入此选项，以便在更新后重新创建缺失的链接；CLI 不会记住或猜测技能安装路径。缺失的工作区目录会被报告，而不会重新创建。已有文件以及指向其他位置的链接绝不会被替换。若工作区目录名称重复，必须使用 --workspace 选择其中一个。链接错误会导致命令以用法错误终止；查询数据不会被移除。请勿将生成的 queries/ 条目纳入已发布的技能包。

对于 queries/ 指向技能仓库的旧版工作区，请先备份查询文件，并将其移至实际工作区的 queries/ 目录，然后再使用 --skill-dir 前删除旧的技能查询条目。CLI 不会自动迁移现有用户数据。

本地开发容器

如果默认端口已被占用，请明确选择一个空闲端口：

qy local status --engine postgres
qy local up --engine postgres --port 55434

该端口会保存在 Quarry 的 config.toml 中的 [local] postgres_port（或 redis_port），并用于 CLI 和 GUI 的本地设置。只有 env=local 连接的 Quarry 命名卷元数据仍指向旧的回环端口时，才会在所有已配置的工作区中更新这些连接；其他连接保持不变。更改过的连接文件会备份在原文件旁边。

更改端口前，必须先使用 qy local down --engine postgres 停止正在运行的 Quarry 容器。停止的容器会使用现有镜像和命名卷重新创建；自定义数据挂载需要手动处理。Docker 必须正在运行。查询命令只会诊断故障，不会启动 Docker，也不会自动停止冲突的服务。

当本地运行的服务与远程（开发）数据库共用时，每次读写都会经过公共网络，而会频繁访问数据库的测试/e2e 运行会因往返延迟而变得不稳定。qy local 会在 docker 容器中运行 Postgres/Redis，让服务只与 localhost 通信：

qy local up shop            # start local Postgres + register a shop `local` connection
qy local up                 # start Postgres, Redis, and the empty Neptune endpoint
qy local up neptune --engine neptune  # register neptune@local independently
qy connections              # shop now shows a [local] env alongside [dev]
qy run active_customers --env local

qy local status             # running? which port / image?
qy local sync shop          # copy dev schema into local (staging db + rename swap)
qy local down               # stop, keep the data volume (data survives)
qy local down --purge       # stop + delete the volume (next up is an empty DB)

qy local up <db> 会在源数据库的工作区中存储一个新的本地连接。创建前，Quarry 会检查所有已配置的工作区，并复用项目范围（group，或未分组时的源工作区）内唯一一个现有本地条目；如果该范围内有多个匹配项，则会报告配置错误。不同项目可以安全地使用相同的逻辑数据库名称：它们对应的 Postgres 物理数据库会使用命名空间，例如 brain_matrix_runtime 和 yiminlab_matrix_runtime。重新创建共享容器时，托管的本地条目会与配置的端口、命名空间和 localhost 凭据保持一致。

本地 Neptune 服务监听 https://localhost:18182，并接受 Quarry 和 AWS Neptune Data API 的 openCypher 请求。默认的 empty 模式不返回任何行，并确认写入操作，但不会持久化数据。

为实现确定性测试，请仅启动 Neptune：qy local up neptune --engine neptune --fixture /path/to/responses.json。fixture 包含一个有序的 responses 数组；第一个 query_contains 子字符串及可选参数子集匹配的规则，会原样返回其 results：

{"responses": [{"query_contains": "MATCH (n)", "parameters": {"user_id": "test-user"}, "results": [{"n": {"name": "example"}}]}]}

设置 query_exact: true 可要求整个查询与 query_contains 完全相同；设置 parameters_exact: true 可要求参数字典完全匹配。这两个标志默认均为 false，适用于现有的子字符串/子集 fixture。 精确参数匹配会递归比较 JSON 类型，并将布尔值与数字区分开。

对于不匹配的查询（包括未配置的写入），Mock 模式会返回 HTTP 501，因此测试不会因空响应而意外通过。qy local neptune-calls --format json 会列出每次 openCypher 调用、其参数、匹配状态以及单调递增的 next 游标；--after <cursor> 可筛选后续测试窗口。fixture 和调用记录保存在进程内存中，并会在端点停止时重置。这是协议级响应 Mock，不是 Cypher 图数据库。Mock 模式仅绑定到回环地址；在 empty 和 mock 之间切换（或更改 fixture）前，必须先明确停止现有端点。qy local status --engine neptune 会显示当前活动的后端。

一个共享的 Postgres 容器会为每个处于范围内的逻辑连接托管一个带命名空间的物理数据库（固定端口 5433；redis 为 6380），数据存储在 docker 命名卷中。需要 docker 守护进程；可使用 --image 覆盖镜像标签。

GUI

GUI 链接使用 /quarry/?db=auth_db&env=prod&table=oauth_accounts。 地址会根据活动标签页使用已配置的逻辑数据库和环境；工作区文件夹名称不会出现在 URL 中。打开聚焦表的链接会恢复选中状态，但不会运行 SQL。/app/ 不再提供服务。

qy gui — 本地零构建 Web GUI（Slate & Copper 主题，支持浅色／深色模式）：

• 默认使用中文；语言切换器可切换到英文，并记住你的选择。
• 分组侧边栏树，带环境切换器、明确的生产环境样式和连接状态指示点
• 多标签编辑器 — 浏览器存储可用时会保留 SQL 和连接草稿；结果快照有大小限制，较大的结果会保留在当前会话中
• SQL 高亮 + 本地自动补全（关键字／表／列）
• SQL 助手 — 在可折叠的编辑器面板中解释或修改当前 SQL，并支持流式回复和检查点；可从历史记录中恢复已关闭的对话。查询仍通过现有的运行控件执行。
• EXPLAIN 按钮 — 单击即可查看查询计划
• 支持类型识别的数据网格：排序、调整列宽、键盘导航（方向键 + Enter）、使用可折叠 JSON 树检查单元格
• CSV／JSON 导出、可搜索的查询历史（包含连接信息和时间）
• 支持 TYPE 的 Redis 键浏览，并带有可折叠的命名空间树
• 更新检查 — 后台线程每 24 小时轮询一次 PyPI；发现有更新版本的 quarry-db 时，会显示标题栏徽章（包含升级命令和发行说明）。可编辑／开发安装会自动跳过；设置 QUARRY_UPDATE_CHECK=0 可完全禁用此功能。

SQL 助手

运行 qy ai configure 进行交互式设置，或使用标志配置兼容 OpenAI 的模型端点：

qy ai configure --base-url https://model.example/v1 --model your-model \
  --api-key-env QUARRY_AI_API_KEY
qy ai show
qy ai explain --db planning --env dev --file query.sql
qy ai sql --db planning --env dev 'Show the latest record per session'

在启动 qy gui 或 CLI 命令的环境中设置指定的密钥环境变量。或者，--api-key-stdin 会将从标准输入读取的密钥存储在单独文件中，并设置仅所有者可访问的权限；--no-key 适用于无需身份验证的本地端点。--bifrost 选择 Bifrost Virtual Key 身份验证，--thinking disabled 请求非思考型回复。提供方选择和回退顺序由已配置的网关管理；Quarry 不会硬编码第二个提供方。

设置位于 ~/.config/quarry/config.toml 的 [assistant] 部分。GUI 和 CLI 均可通过 QUARRY_CONFIG 覆盖该路径。使用存储的身份验证信息时，API 密钥会与配置文件分开存储在同一目录下的 assistant-credentials.json 中，并设置仅所有者可访问的权限。qy ai show 会显示生效的设置，并遮蔽密钥。 assistant-credentials.json 是 Quarry 的内部存储格式，由 qy ai configure 自动创建；你无需自行编写 JSON。 Quarry 不会为你注册或签发 API 密钥。

配置只能通过 CLI 进行：如果缺少模型，GUI 会保留你的消息并显示需要运行的命令。端点必须支持 Chat Completions 流式传输和工具调用，以便发现元数据。

打开 SQL 编辑器左侧的垂直 SQL 助手 / SQL Assistant 栏。聊天区域在左侧打开，SQL 编辑器和查询控件位于右侧。面板延伸至查询工具栏底部，聊天输入框固定在底部。聊天区域从面板顶部开始；分隔线顶部的小箭头可将其隐藏。聊天滚动条保持窄小，并位于分隔线旁。隐藏面板后，工具栏会恢复全宽，结果网格也会有更多空间。展开面板时，编辑器会保留足够高度，以便调整大小后聊天输入框仍然可见。向下拖动水平分隔线，可利用状态栏上方的可用高度；向上拖回分隔线，可重新显示结果。高度限制会随窗口和工具栏大小调整。两条分隔线共用抓手尺寸、颜色和悬停反馈；垂直分隔线左侧有细边框，其底边与工具栏边框无缝衔接。 打开面板不会发送模型请求。当存在 SQL 且聊天输入框为空时，会显示完整解释提示词的淡色建议。 按 Tab 接受显示的文本，然后按 Enter 请求解释。

回复语言只能通过 CLI 配置。默认情况下，它遵循运行 Quarry 的机器的系统语言：中文会解析为中文，其他语言会解析为英文。查看或更改此 GUI 偏好设置：

qy ai language          # Show the GUI preference and resolved reply language
qy ai language zh       # Chinese GUI replies
qy ai language en       # English GUI replies
qy ai language system   # Follow the system language (default)

此选项存储在 Quarry 配置中的 [gui.assistant] reply_language，并适用于所有 GUI 助手回复，与界面语言无关。重新打开 GUI 或将其切回前台时，GUI 会读取更改；它没有语言设置控件。现有草稿、SQL 和历史记录都会保留。旧版 auto 值是 system 的别名。此偏好设置不会影响 CLI 回复或模型端点设置。

手动编写的消息会原样发送。按 Enter 发送其他消息；按 Shift+Enter 换行。助手可以检查当前连接中的 PostgreSQL、MySQL 或 SQLite 表结构（包括键关系），以帮助编写联接。它无法联接彼此独立的连接，也无法运行 SQL。使用 Run 通过 Quarry 现有的只读查询路径执行查询。

未发送的消息会保留在其所属标签页中，即使隐藏助手或切换标签页也不会丢失。

解释内容支持 Markdown 标题、列表、强调、代码块和表格，包括流式回复和重新打开的历史记录。标题使用主题强调色，SQL 代码块会区分关键字、字符串和数字。宽代码块和表格会在聊天面板内滚动。解释中显示的 SQL 会保留在消息中；只有完成的 SQL 编辑才会更新编辑器。

完成的编辑会更新编辑器，并提供 Restore previous SQL。如果回复到达期间你编辑了查询，助手会保留其提议，供你明确应用。恢复检查点只会更改 SQL；它会保留对话并将该更改标记为已恢复，不会再添加另一个恢复操作。它绝不会回滚数据库更改。编辑已保存的查询会创建草稿，而不会修改查询文件。

关闭标签页不会删除其中的对话。History → Conversations 会重新打开最新的 SQL、消息和检查点，但不会执行查询。对话存储在运行 qy gui 的机器上，与浏览器打开的标签页无关，位置为 Quarry 的 config.toml 旁边的 assistant/history.sqlite3。QUARRY_AI_HOME 可用于选择其他对话目录。

隐私与支持范围

Quarry 不会将连接凭据、查询或结果上传到 Quarry 服务。查询会发送到你配置的数据库。GUI 默认绑定到 localhost，并检查本地来源。已安装的 GUI 软件包会定期检查 PyPI 上的更新；设置 QUARRY_UPDATE_CHECK=0 可禁用此功能。

可选的 SQL 助手会将你的 SQL、对话消息和相关架构元数据发送到你配置的模型端点。它不会自动发送查询结果行或数据库/SSH 凭据。模型凭据保留在本地后端；浏览器没有模型密钥输入表单。对话和 SQL 检查点存储在本地，可能包含你输入的 SQL 字面值和文本。

Neptune/openCypher 属于实验性功能，不在稳定数据库支持承诺范围内。其端点和本地空服务测试无法验证真实的 AWS/IAM 行为。有关支持的测试环境、持久化限制和最终的 1.0 验收清单，请参阅 COMPATIBILITY.md。

路线图

• 所有引擎的结果契约中包含列类型
• DuckDB 引擎
• 跨环境架构/数据差异比较
• 写入审计日志（谁在何处、何时运行了什么）
• 单二进制文件分发

开发与测试

pip install -e ".[dev]"
createdb quarry_test && psql quarry_test -f tests/seed.sql   # or: make seed
make test        # layered run with a per-layer PASS/FAIL summary

测试分为四层；使用 python -m pytest --collect-only -q 查看当前数量，并通过 CI 报告查看当前覆盖率。

层级	覆盖范围	需要
unit	纯逻辑和模拟的引擎行为	测试依赖项
integration	真实数据库以及进程内 CLI/GUI/MCP 调度	相关数据库；本地生命周期管理/同步需要 Docker
e2e	真实 CLI/MCP 子进程	PostgreSQL
browser	由 Chromium 驱动的真实构建版 GUI（也包含在 e2e 中）	PostgreSQL + Playwright；浏览键时需要 Redis

缺少依赖项时，测试可能会跳过；有跳过项的绿色测试结果并不代表完成了全面的发布验证。 CI 提供 PostgreSQL 16、MySQL 8.4 和 Redis 7。单元/集成测试的覆盖率门槛为 ≥95%；前端行为会单独验证。

一目了然地查看测试状态

• **在 GitHub 上：**上方的 CI 徽章会实时更新——任意一层 或 覆盖率门槛未通过时，徽章会变红。每次提交和每个 PR 的结果会显示在 Actions 选项卡下方，也会显示为 PR 检查项。
• 在本地查看通过/失败状态：make test 会输出带颜色的分层摘要；使用 make test-unit / test-integration / test-e2e / test-browser 运行单层测试。
• 在本地查看覆盖率：make cov 会检查门槛并生成 HTML 报告——打开 htmlcov/index.html，逐行查看具体的覆盖情况。

完整的架构、固定数据和 CI 布局，请参阅 TESTING.md；贡献指南请参阅 CONTRIBUTING.md。

Quarry 在 macOS 和 Linux 上开发和测试。Windows 目前尚未测试（psql/ssh 集成和端口接管均采用 Unix 风格）——欢迎提交 PR。

许可证

MIT

显式标记生产连接

环境名称只是标签，并非安全策略。在相应连接的 connections.toml 配置段中设置 production = true，例如 env = "jp" 且 production = true。如果省略该标记，其默认值为 false，即使 env = "prod" 也是如此。升级时，请在使用现有生产连接前显式标记它们。

使用 qy connections set CONNECTION_KEY --production --no-test 标记连接， 或使用 --no-production 清除标记（若要指定工作区，请在 connections 前添加 --workspace PATH）。其他更新会保留该标记。 生产环境导航会准备预览，但不会执行；Run 仍需显式操作。CLI 写入需要确认（或使用 --yes），MCP 写入除常规写入选项外，还需要 confirm_prod: true。