🎬 HoRain云小助手：个人主页

 🔥 个人专栏: 《Linux 系列教程》《c语言教程》

⛺️生活的理想，就是为了理想的生活!

---

⛳️ 推荐

前些天发现了一个超棒的服务器购买网站，性价比超高，大内存超划算！忍不住分享一下给大家。点击跳转到网站。

专栏介绍

专栏名称	专栏介绍
《C语言》	本专栏主要撰写C干货内容和编程技巧，让大家从底层了解C，把更多的知识由抽象到简单通俗易懂。
《网络协议》	本专栏主要是注重从底层来给大家一步步剖析网络协议的奥秘，一起解密网络协议在运行中协议的基本运行机制！
《docker容器精解篇》	全面深入解析 docker 容器，从基础到进阶，涵盖原理、操作、实践案例，助您精通 docker。
《linux系列》	本专栏主要撰写Linux干货内容，从基础到进阶，知识由抽象到简单通俗易懂，帮你从新手小白到扫地僧。
《python 系列》	本专栏着重撰写Python相关的干货内容与编程技巧，助力大家从底层去认识Python，将更多复杂的知识由抽象转化为简单易懂的内容。
《试题库》	本专栏主要是发布一些考试和练习题库（涵盖软考、HCIE、HRCE、CCNA等）

目录

⛳️ 推荐

专栏介绍

一、什么是自定义工具

二、工具存放位置

三、基础工具定义（推荐方式）

四、单文件多工具

五、与内置工具冲突

六、参数定义（Zod）

七、上下文（Context）

八、调用外部语言（Python 示例）

1、Python 脚本

2、工具封装

九、最佳实践

---

自定义工具（Custom Tools）允许你为 OpenCode 扩展能力，让 LLM 在对话过程中调用你定义的函数，从而实现数据库查询、脚本执行、API 调用等复杂操作。

这些工具会与内置工具（如 read、write、bash）协同工作，构建完整的自动化开发能力体系。

---

自定义工具是 OpenCode 的核心扩展能力，它让 LLM 从只会生成代码，升级为可以执行任务。

通过合理设计工具，你可以构建：

• 自动化开发流水线
• 智能代码助手
• AI 运维系统
• 企业内部 AI 工具平台

---

一、什么是自定义工具

自定义工具本质上是一个函数接口，LLM 可以在运行过程中主动调用它，并获取执行结果。

典型应用场景：

• 查询数据库（SQL / NoSQL）
• 调用内部 API
• 执行脚本（Python / Shell）
• 读取系统状态或环境信息
• 封装复杂业务逻辑

你可以理解为：让 AI 拥有执行能力的插件机制。

---

二、工具存放位置

OpenCode 会自动加载以下目录中的工具：

• 项目级：.opencode/tools/
• 全局级：~/.config/opencode/tools/

文件名即工具名称（非常关键）。

---

三、基础工具定义（推荐方式）

使用 tool() 辅助函数可以获得类型安全和参数校验能力。

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) {
    return `Executed query: ${args.query}`
  },
})

说明：

• description：工具描述，LLM 用于判断是否调用
• args：参数定义（基于 Zod）
• execute：实际执行逻辑

---

四、单文件多工具

一个文件可以导出多个工具，每个工具会自动命名为：

<文件名>_<导出名>

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

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

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

最终生成工具：

• math_add
• math_multiply

---

五、与内置工具冲突

如果你的工具名称与内置工具相同，会覆盖内置工具。

// 覆盖内置 bash 工具
export default tool({
  description: "Restricted bash wrapper",
  args: {
    command: tool.schema.string(),
  },
  async execute(args) {
    return `blocked: ${args.command}`
  },
})

建议：

• 避免命名冲突
• 如果只是限制能力，优先使用 permission 配置

---

六、参数定义（Zod）

参数使用 Zod Schema 定义，支持类型校验与描述：

args: {
  query: tool.schema.string().describe("SQL query"),
  limit: tool.schema.number().optional(),
}

也可以直接使用 Zod：

import { z } from "zod"

export default {
  description: "Example tool",
  args: {
    name: z.string(),
  },
  async execute(args) {
    return `Hello ${args.name}`
  },
}

---

七、上下文（Context）

工具执行时会自动注入上下文信息：

export default tool({
  description: "Get project info",
  args: {},
  async execute(args, context) {
    const { agent, sessionID, directory, worktree } = context
    return `Agent: ${agent}, Dir: ${directory}`
  },
})<

可用字段：

• agent：当前代理
• sessionID：会话 ID
• messageID：消息 ID
• directory：当前工作目录
• worktree：Git 根目录

---

八、调用外部语言（Python 示例）

你可以用任何语言实现工具逻辑，例如 Python。

1、Python 脚本

# .opencode/tools/add.py
import sys

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

print(a + b)

2、工具封装

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

export default tool({
  description: "Add two numbers using Python",
  args: {
    a: tool.schema.number(),
    b: tool.schema.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()
  },
})

这种方式适合：

• 已有 Python 工具链
• 调用数据分析 / AI 模型
• 执行复杂计算任务

---

九、最佳实践

• 工具描述要清晰，帮助 LLM 正确选择
• 参数设计尽量简单明确
• 避免副作用（除非明确需要）
• 优先通过 permission 控制风险操作
• 工具应聚焦单一职责

❤️❤️❤️本人水平有限，如有纰漏，欢迎各位大佬评论批评指正！😄😄😄

💘💘💘如果觉得这篇文对你有帮助的话，也请给个点赞、收藏下吧，非常感谢!👍 👍 👍

🔥🔥🔥Stay Hungry Stay Foolish 道阻且长,行则将至,让我们一起加油吧！🌙🌙🌙