# @botiverse/porthole 中文文档

规范地址：https://npmcn.com/package/%40botiverse/porthole/

版本：0\.14\.15
npm 元数据更新时间：2026-11-08T07:11:23.734Z
中文译文更新时间：2026-11-08T12:14:19.587Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：6.9 MB，416 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：0 个
- peer 依赖：react \>=19
- 首次发布：2026-10-11T09:21:06.438Z
- 最新版本发布：2026-11-08T07:11:23.400Z
- 近 30 天下载量：22648（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：49（近 12 个月 49 个）

## 中文简介

用于代理制作的 HTML 的主机侧沙盒: 隔离, Egress 硬化, 主题外壳, 闸口主机功能, 以及代理手册, 从一个配置.

## 安装

```sh
npm install @botiverse/porthole
```

也可以使用：`pnpm add @botiverse/porthole`、`yarn add @botiverse/porthole`、`bun add @botiverse/porthole`

## README

# 门洞

`@botiverse/porthole`: 显示 HTML 代理写( 部件、 整页、 MCP Apps 视图) 在你的应用程序里,安全。 一个配置给框架 其隔离,它的CSP, 一个主题外壳 它可能调用的主机函数( 每一个在门后) , 您的代理读取的手册 .

```bash
npm install @botiverse/porthole
```

节点24或后起,或云花工. 浏览器部分是纯 ES 模块,没有 依赖关系(捆绑或服务) `dist/` 带有导入地图:docs/ADOPting.md 第4节.

## 显示内容的两种方式

-   **不透明,在页面中.** 不需要服务器: 内容运行在一个不透明的沙箱框架 源代码。 对于对话中的部件.
-   **服务,以自己的出身.** 每个页面,或每个对话的部件,都有来源 喜欢 `a-<id>.example-usercontent.com`,这样它就可以保持存储,打开 在干净的地址在一个 新建标签, 仅由您的应用程序设置 。 东道主工具包(`createContentHost`)是服务器侧; 您的应用程序只写它的政策: 哪些页面存在, 哪些人可能看到它们 .

## 两分钟内试试看

软件包装了一个完整的应用程序, 同样的代码在节点和工人:

```bash
PORTHOLE_SECRET=$(npx porthole secret) node node_modules/@botiverse/porthole/examples/node/server.mjs
# open http://localhost:8790: a stored page, served on http://a-hello.content.localhost:8790
```

-   `examples/app.mjs`: app(政策,路线,页面),运行时间不可知.
-   `examples/node/server.mjs` (单位:千美元)`nodeServer`, (中文(简体) ), `examples/workers/` (单位:千美元)`contentHostFor`,带有D1 移徙和移徙 `wrangler.jsonc`) (中文(简体) ).
-   `examples/conformance/`:Porthole的相容套房逆向运行,在三台发动机上.
-   `examples/mcp/server.mjs`:代理工具(显示,引导,检查)作为MCP服务器.

## 最小的不透明显示

```js
import { createHost, presets } from "@botiverse/porthole";

const host = createHost(presets.inlineWidget());
const display = host.mount(document.getElementById("widget"), {
  displayId: "w1",
  title: "A chart",
  scheme: "light",
});
display.setContent("<p>Hello from an agent</p>");
```

在反应中 : `<PortholeProvider>` 周围 `<PortholeFrame config displayId title scheme content />` 从 `@botiverse/porthole/react`。 。 。 .

## 由许多文件制成的页面

已送达的页面可能带有自己的文件: 构建的输出、 带有图像的报告、 a 读取其数据的仪表板(0.6). 商店按路径回答一个表和字节 页面的相对地址是自己的版本:

```js
source: async (id, version) => ({
  files: { "index.html": { size: 397, sha256: "…" }, "assets/app.js": { size: 142870, sha256: "…" } },
  read: (path) => myStore.bytes(id, version, path),        // Uint8Array or a stream, whole
}),
entry: {
  // "/v/3/<file>" is version 3, any other path the latest's: answer with the version's own address.
  at: async (scope, path) => {
    const at = versionedAddress(path), version = at?.version ?? (await latestOf(scope));
    return at && { instance: pageOf(scope, version), base: versionBase(version), file: at.file, pinned: true };
  },
},
```

每个文件只从清单中提供 由Porthole自己的表格输入, `nosniff`,带有CSP 打开了这个版本的路径,没有其他来源; `checkFileSet` 检查一个版本 出版时的路径和限制, `lintFiles` 财务报告和审定财务报表 `checkPage({ files })` 是经纪人的 边 docs/ADOPTING.md §由许多文件所制成的页面.

## 作为应用程序的一页:能力运行时间

与 `runtime: "1"` 在其配置(0.7)中,一个页面通过一个全球地址到达其主机,因为 及其查看器级别允许的:

```js
const db = await porthole.use("db");                 // a frozen namespace, or null: draw without it
const votes = db && (await db.query("votes")).docs;  // a refusal rejects with error.code and a sentence
```

主机保留服务:它的处理者(`db`, (中文(简体) ), `artifact`, (中文(简体) ), `assets`, (中文(简体) ), `comments`· ; `user` 这是 观者, `declareCapabilities` 在出版时,观众的级别 在其访问 (单位:千美元)`Grant.level`),以及资产存储 `/server` 服务于 `/_blob/<id>`。 。 。 . `defineRuntimeConformance` 检查处理者。 类型: `types/runtime/v1/*.d.ts`.docs/Apping.md § 能力 运行时间.

## 经纪人得到什么

```js
import { admitContent, checkTool, guideTool, showTool } from "@botiverse/porthole";

const tools = [showTool(config), guideTool(config), checkTool(config)]; // name, description, JSON Schema
const admitted = admitContent(config, html); // refuses only what certainly fails, saying what to change
```

`checkPage` (单位:千美元)`@botiverse/porthole/check`在电话和桌面上运行真实的沙盒中的一页 宽度,光和黑暗, 在别人看到它之前, 并告诉特工什么打破 在几行. `examples/mcp/server.mjs` 电线将工具作为 MCP 服务器.

## 下一个读取

-   [文件/记录](https://npmcn.com/package/%40botiverse/porthole/docs/ADOPTING.md): 开始, 一步步: 服务器, 页面, 其 CSP,工人,地方发展,代理的工具,符合性,故障排除.
-   [选择外出](https://npmcn.com/package/%40botiverse/porthole/docs/ADOPTING.md#choosing-egress): 哪些内容可以装入(已关闭,库) CDN,来自任何https站点的被动介质,每个关卡打开什么,重新打开的风险.
-   [文档/THREAT MODEL.md](https://npmcn.com/package/%40botiverse/porthole/docs/THREAT_MODEL.md): 港洞保护的是什么,谁保护谁;每个港洞 使用,它保证什么, 剩下的给你,和没有覆盖.
-   [文件/DESIGN.md](https://npmcn.com/package/%40botiverse/porthole/docs/DESIGN.md):如何运作. [文件/决定.md](https://npmcn.com/package/%40botiverse/porthole/docs/DECISIONS.md)为什么, 由P-数字(代码引用它们).

## 子路径

| 导入 | 什麽 |
| --- | --- |
| `@botiverse/porthole` | `createHost`, (中文(简体) ), `presets`, (中文(简体) ), `defineDisplays`, (中文(简体) ), `portholeClient`, (中文(简体) ), `lintContent`,工具(浏览器和服务器) |
| `@botiverse/porthole/react` | `PortholeProvider`, (中文(简体) ), `PortholeFrame`, (中文(简体) ), `PortholeView` |
| `@botiverse/porthole/server` | `createContentHost` (单位:千美元)`routes`, (中文(简体) ), `contentHostFor`, (中文(简体) ), `prefixedName`, (中文(简体) ), `d1TicketStore` (任何运行时间) |
| `@botiverse/porthole/node` | `nodeServer`, (中文(简体) ), `nodeHost`, (中文(简体) ), `nodeListener`, (中文(简体) ), `nodeProbe` (节点的 http 服务器) |
| `@botiverse/porthole/mcp` | mCP Apps 适应器 |
| `@botiverse/porthole/check` | `checkPage`, (中文(简体) ), `playwrightDriver`, (中文(简体) ), `cdpDriver`: 代理机的放映前检查 |
| `@botiverse/porthole/conformance` | `defineHostConformance`: 套房, 相对于您的应用程序( Playwright) |

`npx porthole secret` 做一个秘密; `npx porthole d1-schema` 打印 D1 迁移.

阿帕奇2.0 (英语). `/server` 还提供下列文件的副本: [图.js](https://www.chartjs.org/) 4.5.1(MIT)和 [D3级](https://d3js.org/) 7.9.0 (ISC) 为活部件(P079),每个部件配有许可证 (单位:千美元)`/__porthole/lib/<name>@<version>/`从 `src/libraries/files.generated.ts`他们的警告, 和那些包 他们的文件捆绑 [第三次议会 NoTICES.md](https://npmcn.com/package/%40botiverse/porthole/THIRD_PARTY_NOTICES.md)。 。 。 .

发现弱点了吗? 私下报告,作为 [警卫](https://github.com/botiverse/porthole/blob/main/SECURITY.md) 说 从不公开 问题.

## 常见问题

### @botiverse/porthole 是什么？

用于代理制作的 HTML 的主机侧沙盒: 隔离, Egress 硬化, 主题外壳, 闸口主机功能, 以及代理手册, 从一个配置\.

### 如何安装 @botiverse/porthole？

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

### @botiverse/porthole 支持 TypeScript 吗？

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

### @botiverse/porthole 支持 ESM 还是 CommonJS？

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

### @botiverse/porthole 需要什么版本的 Node\.js？

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

### @botiverse/porthole 可以商用吗？

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

### @botiverse/porthole 的下载量有多少？

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

### @botiverse/porthole 还在维护吗？

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