Codex-DSH-Orchestrator

English | 简体中文

Codex-DSH-Orchestrator는 DeepSeek Harness(DSH)와의 제한된 협업을 위한 Codex 우선 오케스트레이션 레이어이자 호출자 측 MCP 브리지입니다. Codex가 구현, 조사, 디버깅, 긴 로그 작업을 DSH에 위임한 다음, 평소 워크플로를 벗어나지 않고도 해당 세션을 관찰하거나 계속하거나 취소할 수 있습니다. Claude Code는 공유 호출자 통합 레이어를 통해 계속 지원되며, 다른 호출자는 호스트 동작이 검증될 때까지 의도적으로 보류됩니다.

이 저장소의 공유 브리지 런타임은 업스트림 dsh-Agentlink project를 독립적으로 유지보수한 파생 프로젝트입니다. 이 프로젝트는 업스트림 MIT 라이선스와 저작권 표기를 유지하며, DeepSeek, OpenAI 또는 업스트림 유지관리자와 제휴하거나 보증을 받지 않습니다.

프로젝트 경계

Codex-DSH-Orchestrator는 호출자 측 오케스트레이션 및 MCP 브리지 프로젝트입니다. 지원되는 호출자를 독립적으로 실행되는 DSH Web Host에 연결합니다. 이 프로젝트는 해당 Host를 시작, 소유, 인증하지 않으며 DSH 요청을 자동 승인하지 않습니다. DSH Cordis 번들이 아닙니다.

Related MCP server: deepseek-harness-mcp

프로젝트 구성 요소

• skill/codex-dsh-orchestrator/ — 프로젝트 전용 Codex 오케스트레이션 스킬 및 에이전트 메타데이터.

• skill/codex-dsh/ — 공유 Codex 호출자 호환 스킬.

• skill/claude-code-dsh/ — 유지 관리되는 Claude Code 호출자 호환 스킬.

• src/ — 호출자 중립적인 공유 MCP 브리지 런타임 및 설치 도구.

• test/ — 로컬 모의 호스트, 안전성, 호환성 및 통합 테스트.

• docs/project-overview.md — 상세 소유권 및 아키텍처 맵.

dsh-Agentlink라는 이름은 호환성과 법적 명확성을 위해 런타임 식별자와 업스트림 귀속 표기로 남아 있으며, 공식 프로젝트 제목은 아닙니다.

호출자 지원

현재 이 저장소에서 설치 경로가 있는 항목은 지원됨으로 표시된 호출자뿐입니다. 계획됨 항목은 방향성일 뿐 출시 약속이 아닙니다.

설치

먼저 환경을 준비하세요. Node.js 22+, 지원되는 호출자(Codex 또는 Claude Code), 그리고 정상 작동하는 DSH CLI가 필요합니다. 테스트된 크로스플랫폼 기준은 x64 Node.js 22 및 24입니다. 다른 Node.js 메이저 버전과 ARM64 환경은 현재 테스트 매트릭스 범위에 포함되지 않습니다. DSH에서 원하는 모델을 한 번 구성하세요. 공유 브리지는 위임 에이전트가 지원되는 프로필을 명시적으로 요청하지 않는 한 그 활성 경로를 그대로 사용합니다.

이식성 및 설치 경계

• 다른 머신에서는 새 클론을 사용하세요. 단일 워크트리 디렉터리를 복사하지 마세요. 해당 .git 파일은 소스 클론의 워크트리 메타데이터를 가리킵니다. 같은 머신에서는 소스 클론에서 git worktree add로 워크트리를 만드세요.

• 깨끗하고 재현 가능한 체크아웃을 위해 npm ci를 우선 사용하세요. 의도적으로 lockfile을 업데이트하려는 경우에만 npm install을 사용하세요.

• npm run setup은 절대 경로의 Node.js 실행 파일과 빌드된 브리지 진입점을 호출자 구성에 기록합니다. 체크아웃을 안정적인 도구 디렉터리에 유지하세요. 이동하거나 Node.js 설치를 변경하거나 다른 워크트리로 전환한 후에는 다시 빌드하고 setup을 다시 실행하고, 기존 항목을 검토한 뒤 명시적 승인이 있을 때만 --replace를 사용하세요.

• Codex MCP 설정과 Codex 스킬 설치는 별개입니다. npm run setup은 MCP 항목을 등록하지만 skill/codex-dsh-orchestrator/는 설치하지 않습니다. 그 스킬은 평소의 Codex 스킬 워크플로를 통해 설치하고 활성화한 다음, $codex-dsh-orchestrator 명령을 신뢰하기 전에 발견 가능한지 확인하세요. Claude Code 설치 설정은 아래에서 설명하는 대로 프로젝트 스킬과 분리되어 관리됩니다.

• DSH_BRIDGE_HOME은 신뢰할 수 있는 로컬 파일시스템에 두세요. 이전 브리지 홈을 다른 머신에 복사하지 말고, 그 머신에서는 새 홈을 사용하세요. DSH 대화 기록은 DSH Web Host에 속하며, 브리지 작업 매핑, 커서, 클레임은 자동으로 이전되지 않습니다.

• Windows desktop-auto 방식은 옵트인입니다. 이미 실행 중인 DSH Desktop Host와 지원되는 Windows 프로세스/루프백 검색 전제조건이 필요합니다. CI는 이 동작들을 목킹하므로 실제 Desktop 설치나 로그인을 입증하지 않습니다. 셋업 위저드는 DSH Desktop을 시작하고 중지하거나 로그인하지 않습니다.

AI 에이전트로 설치

다음 저장소 URL과 프롬프트를 Codex나 다른 코딩 에이전트에 전달하세요.

Install Codex-DSH-Orchestrator from https://github.com/Fly2Kiana/Codex-DSH-Orchestrator.
Check Node.js 22+, the DSH CLI, and my DSH Web Host first. Clone it into a location I approve,
run npm ci and npm run check. For Codex, run npm run setup -- --yes, then install and verify
the shipped Codex skill separately through my normal Codex skill workflow. For Claude Code, run
npm run setup:claude -- --yes --project /absolute/path/to/my/project.
For Claude Code, let setup install the project MCP entry and shipped project skill; use --replace and --replace-skill only after reviewing existing files.
If dsh_agentlink or the legacy dsh_collab entry already exists, show me the conflict before using --replace.
Do not start or stop dsh web for me. Tell me when I need to reload the selected caller and approve project MCP trust.

수동 설치

1. 환경을 확인하세요. DSH CLI 0.1.0-rc.6이 현재 테스트 대상입니다.

   node --version
   dsh --version

2. 공식 DSH Web Host를 별도의 터미널에서 시작하세요.

   dsh web

3. 리포지토리를 클론하고 의존 패키지를 설치하세요.

   git clone https://github.com/Fly2Kiana/Codex-DSH-Orchestrator.git
   cd Codex-DSH-Orchestrator
   npm ci

4. 호출자를 설정하세요.

   For Codex의 경우:

   npm run setup
   npm run doctor

   Windows에서 DSH Desktop과 포트가 자주 바뀌는 루프백을 사용한다면 자동 검색을 명시적으로 선택하세요.

   npm run setup -- --desktop-auto

   Codex 위저드는 Codex TOML 구성을 백업하고 approval_mode = "prompt"로 MCP 항목을 설치합니다. skill/codex-dsh-orchestrator/는 설치하지 않습니다. 그 스킬은 평소 Codex 스킬 워크플로로 설치하고 사용토록 한 다음 발견 가능한지 확인하세요. 정적(staitc) 셋업은 여전히 sed --version 실행을 요구합니다. --desktop-auto는 CLI가 PATH에 없어도 이미 실행 중인 Desktop Host를 검증할 수 있고, 빠져 있는 패키지 버전을 호환성 경고로 보고합니다. 절대 DSH Desktop을 시작하거나 중지하지 않습니다. 기존 브리지 항목을 두 방식 중 하나로 전환하려면 항목을 검토한 뒤 --replace를 반드시 추가해야 합니다. Codex를 다시 시작한 다음 /mcp 또는 Codex Settings에서 dsh_agentlink가 연결되었는지 확인하세요. 완전 수동으로 TOML을 설정하려면 수동 Codex MCP 구성 문서를 참고하세요.

   Claude Code 2.1.199 이상인 경우 .mcp.json을 공유할 프로젝트를 지정해 셋업 명령을 실행하세요.

   npm run setup:claude -- --project /absolute/path/to/your/project
   cd /absolute/path/to/your/project
   claude mcp get dsh_agentlink

   Claude 셋업은 해당 프로젝트의 .mcp.json과 .claude/skills/claude-code-dsh/SKILL.md만 수정하며 관련 없는 서버 항목은 보존합니다. 다음 항목을 각각 보고합니다.

   • MCP 등록

   • 프로젝트 신뢰

   • Claude 스킬 상태

   • Claude 승인 지원

   • DSH 권한/샌드박스 소유권

   • DSH Host 연결성

   프로젝트에서 Claude Code를 열고 /mcp에서 대기 중인 서버를 승인하세요. 브리지는 dsh_resolve_approval을 사람의 조작이 필요한 것으로 표시합니다.

   무인 기본 실행을 하려면 --yes를 추가하세요. 기존 MCP 항목을 업데이트하려면 먼저 검토하고 --replace를 추가하고, 기존 Claude 프로젝트 스킬을 업데이트하려면 먼저 검토하고 --replace-skill을 추가하세요. 스킬을 직접 관리하려면 --no-skill을 추가하세요. 두 설치 프로그램은 모두 이전 dsh_collab 항목을 인식하며, 명시적 교체 승인 후에만 dsh_collab을 dsh_agentlink로 전환합니다. 두 설치 프로그램 모두 DSH를 시작하여, DSH 권한/샌드박스 설정을 바꾸지 않으며, 호출자를 재시작하지 않습니다.

doctor는 DSH_BRIDGE_HOME 아래 브리지의 fail-closed 잠금 위치를 읽기 전용으로 보고하고 절대 삭제하지 않습니다. 따라서 잠금이 있더라도 실행하기에 안전합니다.

이 소스 패치는 새 projection/chunk 플러드가 조정 원장(coordination ledger)를 확장하지 못하게 막지만, 기존의 5 MB 이상인 원장은 압축하지 않습니다. 검사를 위해 이전 브리지 홈은 보존하세요. 새 위임은 별도 DSH_BRIDGE_HOME을 사용할 수 있습니다. 대화의 원천은 브리지 원장이 아니라 DSH session.history에 있습니다. 보수적인 복구 경계는 알려진 이슈를 참조하세요.

이 브리지(러타임 이름 dsh_agentlink)는 호출자 측 플러그인이며 DSH Corda 번들이 아닙니다. dsh plugin --profile ... add ...로 설치하지 마세요.

왜 Codex-DSH-Orchestrator인가?

DSH의 Harness 기능 활용

DSH는 복잡한 작업을 위해 영속 세션, 도구 실행, 서브에이전트, 사람의 감독을 결합합니다. Codex-DSH-Orchestrator를 사용하면 주 호출자(현재 Codex 또는 Claude Code)가 같은 작업 환경에서 두 번째 Harness를 논의하고 조정할 수 있습니다.

또 하나의 네이티브 서브에이전트 그 이상

네이티브 서브에이전트는 여전히 호출자 자체 에이전트 트리 안에 있습니다. 공유 브리지는 별도의 사용자 설정 Harness를 추가합니다. 그 세션은 DSH Web에서 계속 보이며, DSH 자체 워커와 모델 라우트를 사용할 수 있고, 주 호출자가 관찰하거나 계속하거나 취소할 수 있습니다.

시간과 비용 절약

• 시간 절약. 구현, 조사, 추출, 긴 로그 작업을 DeepSeek V4 라우트처럼 DSH에서 구성된 빠른 모델로 라우팅하고, 주 에이전트는 계획과 검증을 계속하세요.

• 비용 절약. 실행 중심 워크로드를 저렴한 DeepSeek 라우트로 옮기면 비싼 주 모델의 소모를 줄일 수 있습니다.

실제 속도와 비용은 선택한 모델·공급자·배포·네트워크·작업에 따라 달라집니다. 설치 후에는 평소처럼 Codex나 Claude Code에서 계속 작업하다가, DSH가 더 나은 실행 경로일 때 상속요청하면 됩니다.

사용 방법

dsh web 실행 중이고 호출자가 MCP 설정을 로드하고 신뢰했다면, Codex나 Claude Code에 자연어로 요청하세요. 예:

Codex-DSH-Orchestrator를 사용해 현재 저장소에서 이 구현을 DSH에 의해 위임하고, DSH Web에서 계속 볼 수 있게 하며, 진행 상황을 보고하고 승인 전에 먼저 문의하세요.

그러면 호출자는 작업을 위임하고 그 이벤트 스트림을 관찰하고, 같은 세션을 계속하고, 답변을 받거나 작업을 취소할 수 있습니다. 구성된 DSH Web origin을 열어 동일한 세션을 검사하고 조작할 수 있습니다. Windows에서 옵트인 DSH_HOST_MODE=desktop-auto 런타임은 자주 바뀌는 임시 포트를 사용하는 대신 DSH Desktop이 소유한 검증된 루프백 리스너를 발견할 수 있습니다. 명시적인 DSH_HOST_URL은 항상 우선합니다.

새로 일임하기 전에 호출자는 이미 알려진 진행사실과 읽기 전용 작업공간 증거(목표, 완료 작업, 가능한 Git HEAD/status 및 변경 경로, 관련 코드/Markdown 경로, 관련 테스트, 제약 조건, 미해결 이슈)을 압축 핸드오프 형태로 구성합니다. DSH에게 핵심 경로를 먼저 읽고, 막히지 않는 한 저장소전체 스캔을 피하라고 지시합니다. 핸드오프에는 비밀 값, 원본 대용량 diff, 파일 본분, 호출자 대화, 내부 추리를 포함하지 않습니다. 이는 호출자를 위한 안내이지 새 파일시스템 권한이 아닙니다. dsh-Agentlink는 이전 호출자 대화 상태를 자동으로 받지 않습니다. 동일한 BridgeTask에 대해서 호출자는 dsh_followup을 사용하며, 일치하는 task id를 알 수 없으면 임의의 이전 id를 추측하지 않고 새 임대를 시작합니다.

사용자가 기존 DSH Desktop 세션을 명시적으로 식별했을 때, 호출자는 먼저 dsh_find_sessions로 범위가 한정된 루트 세션 메타데이터을 읽은 다음, 반환된 정확한 세션 id와 새 메타데이터 전제조건으로 dsh_attach_session을 사용할 수 있습니다. 세션 제목은 전달 탐색 도구일 뿐 첨부자 정체는 아닙니다. 첨부는 오류 id가 아닌 유휴 루트 세션만 받아들이며 브리지 로컬 매핑/작업공간 소유 상태를 생성하거나 재활용하고, 대화 본문을 반환하거나 유지하지 않고 감독을 위해 history를 조정할 수 있습니다. 이 과정은 DSH 세션을 만들거나 이름을 바꾸거나, 프롬프트를 내보내지 않으며 모델 라우팅을 바꾸지 않습니다. 이후 작업을 계속해야 할 때 후속 dsh_followup이 압축 핸드오프를 전달합니다.

Codex 작업에 걸쳐 세션을 재사용하는 것은 보수적인 세 가지 선택입니다: same-known-task, attached-existing-task, 또는 new-session입니다. 동일한 작업 스트림에 대해서만 동일한 알려진 BridgeTask를 재사용하십시오. 명시적 연속 증거가 있는 새 작업의 경우, 메타데이터 전용 dsh_find_sessions를 통해 정확히 하나의 canonical-cwd, 매핑된, 유휴 루트 세션을 찾아 dsh_followup로 계속하기 전에 최신 사전 조건으로 연결하십시오. 제목이나 유사성으로 재사용하지 말고, discovery를 위해 기록을 읽지 마십시오. 모호하거나, 실행 중이거나, 오래되었거나, cwd가 없거나, 매핑 충돌이 있는 후보는 fail closed 방식으로 실패하십시오. 재사용은 핸드오프와 저장소 읽기 작업을 절약할 수 있지만 입력 토큰을 증가시킬 수 있으므로, 연속성이 여전히 유효한 동안에만 비용 최적화로 작용합니다. 재사용과 재검색 회피는 공급자 프롬프트 캐시 적중이나 토큰 할인을 증명하지 않습니다. 공급자 캐시 증거는 DSH가 문서화된 집계 사용량 텔레메트리를 공개하지 않는 한 노출되지 않습니다.

MCP 도구

• dsh_host_status — connect 전용 Host 상태 및 기능

• dsh_find_sessions — 기존 루트 세션의 제한된 메타데이터 전용 검색; 기록이나 raw 프로젝션 없음

• dsh_attach_session — 최신 id/title/cwd/update 사전 조건을 사용해 정확히 하나의 유휴 루트 세션에 안전하게 연결; 프롬프트나 모델 변경 없음

• dsh_delegate — 루트 세션을 생성하고 초기 프롬프트를 큐에 넣습니다. 선택적으로 inherit|flash|pro|modlens-flash|modlens-pro 및 카탈로그가 지원하는 reasoningEffort를 선택할 수 있습니다. 기본적으로 분리되어 있습니다(waitSeconds=0). workspaceMode는 브리지 로컬 클레임이며 DSH 샌드박스 선택자가 아닙니다.

• dsh_followup — 동일한 루트 세션을 명시적 mode="queue"|"steer"(기본 queue)로 계속합니다. 프롬프트 전에 동일한 의미론적 모델 프로필과 검증된 추론 노력을 선택적으로 선택할 수 있습니다.

• dsh_continue — dsh_followup의 호환성 별칭

• dsh_status — 가용성, 실행, 계보, 큐, 보류 중인 상호작용, 최종 메시지, 커서, 워크스페이스 클레임 의미론

• dsh_tail — 브리지 작업 커서를 사용한 제한된 이벤트 요약

• dsh_wait — 지속 이벤트, 상태 변경, 보류 중인 상호작용 또는 종료 상태를 최대 30초 대기

• dsh_observe — dsh_wait의 호환성 별칭; 브리지 커서가 raw 세션 seq 커서를 대체합니다

• dsh_cancel — scope="turn"|"queue"

• dsh_list — 파생된 현재 상태로 보강된 작업 매핑 목록

• dsh_answer_question — 대기 중인 질문 rpcId에 대한 형식화된 답변

• dsh_resolve_approval — 대기 중인 승인 rpcId에 대한 형식화된 allow_once|reject 응답

• dsh_release_workspace — DSH 세션을 닫지 않고 영구적인 브리지 워크스페이스 클레임을 명시적으로 해제

모델 라우팅은 위임과 후속 작업 모두에 대해 옵트인(opt-in) 방식이며 이전 버전과 호환됩니다. modelProfile과 reasoningEffort가 생략되면 작업은 session.models.current를 읽고 routable을 확인하며 session.selectModel을 호출하지 않습니다. 의미론적 매핑은 flash/pro -> deepseek-official/deepseek-v4-{flash,pro}이고, modlens-flash/modlens-pro -> deepseek-modlens/deepseek-v4-{flash,pro}입니다. 요청한 제공자, 모델, 추론 노력은 실행 중인 session.models 카탈로그에 존재해야 합니다. 선택은 초기 또는 후속 프롬프트 전에 실행되고 다시 읽힙니다. 불일치가 있으면 프롬프트를 전송하지 않고 fail closed 처리합니다.

명시적 사용자 선택이 항상 우선합니다. 명시적 선택이 없으면 주요 호출자는 inherit를 유지하고, 일상적인 검색/구현/테스트 수리에 Flash를, 아키텍처 또는 어려운 다단계 디버깅에 Pro를, 시각적 증거가 필수적일 때 해당 ModLens 프로필을 사용할 수 있습니다. dsh-Agentlink는 텍스트 프롬프트만 전송합니다. DSH Host와 ModLens 도구가 접근할 수 있는 절대 로컬 이미지 경로를 포함하되 이미지 바이트는 업로드하지 않습니다. selectionReason은 선택적 감사 근거를 제공하며 DSH로 전송되지 않습니다.

로컬에서 검증된 DSH rc.6 collapsed Code Mode 경로에서, 시각적 핸드오프는 외부 run_code 전송을 사용하고, 그 프로그램 내부에 주입된 tools SDK를 통해 등록된 modlens_read_image를 호출합니다. 호출자는 이 외부 이벤트를 예상된 것으로 취급하고, 셸/브라우저/OCR/이미지 라이브러리 폴백을 금지하며, 중첩된 결과 또는 명시적인 중첩/종료 오류를 기다려야 합니다. 플러그인의 문서화된 내부 제한 시간은 전체 위임 데드라인이 아닙니다. 이것은 버전 범위로 한정된 호환성 지침이며, 이후 Host는 검증된 실제 기능이 다를 경우 이를 따라야 합니다.

중요한 DSH rc.6 부작용: session.selectModel은 선택을 이후 세션을 위한 DSH의 전역 기본값으로도 저장합니다. 위임 및 후속 결과는 명시적 선택이 언제든지 modelRouting.persistsAsDshDefault=true 및 경고를 보고합니다. 해당 유지가 허용되지 않으면 라우팅 필드를 생략하십시오. 삽입 기도 후 선택 검증에 실패하면 프롬프트는 전송되지 않지만, 요청한 선택은 이미 DSH의 전역 기본값으로 되어 있을 수 있습니다.

dsh_wait는 지속적인 브리지 상태를 관찰합니다. 어시스턴트 델타/청크 프레임 및 최상위 session/projection 스냅샷은 건너뜁니다. 따라서 이들은 작업 버전을 증가시키거나 대기자를 깨우지 않습니다. 종료된 후에도 최종 메시지 전체는 상태/테일(tail)을 통해 계속 관찰 가능합니다.

로드맵

다음은 계획된 방향일 뿐이며, 구현된 기능 또는 릴리스 약속은 아닙니다.

1. 더 많은 호출자 진입점 — 호출자 확장이 재개되면 ZCode를 먼저 평가하고, 이후 OpenCode, Workbuddy, Claude Desktop MCP 및 기타 호출자를 공유 Integration Pack 아키텍처로 고려합니다.

2. 에이전트 호출 및 정보 전송 — 질문, 승인, 오류, 최종 답변의 신뢰성을 유지하면서 프롬프트 구성, 컨텍스트 패키징, 출력 다이제스트 및 압축을 개선합니다.

3. DSH 플러그인 인지 세션 — 프리셋 기반 플러그인의 현재 agentPreset 경로를 유지하고, 읽기 전용 프리셋/역량 검증 및 확정 프리셋 보고를 추가하며, 플러그인이 형식화된 후속 생성 초기화가 실제로 필요함을 입증할 때만 선언적 세션 시작 프로파일을 도입합니다.

4. 더 많은 통합 — 공유 Runtime과 호출자 호환성 계약이 안정화된 후 확장합니다.

추가 문서

• 프로젝트 개요 — 공개 정체성, 구성 요소 소유권, Codex 우선 아키텍처

• 아키텍처 및 안전 모델 — 정체성, 상태, 복구, 승인, 취소 및 워크스페이스 조정

• 다중 호출자 확장 아키텍처 — Codex, Claude Code 및 향후 호출자를 위한 공유 Runtime과 Integration Pack 경계

• 연기된 로드맵 — 의도적으로 연기된 작업, 활성화 트리거 및 보존된 안전 경계

• 검증 가이드 — 호환성 및 운영자 승인 검사

• 알려진 이슈 — 현재 업그레이드 및 동시성 주의사항

• 기여 및 보안

라이선스

MIT

알파 노트: DSH는 아직 개발자 프리뷰 상태이며, 이 커뮤니티 프로젝트는 DeepSeek 및 OpenAI와 독립적입니다. 0.1.0-alpha.1에는 shared-ledger 동시성 버그가 있으며, 0.1.0-alpha.2에서 수정되었습니다. 업그레이드하거나 동시 브리지 프로세스를 실행하기 전에 알려진 이슈를 읽으십시오.