04 自定义工具与项目级配置目录

04 自定义工具与项目级配置目录

本节摘要:这是第 11 章的收尾,讲四类扩展点的最后一个——自定义工具,以及如何把四类扩展组织进项目。自定义工具是「代码级补一个工具」,比插件轻、比内置灵活。本节讲清它怎么写、放哪,以及那个组织一切的「项目级配置目录」——它把自定义工具、技能、命令、插件收纳到一个标准位置,让扩展有家可归。

一、自定义工具:代码级补一个工具

第 5 章我们说工具来自三类来源:内置、自定义、插件。自定义工具就是中间那类——你用代码写一个工具,放进项目,OpenCode 自动发现并注册。

它和插件的区别在于重量级:

如果你只是「想加一个特定工具」(比如「查 GitHub PR」),自定义工具就够,不用写整个插件包。

二、自定义工具怎么写

自定义工具是一个脚本文件(通常是 TypeScript/JavaScript),放在项目的工具目录下(如 tool/ 或 tools/)。文件里导出一个工具定义——名字、描述、参数 schema、执行函数:

// 概念性示例:一个自定义工具
export default {
  name: "github_pr_search",
  description: "搜索当前仓库的 GitHub PR",
  args: { query: zod.string() },
  execute: async ({ query }) => {
    // 调 GitHub API 搜 PR
    return results;
  }
}
​

OpenCode 会扫描工具目录,动态导入这些文件,把它们注册进工具注册表(第 5 章)。文件名通常成为工具的「命名空间」,避免和别的工具重名。

💡 动态导入的妙处:自定义工具是「放进去就生效」——你丢一个工具脚本到目录,OpenCode 自动发现、导入、注册。不用改配置、不用重启(配合第 8 章 Reload)。这让「加个工具」变得极轻。

三、项目级配置目录:扩展的家

四类扩展点(插件/技能/命令/自定义工具)都收纳到一个项目级配置目录里。这个目录是 OpenCode 约定俗成的「扩展之家」,大致结构:

项目根/
   └─ 配置目录(如 .opencode/)
      ├─ agent/        自定义 Agent 配置(第 4 章)
      ├─ command/      斜杠命令(.md 模板)
      ├─ tool/         自定义工具(.ts 脚本)
      ├─ skills/       技能(SKILL.md 文件)
      ├─ plugins/      插件(.js/.ts)
      ├─ themes/       主题
      ├─ glossary/     术语表
      └─ (配置文件)   如 opencode.jsonc
​

这个目录是「约定的家」——OpenCode 知道去哪找每种扩展。你按这个结构放文件,OpenCode 自动发现并加载。

四、配置文件:统筹全局

配置目录里还有一个核心配置文件(如 opencode.jsonc),它统筹全局设置:

• 模型 Provider 配置(用哪个厂商)
• Agent 配置(覆盖内置/新增自定义,第 4 章)
• 权限规则(第 4 章)
• 技能/命令/插件路径(指定额外来源)
• 其他(主题、目录等)

这个配置文件是「项目的 OpenCode 总设置」。第 12 章会详讲配置体系,这里你只要知道它存在、它是统筹全局的。

五、扩展的发现与重载

把扩展放进配置目录后,OpenCode 怎么感知?分两种情况:

首次启动

启动时,OpenCode 扫描配置目录,发现并加载所有扩展(自定义工具、技能、命令、插件)。

运行中变更

运行中你加/改/删了扩展文件,OpenCode 怎么知道?靠第 8 章(OpenWork 教程)的 Reload 机制——文件变更触发 Reload 事件,驱动重载,新扩展生效。这就是为什么「丢个工具脚本进去,不用重启就能用」。

你加了一个工具脚本
   │
   ▼ 文件变更被检测(指纹去重)
   │
   ▼ 触发 Reload 事件
   │
   ▼ 重载:重新扫描、导入、注册
   │
   ▼ 新工具可用
​

六、四类扩展的协作

最后,把四类扩展放一起看它们如何协作:

项目配置目录
   ├─ plugins/   ──► 重型全能扩展(工具+钩子+Provider)
   ├─ skills/    ──► 模型按需加载的指令(渐进式披露)
   ├─ command/   ──► 用户快捷发起的模板
   └─ tool/      ──► 代码级补一个工具
        │
        ▼ 都汇入工具注册表 / 系统上下文
        │
        ▼ 模型可用工具集 / 上下文
​

它们各管一摊,但最终都汇入「工具注册表」或「系统上下文」,被 Agent 统一使用。选型原则再强调一遍:

• 复杂多面扩展 → 插件
• 模型按需指令 → 技能
• 用户快捷发起 → 命令
• 补一个特定工具 → 自定义工具

七、第 11 章收尾:扩展生态

读完第 11 章四节,你掌握了 OpenCode 的完整扩展生态:

核心认知:选对机制比用对语法更重要。给定一个扩展需求,先判断该用哪类(插件/技能/命令/自定义工具),再动手。第 12 章讲配置体系与多平台分发——这些扩展如何被配置和打包。

本节要点回顾

1. 自定义工具:代码级补一个工具,比插件轻、比内置灵活。
2. 写法:脚本文件导出工具定义,放工具目录,OpenCode 动态导入注册。
3. 动态导入:放进去就生效,不用改配置/重启(配合 Reload)。
4. 项目级配置目录:四类扩展的家(agent/command/tool/skills/plugins 等)。
5. 配置文件:统筹全局(Provider/Agent/权限/路径)。
6. 发现与重载:首次启动扫描,运行中变更靠 Reload。
7. 第 11 章结束:选对机制比用对语法重要——四类扩展各管一摊,汇入注册表/上下文。

第 11 章结束。下一章讲配置体系与多平台分发——扩展如何被配置、项目如何被打包分发。