Foundgine - 面向.NET的可编程语义执行平台

什么是 Foundgine

现代应用正面临着前所未有的调用方复杂度。Web 端、移动端、REST API、GraphQL 客户端、内部服务、自动化任务，以及日益增长的 AI 智能体——每一种调用方都可能各自实现一套授权、校验、查询翻译和数据访问逻辑。当这些逻辑分散在不同的接口层时，安全边界变得模糊，授权规则难以统一维护，执行语义也容易出现分叉。

Foundgine 是面向 .NET 的可编程语义执行平台，它在这些调用方与其可执行的数据和操作之间，建立了一道受控边界。与其让每个调用方自行实现校验、授权、查询翻译和数据访问，Foundgine 将结构化意图（Intent）转化为一份经授权的执行计划，并通过提供者（Provider）来执行该计划。

调用方描述其需求。Foundgine 决定哪些被允许、如何执行，以及由哪个提供者执行。

这条核心理念背后是一条完整的执行管线：

意图（Intent）
  ↓
语义模型（Semantic Model）
  ↓
解析（Resolution）
  ↓
授权（Authorization）
  ↓
计划（Plan）
  ↓
重写 / 优化（Rewrite / Optimize）
  ↓
提供者编译（Provider Compilation）
  ↓
执行（Execution）
  ↓
结果 + 证据（Result + Evidence）

需要澄清边界：Foundgine 不是 ORM 替代品、不是数据库、不是 GraphQL 服务器、不是大语言模型、不是智能体框架，也不是身份提供者。它是一个可以置于这些系统之下的执行层——为"系统所求"与"应用愿意执行什么"之间提供稳定、可验证的语义执行边界。这一边界既服务传统软件，也服务智能体。

核心架构与技术细节

Foundgine 的架构设计遵循严格的关注点分离原则，每个组件只负责一个职责：

• 语义模型（Semantic Model）——定义面向应用的能力面，与具体持久化细节无关。

• 意图（Intent）——描述调用方想要什么，但不直接绑定到物理提供者。

• 授权（Authorization）——判定请求操作中哪些部分被允许，可为执行计划贡献谓词或约束。

• 规划器（Planner）——构建与提供者无关的操作表示。

• 重写与优化（Rewriting & Optimization）——在保持语义和授权约束的前提下转换计划。

• 提供者（Provider）——将计划编译并执行到具体后端。

多调用方，同一执行模型

REST / API
GraphQL
JSON
AI 智能体
自动化
   │
   ▼
语义意图（Semantic Intent）
   │
   ▼
Foundgine 规划器
   ├── SQL
   ├── InMemory
   └── 未来提供者

这一设计的根本目的，是避免为每种接口单独实现一套执行语义。无论调用方使用 GraphQL 选择集、JSON 结构还是 MCP 协议，最终都归一化为语义意图，交由同一套规划与执行管线处理。

中间计划为何重要

计划（Plan）是语义意图与物理执行之间的架构边界。它给运行时提供了以下能力：

• 保留授权约束

• 校验依赖关系

• 重写操作

• 估算成本

• 推断提供者能力

• 优化执行

• 生成执行证据

语义模型 vs. 持久化模型：持久化模型描述数据如何存储，语义模型描述应用愿意暴露和操作什么。两者不必一致——语义表面可以比物理模型更小、更安全、更有目的性。例如，持久化模型可能包含 TenantId、InternalRiskScore 等内部字段，而面向应用的语义模型并不会暴露这些字段。

Foundgine 与 AI 智能体

AI 智能体的兴起让执行边界变得比以往更重要。一个 AI 模型可以决定它想要达成什么目标，但它不应成为决定自己可以访问哪些应用数据的权威，也不应持有数据库凭据。

对比两种范式：

朴素模式：AI → 生成 SQL → 数据库。这种模式下，模型直接产出的 SQL 绕过应用层授权，数据库凭据暴露给模型层，安全风险极高。

Foundgine 模式：

AI 智能体
    │
    │ 结构化意图
    ▼
Foundgine
    ├── 解析（resolve）
    ├── 校验（validate）
    ├── 授权（authorize）
    ├── 规划（plan）
    └── 执行（execute）
            │
            ▼
        PostgreSQL

Foundgine 刻意与"AI 生成 SQL → 直接命中数据库"的路线不同。它让应用始终掌控授权与执行，同时允许 AI 和其他结构化调用方复用应用能力。

智能体相关包

• Foundgine.AI：基于 Microsoft.Extensions.AI 的 AI 工具集成。

• Foundgine.Agent.OpenAI：OpenAI 智能体接入包。

• Foundgine.MCP：通过 Streamable HTTP 传输（位于 /mcp）暴露语义能力，并提供 .well-known/mcp.json 主机级发现元数据。身份、租户上下文与授权仍由宿主持有，经 SecurityExecutionContext 注入。

供应链端到端基准

Foundgine 的验证体系包含一个供应链端到端（Supply Chain E2E）基准工作流：智能体 → MCP → Foundgine → PostgreSQL。该工作负载涵盖客户、订单、订单项、产品、供应商、分类、库存、仓库、发货与承运人，并在客户、客服、仓库、采购和管理员身份之间混合有效、无效与未授权操作。其中 PlaceOrder 作为高保证纵向切片，集成了授权、所有权校验、验证、服务端定价、库存检查、原子变更、幂等/重放保护与执行证据。

性能证据

为了验证查询性能优势，Foundgine 在 CoffeeBeanery PostgreSQL 图基准中执行了确定性工作负载。基准夹具包含 1,000 个客户、4,000 个关系、12,000 个合同、48,000 笔交易，并发级别为 1/8/32，每个场景测量 10 秒、预热 3 秒、请求超时 5 秒。关联结构为 Customer → CustomerBankingRelationship → Contract → Transaction。

并发 32 下的查询结果

对应的相对提升约为：

• 20.0 倍吞吐量（无缓存）、20.4 倍（有缓存）

• p95 延迟降低 16.7 倍（无缓存）、17.0 倍（有缓存）

值得注意的是，大规模查询优势并不依赖提供者计划缓存——即使关闭缓存，Foundgine 仍能达到约 20 倍的吞吐量提升。

可靠性

三次独立成功运行报告：0 应用错误、0 请求超时、0 取消请求。

需要明确的是：这些结果是特定工作负载下的证据，并非声称 Foundgine 在所有场景下都快于每种 EF Core 或 GraphQL 工作负载。结果取决于工作负载、schema、提供者版本、宿主机、夹具与实现版本。变更（Mutation）性能波动较大，当前不应作为主要性能主张。

生态、包与集成

Foundgine 以协调的 NuGet 包生态发布，而非单一单体库。这为用户提供了从提供者无关契约、语义、规划、执行到 SQL、AI、MCP、GraphQL、AOT 与高保证授权的清晰路径。

NuGet 快照：最新版本 0.5.2，目标框架 .NET 9.0，18 个已发布包，包集总计 7,801 次下载。

注：下载量为 NuGet 报告的包下载次数，非唯一用户或安装数。

集成表面

GraphQL：Foundgine.GraphQL.HotChocolate 适配器将 GraphQL 选择集转换为 Foundgine 语义请求——GraphQL 只是接口，不成为执行模型。MCP：Foundgine.MCP 通过 Streamable HTTP 传输（/mcp）暴露语义能力，同一服务器元数据在 .well-known/mcp.json 中可用于发现工具。

独立安全评估

Foundgine 已由 UnofficialOS（独立的 AI 智能体与 MCP 工具社区目录）进行分析。其 AST 安全审计与验证 当前评分为 90/100，在边缘沙箱安全、开源许可合规、文档与快速上手质量、仓库卫生与来源追溯四项上获得满分。剩余分数差异记录在"生态与 MCP 对齐"类别，原因是该次扫描未检测到 MCP 实现证据——Foundgine 现已包含显式的 mcp.json 与 .well-known/mcp.json 发现元数据。

文档可通过发布站点 Foundgine.io 访问，并提供了 llms.txt / llms-full.md 机器可读文档索引，供 AI 智能体与 LLM 工具直接消费。

安全合规与高保证变更

Foundgine 将安全要求视为语义执行契约的一部分。安全不变量被传播到计划中，并在执行前对照提供者能力进行校验——这防止提供者在无法保持能力安全保证时静默执行该能力。

安全演进阶段

安全演进阶梯包括：不变量注册 → 计划级不变量证明 → SQL 提供者合规 → 高保证变更合规 → 跨提供者合规。

共享责任模型

Foundgine 的授权与执行边界旨在减少不安全访问路径，但应用安全仍是共享责任。身份验证、密钥管理、传输安全、速率限制、数据库权限和部署安全仍然属于应用和基础设施责任。

变更取消传播

变更取消被传播到提供者执行边界，取消检查失败后无法提交。

授权上下文生命周期安全

PostgreSQL 高保证授权上下文是生命周期安全的：操作者/租户身份不可变，版本严格单调递增，已删除身份保留版本墓碑，缺失配置的授权上下文失败关闭（fail closed）。生命周期写入使用与变更授权读取相同的行锁串行化边界。

授权上下文密码学完整性

持久化的 PostgreSQL 授权证据通过外部持有的 HMAC-SHA256 密钥，与其完整规范安全负载进行密码学绑定。密钥生命周期支持 active / verification-only / retired 三种状态，具有单调轮换溯源、原子不可变环快照，以及对持久化证据的安全退役检查。未知密钥、算法不匹配、篡改的操作者/租户/状态/版本/指纹值以及篡改的生命周期墓碑均失败关闭。密钥轮换通过验证密钥环支持，密码学材料始终保留在数据库之外。

验证门禁

Foundgine 的验证路径以分阶段门禁构建信任：

CI 发布工作流将单元、PostgreSQL 集成、授权渗透、对抗安全与性能作业设为包发布的前置条件。

快速上手与当前状态

开始使用 Foundgine 的第一步是访问官方文档：发布站点位于 Foundgine.io，包含"什么是 Foundgine"、架构、性能、AI 智能体与 PostgreSQL 等多个章节。

开发路径

建议的开发路径是先用 InMemory 提供者本地迭代，再迁移到 SQL。在无需数据库的情况下验证语义模型、授权规则与规划行为，可显著加速开发周期。

// 开发/测试阶段使用 InMemory 提供者
using Foundgine.InMemory;

// 语义调用方描述意图，Foundgine 解析/授权/规划并执行
// InMemory 提供者无需数据库即可运行同一套语义模型

生产部署时切换到 Foundgine.Sql，通过 PostgreSQL 提供者执行关系计划。当前版本目标 .NET 9.0，Foundgine.Aot 提供 Native AOT 部署所需的元数据属性与运行时支持。

成熟度预期

Foundgine 当前处于 0.5.x 阶段，公共 API 稳定性、提供者覆盖与生产部署模式应按项目当前的发布与兼容策略对待。每个版本的详细、标注日期的工程记录维护在 CHANGELOG.md 中。

仓库目录导航

对于面向智能体的上手路径，可使用机器可读的 llms.txt / llms-full.md 文档索引，让 AI Agent 和 LLM 工具直接消费 Foundgine 的架构、性能与集成信息。

常见问题