开发自定义扩展

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

创建扩展骨架

从独立应用根目录运行，server:go 包装脚本负责进入 server/ 并设置私有源环境：

pnpm 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 注入扩展。

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

参考示例插件

完整的扩展样例在独立示例插件仓库 igwen6w/modu-example-plugin，以 Manifest app.module/example 接入，包含商品与物料附件、货币管理、员工报销与审批等业务模块，并演示了数据交换回调、附件字段与授权声明（Group、Audience、GrantMode 字段）。默认 starter 不含该插件，需要单独接入。

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

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

生成与检查 catalog

pnpm server:go run ./cmd/modu catalog generate
pnpm server:go run ./cmd/modu catalog check
pnpm server:go run ./cmd/modu doctor
pnpm server:go run ./cmd/modu check

此外还有 build-maintenance、access-policy、readiness 与 authorization 子命令，用于部署维护、访问策略、就绪检查与授权声明的生成核对。

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

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

扩展遵循的 CoreAPI 合同版本为 0.17.0，涵盖数据交换回调与授权声明的 Group、Audience、GrantMode 字段；Manifest 与 Registration 结构保持稳定，sdk.ExtensionData 仍作为宿主注入的数据入口。

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