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

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

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview W3C TraceContext Propagation
+ *
+ * 实现 W3C Trace Context 标准中的 traceparent 格式：
+ * https://www.w3.org/TR/trace-context/#traceparent-header
+ *
+ * 格式: 00-{traceId}-{parentSpanId}-{flags}
+ * - version: 2字符，固定 "00"
+ * - traceId: 32字符，128位追踪ID
+ * - parentSpanId: 16字符，64位父Span ID
+ * - flags: 2字符，采样标志（当前固定 "01"）
+ */
+import type { SpanContext } from "../types";
+/**
+ * 将 SpanContext 序列化为 traceparent 字符串
+ *
+ * W3C TraceContext 语义：
+ * - traceparent 中的 spanId 是"发送方 span"的 ID
+ * - 接收方会将其作为新 span 的 parentSpanId
+ * - 所以应该使用 context.spanId，而非 parentSpanId
+ *
+ * @param context SpanContext
+ * @returns traceparent 格式字符串
+ */
+export declare function serialize(context: SpanContext): string;
+/**
+ * 提取的 Trace Context
+ *
+ * W3C TraceContext 格式: 00-{traceId}-{spanId}-{flags}
+ * - {spanId} 是发送方 span 的 ID
+ * - 接收方应将其作为新 span 的 parentSpanId
+ */
+export interface ExtractedContext {
+    traceId: string;
+    /** 发送方 span 的 ID，接收方应作为新 span 的 parentSpanId */
+    spanId: string;
+}
+/**
+ * 将 traceparent 字符串反序列化为 ExtractedContext
+ *
+ * W3C TraceContext 语义：
+ * - traceparent 中的 "span-id" 是发送方 span 的 ID
+ * - 接收方应该：
+ *   - 使用提取的 traceId
+ *   - 将提取的 spanId 作为 parentSpanId
+ *   - 生成自己的新 spanId
+ *
+ * @param traceparent traceparent 格式字符串
+ * @returns 接收方 ExtractedContext 或 undefined（格式无效）
+ */
+export declare function parse(traceparent: string): ExtractedContext | undefined;
+/**
+ * W3C TraceContext Propagation 实现
+ *
+ * 用于在进程间传递 trace 上下文：
+ * - inject: 将 SpanContext 注入到 carrier（环境变量）
+ * - extract: 从 carrier（环境变量）提取 SpanContext
+ */
+export declare const propagation: {
+    /**
+     * 将 SpanContext 注入到 carrier
+     *
+     * @param carrier 载体对象（通常是环境变量对象）
+     * @param context Span 上下文
+     */
+    inject(carrier: Record<string, string | undefined>, context: SpanContext): void;
+    /**
+     * 从 carrier 提取 SpanContext
+     *
+     * @param carrier 载体对象（通常是环境变量对象）
+     * @returns ExtractedContext 或 undefined
+     */
+    extract(carrier: Record<string, string | undefined>): ExtractedContext | undefined;
+    /**
+     * 获取 traceparent 字段名
+     */
+    getTraceparentHeader(): string;
+};
+export type { SpanContext } from "../types";

package/dist/env/log-trace/opentelemetry/tracer-provider.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @fileoverview OpenTelemetry TracerProvider 实现
+ *
+ * 提供 OpenTelemetry 风格的追踪能力：
+ * - TracerProvider: 全局 Tracer 管理器
+ * - OTelTracer: 具体 Tracer 实现
+ * - OTelSpan: Span 实现
+ *
+ * 支持 W3C TraceContext 格式的跨进程上下文传递
+ */
+import type { SpanContext, SpanAttributes } from "../types";
+import { type SpanStorage } from "../span-storage";
+/**
+ * Span 选项
+ */
+export interface SpanOptions {
+    /** 父 Span 上下文（可选） */
+    parent?: SpanContext;
+    /** Span 属性 */
+    attributes?: SpanAttributes;
+    /** Span 类型 */
+    kind?: string;
+    /** 指定 traceId（可选，如果不提供则自动生成） */
+    traceId?: string;
+    /**
+     * 直接传入完整的 SpanContext（可选）
+     * 如果提供，将使用此 context 而忽略 parent 和 traceId 选项
+     * 用于从外部（如 ES 事件）注入已构建的 context
+     */
+    context?: SpanContext;
+}
+/**
+ * OTel Span 接口
+ */
+export interface OTelSpan {
+    readonly name: string;
+    readonly kind: string;
+    readonly spanContext: SpanContext;
+    readonly attributes: SpanAttributes;
+    startTime?: number;
+    endTime?: number;
+    error?: string;
+    setAttribute(key: string, value: unknown): void;
+    addEvent(name: string, attributes?: Record<string, unknown>): void;
+    end(result?: unknown, error?: Error): void;
+}
+/**
+ * 结束 span 并返回清理函数（用于恢复父上下文）
+ */
+export interface OTelSpanEndResult {
+    /** 结束后的父上下文 */
+    parentContext?: SpanContext;
+    /** traceId（用于显示） */
+    traceId: string;
+}
+/**
+ * OTel Span 接口扩展 - 提供 endSpan 方法
+ */
+export interface OTelSpanWithEndSpan extends OTelSpan {
+    /**
+     * 结束 span 并返回父上下文
+     * 用于结束根 span 后恢复之前的上下文
+     */
+    endSpan(): OTelSpanEndResult;
+}
+/**
+ * OTel Tracer 接口
+ */
+export interface OTelTracer {
+    readonly name: string;
+    readonly version?: string;
+    startSpan(name: string, options?: SpanOptions): OTelSpan;
+    /**
+     * 结束指定 span 并恢复父上下文
+     * @param span 要结束的 span
+     * @returns 结束后的父上下文（用于恢复之前的上下文）
+     */
+    endSpan(span: OTelSpan): SpanContext | undefined;
+    injectToEnv(env: Record<string, string | undefined>): void;
+    getCurrentContext(): SpanContext | undefined;
+    setCurrentContext(context: SpanContext | undefined): void;
+    /**
+     * 生成符合 OTel 格式的 traceId（32 字符 16 进制）
+     */
+    generateTraceId(): string;
+    /**
+     * 生成符合 OTel 格式的 spanId（16 字符 16 进制）
+     */
+    generateSpanId(): string;
+}
+/**
+ * OpenTelemetry TracerProvider
+ *
+ * 全局 Tracer 管理器，负责：
+ * - 维护 Tracer 缓存
+ * - 管理存储
+ * - 处理上下文初始化
+ * - 提供全局 context 供所有 tracer 共享
+ */
+export declare class OTelTracerProvider {
+    private tracers;
+    private storage;
+    private initialized;
+    private globalContext;
+    readonly instanceId: string;
+    constructor(storage?: SpanStorage, dbPath?: string);
+    /**
+     * 初始化 Provider
+     *
+     * 从环境变量恢复上下文（如 TRACEPARENT）
+     */
+    initialize(): Promise<void>;
+    /**
+     * 检查是否已初始化
+     */
+    isInitialized(): boolean;
+    /**
+     * 获取全局 context（所有 tracer 共享）
+     */
+    getGlobalContext(): SpanContext | undefined;
+    /**
+     * 设置全局 context（所有 tracer 共享）
+     */
+    setGlobalContext(context: SpanContext | undefined): void;
+    /**
+     * 获取 Tracer
+     */
+    getTracer(name: string, version?: string): OTelTracer;
+    /**
+     * 从环境变量恢复上下文
+     */
+    private restoreFromEnv;
+    /**
+     * 关闭 Provider
+     */
+    shutdown(): void;
+    /**
+     * 获取存储
+     */
+    getStorage(): SpanStorage;
+}
+/**
+ * 获取 TracerProvider 单例
+ */
+export declare function getTracerProvider(): OTelTracerProvider;
+/**
+ * 重置 TracerProvider（用于测试）
+ */
+export declare function resetTracerProvider(): void;
+/**
+ * 设置 TracerProvider 单例（用于测试中注入自定义 storage）
+ *
+ * Task #2580 (round 3) — 测试需要为 @TracedAs / wrapFunction 装饰的
+ * 函数提供一个带 SQLite 存储的 TracerProvider，以验证 span 名称
+ * 和 attributes。
+ */
+export declare function setTracerProvider(provider: OTelTracerProvider): void;

package/dist/env/log-trace/span-storage.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview Span Storage 实现
+ *
+ * 提供 SQLiteSpanStorage 一种实现，用于持久化存储 span 数据
+ */
+import { type Span, type SpanStorage, type TraceInfo } from "./types";
+export type { SpanStorage, TraceInfo } from "./types";
+/**
+ * SQLite 存储实现
+ *
+ * 根据运行时环境使用 bun:sqlite 或 better-sqlite3
+ *
+ * 注意：此实现仅支持 SQLite 文件存储，不支持 :memory: 模式
+ * WAL 模式默认启用以支持跨进程并发访问
+ */
+export declare class SQLiteSpanStorage implements SpanStorage {
+    private db;
+    private dbPath;
+    private initialized;
+    /**
+     * 创建 SQLiteSpanStorage 实例
+     *
+     * @param dbPath SQLite 数据库文件路径（必填）
+     * @throws Error 如果 dbPath 为空或为 :memory:
+     */
+    constructor(dbPath: string);
+    initialize(): Promise<void>;
+    save(span: Span): void;
+    saveBatch(spans: Span[]): void;
+    findByTraceId(traceId: string): Span[];
+    findBySpanId(spanId: string): Span | undefined;
+    listTraces(limit?: number): TraceInfo[];
+    deleteByTraceId(traceId: string): void;
+    close(): void;
+    private rowToSpan;
+    private buildTree;
+}

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

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Trace Context 实现
+ *
+ * 基于 AsyncLocalStorage 的轻量级追踪上下文实现
+ */
+import { AsyncLocalStorage } from "async_hooks";
+import { type SpanContext, type ITraceContext, type TraceContextOptions } from "./types";
+interface RequestContextData {
+    requestId: string;
+    sessionId?: string;
+    timestamp: number;
+    spanContext?: SpanContext;
+}
+declare const contextStore: AsyncLocalStorage<RequestContextData>;
+export { contextStore };
+/**
+ * 获取当前 TraceContext 实例
+ */
+export declare function getTraceContext(): ITraceContext;
+/**
+ * 设置 TraceContext 实现（用于测试或替换）
+ */
+export declare function setTraceContext(impl: ITraceContext): void;
+/**
+ * 初始化 TraceContext
+ */
+export declare function initTraceContext(options?: TraceContextOptions): ITraceContext;
+export type { ITraceContext, TraceContextOptions } from "./types";

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

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview Log & Trace Component 类型定义
+ */
+/**
+ * Span 上下文
+ */
+export interface SpanContext {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+}
+/**
+ * Span 属性
+ */
+export interface SpanAttributes {
+    [key: string]: string | number | boolean | undefined | Record<string, unknown>;
+}
+/**
+ * Span
+ */
+export interface Span {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: SpanKind;
+    status: SpanStatus;
+    startTime: number;
+    endTime?: number;
+    attributes: SpanAttributes;
+    result?: unknown;
+    error?: string;
+    children?: Span[];
+}
+/**
+ * Span 类型
+ */
+export declare enum SpanKind {
+    CLIENT = "client",
+    SERVER = "server",
+    INTERNAL = "internal"
+}
+/**
+ * Span 状态
+ */
+export declare enum SpanStatus {
+    OK = "ok",
+    ERROR = "error"
+}
+/**
+ * Trace 信息
+ */
+export interface TraceInfo {
+    traceId: string;
+    rootSpanName: string;
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+    spanCount: number;
+    status: "ok" | "error" | "mixed";
+}
+/**
+ * SpanStorage 接口
+ */
+export interface SpanStorage {
+    initialize(): Promise<void>;
+    save(span: Span): void;
+    saveBatch(spans: Span[]): void;
+    findByTraceId(traceId: string): Span[];
+    findBySpanId(spanId: string): Span | undefined;
+    listTraces(limit?: number): TraceInfo[];
+    deleteByTraceId(traceId: string): void;
+    close(): void;
+}
+/**
+ * TraceContext 选项
+ */
+export interface TraceContextOptions {
+    /** 追踪器实现类型 */
+    impl?: "lightweight" | "opentelemetry";
+}
+/**
+ * ITraceContext 接口
+ */
+export interface ITraceContext {
+    /** 获取当前请求的 requestId */
+    getRequestId(): string | undefined;
+    /** 获取当前 Span 上下文 */
+    getSpanContext(): SpanContext | undefined;
+    /** 更新当前 Span 上下文（用于设置子 span 的 parentSpanId） */
+    setSpanContext(spanContext: SpanContext): void;
+    /** 在已存在的追踪上下文中执行函数 */
+    runWithContext<T>(fn: () => T): T;
+    /** 在新追踪上下文中执行函数（同步） */
+    runWithNewContext<T>(requestId: string, sessionId: string | undefined, fn: () => T): T;
+    /** 在已存在的追踪上下文中执行异步函数 */
+    runWithContextAsync<T>(fn: () => Promise<T>): Promise<T>;
+    /** 在新追踪上下文中执行函数（异步） */
+    runWithNewContextAsync<T>(requestId: string, sessionId: string | undefined, fn: () => Promise<T>): Promise<T>;
+    /** 生成新的 requestId */
+    generateRequestId(): string;
+    /** 初始化追踪上下文（请求入口调用） */
+    initContext(requestId: string, sessionId?: string): void;
+    /** 创建并进入新的追踪上下文（请求入口使用，返回清理函数） */
+    startNewContext(requestId: string, sessionId?: string): () => void;
+}
+/**
+ * 日志级别
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Logger 配置
+ */
+export interface LoggerConfig {
+    level?: LogLevel;
+    prefix?: string;
+    filename?: string;
+}
+/**
+ * Logger 接口
+ */
+export interface ILogger {
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+}

package/dist/env/mcp/command-resolver.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Resolve MCP local commands and sanitize npm/npx runtime env.
+ */
+/**
+ * Prefer a locally installed binary over npx/npm exec when available.
+ */
+export declare function resolvePackageRunnerCommand(command: string[], serverDir: string): string[];
+/**
+ * When npm prefix is broken (common in Cursor remote), point npm/npx
+ * at a writable fallback prefix to avoid ENOENT stderr spam.
+ */
+export declare function augmentNpmEnvForPackageRunner(command: string[], env: Record<string, string>): Record<string, string>;

package/dist/env/mcp/config.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @fileoverview MCP Component 配置
+ */
+import { z } from "zod";
+import type { ConfigComponent } from "../../config/config-component";
+/**
+ * MCP 路径配置
+ */
+export interface McpPath {
+    /** 来源类型 */
+    type: "user" | "project" | "custom";
+    /** 路径 */
+    path: string;
+}
+/**
+ * McpPath Schema
+ */
+export declare const McpPathSchema: z.ZodObject<{
+    type: z.ZodEnum<["user", "project", "custom"]>;
+    path: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    type: "custom" | "project" | "user";
+}, {
+    path: string;
+    type: "custom" | "project" | "user";
+}>;
+/**
+ * McpComponent 配置
+ */
+export interface McpComponentConfig {
+    /** 扫描路径列表 */
+    mcpPaths: McpPath[];
+    /** 显式配置的服务器 */
+    servers?: Record<string, z.infer<typeof import("./types.js").McpServerConfigSchema>>;
+    /** 默认超时（毫秒） */
+    timeout?: number;
+    /** 是否启用 */
+    enabled?: boolean;
+}
+/**
+ * McpComponent 配置 Schema
+ */
+export declare const McpComponentConfigSchema: z.ZodObject<{
+    mcpPaths: z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<["user", "project", "custom"]>;
+        path: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        type: "custom" | "project" | "user";
+    }, {
+        path: string;
+        type: "custom" | "project" | "user";
+    }>, "many">;
+    servers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    mcpPaths: {
+        path: string;
+        type: "custom" | "project" | "user";
+    }[];
+    enabled?: boolean | undefined;
+    timeout?: number | undefined;
+    servers?: Record<string, any> | undefined;
+}, {
+    mcpPaths: {
+        path: string;
+        type: "custom" | "project" | "user";
+    }[];
+    enabled?: boolean | undefined;
+    timeout?: number | undefined;
+    servers?: Record<string, any> | undefined;
+}>;
+/**
+ * McpComponentOptions（通过 options 传递）
+ */
+export interface McpComponentOptions {
+    /** ConfigComponent 实例（必填） */
+    configComponent: ConfigComponent;
+    /** 配置文件相对路径 */
+    configPath?: string;
+    /** 环境变量前缀 */
+    envPrefix?: string;
+    /** 直接传入的配置对象（最高优先级） */
+    config?: Partial<McpComponentConfig>;
+}
+/**
+ * 默认 MCP 配置
+ */
+export declare const DEFAULT_MCP_CONFIG: McpComponentConfig;
+/**
+ * 配置 Key 列表（用于 ConfigComponent 注册）
+ */
+export declare const MCP_CONFIG_KEYS: readonly ["mcp.enabled", "mcp.timeout", "mcp.mcpPaths", "mcp.servers"];
+/**
+ * 路径类型优先级
+ */
+export declare const MCP_PATH_PRIORITY: Record<string, number>;
+/**
+ * 获取路径优先级
+ */
+export declare function getMcpPathPriority(type: string): number;

package/dist/env/mcp/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview MCP Component 导出
+ */
+export type { McpServerConfig, McpServerLocalConfig, McpServerRemoteConfig, DiscoveredMcpServer, McpServerStatus, } from "./types";
+export { McpServerConfigSchema, McpServerLocalConfigSchema, McpServerRemoteConfigSchema, } from "./types";
+export { DEFAULT_MCP_CONFIG, MCP_CONFIG_KEYS, getMcpPathPriority, } from "./config";
+export type { McpComponentConfig, McpComponentOptions, McpPath, } from "./config";
+export { McpComponent } from "./mcp-component";
+export { McpScanner } from "./scanner";
+export { McpLoader, type McpClientEntry } from "./loader";
+export { resolveNpmPrefix, resolveGlobalNodeModulesPath, resolveGlobalBinPath, ensureFallbackNpmPrefix, isUsableNpmPrefix, } from "./npm-prefix";
+export { resolvePackageRunnerCommand, augmentNpmEnvForPackageRunner, } from "./command-resolver";
+export { adaptMcpTool, createMcpToolsDescription, convertInputSchemaToZod } from "./tool/adapter";

package/dist/env/mcp/loader.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview MCP 服务器加载器
+ *
+ * 负责连接和管理 MCP 客户端
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { McpServerConfig, DiscoveredMcpServer } from "./types";
+/**
+ * MCP 客户端条目
+ */
+export interface McpClientEntry {
+    name: string;
+    client: Client;
+    transport: StdioClientTransport | StreamableHTTPClientTransport;
+    config: McpServerConfig;
+}
+/**
+ * MCP 服务器加载器
+ *
+ * 负责：
+ * 1. 构建默认配置
+ * 2. 合并显式配置
+ * 3. 连接/断开 MCP 服务器
+ */
+export declare class McpLoader {
+    private clients;
+    private defaultTimeout;
+    constructor(defaultTimeout?: number);
+    /**
+     * 构建默认配置（从扫描结果）
+     *
+     * @param server - 扫描发现的 MCP 服务器信息
+     * @returns MCP 服务器配置
+     */
+    buildDefaultConfig(server: DiscoveredMcpServer): McpServerConfig;
+    /**
+     * 合并配置（显式配置覆盖默认配置）
+     */
+    mergeConfig(defaultConfig: McpServerConfig, explicitConfig?: Partial<McpServerConfig>): McpServerConfig;
+    /**
+     * 连接到 MCP 服务器
+     */
+    connect(name: string, config: McpServerConfig): Promise<McpClientEntry>;
+    /**
+     * 断开连接
+     */
+    disconnect(name: string): Promise<void>;
+    private attachStderrDrain;
+    private closeTransport;
+    /**
+     * 断开所有连接
+     */
+    disconnectAll(): Promise<void>;
+    /**
+     * 获取客户端
+     */
+    getClient(name: string): McpClientEntry | undefined;
+    /**
+     * 获取所有客户端
+     */
+    getAllClients(): Map<string, McpClientEntry>;
+    /**
+     * 检查是否已连接
+     */
+    isConnected(name: string): boolean;
+    /**
+     * 从 auth.json 加载 minimax API key
+     */
+    loadMinimaxApiKey(): Promise<string | undefined>;
+    /**
+     * 注入 minimax 环境变量到 env 对象
+     *
+     * 如果已存在 MINIMAX_API_KEY，不会覆盖
+     */
+    injectMinimaxEnv(env: Record<string, string>): Promise<void>;
+}

package/dist/env/mcp/mcp-component.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview MCP Component 主组件
+ *
+ * MCP 客户端管理组件
+ */
+import { BaseComponent, type ComponentConfig } from "../component";
+import type { McpServerStatus } from "./types";
+import type { ToolInfo } from "../tool/types";
+/**
+ * McpComponent
+ *
+ * MCP 客户端管理组件
+ *
+ * 功能：
+ * 1. 配置管理（支持 file/env/object 三层配置）
+ * 2. 扫描 MCP 服务器
+ * 3. 连接/断开 MCP 服务器
+ * 4. 注册 MCP tools 到 ToolComponent
+ */
+export declare class McpComponent extends BaseComponent {
+    readonly name = "mcp";
+    readonly version = "1.0.0";
+    private config;
+    private toolComponent?;
+    private configComponent?;
+    private scanner?;
+    private loader?;
+    private serverStatus;
+    private registeredTools;
+    constructor();
+    init(config?: ComponentConfig): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private registerConfig;
+    private flattenConfig;
+    private loadServers;
+    private registerServerTools;
+    /**
+     * 获取服务器状态
+     */
+    getServerStatus(name: string): McpServerStatus | undefined;
+    /**
+     * 列出所有服务器
+     */
+    listServers(): McpServerStatus[];
+    /**
+     * 列出所有 MCP 工具
+     */
+    listTools(): ToolInfo[];
+    /**
+     * 重新加载所有服务器
+     */
+    reload(): Promise<void>;
+}