dsh-helm

DSH-Mehrknoten-Steuerungsebene: Erweitert den Einzelrechner-„ChatGPT ↔ DSH"-Connector zu einer Mehrknoten-Steuerungsebene. DeepSeek Harness (DSH)-Instanzen auf mehreren Maschinen registrieren sich über Knoten-Agenten (node-agent) an einem zentralen Hub. ChatGPT kann über einen einzigen Einstiegspunkt an jeden beliebigen Knoten geroutet werden – Code lesen/schreiben, Sitzungen verwalten, Gesundheit prüfen – ohne dass ein Knoten öffentlich exponiert wird.

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 鉴权）

• Jeder Knoten führt dsh-helm agent aus: nur ausgehende Verbindung zum Hub (Mesh-WS), nach innen Bridging zum MCP des lokalen Helm-Daemons (127.0.0.1:3457/mcp).

• Der Hub ist der einzige Einstiegspunkt: ChatGPT ruft Tools über das Hub-MCP (3471) auf, der Hub leitet gemäß Routing-Strategie an den richtigen Knoten weiter; die Knotenanzahl ist für ChatGPT transparent.

• Einzelrechner-Kompatibilität: Bei einem einzelnen Knoten mit node_id == hub defaultNodeId sind Routing und Tool-Aufrufverhalten äquivalent zum Einzelrechner-Daemon (summary/guard/steer sind Erweiterungen der oberen Ebene und beeinflussen die bestehende Aufrufsemantik nicht).

Funktionen

• Mehrknoten-Registrierung und Heartbeat: Knotenidentität node_id (UUID) + HMAC-Challenge-Handshake; 15s Heartbeat, 45s Lease; bei Heartbeat-Timeout des neuen Agenten automatische Wiederverbindung (Half-Open-Erkennung und Reconnect).

• Fünfstufiges Routing: expliziter target_node → session owner → workspace owner → eindeutige presence → defaultNodeId als Fallback; bei unklarem Ziel für destruktive/Schreiboperationen fail-closed-Ablehnung (route_confirmation_required), niemals raten.

• Nachvollziehbares Forwarding: Jedes Forwarding-Ergebnis enthält _route.node_name (display_name) zur Kennzeichnung des ausführenden Knotens; route_explain ist eine Vorschau ohne Ausführung.

• MCP-Tool-Oberfläche 19+5: Die 19 Tools des Einzelrechner-Daemons (code_*/sessions_*/projects_list/supervisor_health usw., snake_case-Parameter unverändert) bleiben erhalten, neu hinzugekommen sind nodes_list/node_get/route_explain/presence_claim/presence_release; alle routbaren Tools haben einen optionalen target_node.

• presence: Manuelle Deklaration (10-Minuten-Pin) + automatische Erkennung von macOS-Vordergrund-Apps (Desktop-Sidecar); bei hoher Konfidenz beider Knoten innerhalb des 15s-Mehrdeutigkeitsfensters → als ambiguous eingestuft, keine automatische Auswahl.

• Mehrschichtige Gesundheit: control / channel / adapter / datapath / serena / tunnel melden jeweils unabhängig, niemals zu einem einzelnen status: ok zusammengefasst.

• Knotenübergreifende Aggregation: workspaces_list/sessions_list/agents_list/projects_list liefern flache Ergebnisse über mehrere Knoten (jeder Eintrag mit node_id).

• Audit- und Routing-Logs: Knotenregistrierung, Heartbeat, Routing-Entscheidungen und presence-Änderungen werden vollständig protokolliert (audit/route_log).

• Metadaten-Rotlinie: Der Hub-Speicher enthält nur Metadaten (Knoten/Leases/Sitzungs- und Workspace-Verzeichnisse/Audit), speichert niemals DSH-Sitzungsinhalte.

Related MCP server: Peta Core

Verzeichnisstruktur

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 优先）

Schnellstart

Voraussetzungen: Node.js >= 22.5, pnpm, curl; auf jedem Knotenrechner zuerst DSH und Helm-Daemon installieren (127.0.0.1:3457/mcp, Bearer-Token in ~/.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                    # 本地配置与连接状态

Weitere Knoten hinzufügen: Nach dsh-helm init auf dem neuen Knotenrechner node_id und token aus node.json über einen sicheren Kanal an den Hub-Administrator übergeben und auf dem Hub-Rechner ausführen (idempotent: Token-Tabelle wird ergänzt/aktualisiert, launchd-Dienst wird automatisch neu geladen):

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

Detaillierter Ablauf siehe docs/onboarding.md.

ChatGPT-Anbindung

Zwei Wege, je nach Bereitstellungsphase:

• A. Einzelrechner-Direktverbindung (Einstieg): Wenn lokal bereits ein Helm-Daemon läuft, behandelt der Hub den lokalen Knoten als lokalen Knoten; das Verhalten entspricht dem Einzelrechner-Connector, kein Tunnel erforderlich.

• B. Mehrknoten (Steuerungsebene, empfohlen): OpenAI Secure MCP Tunnel verbindet das Hub-MCP (3471); ChatGPT verwaltet über einen Einstiegspunkt alle Knoten.

Das vollständige Tutorial auf der OpenAI-Platform-Seite (Tunnel erstellen / Workspace binden / API-Key erstellen / tunnel-client-Parameter / Proxy) siehe docs/chatgpt-tunnel-setup.md; die ChatGPT-Web-Seite (Entwicklermodus / Connector erstellen / Testen) siehe docs/chatgpt-connector.md.

Abwägung der beiden Topologien: Jeder Daemon mit eigenem Tunnel+Connector (mehrere Einstiegspunkte, jeder verwaltet seine eigenen), oder ein Hub-Tunnel + ein Connector verwaltet N Knoten (ein Einstiegspunkt, empfohlen – Hub-Routing über target_node/Routing-Regeln, Antworten enthalten node_name).

Steuerungsebene-HA (Doppelte Control Plane)

Zwei Hubs bilden ein Quorum (2/2) der Steuerungsebene; fällt einer aus, kann der andere weiterhin Lese-Routing und Knoten-Einstiegspunkte bedienen.

• Rollen und Leases: Niedrigere --cp-priority gewinnt als Leader (einziger Schreiber); der Leader erneuert alle 10s den Lease beim Peer; wenn der Peer länger als die Lease-TTL (Standard 45s) nicht erreichbar ist (--cp-failover-ms) → beide Seiten wechseln in read-only-no-quorum, Schreiboperationen geben QUORUM_LOST zurück. Ein Follower wird niemals einseitig befördert – ohne Quorum nur lesend, nicht schreibend (CAP priorisiert Sicherheit).

• Wiederherstellung: Peer-Wiederverbindung → vollständige Registrierungssynchronisierung → erzwungene Neuwahl (term+1) → Lease-Bestätigung durch beide Seiten → Schreibbetrieb wiederhergestellt. Während des gesamten Wiederherstellungsfensters bleiben beide Seiten schreibgeschützt.

• Agent mit mehreren Endpoints: node.json enthält hub_url + fallback_urls; bei Wiederverbindung werden die URLs zyklisch versucht, nach Erfolg gepinnt; bei Ausfall automatischer Wechsel zum zweiten CP.

• Beobachtung: GET /cp-status liefert role/phase/writeMode/quorum/term/leaderId/peers/syncOk/leaseEpoch/failoverCount; dsh-helm doctor und die Dashboard-Karte „Steuerungsebene-HA" zeigen dies direkt an.

• ChatGPT-Einstiegspunkt-HA: Die --mcp.server-url des OpenAI tunnel-client ist channel-gebunden und unterstützt kein Failover auf mehrere Backends innerhalb desselben Connectors. Lokal dsh-helm ha-proxy starten (Standard 127.0.0.1:3481, --primary http://127.0.0.1:3471 --secondary http://<peer-cp>:3471); der Tunnel zeigt weiterhin auf einen Connector (3481); bei Ausfall des primären CP automatischer Wechsel zum sekundären CP, nach Wiederherstellung Wechsel zurück. Doppel-Tunnel + Doppel-Connector ist eine alternative Topologie.

• Bereitstellung des zweiten CP: dsh-helm hub --cp-peer ws://<peer-cp>:3470 --cp-priority 1 --cp-id <node-id> --cp-token-env DSH_HELM_CP_TOKEN; beide Seiten von DSH_HELM_TOKEN enthalten die Token-Tabellen beider Knoten (bei Failover eines Agenten kann der jeweils andere CP authentifizieren). Wenn MCP maschinenübergreifend erreichbar sein muss, --mcp-bind <tailnet-ip> verwenden (Tailscale-ACL-Umzäunung, im Einzelrechner-Szenario loopback beibehalten).

Gerätekopplung (neues DSH-Gerät hinzufügen)

Dashboard „Neues DSH-Gerät" → Einmal-Pairing-Code generieren (10 Minuten gültig, einmalig konsumierbar, nur Hash gespeichert); auf der neuen Maschine dsh-helm join --control-plane ws://<hub>:3470 --code <code> ausführen, um ins Netz aufgenommen zu werden (langfristiges Knoten-Token wird in ~/.dsh/helm/node.json geschrieben, der Hub speichert nur Hash/Status). Die Pairing-API ist nur loopback + Anti-CSRF-Header; Logs enthalten nur Hash-Präfixe. Siehe docs/security.md §5.

MCP Context Isolation (Stabilität bei großen Kontexten)

Antwortverschlankung und -überwachung für den ChatGPT ↔ DSH-Connector bei langen Laufzeiten und Sitzungen mit großem Kontext (Kompatibilitätsschicht, Kette unverändert):

• sessions_get Standard-Zusammenfassung: Standardmäßig wird nur eine strukturierte Zusammenfassung zurückgegeben (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, ohne messages). Die Zusammenfassung wird vom Knoten-Agenten erzeugt: Er fragt bei DSH nur die letzten 20 Nachrichten an (SUMMARY_WINDOW), current_goal ist die handlungsstärkste Benutzeranweisung im Fenster (mit Quell-seq), recent_evidence wird per Regex-Heuristik extrahiert, verdächtige Credential-Zeilen werden vor dem Eintritt in alle Zusammenfassungsfelder entfernt (safety_sanitized-Markierung). Gemessene Basiswerte: frühe große Sitzung 75KB → 1.2KB Antwort; Informationsfidelity-Abnahme-Fixture (1000 Nachrichten) ca. 107KB → 0.7KB, Standardantwort <1KB. Cache in ~/.dsh/helm/summaries/<session_id>.json (60s TTL, nach Schreiboperationen ungültig).

• Vollständiger Verlauf bei Bedarf: include_messages=true (konfigurierbar mit max_messages, Standard 20) liefert vollständige Nachrichten; der Parameter before_seq wird durchgereicht, aber DSH 0.1.1 implementiert kein echtes Paging (Messungen: max_messages ≤100 und beforeSeq wirkungslos) – Verlauf älter als die letzten 100 Nachrichten ist derzeit nicht erreichbar, history_ref kennzeichnet den erreichbaren Bereich explizit (reachable_max_messages:100); alte Aufrufe (ohne Parameter) gehen automatisch in die Zusammenfassung, der Aufrufer muss seine Parameter nicht ändern, aber beachten: Der Rückgabewert wechselt von vollständigen Nachrichten zur Zusammenfassung (bei Bedarf an Originaltext explizit include_messages=true).

• Response Size Guard: Einheitliche Middleware für alle MCP-Antworten des Hubs, MAX_RESPONSE_BYTES=50000; bei Überschreitung automatisches smart-truncate (bleibt gültiges JSON, mit truncated-Metadaten), Log [mcp-guard] <tool> original=.. returned=.. truncated.

• Gesundheitsüberwachung: Der Hub erhält GET /metrics (Anfragenzahl/durchschnittliche und maximale Antwortbytes/Truncation- und Fehlerzähler/aktive Verbindungen/perTool-Details), GET /readyz (HA-Quorum-Bereitschaft), GET /version; das Dashboard erhält einen neuen Tab „MCP-Steuerungsebene".

• Fehlerkorrektur-Einschub/sofortige Intervention: sessions_prompt unterstützt mode=queue|steer (Standard queue, Warteschlangensemantik unverändert); steer umgeht die Warteschlange und injiziert über die DSH-Host-API in laufende Runden (strukturierte Rückgabe steered/queued/rejected/unavailable), das DSH-Verlaufsereignis agent/inbox/spliced bestätigt die Injektion. Design-Review und Implementierungsdetails siehe docs/priority-queue.md.

Plattformunterstützung

Kerncode ohne plattformspezifische Logik (launchd/osascript/PowerShell vollständig isoliert in packages/platform und packages/presence); macOS-Zweimaschinen-Setup (Tailscale) auf echter Hardware verifiziert, Linux/Windows Verifikation auf echter Hardware ausstehend.

Dokumentation

Sicherheitskernpunkte

• Credentials: ~/.dsh/helm/node.json (Knoten-Token) und Daemon-Token-Datei jeweils 0600; die Hub-Token-Tabelle wird über die Umgebungsvariable DSH_HELM_TOKEN injiziert (nicht auf Platte); Token erscheinen nicht in argv/git/Logs; Tunnel-Credentials werden mit env:-Syntax injiziert.

• Bindung: Der Hub bindet standardmäßig nur 127.0.0.1; für maschinenübergreifend Tailscale + --bind <tailnet-ip> empfohlen, --mcp-bind 127.0.0.1 hält MCP nur auf loopback. Hub-MCP (3471) v1 ohne Authentifizierung – strikt verboten, öffentlich zu exponieren; Produktions-Mesh über wss:// (TLS durch Reverse-Proxy/externen https-Server).

• fail-closed: Destruktive Operationen (sessions_prompt/sessions_resume) ohne eindeutiges Ziel werden abgelehnt; im presence-Mehrdeutigkeitsfenster wird nicht geraten.

• Keine Speicherung von Inhalten: Der Store speichert nur Metadaten und Audit, keine DSH-Sitzungsinhalte.

• Detailliertes Sicherheitsmodell siehe docs/security.md und docs/threat-model.md.

Status- und Fakten-Schichtung

Version v0.1.0. Automatisierte Verifikation vollständig grün (Unit + End-to-End-Integrationstests des vollständigen Protokolls mit zwei Fake-Knoten + Informationsfidelity-Abnahme: 399/399 (48 Dateien), build/lint sauber); macOS-Zweimaschinen-Tailscale-Smoke-Test auf echter Hardware abgeschlossen. doctor/dashboard/install implementiert; CLI-Online-RPC-Befehle (nodes/node/route-explain/presence/rotate-token) benötigen weiterhin eine Live-Hub-Verbindung (aktuell Hinweis requires live hub connection, für den nächsten Meilenstein geplant); dieselbe Funktionalität ist über Hub-MCP-Tools (nodes_list usw.) nutzbar; session handoff v1 gibt ehrlich unsupported zurück.

Fähigkeitsstatus nach Beweisstärke geschichtet (nicht vermischt):

Ausdrücklich nicht zugesagt: Keine Production-Ready-Garantie; HA ist Redundanz der selbstverwalteten Steuerungsebene, keine SLA / Zero-Downtime-Zusage; keine Zusage für Fähigkeiten an den offiziellen OpenAI-Grenzen (Tunnel-Mehrinstanz-HA, automatische Schlüsselrotation), solange diese nicht bestätigt sind. Abnahmeergebnis: CONDITIONAL PASS (Fidelity und Sicherheit geschlossen, Vollständigkeit durch die DSH-0.1.1-Protokollgrenzen eingeschränkt).

ops-Skripte

Alle Skripte bash-3.2-kompatibel, [dsh-helm]-Ausgabepräfix, idempotent, prüfen nur und modifizieren keine bestehenden Dienste auf Produktionsports (3080/3457/3458).