外掛快速入門

本指南協助你從空白資料夾快速建立可執行的外掛。

1) 建立最小純後端外掛

建立資料夾，並加入以下檔案：

my-plugin/
  manifest.json
  backend/
    script.js

manifest.json:

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "0.1.0",
  "plugins": [
    {
      "kind": "backend",
      "id": "my-plugin-backend",
      "entrypoint": "backend/script.js"
    }
  ]
}

backend/script.js:

async function init(sdk) {
  sdk.console.log("Plugin started");

  sdk.events.onInterceptResponse(function(req, res) {
    if (!res) return;
    if (res.getCode() === 403) {
      sdk.console.warn("403 on " + req.getUrl());
    }
  });
}

從外掛 > 安裝選取資料夾、啟用外掛，並確認記錄中出現 Plugin started。

2) 若使用 TypeScript

使用以下結構：

my-plugin/
  manifest.json
  backend/
    src/index.ts

以下列命令封裝：

pnpm add -D @ogmabox/ogma-sdk esbuild typescript
pnpm exec esbuild backend/src/index.ts \
  --bundle \
  --platform=neutral \
  --format=iife \
  --external:@ogma/sdk --external:@ogmabox/ogma-sdk \
  --outfile=backend/script.js

然後按照上述步驟安裝資料夾。

3) 之後再加入前端

只有需要面板時，才加入前端項目及 UI 檔案：

my-plugin/
  frontend/
    script.js
    style.css   # optional

接著在 manifest.json 中新增：

{
  "kind": "frontend",
  "id": "my-plugin-frontend",
  "entrypoint": "frontend/script.js",
  "backend": { "id": "my-plugin-backend" }
}

前端通訊請使用 window.ogmaSDK.ready(...)，並將後端呼叫保留在 sdk.api 處理函式中。

4) 通常需要的權限

對於上述後端範例：

• 不需要額外權限（安全的預設權限會自動授予）

若外掛會發出對外請求，請加入：

"permissions": ["send_requests"]

若外掛會寫入檢測發現，請加入：

"permissions": ["write_findings"]

只申請實際使用的權限。

第一個外掛的疑難排解

• Plugin failed to initialize → 開啟記錄，確認已定義 init(sdk)。
• Invalid manifest → 檢查 JSON 的逗號及引號。
• 回呼沒有觸發 → 確認外掛已啟用，且已註冊對應事件（onInterceptResponse）。

完整 API 參考：

• 外掛系統
• 後端 SDK
• 前端 SDK