플러그인 개발 및 구현

컨트롤 플러그인

컨트롤 플러그인은 미리보기 창의 하단 컨트롤 바 왼쪽에 사용자 지정 작업 버튼을 추가하여 활성 파일 또는 폴더에 대한 빠른 작업 및 외부 도구 연동을 지원합니다.

AI 에이전트로 컨트롤 플러그인 구축

아래의 자리 표시자를 교체한 후 코딩 에이전트에 전체 지침을 전달하세요:

https://raw.githubusercontent.com/ccseer/Seer-Controls/refs/heads/main/plugin_development_guide.md 에 있는 Seer 컨트롤 플러그인 개발 가이드를 읽고 따르세요. 아키텍처, plugin.json, 구현, 검증 및 패키징에 대한 단일 진실 출처(Single Source of Truth)로 취급하세요. 가이드를 사용할 수 없는 경우 계속하기 전에 중단하고 보고하세요.

작업을 수행하기 전에 아래의 Requirement(요구 사항)를 검사하세요. 누락되었거나 변경되지 않은 자리 표시자 텍스트이거나 구현하기에 너무 모호한 경우 한 가지 확인 질문을 하고 기다리세요. 누락된 요구 사항을 추측하지 마세요.

명확해지면 현재 작업 영역에서 Canonical v1 프로세스 계약을 준수하는 완전하고 설치 가능한 컨트롤 플러그인을 구현하세요. Seer 자체를 수정하거나 계획 또는 코드 스니펫에서 멈추지 마세요.

가이드의 모든 해당 검증 단계를 따르고 실제 결과를 보고하세요.

Requirement: [이 자리 표시자를 컨트롤 플러그인 요구 사항으로 교체하세요. 예: 현재 디렉터리에서 VS Code 열기 또는 절대 경로를 클립보드에 복사]

아키텍처 및 계약

• 프로세스 모델: Canonical v1 프로세스 계약(backend: "process", capabilities: ["control"])을 구현합니다. Seer는 CLI를 통해 헬퍼를 실행합니다.
• 반환 상태 및 오류 보고:
  • 성공: 프로세스가 종료 코드 0으로 종료됩니다(또는 success_exit_codes와 일치). "close_after_success": true가 구성된 경우 Seer는 실행 성공 후 미리보기 창을 자동으로 닫습니다.
  • 실패: 프로세스가 0이 아닌 코드로 종료됩니다. 표준 오류(stderr)에 기록된 모든 내용은 Seer에 의해 캡처되어 앱 내 토스트 오류 알림으로 표시됩니다.
• UI 및 상호 작용: 컨트롤 플러그인은 자체적인 상주 기본 창을 그리지 않습니다. 일반적인 헬퍼는 백그라운드 작업을 실행하거나, 텍스트를 클립보드에 복사하거나, 네이티브 Windows 시스템 대화 상자(예: 연결 프로그램, 속성, 공유)를 호출합니다.

명령줄 자리 표시자

컨트롤 헬퍼는 대상 경로만 수신합니다 — ${input_file} 및 아래의 공통 자리 표시자 및 일치 토큰 섹션에 나열된 범용 자리 표시자(${use_backslash}, ${seer_dir}, ${seer_exe}, ${seerviewer_exe}, ${7z}).

plugin.json 예시 (Control)

예시 1: 폴더 작업 (Terminal Here)

공식 Terminal Here 플러그인 구성:

{
  "schema_version": 1,
  "id": "io.1218.seer.terminal-here",
  "name": "Terminal Here",
  "description": "Opens a terminal window in the current folder.",
  "version": "1.0.0",
  "appMinVersion": "4.5.10",
  "backend": "process",
  "capabilities": [
    "control"
  ],
  "extensions": [
    "${type_folder}"
  ],
  "command": "terminal_here.exe",
  "arguments": [
    "--input",
    "${input_file}"
  ],
  "close_after_success": false,
  "timeout_ms": 150000,
  "success_exit_codes": [
    0
  ]
}

예시 2: 파일 작업 (Explorer Open With)

공식 Explorer Open With 플러그인 구성:

{
  "schema_version": 1,
  "id": "io.1218.seer.explorer-open-with",
  "name": "Open With",
  "description": "Opens the Windows Open With dialog for the current file.",
  "version": "1.1.0",
  "appMinVersion": "4.5.10",
  "backend": "process",
  "capabilities": [
    "control"
  ],
  "extensions": [
    "${type_file}"
  ],
  "command": "shellopenwith.exe",
  "arguments": [
    "--input",
    "${input_file}",
    "${use_backslash}"
  ],
  "timeout_ms": 30000,
  "success_exit_codes": [
    0
  ]
}

공식 컨트롤 플러그인 소스 코드는 다음을 참조하세요: ccseer/Seer-Controls.

속성 플러그인

속성 플러그인은 Seer의 메타데이터 검사 엔진을 확장합니다. 사용자가 미리보기 중인 파일이나 폴더에서 Ctrl + I를 누르거나(또는 속성 창을 열 때), 일치하는 속성 플러그인이 구조화된 메타데이터와 시각적 스코프/차트를 추출하여 표시합니다.

AI 에이전트로 속성 플러그인 구축

아래의 자리 표시자를 교체한 후 코딩 에이전트에 전체 지침을 전달하세요:

https://raw.githubusercontent.com/ccseer/Seer-Properties/refs/heads/main/plugin_development_guide.md 에 있는 Seer 속성 플러그인 개발 가이드를 읽고 따르세요. 아키텍처, plugin.json, 구현, 검증 및 패키징에 대한 단일 진실 출처(Single Source of Truth)로 취급하세요. 가이드를 사용할 수 없는 경우 계속하기 전에 중단하고 보고하세요.

작업을 수행하기 전에 아래의 Requirement(요구 사항)를 검사하세요. 누락되었거나 변경되지 않은 자리 표시자 텍스트이거나 구현하기에 너무 모호한 경우 한 가지 확인 질문을 하고 기다리세요. 누락된 요구 사항을 추측하지 마세요.

명확해지면 현재 작업 영역에서 Canonical v1 프로세스 계약 및 Schema 1 JSON 사양을 준수하는 완전하고 설치 가능한 속성 플러그인을 구현하세요. Seer 자체를 수정하거나 계획 또는 코드 스니펫에서 멈추지 마세요.

가이드의 모든 해당 검증 단계를 따르고 실제 결과를 보고하세요.

Requirement: [이 자리 표시자를 속성 플러그인 요구 사항으로 교체하세요. 예: MP4 파일의 세부 오디오/비디오 코덱 매개변수 및 비트레이트 추출 및 표시]

아키텍처 및 계약

• 프로세스 모델: Canonical v1 프로세스 계약(backend: "process", capabilities: ["property"], result_schema: 1)을 구현합니다.
• CLI 호출: 호스트가 다음을 전달합니다: --input "${input_file}" --output "${output_file}" --output-dir "${output_dir}"
• 출력 게시:
  • 호스트는 ${output_file}을 확장자가 없는 기본 경로(예: <requestDir>/<md5>)로 확장합니다.
  • 플러그인은 JSON 결과를 <output-base>.json(즉, ${output_file}.json)에 작성해야 합니다.
  • 시각적 첨부 파일(차트, 히스토그램, 벡터스코프)은 ${output_dir}에 저장해야 합니다.
  • 제약 조건: 속성 플러그인에는 ${no_cache}를 사용할 수 없습니다.
• 종료 코드 정책:
  • 예상되는 도메인 결과(예: 서명되지 않은 파일, git 저장소가 아님, 빈 메타데이터 등)는 반드시 종료 코드 0으로 종료하고 JSON에 상태를 설명해야 합니다.
  • 치명적인 오류나 유효하지 않은 호출의 경우에만 0이 아닌 코드로 종료하세요(0이 아닌 종료 시 호스트가 요청 디렉터리를 완전히 삭제합니다).

명령줄 자리 표시자

또한 아래의 공통 자리 표시자 및 일치 토큰 섹션에 나열된 범용 자리 표시자 및 ${type_*} 일치 토큰을 지원합니다. 속성 플러그인에서는 ${no_cache}가 거부됩니다.

결과 JSON (Schema 1) 사양

결과 파일 ${output_file}.json은 result_schema: 1 및 data 개체를 포함하는 유효한 UTF-8 JSON이어야 합니다:

1. 단순 행 (Flat Rows)

전체 결과가 단일 행인 경우에만 사용합니다 (예: SHA-256):

{
  "result_schema": 1,
  "data": {
    "SHA-256": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
  }
}

2. 순서가 지정된 단일 키 객체 배열을 포함하는 하위 그룹 (기본값)

둘 이상의 행을 생성하는 결과는 플러그인 이름을 딴 정확히 하나의 하위 그룹으로 게시해야 합니다. 최상위 수준의 느슨한 행은 다른 모든 플러그인의 행과 충돌하며, 검사기는 이를 하나의 목록으로 표시합니다. 배열의 순서가 곧 렌더링 순서이므로, 행이 나타나는 순서를 플러그인이 결정할 수 있는 유일한 형식입니다:

{
  "result_schema": 1,
  "data": {
    "Git": {
      "value": [
        { "Repository": "ccseer/Seer-Properties" },
        { "Branch": "main" },
        { "Status": "Clean" }
      ]
    }
  }
}

3. 값 객체를 포함하는 하위 그룹

value는 일반 객체일 수도 있지만, 그 행은 파싱된 객체의 키 순서로 렌더링되며 플러그인이 제어할 수 없습니다. 행 순서가 중요하지 않은 경우에만 사용하세요:

{
  "result_schema": 1,
  "data": {
    "Git": {
      "value": {
        "Branch": "main",
        "Status": "Working tree clean"
      }
    }
  }
}

4. 그래픽 차트 및 스코프 (이미지 첨부 파일)

생성된 PNG 차트를 ${output_dir}에 저장하고 {"type": "image", "value": "relative_filename.png"} 형식으로 선언합니다:

{
  "result_schema": 1,
  "data": {
    "Image Scopes": {
      "value": [
        { "RGB Histogram": { "type": "image", "value": "histogram.png" } },
        { "Luma Waveform": { "type": "image", "value": "waveform.png" } }
      ]
    }
  }
}

plugin.json 예시 (Property)

{
  "schema_version": 1,
  "id": "io.1218.seer.git-info",
  "name": "Git Info",
  "description": "Reports repository information for the current folder using Git.",
  "version": "1.0.0",
  "appMinVersion": "4.5.10",
  "backend": "process",
  "capabilities": [
    "property"
  ],
  "extensions": [
    "${type_folder}"
  ],
  "invocations": {
    "property": {
      "command": "git_info.exe",
      "arguments": [
        "--input",
        "${input_file}",
        "--output",
        "${output_file}",
        "--output-dir",
        "${output_dir}"
      ],
      "result_schema": 1,
      "timeout_ms": 30000,
      "success_exit_codes": [
        0
      ]
    }
  }
}

공식 속성 플러그인 소스 코드는 다음을 참조하세요: ccseer/Seer-Properties.