1. 项目概述为AI编程助手定制Flutter开发规则库如果你是一名Flutter开发者并且正在使用Cursor、Windsurf这类集成了大型语言模型的AI编程助手那你一定遇到过这样的场景你让AI帮你生成一个Bloc状态管理的代码结果它给你写出了一个老旧的、基于Bloc类的版本而你实际使用的是flutter_bloc8.0以上版本需要的是基于Cubit和Bloc的新API。或者你希望AI在编写Firebase相关代码时能自动遵循你们团队约定的项目结构比如使用FlutterFire CLI初始化并将配置放在lib/firebase/options目录下。每次都需要在提示词里重复这些冗长的规则不仅效率低下还容易出错。这正是evanca/flutter-ai-rules这个开源项目要解决的问题。它不是一个普通的代码库而是一个专门为AI编程助手如Cursor、Windsurf、Antigravity等设计的、高度结构化的“规则与技能”知识库。其核心目标是将Flutter和Dart开发中的最佳实践、官方规范、特定包的使用约定转化为AI能理解和遵循的指令集。简单来说它就像是为你的AI助手编写的一份详尽的“公司开发规范”或“项目脚手架说明书”让AI生成的代码从一开始就符合你的预期减少返工提升开发的一致性和效率。这个项目最大的特点是“非主观性”。它不掺杂维护者个人的编程偏好或风格其所有内容均严格源自Flutter、Dart以及各流行包如Bloc、Riverpod、Firebase的官方文档。这确保了规则的权威性和普适性你可以将其视为一个纯净的“官方规范萃取器”。当然你也完全可以基于这些基础规则进行个性化的裁剪和扩展以适应自己团队的特殊需求。2. 核心设计思路模块化与场景化驱动这个项目的架构设计非常清晰体现了现代开发工具“即插即用”和“场景驱动”的理念。它不是提供一个庞杂、单一的规则文件让你无从下手而是通过两种主要的组织形式来适应不同的使用场景技能和规则。2.1 技能动态、上下文感知的智能助手技能是该项目目前主推的、更先进的使用方式。它基于一个开放的技能标准其设计哲学是让AI助手能够根据你当前任务的上下文自动选择合适的指导而不是被动地应用所有静态规则。一个技能本质上是一个包含SKILL.md文件的文件夹。这个Markdown文件里写满了针对特定任务的详细指令。例如可能有一个名为bloc_testing的技能其SKILL.md中详细说明了如何使用bloc_test包编写Bloc单元测试和组件测试包括Mock的使用、setUp和tearDown的规范、以及如何验证特定状态和事件的发射。当你将技能文件夹例如skills/bloc_testing/复制到IDE的特定目录如.cursor/skills/后神奇的事情发生了。当你对AI说“为这个登录功能的Cubit写一些测试”AI助手会自动扫描可用的技能识别到bloc_testing技能与“写测试”和“Cubit”相关于是它会在生成代码时主动应用该技能文件中的所有规范。你无需在提示词中手动引用任何规则文件整个过程是隐式且智能的。这种方式的优势显而易见降低心智负担开发者无需记忆或手动指定该用哪条规则。提升精准度AI只在相关任务上应用特定规则避免了无关规则可能造成的干扰或冲突。易于扩展社区可以不断贡献新的技能如skills/firebase_auth/,skills/riverpod_providers/形成一个不断增长的、针对细分领域的智能指令库。2.2 规则静态、可组合的规范片段规则是更传统、更直接的控制方式。项目中的rules/目录下存放了大量独立的Markdown文件每个文件聚焦于一个非常具体的主题。例如rules/bloc.md: 包含Bloc库的最新使用模式、文件夹结构建议、事件/状态命名规范。rules/effective_dart.md: 浓缩了Dart官方风格指南的核心要点。rules/firebase.md: 详细说明了如何使用FlutterFire CLI初始化、多环境配置、以及各服务如Firestore、Auth的初始化代码模板。这些规则文件的特点是高度模块化和可组合性。你可以像搭积木一样根据项目需要选取几个规则文件将它们的内容合并然后粘贴到IDE的全局或项目级规则设置中。例如一个典型的Flutter项目可能会组合effective_dart.md、riverpod.md和mocktail.md这三个规则。为了方便用户快速上手项目还提供了combined/目录里面是一些预配置好的、常用的规则组合包比如flutter_dart__under_6K.md。这些组合包被精心控制在6000字符以内主要是为了兼容Windsurf等IDE对规则文本的长度限制。你可以直接复制整个文件的内容使用。2.3 设计背后的考量为什么选择这种结构这种“技能规则”的双轨制设计背后有深刻的实用性考量。首先区分动态与静态需求。有些规范是普适的、始终需要的比如代码风格Effective Dart。这些适合作为静态规则全局启用。而有些知识是任务特定的、深度的比如“如何搭建一个完整的Firebase Cloud Functions调用链”这只在相关任务中出现适合做成技能避免污染其他任务的上下文。其次应对AI的上下文窗口限制。大型语言模型有输入令牌数的限制。如果把所有Flutter开发规范都塞进一条规则很快就会超出限制导致AI无法看到全部指令或者挤占了分析现有代码的空间。模块化允许用户按需加载只把当前最相关的规范喂给AI最大化利用有限的上下文窗口。最后便于维护和社区贡献。每个技能或规则文件都相对独立指向明确的官方文档源。当Flutter或某个包发布重大更新时只需更新对应的文件即可不会影响其他部分。社区成员也可以轻松地为新的包如go_router、isar提交新的规则或技能使整个知识库保持活力。3. 四种实战使用路径详解了解了项目的设计思路后我们来看看具体怎么用。项目提供了四种清晰的使用路径从全自动到完全手动总有一款适合你。3.1 路径一技能全自动部署推荐这是最“未来感”的用法旨在实现开箱即用、智能辅助。操作步骤定位技能目录打开你的项目根目录查看IDE是否已经生成了技能文件夹。对于Cursor通常是.cursor/skills/对于Windsurf是.windsurf/skills/。如果目录不存在手动创建即可。挑选并复制技能克隆或下载flutter-ai-rules项目进入其skills/文件夹。你会看到一系列以功能命名的子文件夹如bloc/,firebase/,riverpod/等。将你需要的整个文件夹复制到上一步的IDE技能目录中。例如cp -r path/to/flutter-ai-rules/skills/bloc ~/my_project/.cursor/skills/。验证与使用完成复制后重启你的IDE或AI助手会话以确保其重新加载技能。之后当你提出相关任务时AI就会自动调用这些技能。例如你新建一个文件login_cubit.dart并说“请为这个Cubit生成对应的状态和事件类”AI在生成代码时就会自动遵循skills/bloc/SKILL.md中关于状态/事件类应定义为sealed class、使用part文件等规范。实操心得技能生效的关键在于任务描述的清晰度。对AI说“写个Bloc”可能不够精确而说“请使用flutter_bloc库为用户个人资料页面创建一个遵循BLoC 8.0模式的ProfileCubit包含加载、成功、错误三种状态”则能更精准地触发bloc技能。建议在初期可以故意提出一些模糊请求观察AI是否调用了正确的技能以此来检验你的技能部署是否成功。3.2 路径二使用预组合规则包快速启动如果你使用的AI IDE对技能的支持还不完善或者你更喜欢传统的、全局生效的规则方式那么预组合规则包是最快的方式。操作步骤选择组合包进入项目的combined/目录。这里有几个已经打包好的文件如flutter_dart__under_6K.md包含Flutter架构和Dart风格的核心规则。选择一个最符合你项目技术栈的文件。导入IDE规则打开你AI IDE的规则设置界面。在Cursor中可以通过命令面板Cmd/CtrlShiftP搜索“Open Global Rules”或“Open Workspace Rules”。将选中的组合规则文件的内容全部复制粘贴到规则编辑框中。生效测试规则生效后你可以进行简单测试。例如让AI生成一个Dart函数观察其参数和返回值类型声明是否符合Effective Dart的约定比如使用void表示不返回值而不是Null。注意事项combined/下的文件有字符数限制主要是为了Windsurf。这意味着它们是精华版的浓缩。如果你发现某个方面的规则不够详细可以回到rules/目录下找到对应的独立文件将其内容补充到你的规则中。同时要注意规则冲突比如如果同时引入了bloc.md和provider.md中关于项目结构的不同建议AI可能会感到困惑。通常建议一个项目主要遵循一种状态管理库的规则。3.3 路径三引用独立规则文件精细控制对于有经验的开发者或者项目有非常特殊的要求直接引用独立的规则文件能提供最大的灵活性。操作步骤克隆或下载规则库将整个flutter-ai-rules仓库克隆到本地或者直接下载rules/文件夹。在提示词中精确引用当向AI提出复杂需求时在提示词中直接指定需要参考的规则文件。例如“请阅读./rules/firebase.md中关于Firestore安全规则的部分然后为我的‘用户’集合设计一套允许用户仅读写自己文档的规则。”作为PRD的一部分在团队协作中可以将这些规则文件的部分内容整合到产品需求文档中作为对AI助手或开发者的明确技术约束。例如在PRD的“技术规范”章节写明“状态管理请参考rules/riverpod.md中的‘AutoDispose Provider使用规范’和‘状态通知器命名约定’。”这种方式将AI助手变成了一个“超级实习生”它不仅会写代码还会在动手前认真阅读你给它的“工作手册”规则文件。3.4 路径四命令行一键获取技能对于喜欢终端操作、或者希望将技能库的获取集成到项目初始化脚本中的开发者项目提供了一个非常便捷的命令行方法。操作命令解析git clone --depth 1 https://github.com/evanca/flutter-ai-rules.git temp_repo mkdir -p .skills cp -r temp_repo/skills/* .skills rm -rf temp_repo这条命令是一个组合命令依次执行了以下操作git clone --depth 1 ... temp_repo: 以浅克隆只下载最新一次提交的方式将仓库下载到一个临时文件夹temp_repo中速度最快不包含历史记录。mkdir -p .skills: 在当前目录创建一个名为.skills的隐藏文件夹-p参数确保如果文件夹已存在则不会报错。cp -r temp_repo/skills/* .skills: 将临时仓库里skills/目录下的所有内容递归地复制到新建的.skills文件夹中。rm -rf temp_repo: 删除临时的仓库文件夹清理现场。执行完毕后你项目的根目录下就会有一个包含所有技能的.skills文件夹。之后你可以在Cursor或Windsurf中配置让其从这个自定义的.skills目录加载技能或者如前所述在提示词中手动引用如“参考.skills/bloc/SKILL.md为这个事件添加一个copyWith方法。”避坑技巧如果你在团队中工作可以考虑将这个命令行写入项目的README.md或setup.sh脚本中确保每位成员都能一键获取到最新、统一的AI辅助技能库这对于保持团队代码风格的一致性非常有帮助。4. 规则内容深度解析与定制指南仅仅知道如何使用还不够理解这些规则文件里到底写了什么以及如何根据自己的需求进行定制才能发挥其最大威力。4.1 规则文件的典型结构剖析我们以rules/bloc.md为例看看一个高质量的规则文件包含哪些内容。它绝不仅仅是API文档的罗列。版本与范围声明开头会明确此规则基于flutter_bloc哪个版本例如^8.0.0以及覆盖的范围状态管理、导航等。核心概念与模式会强调BLoC 8.0的核心模式比如区分Cubit用于简单逻辑和Bloc用于复杂事件流强调使用sealed class来定义事件和状态以实现穷尽性检查。项目结构建议lib/ ├── features/ │ └── login/ │ ├── data/ │ ├── domain/ │ └── presentation/ │ ├── cubit/ │ │ ├── login_cubit.dart │ │ └── login_state.dart │ └── views/规则会给出一个推荐的特性文件夹结构并解释为什么将cubit和state放在presentation层。代码生成模板提供Bloc/Cubit、事件、状态类的代码模板包括必要的导入、类定义、构造函数和核心方法mapEventToState或emit的骨架。测试规范详细说明如何用bloc_test包编写测试包括如何模拟mock、如何设置测试用例、如何验证状态序列。通常会附带一个完整的测试用例示例。常见反模式与陷阱列出AI容易犯的错误例如“不要直接在新的emit调用后访问state因为状态是异步更新的。如果需要基于新状态做操作使用emit后的.then回调或监听stream。”官方链接在文件末尾一定会附上所有参考的官方文档链接确保溯源清晰。4.2 如何基于官方文档定制你的规则项目的基石是官方文档但你的团队可能有自己的特殊约定。定制规则是必然的一步。定制流程复制并重命名将原规则文件如rules/riverpod.md复制一份重命名为rules/riverpod_myteam.md。增量修改在复制的基础上进行修改。例如官方Riverpod文档可能建议使用StateNotifier但你的团队经过实践发现对大部分场景StateProvider和FutureProvider更简单高效。你就可以在规则中明确写出“对于简单的值同步优先使用StateProviderT对于异步数据获取使用FutureProviderT仅在状态逻辑复杂且包含多个方法时考虑StateNotifierProvider。”添加团队规范加入你们团队独有的约定。比如“所有Provider的变量名必须以_开头并在末尾加上Provider如final _userProfileProvider StateProviderUserProfile?((ref) null);” 或者 “使用riverpod_generator进行代码生成时生成的.g.dart文件必须被添加到.gitignore中。”测试规则有效性修改后创建一个简单的测试提示词比如“用Riverpod创建一个计数器Provider”看看AI生成的代码是否符合你的新规则。如果不符检查是你的规则描述有歧义还是AI没有正确理解。重要提示在定制时尽量保持规则的原子性和单一职责。不要把一个关于状态管理的规则和关于网络请求的规则混在一个文件里。这样便于维护和组合。如果你创建了一个综合性的团队规则可以考虑将其放入combined/目录供新项目快速引用。4.3 处理规则间的潜在冲突由于规则严格遵循不同包的官方文档冲突有时难以避免。最典型的例子是项目结构。Bloc官方推荐的是一种按“特性”组织的结构可能包含data、domain、presentation分层。Firebase官方示例可能为了简洁将所有Firebase相关的初始化、服务和工具类放在一个firebase目录下。你的团队现有项目可能采用的是另一种简单的models、views、controllers结构。当AI同时接收到这些结构建议时它可能会生成混乱的代码。解决方案是优先级覆盖。明确主规则在你的全局或项目规则中首先定义最高优先级的项目结构规则。例如第一段就写明“本项目采用简洁的MVC结构lib/models/,lib/views/,lib/controllers/。所有其他包的使用都应适配此结构。”在技能中做适配在具体的技能文件里可以根据主规则进行适配说明。例如在skills/firebase/SKILL.md中可以写“在本项目中请将Firebase初始化文件置于lib/controllers/firebase/目录下Firestore数据模型置于lib/models/firebase/目录下。”在提示词中即时指定对于一次性的任务如果担心冲突直接在提示词中明确路径“请创建一个用户认证的Bloc按照我们项目的MVC结构请将文件放在lib/controllers/auth/目录下。”通过这种分层策略你可以确保AI在宏观上遵循团队约定在微观上遵循特定包的最佳实践。5. 高级应用与团队协作场景将flutter-ai-rules用于个人项目能极大提升效率但它的价值在团队协作中更能被放大。5.1 在团队中建立统一的AI辅助规范创建团队规则仓库Fork官方的flutter-ai-rules仓库将其作为你们团队内部规则库的基础。集体定制在团队内部进行讨论对核心的规则文件如代码风格、项目结构、状态管理选择进行定制形成团队的“黄金标准”。这个过程本身也是统一技术思想的好机会。集成到开发流程新人入职新成员搭建环境时除了安装Flutter、Dart还需要运行一键脚本获取团队的AI技能库并配置好IDE的全局规则。这能让他们从写第一行代码开始就符合规范。代码审查在PR描述中可以要求作者注明是否使用了AI生成以及引用了哪些规则/技能。审查者可以据此检查生成的代码是否严格遵循了既定规范。持续集成虽然AI规则本身不直接参与CI但可以编写脚本检查项目中是否存在未配置的AI规则文件或者检查生成的代码是否违反了某些核心规则例如通过静态分析工具检查Dart风格。5.2 与AI助手进行“深度对话”超越代码生成这些规则和技能不仅能用于生成代码还能用于更复杂的开发任务。代码重构你可以对AI说“参考.skills/effective_dart/SKILL.md重构这个老旧的Widget类将其拆分为更小的、可复用的StatelessWidget并应用最新的空安全语法。”编写测试“阅读rules/mocktail.md然后为这个UserRepository类编写完整的单元测试覆盖成功、网络错误和解析异常三种情况。”架构设计咨询“基于rules/flutter_app_architecture.md和rules/riverpod.md为一个小型电商应用设计一个前端架构图并列出核心的Provider和目录结构。”故障排查“根据rules/common_errors.md中‘Rendered more than 60 frames’的章节分析我这段动画代码可能存在的性能问题并提供优化建议。”通过这种方式AI助手从一个单纯的代码补全工具升级为了一个随时在线的、熟知团队规范和技术栈的“高级开发伙伴”。5.3 贡献回馈社区如果你根据官方文档更新或创建了一个非常棒的技能回馈给社区是开源精神所在。贡献步骤Fork仓库在GitHub上Forkevanca/flutter-ai-rules项目。创建分支为你的修改创建一个特性分支。添加或修改新增技能/规则如果是针对一个新包如go_router请在skills/或rules/目录下创建新的文件夹或文件。确保你的内容严格基于该包的官方最新文档并在文件末尾附上文档链接。修改现有内容如果Flutter/Dart或某个包发布了重大更新导致现有规则过时请及时更新。同样需要引用新的官方文档链接。提交Pull Request提交PR时在描述中清晰说明你的修改内容、原因以及引用的官方来源链接。维护者会进行审核确保内容的客观性和准确性。通过社区的共同维护这个规则库才能覆盖更广的技术栈跟上生态发展的步伐让所有Flutter开发者受益。6. 常见问题与排错实录在实际使用中你可能会遇到一些问题。以下是一些常见情况的排查与解决思路。问题一复制了技能但AI好像完全没调用检查路径首先确认技能文件夹被正确复制到了IDE识别的目录下如.cursor/skills/并且目录结构是skill_name/SKILL.md。重启会话AI助手可能会缓存可用的技能列表。尝试完全关闭并重新打开IDE或者至少开启一个新的AI聊天会话。验证技能格式打开SKILL.md文件确保其内容是可读的Markdown并且包含清晰的任务描述和指令。AI通常根据文件名和文件内容中的关键词来匹配技能。任务描述关键词在你的任务描述中使用与技能相关的关键词。例如技能文件夹叫firebase_firestore你的提示词里最好包含“Firestore”这个词。问题二规则太多导致AI响应变慢或出错精简规则这很可能是因为你一次性加载了太多规则占用了大量上下文令牌。回顾你的全局规则移除当前项目不直接相关的部分例如一个纯前端项目可能不需要详细的rules/firebase_functions.md规则。使用技能替代将一些大型的、场景特定的规则集转化为技能。让AI在需要时动态加载而不是始终放在上下文中。分组合并如果多个小规则文件经常一起使用可以考虑将它们合并成一个稍大的、但字符数仍在限制内的组合文件减少文件数量带来的开销。问题三AI生成的代码与规则要求有细微出入规则清晰度检查你的规则描述是否足够清晰、无歧义。避免使用“应该”、“最好”这类模糊词汇改用“必须”、“总是”、“禁止”等强制性措辞。例如将“事件类最好使用sealed class”改为“事件类必须定义为sealed class”。提供示例在规则中对于复杂的模式除了文字描述一定要提供一个完整的、可运行的代码示例。AI通过示例学习的效果远好于纯文本描述。迭代提示如果第一次生成不满意不要直接重写。可以指出问题并让AI修正“你生成的State类没有重写toString方法。请根据rules/bloc.md中关于调试的要求为每个状态添加toString方法。”问题四如何管理不同项目有不同的规则项目级规则大多数AI IDE如Cursor都支持项目级Workspace规则其优先级高于全局规则。你可以在每个Flutter项目的根目录下放置一个.cursor/rules文件或IDE对应的规则文件里面只包含这个项目特有的规则。符号链接如果你有一套核心规则想在多个项目间共享可以在每个项目的规则目录中创建一个指向共享规则文件的符号链接软链接。这样更新共享文件所有项目都会同步更新。环境变量或脚本对于更复杂的场景可以编写一个简单的shell脚本根据项目类型如“firebase_project”、“plugin_project”自动复制或组合对应的规则文件到项目目录中。问题五规则与最新包版本不兼容定期更新关注你所用核心包Flutter, Dart, bloc, riverpod等的版本更新。当有重大突破性变更时需要手动检查并更新对应的规则文件。语义化版本在规则文件开头注明其适用的包版本范围例如“适用于riverpod: ^2.0.0”。这能给你和你的队友一个清晰的预期。社区同步定期查看flutter-ai-rules原仓库的更新。如果发现官方仓库已经更新可以将更改合并到你团队的派生仓库中。通过系统地应用这些规则和技能你不仅能显著提升个人开发效率更能为团队引入一种可重复、可验证、高质量的人机协作编码范式。这不仅仅是关于让AI写代码更是关于如何将人类的最佳实践和知识有效地“编程”给AI使其成为团队中一个稳定可靠的生产力伙伴。