开发自定义扩展

自定义扩展适用于需要独立启停、配置、迁移或贡献平台能力，或需要贡献平台能力的模块。普通业务 CRUD 可直接使用应用路由与服务，无需将所有业务都包装成扩展。

创建扩展骨架

从独立应用的 server 目录运行：

go run ./cmd/modu new-extension sample

在 application.Options().Extensions 中追加生成的 Manifest 与 NativeRegistration，并补充真实贡献。应用 CLI 使用 new-extension，与核心开发 CLI 不同。

声明与资源获取

Manifest 描述身份、版本、依赖、权限和贡献。Registration 只构造声明、惰性 factory 与 binder；资源在受控生命周期内获取和释放。

扩展实现不使用 init()，不在包变量中立即初始化资源，也不绕过宿主注入读取其他应用实现。应用装配可将 sdk.ExtensionData 作为宿主 factory 注入扩展。

这些约束让静态检查能够读取声明，而不连接数据库、运行迁移或执行副作用。

参考回执扩展

模板的 app.module/receipt 包含自有表、GET /api/v1/receipts、/example/receipts 惰性页面，以及 app.receipt typed workflow action。

它默认停用，需要在扩展管理显式启用。工作流操作持久化请求 key、digest 与结果；同一请求可查询已有回执，停用后的旧 handle 与 API 会按平台语义拒绝调用。

添加有副作用的动作时，设计稳定请求键、参数摘要、幂等回执和无副作用查询。超时或普通错误不能当作“确定没有执行”。

生成与检查 catalog

go run ./cmd/modu catalog generate
go run ./cmd/modu catalog check
go run ./cmd/modu doctor
go run ./cmd/modu check

catalog 从实际后端装配生成到 ../web/src/extensions/catalog.json，包含核心与应用的最终安装集合。提交生成结果，不手工维护第二份清单。

doctor 与 check 是静态装配检查。static_only: true 表示没有执行资源 factory、迁移或生命周期；检查通过不代表运行健康。check 还核对当前安装的前后端版本。

下一步接入扩展页面，再实际启用、停用扩展，验证权限、状态变化与既有数据。