# @botiverse/hands-electron 中文文档

规范地址：https://npmcn.com/package/%40botiverse/hands-electron/

版本：0\.2\.0
npm 元数据更新时间：2026-07-09T11:26:01.482Z
中文译文更新时间：2026-11-08T12:14:40.834Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40botiverse/hands-electron
原文对照：https://npmcn.com/package/%40botiverse/hands-electron/?lang=original

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

- 包体积（解压后）：19.5 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：electron \>=22
- 首次发布：2026-07-09T11:26:00.742Z
- 最新版本发布：2026-07-09T11:26:01.147Z
- 近 30 天下载量：19134（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 1 个）

## 中文简介

手相撞报告 Electron app – 主 + 渲染器, Crashpad 微型泵自动加载并象征性地服务器侧.

## 安装

```sh
npm install @botiverse/hands-electron
```

也可以使用：`pnpm add @botiverse/hands-electron`、`yarn add @botiverse/hands-electron`、`bun add @botiverse/hands-electron`

## README

# @ botiverse/ hands- electron

Electron apps 的崩溃报告,由 [双手](https://quiver.oranix.io/)。 。 。 .

电能内置 [崩溃](https://www.electronjs.org/docs/latest/api/crash-reporter) 抓取本地小型泵,用于 **主要进程和制造进程** 财务报告和审定财务报表 把它们直接上传到Hands, 存放在那里作为坠机票和 与您上传的 Breakpad 符号相对应的象征性服务器侧 。 这个SDK线 增加渲染器/程序崩溃的听器,并管理崩溃范围 (用户/标记 / 额外/面包屑) 在下一个垃圾堆上随行.

SDK有两个切入点 比如 `@sentry/electron`: 一个给 **主要** 进程和一个 **渲染器**。 。 。 .

## 安装

```bash
npm install @botiverse/hands-electron
```

`electron` 由您的应用程序提供.

## 主要进程

打电话 `init()` 在应用程序准备好之前:

```ts
import { app } from "electron";
import * as Hands from "@botiverse/hands-electron/main";

Hands.init({
  appSlug: "my-desktop-app",     // your Hands app slug
  clientKey: "qk_live_...",      // public client key (safe to ship)
  release: app.getVersion(),     // version_name (defaults to app.getVersion())
  versionCode: 1020300,          // Hands version_code → picks the symbol set
  environment: "stable",         // channel
  extra: { deployment: "ga" },   // static annotations on every crash
  onCrash: (info) => {
    // renderer / child-process termination (incl. oom / killed, which produce
    // no minidump) — log, show a dialog, etc.
    console.warn("process gone:", info.processType, info.reason);
  },
});

// Attach context that rides along on the next crash:
Hands.setUser({ id: "u_123", email: "a@b.com" });
Hands.setTag("feature", "editor");
Hands.setExtra("open_docs", 3);
Hands.addBreadcrumb({ message: "opened project", category: "ui" });
```

`init()` 并使用节奏发射/安装度量衡向Hands发送 随机存储在 Electron 下的每个安装设备 ID `userData`. 这种权力 活动数据和版本分配分析; 在线不真实 心跳声 使用 `Hands.reportDevice(options)` 如果需要强制测量 在正常的24h节节流阀之外.

## 渲染器进程

主进程 Crashpad 自动捕捉到 Render 相撞器 渲染器条目仅管理范围并转发到主要之上的 IPC :

```ts
import * as Hands from "@botiverse/hands-electron/renderer";

Hands.setTag("route", location.pathname);
Hands.addBreadcrumb({ message: "clicked export" });
```

用于沙盒成型器(`contextIsolation: true`,将API从你的 替换为预装入脚本 :

```ts
// preload.ts
import { exposeHands } from "@botiverse/hands-electron/preload";
exposeHands(); // → window.hands.setTag(...), window.hands.addBreadcrumb(...)
```

## 符号( 服务器侧符号)

迷你泵只有在Hands拥有您的应用程序的 Breakpad 时才会变成可读堆栈 符号 `version_code`在 CI 中,用 [`dump_syms`](https://github.com/mozilla/dump_syms) 并同时上传 释放 :

```bash
# produce .sym files for your app + Electron framework binaries
dump_syms path/to/MyApp > syms/MyApp.sym
# … repeat per binary, then zip them (flat is fine — Hands reads each
#    file's MODULE header to place it correctly) …
zip -r symbols.zip syms/

hands builds publish-electron my-desktop-app \
  --version-name 1.2.3 --version-code 1020300 \
  --installer dist/MyApp-1.2.3.exe \
  --symbols symbols.zip
```

一旦符号出现,每张坠机票就会有一个符号堆栈作为 一个评论。 没有符号, Hands 仍然用模块+相撞来记录崩溃 边框.

## 发送什么

每个小型泵都装有哨兵电动式的注释,设置了服务器折叠 输入入票: `product_type=electron`, (中文(简体) ), `version`, (中文(简体) ), `version_code`, (中文(简体) ), `environment`编号 :`channel`, (中文(简体) ), `platform`, (中文(简体) ), `arch`, (中文(简体) ), `process_type`, (中文(简体) ), `electron_version`, (中文(简体) ), `chrome_version`,加任意 `extra` 和当前 用户/tags/面包屑.

## 常见问题

### @botiverse/hands-electron 是什么？

手相撞报告 Electron app – 主 \+ 渲染器, Crashpad 微型泵自动加载并象征性地服务器侧\.

### 如何安装 @botiverse/hands-electron？

在项目目录运行 npm install @botiverse/hands-electron，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：electron（\>=22）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @botiverse/hands-electron 支持 TypeScript 吗？

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

### @botiverse/hands-electron 支持 ESM 还是 CommonJS？

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

### @botiverse/hands-electron 可以商用吗？

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

### @botiverse/hands-electron 的下载量有多少？

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

### @botiverse/hands-electron 还在维护吗？

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