# @andrian\.yablonskyy/thub-common 中文文档

规范地址：https://npmcn.com/package/%40andrian.yablonskyy/thub-common/

版本：2\.2\.6
npm 元数据更新时间：2026-11-03T15:03:23.254Z
中文译文更新时间：2026-11-06T17:26:20.838Z
软件包许可：SEE LICENSE IN LICENSE\.md

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

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

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

- 包体积（解压后）：85.1 kB，18 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=24
- 运行依赖：2 个
- 首次发布：2026-09-22T11:33:45.080Z
- 最新版本发布：2026-11-03T15:03:23.088Z
- 近 30 天下载量：2590（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：55（近 12 个月 55 个）

## 中文简介

共享任务类别计划、状态语句和代理和客户端使用的瘦API客户端

## 安装

```sh
npm install @andrian.yablonskyy/thub-common
```

也可以使用：`pnpm add @andrian.yablonskyy/thub-common`、`yarn add @andrian.yablonskyy/thub-common`、`bun add @andrian.yablonskyy/thub-common`

## README

# @andrian

TestHub的共享代码——一个让CI/CD管道和个人开发者在私人实验室对真正的硬件或仿真器进行固件测试的自办工作网络. 这个软件包没有服务器,也没有自己的CLI;这是依赖光小的核心 [探员](https://github.com/andrianyablonskyy/thub-agent), (中文(简体) ), [协调员](https://github.com/users/andrianyablonskyy/packages/container/package/thub-coordinator) 财务报告和审定财务报表 [客户端](https://github.com/andrianyablonskyy/thub-client) 都取决于,所以三个说完全相同的协议.

## 安装

```bash
npm install @andrian.yablonskyy/thub-common
```

## 里面有什么东西

### 任务规格计划和验证

一个 [亚日弗](https://ajv.js.org/) JSON为代理员向协调员发出的职务说明设计了方案,并用薄薄的包装来验证一个规格并填补其缺省.

```js
const { validateJobSpec } = require('@andrian.yablonskyy/thub-common');

const { valid, spec, errors } = validateJobSpec({
  target: { type: 'hw', labels: ['board:nucleo-f401re'] },
  command: './ci/test.sh',
  downloads: [{ url: 'https://artifactory.example.com/app.bin' }],
  git: { url: 'https://github.com/yourorg/firmware-tests.git', ref: 'v1.4.0' }
});
```

工作是一项任务: `command` (需要)- shell 命令客户端作为其切入点运行, `args` 作为 `"$@"`),可选输入 `downloads` (单位:千美元)`[{ url }]`, (中文(简体) ), `git` (单位:千美元)`url`选项 `ref` 分支、标记或承诺——和 `depth`,默认 1),对于SW工作, `image` (作为 DUT 运行的多克图像). 其他顶级字段 : `target` (单位:千美元)`type`, (中文(简体) ), `labels`选项 `group`编号 :`client`, (中文(简体) ), `suite`, (中文(简体) ), `timeoutSec`, (中文(简体) ), `priority`, (中文(简体) ), `source` (单位:千美元)`ci`编号 :`cli`, (中文(简体) ), `user` (免费文本工作所有人标签), `meta` (任意密钥/价值元数据),以及 `dryRun`。旧形状的规格(`firmware`编号 :`tests`,来自比 `--command`) 拒绝发信息更新代理.

### 国徽和出关代码

```js
const { RESOURCE_STATES, JOB_STATES, ACTIVE_JOB_STATES, TERMINAL_JOB_STATES, BUSY_SOURCES, EXIT_CODES, exitCodeForJobState } = require('@andrian.yablonskyy/thub-common');
```

-   `RESOURCE_STATES`数字 : `REGISTERED`, (中文(简体) ), `IDLE`, (中文(简体) ), `BUSY`, (中文(简体) ), `OUT_OF_SERVICE`, (中文(简体) ), `MAINTENANCE`。 。 。 .
-   `JOB_STATES`数字 : `QUEUED`, (中文(简体) ), `ASSIGNED`, (中文(简体) ), `PREPARING`, (中文(简体) ), `RUNNING`, (中文(简体) ), `PASSED`, (中文(简体) ), `FAILED`, (中文(简体) ), `ERROR`, (中文(简体) ), `TIMEOUT`, (中文(简体) ), `CANCELED`, (中文(简体) ), `LOST`。 。 。 . `ACTIVE_JOB_STATES`编号 :`TERMINAL_JOB_STATES` 是那组东西的两个自然分界线.
-   `BUSY_SOURCES`数字 : `ci`, (中文(简体) ), `cli`, (中文(简体) ), `local` ——资源目前为何繁忙.
-   `EXIT_CODES` 编号 : `exitCodeForJobState(state)`: Agent CLI的流程退出代码(`PASSED` -0个, `FAILED` • 1, `ERROR`编号 :`TIMEOUT`编号 :`LOST` • 2, `CANCELED` ~ 3, 使用/ 自动出错 ~ 4, 与 Ctrl- C 相分离 ~ 130),所以一个 CI 步骤可以分支于 `$?` 不分析输出.

### API 客户端

起码 `fetch`\- 协调员的基于 HTTP 客户端 `/api/v1` 表面,带有一个手卷式的Server-Sent-Events 解析器(没有外部的SSE依赖性)——由代理和客户端使用,所以它们说话完全相同的协议.

```js
const { ApiClient } = require('@andrian.yablonskyy/thub-common');

// userAgent is optional; the Coordinator records "thub-agent/<v>" / "thub-client/<v>" versions for its dashboard
const client = new ApiClient({ baseUrl: 'https://thub.example.com', token: 'agt_...', userAgent: 'thub-agent/1.0.8' });
const job = await client.post('/jobs', spec);
await client.streamEvents(`/jobs/${job.jobId}/logs/stream`, {
  onEvent: ({ event, id, data }) => console.log(event, data)
});
```

`request()`编号 :`get()`编号 :`post()` 处理 JSON 天体、 查询字符串和非-2xx 错误( 以 `.status`编号 :`.body` 设置); `streamEvents()` 重新连接呼叫者需要驱动( 它只描述一个连接对事件的价值, 并在流结束时解决) 和荣誉 `Last-Event-ID` 倒计时.

### 保留资源远程频道

代理、协调员和客户为保留资源共享一个WebSocket频道协议。 除了UART、社署、RTT和视频频道之外,持有者可以要求一个名字 `service` 带有客户端端口的频道。 RTT在选定的ST-Link上打开一个OpenOCD会话,为SEGGER控制块搜索一个已配置的目标RAM范围,并流出一个上行通道. 客户端连接 a `service` 只有频道 `127.0.0.1:<port>` ; 它从来不让客户端的听众接触到网络.

### 版本检查和自更新助手

`PACKAGES` (协调员/代理人/客户姓名), `fetchLatestVersion(pkg, { registry })` (单位:千美元) `latest` 从npm登记簿中取出, `compareVersions`编号 :`isNewer`编号 :`isValidVersion` (限制) `X.Y.Z[-pre]`, (中文(简体) ), `npmBin()` (运行中节点旁边的npm)和 `npmInstallGlobal(pkg, version)` (仅针对三个TestHub包,仅限有效版本).

## 发展

```bash
npm install
npm test    # node --test test/*.test.js
npm run lint
```

## 许可证

见 [利比里亚](https://npmcn.com/package/%40andrian.yablonskyy/thub-common/LICENSE.md)。 。 。 .

## 常见问题

### @andrian\.yablonskyy/thub-common 是什么？

共享任务类别计划、状态语句和代理和客户端使用的瘦API客户端

### 如何安装 @andrian\.yablonskyy/thub-common？

在项目目录运行 npm install @andrian\.yablonskyy/thub-common，或使用 pnpm add / yarn add / bun add。

### @andrian\.yablonskyy/thub-common 支持 TypeScript 吗？

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

### @andrian\.yablonskyy/thub-common 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @andrian\.yablonskyy/thub-common 需要什么版本的 Node\.js？

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

### @andrian\.yablonskyy/thub-common 可以商用吗？

@andrian\.yablonskyy/thub-common 使用 SEE LICENSE IN LICENSE\.md 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @andrian\.yablonskyy/thub-common 的下载量有多少？

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

### @andrian\.yablonskyy/thub-common 还在维护吗？

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