# @app-studio/qa-doctor 中文文档

规范地址：https://npmcn.com/package/%40app-studio/qa-doctor/

版本：0\.11\.6
npm 元数据更新时间：2026-11-05T23:12:08.122Z
中文译文更新时间：2026-11-08T06:22:12.799Z
软件包许可：UNLICENSED

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

原始 npm 页面：https://www.npmjs.com/package/%40app-studio/qa-doctor
原文对照：https://npmcn.com/package/%40app-studio/qa-doctor/?lang=original

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

- 包体积（解压后）：108 kB，50 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：3 个
- peer 依赖：vitest \>=1\.6
- 首次发布：2026-08-09T15:45:49.865Z
- 最新版本发布：2026-11-05T23:12:07.838Z
- 近 30 天下载量：1879（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：33（近 12 个月 33 个）

## 中文简介

证明一个寄存器的 qa. bindings.json 描述它所在的寄存器——作为CLI报告,作为vitest套件 CI不能跳过.

## 安装

```sh
npm install @app-studio/qa-doctor
```

也可以使用：`pnpm add @app-studio/qa-doctor`、`yarn add @app-studio/qa-doctor`、`bun add @app-studio/qa-doctor`

## README

# @app-studio/qa-医生

证明一个仓库 `qa.bindings.json` 描述它的寄存器 实际进入.

## 为什么会这样

一个成熟的QA设置被从一个存储器复制到另一个没有它的 装订正在重写。 在新的寄存器中,守护钩的图案 没有匹配文件, 因此它否认了任何内容, 并且看起来就像一个警卫 没什么好抱怨的 记录的端口是错误的,所以每个指令 在他们身上建起的,曾派人到一个不在那里的门去。 种子账户有 不存在, 因此与他们签约的特工 报告了认证错误 。 还有 文档 _曾经_ 准确的提示没有输入点,所以没有人 读取.

没有任何一项失败。 这一切都是可憎的。 这个包裹就是 观察变成了检查.

## 运行它的两个方式,一个执行

**根据要求:**

```bash
pnpm exec qa doctor            # human report
pnpm exec qa doctor --json     # for agents and CI
pnpm exec qa doctor --strict   # warnings become errors
```

**在仓库自己的套房里**,这就是它不可滑动的原因:

```ts
// tests/qa-doctor.test.ts
import { doctorSuite } from '@app-studio/qa-doctor/vitest';

doctorSuite();
```

一个 `it()` 根据规则. `qa doctor` 当有人运行时会发现错误的束缚; 这在每一次CI跑道上都能发现, 在已经合并的套房里 跳过检查意味着跳出 套房,这是一个决定 有人必须 大声点 A 类 `self/*` 规则验证此文件存在 _财务报告和审定财务报表_ 坠入其中 模糊测试命令选择, 因为测试没有运行比没有更糟糕 测试: 仓库看起来已选中 .

## 它检查什么

| 组 | 证明 |
| --- | --- |
| `bindings/repo-name-matches` | `repo.name` 等于 `package.json`'"名称——被复制的文件探测器,在其它东西可能被误导之前运行. |
| `commands/scripts-resolve` | 每个已声明的命令名称一个真实的脚本或已安装的二进制,它所读取的文件都存在. |
| `commands/layers-reference-commands` | 层指向登记册所定义的命令,层密钥是独一无二的. |
| `commands/gates-reference-commands` | 大门矩阵要求得到这个存储器能够产生的证据. |
| `commands/one-package-manager` | 没有东西告诉任何人运行 npm 在 pnpm 仓库. |
| `commands/smoke` _(仅国产总值)_ | 廉价的命令——打字检查,出字,格式检查——实际上运行. |
| `paths/exist` | 每一个已宣布的路径都在那里,除非列在下面 `deliberatelyAbsent`。 。 。 . |
| `paths/guard-globs-live` | **每个非空的守护模式都匹配至少一个真实文件.** 惰性护卫探测器. |
| `paths/generated-exist` | 所宣布的树木真的在那里. |
| `ports/bound-by-agrees` | 每个端口都是它实际使用的绑定文件的编号,没有两个表面要求一个端口. |
| `env/required-declared` | 需要的变量将被记录在新来者找到的地方 . |
| `env/secrets-not-committed` | 没有承诺文件包含可变标记密钥的真实值 . |
| `seed/accounts-in-source` | 每个承诺的账户都出现在种子来源中. |
| `hooks/registered` | 每个被启用的钩子在正确的事件下被接通,有一个匹配器来覆盖它必须完成的任务. |
| `hooks/wrappers-resolve` | 包装符存在,可执行,并指向安装的逻辑. |
| `hooks/deny-protects-generated` | 所出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出来出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出来来来来来来出出出出出出出出出出出出出来来来来来出出出出出出出出出出出出出出出出出出出出出出出出出出出出出来来来来来来来来来,不可是手. |
| `self/doctor-test-wired`, (中文(简体) ), `self/hooks-test-wired` | 检查在仓库的套房里进行. |
| `docs/entrypoints-point-at-qa` | 一个特工在抵达时读到的文件 上面写着QA是怎么工作的. |

规则ID是稳定的: 由它们组成的CLI组, 测试它们,和主机 给他们准备点药.

## 报告

每个发现都包含三件事 而不是一个

```
✖ ports/bound-by-agrees — each declared port is the number the file that binds it actually uses
   ports.front says 5173, but playwright.config.ts never mentions that number.
   in: playwright.config.ts
   what this means: Every instruction built on this port sends people to a door
     that is not there, and the resulting connection refused reads as a broken
     application rather than a wrong binding.
   fix: Open playwright.config.ts, read the port it binds, and put that number
     in ports.front.
```

一个医生在一周内 就会被忽略了 被忽略的医生与没有医生是分不开的.

## 写你自己的规则

```ts
import { runRules, createDoctorContext } from '@app-studio/qa-doctor';
import type { Rule } from '@app-studio/qa-core';

const noOrphanedFeatures: Rule = {
  id: 'features/registered',
  describes: 'every feature directory is in the composed registry',
  appliesTo: (context) => context.exists('src/features'),
  check(context) {
    const declared = context.read('src/generated/registry.ts') ?? '';
    return context
      .glob('src/features/*/manifest.json')
      .filter((path) => !declared.includes(path.split('/')[2]!))
      .map((path) => ({
        level: 'error' as const,
        rule: 'features/registered',
        message: `${path} is not in the composed registry.`,
        means: 'The feature exists on disk and is not part of the application, which is invisible until someone looks for it.',
        fix: 'Run the composer, or delete the directory.',
      }));
  },
};
```

规则是纯粹的功能 `DoctorContext`因此,他们测试 固定 而不是违背你的真爱 这比平常更重要 这里,因为一个医生 没有人看过去红色 正是惰性机械 此软件包的存在是为了防止.

## 所需资源

节点.js20或更新. `vitest` 是一个可选的对等点, 仅用于 `/vitest` 进入点.

## 常见问题

### @app-studio/qa-doctor 是什么？

证明一个寄存器的 qa\. bindings\.json 描述它所在的寄存器——作为CLI报告,作为vitest套件 CI不能跳过\.

### 如何安装 @app-studio/qa-doctor？

在项目目录运行 npm install @app-studio/qa-doctor，或使用 pnpm add / yarn add / bun add。

### @app-studio/qa-doctor 支持 TypeScript 吗？

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

### @app-studio/qa-doctor 支持 ESM 还是 CommonJS？

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

### @app-studio/qa-doctor 需要什么版本的 Node\.js？

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

### @app-studio/qa-doctor 可以商用吗？

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

### @app-studio/qa-doctor 的下载量有多少？

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

### @app-studio/qa-doctor 还在维护吗？

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