@apexhub/apex-ui-skill 0.0.0-stage → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Apex UI Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,12 @@
1
- # Temporary Holding Version
1
+ # @apexhub/apex-ui-skill
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ `packages/skills/apex-ui/` 是 Apex UI 的开发辅助 Skill,提供组件选型、API 核对、主题接入、前缀重写
4
+ 和用法审计指南。`.agents/skills/apex-ui/` 是仓库内的安装副本,必须与源文件同步。
5
+
6
+ ```bash
7
+ node --input-type=module -e 'import { copySkillPayload } from "./packages/skills/scripts/lib/install.mjs"; copySkillPayload("packages/skills/apex-ui", ".agents/skills/apex-ui")'
8
+ pnpm --filter @apexhub/apex-ui-skill test
9
+ pnpm --filter @apexhub/apex-ui-skill typecheck
10
+ ```
11
+
12
+ 测试只使用临时目录和本地 fixture,不读取用户 npm 配置,也不访问需要认证的 registry。
@@ -0,0 +1,135 @@
1
+ ---
2
+ name: apex-ui
3
+ description: >-
4
+ 在使用 Apex UI(开源 React 组件库)的项目里做页面、改界面、改样式、修组件显示问题、升级组件库时
5
+ 使用。项目里有 src/components/apex.json 或 src/components/apex/ 目录,或依赖里有 @apexhub/apex-ui-react,
6
+ 就适用,即使用户没有提到 Apex UI。也用于首次安装:默认以源码模式把组件源码放进项目的
7
+ src/components/apex/,由项目直接维护和修改。写代码前按项目内组件目录的 llms.txt 和 llm.txt
8
+ 核对真实 Props,不编造组件不存在的 API。
9
+ ---
10
+
11
+ # 使用 Apex UI
12
+
13
+ Apex UI 是基于 Radix UI 和设计 Token 的 React 19 组件库,有两种用法,一个项目只用一种:
14
+
15
+ - **源码模式(默认)**:`npx @apexhub/apex-ui-react-source init` 把全部组件源码复制到
16
+ `src/components/apex/`,代码归项目所有,组件有问题直接改源码。
17
+ - **npm 模式**:安装编译好的 `@apexhub/apex-ui-react`。只在项目已经在用它,或用户明确要求时使用。
18
+
19
+ ## 和用户沟通
20
+
21
+ 用户很可能不是开发人员,只会用自然语言描述想要的页面。默认按下面做,除非用户明显是开发人员并
22
+ 要求看细节:
23
+
24
+ - **用大白话**。说做了什么、现在能看到什么、下一步可以怎么说;不贴命令输出和报错堆栈,不用
25
+ “依赖”“构建”“类型检查”这类词而不解释。
26
+ - **技术选择自己定**。目录、包管理器、依赖版本、文件怎么组织,取本 skill 给的默认值,做完再简单
27
+ 说明,不要拿这些问题去问用户。
28
+ - **只在这些情况先问**:要删除或覆盖用户已有的文件;要改动项目里和 Apex UI 无关的现有功能;需求
29
+ 本身有歧义(页面要什么内容、长什么样)。
30
+ - **做完让用户看得到**。改完页面后确认开发服务器在运行,自己先打开页面检查,再把可以点击的地址
31
+ 给用户。当前工具打不开网页时,至少确认构建通过、开发服务器没有报错,并说明页面还没有实际看过。用户说“这里不对”时,先自己打开页面看实际效果,再动手改。
32
+ - **打开页面时检查这 5 项**:浏览器控制台没有报错;页面没有横向滚动条;主题(亮色或暗色)和用户
33
+ 要求的一致;内置文案(分页、日期、校验提示)的语言和用户一致;用户这次提到的每个功能都点过一遍。
34
+ - 出错自己修;修不了时,说清楚卡在哪、需要用户做的那一件事。
35
+
36
+ ## 开工前先看项目现状
37
+
38
+ 每次对话第一次要动界面之前,在项目根目录运行一次:
39
+
40
+ ```bash
41
+ npx @apexhub/apex-ui-react-source info --json
42
+ ```
43
+
44
+ 按结果里的 `mode` 走:
45
+
46
+ | `mode` | 做什么 |
47
+ | --- | --- |
48
+ | `source` | 源码模式。组件目录是 `dir`。按下面「使用组件」工作 |
49
+ | `npm` | npm 模式,按 `references/setup.md` 工作。不要擅自改成源码模式;用户要求迁移时,先说明影响并得到确认 |
50
+ | `none` | 有项目但还没装 Apex UI。默认按 `references/source-install.md` 用源码模式安装;用户明确要求 npm 包时才按 `references/setup.md` |
51
+ | `no-project` | 当前文件夹还没有项目。按 `references/source-install.md` 做,它会先新建一个 React 项目 |
52
+
53
+ `mode` 是 `source` 时再看这几项,不对就先修好再写页面,不用问用户:
54
+
55
+ - `globalCss` 为 `false`:入口文件还没引入组件目录的 `global.css`。
56
+ - `provider` 为 `false`:应用还没包 `ApexProvider`。
57
+ - `alias` 为 `false`:还没有 `@` 别名,按 `references/source-install.md` 第 2 节补上。
58
+ - `theme` 为 `null`:没传主题,默认是暗色;用户没要求暗色时改成 `theme="light"`。值是 `dynamic`
59
+ 表示主题由项目代码动态决定,不要改。
60
+ - `pendingUpdate` 为 `true`:上次升级有没合并完的文件,先按 `references/update.md` 第 3 步处理。
61
+
62
+ 命令运行不了(没有网络、找不到包)时,自己判断:有 `src/components/apex.json` 是源码模式;
63
+ `package.json` 依赖里有 `@apexhub/apex-ui-react` 是 npm 模式;都没有就是还没安装。
64
+
65
+ ## 使用组件(源码模式)
66
+
67
+ 1. 先读组件目录下的 `AGENTS.md` 和 `llms.txt`(组件索引,每个组件一段最小写法)。要用的写法索引里
68
+ 没有时,再打开该组件目录的 `llm.txt`,按属性名搜索需要的那一段,不用整篇读完。以项目里的这份
69
+ 文档和源码为准。
70
+ 2. 新做页面或往页面里加一块内容之前,读 `references/design-rules.md`:它规定了页面要符合的 Apex UI
71
+ 设计标准(按钮主次、表格对齐、筛选和分页的行为、弹窗按钮文案、加载和出错的处理)。用户不会主动
72
+ 说这些,默认按它做,做完按文末的自查清单过一遍。
73
+ 3. 写之前看一眼 `references/pitfalls.md`。Apex UI 的 API 名字像 antd 但不是 antd:`Table` 用 `data`
74
+ 不用 `dataSource`,列用 `key` 不用 `dataIndex`;没有 `Space`、`Empty`、`Badge` 等组件。不要凭对
75
+ antd 的记忆写属性。
76
+ 4. 从组件目录导入,例如 `import { Button } from '@/components/apex/button'`(按项目的路径别名或
77
+ 相对路径写)。不要从 `@apexhub/apex-ui-react` 导入,也不要安装它。
78
+ 5. `llm.txt` 里的示例已经按源码模式写好,从 `@/components/apex/<目录>` 导入,可以直接照着写。项目
79
+ 没有 `@` 别名时先按 `references/source-install.md` 第 2 节补上。
80
+ 6. 基础界面默认用这些组件,不要另装其他 UI 组件库或手写同类组件;项目里已有的、基于 Apex 的业务
81
+ 组件可以直接复用。Apex UI 里没有需要的组件时,用现有组件和 Token 在项目里拼一个业务组件
82
+ (做法见 `references/selection.md`),做完告诉用户。图标的用法见 `references/conventions.md`「图标」,不要安装图标库。
83
+ 7. 样式定制用公开 CSS Token、`className` 和 `data-slot` 选择器;不依赖内部 DOM 结构。
84
+ 8. React 19 使用普通 `ref` prop;不要使用 `React.forwardRef`。
85
+
86
+ ## 组件有问题时:改组件源码
87
+
88
+ 源码模式下组件属于项目。发现组件缺陷、样式错误或缺少需要的能力时:
89
+
90
+ 1. 先确认问题在组件里(对照 `llm.txt` 和组件源码),而不是业务用法错误。
91
+ 2. 直接修改 `src/components/apex/<组件>/` 里的源码修复,不要在业务代码里用覆盖样式、包一层 hack、
92
+ `as any`、`@ts-ignore` 或复制一份组件来绕过。
93
+ 3. 改动保持最小,只动相关组件。`core/`、`_overlay/`、`_headless/`、`_tags/`、`_namespace/`、
94
+ `utils/` 是共享底层代码,很多组件都在用:默认不动,确认问题就在这里才改,改完把用到它的其他
95
+ 组件也检查一遍。
96
+ 4. 保持键盘交互、焦点管理和无障碍行为;`data-slot` 是对外约定,尽量不改名、不删除。
97
+ 5. 不手改 `theme/*.css`(生成文件);主题覆盖写在单独的 CSS 文件里,放在 `global.css` 之后。
98
+ 6. 改完运行项目的构建命令(一般是 `npm run build`,包含类型检查;有测试就跑测试),再打开页面确认问题确实好了。
99
+ 7. **记录这次修改**:在组件目录的 `CHANGES.md`(`src/components/apex/CHANGES.md`,没有就新建)末尾
100
+ 加一条,格式如下。以后升级组件库和把修复反馈给 Apex UI 都靠它。
101
+
102
+ ```markdown
103
+ ## 2026-01-31 Select:选项文字过长时不换行
104
+ - 文件:select/select.css
105
+ - 原因:长选项把下拉框撑出屏幕
106
+ - 改动:选项文字超出时显示省略号
107
+ ```
108
+
109
+ 8. 用大白话告诉用户哪里有问题、已经修好了;文件名一句带过即可。
110
+ 9. 保留 `apex.json`:它记录原始文件 hash。`npx @apexhub/apex-ui-react-source status` 会对照它列出哪些文件被
111
+ 项目改过、删过、加过。
112
+
113
+ ## 使用上报(默认关闭)
114
+
115
+ 本 Skill 默认不收集使用情况。只有使用者显式设置 `APEX_UI_USAGE_ENDPOINT` 为有效的 HTTP(S) 地址后,安装和使用上报才会启用:
116
+
117
+ - 已配置上报地址且本地开发工具开始使用本 Skill 时,执行一次
118
+ `node <本目录>/scripts/report-usage.mjs active`(只读 Agent、无命令权限或缺脚本的宿主明确跳过)。
119
+ - 启用后只生成匿名客户端 ID(`~/.apex-ui/client-id`)并上报安装版本、日期,不上报问题、代码、项目路径、机器名或身份信息。
120
+ - 不设置 `APEX_UI_USAGE_ENDPOINT` 即保持关闭;已启用时可设置 `APEX_UI_TELEMETRY_DISABLED=1` 或在
121
+ `~/.apex-ui/usage-state.json` 中写 `{"enabled": false}`。CI 环境自动关闭(包括 GitLab CI)。
122
+ - 网络等待约 1 秒,失败静默跳过,不影响主流程。
123
+
124
+ ## 其他任务
125
+
126
+ - 做整页(列表页、表单页、详情页、后台框架、登录页):先从 `references/pages.md` 拿骨架再改,
127
+ 界面规范见 `references/design-rules.md`。
128
+ - 组件目录和缺少组件时的处理:`references/selection.md`;跨组件写法:`references/conventions.md`。
129
+ - 主题与 Token:`references/theming.md`;常见报错:`references/troubleshooting.md`。
130
+ - 生产产物去掉 `apex-*` 前缀:`references/rewrite-prefix.md`(目前只在 npm 模式下验证过;源码模式
131
+ 需要时先告诉用户这一点)。
132
+ - 用户要求检查项目里 Apex UI 用得对不对时读 `references/audit.md`。
133
+ - 升级组件库:按 `references/update.md` 做(`npx @apexhub/apex-ui-react-source@latest update`,会保留项目
134
+ 改过的地方)。不要重新运行 `init`,也不要手动拿新版本覆盖文件。发现有新版本时只用一句话提醒
135
+ 用户,由用户决定升不升。
@@ -0,0 +1,78 @@
1
+ {
2
+ "skill_name": "apex-ui",
3
+ "evals": [
4
+ {
5
+ "id": 1,
6
+ "start": "空文件夹,已运行 npx @apexhub/apex-ui-skill",
7
+ "prompt": "请帮我在当前文件夹里用 Apex UI 搭好前端项目,用亮色主题和中文,做一个带按钮的示例页面,启动后把可以打开的地址发给我。我不是开发人员。",
8
+ "expectations": [
9
+ "项目建在当前文件夹,不在子文件夹",
10
+ "存在 src/components/apex.json,package.json 里没有 @apexhub/apex-ui-react",
11
+ "入口引入了 global.css,并包了 theme=\"light\" 且传了中文 locale 的 ApexProvider",
12
+ "npm run build 通过",
13
+ "回复里有可以点击的本地地址,没有命令输出和报错堆栈",
14
+ "没有向用户提技术问题"
15
+ ]
16
+ },
17
+ {
18
+ "id": 2,
19
+ "start": "已按源码模式装好的 Vite 项目",
20
+ "prompt": "做一个用户列表页:上面可以按姓名搜索,中间是表格,点“编辑”弹出修改窗口。",
21
+ "expectations": [
22
+ "Table 使用 data 属性,没有 dataSource 和 dataIndex",
23
+ "所有组件从 @/components/apex/ 下的目录导入",
24
+ "没有 as any 和 @ts-ignore",
25
+ "package.json 没有新增任何 UI 组件库或图标库",
26
+ "npm run build 通过",
27
+ "回复用大白话说明做了什么,并给出页面地址"
28
+ ]
29
+ },
30
+ {
31
+ "id": 3,
32
+ "start": "已按源码模式装好的项目,页面上有一个选项文字很长的 Select",
33
+ "prompt": "下拉框里的选项文字太长,把页面撑开了,帮我修一下。",
34
+ "expectations": [
35
+ "修改发生在 src/components/apex/select/ 里,而不是在业务代码里覆盖样式",
36
+ "src/components/apex/CHANGES.md 新增一条,包含日期、组件、文件、原因、改动",
37
+ "没有修改 theme/ 下的 css",
38
+ "npm run build 通过",
39
+ "回复里文件名只一句带过"
40
+ ]
41
+ },
42
+ {
43
+ "id": 4,
44
+ "start": "已按源码模式装好的项目",
45
+ "prompt": "在订单详情页加一个时间轴,显示下单、付款、发货、签收四步。",
46
+ "expectations": [
47
+ "没有从 Apex 组件目录导入不存在的 Timeline",
48
+ "新组件放在 src/components/apex/ 之外",
49
+ "样式里的颜色和间距使用 var(--apex-*)",
50
+ "没有安装第三方 UI 组件库",
51
+ "回复里告诉用户这个组件是在项目里拼的"
52
+ ]
53
+ },
54
+ {
55
+ "id": 5,
56
+ "start": "按旧版本源码模式安装的项目,改过一个组件文件且新版本也改了同一处,CHANGES.md 有对应记录",
57
+ "prompt": "把 Apex UI 升级到最新版本。",
58
+ "expectations": [
59
+ "升级前有存档(git 提交或 .apex-backup/)",
60
+ "运行的是 npx @apexhub/apex-ui-react-source@latest update,没有重新运行 init",
61
+ "冲突文件里项目原来的修改仍然生效",
62
+ "升级结束后 .apex-update/ 已删除",
63
+ "CHANGES.md 末尾新增一条升级记录",
64
+ "npm run build 通过"
65
+ ]
66
+ },
67
+ {
68
+ "id": 6,
69
+ "start": "已按源码模式装好的项目,开发服务器在运行,首页按钮文字溢出",
70
+ "prompt": "这里不对。",
71
+ "expectations": [
72
+ "先打开页面查看实际效果,再修改代码",
73
+ "看不出问题在哪时,问的是页面上哪里不对,而不是技术问题",
74
+ "修改后再次打开页面确认"
75
+ ]
76
+ }
77
+ ]
78
+ }