opencode-metrics-plugin-lite

opencode 会话指标插件（轻量版）：挂上即自动记录每个会话的完整指标（tokens / rounds / steps 全文 / 子代理 / 工具调用 / hvigor 构建统计）到快照 JSON。零数据库、零配置。

• 开箱即用：宿主只需在 opencode.json 加一行，无需任何配置
• 实时落盘：会话进行中每 2s 增量写盘，中途退出不丢数据
• 快照就近同步（默认关闭）：开启后每次落盘把会话快照 <sessionId>.json 同步拷贝到会话工作目录的上一级（产物层），便于就地查看（syncSnapshotToWorkspace: true 开启）
• 独立配置文件：.opencode/opencode-metrics.json(.jsonc) 支持注释，存在即完全接管内联配置；用户目录 ~/.config/opencode/ 可放全局兜底配置
• 本地优先：不执行 clean、不上传、零网络

快速开始

第 1 步：注册插件

宿主项目 opencode.json：

{ "plugin": ["opencode-metrics-plugin-lite"] }

仅此一步即完成指标采集。

第 2 步（可选）：独立配置文件

在项目 .opencode/ 目录下创建 opencode-metrics.json 或 opencode-metrics.jsonc（支持注释与尾逗号）。文件存在时完全接管内联第二参：

// .opencode/opencode-metrics.jsonc —— 只记录指定 agent 示例
{
  "agents": ["build", "android-to-hmos-*"]
}

第 3 步（可选）：验证

会话进行几轮后，查看输出目录（见下）出现 <sessionId>.json 与 events/<sessionId>.log。

采集内容

每个会话一个 <sessionId>.json 快照（MetricsOutput 结构）：

| 字段 | 内容 | |---|---| | header | sessionId / 工作目录 / agent / model 及切换分布 | | taskDuration / taskRatio / hangMs | 实际任务执行时长（Σ步窗口 − 悬挂超额）、占比、悬挂超额单列 | | systemPrompts | 各模型 system prompt（子代理跳过） | | rounds[] / waitBreakdown | 每轮 duration、首 token 延迟、tokens、工具调用数、用户消息；轮口径等待明细 | | steps[] | 每步全文（text / reasoning）、tokens、cost、工具明细、结束原因 finish（空串 = 被取消） | | subagents[] | 子代理（task/explore 等）steps、tokens、工具统计，自动并入父会话 | | permissions[] | 权限申请审计：类型 / 目标 / 触发工具 / 审批结论 / 等待时长 | | droid2hmosCalls[] | droid2hmos 调用结构化结果：status / retry.kind / summary / 证据路径 | | failures[] | 失败汇总：tool-error / droid2hmos-failed / step-aborted | | codeStats | 代码行统计——鸿蒙五维（etsLines / tsLines / jsLines / cLines / cppLines，业务总量 businessCodeLines）与安卓三维（android.kotlinLines / javaLines / xmlLines），两侧测试代码与构建配置不计；另含 hvigorw 构建统计（错误码 / 警告 / 模块耗时 / 修复周期） | | planning | todowrite 规划统计 |

输出目录

默认按 env-paths 规范落在用户目录（可用 dirs 自定义）：

| 平台 | 路径 | |---|---| | Windows | %LOCALAPPDATA%\opencode-metrics-plugin\Log\{metrics,events}、...\Log\log\plugin\YYYYMMDD.log（运行日志按日期归档，保留 30 天） | | Linux | ~/.local/state/opencode-metrics-plugin/{metrics,events} | | macOS | ~/Library/Logs/opencode-metrics-plugin/{metrics,events} |

升级与排障

• 升级不生效：opencode 将插件缓存在本机且不自动更新，升级后须删缓存再重启——Windows %USERPROFILE%\.cache\opencode\packages\ 下的 opencode-metrics-plugin* 目录，macOS ~/Library/Caches/opencode/packages/ 下同名目录。
• 验证插件已加载：插件日志（log/plugin/YYYYMMDD.log）首屏出现 [MetricsPlugin] started 行。

配置项速查

全部可选；独立文件与内联第二参字段相同。

| 选项 | 类型 | 默认 | 说明 | |---|---|---|---| | enabled | boolean | true | 总开关，false 时不记录任何会话 | | agents | string[] | — | 会话 agent 白名单（* 通配，如 ["android-to-hmos-*", "build"]）：根会话 agent 命中才记录，子会话随父判定；中途切进白名单也会从命中点起记录（命中即终判，切出仍记录）；缺省全记 | | eventLogging | boolean | true | 原始事件写盘；关闭后快照仍生成，但 steps[].text/reasoning 为空 | | checkpointFlushIntervalMs | number | 2000 | 实时落盘冷却窗口（ms），0 关闭退回只在会话空闲时落盘 | | syncSnapshotToWorkspace | boolean | false | 每次落盘把会话快照 <sessionId>.json 同步拷贝到会话工作目录上一级（产物层）；true 开启 | | dirs | object | env-paths | metricsDir / eventsDir / logFile（基准，实际写 <所在目录>/log/plugin/YYYYMMDD.log） |

可编程 API

import { createMetricsRuntime } from 'opencode-metrics-plugin-lite/api'

const rt = createMetricsRuntime({
  dirs: { metricsDir: '/data/metrics', eventsDir: '/data/events' },
  onFlush: (sessionId, snapshot) => save(snapshot),
})

// 自托管事件源（非 opencode 插件场景）
rt.event({ event: { type: 'message.part.updated', properties: { ... } } })

// 结束时兜底
rt.eventLogger?.dispose()
rt.engine.dispose()

更低层可用 createMetricsEngine（无事件日志，仅指标累计）。

开发

npm run typecheck   # tsc --noEmit
npm test            # 冒烟测试（example/smoke.mts）
npm run build       # 清空 dist 后 tsc

License

MIT