---
url: https://docs.ogmabox.com/zh-Hant/plugins/frontend-sdk.md
description: Ogma 前端外掛 API 參考，涵蓋 iframe 整合、橋接呼叫、UI 面板、命令及主應用程式通訊。
---

# 外掛前端 SDK 參考 {#plugin-frontend-sdk-reference}

外掛前端程式碼在沙箱 iframe 內執行。本文提供底層參考。較高層次的介紹請參閱 [README.md](./README.md)。

***

## 安全模型 {#security-model}

| 屬性 | 值 |
|----------|-------|
| iframe 沙箱 | 僅允許 `allow-scripts`（不包含 `allow-same-origin`） |
| CSP `script-src` | 以 nonce 控制；只載入進入點指令碼 |
| CSP `connect-src` | `'self'`：外掛可向 `/plugins/{id}/api/*` 發出 POST 請求，並輪詢 `/plugins/{id}/events/poll` |
| CSP `default-src` | `'none'` |
| 父層 DOM 存取 | 已封鎖（不包含 `allow-same-origin`） |
| Ogma 工作階段 Cookie | 外掛無法存取 |
| 跨外掛通訊 | 不提供 |

資料橋接呼叫的每個請求都會在伺服器端進行授權；顯示與導覽操作由主應用程式 UI 處理。權限分頁顯示的權限快取僅供顯示，不會控制資料存取。

***

## 橋接通訊協定 {#bridge-protocol}

外掛 JS 透過 `postMessage` 與 Ogma 主應用程式通訊。主應用程式端的橋接位於 `PluginsView.vue`，負責處理 `bridge_request` 訊息。

### 請求封裝 {#request-envelope}

```ts
interface BridgeRequest {
  type: 'bridge_request'
  sessionId: string     // nonce assigned when the bridge is set up; prevents stale messages
  requestId: string     // caller-generated correlation id (max 128 chars)
  command: string       // e.g. "ogma.requests.get"
  payload?: unknown     // command-specific input
}
```

訊息總大小上限：65 536 位元組。

### 回應封裝 {#response-envelope}

```ts
interface BridgeResponse {
  type: 'bridge_response'
  requestId: string
  ok: boolean
  result?: unknown
  error?: string
  code?: string
}
```

### 使用 SDK（建議） {#using-the-sdk-recommended}

不要手動傳送原始的 `postMessage` 橋接請求。請使用全域物件 `ogmaSDK`：

```js
ogmaSDK.ready(function(sdk) {
  sdk.meta.get().then(function(meta) {
    sdk.log.info("running as " + meta.pluginId);
  });
});
```

SDK 會封裝所有橋接通訊，並處理請求關聯、sessionId 管理及 Promise 的完成處理。

***

## 命令參考 {#command-reference}

### `ogma.meta.get` {#ogma-meta-get}

不需要酬載。

傳回 `{ pluginId, packageId, name, version, ogmaVersion }`。

### `ogma.requests.get` {#ogma-requests-get}

酬載：`{ id: string }`

傳回經欄位投影的 HTTP 項目。欄位：`id`、`method`、`host`、`port`、`path`、`query`、`req_len`、`resp_status`、`resp_len`、`roundtrip_ms`、`created_at`。此投影不包含標頭或本文位元組。

需要：`read_http_history`（自動授予）。

### `ogma.requests.getRaw` {#ogma-requests-getraw}

酬載：`{ id: string }`。透過 `sdk.requests.getRaw(id)` 呼叫。

傳回 `requestBodyBase64`、`responseBodyBase64`、解碼後的長度（`requestBodyLength`、`responseBodyLength`）、`requestBodyTruncated`、`responseBodyTruncated` 和 `maxBodyBytes`。雖然名稱包含 Raw，但此操作傳回的是本文位元組，而非完整的原始 HTTP 訊息。支援的內容編碼會在投影前解碼。每個本文上限為 256 KiB；處理完整資源前，請先檢查截斷旗標。

需要：`read_http_history`（自動授予）。

### `ogma.requests.search` {#ogma-requests-search}

酬載：`{ limit?: number, offset?: number, query?: string }`

`query` 支援 HTTPQL 篩選運算式。`limit` 上限：20。傳回 `{ items: [...], total: number, limit: number, offset: number }`。

需要：`read_http_history`（自動授予）。

### `ogma.findings.list` {#ogma-findings-list}

酬載：`{ limit?: number, offset?: number }`

傳回 `{ items: [...], total: number, limit: number, offset: number }`，每頁最多 20 筆檢測發現。項目為摘要；欄位包含 `id`、`title`、`severity`、`status`、`reporter`、`tags` 和 `created_at`。

需要：`read_findings`（自動授予）。

### `ogma.scope.getActive` {#ogma-scope-getactive}

沒有酬載。傳回目前的測試範圍預設集或 `null`。

需要：`read_scope`（自動授予）。

### `ogma.projects.getCurrent` {#ogma-projects-getcurrent}

沒有酬載。傳回 `{ id, name, status }` 或 `null`。

需要：`read_projects`（自動授予）。

### `ogma.log` {#ogma-log}

酬載：`{ message: string }`

寫入外掛記錄緩衝區。

### `ogma.ui.resize` {#ogma-ui-resize}

酬載：`{ height: number }`（上限 2000）

要求主應用程式設定 iframe 高度。

### `ogma.ui.sidebar.registerItem` {#ogma-ui-sidebar-registeritem}

酬載：`{ name: string, path: string }`（name 最多 64 個字元，path 最多 256 個字元）

註冊外掛面板內的導覽。每個外掛最多 20 個項目。使用 `sdk.navigation.addPage(path, { title, body })` 註冊相符的頁面內容；選取項目時，會在 iframe 內顯示該頁面，而不是建立新的 Ogma 頂層工作區路由。

### `ogma.backend.call` {#ogma-backend-call}

酬載：`{ method: string, args: unknown[] }`

呼叫透過 `sdk.api.register(method, fn)` 註冊的後端 RPC 處理函式。方法名稱長度上限為 64 個字元。

傳回後端處理函式的傳回值，並序列化為 JSON。

### `ogma.backend.onEvent` {#ogma-backend-onevent}

酬載：不需要。

僅確認此操作。實際取得事件請使用 `ogma.events.poll`。

### `ogma.events.poll` {#ogma-events-poll}

酬載：`{ since: number }`（上次輪詢的索引；從 0 開始）

傳回 `{ events: [{ event: string, args: unknown[] }], next_since: number }`。

### `ogma.navigation.addPage` {#ogma-navigation-addpage}

酬載：`{ path: string, title?: string }`

橋接會確認頁面路徑。注入的 SDK 也支援將 `{ body: HTMLElement }` 作為 `sdk.navigation.addPage(path, options)` 的選項，將內容附加至 iframe 內，並在主應用程式選取相符側邊欄項目時切換頁面可見性。DOM 節點留在本機，不會透過橋接序列化傳輸。

### `ogma.window.showToast` {#ogma-window-showtoast}

酬載：`{ message: string, variant?: "info"|"success"|"warning"|"error", duration?: number }`

在外掛面板中顯示短暫通知。持續時間以毫秒計（上限 10000，預設 3000）。

### `ogma.commands.register` {#ogma-commands-register}

酬載：`{ id: string, name: string }`

在主應用程式的命令儲存區中註冊外掛命令。主應用程式執行命令時，會將包含 `commandId` 和情境資訊的 `plugin_command` 訊息送回 iframe；外掛必須提供對應的回呼。僅註冊不會執行命令。

### `ogma.menu.registerItem` {#ogma-menu-registeritem}

酬載：`{ type?: "Request" | "RequestRow" | "Response", commandId: string, label?: string }`

註冊連結至外掛命令的快顯選單項目。請先註冊命令。標籤預設使用命令註冊的名稱，若無則使用其 ID；省略 `type` 時預設為 `Request`。主應用程式橋接不會使用 `leadingIcon`。

### 佈景主題輔助函式 {#theme-helpers}

注入的 SDK 也提供 `sdk.theme.get()` 和 `sdk.theme.onChange(callback)`。這些函式會讀取 iframe 的佈景主題，並訂閱主應用程式的佈景主題更新，不需要獨立的資料橋接命令。使用它們可讓外掛 UI 與 Ogma 的淺色/深色外觀一致。

***

## 錯誤代碼 {#error-codes}

| 代碼 | 意義 |
|------|---------|
| `PERMISSION_DENIED` | 外掛缺少所需權限。 |
| `PLUGIN_DISABLED` | 外掛目前未啟用。 |
| `UNKNOWN_COMMAND` | 命令不在支援清單中。 |
| `INVALID_PAYLOAD` | 必要的酬載欄位遺漏或型別錯誤。 |
| `NOT_FOUND` | 要求的資源不存在。 |
| `LIMIT_EXCEEDED` | 已達到每個外掛的數量上限（例如側邊欄項目）。 |
| `SERVER_ERROR` | 內部錯誤。請檢查外掛記錄。 |

***

## 支援的命令清單 {#supported-commands-list}

`ogma.meta.get`, `ogma.log`, `ogma.ui.resize`, `ogma.ui.sidebar.registerItem`, `ogma.requests.get`, `ogma.requests.getRaw`, `ogma.requests.search`, `ogma.findings.list`, `ogma.scope.getActive`, `ogma.projects.getCurrent`, `ogma.backend.call`, `ogma.backend.onEvent`, `ogma.events.poll`, `ogma.navigation.addPage`, `ogma.window.showToast`, `ogma.commands.register`, `ogma.menu.registerItem`.