DeepSeek Harness: ケイパビリティ3役

// ❌ ハードコードされた実装
class FileAnalyzer {
  analyze(path: string) {
    const stat = fs.statSync(path)  // ローカルファイルシステムしか使えない
    return { size: stat.size, type: 'local' }
  }
}

// ✅ 3役分離
// Definition：インターフェース宣言
interface FileStats {
  getSize(path: string): Promise<number>
  getType(path: string): Promise<string>
}

// Provider：実装（ローカル）
class LocalFileStats implements FileStats { ... }

// Provider：実装（リモートサンドボックス）
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（サンドボックス実装）

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

// 下層が Local でも Sandbox でも、Consumer コードは同一
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 （ファイルサイズ照会が置き換え可能）

シナリオ：ローカル開発からサンドボックス実行に切り替え

1. LocalFileStatsProvider をアンロード
2. SandboxFileStatsProvider をロード
3. すべての Consumer が自動的にサンドボックス実装を使用
4. Consumer コード：変更ゼロ

# ローカル開発
plugins：
  file-stats：
    $insert：./providers/local-file-stats

# サンドボックス環境（この1行だけ変更）
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