DeepSeek Harness(dsh)는 DeepSeek AI가 2026-08-13 개발자 프리뷰(MIT)로 공개한 오픈소스 에이전트 하네스다. “Everything is a plugin”을 설계 원칙으로, 모델 어댑터·도구·스킬·세션·샌드박스·스토리지·루프·스케줄링·UI까지 전부 교체 가능한 플러그인으로 구현되며, Cordis 메타 프레임워크 위에서 구동된다. 공개 이틀 만에 GitHub stars 10만+를 기록했다.
핵심 사실
| 항목 | 값 |
|---|---|
| 저장소 | deepseek-ai/deepseek-harness (2026-08-13 생성, TypeScript) |
| 라이선스 | MIT (3rd-party 라이선스는 THIRD_PARTY_NOTICES.md) |
| npm 패키지 | @deepseek-ai/dsh — npx @deepseek-ai/dsh web |
| 기본 Web UI | http://127.0.0.1:3080 |
| 상태 | Developer preview — 호환성 깨짐 예고 |
| 기반 프레임워크 | Cordis v4 — A Programming Paradigm for Spatiotemporal Composability |
| 공개 릴리스 | dsh@0.1.0-rc.5 (고정 커밋 47f943859bef) |
| 지표 (2026-08-15 16:10 KST) | stars ~102,576 / forks ~9,736 / open issues 0 |
구조 분석
1. 모노레포 레이아웃
| 경로 | 규모 | 역할 |
|---|---|---|
apps/ | cli + web | dsh CLI·headless 러너와 Vite 브라우저 앱 |
packages/ | 219개 문서화 패키지, ~3,748 파일 | 제품의 실체 — 모든 기능이 여기 |
docs/ | 324 파일 | architecture·development·subsystems 45종·cookbook·cordis-primer/tutorial·postmortem 4건 |
native/ | landlock-run | Linux Landlock 샌드박스 네이티브 러너 (linux-x64/arm64 프리빌드) |
python/ | sdk + sdk-runtime | 공식 Python SDK(deepseek_harness) + 번들 런타임(cordis.yml 포함) |
.agents/ | 2,078 파일 | 에이전트 노트(implemented 1,517·archived 428·proposed 75·rejected 33) + dsh-* 스킬 — 프로젝트 자체가 에이전트 주도로 개발됨 |
vendor/ | 74 파일 | 벤더드 의존성 (manifest guard로 동기화) |
2. Cordis 커널 — “privileged core 없음”
Cordis 플러그인은 공유 context에 services·typed events·reversible effects를 기여한다. 모델 어댑터·도구 registry·세션 로그·agent loop까지 전부 플러그인이므로 수정할 “코어”가 없다. 등록(registration)은 effect로 취급되어 플러그인이 언로드되면 원상 복구(unwind)된다.
- 프로필(bundle 스택): 실행 중인 dsh는 부팅 시 순서 있는 레이어로 조립된 플러그인 트리.
web·headless가 템플릿 프로필. - 번들(bundle): Cordis 설정 행과 그 행이 마운트하는 코드의 배포 단위.
package.json의dsh필드(dsh.profile/dsh.bundle)로 자기 선언. - 패치 레이어: 번들 순서 → 프로필
cordis.patch.yml→ 사용자 home patch →--patchoverlay 순으로 적용. 패치는 행(row)을 전체 교체하므로 부분 병합이 아니다. dsh --profile web --dump-config로 실제 부팅 트리 확인 가능 — 출력되는 모든 행은 패치로 교체 가능하다.
3. 패키지 지도 (도메인 → 패키지)
| 도메인 | 대표 패키지 | 역할 |
|---|---|---|
| core | core/session·system-prompt·tools·agent·agent-loop·scope | SessionEvent 로그·프롬프트 조립·도구 registry·agent registry·기본 루프·per-agent scope |
| llm | llm/llm·llm-deepseek·llm-pi-ai·llm-retry·token-meter | 메시지/스트림 어휘 + 모델 어댑터 seam (ctx.llm) |
| bundle | bundle/base·web-app·headless | 프로필 기본 레이어 + 표면별 번들 |
| session | session-persistence-jsonl·sqlite·session-projection·session-telemetry·session-title | 로그 영속화·프로젝션·텔레메트리·제목 생성 |
| fs | fs/fs·fs-local·fs-sandbox·tool-fs·tool-str-replace-editor | 파일시스템 seam + 도구 |
| shell | shell/bash-local·bash-sandbox·tool-bash(-persistent) | 셸 실행 seam |
| sandbox | sandbox·sandbox-local·sandbox-policy·sandbox-windows-acl | 실행 격리 (Windows ACL 포함) |
| subprocess | subprocess·subprocess-local | 프로세스 생성 |
| subagent | subagent·tool-subagent·subagent-in-process-driver·subagent-acp·subagent-claude-code·subagent-codex | 서브에이전트 provider — ACP/Claude Code/Codex 위임까지 교체 가능 |
| terminal | terminal·terminal-bash·tool-terminal | 영속 터미널 |
| lsp | lsp·lsp-stdio·tool-lsp | LSP 통합 |
| mcp | mcp-client | MCP 클라이언트 (현재 tools만; resources·prompts는 deferred) |
| acp | acp | Agent Client Protocol |
| hooks | hooks-claude-code·hooks-codex·hook-protocol | 외부 에이전트 훅 |
| workflow | workflow·tool-workflow·workflow-worker-thread | 워크플로우 (journaling·resume은 미제공) |
| goal / plan | goal·tool-goal·plan-mode | 목표 관리·플래닝 |
| skill | skill·tool-skill·skill-filesystem | 스킬 registry (provider-driven) |
| compaction / spill | compaction-basic·spill·spill-policy | 컨텍스트 압축·스필 |
| context | agent-instructions·session-reference·time-context·tmux-context | 컨텍스트 주입 |
| api / sdk / typert | api/gateway·api/remotes·sdk/client·typert/* | Host↔Client RPC 계약·외부 SDK·타입 반영 생성 |
| client | client/ui-* 25종 | 브라우저 UI 플러그인 (대화·도구·설정·trajectory·워크플로우 등) |
| extensions | cordis-host-runner·tool-cordis·ui-cordis | 자가-확장 — dsh가 자기 런타임을 inspect하고 실험 |
| code-runtime | code-runtime·code-runtime-worker-thread | Code Mode SDK 실행 |
| web | web·web-search-deepseek/exa/perplexity·tool-web | 웹 검색·가져오기 |
| e2b | e2b·fs-e2b·subprocess-e2b | E2B 원격 샌드박스 |
4. 실행 모드 4종
- Standard: 파일 편집·셸·파일/웹 검색·스킬·플래닝·목표·서브에이전트·워크플로우의 풀 코딩 에이전트.
- Code: Standard 전체 + Code Mode SDK — 모델이 한 TypeScript 프로그램으로 다단계 도구 호출을 오케스트레이션.
- Minimal: persistent bash + str_replace_editor 2도구 — 최소 환경에서 모델 벤치마킹용.
- Creator: Standard + 런타임 검사·메모리 내 Cordis 플러그인 실험·프리셋 저작 — 새 모드를 조합해 만드는 모드.
5. 턴 플로우 (이벤트 파이프라인)
turn/start → 입력 claim → 프롬프트 섹션+툴 스키마 조립 → agent/pre-step → step/start
→ llm/stream → assistant/* → tool/call → tools/pre·execute·post → tool/result → step/end
→ agent/turn-stopping → turn/end
- step = 모델 요청 1회 + 그 요청이 호출한 도구들. turn = 0+ step.
- durable session events (
turn/*,step/*,user/message,assistant/*,tool/*)는 로그에 남는다. 그 외agent/*·tools/*·llm/stream은 라이브 확장점이고, waterfall 이벤트는next()로 위임해야 한다. - 입력은 단일 inbox로 들어오며, 컨텍스트 주입은 다른 메시지가 올 때까지 대기한다.
6. 세션 로그 = 모델 컨텍스트의 원장
append-only SessionEvent 스트림이 context의 source of truth다. deriveMessages()가 로그에서 모델 history를 투영하고, “Model-visible means logged” 런타임 불변식이 모델 요청에 도달하는 모든 입력이 로그에서 재구성 가능함을 강제한다. resume·fork·search·replay·transcript·telemetry·persistence 모두 같은 스트림에서 파생되며, Trajectory 뷰는 이를 source별로 보여준다.
7. Capability seam — provider 교체가 제품 전체를 바꾼다
seam = Service Definition(인터페이스) + Service Provider(구현) + Consumer(보통 모델-facing tool) 3역할. filesystem·subprocess provider를 원격 sandbox로 교체하면 Bash·PTY·LSP까지 소비자 복제 없이 함께 이동하고, subagent provider도 새 child agent에서 타 제품 위임까지 폭이 넓다.
8. 개발·빌드 구조
- Host/Client 두 tsconfig aggregate (
tsconfig.host.json/tsconfig.client.json): CordisContext인터페이스를 양쪽이 같은 키로 declaration-merge하므로 한 프로그램에 합치면 충돌 → 두 aggregate로 분리. - Typert: Host 타입을 분석해 Host-for-Client Remote projection(api/remotes RPC 계약)을 생성. Host tsdown 단계에서만 실행.
- pnpm@11.7.0, Node 22.19+/24+ (CI 22.19/24/26), lefthook 훅, keyless CI lanes, i18n 문서 체계(EN/zh).
커뮤니티 반응 (HN 722점, 301 comments)
- “Every run is traceable”을 killer feature로 평가: 공식 하네스가 CoT trace를 사용자에게 공개하는 드문 사례 — 미국 모델은 trace를 난독화·암호화한다는 맥락에서 차별점으로 꼽힌다.
- Cordis는 신규가 아님: v3가 4년간 Koishi(봇 프레임워크)에서 검증됐고, v4(이번 논문)가 destructor류 reversible effect·hot reload·동적 enable/dispose를 더했다. OSGi/React useEffect와 비교하는 시각도 있다.
- 비판·회의론: 구조화된 도구 응답 스키마가 LLM과 안 맞는다는 의견, 플러그인 간 의존성 주입의 복잡성 대비 실익(90%는 단순 플러그인)을 의심하는 리뷰, git 도구가 bash 뒤에 숨어 있어 최상위 도구로 필요하다는 피드백.
- 제품 하나라기보다 **“에이전트 하네스를 만드는 하네스/기반 런타임(Agent OS substrate)“**으로 읽는 해석이 일반적이다.
관계
- harness — 에이전트 하네스 아키텍처 개념 (이 페이지의 상위 개념)
- 2026-08-15-x-deepseek-harness-developer-preview — 발표·저장소 인제스트 요약 (기능 경계·한계 상세)
- 2026-08-17-deepseek-harness-study-guide — 고정 커밋의 부팅·세션·도구·프리셋 실행 경로를 따라가는 심층 학습 노트
- moc-ai-agents-harness · moc-ai-agents — 하네스/에이전트 MOC
- deepseek-v4 — DeepSeek 모델 패밀리 (하네스는 모델과 독립 — provider로 교체 가능)
- 2026-08-11-github-primeintellect-prime-agent — 유사한 장기 실행 자기개선 코딩 에이전트
- hermes-agent — 다른 에이전트 프레임워크 (플러그인/스킬 구조 비교 대상)
검증 경계
- 구조 분석 기준:
masterHEAD47f943859bef(2026-08-13, dsh@0.1.0-rc.5) — 기존 raw 캡처와 2026-08-17 고정 커밋 소스 조사에서 동일함을 확인. - stars/forks/주요 수치는 2026-08-15 GitHub API 스냅샷. 공개 이틀 만에 stars 10만+로 빠르게 변동 중.
- 이 세션에서는 설치·빌드·실행·모델 호출을 수행하지 않았다. 플러그인·seam·모드에 대한 서술은 공식 문서/저장소 구조 기반이며, 실제 동작 품질·권한 안전성은 미검증 상태다. 세부 학습 경로는 2026-08-17-deepseek-harness-study-guide에 정리했다.