@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.
@@ -0,0 +1,111 @@
1
+ # 组件目录与选型
2
+
3
+ > **本文件职责**:有哪些组件(去哪查)、用哪个(选型)、以及某组件不存在时怎么办。
4
+ > 单组件的具体 props 不在这里——以对应组件的 `llm.txt` 为准。
5
+
6
+ ## 有哪些组件
7
+
8
+ 源码模式:读组件目录下的 `llms.txt`,里面是当前版本的全部组件和最小写法。npm 模式:读随包的
9
+ `llms.txt`。`icon/`、`icons/`、`clear/` 三个目录没有 `llm.txt`,用法直接看目录里的 `index.ts`。
10
+ Apex UI 里没有的常见组件见 `pitfalls.md`。
11
+
12
+ ## 组件不存在时怎么办
13
+
14
+ 先确认真的没有:很多需求可以用现有组件直接组合出来(例如“搜索框”是 `Input` 加图标,“卡片列表”是
15
+ `Card` 加 `Grid`),这种情况直接组合,不算缺组件。
16
+
17
+ ### 源码模式(默认):在项目里拼一个业务组件
18
+
19
+ 不要停下来等用户决定,也不要引第三方 UI 库。直接做:
20
+
21
+ 1. 放在组件目录**外面**,例如 `src/components/<组件名>/`。`src/components/apex/` 只放 Apex UI 自己的
22
+ 组件,以后升级时不会和它混在一起。
23
+ 2. 尽量用现有 Apex 组件组合;确实需要自己写样式时,颜色、间距、圆角、字号一律用 Apex 的 CSS Token
24
+ (`var(--apex-*)`,见 `theming.md`),不写死数值,这样亮色、暗色主题都能跟着变。
25
+ 3. 交互类组件(浮层、下拉、可聚焦的控件)优先基于项目里已有的 `radix-ui` 基础件,保证键盘和无障碍
26
+ 可用。
27
+ 4. 做完用大白话告诉用户一句,例如“Apex UI 里没有时间轴组件,我用现有组件给你拼了一个,放在项目里,
28
+ 以后可以继续改”。
29
+ 5. 这个组件别的项目多半也用得上时,在 `src/components/apex/CHANGES.md` 记一条“缺少组件:{组件名},
30
+ 已在项目里实现于 {路径}”,方便以后反馈给 Apex UI。
31
+
32
+ ### npm 模式:先停下来
33
+
34
+ npm 模式下表里 / `llms.txt` 里都没有的组件,**默认先停下来、不要自行实现**:
35
+
36
+ - 通用、可复用、别的项目也会用到:直接告诉用户“组件库暂时没有这个组件,需要反馈 Apex UI”;
37
+ 同时写清需要的组件、使用场景和最基本的验收要求。
38
+ - 只服务当前业务:直接告诉用户“组件库没有,需要做成项目自己的业务组件”,等待用户确认后再实现。
39
+
40
+ 不要只说“组件不存在,请决定下一步”。按下面格式回答:
41
+
42
+ ```text
43
+ Apex UI 现在没有 {组件名}。
44
+ 这个能力属于通用基础组件 / 当前项目专用功能。
45
+ 下一步:反馈 Apex UI 补充该组件 / 确认后在项目里实现业务组件。
46
+ ```
47
+
48
+ 用户确认要在项目里实现后,做法同上面源码模式的第 2、3 条。
49
+
50
+ 两种模式下都**不要假装该组件已存在,不要默认引第三方 UI 库**。
51
+
52
+ ## 选型:用哪个组件
53
+
54
+ 不确定选哪个时看这里,定下来后再读对应组件 `llm.txt` 取 API。选定之后怎么用才符合设计标准,见
55
+ `design-rules.md`。每个组件 `llm.txt` 的「何时使用」
56
+ 段落有更细的边界。
57
+
58
+ ## 单选 / 多选 / 层级选择
59
+
60
+ - `Select`:平铺选项的单选 / 多选。
61
+ - `Cascader`:**层级联动**选择,逐级展开(省 → 市 → 区)。
62
+ - `TreeSelect`:从**树**里选,可选父节点、可勾选子树。
63
+
64
+ - `Tree`:直接在页面上展示和勾选父子层级数据。
65
+ - `Checkbox` 可以同时选多个;`Radio` 几个里只能选一个;`Switch` 只用于开和关。
66
+
67
+ 判断:选项是简单列表 → Select;有父子层级且逐级选 → Cascader;任意树形结构里选 → TreeSelect。
68
+
69
+ ## 浮层 / 弹出
70
+
71
+ - `Modal`:居中模态,打断式确认 / 表单。
72
+ - `Drawer`:从边缘滑出,承载较多内容 / 侧边表单,不完全打断。
73
+ - `Popover`:轻量浮层,挂在触发元素旁,放少量富内容。
74
+ - `Tooltip`:纯文字提示,悬停即现。只放一句短话;要放标题、列表、链接或按钮时用 `Popover`。
75
+ - `Dropdown`:触发出一组**操作菜单**。选值用 `Select`,不用 `Dropdown`。
76
+
77
+ 判断:短确认或几个字段的表单 → Modal;内容多、要保留后面的页面作对照 → Drawer;只是补充说明 →
78
+ Tooltip 或 Popover。
79
+
80
+ ## 反馈
81
+
82
+ - `message`:一过性轻提示(保存成功),自动消失,无需用户操作。
83
+ - `notification`:带标题 / 描述的通知,停留更久、可含操作,常用于异步结果。
84
+ - `Alert`:**常驻在页面布局里**的提示条(如表单顶部的警告),不是浮层。
85
+ - `Progress`:有明确百分比的任务进度。
86
+ - `Spin`:加载中状态。`Skeleton`:内容加载前的占位骨架。
87
+
88
+ ## 导航
89
+
90
+ - `Menu`:本库的 Menu 是**双栏 master→detail 导航**(左栏分区 + 右栏子菜单)。需要别的菜单形态前
91
+ 先读 `menu/llm.txt` 确认是否支持。
92
+ - `Tabs`:同层内容切换。`Steps`:分步流程。`Breadcrumb`:路径层级。`Pagination`:翻页。
93
+
94
+ ## 布局与间距
95
+
96
+ - `Layout`:页面骨架(Header / Sider / Content / Footer)。
97
+ - `Grid`(`Row` / `Col`):栅格布局。
98
+ - 没有 `Space` 组件。多个元素之间要间距时,用 flex / grid 容器加 `gap`(值用 `var(--apex-*)` 间距
99
+ Token),或用 `Grid`。
100
+
101
+ ## 输入
102
+
103
+ - `Input`:单行文字;多行用 `type="textarea"`。电话、编号这类可能以 0 开头的也用它。
104
+ - `InputNumber`:数量、金额、比例等真正的数值。
105
+ - `AutoComplete`:自由输入,同时给出建议。
106
+ - `DatePicker` / `RangePicker`:单个日期 / 日期范围。
107
+
108
+ ## 状态与标识
109
+
110
+ - `Tag`:分类、属性和业务状态,都要带文字。
111
+ - `Avatar` / `AvatarGroup`:一个人 / 多个人并排。
@@ -0,0 +1,51 @@
1
+ # npm 模式:安装、Provider 与排错
2
+
3
+ > **本文件只用于 npm 模式**(项目依赖 `@apexhub/apex-ui-react`,或用户明确要求 npm 包)。默认的源码模式见
4
+ > `source-install.md`。
5
+ >
6
+ > **本文件职责**:安装、引入样式、ApexProvider(主题 / locale / 根作用域)、中英文 locale、
7
+ > 微前端接入。组件用法查对应组件的 `llm.txt`;报错排查见 `troubleshooting.md`。
8
+
9
+ ## 安装
10
+
11
+ ```bash
12
+ pnpm add @apexhub/apex-ui-react dayjs
13
+ ```
14
+
15
+ Peer 依赖:`react >=19`、`react-dom >=19`、`dayjs`。Apex UI 依赖 React 19 的新特性(如 ref 作为
16
+ 普通 prop),**不支持 React 18**。
17
+
18
+ 安装命令报找不到包时,说明 npm 包还没有公开发布:告诉用户这一点,并建议改用源码模式
19
+ (`source-install.md`),不要换成别的包。
20
+
21
+ ## 入口样式(必做且仅一次)
22
+
23
+ ```tsx
24
+ // main.tsx / App.tsx —— 全局只引一次
25
+ import '@apexhub/apex-ui-react/style.css'
26
+ ```
27
+
28
+ `style.css` 包含设计 token(CSS 变量)+ 全部组件样式 + 滚动条。漏引会导致组件无样式、
29
+ `var(--apex-*)` 全部回退、布局错乱。
30
+
31
+ ## Provider
32
+
33
+ 全局需要**一个 `ApexProvider`** 包在应用 / 微前端子应用最外层,它统一接管主题、中英文 locale,
34
+ 并提供样式作用域 `.apex-provider`。**它的 props、根布局写法、locale 导入方式以
35
+ `apex-provider/llm.txt` 为准**,这里不重复。环境层面记住三点:
36
+
37
+ - 中文项目必须给它传中文 locale,否则内置文案(分页 / 日期 / 表单校验等)回退**英文**。
38
+ - 主题支持 `'light' | 'dark'`,不传默认 **`dark`**。亮色产品必须显式传 `theme="light"`;细节见
39
+ `theming.md`。
40
+ - 读取当前配置用 `useConfig` Hook(从包根导出)。
41
+
42
+ ## 微前端(wujie / qiankun 等)
43
+
44
+ 子应用里的浮层组件可能 Portal 到宿主 `document.body`,在 Shadow DOM、滚动容器或样式隔离场景中
45
+ 需要逐组件确认挂载与定位行为。处理原则:
46
+
47
+ - **不要给 `ApexProvider` 编造 `getPopupContainer`**;当前 Provider 只负责 theme / locale 与根作用域。
48
+ - 先读具体浮层组件的 `llm.txt`。只有该组件明确提供 `getPopupContainer` / `getContainer` 时,才按其
49
+ API 把 Portal 挂到合适容器;没有公开该能力时,不要套用别的组件 API。
50
+ - token 隔离仍写在 `.apex-provider` 作用域里(见 `theming.md`),避免污染宿主。
51
+ - 主、子应用要各自的 class 前缀时,在各自的 Vite 配置里接入前缀重写插件,见 `rewrite-prefix.md`。
@@ -0,0 +1,146 @@
1
+ # 源码模式安装与接入
2
+
3
+ > **本文件职责**:首次以源码模式接入 Apex UI:准备环境、没有项目时新建项目、运行 `init`、入口接入、
4
+ > 启动页面给用户看、汇报。日常使用和修改组件见 `SKILL.md`;npm 模式见 `setup.md`。
5
+
6
+ 用户很可能不是开发人员。整个过程按 `SKILL.md`「和用户沟通」一节做:技术选择自己定,用大白话
7
+ 说明,不要让用户回答技术问题。用户已经说了要安装或接入 Apex UI,就直接做,不用再问一遍。
8
+
9
+ ## 1. 准备环境
10
+
11
+ 1. 运行 `node -v`。没有 Node.js 或版本低于 20 时,直接帮用户装好最新的 LTS 版本,装之前用一句
12
+ 大白话说明(例如“你的电脑还缺一个运行前端项目必需的工具 Node.js,我现在帮你装上”):
13
+ - Windows:`winget install OpenJS.NodeJS.LTS`
14
+ - macOS:有 Homebrew 用 `brew install node`;没有就让用户从 <https://nodejs.org> 下载安装包,
15
+ 一路点“继续”
16
+ - Linux:用系统的包管理器或 nvm
17
+
18
+ 装完后重新运行 `node -v` 确认。还是找不到命令,多半是当前终端没有读到新的 PATH:Windows 下直接用
19
+ 完整路径 `"C:\Program Files\nodejs\node.exe" -v` 确认,后面的命令把 `C:\Program Files\nodejs`
20
+ 加到本次会话的 PATH 前面再运行;仍然不行就请用户重启 AI 工具后说一句“继续”。装不上时(没有权限、
21
+ 没有网络),把原因和需要用户做的一件事用大白话说清楚,不要贴一堆报错。
22
+ 2. `npx` 下载不了包时,先确认是不是当前 AI 工具禁止了联网;是的话告诉用户需要允许联网,再重试。
23
+
24
+ ## 2. 确认有项目;没有就新建
25
+
26
+ 看当前目录有没有 `package.json`:
27
+
28
+ - **有**,并且依赖里是 React 19 或更新 → 直接到第 3 步。
29
+ - **有**,是 Vue 3 项目 → 这个 skill 目前只管 React。停下来,用大白话告诉用户:Vue 项目可以直接
30
+ 安装 `@apexhub/apex-ui-vue` 使用,用法见 Apex UI 官网;想让 AI 全程代劳的话,另找一个空文件夹新建 React
31
+ 项目。不要在 Vue 项目里安装 React 版组件。
32
+ - **有**,但 React 低于 19,或是纯 HTML 等其他项目 → 停下来,用大白话告诉用户:Apex UI 的 React 版
33
+ 需要 React 19,这个项目用不了,并给出两个选择(另找一个空文件夹新建项目,或请开发人员升级
34
+ React)。不要自己升级 React 或改掉项目的框架。
35
+ - **没有** → 新建一个 React 项目,建在**当前目录**里(不要建在子文件夹里,否则已经装好的 skill 和
36
+ `AGENTS.md` 规则就不在项目里了)。动手前用一句大白话告诉用户,例如:
37
+
38
+ > 这个文件夹里还没有项目,我先帮你建一个 React 网页项目,再把 Apex UI 组件装进去,大约需要
39
+ > 一两分钟。
40
+
41
+ 当前目录里已经有 `AGENTS.md`、`.agents/` 等文件,`create-vite` 不能直接建在非空目录里,所以先建到
42
+ 一个临时子文件夹,再把里面的内容全部搬出来:
43
+
44
+ ```bash
45
+ npm create vite@latest apex-new-project -- --template react-ts --no-interactive
46
+ ```
47
+
48
+ 然后:
49
+ 1. 把 `apex-new-project/` 里的**所有**文件和文件夹(包括 `.gitignore` 这类点开头的)移到当前目录。
50
+ 当前目录已有同名文件(常见的是 `README.md`)时保留用户原来的,不覆盖。
51
+ 2. 删除空的 `apex-new-project/`。
52
+ 3. 把 `package.json` 的 `name` 改成当前文件夹名(小写,空格换成 `-`)。
53
+ 4. 运行 `npm install`。
54
+ 5. 配好 `@` 路径别名,后面所有代码都用 `@/components/apex/...` 导入:
55
+ - `vite.config.ts` 的 `defineConfig` 里加
56
+ `resolve: { alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) } }`,
57
+ 并在文件顶部加 `import { fileURLToPath, URL } from 'node:url'`。
58
+ - `tsconfig.app.json` 的 `compilerOptions` 里加 `"paths": { "@/*": ["./src/*"] }`。
59
+ 6. 当前目录不是 git 仓库且电脑上有 git 时,运行 `git init` 并提交一次,作为“存档点”。没有 git 就
60
+ 跳过,不要为此去装 git 或问用户。
61
+
62
+ 已有项目且是 git 仓库时,如果有没提交的改动,不用让用户处理,继续安装即可;汇报时说明新增了哪些
63
+ 文件。
64
+
65
+ 已有项目没有 `@` 别名时(`tsconfig` 里找不到 `"@/*"`),按上面第 5 步补上,不用问用户。项目用的是
66
+ 别的别名(如 `~/`)时沿用项目的,导入路径相应替换。
67
+
68
+ ## 3. 运行 init
69
+
70
+ 在项目根目录运行:
71
+
72
+ ```bash
73
+ npx @apexhub/apex-ui-react-source init
74
+ ```
75
+
76
+ `init` 会:复制源码到 `src/components/apex/`(`--dir` 可改)、按锁文件识别包管理器并安装写死版本的
77
+ 依赖(`--pm pnpm|npm|yarn|bun` 可指定)、写入 `src/components/apex.json`。
78
+
79
+ `init` 遇到下面情况会停止且不改任何文件。按下表处理,能自己定的就自己定:
80
+
81
+ | 提示 | 处理 |
82
+ | --- | --- |
83
+ | `apex.json` 已存在 | 已经装过了,跳到第 4 步检查入口是否接好 |
84
+ | 目标目录已存在且非空 | 里面是用户自己的文件:改用 `--dir src/components/apex-ui`,不删除用户的文件 |
85
+ | 某依赖已是其他版本 | 只差补丁或小版本时,把这些依赖改成要求的版本后重新 `init`,汇报时说明;差了大版本时停下来,用大白话告诉用户项目里已有的某个库和 Apex UI 需要的版本不一致,改了可能影响现有页面,问是否继续 |
86
+ | 已安装 `@apexhub/apex-ui-react` | 项目在用 npm 模式。告诉用户项目已经在用另一种方式安装的 Apex UI,可以直接用;用户明确要求改成源码模式时才迁移 |
87
+ | React 低于 19 / 没装 React | 按第 2 步处理 |
88
+
89
+ ## 4. 接入入口
90
+
91
+ ### Vite
92
+
93
+ ```tsx
94
+ // src/main.tsx
95
+ import '@/components/apex/global.css'
96
+ import { ApexProvider } from '@/components/apex/apex-provider'
97
+ import zhCN from '@/components/apex/locale/zh_CN'
98
+
99
+ createRoot(document.getElementById('root')!).render(
100
+ <ApexProvider theme="light" locale={zhCN}>
101
+ <App />
102
+ </ApexProvider>,
103
+ )
104
+ ```
105
+
106
+ - `global.css` 全局只引一次,放在业务 CSS 之前。
107
+ - Provider 不传 `theme` 时默认 `dark`。用户没指定时用亮色(`theme="light"`);用户用中文交流时传
108
+ 中文 locale。
109
+ - 新建的 Vite 项目:删掉模板自带的示例内容(`src/App.tsx` 里的计数器、`src/App.css`、
110
+ `src/index.css` 里和 Apex 冲突的全局样式),换成一个用 Apex 组件的简单首页,避免用户看到的是
111
+ 模板页面。
112
+
113
+ ### Next.js App Router
114
+
115
+ - 在 `app/layout.tsx` 引入 `global.css`。
116
+ - `ApexProvider` 放在带 `'use client'` 的 `app/providers.tsx` 里,由 layout 包住 `children`。
117
+ - 组件都是客户端组件,服务端组件里可以直接 import 使用。
118
+ - 开启 `cacheComponents`(Next 16 模板默认开启)时,DatePicker 等初次渲染会读取当前时间的组件要包在
119
+ `<Suspense>` 里,否则 `next build` 预渲染会报错。
120
+
121
+ ### 微前端(Wujie 等)
122
+
123
+ - 在子应用自己的入口引入 `global.css` 并包 `ApexProvider`,不要依赖宿主的样式。
124
+ - 已验证 Wujie 1.0.29 的 Shadow 和 iframe(降级)模式。iframe 模式下 Modal / Drawer 按 Escape
125
+ 关不掉是已知问题,点关闭按钮正常。其他版本和多层嵌套未验证:照常接入,出现浮层或样式问题时告诉用户这个组合还没有验证过。
126
+
127
+ ## 5. 验证,并让用户看到页面
128
+
129
+ 1. 确认首页里至少用了一个 Apex 组件(如 `Button`)。
130
+ 2. 运行项目的类型检查和构建(如 `npm run build`),出错当场修,不要把报错丢给用户。
131
+ 3. 确认项目根目录的 `AGENTS.md`(使用 Claude Code 时还有 `CLAUDE.md`)里有「UI 组件规范(Apex UI)」
132
+ 一节;没有时重新运行 `npx @apexhub/apex-ui-skill` 写入。
133
+ 4. 启动开发服务器(如 `npm run dev`,放在后台运行,不要让它卡住对话),自己先打开页面确认组件
134
+ 样式和主题正常,再把地址给用户。当前 AI 工具没有打开网页的能力时,确认开发服务器启动成功、终端
135
+ 没有报错即可,并告诉用户页面还没有实际看过。
136
+
137
+ ## 6. 汇报(大白话)
138
+
139
+ 用几句话告诉用户,不要贴命令输出:
140
+
141
+ - 做好了什么:项目建好了(如果是新建的)、Apex UI 组件装好了。
142
+ - 在哪里看:给出可以点击的地址(如 `http://localhost:5173`)。
143
+ - 接下来怎么用:直接用一句话描述想要的页面就行,例如“做一个带搜索和表格的用户列表页”;页面哪里
144
+ 不对也直接说。
145
+
146
+ 技术细节(版本、目录、新增的依赖、改了哪些文件)放在最后,一两行带过;用户问起再展开。
@@ -0,0 +1,56 @@
1
+ # 主题与 Token 定制
2
+
3
+ Apex UI 用 CSS 变量(Token)控制颜色、间距、圆角和字号。本文按源码模式写;npm 模式下把
4
+ `global.css` 读作 `@apexhub/apex-ui-react/style.css`,其余相同。
5
+
6
+ ## 去哪里查 Token
7
+
8
+ - 全局语义变量(品牌色、文字色、背景色等):组件目录下的 `llms-theme.txt`,变量定义在
9
+ `theme/aliases.css`。
10
+ - 单个组件的变量:`src/components/apex/<组件>/tokens.txt`。
11
+
12
+ 只在调整主题或样式时才需要读这些文件;普通使用组件不用读。
13
+
14
+ ## 亮暗主题
15
+
16
+ `ApexProvider` 的 `theme` 支持 `light` 和 `dark`,**不传默认是 `dark`**。亮色应用要显式传
17
+ `theme="light"`。不要只在业务容器上写 `data-theme` 来切主题,浮层不会跟着变。
18
+
19
+ ## 覆盖 Token
20
+
21
+ 不要手改 `theme/*.css`(生成文件,升级时会被覆盖)。覆盖写在项目自己的 CSS 文件里,在入口里放在
22
+ `global.css` **之后**引入:
23
+
24
+ ```tsx
25
+ import './components/apex/global.css'
26
+ import './styles/apex-override.css'
27
+ ```
28
+
29
+ 全局换肤覆盖语义变量(名字以 `--apex-` 开头):
30
+
31
+ ```css
32
+ :root {
33
+ --apex-fill-brand-primary: var(--apex-purple-5);
34
+ }
35
+
36
+ [data-theme='dark'] {
37
+ --apex-fill-brand-primary: var(--apex-purple-7);
38
+ }
39
+ ```
40
+
41
+ 只改某一处的某个组件,用 `className` 覆盖该组件的变量(变量名查它的 `tokens.txt`):
42
+
43
+ ```css
44
+ .my-cta {
45
+ --button-fill-default: var(--apex-fill-brand-primary);
46
+ }
47
+ ```
48
+
49
+ 值尽量引用已有变量(`var(--apex-...)`),不要写死色值,否则切换亮暗主题时不会跟着变。
50
+
51
+ ## 作用域
52
+
53
+ - 微前端或需要样式隔离时,把覆盖写在 `.apex-provider` 选择器下,避免影响宿主页面。
54
+ - Modal、Select 等浮层渲染在触发元素之外:写在业务容器上的变量传不到浮层里,要用该组件 `llm.txt`
55
+ 里公开的浮层 `className` 入口,并在实际浮层上确认效果。
56
+ - 选中组件内部部件用 `[data-slot="..."]`;不要用内部 class 名,不要用 `!important`。
@@ -0,0 +1,24 @@
1
+ # 常见报错与排查
2
+
3
+ 没有特别注明的行两种模式通用。
4
+
5
+ | 现象 | 原因 | 处理 |
6
+ | --- | --- | --- |
7
+ | 组件渲染但没有样式 | 入口没引全局样式 | 源码模式在入口引入组件目录的 `global.css`;npm 模式引入 `@apexhub/apex-ui-react/style.css` |
8
+ | 覆盖的 `--apex-*` 变量没生效 | 覆盖文件在库样式之前加载,或选择器不对 | 把覆盖文件放在 `global.css`(npm 模式是 `style.css`)之后;暗色下的覆盖写在 `[data-theme='dark']` 里 |
9
+ | 想要亮色却显示暗色 | Provider 不传 `theme` 时默认 `dark` | `<ApexProvider theme="light">` |
10
+ | 内置文案(分页、日期、校验提示)是英文 | 没传 locale | 给 `ApexProvider` 传 `locale`,中文从 `locale/zh_CN` 导入 |
11
+ | 源码模式里出现 `@apexhub/apex-ui-react` 的 import | 照抄了按 npm 写的示例 | 按组件目录 `AGENTS.md` 的对照表改成组件目录,不要安装 npm 包 |
12
+ | 找不到 `dayjs`、`radix-ui` 等模块(源码模式) | 依赖被删掉或没装上 | 按 `apex.json` 的 `dependencies` 里记录的版本装回去 |
13
+ | 找不到 `.../dist/...` 模块(npm 模式) | 依赖了内部深路径 | 从 `@apexhub/apex-ui-react` 包根具名导入 |
14
+ | 引入组件库即报 dayjs 错误(npm 模式) | 缺少 peer 依赖 | 安装 `dayjs` |
15
+ | `init` 拒绝安装 | 目录非空、已装 npm 包、React 低于 19 或依赖版本冲突 | 按 `source-install.md` 第 3 步的表格处理 |
16
+ | 类型里没有某个 Props 或子组件 | 用了不存在的 API | 读对应 `llm.txt` 按真实导出名写;见 `conventions.md`「类型报错时不要用 any 压下去」 |
17
+ | `message.xxx is not a function` | 把命令式单例当成组件或用了大写导入 | 用小写的 `message` 单例直接调用 |
18
+ | 浮层位置偏移或被裁掉 | Portal 容器或滚动容器变了 | 读该浮层组件的 `llm.txt`,只用它公开的容器 API(如 `getPopupContainer`);`ApexProvider` 上没有这个配置 |
19
+ | Next.js 构建报 `new Date()` 预渲染错误 | `cacheComponents` 下 DatePicker 读取当前时间 | 把用到日期组件的部分包进 `<Suspense>` |
20
+ | 想去掉产物里的 `apex-` 前缀 | 手改 class 改不到构建产物 | 按 `rewrite-prefix.md` 接入 Vite 插件 |
21
+ | Vite 报前缀非法 | prefix 含大写、下划线或保留词 | 用小写 kebab-case,例如 `team-a` |
22
+
23
+ 表里没有的报错:先读报错指向的组件源码和 `llm.txt`。确认是组件本身的问题时,源码模式按 `SKILL.md`
24
+ 「组件有问题时」直接修。
@@ -0,0 +1,93 @@
1
+ # 升级组件库(源码模式)
2
+
3
+ 源码模式下组件是项目自己的代码,不会自动更新。升级由你来做,用户只需要说一句“升级组件库”。
4
+ 目标:拿到 Apex UI 的新版本,同时**保住项目对组件做过的每一处修改**。
5
+
6
+ npm 模式的升级见 `setup.md`(改 `@apexhub/apex-ui-react` 的版本号),不走本文。
7
+
8
+ ## 什么时候提醒用户有新版本
9
+
10
+ 每次对话最多检查一次,在你本来就要动 Apex 组件的时候顺手做:
11
+
12
+ ```bash
13
+ npm view @apexhub/apex-ui-react-source version
14
+ ```
15
+
16
+ 和 `apex.json` 的 `version` 比较。有更新的版本时,在回复末尾用一句大白话提一下,例如
17
+ “组件库有新版本了,想升级的话跟我说一声,我来处理,你之前让我改过的地方会保留。”
18
+ 不要自己直接升级;命令失败(没有网络、查不到包)就跳过,不要告诉用户。
19
+
20
+ ## 升级步骤
21
+
22
+ ### 1. 先说明,再存档
23
+
24
+ 用大白话告诉用户:要把组件更新到新版本,之前改过的地方会保留,过程中页面可能短暂打不开,出问题
25
+ 可以完整退回。然后存一份可以退回的档:
26
+
27
+ - 项目用了 git:确认没有未提交的改动(有就先提交,提交说明写“升级 Apex UI 前的存档”)。
28
+ - 没有 git:把组件目录和 `apex.json` 复制到项目根目录的 `.apex-backup/`。
29
+
30
+ ### 2. 运行升级命令
31
+
32
+ ```bash
33
+ npx @apexhub/apex-ui-react-source@latest update
34
+ ```
35
+
36
+ 一定要带 `@latest`,否则用的是本机缓存的旧版本。组件目录不在默认位置时加 `--dir <目录>`。
37
+ 想先看会发生什么、不改任何文件,加 `--dry-run`。命令对每个文件这样处理:
38
+
39
+ | 情况 | 处理 | 输出里的名字 |
40
+ | --- | --- | --- |
41
+ | 项目没改过,新版本有变化 | 换成新版本 | updated |
42
+ | 新版本新增的文件 | 加进来 | added |
43
+ | 新版本删掉的、项目没改过的文件 | 删除 | removed |
44
+ | 项目改过,新版本没动 | 保持项目的版本 | kept |
45
+ | 两边都改了,改的地方不重叠 | 自动合并 | merged |
46
+ | 两边改了同一处,或无法自动合并 | **不动项目的文件**,等你处理 | Needs a manual merge |
47
+
48
+ 依赖会跟着升到新版本要求的版本;项目自己指定了其他版本的依赖不会被改,输出里会列出来。
49
+ 显示 “already the version of this package” 说明已经是最新,告诉用户不用升级即可。
50
+
51
+ ### 3. 处理需要手动合并的文件
52
+
53
+ 输出 `Needs a manual merge` 时,项目根目录会多一个 `.apex-update/`:
54
+
55
+ - `.apex-update/new/<文件>`:新版本的内容
56
+ - `.apex-update/base/<文件>`:升级前的原始内容(拿得到时才有)
57
+ - 组件目录里的 `<文件>`:项目当前的内容(带着项目的修改)
58
+
59
+ 逐个文件处理:
60
+
61
+ 1. 在 `CHANGES.md` 里找到这个文件对应的记录,弄清项目当初为什么改、改了什么。
62
+ 2. 看新版本是不是已经解决了同一个问题。解决了:直接用新版本的内容,并在 `CHANGES.md` 那条记录
63
+ 后面加一行“- 状态:x.y.z 已包含,升级时改用官方实现”。
64
+ 3. 没解决:以新版本的内容为底,把项目的修改重新做上去,写回组件目录。不要反过来把新版本的改动
65
+ 往旧文件上拼,那样容易漏掉新版本的修复。
66
+ 4. 原因是 “the project deleted this file” 或 “Apex UI removed this file” 时,按 `CHANGES.md` 判断
67
+ 项目是否还需要它;判断不了才问用户,问的时候说清楚这个文件管页面上的什么。
68
+
69
+ 全部处理完后删除 `.apex-update/`。自动合并(merged)的文件也要打开看一眼,确认项目的修改还在。
70
+
71
+ ### 4. 验证
72
+
73
+ 1. 运行项目的构建命令(一般是 `npm run build`),有测试就跑测试。
74
+ 2. 启动开发服务器,打开页面检查:重点看 `CHANGES.md` 里记过的每一处修改还在不在。
75
+ 3. 报错先自己修。常见的是新版本改了某个组件的 Props,业务代码要跟着改:读该组件新的 `llm.txt`。
76
+
77
+ 实在修不好就退回:git 项目回到第 1 步的存档提交;没有 git 的把 `.apex-backup/` 里的内容复制回去。
78
+ 退回后告诉用户这次没升级成功、卡在哪里,页面和升级前一样。
79
+
80
+ ### 5. 收尾
81
+
82
+ 1. 在 `CHANGES.md` 末尾加一条记录:
83
+
84
+ ```markdown
85
+ ## 2026-03-01 升级 0.3.0 → 0.4.0
86
+ - 保留的修改:Select 长选项省略号、Table 表头吸顶
87
+ - 改用官方实现:Modal 关闭按钮位置(0.4.0 已修)
88
+ - 跟着调整的业务代码:订单页的 DatePicker 写法
89
+ ```
90
+
91
+ 2. 删除 `.apex-backup/`(如果建过);git 项目把升级提交一次。
92
+ 3. 用大白话告诉用户:已经升级到哪个版本、之前的修改都还在(有改用官方实现的说一下)、页面地址。
93
+ 不要贴文件清单。
@@ -0,0 +1,27 @@
1
+ ## UI 组件规范(Apex UI)
2
+
3
+ 本项目默认以**源码模式**使用 Apex UI:组件源码在 `src/components/apex/`(以 `src/components/apex.json`
4
+ 的 `dir` 为准),属于本项目代码。还没有这个目录时,先用 `apex-ui` skill 按源码模式安装(当前目录
5
+ 还没有项目时,skill 会先新建一个 React 项目)。
6
+
7
+ - 写界面时默认使用这些组件;不要另装其他 UI 组件库,也不要手写已有的同类组件。已有的、基于 Apex
8
+ 的业务组件可以直接复用。
9
+ - 从组件目录导入(如 `@/components/apex/button`);不要安装或导入 `@apexhub/apex-ui-react`。
10
+ - 写或改组件用法前,先读组件目录下的 `AGENTS.md` 和对应组件的 `llm.txt`,以项目里的源码为准,
11
+ 不编造 Props。
12
+ - Apex UI 的 API 名字像 antd 但不是 antd,不要凭对 antd 的记忆写属性(例如 `Table` 用 `data`,
13
+ 不是 `dataSource`);属性以 `llm.txt` 为准。
14
+ - **组件有问题就改组件**:确认是组件的缺陷、样式错误或缺少能力后,直接修改
15
+ `src/components/apex/` 里对应组件的源码修复;不要在业务代码里用覆盖样式、包装 hack、`as any`、
16
+ `@ts-ignore` 或复制组件来绕过。改动保持最小,改完运行构建(如 `npm run build`),并在
17
+ `src/components/apex/CHANGES.md` 末尾记一条(日期、组件、文件、原因、改动)。
18
+ - **缺组件就在项目里拼一个**:Apex UI 里没有的组件,用现有组件和 `var(--apex-*)` Token 做成业务组件,
19
+ 放在 `src/components/apex/` 外面,做完告诉用户;不要引第三方 UI 库。
20
+ - `core/`、`_overlay/`、`_headless/` 等共享底层代码默认不动,确认问题在这里才改;保持键盘、焦点和
21
+ 无障碍行为;`data-slot` 是对外约定,尽量不改名、不删除。
22
+ - 主题覆盖写在单独的 CSS 文件里,放在 `global.css` 之后;不要手改 `theme/*.css`。
23
+ - **升级组件库**:用 `apex-ui` skill 的升级流程(`npx @apexhub/apex-ui-react-source@latest update`,会保留
24
+ 项目改过的地方);不要重新运行 `init`,也不要手动拿新版本覆盖 `src/components/apex/`。
25
+ - **用户可能不是开发人员**:用大白话沟通;目录、依赖版本这类技术选择自己定,做完再说明;只有要删除
26
+ 或覆盖用户已有的文件、或需求本身不清楚时才先问。改完页面后确认开发服务器在运行,自己先打开页面检查,
27
+ 再把可以点击的地址给用户。
@@ -0,0 +1,27 @@
1
+ ## UI 组件规范(Apex UI)
2
+
3
+ 本项目默认以**源码模式**使用 Apex UI:组件源码在 `src/components/apex/`(以 `src/components/apex.json`
4
+ 的 `dir` 为准),属于本项目代码。还没有这个目录时,先用 `apex-ui` skill 按源码模式安装(当前目录
5
+ 还没有项目时,skill 会先新建一个 React 项目)。
6
+
7
+ - 写界面时默认使用这些组件;不要另装其他 UI 组件库,也不要手写已有的同类组件。已有的、基于 Apex
8
+ 的业务组件可以直接复用。
9
+ - 从组件目录导入(如 `@/components/apex/button`);不要安装或导入 `@apexhub/apex-ui-react`。
10
+ - 写或改组件用法前,先读组件目录下的 `AGENTS.md` 和对应组件的 `llm.txt`,以项目里的源码为准,
11
+ 不编造 Props。
12
+ - Apex UI 的 API 名字像 antd 但不是 antd,不要凭对 antd 的记忆写属性(例如 `Table` 用 `data`,
13
+ 不是 `dataSource`);属性以 `llm.txt` 为准。
14
+ - **组件有问题就改组件**:确认是组件的缺陷、样式错误或缺少能力后,直接修改
15
+ `src/components/apex/` 里对应组件的源码修复;不要在业务代码里用覆盖样式、包装 hack、`as any`、
16
+ `@ts-ignore` 或复制组件来绕过。改动保持最小,改完运行构建(如 `npm run build`),并在
17
+ `src/components/apex/CHANGES.md` 末尾记一条(日期、组件、文件、原因、改动)。
18
+ - **缺组件就在项目里拼一个**:Apex UI 里没有的组件,用现有组件和 `var(--apex-*)` Token 做成业务组件,
19
+ 放在 `src/components/apex/` 外面,做完告诉用户;不要引第三方 UI 库。
20
+ - `core/`、`_overlay/`、`_headless/` 等共享底层代码默认不动,确认问题在这里才改;保持键盘、焦点和
21
+ 无障碍行为;`data-slot` 是对外约定,尽量不改名、不删除。
22
+ - 主题覆盖写在单独的 CSS 文件里,放在 `global.css` 之后;不要手改 `theme/*.css`。
23
+ - **升级组件库**:用 `apex-ui` skill 的升级流程(`npx @apexhub/apex-ui-react-source@latest update`,会保留
24
+ 项目改过的地方);不要重新运行 `init`,也不要手动拿新版本覆盖 `src/components/apex/`。
25
+ - **用户可能不是开发人员**:用大白话沟通;目录、依赖版本这类技术选择自己定,做完再说明;只有要删除
26
+ 或覆盖用户已有的文件、或需求本身不清楚时才先问。改完页面后确认开发服务器在运行,自己先打开页面检查,
27
+ 再把可以点击的地址给用户。