DAP Plugin Docs

Overview

DAP 플러그인은 plugin.yaml과 자기완결 ESM .mjs 진입 파일로 구성됩니다. manifest에는 메타데이터와 권한만 선언하고, 기능 등록은 activate(ctx)에서 수행합니다.

Quickstart

1. 폴더 만들기

my-plugin/
  plugin.yaml
  dap_my_plugin/
    plugin.mjs
  README.md

2. manifest 작성

id: com.example.my_plugin
name: My Plugin
version: 1.0.0
manifest_version: 2
entry: dap_my_plugin.plugin:activate
description: DAP에서 실행되는 첫 플러그인
author: Your Name
min_app_version: "1.4.1"
surface: user
permissions: []
execution_modes:
  - user

3. 액션 등록

// dap_my_plugin/plugin.mjs
export function activate(ctx) {
  ctx.actions.registerAction({
    id: "hello",
    callback: () => {
      ctx.host.bubble.speak("Hello from plugin");
      return "Hello from plugin";
    },
  });

  ctx.radialMenu.addItem({
    itemId: "hello",
    label: "Hello",
    actionId: "hello",
    priority: 50,
  });
}

4. 로컬 설치

Windows:
%APPDATA%\dap\plugins\com.example.my_plugin\

macOS:
~/Library/Application Support/dap/plugins/com.example.my_plugin/

진입 파일은 bare import가 없는 자기완결 .mjs여야 합니다. 로컬 폴더를 설치 경로에 둔 뒤 DAP을 재시작하거나 설정의 플러그인 토글을 다시 켜서 로드합니다.

Core concepts

Guides

명령 등록하기

채팅 또는 스팟라이트 입력을 자연어로 라우팅해야 할 때 ctx.commands를 사용합니다.

ctx.commands.addCommand({
  id: "weather",
  title: "날씨",
  matchers: [
    { type: "keyword", patterns: ["날씨", "weather"], priority: 40 },
  ],
  backend: { type: "builtin", handler: "dap.weather.current" },
});

설정 섹션 추가하기

ctx.settings.registerSettingsSection({
  sectionId: "general",
  title: "My Plugin",
  spec: {
    fields: [
      { key: "compact", label: "간단히 보기", type: "toggle", default: false },
      { key: "mode", label: "모드", type: "select", default: "fast",
        options: [
          { value: "fast", label: "빠르게" },
          { value: "careful", label: "정교하게" },
        ] },
      { key: "note", label: "메모", type: "text" },
    ],
  },
});

const values = ctx.host.settings.values("general");
ctx.host.settings.set("general", "compact", true);

트레이 허브 패널 등록하기

surface_slots: [tray_panel]과 window.palette 권한을 manifest에 선언한 뒤 등록합니다. 패널은 샌드박스 iframe이며 최대 64KB의 JSON형 메시지만 주고받습니다.

# plugin.yaml
permissions:
  - window.palette
surface_slots:
  - tray_panel

const panel = ctx.trayPanel.register({
  id: "status",
  page: "tray/index.html",
  height: 210,
  priority: 10,
});

panel.onMessage((message) => {
  if (message?.type === "refresh") refresh();
});
panel.postMessage({ type: "status", items });

컴팩트 패널 권장 높이는 120–240px입니다. 상세 화면은 ctx.host.windows.openPalette()로 분리하고, 일반 트레이 액션은 ctx.trayMenu.addItem({ showInContextMenu: true })로 명시합니다.

팔레트 UI 열기

팔레트는 플러그인 전용 HTML UI입니다. 페이지는 권한 API를 직접 받지 않고 window.dapPalette 메시지 브리지만 사용합니다.

export function activate(ctx) {
  let palette = null;

  const open = () => {
    if (palette && !palette.isDestroyed()) {
      palette.toggle();
      return;
    }

    palette = ctx.host.windows.openPalette({
      page: "palette/index.html",
      width: 360,
      height: 520,
      frame: false,
    });

    palette.onMessage((msg) => {
      if (msg.type === "ready") {
        palette.postMessage({ type: "items", items: ["A", "B"] });
      }
    });

    palette.show();
  };

  ctx.actions.registerAction({ id: "openPalette", callback: open });
  ctx.radialMenu.addItem({ itemId: "palette", label: "Palette", actionId: "openPalette" });

  return () => palette?.close();
}

API reference

Manifest fields

추가 필드는 거절됩니다. manifest에는 명령·matcher·backend를 넣지 말고 activate(ctx)에서 등록하세요.

ctx namespaces

Host services

Permissions

요청 동작에 꼭 필요한 토큰만 선언하세요. 설치 화면은 선언 권한을 고지하며, 미선언 권한 서비스는 플러그인 컨텍스트에 제공하지 않습니다.

현재 entry module은 신뢰된 in-process 코드입니다. 권한 브로커는 Host API 노출을 제한하지만 악성 플러그인을 프로세스 수준에서 격리하지는 않습니다.

Examples

Daily briefing and OAuth

// plugin.yaml: surface_slots: [briefing.daily]
ctx.briefing.contribute({
  id: "today",
  provider: () => "오늘 일정 2개 · 마감 할 일 1개",
});

// plugin.yaml: permissions: [oauth.connect]
const status = await ctx.host.oauth.status("google-calendar");
if (!status.connected) {
  await ctx.host.oauth.connect({
    connectionId: "google-calendar",
    provider: "google",
    scopes: ["https://www.googleapis.com/auth/calendar.readonly"],
  });
}

OAuth 브라우저 흐름과 refresh token 보관은 DAP Host가 맡습니다. 플러그인은 refresh token을 직접 받거나 저장하지 않습니다. connectors.read를 선언한 플러그인은 현재 ctx.host.connectors.status("gmail")로 { state, via, hint }를 받습니다. state는 connected, unavailable, unknown 중 하나이며, 판별 자체가 실패한 unknown에서는 기능을 차단하지 말고 명시적인 unavailable에서만 Host의 hint를 안내하세요.

Storage

await ctx.host.storage.setJson("pins", ["a", "b"]);
const pins = await ctx.host.storage.getJson("pins");
await ctx.host.storage.delete("pins");

LLM

const answer = await ctx.host.llm.generate(
  "다음 문장을 더 자연스럽게 다듬어줘: " + text,
  30
);

Meeting capability gate

const capability = ctx.host.meeting.capabilities();
if (!capability.available) {
  ctx.host.bubble.speak(capability.reason ?? "회의 캡처를 사용할 수 없어요.");
  return;
}

const offTranscript = ctx.host.meeting.onTranscript((event) => {
  palette.postMessage({ type: "meeting.transcript", event });
});
await ctx.host.meeting.start({ source: "both", sourceLanguage: "en", targetLanguage: "ko" });
// cleanup에서 await ctx.host.meeting.stop(); offTranscript();

Image generation

const image = await ctx.host.imageGen.generate("고양이 밈");
const blobId = await ctx.host.storage.putBlob(image.bytes, {
  mime: image.mime,
  name: image.name,
});

Palette page

<!doctype html>
<meta charset="utf-8" />
<button id="close">close</button>
<ul id="list"></ul>
<script>
  const list = document.getElementById("list");

  window.dapPalette.onMessage((msg) => {
    if (msg.type !== "items") return;
    list.innerHTML = "";
    for (const item of msg.items) {
      const li = document.createElement("li");
      li.textContent = item;
      list.append(li);
    }
  });

  window.dapPalette.postMessage({ type: "ready" });
  document.getElementById("close").onclick = () => window.dapPalette.close();
</script>

Distribution

Catalog entry

플러그인은 공개 GitHub 저장소에 두고, Project-Undonghae/dap-plugins의 plugin_catalog.json에 PR을 보냅니다.

{
  "plugins": [
    {
      "id": "com.example.my_plugin",
      "name": "My Plugin",
      "description": "한 줄 설명",
      "repo": "https://github.com/example/dap-my-plugin.git",
      "ref": "v1.0.0"
    }
  ]
}

• repo는 owner/name 또는 GitHub HTTPS URL을 사용합니다. 저장소는 public이어야 합니다.
• ref는 브랜치·태그·SHA이며 재현 가능한 설치를 위해 버전 태그를 권장합니다.
• plugin.yaml의 id와 카탈로그 id가 다르면 설치를 거절합니다.
• DAP은 GitHub tree/raw API로 파일을 받아 설치합니다. 사용자 PC에서 git, zip 해제, npm install, 빌드를 실행하지 않습니다.
• 설치는 명시적인 신뢰 동작이며 새 플러그인은 즉시 활성화됩니다. 이전에 비활성화한 id는 그 상태를 유지합니다.
• 최대 200파일·20MB이며 node_modules, .git, .github는 제외됩니다.
• 업데이트마다 plugin.yaml의 version을 올리고 카탈로그 ref를 새 태그로 갱신하세요. 권한이 추가되면 사용자가 다시 동의합니다.

Versioning

DAP 앱 릴리스 버전, Plugin Platform 버전, manifest 버전, 개별 플러그인 버전은 서로 다른 책임을 가집니다. 플러그인 개발자에게 영향을 주는 변경은 개발문서와 docs/plugin-platform 아래의 관리 파일을 함께 갱신합니다.

• docs/plugin-platform/version.json은 Plugin Platform의 현재 버전과 호환성 기준입니다.
• docs/plugin-platform/changelog.md는 앱 릴리스 노트와 별도로 플러그인 개발자용 변경사항을 기록합니다.
• manifest_version은 manifest 해석 방식이 호환되지 않을 때만 올립니다.

Troubleshooting

Changelog

2026-08-05: Plugin Platform 0.3.0. briefing.daily, ctx.briefing, oauth.connect/ctx.host.oauth, connectors.read/ctx.host.connectors를 추가했습니다. 최소 앱은 DAP 1.4.1이며 manifest v2는 그대로 호환됩니다.

2026-07-29: Plugin Platform 0.2.0. tray_panel, 동적 tray submenu, ctx.aiContext, 설정 쓰기, presentation/meeting/AI accounts/image generation Host API와 최신 설치·업데이트 계약을 반영했습니다. manifest v2는 그대로 호환됩니다.

2026-07-05: Plugin Platform 0.1.0 기준 문서 구조를 정리했습니다. Electron/TypeScript Host API, manifest v2, palette, distribution, versioning 구조를 반영했습니다.