# @debuffjp/cli 中文文档

规范地址：https://npmcn.com/package/%40debuffjp/cli/

版本：0\.33\.0
npm 元数据更新时间：2026-11-11T02:35:25.286Z
中文译文更新时间：2026-11-11T18:52:36.189Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40debuffjp/cli
原文对照：https://npmcn.com/package/%40debuffjp/cli/?lang=original
项目主页：https://debuff.jp/
源码仓库：https://github.com/debuffjp/debuff

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

- 包体积（解压后）：716 kB，154 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：6 个
- 首次发布：2026-10-16T09:03:39.693Z
- 最新版本发布：2026-11-11T02:35:24.923Z
- 近 30 天下载量：10167（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：56（近 12 个月 56 个）

## 中文简介

解禁 CLI : dev 服务器, 以大小报告、 资产、 逻辑测试、 假想和模糊构建

## 安装

```sh
npm install @debuffjp/cli
```

也可以使用：`pnpm add @debuffjp/cli`、`yarn add @debuffjp/cli`、`bun add @debuffjp/cli`

## README

# @ debuffjp/ cli (英语)

这个 `debuff` 命令:dev 服务器,生产构建与大小报告,资产清单,浏览器情景,模糊播放测试和项目检查. 建于维特.

```bash
npm install -D @debuffjp/cli
npx debuff --help
```

| 命令 | 它会做什么 |
| --- | --- |
| `debuff create [dir]` | 脚手架游戏( 和 `npm create debuff`(中文(简体) ) |
| `debuff dev [--port] [--host]` | 带有热重装的 Dev 服务器; 重新生成更改时显示的资产 |
| `debuff build [--sourcemap]` | 生产结构,然后是原始/gzip/brotli报告。 如果只执行代码泄露失败 |
| `debuff report` | 已存在的大小报告 `dist/` |
| `debuff assets` | 运行资产管道:列出每项资产、其进口商和规模,并加上未使用和生成的文件 |
| `debuff test [files] [-t text] [--changed] [--queue name] [--accept-saves] [--json]` | 运行逻辑测试( R)`tests/**/*.test.ts`与 [庆子](https://github.com/debuffjp/debuff/tree/main/tooling/keiko):以节点为正版游戏,无浏览器,以毫秒计. 从0.32,每次运行记录 每次测试使用,和 `--changed` 仅运行自上次通过以来代码或文件发生变化的测试,加上新的和失败的测试; `--queue push` 为预推钩或CI保留单独记录([如何决定](https://github.com/debuffjp/debuff/tree/main/tooling/keiko#only-what-changed---changed)。从0.29.3开始,它还比较了节省的 `src/` 与 `saves.json` 并打印所改变的东西,与 `debuff build`,以及 `--accept-saves` 更新 `saves.json`它只报告: `debuff build` 保存错误时仍然失败 。 仅在0.29.3之前 `debuff build` 检查保存,以及 `debuff test --accept-saves` 以“ 未知选项” 失败 |
| `debuff scenario [files] [--update] [--strict]` | 运行 `scenarios/*.json` 在无头的克罗姆/埃奇 |
| `debuff fuzz [--seconds] [--runs] [--seed] [--keys] [--ignore]` | 用随机但可信的输入来玩无头游戏 。 报告解释了错误、被卡住的状态和循环(场景,或两个状态字段,在同一两个值之间翻转),每个都作为情景保存于 `.debuff/fuzz/` 复制它. `--keys` 使用关键代码, `PointerRight` 编号 : `PointerMiddle`和手势 `Wheel` (卷轴)和 `Touch` (指拍或拖动),例如. `--keys Touch,Wheel,Space` 为触摸游戏. `--ignore state.shots` 跳过吵闹的田地。 错误时退出 1 |
| `debuff telemetry [on|off|status]` | 匿名建筑注册:成功建造后, `debuff build` 发送一个随机的项目ID,包名和去发版本去去发.jp,这样我们就可以找到用去发的游戏. 关闭在CI,或与 `debuff telemetry off` 编号 : `DEBUFF_TELEMETRY=0`。 。 。 . [寄来的是什么](https://debuff.jp/docs/telemetry) |
| `debuff papercut <title> [--minutes] [--repo] [--area] [--kind] [--workaround] [--hit <id>] [--force]` | 将工具摩擦(慢或片状工具、缺失的API、混乱的docs)报告给公共板 [剪纸.debuff.jp](https://papercuts.debuff.jp/)。它列出相近匹配,而不是重复提交:重运行 `--hit <id>` 将你的分钟加到1,或 `--force`与 `--hit`,标题或 `--body` 说明和 `--workaround` 当纸张剪接没有时(从0.24.1;0.24.0掉出),则填补纸剪接的工作。 只发送您输入的 `debuff-cli <version>`。 。 。 . `DEBUFF_PAPERCUTS_TOKEN` 使新条目同时显示;没有它,他们等待审查。 增加为0.24 |
| `debuff papercuts [on|off|status]` | 自动剪纸: CLI 和 MCP 服务器向 papercuts.debuff.jp 报告在一周内两次看到的设置失败,或者一个比它要慢得多的命令. 他们发送一个固定的标题,一个错误代码,分钟和版本,从来没有消息,路径或项目细节. 从0.26.2中,还有OS,CPU计数,内存,节点版本和被检查的内容(缺少哪个浏览器). 每个指纹最多每天一次;在CI或随同 `DEBUFF_PAPERCUTS=0`。 。 。 . [寄来的是什么](https://debuff.jp/docs/telemetry#papercuts)。添加到0.24中 |
| `debuff inspect` | JSON 项目摘要 |
| `debuff upgrade [--to] [--dry-run]` | 将每个解禁软件包移动到最近发布的版本(或) `--to <version>`在一起,保持每个范围 `^`, (中文(简体) ), `~` 或精确样式,安装项目软件包管理器,然后运行新版本的 `doctor --fix`,也可以重写代理技能。 从来没有降级没有 `--to`如果运行较早的更新软件包.json,但其安装失败或被中断,则再次安装和运行医生(在0.31.1之前,它说“已经”并停止); `--json` 将软件包列表为 `stale`) (中文(简体) ). 增加为0.21 |
| `debuff doctor [--live] [--fix]` | 请检查access-date=中的日期值 (帮助) 节点版本,去发包版本, `node_modules`, (中文(简体) ), `debuff.config.ts`资产, `saves.json`,代理文件和浏览器方案使用。 每一个问题都有问题. `--fix` 应用安全装置(安装、去dupe、添加) `@debuffjp/dev`,写入缺失 `.mcp.json`,重写已安装版本的代理技能,并从0.23中将缺失的代理钩文件写入)在项目包管理器中,然后再次检查. `--live` 也启动dev服务器并检查游戏会暴露出它的dev钩. 从0.21开始,它也说当一个更新的去除。 当需要的检查失败时( 0. 0: 2 之前) 退出 2 。 在此设置点上失败的其他命令 |

添加 `--json` 用于机器可读输出和 `--root <dir>` 瞄准另一个项目.

从0.29.1起,大小报告使用Brotli质量11作为代码和HTML,质量4作为资产,源地图和其他文件. 这样可以避免花几分钟时间重新压缩大资产来报告其规模. 在0.29.1之前,每个文件都使用了质量11. 这适用于 `debuff build`, (中文(简体) ), `debuff report`, (中文(简体) ), `debuff inspect`,则MCP构建工具 `buildReport()`. Raw 和 gzip 测量数据保持其先前的设置. 报告在没有写入压缩文件的情况下测量压缩大小;您的主机选择如何压缩下载.

每天一次,在命令结束时,当更新的去除器被取出时,CLI会打印出一行在stderr上(从0.21). 从0.24, `debuff dev` 把它印到它的旗下,因为它从不离开。 提示从未被打印 `--json` 模式,它关闭在 CI 中 `DEBUFF_UPDATE_CHECK=0`. 代理在会话开始时(下方)从代理钩获得同样的消息.

## 退出代码和出错

从0.20. 在此之前,每一次失败都退出了 1, `doctor` 当所需的检查失败时退出 1, 未知的选项被忽略, 并且 `--json` 错误被打印为文本.

退出代码表示下一步要做什么,所以脚本和代理可以不读出输出就行动:

| 退出 | 含义 | 怎么办 |
| --- | --- | --- |
| 0 个 | 成绩 | 继续 |
| 1个 | 运行报告失败(测试、情景、模糊的发现或漏出),或出乎意料地破裂 | 读取报表或错误 |
| 2个 | 项目或机器需要先修复( 没有浏览器, 无效配置, 缺少 Dev 钩子, 繁忙的端口, 失败) `doctor`(中文(简体) ) | 运行 `npx debuff doctor` 并实行其修正。 重试没用的 |
| 3个 | 错误输入: 未知的命令或选项, 或文件夹没有 | 修改命令行 |

与 `--json` (并且总是为 `inspect`), stdout 中只包含一个JSON文档:结果,或者当命令不能运行时:

```json
{ "error": { "code": "browser_not_found", "message": "…", "fix": "Install Chrome or Edge, or set DEBUFF_BROWSER…", "transient": false } }
```

`code` 这是其中之一 `unknown_command`, (中文(简体) ), `bad_option`, (中文(简体) ), `not_a_project`, (中文(简体) ), `nothing_to_run` (从0.21起:没有设想方案,或没有报告基础), `config_invalid`, (中文(简体) ), `browser_not_found`, (中文(简体) ), `dev_hooks_missing`, (中文(简体) ), `game_hung` (从0.28起:一个打入游戏 超过60 s), `port_in_use`, (中文(简体) ), `network` 财务报告和审定财务报表 `unexpected`,并保持其含义介于释放之间. `transient: true` 表示同一命令如果再次运行可能有效(一个网络 blip). 日志转到 stderr 。 MCP 服务器的工具添加相同 `code` 财务报告和审定财务报表 `fix` 他们的错误.

## 代理钩

从0.23. 新项目船 `.claude/hooks/debuff.mjs`输入Claude代码 `.claude/settings.json` 输入编码 `.codex/hooks.json`。围绕每个编辑和 shell 命令,它:

-   在截取基线或节省变化之前询问人类;
-   拒绝编辑 `.debuff/`, (中文(简体) ), `dist/` 财务报告和审定财务报表 `node_modules/`,一个前景dev服务器,并手动更改 `@debuffjp/*` 各种版本;
-   警告新建 `Math.random`, (中文(简体) ), `Date.now` 和实时线路 `src/`· ;
-   每站一次,请求 `debuff test` 何时 `src/` 自上次运行以来有所改变;
-   从0.24起,在会话开始,最多每天一次, 告诉代理 当一个更新的去除 `npx debuff upgrade`。 。 。 .

闪电进口 `@debuffjp/cli/hook`,所以规则来自于安装的CLI. 以前什么也没有做 `npm install`,以及 `DEBUFF_HOOK=0` 关掉. `// debuff-hook-ignore <rule>` 在一行末尾跳过该行。 规则和细节: [与大赦国际工作人员合作](https://debuff.jp/docs/agents#hook)。 。 。 .

## 假设

```json
{
  "$schema": "../node_modules/@debuffjp/cli/schema/scenario.schema.json",
  "steps": [
    { "press": "ArrowRight" },
    { "wait": 30 },
    { "expect": { "state.player.x": { "gt": 200 } } },
    { "set": { "player.speed": 400 } },
    { "capture": "after-move" }
  ]
}
```

时间只能通过 `wait` 财务报告和审定财务报表 `until` 步骤,所以跑是决定性的。 每个步骤都会在真实的浏览器中使出,所以等得很慢(一分钟的游戏时间可以花上几分钟):检查计时器和其他有逻辑测试的长的计时器,并保持场景短. `until` 一步一滴,直到其条件维持, 如果它们不成功则失败 `within` 许多步骤(默认600),所以一种情景说"直到玩家降落"而不是猜测等待. 路径读取了dev状态 : `scene`, (中文(简体) ), `tick`, (中文(简体) ), `state.*` (你的电话) `inspect()`),以及 `events.<name>`,游戏名称的次数 `game.emit("<name>")` (至一为一. 举个例子 `{ "until": { "events.coin": { "gte": 1 } }, "within": 60 }`重放自 Dev 面板( 或 MCP) `game_replay` 工具)也是假设。 从0.31起,他们持有 `checkpoint` 步骤每60分一分,是游戏状态中每个部分的散列;当一个部分停止匹配时,报告会警告一次与勾和不同的部分(`state.player`, (中文(简体) ), `events`)),而情节依然过去. \* 无障碍检查

情景可以筛选游戏实际绘制的内容:

-   `{ "flashes": 240 }` 播放240个步骤,但闪烁时失败,可能引发对光敏感的缉获:超过3个闪烁每秒超过1/4分10度。 它与WCAG 2.3.1的一般闪光阈值相近,将10°场分别取为屏幕的三分之一.
-   `{ "contrast": [x, y, w, h], "min": 4.5 }` 如果一个区域的光和暗部分(例如,你的HUD文本)对比小于 `min` (默认4.5:1,文本为WCAG AA).
-   `"stepTimeout": 120` 在一个场景的顶端 改变一个步骤可能要花多少秒 游戏才算挂起。 默认60 从0.28.
-   `"reducedMotion": true` 在一个情景的顶端运行,浏览器要求减少运动,所以也可以检查这个模式.

这些是一跑的检查,不是认证:通行证意味着在您所玩的步子中明显没有不安全的事情发生. 红色闪光尚未检查.

将捕获量与每个平台的基线相比较 `scenarios/__baselines__/`。除非您通过 `--strict`设置 `DEBUFF_BROWSER` 使用特定的铬结构.

## 程序使用

```ts
import { buildReport, compileAssets, runScenarios } from "@debuffjp/cli";
```

## 资产和插件

将源资产输入 `assets/`. 管道制作一个模拟清单(`/assets/manifest.json`) (中文(简体) ). 只有文件显示的参考文献以编程方式提供,并在构建中发布,源则从未被修改 .

管道警告说PNG的宽度或高过4096像素,因为纹理限制较小的GPU画出黑色. 将长的图案条分割成多个工作表 。 0.29.3以前,没有警告.

在其中添加工具插件 `debuff.config.ts`数字 :

```ts
import { defineConfig } from "@debuffjp/cli";

export default defineConfig({
  plugins: [
    {
      name: "maps",
      apiVersion: 1,
      // Any language: SourceFile JSON on stdin, ImportResult JSON on stdout.
      assets: [{ name: "maps", extensions: [".map"], command: ["python", "tools/import_map.py"] }],
    },
  ],
});
```

### 书写

第一党党员 `aseprite()` 插件为您运行 Aeprite, 所以 `.aseprite` 财务报告和审定财务报表 `.ase` 文件在 `assets/` 装入像 PNG 没有导出步骤 :

```ts
import { aseprite, defineConfig } from "@debuffjp/cli";

export default defineConfig({ plugins: [aseprite()] });
```

-   `hero.aseprite` 多个框架成为图示工作表 : `assets.frames("hero")` 返回框架顺序.
-   `font@6x9.aseprite` 平移到一个图像,并带有6x9网格,准备 `BitmapFont`。 。 。 .
-   隐藏层被忽略,所以引导层留在源中.

它寻找Aeprite在 `$ASEPRITE`然后打开 `PATH`,然后在平时安装文件夹(包括Steam). 也可以通过 `aseprite({ binary })`。如果它找不到 Aseprite, 建筑警告和跳过这些文件。 结果通过文件内容来缓存,因此Aseprite只在文件更改时运行.

`aseprite/new-font.lua` 创建空白字体工作表, 并设置网格 :

```bash
aseprite -b --script-param w=6 --script-param h=9 --script-param out=assets/font@6x9.aseprite --script node_modules/@debuffjp/cli/aseprite/new-font.lua
```

### 10个

[10个](https://github.com/debuffjp/tenten) 是一个无头像素艺术工具,用于编码代理: MCP 服务器绘制图示和动画,并将其保存为 `.tt`,一个 JSON 文件,以像素作为文本网格,在 git 中显示. `.tt` 文件在 `assets/` 成为没有配置的 PNG 和图示工作表, 相同的方式 `aseprite()` 对 `.aseprite`添加 `tenten()` 仅用于更改 tenten 运行方式的插件 :

```ts
import { defineConfig, tenten } from "@debuffjp/cli";

export default defineConfig({ plugins: [tenten({ command: ["node", "../tenten/bin/tenten.js"] })] });
```

-   `slime.tt` 多个框架成为图示工作表 : `assets.frames("slime")` 返回框架顺序.
-   `font@6x9.tt` 平地为一幅有6x9网格的图像.

脱布克运行 10 个从 `$TENTEN` (数量) `bin/tenten.js`),然后将复制件安装在工程中,否则用 `npx -y -p @debuffjp/tenten tenten` 第一次的时候a `.tt` 文件可见。 十十个需要节点24。 结果被文件内容缓存.

## 常见问题

### @debuffjp/cli 是什么？

解禁 CLI : dev 服务器, 以大小报告、 资产、 逻辑测试、 假想和模糊构建

### 如何安装 @debuffjp/cli？

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

### @debuffjp/cli 支持 TypeScript 吗？

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

### @debuffjp/cli 支持 ESM 还是 CommonJS？

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

### @debuffjp/cli 需要什么版本的 Node\.js？

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

### @debuffjp/cli 可以商用吗？

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

### @debuffjp/cli 的下载量有多少？

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

### @debuffjp/cli 还在维护吗？

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