# enter-rivet-plugin 中文文档

规范地址：https://npmcn.com/package/enter-rivet-plugin/

版本：0\.1\.12
npm 元数据更新时间：2026-11-03T14:05:34.090Z
中文译文更新时间：2026-11-03T14:36:47.342Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/enter-rivet-plugin
原文对照：https://npmcn.com/package/enter-rivet-plugin/?lang=original

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

- 包体积（解压后）：3.3 MB，74 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2025-04-03T23:23:07.802Z
- 最新版本发布：2026-11-03T14:05:33.877Z
- 已发布版本数：39（近 12 个月 19 个）

## 中文简介

该项目包含自定义 [铆钉](https://github.com/Ironclad/rivet) 输入插件。

## 安装

```sh
npm install enter-rivet-plugin
```

也可以使用：`pnpm add enter-rivet-plugin`、`yarn add enter-rivet-plugin`、`bun add enter-rivet-plugin`

## README

# 铆钉输入插件

该项目包含自定义 [铆钉](https://github.com/Ironclad/rivet) 输入插件。

-   [使用插件](https://npmcn.com/package/enter-rivet-plugin/#readme-using-the-plugin)
    -   [在铆钉](https://npmcn.com/package/enter-rivet-plugin/#readme-in-rivet)
    -   [在代码中](https://npmcn.com/package/enter-rivet-plugin/#readme-in-code)
-   [黑珍珠OAuth认证](https://npmcn.com/package/enter-rivet-plugin/#readme-black-pearl-oauth-authentication)
-   [发布到npm](https://npmcn.com/package/enter-rivet-plugin/#readme-publishing-to-npm)
    -   [手动释放](https://npmcn.com/package/enter-rivet-plugin/#readme-manual-release)
    -   [未来的GitHub动作工作流](https://npmcn.com/package/enter-rivet-plugin/#readme-future-github-actions-workflow)
-   [更新已安装的插件](https://npmcn.com/package/enter-rivet-plugin/#readme-updating-installed-plugins)
-   [制作自己的插件](https://npmcn.com/package/enter-rivet-plugin/#readme-making-your-own-plugin)
    -   [⚠️重要注意事项⚠️](https://npmcn.com/package/enter-rivet-plugin/#readme-%EF%B8%8F-important-notes-%EF%B8%8F)
    -   [1\. 插件定义](https://npmcn.com/package/enter-rivet-plugin/#readme-1-plugin-definition)
    -   [2\. 节点的定义](https://npmcn.com/package/enter-rivet-plugin/#readme-2-node-definitions)
    -   [3\. 捆绑销售](https://npmcn.com/package/enter-rivet-plugin/#readme-3-bundling)
    -   [4\. NPM](https://npmcn.com/package/enter-rivet-plugin/#readme-4-npm)
-   [地方发展](https://npmcn.com/package/enter-rivet-plugin/#readme-local-development)

## 使用插件

### 在铆钉

在铆钉中使用这个插件：

1.  打开插件覆盖在屏幕的顶部。
2.  转到列表底部的“NPM Plugin”，然后单击“Add”按钮。
3.  输入“Enter -rivet-plugin”作为包名，并使用“latest”或特定的发布版本。
4.  点击“添加”按钮将插件安装到您当前的项目中。

### 在代码中

加载你的插件和铆钉到你的应用程序：

```ts
import * as Rivet from "@ironclad/rivet-core";
import enterPlugin from "enter-rivet-plugin";
```

注册插件与铆钉使用 `globalRivetNodeRegistry` 或者创建一个新的 `NodeRegistration` 注意到这一点：

```ts
Rivet.globalRivetNodeRegistry.registerPlugin(enterPlugin(Rivet));
```

## 黑珍珠OAuth认证

在Rivet，打开 **设置→进入**,设置 **黑珍珠API URL** 给受保护的人 API(例如 `https://dev.service.app.talismanai.co`), **OAuth登录URL** 转到官方登录页面(例如 `https://dev.admin.getenter.ai/login`）. JSON回调URL和 `redirect_uri` 不是必需的。

部署项目、数据获取器V1、获取输入、Talisman LLM和智能共享 这个登录流程。当API密钥缺失、为空或仅为空白时，Rivet打开 在发出受保护的请求之前，打开一个隔离的Chrome窗口。正常登录。 Rivet捕获JWT从一个 `Authorization: Bearer <jwt>` 由 登录应用程序到配置的确切原点 **黑珍珠API URL**在那之后 请求收到一个成功的HTTP响应。请求谷歌或不相关 起源和被拒绝的令牌将被忽略。如果登录应用程序还没有调用 配置API，在其中打开一个这样做的页面。

Rivet将捕获的令牌重用为 `Authorization: Bearer <jwt>` 用于插件调用。 JWT `exp` 当会话存在时，提供会话生存期。与当前的铆钉构建， 同一开放项目的节点和以后的运行重用该会话；并发 请求共享一个登录窗口。关闭项目/应用程序(或断开 节点调试器)清除身份验证缓存。配置API密钥后， OAuth仍然是HTTP 401/403和OAuth重定向的后备方案。获取输入使用 当不需要API调用时，无需登录即可使用图形提供的内容。

使用Rivet桌面构建和重建执行侧车与头部捕获支持。 旧版本在没有配置OAuth URL时保留API-key-only行为。

运行插件回归测试 `node --test test/*.test.mjs` 和一个兼容的 `@ironclad/rivet-core`． 在开发期间, `RIVET_CORE_MODULE` 可以指出来 核心模块;加载TypeScript源代码也需要 `tsx`。

## 发布到npm

npm包是 **`enter-rivet-plugin`**． Rivet从 `https://registry.npmjs.org/enter-rivet-plugin/<tag-or-version>`，然后下载 由该元数据识别的tarball并加载 `dist/bundle.js`。 `latest` 是一个npm发布标签，而不是一个Git分支。

此存储库中目前没有发布工作流。合并PR； 推送一个Git标签，或者创建一个GitHub版本，都不会将包发布到 自动npm。

### 手动释放

使用具有发布权限的npm帐户 `enter-rivet-plugin` 和 完成npm请求的任何身份验证或双因素验证。

1.  合并预期的更改并更新您的本地 `main` 付款:
    
    ```bash
    git switch main
    git pull --ff-only origin main
    yarn install --immutable
    ```
    
2.  检查已发布的版本，选择以前未使用的版本，然后构建。 下面的示例增加本地补丁版本：
    
    ```bash
    npm view enter-rivet-plugin@latest version
    npm version patch --no-git-tag-version
    yarn build
    npm pack --dry-run --ignore-scripts
    ```
    
    检查包内容，包括 `dist/bundle.js` 以及它的声明。 提交版本更改 `package.json` 和 `package-lock.json`,以及 与任何预期生成的分布变化，通过正常的审查 的过程。从结果发布提交发布。
    
3.  发布构建的包并更新 `latest` 标签:
    
    ```bash
    npm login
    npm whoami
    npm publish --ignore-scripts --access public --tag latest
    ```
    
    运行这个显式命令，而不是 `yarn publish` 或 `npm run publish`。 现有的 `publish` 脚本使用无效的 `--access private` 选项, 调用 `npm publish` 来自npm的发布生命周期。 `--ignore-scripts` 绕过 该脚本;首先必须单独完成构建。这unscoped 包是公开发布的。
    
4.  验证npm的 `latest` 标签指向你刚刚发布的版本：
    
    ```bash
    npm view enter-rivet-plugin dist-tags --json
    ```
    

现有的npm包/版本组合不能被覆盖。如果另一个 发布已使用的版本，请选择新版本后再发布 出版。看到 [NPM发布文档](https://docs.npmjs.com/cli/v11/commands/npm-publish/)。

### 未来的GitHub动作工作流

中创建发布自动化 **这个存储库**， `talismanai/rivet-plugin`,在 `.github/workflows/publish.yml`． 它不是Rivet桌面存储库的一部分。 工作流还没有实现。

一个合适的释放流程是：

1.  合并版本冲突和预期的插件更改。
2.  推送一个版本标签，例如 `v0.1.11` 在发布提交时。
3.  让工作流验证标签是否匹配 `package.json`、安装锁定 依赖、构建、检查包，并将其发布到NPM `latest`。

更喜欢 [NPM可信发布](https://docs.npmjs.com/trusted-publishers/) 与 GitHub Actions OIDC。在npm包的可信发布者设置中，配置 老板 `talismanai`、存储库 `rivet-plugin`、工作流文件名 `publish.yml`， 允许出版。如果使用GitHub环境，其名称也必须匹配。 出版工作需求 `contents: read` 和 `id-token: write`， a支持 github托管的运行器，以及npm可信发布支持的Node/npm版本。 这避免了在GitHub机密中存储长期存在的npm发布令牌。

纠正现有的 `publish` 脚本在自动化中采用之前，或者保留 显式构建并使用上面所示的显式发布命令。

## 更新已安装的插件

使用以下条目的项目跟踪在npm下发布的版本 `latest` 标签:

```yaml
- id: enter-rivet-plugin@latest
  package: enter-rivet-plugin
  tag: latest
  type: package
```

当Rivet加载插件时，它会将安装的版本与npm进行比较 版本，如果有新版本可用，则重新安装。重新启动铆钉和 重新打开项目以加载更新。要锁定一个版本，在两个版本中都使用它的版本 `id` 和 `tag`例如： `enter-rivet-plugin@0.1.11` 和 `0.1.11` 之后, 版本已发布。

在macOS上，默认安装目录为：

```text
~/Library/Application Support/com.ironcladapp.rivet/plugins/enter-rivet-plugin-latest/package
```

本地开发同步放置a `.git` 标记在该目录中。 当它存在时，Rivet会跳过npm重新安装，从而保留本地更改。 使用下面的本地同步命令更新该副本。回到 npm管理的安装，退出Rivet和移动整个 `enter-rivet-plugin-latest` 将目录缓存在安全的地方；重新打开项目 重新下载已发布的包。

发布插件不会更新Rivet应用程序。OAuth特性 需要一个兼容的铆钉桌面构建和重建执行侧车，加上 用户机器上安装的Chrome/Chromium。

## 制作自己的插件

### ⚠️重要注意事项⚠️

-   你必须捆绑你的插件，或者在ESM文件中包含插件的所有代码。插件加载使用 `import(pluginUrl)` 因此必须遵守ESM模块的所有规则。这意味着你不能使用 `require` 或 `module.exports` 在你的插件代码中。如果需要使用外部库，则必须将它们捆绑在一起。
    
-   您也不能导入任何bundle `@ironclad/rivet-core` 在你的插件。铆钉核心库作为参数传递到默认导出函数中。注意只使用 `import type` 语句，否则你的插件将无法成功捆绑。
    

这个存储库有两个绑定的示例 [ESBuild](https://esbuild.github.io/) 并且只能从 `@ironclad/rivet-core`。

### 1\. 插件定义

参见 [src / index.ts](https://npmcn.com/package/enter-rivet-plugin/src/index.ts) 来定义插件。您的插件必须默认导出一个函数，该函数接受Rivet Core库作为其唯一的参数，并返回一个有效的 `RivetPlugin` 对象。

### 2\. 节点的定义

参见 [src /节点/ ExamplePluginNode.ts](https://npmcn.com/package/enter-rivet-plugin/src/nodes/ExamplePluginNode.ts) 来定义插件的节点。您应该遵循类似的语法来导出Rivet Core库中的函数。

-   节点必须实现 `PluginNodeDefinition<T>` 通过调用 `pluginNodeDefinition(yourPluginImpl, "Node Name")`。
-   节点实现必须实现 `PluginNodeImpl<T>`。
-   `T` 应该是你插件的类型定义。

### 3\. 捆绑销售

看到 [bundle.ts](https://npmcn.com/package/enter-rivet-plugin/bundle.ts) 这是一个如何捆绑插件的例子。你可以使用任何你喜欢的捆绑器，但是你必须把你的插件捆绑到一个文件中。你可以使用 [ESBuild](https://esbuild.github.io/) 将你的插件捆绑到一个文件中。

将所有外部库捆绑在一起是很重要的，因为浏览器不能加载纯导入。

### 4\. NPM

将插件发布到npm，以便Rivet用户可以通过UI或SDK安装它。看到 [发布到npm](https://npmcn.com/package/enter-rivet-plugin/#readme-publishing-to-npm) 此存储库的发布过程。

## 地方发展

1.  运行 `yarn dev` 以监视模式启动编译器和打包器。这将自动重新组合和重新绑定您的更改到 `dist` 文件夹中。这也会将捆绑的文件复制到插件安装目录中。
2.  每次更改后，必须重新启动Rivet才能看到更改。

对于一次性构建和同步签出源代码：

```bash
yarn build
yarn exec tsx bundle.ts --sync
```

同步副本 `dist` 和 `package.json` 铆钉的本地插件 安装并将其标记为本地开发副本。之后重新启动Rivet。 这些命令不会创建npm发布。

### 将OAuth JWT复制到项目上下文中

在 **设置→进入**,设置 **OAuth令牌上下文密钥** 旁边 **OAuth登录URL** 给一个名字，比如 `apiJwt`． 留空以禁用复制。在一次成功的 Rivet写道：login，以及无论何时重用经过身份验证的会话 `Bearer <jwt>` 将该键作为项目上下文中的秘密字符串。 该键的现有值被替换；保留其他上下文条目。

使用一个 **上下文** 使用该ID和String数据类型读取它。在 第一次运行时，安排执行，以便Context节点在经过身份验证的节点之后运行。 已运行的上下文节点不会自动再次执行。令牌刷新 替换复制的值。上下文值是一个副本，而不是身份验证缓存； 它不会在缓存过期或应用程序关闭后保持登录有效。

这个可选值遵循Rivet现有的项目上下文存储和持久性； 秘密标志在UI中屏蔽它，不加密它。此功能需要 更新后的Enter插件和Rivet版本都支持OAuth上下文镜像。

### 运行节点前登录

打开一个项目，转到 **设置→进入**． 集 **黑珍珠API URL** 和 **OAuth登录URL**，然后点击 **登录** 在登录URL旁边。这个总是打开的 一个新的登录，即使缓存了JWT，也不执行API请求 部署项目。结果将替换项目的会话和更新 **OAuth令牌上下文密钥** 与 `Bearer <jwt>` 当配置该字段时。 后续节点在桌面和Node执行器中重用会话，包括 当Node执行器在登录后连接时。取消保留现有的 工作会议。关闭设置或切换项目将取消未完成的登录。

### 自动令牌捕获

集 **OAuth登录URL** 进入官方平台登录页面。铆钉自动 从该页发起的成功HTTP请求中捕获有效的Bearer JWT。 登录页面使用的API主机名和路径可以在不更新的情况下更改 铆钉的设置，可能不同于 **黑珍珠API URL**． 请求启动 由谷歌或不相关的浏览器框架排除。手动登录和 节点触发的身份验证使用相同的逻辑。JWT在Black中被重用 Pearl API请求并复制为 `Bearer <jwt>` 到已配置的上下文键。 不需要配置令牌捕获URL；过时的值将被忽略。

## 常见问题

### enter-rivet-plugin 是什么？

该项目包含自定义 铆钉 输入插件。

### 如何安装 enter-rivet-plugin？

在项目目录运行 npm install enter-rivet-plugin，或使用 pnpm add / yarn add / bun add。

### enter-rivet-plugin 支持 TypeScript 吗？

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

### enter-rivet-plugin 支持 ESM 还是 CommonJS？

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

### enter-rivet-plugin 可以商用吗？

enter-rivet-plugin 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### enter-rivet-plugin 还在维护吗？

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