dsh-mcp ⚡

Быстро и дёшево — тяжёлая работа выполняется на deepseek-v4-flash.

Исполнительный слой для MCP-агентов — на базе локального DeepSeek Harness.

Инструменты агентного кодинга дороги и медленны по одной причине: родительская модель читает файлы по одному. dsh-mcp переворачивает это — родительский агент сохраняет рассуждение, локальный DeepSeek Harness выполняет тяжёлую работу: пакетное чтение, редактирование и запуск команд по тарифам deepseek-v4-flash, на вашей машине.

Работает с любым MCP-клиентом · протестирован End-to-End с Claude Code

🌐 English · 简体中文 · 日本語

Зачем: быстро и дёшево — по дизайну

Боль. Долгие задачи с множеством файлов — это то, где агентные инструменты сжигают деньги и время: родительская модель сама перемалывает каждый файл — одно Read на файл, циклы исследования, контекст, который растёт и дрейфует. Вы платите по тарифам родительской модели за чтение и ждёте, пока модель делает это последовательно.

Решение. Один вызов delegate_to_dsh передаёт всю токено-тяжёлую подзадачу свежему, сфокусированному агенту DeepSeek Harness, работающему на deepseek-v4-flash внутри вашего рабочего пространства. Весь файловый ввод-вывод происходит там — пакетно, локально, дёшево. Родитель остаётся в цикле для того, что действительно требует мозга: планирование, диагностика, решения, верификация.

Измерено на 100 долгих задачах в стиле SWE-bench (гетерогенная конфигурация моделей: родитель = deepseek-v4-pro, DSH = deepseek-v4-flash; ветка B запускает ту же родительскую модель без плагина):

Быстрее, точнее — и разрыв в точности теперь статистически значим (p = 3.7×10⁻⁴ при n=100), а не просто направленный. Дорогое чтение теперь выполняется на deepseek-v4-flash. Полный отчёт · Воспроизвести

Как это работает

Промпт, использованный для генерации этого изображения, находится в docs/architecture-image-prompt.md.

• Стандартный MCP stdio-сервер. Любой клиент, говорящий на MCP, может его использовать — Claude Code — это клиент, который мы проверили end-to-end (реальные API-вызовы, запуски из поддиректорий, китайский язык, пробелы в путях).
• Модель родительского агента. Каждое делегирование — это одна самодостаточная подзадача; DSH — это worker без состояния (новый процесс на каждый вызов — нет сессии, которую можно повредить).
• Ноль конфигурации, работает из коробки. CLI DSH обнаруживается автоматически (переопределение через env → соседний checkout → дочерний checkout → установленный в %USERPROFILE%\.dsh).
• Windows-first. process.execPath + явный argv, shell: false — никаких багов с кавычками, никаких .cmd-обёрток, пробелы в путях просто работают.

Быстрый старт

Шаг 1 — соберите один раз

cd dsh-mcp
npm install
npm run build                      # → dist\index.js

Шаг 2 — зарегистрируйте в вашем MCP-клиенте (Claude Code показан как пример)

claude mcp add dsh `
  --transport stdio `
  --env DEEPSEEK_API_KEY=sk-... `
  -- node D:\path\to\dsh-mcp\dist\index.js

claude mcp list                    # confirm "dsh" is listed

Это стандартный MCP-сервер — тот же dist\index.js также работает с OpenAI Codex, Cursor, VS Code и любым другим MCP-клиентом (см. Развёртывание).

Шаг 3 — перезапустите Claude Code, затем сделайте первое делегирование

Claude Code загружает MCP-серверы при запуске, поэтому перезапустите его внутри любого проекта. Затем просто попросите обычными словами:

Пусть DSH прочитает README.md и package.json этого проекта и сообщит название проекта и первый абзац README. Не читай файлы сам — делегируй всё.

Вы увидите, как Claude вызывает delegate_to_dsh, и ответ вернётся через секунды. DSH работает в вашем корне проекта — никогда в каталоге dsh-mcp.

delegate_to_dsh не появляется? Выполните claude mcp list снова — если сервер не запустился, он сообщит об ошибке там. Перейдите к Устранению неполадок.

Бенчмарк

100 долгих задач с множеством файлов в двух партиях (01–50: исправление багов, рефакторинг, миграции, реализация по спецификации, разработка через тесты, аудит; 51–100: harder — глубокие потоки данных, асинхронные гонки, конечные автоматы, парсеры, кэши, межпроцессное состояние) · автоматизированная проверка эталонных результатов (выполнение утверждений + проверка stdout; чистые фикстуры должны падать, эталонные исправления должны проходить) · гетерогенная настройка моделей: родитель = deepseek-v4-pro на обеих ветках, DSH = deepseek-v4-flash на ветке A · полный отчёт: tests/bench/bench-report.md · примечание к эксперименту: Claude Code в этом бенчмарке работает на ядре deepseek-v4-pro (настраивается через переменную окружения ANTHROPIC_MODEL) — родитель — это модель DeepSeek, а не Anthropic, на обеих ветках. Таким образом, разница заключается именно в плагине: один и тот же родитель DeepSeek, с dsh-mcp и без него · набор данных: tests/bench/tasks.mjs

О чём говорят цифры

• Каждый сбой чистого агента — это сбой «сделано наполовину». 5 из 11 — это межфайловые задачи (переименования, миграции журналов, разделение утилит), где чистый агент изменил ссылки, но оставил старый файл, или мигрировал 3 из 5 файлов; 5 — это точечные задачи, где он исправил одну ошибку из двух, экранировал 3 из 5 HTML-символов, дедуплицировал, но не отсортировал. DSH проверяет внутри делегирования и ловит остатки перед возвратом результата.
• Многофайловое исследование остаётся самым большим выигрышем — пакетное «чтение N файлов + анализ» в одном делегировании против построчного чтения, которое теряет ранний контекст.
• Теперь статистически значимо. Точный тест Фишера на точность (100% против 89%, n=100): p = 3.7×10⁻⁴ (< 0.001). Пилотный запуск на 20 задачах был лишь ориентировочным; на 100 задачах разрыв реален.
• Более сложная партия (51–100) делает плагин лучше, а не хуже — ветка A: 100% в обеих партиях, среднее 65с на сложной партии; ветка B: 88% → 90%, но в целом остаётся 11 сбоев.
• Честное исключение — одно извлечение общего модуля (10) было медленнее через DSH (многофайловые перезаписи с возвратом). Ничего подобного не повторилось в сложной партии.

Воспроизведение:

DEEPSEEK_API_KEY=sk-... node tests\bench\run-bench.mjs AB 01-50     # both arms, 100 tasks
DEEPSEEK_API_KEY=sk-... node tests\bench\run-bench.mjs AB 51-100    # (range filter)
DEEPSEEK_API_KEY=sk-... node tests\e2e-headless.mjs                 # real E2E (A/B/C/D)
DEEPSEEK_API_KEY=sk-... node tests\long-horizon-e2e.mjs             # multi-delegation loop

Ключи попадают только во временный mcp.json внутри песочницы и удаляются при выходе — никогда не записываются в репозиторий и не выводятся.

Инструменты

Одно семейство инструментов, разделённое по ответственности, чтобы родительский агент выбирал по намерению (имя инструмента + описание — это входные данные для решения модели):

Все инструменты делегирования используют одну схему: task (обязательно), cwd (необязательно), timeoutMs (переопределение DSH_MCP_TIMEOUT_MS для конкретного вызова) и trackChanges (по умолчанию true).

Отслеживание изменений — у чёрного ящика появляется хвост. Безголовый CLI DSH возвращает только своё финальное сообщение: ни диффа, ни списка файлов. Поэтому каждое делегирование создаёт снимки вашего рабочего пространства до и после и добавляет блок [mcp] к результату, чтобы родитель мог видеть, что делегирование реально затронуло:

<DSH final output>

[mcp] exitCode: 0
[mcp] durationMs: 45210
[mcp] cwd: D:\workspace\foo
[mcp] changedFiles: 2
[mcp]   M src/store.js      (modified)
[mcp]   A src/store.test.js (added)

Используйте trackChanges: false (или DSH_MCP_TRACK_CHANGES=0), чтобы пропустить снимки на очень больших репозиториях. Каталоги зависимостей/сборки (node_modules, .git, dist, build, coverage, …) и скрытые каталоги всегда исключаются.

Ограничения категорий обеспечиваются шаблонами задач, а не CLI — в безголовом режиме DSH нет флага «только чтение». Отслеживание изменений — это страховка: если dsh_investigate всё же что-то изменил, список [mcp] changedFiles раскрывает это, и родитель может сам проверить файлы.

Развёртывание

dsh-mcp — это стандартный MCP-сервер stdio. Любой клиент, поддерживающий MCP, может Разместите его — Claude Code, OpenAI Codex, Cursor, VS Code, Claude Desktop или ваш собственный инструментарий. Сервер и семейство инструментов dsh идентич everywhere; отличается только шаг регистрации. Claude Code — это клиент, который мы проверили end-to-end.

Claude Code (одна команда — пример)

claude mcp add dsh `
  --transport stdio `
  --env DEEPSEEK_API_KEY=sk-... `
  -- node D:\path\to\dsh-mcp\dist\index.js

claude mcp list

OpenAI Codex

Codex загружает MCP-серверы из своего конфига в %USERPROFILE%\.codex\config.toml (на уровне проекта: .codex\config.toml). Добавьте:

[mcp_servers.dsh]
command = "node"
args = ["D:\\path\\to\\dsh-mcp\\dist\\index.js"]
env = { DEEPSEEK_API_KEY = "sk-..." }

Перезапустите codex и просто попросите — например: «Используй инструмент dsh_investigate, чтобы прочитать README и package.json и сообщи название проекта». Codex не видит внутренности DSH (это чёрный ящик для хоста), именно поэтому каждый делегированный вызов возвращает блок [mcp] changedFiles — родитель узнаёт, что затронула делегация, даже если хост — не Claude Code.

Любой другой MCP-клиент

Укажите вашему клиенту на dist\index.js с теми же переменными окружения. Большинство клиентов принимают JSON-блок mcpServers (конфиг уровня проекта Claude Code, Cursor mcp.json, VS Code, Claude Desktop, …):

{
  "mcpServers": {
    "dsh": {
      "command": "node",
      "args": ["D:\\path\\to\\dsh-mcp\\dist\\index.js"],
      "env": { "DEEPSEEK_API_KEY": "sk-..." }
    }
  }
}

Не коммитьте ключ. Скрипты автоматизации удаляют свой временный конфиг перед завершением работы.

Где можно установить DSH?

DSH находится ровно в четырёх местах, проверяемых по порядку — сервер никогда не смотрит на PATH:

1. Переменная окружения DSH_ROOT — явное переопределение, побеждает безусловно
2. Соседний checkout рядом с этим пакетом: ..\deepseek-harness
3. Вложенный checkout внутри этого пакета: .\deepseek-harness
4. Установленный CLI-пакет в домашнем катале DSH: %USERPROFILE%\.dsh\profiles\node_modules\@deepseek-ai\dsh (DSH_HOME переопределяет домашний каталог)

Таким образом, вы можете установить DSH где угодно — соседний checkout, отдельный каталог инструментов, другой диск — и указать DSH_ROOT на него. Подходит любой вариант: исходный checkout (сначала соберите его CLI: pnpm install && pnpm run build) или установленный CLI-пакет (<root>\lib\bin.js). Всё, что находится за пределами этих четырёх мест, просто не обнаруживается; сообщение об ошибке подскажет вам задать DSH_ROOT.

# register with a DSH that lives in your own directory
claude mcp add dsh `
  --transport stdio `
  --env DEEPSEEK_API_KEY=sk-... `
  --env DSH_ROOT=D:\tools\deepseek-harness `
  -- node D:\path\to\dsh-mcp\dist\index.js

Переменные окружения

Устшение неполадок

Как делегировать

Каждый инструмент делегирования принимает один аргумент task (см. Tools для полного семейства). Каждый вызов порождает нового DSH-агента, который работает в вашем рабочем пространстве проекта и возвращает свой конечный результат. У DSH нет памяти между вызовами — это задумка (нет сеанса, который можно повредить) — и он устанавливает одно главное правило:

Делайте каждую делегацию самодостаточной. Дайте DSH всё, что нужно подзадаче: пути к файлам, контекст, ожидаемый результат. Никогда не пишите «как выше», «как раньше» или «тот файл, о котором я упоминал ранее» — DSH не видит вашу переписку.

Хорошая и плохая делегация

Одна и та же задача, написанная двумя способами:

❌ "Fix the bug in the store module and verify."
   — Which module? What bug? Verify how? DSH has no memory of "the" bug.

✅ "In src/store.js, createOrder() (around line 42) computes the order total
    without the tax field. Fix it so the total includes tax. Then run
    node src/tests/order.test.js and report the output."
   — Self-contained: file, bug, expected behavior, verification command.

Три шаблона, покрывающие большинство делегаций

1. Исследование — DSH читает файлы, родитель читает отчёт

Read src/modules/a.js, b.js and c.js and report: (1) every exported
function signature, (2) all TODO/FIXME comments with line numbers,
(3) where each module is imported from. Don't modify anything.

2. Исправление + проверка — родитель решает, DSH выполняет и проверяет

In src/utils.js, slugify("  hello ") returns "hello " instead of "hello"
(leading whitespace leaks through). Fix it, then run
node src/test/utils.test.js and report which assertions pass.

3. Пакетное редактирование — одна делегация вместо N циклов чтение/правка

Across the project, replace every occurrence of config.port with
config.serverPort in all .js files (skip node_modules). List each file
you changed, one line per file.

Когда делегировать — а когда нет

You:   The login flow is broken. Have DSH trace login.js → session.js → db.js
       under src/auth/ and report where an error could be swallowed, with
       line numbers. Don't read the files yourself.

DSH:   Found it: src/auth/session.js:37 catches the error and returns null
       instead of rethrowing, so login.js treats the failure as "not logged
       in". Three files read, nothing modified.

Модель стоимости

Быстрота и дешевизна обеспечиваются моделью на стороне DSH: deepseek-v4-flash. Ранняя разработка полностью велась на flash (и родитель, и DSH); приведённый выше бенчмарк на 100 задач использует гетерогенную комбинацию родитель = deepseek-v4-pro[1m], DSH = deepseek-v4-flash (рука B использует того же родителя pro без плагина, поэтому разница обусловлена именно плагином). Ядро Claude Code в бенчмарке — это модель DeepSeek: ANTHROPIC_MODEL: deepseek-v4-pro[1m], а не модель Anthropic; приведённые ниже утверждения предполагают лишь наличие сильного родителя, независимо от вендора.

• Быстрее — подзадачи с большим количеством токенов (чтение файлов, циклы исследования) выполняются пакетно в DSH вместо последовательного выполнения в родительской сессии; замеренное снижение среднего времени выполнения: −36% (76,5 с против 120,2 с).
• Дешевле — основной расход токенов идёт по тарифам deepseek-v4-flash, а бюджет токенов родителя минимизируется за счёт делегирования (чистое рассуждение).
• Ноль миграции — delegate_to_dsh не зависит от модели на всём протяжении.

Проверено

Дизайн и ограничения (V0.x)

• Синхронное ожидание результата — нет потоковой передачи, нет фоновых задач, нет опроса (ENGINEERING §0/§23). Долгая задача — это один более длинный MCP-вызов; таймаут по умолчанию отсутствует.
• Worker'ы без состояния — каждое делегирование — это новый процесс DSH (накладные расходы на запуск; приемлемо для простых задач).
• Конкурентные делегирования редактируют одну и ту же рабочую область на свой страх и риск — предпочтительны read-only / независимые подзадачи.
• В первую очередь Windows, лицензия MIT. Документация и инженерное обоснование: DSH_MCP_ENGINEERING(1).md (§0–§40).

Отказ от ответственности

dsh-mcp — это независимый проект с открытым исходным кодом. Он не связан с OpenAI, Anthropic или DeepSeek, не одобрен ими и не спонсируется ими. DeepSeek Harness — это проект DeepSeek с открытым исходным кодом; данный адаптер лишь интегрируется с его CLI через протокол MCP. Все названия продуктов и товарные знаки принадлежат их соответствующим владельцам.

Лицензия

MIT