opencode-metrics-plugin 0.2.1 → 0.3.0

package/dist/metrics/upload/types.js

@@ -0,0 +1,43 @@
+// ─── 上传子系统共享类型与默认值（DESIGN.md §13） ───────────────────────────────
+/**
+ * 清洗名称为安全的路径段：非法字符（含空格）替换为 "-"，保留中文与内部点号，
+ * 首尾修剪 "." "-"，结果为空时返回 fallback。
+ *
+ * @param name     原始名称
+ * @param fallback 清洗后为空时的替代值
+ * @returns         可安全用于文件名/云端路径的段
+ */
+export function sanitizeNameSegment(name, fallback = "project") {
+    const cleaned = name
+        .replace(/[\\/:*?"<>|\s]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^[.\-]+|[.\-]+$/g, "");
+    return cleaned || fallback;
+}
+// ─── 默认值（§13.4 / §13.5） ─────────────────────────────────────────────────
+/** 目录内存在这些子目录 → 该目录是产物根 */
+export const DEFAULT_DIR_MARKERS = [".harmonyos", ".mr"];
+/** 目录内存在这些文件/目录 → 该目录是产物根 */
+export const DEFAULT_FILE_MARKERS = [
+    "oh-package.json5",
+    "build-profile.json5",
+    "hvigorfile.ts",
+    "AppScope",
+];
+/** 打包排除的目录/文件名（按路径段匹配） */
+export const DEFAULT_BLACKLIST = [
+    "oh_modules",
+    "build",
+    ".hvigor",
+    ".cxx",
+    ".git",
+    "node_modules",
+    ".idea",
+    "local.properties",
+];
+/** 单包体积上限默认 500MB */
+export const DEFAULT_MAX_ARTIFACT_BYTES = 500 * 1024 * 1024;
+/** 自证据路径向上探测标记的最大层级 */
+export const MAX_PROBE_DEPTH = 5;
+/** 产物根数量上限 */
+export const MAX_ROOTS = 3;

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

@@ -0,0 +1,25 @@
+import type { MetricsDirs } from "../dirs.js";
+import type { UploadConfig } from "./types.js";
+export interface UploadManagerOptions {
+    config?: UploadConfig;
+    /** 实例目录（metricsDir/eventsDir/uploadStagingDir） */
+    dirs: MetricsDirs;
+    /** 归档前回调（事件日志冲刷落盘，消除缓冲延迟导致的空 events 竞态） */
+    onBeforeArchive?: () => void;
+}
+export interface UploadManager {
+    /** 旁路观察事件：收集证据 + 场景命中判定（须在 engine.ingest 之后调用，保证快照先落盘） */
+    observe(event: {
+        type: string;
+        properties?: Record<string, unknown>;
+    }): void;
+    /** 结束：对所有活跃会话触发 dispose 场景并排空队列（best-effort 10s） */
+    dispose(): Promise<void>;
+}
+/**
+ * 创建上传管理器：串联证据 → 根推断 → 打包 → 队列 → AGC 上传，
+ * 终态（成功/重试耗尽）删除暂存双文件。upload 未启用或凭证不可用时返回 null。
+ *
+ * @param options 配置与目录
+ */
+export declare function createUploadManager(options: UploadManagerOptions): UploadManager | null;

package/dist/metrics/upload/uploadManager.js

@@ -0,0 +1,252 @@
+import * as fs from "node:fs";
+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 { createUploadQueue } from "./uploadQueue.js";
+import { resolveScenarios } from "./scenarios.js";
+import { MAX_ROOTS } from "./types.js";
+/**
+ * 创建上传管理器：串联证据 → 根推断 → 打包 → 队列 → AGC 上传，
+ * 终态（成功/重试耗尽）删除暂存双文件。upload 未启用或凭证不可用时返回 null。
+ *
+ * @param options 配置与目录
+ */
+export function createUploadManager(options) {
+    const config = options.config ?? {};
+    if (config.enabled !== true)
+        return null;
+    const credentialsResult = loadAgcCredentials(config.uploader?.agcConfigPath ?? defaultAgcConfigPath());
+    if (!credentialsResult.ok) {
+        log.error("[Metrics] 上传未启用：凭证不可用", { reason: credentialsResult.reason });
+        return null;
+    }
+    const uploader = createAgcUploader(credentialsResult.credentials);
+    const scenarios = resolveScenarios(config.scenarios);
+    const directories = options.dirs;
+    // 启动扫残留：上次进程未清理的暂存产物直接删除
+    sweepStagingDirectory(directories.uploadStagingDir);
+    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);
+            if (ok) {
+                log.info("[Metrics] 上传完成", {
+                    sessionId: uploadPackage.sessionId,
+                    fileName: uploadPackage.archive.fileName,
+                    remoteKey: remoteArchiveKey(uploadPackage),
+                });
+            }
+            else {
+                log.error("[Metrics] 上传失败（暂存已清理）", { sessionId: uploadPackage.sessionId, reason: reason ?? "" });
+            }
+        },
+    });
+    const sessions = new Map();
+    const childToParent = new Map();
+    const completedBashCalls = new Set();
+    function resolveSessionId(rawId) {
+        return childToParent.get(rawId) ?? rawId;
+    }
+    function getOrCreateEvidence(sessionId) {
+        let entry = sessions.get(sessionId);
+        if (!entry) {
+            entry = { collector: new EvidenceCollector(), agentName: "", workingDirectory: "" };
+            sessions.set(sessionId, entry);
+        }
+        return entry;
+    }
+    /**
+     * 触发一次上传：根推断 + 包名推断 + 打包入队。
+     *
+     * @param sessionId    会话 id
+     * @param triggerLabel 场景命名标签
+     */
+    async function triggerUpload(sessionId, triggerLabel) {
+        const evidence = sessions.get(sessionId) ?? { collector: new EvidenceCollector(), agentName: "", workingDirectory: "" };
+        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,
+        });
+        const roots = dedupePaths([...detectedRoots, ...directRoots]).slice(0, MAX_ROOTS);
+        const projectName = resolveAndroidProjectName(seeds, {
+            fallbackDirectory: evidence.workingDirectory || roots[0] || "",
+        }) ?? "project";
+        options.onBeforeArchive?.();
+        const archiveResult = await archiveSessionPackage({
+            sessionId,
+            trigger: triggerLabel,
+            agentName: evidence.agentName || "agent",
+            projectName,
+            roots,
+            metricsDir: directories.metricsDir,
+            eventsDir: directories.eventsDir,
+            stagingDir: directories.uploadStagingDir,
+            blacklist: config.blacklist,
+            excludeAndroidProjects: config.excludeAndroidProjects,
+            maxArtifactBytes: config.maxArtifactBytes,
+        });
+        if (archiveResult.ok) {
+            queue.enqueue(archiveResult.package);
+        }
+    }
+    function observe(event) {
+        const props = event.properties;
+        if (!props)
+            return;
+        if (event.type === "session.created" || event.type === "session.updated") {
+            const info = props.info;
+            if (!info)
+                return;
+            const id = info.id;
+            if (!id)
+                return;
+            const parentID = info.parentID;
+            if (parentID)
+                childToParent.set(id, parentID);
+            const evidence = getOrCreateEvidence(resolveSessionId(id));
+            if (event.type === "session.created") {
+                const directory = info.directory;
+                if (directory)
+                    evidence.workingDirectory = directory;
+            }
+            else {
+                const agent = info.agent;
+                if (agent)
+                    evidence.agentName = agent;
+            }
+            return;
+        }
+        const rawSessionId = props.sessionID || props.info?.id;
+        if (!rawSessionId)
+            return;
+        const sessionId = resolveSessionId(rawSessionId);
+        const evidence = getOrCreateEvidence(sessionId);
+        if (event.type === "message.part.updated") {
+            const part = props.part;
+            if (!part || part.type !== "tool")
+                return;
+            const toolState = part.state;
+            if (toolState?.status !== "completed")
+                return;
+            const tool = part.tool;
+            const input = toolState.input;
+            const callID = part.callID;
+            if (tool === "write" || tool === "edit") {
+                const filePath = input?.filePath || input?.path;
+                if (filePath)
+                    evidence.collector.recordFileEdit(filePath);
+                return;
+            }
+            if (tool === "bash") {
+                const command = input?.command || "";
+                const workdir = input?.workdir;
+                evidence.collector.recordBash(workdir, command);
+                if (callID) {
+                    if (completedBashCalls.has(callID))
+                        return;
+                    completedBashCalls.add(callID);
+                }
+                for (const scenario of scenarios) {
+                    if (!scenario.enabled || scenario.commandRegexes.length === 0)
+                        continue;
+                    if (scenario.commandRegexes.some((regex) => regex.test(command))) {
+                        void triggerUpload(sessionId, scenario.label);
+                    }
+                }
+            }
+            return;
+        }
+        // 事件名场景命中（session.deleted 时 engine 已先落最终快照）
+        const matched = scenarios.some((scenario) => scenario.enabled && scenario.events.includes(event.type));
+        if (matched) {
+            void triggerUpload(sessionId, scenarios.find((scenario) => scenario.enabled && scenario.events.includes(event.type)).label);
+            if (event.type === "session.deleted")
+                sessions.delete(sessionId);
+        }
+    }
+    async function dispose() {
+        for (const scenario of scenarios) {
+            if (!scenario.enabled || !scenario.events.includes("dispose"))
+                continue;
+            for (const sessionId of [...sessions.keys()]) {
+                await triggerUpload(sessionId, scenario.label);
+            }
+        }
+        await queue.drain(10_000);
+    }
+    return { observe, dispose };
+}
+/** 应用 appendArtifacts 规则：marker 进探测扩展，显式路径按 matchBy 命中后作为直接根 */
+function collectArtifactRules(seeds, workingDirectory, rules) {
+    const extraDirMarkers = [];
+    const extraFileMarkers = [];
+    const directRoots = [];
+    for (const rule of rules) {
+        if (rule.dirMarkers)
+            extraDirMarkers.push(...rule.dirMarkers);
+        if (rule.fileMarkers)
+            extraFileMarkers.push(...rule.fileMarkers);
+        if (!rule.path)
+            continue;
+        const resolved = path.isAbsolute(rule.path)
+            ? rule.path
+            : workingDirectory
+                ? path.resolve(workingDirectory, rule.path)
+                : "";
+        if (!resolved)
+            continue;
+        const matchBy = rule.matchBy ?? "session-activity";
+        const hit = matchBy === "existence"
+            ? fs.existsSync(resolved)
+            : seeds.some((seed) => isPathInside(seed, resolved));
+        if (hit && fs.existsSync(resolved))
+            directRoots.push(resolved);
+    }
+    return { directRoots, extraMarkers: { extraDirMarkers, extraFileMarkers } };
+}
+/** 去重路径（Windows 大小写不敏感），保持首次出现顺序 */
+function dedupePaths(paths) {
+    const seen = new Set();
+    const result = [];
+    for (const target of paths) {
+        const key = process.platform === "win32" ? target.toLowerCase() : target;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(target);
+    }
+    return result;
+}
+/** 启动清扫暂存目录：删除上次进程遗留的产物与组装目录 */
+function sweepStagingDirectory(stagingDir) {
+    try {
+        let removed = 0;
+        for (const entry of fs.readdirSync(stagingDir)) {
+            if (entry.endsWith(".tar.gz") || entry.endsWith(".json") || entry.startsWith(".assembly-")) {
+                fs.rmSync(path.join(stagingDir, entry), { recursive: true, force: true });
+                removed++;
+            }
+        }
+        if (removed > 0)
+            log.info("[Metrics] 启动清扫暂存目录", { stagingDir, removed });
+    }
+    catch {
+        // 目录不存在：无需处理
+    }
+}
+function removeQuietly(filePath) {
+    try {
+        fs.rmSync(filePath, { force: true });
+    }
+    catch {
+        // 删除失败只记日志层面忽略
+    }
+}

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

@@ -0,0 +1,34 @@
+import type { UploadPackage } from "./types.js";
+/** 单次任务执行结果：失败时给出是否可重试（不可重试的失败直接终态） */
+export type UploadTaskOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    retryable: boolean;
+    reason: string;
+};
+export interface UploadQueueOptions {
+    /** 执行一次上传任务（一个任务对应两个文件，两者都成功才算成功） */
+    worker: (uploadPackage: UploadPackage) => Promise<UploadTaskOutcome>;
+    /** 单任务最大尝试次数（含首次），默认 5 */
+    maxAttempts?: number;
+    /** 退避基数（毫秒），实际延迟为 backoffMs × 4^(n-1)，默认 1000 */
+    backoffMs?: number;
+    /** 任务终态回调（成功或不可重试失败或重试耗尽）；调用方在此清理暂存双文件 */
+    onSettled?: (uploadPackage: UploadPackage, ok: boolean, reason?: string) => void;
+}
+export interface UploadQueue {
+    /** 入队一个上传任务，立即返回不阻塞 */
+    enqueue(uploadPackage: UploadPackage): void;
+    /** 等待队列排空（最多 timeoutMs），返回是否已排空 */
+    drain(timeoutMs: number): Promise<boolean>;
+    /** 当前待处理与进行中的任务数 */
+    pendingCount(): number;
+}
+/**
+ * 创建串行上传队列：任务按入队顺序逐个执行，
+ * 可重试失败按指数退避重试，终态（成功/失败）回调 onSettled。
+ *
+ * @param options 队列行为配置
+ */
+export declare function createUploadQueue(options: UploadQueueOptions): UploadQueue;

package/dist/metrics/upload/uploadQueue.js

@@ -0,0 +1,77 @@
+import { log } from "../../shared/log.js";
+/**
+ * 创建串行上传队列：任务按入队顺序逐个执行，
+ * 可重试失败按指数退避重试，终态（成功/失败）回调 onSettled。
+ *
+ * @param options 队列行为配置
+ */
+export function createUploadQueue(options) {
+    const maxAttempts = options.maxAttempts ?? 5;
+    const backoffMs = options.backoffMs ?? 1000;
+    const pending = [];
+    let processing = false;
+    async function runWithRetry(uploadPackage) {
+        let lastReason = "";
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            let outcome;
+            try {
+                outcome = await options.worker(uploadPackage);
+            }
+            catch (err) {
+                outcome = { ok: false, retryable: true, reason: String(err) };
+            }
+            if (outcome.ok) {
+                options.onSettled?.(uploadPackage, true);
+                return;
+            }
+            lastReason = outcome.reason;
+            if (!outcome.retryable) {
+                options.onSettled?.(uploadPackage, false, outcome.reason);
+                return;
+            }
+            if (attempt < maxAttempts) {
+                const delayMs = backoffMs * 4 ** (attempt - 1);
+                log.info("[Metrics] 上传任务将重试", {
+                    sessionId: uploadPackage.sessionId,
+                    attempt,
+                    delayMs,
+                    reason: outcome.reason,
+                });
+                await sleep(delayMs);
+            }
+        }
+        options.onSettled?.(uploadPackage, false, `重试耗尽(${maxAttempts}次): ${lastReason}`);
+    }
+    async function processPending() {
+        processing = true;
+        try {
+            while (pending.length > 0) {
+                const uploadPackage = pending.shift();
+                await runWithRetry(uploadPackage);
+            }
+        }
+        finally {
+            processing = false;
+        }
+    }
+    return {
+        enqueue(uploadPackage) {
+            pending.push(uploadPackage);
+            if (!processing)
+                void processPending();
+        },
+        async drain(timeoutMs) {
+            const deadline = Date.now() + timeoutMs;
+            while ((pending.length > 0 || processing) && Date.now() < deadline) {
+                await sleep(25);
+            }
+            return pending.length === 0 && !processing;
+        },
+        pendingCount() {
+            return pending.length + (processing ? 1 : 0);
+        },
+    };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

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

@@ -0,0 +1,75 @@
+/**
+ * 会话证据收集器：旁路记录 write/edit 的文件路径与 bash 的工作目录、命令路径线索。
+ * 触发上传时用这些路径推断产物根。
+ */
+export declare class EvidenceCollector {
+    private readonly filePaths;
+    private readonly directories;
+    /**
+     * 记录一次文件写入/编辑。
+     *
+     * @param filePath 被写入文件的绝对路径
+     */
+    recordFileEdit(filePath: string): void;
+    /**
+     * 记录一次 bash 调用：登记工作目录，并从命令行提取路径线索
+     * （cd <path>、git -C <path>、出现 hvigorw 时登记工作目录本身）。
+     *
+     * @param workdir 命令执行目录（可能为空）
+     * @param command 完整命令行
+     */
+    recordBash(workdir: string | undefined, command: string): void;
+    /** 全部证据路径（文件 + 目录），供根推断使用 */
+    seeds(): string[];
+    private resolveAgainst;
+}
+export interface ResolveRootsOptions {
+    /** 追加目录标记（与内置合并） */
+    extraDirMarkers?: string[];
+    /** 追加文件标记（与内置合并） */
+    extraFileMarkers?: string[];
+    /** 剔除安卓工程根（缺省 true） */
+    excludeAndroidProjects?: boolean;
+}
+/**
+ * 判断目录是否为安卓工程：统计 gradle 构建信号（settings.gradle、gradlew、
+ * app/build.gradle、根 build.gradle+app/、AndroidManifest+src/），
+ * 命中 2 个及以上即判定，避免单文件误判。
+ *
+ * @param directory 待判定目录
+ * @returns          是安卓工程返回 true
+ */
+export declare function looksLikeAndroidProject(directory: string): boolean;
+/**
+ * 从证据路径推断产物根：自每条证据所在目录向上逐级探测标记（最多 5 层），
+ * 目录内存在任一标记即记为根；安卓工程根（自身无鸿蒙工程标记）先剔除，
+ * 嵌套根归并到最外层，去重后最多 3 个。
+ *
+ * @param seeds   证据路径（文件或目录的绝对路径）
+ * @param options 追加标记与安卓剔除开关（来自 appendArtifacts 配置）
+ * @returns        产物根绝对路径数组；无命中返回空数组
+ */
+export declare function resolveWorkspaceRoots(seeds: string[], options?: ResolveRootsOptions): string[];
+/**
+ * 判断证据路径是否位于配置路径之下（追加产物 "session-activity" 命中判定，
+ * Windows 下大小写不敏感）。
+ *
+ * @param evidencePath 证据路径
+ * @param configPath   配置的产物路径
+ * @returns            命中返回 true
+ */
+export declare function isPathInside(evidencePath: string, configPath: string): boolean;
+export interface AndroidProjectNameOptions {
+    /** 未探测到包名时的目录兜底（通常传会话工作目录），返回其目录名 */
+    fallbackDirectory?: string;
+}
+/**
+ * 从会话证据推断安卓项目名：在证据目录及其祖先（≤3 层）定位
+ * build.gradle / AndroidManifest.xml，按 applicationId > manifest package > namespace
+ * 的优先级提取包名；探测不到时回退目录名，仍无则返回 null。
+ *
+ * @param seeds   证据路径（文件或目录的绝对路径）
+ * @param options fallbackDirectory 提供目录兜底
+ * @returns        包名 / 兜底目录名（经名称清洗）；无可返回 null
+ */
+export declare function resolveAndroidProjectName(seeds: string[], options?: AndroidProjectNameOptions): string | null;