dsh-superagent란?
dsh-superagent는 하나의 GitHub 저장소에서 작업하도록 설계된 선제적 코딩 에이전트입니다. DeepSeek Harness용 번들로 배포되며 GitHub와 선택적으로 Feishu에서 요청을 수신합니다.
승인된 사용자가 작업을 요청하면 시스템은 작업 항목을 열고, 전용 에이전트 세션과 디렉터리를 생성한 뒤 작업을 완료하고 원래 대화에 답변합니다. 결과에는 풀 리퀘스트가 포함될 수 있습니다. 웹 패널에서는 사람의 확인이나 조치가 필요한 항목을 보여 줍니다.
dsh-superagent는 참고용 연구 프로토타입이며, 공식 DeepSeek 제품이나 프로덕션 환경에 바로 사용할 수 있는 시스템이 아닙니다.
공개된 저장소는 팀의 내부 버전 및 Exploring Super-agent Design: Towards a More Autonomous Agent System에서 논의된 구현과 다릅니다. 해당 글의 일부 아이디어는 향후 방향을 설명하며 이 프로토타입에는 구현되어 있지 않습니다.
핵심 설계 원칙
이 프로젝트는 사람의 주의를 최대한 적게 요구하면서 최대한 많은 가치를 제공하는 것을 목표로 합니다. 팀 전체를 위한 에이전트 역시 팀의 주의를 소모할 수 있으므로 dsh-superagent는 다음 두 가지 중요한 제약을 따릅니다.
- 누군가 행동을 요청하거나 팀에서 정의한 규칙이 해당 행동을 허용할 때만 행동합니다.
- 누군가 조치를 취해야 하거나 완료된 결과를 활용할 수 있을 때만 메시지를 보냅니다.
에이전트를 배포하기 전에 철학 문서를 읽어 보세요. 이 문서는 운영 원칙과 시스템을 실행하는 사람의 책임을 설명합니다.
주요 기능
- 단일 저장소 집중: 각 배포는 하나의 GitHub 저장소에서 작동합니다.
- GitHub 통합: 에이전트는 GitHub에서 발생한 승인된 요청을 수신합니다.
- 선택적 Feishu 통합: 팀은 Feishu를 요청 소스로 사용할 수도 있습니다.
- 작업 항목 추적: 승인된 요청은 작업 항목으로 전환됩니다.
- 격리된 실행: 각 작업은 자체 에이전트 세션과 디렉터리에서 실행됩니다.
- 대화 인식 답변: 결과는 요청이 시작된 대화로 반환됩니다.
- 사람의 조치가 필요한 작업 패널: 웹 패널에서 사람의 개입이 필요한 작업을 확인할 수 있습니다.
- 규칙에 따른 동작: 에이전트는 요청에 응답하거나 팀의 명시적 규칙이 있을 때만 행동합니다.
설치 전 확인 사항
이 저장소를 연구용 코드로 취급하세요. 버그, 일관되지 않은 코딩 스타일 또는 사용자의 환경에 적합하지 않은 엔지니어링 결정이 포함되어 있을 수 있습니다. 실제로 의존하기 전에 구현을 검토하고 필요에 맞게 수정하세요.
설정 단계가 많으므로 프로젝트에서는 필요한 구성을 수동으로 추측하기보다 코딩 에이전트와 협력하여 설정을 완료할 것을 권장합니다.
안내에 따른 설치 및 설정
1단계: 코딩 에이전트로 저장소 열기
복제했거나 체크아웃한 저장소를 코딩 에이전트에서 사용할 수 있도록 하세요. 그런 다음 프로젝트에서 권장하는 설정 지침을 제공하세요.
이 저장소의 SETUP.md를 읽고 저와 함께 dsh-superagent를 설정해 주세요.코딩 에이전트는 SETUP.md를 기준 문서로 따라야 합니다.
2단계: 설정 질문에 답하기
설정 과정에서는 한 번에 하나씩 짧은 질문을 하도록 설계되어 있습니다. 저장소, 통합 기능 및 환경에 대해 요청된 정보를 제공하세요. 에이전트의 도움을 받는 과정이라는 이유만으로 검토 단계를 건너뛰지 마세요.
3단계: 전체 계획 검토하기
필요한 정보를 수집하면 코딩 에이전트가 전체 계획을 한 번 제시합니다. 설치 또는 구성 변경을 허용하기 전에 계획을 신중하게 검토하세요. 특히 계획이 에이전트로 관리하려는 저장소 및 활성화하려는 요청 소스와 일치하는지 확인하세요.
4단계: 에이전트가 프로젝트를 설치하고 구성하도록 하기
계획을 승인하면 코딩 에이전트가 SETUP.md에 따라 시스템을 설치하고 구성합니다. README에서는 자세한 설정 절차를 해당 파일에 위임하므로 문서화되지 않은 명령에 의존하지 말고 파일의 최신 지침을 따르세요.
5단계: 프로젝트 검증하기
개발 검증을 위해 다음 명령을 실행하세요.
pnpm check이 명령은 타입 검사, 테스트 및 빌드를 실행합니다. 성공적으로 완료되면 프로젝트의 타입, 테스트 모음 및 빌드 프로세스를 종합적으로 확인할 수 있습니다.
에이전트를 운영하기 전에 문서 이해하기
번호가 매겨진 문서는 의도적으로 누적되는 방식으로 구성되어 있습니다. 각 문서는 이전 문서에서 소개한 내용만을 전제로 하므로 순서대로 읽으세요.
- 000 철학: 주의를 최소화하는 운영 원칙과 운영자의 책임을 이해합니다.
- 001 도메인 모델: 프로젝트의 핵심 개념과 개념 간 관계를 배웁니다.
- 002 권한 부여: 에이전트에게 작업을 수행하도록 요청할 수 있는 사람을 정합니다.
- 003 실행: 승인된 작업이 실행되는 방식을 이해합니다.
- 004 프롬프트: 에이전트의 동작을 안내하는 프롬프트를 검토합니다.
- 005 패널: 웹 패널이 사람의 주의가 필요한 항목을 표시하는 방식을 배웁니다.
- 006 배포: 수동 설정, 구성, 업그레이드 및 문제 해결 지침을 따릅니다.
- 007 아키텍처: 시스템의 기술적 구조를 살펴봅니다.
- 008 쿡북: Source를 추가하는 방법을 배웁니다.
기본 사용법
권한이 있는 요청 제출
설정이 끝나면 권한이 있는 사용자는 GitHub를 통해 또는 선택적 통합이 활성화된 경우 Feishu를 통해 에이전트에게 저장소 작업을 요청할 수 있습니다. 일반적인 요청에는 원하는 저장소 변경 사항과 관련 승인 기준을 명시해야 합니다.
예를 들어 권한이 있는 사용자는 에이전트에게 저장소 이슈를 조사하고, 적절한 코드를 변경한 뒤 결과를 반환하도록 요청할 수 있습니다. 정확한 요청 방식과 허용된 사용자는 구성한 Source와 권한 부여 규칙에 따라 달라집니다.
에이전트가 작업 항목을 생성하고 실행하도록 하기
요청이 승인되면 dsh-superagent는 작업 항목을 열고 자체 에이전트 세션과 디렉터리에서 작업을 수행합니다. 이 실행 모델은 작업의 작업 컨텍스트를 분리된 상태로 유지합니다.
컨텍스트 안에서 결과 받기
에이전트는 사용자가 별도의 채널에서 결과를 찾도록 하지 않고 원래 대화에서 답변합니다. 수행한 작업에 따라 응답에 풀 리퀘스트가 포함될 수 있습니다.
사람의 후속 조치에 패널 사용
사람의 조치가 필요한 작업은 웹 패널에서 확인합니다. 패널은 모든 내부 단계에 대해 불필요한 커뮤니케이션을 생성하는 대신 사람의 조치가 필요한 항목을 표시하여 프로젝트의 주의 관리 목표를 지원합니다.
권한 부여 및 안전한 운영
권한 부여는 이 설계의 핵심입니다. 팀의 저장소 전반에서 능동적으로 작업할 수 있는 에이전트가 임의의 요청을 받아들여서는 안 됩니다. 권한 부여 문서를 사용하여 작업을 시작할 수 있는 사람과 조건을 정의합니다.
- 요청자 제한: 의도한 사람이나 시스템만 실행 가능한 요청을 생성하도록 허용합니다.
- 팀 규칙 검토: 자동화된 작업이 팀에서 명시적으로 작성한 규칙에 따라서만 실행되는지 확인합니다.
- 사람의 검토 유지: 에이전트가 생성한 변경 사항을 검사와 조정이 필요할 수 있는 작업으로 취급합니다.
- 사용 범위 확대 전 테스트: 개발 변경 후
pnpm check를 실행하고 환경에서 동작을 검증합니다.
고급 팁
수동 작업에는 배포 가이드 사용
설정을 수동으로 수행하거나, 구성을 변경하거나, 프로젝트를 업그레이드하거나, 문제를 해결해야 한다면 006 배포를 참조합니다. README는 이 문서를 해당 운영 절차에 대한 자세한 자료로 안내합니다.
동작을 조정할 때 프롬프트 검토
에이전트가 작업을 해석하거나 실행하는 방식을 변경하기 전에 004 프롬프트를 읽습니다. 프롬프트 변경은 에이전트가 언제 커뮤니케이션하는지, 작업에 어떻게 접근하는지, 프로젝트의 주의 최소화 철학을 얼마나 충실히 따르는지에 영향을 줄 수 있습니다.
작업 격리를 수정하기 전에 실행 방식 검토
시스템은 각 작업 항목에 자체 에이전트 세션과 디렉터리를 제공합니다. 이 동작을 변경하기 전에 003 실행과 007 아키텍처를 검토하여 변경 사항이 프로젝트의 실행 모델 및 시스템 모델과 일관되도록 합니다.
새 Source를 신중하게 추가
Source는 시스템이 작업을 수신할 수 있게 하는 통합입니다. 제공된 GitHub 및 선택적 Feishu 경로 외에 Source를 추가하려면 008 쿡북을 따릅니다. 새로운 요청 채널을 도입할 때 권한 부여 모델을 우회하지 마십시오.
유용한 침묵에 최적화
시스템을 조정할 때는 작업의 가치와 알림이 발생시키는 주의 비용을 모두 평가합니다. 사람이 조치해야 하거나 활용 가능한 결과가 준비된 경우에 커뮤니케이션하는 것을 우선합니다. 이는 확장 기능과 운영 규칙을 프로젝트의 핵심 철학에 맞춥니다.
개발 워크플로
코드를 수정한 후 프로젝트의 통합 검증 명령을 사용합니다.
pnpm check이 명령은 타입 검사, 테스트 및 빌드를 실행하므로 변경 사항을 공유하거나 배포하기 전에 정기적으로 확인해야 합니다. 이 명령을 통과했다고 해서 연구용 프로토타입이 프로덕션에 바로 사용할 수 있는 상태가 되는 것은 아닙니다. 여전히 동작, 보안 가정, 권한 부여 및 환경에 대한 적합성을 검토해야 합니다.
결론
dsh-superagent는 사람의 주의에 대한 요구를 최소화하면서 단일 GitHub 저장소의 작업을 위임하기 위한 연구 지향적 모델을 제공합니다. 안내된 SETUP.md 워크플로로 시작하고, 번호가 매겨진 문서를 순서대로 읽고, 권한 부여를 보수적으로 구성하고, pnpm check로 변경 사항을 검증한 다음, 패널을 사용하여 실제로 필요한 곳에 사람의 노력을 집중하십시오.