deepseek-subagent-mcp

Даёт Claude Code, Codex или любому другому MCP-клиенту агента DeepSeek Harness, которому можно поручать работу, так же, как он поручал бы её одному из своих субагентов.

MCP (Model Context Protocol) — это стандарт, с помощью которого кодирующий агент загружает внешние инструменты. DeepSeek Harness — это открытый агентский рантайм DeepSeek: модель в цикле с файловыми и shell-инструментами, выпущенный в августе 2026 года под лицензией MIT. Этот сервер находится между ними: он запускает агента Harness в отдельном процессе и предоставляет шесть инструментов для его запуска, наблюдения, продолжения и остановки.

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

Требования

• Python 3.11 или новее

• Ключ API DeepSeek с platform.deepseek.com

• macOS 14+ на Apple Silicon, или Linux на x86-64 или arm64

Установка Node.js не требуется: рантайм Harness поставляется как самодостаточный исполняемый файл внутри wheel-пакета deepseek-harness-sdk. Этот wheel-пакет также является ограничением платформы — он публикует macosx_14_0_arm64, manylinux_2_28_x86_64 и manylinux_2_28_aarch64 и ничего больше, так что Windows, Intel Mac и macOS 13 вообще не могут установить это.

Установка

uvx --from git+https://github.com/gaztrabisme/deepseek-subagent-mcp deepseek-subagent-mcp

Claude Code

Добавьте в .mcp.json в вашем проекте или в ~/.claude.json для всех проектов:

{
  "mcpServers": {
    "deepseek-subagent": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/gaztrabisme/deepseek-subagent-mcp",
        "deepseek-subagent-mcp"
      ],
      "env": {
        "DEEPSEEK_API_KEY": "sk-...",
        "DSA_WORKSPACE": "/path/to/your/project"
      }
    }
  }
}

Codex

Добавьте в ~/.codex/config.toml:

[mcp_servers.deepseek-subagent]
command = "uvx"
args = ["--from", "git+https://github.com/gaztrabisme/deepseek-subagent-mcp", "deepseek-subagent-mcp"]
env = { DEEPSEEK_API_KEY = "sk-...", DSA_WORKSPACE = "/path/to/your/project" }

Инструменты

Запуски асинхронны по умолчанию, потому что задача кодирования может занять много минут, а MCP-клиенты прерывают отдельные вызовы инструментов по таймауту. dsh_delegate возвращается сразу после постановки работы в очередь; dsh_await занимается ожиданием и сообщает о прогрессе, пока ждёт. Для коротких задач передайте wait_seconds в dsh_delegate и пропустите второй вызов.

Каждый dsh_delegate создаёт одного агента, удерживая один процесс рантайма и одну сохранённую сессию. dsh_continue повторно входит в эту сессию, так что у дочернего агента сохраняются его более ранние ходы в контексте.

Каждая делегация указывает, как она будет проверена

dsh_delegate требует аргумент verification: команду, которая доказывает, что задача выполнена.

dsh_delegate(task="Fix the failing date parser", verification="pytest -q tests/test_dates.py")

Сервер сам запускает эту команду в рабочем пространстве агента после того, как дочерний агент завершил работу. Дочерний агент, сообщающий о своих собственных результатах тестов, — это утверждение; код выхода — это факт, а агенты, преждевременно объявляющие победу, — это хорошо задокументированный сбой.

Команда классифицируется той же политикой, которая ограничивает собственные вызовы дочернего агента перед их выполнением, — вызывающая сторона является другим агентом и может быть подвергнута промпт-инъекции, поэтому «вызывающая сторона попросила об этом» не является авторизацией. Передайте verification="true", когда проверять действительно нечего; явная ложь лучше молчаливого значения по умолчанию.

Что возвращается

Субагент, возвращающий полный транскрипт, сводит на нет собственную цель. Когда ответ дочернего агента больше, чем DSA_SUMMARY_TOKENS, ему предлагается — в той же сессии, ещё одним ходом — заменить его кратким резюме для передачи из семи разделов: Цель, Ограничения и предпочтения, Прогресс, Ключевые решения, Следующие шаги, Соответствующие файлы, Критический контекст. Именно это пересекает границу MCP.

Ответ, уже не превышающий лимит, возвращается дословно и не требует дополнительного хода. Сырой ответ всегда сохраняется: dsh_transcript(run_id, raw=True).

Контролируемое выполнение

Вызовы инструментов дочернего агента блокируются до их выполнения. Хук PreToolUse внутри рантайма передаёт каждый предлагаемый вызов этому серверу, который отвечает разрешить или запретить; запрещённый вызов возвращается модели как заблокированный результат инструмента с указанием причины, и модель адаптируется.

Детерминированный классификатор решает первым, и он решает большинство вызовов. Чтение файлов, ls, grep, операции чтения систем контроля версий, запуск собственного кода и тестов рабочего пространства разрешены без участия модели. Привилегированные команды, удаления за пределами рабочего пространства, fetch, переданный по конвейеру в shell, и всё, что касается SSH-ключей или .env, категорически запрещены — в том числе через безобидно выглядящий глагол, потому что cat ~/.ssh/id_rsa — это инструмент только для чтения, применённый к секрету. Эскалируется только то, что классификатор не может классифицировать.

Эскалация выполняется на лучшем уровне, который поддерживает клиент, определяется при запуске и сообщается через dsh_list:

Каждый уровень при сбое закрывается. Недостижимый супервизор, таймаут, некорректный запрос или клиент, не поддерживающий ни одну из возможностей, — всё приводит к запрету, но никогда к одобрению.

Лестница проходится, а не выбирается один раз: уровень, который ошибается, переходит к следующему, поэтому клиент, отбрасывающий sampling — объявленный устаревшим в редакции спецификации от 2026-07-28, но всё ещё работающий сегодня, — деградирует до вопроса к вам, а не до запрета всего. Уровень, у которого истекает таймаут, не переходит дальше; не получивший ответа вопрос означает «нет», и повторный вопрос по другому каналу лишь удвоит ожидание.

Установите DSA_SUPERVISOR=off, чтобы полностью отключить шлюз.

Супервизору показываются структурированные факты, а не текст дочернего агента: инструмент, программы в каждом сегменте конвейера и каждый путь, который называет команда, с флагом внутри-или-снаружи-рабочего-пространства. Дочерний агент пишет и команду, и любое обоснование для неё; агент, способный аргументировать свою позицию, будет это делать. Путь, который нельзя разрешить статически, — $TMPDIR/out.txt, — сообщается как неразрешённый, а не угадывается, и считается находящимся снаружи.

examples/claude_supervisor.py запускает весь шаблон на реальном Claude для клиентов, которые сами не объявляют sampling:

DEEPSEEK_API_KEY=sk-... uv run python examples/claude_supervisor.py

Потолки и стоимость

Делегированный агент тратит ваши деньги в цикле, поэтому его ограничивают четыре независимых потолка, и каждый запуск сообщает, что было использовано.

В проводном протоколе нет отмены посреди хода, поэтому каждая остановка — это убийство процесса. Убийство из-за потолка всегда имеет приоритет над тем, что сообщил сам запуск: вывод убитого процесса никогда не читается как успех.

dsh_delegate, dsh_await и dsh_list сообщают об использовании токенов — ввод, вывод, чтение и запись кэша, а также количество шагов, — суммируя данные, сообщённые провайдером. Ввод на каждом шаге суммируется намеренно: каждый запрос оплачивает весь повторно отправляемый префикс, так что итог — это фактическая стоимость делегации.

Конфигурация

Каждый параметр — это переменная окружения на процессе сервера.

Ограничения, которые следует знать перед использованием

Они исходят из протокола проводки Harness SDK, а не из решений, принятых здесь.

• Песочница файловой системы не охватывает bash. dsh-fs-sandbox ограничивает инструменты write/edit модели рабочим пространством, но dsh-bash-sandbox не входит в состав исполняемого файла среды выполнения, поэтому сам bash не ограничен. Супервизор покрывает это — он блокирует каждый инструмент, включая bash, до выполнения. При DSA_SUPERVISOR=off границ для bash вообще нет; направьте его на ветку или временный каталог.

• Песочница ограничивает только воздействие на файлы — не на сеть, процессы или системные вызовы. И workspace-write разрешает /tmp, а также корень рабочего пространства.

• Отмена убивает процесс. В протоколе нет отмены в середине хода, поэтому dsh_cancel завершает среду выполнения. Уже записанные правки остаются на диске, и сессию нельзя возобновить после этого.

• Сессия удаленного агента исчезает, но его результаты — нет. После DSA_IDLE_TIMEOUT процесс освобождается; dsh_await и dsh_transcript по-прежнему работают с его завершенными запусками, dsh_continue — нет.

• Сессии живут столько же, сколько процесс. Нет закрытия по сессиям, поэтому память растет с историей агента. Отменяйте агентов, с которыми закончили.

• Вышестоящий проект находится в стадии предварительной разработки. deepseek-harness-sdk зафиксирован на ==0.1.0rc7; за неделю вышли два кандидата в релиз. Ожидайте изменений протокола.

Разработка

uv sync
uv run pytest                  # 127 tests, no API key, no network
uv run ruff check .
uv run deepseek-subagent-mcp   # starts on stdio; a client drives it

Живые тесты требуют реального ключа и расходуют токены; они не собираются pytest:

DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_task.py        # the product works
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_result.py      # distillation and the archive
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_supervisor.py  # the gate works
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_escalation.py  # both escalation tiers
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_limits.py      # reaper and deadline
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_mcp.py         # all six tools

CLAUDE.md содержит архитектуру и ограничения вышестоящего проекта; wiki/ содержит записи решений и результаты измерений.

Лицензия

MIT.