이 책의 안내

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

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

1. 무엇인가

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

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

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 ARM64는 현재 실험적 빌드입니다. 본체는 ARM64 네이티브지만 패키지 안의 일부 페이로드(내장 Python / Node / Office 런타임, 일부 네이티브 모듈)는 여전히 x64라서 ARM 기기에서 완전한 검증을 마치지 않았습니다. 일반 사용자는 x64 버전을 권장합니다.

3. 처음 실행

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

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

4. 메인 화면 한눈에

5. 첫 대화 시작하기

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

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

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

6. 트레이 메뉴

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

7. 설정 페이지

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

8. Profile: 여러 설정

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

실용적인 세 가지 규칙:

• 한 Profile이 망가져도 다른 Profile로 바꿔 작업을 이어 갈 수 있습니다. 먼저 고칠 필요가 없습니다.
• 새 Profile은 비어 있습니다(공식 기본 구성만 있음). 플러그인을 다시 설치해야 하는데, 바로 그 점이 깨끗한 이유입니다.
• Profile을 삭제하면 로컬 설정과 플러그인 파일도 함께 지워지고 되돌릴 수 없습니다.

9. 플러그인: 출하 상태와 설치 방법

9.1 출하 시 포함된 것

설치 패키지에는 서드파티 플러그인이 하나도 들어 있지 않습니다. 처음 시작할 때 만들어지는 기본 Profile은 공식 기본 구성 두 개만 로드합니다:

• @deepseek-ai/dsh-base — Host 커널: 세션, 도구, 파일 접근, 모델 연결.
• @deepseek-ai/dsh-web-app — 여러분이 보는 웹 인터페이스.

즉, 막 설치했을 때 얻는 것은 깨끗하고, 대화가 되고, 파일을 읽고 쓰고, 명령을 실행할 수 있는 데스크톱 앱입니다. 플러그인 마켓, 전문가 팀, 음성 입력, 작업 보드, 코드 그래프 등은 모두 직접 설치해야 합니다. 이는 의도된 설계입니다. 무엇을 설치할지는 여러분이 정하고, 문제가 생기면 「최근에 설치한 그것」으로 범위를 좁히기 쉽습니다.

9.2 세 가지 설치 경로

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

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

일부 플러그인은 DSH와 함께 제공됩니다. 이런 항목에는 「플러그인은 DSH와 함께 제공됩니다 · 다운로드할 필요 없이 활성화하면 바로 사용할 수 있습니다」라고 표시되고, 활성화를 누르면 바로 적용됩니다. 현재 DSH 버전보다 오래된 경우에는 「업데이트」가 나타납니다. 여기에 해당하는 것은 전문가 팀, 음성 입력, 플러그인 마켓, 자동 검토, 터미널, 세션 검색, 세션 제목, 배지 스킬, Ralph, 사고 과정 번역, Inspector, LiveShare, Forge, 워크트리 도구, 개인화 추천 등입니다. 부피나 의존성이 커서 기본으로 설치되지 않는 것(Claude Code 서브에이전트, Codex 서브에이전트, Computer Use 데스크톱 제어)도 플러그인 페이지에서 필요할 때 활성화합니다.

DSH에 내장된 기본 구성(dsh-base, dsh-web-app 같은 것)은 플러그인 페이지의 관리 가능한 목록에 나타나지 않습니다. 이들의 실행 상태는 설정 → 「내장 플러그인」에서 확인합니다.

플러그인 마켓은 현재 두 가지 중에서 고를 수 있습니다: dsh-community-market(내장 개방형 마켓, 사용자 지정 데이터 소스 지원)와 dsh-market(커뮤니티 인기 마켓, 데이터는 awesome-dsh-plugin에서 옴). 둘은 한 번에 하나만 활성화할 수 있습니다.

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

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

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

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

9.4 비활성화와 제거

• 먼저 비활성화, 그다음 제거: 비활성화는 다음 시작에 로드하지 않게 할 뿐이고 설치 파일과 설정은 그대로 남아 언제든 되살릴 수 있습니다. 제거는 dsh plugin remove로 패키지를 지우며, 인터페이스가 「제거하면 이 플러그인이 제공하는 기능이 사라집니다」라고 한 번 묻습니다. 복구 도우미에서는 비활성화를 「사용 안 함」이라고 부르는데 같은 동작입니다.
• 플러그인 관리자 자체에 필요한 구성(Host, 웹 서비스, 파일 접근 등)에는 「플러그인 관리에 필요하므로 비활성화하거나 제거할 수 없습니다」라고 표시됩니다. 앱을 못 쓰게 만드는 일을 막기 위해서입니다. dsh-base, dsh-web-app 같은 내장 기본 구성은 관리 목록에 아예 들어오지 않고, 「설정 → 내장 플러그인」에서만 상태를 볼 수 있습니다.
• 이전 버전에서 올라온 Profile은 설정에서 한 번 직접 고르기 전까지 플러그인 마켓이 기본으로 꺼져 있습니다. 고장이 아닙니다.

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

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

10. 안전 모드와 복구 모드

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

10.1 안전 모드

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

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

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

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

제한(설계된 동작):

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

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

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

언제 들어오게 되는가:

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

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

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

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

10.3 나가는 길

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

11. 업데이트

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

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

12. 문제가 생겼을 때

진단 정보 내보내기

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

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

더 많은 문서

• README.md / README.zh.md: 설치, 빌드, 개발 환경.
• docs/: 아키텍처 설명, 릴리스 절차, 플러그인 개발 가이드.
• 같은 디렉터리의 Nonead-DSH-Desktop-User-Manual.en.md와 여덟 언어 HTML 판: 내용이 대응되어 대조하기 좋습니다.

감사의 글

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

서드파티 플러그인의 작성자 정보는 각 플러그인과 함께 배포되며, 플러그인 페이지나 플러그인 마켓의 상세에서 볼 수 있습니다. 이 매뉴얼은 구체적인 버전과 작성자를 더 이상 하나씩 나열하지 않습니다. 그것은 여러분의 설치 선택에 속하고, 제품의 출하 상태가 아니기 때문입니다.

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