@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,471 @@
1
+ # Apex UI 消费方项目审计
2
+
3
+ > 本文件只服务 `/apex-ui audit`:先通过标准版门禁,再只读审计并生成可直接行动的报告;用户明确确认后才修改项目代码。
4
+
5
+ ## 目录
6
+
7
+ - 标准版门禁
8
+ - 不可越过的边界与事实来源
9
+ - 阶段一:只读审计
10
+ - 检查完成的硬门槛
11
+ - 处理结论、风险与证据标准
12
+ - 审计报告规范与模板
13
+ - 阶段二:确认后修改
14
+
15
+ ## 标准版门禁
16
+
17
+ 标准版不写死版本号:每次新审计先从 registry **`latest`** 解析精确 semver,记为 `STANDARD_VERSION`;
18
+ 不得改用 `next`、其他已发布版本或印象中的旧号。该精确版本在本次报告及其后续修改中固定;
19
+ 只有开始新审计时重新解析 `latest`。
20
+ 旧 skill 中的固定版本、示例、历史报告、对话记忆和本地组件库仓库版本都不能作为本次 `latest` 的证据。
21
+ **不得仅因已安装版本不同于 `latest` 就要求降级**;先按下方规则比较版本和核对查询来源。
22
+
23
+ ### 0. 解析标准版
24
+
25
+ 在项目根执行,保留 npm 对项目 `.npmrc`、用户配置和环境变量的正常合并:
26
+
27
+ ```bash
28
+ npm config get @apex-ui:registry
29
+ npm view @apexhub/apex-ui-react@latest version --json --prefer-online
30
+ ```
31
+
32
+ 按 JSON 解析 stdout,结果须为单个稳定版字符串 `x.y.z`(即 `STANDARD_VERSION`);不要把 stderr 的
33
+ npm 警告当作版本。`--prefer-online` 强制检查缓存是否过期;不能只读已有缓存后声称实时查询成功。
34
+ 记录实际执行命令、成功查询的 stdout、查询时间与时区,以及有效 registry(输出前去除 URL 中的凭据)。
35
+ 若 scope registry 为 `undefined`,再用 `npm config get registry` 确认默认来源;不得擅自切换 registry。
36
+ 报告写「标准版来源:{脱敏 registry};latest → {版本};查询时间:{含时区的时间}」。
37
+ 没有本次成功查询的输出,不得填写“要求版本”或给出带猜测版本号的安装命令。
38
+ 不要默认传 `--userconfig .npmrc`,它会替换用户配置来源,导致用户配置中的认证失效。
39
+ 失败、无 `latest`、非稳定版或无效 JSON:标“无法继续检查”并停止;提示检查 registry / `.npmrc`
40
+ 与网络。错误信息须去除凭据,不输出配置文件中的 Token。
41
+
42
+ ### 1. 核对消费方安装
43
+
44
+ 对每个实际消费 Apex UI 的应用或 workspace:
45
+
46
+ 1. 同时检查 `package.json`、锁文件和 `node_modules/@apexhub/apex-ui-react/package.json`。
47
+ 2. `package.json` 的有效依赖范围须允许 `STANDARD_VERSION`,锁文件与实际解析版本须精确为
48
+ `STANDARD_VERSION`;不要只看其中一处。允许 `^1.0.0` 解析到标准版 `1.1.0`,不要求范围起点
49
+ 等于标准版;catalog、overrides 等间接声明须先解析有效配置。
50
+ 3. 版本不一致时先区分原因,稳定版本按 semver 数值比较(如 `1.0.10 > 1.0.2 > 0.4.47`),
51
+ 不能按字符串排序,也不能把所有“不相等”都变成安装指令:
52
+ - 声明允许标准版,锁定和实际版本均为标准版:通过,继续只读审计,不要求重复安装。
53
+ - 任一锁定或实际稳定版本高于 `STANDARD_VERSION`:先核对查询是否在正确项目根执行、有效
54
+ registry 是否对应项目依赖来源、是否读取了本次成功查询结果。重新实时查询一次;仍较低时标
55
+ “无法继续检查:registry latest 低于项目版本”,保留现有依赖,下一步是核对 registry / 发布标签。
56
+ 不得输出降级命令,不得自行改 dist-tag,也不得直接把最高已发布版本当作标准版。
57
+ - 锁定与实际版本不一致,或有效声明不允许实际版本:说明具体不一致,先核对当前 workspace、
58
+ overrides / catalog 和安装状态,不把问题归因为必须换到一个更低版本。
59
+ - 实际版本为预发布版、workspace / file / link 或本地 fork:说明不属于本流程的标准稳定版,
60
+ 不自动替换为稳定版;需先明确对应版本的审计范围。
61
+ - 确认未安装,或锁定与实际稳定版本一致且低于本次标准版:停止,并让用户在对应 workspace
62
+ 安装(替换为本次成功查询出的精确号):
63
+
64
+ ```bash
65
+ pnpm add @apexhub/apex-ui-react@STANDARD_VERSION
66
+ ```
67
+
68
+ 4. 用户确认安装后再核对上述三处;门禁未通过前不得继续审计或改用其他版本文档。
69
+ 5. 安装失败时保留错误,提示处理 registry、权限或依赖冲突;不得绕过门禁。
70
+
71
+ Monorepo 只要求实际消费方 workspace 对齐 `STANDARD_VERSION`,勿向无关 workspace 加依赖。
72
+
73
+ 通过后在当前对话的审计记录中保留查询时间、精确版本、各消费方实际包路径,以及相关 manifest、
74
+ 锁文件、补丁配置、随包文档和候选代码的内容摘要或哈希。记录用于阶段二复核,不在项目内生成文件。
75
+ 实际包按消费方模块解析位置定位,允许合法的 workspace 提升安装,不能仅因应用下没有物理目录判未安装。
76
+
77
+ ## 不可越过的边界与事实来源
78
+
79
+ ### 边界
80
+
81
+ 1. AI 在阶段一禁止修改、创建或删除项目文件,禁止自行安装、升级或降级依赖,禁止运行会改写文件的
82
+ formatter、fix、迁移或生成命令。门禁未通过时按具体原因说明下一步并停止,不能一律要求安装。
83
+ 2. 阶段一报告完成后必须停止。只有用户明确回复「全部修改」或指定 P 类编号,才能进入阶段二。
84
+ 3. 不把 `.apex-*`、`[data-slot]`、`!important`、wrapper 或其他 UI 库一律视为错误;结合上下文判断。
85
+ 4. 不修改 `node_modules` 或 Apex UI 源码,不回退、覆盖用户已有修改,不扩大用户确认的修改范围。
86
+ 5. 当前标准版没有某项业务能力,不等于组件库有问题。组件库明确不支持、决定不实现或只服务当前
87
+ 项目的行为,按业务定制处理,不进入报告。
88
+ 6. 只有本次实际取得的证据才能标为“已验证”;没有执行的检查明确标为未验证。
89
+
90
+ ### 事实来源优先级
91
+
92
+ 通过门禁后按以下顺序建立基线:
93
+
94
+ 1. 项目规范:`AGENTS.md`、`CLAUDE.md`、README、各 workspace 的 `package.json`。
95
+ 2. 锁文件及实际安装的 `@apexhub/apex-ui-react@STANDARD_VERSION`。
96
+ 3. `node_modules/@apexhub/apex-ui-react/llms.txt`。
97
+ 4. `llms.txt` 链接到的 `dist/llm/<目录名>.txt` 组件文档。
98
+ 5. 文档无法解释类型或行为时,再查当前安装版本的 `.d.ts` 和可定位的实现产物。
99
+ 6. 判断历史临时代码的原始目的时,按需只读检查注释、测试、`git blame` 和相关提交历史。
100
+
101
+ 已安装 `STANDARD_VERSION` 但无法定位 `llms.txt` 或必要组件文档时,将状态标为“无法继续检查”并停止;
102
+ 不得改用其他版本文档下结论。
103
+
104
+ ## 阶段一:只读审计
105
+
106
+ ### 1. 建立边界与覆盖率
107
+
108
+ - 读取 Git 状态,记录审计开始前已有修改和未跟踪文件。
109
+ - 确认包管理器、workspace、应用入口、样式入口及可用验证脚本。
110
+ - 先生成目标文件清单,再开始搜索。目标文件包括实际消费 Apex UI 的 workspace 中所有源码、样式、
111
+ 配置、测试、脚本和补丁文件;至少覆盖 `js`、`jsx`、`ts`、`tsx`、`mjs`、`cjs`、`css`、`scss`、
112
+ `less`、`html`、`json`、`yaml`、`yml` 和项目实际使用的模板文件。
113
+ - 默认排除 `.git`、`node_modules`(标准版文档和 manifest 除外)、构建产物、coverage、缓存、生成文件
114
+ 和 vendor。先从 Git、workspace 配置和构建配置确认实际目录名,不能只按常见目录名猜;报告中列出
115
+ 实际排除项。
116
+ - 每个目标文件必须进入至少一轮对应类型的扫描。记录“已扫描文件数 / 目标文件数”和“已扫描
117
+ workspace 数 / 目标 workspace 数”;两者都必须是 `N/N`。
118
+ - 无法读取的文件、超大文件、动态生成代码和无法展开的模板单独记录。不能把它们算进已扫描数量。
119
+
120
+ ### 2. 盘点依赖与组件使用
121
+
122
+ - 检查所有 `package.json` 与锁文件,记录 Apex UI 及相关插件的直接、间接和重复版本。
123
+ - 检查 alias、resolutions、overrides、patchedDependencies、postinstall 和本地 fork。
124
+ - 盘点 Apex UI 被哪些应用或 workspace 使用,以及组件和类型的正式导入名。
125
+ - 检查是否只从 `@apexhub/apex-ui-react` 包根导入,是否存在 `src` / `dist` 深链或内部模块引用。
126
+ - 检查 `style.css` 是否在正确的全局入口引入且未重复引入。
127
+ - 核对 `ApexProvider`、locale、主题和微前端配置。
128
+
129
+ 组件目录以随包 `llms.txt` 为准。必须从包根导入、二次导出、别名、wrapper、HOC、Hook 和动态导入
130
+ 继续追踪到实际组件;不能只搜索直接 import。统计“已读取组件文档数 / 实际使用组件数”,必须为
131
+ `N/N`。使用文件数、使用次数和组件列表只供内部判断覆盖率,不写进用户报告。
132
+
133
+ ### 3. 核对 API、样式和临时代码
134
+
135
+ 逐个读取实际使用组件的 `llm.txt`,检查:
136
+
137
+ - 组件、Props、默认值、事件签名和受控模式是否存在;
138
+ - 是否使用废弃或不支持的 API,或用 `as any`、`@ts-ignore`、`@ts-expect-error` 绕过组件类型;
139
+ - 是否依赖内部 DOM、内部类名、非公开属性或特定渲染顺序;
140
+ - 是否存在旧版问题遗留的状态同步、事件拦截、延时、重试或兼容分支;
141
+ - 是否用 `.apex-*`、内部 DOM 层级、高权重选择器、`!important`、`:global(...)` 或 CSS-in-JS 强制
142
+ 覆盖组件内部样式;
143
+ - 是否通过 inline style、`setProperty`、ref、`querySelector`、`MutationObserver` 或定时器修改内部 DOM;
144
+ - 是否存在 patch-package、patchedDependencies、postinstall 修改、monkey patch、复制源码、wrapper、
145
+ HOC、Hook、工具函数、原生控件替代或相同能力的第三方 UI 组件。
146
+
147
+ 至少分六轮扫描,不能用一次宽泛搜索代替:
148
+
149
+ 1. 依赖、包根导入、深链、二次导出、别名、动态导入、patch 和本地 fork;
150
+ 2. JSX、Props、事件、受控状态、废弃 API、类型绕过和原生 / 第三方组件替代;
151
+ 3. `.apex-*`、`data-slot`、Token、CSS 层级、高权重选择器、`!important`、`:global` 和 CSS-in-JS;
152
+ 4. `querySelector`、ref、`setProperty`、DOM 修改、capture 事件、Observer、timer 和重试逻辑;
153
+ 5. wrapper、HOC、Hook、工具函数、复制组件源码和业务组合组件;
154
+ 6. 对所有命中读取完整函数、组件或样式块;必要时查看测试、注释、`git blame` 和相关提交。
155
+
156
+ 公开 Props、官方 Token、稳定 `data-slot`、业务容器布局和不依赖内部结构的 `className` 可能是合法定制。
157
+ 关键词命中只能作为线索,必须阅读代码上下文;不清楚临时代码原因时按需检查只读 Git 历史。
158
+
159
+ 本审计只把以下线索作为候选,不直接当成问题:
160
+
161
+ - 覆盖 `.apex-*` 内部样式或依赖内部 DOM;
162
+ - 手写组件外观、事件或状态逻辑;
163
+ - 用业务组件组合出 Apex UI 没有的交互。
164
+
165
+ 同时将违反公开接入或 API 契约的用法列为候选,例如漏引 `style.css`、错误 Props 或错误事件签名。
166
+ 发现候选后,分别判断项目用法是否违反公开契约、临时代码是否有等价公开替代能力、组件实现是否违反
167
+ 公开承诺。按下方 P / L / V / K 证据标准归类;证据不足时继续调查,不能直接当作合法定制忽略。
168
+
169
+ ### 4. 建立候选项台账并逐条关闭
170
+
171
+ 搜索命中去重后建立内部候选项台账。每项记录:唯一编号、所有位置、当前行为、命中原因、读过的上下文、
172
+ 对应组件文档、公开 API / 类型 / 实现证据、结论 `P / L / V / K` 和结论理由。
173
+
174
+ - 每个命中都必须进入某个候选项,不能因为数量多而抽样。
175
+ - 同一根因可合并,但必须保留全部位置;不同根因不能为了缩短报告强行合并。
176
+ - 被判断为 K 的项也要在内部台账写明“为什么不是问题”,但不向用户输出。
177
+ - 发现新别名、wrapper、内部类名或工具函数时,继续反向和正向追踪调用,直到没有新的项目内引用。
178
+ - 最终必须满足:`候选项总数 = P + L + V + K`,且“未归类候选项”为 0。
179
+
180
+ ## 检查完成的硬门槛
181
+
182
+ 只有同时满足以下条件,报告才能写“检查完成”或“项目无需修改”:
183
+
184
+ 1. 目标 workspace 为 `N/N`,目标文件为 `N/N`;
185
+ 2. 实际使用组件已追踪完成,组件文档为 `N/N`;
186
+ 3. 六轮扫描全部执行,候选项为 `N/N`,未归类候选项为 0;
187
+ 4. 每个 P / L / V 都完成对应证据门槛,每个 K 都写明排除理由;
188
+ 5. 静态代码无法确认、但会影响 P / L 判断的行为,已经通过现有测试、页面运行或最小复现验证。
189
+
190
+ 任一条件不满足时:
191
+
192
+ - 状态写“检查未完成”,不能写“没有问题”或“项目无需修改”;
193
+ - 明确写出缺口、影响哪些结论、下一步要执行的唯一验证动作;
194
+ - 环境无法继续时写“无法继续检查”;不要用猜测补齐 `N/N`。
195
+
196
+ 全量静态扫描只能证明目标文件和已发现候选项全部处理,不能证明所有运行时路径都执行过。需要页面状态、
197
+ 用户操作或异步时序才能确认的风险,必须完成运行验证;无法验证就把相关范围列为未完成。
198
+
199
+ ## 处理结论、风险与证据标准
200
+
201
+ ### 处理分类
202
+
203
+ - **P — 项目里需要改**:满足以下任一路径:项目用法违反标准版公开接入或 API 契约,且有可验证的
204
+ 正确改法;或标准版已有公开能力可等价替换内部覆盖或手写功能。前者包括漏引样式、错误 Props、
205
+ 事件签名、受控状态和不支持的深链导入,不要求存在临时代码。编号从 `P-001` 起。
206
+ 只有 P 类可以进入阶段二修改。
207
+ - **L — Apex UI 本身的问题**:当前安装版本的公开文档、类型或明确承诺与实际运行实现不一致。
208
+ 编号从 `L-001` 起。只报告可复现的组件库 Bug,不把“没有业务需要的 API”算作组件库问题。
209
+ - **V — 需要先确认**:只有业务要求、运行时结果或验收标准无法从代码和当前环境确认时使用。
210
+ 编号从 `V-001` 起。必须给出一个明确的确认问题或验证动作。
211
+ - **K — 不需要处理**:正常别名、代码风格、公开 API 用法、业务布局、业务样式、组件库明确不支持的
212
+ 业务行为,以及项目自己的组合组件。即使其中存在内部 class 或手写逻辑,只要未违反公开契约、
213
+ 没有公开替代方案且不是组件库 Bug,就不编号、不计数、不在用户报告中输出。
214
+
215
+ ### 分类规则
216
+
217
+ 1. 先判断“是不是问题”,再判断谁处理和风险。内部 class、手写代码、代码量大都不能单独证明有问题。
218
+ 2. 正常 import 别名、解构别名、命名风格、原生元素和代码一致性不属于本次升级风险审计;除非它们
219
+ 违反当前 Apex UI API 并能证明当前或升级后会出错,否则直接忽略。
220
+ 3. P 类的错误用法须给出“违反的公开契约、实际影响、正确用法”;临时代码替换须同时给出“现有
221
+ 手写代码、可替代它的公开能力、业务行为等价证据”。不能把第二条路径的条件强加给第一条路径。
222
+ 4. L 类必须给出文档或类型的明确承诺、实际实现、两者冲突和复现方式。组件库决定不实现某项行为,
223
+ 或只是没有业务需要的 API,不得归为 L。
224
+ 5. 能通过随包文档、`.d.ts`、当前安装版本实现或只读 Git 历史确认的,不得放进 V 类。先查完再下结论。
225
+ 6. 不把证据不足交给用户兜底。只有业务意图或必须运行页面才能确认的事项才交给用户。
226
+
227
+ ### 风险等级
228
+
229
+ - **高**:错误接入或 API 用法导致运行错误、组件整体无样式或核心流程不可用;内部覆盖在升级后
230
+ 有明确失效证据并影响核心功能;或者组件实现违反公开文档并影响核心功能。
231
+ - **中**:问题成立,但只影响单个页面或非核心交互,且升级后有明确回归方式。
232
+ - **低**:问题成立但影响很小。纯维护性、命名或代码风格问题不进入报告,不能用“低风险”收进来。
233
+
234
+ ### 判断置信度
235
+
236
+ - **高**:代码位置、标准版依据和原始用途均有直接证据。
237
+ - **中**:依据基本成立,但原始用途或删除后的行为缺少一部分证据。
238
+ - **低**:主要来自关键词、命名或间接推断。
239
+
240
+ ### P 类硬门槛
241
+
242
+ 只有同时满足以下条件才能归为 P 类:
243
+
244
+ 1. 给出具体代码位置和实际行为;
245
+ 2. 标明属于“错误用法修正”还是“临时代码替换”;
246
+ 3. 错误用法修正:给出 `STANDARD_VERSION` 的公开接入或 API 契约、违反位置、实际影响及正确用法,
247
+ 不要求有内部覆盖、手写功能或历史 workaround;
248
+ 4. 临时代码替换:指出内部覆盖或手写功能、原始用途和标准版的公开替代能力,引用文档、类型或实现,
249
+ 证明能满足当前业务要求,而不是只做到“看起来差不多”;第 3、4 条按对应路径执行;
250
+ 5. 给出修正或替换后的预期结果和验收方式;
251
+ 6. 判断置信度为“高”。
252
+
253
+ 不满足 P 类门槛时,继续判断是 L、V 还是 K,不得统一塞进“需要确认”。不得因为代码“像 hack”
254
+ 就建议删除。
255
+
256
+ ### L 类硬门槛
257
+
258
+ 只有同时满足以下条件才能归为 L 类:
259
+
260
+ 1. 指出 `STANDARD_VERSION` 文档、类型或公开承诺的具体内容;
261
+ 2. 用当前安装版本的实现或运行结果证明实际行为与承诺不一致;
262
+ 3. 给出受影响的项目位置和可复现步骤;
263
+ 4. 写出组件库应该修正实现还是修正文档,以及验收标准。
264
+
265
+ “没有某个 API”“业务希望组件换一种交互”“组件库决定不实现”都不满足 L 类门槛,直接归为 K。
266
+
267
+ ## 审计报告规范与模板
268
+
269
+ ### 表达规则
270
+
271
+ - 结论先行,优先回答“项目要改什么、哪些问题需要反馈给 Apex UI、还需要确认什么”。
272
+ - 主报告目标控制在约 70 行;可复制的 Apex UI 反馈代码块不计入此限制。重复问题合并为一项并注明
273
+ 位置数量,不遗漏 P / L / V 类问题。
274
+ - 不输出合法定制、组件使用次数、使用文件数或组件使用概览。这些信息只供审计过程判断覆盖率。
275
+ - “检查范围”只输出完成度数字、未覆盖范围和运行验证状态,不输出组件清单或内部候选项台账。
276
+ - 不粘贴原始搜索结果、完整日志或大段代码;每项证据用一至两句话,位置统一写 `path:line`。
277
+ - 组件库问题写清公开承诺、实际行为、影响和复现方式;不要输出组件库已决定不支持的业务需求。
278
+ - 存在 L 类问题时,必须在问题说明后增加“可直接复制给 Apex UI”的独立 Markdown 代码块;每个
279
+ L 类问题一个代码块,用户无需重新整理即可复制到缺陷单或群消息。
280
+ - 没有内容的“项目里需要改”“需要反馈给 Apex UI”“需要先确认”章节直接省略,不写“无”。
281
+
282
+ ### 说人话
283
+
284
+ 报告面向开发者,可以使用 API、Props、DOM、CSS、Token、`data-slot` 等必要编程术语,但句子要短、
285
+ 动作要直接。每条问题依次回答:
286
+
287
+ 1. 这段代码有什么问题;
288
+ 2. 会造成什么影响;
289
+ 3. 谁需要处理;
290
+ 4. 具体怎么处理和怎么验收。
291
+
292
+ 使用直接表达:
293
+
294
+ - 写“项目代码需要改”,不写“消费方侧建议治理”;
295
+ - 写“Apex UI 已有 `{API}`,项目应直接使用”,不写“建议优先复用标准能力”;
296
+ - 写“Apex UI 的实现与文档不一致”,不写“组件库侧疑似存在能力异常”;
297
+ - 写“升级后可能失效”,不写“存在版本漂移风险”;
298
+ - 写“还没验证”,不写“行为等价性未证实”;
299
+ - 写“先保留这段代码”,不写“维持现有 workaround”。
300
+
301
+ 禁止使用没有明确动作的说法:`建议评估`、`可以考虑`、`视情况处理`、`试一下`、`保留或修改`、
302
+ `若不行再反馈`。确实需要分支判断时,只能放进 V 类,并给出唯一的确认问题或验证步骤。
303
+
304
+ ### 固定模板
305
+
306
+ 严格按以下顺序输出,不改成散文:
307
+
308
+ ````markdown
309
+ # Apex UI 使用检查报告
310
+
311
+ ## 一、结论
312
+
313
+ - 检查状态:检查完成,可以确认修改 / 检查完成,项目无需修改 / 检查未完成 / 无法继续检查
314
+ - 组件库版本:通过 / 未通过(脱敏 registry;latest → STANDARD_VERSION;查询时间与时区;声明、锁定与实际版本;未通过原因)
315
+ - 项目里需要改:N 项
316
+ - 需要反馈给 Apex UI:N 项
317
+ - 需要先确认:N 项
318
+ - 现在要做:……
319
+
320
+ ## 二、项目里需要改
321
+
322
+ ### P-001 · 简短问题名(高风险)
323
+
324
+ - 位置:`src/example.css:10`
325
+ - 问题:这段代码……,当前 / 升级后会……。
326
+ - 为什么要改:违反公开契约……,正确用法为……;或公开能力……可完整替代当前手写代码(只填适用路径)。
327
+ - 怎么改:删除 / 替换为……。
328
+ - 验收:运行……;确认……。
329
+
330
+ ## 三、需要反馈给 Apex UI
331
+
332
+ ### L-001 · 简短问题名(中风险)
333
+
334
+ - 位置:`src/example.tsx:20`
335
+ - 问题:文档 / 类型承诺……,但实际实现……。
336
+ - 影响:项目在……时会……。
337
+ - 复现:……。
338
+ - Apex UI 怎么改:修正实现 / 文档……;验收标准是……。
339
+
340
+ 可直接复制给 Apex UI:
341
+
342
+ ```markdown
343
+ 【Apex UI Bug】【组件名】简短问题名
344
+
345
+ - 版本:@apexhub/apex-ui-react@STANDARD_VERSION
346
+ - 问题:文档 / 类型承诺……,但实际……。
347
+ - 影响:……。
348
+ - 复现步骤:
349
+ 1. ……
350
+ 2. ……
351
+ - 期望结果:……。
352
+ - 实际结果:……。
353
+ - 建议修复:修正实现 / 文档……。
354
+ - 验收标准:……。
355
+ - 项目位置:src/example.tsx:20
356
+ ```
357
+
358
+ ## 四、需要先确认
359
+
360
+ ### V-001 · 简短问题名(中风险)
361
+
362
+ - 位置:`src/example.tsx:30`
363
+ - 还不清楚:代码无法说明业务是否要求……。
364
+ - 已确认:文档、类型和实现只能确认……。
365
+ - 需要确认:请确认……。
366
+ - 确认后:如果……,归为 P-xxx;如果……,归为 L-xxx / 无需处理。
367
+
368
+ ## 五、检查范围
369
+
370
+ - 文件:已扫描 N / N;workspace:N / N。
371
+ - 组件文档:已读取 N / N;候选项:已处理 N / N,未归类 0。
372
+ - 运行验证:已完成…… / 未完成……;未完成时说明影响的结论。
373
+ - 排除:构建产物、生成文件……;无法读取:无 / ……。
374
+ - 文件修改:无;开始前已有未提交改动时在这里说明。
375
+
376
+ ## 六、下一步
377
+
378
+ 请确认:
379
+ 1. 修改全部 P 类问题(P-001、P-002)
380
+ 2. 只修改指定 P 类编号
381
+ 3. 暂不修改
382
+ ````
383
+
384
+ ### 特殊结果
385
+
386
+ - **P 类为 0**:不要询问是否修改;写“本次已确认的项目修改项为 0”。有 L 类时直接列出需要
387
+ 反馈给 Apex UI 的问题和可复制反馈块;有 V 类时只请用户回答明确的问题。
388
+ - **P、L、V 均为 0 且完成门槛全部通过**:状态写“项目无需修改”,只保留结论和“检查范围”。
389
+ - **任一完成门槛未通过**:状态写“检查未完成”,不能使用 P、L、V 均为 0 的“项目无需修改”结论;
390
+ 只输出已经确认的问题、检查缺口和下一步验证动作。
391
+ - **版本或文档检查失败**:状态写“无法继续检查”,只告诉用户失败原因和下一步操作,不输出修改选项。
392
+ - 下一步列出的“修改全部”必须带本次真实 P 类编号,不得保留模板占位符。
393
+ - **P 类为 0 时删除修改确认选项**;仍有检查缺口时保留下一步验证动作,不让用户确认不存在的修改。
394
+
395
+ ### Apex UI 反馈块规则
396
+
397
+ - 反馈标题直接写组件名和现象,不使用 L 编号作为标题;L 编号只用于报告内对应。
398
+ - 必须填写真实版本、问题、影响、复现步骤、期望结果、实际结果、建议修复和验收标准,不保留占位符。
399
+ - 复现步骤写成最短可执行步骤;已有最小复现代码时放进同一个反馈代码块。
400
+ - 项目位置可以保留,方便追查;不要附带与 Bug 无关的业务代码、内部候选项或 K 类结论。
401
+ - 多个 L 类问题不能合并进一个代码块;这样用户可以按问题分别复制和提交。
402
+
403
+ 输出报告后停止,不得在同一轮修改代码。
404
+
405
+ ## 阶段二:确认后修改
406
+
407
+ 只有用户基于当前报告明确选择全部 P 类问题或给出具体 P 类编号时执行:
408
+
409
+ 1. 记录确认范围;L 类不修改项目代码,V 类必须先完成确认并重新归类为 P 后才能修改。
410
+ 2. 按下方“修改前复核”核对报告固定的 `STANDARD_VERSION` 与 Git 状态,不重新解析 `latest`。
411
+ 3. 修改前记录受影响检查的现有结果;能运行时先运行针对性检查,无法运行则明确缺少修改前基线。
412
+ 4. 只修改已确认的 P 类编号,不升级依赖、不重构无关代码、不扩大范围。
413
+ 5. 按项目 `package.json` 中真实脚本运行适当的格式检查、类型检查、测试和构建;失败按下方归因处理。
414
+ 6. 项目支持页面或端到端验证时,检查受影响的关键交互;无法运行时明确说明。
415
+ 7. 检查最终 diff,确认只包含已确认修改且保留审计前的用户修改。
416
+
417
+ ### 修改前复核
418
+
419
+ - 将报告记录的 manifest、锁文件有效解析、实际安装版本、补丁、文档与相关代码逐项和当前状态比较。
420
+ Git 状态相同不代表内容相同,已有未提交修改也须比较内容。
421
+ - 仅 registry 的 `latest` 已更新,实际依赖和证据未变:继续已确认修改,不要求升级或重新批准。
422
+ 此阶段无需访问 registry,离线也可用未变的本地依赖和报告继续。
423
+ - 只有无关文件或锁文件无关条目变化:说明已核对,不阻塞已确认项。
424
+ - 相关代码、补丁、类型或文档变化但实际版本不变:重新验证受影响条目的证据;改法和范围仍成立时
425
+ 继续执行已有授权。结论或改法改变时先更新该条报告,只对新增或变化的修改范围请求确认。
426
+ - 实际版本或有效依赖解析变化:暂停受影响 workspace 的旧报告修改,针对当前环境重新审计并给出
427
+ 更新报告;不自动升级、降级依赖。其他证据未变的已确认项可继续。
428
+ - 无法恢复原报告版本或相关证据:说明缺少哪项记录,先重新建立该范围的审计依据,不能猜测基线。
429
+
430
+ ### 验证失败处理
431
+
432
+ - **报告结论不成立**:撤销该项本轮改动,保留用户已有及并发修改,更新该项结论并说明原因。
433
+ - **确认本轮引入回归**:先在已确认范围内修复并重跑受影响检查;仍无法修复时,仅撤销造成回归的
434
+ 本轮改动,重跑相关检查,记录该项未完成。
435
+ - **项目已有失败**:用修改前结果或独立复现证明同一失败已存在;保留正确修复,列出无关失败,
436
+ 不因全仓命令退出非零撤销已验证修改,也不把全仓检查标为通过。
437
+ - **环境故障**:例如服务不可用或浏览器缺失。保留改动,记录失败命令、环境原因、受影响验收项和
438
+ 下一步验证动作,标为“修改已完成,验证未完成”,不能称已验证通过。
439
+ - **暂时无法归因**:继续用最小复现、针对性检查和修改前证据定位;仍无法确认则保留待验证改动,
440
+ 明确标为“验证未完成”,不能称正确修复或已确认回归,也不能自动撤销。
441
+ - 撤销只处理对应条目本轮改动,不使用 reset / checkout 或恢复整文件覆盖用户修改。独立条目不因
442
+ 其他条目失败被一并撤销;存在依赖关系时联动复核受影响条目。
443
+
444
+ 阶段二使用以下简洁模板:
445
+
446
+ ```markdown
447
+ # Apex UI 修改结果
448
+
449
+ ## 结论
450
+
451
+ - 用户确认:P-001、P-002
452
+ - 修改完成:N 项
453
+ - 未完成:N 项
454
+ - 验证结果:通过 / 部分通过 / 未通过
455
+
456
+ ## 修改结果
457
+
458
+ | ID | 结果 | 修改文件 | 说明 |
459
+ | --- | --- | --- | --- |
460
+ | P-001 | 已修改 | src/example.css | 删除旧版覆盖 |
461
+
462
+ ## 验证
463
+
464
+ | 命令或页面 | 结果 | 备注 |
465
+ | --- | --- | --- |
466
+ | pnpm typecheck | 通过 | … |
467
+
468
+ ## 还需要处理
469
+
470
+ - 无 / 未完成原因、异常样式、功能问题或需要反馈 Apex UI 的事项
471
+ ```
@@ -0,0 +1,38 @@
1
+ # Apex UI 消费方用法审计
2
+
3
+ 本流程用于检查 **npm 模式** 应用对公开 Apex UI API 的使用。源码模式下组件属于项目、允许修改,不按本流程把组件改动判为违规;只检查业务代码是否从组件目录导入、是否用 hack 绕过组件问题。
4
+
5
+ 先建立当前版本证据,再输出只读报告;只有用户明确
6
+ 确认修改范围后才改消费方代码。
7
+
8
+ ## 建立版本基线
9
+
10
+ 如果需要 npm 模式的完整 registry 门禁、覆盖率清单、证据台账和确认后修改流程,继续阅读
11
+ `references/audit-npm.md`;本文件保留源码模式与 npm 模式的共同入口。
12
+
13
+ 在消费方项目根运行:
14
+
15
+ ```bash
16
+ npm view @apexhub/apex-ui-react@latest version --json --prefer-online
17
+ ```
18
+
19
+ 记录返回的稳定版本、查询时间和 registry 来源。同步核对消费方 `package.json`、锁文件和实际安装的
20
+ `@apexhub/apex-ui-react/package.json`;版本不一致时先说明原因,不自动降级或替换依赖。
21
+
22
+ ## 静态检查
23
+
24
+ 先列出目标 workspace 和源码文件,再逐项检查:
25
+
26
+ - 是否从 `@apexhub/apex-ui-react` 包根导入,是否漏引 `style.css`;
27
+ - 组件、Props、事件签名、受控模式和 locale 是否符合随包 `llm.txt`;
28
+ - 是否使用 `as any`、`@ts-ignore`、内部 class、内部 DOM 或未公开属性;
29
+ - 是否通过公开 Token、`data-slot` 和 `className` 完成样式定制;
30
+ - 是否存在可由公开 API 替代的临时 DOM 操作或第三方组件替代。
31
+
32
+ 关键词命中只作为线索,必须读取完整上下文。记录每个候选的文件、证据、影响和结论;不要因为业务
33
+ 组合组件或合法主题覆盖而误报。
34
+
35
+ ## 报告
36
+
37
+ 报告至少包含:版本基线、扫描范围、已确认的项目问题、组件库问题、需要用户确认的事项、验证结果和
38
+ 下一步。没有证据时标记为未验证;不要把“检查完成”建立在单次关键词搜索上。
@@ -0,0 +1,81 @@
1
+ # 通用约定与坑
2
+
3
+ > **本文件职责**:只放**跨组件、且在单个组件 `llm.txt` 里看不出来的**约定。某个组件自己的 Props、
4
+ > `onChange` 签名、示例,读该组件的 `llm.txt`,不在这里重复。
5
+ >
6
+ > 示例按源码模式写(从 `@/components/apex/<目录>` 导入)。npm 模式下把导入路径统一换成包根
7
+ > `@apexhub/apex-ui-react`,其余规则相同。
8
+
9
+ ## 导入
10
+
11
+ - 源码模式:从组件目录导入,一个目录一条 import。导出名和目录的对应关系见组件目录 `AGENTS.md` 末尾
12
+ 的表格。类型也从同一个目录导入:
13
+
14
+ ```tsx
15
+ import { Button, type ButtonProps } from '@/components/apex/button'
16
+ import { Form, FormItem, useForm } from '@/components/apex/form'
17
+ ```
18
+
19
+ - npm 模式:组件和类型都从包根 `@apexhub/apex-ui-react` 具名导入,不要深链 `dist` / `src`。
20
+ - 导出名大小写敏感。命令式反馈是**小写单例** `message` / `notification`,直接调用,不是放进 JSX 的
21
+ 组件;普通组件是大驼峰;Hook 是 `useForm` / `useBreakpoint` / `useConfig`。
22
+ - 不要手写组件的 Props 类型,用组件导出的类型。
23
+
24
+ ## 类型报错时不要用 any 压下去
25
+
26
+ 类型报错通常说明用了不存在的 API。按下面顺序处理:
27
+
28
+ 1. 读该组件的 `llm.txt`,改用文档里的写法。`Tabs` / `Collapse` / `Steps` 这类列表型容器用 `items`
29
+ 配置,没有 `TabPane`、`Panel`、`Step` 子组件。
30
+ 2. 只有 `llm.txt` 写明的复合子组件才能用,例如 `Table.Summary`、`Form.Item`、`Breadcrumb.Link`、
31
+ `DatePicker.RangePicker`。
32
+ 3. 文档里的写法确实满足不了需求:源码模式下按 `SKILL.md`「组件有问题时」去改组件源码;npm 模式下
33
+ 告诉用户组件缺这个能力。
34
+
35
+ 不要写 `const TabsAny = Tabs as any`、`(Tabs as any).TabPane`、`@ts-ignore` 这类绕过。
36
+
37
+ ```tsx
38
+ // ✅ 正确
39
+ <Tabs
40
+ defaultActiveKey="tab1"
41
+ items={[
42
+ { key: 'tab1', label: 'Tab 1', children: <Content /> },
43
+ { key: 'tab2', label: 'Tab 2', children: <Content2 /> },
44
+ ]}
45
+ />
46
+
47
+ // ❌ 错误:不存在的复合子组件
48
+ <Tabs defaultActiveKey="tab1">
49
+ <Tabs.TabPane tab="Tab 1" key="tab1">...</Tabs.TabPane>
50
+ </Tabs>
51
+ ```
52
+
53
+ ## 受控写法
54
+
55
+ 表单类组件:传 `value` + `onChange` 为受控,传 `defaultValue` 为非受控,不要同时传。**各组件的
56
+ `onChange` 参数不一样**,写之前查该组件的 `llm.txt`。
57
+
58
+ ## 命令式反馈与浮层
59
+
60
+ - `message` / `notification` 直接调用,不需要在 JSX 里挂组件。
61
+ - 命令式确认框用 `Modal.useModal()`,这样能拿到当前主题和 locale。
62
+
63
+ ## 图标
64
+
65
+ - 内置图标在组件目录的 `icons/`,数量不多,主要是组件自己用的(关闭、箭头、日历等)。能用的名字
66
+ 看 `icons/index.ts` 的导出,从 `@/components/apex/icons` 导入。
67
+ - 内置没有的图标:用内联 SVG,或者直接用文字。**不要安装图标库**(`@ant-design/icons`、
68
+ `lucide-react` 等),图标来源还没定。
69
+ - 只有图标、没有文字的按钮必须传 `aria-label`。
70
+
71
+ ## 可访问性
72
+
73
+ - 可点击的元素用 `Button`,不要用 `div + onClick`。
74
+ - `Switch` / `Checkbox` / `Radio` 配 `<label htmlFor>`。
75
+ - 只有图标、没有文字的可点击元素必须传 `aria-label`。
76
+ - 不要为了外观删掉 `aria-*`。
77
+
78
+ ## 样式定制
79
+
80
+ - 改外观用公开 Token(CSS 变量)和 `className`,见 `theming.md`。
81
+ - 要选中组件内部某个部件时用 `[data-slot="<部件名>"]`,不要用组件内部的 class 名。