dsh-pet 🐾

DeepSeek Harness에 사는 데스크톱 펫입니다: 대기 호흡, 무작위 동작(졸기, 루빅스 큐브 놀이, 훠궈 먹기 등), 좌우 방향 전환, 화면 배회, Q를 클릭하면 통통 튀기, 드래그하여 던지거나 반사시키기, 마우스 오른쪽 버튼 메뉴 호출—100여 개에 달하는 수작업 애니메이션 투명 애니메이션이 끊김 없이 연결됩니다. 또한 DSH 세션 이벤트에 맞춰 작업 상태 애니메이션을 전환할 수 있으며, 단계별로 잔액 애니메이션 + 머리 위 말풍선 표시, 잡담 및 대화 채팅 기능도 제공합니다. 여러 개를 동시에 띄울 수 있고, 브라우저에서 벗어나 데스크톱 (투명 고정 작은 창)에 거주하게 할 수도 있으며, 스스로 새로운 종류의 펫 (pet pack)을 추가할 수도 있습니다.

이것은 단순한 플러그인이 아니라 완벽한 삼위일체 프로젝트입니다:

① 프롬프트(배합)    →  ② 소재 생성 체인(엔진)  →  ③ 플러그인(완제품)
AI가 애니메이션을 생성하는 배합     원천 비디오 → 투명 애니메이션 파이프라인    DSH에서 실행되는 펫

누구나 이 저장소를 clone하면 처음부터 자신만의 데스크톱 펫을 만들 수 있습니다—캐릭터 변경, 동작 변경, 스타일 변경 등 모든 과정이 재현 가능합니다.

빠른 시작 (플러그인 설치)

설치 방법은 어떤 DSH를 사용하는지에 따라 다릅니다:

🪟 데스크톱 애플리케이션(Electron 버전)

직접 애플리케이션 내의 「플러그인 관리」 페이지 설치 창에 dsh-pet을 입력하면 터미널을 열 필요가 없습니다. 다만, 터미널에서 플러그인을 조작할 때는 데스크톱 애플리케이션 자체에 포함된 CLI를 사용해야 합니다.

🌐 dsh web

아래 명령어들은 명령줄 터미널(PowerShell / CMD 등)에서 실행합니다. 전제 조건은 DSH 환경이 준비되어 있어야 한다는 것입니다:

# ① 선행 요구사항: Node.js가 설치되었는지 확인
node -v

...

재부팅 후 재실행해야 적용됩니다. 실행 중인 프로세스는 메모리에 있는 이전 플러그인을 유지하기 때문입니다. 펫은 화면 오른쪽 상단(기본 설정 코너, 설정 페이지에서 수정 가능)에 나타납니다.

호환성: 본 플러그인은 현재 dsh 0.2.1-rc.2 버전에서 개발 및 테스트되었습니다 (dsh --version으로 버전을 확인할 수 있습니다). 동일한 버전을 사용하는 것이 권장되며, 다른 버전에서 문제가 발생할 경우 피드백을 환영합니다.

소스 코드로부터 설치하기 (본 레포지토리 클론 후)

lib/에 생성된 빌드 산출물은 라이브러리에 포함되지 않으므로, 클론한 후에는 먼저 빌드하고 설치해야 합니다:

# ① 본 레포지토리를 클론하고 플러그인 디렉토리로 이동
git clone https://github.com/PC2005-cloud/dsh-pet.git
cd dsh-pet/dsh-pet
...

참고: npm run build (즉, scripts/prepare.js)를 실행해야 완벽하게 설치 가능한 lib가 생성됩니다. tsdown 빌드 외에도 데스크톱 공유 핵심(shared-core.js)을 빌드하고, 타입 선언을 생성하며, 배포용 files 목록을 수렴합니다. 순수한 tsdown 빌드는 데스크톱 런타임과 타입을 누락시킵니다. 배포 및 패키징 시 (npm publish / npm pack)는 prepack이 이를 자동으로 호출하므로, 레포지토리를 클론한 후에는 수동으로 한 번 실행해야 합니다.

설치 후 무엇을 보게 될까요

기본 설정은 `display:

소규모 수정은 별도 버전으로 배포하지 않습니다. 사용에 영향을 주지 않는 작은 버그나 최적화는 다음 버전과 함께 누적되어 배포되므로, 버전 업데이트가 너무 잦아지는 것을 방지합니다. 따라서 「main에서 이미 수정됨」이 「사용자가 설치한 이 버전에도 포함됨」을 의미하지 않습니다. latest가 업데이트되지 않았다면, main의 커밋 기록을 기준으로 합니다.
미출시된 수정을 즉시 사용하고 싶다면: 위에 안내된 「소스 코드로부터 설치」를 통해 플러그인을 로컬 저장소로 지정하면 됩니다. 주의할 점은 호스트(Host) 측의 코드 변경 사항은 DSH를 재실행해야만 적용된다는 것입니다 (브라우저 측은 페이지 새로고침으로 충분합니다).
버그 보고 시 다음 정보를 포함해 주세요: 플러그인 버전, dsh 버전, 운영체제, 재현 단계(로그나 스크린샷이 있으면 더 좋습니다).

플러그인 기능

순수한 데스크톱 펫: 날씨, 모니터링 등 관련 없는 기능은 하지 않으며 DSH 코어에 영향을 주지 않습니다. 선택 가능한 능력은 아래 항목들뿐입니다 (잔액 / 잡담 / 대화 / 작업 상태 / 시스템 알림)
애니메이션 체인: 각 애니메이션(대기 포함)이 재생되면 가중치에 따라 다음 애니메이션을 선택합니다 (기본 idle 10 / turn 5 / move 5 + 분류 가중치, config.jsonc에서 조정 가능). 애니메이션은 순차적으로 연결됩니다.
이벤트 애니메이션: 잔액 / 잡담 / 작업 상태는 단계별로 전용 애니메이션을 트리거합니다. 단계는 후보 배열을 지원하여, 트리거 시 해당 단계 내에서 무작위로 또는 순환하며 재생되어 연속으로 같은 애니메이션이 재생되는 것을 방지합니다.
다중 실행: 여러 개의 펫을 동시에 표시할 수 있으며, 각 펫은 독립적인 크기와 위치를 가집니다 (설정 페이지의 「데스크톱 펫 설정」에서 추가/삭제).
화면 유영(Screen Roaming): 지정된 방향으로 걸어 다니며, 먼저 공간을 탐지하고 화면 밖으로 나가지 않습니다 (다중 모니터는 각 화면 경계를 기준으로 판단합니다. 설정 페이지의 「현재 화면에 고정」을 활성화하면 현재 해당 화면 내에서만 움직입니다).
클릭 / 드래그 / 던지기: 클릭 시 반응 애니메이션과 탄력적인 압축이 발생합니다. 드래그할 때는 감쇠 스프링처럼 따라오고, 놓으면 포물선으로 날아가며 화면 가장자리에서 반동하고 착지 후 마찰로 멈추면서 탄력적으로 한 번 더 움직입니다. 부드럽게 내려놓으면 제자리에 멈춥니다. 양 끝단은 동일한 순수 함수 물리 및 압축 곡선을 사용합니다 (dsh-pet/src/shared/physics.ts).
우클릭 메뉴: 「액션 → 분류 → 구체적인 애니메이션」을 임의로 재생할 수 있습니다 (이동 관련 애니메이션을 재생하면 실제로 걸어 다니는 구간이 발생합니다). 도구 항목은 다음과 같습니다 — 브라우저 측: 잡담 / 대화 / 초기 위치로 돌아가기; 데스크톱 측: + 웹사이트 열기, 잔액 확인(잔액 활성화 시 표시), 설정 재로드(설정 파일을 수정한 후 모든 데스크톱 펫을 우클릭하여 바로 재로드할 수 있으며, 설정 페이지로 돌아가 저장할 필요가 없습니다).
「웹사이트 열기」는 호스트에 따라 자동 분배됩니다: 펫의 호스트가 DSH 데스크톱 애플리케이션일 경우, 이 항목은 자동으로 「DeepSeek Harness 열기」로 변경되어 — 앱이 자체 등록한 dsh://open 프로토콜을 사용하여 데스크톱 애플리케이션 메인 창을 전경으로 가져옵니다 (이미 실행 중이면 전경화하고, 실행 중이 아니면 실행합니다); 호스트가 dsh web / 독립 모드일 경우, 시스템 기본 브라우저로 사이트를 엽니다.
방향 및 착지: 모든 애니메이션은 미러링(좌/우 방향)이 가능하며, 발바닥 라인은 통일되어 있어 펫은 항상 바닥에 서 있습니다.
부드러운 전환: 이중 버퍼 교차 페이드 인을 사용하여 전환 시 공백 프레임이 없습니다.
잔액 표시: 사용된 백분율에 따라 단계별로 잔액 애니메이션을 재생하고 머리 위에 연상 거품(10초 후 자동 사라짐)을 띄웁니다. DeepSeek은 계좌 잔액을, OpenCode Zen Go와 Command Code는 가장 시급한 한도 창을 표시합니다. 미등록 잔액 인터페이스 서비스 제공자는 팝업 문자 설명으로 변경되었습니다 (더 이상 무음 처리하지 않음); 펫별로 독립적인 스위치가 있습니다.
잡담 및 대화: 잡담은 주기적으로 자동으로 문장 하나를 생성합니다 (말하는 애니메이션 + 거품, 수동 트리거도 가능). 대화는 우클릭 메뉴의 입력창에서 펫과 채팅하며, 기억이 영구 저장됩니다 (브라우저 / 데스크톱 공유 동일한 데이터).
작업 상태 연동: DSH 세션 이벤트를 감지하여 「사고 중 / 작업 중 / 정리 중 / 대기 중 / 성공 / 오류」 단계 애니메이션과 상시 거품을 전환합니다. 다단계 목표 임무는 실제로 마무리되는 라운드에서만 축하합니다.
시스템 알림: 창이 포커스를 잃으면 시스템 토스트(대화 완료 / 생성 실패 / 출력 잘림 / 권한 요청 / 사용자 선택)가 표시됩니다.
데스크톱 모드 (선택 사항): 각 펫마다 독립적인 투명 고정형 작은 창을 열어, 브라우저와 엄격하게 동일하게 작동하며 동일한 소재와 순수 로직을 공유합니다 (아래 섹션 참조).
pet pack (추가 펫 종류): pet/ 아래에 종류명-config.json과 종류명-animation/ 폴더를 생성하면, 독립적인 애니메이션 풀과 소재를 가진 새로운 종류가 추가됩니다. 다중 인스턴스는 소재를 공유합니다 (「설정 → 방법 4」 참조).
사용자 정의 애니메이션: main-animation/webm/에 VP9-Alpha 형식의 .webm 파일을 넣으면, 패키지 내 소재보다 우선하여 새로운 애니메이션이 됩니다.
웹 접근성: prefers-reduced-motion을 지원합니다 (동작 최소화 설정 시 탄력적인 압축 및 페이드 인 전환 건너뛰기).

🔌 외부 인터페이스 (다른 플러그인이 호출할 수 있도록)

데스크톱 펫은 스스로만 작동하는 것이 아니라, 외부 HTTP 인터페이스 세트를 개방하여 다른 플러그인이나 스크립트가 이를 구동하거나 상태를 읽을 수 있게 합니다.

할 수 있는 것: 지정된 말 한마디를 하게 하거나, 특정 애니메이션을 재생하거나, 대화를 나눌 수 있습니다. 현재 말하는 내용, 작업 상태, 시스템 알림 및 잔액 등을 읽어올 수 있습니다.
개방 이유: 데스크톱 펫은 단순한 장식품에 그쳐서는 안 됩니다. 예를 들어 '여성 비서(maid)' 플러그인이 검사 후 무언가 말하고 싶을 때, 이 데스크톱 펫이 마치 그녀의 '실체'처럼 입을 열게 할 수 있습니다. 또한 누구나 이를 기반으로 이차 개발하기 편리합니다.
설정 방법: DSH 자체 웹 서비스에 연결(접두사 /dsh-pet-7340, 로컬 본체만 청취, 인증 없음). 액션 관련 인터페이스는 {ok}만 반환하며, 데이터는 모두 GET /state`에서 읽어옵니다.

세 가지 관련 파일:

API.md — 인터페이스 목록 (각 인터페이스 한 문장 요약, 기능 미리보기)
openapi.yaml — 전체 계약서 (OpenAPI 3.1, Swagger UI / Postman에 직접 가져오기 가능)
tools/api-tester.html — 데스크톱 펫 제어 콘솔: 서드파티 소비자의 예시 페이지로, 직관적인 사용이 가능합니다 (node tools/api-tester.cjs 실행).

호환성

운영체제: Windows / Linux / macOS 세 플랫폼 모두에서 실행 가능 — 브라우저 오버레이와 데스크톱 모드(Electron 투명 고정 창)의 동작은 완벽하게 일치합니다. Electron은 플랫폼별로 자동 탐지/다운로드됩니다 (electron.exe / Electron.app / linux 단일 파일), 수동 설치가 필요 없습니다.
헤드리스 / 데스크톱 환경 없음: Linux 헤드리스 등 그래픽 세션이 없는 환경도 지원합니다 — 데스크톱 모드는 자동적으로 디스플레이 환경을 감지합니다 (Linux에 DISPLAY 또는 WAYLAND_DISPLAY가 없을 경우, 화면 없음으로 판단하고 데스크톱 창은 건너뛰고 로그로만 경고). 브라우저 오버레이는 영향을 받지 않습니다.
브라우저: 브라우저 오버레이는 Chromium 코어(Chrome / Edge 등)와 Firefox를 지원합니다 — 투명 애니메이션은 VP9-Alpha webm에 의존하며, 세 가지 모두 투명도가 확인되었습니다. Safari는 지원하지 않습니다 (macOS가 webm alpha를 인식하지 않아 투명 렌더링 시 검은색 배경으로 표시됨) — macOS의 경우 .mov 소재를 사용합니다 (GitHub Release assets-mov에서 다운로드하여 넣고 ANIMATION_EXT 변수를 수정하면 됩니다. 「②.5 Safari/HEVC 호환 소재」 참조).
다중 디스플레이: 다중 모니터 환경을 지원합니다 — 화면 간 이동/투척은 각 화면 작업 영역을 경계로 하며, 이종 스케일링(각 화면의 DPI가 다른 경우), 작업 표시줄 바, 화면 사이의 빈 공간까지 정확하게 판별합니다 (가로 / 세로 / 상하 배치 모두 가능). 설정 페이지의 '현재 화면에 고정' 기능을 사용하면 펫이 (투척 및 이동) 현재 위치한 화면 내에서만 활동하도록 할 수 있습니다.

🪟 데스크톱 모드 (선택 사항, 브라우저와 분리)

플러그인은 듀얼 모드를 내장하고 있습니다: 설치 후 기본적으로 독립적인 투명 고정 소형 창을 실행합니다 — 각 데스크톱 펫마다 개별 로컬 창이 열립니다 (펫을 따라 이동하며, 화면 전체를 채우지 않음). 이 동작은 브라우저 오버레이와 엄격하게 동일하며 기능도 완벽히 일치합니다:

의존성: 최초 시작 시 Electron을 자동 탐지/다운로드합니다 (~/.dsh/electron/, 또는 cd dsh-pet && npm run ensure:electron으로 수동 트리거 가능). 누락된 경우 로그 경고만 발생하며 브라우저 형태에는 영향을 주지 않습니다.
스위치 = 각 펫의 필수 필드 display: web = 브라우저만 / desktop = 데스크톱만 / both = 둘 다 / none = 아무것도 표시 안 함; 데스크톱 모드는 display에 desktop이 포함된 모든 펫을 렌더링합니다 (같은 화면에 여러 개 열릴 수 있으며, 브라우저와 동일). 설정 페이지의 '데스크톱 펫 설정'에서 편집하면 즉시 적용됩니다.
데스크톱 측 데이터는 독립적인 프로세스 파이프를 사용하며, DSH의 HTTP 라우팅에 의존하지 않아 웹 접근 게이트의 영향을 받지 않습니다.
로컬 디버깅: cd dsh-pet && npm run start:desktop -- http://127.0.0.1:3080/dsh-pet-7340/config (호스트가 없을 경우 자동으로 HTTP 경로로 회귀)

🧍 독립 실행 (DSH를 전혀 열지 않음)

DSH조차 필요 없습니다: 플러그인의 호스트 절반이 가짜 컨텍스트(pseudo ctx)에서 실행되며, 로컬 본체 HTTP 서비스가 라우팅을 담당합니다 (라우트 테이블은 여전히 플러그인의 것).

npm install -g dsh-pet        # 반드시 npm으로 설치해야 합니다; dsh plugin add로 프로필에 추가하면 bin이 PATH에 없습니다.
dsh-pet-standalone            # http://127.0.0.1:3080/dsh-pet-7340/ (점유 중이면 다음 포트로 조정)
dsh-pet-standalone --check    # 검사만 수행
...

사용 가능: 애니메이션 체인, 클릭/드래그/던지기, 마우스 오른쪽 버튼 메뉴, 다중 실행(多開), 사용자 지정 애니메이션 및 이모티콘 팩, pet pack.
사용 불가: 잔액, 잡담, 대화, 시스템 알림 — reason이 포함된 구조화된 실패를 반환 (["API.md"] 참조).
설정: DSH와 동일한 설정 파일 사용 ($DSH_HOME/dsh-pet/main-config.jsonc → 패키지 내 기본값).
display에 desktop/both를 포함하는 인스턴스만 표시; 포트는 기본 3080; Ctrl+C 또는 POST /shutdown으로 종료.
DSH 내부 실행과 동시에 열 수 있으나, %APPDATA%\dsh-pet-electron-helper를 공유하므로 캐시 충돌이 발생할 수 있음 (경고만 표시).

⚙️ 잔액 표시 (Balance)

eventsRefreshSec.balance (초) 주기로 현재 서비스 제공업체의 잔액/사용량 데이터를 가져오며, 새로 고침 시마다 단계별 애니메이션을 트리거하고, 반려동물 머리 위에 연상 거품이 팝업됩니다 (반려동물의 크기 등에 비례하여 축소 확대되며, 10초 후 자동 사라짐):

DeepSeek 공식 (deepseek-official): 거품에 계정 잔액 표시 (예: 잔액 ¥8.79); 잔액은 ¥20 단위로 만액 기준으로 환산되어 사용된 백분율을 나타내며, 6단계 애니메이션으로 재생됩니다 (돈주머니 가득 → 금주머니 딸랑 → 돈주머니 평상시 → 돈 주름지게 → 주머니 비어 깨끗함 → 동전 한 닢도 남지 않음).
OpenCode Zen Go (opencode-go): 거품에 5시간/주/월 세 가지 할당량 창 중 가장 먼저 부족한 것을 표시 (예: 주간 할당량 사용 88% / 2.5일 재설정), 이 역시 사용된 백분율에 따라 단계별로 재생됩니다.
Command Code (commandcode, GOAT 등 패키지 포함): 거품에 5시간/주/월 세 가지 할당량 창 중 가장 먼저 부족한 것을 표시 (opencode와 동일한 기준: 남은 할당량이 가장 적은 것, 보통 5시간을 먼저 보고); 패키지에 기간 제한이 없을 경우 월간 창만 표시합니다.
미지원 서비스 제공업체: 잔액 인터페이스가 등록되지 않은 서비스 제공업체는 단계별 애니메이션 대신 문자 설명 한 줄로 대체됩니다. 첫 번째 줄은 「현재 서비스 제공업체는 잔액 조회가 지원되지 않습니다」이며, 두 번째 줄에는 현재 provider id를 표시합니다 (자가 점검 용이). 자가 탐색 실패/자격 증명 부족 시에도 동일하게 처리됩니다. 자동 폴링(polling)은 원인이 변경될 때만 한 번 팝업되며, 수동으로 /balance 또는 데스크톱 마우스 오른쪽 버튼 「잔액 보기」를 클릭하면 매번 팝업합니다.
반려동물별 스위치: pets[i].balanceEnabled (필수 부울)로 해당 반려동물이 잔액 애니메이션/거품을 트리거할지 여부를 제어합니다.
필요 자격 증명: 각 provider에 해당하는 API 키 (deepseek-official → DEEPSEEK_API_KEY; opencode-go → OPENCODE_GO_API_KEY; commandcode → COMMANDCODE_API_KEY)를 DSH 자격 증명에서 설정한 후 활성화해야 합니다. 매칭되지 않는 서비스 제공업체는 애니메이션을 트리거하지 않고 위의 문자 설명 거품으로 대체됩니다.

⚙️ 잡담 및 대화 (Whisper & Chat)

잡담: pets[i].whisperEnabled가 활성화되면, eventsRefreshSec.whisper (초, 기본값 300) 주기로 자동으로 문장 하나를 생성합니다 — 각 반려동물마다 독립적인 주기와 문안을 가집니다; 트리거 시 무작위로 events.whisper 애니메이션 + 머리 위 말풍선이 나타납니다 (10초 사라짐). 기본적으로 활성화되어 있습니다.
수동 트리거: 마우스 오른쪽 버튼 메뉴 「잡담」에서 언제든지 문장을 받을 수 있으며 — whisperEnabled의 제약을 받지 않습니다 (해당 필드는 자동 주기 폴링만 비활성화함).
대화: 마우스 오른쪽 버튼 메뉴 「대화」 또는 /chat 명령을 사용하면 입력창이 열리고 반려동물과 대화할 수 있습니다 — 답변은 잡담과 동일한 방식으로 표시됩니다 (말하는 애니메이션 + 거품); 기억의 영속성은 $DSH_HOME/dsh-pet/memory.json에 저장되며, 브라우저와 데스크톱이 같은 파일을 공유합니다; 다수의 반려동물이 있을 경우 /pet을 먼저 사용하여 대화 대상을 선택해야 합니다.

⚙️ 작업 상태 연동 (Work Status)

pets[i].workStatusEnabled가 활성화되면, 반려동물은 DSH 세션 활동에 따라 「사고 / 작업 / 정리 / 대기 / 성공 / 오류」 여섯 단계 애니메이션 + 머리 위 거품을 따릅니다: 비종료 상태 애니메이션이 반복 재생되고, 거품은 상시 표시됩니다; 성공/오류는 한 번 재생되며, 거품은 10초 후 자동 수거됩니다.

단계별 애니메이션: animations.events.workStatus 배열이며, 인덱스가 단계입니다 (중간에 새 단계를 삽입하지 말고, 끝에만 추가할 수 있습니다).
거품 문안: workStatusTexts에서 각 단계마다 여러 개의 무작위 문구를 설정할 수 있으며, 작업 상세 정보(todo)가 우선합니다.
단계 후보 배열: 임의의 단계 슬롯에는 string | string[]를 작성할 수 있습니다 — 배열 = 해당 단계 내에서 무작위로 1개를 추출하여 순환 재생하며, 연속으로 같은 내용이 나오는 것을 방지합니다 (잔액 / 잡담 단계에도 동일하게 적용됩니다).

⚙️ 설정 (크기 / 위치 / 다중 실행)

테이블 펫(桌宠)의 크기, 위치, 다중 실행 여부 모두 설정 가능하며, 두 가지 경로가 있습니다:

💡 두 경로는 편집 진입점만 다를 뿐, 최종적으로는 동일한 사용자 설정 파일을 사용합니다. — 설정 페이지에서 변경 가능한 옵션보다 훨씬 많은 설정 능력을 가지고 있습니다. 설정 페이지에서는 크기/위치/여백(margin)/표시 위치/잔액 스위치/다중 실행 여부 등을 수정할 수 있지만, 수동으로 설정 파일(config.jsonc)을 작성하면 애니메이션 풀, 재생 가중치, 이벤트 애니메이션, 새로고침 주기 등 원하는 대로 자유롭게 구성할 수 있습니다. 단지 형식이 패키지에 포함된 기본 설정 파일 config.jsonc과 일치하기만 하면 되며, 사용자 설정은 해당 필드의 기본값을 전체적으로 덮어씁니다.

방식 1: 설정 페이지 (권장)

DSH 설정 → 「테이블 펫 설정」:

크기: 너비 px (높이는 자동 계산 = 너비 × 9/16)
위치: 네 귀퉁이(corner) + 수평/수직 여백(marginX / marginY)
표시 위치(display): web=브라우저 전용 / desktop=데스크톱 전용 / both=둘 다 표시 / none=아무것도 표시 안 함
잔액 기능: 체크 시 해당 펫이 잔액 애니메이션을 트리거하고 잔액 풍선을 표시합니다. (서비스 제공자가 잔액 인터페이스를 등록하지 않은 경우, 텍스트 설명 풍선으로 대체됩니다.)
다중 실행: 펫 추가/삭제. 각 펫은 독립적인 ID, 크기, 위치를 가집니다.
물리적 매개변수: 던지거나 떨어뜨리는 느낌(중력 / 탄성 / 바닥 마찰 / 총 힘 / 상단 반발 / 펫 간 충돌)도 설정 페이지에서 그래픽적으로 수정할 수 있어, 파일을 직접 수정할 필요가 없습니다.
AI 모델: 잡담과 대화는 각각 지정된 모델을 사용할 수 있습니다. — 설정 페이지의 「AI 모델」 항목은 각 항목마다 드롭다운 메뉴를 제공합니다. (DSH 대화창 오른쪽 하단의 모델 선택기와 동일: 검색창 + 서비스 제공자별 그룹 목록, 옵션 출처가 같습니다.) '현재 대화 따르기'를 선택하면 현재 대화의 모델을 사용하며, 지정했으나 호출에 실패할 경우 자동으로 현재 대화의 모델로 재시도됩니다.
「저장」 버튼은 즉시 적용되며 (새로고침 불필요), 「동기화」는 패키지 내 config.jsonc의 원본 내용(주석 및 모든 고급 필드 포함)을 사용자 설정 파일에 통째로 작성합니다. 이는 기본값으로 돌아가는 것과 같지만, 직접 편집 가능한 완전한 설정 파일을 남겨줍니다.

방식 2: config.jsonc (단일 출처)

플러그인 패키지 내 dsh-pet/assets/config.jsonc의 pets 배열에 기본 펫이 정의되어 있습니다:

"pets": [
  { "id": "main", "size": 462, "balanceEnabled": true, "display": "both", "position": { "corner": "top-right", "marginX": 24, "marginY": 100 } }
]

각 펫: id(식별자) / size(너비 px) / balanceEnabled(잔액 기능 활성화 여부, 필수 부울) / display(web/desktop/both/none, 필수, 위 참조) / position(네 귀퉁이 중 하나 + marginX/marginY 여백)
잔액 새로고침 주기: eventsRefreshSec.balance (초) — 잔액 데이터가 새로고침되고 잔액 애니메이션이 트리거되는 간격입니다. 시작 시 즉시 한 번 트리거되며, 이후 이 주기에 따라 순환합니다 (기본값 1800).
설정 페이지에서 수정한 내용은 사용자 계층의 $DSH_HOME/dsh-pet/main-config.jsonc에 저장됩니다 (전체 펫 목록이며, 패키지 기본값을 덮어씁니다). 「동기화」는 패키지 내 config.jsonc 원본 전체를 이 파일에 작성합니다 (이는 기본값으로 돌아가는 것과 같지만, 파일이 남아 직접 편집할 수 있습니다).

방식 3: 설정 파일 수동 편집 (고급, 자유로운 구성)

사용자 계층의 설정 파일은 $DSH_HOME/dsh-pet/main-config.jsonc에 위치합니다. 이 파일은 패키지 기본 설정과 동일한 형식을 가집니다. 따라서 무엇을 수정하고 싶은지에 따라 assets/config.jsonc 구조를 그대로 따라 작성하면 됩니다. 잘못된 필드나 누락된 필드는 기본값으로 돌아가며, 전체 파일을 작성할 필요도 (그리고 할 수도) 없습니다. 설정 페이지의 「동기화」 기능을 사용하면 이 완전한 파일(원본 복사본이며 주석이 완벽하게 포함됨)을 직접 생성할 수 있습니다.

필드	역할	형식 및 기본값 유지
`pets`	펫 목록 (크기/위치/다중 실행/잔액 스위치)	배열, 각 항목은 `pets[]` 구조와 동일
...

오버라이드 의미: 사용자가 해당 필드를 지정하면 전체적으로 대체합니다 (예: animations를 작성했다면 전체 애니메이션 풀을 사용하고 기본값을 대체). 작성하지 않은 필드는 패키지 내의 기본값으로 돌아갑니다. 유효성 검사는 플러그인 로드 시 실행됩니다 — 형식 오류는 DSH 콘솔에 명시적으로 오류가 표시되며, 불완전한 설정이 조용히 작동하지 않습니다.

방식 4: 추가 펫 (pet pack) — 새로운 '종류' 추가

방식 1~3은 기본 펫의 인스턴스만 조정합니다 (수량/크기/위치). 애니메이션 풀은 항상 전역적으로 하나입니다. 완전히 새로운 종류의 펫 (독립적인 애니메이션 풀 + 자체 소재)을 추가하려면, 사용자 데이터 루트 아래에 pet/ 디렉토리를 생성합니다:

$DSH_HOME/dsh-pet/
├─ main-config.jsonc           ← 메인 펫 설정 (기존, 변경 없음)
├─ main-animation/webm/*.webm  ← 메인 펫 소재 (기존, main에만 속함)
...

추가 펫 한 종류 = -config.json 파일 하나 + -animation/ 디렉토리 하나로 구성되며, 접두사(prefix)를 맞춰야 합니다. pet/을 스캔하여 자동으로 발견하며, 브라우저와 데스크톱 모두에 동시에 적용됩니다. 하나의 -config.json은 하나의 '종류' (애니메이션 풀 + 소재 디렉토리)를 정의하고, pets 배열에는 해당 종류의 임의의 여러 인스턴스를 배치할 수 있습니다 (애니메이션 풀 및 소재 공유):

// pet/pig-config.json —— main-config.jsonc와 동일한 구조의 전체 설정
{
  "notificationsEnabled": true,
...

dsh-pet: DeepSeek Harness용 데스크톱 펫

요약

핵심 포인트

dsh-pet 🐾

빠른 시작 (플러그인 설치)

🪟 데스크톱 애플리케이션(Electron 버전)

🌐 dsh web

소스 코드로부터 설치하기 (본 레포지토리 클론 후)

설치 후 무엇을 보게 될까요

플러그인 기능

🔌 외부 인터페이스 (다른 플러그인이 호출할 수 있도록)

호환성

🪟 데스크톱 모드 (선택 사항, 브라우저와 분리)

🧍 독립 실행 (DSH를 전혀 열지 않음)

⚙️ 잔액 표시 (Balance)

⚙️ 잡담 및 대화 (Whisper & Chat)

⚙️ 작업 상태 연동 (Work Status)

⚙️ 설정 (크기 / 위치 / 다중 실행)

방식 1: 설정 페이지 (권장)

방식 2: config.jsonc (단일 출처)

방식 3: 설정 파일 수동 편집 (고급, 자유로운 구성)

방식 4: 추가 펫 (pet pack) — 새로운 '종류' 추가

댓글

dsh-pet 🐾

빠른 시작 (플러그인 설치)

🪟 데스크톱 애플리케이션(Electron 버전)

🌐 dsh web

소스 코드로부터 설치하기 (본 레포지토리 클론 후)

설치 후 무엇을 보게 될까요

플러그인 기능

🔌 외부 인터페이스 (다른 플러그인이 호출할 수 있도록)

호환성

🪟 데스크톱 모드 (선택 사항, 브라우저와 분리)

🧍 독립 실행 (DSH를 전혀 열지 않음)

⚙️ 잔액 표시 (Balance)

⚙️ 잡담 및 대화 (Whisper & Chat)

⚙️ 작업 상태 연동 (Work Status)

⚙️ 설정 (크기 / 위치 / 다중 실행)

방식 1: 설정 페이지 (권장)

방식 2: config.jsonc (단일 출처)

방식 3: 설정 파일 수동 편집 (고급, 자유로운 구성)

방식 4: 추가 펫 (pet pack) — 새로운 '종류' 추가