入口与生命周期

这一页讲入口代码 plugin.ts 的写法：宿主在什么时候调用它、activate 函数里该按什么顺序做事、插件被停止时怎么收尾。看完你就能解释"插件为什么没出现"和"插件卸载后为什么还在跑"这两类问题。

前置条件

清单和生成类型已同步（改过清单就先 pnpm run generate）。

每个实际使用的宿主页面都有一个 src/hosts/<host>/activate.ts。

fh2-plugin-sdk 是插件开发 SDK；下文模块名用于说明，实际导入路径保留生成工程配置。模块名不表示已发布的 npm 包名。

唯一入口，按宿主分流

一个插件只有一个入口文件。宿主加载插件后会调用它的 activate(ctx) 函数；同一个插件可能被多个页面激活，用 ctx.host.id 判断当前在哪个页面：

// src/plugin.ts
import { definePlugin } from 'fh2-plugin-sdk'
import type { PluginContext } from 'fh2-plugin-sdk'
import type { AppCockpitContext, AppMessageContext, AppProjectContext } from './generated/plugin-types'

export default definePlugin({
  async activate (ctx: PluginContext) {
    switch (ctx.host.id) {
      case 'cockpit':
        return (await import('./hosts/cockpit/activate')).activate(ctx as AppCockpitContext)
      case 'project':
        return (await import('./hosts/project/activate')).activate(ctx as AppProjectContext)
      case 'message':
        return (await import('./hosts/message/activate')).activate(ctx as AppMessageContext)
      default:
        return undefined
    }
  },
})

三条规则：

入口的 default export 必须是 definePlugin(...) 的结果。

只给清单里实际声明了扩展点的宿主写分支。比如插件没有计划页扩展，就不要写 plan 分支。

动态 import() 只是把各页面代码拆成小包，不会产生第二个入口或第二套生命周期。不要把 Vue、DOM 操作或界面挂载依赖引进 plugin.ts。

activate 里的推荐顺序

每个 src/hosts/<host>/activate.ts 按这个顺序写，最不容易出错：

// src/hosts/project/activate.ts
import type { AppProjectContext } from '../../generated/plugin-types'
import { projectView } from '../../views/project-panel/contract'

export async function activate (ctx: AppProjectContext) {
  // 1. 取能力：可选能力可能拿不到（undefined），先处理缺席
  const project = await ctx.capabilities.get('project:context')
  if (!project) return

  // 2. 建立入口侧状态
  const snapshot = await project.getState()
  ctx.logger.info('当前项目', { projectId: snapshot.projectId })

  // 3. 注册界面处理函数（先于扩展提交，按钮打开界面时才不会落空）
  await projectView.handle(ctx, { /* state 与 methods，见界面与状态一页 */ })

  // 4. 提交扩展（按钮、面板……）
  await ctx.extensions.contribute('project-entry', {
    icon: 'plugin',
    label: '项目面板',
    disabled: snapshot.projectId === null,
    showBadge: false,
    render: () => projectView.get(ctx),
  })

  // 5. 最后启动订阅、定时器等持续型任务
}

不同宿主之间没有固定的激活顺序，不要假设"提供数据的宿主一定先激活"。

停止与收尾

插件被停止时（用户切走页面、插件被禁用或卸载、配置变更等），平台会先冻结运行时，再让你清理。冻结之后 ctx.apiCall 和 ctx.storage 会直接报 HOST_RUNTIME_DISPOSED，登记过的订阅也已经在回收，所以 dispose 里只做收尾，不要在里面保存数据。

需要落盘的草稿，在状态变化时写，不要等到退出：

// 跟着输入写，退出时什么都不用补
async function saveDraft (text: string): Promise<void> {
  await ctx.storage.local.set('draft', { text })
}

return {
  dispose () {
    controller.stop()   // 平台管不到的第三方资源
  },
}

平台会自动回收它登记过的资源：扩展、界面、定时器（ctx.timers）、平台事件和 WebSocket 订阅、跨宿主通信服务等。只有平台管不到的东西才需要你在这里清理，比如第三方 SDK 的控制器、硬件句柄。

停止原因 reason 的取值：

reason	含义
`host-unmount`	宿主页面卸载
`plugin-disabled`	插件被禁用
`plugin-uninstalled`	插件被卸载
`config-changed`	用户改了配置（之后会用新配置重新激活）
`activation-failed`	激活过程出错
`runtime-terminated`	运行时被强制终止

两个配合要点：

长异步操作每步检查 ctx.lifecycle.signal.aborted，已中止就尽快返回。

运行时停止后不要再更新界面状态——订阅已被回收，更新是无效写入。

日常命令与预期

预期：同一个插件在每个宿主里各有一份独立运行时（各自的 ctx、ctx.host.instanceId 和状态），一个页面卸载不影响另一个页面。在本地调试页面里逐个宿主切换验证。

常见问题

现象	原因与处理
激活没报错，但页面上什么都没出现	检查 `ctx.host.id` 分支是否覆盖了当前页面；`contribute` 的扩展 ID 是否与清单一致
能力调用不生效	`ctx.capabilities.get()` 可能返回 `undefined`（当前宿主没提供），必须有缺席分支
插件停了但第三方任务还在跑	平台只回收登记过的资源；第三方控制器要放进返回的 `dispose` 里停
改配置后插件"重启"了	正常行为：配置变更会停止旧运行时并用新快照重新激活
想在一个宿主里访问另一个宿主的变量	做不到，运行时互相独立；需要协作用跨宿主通信服务（见多宿主插件）

前置条件#

唯一入口，按宿主分流#

activate 里的推荐顺序#

停止与收尾#