เอกสารอ้างอิง SDK ฟรอนต์เอนด์ของปลั๊กอิน

โค้ดฟรอนต์เอนด์ของปลั๊กอินทำงานใน iframe ที่อยู่ในแซนด์บ็อกซ์ เอกสารนี้เป็นข้อมูลอ้างอิงระดับล่าง สำหรับบทนำที่อธิบายภาพรวม ดู README.md

โมเดลความปลอดภัย

คุณสมบัติ	ค่า
แซนด์บ็อกซ์ iframe	เฉพาะ `allow-scripts` (ไม่มี `allow-same-origin`)
CSP `script-src`	ควบคุมด้วย nonce; โหลดเฉพาะสคริปต์จุดเริ่มต้นการทำงาน
CSP `connect-src`	`'self'` - ปลั๊กอินสามารถส่ง POST ไปยัง `/plugins/{id}/api/*` และโพล `/plugins/{id}/events/poll`
CSP `default-src`	`'none'`
การเข้าถึง DOM ของหน้าที่ครอบ iframe	ถูกปิดกั้น (ไม่มี `allow-same-origin`)
คุกกี้เซสชันของ Ogma	ปลั๊กอินเข้าถึงไม่ได้
การสื่อสารระหว่างปลั๊กอิน	ไม่รองรับ

การเรียกบริดจ์ข้อมูลจะได้รับการตรวจสอบสิทธิ์ฝั่งเซิร์ฟเวอร์ในทุกคำขอ ส่วนการแสดงผลและการนำทางจัดการโดย UI ของโฮสต์ แคชสิทธิ์ที่แสดงในแท็บสิทธิ์มีไว้เพื่อแสดงผลเท่านั้น ไม่ได้ใช้ควบคุมการเข้าถึงข้อมูล

โปรโตคอลบริดจ์

JS ของปลั๊กอินสื่อสารกับโฮสต์ Ogma ผ่าน postMessage โฮสต์อยู่ใน 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 แม้ชื่อจะสื่อเป็นอย่างอื่น การดำเนินการนี้ส่งคืนไบต์ของเนื้อหา ไม่ใช่ข้อความ 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 } (ชื่อไม่เกิน 64 อักขระ พาธไม่เกิน 256 อักขระ)

ลงทะเบียนการนำทางภายในแผงปลั๊กอิน สูงสุด 20 รายการต่อปลั๊กอิน ลงทะเบียนเนื้อหาของหน้าที่ตรงกันด้วย sdk.navigation.addPage(path, { title, body }); เมื่อเลือกรายการจะแสดงหน้านั้นภายใน iframe ไม่ใช่เส้นทางระดับบนใหม่ในพื้นที่ทำงาน Ogma

`ogma.backend.call`

เพย์โหลด: { method: string, args: unknown[] }

เรียกตัวจัดการ RPC แบ็กเอนด์ที่ลงทะเบียนผ่าน sdk.api.register(method, fn) ชื่อเมธอดมีความยาวสูงสุด 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 ยังคงอยู่ภายใน iframe ไม่ได้ซีเรียลไลซ์ส่งผ่านบริดจ์

`ogma.window.showToast`

เพย์โหลด: { message: string, variant?: "info"|"success"|"warning"|"error", duration?: number }

แสดงการแจ้งเตือนแบบโทสต์ในแผงปลั๊กอิน ระยะเวลาเป็นมิลลิวินาที (สูงสุด 10000 ค่าเริ่มต้น 3000)

`ogma.commands.register`

เพย์โหลด: { id: string, name: string }

ลงทะเบียนคำสั่งปลั๊กอินในที่เก็บคำสั่งของโฮสต์ เมื่อโฮสต์ดำเนินการ จะส่งข้อความ plugin_command ที่มี commandId และบริบทกลับไปยัง iframe; ปลั๊กอินต้องจัดเตรียมคอลแบ็กที่ตรงกัน การลงทะเบียนเพียงอย่างเดียวไม่ทำให้คำสั่งทำงาน

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

เครื่องมือช่วยเรื่องธีม

รหัสข้อผิดพลาด

รายการคำสั่งที่รองรับ