opencode-metrics-plugin 0.1.5 → 0.2.0

package/README.md

@@ -1,390 +1,108 @@
-# opencode-metrics-plugin
-
-**opencode 会话实时统计插件**（通用核心，发布于公共 npm）。
-
-- **实时事件 → SessionMetrics 快照**：订阅 opencode 事件流（`session.*` / `message.*` / `part.*`），累加每会话状态，每轮 `session.idle` 产出完整快照 JSON（多轮增量 merge）
-- **摘要/详情双表（全局 summary.db）**：本机多宿主共享一个 sqlite 双表库（表结构与 tnnotix 既有库一致，显示字段不变）；live 与回填同拍写入，查询一处获得全部宿主会话
-- **统计范围可控**（默认不采）：支持 宿主声明 / agent 白名单 / 工作目录前缀 / 全量 四种策略
-- **多引擎目录隔离**：快照 JSON 目录为引擎实例属性，同进程多个宿主插件各写各的，互不覆盖
-- **历史回填**：从 opencode.db 重建历史会话快照，按归属规则路由到各引擎目录（CLI 全量 + 启动增量），摘要同样入全局库
-- **无 UI、无编译专属依赖**（HarmonyOS 的 hvigor/ets 统计逻辑一并保留为可选路径，非 HarmonyOS 会话为空）
-
-## 总览
-
-```
-opencode 事件流（广播给所有已加载插件）
-        │  宿主 event hook → runtime.event({ event })
-        ▼
-  ┌─ 引擎（scope 门控）─────────────── 实时累计 ──────────────────┐
-  │                                                              │
-  │  每轮 session.idle / flush / dispose                          │
-  │        │                                                     │
-  │        ├─→ 各宿主 <metricsDir>\<sessionId>.json（快照文件，    │
-  │        │        按宿主隔离——多写者会冲突，必须分目录）          │
-  │        ├─→ 全局 summary.db 双表（force，与文件同拍）            │
-  │        │      session_summaries（摘要索引行，多宿主聚合）       │
-  │        │      session_details（full_data = 快照原文）          │
-  │        └─→ onFlush(sessionId, snapshot)     宿主自定义消费     │
-  │                                                              │
-  │  events\<sessionId>.log（原始事件流，仅 scope 内会话）          │
-  └──────────────────────────────────────────────────────────────┘
-  backfillFromOpencode（opencode.db 历史重建，soft 入全局库，live 永远赢）
-        │
-        ▼
-  查询：querySummaries / getDetail / getSubagentSteps / getSessionRaw
-        （缺省即查全局库 → 一次获得所有宿主的会话列表）
-```
-
-
-## 安装
-
-公共包，直接安装，无需任何 registry / token 配置：
-
-```bash
-npm install opencode-metrics-plugin
-```
-
-> 从旧 `@dear-xml` 私有包迁移的用户：**全局数据目录不变**——快照/摘要库仍落
-> `%LOCALAPPDATA%/opencode-metrics-plugin/Log/`（`defaultDirs` 的 appName
-> 默认值与包名解耦，已聚合的数据不受迁移/升级影响）。
-
-## 快速开始
-
-```ts
-import { createMetricsRuntime } from 'opencode-metrics-plugin'
-
-// 场景 A：全局记录（宿主指定目录，scope=all 记录一切会话）
-const rt = createMetricsRuntime({
-  dirs: { metricsDir: '/data/agent-metrics', eventsDir: '/data/agent-events' },
-  scope: { mode: 'all' },
-  backfillOnStart: true,   // 可选：启动时增量补齐插件未运行期间的会话
-})
-// 在宿主插件 hooks.event 里调用（注意包一层 { event }）：
-//   async ({ event }) => rt.event({ event })
-
-// 场景 B：按工作目录前缀统计
-const rt2 = createMetricsRuntime({ scope: { mode: 'cwd', cwdPrefixes: ['/srv/frontend'] } })
-
-// 场景 C：宿主声明模式——默认不采，宿主在目标会话创建时 claim
-const rt3 = createMetricsRuntime({ scope: { mode: 'declared' } })
-rt3.engine.claimSession(sessionId, { agent: 'my-plugin-agent' })
-```
-
-## 策略
-
-| mode | 行为 |
-|---|---|
-| `all` | 统计所有会话（可加 `agents` 只统计白名单 agent） |
-| `none` | 默认不统计；`claimSession` 的会话才统计 |
-| `declared` | 仅宿主 `claimSession`（或 `agents` 命中） |
-| `cwd` | 仅工作目录命中 `cwdPrefixes` 的会话 |
-
-子代理（opencode 以 `parentID` 标识）自动随其父会话纳入，不单独计为独立会话。
-
-## 历史回填（backfill）
-
-从 `~/.local/share/opencode/opencode.db` 重建历史会话快照，按归属规则路由写入各引擎目录。
-归属判定链：`session.agent` 列 →（null 时）首条含 agent 的 message → 引擎规则（`agents` / `cwdPrefixes`）→ 兜底目录。
-空会话（无消息）跳过；快照带 `source: "backfill"` 字段与 live 区分；已有 live 快照不覆盖。
-
-```ts
-import { backfillFromOpencode } from 'opencode-metrics-plugin'
-
-const result = await backfillFromOpencode({
-  dbPath: '可选，默认 ~/.local/share/opencode/opencode.db',
-  engines: [
-    // summaryFile 可选：缺省写全局共享库（与 live 同库）；显式指定可路由到隔离库
-    { label: 'harmony-code', metricsDir: '.../hm-plugin-nodejs/Log/metrics', agents: ['harmonyos-plugin'] },
-    { label: 'tnnotix', metricsDir: '.../plugin-b/Log/metrics', agents: ['harmonyos-ascf'] },
-  ],
-  fallback: { metricsDir: '.../default/Log/metrics' },   // 无人认领的会话
-  filter: { agents: ['harmonyos-convert'] },             // 只回填指定插件/agent 的会话
-  skipExisting: true,                                    // live 优先（默认 true）
-  incremental: false,                                    // true=按各目录 .backfill-state 水位增量
-  dryRun: false,                                         // true=只统计不写盘
-  onSessionBackfilled: (sessionId, label, metricsDir) => {},  // 单会话完成回调
-})
-// result: { perEngine: [{label, metricsDir, written, skippedExisting, skippedEmpty}],
-//           fallback: 同上 | null, skippedByFilter, unattributed, total }
-```
-
-### 触发时机
-
-- **CLI 全量**：`node dist/backfill-cli.js --config engines.json [--agent <name>] [--since <ms|ISO>] [--dry-run] [--db <path>]`
-  配置文件（JSON，支持 `//` 注释）：`{ "dbPath"?, "engines": [{ "label", "metricsDir", "agents"?, "cwdPrefixes"?, "summaryFile"? }], "fallback"?, "filter"? }`（summaryFile 缺省 = 全局共享库，与 live 同库）
-- **启动增量**：`createMetricsRuntime({ backfillOnStart: true, ... })`，各引擎目录 `.backfill-state` 水位记录进度，插件加载时自动补齐"插件未运行期间"的本引擎会话（仅当 scope 可静态判定：`mode: all` 或配置了 `agents`/`cwdPrefixes` 时生效）
-
-### 保真度
-
-| 指标 | 回填可重建 |
-|---|---|
-| tokens / cacheHitRate / 轮次 / 时长 / 工具分布 / steps / skills / 子代理 | 完整 |
-| 代码编译统计（hvigor）/ anomaly / compaction 细节 | 置零或缺省 |
-
-## 摘要/详情双表（summary.db）
-
-插件在快照文件之外自动维护一个 sqlite 摘要库：**缺省为全局共享路径**（`%LOCALAPPDATA%/opencode-metrics-plugin/Log/summary.db`，不随 metricsDir 派生——本机多宿主自动聚合到同一个库）；需要隔离时经 `dirs.summaryFile` 精确指定。表结构与 tnnotix 既有库完全一致（显示字段不变）：
-
-- `session_summaries`：`session_id / task_id / agent / model / directory / title / first_user_message / step_count / tool_calls / total_tokens_{input,output,cache_read,cache_write,reasoning} / total_tokens / duration / created_at / source_file / ingested_at`（索引：`created_at` / `task_id` / `model`）
-- `session_details`：`session_id / full_data`（完整快照 JSON 原文）
-
-写入时机：
-
-| 时机 | 模式 | 说明 |
-|---|---|---|
-| live flush（每轮 `session.idle`） | force | 双表与快照文件同拍最新；进行中会话每轮自动刷新，首轮结束即可查到 |
-| `backfillFromOpencode` | soft | 已有 `total_tokens > 0` 的行不覆盖，live 永远赢 |
-| `reindexDir(metricsDir)` | soft + prune | 扫描存量 JSON 重建；`prune: true` 清理文件已删的孤儿行 |
-
-> 依赖 `node:sqlite`（Node >= 22.5）。不可用时实时统计与快照文件照常工作，仅摘要库停用（进程内只告警一次）。
-
-## API 使用指导
-
-### createMetricsRuntime —— 一体封装（推荐入口）
-
-目录 + 事件日志 + 引擎 + 可选启动回填的一体组装，宿主通常只需这一个函数。
-
-```ts
-import { createMetricsRuntime } from 'opencode-metrics-plugin'
-
-const rt = createMetricsRuntime({
-  enabled: true,                    // 总开关（默认 true）
-  scope: { mode: 'all' },           // 统计范围（见「策略」）
-  dirs: {                           // 可选，实例目录（三层解析）
-    metricsDir: '...', eventsDir: '...', logFile: '...', summaryFile: '...',
-  },
-  onFlush: (sessionId, snapshot) => {
-    // 每轮 flush 后回调（snapshot 为本轮快照；宿主可在此上报自有系统）
-  },
-  eventLogging: true,               // 是否写 events/<id>.log（默认 true），与引擎共用 scope 门控
-  backfillOnStart: true,            // 启动增量回填（见上）
-})
-
-rt.event({ event })                 // 挂到宿主 hooks.event：async ({ event }) => rt.event({ event })
-rt.engine                           // 底层引擎（claimSession / flush / dispose ...）
-rt.eventLogger                      // 事件记录器（null 当 eventLogging:false）
-rt.dirs                             // 解析后的完整目录集（含派生的 summaryFile）
-rt.eventLogger?.flush()             // 退出前手动刷事件日志缓冲
-rt.engine.dispose()                 // 退出前兜底刷所有未落盘会话（快照+双表）
-```
-
-### createMetricsEngine —— 手动组装引擎
-
-需要自己控制事件日志/生命周期时使用（harmony-code 即此方式）。
-
-```ts
-import { createMetricsEngine } from 'opencode-metrics-plugin'
-
-const engine = createMetricsEngine({
-  enabled: true,
-  scope: { mode: 'all', agents: ['harmonyos-plugin'] },
-  dirs: { metricsDir: '...', eventsDir: '...' },   // 构造时三层解析并固化；缺省回退进程级默认
-  onFlush: (sessionId, snapshot) => {},
-})
-// 兼容旧布尔入参：createMetricsEngine(true) === scope all；false === none
-
-engine.ingest(event)                          // 喂事件：{ type, properties }
-engine.ingestPrompt(sessionId, modelId, system)  // 喂 system prompt（string[]）
-engine.claimSession(sessionId, { agent })     // declared/none 模式下显式纳入某会话
-engine.scopeOf(sessionId)                     // 查询会话是否在统计范围
-engine.shouldTrack(sessionId, type, props)    // 归属判定（供 event-logger 等共用同一门控）
-engine.isSubAgent(sessionId)                  // 是否子代理会话
-engine.flush(sessionId)                       // 手动触发单会话落盘（快照文件 + summary.db）
-engine.dispose()                              // 兜底刷全部未落盘会话并清空状态
-```
-
-### createEventLogger —— 原始事件流记录
-
-```ts
-import { createEventLogger } from 'opencode-metrics-plugin'
-
-const logger = createEventLogger(true, false, {
-  eventsDir: '.../events',                    // 实例目录；缺省回退进程级默认
-  isTracked: (sessionId, event) => engine.shouldTrack(sessionId, event.type, event.properties),
-  // 与引擎共用同一 scope 判定：引擎不统计的会话不写事件日志
-})
-
-logger.log(event)                // 喂事件（子代理事件自动并入父日志）
-logger.logPrompt(sessionId, type, content)
-logger.isSubAgent(sessionId)
-logger.flush()                   // 刷缓冲到磁盘
-logger.dispose()
-```
-
-### backfillFromOpencode —— 历史回填
-
-见「历史回填」章节完整示例与选项说明。
-
-### querySummaries / countSummaries —— 摘要筛选（列表数据源）
-
-```ts
-import { querySummaries, countSummaries } from 'opencode-metrics-plugin'
-
-const rows = querySummaries(
-  {
-    agent: 'harmonyos-plugin',             // 单值精确；多值用 agents: [...]
-    agents: ['harmonyos-plugin', 'harmonyos-convert'],
-    taskId: 'task_42',                     // 任务分组（先经 setSessionTaskId 标记）
-    directoryPrefix: 'D:/company/app2hm',  // 反斜杠/大小写自动归一
-    model: 'glm-4.6',
-    sessionIds: ['ses_a', 'ses_b'],        // 会话 id 名单（按集合聚合汇总用）
-    since: '2026-01-01',                   // created_at 下界（ISO 或毫秒时间戳）
-    until: Date.now(),                     // 上界
-    limit: 20,
-    offset: 0,
-  },
-  { metricsDir: '.../Log/metrics' },       // 可选：指定实例目录（缺省走三层解析）
-)
-// rows: SessionSummary[]（created_at 倒序）—— id / taskId / agent / model / directory / title /
-//   stepCount / toolCalls / totalTokens{input,output,cacheRead,cacheWrite,reasoning,total} /
-//   duration / createdAt / firstUserMessage / filePath ...
-
-const total = countSummaries({ agent: 'harmonyos-plugin' }, { metricsDir: '.../Log/metrics' })
-// 同条件总数，配合 limit/offset 做分页
-```
-
-### getDetail —— 单会话详情（详情页数据源）
-
-```ts
-import { getDetail } from 'opencode-metrics-plugin'
-
-const detail = getDetail('ses_xxx', { metricsDir: '.../Log/metrics' })
-// detail: SessionDetail —— steps / rounds / tools / codeStats / planning / skills /
-//   systemPrompts；子代理默认摘要化（steps 剥离为 stepCount，载荷更轻）
-
-const full = getDetail('ses_xxx', { metricsDir: '.../Log/metrics' }, { fullSubagents: true })
-// fullSubagents: true 保留完整子代理 steps（需直接渲染子代理树的宿主用）
-```
-
-数据源优先级：`session_details.full_data` → 快照文件回退；返回 `null` 表示会话不存在。
-
-### getSubagentSteps —— 子代理 steps 懒加载
-
-```ts
-const steps = getSubagentSteps('ses_xxx', 0, { metricsDir: '.../Log/metrics' })
-// StepData[] | null：DB full_data → 文件回退；配合 getDetail 摘要化模式按需取
-```
-
-### getSessionRaw —— 原始快照 JSON（下载能力）
-
-```ts
-const rawJson = getSessionRaw('ses_xxx', { metricsDir: '.../Log/metrics' })
-// string | null：快照文件优先 → DB full_data 回退
-```
-
-### setSessionTaskId —— 任务分组标记
-
-```ts
-setSessionTaskId('ses_xxx', 'task_42', { metricsDir: '.../Log/metrics' })
-// boolean：是否命中行（false = 摘要库中无该会话）；taskId 传 null 可清除分组
-const group = querySummaries({ taskId: 'task_42' }, { metricsDir: '.../Log/metrics' })
-```
-
-### removeSession —— 删除会话行（宿主删除链路）
-
-```ts
-const { deleted, sourceFile } = removeSession('ses_xxx', { metricsDir: '.../Log/metrics' })
-// 事务内删双表行；sourceFile 为被删行的 source_file，供宿主继续清理快照文件/事件日志
-// 行不存在或库不可用时 deleted=false（幂等，可安全重试）
-```
-
-### reindexDir —— 存量重建 + 孤儿清理
-
-```ts
-const { scanned, upserted, pruned } = reindexDir('.../Log/metrics', {
-  summaryFile: '可选，缺省全局共享库',
-  prune: true,     // 清理 source_file 已不存在于磁盘的孤儿行（双表同删）
-})
-```
-
-典型场景：
-- 升级接入后把历史快照文件一次性登记进摘要库
-- 删除文件后清理双表孤儿行——注意共享库语义下 prune 清理的是**全库**孤儿（含其他宿主目录已消失的快照），属预期行为
-
-### upsertSessionSnapshot —— 手动入库（自定义数据源）
-
-```ts
-upsertSessionSnapshot(summaryFile, snapshot, filePath, 'force')
-// summaryFile: 库路径；snapshot: MetricsOutput；filePath: 记入 source_file 的快照路径
-// 'force' 总是刷新（live 语义）；'soft' 不覆盖已有 total_tokens>0 的行（backfill 语义）
-```
-
-宿主从自有管道拿到快照对象时可直接入库；返回 boolean 表示是否成功。
-
-### 目录 API
-
-```ts
-import { defaultDirs, configureDirs, getDirs, resolveDirs, getSummaryFile } from 'opencode-metrics-plugin'
-
-defaultDirs('my-app')   // 兜底目录集：envPaths('my-app').log 下 metrics/ events/ plugin.log summary.db
-                        // 不传应用名则为 'opencode-metrics-plugin'（本包默认，即全局共享库所在）
-configureDirs({ summaryFile: '...' })   // 只改摘要库落点（进程级）；其余保持默认
-configureDirs({ metricsDir: '...' })    // 改快照目录不影响 summaryFile（仍为全局库，除非显式配置）
-getDirs()               // 当前进程级默认（defaultDirs + configureDirs 合并结果）
-resolveDirs(partial)    // 三层合并：defaultDirs → configureDirs → partial；summaryFile 显式值优先，缺省全局
-getSummaryFile()        // 进程级默认摘要库路径
-```
-
-落点语义（关键）：
-```
-宿主传了 metricsDir='.../hm-plugin/Log/metrics' 时：
-  .../hm-plugin/Log/metrics/<sessionId>.json     ← 快照按宿主隔离
-  %LOCALAPPDATA%/opencode-metrics-plugin/Log/
-    ├── summary.db                                ← 摘要库恒为全局（缺省），多宿主聚合
-    └── metrics/ events/ plugin.log               ← 仅当宿主连 metricsDir 也没配时的兜底
-```
-
-### 辅助函数
-
-```ts
-import {
-  extractSummaryFields,   // (snapshot, filePath) → SummaryFields：快照→摘要列提取（入库同口径）
-  snapshotToSummary,     // (snapshot, filePath?) → SessionSummary：快照→列表摘要（含 main/subagent tokens 拆分）
-  detailFromRaw,         // (raw, { keepSubagentSteps? }) → SessionDetail：快照→详情（默认子代理摘要化）
-  detailFullFromRaw,     // (raw) → SessionDetail：保留完整子代理 steps 的详情
-  sumTokens,             // (TokenUsage[]) → TokenUsage：逐元素累加
-  subtractTokens,        // (a, b) → TokenUsage：相减（剥离子代理 token）
-  toIsoString,           // (string|number|Date) → ISO 字符串 | null
-  firstUserMessageOf,    // (rounds) → string | undefined：首条用户消息（兼容 string/string[]）
-  openSummaryDb,         // (file) → DatabaseSync | null：打开/复用摘要库连接（WAL + 幂等建表）
-  closeSummaryDbs,       // () => void：关闭全部缓存连接（宿主删除目录前调用，避免 Windows 句柄占用）
-} from 'opencode-metrics-plugin'
-```
-
-## 类型导出
-
-- 快照/状态：`MetricsOutput` / `SessionMetrics*` / `TokenUsage` / `StepData` / `RoundSnapshot` / `SubAgentOutput` / `PlanningMetrics` / `SessionMeta`
-- 查询：`SessionSummary` / `SessionDetail` / `SubagentView` / `SummaryFilter` / `SummaryFields` / `ReindexResult` / `UpsertMode` / `RemoveSessionResult`
-- 回填：`BackfillOptions` / `BackfillEngineRule` / `BackfillFilter` / `BackfillResult` / `BackfillEngineStat` / `BackfillMetricsOutput`
-- 目录：`MetricsDirs`；引擎：`MetricsEngineOptions` / `MetricsScope` / `MetricsScopeMode` / `MetricsEngine`；事件：`EventLogger` / `EventLoggerOptions`；运行时：`MetricsRuntime` / `MetricsRuntimeOptions`
-
-> 回填与摘要库功能依赖 `node:sqlite`（Node >= 22.5）；实时统计与快照文件核心无此要求。
-
-## 构建/发布
-
-```bash
-npm install
-npm run build        # tsc → dist/
-npm test             # example/smoke.mts（tsx，53 断言）
-npm pack             # 本地发包前检查
-npm publish          # 发布到 npm registry
-```
-
-## 目录结构
-
-```
-src/
-├── index.ts            createMetricsRuntime / 查询 API / 全部类型导出
-├── metrics-engine.ts   createMetricsEngine（策略 + claimSession + onFlush + 实例目录）
-├── metrics-types.ts    状态/快照类型（MetricsOutput/SessionMetrics*）
-├── metrics-handlers.ts 事件→状态 累加
-├── metrics-output.ts   flush 组装快照 + 写盘 + 双表 force 入库（返回快照供 onFlush）
-├── metrics-steps.ts    步骤内容回填（读 events 日志，实例目录）
-├── event-logger.ts     events/<sessionId>.log 记录/轮转（实例目录 + isTracked 门控）
-├── compile-analyzer.ts hvigor 输出解析（可选，非编译会话为空）
-├── backfill.ts         opencode.db 历史回填（归属路由 + 水位 + source 标记 + 双表 soft 入库）
-├── backfill-cli.ts     回填命令行入口
-├── summary-store.ts    摘要/详情双表（summary.db）+ 全部查询 API + reindex
-├── dirs.ts             目录参数化（defaultDirs/configureDirs/getDirs/resolveDirs/summaryFile 派生）
-└── logger.ts           运行日志（文件 + console 回退）
-```
+# opencode-metrics-plugin
+
+**opencode 会话指标插件**：挂上即自动记录每个会话的完整指标（tokens / rounds / steps 全文 / 子代理 / 工具调用 / hvigor 构建统计），每轮对话结束落盘一个快照 JSON。
+
+- **开箱即用**：宿主只需在 `opencode.json` 加一行，无需任何配置
+- **全量记录**：集成时刻起的所有会话（含子代理会话，自动并入父会话）
+- **增量 merge**：同会话多轮持续追加，进程重启后 rounds/steps 不丢
+- **dispose 兜底**：未走 `session.idle` 的会话在插件卸载时也会落盘
+- **可编程 API**：`createMetricsEngine` / `createMetricsRuntime` 可脱离插件契约单独使用
+
+## 总览
+
+```
+opencode 事件流
+        │  plugin event hook
+        ▼
+  ┌─ runtime（事件记录 + 指标引擎）────────────────────────────┐
+  │  events\<sessionId>.log     原始事件流（steps 全文数据源）   │
+  │                                                             │
+  │  每轮 session.idle / dispose 兜底                            │
+  │        ├─→ <metricsDir>\<sessionId>.json（快照，增量 merge） │
+  │        └─→ onFlush(sessionId, snapshot)（宿主自定义消费）    │
+  └─────────────────────────────────────────────────────────────┘
+        │
+        ▼
+  session-viewer 扫描 metricsDir 解析展示（完全解耦）
+```
+
+## 快速开始
+
+宿主项目 `opencode.json`：
+
+```jsonc
+// 最简
+{ "plugin": ["opencode-metrics-plugin"] }
+
+// 带配置
+{
+  "plugin": [
+    ["opencode-metrics-plugin", { "enabled": true, "eventLogging": true }]
+  ]
+}
+```
+
+配置项（全部可选）：
+
+| 选项 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `enabled` | `boolean` | `true` | 总开关，`false` 时不记录任何会话 |
+| `eventLogging` | `boolean` | `true` | 原始事件写盘（`events/<sessionId>.log`）；关闭后快照仍生成，但 `steps[].text/reasoning` 为空 |
+| `dirs` | `Partial<MetricsDirs>` | env-paths | 自定义 `metricsDir` / `eventsDir` / `logFile`（多实例同用时建议各传各的） |
+| `onFlush` | `(sessionId, snapshot) => void` | — | 快照落盘后回调（可在此上报自有系统） |
+
+## 输出
+
+默认目录（appName `opencode-metrics-plugin`，env-paths 规范）：
+
+| 平台 | 路径 |
+|---|---|
+| Windows | `%LOCALAPPDATA%\opencode-metrics-plugin\Log\metrics\`（events 同级） |
+| Linux | `~/.local/state/opencode-metrics-plugin/metrics/` |
+| macOS | `~/Library/Logs/opencode-metrics-plugin/metrics/` |
+
+每个会话一个 `<sessionId>.json`（`MetricsOutput` 结构），核心字段：
+
+- `header`：sessionId / 工作目录 / agent / model 及切换分布
+- `systemPrompts`：各模型 system prompt（经 `experimental.chat.system.transform` hook 记录，子代理跳过）
+- `rounds[]`：每轮 duration、首 token 延迟、tokens、工具调用数、用户消息文本
+- `steps[]`：每步全文（text / reasoning 来自事件日志）、tokens、cost、工具明细
+- `subagents[]`：子代理（task/explore 等）steps、tokens、工具统计
+- `codeStats`：hvigorw 构建统计（错误码 / 警告 / 模块耗时 / 修复周期；非 HarmonyOS 会话为空）
+- `planning`：todowrite 规划统计
+
+配套可视化：[session-viewer](../session-viewer) 扫描 metricsDir 直接解析展示，无需任何服务端支持。
+
+## 可编程 API
+
+```ts
+import { createMetricsRuntime, configureDirs } from 'opencode-metrics-plugin'
+
+const rt = createMetricsRuntime({
+  dirs: { metricsDir: '/data/metrics', eventsDir: '/data/events' },
+  onFlush: (sessionId, snapshot) => upload(snapshot),
+})
+
+// 自托管事件源（非 opencode 插件场景）
+rt.event({ event: { type: 'message.part.updated', properties: { ... } } })
+
+// 结束时兜底
+rt.eventLogger?.dispose()
+rt.engine.dispose()
+```
+
+更低层可用 `createMetricsEngine`（无事件日志，仅指标累计）。
+
+## 开发
+
+```bash
+npm run typecheck   # tsc --noEmit
+npm test            # 冒烟测试（example/smoke.mts，27 断言）
+npm run build       # 清空 dist 后 tsc
+```
+
+结构：`src/plugin.ts`（插件入口）→ `src/metrics/`（域：engine / snapshot / eventlog / analysis / runtime）→ `src/shared/log.ts`。`@opencode-ai/plugin` 仅作类型依赖（peer），运行时零依赖（除 env-paths）。
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -1,51 +1,5 @@
-import type { MetricsEngineOptions } from "./metrics-engine.js";
-import type { EventLoggerOptions } from "./event-logger.js";
-import type { MetricsDirs } from "./dirs.js";
-export { createMetricsEngine } from "./metrics-engine.js";
-export type { MetricsEngineOptions, MetricsScope, MetricsScopeMode, MetricsEngine } from "./metrics-engine.js";
-export { configureDirs, defaultDirs, getDirs, resolveDirs, getSummaryFile } from "./dirs.js";
-export type { MetricsDirs } from "./dirs.js";
-export { createEventLogger } from "./event-logger.js";
-export type { EventLogger, EventLoggerOptions } from "./event-logger.js";
-export { backfillFromOpencode } from "./backfill.js";
-export type { BackfillOptions, BackfillEngineRule, BackfillFilter, BackfillResult, BackfillEngineStat, BackfillMetricsOutput, } from "./backfill.js";
-export { querySummaries, countSummaries, getDetail, getSubagentSteps, getSessionRaw, setSessionTaskId, reindexDir, upsertSessionSnapshot, openSummaryDb, closeSummaryDbs, removeSession, extractSummaryFields, snapshotToSummary, detailFromRaw, detailFullFromRaw, sumTokens, subtractTokens, toIsoString, firstUserMessageOf, } from "./summary-store.js";
-export type { SummaryFilter, SessionSummary, SessionDetail, SubagentView, ReindexResult, UpsertMode, SummaryFields, RemoveSessionResult, } from "./summary-store.js";
-export type * from "./metrics-types.js";
-export interface MetricsRuntimeOptions extends Omit<MetricsEngineOptions, "enabled"> {
-    dirs?: Partial<MetricsDirs>;
-    enabled?: boolean;
-    /** 事件写盘（events/<sessionId>.log）；仅记录归属命中本引擎 scope 的会话 */
-    eventLogging?: boolean;
-    /** 事件记录器额外选项（如外部传入的 isTracked 门控，一般由 runtime 自动注入无需配置） */
-    eventLoggerOptions?: Omit<EventLoggerOptions, "eventsDir" | "isTracked">;
-    /**
-     * 启动时增量回填本引擎归属的历史会话（读 opencode.db，水位存于 metricsDir/.backfill-state.json）。
-     * 仅当 scope 可静态判定（mode all，或配置了 agents/cwdPrefixes）时生效，用于补齐"插件未运行期间"的间隙会话。
-     */
-    backfillOnStart?: boolean;
-}
-/**
- * 组装一整套"通用统计插件"的运行时：事件记录 + 指标引擎。
- * 目录为实例级（不产生全局副作用）：defaultDirs → 进程级默认（configureDirs）→ opts.dirs 三层合并。
- * 同一进程可创建多个 runtime（不同插件各配各目录），scope 门控同时作用于引擎计数与事件写盘。
- */
-export declare function createMetricsRuntime(opts?: MetricsRuntimeOptions): {
-    dirs: MetricsDirs;
-    eventLogger: import("./event-logger.js").EventLogger | null;
-    engine: import("./metrics-types.js").MetricsEngine & {
-        claimSession: (sessionId: string, meta?: {
-            agent?: string;
-        }) => void;
-        scopeOf: (sessionId: string) => boolean;
-        shouldTrack: (sessionId: string, eventType: string, props: Record<string, unknown> | undefined) => boolean;
-    };
-    /** opencode event hook：`async ({ event }) => { runtime.event({ event }) }` */
-    event(input: {
-        event: {
-            type: string;
-            properties?: Record<string, unknown>;
-        };
-    }): void;
-};
-export type MetricsRuntime = ReturnType<typeof createMetricsRuntime>;
+export { MetricsPlugin, default } from './plugin.js';
+export type { MetricsPluginOptions } from './plugin.js';
+export * from './metrics/index.js';
+export { setLogLevel, setLogFile, flushLogs } from './shared/log.js';
+export type { LogLevel } from './shared/log.js';

package/dist/index.js

@@ -1,61 +1,5 @@
-import { createMetricsEngine } from "./metrics-engine.js";
-import { createEventLogger } from "./event-logger.js";
-import { resolveDirs } from "./dirs.js";
-import { backfillFromOpencode } from "./backfill.js";
-export { createMetricsEngine } from "./metrics-engine.js";
-export { configureDirs, defaultDirs, getDirs, resolveDirs, getSummaryFile } from "./dirs.js";
-export { createEventLogger } from "./event-logger.js";
-export { backfillFromOpencode } from "./backfill.js";
-export { querySummaries, countSummaries, getDetail, getSubagentSteps, getSessionRaw, setSessionTaskId, reindexDir, upsertSessionSnapshot, openSummaryDb, closeSummaryDbs, removeSession, extractSummaryFields, snapshotToSummary, detailFromRaw, detailFullFromRaw, sumTokens, subtractTokens, toIsoString, firstUserMessageOf, } from "./summary-store.js";
-/**
- * 组装一整套"通用统计插件"的运行时：事件记录 + 指标引擎。
- * 目录为实例级（不产生全局副作用）：defaultDirs → 进程级默认（configureDirs）→ opts.dirs 三层合并。
- * 同一进程可创建多个 runtime（不同插件各配各目录），scope 门控同时作用于引擎计数与事件写盘。
- */
-export function createMetricsRuntime(opts = {}) {
-    const dirs = resolveDirs(opts.dirs);
-    const engine = createMetricsEngine({
-        enabled: opts.enabled,
-        scope: opts.scope,
-        dirs,
-        onFlush: opts.onFlush,
-    });
-    const eventLogger = (opts.eventLogging ?? true)
-        ? createEventLogger(true, false, {
-            eventsDir: dirs.eventsDir,
-            // 事件记录与引擎共用同一归属判定：引擎不统计的会话不写事件日志
-            isTracked: (sessionId, event) => engine.shouldTrack(sessionId, event.type, event.properties),
-        })
-        : null;
-    if (opts.backfillOnStart) {
-        const scope = opts.scope ?? { mode: "all" };
-        const staticallyAttributable = scope.mode === "all" || (scope.agents?.length ?? 0) > 0 || (scope.cwdPrefixes?.length ?? 0) > 0;
-        if (staticallyAttributable) {
-            setImmediate(() => {
-                backfillFromOpencode({
-                    engines: [{
-                            label: "self",
-                            metricsDir: dirs.metricsDir,
-                            agents: scope.agents,
-                            cwdPrefixes: scope.cwdPrefixes,
-                            summaryFile: dirs.summaryFile, // 与 live flush 同库（缺省全局共享库）
-                        }],
-                    skipExisting: true,
-                    incremental: true,
-                }).catch((err) => {
-                    console.error("[opencode-metrics-plugin] 启动增量回填失败:", err);
-                });
-            });
-        }
-    }
-    return {
-        dirs,
-        eventLogger,
-        engine,
-        /** opencode event hook：`async ({ event }) => { runtime.event({ event }) }` */
-        event(input) {
-            eventLogger?.log(input.event);
-            engine.ingest(input.event);
-        },
-    };
-}
+// opencode-metrics-plugin 包出口
+// 默认导出即 opencode 插件入口（dist/index.js）；metrics 域与 shared/log 为可编程 API
+export { MetricsPlugin, default } from './plugin.js';
+export * from './metrics/index.js';
+export { setLogLevel, setLogFile, flushLogs } from './shared/log.js';