# @dataworks-technology/cli 中文文档

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

版本：2\.3\.2
npm 元数据更新时间：2026-11-11T07:29:28.679Z
中文译文更新时间：2026-11-14T13:43:24.344Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：2.2 MB，886 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：9 个
- 首次发布：2026-08-10T10:22:21.558Z
- 最新版本发布：2026-11-11T07:29:28.463Z
- 近 30 天下载量：2024（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

Dataworks 数据引擎的官方命令行界面

## 安装

```sh
npm install @dataworks-technology/cli
```

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

## README

![Dataworks Logo](https://cdn.jsdelivr.net/npm/@dataworks-technology/cli@latest/.github/.assets/dataworks-dark.svg)

# 数据工作——CLI

> Dataworks体育数据平台的官方命令行界面. 通过数据工作认证,运行公共数据引擎API,摄入度量衡,并从终端或自动化工作流程中消耗实时事件.

* * *

## 概览

这个 `dw` 二进制翻转公开的 GraphQL 合同 `@dataworks-technology/data` 输入可发现、可键入的命令。 它提供人可读输出供交互使用,并稳定JSON或NDJSON输出给脚本和代理.

### 表面指挥

| 命令 | 说明 |
| --- | --- |
| `dw agents install` | 为AI代理安装数据工作技能和MCP工具 |
| `dw auth ...` | 登录、 登录和检查活动的 UAT 或 Live 会话 |
| `dw autocomplete` | 为命令和旗帜安装 shell 补全 |
| `dw data ...` | 运行来自计划的查询、突变和订阅 |
| `dw ingest` | 将运动员的度量表发送到数据引擎摄入端点 |
| `dw events subscribe` | 订阅 AppSync 事件频道 |
| `dw graphql ...` | 运行原始 GraphQL 查询、变异和订阅 |
| `dw report-error` | 报告数据源出错 |
| `dw tenant ...` | 列出或选择后续命令使用的租户 |
| `dw commands` | 打印完整的命令目录 |

* * *

## 先决条件

-   [节点.js](https://nodejs.org/) 22 或更新运行已公布的 CLI
-   数据工作账户
-   [阿宝](https://bun.sh/) 数据库开发
-   仅将寄存器开发:带有CodeArtifact的AWS证书改为访问. `bun install` 运行 a `preinstall` 用来为私人取一个符号的钩子 `@dataworks/sdk` 依赖性,提供度量目录. 使用 `AWS_PROFILE=your-profile-name bun install` 非默认配置文件,以及 `bun run sdk` 要刷新过期的符号。 安装已公布的 CLI 需求 没有这些.

* * *

## 快速启动

1.  **安装 CLI :**
    
    ```sh
    npm install --global @dataworks-technology/cli
    dw --help
    ```
    
2.  **认证 :**
    
    ```sh
    dw auth login --environment uat
    dw auth status
    ```
    
    CLI 在您的浏览器中打开管理登录的 Dataworks , 并且从未收到您的密码 。 会话存储在操作系统认证存储中,从未存储在数据工作配置文件中. 如果浏览器无法自动打开, 请通过 `--no-browser` 并访问同一计算机上显示的 URL。 无头工作可以提供受保护的工作 `DW_SESSION_JSON` 换成秘密.
    
    `--environment` 接受 `live`, (中文(简体) ), `uat`,或任何命名的环境,例如 `james-dev`. 通过Live Cognito游泳池进行现场直播 环境标志通过UAT的。 公共 UAT 和 Live Cognitto 客户端的ID 被构建在。 用它代替它们 `--client-id`, (中文(简体) ), `DW_UAT_CLIENT_ID`, (中文(简体) ), `DW_LIVE_CLIENT_ID`,或 `DW_CLIENT_ID` 当测试不同的应用程序客户端时.
    
3.  **列出并选择租户.** 选择被保存到您的本地配置文件 用于后续命令.
    
    ```bash
    dw tenant list
    dw tenant select
    dw tenant select tenant-123
    ```
    
    `dw tenant list` 显示友好名称、ID和当前选择。 探员 并使用脚本 `dw tenant list --json`。 。 。 .
    
4.  **发现并运行命令 :**
    
    ```sh
    dw commands
    dw data athlete list
    dw data athlete create --name "Ada" --date-of-birth 1992-01-01
    ```
    

生成的命令文档可见于 [`docs/commands`](https://npmcn.com/package/%40dataworks-technology/cli/docs/commands/README.md)。 。 。 .

5.  **在 Codex 或 Claude 代码中启用数据工作 :**
    
    ```sh
    dw agents install
    ```
    
    此检测支持客户端并安装完整的数据工作插件 : 平滑的技巧加上只读的 `query_metrics` MCP服务器. 开始 a 安装后新建 Codex 线程 。 在克洛德代码,运行 `/reload-plugins` 或者说 启动新会话 。 只配置一个客户端, 使用 `dw agents install codex` 或者说 `dw agents install claude-code`。 。 。 .
    
    在设置完成之前, 交互式 CLI 最多使用此提醒打印 每24小时一次 从来没有出现过 `--json`永远藏起来 `dw agents reminder disable`,用 `dw agents reminder enable`,或 设定 `DW_NO_AGENT_REMINDER=1` 用于单一过程或自动化环境.
    

* * *

## 巴什自动完成

生成补全缓存并打印一次性的 Bash 设置指令 :

```sh
dw autocomplete bash
```

Global npm 安装并升级自动运行此命令. 它准备 最新的补全缓存并打印设置指令,但不编辑您的 shell 启动文件 。 如果 npm 无法访问 shell 缓存, 仍然安装 成功,您可以重试 `dw autocomplete bash`。 。 。 .

遵循显示的指示并重新装入 Bash 后, 按 Tab 到 完整 `dw` 命令名称和旗帜。 运行 `dw autocomplete --refresh-cache` 在安装添加命令的发布后.

## AI 代理计量查询

该软件包包括一个有重点的,只读的MCP服务器,它有三个工具: `query_metrics`, (中文(简体) ), `list_athletes`,以及 `list_events`。它使用同样的OS支持的登录会话,并选定租户为 `dw`,通过准确的ID或独有的名称解决运动员,解决公制名称 对照Cononical Dataworks目录, 民调同步数据探索器 查询,并返回正规结构行。 GPS 值包括解码 纬度和经度;心率值在有效时使用数字 BPM.

量子措辞与案例、空间、连字符和下划线不一致, 因此,“心率”决定 `heartrate`,与别名,例如: `gps`, (中文(简体) ), `hr`, (中文(简体) ), 财务报告和审定财务报表 `watts`。未识别名称返回最接近的犬科候选人 而不是赤裸裸的拒绝.

Codex和Claude代码最简单的设置是:

```sh
dw agents install
```

该命令在升级后可以安全地重新运行. 它安装或更新完整 每个被检测到的客户端的数据工作插件,并报告重装或重新启动步骤. 如果旧的市场注册指向不同的CLI安装,则重新运行 与 `--force`。 。 。 .

### 保持插件当前

代理客户端将插件复制到一个版本绑定的目录而不是读取 已安装 npm 软件包,因此升级 CLI 本身并不更新 技术 代理加载。 MCP服务器确实与CLI一起移动,因为它是 以 `dw-mcp` 从 `PATH` ——留下由老技能驱动的新服务器 直到插件刷新为止.

全局安装并升级自动刷新:后置钩子运行 `dw agents install --refresh`,仅更新已有客户端 数据工作和配置没有新内容 。 事后重新装入客户端 `/reload-plugins` 在克洛德代码中,或者一个新的代码线.

当不能运行时——安装 `--ignore-scripts`,或重新设置CLI 在不同的节点版本下—— `dw` 每天最多打印一次提醒 告诉你插件在后面 并命名修复它所需的两个步骤. 刷新为 `dw agents install`,添加 `--force` 如果市场仍然 在上次安装时点,然后重新装入客户端.

重新装入任何一种方式的事务: 已经运行的客户端保留插件复制 在启动时加载, 因此仅刷新不会改变当前会话中的任何内容 .

成功的设置会自动禁用定期的 CLI 提醒 。 选择退出 不安装代理集成, 运行 `dw agents reminder disable`。 。 。 .

其他 MCP 客户端可以启动安装 `dw-mcp` 二进制直接 :

```json
{
  "mcpServers": {
    "dataworks": {
      "command": "dw-mcp",
      "args": []
    }
  }
}
```

Npm 包装一个相容的 Codex 和 Claude 代码插件 `plugins/dataworks`它的突出重点的技巧使诸如“给我最后的..... James Haigh的30个GPS值“改为 `query_metrics` 电话 该工具接受 完全一个 `athlete_id` 或者说 `athlete_name`附加时 `metric`; 可选输入为 `limit`, (中文(简体) ), `order`, (中文(简体) ), `from`, (中文(简体) ), `to`, (中文(简体) ), `event_id`, (中文(简体) ), `dataset_datasource_id`, (中文(简体) ), `tenant_id`, (中文(简体) ), `metric_category`,以及 `timeout_ms`。 。 。 .

查询范围必须是 `athlete_id`, (中文(简体) ), `athlete_name`, (中文(简体) ), `event_id`,或 `dataset_datasource_id`。只提供事件或数据源回答问题 关于整个种族——"T100旧金山的最新心率值",以及 返回无效 `athlete` 每一行仍然随身携带 `athlete_id`。 。 。 .

`list_athletes` 财务报告和审定财务报表 `list_events` 存在,所以代理可以解析一个ID而不是 猜猜看,除了"错误拼写"以外,还能分辨出"不是在这个租户". 何时 `list_events` 报告 `unavailable: true` aPI没有为此归还任何东西 ,这是一个权限问题,而不是空置的租户.

服务器从不执行突变. 如果名称解析模糊,它 返回候选人,并需要明确的运动员ID而不是猜测. 每个错误都带有 `recovery` 字段命名修正它的命令.

* * *

## 产出和安全

-   命令默认会让人读取表格.
-   过 `--json` 对脚本和代理。 有限结果使用稳定 `{data,meta}` 信封; 订阅和其他流会释放出新行限制的JSON(NDJSON).
-   生成突变支持 `--dry-run --json` 在不发送请求的情况下提出请求.
-   破坏性突变和所有活性突变需要确认;非互动性呼叫者必须通过 `--yes`。 。 。 .
-   密码,令牌,授权信头,秘密,以及API密钥均由结构输出进行编辑.
-   缺少参数错误列出所需的 GraphQL 类型和代表性值,然后提供一个安全的复制复制示例和一个精确 `--help` 命令; `--json` 包含与结构化细节相同的指导.

```sh
# Preview a mutation without sending it
dw data athlete update --public-id athlete-123 --name "Ada L." --dry-run --json

# Explicitly confirm a destructive mutation
dw data athlete delete --public-id athlete-123 --yes

# Use raw GraphQL when no friendly command fits
dw graphql query --document @query.graphql --variables @variables.json --json
```

### 粗略的衡量标准

`dw ingest` 验证并发送运动员参数到一个事件和 数据集数据源. 每个衡量标准都要求 `athletePublicId`, (中文(简体) ), `metric`, (中文(简体) ), `value`, (中文(简体) ), 和一个正整数 `timestamp`通过一个内置的 JSON 阵列, a `{ "metrics": [...] }` 对象, `@filename`,或 `-` 从标准读取 JSON 输入.

```sh
# Inline JSON
dw ingest --event event-123 --dataset-datasource ds-456 --metrics '[{"athletePublicId":"ath-1","metric":"heartrate_calculated","value":172,"timestamp":1700000000}]'

# File input; strict validation rejects the whole batch if any metric is invalid
dw ingest --event event-123 --dataset-datasource ds-456 --metrics @metrics.json

# Send valid metrics, report dropped invalid metrics, and return stable JSON
dw ingest --event event-123 --dataset-datasource ds-456 --metrics @metrics.json --best-effort --json
```

### 订阅实时事件

实时计量频道使用情况 `dataworks/<dataset-datasource-id>/<event-id>/<metric-or-*>`启用 `*` 观看 数据集数据源/事件对的每个度量,或缩小的度量名 溪流。 溪流。 领先 `/` 是可选的。 人类产出为表格;添加 `--json` 页:1 邓杰森.

新闻 `Ctrl+C` 一次关闭 WebSocket 订阅并返回 壳.

```sh
# Watch all metrics for dataset-datasource 1 and event 1
dw events subscribe --channel dataworks/1/1/*

# Watch only heart-rate metrics as NDJSON
dw events subscribe --channel dataworks/1/1/heartrate --json
```

### 查询数据探索器

`dw data data-explorer execute` 带有明确列的查询参数存储 清单和计量类别。 可选字段支持数据浏览器过滤规则, 组合、分组、订购、限制和投票是同步的 `queryExecutionId`。该类别必须是 `METRICS_TYPE_A`, (中文(简体) ), `METRICS_TYPE_B`,或 `METRICS_TYPE_C`· ; `--columns` 是JSON阵列.

```sh
# Keep a filtered GPS query in a reusable JSON file
dw data data-explorer execute --input @gps-query.json --json

# Return the latest 30 GPS positions for one athlete
dw data data-explorer execute --columns '["timestamp","athletepublicid","current"]' --metric-category METRICS_TYPE_A --filter-rules '{"combinator":"and","rules":[{"field":"metric","operator":"in","value":"latlong"},{"field":"athletepublicid","operator":"in","value":"athlete-123"}]}' --limit 30 --order-by timestamp --order-direction DESC --json
```

相应 `gps-query.json` 包含没有 CLI 旗的相同字段 转换 :

```json
{
  "columns": ["timestamp", "athletepublicid", "metric", "current"],
  "metricCategory": "METRICS_TYPE_A",
  "filterRules": "{\"combinator\":\"and\",\"rules\":[{\"field\":\"metric\",\"operator\":\"in\",\"value\":\"latlong\"},{\"field\":\"athletepublicid\",\"operator\":\"in\",\"value\":\"athlete-123\"}]}",
  "limit": 30,
  "orderBy": "timestamp",
  "orderDirection": "DESC"
}
```

`filterRules` 是一个包含顶级的 AWSJSON 字符串 `combinator` (单位:千美元) `rules` 阵列。 每一个规则 `field`, (中文(简体) ), `operator`字符串 `value`; 已支持 运算符包括 `=`, (中文(简体) ), `!=`, (中文(简体) ), `>`, (中文(简体) ), `<`, (中文(简体) ), `>=`, (中文(简体) ), `<=`, (中文(简体) ), `contains`,以及 `in`。 。 。 . 用于 `in` 以逗号分隔。 GPS是标准 `latlong` 内 `METRICS_TYPE_A`; 数据 `current` 值是一个 `latitude:longitude` 绳子。 运行 `dw data data-explorer execute --help` 用于完整旗帜列表和示例. 单位 `--json` 输出, `rows` 是AWSJSON,可能需要JSON解码直到它成为 数组; 默认表格输出为人类进行解码.

* * *

## 常见命令

| 命令 | 说明 |
| --- | --- |
| `bun install --frozen-lockfile` | 安装开发依赖 |
| `bun run sdk` | 刷新用于获取的代码Artiffact 令牌 `@dataworks/sdk` |
| `bun run dev --help` | 运行 TypeScript 开发 CLI |
| `bun run generate` | 重新生成基于计划的指令和 Markdown |
| `bun run generate:check` | 校验生成的文件为当前文件 |
| `bun run test` | 运行 Vitest 单元测试 |
| `bun run lint` | 运行类型脚本检查 |
| `bun run format` | 用 Pretier 格式化文件 |
| `bun run build` | 生成命令, 为节点编译, 并构建 oclif 显示 |
| `make verify` | 运行生成、格式化、打字、测试和生产建设 |

* * *

## SDK 和命令生成

数据引擎SDK发布过滤后的公共GraphQL schema和包含其SDK版本,操作计数和schema hash的版本合同. 这个寄存器将SDK版本所标注,验证合同,并为每次公共操作生成一个oclif命令和Markdown页面.

下方的文件 `src/generated/`, (中文(简体) ), `src/commands/data/`,以及 `docs/commands/` 生成。 变动 [`schema/operation-overrides.json`](https://npmcn.com/package/%40dataworks-technology/cli/schema/operation-overrides.json), (中文(简体) ), [`scripts/generate-commands.ts`](https://npmcn.com/package/%40dataworks-technology/cli/scripts/generate-commands.ts),或上游公共计划而不是编辑生成的文件.

冠名是用同样的方式生成的. [`scripts/generate-metrics.ts`](https://npmcn.com/package/%40dataworks-technology/cli/scripts/generate-metrics.ts) 读取 `metricConfig` 从私人 `@dataworks/sdk` 依赖和排放 `src/generated/metrics.ts` 和目录块 `query-dataworks-metrics` 技术。 要添加一个度量, 请更改 SDK , 而不是生成的文件, 而不是在 `src/lib/metric-names.ts`。 。 。 .

每天对新软件进行SDK维护工作流程检查 `@dataworks-technology/data` 财务报告和审定财务报表 `@dataworks/sdk` 各个版本。 决定式生成首先运行;如果需要兼容性工作,则受限的LiteLLM维护代理修复. 寄存器工作流程用完整的CI验证准确的更新,自动合并成功的更新,并开始CLI发布. 修复失败仍然是供人审查的公关草案.

见 [结构](https://npmcn.com/package/%40dataworks-technology/cli/docs/architecture.md), (中文(简体) ), [捐款](https://npmcn.com/package/%40dataworks-technology/cli/docs/contributing.md), (中文(简体) ), [自动 SDK 维护](https://npmcn.com/package/%40dataworks-technology/cli/docs/maintenance.md), (中文(简体) ), [警卫](https://npmcn.com/package/%40dataworks-technology/cli/docs/security.md),以及 [释放](https://npmcn.com/package/%40dataworks-technology/cli/docs/releasing.md) 详细情况.

* * *

## 排雷中心/发改委

| 触发 | 工作流程 | 说明 |
| --- | --- | --- |
| 拉请求或推向 `main` | `ci.yml` | 核证带有22和24号节点的自备跑道上的生成、格式、类型、测试、建造和包装 |
| 每日日程安排或人工发送 | `sdk-sync.yml` | 更新 SDK , 验证并自动合并成功的维护 PR |
| 手工调度 | `uat-e2e.yml` | 认证反对 UAT 并读取公开数据表 |
| 推动 `main` 或人工发送 | `release.yml` | 运行自寄主机的发布请求, 然后发布 npm 信任的出版并通知 Slack |

成功的SDK维护与放行取悦PR被验证并自动合并. SDK修复失败仍为人审查PR草案. npm 成功出版后通知Slack通过 `SLACK_WEBHOOK_URL`。 。 。 .

* * *

## 代码样式

-   **阿宝** 依赖管理和寄存脚本
-   **节点.js 22+** 已公布的 CLI 兼容性
-   **高级** 用于格式化
-   **维特** 用于单位测试
-   **常规承诺** 由承诺方强制执行`feat:`, (中文(简体) ), `fix:`, (中文(简体) ), `chore:`, (中文(简体) ), `refactor:`, (中文(简体) ), `test:`, (中文(简体) ), `docs:`(中文(简体) )
-   对每个生成的图QL突变进行明确的风险分类

* * *

## 交叉依赖关系

-   取决于 **数据工作-数据** 用于公共图QL计划 `@dataworks-technology/data` 软件包
-   使用生成 Data SDK Docusaurus 引用的相同的公共合同
-   运行时对 UAT 或 Live Cognitto 和数据引擎端点进行认证
-   新的SDK版本通过经核实的自动拉动请求而不是手动复制

* * *

## 贡献者

-   [詹姆斯・海格](https://github.com/jameshaigh54)
-   [费利克斯·阿隆索·罗德里格斯](https://github.com/felixalonso)
-   [保罗·加德纳](https://github.com/phpMagpie)
-   [克里斯·摩尔](https://github.com/cwiggo)
-   [玛蒂娜·布里兰特](https://github.com/martina-WAS)

## 许可证

麻省理工学院

## 常见问题

### @dataworks-technology/cli 是什么？

Dataworks 数据引擎的官方命令行界面

### 如何安装 @dataworks-technology/cli？

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

### @dataworks-technology/cli 支持 TypeScript 吗？

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

### @dataworks-technology/cli 支持 ESM 还是 CommonJS？

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

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

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

### @dataworks-technology/cli 可以商用吗？

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

### @dataworks-technology/cli 的下载量有多少？

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

### @dataworks-technology/cli 还在维护吗？

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