# @aletheia-works/formicarium 中文文档

规范地址：https://npmcn.com/package/%40aletheia-works/formicarium/

版本：0\.12\.0
npm 元数据更新时间：2026-11-04T21:40:12.464Z
中文译文更新时间：2026-11-06T02:43:41.252Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：10.4 MB，41 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：0 个
- 首次发布：2026-10-10T10:37:05.610Z
- 最新版本发布：2026-11-04T21:40:12.097Z
- 近 30 天下载量：6172（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

在浏览器中运行未修改的x86-64 Linux CLI程序,并在 paludarium Web Assembly 模拟器上运行 Node.js

## 安装

```sh
npm install @aletheia-works/formicarium
```

也可以使用：`pnpm add @aletheia-works/formicarium`、`yarn add @aletheia-works/formicarium`、`bun add @aletheia-works/formicarium`

## README

# 天文馆

在浏览器和Node.js运行未修改的x86-64 Linux命令行程序, 没有启动内核。 家具包装 [陈列馆](https://github.com/aletheia-works/paludarium),一个用户模式 x86-64 Linux 仿真器编译到 WebAssembly (一个 Rust 的对应器) [罐/链接](https://github.com/jart/blink)),并给出一个小 JavaScript API: 给它一个静态的 Linux 可执行文件 和一些文件, 运行它, 并拿回去 退出代码,输出和它所撰写的文件. 目标是让一个 CLI 错误 复制在网页上以-s形式运行.

-   **试试看:** 页:1 [显示网站](https://aletheia-works.github.io/formicarium/) 有终端可以安装和运行 aube, bitchfork, Biome,纳米,jj 和 在您的 浏览器.
-   **软件包 :** [`@aletheia-works/formicarium`](https://www.npmjs.com/package/@aletheia-works/formicarium) 时间npm.
-   **联合国** 页:1 [站点](https://aletheia-works.github.io/formicarium/) 拥有指南(包括安装和命令API)和开发 节(运行时架构,设计决定),英文和日文.

## 状态

缩略语是年轻的(0.x),其API可能仍然会改变. 检查了什么 每一个变化 :

-   Rust探测器(线,定时器, `UnixStream::pair`, Rayon, 穆特克斯/ 康德瓦尔, 硬链接,符号链接, `flock`)通过Node.js,chromium,Firefox和WebKit.
-   Aube和pitchfork的多步骤会话输出与本地输出相同 x86-64 Linux (英语).
-   分布式JavaScript的行覆盖率保持在80%或以上.

它运行一个翻译器( 还没有 JIT), 因此重度程序比 当地人 CI 运行浏览器探测器、安装和命令检查 在 macOS 上以真实的 Safari 显示接受和显示网站接受; 其他浏览器套件使用 剧作家WebKit取而代之. 浏览器探测器以及安装和命令 在iOS 26 模拟器中还用 Safari 进行 iOS 的检查(尚未使用 iOS 27 safaridriver不能驱动;一个真正的iPhone没有测试.

## 安装

```sh
npm install @aletheia-works/formicarium
```

需要节点.js 24或后.

## 快速启动 (Node.js)

```js
import { createSession } from '@aletheia-works/formicarium/node';
import { decodeUtf8 } from '@aletheia-works/formicarium';

// guestBytes: a static ELF64 little-endian x86-64 Linux executable (Uint8Array).
const session = await createSession({ cwd: '/work', home: '/home/guest' });
try {
  const result = await session.run({ guest: guestBytes, args: ['--version'] });
  console.log(result.exitCode, decodeUtf8(result.stdout));
} finally {
  await session.dispose();
}
```

客人不包括在内。 将它们建为静态 musl 可执行文件, 或安装 它们来自安装 API (下方) 的目录 .

## 在浏览器中

导入 `createSession` 从 `@aletheia-works/formicarium/browser`。页面必须 能够使用 `SharedArrayBuffer`数字 :

-   服务页面 `Cross-Origin-Opener-Policy: same-origin` 财务报告和审定财务报表 `Cross-Origin-Embedder-Policy: require-corp` (或使用服务人员,例如: 固定主机服务员).
-   服务于软件包`runtime/web/package-worker.bundle.js`)和核心点 下级 `assets/paludarium/` 从您的页面来源.
-   允许在 例如,内容安全政策 `script-src 'self' 'wasm-unsafe-eval'; worker-src 'self'; connect-src 'self'`。 。 。 . `blob:` 无需.

这个 [嵌入引导](https://aletheia-works.github.io/formicarium/guides/embedding/) 有个完整的例子.

## API会做什么

-   **会议.** A 类 `Session` 在运行之间持有虚拟文件系统。 只有 工作目录和主目录持续存在;文件共享 `inodeId` 保持硬链接,同义链接保持链接,并保留模式。 运行使用之间 `listEntries`, (中文(简体) ), `readFile`, (中文(简体) ), `remove`, (中文(简体) ), `setCwd` 财务报告和审定财务报表 `reset`· ; `dispose` 关闭 永远的会面.
-   **运行.** 每跑一跑就开工一回和一回新核心. 会话运行一 时事`BUSY` (否则) 非零宾客通常会解决 带有退出代码和原始 stdout/stderr 字节; `onOutput` 流出它们 顺序。 主机,核心,超时(默认为600 000 ms, `timeoutMs` (改为) 和取消(`AbortSignal`(b) 以下列方式拒绝失败: `ExecutionError` 携带马厩 `code` (所有代码均列于 `ERROR_CODES` 报告 [错误代码](https://aletheia-works.github.io/formicarium/guides/errors/) 和部分产出。 当内部运行失败时 工人,他们 `cause` 链条名称原出错; 它保留 javaScript 引擎、 Web Assembly 或核心所撰写的信件, 仅限 其他错误的名称,因此,像 env 值这样的调用数据不包括在内。 A 类 失败或取消运行 离开文件系统原样。 作为互动嘉宾, `stdin` 溪流 其标准输入和 `terminal: { columns, rows }` 制定标准 流出一个终端; 运行 `stdin` 没有默认超时。 在一个 浏览器, 在一个页面上运行所有会话, 以一个开始其核心 时间(每个人等到跑步开始之前, 开始它的客人,结束,或 开始 10 s), 等待数 `timeoutMs`宾客 仍然同时运行.
-   **腾讯网.** 客人没有网络 除非跑道经过 `network: { allow: ['github.com:443'] }`。然后可以打开 TCP 连接 仅用于所列目的地,仅用于解决所列名称 其它失败 `ENETUNREACH` (一个没有来宾听众的回回地址) 与 `ECONNREFUSED`),嘉宾可以自行回转服务. TLS在客人里面运行,所以给它CA 证书。 浏览器没有 TCP 套接字, 因此浏览器运行也需要 `network.relay: { url, protocols? }`,例如 `@aletheia-works/paludarium-wasm/relay` 服务; 没有它失败 `UNSUPPORTED_ENV`. Node.js在给出时使用中继器.
-   **核心资产.** 在核心开始之前, 被钉住的帕鲁达姆版本和 每个核心文件的SHA-256都经过核对 `assets/paludarium/build-info.json` (单位:千美元)`ASSET_LOAD` 如果丢失或更改, `CORE_INIT` 如果核心无法启动). 节点.js 装入已检查的字节 一个私人目录。 浏览器在检查后从它的 URL 中加载核心, 所以 服务来自你信任的来源的资产.
-   **来宾与目录.** `validateGuest` 检查客人的字节并构建 资料, `createInstaller` 从固定目录中安装工具 检查的ELF或tar.gz下载, `registerValidatedGuest` 登记a 已检查的来宾( e)`runValidatedGuest` 运行它一次, `fixtureToFsEntries` 检查会话开始的文件,以及 `createCommandSession` 运行一个命令行( e)`ls`, (中文(简体) ), `cat`, (中文(简体) ), `cd`, (中文(简体) ), `rm -rf`, (中文(简体) ), `cp`, (中文(简体) ), `mv`, (中文(简体) ), `install <tool>`,或已安装的工具,在 `NAME=value` 环境任务)无外壳. A 类 在命令会话中以名称运行的已注册工具, 每个来宾都会找到 它作为 `/usr/bin/<tool>`。安装 `createInstaller` 写入不输出, 因此一个页面可以在工具齐备之前 用户任意类型 。 见 [安装 API](https://aletheia-works.github.io/formicarium/guides/install-api/) 财务报告和审定财务报表 [命令 API](https://aletheia-works.github.io/formicarium/guides/command-api/)。 。 。 .

## 限制

-   来宾必须是静态的x86-64 Linux ELF可执行文件. `validateGuest` 财务报告和审定财务报表 安装还拒绝超过128个米B的来宾.
-   来宾只作为被允许目的地的TCP客户进入网络, 通过浏览器中的继电器。 客人也可以服务于TCP和交换UDP ; 其他 UDP 仅访问名称.
-   核心的内存被封为1GB.
-   每次运行都从新文件系统开始;只有工作目录和 家目录结转.

## 如何运作

运行时间分为公共API,每个运行的工人,来宾输入/输出 和一个单元, `runtime/core.ts`,它知道模拟器的核心。 核心内容 本身就是 `@aletheia-works/paludarium-wasm` npm 包, 钉入精确 版本并运入 `assets/paludarium/`见 [运行时架构](https://aletheia-works.github.io/formicarium/development/architecture/) 编辑 [结构决定](https://aletheia-works.github.io/formicarium/development/decisions/)。 。 。 .

## 捐款

见 [捐款额](https://github.com/aletheia-works/formicarium/blob/main/CONTRIBUTING.md) 建立、测试和拉动请求,并跟踪 [行为守则](https://github.com/aletheia-works/formicarium/blob/main/CODE_OF_CONDUCT.md)。 。 。 . 如本报告所述,私下报告脆弱性 [安全政策](https://github.com/aletheia-works/formicarium/blob/main/SECURITY.md)。 。 。 .

## 许可证

阿帕奇许可证2.0. 捆绑的帕鲁迪尔核也是Apache-2.0;见 `THIRD_PARTY_NOTICES.md` 编辑 [核心许可证](https://aletheia-works.github.io/formicarium/development/licenses/)。 。 。 .

## 常见问题

### @aletheia-works/formicarium 是什么？

在浏览器中运行未修改的x86-64 Linux CLI程序,并在 paludarium Web Assembly 模拟器上运行 Node\.js

### 如何安装 @aletheia-works/formicarium？

在项目目录运行 npm install @aletheia-works/formicarium，或使用 pnpm add / yarn add / bun add。

### @aletheia-works/formicarium 支持 TypeScript 吗？

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

### @aletheia-works/formicarium 支持 ESM 还是 CommonJS？

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

### @aletheia-works/formicarium 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @aletheia-works/formicarium 可以商用吗？

@aletheia-works/formicarium 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aletheia-works/formicarium 的下载量有多少？

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

### @aletheia-works/formicarium 还在维护吗？

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