第六章：工具与数据类能力

// 来自 packages/core/tools/src/index.ts
declare module '@deepseek-ai/cordis' {
  interface Context {
    tools: ToolRuntime
  }
}

interface ToolRuntime {
  /** 注册工具 */
  register(tool: ToolRegistration): Disposable
  
  /** 获取所有工具 schema */
  schemas(): ToolSchema[]
  
  /** 获取 SDK 工具 schema */
  sdkSchemas(): ToolSchema[]
}

// 注册一个工具
const disposable = ctx.tools.register({
  name: 'my_tool',
  description: '我的自定义工具',
  parameters: {
    type: 'object',
    properties: {
      input: { type: 'string', description: '输入参数' }
    },
    required: ['input']
  },
  async execute(input, context) {
    // 执行工具逻辑
    return { result: `处理了: ${input.input}` }
  }
})

// 之后可以注销
disposable.dispose()

// 三个 waterfall 事件
'tools/pre-execute'   // 工具执行前
'tools/execute'       // 工具执行
'tools/post-execute'  // 工具执行后

interface ToolExecutionInput {
  /** 工具名称 */
  name: string
  /** 工具参数 */
  parameters: Record<string, unknown>
  /** 关联的 Agent */
  agent: Agent
  /** 关联的会话 */
  session: Session
}

interface ToolRunContext {
  /** 取消信号 */
  signal: AbortSignal
  /** 超时设置 */
  timeout?: number
  /** 日志记录器 */
  logger: Logger
}

// 来自 packages/shell/shell-local/src/index.ts（概念性）
class LocalShellProvider implements ShellProvider {
  /** 执行命令 */
  async execute(command: string, options: ShellOptions): Promise<ShellResult> {
    // 1. 解析命令
    const [cmd, ...args] = this.parseCommand(command)
    
    // 2. 通过 subprocess 执行
    const process = await this.subprocess.spawn(cmd, args, {
      cwd: options.cwd,
      env: options.env,
      timeout: options.timeout
    })
    
    // 3. 收集输出
    const stdout = await process.stdout.read()
    const stderr = await process.stderr.read()
    const exitCode = await process.wait()
    
    return { stdout, stderr, exitCode }
  }
}

// tool-shell 将 Shell 能力暴露为模型工具
ctx.tools.register({
  name: 'bash',
  description: 'Execute a bash command',
  parameters: {
    type: 'object',
    properties: {
      command: { type: 'string', description: 'The command to execute' }
    },
    required: ['command']
  },
  async execute(input) {
    const result = await ctx.shell.execute(input.command)
    return result
  }
})

// 来自 packages/subprocess/subprocess-local/src/index.ts（概念性）
class LocalSubprocessProvider implements SubprocessProvider {
  /** 启动进程 */
  async spawn(command: string, args: string[], options: SpawnOptions): Promise<RunningProcess> {
    const child = spawn(command, args, {
      cwd: options.cwd,
      env: options.env,
      stdio: ['pipe', 'pipe', 'pipe']
    })
    
    return {
      pid: child.pid,
      stdout: child.stdout,
      stderr: child.stderr,
      async wait() {
        return new Promise(resolve => {
          child.on('close', code => resolve(code))
        })
      },
      kill() {
        child.kill()
      }
    }
  }
}

// 来自 packages/fs/fs-local/src/index.ts（概念性）
class LocalFileSystemProvider implements FileSystemProvider {
  /** 读取文件 */
  async readBytes(path: string): Promise<Buffer> {
    return readFile(path)
  }
  
  /** 写入文件 */
  async writeBytes(path: string, data: Buffer): Promise<void> {
    await writeFile(path, data)
  }
  
  /** 列出目录 */
  async listDir(path: string): Promise<DirEntry[]> {
    return readdir(path, { withFileTypes: true })
  }
  
  /** 搜索文件 */
  async search(pattern: string, root: string): Promise<SearchResult[]> {
    // 使用 glob 模式匹配
  }
}

// 来自 packages/fs/fs-policy（概念性）
interface FileSystemPolicy {
  /** 检查路径是否可访问 */
  canAccess(path: string, mode: 'read' | 'write'): boolean
  
  /** 检查路径是否在允许的范围内 */
  isInScope(path: string): boolean
}

// 来自 packages/lsp/lsp-stdio/src/index.ts（概念性）
class StdioLspProvider implements LspProvider {
  /** 启动 LSP 服务器 */
  async startServer(language: string): Promise<LspConnection> {
    const serverPath = this.resolveServerPath(language)
    const process = spawn(serverPath, ['--stdio'])
    
    return {
      async sendRequest(method, params) {
        // 发送 JSON-RPC 请求
        const request = { jsonrpc: '2.0', id: nextId++, method, params }
        process.stdin.write(JSON.stringify(request) + '\n')
        
        // 等待响应
        return waitForResponse(request.id)
      },
      
      async sendNotification(method, params) {
        const notification = { jsonrpc: '2.0', method, params }
        process.stdin.write(JSON.stringify(notification) + '\n')
      }
    }
  }
}

// 来自 packages/web/web-search/src/index.ts（概念性）
class WebSearchProvider implements WebSearchProvider {
  /** 搜索网页 */
  async search(query: string, options: SearchOptions): Promise<SearchResult[]> {
    const response = await fetch(`https://api.search.example/search`, {
      method: 'POST',
      body: JSON.stringify({ query, ...options })
    })
    
    return response.json()
  }
}

// 来自 packages/web/web-fetch/src/index.ts（概念性）
class WebFetchProvider implements WebFetchProvider {
  /** 获取网页内容 */
  async fetch(url: string, options: FetchOptions): Promise<FetchResult> {
    const response = await fetch(url)
    const content = await response.text()
    
    return {
      url,
      title: extractTitle(content),
      content: extractText(content),
      links: extractLinks(content)
    }
  }
}

// 来自 packages/skill/skill/src/index.ts
class SkillRegistry {
  /** 注册 Skill */
  register(skill: Skill): Disposable
  
  /** 获取 Skill */
  get(name: string): Skill | undefined
  
  /** 列出所有 Skill */
  list(): Skill[]
}

interface Skill {
  /** Skill 名称 */
  name: string
  /** 描述 */
  description: string
  /** 执行函数 */
  execute(input: unknown, context: SkillContext): Promise<unknown>
}

// 1. Service Definition
interface ImageProcessingService {
  resize(image: Buffer, width: number, height: number): Promise<Buffer>
  compress(image: Buffer, quality: number): Promise<Buffer>
}

// 2. Provider
class LocalImageProcessingProvider implements ImageProcessingService {
  async resize(image: Buffer, width: number, height: number): Promise<Buffer> {
    // 使用 sharp 或其他库处理
    return sharp(image).resize(width, height).toBuffer()
  }
}

// 3. Consumer 工具
ctx.tools.register({
  name: 'image_resize',
  description: 'Resize an image',
  parameters: {
    type: 'object',
    properties: {
      image_path: { type: 'string' },
      width: { type: 'number' },
      height: { type: 'number' }
    }
  },
  async execute(input) {
    const image = await ctx.fs.readBytes(input.image_path)
    const resized = await ctx.imageProcessing.resize(image, input.width, input.height)
    return { path: '/tmp/resized.jpg' }
  }
})