opencode-metrics-plugin 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 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
 
 ## 快速开始
@@ -57,10 +58,11 @@
 默认开启（`upload.enabled: false` 可关）：
 
 - **触发场景**：bash 执行 `git commit`（label=`git`）、会话结束/插件退出（label=`session-end`）；可自定义场景（命令正则或事件名）
-- **打包内容**：时点快照 JSON + 事件日志（恒含）+ 会话动过的工作区产物根（鸿蒙工程标记探测，≤3 个）
+- **打包内容**：时点快照 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，从最旧删）自动清理
 
 ## 输出目录
 
@@ -68,7 +70,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 +85,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 块
 
@@ -97,6 +99,7 @@
 | `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/ 总量上限（超限从最旧删） |
 
 ## 可编程 API
 
@@ -122,7 +125,7 @@ rt.engine.dispose()
 
 ```bash
 npm run typecheck   # tsc --noEmit
-npm test            # 冒烟测试（example/smoke.mts，53 断言）
+npm test            # 冒烟测试（example/smoke.mts，71 断言）
 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/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/types.d.ts

@@ -37,6 +37,15 @@ export interface UploadRetryConfig {
     maxAttempts?: number;
     backoffMs?: number;
 }
+/** 失败保留与启动补偿重传：失败包移入 failed/（与云端同构目录），启动时重传 */
+export interface RetryRescueConfig {
+    /** 缺省 true：失败保留 + 启动补偿；false 时失败即删（旧行为） */
+    enabled?: boolean;
+    /** failed/ 内包保留天数，过期删除（缺省 7） */
+    retentionDays?: number;
+    /** failed/ 总量字节上限，超限从最旧删除（缺省 1GB） */
+    maxFailedBytes?: number;
+}
 /** opencode.json 的 upload 配置整块（§13.8） */
 export interface UploadConfig {
     /** 上传总开关，缺省 true（装上即上传）；false 显式关闭 */
@@ -51,6 +60,7 @@ export interface UploadConfig {
     /** 单包体积上限，超限该次标 failed */
     maxArtifactBytes?: number;
     retry?: UploadRetryConfig;
+    retryRescue?: RetryRescueConfig;
 }
 /** 暂存目录内的单个上传文件（归档包或快照） */
 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.js

@@ -3,7 +3,7 @@ import * as path from "node:path";
 import { log } from "../../shared/log.js";
 import { EvidenceCollector, isPathInside, resolveAndroidProjectName, resolveWorkspaceRoots, } from "./workspaceResolver.js";
 import { archiveSessionPackage } from "./packageArchiver.js";
-import { createAgcUploader, defaultAgcConfigPath, loadAgcCredentials, remoteArchiveKey } from "./agcUploader.js";
+import { createAgcUploader, composeRemoteBase, defaultAgcConfigPath, loadAgcCredentials, remoteArchiveKey } from "./agcUploader.js";
 import { createUploadQueue } from "./uploadQueue.js";
 import { resolveScenarios } from "./scenarios.js";
 import { MAX_ROOTS } from "./types.js";
@@ -25,27 +25,62 @@ export function createUploadManager(options) {
     const uploader = createAgcUploader(credentialsResult.credentials);
     const scenarios = resolveScenarios(config.scenarios);
     const directories = options.dirs;
-    // 启动扫残留：上次进程未清理的暂存产物直接删除
-    sweepStagingDirectory(directories.uploadStagingDir);
+    // 失败保留与启动补偿配置（默认开启）
+    const rescueEnabled = config.retryRescue?.enabled !== false;
+    const retentionMs = (config.retryRescue?.retentionDays ?? 7) * 24 * 60 * 60 * 1000;
+    const maxFailedBytes = config.retryRescue?.maxFailedBytes ?? 1024 * 1024 * 1024;
+    // 启动扫残留：崩溃遗留的完整三件套移入 failed/（待重传），孤立文件删除；
+    // failed/ 存量先做过期/超量清理再重新入队补偿上传
     const queue = createUploadQueue({
         worker: (uploadPackage) => uploader.uploadPackage(uploadPackage),
         maxAttempts: config.retry?.maxAttempts,
         backoffMs: config.retry?.backoffMs,
         onSettled: (uploadPackage, ok, reason) => {
-            removeQuietly(uploadPackage.archive.filePath);
-            removeQuietly(uploadPackage.snapshot.filePath);
+            const metaPath = uploadPackage.archive.filePath.replace(/\.tar\.gz$/, ".meta.json");
             if (ok) {
+                removeQuietly(uploadPackage.archive.filePath);
+                removeQuietly(uploadPackage.snapshot.filePath);
+                removeQuietly(metaPath);
+                // 来自 failed/ 的补偿重传：清掉可能残留的空目录
+                removeEmptyDirsUp(path.dirname(uploadPackage.archive.filePath), path.join(directories.uploadStagingDir, "failed"));
                 log.info("[Metrics] 上传完成", {
                     sessionId: uploadPackage.sessionId,
                     fileName: uploadPackage.archive.fileName,
                     remoteKey: remoteArchiveKey(uploadPackage),
                 });
+                return;
             }
-            else {
+            if (!rescueEnabled) {
+                removeQuietly(uploadPackage.archive.filePath);
+                removeQuietly(uploadPackage.snapshot.filePath);
+                removeQuietly(metaPath);
                 log.error("[Metrics] 上传失败（暂存已清理）", { sessionId: uploadPackage.sessionId, reason: reason ?? "" });
+                return;
+            }
+            const atStagingTop = path.resolve(path.dirname(uploadPackage.archive.filePath)) === path.resolve(directories.uploadStagingDir);
+            if (atStagingTop) {
+                const failedDir = movePackageIntoFailed(directories.uploadStagingDir, uploadPackage, metaPath);
+                log.error("[Metrics] 上传失败（已保留至 failed 目录，下次启动重传）", {
+                    sessionId: uploadPackage.sessionId,
+                    reason: reason ?? "",
+                    failedDir,
+                });
+            }
+            else {
+                // 补偿重传仍失败：原地保留，下次启动再试
+                log.error("[Metrics] 补偿重传仍失败（继续保留待下次）", { sessionId: uploadPackage.sessionId, reason: reason ?? "" });
             }
         },
     });
+    const rescued = [
+        ...sweepStagingDirectory(directories.uploadStagingDir, rescueEnabled),
+        ...collectFailedPackages(directories.uploadStagingDir, retentionMs, maxFailedBytes),
+    ];
+    if (rescued.length > 0) {
+        log.info("[Metrics] 启动补偿：历史失败/遗留包重新入队", { count: rescued.length });
+        for (const pkg of rescued)
+            queue.enqueue(pkg);
+    }
     const sessions = new Map();
     const childToParent = new Map();
     const completedBashCalls = new Set();
@@ -55,7 +90,7 @@ export function createUploadManager(options) {
     function getOrCreateEvidence(sessionId) {
         let entry = sessions.get(sessionId);
         if (!entry) {
-            entry = { collector: new EvidenceCollector(), agentName: "", workingDirectory: "" };
+            entry = { collector: new EvidenceCollector(), agentName: "", workingDirectory: "", startedAt: Date.now() };
             sessions.set(sessionId, entry);
         }
         return entry;
@@ -67,13 +102,15 @@ export function createUploadManager(options) {
      * @param triggerLabel 场景命名标签
      */
     async function triggerUpload(sessionId, triggerLabel) {
-        const evidence = sessions.get(sessionId) ?? { collector: new EvidenceCollector(), agentName: "", workingDirectory: "" };
+        const evidence = sessions.get(sessionId) ??
+            { collector: new EvidenceCollector(), agentName: "", workingDirectory: "", startedAt: Date.now() };
         const seeds = evidence.collector.seeds();
         const { directRoots, extraMarkers } = collectArtifactRules(seeds, evidence.workingDirectory, config.appendArtifacts ?? []);
         const detectedRoots = resolveWorkspaceRoots(seeds, {
             extraDirMarkers: extraMarkers.extraDirMarkers,
             extraFileMarkers: extraMarkers.extraFileMarkers,
             excludeAndroidProjects: config.excludeAndroidProjects,
+            sessionStartedAt: evidence.startedAt,
         });
         const roots = dedupePaths([...detectedRoots, ...directRoots]).slice(0, MAX_ROOTS);
         const projectName = resolveAndroidProjectName(seeds, {
@@ -225,12 +262,41 @@ function dedupePaths(paths) {
     }
     return result;
 }
-/** 启动清扫暂存目录：删除上次进程遗留的产物与组装目录 */
-function sweepStagingDirectory(stagingDir) {
+/**
+ * 启动清扫暂存目录顶层：崩溃遗留的完整三件套（tar.gz + json + meta.json）
+ * 移入 failed/ 同构目录并入队重传；孤立文件与组装目录直接删除。
+ *
+ * @param stagingDir    暂存目录
+ * @param rescueEnabled 失败保留开关（false 时完整三件套也直接删除，旧行为）
+ * @returns             可补偿重传的包列表（顶层遗留部分）
+ */
+function sweepStagingDirectory(stagingDir, rescueEnabled) {
+    const rescued = [];
     try {
+        const entries = fs.readdirSync(stagingDir);
+        const names = new Set(entries);
+        const handled = new Set(["failed"]);
         let removed = 0;
-        for (const entry of fs.readdirSync(stagingDir)) {
-            if (entry.endsWith(".tar.gz") || entry.endsWith(".json") || entry.startsWith(".assembly-")) {
+        for (const entry of entries) {
+            if (handled.has(entry))
+                continue;
+            if (entry.endsWith(".tar.gz")) {
+                const base = entry.slice(0, -".tar.gz".length);
+                const pkg = rescueEnabled ? loadIntactPackage(stagingDir, base, names) : undefined;
+                if (pkg) {
+                    movePackageIntoFailed(stagingDir, pkg, path.join(stagingDir, `${base}.meta.json`));
+                    rescued.push(pkg);
+                }
+                else {
+                    fs.rmSync(path.join(stagingDir, entry), { force: true });
+                    removed++;
+                }
+                handled.add(entry);
+                handled.add(`${base}.json`);
+                handled.add(`${base}.meta.json`);
+                continue;
+            }
+            if (entry.endsWith(".json") || entry.startsWith(".assembly-")) {
                 fs.rmSync(path.join(stagingDir, entry), { recursive: true, force: true });
                 removed++;
             }
@@ -241,6 +307,157 @@ function sweepStagingDirectory(stagingDir) {
     catch {
         // 目录不存在：无需处理
     }
+    return rescued;
+}
+/**
+ * 读取暂存顶层完整三件套并重建上传包（meta 反序列化 + 双文件在位校验）。
+ *
+ * @param stagingDir 暂存目录
+ * @param base       包基名（不含后缀）
+ * @param names      顶层文件名集合
+ * @returns           完整时返回包；任何缺失/损坏返回 undefined
+ */
+function loadIntactPackage(stagingDir, base, names) {
+    const jsonName = `${base}.json`;
+    const metaName = `${base}.meta.json`;
+    if (!names.has(jsonName) || !names.has(metaName))
+        return undefined;
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(stagingDir, metaName), "utf-8"));
+        if (pkg?.archive?.fileName !== `${base}.tar.gz` || pkg?.snapshot?.fileName !== jsonName)
+            return undefined;
+        pkg.archive.filePath = path.join(stagingDir, pkg.archive.fileName);
+        pkg.snapshot.filePath = path.join(stagingDir, pkg.snapshot.fileName);
+        if (!fs.existsSync(pkg.archive.filePath) || !fs.existsSync(pkg.snapshot.filePath))
+            return undefined;
+        return pkg;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 计算包在 failed/ 下的落位目录（与云端对象路径同构，便于查找与手动上传）：
+ * failed/YYYYMMDD/<projectName>-<sessionId>/<agent缩写>-<trigger>-v<n>/
+ */
+function failedDirFor(stagingDir, pkg) {
+    const segments = composeRemoteBase(pkg).split("/");
+    segments.pop();
+    return path.join(stagingDir, "failed", ...segments);
+}
+/**
+ * 把包的双文件与 meta 移入 failed/ 同构目录（同盘 rename）。
+ *
+ * @param stagingDir 暂存目录
+ * @param pkg        上传包
+ * @param metaPath   meta 文件当前路径
+ * @returns           落位目录
+ */
+function movePackageIntoFailed(stagingDir, pkg, metaPath) {
+    const targetDir = failedDirFor(stagingDir, pkg);
+    fs.mkdirSync(targetDir, { recursive: true });
+    pkg.archive.filePath = renameInto(pkg.archive.filePath, path.join(targetDir, pkg.archive.fileName));
+    pkg.snapshot.filePath = renameInto(pkg.snapshot.filePath, path.join(targetDir, pkg.snapshot.fileName));
+    renameInto(metaPath, path.join(targetDir, path.basename(metaPath)));
+    return targetDir;
+}
+/** rename 到目标（已存在则先删）；返回目标路径 */
+function renameInto(source, target) {
+    try {
+        fs.rmSync(target, { force: true });
+        fs.renameSync(source, target);
+    }
+    catch {
+        // 移动失败：文件留在原处，下次启动清扫兜底
+    }
+    return target;
+}
+/**
+ * 收集 failed/ 存量包：先做过期（retentionMs）与总量（maxFailedBytes，从最旧删起）
+ * 清理，再把完整包重建（filePath 重指 failed/ 内）返回入队。
+ *
+ * @param stagingDir     暂存目录
+ * @param retentionMs    保留时长（毫秒）
+ * @param maxFailedBytes 总量字节上限
+ * @returns              可重传的包列表
+ */
+function collectFailedPackages(stagingDir, retentionMs, maxFailedBytes) {
+    const failedRoot = path.join(stagingDir, "failed");
+    if (!fs.existsSync(failedRoot))
+        return [];
+    const packages = [];
+    const walk = (dir, depth) => {
+        if (depth > 4)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const child = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(child, depth + 1);
+                continue;
+            }
+            if (!entry.name.endsWith(".meta.json"))
+                continue;
+            try {
+                const pkg = JSON.parse(fs.readFileSync(child, "utf-8"));
+                const pkgDir = path.dirname(child);
+                pkg.archive.filePath = path.join(pkgDir, pkg.archive.fileName);
+                pkg.snapshot.filePath = path.join(pkgDir, pkg.snapshot.fileName);
+                if (!fs.existsSync(pkg.archive.filePath) || !fs.existsSync(pkg.snapshot.filePath)) {
+                    fs.rmSync(pkgDir, { recursive: true, force: true });
+                    continue;
+                }
+                pkg.archive.sizeBytes = fs.statSync(pkg.archive.filePath).size;
+                pkg.snapshot.sizeBytes = fs.statSync(pkg.snapshot.filePath).size;
+                packages.push({ pkg, dir: pkgDir, size: pkg.archive.sizeBytes + pkg.snapshot.sizeBytes, createdAt: pkg.createdAt ?? 0 });
+            }
+            catch {
+                // meta 损坏：整目录删除，防止永久残留
+                fs.rmSync(path.dirname(child), { recursive: true, force: true });
+            }
+        }
+    };
+    walk(failedRoot, 0);
+    const now = Date.now();
+    const survivors = [];
+    let totalBytes = 0;
+    let removed = 0;
+    for (const item of packages.sort((a, b) => a.createdAt - b.createdAt)) {
+        if (now - item.createdAt > retentionMs || totalBytes + item.size > maxFailedBytes) {
+            fs.rmSync(item.dir, { recursive: true, force: true });
+            removeEmptyDirsUp(path.dirname(item.dir), failedRoot);
+            removed++;
+            continue;
+        }
+        totalBytes += item.size;
+        survivors.push(item);
+    }
+    if (removed > 0)
+        log.info("[Metrics] failed 目录清理（过期/超量）", { stagingDir, removed });
+    removeEmptyDirsUp(failedRoot, failedRoot);
+    return survivors.map((item) => item.pkg);
+}
+/** 自下而上删除空目录（直到 root，含 root 本身可删） */
+function removeEmptyDirsUp(directory, root) {
+    let current = path.resolve(directory);
+    const top = path.resolve(root);
+    while (current.startsWith(top)) {
+        try {
+            fs.rmdirSync(current);
+        }
+        catch {
+            return;
+        }
+        if (current === top)
+            return;
+        current = path.dirname(current);
+    }
 }
 function removeQuietly(filePath) {
     try {

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

@@ -30,6 +30,8 @@ export interface ResolveRootsOptions {
     extraFileMarkers?: string[];
     /** 剔除安卓工程根（缺省 true） */
     excludeAndroidProjects?: boolean;
+    /** 会话开始时间戳（毫秒）；提供时启用兄弟鸿蒙工程探测（mtime 时间窗防邻居混入） */
+    sessionStartedAt?: number;
 }
 /**
  * 判断目录是否为安卓工程：统计 gradle 构建信号（settings.gradle、gradlew、

package/dist/metrics/upload/workspaceResolver.js

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { DEFAULT_DIR_MARKERS, DEFAULT_FILE_MARKERS, MAX_PROBE_DEPTH, MAX_ROOTS, sanitizeNameSegment, } from "./types.js";
+import { DEFAULT_BLACKLIST, DEFAULT_DIR_MARKERS, DEFAULT_FILE_MARKERS, MAX_PROBE_DEPTH, MAX_ROOTS, sanitizeNameSegment, } from "./types.js";
 /**
  * 会话证据收集器：旁路记录 write/edit 的文件路径与 bash 的工作目录、命令路径线索。
  * 触发上传时用这些路径推断产物根。
@@ -87,6 +87,86 @@ export function looksLikeAndroidProject(directory) {
 function hasHarmonyProjectMarkers(directory) {
     return ["oh-package.json5", "build-profile.json5", "hvigorfile.ts", "AppScope"].some((marker) => fs.existsSync(path.join(directory, marker)));
 }
+/** 安卓根内可直接提升为产物根的工作区目录名（droid2hmos 的 .migration 与转换工具的 .harmonyos） */
+const HARMONY_WORKSPACE_DIRS = [".migration", ".harmonyos"];
+/** 容器化降级扫描深度：安卓根内向内找鸿蒙子根的最大层数 */
+const NESTED_SCAN_DEPTH = 2;
+/**
+ * 在安卓工程根内部收集鸿蒙产物根：BFS 扫描（最多 NESTED_SCAN_DEPTH 层，
+ * 跳过黑名单目录），子目录含鸿蒙工程标记、或为 .migration/.harmonyos
+ * 工作区目录时提升为产物根；命中后不再深入该子树。
+ *
+ * @param androidRoot 安卓工程根绝对路径
+ * @returns           提升的鸿蒙产物根数组（空数组 = 纯安卓工程，整体丢弃）
+ */
+function findNestedHarmonyRoots(androidRoot) {
+    const found = [];
+    const skipped = new Set(DEFAULT_BLACKLIST.map((name) => name.toLowerCase()));
+    const queue = [{ directory: androidRoot, depth: 0 }];
+    while (queue.length > 0) {
+        const { directory, depth } = queue.shift();
+        let entries;
+        try {
+            entries = fs.readdirSync(directory, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || skipped.has(entry.name.toLowerCase()))
+                continue;
+            const child = path.join(directory, entry.name);
+            if (HARMONY_WORKSPACE_DIRS.includes(entry.name) || hasHarmonyProjectMarkers(child)) {
+                found.push(child);
+                continue;
+            }
+            if (depth + 1 < NESTED_SCAN_DEPTH) {
+                queue.push({ directory: child, depth: depth + 1 });
+            }
+        }
+    }
+    return found;
+}
+/**
+ * 在安卓工程根的同级目录探测兄弟鸿蒙工程：扫描父目录一级，子目录含鸿蒙
+ * 工程标记、且目录 mtime 不早于会话开始时间（本会话内被写入，防邻居旧
+ * 工程混入）时提升为产物根。
+ *
+ * @param androidRoot      安卓工程根绝对路径
+ * @param sessionStartedAt 会话开始时间戳（毫秒）
+ * @returns                提升的兄弟鸿蒙产物根数组
+ */
+function findSiblingHarmonyRoots(androidRoot, sessionStartedAt) {
+    const parent = path.dirname(path.resolve(androidRoot));
+    const selfKey = normalizeKey(androidRoot);
+    let entries;
+    try {
+        entries = fs.readdirSync(parent, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const entry of entries) {
+        // 隐藏目录（.git/.idea 等）不作为工程候选
+        if (!entry.isDirectory() || entry.name.startsWith("."))
+            continue;
+        const sibling = path.join(parent, entry.name);
+        if (normalizeKey(sibling) === selfKey)
+            continue;
+        if (!hasHarmonyProjectMarkers(sibling))
+            continue;
+        try {
+            if (fs.statSync(sibling).mtimeMs < sessionStartedAt)
+                continue;
+        }
+        catch {
+            continue;
+        }
+        found.push(sibling);
+    }
+    return found;
+}
 /**
  * 从证据路径推断产物根：自每条证据所在目录向上逐级探测标记（最多 5 层），
  * 目录内存在任一标记即记为根；安卓工程根（自身无鸿蒙工程标记）先剔除，
@@ -111,6 +191,11 @@ export function resolveWorkspaceRoots(seeds, options) {
             if (markers.some((marker) => fs.existsSync(path.join(current, marker)))) {
                 found.push(current);
             }
+            else if (looksLikeAndroidProject(current)) {
+                // 无标记的安卓根也纳入候选：由剔除分支做容器化降级
+                // （向内提升鸿蒙子根/工作区、按时间窗探测兄弟工程）
+                found.push(current);
+            }
             const parent = path.dirname(current);
             if (parent === current)
                 break;
@@ -119,7 +204,20 @@ export function resolveWorkspaceRoots(seeds, options) {
     }
     let candidates = dedupeRoots(found);
     if (options?.excludeAndroidProjects !== false) {
-        candidates = candidates.filter((root) => !looksLikeAndroidProject(root) || hasHarmonyProjectMarkers(root));
+        const kept = [];
+        for (const root of candidates) {
+            if (!looksLikeAndroidProject(root) || hasHarmonyProjectMarkers(root)) {
+                kept.push(root);
+                continue;
+            }
+            // 安卓根容器化降级：不整体丢弃，向内收集鸿蒙子根/工作区，
+            // 并按会话时间窗向外探测兄弟鸿蒙工程（防邻居旧工程混入）
+            kept.push(...findNestedHarmonyRoots(root));
+            if (options?.sessionStartedAt !== undefined) {
+                kept.push(...findSiblingHarmonyRoots(root, options.sessionStartedAt));
+            }
+        }
+        candidates = dedupeRoots(kept);
     }
     return limitRoots(mergeNestedRoots(candidates));
 }

package/dist/shared/log.d.ts

@@ -1,7 +1,12 @@
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
 export declare function setLogLevel(level: LogLevel): void;
-/** 设置运行日志落盘文件；传 null 关闭文件输出（仅 console）。 */
+/** 设置运行日志基准文件；实际写入 <所在目录>/log/plugin/YYYYMMDD.log；传 null 关闭文件输出（仅 console）。 */
 export declare function setLogFile(file: string | null): void;
+/**
+ * 清理过期运行日志：只删基准同目录 log/plugin/ 下严格 YYYYMMDD.log
+ * 且 mtime 超过保留天数的文件；其余任何文件一概不碰。幂等，可反复调用。
+ */
+export declare function cleanupOldLogFiles(): void;
 export declare function flushLogs(): void;
 export declare const log: {
     debug(...parts: unknown[]): void;

package/dist/shared/log.js

@@ -8,10 +8,52 @@ export function setLogLevel(level) {
 }
 const DEFAULT_LOG_FILE = path.join(envPaths('opencode-metrics-plugin', { suffix: '' }).log, 'plugin.log');
 let logFile = DEFAULT_LOG_FILE;
-/** 设置运行日志落盘文件；传 null 关闭文件输出（仅 console）。 */
+/** 设置运行日志基准文件；实际写入 <所在目录>/log/plugin/YYYYMMDD.log；传 null 关闭文件输出（仅 console）。 */
 export function setLogFile(file) {
     logFile = file;
+    resolvedFile = null;
 }
+// ─── 按日期归档（0.3.2）：进程首写时按当天定死目标文件，跨午夜不切换 ───
+/** 运行日志保留天数，超期文件启动清理时删除 */
+const MAX_AGE_DAYS = 30;
+/** 缓存的目标文件（基准 + log/plugin/日期 推导）；null 表示尚未解析或未启用 */
+let resolvedFile = null;
+/**
+ * 解析当天目标日志文件：<基准所在目录>/log/plugin/YYYYMMDD.log。
+ * 进程生命周期内锁定（跨午夜不切换），下次进程自然写新日期文件。
+ */
+function resolveTargetFile(base) {
+    const now = new Date();
+    const pad = (n) => String(n).padStart(2, '0');
+    const date = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}`;
+    return path.join(path.dirname(base), 'log', 'plugin', `${date}.log`);
+}
+/**
+ * 清理过期运行日志：只删基准同目录 log/plugin/ 下严格 YYYYMMDD.log
+ * 且 mtime 超过保留天数的文件；其余任何文件一概不碰。幂等，可反复调用。
+ */
+export function cleanupOldLogFiles() {
+    if (logFile == null)
+        return;
+    try {
+        const dir = path.join(path.dirname(logFile), 'log', 'plugin');
+        if (!fs.existsSync(dir))
+            return;
+        const maxAgeMs = MAX_AGE_DAYS * 24 * 60 * 60 * 1000;
+        for (const entry of fs.readdirSync(dir)) {
+            if (!/^\d{8}\.log$/.test(entry))
+                continue;
+            const full = path.join(dir, entry);
+            try {
+                if (Date.now() - fs.statSync(full).mtimeMs > maxAgeMs)
+                    fs.unlinkSync(full);
+            }
+            catch { }
+        }
+    }
+    catch { }
+}
+setImmediate(cleanupOldLogFiles);
 let buffer = [];
 let flushTimer = null;
 const FLUSH_INTERVAL_MS = 500;
@@ -20,8 +62,10 @@ function writeLine(line) {
     if (logFile == null)
         return;
     try {
-        fs.mkdirSync(path.dirname(logFile), { recursive: true });
-        fs.appendFileSync(logFile, line + '\n');
+        if (resolvedFile == null)
+            resolvedFile = resolveTargetFile(logFile);
+        fs.mkdirSync(path.dirname(resolvedFile), { recursive: true });
+        fs.appendFileSync(resolvedFile, line + '\n');
     }
     catch {
         // 文件不可写时回退 console，避免静默吞日志

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-metrics-plugin",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "opencode plugin: auto-records every session's metrics (tokens/rounds/steps/sub-agents/hvigor builds) to snapshot JSON. Zero DB, zero config. Pair with session-viewer for visualization.",
   "type": "module",
   "license": "MIT",