Manifest

每个插件根目录都需要 manifest.json。它会用于安装、权限审核、打包、运行时加载和 catalog 发布。

Level 0 示例

{
  "id": "dev.example.my-plugin",
  "name": "My Plugin",
  "version": "0.1.0",
  "description": "Short user-facing summary.",
  "author": "Example",
  "compatibility": {
    "min_app_version": "0.8.0",
    "min_host_api_version": "0.2.13"
  },
  "capability_levels": [0],
  "host_capabilities": ["navigation", "file_intents", "theme_read"],
  "integration": {
    "level0": {
      "module_id": "my-plugin",
      "module_label": "My Plugin",
      "module_icon": "Sparkles",
      "sidebar_position": "main",
      "sidebar_order": 120,
      "panel_entry": "app/dist/index.js"
    }
  },
  "window": {
    "default_open_mode": "reuse_or_new",
    "reuse_key": "resource",
    "allow_multiple": true,
    "document_handlers": [
      {
        "id": "markdown",
        "label": "Markdown",
        "extensions": [".md", ".markdown"],
        "mime_types": ["text/markdown"],
        "route": "/document",
        "resource_param": "path"
      }
    ]
  },
  "entry": {
    "native": {
      "macos_arm64": "backend/target/release/libmy_plugin.dylib",
      "windows_x64": "backend/target/release/my_plugin.dll",
      "linux_x64": "backend/target/release/libmy_plugin.so"
    },
    "frontend": "app/dist/index.js",
    "frontend_styles": "app/dist/styles.css"
  },
  "permissions": [
    { "type": "ipc_register" },
    { "type": "host_theme_read" }
  ],
  "commands": [
    { "id": "ping", "description": "Return plugin health information." }
  ]
}

规则

id 发布后必须保持稳定。
version 使用 semver，官方插件初版从 0.1.0 开始。
host_capabilities 必须匹配前端实际使用的 SDK helper。
permissions 必须是最小权限集合。
entry.frontend 指向构建后的 JS bundle。
entry.frontend_styles 指向构建后的样式文件。
commands[].id 和 Rust 后端注册的命令名一致，不包含 SDK 自动前缀。

窗口策略

插件如果希望自己的路由或资源进入 HaloForge 多窗口分发，可以在 manifest 中声明 window 配置。

多窗口策略要求 HaloForge 0.8.0 或更高版本，以及 plugin host API 0.2.13 或更高版本。发布声明了 window 的插件时，要同步更新 compatibility.min_app_version 和 compatibility.min_host_api_version。

字段	含义
`default_open_mode`	`smart`、`current`、`new_window`、`reuse_existing` 或 `reuse_or_new`。
`reuse_key`	`plugin`、`route`、`resource` 或 `none`。
`allow_multiple`	是否允许同一插件同时存在多个窗口。
`document_handlers`	把扩展名或 MIME 类型映射到插件 route 的文件/资源 handler。

插件只声明意图；真正的窗口创建、聚焦、session restore、Windows snap layout 兼容和冲突处理仍由宿主负责。

document_handlers 条目支持：

字段	含义
`id`	插件内稳定唯一的 handler ID。
`label`	菜单和打开方式界面使用的用户可见名称。
`extensions`	带点的小写扩展名，例如 `.md`。
`mime_types`	插件支持的 MIME 类型。
`route`	打开资源时进入的插件 route。
`resource_param`	接收资源 path 或 URI 的 query 参数，默认是 `path`。
`open_mode`、`reuse_key`、`allow_multiple`	覆盖插件级窗口策略的 handler 级配置。

document_handlers 驱动的是宿主拥有的文件分发界面，例如「打开文件」和「打开方式」。不同来源的宿主命令仍然可以选择更严格的目标窗口：例如 File > Open Markdown 是当前窗口导航动作，而操作系统文件激活和 deep link 可以使用上面的多窗口策略。

应用菜单栏不是插件可直接控制的 DOM surface。截至 host API 0.2.13，插件不应假设自己可以任意向 File/Edit/View 菜单注入菜单项。如果插件需要菜单动作，应先新增文档化的 declarative manifest/SDK contribution，让 HaloForge 统一处理文案、权限、窗口目标和原生菜单行为。

常见 Host Capabilities

Capability	SDK
`navigation`	`useHostNavigation()`
`app_state`	`useHostAppState()`
`file_intents`	`useHostFileIntent()`
`file_dialogs`	`pickHostFile()` / `pickHostDirectory()` / `saveHostFile()`
`aichat`	`useHostAI()`
`enterprise_gateway`	`enterpriseGateway()`
`theme_read`	`useHostTheme()` / `useAppTheme()`
`event_subscribe`	`useHostEvent()`

enterprise_gateway 是托管生图网关的历史 capability 名称。产品 UI 应显示为 “HaloForge Cloud gateway” 或 “Managed gateway”，不要在社区版界面显示 “Enterprise gateway”。