PerryLink/dsh-plugin-guide

DeepSeek Harness 플러그인 개발(dsh-plugin-guide)

공식 자료를 기반으로 DeepSeek Harness 플러그인을 개발합니다. 이 스킬은 워크플로우 및 제약 조건 체크리스트입니다. 세부 사항은 항상 지식 베이스 원문을 인용하며, 기억에 의존하여 지어내지 않습니다. 모든 "반드시/금지" 조항은 공식 저장소 AGENTS.md, docs/ 및 문서 사이트를 기준으로 하며, 충돌 시 공식 원문을 우선합니다.

지식 베이스 위치 (순서대로 찾아서 처음 존재하는 것을 사용)

이 스킬과 지식 베이스는 같은 디렉토리에 배포됩니다(이 SKILL.md 파일이 있는 디렉토리가 지식 베이스 루트). 모든 경로는 상대 경로입니다. 이 파일만单独 복사하고 guide/, references/ 디렉토리가 없을 경우 다음 대체 경로를 찾습니다.

1. 이 파일과 같은 디렉토리: ./guide/ (종합 가이드 + 빠른 참조 + 문서 링크 색인), ./references/ (조사 보고서 및 공식 문서 전체 사본 references/official-docs/docs/), ./downloads/ (원본 다운로드 파일, 선택 사항)
2. 로컬 주 사본: D:\deepseek-harness\Project\Plugins\dsh-plugin-guide\ (예시 경로, 실제 설치 위치에 따라 조정)
3. 공식 저장소 체크아웃: D:\deepseek-harness\ (docs/, vendor/cordis/, packages/, examples/)
4. 온라인: https://github.com/deepseek-ai/deepseek-harness , https://deepseek-harness.github.io/deepseek-harness/develop/basic/ , https://github.com/cordiverse/cordis

아래 경로는 기본적으로 위 1번(이 스킬 파일이 있는 디렉토리)을 기준으로 합니다.

개발 전제 조건 (첫 단계, 필수)

1. Cordis 개념을 아직 읽지 않았다면: references/official-docs/docs/cordis-primer.md (5개 개념, 5분 소요)를 읽습니다. 직접 따라 해볼 필요가 있다면 references/official-docs/docs/cordis-tutorial/ 01-07을 실행합니다(API 키 없이 실행 가능).
2. guide/quick-reference.md (계약 빠른 참조) + guide/plugin-dev-guide.md (전체 경로)를 엽니다. 공식/커뮤니티 문서 URL 대응은 guide/links.md를 참조합니다.
3. 대상 확장 지점 확인: references/official-docs/docs/architecture.md의 "Where new behavior goes" 표와 references/official-docs/docs/cookbook/extension-cookbook.md의 feature→mechanism 표를 읽습니다. 새 동작은 반드시 문서화된 확장 지점에 연결해야 하며, agent-loop를 수정해서는 안 됩니다.

반드시 준수해야 할 플러그인 계약 (공식 레드라인, 항목별 확인)

• 플러그인 = 모듈 내보내기 name + apply(ctx, config) (+ 선택적 inject: string[]). 의존하는 서비스는 apply 전에 준비됩니다. 의존 서비스가 사라지면 자동으로 언로드되고, 복구되면 자동으로 다시 로드됩니다.
• 등록 즉시 효과: 모든 기여는 ctx.effect() / ctx.on() / 서비스 register()를 통해 이루어집니다(disposer 반환). 절대 수동으로 removeListener/clearInterval 방식으로 정리하지 않습니다.
• waterfall 리스너는 반드시 next()를 호출해야 합니다. 호출하지 않으면 의도적인 단락(인터셉트 의미)입니다. emit/waterfall/parallel/serial/bail 의미는 빠른 참조 표를 참조합니다.
• 모델 가시성 ⟺ 기록됨: 모델 요청에 들어가는 모든 것은 세션 로그에서 재구성 가능해야 합니다. 새로운 모델 가시 입력을 추가하려면 반드시 새로운 SessionEventMap 세션 이벤트를 추가해야 합니다.
• 타입 안전 이벤트/서비스는 declaration merging(declare module '@deepseek-ai/cordis')을 사용합니다. 이벤트 문서에는 @mode를 표시합니다.
• 설정은 Schemastery Schema<Config>를 사용합니다(일반 객체 금지). 잘못된 설정은 로딩 시 명확하게 실패합니다. 조정 가능한 매개변수를 하드코딩하지 마십시오(판단 기준: cordis.yml에서 변경 가능한지).
• 도구는 defineTool을 사용합니다. execute는 output.schema에 선언된 표준 JSON 값만 반환합니다. exec.signal을 존중합니다. 사람이 읽을 수 있는 내용은 output.render에 넣습니다. UI 카드 presenter는 순수 함수여야 합니다(I/O, 시계, 랜덤 금지).
• 교체 가능한 능력은 3계층 접합부(Service Definition / Provider / Consumer)로 설계합니다. 미리 분리하지 않습니다.
• 번들링: 번들 매니페스트 "dsh":{"bundle":{"patch":"..."}}. 덮어쓰기는 id를 기준으로 전체 행을 config로 교체합니다. !!js(이중 느낌표) 사용. git 설치 시 prepare 스크립트와 사용자 측 allowBuilds가 필요합니다. npm/tarball 게시 시 빌드 허가가 필요하지 않습니다.

작업 유형별 개발 경로

(모든 경로는 references/official-docs/ 아래에 있으며, 공식 문서 전체 사본입니다)

• 새 도구: docs/user/develop/basic/tool.md (튜토리얼) → docs/cookbook/adding-a-tool.md (전체 계약: 매개변수 검증, 표준 값, 백그라운드 작업 ctx.jobs, 전략 훅, Code Mode, UI 카드) → 참조 구현 packages/shell/tool-bash (로컬 체크아웃).
• 새 서비스/능력: docs/user/develop/framework/service.md + docs/user/develop/practice/ (3계층 분할 전체 코드).
• 인터셉트/전략/훅: docs/cookbook/extension-cookbook.md (permission-gate 예제) + docs/event-producer-consumer.md (전체 이벤트 매트릭스).
• 새 LLM 제공자: docs/user/develop/practice/llm-adapter.md (StreamChunk 프로토콜).
• UI/세션 노드: docs/cookbook/adding-a-conversation-node.md + docs/subsystems/session.md, client-modules.md.
• 패키징/게시: docs/user/develop/basic/publish.md (bundle/profile, 레이어 순서, git 설치 시 주의사항).
• 서비스/이벤트 정확한 시그니처 조회: docs/subsystems/*.md (생성형 Cordis API 영역) + docs/cordis-api/*. 수동으로 두 번째 정적 목록을 만들지 마십시오. 사이트 URL ↔ 로컬 사본 대응은 guide/links.md를, 커뮤니티 링크 전체 목록은 references/community-ecosystem.md를 참조합니다.
• 커뮤니티 구현 참조 및 실제 테스트 함정: references/community-ecosystem.md, references/community-repo-deep-dive.md (15개 개발 저장소 심층 분석), downloads/community-repos/ (전체 소스 코드 사본, scripts/download-community-repos.ps1을 먼저 실행하여 생성). 커뮤니티에서 확인된 메커니즘 변경(repository-plugin 0811 제거, bundle 대 순수 cordis 이중 채널 등) 및 20개의 실제 테스트 함정(cordis 이중 사본/tsconfig 세트/다중 프레임 zstd/Windows junction 등)은 guide/plugin-dev-guide.md §7에 있습니다.

검증 (전달 전)

• 로딩 검증: dsh --profile <name> --dump-config를 실행하여 patch 행이 적용되었는지 확인합니다. 시작 로그에 FAILED가 없어야 합니다.
• 동작 검증: Web UI 또는 dsh --profile headless "…"를 사용하여 실제 테스트합니다. 도구 반환/모델 가시 텍스트가 동작입니다. 변경 사항은 반드시 재테스트해야 합니다.
• 저장소 내 변경 시 추가 절차: 타입 검사, 대상 패키지 테스트, keyless snapshot(모델/제품 가시 동작에는 조립 후 전사 스냅샷 필요), 이중 언어 문서 쌍 유지, Agent Note(사소하지 않은 변경은 동일 PR).
• 독립 플러그인 패키지: pnpm pack 후 깨끗한 프로필에 설치하여 검증합니다(lib/ 빌드 산출물 포함).

지식 베이스 유지 관리 (필요 시)

• 공식 문서 사본 동기화: pwsh -File ./scripts/sync-official-docs.ps1 [-Checkout <deepseek-harness checkout>] - git이 추적하는 파일만 동기화합니다(추적되지 않은 초안과 푸시되지 않은 커밋은 포함되지 않음). 그리고 references/official-docs/SNAPSHOT.md를 갱신합니다. README의 "최종 검증" 날짜와 커밋 번호는 SNAPSHOT.md를 참조하며, 수동으로 수정하지 않습니다. 드리프트 검증: pwsh -File ./scripts/verify-kit.ps1 -Checkout <checkout>.
• 온라인 자료 갱신: pwsh -File ./scripts/download-sources.ps1. 커뮤니티 저장소 갱신: pwsh -File ./scripts/download-community-repos.ps1 (두 스크립트 모두 멱등성이며, 출력은 ./downloads/에 저장됨). 주제 목록 개수 재확인: pwsh -File ./scripts/gen-topic-snapshot.ps1 -OutDir <dir> -MaxPages 20 (GitHub Search API q=topic:dsh-plugin; 페이지당 최대 1000개 항목, 중복 제거 수와 API total_count를 모두 sources.md §D.2에 기록).
• 에이전트 스킬 사본 설치/갱신: pwsh -File ./scripts/install-skill.ps1 -Target <skill directory> (downloads/와 .github/는 건너뛰고, 바이트 단위로 검증).
• 충돌 판정: 공식 문서와 충돌 시 references/official-docs/ (공식 저장소 원문)을 우선합니다.

경계

• 이 스킬은 "안내 + 제약 + 자료 색인"이며, 스크립트/목록의 기계적 실행이 아닙니다. 정확한 API는 생성형 참조를 기준으로 합니다.
• 사용자가 명시적으로 요청하지 않는 한, 지식 베이스 외부의 harness 저장소 파일을 수정하지 않습니다. vendor/와 .agents/notes/archived/는 읽기 전용입니다.
• downloads/ 내용을 참조하기 전에 해당 내용이 존재하는지 먼저 확인합니다(이 디렉토리는 git에 포함되지 않으며, 위 스크립트에 의해 생성되어야 함). awesome-dsh-plugins의 아카이브는 로컬 참조용으로만 제공되며, 저장소와 함께 재배포할 수 없습니다(해당 상위 저장소는 내부 사용 제약 조건을 선언하며, NOTICE.md 참조).