---
name: xycomponents-cli
version: 1.0.0
description: >-
  通过项目内 xycomponents CLI 查询 @czxingyu/xycomponents 组件目录、Props、Events、
  Slots、示例代码、包入口与迁移说明。在编写或修改 xy- 组件用法、脚手架、
  或需要结构化组件元数据时使用。执行前确认已读本 skill 与 xycomponents-shared。
metadata:
  requires:
    bins: ["xycomponents"]
---

# xycomponents CLI

**CRITICAL — 执行查询前 MUST 先读 [`../xycomponents-shared/SKILL.md`](../xycomponents-shared/SKILL.md) 的版本策略。**

所有命令在**业务项目根目录**执行，且必须带 `--json`（机器可读）：

```bash
pnpm exec xycomponents <command> --json
```

npm / yarn：

```bash
npm exec xycomponents <command> --json
yarn xycomponents <command> --json
```

**禁止**使用全局安装的 `xycomponents`；版本必须与 `package.json` 中的 `@czxingyu/xycomponents` 一致。

## 推荐工作流

```text
1. pnpm exec xycomponents doctor --json          # 确认 CLI 可用、目录完整
2. pnpm exec xycomponents components --json       # 列出全部组件（或按 category 过滤结果）
3. pnpm exec xycomponents component <name> --json # 单个组件完整 API
4. pnpm exec xycomponents snippet <name> --example <id>  # 可复制示例（可加 --json）
```

## 命令速查

| 命令                                  | 用途                                                 |
| ------------------------------------- | ---------------------------------------------------- |
| `doctor --json`                       | 目录覆盖率、schema 版本、健康状态                    |
| `components --json`                   | 全部组件摘要（name、tag、category、lifecycle、docs） |
| `components --include-retired --json` | 含已退役 tombstone                                   |
| `component <name> --json`             | Props、Events、Slots、examples、import 信息          |
| `snippet <name> --example <id>`       | 示例 SFC 代码；加 `--json` 得结构化结果              |
| `migrate <name> --json`               | stable / deprecated / retired 及迁移步骤             |
| `package --json`                      | default / lite 入口、样式路径、lite 排除清单         |
| `help`                                | 命令列表                                             |

组件 `<name>` 使用 CLI 名（kebab-case），如 `button`、`form`、`date-picker`、`config-provider`。

## 分类过滤

`components` 返回的 `category` 字段示例：`General`、`Layout`、`Navigation`、`Data Entry`、`Data Display`、`Feedback`。可在 JSON 结果中按 category 过滤；CLI 的 `--category` 需与元数据中的 category 字符串完全一致。

## JSON 使用规则

- 以 CLI 输出的 JSON 为**唯一 API 真相**；不要臆造 prop 名、event 名或 slot 名。
- `component` 响应中的 `examples[].id` 用于 `snippet --example`。
- `lifecycle.status` 为 `deprecated` 或 `retired` 时，必须先跑 `migrate` 再改代码。
- 解析失败或 `exitCode !== 0` 时，检查是否已 `pnpm add @czxingyu/xycomponents` 并 `pnpm install`。

## 常见场景

**不知道有没有某个组件**

```bash
pnpm exec xycomponents components --json
```

**实现一个表单页**

```bash
pnpm exec xycomponents component form --json
pnpm exec xycomponents snippet form --example basic
```

**用户提到旧组件名或 API 报错**

```bash
pnpm exec xycomponents migrate <name> --json
```

**选择 full 还是 lite 入口**

```bash
pnpm exec xycomponents package --json
```

## 维护者（vue3components 源码仓库）

```bash
pnpm run build:cli
pnpm xycomponents component <name> --json
```

未 `build:cli` 时 `dist/cli.js` 可能落后于源码元数据。