# @hyperframes/inspector 中文文档

规范地址：https://npmcn.com/package/%40hyperframes/inspector/

版本：0\.8\.226
npm 元数据更新时间：2026-11-01T06:32:42.247Z
中文译文更新时间：2026-11-01T11:10:41.963Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：3.6 MB，85 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：9 个
- 首次发布：2026-10-13T05:12:00.068Z
- 最新版本发布：2026-11-01T06:32:41.932Z
- 已发布版本数：75（近 12 个月 75 个）

## 中文简介

恢复原始的HTML/CSS/GSAP上下文 **编辑前的已知元素**。这不是视频检查、屏幕截图、diff或受影响组件验证器。它将I002运行时/编译器来源方法与I003 hf拥有的服务边界结合起来。T

## 安装

```sh
npm install @hyperframes/inspector
```

也可以使用：`pnpm add @hyperframes/inspector`、`yarn add @hyperframes/inspector`、`bun add @hyperframes/inspector`

## README

# 组件源检查（可选择加入）

恢复原始的HTML/CSS/GSAP上下文 **编辑前的已知元素**。这不是视频检查、屏幕截图、diff或受影响组件验证器。它将I002运行时/编译器来源方法与I003 hf拥有的服务边界结合起来。代理适配器不持有DOM或动画状态。

出版 `@hyperframes/inspector`。它不会修改共享安装，也不会在线束中注册自己。

## 开始

从这个结帐，与Bun和安装Chrome/无头外壳：

```sh
bun install --ignore-scripts
bun run --filter '@hyperframes/{parsers,lint,studio-server}' build
bun run build:hyperframes-runtime
# Optional when Chrome is not already under ~/.cache/hyperframes/chrome:
export HF_INSPECT_CHROME=/absolute/path/to/chrome
bun packages/inspector/src/server.ts /absolute/video/project
```

服务打印它的环回URL。开始时确实如此 **不** 启动浏览器。第一次检查加载项目一次。

包提供功能，而不是代理工具：一个工具定义它自己的工具名称、描述和模式，以及调用 `POST /inspect` 使用下面的JSON。该服务在启动时绑定到一个项目，因此不需要每个调用的项目路径。 `GET /info` 返回项目标识和启动/查询计数器。Stop with SIGINT/SIGTERM；服务处理自己的页面/浏览器。

## 输入

```json
{
  "targets": [
    { "selector": "#title" },
    { "selector": ".subtitle", "within": "#chapter-flow" },
    { "hfId": "hf-8e8x" },
    { "ref": "hfi:GENERATION:NUMBER" }
  ]
}
```

-   `within` 是可选的。只有一个匹配成功；多个匹配返回候选项，而不是默默地返回第一个匹配。坏目标不会丢弃同一批中的有效目标。
-   Refs标识实际的元素，包括没有id的子元素，并在源更改、空闲释放或处置时过期。HF id可以跨组件实例重复；这些也会返回歧义。
-   默认情况下包括后代（最多1000个，带有显式截断标志）。
-   普通请求不查找、拍照、渲染帧或编码视频。
-   可选 `time` 请求一个精确的HF搜索并报告玩家的时间/持续时间。它是用于故意的运行时探索，而不需要检查预定的动画代码。

## 输出

默认JSON的上限为12,000 UTF-8字节，包括元数据。每个片段的 `id` 命名它的文件及其开始和结束行(`file:start-end`）; 一个片段也有它的种类， **未修改的完整源代码行**，以及该块是否在文件中只出现一次。当查询指定多个目标时， `targets` 给出它所服务的输入目标索引。代码中不插入漂亮的打印或省略号。相邻/重叠块跨目标合并。

```json
{
  "generation": "...",
  "results": [{ "target": 0, "status": "found", "animations": 4 }],
  "snippets": [
    {
      "id": "scene.html:20-24",
      "kind": ["animation creation"],
      "targets": [0, 1],
      "code": "the exact original source lines, including whitespace",
      "uniqueInFile": true
    }
  ]
}
```

本例省略了元数据。实现报告中的实际文件显示了完整的输出。

共享的助手只出现一次 **查询** 使用它们的目标。 `coTargets` 命名最多三个观察到的同一间间的附加DOM目标，优先考虑查询之外的元素，以及 `coTargetsOmitted` 计算剩下的；它不要求枚举对helper的所有单独调用。创建语句和授权调用方语句被映射；小的命名帮助函数是完整返回的。变量赋值不是堆栈/数据流历史记录。一个缺失的源源增量 `unmappedAnimations`，而不是猜测一个可编辑的位置。

HTML片段是唯一标识的授权开始标记（它们的完整源代码行）；动态生成的标记可能没有生成的标记匹配。CSS是一种授权选择器候选扫描，而不是活动级联、媒体查询状态或继承样式的证明。特别是，在不同作用域场景样式中重用的类可以有多个候选源规则。

### 更大的结果

代码块是原子的。 `omitted`， `omittedCount`, `nextOffset` 描述丢失的积木。重复相同的目标与返回 `generation` 和 `offset: nextOffset`，或请求选定的id：

```json
{ "targets": [], "generation": "RETURNED_GENERATION", "snippets": ["scene.html:20-24"] }
```

`maxBytes` 可以显式提高（2,048-256,000）。大于预算的块不会被切成两半：请求具有更大预算的ID或读取其文件/范围。因此，在预算增加之前，分页可以保持相同的偏移量。老一代的延续被拒绝。

的显式HTTP请求才能获得完整的运行时证据 `debug: true`;它故意不作为默认请求或其输出预算的一部分。

## 时间轴

`POST /timeline` 回答在同一浏览器、页面和生成时调度哪些动画 `/inspect`。它从不查找、渲染或编辑文件。

```json
{ "component": { "selector": "#title" }, "boundary": 7.9 }
```

`component` 是可选的，并且像 `/inspect` 目标;对于每一个已注册的HF时间轴忽略它。最多给一个 `at`， `range: [start, end]` 或者 `boundary`，以全球秒为单位；在进度概述中省略这三个部分。结果是按组件分组的短文本，包含事件时间、目标、属性和源位置； `generation` 和 `offset` 浏览它们。覆盖范围仅为注册dom -目标GSAP动画和显式HF项目；任何超出这一范围或超过扩张限制的内容都将被报告为不完整覆盖，而不是猜测。

## 元素映射

`POST /element-map` 返回来自同一页面的组合元素映射。它不读取查询字段。一个没有 `index.html` 答案 `404` `{ "error": "no-composition", "code": "no-composition" }`.

## 错误

每次拒绝都是JSON `{ "error", "code" }`. `code` 是稳定令牌(`no-composition`， `stale_generation`， `source_changed_during_query`， `request_too_large`）; 没有标记的句子是 `invalid_request`。缺少的浏览器是 `503` `browser_unavailable`，而意外的失败是 `500` `internal_error`。导入模块不会监听； `createInspectorServer(project)` 构建一个。一条未知的路线是 `404` `{ "error": "not_found", "code": "not_found" }`. `GET /info` 增加了 `version`，此软件包的版本。进程监听 `127.0.0.1` 并拒绝 `Host` 这不是环回，因此重新绑定请求不能读取项目路径。使用以下包安装服务器： `hyperframes-inspector <project> [port]`，或者 `node dist/server.js`.

## 生命周期和开销

一个懒惰的浏览器，每个项目服务一个不可变的绑定页面。Warm查询重用这两者。源HTML/JS/CSS/JSON是内容散列的；更改会关闭旧页面并创建一个新页面，从而重用浏览器。业务对请求进行序列化，查询完成后重新检查源指纹。没有工作室的热补丁或旧的时间线对象在重建中幸存下来。两分钟空闲时间释放页面和浏览器。仅更改媒体字节不属于源上下文无效机制的一部分。

GSAP钩子是在编写页面脚本之前安装的。它们只存在于检查页面中，而不是正常的Studio、检查或呈现路径中。运行时记录的上限为20,000条。正常高频输出中不注入记录仪。未执行的回调创建的动画，原始构造函数，其他动画系统，iframe内容和删除的动画不在覆盖范围内。显式时间查询可以执行回调；它不能证明所有未来的道路都被覆盖了。

## 验证

```sh
bun run --filter @hyperframes/inspector test
bunx tsc -p packages/inspector/tsconfig.json --noEmit
bun packages/inspector/tests/browser.ts /absolute/path/to/gsap.min.js
bun packages/inspector/tests/lifecycle.ts /absolute/path/to/gsap.min.js
bun packages/inspector/tests/transport.ts /absolute/path/to/Rowan-film
bun packages/inspector/tests/film.ts /absolute/path/to/Rowan-film /tmp/film-inspection.json
```

浏览器测试生成一次性固定装置。电影审计在剪辑前将源/资产复制到临时项目中；它从不编辑提供的原件。它检查固定帧奇偶性、精确源片段、页面替换、浏览器重用和播放器时间/持续时间。这是工程验证，而不是额外的付费代理A/B或证明的令牌/成本效益。

## 常见问题

### @hyperframes/inspector 是什么？

恢复原始的HTML/CSS/GSAP上下文 编辑前的已知元素。这不是视频检查、屏幕截图、diff或受影响组件验证器。它将I002运行时/编译器来源方法与I003 hf拥有的服务边界结合起来。T

### 如何安装 @hyperframes/inspector？

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

### @hyperframes/inspector 支持 TypeScript 吗？

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

### @hyperframes/inspector 支持 ESM 还是 CommonJS？

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

### @hyperframes/inspector 可以商用吗？

@hyperframes/inspector 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @hyperframes/inspector 还在维护吗？

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