DeepSeek Super-agent 설정: Router와 Worker 작동 방식

DeepSeek Super-agent는 저장소 하나, 허용된 요청자 한 명, 전용 운영체제 계정으로 먼저 시험합니다. Router는 권한이 확인된 요청을 Ticket으로 만들고, Worker는 각각 별도의 세션과 디렉터리에서 작업합니다. 처음에는 observe를 켜 두되, 명시적인 요청은 이 모드에서도 실행될 수 있다는 점에 유의합니다.

2026-11-09 기준 dsh-superagent-prototype은 연구용 코드입니다. DeepSeek의 공식 제품이나 운영 환경에 바로 투입할 수 있는 서비스가 아닙니다. 패키지 매니페스트에는 버전 0.1.0과 MIT 라이선스가 명시되어 있습니다. 공개 구현은 팀의 내부 시스템 및 설계 글에서 설명한 구현과도 다릅니다.

Router, Ticket, Worker의 역할

핵심 차이는 새로운 모델이나 코딩 화면이 아니라, 저장소에서 작업 요청을 계속 받는다는 점입니다. 이 확장 패키지는 DeepSeek Harness 안에서 실행되며 GitHub 저장소 하나를 감시합니다. 필요하면 Feishu 메시지도 받을 수 있습니다.

도메인 모델은 들어오는 이벤트와 실행이 허용된 작업을 구분합니다. Eval이라는 평가 과정이 작업 후보를 새 Ticket으로 만들지 판단합니다. 수락된 Ticket마다 권한의 근거와 작업 범위를 기록하는 Mandate가 붙습니다.

Router는 요청을 어디로 보낼지 결정하는 기본 에이전트 세션입니다. Worker는 수락된 작업을 실행합니다. 설정 화면에서는 이 Worker를 Executor라고 부릅니다.

Worker마다 별도의 세션과 작업 디렉터리를 사용합니다. 결과는 풀 리퀘스트 링크가 담긴 GitHub 댓글처럼 원래 대화로 돌아옵니다. 디렉터리를 나누면 작업 사본은 분리되지만, 프로세스가 읽을 수 있는 파일까지 제한되지는 않습니다.

예를 들어, 서로 관련 없는 버그 보고 두 건을 하나의 코딩 대화에 넣는 대신 별도 Ticket으로 처리할 수 있습니다. 개별 코딩 작업을 시작하는 것보다 들어오는 요청을 정리하고 배분하는 데 더 많은 주의가 필요한 경우에 유용합니다.

대화하면서 변경 하나를 처리하려면 기존 코딩 에이전트를 유지합니다. 범위를 제한해 작업을 맡기려면 모델을 명시적으로 지정한 읽기 전용 Claude Code 하위 에이전트부터 시작합니다.

observe가 보안 샌드박스가 아닌 이유

observe는 맥락에서 추론한 작업을 제한할 뿐, 모든 실행을 막지는 않습니다. 권한 규칙은 모든 수락 모드에서 명시적인 요청을 허용합니다.

observe에서는 추론한 작업 후보가 긍정적으로 평가되어도 “would accept” 기록만 남기고 작업을 만들지 않습니다. auto에서는 긍정적인 평가를 바탕으로 추론한 작업을 수락할 수 있습니다. 허용된 사람이 에이전트를 멘션하면 어떤 모드에서도 작업을 요청할 수 있습니다.

허용 목록만으로 요청 수락 여부를 통제하는 것은 아닙니다. 수락 설정표의 셀에서 목록에 없는 사람에게도 명시적인 요청 권한을 부여할 수 있습니다. 따라서 observe에만 의존하지 않고 아래 절차로 요청자를 한 명으로 제한합니다.

danger-full-access의 의미

에이전트의 인증 정보만 보관하는 운영체제 계정을 사용합니다. 배포 가이드의 격리 경고는 dsh-superagent-router와 dsh-superagent-worker 모두에 적용됩니다. 두 프리셋은 운영자의 운영체제 사용자로서 danger-full-access 권한으로 실행됩니다.

인증 정보 래퍼는 사용할 계정을 선택할 뿐, 프로세스를 격리하지 않습니다. Worker는 절대 경로로 프로그램을 실행하고 운영자의 홈 디렉터리를 읽을 수 있습니다. 구현 가이드에 따르면 Router에도 셸과 파일 읽기 도구가 제공됩니다.

첫 시험에는 임시 머신이나 가상 머신을 사용하고, 에이전트 계정에는 관리자 권한을 주지 않습니다. 개인 인증 정보, 운영 환경의 비밀 정보, 관련 없는 저장소는 이 환경에 두지 않습니다. 이는 배포 시 적용하는 예방 조치이며, 프로토타입 자체가 제공하는 보호 기능이 아닙니다.

Harness 프로필도 별도로 유지합니다. 플러그인은 프로세스 전체의 PATH와 git 설정을 변경합니다. 패널은 127.0.0.1에 바인딩한 상태로 두고, 시험 서비스를 공개 웹 서비스로 노출하지 않습니다.

GitHub만 사용하는 시험 환경 구성

새 계정과 새 프로필에서 아래 수동 절차를 진행합니다. 저장소에는 에이전트의 도움을 받아 설정하는 SETUP.md도 있습니다.

사전 요구 사항 확인

Node.js 22.19+ 또는 24+, pnpm, git 2.32+, Python 3.8+, tmux, GitHub CLI 2.48+를 설치합니다. 이는 문서에 명시된 사전 요구 사항입니다.

github.com의 저장소와 DeepSeek Harness용 모델 제공업체도 필요합니다. GitHub Enterprise Server는 지원하지 않습니다. 대상 저장소에서 Git LFS를 사용한다면 git-lfs를 설치합니다.

비어 있지 않고 README.md가 포함된 시험용 저장소를 사용합니다. 첫 시험에는 요청자와 에이전트만 접근하는 비공개 저장소를 권장합니다.

Feishu는 선택 사항이며 이번 시험에서는 사용하지 않습니다. 문서의 연결 절차에는 봇이 활성화된 Feishu 또는 Lark 앱과 lark-cli가 추가로 필요합니다. 프로젝트에서 시험한 lark-cli 버전은 1.0.90입니다.

에이전트 계정으로만 로그인

전용 GitHub 사용자 계정을 만들고 시험용 저장소에 쓰기 권한을 부여합니다. 전용 운영체제 계정의 Bash에서 다음 명령을 실행합니다.

unset GH_TOKEN GITHUB_TOKEN
gh auth login --hostname github.com --git-protocol https
gh api user --jq .login
gh auth setup-git --hostname github.com

에이전트 계정으로 GitHub CLI의 대화형 로그인을 완료합니다. gh api 명령에는 에이전트의 로그인 이름이 나와야 합니다. 두 변수를 해제하면 환경 변수의 인증 정보가 저장된 로그인보다 우선하는 문제를 막을 수 있습니다.

별도의 gh auth setup-git 단계는 Git이 GitHub CLI를 인증 정보 도우미로 사용하도록 설정합니다. 준비 작업과 브랜치 푸시에서 Git을 직접 실행하므로 필요한 단계입니다.

문서의 GitHub CLI 복제 구문에 따라 로컬 사본을 만듭니다.

read -r -p "Repository (owner/name): " TARGET_REPOSITORY
mkdir -p "$HOME/src"
gh repo clone "$TARGET_REPOSITORY" "$HOME/src/superagent-target"

이어서 gh api와 별개로 HTTPS 접근을 확인합니다.

GIT_TERMINAL_PROMPT=0 git ls-remote \
  "https://github.com/$TARGET_REPOSITORY.git" HEAD

GIT_TERMINAL_PROMPT=0 git -C "$HOME/src/superagent-target" push --dry-run \
  "https://github.com/$TARGET_REPOSITORY.git" \
  HEAD:refs/heads/agent-auth-check

git ls-remote는 원격 저장소의 HEAD를 반환해야 합니다. 공개 저장소라면 인증하지 않아도 이 읽기 작업이 성공할 수 있습니다. push --dry-run 검사는 원격 참조를 갱신하지 않고 푸시 연결을 시험합니다.

두 명령이 모두 성공해야 합니다. 다만 최종 결과 전달 여부는 이후 실제 PR을 만들 때 브랜치가 정상적으로 푸시되는지 확인해 판단합니다.

이 예제는 운영체제 계정 전체가 에이전트 전용이므로 gh를 직접 사용합니다. 여러 GitHub 계정으로 로그인한 개인 계정의 설정을 재사용하지 않습니다.

전용 Harness 프로필 설치

배포 가이드에서 고정한 Harness 버전 0.2.1-rc.3을 사용합니다. 확장 패키지의 매니페스트는 engines.dsh가 ^0.2.1-alpha.2를 충족하도록 요구합니다.

첫 dsh 명령을 실행하기 전에 DSH_HOME을 설정합니다. 해당 버전의 CLI 참조는 이름이 있는 프로필을 $DSH_HOME/profiles/<name> 아래에 배치합니다. 이번 시험에서는 $HOME/.dsh를 저장 위치로 명시적으로 선택합니다.

다음 Bash 명령은 새로 설치할 때만 사용합니다.

export DSH_HOME="$HOME/.dsh"

npm install -g @deepseek-ai/dsh@0.2.1-rc.3
git clone https://github.com/deepseek-ai/dsh-superagent-prototype.git
cd dsh-superagent-prototype
pnpm install
pnpm build
dsh superagent --from-default-profile web --dump-config > /dev/null
dsh plugin --profile superagent add "link:$PWD"

기존 설치 환경에서 프로필 생성 명령을 다시 실행하지 않습니다. 이 명령은 프로필을 교체하고 해당 cordis.patch.yml을 삭제합니다. 업데이트할 때는 배포 가이드의 업그레이드 절차를 따릅니다.

머신 설정을 기록하기 전에 프로필 매니페스트가 있는지 확인합니다. 같은 Bash 셸에서 계속 진행합니다.

test -f "$DSH_HOME/profiles/superagent/package.json" || exit 1

cat > "$DSH_HOME/profiles/superagent/cordis.patch.yml" <<EOF
- id: webserver
  config:
    host: 127.0.0.1
    port: 3082
- id: dsh-superagent
  config:
    stateDir: "$DSH_HOME/state/superagent"
EOF

if tmux list-sessions >/dev/null 2>&1; then
  tmux set-environment -g DSH_HOME "$DSH_HOME"
  if tmux has-session -t '=dsh-superagent' 2>/dev/null; then
    tmux set-environment -t '=dsh-superagent' DSH_HOME "$DSH_HOME"
  fi
fi

scripts/dsh-superagent start
scripts/dsh-superagent status

서비스 스크립트는 tmux를 통해 dsh --profile superagent를 실행합니다. 새 tmux 서버는 내보낸 환경 변수를 상속합니다. 위 코드는 이미 실행 중인 서버나 세션의 tmux 환경도 갱신합니다.

서버 머신의 브라우저에서 http://127.0.0.1:3082를 엽니다. Harness 설정에서 Open configuration file을 선택하면 위의 superagent/cordis.patch.yml 경로가 열려야 합니다. 다른 경로를 가리키면 중단합니다. 제공업체 설정을 추가한 뒤에는 이 패치 파일을 다시 덮어쓰지 않습니다.

사이드바에서 Superagent를 선택합니다. 저장소와 계정 설정을 완료하기 전까지 초기 설정 경고가 나오는 것은 정상입니다. 요청 수신을 설정하기 전에 아래 모델 선택 절차를 먼저 완료합니다.

요청 수신과 Ticket별 작업 트리 설정

Superagent → Settings에서 문서에 명시된 설정 그룹을 사용합니다.

Sources → GitHub에서 저장소를 해당 owner/name으로, 에이전트 CLI를 gh로 설정합니다. 모든 Issues, 풀 리퀘스트, 댓글, 기본 브랜치의 CI를 수신하는 스위치는 끈 상태로 둡니다. Feishu도 비활성화 상태를 유지합니다.

Eval → On each Source → GitHub의 GitHub accounts that may originate work에는 요청자로 사용할 개인 로그인 이름만 남깁니다. 다른 항목은 삭제하고 봇 목록은 비워 둡니다. 목록에 없는 사람에 관한 모든 수락 셀을 ignore로 설정합니다. 에이전트를 직접 부르는 사람에 관한 셀도 포함합니다. 수락 모드를 observe로 지정해 저장합니다.

목록에 없는 사람의 기본값은 수락 매트릭스에 정의되어 있습니다. 이 설정은 새 작업 요청을 제한합니다. 구독 중인 대화의 메시지가 기존 Ticket에 맥락으로 전달되는 것까지 막지는 않습니다. 시험 대화에는 요청자와 에이전트만 참여하도록 제한합니다.

Execution에서는 시험용 동시 실행 수를 1로 설정합니다. 디렉터리 루트는 기본값을 유지합니다. 다음 코드를 준비 명령 필드에 붙여 넣습니다. 실행에는 sh를 사용하며, 이 구문은 Bash에서도 유효합니다.

git -C "$HOME/src/superagent-target" fetch --no-tags \
  "https://github.com/$DSH_SUPERAGENT_GITHUB_REPOSITORY.git" \
  "${DSH_SUPERAGENT_GITHUB_PR_HEAD:-HEAD}:refs/dsh-superagent/$DSH_SUPERAGENT_TICKET" &&
git -C "$HOME/src/superagent-target" worktree add \
  -b "agent/$DSH_SUPERAGENT_NAME" \
  "$DSH_SUPERAGENT_DIR" \
  "refs/dsh-superagent/$DSH_SUPERAGENT_TICKET"

배포 가이드의 작업 트리 예제를 앞서 만든 로컬 사본에 맞춘 명령입니다. 해당 리비전을 가져온 다음 Ticket의 브랜치와 작업 사본을 만듭니다. 준비 명령이 없으면 Worker는 빈 디렉터리에서 시작합니다.

Prompts에서는 커밋 작성자 정보와 에이전트가 관여했음을 알리는 문구를 설정합니다. 병합은 사람이 하도록 요구하고 별도의 병합 계정은 제공하지 않습니다. 프롬프트 지시는 행동을 안내할 뿐, 저장소 보호 규칙을 강제하지 않습니다.

다른 모델을 선택하는 방법

DeepSeek Harness에 설정한 제공업체를 통해 다른 모델을 사용할 수 있습니다. dsh-v0.2.1-rc.3 태그의 제공업체 가이드에 설치된 버전의 다음 절차가 나와 있습니다.

Harness의 Settings → Models를 엽니다. DeepSeek 카드에 API 키를 입력해 저장하거나, Add model provider에서 다른 지원 제공업체를 선택합니다. 인증 정보는 GitHub 대화가 아니라 이 로컬 화면에 입력합니다.

Custom model API에는 소문자 Provider ID, 기본 URL, 일치하는 API 프로토콜, 인증 정보, 최소 하나의 모델을 지정합니다. 값은 제공업체 문서를 따릅니다. 제공업체 설정을 저장했다고 해서 모델이 필요한 도구 호출을 수행할 수 있다고 확인된 것은 아닙니다.

다음으로 해당 버전의 웹 UI 가이드에 따라 Choose workspace에서 $HOME/src/superagent-target을 추가하고 선택합니다. 일반 세션을 시작하고 모델 선택기에서 설정한 모델을 고릅니다. 이 선택은 새 세션의 기본값이 됩니다.

또 다른 새 세션을 열고, 요청을 보내기 전에 같은 제공업체와 모델이 표시되는지 확인합니다. 수정 없이 README.md를 읽고 첫 번째 제목을 반환하도록 요청합니다. 응답을 실제 파일과 비교합니다. 이 시험에는 두 관리용 dsh-superagent-* 프리셋 중 어느 것도 사용하지 않습니다.

그다음 확인한 제공업체와 모델을 Superagent → Settings → Eval 및 Execution에서 명시적으로 선택합니다. Eval은 Router와 평가에 사용할 모델을, Execution은 Worker 모델을 지정합니다. 이번 시험에서는 확인되지 않은 기본값에 의존하지 않습니다. 프로필의 기본 모델을 확인한 뒤에만 이 선택 항목을 비워 둘 수 있습니다.

Executor의 모델 선택은 세션을 만들 때 적용됩니다. 기존 Worker 세션은 원래 모델을 유지하고, Retry도 같은 세션을 재사용합니다. 나중에 모델을 변경하면 새 Ticket으로 확인합니다.

요청 한 건으로 검증하고 실패 지점 확인

코드 변경을 요청하기 전에 GitHub 요청부터 응답까지 전체 흐름을 확인합니다. 패널이 실행된다는 사실만으로 권한 확인, 준비 작업, 모델 호출이 모두 정상이라고 판단할 수는 없습니다.

먼저 scripts/dsh-superagent status를 다시 실행합니다. 종료 코드가 0이고 설정 문제가 없어야 합니다. 허용된 개인 계정으로 issue에 새 댓글을 작성합니다. @AGENT_LOGIN은 에이전트의 로그인 이름으로 바꿉니다.

@AGENT_LOGIN Read README.md and reply here with its first heading.
Do not edit files, push a branch, or open a pull request.

배포 가이드의 시험 절차에 따르면 생성된 Ticket은 Overview에 나타납니다. 원래 GitHub 대화에 올바른 제목을 담은 응답이 도착했는지 확인합니다.

이 검증이 성공하면 작은 문서 수정과 사람이 검토할 풀 리퀘스트 생성을 요청합니다. 브랜치가 실제로 푸시되었는지, PR이 에이전트 계정으로 생성되었는지, diff가 요청 범위 안에 있는지 확인합니다. 이는 환경의 수용 기준이지, 모델이 반드시 낼 결과를 보장하는 설명이 아닙니다.

Ticket이 보이지 않으면 허용한 로그인 이름, 수락 셀, 저장소, GitHub 소스의 상태를 확인합니다. 그다음 에이전트를 멘션하는 새 댓글을 작성합니다.

서비스 스크립트는 프로세스나 실행 환경 문제에 1, 구성 요소 오류에 2, 미완료 설정에 3을 반환합니다. 1은 재시작이 도움이 될 수 있습니다. 2나 3은 표시된 원인을 해결합니다.

일시적인 모델 또는 네트워크 장애에는 실행 가이드에 따라 대기 시간을 늘리면서 3회 재시도합니다. HTTP 408, 429, 5xx가 여기에 포함됩니다. 준비 명령의 실패는 이 자동 재시도 대상에서 제외됩니다.

준비 명령 실패 후 복구

Retry를 선택하기 전에 기록된 준비 오류와 Ticket 디렉터리를 살펴봅니다. 시작 구현은 해당 디렉터리가 없을 때만 준비 작업을 실행합니다. 디렉터리가 이미 있으면 작업이 미완료 상태여도 준비된 것으로 취급합니다.

디렉터리가 없다면 인증 정보나 준비 명령의 문제를 수정한 뒤 Retry를 선택합니다. 새 실행에서 준비 작업을 다시 시도합니다.

디렉터리가 있다면 Ticket 상세 화면에서 경로를 복사하고 Bash로 검사합니다.

read -r -p "Ticket directory (absolute path): " TICKET_DIR
git -C "$TICKET_DIR" rev-parse --show-toplevel
git -C "$TICKET_DIR" status --short --branch

출력된 최상위 디렉터리는 상위의 다른 작업 사본이 아니라 Ticket 디렉터리여야 합니다. 브랜치와 작업 트리 상태, 필요한 파일, 이전에 실패한 모든 준비 단계를 확인합니다.

기존 디렉터리에서는 준비를 완료하고 검증한 뒤에만 Retry를 실행합니다. Retry는 디렉터리를 다시 만들지 않습니다. 불완전한 작업 사본을 안전하게 복원하기 어렵다면 보존한 채 해당 Ticket을 중단하고 명령을 수정합니다. 그런 다음 새 issue로 작업을 요청합니다. 계속하기 전에 새 Ticket이 새 디렉터리를 사용하는지 확인합니다.

Ticket이 실패한 뒤에는 CI와 봇 메시지가 Worker를 다시 실행하지 않습니다. 사람이 개입해야 합니다. 시험을 마치면 서비스를 중지합니다.

scripts/dsh-superagent stop

계속 운영할지 판단하는 기준

요청 분배 결과와 제출된 변경이 운영에 드는 수고를 정당화할 때만 프로토타입을 계속 실행합니다. 처음에는 범위를 좁게 유지합니다. 유용한 결과와 제공업체 사용량을 측정한 뒤 동시 실행 수를 늘립니다.

모델 가격만 보지 말고 승인된 변경 한 건당 비용을 비교합니다. 요청 분배, 평가, Worker 호출, 장애 복구까지 시험 예산에 포함합니다. 코딩 에이전트의 작업당 비용 가이드는 모델과 실행 환경을 함께 비교하는 방법을 제공합니다.

내부 시연을 이 공개 코드의 동작과 동일하게 보지 않습니다. 저장소는 설계 글의 일부 내용이 구현되지 않았다고 경고합니다. 자체 검증으로 사용 범위를 넓혀도 된다고 판단할 때까지 환경 격리와 사람의 검토를 유지합니다.