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 的 [Built-in Tools](/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`。
---
### 参数
您可以使用 `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"
},
}
```
---
### 上下文
工具接收有关当前会话的上下文：
```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 脚本。
|
