DeepSeek Harness: pipeline de ejecución de herramientas y control de permisos

En los capítulos anteriores aprendimos a registrar herramientas con defineTool y a escuchar varios puntos de extensión con el sistema de eventos.

Pero ahora surge una pregunta: después de que el modelo emite una llamada a herramienta, hasta que la herramienta realmente se ejecuta y el resultado regresa al modelo, ¿qué pasos intermedios ocurren?

En este capítulo explicaremos claramente el «pipeline de ejecución de herramientas» de dsh y cómo implementar un control de permisos con plugins de enganche (hook).

En una frase: una llamada a herramienta pasa por múltiples etapas en un orden fijo; cada etapa se encarga de un tipo de política, y los plugins de enganche pueden permitir, rechazar o preguntar.


Orden general del pipeline

La ejecución de herramientas no es tan simple como «llamar a una función»; es un pipeline con un orden fijo.

La documentación oficial resume el orden como:tools/pre-execute → guardia monótona → tools/execute → tools/post-execute → finalizeContent → tools/result。

De estos, los tres primeros son waterfall y pueden reescribir una llamada, mientras que finalizeContent y tools/result, controlados por la propia definición, se ejecutan después.

工具执行流水线流程图

Primero veamos dos conceptos que suelen confundirse:

waterfall(Evento waterfall) es un patrón de despacho de eventos; los listeners pueden llamarnext()delegar la decisión hacia abajo, o devolver directamente una decisión para cortocircuitar.

Guardia monótona(monotonic guard) es una línea de defensa final que solo permite reducir, no revocar.

A continuación explicamos cada etapa por separado.


tools/pre-execute: capa de políticas reordenables

tools/pre-executeEs el primer waterfall del pipeline, responsable de albergar políticas reordenables como «hooks, permisos, sandbox».

Se llama «reordenable» porque los listeners pueden, mediantenext()pasar la decisión al siguiente listener; el orden de varios plugins de políticas se puede ajustar en la configuración.

Este waterfall devuelve una decisión tipadaPreToolDecision, con tres valores posibles:

DecisiónSignificadoComportamiento posterior
{ kind: 'allow' }Permitir esta llamadaContinuar a la guardia monótona y las etapas siguientes.
{ kind: 'deny'; reason: string }Rechazar esta llamadaSe materializa como un resultado de error; el cuerpo de la herramienta se omite.
{ kind: 'ask'; reason?: string }Preguntar al usuarioSolo si el servicio de aprobación devuelveallowed-oncese continúa; de lo contrario, se rechaza.

NotaaskRama: disparactx.approvaluna consulta de una sola vez; este tema se desarrollará en el siguiente artículo.

Los argumentos no se pueden reescribir, porque el historial, la auditoría, la interfaz de usuario y la ejecución deben ser consistentes.

¿Cuándo usar pre-execute?

Úsalo cuando una política necesite una de las tres acciones «permitir, rechazar o preguntar» y se desee que las políticas puedan ordenarse libremente.

Los plugins como sandbox, permisos, plan-mode utilizan este punto de extensión.


Guardia monótona: rechazo final irrevocable

La desventaja del waterfall es que los listeners registrados posteriormente pueden anular la decisión de los anteriores.

Cuando un invariante necesita «rechazo final e irrevocable por cualquier persona», se debe usarctx.tools.guard()。

El tipo de la guardia esToolGuard, no tiene deliberadamente un resultado allow: devolver un string indica rechazo; devolverundefinedindica mantener el estado actual.

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

Debido a que la guardia no tiene resultado allow, el orden de los listeners jamás puede convertir un rechazo en una aprobación.

Este es el significado de «monótono»: solo disminuye, no aumenta; solo quita permisos, no otorga permisos.

Principio práctico: las políticas reordenables van entools/pre-execute; los invariantes que deben ser «de efecto final e irrevocables» van enctx.tools.guard()。


tools/execute y tools/post-execute

tools/executeSe encarga del «despacho envolvente», es decir, envolver la acción de llamar al cuerpo de la herramienta.

Los timeouts, reintentos y recopilación de métricas se hacen en esta capa; envuelve el ciclo de vida real del despacho.

La vista que recibe esToolDispatchExecution: solo esta vista puede reemplazar elexec.signal, usado para imponer un tiempo límite.

La regla de reemplazo es: se puede reemplazar, pero no eliminar; el registro vuelve a fusionar la signal de la persona que llama antes de invocar el cuerpo de la herramienta.

tools/post-executeSe encarga de verificar o reescribir después de que la herramienta se ejecuta y antes de normalizar el resultado; devuelvePostToolDecision:

DecisiónSignificado
{ kind: 'accept'; content? }Aceptar el resultado; puede reemplazar el contenido mostrado (conserva el valor canónico y los metadatos).
{ kind: 'accept'; value }Aceptar el resultado; puede reemplazar el valor canónico (se revalida y recalcula el contenido).
{ kind: 'block'; feedback }Bloquear el resultado; convertir la corrección en un resultado de error.

El reemplazo de contenido es una política de presentación, no de confidencialidad.

Para ocultar valores programáticos, se debe reemplazar ese valor o bloquear el resultado.


finalizeContent y tools/result

finalizeContentSon callbacks propiedad de la definición de herramienta (ToolDefinition); el registro los invoca exactamente una vez.

Es el «último invariante solo de contenido»: se ejecuta sincrónicamente y solo permite correcciones finales a nivel de contenido.

Después de esto, el registro materializa y congela el resultado aceptado, y luego disparatools/result。

tools/resultEs una notificación síncrona para observarel resultado autoritativo congelado e inmutable。

El observador no puede transformar el resultado; los fallos del observador también quedan aislados y no afectan el flujo principal.

Úsalo cuando se necesite «auditoría, métricas, capturar el resultado final»; solo se usa cuando se necesite «transformar el resultado o agregar contexto».tools/post-execute。

Truco de memoria para elegir: pre-execute decide «si se puede hacer», execute decide «cómo hacerlo», post-execute decide «cómo se presenta el resultado», y result solo se encarga de «echar un vistazo al resultado final».


Ejemplo práctico: escribir un plugin de control de permisos

La documentación oficial usa «control de permisos» como ejemplo para mostrar cómo los plugins de enganche usantools/pre-execute。

Los plugins de enganche son simplemente plugins de Cordis; no requieren un protocolo externo.

Ejemplo

// Ruta del archivo: my-plugins/permission-gate/src/index.ts
// Un plugin de control de permisos basado en tools/pre-execute.
// Devuelve una decisión tipada: si coincide con la lista negra, deniega; de lo contrario, llama a next() para delegar.
import type { Context } from '@deepseek-ai/cordis'
import type { PreToolDecision, ToolExecution } from '@deepseek-ai/dsh-tools'

// Lista negra: herramientas que tienen prohibido escribir directamente en el sistema de archivos en el proyecto ejemplo.
// Aquí se demuestra con el conjunto más simple; en un proyecto real se puede consultar una base de datos o al servicio de aprobación.
const DENY_TOOLS = new Set(['fs_write', 'fs_edit'])

// Función de decisión de política: devuelve si esta llamada está permitida.
// exec lleva una identidad de llamada inmutable (callId, name, arguments, agent, token, signal).
async function isAllowed(exec: ToolExecution): Promise<boolean> {
  if (DENY_TOOLS.has(exec.name)) return false
  // Ejemplo adicional: en la demostración de ejemplo se prohíbe modificar el archivo .env (los argumentos se congelan antes de entrar a la política).
  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 es un waterfall: los listeners pueden devolver una decisión o llamar a next() para delegar.
  ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => {
    if (!(await isAllowed(exec))) {
      // Devolver deny termina inmediatamente la llamada; los listeners posteriores no se ejecutan.
      return { kind: 'deny', reason: 'Denied by policy: this tool is not allowed in the ejemplo workspace.' }
    }
    // Permitir: pasar la decisión a los listeners posteriores en el pipeline.
    return next()
  })
}

Una vez cargado este plugin, cada llamada a herramienta del modelo pasará primero por él.

Las herramientas que coinciden con la lista negra reciben un resultado de error con reason, y el cuerpo de la herramienta se omite.

Debido a que devuelve una decisión tipada, otros plugins de políticas aún pueden participar en la decisión después de él.


Ejemplo práctico: añadir tiempo de espera con tools/execute

El timeout pertenece al ámbito de «despacho envolvente», por lo que debe usarsetools/executepara envolverlo, en lugar de escribirlo en el cuerpo de la herramienta.

Ejemplo

// Ruta del archivo: my-plugins/tool-guard/src/index.ts
// Envuelve el ciclo de vida de despacho real con tools/execute: agrega un tiempo de espera de 30 segundos a cada llamada de herramienta.
import type { Context } from '@deepseek-ai/cordis'

export const name = 'tool-guard'

export function apply(ctx: Context) {
  // tools/execute es una cascada: debes llamar a next() para ejecutar el cuerpo real de la herramienta.
  ctx.on('tools/execute', async (exec, next) => {
    // Nota: solo la vista tools/execute puede reemplazar exec.signal.
    // Aquí se fusiona la señal del llamador con un plazo de 30 segundos, sobrescribiendo la señal original.
    const originalSignal = exec.signal
    const deadline = AbortSignal.timeout(30_000)
    exec.signal = AbortSignal.any([originalSignal, deadline])
    try {
      // Delega al execute() real de la herramienta; tanto el tiempo de espera como la cancelación del llamador activan abort.
      return await next()
    } finally {
      // Restaura la señal original después de su uso para evitar contaminar llamadas posteriores.
      exec.signal = originalSignal
    }
  })
}

Regla: puedes reemplazar exec.signal, pero no eliminarlo.

El registro vuelve a fusionar la signal del llamador antes de invocar el cuerpo de la función de la herramienta, por lo que es seguro que la capa de envoltura reemplace la signal.


Ejemplo práctico: usar ctx.tools.guard() para rechazo monótono

Cuando el invariante requiere un "rechazo final e irrevocable", usactx.tools.guard()。

Nota: el tipo de retorno del guard esstring | undefined, no tiene rama allow.

Ejemplo

// Ruta del archivo: my-plugins/invariant-guard/src/index.ts
// Un rechazo final irrevocable: prohíbe ejecutar run_code en el entorno de demostración de ejemplo.
import type { Context } from '@deepseek-ai/cordis'

export const name = 'invariant-guard'

export function apply(ctx: Context) {
  // Registra un guard monótono. Devolver un string significa rechazo; devolver undefined significa mantener el estado actual.
  const disposer = ctx.tools.guard((execution) => {
    if (execution.name === 'run_code') {
      return 'run_code is disabled in the ejemplo demo profile.'
    }
    return undefined // Permitir: dejar sin cambios la decisión de pre-execute
  })

  // guard() devuelve una función de desmontaje precisa; el framework la invoca automáticamente cuando el plugin se desmonta.
  ctx.effect(() => disposer)
}

Como el guard no tiene un resultado allow, incluso si hay un listener posterior que quiera permitirrun_code, no puede convertir este rechazo en una autorización.


Resumen y autoevaluación

La canalización de ejecución de herramientas desacopla la "política" del "cuerpo de la herramienta", permitiendo que los hooks abarquen diferentes familias de herramientas sin que las herramientas se acoplen a un servicio de políticas específico.

Preguntas de autoevaluación:

PreguntaReferencia
Si quieres que una herramienta "nunca pueda ser autorizada por nadie", ¿debes usar pre-execute o guard?guard, porque el guard no tiene resultado allow y es irrevocable
Para agregar un tiempo de espera uniforme a todas las herramientas, ¿qué evento debes escuchar?tools/execute, envuelve el despacho y puede reemplazar la signal
Si solo quieres registrar el resultado final para auditoría sin modificar nada, ¿qué etapa debes usar?tools/result, observa el resultado autoritativo congelado
Otras extensiones