플러그인 배포하기

Git 저장소나 폴더로 플러그인을 공유하고, 버전을 매기고, Agentty가 바뀌어도 계속 동작하게 유지하는 방법.

중앙 레지스트리는 없습니다. 플러그인은 매니페스트가 든 폴더이므로, 배포란 그 폴더를 사람들이 받을 수 있는 곳에 두는 일입니다.

Git 저장소로 공유하기#

agentty-plugin.json을 저장소 최상위에 두세요. 이용자는 직접 만들기 → Git에서 설치에 https:// 주소를 붙여넣습니다.

text
your-plugin/
├── agentty-plugin.json
├── main.mjs
├── agentty-plugin.mjs     번들된 SDK
├── README.md
└── LICENSE
Important

SDK와 필요한 node_modules를 포함해, 실행에 필요한 모든 것을 함께 넣으세요. Agentty는 npm install을 실행하지 않고 진입점을 그대로 시작합니다. 의존성이 빠진 플러그인은 이용자 컴퓨터에서 모듈을 찾지 못해 로그에 오류를 남기며 실패합니다.

가능하면 의존성 없는 코드를 쓰세요. SDK 자체에 의존성이 없는 이유도 이것입니다.

폴더로 공유하기#

폴더에서 설치… 는 폴더를 ~/.agentty/plugins/로 복사합니다. 올바른 이름의 폴더로 풀리는 zip도 같은 방식으로 동작합니다. 폴더 이름은 매니페스트의 id와 같아야 합니다.

버전#

version은 major.minor.patch입니다. Agentty는 이를 카드에 표시하고, 내장 플러그인의 새 버전이 함께 배포되면 업데이트를 제안하는 데 씁니다.

Git이나 폴더에서 설치한 플러그인은 이용자가 다시 설치해 갱신합니다. README에 그 방법을 적고, 매니페스트의 links가 변경 내역을 볼 수 있는 곳을 가리키게 하세요.

apiVersion은 어떤 플러그인 API 버전을 기준으로 작성했는지를 뜻하며 현재는 1입니다. 최신 숫자를 무작정 따라가지 말고 실제로 테스트한 버전을 적으세요.

도움이 되는 README#

스토어 카드에는 description과 최대 6개의 links가 표시됩니다. 그 밖에 필요한 내용은 README에 씁니다.

  • 무엇과 연동되는지, 동작하려면 무엇이 설치돼 있어야 하는지
  • 어떤 권한을 요청하며 그 이유가 무엇인지 — 쓸 수 있는 가장 유용한 한 줄입니다
  • 무엇을 어디에 저장하는지
  • 문제를 어디에 알리면 되는지

다른 앱과 연동한다면 카드가 설치 여부를 표시할 수 있도록 선언하세요.

json
{
  "requires": {
    "name": "Cosmica",
    "url": "https://www.cosmica.ink/",
    "note": "Needed to read and write notes"
  },
  "detect": ["~/Applications/Cosmica.app", "/Applications/Cosmica.app"]
}

detect가 맞으면 그 이용자에게 카드가 추천으로 표시됩니다.

배포 전 테스트#

  • 개발용 폴더 연결… 은 작업 중인 사본에서 플러그인을 실행하므로, 재설치 없이 수정하고 재시작만 누르면 됩니다.
  • 카드의 로그는 stderr, 프로토콜 오류, 크래시, 종료 코드를 보여줍니다.
  • 테스트 하네스로 직접 구동하세요. stdin에서 JSON 줄을 읽고 stdout에 쓰는 평범한 프로그램이므로, initialize와 확인하고 싶은 알림을 보내고 돌아오는 값을 검증하면 됩니다.
  • 실제로 선언한 권한으로 시험하세요. 권한 없는 호출은 -32001로 실패하는데, 개발 중에 더 많은 권한을 갖고 있으면 놓치기 쉽습니다.
  • 두 테마와 긴 패널을 모두 확인하세요. 패널은 폭 360px이고 스크롤됩니다.

계속 동작하게 유지하기#

  • shutdown을 처리하고 종료하세요. 1.5초 뒤에도 살아 있으면 강제 종료됩니다.
  • 프로토콜 메시지 외에는 stdout에 쓰지 마세요. plugin.log(...)나 console.error(...)를 씁니다.
  • 컨텍스트의 모든 필드를 선택적인 것으로 다루세요. 무엇이 들어 있는지는 권한과 창 상태가 결정합니다.
  • 이후 버전에서 새로운 UI 요소와 컨텍스트 필드가 생길 수 있습니다. 모르는 것은 실패시키지 말고 무시하세요.

내장 플러그인#

Agentty에 포함되어 배포되는 플러그인은 애플리케이션과 함께 업데이트되며, 연동 대상 앱이 설치돼 있으면 카드에 추천이 표시됩니다. 만든 플러그인이 여기 어울린다고 생각하면, 무엇을 하고 누구를 위한 것인지 설명해 Agentty 릴리스 저장소에 이슈로 올려 주세요.