dsh-superagent-prototype

1. 프로젝트 개요

dsh-superagent-prototype은 단일 GitHub 저장소에 대한 승인된 요청을 추적 가능한 작업으로 전환하고, 각 작업을 전용 DeepSeek Harness 세션과 디렉터리에서 실행한 뒤 결과를 원래 대화로 반환하는 오픈소스 TypeScript 코딩 에이전트 프로토타입입니다. 저장소 README

2. 배경 및 포지셔닝

이 프로젝트는 DeepSeek Harness 팀의 일상적인 개발 작업에서 출발했습니다. 그 사명은 팀 동료의 주의를 최소한으로 요구하면서 유용한 엔지니어링 결과를 제공하는 것입니다. 작업은 명시적인 요청이나 문서화된 팀 규칙을 통해 시작되며, 커뮤니케이션은 실행 가능한 질문과 사용 가능한 결과에 집중합니다. 설계 철학

이 프로젝트의 두드러진 강조점은 지속적인 팀 워크플로입니다. 요청, 승인, 실행, 후속 조치, 전달이 하나의 저장소를 중심으로 함께 모델링됩니다. 따라서 대화형 코딩 세션을 넘어서는 저장소 에이전트를 탐구하는 개발자에게 관련이 있지만, 이 프로젝트는 비교 성능 벤치마크를 공개하지 않습니다. 도메인 모델

유지 관리자들은 이 프로젝트를 공식 DeepSeek 제품이나 프로덕션 준비가 된 서비스가 아니라 연구용 코드라고 명시적으로 설명합니다. 공개 프로토타입은 내부 구현 및 함께 제공되는 연구 논문과 다르며, 해당 논문에서 논의된 일부 아이디어는 향후 방향으로 남아 있습니다. 프로젝트 상태

3. 기능 분류

아래 수치는 각 범주에 나열된 특정 기능이나 리소스를 설명하는 것이지, 공식적인 총 기능 수를 의미하지 않습니다.

협업 및 이벤트 수집

🔌 저장소 및 채팅 입력 — 대표 기능 4가지

• 구성된 저장소에 대한 GitHub 알림 수집.
• 선택적 Feishu/Lark 봇 통합.
• 기존 작업에 후속 맥락을 전달하는 스레드 구독.
• 요청과 연결된 대화에 대한 채널 기반 응답.

목적: 팀 대화를 실행 가능한 작업에 연결하면서 작업을 계속하는 데 필요한 맥락을 보존합니다. 도메인 모델

승인 및 능동적 작업

🛡️ 정책 제어 — 대표 기능 5가지

• 각 소스에 대한 허용 발신자 목록.
• 범위, 발신자 멤버십, 에이전트 호출 여부에 기반한 승인 테이블.
• 추론된 능동적 요청에 대한 문서화된 규칙.
• 세 가지 수용 모드: 꺼짐, 관찰, 자동.
• 작업이 수용된 권한을 기록하는 티켓 위임.

목적: 작업 시작 권한과 단순히 맥락을 제공하는 메시지를 구분합니다. 승인 가이드

작업 실행

⚙️ 실행 수명 주기 — 대표 기능 4가지

• 각 티켓에 대한 전용 실행기 세션.
• Git 워크트리를 포함한 작업 디렉터리용 구성 가능한 준비 명령.
• 작업자 동시성 및 모델 구성.
• 중단된 할당의 복구 및 재시도 처리.

목적: 실행 차례와 재시작 전반에 걸쳐 작업 항목을 독립적으로 추적하고 관리할 수 있게 유지합니다. 실행 가이드

인간 감독

📊 운영자 패널 — 탭 6개, 대표 예시 5가지

• 개요는 인간의 주의가 필요한 작업을 강조합니다.
• 소스는 통합 상태와 전달 문제를 보여줍니다.
• 트리거는 스레드, 수신 이벤트, 구독을 표시합니다.
• 평가는 결정, 사유, 일치된 규칙을 기록합니다.
• 실행은 티켓 상태, 작업자 활동, 개입 제어를 노출합니다.

목적: 미결 결정과 워크플로 이력을 가시화합니다. 여섯 번째 탭인 설정은 소스, 평가, 실행, 프롬프트, 배포를 구성합니다. 패널 가이드

사용자 정의 및 확장

🧩 확장 리소스 — 대표 리소스 4가지

• 편집 가능한 팀 프롬프트 섹션.
• 번들로 제공되는 GitHub 및 Feishu 스킬.
• 예시 DeepSeek Harness 프로필 구성.
• 추가 소스 플러그인 구현을 위한 쿡북.

목적: 팀이 지침과 이벤트 통합을 자체 저장소 워크플로에 맞게 조정할 수 있게 합니다. 프롬프트 가이드, 소스 쿡북

4. 주요 하이라이트

• 능동적 실행을 활성화하기 전에 관찰하세요. 기본 관찰 모드는 추론된 작업이 수용될지 여부를 작업을 생성하지 않고 기록하여, 운영자가 먼저 자신의 규칙을 평가할 수 있는 방법을 제공합니다. 승인
• 요청에서 결과까지 추적 가능한 작업. 트리거, 결정, 티켓, 할당은 에이전트가 무엇을 수용했고 어떻게 진행되었는지 이해하기 위한 공통 어휘를 제공합니다. 도메인 모델
• 분리된 실행 컨텍스트. 각 티켓은 자체 세션과 작업 디렉터리를 가지며, Git 워크트리는 독립적인 저장소 체크아웃을 제공할 수 있습니다. 이는 워크플로 경계이지 운영체제 보안 샌드박스가 아닙니다. 실행, 배포
• 주의 집중형 감독. 패널은 차단된 작업과 실행 가능한 문제를 우선시하며, 필요할 때 상세 이력을 제공합니다. 패널
• 확장 가능한 이벤트 소스. 쿡북은 이벤트 변환, 응답 전달, 승인 통합, 소스 수명 주기 동작을 설명합니다. 쿡북

5. 역할별 사용 사례

다음은 문서화된 워크플로의 잠재적 응용 사례이지, 특화된 내장 기능에 대한 주장이 아닙니다.

역할	실용적 활용
일반 개발자	저장소 대화에서 범위가 정해진 버그 수정이나 기능 작업을 위임하고 결과 변경 사항이나 풀 리퀘스트를 검토합니다.
DevOps/SRE	전용 에이전트 프로필을 운영하고, 상태를 모니터링하며, 규칙으로 승인된 저장소 CI 이벤트 응답을 실험합니다.
보안 엔지니어	발신자 권한, 실행 자격 증명, 런타임 격리를 검토하고, 일반 저장소 요청을 통해 범위가 정해진 교정 작업을 할당합니다.
데이터/연구 과학자	이벤트 라우팅, 정책 평가, 작업 복구를 연구하거나 연구 저장소에서 코드 변경을 위임합니다.
프로젝트 관리자	결정을 기다리는 티켓을 검토하고, 요청된 결과를 명확히 하며, 감독 패널을 통해 작업을 추적합니다.

기반 메커니즘은 도메인 모델, 패널 가이드, 배포 가이드에 문서화되어 있습니다.

6. 시작하기

경로 1: 필요한 것 찾기

README로 시작한 다음, 철학부터 소스 쿡북까지 9개의 번호가 매겨진 문서를 순서대로 읽으세요. 구현을 탐색하려면 아키텍처를, 운영 세부 사항은 배포를 사용하세요.

경로 2: 설치 및 통합

권장 시작점은 에이전트 지원 SETUP.md입니다. 코딩 에이전트에게 다음 지시를 내리세요:

Read SETUP.md in this repository and set up dsh-superagent with me.

사전 요구 사항에는 22.x 라인의 Node.js 22.19+ 또는 Node.js 24+, pnpm, Git 2.32+, Python 3.8+, tmux, GitHub CLI 2.48+, github.com의 저장소, DeepSeek Harness에 구성된 모델 제공자가 포함됩니다. Feishu는 추가로 봇 설정과 lark-cli가 필요합니다.

기존 superagent 프로필이 없는 새 설치의 경우, 배포 가이드는 저장소 URL을 채워 넣은 다음 순서를 제공합니다:

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

프로필 생성 명령은 기존 프로필을 대체하므로 업그레이드에 재사용하지 마세요. 시작하기 전에 나머지 배포 단계를 따르세요: 전용 에이전트 GitHub 계정과 CLI 자격 증명을 구성하고, 예시 프로필 구성을 채우고, 소스, 정책, 실행, 팀 프롬프트를 구성하세요. 설치 명령만으로는 설정이 완료되지 않습니다.

경로 3: 기여하기

동작을 변경하기 전에 아키텍처 가이드를 읽으세요. 통합의 경우 문서화 및 테스트 요구 사항을 포함한 소스 확장 쿡북을 따르세요.

개발 체크아웃에서 저장소의 통합 타입 검사, 테스트, 빌드를 실행하세요:

pnpm check

검토된 트리에는 독립적인 CONTRIBUTING.md가 포함되어 있지 않습니다. 제안된 변경 사항에는 문서화된 개발 워크플로와 GitHub의 풀 리퀘스트 인터페이스를 사용하세요.

7. 프로젝트 구조

dsh-superagent-prototype/
├── README.md                  # Overview and documentation index
├── SETUP.md                   # Agent-assisted setup workflow
├── LICENSE                    # MIT license
├── docs/                      # Nine ordered design and operation documents
├── examples/
│   └── profile.cordis.patch.yml
├── prompts/                   # Agent instructions and team sections
├── skills/                    # GitHub and Feishu skills
├── locale/                    # English and Chinese interface resources
├── scripts/
│   └── dsh-superagent          # Service lifecycle helper
├── src/
│   ├── index.ts               # Bundle entry point
│   ├── core/                  # Domain engine and lifecycle rules
│   ├── app/                   # Runtime, storage, API, and orchestration
│   ├── executor/              # Harness execution adapter
│   ├── sources/               # GitHub, Feishu, and Source infrastructure
│   └── client/                # Web supervision interface
├── tests/                     # Domain, integration, and interface tests
├── cordis.patch.yml           # Bundle plugin configuration
└── package.json               # Dependencies, compatibility, and scripts

아키텍처는 도메인 규칙을 실행 및 통합 어댑터와 분리하며, 클라이언트는 운영자용 패널을 제공합니다. 소스 트리와 아키텍처 가이드를 참고하세요.

8. 관련 생태계

• DeepSeek Harness: 에이전트 세션, 도구, 모델 통합, 웹 인터페이스를 제공하는 호스트 런타임입니다. 공식 홈페이지는 런타임 저장소와 개발자 문서로 연결되며, 일반 목적 기능을 이 프로토타입이 구현한 기능과 혼동해서는 안 됩니다.
• Cordis: Harness 생태계와 이 번들의 구성에서 사용되는 플러그인 아키텍처입니다. 프로젝트의 패키지 매니페스트는 Harness 및 Cordis 호환성 요구 사항을 나열합니다.
• GitHub 및 GitHub CLI: 에이전트 신원과 저장소 운영에 사용되는 저장소 협업 플랫폼 및 명령 인터페이스입니다.
• Feishu/Lark 및 lark-cli: 요청 수신과 응답 반환을 위한 선택적 채팅 통합입니다. 계정 설정은 배포에 문서화되어 있습니다.
• Git 워크트리 및 tmux: 배포 워크플로에 나온 대로 작업 체크아웃 준비와 서비스 프로세스 관리를 위한 보완 도구입니다.

9. 라이선스

저장소는 MIT 라이선스를 사용하며, 저작권은 DeepSeek Harness 팀에 있습니다.

• ✅ 상업적 및 사적 사용, 수정, 복사, 배포, 재라이선스, 사본 판매가 허용됩니다.
• ✅ 필수 고지 사항이 유지되는 한, 수정된 버전을 원하는 조건으로 배포할 수 있습니다.
• ❌ 소프트웨어 사본이나 상당 부분에서 저작권 및 허가 고지를 생략할 수 없습니다.
• ℹ️ 소프트웨어는 보증 없이 제공되며, 라이선스는 저자 책임을 면제합니다.
• ℹ️ 프로토타입의 라이선스는 외부 서비스, 모델 제공자, 의존성의 조건을 대체하지 않습니다.

10. 자주 묻는 질문

Q: 이것은 공식적이고 프로덕션 준비가 된 DeepSeek 서비스인가요?

A: 아닙니다. README는 이를 참고용 연구 프로토타입으로 명시합니다. 채택하기 전에 구현을 검토하고 조정하세요.

Q: 능동 모드는 에이전트가 임의의 작업을 시작한다는 뜻인가요?

A: 추론된 작업에는 구성된 승인 경로, 평가, 일치하는 문서화된 규칙, 자동 모드가 필요합니다. 관찰 모드는 실행하지 않고 잠재적 수용을 기록하며, 명시적 요청은 세 가지 모드 모두에서 사용할 수 있습니다. 승인을 참고하세요.

Q: 하나의 인스턴스가 여러 저장소나 GitHub Enterprise Server를 관리할 수 있나요?

A: 문서화된 범위는 인스턴스당 하나의 GitHub 저장소이며, 배포에는 github.com이 필요합니다. GitHub Enterprise Server는 명시적으로 지원되지 않습니다. 배포를 참고하세요.

Q: 작업자 디렉터리는 안전한 샌드박스인가요?

A: 아닙니다. 관리되는 세션은 운영자의 운영체제 사용자로서 전체 액세스 권한으로 실행되며, 자격 증명 래퍼는 프로세스를 격리하지 않고 계정을 선택합니다. 배포 가이드는 격리가 필요할 때 에이전트 자격 증명만 포함하는 전용 운영체제 계정을 권장합니다. 권한 및 격리를 참고하세요.

Q: Feishu가 필수인가요, 다른 통합을 추가할 수 있나요?

A: Feishu는 선택 사항입니다. GitHub는 핵심 저장소 통합이며, 쿡북은 정책, 맥락, 전달 동작을 포함한 또 다른 소스를 구현하는 방법을 설명합니다.

11. 빠른 링크

• 프로젝트 저장소
• README 및 프로젝트 상태
• 공식 프로젝트 문서
• 에이전트 지원 설정
• 수동 배포 및 문제 해결
• 기여 안내: 아키텍처 및 개발 워크플로
• 소스 확장 가이드
• 풀 리퀘스트 및 코드 리뷰
• DeepSeek Harness 홈페이지 및 커뮤니티 플러그인 링크
• MIT 라이선스

검토된 README에는 독립적인 기여 가이드나 전용 프로젝트 토론 포럼이 링크되어 있지 않습니다. 참여를 위한 문서화된 시작점으로 저장소와 업스트림 홈페이지를 사용하세요.

12. 요약

dsh-superagent-prototype은 전 세계 개발자에게 저장소 대화, 명시적 승인, 지속적 작업 실행, 인간 감독을 결합하는 구체적인 참고 자료를 제공합니다. 저장소 코딩 에이전트를 연구하고 DeepSeek Harness 생태계를 확장하는 팀과 연구자에게 유용하며, 연구 구현이므로 운영에 사용하기 전에 검토와 조정이 필요합니다.