@ai-setting/roy-agent-core 1.7.52 → 1.7.53

package/dist/env/log-trace/decorator.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @fileoverview @Traced 装饰器实现
+ *
+ * 提供函数包装和装饰器来自动创建 Span
+ * 支持注解到 async 函数和非 async 函数上
+ * 使用 OpenTelemetry 标准方式
+ */
+export interface TracedOptions {
+    name?: string;
+    recordParams?: boolean;
+    recordResult?: boolean;
+    recordError?: boolean;
+    log?: boolean;
+    maxLogSize?: number;
+    paramFilter?: (args: any[], argNames?: string[]) => Record<string, any>;
+    /**
+     * NEW: result filter - returns object whose keys are spread as top-level
+     * span attributes. Used to expose named result fields (e.g. diagnostics.length,
+     * cache.hit) for cli-e2e-test field-shape verification.
+     */
+    resultFilter?: (result: any) => Record<string, any>;
+    /**
+     * NEW: when true (default false), spread paramFilter output keys to top-level
+     * attributes in addition to attributes['params']. Used to expose named
+     * parameter fields (e.g. serverIds, workspaceRoot) for cli-e2e-test.
+     */
+    flattenParamFilter?: boolean;
+    /**
+     * NEW: 返回值驱动的 ERROR 状态。
+     *
+     * 返回 Error（或任意 truthy）→ 即使函数**正常返回**，也把 span 标成 ERROR；
+     * 返回 undefined / null / false → 保持 OK。
+     *
+     * 解决什么：有些 API 用返回值而不是抛异常来表达失败，例如工具执行返回
+     * `{ success: false, error: "Tool not found: bash" }`。旧行为下 span.status
+     * 仍是 `ok`（错误只落在 result 属性里），`roy-agent debug trace --list`
+     * 聚合出来的 status 全是 ok —— 2026-10-16 的空 checkpoint 事故就是这样
+     * 静默了几周，直到人工翻 25GB trace DB 才发现。
+     *
+     * 为什么不用抛异常：ReAct 循环需要把失败作为 tool result 回灌给模型
+     * （AI SDK v6 要求 tool-call / tool-result 1:1 配对）。抛异常会破坏配对，
+     * 所以只能在「返回值已是失败」的前提下补一个 span 状态。
+     */
+    errorIf?: (result: any) => Error | string | undefined | null | false;
+}
+/**
+ * @Traced 装饰器工厂
+ *
+ * 同时支持两种调用约定，避免 toolchain 差异导致崩溃：
+ *   1. Legacy（TS experimentalDecorators）: (target, propertyKey, descriptor)
+ *      — 改写 descriptor.value，返回 descriptor。
+ *   2. Standard（TC39 / Bun __decorateElement）: (value, context)
+ *      — 返回包装后的函数；context.name 作为默认 span 名。
+ *
+ * 背景：同一 tsconfig（experimentalDecorators: true）下，Bun 对个别文件
+ * （如 event-store.ts）会走 standard 装饰器路径，只传 2 个参数，导致旧实现
+ * `descriptor.value` 读到 undefined 崩溃。
+ */
+export declare function Traced(options?: TracedOptions): (target: any, propertyKey?: any, descriptor?: any) => any;
+/**
+ * @TracedAs 装饰器工厂 - 使用自定义名称
+ */
+export declare function TracedAs(name: string, options?: Omit<TracedOptions, "name">): (target: any, propertyKey?: any, descriptor?: any) => any;
+/**
+ * @TracedLightweight 装饰器工厂 - 轻量级追踪
+ */
+export declare function TracedLightweight(options?: {
+    log?: boolean;
+    maxLogSize?: number;
+}): (target: any, propertyKey?: any, descriptor?: any) => any;
+/**
+ * 包装函数以自动创建 Span
+ *
+ * 同时支持 async 函数和非 async 函数：
+ * - async 函数：自动检测 Promise 并正确处理
+ * - 非 async 函数：同步执行，直接返回结果
+ */
+export declare function wrapFunction<T extends (...args: any[]) => any>(fn: T, name: string, options?: {
+    recordParams?: boolean;
+    recordResult?: boolean;
+    recordError?: boolean;
+    log?: boolean;
+    maxLogSize?: number;
+    paramFilter?: (args: any[], argNames?: string[]) => Record<string, any>;
+    resultFilter?: (result: any) => Record<string, any>;
+    flattenParamFilter?: boolean;
+    errorIf?: (result: any) => Error | string | undefined | null | false;
+}): T;

package/dist/env/log-trace/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Log & Trace 模块导出
+ *
+ * OpenTelemetry 标准接口
+ */
+export { type Span, type SpanContext, type SpanAttributes, type TraceInfo, type SpanStorage, type ITraceContext, type LogLevel, type LoggerConfig, type ILogger, type TraceContextOptions, } from "./types";
+export { SpanKind, SpanStatus } from "./types";
+export { SQLiteSpanStorage } from "./span-storage";
+export { LogTraceComponent, type LogTraceConfig, type LogTraceComponentOptions, LogTraceConfigSchema, getDefaultLogDir, getDefaultSpanDbPath, } from "./log-trace-component";
+export { OTelTracerProvider, getTracerProvider, resetTracerProvider, type OTelTracer, type OTelSpan, type SpanOptions, } from "./opentelemetry/tracer-provider";
+export { propagation, serialize, parse, type ExtractedContext, } from "./opentelemetry/propagation";
+export { injectToEnv, injectToEnvWithContext, injectToEnvFromCarrier, getTraceparentHeader, type EnvCarrier, } from "./opentelemetry/propagation-env";
+export { createLogger, setQuietMode, isQuietMode, setConfigComponent as setLoggerConfigComponent, getLogLevel, getLogLevels, getLogDir, getLogFile, setLogDirOverride, getLogDirOverride, simplifyFilePath, getMaxOutput, } from "./logger";
+export { TracedAs, Traced, TracedLightweight, wrapFunction, type TracedOptions } from "./decorator";

package/dist/env/log-trace/log-trace-component.d.ts

@@ -0,0 +1,268 @@
+/**
+ * @fileoverview Log & Trace Component
+ *
+ * 提供日志和追踪的统一组件封装
+ *
+ * 配置通过 ConfigComponent 实时获取，支持配置热更新
+ */
+import { BaseComponent, type ComponentConfig, type ComponentSchema } from "../component";
+import { z } from "zod";
+import { createLogger, type LogLevel } from "./logger";
+import { type OTelTracer } from "./opentelemetry/tracer-provider";
+import { type ITraceContext } from "./trace-context";
+import type { ConfigComponent } from "../../config/config-component";
+/**
+ * 获取默认日志目录（基于 XDG 标准）
+ * 存储在 XDG_DATA_HOME/roy-agent/logs/
+ */
+export declare function getDefaultLogDir(): string;
+/**
+ * 获取默认的 span 数据库路径（基于 XDG 标准）
+ * 存储在 XDG_DATA_HOME/roy-agent/traces.db
+ */
+export declare function getDefaultSpanDbPath(): string;
+/**
+ * Log & Trace Component 配置 Schema
+ */
+export declare const LogTraceConfigSchema: z.ZodObject<{
+    /** 是否启用日志 */
+    logging: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        level: z.ZodDefault<z.ZodEnum<["debug", "info", "warn", "error"]>>;
+        quiet: z.ZodDefault<z.ZodBoolean>;
+        file: z.ZodDefault<z.ZodString>;
+        dir: z.ZodDefault<z.ZodString>;
+        /** 日志输出最大长度（0 表示不限制） */
+        maxOutput: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        file: string;
+        level: "error" | "debug" | "info" | "warn";
+        quiet: boolean;
+        dir: string;
+        maxOutput: number;
+    }, {
+        enabled?: boolean | undefined;
+        file?: string | undefined;
+        level?: "error" | "debug" | "info" | "warn" | undefined;
+        quiet?: boolean | undefined;
+        dir?: string | undefined;
+        maxOutput?: number | undefined;
+    }>>;
+    /** 是否启用追踪 */
+    tracing: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        dbPath: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        dbPath?: string | undefined;
+    }, {
+        enabled?: boolean | undefined;
+        dbPath?: string | undefined;
+    }>>;
+    /** 初始化请求上下文 */
+    initContext: z.ZodOptional<z.ZodObject<{
+        requestId: z.ZodOptional<z.ZodString>;
+        sessionId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        requestId?: string | undefined;
+        sessionId?: string | undefined;
+    }, {
+        requestId?: string | undefined;
+        sessionId?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    logging: {
+        enabled: boolean;
+        file: string;
+        level: "error" | "debug" | "info" | "warn";
+        quiet: boolean;
+        dir: string;
+        maxOutput: number;
+    };
+    tracing: {
+        enabled: boolean;
+        dbPath?: string | undefined;
+    };
+    initContext?: {
+        requestId?: string | undefined;
+        sessionId?: string | undefined;
+    } | undefined;
+}, {
+    logging?: {
+        enabled?: boolean | undefined;
+        file?: string | undefined;
+        level?: "error" | "debug" | "info" | "warn" | undefined;
+        quiet?: boolean | undefined;
+        dir?: string | undefined;
+        maxOutput?: number | undefined;
+    } | undefined;
+    tracing?: {
+        enabled?: boolean | undefined;
+        dbPath?: string | undefined;
+    } | undefined;
+    initContext?: {
+        requestId?: string | undefined;
+        sessionId?: string | undefined;
+    } | undefined;
+}>;
+export type LogTraceConfig = z.infer<typeof LogTraceConfigSchema>;
+/**
+ * LogTraceComponent 配置选项（通过 options 传递）
+ *
+ * 配置加载顺序（优先级从低到高）：
+ * 1. File - 配置文件（通过 configPath 指定）
+ * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+ * 3. Object - 直接传入的 config 对象（最高优先级）
+ */
+export interface LogTraceComponentOptions {
+    /** ConfigComponent 实例（必填） */
+    configComponent: ConfigComponent;
+    /** 配置文件相对路径（可选，基于 XDG_DATA_HOME） */
+    configPath?: string;
+    /** 环境变量前缀（可选，默认 "LOG"） */
+    envPrefix?: string;
+    /**
+     * 项目根目录（可选，默认 process.cwd()）
+     * 用于加载 ${cwd}/.roy/config.jsonc 项目级配置
+     */
+    cwd?: string;
+    /** 回调函数 */
+    callbacks?: {
+        onLogLevelChange?: (level: LogLevel) => void;
+    };
+    /** 直接传入的配置对象（可选，优先级最高） */
+    config?: Partial<LogTraceConfig>;
+}
+/**
+ * Log & Trace Component
+ *
+ * 提供统一的日志和追踪能力
+ * 配置通过 ConfigComponent 实时获取，支持配置热更新
+ *
+ * @example
+ * // 通过 ConfigComponent 初始化
+ * const configComponent = new ConfigComponent();
+ * const component = new LogTraceComponent();
+ * await component.init({
+ *   env,  // Environment 实例（必填）
+ *   options: { configComponent }
+ * });
+ *
+ * // 配置更新后，日志级别会自动热更新
+ * configComponent.set("log-trace.logging.level", "debug");
+ *
+ * // 初始化追踪上下文
+ * component.initContext("request-123", "session-456");
+ *
+ * // 使用日志
+ * component.getLogger().info("Hello, world!");
+ *
+ * // 使用追踪
+ * const span = component.getTracer().startSpan("my-span");
+ * component.getTracer().endSpan(span);
+ */
+export declare class LogTraceComponent extends BaseComponent {
+    readonly name = "log-trace";
+    readonly version = "1.0.0";
+    private config?;
+    private configComponent?;
+    private tracer?;
+    private traceContext?;
+    /** 配置变更 watcher 清理函数 */
+    private configWatcher?;
+    constructor();
+    /**
+     * 初始化组件
+     *
+     * 配置加载优先级（从高到低）：
+     * 1. Object - 直接传入的 config 对象
+     * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+     * 3. File - 配置文件（通过 configPath 指定）
+     */
+    init(config: ComponentConfig): Promise<void>;
+    /**
+     * 注册配置到 ConfigComponent
+     *
+     * 遵循 SessionComponent 模式：
+     * 1. 使用 registerComponent 注册配置结构
+     * 2. 使用 load 加载配置
+     * 3. 设置默认值
+     * 4. 处理环境变量后备方案
+     * 5. 处理 config 对象
+     *
+     * 配置加载顺序（优先级从低到高）：
+     * 1. FileSource - 从配置文件加载（最低）
+     * 2. EnvSource - 从环境变量加载（中等）
+     * 3. MemorySource - 直接配置对象（最高）
+     */
+    private registerConfig;
+    /**
+     * 将配置对象展平为点号路径
+     */
+    private flattenConfig;
+    /**
+     * 注册配置热更新监听
+     */
+    private registerConfigWatcher;
+    /**
+     * 处理配置变更
+     */
+    protected onConfigChange(event: {
+        key: string;
+        oldValue?: unknown;
+        newValue?: unknown;
+    }): void;
+    /**
+     * 创建存储实例
+     *
+     * @throws Error 如果未配置 dbPath
+     */
+    private createStorage;
+    /**
+     * 配置日志系统
+     *
+     * 默认 quiet 模式开启，除非显式设置为 false
+     */
+    private configureLogging;
+    /**
+     * 初始化追踪上下文
+     *
+     * @param requestId 请求 ID
+     * @param sessionId 会话 ID（可选）
+     */
+    initContext(requestId: string, sessionId?: string): void;
+    /**
+     * 创建新的追踪上下文（返回清理函数）
+     *
+     * @param requestId 请求 ID
+     * @param sessionId 会话 ID（可选）
+     */
+    startContext(requestId: string, sessionId?: string): () => void;
+    /**
+     * 获取 Logger
+     *
+     * @param prefix 日志前缀
+     */
+    getLogger(prefix?: string): ReturnType<typeof createLogger>;
+    /**
+     * 获取 Tracer
+     */
+    getTracer(): OTelTracer;
+    /**
+     * 获取 Trace Context
+     */
+    getTraceContext(): ITraceContext | undefined;
+    /**
+     * 获取当前 requestId
+     */
+    getRequestId(): string | undefined;
+    /**
+     * 停止组件
+     */
+    onStop(): Promise<void>;
+}
+/**
+ * Log & Trace Component Schema
+ */
+export declare const logTraceComponentSchema: ComponentSchema;

package/dist/env/log-trace/log-trace-config-registration.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @fileoverview LogTrace Component 配置注册
+ *
+ * 使用 ConfigComponent.registerComponent() 机制统一管理配置
+ */
+import type { ComponentRegistration } from "../../config/config-component";
+/**
+ * LogTrace Component 默认配置值
+ *
+ * 注意：键使用完整格式（带 "log-trace." 前缀），在 registerConfig 中手动设置
+ * 注意：动态默认值（logging.dir, logging.file, logging.maxOutput）在 registerConfig 中单独处理
+ */
+export declare const LOG_TRACE_DEFAULTS: Record<string, unknown>;
+/**
+ * LogTrace Component 配置注册常量
+ *
+ * 定义了所有 LogTrace 相关的配置项和来源
+ *
+ * Source 优先级（数值越大越高）：
+ * - project: 25（${cwd}/.roy/config.jsonc，最高优先级）— 由 LogTraceComponent.registerConfig() 手动注册
+ * - env:     20（环境变量）
+ * - file:    10（全局 XDG 配置，默认）
+ * - memory:   0（默认值，代码设置）
+ */
+export declare const LOG_TRACE_CONFIG_REGISTRATION: ComponentRegistration;

package/dist/env/log-trace/logger.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @fileoverview Logger - 统一日志系统
+ *
+ * 遵循 XDG Base Directory Specification:
+ * - 日志存储在 XDG_DATA_HOME/roy-agent/logs/ (默认 ~/.local/share/roy-agent/logs/)
+ * 无需配置，自动创建目录
+ *
+ * 支持 traceId 追踪：通过 trace-context 模块自动注入
+ *
+ * 配置优先级（从高到低）：
+ * 1. ConfigComponent (log-trace.logging.level, log-trace.logging.dir)
+ * 2. 环境变量 (LOG_LEVEL, LOG_DIR)
+ * 3. setLogDirOverride() 手动设置
+ * 4. XDG 默认路径
+ */
+/**
+ * 简化 Bun file: 协议的编码路径
+ * 例如: packages+core/node_modules/.bun/@roy-agent+core@file+packages+core/node_modules/@roy-agent/core/src/env/agent/agent-component.ts
+ * 转换为: packages/core/src/env/agent/agent-component.ts
+ */
+export declare function simplifyFilePath(fullPath: string): string;
+import type { LogLevel, ILogger } from "./types";
+export declare function isQuietMode(): boolean;
+export declare function setQuietMode(enabled: boolean): void;
+/**
+ * 设置 ConfigComponent 实例（用于实时配置读取）
+ */
+export declare function setConfigComponent(component: any): void;
+/**
+ * 获取日志级别（支持热更新）
+ */
+export declare function getLogLevel(): LogLevel;
+/**
+ * 获取指定类别的日志级别
+ *
+ * 支持按类别配置日志级别，配置路径：log-trace.logging.levels.<category>
+ *
+ * @param category 日志类别（如 "llm", "agent", "tool"）
+ * @returns 该类别的日志级别，如果未配置则返回全局级别
+ */
+export declare function getCategoryLogLevel(category: string): LogLevel;
+/**
+ * 获取日志文件名
+ * 实时从 ConfigComponent 读取（支持 env/file/memory 多 source）
+ */
+export declare function getLogFile(): string;
+export declare function getLogDir(): string;
+/**
+ * 获取日志输出最大长度配置
+ * 实时从 ConfigComponent 读取
+ *
+ * @returns 配置的值（0 表示不限制），如果未配置则返回 undefined
+ */
+export declare function getMaxOutput(): number | undefined;
+export declare function setLogDirOverride(dir: string): void;
+export declare function getLogDirOverride(): string | undefined;
+declare class Logger implements ILogger {
+    private prefix;
+    constructor(prefix: string);
+    private shouldLog;
+    private ensureLogDirectory;
+    private getCallerLocation;
+    private getRelativePath;
+    private formatMessage;
+    private writeToFile;
+    private log;
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+}
+/**
+ * 创建或获取 Logger 实例
+ * @param prefix Logger 前缀
+ *
+ * 日志文件名通过 ConfigComponent 实时读取（log-trace.logging.file）
+ */
+export declare function createLogger(prefix: string): Logger;
+/**
+ * 获取所有日志级别
+ */
+export declare function getLogLevels(): LogLevel[];
+export type { LogLevel, ILogger } from "./types";

package/dist/env/log-trace/opentelemetry/cli-propagation.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @fileoverview CLI Propagation 模块
+ *
+ * 提供 CLI 启动时从环境变量提取 trace context 的功能：
+ * - 从 TRACEPARENT 环境变量提取父 span context
+ * - 支持 W3C TraceContext 格式
+ *
+ * 使用场景：
+ * - Workflow CLI 启动时从父进程传递 trace context
+ * - 子进程能够关联到主进程的 trace
+ */
+import type { SpanContext } from '../types';
+/**
+ * CLI 传播选项
+ */
+export interface CliPropagationOptions {
+    /** 是否静默模式（不输出日志） */
+    silent?: boolean;
+    /** 自定义 carrier（默认从 process.env 读取） */
+    carrier?: Record<string, string | undefined>;
+}
+/**
+ * 提取结果
+ */
+export interface ExtractResult {
+    /** 提取的 traceId */
+    traceId: string;
+    /** 父 spanId（新 span 的 parentSpanId） */
+    parentSpanId: string;
+    /** 原始的 traceparent 字符串 */
+    rawTraceparent: string;
+}
+/**
+ * 从环境变量提取 trace context
+ *
+ * @param options 传播选项
+ * @returns 提取结果，如果不存在则返回 undefined
+ */
+export declare function extractFromEnv(options?: CliPropagationOptions): ExtractResult | undefined;
+/**
+ * 从提取结果构建 SpanContext
+ *
+ * 用于初始化 OTelTracerProvider 时构建传入的上下文
+ *
+ * @param extracted 提取结果
+ * @returns 适用于初始化 provider 的 SpanContext
+ */
+export declare function buildSpanContextFromExtracted(extracted: ExtractResult): SpanContext;
+/**
+ * 从提取结果构建完整 SpanContext（包含占位 spanId）
+ *
+ * 用于初始化 OTelTracerProvider 的 tracer.currentContext
+ *
+ * @param extracted 提取结果
+ * @returns SpanContext，其中 spanId 待 provider 生成新值
+ */
+export declare function buildInitialSpanContext(extracted: ExtractResult): SpanContext;
+/**
+ * CLI 初始化追踪器
+ *
+ * 从环境变量提取 trace context 并初始化 OTelTracerProvider
+ *
+ * 使用场景：
+ * ```typescript
+ * // 在 CLI 启动时调用
+ * import { initTracerFromEnv } from './opentelemetry/cli-propagation';
+ * import { getTracerProvider } from './opentelemetry/tracer-provider';
+ *
+ * async function main() {
+ *   const provider = getTracerProvider();
+ *   await provider.initialize();
+ *
+ *   // 尝试从环境变量恢复上下文
+ *   initTracerFromEnv(provider);
+ *
+ *   // 继续正常执行...
+ * }
+ * ```
+ *
+ * @param provider OTelTracerProvider 实例
+ * @param options 传播选项
+ */
+export declare function initTracerFromEnv(provider: {
+    getTracer: (name: string) => {
+        setCurrentContext: (ctx: SpanContext | undefined) => void;
+    };
+}, options?: CliPropagationOptions): void;
+/**
+ * 检查是否存在 trace context
+ *
+ * @returns 是否存在有效的 trace context
+ */
+export declare function hasTraceContext(): boolean;
+/**
+ * 获取当前 traceId（如果存在）
+ *
+ * @returns traceId 或 undefined
+ */
+export declare function getTraceId(): string | undefined;
+/**
+ * 获取当前 parentSpanId（如果存在）
+ *
+ * @returns parentSpanId 或 undefined
+ */
+export declare function getParentSpanId(): string | undefined;

package/dist/env/log-trace/opentelemetry/mod.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview OpenTelemetry 模块统一导出
+ *
+ * @example
+ * import { getTracerProvider, propagation } from './opentelemetry/mod';
+ *
+ * // 初始化
+ * const provider = getTracerProvider();
+ * await provider.initialize();
+ *
+ * // 获取 Tracer
+ * const tracer = provider.getTracer('my-service');
+ *
+ * // 启动 Span
+ * const span = tracer.startSpan('my-operation');
+ *
+ * // 注入到环境变量
+ * const env: Record<string, string | undefined> = {};
+ * tracer.injectToEnv(env);
+ * process.env = { ...process.env, ...env };
+ */
+export { OTelTracerProvider, getTracerProvider, resetTracerProvider, type OTelTracer, type OTelSpan, type SpanOptions } from './tracer-provider';
+export { propagation, serialize, parse, type ExtractedContext } from './propagation';
+export { injectToEnv, injectToEnvWithContext, injectToEnvFromCarrier, getTraceparentHeader, type EnvCarrier } from './propagation-env';

package/dist/env/log-trace/opentelemetry/propagation-env.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @fileoverview Propagation Env Module
+ *
+ * 提供便捷的环境变量注入功能，用于在子进程执行时传递 trace context。
+ *
+ * @example
+ * ```typescript
+ * import { injectToEnv, injectToEnvWithContext } from './propagation-env';
+ *
+ * // 在 Bash 工具中执行子进程前：
+ * const traceEnv = injectToEnv();  // 从当前 OTelTracerProvider 获取并注入
+ * const options = {
+ *   env: { ...process.env, ...traceEnv, ...env },
+ * };
+ * spawn(command, args, options);
+ * ```
+ */
+import type { SpanContext } from "../types";
+/**
+ * 环境变量对象类型
+ */
+export type EnvCarrier = Record<string, string | undefined>;
+/**
+ * 从当前 OTelTracerProvider 获取上下文并注入到环境变量
+ *
+ * 这是一个便捷函数，封装了常见的注入模式：
+ * 1. 从全局 TracerProvider 获取当前 Tracer
+ * 2. 获取当前 span context
+ * 3. 注入到目标环境变量
+ *
+ * @param env 目标环境变量对象（默认：{}）
+ * @returns 注入了 TRACEPARENT 的环境变量对象
+ *
+ * @example
+ * ```typescript
+ * const env = injectToEnv({ PATH: '/usr/bin' });
+ * // env.TRACEPARENT = '00-{traceId}-{spanId}-01'
+ * // env.PATH = '/usr/bin'
+ * ```
+ */
+export declare function injectToEnv(env?: EnvCarrier): EnvCarrier;
+/**
+ * 将指定的 SpanContext 直接注入到环境变量
+ *
+ * 与 injectToEnv 不同，这个函数不需要访问全局 TracerProvider，
+ * 直接使用传入的 SpanContext 进行注入。
+ *
+ * @param env 目标环境变量对象
+ * @param context 要注入的 SpanContext
+ * @returns 注入了 TRACEPARENT 的环境变量对象
+ *
+ * @example
+ * ```typescript
+ * const span = tracer.startSpan('my-span');
+ * const env = injectToEnvWithContext({}, span.spanContext);
+ * ```
+ */
+export declare function injectToEnvWithContext(env: EnvCarrier, context: SpanContext): EnvCarrier;
+/**
+ * 从源环境变量 carrier 复制 TRACEPARENT 到目标 carrier
+ *
+ * 用于将一个环境变量对象中的 trace context 传递到另一个：
+ * - 从 process.env 复制到子进程的环境变量
+ * - 从父进程环境变量复制到子进程环境变量
+ *
+ * @param target 目标 carrier（将被修改）
+ * @param source 源 carrier
+ * @returns 目标 carrier
+ *
+ * @example
+ * ```typescript
+ * // 在 fork 子进程时继承父进程的 trace context
+ * const childEnv = injectToEnvFromCarrier({}, process.env);
+ * ```
+ */
+export declare function injectToEnvFromCarrier(target: EnvCarrier, source: EnvCarrier): EnvCarrier;
+/**
+ * 获取 TRACEPARENT 字段名
+ */
+export declare function getTraceparentHeader(): string;
+export type { SpanContext } from "../types";