OpenCode · 第 11 章 插件、技能与斜杠命令

OpenCode · 第 11 章 插件、技能与斜杠命令

章节摘要:OpenCode 提供了四类扩展点,各自解决不同的问题:插件(plugin)是包级扩展,能注册工具、适配器、Provider、界面扩展、终端环境、事件钩子;技能(Skill)是一种特殊的「上下文源」,以渐进式披露的方式暴露给模型——模型先只看到技能的名字和描述,需要时才通过技能工具读取正文;斜杠命令(slash command)是用户侧的提示词模板,输入 /某命令 就展开成预设提示;自定义工具则让你用代码定义新工具。本章的关键不是罗列这四者,而是讲清它们的边界与协作:什么时候该用插件而非技能?技能的「渐进式披露」为何比把所有指令塞进系统提示更省 token?为什么斜杠命令和技能解决的是不同问题(前者是用户快捷方式,后者是模型按需加载)?读完本章,你能为给定的扩展需求选对机制,并理解这四者如何叠加成一个完整的扩展生态。

学习目标

阅读完本章,你应当能够:

1. 列出四类扩展点(插件、技能、斜杠命令、自定义工具)的职责边界,并为给定需求选对机制。
2. 描述插件对外 API 契约:如何用模式校验定义工具、有哪些事件钩子(如系统提示变换、工具定义钩子)。
3. 解释技能作为上下文源的渐进式披露:模型先只看名字描述,按需读取正文,为什么这比全塞进系统提示更省 token。
4. 说明斜杠命令作为用户侧提示模板的用法,以及它与技能的根本区别(用户触发 vs 模型按需)。
5. 用项目级配置目录组织自定义工具、技能、命令、插件,构成完整扩展。

核心概念速览

一句话总结:四类扩展点分工明确——插件是包级全能扩展,技能是模型按需加载的渐进式披露(省 token),斜杠命令是用户快捷方式,自定义工具是代码级补充;选对机制比用对语法更重要。

子章节导航

01 插件对外 API 契约

讲插件的对外契约:如何用模式校验(而非效应 Schema)定义工具(降低插件作者门槛)、插件能注册什么(工具、工作区适配器、Provider、界面扩展、终端环境叠加)、有哪些事件钩子(如系统提示变换、工具定义钩子)。重点说明插件是「包级全能扩展」。

02 技能作为上下文源的渐进式披露

本章核心工程点。讲技能如何作为第 8 章的「上下文源」暴露给模型:模型先只看到技能的名字和描述(占很少 token),需要时通过技能工具读取正文(渐进式披露)。重点论证:为什么这比把所有指令塞进系统提示更省 token、更聚焦。

03 斜杠命令模板

讲斜杠命令:用户输入 /某命令 时,它展开成一段预设提示发给会话。重点说明它与技能的根本区别——斜杠命令是用户主动触发的快捷方式,技能是模型按需加载的能力;前者解决「快速发起」,后者解决「模型需要时才知道」。

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

讲自定义工具(项目目录下的工具脚本,通常是 TypeScript/JavaScript 文件)以及如何用项目级配置目录组织自定义工具、技能、命令、插件。给出一套推荐的项目结构,让四类扩展协同工作。

子章节之间的逻辑关系

本章遵循「包级 → 模型侧 → 用户侧 → 组织」的扩展全景路径:

插件 (01)      ──最重的包级扩展
   │
   ▼
技能 (02)      ──最精巧的渐进式披露
   │
   ▼
斜杠命令 (03)  ──最轻的用户快捷方式
   │
   ▼
自定义工具 (04) ──如何把它们组织起来
   │
   ▼
第 12 章:这些扩展如何被配置体系管理
​

前三节按「重 → 轻」介绍三类扩展,最后一节讲如何把它们组织进项目。理解了全部四节,你就能为任意扩展需求选对机制——这正是「会用扩展」与「乱用扩展」的分水岭。

前置知识与后续延伸

前置知识:

• 第 4 章权限模型(插件注册的工具同样受权限约束)
• 第 5 章工具系统(插件工具、自定义工具都进入注册表)
• 第 8 章上下文源(技能是作为一种上下文源实现的)

本章为后续章节奠定的基础:

• 四类扩展点的组织方式为第 12 章配置体系铺垫
• 技能的渐进式披露为理解 OpenCode 如何控制模型 token 预算提供另一视角
• 插件契约为第 13 章二次开发与贡献铺垫