TraceKit (OpenCode Tracepoint Plugin)

TraceKit 是一个面向 OpenCode 的可观测性插件，支持：

• 自动拦截 tool/skill 调用并记录 span（start/end）
• 在任意 agent 和 skill 中显式打点（trace_emit）
• 记录自定义指标（trace_counter）与业务阶段（trace_span）
• 将 trace 以 ndjson 落盘，并支持离线导出和分析

安装与接入步骤见：plugins/tracekit/docs/installation.md 发布到 npm 见：plugins/tracekit/docs/publish.md

npm 安装（发布后）

npm install opencode-tracekit

目录结构

plugins/tracekit/
  index.ts
  src/
    tracekit_plugin.ts
    trace_record.ts
    ndjson_writer.ts
    span_context.ts
    hooks_tool.ts
    hooks_session.ts
    tools_trace_emit.ts
    tools_trace_counter.ts
    tools_trace_span.ts
    analyzer.ts
    exporter.ts
    cli.ts

快速接入

import { createTraceKitPlugin } from "./plugins/tracekit";

const tracekit = createTraceKitPlugin({
  outPath: "./trace.ndjson",
  includeCounterTool: true,
  includeSpanTool: true,
});

// 伪代码：把 hooks / tools 注册给 OpenCode runtime
opencode.registerPlugin({
  hooks: tracekit.hooks,
  tools: tracekit.tools,
  shutdown: tracekit.shutdown,
});

在 Agent / Skill 中插入 trace 点

Tracepoint

{
  "tool": "trace_emit",
  "args": {
    "name": "agent.plan.generated",
    "level": "info",
    "attrs": { "agent": "planner", "stepCount": 4 }
  }
}

自定义 Span（业务阶段）

{ "tool": "trace_span", "args": { "op": "start", "name": "ipd.phase.spec" } }
{ "tool": "trace_emit", "args": { "name": "spec.ready" } }
{ "tool": "trace_span", "args": { "op": "end", "status": "ok" } }

Counter

{
  "tool": "trace_counter",
  "args": {
    "name": "spec.requirements.count",
    "value": 23
  }
}

导出与分析

# 统计分析
node dist/cli.js analyze ./trace.ndjson

# 导出 JSON
node dist/cli.js export ./trace.ndjson --out ./trace.json --format json

# 导出 CSV
node dist/cli.js export ./trace.ndjson --out ./trace.csv --format csv

Record 协议

参考 src/trace_record.ts，核心事件类型：

• capture_start / capture_end
• session
• span_start / span_end
• tracepoint
• marker
• counter