Public Components Skill

使用本 Skill 来帮助各类 AI 编程助手生成、审查或排查消费 @arim-aisdc/public-components 的代码。始终把组件库根入口导出视为公共接口边界，并按任务类型只读取必要的参考文档。

触发条件

当任务涉及以下内容时使用本 Skill：

• 生成、重构、审查或排查消费 @arim-aisdc/public-components 的前端代码。
• 确认根包导出、/utils 工具函数、主题变量路径或内部路径导入边界。
• 使用 TableMax、ProTable、RemoteSelect、SplitterPane、导出配置、CustomForm、QueryFilter、SchemaForm、ConfigProvider/useConfig、权限体系、筛选组件、ConditionExpression、缓存、事件总线、MessageTip、ModalTip 或多语言配置。
• 处理 TypeScript 类型错误、导出不匹配、旧文档冲突、组件行为异常或后台管理界面一致性问题。

核心规则

1. 优先从 @arim-aisdc/public-components 根包导入。
2. 不要编造 src/index.ts 或已记录二级路径没有公开的接口。
3. 按任务类型读取相关 references/ 文件，不要默认一次性加载全部参考文档。
4. 只要涉及页面开发、页面重构、列表页、表格、表单、弹窗或任何界面样式，就必须读取并严格遵守 references/ui-consistency.md。
5. 只有当参考文档缺少关键细节、出现 TypeScript 报错，或导出/类型冲突时，才回到源码校对。
6. 仅在用户明确接受风险时，才建议内部路径导入。

根包公共导出

默认可安全使用的常见根包导出：

• 组件：TableMax、ProTable、StatusCell、RemoteSelect、CustomForm、QueryFilter、SchemaForm、ConfigProvider、PermissionProvider、Restricted、PermissionContext、BaseInfo、CenterModal、DrawerCom、SplitPane、SplitterPane、CacheTabs、DraggableBox、ConditionExpression、Icon、Empty、MessageTip、ModalTip
• ProTable 公开类型/映射：IconMap、statusDataType、CellMergeMap、CellMergeInfo；RemoteSelect 公开类型：RemoteSelectProps
• TableMax/共享列类型：InputType、FilterType、FilterFnType、SortFnType、ColumnPinningConfigType、ColumnVisibleConfigType、ColumnType、TableMaxColumnType、TableMaxProps
• Filter 系列：FilterSelect、FilterInputNumber、FilterRadio、FilterSlider、FilterSwitch、FilterColor
• hooks 与事件：useConfig、useEventBus、events、usePageCacheState、useCenterModalState
• 多语言配置：public_zhCN、public_enUS、public_viVN

不要默认把以下能力作为根包导入：

• ThemeProvider
• useTranslation
• ColorSelector
• MicroComponent

如果用户要求这些能力，先说明它们不是当前根包公共导出，再优先提供根包已公开的替代方案。

补充边界：

• defaultRowHeight 当前只从 ProTable 组件子入口导出，尚未由包根 src/index.ts re-export；在根包未补导出前不要生成根包 import。
• SchemaForm 根包当前只公开默认组件；DataSourceTypeEnum、FormActionEnum、ProFieldValueTypeEnum 及相关类型不要默认写成根包导入。

导入模式

根包导入：

import { TableMax, ConfigProvider, public_zhCN } from '@arim-aisdc/public-components';

工具函数：

import { to, getTextWidth, judgeHasPermission } from '@arim-aisdc/public-components/utils';

主题变量仅在必要时使用：

import { publicThemeMap } from '@arim-aisdc/public-components/themes/variablesConfig';

参考文档路由

• TableMax、列定义、分页、排序、筛选、拖拽、虚拟行/列、导出配置：读取 references/table-max.md。
• ProTable、StatusCell、单元格合并、虚拟列表、列宽、懒 Tooltip、ProTable 导出：读取 references/pro-table.md。
• 独立 RemoteSelect、远程搜索、前端过滤、fieldNames、labelInValue：读取 references/remote-select.md。
• ConfigProvider、useConfig、主题变量、多语言配置、TableMax 全局配置：读取 references/config-provider.md。
• PermissionProvider、Restricted、PermissionContext、权限判断：读取 references/permission.md。
• useEventBus、events、usePageCacheState、useCenterModalState、hook 行为：读取 references/hooks.md。
• FilterSelect、FilterInputNumber、FilterSlider、FilterSwitch、FilterColor、FilterRadio、ConditionExpression、条件表达式远程参数选项：读取 references/filter-components.md。
• CustomForm、QueryFilter、SchemaForm、Empty、CenterModal、DrawerCom、SplitPane、SplitterPane、DraggableBox、Icon、CacheTabs、BaseInfo、MessageTip、ModalTip：读取 references/other-components.md；涉及 SplitterPane 新 props 时同时读取对应迁移段落。
• 推荐写法与防漂移规则：读取 references/best-practices.md。
• 页面开发、页面重构、列表页、详情页、表单页、弹窗页、区块式表格、后台管理界面、UI 一致性约束：必须读取 references/ui-consistency.md。
• UI 颜色变量找不到合适语义 token，且当前项目没有可复用写法时，最后读取 references/color-variable-palette.md 作为最低优先级兜底参考。
• 报错、异常行为、旧文档、导出或类型不匹配：读取 references/troubleshooting.md。

任务流程

1. 先判断用户代码使用的是根包、/utils、主题变量路径，还是内部路径。
2. 生成 import 前，先确认公共导出边界。
3. 按上面的参考文档路由读取当前任务需要的文档。
4. 如果是界面或页面任务，把 references/ui-consistency.md 作为强制验收约束；生成代码前先观察当前项目类似页面和组件是否已有更简单写法，优先使用组件内置 props、组件组合和现有 class，避免不必要的 CSS/Less。
5. 遇到颜色不确定时，先查当前项目已有 token 或类似组件写法，再按 references/ui-consistency.md 的语义变量处理；仍找不到合适变量时，才读取 references/color-variable-palette.md 作为最低优先级参考。
6. 按已记录公共接口生成代码。
7. 如果细节缺失或 TypeScript 结果不一致，再查看源码基线文件并修正输出。

高风险错误

• 不要写 Restricted fallback；当前 Restricted 只支持 requiredPermissions、isPage、children。
• 不要给 useCenterModalState 使用 visible；当前状态字段是 open。
• 不要混用三套表单模型：CustomForm 使用 CustomFormItemType，QueryFilter 使用 FormItemType，SchemaForm 使用 formConfig。
• 不要把 useTranslation 写成根包导入；多语言优先通过 ConfigProvider 和 public_zhCN/public_enUS/public_viVN 配置。
• 不要把 CacheTabs 当成通用 Tabs 封装；它绑定 keep-alive 缓存场景。
• ProTable 与 TableMax 当前仍是两个公开实现；除非组件库文档明确说明替代关系，不要擅自把 ProTable 描述成 TableMax 的无条件替代品。ProTable 的默认 rowHeight 为 36，TableMax 当前默认行高为 42，使用虚拟化时必须按实际组件核对。
• ProTable 的 mergeCells 支持自动合并或函数返回 { rowSpan, colSpan }；源码对虚拟化/最大行数仍存在类型注释与实现口径差异，未确认前不要生成“固定 100/500 行”或“必然禁用虚拟列表”的结论。
• ProTable 导出会处理 ReactNode、函数表头和格式化结果，并排除内置列、disabledExport 列，以及有效列 key（id 优先，否则 accessorKey）为 operate/operation 或解析后表头为“操作”的列；这些规则不要未经核对泛化到其他表格实现。
• RemoteSelect 默认远程搜索需显式开启 showSearch，提供 getOptionsFn 时初始化会先请求一次，输入再按 500ms 防抖调用 getOptionsFn(keyword)；配置 canFrontFilter 或 frontendFilterOptionFun 后，搜索只做前端过滤，当前实现通常不因受控值变化自动刷新 options。
• SplitPane 已进入 deprecated 兼容期，新代码优先使用 SplitterPane；后者支持受控 size、onCollapse、lazy、面板/容器 class/style 和带用户、路由前缀的尺寸缓存。
• antd 5 兼容代码应优先使用当前属性名，例如 Modal 的 destroyOnHidden、组件 styles、直接使用 antd Select 时的 popupMatchSelectWidth；QueryFilter 仍使用其公开字段 dropdownMatchSelectWidth，RemoteSelect 只使用自身声明的 props。遇到旧属性告警先读取排障文档。
• ModalTip.delete/confirm 如需使用 antd App 上下文实例，先核对当前 modalInstance 类型，不要为了消除警告直接改用内部路径。
• 不要假设 TableMax exportConfig 只配置 fileName/sheetName 能通过类型检查；当前 ExportOptions 类型要求 pageFetcher。当前页导出优先只传 canExport，文件名优先用 tableTitle，全量导出再补齐 pageFetcher。
• 不要给 ConditionExpression 远程参数选项同时开启前端筛选；传入 parameterOptionsRequest 后组件内部会把 Select filterOption 设为 false 并使用远程搜索。
• 不要在 .less 或 .module.less 中直接写 var(--global-*)；优先使用项目已有 Less 主题变量，例如 @global-card-background-color。
• 不要在 UI 界面 任务中自由发挥色值、圆角、间距、表格滚动或分页样式；颜色优先使用项目主题 token 或 references/ui-consistency.md 的语义变量，缺少变量时宁愿删除颜色覆盖，不要写死裸色。

维护信息

本段只服务 Skill 维护者，不是普通任务必须关注的上下文。除非正在校准本 Skill 或用户明确要求核对源码，否则不要因为这些信息读取本地源码。

• Skill 版本：v1.4.0
• 组件库：@arim-aisdc/public-components
• 组件库版本：2.4.12
• 源码校准目录：由维护者通过 PUBLIC_COMPONENTS_SOURCE 配置，不写入固定本机路径。
• 最近源码校准：2026-09-24（本地 develop，37ec939；发布产物未单独核验）
• 本地版本更新记录：VERSION_UPDATES.local.md，该文件只保留在维护者本地，并通过 .gitignore 排除，不随 Skill 发布。

如果 Skill 文档与可访问源码冲突，以源码为准，并把该冲突视为后续需要修正文档的漂移信号。