Hooks

Hooks（钩子）是码道CLI插件系统的核心机制，允许开发者在工具执行、消息处理、权限控制等关键节点注入自定义逻辑。插件通过返回一个Hooks对象来声明自己关注的生命周期事件，当对应事件触发时，插件的自定义函数将被调用。

表1 配置路径
配置级别	配置说明	位置
个人级	当前用户下的所有项目	“~/codeartsdoer/plugin”或“~/.codeartsdoer/plugins” “~”表示当前用户的主目录，Windows下等同于“C:\Users\用户名\”，macOS下等同于“/Users/用户名/”
项目级	仅针对当前项目生效，	“项目根目录/.codeartsdoer/plugin”或“项目根目录/.codeartsdoer/plugins”

编写示例

本文以创建个人级别的Hook为例。

以下示例创建一个JsonFormatPlugin插件，在读取.json文件后，自动将挤成一行的压缩JSON，整理成2个空格缩进的格式化形式。

进入“~\.codeartsdoer\plugin”，创建并编写文件“JsonFormatPlugin.ts”。

// 导入Plugin类型，用于定义插件
import type { Plugin } from "@opencode-ai/plugin"
// 导入文件系统模块，用于读写磁盘文件
import { readFileSync, writeFileSync } from "fs"

// 导出插件实现，Plugin是一个异步函数，接收插件输入参数并返回Hooks对象
export const JsonFormatPlugin: Plugin = async ({}) => {
  return {
    // 监听工具执行后的钩子，在工具执行完成后触发
    "tool.execute.after": async (
      // 输入参数：包含工具名称、会话ID、调用ID、参数等信息
      input: { tool: string; sessionID: string; callID: string; args: any },
      // 输出参数：包含工具执行结果的标题、输出内容、元数据
      output: { title: string; output: string; metadata: any },
    ) => {
      if (input.tool !== "read") return

      // 获取文件路径，只处理.json文件
      const filePath = input.args?.filePath || input.args?.[0] || ""
      if (!filePath.endsWith(".json")) return

      try {
        const raw = readFileSync(filePath, "utf-8").trim()
        const parsed = JSON.parse(raw)
        const formatted = JSON.stringify(parsed, null, 2) + "\n"
        if (formatted === raw) return

        // 将格式化后的内容写回磁盘文件
        writeFileSync(filePath, formatted, "utf-8")
      } catch {}
    },
  }
}

创建并编写测试文件“test-plugin.json”，内容为压缩格式的JSON。

{"plugin":"JsonFormatPlugin","test":{"input":"压缩的单行JSON","output":"格式化的多行JSON"}}

图1 格式化前

根据不同的开发模式，执行命令：
- 如果是TUI开发模式，在TUI对话框中输入如下指令并回车：
```
读取 test-plugin.json
```
- 如果是CLI开发模式，请执行如下命令：
```
codearts run "读取 test-plugin.json"
```
  图2 CLI开发模式的命令截图
执行完成后，“test-plugin.json”文件将被自动格式化为多行缩进形式。再次读取同一文件时，由于已是格式化状态，不会重复处理。

如下图所示，该JSON文件已经被格式化。

图3 格式化后的效果图