플러그인 만들기 · Herdr 한국어 문서

Herdr 플러그인은 공유 가능하고 실행 가능한 워크플로 패키지입니다. 플러그인은 Bash 스크립트, JavaScript 앱, Lua 스크립트, Rust 바이너리 또는 컴퓨터에서 실행할 수 있는 기타 argv 명령일 수 있습니다. Herdr는 설치, 매니페스트 유효성 검사, 키 설정, 터미널 패널, 이벤트, 호출 컨텍스트 및 소켓 액세스와 같은 호스트 표면을 소유합니다. 플러그인은 구현 언어, 종속성, 파일 및 내구성 상태를 소유합니다.

Herdr가 린 상태를 유지할 수 있도록 플러그인이 존재합니다. 핵심은 터미널 작업 공간, 패널, 에이전트 및 안정적인 CLI/소켓 API에 중점을 둡니다. 플러그인은 기존 확장 표면을 사람들이 Herdr 자체에 모든 워크플로우를 추가하지 않고도 구축, 설치 및 공유할 수 있는 재사용 가능한 워크플로우로 전환합니다.

플러그인은 herdr-plugin.toml 매니페스트와 Herdr가 시작할 수 있는 명령이 있는 디렉터리입니다. Herdr는 매니페스트의 유효성을 검사하고, 런타임 컨텍스트를 삽입하고, 선언된 명령을 시작하고, 로그를 기록합니다. 명령은 추가 작업을 수행해야 할 때 CLI 또는 소켓을 통해 Herdr로 다시 호출됩니다.

별도의 플러그인 SDK나 제한된 명령 세트는 없습니다. 전체 Herdr CLI는 플러그인 API입니다. CLI 참조의 모든 명령은 플러그인에서 사용할 수 있으며 플러그인은 herdr ...로 직접 실행할 수 있는 모든 명령을 실행할 수 있습니다. 대부분의 플러그인은 실행 중인 Herdr 바이너리를 가리키는 HERDR_BIN_PATH을 통해 Herdr를 호출해야 합니다. 이는 Unix 소켓과 Windows 명명된 파이프에서 플러그인의 이식성을 유지합니다. 원시 JSON 요청을 직접 보내려면 소켓 API을 사용하세요.

런타임 작업 등록 및 기본 비터미널 플러그인 UI는 플러그인 v1의 일부가 아닙니다. 작업, 이벤트 훅, 패널 및 링크 처리기는 모두 매니페스트에 선언됩니다.

신뢰와 보안

플러그인은 컴퓨터에서 실행되는 일반 코드입니다. 빌드 및 런타임 명령은 사용자로 실행되고 환경을 상속하며 전체 Herdr CLI를 호출할 수 있습니다. 플러그인을 편집기, 셸 또는 코딩 에이전트에 추가하는 확장처럼 취급하세요.

신뢰할 수 있는 작성자 및 저장소의 플러그인만 설치하거나 연결하세요. 설치하거나 연결하기 전에 herdr-plugin.toml 매니페스트와 이것이 실행하는 스크립트 또는 바이너리를 훑어보세요. herdr plugin install은 대화형 터미널에서 실행될 소스와 명령의 미리보기를 표시하므로 확인하기 전에 검토할 수 있습니다. 이미 신뢰하는 소스에는 --yes를 사용하고, 특정 개정판을 원할 때는 --ref을 고정하세요.

Herdr는 매니페스트의 유효성을 검사하고 각 플러그인의 구성과 상태를 자체 디렉터리에 유지하지만 플러그인 코드를 검토하거나 샌드박스하지는 않습니다. 타사 플러그인은 Herdr가 아닌 작성자가 제공합니다. 실행 여부를 결정하는 책임은 귀하에게 있습니다.

매니페스트

매니페스트는 Herdr과 플러그인 간의 계약입니다. 이는 패키지 메타데이터, 지원되는 플랫폼, 선택적 빌드 명령 및 Herdr가 실행할 수 있는 진입점을 선언합니다.

TOML

id = "example.layout"
name = "Layout"
version = "0.1.0"
min_herdr_version = "0.7.0"
description = "Apply project layouts"
platforms = ["linux", "macos", "windows"]


[[build]]
command = ["npm", "ci"]


[[build]]
command = ["npm", "run", "build"]
platforms = ["linux", "macos"]


[[startup]]
command = ["node", "dist/restore.js"]


[[actions]]
id = "apply"
title = "Apply layout"
contexts = ["workspace"]
command = ["node", "dist/apply.js"]


[[events]]
on = "worktree.created"
command = ["herdr", "workspace", "list"]


[[panes]]
id = "board"
title = "Project board"
placement = "overlay"
command = ["herdr-board"]


[[link_handlers]]
id = "github-issue"
title = "Open GitHub issue"
pattern = "^https://github\\.com/[^/]+/[^/]+/(issues|pull)/[0-9]+$"
action = "apply"

최상위 수준 id, name, version 및 min_herdr_version이 필요합니다. min_herdr_version를 플러그인이 사용하는 플러그인 API, 이벤트 이름 및 매니페스트 필드를 지원하는 가장 오래된 Herdr 버전으로 설정하세요. Herdr는 최소 버전이 현재 바이너리보다 최신인 경우 플러그인 연결이나 설치를 거부합니다. description는 선택 사항입니다. 플러그인 ID는 ASCII 문자, 숫자, 점, 콜론, 밑줄 및 하이픈을 사용할 수 있습니다.

작업 ID, 패널 ID 및 링크 처리기 ID는 플러그인 내부의 로컬 ID입니다. ASCII 문자, 숫자, 콜론, 밑줄, 하이픈을 사용할 수 있지만 점은 사용할 수 없습니다. 각 ID 유형은 플러그인 내에서 고유해야 합니다. Herdr는 전역적으로 고유한 이름이 필요할 때 작업 ID를 plugin.id.action로 한정합니다.

platforms = ["linux", "macos", "windows"]을 사용하여 플러그인이 실행될 수 있는 위치를 선언하세요. 빌드 명령, 시작 훅, 작업, 이벤트 훅, 패널 및 링크 처리기도 자체 platforms을 선언할 수 있습니다. 아이템 수준 플랫폼은 최상위 목록보다 우선 적용됩니다. 경고와 함께 최상위 platforms 링크가 없는 로컬 플러그인.

command 값은 argv 배열입니다. Herdr는 쉘을 통해 이를 실행하지 않으므로 명령이 쉘 자체를 시작하지 않는 한 쉘 확장이 없습니다. 스크립트나 바이너리에 언어별 동작을 추가하세요.

첫 번째 플러그인

herdr-plugin.toml과 하나의 실행 가능한 스크립트 또는 프로그램이 포함된 디렉터리로 시작합니다.

텍스트

my-plugin/
  herdr-plugin.toml
  index.js

TOML

id = "example.workspace-tools"
name = "Workspace Tools"
version = "0.1.0"
min_herdr_version = "0.7.0"
description = "Small workspace helpers"
platforms = ["linux", "macos", "windows"]


[[actions]]
id = "list-workspaces"
title = "List workspaces"
contexts = ["workspace"]
command = ["node", "index.js"]

명령 내에서 HERDR_BIN_PATH을 사용하여 Herdr를 다시 호출합니다.

const { spawnSync } = require("node:child_process");


const herdr = process.env.HERDR_BIN_PATH ?? "herdr";
const result = spawnSync(herdr, ["workspace", "list"], {
  encoding: "utf8",
  stdio: ["ignore", "pipe", "pipe"],
});


process.stdout.write(result.stdout);
process.stderr.write(result.stderr);
process.exit(result.status ?? 1);

이 예에서는 Node를 사용하지만 플러그인에 대해서는 Node가 필요하지 않습니다. 매니페스트는 Bash, PowerShell, Python, Rust, Go, Lua, Bun 또는 사용자 컴퓨터에서 사용할 수 있는 기타 명령을 시작할 수 있습니다.

설치 및 연결

예제 플러그인을 설치합니다:

bash

herdr plugin install ogulcancelik/herdr-plugin-examples/agent-telegram-notify
herdr plugin config-dir examples.agent-telegram-notify
herdr plugin list
herdr plugin action list --plugin examples.agent-telegram-notify

로컬 플러그인을 작성할 때 대신 작업 디렉터리를 연결하세요.

bash

herdr plugin link /path/to/plugin
herdr plugin config-dir example.layout
herdr plugin action list --plugin example.layout
herdr plugin action invoke example.layout.apply
herdr plugin pane open --plugin example.layout --entrypoint board
herdr plugin log list --plugin example.layout

plugin install은 owner/repo/subdir과 같은 GitHub 단축어만 허용합니다. git로 복제하고 대화형 터미널에 미리보기를 표시하고 지원되는 빌드 명령을 실행한 다음 Herdr 관리 플러그인 데이터에 체크아웃을 저장하고 등록합니다. 비대화형 설치에는 --yes을 사용하세요. GitHub 관리 플러그인을 다시 설치하면 해당 관리 체크아웃이 대체됩니다. 활성화된 상태를 포함하여 설치되고 연결된 플러그인은 현재 사용자에게 전역적이며 모든 Herdr 세션에서 사용할 수 있습니다. plugin install 및 plugin link 모두 Herdr 서버가 실행되지 않는 동안 플러그인을 등록할 수 있습니다. Herdr 0.7.3의 명명된 세션에만 설치된 플러그인은 다시 설치하거나 연결해야 합니다. 기존 플러그인 구성 및 상태는 그대로 유지됩니다. 로컬로 연결된 플러그인을 통한 설치는 거부됩니다. 먼저 로컬 플러그인을 연결 해제하거나 제거하세요. plugin install 및 plugin link은 플러그인의 구성 및 상태 디렉터리를 생성하고 plugin config-dir <id>은 설정 문서 및 쉘 스크립트에 대한 구성 디렉터리를 출력합니다.

plugin uninstall <id-or-source>은 플러그인 등록을 취소합니다. GitHub 관리 설치의 경우 관리 체크아웃도 제거하고 플러그인 ID 또는 설치에 사용된 것과 동일한 owner/repo[/subdir...] 약어를 허용합니다. plugin unlink <id>는 플러그인 등록을 취소하고 파일만 남겨두므로 로컬 개발에 유용합니다. v1에는 별도의 plugin update이 없습니다. 관리되는 플러그인을 새로 고치려면 GitHub에서 다시 설치하세요.

예제 요리책 저장소는 ogulcancelik/herdr-plugin-examples입니다. agent-telegram-notify, github-link-preview 및 dev-layout-bootstrap을 포함하여 하위 디렉터리에 별도의 예제 플러그인이 포함되어 있습니다. 복사할 예시로 사용하세요. Herdr는 이를 공식 플러그인으로 유지하지 않습니다.

빌드 명령

빌드 명령은 확인 후 Herdr가 플러그인을 등록하기 전에 GitHub plugin install 중에 실행됩니다. 빌드 명령이 실패하면 설치가 중단되고 플러그인이 등록되지 않습니다. plugin link은 빌드 명령을 실행하지 않습니다. 지역 작가들은 작업 트리를 직접 구축합니다. 빌드 명령으로 파일이 생성될 수 있지만 설치 미리보기 이후 herdr-plugin.toml를 변경하면 설치가 중단됩니다. 빌드 실패는 도구 출력을 해석하지 않고 플러그인 ID, 빌드 인덱스, 작업 디렉터리, 명령, 종료 상태 또는 생성 오류 및 제한된 stdout/stderr을 표시합니다.

빌드 명령도 일반 argv 명령이지만 런타임 플러그인 컨텍스트나 Herdr 소켓 환경을 수신하지 않습니다. 플러그인 작성자는 cargo, npm, bun 또는 lua과 같은 필수 시스템 도구를 문서화해야 합니다. Herdr는 빌드 실패를 보고하지만 누락된 툴체인을 설치하지 않습니다.

시작 훅

[[startup]] 명령은 Herdr가 세션을 복원하고 해당 API 소켓이 준비된 후 활성화된 각 플러그인에 대해 한 번 실행됩니다. 라이브 핸드오프 중에 새 서버가 인계되면 다시 실행되지만 클라이언트가 연결되거나 구성이 다시 로드되거나 플러그인이 연결되거나 활성화된 경우에는 실행되지 않습니다. Herdr는 이를 비동기식으로 시작하고 일반 플러그인 명령 로그에 완료를 기록합니다. 시작 실패로 인해 서버가 중지되지는 않습니다.

시작 훅는 감독되는 데몬이 아닌 일회성 초기화 명령입니다. 훅는 플러그인 소유 상태를 복원하고 필요한 Herdr API를 호출한 후 종료해야 합니다. 예를 들어 플러그인은 HERDR_PLUGIN_STATE_DIR 아래에 선언적 에이전트 보기를 저장한 다음 시작 훅에서 해당 보기를 읽고 다시 적용할 수 있습니다.

시작 훅는 일반 런타임 플러그인 환경과 HERDR_PLUGIN_EVENT=startup을 수신합니다. 설치 미리보기에는 모든 시작 명령이 나열되므로 사용자는 자동으로 실행되는 코드를 검토할 수 있습니다.

명령 및 환경

런타임 명령은 플러그인 디렉터리를 작업 디렉터리로 사용하여 실행됩니다. Herdr는 HERDR_SOCKET_PATH, HERDR_BIN_PATH, HERDR_ENV=1, HERDR_PLUGIN_ID, HERDR_PLUGIN_ROOT, HERDR_PLUGIN_CONFIG_DIR, HERDR_PLUGIN_STATE_DIR, HERDR_PLUGIN_CONTEXT_JSON 및 사용 가능한 HERDR_WORKSPACE_ID, HERDR_TAB_ID 및 HERDR_PANE_ID을 주입합니다. 작업 명령도 HERDR_PLUGIN_ACTION_ID을 수신합니다. 시작 및 이벤트 훅는 HERDR_PLUGIN_EVENT(시작 훅의 경우 startup)를 수신하고 이벤트 훅는 추가로 HERDR_PLUGIN_EVENT_JSON을 수신하며 패널 명령은 HERDR_PLUGIN_ENTRYPOINT_ID을 수신합니다.

HERDR_PLUGIN_ROOT은 설치되었거나 연결된 플러그인 디렉터리입니다. GitHub 설치 플러그인 루트는 관리되는 소스 체크아웃이므로 사용자 자격 증명이나 지속 가능한 상태를 여기에 저장하지 마세요. .env 파일과 같은 사용자 편집 가능한 구성을 HERDR_PLUGIN_CONFIG_DIR 아래에 두고, 로컬 런타임 상태를 HERDR_PLUGIN_STATE_DIR 아래에 두십시오. Herdr는 레거시 플러그인 구성 위치에서 해당 디렉터리와 시드 HERDR_PLUGIN_CONFIG_DIR를 생성하지만 해당 콘텐츠의 유효성을 검사, 동기화 또는 삭제하지는 않습니다. 플러그인은 파일 형식과 수명주기를 소유합니다.

HERDR_PLUGIN_CONTEXT_JSON에는 해당 호출에 사용할 수 있는 작업 공간, 탭, 포커스 패널, 작업 트리, 에이전트, 선택한 텍스트, 클릭한 URL 및 링크 처리기 필드가 포함될 수 있습니다. 셸 플러그인은 공통 ID에 대한 개별 환경 변수를 읽거나 전체 형태에 대한 컨텍스트 JSON을 구문 분석할 수 있습니다.

플러그인이 Node, PowerShell, Bash 또는 다른 런타임에서 이식적으로 Herdr를 호출해야 하는 경우 HERDR_BIN_PATH을 사용하세요. HERDR_SOCKET_PATH 뒤의 원시 소켓 전송은 OS별로 다릅니다. Unix 클라이언트는 Unix 소켓 경로에 연결하고 Windows 클라이언트는 명명된 파이프에 연결합니다. HERDR_BIN_PATH를 통한 CLI 호출은 이러한 전송 차이를 방지합니다. 사용 가능한 명령은 CLI 참조를, 원시 요청 형태는 소켓 API을 참조하세요.

창

매니페스트 패널 placement의 기본값은 overlay입니다. 이는 활성 패널 위에 임시 확대/축소 오버레이를 열고 닫힐 때 이전 포커스 및 확대/축소를 복원합니다. plugin.pane.open 요청은 overlay, popup, split, tab 또는 zoomed을 사용하여 매니페스트 배치를 재정의할 수 있습니다.

placement = "popup"은 타일 레이아웃을 변경하지 않고 세션 모달 터미널 팝업을 엽니다. 매니페스트 또는 공개 요청에서 선택적 width 및 height 필드를 허용합니다. 기본 절반 크기 팝업에서는 이를 생략하고, 외부 터미널 셀 치수에는 숫자를 사용하거나 터미널 영역의 백분율에는 "80%"과 같은 문자열을 사용합니다. Escape를 포함한 모든 터미널 입력을 수신하고 명령이 종료되거나 popup.close 요청이 전송되면 닫힙니다. 팝업 최소값보다 작은 크기는 고정됩니다.

패널이 항상 일시적이어야 하는 경우 플러그인 패널 진입점에서 직접 배치를 선언합니다.

TOML

[[panes]]
id = "picker"
title = "Picker"
platforms = ["linux", "macos"]
placement = "popup"
width = "80%"
height = 20
command = ["sh", "picker.sh"]

분할, 탭, 확대 및 오버레이 플러그인 패널은 열린 후 일반 Herdr 창입니다. 플러그인은 소켓이나 CLI를 통해 pane.move, pane.swap, pane.resize 및 pane.zoom과 같은 표준 패널 API를 호출할 수 있습니다. Herdr는 탭이나 작업 공간을 이동할 때 플러그인 패널 소유권을 기본 패널에 연결된 상태로 유지합니다. 팝업은 Herdr 패널이 아닌 싱글톤 세션 리소스입니다. 팝업에는 패널 ID가 없고 플러그인 포커스 컨텍스트를 변경하지 않으며 패널 수명 주기 이벤트를 생성하지 않으며 패널, 레이아웃, 지속성 또는 에이전트 API에 참여하지 않습니다. 해당 프로세스는 HERDR_PANE_ID를 수신하지 않습니다. 기본 타일 패널은 HERDR_PLUGIN_CONTEXT_JSON을 통해 계속 사용할 수 있습니다. 설정, 복사 모드 또는 다른 Herdr 모달이 활성화된 동안 팝업을 열면 ui_busy이 반환되고, 실행 후 plugin.pane.open은 ok 결과를 반환합니다.

Windows에서 빌드 명령, 작업 명령 및 이벤트 명령은 베어 명령이 PATH에 있을 때 npm.cmd, bun.cmd 및 pnpm.cmd과 같은 일반적인 PATHEXT shim을 확인합니다. 패널 명령은 Herdr의 일반 Windows 패널 실행 프로그램을 사용하며 여전히 유효한 Windows argv 명령이어야 합니다.

키바인딩

설치된 플러그인 작업에 키를 바인딩합니다.

TOML

[[keys.command]]
key = "prefix+l"
type = "plugin_action"
command = "example.layout.apply"
description = "apply layout"

링크 핸들러

브라우저에서 URL을 여는 대신 [[link_handlers]]을 사용하여 일치하는 터미널 URL에 대한 수정된 클릭을 플러그인 작업으로 라우팅합니다. 수정된 클릭 수정자는 macOS를 포함한 모든 플랫폼에서 Control입니다. 캡처된 터미널 마우스 보고서는 일반 클릭과 별도로 Command/Super를 노출하지 않기 때문입니다. pattern은 클릭한 URL과 일치하는 Rust 정규식이며, action는 동일한 플러그인에서 선언된 작업의 이름을 지정해야 합니다. 링크 처리기 작업은 HERDR_PLUGIN_CONTEXT_JSON에서 invocation_source = "link_click", clicked_url 및 link_handler_id를 받습니다. 쉘 플러그인은 HERDR_PLUGIN_CLICKED_URL 및 HERDR_PLUGIN_LINK_HANDLER_ID도 읽을 수 있습니다. 핸들러는 각 플러그인 내에서 매니페스트 순서로 확인됩니다.

저장

v1에는 Herdr 관리 플러그인 스토리지 API가 없습니다. 지속 가능한 상태가 필요한 플러그인은 해당 파일이나 데이터베이스를 소유해야 합니다.

마켓플레이스

커뮤니티 플러그인은 필수 메타데이터를 구문 분석할 수 있는 하나 이상의 herdr-plugin.toml 파일이 포함된 herdr-plugin 태그가 지정된 공개 GitHub 저장소의 자동 색인인 marketplace에서 검색할 수 있습니다. 플러그인은 일반적인 GitHub 저장소로 유지됩니다. 하나를 게시한 다음 herdr plugin install owner/repo[/subdir]를 공유하세요.

플러그인을 나열하려면 GitHub 주제 herdr-plugin을 추가하고 해당 매니페스트를 저장소 기본 분기의 루트나 하위 디렉터리에 배치하세요. 하나의 저장소 카드에는 별도로 설치 가능한 여러 플러그인이 포함될 수 있습니다. 인덱스는 30분마다 새로 고쳐집니다. 검색 방법은 마켓플레이스를 참조하세요.