# @enricai/barnacle 中文文档

规范地址：https://npmcn.com/package/%40enricai/barnacle/

版本：1\.21\.6
npm 元数据更新时间：2026-11-12T18:52:16.912Z
中文译文更新时间：2026-11-13T17:56:34.620Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：6 MB，680 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.19\.0
- 运行依赖：33 个
- peer 依赖：vitest ^4\.1\.10，dd-trace ^6，hot-shots ^18
- 首次发布：2026-07-14T18:43:51.050Z
- 最新版本发布：2026-11-12T18:52:16.518Z
- 近 30 天下载量：5170（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：146（近 12 个月 146 个）

## 中文简介

巴纳克将任何网站变成API. POST 结构化有效载荷到打入的端点,而Barnacle通过目标站点驱动浏览器会话,返回结构化结果.

## 安装

```sh
npm install @enricai/barnacle
```

也可以使用：`pnpm add @enricai/barnacle`、`yarn add @enricai/barnacle`、`bun add @enricai/barnacle`

## README

# 巴纳克

巴纳克将任何网站变成API. 指向一个网站,描述用户 它生成一个插件,由 HTTP 直接呼叫自动支持 浏览器倒回-没有需要手动维护的刮取代码.

## 如何运作

点Barnacle在一个站点,用简单的英语描述用户流量,并运行 3 侦察命令 Barnacle 通过流量驱动一个真正的浏览器, 抓取每个 API呼叫,用平版HTTP重放,以证明哪些没有浏览器就能工作, 探测速率限制上限,并生成一个完整的插件 — Zod schemas 从捕获的JSON、负载头、限速上限、热道推断 HTTP 客户端,和 Stagehand 浏览器倒置. 在一行中注册插件; Barnacle 处理会话、重试、回落路由、持续审计 响应信封包装.

| 阶段 | 运行中 | 你得到的东西 |
| --- | --- | --- |
| **1 — 浏览器侦察** | `pnpm run recon:browser` | 每个API呼叫网站,捕获到 `<run-dir>/graphql/*.json` |
| **2–3 — HTTP 重放+ 探测** | `pnpm run recon:http` | 证明每个端点没有浏览器工作; 限速上限; 静态固定装置 |
| **4 — 插件生成** | `pnpm run recon:generate` | 一个完整的插件: Zod schemas, headers, Bottleneck 配置, 热路径客户端, Stagehand 倒置 |
| **5+ — 运行时间** | `pnpm start` | 直接 HTTP 热路, 自动浏览器回落, 夜间吸烟测试, 漂移检测 |

见 [文件/建筑图](https://npmcn.com/package/%40enricai/barnacle/docs/architecture.md) 设计理由 [文件/游戏手册.md](https://npmcn.com/package/%40enricai/barnacle/docs/playbook.md) 完全的分步指南 添加新网站.

## 使用量

### 先决条件

-   节点.js 22.19+
-   pnpm 10.4.1 (中文(简体) )
-   浏览器账户( A)`BROWSERBASE_API_KEY` + 键 `BROWSERBASE_PROJECT_ID`),用于被管理的浏览器会话——默认提供者. 一个钢铁帐户(`STEEL_API_KEY`)是一种通过 `SCRAPER_PROVIDER=steel`
-   自动键( A)`ANTHROPIC_API_KEY`为了Stagehand的LLM电话, **或者说** AWS Bedrock (英语:`USE_BEDROCK=true` + AWS证书)——见 [文件/配置](https://npmcn.com/package/%40enricai/barnacle/docs/configuration.md) 详情

### 安装

```bash
pnpm install
cp .env.example .env   # fill in BROWSERBASE_API_KEY + BROWSERBASE_PROJECT_ID (or STEEL_API_KEY for SCRAPER_PROVIDER=steel) and either ANTHROPIC_API_KEY or Bedrock creds
```

生成和散开一个 API 密钥,加上完整的 Env-var 引用, 生活在 [文件/配置](https://npmcn.com/package/%40enricai/barnacle/docs/configuration.md)。 。 。 .

### 德维

```bash
pnpm run dev
```

### 生产建筑

```bash
pnpm run build
pnpm start
```

### 试试看

随着dev服务器的运行,确认它是:

```bash
curl -s http://localhost:3000/health | jq .
```

已注册内置插件的 Barnacle 靴子( 见 `BUILTIN_SITE_PLUGINS` 内 `src/plugins/discover.ts`) (中文(简体) ). 每个注册的插件曝光 `POST /v1/<siteId>/run`; 每个响应使用相同的信封形状 (单位:千美元)`{ status, ...pluginData }`)所以客户共享一个解析器. 见 [文档/插件作者.md#端点](https://npmcn.com/package/%40enricai/barnacle/docs/plugin-authoring.md#endpoints) 用于整个终点.

## 图标

| 命令 | 它会做什么 |
| --- | --- |
| `pnpm run dev` | `tsx watch --env-file=.env src/server.ts` 热重装 |
| `pnpm run build` | 编译为 `dist/` (tsc +路径别名重写+复制固定) |
| `pnpm start` | `node dist/server.js` |
| `pnpm run typecheck` | 严格 TS 不发送 |
| `pnpm run lint` 编号 : `lint:fix` | 生物体 |
| `pnpm run test` | 检测单位+整合 |
| `pnpm test src/scraper/fixtures.test.ts` | 运行单个测试文件( NEVER 使用) `--` 在过滤器之前) |
| `pnpm run test:watch` | 监视模式下的维特 |
| `pnpm run test:coverage` | V8覆盖报告 |
| `pnpm run format` | Biome 格式写入 |
| `pnpm run recon:browser` | 第一阶段——驱动浏览器+捕获API呼叫 |
| `pnpm run recon:http` | 阶段2–3——回放,回放,探测率限制 |
| `pnpm run recon:generate -- --site-id <id>` | 第4阶段——从文物中生成完整的插件 |
| `pnpm run recon:summarize -- --site-id <id>` | 第4阶段(可选)——撰写人能读取的研究结果 |
| `pnpm run recon:heal -- --site-id <id> --url <url>` | 在不修改源文件的情况下自愈失败的重试流程 |
| `pnpm run smoke -- --site <id> --payload '...'` | 第6阶段——进行夜间漂浮探测烟雾试验 |
| `pnpm run judge:llm -- --calls-ndjson <path> --call-type <type>` | 有分数的 LLM 调用三维分数 |
| `pnpm run heal:llm -- --verdict-path <path> --call-type <type>` | 自愈失败的即时模板 |

## 写入插件

站点插件是一个满足的单一类型脚本模块 `SitePlugin<TInput, TOutput>` 从 `src/site-plugin.ts` a 包括: `meta` 块,可选 `executeHttp` 热道,还有 阶段手 `execute` 倒计时. `pnpm run recon:generate` 为您撰写此结构 . 插件也可以是完全没有TypeScript的配置唯一的JSON显示. 满 参考文献 [文件/插件作者.md](https://npmcn.com/package/%40enricai/barnacle/docs/plugin-authoring.md)。 。 。 .

## 参考文献

-   编码标准 : [克劳德·姆德](https://npmcn.com/package/%40enricai/barnacle/CLAUDE.md)
-   建筑和设计原理 : [文件/建筑图](https://npmcn.com/package/%40enricai/barnacle/docs/architecture.md)
-   侦察游戏本(分步骤): [文件/游戏手册.md](https://npmcn.com/package/%40enricai/barnacle/docs/playbook.md)
-   配置( 所有嵌入式 vars, 部署, 共同问题) : [文件/配置](https://npmcn.com/package/%40enricai/barnacle/docs/configuration.md)
-   插件作者指南 : [文件/插件作者.md](https://npmcn.com/package/%40enricai/barnacle/docs/plugin-authoring.md) (可操作的例子: [实例/插件/hello-site/](https://npmcn.com/package/%40enricai/barnacle/examples/plugins/hello-site/README.md)(中文(简体) )
-   测试指南 : [文件/测试](https://npmcn.com/package/%40enricai/barnacle/docs/testing.md)
-   安全政策和脆弱性报告: [警卫](https://npmcn.com/package/%40enricai/barnacle/SECURITY.md)
-   遥测 & LLM 判断概念指南 : [文件/遥测和判断](https://npmcn.com/package/%40enricai/barnacle/docs/telemetry-and-judging.md)
-   提交调节运行本 : [文件/提交-和解](https://npmcn.com/package/%40enricai/barnacle/docs/submission-reconciliation.md)
-   现场侦察结果: [文档/目标校对](https://npmcn.com/package/%40enricai/barnacle/docs/target-recon.md) (第一次会议之后人口众多) `pnpm run recon:summarize`(中文(简体) )

## 许可证

[麻省理工学院](https://npmcn.com/package/%40enricai/barnacle/LICENSE) 加纳

欢迎捐款——见 [捐款额](https://npmcn.com/package/%40enricai/barnacle/CONTRIBUTING.md)。 。 。 .

## 常见问题

### @enricai/barnacle 是什么？

巴纳克将任何网站变成API\. POST 结构化有效载荷到打入的端点,而Barnacle通过目标站点驱动浏览器会话,返回结构化结果\.

### 如何安装 @enricai/barnacle？

在项目目录运行 npm install @enricai/barnacle，或使用 pnpm add / yarn add / bun add。

### @enricai/barnacle 支持 TypeScript 吗？

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

### @enricai/barnacle 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @enricai/barnacle 需要什么版本的 Node\.js？

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

### @enricai/barnacle 可以商用吗？

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

### @enricai/barnacle 的下载量有多少？

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

### @enricai/barnacle 还在维护吗？

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