opencode-metrics-plugin 0.2.0 → 0.3.0

package/dist/metrics/upload/agcUploader.js

@@ -0,0 +1,244 @@
+import * as fs from "node:fs";
+import * as http from "node:http";
+import * as https from "node:https";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { sanitizeNameSegment } from "./types.js";
+/** region → 默认域名映射（未显式配置 api_domain/storage_domain 时使用） */
+const REGION_DOMAINS = {
+    CN: { apiDomain: "connect-api.cloud.huawei.com", storageDomain: "ops-server-drcn.agcstorage.link/v0" },
+    DE: { apiDomain: "connect-api-dre.cloud.huawei.com", storageDomain: "ops-server-dre.agcstorage.link/v0" },
+    SG: { apiDomain: "connect-api-dra.cloud.huawei.com", storageDomain: "ops-server-dra.agcstorage.link/v0" },
+    RU: { apiDomain: "connect-api-drru.cloud.huawei.com", storageDomain: "ops-server-drru.agcstorage.link/v0" },
+};
+/** token 有效期安全余量（秒）：剩余时间小于此值即重新获取 */
+const TOKEN_MARGIN_SECONDS = 60;
+const TOKEN_TIMEOUT_MS = 30_000;
+const UPLOAD_TIMEOUT_MS = 10 * 60_000;
+/** AGC 凭证默认文件：包内 assets/agc-apiclient.json（opencode.json 未配置 agcConfigPath 时使用） */
+export function defaultAgcConfigPath() {
+    return fileURLToPath(new URL("../../../assets/agc-apiclient.json", import.meta.url));
+}
+/**
+ * 读取并校验 agc-apiclient.json：必填字段齐全、域名按 region 映射
+ * （显式配置的 api_domain/storage_domain 优先）。失败返回原因，不抛异常。
+ *
+ * @param configPath    agc-apiclient.json 绝对路径
+ * @param tokenCacheDir token 缓存目录覆盖（测试用）
+ * @returns              成功返回完整凭证；失败返回原因
+ */
+export function loadAgcCredentials(configPath, tokenCacheDir) {
+    let raw;
+    try {
+        raw = fs.readFileSync(configPath, "utf-8");
+    }
+    catch (err) {
+        return { ok: false, reason: `读取配置失败 ${configPath}: ${String(err)}` };
+    }
+    let config;
+    try {
+        config = JSON.parse(raw);
+    }
+    catch (err) {
+        return { ok: false, reason: `配置不是合法 JSON: ${String(err)}` };
+    }
+    const client_id = config.client_id;
+    const client_secret = config.client_secret;
+    const project_id = config.project_id;
+    const region = config.region;
+    const bucket_name = config.bucket_name;
+    if (!client_id || !client_secret || !project_id || !region) {
+        return { ok: false, reason: "配置缺少 client_id / client_secret / project_id / region" };
+    }
+    if (!bucket_name) {
+        return { ok: false, reason: "配置缺少 bucket_name" };
+    }
+    const mapped = REGION_DOMAINS[region];
+    const api_domain = config.api_domain || mapped?.apiDomain || "";
+    const storage_domain = config.storage_domain || mapped?.storageDomain || "";
+    if (!api_domain || !storage_domain) {
+        return { ok: false, reason: `无法确定域名（region=${region}），请显式配置 api_domain / storage_domain` };
+    }
+    return {
+        ok: true,
+        credentials: { client_id, client_secret, project_id, region, bucket_name, api_domain, storage_domain, tokenCacheDir },
+    };
+}
+/**
+ * 创建 AGC 上传器（token 自动获取与缓存 + 流式 PUT）。
+ *
+ * @param credentials 已解析的凭证
+ */
+export function createAgcUploader(credentials) {
+    return {
+        async uploadPackage(uploadPackage) {
+            const tokenOutcome = await getAccessToken(credentials);
+            if (!tokenOutcome.ok)
+                return tokenOutcome;
+            const remoteBase = composeRemoteBase(uploadPackage);
+            const archiveOutcome = await uploadFile(credentials, tokenOutcome.token, uploadPackage.archive.filePath, `${remoteBase}.tar.gz`);
+            if (!archiveOutcome.ok)
+                return archiveOutcome;
+            return uploadFile(credentials, tokenOutcome.token, uploadPackage.snapshot.filePath, `${remoteBase}.json`);
+        },
+    };
+}
+/** 获取 access token：优先读缓存（留 60s 余量），否则 client_credentials 换取并写缓存 */
+async function getAccessToken(credentials) {
+    const cacheDir = credentials.tokenCacheDir ?? path.join(os.homedir(), ".agc_cache");
+    const cacheFile = path.join(cacheDir, `token_${credentials.client_id}.cache`);
+    try {
+        const cache = JSON.parse(fs.readFileSync(cacheFile, "utf-8"));
+        if (cache.access_token && Date.now() / 1000 < (cache.expires_at ?? 0) - TOKEN_MARGIN_SECONDS) {
+            return { ok: true, token: cache.access_token };
+        }
+    }
+    catch {
+        // 无缓存或缓存损坏，走获取流程
+    }
+    let response;
+    try {
+        response = await fetch(`${withScheme(credentials.api_domain)}/api/oauth2/v1/token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                grant_type: "client_credentials",
+                client_id: credentials.client_id,
+                client_secret: credentials.client_secret,
+            }),
+            signal: AbortSignal.timeout(TOKEN_TIMEOUT_MS),
+        });
+    }
+    catch (err) {
+        return { ok: false, retryable: true, reason: `token 请求失败: ${describeError(err)}` };
+    }
+    if (!response.ok) {
+        return { ok: false, retryable: response.status >= 500, reason: `token 响应 ${response.status}: ${await safeText(response)}` };
+    }
+    const result = (await response.json().catch(() => null));
+    if (!result?.access_token) {
+        return { ok: false, retryable: false, reason: "token 响应缺少 access_token" };
+    }
+    try {
+        fs.mkdirSync(cacheDir, { recursive: true });
+        fs.writeFileSync(cacheFile, JSON.stringify({
+            access_token: result.access_token,
+            expires_at: Date.now() / 1000 + (result.expires_in ?? 172800),
+        }));
+    }
+    catch {
+        // 缓存写失败不影响本次上传
+    }
+    return { ok: true, token: result.access_token };
+}
+/** 流式上传单文件到云存储对象 */
+/** 流式上传单文件到云存储对象（原生 http/https：AGC 网关硬性要求显式 Content-Length，拒绝 chunked；fetch 规范禁止手动设置该头） */
+async function uploadFile(credentials, token, localPath, remoteObject) {
+    let sizeBytes;
+    try {
+        sizeBytes = fs.statSync(localPath).size;
+    }
+    catch (err) {
+        return { ok: false, retryable: false, reason: `文件不存在 ${localPath}: ${String(err)}` };
+    }
+    const uploadUrl = `${withScheme(credentials.storage_domain)}/${credentials.bucket_name}/${encodeURI(remoteObject)}`;
+    return new Promise((resolve) => {
+        let url;
+        try {
+            url = new URL(uploadUrl);
+        }
+        catch {
+            return resolve({ ok: false, retryable: false, reason: `上传地址无效: ${uploadUrl}` });
+        }
+        const transport = url.protocol === "http:" ? http : https;
+        const request = transport.request({
+            hostname: url.hostname,
+            port: url.port || (url.protocol === "http:" ? 80 : 443),
+            path: `${url.pathname}${url.search}`,
+            method: "PUT",
+            headers: {
+                client_id: credentials.client_id,
+                productId: credentials.project_id,
+                Authorization: `Bearer ${token}`,
+                "Content-Type": "application/octet-stream",
+                "X-Agc-File-Size": String(sizeBytes),
+                "Content-Length": String(sizeBytes),
+            },
+        }, (response) => {
+            let bodyText = "";
+            response.setEncoding("utf-8");
+            response.on("data", (chunk) => {
+                if (bodyText.length < 512)
+                    bodyText += chunk;
+            });
+            response.on("end", () => {
+                const status = response.statusCode ?? 0;
+                if (status >= 200 && status < 300) {
+                    resolve({ ok: true });
+                }
+                else {
+                    resolve({
+                        ok: false,
+                        retryable: status >= 500 || status === 429,
+                        reason: `上传响应 ${status}: ${bodyText.trim().slice(0, 512)}`,
+                    });
+                }
+            });
+            response.on("error", (err) => resolve({ ok: false, retryable: true, reason: `上传失败: ${describeError(err)}` }));
+        });
+        request.setTimeout(UPLOAD_TIMEOUT_MS, () => {
+            request.destroy(new Error(`上传超时(${UPLOAD_TIMEOUT_MS}ms)`));
+        });
+        request.on("error", (err) => resolve({ ok: false, retryable: true, reason: `上传失败: ${describeError(err)}` }));
+        const fileStream = fs.createReadStream(localPath);
+        fileStream.on("error", (err) => request.destroy(err));
+        fileStream.pipe(request);
+    });
+}
+/**
+ * 缩写 agent 名用于云端路径段：按 "-" 分段取各段首字母（harmonyos-convert→hc），
+ * 单段名取前 3 字符（explore→exp），空名兜底 agent。
+ *
+ * @param agentName 触发时会话的 agent 名
+ * @returns          缩写后的安全路径段
+ */
+export function abbreviateAgentName(agentName) {
+    const segments = agentName.split("-").filter((segment) => segment.length > 0);
+    if (segments.length === 0)
+        return "agent";
+    const abbreviation = segments.length === 1 ? segments[0].slice(0, 3) : segments.map((segment) => segment[0]).join("");
+    return sanitizeNameSegment(abbreviation, "agent");
+}
+/**
+ * 组装云端对象路径前缀（含版本目录，双文件归拢其内）：
+ * YYYYMMDD/<projectName>-<sessionId>/<agent缩写>-<trigger>-v<n>/<agent缩写>-<trigger>-v<n>
+ */
+function composeRemoteBase(uploadPackage) {
+    const now = new Date();
+    const pad = (value) => String(value).padStart(2, "0");
+    const dateDirectory = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}`;
+    const fileBase = `${abbreviateAgentName(uploadPackage.agentName)}-${uploadPackage.trigger}-v${uploadPackage.sequence}`;
+    return `${dateDirectory}/${uploadPackage.projectName}-${uploadPackage.sessionId}/${fileBase}/${fileBase}`;
+}
+/** 归档包云端对象完整路径（上传成功日志用） */
+export function remoteArchiveKey(uploadPackage) {
+    return `${composeRemoteBase(uploadPackage)}.tar.gz`;
+}
+/** 域名字段兼容完整 URL（http:// 前缀用于本地联调），裸域名补 https:// */
+function withScheme(domain) {
+    return domain.startsWith("http://") || domain.startsWith("https://") ? domain : `https://${domain}`;
+}
+async function safeText(response) {
+    try {
+        return (await response.text()).slice(0, 512);
+    }
+    catch {
+        return "";
+    }
+}
+function describeError(err) {
+    if (err instanceof Error)
+        return `${err.name}: ${err.message}`;
+    return String(err);
+}

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

@@ -0,0 +1,34 @@
+import { type ArchiveResult } from "./types.js";
+export interface ArchiveSessionOptions {
+    sessionId: string;
+    /** 触发场景标签（文件名的一段） */
+    trigger: string;
+    /** 触发时会话的 agent 名（文件名的一段） */
+    agentName: string;
+    /** 安卓项目名（包名或目录名兜底，文件名的一段） */
+    projectName: string;
+    /** workspace 产物根（空数组 = 只打恒含项） */
+    roots: string[];
+    /** 快照目录（恒含 <sessionId>.json） */
+    metricsDir: string;
+    /** 事件日志目录（恒含 <sessionId>.log 及轮转 <sessionId>.*.log） */
+    eventsDir: string;
+    /** 暂存目录（双文件输出位置） */
+    stagingDir: string;
+    /** 追加黑名单（与默认合并） */
+    blacklist?: string[];
+    /** 剔除根内嵌套的安卓工程子目录（深度 ≤2），缺省 true */
+    excludeAndroidProjects?: boolean;
+    /** 单包体积上限，超限该次失败 */
+    maxArtifactBytes?: number;
+}
+/**
+ * 打包一次上传产物：恒含项（快照 + 事件日志）与各 workspace 根打成单个 tar.gz，
+ * 同时把时点快照单独复制一份，两个文件输出到暂存目录。
+ * 命名 <sessionId>-<agentName>-<trigger>-v<n>.tar.gz 与同名 .json。
+ * 失败不抛异常，返回 { ok: false, reason }。
+ *
+ * @param options 归档参数（会话、根、目录、限制项）
+ * @returns        成功返回产物包信息；失败返回原因
+ */
+export declare function archiveSessionPackage(options: ArchiveSessionOptions): Promise<ArchiveResult>;

package/dist/metrics/upload/packageArchiver.js

@@ -0,0 +1,213 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { log } from "../../shared/log.js";
+import { looksLikeAndroidProject } from "./workspaceResolver.js";
+import { DEFAULT_BLACKLIST, DEFAULT_MAX_ARTIFACT_BYTES, sanitizeNameSegment, } from "./types.js";
+// 会话维度单调序号：v1, v2, ...（进程内；硬杀丢失为 v1 已知限制）
+const sessionSequence = new Map();
+let tarAvailable = null;
+/**
+ * 打包一次上传产物：恒含项（快照 + 事件日志）与各 workspace 根打成单个 tar.gz，
+ * 同时把时点快照单独复制一份，两个文件输出到暂存目录。
+ * 命名 <sessionId>-<agentName>-<trigger>-v<n>.tar.gz 与同名 .json。
+ * 失败不抛异常，返回 { ok: false, reason }。
+ *
+ * @param options 归档参数（会话、根、目录、限制项）
+ * @returns        成功返回产物包信息；失败返回原因
+ */
+export async function archiveSessionPackage(options) {
+    const { sessionId, roots, metricsDir, eventsDir } = options;
+    if (!(await isTarAvailable())) {
+        return fail("tar-unavailable", "系统 tar 不可用");
+    }
+    const snapshotSource = path.join(metricsDir, `${sessionId}.json`);
+    if (!fs.existsSync(snapshotSource)) {
+        return fail("snapshot-missing", `快照不存在: ${snapshotSource}`);
+    }
+    const stagingDir = options.stagingDir;
+    fs.mkdirSync(stagingDir, { recursive: true });
+    const sequence = (sessionSequence.get(sessionId) ?? 0) + 1;
+    sessionSequence.set(sessionId, sequence);
+    const agentLabel = sanitizeNameSegment(options.agentName, "agent");
+    const projectLabel = sanitizeNameSegment(options.projectName);
+    const triggerLabel = sanitizeNameSegment(options.trigger, "upload");
+    const baseName = `${sessionId}-${agentLabel}-${triggerLabel}-v${sequence}`;
+    const archivePath = path.join(stagingDir, `${baseName}.tar.gz`);
+    const snapshotPath = path.join(stagingDir, `${baseName}.json`);
+    const tmpPath = `${archivePath}.tmp`;
+    // 组装恒含项（复制小文件，workspace 根原位引用）
+    const assemblyDir = path.join(stagingDir, `.assembly-${sessionId}-v${sequence}`);
+    try {
+        fs.rmSync(assemblyDir, { recursive: true, force: true });
+        fs.mkdirSync(path.join(assemblyDir, "snapshot"), { recursive: true });
+        fs.mkdirSync(path.join(assemblyDir, "events"), { recursive: true });
+        fs.copyFileSync(snapshotSource, path.join(assemblyDir, "snapshot", `${sessionId}.json`));
+        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 tarError = await runTar(args);
+        if (tarError) {
+            return fail("tar-failed", tarError);
+        }
+        fs.renameSync(tmpPath, archivePath);
+        const sizeBytes = fs.statSync(archivePath).size;
+        const maxBytes = options.maxArtifactBytes ?? DEFAULT_MAX_ARTIFACT_BYTES;
+        if (sizeBytes > maxBytes) {
+            fs.rmSync(archivePath, { force: true });
+            return fail("too-large", `包体积 ${sizeBytes} 超过上限 ${maxBytes}`);
+        }
+        // 快照单独一份（与包内时点一致）
+        fs.copyFileSync(path.join(assemblyDir, "snapshot", `${sessionId}.json`), snapshotPath);
+        const sha256 = await computeSha256(archivePath);
+        log.info("[Metrics] archived", { sessionId, trigger: triggerLabel, baseName, sizeBytes, excludedAndroid });
+        const uploadPackage = {
+            sessionId,
+            trigger: triggerLabel,
+            sequence,
+            agentName: agentLabel,
+            projectName: projectLabel,
+            archive: { fileName: `${baseName}.tar.gz`, filePath: archivePath, sizeBytes },
+            snapshot: {
+                fileName: `${baseName}.json`,
+                filePath: snapshotPath,
+                sizeBytes: fs.statSync(snapshotPath).size,
+            },
+            sha256,
+            roots: [...roots],
+            createdAt: Date.now(),
+        };
+        return { ok: true, package: uploadPackage };
+    }
+    catch (err) {
+        // 失败时清掉已产生的半成品，不留脏文件
+        fs.rmSync(archivePath, { force: true });
+        fs.rmSync(snapshotPath, { force: true });
+        return fail("archive-error", String(err));
+    }
+    finally {
+        fs.rmSync(assemblyDir, { recursive: true, force: true });
+        if (fs.existsSync(tmpPath))
+            fs.rmSync(tmpPath, { force: true });
+    }
+}
+/** 组装 tar 参数：黑名单排除 + 嵌套安卓工程剔除 + 恒含项 + 各 workspace 根（按 basename 入包，重名加序号后缀）；全部 --exclude 须在任何操作数之前（bsdtar 不解析操作数之后的选项） */
+function buildTarArgs(output, assemblyDir, roots, extraBlacklist, excludeAndroidProjects) {
+    const blacklist = [...DEFAULT_BLACKLIST, ...extraBlacklist];
+    const excludedAndroid = [];
+    // 根条目名先就位（重名加序号），安卓剔除以条目名锚定
+    const usedNames = new Set();
+    const rootEntries = roots.map((root) => {
+        let entryName = path.basename(path.resolve(root)) || "workspace";
+        if (usedNames.has(entryName.toLowerCase())) {
+            entryName = `${entryName}-${usedNames.size + 1}`;
+        }
+        usedNames.add(entryName.toLowerCase());
+        return { root, entryName };
+    });
+    const args = ["-czf", output];
+    for (const name of blacklist) {
+        // 裸名匹配末段（GNU tar），*/名匹配任意深度（bsdtar）
+        args.push("--exclude", name, "--exclude", `*/${name}`);
+    }
+    if (excludeAndroidProjects) {
+        for (const { root, entryName } of rootEntries) {
+            for (const relativePath of detectNestedAndroidDirs(root, blacklist)) {
+                excludedAndroid.push(`${entryName}/${relativePath}`);
+                // 锚定到该根条目下，避免误伤其他根的同名目录
+                args.push("--exclude", `${entryName}/${relativePath}`, "--exclude", `*/${entryName}/${relativePath}`);
+            }
+        }
+    }
+    args.push("-C", assemblyDir, ".");
+    for (const { root, entryName } of rootEntries) {
+        args.push("-C", path.dirname(path.resolve(root)), entryName);
+    }
+    return { args, excludedAndroid };
+}
+/** 扫描根的直接与二级子目录，返回识别为安卓工程的相对路径（命中即止，不再深入） */
+function detectNestedAndroidDirs(root, blacklist) {
+    const found = [];
+    const queue = [
+        { directory: root, relativePath: "", depth: 0 },
+    ];
+    const skipped = new Set(blacklist.map((name) => name.toLowerCase()));
+    while (queue.length > 0) {
+        const { directory, relativePath, 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 childRelative = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+            const childDirectory = path.join(directory, entry.name);
+            if (looksLikeAndroidProject(childDirectory)) {
+                found.push(childRelative);
+                continue;
+            }
+            if (depth + 1 < 2) {
+                queue.push({ directory: childDirectory, relativePath: childRelative, depth: depth + 1 });
+            }
+        }
+    }
+    return found;
+}
+/** 收集会话事件日志：当前日志 + 轮转副本 */
+function collectEventLogs(sessionId, eventsDir) {
+    try {
+        return fs
+            .readdirSync(eventsDir)
+            .filter((file) => file === `${sessionId}.log` ||
+            (file.startsWith(`${sessionId}.`) && file.endsWith(".log")))
+            .map((file) => path.join(eventsDir, file));
+    }
+    catch {
+        return [];
+    }
+}
+/** 运行 tar，返回错误描述（null = 成功） */
+function runTar(args) {
+    return new Promise((resolve) => {
+        const child = spawn("tar", args, { windowsHide: true });
+        let stderr = "";
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString();
+            if (stderr.length > 4096)
+                stderr = stderr.slice(-4096);
+        });
+        child.on("error", (err) => resolve(String(err)));
+        child.on("close", (code) => resolve(code === 0 ? null : `tar 退出码 ${code}: ${stderr.trim()}`));
+    });
+}
+/** 探测系统 tar 是否可用（结果缓存） */
+async function isTarAvailable() {
+    if (tarAvailable !== null)
+        return tarAvailable;
+    tarAvailable = await new Promise((resolve) => {
+        const child = spawn("tar", ["--version"], { windowsHide: true });
+        child.on("error", () => resolve(false));
+        child.on("close", (code) => resolve(code === 0));
+    });
+    return tarAvailable;
+}
+/** 流式计算文件 sha256 */
+async function computeSha256(filePath) {
+    const hash = createHash("sha256");
+    const stream = fs.createReadStream(filePath);
+    for await (const chunk of stream) {
+        hash.update(chunk);
+    }
+    return hash.digest("hex");
+}
+/** 统一失败出口：记日志并返回结果对象 */
+function fail(code, reason) {
+    log.error("[Metrics] archive failed", { code, reason });
+    return { ok: false, reason: `${code}: ${reason}` };
+}

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

@@ -0,0 +1,20 @@
+import type { ScenarioConfig } from "./types.js";
+/** 解析后的触发场景：label 用于文件命名，commands/events 为两类匹配源 */
+export interface ResolvedScenario {
+    key: string;
+    /** 命名标签（文件名 <sessionId>-<agentName>-<label>-v<n> 的一段） */
+    label: string;
+    enabled: boolean;
+    /** bash 命令正则（工具 completed 时判定） */
+    commandRegexes: RegExp[];
+    /** 匹配的事件名（含特殊值 "dispose"，由管理器结束时触发） */
+    events: string[];
+}
+/**
+ * 合并内置场景与 opencode.json 配置：内置 key 深合并（label/commands/events 可覆盖、
+ * enabled:false 可禁用），自定义 key 直接新增；非法正则跳过并记日志。
+ *
+ * @param configs opencode.json upload.scenarios
+ * @returns        全部场景（含禁用的，调用方按 enabled 过滤）
+ */
+export declare function resolveScenarios(configs?: Record<string, ScenarioConfig>): ResolvedScenario[];

package/dist/metrics/upload/scenarios.js

@@ -0,0 +1,43 @@
+import { log } from "../../shared/log.js";
+/** 内置默认场景（opencode.json scenarios 按 key 合并覆盖） */
+const BUILTIN_SCENARIOS = {
+    "session-end": { label: "session-end", events: ["dispose", "session.deleted"] },
+    "git-commit": { label: "git", commands: ["\\bgit\\s+commit\\b"] },
+};
+/**
+ * 合并内置场景与 opencode.json 配置：内置 key 深合并（label/commands/events 可覆盖、
+ * enabled:false 可禁用），自定义 key 直接新增；非法正则跳过并记日志。
+ *
+ * @param configs opencode.json upload.scenarios
+ * @returns        全部场景（含禁用的，调用方按 enabled 过滤）
+ */
+export function resolveScenarios(configs) {
+    const merged = new Map();
+    for (const [key, builtin] of Object.entries(BUILTIN_SCENARIOS)) {
+        merged.set(key, { ...builtin, ...(configs?.[key] ?? {}) });
+    }
+    for (const [key, config] of Object.entries(configs ?? {})) {
+        if (!merged.has(key))
+            merged.set(key, config);
+    }
+    const result = [];
+    for (const [key, config] of merged) {
+        const commandRegexes = [];
+        for (const pattern of config.commands ?? []) {
+            try {
+                commandRegexes.push(new RegExp(pattern));
+            }
+            catch (err) {
+                log.warn("[Metrics] 场景正则无效，已跳过", { key, pattern, error: String(err) });
+            }
+        }
+        result.push({
+            key,
+            label: config.label ?? key,
+            enabled: config.enabled !== false,
+            commandRegexes,
+            events: config.events ?? [],
+        });
+    }
+    return result;
+}

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

@@ -0,0 +1,111 @@
+/** 追加产物的命中方式 */
+export type ArtifactMatchBy = "session-activity" | "existence";
+/**
+ * opencode.json upload.appendArtifacts 的单条规则。
+ * matchBy = "session-activity" 时须被会话修改过程命中才纳入；
+ * "existence" 时触发时刻路径存在即纳入。
+ */
+export interface ArtifactRule {
+    /** 产物标识，用于日志与包内条目命名 */
+    name: string;
+    /** 显式产物路径（绝对或相对会话工作目录） */
+    path?: string;
+    /** 追加目录标记（探测规则同内置 dirMarkers） */
+    dirMarkers?: string[];
+    /** 追加文件标记（探测规则同内置 fileMarkers） */
+    fileMarkers?: string[];
+    matchBy?: ArtifactMatchBy;
+}
+/** 触发场景配置：按 key 与内置场景合并，enabled:false 禁用 */
+export interface ScenarioConfig {
+    enabled?: boolean;
+    /** 命名标签，用于包名 <sessionId>-<label>-v<n> */
+    label?: string;
+    /** bash 工具命令正则（completed 时判定） */
+    commands?: string[];
+    /** TRACKED_EVENT_TYPES 内事件名 */
+    events?: string[];
+}
+/** 上传通道配置（当前仅 agc） */
+export interface UploaderConfig {
+    type?: string;
+    /** agc-apiclient.json 绝对路径 */
+    agcConfigPath?: string;
+}
+/** 重试策略：指数退避 backoffMs × 4^n，4xx 不重试 */
+export interface UploadRetryConfig {
+    maxAttempts?: number;
+    backoffMs?: number;
+}
+/** opencode.json 的 upload 配置整块（§13.8） */
+export interface UploadConfig {
+    /** 上传总开关，缺省 false（行为与 0.2.x 零差异） */
+    enabled?: boolean;
+    uploader?: UploaderConfig;
+    scenarios?: Record<string, ScenarioConfig>;
+    appendArtifacts?: ArtifactRule[];
+    /** 打包排除的目录/文件名，追加到默认黑名单 */
+    blacklist?: string[];
+    /** 剔除安卓工程（根级剔除 + 根内子树剔除），缺省 true */
+    excludeAndroidProjects?: boolean;
+    /** 单包体积上限，超限该次标 failed */
+    maxArtifactBytes?: number;
+    retry?: UploadRetryConfig;
+}
+/** 暂存目录内的单个上传文件（归档包或快照） */
+export interface UploadPackageFile {
+    fileName: string;
+    /** 暂存目录内绝对路径 */
+    filePath: string;
+    sizeBytes: number;
+}
+/** 一次归档的结果：进上传队列的单元，一个任务上传两个文件（tar.gz + 快照 JSON） */
+export interface UploadPackage {
+    sessionId: string;
+    /** 触发场景名（文件名中的 label 段） */
+    trigger: string;
+    /** 会话内单调递增序号，从 1 起 */
+    sequence: number;
+    /** 触发时会话的 agent 名（云端路径一段） */
+    agentName: string;
+    /** 安卓包名；探测失败时为目录名兜底（云端路径一段） */
+    projectName: string;
+    /** 归档包（tar.gz） */
+    archive: UploadPackageFile;
+    /** 快照 JSON（单独上传的一份） */
+    snapshot: UploadPackageFile;
+    /** 归档包 sha256 */
+    sha256: string;
+    /** 纳入的 workspace 产物根 */
+    roots: string[];
+    createdAt: number;
+}
+/**
+ * 清洗名称为安全的路径段：非法字符（含空格）替换为 "-"，保留中文与内部点号，
+ * 首尾修剪 "." "-"，结果为空时返回 fallback。
+ *
+ * @param name     原始名称
+ * @param fallback 清洗后为空时的替代值
+ * @returns         可安全用于文件名/云端路径的段
+ */
+export declare function sanitizeNameSegment(name: string, fallback?: string): string;
+/** 归档结果：成功返回产物包，失败返回原因（不抛异常） */
+export type ArchiveResult = {
+    ok: true;
+    package: UploadPackage;
+} | {
+    ok: false;
+    reason: string;
+};
+/** 目录内存在这些子目录 → 该目录是产物根 */
+export declare const DEFAULT_DIR_MARKERS: readonly string[];
+/** 目录内存在这些文件/目录 → 该目录是产物根 */
+export declare const DEFAULT_FILE_MARKERS: readonly string[];
+/** 打包排除的目录/文件名（按路径段匹配） */
+export declare const DEFAULT_BLACKLIST: readonly string[];
+/** 单包体积上限默认 500MB */
+export declare const DEFAULT_MAX_ARTIFACT_BYTES: number;
+/** 自证据路径向上探测标记的最大层级 */
+export declare const MAX_PROBE_DEPTH = 5;
+/** 产物根数量上限 */
+export declare const MAX_ROOTS = 3;