插件开发入门：清单、沙箱与生命周期

插件用于承载不适合写进主题的业务能力，例如表单、统计、SEO 扩展或第三方服务对接。插件与主题分离，停用插件不会删除主题，也不会改动内容数据。

目录结构

my_plugin/
  plugin.json
  backend/
    main.star
  admin/
    index.html
  assets/
  README.md

plugin.json

{
  "id": "my_plugin",
  "name": "示例插件",
  "version": "1.0.0",
  "engine": ">=1.0.0",
  "permissions": ["content.read"],
  "template_tags": ["head"]
}

清单声明插件 ID、版本、权限和模板标签。插件 ID 会作为标签前缀，例如 {djm:my_plugin.head/}。

沙箱运行时

后端脚本运行在 Starlark 沙箱中，不能直接访问文件系统或任意网络，只能使用宿主提供的受控 API。需要新增能力时，应先评估权限与数据边界，而不是把敏感操作暴露成通用接口。

后台入口

插件可以提供后台页面，通过宿主路由与权限体系加载。页面运行在受控 iframe 中，静态子资源需要允许匿名读取，但业务接口仍必须校验管理员会话与权限。

生命周期

1. 安装：校验清单、签名与包结构，解压到 plugins/<id>。
2. 启用：注册权限、后台入口与模板标签。
3. 升级：按版本执行迁移，失败时保留检查点并可恢复。
4. 停用/卸载：停用立即停止运行；卸载前检查附件引用与数据依赖。

开发建议

• 先在本地开发环境开启开发者模式，再导入未签名插件。
• 把权限声明控制在最小范围，所有写操作都记录审计。
• 模板标签只返回数据，不拼接可执行 HTML；需要标记时交给核心校验。
• 为升级与回滚准备迁移脚本和检查清单。