Nifra docs

Nifra

面向 AI 的 TypeScript 框架。
在五种 UI 库上提供类型化 API 和全栈 SSR，同一个应用可运行于 Bun、Node、Deno 和 edge 环境——
让人类和编码 Agent 都能安全地修改它。

文档 · 在线体验 · 基准测试 · 与其他框架的比较

---

Nifra 面向构建、运营和使用过程中都有 Agent 参与的软件。

Agent 不应只是硬套在应用上的聊天气泡，也不应是只能猜测 API 的编码助手。 它应能发现真实契约、调用类型化能力、将进度流式传输到 UI、在适当的边界请求批准、乐观地更新状态、与服务端协调，并留下工作确实已完成的证据。Nifra 将这些整合为一个系统：

• **构建层：**类型化 API、运行时 Schema、无需代码生成的客户端、全栈 SSR，以及可运行于五种 UI 库和五种运行时的单一应用。
• **Agent 层：**页面级 WebMCP、远程 MCP/MCP Apps、A2A 和 AG-UI，共用同一套能力与工具契约。
• **执行层：**有界的 Agent 执行轮次、预算、审批、幂等性、取消、可恢复的证据，以及与提供商无关的模型接口。
• **UI 层：**确定性的预测式 UI、共享运行状态、流式增量、人在回路中的决策、不包含内容的浏览器视图，以及 Run Studio。
• **验证层：**实时 MCP 项目上下文，以及类型检查、路由保证、效果溯源、清单和基于契约的验证门槛。

一个契约，覆盖每个层面。

核心设计决策很简单：只定义一次能力，然后将其映射到适合当下场景的层面。页面级 Agent 可在页面打开时使用 WebMCP；后台 Agent 可使用远程 MCP；其他 Agent 可使用 A2A；面向人类的客户端可使用 AG-UI。它们仍共享相同的类型化验证、授权、审批、输出和证据边界。

import { t } from "@nifrajs/schema"
import { defineAgentCapability, registerWebMcpTools } from "@nifrajs/webmcp"

export const addToCart = defineAgentCapability({
  name: "cart.add",
  description: "Add a product to the current cart.",
  input: t.object({ sku: t.string(), quantity: t.number() }),
  output: t.object({ cartVersion: t.string() }),
  writes: ["cart"],
  execute: (input) => addItemOnTheServer(input),
  predict: ({ input, version }) => ({
    baseVersion: version,
    patch: [{ op: "add", path: "/items/-", value: input }],
  }),
})

// Explicit page-local discovery. Unsupported hosts receive a safe no-op report.
await registerWebMcpTools([addToCart])

同一个 addToCart.tool 可映射到 Nifra 的远程 MCP 适配器，也可由 Agent 运行器调用。预测由确定性的应用代码生成，而非由 LLM 猜测；提交、回滚、冲突、过期和权威协调都是明确的结果。

请参阅 WebMCP 和预测式 UI 指南以及 Agent 层。

从类型化后端开始

bun create nifra my-app # scaffold the API starter
cd my-app
bun install
bun run dev

对于带 SSR 的全栈 React 应用：

bun create nifra my-app --template site --framework react

或者为现有项目添加后端：

bun add @nifrajs/core @nifrajs/schema @nifrajs/client

import { server } from "@nifrajs/core/server"
import { t } from "@nifrajs/schema"

export const app = server()
  .get("/users/:id", (c) => ({ id: c.params.id }))
  .post("/users", { body: t.object({ name: t.string() }) }, (c) => ({
    id: crypto.randomUUID(),
    name: c.body.name,
  }))

客户端类型会从服务端类型推断得出——无需代码生成、重复定义架构，也不会有过时的 SDK：

import { client } from "@nifrajs/client"
import type { app } from "./server"

const api = client<typeof app>("http://localhost:3000")
const result = await api.users({ id: "42" }).get()

if (result.ok) result.data.id   // route return type, checked by tsc
else result.error               // failures are returned, never thrown

修改路由后，所有调用方都会停止编译，直到完成更新。随着应用增长，添加加载器、操作、流式传输、 defer()/<Await>、孤岛、查询缓存、渐进增强表单和服务端函数。同一 Web 层可运行于 React、Vue、Solid、Svelte 或 Preact。

Web 层还能让页面保持最新且快速，无需第二套数据层：

• 实时刷新——加载器通过 live(...) 声明读取的键；发布内容后，所有打开的标签页中只有对应加载器会重新加载，并通过导航时运行的同一套中间件、门控和加载器执行。
• 部分预渲染（实验性）——所有访客共享的页面部分会一次性从缓存提供，每位访客专属的部分则会随着对应加载器完成而流式传输。
• 所有五种适配器均支持服务端组件——React RSC/Flight，以及其他适配器的原生服务端渲染区域。
• 保持页面存活——前进和后退时，页面会连同状态、滚动位置和焦点一起恢复。
• SSG 和 ISR 支持按标签清除缓存，并按顺序清除数据缓存、页面存储、实时页面和 CDN，确保写入者能读到自己写入的数据。

Agentic 后端：有界、类型化、可观测

Nifra 也为产品本身就是 Agent 的应用提供运行时。模型提供商、凭据、持久化状态、租户管理和策略均通过注入的接口提供；框架负责其周边的安全和执行语义。

import { createAgentState, runAgent } from "@nifrajs/agent"

const result = await runAgent(definition, { value: input }, ports, {
  state: createAgentState("support-1"),
  maxTurns: 8,
})

你将获得类型化工具契约、有界轮次与预算、审批、取消、幂等性、可恢复的纯令牌证据、模型/令牌流式传输、临时共享状态以及可组合的遥测。独立的 nifra-agent 主机可将未通过轮次后门控的情况转为有界修复轮次。本地进程和扩展适配器可以隔离崩溃和意外情况，但并非用于运行恶意代码的沙箱。

Agentic UI：从意图到可见状态

UI 并非事后才考虑的部分。Nifra 为 Agent 提供了多种经过精心设计的应用交互方式：

界面	适用场景	Nifra 的契约
WebMCP	Agent 在当前打开的页面中执行操作	显式工具允许列表、类型化输入/输出、有界回执、确定性预测、版本化协调
MCP / MCP Apps	远程工具、后台工作和丰富的工具结果	同一核心工具可映射至远程 MCP 和 ui:// 小组件
AG-UI	将 Agent 运行过程流式传输到产品 UI	SSE 生命周期、文本/推理/工具增量、共享状态快照/增量、可恢复证据、类型化恢复
Agent App / Workbench	浏览器和桌面控制平面	协商功能、审批、交接、决策收件箱、能力注册表、Run Studio

对于预测性交互，应用会提供纯补丁和协调规则。存储会原子地应用补丁，然后接受权威服务端状态，或报告回滚、冲突或过期。即使没有 Agent 主机，人类用户界面也能完全正常运行。

无需重写 Agent 即可实现互操作

运行器是中心；协议适配器是边缘：

• @nifrajs/mcp 提供工具和 MCP Apps。
• @nifrajs/webmcp 提供显式的页面本地工具和预测式 UI。
• @nifrajs/a2a 挂载 A2A 1.0 卡片以及 JSON-RPC/SSE。
• @nifrajs/ag-ui 通过 SSE 挂载 AG-UI 事件。
• @nifrajs/agent-app 提供与后端无关的浏览器客户端。
• @nifrajs/coding-agent、@nifrajs/agent-protocol 和 @nifrajs/pi 提供独立的编码 Agent 宿主；@nifrajs/acp 可通过该宿主驱动任意 Agent Client Protocol Agent。

每个协议边界仍需应用级身份验证和授权。公开的参考适配器将凭据、持久化存储、租户状态和运维策略留在包外，以便你为部署提供合适的实现。

为编码 Agent 提供实时项目，而非过时文档

注册一次 Nifra，Agent 就能检查实际项目、获取经过版本校验的示例和类型、在正确的路由目录中搭建脚手架、运行 HTTP/SSR/WebSocket 检查、检查近期请求，并针对结构化修复反复迭代：

claude mcp add nifra -- bunx nifra mcp
nifra init-agents

nifra context       # live route and convention map
nifra smoke         # real SSR, API, auth and hydration requests against the build
nifra check         # typecheck, drift, and bundle-boundary gate
nifra assure        # route security evidence gate
nifra levels        # cumulative proof level and next missing rung

本地服务器在你的代码所在位置运行——你的源代码绝不会传到 Nifra。教学工具也托管在 mcp.nifra.dev，供只需使用经过验证的 Nifra 语料库的 Agent 使用。Pi 和 Claude Code 均有可用的技能。

用证据说话，而非空口承诺

Agent 系统需要的不只是“模型说它成功了”。Nifra 将重要声明转化为门禁：

nifra check
nifra assure
nifra capabilities check
nifra manifest diff
nifra levels --min 1

• nifra check 会捕获类型偏移、绕过类型化客户端的原始调用、仅限服务端的包泄漏以及其他契约违规。
• nifra assure 会对实时路由图进行分类；如果缺少必要的身份验证、验证、速率限制、CSRF 或请求体大小上限证据，就会失败。
• nifra capabilities check 会将声明的效果令牌与模块图和经过审核的锁文件进行比较。
• nifra manifest diff 会在晋级时检测契约、保障、效果和响应敏感性方面的变化。
• nifra levels 会报告项目实际达到的最高累积证明级别，从类型化契约到契约派生的不变量测试。

文档和示例均基于实时 API 编译，可供机器读取的 MCP 语料库则从构建后的包生成。Agent 获得的是可修复的诊断，而不是过时的建议。

全栈可移植性，无框架负担

应用生命周期为 app.fetch(Request): Promise<Response>。定义一次，即可通过小型适配器部署到 Bun、Node、Deno、Cloudflare Workers/Pages 或 Vercel Edge。Web 层支持 React、Vue、Solid、Svelte 和 Preact，且无需更改路由/数据模型。

site/shared/data/benchmarks.json 中发布的快照是网站表格和基准测试对比文章的事实来源。基准测试套件通过 bench/site-bench.ts 将最新结果合并到该文件中。公开表格也包含 Nifra 表现较差的项目，并将纯 HTTP、中间件形态的 HTTP、动态 SSR 和可缓存 SSR 结果分别列出。

请参阅基准测试方法和完整结果，也可以自行运行 bun run bench:http / bun run bench:ssr。

完备组件（56 个包，均有类型定义，全部可选）

包按用途分类：

层级	包
后端	core · schema · client · middleware
全栈 Web	web · web-react · web-vue · web-solid · web-svelte · web-preact · web-vanilla · cache · i18n · image · content
运行时	node · deno · edge · workers · aws-lambda
Agent 运行时	agent · prompt · runner · agent-telemetry
Agent UI 和协议	webmcp · agent-app · mcp · a2a · ag-ui
编码 Agent	coding-agent · agent-protocol · pi · acp · skills
应用服务与质量	auth · better-auth · authjs · jobs · cron · storage · uploads · testing · mock · otel
工具	cli · create-nifra · devtools · ts-plugin

所有包均为可选且有类型定义。从核心包开始，然后仅添加产品所需的功能。浏览完整文档。

开发

bun install
bun run check          # lint, typecheck, tests, docs, corpus, and size gates
bun run build          # emit dist/ for all packages
bun run bench:http     # reproducible HTTP matrix

欢迎贡献，详见 CONTRIBUTING.md。采用 MIT 许可。