@czxingyu/xycomponents 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@czxingyu/xycomponents",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "bin": {
     "xycomponents": "dist/cli.js"
   },
@@ -8,7 +8,8 @@
     "dist",
     "components/style/*.css",
     "docs/maintenance/migrations/*.md",
-    "global.d.ts"
+    "global.d.ts",
+    "skills"
   ],
   "type": "module",
   "sideEffects": [

package/skills/README.md

@@ -0,0 +1,64 @@
+# xycomponents AI Skills
+
+面向 Cursor 等 AI Agent 的 Skill，配合项目内安装的 `@czxingyu/xycomponents` 使用。
+
+## 原则
+
+- **CLI 与组件库版本一致**：在业务项目中 `pnpm add @czxingyu/xycomponents`，用 `pnpm exec xycomponents` 查询；升级库时重新 `pnpm add`，CLI 随包更新。
+- **不要全局安装** CLI，避免 AI 查到与项目不一致的 API。
+- **Bug / 新组件**：业务项目 AI 用 `xycomponents-contribute` 提交 GitHub Issue；组件库维护者用 `xycomponents-maintainer` 集中分诊与修复。
+
+## 完整闭环
+
+```text
+业务项目                         组件库仓库 (vue3components)
+────────                         ──────────────────────────
+pnpm add @czxingyu/xycomponents
+pnpm exec xycomponents ...  ──►   查用法 / API
+       │
+       ▼ Bug 或 Feature
+gh issue create (contribute) ──►  needs-triage 队列
+                                 maintainer skill 拉取 Issue
+                                 修复 / 新增组件 / 发版
+       ▲
+pnpm add @新版本 ◄───────────────  关闭 Issue，注明版本
+```
+
+## 安装 Skill 到业务项目
+
+复制 **`xycomponents-shared`**、**`xycomponents-cli`**、**`xycomponents-contribute`** 到 `.cursor/skills/`。
+
+```bash
+pnpm add @czxingyu/xycomponents
+cp -r node_modules/@czxingyu/xycomponents/skills/xycomponents-shared .cursor/skills/
+cp -r node_modules/@czxingyu/xycomponents/skills/xycomponents-cli .cursor/skills/
+cp -r node_modules/@czxingyu/xycomponents/skills/xycomponents-contribute .cursor/skills/
+```
+
+本仓库维护者额外启用 **`xycomponents-maintainer`**（已在 `.cursor/skills/`）。
+
+提交 Issue 需本机安装 [GitHub CLI](https://cli.github.com/) 并 `gh auth login`。
+
+## Skill 列表
+
+| Skill                                                         | 谁用         | 用途                         |
+| ------------------------------------------------------------- | ------------ | ---------------------------- |
+| [xycomponents-shared](./xycomponents-shared/SKILL.md)         | 业务项目     | 安装、版本策略、Vue 接入     |
+| [xycomponents-cli](./xycomponents-cli/SKILL.md)               | 业务项目     | CLI 查询 Props / 示例        |
+| [xycomponents-contribute](./xycomponents-contribute/SKILL.md) | 业务项目     | 提交 Bug / Feature Issue     |
+| [xycomponents-maintainer](./xycomponents-maintainer/SKILL.md) | 组件库维护者 | 拉取 Issue、分诊、修复、发版 |
+
+## GitHub Issue 模板
+
+| 模板                                                 | 标签                          | 场景              |
+| ---------------------------------------------------- | ----------------------------- | ----------------- |
+| [bug.yml](../.github/ISSUE_TEMPLATE/bug.yml)         | `bug`, `needs-triage`         | 可复现缺陷        |
+| [feature.yml](../.github/ISSUE_TEMPLATE/feature.yml) | `enhancement`, `needs-triage` | 新组件或 API 增强 |
+
+用法问题优先 [Discussions](https://github.com/czhang31795/vue3components/discussions)。
+
+## 验证 CLI
+
+```bash
+pnpm exec xycomponents doctor --json
+```

package/skills/xycomponents-cli/SKILL.md

@@ -0,0 +1,101 @@
+---
+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` 可能落后于源码元数据。

package/skills/xycomponents-contribute/SKILL.md

@@ -0,0 +1,109 @@
+---
+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)（仅组件库仓库维护者）。

package/skills/xycomponents-maintainer/SKILL.md

@@ -0,0 +1,118 @@
+---
+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` |

package/skills/xycomponents-shared/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: xycomponents-shared
+version: 1.0.0
+description: >-
+  @czxingyu/xycomponents 安装、版本对齐与 Vue 应用接入。在业务项目中使用 xy- 组件、
+  引入样式与类型、升级组件库，或需要确认 CLI 与 npm 包版本一致时使用。
+  查询 Props/Events/Slots 前请先读本 skill，再读 xycomponents-cli skill。
+metadata:
+  requires:
+    packages: ["@czxingyu/xycomponents"]
+---
+
+# xycomponents 共享规则
+
+## 版本与 CLI 策略（必须遵守）
+
+- **只在当前项目内**安装 `@czxingyu/xycomponents`；**不要**全局安装 CLI，也不要用与项目 `package.json` 版本不一致的全局命令。
+- CLI 元数据随 npm 包一起发布；**CLI 版本 = 已安装的包版本**。
+- 升级组件库时重新安装，CLI 会同步更新：
+
+```bash
+pnpm add @czxingyu/xycomponents@latest
+# 或锁定版本：pnpm add @czxingyu/xycomponents@0.1.2
+```
+
+- 安装或升级后验证：
+
+```bash
+pnpm exec xycomponents doctor --json
+```
+
+期望 `status` 为 `"pass"`。若命令不存在，说明依赖未安装或未执行 `pnpm install`。
+
+## 应用接入
+
+完整入口（默认推荐）：
+
+```ts
+import { createApp } from "vue";
+import XyComponents from "@czxingyu/xycomponents";
+import "@czxingyu/xycomponents/style";
+
+createApp(App).use(XyComponents).mount("#app");
+```
+
+轻量入口（排除 Empty / List / Result / Table / Transfer 等大资源组件族）：
+
+```ts
+import XyComponentsLite from "@czxingyu/xycomponents/lite";
+import "@czxingyu/xycomponents/lite/style";
+
+app.use(XyComponentsLite);
+```
+
+全局模板类型（使用 `app.use(XyComponents)` 时推荐）：
+
+```ts
+/// <reference types="@czxingyu/xycomponents/global" />
+```
+
+## 命名约定
+
+| 场景       | 形式               | 示例                    |
+| ---------- | ------------------ | ----------------------- |
+| Vue 组件名 | `Xy` + PascalCase  | `XyButton`              |
+| 模板标签   | `xy-` + kebab-case | `<xy-button>`           |
+| CLI 组件名 | kebab-case         | `button`、`date-picker` |
+
+## 写组件代码前
+
+1. 确认项目已安装 `@czxingyu/xycomponents`。
+2. 读取 [xycomponents-cli](../xycomponents-cli/SKILL.md)。
+3. 用 `pnpm exec xycomponents component <name> --json` 查 API，**禁止凭记忆猜测** Props / Events / Slots。
+4. 需要示例时用 `pnpm exec xycomponents snippet <name> --example <id>`。
+5. 遇到弃用或已删除组件，先 `pnpm exec xycomponents migrate <name> --json`。
+6. 确认是库 Bug 或需要新能力时，读 [xycomponents-contribute](../xycomponents-contribute/SKILL.md) 提交 GitHub Issue。
+
+## 入口选择
+
+不确定用 default 还是 lite 时：
+
+```bash
+pnpm exec xycomponents package --json
+```
+
+## 样式与主题
+
+- 必须引入对应 style 入口（`style` 或 `lite/style`）。
+- 组件内不要硬编码 `font-size: Npx`；扩展尺寸请用 `components/style/vars.css` 中的 design token（`--xy-font-size-*`、`--xy-control-font-size-*` 等）。
+
+## 本仓库（vue3components）维护者例外
+
+在组件库源码仓库内开发时，先构建 CLI 再查询：
+
+```bash
+pnpm run build:cli
+pnpm xycomponents component <name> --json
+```
+
+维护流程另见仓库根目录 `AGENTS.md`。