---
name: xycomponents-maintainer
version: 1.0.0
description: >-
  在 vue3components 源码仓库中集中拉取 GitHub Bug/Feature Issue、分诊、修复回归、
  或按规范新增组件。维护者处理 needs-triage 队列、跑 CI、发版时使用。
  业务项目 AI 不要应用本 skill。
---

# xycomponents 维护者工作流

**适用范围**：`czhang31795/vue3components` 源码仓库。业务项目请用 `xycomponents-contribute` 提交 Issue。

## 开始工作

```bash
pnpm install
pnpm run build:cli
pnpm xycomponents doctor --json
pnpm run audit:components
```

先读 `AGENTS.md`、`docs/maintenance/ai-bugfix.md`、`docs/maintenance/component-development.md`。

## 集中拉取待处理 Issue

需 `gh` 已登录且有仓库权限。

**待分诊 Bug**

```bash
gh issue list --repo czhang31795/vue3components --label "needs-triage,bug" --state open --json number,title,labels,createdAt,url
```

**待分诊 Feature / 新组件**

```bash
gh issue list --repo czhang31795/vue3components --label "needs-triage,enhancement" --state open --json number,title,labels,createdAt,url
```

**某组件相关 Issue（标题或正文搜索）**

```bash
gh search issues --repo czhang31795/vue3components "table label:bug" --json number,title,state,url
```

**查看单个 Issue 全文**

```bash
gh issue view <number> --repo czhang31795/vue3components
```

## 分诊规则

| 结论         | 动作                                                                  |
| ------------ | --------------------------------------------------------------------- |
| 信息不足     | 评论索要最小复现 / 版本；保持 `needs-triage`                          |
| 用法问题     | 指向 CLI 与文档；关闭或转 Discussions                                 |
| 确认 Bug     | 去掉 `needs-triage`，保留 `bug`；可选加 `component:<name>` 自定义标签 |
| 确认 Feature | 评估是否与 `docs/maintenance/component-library-status.md` 路线一致    |
| 重复         | 关闭并链接已有 Issue                                                  |

```bash
gh issue edit <number> --repo czhang31795/vue3components --remove-label needs-triage
gh issue comment <number> --repo czhang31795/vue3components --body "..."
```

## 修复 Bug（与 ai-bugfix.md 一致）

1. 读 Issue + `pnpm xycomponents component <name> --json` 定位源码与文档。
2. GitNexus：`query` → `context` → **`impact`**（HIGH/CRITICAL 须警告用户）。
3. 先写**失败回归测试**，再最小修复。
4. `pnpm test`（目标文件）→ `pnpm run ci`。
5. `detect_changes({ scope: "compare", base_ref: "main" })`。
6. 公开行为变化：`pnpm changeset`。
7. PR 描述关联 `Fixes #<number>`，附修复前后证据。

```bash
gh pr create --title "fix(<component>): ..." --body "Fixes #123\n\n..."
```

## 新增组件（来自 Feature Issue）

仅当有明确业务证据且现有组件 + core 原语无法组合时进行：

```bash
pnpm generate:component -- <Name> --title <中文名> --group <group> --description <description>
```

分组：`general` | `navigation` | `layout` | `data-entry` | `data-display` | `feedback`

逐项替换 `@xy-component-placeholder`，同步文档 API、Demo、CLI 详细元数据，直至 `pnpm run audit:components` 与 `pnpm run ci` 通过。

## 批量修复同一组件的多条 Bug

```bash
gh search issues --repo czhang31795/vue3components "label:bug label:needs-triage table"
```

按 Issue 优先级合并根因；同一 PR 可 `Fixes #1, Fixes #2`（仅当同一修复确实解决多个 Issue）。

## 发版后通知

合并并发布后，在相关 Issue 评论修复版本，例如 `@czxingyu/xycomponents@0.1.3`，并关闭 Issue。

```bash
gh issue close <number> --repo czhang31795/vue3components --comment "Fixed in @czxingyu/xycomponents@0.1.3"
```

## 权威文档

| 主题            | 路径                                           |
| --------------- | ---------------------------------------------- |
| Bug 闭环        | `docs/maintenance/ai-bugfix.md`                |
| 组件完成定义    | `docs/maintenance/component-development.md`    |
| 生命周期 / 迁移 | `docs/maintenance/component-lifecycle.md`      |
| 发布            | `docs/maintenance/release.md`                  |
| 能力路线图      | `docs/maintenance/component-library-status.md` |