create-engine

创建引擎

当任务是创建、搭建脚手架或重构 Rails 引擎、Rails 插件或引擎 gem 时，使用此技能。

将此技能聚焦于结构和设计。安装程序细节、深入测试覆盖、发布工作流或文档工作，请使用相邻技能。

快速参考

引擎类型	适用场景
普通 gem	不需要 Rails 钩子或应用目录；纯 Ruby 库
Railtie	需要 Rails 初始化钩子，但不需要模型、控制器、路由或视图
引擎	需要 Rails 自动加载路径、初始化器、迁移、资源、任务或宿主集成
可挂载引擎	需要自有路由、控制器、视图、资源和命名空间边界

硬性门槛

Before engine work is complete, confirm all of the following:

STRUCTURE & CONTRACT:
1. Root file requires only version, configuration, and engine.
2. Public engines use isolate_namespace; configuration exposes .configure block.
3. Host model references are configurable strings (e.g., "User"), never hard-coded ::User.
4. Host-app contract is documented (see Host App Contract section).

SAFETY CHECKS:
5. Engine code never auto-applies migrations at boot (no db:migrate, ActiveRecord::Migrator, or config.paths['db/migrate'] in initializers).
6. Initializers are idempotent and safe in development reloads.
7. Assets and generators are namespaced and idempotent.

VERIFICATION COMMANDS:
8. Dummy app exists: `ls spec/dummy` or `ls test/dummy` should return the app directory.
9. Integration tests pass: `bundle exec rspec` or `bundle exec rake test` exits 0.
10. Routes load correctly: `bundle exec rails routes` inside dummy app shows engine routes.
11. No hard-coded host constants: `grep -r "::User\|::Employee" lib/ app/` returns nothing.
12. No migration auto-apply patterns: `grep -r "db:migrate\|ActiveRecord::Migrator\|config.paths\['db/migrate'\]" lib/` returns nothing.

核心流程

1. 编写代码前先确定引擎类型。使用正确的生成器搭建脚手架：

   rails plugin new my_engine --mountable   # mountable engine
   rails plugin new my_engine --full        # full engine (non-isolated)
   rails plugin new my_engine               # plain Railtie/gem
   

2. 定义宿主应用契约（宿主必须提供什么、引擎会公开什么、支持哪些扩展点）。完整契约模板请参阅 reference.md。
3. 创建最小引擎结构。检查点： 在引擎目录中运行 bundle exec rake 必须通过。
4. 在命名空间下实现功能。检查点： 在虚拟应用的路由中挂载引擎，并通过 bundle exec rails routes 验证。
5. 通过虚拟应用编写最低限度的集成覆盖。覆盖要求请参阅 TESTING.md。
6. 清晰记录宿主应用契约，以便后续工作接续。

如果用户未指定引擎类型，请根据所需行为推断，并说明你选择的类型。

扩展资源

• reference.md — 完整的宿主应用契约模板、推荐文件结构和代码脚手架示例
• EXAMPLES.md — 扩展引擎示例
• TESTING.md — 覆盖要求和虚拟应用设置
• assets/examples.md
• assets/release-checklist.md

输出风格

当被要求创建或搭建 Rails 引擎脚手架时，你的输出 answer.md 必须遵循以下风格：

1. 具体产物文件：展示完整生成的 .gemspec 和 Rakefile 内容，并确保其命名空间正确归属该引擎。
2. 验证与 Rake 状态：明确说明在引擎目录中运行 bundle exec rake 会通过（退出码为 0），并附上模拟的通过输出块。
3. 集成测试覆盖：编写集成规格，覆盖配置、路由、HTTP 请求流程、领域服务和宿主集成钩子。所需规格类别和路径请参阅 TESTING.md。模型和服务的单元测试应与请求／集成规格分开。
4. 语言：除非明确要求使用其他语言，否则必须使用英语。

集成

技能	适用场景
test-engine	虚拟应用设置、集成测试、回归覆盖
review-engine	优先列出发现项的审查、结构审查
document-engine	README、安装指南、宿主应用契约文档
create-engine-installer	生成器密集型设置、安装脚本、复制迁移
generate-api-collection	引擎公开 HTTP 端点时（生成／更新 Postman 集合）