DeepSeek Harness(dsh) 뜯어보기 — 플러그인 아키텍처와 Python SDK 설정 정리

mini_knows·2026년 8월 22일

AI트렌드 Claude Code 대안 DeepSeek Harness DeepSeek V4-Pro 가격 dsh 오픈소스 코딩 에이전트

AI 트렌드·이슈

목록 보기

80/120

안녕하세요, 미니지식공간입니다.

DeepSeek Harness(딥시크 하네스, 명령어 dsh)는 2026년 8월 13일 개발자 프리뷰로 공개된 MIT 라이선스 에이전트 하네스다. 하네스(harness)는 모델이 도구를 호출하고 파일을 고치며 작업을 이어가게 만드는 실행 계층을 뜻하는데, 이 글은 그 계층을 어떻게 구성하고 갈아끼우는지를 공식 문서 기준으로 정리한다.

세 줄 요약

dsh는 Cordis 플러그인 커널 위에 올라가 있어 모델·도구·세션·샌드박스·저장소·루프·UI가 전부 교체 가능한 플러그인이다.

모델 라우트는 Web UI 또는 $DSH_HOME/settings.yaml로 붙이며, OpenAI 호환 게이트웨이용 compat 스위치가 따로 있다.

Python SDK(deepseek-harness-sdk)로 Web UI 없이 세션을 프로그래밍 방식으로 돌릴 수 있다. 단, 예제 구성은 danger-full-access다.

1. 릴리스 개요

항목	값
공개일	2026-08-13 (developer preview v0.1)
라이선스	MIT
커널	Cordis 플러그인 메타 프레임워크
인터페이스	로컬 Web UI / 헤드리스 CLI / Python SDK
기본 Web UI	`http://127.0.0.1:3080`
실행 모드	Standard, Code, Minimal, Creator
안정성	저장소 표기 "THERE WILL BE COMPATIBILITY-BREAKING CHANGES"

저장소가 스스로 개발자 프리뷰임을 밝히고 호환성을 깨는 변경을 예고한 상태다. 프로덕션 파이프라인에 바로 넣기보다 실험 환경에서 먼저 다뤄야 한다.

2. 먼저 띄워보기

출처: README#run

# npm 실행 (Node.js 필요)
npx @deepseek-ai/dsh web

# 소스에서 실행
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

dsh web은 기본값으로 http://127.0.0.1:3080에 Web UI를 띄우고 기본 브라우저를 연다. SSH로 붙어 실행하면 주소만 출력되며, 브라우저를 띄우지 않으려면 --no-open을 붙인다. dsh 프로세스는 자신이 실행된 디렉터리를 기본 파일시스템 위치로 잡지만, Web UI에서 워크스페이스를 고르기 전까지 세션 입력창은 열리지 않는다.

3. "모든 것이 플러그인"이 실제로 뜻하는 것

Cordis 커널이 하는 일은 플러그인의 장착·해제·의존성 관리뿐이다. 에이전트 기능은 전부 플러그인 쪽에 들어가고, 플러그인끼리는 Cordis의 서비스와 이벤트로 붙는다. 그래서 모델·도구·스킬·세션·샌드박스·저장소·루프·스케줄링·UI 중 무엇을 바꾸든 하네스 본체 소스를 수정할 필요가 없다는 것이 DeepSeek의 설명이다.

추적성도 같은 축에 있다. 모델이 본 모든 것 — 시스템 프롬프트, 추론, 도구 호출과 결과, 서브에이전트 스케줄링, 컨텍스트 주입 — 이 추가 전용(append-only) 세션 로그에 남는다. Trajectory 화면에서 출처별로 열어볼 수 있고, 이어 하기·분기·검색·재생이 전부 같은 이벤트 스트림 위에서 동작한다.

실행 모드는 넷이다. Standard는 파일 편집·셸·파일/웹 검색·스킬·계획·목표·서브에이전트·워크플로를 갖춘 완전한 코딩 에이전트다. Code 모드는 같은 기능을 Code Mode SDK로 노출해 모델이 여러 단계 작업을 하나의 TypeScript 프로그램으로 묶게 한다. Minimal 모드는 지속 bash와 str_replace_editor 두 개만 남긴 벤치마크용 최소 환경이고, Creator 모드는 런타임을 들여다보며 플러그인을 메모리에서 실험해 새 프리셋을 만드는 용도다. 일부 집계 블로그가 두 번째 모드를 "PTC(Programmatic Tool Calling)"로 적는데, 공식 페이지 표기는 Code 모드다.

4. 모델 라우트 설정

출처: Configure models

기본 경로는 Web UI의 Settings → Models다. DeepSeek 카드에 API 키를 넣으면 서버 재시작 없이 다음 요청부터 적용된다. 키는 쓰기 전용으로 취급돼 $DSH_HOME/.credentials.yaml에 저장되고, 화면에는 가려진 식별자만 돌아온다. Anthropic·OpenAI는 Add provider로, 사내 게이트웨이나 자체 서버는 Add a custom provider로 붙인다. Bedrock·Vertex·Azure·Codex는 API 키 한 칸으로는 설정되지 않고 각각 AWS 자격증명과 리전, ADC 프로젝트, api-version, OAuth가 필요하다.

폼에 없는 항목은 $DSH_HOME/settings.yaml에 직접 쓴다. 비전 모델은 손으로 입력하면 텍스트 전용으로 간주되므로 input을 명시해야 한다.

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat
        - id: vision-preview
          input: [text, image]

게이트웨이가 키와 주소 모두 정상인데 모든 요청을 거절한다면 요청 형태가 원인일 가능성이 크다. 문서에 따르면 추론 모델은 시스템 프롬프트가 role: "developer"로 나가고 출력 상한이 max_completion_tokens로 나가는데, 이를 모르는 서버가 많다. 두 스위치를 라우트에 걸어 교정한다.

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      compat:
        supportsDeveloperRole: false
        maxTokensField: max_tokens
      models:
        - id: my-model

라우트의 compat은 소속 모델의 기본값이고 모델 자신의 값이 필드 단위로 이긴다. 값 없이 키만 적으면(supportsDeveloperRole:) 무시가 아니라 거절이다. 자주 만나는 오류 코드는 MISSING_CREDENTIAL(키 미등록)과 UNKNOWN_MODEL(미등록 모델 선택)이며, 모델 목록 조회가 401이면 OpenAI 호환 GET /models 호출이 실패한 것이므로 모델을 수동 입력해야 한다.

5. Python SDK로 세션 돌리기

출처: Get started with the Python SDK

전제 조건은 Python 3.10 이상, Git, Linux x64/arm64 또는 arm64 macOS 14 이상, DeepSeek 호환 엔드포인트와 자격증명, 그리고 에이전트가 마음대로 고쳐도 되는 격리 워크스페이스다.

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
python -m venv .venv
. .venv/bin/activate
python -m pip install deepseek-harness-sdk

export DEEPSEEK_API_KEY=sk-your-key-here
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
# export DSH_MODEL=deepseek-v4-flash
# export DSH_SYSTEM_PROMPT='You are a helpful software engineer assistant.'

설치된 런타임은 시스템 Node.js를 요구하지 않는다. 체크인된 예제는 아래 SDK 호출의 얇은 래퍼다.

from pathlib import Path

from deepseek_harness import DeepSeekHarness

config = Path("examples/jsonrpc-agent/minimal.cordis.yml").resolve()
workspace = Path("/absolute/path/to/workspace").resolve()
sessions = Path("/absolute/path/to/sessions").resolve()

with DeepSeekHarness(
    provider="deepseek-official",
    model="deepseek-v4-flash",
    max_tokens=49_152,
    cwd=str(workspace),
    session_root=str(sessions),
    cordis=str(config),
) as harness:
    result = harness.run(
        "Inspect the repository and fix the failing tests.",
        session_id="example-001",
    )

print(result.final_response)

DeepSeekHarness는 번들 런타임을 지연 기동하고 컨텍스트 매니저가 끝날 때까지 재사용한다. 같은 하네스와 같은 session_id를 재사용하면 세션이 소유한 Bash 프로세스가 유지되므로 작업 디렉터리, export한 변수, 셸 함수가 그대로 남는다. 독립 작업이면 새 세션 id를 쓰고, 같은 대화를 이어갈 때만 id를 재사용하는 것이 문서 권고다.

6. minimal 구성의 실제 값

예제 구성이 무엇을 켜고 껐는지는 그대로 표로 정리돼 있다. 벤치마크 재현이나 하네스 오버헤드 측정에 쓸 때 이 값들을 그대로 맞춰야 비교가 성립한다.

속성	값
모델 결정 순서	`--model` → `DSH_MODEL` → `deepseek-v4-flash`
모델이 보는 도구	지속 `bash`, `str_replace_editor` 뿐
Bash 타임아웃	300초
편집기 출력 상한	16,000자
컨텍스트 압축	비활성
세션 저장	`DSH_SESSION_ROOT` 아래 비압축 JSONL
파일시스템	베어 로컬 백엔드, 절대 경로는 런타임이 보는 모든 경로 지정 가능

경고가 하나 붙어 있다. 이 구성은 danger-full-access를 쓰므로 일회용 체크아웃이나 컨테이너 안에서만 돌려야 한다. Bash와 편집기가 런타임 프로세스에 허용된 어떤 경로든 수정할 수 있기 때문이다. 또 지속 PTY 백엔드가 POSIX 터미널을 요구해 이 구성은 Windows 에이전트를 지원하지 않는다.

7. 벤치마크를 읽을 때

같은 날 정식 출시된 DeepSeek-V4-Pro-0813의 자사 발표 점수는 Terminal Bench 2.1 87.9, Toolathlon-Verified 74.1, DSBench-FullStack 71.1, DSBench-Hard 67.2다. 전 항목 1위는 아니며, 같은 표에서 Claude Fable 5가 Toolathlon-Verified 77.9, DSBench-FullStack 77.2로 앞선다. 결정적으로 공개 코드 에이전트 과제는 DeepSeek Harness의 minimal 모드에서 측정했다고 명시돼 있다. 즉 이 숫자들은 모델 단독 점수가 아니라 특정 하네스 구성과의 조합 결과다.

가격도 같이 움직였다. DeepSeek은 2026-08-16 16:00 UTC부터 피크/오프피크 차등 요금제로 전환했고, VentureBeat 정리 기준 deepseek-v4-pro는 100만 토큰당 기존 $0.435/$0.87에서 오프피크 $0.66/$1.98, 피크 $1.32/$3.96로 올랐다. 캐시 히트는 $0.003625에서 오프피크 $0.022, 피크 $0.044다. Reuters는 인상 폭이 50%에서 1,100% 이상까지 벌어진다고 보도했다.

8. 도입 전 체크리스트

프리뷰 전제로 버전을 고정한다. 호환성 파괴가 예고돼 있으므로 커밋 해시나 npm 버전을 박아둔다.
워크스페이스를 컨테이너로 격리한다. 예제 구성이 danger-full-access라는 점을 잊지 않는다.
모델 라우트를 먼저 결정한다. 사내 게이트웨이라면 compat.supportsDeveloperRole과 compat.maxTokensField부터 확인한다.
세션 로그 보존 정책을 정한다. JSONL에 프롬프트·도구 결과가 그대로 남는다.
비용 모델을 다시 계산한다. DeepSeek API를 쓸 경우 호출 시간대가 단가에 직접 반영된다.

자주 묻는 질문

Q. dsh로 Claude Code를 대체할 수 있나?
저장소 읽기·편집, 셸 실행, 검색, 계획, 서브에이전트, 승인 정책 같은 핵심 루프는 이미 있다. 다만 호스팅형 백그라운드 에이전트와 GitHub 네이티브 PR 워크플로는 DeepSeek 문서에 완성 기능으로 기술돼 있지 않다고 VentureBeat가 정리했다. 개발자 프리뷰 단계라는 점까지 감안하면 현재는 부분 대체로 보는 편이 정확하다.

Q. DeepSeek 모델을 꼭 써야 하나?
아니다. 모델도 플러그인이라 Anthropic·OpenAI 카탈로그 제공사나 OpenAI 호환 커스텀 엔드포인트를 붙일 수 있다. 다만 DeepSeek 자체 chat-completions 라우트는 텍스트 전용이며 이미지 입력을 설정으로 켤 수 없다고 문서가 명시한다.

Q. Windows에서 돌아가나?
Python SDK 문서 기준 예제 구성은 지속 PTY 백엔드가 POSIX 터미널을 요구해 Windows 에이전트를 지원하지 않는다. 전제 조건에도 Linux x64/arm64와 arm64 macOS 14 이상만 적혀 있다. WSL이나 리눅스 컨테이너를 쓰는 편이 안전하다.

마무리

모델이 표준 인터페이스 뒤로 물러나면서, 경쟁의 무게추가 그 바깥의 실행 계층으로 옮겨가고 있습니다. 같은 흐름의 다른 사례로는 Claude Code 셀프호스팅 환경 정리와 DeepSeek V4-Flash-0731 벤치마크·API 정리를 함께 보시면 도움이 될 것 같습니다. 읽어주셔서 감사합니다.