FastAdmin插件开发：用AI Skill固化约定，一次生成可用插件-开发者社区

FastAdmin 社区最近有个很典型的现象：开发者用 AI 写插件，得到一大段 PHP，看起来格式完整，复制到addons/目录后，点“安装”就报错，或者页面 404。问题通常不在 PHP 语法，而是 FastAdmin 是一个很吃“约定”的框架——目录结构、类名大小写、数据库前缀、后台菜单规则、前端表格 URL 都得对齐。AI 没有这些上下文时，写出来的代码就是“代码层面正确、工程层面不可用”。

这篇文章想分享的不是又一段泛泛的 prompt，而是一种把 FastAdmin 插件开发规则沉淀成 AI Skill 的实践。我把 FastAdmin 的目录规范、字段约定、SQL 规范和安装检查项写进一个skill.md，让大模型在“聊插件需求”时直接按规则输出。整套流程跑顺之后，生成一个可安装的后台管理插件只需要一次对话、一次文件复制，再在 FastAdmin 后台点一次安装。下面会讲清楚 Skill 的设计思路、规则怎么写、完整示例和排错方法。

1. 先给结论：FastAdmin 插件开发天生适合做成 AI Skill

先说判断：FastAdmin 这种以“约定+生成”为核心的 PHP 后台框架，比普通 PHP 项目更适合用 AI 来生成代码，前提是你要把框架约定完整交给模型。

如果你是刚接触 FastAdmin 的开发者，可能觉得 AI 对话生成插件已经很方便。但真正在项目里工作过的人会发现，FastAdmin 的插件开发难点从来不是“写逻辑”，而是“守规矩”。比如：

插件主类文件名必须和目录名形成驼峰对应关系；
控制器里方法名必须和前端 URL 通过固定规则绑定；
数据库表通常要支持__PREFIX__占位符，避免默认前缀变动导致 SQL 失败；
后台页面返回 JSON 的字段格式要和前端table.js预期一致；
菜单与权限规则要在auth_rule表里注册。

这些规矩在官方文档里分散在不同页面，而大模型在训练时会把 FastAdmin 和其他 ThinkPHP 项目混在一起。你在对话框里说“帮我写一个插件”，模型只能凭概率推断，结果经常会生成一套通用 ThinkPHP 代码，而不是 FastAdmin 可安装插件。

因此，我更推荐用 Skill 解决“场景缺失”的问题。Skill 的本质是一份长期复用的任务协议，它把项目背景、命名规范、输出结构和自检清单固化下来，每次对话都让 AI 从这份协议出发，而不是从“大模型的模糊记忆”出发。

2. FastAdmin 插件到底难在哪里：约定比语法更重要

2.1 一个标准插件包的文件结构长什么样

FastAdmin 的 addons 插件一般有固定的目录骨架。简单理解，插件就是一个带安装、卸载、配置能力的模块目录。我第一次把插件需求交给 AI 时，模型生成的目录和 FastAdmin 实际需要的目录经常对不上。

FastAdmin 项目里插件目录的结构看起来类似：

your-fastadmin-project/ ├── addons/ │ └── demo_notice/ │ ├── DemoNotice.php │ ├── config.php │ ├── bootstrap.js │ ├── install.sql │ ├── uninstall.sql │ ├── controller/ │ ├── model/ │ └── view/ ├── application/ ├── public/ └── docs/

其中DemoNotice.php是插件主类，它负责声明插件的名称、版本、描述，并在安装/卸载时提供逻辑入口。install.sql和uninstall.sql处理数据库变更。bootstrap.js通常用于让前端模块感知插件存在。如果这些文件缺失或名称大小写不一致，后台插件管理列表可能根本识别不出这个插件，识别出来也会在安装阶段报错。

很多 AI 生成工具会忽略config.php和bootstrap.js，只给你一个控制器文件。控制器没问题，但插件系统无法把它当可用插件加载，这就是“聊出的代码不能落地”的一个重要原因。

2.2 表格：AI 写 FastAdmin 插件时最容易出问题的位置

容易出错的位置	常见错误	后果
插件主类	类名和目录名驼峰形式不一致	插件无法被识别
SQL 前缀	直接写死`fa_`，没有使用`__PREFIX__`	换了表前缀就报错
控制器命名空间	把插件控制器写成`app\admin\controller`	路径不匹配，路由 404
AJAX 返回格式	随意返回数组或字符串	列表页表格数据解析失败
菜单规则	没有提供权限规则初始化逻辑	插件安装后后台看不到入口
卸载脚本	直接删除表，没有考虑已有数据	生产环境误删风险高

2.3 稳定插件的 5 个维度

在把 “稳定” 作为 Skill 生成目标之前，我先定义了什么是“稳定”。这里不是指代码 bug 少，而是指以下五个维度都过关：

能识别：插件目录放在addons/后，后台插件管理列表能看到。
能安装：安装 SQL 能正确执行，表前缀被正确替换。
能访问：生成的后台页面 URL 和控制器路由一致，不出现 404。
能操作：列表、新增、编辑、删除等操作的数据格式符合 FastAdmin 前端容器预期。
能回滚：卸载脚本不会报错，且不会误删非授权数据。

这个定义很关键。因为 AI 无法判断自己生成的代码是否“稳定”，Skill 的价值就在于把上述维度变成可执行的检查清单。

3. Skill 和普通提示词的区别：不是“上下文”，而是“工作流”

很多人以为 Skill 就是把一大段背景知识塞给 AI，类似自定义系统指令。但其实 Skill 更接近“工作流定义”，而不只是“角色设定”。

举个例子，普通提示词可能是这样的：

你是一个 FastAdmin 开发专家，帮我写一个公告管理插件。

这种提示词的缺点很明显：模型只能依赖内部知识，无法保证它记得 FastAdmin 的表前缀规则，也无法保证它输出的控制器符合 FastAdmin 前端表格 JS 的调用格式。每次对话都要重新描述一次，项目里的新成员也无法复用同一套经验。

而 Skill 可以是一个结构化文件。它不仅有“背景知识”，还定义了模型接到需求后的处理顺序，比如：

先解析用户的功能需求；
整理出需要的数据库字段；
根据install.sql模板生成建表语句；
按控制器输出格式生成 PHP 逻辑；
输出安装检查清单。

这一个流程对应的就是人类开发者写插件的真实习惯：先建表，再写控制器，再接入前端，最后验证。AI 在 Skill 的约束下，不再“想到哪写到哪”，而是按一套已验证的步骤工作。

如果用一句话概括：提示词是让模型“知道”，Skill 是让模型“做到”。

FastAdmin 和 Skill 的组合之所以高效，是因为 FastAdmin 的核心工作方式就是“把重复开发流程标准化”。FastAdmin 的一键生成 CRUD，本质上就是把建表、生成控制器、生成视图、生成 JS 的流程自动化。AI Skill 做的事情与它同构，只不过把规则从 FastAdmin 源码里搬到了模型提示上下文中。

4. 环境准备：让 AI 拥有插件开发的“项目语境”

在动手写 Skill 之前，需要先准备两个环境。

4.1 FastAdmin 项目环境

本文不限定具体版本，请以你自己的 FastAdmin 项目为准。 FastAdmin 基于 ThinkPHP 5，运行环境通常需要 PHP 7.x，同时要能够正常配置伪静态和后台登录。你可以先准备一个干净的本地测试项目，不要在正式生产环境直接做插件安装实验。

如果你使用的 AI 客户端可以读取项目目录，建议把 FastAdmin 项目的源码目录加入 AI 的工作区。这样模型可以直接查看addons/目录下已有插件的真实结构，生成的代码会更有参考性。

4.2 Skill 文件存放目录

Skill 是一个纯文本目录，不依赖 FastAdmin 自身的插件机制。为了便于用 git 管理，推荐放在项目中如下位置：

your-fastadmin-project/ └── docs/ └── skills/ └── fastadmin-plugin/ └── skill.md

把 Skill 放进项目仓库有几层好处：

团队其他人拉取代码后，可以直接复用同一套插件生成规则；
FastAdmin 版本升级后，可以提交增量修改；
AI 客户端在工作区里能读取该文件，不需要每次复制粘贴一大段内容。

不同 AI 工具对 Skill 目录的读取方式不一样。如果你的工具不支持自动读取，最简单的方式是把skill.md的完整内容作为首条系统提示发送给模型。效果差别不大，核心在于内容质量。

5. 开发 Skill 的核心过程：把 FastAdmin 经验变成规则文件

下面是我整理一个 FastAdmin 插件生成 Skill 时的主要流程。你也可以按这个逻辑改造出适合作者自己项目的 Skill。

5.1 第一步：收集项目里的“硬性约定”

所谓硬性约定，是指那些一旦写错就会导致插件不可用的规则。我在自己的skill.md里至少固定了以下内容：

插件标识只能使用小写字母、数字、下划线；
主类文件名必须由插件标识驼峰化后得到；
插件表 SQL 中的前缀必须使用__PREFIX__占位；
后台管理页面中，模型保存失败时要返回模型错误，而不是简单返回false；
控制器继承自 FastAdmin 提供的后台基类，确保权限、登录态、日志等能力可用。

你不需要一开始就写全所有规则，可以从报错中逐步补充。比如“AI 生成的插件在安装时提示表不存在”，就把“SQL 前缀规则”加入 Skill；“AI 生成的页面列表 URL 不对”，就把“前端列表 URL 生成规则”加入 Skill。

5.2 第二步：给模型定义输出格式

FastAdmin 插件不像普通 GitHub 项目那样只有代码，还需要生成 SQL、控制器、模型、视图、JS。如果模型分不清先后顺序，输出就会乱。

我习惯让模型在生成前先输出一个“文件清单”，结构大致如下：

addons/demo_notice/ ├── DemoNotice.php ├── config.php ├── install.sql ├── uninstall.sql ├── controller/ │ └── Notice.php ├── model/ │ └── Notice.php └── view/ └── notice/ ├── index.html ├── add.html └── edit.html

先让模型列出文件结构，有助于检查它是否理解了需求。这个文件结构本身也可以作为一个模板，固化成 Skill 里的“默认工程结构”。