# @cogniqa-app/recorder 中文文档

规范地址：https://npmcn.com/package/%40cogniqa-app/recorder/

版本：0\.3\.5
npm 元数据更新时间：2026-11-04T15:48:38.233Z
中文译文更新时间：2026-11-10T13:05:07.613Z
软件包许可：UNLICENSED

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

原始 npm 页面：https://www.npmjs.com/package/%40cogniqa-app/recorder
原文对照：https://npmcn.com/package/%40cogniqa-app/recorder/?lang=original
项目主页：https://github.com/flabdev/CogniQA/tree/main/apps/recorder-cli#readme
源码仓库：https://github.com/flabdev/CogniQA

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

- 包体积（解压后）：164 kB，16 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=18\.0\.0
- 运行依赖：4 个
- 首次发布：2026-08-18T09:07:51.640Z
- 最新版本发布：2026-11-04T15:48:38.102Z
- 近 30 天下载量：2559（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

CognitQA的本地记录器——在您自己的机器上发射一个真实的浏览器,这样"记录"就可以将您的点击作为测试步骤来捕捉,而不会有一个浏览器在CognitQA的服务器上运行.

## 安装

```sh
npm install @cogniqa-app/recorder
```

也可以使用：`pnpm add @cogniqa-app/recorder`、`yarn add @cogniqa-app/recorder`、`bun add @cogniqa-app/recorder`

## README

# @cognique-app/录音机

[![npm version](https://img.shields.io/npm/v/@cogniqa-app/recorder.svg)](https://www.npmjs.com/package/@cogniqa-app/recorder) [![License](https://img.shields.io/npm/l/@cogniqa-app/recorder.svg)](https://github.com/flabdev/CogniQA/blob/main/apps/recorder-cli/package.json)

> **本地浏览器记录器 [认知](https://cogniqa.fissionlabs.com/)** ——在自己的机器上发射一个真实的浏览器,这样你就可以通过简单的点击应用程序来记录测试步骤. 在录制过程中,没有浏览器运行在CognitQA的服务器上.

## 目录

-   [这是什么?](https://npmcn.com/package/%40cogniqa-app/recorder/#readme-what-is-this)
-   [特征](https://npmcn.com/package/%40cogniqa-app/recorder/#readme-features)
-   [先决条件](https://npmcn.com/package/%40cogniqa-app/recorder/#readme-prerequisites)
-   [安装](https://npmcn.com/package/%40cogniqa-app/recorder/#readme-installation)
-   [使用量](https://npmcn.com/package/%40cogniqa-app/recorder/#readme-usage)
    -   [启动录音机](https://npmcn.com/package/%40cogniqa-app/recorder/#readme-start-the-recorder)
    -   [禁用自动启动](https://npmcn.com/package/%40cogniqa-app/recorder/#readme-disable-autostart)
-   [配置](https://npmcn.com/package/%40cogniqa-app/recorder/#readme-configuration)
    -   [更改本地端口](https://npmcn.com/package/%40cogniqa-app/recorder/#readme-changing-the-local-port)
    -   [自办/开发设置](https://npmcn.com/package/%40cogniqa-app/recorder/#readme-self-hosted--development-setups)
-   [如何运作](https://npmcn.com/package/%40cogniqa-app/recorder/#readme-how-it-works)
-   [警卫](https://npmcn.com/package/%40cogniqa-app/recorder/#readme-security)
-   [系统要求](https://npmcn.com/package/%40cogniqa-app/recorder/#readme-system-requirements)
-   [解决问题](https://npmcn.com/package/%40cogniqa-app/recorder/#readme-troubleshooting)
-   [许可证](https://npmcn.com/package/%40cogniqa-app/recorder/#readme-license)

## 这是什么?

`@cogniqa-app/recorder` 是CognitQA用户的相伴 CLI 。 单击时 **"记录"** 在CognitQA网络应用内部

1.  接收来自Cognica的一次性安全票
2.  启用真实的 Chromium 浏览器窗口 **** 机器
3.  重放任何已有的前提条件步骤, 这样您就可以从正确的页面开始
4.  抓取每次点击、填充和导航作为结构化测试步骤
5.  把这些步骤实时流回Cognica

因为浏览器在本地运行,所以可以与内部站点,被VPN保护的应用软件,或者公司防火墙后的任何东西交互——你的应用程序流量都没有离开你的机器.

## 特征

-   **当地第一记录** ——浏览器运行在您的机器上,而不是在云中
-   **温暖开始重放** ——在开始录制前自动重放已存在的登录/先决条件步骤
-   **游戏机驱动** – 建于同名录音引擎上 `npx playwright codegen`
-   **电子覆盖** —— 运行/ 完成/ 删除控件的清洁浮动工具栏
-   **自动发射** ——可选注册自己在登录时自动启动
-   **单会场安全** ——一次只录制一个会话;拒绝意外双开
-   **原产地锁定** – 只接受来自 CogniaQA 网络来源的命令

## 先决条件

-   **节点.js** `>= 18.0.0` (LTS建议)
-   **无** 或者说 **npx 数据** (来与节点.js)

录音窗口运行在Electron上,安装时自动下载——不需要单独的浏览器安装.

## 安装

您不需要复制此寄存器 。 从 npm 直接安装 :

```bash
npm install -g @cogniqa-app/recorder
```

或按需运行而不安装:

```bash
npx @cogniqa-app/recorder listen
```

在全局安装后,二进制为:

```bash
cogniqa-recorder listen
```

## 使用量

### 启动录音机

使用 CognitQA 时, 把这个运行在终端中 :

```bash
cogniqa-recorder listen
```

你会看到:

```
[recorder] Listening on http://127.0.0.1:51820 — leave this running, then click
[recorder] "Record" in CogniQA. Press Ctrl+C to stop.
```

在第一个成功运行时, 记录器也会自动注册, 在登录时自动启动( 您可以稍后禁用 ) .

### 禁用自动启动

如果您不再需要记录器在登录时自动启动 :

```bash
cogniqa-recorder disable
```

## 配置

对主机 CognitQA 实例的正常使用不需要配置 .

### 更改本地端口

如果默认端口已经被取走, 您可以覆盖它 :

```bash
# macOS / Linux
COGNIQA_RECORDER_PORT=51900 cogniqa-recorder listen

# Windows (PowerShell)
$env:COGNIQA_RECORDER_PORT=51900; cogniqa-recorder listen
```

录音机只能绑住 `127.0.0.1` (当地主播). 无法从你网络上的另一台机器上找到它 不管它使用的是哪个端口.

### 自办/开发设置

默认录音机会与主机CogniaQA交谈 `latest` 仅接受构建 `https://cogniqa.fissionlabs.com`,以及 `@beta` 编号 : `@stage` 仅接受构建 `https://dev-cogniqa.fissionlabs.com`。 。 。 .

如果您正在本地运行自己的 CognitQA 后端和网络应用程序, 请在启动记录器前设置 :

```bash
# macOS / Linux
COGNIQA_API_URL=http://localhost:3001 COGNIQA_WEB_ORIGIN=http://localhost:3000 cogniqa-recorder listen

# Windows (PowerShell)
$env:COGNIQA_API_URL="http://localhost:3001"; $env:COGNIQA_WEB_ORIGIN="http://localhost:3000"; cogniqa-recorder listen
```

## 如何运作

```
┌─────────────────┐         ┌──────────────────────────┐         ┌─────────────────┐
│  CogniQA Web    │ ──────► │  @cogniqa-app/recorder   │ ──────► │  Chromium       │
│  (your browser) │  ticket │  (localhost :51820)      │  CDP    │  (your machine) │
└─────────────────┘         └──────────────────────────┘         └─────────────────┘
                                   │                                    │
                                   │  Playwright recorder API           │
                                   │  (clicks, fills, navigations)      │
                                   │                                    │
                                   ▼                                    ▼
                         ┌──────────────────────────┐         ┌─────────────────┐
                         │  Electron overlay window │         │  CogniQA API    │
                         │  (Run / Done / Delete)   │         │  (step stream)  │
                         └──────────────────────────┘         └─────────────────┘
```

1.  **车票握手** ——在CognitQA点击"Record"时,网络应用生成一单使用票并POST将其输入到本地收音机 `/start` 终点.
2.  **验证** ——录音机立即用CognitQA API赎回出票. 无效的,过期的,或者已经使用的票被拒.
3.  **浏览器启动** ——一个标题为Chrimium的窗口通过Playwright打开. 任何已有的前提条件步骤先重放,然后降落在正确的页面上.
4.  **记录** —— Playwright 的内部记录器引擎捕捉出每个可操作的事件.
5.  **实时同步** – 每一被捕获的台阶通过投票返回CogniqueQA网页标签 `/status`。 。 。 .
6.  **完成** ——单击 **完成** 在浮动电子工具栏(或关闭浏览器窗口)中结束会话.

## 警卫

-   **来源验证** ——每个收到的申请都与许可来源清单核对。 跨源请求在到达任何处理者之前都会被拒绝.
-   **一次性机票** ——记录会话只能由CognitQA后端所铸造的密码随机,单用票启动.
-   **本地绑定** —— HTTP 服务器只绑定到 `127.0.0.1`; 它从不接受您网络上其他设备的连接 .
-   **无持久性全权证书** ——记录器不存储API密钥,密码,或会话符号. 唯一能叫它赎票的网络.
-   **私人网络访问** - CORS信头包括: `Access-Control-Allow-Private-Network` 因此现代Chrome版本允许主机CognitQA应用程序到达您的本地主机记录器.

## 系统要求

| 监督办 | 状态 | 页:1 |
| --- | --- | --- |
| 视窗 10/11 | 获支持 | 电源壳或命令提示 |
| 马可斯12+ | 获支持 | 英特尔和苹果硅 |
| Linux (Ubuntu 20.04+, Fedora, Debian) (英语) | 获支持 | X11 或 Wayland 有显示服务器 |

> 由于记录器发射一个 **标题** 浏览器窗口 。 它不会在无头的SSH会话中工作,没有X11转发.

## 解决问题

### 登录时无法自动开始注册

企业管理的机器可以屏蔽登录项目注册. 这是非致命的警告,快跑 `cogniqa-recorder listen` 重开后再次出现.

### "51820港已经投入使用"

记录器自动尝试端口 `51820` 结束 `51825`如果全部取下,请设置不同的基端口:

```bash
COGNIQA_RECORDER_PORT=51900 cogniqa-recorder listen
```

### 浏览器不打开

如果 Electron 窗口无法启动(例如 Electron 二进制没有下载,因为安装运行与 `--ignore-scripts` 或位于代理机后,记录器会倒回一个独立的铬窗口. 倒计时需要Playwright的铬:

```bash
npx playwright install chromium
```

### 键盘无效、已过期或已使用

车票采用单用并有时间限制. 刷新 CignQA 页面并单击 **记录** 再次获得一张新票.

### 来源错配错误

如果你是自作自受 Cognica , 请看 [自办/开发设置](https://npmcn.com/package/%40cogniqa-app/recorder/#readme-self-hosted--development-setups) 上方将记录器指向您的本地网络来源.

## 许可证

无效——见 [软件包.json](https://github.com/flabdev/CogniQA/blob/main/apps/recorder-cli/package.json) 详细情况.

* * *

**仓库 :** [github.com/flabdev/认知QA](https://github.com/flabdev/CogniQA)  
**问题:** [github.com/flabdev/认知QA/问题](https://github.com/flabdev/CogniQA/issues)  
**主页 :** [github.com/flabdev/CognitQA/tree/main/apps/recorder-cli#readme 页面存档备份,存于互联网档案馆](https://github.com/flabdev/CogniQA/tree/main/apps/recorder-cli#readme)

## 常见问题

### @cogniqa-app/recorder 是什么？

CognitQA的本地记录器——在您自己的机器上发射一个真实的浏览器,这样"记录"就可以将您的点击作为测试步骤来捕捉,而不会有一个浏览器在CognitQA的服务器上运行\.

### 如何安装 @cogniqa-app/recorder？

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

### @cogniqa-app/recorder 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cogniqa-app\_\_recorder 是否存在。

### @cogniqa-app/recorder 支持 ESM 还是 CommonJS？

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

### @cogniqa-app/recorder 需要什么版本的 Node\.js？

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

### @cogniqa-app/recorder 可以商用吗？

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

### @cogniqa-app/recorder 的下载量有多少？

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

### @cogniqa-app/recorder 还在维护吗？

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