opencode-tracekit 0.1.0 → 0.1.4

package/README.md

@@ -3,8 +3,8 @@
 TraceKit 是一个面向 OpenCode 的可观测性插件，支持：
 
 - 自动拦截 `tool/skill` 调用并记录 span（start/end）
-- 在任意 agent 和 skill 中显式打点（`trace.emit`）
-- 记录自定义指标（`trace.counter`）与业务阶段（`trace.span`）
+- 在任意 agent 和 skill 中显式打点（`trace_emit`）
+- 记录自定义指标（`trace_counter`）与业务阶段（`trace_span`）
 - 将 trace 以 `ndjson` 落盘，并支持离线导出和分析
 
 安装与接入步骤见：`plugins/tracekit/docs/installation.md`
@@ -61,7 +61,7 @@ opencode.registerPlugin({
 
 ```json
 {
-  "tool": "trace.emit",
+  "tool": "trace_emit",
   "args": {
     "name": "agent.plan.generated",
     "level": "info",
@@ -73,16 +73,16 @@ opencode.registerPlugin({
 ### 自定义 Span（业务阶段）
 
 ```json
-{ "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" } }
+{ "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
 
 ```json
 {
-  "tool": "trace.counter",
+  "tool": "trace_counter",
   "args": {
     "name": "spec.requirements.count",
     "value": 23

package/dist/index.d.ts

@@ -1,5 +1,8 @@
+import { TraceKitPlugin } from "./src/opencode_plugin.js";
 import { createTraceKitPlugin } from "./src/tracekit_plugin.js";
 export { createTraceKitPlugin };
-export default createTraceKitPlugin;
-export type { TraceKitConfig, TraceKitPlugin } from "./src/tracekit_plugin.js";
+export { TraceKitPlugin };
+export default TraceKitPlugin;
+export { createOpenCodeTraceKit } from "./src/opencode_plugin.js";
+export type { TraceKitConfig, TraceKitPlugin as TraceKitCorePlugin } from "./src/tracekit_plugin.js";
 export type { TraceRecord } from "./src/trace_record.js";

package/dist/index.js

@@ -1,3 +1,6 @@
+import { TraceKitPlugin } from "./src/opencode_plugin.js";
 import { createTraceKitPlugin } from "./src/tracekit_plugin.js";
 export { createTraceKitPlugin };
-export default createTraceKitPlugin;
+export { TraceKitPlugin };
+export default TraceKitPlugin;
+export { createOpenCodeTraceKit } from "./src/opencode_plugin.js";

package/dist/src/opencode_plugin.d.ts

@@ -0,0 +1,28 @@
+import { type TraceKitConfig } from "./tracekit_plugin.js";
+interface OpenCodePluginContext {
+    workingDirectory?: string;
+}
+interface OpenCodeExecContext {
+    sessionID?: string;
+    sessionId?: string;
+}
+interface OpenCodeToolDefinition {
+    description: string;
+    parameters: Record<string, unknown>;
+    execute: (args: Record<string, unknown>, execCtx: OpenCodeExecContext) => Promise<Record<string, unknown>>;
+}
+export declare function TraceKitPlugin(ctx: OpenCodePluginContext): Promise<{
+    tool: {
+        trace_emit: OpenCodeToolDefinition;
+        trace_counter: OpenCodeToolDefinition;
+        trace_span: OpenCodeToolDefinition;
+    };
+}>;
+export declare function createOpenCodeTraceKit(config?: TraceKitConfig): (ctx: OpenCodePluginContext) => Promise<{
+    tool: {
+        trace_emit: OpenCodeToolDefinition;
+        trace_counter: OpenCodeToolDefinition;
+        trace_span: OpenCodeToolDefinition;
+    };
+}>;
+export {};

package/dist/src/opencode_plugin.js

@@ -0,0 +1,87 @@
+import { createTraceKitPlugin } from "./tracekit_plugin.js";
+export async function TraceKitPlugin(ctx) {
+    return createOpenCodeTraceKit()(ctx);
+}
+function toRuntime(execCtx) {
+    return {
+        sessionId: String(execCtx.sessionID ?? execCtx.sessionId ?? "unknown-session"),
+        ts: Date.now(),
+    };
+}
+export function createOpenCodeTraceKit(config = {}) {
+    return async (ctx) => {
+        const workingDirectory = ctx.workingDirectory ?? process.cwd();
+        const core = createTraceKitPlugin({
+            outPath: `${workingDirectory}/trace.ndjson`,
+            ...config,
+        });
+        return {
+            tool: {
+                trace_emit: defineTool({
+                    description: "Emit a tracepoint for current session",
+                    parameters: {
+                        type: "object",
+                        properties: {
+                            name: { type: "string" },
+                            level: { type: "string", enum: ["info", "warn", "error"] },
+                            attrs: { type: "object", additionalProperties: true },
+                            links: { type: "array", items: { type: "object", additionalProperties: true } },
+                        },
+                        required: ["name"],
+                    },
+                    execute: async (args, execCtx) => {
+                        const runtime = toRuntime(execCtx);
+                        const emit = core.tools.find((t) => t.name === "trace_emit");
+                        if (!emit)
+                            return { ok: false, reason: "trace_emit tool missing" };
+                        return emit.handler(args, runtime);
+                    },
+                }),
+                trace_counter: defineTool({
+                    description: "Emit a counter metric for current session",
+                    parameters: {
+                        type: "object",
+                        properties: {
+                            name: { type: "string" },
+                            value: { type: "number" },
+                            attrs: { type: "object", additionalProperties: true },
+                        },
+                        required: ["name", "value"],
+                    },
+                    execute: async (args, execCtx) => {
+                        const runtime = toRuntime(execCtx);
+                        const counter = core.tools.find((t) => t.name === "trace_counter");
+                        if (!counter)
+                            return { ok: false, reason: "trace_counter tool missing" };
+                        return counter.handler(args, runtime);
+                    },
+                }),
+                trace_span: defineTool({
+                    description: "Create a manual span for phase tracking",
+                    parameters: {
+                        type: "object",
+                        properties: {
+                            op: { type: "string", enum: ["start", "end"] },
+                            spanId: { type: "string" },
+                            name: { type: "string" },
+                            kind: { type: "string", enum: ["manual", "message", "model", "tool", "skill"] },
+                            status: { type: "string", enum: ["ok", "error", "unknown"] },
+                            attrs: { type: "object", additionalProperties: true },
+                        },
+                        required: ["op"],
+                    },
+                    execute: async (args, execCtx) => {
+                        const runtime = toRuntime(execCtx);
+                        const span = core.tools.find((t) => t.name === "trace_span");
+                        if (!span)
+                            return { ok: false, reason: "trace_span tool missing" };
+                        return span.handler(args, runtime);
+                    },
+                }),
+            },
+        };
+    };
+}
+function defineTool(toolDef) {
+    return toolDef;
+}

package/dist/src/tools_trace_counter.js

@@ -1,6 +1,6 @@
 export function makeTraceCounterTool(writer) {
     return {
-        name: "trace.counter",
+        name: "trace_counter",
         description: "Emit a numeric counter metric for current session.",
         inputSchema: {
             type: "object",

package/dist/src/tools_trace_emit.js

@@ -1,7 +1,7 @@
 import { id } from "./utils.js";
 export function makeTraceEmitTool(writer, ctx) {
     return {
-        name: "trace.emit",
+        name: "trace_emit",
         description: "Emit a tracepoint event that is attached to the current active span.",
         inputSchema: {
             type: "object",

package/dist/src/tools_trace_span.js

@@ -1,7 +1,7 @@
 import { id } from "./utils.js";
 export function makeTraceSpanTool(writer, ctx) {
     return {
-        name: "trace.span",
+        name: "trace_span",
         description: "Start or end a manual span to capture custom business phases.",
         inputSchema: {
             type: "object",

package/docs/installation.md

@@ -70,7 +70,7 @@ npm install opencode-tracekit
 3. 检查是否有以下记录类型：
 - `capture_start`
 - `span_start` / `span_end`
-- `tracepoint`（调用 `trace.emit` 后出现）
+- `tracepoint`（调用 `trace_emit` 后出现）
 
 你也可以用内置 CLI 验证：
 
@@ -82,15 +82,15 @@ node dist/src/cli.js analyze ./trace.ndjson
 ## 4. 在 Agent/Skill 中使用打点工具
 
 ```json
-{ "tool": "trace.emit", "args": { "name": "agent.plan.generated", "level": "info" } }
+{ "tool": "trace_emit", "args": { "name": "agent.plan.generated", "level": "info" } }
 ```
 
 ```json
-{ "tool": "trace.span", "args": { "op": "start", "name": "ipd.phase.spec" } }
+{ "tool": "trace_span", "args": { "op": "start", "name": "ipd.phase.spec" } }
 ```
 
 ```json
-{ "tool": "trace.counter", "args": { "name": "token.estimate", "value": 128 } }
+{ "tool": "trace_counter", "args": { "name": "token.estimate", "value": 128 } }
 ```
 
 ## 5. 导出与分析
@@ -119,5 +119,5 @@ node dist/src/cli.js export ./trace.ndjson --out ./trace.csv --format csv
   - 检查 runtime 是否正确触发了 `onToolEnd`
   - 检查 `toolCallId` 是否在 start/end 事件里一致
 
-- `trace.emit` 不可用：
+- `trace_emit` 不可用：
   - 检查 `tools: tracekit.tools` 是否传入 runtime

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-tracekit",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "description": "Tracepoint and tracing plugin for OpenCode (agent/skill/tool spans, emit/export/analyze).",
   "license": "MIT",
   "type": "module",