Конвейер выполнения инструментов 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, и для них не требуется внешний протокол.
Пример
// Плагин 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, а не записан в тело инструмента.
Пример
// Используйте 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 нет.
Пример
// Безвозвратный окончательный отказ: запрещает выполнение 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Он наблюдает за замороженным авторитетным результатом |