# @arnilo/liveframe 中文文档

规范地址：https://npmcn.com/package/%40arnilo/liveframe/

版本：0\.2\.3
npm 元数据更新时间：2026-11-04T15:48:29.535Z
中文译文更新时间：2026-11-06T20:02:39.381Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40arnilo/liveframe
原文对照：https://npmcn.com/package/%40arnilo/liveframe/?lang=original
项目主页：https://github.com/ashiqrniloy/liveframe#readme
源码仓库：https://github.com/ashiqrniloy/liveframe

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.8 MB，371 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react ^19\.0\.0，react-dom ^19\.0\.0，playwright ^1\.49\.0，@modelcontextprotocol/server ^2\.0\.0
- 首次发布：2026-10-26T20:09:23.198Z
- 最新版本发布：2026-11-04T15:48:29.225Z
- 近 30 天下载量：2621（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

运行时可编组的UI:原生,设计-系统配方和TSX部件,在没有部署的情况下改变应用程序的UI.

## 安装

```sh
npm install @arnilo/liveframe
```

也可以使用：`pnpm add @arnilo/liveframe`、`yarn add @arnilo/liveframe`、`bun add @arnilo/liveframe`

## README

# 内框

[![CI](https://github.com/ashiqrniloy/liveframe/actions/workflows/ci.yml/badge.svg)](https://github.com/ashiqrniloy/liveframe/actions/workflows/ci.yml)

运行时可编译应用程序的UI:在运行时人和AI代理安装了TSX部件,应用程序的UI会改变,没有部署.

一个应用程序载着一小组信任的人 **原始组件** (单位:千美元) **设计系统**部件是普通的TSX 写在那些原始人身上的 部件代码运行在应用程序的后端;浏览器只绘制一个具有应用程序自身组件的已验证树,因此UI看起来是本地的,页面中没有部件代码运行.

四条规则,没有一条是可选的:

1.  部件代码从未在浏览器中运行 。 只有应用的编译原始人运行在那里.
2.  UI树是数据,在被渲染者读取之前就被验证.
3.  部件代码从不设置颜色或原始 CSS 。 外观出自设计系统;布局出自于有符号约束的风格道具.
4.  部件从不拥有权威 。 数据被解决,动作由app运行,作为取景器.

[规格](https://npmcn.com/package/%40arnilo/liveframe/docs/spec.md) • 妇女 [如何建造地表](https://npmcn.com/package/%40arnilo/liveframe/docs/model.md) • 妇女 [安保模式](https://npmcn.com/package/%40arnilo/liveframe/docs/security.md) • 妇女 [兼容性](https://npmcn.com/package/%40arnilo/liveframe/docs/compatibility.md) • 妇女 [更改日志](https://npmcn.com/package/%40arnilo/liveframe/CHANGELOG.md)

## 安装

```bash
bun add @arnilo/liveframe
```

每个同位素是可选的,只有需要它的子路径:

| 端点 | 范围 | 需要满足 |
| --- | --- | --- |
| `react`, (中文(简体) ), `react-dom` | `^19.0.0` | `/react`, (中文(简体) ), `/preview/react`, (中文(简体) ), `/conformance/react` |
| `playwright` | `^1.49.0` | `liveframe preview capture`,MCP服务器的 `capture_preview` |
| `@modelcontextprotocol/server` | `^2.0.0` | `liveframe mcp` |

后端子路径( S)`/store/fs`, (中文(简体) ), `/preview/worker`,在流程中的包装器和CLI)需要Bun ≥ 1.4.2. 主机-API无子路径需要 ES2022 外加以下列出的全球. 浏览器子路径( N)`/css`, (中文(简体) ), `/react`, (中文(简体) ), `/preview/react`, (中文(简体) ), `/conformance/react`需要任何无害环境管理包件。 包船编译 ES2022 JavaScript 与 `.d.ts` 申报和出版的JSON Schemas; [第13节](https://npmcn.com/package/%40arnilo/liveframe/docs/spec.md#13-tech-stack-and-packages) 有运行时间矩阵和软件包内容.

| 无主机 API 子路径 | 非 ECMAScript 全球 |
| --- | --- |
| `.` | 无 |
| `sdk` | 无 |
| `css` | 无 |
| `authoring` | `TextEncoder`, (中文(简体) ), `TextDecoder`, (中文(简体) ), `URL`, (中文(简体) ), `console` |
| `runner-kit` | 无 |
| `preview/capture` | `TextEncoder`, (中文(简体) ), `TextDecoder`, (中文(简体) ), `URL` |
| `conformance` | `TextDecoder`, (中文(简体) ), `console` |
| `pack` | `TextDecoder`, (中文(简体) ), `console` |
| `store` | `console` |
| `preview` | `setTimeout`, (中文(简体) ), `clearTimeout`, (中文(简体) ), `TextDecoder`, (中文(简体) ), `console` |

路径相对 `@arnilo/liveframe`· ; `.` 是根导出 。 这个 `sdk` 行包括 `/sdk/gen` 以及JSX运行时间; `/runner-kit.bundle.js` 财务报告和审定财务报表 `/validator.bundle.js` 也无需非 ECMAScript 全球 。 条目包括捆绑的依赖关系: 橡子守护其未用 `console` 和包装器的源映射编码器可选使用 `TextDecoder` 带有纯JavaScript倒置. 预览定时器绑定模块加载;抓取需要编码和URL API. 作者到达捕获。 源、已编译的输出和浏览器捆绑将对照CI中的本表进行核对.

## 快速启动

编目,其反应执行和验证器都是表面需要的. `compileValidator` 取一个部件的已验证目录、能力和显示; `createRenderer` 返回时 `<Surface>` 画出它验证过的一棵树.

```tsx
import { type Catalog, compileValidator, defineComponent, obj, str, type UiTree } from "@arnilo/liveframe";
import { createRenderer, implement } from "@arnilo/liveframe/react";

const text = defineComponent({
  kind: "text",
  description: "One line of text.",
  props: obj({ value: str({ maxLength: 200 }) }),
  children: "none",
  variants: ["default"],
  defaultVariant: "default",
  slots: ["root"],
  events: {},
  styleProps: [],
  a11y: { role: "paragraph" },
});

const catalog = {
  format: "liveframe-catalog/1",
  catalogId: "acme.ui@1",
  description: "The app's primitives.",
  vocabulary: {
    colourRoles: ["text.primary", "surface.base", "accent.primary"],
    surfaceRoles: ["surface.base"],
    fillableRoles: ["accent.primary"],
    typographyRoles: ["body"],
    space: ["space.1"],
    radius: ["radius.control"],
    size: ["size.glyph"],
    breakpoints: ["bp.sm"],
    tones: { default: "text.primary" },
    surfaceTypography: "body",
  },
  definitions: [text],
} as const satisfies Catalog;

const capabilities = { format: "liveframe-capabilities/1", sources: {}, actions: {} };
const manifest = {
  format: "liveframe-manifest/1",
  id: "hello",
  version: "1.0.0",
  catalogId: catalog.catalogId,
  params: obj({}),
  state: obj({}),
  context: obj({}),
  initialState: {},
  sources: {},
  actions: [],
};

const Text = implement(text, ({ props, slot, style }) => (
  <p className={slot("root")} style={style}>
    {props.value}
  </p>
));
const { Surface } = createRenderer({ catalog, implementations: [Text] });
const validator = compileValidator({ catalog, capabilities, manifest });
const identity = { id: "acme", version: "1.0.0" };

/** Draw a validated tree that the app's backend rendered. */
export function Hello({
  tree,
  onIntent,
}: {
  tree: unknown;
  onIntent: (intent: { type: "setState" | "action" }) => void;
}) {
  return (
    <Surface
      tree={tree}
      validator={validator}
      theme={identity}
      designSystem={identity}
      onIntent={onIntent}
      fallback={null}
    />
  );
}

export const tree: UiTree = {
  format: "liveframe/1",
  catalogId: catalog.catalogId,
  surfaceId: "hello",
  revision: 1,
  root: { id: "root", kind: "text", props: { value: "Hello from Liveframe" } },
};
```

部件与 [SDK 软件](https://npmcn.com/package/%40arnilo/liveframe/docs/sdk.md),用于出口 `render()` jSX运行时间并释放出树 `Hello` 接收。 这个 [预览指南](https://npmcn.com/package/%40arnilo/liveframe/docs/preview.md) 显示执行部件代码的后端运行器,以及 [软件包指南](https://npmcn.com/package/%40arnilo/liveframe/docs/packages.md) 显示所制成的部件如何成为一个不可改变的软件包 .

对于流传更新, `diffTrees(prev, next)` 发出可选 `liveframe/tree-patch/1` 在后端上补丁,浏览器主机应用它 `applyPatch(base, patch)` 将被补丁的树传递到 `<Surface>` (在到达时验证整棵树):

```ts
import { applyPatch, diffTrees } from "@arnilo/liveframe";

const next = {
  ...tree,
  revision: 2,
  root: { id: "root", kind: "text", props: { value: "Hello again" } },
};
const patch = diffTrees(tree, next);
if (patch.ok) {
  const updated = applyPatch(tree, patch.value);
  if (updated.ok) Hello({ tree: updated.value, onIntent: () => {} });
}
```

## 包裹里有什么

| 导入 | 持有 |
| --- | --- |
| `@arnilo/liveframe` | 定义、目录、主题、设计系统、UI-tree和树标格式; `validateTreePatch`, (中文(简体) ), `diffTrees` 财务报告和审定财务报表 `applyPatch`; 验证器; 食谱解析器; `LiveframeFailure` 财务报告和审定财务报表 `LiveframeError` |
| `@arnilo/liveframe/sdk` | JSX运行时间(`/sdk/jsx-runtime`, (中文(简体) ), `/sdk/jsx-dev-runtime`(a) 故意帮助者 `render()` |
| `@arnilo/liveframe/sdk/gen` | 后面是主机侧发射器 `liveframe gen`数字 : `generate()`, (中文(简体) ), `generateDefinitions()` 财务报告和审定财务报表 `generateElementsSchema()` |
| `@arnilo/liveframe/react` | 制作者: `createRenderer()`, (中文(简体) ), `<Surface>` 财务报告和审定财务报表 `implement()` |
| `@arnilo/liveframe/css` | 范围 CSS 投影和类、 样式、 范围和可变帮助; 主机插入工作表 |
| `@arnilo/liveframe/pack` | 软件包和情景格式,结构验证器, `pack()`, (中文(简体) ), `verifyPackage()`, (中文(简体) ), `canonicalJson()` 财务报告和审定财务报表 `packageHash()` |
| `@arnilo/liveframe/store` | 记录格式 `Store` 接口, `memoryStore()` 财务报告和审定财务报表 `loadPlacement()` |
| `@arnilo/liveframe/store/fs` | `fileStore(dir)`,用于读取和写入文件系统 |
| `@arnilo/liveframe/preview` | 这个 `Runner` 接口, `inProcessRunner()` 财务报告和审定财务报表 `createPreview()` |
| `@arnilo/liveframe/authoring` | 没有MCP的8个打出作者操作;主机提供其跑取器 |
| `@arnilo/liveframe/runner-kit` | `renderModule()` 财务报告和审定财务报表 `linkPackage()`半个跑者 |
| `@arnilo/liveframe/runner-kit.bundle.js` | 包、 SDK 和校验器作为隔离设备的无导入ES模块 |
| `@arnilo/liveframe/validator.bundle.js` | 根导出为不渲染而验证主机的无导入 ES 模块 |
| `@arnilo/liveframe/preview/capture` | 以可插件后端的字节抓取 |
| `@arnilo/liveframe/preview/worker` | `workerRunner()`,则需要 `Worker` 全球 |
| `@arnilo/liveframe/preview/react` | `<Preview>` |
| `@arnilo/liveframe/conformance` | 免费主机API目录、设计系统和存储套件 |
| `@arnilo/liveframe/conformance/react` | 制造器套房和 `conformancePage()` |
| `@arnilo/liveframe/schemas/<format>.json` | 每个格式的 JSON Schema |

这个 [光谱](https://npmcn.com/package/%40arnilo/liveframe/docs/spec.md#13-tech-stack-and-packages) 定义每个子路径的合同.

## 用编码代理

`liveframe mcp` 是一个 [MCP 磁共振](https://modelcontextprotocol.io/) 服务器在 stdio 上让一个编码代理读取您的目录, 写一个草稿部件并查看它的成份 。 它只写: 没有安装、放置或批准部件或运行动作的工具 .

1.  安装可选对等器 : `bun add -d @modelcontextprotocol/server`,以及 `bunx playwright install chromium` 如果代理商应该抓取截图.
2.  写入默认导出一个配置模块 `AuthoringConfig` (你的电话) `catalog`, (中文(简体) ), `capabilities`, (中文(简体) ), `runner` 和,为了抓获,a `preview(binding)` 开始你的 `<Preview>` 页:1. [`examples/demo-host/mcp.config.ts`](https://github.com/ashiqrniloy/liveframe/blob/main/examples/demo-host/mcp.config.ts) 这是一个工作.
3.  与代理注册. 对于克洛德代码,放这个 `.mcp.json` 在您的应用程序中; Claude Desktop 和其他客户端使用相同的 `mcpServers` 形状 :

```json
{ "mcpServers": { "liveframe": { "command": "bunx", "args": ["liveframe", "mcp", "./mcp.config.ts"] } } }
```

客户端自己启动服务器. 这个 [MCP 指南](https://npmcn.com/package/%40arnilo/liveframe/docs/mcp.md) 涵盖8个工具,抓取和出错.

## 指南

-   [模型](https://npmcn.com/package/%40arnilo/liveframe/docs/model.md) ——何去何从,谁拥有每一步
-   [格式和验证](https://npmcn.com/package/%40arnilo/liveframe/docs/formats.md) ——目录,主题,设计系统,能力,运单,树木
-   [写入部件](https://npmcn.com/package/%40arnilo/liveframe/docs/sdk.md) - TSX SDK、意向助手和 `liveframe gen`
-   [铸造器](https://npmcn.com/package/%40arnilo/liveframe/docs/renderer.md) ——原始人,执行人, `<Surface>` 和意图处理
-   [样式](https://npmcn.com/package/%40arnilo/liveframe/docs/styling.md) ——食谱,三张单和范围CSS
-   [包、仓库和跑道](https://npmcn.com/package/%40arnilo/liveframe/docs/packages.md) —— 说 `pack()`, (中文(简体) ), `fileStore`, (中文(简体) ), `inProcessRunner`, (中文(简体) ), `workerRunner`
-   [预览和抓取](https://npmcn.com/package/%40arnilo/liveframe/docs/preview.md) 预览会话, `<Preview>` 财务报告和审定财务报表 `liveframe preview capture`
-   [遵约](https://npmcn.com/package/%40arnilo/liveframe/docs/conformance.md) 软件目录、造型、制造器和存储的测试工具箱
-   [MCP的代理作者](https://npmcn.com/package/%40arnilo/liveframe/docs/mcp.md) —— 说 `liveframe mcp` 及其八项工具
-   [代理通过演示](https://npmcn.com/package/%40arnilo/liveframe/docs/demo-agent.md) - 作者、抓取、安装和放置草稿
-   [安保模式](https://npmcn.com/package/%40arnilo/liveframe/docs/security.md) ——什么被验证在哪里,什么不是沙盒
-   [兼容性](https://npmcn.com/package/%40arnilo/liveframe/docs/compatibility.md) - 一个版本的突起可能改变

## 状态

前 1.0 (中文(简体) )`0.2.2` 是当前发布)。 公共 API、格式和光盘 `fileStore` 布局由 [兼容政策](https://npmcn.com/package/%40arnilo/liveframe/docs/compatibility.md); 数据 [发布注释](https://npmcn.com/package/%40arnilo/liveframe/CHANGELOG.md) 列出此发行的已知限制.

## 发展

```bash
bun install
bun run check   # build, generated output, typecheck, lint, format, tests
```

仓库布局、路线图和计划: [`roadmap.md`](https://github.com/ashiqrniloy/liveframe/blob/main/roadmap.md), (中文(简体) ), [`plans/`](https://github.com/ashiqrniloy/liveframe/blob/main/plans/README.md)与代理人合作: [`AGENTS.md`](https://github.com/ashiqrniloy/liveframe/blob/main/AGENTS.md)安全报告: [`SECURITY.md`](https://npmcn.com/package/%40arnilo/liveframe/SECURITY.md)。 。 。 .

## 许可证

麻省理工学院——见 [`LICENSE`](https://npmcn.com/package/%40arnilo/liveframe/LICENSE)。 。 。 .

## 常见问题

### @arnilo/liveframe 是什么？

运行时可编组的UI:原生,设计-系统配方和TSX部件,在没有部署的情况下改变应用程序的UI\.

### 如何安装 @arnilo/liveframe？

在项目目录运行 npm install @arnilo/liveframe，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 liveframe，可以用 npx liveframe 直接运行。

### @arnilo/liveframe 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @arnilo/liveframe 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @arnilo/liveframe 可以商用吗？

@arnilo/liveframe 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @arnilo/liveframe 的下载量有多少？

根据 npm 官方下载统计，@arnilo/liveframe 在 2026/10/07 – 2026/11/05 这 30 天内被下载 2,621 次，日均约 87 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @arnilo/liveframe 还在维护吗？

最新版本 0\.2\.3 发布于 2026/11/04（3 天前）；至今共发布 16 个版本，其中过去 12 个月发布了 16 个；首次发布于 2026/10/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。