작동 원리 심층 (Under the Hood)
DeepSeek Harness의 내부 작동 방식은 크게 세 가지 축으로 나눌 수 있습니다: 서비스 주입 기반 메인 루프, 단조 증가형 이벤트 궤적 기록, 그리고 다단계 승인 제어 시스템입니다.
1. 이벤트 디스패치 및 메시지 세션 처리
사용자가 에이전트에게 명령을 전달하면 UI 플러그인이 이를 수신하여 커널의 이벤트 버스로 전달합니다. 커널은 등록된 모델 어댑터 플러그인으로 현재 맥락과 프로그래밍 가능한 스킬 목록을 넘깁니다. 모델이 도구 호출(Tool Call)을 판단하면, 도구 레지스트리 플러그인이 이를 받아 샌드박스 및 승인 정책 플러그인으로 검증을 요청합니다.
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#F0EEE9","primaryBorderColor":"#2a78d6","primaryTextColor":"#2b2926","secondaryColor":"#e8f0fb","secondaryBorderColor":"#4a3aa7","secondaryTextColor":"#2b2926","tertiaryColor":"#eafaf3","tertiaryBorderColor":"#1baf7a","tertiaryTextColor":"#2b2926","lineColor":"#8a8578","textColor":"#2b2926","edgeLabelBackground":"#F0EEE9","noteBkgColor":"#F0EEE9","noteTextColor":"#2b2926","noteBorderColor":"#8a8578","clusterBkg":"#faf9f6","clusterBorder":"#d8d4c8","fontFamily":"Pretendard, sans-serif"}}}%%
sequenceDiagram
participant User as 사용자
participant UI as UI 플러그인
participant Kernel as Cordis 커널
participant Model as 모델 어댑터
participant Tool as 도구 플러그인
participant Sandbox as 샌드박스
User->>UI: 메시지 전송
UI->>Kernel: 이벤트발행 사용자입력
Kernel->>Model: 프롬프트 전달 및 추론
Model-->>Kernel: 도구 호출 요청
Kernel->>Tool: 도구 검증 및 권한 확인
Tool->>Sandbox: 격리 환경 명령 실행
Sandbox-->>Tool: 실행 결과 반환
Tool-->>Kernel: 도구 실행 결과 반환
Kernel->>Model: 실행 결과 포함 프롬프트 재전송
Model-->>Kernel: 최종 응답 생성
Kernel-->>UI: 세션 기록 업데이트 및 사용자 출력
2. 세션 생명주기와 상태 관리
에이전트의 구동 세션은 정교한 상태 머신으로 관리됩니다. 각 상태 변화는 불변(Immutable) 상태로 전이되며 결코 이전 기록을 덮어쓰지 않습니다.
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#F0EEE9","primaryBorderColor":"#2a78d6","primaryTextColor":"#2b2926","secondaryColor":"#e8f0fb","secondaryBorderColor":"#4a3aa7","secondaryTextColor":"#2b2926","tertiaryColor":"#eafaf3","tertiaryBorderColor":"#1baf7a","tertiaryTextColor":"#2b2926","lineColor":"#8a8578","textColor":"#2b2926","edgeLabelBackground":"#F0EEE9","noteBkgColor":"#F0EEE9","noteTextColor":"#2b2926","noteBorderColor":"#8a8578","clusterBkg":"#faf9f6","clusterBorder":"#d8d4c8","fontFamily":"Pretendard, sans-serif"}}}%%
stateDiagram-v2
[*] --> STATE_IDLE
STATE_IDLE --> STATE_THINKING : 입력 수신
STATE_THINKING --> STATE_TOOL_CALL : 도구 호출 필요
STATE_TOOL_CALL --> STATE_APPROVING : 승인 정책 검사
STATE_APPROVING --> STATE_EXECUTING : 승인 완료
STATE_EXECUTING --> STATE_THINKING : 실행 결과 수신
STATE_THINKING --> STATE_RESPONDING : 최종 답안 생성
STATE_RESPONDING --> STATE_IDLE : 응답 완료
3. 단조 증가형 이벤트 트래젝터리(Trajectory) 데이터 스키마
DeepSeek Harness는 모든 실행 과정을 기록하는 트래젝터리(Trajectory) 데이터베이스 모델을 가지고 있습니다. 세션 아래 단계별 궤적이 생성되고, 그 궤적마다 세부 이벤트가 매핑되는 구조입니다.
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#F0EEE9","primaryBorderColor":"#2a78d6","primaryTextColor":"#2b2926","secondaryColor":"#e8f0fb","secondaryBorderColor":"#4a3aa7","secondaryTextColor":"#2b2926","tertiaryColor":"#eafaf3","tertiaryBorderColor":"#1baf7a","tertiaryTextColor":"#2b2926","lineColor":"#8a8578","textColor":"#2b2926","edgeLabelBackground":"#F0EEE9","noteBkgColor":"#F0EEE9","noteTextColor":"#2b2926","noteBorderColor":"#8a8578","clusterBkg":"#faf9f6","clusterBorder":"#d8d4c8","fontFamily":"Pretendard, sans-serif"}}}%%
erDiagram
SESSION_ENTITY ||--o{ TRAJECTORY_ENTITY : contains
TRAJECTORY_ENTITY ||--|{ EVENT_ENTITY : logs
EVENT_ENTITY ||--o| TOOL_CALL_ENTITY : triggers
EVENT_ENTITY ||--o| MODEL_LOG_ENTITY : records
SESSION_ENTITY {
string session_id
string created_at
string status
}
TRAJECTORY_ENTITY {
string trajectory_id
string session_id
int step_number
}
EVENT_ENTITY {
string event_id
string event_type
string timestamp
}
4. 베이스라인 실행 모드 분리
DeepSeek Harness는 사용 목적에 맞춰 최적화된 4가지 실행 기본 모드를 선언적으로 제공합니다.
| 실행 모드 | 주요 역할 및 특징 | 실행 도구 및 접근 권한 제한 |
|---|
| Standard 모드 | 일반적인 풀스택 에이전트 구동 환경 | 쉘 명령 실행, 웹 브라우징, 파일 CRUD 전체 접근 허용 |
| Code 모드 | 프로그래밍 기반 작업 처리를 위한 SDK 형태 | 여러 단계의 도구 연쇄를 코드 배치로 한꺼번에 실행 |
| Minimal 모드 | 경량화된 터미널 전용 제어 환경 | 지속형 쉘(Persistent Shell) 세션 중심의 최소 자원 구동 |
| Custom 모드 | 사용자 정의 플러그인 조합 모드 | 선언적 YAML/JSON 설정으로 동적 마운트 구성 |
DeepSeek Harness 내부에서 각 기능 모듈이 차지하는 역할 구성비는 아래 다이어그램과 같이 도구, 모델, 프로세스 제어가 균형 있게 정립되어 있습니다.
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#F0EEE9","primaryBorderColor":"#2a78d6","primaryTextColor":"#2b2926","secondaryColor":"#e8f0fb","secondaryBorderColor":"#4a3aa7","secondaryTextColor":"#2b2926","tertiaryColor":"#eafaf3","tertiaryBorderColor":"#1baf7a","tertiaryTextColor":"#2b2926","lineColor":"#8a8578","textColor":"#2b2926","edgeLabelBackground":"#F0EEE9","noteBkgColor":"#F0EEE9","noteTextColor":"#2b2926","noteBorderColor":"#8a8578","clusterBkg":"#faf9f6","clusterBorder":"#d8d4c8","fontFamily":"Pretendard, sans-serif"}}}%%
pie title DeepSeek Harness 실행 환경 기능 구성 요소
"모델 어댑터 및 추론" : 25
"도구 및 스킬 레지스트리" : 25
"샌드박스 및 프로세스 제어" : 20
"세션 및 궤적 기록" : 15
"승인 정책 및 UI" : 15
이러한 분리 구조 덕분에 문제가 발생했을 때 전체 파이프라인을 재구성할 필요 없이, 문제가 되는 특정 로그 및 재생 엔진에 접근하여 분석할 수 있습니다.
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#F0EEE9","primaryBorderColor":"#2a78d6","primaryTextColor":"#2b2926","secondaryColor":"#e8f0fb","secondaryBorderColor":"#4a3aa7","secondaryTextColor":"#2b2926","tertiaryColor":"#eafaf3","tertiaryBorderColor":"#1baf7a","tertiaryTextColor":"#2b2926","lineColor":"#8a8578","textColor":"#2b2926","edgeLabelBackground":"#F0EEE9","noteBkgColor":"#F0EEE9","noteTextColor":"#2b2926","noteBorderColor":"#8a8578","clusterBkg":"#faf9f6","clusterBorder":"#d8d4c8","fontFamily":"Pretendard, sans-serif"}}}%%
flowchart LR
INPUT["사용자 입출력"] --> TRAJ_LOG["단조 증가 이벤트 로그"]
TOOL_EXEC["도구 실행 결과"] --> TRAJ_LOG
MODEL_REASON["모델 추론 기록"] --> TRAJ_LOG
TRAJ_LOG --> REPLAY_ENGINE["타임라인 리플레이 엔진"]
REPLAY_ENGINE --> DEBUG_ANALYSIS["오류 분석 및 벤치마크"]