opencode-metrics-plugin 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.3.0（未发布）
+
+- 新增会话产物上传：`git commit` / 会话结束自动打包（快照 + 事件日志 + 工作区产物）上传 AGC 云存储，安卓工程自动剔除，失败指数退避重试。
+- 新增 checkpoint 实时落盘（默认 2s 冷却），会话中途退出不再丢指标。
+- 新增独立配置文件 `.opencode/opencode-metrics.json(.jsonc)`（支持注释），存在即完全接管内联配置。
+
+## 0.2.0
+
+- 重构为纯快照 JSON 输出：移除 sqlite/backfill 链路，src 按 engine / snapshot / eventlog / analysis 域重组。
+- 插件接管 systemPrompts 记录；发布渠道迁移至 npm 公共源，包名定为 opencode-metrics-plugin。
+
+## 0.1.x
+
+- 初始版本：opencode 会话事件采集、快照落盘与历史会话补录（GitHub Packages scoped 发布）。

package/README.md

@@ -1,82 +1,111 @@
 # opencode-metrics-plugin
 
-**opencode 会话指标插件**：挂上即自动记录每个会话的完整指标（tokens / rounds / steps 全文 / 子代理 / 工具调用 / hvigor 构建统计），每轮对话结束落盘一个快照 JSON。
+**opencode 会话指标插件**：挂上即自动记录每个会话的完整指标（tokens / rounds / steps 全文 / 子代理 / 工具调用 / hvigor 构建统计），并支持把会话快照与工作区产物自动上传到云存储。
 
 - **开箱即用**：宿主只需在 `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 解析展示（完全解耦）
-```
+- **实时落盘**：会话进行中每 2s 增量写盘，中途退出不丢数据
+- **产物上传**（可选）：`git commit` 或会话结束时自动打包上传，安卓源码工程自动剔除
+- **独立配置文件**：`.opencode/opencode-metrics.json(.jsonc)` 支持注释，存在即完全接管内联配置
+- **零打扰**：不修改工作区、不执行 clean；上传默认关闭，不配置零开销
 
 ## 快速开始
 
+### 第 1 步：注册插件
+
 宿主项目 `opencode.json`：
 
 ```jsonc
-// 最简
 { "plugin": ["opencode-metrics-plugin"] }
+```
+
+仅此一步即完成指标采集，无需其他配置。
+
+### 第 2 步（可选）：独立配置文件
 
-// 带配置
+在项目 `.opencode/` 目录下创建 `opencode-metrics.json` 或 `opencode-metrics.jsonc`（支持注释与尾逗号）。文件存在时**完全接管**内联第二参，推荐用这种方式配置：
+
+```jsonc
+// .opencode/opencode-metrics.jsonc —— 最小上传配置
 {
-  "plugin": [
-    ["opencode-metrics-plugin", { "enabled": true, "eventLogging": true }]
-  ]
+  "upload": {
+    "enabled": true
+  }
 }
 ```
 
-配置项（全部可选）：
+上传开启后默认使用包内 AGC 凭证，无需额外配置。
 
-| 选项 | 类型 | 默认 | 说明 |
-|---|---|---|---|
-| `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` | — | 快照落盘后回调（可在此上报自有系统） |
+### 第 3 步（可选）：验证
 
-## 输出
+- 指标：会话进行几轮后，查看输出目录（见下）出现 `<sessionId>.json` 与 `events/<sessionId>.log`
+- 上传：会话内执行一次 `git commit`，插件日志出现 `上传完成`，云存储桶出现 `YYYYMMDD/<项目名>-<sessionId>/` 目录
 
-默认目录（appName `opencode-metrics-plugin`，env-paths 规范）：
+## 采集内容
+
+每个会话一个 `<sessionId>.json` 快照（`MetricsOutput` 结构）：
+
+| 字段 | 内容 |
+|---|---|
+| `header` | sessionId / 工作目录 / agent / model 及切换分布 |
+| `systemPrompts` | 各模型 system prompt（子代理跳过） |
+| `rounds[]` | 每轮 duration、首 token 延迟、tokens、工具调用数、用户消息 |
+| `steps[]` | 每步全文（text / reasoning）、tokens、cost、工具明细 |
+| `subagents[]` | 子代理（task/explore 等）steps、tokens、工具统计，自动并入父会话 |
+| `codeStats` | hvigorw 构建统计（错误码 / 警告 / 模块耗时 / 修复周期；非 HarmonyOS 会话为空） |
+| `planning` | todowrite 规划统计 |
+
+配套可视化：[session-viewer](../session-viewer) 扫描 metricsDir 直接解析展示，无需服务端。
+
+## 产物上传
+
+开启 `upload.enabled` 后：
+
+- **触发场景**：bash 执行 `git commit`（label=`git`）、会话结束/插件退出（label=`session-end`）；可自定义场景（命令正则或事件名）
+- **打包内容**：时点快照 JSON + 事件日志（恒含）+ 会话动过的工作区产物根（鸿蒙工程标记探测，≤3 个）
+- **自动剔除**：黑名单目录（`oh_modules` / `build` / `node_modules` 等 8 项）；安卓工程（根级 + 子树级，gradle 信号 ≥2 判定，可用 `excludeAndroidProjects: false` 关闭）
+- **云端路径**：`YYYYMMDD/<安卓包名或项目名>-<sessionId>/<agent缩写>-<触发>-v<n>/<agent缩写>-<触发>-v<n>.tar.gz` 与同名 `.json`（一个版本一个目录，双文件归拢）
+- **可靠性**：串行队列 + 指数退避重试（默认 5 次，4xx 不重试）；上传成功/终态失败后自动清理本地暂存
+
+## 输出目录
+
+默认按 env-paths 规范落在用户目录（可用 `dirs` 自定义）：
 
 | 平台 | 路径 |
 |---|---|
-| Windows | `%LOCALAPPDATA%\opencode-metrics-plugin\Log\metrics\`（events 同级） |
-| Linux | `~/.local/state/opencode-metrics-plugin/metrics/` |
-| macOS | `~/Library/Logs/opencode-metrics-plugin/metrics/` |
+| Windows | `%LOCALAPPDATA%\opencode-metrics-plugin\Log\{metrics,events,plugin.log}`、`...\Data\upload-staging` |
+| Linux | `~/.local/state/opencode-metrics-plugin/{metrics,events}` |
+| macOS | `~/Library/Logs/opencode-metrics-plugin/{metrics,events}` |
+
+## 配置项速查
 
-每个会话一个 `<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 直接解析展示，无需任何服务端支持。
+| 选项 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `enabled` | boolean | `true` | 总开关，`false` 时不记录任何会话 |
+| `eventLogging` | boolean | `true` | 原始事件写盘；关闭后快照仍生成，但 `steps[].text/reasoning` 为空 |
+| `checkpointFlushIntervalMs` | number | `2000` | 实时落盘冷却窗口（ms），`0` 关闭退回只在会话空闲时落盘 |
+| `dirs` | object | env-paths | `metricsDir` / `eventsDir` / `logFile` / `uploadStagingDir` |
+
+### upload 块
+
+| 选项 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `upload.enabled` | boolean | `false` | 上传总开关；不配置本块零开销 |
+| `upload.uploader.agcConfigPath` | string | 包内凭证 | `agc-apiclient.json` 绝对路径（client_id/secret/project_id/region/bucket） |
+| `upload.scenarios` | object | 内置两场景 | 按 key 合并：`enabled:false` 禁用内置；自定义场景提供 `commands`（正则）或 `events`（事件名）与 `label`（进文件名） |
+| `upload.appendArtifacts` | array | — | 追加产物规则：`path`（绝对或相对会话工作目录）+ `matchBy`（`session-activity` 会话动过才纳入 / `existence` 存在即纳入）+ `dirMarkers`/`fileMarkers` |
+| `upload.blacklist` | string[] | 默认 8 项 | 打包排除的目录/文件名（追加，不替换） |
+| `upload.excludeAndroidProjects` | boolean | `true` | 剔除安卓工程（根级 + 根内子树） |
+| `upload.maxArtifactBytes` | number | `524288000` | 单包体积上限（默认 500MB），超限该次标失败 |
+| `upload.retry` | object | `{5, 1000}` | `maxAttempts` 最大尝试次数；`backoffMs` 退避基数（1s/4s/16s/64s/256s） |
 
 ## 可编程 API
 
 ```ts
-import { createMetricsRuntime, configureDirs } from 'opencode-metrics-plugin/api'
+import { createMetricsRuntime } from 'opencode-metrics-plugin/api'
 
 const rt = createMetricsRuntime({
   dirs: { metricsDir: '/data/metrics', eventsDir: '/data/events' },
@@ -97,12 +126,10 @@ rt.engine.dispose()
 
 ```bash
 npm run typecheck   # tsc --noEmit
-npm test            # 冒烟测试（example/smoke.mts，27 断言）
+npm test            # 冒烟测试（example/smoke.mts，53 断言）
 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/assets/agc-apiclient.json

@@ -0,0 +1,10 @@
+{
+    "type": "project_client_id",
+    "developer_id": "2850086000535724929",
+    "project_id": "101653523864996148",
+    "client_id": "2036342510879556160",
+    "client_secret": "D6F8DA190967ABF81A2E17F0AE7C96A9DB7094BB9870230D7D701E5153338F04",
+    "configuration_version": "3.0",
+    "region": "CN",
+    "bucket_name": "d2h-oekjj"
+}

package/dist/metrics/configLoader.d.ts

@@ -0,0 +1,20 @@
+import type { MetricsRuntimeOptions } from "./runtime.js";
+/** 插件独立配置文件（项目 .opencode 目录下；.json 优先于 .jsonc） */
+export declare const CONFIG_FILE_NAMES: readonly string[];
+export interface ResolvedPluginConfig {
+    /** 生效配置（独立文件内容或内联第二参） */
+    config: MetricsRuntimeOptions;
+    /** 配置来源：file = 独立文件接管，inline = opencode.json 内联 */
+    source: "file" | "inline";
+}
+/**
+ * 解析插件生效配置：项目 .opencode 目录下存在 opencode-metrics.json / .jsonc
+ * （按此顺序查找，内容容忍 JSONC 注释与尾逗号）且为合法对象时完全接管
+ * （opencode.json 内联第二参全部忽略），否则回退内联。
+ * 文件缺失静默回退；内容非法记日志回退，不抛异常。
+ *
+ * @param projectDirectory opencode 启动的项目根（PluginInput.directory）
+ * @param inlineOptions    opencode.json 插件内联第二参
+ * @returns                 生效配置与来源
+ */
+export declare function resolvePluginConfig(projectDirectory: string, inlineOptions?: MetricsRuntimeOptions): ResolvedPluginConfig;

package/dist/metrics/configLoader.js

@@ -0,0 +1,99 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { log } from "../shared/log.js";
+/** 插件独立配置文件（项目 .opencode 目录下；.json 优先于 .jsonc） */
+export const CONFIG_FILE_NAMES = [
+    ".opencode/opencode-metrics.json",
+    ".opencode/opencode-metrics.jsonc",
+];
+/**
+ * 解析插件生效配置：项目 .opencode 目录下存在 opencode-metrics.json / .jsonc
+ * （按此顺序查找，内容容忍 JSONC 注释与尾逗号）且为合法对象时完全接管
+ * （opencode.json 内联第二参全部忽略），否则回退内联。
+ * 文件缺失静默回退；内容非法记日志回退，不抛异常。
+ *
+ * @param projectDirectory opencode 启动的项目根（PluginInput.directory）
+ * @param inlineOptions    opencode.json 插件内联第二参
+ * @returns                 生效配置与来源
+ */
+export function resolvePluginConfig(projectDirectory, inlineOptions = {}) {
+    if (!projectDirectory)
+        return { config: inlineOptions, source: "inline" };
+    let configPath = "";
+    let raw;
+    for (const name of CONFIG_FILE_NAMES) {
+        const candidate = path.join(projectDirectory, name);
+        try {
+            raw = fs.readFileSync(candidate, "utf-8");
+            configPath = candidate;
+            break;
+        }
+        catch {
+            // 该名字的文件不存在，尝试下一个
+        }
+    }
+    if (raw === undefined)
+        return { config: inlineOptions, source: "inline" };
+    let parsed;
+    try {
+        parsed = JSON.parse(stripJsoncSyntax(raw));
+    }
+    catch (err) {
+        log.error("[Metrics] 配置文件内容非法，回退内联配置", { configPath, error: String(err) });
+        return { config: inlineOptions, source: "inline" };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        log.error("[Metrics] 配置文件顶层必须是对象，回退内联配置", { configPath });
+        return { config: inlineOptions, source: "inline" };
+    }
+    log.info("[Metrics] 使用独立配置文件", { configPath });
+    return { config: parsed, source: "file" };
+}
+/**
+ * 去除 JSONC 语法（行注释 / 块注释 / 尾逗号），字符串内的 // 与 /* 原样保留。
+ *
+ * @param text 原始文件内容
+ * @returns      可交给 JSON.parse 的纯 JSON 文本
+ */
+function stripJsoncSyntax(text) {
+    let result = "";
+    let inString = false;
+    let index = 0;
+    while (index < text.length) {
+        const char = text[index];
+        const next = text[index + 1];
+        if (inString) {
+            result += char;
+            if (char === "\\") {
+                result += next ?? "";
+                index += 2;
+                continue;
+            }
+            if (char === "\"")
+                inString = false;
+            index++;
+            continue;
+        }
+        if (char === "\"") {
+            inString = true;
+            result += char;
+            index++;
+            continue;
+        }
+        if (char === "/" && next === "/") {
+            while (index < text.length && text[index] !== "\n")
+                index++;
+            continue;
+        }
+        if (char === "/" && next === "*") {
+            index += 2;
+            while (index < text.length && !(text[index] === "*" && text[index + 1] === "/"))
+                index++;
+            index += 2;
+            continue;
+        }
+        result += char;
+        index++;
+    }
+    return result.replace(/,(\s*[}\]])/g, "$1");
+}

package/dist/metrics/dirs.d.ts

@@ -6,6 +6,8 @@ export interface MetricsDirs {
     eventsDir: string;
     /** 运行日志文件（可选；logger 无文件权限时回退 console） */
     logFile: string;
+    /** 上传暂存目录（tar.gz 产物包输出位置；默认 <envPaths.data>/upload-staging） */
+    uploadStagingDir: string;
 }
 export declare function defaultDirs(appName?: string): MetricsDirs;
 /**

package/dist/metrics/dirs.js

@@ -7,6 +7,7 @@ export function defaultDirs(appName = 'opencode-metrics-plugin') {
         metricsDir: path.join(base.log, 'metrics'),
         eventsDir: path.join(base.log, 'events'),
         logFile: path.join(base.log, 'plugin.log'),
+        uploadStagingDir: path.join(base.data, 'upload-staging'),
     };
 }
 let _dirs = defaultDirs();

package/dist/metrics/engine/engine.d.ts

@@ -1,15 +1,19 @@
 import type { MetricsEngine, MetricsOutput } from "../types.js";
 import type { MetricsDirs } from "../dirs.js";
+/** 两次 checkpoint 落盘之间的默认最小间隔（ms） */
+export declare const DEFAULT_CHECKPOINT_FLUSH_INTERVAL_MS = 2000;
 export type { TokenUsage, ToolStats, StageType, StageInfo, MessageEntry, ToolCallEntry, SessionMeta, CompileStats, SkillCallEntry, SkillSearchEntry, StepData, RoundSnapshot, SubAgentOutput, MetricsOutput, MetricsEngine, } from "../types.js";
 export interface MetricsEngineOptions {
     enabled?: boolean;
-    /** 本引擎输出目录（多引擎各自独立）；缺省回退进程级默认（configureDirs），构造时解析固化 */
+    /** 本引擎的输出目录；缺省用进程级默认目录 */
     dirs?: Partial<MetricsDirs>;
-    /** flush 会话快照后回调（宿主可在此把快照上报自有系统） */
+    /** 每次快照落盘后的回调 */
     onFlush?: (sessionId: string, snapshot: MetricsOutput) => void;
+    /** 两次 checkpoint 落盘之间的最小间隔（ms）；0 = 关闭 checkpoint，只在 idle/退出时落盘 */
+    checkpointFlushIntervalMs?: number;
 }
 /**
- * 创建指标引擎：订阅事件流，按会话累计状态，idle/flush/dispose 产出快照 JSON。
- * 0.2.0 起移除 scope 门控——记录全部会话；子会话（parentID）自动并入父会话。
+ * 创建指标引擎：订阅事件流，按会话累计指标，落盘快照 JSON。
+ * 子会话（parentID）自动并入父会话。
  */
 export declare function createMetricsEngine(opts?: MetricsEngineOptions): MetricsEngine;

package/dist/metrics/engine/engine.js

@@ -2,19 +2,25 @@ import { TRACKED_EVENT_TYPES } from "../types.js";
 import { createSessionMetrics } from "./state.js";
 import { handlePartUpdated, handleSessionUpdated, handleMessageUpdated, handleSubAgentParts } from "./handlers.js";
 import { handleSessionIdle, flushMetrics } from "../snapshot/flush.js";
+import { clearStepContentCache } from "../snapshot/steps.js";
 import { mergeChildMetrics } from "../snapshot/merge.js";
 import { resolveDirs } from "../dirs.js";
 import { log } from "../../shared/log.js";
+/** 两次 checkpoint 落盘之间的默认最小间隔（ms） */
+export const DEFAULT_CHECKPOINT_FLUSH_INTERVAL_MS = 2000;
 /**
- * 创建指标引擎：订阅事件流，按会话累计状态，idle/flush/dispose 产出快照 JSON。
- * 0.2.0 起移除 scope 门控——记录全部会话；子会话（parentID）自动并入父会话。
+ * 创建指标引擎：订阅事件流，按会话累计指标，落盘快照 JSON。
+ * 子会话（parentID）自动并入父会话。
  */
 export function createMetricsEngine(opts = {}) {
     const enabled = opts.enabled !== false;
     const instanceDirs = opts.dirs ? resolveDirs(opts.dirs) : undefined;
+    const checkpointIntervalMs = opts.checkpointFlushIntervalMs ?? DEFAULT_CHECKPOINT_FLUSH_INTERVAL_MS;
     const sessions = new Map();
     const childToParent = new Map();
     const childSessionIds = new Set();
+    // 上次 checkpoint 落盘时刻（引擎级，所有会话共享冷却窗口）
+    let lastCheckpointAt = 0;
     function resolveSessionId(rawId) {
         return childToParent.get(rawId) ?? rawId;
     }
@@ -50,14 +56,22 @@ export function createMetricsEngine(opts = {}) {
         log.info("[Metrics] extractSessionId: no sessionID found", { type: event.type });
         return undefined;
     }
+    /**
+     * 获取会话状态，不存在则创建。
+     *
+     * @param sessionId 会话 id
+     * @returns 会话状态，及是否为本次新建
+     */
     function getOrCreateSession(sessionId) {
         let state = sessions.get(sessionId);
         if (!state) {
             state = createSessionMetrics(sessionId);
             sessions.set(sessionId, state);
+            return { state, created: true };
         }
-        return state;
+        return { state, created: false };
     }
+    /** 调用 onFlush 回调，回调抛错只记日志不中断 */
     function emitFlush(sessionId, snapshot) {
         if (snapshot && opts.onFlush) {
             try {
@@ -68,6 +82,56 @@ export function createMetricsEngine(opts = {}) {
             }
         }
     }
+    /**
+     * 结束会话：把进行中的 stage 和未完结的修复周期收尾入账，写出最终 JSON。
+     *
+     * @param sessionId 会话 id
+     * @param state     会话状态（就地结算）
+     * @param now       结束时刻（ms）
+     */
+    function finalizeAndFlush(sessionId, state, now) {
+        if (state.currentStage) {
+            state.currentStage.endTime = now;
+            state.currentStage.tokens = { ...state._stageTokens };
+            if (state.currentStage.stage === "build") {
+                state.currentStage.hvigorwCalls = state.compileStats.hvigorwCalls;
+            }
+            state.stages.push(state.currentStage);
+            state.currentStage = null;
+        }
+        state.lastStageEndTime = now;
+        if (state.compileStats._pendingFix) {
+            state.compileStats.fixCycles.push({
+                failTime: state.compileStats._pendingFix.failTime,
+                successTime: 0,
+                attempts: state.compileStats._pendingFix.attempts,
+                codeChanges: state.compileStats._pendingFix.codeChanges,
+            });
+            state.compileStats._pendingFix = null;
+        }
+        state.endTime = now;
+        state._checkpointDirty = false;
+        emitFlush(sessionId, flushMetrics(sessionId, state, now, instanceDirs));
+    }
+    /**
+     * checkpoint 判定：会话有新数据且冷却期已过时，把当前状态落盘。
+     *
+     * @param sessionId 会话 id
+     * @param state     会话状态（读取并清除 _checkpointDirty）
+     */
+    function evaluateCheckpoint(sessionId, state) {
+        if (checkpointIntervalMs <= 0)
+            return;
+        if (!state._checkpointDirty)
+            return;
+        const now = Date.now();
+        if (now - lastCheckpointAt < checkpointIntervalMs)
+            return;
+        lastCheckpointAt = now;
+        state._checkpointDirty = false;
+        log.info("[Metrics] checkpoint flush", { sessionId });
+        emitFlush(sessionId, flushMetrics(sessionId, state, now, instanceDirs));
+    }
     return {
         ingest(event) {
             if (!enabled)
@@ -88,7 +152,7 @@ export function createMetricsEngine(opts = {}) {
                 const agentName = parts[3] || "";
                 const title = parts[4] || "";
                 sessionId = parentId;
-                const parentState = getOrCreateSession(parentId);
+                const { state: parentState } = getOrCreateSession(parentId);
                 const childState = sessions.get(childId);
                 if (childState) {
                     log.info("[Metrics] Migration: merging existing child state", { childId, parentId });
@@ -114,19 +178,37 @@ export function createMetricsEngine(opts = {}) {
                     }
                 }
             }
-            const state = getOrCreateSession(sessionId);
+            const { state, created } = getOrCreateSession(sessionId);
             // 子代理事件路由：原始事件来自子会话时进入对应 subAgents 条目
             const originalSessionId = props?.sessionID || "";
             if (childSessionIds.has(originalSessionId)) {
                 const sub = state.subAgents.get(originalSessionId);
                 if (sub) {
                     handleSubAgentParts(sub, event);
+                    // 子代理的完整回复/单步结束：置脏父会话
+                    if (event.type === "message.updated" ||
+                        (event.type === "message.part.updated" &&
+                            props?.part?.type === "step-finish")) {
+                        state._checkpointDirty = true;
+                    }
+                    evaluateCheckpoint(sessionId, state);
                     return;
                 }
                 else {
                     log.info("[Metrics] Sub-agent routing MISS — entry not found", { eventType: event.type, originalSessionId, subAgentsKeys: [...state.subAgents.keys()] });
                 }
             }
+            // 会话被删除：最终落盘后清掉内存态与解析缓存
+            if (event.type === "session.deleted") {
+                finalizeAndFlush(sessionId, state, Date.now());
+                sessions.delete(sessionId);
+                clearStepContentCache(sessionId, instanceDirs?.eventsDir);
+                return;
+            }
+            // 新会话的首个事件：置脏让快照文件尽早出现
+            if (created || event.type === "session.created") {
+                state._checkpointDirty = true;
+            }
             // 提取工作目录
             if (event.type === "session.created" && props) {
                 const info = props.info;
@@ -143,7 +225,13 @@ export function createMetricsEngine(opts = {}) {
                 handlePartUpdated(state, props);
             }
             if (event.type === "session.updated" && props) {
+                const attributionBefore = `${state.agent.current}|${state.model.current}|${state.sessionMeta.workingDirectory}`;
                 handleSessionUpdated(state, props);
+                const attributionAfter = `${state.agent.current}|${state.model.current}|${state.sessionMeta.workingDirectory}`;
+                // agent/model/目录任一变化：置脏
+                if (attributionBefore !== attributionAfter) {
+                    state._checkpointDirty = true;
+                }
             }
             if (event.type === "session.idle") {
                 emitFlush(sessionId, handleSessionIdle(state, sessionId, instanceDirs));
@@ -156,6 +244,12 @@ export function createMetricsEngine(opts = {}) {
             }
             if (event.type === "message.updated" && props) {
                 handleMessageUpdated(state, props);
+                const info = props.info;
+                const role = info?.role;
+                // 用户消息（轮开始）或 assistant 完整回复结束：置脏
+                if (role === "user" || (role === "assistant" && info?.finish)) {
+                    state._checkpointDirty = true;
+                }
             }
             if (event.type === "permission.asked" ||
                 event.type === "permission.replied" ||
@@ -165,11 +259,13 @@ export function createMetricsEngine(opts = {}) {
                     state.anomaly.events.push(event.type);
                 }
             }
+            // 统一的 checkpoint 判定点
+            evaluateCheckpoint(sessionId, state);
         },
         ingestPrompt(sessionId, modelId, system) {
             if (!enabled)
                 return;
-            const state = getOrCreateSession(resolveSessionId(sessionId));
+            const { state } = getOrCreateSession(resolveSessionId(sessionId));
             state.systemPrompts.set(modelId, system);
         },
         isSubAgent(sessionId) {
@@ -183,32 +279,14 @@ export function createMetricsEngine(opts = {}) {
             state.endTime = now;
             emitFlush(sessionId, flushMetrics(sessionId, state, now, instanceDirs));
         },
+        /** 结束引擎：把尚未落盘的会话逐一落盘，并清空全部内存 */
         dispose() {
             const now = Date.now();
             for (const [sessionId, state] of sessions) {
                 if (state._idleFlushed)
                     continue;
-                if (state.currentStage) {
-                    state.currentStage.endTime = now;
-                    state.currentStage.tokens = { ...state._stageTokens };
-                    if (state.currentStage.stage === "build") {
-                        state.currentStage.hvigorwCalls = state.compileStats.hvigorwCalls;
-                    }
-                    state.stages.push(state.currentStage);
-                    state.currentStage = null;
-                }
-                state.lastStageEndTime = now;
-                if (state.compileStats._pendingFix) {
-                    state.compileStats.fixCycles.push({
-                        failTime: state.compileStats._pendingFix.failTime,
-                        successTime: 0,
-                        attempts: state.compileStats._pendingFix.attempts,
-                        codeChanges: state.compileStats._pendingFix.codeChanges,
-                    });
-                    state.compileStats._pendingFix = null;
-                }
-                state.endTime = now;
-                emitFlush(sessionId, flushMetrics(sessionId, state, now, instanceDirs));
+                finalizeAndFlush(sessionId, state, now);
+                clearStepContentCache(sessionId, instanceDirs?.eventsDir);
             }
             sessions.clear();
             childToParent.clear();

package/dist/metrics/engine/state.d.ts

@@ -10,6 +10,19 @@ export interface SubAgentState {
     _userMessageIds: Set<string>;
     _pendingUserMessage: string[];
 }
+/**
+ * 上次 flush 时各累加字段的累计值，用于本次 flush 计算差量、避免重复累计。
+ */
+export interface FlushBaseline {
+    errorCodeCounts: Record<string, number>;
+    warningCounts: Record<string, number>;
+    warningEntriesTotal: number;
+    moduleTimings: Record<string, {
+        totalDuration: number;
+        taskCount: number;
+    }>;
+    fixCycleCount: number;
+}
 export interface SessionMetricsState {
     sessionId: string;
     startTime: number;
@@ -58,6 +71,10 @@ export interface SessionMetricsState {
     _roundFirstBuildTracked: boolean;
     _roundIdleProcessed: boolean;
     _idleFlushed: boolean;
+    /** 有未落盘的新数据，待下次 checkpoint 判定时落盘 */
+    _checkpointDirty: boolean;
+    /** 上次 flush 的累加字段基线；null = 尚未 flush 过 */
+    _flushBaseline: FlushBaseline | null;
     messageMap: Map<string, MessageEntry>;
     toolCallMap: Map<string, ToolCallEntry>;
     textLengthMap: Map<string, number>;

package/dist/metrics/engine/state.js

@@ -78,6 +78,8 @@ export function createSessionMetrics(sessionId) {
         _roundFirstBuildTracked: false,
         _roundIdleProcessed: false,
         _idleFlushed: false,
+        _checkpointDirty: false,
+        _flushBaseline: null,
         planningCalls: [],
         systemPrompts: new Map(),
     };

package/dist/metrics/index.d.ts

@@ -6,4 +6,7 @@ export { createEventLogger } from './eventlog/event-logger.js';
 export type { EventLogger, EventLoggerOptions } from './eventlog/event-logger.js';
 export { createMetricsRuntime } from './runtime.js';
 export type { MetricsRuntime, MetricsRuntimeOptions } from './runtime.js';
+export { createUploadManager } from './upload/uploadManager.js';
+export type { UploadManager, UploadManagerOptions } from './upload/uploadManager.js';
+export type { UploadConfig, ScenarioConfig, ArtifactRule, UploadPackage } from './upload/types.js';
 export * from './types.js';

package/dist/metrics/index.js

@@ -3,4 +3,5 @@ export { createMetricsEngine } from './engine/engine.js';
 export { configureDirs, defaultDirs, getDirs, resolveDirs, getMetricsDir, getEventsDir, getLogFile } from './dirs.js';
 export { createEventLogger } from './eventlog/event-logger.js';
 export { createMetricsRuntime } from './runtime.js';
+export { createUploadManager } from './upload/uploadManager.js';
 export * from './types.js';