DeepSeek Harness: القدرات: الأدوار الثلاثة

// ❌ تنفيذ مُرمّز بثبات
class FileAnalyzer {
  analyze(path: string) {
    const stat = fs.statSync(path)  // يمكن استخدام نظام الملفات المحلي فقط
    return { size: stat.size, type: 'local' }
  }
}

// ✅ فصل الأدوار الثلاثة
// Definition: تصريح الواجهة
interface FileStats {
  getSize(path: string): Promise<number>
  getType(path: string): Promise<string>
}

// Provider: تنفيذ (محلي)
class LocalFileStats implements FileStats { ... }

// Provider: تنفيذ (sandbox بعيد)
class SandboxFileStats implements FileStats { ... }

// Consumer: استخدام (لا يهتم بالتنفيذ المُحدد)
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: 'File statistics and metadata access',
  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 (تنفيذ محلي)
│   └── sandbox.ts       ← Provider (تنفيذ 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) => { ... },
  // يجب تنفيذ جميع دوال الواجهة
})

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 }
    }
  }))
}

// كود Consumer متطابق بغض النظر عما إذا كان Local أو Sandbox تحته
const size = await ctx['file-stats'].getSize(path)

// عبر توسيع الأنواع
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[]>
    }
  }
}

بدون seam:
  Consumer → Provider A (مُرمّز بثبات، لا يمكن الاستبدال)

مع seam:
  Consumer → Definition (seam) → Provider A
                        (seam) → Provider B (استُبدل!)

seam خشن: FileSystem (نظام الملفات بالكامل قابل للاستبدال)
seam متوسط: FileStats (إحصائيات الملفات قابلة للاستبدال)
seam دقيق: FileSize (استعلام حجم الملف قابل للاستبدال)

سيناريو: التبديل من التطوير المحلي لتنفيذ sandbox

1. ألغِ تحميل LocalFileStatsProvider
2. حمّل SandboxFileStatsProvider
3. جميع Consumers يستخدمون تلقائياً تنفيذ sandbox
4. كود Consumer: صفر تعديلات

# تطوير محلي
plugins:
  file-stats:
    $insert: ./providers/local-file-stats

# بيئة sandbox (غيّر هذا السطر فقط)
plugins:
  file-stats:
    $replace: ./providers/sandbox-file-stats

// تبديل ديناميكي عبر $replace
ctx.on('config/updated', (config) => {
  if (config.environment === 'sandbox') {
    // الإطار يُعيد التحميل تلقائياً، يبدل لـ Sandbox Provider
  }
})

# المجموعة A: تنفيذ محلي
realms:
  group-a:
    plugins:
      file-stats:
        $insert: ./providers/local-file-stats
  
  group-b:
    plugins:
      file-stats:
        $insert: ./providers/sandbox-file-stats