# @adobe/aio-cli-plugin-telemetry 中文文档 规范地址：https://npmcn.com/package/%40adobe/aio-cli-plugin-telemetry/ 版本：2\.2\.0 npm 元数据更新时间：2026-10-01T01:32:09.015Z 中文译文更新时间：2026-11-05T20:57:32.802Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40adobe/aio-cli-plugin-telemetry 原文对照：https://npmcn.com/package/%40adobe/aio-cli-plugin-telemetry/?lang=original 项目主页：https://github.com/adobe/aio-cli-plugin-telemetry 源码仓库：https://github.com/adobe/aio-cli-plugin-telemetry ## 关键信息（来自 npm 元数据） - 包体积（解压后）：47.8 kB，13 个文件 - TypeScript 类型：未声明 - Node.js 要求：\>=20 - 运行依赖：5 个 - 首次发布：2022-03-29T06:55:04.416Z - 最新版本发布：2026-06-10T18:35:21.409Z - 近 30 天下载量：23627（2026-10-05 至 2026-11-03，npm 官方下载统计） - 已发布版本数：17（近 12 个月 3 个） ## 中文简介 Adobe 开发者 cli 遥测 ## 安装 ```sh npm install @adobe/aio-cli-plugin-telemetry ``` 也可以使用：`pnpm add @adobe/aio-cli-plugin-telemetry`、`yarn add @adobe/aio-cli-plugin-telemetry`、`bun add @adobe/aio-cli-plugin-telemetry` ## README # aio-cli-plugin-遥测 Adobe 开发者 cli 使用遥测 [![License](https://img.shields.io/npm/l/@adobe/aio-cli-plugin-telemetry.svg)](https://github.com/adobe/aio-cli-plugin-telemetry/blob/master/package.json) [![oclif](https://img.shields.io/badge/cli-oclif-brightgreen.svg)](https://oclif.io/) [![Version](https://img.shields.io/npm/v/@adobe/aio-cli-plugin-telemetry.svg)](https://npmjs.org/package/@adobe/aio-cli-plugin-telemetry) [![Downloads/week](https://img.shields.io/npm/dw/@adobe/aio-cli-plugin-telemetry.svg)](https://npmjs.org/package/@adobe/aio-cli-plugin-telemetry) [![Codecov Coverage](https://img.shields.io/codecov/c/github/adobe/aio-cli-plugin-telemetry/master.svg?style=flat-square)](https://codecov.io/gh/adobe/aio-cli-plugin-telemetry/) [![Github Issues](https://img.shields.io/github/issues/adobe/aio-cli-plugin-telemetry.svg)](https://github.com/adobe/aio-cli-plugin-telemetry/issues) [![Github Pull Requests](https://img.shields.io/github/issues-pr/adobe/aio-cli-plugin-telemetry.svg)](https://github.com/adobe/aio-cli-plugin-telemetry/pulls) # 图标 - [`aio telemetry yes`](https://npmcn.com/package/%40adobe/aio-cli-plugin-telemetry/#readme-aio-telemetry-yes) ## `aio telemetry yes` 允许 cli 收集匿名使用数据 ``` USAGE $ aio telemetry yes $ aio telemetry off $ aio telemetry ARGUMENTS [STATE] (on|off|yes|no) set telemetry state DESCRIPTION Allow the cli to collect anonymous usage data ``` _参见代码 : [src/命令/遥测/index.js](https://github.com/adobe/aio-cli-plugin-telemetry/blob/v2.2.0/src/commands/telemetry/index.js)_ ## 配置 当此插件由不同的 CLI 托管时 : - `aioTelemetry` (根中的可选对象) `package.json` 会 议 日 程 和 议 程 **主机 CLI** 一样 `pjson` oclif通过入内钩: - `postUrl` (可选字符串):接收 POSTed 量子批量的遥测代理的 HTTPS URL. 当您的 CLI 发送到一个不同于插件默认的 App 构建器动作或网关时使用此功能 . - `fetchHeaders`:可选额外信头合并为遥测请求(`Content-Type` 总是设定) - `productPrivacyPolicyLink`: 一次性遥测通知中显示的链接(收集什么以及如何选择退出) - `productName`: 如何在遥测通知中提及CLI(来自 `displayName` 或者说 `name` 内 `package.json`(中文(简体) ) - `productBin`: 在帮助文本中显示(来自 `bin` 内 `package.json`;如果存在多个宾箱,则使用第一个宾箱). 示例:运行 `${productBin} telemetry on` ### 覆盖遥测 POST URL 解析顺序( 第一局胜出) : 1. **`aioTelemetry.postUrl`** 在主机 CLI 中 `package.json` 2. **`AIO_TELEMETRY_POST_URL`** 环境变量( 非空字符串) 3. **内建默认** 在插件中 (`DEFAULT_TELEMETRY_POST_URL` 内 [`src/telemetry-lib.js`](https://github.com/adobe/aio-cli-plugin-telemetry/blob/master/src/telemetry-lib.js)(中文(简体) ) 东道主 `package.json` 示例: ```json { "name": "my-cli", "bin": { "mycli": "./bin/run.js" }, "aioTelemetry": { "postUrl": "https://-.adobeio-static.net/api/v1/web//" } } ``` 环境覆盖( 无) `package.json` 更改; 用于 CI、 中继或本地代理调试 : ```sh export AIO_TELEMETRY_POST_URL='https://-.adobeio-static.net/api/v1/web//' mycli app deploy ``` 解析的 URL 在每次遥测发送上传递给冲洗工; 它适用于CLI 过程的其余部分 `init` 运行. ## 通过环境变量选择出去 遥测在 `AIO_TELEMETRY_DISABLED` 设置为其中之一 **`true`**, (中文(简体) ), **`1`**,或 **`yes`** (精确匹配;大小写敏感). 其他价值,例如: `0`, (中文(简体) ), `false`, (中文(简体) ), `no`,或空字符串 **没有** 通过此变量禁用遥测 . 这并不能改变持续的退出状态。 对CI管道和脚本环境有用. ```sh AIO_TELEMETRY_DISABLED=true aio app deploy AIO_TELEMETRY_DISABLED=1 aio app deploy AIO_TELEMETRY_DISABLED=yes aio app deploy ``` ## Fush 架构 遥测是 **最佳成绩**: 当代理已下架或网络失败时, 事件不会持续 . 冲浪发生在一个 **终端事件** —— 说 `postrun` (命令成功), `command-error` (投掷命令),或 `command-not-found`。 oclif 运行 `postrun` 只有在成功的时候,所以 `command-error`编号 :`command-not-found` 必须自行冲出;否则误差遥测(最有价值信号)会被缓冲并悄悄地投出出出站. 在一个终端事件上,来自同一指令中较早的钩子的任何内置度量衡都与终端度量衡合并,合并后批量交给一个 **防火和遗忘去除子进程** (单位:千美元)`src/flush-worker.js`) (中文(简体) ). 母体CLI产下工人,立即 `unref()`s,所以CLI可以不用等HTTP POST就退出. 如果 POST 失败(网络出错或非-2xx 响应),则批量投放;遥测不能阻断或慢化正常的CLI使用. 非致命事件(例如: `telemetry-notice`) 在一个 **模拟缓冲** 直到下一个终端事件冲出它们。 如果进程在任何终端事件(崩溃, `SIGKILL`),缓冲事件丢失. 当远程测量被禁用或当 `init` 重运行( 新的命令会话) . ## 特工检测 该插件通过检查事件发生时的环境变量来检测CLI是被AI代理还是被人类所引用. 检测到的上下文作为 `invocation_context` (单位:千美元)`"agent"` 或者说 `"human"`和 `agent_name`。 。 。 . 自动检测到支持的代理 : | 环境变量 | 检测到的代理名称 | | --- | --- | | `AGENT` | 变量值(或 `"generic"` 若为 `1`编号 :`true`(中文(简体) ) | | `AI_AGENT` | 变量值(或 `"generic"` 若为 `1`编号 :`true`(中文(简体) ) | | `AIO_AGENT` | `aio-opt-in` | | `AIO_INVOCATION_CONTEXT=agent` | `aio-opt-in` | | `CURSOR_AGENT` | `cursor` | | `CLAUDECODE` 编号 : `CLAUDE_CODE` | `claude` | | `GEMINI_CLI` | `gemini` | | `CODEX_SANDBOX` | `codex` | | `AUGMENT_AGENT` | `augment` | | `CLINE_ACTIVE` | `cline` | | `OPENCODE_CLIENT` | `opencode` | | `REPL_ID` | `replit` | | `PATH` 包含 `github.copilot-chat` | `github-copilot` | 在不设置特定工具变量的情况下选择代理跟踪, 设置 `AIO_INVOCATION_CONTEXT=agent`。 。 。 . ## POST 数据 这个 `eventData` 属性总是字符串。 对象和阵列作为JSON文本(例如. `"{}"`, (中文(简体) ), `"{\"message\":\"…\"}"`) (中文(简体) ). 串接有效载荷(如遥测通知结果) `shown`)作为纯文本存储,无需多加一层JSON引用. 数字和布尔使用它们通常的字符串形式(`"0"`, (中文(简体) ), `"false"`) (中文(简体) ). 计量有效载荷的示例形状: ```json [{ "metrics": [{ "name": "aio.cli.telemetry", "type": "gauge", "value": 1, "timestamp": 1673404918437, "attributes": { "eventName": "postrun", "eventData": "{}", "cliVersion": "@adobe/aio-cli@11.0.2", "clientId": 264421030538, "command": "app:deploy", "commandDuration": 5661, "commandFlags": "", "commandSuccess": true, "nodeVersion": "v22.21.1", "osNameVersion": "macOS Sequoia 15.4", "invocation_context": "human", "agent_name": "unknown" } }] }] ``` ## 常见问题 ### @adobe/aio-cli-plugin-telemetry 是什么？ Adobe 开发者 cli 遥测 ### 如何安装 @adobe/aio-cli-plugin-telemetry？ 在项目目录运行 npm install @adobe/aio-cli-plugin-telemetry，或使用 pnpm add / yarn add / bun add。 ### @adobe/aio-cli-plugin-telemetry 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/adobe\_\_aio-cli-plugin-telemetry 是否存在。 ### @adobe/aio-cli-plugin-telemetry 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @adobe/aio-cli-plugin-telemetry 可以商用吗？ @adobe/aio-cli-plugin-telemetry 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。 ### @adobe/aio-cli-plugin-telemetry 的下载量有多少？ 根据 npm 官方下载统计，@adobe/aio-cli-plugin-telemetry 在 2026/10/05 – 2026/11/03 这 30 天内被下载 23,627 次，日均约 788 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @adobe/aio-cli-plugin-telemetry 还在维护吗？ 最新版本 2\.2\.0 发布于 2026/06/11（4 个月前）；至今共发布 17 个版本，其中过去 12 个月发布了 3 个；首次发布于 2022/03/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。