DeepSeek Harness: Três Papéis da Capacidade

// ❌ Implementação hardcoded
class FileAnalyzer {
  analyze(path: string) {
    const stat = fs.statSync(path)  // Só pode usar sistema de arquivos local
    return { size: stat.size, type: 'local' }
  }
}

// ✅ Separação de três papéis
// Definition: declarar interface
interface FileStats {
  getSize(path: string): Promise<number>
  getType(path: string): Promise<string>
}

// Provider: implementação (local)
class LocalFileStats implements FileStats { ... }

// Provider: implementação (sandbox remoto)
class SandboxFileStats implements FileStats { ... }

// Consumer: uso (não se importa com implementação específica)
class FileAnalyzer {
  constructor(private stats: FileStats) {}
  analyze(path: string) {
    const size = await this.stats.getSize(path)
    return { size }
  }
}

import { defineCapability } from '@deepseek-ai/cordis'

export const FileStats = defineCapability({
  name: 'file-stats',
  description: 'Estatísticas de arquivo e acesso a metadados',
  interface: {
    getSize(path: string): Promise<number>
    getType(path: string): Promise<string>
    exists(path: string): Promise<boolean>
    list(dir: string): Promise<string[]>
  }
})

capabilities/
├── file-stats/
│   ├── definition.ts    ← Definition
│   ├── local.ts         ← Provider (implementação local)
│   └── sandbox.ts       ← Provider (implementação sandbox)

import { FileStats } from './definition'

export default class LocalFileStatsProvider extends Service {
  static inject = ['fs']

  constructor(ctx: Context) {
    super(ctx, 'file-stats')
    ctx.implement(FileStats, {
      async getSize(path: string) {
        const stat = await ctx.fs.stat(path)
        return stat.size
      },
      async getType(path: string) {
        const stat = await ctx.fs.stat(path)
        return stat.isDirectory ? 'directory' : 'file'
      },
      async exists(path: string) {
        try {
          await ctx.fs.stat(path)
          return true
        } catch {
          return false
        }
      },
      async list(dir: string) {
        const entries = await ctx.fs.readdir(dir)
        return entries.map(e => e.name)
      }
    })
  }
}

ctx.implement(FileStats, {
  getSize: async (path) => { ... },
  getType: async (path) => { ... },
  // Deve implementar todos os métodos da interface
})

export default class LocalFileStatsProvider extends Service {
  constructor(ctx: Context) {
    super(ctx, 'file-stats')
    ctx.implement(FileStats, {
      async getSize(path) {
        const stat = await ctx.fs.stat(path)
        return stat.size
      },
      async getType(path) {
        return (await ctx.fs.stat(path)).isDirectory ? 'directory' : 'file'
      },
      async exists(path) {
        try { await ctx.fs.stat(path); return true } catch { return false }
      },
      async list(dir) {
        return (await ctx.fs.readdir(dir)).map(e => e.name)
      }
    })
  }
}

export default class SandboxFileStatsProvider extends Service {
  constructor(ctx: Context) {
    super(ctx, 'file-stats')
    ctx.implement(FileStats, {
      async getSize(path) {
        const resp = await fetch(`http://sandbox:8080/stat?path=${path}`)
        return (await resp.json()).size
      },
      async getType(path) {
        const resp = await fetch(`http://sandbox:8080/stat?path=${path}`)
        return (await resp.json()).type
      },
      async exists(path) {
        const resp = await fetch(`http://sandbox:8080/exists?path=${path}`)
        return (await resp.json()).exists
      },
      async list(dir) {
        const resp = await fetch(`http://sandbox:8080/ls?dir=${dir}`)
        return (await resp.json()).entries
      }
    })
  }
}

export const inject = ['file-stats']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'file_info',
    description: 'Get file information',
    parameters: {
      type: 'object',
      properties: {
        path: { type: 'string', description: 'File path' }
      },
      required: ['path']
    },
    async execute({ path }, ctx) {
      const size = await ctx['file-stats'].getSize(path)
      const type = await ctx['file-stats'].getType(path)
      return { path, size, type }
    }
  }))
}

// Código Consumer é idêntico independentemente de Local ou Sandbox abaixo
const size = await ctx['file-stats'].getSize(path)

// Via extensão de tipo
declare module '@deepseek-ai/cordis' {
  interface Context {
    'file-stats': {
      getSize(path: string): Promise<number>
      getType(path: string): Promise<string>
      exists(path: string): Promise<boolean>
      list(dir: string): Promise<string[]>
    }
  }
}

Sem seam:
  Consumer → Provider A (hardcoded, não pode substituir)

Com seam:
  Consumer → Definition (seam) → Provider A
                        (seam) → Provider B (substituído!)

seam grossa: FileSystem (sistema de arquivos inteiro substituível)
seam média: FileStats (estatísticas de arquivo substituíveis)
seam fina: FileSize (consulta de tamanho de arquivo substituível)

Cenário: Alternar de desenvolvimento local para execução em sandbox

1. Descarregar LocalFileStatsProvider
2. Carregar SandboxFileStatsProvider
3. Todos os Consumers automaticamente usam a implementação sandbox
4. Código Consumer: zero modificações

# Desenvolvimento local
plugins:
  file-stats:
    $insert: ./providers/local-file-stats

# Ambiente sandbox (apenas mudar esta linha)
plugins:
  file-stats:
    $replace: ./providers/sandbox-file-stats

// Alternar dinamicamente via $replace
ctx.on('config/updated', (config) => {
  if (config.environment === 'sandbox') {
    // Framework auto-recarrega, alterna para Sandbox Provider
  }
})

# Grupo A: implementação local
realms:
  group-a:
    plugins:
      file-stats:
        $insert: ./providers/local-file-stats
  
  group-b:
    plugins:
      file-stats:
        $insert: ./providers/sandbox-file-stats