hermes-dsh-bridge

Специализированный MCP-плагин — мост Hermes ↔ DeepSeek Harness: поднимает MCP-сервер внутри Harness, чтобы внешние MCP-клиенты (например, Hermes) могли управлять агентом Harness для настоящей кодинг-работы.

Hermes — мозг, Harness — руки.

Зачем это нужно

В Harness уже есть мощный агентный рантайм (инструменты, LLM, агенты, сессии), но это Cordis-приложение — другие агенты им не управляют. Этот плагин выворачивает Harness наизнанку: запускает внутри Harness настоящий MCP-сервер (StreamableHTTP), связывая ядро Harness (ctx.agents / ctx.agentPresets / ctx.tools) и позволяя внешнему «мозгу» раздавать настоящую работу «рукам» 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

Инструменты (19)

Задачи

Сессии

Файлы (под ограничением path jail)

Статус и конфигурация

Пресеты

Мета

Структурированный результат и статистика

Каждый agent_run возвращает структурированный результат и статистику расхода за этот проход:

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

Замкнутый контур: клиент передаёт память как context в каждую задачу, результат (changes/verification/leftovers) снова сохраняется в память клиента для следующего раунда.

Установка

Способ A — установка в профиль Harness из npm

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

Способ Б — сборка из исходников

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 (обязательно к прочтению): Harness подключает @deepseek-ai/* из глобального дерева, а в node_modules самого плагина могут оказаться параллельные копии — два экземпляра модуля ⇒ Symbol не совпадает ⇒ агент незаметно лишается всех инструментов (проявляется тем, что agent_run печатает лишь текст <tool_calls>, а toolCalls всегда пуст). Исправление: симлинк @deepseek-ai/*-зависимостей плагина на глобальное дерево 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 не опубликован в npm registry и существует только в глобальном дереве Harness — симлинк обязателен.)

Patch-конфигурация

Добавьте в конец файла cordis.patch.yml вашего профиля Harness (или эквивалентного patch-файла):

- 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

Перезапуск и проверка

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

🤖 Инструкция по установке в один клик для ИИ (для AI-агента)

Приведённые шаги рассчитаны на другого AI-агента: если вы AI-агент и устанавливаете этот плагин в управляемую вами среду Harness, строго выполняйте пронумерованные шаги ниже и после каждого шага сверяйте вывод перед продолжением.

Предварительные проверки (сначала эти 3 шага)

1. Если Node ≥ 22.18: node --version (при 22.18 ниже упадёт zstd/stripTypeScriptTypes — сначала обновите Node).

2. Проверьте, что целевой профиль Harness существует: ls ~/.dsh/profiles/ (название профиля ниже обозначено как <PROFILE>).

3. Проверьте, что глобальное дерево Harness существует: npm root -g (ниже $GLOBAL_TREE заменяет npm root -g).

Шаги установки (можно копировать и запускать)

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

Критерии приёмки

• dsh_mcp.py list выводит ≥ 19 инструментов, среди них обязательно agent_run, session_stats, preset_set, fs_read.

• У status_get параметр version в ответе равен 0.3.0, а provider/model — значения из вашей конфигурации.

• Прогоните пробную задачу: python3 examples/hermes_dsh_mcp.py run '回复:安装成功' — ответ содержит поле stats.

Типовые сбои и действия (смотреть, когда столкнётесь)

Полное руководство по устранению — docs/TROUBLESHOOTING.md.

Документация

• docs/TOOLS.md — полный справочник по 19 инструментам (вход/выход/лимиты/коды ошибок)

• docs/CONFIG.md — поля конфигурации и безопасные значения по умолчанию

• docs/TROUBLESHOOTING.md — известные грабли (SSE-разбор, 8KБ-бобрезка, dual-package hazard…)

• docs/SECURITY.md — threat model

• examples/hermes_dsh_mcp.py — MCP-клиент на Python из нуля зависимостей (только стандартная библиотека).

Позиционирование

Подходит как запасной инструмент, а не как главный каждый день: чтобы править код, запускайте своего основного Агента каждый день. Когда нужна изоляция контекста (большой рефакторинг выжжет клиентский контекст) или параллельное выполнение независимых задач — тогда за этим плагином.

• Сессии агента переиспользуются на основе cwd (не пере-загружается контекст проекта при каждом вызове).

• Bash изолируется в песочницу (workspace-write): на хосте должен быть установлен bubblewrap, иначе команды записи будут отклонены.

• Блоки reasoning/thinking вырезаются перед возвратом (двойная защита: на стороне плагина + текстовая фильтрация на уровне текста).

License

GPL-3.0-only, части MIT от вышестоящих компонентов сохранены — см. NOTICE.md.