Три роли возможности DeepSeek Harness: определение / провайдер / потребитель
В официальной документации часто упоминаются Определение сервиса, Поставщик сервиса и Потребитель. Вместе они образуют шов возможности — то есть заменяемый интерфейс возможности.
Эта глава прояснит, что представляет собой каждый из трёх, и почему возможность разделена на три роли.
Целостная возможность образует её шов; ни одна отдельная роль не является швом.
Что представляет собой каждая из трёх ролей?
Когда возможность достаточно универсальна и должна поддерживать заменяемых поставщиков (например, выполнение Bash), каркас разделяет возможность на три роли.
| Роль | За что она отвечает? | На примере Bash |
|---|---|---|
| Определение сервиса Интерфейс + типы | Определяет сервис Cordis, а также типы Request и Result | dsh-shell (зарегистрирован как ctx.shell) |
| Поставщик сервиса Реализация | Фактически реализует эту возможность, обычно ориентируясь на конкретную среду выполнения | dsh-bash-local (локальное выполнение) |
| Потребитель Инструменты, ориентированные на модель | Предоставить возможность как инструмент, который могут вызывать модели | dsh-tool-bash (инструмент bash) |
Определение сервиса только объявляет, «какие возможности существуют и как они выглядят», не заботясь о том, как они реализованы.
Поставщик сервиса наследует абстрактный класс Определения и задаёт конкретное поведение.
Потребитель обращён к модели, оборачивая возможность в схемы инструментов, чтобы модель могла её вызвать.
Три роли можно разместить в одном пакете или разделить по разным пакетам.
Есть только один критерий: должны ли эти роли развиваться или заменяться независимо.
Разберитесь в трёх ролях шва с помощью одной диаграммы
Все три роли зависят от Определения, тогда как Поставщик и Потребитель не зависят друг от друга.
Пунктирный прямоугольник на диаграмме — это полная возможность, то есть шов.
Определение находится посередине; и Провайдер, и Потребитель зависят только от него.
Провайдер наследует реализацию Определения, а Потребитель черезinject: ['shell']зависит от него.
Между Провайдером и Потребителем нет зависимости.
Поэтому при замене Провайдера ни Определению, ни Потребителю не требуется ни единой строки изменений.
На примере Bash: три роли ctx.shell
Выполнение Bash — самый типичный шов в dsh; каждая из трёх ролей имеет собственный пакет.
Определение сервиса — это пакет dsh-shell, зарегистрированный как сервис ctx.shell.
Оно определяет тип запроса для BashShellExecRequestи тип результатаShellRunResult。
Провайдер сервиса — dsh-bash-local, который выполняет команды на локальном компьютере.
У того же Определения есть другие Провайдеры, например dsh-bash-sandbox, выполняющий команды в песочнице, и dsh-pwsh-local, выполняющий PowerShell.
Потребитель — dsh-tool-bash, который оборачивает возможность в bash-инструмент, вызываемый моделью.
tool-bash через inject объявляет зависимость ctx.shell, а в execute вызывает ctx.shell.run(...).
Официальный справочный документ "Capability Seam and Core Services" использует таблицу для поддержания принадлежности ctx.shell трём ролям.
| ключ ctx | Роль | Связанный пакет (Определение) | Реализация (Провайдер) | Прямой потребитель (Потребитель) |
|---|---|---|---|---|
| ctx.shell | seam | shell | bash-local / bash-sandbox / pwsh-local | tool-bash / tool-pwsh / hooks-claude-code / hooks-codex |
Потребители также включают два плагина-моста для хуков: hooks-claude-code и hooks-codex.
Как и tool-bash, они распознают только интерфейс ctx.shell и не обращают внимания на то, какой исполнитель за ним стоит.
В Bash-шве запрос ShellExecRequest, видимый модели (workdir, timeoutMs — необязательный), отделён от полностью разрешённой спецификации ShellExecSpec (поля обязательны), фактически используемой исполнителем.
Слой инструментов вызывает ctx.shell.resolve(request) между ними — это «явное лучше неявного на границах пакетов».
Почему нужно разделить это на три роли?
Первое преимущество разделения — провайдеры можно заменять.
Одно и то же Service Definition может иметь несколько провайдеров, выбираемых через cordis.yml.
Пример
# Локальное выполнение
- name: '@deepseek-ai/dsh-bash-local'
# Чтобы переключить провайдера, просто замените строку выше.
# Замените на строку ниже, чтобы переключиться на исполнитель в песочнице:
# - name: '@deepseek-ai/dsh-bash-sandbox'
При переключении провайдеров как Service Definition, так и Consumer остаются неизменными.
Второе преимущество разделения — три роли могут развиваться независимо.
| Роль | Свобода развиваться независимо |
|---|---|
| Определение сервиса | Как только вызывающие начинают зависеть от его соглашений, он редко меняется. |
| Поставщик сервиса | Может независимо оптимизировать производительность и безопасность |
| Потребитель | Может настраивать, как возможность представлена модели |
Третье преимущество разделения — развязывание зависимостей.
Поставщик сервиса зависит от определения сервиса.
Потребитель зависит от определения сервиса.
Поставщик сервиса и потребительВзаимно независимы。
| Отношения зависимостей | Выполняется ли это |
|---|---|
| Поставщик → Определение | Да |
| Потребитель → Определение | Да |
| Поставщик → Потребитель | нет |
| Потребитель → Поставщик | нет |
Практический анализ: найдите три роли используемого вами шва.
Официальный справочный документ «Capability Seam and Core Services» содержит полный список сервисов.
Выберите знакомый вам шов, например ctx.fs или ctx.llm, и разберите его в три шага.
Шаг 1: найдите его пакет определения — то есть столбец «пакет принадлежности» в таблице.
Шаг 2: найдите его пакет поставщика — то есть столбец «реализация» в таблице.
Шаг 3: найдите его потребителя — то есть столбец «прямой потребитель» в таблице.
Например, у ctx.llm Определение — это пакет llm, Реализация — llm-deepseek и llm-pi-ai, прямые потребители — agent-loop и compaction-basic.
Другой пример — ctx.fs: Определение — это пакет fs, реализации — fs-local, fs-sandbox и fs-e2b, а прямой потребитель — tool-fs.
Как только вы привыкнете к такому образу мышления, вы сможете с первого взгляда определить, к какой роли относится любой встроенный сервис.
Итог и самопроверка
Резюме в одном предложении: возможность разделяется на три роли — Definition (интерфейс и типы), Provider (реализация) и Consumer (инструменты, обращённые к модели), — и вместе они образуют шов.
Вопрос для самопроверки 1: каким пакетам соответствуют Definition, Provider и Consumer возможности Bash?
Вопрос для самопроверки 2: при замене Provider для Bash какие пакеты могут остаться без изменений?
Вопрос для самопроверки 3: почему говорят, что «любая отдельная роль — это не шов»?
Другие расширения