语义治理层 hejielijob-commits/SemaRail

SemaRail

受治理的语义层，帮 AI 智能体读懂业务数据，跑出安全、可审查的查询。

SemaRail 把数据库 schema、业务定义、关系、规则和已审核 SQL 变成一份语义上下文，让 AI 智能体始终按同一套口径使用。它提供可视化 Semantic Console 来管理这份上下文，提供稳定的 MCP 接口对接智能体，还提供受治理的查询边界，只做只读数据访问。

可选的 Codex 桌面端集成、元数据策略、Trace API 和回放校验，见 Codex desktop Trace v1。

SemaRail 不绑定任何智能体。只要客户端支持 MCP，就能通过带认证的 HTTP 端点或 stdio 桥接使用它的语义工具。

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

SemaRail Semantic Console overview

功能

- 可视化语义建模 —— 导入数据库 schema，管理模型、字段、关系、视图、cube、业务规则和已审核 SQL 知识。
- 不绑定智能体的 MCP 工具 —— 通过带认证的 Streamable HTTP 暴露语义上下文和受治理查询，并为有需要的客户端提供带认证的 stdio 桥接。
- 受治理的数据访问 —— 每个请求都解析到当前 Subject 和策略，用 sqlglot 解析生成的 PostgreSQL，强制表/列/行规则和物理对象白名单，并施加只读、超时、行数、字节数和并发限制。
- 有边界的智能体结果 —— 小结果直接内联返回，大结果转成短期有效的 CSV 下载，智能体上下文里只留 20 行预览。
- 企业身份与策略 —— 用可撤销的服务账号密钥，或钉钉/OIDC 员工会话；改权限不用重装智能体；审计决策时不存 SQL、结果行和密钥。
- 常见数据库元数据 —— 测试连接、浏览 schema、导入模型，支持 PostgreSQL、MySQL、SQLite、ClickHouse 和 DuckDB。
- 带版本的语义项目 —— 校验草稿，查看生成的源码和 diff，发布修订，回滚变更。
- 双语元数据 —— 同时维护英文和简体中文显示名，稳定的技术标识符不变。
- 可定位的查询诊断 —— 让 Core trace 贯穿策略、规划和执行，保留带版本的详细错误，并留存有边界、已脱敏的失败证据 30 天，不存结果行。
- 完整执行追踪 —— 把选择加入的 Codex 桌面回合按 Session → turn → Agent/subagent → tool → Core 回放，展示并行活动、观测到的耗时、错误，以及直接跳转到问题的入口。追踪事件只保留安全元数据，保存 30 天。
- 显式反馈与回归审查 —— 从 MCP 或 Console 链接提交调用方自有的反馈，在 Console 中分类，只导出经过审查、可复现的回归用例。
- 业务条件澄清 —— 发布结构化的指标、时间范围、粒度和业务定义确认规则；必需条件会阻止执行，直到 semarail_prepare_query 返回 ready。

数据源管理

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

数据源管理

语义模型工作台

编辑业务名称、描述、可见性、主键和字段字典，同时把生成的语义源码和统一 diff 放在旁边。

语义模型工作台

关系图

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

语义关系图

Agent Trace 工作台

打开 Quality → Agent traces（质量 → Agent 追踪），按时间浏览执行追踪，查看持久化的事件时间线。一个 Codex 聊天就是一个 Session；每个主 Agent 回合就是一条 Trace。

| Console 页面 | 新功能 |
| Agent traces / Agent 追踪 | 追踪列表、Session/turn/Agent/subagent/tool/Core 层级、并行活动、状态、观测到的耗时、Core 认证/策略/运行时阶段，以及证据链接。 |
| Issues & feedback / 问题与反馈 | 从 Core 的 traceId 打开来源 Agent Trace；失败的工具 Span 直接链接到对应问题。 |

失败子代理工具 Span，带 Core 证据和直接问题链接

查看完整 Trace 页面。

- 刷新会从持久化事件重建时间线。缺失的完成事件、未知的工具归属、运行中的 Span 和未知结果都有明确标签。
- 采集需要显式启用项目，并单独安装 SemaRail Codex Trace 插件。
在 Codex 中信任其当前钩子，然后开始新聊天；已有聊天不会回填。采集失败不会改变工具结果或执行。
- 提示词、模型输入/输出、工具参数/结果正文和转录不会保存为 Trace 数据。缺失的 LLM 耗时和 Token 事件显示 Not collected / 未采集。Agent/tool 区间是钩子观测到的耗时； Core 时长在 Core 内测量。
- 事件接入和管理读取都按项目范围校验权限；支持重复和乱序事件，Core 链接会校验组织、项目和主体归属，过期的 Trace 事件在 30 天后删除。Core RPC v3 在成功和失败时都提供关联 ID，同时保留 v1/v2 兼容性。

第一版提供结构化回放和错误定位。配置和验收细节见 Trace v1 安装、API、边界与桌面验证。

Trace v2：诊断、对比与查询回归

Quality 部分新增独立的 Trace comparison 页面，并为 Agent traces 扩展会话/主体/时间/状态/问题筛选、规则诊断和采集器健康状态。发现项会链接到观测到的证据；Core 慢阶段作为检查项。对比会保留所有观测到的语义版本，当任一 Trace 缺少元数据时，版本变更报告为未知。无法建立对应关系时，并行或不完整的活动保持未匹配。

Regression cases 支持注册测试数据集、审阅手动问题/SQL/澄清输入、创建草稿，然后编辑并启用带版本的断言，串行运行最多二十个用例，支持取消和持久化运行历史。
执行通过 Core 使用当前受管调用方，且仅在活动数据源与注册的测试环境匹配时运行。历史会链接到安全的 Core 诊断信息和来源问题/Trace。运行结果不保留结果值；不完整或含糊的结果标记为 inconclusive。从问题创建用例会打开空白手动表单；仅当其 Core 关联通过校验时，才填入反馈 ID 和 Agent Trace ID。取消是异步的，运行历史会在 worker 结束后报告终态。

可选的 Codex 插件会在后台投递前持久化安全事件，重试可恢复的失败，并暴露本地队列状态/flush/cleanup 命令。控制台健康报告会显示积压和新鲜度，但不估算未观测到的丢失。见 Trace v2 安装、契约与边界。

以下页面展示隔离的合成 HR 验收环境。

Agent traces：投递积压、重试与报告新鲜度

Trace collector health

Trace 详情：基于证据的诊断

Trace collector health and diagnosis

Trace 对比：失败执行与手动纠正执行

Trace comparison

Regression cases：已审阅断言、运行历史与 Core 证据

Query regression run

投递恢复、桌面关联、隐私和回归验证见 Trace v2 验收记录。

项目路线图

这份路线图列出项目的主要里程碑。文件级发布说明见 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 强制执行的查询澄清规则。 |
| 2026-09-30 | 已完成 | 新增 Agent Trace 工作台、仅采集元数据的 Codex 生命周期、Core RPC v3 关联、并行回放和双向问题导航；验证了启用和未启用桌面聊天两种情况。 |
| 2026-10-11 | 已完成 | 新增 Trace v2 投递恢复、采集器健康检查、基于证据的规则、独立 Trace 对比，以及经审核的手动查询回归，带持久历史和 Core 证据链接。 |
| 下一步 | 计划中 | 把受治理的查询执行扩展到 PostgreSQL 之外，同时保留同一套策略、限制、审计和取消契约。 |
| 下一步 | 计划中 | 新增由 DuckDB 支撑的托管 CSV/Excel 导入工作流，不向 Agent 暴露上传文件或本地路径。 |
| 后续 | 计划中 | 等 alpha 安装和升级流程稳定后，发布带版本的 SemaRail Core 包。 |

技术栈

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

快速开始

安装 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]"

启动 Semantic Console

仓库里带了一个确定性的销售项目，供本地体验：

$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。服务器默认绑定到回环地址。

配合 MCP 智能体使用 SemaRail

默认的多用户集成方式是 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 integration

启动带认证的 MCP

让 MCP 端点使用与 Core 相同的项目和状态目录：

$env:SEMARAIL_API_TOKEN = "<local bootstrap token>"
semarail mcp serve
--project C:\path\to\semantic-project
--state-dir C:\path\to\semarail-state

端点是 http://127.0.0.1:48764/mcp。bootstrap token 用来初始化共享控制面存储，但远程 MCP 会拒绝它。在 Access control 中创建服务账号，分配可信属性，绑定项目/数据源/表/列/行策略，然后签发一次性密钥。把该托管密钥配置到智能体的私有环境或密钥管理器中：

{
"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 后，智能体带着提取出的业务条件调用 semarail_prepare_query。Core 应用已为所引用模型发布的规则，返回 ready、needs_clarification 或 blocked。必需条件或需显式确认的条件无法绕过，直接调用查询端点也不行，用旧客户端也一样。开放式语言理解和答案抽取仍由智能体负责；Core 只校验结构化条件和单次查询准备记录。
semarail_submit_feedback 明确声明为写操作。它只接受当前调用方拥有的 query 或 trace，并支持幂等重试。失败会自动捕获，附带经过脱敏、长度受限的 question/SQL 证据；执行成功时只保留元数据，除非用户主动提交反馈。不存储任何结果行，也不存储完整的 Agent 对话。管理员可以在 Console 的 Issues & feedback 和 Regression cases 页面中为问题分类、推进其工作流、关联重复项、创建经过审核的回归用例，并导出带版本号的 JSON。

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

SemaRail Core 内置本地管理 API，用于管理服务账号和外部认证的员工，支持一次性 API key 签发、密钥轮换与吊销、短时效员工会话、带版本号的策略绑定以及审计事件。策略可以限制工具范围、项目、物理表、列、查询上限，以及由可信主体属性推导出的行。执行前会以绑定数据库参数的方式注入强制行谓词；权限缺失或格式错误时按失败关闭处理。

策略 schema 版本 2 还能通过当前 PostgreSQL 数据源中一张预先展开、按租户隔离的员工权限表来过滤业务行。该查询不递归、参数化、每次查询都会执行，并且不会让 Agent 直接访问权限表。参见 Access control。

例如，映射中包含 A -> B 和 B -> C 时，A 可以读取 B，但不会继承对 C 的访问权限。如果 A 应当同时看到两者，需要显式添加 A -> C。可信的 attributes.employeeId 值由管理员在 Access control 中维护；身份服务商展示的员工编号不会自动提升为可信值。PostgreSQL 配置档必须保留其密码（或使用等效的服务端密钥来源），这样 Core 才能在启动后重新连接。

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

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

已认证的 stdio 桥接

如果智能体只支持 stdio，登录一次，再把 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 login 写入的、受 ACL 保护的员工会话，把每个工具转发到 Core 的已认证运行时。它不加载 Wren，不打开数据库，不接受 Subject/policy/DSN 参数，也不打印 token。如果要用服务账号，就在 bridge 进程的私有环境里设置 SEMARAIL_MCP_TOKEN。用 --token-env <NAME> 可以指定另一个环境变量名。

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

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

运行 MCP 验收测试：

pnpm acceptance:mcp
pnpm acceptance:core

安全模型

所有模型生成的 SQL 都按不可信输入处理。

- PostgreSQL 语句用 sqlglot 做结构化解析。
- DML、多语句 SQL、危险函数、未授权对象一律 fail closed。
- 查询执行使用只读账号，并限制行数、字节数、超时、并发和取消。
- PostgreSQL 部署可以加上事务级 Subject 上下文和原生 RLS，作为第二层强制；见 PostgreSQL row-level security。
- 协议与展示载荷都是 JSON 安全的，并且带版本；未知版本 fail closed。
- 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 门禁。它需要管理员设置，会创建再清理隔离的测试数据库/角色夹具。该门禁还会验证 permissionLookup 主体、租户、非递归映射，以及映射表更新通过 framed Sidecar 的即时可见性。
pnpm acceptance:postgres
运行 PostgreSQL 控制存储、诊断、反馈、回归和澄清门禁。管理员 URL 只从这个环境变量读取；脚本会创建并删除一个隔离数据库。
$env:SEMARAIL_ACCEPTANCE_ADMIN_DATABASE_URL = "<PostgreSQL administrator URL>"
pnpm acceptance:control-postgres
预览 PostgreSQL 验收前置条件，不改动数据库。
& .\.venv\Scripts\python.exe scripts\acceptance-postgres.py --dry-run
pnpm evaluate:golden --self-test

提交 pull request 之前，先看 CONTRIBUTING.md。安全问题请走 SECURITY.md 里的私密流程上报，不要开公开 issue。用户可见的变更记录在 CHANGELOG.md。

当前范围

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

上游基础

SemaRail 基于 WrenAI 代码库和 Python SDK/Core 改编而来。目前使用 wrenai==0.13.2，以及它公开的 context、validation、build、field-registry 和 project-format API。

SemaRail 是独立项目，不是 WrenAI 的官方发行版，也不是 Canner 的产品，未获 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。