opencode-metrics-plugin 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dear-xml
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,390 @@
+# 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 回退）
+```

package/dist/backfill-cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/backfill-cli.js

@@ -0,0 +1,74 @@
+import * as fs from "fs";
+import * as path from "path";
+import { backfillFromOpencode } from "./backfill.js";
+function loadConfig(configPath) {
+    let raw = fs.readFileSync(configPath, "utf-8");
+    // 容忍 // 行注释与尾逗号外的常见 jsonc 写法（去掉整行注释）
+    raw = raw
+        .split("\n")
+        .map((l) => l.replace(/^\s*\/\/.*$/, ""))
+        .join("\n");
+    const cfg = JSON.parse(raw);
+    if (!Array.isArray(cfg.engines) || cfg.engines.length === 0) {
+        throw new Error("配置文件缺少 engines 数组");
+    }
+    return cfg;
+}
+function parseArgs(argv) {
+    const out = { agents: [], dryRun: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--config")
+            out.config = argv[++i];
+        else if (a === "--agent")
+            out.agents.push(argv[++i]);
+        else if (a === "--since") {
+            const v = argv[++i];
+            const n = Number(v);
+            out.since = Number.isFinite(n) && v.trim() !== "" ? n : Date.parse(v);
+        }
+        else if (a === "--dry-run")
+            out.dryRun = true;
+        else if (a === "--db")
+            out.dbPath = argv[++i];
+        else if (a === "--help" || a === "-h") {
+            console.log("用法: node dist/backfill-cli.js --config <engines.json> [--agent <name>...] [--since <ms|ISO>] [--db <path>] [--dry-run]");
+            process.exit(0);
+        }
+    }
+    return out;
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (!args.config) {
+        console.error("必须指定 --config <engines.json>");
+        process.exit(1);
+    }
+    const cfg = loadConfig(path.resolve(args.config));
+    const filter = { ...(cfg.filter ?? {}) };
+    if (args.agents.length > 0)
+        filter.agents = args.agents;
+    if (typeof args.since === "number" && Number.isFinite(args.since))
+        filter.since = args.since;
+    const opts = {
+        dbPath: args.dbPath ?? cfg.dbPath,
+        engines: cfg.engines,
+        fallback: cfg.fallback,
+        filter,
+        skipExisting: true,
+        dryRun: args.dryRun,
+    };
+    console.log(`回填开始: db=${opts.dbPath ?? "默认"} 引擎数=${opts.engines.length}${opts.dryRun ? " [dry-run]" : ""}`);
+    const result = await backfillFromOpencode(opts);
+    for (const s of result.perEngine) {
+        console.log(`  [${s.label}] ${s.metricsDir} → 写入 ${s.written} | 已有跳过 ${s.skippedExisting} | 空会话 ${s.skippedEmpty}`);
+    }
+    if (result.fallback) {
+        console.log(`  [fallback] ${result.fallback.metricsDir} → 写入 ${result.fallback.written} | 已有跳过 ${result.fallback.skippedExisting} | 空会话 ${result.fallback.skippedEmpty}`);
+    }
+    console.log(`  过滤跳过 ${result.skippedByFilter} | 无人认领 ${result.unattributed} | 顶层会话总数 ${result.total}`);
+}
+main().catch((err) => {
+    console.error("回填失败:", err);
+    process.exit(1);
+});

package/dist/backfill.d.ts

@@ -0,0 +1,58 @@
+import type { MetricsOutput } from "./metrics-types.js";
+/** 引擎归属规则（与运行时 scope 同语义：agents 命中或 cwd 前缀命中即归属，首条命中优先） */
+export interface BackfillEngineRule {
+    label: string;
+    /** 该引擎快照写入目录（<sessionId>.json 落这里） */
+    metricsDir: string;
+    /** agent 名单（session.agent 列，缺失时回退首条含 agent 的 message） */
+    agents?: string[];
+    /** 工作目录前缀（与 session.directory 前缀匹配，斜杠/大小写不敏感） */
+    cwdPrefixes?: string[];
+    /** 摘要库落点；缺省写全局共享库（与 live flush 一致，多宿主聚合） */
+    summaryFile?: string;
+}
+/** 回填会话选择过滤器（在归属判定之前应用） */
+export interface BackfillFilter {
+    agents?: string[];
+    cwdPrefixes?: string[];
+    since?: number;
+    sessionIds?: string[];
+}
+export interface BackfillOptions {
+    /** opencode 数据库路径，默认 ~/.local/share/opencode/opencode.db */
+    dbPath?: string;
+    engines: BackfillEngineRule[];
+    /** 无人认领会话的兜底目录（不配则跳过不回填） */
+    fallback?: {
+        metricsDir: string;
+        summaryFile?: string;
+    };
+    filter?: BackfillFilter;
+    /** 目标目录已有快照（live 优先）则跳过，默认 true */
+    skipExisting?: boolean;
+    /** 增量模式：读各目录 .backfill-state.json 水位，只回填 time_created 更晚的会话 */
+    incremental?: boolean;
+    /** 只统计不写盘 */
+    dryRun?: boolean;
+    /** 单会话回填完成回调 */
+    onSessionBackfilled?: (sessionId: string, label: string, metricsDir: string) => void;
+}
+export interface BackfillEngineStat {
+    label: string;
+    metricsDir: string;
+    written: number;
+    skippedExisting: number;
+    skippedEmpty: number;
+}
+export interface BackfillResult {
+    perEngine: BackfillEngineStat[];
+    fallback: BackfillEngineStat | null;
+    skippedByFilter: number;
+    unattributed: number;
+    total: number;
+}
+export type BackfillMetricsOutput = MetricsOutput & {
+    source: "backfill";
+};
+/** 从 opencode.db 回填历史会话统计：按归属规则路由写入各引擎目录（快照带 source:"backfill"）。 */
+export declare function backfillFromOpencode(opts: BackfillOptions): Promise<BackfillResult>;