Özel Araçlar

Özel araçlar, sizin yazdığınız ve LLM’in sohbet sırasında çağırabildiği fonksiyonlardır. Kodine’ın read, write ve bash gibi yerleşik araçlarıyla yan yana çalışırlar.

---

Araç oluşturma

Araçlar TypeScript ya da JavaScript dosyaları biçiminde tanımlanır. Ancak araç tanımının içinden istediğiniz dilde yazılmış betikleri çağırabilirsiniz; TypeScript/JavaScript yalnızca araç tanımının kendisi için gereklidir.

---

Konum

Araçlar şu iki yere konabilir:

• Proje düzeyinde: projenizdeki .kodine/tools/ dizinine
• Global olarak: ~/.config/kodine/tools/ dizinine

---

Yapı

Araç yazmanın en pratik yolu, tür güvenliği ve doğrulama sağlayan tool() yardımcısıdır.

.kodine/tools/database.ts

import { tool } from "@kodine-ai/plugin"

export default tool({
  description: "Query the project database",
  args: {
    query: tool.schema.string().describe("SQL query to execute"),
  },
  async execute(args) {
    // Veritabanı mantığınız buraya
    return `Executed query: ${args.query}`
  },
})

Dosya adı aynı zamanda araç adı olur. Yukarıdaki örnek database adlı bir araç üretir.

---

Dosya başına birden fazla araç

Tek bir dosyadan birden çok araç da dışa aktarabilirsiniz. Her bir export, <filename>_<exportname> adını taşıyan ayrı bir araç haline gelir:

.kodine/tools/math.ts

import { tool } from "@kodine-ai/plugin"

export const add = tool({
  description: "Add two numbers",
  args: {
    a: tool.schema.number().describe("First number"),
    b: tool.schema.number().describe("Second number"),
  },
  async execute(args) {
    return args.a + args.b
  },
})

export const multiply = tool({
  description: "Multiply two numbers",
  args: {
    a: tool.schema.number().describe("First number"),
    b: tool.schema.number().describe("Second number"),
  },
  async execute(args) {
    return args.a * args.b
  },
})

Bu dosya iki araç üretir: math_add ve math_multiply.

---

Yerleşik araçlarla ad çakışmaları

Özel araçlar, araç adına göre eşleştirilir. Özel aracınız yerleşik bir araçla aynı adı taşıyorsa özel olan kazanır.

Örneğin şu dosya, yerleşik bash aracının yerini alır:

.kodine/tools/bash.ts

import { tool } from "@kodine-ai/plugin"

export default tool({
  description: "Restricted bash wrapper",
  args: {
    command: tool.schema.string(),
  },
  async execute(args) {
    return `blocked: ${args.command}`
  },
})

Note

Bilinçli olarak yerleşik bir aracı ezmek istemiyorsanız benzersiz adlar seçin. Amacınız yalnızca yerleşik aracı kapatmaksa (ezmek değil) izinleri kullanın.

---

Argümanlar

Argüman tiplerini tanımlarken Zod tabanlı tool.schema yardımcısını kullanabilirsiniz.

args: {
  query: tool.schema.string().describe("SQL query to execute")
}

Dilerseniz Zod’u doğrudan içe aktarıp düz bir nesne de döndürebilirsiniz:

import { z } from "zod"

export default {
  description: "Tool description",
  args: {
    param: z.string().describe("Parameter description"),
  },
  async execute(args, context) {
    // Aracın uygulaması
    return "result"
  },
}

---

Bağlam

Araçlar, yürütüldükleri oturuma dair bağlam bilgisi alır:

.kodine/tools/project.ts

import { tool } from "@kodine-ai/plugin"

export default tool({
  description: "Get project information",
  args: {},
  async execute(args, context) {
    // Bağlam bilgilerine erişim
    const { agent, sessionID, messageID, directory, worktree } = context
    return `Agent: ${agent}, Session: ${sessionID}, Message: ${messageID}, Directory: ${directory}, Worktree: ${worktree}`
  },
})

Oturumun çalışma dizini için context.directory kullanın. Git worktree kökü için context.worktree kullanın.

---

Örnekler

Python ile araç yazma

Araçlarınızı dilediğiniz dilde yazabilirsiniz. Aşağıda, Python ile iki sayıyı toplayan bir örnek var.

Önce Python betiğini oluşturun:

.kodine/tools/add.py

import sys

a = int(sys.argv[1])
b = int(sys.argv[2])
print(a + b)

Ardından bu betiği çağıran araç tanımını yazın:

.kodine/tools/python-add.ts

import { tool } from "@kodine-ai/plugin"
import path from "path"

export default tool({
  description: "Add two numbers using Python",
  args: {
    a: tool.schema.number().describe("First number"),
    b: tool.schema.number().describe("Second number"),
  },
  async execute(args, context) {
    const script = path.join(context.worktree, ".kodine/tools/add.py")
    const result = await Bun.$`python3 ${script} ${args.a} ${args.b}`.text()
    return result.trim()
  },
})

Burada Python betiğini çalıştırmak için Bun.$ yardımcısından yararlanıyoruz.