项目上下文

project:context 让插件读取当前项目、组织和用户信息，并在它们变化时收到通知。清单声明 project:context 权限，代码里 await ctx.capabilities.get('project:context') 获取并判空。只在项目宿主可用。

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

const project = await ctx.capabilities.get('project:context')
if (!project) {
  ctx.logger.warn('project:context 不可用')
  return
}

方法清单

方法	说明
`getState()`	返回当前状态快照
`onStateChanged(handler)`	订阅变化；注册后立即回调一次当前状态；返回可释放句柄

状态结构：

interface ProjectContextState {
  readonly projectId: string | null
  readonly organizationId: string | null
  readonly userInfo: {
    readonly org_role: string | null
    readonly project_role: string | null
    readonly user_id: string | null
    readonly nick_name: string | null
    readonly account: string | null
  }
}

字段说明：

字段为 null 是正常的过渡态（宿主刚挂载、项目切换中）。不要把 null 转成空字符串后继续发业务请求。

org_role 优先取项目用户里的组织角色，缺失时回退组织用户角色。

account 依次回退项目账号、组织账号。

集成片段

先按第一个前端插件建立可运行工程，再按项目侧栏扩展接入项目宿主。下面不是完整的 fh2-plugin.json，不可整份替换：将 permissions 去重合并到现有清单，保留现有项目宿主扩展、界面声明/注册和入口。权限不会触发激活；清单若只有 extensions: []，activate() 不会执行。

合并到 fh2-plugin.json 的字段：

{
  "permissions": ["project:context", "platform:http"]
}

下面的 definePlugin 只示范入口逻辑组织，不是可直接替换完整工程的入口；保留生成工程的 SDK 导入路径，将能力逻辑合入已有项目宿主的 activate 和业务收尾，保留项目扩展贡献与界面注册。/audit/project-entered 需由你的业务后端提供。

// plugin.ts
import { definePlugin } from 'fh2-plugin-sdk'

export default definePlugin({
  async activate (ctx) {
    if (ctx.host.id !== 'project') return
    const project = await ctx.capabilities.get('project:context')
    if (!project) {
      ctx.logger.warn('project:context 不可用')
      return
    }

    let activeProjectId: string | null = null
    async function apply (state: Awaited<ReturnType<typeof project.getState>>) {
      activeProjectId = state.projectId
      if (!state.projectId || !state.organizationId || !state.userInfo.user_id) return
      await ctx.apiCall('/audit/project-entered', {
        method: 'POST',
        body: {
          projectId: state.projectId,
          organizationId: state.organizationId,
          userId: state.userInfo.user_id,
          projectRole: state.userInfo.project_role,
        },
        idempotencyKey: `entered-${state.projectId}-${state.userInfo.user_id}`,
      })
    }

    await apply(await project.getState())
    const subscription = await project.onStateChanged((state) => {
      if (state.projectId === activeProjectId) return
      void apply(state).catch(error => ctx.logger.error('项目上下文处理失败', {
        message: error instanceof Error ? error.message : String(error),
      }))
    })

    return {
      async dispose () {
        await subscription.dispose()
      },
    }
  },
})

注意事项

其他宿主即使声明了这个权限，get() 也是 undefined。

上下文是只读快照：不能用它修改项目数据，也不能替代业务权限校验（角色字段只是展示信息，不是授权依据）。

离开项目页后不再收到回调；不要复用旧的 projectId。

宿主卸载会清理订阅；由回调发起的自有异步工作要自己取消。

常见问题

现象	原因与处理
首次进入没触发业务请求	`projectId` 等字段还是 `null`（过渡态）；等状态完整后再发请求
切换项目收到重复回调	自己记录上一次 `projectId`，相同则跳过（见示例）
想根据角色控制功能	角色字段仅用于展示判断；真正的权限由后端接口校验
离开项目页还在发请求	在 `dispose` 里释放订阅，并取消回调发起的未完成请求

方法清单#

集成片段#

注意事项#

常见问题#

方法清单

集成片段

注意事项

常见问题