dsh-helm

DSH 다중 노드 컨트롤 플레인: 단일 머신의 'ChatGPT ↔ DSH' 커넥터를 다중 노드 컨트롤 플레인으로 확장합니다. 여러 머신의 DeepSeek Harness(DSH)가 노드 에이전트(node-agent)를 통해 통합 Hub에 등록되고, ChatGPT는 단일 엔트리포인트를 통해 모든 노드로 라우팅할 수 있습니다—코드 읽기/쓰기, 세션 관리, 상태 확인이 가능하며, 어떤 노드도 공개 인터넷에 노출하지 않습니다.

ChatGPT Web（连接器/插件）
   │ OpenAI Secure MCP Tunnel（tunnel-client，TLS）
   ▼
Hub 控制平面     MCP 127.0.0.1:3471（ChatGPT 入口）    mesh <hub-ip>:3470（节点接入）
   │ 路由：显式 target → session owner → workspace owner → presence → default
   ├──────────────┬──────────────┬──────────────┐
   ▼              ▼              ▼              ▼
node-agent    node-agent    node-agent    node-agent   （每台机器：出站 WS + HMAC 握手）
   │              │              │              │
   ▼              ▼              ▼              ▼
daemon 3457 → DSH   daemon 3457 → DSH   ……      （各节点本地 helm daemon，Bearer 鉴权）

• 각 노드는 dsh-helm agent를 실행합니다: 아웃바운드 전용으로 hub에 연결(mesh WS)하고, 로컬 helm daemon의 MCP(127.0.0.1:3457/mcp)를 내부로 브리징합니다.

• hub는 유일한 엔트리포인트입니다: ChatGPT는 hub MCP(3471)를 통해 도구를 호출하고, hub는 라우팅 정책에 따라 올바른 노드로 전달합니다. 노드 수는 ChatGPT에 투명합니다.

• 단일 머신 호환: 단일 노드이고 node_id == hub defaultNodeId인 경우, 라우팅 및 도구 호출 동작은 단일 머신 daemon과 동일합니다(요약/가드/스티어는 상위 계층 강화이며 기존 호출 의미론에 영향을 주지 않습니다).

기능 특징

• 다중 노드 등록 및 하트비트: 노드 ID node_id(UUID) + HMAC 챌린지 핸드셰이크; 15초 하트비트, 45초 임대; 새 버전 에이전트는 하트비트 타임아웃 시 자동 재연결(반개방 연결 감지 재연결).

• 5단계 라우팅: 명시적 target_node → session owner → workspace owner → 모호성 없는 presence → defaultNodeId 폴백; destructive/write 작업의 대상이 명확하지 않으면 fail-closed 거부(route_confirmation_required), 절대 추측하지 않음.

• 전달 추적 가능: 각 전달 결과에 _route.node_name(display_name)으로 실행 노드가 표시됩니다; route_explain은 실행 없이 미리보기만 합니다.

• MCP 도구 표면 19+5: 단일 머신 daemon의 19개 도구(code_*/sessions_*/projects_list/supervisor_health 등, snake_case 매개변수 불변)는 그대로 유지되고, nodes_list/node_get/route_explain/presence_claim/presence_release가 추가됩니다; 모든 라우팅 가능 도구에는 선택적 target_node가 있습니다.

• presence: 수동 선언(10분 핀) + macOS 포그라운드 앱 자동 감지(데스크톱 sidecar); 15초 모호성 창 내에서 두 노드의 높은 신뢰도 → ambiguous로 판정, 자동 선택하지 않음.

• 계층형 상태: control / channel / adapter / datapath / serena / tunnel 각 계층이 독립적으로 보고되며, 단일 status: ok로 축소하지 않습니다.

• 크로스 노드 집계: workspaces_list/sessions_list/agents_list/projects_list는 다중 노드 플랫 결과를 반환합니다(각 항목에 node_id 포함).

• 감사 및 라우팅 로그: 노드 등록, 하트비트, 라우팅 결정, presence 변경이 모두 데이터베이스에 기록됩니다(audit/route_log).

• 메타데이터 레드라인: hub 저장소에는 메타데이터(노드/임대/세션 및 작업 공간 디렉터리/감사)만 포함되며, DSH 세션 본문은 절대 저장하지 않습니다.

Related MCP server: Peta Core

디렉터리 구조

dsh-helm/
├── packages/
│   ├── protocol/    # wire 协议：envelope、JSON-RPC、HMAC 握手、常量
│   ├── store/       # SQLite：节点注册表、presence、目录、审计
│   ├── hub/         # 控制面：Router、WS mesh 3470、MCP 3471
│   ├── node-agent/  # 节点代理：出站 WS、重连、本地 DSH 桥
│   ├── presence/    # presence providers（手动/macOS/浏览器）
│   ├── platform/    # 跨平台适配（launchd/systemd/Windows 模板）
│   └── cli/         # dsh-helm CLI（init/agent/hub/status/nodes/…）
├── tests/integration/  # 双 fake node 端到端测试
└── scripts/            # ops 脚本（bash，macOS 优先）

빠른 시작

전제 조건: Node.js >= 22.5, pnpm, curl; 각 노드 머신에 DSH와 helm daemon(127.0.0.1:3457/mcp, Bearer 토큰은 ~/.agent-chatgpt-helm/token에 있음)을 먼저 설치합니다.

# 1. 安装 CLI（构建 + 写 ~/.local/bin/{dsh-helm,dsh-helm-agent,dsh-helm-hub}，幂等）
./scripts/install.sh

# 2. 初始化节点身份（生成 ~/.dsh/helm/node.json，权限 0600）
dsh-helm init

# 3. 编辑 ~/.dsh/helm/node.json：设置 hub_url 与 local_mcp_token
#    hub_url：内网/Tailscale 用 ws://<hub-ip>:3470，生产用 wss://

# 4. hub 机器：启动控制面（mesh 3470 + MCP 3471；默认只绑 127.0.0.1）
dsh-helm hub
#    多机场景：dsh-helm hub --bind <tailnet-ip> --mcp-bind 127.0.0.1

# 5. 节点机器：启动 agent（先前台验证，再装自启服务）
dsh-helm agent
./scripts/install-service.sh        # macOS：launchd 服务（com.dsh-helm.node-agent）

# 6. 自检与状态
./scripts/verify.sh                 # 0 全绿 / 1 警告 / 2 严重
./scripts/health.sh                 # 节点状态表（走 hub MCP supervisor_health）
dsh-helm status                    # 本地配置与连接状态

더 많은 노드 추가: 새 노드 머신에서 dsh-helm init 후, node.json의 node_id와 token을 안전한 채널을 통해 hub 관리자에게 전달하고, hub 머신에서 실행합니다(멱등: 토큰 테이블에 추가/업데이트, launchd 서비스 자동 리로드):

./scripts/register-node.sh <node_id> <token>

자세한 절차는 docs/onboarding.md를 참조하세요.

ChatGPT 연결

배포 단계에 따라 두 가지 경로가 있습니다:

• A. 단일 머신 직접 연결(시작): 로컬에 helm daemon이 이미 있는 경우, hub는 로컬 노드를 local node로 취급하며 단일 머신 커넥터와 동일하게 동작합니다. 터널이 필요 없습니다.

• B. 다중 노드(컨트롤 플레인, 권장): OpenAI Secure MCP Tunnel을 hub MCP(3471)에 연결하여 ChatGPT가 단일 엔트리포인트로 모든 노드를 관리합니다.

OpenAI Platform 측 전체 튜토리얼(터널 생성 / workspace 바인딩 / API key 생성 / tunnel-client 매개변수 / 프록시)은 docs/chatgpt-tunnel-setup.md를 참조하세요; ChatGPT Web 측(개발자 모드 / 커넥터 생성 / 테스트)은 docs/chatgpt-connector.md를 참조하세요.

두 토폴로지의 장단점: 각 daemon에 터널+커넥터를 각각 구성(다중 엔트리포인트, 각자 관리)하거나, 하나의 hub 터널 + 하나의 커넥터로 N개 노드를 관리(단일 엔트리포인트, 권장—hub가 target_node/라우팅 규칙으로 라우팅하고, 응답에 node_name 포함).

컨트롤 플레인 HA(이중 Control Plane)

두 대의 hub가 quorum(2/2) 컨트롤 플레인을 구성하여, 한 대가 장애가 나도 다른 한 대가 읽기 라우팅과 노드 엔트리포인트를 계속 제공할 수 있습니다.

• 역할 및 임대: --cp-priority가 낮은 쪽이 leader로 선출됩니다(유일한 쓰기 권한); leader는 10초마다 peer에게 임대를 갱신하고, peer가 임대 TTL(--cp-failover-ms, 기본 45초)을 초과하여 연결이 끊기면 → 양쪽 모두 read-only-no-quorum 상태가 되고, 쓰기 작업은 QUORUM_LOST를 반환합니다. follower는 절대 단독으로 승격하지 않습니다—quorum을 잃으면 읽기 전용으로만 동작합니다(CAP에서 안전 우선).

• 복구: peer 재연결 → 레지스트리 전체 동기화 → 강제 재선거(term+1) → 임대 양쪽 확인 → 쓰기 복구. 전체 복구 창 동안 양쪽은 읽기 전용을 유지합니다.

• agent 다중 엔드포인트: node.json에 hub_url + fallback_urls를 구성하고, 재연결 시 라운드로빈으로 시도한 후 성공하면 고정합니다; 장애 시 자동으로 두 번째 CP로 전환합니다.

• 관측: GET /cp-status는 role/phase/writeMode/quorum/term/leaderId/peers/syncOk/leaseEpoch/failoverCount를 반환합니다; dsh-helm doctor와 Dashboard의 '컨트롤 플레인 HA' 카드에서 직접 확인할 수 있습니다.

• ChatGPT 엔트리포인트 HA: OpenAI tunnel-client의 --mcp.server-url은 channel 한정이며, 동일 커넥터 내 다중 백엔드 failover가 없습니다. 로컬에서 dsh-helm ha-proxy(기본 127.0.0.1:3481, --primary http://127.0.0.1:3471 --secondary http://<peer-cp>:3471)를 실행하고, 터널은 여전히 하나의 커넥터(3481)를 가리킵니다; 주 CP가 연결이 끊기면 자동으로 보조 CP로 전환되고, 복구 후 다시 전환됩니다. 이중 터널 + 이중 커넥터는 대체 토폴로지입니다.

• 두 번째 CP 배포: dsh-helm hub --cp-peer ws://<peer-cp>:3470 --cp-priority 1 --cp-id <node-id> --cp-token-env DSH_HELM_CP_TOKEN; 양쪽 DSH_HELM_TOKEN에는 양쪽 노드 토큰 테이블이 모두 포함되어야 합니다(어느 agent가 장애 조치되더라도 상대 CP가 인증할 수 있음). MCP를 크로스 머신에서 접근해야 하는 경우 --mcp-bind <tailnet-ip>를 사용합니다(Tailscale ACL 펜스, 단일 머신 시나리오에서는 loopback 유지).

장치 페어링(새 DSH 장치 추가)

Dashboard의 '새 DSH 장치 추가' → 일회용 페어링 코드 생성(10분 유효, 단일 사용, 해시만 저장); 새 머신에서 dsh-helm join --control-plane ws://<hub>:3470 --code <code>를 실행하여 네트워크에 가입합니다(장기 노드 토큰을 생성하여 ~/.dsh/helm/node.json에 저장, hub는 해시/상태만 저장). 페어링 API는 loopback 전용 + CSRF 방지 헤더; 로그에는 해시 접두사만 기록됩니다. 자세한 내용은 docs/security.md §5를 참조하세요.

MCP Context Isolation(대형 컨텍스트 안정성)

ChatGPT ↔ DSH 커넥터의 장시간 실행, 대형 컨텍스트 세션에서의 응답 슬림화 및 모니터링(호환 계층, 링크 변경 없음):

• sessions_get 기본 요약: 기본적으로 구조화된 요약만 반환합니다(id/title/status/workspace/created_at/updated_at/last_message_summary/last_assistant_summary/current_goal/current_goal_seq/last_user_message/recent_evidence{commits,paths,errors,tests}/history_ref/safety_sanitized/token_estimate/continuation_available, messages 없음). 요약은 node agent가 생성합니다: DSH에 마지막 20개 메시지만 요청(SUMMARY_WINDOW), current_goal은 창 내에서 가장 행동 지향적인 사용자 명령(출처 seq 포함), recent_evidence는 정규식 휴리스틱 추출, 의심스러운 자격 증명 줄은 요약 필드에 들어가기 전에 제거됩니다(safety_sanitized 표시). 실측 기준: 초기 대형 세션 응답 75KB → 1.2KB; 정보 충실도 수용 fixture(1000개 메시지) 약 107KB → 0.7KB, 기본 응답 <1KB. ~/.dsh/helm/summaries/<session_id>.json에 캐시(60초 TTL, 쓰기 작업 후 무효화).

• 전체 기록 필요 시 가져오기: include_messages=true(선택적 max_messages, 기본 20)는 전체 메시지를 반환합니다; before_seq 매개변수는 전달되지만 DSH 0.1.1은 실제 페이징을 구현하지 않았습니다(탐지 실측: max_messages ≤100이고 beforeSeq는 무효)—최근 100개 메시지 밖의 기록은 현재 접근 불가능하며, history_ref는 접근 가능 범위를 명시적으로 표시합니다(reachable_max_messages:100); 기존 호출(매개변수 없음)은 자동으로 요약을 사용하며, 호출자는 매개변수를 변경할 필요가 없지만 반환 내용이 전체 메시지에서 요약으로 변경된다는 점에 유의하세요(원문이 필요하면 명시적으로 include_messages=true).

• Response Size Guard: hub의 모든 MCP 응답에 통합 미들웨어, MAX_RESPONSE_BYTES=50000; 초과 시 자동 smart-truncate(여전히 유효한 JSON 보장, truncated 메타데이터 첨부), 로그 [mcp-guard] <tool> original=.. returned=.. truncated.

• 상태 모니터링: hub에 GET /metrics(요청 수/평균 및 최대 응답 바이트/잘림 및 오류 수/활성 연결/perTool 세부 정보), GET /readyz(HA quorum 준비), GET /version 추가; Dashboard에 'MCP 컨트롤 플레인' 탭 추가.

• 오류 수정 끼어들기/즉시 개입: sessions_prompt는 mode=queue|steer를 지원합니다(기본 queue 대기열 의미론 유지); steer는 대기열을 우회하여 DSH 호스트 API를 통해 실행 중인 턴에 주입합니다(구조화된 반환 steered/queued/rejected/unavailable), DSH 이벤트 agent/inbox/spliced로 주입을 확인합니다. 설계 검토 및 구현 세부 사항은 docs/priority-queue.md를 참조하세요.

플랫폼 지원

핵심 코드는 플랫폼 특정 로직이 전혀 없습니다(launchd/osascript/PowerShell은 모두 packages/platform 및 packages/presence에 격리됨); macOS 이중 머신(Tailscale)은 실기기 검증 완료, Linux/Windows는 실기기 검증 대기.

문서

보안 요점

• 자격 증명: ~/.dsh/helm/node.json(노드 토큰) 및 daemon 토큰 파일은 모두 0600; hub 토큰 테이블은 DSH_HELM_TOKEN 환경 변수로 주입(디스크에 저장 안 함); 토큰은 argv/git/로그에 나타나지 않음; 터널 자격 증명은 env: 구문으로 주입.

• 바인딩: hub는 기본적으로 127.0.0.1에만 바인딩; 크로스 머신은 Tailscale + --bind <tailnet-ip> 권장, --mcp-bind 127.0.0.1로 MCP를 loopback 전용으로 유지. hub MCP(3471) v1은 인증 없음—공개 인터넷에 직접 노출 금지; 프로덕션 mesh는 wss://(TLS는 리버스 프록시/외부 https 서버가 담당).

• fail-closed: 파괴적 작업(sessions_prompt/sessions_resume)은 명확한 대상이 없으면 거부; presence 모호성 창 내에서 추측하지 않음.

• 본문 저장 없음: store는 메타데이터와 감사만 저장하며 DSH 세션 내용을 저장하지 않음.

• 자세한 보안 모델은 docs/security.md 및 docs/threat-model.md 참조.

상태 및 사실 계층

버전 v0.1.0. 자동화 검증 전체 통과(단위 + 이중 fake node 전체 프로토콜 엔드투엔드 통합 테스트 + 정보 충실도 수용: 399/399(48개 파일), build/lint 깨끗함); macOS 이중 머신 Tailscale 실기기 스모크 완료. doctor/dashboard/install 구현됨; CLI 온라인 RPC 명령(nodes/node/route-explain/presence/rotate-token)은 여전히 live hub 연결 필요(현재 requires live hub connection 메시지 표시, 다음 마일스톤 계획), 동일 기능은 hub MCP 도구(nodes_list 등)로 사용 가능; session handoff v1은 정직하게 unsupported 반환.

능력 상태는 증거 강도에 따라 계층화(혼동하지 않음):

명시적 비약속: production-ready 보장 없음; HA는 자체 관리 컨트롤 플레인 중복이며 SLA / zero-downtime 보장 없음; OpenAI 공식 기능 경계(터널 다중 인스턴스 HA, 키 자동 교체)가 확인되기 전에는 약속하지 않음. 수용 판정은 CONDITIONAL PASS(충실도 및 보안 폐쇄, 완전성은 DSH 0.1.1 프로토콜 경계로 제한).

ops 스크립트

모든 스크립트는 bash 3.2 호환, [dsh-helm] 출력 접두사, 멱등, 프로덕션 포트(3080/3457/3458)의 기존 서비스를 탐지만 하고 수정하지 않습니다.