---
url: https://docs.ogmabox.com/zh/plugins/backend-sdk.md
description: Ogma 后端插件 API 参考，涵盖沙箱执行、存储路径、HTTP 历史记录访问、安全发现、命令及宿主集成。
---

# 插件后端 SDK 参考 {#plugin-backend-sdk-reference}

后端插件代码在 Ogma 的 JavaScript 沙箱中运行，并从宿主应用接收 `sdk` 对象。

完整插件包格式、清单字段、权限和示例，请先参阅[插件系统指南](./README.md)。

## 入口 {#entry-point}

后端插件提供 `init` 函数：

```js
async function init(sdk) {
  sdk.console.log("plugin started");
}
```

插件启用时，Ogma 会调用 `init(sdk)`。

## 核心命名空间 {#core-namespaces}

| 命名空间 | 用途 |
| --- | --- |
| `sdk.console` | 将消息写入插件日志缓冲区。 |
| `sdk.meta` | 读取插件元数据和数据路径。 |
| `sdk.events` | 为 Ogma 事件注册回调。 |
| `sdk.requests` | 查询 HTTP 历史记录和请求数据。 |
| `sdk.findings` | 在权限允许时查询或创建安全发现。 |
| `sdk.scope` | 读取当前测试范围信息。 |
| `sdk.storage` | 以键值形式持久保存插件状态。 |
| `sdk.fs` | 在插件私有数据目录内执行文件操作。 |
| `sdk.path` | 用于组合插件数据目录内路径的辅助函数。 |
| `sdk.api` | 向插件前端提供后端处理函数。 |

## 日志 {#logging}

```js
sdk.console.log("message")
sdk.console.warn("warning")
sdk.console.error("error")
```

消息可在插件日志 UI 中查看。请保持日志简洁，避免写入秘密信息。

## 元数据 {#metadata}

```js
sdk.meta.id()
sdk.meta.packageId()
sdk.meta.version()
sdk.meta.path()
```

使用 `sdk.meta.path()` 存储插件专属数据。不要假定沙箱中的插件代码可以访问任意文件系统路径。

```js
sdk.storage.set("key", "value")
sdk.storage.get("key")
sdk.storage.keys()
sdk.storage.delete("key")
sdk.storage.clear()
```

```js
sdk.fs.readFile("relative/file.txt")
sdk.fs.writeFile("relative/file.txt", "text")
sdk.fs.appendFile("relative/file.txt", "more")
sdk.fs.exists("relative/file.txt")
sdk.fs.existsSync("relative/file.txt")
sdk.fs.mkdir("relative/dir")
sdk.path.join("a", "b", "c")
```

## 事件 {#events}

```js
sdk.events.onInterceptRequest(function(req) {
  return req
})

sdk.events.onInterceptResponse(function(req, res) {
  sdk.console.log(res.getCode())
})

sdk.events.onProjectChange(function() {
  sdk.console.log("project changed")
})
```

回调应快速执行。耗时较长的操作应由明确的用户操作或后端 API 处理函数触发。

## 前端桥接处理函数 {#frontend-bridge-handlers}

后端插件可向前端插件面板提供处理函数：

```js
sdk.api.register("ping", async function(input) {
  return { ok: true, input: input };
});
```

前端通过 Ogma 前端 SDK 调用处理函数。参阅[前端 SDK 参考](./frontend-sdk.md)。

## 安全要求 {#security-expectations}

* 将 HTTP 流量、安全发现、日志和导出内容视为敏感数据。
* 仅申请插件所需的权限。
* 默认情况下，绝不记录凭据、Cookie、Bearer 令牌或私有流量。
* 让插件行为明确且易于用户理解。