Schemabrain

别再把原始数据库连接字符串交给 AI Agent。

改用 SchemaBrain——一个只读的信任与智能层。Agent 永远不会编写 SQL，PII 会在查询运行前被拒绝，每次调用都会记录在防篡改审计日志中。

适用于 Claude Desktop · Claude Code · Cursor · Windsurf · 任意 MCP 主机

SchemaBrain 根据你掌控的定义编译每个查询——从提示词到数据库原始 SQL 之间没有任何通路。

三项保障，弥合 AI Agent 与数据库之间的信任鸿沟：

• 架构层面只读，而非配置层面只读 — 提供十二个 MCP 工具，没有一个能够写入。没有 execute() 工具，没有 query() 工具，也没有从 Agent 提示词到数据库写入的通路。
• 在检索边界拒绝涉及 PII 的请求 — PII 标签会从物理架构沿关联和指标传递。如果查询涉及被屏蔽的类别，SchemaBrain 会在查询数据库之前拒绝请求。
• 加密审计链 — 每次调用、拒绝和恢复都会记录在经 SHA256 哈希的追加式日志中（尽力而为：磁盘已满或未配置写入器时会记录警告并继续，而不会导致查询失败）。如果过去的任何日志行被改写，audit verify 会以非零状态码退出。

亲眼看看——请求架构无法回答的问题，它会拒绝请求，而不是捏造关联：

你： 按套餐层级计算用量

SchemaBrain → Agent： { "kind": "unreachable_entity", "recovery": { "suggested_tool": "resolve_join" } } — 用量事件中没有 plan_id，因此它不会凭空编造关联。

Claude： 我不能捏造这个关联——不过可以改为查询按套餐层级统计的合同收入，这项查询确实能够解析。✓

→ 完整会话，包含 SQL 和结果

观看运行过程——实时 Postgres 架构会转化为受治理的知识图谱，防火墙会计算安全指标并拒绝泄露请求，每次调用都会记录在防篡改审计日志中。无需 Agent，也无需 API 密钥：

---

uvx schemabrain init
# then: Cmd+Q Claude Desktop, relaunch, and ask: "list the entities SchemaBrain knows about"
# prefer a persistent install? pipx install schemabrain (or) pip install schemabrain

**费用：**运行捆绑演示 $0（预先精选的数据包，无需 API 密钥）· 为新的 84 列架构建立 LLM 索引约 ~$0.03 · 为未更改的架构重新建立索引 $0。详情请参阅示例会话。

**状态：0.6.0（测试版）。**目前支持 Postgres（本地存储本身使用 SQLite）。SQLite / Snowflake / BigQuery / MySQL 源连接器已列入路线图。

---

目录

根据你的需求阅读：

目标	前往
在捆绑的测试数据上试用	快速入门
了解安全保障	安全保障
接入你的 MCP 客户端	Claude Desktop · Claude Code · Cursor · Windsurf · Cline · ChatGPT（路线图）
接入你自己的 Agent 循环	docs/setup/manual.md
构建语义层	docs/semantic-layer.md
在生产环境中运行（审计、漂移、Docker）	docs/operations.md
观察 Agent（实时查看、审计日志、OTel）	docs/observability.md
与 Querybear / Anthropic reference Postgres MCP 比较	与 Querybear 比较 · 与 Anthropic reference 比较
与 Vanna / Atlan / dbt-mcp / WrenAI 比较	docs/landscape.md

---

快速入门

**只想看看它能做什么？**运行 uvx schemabrain demo — 一条命令，无需输入提示。它会构建示例 SaaS 层，然后让你打开仪表板或运行终端防火墙演示。对于仪表板 / 演示路径，无需 API 密钥，也无需 Docker。以下步骤介绍如何将 SchemaBrain 接入你自己的 Agent，并连接你自己的数据库。

从 uvx schemabrain init 开始，只需三步即可完成 Claude Desktop 集成。如果粘贴你自己的 Postgres URL，则无需 Docker，约需 30 秒。按 Enter 使用捆绑演示时，init 会调用 Docker，并在首次运行时下载约 67 MB 的嵌入模型；缓存后约需 45 秒。

1. 安装

uvx schemabrain init        # zero-install: runs the wizard in one shot
# or install persistently first:
pipx install schemabrain    # (or) pip install schemabrain
schemabrain --version

从源码安装（git clone + uv sync --extra dev）的说明见 docs/setup.md。

2. 运行激活向导

schemabrain init

init 是一个七阶段向导，只需一条命令，即可从“我有一个 Postgres 数据库”带你完成到“Claude Desktop 可以回答关于它的问题”。首次运行时，向导会提示你提供所需信息：

• Postgres URL — 粘贴你自己的连接字符串，或按 Enter 启动本地演示 Postgres 容器并载入捆绑的 SaaS 测试数据（会自动调用 Docker；重复运行时不会重复执行）。
• ANTHROPIC_API_KEY — 可选。跳过后，向导仍会配置 Claude Desktop。在演示路径中，实体 + 指标 + 联接已从捆绑的 YAML 数据包中预先精选 — 语义层无需配置即可工作。在你自己的数据库上，获得密钥后可通过 schemabrain entities suggest --apply 运行实体精选。

SchemaBrain init — activation wizard

  [1/7] Source check       ✓ source reachable + read-only
  [2/7] Index schema       ✓ 12 tables, 84 columns indexed
  [3/7] Curate entities    ✓ 12 entities applied (bundled demo pack)
  [4/7] Curate metrics     ✓ 5 metrics applied (bundled demo pack)
  [5/7] Curate joins       ✓ 11 canonical joins applied (bundled demo pack)
  [6/7] Wire host          ✓ wrote schemabrain entry to claude_desktop_config.json
                           (default; switch with --host claude-code|cursor|windsurf|manual)
  [7/7] Next               ✓ restart your MCP host, then ask: "list the entities SchemaBrain knows about"

完整的向导参考（阶段说明、标志、dbt 自动检测、适用于非 Claude Desktop 主机的 --print-only、--no-entities / --no-metrics / --no-joins 退出选项、费用上限暂停）：docs/setup.md。

3. 重启 Claude Desktop 并提问

1. 完全退出 Claude Desktop——按 Cmd+Q，不要只关闭窗口。MCP 配置只会在冷启动时读取。

2. 重新启动。

3. 新建对话：

   列出 SchemaBrain 了解的实体

如果 Claude 调用了 list_entities，并报告了 user、order 等实体，就完成了。如果没有，请参阅故障排除。

完成向导后，schemabrain inspect 会显示 Agent 已获得的内容，schemabrain tail 会实时输出每次工具调用——请参阅 docs/operations.md。

项目文件

init 只会写入 ./schemabrain.db（本地存储——请将其加入 gitignore）和主机配置。如需将 PII 策略和语义层作为可编辑 YAML 进行调整，请使用 --emit-yaml-dir 重新运行：

schemabrain init --url-env DATABASE_URL --emit-yaml-dir ./schemabrain
# → ./schemabrain/pii_policy.yaml + entities/ + metrics/ + joins/

编辑文件后，运行 schemabrain apply ./schemabrain，再运行 schemabrain check 进行验证，然后重启 serve。这里没有 schemabrain.yaml——配置由 CLI 标志、SCHEMABRAIN_* 环境变量（自动从 .env 加载）和该 YAML 目录树组成。完整说明：你的项目。

---

安全保障

SchemaBrain 目前在 SQL 边界强制执行以下六项属性：

1. 由架构保证只读，而非依赖配置

MCP 接口提供 12 个工具——没有一个可以写入。没有 execute()、没有 query()，无论会话状态如何，都不存在从 Agent 提示词写入数据库的路径——这项保障由结构决定，而不是 Agent 可以切换的标志。schemabrain serve 还会固定设置 default_transaction_read_only=on，以增加一层防护。通过架构保证只读 →

2. 在 get_metric 工具边界执行 PII 感知拒绝

任何涉及被阻止 PII 类别的 get_metric 都会返回 refused 封装——编译后的 SQL 不会执行，拒绝记录会写入 mcp_audit。describe_entity 也会在列级别执行同样的规则（被阻止的列会标记为 redacted=True）。init 默认阻止可能造成灾难性泄露的类别集合（credential,payment_card,government_id）；--pii-block 会替换该集合，因此如需扩大范围，请列出完整目标集合。检测通过列名模式匹配覆盖十二个 GDPR / CCPA / HIPAA / PCI 类别；基于内容的分类已列入路线图。PII 分类体系与传播 →

3. 防篡改审计日志

每次工具调用都会向只追加的 mcp_audit 表写入一行——包含 PII 类别、内容寻址指纹和 sha256 哈希链。audit verify 会重新遍历哈希链；如果任何历史行被改写，就会以非零状态码退出。

schemabrain audit verify   # exit 0 = chain clean

防篡改审计链 →

4. 失败是契约，而不是字符串

每次非成功调用——无论是拒绝、错误还是降级——都会返回结构化的 recovery.suggested_args 块，而不是需要解析的消息。PII 阻止（status: "refused"）会提供实体以供重试；维度不明确和实体无法访问（status: "error"）会提供候选项供选择，或建议下一步调用的工具。只有策略拒绝才会标记为 refused；“我不会猜测”属于带有恢复载荷的 error。

{ "status": "error", "kind": "ambiguous_time_dimension",
  "recovery": { "suggested_tool": "get_metric",
                "suggested_args": {"time_dimension": "order.placed_at"} } }

结构化恢复 →

5. 编译路径：定义 → 参数化 SQL

实体、指标和规范联接会编译为参数化 SQL，并由 SchemaBrain 在自身一侧执行。Agent 可以看到结果行和实际执行的 SQL，但不能向数据库发送任意语句。init 期间由大模型建议的定义需经过审核并显式应用。构建语义层 →

6. 可接入任何 Agent 循环

Claude Desktop 可见的同一 MCP stdio 接口也向任何 MCP 主机开放，包括你自己的 Anthropic、OpenAI 或 LangGraph 循环。examples/anthropic_demo.py 是一个约 260 行代码的即插即用示例，可将 Claude Haiku 4.5 接入 schemabrain serve，并准确输出 Agent 选择的工具。Anthropic SDK 操作指南 →

---

可观测性仪表板

SchemaBrain 提供一个可选的只读仪表板，展示 MCP 服务已在写入的相同审计、PII 和拒绝数据。运行 schemabrain dashboard 会启动一个本地 FastAPI 辅助服务，用于提供预构建的静态 UI；无需 Node 运行时，不会暴露网络，也不包含写入路径。

pip install "schemabrain[ui]"
schemabrain dashboard
# → http://127.0.0.1:7878

它是查看器，而非控制台——没有设置项、没有 SQL 输入区，也没有写入路径。九个只读界面，分别回答 MCP 信封本身无法以可视化方式呈现的运维问题。标志性界面是知识图谱——你的架构会呈现为语义层编译连接时所依据的同类实体关系投影：

• 知识图谱（/graph）——我的架构究竟是如何连接的？ 实体作为节点，规范连接作为边（实线表示已声明的外键，虚线表示从日志中挖掘出的连接），标记包含 PII 的实体并突出显示拒绝热点，同时在高亮的连接路径上显示已声明外键的基数——以图谱而非表清单的形式呈现架构。
• 概览（/overview）——首页：一目了然地查看实体、指标、连接和灾难性 PII 的数量。
• 实体（/entities）——可排序的索引；深入查看任意实体的列、PII、指标和规范连接。
• 数据字典（/dict）——列出每张表、每个列、类型、PII 类别、连接和指标，并支持一键导出 Markdown（与 schemabrain docs 写入的产物相同）。
• PII 矩阵（/pii）——哪些列包含敏感数据？ 热力图中，每个已分类列占一行，每个 PII 类别占一个单元格；每列根据其建议等级标记为 block / redact / allow。属于灾难性泄露类别（credential、payment_card、government_id）的列无论策略如何都会被硬性阻止，并固定在顶部——这样，在将 Agent 指向新的架构之前，你就能发现隐藏在 users 中的 payment_card 列，并一眼看出哪些内容会触发默认的 --pii-block 策略。选择任意行，即可深入查看其所属实体的列、指标和连接。
• 拒绝记录（/refusals）——SchemaBrain 阻止了什么，Agent 收到了什么？ 按时间顺序显示被拦截的调用；展开任意行即可内联查看完整内容——触发的原因（pii_blocked、allowlist_violation、fragment_unsafe、cost_cap_exceeded、ambiguous_resolution、schema_drift）、与策略相交的确切类别集合，以及 Agent 收到的结构化 error.recovery（建议的工具和参数），以便恢复操作。可用于排查“Agent 说无法访问该内容”的问题，并检查这些提示是否确实起到了帮助作用。
• 审计查看器（/audit）——审计链仍然完整吗？ 防篡改日志的可视化界面：每次工具调用，无论结果如何，都会恰好写入一行，并由 chain_hash = sha256(prev_hash || canonical(row)) 进行锚定。运行校验前，完整性状态栏会显示 not verified this session；校验后则显示 verified · n/N intact（或标记 N rows edited after write）。Verify 按钮会在服务端重新遍历审计链，并且在浏览器中重新计算每个可见行的 RFC-6962 Merkle 包含证明。选择一行即可打开完整内容（工具、状态、成本类别、PII 类别、指纹、chain_hash，以及通向根节点的证明路径）。重新加载即可查看新的调用记录。
• 策略（/policy）——防火墙执行的 block / redact / allow 网格，并公开始终启用的灾难性泄露底线（无法移除）。更改需通过复制 CLI 命令完成——仪表板不会写入数据。
• 漂移（/drift）——存储可检测到的配置和增强信息漂移；每项都提供可复制的 CLI 修复命令。

知识图谱——将架构呈现为语义层用于编译连接的实体关系投影；标记灾难性 PII 实体，并追踪规范连接路径。

更多仪表板视图——概览、PII 矩阵、拒绝记录、审计、实体、数据字典、策略和漂移

概览——在一个屏幕上查看整个边界：绑定了什么、保护了什么、发生了什么漂移。

PII 矩阵 — 哪些列包含敏感数据，以及默认策略会阻止什么。

拒绝记录 — 每次被拦截的调用、触发的原因，以及 Agent 收到的恢复提示。

审计查看器 — 可防篡改的链，由服务器端验证到每行的哈希关联。

实体 — 从原始架构中绑定出的每个业务实体，以及其 PII 暴露情况和联接数。

数据字典 — 每张表、每列、每种类型和每个联接，均可导出为 Markdown，用于你的代码仓库或 Wiki。

策略 — 防火墙强制执行的阻止 / 脱敏 / 允许网格，并注明始终启用的最低防护。

漂移 — 存储可检测配置和增强数据的漂移，并为每项提供可复制的 CLI 修复命令。

仪表板仅绑定到 127.0.0.1——这是有意设计的，不提供 --host 标志。它是只读的，并读取 serve 写入的同一个 SQLite 存储。没有 Agent 会与它通信。

仪表板指南 → · PII 矩阵 → · 拒绝记录 → · 审计查看器 →

---

兼容工具

SchemaBrain 通过 stdio 使用 Model Context Protocol。schemabrain init --host <X> 会为四种 MCP 客户端写入一方配置；其他所有支持 MCP stdio 的客户端都可通过 --host manual 使用（打印配置片段，供你粘贴）。

一方配置

schemabrain init --host <X> 会直接将 MCP 条目写入宿主的配置文件。

客户端	设置指南	配置路径
Claude Desktop	/setup/claude-desktop	macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json
Claude Code	/setup/claude-code	调用 claude mcp add
Cursor	/setup/cursor	~/.cursor/mcp.json
Windsurf	/setup/windsurf	~/.codeium/windsurf/mcp_config.json

其他 MCP stdio 主机

schemabrain init --host manual 会将 JSON 条目打印到标准输出——将其粘贴到你所用的主机配置中即可。原则上，任何能启动子进程并通过 MCP stdio 通信的客户端都应该可用；我们尚未对每一种客户端进行全面测试。常见目标：

• Zed — 完整操作指南见 docs/setup/zed.md
• Codex CLI（ChatGPT 用户可用的方案）— 完整操作指南见 docs/setup/codex.md
• Cline（VS Code 扩展）— schemabrain init --host manual 会打印 mcpServers 配置块；通过 MCP Servers → Configure MCP Servers 将其粘贴到 Cline 的设置中。完整操作指南见 docs/setup/cline.md
• Continue — 粘贴到 ~/.continue/config.json
• 你自己的 Agent 循环 — 参见 examples/anthropic_demo.py，了解约 250 行代码的 Anthropic-SDK 参考实现

这 12 个工具、PII 感知拒绝策略、审计链和恢复约定均与传输方式无关——任何符合规范的 stdio MCP 客户端都能获得相同的保障。

Agent 框架

任何能够启动 MCP 服务的框架都可以使用相同的 stdio MCP 接口。Anthropic SDK 路径经过官方测试；原则上，其他框架只要其 MCP 集成通过 stdio 通信即可使用。

• Anthropic SDK — 官方操作指南见 docs/setup/manual.md；参考循环见 examples/anthropic_demo.py
• LangChain / LangGraph — 通过 langchain-mcp-adapters
• Pydantic AI — 通过其内置 MCP 支持
• CrewAI / AutoGen / Agno / 自定义循环 — 原则上，任何带有 stdio MCP 客户端的框架都可使用；我们尚未逐一测试

我们不提供针对各框架的适配器；使用框架的标准 MCP 客户端即可。

尚不支持（云端 / HTTPS 主机）

SchemaBrain v0.6 仅支持 stdio，不支持 HTTPS / SSE 传输。需要云端 HTTPS 端点的客户端目前无法使用：

• ChatGPT Connectors — 变通方案及 v0.5+ 路线图见实际差距说明
• 托管式 MCP 网关 — 这是有意为之（本地优先策略；参见 与 Querybear 的比较）

如果你现在需要 ChatGPT 支持，社区提供的 stdio→HTTPS 桥接工具（mcp-remote、mcp-proxy 等）或许可用；我们尚未验证任何特定桥接工具是否符合 PII / 审计 / 恢复语义。

采购 / 审查安全态势 →

---

示例会话

在内置 SaaS 测试数据集（12 张表、84 个列、12 个实体）上运行的真实 Claude Desktop 会话。为缩短篇幅，此处内容经过精简——真实的 Agent 会先探索 list_metrics / suggest_joins，然后得出这条路径无法到达的结论：

你： 使用 SchemaBrain，按计划层级统计我们的使用量。

Claude： （调用 get_metric(name="usage_volume", group_by=["plan.title"])。该指标以 usage_event 为锚点；要到达 plan，需要使用架构中不存在的联接，因此拒绝：）

{ "status": "error",
  "error": {
    "kind": "unreachable_entity",
    "message": "entity 'plan' is not reachable from metric anchor 'usage_event'; no canonical join exists. Run `schemabrain joins suggest` to surface candidate joins.",
    "recovery": { "suggested_tool": "resolve_join",
                  "suggested_args": { "entity_a": "usage_event", "entity_b": "plan" } } } }

（Claude 在联接层进行确认——resolve_join("usage_event", "plan") 返回 kind: no_canonical_join。usage_events 仅包含 workspace_id，从不包含 plan_id，也没有任何表能连接这两者。）

先说结论：我无法计算按计划划分的使用量，你也不应该希望我伪造结果——此架构中没有使用事件与计划之间的建模关系。usage_events 记录的是 workspace_id，而不是计划；两者之间也没有任何联接。在建立这种关联之前，“按计划层级划分的使用量”无法回答——我不会凭空捏造。

我可以提供的是按计划层级划分的合同收入（此路径可完整解析：subscription_item → subscription → plan，两处均为 fk_constraint 联接，confidence: HIGH）：

SELECT p.title                                     AS plan_tier,
       SUM(si.unit_price_cents * si.seats) / 100.0  AS revenue   -- prices stored in integer cents
FROM   public.subscription_items si
JOIN   public.subscriptions      s ON si.subscription_id = s.id
JOIN   public.plans              p ON s.plan_id          = p.id
GROUP BY p.title
ORDER BY revenue DESC;

计划层级	收入
Enterprise	$379,620.00
Pro	$539.00
Free	$54.00

两点重要说明：

• 合同金额，不是实收金额。 这是订阅明细项收入（seats × unit_price_cents），不是已支付的发票金额。要计算账单总额，total_revenue 指标改以 invoices 为锚点。
• 以整数分为单位。 unit_price_cents 存储为整数；/ 100.0 会将其转换为货币金额。

关键区别在于没有发生什么：面对按计划划分使用量的请求，大多数基于 LLM 的数据库工具都会自信地生成 JOIN plans p ON usage_events.plan_id = p.id，尽管 plan_id 列根本不存在。SchemaBrain 拒绝了——get_metric 返回的是 kind: unreachable_entity 和 recovery.suggested_tool: resolve_join，而非一段文字。Agent 以编程方式遵循结构化恢复约定，而不是捏造联接。这一现场演示展现了“拒绝而非捏造”的安全机制。

成本。 使用 Claude Haiku 4.5 时，每列约 $0.0004（名称晦涩的列可通过 --enable-sonnet 选择 Sonnet 4.6）。随附的 12 表测试数据（84 列、12 个实体 + 5 个指标 + 11 个联接）已预先整理，因此演示流程应用它的成本为 $0——无需 API 密钥。使用 LLM 列描述为这 84 列建立索引，成本约为 $0.03。Pagila DVD 租赁示例（分区去重后为 87 列）是直接测得的参考数据——105 秒内耗费 $0.0299。对未更改的架构重新建立索引，成本为 $0——内容寻址指纹会完全跳过 LLM 调用。

如需验证 Claude 生成的 SQL 在机制上是否正确（以及标出的注意事项是否确实反映了数据行为），请参阅验证 Claude 生成的 SQL。

亲自运行这一完整会话： schemabrain init 会通过一条命令引导你配置好 Claude Desktop；然后询问 Claude “使用 SchemaBrain，按计划层级统计我们的使用量。”，实时观察它先拒绝、再转而提供可回答的结果。

发展方向

SchemaBrain 正在演进为 AI Agent 与数据库之间的信任与智能层——它为 Agent 提供数据库架构的语义地图，根据你控制的定义编译答案，并确保每次调用都考虑 PII 且经过审计。SQL 边界安全是这一层能力的一个证明，而不是它的全部定位。

这一定位以语义基础为依托。如果不知道哪些列包含 PII，就无法拒绝“此查询涉及 PII”。如果没有规范联接定义，就无法回答“通过此联接表进行联接”。如果不知道指标的粒度，就无法提供该指标。

因此，工程上的推进顺序是 架构智能 → 语义基础 → 信任原语。目前，Agent 从不编写原始 SQL：它会调用 get_metric 和语义层工具，SchemaBrain 会编译成 Agent 看不到的参数化 SQL，并提供基于 PII 的拒绝机制、每次拒绝或降级调用的结构化恢复信息、带语句超时和行数上限的只读执行，以及防篡改审计链。基于定义并编译 SQL 的方式是默认选项，也是推荐方式。检查 Agent 任意生成的 SQL（validate_query / execute）是后续可选的主动启用路径，并非我们正在转向的方向。请参阅路线图。

---

路线图

v0.5 / v1 / v2 / v3 标签是路线图里程碑名称，不是软件包版本。软件包严格遵循语义化版本规范——1.0.0 留给经过外部用户实战验证、且无需强制破坏性变更的 API。请参阅 ADR-0003。

完整且持续更新的路线图——包括明确的非目标，以及如何影响优先事项——见 ROADMAP.md。

当前 — v0.6.x 已发布

运行 pip install schemabrain 后可获得：

• MCP 服务，包含 12 个只读工具 — find_relevant_tables、find_relevant_entities、describe_table、describe_column、describe_entity、list_entities、list_metrics、list_joins、suggest_joins、resolve_join、get_example_queries、get_metric。
• 基于定义的编译 — Agent 从不编写原始 SQL；答案根据你控制的定义编译，并在数据库层强制实施只读执行，同时设置语句超时和行数上限。
• 架构智能引擎 — 将 Postgres 索引到本地 SQLite 存储；成本受限的 LLM 语义增强（可选择将隐晦列路由至 Sonnet，使用 --enable-sonnet）；设备端嵌入（BAAI/bge-small ONNX）；语义表检索（基于这些嵌入计算余弦相似度，按每张表中匹配度最高的列排序）；实体识别并提供依据和置信度；通过已声明的外键、查询日志和 dbt relationships 发掘联接；持久化的规范联接图，支持多跳 BFS；以及指标层。
• 信任与安全 — PII 分类（涵盖 12 个类别的 60 条规则），附带逐列置信度、标签传播机制，以及灾难性泄露防护底线（按 PII 列分组会被拒绝，因为这会披露行级信息）；可编辑策略（阻止 / 脱敏 / 允许，并支持逐列覆盖）；防篡改的 SHA-256 哈希链审计日志，支持在浏览器中验证的 RFC-6962 默克尔证明和 audit verify。
• 图谱驱动的仪表板，包含 9 个界面 — 标志性交互式知识图谱，以及概览、实体（可排序索引 + 带语义面板的详情视图）、数据字典（导出为 Markdown）、PII 矩阵、拒绝记录、审计查看器、可编辑的策略编辑器和漂移智能。支持双主题、需选择启用、只读，且仅限 127.0.0.1 访问。
• 命令行工具 — init、demo、index、import dbt、inspect、diff、check、entities、joins、metrics、policy {show, apply, tag}、docs、dashboard、doctor、serve、audit。以 Apache-2.0 许可证发布于 PyPI，并提供无头 Docker 镜像。

后续 — 路线图（暂缓；仅代表未来方向）

阶段 2 — 差异化功能

• 查询成本估算（对编译后的 SQL 执行 EXPLAIN）
• 租户隔离检测 — 检查是否缺少筛选条件，以及是否存在跨租户联接
• 定义间的影响分析
• 使用情况分析 — 热点和未使用表检测
• 通用策略规则语法
• 无需查询日志即可发现隐式外键
• 工具响应的上下文预算管理

阶段 3 — 探索性方向

• 持久化 Agent 记忆
• 多 Agent 协作
• 远程 MCP 传输，以及轻量级客户端 SDK
• 可选、需主动启用的 Agent 编写 SQL 通道（validate_query / execute），须通过显式标志开启。由定义驱动的编译 SQL 仍是默认且推荐的方式；如果该通道最终推出，它将供希望先解析任意 Agent 生成的 SQL 再执行的团队使用。该功能尚未发布，也没有计划改变由定义驱动的默认方式。

此路线图中的所有内容均为开源。

---

故障排除

最常见的五种首次运行故障。完整的故障排除指南见 docs/setup/manual.md。

• pip install schemabrain 安装的是旧版本。 请检查 schemabrain --version。如果版本与最新版本不符，说明 pip 缓存已过期 — 请运行 pip install --upgrade schemabrain。schemabrain init 会将相同版本写入 Claude Desktop 代码片段，以确保重启后仍可复现。如果你从 PyPI 安装，并且 uv 位于 PATH 中，代码片段会运行 uvx schemabrain==<pin>（通过 pip 升级后需手动更新版本锁定）；否则 — 未从 PyPI 安装（本地 wheel、可编辑安装或 git 检出），或没有 uvx — 代码片段会锁定已安装的 schemabrain 入口点的绝对路径，该路径对应于你运行 init 时所用的环境。
• init 报告 source unreachable。 首次运行时，Postgres 可能尚未就绪 — 请等待几秒后重试。对于你自己的数据库，请检查主机、端口和凭据。接受任何形式的连接 URL（postgresql://、postgres://、postgresql+psycopg://）。
• 首次运行 init 或 schemabrain index 卡住约 60 秒。 这是正常现象。首次建立索引时会下载 ONNX 嵌入模型（约 67 MB），并为每一列调用一次 LLM。后续运行速度很快。
• init 在阶段 6“wire host”失败。 必须先安装 Claude Desktop — SchemaBrain 会写入其配置文件，而该文件只有在 Claude Desktop 至少启动过一次后才会创建。
• 重启后，Claude Desktop 中没有显示 SchemaBrain。 必须使用 Cmd+Q 退出（关闭窗口不会触发重新读取 MCP 配置）。运行 schemabrain doctor 验证配置是否已写入。如果 doctor 显示一切正常，但 Claude Desktop 仍看不到工具，请检查 ~/Library/Logs/Claude/mcp*.log。
• Apple Silicon + Python 3.12。 fastembed 的 onnxruntime 依赖未提供适用于 Python 3.12 及以上版本的 arm64 wheel，因此无法构建嵌入。init 会在预检阶段捕获此问题，并提示你使用 Python 3.11（例如 pyenv local 3.11.10），或使用 --no-embed 重新运行（改用关键词搜索，而非语义搜索 — 其他功能均可正常使用）。

---

文档

文档	内容
docs/setup.md	激活向导（推荐）——选择主机、运行向导，然后向 Agent 提问（约 60 秒）
docs/setup/docker.md	Docker 安装（镜像内置嵌入模型，无需首次运行时下载）
docs/setup/manual.md	手动执行 index、mine-queries、日志配置、故障排除、MCP Inspector、SQL 验证阶梯
docs/first-5-queries.md	init 后实际要做什么——通过五个查询测试只读、PII 感知拒绝、审计链和结构化恢复
docs/semantic-layer.md	构建实体、指标（包括复合表达式）、规范联接（包括多跳联接）、导入 dbt
docs/operations.md	inspect、check（漂移）、index --dry-run、Docker compose
docs/observability.md	tail、审计日志、OTel 导出、PII 分类
docs/reference/mcp-tools/overview.mdx	全部 12 个 MCP 工具的完整参考（概览 + 12 个单工具页面）
docs/architecture.mdx	流水线、检索契约、缓存逻辑、成本模型、评估
docs/dashboard/overview.mdx	只读可观测性仪表板——PII 矩阵、拒绝记录、审计查看器
docs/landscape.md	与 Vanna / Atlan / dbt-mcp / WrenAI 的比较；“这是语义层吗？”
docs/threat-model.md	安全模型 + 边界
docs/adr/	架构决策记录（审计/PII 分类、存储协议、版本控制策略、可观测性总线）
examples/	可直接复制粘贴的 MCP 配置、无头 Agent 循环、电商端到端演练

---

常见问题

我的数据会离开本机吗？ 只有经 LLM 增强的列描述以及用于生成这些描述的脱敏样本值。样本离开分析器模块前，都会经过三轮正则处理（电子邮件、美国 SSN、信用卡格式的数字串）——请参阅 schemabrain/profiler/stats.py。Anthropic API 调用会发送列元数据 + 脱敏样本 + 相邻列上下文，不会发送原始行。嵌入由 fastembed 在本地生成（BAAI/bge-small-en-v1.5、ONNX，约 67 MB）。

目前支持哪些数据库？ 目前唯一的源连接器是 Postgres 16+（本地存储本身是一个 SQLite 文件）。SQLite源连接器以及 Snowflake / BigQuery / MySQL，大多只需新增一个 DataSource 实现并调整分析器——已列入 v1.x 路线图。

为什么选择 MCP，而不是 REST API？ 使用者是 Agent，而不是服务。MCP 对工具注册、架构描述和请求/响应传输进行了标准化。Agent 可以原生发现 SchemaBrain 并获取其工具集，无需 API 封装，也无需为每种语言维护 SDK。

这是像 Cube 或 dbt Semantic Layer 这样的语义层吗？ 不完全是——SchemaBrain 构建在语义层基底之上，是 AI Agent 与数据库之间的信任和智能层。实体、指标和规范联接都是一等持久化定义（list_entities、describe_entity、resolve_join、get_metric），并让安全原语成为可能——架构级只读、PII 感知拒绝、审计链。语义基底是基础；包括防火墙在内的 SQL 边界安全是该层能力的一个证明，而非其全部定位。请参阅 docs/landscape.md，了解与 Cube / dbt-mcp / Vanna / WrenAI 的完整比较。

更多问题的解答见 docs/setup/manual.md（为什么使用本地嵌入、更多故障排除）。

---

在你自己的 Postgres 上运行？

如果你打算让 AI Agent 连接真实的（非演示）Postgres，我很想了解使用体验——哪些奏效了，哪些出了问题，哪些地方顺手或棘手。欢迎发起 GitHub 讨论或提交 GitHub issue，也可以通过 GitHub 联系我（@Arun-kc）。我很乐意帮你配置好。

---

贡献者

---

贡献与许可证

欢迎提交 PR。标准很高——请参阅 CONTRIBUTING.md，了解测试优先、99% 覆盖率、约定式提交和架构不变量检查清单。CI 会强制执行所有要求。

Bug 和功能请求请使用 .github/ISSUE_TEMPLATE/ 中的结构化模板。没有复现步骤的 Bug 报告，或没有明确说明根本问题的功能请求，将会被关闭，并要求补充正确的信息后重新提交。

Apache 2.0。