opencode-metrics-plugin 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.3.3（2026-09-12）
+
+- session-end 三层保障，修复宿主进程突然死亡导致会话终态包永不产出的问题：
+  - **task 工具终态触发**：根会话的 task 工具 `completed` / `error` 即刻打包上传 session-end（子代理嵌套调用不触发，callID 去重）；
+  - **打包前快照终稿化**：打包前先冲刷事件日志与引擎快照，包内快照必含触发事件本身（原 2s 冷却可能落后）；
+  - **孤儿快照补传**：启动时扫描静默超 24h 且未上云终态的快照（`metrics/.sent/` 已传标记防重），按快照证据补打 session-end 包，超 7 天放弃（`upload.orphanRescue` 可调）。
+- 场景系统支持 `tools` 工具名匹配器（内置 session-end 即 `tools: ["task"]`）；`session.created` 即种子工作区证据，纯 task 会话也能完成根推断与包名推断。
+
+## 0.3.2（2026-09-12）
+
+- 产物根推断增强：迁移工作区标记修正为 `.migration`；安卓工程根容器化降级（向内提升鸿蒙子工程与 `.migration`/`.harmonyos` 工作区）；会话时间窗内新建的相邻鸿蒙工程纳入，邻居老工程不混入；纯安卓工程不打包。
+- 新增 hap 产物通道：build 目录内的 `.hap` 借道组装目录随包上传，不受 build 黑名单影响。
+- 配置三级优先：项目 `.opencode/` → 用户目录 `~/.config/opencode/` → 内联；各级 json 优先于 jsonc，内容非法自动落下一级。
+- 上传失败保留与启动补偿重传：失败包移入 `failed/` 与云端同构目录（可手动上传），下次启动自动重传，成功即清理；超期（默认 7 天）/超量（默认 1GB）自动清理（`upload.retryRescue`）。
+- 运行日志按日期归档：写入 `<日志目录>/log/plugin/YYYYMMDD.log`（进程首写定死当天文件，跨午夜不切换），启动时自动清理超 30 天的日期日志；旧 `plugin.log` 保留不动。
+- 云端路径日期目录改用包创建时间（createdAt），消除跨午夜漂移与重传漂移。
+
 ## 0.3.1（2026-09-10）
 
 - 上传总开关 `upload.enabled` 缺省改为 true：插件装上即上传（包内 AGC 凭证），`false` 显式关闭。

package/README.md

@@ -5,7 +5,8 @@
 - **开箱即用**：宿主只需在 `opencode.json` 加一行，无需任何配置
 - **实时落盘**：会话进行中每 2s 增量写盘，中途退出不丢数据
 - **开箱即传**：上传默认开启（包内 AGC 凭证），`git commit` / 会话结束自动打包上传，安卓源码工程自动剔除，`upload.enabled: false` 可关
-- **独立配置文件**：`.opencode/opencode-metrics.json(.jsonc)` 支持注释，存在即完全接管内联配置
+- **独立配置文件**：`.opencode/opencode-metrics.json(.jsonc)` 支持注释，存在即完全接管内联配置；用户目录 `~/.config/opencode/` 可放全局兜底配置
+- **失败不丢**：上传失败的包保留在 `failed/`（与云端路径同构，可手动上传），下次启动自动补偿重传
 - **零打扰**：不修改工作区、不执行 clean
 
 ## 快速开始
@@ -56,11 +57,13 @@
 
 默认开启（`upload.enabled: false` 可关）：
 
-- **触发场景**：bash 执行 `git commit`（label=`git`）、会话结束/插件退出（label=`session-end`）；可自定义场景（命令正则或事件名）
-- **打包内容**：时点快照 JSON + 事件日志（恒含）+ 会话动过的工作区产物根（鸿蒙工程标记探测，≤3 个）
+- **触发场景**：bash 执行 `git commit`（label=`git`）；会话结束/插件退出（label=`session-end`）；**根会话 task 工具完成或失败即刻触发 session-end**（子代理嵌套调用不触发）。可自定义场景（命令正则、事件名或工具名）
+- **打包内容**：时点快照 JSON + 事件日志（恒含）+ 会话动过的工作区产物根（鸿蒙工程标记探测，≤3 个）+ build 目录内的 `.hap` 产物包（借道组装目录，不受 build 黑名单影响）
+- **根推断增强**：安卓工程根（如 gradle 外壳）不整根保留也不丢弃——向内扫描提升鸿蒙子工程（`ohos/` 等）与迁移工作区（`.migration` / `.harmonyos`）；会话期间新建的相邻鸿蒙工程（目录 mtime 在会话开始之后）也会纳入，邻居老工程不混入；纯安卓工程（无任何鸿蒙子根）不打包
 - **自动剔除**：黑名单目录（`oh_modules` / `build` / `node_modules` 等 8 项）；安卓工程（根级 + 子树级，gradle 信号 ≥2 判定，可用 `excludeAndroidProjects: false` 关闭）
-- **云端路径**：`YYYYMMDD/<安卓包名或项目名>-<sessionId>/<agent缩写>-<触发>-v<n>/<agent缩写>-<触发>-v<n>.tar.gz` 与同名 `.json`（一个版本一个目录，双文件归拢）
-- **可靠性**：串行队列 + 指数退避重试（默认 5 次，4xx 不重试）；上传成功/终态失败后自动清理本地暂存
+- **云端路径**：`YYYYMMDD/<安卓包名或项目名>-<sessionId>/<agent缩写>-<触发>-v<n>/<agent缩写>-<触发>-v<n>.tar.gz` 与同名 `.json`（一个版本一个目录，双文件归拢；日期取包创建日）
+- **可靠性**：串行队列 + 指数退避重试（默认 5 次，4xx 不重试）；失败包移入暂存目录 `failed/` 下**与云端同构的目录**（含 meta 元数据，可整目录手动上传），下次启动自动补偿重传，重传成功即清理；保留超期（默认 7 天）或超量（默认 1GB，从最旧删）自动清理
+- **进程死亡兜底**：宿主突然退出（session-end 从未触发）时，下次启动对静默超 24h 且未传终态的快照自动补打 session-end 包（`metrics/.sent/` 已传标记防重传，超 7 天放弃）
 
 ## 输出目录
 
@@ -68,7 +71,7 @@
 
 | 平台 | 路径 |
 |---|---|
-| Windows | `%LOCALAPPDATA%\opencode-metrics-plugin\Log\{metrics,events,plugin.log}`、`...\Data\upload-staging` |
+| Windows | `%LOCALAPPDATA%\opencode-metrics-plugin\Log\{metrics,events}`、`...\Log\log\plugin\YYYYMMDD.log`（运行日志按日期归档，保留 30 天）、`...\Data\upload-staging` |
 | Linux | `~/.local/state/opencode-metrics-plugin/{metrics,events}` |
 | macOS | `~/Library/Logs/opencode-metrics-plugin/{metrics,events}` |
 
@@ -83,7 +86,7 @@
 | `enabled` | boolean | `true` | 总开关，`false` 时不记录任何会话 |
 | `eventLogging` | boolean | `true` | 原始事件写盘；关闭后快照仍生成，但 `steps[].text/reasoning` 为空 |
 | `checkpointFlushIntervalMs` | number | `2000` | 实时落盘冷却窗口（ms），`0` 关闭退回只在会话空闲时落盘 |
-| `dirs` | object | env-paths | `metricsDir` / `eventsDir` / `logFile` / `uploadStagingDir` |
+| `dirs` | object | env-paths | `metricsDir` / `eventsDir` / `logFile`（基准，实际写 `<所在目录>/log/plugin/YYYYMMDD.log`）/ `uploadStagingDir` |
 
 ### upload 块
 
@@ -91,12 +94,14 @@
 |---|---|---|---|
 | `upload.enabled` | boolean | `true` | 上传总开关；`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.scenarios` | object | 内置两场景 | 按 key 合并：`enabled:false` 禁用内置；自定义场景提供 `commands`（正则）/ `events`（事件名）/ `tools`（工具名，终态触发）与 `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） |
+| `upload.retryRescue` | object | `{true, 7, 1GB}` | 失败保留与补偿重传：`enabled` 开关；`retentionDays` 保留天数；`maxFailedBytes` failed/ 总量上限（超限从最旧删） |
+| `upload.orphanRescue` | object | `{true, 24, 7}` | 孤儿快照补传：`enabled` 开关；`idleHours` 静默下限（小时）；`maxAgeDays` 最大快照年龄（天），超龄放弃 |
 
 ## 可编程 API
 
@@ -122,7 +127,7 @@ rt.engine.dispose()
 
 ```bash
 npm run typecheck   # tsc --noEmit
-npm test            # 冒烟测试（example/smoke.mts，53 断言）
+npm test            # 冒烟测试（example/smoke.mts，90 断言）
 npm run build       # 清空 dist 后 tsc
 ```
 

package/dist/metrics/configLoader.d.ts

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

package/dist/metrics/configLoader.js

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { log } from "../shared/log.js";
 /** 插件独立配置文件（项目 .opencode 目录下；.json 优先于 .jsonc） */
@@ -6,48 +7,86 @@ export const CONFIG_FILE_NAMES = [
     ".opencode/opencode-metrics.json",
     ".opencode/opencode-metrics.jsonc",
 ];
+/** 插件全局配置文件（用户 home 下 .config/opencode；.json 优先于 .jsonc），项目级缺失时兜底 */
+export const GLOBAL_CONFIG_FILE_NAMES = [
+    "opencode-metrics.json",
+    "opencode-metrics.jsonc",
+];
+/** 计算全局配置目录（用户 home 下 .config/opencode） */
+export function globalConfigDirectory() {
+    return path.join(os.homedir(), ".config", "opencode");
+}
 /**
- * 解析插件生效配置：项目 .opencode 目录下存在 opencode-metrics.json / .jsonc
- * （按此顺序查找，内容容忍 JSONC 注释与尾逗号）且为合法对象时完全接管
- * （opencode.json 内联第二参全部忽略），否则回退内联。
- * 文件缺失静默回退；内容非法记日志回退，不抛异常。
+ * 解析插件生效配置：优先级 项目 .opencode 独立文件 → 用户 home 全局文件 → 内联。
+ * 各级均按 .json → .jsonc 顺序查找，内容容忍 JSONC 注释与尾逗号；
+ * 命中且为合法对象即完全接管（opencode.json 内联第二参全部忽略）。
+ * 文件缺失静默落到下一级；内容非法记日志落下一级，不抛异常。
  *
  * @param projectDirectory opencode 启动的项目根（PluginInput.directory）
  * @param inlineOptions    opencode.json 插件内联第二参
+ * @param options          解析选项（globalConfigDir 可注入测试目录）
  * @returns                 生效配置与来源
  */
-export function resolvePluginConfig(projectDirectory, inlineOptions = {}) {
+export function resolvePluginConfig(projectDirectory, inlineOptions = {}, options = {}) {
     if (!projectDirectory)
         return { config: inlineOptions, source: "inline" };
-    let configPath = "";
-    let raw;
-    for (const name of CONFIG_FILE_NAMES) {
-        const candidate = path.join(projectDirectory, name);
+    const globalDir = options.globalConfigDir ?? globalConfigDirectory();
+    const levels = [
+        { label: "file", base: projectDirectory, names: CONFIG_FILE_NAMES },
+        { label: "global", base: globalDir, names: GLOBAL_CONFIG_FILE_NAMES },
+    ];
+    for (const level of levels) {
+        const found = readFirstExisting(level.base, level.names);
+        if (!found)
+            continue;
+        const parsed = parseConfigFile(found.configPath, found.raw);
+        if (!parsed)
+            continue;
+        log.info("[Metrics] 使用独立配置文件", { configPath: found.configPath, level: level.label });
+        return { config: parsed, source: level.label };
+    }
+    return { config: inlineOptions, source: "inline" };
+}
+/**
+ * 按顺序查找首个存在的配置文件。
+ *
+ * @param baseDirectory 基准目录
+ * @param names         相对文件名列表（json 优先于 jsonc）
+ * @returns              首个命中的文件路径与原始内容；全部缺失返回 undefined
+ */
+function readFirstExisting(baseDirectory, names) {
+    for (const name of names) {
+        const candidate = path.join(baseDirectory, name);
         try {
-            raw = fs.readFileSync(candidate, "utf-8");
-            configPath = candidate;
-            break;
+            return { configPath: candidate, raw: fs.readFileSync(candidate, "utf-8") };
         }
         catch {
             // 该名字的文件不存在，尝试下一个
         }
     }
-    if (raw === undefined)
-        return { config: inlineOptions, source: "inline" };
+    return undefined;
+}
+/**
+ * 解析并校验配置文件内容，非法时记日志返回 null。
+ *
+ * @param configPath 文件绝对路径（日志定位用）
+ * @param raw        原始文本
+ * @returns           合法配置对象；非法返回 null
+ */
+function parseConfigFile(configPath, raw) {
     let parsed;
     try {
         parsed = JSON.parse(stripJsoncSyntax(raw));
     }
     catch (err) {
-        log.error("[Metrics] 配置文件内容非法，回退内联配置", { configPath, error: String(err) });
-        return { config: inlineOptions, source: "inline" };
+        log.error("[Metrics] 配置文件内容非法，回退下一级配置", { configPath, error: String(err) });
+        return null;
     }
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        log.error("[Metrics] 配置文件顶层必须是对象，回退内联配置", { configPath });
-        return { config: inlineOptions, source: "inline" };
+        log.error("[Metrics] 配置文件顶层必须是对象，回退下一级配置", { configPath });
+        return null;
     }
-    log.info("[Metrics] 使用独立配置文件", { configPath });
-    return { config: parsed, source: "file" };
+    return parsed;
 }
 /**
  * 去除 JSONC 语法（行注释 / 块注释 / 尾逗号），字符串内的 // 与 /* 原样保留。

package/dist/metrics/runtime.js

@@ -21,7 +21,11 @@ export function createMetricsRuntime(opts = {}) {
     const uploadManager = createUploadManager({
         config: opts.upload,
         dirs,
-        onBeforeArchive: () => eventLogger?.flush(),
+        onBeforeArchive: (sessionId) => {
+            eventLogger?.flush();
+            // 引擎快照即时落盘：包内快照为触发时刻终稿（而非落后 checkpoint 间隔的旧稿）
+            engine.flush(sessionId);
+        },
     });
     return {
         dirs,

package/dist/metrics/upload/agcUploader.d.ts

@@ -61,5 +61,11 @@ export declare function createAgcUploader(credentials: AgcCredentials): AgcUploa
  * @returns          缩写后的安全路径段
  */
 export declare function abbreviateAgentName(agentName: string): string;
+/**
+ * 组装云端对象路径前缀（含版本目录，双文件归拢其内）：
+ * YYYYMMDD/<projectName>-<sessionId>/<agent缩写>-<trigger>-v<n>/<agent缩写>-<trigger>-v<n>
+ * 日期目录取包创建日（createdAt）：重传不漂移到重传当天，失败保留目录与之同构。
+ */
+export declare function composeRemoteBase(uploadPackage: UploadPackage): string;
 /** 归档包云端对象完整路径（上传成功日志用） */
 export declare function remoteArchiveKey(uploadPackage: UploadPackage): string;

package/dist/metrics/upload/agcUploader.js

@@ -213,11 +213,12 @@ export function abbreviateAgentName(agentName) {
 /**
  * 组装云端对象路径前缀（含版本目录，双文件归拢其内）：
  * YYYYMMDD/<projectName>-<sessionId>/<agent缩写>-<trigger>-v<n>/<agent缩写>-<trigger>-v<n>
+ * 日期目录取包创建日（createdAt）：重传不漂移到重传当天，失败保留目录与之同构。
  */
-function composeRemoteBase(uploadPackage) {
-    const now = new Date();
+export function composeRemoteBase(uploadPackage) {
+    const created = new Date(uploadPackage.createdAt);
     const pad = (value) => String(value).padStart(2, "0");
-    const dateDirectory = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}`;
+    const dateDirectory = `${created.getFullYear()}${pad(created.getMonth() + 1)}${pad(created.getDate())}`;
     const fileBase = `${abbreviateAgentName(uploadPackage.agentName)}-${uploadPackage.trigger}-v${uploadPackage.sequence}`;
     return `${dateDirectory}/${uploadPackage.projectName}-${uploadPackage.sessionId}/${fileBase}/${fileBase}`;
 }

package/dist/metrics/upload/packageArchiver.d.ts

@@ -32,3 +32,18 @@ export interface ArchiveSessionOptions {
  * @returns        成功返回产物包信息；失败返回原因
  */
 export declare function archiveSessionPackage(options: ArchiveSessionOptions): Promise<ArchiveResult>;
+/** 单个 hap 文件的收集描述：归属根与根内相对路径（分隔符统一 /） */
+export interface HapFileRef {
+    root: string;
+    relativePath: string;
+    filePath: string;
+}
+/**
+ * 收集各产物根下 build 目录内的 .hap 产物包：普通区域跳过黑名单目录递归
+ * 下探，进入 build 目录后不再跳过（产物在 build 深层），仅收集 .hap 文件。
+ *
+ * @param roots     产物根绝对路径数组
+ * @param blacklist 额外黑名单（与默认合并）
+ * @returns          hap 文件描述数组（root 归属 + 根内相对路径）
+ */
+export declare function collectHapFiles(roots: string[], blacklist?: string[]): HapFileRef[];

package/dist/metrics/upload/packageArchiver.js

@@ -47,7 +47,22 @@ export async function archiveSessionPackage(options) {
         for (const logFile of collectEventLogs(sessionId, eventsDir)) {
             fs.copyFileSync(logFile, path.join(assemblyDir, "events", path.basename(logFile)));
         }
-        const { args, excludedAndroid } = buildTarArgs(tmpPath, assemblyDir, roots, options.blacklist ?? [], options.excludeAndroidProjects !== false);
+        const rootEntries = assignRootEntryNames(roots);
+        // hap 产物包独立收集：build 目录整体在 tar 黑名单中，hap 借道组装目录随包上传；
+        // 目标路径剥去 build 段（否则被 --exclude */build 连坐排除）
+        const hapFiles = collectHapFiles(roots, options.blacklist ?? []);
+        let hapBytes = 0;
+        for (const hap of hapFiles) {
+            const entry = rootEntries.find((candidate) => normalizeRootKey(candidate.root) === normalizeRootKey(hap.root));
+            if (!entry)
+                continue;
+            const targetRelative = hap.relativePath.replace(/(^|\/)build\//, "$1");
+            const target = path.join(assemblyDir, "hap", entry.entryName, ...targetRelative.split("/"));
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            fs.copyFileSync(hap.filePath, target);
+            hapBytes += fs.statSync(hap.filePath).size;
+        }
+        const { args, excludedAndroid } = buildTarArgs(tmpPath, assemblyDir, rootEntries, options.blacklist ?? [], options.excludeAndroidProjects !== false);
         const tarError = await runTar(args);
         if (tarError) {
             return fail("tar-failed", tarError);
@@ -62,7 +77,7 @@ export async function archiveSessionPackage(options) {
         // 快照单独一份（与包内时点一致）
         fs.copyFileSync(path.join(assemblyDir, "snapshot", `${sessionId}.json`), snapshotPath);
         const sha256 = await computeSha256(archivePath);
-        log.info("[Metrics] archived", { sessionId, trigger: triggerLabel, baseName, sizeBytes, excludedAndroid });
+        log.info("[Metrics] archived", { sessionId, trigger: triggerLabel, baseName, sizeBytes, excludedAndroid, hapCount: hapFiles.length, hapBytes });
         const uploadPackage = {
             sessionId,
             trigger: triggerLabel,
@@ -79,6 +94,8 @@ export async function archiveSessionPackage(options) {
             roots: [...roots],
             createdAt: Date.now(),
         };
+        // 元数据 sidecar：失败保留/启动补偿重建上传任务与云端路径的依据，终态时随双文件删除
+        fs.writeFileSync(path.join(stagingDir, `${baseName}.meta.json`), JSON.stringify(uploadPackage, null, 2));
         return { ok: true, package: uploadPackage };
     }
     catch (err) {
@@ -93,13 +110,10 @@ export async function archiveSessionPackage(options) {
             fs.rmSync(tmpPath, { force: true });
     }
 }
-/** 组装 tar 参数：黑名单排除 + 嵌套安卓工程剔除 + 恒含项 + 各 workspace 根（按 basename 入包，重名加序号后缀）；全部 --exclude 须在任何操作数之前（bsdtar 不解析操作数之后的选项） */
-function buildTarArgs(output, assemblyDir, roots, extraBlacklist, excludeAndroidProjects) {
-    const blacklist = [...DEFAULT_BLACKLIST, ...extraBlacklist];
-    const excludedAndroid = [];
-    // 根条目名先就位（重名加序号），安卓剔除以条目名锚定
+/** 分配根的包内条目名：默认取根 basename，重名追加序号后缀（大小写不敏感去重） */
+function assignRootEntryNames(roots) {
     const usedNames = new Set();
-    const rootEntries = roots.map((root) => {
+    return roots.map((root) => {
         let entryName = path.basename(path.resolve(root)) || "workspace";
         if (usedNames.has(entryName.toLowerCase())) {
             entryName = `${entryName}-${usedNames.size + 1}`;
@@ -107,6 +121,74 @@ function buildTarArgs(output, assemblyDir, roots, extraBlacklist, excludeAndroid
         usedNames.add(entryName.toLowerCase());
         return { root, entryName };
     });
+}
+/** 根路径归一化比较键（仅 Windows 大小写不敏感） */
+function normalizeRootKey(target) {
+    const resolved = path.resolve(target);
+    return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+/** hap 收集递归深度上限（build 目录内部层级防护） */
+const HAP_SCAN_DEPTH = 10;
+/**
+ * 收集各产物根下 build 目录内的 .hap 产物包：普通区域跳过黑名单目录递归
+ * 下探，进入 build 目录后不再跳过（产物在 build 深层），仅收集 .hap 文件。
+ *
+ * @param roots     产物根绝对路径数组
+ * @param blacklist 额外黑名单（与默认合并）
+ * @returns          hap 文件描述数组（root 归属 + 根内相对路径）
+ */
+export function collectHapFiles(roots, blacklist = []) {
+    const skipped = new Set([...DEFAULT_BLACKLIST, ...blacklist].map((name) => name.toLowerCase()));
+    const results = [];
+    for (const root of roots) {
+        walkForHap(path.resolve(root), path.resolve(root), 0, skipped, false, results);
+    }
+    return results;
+}
+/**
+ * 递归扫描 hap：普通区跳过黑名单目录，build 子树内全量下探收集 .hap 文件。
+ *
+ * @param current     当前扫描目录
+ * @param root        所属产物根（相对路径基准）
+ * @param depth       当前深度（防护上限）
+ * @param skipped     黑名单目录名集合（小写）
+ * @param insideBuild 当前是否已处于 build 子树内
+ * @param results     收集结果累加数组
+ */
+function walkForHap(current, root, depth, skipped, insideBuild, results) {
+    if (depth > HAP_SCAN_DEPTH)
+        return;
+    let entries;
+    try {
+        entries = fs.readdirSync(current, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const child = path.join(current, entry.name);
+        if (entry.isDirectory()) {
+            const isBuild = entry.name.toLowerCase() === "build";
+            if (insideBuild || isBuild) {
+                walkForHap(child, root, depth + 1, skipped, true, results);
+            }
+            else if (!skipped.has(entry.name.toLowerCase())) {
+                walkForHap(child, root, depth + 1, skipped, false, results);
+            }
+        }
+        else if (insideBuild && entry.name.toLowerCase().endsWith(".hap")) {
+            results.push({
+                root,
+                relativePath: path.relative(root, child).split(path.sep).join("/"),
+                filePath: child,
+            });
+        }
+    }
+}
+/** 组装 tar 参数：黑名单排除 + 嵌套安卓工程剔除 + 恒含项 + 各 workspace 根（按 basename 入包，重名加序号后缀）；全部 --exclude 须在任何操作数之前（bsdtar 不解析操作数之后的选项） */
+function buildTarArgs(output, assemblyDir, rootEntries, extraBlacklist, excludeAndroidProjects) {
+    const blacklist = [...DEFAULT_BLACKLIST, ...extraBlacklist];
+    const excludedAndroid = [];
     const args = ["-czf", output];
     for (const name of blacklist) {
         // 裸名匹配末段（GNU tar），*/名匹配任意深度（bsdtar）

package/dist/metrics/upload/scenarios.d.ts

@@ -1,5 +1,5 @@
 import type { ScenarioConfig } from "./types.js";
-/** 解析后的触发场景：label 用于文件命名，commands/events 为两类匹配源 */
+/** 解析后的触发场景：label 用于文件命名，commands/events/tools 为三类匹配源 */
 export interface ResolvedScenario {
     key: string;
     /** 命名标签（文件名 <sessionId>-<agentName>-<label>-v<n> 的一段） */
@@ -9,12 +9,25 @@ export interface ResolvedScenario {
     commandRegexes: RegExp[];
     /** 匹配的事件名（含特殊值 "dispose"，由管理器结束时触发） */
     events: string[];
+    /** 匹配的工具名（根会话直接调用的工具 completed/error 时触发） */
+    toolNames: string[];
 }
 /**
- * 合并内置场景与 opencode.json 配置：内置 key 深合并（label/commands/events 可覆盖、
- * enabled:false 可禁用），自定义 key 直接新增；非法正则跳过并记日志。
+ * 合并内置场景与 opencode.json 配置：内置 key 深合并（label/commands/events/tools
+ * 可覆盖、enabled:false 可禁用），自定义 key 直接新增；非法正则跳过并记日志。
  *
  * @param configs opencode.json upload.scenarios
  * @returns        全部场景（含禁用的，调用方按 enabled 过滤）
  */
 export declare function resolveScenarios(configs?: Record<string, ScenarioConfig>): ResolvedScenario[];
+/**
+ * 判定工具终态事件命中的场景：根会话直接调用的工具进入终态
+ * （completed/error）时命中其 toolNames；子代理嵌套调用不命中。
+ *
+ * @param scenarios    已解析场景（含禁用项，函数内过滤 enabled）
+ * @param tool         工具名
+ * @param status       工具状态（仅 completed/error 视为终态）
+ * @param isRootSession 事件原始会话是否根会话（未被子代理映射）
+ * @returns             命中的启用场景列表
+ */
+export declare function matchToolScenarios(scenarios: ResolvedScenario[], tool: string, status: string, isRootSession: boolean): ResolvedScenario[];

package/dist/metrics/upload/scenarios.js

@@ -1,12 +1,16 @@
 import { log } from "../../shared/log.js";
 /** 内置默认场景（opencode.json scenarios 按 key 合并覆盖） */
 const BUILTIN_SCENARIOS = {
-    "session-end": { label: "session-end", events: ["dispose", "session.deleted"] },
+    "session-end": {
+        label: "session-end",
+        events: ["dispose", "session.deleted"],
+        tools: ["task"],
+    },
     "git-commit": { label: "git", commands: ["\\bgit\\s+commit\\b"] },
 };
 /**
- * 合并内置场景与 opencode.json 配置：内置 key 深合并（label/commands/events 可覆盖、
- * enabled:false 可禁用），自定义 key 直接新增；非法正则跳过并记日志。
+ * 合并内置场景与 opencode.json 配置：内置 key 深合并（label/commands/events/tools
+ * 可覆盖、enabled:false 可禁用），自定义 key 直接新增；非法正则跳过并记日志。
  *
  * @param configs opencode.json upload.scenarios
  * @returns        全部场景（含禁用的，调用方按 enabled 过滤）
@@ -37,7 +41,25 @@ export function resolveScenarios(configs) {
             enabled: config.enabled !== false,
             commandRegexes,
             events: config.events ?? [],
+            toolNames: config.tools ?? [],
         });
     }
     return result;
 }
+/**
+ * 判定工具终态事件命中的场景：根会话直接调用的工具进入终态
+ * （completed/error）时命中其 toolNames；子代理嵌套调用不命中。
+ *
+ * @param scenarios    已解析场景（含禁用项，函数内过滤 enabled）
+ * @param tool         工具名
+ * @param status       工具状态（仅 completed/error 视为终态）
+ * @param isRootSession 事件原始会话是否根会话（未被子代理映射）
+ * @returns             命中的启用场景列表
+ */
+export function matchToolScenarios(scenarios, tool, status, isRootSession) {
+    if (!isRootSession || !tool)
+        return [];
+    if (status !== "completed" && status !== "error")
+        return [];
+    return scenarios.filter((scenario) => scenario.enabled && scenario.toolNames.includes(tool));
+}

package/dist/metrics/upload/types.d.ts

@@ -25,6 +25,8 @@ export interface ScenarioConfig {
     commands?: string[];
     /** TRACKED_EVENT_TYPES 内事件名 */
     events?: string[];
+    /** 工具名匹配器：根会话直接调用的工具进入终态（completed/error）时触发 */
+    tools?: string[];
 }
 /** 上传通道配置（当前仅 agc） */
 export interface UploaderConfig {
@@ -37,6 +39,24 @@ export interface UploadRetryConfig {
     maxAttempts?: number;
     backoffMs?: number;
 }
+/** 失败保留与启动补偿重传：失败包移入 failed/（与云端同构目录），启动时重传 */
+export interface RetryRescueConfig {
+    /** 缺省 true：失败保留 + 启动补偿；false 时失败即删（旧行为） */
+    enabled?: boolean;
+    /** failed/ 内包保留天数，过期删除（缺省 7） */
+    retentionDays?: number;
+    /** failed/ 总量字节上限，超限从最旧删除（缺省 1GB） */
+    maxFailedBytes?: number;
+}
+/** 孤儿快照补传：宿主死亡导致终态触发从未发生时，启动后按快照年龄补打 session-end 包 */
+export interface OrphanRescueConfig {
+    /** 缺省 true：启用孤儿快照补传 */
+    enabled?: boolean;
+    /** 快照静默多久视为孤儿（小时，缺省 24；活跃会话快照始终排除） */
+    idleHours?: number;
+    /** 快照最大补传年龄（天，缺省 7，超过视为陈旧放弃） */
+    maxAgeDays?: number;
+}
 /** opencode.json 的 upload 配置整块（§13.8） */
 export interface UploadConfig {
     /** 上传总开关，缺省 true（装上即上传）；false 显式关闭 */
@@ -51,6 +71,8 @@ export interface UploadConfig {
     /** 单包体积上限，超限该次标 failed */
     maxArtifactBytes?: number;
     retry?: UploadRetryConfig;
+    retryRescue?: RetryRescueConfig;
+    orphanRescue?: OrphanRescueConfig;
 }
 /** 暂存目录内的单个上传文件（归档包或快照） */
 export interface UploadPackageFile {

package/dist/metrics/upload/types.js

@@ -16,7 +16,7 @@ export function sanitizeNameSegment(name, fallback = "project") {
 }
 // ─── 默认值（§13.4 / §13.5） ─────────────────────────────────────────────────
 /** 目录内存在这些子目录 → 该目录是产物根 */
-export const DEFAULT_DIR_MARKERS = [".harmonyos", ".mr"];
+export const DEFAULT_DIR_MARKERS = [".harmonyos", ".migration"];
 /** 目录内存在这些文件/目录 → 该目录是产物根 */
 export const DEFAULT_FILE_MARKERS = [
     "oh-package.json5",

package/dist/metrics/upload/uploadManager.d.ts

@@ -4,8 +4,8 @@ export interface UploadManagerOptions {
     config?: UploadConfig;
     /** 实例目录（metricsDir/eventsDir/uploadStagingDir） */
     dirs: MetricsDirs;
-    /** 归档前回调（事件日志冲刷落盘，消除缓冲延迟导致的空 events 竞态） */
-    onBeforeArchive?: () => void;
+    /** 归档前回调（事件日志冲刷 + 引擎快照落盘，消除缓冲延迟导致的旧快照/空 events 竞态） */
+    onBeforeArchive?: (sessionId: string) => void;
 }
 export interface UploadManager {
     /** 旁路观察事件：收集证据 + 场景命中判定（须在 engine.ingest 之后调用，保证快照先落盘） */
@@ -23,3 +23,30 @@ export interface UploadManager {
  * @param options 配置与目录
  */
 export declare function createUploadManager(options: UploadManagerOptions): UploadManager | null;
+/**
+ * 记录会话终态包已成功上云。
+ * 快照原件（metrics/<sessionId>.json）会永久保留为本地记录，
+ * "已传标记"才是孤儿扫描防重复上传的依据。
+ */
+export declare function markSessionUploaded(metricsDir: string, sessionId: string): void;
+/** 会话终态包是否已成功上云 */
+export declare function isSessionUploaded(metricsDir: string, sessionId: string): boolean;
+/** 孤儿快照候选：从磁盘快照恢复的会话证据 */
+export interface OrphanSnapshot {
+    sessionId: string;
+    filePath: string;
+    workingDirectory: string;
+    agentName: string;
+    startedAt: number;
+}
+/**
+ * 扫描目录选出孤儿快照候选：mtime 静默 [idleMs, maxAgeMs] 且不在活跃集的快照。
+ * 上传成功后快照即被删除，"文件仍在"天然等价于"终态未传出"。
+ *
+ * @param metricsDir 快照目录
+ * @param idleMs     静默下限（毫秒）
+ * @param maxAgeMs   年龄上限（毫秒）
+ * @param isActive   活跃会话判定（IO 前后各查一次，防竞态）
+ * @returns           候选列表（无法解析的快照跳过）
+ */
+export declare function selectOrphanSnapshots(metricsDir: string, idleMs: number, maxAgeMs: number, isActive: (sessionId: string) => boolean): Promise<OrphanSnapshot[]>;