# @basis-theory/react-agentic 中文文档 规范地址：https://npmcn.com/package/%40basis-theory/react-agentic/ 版本：2\.1\.0 npm 元数据更新时间：2026-11-02T18:33:36.968Z 中文译文更新时间：2026-11-07T18:01:25.555Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40basis-theory/react-agentic 原文对照：https://npmcn.com/package/%40basis-theory/react-agentic/?lang=original ## 关键信息（来自 npm 元数据） - 包体积（解压后）：819 kB，80 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：0 个 - peer 依赖：react ^18\.2\.0 \|\| ^19\.0\.0，react-dom ^18\.2\.0 \|\| ^19\.0\.0 - 首次发布：2026-03-13T02:29:21.528Z - 最新版本发布：2026-09-11T18:09:24.096Z - 近 30 天下载量：106270（2026-10-08 至 2026-11-06，npm 官方下载统计） - 已发布版本数：18（近 12 个月 18 个） ## 中文简介 基础理论 AI 反应库 ## 安装 ```sh npm install @basis-theory/react-agentic ``` 也可以使用：`pnpm add @basis-theory/react-agentic`、`yarn add @basis-theory/react-agentic`、`bun add @basis-theory/react-agentic` ## README # @ basis-理论/反应代理 > \[大 **需要使用HTTPS.** 用于验证的卡片网络SDK(Visa和Mastercard)要求您的应用程序在HTTPS上服务,即使在开发中也如此. 普通HTTP的验证失败 . > > 对于地方发展,我们建议 [云浮快隧道](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/) 用零配置在 HTTPS 上曝光您的本地服务器 : > > ```bash > # Install cloudflared > brew install cloudflared > > # Start a quick tunnel pointing to your local dev server > cloudflared tunnel --url http://localhost:3000 > ``` > > 这给你一个临时的 `https://*.trycloudflare.com` URL 您可以用于测试 . ## 安装 ```bash npm install @basis-theory/react-agentic ``` ## 设置 包装您的应用程序 `BtAiProvider`数字 : ```jsx import { BtAiProvider } from '@basis-theory/react-agentic'; function App() { return ( ); } ``` ### BtAi 提供道具 | Prop | 类型 | 需求 | 说明 | | --- | --- | --- | --- | | `apiKey` | `string` | 对 | 基础理论 AI 公共 API 密钥 | | `environment` | `'production' | 'test'` | 没有 | 要使用的环境( 默认 ): `production`(中文(简体) ) | | `agenticApiUrl` | `string` | 没有 | 覆盖代理商务 API 基础 URL | | `passkeyTimeoutMs` | `number` | 没有 | Visa 密码认证的超时( 默认 ) ms `60000`(中文(简体) ) | | `sessionReadyTimeoutMs` | `number` | 没有 | 刷新后签证会话准备超时( 默认值 : `10000`(中文(简体) ) | | `onNewDevice` | `'decline' | 'reenroll'` | 没有 | 当指令校验检测到不同的设备时的行为( 默认 ): `reenroll`(中文(简体) ) | ## SDK 准备状态 这个 `useAgentic` 钩子会暴露 `ready` 布尔表示基础卡网SDKs(Visa和Mastercard)何时完成初始化. 在SDK准备就绪之前,用这个来防止调用核查方法. ```jsx import { useAgentic } from '@basis-theory/react-agentic'; function VerifyButton() { const { ready, verifyEnrollment } = useAgentic(); return ( ); } ``` - `false` 初始化和SDK初始化期间 - `true` 至少一个卡片网络SDK(Visa或Mastercard)已经准备好 - 恢复为 `false` 如果提供者卸载或环境发生变化 所有核查方法`verifyEnrollment`, (中文(简体) ), `verifyInstruction`自动等待 `ready` 在执行前,所以在初始化完成之前可以安全地给他们打电话——他们会排队直到SDK准备好. 颗粒网状态,使用 `getStatus()` 返回时 `{ visa: boolean, mastercard: boolean }`。 。 。 . ## 钩子 ### `useAgentic()` 编号 : `useBtAi()` 与SDK互动的主钩. 返回验证方法和SDK状态. ```jsx import { useAgentic } from '@basis-theory/react-agentic'; function MyComponent() { const { ready, // boolean - whether the SDK is ready apiKey, // string - current API key environment, // string - current environment updateApiKey, // (newKey: string) => void getStatus, // () => { visa: boolean, mastercard: boolean } verifyEnrollment, // (enrollmentId: string) => Promise verifyInstruction, // (agentId: string, instructionId: string) => Promise } = useAgentic(); } ``` 两者 `useAgentic()` 财务报告和审定财务报表 `useBtAi()` 返回同一接口——以您喜欢的为准. ### `useEnrollmentVerification()` 基于行动的钩子用于建立 **自定义注册验证 UI**。根据 `status` 并要求相应的行动来推进流动. 这个钩子处理两个卡片网络的完整管弦: - **签证**\- 完成 - **总卡**: 弹出式认证 – 完成 #### 状态 | 状态 | 说明 | 可用动作 | | --- | --- | --- | | `idle` | 未开始 | `start()` | | `loading` | 正在运行中 | —— 说 | | `otp_required` | 显示 OTP 方法拾取器( O)`otpMethods` (备有) | `selectOtpMethod(methodId)` | | `otp_sent` | 显示 OTP 代码输入 | `submitOtp(code)` | | `passkey_required` | 需要创建签证密码 | `confirmPasskey()` | | `popup_required` | 需要主卡弹出 | `confirmPasskey()`, (中文(简体) ), `retry()` | | `verified` | 核查完成 | —— 说 | | `error` | 出事了(`error` 有消息) | `retry()`, (中文(简体) ), `start()` | #### 示例 ```jsx import { useEnrollmentVerification } from '@basis-theory/react-agentic'; function CustomEnrollmentUI({ enrollmentId }) { const { status, // current status (see table above) error, // string | null — error message when status is 'error' otpMethods, // available OTP methods when status is 'otp_required' start, // () => Promise — begin or restart verification selectOtpMethod, // (methodId: string) => Promise — select an OTP delivery method submitOtp, // (code: string) => Promise — submit the OTP code confirmPasskey, // () => Promise — trigger passkey creation (Visa) or popup (Mastercard) retry, // () => Promise — retry the current step (or restart if needed) cancel, // () => void — cancel and reset to idle } = useEnrollmentVerification({ enrollmentId }); // Render your own UI based on status } ``` #### 如何构建自己的用户界面 - 打电话 `start()` 以启动入学核查流程 - 打开 `status` 使每一步骤具有适当的UI: - **`loading`** 显示自旋器或加载指示器 - **`otp_required`** - 从 `otpMethods` 打电话 `selectOtpMethod(methodId)` 选择时 - **`otp_sent`** ——提供代码输入字段并调用 `submitOtp(code)` 提交时 - **`passkey_required`** 显示快速/ 按钮解释密码创建和呼叫 `confirmPasskey()` - **`popup_required`** 显示一个快速/ 按钮解释 Mastercard 弹出认证和呼叫 `confirmPasskey()` - **`verified`** 显示成功信息, 继续您的应用程序流 - **`error`** - 显示 `error` 带有按钮的信件 `retry()` 或者说 `start()` 再来一次 - 使用 `cancel()` 让用户中止并重置到 `idle` 任何时候 - 钩子在内部管理所有的卡- 网络管弦乐—— 您只需要渲染UI和调用动作 ### `useInstructionVerification()` 基于行动的钩子用于建立 **自定义指令校验**。处理两个卡片网络的密码认证: - **签证**: 密码认证 – 完成 - **总卡**: 弹出式认证 – 完成 #### 状态 | 状态 | 说明 | 可用动作 | | --- | --- | --- | | `idle` | 未开始 | `start()` | | `loading` | 正在运行中 | —— 说 | | `passkey_required` | 需要签证密码 | `confirmPasskey()` | | `popup_required` | 需要主卡弹出 | `confirmPasskey()`, (中文(简体) ), `retry()` | | `verified` | 核查完成 | —— 说 | | `error` | 出事了(`error` 有消息) | `retry()`, (中文(简体) ), `start()` | #### 示例 ```jsx import { useInstructionVerification } from '@basis-theory/react-agentic'; function CustomInstructionUI({ agentId, instructionId }) { const { status, // current status (see table above) error, // string | null — error message when status is 'error' start, // () => Promise — begin or restart verification confirmPasskey, // () => Promise — trigger passkey auth (Visa) or popup (Mastercard) retry, // () => Promise — retry the current step (or restart if needed) cancel, // () => void — cancel and reset to idle } = useInstructionVerification({ agentId, instructionId }); // Render your own UI based on status } ``` #### 如何构建自己的用户界面 - 打电话 `start()` 以启动指令验证流程 - 打开 `status` 使每一步骤具有适当的UI: - **`loading`** 显示自旋器或加载指示器 - **`passkey_required`** 显示一个快速/按钮解释 Visa 密码认证和呼叫 `confirmPasskey()` - **`popup_required`** 显示一个快速/ 按钮解释 Mastercard 弹出认证和呼叫 `confirmPasskey()` - **`verified`** 显示成功信息, 继续您的应用程序流 - **`error`** - 显示 `error` 带有按钮的信件 `retry()` 或者说 `start()` 再来一次 - 使用 `cancel()` 让用户中止并重置到 `idle` 任何时候 - 钩子在内部管理所有的卡- 网络管弦乐—— 您只需要渲染UI和调用动作 ## 核查 打开一个模式,引导用户通过入学验证。 自动处理Visa(OTP + 密码创建)和Mastercard(流行认证)的流量. ```jsx import { useAgentic } from '@basis-theory/react-agentic'; function EnrollmentExample() { const { verifyEnrollment } = useAgentic(); const handleVerify = async () => { try { const result = await verifyEnrollment('enrollment-id'); console.log('Verified:', result); } catch (err) { console.error('Verification failed:', err.message); } }; return ; } ``` ## 校验 打开一个模式,通过指令验证(passkey认证)来引导用户. 支持Visa和Mastercard卡两种卡. ```jsx import { useAgentic } from '@basis-theory/react-agentic'; function InstructionExample() { const { verifyInstruction } = useAgentic(); const handleVerify = async () => { try { const result = await verifyInstruction('agent-id', 'instruction-id'); console.log('Verified:', result); } catch (err) { console.error('Verification failed:', err.message); } }; return ; } ``` ## 公用事业 ### `collectDeviceContext()` 收集随核查请求而发送的浏览器和设备指纹数据. 如果你正在构建一个完全定制的集成,就很有用. ```jsx import { collectDeviceContext } from '@basis-theory/react-agentic'; const context = collectDeviceContext(); // { userAgent, language, platform, screenResolution, ... } ``` ## 许可证 麻省理工学院 ## 常见问题 ### @basis-theory/react-agentic 是什么？ 基础理论 AI 反应库 ### 如何安装 @basis-theory/react-agentic？ 在项目目录运行 npm install @basis-theory/react-agentic，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.2\.0 \|\| ^19\.0\.0）、react-dom（^18\.2\.0 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @basis-theory/react-agentic 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @basis-theory/react-agentic 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @basis-theory/react-agentic 可以商用吗？ @basis-theory/react-agentic 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @basis-theory/react-agentic 的下载量有多少？ 根据 npm 官方下载统计，@basis-theory/react-agentic 在 2026/10/08 – 2026/11/06 这 30 天内被下载 106,270 次，日均约 3,542 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @basis-theory/react-agentic 还在维护吗？ 最新版本 2\.1\.0 发布于 2026/09/12（1 个月前）；至今共发布 18 个版本，其中过去 12 个月发布了 18 个；首次发布于 2026/03/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。