anumana

Anumana

运行查询之前，就知道它会花费多少。 为 AI 编写的每条查询提供推理级预判。

Anumana 是一个 MCP 服务，可在 AI 编码 Agent 刚写出昂贵查询时、在它执行查询或将其提交到 PR 之前将其拦截。它运行在 Claude、Cursor、Windsurf、Codex、Kiro 或任何兼容 MCP 的 Agent 中，通过 EXPLAIN 读取你的真实架构（绝不使用 EXPLAIN ANALYZE），并用通俗易懂的语言告诉你查询的运行方式，以及它是否会造成影响。

它专注于AI Agent 实际生成的查询：目前是文本转 SQL，同时也支持 RAG / 向量搜索（pgvector）——因为编写相似度搜索的 Agent 根本不知道自己刚刚触发了对所有嵌入向量的暴力扫描。Anumana 为 Agent 补上了缺失的反馈环。

它不是另一个 NL→SQL 工具，也不是数据库健康状况仪表板。它只做一件事：防止 AI 编写的数据库代码悄无声息地损害生产环境。

---

它能做什么（功能）

工具	它能回答什么
preflight_query	“这条 SQL 查询会很昂贵吗？”——风险等级（便宜／中等／昂贵／危险）、扫描行数与返回行数、扫描策略以及开销标记。无需执行查询。
preflight_vector_search	“这次 RAG 相似度搜索会很昂贵吗？”——捕捉普通 SQL 检查会漏掉的向量陷阱：没有 HNSW/IVFFlat 索引的暴力扫描、top_k 过大、搜索范围无界、元数据筛选导致 ANN 召回率下降。
rewrite_query	“让它更便宜。”——提供经过验证的等效改写，并展示改写前后的规划器成本，以及以选择性为门槛的索引建议（筛选条件匹配表中大多数行时，不会建议你为该列建索引）。engine="pgvector" 会建议创建 HNSW 索引。
explain_query_working	“它是怎么运行的？”——分为两层：逻辑收集顺序（FROM → WHERE → GROUP BY → HAVING → SELECT → ORDER BY → LIMIT），以及针对你的架构生成的实际物理计划，并逐步说明。
preflight_schema_only	“我还没提供数据库凭据。”——针对粘贴的 CREATE TABLE DDL 进行静态分析，无需连接数据库。离线、零信任的入口。

引擎（12 个，涵盖 7 种范式）： Postgres 和 SQLite 已通过实时测试； MySQL、pgvector、MongoDB、DynamoDB、FalkorDB、Cassandra、Redshift、BigQuery、 Snowflake 和 ClickHouse 则以已通过离线验证、未经测试的适配器形式提供， 后续会逐个进行实时推广。完整矩阵和成本信号见 SUPPORTED_ENGINES.md。适配器接口见 DESIGN.md。

唯一诚实的规则

Postgres 规划器成本是无单位的，并非毫秒（文档）。 Anumana 绝不会捏造 ~3.2s 这样的数字。它会报告扫描行数、扫描策略、 风险等级、开销标记以及改写的成本差值——所有内容都有依据，绝不凭空编造。 每项估算都会附带准确度等级（实时模式为 UPPER_BOUND，仅架构模式为 HEURISTIC）。

---

安装

pip install anumana-mcp          # once published to PyPI
# or from source:
pip install -e .

然后将你的 Agent 指向它。由用户安装；Agent 会在连接时通过 MCP tools/list 握手自动发现工具——无需发布到任何商店。

Claude Desktop / Cursor / Windsurf / Kiro — mcpServers 配置块

{
  "mcpServers": {
    "anumana": {
      "command": "uvx",
      "args": ["anumana-mcp"],
      "env": { "ANUMANA_DSN": "postgres://readonly@localhost:5432/mydb" }
    }
  }
}

请使用只读 Postgres 角色。Anumana 只会执行 EXPLAIN，但只读权限是 纵深防御的一环。省略 ANUMANA_DSN 即可在仅架构模式下运行（输入 DDL，无需数据库）。

---

无数据库试用（30 秒）

python3 src/demo.py          # runs the engine on a canned plan, zero deps

使用真实 Postgres 测试

# a throwaway table, then:
ANUMANA_DSN=postgres://localhost/mydb anumana-mcp

参见 src/live_test.py，其中提供了一个由 psql 支持的测试框架，可用实时数据验证真实的成本差值和选择性门槛。

---

刻意不包含的功能

没有 run_query（我们绝不执行你的 SQL），没有 NL→SQL（Agent 已经会做），没有数据库健康状况报告，也没有美元计费。保持专注就是我们的策略。

许可证

MIT——参见 LICENSE。

社区与联系

欢迎贡献 — 请参阅 CONTRIBUTING.md 和 行为准则。添加数据库引擎是最有价值的贡献；适配器约定很精简（SUPPORTED_ENGINES.md）。

• **错误 / 想法：**请提交 GitHub issue。
• **安全问题：**请参阅 SECURITY.md — 私下报告。
• **维护者：**[email protected]