hermes-dsh-bridge

Ein MCP-Plugin, das speziell Hermes ↔ DeepSeek Harness verbindet: Es startet einen MCP-Server innerhalb von Harness, sodass externe MCP-Clients (wie Hermes) die Agents von Harness für echte Codierungsaufgaben steuern können.

Hermes ist das Gehirn, Harness die Hände.

Warum das Plugin existiert

Harness bringt eine leistungsfähige Agent-Laufzeit mit (Werkzeuge, LLM, Agents, Sessions), aber es ist eine Cordis-Anwendung, die von anderen Agents nicht angesteuert werden kann. Dieses Plugin dreht Harness um: Es startet innerhalb von Harness einen echten MCP-Server (StreamableHTTP), verbindet die Harness-Kerndienste (ctx.agents / ctx.agentPresets / ctx.tools) und lässt externe Agents die eigentliche Arbeit an die „Hände“ von Harness übergeben.

Hermes (MCP client, 大脑)
   │  agent_run / task_inbox / fs_read / session_stats ... (HTTP)
   ▼
harness-mcp-server (MCP server, :8090)
   │  ctx.agents.create → mount 'standard' preset
   ▼
Harness agent — 完整工具集: bash, fs, todo, web…

Related MCP server: dsh-harness-mcp-server

Werkzeuge (19) – Anleitung

Aufgaben

Sessions

Dateien (durch path jail eingeschränkt)

Status und Konfiguration

Presets

Meta

Strukturierte Ergebnisse und Statistik

Jeder agent_run-Aufruf liefert strukturierte Ergebnisse inklusive der dies auf Verbrauchsstatistik dieser Runde:

{
  "sessionId": "...",
  "assistantText": "最终回答",
  "toolCalls": [{ "name": "bash", "args": "..." }],
  "toolResults": ["命令输出"],
  "changes": "改了什么",
  "verification": "怎么验证的",
  "leftovers": "遗留问题",
  "stats": {
    "rounds": 1, "steps": 3,
    "llmTime": 13.9, "toolTime": 0.04,
    "ttft": 3349, "tokensPerSec": 40.7,
    "cacheHitRate": 1, "inputTokens": 8831, "outputTokens": 157
  }
}

Geschlossener Kreislauf: Der Client gibt das Gedächtnis bei jedem Task als context mit und speichert die Ergebnisse (changes/verification/leftovers) danach wieder in seinem Gedächtnis, damit sie in der nächsten Runde verwendet werden können.

Installation

Option A — Aus npm in das Harness-Profil installieren

# 在 Harness profile 的 node_modules 下
cd ~/.dsh/profiles/<你的profile>/node_modules
npm install hermes-dsh-bridge

Option B — Quellcode selbst erstellen

git clone https://github.com/Emilia-awa/hermes-dsh-bridge.git
cd hermes-dsh-bridge
npm install && npm run build   # 产出 lib/index.js
# 把构建产物放进 Harness profile:
#   ~/.dsh/profiles/<你的profile>/node_modules/hermes-dsh-bridge

⚠️ Dual-Package-Hazard (unbedingt lesen): Harness löst @deepseek-ai/* aus dem globalen Baum auf. Das eigene node_modules des Plugins kann dabei parallele Kopien enthalten –– zwei Modulinstanzen ⇒ Symbol stimmt nicht mehr überein ⇒ der Agent verliert still alle Werkzeuge (sichtbar daran, dass agent_run nur den <tool_calls>-Text liefert und toolCalls permanent ein leeres Array ist). Lösung: Die @deepseek-ai/*-Abhängigkeiten des Plugins per Symlink in den globalen Harness-Baum leiten:

PROFILE=~/.dsh/profiles/<你的profile>/node_modules
GLOBAL=$(npm root -g)/@deepseek-ai/dsh/node_modules/@deepseek-ai
for pkg in cordis cosmokit dsh-agent dsh-llm dsh-session dsh-tools dsh-scope \
           dsh-agent-presets dsh-code-runtime dsh-system-prompt dsh-typert-protocol \
           dsh-attachment dsh-brand dsh-invariants dsh-timeout dsh-settings \
           dsh-home-paths dsh-atomic-write dsh-user-approval \
           cordis-plugin-include cordis-plugin-loader; do
  rm -rf "$PROFILE/@deepseek-ai/$pkg" && ln -sfn "$GLOBAL/$pkg" "$PROFILE/@deepseek-ai/$pkg"
done

(cordis-plugin-include/loader ist nicht auf der npm-Registry, sondern nur im globalen Harness-Baum; es muss per Symlink verknüpft werden.)

Patch konfigurieren

Hänge in deiner Harness-Profil-Datei cordis.patch.yml (oder einer gleichwertigen Patch-Datei) am Ende Folgendes an:

- insert:
    - id: hermes-dsh-bridge
      name: 'hermes-dsh-bridge'
      config:
        http: true
        port: 8090
        host: 127.0.0.1        # 默认仅本机; 暴露前必须加认证
        # authToken: '你的随机长token'     # 可选: Bearer token 认证
        # workspaceRoots: ['/workspace']  # 可选: cwd 白名单
        # enableFsWrite: true             # 可选: 开启 fs_write(默认关)
        # ⚠️ 必须显式声明 provider/model, 否则 agent 组装会因空 {{model}} 崩溃:
        provider: opencode-go
        model: deepseek-v4-flash

Neustart prüfen

systemctl restart dsh.service        # 或你管理 Harness 的方式
# 验证 19 个工具全在线:
python3 examples/hermes_dsh_mcp.py list
python3 examples/hermes_dsh_mcp.py call status_get '{}'

🤖 AI-Ein-Klick-Installationsanleitung (Installationsanleitung für AI-Agenten)

Die folgenden Schritte sind für einen AI-Agenten gedacht: Wenn du ein KI-Agent bist und dieses Plugin in die von dir verwaltete Harness-Umgebung einrichten möchtest, führe die nummerierten Schritte der Reihe nach aus. Prüfe nach jedem Schritt die Ausgabe, bevor du fortfahren kannst.

Vorab-Prüfungen (zuerst diese 3 Schritte)

1. Prüfe Node ≥ 22.18: node --version (unter 22.18 wird ein Fehler bei zstd/stripTypeScriptTypes gemeldet; aktualisiere zuerst Node).

2. Prüfe, ob das Ziel-Harness-Profil existiert: ls ~/.dsh/profiles/ (Profile Name, du in späiter Instanz mit <PROFILE> ersetzt).

3. Prüfe, ob der globale Harness-Baum existiert: npm root -g (ersetze im Folgenden npm root -g durch $GLOBAL_TREE).

Installationsschritte (kopier- und ausführbar)

# ① 安装插件到 profile
cd ~/.dsh/profiles/<PROFILE>/node_modules
npm install hermes-dsh-bridge        # 未发布到 npm 前用方式 B（源码）

# ② 修复 dual-package hazard: 把所有 @deepseek-ai/* 和 cordis-plugin-* symlink 到全局树
GLOBAL_TREE=$(npm root -g)/@deepseek-ai/dsh/node_modules/@deepseek-ai
for pkg in cordis cosmokit dsh-agent dsh-llm dsh-session dsh-tools dsh-scope \
           dsh-agent-presets dsh-code-runtime dsh-system-prompt dsh-typert-protocol \
           dsh-attachment dsh-brand dsh-invariants dsh-timeout dsh-settings \
           dsh-home-paths dsh-atomic-write dsh-user-approval \
           cordis-plugin-include cordis-plugin-loader; do
  rm -rf "@deepseek-ai/$pkg" 2>/dev/null
  ln -sfn "$GLOBAL_TREE/$pkg" "@deepseek-ai/$pkg"
done

# ③ 在 profile 的 cordis patch 文件(cordis.patch.yml)末尾追加配置
cat >> ~/.dsh/profiles/<PROFILE>/cordis.patch.yml <<'EOF'
- insert:
    - id: hermes-dsh-bridge
      name: 'hermes-dsh-bridge'
      config:
        http: true
        port: 8090
        host: 127.0.0.1
        provider: opencode-go      # ← 换成你自己的 provider id
        model: deepseek-v4-flash   # ← 换成你自己的 model id
EOF

# ④ 重启 Harness(注意: 若你正跑在 Harness 里, 用 systemd-run 脱离进程树重启)
systemctl restart dsh.service

# ⑤ 验证: 等 8 秒后检查 MCP server 起来 + 工具列表
sleep 8
curl -s -X POST http://127.0.0.1:8090/mcp \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"ai-setup","version":"1.0"}}}' \
  | tail -1 | head -c 300
python3 examples/hermes_dsh_mcp.py list | grep -cE "agent_run|session_stats|preset_set"   # 期望 ≥ 3

Abnahmekriterien

• dsh_mcp.py list gibt mindestens 19 Werkzeuge aus, u. a. agent_run, session_stats, preset_set, fs_read.

• status_get liefert version = 0.3.0, provider/model wie von dir konfiguriert.

• Führe eine Smoke-Test mit python3 examples/hermes_dsh_mcp.py run '回复:安装成功' aus,übere, das Ergebnis das Feld stats enthält.

Häufige Fehler und Gegenmaßnahmen (nur wenn nötig)

Die vollständige Fehlersuche bei docs/TROUBLESHOOTING.md.

Dokumentation

• docs/TOOLS.md — vollständige Referenz zu den 19 Werkzeugen (Argumente/Rückgabewerte/Limits/Fehlercodes)

• docs/CONFIG.md — Konfigurationsparameter, sicherheitsrelevante Standardwerte

• docs/TROUBLESHOOTING.md — bekannte Fallstricken (SSE-Parsen, 8-KB- Absch, Dual-Package-Hazard …)

• docs/SECURITY.md — Bedrohungsmodell

• examples/hermes_dsh_mcp.py — Python-MCP-Client ohne externe Dependencies (nur Standardbibliothek)

Weiteres zu Ziel und Positionierung

Wird nur als Fallback-Tool und nicht als Alltagswerkzeug empfohlen: Für regelmäßige Codeänderungen steuere direkt deinen Haupt-Agenten. Greif nur dann zu, wenn es um Kontextisolation (große Refactorings würden den Clientkontext sprengen) oder parallele Ausführung unabhängiger Aufgaben geht.

• Agent-Sessions werden nach cwd wiederverwendet (vermeidet das erneute Laden des Projekt "Kontext" bei jedem Aufruf).

• Bash ist gesandboxed (workspace-write): Auf dem Hoster muss bubblewrap installiert sein, sonst werden Schreibbefehle abgelehnt.

• Reasoning-/Thinking-Blöcke werden vor der Rückgabe entfernt (doppelte Seite + Text "Ebene"-Fallback).

Lizenz

GPL-3.0-only, mit Hinweis auf das MIT-LICENSE-upstreams – siehe NOTICE.md.