---
name: xycomponents-contribute
version: 1.0.0
description: >-
  在业务项目中向 xycomponents 反馈 Bug、功能建议或新组件需求。当组件行为异常、
  文档与 CLI 不一致、需要库侧新增能力，或用户要求提交 GitHub Issue 时使用。
  先读 xycomponents-shared 与 xycomponents-cli，再按本 skill 创建 Issue。
metadata:
  requires:
    packages: ["@czxingyu/xycomponents"]
---

# xycomponents 反馈与 Issue

**前置**：已读 [`xycomponents-shared`](../xycomponents-shared/SKILL.md) 与 [`xycomponents-cli`](../xycomponents-cli/SKILL.md)。

**仓库**：`czhang31795/vue3components`（npm 包 `@czxingyu/xycomponents`）

## 先判断走哪条路

| 情况                         | 动作                                                                                                                                     |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| 用法不确定、可能是误用       | 先 `pnpm exec xycomponents component <name> --json`；仍不清楚 → [Discussions](https://github.com/czhang31795/vue3components/discussions) |
| 确认是组件库 Bug（复现稳定） | 创建 **Bug Issue**（见下）                                                                                                               |
| 需要新组件或增强现有 API     | 创建 **Feature Issue**（见下）                                                                                                           |
| 含密钥、内网地址、用户数据   | **不要**写入 Issue；脱敏后再提交                                                                                                         |

## 提交 Bug 前（必须）

1. 用 CLI 核对公开 API，确认不是文档误读：

```bash
pnpm exec xycomponents component <name> --json
pnpm exec xycomponents doctor --json
```

2. 整理**最小 Vue 复现**（单文件 SFC 或 StackBlitz/CodeSandbox 链接），去掉业务无关代码。
3. 记录：`@czxingyu/xycomponents` 版本、Vue 版本、浏览器/Node 环境。
4. 明确：期望行为、实际行为、控制台/无障碍相关日志。
5. 标注是否为回归（之前版本是否正常）。

## 用 GitHub CLI 创建 Bug Issue

需已安装并登录 [`gh`](https://cli.github.com/)（`gh auth status`）。

```bash
gh issue create \
  --repo czhang31795/vue3components \
  --template bug \
  --title "[Bug] <组件> <一句话摘要>" \
  --field component="<name>" \
  --field version="@czxingyu/xycomponents <版本>, Vue <版本>, <浏览器>" \
  --field reproduction="<最小复现 SFC 或链接>" \
  --field steps="1. ...\n2. ...\n3. ..." \
  --field expected="<期望行为>" \
  --field actual="<实际行为与错误日志>" \
  --field regression="不确定|是，之前版本正常|否，从未正常"
```

创建成功后把 Issue URL 返回给用户。自动带上标签 `bug`、`needs-triage`。

若 `gh` 不可用，给出 Web 链接让用户确认后提交：

`https://github.com/czhang31795/vue3components/issues/new?template=bug`

Issue 正文请按模板字段自行填写（与上面 `--field` 内容一致）。

## 用 GitHub CLI 创建 Feature / 新组件 Issue

新增组件或增强 API 前，先证明现有目录无法满足：

```bash
pnpm exec xycomponents components --json
pnpm exec xycomponents component <相近组件> --json
pnpm exec xycomponents package --json
```

```bash
gh issue create \
  --repo czhang31795/vue3components \
  --template feature \
  --title "[Feature] <组件或能力> <一句话摘要>" \
  --field component="<name>" \
  --field version="@czxingyu/xycomponents <版本>" \
  --field request_type="新增组件|增强现有组件|文档 / Demo / CLI 元数据|其他" \
  --field scenario="<业务场景>" \
  --field alternatives="<已尝试的组件组合或方案>" \
  --field proposal="<期望 API / 交互草案，可留空>"
```

Web 备选：`https://github.com/czhang31795/vue3components/issues/new?template=feature`

## AI 不应做的事

- 不要在未用 CLI 核对 API 的情况下断定是 Bug。
- 不要提交无法复现的 Issue（缺少步骤、版本或最小复现）。
- 不要替维护者直接改组件库源码（业务项目 AI 只反馈 Issue，除非用户明确要求 fork/PR）。
- 不要把 `pnpm exec xycomponents` 换成全局 `xycomponents`（版本必须与项目一致）。

## 提交后

告知用户 Issue 编号与链接；修复由维护者在组件库仓库集中处理。用户升级修复版本：

```bash
pnpm add @czxingyu/xycomponents@<新版本>
pnpm exec xycomponents doctor --json
```

维护者处理流程见 [`xycomponents-maintainer`](../xycomponents-maintainer/SKILL.md)（仅组件库仓库维护者）。