17.4 实验四：编写 OpenCode Plugin

模型: claude-opus-4-6 (anthropic/claude-opus-4-6) 生成日期: 2026-02-18

---

前三个实验中，我们从零搭建了 LLM CLI 对话工具、添加了 Tool Use 能力、构建了 MCP Server。这些都是独立项目——它们运行在 OpenCode 之外。本节我们转换视角，深入 OpenCode 内部——通过编写一个 Plugin，直接扩展 OpenCode 的核心能力。

在第 13 章我们详细分析了 Plugin 系统的架构：@opencode-ai/plugin 包定义了类型接口，plugin/index.ts 实现了加载机制，oh-my-opencode 展示了 Plugin 系统的全部威力。现在我们动手实现一个自己的 Plugin。

17.4.1 目标

实现一个名为 opencode-plugin-guardian 的 Plugin，包含以下功能：

1. chat.message Hook：在每次用户发送消息时，自动注入项目规范（如代码风格要求）

2. tool.execute.before Hook：在工具执行前记录操作日志

3. tool.execute.after Hook：在工具执行后记录结果和耗时

4. 自定义工具 project_stats：统计项目的文件数量、代码行数等基本信息

通过这个实验，你将亲手体验 Plugin 的完整开发流程——从类型定义到 Hook 编写，从工具注册到本地调试。

17.4.2 回顾 Plugin 接口

在开始编码之前，让我们回顾 @opencode-ai/plugin 定义的核心类型（详见第 13.1 节）：

// 核心类型定义
type Plugin = (input: PluginInput) => Promise<Hooks>

type PluginInput = {
  client: ReturnType<typeof createOpencodeClient>  // OpenCode SDK 客户端
  project: Project                                   // 当前项目信息
  directory: string                                  // 当前工作目录
  worktree: string                                   // 项目根目录
  serverUrl: URL                                     // OpenCode Server URL
  $: BunShell                                        // Shell 执行接口
}

Plugin 的本质是一个异步函数：接收 PluginInput 上下文，返回一个 Hooks 对象。Hooks 中的每个字段对应一个生命周期钩子，OpenCode 会在合适的时机调用它们。

衍生解释——什么是生命周期钩子（Lifecycle Hook）？

生命周期钩子是一种软件设计模式，允许外部代码在框架的关键执行节点"挂载"自定义逻辑。就像 React 的 useEffect 在组件挂载/更新时执行，或者 Git 的 pre-commit Hook 在提交前执行一样，OpenCode 的 Plugin Hook 在消息发送、工具执行等关键节点被触发。

核心思想是控制反转（Inversion of Control）：你不需要修改 OpenCode 的源码，只需在规定的接口上注册回调函数，框架会在合适的时机调用你的代码。

17.4.3 实现步骤

步骤一：初始化项目

# 创建项目目录
mkdir opencode-plugin-guardian
cd opencode-plugin-guardian

# 初始化 Bun 项目
bun init -y

# 安装 Plugin 类型定义
bun add @opencode-ai/plugin

安装完成后，项目结构如下：

opencode-plugin-guardian/
├── package.json
├── tsconfig.json
├── node_modules/
└── src/
    └── index.ts        # Plugin 入口（稍后创建）

编辑 package.json，设置入口文件和构建配置：

{
  "name": "opencode-plugin-guardian",
  "version": "0.1.0",
  "main": "src/index.ts",
  "type": "module",
  "dependencies": {
    "@opencode-ai/plugin": "latest"
  }
}

步骤二：编写 Plugin 入口

创建 src/index.ts——这是 Plugin 的核心文件：

import type { Plugin, Hooks } from "@opencode-ai/plugin"
import { tool } from "@opencode-ai/plugin/tool"
import { createProjectStatsTool } from "./tools/project-stats"
import { createLogger } from "./logger"

const GuardianPlugin: Plugin = async (ctx) => {
  // 初始化日志记录器
  const logger = createLogger(ctx.directory)

  // 读取项目规范文件（如果存在）
  const guidelinesPath = `${ctx.directory}/.guardian/guidelines.md`
  let guidelines = ""
  try {
    const file = Bun.file(guidelinesPath)
    if (await file.exists()) {
      guidelines = await file.text()
    }
  } catch {
    // 没有规范文件，跳过
  }

  const hooks: Hooks = {
    // ---- 1. 注册自定义工具 ----
    tool: {
      project_stats: createProjectStatsTool(ctx),
    },

    // ---- 2. chat.message Hook：注入项目规范 ----
    "chat.message": async (input, output) => {
      if (!guidelines) return

      // 只在主会话中注入，避免子 Agent 会话重复注入
      if (!input.agent || input.agent === "build") {
        // 将项目规范作为附加的文本 Part 注入到消息中
        output.parts.push({
          type: "text",
          text: [
            "<project-guidelines>",
            guidelines,
            "</project-guidelines>",
          ].join("\n"),
        })
      }
    },

    // ---- 3. tool.execute.before Hook：执行前日志 ----
    "tool.execute.before": async (input, output) => {
      const timestamp = new Date().toISOString()
      logger.log(
        `[${timestamp}] BEFORE | tool=${input.tool} | session=${input.sessionID} | args=${JSON.stringify(output.args).slice(0, 200)}`
      )
    },

    // ---- 4. tool.execute.after Hook：执行后日志 ----
    "tool.execute.after": async (input, output) => {
      if (!output) return
      const timestamp = new Date().toISOString()
      logger.log(
        `[${timestamp}] AFTER  | tool=${input.tool} | session=${input.sessionID} | title=${output.title} | output_length=${output.output.length}`
      )
    },
  }

  return hooks
}

// 默认导出，OpenCode 的 Plugin 加载器会自动发现
export default GuardianPlugin

这段代码清晰地展示了 Plugin 的四大能力：

能力	Hook 名称	执行时机
注册自定义工具	tool	Plugin 初始化时
消息拦截	chat.message	用户发送消息时
工具执行前拦截	tool.execute.before	任何工具执行前
工具执行后处理	tool.execute.after	任何工具执行后

步骤三：实现日志模块

创建 src/logger.ts——一个简单的文件日志记录器：

import * as fs from "fs"
import * as path from "path"

export function createLogger(directory: string) {
  const logDir = path.join(directory, ".guardian")
  const logFile = path.join(logDir, "operations.log")

  // 确保日志目录存在
  if (!fs.existsSync(logDir)) {
    fs.mkdirSync(logDir, { recursive: true })
  }

  return {
    log(message: string) {
      fs.appendFileSync(logFile, message + "\n")
    },
  }
}

步骤四：实现自定义工具

创建 src/tools/project-stats.ts——实现 project_stats 工具：

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

export function createProjectStatsTool(ctx: PluginInput) {
  return tool({
    description:
      "统计当前项目的基本信息，包括文件数量、代码行数、文件类型分布等。" +
      "用于快速了解项目规模和结构。",

    args: {
      path: tool.schema
        .string()
        .optional()
        .describe("要统计的目录路径，默认为项目根目录"),
      extensions: tool.schema
        .string()
        .optional()
        .describe(
          "要统计的文件扩展名，逗号分隔，如 'ts,tsx,js'。不指定则统计所有文件"
        ),
    },

    async execute(args, context) {
      const targetDir = args.path || ctx.directory
      const extensions = args.extensions
        ? new Set(args.extensions.split(",").map((e) => e.trim()))
        : null

      try {
        // 使用 ctx.$ (BunShell) 执行统计命令
        // 获取文件列表（排除 node_modules、.git 等）
        const findResult = await ctx
          .$`find ${targetDir} -type f \
              -not -path "*/node_modules/*" \
              -not -path "*/.git/*" \
              -not -path "*/dist/*" \
              -not -path "*/.opencode/*"`
          .text()

        const allFiles = findResult
          .trim()
          .split("\n")
          .filter((f) => f.length > 0)

        // 按扩展名过滤
        const files = extensions
          ? allFiles.filter((f) => {
              const ext = f.split(".").pop() || ""
              return extensions.has(ext)
            })
          : allFiles

        // 统计文件类型分布
        const extCounts: Record<string, number> = {}
        for (const file of files) {
          const ext = file.split(".").pop() || "(无扩展名)"
          extCounts[ext] = (extCounts[ext] || 0) + 1
        }

        // 统计代码行数（使用 wc -l）
        let totalLines = 0
        if (files.length > 0) {
          // 分批处理，避免参数过长
          const batchSize = 100
          for (let i = 0; i < files.length; i += batchSize) {
            const batch = files.slice(i, i + batchSize)
            try {
              const wcResult = await ctx
                .$`wc -l ${batch.join(" ")} 2>/dev/null | tail -1`
                .text()
              const match = wcResult.trim().match(/^\s*(\d+)/)
              if (match) {
                totalLines += parseInt(match[1], 10)
              }
            } catch {
              // 某些文件可能无法读取，跳过
            }
          }
        }

        // 构建输出
        const sortedExts = Object.entries(extCounts)
          .sort((a, b) => b[1] - a[1])
          .slice(0, 15) // 只显示前 15 种

        const extTable = sortedExts
          .map(([ext, count]) => `  .${ext}: ${count} 个文件`)
          .join("\n")

        return [
          `## 项目统计: ${targetDir}`,
          "",
          `- **文件总数**: ${files.length}`,
          `- **代码总行数**: ${totalLines.toLocaleString()}`,
          `- **文件类型分布** (Top ${sortedExts.length}):`,
          extTable,
        ].join("\n")
      } catch (error) {
        return `统计失败: ${error instanceof Error ? error.message : String(error)}`
      }
    },
  })
}

让我们解析这个工具实现的关键点：

1. tool() 工厂函数：来自 @opencode-ai/plugin/tool，它接受 description、args、execute 三个字段。args 使用 tool.schema（实际上就是 Zod）来定义参数 Schema，OpenCode 会自动将 Schema 转换为 LLM 能理解的 Tool 定义。

2. ctx.$（BunShell）：Plugin 通过 PluginInput 获得 Bun 的 Shell 执行能力。ctx.$\command`` 是模板字符串语法，类似在终端中执行命令。

3. context 参数：execute 函数的第二个参数提供了 sessionID、messageID、agent、abort 信号等上下文信息，可以用来做更精细的控制。

步骤五：本地调试

OpenCode 支持通过 file:// 协议加载本地 Plugin，无需发布到 npm。

编辑你的项目中的 opencode.json（或 ~/.config/opencode/opencode.json）：

{
  "plugin": [
    "file:///absolute/path/to/opencode-plugin-guardian"
  ]
}

然后启动 OpenCode：

opencode

你应该能在启动日志中看到 Plugin 被加载的信息。试试以下操作来验证：

1. 验证 chat.message Hook：在项目中创建 .guardian/guidelines.md 文件并写入一些代码规范，然后发送消息——观察 AI 是否遵循了你的规范。

2. 验证工具注册：在对话中让 AI 使用 project_stats 工具，例如输入 "统计一下当前项目的代码量"。

3. 验证日志 Hook：检查 .guardian/operations.log 文件，应该能看到每次工具调用的记录。

日志文件的输出类似这样：

[2026-02-18T10:30:15.123Z] BEFORE | tool=read | session=ses_abc123 | args={"file_path":"/src/index.ts"}
[2026-02-18T10:30:15.456Z] AFTER  | tool=read | session=ses_abc123 | title=Read(/src/index.ts) | output_length=2340
[2026-02-18T10:30:18.789Z] BEFORE | tool=project_stats | session=ses_abc123 | args={"extensions":"ts,tsx"}
[2026-02-18T10:30:19.234Z] AFTER  | tool=project_stats | session=ses_abc123 | title= | output_length=456

17.4.4 深入理解 Plugin 加载机制

让我们对照源码，看看 OpenCode 是如何加载我们的 Plugin 的。回顾第 13.3 节的分析，packages/opencode/src/plugin/index.ts 中的加载流程：

// 简化后的加载流程
for (let plugin of plugins) {
  if (!plugin.startsWith("file://")) {
    // npm 包模式：解析 name@version，通过 BunProc.install() 安装
    const pkg = parsePackageName(plugin)
    plugin = await BunProc.install(pkg.name, pkg.version)
  }

  // 导入模块
  const mod = await import(plugin)

  // 遍历所有导出，找到 Plugin 函数并初始化
  for (const [_name, fn] of Object.entries(mod)) {
    const init = await fn(input)  // 调用 Plugin 函数
    hooks.push(init)               // 收集返回的 Hooks
  }
}

关键点：

1. file:// 前缀判断是本地文件还是 npm 包。本地文件直接 import，npm 包先安装到 ~/.cache/opencode/node_modules/ 再导入。

2. OpenCode 会遍历模块的所有导出（Object.entries(mod)），找到类型为函数的导出并调用。这意味着一个模块可以导出多个 Plugin 函数。

3. Hook 触发时，所有 Plugin 返回的 Hooks 按注册顺序链式调用——先注册的 Plugin 先执行。这与中间件管道类似。

17.4.5 进阶：添加 event Hook

除了 chat.message 和 tool.execute.*，Plugin 还可以监听 OpenCode 的事件系统。让我们为 Guardian Plugin 添加会话事件监听：

// 在 hooks 对象中添加 event Hook
event: async (input) => {
  const { event } = input

  // 监听会话创建事件
  if (event.type === "session.created") {
    logger.log(`[SESSION] 新会话创建: ${JSON.stringify(event.properties)}`)
  }

  // 监听会话错误事件
  if (event.type === "session.error") {
    logger.log(`[ERROR] 会话错误: ${JSON.stringify(event.properties)}`)
  }
},

event Hook 接收 OpenCode 事件总线（第 11 章）发布的所有事件。通过 event.type 字段可以区分事件类型，event.properties 包含事件的详细数据。

17.4.6 进阶：添加 experimental.chat.system.transform Hook

这个实验性 Hook 允许你修改发送给 LLM 的 System Prompt。例如，根据当前时间注入不同的行为指令：

"experimental.chat.system.transform": async (input, output) => {
  const hour = new Date().getHours()

  if (hour >= 22 || hour < 6) {
    // 深夜模式：提醒 AI 更加谨慎
    output.system.push(
      "当前是深夜时间。用户可能比较疲劳，请在执行危险操作（如删除文件、" +
      "修改关键配置）前额外确认。回复尽量简洁，避免长篇大论。"
    )
  }
},

output.system 是一个字符串数组，最终会被拼接为 LLM 的 System Prompt。你可以向其中 push 新的指令段落。

17.4.7 发布到 npm

当 Plugin 开发完成后，你可以将其发布到 npm，这样其他 OpenCode 用户也可以使用：

# 确保 package.json 中的 name 是全局唯一的
# 登录 npm
npm login

# 发布
npm publish

发布后，用户只需在 opencode.json 中添加包名即可：

{
  "plugin": ["[email protected]"]
}

OpenCode 会自动通过 BunProc.install() 安装并加载。

17.4.8 知识点总结

通过这个实验，我们掌握了以下核心知识：

知识点	对应的源码位置	说明
Plugin 类型接口	packages/plugin/src/index.ts	Plugin、PluginInput、Hooks 类型定义
工具定义 API	packages/plugin/src/tool.ts	tool() 函数与 Zod Schema 参数定义
Hook 生命周期	packages/opencode/src/plugin/index.ts	trigger() 方法的 Hook 链式调用
本地加载	packages/opencode/src/plugin/index.ts	file:// 协议的处理逻辑
npm 加载	packages/opencode/src/bun/index.ts	BunProc.install() 动态安装机制
消息模型	packages/plugin/src/index.ts	chat.message 的 output.parts 结构

Plugin 开发的核心原则：

1. 最小侵入：Plugin 通过 Hook 扩展行为，而不是修改 OpenCode 的核心代码。

2. 容错优先：Hook 中的错误不应该导致 OpenCode 崩溃。始终使用 try-catch 包裹可能失败的操作。

3. 上下文感知：通过 PluginInput 获取当前项目信息，而非硬编码路径。使用 ctx.directory 而非 process.cwd()。

4. 按需注入：不要在每条消息中都注入大量内容——这会浪费 Token。根据 input.agent 等条件有选择地注入。

下一个实验中，我们将更进一步——模仿 oh-my-opencode 的核心架构，实现一个多 Agent 编排系统。