DeepSeek Harness · 시스템 맵

모든 것이 플러그인: 공식 발표와 소스 대조

발표문에 나온 네 모드·플러그인 생태계가 deepseek-harness 저장소의 어느 파일에 대응할까요? 이 레슨에서 하나씩 맞춰 봅니다.

강의 목표이 레슨을 읽고 나면 발표문의 말을 두 가지 아이디어로 풀어낼 수 있어요. DSH가 모델 어댑터·도구·agent loop까지 전부 플러그인으로 만든 이유, 그리고 공식 발표의 네 모드가 소스에서는 플러그인 목록 네 장에 불과한 이유. PTC 모드의 소스 속 진짜 이름도 말할 수 있게 됩니다.
인터랙티브 데모 · 먼저 해보고 배우기

아래 데모는 플러그인 목록 네 장을 전환 가능한 패널로 만들었어요. 위 네 모드 버튼을 눌러 카드가 어떻게 켜지고 꺼지는지 보세요. 초록은 추가, 빨강은 제거, 호박색은 이름은 같지만 설정이 바뀐 경우예요. 하단 자막이 매 단계를 알려 줍니다. 먼저 갖고 놀아 두면, 뒤에서 말할 아이디어는 이미 이 패널에서 한 번씩 돌아간 거예요.

이전 모드 대비 추가 이전 모드 대비 제거 같은 이름 플러그인, 설정만 다름 이 모드에서 활성 이 모드에서 미마운트
플러그인 목록은 apps/cli/config/agent-presets/ 아래 agent.cordis.yml 네 장에서 가져왔어요(확인일 2026-08-13). 플러그인 id와 패키지 이름은 소스 실명입니다. macOS 시점으로, Windows 전용 tool-pwsh와 disabled 위임 행 두 줄은 빼 두었어요. 시야에 들어오면 네 모드를 한 바퀴 자동 재생한 뒤, 자유롭게 클릭할 수 있어요.
아이디어 1 · 커널은 장착·해제만, 비즈니스는 전부 플러그인

어떤 문제를 푸는가.모놀리스 Agent 제품을 쓰다가 세션 로그 포맷만 바꾸고 싶다고 상상해 보세요. 저장소를 fork하고, 수십만 줄 소스에서 로그 구현을 찾아 고친 뒤 다시 빌드하고, 업스트림이 나올 때마다 패치를 다시 합쳐야 해요. 로그 같은 변두리 능력만 이래도 그런데, agent loop 본체까지 바꾸려면 사실상 제품 재작성이에요. 능력이 제품 소스에 용접돼 있으면, 깊은 커스터마이징은 전부 장기 유지보수 짐이 됩니다.

아이디어는 무엇인가.DSH는 커널을 최소로 줄여요. 저장소에 vendor된 Cordis 프레임워크는 세 가지만 합니다. 공유 컨텍스트에 플러그인을 싣고, 내리고, 매번 등록을 되돌릴 수 있는 부작용으로 기록해 언로드 때 자동 롤백. 비즈니스 로직은 한 줄도 없어요. 모든 능력은 packages/로 옮겨져 49개 그룹·219개 패키지가 전부 플러그인으로 존재합니다. 모델 어댑터도, 도구도, 세션 로그도, agent loop 본체까지 플러그인이에요. 루트 AGENTS.md 3행은 굵은 영어로 “everything is a plugin”이라고 적혀 있어요. 공식 문서 원문:

Cordis는 dsh의 기반 프레임워크예요. 플러그인이 공유 컨텍스트에 서비스·타입화된 이벤트·되돌릴 수 있는 부작용을 기여합니다. 제품의 모든 부분이 플러그인이며, 모델 어댑터·도구 레지스트리·세션 로그·agent loop 자체까지 포함하니, 각각을 설정으로 교체할 수 있어요.

패치해야 하는 특권 커널은 없어요. dsh를 확장하는 방법은 다른 플러그인 옆에 플러그인을 마운트하는 것이고, 각 등록은 부작용이라 해당 플러그인이 언로드되면 취소됩니다.

docs/architecture.zh.md · 11·13행
vendor/ Cordis 커널 플러그인 로드 / 언로드 의존성 해석 부작용 롤백, 비즈니스 로직 제로 packages/ · 49그룹 · 219패키지 · 전부 플러그인 core/ 제품 API 백본 session · system-prompt · tools · agent-loop 능력 seam 시리즈 llm · fs · shell · sandbox · web · compaction … 세션과 데이터 session · storage · settings · credentials … 엔트리와 UI boot · host · client · api · acp · sdk 조합과 생태계 bundle · preset · extensions · hooks agent-presets/ 플러그인 목록 네 장 standard/ 표준 code/ PTC minimal/ 미니멀 cordis/ 크리에이티브
수업용 구조도: 그룹 분류는 AGENTS.md “Repository layout”과 packages/README.zh.md를 따르며, 내용은 수업에 맞게 정리했습니다. 패키지 수는 2026-08-13 로컬 집계예요.

DSH에 능력을 더할 때도 그 저장소를 건드릴 필요 없어요. 트리 밖(out-of-tree, 공식 저장소 바깥) 플러그인은 dsh plugin --profile <name> add <package>로 profile에 넣고, 런타임에 마운트되며, 언로드 때 등록된 부작용이 자동 롤백됩니다. README는 플러그인 저장소에 dsh-plugin 토픽 태그를 달아 서로 찾게 하라고도 해요. 발표문이 생태계 공동 구축을 초대하는 이유 — 메커니즘은 이미 있어요.

출처: packages/bundle/README.zh.md 13행; README.zh.md 40행; docs/architecture.zh.md 13행

왜 오래가는가.마이크로커널 생각은 이 코드보다 훨씬 오래됐어요. OS 수업의 Mach와 L4, 브라우저 확장 체계, VS Code 플러그인 생태계 — 같은 길이에요. 빨리 바뀌는 능력은 바깥 고리, 거의 안 바뀌는 장착·해제는 코어. DSH가 내년에 agent loop를 다시 써도 Cordis 장착·해제 로직은 한 줄도 안 건드리고, 다른 언어로 harness 전체를 다시 써도 이 계층은 그대로 먹혀요. 그래서 이 강의의 구조를 기억하는 편이 코드를 외우는 것보다 이득이고, 코드는 이 아이디어의 한 구현일 뿐이에요.

빨리 바뀌는 능력은 플러그인에, 거의 안 바뀌는 장착·해제는 커널에 살아요.
아이디어 2 · 모드는 곧 목록 한 장

어떤 문제를 푸는가.대부분 제품의 모드는 하드코딩이에요. if (mode === 'lite') 같은 분기가 코드에 흩어져 있고, 모드 개수는 코드를 쓰는 순간에 이미 고정됩니다. 모드를 하나 더하려면 코드를 고치고 테스트를 통과하고 배포를 기다려야 하고, 모드 안 능력 하나만 미세 조정해도 같은 파이프라인이에요. 사용자는 더 선택지가 없어 공식 패키지 몇 개 중에서만 고르게 됩니다.

아이디어는 무엇인가.DSH에서 모드는 apps/cli/config/agent-presets/ 아래 디렉터리 하나이고, 안에 파일 두 개예요. preset.yml은 3줄뿐으로 UI 표시 이름과 정렬만 맡고, agent.cordis.yml은 플러그인 목록이라 부팅 때 Cordis가 줄줄이 마운트해 조립된 Agent를 내놓습니다. 모드 전환은 목록을 바꿔 다시 조립하는 것이고, 소스에 모드 분기는 없어요. 네 모드 차이는 카드 네 장이면 충분해요:

표준 모드

agent-presets/standard/ · 251행
누구를 위한가
매일 코드를 쓰는 사람 — 이게 기본 티어예요.
다른 모드와의 관계
이게 기준이에요. 플러그인 23개 전부 켜진 상태(macOS 시점)로 파일 편집·shell·검색·계획·서브에이전트·워크플로가 다 있어요. 나머지 세 모드는 전부 이것에 대한 가감으로 설명됩니다.
뒤의 아이디어
능력이 갖춰진 참조계를 먼저 정의해야, 다른 조합도 한 문장으로 자신을 말할 자격이 생겨요.
출처: standard/agent.cordis.yml 전문

PTC 모드

agent-presets/code/ · 262행
누구를 위한가
긴 다단계 작업을 돌리면서, 도구 호출 왕복을 한 번에 하나씩 하기엔 너무 느리다고 느끼는 사람.
표준 대비 뭐가 늘고 줄었나
standard는 한 줄도 안 건드리고, 끝에 tool-presentation 하나를 더 달며 mode: code로 설정해요. 모델이 TypeScript 작은 프로그램을 쓰면, run_code 한 번에 예전엔 왕복 다섯 번이던 일을 끝냅니다.
뒤의 아이디어
바뀐 건 도구 제시 방식뿐이고 능력 자체는 그대로라, 차이는 한 줄만 가질 자격이 있어요.
출처: code/agent.cordis.yml 259–262행, 3행 주석에 standard 전량이 그대로라고 명시

미니멀 모드

agent-presets/minimal/ · 62행
누구를 위한가
모델 벤치마크를 돌리는 사람.
표준 대비 뭐가 늘고 줄었나
플러그인은 6개만 남아요. persona는 한 문장으로 고정(complete: true — 다른 플러그인이 프롬프트를 덧붙이려 해도 못 함)이고, 도구는 지속 bash와 str_replace_editor뿐, compaction(컨텍스트 압축)도 없어요.
뒤의 아이디어
harness 변수를 깨끗이 비우면, 남는 표현은 모델 그 자체예요.
출처: minimal/agent.cordis.yml 전문 62행, persona는 8–13행

크리에이티브 모드

agent-presets/cordis/ · 262행
누구를 위한가
Agent가 Agent를 만들게 하고 싶은 사람.
표준 대비 뭐가 늘고 줄었나
standard 풀세트 위에 tool-cordis 도구 세트, 조합 작성을 가르치는 skill 하나, persona 버전도 바꿔 달아요. Agent가 런타임에 자기 플러그인을 검사·마운트하고, 쓴 조합을 새 preset으로 저장할 수 있어요.
뒤의 아이디어
조립기 자체도 플러그인이라 Agent에게 열어 줄 수 있어요. 파일 머리 주석은 이 모드의 세션을 shell 권한처럼 다루라고 경고합니다.
출처: cordis/agent.cordis.yml 245–246행, 권한 경고는 9–12행

마케팅 단어 하나를 짚고 넘어갈게요. code/preset.yml 1행은 name: PTC 模式라고 쓰지만 디렉터리 이름은 code이고, 소스 주석·문서에서는 이 메커니즘을 Code Mode라고 부르며, 저장소 어디에도 PTC라는 구현 이름은 없어요. PTC는 UI 문구 층에만 살고, 소스를 말할 때는 Code Mode라고 해야 맞아요.

모드를 바꾼다는 건, 목록을 바꿔 다시 조립한다는 뜻이에요.

왜 오래가는가.이 아이디어엔 흔한 이름이 있어요 — 설정이 곧 아키텍처. 시스템 간 행동 차이를 선언형 목록 한 장으로 모으면, 아키텍처 문제는 텍스트 문제로 차원이 낮아져요. 두 모드 차이는 YAML 두 장을 diff하면 되고, 새 모드는 디렉터리를 복사해 몇 줄만 고치면 되고, 문제 나면 목록을 롤백하면 돼요. Kubernetes는 YAML로 클러스터를, Docker는 Dockerfile로 이미지를 선언하죠 — 같은 생각이 다른 층에서 반복됩니다. DSH 플러그인 구현이 언젠가 전부 다시 쓰여도, 목록이라는 추상은 그대로 성립해요.

가로 비교 · 능력을 더할 때 저장소 소스를 고쳐야 하나

모든 것이 플러그인이라는 가치는 동종 제품을 옆에 둬야 선명해져요. 같은 질문 — Agent에 새 능력을 더할 때 그 저장소 소스를 건드려야 하나 — 세 곳이 세 가지 답을 내놓아요:

DSH: 플러그인 트리

저장소를 고칠 필요 없음

능력은 트리 밖 npm 패키지 하나예요. dsh plugin --profile <name> add <package>로 profile에 넣고, 런타임에 마운트되며, 언로드 때 등록된 부작용이 자동 롤백됩니다. 모드 단위 차이도 YAML에서 몇 줄 가감일 뿐이에요.

출처: packages/bundle/README.zh.md 13행; docs/architecture.zh.md 13행

Claude Code: 제품 모놀리스

경우에 따라

복원 소스는 TypeScript 모놀리스 트리(restored-src/src/, 엔트리 main.tsx)라 내장 기능을 바꾸려면 제품 소스를 건드려야 해요. 바깥으로는 hooks·MCP·Skills 확장구가 있어 도구와 가로채기 지점은 더할 수 있지만, 세션 로그 같은 깊은 구현은 갈아끼울 수 없어요. 공개 증거(복원 소스 디렉터리 구조) 기준.

Grok Build: Cargo Workspace

저장소를 고쳐야 함

루트 Cargo.toml의 members 배열에 workspace 멤버 79개(로컬 집계)가 있고, 능력은 crate로 나뉘어 컴파일 타임에 조합돼요. 새 능력은 crate를 만들고 루트 목록을 고친 뒤 다시 컴파일해야 합니다. 분할 세부: 12-1 · Workspace 멤버 79개가 제품을 이루는 방식.

세 곳에 절대 우열은 없어요. Grok은 컴파일 타임 조합으로 Rust 타입·성능 보장을, Claude Code는 모놀리스로 제품 반복 속도를, DSH는 플러그인 트리로 런타임 탈부착을 얻어요. 다만 교체·감사 가능한 런타임이 필요하다면, fork 없이 깊은 능력을 바꿀 수 있게 하는 건 셋 중 DSH뿐이에요.

수업 실습
01

목록에서 행동 차이 추론하기

standard/agent.cordis.yml에서 id: compaction 그룹 전체(137–155행)를 지운 세션이, 컨텍스트 압박 아래에서 미니멀 모드와 동등할까요? 이어서 minimal/agent.cordis.yml의 persona 필드 세 개(8–13행)를 대조해, 압축 말고 또 빠진 두 가지를 말해 보세요.

Takeaway:DSH 커널은 플러그인 로드·언로드·의존성만 맡고, 능력은 전부 packages/ 안의 플러그인이에요. 공식 발표의 네 모드는 소스에서 agent-presets 플러그인 목록 네 장이고, 모드를 바꾼다는 건 목록을 바꿔 다시 조립한다는 뜻입니다. PTC라는 이름은 preset.yml 표시 이름에만 살고, 메커니즘의 진짜 이름은 Code Mode예요.