内部模块: Tool (工具系统)

export namespace ToolRegistry {
  // 状态管理
  export const state = Instance.state(async () => {
    const custom = [] as Tool.Info[]
    
    // 1. 扫描配置目录
    const glob = new Bun.Glob("tool/*.{js,ts}")
    for (const dir of await Config.directories()) {
      for await (const match of glob.scan({ cwd: dir })) {
        const mod = await import(match)
        // 注册工具...
      }
    }
    
    // 2. 加载插件工具
    const plugins = await Plugin.list()
    for (const plugin of plugins) {
      for (const [id, def] of Object.entries(plugin.tool ?? {})) {
        custom.push(fromPlugin(id, def))
      }
    }
    
    return { custom }
  })
  
  // 获取所有工具
  async function all(): Promise<Tool.Info[]> {
    const custom = await state().then(x => x.custom)
    return [
      InvalidTool,
      QuestionTool,
      BashTool,
      ReadTool,
      EditTool,
      // ... 所有内置工具
      ...custom  // 自定义工具
    ]
  }
  
  // 为特定 Agent 过滤工具
  export async function tools(
    agentId: string,
    providerID: string
  ): Promise<Tool.Info[]> {
    const all = await this.all()
    
    // 过滤规则
    return all.filter(tool => {
      // 某些工具仅对特定 provider 可用
      if (tool.id === "codesearch") {
        return providerID === "opencode"
      }
      return true
    })
  }
}

export namespace Tool {
  export type Info = {
    id: string
    init: (context: InitContext) => Promise<Definition>
  }
  
  export type Definition = {
    description: string
    parameters: z.ZodObject<any>
    execute: (
      args: any,
      context: ExecuteContext
    ) => Promise<Result>
  }
  
  export type Result = {
    title: string
    output: string | object
    metadata?: {
      truncated?: boolean
      outputPath?: string
      [key: string]: any
    }
  }
}

// 工具的 init 阶段
const toolInfo: Tool.Info = {
  id: "read",
  init: async (initCtx) => ({
    description: "读取文件内容",
    parameters: z.object({
      filePath: z.string().describe("文件路径")
    }),
    execute: async (args, execCtx) => {
      // 执行逻辑
      const content = await Bun.file(args.filePath).text()
      return {
        title: args.filePath,
        output: content
      }
    }
  })
}

// packages/opencode/src/tool/read.ts
export const ReadTool: Tool.Info = {
  id: "read",
  init: async (initCtx) => ({
    description: "读取文件内容",
    parameters: z.object({
      filePath: z.string(),
      offset: z.number().optional(),
      limit: z.number().optional()
    }),
    
    async execute(args, ctx) {
      // 1. 验证路径
      const filePath = path.resolve(
        ctx.sessionDirectory,
        args.filePath
      )
      
      // 2. 读取文件
      const file = Bun.file(filePath)
      const content = await file.text()
      
      // 3. 处理偏移和限制
      const lines = content.split("\n")
      const start = args.offset || 0
      const end = args.limit 
        ? start + args.limit 
        : lines.length
      
      const output = lines
        .slice(start, end)
        .map((line, i) => `${start + i + 1}| ${line}`)
        .join("\n")
      
      return {
        title: filePath,
        output,
        metadata: {
          totalLines: lines.length,
          returnedLines: end - start
        }
      }
    }
  })
}

export namespace Truncate {
  // 默认限制
  const MAX_OUTPUT_SIZE = 50 * 1024  // 50KB
  const MAX_LINES = 2000
  
  export async function output(
    result: any,
    options: TruncateOptions,
    agent?: Agent.State
  ): Promise<TruncateResult> {
    const output = typeof result === "string" 
      ? result 
      : JSON.stringify(result, null, 2)
    
    // 检查是否需要截断
    if (output.length <= MAX_OUTPUT_SIZE) {
      return {
        content: output,
        truncated: false
      }
    }
    
    // 截断并保存到文件
    const outputPath = path.join(
      agent.directory,
      ".opencode/output",
      `${Date.now()}.txt`
    )
    
    await Bun.write(outputPath, output)
    
    // 返回截断的内容
    const truncated = output.slice(0, MAX_OUTPUT_SIZE)
    return {
      content: truncated + `\n\n... (truncated, full output in ${outputPath})`,
      truncated: true,
      outputPath
    }
  }
}

import { z } from "zod"
import type { ToolDefinition } from "@opencode-ai/plugin"
 
export default {
  description: "我的自定义工具",
  args: {
    input: z.string().describe("输入参数")
  },
  async execute(args, ctx) {
    // 工具逻辑
    const result = processInput(args.input)
    return result
  }
} satisfies ToolDefinition

// my-plugin.ts
export default async function plugin({ client, $ }) {
  return {
    tool: {
      "my-tool": {
        description: "我的自定义工具",
        args: {
          input: z.string()
        },
        async execute(args, ctx) {
          return `处理结果: ${args.input}`
        }
      }
    }
  }
}

export const BashTool: Tool.Info = {
  id: "bash",
  init: async (initCtx) => ({
    description: "执行 Shell 命令",
    parameters: z.object({
      command: z.string(),
      workdir: z.string().optional(),
      timeout: z.number().optional()
    }),
    
    async execute(args, ctx) {
      // 超时控制
      const timeout = args.timeout || 120000 // 2分钟
      
      // 执行命令
      const proc = Bun.spawn(["/bin/bash", "-c", args.command], {
        cwd: args.workdir || ctx.sessionDirectory,
        stdout: "pipe",
        stderr: "pipe"
      })
      
      // 等待完成
      const result = await Promise.race([
        proc.exited,
        new Promise((_, reject) => 
          setTimeout(() => reject(new Error("Timeout")), timeout)
        )
      ])
      
      const stdout = await new Response(proc.stdout).text()
      const stderr = await new Response(proc.stderr).text()
      
      return {
        title: args.command,
        output: stdout || stderr,
        metadata: {
          exitCode: proc.exitCode,
          stderr: stderr
        }
      }
    }
  })
}

export const EditTool: Tool.Info = {
  id: "edit",
  init: async (initCtx) => ({
    description: "编辑文件（精确替换）",
    parameters: z.object({
      filePath: z.string(),
      oldString: z.string(),
      newString: z.string(),
      replaceAll: z.boolean().optional()
    }),
    
    async execute(args, ctx) {
      // 读取文件
      const filePath = path.resolve(ctx.sessionDirectory, args.filePath)
      const content = await Bun.file(filePath).text()
      
      // 执行替换
      let newContent
      if (args.replaceAll) {
        newContent = content.replaceAll(args.oldString, args.newString)
      } else {
        // 检查是否唯一
        const count = (content.match(new RegExp(
          escapeRegex(args.oldString), 
          "g"
        )) || []).length
        
        if (count === 0) {
          throw new Error("oldString not found")
        }
        if (count > 1) {
          throw new Error("oldString found multiple times")
        }
        
        newContent = content.replace(args.oldString, args.newString)
      }
      
      // 写入文件
      await Bun.write(filePath, newContent)
      
      return {
        title: filePath,
        output: "File edited successfully"
      }
    }
  })
}

export const TaskTool: Tool.Info = {
  id: "task",
  init: async (initCtx) => ({
    description: "委派任务给子 Agent",
    parameters: z.object({
      description: z.string(),
      prompt: z.string(),
      subagent_type: z.string()
    }),
    
    async execute(args, ctx) {
      // 创建子会话
      const subSession = await Session.create({
        agentId: args.subagent_type,
        parentSessionId: ctx.sessionID
      })
      
      // 执行任务
      await Session.prompt(subSession.id, args.prompt)
      
      // 等待完成
      await Session.waitForCompletion(subSession.id)
      
      // 返回结果
      const result = await Session.getResult(subSession.id)
      
      return {
        title: args.description,
        output: result
      }
    }
  })
}

// 执行工具前的权限检查
async function executeTool(
  toolId: string,
  args: any,
  context: ExecuteContext
): Promise<Tool.Result> {
  // 1. 获取工具定义
  const toolInfo = await ToolRegistry.get(toolId)
  
  // 2. 权限检查
  const permission = await Permission.check(
    context.agentId,
    toolId,
    args
  )
  
  if (permission === "deny") {
    throw new Error("Permission denied")
  }
  
  if (permission === "ask") {
    const userResponse = await Permission.ask(
      context.sessionID,
      toolId,
      args
    )
    
    if (userResponse !== "allow") {
      throw new Error("User denied permission")
    }
  }
  
  // 3. 执行工具
  const definition = await toolInfo.init({ agent: context.agent })
  const result = await definition.execute(args, context)
  
  // 4. 截断输出
  const truncated = await Truncate.output(
    result.output,
    {},
    context.agent
  )
  
  return {
    ...result,
    output: truncated.content,
    metadata: {
      ...result.metadata,
      truncated: truncated.truncated,
      outputPath: truncated.outputPath
    }
  }
}

// ✅ 好：使用流式处理大文件
async execute(args, ctx) {
  const file = Bun.file(args.filePath)
  const stream = file.stream()
  // 处理流...
}
 
// ❌ 差：一次性加载大文件
async execute(args, ctx) {
  const content = await Bun.file(args.filePath).text()
  // 可能导致内存问题...
}

// ✅ 好：验证路径安全
async execute(args, ctx) {
  const filePath = path.resolve(ctx.sessionDirectory, args.filePath)
  
  // 防止路径遍历
  if (!filePath.startsWith(ctx.sessionDirectory)) {
    throw new Error("Access denied: path outside session directory")
  }
  
  // 继续执行...
}
 
// ❌ 差：直接使用用户输入
async execute(args, ctx) {
  await Bun.write(args.filePath, args.content)
}