语义治理层hejielijob-commits/SemaRail

SemaRail

一个受治理的语义层，帮助 AI 智能体理解业务数据并运行安全、可检查的查询。

License: MIT
Project status: Alpha
Node.js
Python

SemaRail 将数据库模式、业务定义、关系、规则和经过审核的 SQL 转化为 AI 智能体可以一致使用的语义上下文。它提供了一个可视化的 Semantic Console 来管理该上下文，一个用于智能体集成的稳定 MCP 接口，以及一个用于只读数据访问的受治理查询边界。

SemaRail 与智能体无关。任何支持 MCP 的客户端都可以通过经过身份验证的 HTTP 端点或 stdio 桥接使用其语义工具。

状态： Alpha。在首个稳定版本发布之前，API、配置和存储格式可能会发生变化。Core tarball 可以从源代码构建；npm 和 PyPI 包尚未发布。

SemaRail Semantic Console 概览

功能特性

- 可视化语义建模 — 导入数据库模式，并管理模型、字段、关系、视图、立方体、业务规则和经过审核的 SQL 知识。
- 与智能体无关的 MCP 工具 — 通过经过身份验证的 Streamable HTTP 暴露语义上下文和受治理查询，并为需要的客户端提供经过身份验证的 stdio 桥接。
- 受治理的数据访问 — 将每个请求解析为当前 Subject 和策略，使用 sqlglot 解析生成的 PostgreSQL，强制执行表/列/行规则和物理对象允许列表，并应用只读、超时、行数、字节数和并发限制。
- 有界的 Agent 结果 — 将小型查询结果以内联方式返回，但将较大的结果转换为短期 CSV 下载，在 Agent 上下文中仅提供 20 行预览。
- 企业身份与策略 — 使用可撤销的服务账户密钥或钉钉/OIDC 员工会话，无需重新安装 Agent 即可更改权限，并在不存储 SQL、结果行或机密的情况下审计决策。
- 常见数据库元数据 — 测试连接、浏览模式，并从 PostgreSQL、MySQL、SQLite、ClickHouse 和 DuckDB 导入模型。
- 版本化语义项目 — 验证草稿，检查生成的源代码和差异，发布修订版本，并回滚更改。
- 双语元数据 — 维护英文和简体中文显示名称，而不更改稳定的技术标识符。
- 可操作的查询诊断 — 在策略、规划和执行过程中携带 Core trace，保留版本化的详细错误，并保留有界的脱敏失败证据 30 天，而不存储结果行。
- 显式反馈与回归审查 — 从 MCP 或 Console 链接提交调用方拥有的反馈，在 Console 中对其进行分类，并仅导出经过审查的可复现回归用例。
- 业务条件澄清 — 发布结构化的指标、时间范围、粒度和业务定义确认规则；必需条件会阻止执行，直到 semarail_prepare_query 返回就绪状态。

数据源管理

数据源凭据保留在服务器上，并在 API 响应中被脱敏。标准 Console 安装包含 PostgreSQL、MySQL、SQLite、ClickHouse 和 DuckDB 驱动，用于连接测试、模式浏览和模型导入。本地 SQLite 和 DuckDB 文件以只读方式打开。

数据源管理

语义模型工作台

编辑业务名称、描述、可见性、主键和字段字典，同时将生成的语义源代码和统一差异视图保持在附近。

语义模型工作台

关系图

在交互式图中探索和维护字段级模型关系。

语义关系图

项目路线图

此路线图突出显示主要项目里程碑。有关文件级发布说明，
请参阅 CHANGELOG.md。

| 日期 | 状态 | 里程碑 |
| --- | --- | --- |
| 2026-08-30 | 已完成 | 建立 SemaRail 品牌、Semantic Console 和稳定的语义 MCP 契约。 |
| 2026-08-31 | 已完成 | 添加钉钉和 OIDC 员工登录、可撤销会话、可信主体属性以及管理员管理的账户访问。 |
| 2026-09-01 | 已完成 | 添加项目、数据源、表、列和行范围的授权，并支持即时策略和凭据撤销。 |
| 2026-09-02 | 已完成 | 添加多用户认证 MCP、PostgreSQL 支持的访问控制存储、事务本地主体上下文以及 PostgreSQL RLS 隔离。 |
| 2026-09-03 | 已完成 | 通过真实 PostgreSQL 17 测试、首次请求 MCP 查询启动、干净的 Linux CI 构建以及 A/B 员工行隔离验证，强化权限控制验收。 |
| 2026-09-04 | 已完成 | 添加有界查询结果交付：最多 50 行和 128 KiB 内联，否则提供可撤销的 15 分钟 CSV 工件，包含 20 行 Agent 预览和 16 MiB 上限。 |
| 2026-09-10 | 已完成 | 添加版本化的详细查询错误和跟踪、独立的 30 天诊断、显式反馈和经审查的回归案例，以及 Core 强制执行的查询澄清规则。 |
| 下一步 | 计划中 | 将受治理的查询执行扩展到 PostgreSQL 之外，同时保留相同的策略、限制、审计和取消契约。 |
| 下一步 | 计划中 | 添加由 DuckDB 支持的托管 CSV/Excel 摄取工作流，而不向 Agent 暴露上传的文件或本地路径。 |
| 稍后 | 计划中 | 在 alpha 安装和升级流程稳定后，发布版本化的 SemaRail Core 包。 |

技术栈

- Python 3.11+
- TypeScript 和 Node.js
- React 18 和 Vite
- Model Context Protocol (MCP) Python SDK
- 用于结构化 SQL 验证的 sqlglot
- 用于受治理查询执行的 PostgreSQL
- 用于 Console 元数据工作流的 PostgreSQL、MySQL、SQLite、ClickHouse 和 DuckDB 驱动

快速开始

安装 SemaRail Core

要求：

- Node.js ^22.19.0 || >=24
- Python >=3.11

在该包发布之前，请从仓库构建本地 Core tarball：

pnpm install
pnpm package:core
npm install --global .\dist\hejielijob-semarail-core-0.1.0-alpha.4.tgz
$env:SEMARAIL_API_TOKEN = semarail token create
semarail start --project C:\path\to\semantic-project

Core 进程负责管理语义项目、数据库凭据、执行限制、Semantic Console 和 MCP 服务器。启动后打开 http://127.0.0.1:48763。请对 SEMARAIL_API_TOKEN 保密：它是本地引导管理员凭据，用于创建范围更窄、可撤销的服务账户密钥。

从源码运行

要求：

- Git
- Node.js ^22.19.0 || >=24
- pnpm 11.x
- Python >=3.11
- 仅当你想执行受治理查询时才需要 PostgreSQL

git clone https://github.com/hejielijob-commits/SemaRail.git
cd SemaRail
pnpm install
pnpm build

如需针对 100,000 名合成员工和五个授权角色进行更大规模、可复现的本地验证，请参阅 HR 企业基准测试。它独立于 CI 运行，并且需要 Docker。

HR 企业基准测试：概览与结果

该基准测试包含 60 个取自企业 HR 场景的固定问题，
构建在包含 100,000 名员工和 190 万行 PostgreSQL 数据的可复现数据集之上。
它包含 30 个基础报表问题、15 个跨模型分析问题，以及 15 个授权边界问题，使用中文和英文，覆盖五个企业角色。它们共同验证了 MDL 模型、关系、指标规则、SQL 知识、语义规划、受治理执行和访问控制。全部 60 个问题均通过。

已检入的语义层和评估证据包括：

- Wren MDL 项目
- 六个语义模型定义
- 模型关系
- HR 指标和授权规则
- SQL 知识示例
- PostgreSQL schema
- 60 个评估用例
- 评估过程与结果
- 机器可读的结果摘要

创建 Python 环境并安装语义运行时、MCP 服务器、Console、受治理 PostgreSQL 查询驱动和 Console 元数据驱动：

py -3.11 -m venv .venv
& .\.venv\Scripts\python.exe -m pip install
-e ".\python\sidecar[wren,mcp]"
-e ".\apps\semantic-console[wren]"

启动语义控制台

该仓库包含一个用于本地导览的确定性销售项目：

$stateDir = Join-Path $env:LOCALAPPDATA "semarail\semantic-console\sales-demo"
& .\.venv\Scripts\python.exe -m server
--project-dir .\examples\wren-postgres
--state-dir $stateDir
--static-dir .\apps\semantic-console\web\dist

打开 http://127.0.0.1:48763。服务器默认绑定到回环地址。

将 SemaRail 与 MCP 智能体配合使用

默认的多用户集成是 SemaRail 经过身份验证的 Streamable HTTP
MCP 端点。它向任何支持 MCP 的智能体公开相同的七个稳定工具：

- semarail_validate_project
- semarail_list_models
- semarail_get_context
- semarail_plan_query
- semarail_prepare_query
- semarail_governed_query
- semarail_submit_feedback

SemaRail MCP 集成

启动经过身份验证的 MCP

针对与 Core 相同的项目和状态目录启动 MCP 端点：

$env:SEMARAIL_API_TOKEN = ""
semarail mcp serve
--project C:\path\to\semantic-project
--state-dir C:\path\to\semarail-state

端点为 http://127.0.0.1:48764/mcp。引导令牌会初始化
共享控制平面存储，但会被远程 MCP 拒绝。在访问
控制中，创建一个服务账户，分配受信任属性，绑定
项目/数据源/表/列/行策略，并签发一次性密钥。在智能体的私有环境或密钥管理器中配置
该托管密钥：

{
"mcpServers": {
"semarail": {
"url": "http://127.0.0.1:48764/mcp",
"transport": "streamable-http",
"headers": {
"Authorization": "Bearer ${SEMARAIL_TOKEN}"
}
}
}
}

每次调用都会重新验证密钥或员工会话，并读取当前策略，
因此禁用账户、撤销密钥、更改属性或解绑
策略都会影响下一个请求。数据源凭据和项目路径保留在
Core 内部，绝不会进入 MCP 客户端配置。回环地址是安全的
默认值；非回环绑定需要显式的 --allowed-host 和 TLS
反向代理。

受治理的查询结果使用有界交付契约。最多 50
行且其 UTF-8 JSON 表示最多为 128 KiB 的结果保持内联。更大的
结果最多返回 20 行预览以及一个临时 CSV 下载 URL；
完整 CSV 绝不会插入模型上下文。下载在 15
分钟后过期，并且当签发凭据、主体、
数据源或策略上下文不再是最新时立即失效。alpha 查询上限
仍为 500 行，CSV 上限为 16 MiB；这不是批量导出 API。
管理员可以将 SEMARAIL_ARTIFACT_TTL_SECONDS 设置为 60 到
86400 秒之间的值；默认值为 900 秒，MCP 调用方无法覆盖它。
在生成候选语义 SQL 后，Agent 会调用 semarail_prepare_query，并传入提取出的业务条件。Core 会应用为所引用模型发布的规则，并返回 ready、needs_clarification 或 blocked。必需条件或可显式确认的条件不能通过直接调用查询端点来绕过，包括通过较旧客户端调用。开放式语言解释和答案提取仍由 Agent 负责；Core 验证结构化条件和单次查询准备记录。

semarail_submit_feedback 被明确声明为写操作。它只接受当前调用方拥有的查询或 trace，并支持幂等重试。失败会被自动捕获，并带有有界的脱敏问题/SQL 证据；成功执行仅保留元数据，除非用户提交反馈。不会存储结果行或完整的 Agent 对话。管理员可以在 Console 的 Issues & feedback 和 Regression cases 页面中对问题进行分类、推进其工作流、关联重复项、创建经过审查的回归用例，并导出版本化 JSON。

服务账号、员工和行权限（alpha）

SemaRail Core 包含一个本地管理 API，用于服务账号和外部认证员工、一次性 API key 签发、密钥轮换/撤销、短期员工会话、版本化策略绑定和审计事件。策略可以限制工具范围、项目、物理表、列、查询限制，以及从可信主体属性派生的行。强制行谓词会在执行前使用绑定的数据库参数注入；缺失或格式错误的权限会以失败关闭方式处理。

例如，两个 agent 可以运行相同的销售查询，而账号 A 被限制为区域 CN-JIA，账号 B 被限制为 CN-YI。更新账号属性或策略会在下一次请求时生效。参见 Access control (alpha) 和 the architecture decision。

员工可以通过配置的 DingTalk 或通用 OIDC provider 使用 semarail auth login --provider  登录。浏览器回调永远不会收到 SemaRail bearer token；发起登录的 CLI 会用一次性 device code 交换一个有界会话，然后进入与 API key 相同的 Subject/PolicyEngine 路径。新员工在管理员于 Access control 中分配可信属性和策略之前没有数据策略。有关 provider 配置和安全边界，参见 Access control (alpha)。

已认证 stdio bridge

对于仅支持 stdio 的 Agent，登录一次并将 bridge 配置为其 MCP 命令：

semarail auth login --provider dingtalk --endpoint http://127.0.0.1:48763
semarail mcp bridge --endpoint http://127.0.0.1:48763

bridge 会读取由 semarail auth 写入的受 ACL 保护的员工会话
login，并将每个工具转发到 Core 的已认证运行时。它不会加载
Wren、打开数据库、接受 Subject/policy/DSN 参数，或打印令牌。
对于服务账户，改为在桥接进程的
私有环境中设置 SEMARAIL_MCP_TOKEN。使用 --token-env  选择另一个环境
变量名。

受信任的本地操作员兼容性

semarail-mcp 和 semarail-query-mcp 仍然可用，以保持兼容性和
隔离的本地评估。它们直接加载项目/Sidecar，因此不提供
按用户解析 Subject、即时策略变更或
身份审计。不要将它们用作共享员工或多租户边界。
请改用已认证的 HTTP MCP 或 semarail mcp bridge。

使用以下命令运行 MCP 验收测试：

pnpm acceptance:mcp
pnpm acceptance:core

安全模型

所有模型生成的 SQL 都被视为不受信任的输入。

- PostgreSQL 语句使用 sqlglot 进行结构化解析。
- DML、多语句 SQL、危险函数和未授权对象会失败关闭。
- 查询执行使用只读账户，并带有行数、字节数、超时、并发和取消限制。
- PostgreSQL 部署可以添加事务本地 Subject 上下文和原生 RLS 作为第二层强制执行；请参阅 PostgreSQL 行级安全。
- 协议和展示负载是 JSON 安全的并带版本；未知版本会失败关闭。
- Sidecar stdout 仅用于协议；诊断信息发送到 stderr。
- 数据源凭据保留在服务器端，并在 Console API 响应中被脱敏。
- 在此 alpha 版本中，Console 仍然仅限回环地址。Subject 策略、表/列/行授权、PostgreSQL RLS 上下文、可选的 PostgreSQL 控制平面存储，以及仅元数据审计事件均已实现。互联网暴露仍然需要加固的反向代理、TLS、部署监控、备份/恢复，以及组织特定的身份配置。

仓库布局

| 路径 | 用途 |
| --- | --- |
| apps/semantic-console | 本地 Python 服务器和 React Semantic Console。 |
| python/sidecar | 语义规划、SQL 策略/执行、分帧 RPC 和 MCP 服务器。 |
| packages/contract | 共享的带版本 Core、MCP 和 Console 契约。 |
| packages/core | 可独立安装的 SemaRail Core CLI/运行时发行版。 |
| examples/wren-postgres | 确定性的销售项目和黄金问题语料库。 |
| scripts | 打包、验收和评估门禁。 |

开发

pnpm typecheck
pnpm test
pnpm build
pnpm acceptance:core
pnpm acceptance:mcp

额外的集成门禁：

运行真实的 PostgreSQL 17/RLS 门禁。它需要管理员设置，并
创建然后清理隔离的测试数据库/角色夹具。
pnpm acceptance:postgres
运行 PostgreSQL 控制存储、诊断、反馈、回归和
澄清门禁。管理员 URL 仅从此环境读取
变量；脚本会创建一个隔离的数据库并在完成后将其删除。
$env:SEMARAIL_ACCEPTANCE_ADMIN_DATABASE_URL = ""
pnpm acceptance:control-postgres
在不更改数据库的情况下预览 PostgreSQL 验收前置条件。
& .\.venv\Scripts\python.exe scripts\acceptance-postgres.py --dry-run
pnpm evaluate:golden --self-test

在提交拉取请求之前，请参阅 CONTRIBUTING.md。请通过 SECURITY.md 中的私密流程报告安全问题，而不要通过公开 issue 报告。用户可见的变更记录在 CHANGELOG.md 中。

当前范围

- SemaRail 的语义 MCP 接口可以使用所配置语义配置文件支持的数据源。
- 通过 MCP 进行受治理的查询执行目前仅支持 PostgreSQL。
- Semantic Console 支持 PostgreSQL、MySQL、SQLite、ClickHouse 和 DuckDB 的连接测试、模式浏览和模型导入。
- 当前语义运行时不支持 View 到 View 的引用；嵌套 View 依赖会在执行前被拒绝。

上游基础

SemaRail 基于 WrenAI 代码库及 Python SDK/Core 并对其进行了改编。它目前使用 wrenai==0.13.2 及其公开的 context、validation、build、field-registry 和 project-format API。

SemaRail 是一个独立项目，不是 WrenAI 的官方发行版或 Canner 产品，也未获得 Canner 的认可或与其存在关联。SemaRail 名称和品牌独立于上游项目。

许可证

本仓库根据 MIT License 发布，版权所有 © 2026 hejielijob-commits。

第三方组件保留其各自的许可证：

- wrenai==0.13.2 声明自身为 Apache-2.0，并由 WrenAI 项目维护。
- Semantic Console 捆绑了其浏览器依赖；其许可证文件
在 Core 制品中暂存于 semantic-console-web/licenses 下。

有关依赖项和制品归属清单，请参阅 THIRD_PARTY_NOTICES.md。