Три роли возможности DeepSeek Harness: определение / провайдер / потребитель

В официальной документации часто упоминаются Определение сервиса, Поставщик сервиса и Потребитель. Вместе они образуют шов возможности — то есть заменяемый интерфейс возможности.

Эта глава прояснит, что представляет собой каждый из трёх, и почему возможность разделена на три роли.

Целостная возможность образует её шов; ни одна отдельная роль не является швом.


Что представляет собой каждая из трёх ролей?

Когда возможность достаточно универсальна и должна поддерживать заменяемых поставщиков (например, выполнение Bash), каркас разделяет возможность на три роли.

РольЗа что она отвечает?На примере Bash
Определение сервиса Интерфейс + типыОпределяет сервис Cordis, а также типы Request и Resultdsh-shell (зарегистрирован как ctx.shell)
Поставщик сервиса РеализацияФактически реализует эту возможность, обычно ориентируясь на конкретную среду выполненияdsh-bash-local (локальное выполнение)
Потребитель Инструменты, ориентированные на модельПредоставить возможность как инструмент, который могут вызывать моделиdsh-tool-bash (инструмент bash)

Определение сервиса только объявляет, «какие возможности существуют и как они выглядят», не заботясь о том, как они реализованы.

Поставщик сервиса наследует абстрактный класс Определения и задаёт конкретное поведение.

Потребитель обращён к модели, оборачивая возможность в схемы инструментов, чтобы модель могла её вызвать.

Три роли можно разместить в одном пакете или разделить по разным пакетам.

Есть только один критерий: должны ли эти роли развиваться или заменяться независимо.


Разберитесь в трёх ролях шва с помощью одной диаграммы

Все три роли зависят от Определения, тогда как Поставщик и Потребитель не зависят друг от друга.

能力 Seam 三角色关系图

Пунктирный прямоугольник на диаграмме — это полная возможность, то есть шов.

Определение находится посередине; и Провайдер, и Потребитель зависят только от него.

Провайдер наследует реализацию Определения, а Потребитель через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.shellseamshellbash-local / bash-sandbox / pwsh-localtool-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.

Пример

# Путь к файлу: 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: почему говорят, что «любая отдельная роль — это не шов»?

Другие расширения