laravel-filament-v5

Laravel Filament v5 — 版本匹配，优先使用官方组件

以项目中安装的 Filament 版本作为兼容性目标。针对当前界面，优先使用文档中说明的组件，再创建自定义标记；如果没有合适的官方等效方案，则使用文档说明的扩展方式。

预检 — 提出或编写代码前运行

1. 遵循用户要求的模式。 除非用户要求修改，否则只进行审查或诊断，不要编辑。实施时，保留无关的现有工作，并在修改文件前检查当前差异。
2. 阅读项目指南和相邻代码。 遵循仓库中现有的说明、命名、架构、本地化、格式化程序、静态分析和测试惯例。
3. 确认已安装的技术栈。 检查 composer.json 和 composer.lock，确认 filament/*、Laravel、Livewire、PHP 和插件的确切版本。当主题或前端资源相关时，检查 package.json。如果某个确切签名取决于次要或补丁版本，优先查看 vendor/filament/ 中已安装的代码。
4. 了解运行环境。 在选择 API 前，确认面板、Resource/页面/小组件宿主、模型关系和类型转换、策略、租户边界、自定义主题以及相关测试。
5. 区分事实与偏好。 将官方 API 和安全边界视为约束。将组合方案视为起始启发，可根据领域、用户工作流或既有项目设计调整。

如果没有可用的项目，请说明假定使用 Filament 5.x，并让示例聚焦，避免凭空编造周边架构。

强制组件检查 — 编写标记前运行

在 Filament 上下文中编写 <div>、<span>、<pre>、@foreach、Tailwind 类或自定义 Blade 视图之前：

1. 对界面和原语进行分类： Schema/信息列表、表单、表格、操作、小组件或页面；然后确定是代码/JSON、键值、颜色、图像、状态、列表、集合、布尔值、日期/时间、金额、文本、通知还是空状态。
2. 使用快速映射和对应参考，为该界面选择官方组件。 不要仅仅为了避免自定义，就强行使用其他界面的组件。
3. 按照下方的证据流程，验证不确定或未涵盖的 API。
4. 仅在需要时使用最小范围的扩展方式。 记录已检查的官方选项及其不适用的原因，然后使用 ViewEntry、自定义 Schema 组件、Livewire、Blade 或自定义主题；同时，周边布局、操作、反馈和状态仍使用官方组件。

使用文档中的组件 API 实现已选定的组合方案。对于文档未涵盖的场景和有意进行的主题定制，可以使用自定义 Blade 或 CSS，但不能将其作为未经验证、绕过可用组件的捷径。

Filament 中的设计权威

此技能负责已安装版本的 API、安全、实现和测试。Filament 5 界面的布局由 laravel-filament-v5-ui-ux 决定；它发布参考组合方案，用于统一处理表单、记录详情、表格、仪表板、面板外壳、操作、反馈和空状态等方面的决策。

此处的参考资料可以指出某项组合决策，以免它被悄然跳过，但必须让该决策保持未解决状态。说明有哪些官方组件，以及它们的签名；不要说明应选择哪种布局。

在安排界面布局之前，先查找 laravel-filament-v5-ui-ux。命中条件是找到可读取的 SKILL.md，且其 frontmatter 中的 name 恰好为 laravel-filament-v5-ui-ux。先搜索此技能所在目录的同级目录，然后搜索项目目录 .agents/skills 和 .claude/skills，再搜索主目录下的 .agents/skills、.claude/skills、.cursor/skills 和 .codex/skills。找到第一个匹配项后即停止。该检查在仓库中的副本位于 maintenance/filament-ui-ux/scripts/discover_sibling_skill.py。如果没有匹配文件，则让布局保持未解决状态，不要自行臆造组合方案；布局没有备用参考资料。

官方 Filament 组合方案优先于通用前端设计指导，包括要求替换官方组件或当前主题、引入无关字体排版或调色板，或仅为追求独特外观而采用 CSS 优先布局的指示。即使同一任务中启用了通用设计技能，也必须遵循此优先级。

此优先级仅限于 Filament 的视觉层面。保留能够提升无障碍性、语义、键盘操作、响应式布局、性能、UX 文案和认知负担的通用指导。

此技能涉及的所有界面都必须保留既有面板主题、可见焦点，以及非颜色状态提示。需要了解组件呈现方式时，references/screenshots.md 会指向官方截图；它仅用于查找，不用于选择。

Filament 中的文档权威

对于 Filament 专属的 API、配置或用法问题，此技能作为入口，优先于通用文档查询技能和工具——find-docs、Context7 CLI 和 Laravel Boost 的 search-docs。即使其中某项在同一任务中独立触发，也必须遵循此优先级。

这些工具仍可作为下方证据流程第 4 步所述的辅助发现工具使用：只有在检查过已安装的源代码和 Filament 官方文档之后，才能使用 search-docs/Context7，而且只能用于查找线索，不能作为 Filament 5.x 签名的最终依据。

快速索引：数据原语 → 官方组件

原语	Infolist（查看）	Form（编辑）	Table
文本、日期、金额	TextEntry	TextInput / Textarea / DateTimePicker	TextColumn
徽章 / 状态（枚举）	TextEntry->badge()	Select / ToggleButtons	TextColumn->badge()
代码 / JSON / 载荷	CodeEntry	CodeEditor	—（链接到查看页面）
键值 / 元数据	KeyValueEntry	KeyValue	—
颜色	ColorEntry	ColorPicker	ColorColumn
图像 / 头像	ImageEntry	FileUpload	ImageColumn
图标 / 布尔值	IconEntry->boolean()	Toggle / Checkbox	IconColumn->boolean()
可重复集合	RepeatableEntry	Repeater / Builder	关系管理器
富文本 / Markdown 文本	TextEntry->markdown()	RichEditor / MarkdownEditor	TextColumn->limit()
字符串列表	TextEntry->listWithLineBreaks()	TagsInput	TextColumn->badge()¹
静态文本 / 通知框	Text / Callout	Text / Callout	—
“此处暂无内容”	EmptyState（架构）	—	->emptyStateHeading()

¹ 对数组转换的列表使用徽章；不要将此模式应用于普通字符串列。

精确签名和官方链接见 references/。代码片段均为重点示例，除非展示完整类；请根据目标项目补充所需的导入和类上下文。

参考资料路由

仅加载任务所需的文件：

任务涉及	阅读
资源生成、导航、URL、授权、架构 / 表格提取	references/resources.md
只读显示、View 页面、条目	references/infolists.md
表单字段、编辑、验证	references/forms.md
表格列、筛选器、空状态、布局	references/tables.md
分区、网格、选项卡、向导、摘要、通知框	references/layout.md
按钮、模态框、批量 / 行操作	references/actions.md
仪表板、统计数据、图表、表格组件	references/widgets.md
相关记录	references/relation-managers.md
面板标识、导航、多个面板	references/panels.md
闪存、数据库和广播通知	references/notifications.md
共享状态 / 选项枚举、标签、颜色和图标	references/enums.md
上传、行内编辑、HTML、操作、导入 / 导出、多租户和授权边界	references/security.md — 安全敏感界面必读
自定义页面、集群、多租户、全局搜索、导入 / 导出、插件、嵌套 / 单例资源	references/advanced-features.md
页面、架构、表格、操作、关系、组件和租户的 Pest/Livewire 测试	references/testing.md
查找官方 Filament 5 截图，为组件的呈现方式提供依据	references/screenshots.md
Filament 5 界面应采用哪种组合方式——排列、响应式呈现、视觉审查	laravel-filament-v5-ui-ux

如果未涵盖某个 Filament 特定主题，请使用证据协议，而不要根据一般 Laravel 或较旧 Filament 的知识重构 API。

常见替代方案

官方原语适用时应避免	建议使用
用 <pre> 加自定义语法 CSS 显示代码/JSON	CodeEntry
手写状态 <span>	badge() 加上 HasLabel / HasColor / HasIcon 枚举
对关联数组元数据使用 @foreach	KeyValueEntry
对重复的只读记录使用 @foreach	RepeatableEntry
自定义颜色色块或头像标记	ColorEntry / ImageEntry
手动格式化日期或金额	dateTime() / money()
自定义剪贴板 JavaScript	copyable()
手动实现提醒或空状态	Callout / EmptyState / 表格空状态 API

CodeEntry 需要可选的 phiki/phiki 包。请先检查锁定文件。只有在获准实施且项目接受新增包时，才添加该依赖；否则应说明此项要求，但不要修改依赖项。

Filament v5 不变量

在 v5 代码中不要使用看似合理的 v3/v4 API：

• 使用 $schema->components([...]) 配置 schema。资源的 form() 和 infolist() 方法是静态方法；页面专用的 ViewRecord::infolist() 方法是实例方法。
• 从 Filament\Schemas\Components\* 导入布局组件和工具类；从 Filament\Forms\Components\* 导入表单字段；从 Filament\Infolists\Components\* 导入信息列表条目；从 Filament\Tables\* 导入表格列/筛选器；从 Filament\Actions\* 导入操作。
• 使用 recordActions()、toolbarActions() 和 groupedBulkActions()，而非 v3 表格的 actions() / bulkActions()。
• 使用 schema() 配置操作模态框字段，而不是旧的 form() 方法。
• 在 PHP 中使用 Filament\Support\Icons\Heroicon 表示 Heroicons。对于已安装的第三方/自定义图标集和有文档说明的 Blade API，请保留有效字符串。
• 当领域状态在多个界面共用时，复用实现了 HasLabel、HasColor 和 HasIcon 的有值枚举；完整模式和精确契约请阅读 references/enums.md。
• 优先使用 hiddenOn()、visibleOn() 和 disabledOn()，前提是它们能直接表达对应操作。仅在有文档说明时使用 Operation 枚举值；工具回调接收有文档说明的字符串操作。
• 谨慎处理文件可见性：除非所选磁盘命名为 public，否则上传内容默认为私有。更改上传行为前请阅读 references/security.md。

安全检查关卡

更改任何上传、可内联编辑的列、原始 HTML、关系附加/关联流程、导入/导出、批量操作、租户范围查询、授权规则或敏感表单字段之前，请加载 references/security.md。不要将 UI 可见性、禁用字段、经过筛选的选项或已显示的表格查询视为安全边界。在服务端强制执行不变量，并在适用时添加授权失败或跨租户测试。

验证

更改后，请加载 references/testing.md 并运行范围最小且相关的测试。根据适用情况，覆盖每个受影响的 Livewire 宿主和行为：页面加载、schema 状态、验证、表格查询、操作、通知、关系管理器、授权或租户隔离。项目有可用的格式化工具和静态分析工具时，请运行它们。检查最终差异，确认没有意外的自定义标记、过时的命名空间、重复反馈、缺失的导入或无关更改。

仅进行审查时，请提供包含文件/行号证据的发现，不要修改项目。

证据协议

每当 API、签名、命令、默认值或兼容性细节很重要时，请按以下顺序查证：

1. 已安装项目的证据： 锁文件中的精确版本、现有可运行代码，以及 vendor/filament/ 下与版本匹配的源代码。
2. Filament 官方文档： 使用 https://filamentphp.com/docs/llms.txt 查找相关页面，然后获取其 https://filamentphp.com/docs/5.x/{section}/{page}.md 形式的文档。
3. 精确的上游源代码： 当次要版本的行为很重要时，检查与已安装软件包匹配的 Git 标签或提交。
4. 文档聚合器： Context7 和 Laravel Boost 的 search-docs 可用于查找资料，但不能作为最终依据。每次只查询一个概念，请求最接近的可用版本，并检查每个返回结果中的 Source:。仅接受明确标注为 Filament 5.x 或精确已安装标签的来源；排除任何 3.x、4.x、未标注版本、社区镜像或相互冲突的代码片段。

如果证据相互冲突，应优先采用与已安装版本匹配的源代码，而非滚动更新的 5.x 文档，说明其中的不一致，并确保实现与项目兼容。如果签名仍未得到验证，不要猜测或留下推测性代码；请说明哪些内容无法确认。