# @forwardpath/js 中文文档

规范地址：https://npmcn.com/package/%40forwardpath/js/

版本：0\.2\.0
npm 元数据更新时间：2026-10-22T20:39:24.937Z
中文译文更新时间：2026-11-15T09:54:51.797Z
软件包许可：UNLICENSED

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

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

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

- 包体积（解压后）：28 kB，22 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：ai ^7
- 首次发布：2026-10-22T13:10:11.700Z
- 最新版本发布：2026-10-22T20:39:24.620Z
- 近 30 天下载量：3980（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

FrontPath 摄取 API 的无框架客户端.

## 安装

```sh
npm install @forwardpath/js
```

也可以使用：`pnpm add @forwardpath/js`、`yarn add @forwardpath/js`、`bun add @forwardpath/js`

## README

# @forwardpath/js (英语)

FrontPath 摄取 API 的无框架客户端. 它流出摄入量 代理通过 [AI SDK 软件](https://ai-sdk.dev/),上传文件和收集 页面上下文. `@forwardpath/react` 财务报告和审定财务报表 `@forwardpath/node` 以它为基础.

## 安装

```sh
npm install @forwardpath/js ai
```

`ai` (v7)是同龄人依赖关系.

## 密钥

可公布的密钥( E)`fppk_…`)按设计公开. 在浏览器代码中是安全的 并且只有从源头 允许在钥匙上工作。 每个项目创建一个 在前卫门户.

您的密钥 API (`fp_…`)可以为任何用户提供薄荷会话. 留着吧 服务器。 这个包裹从不发送.

## 使用量

```ts
import { useChat } from "@ai-sdk/react";
import {
  collectClientContext,
  createBrowserSession,
  createIntakeChatTransport,
  getAnonymousId,
  shouldSendAfterContact,
  uploadAttachment,
  type UploadedAttachment,
} from "@forwardpath/js";

const baseUrl = "https://app.forwardpath.ai";
const attachments: UploadedAttachment[] = [];
let session: { token: string; expiresAt: string } | null = null;

// Mints a session in the browser; mints again a minute before it expires.
async function getSessionToken() {
  if (!session || Date.parse(session.expiresAt) - Date.now() < 60_000) {
    session = await createBrowserSession({
      baseUrl,
      publishableKey: "fppk_…",
      // For a signed-in user, send user: { id, email, name } instead.
      anonymousId: getAnonymousId(),
      clientContext: collectClientContext({ appName: "Acme" }),
    });
  }
  return session.token;
}

const transport = createIntakeChatTransport({
  baseUrl,
  getSessionToken,
  getClientContext: () =>
    collectClientContext({ appName: "Acme", appVersion: "2.4.0" }),
  getUploadedAttachments: () => attachments,
});

// In a React component:
const { messages, sendMessage, addToolOutput } = useChat({
  transport,
  sendAutomaticallyWhen: shouldSendAfterContact,
});

// Attach a file before the next message:
attachments.push(
  await uploadAttachment({
    baseUrl,
    sessionToken: await getSessionToken(),
    file,
  }),
);
```

`getSessionToken` 在每次聊天请求之前运行,以便返回缓存 当旧的纸币过期时, 代币和薄荷新纸币.

## `createBrowserSession(options)`

电话 `POST /api/v1/intake/browser-sessions` 并决心 `{ token, expiresAt, projectSlug, contactCollection, reporter }`。 。 。 .

| 选项 | 说明 |
| --- | --- |
| `baseUrl` | FPOS来源. |
| `publishableKey` |  `fppk_…` 键. |
| `user` | `{ id, email?, name? }` 用于注册用户。 发送此或 `anonymousId`。 。 。 . |
| `userHash` | `createUserHash()` 从 `@forwardpath/node`,计算在您的服务器上。 需求 `user`。 。 。 . |
| `anonymousId` | 一个没有用户的访客的稳定身份证明,例如:. `getAnonymousId()`。 。 。 . |
| `clientContext` | 页面上下文,例如来自 `collectClientContext()`。 。 。 . |
| `fetch` | 自定义 `fetch`。 。 。 . |

`reporter.identity` 实值 `verified` 带有有效的 `userHash`, (中文(简体) ), `claimed` 与 `user` 单独(浏览器给用户取名,所以视其为未经核实)和 `anonymous` 与 `anonymousId`坏键或 `userHash` 拒绝与401, 一个来源,密钥不允许用 403 .

`getAnonymousId()` 返回保留在其中的随机编号 `localStorage` 下级 `forwardpath:anonymous-id`。当存储被屏蔽时,会持续页面 装入。 在服务器上,每个呼叫者都得到同样的ID,所以在浏览器中调用它.

## 电子邮件表

当代理商没有给记者的邮件,而密钥会收集电子邮件时,它就会 调用客户端工具 `requestContact`。聊天显示它是一个 `tool-requestContact` 页:1 `input-available` 状态。 显示窗体,然后 以 `addToolOutput`数字 :

```ts
addToolOutput({
  tool: "requestContact",
  toolCallId: part.toolCallId,
  output: { email: "ada@example.com", name: "Ada" }, // or { skipped: true }
});
```

-   检查电子邮件 `isContactEmail(email)` 先说 API拒绝 如果电子邮件无效, 则整个聊天请求 .
-   仅在助理消息出现时提供跳过 `metadata.contactCollection` 实值 `optional`这是 `required` 或者说 `off` 否则.
-   过 `shouldSendAfterContact` 作为 `sendAutomaticallyWhen` 所以,代理人 回答后继续 别用AI SDK的 `lastAssistantMessageIsCompleteWithToolCalls` 独活:它永远重传 一旦特工把报告归档.
-   表格打开时不要发送新信息. API不能拿一个 与未回复的工具呼叫聊天 .

`@forwardpath/react` 做这一切为你.

## 来自服务器的会话

用您的 API 密钥在服务器上薄荷会话, 使用 `@forwardpath/node` 并且已经 `getSessionToken` 从自己取出信物 路线,例如:. `POST /api/forwardpath/session`。 。 。 .

## 错误

`createBrowserSession` 财务报告和审定财务报表 `uploadAttachment` 抛出和聊天传输 拒绝, `ForwardPathApiError` 在非-2xx响应。 它已经 `status`, (中文(简体) ), `code` (例如:. `unauthorized`, (中文(简体) ), `validation_error`, (中文(简体) ), `rate_limited`, (中文(简体) ), `title` 财务报告和审定财务报表 选项 `detail`。 。 。 .

```ts
import { ForwardPathApiError } from "@forwardpath/js";

try {
  await uploadAttachment({ baseUrl, sessionToken, file });
} catch (error) {
  if (error instanceof ForwardPathApiError && error.status === 401) {
    // Session expired: mint a new one and retry.
  }
}
```

## 页面上下文

`collectClientContext(extra?)` 读取页面 URL, 主机,路径,标题, 参考器、用户代理、语言、时区和视图大小,然后合并到 `appName`, (中文(简体) ), `appVersion`, (中文(简体) ), `environment` 财务报告和审定财务报表 `custom`在浏览器外 仅返回 `extra`,因此在服务器渲染时可以安全拨打. 过去的数值 aPI的限制(例如:. `custom` 上限为30个密钥和4000个字符) 被剪辑或丢弃,所以它们不能失败聊天请求.

## 常见问题

### @forwardpath/js 是什么？

FrontPath 摄取 API 的无框架客户端\.

### 如何安装 @forwardpath/js？

在项目目录运行 npm install @forwardpath/js，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：ai（^7）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @forwardpath/js 支持 TypeScript 吗？

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

### @forwardpath/js 支持 ESM 还是 CommonJS？

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

### @forwardpath/js 可以商用吗？

@forwardpath/js 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @forwardpath/js 的下载量有多少？

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

### @forwardpath/js 还在维护吗？

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