# @crvouga/mockingbird-service-persona 中文文档

规范地址：https://npmcn.com/package/%40crvouga/mockingbird-service-persona/

版本：3\.11\.0
npm 元数据更新时间：2026-11-11T02:25:26.973Z
中文译文更新时间：2026-11-11T06:26:52.939Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40crvouga/mockingbird-service-persona
原文对照：https://npmcn.com/package/%40crvouga/mockingbird-service-persona/?lang=original
项目主页：https://github.com/crvouga/mockingbird/tree/main/packages/service/persona#readme
源码仓库：https://github.com/crvouga/mockingbird

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

- 包体积（解压后）：4.4 MB，18 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-09-22T23:56:20.469Z
- 最新版本发布：2026-11-11T02:25:26.611Z
- 近 30 天下载量：2912（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：41（近 12 个月 41 个）

## 中文简介

Persona身份验证API的状态仿真器:查询创建,列表(可重复使用查询),获取,主机流程页面,管理生命周期过渡,Persona-Signature webhoks.

## 安装

```sh
npm install @crvouga/mockingbird-service-persona
```

也可以使用：`pnpm add @crvouga/mockingbird-service-persona`、`yarn add @crvouga/mockingbird-service-persona`、`bun add @crvouga/mockingbird-service-persona`

## README

# @crvouga/ 嘲笑鸟 - 服务 - 人

> 本地模拟器。 真正的API合同. 部分 [嘲笑鸟](https://github.com/crvouga/mockingbird)。 。 。 .

状态模拟器 **个人a**测试套房的身份验证API:创建查询, 查找“ 可重复使用的查询” 列表, 获取一个查询, 主机流程页成员被发送 改为和 `Persona-Signature`\- 签署事件 Persona回帖。 问询只在 测试是这样说的(管理动作或点击主机页面),所以Rx咨询的ID 核查步骤(旗帜) `rx-id-verification`)运行时没有真正的沙盒或真正的自拍.

-   行动范围: [支助](https://github.com/crvouga/mockingbird/blob/main/packages/service/persona/SUPPORT.md)
-   Persona没有发布OpenAPI文件:合同(`openapi.yaml`)是手写自 Persona的API参考文献(JSON:API, `Persona-Version: 2023-01-05`和我们的EMR的Zod计划.

## 安装

```bash
npm install -D @crvouga/mockingbird-service-persona
```

仅限无害环境管理。 节点 22或 Bun 1.2. 无土生属地. 给它服务 `npx mockingbird-persona serve`, (中文(简体) ), `createServer` 从 `./server` (节点),或 `createRuntime` 与 任何获取服务器.

## 使用量

将EMR指向模拟器(这些都需要在 `E/config/env.ts`:

| EMR 掩体 | 数值 |
| --- | --- |
| `PERSONA_API_URL` | `http://127.0.0.1:8815` (或 `…/__admin/ns/<namespace>`(中文(简体) ) |
| `PERSONA_API_KEY` | 任何持枪者(或已逝去者) `--api-key`(中文(简体) ) |
| `PERSONA_WEB_INQUIRY_URL`, (中文(简体) ), `PERSONA_MOBILE_INQUIRY_URL` | `http://127.0.0.1:8815/verify` |
| `PERSONA_IDENTITY_INQUIRY_TEMPLATE_ID`, (中文(简体) ), `PERSONA_PHONE_INQUIRY_TEMPLATE_ID` | 任意 `itmpl_…` 编号 |
| `PERSONA_WEBHOOK_SECRET` | 以 `--webhook-secret` |

```bash
npx mockingbird-persona serve --port 8815 \
  --webhook-url http://127.0.0.1:4000/v1/identify-verification/webhook \
  --webhook-secret "$PERSONA_WEBHOOK_SECRET"
```

```ts
import { createServer } from "@crvouga/mockingbird-service-persona/server"

// Test setup: a local Persona that posts its signed events to the app's webhook route.
const server = await createServer({
  webhooks: { url: "http://127.0.0.1:4000/v1/identify-verification/webhook", secret: "wbhsec_test" },
})
const baseUrl = server.url // the app's PERSONA_API_URL

// Application code: the request it sends to Persona.
const created = await fetch(`${baseUrl}/inquiries`, {
  method: "POST",
  headers: { authorization: "Bearer persona_sandbox_x", "content-type": "application/json" },
  body: JSON.stringify({
    data: { type: "inquiry", attributes: { "inquiry-template-id": "itmpl_identity", "reference-id": "patient-1" } },
  }),
})
const { data } = (await created.json()) as { data: { id: string } }

// Test control: finish it the way a member and Persona's workflow would: started → completed →
// approved, one signed event per step.
await fetch(`${baseUrl}/__admin/inquiries/${data.id}/approve`, { method: "POST" })

await server.close()
```

### 路线

| 路线 | 行为 |
| --- | --- |
| `POST /inquiries` | 亚庇: `{data: {type: "inquiry", attributes: {inquiry-template-id | template-id, reference-id, redirect-uri, fields, note, platform}}}` − 201个 `{data: <inquiry>, included: []}`状态 `created`编号 `inq_` +24个字符。 没有模板 ~ 400; 模板未在 `settings.templates` (或无) `itmpl_…`编号 :`tmpl_…` (未定时) — 422. 输出 `inquiry.created`。 。 。 . |
| `GET /inquiries` | `filter[reference-id]`, (中文(简体) ), `filter[inquiry-template-id]`, (中文(简体) ), `filter[status]` (comma名单), `page[size]` (1-100,默认为10), `page[after]`最先更新的; `links.next` 是下一页. |
| `GET /inquiries/{id}` | 调查,或404 `{errors: [{title: "Record not found", detail, status: "404"}]}`。 。 。 . |
| `GET /verify?inquiry-id=&redirect-uri=` | 主机流量页面( 上下行)`PERSONA_WEB_INQUIRY_URL`) (中文(简体) ). 开始调查`pending`, (中文(简体) ), `inquiry.started`),其链接完成. |
| `GET /verify/complete?inquiry-id=&outcome=&redirect-uri=` | `outcome` =: `approve`, (中文(简体) ), `decline`, (中文(简体) ), `needs_review`, (中文(简体) ), `complete` 或者说 `fail`; 然后为 302 至 `redirect-uri?inquiry-id=&status=&reference-id=`。 。 。 . |

查询资源带有Persona的属性(`status`, (中文(简体) ), `reference-id`, (中文(简体) ), `note`, (中文(简体) ), `created-at`, (中文(简体) ), `started-at`, (中文(简体) ), `completed-at`, (中文(简体) ), `failed-at`, (中文(简体) ), `decisioned-at`, (中文(简体) ), `expired-at`, (中文(简体) ), `name-first`编号 :`name-last`编号 :`birthdate` 从预填, `fields` 作为 `{type, value}`和 关系(`inquiry-template.data {type: "inquiry-template", id}`空无 `reports`, (中文(简体) ), `verifications`, (中文(简体) ), `sessions`, (中文(简体) ), `documents`, (中文(简体) ), `selfies`) (中文(简体) ). 错误为 JSON: API 带有 **字符串** `status`我们的消费者 `PersonaErrorSchema` 要求.

认证 : `Authorization: Bearer <key>` 每个 API 路由( 丢失 ~ 401 JSON: API 错误) . `PUT /__admin/settings {"apiKeys": [...]}` 限制接受哪些密钥.

### 生命周期和网点

`created → pending → completed → approved | declined | needs_review`附加时 `failed` 财务报告和审定财务报表 `expired` 从公开调查。 关于公开调查的决定通过 `completed` 第一个 (作为完成流程和工作流程决定的成员),因此每个步骤都发出自己的信号 事件: `inquiry.created`, (中文(简体) ), `inquiry.started`, (中文(简体) ), `inquiry.completed`, (中文(简体) ), `inquiry.approved`, (中文(简体) ), `inquiry.declined`, (中文(简体) ), `inquiry.marked-for-review`, (中文(简体) ), `inquiry.failed`, (中文(简体) ), `inquiry.expired`。 。 。 .

每次活动都是Persona的信封, `{data: {type: "event", id: "evt_…", attributes: {name, payload: {data: <inquiry>, included: [], meta: {}}, created-at}}}`,张贴于 `Persona-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>`。时间戳是 墙上钟. 非-2xx的答案被重审(立即,5s,5min,30min,2h); `GET /__admin/webhooks`, (中文(简体) ), `/__admin/webhooks/events`, (中文(简体) ), `POST /__admin/webhooks/flush`, (中文(简体) ), `/__admin/webhooks/:id/replay` 财务报告和审定财务报表 `PUT /__admin/webhook-endpoints` 到处工作.

### 管理员(超过标准合同)

| 路线 | 效果 |
| --- | --- |
| `POST /__admin/inquiries/:id/{approve|decline|needs_review}` | 目录的决定(通过 `completed` 调查尚未结束时). |
| `POST /__admin/inquiries/:id/{start|complete|fail|expire}` | 其他生命周期步骤. 非法行动为409起,身份不明的为404起. |
| `GET /__admin/inquiries` | 地名空间的查询. |
| `GET/PUT /__admin/settings` | `{apiKeys?: string[], templates?: string[]}` 呼叫的命名空间. |
| `POST /__admin/signature-faults` | `{mode: "mismatch" | "short", count?}`: 接下来的事件签名错误. `mismatch` 保持长度( 我们的接收者回答 401 ); `short` 切换十六进制( 我们的接收器) `timingSafeEqual` 掷出:500分. |

错误预设( E)`POST /__admin/faults {"preset": "<name>", "count"?: n}`: `list_fails` (单位:千美元) 可重复使用的搜索500s;我们的客户端无法打开并创建), `create_fails`, (中文(简体) ), `not_found`, (中文(简体) ), `unauthorized`, (中文(简体) ), `rate_limited` (429个), `server_error`, (中文(简体) ), `slow` (3个s), `webhook_duplicate`, (中文(简体) ), `webhook_reorder`, (中文(简体) ), `webhook_drop`。 。 。 .

### 命名空间

`x-mockingbird-namespace`页:1 `/__admin/ns/<name>` 前缀在 `PERSONA_API_URL` 财务报告和审定财务报表 `PERSONA_WEB_INQUIRY_URL` (主机页面的链接保留它),或 API 密钥: `PUT /__admin/credentials {"credentials": {"<PERSONA_API_KEY>": "<namespace>"}}`。 。 。 .

### 我们的消费者用它做什么(差异)

-   我们的EMR只行动于 `status === "completed"` (单位:千美元)`updateIdentityVerificationForPatient`(三); `approved`编号 :`declined` 事件被解析和忽略。 所以一个被拒绝的调查已经标记 经核查的成员 `completed`。模拟器发送两个事件 所以套房可以看到.
-   我们的接收器比较签名和 `crypto.timingSafeEqual`,这表示长度 不匹配: 长度错误 `v1=` 是一个未发现的500,而不是一个401(`signature-faults` `short`) (中文(简体) ).
-   我们的消费者没有正式的Persona Node SDK (Plade) `fetch`),所以没有SDK 滴入测试.

### 故意不模拟

-   核查、报告、会话、文件和自拍:关系总是空的 没有政府ID或自拍捕捉。 主机页面是一组链接.
-   调查模板的步骤和工作流程`next-step-name` 仅是 `start` 编号 : `success`),恢复 会话符号( e)`POST /inquiries/{id}/resume`、编辑、标签和账户.
-   调查在计时器上已过期:调查仅通过 `…/expire`。 。 。 .
-   嵌入式(JS SDK / iframe)流和移动式 SDK.

## API 密码

| 导出 | 仁爱 | 说明 |
| --- | --- | --- |
| `PersonaAPI` | 类 | 进程模拟器 : `fetch(request)`, (中文(简体) ), `reset()`, (中文(简体) ), `transition(id, action)`, (中文(简体) ), `inquiries()`选项: `sqlite`, (中文(简体) ), `now`, (中文(简体) ), `namespace`, (中文(简体) ), `publicNamespace`, (中文(简体) ), `settings`, (中文(简体) ), `onWebhook`。 。 。 . |
| `createRuntime` | 函数 | 全面服务合同的仿真器(健康、管理、命名空间、证书、预设、网络呼号)。 选项 : `webhooks: {url, secret, retryDelaysMs?, fetch?}`, (中文(简体) ), `settings`, (中文(简体) ), `clock`, (中文(简体) ), `seed`, (中文(简体) ), `adminKey`, (中文(简体) ), `onLog`。 。 。 . |
| `PERSONA_PRESETS` | 对象 | 每个命名的断层预设. |
| `PERSONA_SIGNATURE_HEADER` | 字符串 | `"Persona-Signature"`。 。 。 . |
| `PERSONA_NAMESPACE`, (中文(简体) ), `PERSONA_VERSION` | 字符串 | `"persona"`, (中文(简体) ), `"2023-01-05"`。 。 。 . |
| `INQUIRY_ACTIONS` | 数组 | 管理者生命周期行动. |
| `inquiryResource` | 函数 | 将查询记录序列化为Persona's JSON:API资源. |
| `personaErrors` | 函数 | JSON: API 错误响应( 字符串) `status`) (中文(简体) ). |
| `DEFAULT_SETTINGS` | 对象 | 默认每个名称空间设置 . |
| `document`, (中文(简体) ), `operationIds`, (中文(简体) ), `supportedOperationIds` | 数值 | 销售商为OpenAPI合同及其业务代号. |
| `createServer`, (中文(简体) ), `serveTarget`, (中文(简体) ), `DEFAULT_PORT` (单位:千美元)`./server`(中文(简体) ) | 节点 | 服务过来 `node:http`; 数据 `serve` CLI目标; 第8815口. |

部分 [嘲笑鸟](https://github.com/crvouga/mockingbird)。 。 。 .

## 常见问题

### @crvouga/mockingbird-service-persona 是什么？

Persona身份验证API的状态仿真器:查询创建,列表\(可重复使用查询\),获取,主机流程页面,管理生命周期过渡,Persona-Signature webhoks\.

### 如何安装 @crvouga/mockingbird-service-persona？

在项目目录运行 npm install @crvouga/mockingbird-service-persona，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mockingbird-persona，可以用 npx mockingbird-persona 直接运行。

### @crvouga/mockingbird-service-persona 支持 TypeScript 吗？

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

### @crvouga/mockingbird-service-persona 支持 ESM 还是 CommonJS？

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

### @crvouga/mockingbird-service-persona 可以商用吗？

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

### @crvouga/mockingbird-service-persona 的下载量有多少？

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

### @crvouga/mockingbird-service-persona 还在维护吗？

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