# @forestadmin/agent 中文文档

规范地址：https://npmcn.com/package/%40forestadmin/agent/

版本：1\.113\.3
npm 元数据更新时间：2026-11-13T15:45:55.413Z
中文译文更新时间：2026-11-15T07:13:03.915Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：1 MB，201 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：25 个
- peer 依赖：@fastify/express ^1\.1\.0 \|\| ^2\.0\.0 \|\| ^3\.0\.0 \|\| ^4\.0\.0，@forestadmin/agent-bff 1\.45\.0，@forestadmin/workflow-executor 1\.37\.0
- 首次发布：2022-04-15T08:12:44.397Z
- 最新版本发布：2026-11-13T15:45:55.018Z
- 近 30 天下载量：80520（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：546（近 12 个月 209 个）

## 中文简介

森林管理节点的主要出入口. js SDK: `createAgent(options)` 返回您在 HTTP 服务器上挂载的数据源、定制、图表和插件.

## 安装

```sh
npm install @forestadmin/agent
```

也可以使用：`pnpm add @forestadmin/agent`、`yarn add @forestadmin/agent`、`bun add @forestadmin/agent`

## README

# @ forestadmin/ 代理服务器

森林管理节点的主要出入口. js SDK: `createAgent(options)` 返回代理人到 然后挂载在 HTTP 服务器上.

见 [开发者指南](https://docs.forestadmin.com/developer-guide-agents-nodejs) 全文 文档.

## 可选的进程中组件

通常单独部署的两个部件可以运行在特工内部。 两者都是可选的 包,以动态方式加载:不使用它们的代理从不加载它们的代码.

### 一个BFF - `agent.addBff()`

```bash
npm install @forestadmin/agent-bff
```

```ts
await createAgent(options)
  .addDataSource(/* … */)
  .addBff({ allowedOrigins: ['https://my-app.com'] })
  .mountOnStandaloneServer(3351)
  .start();
```

服务于 REST BFF 下 `/bff` 无论该代理机搭载在哪个端口上 在每个上载目标上 `mountOnStandaloneServer` 上方,或主机本身的听众 `mountOnExpress`, (中文(简体) ), `mountOnKoa`, (中文(简体) ), `mountOnFastify`, (中文(简体) ), `mountOnNestJs`A级 `mountOn*` 调用是打开套接字的内容 : `start()` 只构建 代理的路由器,所以一个连锁 没有一个服务什么, BFF 包括.

BFF在同一过程中到达代理,所以没有第二个端口,也没有代理 URL 到 配置, 没有要保持同步的秘密 `authSecret`, (中文(简体) ), `envSecret`、森林urls 和 日志被继承 .

所有东西 `addBff()` takes 是它交换到的特性 : `tokenEncryptionKey` 启用 OAuth(和 随它而来, `allowedOrigins` 允许浏览器访问, `openapiEnabled` 为文件服务 (嵌入时默认关闭). `GET /bff/health` 报告 `configured`。 。 。 .

**在任何身体剖析器之前挂载代理** ——首先运行的剖析器会消耗 请求流,以及每个 BFF `POST` 然后回答 `500 stream.not.readable`。 。 。 .

宽容 `cors()` 在挂载前登记,您需要飞行前的费用,但不需要许可列表: 主机答案 `OPTIONS` 和它自己的政策, 没有下游可以收回,所以 之后的请求无论如何都会到达此地 `403 origin_not_allowed` 除非其为 `Origin` 这是您列出的。 浏览器看到错误的飞行前预览; 收藏仍然从未读取 为了那个来源.

在自己作品的子路径下上山: `app.use('/api', mounted)` 服务于 `/api/bff`,且前缀是每个请求产生的,所以 OpenAPI `servers` 条目和文档页面 携带 `/api/bff` 我也一样.

**`agentTimeoutMs` 束缚了等待,而不是工作.** 当打给特工的电话超过BFF时 有错误的答案,但无任何被取消:进程内请求运行到完成。 一个 时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时断时. 在您最慢动作上方显示超时大小, 如果您打算重试的话, 则使动作具有像素性 .

**`addBff()` 无法与 `mountAiMcpServer({ basePath: '/bff' })`** —— MCP 服务器 将索赔 `/bff/oauth` 财务报告和审定财务报表 `/bff/mcp`无论你说的第二投在现场 建设者呼叫而不是从 `start()`。 。 。 .

见 [`@forestadmin/agent-bff`](https://npmcn.com/package/%40forestadmin/agent-bff/README.md) 路径、认证模式和 与独立部署的差异.

### 一个工作流程执行器 - `agent.addWorkflowExecutor()`

```bash
npm install @forestadmin/workflow-executor
```

在代理服务器旁运行工作流程执行器, 代理 `/_internal/executor/*` 对它。 见 [`@forestadmin/workflow-executor`](https://npmcn.com/package/%40forestadmin/workflow-executor/README.md)。 。 。 .

## 常见问题

### @forestadmin/agent 是什么？

森林管理节点的主要出入口\. js SDK: createAgent\(options\) 返回您在 HTTP 服务器上挂载的数据源、定制、图表和插件\.

### 如何安装 @forestadmin/agent？

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

### @forestadmin/agent 支持 TypeScript 吗？

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

### @forestadmin/agent 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @forestadmin/agent 可以商用吗？

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

### @forestadmin/agent 的下载量有多少？

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

### @forestadmin/agent 还在维护吗？

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