1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
---
title: 自定義工具
description: 建立 LLM 可以在 opencode 中呼叫的工具。
---
自定義工具是您建立的函式，LLM 可以在對話期間呼叫。它們與 opencode 的 [內建工具](/docs/tools) 一起工作，例如 `read`、`write` 和 `bash`。
---
## 建立工具
工具定義為 **TypeScript** 或 **JavaScript** 檔案。但是，工具定義可以呼叫用 **任何語言** 編寫的指令碼 - TypeScript 或 JavaScript 僅用於工具定義本身。
---
### 位置
它們可以定義為：
- 透過將它們放在專案的 `.opencode/tools/` 目錄中來本地進行。
- 或者在全域範圍內，將它們放置在 `~/.config/opencode/tools/` 中。
---
### 結構
建立工具的最簡單方法是使用 `tool()` 輔助程式，它提供類型安全和驗證。
```ts title=".opencode/tools/database.ts" {1}
import { tool } from "@opencode-ai/plugin"
export default tool({
description: "Query the project database",
args: {
query: tool.schema.string().describe("SQL query to execute"),
},
async execute(args) {
// Your database logic here
return `Executed query: ${args.query}`
},
})
```
**檔名**成為**工具名稱**。以上建立了一個 `database` 工具。
---
#### 每個檔案多個工具
您也可以從單個檔案匯出多個工具。每個匯出都會成為**一個單獨的工具**，名稱為 **`<filename>_<exportname>`**：
```ts title=".opencode/tools/math.ts"
import { tool } from "@opencode-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
},
})
```
這將建立兩個工具：`math_add` 和 `math_multiply`。
---
### 參數 (Arguments)
您可以使用 `tool.schema`（即 [Zod](https://zod.dev)）來定義參數類型。
```ts "tool.schema"
args: {
query: tool.schema.string().describe("SQL query to execute")
}
```
您也可以直接匯入 [Zod](https://zod.dev) 並返回一個一般物件：
```ts {6}
import { z } from "zod"
export default {
description: "Tool description",
args: {
param: z.string().describe("Parameter description"),
},
async execute(args, context) {
// Tool implementation
return "result"
},
}
```
---
### 上下文 (Context)
工具接收有關當前工作階段的上下文：
```ts title=".opencode/tools/project.ts" {8}
import { tool } from "@opencode-ai/plugin"
export default tool({
description: "Get project information",
args: {},
async execute(args, context) {
// Access context information
const { agent, sessionID, messageID, directory, worktree } = context
return `Agent: ${agent}, Session: ${sessionID}, Message: ${messageID}, Directory: ${directory}, Worktree: ${worktree}`
},
})
```
使用 `context.directory` 作為工作階段工作目錄。
使用 `context.worktree` 作為 git 工作樹根。
---
## 範例
### 用 Python 編寫一個工具
您可以用任何您想要的語言編寫工具。下面是一個使用 Python 將兩個數字相加的範例。
首先，將該工具建立為 Python 指令碼：
```python title=".opencode/tools/add.py"
import sys
a = int(sys.argv[1])
b = int(sys.argv[2])
print(a + b)
```
然後建立呼叫它的工具定義：
```ts title=".opencode/tools/python-add.ts" {10}
import { tool } from "@opencode-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, ".opencode/tools/add.py")
const result = await Bun.$`python3 ${script} ${args.a} ${args.b}`.text()
return result.trim()
},
})
```
這裡我們使用 [`Bun.$`](https://bun.com/docs/runtime/shell) 公用程式來執行 Python 指令碼。
|
