dsh-helm

Многоузловая управляющая плоскость DSH: расширение однокомпьютерного коннектора «ChatGPT ↔ DSH» до многоузловой управляющей плоскости. DeepSeek Harness (DSH) на нескольких машинах регистрируются в едином хабе через агенты узлов (node-agent), и 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: только исходящее соединение с хабом (mesh WS), внутренний мост к MCP локального helm-демона (127.0.0.1:3457/mcp).

• Хаб — единственная точка входа: ChatGPT вызывает инструменты через MCP хаба (3471), хаб пересылает на нужный узел по политике маршрутизации; количество узлов прозрачно для ChatGPT.

• Совместимость с одиночной машиной: при одном узле и node_id == hub defaultNodeId маршрутизация и поведение вызова инструментов эквивалентны однокомпьютерному демону (summary/guard/steer — надстроечные улучшения, не влияют на существующую семантику вызовов).

Возможности

• Регистрация нескольких узлов и heartbeat: идентичность узла node_id (UUID) + HMAC-рукопожатие с вызовом; heartbeat 15 с, аренда 45 с; при таймауте heartbeat агент новой версии автоматически переподключается (обнаружение полуоткрытых соединений и переподключение).

• Пятиуровневая маршрутизация: явный 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: 19 инструментов однокомпьютерного демона (code_*/sessions_*/projects_list/supervisor_health и т.д., параметры snake_case без изменений) сохранены как есть, добавлены nodes_list/node_get/route_explain/presence_claim/presence_release; все маршрутизируемые инструменты имеют необязательный target_node.

• presence: ручное объявление (пин на 10 минут) + автоматическое обнаружение активного приложения macOS (desktop sidecar); в 15-секундном окне неоднозначности при высокой уверенности по двум узлам → признаётся ambiguous, автоматический выбор не выполняется.

• Многоуровневое состояние здоровья: control / channel / adapter / datapath / serena / tunnel — каждый уровень отчитывается независимо, никогда не сворачивается в единый status: ok.

• Агрегация между узлами: workspaces_list/sessions_list/agents_list/projects_list возвращают плоские результаты по нескольким узлам (каждая запись с node_id).

• Аудит и журнал маршрутизации: регистрация узлов, heartbeat, решения маршрутизации, изменения presence — всё сохраняется в БД (audit/route_log).

• Красная линия метаданных: хранилище хаба содержит только метаданные (узлы/аренды/сессии и каталоги рабочих областей/аудит), никогда не хранит содержимое сессий 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-демон (127.0.0.1:3457/mcp, Bearer token в ~/.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_id и token из node.json администратору хаба по защищённому каналу, затем выполните на машине хаба (идемпотентно: добавление/обновление таблицы токенов, автоматическая перезагрузка службы launchd):

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

Подробный процесс см. в docs/onboarding.md.

Подключение ChatGPT

Два пути, выбор по этапу развёртывания:

• A. Прямое подключение одной машины (начальный этап): если на локальной машине уже есть helm-демон, хаб рассматривает локальный узел как local node, поведение идентично однокомпьютерному коннектору, туннель не требуется.

• B. Многоузловой (управляющая плоскость, рекомендуется): OpenAI Secure MCP Tunnel подключается к MCP хаба (3471), ChatGPT — одна точка входа для управления всеми узлами.

Полный учебник на стороне OpenAI Platform (создание туннеля / привязка workspace / создание API key / параметры tunnel-client / прокси) см. в docs/chatgpt-tunnel-setup.md; на стороне ChatGPT Web (режим разработчика / создание коннектора / тестирование) см. в docs/chatgpt-connector.md.

Компромисс двух топологий: каждый демон со своим туннелем+коннектором (несколько точек входа, каждый управляет своим), или один туннель хаба + один коннектор для управления N узлами (единая точка входа, рекомендуется — маршрутизация хаба target_node/правила маршрутизации, ответы с node_name).

HA управляющей плоскости (двойная Control Plane)

Два хаба образуют кворум (2/2) управляющей плоскости; при отказе любого из них другой продолжает обслуживать чтение маршрутов и точки входа узлов.

• Роли и аренда: побеждает меньший --cp-priority — становится лидером (единственный писатель); лидер каждые 10 с продлевает аренду у peer; если peer недоступен дольше TTL аренды (--cp-failover-ms, по умолчанию 45 с) → обе стороны переходят в read-only-no-quorum, операции записи возвращают QUORUM_LOST. follower никогда не повышается в одностороннем порядке — при потере кворума только чтение без записи (CAP: приоритет безопасности).

• Восстановление: переподключение peer → полная синхронизация реестра → принудительные перевыборы (term+1) → подтверждение аренды обеими сторонами → восстановление записи. В течение всего окна восстановления обе стороны остаются в режиме только чтения.

• Несколько endpoint у агента: в node.json настраиваются hub_url + fallback_urls, при переподключении циклический перебор с закреплением после успеха; при сбое автоматическое переключение на вторую CP.

• Наблюдаемость: GET /cp-status возвращает role/phase/writeMode/quorum/term/leaderId/peers/syncOk/leaseEpoch/failoverCount; dsh-helm doctor и карточка «控制面 HA» в Dashboard отображают напрямую.

• HA точки входа ChatGPT: --mcp.server-url у OpenAI tunnel-client ограничен каналом, без 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 на обеих сторонах содержит обе таблицы токенов узлов (при переключении любого агента другая CP сможет аутентифицировать). Если MCP должен быть доступен между машинами, используйте --mcp-bind <tailnet-ip> (ограждение Tailscale ACL, в однокомпьютерном сценарии остаётся loopback).

Сопряжение устройств (добавление нового DSH-устройства)

Dashboard «新增 DSH 设备» → генерация одноразового кода сопряжения (действителен 10 минут, одноразовое потребление, хранится только хэш); на новой машине выполняется dsh-helm join --control-plane ws://<hub>:3470 --code <code> для входа в сеть (генерация долгосрочного node token, запись в ~/.dsh/helm/node.json, хаб хранит только hash/статус). 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). Сводка генерируется агентом узла: у DSH запрашиваются только последние 20 сообщений (SUMMARY_WINDOW), current_goal — наиболее действенная пользовательская инструкция в окне (с исходным seq), recent_evidence — извлечение регулярными выражениями, строки с подозрением на учётные данные удаляются до попадания в любое поле сводки (флаг safety_sanitized). Замеры на практике: ответ ранней большой сессии 75 КБ → 1,2 КБ; приёмочный fixture информационной точности (1000 сообщений) ~107 КБ → 0,7 КБ, ответ по умолчанию <1 КБ. Кэш в ~/.dsh/helm/summaries/<session_id>.json (TTL 60 с, инвалидация после операций записи).

• Полная история по запросу: 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: единый middleware для всех MCP-ответов хаба, MAX_RESPONSE_BYTES=50000; при превышении автоматическое smart-truncate (гарантированно остаётся корректным JSON, добавляются метаданные truncated), журнал [mcp-guard] <tool> original=.. returned=.. truncated.

• Мониторинг состояния: в хабе добавлены GET /metrics (количество запросов/средний и максимальный размер ответа в байтах/счётчики усечений и ошибок/активные соединения/детализация perTool), GET /readyz (готовность HA-кворума), GET /version; в Dashboard добавлена вкладка «MCP 控制面».

• Внеочередная коррекция/немедленное вмешательство: sessions_prompt поддерживает mode=queue|steer (по умолчанию queue — семантика очереди без изменений); steer в обход очереди через host API DSH внедряется в выполняющийся раунд (структурированный возврат 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 (node token) и файл токена демона — оба 0600; таблица токенов хаба внедряется через переменную окружения DSH_HELM_TOKEN (не сохраняется на диск); токены не появляются в argv/git/журналах; учётные данные туннеля внедряются синтаксисом env:.

• Привязка: хаб по умолчанию привязан только к 127.0.0.1; для межмашинного доступа рекомендуется Tailscale + --bind <tailnet-ip>, --mcp-bind 127.0.0.1 сохраняет MCP только на loopback. MCP хаба (3471) v1 без аутентификации — категорически запрещено прямое раскрытие в публичную сеть; в production mesh используется wss:// (TLS обеспечивается обратным прокси/внешним https-сервером).

• fail-closed: деструктивные операции (sessions_prompt/sessions_resume) без чёткой цели отклоняются; в окне неоднозначности presence не выполняются догадки.

• Без хранения содержимого: store хранит только метаданные и аудит, содержимое сессий DSH не сохраняется.

• Подробная модель безопасности — в docs/security.md и docs/threat-model.md.

Расслоение статуса и фактов

Версия v0.1.0. Автоматическая проверка полностью зелёная (модульные тесты + сквозные интеграционные тесты полного протокола с двумя фейковыми узлами + приёмка информационной точности: 399/399 (48 файлов), build/lint чистые); дымовой тест на реальном оборудовании macOS с двумя машинами через Tailscale завершён. doctor/dashboard/install реализованы; онлайн RPC-команды CLI (nodes/node/route-explain/presence/rotate-token) всё ещё требуют подключения к живому хабу (в настоящее время выводят requires live hub connection, планируется в следующей вехе), те же возможности доступны через 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).