# @apicity/har 中文文档

规范地址：https://npmcn.com/package/%40apicity/har/

版本：0\.27\.0
npm 元数据更新时间：2026-11-06T09:55:58.389Z
中文译文更新时间：2026-11-06T17:35:52.045Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：274 kB，67 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：0 个
- 首次发布：2026-10-24T15:25:56.661Z
- 最新版本发布：2026-11-06T09:55:58.210Z
- 近 30 天下载量：2569（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

HAR 1.2 序列化,秘密洗涤和Polly记录身份.

## 安装

```sh
npm install @apicity/har
```

也可以使用：`pnpm add @apicity/har`、`yarn add @apicity/har`、`bun add @apicity/har`

## README

# @apicity/ har (英语)

无依赖性节点.js HAR 1.2 序列化、秘密清洗和选入 请求/回复抓取. `createHarCapture` 提供可注射取回, 调用瞄准镜,可选全局安装,以及带有JSONL索引的已刷取文件. 见 [抓取指南](https://npmcn.com/docs/har-capture.md) 关于设置和保留的细节.

```ts
import { exchangeToEntry, scrubHar, pollyEntryId } from "@apicity/har";

declare const request: Request; // the request you sent
declare const response: Response; // its response, body unread

const entry = await exchangeToEntry(request, response, {
  startedAt: new Date(),
  durationMs: 120,
});
entry._id = pollyEntryId(entry);
```

-   `createHarCapture({ dir, mode: "all" | "failures", providers?, maxBodyBytes?, maxSummarizeBytes?, sseTailBytes?, context?, onError?, clock?, idFactory? })` 返回时 `{ fetch, call, install, flush, close }`。包装提供者在 `call({ provider, endpoint, input, context?, estimate? }, fn)` 等待着 `close()` 退出前; 一个呼叫 `context` 被浅浅地合并在俘虏 `context` 只有那个电话. `estimate` (单位:千美元)`usd`, (中文(简体) ), `source`, (中文(简体) ), `rateAsOf`, (中文(简体) ), `warnings`, (中文(简体) ), `breakdown`, (中文(简体) ), `status`)写给 `log._apicity.estimate` 作为 `estimateUsd` 内 `index.jsonl`。 。 。 . `input` 与 1024 以上的每个数据 URL 或基数64 字段一起写 字符,以及每个字节数组,取而代之的是其散列的占位符,解码 大小和媒体类型。 抓取在写出错误后被禁用,而不更改 提供者结果。 无法读取的正文不会禁用它: 交换是 保存为 `bodyTruncated`,以及 `responseCut` 和呼吁的结果 实值 `network_error`。 。 。 .
-   `exchangeToEntry(request: Request, responseOrError: Response | Error, timing, options?)` 读取克隆并返回被擦除的条目。 时机已经 `startedAt`, (中文(简体) ), `durationMs` 和可选 HAR `timings`选项 `maxBodyBytes` (262144号) 默认), `maxSummarizeBytes` (16个米B), `sseTailBytes` (64个基B), `streamed` 财务报告和审定财务报表 `role`二进制和超大小的身体成为SHA-256、字节和MIME型 占位符,但 JSON 请求最多 `maxSummarizeBytes` 其文本符合 其介质汇总后封顶。 多段文件成为名称/类型/大小 总结。 内置数据URL和长基64被汇总. 一个文本流结束 盖子是第一个 `maxBodyBytes` 最后一个 `sseTailBytes`,整行 添加一个 `: apicity-gap <n> bytes dropped` 注释; `_apicity.streamed` 财务报告和审定财务报表 `bodyTruncated` 说明 他们。 中读失败的躯体 保存到达的东西: 溪流的整行,或 任何不解析整个 JSON 文档的占位符。 一个网络 错误生成状态 0; 呼叫级别错误元数据属于 `log._apicity`。 。 。 . `streamIncomplete` 标记一条无新线的线尾或 在公认的Anthropic、OpenAI或Google流中没有最终使用 也标记了整个保留的JSON反应,不解析,即使 运输报告清洁 EOF。 此 JSON 仅保存为散列/ 大小占位符 . 它设置 `bodyTruncated` 并保持成本证据未定。 不可分类 在一个公认的协议中,一个米B以上的框架或线条不完整。 这是 与留存额上限无关 `responseCut` (运输故障):完成 运输失败之后的最后用途仍然可以解决。 遗产捕获 无 `streamIncomplete` 保留现有的成本语义。 机构必须 未使用, 溪流必须最终完成; 中止的请求取消其 获取复制件, 这样它无法控制冲浪 .
-   `scrubEntry(entry)` 财务报告和审定财务报表 `scrubHar(har)` 变相而还其辩. 扫描覆盖信头、 URL、 JSON 和窗体编码的供应商证书 尸体,饼干, 响应账户元数据及 `_apicity` 输入/估计/内容/字段。 它保留了提示和 普通载荷。 这不是一般的个人数据匿名.
-   `pollyEntryId(entry, options?)` 使用 存储器的默认带匹配规则 。 自定义匹配要求 `excludeHeaders`, (中文(简体) ), `headers: false`,或 `body: false` 视情况而定。 URL 网络 以 Polly 的 url- parse 和 qs 的 url- parse 使其 正常化 : 键被排序并 RFC 3986 逃脱、重复、无值和括号的密钥被保留 碎片被丢弃。 被总结的身体不能复制其特征 原生字节, % 畸形的查询部分也不可能一次逃脱 (单位:千美元) `Request` 重新编码了它。 未关闭的已录入的 URL `[` 或超过 作为对该 URL 的新请求, 不如所记录:波利的再序列化在那里并不稳定.
-   `pollyRecordingDir(name)` 执行Polly的分块弹道和FNV-1a散列.
-   HAR 类型 : `Har`, (中文(简体) ), `HarLog`, (中文(简体) ), `HarEntry`, (中文(简体) ), `HarRequest`, (中文(简体) ), `HarResponse`, (中文(简体) ), `HarContent`, (中文(简体) ), `HarPostData`, (中文(简体) ), `HarNameValue`, (中文(简体) ), `HarCookie`, (中文(简体) ), `HarPage`, (中文(简体) ), `HarCacheEntry`, (中文(简体) ), `HarTimings`, (中文(简体) ), `ApicityCallMetadata`,以及 `ApicityEntryMetadata`。 。 。 .
-   选项 : `ExchangeTiming`, (中文(简体) ), `ExchangeOptions`, (中文(简体) ), `PollyIdentityOptions`。 。 。 .

记录工具的兼容性导出 : `redactPersistedHarSecrets`, (中文(简体) ), `persistSafeTextRequestBody`, (中文(简体) ), `summarizeJsonRequestBodyMedia`, (中文(简体) ), `summarizeMultipartFormData`, (中文(简体) ), `summarizeMultipartRequestBody`, (中文(简体) ), `redactedRequestId`, (中文(简体) ), `PersistedHarRecording`, (中文(简体) ), `REDACTED_HAR_VALUE`, (中文(简体) ), `HarHeaderLike`, (中文(简体) ), `HarCookieLike`, (中文(简体) ), `HarRequestLike`, (中文(简体) ), `HarResponseLike`, (中文(简体) ), `HarRecordingLike`, (中文(简体) ), `isSensitiveRequestHeaderName`, (中文(简体) ), `isSensitiveResponseHeaderName`, (中文(简体) ), `scrubSensitiveRequestHeaders`, (中文(简体) ), `scrubSensitiveResponseHeaders`, (中文(简体) ), `scrubRequestCookies`, (中文(简体) ), `scrubResponseCookies`, (中文(简体) ), `scrubSensitiveResponse`, (中文(简体) ), `scrubPolymarketAuthArtifacts`, (中文(简体) ), `scrubSensitiveRecording`, (中文(简体) ), `PERSISTED_REQUEST_HEADER_PLACEHOLDERS`, (中文(简体) ), `persistedRequestHeaderPlaceholder`, (中文(简体) ), `redactFalCheckpoints`, (中文(简体) ), `findUnredactedRequestSecrets`,以及 `findLiveFalCheckpoints`。 。 。 .

## 仓库整合

包裹拥有规则. `tests/harness.ts` 财务报告和审定财务报表 `tests/har-scrub.ts` 为: 兼容导出; Vitest 源别名与此包相悖 . 独立的 HAR 查看器/ 报告/ 电子邮件工具通过导入同一来源 `har-data.ts` 财务报告和审定财务报表 `har-scrub.ts` 使用相对路径,所以 `tsx` 还行 从寄存器之外,没有软件包构建或虚拟化名. `gen:shared` 副本 `src/har-secrets.mjs` 改为 `scripts/lib/har-secrets.mjs` (共享源的显式把它接上). 此已执行, 生成的复制让 `gen:examples:check`, (中文(简体) ), `lint:recordings` 财务报告和审定财务报表 `doc-gen:check` 运行一个干净的取出 在创建任何软件包之前. `gen:shared:check` 防止漂移。 没有运行时间软件包 这些脚本需要依赖或建立进口.

## 成本证据

`entryToProviderExchange` 将一个 HAR 输入到交换形状 `extractActual` 内 `@apicity/cost` 改为:小写页眉名称,解析出JSON或 SSE 数据框架和无效 `requestBody` 一个被俘的占位符。 这个包 不导入 `@apicity/cost`;形状结构吻合.

```ts
import { entryToProviderExchange, type HarEntry } from "@apicity/har";

declare const entry: HarEntry;

const exchange = entryToProviderExchange(entry, {
  provider: "openai",
  dotPath: "v1.responses",
});
exchange.responseHeaders["content-type"];
```

`provider` 回到拥有请求主机的那个.

## 交换分析助手

`exchangeSucceeded(provider, entry)` 需要 HTTP 2xx 并拒绝 KIE 和 xAI 失败信封. `responseObject(entry)` 解码 JSON 对象响应, 包括基础64 HAR内容.

`findMatchingRow(entry, rows, {provider})` 首先匹配完整的 URL,然后使用一个 提供者扫描路径匹配, 然后再次匹配 Fal 的全部 URL `{endpoint_id}` 横跨整个路径段( c)`fal-ai/flux/dev`) (中文(简体) ). 带行 `provider`, (中文(简体) ), `method`, (中文(简体) ), `dotPath` 财务报告和审定财务报表 `fullUrl`。 。 。 . `matchHarEntryStrict`, (中文(简体) ), `matchHarEntryLenient`, (中文(简体) ), `matchHarEntrySpanning` 财务报告和审定财务报表 `compileTsvUrlPattern` 曝光个人匹配操作. 这些是犬科动物 执行也同步到存储器脚本.

## 常见问题

### @apicity/har 是什么？

HAR 1\.2 序列化,秘密洗涤和Polly记录身份\.

### 如何安装 @apicity/har？

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

### @apicity/har 支持 TypeScript 吗？

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

### @apicity/har 支持 ESM 还是 CommonJS？

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

### @apicity/har 需要什么版本的 Node\.js？

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

### @apicity/har 可以商用吗？

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

### @apicity/har 的下载量有多少？

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

### @apicity/har 还在维护吗？

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