Codex DSH MCP

비용 인식형 MCP 브리지로, Codex가 반복적이고 컨텍스트가 많이 필요한 작업을 DeepSeek Harness에 위임하는 동안 Codex는 아키텍처, 리뷰, 최종 검증을 계속 제어합니다.

Codex DSH MCP는 각 DeepSeek 워커를 커밋된 HEAD에서 생성된 격리된 Git 워크트리에서 실행합니다. 메인 워크스페이스에 변경 사항을 자동으로 적용하지 않습니다. Codex와 인간 리뷰어는 먼저 검토할 수 있도록 간결한 결과, Markdown 보고서, 패치를 받습니다.

왜 사용하나요?

• 저장소 탐색, 일상적인 구현, 리팩터링, 테스트, 일반적인 수정을 DeepSeek에 오프로드합니다.

• 위험도가 높은 아키텍처, 보안, 최종 리뷰, 승인은 Codex가 유지합니다.

• 실패한 위임은 최대 한 번만 재시도한 후 호출 낭비 대신 ESCALATED_TO_CODEX를 반환합니다.

• 프로젝트별 호출, 기간, 성공률, 명확하게 라벨링된 추정/보고 토큰 사용량을 추적합니다.

• 메인 체크아웃을 보호합니다. 워커는 격리된 워크트리에서만 작동합니다.

빠른 시작

1. 이 저장소를 클론하고 Windows 탐색기에서 폴더를 엽니다.

2. install-windows.bat을 더블클릭합니다(또는 PowerShell에서 install-windows.ps1을 실행).

3. config.toml.example을 %USERPROFILE%\.codex\config.toml에 병합하고 브리지 경로를 업데이트합니다.

4. AGENTS.md를 전역 또는 프로젝트 수준 Codex 지침에 병합합니다.

5. Codex를 다시 시작하고 deepseek MCP 서버가 다섯 개의 도구를 노출하는지 확인합니다.

노출되는 기능

• deepseek_explore — 읽기 전용 저장소 탐색/검색.

• deepseek_task — 격리된 워크트리에서 일반 구현/리팩터링/테스트 작업.

• deepseek_fix — 격리된 워크트리에서 버그/실패 테스트 진단-수정-테스트 루프.

• deepseek_review — 읽기 전용 집중 리뷰.

• deepseek_stats — 읽기 전용 브리지 통계(총계, 도구 수, 성공률, 평균 기간, 최근 10개 작업 메타데이터).

라우팅 작동 방식

AGENTS.md는 Codex에게 작고 중요하며 아키텍처 관련, 보안에 민감하거나, 파괴적이거나, 이미 에스컬레이션된 작업에는 DIRECT_CODEX를 선택하도록 지시합니다. 광범위한 탐색과 일상적인 작업—특히 약 세 개 이상의 파일을 읽어야 하거나, 약 두 개 이상의 파일을 변경해야 하거나, 편집/테스트/수정 루프가 예상되는 경우—에는 DELEGATE_DEEPSEEK를 선택합니다. Codex는 이 선택을 위해 먼저 저장소를 스캔하지 않습니다.

User
 ↓
Codex Router
 ├── Small / Critical ──→ Codex
 │
 └── Delegatable
       ↓
    DeepSeek
       ↓
 ┌─────┴─────┐
Success     Failure
 ↓             ↓
Review      Retry once
               ↓
          Failure again
               ↓
             Codex

재시도는 동일한 작업 ID를 사용하는 집중 버그 수정 시도입니다. 두 번째 실패는 ESCALATED_TO_CODEX를 반환합니다. Codex가 인계받으며 동일한 문제를 세 번째로 위임해서는 안 됩니다.

요구 사항

• Windows 10/11(브리지에는 POSIX 경로도 있음).

• Node.js 20 이상.

• MCP 지원이 있는 Codex.

• dsh로 사용 가능하고 사용하려는 DeepSeek 모델/서비스에 대해 이미 구성/인증된 DeepSeek Harness.

Windows에 설치

이 폴더에서 PowerShell을 엽니다:

Set-ExecutionPolicy -Scope Process Bypass
.\install-windows.ps1

또는 install-windows.bat을 더블클릭합니다. 동일한 설치 프로그램의 간단한 Windows 래퍼입니다.

그런 다음 Codex를 사용하기 전에 DeepSeek Harness가 독립적으로 작동하는지 확인합니다:

dsh --profile headless "Reply with exactly READY"

작동하지 않으면 먼저 dsh를 수정하세요. MCP 브리지는 의도적으로 DeepSeek 자격 증명을 관리하지 않습니다.

Codex 구성

config.toml.example을 %USERPROFILE%\.codex\config.toml에 병합하고 예제 경로를 교체합니다:

[mcp_servers.deepseek]
command = "node"
args = ["C:/tools/codex-deepseek-bridge/src/index.mjs"]
startup_timeout_sec = 20
tool_timeout_sec = 7200

[mcp_servers.deepseek.env]
DSH_BATCH_CONTROLLER = "C:/Users/Administrator/.codex/skills/dsh-batch-subagents/scripts/dsh-batch-agents.mjs"
DSH_COMMAND = "dsh"
DSH_TIMEOUT_MS = "1800000"
DSH_MAX_OUTPUT_CHARS = "6000"
DSH_AUTO_RETRY = "true"
DSH_MAX_RETRIES = "1"
DSH_STATS_ENABLED = "true"
DSH_TOKEN_STATS = "true"
DEEPSEEK_ALLOWED_ROOT = "D:/Projects"

Codex를 다시 시작합니다. Codex TUI에서 /mcp는 deepseek MCP 서버와 다섯 개의 도구를 표시해야 합니다.

위임 프롬프트 설치

단일 저장소의 경우 AGENTS.md를 저장소 루트에 둡니다(또는 DeepSeek 위임 섹션을 기존 AGENTS.md에 병합).

전역 개인 정책의 경우 내용을 %USERPROFILE%\.codex\AGENTS.md에 병합합니다. 프로젝트별 지침이 여전히 이를 재정의할 수 있습니다.

권장 첫 테스트

임시 Git 저장소에서 Codex에게 요청합니다:

CLI 인수가 어디에서 파싱되는지 찾아보세요. 저장소 탐색에는 DeepSeek을 사용하고 관련 파일을 보고하세요. 아무것도 수정하지 마세요.

그런 다음 무해한 쓰기 작업을 시도합니다:

기존 순수 헬퍼에 대한 작은 단위 테스트를 추가하세요. 구현을 DeepSeek에 위임한 다음, 성공을 보고하기 전에 직접 diff를 검토하고 해당 테스트를 실행하세요.

그런 다음 통계를 확인합니다:

deepseek_stats를 실행하여 브리지 사용량과 토큰 절감을 확인하세요.

환경 변수

핵심

자동 재시도

통계

결과 형식

모든 위임 도구는 다음 필드가 포함된 간결한 구조화된 JSON 객체를 반환합니다:

에스컬레이션 흐름

Tool call → attempt 1 (fails) → retry → attempt 2 (fails) → return escalated_to_codex

위임이 status: "escalated_to_codex"를 반환하면 Codex는 근본 원인을 조사하고 다음 단계를 결정해야 합니다. 브리지는 절대 Codex API를 호출하지 않습니다.

토큰 통계

토큰 사용량은 사용량 JSON 블록을 사용할 수 있을 때 DeepSeek/Harness 출력에서 파싱됩니다(source: "reported", estimated: false). 그렇지 않으면 프롬프트/결과 문자 수에서 약 4자당 1토큰으로 근사됩니다(source: "estimated", estimated: true). 보고된 사용량은 공급자 데이터이고, 추정 사용량은 대체 근사치일 뿐입니다.

프로젝트 수준 .codex-deepseek/stats.json은 최대 100개 시도의 제한된 메타데이터를 기록하며 임시 파일 후 이름 변경을 통해 작성됩니다. 완전한 작업 프롬프트, 결과 요약, diff, 변경된 파일 경로 또는 아티팩트 경로는 절대 저장하지 않습니다. deepseek_stats는 총계, 성공률, 평균 기간, 도구별 횟수, 가장 최근 10개 메타데이터 항목을 반환합니다.

estimated_codex_tokens_avoided는 DeepSeek이 처리한 컨텍스트 양을 Codex가 처리하지 않아도 된 컨텍스트의 대략적인 대리 지표로 사용합니다. 항상 estimate_only: true로 표시됩니다. OpenAI 또는 Codex 할당량 측정이 아니며, 위임이 방향적으로 가치가 있는지 판단하는 데만 사용해야 합니다.

보안 모델

deepseek_task와 deepseek_fix는 DeepSeek Harness가 격리된 Git 워크트리만 편집하도록 허용합니다. 보고서와 패치는 Codex와 인간 리뷰를 위해 저장소 외부에 보관됩니다. 자동으로 병합되거나 적용되는 것은 없습니다.

deepseek_explore와 deepseek_review도 격리된 워크트리에서 실행됩니다. 읽기 전용 동작은 프롬프트 수준 정책으로 유지되지만, 실수로 인한 쓰기는 메인 워크스페이스에 닿을 수 없습니다.

deepseek_stats는 읽기 전용이며 통계 파일에만 접근합니다.

Codex 사용량을 절약하는 이유

비용이 많이 드는 루프는 일반적으로 저장소 검색 → 많은 파일 읽기 → 구현 → 테스트 → 실패 분석 → 재시도입니다. 브리지는 이 루프를 별도의 DeepSeek Harness 세션으로 이동합니다. DeepSeek의 간결한 구조화된 결과만 Codex로 반환되며, Codex는 결과 diff를 검사하고 목표 검증을 수행할 수 있습니다.

작성자

@sakurameishi가 만들고 유지 관리합니다.

라이선스

MIT © 2026 sakurameishi.