@tencent-ai/agent-harness 0.2.0-beta.7 → 0.2.0-beta.8

package/cli/dist-server/types/node/galileo/galileo-chat-reporter.d.ts

@@ -0,0 +1,302 @@
+/**
+ * GalileoChatReporter — 伽利略 Chat 事件上报模块
+ *
+ * 负责将 chat_request_response / chat_message_status 两个核心事件上报到伽利略可观测平台，
+ * 覆盖 task 级（一次完整请求-响应）和 message 级（单条消息）两种粒度，每种粒度上报成功/失败两路。
+ *
+ * 上报策略（设计要点）：
+ * - **统一走 Log 视图**：error 路径发 logError，success 路径发 logInfo，**完全不发 Counter**
+ *   - 错误率分子：count(agent.{request,message}.error_detail)
+ *   - 错误率分母：count(error_detail) + count(success_detail)
+ *   - Counter 装不下 trace_id / agent_name / current_turn 等下钻字段，Log 视图原生支持按字段聚合
+ * - **未维护业务码报警**：当 ctx.unknownBizCode 非空时额外发一条独立 logError
+ *   `agent.error.unknown_biz_code`，与主错误日志解耦便于后台单独配告警规则
+ *
+ * 与 AgentMetricsAggregator 的关系：
+ * - aggregator 的 agent.request.{total,success,failed} 是 **HTTP message 级**、空维度的 Counter，
+ *   覆盖面只有 model-provider 的 stream end/error（不含 401/429/网关 5xx，因为那些被
+ *   error-analyzer 转成了"成功的 Response"），仅作全局可用性视角
+ * - 本模块的 agent.{request,message}.{error,success}_detail 是 **task / message 级**、含完整下钻字段的日志流，
+ *   覆盖所有完成事件，是 SLA 看板的主数据源
+ *
+ * 反污染守卫：
+ * - user_cancelled 不上报（无论 error 还是 success），避免污染错误率指标
+ *   这些场景由 Telemetry → ClickHouse 通道单独保留（用于 cancellation 行为分析）
+ * - GalileoService 未就绪时全链路降级为 noop
+ */
+import { type ModelCallAgentType } from '../../vendor/cbc-core/node/index.js';
+import type { ErrorSubcategory } from './error-category';
+export declare const GalileoChatReporter: unique symbol;
+/**
+ * 请求级错误上下文（chat_request_response 失败时）。
+ * 字段对应 design.md 第 3.2 节定义。
+ */
+export interface RequestErrorContext {
+    conversationId: string;
+    conversationRequestId: string;
+    promptRequestId?: string;
+    traceId: string;
+    messageId?: string;
+    /** 用户 uid（按用户聚合/下钻维度，伽利略 log 标准识别字段；未登录或上游未透传时为空） */
+    uid?: string;
+    errorCategory: string;
+    errorSubcategory: ErrorSubcategory;
+    errorCode: string;
+    /**
+     * 走业务码路径但 BIZ_CODE_MAP / BIZ_CODE_RANGES 都没命中时的原始码。
+     * 设置时表示后端可能新增了我们尚未维护的业务码，需要在伽利略后台告警提示。
+     */
+    unknownBizCode?: string;
+    errorMessage: string;
+    acpErrorCode?: number;
+    httpStatusCode?: number;
+    nodeErrorCode?: string;
+    isFirstTokenTimeout?: boolean;
+    isEmptyStream?: boolean;
+    isInputLengthError?: boolean;
+    isRetryable?: boolean;
+    finishReason?: string;
+    model: string;
+    modelName?: string;
+    scene: string;
+    agentName?: string;
+    agentType?: string;
+    currentTurn?: number;
+    isCustomModel?: boolean;
+    /**
+     * 本轮 `wb.api.request` 实际上报的 host（容灾后的最终域名）。
+     * 没有对应 API 样本时为空，不拿别的请求的域名顶上。
+     */
+    host?: string;
+    /**
+     * 最后一跳钉住的 IP。未钉为空。钉 IP 不改写 host，域名仍是 URL 上的主机名。
+     */
+    pin?: string;
+}
+/**
+ * 消息级错误上下文（chat_message_status 失败时）。
+ * 比 RequestErrorContext 字段少（无 acpErrorCode / 特征标记 / 上下文维度），
+ * 因为 message 级量大，需要更精简。
+ */
+export interface MessageErrorContext {
+    conversationId: string;
+    conversationRequestId: string;
+    promptRequestId?: string;
+    messageId: string;
+    traceId: string;
+    /** 用户 uid（按用户聚合/下钻维度，伽利略 log 标准识别字段；未登录或上游未透传时为空） */
+    uid?: string;
+    errorCode: string;
+    errorCategory: string;
+    errorSubcategory: ErrorSubcategory;
+    /** 同 RequestErrorContext.unknownBizCode：未维护的业务码报警标记。 */
+    unknownBizCode?: string;
+    errorMessage: string;
+    nodeErrorCode?: string;
+    httpStatusCode?: number;
+    model: string;
+    currentTurn?: number;
+}
+/**
+ * 请求级成功上下文（chat_request_response isSuccessful=true 时）。
+ *
+ * 字段集与 RequestErrorContext 共享下钻必需信息（trace_id / messageId / agentName / currentTurn 等），
+ * 但去掉了 error_* 系列字段（成功路径无错误信息）。
+ */
+export interface RequestSuccessContext {
+    conversationId: string;
+    conversationRequestId: string;
+    promptRequestId?: string;
+    traceId: string;
+    messageId?: string;
+    /** 用户 uid（按用户聚合/下钻维度，伽利略 log 标准识别字段；未登录或上游未透传时为空） */
+    uid?: string;
+    model: string;
+    modelName?: string;
+    scene: string;
+    agentName?: string;
+    agentType?: string;
+    currentTurn?: number;
+    isCustomModel?: boolean;
+    finishReason?: string;
+    /**
+     * 本轮 `wb.api.request` 实际上报的 host（容灾后的最终域名）。
+     * 没有对应 API 样本时为空，不拿别的请求的域名顶上。
+     */
+    host?: string;
+    /**
+     * 最后一跳钉住的 IP。未钉为空。钉 IP 不改写 host，域名仍是 URL 上的主机名。
+     */
+    pin?: string;
+}
+export type RequestStartContext = Omit<RequestSuccessContext, 'finishReason'>;
+/**
+ * 消息级成功上下文（chat_message_status messageErrorCode='0' 时）。
+ *
+ * 比 RequestSuccessContext 字段少，对齐 MessageErrorContext 的精简风格。
+ */
+export interface MessageSuccessContext {
+    conversationId: string;
+    conversationRequestId: string;
+    promptRequestId?: string;
+    messageId: string;
+    traceId: string;
+    /** 用户 uid（按用户聚合/下钻维度，伽利略 log 标准识别字段；未登录或上游未透传时为空） */
+    uid?: string;
+    model: string;
+    currentTurn?: number;
+}
+/**
+ * 消息级开始上下文（首个 assistant 内容 chunk 到达时）。
+ *
+ * 字段集与 MessageSuccessContext 对齐，便于同一次 message 横向 join。
+ */
+export interface MessageStartContext {
+    conversationId: string;
+    conversationRequestId: string;
+    promptRequestId?: string;
+    messageId: string;
+    traceId: string;
+    /** 用户 uid（按用户聚合/下钻维度，伽利略 log 标准识别字段；未登录或上游未透传时为空） */
+    uid?: string;
+    model: string;
+    currentTurn?: number;
+}
+/** Tool 调用「开始」— PreToolUse 时上报，仅定位信息。 */
+export interface ToolStartContext {
+    /** 关联 ID（与 request/message 级一致，便于 Log 视图横向 join） */
+    conversationId: string;
+    conversationRequestId: string;
+    promptRequestId?: string;
+    messageId?: string;
+    traceId: string;
+    uid?: string;
+    toolName: string;
+    /** 来自 ACP toolCall.callId */
+    callId: string;
+    /** 当 toolName 为 DeferExecuteTool 时，实际被代理的目标工具名 */
+    targetToolName?: string;
+    /** 能力类型归一（builtin/mcp/plugin/connector/skill）；用于会话能力归因聚合 */
+    capabilityType?: string;
+    /** 能力实例标识（mcp/connector→server，plugin→pluginName，skill→skill名，builtin→工具名） */
+    capabilityId?: string;
+    /** expert 会话标识；非 expert 会话为空 */
+    expertId?: string;
+    model?: string;
+    modelName?: string;
+    scene?: string;
+    agentName?: string;
+    agentType?: ModelCallAgentType;
+    currentTurn?: number;
+}
+/** Tool 调用「成功」— PostToolUse 且非 error 时上报；不带 input/output（量大且含敏感数据）。 */
+export interface ToolSuccessContext extends ToolStartContext {
+    /** 工具执行耗时（ms） */
+    durationMs: number;
+    /** 当 toolName 为 DeferExecuteTool 时，实际被代理的目标工具名 */
+    targetToolName?: string;
+}
+/**
+ * Tool 调用「失败」— PostToolUseFailure（thrown）或 PostToolUse + is_error（response_flag）。
+ * 用户主动取消（is_interrupt）由调用方过滤。
+ */
+export interface ToolErrorContext extends ToolStartContext {
+    durationMs: number;
+    /** 错误大类（如 EXECUTION_ERROR / TIMEOUT / VALIDATION_ERROR；缺失 fallback 'UNKNOWN'） */
+    errorType: string;
+    /** 错误信息原文（截断至 500 字符） */
+    errorMessage: string;
+    errorSource: 'thrown' | 'response_flag';
+    /** 当 toolName 为 DeferExecuteTool 时，实际被代理的目标工具名 */
+    targetToolName?: string;
+    /** 稳定消息 ID，用于从聚合表下钻到具体失败样本 */
+    conversationMessageId?: string;
+    /** 稳定错误码（纯数字字符串，如 '1001'），值来自 ToolErrorCode 枚举；缺失时兜底 '99999' */
+    toolErrorCode?: string;
+    /** 稳定错误名（如 'ReadFileNotFoundError'），由错误码反查枚举名得到 */
+    toolErrorName?: string;
+    /** 可读错误原因（如 '文件不存在'） */
+    errorReason?: string;
+}
+export interface GalileoChatReporter {
+    /** chat_request_response 已发出、开始处理响应时调用 — Task 级开始日志（仅 logInfo）。 */
+    reportRequestStart(context: RequestStartContext): void;
+    /** chat_request_response 失败时调用 — Task 级错误上报（logError + addCounter）*/
+    reportRequestError(context: RequestErrorContext): void;
+    /** chat_message_status 失败时调用 — Message 级错误上报（logError + addCounter）*/
+    reportMessageError(context: MessageErrorContext): void;
+    /**
+     * chat_request_response isSuccessful=true 时调用 — Task 级成功日志（仅 logInfo）。
+     * 不再发 Counter，错误率分母通过日志聚合 success_detail 条数得到。
+     */
+    reportRequestSuccess(context: RequestSuccessContext): void;
+    /**
+     * chat_message_status messageErrorCode='0' 时调用 — Message 级成功日志（仅 logInfo）。
+     * 不再发 Counter，错误率分母通过日志聚合 success_detail 条数得到。
+     */
+    reportMessageSuccess(context: MessageSuccessContext): void;
+    /**
+     * 首个 assistant 内容 chunk 到达时调用 — Message 级开始日志（仅 logInfo）。
+     * 与 success_detail 共享字段，用于定位 message 生命周期起点。
+     */
+    reportMessageStart(context: MessageStartContext): void;
+    /** Tool 调用开始（PreToolUse） — Tool 级开始日志（logInfo）。 */
+    reportToolStart(context: ToolStartContext): void;
+    /** Tool 调用成功（PostToolUse 且 tool_response 不是 error） — logInfo。 */
+    reportToolSuccess(context: ToolSuccessContext): void;
+    /** Tool 调用失败（PostToolUseFailure 或 PostToolUse 且 response.is_error） — logError。 */
+    reportToolError(context: ToolErrorContext): void;
+}
+export declare class GalileoChatReporterImpl implements GalileoChatReporter {
+    private readonly galileo;
+    /**
+     * 用户主动取消不属于"错误"，不上报到伽利略以避免污染错误率指标。
+     * 这些场景由 Telemetry → ClickHouse 通道单独保留（用于 cancellation 行为分析）。
+     */
+    private isCancellation;
+    reportRequestError(ctx: RequestErrorContext): void;
+    reportMessageError(ctx: MessageErrorContext): void;
+    /**
+     * 上报未维护业务码的告警事件。
+     *
+     * 通过独立的 logError 事件单独透出，与主错误日志解耦：
+     * - 主错误日志（agent.{request,message}.error_detail）仍含 unknown_biz_code 字段供下钻搜索
+     * - 此独立事件 agent.error.unknown_biz_code 用于精确告警，避免和正常错误日志混在一起
+     *
+     * 后台告警规则建议：
+     *   count(agent.error.unknown_biz_code) by biz_code > 0 over 1h
+     * 命中即提示研发补充 BIZ_CODE_MAP 维护表。
+     */
+    private reportUnknownBizCode;
+    /**
+     * Task 级开始日志（仅 logInfo，不发 Counter）。
+     *
+     * 在 LLM request 已发出、开始处理响应时上报，与 request.success_detail 共享字段，
+     * 用于定位 request 生命周期起点。
+     */
+    reportRequestStart(ctx: RequestStartContext): void;
+    /**
+     * Task 级成功日志（仅 logInfo，不发 Counter）。
+     *
+     * 错误率分母通过 Log 视图聚合：
+     *   error_rate = count(agent.request.error_detail) / (count(agent.request.error_detail) + count(agent.request.success_detail))
+     */
+    reportRequestSuccess(ctx: RequestSuccessContext): void;
+    /**
+     * Message 级成功日志（仅 logInfo，不发 Counter）。
+     */
+    reportMessageSuccess(ctx: MessageSuccessContext): void;
+    /**
+     * Message 级开始日志（仅 logInfo，不发 Counter）。
+     */
+    reportMessageStart(ctx: MessageStartContext): void;
+    /** Tool 调用开始（PreToolUse） — logInfo。 */
+    reportToolStart(ctx: ToolStartContext): void;
+    /** Tool 调用成功（PostToolUse 且 tool_response 不是 error） — logInfo。 */
+    reportToolSuccess(ctx: ToolSuccessContext): void;
+    /**
+     * Tool 调用失败（PostToolUseFailure，或 PostToolUse + is_error=true） — logError。
+     * 用户主动取消（Abort）由调用方过滤。
+     */
+    reportToolError(ctx: ToolErrorContext): void;
+}

package/cli/dist-server/types/node/galileo/galileo-protocol.d.ts

@@ -0,0 +1,78 @@
+/**
+ * GalileoService — CLI 进程伽利略可观测抽象接口
+ *
+ * 通过纯 HTTPS OTLP HTTP JSON 协议上报 Metrics/Logs 到伽利略平台，
+ * 提供 Histogram（耗时）、Counter（计数）、Logger（结构化日志）三类上报。
+ * 所有方法在未就绪时降级为 noop，不影响 Agent 主逻辑。
+ */
+export declare const GalileoService: unique symbol;
+export interface GalileoService {
+    /** Histogram 上报（耗时类指标，伽利略自动聚合 P50/P95/P99） */
+    recordDuration(metric: string, durationMs: number, dimensions?: Record<string, string>): void;
+    /** Counter 上报（计数类指标，支持批量 add） */
+    addCounter(metric: string, count: number, dimensions?: Record<string, string>): void;
+    /** 结构化日志上报（info 级别，供伽利略 Log 视图查询） */
+    logInfo(message: string, attributes?: Record<string, string | number | boolean>): void;
+    /** 结构化日志上报（error 级别） */
+    logError(message: string, attributes?: Record<string, string | number | boolean>): void;
+    /** SDK 是否初始化成功 */
+    isReady(): boolean;
+    /**
+     * 等待 SDK 后台初始化完成（带超时保护）。
+     *
+     * 用于需要创建真实 span 的调用方（如 TraceStartHook）在冷启动时
+     * 等待 Galileo SDK 注册全局 TracerProvider，避免拿到 NonRecordingSpan。
+     * 超时后 resolve（不抛错），调用方应检查 isReady() 自行降级。
+     *
+     * @param timeoutMs 等待上限，默认 5000ms
+     */
+    waitReady(timeoutMs?: number): Promise<void>;
+    /**
+     * 等待 galileo SDK 初始化完成（含 AgentLens primary 双报通道挂载）。
+     *
+     * 非交互快速进程（`-p` / stream-json）在 SDK 就绪前开始 agent run 时，
+     * 业务 span 会因 OTel ProxyTracer 未代理到真实 provider 而变成 NonRecordingSpan
+     * 整体丢失（Issue #83191）。调用方应在发起 agent 请求前调用本方法，
+     * 把「SDK 就绪」变为请求的前置条件。
+     *
+     * 语义：
+     * - 已就绪 / 已判定未启用：立即返回当前 ready 状态；
+     * - 初始化中：await 在途 _initPromise（受 deadline 约束，不阻塞超过 timeoutMs）；
+     * - 超时：返回 false，调用方按有界降级处理（不抛错）。
+     *
+     * 注意：返回 `false` **不区分「已判定未启用」与「启用但超时未就绪」**，
+     * 调用方需结合 `process.env.GALILEO_ENABLE`（'true' 表示已判定启用）与
+     * `GALILEO_SDK_READY`（'0' 表示 doInit 失败）判断具体语义，避免误报。
+     *
+     * @param timeoutMs 等待总耗时上限，默认 10000ms
+     */
+    waitForReady(timeoutMs?: number): Promise<boolean>;
+    /**
+     * 强制 flush OTel provider buffer（metrics + trace + logs），但**不关闭** provider。
+     *
+     * 适用场景：进程退出前的"第一阶段" —— 先把已有数据推出去，但后续 cleanup 逻辑
+     * 仍可继续上报（如 SessionEnd hook 可能再打 counter/log）。
+     *
+     * 实现：
+     * - **可重复调用**：每次都真正 forceFlush（非幂等缓存）
+     * - **自带 deadline**：内部最多等 `timeoutMs`，超时后强制 resolve，不抛错
+     * - **SDK 未就绪时 noop**
+     *
+     * @param timeoutMs flush 总耗时上限，默认 2000ms
+     */
+    forceFlush(timeoutMs?: number): Promise<void>;
+    /**
+     * 强制 flush + 关闭底层 OTel provider。调用后 provider 不再接受新数据。
+     *
+     * 适用场景：进程退出前的"最终阶段" —— 所有 cleanup/session-end 逻辑跑完后，
+     * 做最后一次 flush 并 shutdown provider。
+     *
+     * 实现：
+     * - **幂等**：可重复调用，二次起直接 noop
+     * - **自带 deadline**：内部最多等 `timeoutMs`（默认 2000），超时后强制 resolve，不抛错
+     * - **SDK 未就绪时 noop**：`ready=false` 时直接 resolve
+     *
+     * @param timeoutMs flush + shutdown 总耗时上限，默认 2000ms
+     */
+    shutdown(timeoutMs?: number): Promise<void>;
+}

package/cli/dist-server/types/node/galileo/galileo-service.d.ts

@@ -0,0 +1,171 @@
+/**
+ * GalileoServiceImpl — @tencent/galileo-node-sdk 封装
+ *
+ * 生命周期：
+ *   initialize() — 同步；普通启动立即检查环境变量，prewarm standby 延后到 activate
+ *   onStart()    — 异步但**不阻塞**：将 SDK 初始化存为后台 promise（fire-and-forget），
+ *                  不 await，避免阻塞 CellJS ApplicationLifecycle 串行链路
+ *                  （串行 await 会推迟 HTTP Server listen → 推迟 ACP Server 就绪 → 阻塞会话打开）
+ *
+ * 降级策略：SDK 加载/初始化失败时全链路降级为 noop，不影响 CLI 主逻辑。
+ * 关闭方式：设 DISABLE_GALILEO=1 环境变量。
+ */
+import { Application, ApplicationLifecycle } from '@celljs/core';
+import { AuthenticationManager } from '../../workspace/authentication/lib/common/index.js';
+import { ClientInfoProvider, ProductManager } from '../../workspace/product/lib/common/index.js';
+import { Logger, TracerProvider } from '../../workspace/telemetry/lib/common/index.js';
+import { type IPrewarmStateService } from '../prewarm/prewarm-protocol';
+import { GalileoService } from './galileo-protocol';
+export declare function isGalileoOtlpRequest(input: unknown, galileoHostname: string): boolean;
+export declare class GalileoServiceImpl implements GalileoService, ApplicationLifecycle<Application> {
+    protected readonly logger: Logger;
+    protected readonly productManager: ProductManager;
+    protected readonly clientInfoProvider: ClientInfoProvider | undefined;
+    protected readonly authenticationManager: AuthenticationManager | undefined;
+    protected readonly tracerProvider: TracerProvider | undefined;
+    protected readonly prewarmState?: IPrewarmStateService;
+    private ready;
+    private meter;
+    private galileoLogger;
+    private tracer;
+    private startupSpan;
+    private otelMeterProvider;
+    private otelTracerProvider;
+    private otelLoggerProvider;
+    private shutdownPromise;
+    private histograms;
+    private counters;
+    private authSubscription;
+    private productConfigDisposable;
+    private galileoFingerprint;
+    /**
+     * 同步初始化 — 检查环境变量后 fire-and-forget 启动 SDK 初始化。
+     * prewarm standby 期延后整个判定，避免读取 activate merge 前的环境。
+     */
+    initialize(): void;
+    private _initializationStarted;
+    private _activationDeferred;
+    private _shouldInit;
+    private _ValueType;
+    /** 后台初始化 promise — forceFlush/shutdown 会 await 它确保初始化完成再操作 */
+    private _initPromise;
+    /** 标记 onStop 已被调用，防止 doInit 后台跑完后再 subscribe（竞态保护） */
+    private _stopped;
+    /**
+     * 异步生命周期钩子 — **不阻塞**框架启动。
+     *
+     * 将实际 SDK 初始化存为后台 promise（fire-and-forget）：
+     * CellJS AbstractApplication.doStart() 串行 await 每个 lifecycle.onStart()，
+     * 如果这里 await waitConfiguration / SetupGalileo，会推迟 HTTP Server listen，
+     * 进而推迟 ACP Server 就绪，阻塞 IDE 会话打开。
+     */
+    onStart(): Promise<void>;
+    /**
+     * 后台初始化 — 读取 product.json 顶层 Galileo.enable 开关，按需启动 SDK。
+     * 任何异常都降级为 noop，不影响主流程。
+     */
+    private doInit;
+    onStop(): void;
+    private _patchName;
+    private _clientVersion;
+    private _uid;
+    private _gpuModel;
+    private _gpuVram;
+    private doSetup;
+    recordDuration(metric: string, durationMs: number, dimensions?: Record<string, string>): void;
+    addCounter(metric: string, count: number, dimensions?: Record<string, string>): void;
+    /**
+     * SDK 的 ExtAttributes 类型定义为 `{ [key: string]: string }`，
+     * 把 number/boolean/null/undefined 统一转成 string，避免被 SDK 内部序列化静默丢弃字段。
+     */
+    private normalizeAttributes;
+    logInfo(message: string, attributes?: Record<string, string | number | boolean>): void;
+    logError(message: string, attributes?: Record<string, string | number | boolean>): void;
+    isReady(): boolean;
+    waitReady(timeoutMs?: number): Promise<void>;
+    /**
+     * 等待 galileo SDK 初始化完成（含 AgentLens primary 双报通道挂载）。
+     *
+     * 非交互快速进程（`-p` / stream-json）在 SDK 就绪前开始 agent run 时，
+     * 业务 span 会因 OTel ProxyTracer 未代理到真实 provider 而变成 NonRecordingSpan
+     * 整体丢失（Issue #83191）。由 CliExecutor 在发请求前调用，把「SDK 就绪」变为
+     * 请求的前置条件。
+     *
+     * - 已就绪 / 已判定未启用：立即返回当前 ready 状态；
+     * - 初始化中：await 在途 _initPromise（受 deadline 约束）；
+     * - 超时：返回 false，调用方按有界降级处理（不抛错）。
+     */
+    waitForReady(timeoutMs?: number): Promise<boolean>;
+    /**
+     * 强制 flush OTel provider buffer（metrics + trace + logs），但不关闭 provider。
+     *
+     * 用途：退出前"第一阶段" —— 先把已有数据推出去，后续 cleanup 仍可继续上报。
+     * 可重复调用（每次都真正 forceFlush），与 shutdown 的幂等缓存互不影响。
+     */
+    forceFlush(timeoutMs?: number): Promise<void>;
+    /**
+     * 强制 flush + 关闭底层 OTel provider。调用后 provider 不再接受新数据。
+     *
+     * 用途：退出前"最终阶段" —— 所有 cleanup/session-end 跑完后做最后一次 flush 并 shutdown。
+     *
+     * 实现要点：
+     * - **幂等**：缓存 `shutdownPromise`，二次调用直接返回首次的 promise
+     * - **总耗时上限 timeoutMs**：避免拖住 CLI 退出。三个 provider 共用一个 deadline。
+     * - **任何失败都吞掉**：监控自身不能阻塞进程退出。
+     */
+    shutdown(timeoutMs?: number): Promise<void>;
+    /**
+     * 定位 logs 通道可 forceFlush 的句柄 —— 退出前 flush 日志用。
+     *
+     * 伽利略 SDK 的 Logger 在 `initLogger()` 里把 LoggerProvider 当局部变量持有、只返回
+     * `loggerProvider.getLogger(...)` 的结果，外部拿不到 provider 本身。因此按以下顺序探测：
+     * provider 反向引用（`_loggerProvider` / `loggerProvider`）→ `_sharedState.activeProcessor`。
+     * SDK 0.3.x 依赖的 OTel sdk-logs Logger 只暴露 `_sharedState`，其 activeProcessor 同样实现
+     * forceFlush/shutdown（LoggerProvider 本身也只是转调它），是这些版本上唯一可用的句柄。
+     *
+     * 全部探测失败时返回 null —— 只影响退出前的日志 flush，不影响主流程。
+     */
+    private resolveLogFlushHandle;
+    /**
+     * Promise + deadline 竞速：
+     * - 到 deadline 强制 resolve（不抛），让上层 safe() 继续往下走
+     * - promise 自己抛错则**透传 reject**，由上层 safe() 的 try/catch 接住并 warn 哪一路坏了
+     * `label` 仅用于排错日志区分通道。
+     */
+    private withTimeout;
+    /** 注入 turn baggage 与全局维度；调用方显式 dimensions 优先。 */
+    private withGlobalDimensions;
+    /** 注入 turn baggage 与全局属性；调用方显式 attrs 优先。 */
+    private withGlobalAttrs;
+    private static otlpHttpProxyAgentPatched;
+    /**
+     * Galileo SDK 的 OTLP/HTTP exporter 默认不会读 HTTPS_PROXY；并且它内部依赖路径在
+     * Rspack bundle 后不适合直接 require/patch。这里改为对 Node https.request 做一个
+     * 很窄的补丁：只给当前 Galileo endpoint hostname 的 HTTPS 请求注入 HttpsProxyAgent。
+     */
+    private patchOtlpHttpProxyAgent;
+    private handleProductConfigurationChanged;
+    /**
+     * 构造 GalileoLogger 全局静态属性 — SDK 会把这些自动挂到每条 log 的 tags.* 下。
+     *
+     * 设计原则：
+     * - **只挂静态值**（构造一次永久复用）。运行时易变值（freemem / uptime / heap）
+     *   走 metrics（gauge / histogram）通道，不要塞 attribute。
+     * - **不挂隐私敏感字段**（hostname / userInfo），避免 PII 泄露。
+     * - **不与伽利略后台 IP enrich 字段重复**（country/city/ip/isp 由后台自动塞）。
+     * - **value 全部 string**（SDK 类型 `Attributes = { [k: string]: string }` 强约束）。
+     * - **可选字段缺失时不下发**（不下发空字符串），便于 BI 用 `tags.x =~ ".+"` 干净过滤。
+     *
+     * 字段来源：
+     * - `os` / `arch` / `osVersion` / `cpuCores` / `cpuModel` / `memoryGB`：Node 内置 API
+     * - `nodeVersion`：`process.version`
+     * - `appName` / `appVersion` / `extName` / `extVersion` / `ideType` / `downloadChannel`：
+     *   desktop main 通过 `CLIENT_INFO_*` 环境变量注入（见
+     *   `apps/workbuddy-desktop/src/main/runtime/workbuddy-client-info-env.ts`）；
+     *   裸 agent-cli 模式下 fallback 为 `'agent-cli'` 或不下发。
+     */
+    private buildGlobalLogAttributes;
+    private static readonly execFileAsync;
+    private static readonly GPU_DETECT_TIMEOUT_MS;
+    private detectGpuInfo;
+}