hermes-dsh-bridge

Plugin MCP especializado en puentear Hermes ↔ DeepSeek Harness: inicia un servidor MCP dentro de Harness, permitiendo que clientes MCP externos (como Hermes) manejen el Agent de Harness para ejecutar tareas de codificación reales.

Hermes es el cerebro, Harness es las manos.

Por qué existe

Harness incluye un potente runtime de agentes (herramientas, LLM, Agent, sesiones), pero es un aplicación de Cordis que otros agentes no pueden adaptar. Este plugin le da la vuelta a Harness: lanza un servidor MCP real (StreamableHTTP) dentro de Harness, conectando los servicios centrales de Harness (ctx.agents / ctx.agentPresets / ctx.tools), para que un “cerebro” externo lo asigne tareas reales a las “manos” de Harness.

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

Herramientas (19)

Tareas

Sesiones

Archivos (con restricción de path jail)

Estado y configuración

Presets

Meta

Resultado estructurado y estadística

Cada agent_run devuelve un resultado estructurado y añade las estadísticas de uso de esa ronda:

{
  "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
  }
}

Se crea la presión: el cliente alimenta la memoria como context en cada tarea y vuelve a guardar el resultado (changes/verification/leftovers) en la memoria del cliente para la siguiente.

Instalación

Opción A — instalar desde npm en un perfil de Harness

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

Opción B — compilar desde el código fuente

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

⚠️ Peligro de doble paquete (obligatorio): Harness resuelve @deepseek-ai/* desde su árbol global; los propios node_modules delplugin pueden tener una copia en paralelo — dos instancias de módulo ⇒ Symbol no coincide ⇒ el Agent pierde silenciosamente todas las herramientas (manifestado como agent_run devuelve solo texto <tool_calls> y toolCalls siempre es una matriz vacía). Solución: se vincula simbólicamente la dependencia @deepseek-ai/* del plugin al árbol global de Harness:

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 no está publicado en el registro de npm, solo existe en el árbol global de Harness, por lo que debe enlazarse simbólicamente).

Configuración de Parche

Al final de cordis.patch.yml del perfil de Harness (o el archivo de parches equivalente), añade:

- 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

Reiniciar y verificar

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

🤖 Guía de instalación con IA en un clic (instrucciones de instalación para Agent IA)

Los pasos siguientes son para otro Agente de IA: si eres un agente de IA y quieres instalar este plugin en el entorno de Harness que gestionas, ejecuta estrictamente los pasos numerados comprobando la salida tras cada uno antes de continuar.

Comprobaciones previas (primeros 3 pasos)

1. Confirma que Node ≥ 22.18: node --version (si es menor de 22.18 se mostrarán errores de falta de zstd/stripTypeScriptTypes; antes actualiza Node).

2. Confirma que existe el perfil de Harness: ls ~/.dsh/profiles/ (busca el nombre de perfil que quieres instalar; de aquí en adelante se indicará <PROFILE>).

3. Confirma que existen el árbol global de Harness: npm root -g (de aquí en adelante se usa $GLOBAL_TREE en lugar de npm root -g).

Pasos de instalación (se pueden copiar y ejecutar)

# ① 安装插件到 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

Criterios de aceptación

• dsh_mcp.py list debe mostrar ≥ 19 herramientas, e incluir obligatoriamente agent_run, session_stats, preset_set, fs_read.

• status_get debe devolver version con valor 0.3.0; y provider / model deben tener los valores que has configurado.

• Si ejecutas una tarea de prueba python3 examples/hermes_dsh_mcp.py run '回复:安装成功', obtén un resultado con el campo stats.

Fallos habituales y contramedidas (consulte a los que encuentre)

La solución completa está en docs/TROUBLESHOOTING.md.

Documentación

• docs/TOOLS.md — referencia completa de las 19 herramientas (entrada/salida/límites/códigos de error)

• docs/CONFIG.md — configuraciones, valores predeterminados seguros

• docs/TROUBLESHOOTING.md — problemas conocidos (parseo de SSE, truncado a 8KB, alerta de doble paquete…)

• docs/SECURITY.md — modelo de amenazas

• examples/hermes_dsh_mcp.py — client MCP en Python sin dependencias (solo biblioteca estándar)

Posicionamiento

Es adecuado como herramienta secundaria más que para uso diario: para el código diario, canaliza directamente tu main agent. Lóregalo cuando necesites aislar el contexto (un gran refactor puede reventar el contexto del cliente) o para ejecutar en paralelo tareas independientes.

• El agente se reutiliza por cwd (evita volver a cargar el contexto del proyecto en cada llamada).

• Bash está en entorno aislado (workspace-write): en la máquina anfitriona instala bubblewrap; si no, se rechazarán los comandos de escritura.

• Los bloques razonamiento/pensamiento se descartan antes de devolverse (doble capa, ambas en el plugin y con protección a nivel textual).

Licencia

GPL-3.0-only, seura de acuerdo a y partes MIT upstream — ver NOTICE.md.