Dropstone Docs

自訂工具

建立 LLM 可在 dropstone 中呼叫的工具。

自訂工具是您建立的函數，LLM 可在對話期間呼叫。它們與 Dropstone 的內建工具（如 read、write 和 bash）一起運作。

建立工具

工具定義為 TypeScript 或 JavaScript 檔案。工具定義本身是 TS/JS，但它執行的工作可以用任何語言實現：shell 指令碼、Python、Go，任何可從 Bun 的 shell 助手生成的東西。

位置

可以在以下位置定義：

  • 本地方式：將它們放在您專案的 .dropstone/tools/ 目錄中。
  • 或全域方式：將它們放在 ~/.config/dropstone/tools/。

結構

建立工具的最簡單方式是使用 tool() 助手，它提供型別安全和驗證。

import { tool } from "@blankline/dropstone-plugin"

export default tool({
  description: "查詢專案資料庫",
  args: {
    query: tool.schema.string().describe("要執行的 SQL 查詢"),
  },
  async execute(args) {
    // 您的資料庫邏輯在這裡
    return `執行查詢：${args.query}`
  },
})

檔案名稱變成工具名稱。上面建立了一個 database 工具。

每個檔案多個工具

您也可以從單個檔案匯出多個工具。每個匯出變成一個單獨的工具，名稱為 <filename>_<exportname>：

import { tool } from "@blankline/dropstone-plugin"

export const add = tool({
  description: "加兩個數字",
  args: {
    a: tool.schema.number().describe("第一個數字"),
    b: tool.schema.number().describe("第二個數字"),
  },
  async execute(args) {
    return args.a + args.b
  },
})

export const multiply = tool({
  description: "乘以兩個數字",
  args: {
    a: tool.schema.number().describe("第一個數字"),
    b: tool.schema.number().describe("第二個數字"),
  },
  async execute(args) {
    return args.a * args.b
  },
})

這建立了兩個工具：math_add 和 math_multiply。

與內建工具的名稱衝突

自訂工具由工具名稱鍵入。如果自訂工具使用與內建工具相同的名稱，自訂工具優先。

例如，此檔案取代內建的 bash 工具：

import { tool } from "@blankline/dropstone-plugin"

export default tool({
  description: "受限的 bash 包裝器",
  args: {
    command: tool.schema.string(),
  },
  async execute(args) {
    return `已阻止：${args.command}`
  },
})

Note:

除非您有意要取代內建工具，否則偏好使用唯一名稱。如果您想停用內建工具但不覆蓋它，請使用權限。

引數

您可以使用 tool.schema（只是 Zod）來定義引數型別。

args: {
  query: tool.schema.string().describe("要執行的 SQL 查詢")
}

您也可以直接匯入 Zod 並傳回純物件：

import { z } from "zod"

export default {
  description: "工具描述",
  args: {
    param: z.string().describe("參數描述"),
  },
  async execute(args, context) {
    // 工具實現
    return "結果"
  },
}

上下文

工具接收有關目前工作階段的上下文：

import { tool } from "@blankline/dropstone-plugin"

export default tool({
  description: "取得專案資訊",
  args: {},
  async execute(args, context) {
    // 存取上下文資訊
    const { agent, sessionID, messageID, directory, worktree } = context
    return `代理：${agent}，工作階段：${sessionID}，訊息：${messageID}，目錄：${directory}，工作樹：${worktree}`
  },
})

使用 context.directory 表示工作階段工作目錄。 使用 context.worktree 表示 git 工作樹根目錄。

範例

用 Python 寫工具

您可以用任何語言寫工具。以下是使用 Python 加兩個數字的範例。

首先，建立工具作為 Python 指令碼：

import sys

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

然後建立呼叫它的工具定義：

import { tool } from "@blankline/dropstone-plugin"
import path from "path"

export default tool({
  description: "使用 Python 加兩個數字",
  args: {
    a: tool.schema.number().describe("第一個數字"),
    b: tool.schema.number().describe("第二個數字"),
  },
  async execute(args, context) {
    const script = path.join(context.worktree, ".dropstone/tools/add.py")
    const result = await Bun.$`python3 ${script} ${args.a} ${args.b}`.text()
    return result.trim()
  },
})

這裡我們使用 Bun.$ 公用程式來執行 Python 指令碼。

Ctrl+I