DeepSeek Harness란 무엇인가? 모든 것이 플러그인인 에이전트 런타임

DeepSeek Harness란 무엇인가?

DeepSeek Harness(약칭 dsh)는 MIT 라이선스 아래 DeepSeek AI에서 제공하는 오픈 소스 에이전트 하니스 입니다. 이는 언어 모델과 외부 세계 사이에 놓여 도구, 세션, 샌드박싱, 그리고 작업을 지속시키는 루프를 제공합니다.

DeepSeek의 정의는 "Agent = Model + Harness"입니다. 모델은 추론과 생성을 담당하고, 하니스는 그 추론이 실제 파일 시스템에 작용하고, 매번 작업을 다시 설명하지 않아도 계속 진행되도록 하는 모든 것을 담당합니다.

이는 DeepSeek Harness보다 먼저 존재한 플러그인 프레임워크인 Cordis 위에서 동작합니다. Cordis는 설정을 통해 이러한 부분들을 독립적으로 교체할 수 있게 합니다. 그 선택의 비용은 뒤에서 다시 다루겠습니다.

이 관점을 바탕으로, 흔한 오해 두 가지를 먼저 짚겠습니다.

DeepSeek Harness는 AI 모델이 아닙니다

앞서 말했듯 모델과 런타임은 분리된 레이어입니다. 이 분리는 도구나 세션 설정을 바꾸지 않고도 제공자를 교체할 수 있게 해 줍니다. 동일한 런타임이 DeepSeek, Anthropic, OpenAI 또는 OpenAI 호환 엔드포인트를 사용할 수 있습니다.

DeepSeek Harness는 코딩 어시스턴트 그 이상입니다

Standard 모드는 코딩 어시스턴트 같은 인상을 주지만, 이는 여러 설정 중 하나일 뿐입니다. 뒤에서 다루겠지만 Minimal과 Creator 모드는 에이전트가 사용할 수 있는 것을 바꿉니다. 새로운 설정을 만드는 데에는 여전히 엔지니어링 작업이 필요하며, 개발자는 그 부품들에 접근할 수 있습니다.

Cordis가 DeepSeek Harness 플러그인을 구성하는 방식

앞서 언급했듯 Cordis는 DeepSeek Harness의 기반이 되는 플러그인 프레임워크입니다. 각 부분이 단일 제공자의 코드에 묶이지 않고 필요한 서비스를 요청할 수 있게 합니다.

Cordis는 Koishi 챗봇 생태계에서 나왔고 Shigma로 알려진 개발자가 만들었습니다. DeepSeek는 이를 공급하고 확장합니다. 설계는 A Programming Paradigm for Spatiotemporal Composability라는 논문에서 설명합니다.

이 기본 개념은 프로젝트의 주요 슬로건과 두 가지 Cordis 용어로 이어집니다. 이름은 학술적으로 들리지만 동작은 비교적 단순합니다.

"모든 것은 플러그인이다"

DeepSeek의 아키텍처 문서에 따르면 dsh는 플러그인을 다른 것들과 나란히 마운트하는 방식으로 확장합니다. 모델 어댑터, 도구, 세션, 샌드박스, 스토리지, 스케줄링, 에이전트 루프, UI가 모두 플러그인입니다.

문구를 문자 그대로 적용하면 과장됩니다. 플러그인 아래에는 여전히 Cordis가 있습니다. Cordis는 플러그인을 로드·제거하고, 필요한 것을 점검하며, 서로 통신하는 데 쓰이는 이벤트를 실행합니다. Cordis는 필수이며, 선택 가능한 또 하나의 조각이 아닙니다.

공간적 합성은 플러그인 의존성을 관리합니다

플러그인은 수동 부트 시퀀스 없이 필요한 서비스를 선언합니다. 필요한 서비스가 존재하면 활성화되고, 필수 서비스가 사라지면 비활성화됩니다. 의존성이 실행 시점을 결정합니다.

공간적 합성이라는 용어로 DeepSeek는 이를 설명합니다. 의존성이 한 구성요소가 어디에 들어맞는지 Cordis에 알려 주므로, 개발자가 시작 순서를 일일이 정하지 않아도 됩니다.

시간적 합성은 플러그인 효과를 되감습니다

Cordis는 이벤트 리스너, 프롬프트 섹션, 도구 스키마 같은 등록도 추적합니다. 플러그인을 제거하면 고아 리스너를 남기지 않고 그 효과가 제거됩니다. 다만 셸 명령 같은 외부 동작은 되돌리지 않습니다. 가역성은 Cordis가 추적하는 효과에만 적용됩니다.

DeepSeek Harness 아키텍처: 런타임의 결합 방식

실행 인스턴스는 정해진 순서로 로드된 설정에서 구성된 플러그인 트리입니다. 어떤 부분이 활성화되는지는 설정에 달려 있습니다.

Cordis는 교체 가능한 모든 런타임 플러그인을 연결합니다. 이미지: 필자 제작.

Cordis 서비스는 플러그인이 서로를 찾게 합니다

Cordis는 공유 서비스 디렉터리를 제공합니다. 플러그인은 ctx.tools, ctx.llm, ctx.sessions 같은 안정적인 키를 사용하고, 특정 제공자의 코드를 임포트하지 않습니다. ctx.llm을 호출하는 도구는 뒤에 어떤 모델 어댑터가 있는지 알 필요가 없습니다.

에이전트 프리셋과 런타임 프로파일은 서로 다른 레이어를 제어합니다

모든 것이 교체 가능하더라도, 실행 시 무엇을 마운트할지는 결정되어야 합니다. DeepSeek Harness는 혼동하기 쉬운 두 레이어에서 그 답을 제시합니다.

요약하면: 프로파일은 프로그램의 시작 방식을 제어하고, 프리셋은 에이전트가 할 수 있는 일을 제어합니다. 웹 앱만 쓴다면 다음 두 하위 섹션은 건너뛰셔도 됩니다.

런타임 프로파일

런타임 프로파일(web, headless, sdk, sdk-minimal, acp 템플릿 제공)은 애플리케이션의 시작 방식과 부팅 시 어떤 Cordis 플러그인 묶음을 쌓을지를 결정합니다. 대부분의 독자는 dsh web 같은 명령을 실행하는 것 외에 이 레이어를 건드릴 일이 없습니다.

에이전트 프리셋

에이전트 프리셋(Standard, PTC, Minimal, Creator)은 활성 세션이 사용할 수 있는 것을 결정합니다. 패치 파일로 Harness 소스를 수정하지 않고도 프리셋을 바꿀 수 있습니다.

에이전트 루프는 턴, 스텝, 도구 호출을 조율합니다

DeepSeek는 스텝과 턴을 구분합니다. 스텝은 하나의 모델 요청과 그에 따른 도구 호출 묶음입니다. 턴은 0개 이상의 스텝으로, 첫 입력이 접수되면 열리고 아무 것도 남지 않으면 닫힙니다. 대부분의 턴은 에이전트가 답하기 전 여러 스텝을 실행하지만, 거부된 입력은 스텝을 소모하지 않은 채 턴을 닫습니다.

하나의 턴에는 여러 스텝이 포함될 수 있습니다. 이미지: 필자 제작.

세션은 추가 전용 이벤트 로그를 사용합니다

제가 가장 중요하다고 보는 부분입니다. 세션은 채팅 메시지 배열이 아니라 타입이 지정된 이벤트의 추가 전용 로그입니다. Harness는 그 로그에서 모델의 히스토리를 구성하며, 세션 문서는 모델에 전송되는 모든 것이 그 로그에서 복원 가능해야 한다고 요구합니다.

재개, 분기, 검색, 재생, Trajectory 보기는 모두 이 이벤트 스트림 위에 구축됩니다.

히스토리를 다시 도출하는 것은 결정론적 재실행이 아닙니다. 모델 출력과 외부 상태는 달라질 수 있지만, 로그는 무슨 일이 일어났는지 점검 가능한 기록을 제공합니다.

세션 히스토리는 추가 전용 로그입니다. 이미지: 필자 제작.

DeepSeek Harness가 도구와 샌드박스를 제어하는 방식

모델은 도구를 이름으로 요청할 수 있지만 직접 실행할 수는 없습니다. 요청과 파일 시스템 변경 사이에는 두 단계의 별도 제어가 있습니다.

도구 실행 파이프라인

호출은 정책 점검, 실행, 결과 처리 단계를 거칩니다. 도구를 고르는 것은 모델이지만, 실행 여부와 방식은 런타임이 결정합니다.

도구의 실행 방식은 런타임이 결정합니다. 이미지: 필자 제작.

샌드박싱과 승인

• 승인은 사용자가 동작을 확인해야 하는지를 묻습니다. 
• 샌드박싱은 실행 범위와 방식을 제한합니다. 

DeepSeek는 두 개념을 분리합니다. 다만 권한 프리셋은 두 제어를 함께 묶어 제공하며, 이는 컨테이너 런타임이 프로세스 권한과 실행 경계를 구분하는 것과 유사합니다.

제한 사항에서 다시 언급할 점이니 미리 짚습니다. 시스템 프롬프트로 모델에게 "파일만 읽으라"고 지시하는 것은 모델이 따를 수 있는 제안일 뿐, OS 수준 샌드박스 제한처럼 강제되는 경계는 아닙니다.

DeepSeek Harness 모드: Standard, PTC, Minimal, Creator

DeepSeek Harness는 네 가지 모드를 제공합니다. 어느 하나가 상위 개념이 아닙니다. "이 세션에 런타임을 얼마나 노출할 것인가"에 대한 네 가지 해답이며, 올바른 선택은 작업에 따라 달라집니다. 앞선 아키텍처 섹션에서 보았듯 각 모드는 에이전트가 사용할 수 있는 도구 집합을 바꿉니다.

네 가지 모드는 하나의 런타임 기반을 공유합니다. 이미지: 필자 제작.

Standard 모드

범용 기준선:

• 파일 편집
• 셸 접근
• 파일 및 웹 검색
• Skills
• 계획
• 목표
• 서브에이전트
• 워크플로

일반적인 저장소 작업에는 이 모드로 시작하겠습니다.

PTC 모드

PTC 모드는 Standard의 도구 세트를 거의 그대로 유지하되, 모델이 도구에 접근하는 방식을 바꿉니다. (버전 0.1.2부터 웹 PTC 모드는 범용 workflow 도구를 기본 제공하지 않습니다.) 

여러 모델 스텝에 걸쳐 개별 도구를 요청하는 대신, 모델은 생성된 SDK를 대상으로 프로그램을 작성합니다. 그 프로그램은 run_code를 통해 여러 도구를 호출할 수 있습니다. 모든 호출은 동일한 정책 점검을 거치므로, PTC는 허용 동작을 바꾸는 것이 아니라 계획을 표현하는 방식을 바꿉니다.

제품 페이지에서는 여전히 "Code 모드"라는 라벨을 쓰지만, 최신 공식 릴리스에서 명칭을 PTC 모드로 바꾸면서 기존 대화 기록은 읽을 수 있게 유지했습니다. 여기서는 일관되게 PTC 모드라고 부르겠습니다. 약어의 의미는 FAQ에서 다시 다룹니다.

Minimal 모드

Minimal 모드는 환경을 두 가지 도구로 최소화합니다: 지속형 셸과 문자열 치환 파일 편집기. DeepSeek는 모델 벤치마크에 이를 사용합니다. 테스트 결과는 모델의 가중치뿐 아니라 하니스에도 부분적으로 의존하기 때문입니다.

Creator 모드

Creator 모드는 개발자가 런타임을 점검하고 메모리 내에서 Cordis 플러그인을 테스트할 수 있게 합니다. 프리셋을 구축하기 위한 용도이며, 그 이상의 자가 개선 기능이 있다고 보기는 어렵습니다.

DeepSeek Harness가 다른 에이전트 프레임워크와 다른 점

DeepSeek Harness는 런타임 하위 부분을 교체 가능하게 만들어 많은 에이전트 프레임워크와 다릅니다. 이 구분은 아키텍처에 포함시킬 수도 있었지만 놓치기 쉽습니다. Cordis는 하나의 플러그인 시스템으로 이러한 변화를 처리합니다.

도구 호출만 바꾸는 것이 아니라 에이전트의 동작 방식 자체를 바꿀 수 있습니다. 이벤트 로그 덕분에 개발자가 실행 과정을 채팅 대화록이 아닌 조사 가능한 형태로 남길 수 있습니다. 이어서 Minimal과 Creator 모드는 런타임을 서로 반대 방향에서 테스트하도록 도와줍니다.

DeepSeek Harness vs. Claude Code, Codex, OpenCode

기능 체크리스트만으로는 요점을 놓칩니다. 경쟁 제품들도 확장을 지원합니다. 유용한 질문은 개발자가 어느 부분을 바꿀 수 있느냐입니다. 사소해 보이지만 결코 작지 않습니다. Harness와 Claude Code 비교 기사에서는 동일한 모델을 양쪽에 사용해 설정, 로그, 비용을 다룹니다.

DeepSeek Harness vs. Claude Code

Claude Code는 프로젝트 지시문, 스킬, 훅, MCP, 서브에이전트, 에이전트 SDK를 지원하면서도 내장 루프는 고정합니다. DeepSeek Harness는 설정을 통해 루프, 모델 어댑터, 스토리지 레이어를 교체할 수 있습니다.

DeepSeek Harness vs. Codex

Codex는 CLI와 App Server도 오픈 소스이므로 더 신중한 비교가 필요합니다. 문서화된 진입점을 통해 개발자가 확장하는 에이전트 하니스를 제공합니다. DeepSeek Harness는 런타임 자체를 바꾸도록 설계되었습니다. 제어 수준이 다릅니다.

DeepSeek Harness vs. OpenCode

OpenCode는 이미 오픈 소스이고 여러 모델 제공자와 작동하며, 클라이언트-서버 아키텍처를 사용합니다. 도구, 권한, 세션, 제공자를 구성할 수 있습니다. 플러그인은 고정된 서버 코어를 확장하는 반면, DeepSeek는 루프와 세션 저장소까지 교체 가능하게 합니다.

DeepSeek Harness를 사용할 때

런타임 부품을 교체하는 행위 자체는 목적이 아닙니다. 추가 제어는 이미 겪고 있는 문제를 해결할 때만 가치가 있습니다.

• 런타임 자체가 프로젝트의 일부일 때. 모델 어댑터, 에이전트 루프, 스토리지, 세션 동작을 수정하는 경우, 단순히 에이전트 위에 구축하는 것이 아니라면 더 직접적인 선택입니다.
• 통제된 환경에서 모델을 비교할 때. 동일한 런타임을 사용하면 모델만 교체할 때 테스트의 더 많은 요소를 고정할 수 있습니다. 다만 모델의 도구 사용과 추론 방식 차이는 여전히 존재합니다.
• 복잡한 실행을 디버깅해야 할 때. 세션 이벤트 로그와 Trajectory 보기는 모델이 본 맥락과 실행된 도구를 재구성하기 쉽게 해 줍니다.
• 에이전트 내부를 테스트할 때. Creator 모드와 Cordis는 애플리케이션 코드 작성보다 에이전트 구성 방식을 연구하는 개발자에게 적합합니다.

단순한 모델 호출이나, 내부를 건드릴 필요 없이 완성형 코딩 에이전트를 원하는 팀에는 불필요할 수 있습니다. 더 많은 부품을 교체하는 일은 그 제어가 실제 문제를 해결할 때만 감수할 가치가 있습니다.

DeepSeek Harness의 한계: 개발자 프리뷰와 보안 위험

위의 아키텍처가 오늘 당장 어디에서 부족한지 명확히 짚지 않으면 큰 의미가 없습니다.

아직 개발자 프리뷰입니다

DeepSeek 저장소는 파괴적 변경이 있을 것이라고 분명히 밝힙니다. 이는 이미 일어났습니다. Code에서 PTC로의 이름 변경과 함께 세션 API 변경과 선택적 SQLite 스토리지 옵션 제거가 있었습니다. 버전을 고정하세요. 그 과정을 생략하고 설정이 안정적이길 바라기만 하는 것은 계획이 아닙니다.

더 많은 제어는 더 높은 복잡성을 의미합니다

런타임을 더 교체 가능하게 만들수록 개발자가 배울 것도 늘어납니다. 플러그인 의존성, 설정, 제공자 차이, 버전 호환성 등입니다. 이는 편의성과 제어 사이의 흔한 교환 관계입니다.

DeepSeek Harness는 로컬인가요?

DeepSeek Harness는 기본적으로 세션 내용, 도구 기록, 설정을 로컬에 저장한다고 데이터 처리 고지에 명시되어 있습니다. 설정과 프로젝트 목록에 대한 익명 보고는 끌 수 있습니다. 

하지만 외부 모델 제공자, 웹 도구, MCP 서버, 플러그인은 각자의 정책에 따라 데이터를 머신 밖으로 전송할 수 있습니다. "로컬 우선"은 연결하는 모든 서비스를 포괄하지 않습니다.

에이전트를 실행하는 것은 보안 위험을 동반합니다

파일을 편집하고, 명령을 실행하며, 서드파티 플러그인을 로드할 수 있는 런타임은 실제 피해를 유발할 수 있습니다. DeepSeek의 안전성 고지에 따르면 이 프로젝트는 보안 감사를 받지 않았습니다. 샌드박싱, 승인, 권한 제어는 위험을 줄여 주지만 격리를 보장하지는 않습니다.

자신의 머신에서 소프트웨어를 실행한다고 해서 위험이 사라지지 않습니다. 제한된 권한을 사용하고, 신뢰할 수 없는 작업에는 폐기 가능한 환경을 사용하며, 숨겨진 지시가 포함될 수 있는 콘텐츠에는 주의하세요.

에이전트의 행동은 왜 모델만으로 결정되지 않는가

에이전트의 행동은 모델뿐 아니라 런타임에도 좌우됩니다. 이는 "Agent = Model + Harness"로 돌아가며, 같은 분리는 DeepSeek를 넘어 LLM 에이전트 전반에 적용됩니다.

모델이 만들어낼 수 있는 것은 그 가중치에 달려 있습니다. 에이전트가 실제로 무엇을 하느냐는 모델이 어떤 컨텍스트를 받는지, 허용된 동작이 무엇인지, 실행이 얼마나 엄격히 제한되는지에도 달려 있습니다. 이 모든 것은 가중치에 포함되어 있지 않습니다.

DeepSeek Harness는 주변 레이어를 개발자가 교체 가능한 명명된 부품으로 분해해 보여 줍니다. Minimal 모드는 왜 이것이 DeepSeek를 넘어 중요한지도 보여줍니다. 벤치마크 점수는 모델뿐 아니라 테스트에 사용된 하니스를 부분적으로 반영합니다. 하니스가 모델을 더 똑똑하게 만드는 것은 아닙니다. 모델이 일하는 환경을 바꾸는 것입니다.

결론

서두의 문장이 핵심을 잘 담고 있습니다. 모델은 추론을 담당하지만, 런타임은 그 추론이 어디에 닿고 무엇을 할 수 있는지 결정합니다. DeepSeek Harness는 모델 어댑터와 도구부터 세션 저장소와 에이전트 루프까지 그 런타임을 편집 가능하게 만듭니다.

그 제어에는 비용이 따릅니다. 더 많은 런타임을 교체할수록 설정, 버전 변경, 보안 경계를 더 많이 책임져야 합니다. 셸 접근이 가능한 개발자 프리뷰는 설치하고 잊을 수 있는 종류가 아닙니다.

제 의견은 단순합니다. 런타임 자체가 작업의 일부일 때 DeepSeek Harness를 사용하세요. 저장소 편집만 필요하다면, 완성형 코딩 에이전트가 더 수월합니다.

설정 방법은 DeepSeek Harness 튜토리얼에서 다룹니다. Claude Code 대안 가이드는 더 많은 코딩 에이전트를 비교하며, Introduction to AI Agents는 이 글이 전제한 기본기를 다룹니다.