统一错误模型

throw { code: 'INVALID_ARGUMENT', message: 'title 不能为空' }
throw { code: 'NOT_FOUND', message: '记录不存在' }

// handlers/capture/get-event.ts
function requireText (input, key) {
  const value = String(input[key] == null ? '' : input[key]).trim()
  if (!value) {
    throw { code: 'INVALID_ARGUMENT', message: key + ' 不能为空' }
  }
  return value
}

export function handle (input: RecordInput, ctx: HandlerCtx) {
  const eventId = requireText(input, 'event_id')

  const result = store.query('capture_event', { id: { eq: eventId } }, { limit: 1 })
  if (!result.ok) {
    throw { code: result.error.code, message: '查询抓拍失败: ' + result.error.message }
  }
  if (result.data.list.length === 0) {
    throw { code: 'NOT_FOUND', message: '抓拍事件不存在' }
  }

  const row = result.data.list[0]
  return { event_id: row.id, status: row.status || '' }
}

// ❌ 平台会把返回值当成成功，前端拿到 code=0
return { ok: false, error: '数据库失败' }

// src/shared/invoke.ts
import { isPluginError } from 'fh2-plugin-sdk'
import type { JsonValue, PluginContext } from 'fh2-plugin-sdk'

interface GatewayDetail {
  readonly gatewayCode?: number
  readonly httpStatus?: number
  readonly gatewayMessage?: string
}

export async function invoke<T> (
  ctx: Pick<PluginContext, 'apiCall'>,
  pluginId: string,
  handler: string,
  input: Record<string, JsonValue>,
  idempotencyKey?: string,
): Promise<T> {
  try {
    const res = await ctx.apiCall<{ code: number; message: string; data: JsonValue }>('/plugin/invoke', {
      method: 'POST',
      body: { pluginId, handler, input },
      ...(idempotencyKey ? { idempotencyKey } : {}),
    })
    // 只有 code === 0 才会走到这里
    return res.data as T
  } catch (error) {
    if (isPluginError(error) && error.code === 'PLUGIN_GATEWAY_ERROR') {
      const detail = (error.detail ?? {}) as GatewayDetail
      // gatewayCode 对应上方对照表：40006 契约、20001 业务、50301 系统
      const gatewayCode = detail.gatewayCode ?? 0
      const retryable = gatewayCode === 50301 || gatewayCode === 50401
      const business = gatewayCode === 20001
      void retryable
      void business
      throw new Error(`[${gatewayCode}] ${detail.gatewayMessage ?? error.message}`)
    }
    throw error
  }
}

{
  "ok": false,
  "error": { "code": "INVALID_FILTER", "message": "筛选条件非法" }
}