插件前端 SDK 参考

插件前端代码在沙箱 iframe 内运行。本文档提供底层参考。更高层次的介绍请参阅 README.md。

安全模型

属性	值
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 处理。权限选项卡中显示的权限缓存仅用于展示，不控制数据访问。

桥接协议

插件 JS 通过 postMessage 与 Ogma 宿主通信。宿主位于 PluginsView.vue 中，负责处理 bridge_request 消息。

请求封装

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 字节。

响应封装

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

使用 SDK（推荐）

不要手动发送原始 postMessage 桥接请求。请使用全局对象 ogmaSDK：

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

SDK 封装所有桥接通信，并处理请求关联、sessionId 管理和 Promise 的完成处理。

命令参考

`ogma.meta.get`

无需载荷。

返回 { pluginId, packageId, name, version, ogmaVersion }。

`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`

载荷：{ id: string }。通过 sdk.requests.getRaw(id) 调用。

返回 requestBodyBase64、responseBodyBase64、解码后的长度（requestBodyLength、responseBodyLength）、requestBodyTruncated、responseBodyTruncated 和 maxBodyBytes。尽管名称包含 Raw，此操作返回的是消息体字节，而非完整的原始 HTTP 消息。支持的内容编码会在投影前解码。每个消息体上限为 256 KiB；处理完整资源前，请检查截断标志。

需要：read_http_history（自动授予）。

`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`

载荷：{ 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`

无载荷。返回当前测试范围预设或 null。

需要：read_scope（自动授予）。

`ogma.projects.getCurrent`

无载荷。返回 { id, name, status } 或 null。

需要：read_projects（自动授予）。

`ogma.log`

载荷：{ message: string }

写入插件日志缓冲区。

`ogma.ui.resize`

载荷：{ height: number }（上限 2000）

请求宿主设置 iframe 高度。

`ogma.ui.sidebar.registerItem`

载荷：{ name: string, path: string }（name 最多 64 个字符，path 最多 256 个字符）

注册插件面板内的导航。每个插件最多 20 个条目。使用 sdk.navigation.addPage(path, { title, body }) 注册对应的页面内容；选择条目时会在 iframe 内显示该页面，而非创建新的 Ogma 顶层工作区路由。

`ogma.backend.call`

载荷：{ method: string, args: unknown[] }

调用通过 sdk.api.register(method, fn) 注册的后端 RPC 处理函数。方法名长度上限为 64 个字符。

返回后端处理函数的返回值，经过 JSON 序列化。

`ogma.backend.onEvent`

载荷：无需载荷。

仅确认该操作。实际获取事件请使用 ogma.events.poll。

`ogma.events.poll`

载荷：{ since: number }（上次轮询的索引；从 0 开始）

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

`ogma.navigation.addPage`

载荷：{ path: string, title?: string }

桥接会确认页面路径。注入的 SDK 还支持将 { body: HTMLElement } 作为 sdk.navigation.addPage(path, options) 的选项，将内容附加到 iframe 内，并在宿主选择匹配的侧边栏条目时切换页面可见性。DOM 节点保留在本地，不会通过桥接序列化传输。

`ogma.window.showToast`

载荷：{ message: string, variant?: "info"|"success"|"warning"|"error", duration?: number }

在插件面板中显示提示通知。持续时间单位为毫秒（上限 10000，默认 3000）。

`ogma.commands.register`

载荷：{ id: string, name: string }

在宿主命令存储中注册插件命令。宿主执行命令时，会向 iframe 发回包含 commandId 和上下文的 plugin_command 消息；插件必须提供对应的回调。仅注册不会执行命令。

`ogma.menu.registerItem`

载荷：{ type?: "Request" | "RequestRow" | "Response", commandId: string, label?: string }

注册与插件命令关联的上下文菜单条目。请先注册命令。标签默认使用命令注册名称，若无则使用其 ID；省略 type 时默认为 Request。宿主桥接不会使用 leadingIcon。

主题辅助函数

注入的 SDK 还提供 sdk.theme.get() 和 sdk.theme.onChange(callback)。它们读取 iframe 主题并订阅宿主主题更新，无需单独的数据桥接命令。使用这些函数可使插件 UI 与 Ogma 的浅色/深色外观保持一致。

错误代码

代码	含义
`PERMISSION_DENIED`	插件缺少所需权限。
`PLUGIN_DISABLED`	插件当前未启用。
`UNKNOWN_COMMAND`	命令不在支持列表中。
`INVALID_PAYLOAD`	必需的载荷字段缺失或类型错误。
`NOT_FOUND`	请求的资源不存在。
`LIMIT_EXCEEDED`	已达到每个插件的数量限制（例如侧边栏条目）。
`SERVER_ERROR`	内部错误。请检查插件日志。

支持的命令列表

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.

插件前端 SDK 参考 ​

安全模型 ​

桥接协议 ​

请求封装 ​

响应封装 ​

使用 SDK（推荐） ​

命令参考 ​

ogma.meta.get ​

ogma.requests.get ​

ogma.requests.getRaw ​

ogma.requests.search ​

ogma.findings.list ​

ogma.scope.getActive ​

ogma.projects.getCurrent ​

ogma.log ​

ogma.ui.resize ​

ogma.ui.sidebar.registerItem ​

ogma.backend.call ​

ogma.backend.onEvent ​

ogma.events.poll ​

ogma.navigation.addPage ​

ogma.window.showToast ​

ogma.commands.register ​

ogma.menu.registerItem ​

主题辅助函数 ​

错误代码 ​

支持的命令列表 ​

插件前端 SDK 参考

安全模型

桥接协议

请求封装

响应封装

使用 SDK（推荐）

命令参考

`ogma.meta.get`

`ogma.requests.get`

`ogma.requests.getRaw`

`ogma.requests.search`

`ogma.findings.list`

`ogma.scope.getActive`

`ogma.projects.getCurrent`

`ogma.log`

`ogma.ui.resize`

`ogma.ui.sidebar.registerItem`

`ogma.backend.call`

`ogma.backend.onEvent`

`ogma.events.poll`

`ogma.navigation.addPage`

`ogma.window.showToast`

`ogma.commands.register`

`ogma.menu.registerItem`

主题辅助函数

错误代码

支持的命令列表