# @genie-react/cli 中文文档

规范地址：https://npmcn.com/package/%40genie-react/cli/

版本：1\.0\.2
npm 元数据更新时间：2026-11-16T01:34:03.870Z
中文译文更新时间：2026-11-16T03:29:25.514Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40genie-react/cli
原文对照：https://npmcn.com/package/%40genie-react/cli/?lang=original
项目主页：https://github.com/Genie-sa/genie-react#readme
源码仓库：https://github.com/Genie-sa/genie-react

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

- 包体积（解压后）：1.3 MB，24 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-07-01T19:43:44.061Z
- 最新版本发布：2026-11-16T01:34:03.526Z
- 近 30 天下载量：7460（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：35（近 12 个月 35 个）

## 中文简介

从终端给AI编码代理直播React和TanStack DevTools. 检查,优化,测试,验证一个运行的应用程序.

## 安装

```sh
npm install @genie-react/cli
```

也可以使用：`pnpm add @genie-react/cli`、`yarn add @genie-react/cli`、`bun add @genie-react/cli`

## README

# 精灵CLI

为运行的 React app 提供您的编码代理 DevTools .

CLI让代理机从终端检查,优化,测试,验证应用程序.

## 开始

```bash
pnpm add -D genie-react
npx @genie-react/cli init
pnpm dev
npx @genie-react/cli status --sessions-only
```

如果打开一个以上的标签,请用 `agent-browser --session my-agent open <url>` (或添加) `?_genie=my-agent` 到另一个浏览器中的 URL)。 那就通过 `--session my-agent` 给每个命令.

其别名可存活于导航,再装入,再接再通. 从工作空间根中, CLI 选择一个活的应用或者在几个活的时用一个明确的列表来停止.

## 查找已浪费的

```bash
npx @genie-react/cli call react_clear_renders '{}'
# Drive one flow in the app.
npx @genie-react/cli call react_get_renders '{"sort":"selfTime","limit":3}'
npx @genie-react/cli call react_render_causes '{"component":"Button","limit":3}'
```

只在观测覆盖完成和 `budgetExhaustedCommits` 为零。 这个 默认的适应性预算会增加, 以适应您清除时挂起的树 。 当一个极限仍然跳过工作, `coverage.budgetAdvice` 提出预算:明确预算并重复这一步骤, 因为后期的成长无法恢复 被承诺所忽略的证据.

真实的摘录 `react_render_causes` 从 Vite 演示输出 :

```text
events[5] (componentName #componentId {fields}, then ← kind evidence name {fields} per cause):
  each: {mountId:mount:9,source:{location:App.tsx:234:6,ownership:app}}
  TaskPanel #57 {renderEventId:render:13:184,documentCommitId:13,inputEvidence:changed}
    ← query exact "[\"tasks\"]" {reason:query-notification-delivered,changedResultFields:[data,dataUpdatedAt]}
    ← external-store inferred tanstack-mutation-observer
  TaskPanel #57 {renderEventId:render:10:149,documentCommitId:10,inputEvidence:none-observed}
    ← parent inferred App
coverage:
  complete: true
  inputAttributionComplete: true
  semantics: exact
```

代理人获得组件,来源位置,以及每个原因及其证据等级: `exact`, (中文(简体) ), `inferred`,或 `unknown`。原因包括道具、状态、上下文、查询、路由器、父母制作和挂载.

## 审计影响

```bash
npx @genie-react/cli call react_effect_audit '{"appOnly":true,"onlyHot":true}'
```

每项影响都报告其来源以及所有权证据是否 `exact`, (中文(简体) ), `inferred`,或 `unknown`。热量使用最小样本数和95%的间隔,因此标记了短跑 `insufficient-data`。 。 。 .

## 检查活钩

```bash
npx @genie-react/cli call react_find_components '{"query":"App","exact":true}'
# Use the id returned above. The Vite demo returned TaskPanel #57.
npx @genie-react/cli call react_inspect_component '{"id":57}'
```

Vite演示节选 :

```text
id: 57
name: TaskPanel
kind: function
props: {}
hooks[29]:
  - {index:0,kind:state,stateful:true,stateIndex:0,value:admin}
  - {index:1,kind:state,stateful:true,stateIndex:1,value:""}
  - {index:6,kind:effect,stateful:false,customHooks:[useQuery,useBaseQuery],deps:["ƒ anonymous()"]}
```

代理器可以读取挂载组件的真正道具,状态,和钩子,而不是从源头来猜测.

## 测试 TanStack 状态

```bash
npx @genie-react/cli call query_simulate_state \
  '{"queryKey":["demo","greeting"],"state":"pending"}'
```

```text
ok: true
queryHash: "[\"demo\",\"greeting\"]"
simulatedState: pending
originalStatus: success
```

该代理可以驱动和验证真实的加载UI,然后恢复准确的查询状态:

```bash
npx @genie-react/cli call query_restore_state '{"queryKey":["demo","greeting"]}'
```

```text
ok: true
restored: 1
```

## 代理输出

每个命令默认打印压缩文本 。 它保留了结果的每个领域,引用了应用字符串,所以它们不能假造一行,并且比JSON的代号成本更低:大约72%的代号贯穿了记录结果,42-60 %的元件树. 添加 `--json` jSON 文档 :

```bash
npx @genie-react/cli call react_inspect_component '{"id":57}' --json
```

使用 `--fields` 当代理只需要几个字段时:

```bash
npx @genie-react/cli call query_list '{}' --fields queryHash,status,fetchStatus
```

```text
[1]:
  - {queryHash:"[\"demo\",\"greeting\"]",status:success,fetchStatus:idle}
```

每个工具都包含其输入方案和一个可运行的例子:

```bash
npx @genie-react/cli tools
npx @genie-react/cli tools react_inspect_component
```

失败始于 `error <reason>: <message>`,则 `next: $ <command>` 当恢复命令被知道时. `--json` 打印一个紧凑的 JSON 值,但字段相同. `batch` a 下每个结果显示一个块 `[n/total] tool ok|error` 页眉; `batch --json` 打印一个 JSON 阵列和 `batch --ndjson` 指纹 JSONL.

分析输出的脚本添加 `--json`,或设置 `GENIE_OUTPUT=json` 曾经保留了0.19输出,JSONL包含. CLI 所属状态、批量和出错对象包括 `schemaVersion` 在JSON。 (英语) 成功调用保持输出图示 `tools <tool>`编辑 [产出合同](https://github.com/Genie-sa/genie-react/blob/main/docs/json-cli.md) 指定文本格式.

使用 `--verbose` 当启动不明确时。 它会打印出CLI版本,桥接目标,会话,以及时间预算到 stderr. `--connect-timeout <ms>` 只限桥接.

等待精确的查询键而不是睡觉:

```bash
npx @genie-react/cli call devtools_wait \
  '{"condition":"query-settled","queryKey":["demo","greeting"]}'
```

对于一个大的组件树,呼叫 `react_find_components`,然后以 `rootId` 改为 `react_get_tree`。 。 。 .

## 比较重复运行

清除渲染数据, 驱动一个精确的流, 并创建一个命名的捕获 :

```bash
npx @genie-react/cli call react_clear_renders '{}'
# Drive the flow.
npx @genie-react/cli call devtools_capture_create '{"name":"before-1"}' --json
```

丢弃反应覆盖不完整或预算已耗尽而不是比较a的捕获 下行观察.

变更前后运行同流至少3次. 然后比较返回的ID:

```bash
npx @genie-react/cli call devtools_capture_compare \
  '{"baselineCaptureIds":["<before-1>","<before-2>","<before-3>"],"candidateCaptureIds":["<after-1>","<after-2>","<after-3>"],"metrics":["react.renders"],"budgets":[{"metric":"react.renders","maxRegressionPct":0}]}'
```

判决是 `pass`, (中文(简体) ), `fail`,或 `insufficient-data`它还报告样本数、中位数、p95和分布。 中枢保存了最新的20个俘获.

见 [完整的设置和工具列表](https://github.com/Genie-sa/genie-react#readme)。 。 。 .

## 常见问题

### @genie-react/cli 是什么？

从终端给AI编码代理直播React和TanStack DevTools\. 检查,优化,测试,验证一个运行的应用程序\.

### 如何安装 @genie-react/cli？

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

### @genie-react/cli 支持 TypeScript 吗？

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

### @genie-react/cli 支持 ESM 还是 CommonJS？

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

### @genie-react/cli 可以商用吗？

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

### @genie-react/cli 的下载量有多少？

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

### @genie-react/cli 还在维护吗？

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

