opencode-hooks-tracer 使用手册

opencode-hooks-tracer 是一个 OpenCode 插件，用 OpenCode hooks 记录会话过程，并输出为 JSONL 文件。

它保留 opencode-api-tracer 的 JSONL 查看器和交互列表，但数据来源改成 OpenCode hooks，不再 monkey patch globalThis.fetch。

1. 配置插件

本地开发时可以直接引用当前项目：

{
  "plugin": ["file:///Users/yulong/work/opencode-hooks-tracer/dist/index.js"]
}

发布到 npm 后可以改成：

{
  "plugin": ["opencode-hooks-tracer"]
}

2. 配置输出目录

推荐用环境变量指定 JSONL 输出目录：

OPENCODE_HOOKS_TRACER_DIR=/tmp/opencode-hooks-tracer \
opencode run "Reply exactly: OK"

也可以在插件配置里指定：

{
  "plugin": [
    [
      "file:///Users/yulong/work/opencode-hooks-tracer/dist/index.js",
      {
        "dir": "/tmp/opencode-hooks-tracer"
      }
    ]
  ]
}

如果不指定，默认输出到：

~/opencode-hooks-tracer

3. 输出内容

每一行是一条 JSON 记录，仍然使用 request、response、error 三类。

请求记录来自 chat.message 和 experimental.chat.system.transform：

{
  "kind": "request",
  "id": 1,
  "sessionID": "ses_...",
  "method": "HOOK",
  "url": "opencode://hook/chat.message",
  "body": {
    "source": "opencode-hooks",
    "hook": "chat.message",
    "agent": "build",
    "model": {
      "providerID": "minimax",
      "modelID": "MiniMax-M2.7-highspeed"
    },
    "system": ["..."],
    "messages": [
      {
        "role": "user",
        "content": "Reply exactly: OK"
      }
    ]
  }
}

响应记录来自 message.updated，并结合 message.part.updated、tool.execute.before、tool.execute.after 补充输出和工具调用：

{
  "kind": "response",
  "id": 1,
  "sessionID": "ses_...",
  "method": "HOOK",
  "url": "opencode://hook/message.updated",
  "status": 200,
  "body": {
    "source": "opencode-hooks",
    "hook": "message.updated",
    "output": [
      {
        "role": "assistant",
        "content": "OK"
      }
    ],
    "tool_calls": [],
    "tokens": {
      "input": 10,
      "output": 2,
      "reasoning": 1,
      "total": 13
    }
  }
}

4. 查看日志

npx --registry=https://registry.npmjs.org/ opencode-hooks-tracer /tmp/opencode-hooks-tracer

本地开发时也可以直接运行：

python3 /Users/yulong/work/opencode-hooks-tracer/scripts/opencode_api_radar.py /tmp/opencode-hooks-tracer

常用参数：

# 只查看历史，不继续监听新日志
opencode-hooks-radar /tmp/opencode-hooks-tracer --static

# 直接打开指定 session
opencode-hooks-radar /tmp/opencode-hooks-tracer --session ses_...

5. 和 opencode-api-tracer 的区别

| 项目 | 数据来源 | 能看到什么 | 看不到什么 | |---|---|---|---| | opencode-api-tracer | globalThis.fetch | 原始 HTTP request/response payload | 不走 fetch 的请求 | | opencode-hooks-tracer | OpenCode hooks | session、user message、system prompt、assistant output、tool calls、tokens | 原始 HTTP headers、真实 URL、provider 原始响应体 |

这个项目适合看 OpenCode 语义层信息；如果要逐字节分析 provider HTTP payload，仍然用 opencode-api-tracer。