이 책의 안내

열세 개 절이 「설치 → 사용 → 문제 해결」 순서로 배치되어 있습니다. 특정 문제만 해결하려면 12절로 바로 이동하세요.

• 1 · 무엇인가 — 세 계층 구조, 일상에서는 맨 위 계층만 다룹니다.
• 2 · 설치 — 세 플랫폼에서 어떤 패키지를 받아 어떻게 설치하는지.
• 3 · 처음 실행 — 여섯 단계 마법사, 그리고 「창을 닫는 것은 종료가 아닙니다」.
• 4 · 메인 화면 한눈에 — 네 영역이 각각 무엇을 맡는지.
• 5 · 첫 대화 — 요구 사항을 명확하게 전달하는 방법.
• 6 · 트레이 메뉴 — 시스템 수준의 진입점이 모두 여기에 있습니다.
• 7 · 설정 페이지 — 구역별로 무엇을 바꿀 수 있는지.
• 8 · Profile — 여러 설정을 전환하는 방법과 실패 시 되돌리기.
• 9 · 사전 설치된 플러그인 — 플러그인 35개를 일곱 분류로 하나씩 소개하고, 관리와 재설치 방법까지.
• 10 · 안전 모드와 복구 모드 — 플러그인 때문에 시작이 안 될 때 살리는 방법.
• 11 · 업데이트 — 다섯 단계와 재사용 가능한 네 가지 조작.
• 12 · 문제가 생겼을 때 — 흔한 증상 대조표와 진단 내보내기.
• 13 · 데이터와 도움말 — 파일 위치와 더 많은 문서로 가는 길.

1. 무엇인가

한 문장으로: DeepSeek Harness의 에이전트 기능을 데스크톱 앱에 담았습니다. 아이콘을 두 번 누르면 대화를 시작할 수 있고, 파일을 읽고 쓰며, 명령을 실행하고, 도구를 호출합니다.

제품은 세 계층으로 이루어져 있습니다. 여러분이 상대하는 것은 세 번째 계층뿐이고, 앞의 두 계층은 백그라운드에서 알아서 동작합니다.

이 버전(Essentials 판)과 소프트웨어 저장소의 범용 판에는 차이가 하나 더 있습니다: 껍데기만 얹어 두고 플러그인은 직접 설치하라고 비워 둔 앱이 아니라, 이미 골라 두고 서로 맞물리도록 구성한 플러그인 35개를 설치 패키지에 함께 담았습니다. 설치 후 처음 열면 이런 기능들이 플러그인 페이지에서 이미 기다리고 있고, npm에서 하나씩 찾을 필요가 없습니다.

2. 설치

제품 다운로드 페이지에서 해당 플랫폼의 설치 패키지를 받아 두 번 누르면 됩니다. 설치 패키지에 Electron, Node.js, pnpm과 고정 버전의 DSH 런타임이 이미 들어 있어서 다른 환경을 따로 설치할 필요가 없습니다. 이 버전에 포함된 것은 Electron 44.0.0, Node.js 24.21.0, pnpm 11.8.0, Python 3.12.14, 그리고 DSH 런타임 0.2.2-rc.1입니다.

업그레이드 설치에 이전 버전을 직접 끌 필요가 없습니다. 설치 프로그램이 먼저 실행 중인 이전 버전에 종료를 요청하고, 응답이 없으면 강제로 끝낸 뒤 파일을 덮어씁니다. 정말로 종료할 수 없으면 설치가 분명하게 오류를 내고 멈추며, 설치만 끝나고 앱이 열리지 않는 일은 없습니다. 그래도 업그레이드 전에 하던 작업을 저장해 두는 편이 좋습니다. 제거할 때도 실행 중인 프로그램을 먼저 확인해 닫으므로, 제거 도중 파일이 잠기는 일이 없습니다.

참고: 다운로드 페이지에서는 현재 Windows x64, macOS 유니버설 패키지, Linux x64 세 가지를 제공합니다. Linux arm64 산출물은 테스트 채널에서 빌드되며 아직 안정판 다운로드 링크에 들어가지 않았습니다. ARM 기기에서 네이티브 모듈 문제가 생기면 해당 플랫폼의 x64 버전이나 테스트 채널 산출물을 쓰세요.

3. 처음 실행

처음 시작하면 기본 설정 한 벌(desktop이라는 Profile)을 자동으로 준비하고, 이 PC에서 인터페이스 서비스를 띄웁니다. 먼저 마법사가 나오는데 모두 여섯 단계이고, 언제든 「설정 건너뛰기」를 눌렀다가 나중에 설정 페이지에서 채울 수 있습니다:

마지막 페이지에서는 먼저 대분류 개요를 보여 줍니다: 기억과 컨텍스트, 인터페이스와 작업 공간, 에이전트와 스킬, 문서와 미디어, 코드와 엔지니어링, 로봇과 시뮬레이션, 연결과 자동화. 각 분류마다 「이 분류가 무엇을 도와주는지」와 플러그인 개수를 적어 둡니다. 「완료하고 시작」을 누르면 그때부터 하나씩 설치하며, 각 플러그인 차례가 되면 이름, 버전, 소속 대분류, 전체 설명, 그리고 「○○님 덕분에 이 플러그인이 있습니다」라는 감사 문구를 보여 줍니다. 설치 중에는 조작할 필요가 없고 진행률이 끝날 때까지 기다리면 됩니다 — 패키지 35개를 하나씩 설치하므로 첫 실행은 평소보다 조금 더 걸립니다.

마법사가 끝나면 메인 화면으로 들어갑니다. 창을 닫는 것은 앱을 종료하는 것이 아닙니다. 기본 설정에서는 창만 트레이로 들어가고 백그라운드 서비스와 실행 중인 작업은 계속 돌아갑니다. 정말로 끝내려면 트레이 메뉴의 「종료」를 쓰세요.

4. 메인 화면 한눈에

사전 설치 플러그인을 설치한 뒤에는 사이드바와 입력창에 진입점이 더 생깁니다: 스킬 센터, 작업 보드, 비용 보드, 입력 기록, 전문가 팀 등. 모두 9절의 플러그인들이 제공하는 것이고, 해당 플러그인을 끄면 사라집니다.

5. 첫 대화 시작하기

1. 새 세션을 만들고 작업 디렉터리를 고릅니다.
2. 「무엇을 + 어디서 + 결과가 어떤 모습이어야 하는지」를 한 문장으로 말합니다. 예: 「이 디렉터리의 README를 읽고, 만료된 다운로드 링크를 찾아 표로 정리해 줘」.
3. 작업을 시작하면 도구 호출과 바뀌는 파일을 지켜봅니다. 방향을 바꾸고 싶으면 바로 중단하고 새 요구 사항을 말합니다.
4. 결과가 마음에 들지 않으면 무엇이 잘못됐는지 말합니다. 맥락을 그대로 들고 고치므로 세션을 새로 열 필요가 없습니다.

요구 사항을 명확하게 전달하는 세 가지 요점:

• 범위: 어느 디렉터리, 어느 파일만 고칠지. 마음대로 확장하지 않게 합니다.
• 완료 기준: 어떤 결과면 끝인지(실행이 되는지, 테스트가 통과하는지, 표에 빈 값이 없는지).
• 제약: 건드리면 안 되는 것, 반드시 유지할 형식, 네트워크를 써도 되는지 여부.

6. 트레이 메뉴

창을 닫은 뒤에는 트레이 아이콘이 앱의 총입구입니다. 트레이 아이콘을 마우스 오른쪽 버튼으로 누르면 다음이 보입니다:

이전 판 매뉴얼에 있던 「모드: 강화 / 호환 / 확장」은 없앴습니다. 2.2.9부터 창 모드는 고정이고, 설정에는 「창 모양(재질)」 항목만 남아 있습니다.

7. 설정 페이지

설정 진입점은 사이드바 아래쪽에 있습니다(설정 → 데스크톱 설정). 구역은 다음과 같습니다:

안전 모드에서는 이 페이지가 읽기 전용이고, 브라우저 접근, LAN, 원격 제어, 알림 같은 항목도 비활성화됩니다. 이는 설계된 동작이며 고장이 아닙니다.

8. Profile: 여러 설정

Profile은 독립된 설정 환경 한 벌입니다. 세션, 플러그인, 설정이 각각 따로 있고 서로 간섭하지 않습니다. 흔한 쓰임은 「업무」와 「개인」을 나누거나, 「일상」과 「새 플러그인 시험용」을 나누는 것입니다.

실용적인 세 가지 규칙:

• 한 Profile이 망가져도 다른 Profile로 바꿔 작업을 이어 갈 수 있습니다. 먼저 고칠 필요가 없습니다.
• 새로 만든 Profile에는 공식 기본 구성만 있고, 사전 설치된 플러그인 35개는 마법사를 완료한 그 벌에만 설치됩니다. Profile을 바꿔 계속 쓰려면 플러그인 페이지에서 실제 목록을 확인하고 빠진 것을 채우세요.
• Profile을 삭제하면 복구 백업 디렉터리로 옮겨집니다(즉시 지워지지는 않음). 공유 세션과 설정은 유지되지만, 해당 Profile 기준으로는 더 이상 쓸 수 없으니 실행 전에 확인하세요.

9. 사전 설치된 플러그인

이 절은 이번 판 매뉴얼의 핵심입니다. 2.2.9 설치 패키지에는 플러그인 35개가 함께 들어 있고, 일곱 대분류에 나뉘어 첫 마법사를 마칠 때 현재 Profile에 자동으로 설치됩니다. 아래에서는 먼저 「무엇이, 어떻게 설치되는지」를 설명하고, 이어서 분류별로 하나씩 소개한 뒤, 관리와 재설치 방법을 다룹니다.

9.1 출하 시 무엇이 사전 설치되는가

설치 패키지가 플러그인 35개의 압축 파일을 함께 배포하며(plugins/ 디렉터리), 첫 마법사가 끝날 때 하나씩 Profile에 설치합니다. 「선택 다운로드」가 아니라 설치하면 바로 있는 것입니다. 플러그인 페이지를 열면 「설치된 플러그인」에서 35개 전부를 볼 수 있고, 기본적으로 활성화 상태입니다.

9.2 사전 설치가 일어나는 방식

알아 두면 좋은 몇 가지 세부 사항:

• 설치는 하나씩 진행됩니다, 설치할 때마다 마법사에 이름, 버전, 대분류, 설명, 작성자가 표시됩니다. 전부 끝나기 전에 창을 닫지 마세요.
• 성공 판정은 Profile의 package.json 의존성에 이 패키지 이름이 나타나는지로 하며, 명령이 오류를 냈는지 여부가 아닙니다. 설치가 끝나면 이름을 profile.bundles에도 넣는데, 그렇지 않으면 「설치됐지만 활성화되지 않은」 상태가 됩니다.
• 플러그인 하나가 실패해도 시작을 막지 않습니다: 설치 후 실패가 있으면 이름과 이유를 하나씩 나열한 요약 대화 상자가 뜨고, 동시에 데스크톱 로그에 기록됩니다(bundled plugin not installed: <이름>: <이유>). 마법사는 평소대로 끝납니다. 나중에 플러그인 페이지에서 실제로 목록에 있는지 확인하세요.
• 마법사를 완료한 그 Profile 한 벌에만 설치됩니다. 이후 새로 만든 Profile은 깨끗한 상태이므로, 필요하면 마법사를 다시 돌리거나 플러그인 페이지에서 채우세요.

9.3 분류별 상세 목록

아래는 일곱 대분류로 나눈 플러그인 35개 전부입니다. 이름 뒤의 v는 함께 배포된 버전이고, 「적합한 용도」 한 줄은 선택을 돕기 위한 제안이며 기능 제한이 아닙니다.

9.4 비활성화, 제거, 다시 설치

• 먼저 비활성화, 그다음 제거: 비활성화는 다음 시작에 로드하지 않게 할 뿐이고 설치 파일과 설정은 그대로 남아 언제든 되살릴 수 있습니다. 제거는 dsh plugin remove로 패키지를 지우며, 인터페이스가 「제거하면 이 플러그인이 제공하는 기능이 사라집니다」라고 한 번 묻습니다.
• 사전 설치 플러그인을 제거해도 공간은 거의 줄지 않습니다: 설치 패키지 안의 원본 .tgz는 여전히 프로그램 디렉터리의 plugins/ 아래에 있고, 지워지는 것은 Profile 안의 설치 사본입니다. 정말로 용량을 줄이려면 하나씩 제거하는 것이 아니라 이 패키지들이 없는 설치 패키지로 바꿔야 합니다.
• 다시 설치: 설정 → 데스크톱 도구 → 「설정 마법사」에서 6페이지까지 다시 진행해 「완료하고 시작」을 누르면 Profile에 빠진 패키지를 채워 넣습니다. 9.5의 경로로 직접 설치해도 됩니다.
• 보호된 구성은 건드릴 수 없습니다: 플러그인 관리자 자체에 필요한 구성(Host, 웹 서비스, 파일 접근 등)에는 「플러그인 관리에 필요하므로 비활성화하거나 제거할 수 없습니다」라고 표시됩니다. dsh-base, dsh-web-app 같은 내장 기본 구성은 관리 목록에 아예 들어오지 않고, 「설정 → 내장 플러그인」에서만 상태를 볼 수 있습니다.

9.5 직접 플러그인 설치: 세 가지 경로

플러그인 페이지(왼쪽 「플러그인」, 부제는 「플러그인 설치, 활성화 및 구성」)는 두 가지 일을 합니다:

• 새 플러그인 설치: 「플러그인 추가」를 누르고 「서드파티 플러그인 설치」를 골라 npm 패키지 이름(예: dsh-xxx 또는 @작성자/플러그인 이름), GitHub 저장소 주소, 또는 이 PC의 디렉터리를 입력합니다. 설치할 때 설치 소스를 고를 수 있습니다: 기본 설치 소스, 공식 소스, 중국 본토 미러 소스, 또는 직접 지정한 사내 npm 소스.
• 설치된 것 관리: 「설치된 플러그인」에서 활성화, 비활성화, 제거, 업데이트 확인을 하고, 각 플러그인의 버전, 출처, 실행 상태를 볼 수 있습니다.

플러그인 마켓은 두 가지 중에서 고를 수 있습니다: dsh-community-market(내장 개방형 마켓, 사용자 지정 데이터 소스 지원, Beta)와 dsh-market(커뮤니티 인기 마켓, 데이터는 awesome-dsh-plugin에서 오며 번들 플러그인 이름은 dshmarket). 둘은 한 번에 하나만 활성화할 수 있습니다. 마켓 자체가 플러그인이므로 플러그인 페이지에서 바로 켜고 끌 수도 있습니다.

터미널의 세 가지 명령(--profile을 붙이지 않으면 현재 활성화된 Profile에 적용):

9.6 설치 후에는 재시작, 설치 후에는 확인

플러그인을 설치한 뒤 앱을 재시작해야 로드됩니다. 설치가 끝나면 인터페이스에 「설치되었습니다. DSH를 다시 시작하여 로드하세요.」라고 안내가 나옵니다. 제대로 설치됐는지 확인하려면:

1. 플러그인 페이지를 열어 「설치된 플러그인」에 있는지, 활성화 상태인지 봅니다.
2. 사이드바에 그 진입점(마켓, 보드, 전문가 팀, 비용 같은 페이지)이 생겼는지 봅니다.
3. 그래도 확실하지 않으면 「설정 → 로그」를 열고 로그 수준을 높인 뒤 한 번 재시작합니다. 로드 실패는 보통 분명한 오류로 남습니다.

9.7 플러그인 때문에 앱이 망가졌다면

운영 체제를 다시 설치할 필요도, 데이터 디렉터리를 지울 필요도 없습니다. 10절의 복구 도우미로 갑니다. 먼저 「플러그인 관리」에서 최근에 설치한 것을 사용 안 함으로 바꾸고 시작하고, 그래도 안 되면 「롤백」으로 직전의 정상 시작 체크포인트로 되돌립니다. 사전 설치 플러그인도 마찬가지입니다. 나중에 설치한 것과 다르지 않습니다.

10. 안전 모드와 복구 모드

두 기능은 같은 종류의 문제를 풉니다. 무엇인가를 설치한 뒤 시작이 안 되는 상황입니다. 차이는 안전 모드는 「깨끗한 환경으로 들어가 작업하는 것」, 복구 모드는 「문 밖에 서서 고치는 것」이라는 점입니다.

10.1 안전 모드

안전 모드는 별도의 임시 데이터 디렉터리로 시작합니다. 기존 플러그인, 설정, 세션, 작업 공간 기록을 읽지 않으므로 그것들 때문에 무너지지도 않습니다. 원래 데이터는 한 바이트도 건드리지 않습니다.

들어가는 방법: 트레이 → 「안전 모드 진입…」, 또는 복구 도우미 첫 화면에서 「안전 모드」를 누릅니다.

안전 모드에서 할 수 있는 일:

• 「정말 플러그인 문제인지」 확인하기 — 안전 모드에서 모두 정상이라면 문제는 플러그인이나 설정에 있습니다.
• 웹 인터페이스로 평소처럼 대화하고 파일을 읽고 쓰기. 급한 일을 먼저 처리할 수 있습니다.
• 로그 확인, 진단 정보 내보내기(진단 패키지는 복구 도우미에서도 내보낼 수 있습니다).

제한(설계된 동작):

• 데스크톱 설정 페이지가 읽기 전용으로 고정되어 바꿀 수 없습니다.
• 브라우저 접근, LAN 접근, 원격 제어, 데스크톱 알림처럼 영구 설정에 의존하는 항목은 쓸 수 없습니다.
• 화면 위쪽에 「안전 모드」 표시줄이 계속 떠서, 지금 임시 환경에서 실행 중임을 알려 줍니다.

나가기: 트레이 → 「안전 모드 종료 후 재시작…」. 나간 뒤 임시 환경은 다음 정상 시작 때 자동으로 정리되고, 디스크에 남아 자리를 차지하지 않습니다.

10.2 복구 도우미(복구 모드)

언제 들어오게 되는가:

• 트레이에서 「복구 도우미…」를 직접 고를 때.
• 시작이 연속으로 실패해 앱이 스스로 복구 도우미로 물러날 때.
• 인터페이스가 도저히 뜨지 않을 때는 「DSH Desktop 복구」 대화 상자가 따로 뜨고, 백그라운드 서비스를 재시작하지 않고 복구를 한 번 더 시도할 수 있습니다.

복구 도우미는 세 가지를 알려 줍니다: 왜 들어왔는지(직접 들어오면 「수동으로 복구 모드에 진입했습니다」라고 적힘), 지금 어느 Profile과 어느 디렉터리를 쓰는지, 시작이 어느 단계에서 멈췄는지(Electron 초기화 → 셸 환경 준비 → 데스크톱 런타임 준비 → Profile 선택 → 플러그인 구성 조합 → 플러그인 서비스 시작 → 데스크톱 인터페이스 시작 → 시작 결과 확인). 어디서 막혔는지 알면 문제 범위도 그만큼 좁혀집니다.

롤백은 어떻게 동작하는가: 시작에 성공할 때마다 앱은 「시작 체크포인트」를 하나 남깁니다. 그 순간 정상 동작하던 설정을 기록해 두는 것입니다. 롤백은 Profile, settings.yaml, 플러그인 활성화 상태를 그 시점으로 함께 되돌립니다. 체크포인트는 「복원 가능 / 읽을 수 없음 / 체크포인트 없음」 세 상태로 표시되고, 「읽을 수 없음」은 그 체크포인트 자체가 손상됐다는 뜻이므로 더 이른 것을 고르세요.

공장 초기화: 현재 데이터 디렉터리를 통째로 휴지통(Windows에서는 재활용 통)으로 옮기고, 재시작 후 기본 Profile을 새로 만듭니다. 데이터 디렉터리 밖의 프로젝트 파일은 지우지 않습니다. 앱은 자기 설정과 세션만 정리합니다. 실행 전에 이전 세션이 정말 필요 없는지 확인하세요.

10.3 나가는 길

고친 뒤에 따로 정리할 것은 없습니다. 복구 도우미를 정상적으로 닫고 앱을 시작하면 됩니다. 복구 모드에서 「재시작」을 누른 경우 앱이 정상 시작 절차를 다시 밟고, 또 실패하면 복구 도우미로 돌아옵니다. 끝없이 반복되지는 않습니다.

11. 업데이트

다섯 단계: 확인 → 다운로드 → 설치 → 재시작 → 버전 확인. 재사용 가능한 네 가지 조작:

• 직접 확인: 트레이 → 「업데이트 확인…」, 또는 설정 → 버전 및 업데이트 → 「업데이트 확인」.
• 재시작: 설정 → 버전 및 업데이트 → 「재시작」. 제목 표시줄에 업데이트 알림이 있으면 거기서 바로 눌러도 됩니다.
• 설치 잔여물 정리: 업데이트 실패는 보통 이전 인스턴스가 파일을 잡고 있어서 생깁니다. 트레이에서 앱을 종료한 뒤 설치 패키지를 다시 실행하면 되고, 디렉터리를 직접 지울 필요는 없습니다.
• 되돌리기: 직전의 정상 시작 상태로만 돌아가려면 복구 도우미의 「롤백」. 안정 채널의 설치 패키지로 바꾸려면 다운로드 페이지에서 해당 버전을 받아 덮어쓰기 설치하면 되고, Profile과 플러그인은 모두 유지됩니다.

12. 문제가 생겼을 때

진단 정보 내보내기

트레이 → 「진단 정보 내보내기…」, 또는 설정 페이지 아래쪽의 같은 항목. 내보낸 패키지에는 로컬 경로, 로그, 시스템 정보, 크래시 시점의 메모리 조각이 들어 있습니다. 공유하기 전에 직접 한 번 읽어 보세요. 경로와 세션 조각에 사적인 내용이 들어 있을 수 있습니다.

13. 데이터는 어디에, 도움은 어디서

더 많은 문서

• README.md / README.zh.md: 설치, 빌드, 개발 환경.
• docs/: 아키텍처 설명, 릴리스 절차, 플러그인 개발 가이드.
• 같은 디렉터리의 Nonead-DSH-Desktop-User-Manual.en.md와 여덟 언어 HTML 판: 내용이 대응되어 대조하기 좋습니다.
• CHANGELOG.md: 버전별 변경 사항. 2.2.9 항목 아래에 이 책과 같은 「내장 플러그인 목록(35개)」이 있습니다.

감사의 글

이 제품은 업스트림 DeepSeek Harness와 오픈 소스 커뮤니티 위에 서 있습니다: Electron, Node.js, pnpm, Python, 그리고 Cordis 플러그인 체계와 공식 bundle 생태계. 업스트림 유지 관리자와 모든 기여자에게 감사드립니다.

함께 배포되는 플러그인 35개는 다음 작성자와 팀이 만들었습니다(이름순, 같은 작성자가 여러 개를 기여한 경우도 있습니다):

각 플러그인의 구체적인 버전, 작성자, 전체 설명은 함께 배포되는 plugins/manifest.json에 있고, 플러그인 페이지의 상세에서도 볼 수 있습니다.

매뉴얼은 버전에 따라 갱신됩니다. 현재 버전과 다른 부분을 발견하면 GitHub / GitCode로 이슈를 남겨 주세요.