@ai-setting/roy-agent-core 1.0.0

package/src/env/llm/types.ts

@@ -0,0 +1,424 @@
+import { z } from "zod";
+
+// ============================================================================
+// Message Types
+// ============================================================================
+
+/**
+ * LLM Message
+ */
+export interface LLMMessage {
+  /** 消息角色 */
+  role: "system" | "user" | "assistant" | "tool";
+  /** 消息内容 */
+  content: string;
+  /** 工具调用（仅 assistant 角色） */
+  toolCalls?: ToolCall[];
+  /** 工具调用 ID（仅 tool 角色） */
+  toolCallId?: string;
+  /** 名称（用于 function 调用） */
+  name?: string;
+}
+
+/**
+ * Tool Call (OpenAI format)
+ */
+export interface ToolCall {
+  /** 工具调用 ID */
+  id: string;
+  /** 工具名称 */
+  name: string;
+  /** 工具参数（JSON 字符串） */
+  arguments: string;
+  /** OpenAI 格式的 function 对象 */
+  function?: {
+    /** 函数名称 */
+    name: string;
+    /** 函数参数（JSON 字符串） */
+    arguments: string;
+  };
+}
+
+/**
+ * Tool Result
+ */
+export interface ToolResult {
+  /** 对应的工具调用 ID */
+  toolCallId: string;
+  /** 工具执行结果 */
+  result: string;
+  /** 是否为错误 */
+  isError?: boolean;
+}
+
+// ============================================================================
+// Output Types
+// ============================================================================
+
+/**
+ * Usage Information
+ */
+export interface UsageInfo {
+  /** Prompt Token 数 */
+  promptTokens: number;
+  /** Completion Token 数 */
+  completionTokens: number;
+  /** 总 Token 数 */
+  totalTokens: number;
+}
+
+/**
+ * LLM Output
+ */
+export interface LLMOutput {
+  /** 生成的内容 */
+  content: string;
+  /** 推理/思考内容（支持 reasoning 模型的输出） */
+  reasoning?: string;
+  /** 完成原因 */
+  finishReason: "stop" | "length" | "content-filter" | "tool-calls" | "function-call";
+  /** 工具调用 */
+  toolCalls?: ToolCall[];
+  /** Usage 信息 */
+  usage?: UsageInfo;
+  /** 生成模型 */
+  model?: string;
+}
+
+// ============================================================================
+// Provider Types
+// ============================================================================
+
+/**
+ * Provider 类型
+ */
+export type ProviderType = "openai" | "anthropic" | "google" | "openai-compatible";
+
+/**
+ * Provider 能力配置
+ */
+export interface ProviderCapabilities {
+  /** 支持推理（CoT） */
+  reasoning?: boolean;
+  /** 支持工具调用 */
+  toolcall?: boolean;
+  /** 混合内容字段（用于解析推理内容） */
+  interleaved?: {
+    /** 字段名 */
+    field: string;
+  };
+  /** 文本内思考标签配置 */
+  thinkingInText?: {
+    /** 是否启用 */
+    enabled?: boolean;
+    /** 标签列表 */
+    tags?: string[];
+    /** 是否从输出中移除标签内容 */
+    removeFromOutput?: boolean;
+  };
+}
+
+/**
+ * 模型限制配置
+ */
+export interface ModelLimits {
+  /** 上下文窗口大小（Token 数） */
+  contextWindow: number;
+  /** 压缩阈值（0-1），超过此比例触发上下文压缩 */
+  compactionThreshold?: number;
+  /** 最大输出 Token 数 */
+  maxOutputTokens?: number;
+}
+
+/**
+ * Provider 配置
+ */
+export interface ProviderConfig {
+  /** Provider 类型 */
+  provider: ProviderType | string;
+  /** Provider 名称 */
+  name?: string;
+  /** Provider 描述 */
+  description?: string;
+  /** API Key */
+  apiKey: string;
+  /** Base URL（可选，用于代理或兼容 API） */
+  baseURL?: string;
+  /** 支持的模型列表 */
+  models?: string[];
+  /** Provider 默认模型 */
+  defaultModel?: string;
+  /** Provider 默认温度参数 */
+  temperature?: number;
+  /** Provider 默认最大 Token 数 */
+  maxTokens?: number;
+  /** Provider 能力配置 */
+  capabilities?: ProviderCapabilities;
+  /** 模型限制配置（按模型 ID 索引） */
+  limits?: Record<string, ModelLimits>;
+  /** Provider 特定选项（如 __dangerous__） */
+  providerOptions?: Record<string, unknown>;
+  /** 其他配置 */
+  options?: Record<string, unknown>;
+}
+
+/**
+ * LLM Provider 实例（由 AI SDK 创建）
+ */
+export interface LLMProvider {
+  /** Provider ID */
+  id: string;
+  /** Provider 实例 */
+  provider: unknown;
+  /** 支持的模型 */
+  models: string[];
+  /** Provider 配置 */
+  config?: ProviderConfig;
+}
+
+// ============================================================================
+// Config Types
+// ============================================================================
+
+/**
+ * 全局默认配置
+ */
+export interface LLMDefaultConfig {
+  /** 默认温度参数 */
+  temperature?: number;
+  /** 默认最大 Token 数 */
+  maxTokens?: number;
+}
+
+/**
+ * LLM Config
+ */
+export interface LLMConfig {
+  /** 全局默认配置 */
+  default?: LLMDefaultConfig;
+  /** 默认模型 */
+  defaultModel?: string;
+  /** Provider 配置映射 */
+  providers: Record<string, ProviderConfig>;
+  /** 默认 Provider */
+  defaultProvider: string;
+  /** 温度参数（全局覆盖） */
+  temperature?: number;
+  /** 最大 Token 数（全局覆盖） */
+  maxTokens?: number;
+  /** Top P（全局覆盖） */
+  topP?: number;
+  /** 是否流式输出 */
+  stream?: boolean;
+  /** 其他配置 */
+  options?: Record<string, unknown>;
+}
+
+// ============================================================================
+// Config Schema
+// ============================================================================
+
+/**
+ * ProviderCapabilities Zod Schema
+ */
+export const ProviderCapabilitiesSchema = z.object({
+  reasoning: z.boolean().optional(),
+  toolcall: z.boolean().optional(),
+  interleaved: z.object({
+    field: z.string(),
+  }).optional(),
+  thinkingInText: z.object({
+    enabled: z.boolean().optional(),
+    tags: z.array(z.string()).optional(),
+    removeFromOutput: z.boolean().optional(),
+  }).optional(),
+});
+
+/**
+ * ModelLimits Zod Schema
+ */
+export const ModelLimitsSchema = z.object({
+  contextWindow: z.number().int().positive(),
+  compactionThreshold: z.number().min(0).max(1).optional(),
+  maxOutputTokens: z.number().int().positive().optional(),
+});
+
+/**
+ * ProviderConfig Zod Schema
+ */
+export const ProviderConfigSchema = z.object({
+  provider: z.string(),
+  name: z.string().optional(),
+  description: z.string().optional(),
+  apiKey: z.string(),
+  baseURL: z.string().optional(),
+  models: z.array(z.string()).optional(),
+  defaultModel: z.string().optional(),
+  temperature: z.number().min(0).max(2).optional(),
+  maxTokens: z.number().int().positive().optional(),
+  capabilities: ProviderCapabilitiesSchema.optional(),
+  limits: z.record(z.string(), ModelLimitsSchema).optional(),
+  providerOptions: z.record(z.unknown()).optional(),
+  options: z.record(z.unknown()).optional(),
+});
+
+/**
+ * LLMDefaultConfig Zod Schema
+ */
+export const LLMDefaultConfigSchema = z.object({
+  temperature: z.number().min(0).max(2).optional(),
+  maxTokens: z.number().int().positive().optional(),
+});
+
+/**
+ * LLMConfig Zod Schema
+ */
+export const LLMConfigSchema = z.object({
+  default: LLMDefaultConfigSchema.optional(),
+  defaultModel: z.string().optional(),
+  providers: z.record(z.string(), ProviderConfigSchema),
+  defaultProvider: z.string(),
+  temperature: z.number().min(0).max(2).default(0.7),
+  maxTokens: z.number().int().positive().optional(),
+  topP: z.number().min(0).max(1).optional(),
+  stream: z.boolean().default(true),
+  options: z.record(z.unknown()).optional(),
+});
+
+// ============================================================================
+// Invoke Types
+// ============================================================================
+
+/**
+ * LLM Invoke 请求
+ */
+export interface LLMInvokeRequest {
+  /** 消息列表 */
+  messages: LLMMessage[];
+  /** Provider ID（可选，默认使用配置的默认 Provider） */
+  providerId?: string;
+  /** 模型（可选，默认使用配置的默认模型） */
+  model?: string;
+  /** 工具列表 */
+  tools?: ToolInfo[];
+  /** 温度参数 */
+  temperature?: number;
+  /** 最大 Token 数 */
+  maxTokens?: number;
+  /** Top P */
+  topP?: number;
+  /** 工具选择策略 */
+  toolChoice?: "auto" | "none" | { type: "function"; function: { name: string } };
+  /** 停止序列 */
+  stopSequences?: string[];
+  /** Abort Signal */
+  abortSignal?: AbortSignal;
+  /** 调用上下文（用于事件元数据） */
+  context?: LLMInvokeContext;
+  /** 跳过上下文阈值检查（用于 SummaryAgent 等内部调用，避免循环触发压缩） */
+  skipThresholdCheck?: boolean;
+}
+
+/**
+ * LLM Invoke 结果
+ */
+export interface LLMInvokeResult {
+  /** LLM 输出 */
+  output: LLMOutput;
+  /** 使用的 Provider ID */
+  providerId: string;
+  /** 使用的模型 */
+  model: string;
+  /** 调用延迟（毫秒） */
+  latencyMs: number;
+}
+
+// ============================================================================
+// Stream Types
+// ============================================================================
+
+/**
+ * Stream 事件类型
+ */
+export type StreamEventType =
+  | "start"
+  | "text"
+  | "reasoning"
+  | "tool-call"
+  | "tool-result"
+  | "finish"
+  | "error";
+
+/**
+ * Stream 事件
+ */
+export interface StreamEvent {
+  /** 事件类型 */
+  type: StreamEventType;
+  /** 文本内容（type=text 时） */
+  content?: string;
+  /** Delta 内容（type=text 时） */
+  delta?: string;
+  /** 推理内容（type=reasoning 时） */
+  reasoning?: string;
+  /** 工具调用（type=tool-call 时） */
+  toolCall?: {
+    id: string;
+    name: string;
+    arguments: string;
+  };
+  /** 工具结果（type=tool-result 时） */
+  toolResult?: {
+    id: string;
+    result: string;
+  };
+  /** 完成原因（type=finish 时） */
+  finishReason?: "stop" | "length" | "content-filter" | "tool-calls";
+  /** Usage 信息（type=finish 时） */
+  usage?: UsageInfo;
+  /** 错误信息（type=error 时） */
+  error?: string;
+}
+
+// ============================================================================
+// Tool Types
+// ============================================================================
+
+/**
+ * Tool Info（用于 LLM 工具调用）
+ */
+export interface ToolInfo {
+  /** 工具名称 */
+  name: string;
+  /** 工具描述 */
+  description?: string;
+  /** 工具参数 Schema */
+  parameters: Record<string, unknown>;
+}
+
+// ============================================================================
+// LLM Stream Event Types (for env.pushEnvEvent)
+// ============================================================================
+
+/**
+ * LLM 调用上下文（用于事件元数据）
+ */
+export interface LLMInvokeContext {
+  /** Session ID */
+  sessionId?: string;
+  /** Message ID */
+  messageId?: string;
+}
+
+/**
+ * LLM 流式事件类型（用于通过 env.pushEnvEvent 发布）
+ * 
+ * 这些事件会被包装成 EnvEvent 格式发布，事件类型为 `llm.${event.type}`
+ */
+export type LLMStreamEvent =
+  | { type: "start"; metadata: { model: string } }
+  | { type: "text"; content: string; delta: string }
+  | { type: "reasoning"; content: string }
+  | { type: "tool_call"; toolCall: { id: string; name: string; arguments: string } }
+  | { type: "completed"; content: string; metadata: { model: string; usage?: UsageInfo } }
+  | { type: "error"; error: string };

package/src/env/log-trace/decorator-otel.test.ts

@@ -0,0 +1,182 @@
+/**
+ * @fileoverview @Traced 装饰器 OTel 集成测试
+ * 
+ * 使用 OpenTelemetry 方式测试装饰器功能
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { Traced, TracedAs, TracedLightweight, wrapFunction } from "./decorator";
+import { getTracerProvider, resetTracerProvider, type OTelTracer } from "./opentelemetry/tracer-provider";
+import { join } from "path";
+
+describe("@Traced Decorator (OTel)", () => {
+  let tracer: OTelTracer;
+  let provider: ReturnType<typeof getTracerProvider>;
+
+  beforeEach(async () => {
+    resetTracerProvider();
+    provider = getTracerProvider();
+    await provider.initialize();
+    tracer = provider.getTracer('test-decorator');
+  });
+
+  afterEach(() => {
+    resetTracerProvider();
+  });
+
+  describe("wrapFunction - 非 async 函数", () => {
+    test("should wrap a sync function and create span", async () => {
+      const fn = (a: number, b: number) => a + b;
+      const wrapped = wrapFunction(fn, "add");
+      
+      const result = wrapped(1, 2);
+      
+      expect(result).toBe(3);
+      
+      // 验证函数正常工作，span 创建和结束都应该成功
+    });
+
+    test("should record sync function result", async () => {
+      const fn = () => ({ data: "test" });
+      const wrapped = wrapFunction(fn, "getData", { recordResult: true });
+      
+      const result = wrapped();
+      expect(result).toEqual({ data: "test" });
+    });
+
+    test("should record sync function error", async () => {
+      const fn = () => {
+        throw new Error("sync error");
+      };
+      const wrapped = wrapFunction(fn, "syncErrorFn", { recordError: true });
+      
+      expect(() => wrapped()).toThrow("sync error");
+    });
+
+    test("should support methods with parameters", async () => {
+      class TestService {
+        @TracedAs('method-with-params')
+        methodWithParams(a: number, b: string): string {
+          return `${a}-${b}`;
+        }
+      }
+
+      const service = new TestService();
+      const result = service.methodWithParams(1, 'test');
+
+      expect(result).toBe('1-test');
+    });
+
+    test("should support async methods", async () => {
+      class TestService {
+        @TracedAs('async-method')
+        async asyncMethod(): Promise<string> {
+          return 'async result';
+        }
+      }
+
+      const service = new TestService();
+      const result = await service.asyncMethod();
+
+      expect(result).toBe('async result');
+    });
+  });
+
+  describe("nesting", () => {
+    test("should maintain context across nested decorated methods", async () => {
+      // 装饰器内部使用 getTracerProvider().getTracer("decorator")
+      // 我们获取同一个 tracer 来检查上下文
+      const decoratorTracer = getTracerProvider().getTracer("decorator");
+      
+      class TestService {
+        @TracedAs('parent')
+        parent(): string {
+          return this.child();
+        }
+
+        @TracedAs('child')
+        child(): string {
+          return 'child result';
+        }
+      }
+
+      const service = new TestService();
+      const result = service.parent();
+
+      expect(result).toBe('child result');
+      
+      // 验证嵌套调用正常工作（函数返回正确结果）
+      // 上下文在 span.end() 后会被清除
+    });
+
+    test("should handle deeply nested decorated methods", async () => {
+      class TestService {
+        @TracedAs('level1')
+        level1(): string {
+          return this.level2();
+        }
+
+        @TracedAs('level2')
+        level2(): string {
+          return this.level3();
+        }
+
+        @TracedAs('level3')
+        level3(): string {
+          return 'deep result';
+        }
+      }
+
+      const service = new TestService();
+      const result = service.level1();
+
+      expect(result).toBe('deep result');
+    });
+  });
+
+  describe("span attributes", () => {
+    test("should record method args as params", async () => {
+      class TestService {
+        @TracedAs('with-args')
+        withArgs(a: number, b: string): string {
+          return `${a}-${b}`;
+        }
+      }
+
+      const service = new TestService();
+      const result = service.withArgs(42, 'hello');
+
+      expect(result).toBe('42-hello');
+    });
+
+    test("should maintain span tree in storage after nested calls", async () => {
+      // 捕获第一个 span 的 traceId
+      let capturedTraceId: string | undefined;
+      
+      class TestService {
+        @TracedAs('outer')
+        outer(): string {
+          // 捕获开始时的 traceId
+          const current = tracer.getCurrentContext();
+          if (current && !capturedTraceId) {
+            capturedTraceId = current.traceId;
+          }
+          return this.inner();
+        }
+
+        @TracedAs('inner')
+        inner(): string {
+          return 'inner';
+        }
+      }
+
+      const service = new TestService();
+      service.outer();
+
+      // 验证函数调用正常工作
+      // 注意：由于装饰器使用 getTracerProvider().getTracer("decorator")
+      // 而测试使用 getTracerProvider().getTracer('test-decorator')
+      // 可能不是同一个实例，但调用应该仍然正常工作
+    });
+  });
+});