DeepSeek Harness en la práctica: escribir una capacidad reemplazable

El capítulo anterior explicó el concepto de los tres roles; en este artículo lo convertiremos en código siguiendo el tutorial oficial.

Vamos a implementar una capacidad llamada myCap: recibe un texto y devuelve todo en mayúsculas. Es lo bastante pequeña para entenderla de un vistazo y cubre por completo los tres paquetes: Definition, Provider y Consumer.

Tres pasos: Service Definition (clase abstracta + tipos) → Service Provider (subclase de implementación) → Consumer (defineTool).

Finalmente, cargamos el Provider y el Consumer de forma combinada en cordis.yml.


Primer paso: escribir la Service Definition

La Service Definition declara la capacidad en sí: cómo se llama el servicio, cómo se invoca y cuáles son los tipos de la solicitud y el resultado.

No contiene ninguna lógica de implementación; solo tiene un método abstracto y dos interfaces.

La clase abstracta MyCapService hereda de Service y, mediantesuper(ctx, 'myCap')se registra como servicio con nombre.

La fusión de declaraciones con `declare module` le da un tipo a ctx.myCap; este truco se explicó en el artículo 14.

Ejemplo

// ruta del archivo: packages/my-cap/my-cap/src/index.ts
import { Service, type Context } from '@deepseek-ai/cordis'

// Fusión de declaraciones: hacer que ctx.myCap tenga sugerencias de tipo en TypeScript
declare module '@deepseek-ai/cordis' {
  interface Context {
    myCap: MyCapService
  }
}

// Clase abstracta: el paquete Definition solo declara el contrato, no escribe la implementación
export abstract class MyCapService extends Service {
  constructor(ctx: Context) {
    super(ctx, 'myCap') // Registrar como servicio nombrado ctx.myCap
  }

  /** Execute the capability. */
  abstract execute(request: MyCapRequest): Promise<MyCapResult>
}

// Tipo de solicitud: el llamador debe proporcionar input
export interface MyCapRequest {
  input: string
}

// Tipo de resultado: la capacidad retorna output
export interface MyCapResult {
  output: string
}

`abstract execute` es el único método abstracto; el Provider debe implementarlo.

MyCapRequest tiene el campo input, y MyCapResult tiene el campo output.

Los tipos de solicitud y resultado pertenecen al paquete Definition; tanto el Provider como el Consumer los importan desde allí.


Segundo paso: escribir el Service Provider

El Service Provider hereda de la clase abstracta y añade el comportamiento real.

MyCapLocal convierte input a mayúsculas y lo devuelve.

`export const name` declara el nombre del plugin; en `apply` se registra la implementación del servicio mediante `ctx.plugin(MyCapLocal)`.

Ejemplo

// Ruta del archivo: packages/my-cap/my-cap-local/src/index.ts
import type { Context } from '@deepseek-ai/cordis'
import { MyCapService, type MyCapRequest, type MyCapResult } from '@deepseek-ai/dsh-my-cap'

// Clase de implementación: solo depende del paquete Definition
class MyCapLocal extends MyCapService {
  async execute(request: MyCapRequest): Promise<MyCapResult> {
    // Local provider behavior.
    return { output: request.input.toUpperCase() }
  }
}

export const name = 'my-cap-local'

export function apply(ctx: Context) {
  // Cargar la clase de implementación como plugin y registrarla como el servicio real de ctx.myCap
  ctx.plugin(MyCapLocal)
}

El Provider depende solo de la clase abstracta y los tipos del paquete Definition.

No le importa cómo llama el modelo ni cómo es la herramienta.

Si en el futuro quieres cambiar a otra implementación, por ejemplo que se ejecute en un servidor remoto, solo necesitas escribir otra subclase de Provider.


Tercer paso: escribir el consumidor (Consumer)

El Consumer envuelve la capacidad como una herramienta que el modelo puede invocar.

`inject` declara las dependencias tools y myCap, y garantiza que `apply` se ejecute solo después de que ambos servicios estén listos.

`defineTool` declara el schema de la herramienta; cuando el modelo vea la herramienta my_cap, pasará los parámetros según `parameters`.

En `execute` se llama a `ctx.myCap.execute` y el resultado se devuelve como salida de la herramienta.

Ejemplo

// Ruta del archivo: packages/my-cap/tool-my-cap/src/index.ts
import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'tool-my-cap'
// Declaración de dependencias: tools proporciona el punto de entrada de registro, myCap proporciona la implementación del servicio
export const inject = ['tools', 'myCap']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'my_cap', // Nombre de la herramienta orientada al modelo
    description: 'Execute my capability.',
    // Schema de parámetros: el modelo genera los parámetros según el schema
    parameters: {
      input: { type: 'string', required: true },
    },
    // Schema de salida y método de renderizado
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    // Ejecución real: invocar el servicio de capacidad
    async execute(args) {
      const result = await ctx.myCap.execute({ input: args.input })
      return result.output
    },
  }))
}

El modelo no conoce directamente ctx.myCap; solo conoce la herramienta my_cap.

El Consumer es el puente entre ambos y también se encarga de renderizar el resultado como texto visible para el modelo.


Estructura de tres roles de myCap y flujo de datos

Al juntar los tres paquetes, los datos parten del modelo, pasan por Consumer y Definition, y llegan al Provider.

myCap 三角色结构与数据流图

El modelo primero llama a la herramienta my_cap; este paso ocurre solo en la capa del Consumer.

El Consumer envuelve los parámetros en un MyCapRequest y lo entrega a `ctx.myCap.execute(request)`.

La Definition delega la llamada a la implementación del Provider actualmente cargada.

Después de calcular el resultado, el Provider devuelve el MyCapResult al Consumer por el mismo camino.

El Consumer renderiza output como texto y se lo entrega al modelo como resultado de la herramienta.

En toda la cadena, cuando se reemplaza el Provider, ni el Consumer ni el modelo lo notan.


Composición en cordis.yml

Escribir los tres paquetes es solo tener las piezas; además hay que cargar el Provider y el Consumer juntos en cordis.yml.

Al cargar el Provider, ctx.myCap tiene implementación; al cargar el Consumer, el modelo tiene la herramienta my_cap.

Ejemplo

# Ruta del archivo: cordis.yml
# Cargar primero el Provider para que ctx.myCap tenga una implementación
- name
: '@deepseek-ai/dsh-my-cap-local'

# Luego cargar el Consumer para que el modelo pueda usar la herramienta my_cap
- name
: '@deepseek-ai/dsh-tool-my-cap'

En cuanto al orden de carga, Cordis ordena automáticamente según las dependencias, por lo que no importa si el Provider va antes o después que el Consumer.

Para cambiar a otro Provider, solo hay que modificar la primera línea; el Consumer se mantiene igual.


Puntos clave de diseño

La documentación oficial da tres puntos clave de diseño; conviene recordarlos antes de escribir una capacidad.

Primero: no hagas divisiones preventivas.

Solo separa los roles en paquetes distintos cuando necesiten evolucionar de forma independiente.

Un plugin de herramienta simple no necesita dividirse; es totalmente válido que un solo paquete asuma varios roles.

Segundo: la Service Definition posee los tipos Request/Result.

Como el Provider y el Consumer solo dependen del paquete Definition, los tipos de solicitud y resultado deben definirse en Definition.

Tercero: lo explícito es mejor que lo implícito.

La implementación debe manejar los valores por defecto mediante un paso explícito de `resolve(request)`, en lugar de ocultar `?? default` dentro de `run()`.

El Bash seam es un ejemplo: `workdir` y `timeoutMs` de ShellExecRequest son opcionales; la capa de herramienta primero llama a `ctx.shell.resolve(request)` para obtener un ShellExecSpec con todos los campos obligatorios, y luego se lo pasa a `run()`.

No agregues valores por defecto silenciosamente dentro de `run()`; primero haz `resolve` y luego ejecuta, así los límites quedan claros.


Resumen y autoevaluación

Resumen en una frase: escribir una capacidad reemplazable = clase abstracta Definition + subclase Provider + herramienta Consumer, más un cordis.yml.

Autoevaluación 1: ¿En qué paquete deberían definirse MyCapRequest y MyCapResult?

Autoevaluación 2: ¿Existe dependencia entre Provider y Consumer?

Autoevaluación 3: ¿Por qué no se recomienda la división preventiva en plugins de herramientas simples?

Otras extensiones