cx-infra

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Infrastructure Resources Skill

基础设施资源Skill

Use this skill to discover and inspect infrastructure resources — what exists, whether it is healthy, and what its raw data contains.

使用此Skill可发现和检查基础设施资源——包括资源的存在情况、健康状态以及原始数据内容。

CLI Commands

CLI命令

Command	Purpose	Key flags
`cx infra resources types`	List available resource types (category/type pairs)	-
`cx infra resources list`	List resources of one category/type	`--category` , `--type` (required); `--name-filter` , `--scope key=value` , `--start-row` , `--end-row`
`cx infra resources health-history <resource-id>`	Daily health samples for one resource, oldest first	-
`cx infra resources raw-data <resource-id>`	Raw resource document as JSON	-

All commands are read-only and support
```
-o json
```
/
```
-o agents
```
for structured output.
Multi-profile fan-out applies to
types
and
list
only. Repeat
```
-p <profile>
```
on those to compare fleets across accounts.
```
health-history
```
and
```
raw-data
```
take a resource id, which is scoped to one team, so they reject more than one
```
-p
```
— run them once per profile instead.
```
--scope
```
is repeatable across different keys; allowed keys are
```
service
```
,
```
environment
```
,
```
team
```
(e.g.
```
--scope environment=prod --scope service=checkout
```
). Multiple keys combine with AND — a resource must match all of them. Each key accepts a single value and may be given at most once; repeating one (e.g.
```
--scope service=a --scope service=b
```
) is rejected. To cover several values for one key, run one query per value and combine the results.
Pagination:
```
--start-row
```
/
```
--end-row
```
define a row window (
```
--end-row
```
is exclusive); the default is the first 100 rows, and omitting only
```
--end-row
```
gives 100 rows from
```
--start-row
```
. Page through large fleets in windows (0-100, 100-200, …). list
never pages for you — fleets can run to hundreds of thousands of resources, so it returns one window and reports the total.
The window cannot reach past row 10,000. The API rejects any request whose
```
start-row + rows
```
exceeds 10,000, so paging cannot enumerate a fleet larger than that even though
```
total_count
```
reports its true size. In any case, narrow with
```
--name-filter
```
or
```
--scope
```
and page within each subset rather than trying to walk the whole list.
```
list
```
wraps its rows in an envelope (
```
total_count
```
,
```
returned_count
```
,
```
resources
```
) — the other subcommands return bare arrays.
```
total_count
```
is the fleet-wide match count, always present and independent of the window, so use it as the stop condition: keep paging while
```
start_row + returned_count < total_count
```
, subject to the 10,000-row ceiling above.
Pass resource IDs exactly as returned by
list
(quote them — they contain
```
:
```
and
```
=
```
); the CLI percent-encodes them for you.

命令	用途	关键参数
`cx infra resources types`	列出可用的资源类型（分类/类型对）	-
`cx infra resources list`	列出某一分类/类型的资源	`--category` 、 `--type` （必填）； `--name-filter` 、 `--scope key=value` 、 `--start-row` 、 `--end-row`
`cx infra resources health-history <resource-id>`	单个资源的每日健康样本，按从旧到新排序	-
`cx infra resources raw-data <resource-id>`	以JSON格式返回原始资源文档	-

所有命令均为只读，并支持使用
```
-o json
```
/
```
-o agents
```
输出结构化结果。
多配置文件扩展仅适用于
types
和
list
命令。在这些命令中重复使用
```
-p <profile>
```
可跨账户比较资源集群。
```
health-history
```
和
```
raw-data
```
需要资源ID，而资源ID属于单个团队，因此这些命令拒绝多个
```
-p
```
参数——请针对每个配置文件单独运行。
```
--scope
```
可针对不同键重复使用；允许的键包括
```
service
```
、
```
environment
```
、
```
team
```
（例如
```
--scope environment=prod --scope service=checkout
```
）。多个键通过逻辑与组合——资源必须匹配所有键。每个键仅接受单个值，且最多可使用一次；重复使用同一键（例如
```
--scope service=a --scope service=b
```
）会被拒绝。若要针对同一键的多个值进行查询，请为每个值单独运行一次查询并合并结果。
分页：
```
--start-row
```
/
```
--end-row
```
定义行窗口（
```
--end-row
```
为排他）；默认返回前100行，仅省略
```
--end-row
```
时将从
```
--start-row
```
开始返回100行。请按窗口（0-100、100-200……）遍历大型资源集群。list
命令不会自动分页——资源集群可能多达数十万个资源，因此它仅返回一个窗口并报告总数。
窗口不能超过第10000行。若
```
start-row + rows
```
超过10000，API会拒绝请求，因此即使
```
total_count
```
报告了真实的集群大小，分页也无法枚举超过10000行的集群。无论如何，请使用
```
--name-filter
```
或
```
--scope
```
缩小范围，并在每个子集中进行分页，而非尝试遍历整个列表。
```
list
```
命令的结果会封装在一个信封结构中（包含
```
total_count
```
、
```
returned_count
```
、
```
resources
```
）——其他子命令返回的是裸数组。
```
total_count
```
是集群范围内匹配的总数，始终存在且与窗口无关，因此请将其作为停止条件：当
```
start_row + returned_count < total_count
```
时继续分页，但需遵守上述10000行的上限。
请严格按照
list
命令返回的格式传递资源ID（需加引号——它们包含
```
:
```
和
```
=
```
）；CLI会自动对其进行百分号编码。

Inspection Workflow

检查工作流

Three steps, and only because each one supplies an input the next one requires:

types

gives the mandatory

--category

--type

list

gives the

resource_id

. Answering "is

web-server-1

healthy?" is these three calls — nothing more.

Discover what exists — categories and types are dynamic, so never guess:
bash
```
cx infra resources types -o json
```

List resources of that category/type, narrowing with name and scope filters:

bash

cx infra resources list --category Hosts --type EC2_Instances \
  --name-filter web --scope environment=prod -o json

Inspect one resource using a
```
resource_id
```
from step 2. Statuses are
```
Healthy
```
,
```
Critical
```
, or
```
Unmonitored
```
, one sample per day, oldest first:
bash
```
cx infra resources health-history "1001234:host_id=i-abc123" -o json
```
```
raw-data
```
is the alternative to this step, not a follow-on — use it instead when you need source-specific detail rather than health.

分为三个步骤，每个步骤的输出作为下一个步骤的输入：

types

命令提供必填的

--category

--type

参数，

list

命令提供

resource_id

。回答「

web-server-1

是否健康？」只需以下三次调用——无需其他操作。

发现现有资源——分类和类型是动态的，请勿猜测：
bash
```
cx infra resources types -o json
```

列出该分类/类型的资源，可通过名称和范围过滤器缩小范围：

bash

cx infra resources list --category Hosts --type EC2_Instances \
  --name-filter web --scope environment=prod -o json

使用步骤2中获取的
resource_id
检查单个资源。状态包括
```
Healthy
```
、
```
Critical
```
或
```
Unmonitored
```
，每天一个样本，按从旧到新排序：
bash
```
cx infra resources health-history "1001234:host_id=i-abc123" -o json
```
```
raw-data
```
是此步骤的替代方案，而非后续步骤——当你需要特定来源的详细信息而非健康状态时，请使用该命令。

Examples

示例

Just the ids and names

仅获取ID和名称

bash

undefined

bash

undefined

Rows live under .resources —

list

returns an envelope

结果行位于.resources下——

list

命令返回信封结构

cx infra resources list --category Hosts --type EC2_Instances -o json
| jq '[.resources[] | {resource_id, name}]'

undefined

cx infra resources list --category Hosts --type EC2_Instances -o json
| jq '[.resources[] | {resource_id, name}]'

undefined

Check fleet size, and whether one window covered it

检查集群大小，以及当前窗口是否覆盖所有资源

bash

cx infra resources list --category Hosts --type EC2_Instances -o json \
  | jq '{total_count, returned_count}'

bash

cx infra resources list --category Hosts --type EC2_Instances -o json \
  | jq '{total_count, returned_count}'

Next window, if there is one

如果存在下一个窗口

cx infra resources list --category Hosts --type EC2_Instances
--start-row 100 --end-row 200 -o json

undefined

cx infra resources list --category Hosts --type EC2_Instances
--start-row 100 --end-row 200 -o json

undefined

Find when a resource went critical

查找资源何时变为严重状态

bash

undefined

bash

undefined

health-history returns a bare array, so no .resources here

health-history返回裸数组，因此这里没有.resources

cx infra resources health-history "1001234:host_id=i-abc123" -o json
| jq '[.[] | select(.status == "Critical")]'

undefined

cx infra resources health-history "1001234:host_id=i-abc123" -o json
| jq '[.[] | select(.status == "Critical")]'

undefined

Read the raw resource document

读取原始资源文档

bash

undefined

bash

undefined

Source-specific detail: tags, instance metadata, configuration

特定来源的详细信息：标签、实例元数据、配置

cx infra resources raw-data "1001234:host_id=i-abc123" -o json

undefined

cx infra resources raw-data "1001234:host_id=i-abc123" -o json

undefined

Key Principles

核心原则

Discover before listing —
```
--category
```
and
```
--type
```
are required; always start from
```
cx infra resources types
```
.
Quote resource IDs and pass them verbatim — they embed
```
:
```
,
```
|
```
, and
```
=
```
; the CLI handles URL encoding.
Scope keys are a fixed set (
```
service
```
,
```
environment
```
,
```
team
```
) — unknown keys are rejected client-side before any request is made.
A missing raw document is not an error —
```
raw-data
```
exits 0 and emits an empty result on stdout:
```
[]
```
in
```
json
```
,
```
[0]:
```
in
```
agents
```
, and
```
No raw data found.
```
in text. Only the note
```
no raw data for this resource
```
goes to stderr. Parse the empty stdout result as a cleanly absent document, not a failure — and do not expect stdout to be blank.
Use
-o json
with
jq
for filtering; use
```
-o agents
```
for token-efficient output in agent contexts.
Multi-profile fan-out is for
types
and
list
only — repeating
```
-p <profile>
```
tags each row with its profile so fleets can be compared across accounts. The row window applies per profile, so
```
list
```
adds a
```
counts_by_profile
```
breakdown — page each profile against its own
```
total_count
```
, not the aggregate.
```
health-history
```
and
```
raw-data
```
error on a second
```
-p
```
.
A resource id never crosses profiles — it embeds the team id (
```
1001234:host_id=…
```
), so an id from one account cannot resolve in another. When a multi-profile
```
list
```
turns up something worth inspecting, note its
```
profile
```
field and query that single profile for its health or raw data.
Infra health is its own concept — the
```
Healthy
```
/
```
Critical
```
/
```
Unmonitored
```
statuses are computed by the infrastructure domain and are not the same as Service Catalog health. Correlate them with telemetry signals; do not treat them as interchangeable.
resource_id
never leaves this skill — pass it only to
```
health-history
```
and
```
raw-data
```
. For every other command, pivot on the resource
```
name
```
or the
```
service
```
scope value.

先发现再列出——
```
--category
```
和
```
--type
```
为必填参数；请始终从
```
cx infra resources types
```
命令开始。
为资源ID添加引号并按原样传递——它们包含
```
:
```
、
```
|
```
和
```
=
```
；CLI会处理URL编码。
范围键是固定集合（
```
service
```
、
```
environment
```
、
```
team
```
）——未知键会在客户端被拒绝，不会发送任何请求。
缺少原始文档并非错误——
```
raw-data
```
命令会返回0退出码，并在标准输出中输出空结果：
```
json
```
格式为
```
[]
```
，
```
agents
```
格式为
```
[0]:
```
，文本格式为
```
No raw data found.
```
。只有
```
no raw data for this resource
```
的提示会输出到标准错误。请将标准输出的空结果视为文档不存在，而非失败——且不要期望标准输出为空。
结合
-o json
和
jq
进行过滤；在Agent环境中使用
```
-o agents
```
以实现高效的令牌输出。
多配置文件扩展仅适用于
types
和
list
命令——重复使用
```
-p <profile>
```
会为每行添加配置文件标签，以便跨账户比较资源集群。行窗口针对每个配置文件生效，因此
```
list
```
命令会添加
```
counts_by_profile
```
细分——请针对每个配置文件的
```
total_count
```
进行分页，而非聚合总数。
```
health-history
```
和
```
raw-data
```
命令在使用第二个
```
-p
```
参数时会报错。
资源ID不会跨配置文件——它包含团队ID（
```
1001234:host_id=…
```
），因此一个账户的ID无法在另一个账户中解析。当多配置文件的
```
list
```
命令找到需要检查的资源时，请记录其
```
profile
```
字段，并针对该单个配置文件查询其健康状态或原始数据。
基础设施健康是独立概念——
```
Healthy
```
/
```
Critical
```
/
```
Unmonitored
```
状态由基础设施域计算得出，与服务目录健康状态不同。请将它们与遥测信号关联；不要将它们视为可互换的。
resource_id
仅在本Skill内使用——仅将其传递给
```
health-history
```
和
```
raw-data
```
命令。对于所有其他命令，请基于资源
```
name
```
或
```
service
```
范围值进行转换。

cx-infra

Original

Translation

Infrastructure Resources Skill

基础设施资源Skill

CLI Commands

CLI命令

Inspection Workflow

检查工作流

Examples

示例

Just the ids and names

仅获取ID和名称

Rows live under .resources —
`list`
returns an envelope

结果行位于.resources下——
`list`
命令返回信封结构

Check fleet size, and whether one window covered it

检查集群大小，以及当前窗口是否覆盖所有资源

Next window, if there is one

如果存在下一个窗口

Find when a resource went critical

查找资源何时变为严重状态

health-history returns a bare array, so no .resources here

health-history返回裸数组，因此这里没有.resources

Read the raw resource document

读取原始资源文档

Source-specific detail: tags, instance metadata, configuration

特定来源的详细信息：标签、实例元数据、配置

Key Principles

核心原则

Related Skills

相关技能

cx-infra

Original

Translation

Infrastructure Resources Skill

基础设施资源Skill

CLI Commands

CLI命令

Inspection Workflow

检查工作流

Examples

示例

Just the ids and names

仅获取ID和名称

Rows live under .resources — list returns an envelope

结果行位于.resources下——list命令返回信封结构

Check fleet size, and whether one window covered it

检查集群大小，以及当前窗口是否覆盖所有资源

Next window, if there is one

如果存在下一个窗口

Find when a resource went critical

查找资源何时变为严重状态

health-history returns a bare array, so no .resources here

health-history返回裸数组，因此这里没有.resources

Read the raw resource document

读取原始资源文档

Source-specific detail: tags, instance metadata, configuration

特定来源的详细信息：标签、实例元数据、配置

Key Principles

核心原则

Related Skills

相关技能

Rows live under .resources —
`list`
returns an envelope

结果行位于.resources下——
`list`
命令返回信封结构