Конвейер выполнения инструментов DeepSeek Harness и шлюз разрешений

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

Но теперь возникает вопрос: после того как модель отправляет вызов инструмента, до момента фактического выполнения инструмента и возврата результата модели, какие шаги на самом деле происходят в промежутке?

В этой главе мы подробно объясним «конвейер выполнения инструментов» dsh и то, как реализовать шлюзы разрешений с помощью hook-плагинов.

В одном предложении: вызов инструмента проходит через несколько этапов в фиксированном порядке, каждый этап отвечает за одну категорию политики, а hook-плагины могут разрешать, запрещать или запрашивать в рамках этих этапов.


Общий порядок конвейера

Выполнение инструмента не так просто, как «вызов функции»; это конвейер с фиксированным порядком.

Официальная документация резюмирует порядок так:tools/pre-execute → Monotonic guard → tools/execute → tools/post-execute → finalizeContent → tools/result。

Среди них первые три waterfall-этапа могут один раз переписать вызов, а finalizeContent и tools/result, управляемые самим определением, выполняются после них.

工具执行流水线流程图

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

waterfall(событие Waterfall) — это паттерн диспетчеризации событий; слушатели могутnext()делегировать право принятия решения дальше или напрямую вернуть решение, чтобы досрочно завершить обработку.

Монотонный предохранитель(Monotonic guard) — это последняя линия защиты, которая позволяет только ужесточать, но никогда не отменять.

Ниже мы объясним каждый шаг по очереди.


tools/pre-execute: слой политики с возможностью переупорядочивания

tools/pre-executeЭто первый водопад в конвейере, отвечающий за проведение переупорядочиваемых политик, таких как "хуки, разрешения, песочница."

Причина, по которой он называется "переупорядочиваемым", заключается в том, что слушатели могутnext()передавать право принятия решения следующему слушателю, а порядок нескольких плагинов политик можно настроить в конфигурации.

Этот водопад возвращает типизированное решениеPreToolDecisionВозможны три значения:

Принятие решенийЗначениеПоследующее поведение
{ kind: 'allow' }Разрешить этот вызовПродолжить с монотонной защитой и последующими шагами.
{ kind: 'deny'; reason: string }Отклонить этот вызовЭто материализуется в результат ошибки, и тело инструмента пропускается.
{ kind: 'ask'; reason?: string }Спросить пользователяТолько когда служба одобрения возвращаетallowed-onceТогда продолжить, иначе отклонить.

ПримечаниеaskВетка: она сработаетctx.approvalкак разовый запрос; эта часть будет оставлена для следующей статьи.

Параметры нельзя изменять, потому что записи истории, аудит, UI и выполнение должны оставаться согласованными.

Когда использовать pre-execute?

Когда политике требуется одно из трёх действий — "allow, deny или ask" — и политики должны свободно упорядочиваться, используйте это.

Плагины, такие как sandbox, permission и plan-mode, все используют эту точку расширения.


Монотонный защитный механизм: безотзывный окончательный отказ.

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

Когда инвариант требует "окончательного отказа, и никто не может его отозвать," используйтеctx.tools.guard()。

Тип защитного механизма —ToolGuardОн намеренно не имеет результата allow: возврат строки означает отклонение, возвратundefinedОзначает сохранение статус-кво.

// ToolGuard:感知作用域的最终预分派策略
type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined

Поскольку у защитного механизма нет результата allow, порядок слушателей никогда не сможет превратить отклонение обратно в одобрение.

Вот что означает "монотонный": только уменьшать, никогда не увеличивать; только отзывать разрешения, никогда не предоставлять их.

Практические принципы: Размещайте здесь переупорядочиваемые политики.tools/pre-execute; инварианты, которые должны быть "окончательными и необратимыми", помещаются вctx.tools.guard()。


tools/execute и tools/post-execute

tools/executeОн отвечает за "обёртку вокруг диспетчеризации", то есть за обёртывание фактического вызова тела инструмента.

Тайм-аут, повторные попытки и сбор метрик обрабатываются на этом уровне; то, что он обёртывает, — это фактический жизненный цикл диспетчеризации.

Получаемое им представление — этоToolDispatchExecution: только это представление может заменить требуемыйexec.signal, используется для установления крайнего срока.

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

tools/post-executeОн отвечает за проверку или перезапись после выполнения инструмента и до нормализации результата; он возвращаетPostToolDecision:

Принятие решенийЗначение
{ kind: 'accept'; content? }Принять результат, может заменить отображаемое содержимое (сохраняя каноническое значение и метаданные).
{ kind: 'accept'; value }Принять результат, может заменить каноническое значение (будет повторно проверено и пересчитано содержимое).
{ kind: 'block'; feedback }Блокировать результат, превращая корректирующую обратную связь в результат с ошибкой.

Замена содержимого — это политика отображения, а не политика конфиденциальности.

Чтобы скрыть значение, заданное программно, нужно заменить это значение или заблокировать результат.


finalizeContent и tools/result

finalizeContentЭто колбэк, принадлежащий самому ToolDefinition, и реестр вызывает его ровно один раз.

Это "последний инвариант, касающийся только содержимого": выполняется синхронно, допуская лишь финальные исправления на уровне содержимого.

После этого реестр материализует и замораживает принятый результат, затем инициируетtools/result。

tools/resultЭто синхронное уведомление, используемое для наблюдения.Замороженный, неизменяемый авторитетный результат。

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

Используйте его, когда нужны "аудит, метрики, захват финального результата"; используйте его только тогда, когда нужно "преобразовать результат или присоединить контекст".tools/post-execute。

Мнемоника для выбора: pre-execute решает "можно ли это сделать", execute решает "как это сделать", post-execute решает "как представлен результат", result отвечает только за "взгляд на финальный результат".


Практический пример: напишите плагин-шлюз разрешений.

Официальная документация использует "permission gate" как пример, чтобы показать, как hook-плагины используютtools/pre-execute。

Хук-плагины — это обычные плагины Cordis, и для них не требуется внешний протокол.

Пример

// Путь к файлу: my-plugins/permission-gate/src/index.ts
// Плагин permission gate, основанный на tools/pre-execute.
// Он возвращает типизированное решение: отклонить, если в чёрном списке, иначе вызвать next() для делегирования.
import type { Context } from '@deepseek-ai/cordis'
import type { PreToolDecision, ToolExecution } from '@deepseek-ai/dsh-tools'

// Чёрный список: инструменты, которым запрещено напрямую записывать в файловую систему в примере проекта.
// Здесь мы используем простой набор для демонстрации; в реальных проектах можно обратиться к базе данных или к сервису согласования.
const DENY_TOOLS = new Set(['fs_write', 'fs_edit'])

// Функция принятия решения по политике: возвращает, разрешён ли этот вызов.
// exec несёт неизменяемую идентичность вызова (callId, name, arguments, agent, token, signal).
async function isAllowed(exec: ToolExecution): Promise<логическое значение> {
  if (DENY_TOOLS.has(exec.name)) return false
  // Дополнительный пример: в демонстрационном примере изменение файлов .env запрещено (аргументы замораживаются до входа в политику).
  const raw = exec.arguments as { path?: string }
  if (typeof raw.path === 'string' && raw.path.includes('.env')) return false
  return true
}

export const name = 'permission-gate'

export function apply(ctx: Context) {
  // tools/pre-execute — это waterfall: слушатели могут вернуть решение или вызвать next(), чтобы делегировать.
  ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => {
    if (!(await isAllowed(exec))) {
      // Возврат deny немедленно завершит этот вызов; последующие слушатели не будут выполнены.
      return { kind: 'deny', reason: 'Запрещено политикой: этот инструмент не разрешён в примере рабочего пространства.' }
    }
    // pass through: передать решение последующим слушателям в конвейере.
    return next()
  })
}

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

Инструмент, попавший в чёрный список, получит результат с ошибкой и указанием причины, а тело инструмента пропускается.

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


Практический пример: добавление тайм-аута с помощью tools/execute

Тайм-аут относится к аспекту "around dispatch" и должен быть обёрнут с помощьюtools/execute, а не записан в тело инструмента.

Пример

// Путь к файлу: my-plugins/tool-guard/src/index.ts
// Используйте tools/execute, чтобы обернуть фактический жизненный цикл диспетчеризации: добавьте 30-секундный тайм-аут к каждому вызову инструмента.
import type { Context } from '@deepseek-ai/cordis'

export const name = 'tool-guard'

export function apply(ctx: Context) {
  // tools/execute — это каскад: нужно вызвать next(), чтобы выполнить фактическое тело инструмента.
  ctx.on('tools/execute', async (exec, next) => {
    // Примечание: только представление tools/execute может заменить exec.signal.
    // Здесь сигнал вызывающего объединяется с 30-секундным дедлайном, переопределяя исходный сигнал.
    const originalSignal = exec.signal
    const deadline = AbortSignal.timeout(30_000)
    exec.signal = AbortSignal.any([originalSignal, deadline])
    try {
      // Делегировать фактическому execute() инструмента; тайм-аут или отмена вызывающей стороны вызовут abort.
      return await next()
    } finally {
      // Восстановите исходный сигнал после использования, чтобы не загрязнять последующие вызовы.
      exec.signal = originalSignal
    }
  })
}

Правило: exec.signal можно заменить, но нельзя удалить.

Реестр повторно объединит сигнал вызывающей стороны перед вызовом тела функции инструмента, поэтому слою-обёртке безопасно заменять сигнал.


Практический пример: монотонное отклонение с ctx.tools.guard()

Когда инвариант требует "окончательного отказа, безвозвратного", используйтеctx.tools.guard()。

Обратите внимание, что тип возвращаемого значения guard —string | undefined, ветви allow нет.

Пример

// Путь к файлу: my-plugins/invariant-guard/src/index.ts
// Безвозвратный окончательный отказ: запрещает выполнение run_code в среде демонстрационного примера.
import type { Context } from '@deepseek-ai/cordis'

export const name = 'invariant-guard'

export function apply(ctx: Context) {
  // Регистрирует монотонный guard. Возврат строки означает отклонение; возврат undefined означает отсутствие изменений.
  const disposer = ctx.tools.guard((execution) => {
    if (execution.name === 'run_code') {
      return 'run_code отключён в профиле демонстрационного примера.'
    }
    return undefined // Пропустить: оставить решение pre-execute без изменений
  })

  // guard() возвращает точную функцию очистки; фреймворк автоматически вызывает её при выгрузке плагина.
  ctx.effect(() => disposer)
}

Поскольку guard не имеет результата allow, даже если более поздний слушатель хочет разрешитьrun_code, он не может превратить этот отказ обратно в одобрение.


Итоговая самопроверка

Конвейер выполнения инструментов отделяет «политики» от «тела инструмента», позволяя хукам охватывать разные семейства инструментов, не связывая инструменты с конкретным сервисом политик.

Вопросы для самопроверки:

ПроблемаСсылка
Если вы хотите, чтобы инструмент был «никогда не одобряемым никем», следует использовать pre-execute или guard?guard, потому что у guard нет результата allow, он необратим.
Чтобы добавить единый таймаут для всех инструментов, какое событие следует слушать?tools/execute, он оборачивает dispatch и может заменить signal
Если вы хотите только записать окончательный результат для аудита, ничего не меняя, какой шаг следует использовать?tools/resultОн наблюдает за замороженным авторитетным результатом
Другие расширения